Repository navigation
perf(agents): share the agents-dir revision memo with the KAS session start - #13067
Conversation
|
Intent: one directory-revision memo in Not a goal: changing what the catalog caches ( |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify SEL consumers tolerate a memo-hit KAS session start emitting zero [DESIGN-REVIEWED] a9afa41 |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the memo hands back the stored tool-policy dict itself — confirm no policy caller mutates it, since only the KAS side deep-copies. What this change shipsInventory (9 items) — 9 justifiedIntent: stop a KAS session start from re-parsing every installed agent spec when the agents directory is unchanged — a FIX (perf defect, linked issue #12721, deferrals from #12722; the measured cost is already recorded in the base comment at
[FIRST-PRINCIPLES-REVIEWED] a9afa41 |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed |
57f1217 to
bc003cd
Compare
|
|
|
|
|
Pushed bc003cd: the review-round fixes above (net smaller: |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
|
bc003cd to
9bad637
Compare
|
|
|
|
Pushed 9bad637: the round-2 fixes above; also re-runs the |
9c8c4f9 to
26d746c
Compare
|
26d746c to
d42a497
Compare
|
|
|
Re-pushed the identical tree (26d746c → d42a497, no code change) to re-run Windows shard 7, whose only failure was |
d42a497 to
a9afa41
Compare
cixuuz
left a comment
There was a problem hiding this comment.
Verified the perf claim (KAS session start paying the same full agents-dir scan the tool-policy read already memoized in #12722) and the shared AgentsDirMemo primitive against source: the store/hit rules (revision before+after compute, exception unstored, per-directory key cap) are correctly extracted into one class used by both callers with separate instances (different SEL operation labels), and the KAS side deep-copies its answer so caller mutation can't leak into a later session. All 4 review lanes (Design, First Principles, Opus, GPT) are PASS/no-blocking at this exact head, dispositions across rounds all resolved, and CI is fully green. High confidence.
Problem / Motivation
Every KAS session start resolves its agent through
agent_discovery.spec_by_declared_name, which hardened-reads every spec in the agents directory to find one declaredname. On the profiled host (~2000 installed specs) that is most of a second of GIL-holding path validation and JSON parsing on a worker thread per session start. #12722 pinned the tool-policy read's answer to a stat-only directory revision, but KAS start is the second caller of the same scan and still paid the full cost, so a session start plus its managed MCP servers' policy request cost 2N reads. The revision helper also lived indashboard/handlers/sessions.py, duplicating the walkagent_discovery._dir_signaturealready does.Why it matters
The scan holds the GIL for most of a second, which the gateway's event loop sees as
loop_lag; the adaptive concurrency controller reads that as pressure and pins the subagent cap at 1 on an idle 128-core host. Session start is the most frequent path that pays it. This closes the three deferrals recorded on #12721 from PR #12722.What changed (motivation → approach → change)
Motivation: two callers of one expensive scan, one memoized, one not, with the memo's revision logic living in a handler module.
Approach: move the revision into
agent_discovery, next to_dir_signature, and put the store/hit rules in one small primitive both callers use, so the rules that took #12722 fifteen review rounds to settle are written once.Change:
src/kiro_crew/agent_discovery.py:_iter_spec_entriesis the onescandirwalk;_dir_signatureprojects(name, mtime_ns)from it and keeps its never-Nonecontract (the catalog caches do not change what they invalidate on).agents_dir_revisionis the stricter fingerprint with the same behaviour as the handler's private copy (Windows off, symlink, an entry whose kind cannot be read or a directory that cannot be listed →None(_dir_signaturekeeps treating the last as empty), entry cap →Noneplus one warning per directory (its text is nowagents-dir memo disabled for <dir>: N spec entries exceed M, replacing the handler'stool-policy memo disabled for ..., since the revision now serves both callers), racy window, spec generation in the tuple).AgentsDirMemo[T].get(agents_dir, key, compute): revision before, hit on same revision, elsecompute(), revision after, store only when equal and notNone; exceptions propagate unstored;_AGENTS_DIR_MEMO_MAX_KEYS(256) keys per directory. There is no registry orclear():clear_list_agents_cachebumps the spec generation, which is part of every revision, so stored answers stop matching on their own. The stored object is returned as-is, so a caller that hands it to mutating code copies it.sessions.py: one_TOOL_POLICY_MEMOinstance and a thin_read_managed_tool_policy_sync; the private revision function, its constants and dicts are deleted._read_managed_tool_policy_uncachedand_refuse_if_any_spec_is_unreadableare unchanged.src/kiro_crew/acp/kas_agents.pyload_agent_spec: the scan answer is served from its own_SPEC_SCAN_MEMO(separate instance: the two surfaces carry different SELoperationlabels) and returned as a deep copy, so it is still a parse the caller owns.AmbiguousAgentSpecError/OSErrorstill raise every call; the<id>.jsonfallback read stays uncached.Backwards compatibility
Compatible: no wire format, config, or public API changes;
_dir_signaturekeeps its exact return type and semantics, and every refusal path is re-derived per call exactly as before.Tests
test/test_agents_dir_memo.py(new): the revision tests moved fromtest_session_tool_policy_cache.py(content/permission changes, racy window, entry cap with one warning, platform gate, symlink entry and the catalog signature staying on for it (both through a fakeDirEntry, no symlink created), an entry whoseis_symlinkraises, an unlistable directory, stray files ignored) plustest_the_catalog_signature_stays_on_where_the_revision_refuses; memo primitive tests (unchanged directory served / edit seen, exception stores nothing, per-directory cap,clear_list_agents_cacheinvalidates through the generation); KAS teststest_kas_load_agent_spec_reads_once_per_directory_revision(N reads, then 0, then N after anos.utime-bumped edit; fails on main),test_kas_memoized_spec_is_a_copy,test_kas_refusals_are_re_derived_on_every_call,test_kas_direct_filename_fallback_is_not_memoized.test/test_session_tool_policy_cache.py: keeps the policy-semantics tests on the shared memo and addstest_the_policy_memo_is_separate_from_the_projection_memo.test_session_tool_policy_off_loop.py,test_agent_discovery.py,test_kas_agents.py,test_parsed_agents_cache.py,test_pathres_loop_starvation.pypass unchanged.Manual verification
N/A — unit coverage sufficient: the read-count tests observe the hardened reader directly, which is the cost being removed.
Related Issues
Fixes #12721
Pattern harvest
Not generalizable: this is the second caller of a scan whose first caller was already memoized in #12722; the primitive introduced here is what stops the pattern from recurring for a third caller.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Fixes #12721