Skip to content

feat(*): freeze the tool array per session and report availability - #1373

Open
LivXue wants to merge 3 commits into
mainfrom
feat/session_tool_array_snapshot
Open

LivXue wants to merge 3 commits into
mainfrom
feat/session_tool_array_snapshot

Conversation

@LivXue

@LivXue LivXue commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Summary

The provider tool array is the prompt-cache prefix, so a live availability
switch must not move it. A session now captures its array on its first
assembly and serves it byte-identically until a refresh point: a new
session, a context compaction (cashed by the next assembly), a /clear, or
a release. tools.disabledTools, a missing credential, and a selected
knowledge base change availability instead, reported in the runtime context
as keyed deltas; a call to an advertised-but-withheld tool is refused with
the reason.

MCP tools follow the same contract: a server that connects mid-session is
reported as joining at the next refresh, and one that disconnects or is
removed keeps its schemas and reports that calls fail. A compaction marks
the session for a refresh at the next assembly, so that turn's array,
notices, and system-prompt derivations all come from one snapshot. A charter
still narrows the array on read as a per-dispatch security boundary; dynamic
schemas keep re-rendering as before. The constructor's disabled_tools
stays a hard subset and never enters the snapshot.

Type

  • Feature

Verification

  • Relevant tests pass locally
  • Relevant lint / type checks pass locally
  • User-facing docs or screenshots are updated when needed

uv run --frozen --all-extras pytest on the 19 affected files (Python
3.12): 842 passed, 1 skipped.

Full suite with the 15 pre-existing environment failures deselected
(reproduced on the base commit b73df6d): two runs, 40856 and 40857
passed; the only failures were three different load-sensitive timing tests,
each passing in isolation (node stderr replay, litellm cold cache,
tool-registry event-loop timing).

make check-commits, make check-source-language, and
make check-large-files: clean.

Risk

  • Security impact considered
  • Backward compatibility considered
  • Rollback path is clear for risky changes

Security: a charter narrows the frozen array on read, so a maker turn still
cannot see a writing tool; a test pins it. Tool and server names in notices
are escaped. Cross-session isolation is pinned by a test.

Compatibility: a deploy that expected tools.disabledTools to remove the
schema now keeps the schema and gets a refusal with the reason; the runtime
context names the switch. MCP tools that connect mid-session join at the
next compaction or new conversation, reachable meanwhile through
tool_call.

Release: a snapshot now lives until the session is released (ACP close or
session delete), invalidated by a compaction, or its log id changes. The
registry no longer evicts to bound memory; a deploy serving very many
distinct sessions keeps one small snapshot each until the session ends.

Rollback: revert this squashed commit. The snapshot is in memory only; no
stored state changes format.

Related Issues

N/A

@LivXue
LivXue requested review from 0xKT and gloryfromca November 20, 2026 08:40

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Blocking: keep active sessions' snapshots stable beyond the 64-entry cache limit.

I found one blocking correctness issue inline. I reviewed the full diff and relevant surrounding callers/history, including the repository rules and canonical runtime terms, session/turn scoping, MCP connect/reconnect/removal paths, compaction and /clear refresh behavior, live availability/refusal behavior, backward compatibility of runtime-context notices, and the changed tests. I found no weakened tests.

Verification: after uv sync --all-packages, uv run pytest tests/test_agent_knowledge_search.py tests/test_agent_loop_disabled_tools.py tests/test_agent_loop_mcp_sync.py tests/test_agent_loop_tool_array_stability.py tests/test_agent_loop_tool_notices.py tests/test_agent_loop_web_tools.py tests/test_context_compacting_runtime.py tests/test_context_runtime_context.py tests/test_harness_modules.py tests/test_plughub_tool.py tests/test_read_file_image.py tests/test_tool_registry_session_snapshot.py -q passed: 484 passed, 2 warnings. The first attempt could not set up because the default environment lacked the raven_everos workspace package; syncing all workspace packages resolved that environment issue. git diff --check github/main...HEAD also passed.

Comment thread raven/agent/tools/registry.py Resolved
A live off switch, a missing credential, or a selected knowledge base no
longer adds or removes a schema. The provider tool array is the prompt-cache
prefix, so it is captured on a session's first assembly and served
byte-identically until a refresh point: a new session, a compaction, a
/clear, or a session release.

System and MCP availability changes ride the keyed runtime-context notices
instead, sent only when they differ from what the replayed history already
says. A call to an advertised-but-withheld tool is refused with the reason
and a statement that it returns.

A compaction marks the session for a refresh cashed by the next assembly, so
that turn's array, notices, and system-prompt derivations all come from one
snapshot. A charter narrows the array on read as a per-dispatch security
boundary; dynamic schemas keep re-rendering as before. The constructor's
disabled_tools stays a hard subset and never enters the snapshot.
CONTEXT.md still described the tool array as frozen per generation and a
plugin connect as joining it on purpose. The array is frozen per session and
recaptured only at a refresh point; a live switch or a missing credential is
an availability change reported in the runtime context, not a schema move.
The dispatch-section rule and the web-search key note follow the same split.
The 64-entry cap evicted the oldest session's snapshot to make room for a
new one, so a gateway serving more than 64 conversations silently
recaptured an active session's array on its next turn. Drop the cap: a
snapshot now lives until the session is released, invalidated, or its log
id changes, which are the refresh points the contract names.

session.delete now releases the session's snapshot, log id, and overlay
tools with its binding and Persona, so a reused key starts fresh.
Regression tests cover the 65th session and the delete path.
@LivXue
LivXue force-pushed the feat/session_tool_array_snapshot branch from cb6832a to ab3a5aa Compare November 20, 2026 10:19
@LivXue
LivXue requested a review from gloryfromca November 20, 2026 10:21

@gloryfromca gloryfromca left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blockers; this can merge as far as I am concerned.

The prior blocker is fixed: active session snapshots are no longer capacity-evicted, and the existing session teardown path releases snapshot state when a key is retired. I reviewed the fix delta and the rebased full PR against the repository rules and runtime terminology, relevant callers and history, session lifecycle and key reuse, compaction and /clear refresh behavior, MCP availability behavior, backward compatibility of the notice history, and the changed tests. I found no weakened tests or new issue worth raising.

Verification: uv run pytest tests/test_agent_knowledge_search.py tests/test_agent_loop_disabled_tools.py tests/test_agent_loop_mcp_sync.py tests/test_agent_loop_tool_array_stability.py tests/test_agent_loop_tool_notices.py tests/test_agent_loop_web_tools.py tests/test_context_compacting_runtime.py tests/test_context_runtime_context.py tests/test_harness_modules.py tests/test_plughub_tool.py tests/test_read_file_image.py tests/test_tool_registry_session_snapshot.py tests/test_rpc_session.py -q passed: 713 passed, 2 warnings. git diff --check github/main...HEAD also passed.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants