Something went wrong. Try again.
MCP based ACP agent
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624"""Agent session management - persistence layer for conversation state.
One row = One message. No conv_index gymnastics. No reconstruction headaches.Just serialize the message dict, deserialize it back.
Agent owns the session. agent_id = "{session_id}-{agent_idx}-{fork_idx}"is the PK (schema v5; trunk carries fork_idx=1). session_id is derived fromagent_id for ACP upstream routing."""
import osfrom logging import Loggerfrom pathlib import Pathfrom typing import Any
from coolname import generate_slug
from crow_cli.agent.memory import DEFAULT_MEMORY_PATH, MemoryClient, MemoryServiceErrorfrom crow_cli.memory import build_agent_idfrom crow_cli.agent.prompt import ( SystemPromptResponse, default_system_prompt, render_template,)
from crow_cli.config import ( Config,)
async def get_session_by_cwd( cwd, memory_path=DEFAULT_MEMORY_PATH, limit: int = 50, offset: int = 0): """ Lookup sessions by working directory via the memory db, most recently active first, one page at a time.
One row per session: a session can hold several trunk agents (agent_idx 1..N via delegation) and forks, all carrying the same workspace, so we group by session_id and keep the trunk with the largest agent_idx (the most recent agent) as the representative. Recency comes from the aggregate last-message timestamp; the expensive per-session title query only runs for the requested page.
Returns a tuple of (page of session info dicts, next offset or None). """ client = MemoryClient(memory_path) try: representatives: dict[str, object] = {} roots: dict[str, object] = {} for agent in await client.list_agents(): prompt_args = agent.prompt_args or {} if prompt_args.get("workspace") != cwd or agent.fork_idx != 1: continue current = representatives.get(agent.session_id) if current is None or agent.agent_idx > current.agent_idx: representatives[agent.session_id] = agent if agent.agent_idx == 1: roots[agent.session_id] = agent
# True recency: last message activity per session (single aggregate). activity = { s.session_id: s.last_activity for s in await client.list_sessions(limit=1_000_000) } ordered = sorted( representatives.items(), key=lambda item: activity.get(item[0]) or item[1].created_at, reverse=True, )
page = ordered[offset : offset + limit] next_offset = offset + limit if offset + limit < len(ordered) else None
result = [] for session_id, agent in page: # Title from the root agent's second message (index 1, after the # system message). Fetch the first three records so len > 2 tells # us a title exists. title = "Untitled Chat" title_agent = roots.get(session_id, agent) recs = await client.query_messages( agent_id=title_agent.agent_id, order="asc", limit=3 ) if len(recs) > 2: try: content = recs[1].data.get("content", "") if isinstance(content, list): title = "".join( b.get("text", "") for b in content if b.get("type") == "text" )[:50] else: title = str(content)[:50] if not title: title = "Untitled Chat" except (AttributeError, TypeError): title = "Untitled Chat"
result.append( { "cwd": cwd, "session_id": session_id, "title": title, "updated_at": activity.get(session_id) or agent.created_at, } ) return result, next_offset finally: await client.close()
def get_coolname() -> str: """Generate a memorable slug""" return generate_slug(4)
def snap_turn_cut(messages: list[dict], turn_idx: int | None) -> int | None: """Compute the fork cut point for a turn anchor.
``turn_idx`` is the 0-based turn (user message) within the agent's message list, in the sense "include through the END of this turn". Cut points land on user-message boundaries, so an assistant tool_calls group is never split from its tool results. Returns the number of messages to keep; None keeps everything (fork at HEAD). """ if turn_idx is None: return None user_idxs = [i for i, m in enumerate(messages) if m.get("role") == "user"] if not user_idxs: return None turn_idx = max(turn_idx, 0) if turn_idx + 1 >= len(user_idxs): return None # last turn (or beyond) -> HEAD return user_idxs[turn_idx + 1]
def snap_offset_cut( messages: list[dict], offset: int, delegation_ids: set[str] | None = None,) -> int: """Compute the fork cut point for a message offset.
``offset`` is how many messages back from HEAD to fork: 0 keeps everything, N drops the last N. Unlike :func:`snap_turn_cut` this is message-granular — a turn boundary is too coarse when the point is to step back over ONE call.
The raw cut is then SNAPPED back past anything that must not end a fork's history:
* an assistant message carrying ``tool_calls``. Its results follow it, so they are on the far side of the cut and the group is left dangling — and a dangling group is not merely ugly, it is rejected: every tool_call_id in an assistant message must be followed by a tool message answering it. * a tool result answering one of ``delegation_ids``. A fork whose history ENDS in "I delegated this and here is what came back" is a fork that delegates instead of answering — the infinity mirror. The snap then takes the assistant message above it on the next pass, so the whole delegation group goes.
A delegation deeper in the kept prefix is NOT removed — that would mean either rewriting rows a fork shares with its trunk or discarding everything since the first one. See EXECUTE_TODO 10e(i).
Returns the number of messages to keep. 0 means nothing survives, which is not a fork but a new session; callers raise. """ ids = delegation_ids or set() cut = max(len(messages) - max(offset, 0), 0) while cut > 0: msg = messages[cut - 1] role = msg.get("role") if role == "assistant" and msg.get("tool_calls"): cut -= 1 elif role == "tool" and msg.get("tool_call_id") in ids: cut -= 1 else: break return cut
async def lookup_or_create_prompt( template: str, name: str, memory_path: str = DEFAULT_MEMORY_PATH,) -> str: """ Lookup existing prompt by template content, or create new one if not found. """ client = MemoryClient(memory_path) try: return await client.lookup_or_create_prompt(template, name) finally: await client.close()
class AgentSession: """ Manages conversation state and persistence via an in-process sqlite db.
agent_id = "{session_id}-{agent_idx}-{fork_idx}" is the key. session_id is derived for ACP upstream routing only. """
def __init__( self, agent_id: str, session_id: str, agent_idx: int = 0, memory_path: str = DEFAULT_MEMORY_PATH, cwd: str = "/tmp", fork_idx: int = 1, forked_at: str | None = None, ): self.agent_id = agent_id self.session_id = session_id self.agent_idx = agent_idx self.fork_idx = fork_idx self.forked_at = forked_at self.memory_path = memory_path # ACP paths are absolute by contract; a relative cwd (e.g. a client's # bare ".") would resolve against whatever process consumes it next — # the MCP server's — instead of this session's directory. self.cwd = os.path.abspath(cwd) self.messages: list[dict] = [] self._client = None self.model_identifier = None self.prompt_args: dict[str, Any] | None = None
@property def rlm_depth(self) -> int: """How many delegations deep this session is: 0 for a trunk, N for a delegate N forks down.
Persisted inside prompt_args rather than in a column of its own because prompt_args is JSON, is copied by :meth:`fork`, and create_database is create_all — additive TABLES, no ALTER, so a new column means a migration against the live db (EXECUTE_TODO 10/AG). Jinja2 ignores template variables the template does not use, so the extra key costs nothing at render time.
It rides the wire as session/fork's ``_meta`` rlmDepth and lands here, which is what makes it survive a load in a DIFFERENT process — a budget held in memory would reset the moment a delegate was re-prompted, and a delegate that forgets its depth is the mirror again. """ depth = (self.prompt_args or {}).get("rlm_depth", 0) return depth if isinstance(depth, int) and depth > 0 else 0
@property def client(self) -> MemoryClient: """Lazy-load the memory client.""" if self._client is None: self._client = MemoryClient(self.memory_path) return self._client
async def add_message(self, msg: dict, usage: dict | None = None): """ Add message to in-memory list AND persist to the service.
Args: msg: Full message dict (role, content, tool_calls, etc.) usage: Token usage dict with prompt_tokens, completion_tokens, total_tokens """ self.messages.append(msg) await self.client.add_message(self.agent_id, msg, usage)
async def add_tool_response( self, tool_results: list[dict], logger: Logger, ): for tool_result in tool_results: logger.info(f"TOOL RESULT: {tool_result}") await self.add_message(tool_result)
async def add_assistant_response( self, thinking: list[str], content: list[str], tool_call_inputs: list[dict], logger: Logger, usage: dict | None = None, ): """ Handle complex react message building + tool calls + results.
Args: thinking: List of thinking tokens content: List of content tokens tool_call_inputs: Tool calls from assistant logger: Logger instance usage: Token usage dict with prompt_tokens, completion_tokens, total_tokens """ # Build react message if len(content) > 0 or len(tool_call_inputs) > 0 or len(thinking) > 0: thinking_text = "".join(thinking) if thinking else "" content_text = "".join(content) if content else "" msg = {"role": "assistant", "content": content_text} if thinking_text and thinking_text != "": msg["reasoning_content"] = thinking_text if tool_call_inputs: msg["tool_calls"] = tool_call_inputs
logger.info(f"Adding message: {msg}") logger.info(f"Message usage: {usage}") # Add to database/list await self.add_message(msg, usage)
async def _save_messages(self, messages: list[dict]): """Batch save messages to the service.""" await self.client.save_messages(self.agent_id, messages)
@classmethod async def create( cls, prompt_id: str, prompt_args: dict[str, Any], tool_definitions: list[dict], request_params: dict[str, Any], model_identifier: str, memory_path: str = DEFAULT_MEMORY_PATH, cwd: str = "/tmp", agent_idx: int = 1, fork_idx: int = 1, forked_at: str | None = None, session_id: str | None = None, initial_messages: list[dict[str, Any]] | None = None, ) -> "AgentSession": """Factory method to create a new agent session.""" cwd = os.path.abspath(cwd) client = MemoryClient(memory_path)
# Load and render prompt try: prompt = await client.get_prompt(prompt_id) except MemoryServiceError as e: if e.status == 404: raise ValueError(f"Prompt '{prompt_id}' not found") from e raise
system_prompt = render_template(prompt.template, **prompt_args) if session_id is None: session_id = get_coolname() agent_id = build_agent_id(session_id, agent_idx, fork_idx)
# Create agent record await client.create_agent( agent_id=agent_id, session_id=session_id, agent_idx=agent_idx, fork_idx=fork_idx, forked_at=forked_at, cwd=cwd, prompt_id=prompt_id, prompt_args=prompt_args, system_prompt=system_prompt, tool_definitions=tool_definitions, request_params=request_params, model_identifier=model_identifier, ) await client.close()
# Build session instance session = cls( agent_id, session_id, agent_idx, memory_path, cwd=cwd, fork_idx=fork_idx, forked_at=forked_at, ) session.model_identifier = model_identifier session.tools = tool_definitions session.request_params = request_params session.prompt_id = prompt_id session.prompt_args = prompt_args
# Start with system message session.messages = [{"role": "system", "content": system_prompt}] await session._save_messages(session.messages)
# Add initial messages if provided if initial_messages: for msg in initial_messages: if msg.get("role") != "system": # Skip system messages await session.add_message(msg)
return session
@classmethod async def get_max_agent_idx( cls, session_id: str, memory_path: str = DEFAULT_MEMORY_PATH, fork_idx: int | None = 1, ) -> int: """Return the highest agent_idx for a given session_id.
fork_idx=1 (default) follows the trunk; None scans all forks. """ client = MemoryClient(memory_path) try: return await client.get_max_agent_idx(session_id, fork_idx=fork_idx) finally: await client.close()
@classmethod async def list_sessions( cls, limit: int = 50, offset: int = 0, memory_path: str = DEFAULT_MEMORY_PATH, include_forks: bool = False, ) -> list[dict]: """List sessions ordered by most-recent message activity (desc).
include_forks=False (default) hides the fork dimension: trunk agents and their messages only. """ client = MemoryClient(memory_path) try: return await client.list_sessions( limit=limit, offset=offset, include_forks=include_forks ) finally: await client.close()
@classmethod async def load( cls, agent_id: str, memory_path: str = DEFAULT_MEMORY_PATH, ) -> "AgentSession": """Factory method to load existing agent session from the service.""" client = MemoryClient(memory_path) try: agent, messages = await client.load(agent_id, hydrate=True) except MemoryServiceError as e: if e.status == 404: raise ValueError(f"Agent '{agent_id}' not found") from e raise finally: await client.close()
session = cls( agent_id=agent.agent_id, session_id=agent.session_id, agent_idx=agent.agent_idx, memory_path=memory_path, cwd=agent.cwd, fork_idx=agent.fork_idx, forked_at=agent.forked_at, ) session.model_identifier = agent.model_identifier session.tools = agent.tool_definitions session.request_params = agent.request_params session.prompt_id = agent.prompt_id session.prompt_args = agent.prompt_args session.messages = messages
return session
@classmethod async def fork( cls, session_id: str, memory_path: str = DEFAULT_MEMORY_PATH, cwd: str = "/tmp", agent_idx: int | None = None, turn_idx: int | None = None, message_offset: int | None = None, delegation_ids: set[str] | None = None, rlm_depth: int | None = None, ) -> "AgentSession": """Fork a TRUNK agent of the session (default: HEAD = max agent_idx).
The fork shares (session_id, agent_idx) with its source and gets the next fork_idx. Its context is the trunk's prefix rows up to the anchor (stored as forked_at, a message-id POSITION) — shared rows, never copied. The fork inherits the source's prompt, tools, request params and model.
Two policies pick the anchor, and they are mutually exclusive: ``turn_idx`` counts whole turns and cuts on user-message boundaries (:func:`snap_turn_cut`); ``message_offset`` counts single messages back from HEAD and then snaps off anything that must not end a fork's history (:func:`snap_offset_cut`). Only the offset path snaps, so a turn fork — the CLI's ``--fork``, an interrogation fork — keeps exactly the behaviour it has always had.
``delegation_ids`` are the LLM tool-call ids of delegations the source already made (see :func:`crow_cli.memory.delegation_tool_call_ids`); the offset snap steps over a trailing one so the fork's history does not end in "I delegated this".
``rlm_depth`` marks the fork as a delegate that many levels down. It is persisted in prompt_args, so it survives a load in a different process; None means "not a delegation fork" and leaves the source's args exactly as they were. """ if turn_idx is not None and message_offset is not None: raise ValueError("fork on turn_idx OR message_offset, not both") client = MemoryClient(memory_path) try: if agent_idx is None: agent_idx = await client.get_max_agent_idx(session_id) source_id = build_agent_id(session_id, agent_idx, 1) source, _ = await client.load(source_id) records = await client.query_messages(agent_id=source_id) if not records: raise ValueError(f"source agent '{source_id}' has no messages to fork") messages = [r.data for r in records] if message_offset is not None: cut = snap_offset_cut(messages, message_offset, delegation_ids) # cut == 0 used to fall through to records[cut - 1] == # records[-1], i.e. "keep nothing" silently became "fork at # HEAD" — the one outcome the offset exists to prevent. if cut == 0: raise ValueError( f"forking '{source_id}' {message_offset} messages back leaves " "no history to fork: everything at the tail is part of the " "group being stepped over" ) else: cut = snap_turn_cut(messages, turn_idx) anchor = records[-1].id if cut is None else records[cut - 1].id fork_idx = await client.get_max_fork_idx(session_id, agent_idx) + 1 fork_id = build_agent_id(session_id, agent_idx, fork_idx) # The depth rides prompt_args so it is durable and survives a # load in another process; None means "not a delegation fork" # and leaves the source's args exactly as they were. prompt_args = source.prompt_args if rlm_depth is not None: prompt_args = {**(prompt_args or {}), "rlm_depth": rlm_depth} await client.create_agent( agent_id=fork_id, session_id=session_id, agent_idx=agent_idx, fork_idx=fork_idx, forked_at=str(anchor), cwd=cwd, prompt_id=source.prompt_id, prompt_args=prompt_args, system_prompt=source.system_prompt, tool_definitions=source.tool_definitions, request_params=source.request_params, model_identifier=source.model_identifier, ) finally: await client.close()
# Reload through the normal path so the fork's message view (trunk # prefix + its own rows) is assembled and hydrated. return await cls.load(fork_id, memory_path=memory_path)
async def close(self): """Close the HTTP client.""" if self._client is not None: await self._client.close() self._client = None
async def make_agent_session( config: Config, tools: list[dict], model_id: str, cwd: str, session_id: str | None = None, agent_idx: int | None = None, fork_idx: int = 1, forked_at: str | None = None, template: str | None = None, template_args: dict[str, Any] | None = None,): """Mint an agent row and its session, rendering its system prompt.
``template`` / ``template_args`` are the system-prompt seam. Pass neither and the prompt comes from :func:`default_system_prompt` — crow's template with args assembled from ``cwd``, which is what ``session/new`` wants. Pass both and the row is created with exactly that prompt, which is what compaction does: its callable decides what the NEXT generation's system prompt is, and this is where that decision lands.
The seam sits here rather than in :meth:`AgentSession.create` because ``create`` speaks in ``prompt_id`` — an already-persisted template row. A caller with a prompt of its own should not have to know about the ``prompts`` table. """ cwd = os.path.abspath(cwd) if session_id is None: session_id = get_coolname() if agent_idx is None: agent_idx = 1 if template is None: system_prompt = default_system_prompt(config, cwd, session_id) else: system_prompt = SystemPromptResponse( template=template, template_args=template_args or {} ) prompt_id = await lookup_or_create_prompt( system_prompt.template, name="crow-default", memory_path=config.db_uri ) return await AgentSession.create( prompt_id=prompt_id, prompt_args=system_prompt.template_args, tool_definitions=tools, request_params={"temperature": 0.2}, model_identifier=model_id, memory_path=config.db_uri, cwd=cwd, agent_idx=agent_idx, fork_idx=fork_idx, forked_at=forked_at, session_id=session_id, )