Repository navigation
feat(pi): steer a running pi turn through Crew's gate extension - #22923
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: a live pi-acp 0.0.34 / pi 1.3.0 capture shows the steer reaching the model inside the same turn, and the change only adds a path. Notes
[DESIGN-REVIEWED] e0c25ee Description read[DESCRIPTION-READ] d7cb9036c85c4ffba1af1c60e166d5306b11c2c31e9a2024a4153d66a7872d9f 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. Every item serves the frozen Goal, the steer reuses the existing pi gate leaf, publisher and extension seal reader, and pi's own Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: let a pi user correct a running turn from the dashboard composer, so the model reads the correction in that same turn. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] e0c25ee Description read[DESCRIPTION-READ] 74a32283dc56ae1015f219e7b54fe8cd63c1119851ab3867743c8074565ddb78 That sha256 names the PR description this verdict read. 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: |
15eb642 to
8def4be
Compare
8def4be to
44e404d
Compare
44e404d to
e0c25ee
Compare
|
HOLD for human security review. Reviewed head e0c25ee. This PR adds a new way for text to enter a running pi turn: the gateway writes sealed files into the owner-only pi gate leaf, and Crew's tool-gate extension queues them as user messages. It also adds a per-launch AES-GCM key to the pi child's environment and re-pins the gate extension digest. Changes to the gate extension and to agent input paths are reserved for a human reviewer, so I am not approving. In what I read I found no definite defect. The seal binds nonce, session and sequence (pi_steer.py#L113), and the extension delivers only after a completed turn and never below its floor (kiro_crew_tool_gate.ts#L419). Also needed before approval: reply to the current-head lane notes. The concrete one is the Design note that the consumed signal depends on — crew-pr-reviewer (r119) |
Problem / Motivation
Goal: Users can add a message to a running pi turn from the dashboard composer, and the model reads it inside that same turn.
pi is the only selectable harness whose card reports "You can add a message while it works" as unavailable. pi-acp 0.0.34 (the adapter Crew installs) has no steer verb. A second
session/promptsent while a turn runs lands in pi-acp'sturnQueueand runs as a new turn after the current one (dist/index.js,PiAcpSession.prompt). So every mid-turn message on pi waits for the whole turn and then runs as its own turn.Why it matters
Correcting a running pi agent ("not that file", "also check X") means waiting out the full turn or cancelling it and losing the work. On every other harness Crew offers the steer. pi users get the queue fallback only.
Not a goal
_session/steeringverb in svkozak/pi-acp was declined, and@openma/pi-acpis a different package Crew does not install. Closed feat(pi): steer mid-turn messages over pi-acp _session/steering #21740 took that route.supports_refusal_steerstays False, and pi stays out ofACP_BACKENDS_STEER. A pi denial already reaches the model inside the same turn, as the blocked call's own error result.spawn_steeron pi. pi joinssteer_needs_loss_recoverylike goose, so those surfaces keep queueing. Only the dashboard composer steers.What changed (motivation → approach → change)
Goal: get the text into pi's own steering queue (
agent.steer), which pi's agent loop reads before its next model call in the same run (pi-agent-coreagent-loop.js).Approach: Crew already loads its own gate extension into every pi session, and pi's extension API can queue a steer. So the gateway hands each steer straight to that extension through a sealed file channel, and pi-acp is bypassed. Two alternatives were rejected:
session/promptbecomes a follow-up turn, not a steer.pi.sendUserMessage(text, {deliverAs: "steer"}), from the agreed sketch, awaits pi's input handlers before it queues. Its steer can therefore miss the read before the next model call and surface in the next run, or start a run of its own once pi goes idle. The independent security review upheld this.The extension therefore uses
pi.sendMessage({customType: "kiro-crew-steer", …}, {deliverAs: "steer"}), which reachesagent.steerwith no await. pi hands a custom message to the model as a user message (messages.jsconvertToLlm), so the model sees the same thing either way. Verified against the pinned pi 1.3.0 package source and the live capture below.Change:
acp/harness/pi_steer.py(new):PiSteerChannelholds a per-launch key, seals each steer bound to its nonce, pi session and sequence number, publishes it into the pi gate leaf, and discards the files. It also providessteer_echo_seq.acp/pi_steer_turn.py(new): the client's half. It opens the channel per prompt turn and writes a steer only while that turn is open. It reads the extension's consumed notification back out of the stream asEVENT_STEER_CONSUMED, so the notification never shows as text. It removes every steer file at the turn's terminal, under one lock with the write.gate_extensions/pi/kiro_crew_tool_gate.ts: the steer reader onturn_end, the consumed notify onmessage_start, and retiring leftover steers onagent_settled. The extension digest is re-pinned inharness/pi.py.harness/pi.py:PiLaunchmints the channel beside the gate nonce and passesKIROCREW_PI_STEER/KIROCREW_PI_STEER_KEYin the child's environment.client_turn_control.py/client_turn.py/client_class.py/harness/base.py: wiring only.steer()routes pi to the new module._steering_request_readyanswers for pi from its channel.backends_turns.py: pi joinsACP_BACKENDS_STEERING_REQUEST. The membership comment citesacp_frames/pi/steering-live.jsonl.harness-parity.md,harness-onboarding.md,messaging.md, and the pi fixtures README.Security boundary: the pi steer channel
This PR adds a new input path into a running pi process: text the gateway writes is injected into the running turn as a user message. It goes through Crew's own gate extension inside pi (
pi.sendMessage(message, {deliverAs: "steer"})), which pi converts to a user message for the model. pi-acp is bypassed.Who can write the channel. Only the gateway.
<config_dir>/pi-gate/. That is the existing owner-only (0700) leaf that already holds the sealed gate extension, the launcher and the MCP handoff._pi_gate_artifact_dir()and refuses on any mismatch. That call checks the leaf is a real directory (not a symlink or junction), is owner-only, and resolves to the path the launch verified.security/paths_lists.pyentry, unchanged.How a message is authenticated.
os.urandomand is minted per launch (perPiLaunch.resolve_spawn). It is carried only in that pi process's environment (KIROCREW_PI_STEER_KEY) and never written to disk.kiro-crew-steer \0 <gate nonce> \0 <pi session id> \0 <seq>.kirocrew_pi_gate_<gateway pid>_steer_<nonce>_) and a 10-digit sequence number;ctx.sessionManager.getSessionId()./proc/<pid>/environ). File names do expose each launch's nonce, which authenticates nothing on its own.Replay and ordering.
turn_endit delivers the single lowest-numbered valid steer above the floor and raises the floor to it.When no turn is running.
On the client side:
_pi_steer_turnset by_dispatch_prompt_events,_turn_donenot set, not cancelled). It writes under the same lock that closes the turn.steer(), however many cancels arrive, waits its write out and removes the file before releasing the lock.finally, removes every file in the directory that carries this launch's stem, after any write in flight lands.finallyruns only after the next turn has opened, it leaves that turn's files alone; their own terminal removes them.On the extension side:
turn_endwhose outcome iscompleted, whose message did not stop witherrororaborted, with no aborted signal and pi not idle.pi.sendMessage, whose path toagent.steercontains no await. The streaming check and the enqueue happen in the same synchronous step, inside theturn_endboundary that pi awaits before it reads the queue.triggerTurn, so it never starts a run of its own.turn_endand before the next model call of the same run. NofinishTurnin 1.3.0 ends a run at that point.steer_needs_loss_recovery).Consumed echo.
ctx.ui.notify('{"kiro-crew-steer":1,"nonce":…,"seq":N}'). It identifies the message by itscustomTypeand the sequence number in itsdetails, never by text.agent_message_chunkcarrying_meta.piAcp.notify.EVENT_STEER_CONSUMEDand swallows the frame, so the notify never appears as turn text.Bounds.
\uescapes, so a steer at the bound stays under the 512 KiB file size the extension reads.Cleanup on session end.
finally.kirocrew_pi_gate_<pid>_*.jsonfamily, keyed on a dead pid, already covers them.Fresh-context security review. Two rounds, each a separate
spawn_runsubagent on GPT 5.5, given only the diff, this statement, and the pinned pi / pi-acp sources.Round 1 upheld three findings, all fixed:
sendUserMessagecould miss the queue read, land in the next run, or start a run while pi was idle. Fixed by moving tosendMessage.Round 2 confirmed 1 and 3 fixed and upheld two more, both fixed:
4. A second cancel skipped the undo. Every further cancel is now absorbed until the write and its removal finish.
5. An old turn's late
finallydeleted the next turn's files. The close now runs only for its own turn.Its remaining notes were informational: the
/proc/environassumption, now stated above; that a mismatched pi session id fails closed and queues the steer; and an in-memory floor that resets on an extension reload, which nothing triggers mid-run today.Sensitive change: none. No Sensitive Change Review-watched file is touched; every changed path was checked with fnmatch against
SENSITIVE_GLOBSin.github/scripts/sensitive_change_review.py. The steer files reuse the existing pi-gate leaf, its read-only mount, its file-tool fence and its sweep family, with no new path or sandbox entry.Backwards compatibility
Compatible: purely additive. pi gains a steer channel. Every other harness's steer routing is untouched. A pi session without a channel (none minted) reports
supports_steerFalse, as before.Removes nothing: no validator tightened and no key, path, record or public function removed or renamed. The extension's digest pin moves with its bytes, as every extension edit does.
Sibling pi PRs: #22883 and #22808 merged while this was in flight. This branch is rebased on both. The only conflicts were an import union in
harness/pi.pyand a table-row union intest/fixtures/acp_frames/pi/README.md, andgit range-diffshows this patch unchanged apart from context.Tests
test/test_pi_steer.py(new, 28): the channel and the client's half.env(), and a refused moved directory or symlink swap, with the leaf re-secured to 0700.steer_echo_seqaccepts only the exact envelope.supports_steer,steer_needs_loss_recoveryandsupports_refusal_steerfor pi._dispatch_prompt_events. Files are gone at the terminal.discardremoves by stem. An astral-character steer at the bound fits. A failed write holds nothing.test/test_pi_gate_extension_steer.py(new, 16, Node,real_adapter): the shipped extension against a stand-in pi.triggerTurn, and never on an idle agent. Its start is echoed.turn_end.steering-live.expected.json, plus api_steer_consumedkey inacp_frame_replay_harness.py, pins the parser on the capture.ACP_BACKENDS_STEERING_REQUESTset equality (test_codex_steering_request.py), the client-spawnable verb coverage (test_goose_steer_request.py), the pi card count 5→6 (test_backend_cards.py), the X-capture mutation pin (test_x_feature_captures.py), the pi spawn env (test_acp_pi_backend_spawn.py), and the launch golden (the steer stem and key are volatile values).triggerTurn;test_codex_session_mcp::test_the_installed_adapter_still_builds_the_frames_the_refusal_reads, and it fails identically on a clean main worktree on this host because of the installed adapter.test_kas_bundle.py(glibc 2.26 on this host) was excluded for the same reason. After the rebase onto fix(pi): run pi under a Node that meets its engine floor #22883: 1,631 passed in the pi, steer and corpus subset.HARNESS_BASE_REF=origin/main(including the X-capture gate), file line cap, frame host-data, black, isort, flake8, mypy. No user strings were added, soi18n:checkdoes not apply.Manual verification
Live capture through Crew's own
AcpClientandPiLaunch. pi-acp 0.0.34 and pi 1.3.0 were installed into a scratch npm prefix (the global pi was not touched), with a scripted OpenAI-compatible model on loopback named in a scratchmodels.json. The recording host refuses user namespaces, so the capture driver ran the session withsandbox_mode="off"and neutered the floor that refuses an unsandboxed pi. That change is in the driver only; nothing insrc/differs for it.The model called
bashwithsleep 4 && echo done, and the client approved the gate's permission request. One second in, the client steered "Also tell me the word PINEAPPLE." andsteer()returned True. After the tool result, the extension queued the steer atturn_endand the client sawEVENT_STEER_CONSUMED. The model's next request carried the steer as its latest user message, and it answered "Steer received: PINEAPPLE." in the samesession/prompt, which endedend_turn. No steer file was left in the pi-gate directory afterwards. The frames are intest/fixtures/acp_frames/pi/steering-live.jsonl. The session id, the dialog uuid and the project path were normalized at capture, per the corpus README.Related Issues
No linked issue. Prior art: closed #21740 (pi steer over a pi-acp
_session/steeringverb), whose reviewers asked for a route the installed adapter actually serves. This is that route.Pattern harvest
Rule candidate: review-prompt
Pattern: an extension API that queues work "while streaming" must reach its enqueue with no await after the streaming check; otherwise the work can land after the run boundary it was meant for (here
pi.sendUserMessageawaits input handlers before deciding steer-vs-new-run).Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.