Repository navigation
refactor(dashboard): split files.py, terminal.py and usage.py by owner - #20835
Conversation
Sensitive change review
|
Sensitive Change ReviewSensitive files changed:
|
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Before merge, confirm that What this change shipsInventory (7 items) — 7 justifiedIntent: keep three dashboard handler modules under the 2,000-line cap with no behaviour change. This is a FIX (a mandated cap), not a feature.
[FIRST-PRINCIPLES-REVIEWED] 6495e53 Description read[DESCRIPTION-READ] 62c7ce9f6f9392d25f8df5824d7fbd38042b3a6f437a009a919cbea7c29efbb0 That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — 🟡 CONCERNSDesign-level review of Design-Verdict: CONCERNS The three new file_api owners are filed as "non-egress" even though they hold the actual egress redaction, so the posture census can no longer see new egress there. Watch
[DESIGN-REVIEWED] 6495e53 Description read[DESCRIPTION-READ] 76de102b8c97a4f1bc440b0ecc39e587b22d6d6e7e621cc852cbf2c4d480c680 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 |
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: |
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: |
4531849 to
7ed20a6
Compare
Sensitive change review
|
|
|
chenmingwei23
left a comment
There was a problem hiding this comment.
Approving: readiness gate passed, no conflicts, checks green.
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved by a maintainer after reading the review lanes: every lane is clean on this head, and the automated triage held it only on a size, path, category or doc rule.
7a144ec
7ed20a6 to
7a144ec
Compare
Sensitive change review
|
|
Rebased onto
|
|
The dashboard's files, terminal and usage handlers were 3,211, 2,895 and 2,807 lines, past the 2,000-line cap on hand-written files. Each module stays the import path and patch surface its routes, callers and tests use, and its code moves unchanged into owners grouped by responsibility. files.py stays the file_api compose facade: new path_probe, outbox, channel_upload, desktop and editor owners, plus the grep owner, take its routes, and it keeps the module state, the imports its owners read, the shared seams and the two directory-picker routes, whose skip sets hold a literal the internal content scan refuses on an added line (1,256 lines). Each construct a repository guard reads by path has named homes that the composition contract pins. terminal.py (1,551 lines) and usage.py (842 lines) become mirror facades (kiro_crew._facade_mirror) over terminal_* and usage_* sibling owners, so a patch through the facade still reaches every module holding the name. They keep the code an added-line gate or a path pin holds in place: the WebSocket, completion and redaction routes, the lsof and fence-shell probes, the bash readiness hook, the model a turn is recorded under, and the token writer with the family's one kiro_crew.acp import. Guards that read these files by path now read the code's new home, or the facade joined with its owners; the path-keyed rows, baselines, CI path filter and owning specs follow the move. Part of #20192
c71121e to
6495e53
Compare
Sensitive change review
|
|
|
|
|
Holding 6495e53 for a human reviewer. No defect found. Why it is reserved: the PR moves the file read/write/raw/diff routes, the outbox file-card broadcast, the upload gates, and the terminal PTY/reaper code. It also adds three A maintainer needs to rule on the Design Review CONCERNS (span 6ebb92318f83): the two sink rows still name KiroCrew/src/kiro_crew/security_posture.py Lines 2287 to 2294 in 6495e53 dashboard/state.py split. Whether that is acceptable is a security-posture call for a maintainer.
Why the move looks safe: the AST check against merge base 9fba246 shows all 165 moved top-level units present in their owners. 163 are identical, and — crew-pr-reviewer (r108) |
iamwhatever
left a comment
There was a problem hiding this comment.
Deep check of 6495e53. This supersedes our earlier sensitive-file HOLD: the sensitive touches are mechanical moves.
- The file read/raw/write/diff routes, the outbox broadcast, the upload admission gate, and the terminal PTY and orphan-reaper code all move unchanged. AST compare against merge base 9fba246 shows 165/165 units identical apart from docstrings. Every global the composed file_api owners read is bound in handlers/files.py, where _facade_compose runs them. Every old terminal and usage name is still served by the facade.
- The three new NON_EGRESS_REDACTION_MODULES rows () follow the existing grep.py and dashboard/state.py precedent. The drift guard works per module, so coverage is the same as at base, and no row is dropped. The Design rebuttal holds: the sink rows render their module path on the posture page.
KiroCrew/src/kiro_crew/security_posture.py
Lines 2287 to 2294 in 6495e53
- Each path-keyed guard (BENIGN_SPAWNS, the JSON-body register, the redaction-switch file set) now points at the file that holds its construct.
AI lanes are answered, the follow-up is #21087, there is no active change request, and CI is green.
— crew-pr-reviewer (r108 deep)
This reverts commit 7f60e451f6d. Removes the Estimated Tokens card, the Est. tokens Daily History column and the backend estimator that fed them. Credits stay as they were. The estimator moved from handlers/usage.py into handlers/usage_sessions.py after the original PR (#20835), so that part is reverted by hand there; usage.py drops only the facade re-exports. The docs keep the later credit run-out paragraph.
Problem / Motivation
Goal: Bring
dashboard/handlers/files.py,terminal.pyandusage.pyunder the 2,000-line cap by moving their code into owner modules, with no behaviour change.The repository is adopting a hard rule that no hand-written file exceeds 2,000 lines (#20192). These three dashboard handlers were 3,211, 2,895 and 2,807 lines.
files.pychanges several times a week, so it needs real headroom under the cap, not just a few lines.Why it matters
Every file-route, terminal or usage change edits one of these three files, so concurrent changes collide in them and each review reads past thousands of unrelated lines. After this change each responsibility has its own module, and the next feature lands in the owner of its family instead of growing a 3,000-line file.
Not a goal
What changed (motivation → approach → change)
Each module stays the import path and patch surface its routes, callers and tests use, and moves whole definitions, unchanged, into owners grouped by responsibility.
files.pyalready composes thedashboard/file_api/owners onto its globals (through the sharedkiro_crew._facade_compose.compose), so its routes join that family.terminal.pyandusage.pybecome mirror facades (kiro_crew._facade_mirror): the facade imports what its own code reads and serves the rest, and a patch through the facade is written into every owner that holds the name.handlers/files.py(compose)file_api/path_probe.py(the_run_path_probechokepoint),outbox.py(outbox routes),channel_upload.py(Slack and channel uploads and their admission gate),desktop.py(reveal, native picker, screenshot),editor.py(file read, raw, write, diff);grep.pytakesapi_file_grephandlers/terminal.py(mirror)terminal_session.py(session state, registry, config gate),terminal_shell.py(shell, cwd, child env),terminal_transport.py(socket ownership, PTY bytes),terminal_lifecycle.py(child exit, teardown, orphan reaper),terminal_complete.py(path-completion vetting),terminal_routes.py(create, list, delete)handlers/usage.py(mirror)usage_store.py(shards, window, slot categories, row readers),usage_spend.py,usage_context.py,usage_cost.py,usage_history.py,usage_sessions.pyWhat stays in each facade, and why, is listed under Move audit below:
files.pykeeps its state, shared seams and the two directory-picker routes (their skip sets hold a literal the internal content scan refuses on an added line), which is why it ends at 1,261 lines, under the 2,000-line cap.Backwards compatibility
Compatible: every name the three modules bound before still resolves on them to the same object, routes and the handlers package re-exports are unchanged, and every patch target still reaches the code it patched (
test_dashboard_files_composition_contract,test_campaign_facades_base_public_names,test_facade_mirror_guards).Reader: src/kiro_crew/dashboard/handlers/files.py:is_tracked_channel -- chat -- bound on the facade by attribute (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_reveal_path -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_notify -- subagent -- composed from file_api/outbox.py (test_file_delivery_consent)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_download -- chat -- composed from file_api/outbox.py (test_file_delivery_consent)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_outbox_list -- chat -- composed from file_api/outbox.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_slack_upload_file -- chat -- composed from file_api/channel_upload.py (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_channel_upload_file -- chat -- composed from file_api/channel_upload.py (test_file_send_channel)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_upload -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_screenshot -- crew page -- composed from file_api/desktop.py (test_dashboard_files_composition_contract)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_read -- crew page -- composed from file_api/editor.py (test_credential_redaction_switch)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_raw -- crew page -- composed from file_api/editor.py (test_file_raw)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_write -- crew page -- composed from file_api/editor.py (test_dashboard_file_io)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_grep -- crew page -- composed from file_api/grep.py (test_file_grep)
Reader: src/kiro_crew/dashboard/handlers/files.py:api_file_diff -- crew page -- composed from file_api/editor.py (test_credential_redaction_switch)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_create -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_delete -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:api_terminal_list -- crew page -- served from terminal_routes (test_terminal_handler)
Reader: src/kiro_crew/dashboard/handlers/terminal.py:reap_orphaned_terminals -- release -- served from terminal_lifecycle (test_dashboard_server_startup_coverage)
Reader: src/kiro_crew/dashboard/handlers/usage.py:resolve_window -- crew page -- served from usage_store (test_telemetry_time_window)
Reader: src/kiro_crew/dashboard/handlers/usage.py:spend_key_for_slot -- chat -- served from usage_spend (test_session_spend_identity)
Reader: src/kiro_crew/dashboard/handlers/usage.py:slot_spend -- chat -- served from usage_spend (test_session_memory)
Reader: src/kiro_crew/dashboard/handlers/usage.py:daily_credits -- crew page -- served from usage_spend (test_usage_daily_credits)
Reader: src/kiro_crew/dashboard/handlers/usage.py:is_session_slot -- crew page -- served from usage_store (test_cost_breakdown)
Reader: src/kiro_crew/dashboard/handlers/usage.py:session_category -- crew page -- served from usage_store (test_telemetry_column_taxonomy)
Reader: src/kiro_crew/dashboard/handlers/usage.py:context_occupancy -- crew page -- served from usage_context (test_context_occupancy)
Reader: src/kiro_crew/dashboard/handlers/usage.py:slot_turn_usage -- crew page -- served from usage_spend (test_usage_turns)
Reader: src/kiro_crew/dashboard/handlers/usage.py:context_trace -- crew page -- served from usage_context (test_context_trace)
Reader: src/kiro_crew/dashboard/handlers/usage.py:cost_breakdown -- crew page -- served from usage_cost (test_cost_breakdown)
Move audit
Every moved definition has the same AST as at base; owners are black-formatted. The edits inside moved code are comment and docstring only: an own-line
# nosemgrepabove the diff route'sgit showargv (the finding is pre-existing; a new path re-reports it), a same-line# wokeignore:rule=masteron_TerminalSession.master_fd(the othermaster_fdlines carry it), and one docstring pointer in_pty_child_env(see the spawn comment in api_terminal_ws).files.pybindsis_tracked_channelby attribute fromchannel_upload(the lazy-import contract pins everyimportof that name tokiro_crew.slack.handler). The one moved exception class,_PathProbeBusy, keeps__module__ = "kiro_crew.dashboard.handlers.files", the path callers import it from, so a traceback renders it as before; the other moved classes (_PathProbe,_TerminalSession,_ConptyBackend,TimeWindow) take their owner's module, and nothing in the tree reads their__module__or pickles them. The split is a reproducible recipe;git diffandgit diff --minimaladd the same lines in every changed file (files.py +84/-2039, terminal.py +127/-1471, usage.py +144/-2109). Diff: 810,154 bytes.What stays, and why:
files.pykeeps the module state, the imports its owners read, and the shared seams (_sel,_audit_file_send,_subagent_parent_session_key,_body_err_code,_walk_monotonic,_owner_view_bypasses_credential_pass). It also keeps the two directory-picker routes,api_browse_dirsandapi_browse_files, byte-identical in their base place: their skip sets hold a literal the internal content scan refuses on an added line, so they cannot move. That is whyfiles.pyends at 1,261 lines, above the 1,200 this campaign aims for on a file that changes this often, and well under the 2,000-line cap.terminal.pykeeps the WebSocket route (path pins,BENIGN_SPAWNS), the completion route and its listing (comment-history and brand on its docstrings), the redaction route (NON_EGRESS_REDACTION_MODULES), thelsofand fence-shell probes (cross-platform and subprocess-encoding gates) and the bash readiness hook.usage.pykeeps the token-record writer with the family's onekiro_crew.acpimport (agent-sdk boundary), the oneemit_turn_durationcall, and the turn-model resolution. Moved code logs through the original logger names (logging.getLogger("kiro_crew.dashboard.handlers.terminal")/...usage; file_api owners log through the facade'sloggerby compose), so log captures keyed on them see the same records.terminal_shell.py(139 lines) is under 150 on purpose: what a new session's shell is and inherits is one responsibility, separate from session state.The docs follow the move: the owner maps in
docs/system-specs/modules/learn-cron-dashboard.md(file API, terminal and usage owners), the file citations infile-search.md,security.md,governance.md,computer-use.md,platform-context.md,metrics.md,crew-log-emitter.md,common/code-style.md,rfc-issue-radar-crews.md,rfc-chat-document-attachments.mdandrfc-resumable-subagent-sessions.md(a line citation becomes a symbol), and the facade list indocs/feature-map/README.md.src/kiro_crew/security_posture.pylists the outbox, channel_upload and editor owners inNON_EGRESS_REDACTION_MODULESbesidegrep.py: they redact what the facade's registered sink rows already name.Comment citations (KC28 L29)
Prose that named one of these files as the home of code this change moves now names the owner; only the cited path changes.
agent.py,agent_discovery.py,apps/bridges.py,apps/builtins/auto_research/campaign/storage.py,dashboard/handlers/files.py,dashboard/handlers/hooks.py,dashboard/handlers/mcp.py,mcp_discovery.py,session_map.py,slack/sessions_view.py,subagent_persistence.pydashboard/handlers/usage.py is the reference implementationdashboard/handlers/usage_store.py ...test/test_lazy_data_home_paths.py:22dashboard/handlers/usage.pydashboard/handlers/usage_store.pycrew_log/emit.py:127,config/paths.py:1205dashboard/handlers/usage.pydashboard/handlers/usage_sessions.pydashboard/handlers/usage.py:106(relayed from the provider split)providers/acp.py:610providers/acp_runtime_start.py(AcpProvider._start_kiro_runtime_impl, where_clienttakes the session provider)dashboard/handlers/core.py:3190terminal.py _completion_disabledterminal_session.py _completion_disableddashboard/handlers/appearances.py:60, :156handlers/files.py(SVG policy)file_api/editor.pydashboard/handlers/knowledge.py:1278handlers/files.py(native picker)file_api/desktop.pyapps/builtins/pptx_maker/backend/routes.py:382dashboard/handlers/files.py(SVG hazard note)dashboard/file_api/outbox.pytask_executor.py:997, :1656,dashboard/handlers/hooks.py:1564,subagent_manager/run.py:3545dashboard/handlers/files.py imports is_tracked_channeldashboard/file_api/channel_upload.py imports ...docs/request-for-change/rfc-issue-radar-crews.md:533, :625_MAX_SESSIONSinhandlers/terminal.pyhandlers/terminal_session.pydocs/request-for-change/rfc-chat-document-attachments.md:124_gate_upload_file(handlers/files.py)dashboard/file_api/channel_upload.pytest/test_session_memory.py:514slot_spend...usage.pyusage_spend.pytest/test_api_file_diff.py:1api_file_diff...dashboard/handlers/files.pydashboard/file_api/editor.py (served by handlers/files.py)Folded from the campaign review of this change: (1) the four
is_tracked_channelcircular-import comments, (2)_MAX_SESSIONSinrfc-issue-radar-crews.md(two sites), (3)_gate_upload_fileinrfc-chat-document-attachments.md, (4)slot_spendintest_session_memory.py, (5) the module docstring oftest_api_file_diff.py, (6) one sentence in thefile_api/__init__.pydocstring and in the learn-cron owner paragraph saying_PathProbeBusyreports the facade module, and (7, 8) the two frontend comments listed under "References not edited (cost)" below.cron.py:286anddashboard/state.py:7507also cite the old files. Other changes were reshaping those files, so this PR leaves both alone; the re-point is tracked in #21087. Both names still resolve through the facades.References not edited (cost): two frontend code comments keep their old path, because a comment-only edit there would pull the frontend CI jobs onto this backend split. The follow-up that re-points them is tracked in #21087.
website/src/pages/telemetryRange.ts:6resolve_windowindashboard/handlers/usage.pydashboard/handlers/usage_store.py(served byusage.py)website/capture/path-chips.tsx:13api_file_readindashboard/handlers/files.pydashboard/file_api/editor.py(served byfiles.py)CI path references
.github/workflows/macos-on-demand.ymldarwin filter: the sixsrc/kiro_crew/dashboard/handlers/terminal_*.pyowners besideterminal.py(the file_api owners were already covered byfile_api/**).Tests
No assertion's matcher or expected value is relaxed. Source-reading pins read the code where it lives (KC28 L30 re-points, L40(8) joins), and each goes red under a mutation in the code's new home (21 mutation cases, all red):
test_appearance_library(SVG policy) andtest_desktop_ui_trusted_bin(git argv) readfile_api/editor.py;test_cse_2026_08_07_fixesslicesfile_api/channel_upload.py.test_json_object_body_guard(six register keys),test_spawn_auditBENIGN_SPAWNS(four keys, among themfile_api/editor.py::_diff_redacted_bodies, the git spawn fix(dashboard): build the file panel diff from whole redacted files #20594 added to the diff route),test_security_posturecensus (dashboard/file_api/outbox.py: 1),test_credential_redaction_switchexact set (+file_api/editor.py),test_no_config_dir_in_async(six owners),error-code-baseline.json(files.py's 33 split as outbox 11, editor 12, desktop 7, channel_upload 3; totals unchanged),test_campaign_facades_base_public_names(two new inventory files,test/campaign_facade_inventories/kiro_crew.dashboard.handlers.terminal.jsonand...usage.json).test_redactors_are_called_only_by_the_selection_handler,test_no_send_through_the_session_field_after_an_await) and the one-emit guard intest_turn_metric_all_surfaces.test_dashboard_files_composition_contract: owner set, base owners, facade definitions and the shape digest gain the moved names (taken from the base file);_STAYS_IN_THE_FACADEbecomes_GUARDED_CONSTRUCT_HOMES(each construct in exactly its named files, absent from every other file of the family). This reverses a base pin on purpose. Base_FACADE_DEFSkept file delivery (the outbox routes with the census site, the Slack and channel uploads with their admission gate) and every route a guard reads by path infiles.py, because those guards readfiles.pyby path. This PR re-points each of those guards, path only, to the file the route now lives in, and a mutation in that file turns each one red. That reason for holding the routes infiles.pytherefore no longer applies. What a gate cannot follow stays: the two directory-picker routes and their content-scan literal; the census check reads the outbox owner; the register keeps nohandlers/files.pykey.test_terminal_facade.py,test_usage_facade.py: owner set and layer order, theTYPE_CHECKINGhome manifest for served names, the shared logger, and a facade patch reaching the owner that reads it. Newtest_files_path_probe.py:_PathProbeBusynames the facade module in a traceback, is one class for every importer, and defines no methods (compose selects classes by their owner__module__, so a method on it would not be rebound). Each new file passes 5 repeat runs at-n 0and one at-n 3.Local gates: 159 related test files (every file that imports, patches or reads these modules, plus the repository guards that scan them) 7,608 passed, 16 skipped; every new module at or above 82% line coverage under them (
channel_upload.py82.1%, the rest 88-100%);mypy src/kiro_crewclean (2,447 files); isort, flake8, black gate, subprocess-encoding, agent-sdk boundary, sync-io, loop-locks, memory-store, cwd-reads, comment-history, brand, harness, feature-map, docs-lint and line-cap (0 failures) pass; semgrep 1.78 with CI's rule set over the 60 changed Python files: 0 new findings, no parse errors; flake-pattern ratchet passes; take-away hits are the 28 Reader lines above.scripts/local-gate.py --dry-runselects 3,678 backend + 2,139 frontend files, so the floor above ran instead and CI owns the broad matrix.Notes: the
terminal_transport.pymodule docstring and its entry in the learn-cron owner map say the bash readiness marker is "matched, not removed": the code matches it and forwards the output bytes unchanged, as the spec's "Terminal input readiness" row states.Manual verification
N/A: a verbatim move behind unchanged import paths; the 159 related test files exercise every moved route and helper.
Related Issues
Part of #20192
Follow-up: #21087 (re-points four code comments that still cite the split files)
Checklist
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.