Repository navigation
perf: list MCP tools before loading tool handlers - #35293
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: every server still lists its tools through one live path, and the remaining handler-load failure is described and accepted. Notes
[DESIGN-REVIEWED] 297b016 Description read[DESCRIPTION-READ] 524fb1c0201f32c701811bf872a7e6957a170bdca9d19a46bf8630d6fc768438 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: each item lowers the measured spawn-to-list time and leaves both answers byte-identical. If the engine never sends Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: a new session starts sooner because Kiro Crew's four MCP servers list their tools before loading their handlers. ADDITION (perf).
[FIRST-PRINCIPLES-REVIEWED] 297b016 Description read[DESCRIPTION-READ] 3d3e1e5489239f25a08b6bb7033998d25fb656f22d0a1ff462ef92df1a97324c That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
b50a3b4 to
0755a3c
Compare
Sensitive Change ReviewSensitive files changed:
|
Sensitive change review
|
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates an 18% chance that this change introduces a defect, above the 12% limit for approving on its own. The four Kiro Crew stdio servers now answer An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
0755a3c to
337a393
Compare
Sensitive change review
|
337a393 to
9e455af
Compare
Sensitive change review
|
buluoray
left a comment
There was a problem hiding this comment.
Approve on 9e455af. The rebase onto main f859940 drops the graduated black-baseline entry and keeps main's DEFERRED_STEP_WORKERS import beside the PR's two new imports, so lint is green and merge-tree is clean. Backend Tests shards are still running. Lead note: both blockers named at 337a393 are resolved; the delta adds nothing else. Decisive lines: .github/black-baseline.txt (test/test_mcp_gateway_oversize.py removed) ; src/kiro_crew/mcp_tools/spawn.py:929-931 (conflict resolved, all three imports kept) ; src/kiro_crew/mcp_gateway/pool.py:162
An agent engine starts every MCP server of a session at session start and holds the first prompt until each has answered initialize and tools/list. Kiro Crew's four own servers imported about 1,000 package modules before answering, so a new session waited on code that only a tool call needs. Each server now answers both requests once the platform has booted and loads its handlers after. One function builds each answer (mcp_shared_listing), used before and after the handlers load, and each server declares itself once in a module that imports no handler. The dispatch loop handles every frame the early answers left, once and in order. The two live values in the spawn descriptions stay live: their readers work before kiro_crew.subagent and the conversation store are loaded, and go through those modules once they are. A subprocess test bounds what each server may load before it lists. The tool lists are byte-identical to main. Closes #35275
9e455af to
297b016
Compare
Sensitive change review
|
buluoray
left a comment
There was a problem hiding this comment.
Approve on 297b016. Since our approval on 9e455af, this head is a rebase onto main e8283ce plus one new test that compares the standalone sub-agent readers with the facade. No product code changed. I traced the early answer again. It builds the initialize result and the tool list with the same functions the dispatch loop uses. It runs only after every start-up refusal, and it reads the session's tool policy the same way the loop does. A tools/call that arrives before the handlers load is left for the loop, which answers it once and in order. The 744 tests in the 18 related files pass. Two parts of the early path have no test. If the early tools/list skipped the session's tool exclusions, no test would fail. If the loop dropped the in-flight report request from an initialize answered early, no test would fail either. Please add a test for each. The red backend shards on this head are the two tests that were red on main before #35625. The branch needs a rebase onto current main to clear them. Decisive lines: src/kiro_crew/mcp_shared_listing.py:296-305 (early tools/list uses the loop's own listable_tools and policy) ; src/kiro_crew/mcp_shared_dispatch.py:1334-1354 (carried frames answered first, in order; early initialize params carried) ; src/kiro_crew/mcp_entry.py:203 (answer runs after every start-up refusal, before the handler import) ; test/test_subagent_standalone.py (only new hunk since 9e455af)
Pull request was closed
Problem / Motivation
Goal: A new session stops waiting for Kiro Crew's own MCP servers to load their tool code before they can say which tools exist.
The agent engine starts every MCP server of a session when the session starts, and holds the first prompt until each has answered
initializeandtools/list. Kiro Crew's four own servers (kirocrew-core,kirocrew-cron,kirocrew-guide,kirocrew-mate) each imported about 1,000 package modules before answering: the code that runs every tool, the sub-agent manager, the conversation store, the agent client. On a zero-config Linux install the slowest of them,kirocrew-core, took about 1.4 s to list, and the session could not start before it.Why it matters
Every new session pays this, on every backend, before the user's first message is even sent to the model. It is the largest part of the gap between Kiro Crew's cold session start and the bare engine's.
Not a goal
acp/is untouched).What changed (motivation → approach → change)
A new session starts sooner, with the same tools. Each of Kiro Crew's own MCP servers now says which tools it has first, and loads the code that runs them after.
initializeresult and the filtered list inside the dispatch loopmcp_shared_listing), used before and after the handlers loadStdioServer), in a module that imports no handlerWhy this shape. Listing needs the tool descriptors and the session's tool policy. It does not need the code that runs a tool. So the descriptors moved to modules that import no handler (
mcp_tools/catalog/, and the*_tool_listmodule of each server), andmcp_entryanswers the two requests once the platform has booted. Every start-up refusal still happens before anything is answered. Atools/callthat arrives while the handlers load waits in the pipe; the loop then handles every frame once, in order.The two live hints stay live. The spawn tools' descriptions name the sub-agent ceiling and the agents the calling parent may spawn. Their readers now work before
kiro_crew.subagentand the conversation store are loaded:subagent_parts/host_memory.pyand the newsubagent_parts/spawn_allowlists.pyimport what they read,kiro_crew.subagent_standalonereaches them, andhistory_metadata_line.pyreads one session's record without the store, from the fileConversationLog._pathresolves (that method is unchanged). Once those modules are loaded the same calls go through them, so every existing patch seam still works.If the handlers cannot load. The import runs where it always ran. A missing dependency still heals and retries. Any other failure still prints its reason on stderr and exits non-zero. The difference is timing: the client already holds the tool list, so it sees a server that listed its tools and then closed its pipe, the same state as a server that crashed mid-session.
Smaller cuts on the same path. Platform boot and core's listing no longer load the OS sandbox module (two constants and two phrases moved to light modules:
speech_providers,autonudge_judge_phrases). The config loader imports the MCP rewriter only on the branch that reads it (config/loader.py,config/loader_config.py), andmessaging/__init__.pyresolves its exports on first read.A ratchet holds it.
test_mcp_listing_import_budget.pyruns each server's real entry in a fresh interpreter and bounds what is loaded when the list goes out: a named denylist and a module count per server.Time from spawn to
tools/listanswered, the four servers started together as the engine starts them. Linux, one host, n = 3 before and n = 3 after, taken in before/after pairs, one measurement at a time; before = main at the merge-base. Median, with the three samples in brackets:The host was shared (1-minute load 0.35 to 0.73 per core), which is why the samples spread; within each pair the after run took 41% to 52% of the before run. This phase ends before the model is called, so no model turn was timed. Package modules loaded at list time: about 1,000 before; 461 (core) and about 330 (the other three) after.
The design note (one listing path, no handoff file, live hints kept) was reviewed by a maintainer before the build; the diff is large because descriptors moved, not because behaviour grew.
Backwards compatibility
Compatible: every server answers the same
initializeresult and the same tool list, byte for byte (compared for all four against main), and every import path and patch seam that existed still resolves.Removes nothing for a caller: each definition below moved to a new module, and the module it left still serves the same name as the same object. The readers, found by
git greponorigin/main:Reader: src/kiro_crew/mcp_tools/init.py:build_tool_list -- chat -- reads each domain's
schemas()andadvertised()frommcp_tools/catalog/<domain>, the module that now defines them;test_mcp_tool_registry.pyReader: src/kiro_crew/mcp_tools/init.py:build_tool_names -- chat -- the same builders, names only;
test_mcp_discovery_agent_config.pyReader: src/kiro_crew/mcp_tools/app_tools.py:_core_tool_names -- app -- moved with
schemas()intomcp_tools/catalog/app_tools.pyand reads the catalogue;test_app_agent_tools.pyReader: src/kiro_crew/apps/builtins/ops_mission_control/tests/test_agent_api_tool.py:app_tools.schemas -- app --
mcp_tools/app_tools.pyre-exportsschemasandadvertisedfrom the catalogueReader: src/kiro_crew/mcp_tools/control_parts/monitor.py:screen_phrase -- chat --
autonudge_judge.pyre-exportsscreen_phraseandending_phrasefromautonudge_judge_phrases.pyReader: src/kiro_crew/dashboard/session_directive_apply_monitor.py:screen_phrase -- chat -- the same re-export;
test_campaign_facades_base_public_names.pyReader: src/kiro_crew/mcp_tools/control_parts/schemas.py:ending_phrase -- chat -- imports both phrases from
autonudge_judge_phrases.py, the same objectsReader: src/kiro_crew/mcp_tools/spawn_parts/listing.py:visible_agent_names -- subagent -- imported from
kiro_crew.subagent, which binds it fromsubagent_parts/spawn_allowlists.py;test_agent_roster_shared.pyReader: src/kiro_crew/mcp_tools/spawn.py:agent_matches_allowlist -- subagent -- imported from
kiro_crew.subagent, as isparent_spawn_allowlists;test_spawn_parts_contract.pyReader: src/kiro_crew/subagent_parts/agent_policy.py:_vet_parent_available_agents -- subagent -- runs on the facade's globals, where the four moved names stay bound;
test_spawn_parent_available_agents.pyReader: src/kiro_crew/acp/kas_subagent_targets.py:spawn_allowlist -- subagent -- imported from
kiro_crew.subagent;test_subagent_parts_composition_contract.pyholds it as one objectReader: src/kiro_crew/agent_sdk/tools_settings_reach.py:spawn_allowlist -- chat -- names the function in its docstring only; the reference now points at
spawn_allowlists.pyReader: src/kiro_crew/slack/gateway_runtime/cron_fire.py:parent_spawn_allowlists -- cron -- imported from
kiro_crew.subagent, unchangedThe security posture table gains one row:
subagent_parts/spawn_allowlists.pysits besidesubagent_parts/agent_policy.pyinNON_EGRESS_REDACTION_MODULES(security_posture.py), because the two redactor calls it holds moved from that file unchanged. No output path is added.Where the code went, by file:
mcp_shared_listing.py(new),mcp_shared.py,mcp_shared_dispatch.py,mcp_shared_wire.py,mcp_entry.py.mcp_core_tool_list.py,mcp_guide_tool_list.py,mcp_mate_tool_list.py(new),mcp_cron_tool_list.py; their serversmcp_core.py,mcp_cron.py,mcp_guide.py,mcp_mate.pypass the declaration to the loop.src/kiro_crew/mcp_tools/catalog/(new); each domain module undersrc/kiro_crew/mcp_tools/re-exports its builders.subagent_standalone.py(new),subagent.pyandsubagent_parts/;execution_context.py,history_metadata_line.py(new),history.py,history_projection.py,history_projection_contract.py,history_projection_reads.py.speech_providers.py,voice_reply.py,autonudge_judge.py,autonudge_judge_phrases.py(new).src/kiro_crew/mcp_gateway/pool.py, below.One behaviour changes for an operator who set either of two config keys.
mcp_gateway/pool.pyresolvesmcp_gateway.read_buffer_limit_bytesandmcp_gateway.response_spill_threshold_byteswhile it is imported. On main that read ran inside the config loader's own import, failed every time, and was swallowed, so the gateway side used the environment variable or the built-in default and ignored the key. The loader no longer imports the MCP rewriter eagerly, so the read now succeeds and a configured value is the one in force, asdocs/architecture/mcp.mdalready describes. Unset keys (the default) read exactly as before. With no data home yet the import reads no config and creates nothing, as before (test_mcp_gateway_oversize.py).Tests
test/test_mcp_shared_listing.py(new): the two builders; the early answers take only the two requests they serve; a call, a malformed frame, an end of stream and a failed list are left for the loop; the loop answers what was left once and in order; a later list comes from the same function.test/test_mcp_listing_import_budget.py(new): the ratchet described above, in a real subprocess per server.test/test_history_metadata_line.py(new): the light reader and the store agree on every first-line shape; the session record is read without loading the store.test/test_subagent_standalone.py(new): the two standalone owners bind every global they read, answer with the facade unloaded, and a patch of the facade reaches them once it loads.test_subagent_parts_composition_contract.py,test_spawn_parts_contract.py,test_mcp_shared_facade.py, one inventory file, and the source-path pins that named the old files (test_agent_spec_hardened_reads.py,test_agent_spec_pins.py,test_kas_tools_settings_aliases.py,test_crewmate_prompts.py,test_agent_refactor_contracts.py).test/test_mcp_gateway_oversize.py: importing the gateway with no data home creates nothing and uses the defaults; with a configured ceiling, that ceiling is in force.Determinism: the four new files ran 10 times at
-n 2with 0 failures, and once in a shuffled order (seed 20261111,-n0), all passing. No test sleeps or waits on a literal duration; the silent-client case is scripted, so no time passes.Related sets run locally by name (2,067 tests across 37 files, plus the roster and spawn files), all passing. isort, flake8, mypy, the black gate, the comment-history, brand, line-cap, subprocess-encoding and harness-parity gates, the flake-pattern ratchet and the repository's semgrep rules pass.
Manual verification
initializeresult and tool list compared byte for byte against main at the merge-base (134,440 bytes for core). Identical.Screenshots / video
N/A. No user-visible frontend surface is touched.
Related Issues
Closes #35275
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)