Skip to content

refactor(kas): split kas_agents.py by moving mcp projection to owners - #37828

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
crew/linuxflackyguard/split-kas-facade
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
crew/linuxflackyguard/split-kas-facade

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Bring src/kiro_crew/acp/kas_agents.py (2,004 lines) back under the 2,000-line cap with a pure move, so the main ratchet audit stops naming it.

Main's Ratchet Audit has been red on every push since 11/13 because two files are over the cap (#36565). This PR handles acp/kas_agents.py; hooks.py is split separately.

Why it matters

While a file is over the cap, every PR that touches it fails backend-ratchets, and the whole-tree audit on main stays red, which hides real regressions behind a known failure.

Not a goal

  • Any behaviour change in the KAS projection, the hoist, or what reaches the wire.
  • Renaming or re-homing any public name, or changing a caller's import path.
  • Splitting src/kiro_crew/hooks.py (handled in its own PR).
  • Fixing comment citations that were already stale on main (kas_agents.projected_write_allowlist, kas_agents.withheld_credentials_notice).

What changed (motivation → approach → change)

kas_agents.py held two jobs beside the agent projection: deciding the mcpServers block, and hoisting the active agent's managed servers into the session-level array. Each moves whole into its own owner, so the file can stay the projection and the one import path:

  • acp/kas_agents_mcp_servers.py (403 lines): _project_mcp_servers and its constants (MANAGED_MCP_SERVER_NAMES, WithheldOut, NOT_RUN_*, _CREDENTIAL_BEARING_FIELDS, _WRAPPER_MARKERS).
  • acp/kas_agents_session_hoist.py (311 lines): hoist_servers_for_session, _HOISTABLE_ENTRY_KEYS, _managed_first, _managed_entry, _tokened_managed_element.
  • acp/kas_agents.py (2,004 → 1,439 lines) becomes a _facade_mirror facade over those owners and the existing kas_agents_registered.py. It keeps every import it had, imports back each moved name a caller or its own code reads, and serves the six owner-only names through the mirror. A patch of kiro_crew.acp.kas_agents.<name> therefore still reaches the moved code (_registry_governed is read inside _project_mcp_servers). Both owners log as kiro_crew.acp.kas_agents. __all__ is derived from the namespace, as the spec asks for a module that had none.

Moved bodies are byte-identical to main; only module headers are new.

Backwards compatibility

Compatible: every name kiro_crew.acp.kas_agents bound on main still resolves there, to the same object (proof below), and no caller or test import changed.

The diff deletes definitions from kas_agents.py (they move to the owners). Every reader still gets them from the old path:

Reader: src/kiro_crew/acp/runtime.py:hoist_servers_for_session -- chat -- imported from kiro_crew.acp.kas_agents, which binds the owner's function; test_kas_agents_mcp_servers.py
Reader: src/kiro_crew/acp/runtime_session_create.py:hoist_servers_for_session -- chat -- same import, same object; test_kas_agents_mcp_spec_gate.py
Reader: src/kiro_crew/acp/runtime_session_load.py:hoist_servers_for_session -- chat -- same import, same object; test_kas_env_launch_resume.py
Reader: src/kiro_crew/acp/kas_withheld_notice.py:WithheldOut -- chat -- WithheldOut and the three NOT_RUN_* constants are imported back onto the facade; test_acp_runtime.py
Reader: src/kiro_crew/acp/kas_agents.py:to_client_custom_agent -- chat -- calls _project_mcp_servers, imported back from its owner; test_kas_agents.py
Reader: test/test_mate_work_ledger_mount.py:_project_mcp_servers -- subagent -- from kiro_crew.acp.kas_agents import _project_mcp_servers resolves to the owner's function; test_mate_work_ledger_mount.py
Reader: test/test_kas_app_mcp_session_identity.py:MANAGED_MCP_SERVER_NAMES -- chat -- imported back onto the facade, same frozenset object; test_kas_app_mcp_session_identity.py
Reader: test/test_kas_agents_facade.py:_managed_first -- chat -- _managed_first, _managed_entry, _tokened_managed_element, _HOISTABLE_ENTRY_KEYS, _CREDENTIAL_BEARING_FIELDS and _WRAPPER_MARKERS have no reader outside the owners and are served from them by the mirror; test_kas_agents_facade.py

