diff --git a/CONTEXT.md b/CONTEXT.md index 2337aa8cb..bb640d38a 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -115,9 +115,14 @@ produces nothing of its own and exists to put a question to this turn's Agent Pa merge what they answer (`ask_intake`, `ask_advice`, `ask_review`, `ask_salvage`, `ask_judge`, `ask_system_addendum`, `ask_archive`, `ask_select_tools`). Replacing a role therefore means two different things: a new way to produce, or a new rule for adjudicating what the products say. -Frozen per Generation: the tool array is the prompt-cache prefix, so the set a turn runs on -does not move between two of its model calls -- except for tools the turn's own `plugin` call -connected, which join it on purpose (`ToolRegistry.admit_to_this_turn`). +Frozen per Session: the tool array is the prompt-cache prefix, so the set a session +assembles with does not move between its model calls or between its turns. It is +captured on the session's first assembly and recaptured only at a refresh point -- a +new session, a compaction (cashed by the next assembly), a `/clear`, or a release. A +live switch, a missing credential, or a selected base changes availability, not the +array, and is reported in the runtime context; a tool the turn's own `plugin` call +connects is admitted to `offers` (reachable through `tool_call`) and joins the array at +the next refresh. **Harness Curator** (`experimental/curator/`): Experimental generation of a worker's Harness from its task, the materials handed to it and @@ -719,9 +724,11 @@ user declaring the agent owns nothing and is never refilled. Two things never carry ownership. The generic row (`Raven-General`) claims none whatever a config says, because it carries no capability bias and a line about it would prohibit the agent reading it from doing its own work. And the section is withheld entirely on a turn holding -no dispatch tool — `spawn` and `run_subagent_dag` can both be withheld by -`tools.disabledTools`, and a prohibition outliving every means of handing the work over -leaves a request with no compliant action at all. Only the paths the turn does hold are named. +no dispatch tool — a hard-subset deploy or a charter narrowing can leave the array without +`spawn` and `run_subagent_dag`, and a prohibition outliving every means of handing the work +over leaves a request with no compliant action at all. A live `tools.disabledTools` switch +keeps the schema and reports the tool unavailable in the runtime context instead. Only the +paths the turn does hold are named. _Avoid_: putting it in `description` — that copy is spliced into the tool descriptions, where the model reads it only once it is already choosing an agent. @@ -926,8 +933,10 @@ Which interchangeable backend each web tool calls: `tools.web.search.provider` s so a selection names a vendor and never a URL. `web_search` is registered whatever the config holds and *withheld* from the offered set while the selected vendor's key does not resolve (Keenable searches without one and is offered keyless, as Jina reads pages keyless), so a key -pasted mid-run surfaces it without a restart -- read live from the vendor slot and, for Serper, -from the pre-vendor leaf, in the order `WebToolsConfig.vendor_key` resolves them, and an empty +pasted mid-run makes it callable again without a restart -- the schema was already in the +session's frozen array, and the runtime context clears the notice -- read live from the vendor +slot and, for Serper, from the pre-vendor leaf, in the order `WebToolsConfig.vendor_key` +resolves them, and an empty slot is a revocation rather than a miss (except for a borrowing vendor, whose empty slot is the ordinary state and whose LLM provider key answers instead); `web_fetch` is always offered, falling back to Jina, which reads pages without a key. The two sub-agent launchers inherit the host's selection @@ -2349,12 +2358,13 @@ whose change implies WORK rather than a different answer (constructing a provide an MCP handshake, moving a workspace) keeps its apply path -- a door, the pool's fingerprint cache, or the generation swap. Timing is asymmetric by design: a revocation binds the next read (a tightened deny pattern gates the very next tool call), while an -addition to the model's tool array lands on the next turn -- `ToolRegistry.turn_scope` -freezes both registry membership and the withheld set at turn entry, because the array -is the prompt-cache prefix and must not move between two model calls of one turn. The one -exception is an addition the turn's own call produced: `ToolRegistry.admit_to_this_turn` -lets the tools a `plugin` connect or authorize registered join that turn from its next -model call, at the cost of one rebuilt prefix. +addition to the model's tool array is held until a session refresh -- `ToolRegistry` freezes +the array on the session's first assembly and recaptures it only at a new session, a +compaction, a `/clear`, or a release, because the array is the prompt-cache prefix. +`ToolRegistry.turn_scope` still freezes registry membership and the withheld set at turn +entry, so a mid-turn arrival cannot change what `offers` or `execute` admits. The turn's own +`plugin` call is the one admission: `ToolRegistry.admit_to_this_turn` lets the tools it +connected reach `tool_call` from the next model call, without moving the array. _Avoid_: reading `config.json` keys ad hoc outside this module; treating a live preference as a door (doors reconcile members after a durable write; this lane never touches member identity). diff --git a/raven/agent/loop/main.py b/raven/agent/loop/main.py index 122176352..3ea1f9199 100644 --- a/raven/agent/loop/main.py +++ b/raven/agent/loop/main.py @@ -397,6 +397,14 @@ def __init__( # Asked once per assembled tool array, so an off switch flipped now is # honoured by the next request rather than the next restart. self.tools.set_withheld_source(self._withheld_tool_names) + # The same switch, asked for its reason: the runtime-context notice and + # the refusal of a call to an advertised-but-withheld tool say which + # setting or credential puts the tool back. + self.tools.set_withheld_reason_source(self._withheld_tool_reasons) + # The constructor's list is the one off switch that cannot move while + # the process runs, so it stays a hard removal from the session array + # instead of becoming a notice. + self.tools.set_hard_withheld_source(self._hard_withheld_names) # Context engine — the single ContextAssembler. # Constructed here (after self.tools) so the factory can capture @@ -465,7 +473,7 @@ def __init__( # rebuilt on a hot config apply, so anything captured now would be # either missing or stale by the time a turn asks for it. list_subagents=lambda: self.subagents.list_agents(), - get_tool_notices=self._mcp_tool_notices, + get_tool_notices=self._tool_notices, # Read at call time: the board is wired further down this constructor. get_session_notices=lambda key: self.task_board.turn_notes(key) if self.task_board else [], now_fn=now_fn, diff --git a/raven/agent/loop/mcp_glue.py b/raven/agent/loop/mcp_glue.py index 78938589f..69cd8c002 100644 --- a/raven/agent/loop/mcp_glue.py +++ b/raven/agent/loop/mcp_glue.py @@ -36,6 +36,47 @@ async def _swallow_terminal_cancel(task: "asyncio.Task") -> None: pass +_MCP_AUTH_REMAIN = ( + "installed, awaiting authorization. Its tools remain in this conversation's tool list, but " + "calls to them fail until it is authorized -- by the `plugin` tool's authorize action, or by " + "the user in the plugin panel." +) +_MCP_CONNECTING_REMAIN = ( + "installed, still connecting. Its tools remain in this conversation's tool list, but calls to " + "them fail until the handshake finishes." +) +_MCP_DISCONNECTED_REMAIN = ( + "disconnected. Its tools remain in this conversation's tool list, and calls to them fail until it reconnects." +) +_MCP_DISABLED_REMAIN = ( + "disabled in settings. Its tools remain in this conversation's tool list, and calls to them " + "fail until it is enabled again." +) +_MCP_REMOVED_REMAIN = ( + "no longer loaded. Its tools remain in this conversation's tool list, and calls to them fail " + "until it is added back." +) +_MCP_AUTH_LIVE = ( + "installed, awaiting authorization. Its tools are absent from this turn's definitions until " + "it is authorized -- by the `plugin` tool's authorize action, or by the user in the plugin " + "panel." +) +_MCP_AUTH_JOIN = ( + "installed, awaiting authorization. Its tools are absent from this conversation's tool list; " + "after it is authorized they join at the next compaction or new conversation -- by the " + "`plugin` tool's authorize action, or by the user in the plugin panel." +) +_MCP_CONNECTING_LIVE = ( + "installed, still connecting. Its tools are absent from this turn's definitions and register " + "themselves when the handshake finishes, so they are available from a later turn without " + "anyone acting." +) +_MCP_CONNECTING_JOIN = ( + "installed, still connecting. Its tools join this conversation's tool list at the next " + "compaction or new conversation." +) + + class McpGlueMixin: """MCP lifecycle glue: connect, sync, prewarm, apply, close. Bodies moved verbatim from main.py.""" @@ -171,8 +212,8 @@ def _sync_mcp_meta_tools(self) -> None: def _mcp_tool_notices(self) -> list[str]: """Host facts about MCP tools the definitions cannot carry. - One line per enabled server whose tools are absent from this turn for a - reason the model cannot see, and the three reasons need different lines: + One line per server whose tools the model cannot use, and the states + need different lines: * ``auth_required`` -- the wait is on a person, and the answer names who can end it. Without this the model reads an unauthorized plugin as a @@ -185,20 +226,29 @@ def _mcp_tool_notices(self) -> list[str]: names an installed server, so a model that does not think to search reports a capability it holds as missing. ``tool_search``'s own description says a catalog exists; only this says what is in it. - - This line states an inventory and promises no route, which is what keeps - it true. This block is rendered once per turn, while the fold is decided - per model call against an array a ``before_iteration`` hook may narrow - first (``HookDecision.modified_tools``) -- so a turn-level sentence about - what this request folded, or about reaching it through ``tool_search`` / - ``tool_call``, can be falsified after it is written. "This server is - connected and offers N tools" cannot. - - The count is the server's tools this turn's array carries, not the - manager's ``tool_count``: that one counts every wrapper the server - registered, including one the operator switched off, which no surface - offers. The fold gate is only about noise -- below it every schema is in - the array and the line tells the model nothing it cannot see. + * connected, disconnected, or disabled while its tools are OUTSIDE the + session's frozen array -- the array is not recomputed until a new + session or a compaction, so the line says what state the server is in + and when its tools join. A server that connects mid-session is + reachable through ``tool_call`` only if the model knows the name and + arguments; the honest fact is the refresh point. + + The array is the session's snapshot (``ToolRegistry.get_definitions``): + captured once and refreshed only at a new session, a compaction, or a + log id change. This line states an inventory and promises no route, + which is what keeps it true. This block is rendered once per turn, while + the fold is decided per model call against an array a + ``before_iteration`` hook may narrow first + (``HookDecision.modified_tools``) -- so a turn-level sentence about what + this request folded, or about reaching it through ``tool_search`` / + ``tool_call``, can be falsified after it is written. "This server is + connected and offers N tools" cannot. + + The folded count is the server's tools the array carries, not the + manager's ``tool_count``: that one counts every wrapper the server + registered, including one the operator switched off, which no surface + offers. The fold gate is only about noise -- below it every schema is in + the array and the line tells the model nothing it cannot see. Rendered into the runtime-context block, not the system prompt -- the set changes turn to turn and must never be cached with the prefix. This @@ -224,32 +274,75 @@ def _mcp_tool_notices(self) -> list[str]: offered: set[str] = set() if folded: offered = {d["function"]["name"] for d in self.tools.get_definitions()} + # None outside a turn: the pre-freeze behaviour, where the array is the + # live view and a server's tools appear as soon as it connects. + snapshot = self.tools.session_definition_names() + snapshot_servers = self.tools.session_definition_servers() if snapshot is not None else frozenset() + seen: set[str] = set() notices = [] for snap in mgr.status(): + name = snap["name"] + seen.add(name) + snap_names = set(self.tools.session_definition_names_of_server(name)) if snapshot is not None else set() + live_names = set(self.tools.names_from(name)) if not snap.get("enabled", True): + if snap_names: + notices.append(mcp_notice(name, _MCP_DISABLED_REMAIN)) continue - if snap["state"] == "auth_required": - notices.append( - mcp_notice( - snap["name"], - "installed, awaiting authorization. Its tools are absent from this turn's " - "definitions until it is authorized -- by the `plugin` tool's authorize " - "action, or by the user in the plugin panel.", - ) - ) - elif snap["state"] == "connecting": - notices.append( - mcp_notice( - snap["name"], - "installed, still connecting. Its tools are absent from this turn's " - "definitions and register themselves when the handshake finishes, so " - "they are available from a later turn without anyone acting.", + state = snap["state"] + if state == "auth_required": + if snapshot is None: + text = _MCP_AUTH_LIVE + elif snap_names: + text = _MCP_AUTH_REMAIN + else: + text = _MCP_AUTH_JOIN + notices.append(mcp_notice(name, text)) + elif state == "connecting": + if snapshot is None: + text = _MCP_CONNECTING_LIVE + elif snap_names: + text = _MCP_CONNECTING_REMAIN + else: + text = _MCP_CONNECTING_JOIN + notices.append(mcp_notice(name, text)) + elif snap["connected"]: + added = live_names - snap_names + gone = snap_names - live_names + if snapshot is not None and snap_names and (added or gone): + # A reconnect can change the server's tool set; the frozen + # array kept the old names. Name both halves rather than + # reporting the connection as fully in the list. + parts: list[str] = [] + if added: + parts.append( + f"{len(added)} new tool(s) join this conversation's tool list at the next " + "compaction or new conversation" + ) + if gone: + parts.append( + f"{len(gone)} tool(s) that are no longer registered remain in the list and " + "calls to them fail" + ) + notices.append(mcp_notice(name, "connected; " + "; ".join(parts) + ".")) + elif snapshot is not None and not snap_names and live_names: + notices.append( + mcp_notice( + name, + f"connected, offering {len(live_names)} tool(s); they join this conversation's " + "tool list at the next compaction or new conversation.", + ) ) - ) - elif folded and snap["connected"]: - mine = [n for n in self.tools.names_from(snap["name"]) if n in offered] - if mine: - notices.append(mcp_notice(snap["name"], f"connected, offering {len(mine)} tool(s).")) + elif folded: + mine = [n for n in live_names if n in offered] + if mine: + notices.append(mcp_notice(name, f"connected, offering {len(mine)} tool(s).")) + elif snap_names: + notices.append(mcp_notice(name, _MCP_DISCONNECTED_REMAIN)) + # A server removed outright has no row in status() at all, but its names + # are still advertised by the frozen array. + for name in sorted(snapshot_servers - seen): + notices.append(mcp_notice(name, _MCP_REMOVED_REMAIN)) return notices def prewarm_mcp(self) -> None: diff --git a/raven/agent/loop/organ_glue.py b/raven/agent/loop/organ_glue.py index d07590cb7..8b562a371 100644 --- a/raven/agent/loop/organ_glue.py +++ b/raven/agent/loop/organ_glue.py @@ -223,6 +223,13 @@ async def _assemble_context_messages( model answer for a routed one. """ from raven.context_engine import TurnContext # deferred — see module note + from raven.context_engine.history.markers import HISTORY_COMPACTED_META + + # The session log this turn reads. ``/clear`` mints a new log id on the + # same key; a frozen array captured under the old one is dropped and + # recaptured here, before the engine budgets with it. + revision = session.revision if isinstance(session, Session) else None + self.tools.bind_session_revision(session_key, revision.log_id if revision is not None else None) # Reset the metadata stash BEFORE calling the engine. If # ``engine.assemble`` raises partway, the next caller falls back to @@ -248,6 +255,11 @@ async def _assemble_context_messages( session_revision=session.revision if isinstance(session, Session) else None, ), ) + if assembled.metadata.get(HISTORY_COMPACTED_META): + # Mark, not invalidate: this turn's array is the one its notices and + # system-prompt derivations were built from. The next assembly + # cashes the mark, so the array, notices and text all move together. + self.tools.schedule_definitions_refresh(session_key) # Stash the engine's injected_skill_ids so the after-turn # feedback dispatcher can read the source-qualified ids the # unified engine populates via SkillForgeRouter. If the key is absent diff --git a/raven/agent/loop/wiring.py b/raven/agent/loop/wiring.py index 2573c6977..008891f30 100644 --- a/raven/agent/loop/wiring.py +++ b/raven/agent/loop/wiring.py @@ -175,7 +175,7 @@ def _withheld_tool_names(self) -> frozenset[str]: withheld: set[str] = set() for entry in configured: withheld.update(self.tools.resolve_configured(entry)) - withheld.update(self._unconfigured_tool_names()) + withheld.update(self._unconfigured_tool_reasons()) # Nothing to search is not a tool to offer. Read from the turn's own # binding rather than from config, so attaching a base takes effect on # the next model call and detaching every base takes the tool away @@ -184,8 +184,89 @@ def _withheld_tool_names(self) -> frozenset[str]: withheld.add("knowledge_search") return frozenset(withheld - (RESOURCE_TOOL_NAMES | PROMPT_TOOL_NAMES | META_TOOL_NAMES)) - def _unconfigured_tool_names(self) -> set[str]: - """Registered tools whose config asks for nothing right now, read live. + def _withheld_tool_reasons(self) -> dict[str, str]: + """The same union as :meth:`_withheld_tool_names`, each name with its reason. + + The reason is what the runtime-context notice and the refusal of a call + to an advertised-but-withheld tool say, so the model can act on the + setting or credential that puts the tool back. Reserved names are + removed here rather than at the switch, for the reasons the names + method gives. + """ + from raven.agent.tools.tool_search import META_TOOL_NAMES + from raven.config.live import disabled_tool_names + from raven.mcp.prompts import PROMPT_TOOL_NAMES + from raven.mcp.resources import RESOURCE_TOOL_NAMES + + reasons: dict[str, str] = {} + configured = set(disabled_tool_names(self._live_config)) | set(self._disabled_tools) + for entry in configured: + for name in self.tools.resolve_configured(entry): + reasons.setdefault(name, "switched off in settings (tools.disabledTools)") + for name, reason in self._unconfigured_tool_reasons().items(): + reasons.setdefault(name, reason) + if not knowledge_scope.selected(): + reasons.setdefault("knowledge_search", "no knowledge base is selected in this conversation") + reserved = RESOURCE_TOOL_NAMES | PROMPT_TOOL_NAMES | META_TOOL_NAMES + return {name: reason for name, reason in reasons.items() if name not in reserved} + + def _hard_withheld_names(self) -> frozenset[str]: + """Names the constructor's own list takes off for the life of the process. + + The eval harness's strict subset, resolved against the registry when + asked. It never enters a session snapshot: it cannot change mid-session, + so keeping it out costs no prompt cache, and "the model never sees it" + is the harness's contract. Reserved names are ignored for the same + reason :meth:`_withheld_tool_names` ignores them. + """ + from raven.agent.tools.tool_search import META_TOOL_NAMES + from raven.mcp.prompts import PROMPT_TOOL_NAMES + from raven.mcp.resources import RESOURCE_TOOL_NAMES + + names: set[str] = set() + for entry in self._disabled_tools: + names.update(self.tools.resolve_configured(entry)) + return frozenset(names - (RESOURCE_TOOL_NAMES | PROMPT_TOOL_NAMES | META_TOOL_NAMES)) + + def _tool_availability_notices(self) -> list[str]: + """One line per advertised tool the live switch has off right now. + + The array is the session's frozen snapshot, so a tool in it that is + withheld is still visible to the model and can still be called; this is + where it learns why the call will be refused, and when the tool comes + back. MCP tools are left to :meth:`_mcp_tool_notices`, which speaks per + server: a server's whole set goes away together, and one line per tool + would repeat the same fact. + """ + from raven.context_engine.runtime_context import tool_notice + + names = self.tools.session_definition_names() + if not names: + return [] + # The reason map is the loop's own switch axes (settings, credentials, + # the selected base). A name withheld by a charter or by the turn + # freeze is not in it, and is left to the dispatch's own prompt: it is + # a restriction on this turn, not an availability fact, and a sentence + # naming a setting would be false. + reasons = self._withheld_tool_reasons() + lines: list[str] = [] + for name in sorted(set(reasons) & names): + if self.tools.session_definition_origin(name) is not None: + continue + lines.append( + tool_notice( + name, + f"currently unavailable -- {reasons[name]}; calls to it are refused until it is enabled again.", + ) + ) + return lines + + def _tool_notices(self) -> list[str]: + """The host's tool-surface facts for this turn's runtime context.""" + return [*self._mcp_tool_notices(), *self._tool_availability_notices()] + + def _unconfigured_tool_reasons(self) -> dict[str, str]: + """Registered tools whose config asks for nothing right now, with why. The old registration gate, moved to the withheld axis so it works in both directions while the process runs. The rules themselves are @@ -201,9 +282,11 @@ def _unconfigured_tool_names(self) -> set[str]: ``isinstance`` check read a plugin *subclass* as the built-in itself and withheld it on the built-in's empty section. """ + from raven.agent.tools.browser import BROWSER_TOOL_NAMES + media = self.media_config gated = getattr(self, "_config_gated_tools", {}) - names: set[str] = set() + names: dict[str, str] = {} for cls, kind, fallback in ( (ImageGenerateTool, "image", media.image), (SpeechGenerateTool, "speech", media.speech), @@ -213,7 +296,7 @@ def _unconfigured_tool_names(self) -> set[str]: continue cfg = self._live_media_config(kind, fallback) if not (cfg.api_key or cfg.model): - names.add(cls.name) + names[cls.name] = f"its tools.media.{kind} section names no model and no key" search = self.tools.get(WebSearchTool.name) # Asked of the tool, not restated here: it resolves the selected # vendor's key from the live reader below or from that vendor's own @@ -221,10 +304,10 @@ def _unconfigured_tool_names(self) -> set[str]: # SERPER_API_KEY whatever the deployment had chosen, which withheld a # keyed Tavily search. if search is not None and search is gated.get(WebSearchTool.name) and not search.ready: - names.add(WebSearchTool.name) + names[WebSearchTool.name] = "no search key is configured for the selected search vendor" pictures = self.tools.get(ImageSearchTool.name) if pictures is not None and pictures is gated.get(ImageSearchTool.name) and not pictures.api_key: - names.add(ImageSearchTool.name) + names[ImageSearchTool.name] = "no image-search key is configured for the selected vendor" # A contributed tool that declared ``configured()`` at the door answers # for itself on this same lane (the paper is in # raven/contracts/plugin_surface.py): the built-ins above are judged by @@ -247,7 +330,11 @@ def _unconfigured_tool_names(self) -> set[str]: logger.warning("tool {} could not say whether it is configured: {}", name, exc) continue if not offered: - names.add(name) + names[name] = ( + "the browser driver is not installed (the browser extra is missing)" + if name in BROWSER_TOOL_NAMES + else "the plugin that contributes it reports it is not configured" + ) return names def _live_exec_extra_deny(self) -> list[str] | None: @@ -863,6 +950,10 @@ def clear_session_binding(self, session_key: str) -> None: # does: a deleted session has nothing left to run as, and this is the # one place that says a session is over. self._session_personas.pop(session_key, None) + # The frozen tool array and its log id go with it for the same reason: + # the key may be reused by a later session, and an active session's + # array must never be evicted to make room for another. + self.tools.release_session_tools(session_key) def _forget_transport_verdicts(self) -> None: """Drop the capability verdicts a new provider may answer differently. diff --git a/raven/agent/tools/plughub.py b/raven/agent/tools/plughub.py index 62364c902..92fef8428 100644 --- a/raven/agent/tools/plughub.py +++ b/raven/agent/tools/plughub.py @@ -194,8 +194,9 @@ def description(self) -> str: "command line, and you must not compose one. Never put an API key, token, password or account " "name in these arguments: a plugin that needs a secret is reported with " "the field's name, and the user enters it in the plugin panel. A newly " - "connected plugin's tools appear in your tool list from the next step on, " - "not inside this call's result." + "connected plugin's tools join this conversation's tool list at the next " + "compaction or new conversation; until then `tool_call` can reach them by " + "name, not inside this call's result." ) @property @@ -383,7 +384,7 @@ def _connect_report(self, name: str, result: dict) -> str: named = f": {', '.join(tools)}" if tools else "" return ( f"Connected '{name}'. It registered {snap.get('tool_count') or len(tools)} tool(s){named}. " - f"They are in your tool list from the next step on." + f"{self._joined_note()}" ) url = pending_url(name) @@ -448,7 +449,7 @@ async def _authorize(self, name: str) -> str: named = f": {', '.join(tools)}" if tools else "" return ( f"'{name}' is authorized and connected, with {snap.get('tool_count') or len(tools)} tool(s){named}. " - f"They are in your tool list from the next step on." + f"{self._joined_note()}" ) url = pending_url(name) if url: @@ -491,7 +492,11 @@ async def _remove(self, name: str, confirm: bool) -> str: except PlugConnectError as e: return f"Error: removing '{name}' failed: {e.detail}" origin = out.get("origin") or "market" - return f"Removed '{name}' ({origin} entry), with its stored credentials. Its tools are gone from your list." + return ( + f"Removed '{name}' ({origin} entry), with its stored credentials. Its tools keep their " + "schemas in this conversation's tool list until the next compaction or new conversation, " + "but calls to them now fail." + ) # ── helpers ──────────────────────────────────────────────────── @@ -523,12 +528,29 @@ async def _near(self, name: str) -> list[dict]: reader of a refused hub.""" return (await self._lookup(name, _NEAR_LIMIT))[:_NEAR_LIMIT] + def _joined_note(self) -> str: + """What a newly connected plugin's tools can do before the array refreshes. + + The session's schema array is the prompt-cache prefix and is frozen + until a compaction or a new conversation, so the tools are not in it + yet. The turn admission makes them reachable through ``tool_call`` by + name; the note names that route only where it exists. + """ + if self._registry is not None and self._registry.offers_by_name("tool_call"): + return ( + "They join this conversation's tool list at the next compaction or new conversation; " + "`tool_call` can reach them by name now." + ) + return "They join this conversation's tool list at the next compaction or new conversation." + def _join_turn(self, server: str) -> list[str]: """The server's tools, let into the running turn. - Without this the turn freeze holds them back until the user sends - another message, and the result's "from the next step on" is a promise - the agent then fails to keep. + The session's schema array is frozen; admission is what makes the tools + reachable through ``offers`` (``tool_search`` and ``tool_call``) now, + while the result text names the refresh point for the array. Without it + the turn freeze would refuse even ``tool_call`` until the user sent + another message. """ tools = self._tools_of(server) if self._registry is not None: diff --git a/raven/agent/tools/registry.py b/raven/agent/tools/registry.py index ed2d9f8cb..c28da85bc 100644 --- a/raven/agent/tools/registry.py +++ b/raven/agent/tools/registry.py @@ -63,6 +63,27 @@ class ToolSpec: tool: Tool +@dataclass(frozen=True) +class _SessionDefinitions: + """One session's frozen tool array and where each name came from. + + ``origins`` is captured beside the schemas because an MCP tool that + unregisters later takes its ``_origins`` entry with it, and the notice + source still has to say which server's tools left the registry. + """ + + entries: list[tuple[str, dict[str, Any]]] + origins: dict[str, "MCPToolRef | None"] + #: Names whose schema was AUTHORED as dynamic. Their captured schema is the + #: fallback; each read re-renders the live one, the way the live view always + #: has. A frozen enum here would hide an agent table a playbook just bound. + dynamic: frozenset[str] + log_id: str | None + + +_MISSING = object() + + def admit_tool(tool: Tool) -> ToolSpec: """Check the four authored members, normalize the optional ones, dispense the frozen spec. @@ -167,6 +188,21 @@ def absent_tool_error(name: str, *, tail: str = "") -> str: return f"Error: tool '{name}' is not available. It may have been unloaded, or the name may be wrong{tail}." +def unavailable_tool_error(name: str, reason: str) -> str: + """What a call to an advertised-but-withheld tool gets. + + Distinct from :func:`absent_tool_error`: the model can see this schema in + the session's frozen array, so "not found" would send it looking for a name + problem that does not exist. Naming the reason is what makes the refusal + actionable instead of a retry loop. + """ + why = f" ({reason})" if reason else "" + return ( + f"Error: tool '{name}' is currently unavailable{why}. It stays in this conversation's tool list " + "and can be called again once it is enabled; do not retry it in this turn." + ) + + def _received_tail(params: dict[str, Any]) -> str: """The text the model actually emitted, for a call whose arguments did not parse. @@ -369,6 +405,27 @@ def __init__( # consults it for dispatch, so the three cannot disagree). self._withheld: Callable[[], frozenset[str]] | None = None self._schema_hidden: set[str] = set() + # A name the constructor's own list takes off for the life of the + # process (an eval harness's strict subset). It never enters a session + # snapshot: it cannot change mid-session, so keeping it out costs no + # cache, and the harness's contract is "the model never sees it". + self._hard_withheld: Callable[[], frozenset[str]] | None = None + # Why a withheld tool is off, for the runtime-context line and for the + # refusal a call gets. Asked per read, like the off switch itself. + self._withheld_reason: Callable[[], Mapping[str, str]] | None = None + # The session whose array this task serves. Set by ``session_scope_for`` + # and unset outside a turn (a sub-agent, a bare test), which is what keeps the live view there. + self._definition_session: ContextVar[str | None] = ContextVar("tool_registry_definition_session", default=None) + # The frozen array per session, and the log id it was captured under. + # Dropped only by a release, an explicit invalidation, or a log id + # change -- never evicted to make room for another session: that would + # silently recapture an active session's array on its next turn. + self._session_definitions: dict[str, _SessionDefinitions] = {} + self._session_log_ids: dict[str, str | None] = {} + # Sessions whose next assembly recaptures. A compaction marks its + # session here instead of dropping the array mid-turn: the notices and + # system-prompt derivations for that turn were already built from it. + self._definitions_refresh_pending: set[str] = set() # Placed at assembly, not by registering late: an MCP server connects, # and a session brings its own tools, after the host wired its own, so # registration order cannot keep anything at the end. See ``list_last``. @@ -421,6 +478,29 @@ def set_withheld_source(self, source: "Callable[[], frozenset[str]] | None") -> """ self._withheld = source + def set_hard_withheld_source(self, source: Callable[[], frozenset[str]] | None) -> None: + """Install the names off for the life of the process, not for a turn. + + A session snapshot keeps live-withheld tools in the array so a switch + flipped mid-session never moves the prompt-cache prefix. That reasoning + does not cover a name the *constructor* fixed off: it cannot change + while the process runs, so keeping it out costs no cache, and the eval + harness that passes such a list means "the model never sees it". This + source is that list, resolved against the registry at capture time so a + name that arrives later (an MCP tool) is still judged. + """ + self._hard_withheld = source + + def set_withheld_reason_source(self, source: Callable[[], Mapping[str, str]] | None) -> None: + """Install the answer to "why is this name off right now". + + Only a reason's *presence* changes behaviour elsewhere; the text is for + the runtime-context line and the refusal a call gets, which is what + turns "tool unavailable" into something the model can act on (add the + key, select a base, flip the switch). Asked per read, like the switch. + """ + self._withheld_reason = source + def _verifier_refusals(self, name: str, params: dict[str, Any]) -> list[str]: """Why the Action role refuses this call, or an empty list. @@ -649,8 +729,15 @@ def bind_session_tools(self, session_key: str, tools: "Mapping[str, Tool]") -> N self._session_tools[session_key] = dict(tools) def release_session_tools(self, session_key: str) -> None: - """Forget one session's tools. Idempotent -- a session that brought none is normal.""" + """Forget one session's tools. Idempotent -- a session that brought none is normal. + + Also drops the session's frozen tool array: a session that ends must not + leave a snapshot behind for a later key reuse to inherit. + """ self._session_tools.pop(session_key, None) + self._session_definitions.pop(session_key, None) + self._session_log_ids.pop(session_key, None) + self._definitions_refresh_pending.discard(session_key) @contextmanager def session_scope(self, tools: "Mapping[str, Tool] | None") -> Iterator[None]: @@ -673,9 +760,19 @@ def session_scope(self, tools: "Mapping[str, Tool] | None") -> Iterator[None]: @contextmanager def session_scope_for(self, session_key: str) -> Iterator[None]: - """:meth:`session_scope` over whatever this session bound, if anything.""" + """:meth:`session_scope` over whatever this session bound, if anything. + + Also names the session whose frozen tool array this task reads. The + array is the prompt-cache prefix, so it is captured once per session + and served byte-identically until a refresh point (a new session, a + compaction, a log id change, a release). + """ with self.session_scope(self._session_tools.get(session_key)): - yield + token = self._definition_session.set(session_key) + try: + yield + finally: + self._definition_session.reset(token) @contextmanager def turn_scope(self) -> Iterator[None]: @@ -724,7 +821,10 @@ def admit_to_this_turn(self, names: Iterable[str]) -> None: It is wrong when the turn's own call produced the arrival -- the ``plugin`` tool connecting what the user just asked for -- because then all the wait buys is a user having to say "go on" before the agent can - use it. That is paid for with one rebuilt cache prefix, once. + use it. The session's schema array is frozen, so this does not put the + arrival in it; it admits the name to ``offers`` (tool-search and + ``tool_call``), which is the route the plugin result names. The array + joins at the next refresh. Mutated in place rather than re-set, so the admission reaches the loop's reads however the call was dispatched: a ``set`` made inside a @@ -843,13 +943,44 @@ def take_metadata(self, name: str, params: dict[str, Any] | None = None) -> dict return tool.metadata_owner(params or {}).take_metadata() def get_definitions(self) -> list[dict[str, Any]]: - """Tool definitions in OpenAI format, minus those not on offer right now. - - Assembled per LLM call, which is what makes an off switch take effect on - the next turn rather than the next restart: the list is computed here, so - the only thing a preference has to do is be readable by the time this - runs. + """Tool definitions in OpenAI format, from the session's frozen array when one is bound. + + Inside a turn the array is the prompt-cache prefix: it is captured the + first time a session asks for it and served unchanged until the loop + invalidates it (a compaction, a log id change, a release). Availability + changes -- an off switch, a credential, a base attached mid-conversation + -- are reported in the runtime context instead, so they never move the + prefix. Outside a turn (a sub-agent, a bare test) the live + view is served, unchanged. + + The live view is assembled per LLM call, which is what makes an off + switch take effect on the next turn rather than the next restart: the + list is computed here, so the only thing a preference has to do is be + readable by the time this runs. + + Inside a session the snapshot is narrowed on read by the turn's + charter. That is a per-dispatch restriction, not a session availability + switch: a maker turn must not be able to see a writing tool at all, so + the narrowing is applied per read rather than frozen into the snapshot. """ + session = self._definition_session.get() + if session is not None: + cached = self._session_definitions_for(session) + charter = _charter_withheld(self._tools) + out: list[dict[str, Any]] = [] + for name, schema in cached.entries: + if name in charter: + continue + if name in cached.dynamic: + tool = self._visible(name) + if tool is not None: + schema = tool.to_schema() + out.append(schema) + return copy.deepcopy(out) + return self._live_definitions() + + def _live_definitions(self) -> list[dict[str, Any]]: + """The unfrozen view: registered, offered on this turn, not schema-hidden.""" withheld = self.withheld_names() # Served from the admitted snapshot, not the live object: what the # model is shown is what the door checked, whatever the object has @@ -871,6 +1002,163 @@ def get_definitions(self) -> list[dict[str, Any]]: out.extend(last[name] for name in self._listed_last if name in last) return out + def _session_definitions_for(self, session_key: str) -> _SessionDefinitions: + """The session's frozen array, capturing it on first ask.""" + cached = self._session_definitions.get(session_key) + if cached is None: + cached = self._capture_definitions(session_key) + self._session_definitions[session_key] = cached + return cached + + def _capture_definitions(self, session_key: str) -> _SessionDefinitions: + """Take the session's array from the REGISTERED set, not the offered one. + + The live withheld axis is deliberately not consulted: a tool it has off + is still in the array, so flipping the switch either way mid-session + changes only whether calls run. The constructor's hard subset and the + schema-hidden declarations are the exceptions -- neither can move while + the process runs, so keeping them out costs no cache. + """ + try: + hard = self._hard_withheld() if self._hard_withheld is not None else frozenset() + except Exception: # noqa: BLE001 - a bad read must not cost the session its array + logger.warning("tools: could not read the hard-disabled list; keeping every name") + hard = frozenset() + entries: list[tuple[str, dict[str, Any]]] = [] + last: dict[str, tuple[str, dict[str, Any]]] = {} + origins: dict[str, "MCPToolRef | None"] = {} + dynamic: set[str] = set() + for name, tool in self._visible_tools().items(): + if name in hard or name in self._schema_hidden: + continue + if not self.offers_on_this_channel(tool) or not self._visible_to_this_turn(name): + continue + spec = self._specs.get(name) + schema = tool.to_schema() if spec is None or spec.schema_dynamic else spec.schema + if spec is not None and spec.schema_dynamic: + dynamic.add(name) + origins[name] = self._origins.get(name) + pair = (name, schema) + if name in self._listed_last: + last[name] = pair + else: + entries.append(pair) + entries.extend(last[name] for name in self._listed_last if name in last) + return _SessionDefinitions( + entries=entries, + origins=origins, + dynamic=frozenset(dynamic), + log_id=self._session_log_ids.get(session_key), + ) + + def invalidate_session_definitions(self, session_key: str) -> None: + """Drop the frozen array; the next read captures a fresh one. + + Called at the refresh points that are not a new session: a context + compaction and a log id change. Costs one rebuilt prefix, which the + caller has already paid for by rebuilding the history. + """ + self._session_definitions.pop(session_key, None) + + def schedule_definitions_refresh(self, session_key: str) -> None: + """Mark the array for recapture at the session's next assembly. + + A compaction turn cannot switch arrays coherently: the assembler has + already read the tool definitions into its notices and system-prompt + derivations, and only the history half is being rebuilt. Marking + instead of invalidating keeps that turn on one array; the next + assembly's :meth:`bind_session_revision` does the recapture, so the + array, the notices and the system-prompt text move together. + """ + self._definitions_refresh_pending.add(session_key) + + def bind_session_revision(self, session_key: str, log_id: str | None) -> None: + """Record the session log this turn reads, dropping a stale snapshot. + + ``/clear`` mints a new ``log_id`` on the same session key; a snapshot + taken under the old log is reset with it, while a turn that reads the + same log keeps the array it already has. A refresh scheduled by the + previous turn's compaction is cashed here, at the start of the next + assembly. + """ + known = self._session_log_ids.get(session_key, _MISSING) + if known is not _MISSING and known != log_id: + self._session_definitions.pop(session_key, None) + if session_key in self._definitions_refresh_pending: + self._definitions_refresh_pending.discard(session_key) + self._session_definitions.pop(session_key, None) + self._session_log_ids[session_key] = log_id + + def session_definition_names(self) -> frozenset[str] | None: + """Names in the session's frozen array, or ``None`` outside a session. + + Forces the capture: the notice source runs during assembly, before the + tool definitions are necessarily read, and it must describe the array + the turn is about to send. + """ + session = self._definition_session.get() + if session is None: + return None + return frozenset(self._session_definitions_for(session).origins) + + def session_definition_origin(self, name: str) -> "MCPToolRef | None": + """Where a name in the session's frozen array came from, or ``None``. + + ``None`` covers both "not in the array" and "a tool with no MCP + origin"; a caller that needs the difference asks + :meth:`session_definition_names` first. + """ + session = self._definition_session.get() + if session is None: + return None + return self._session_definitions_for(session).origins.get(name) + + def session_definition_names_of_server(self, server: str) -> list[str]: + """Snapshot names one MCP server contributed, whether or not it is still connected.""" + session = self._definition_session.get() + if session is None: + return [] + cached = self._session_definitions_for(session) + return [name for name, ref in cached.origins.items() if ref is not None and ref.server == server] + + def session_definition_servers(self) -> frozenset[str]: + """Every MCP server that contributed a name to the session's frozen array. + + Kept beside the schemas so a server the manager has since removed from + ``status()`` still gets a notice: its names were advertised and calls to + them fail, and no live row is left to speak for them. + """ + session = self._definition_session.get() + if session is None: + return frozenset() + cached = self._session_definitions_for(session) + return frozenset(ref.server for ref in cached.origins.values() if ref is not None) + + def unavailable_reason(self, name: str) -> str | None: + """Why a name in the frozen array cannot run right now, or ``None``. + + ``None`` when the name is not withheld, is outside a session, never + made the array (a hard-withheld name is answered as absent, the way an + unregistered one is), or is withheld by an axis the reason source does + not speak for -- a charter narrowing this dispatch, or the turn freeze. + Those are restrictions on *this turn*, not an operator setting, and + inventing a settings sentence for them is a fact the model would act + on wrongly. + """ + if name not in self.withheld_names(): + return None + session = self._definition_session.get() + if session is None: + return None + if name not in self._session_definitions_for(session).origins: + return None + if self._withheld_reason is None: + return None + try: + return self._withheld_reason().get(name) + except Exception: # noqa: BLE001 - a bad read must not cost the refusal + return None + def hidden_definition(self, name: str) -> dict[str, Any] | None: """One schema-hidden tool's definition, in the shape a visible tool gets. @@ -968,7 +1256,15 @@ async def _execute( # A registered tool answers data questions from its admitted spec; a # session overlay tool never passed the door and answers live. spec = self._specs.get(name) if tool is not None and self._tools.get(name) is tool else None - if not tool or name in self.withheld_names() or not self._visible_to_this_turn(name): + withheld = self.withheld_names() + if not tool or name in withheld or not self._visible_to_this_turn(name): + # A name in the session's frozen array that is withheld is + # advertised: the model can see its schema, so answer with the + # reason and the fact that it returns, not with "not found". + if tool is not None and name in withheld: + reason = self.unavailable_reason(name) + if reason is not None: + return unavailable_tool_error(name, reason) # No catalog listing on the end of it. Unfolded, every schema is # already in this request and a list only repeats it; folded, a # cataloged tool is reached through ``tool_call``, which appends the diff --git a/raven/agent/tools/tool_search.py b/raven/agent/tools/tool_search.py index 7b43b6ffe..0e1a3e8d8 100644 --- a/raven/agent/tools/tool_search.py +++ b/raven/agent/tools/tool_search.py @@ -37,7 +37,7 @@ from itertools import zip_longest from typing import TYPE_CHECKING, Any, NamedTuple -from raven.agent.tools.registry import absent_tool_error +from raven.agent.tools.registry import absent_tool_error, unavailable_tool_error from raven.agent.tools.tool_index import ToolIndex, rank_tools from raven.contracts.token_strategy import TokenStrategy from raven.contracts.tool import Tool @@ -274,9 +274,12 @@ def resolve_target(self, name: Any) -> _Target: ``tool_call`` would recurse into itself. - absent, or withheld from this channel: one answer for both, and the same sentence the direct path uses. Withheld is answered as absent - deliberately -- "it exists but not for you" is itself the way around - the filter that keeping it out of the schema was meant to close. - Appending where the catalog is is safe for that branch because + deliberately for a name that never made the session's array -- "it + exists but not for you" is itself the way around the filter that + keeping it out of the schema was meant to close. A name that IS in + the array and withheld gets its reason instead: the model can see the + schema, so calling it is a live option, not a name mistake. + Appending where the catalog is is safe for the absent branch because ``search`` filters by channel too. It reads as a statement of where the truth lives, not an instruction to search again: a model that searched, called what it found, and lost the tool in between would @@ -291,6 +294,9 @@ def resolve_target(self, name: Any) -> _Target: return _Target(None, f"Error: '{name}' cannot be invoked via tool_call.") tool = self._registry.get(name) if tool is None or not self._registry.offers(tool): + reason = self._registry.unavailable_reason(name) + if reason is not None: + return _Target(None, unavailable_tool_error(name, reason)) tail = " -- tool_search lists what is currently loaded" if self.search_visible() else "" return _Target(None, absent_tool_error(name, tail=tail)) return _Target(tool, None) diff --git a/raven/context_engine/history/compacting/runtime.py b/raven/context_engine/history/compacting/runtime.py index 0860010ed..c6e8c86bb 100644 --- a/raven/context_engine/history/compacting/runtime.py +++ b/raven/context_engine/history/compacting/runtime.py @@ -80,7 +80,12 @@ checkpoint_key, session_message_key, ) -from raven.context_engine.history.markers import HISTORY_CHECKPOINT_KEY, HISTORY_PINNED_KEY, HISTORY_PRIVATE_KEYS +from raven.context_engine.history.markers import ( + HISTORY_CHECKPOINT_KEY, + HISTORY_COMPACTED_META, + HISTORY_PINNED_KEY, + HISTORY_PRIVATE_KEYS, +) from raven.context_engine.history_trimmer import HistoryTrimmer, TrimOutcome from raven.context_engine.runtime_context import retell_notices from raven.contracts.context import AssemblyContext, OverflowOutcome, Segment @@ -272,7 +277,11 @@ async def build(self, ctx: AssemblyContext) -> Segment: raise RuntimeError("CompactingHistoryBuilder requires ctx.prefix (phase B)") session = list(ctx.session_messages or []) if not session: - return Segment(text="", history=[], meta={"path": SEGMENT_PATH, "compaction_action": "pass"}) + return Segment( + text="", + history=[], + meta={"path": SEGMENT_PATH, "compaction_action": "pass", HISTORY_COMPACTED_META: False}, + ) revision = ctx.session_revision if revision is None: return self._unscoped(ctx, ctx.prefix, session) @@ -937,6 +946,7 @@ def _unscoped( meta={ "path": SEGMENT_PATH, "compaction_action": "unscoped", + HISTORY_COMPACTED_META: len(outcome.included_ids) < len(session), "history_kept": len(outcome.included_ids), "history_total": len(session), "history_tokens": outcome.estimated_tokens, @@ -960,6 +970,7 @@ def _meta( return { "path": SEGMENT_PATH, "compaction_action": plan.action, + HISTORY_COMPACTED_META: plan.action == "compact", "compaction_trigger": str(plan.trigger), "compaction_generation": generation, "prompt_tokens": plan.prompt_tokens, diff --git a/raven/context_engine/history/markers.py b/raven/context_engine/history/markers.py index 402948487..b4744cb72 100644 --- a/raven/context_engine/history/markers.py +++ b/raven/context_engine/history/markers.py @@ -19,7 +19,22 @@ HISTORY_PINNED_KEY = "_history_pinned" """Set to ``True`` on every message of a pinned exchange.""" +HISTORY_COMPACTED_META = "history_compacted" +"""``Segment.meta`` flag: this turn rewrote history, so the tool array may refresh. + +The array is the prompt-cache prefix and is frozen for a session; a compaction +already rebuilds the history half of that prefix, so it is the one turn where +recapturing the array costs nothing extra. The loop reads this key off the +assembled metadata and schedules the session's next-assembly refresh. A +metadata key rather than a message key: it rides the segment, never a message. +""" + HISTORY_PRIVATE_KEYS = frozenset({HISTORY_CHECKPOINT_KEY, HISTORY_PINNED_KEY}) -__all__ = ["HISTORY_CHECKPOINT_KEY", "HISTORY_PINNED_KEY", "HISTORY_PRIVATE_KEYS"] +__all__ = [ + "HISTORY_CHECKPOINT_KEY", + "HISTORY_COMPACTED_META", + "HISTORY_PINNED_KEY", + "HISTORY_PRIVATE_KEYS", +] diff --git a/raven/context_engine/runtime_context.py b/raven/context_engine/runtime_context.py index 247329f5b..39f526efd 100644 --- a/raven/context_engine/runtime_context.py +++ b/raven/context_engine/runtime_context.py @@ -74,6 +74,11 @@ def replayed_content(message: dict[str, Any]) -> Any: MCP_NOTICE_HEADER = "MCP plugin changes since the last note (an earlier note stands until one here replaces it):" """Opens a turn's MCP lines, so a plugin no line names reads as unchanged rather than resolved.""" +TOOL_NOTICE_HEADER = ( + "Tool availability changes since the last note (an earlier note stands until one here replaces it):" +) +"""Opens a turn's tool-availability lines, so a tool no line names reads as unchanged.""" + _MCP_SUBJECT = re.compile(r"MCP plugin '(?P(?:[^'\\]|\\.)*)': ") _LEGACY_MCP_SUBJECT = re.compile(r"MCP plugin '(?P.+?)': ") """The name a line filed before the escaping held: the raw text up to the first ``': ``. @@ -82,7 +87,10 @@ def replayed_content(message: dict[str, Any]) -> Any: which is how a raw name holding a quote or a lone backslash is still recovered. """ +_TOOL_SUBJECT = re.compile(r"Tool '(?P(?:[^'\\]|\\.)*)': ") + _CLEARED = "the earlier note about it no longer applies; this turn's tool definitions show what it offers." +_TOOL_CLEARED = "available again -- the earlier note no longer applies." def mcp_notice(name: str, text: str) -> str: @@ -95,6 +103,17 @@ def mcp_notice(name: str, text: str) -> str: return f"MCP plugin '{quoted}': {text}" +def tool_notice(name: str, text: str) -> str: + """One tool's availability line, keyed by the tool name the same way. + + A tool and an MCP plugin can share a name (``web_search`` is plausible for + both), so the kind is part of the key :func:`notice_key` reads back; the + two lines never replace each other. + """ + quoted = name.replace("\\", "\\\\").replace("'", "\\'") + return f"Tool '{quoted}': {text}" + + def notice_subject(line: str) -> str | None: """The plugin ``line`` speaks of, or ``None`` for a line that names none. @@ -103,11 +122,32 @@ def notice_subject(line: str) -> str | None: to the first ``': ``. The two formats are ambiguous for a raw name holding a backslash: it can look escaped, and the escaped reading wins there. """ + key = _mcp_key(line) + return key[1] if key is not None else None + + +def notice_key(line: str) -> tuple[str, str] | None: + """What ``line`` speaks of: ``("mcp", plugin)``, ``("tool", name)``, or ``None``. + + The kind is in the key so a plugin and a tool of the same name keep their + own notes; a line that names neither (a header, a host notice) is unkeyed and + is sent every turn. + """ + mcp = _mcp_key(line) + if mcp is not None: + return mcp + match = _TOOL_SUBJECT.match(line) + if match is not None and _written_escaped(match["name"]): + return "tool", re.sub(r"\\(.)", r"\1", match["name"]) + return None + + +def _mcp_key(line: str) -> tuple[str, str] | None: match = _MCP_SUBJECT.match(line) if match is not None and _written_escaped(match["name"]): - return re.sub(r"\\(.)", r"\1", match["name"]) + return "mcp", re.sub(r"\\(.)", r"\1", match["name"]) legacy = _LEGACY_MCP_SUBJECT.match(line) - return legacy["name"] if legacy else None + return ("mcp", legacy["name"]) if legacy else None def _written_escaped(name: str) -> bool: @@ -127,41 +167,56 @@ def _written_escaped(name: str) -> bool: return True -def _clears(name: str, line: str) -> bool: - """Whether ``line`` clears ``name``: in the escaped form, or the raw one filed before it.""" +def _clears(key: tuple[str, str], line: str) -> bool: + """Whether ``line`` clears ``key``: in the escaped form, or the raw one filed before it.""" + kind, name = key + if kind == "tool": + return line == tool_notice(name, _TOOL_CLEARED) return line == mcp_notice(name, _CLEARED) or line == f"MCP plugin '{name}': {_CLEARED}" -def told_notices(messages: list[dict[str, Any]]) -> dict[str, str]: - """The MCP lines a model reading ``messages`` holds as current, by plugin. +def _cleared_line(key: tuple[str, str]) -> str: + kind, name = key + return tool_notice(name, _TOOL_CLEARED) if kind == "tool" else mcp_notice(name, _CLEARED) + + +def told_notices(messages: list[dict[str, Any]]) -> dict[tuple[str, str], str]: + """The notes a model reading ``messages`` holds as current, by kind and name. - The runtime-context blocks are read in order: a line sets its plugin's + The runtime-context blocks are read in order: a line sets its subject's note and a cleared line drops it. What a compaction took out of the messages is not read, so it is told again. """ - told: dict[str, str] = {} + told: dict[tuple[str, str], str] = {} for message in messages: for line in _block_lines(message): - name = notice_subject(line) - if name is None: + key = notice_key(line) + if key is None: continue - if _clears(name, line): - told.pop(name, None) + if _clears(key, line): + told.pop(key, None) else: - told[name] = line + told[key] = line return told -def notice_changes(current: list[str], told: dict[str, str]) -> list[str]: - """The tool-notice lines to send: each plugin line unlike ``told``, and every line that names no plugin. +def notice_changes(current: list[str], told: dict[tuple[str, str], str]) -> list[str]: + """The tool-notice lines to send: each subject line unlike ``told``, and every line that names no subject. - A plugin ``told`` holds and ``current`` no longer names gets a cleared line, + A subject ``told`` holds and ``current`` no longer names gets a cleared line, since a missing line now means "unchanged". """ unkeyed, keyed = _split(current) - lines = [line for name, line in keyed.items() if told.get(name) != line] - lines += [mcp_notice(name, _CLEARED) for name in told if name not in keyed] - return [*unkeyed, MCP_NOTICE_HEADER, *lines] if lines else unkeyed + pairs = [(key, line) for key, line in keyed.items() if told.get(key) != line] + pairs += [(key, _cleared_line(key)) for key in told if key not in keyed] + mcp = [line for key, line in pairs if key[0] == "mcp"] + tools = [line for key, line in pairs if key[0] == "tool"] + lines = list(unkeyed) + if mcp: + lines += [MCP_NOTICE_HEADER, *mcp] + if tools: + lines += [TOOL_NOTICE_HEADER, *tools] + return lines def notice_ceiling(current: list[str], session_messages: list[dict[str, Any]]) -> list[str]: @@ -169,12 +224,22 @@ def notice_ceiling(current: list[str], session_messages: list[dict[str, Any]]) - The history a turn replays exists only after the history strategy has budgeted the turn, so the budget is taken over this: all of ``current``, - plus a cleared line for every plugin the session ever noted. + plus a cleared line for every subject the session ever noted. """ unkeyed, keyed = _split(current) - noticed = {name for message in session_messages for line in _block_lines(message) if (name := notice_subject(line))} - lines = [*keyed.values(), *(mcp_notice(name, _CLEARED) for name in sorted(noticed - keyed.keys()))] - return [*unkeyed, MCP_NOTICE_HEADER, *lines] if lines else unkeyed + noticed = { + key for message in session_messages for line in _block_lines(message) if (key := notice_key(line)) is not None + } + pairs = list(keyed.items()) + pairs += [(key, _cleared_line(key)) for key in sorted(noticed - keyed.keys())] + mcp = [line for key, line in pairs if key[0] == "mcp"] + tools = [line for key, line in pairs if key[0] == "tool"] + lines = list(unkeyed) + if mcp: + lines += [MCP_NOTICE_HEADER, *mcp] + if tools: + lines += [TOOL_NOTICE_HEADER, *tools] + return lines def retell_notices(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> list[dict[str, Any]]: @@ -195,7 +260,9 @@ def retell_notices(before: list[dict[str, Any]], after: list[dict[str, Any]]) -> lines = message.get(RUNTIME_CONTEXT_KEY) if message.get("role") != "user" or not isinstance(lines, str) or not lines: continue - told = "\n".join([lines, *(repair[1:] if MCP_NOTICE_HEADER in lines.splitlines() else repair)]) + present = set(lines.splitlines()) + extra = [line for line in repair if line not in (MCP_NOTICE_HEADER, TOOL_NOTICE_HEADER) or line not in present] + told = "\n".join([lines, *extra]) content = _replaced(message.get("content"), lines, told) if content is None: continue @@ -230,15 +297,15 @@ def _replaced(content: Any, lines: str, told: str) -> Any: return [*content[:at], {**content[at], "text": content[at]["text"].replace(lines, told, 1)}, *content[at + 1 :]] -def _split(lines: list[str]) -> tuple[list[str], dict[str, str]]: +def _split(lines: list[str]) -> tuple[list[str], dict[tuple[str, str], str]]: unkeyed: list[str] = [] - keyed: dict[str, str] = {} + keyed: dict[tuple[str, str], str] = {} for line in lines: - name = notice_subject(line) - if name is None: + key = notice_key(line) + if key is None: unkeyed.append(line) else: - keyed[name] = line + keyed[key] = line return unkeyed, keyed diff --git a/raven/context_engine/segments/active_skills.py b/raven/context_engine/segments/active_skills.py index 1f0b3346c..a67011cfd 100644 --- a/raven/context_engine/segments/active_skills.py +++ b/raven/context_engine/segments/active_skills.py @@ -53,7 +53,11 @@ def _require_tools(self, skills: "list[SkillMeta]") -> "list[SkillMeta]": ``tools.disabled_tools``. Unlike ``requires.bins`` / ``requires.env`` (process-static, resolved - in the registry) the tool set is live and hot-appliable, so it is - checked here, per turn, against the definitions actually being sent. + in the registry) the tool set is checked here, per turn, against the + definitions actually being sent. Inside a turn those are the session's + frozen array: a tool a live switch has turned off stays in it and is + reported as unavailable in the runtime context, so its skill stays + injected. The filter still drops a skill for a tool the session never + registered. """ return filter_by_required_tools(skills, render.collect_tool_names(self._get_tool_definitions)) diff --git a/raven/context_engine/segments/render.py b/raven/context_engine/segments/render.py index 5c6d98045..ca3fd8909 100644 --- a/raven/context_engine/segments/render.py +++ b/raven/context_engine/segments/render.py @@ -165,7 +165,12 @@ def _tool_names(get_tool_definitions: Callable[[], list[Any]] | None) -> list[st def live_dispatch_tools(get_tool_definitions: Callable[[], list[Any]] | None) -> tuple[str, ...]: - """Which dispatch paths this turn actually holds. + """Which dispatch paths the agent's tool list advertises. + + The list is the session's frozen array inside a turn, so a tool a live + switch has turned off is still counted here; the runtime context reports it + as unavailable. A charter that narrows one dispatch is likewise not + reflected -- the charter's own prompt carries that restriction. Reads ``_tool_names`` rather than ``collect_tool_names`` because the two questions part company on an empty tool table. For the always-skills filter @@ -189,7 +194,7 @@ def live_dispatch_tools(get_tool_definitions: Callable[[], list[Any]] | None) -> def collect_tool_names(get_tool_definitions: Callable[[], list[Any]] | None) -> list[str] | None: - """Names in the agent's live tool list, or ``None`` when there is nothing to gate on. + """Names in the agent's tool list (the session's frozen array inside a turn). Deliberately lossy: no tool awareness, a lookup that raised, and a successful empty result all read as ``None``, and callers must take that as "do not diff --git a/raven/rpc/methods/reload.py b/raven/rpc/methods/reload.py index c9606fb7b..1ae3d1285 100644 --- a/raven/rpc/methods/reload.py +++ b/raven/rpc/methods/reload.py @@ -28,9 +28,10 @@ from raven.rpc.dispatcher import Dispatcher _CONFIRM_MESSAGE = ( - "/reload-mcp reconnects the MCP servers whose config changed. The tool list " - "is the first thing in the cached prompt prefix, so a change to it rebuilds " - "the whole cache for this conversation. Run '/reload-mcp now' to proceed." + "/reload-mcp reconnects the MCP servers whose config changed. A conversation's " + "tool list is frozen until its next compaction or a new conversation, so an " + "existing session keeps its cached prefix and the reconciled tools join then. " + "Run '/reload-mcp now' to proceed." ) @@ -93,7 +94,11 @@ async def reload_mcp(params: dict, *, agent_loop_factory: Any = None) -> dict: # "reconciled", not "reconnected". The count is records touched -- a detach # counts, and so does an attempt that failed or parked at the browser -- so # naming it a reconnect reported a total outage as a successful reload. - tools = "the tool list changed" if report.tools_changed else "the tool list is unchanged" + tools = ( + "the registered tool set changed; this conversation joins it at the next compaction or new conversation" + if report.tools_changed + else "the registered tool set is unchanged" + ) return { "ok": True, "status": "reloaded", diff --git a/tests/test_agent_knowledge_search.py b/tests/test_agent_knowledge_search.py index 7872f8d55..b6383cd48 100644 --- a/tests/test_agent_knowledge_search.py +++ b/tests/test_agent_knowledge_search.py @@ -491,11 +491,15 @@ async def test_a_turn_offers_the_search_when_its_session_named_a_base(tmp_path: assert "knowledge_search" in provider.offered[0] -async def test_a_turn_whose_session_named_none_is_offered_none(tmp_path: Any) -> None: +async def test_a_turn_whose_session_named_none_advertises_it_as_unavailable(tmp_path: Any) -> None: + """The schema stays in the session's frozen array so the array -- the + prompt-cache prefix -- does not move when a base is attached or detached. + Availability is the runtime context's job: the tool answers calls with a + refusal and the notice says no base is selected.""" provider = await _turn(tmp_path / "ws", []) assert provider.offered, "the turn made no model call" - assert "knowledge_search" not in provider.offered[0] + assert "knowledge_search" in provider.offered[0], "a frozen array keeps the schema" # -- which library the tool searches ------------------------------- diff --git a/tests/test_agent_loop_disabled_tools.py b/tests/test_agent_loop_disabled_tools.py index 5fdcdd56c..e168e6692 100644 --- a/tests/test_agent_loop_disabled_tools.py +++ b/tests/test_agent_loop_disabled_tools.py @@ -45,9 +45,9 @@ def _offered(loop: AgentLoop) -> set[str]: class TestTheFileIsTheAuthority: - """The direction that used to be impossible. Asserted through the assembled - array rather than through ``_withheld_tool_names``, because the array is what a - turn actually sends and the helper is an implementation detail of it.""" + """The direction that used to be impossible. Asserted through the live + array, which is what callers outside a turn see; a session's frozen array is + covered in test_tool_registry_session_snapshot.py.""" def test_a_switch_flipped_after_startup_is_honoured(self, tmp_path: Path, monkeypatch) -> None: cfg = tmp_path / "config.json" diff --git a/tests/test_agent_loop_mcp_sync.py b/tests/test_agent_loop_mcp_sync.py index 13ac05035..ab69edcf4 100644 --- a/tests/test_agent_loop_mcp_sync.py +++ b/tests/test_agent_loop_mcp_sync.py @@ -512,6 +512,106 @@ async def test_the_count_is_what_the_array_carries_not_what_the_server_registere assert all_off._mcp_tool_notices() == [], "a server offering nothing gets no line" +class _StatusManager: + """The manager surface ``_mcp_tool_notices`` reads, with the state handed to it.""" + + def __init__(self, *snaps: dict) -> None: + self._snaps = list(snaps) + + def status(self) -> list[dict]: + return self._snaps + + def servers_offering(self, primitive: str) -> list[str]: + return [] + + +def _snap(name: str, state: str, *, enabled: bool = True) -> dict: + return { + "name": name, + "state": state, + "connected": state == "connected", + "enabled": enabled, + "tool_count": 0, + } + + +async def test_a_server_connected_mid_session_joins_at_the_next_refresh(workspace) -> None: + loop = _loop(workspace) + with loop.tools.session_scope_for("s1"): + loop.tools.get_definitions() + loop.tools.register( + _FakeTool("mcp_svc_search"), origin=MCPToolRef(name="mcp_svc_search", server="svc", tool="search") + ) + loop._mcp_manager = _StatusManager(_snap("svc", "connected")) + notes = loop._mcp_tool_notices() + + assert len(notes) == 1, notes + assert "1 tool(s)" in notes[0] + assert "next compaction or new conversation" in notes[0] + + +async def test_a_server_still_connecting_joins_at_the_next_refresh(workspace) -> None: + loop = _loop(workspace) + with loop.tools.session_scope_for("s1"): + loop.tools.get_definitions() + loop._mcp_manager = _StatusManager(_snap("svc", "connecting")) + notes = loop._mcp_tool_notices() + + assert len(notes) == 1, notes + assert "next compaction or new conversation" in notes[0] + + +async def test_a_disconnected_server_keeps_its_tools_in_the_list(workspace) -> None: + loop = _loop(workspace) + loop.tools.register( + _FakeTool("mcp_svc_search"), origin=MCPToolRef(name="mcp_svc_search", server="svc", tool="search") + ) + with loop.tools.session_scope_for("s1"): + assert "mcp_svc_search" in {d["function"]["name"] for d in loop.tools.get_definitions()} + # The manager unregisters its tools on disconnect. The snapshot's + # origin record is what still knows which server they belonged to. + loop.tools.unregister("mcp_svc_search") + loop._mcp_manager = _StatusManager(_snap("svc", "disconnected")) + notes = loop._mcp_tool_notices() + + assert len(notes) == 1, notes + assert "remain in this conversation's tool list" in notes[0] + + +async def test_a_removed_server_still_gets_a_notice(workspace) -> None: + loop = _loop(workspace) + loop.tools.register( + _FakeTool("mcp_svc_search"), origin=MCPToolRef(name="mcp_svc_search", server="svc", tool="search") + ) + with loop.tools.session_scope_for("s1"): + assert "mcp_svc_search" in {d["function"]["name"] for d in loop.tools.get_definitions()} + loop.tools.unregister("mcp_svc_search") + # A removed server is dropped from the manager entirely: status() has + # no row to hang the disconnected line on. + loop._mcp_manager = _StatusManager() + notes = loop._mcp_tool_notices() + + assert len(notes) == 1, notes + assert "svc" in notes[0] and "no longer loaded" in notes[0] + + +async def test_a_reconnected_server_that_gained_tools_says_they_join_at_the_next_refresh(workspace) -> None: + loop = _loop(workspace) + loop.tools.register( + _FakeTool("mcp_svc_search"), origin=MCPToolRef(name="mcp_svc_search", server="svc", tool="search") + ) + with loop.tools.session_scope_for("s1"): + assert "mcp_svc_search" in {d["function"]["name"] for d in loop.tools.get_definitions()} + loop.tools.register( + _FakeTool("mcp_svc_create"), origin=MCPToolRef(name="mcp_svc_create", server="svc", tool="create") + ) + loop._mcp_manager = _StatusManager(_snap("svc", "connected")) + notes = loop._mcp_tool_notices() + + assert len(notes) == 1, notes + assert "1 new tool(s)" in notes[0] and "next compaction" in notes[0] + + async def test_tool_notices_ride_the_runtime_context_block(workspace) -> None: from datetime import datetime diff --git a/tests/test_agent_loop_tool_array_stability.py b/tests/test_agent_loop_tool_array_stability.py new file mode 100644 index 000000000..beb364b56 --- /dev/null +++ b/tests/test_agent_loop_tool_array_stability.py @@ -0,0 +1,226 @@ +"""A compaction is the one turn allowed to move the session's frozen tool array. + +The array is captured on a session's first assembly and served unchanged until +a refresh point. A compaction is one: the history it budgets is rebuilt, so the +turn already pays for a new prefix and the array can be recaptured with it. An +ordinary turn must not invalidate it -- that would rebuild the prefix every +turn, which is the cost this whole mechanism exists to remove. +""" + +from __future__ import annotations + +import asyncio +import json +from pathlib import Path +from typing import Any + +from raven.agent.loop.main import AgentLoop +from raven.context_engine.history.markers import HISTORY_COMPACTED_META +from raven.contracts.assembled import AssembledContext +from raven.contracts.tool import Tool +from tests._wiring import wire + + +class _StubProvider: + def get_default_model(self) -> str: + return "stub-model" + + async def chat_with_retry(self, **kwargs): # pragma: no cover - never invoked + raise NotImplementedError + + +def _loop(tmp_path: Path) -> AgentLoop: + return AgentLoop(provider=_StubProvider(), workspace=tmp_path / "ws", **wire()) + + +def _assembled(metadata: dict) -> AssembledContext: + return AssembledContext(messages=[{"role": "system", "content": "s"}], metadata=metadata) + + +def _run(loop: AgentLoop, monkeypatch, metadata: dict, calls: list[str], bound: list[tuple]) -> None: + async def assemble(*args, **kwargs): + return _assembled(metadata) + + monkeypatch.setattr(loop.tools, "schedule_definitions_refresh", calls.append) + monkeypatch.setattr(loop.tools, "bind_session_revision", lambda key, log: bound.append((key, log))) + monkeypatch.setattr(loop.harness.memory, "assemble", assemble) + session = loop.sessions.get_or_create("test:c1") + asyncio.run( + loop._assemble_context_messages( + session=session, + session_key="test:c1", + current_message="hi", + ) + ) + + +def test_a_compacted_turn_schedules_the_next_assembly(tmp_path: Path, monkeypatch) -> None: + """The refresh waits for the next assembly so the compaction turn's array, + notices and system-prompt derivations are all the one snapshot it was + budgeted with -- not a new array beside old text.""" + loop = _loop(tmp_path) + calls: list[str] = [] + bound: list[tuple] = [] + + _run(loop, monkeypatch, {HISTORY_COMPACTED_META: True}, calls, bound) + + assert calls == ["test:c1"] + assert bound and bound[0][0] == "test:c1" + + +def test_an_ordinary_turn_keeps_the_snapshot(tmp_path: Path, monkeypatch) -> None: + loop = _loop(tmp_path) + calls: list[str] = [] + bound: list[tuple] = [] + + _run(loop, monkeypatch, {HISTORY_COMPACTED_META: False}, calls, bound) + + assert calls == [] + assert bound and bound[0][0] == "test:c1" + + +# --------------------------------------------------------------------------- +# Acceptance: a real turn, recorded from the provider's side +# --------------------------------------------------------------------------- + + +class _RecordingProvider: + """Records the messages and tools of every model call, then says nothing.""" + + api_key = "test" + + def __init__(self) -> None: + self.messages: list[list[dict]] = [] + self.tools: list[list[dict]] = [] + + async def chat(self, messages, tools=None, **kwargs): + from raven.providers.base import LLMResponse + + self.messages.append(list(messages)) + self.tools.append(list(tools or [])) + return LLMResponse(content="done", tool_calls=[]) + + async def chat_with_retry(self, **kwargs): + return await self.chat(kwargs.get("messages"), kwargs.get("tools")) + + def get_default_model(self) -> str: + return "stub" + + def classify_error(self, exc: BaseException): + raise exc + + +class _LateTool(Tool): + def __init__(self) -> None: + pass + + @property + def name(self) -> str: + return "late_tool" + + @property + def description(self) -> str: + return "registered after the session's array was captured" + + @property + def parameters(self) -> dict[str, Any]: + return {"type": "object", "properties": {}} + + async def execute(self, **kwargs: Any) -> str: + return "ran" + + +async def _nowhere(*args: Any, **kwargs: Any) -> None: + return None + + +def _request(): + from raven.spine.message import ChatType, Source + from raven.spine.turn import Origin, TurnRequest + + return TurnRequest( + origin=Origin.USER, + source=Source(channel="tui", chat_id="chat1", sender_id="user", chat_type=ChatType.DM), + text="hi", + ) + + +def _turns(tmp_path: Path, provider: _RecordingProvider) -> AgentLoop: + return AgentLoop(provider=provider, workspace=tmp_path / "ws", **wire(max_iterations=1)) + + +def _text(message: dict) -> str: + content = message.get("content") + if isinstance(content, str): + return content + return "\n".join(block.get("text", "") for block in content or [] if isinstance(block, dict)) + + +def _names(tools: list[dict]) -> set[str]: + return {d["function"]["name"] for d in tools} + + +def test_a_live_switch_does_not_move_the_array_and_the_next_turn_says_why(tmp_path: Path, monkeypatch) -> None: + cfg = tmp_path / "config.json" + cfg.write_text(json.dumps({"tools": {"disabledTools": []}}), encoding="utf-8") + monkeypatch.setattr("raven.home._current_config_path", cfg) + provider = _RecordingProvider() + loop = _turns(tmp_path, provider) + + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + cfg.write_text(json.dumps({"tools": {"disabledTools": ["grep"]}}), encoding="utf-8") + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + + assert len(provider.tools) == 2, "one model call per turn" + assert provider.tools[0] == provider.tools[1], "the array is the prefix; a switch must not move it" + assert "grep" in _names(provider.tools[1]) + assert "Tool 'grep': currently unavailable" in _text(provider.messages[1][-1]) + + +def test_a_compaction_schedules_the_next_turns_refresh(tmp_path: Path, monkeypatch) -> None: + cfg = tmp_path / "config.json" + cfg.write_text(json.dumps({"tools": {}}), encoding="utf-8") + monkeypatch.setattr("raven.home._current_config_path", cfg) + provider = _RecordingProvider() + loop = _turns(tmp_path, provider) + + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + loop.tools.register(_LateTool()) + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + assert "late_tool" not in _names(provider.tools[1]), "an ordinary turn keeps the captured array" + + real = loop.harness.memory.assemble + compacting = {"on": True} + + async def marked(*args, **kwargs): + assembled = await real(*args, **kwargs) + if compacting["on"]: + assembled.metadata[HISTORY_COMPACTED_META] = True + compacting["on"] = False + return assembled + + monkeypatch.setattr(loop.harness.memory, "assemble", marked) + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + assert "late_tool" not in _names(provider.tools[2]), ( + "the compaction turn stays coherent: array, notices and system prompt are the same snapshot" + ) + + asyncio.run(loop.run_turn(_request(), _nowhere, lambda: [], stream=False)) + assert "late_tool" in _names(provider.tools[3]), "the next assembly recaptures the array" + + +def test_deleting_a_session_releases_its_frozen_array(tmp_path: Path) -> None: + """A deleted session's snapshot is released with its binding, so a later + session reusing the key captures the registry as it is then -- and an + active session's snapshot is never dropped to make room for another.""" + loop = _loop(tmp_path) + + with loop.tools.session_scope_for("test:c1"): + assert "late_tool" not in {d["function"]["name"] for d in loop.tools.get_definitions()} + loop.tools.register(_LateTool()) + assert "late_tool" not in {d["function"]["name"] for d in loop.tools.get_definitions()} + + loop.clear_session_binding("test:c1") + + with loop.tools.session_scope_for("test:c1"): + assert "late_tool" in {d["function"]["name"] for d in loop.tools.get_definitions()} diff --git a/tests/test_agent_loop_tool_notices.py b/tests/test_agent_loop_tool_notices.py new file mode 100644 index 000000000..0b63196b7 --- /dev/null +++ b/tests/test_agent_loop_tool_notices.py @@ -0,0 +1,114 @@ +"""A live off switch changes availability, never the array; the runtime context says which. + +The array is the prompt-cache prefix and is frozen for the session by +``ToolRegistry``. This file pins the loop's half: the reasons it can name, the +notices it sends, and the refusal a call gets when the schema is visible but the +switch is off. +""" + +from __future__ import annotations + +import asyncio +import json +from pathlib import Path + +import pytest + +from raven.agent.loop.main import AgentLoop +from raven.context_engine.runtime_context import notice_key +from tests._wiring import wire + + +class _StubProvider: + """Construction reads the default model; no turn is run here.""" + + def get_default_model(self) -> str: + return "stub-model" + + async def chat_with_retry(self, **kwargs): # pragma: no cover - never invoked + raise NotImplementedError + + +def _loop(tmp_path: Path, **kwargs) -> AgentLoop: + return AgentLoop(provider=_StubProvider(), workspace=tmp_path / "ws", **wire(**kwargs)) + + +def _write_switches(path: Path, names: list[str]) -> None: + path.write_text(json.dumps({"tools": {"disabledTools": names}}), encoding="utf-8") + + +@pytest.fixture(autouse=True) +def _no_ambient_search_key(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.delenv("SERPER_API_KEY", raising=False) + + +def test_a_live_disabled_tool_keeps_its_schema_and_gets_a_notice(tmp_path: Path, monkeypatch) -> None: + cfg = tmp_path / "config.json" + _write_switches(cfg, ["grep"]) + monkeypatch.setattr("raven.home._current_config_path", cfg) + loop = _loop(tmp_path) + + with loop.tools.session_scope_for("s1"): + names = {d["function"]["name"] for d in loop.tools.get_definitions()} + assert "grep" in names, "the array is the prefix; a switch must not move it" + assert not loop.tools.offers_by_name("grep") + notes = loop._tool_notices() + + by_key = {notice_key(note): note for note in notes} + assert ("tool", "grep") in by_key, notes + assert "switched off in settings" in by_key[("tool", "grep")] + + +def test_an_unconfigured_tool_says_why_it_cannot_run(tmp_path: Path, monkeypatch) -> None: + monkeypatch.setattr("raven.home._current_config_path", tmp_path / "absent.json") + loop = _loop(tmp_path) + + with loop.tools.session_scope_for("s1"): + loop.tools.get_definitions() + notes = loop._tool_notices() + + by_key = {notice_key(note): note for note in notes} + assert ("tool", "web_search") in by_key, notes + assert "no search key" in by_key[("tool", "web_search")] + assert ("tool", "knowledge_search") in by_key, notes + assert "no knowledge base is selected" in by_key[("tool", "knowledge_search")] + + +def test_a_constructor_disabled_tool_stays_out_and_gets_no_notice(tmp_path: Path, monkeypatch) -> None: + monkeypatch.setattr("raven.home._current_config_path", tmp_path / "absent.json") + loop = _loop(tmp_path, disabled_tools=["grep"]) + + with loop.tools.session_scope_for("s1"): + names = {d["function"]["name"] for d in loop.tools.get_definitions()} + assert "grep" not in names, "the eval harness subset never enters the snapshot" + notes = loop._tool_notices() + + assert not any(notice_key(note) == ("tool", "grep") for note in notes) + + +def test_an_unavailable_tool_call_is_refused_with_the_reason(tmp_path: Path, monkeypatch) -> None: + cfg = tmp_path / "config.json" + _write_switches(cfg, ["grep"]) + monkeypatch.setattr("raven.home._current_config_path", cfg) + loop = _loop(tmp_path) + + with loop.tools.session_scope_for("s1"): + loop.tools.get_definitions() + answer = asyncio.run(loop.tools.execute("grep", {})) + + assert "currently unavailable" in answer + assert "switched off in settings" in answer + assert "not available" not in answer, "an advertised tool is not 'absent'" + + +def test_a_charter_restriction_is_not_reported_as_a_settings_switch(tmp_path: Path, monkeypatch) -> None: + from raven.agent.subagent.charter import Charter, charter_scope + + monkeypatch.setattr("raven.home._current_config_path", tmp_path / "absent.json") + loop = _loop(tmp_path) + with loop.tools.session_scope_for("s1"): + loop.tools.get_definitions() + with charter_scope(Charter(tools=("grep",))): + notes = loop._tool_notices() + + assert not any(notice_key(note) == ("tool", "exec") for note in notes), notes diff --git a/tests/test_agent_loop_web_tools.py b/tests/test_agent_loop_web_tools.py index cb59cae6e..b930aca4f 100644 --- a/tests/test_agent_loop_web_tools.py +++ b/tests/test_agent_loop_web_tools.py @@ -558,11 +558,11 @@ def write(enabled): tool = loop.tools.get("image_generate") for enabled in [initially_enabled, not initially_enabled, initially_enabled]: write(enabled) - assert ("image_generate" not in loop._unconfigured_tool_names()) is enabled + assert ("image_generate" not in loop._unconfigured_tool_reasons()) is enabled assert tool._config.api_key == ("host-key" if enabled else "") assert tool._config.model == ("openai/gpt-image-2" if enabled else "") host.write_text(json.dumps({"tools": {}})) - assert "image_generate" in loop._unconfigured_tool_names() + assert "image_generate" in loop._unconfigured_tool_reasons() assert not tool._config.api_key diff --git a/tests/test_context_compacting_runtime.py b/tests/test_context_compacting_runtime.py index 4cfa18156..89ea45c3d 100644 --- a/tests/test_context_compacting_runtime.py +++ b/tests/test_context_compacting_runtime.py @@ -31,7 +31,12 @@ from raven.context_engine import headroom from raven.context_engine.history.compacting import CompactingHistoryBuilder from raven.context_engine.history.compacting.store import CHECKPOINT_DIR, STATE_FILE, CheckpointStore -from raven.context_engine.history.markers import HISTORY_CHECKPOINT_KEY, HISTORY_PINNED_KEY, HISTORY_PRIVATE_KEYS +from raven.context_engine.history.markers import ( + HISTORY_CHECKPOINT_KEY, + HISTORY_COMPACTED_META, + HISTORY_PINNED_KEY, + HISTORY_PRIVATE_KEYS, +) from raven.context_engine.history_trimmer import HistoryTrimmer from raven.contracts.assembled import TokenBudget from raven.contracts.context import AssembledPrefix, AssemblyContext, SessionRevision @@ -273,6 +278,7 @@ async def test_a_prompt_over_the_line_comes_back_under_target(self, tmp_path: Pa segment = await _builder(tmp_path).build(_ctx(_session(80))) meta = segment.meta assert meta["compaction_action"] == "compact" + assert meta[HISTORY_COMPACTED_META] is True assert meta["prompt_tokens"] > meta["trigger_tokens"] assert meta["history_tokens"] <= meta["target_tokens"] assert meta["history_kept"] < meta["history_total"] @@ -318,6 +324,8 @@ async def test_replaying_a_compacted_session_does_not_compact_it_again(self, tmp first = await builder.build(_ctx(session)) second = await builder.build(_ctx(session)) assert (first.meta["compaction_action"], second.meta["compaction_action"]) == ("compact", "pass") + assert first.meta[HISTORY_COMPACTED_META] is True + assert second.meta[HISTORY_COMPACTED_META] is False assert second.meta["compaction_generation"] == 1 assert second.history == first.history diff --git a/tests/test_context_runtime_context.py b/tests/test_context_runtime_context.py index bd568b2f6..ac5e19ee6 100644 --- a/tests/test_context_runtime_context.py +++ b/tests/test_context_runtime_context.py @@ -296,6 +296,7 @@ def test_a_filed_message_costs_what_its_replay_costs(self) -> None: _HEADER = "MCP plugin changes since the last note (an earlier note stands until one here replaces it):" +TOOL_HEADER = "Tool availability changes since the last note (an earlier note stands until one here replaces it):" _AUTH = "MCP plugin 'github': installed, awaiting authorization." _CONNECTING = "MCP plugin 'notion': installed, still connecting." _FOLDED = "MCP plugin 'notion': connected, offering 3 tool(s)." @@ -610,7 +611,7 @@ def test_a_question_behind_a_recovery_notice_gets_the_note_in_its_own_block(self assert block["text"] == kept[RUNTIME_CONTEXT_KEY] assert block["text"].endswith(f"{_HEADER}\n{_AUTH}") assert rest == [self._IMAGE, {"type": "text", "text": "look"}] - assert told_notices([kept]) == {"github": _AUTH} + assert told_notices([kept]) == {("mcp", "github"): _AUTH} def test_a_note_the_question_changed_behind_a_recovery_notice_is_not_put_back(self) -> None: """The question's own block is read wherever it sits, so a reclaim does @@ -624,7 +625,7 @@ def test_a_note_the_question_changed_behind_a_recovery_notice_is_not_put_back(se [kept] = retell_notices([older, question], [question]) assert kept["content"] == question["content"] - assert told_notices([kept]) == {"notion": _FOLDED} + assert told_notices([kept]) == {("mcp", "notion"): _FOLDED} @pytest.mark.parametrize("words", ["q1", [{"type": "text", "text": "q1"}]], ids=["string", "block-list"]) def test_a_recorded_block_the_content_no_longer_holds_is_neither_read_nor_retold(self, words: Any) -> None: @@ -737,7 +738,7 @@ def test_two_plugins_whose_names_share_a_prefix_keep_their_own_lines(self) -> No def test_a_cleared_name_with_a_quote_is_read_as_cleared(self) -> None: from raven.context_engine.runtime_context import mcp_notice, notice_changes, told_notices - told = {"a': b": mcp_notice("a': b", "still connecting.")} + told = {("mcp", "a': b"): mcp_notice("a': b", "still connecting.")} [_, cleared] = notice_changes([], told) replay = {"role": "user", "content": with_runtime_context(f"{_TAG}\n{_HEADER}\n{cleared}", "q")} @@ -772,7 +773,7 @@ def test_a_note_filed_before_the_escaping_keys_its_plugin(self) -> None: legacy = "MCP plugin 'a'b': installed, still connecting." replay = {"role": "user", "content": with_runtime_context(f"{_TAG}\n{_HEADER}\n{legacy}", "q")} - assert told_notices([replay]) == {"a'b": legacy} + assert told_notices([replay]) == {("mcp", "a'b"): legacy} def test_a_cleared_line_filed_before_the_escaping_still_clears(self) -> None: """The line that clears a plugin was written raw too; it has to be read as @@ -784,3 +785,34 @@ def test_a_cleared_line_filed_before_the_escaping_still_clears(self) -> None: replay = {"role": "user", "content": with_runtime_context(f"{_TAG}\n{_HEADER}\n{noted}\n{legacy}", "q")} assert told_notices([replay]) == {} + + def test_a_tool_line_keys_itself(self) -> None: + from raven.context_engine.runtime_context import notice_key, tool_notice + + assert notice_key(tool_notice("web_search", "currently unavailable.")) == ("tool", "web_search") + + def test_a_tool_and_a_plugin_with_the_same_name_keep_their_own_lines(self) -> None: + from raven.context_engine.runtime_context import mcp_notice, notice_changes, tool_notice + + plugin = mcp_notice("web_search", "still connecting.") + tool = tool_notice("web_search", "currently unavailable.") + + assert notice_changes([plugin, tool], {}) == [_HEADER, plugin, TOOL_HEADER, tool] + + def test_an_unchanged_tool_line_is_not_resent(self) -> None: + from raven.context_engine.runtime_context import notice_changes, told_notices, tool_notice + + line = tool_notice("web_search", "currently unavailable.") + replay = {"role": "user", "content": with_runtime_context(f"{_TAG}\n{TOOL_HEADER}\n{line}", "q")} + + assert notice_changes([line], told_notices([replay])) == [] + + def test_a_tool_that_returns_gets_a_cleared_line(self) -> None: + from raven.context_engine.runtime_context import notice_changes, notice_key, tool_notice + + told = {("tool", "web_search"): tool_notice("web_search", "currently unavailable.")} + [header, cleared] = notice_changes([], told) + + assert header == TOOL_HEADER + assert notice_key(cleared) == ("tool", "web_search") + assert "available again" in cleared diff --git a/tests/test_harness_modules.py b/tests/test_harness_modules.py index 28e3f306a..2d5910eb8 100644 --- a/tests/test_harness_modules.py +++ b/tests/test_harness_modules.py @@ -585,7 +585,7 @@ def test_a_proactive_summary_tells_again_the_note_it_took_away(): "fixture must have the summary replace the note's carrier, not tail or protect it" ) assert messages == before, "the list handed in is the turn's own record, not the summary's to edit" - assert told_notices(result.messages) == {"github": _AUTH} + assert told_notices(result.messages) == {("mcp", "github"): _AUTH} [repaired] = [m for m in result.messages if m.get(RUNTIME_CONTEXT_KEY)] assert repaired["content"].split("\n\n", 1)[0] == repaired[RUNTIME_CONTEXT_KEY] assert repaired[RUNTIME_CONTEXT_KEY].splitlines().count(MCP_NOTICE_HEADER) == 1 @@ -606,7 +606,7 @@ def test_an_overflow_head_summary_tells_again_the_note_it_took_away(): assert provider.calls == 1, "nothing is elidable in this fixture, so the summary is the answer" assert result.changed and state.compress_retries == 1 and state.reactive_summary_tried - assert told_notices(result.messages) == {"github": _AUTH} + assert told_notices(result.messages) == {("mcp", "github"): _AUTH} _CLEARED = "the earlier note about it no longer applies; this turn's tool definitions show what it offers." @@ -630,7 +630,7 @@ def test_the_newest_note_state_is_what_comes_back(): result = asyncio.run(memory.shrink(messages, pressure=WindowPressure.PROACTIVE, state=state, model="m")) assert provider.calls == 1 and result.changed - assert told_notices(result.messages) == {_QUOTED_NAME: _QUOTED, "slides": _SLIDES_CONNECTED} + assert told_notices(result.messages) == {("mcp", _QUOTED_NAME): _QUOTED, ("mcp", "slides"): _SLIDES_CONNECTED} assert not any(_AUTH in str(m.get("content")) for m in result.messages), "a cleared note must not come back" @@ -649,7 +649,7 @@ def test_a_note_the_question_already_carries_is_not_told_twice(): assert provider.calls == 1 and result.changed assert result.messages[-1] is question, "nothing was lost, so nothing was rewritten" - assert told_notices(result.messages) == {"github": _AUTH} + assert told_notices(result.messages) == {("mcp", "github"): _AUTH} assert question["content"].split("\n\n", 1)[0].splitlines().count(MCP_NOTICE_HEADER) == 1 @@ -665,7 +665,7 @@ def test_consecutive_summaries_do_not_stack_the_notes(): first = asyncio.run( memory.shrink(_pressured_turn(_question(), block), pressure=WindowPressure.PROACTIVE, state=state, model="m") ) - assert first.changed and told_notices(first.messages) == {"github": _AUTH} + assert first.changed and told_notices(first.messages) == {("mcp", "github"): _AUTH} call = {"role": "assistant", "content": "", "tool_calls": [{"id": "c1", "type": "function"}]} result_msg = {"role": "tool", "tool_call_id": "c1", "content": "done"} @@ -684,7 +684,7 @@ def test_consecutive_summaries_do_not_stack_the_notes(): [repaired] = [m for m in second.messages if m.get(RUNTIME_CONTEXT_KEY)] block_lines = repaired["content"].split("\n\n", 1)[0].splitlines() assert block_lines.count(MCP_NOTICE_HEADER) == 1 and block_lines.count(_AUTH) == 1 - assert told_notices(second.messages) == {"github": _AUTH} + assert told_notices(second.messages) == {("mcp", "github"): _AUTH} def test_a_multimodal_question_gets_the_note_in_its_first_block(): @@ -720,7 +720,7 @@ def test_a_multimodal_question_gets_the_note_in_its_first_block(): assert repaired["content"][0]["text"].endswith(_AUTH) assert repaired["content"][1:] == [{"type": "text", "text": "look at this"}] assert result.messages[-2:] == [call, result_msg] - assert told_notices(result.messages) == {"github": _AUTH} + assert told_notices(result.messages) == {("mcp", "github"): _AUTH} async def _raising_chat(**_kwargs): @@ -742,7 +742,7 @@ def test_a_failed_summary_leaves_the_transcript_alone(): assert result.messages is messages and not result.changed assert state.compress_retries == 1 and state.head_summary_failures == 1 - assert told_notices(messages) == {"github": _AUTH}, "nothing was taken away, so nothing needed retelling" + assert told_notices(messages) == {("mcp", "github"): _AUTH}, "nothing was taken away, so nothing needed retelling" def test_a_skipped_summary_leaves_the_transcript_alone(): @@ -762,7 +762,7 @@ def test_a_skipped_summary_leaves_the_transcript_alone(): assert result.messages is messages and not result.changed and provider.calls == 0 assert state.compress_retries == 0 - assert told_notices(messages) == {"github": _AUTH} + assert told_notices(messages) == {("mcp", "github"): _AUTH} def test_compaction_disabled_leaves_the_transcript_alone(): @@ -786,7 +786,7 @@ def test_compaction_disabled_leaves_the_transcript_alone(): result = asyncio.run(memory.shrink(messages, pressure=WindowPressure.PROACTIVE, state=state, model="m")) assert result.messages is messages and not result.changed and provider.calls == 0 - assert told_notices(messages) == {"github": _AUTH} + assert told_notices(messages) == {("mcp", "github"): _AUTH} def test_pruning_tool_results_alone_touches_no_notice_blocks(): @@ -823,7 +823,7 @@ def test_pruning_tool_results_alone_touches_no_notice_blocks(): carrier = next(m for m in result.messages if "older work" in str(m.get("content"))) assert carrier is messages[1], "a user message is never the pruner's to edit" assert result.messages[-1] is question and MCP_NOTICE_HEADER not in str(question["content"]) - assert told_notices(result.messages) == {"github": _AUTH} + assert told_notices(result.messages) == {("mcp", "github"): _AUTH} def test_a_summary_never_takes_the_question_out_of_the_turn(): @@ -848,4 +848,4 @@ def test_a_summary_never_takes_the_question_out_of_the_turn(): m.get("role") == "user" and without_runtime_context(m) == without_runtime_context(question) for m in result.messages ), "the turn's question may not be summarized away" - assert told_notices(result.messages) == {"github": _AUTH}, "the note the summary took away is told again" + assert told_notices(result.messages) == {("mcp", "github"): _AUTH}, "the note the summary took away is told again" diff --git a/tests/test_plughub_tool.py b/tests/test_plughub_tool.py index f3b703e98..6014e3ec3 100644 --- a/tests/test_plughub_tool.py +++ b/tests/test_plughub_tool.py @@ -427,9 +427,9 @@ def _offered(reg: ToolRegistry) -> set[str]: @pytest.mark.parametrize("action", ["connect", "authorize"]) async def test_the_tools_a_call_connects_are_usable_in_the_same_turn(_isolated, monkeypatch, action) -> None: - """The result says "from the next step on", and the turn freeze used to make - that false: the agent saw the tools named and could not call them until the - user sent another message.""" + """The session's schema array is frozen, so a newly connected plugin's tools + join it at the next refresh. They are usable now through ``tool_call``, and + the result says exactly that -- not "from the next step on".""" _patch_catalog(monkeypatch, _entry("none")) if action == "authorize": _isolated["cfg_path"].write_text( @@ -440,12 +440,14 @@ async def test_the_tools_a_call_connects_are_usable_in_the_same_turn(_isolated, tool = PluginTool(loop=loop, registry=reg) reg.register(tool) - with reg.turn_scope(): + with reg.session_scope_for("s1"), reg.turn_scope(): + reg.get_definitions() # the session's array, captured before the connect reg.register(_Named("mcp_svc_a")) assert "mcp_svc_a" not in _offered(reg) out = await reg.execute("plugin", {"action": action, "name": "svc"}) assert "mcp_svc_a" in out - assert "mcp_svc_a" in _offered(reg) + assert "next compaction or new conversation" in out + assert "mcp_svc_a" not in _offered(reg), "the frozen array does not move mid-session" assert await reg.execute("mcp_svc_a", {}) == "ran" diff --git a/tests/test_read_file_image.py b/tests/test_read_file_image.py index ff0ac2ea2..29c4e5387 100644 --- a/tests/test_read_file_image.py +++ b/tests/test_read_file_image.py @@ -1514,6 +1514,7 @@ class _Stop(Exception): engine = _Engine() loop.context_engine = engine loop.harness = SimpleNamespace(memory=engine) + loop.tools = SimpleNamespace(bind_session_revision=lambda *a: None) monkeypatch.setattr(AgentLoop, "_context_messages_for_session", lambda self, s: []) monkeypatch.setattr(AgentLoop, "_make_token_budget", lambda self, s=None: None) loop._last_injected_skill_ids = None @@ -1556,6 +1557,7 @@ async def assemble(self, session_key, session_messages, budget, *, turn): engine = _Engine() loop.context_engine = engine loop.harness = SimpleNamespace(memory=engine) + loop.tools = SimpleNamespace(bind_session_revision=lambda *a: None) monkeypatch.setattr(AgentLoop, "_context_messages_for_session", lambda self, s: []) monkeypatch.setattr(AgentLoop, "_make_token_budget", lambda self, s=None: None) loop._last_injected_skill_ids = None diff --git a/tests/test_tool_registry_session_snapshot.py b/tests/test_tool_registry_session_snapshot.py new file mode 100644 index 000000000..d2040d2c3 --- /dev/null +++ b/tests/test_tool_registry_session_snapshot.py @@ -0,0 +1,240 @@ +"""The tool array is frozen for a session and recomputed only at a refresh point. + +The array is the prompt-cache prefix, so a live availability switch must not +move it. Inside ``session_scope_for`` the registry serves the snapshot it took +at the session's first assembly; outside one (a sub-agent, a test) +it keeps the live view. Refresh points are a new session, a ``log_id`` change +(``/clear``), an explicit invalidation (compaction), and a release. + +What a snapshot includes is the *registered* set, not the offered set: a tool a +live switch has withheld is still in it, so flipping the switch either way +mid-session only changes whether calls run, never the array. The constructor's +hard subset is the exception -- it cannot change for the life of the process, +so keeping it out costs no cache and preserves the eval-harness contract. +""" + +from __future__ import annotations + +from typing import Any + +from raven.agent.tools.registry import ToolRegistry +from raven.contracts.tool import Tool + + +class _Stub(Tool): + def __init__(self, name: str) -> None: + self._name = name + + @property + def name(self) -> str: + return self._name + + @property + def description(self) -> str: + return "stub" + + @property + def parameters(self) -> dict[str, Any]: + return {"type": "object", "properties": {}} + + async def execute(self, **kwargs: Any) -> str: + return "ran" + + +def _registry(*names: str) -> ToolRegistry: + reg = ToolRegistry() + for name in names: + reg.register(_Stub(name)) + return reg + + +def _defs(reg: ToolRegistry) -> list[str]: + return [d["function"]["name"] for d in reg.get_definitions()] + + +def test_the_array_does_not_move_when_the_switch_flips_mid_session() -> None: + switches: set[str] = set() + reg = _registry("exec", "grep") + reg.set_withheld_source(lambda: frozenset(switches)) + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "grep"] + switches.add("grep") + assert _defs(reg) == ["exec", "grep"] + switches.discard("grep") + assert _defs(reg) == ["exec", "grep"] + switches.add("grep") + assert _defs(reg) == ["exec", "grep"] + + assert _defs(reg) == ["exec"] + + +def test_outside_a_session_the_live_switch_still_filters() -> None: + reg = _registry("exec", "grep") + reg.set_withheld_source(lambda: frozenset({"grep"})) + + assert _defs(reg) == ["exec"] + + +def test_a_hard_withheld_name_never_enters_the_snapshot() -> None: + reg = _registry("exec", "grep") + reg.set_hard_withheld_source(lambda: frozenset({"exec"})) + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["grep"] + + +def test_a_schema_hidden_tool_never_enters_the_snapshot() -> None: + reg = _registry("exec", "grep") + reg.hide_from_schema("exec") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["grep"] + + +def test_invalidating_recaptures_late_registrations() -> None: + reg = _registry("exec") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec"] + reg.register(_Stub("find")) + assert _defs(reg) == ["exec"] + + reg.invalidate_session_definitions("s1") + + assert _defs(reg) == ["exec", "find"] + + +def test_releasing_the_session_drops_the_snapshot() -> None: + reg = _registry("exec") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec"] + reg.register(_Stub("find")) + assert _defs(reg) == ["exec"] + + reg.release_session_tools("s1") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "find"] + + +def test_a_new_log_id_refreshes_the_snapshot() -> None: + reg = _registry("exec") + reg.bind_session_revision("s1", "log-a") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec"] + reg.register(_Stub("find")) + assert _defs(reg) == ["exec"] + + reg.bind_session_revision("s1", "log-b") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "find"] + + +def test_unavailable_reason_reads_back_the_source() -> None: + reg = _registry("exec", "grep") + reg.set_withheld_source(lambda: frozenset({"exec"})) + reg.set_withheld_reason_source(lambda: {"exec": "switched off in settings"}) + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "grep"] + assert reg.unavailable_reason("exec") == "switched off in settings" + assert reg.unavailable_reason("grep") is None + assert reg.unavailable_reason("missing") is None + + +def test_session_definition_names_are_the_snapshot_not_the_offered_set() -> None: + reg = _registry("exec", "grep") + reg.set_withheld_source(lambda: frozenset({"grep"})) + + with reg.session_scope_for("s1"): + assert reg.session_definition_names() == frozenset({"exec", "grep"}) + + +def test_a_charter_withheld_tool_has_no_settings_reason() -> None: + """A charter narrows one dispatch; it is not the operator switching a tool + off. The refusal still happens through ``offers``, but the reason source + must not invent a settings fact for it.""" + from raven.agent.subagent.charter import Charter, charter_scope + + reg = _registry("exec", "grep") + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "grep"] + with charter_scope(Charter(tools=("grep",))): + assert reg.unavailable_reason("exec") is None + assert reg.unavailable_reason("grep") is None + + +def test_scheduling_a_refresh_waits_for_the_next_assembly() -> None: + """A compaction turn keeps the array it was budgeted with; the next + assembly recaptures, so the array, the notices and the system-prompt + derivations all come from one snapshot.""" + reg = _registry("exec") + reg.bind_session_revision("s1", "log-a") + + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec"] + reg.register(_Stub("find")) + reg.schedule_definitions_refresh("s1") + assert _defs(reg) == ["exec"] + + reg.bind_session_revision("s1", "log-a") + + with reg.session_scope_for("s1"): + assert set(_defs(reg)) == {"exec", "find"} + + +def test_two_sessions_keep_their_own_arrays() -> None: + """One process-wide registry serves concurrent sessions; a snapshot belongs + to the key it was captured under, and a later registration is not backfilled + into an older session.""" + reg = _registry("exec") + + with reg.session_scope_for("a"): + assert _defs(reg) == ["exec"] + + reg.register(_Stub("find")) + + with reg.session_scope_for("b"): + assert set(_defs(reg)) == {"exec", "find"} + with reg.session_scope_for("a"): + assert _defs(reg) == ["exec"] + + +def test_a_charter_narrows_the_array_before_it_is_served() -> None: + """A charter is a per-dispatch security narrowing, not a session + availability switch: a maker turn must not see a writing tool at all. It is + applied on read, over the frozen registered set.""" + from raven.agent.subagent.charter import Charter, charter_scope + + reg = _registry("exec", "grep") + with reg.session_scope_for("s1"): + assert _defs(reg) == ["exec", "grep"] + with charter_scope(Charter(tools=("grep",))): + assert _defs(reg) == ["grep"] + assert _defs(reg) == ["exec", "grep"] + + +def test_the_array_survives_more_sessions_than_the_old_cache_limit() -> None: + """A live session's snapshot must not be evicted to make room for another + session: a gateway can serve more than 64 conversations, and an eviction + silently recaptures the array on that session's next ordinary turn.""" + reg = _registry("base") + reg.bind_session_revision("s0", "log") + + with reg.session_scope_for("s0"): + assert _defs(reg) == ["base"] + + for i in range(64): + key = f"s{i + 1}" + reg.bind_session_revision(key, "log") + with reg.session_scope_for(key): + _defs(reg) + + reg.register(_Stub("late")) + + with reg.session_scope_for("s0"): + assert _defs(reg) == ["base"]