Something went wrong. Try again.
MCP based ACP agent
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543"""Read path: agents, prompts, messages, sessions, keyword search."""
from sqlalchemy import funcfrom sqlalchemy.orm import Session
from . import ftsfrom .ids import build_agent_id, parse_agent_idfrom .image_store import ImageStorefrom .messages import hydrate_messagefrom .models import ( GOAL_ACTIVE, Agent, Goal, Message, Prompt, SubtoolCall, Task, TaskDelivery,)
def get_agent(engine, agent_id: str) -> Agent | None: with Session(engine) as db: return db.query(Agent).filter_by(agent_id=agent_id).first()
def list_agents(engine, session_id: str | None = None) -> list[Agent]: with Session(engine) as db: q = db.query(Agent) if session_id is not None: q = q.filter_by(session_id=session_id) return q.order_by(Agent.agent_idx).all()
def agent_index(engine) -> dict[str, tuple[str, int]]: """agent_id -> (session_id, agent_idx) for EVERY agent, reading only the id columns — full Agent rows carry each agent's system prompt and tool definitions, which is hundreds of MB across the table.""" with Session(engine) as db: rows = db.query(Agent.agent_id, Agent.session_id, Agent.agent_idx).all() return {a.agent_id: (a.session_id, a.agent_idx) for a in rows}
def session_exists(engine, wire_id: str) -> bool: """Whether any agent row exists for this wire id.
``wire_id`` is a trunk's bare session_id or a fork's full agent_id, and both are answered without hydrating anything: this exists for callers that have to tell "nothing to do" from "no such session" — ``session/close`` — and paying :func:`load_messages` for a session about to be thrown away is not a price worth paying to answer a yes/no question. """ try: parse_agent_id(wire_id) except ValueError: column, value = Agent.session_id, wire_id else: column, value = Agent.agent_id, wire_id with Session(engine) as db: return db.query(Agent.agent_id).filter(column == value).first() is not None
def get_prompt(engine, prompt_id: str) -> Prompt | None: with Session(engine) as db: return db.query(Prompt).filter_by(id=prompt_id).first()
def get_session_mcp_servers(engine, wire_id: str) -> list: """The session's client-defined mcpServers (wire JSON dicts); [] when nothing was ever supplied. Cross-process read: this is how a separate MCP server process sees what the client gave the agent.
Storage rides the agents table (no table of its own): the servers live on the row provisioned with them. wire_id is the trunk's bare session_id or a fork's full agent_id; the read scans that wire session's agent chain (newest first) and returns the most recent provisioning. Compaction rows carry NULL and are skipped. """ try: session_id, _, fork_idx = parse_agent_id(wire_id) except ValueError: session_id, fork_idx = wire_id, 1 with Session(engine) as db: rows = ( db.query(Agent) .filter_by(session_id=session_id, fork_idx=fork_idx) .order_by(Agent.agent_idx.desc()) .all() ) for row in rows: if row.mcp_servers is not None: return list(row.mcp_servers) return []
def delegation_tool_call_ids( engine, wire_id: str, tools: tuple[str, ...] = ("rlm",)) -> set[str]: """The LLM tool-call ids of every in-cell delegation this session made.
A delegation made INSIDE an execute cell does not appear in the message history as a call named "rlm" — the history holds one ``execute`` call and whatever the cell printed. What links the two is the subtool register: one subtool_calls row per in-cell tool call, carrying the PARENT execute call's ACP id. TurnCtx.tcid is ``f"{turn_id}/{llm_id}"``, so the last path segment is the LLM's own tool_call_id — exactly what the persisted assistant message carries in ``tool_calls[].id``. Matching on that is precise; grepping the cell's source for "rlm(" is not (it hits comments, strings, and this docstring).
``wire_id`` is a trunk's bare session_id or a fork's full agent_id; both are matched, because the register stores whichever the agent injected. """ try: bare, _, _ = parse_agent_id(wire_id) except ValueError: bare = wire_id with Session(engine) as db: rows = ( db.query(SubtoolCall.parent_tool_call_id) .filter( SubtoolCall.session_id.in_({wire_id, bare}), SubtoolCall.tool.in_(tools), ) .all() ) return {r[0].rsplit("/", 1)[-1] for r in rows if r[0]}
def subtool_calls_by_parent(engine, wire_id: str) -> dict[str, list[SubtoolCall]]: """Every in-cell tool call this session made, grouped by the LLM id of the execute call that made it, in the order the cell made them.
Same join as :func:`delegation_tool_call_ids`, different question: that one answers "was this call a delegation" and returns a set, this one returns the rows themselves so a replay can re-present each call as the tool call it was — args, diff, location and all. The join is the last path segment of ``parent_tool_call_id`` because ``TurnCtx.tcid`` is ``f"{turn_id}/{llm_id}"`` and the turn id died with the process that minted it, while the llm id is persisted in the assistant message's ``tool_calls[].id``.
**Read-only by contract.** The live drain (``agent/tools.py _emit_subtool_calls``) owns ``emitted`` as its queue marker and flips it to claim rows; a replay is a re-presentation, not a consumption, so this must not touch it or those calls vanish from the wire forever.
``wire_id`` is a trunk's bare session_id or a fork's full agent_id, and both are matched because the register stores whichever the agent injected (``meta["session_id"]``). That cannot double-count: one parent id was executed once, by one agent, which wrote its rows under one session_id. """ try: bare, _, _ = parse_agent_id(wire_id) except ValueError: bare = wire_id with Session(engine) as db: rows = ( db.query(SubtoolCall) .filter(SubtoolCall.session_id.in_({wire_id, bare})) .order_by(SubtoolCall.id) .all() ) grouped: dict[str, list[SubtoolCall]] = {} for row in rows: if row.parent_tool_call_id: grouped.setdefault(row.parent_tool_call_id.rsplit("/", 1)[-1], []).append(row) return grouped
def get_task(engine, task_id: str) -> Task | None: with Session(engine) as db: return db.query(Task).filter_by(task_id=task_id).first()
def task_by_sub_session(engine, sub_session: str) -> Task | None: """The task that owns a child session (latest, if several re-opened).""" with Session(engine) as db: return ( db.query(Task) .filter_by(sub_session=sub_session) .order_by(Task.created_at.desc()) .first() )
def count_tasks(engine, owner_session: str | None = None) -> int: """Total tasks ever launched — globally (the task-N numbering, whose UNIQUE constraint is global) or by one session.""" with Session(engine) as db: query = db.query(Task) if owner_session is not None: query = query.filter_by(owner_session=owner_session) return query.count()
def running_tasks(engine, owner_session: str) -> list[Task]: with Session(engine) as db: return ( db.query(Task) .filter_by(owner_session=owner_session, status="running") .order_by(Task.created_at) .all() )
def owner_tasks(engine, owner_session: str) -> list[Task]: """Every task one session has launched, any status, oldest first.
``running_tasks`` answers "what am I waiting on"; this answers "what have I ever set going", which is the question a bare ``task_read()`` asks. Terminal tasks are included on purpose — the whole point of the mailbox is that a completion can be missed (owner mid-turn, owner compacted, owner restarted), and the row is the only durable record that it happened. """ with Session(engine) as db: return ( db.query(Task) .filter_by(owner_session=owner_session) .order_by(Task.created_at) .all() )
def pending_deliveries(engine, session_id: str) -> list[TaskDelivery]: """The session's undelivered completions, in ARRIVAL order.""" with Session(engine) as db: return ( db.query(TaskDelivery) .filter_by(session_id=session_id, status="pending") .order_by(TaskDelivery.id) .all() )
def get_goal(engine, session_id: str) -> Goal | None: """This session's goal, whatever its status. ``/goal`` with no argument reads this: a paused or blocked goal is not nothing, and a user who has to guess which of the two they left behind cannot decide what to do next.""" with Session(engine) as db: return db.query(Goal).filter_by(session_id=session_id).first()
def active_goal(engine, session_id: str) -> Goal | None: """The goal if and only if it continues. None for every other status.
The driver asks THIS and never ``get_goal``, so "should I keep going" is one column compare in one place rather than a status switch repeated at every call site that has to agree. A goal that is paused, blocked, budget_limited or complete is a row worth showing and not a reason to run another turn. """ with Session(engine) as db: row = db.query(Goal).filter_by(session_id=session_id, status=GOAL_ACTIVE).first() return row
def get_max_agent_idx(engine, session_id: str, fork_idx: int | None = 1) -> int: """Highest agent_idx for a session. fork_idx=1 (default) follows the trunk; None scans all forks.""" with Session(engine) as db: q = db.query(Agent.agent_idx).filter_by(session_id=session_id) if fork_idx is not None: q = q.filter_by(fork_idx=fork_idx) rows = q.all() return max((r[0] for r in rows), default=1)
def get_max_fork_idx(engine, session_id: str, agent_idx: int) -> int: """Highest fork_idx for a (session_id, agent_idx) pair — 1 when only the trunk exists.""" with Session(engine) as db: rows = ( db.query(Agent.fork_idx) .filter_by(session_id=session_id, agent_idx=agent_idx) .all() ) return max((r[0] for r in rows), default=1)
def load_agent_messages( engine, agent, hydrate: bool = False, store: ImageStore | None = None,) -> list[dict]: """Message VIEW for an agent row.
The trunk (fork_idx=1) sees its own rows. A fork sees the trunk's PREFIX rows (id <= forked_at) followed by its own rows — the prefix is shared, never copied. """ session_id, agent_idx, fork_idx = parse_agent_id(agent.agent_id) if fork_idx == 1: return load_messages(engine, agent.agent_id, hydrate, store) trunk_id = build_agent_id(session_id, agent_idx, 1) anchor = int(agent.forked_at) if agent.forked_at is not None else None with Session(engine) as db: q = db.query(Message).filter_by(agent_id=trunk_id).order_by(Message.id) if anchor is not None: q = q.filter(Message.id <= anchor) msgs = [dict(r.data) for r in q.all()] msgs += [ dict(r.data) for r in db.query(Message) .filter_by(agent_id=agent.agent_id) .order_by(Message.id) .all() ] if hydrate and store: msgs = [hydrate_message(m, store) for m in msgs] return msgs
def load_messages( engine, agent_id: str, hydrate: bool = False, store: ImageStore | None = None,) -> list[dict]: with Session(engine) as db: rows = db.query(Message).filter_by(agent_id=agent_id).order_by(Message.id).all() msgs = [dict(r.data) for r in rows] if hydrate and store: msgs = [hydrate_message(m, store) for m in msgs] return msgs
def query_messages( engine, agent_ids: list[str], roles: list[str] | None = None, after: str | None = None, before: str | None = None, order: str = "asc", limit: int = 1_000_000, offset: int = 0,) -> list[Message]: with Session(engine) as db: q = db.query(Message).filter(Message.agent_id.in_(agent_ids)) if roles is not None: q = q.filter(Message.role.in_(roles)) if after is not None: q = q.filter(Message.created_at > after) if before is not None: q = q.filter(Message.created_at < before) q = q.order_by(Message.id.asc() if order == "asc" else Message.id.desc()) return q.offset(offset).limit(limit).all()
def list_sessions(engine, limit: int = 50, offset: int = 0, include_forks: bool = False) -> list[dict]: """Sessions ordered by most recent message activity (desc).
include_forks=False (default) hides the fork dimension entirely: only trunk agent rows (fork_idx=1) are counted, and since fork messages are keyed by their fork agent_id, dropping the fork agent rows drops their messages from the join too. """ with Session(engine) as db: q = db.query( Agent.session_id, func.max(Message.created_at), func.count(func.distinct(Message.id)), func.count(func.distinct(Agent.agent_id)), ).join(Message, Message.agent_id == Agent.agent_id, isouter=True) if not include_forks: q = q.filter(Agent.fork_idx == 1) rows = ( q.group_by(Agent.session_id) .order_by(func.max(Message.created_at).desc()) .offset(offset) .limit(limit) .all() ) models = {} agent_q = db.query(Agent.session_id, Agent.model_identifier) if not include_forks: agent_q = agent_q.filter(Agent.fork_idx == 1) for a in agent_q.all(): models.setdefault(a.session_id, a.model_identifier) return [ { "session_id": sid, "last_activity": last or "", "message_count": n_msg, "agent_count": n_agent, "model_identifier": models.get(sid, ""), } for sid, last, n_msg, n_agent in rows ]
#: How much of the first user message becomes a session's title.TITLE_LEN = 50
def _session_title(db: Session, agent_id: str | None) -> str | None: """The first user message of a session's ROOT agent, trimmed.
Read off the root rather than the representative: a session that compacted has an agent_idx-2 row whose first message is a summary, and titling from that would rename the session every time it grew. Index 1 because index 0 is the system row ``AgentSession.create`` always writes first.
None rather than a placeholder. ``SessionInfo.title`` is optional and the client is the one that knows what an untitled session should look like. """ if agent_id is None: return None rows = ( db.query(Message.data) .filter_by(agent_id=agent_id) .order_by(Message.id) .limit(2) .all() ) if len(rows) < 2: return None content = (rows[1][0] or {}).get("content", "") if isinstance(content, list): text = "".join( b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text" ) else: text = str(content) return text.strip()[:TITLE_LEN] or None
def session_title(engine, agent_id: str) -> str | None: """The title :func:`list_session_infos` would show for one agent.
Exists so an agent can announce a session's name the moment one exists. No response in the protocol carries a ``SessionInfo`` — ``session/new`` answers with a sessionId and config options — so ``session_info_update`` is the only way a client watching a session list learns a title without re-listing. Reading it back out of the store rather than deriving it from the prompt in hand is the whole point: the notification and the list are then incapable of disagreeing about what the session is called. """ with Session(engine) as db: return _session_title(db, agent_id)
def list_session_infos( engine, cwd: str | None = None, limit: int = 50, offset: int = 0,) -> tuple[list[dict], int | None]: """One page of sessions shaped for ACP ``session/list``.
Returns ``(infos, next_offset)``, where ``next_offset`` is None on the last page and each info carries exactly the four fields ``SessionInfo`` has: ``session_id``, ``cwd``, ``title``, ``updated_at``.
Not :func:`list_sessions` with extra keys. That one is the memory tool's view — message counts, model, who is working now — and its callers render every column it returns; this one is a wire shape, and a wire shape that grew a ``message_count`` would be a column the protocol has nowhere to put.
``cwd`` filters; None lists every session the store knows. Recency is the last message, falling back to the agent row's own creation for a session that was opened and never spoken to — without the fallback a brand-new session sorts as older than everything, which is the one session a client is most likely to be looking for.
Forks are excluded, as in :func:`list_sessions`: a fork is addressed by its own agent id and is a branch of a listed session, not a session of its own. """ with Session(engine) as db: last = func.coalesce(func.max(Message.created_at), func.max(Agent.created_at)) q = ( db.query(Agent.session_id, last) .join(Message, Message.agent_id == Agent.agent_id, isouter=True) .filter(Agent.fork_idx == 1) ) if cwd is not None: q = q.filter(Agent.cwd == cwd) # One extra row rather than a COUNT: "is there a next page" is the only # thing the extra answer buys, and a second aggregate over the whole # table costs more than one row. rows = q.group_by(Agent.session_id).order_by(last.desc()).offset(offset).limit(limit + 1).all() more = len(rows) > limit rows = rows[:limit] ids = [r[0] for r in rows]
head: dict[str, tuple[int, str, str]] = {} root: dict[str, str] = {} if ids: agents = ( db.query( Agent.session_id, Agent.agent_id, Agent.agent_idx, Agent.cwd, Agent.created_at, ) .filter(Agent.session_id.in_(ids), Agent.fork_idx == 1) .all() ) for sid, agent_id, idx, agent_cwd, created in agents: if sid not in head or idx > head[sid][0]: head[sid] = (idx, agent_cwd, created) if idx == 1: root[sid] = agent_id infos = [ { "session_id": sid, "cwd": head.get(sid, (0, cwd or "", ""))[1], "title": _session_title(db, root.get(sid)), "updated_at": updated or head.get(sid, (0, "", ""))[2] or None, } for sid, updated in rows ] return infos, (offset + limit if more else None)
def search_messages( engine, query: str, limit: int = 20, session_id: str | None = None, agent_idx: int | None = None, agent_ids: set[str] | None = None, roles: list[str] | None = None, include_forks: bool = True,) -> list[dict]: """Keyword search over message text (FTS5/bm25 on sqlite, tsvector/ts_rank on postgres — see memory/fts.py). Returns {message fields + session_id/agent_idx + score} dicts, best match first. ``score`` is lower = better on both backends.
Filters are pushed INTO the query (fts.search_rows joins messages and agents), so ``limit`` is the number of matches returned rather than the number of global top hits that happened to survive a Python-side filter. """ with engine.connect() as conn: return fts.search_rows( conn, engine, query, limit, roles=roles, session_id=session_id, agent_idx=agent_idx, agent_ids=agent_ids, include_forks=include_forks, )