Tests

  • New test/test_kas_agents_facade.py: every name the test trees patch through the facade reaches every holder (including an owner, _registry_governed); the owners are exactly the kas_agents_*.py siblings in layer order and never import the facade; only the six owner-only names are served; the family logs under one logger. Opts into the shared known_seams check.
  • New test/campaign_facade_inventories/kiro_crew.acp.kas_agents.json: the 120 public names main bound, and 99 import-bound ones checked against their home object.
  • Proof: not provable -- test-only change (a pure move; there is no production behaviour change to revert)

Proof of the split, against base fd4b0d4:

  1. Names: a script imported kiro_crew.acp.kas_agents on the base and on the branch. All 166 names bound on the base resolve on the branch (0 missing). Each name bound by import is its home module's own object (0 mismatches). The branch adds only mirror glue (_EXPORTS, _KAS_AGENTS_OWNERS, _SERVED, _MIRROR, _facade_mirror, _importlib, _sys, _owner).
  2. Import paths: all 50 names spelled as from kiro_crew.acp.kas_agents import, kas_agents.<name> or patch("kiro_crew.acp.kas_agents.<name>") in src/ and test/ resolve on the branch. The only ones that do not, projected_write_allowlist and withheld_credentials_notice, are comment citations that already fail to resolve on the base.
  3. Related backend set (SCOPED_TESTS_BASE_REF=<merge-base> scripts/run_scoped_tests.py --surface backend, 90 files) on a Linux DevSpace: 4679 passed, 5 skipped, 0 failed. With nothing red, no comparison run on base was needed. Locally, test_facade_mirror_guards.py, test_facade_shared_checks.py, test_campaign_facades_base_public_names.py and test_mirrored_owner_storage.py with the new facade test: 1169 passed.
  4. scripts/check_file_line_cap.py: the scoped run passes. With RATCHET_SCOPE_WHOLE_TREE=1 the only file it names is src/kiro_crew/hooks.py (the sibling split). kas_agents.py has no baseline row.
  5. flake8, isort, mypy src/kiro_crew (4734 files, clean), the black gate (black 26.10.1), comment-history, brand-name, subprocess-encoding, test/test_flake_pattern_ratchet.py (71 passed), semgrep scan --config semgrep/ --baseline-commit <merge-base> --error (clean) and scripts/docs_lint.py all pass.

Manual verification

N/A — a pure move of whole definitions; the related backend set and the facade guards cover the import and patch surface.

Related Issues

Part of #36565

Open PRs that touch this file, and what each one meets after this split (from gh pr diff):

PR Hunks in kas_agents.py After this split
#32021 mcp_cleanup import (+mcp_entry_is_remote); 2 hunks in _project_mcp_servers Both hunks and the new import move to kas_agents_mcp_servers.py
#26455 _ceiling_permitted, to_client_custom_agent Clean rebase: both stay in kas_agents.py; only line offsets shift
#22929 new mcp_provenance import; 1 hunk in _project_mcp_servers Hunk and import move to kas_agents_mcp_servers.py
#17015 imports; _ceiling_permitted; to_client_custom_agent; deletes _managed_entry/_tokened_managed_element (-65 lines) The import, _ceiling_permitted and to_client_custom_agent hunks stay in kas_agents.py. The deletion and its kas_managed_entries imports move to kas_agents_session_hoist.py, and those two names leave _SERVED and the TYPE_CHECKING block

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 16, 2026 05:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision c7e3f28850d6bb88737c7ef1075068e616cabe7e touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c7e3f28850d6bb88737c7ef1075068e616cabe7e — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this is a pure move behind the repo's existing _facade_mirror facade pattern, the import and patch paths are kept, and a facade test pins them.

[DESIGN-REVIEWED] c7e3f28

Description read

