Repository navigation
feat(instances): fetch a crew's session back to the hub - #19440
koenvincent wants to merge 2 commits into
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: the pull reuses the existing Notes
[DESIGN-REVIEWED] 8e56a00 Description read[DESCRIPTION-READ] c92f96873d6f5bb8b4eb654c27560ecc61b01c691eef10405172e0a82a68ac72 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, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The pull route ships with no caller in this repo yet. That is a reversible, declared deferral, not a blocker. Notes
What this change shipsInventory (7 items) — 6 justifiedIntent: let the owner copy a crew's session back to the hub in one request instead of a manual export/download/import round trip. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 8e56a00 Description read[DESCRIPTION-READ] c6bb5cc310c975006d39496b27a44971de744372fba6f5e143df342a6bf1b318 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] 8e56a00 |
|
Addressing the review lanes on
|
|
CI on |
|
Update on the live check I promised: I could not run this branch as a hub on my machine yet. A pod for the worktree provisions now, after a venv workaround (the bundled Python has no Unless a reviewer can run it sooner, I will do the check on the first insider build that carries this route: pull a session from a crew connected over SSM, with the crew's |
3d1b2ca to
98d21e0
Compare
98d21e0 to
754c15f
Compare
efc7f4a to
d625163
Compare
|
|
|
Thanks for r101. Head is now d625163, on the same base (main 75726a8) and still 2 commits, both signed by GitHub. 3. First Principles on efc7f4a. One disposition record per item, above:
4. Design: does aiohttp gunzip the export on the way in? No. I checked it rather than reasoning about it. I served a staged gzip through the crew's real
aiohttp's client inflates only on a Button. It stays out of this PR unless a maintainer says otherwise. It is tracked in #20548. Still open, for maintainers:
|
|
Rebased onto main 9a77e12; new head 1848038. The red backend shards on d625163 (Linux 3.12 (1), Windows (1), macOS (1)) were one test of this PR: Windows (2) failed on an unrelated test: an xdist worker crashed on a timeout in |
|
Rebased onto main 83e97cd (new head c873dca) after it went CONFLICTING again: only the crew-window row in the feature map, where main had moved the sidebar file paths. I kept main's row and re-added the three fetch-session additions; the feature-map gate passes and 269 session-transfer tests are green. The one red on 1848038, |
|
CI on c873dca: the only failing test is |
|
Live check against a real crew (as asked in the HOLD), with this branch's hub code at c873dca:
|
|
@iamwhatever friendly ping for a re-review when you have a moment. Since your HOLD: the live check against a real crew is posted above, the branch is rebased on main (head |
|
HOLD at 1bb5ee6. The code still looks right after the #21111 split: the owner _guard runs before any peer call, the slot key is checked and percent-quoted, a crew refusal relays only peer_status, a bad crew bundle becomes a 502, and the sender name comes from the hub's registry ( KiroCrew/src/kiro_crew/dashboard/handlers_instances_peer.py Lines 105 to 218 in 1bb5ee6 What blocks approval:
No PR code was run locally. — crew-pr-reviewer (r112) |
|
GPT 6.1, fetch rejects valid peer session keys ( |
|
Rebased onto main
Checked locally: |
|
HOLD at 1691911. A human review is required, and one maintainer decision is still open. The code still looks sound. The owner What blocks approval:
Reviewed head: 1691911 — crew-pr-reviewer (r121) |
POST /api/instances/{id}/fetch-session is the pull counterpart of
send-session. The hub reads the peer's own export route over the open
tunnel (proxy_request: manager-held cookie, one re-mint, no redirects)
and installs the reply through the one arrival path, so the format
sniff, admissions, redaction, arrival folders and copy semantics are the
same code a pushed or file-imported session meets.
Layer B is requested and the peer decides it: its export carries the
context window only when its operator enabled export_include_layer_b and
the request is the owner's, which a minted token's subject is.
The peer slot key is validated and percent-quoted into the path; a peer
refusal relays its status only, never its body. Owner-only via _guard.
|
On the open maintainer decision from r121 (does merging need the live run of a hub serving I tried to run it today on an isolated Linux host with this branch at So I would ask a maintainer to defer the full hub-side run. If you agree, I will open an issue for it and link it in the description. That leaves only the human review the policy reserves for this route. @chenmingwei23 could you take it? |
|
Opened #30231 for the two-gateway run and linked it in the description, so a maintainer can defer it there. The rest of this PR waits only on human review. |
Problem / Motivation
Goal: Let the hub copy one of a connected crew's sessions back to itself, with full context when the crew allows it.
Send session already copies a session hub -> crew over the open tunnel, Layer B included. The opposite direction has no route: to bring a session a crew ran back to the hub, the owner has to open the crew's pane, export the session to a file, download it, and import that file on the hub.
docs/system-specs/modules/instances.md§14.6 names a hub-initiated pull as the natural follow-on for exactly this reason: a crew usually cannot reach back to the hub.Why it matters
Work that starts on a crew and has to continue on the owner's machine (or the other way round, then back) is a round trip today with a file in the middle, and the file step is easy to get wrong: the download lands in the browser's folder, and the import has to happen in the right dashboard. A pull over the tunnel the hub already holds makes the return trip one request, through the same arrival path every other transfer uses.
Not a goal
export_include_layer_bopt-in and owner check decide it, unchanged.proxy_requestalready uses for that crew.What changed (motivation → approach → change)
SshTunnelManager.proxy_request(manager-held cookie, one re-mint on 401/403,allow_redirects=False) against the crew's ownGET /api/chat/slots/{slot}/export?include_layer_b=true, which is inside the proxy'sapi/chatgrant. The write is the one arrival path,_install_arrived_bundle. The browser-facing proxy route is not used: it forwards JSON and SSE only and would refuse the gzip export.session_transfer_intake.py/session_transfer_install.py(weresession_transfer.pybefore refactor(dashboard): split session_transfer and handlers_instances #21111):_read_bundle_bodyand_install_arrived_bundletake an optionalsource, anything with acontentstream. It defaults to the request, so the existing import route is unchanged. A newinstall_peer_export(request, source)runs the arrival with the crew's live response as the body. Format sniff, upload and expansion admissions, memory admission, redaction, arrival folders and copy semantics are the same code.handlers_instances_peer.py(washandlers_instances.pybefore refactor(dashboard): split session_transfer and handlers_instances #21111; the facade serves it ashandlers_instances.api_instances_fetch_session):POST /api/instances/{id}/fetch-sessionwith body{"slot": "<the crew's slot key>"}. Owner-only through_guard. The slot key must match_FETCH_SLOT_KEY_REand is percent-quoted into the path, so it cannot leave the export segment. A crew 404 that carries the export's ownexport_slot_not_foundbecomes404 transfer_slot_not_found; a bare 404 (a crew without the route) is a refusal, not a missing session. Any other crew refusal becomes502 transfer_peer_refusedwithpeer_status, which already tells "never exportable" (400) from "try again" (503) and "failed" (500). Nothing of the crew's body is relayed: it is peer text, and at most 4 KiB of a 404 is read only to check forexport_slot_not_found. Proxy failures keep their own codes (503for not connected or no credential,502otherwise). Audited asinstances_fetch_session.Imported/from <crew name>,(from <crew name>)), not under anyoriginin the crew's bytes.install_peer_exportpasses it asorigin_override, and only this route sets it; every other arrival keeps the origin from its own bundle. The crew's export leavesoriginempty, and the crew's bytes are untrusted, so the hub's name is the one a reader can rely on.400for a bundle it cannot read (transfer_body_unreadable,transfer_invalid_gzip,transfer_invalid_json, a validation code). Here that bundle is the crew's reply, not the caller's request, so the route re-answers it as502and keeps the arrival'scode(_peer_bundle_failure). The caller's own body (the slot key) is still a400.dashboard.export_include_layer_band the request is the owner's. A minted token's subject is the crew's owner, so the pull qualifies;test_the_hubs_minted_credential_reaches_the_crews_export_as_its_ownerdrives that chain (see Tests). Otherwise the arrival is transcript-only and the import'sresume_modesays so.send-session, before the catch-all proxy route.instances.md§14.4 gets the route row and its contract; §14.6 no longer calls the pull a follow-on.Backwards compatibility
Compatible: one new route. The import route reads its own request body exactly as before, because
sourcedefaults to the request.Removes nothing: the diff adds a route and an optional parameter, and changes no existing contract.
Tests
In
test/test_session_transfer_fetch.py(its own file since #22132 split the old suite by topic):test_fetch_session_installs_the_peers_export_as_a_new_local_slot: the hub asks the crew's export route withinclude_layer_b=true, and a gzipped export arrives as one new local slot.test_fetch_session_refuses_a_slot_key_that_could_leave_the_export_path:../status,chat/1, empty, over-long and%2e%2eare refused with400and never reach the crew.test_fetch_session_names_the_sender_from_the_hub_not_the_crews_bytes: a crew-suppliedorigindoes not choose the folder or the title.test_fetch_session_maps_a_missing_peer_session_to_404: only with the export's ownexport_slot_not_found; no slot is created.test_fetch_session_does_not_read_a_crew_without_the_route_as_a_missing_session: a bare 404 is502 transfer_peer_refusedwithpeer_status: 404and nothing else.test_fetch_session_relays_the_status_of_an_export_refusal_and_nothing_else: each of the export's refusals arrives as itspeer_statusonly.test_fetch_session_maps_only_the_exports_own_404_to_a_missing_session: a 404 with another code, an over-long body or non-JSON is a refusal, not a missing session.test_fetch_session_blames_the_peer_not_the_caller_for_a_bad_bundle: a corrupt gzip or malformed export from the crew is a502keeping the arrival's code.test_fetch_session_relays_only_the_status_of_a_peer_refusal: a credential-shaped string in the crew's refusal body does not appear in the response.test_fetch_session_reports_a_peer_that_is_not_connected:503 proxy_peer_not_connected.test_fetch_session_is_owner_only: an app token is refused before the crew is asked anything.test_the_hubs_minted_credential_reaches_the_crews_export_as_its_owner: the premise the Layer B claim rests on, with no stub between the steps. The crew's real/api/token/localmint (whatkirocrew tokencalls), the manager's link exchange (GET /api/status?token=, keeping the port-scoped cookie) and the export request with that cookie through the crew's realtoken_auth_middleware; the export's own gate,is_owner_dashboard_request, answers true. Covered for both owner shapes: a configured owner id, and none (local-app).test_session_export.py::test_an_export_carries_layer_b_on_explicit_opt_incovers the other half (owner + flag + operator setting -> Layer B).Mutation check: dropping the
sourcepass-through in_read_bundle_bodyfails the arrival test, and dropping the slot-key check fails the traversal test. Minting for any other subject fails the premise test (both cases); treating any 404 as a missing session, reading a 404 past the cap, and relaying any field beyondpeer_statuseach fail their test.Run locally:
test/test_session_transfer.py(262 passed),test/test_dashboard_route_table.pyandtest/test_dashboard_server_composition_contract.py(113 passed),test/test_error_code_contract.py,test/test_instances.pyandtest/test_remote_crew_peer_slots.py(528 passed). Fivetest_instances.pyforwarder-identity tests fail the same way on unmodified main in my environment, because the sandbox cannot read process start-time identity; they are unrelated to this diff.scripts/check_feature_map.pyagainst origin/main passes, and black is clean.After the rebase onto main d06b611 (head 443ff30): the only conflict was the route block in
routes/connections.py, where main addedcrew-turnat the same spot; both routes are kept. Re-run:test_session_transfer.py, the route-table and composition-contract tests (120 passed), feature-map gate clean.After the rebase onto main 75726a8 (head efc7f4a): the only conflict was the feature-map row, where main renamed
pages/ChatSidebar.tsxtopages/chat-sidebar/SessionRow.tsx; main's row is kept with this PR's three additions. Re-run:test_session_transfer.py,test_error_code_contract.py, the route-table and composition-contract tests (389 passed),test_remote_crew_peer_slots.py(45 passed), feature-map gate, black, flake8 and mypy clean.Head d625163 (same base):
peer_codeand its allowlist are removed (First Principles item 3, no reader); a refusal carriespeer_statusonly. Re-run:test_session_transfer.py, thetest_instances*files and the three error-code contract tests (890 passed; the 5 failures are forwarder-process tests that fail identically on efc7f4a in this sandbox and are untouched), black, isort, flake8 and mypy clean.After the rebase onto main 5d1a459 (head 43fb15c, now 1bb5ee6): #21111 split
session_transfer.pyandhandlers_instances.pyinto owners. Nothing in the behaviour changed. The changes moved with the code:sourceon_stalling_chunks/_stream_request_to_file/_read_bundle_bodyis now insession_transfer_intake.py,install_peer_exportand the_install_arrived_bundlekeywords are insession_transfer_install.py, and the route with_FETCH_SLOT_KEY_RE,_peer_slot_is_missingand_peer_bundle_failureis inhandlers_instances_peer.py("the routes that read a peer", per the facade's owner list). All of them are in the facades'TYPE_CHECKINGlists. Re-run:test_session_transfer.py,test_handlers_instances*and the facade tests (3444 passed; the only 6 failures are intest_pod_runtime_refactor_facade.py, which my sandbox refuses ascratchdirectory for, and which this PR doesn't touch), plus mypy, black, flake8, docs-lint and the feature-map gate. At 1bb5ee6,_peer_slot_is_missingreads the crew's 404 through the existingread_capped_responseinstead of its own chunk loop (First Principles blocker on 43fb15c). Removing the cap check turns 2 fetch tests red.After the rebase onto main 453cc4b (head 3eb7987): #22132 split
test/test_session_transfer.pyby topic, so this PR's fetch-session section, its helpers and the credential-premise tests moved unchanged into a newtest/test_session_transfer_fetch.py; it imports the shared helpers fromsession_transfer_helpersand keeps its own copy of the six-line_filed_folder. No source change. Re-run: thetest_session_transfer*andtest_handlers_instances*files and thetest_instances*files (898 passed); 5 failures intest_instances_orphan_reclaim.pyandtest_instances_forwarder_hints.py, which this PR does not touch, need a readable process start time that this sandbox does not give. mypy, flake8, docs lint and the feature-map check are clean.Rebased onto main f0d0cd2 (head 15e419d) because main changed the feature-map row this PR extends; the row keeps main's text plus our three insertions, and nothing else moved. Before that: rebased onto main f62ab4f (head 3e6a734) only to pick up #22433: the run on 3eb7987 failed in
test_chat_follow_default_slot_kinds.py, which main had broken by moving_import_thread_to_slotand fixed in #22433. No conflicts and no change to this PR's patch; the fetch tests,test_session_transfer.py, that slot-kinds file and thetest_handlers_instances*files (85) pass, as do mypy, flake8, docs lint and the feature-map gate.Manual verification
Not yet run against a live crew. The credential premise is now covered in-process (see Tests); what only a live run adds is the real tunnel and the crew's real export bytes. Planned, and posted on this PR when run: connect a crew, call the route for one of its sessions with the crew's
export_include_layer_bon, and check that the arrival'sresume_modereports a full resume and that the session continues with its context. Whether that run gates the merge is the open maintainer decision.Related Issues
Follow-on named in
docs/system-specs/modules/instances.md§14.6.Checklist
Contribution License Agreement
Contributed under the project's Apache-2.0 license.
Live run: the two-gateway run is tracked in #30231, so it can be deferred without holding this PR.