""" 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 from agent_id for ACP upstream routing. """ import os from logging import Logger from pathlib import Path from typing import Any from coolname import generate_slug from crow_cli.agent.memory import DEFAULT_MEMORY_PATH, MemoryClient, MemoryServiceError from crow_cli.memory import build_agent_id from 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, )