[DESCRIPTION-READ] 710da7ed6980a7cb84d13a521f6b68dafb5ab2f8ba9c75965e06ceee87e33964

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c7e3f28850d6bb88737c7ef1075068e616cabe7e — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks: this is a pure move that the AGENTS.md 2,000-line cap requires, using the repository's existing _facade_mirror mechanism (281 files under src/kiro_crew use it).

What this change ships

Inventory (6 items) — 6 justified

Intent: bring kas_agents.py back under the 2,000-line cap so every PR touching it, and the main ratchet audit, stop going red. This is a FIX (a refactor that unwedges a red gate).

  1. The mcpServers projection and its constants now live in kas_agents_mcp_servers.py — justified
  2. The session-level hoist now lives in kas_agents_session_hoist.py — justified
  3. kas_agents.py becomes a mirror facade, so old import and patch paths keep working — justified
  4. kas_agents.py now defines __all__, so a star import binds an explicit set — justified
  5. Both new owners log under the kiro_crew.acp.kas_agents logger name, as before — justified
  6. A new facade guard test and a public-name inventory JSON pin what the facade can reach — justified

[FIRST-PRINCIPLES-REVIEWED] c7e3f28

Description read

[DESCRIPTION-READ] c0e4f93ff89c51446f849875ea095942d1274fa959b67f2c1e13de57cd514cfc

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c7e3f28850d6bb88737c7ef1075068e616cabe7e — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c7e3f28

Verdict parsed from the review's SHA-scoped output markers for commit c7e3f28850d6bb88737c7ef1075068e616cabe7e.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c7e3f28850d6bb88737c7ef1075068e616cabe7e false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c7e3f28850d6bb88737c7ef1075068e616cabe7e and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c7e3f28

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c7e3f28850d6bb88737c7ef1075068e616cabe7e false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 16, 2026
Move the mcpServers projection (_project_mcp_servers and its
constants) into acp/kas_agents_mcp_servers.py and the session-level
hoist (hoist_servers_for_session and its helpers) into
acp/kas_agents_session_hoist.py, verbatim. kas_agents.py drops from
2,004 to under 1,450 lines and becomes a _facade_mirror facade over
those owners and kas_agents_registered.py, so every name stays
importable and patchable at kiro_crew.acp.kas_agents. No logic change.

Part of #36565
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/acp/client_claude.py, src/kiro_crew/acp/harness/kas.py, test/conftest.py and 19 more since this head went green (fd4b0d4 -> b8631dd); CI re-running.

@bolichen97
bolichen97 force-pushed the crew/linuxflackyguard/split-kas-facade branch from a51ec0a to c7e3f28 Compare November 16, 2026 06:23
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 16, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 16, 2026 07:19
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider estimates a 6% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 1866 lines, more than the 400 it may approve on its own.

This is a pure move of the mcpServers projection and the session-level hoist out of kas_agents.py into two sibling owners, with kas_agents.py kept as a _facade_mirror facade, the shape the repo's code-style spec requires. I checked that the moved bodies are unchanged, that every global they read is still bound on the facade (so a facade patch reaches them), that owners load in layer order and never import the facade, that the logger name is preserved, and that all is derived from the namespace as the spec says. A new facade test checks patch reach, owner order, which names are served, and the single logger. All CI checks are green. No behaviour change, regression or trust-boundary issue found.

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 c7e3f28850 · 1866 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I reviewed head c7e3f28. Each moved definition (the mcpServers projection with its constants, and the session-level hoist with its helpers) has the same source text as the merge base, and every definition that stayed in kas_agents.py is unchanged. The facade still binds or serves every name it had before, the owners import the same source objects and log under the same logger name, and no owner imports the facade. On this head, every test file that references kas_agents plus the facade guard suites pass (5894 passed, 0 failed), and flake8 is clean on the touched files. This is a pure move with no behaviour change, so nothing blocks.

@KiroCrewCaptain
KiroCrewCaptain merged commit 31cc202 into main Nov 16, 2026
97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the crew/linuxflackyguard/split-kas-facade branch November 16, 2026 07:53
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
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