Skip to content

feat(pi): steer a running pi turn through Crew's gate extension - #22923

Merged
iamwhatever merged 2 commits into
mainfrom
feat/pi-steer
Oct 23, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
feat/pi-steer

Conversation

@kyleseaman

@kyleseaman kyleseaman commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

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/prompt sent while a turn runs lands in pi-acp's turnQueue and 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

  • No upstream pi-acp change. The _session/steering verb in svkozak/pi-acp was declined, and @openma/pi-acp is a different package Crew does not install. Closed feat(pi): steer mid-turn messages over pi-acp _session/steering #21740 took that route.
  • No deny-notice steering for pi: supports_refusal_steer stays False, and pi stays out of ACP_BACKENDS_STEER. A pi denial already reaches the model inside the same turn, as the blocked call's own error result.
  • No steer from messaging channels, Side Chat or spawn_steer on pi. pi joins steer_needs_loss_recovery like 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-core agent-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:

  • A second session/prompt becomes 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 reaches agent.steer with no await. pi hands a custom message to the model as a user message (messages.js convertToLlm), 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): PiSteerChannel holds 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 provides steer_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 as EVENT_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 on turn_end, the consumed notify on message_start, and retiring leftover steers on agent_settled. The extension digest is re-pinned in harness/pi.py.
  • harness/pi.py: PiLaunch mints the channel beside the gate nonce and passes KIROCREW_PI_STEER / KIROCREW_PI_STEER_KEY in 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_ready answers for pi from its channel.
    • The turn opens and closes the channel.
    • The read loop swallows the notify.
    • The client gets three state fields.
  • backends_turns.py: pi joins ACP_BACKENDS_STEERING_REQUEST. The membership comment cites acp_frames/pi/steering-live.jsonl.
  • Docs: 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.

  • Each steer is one file in <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.
  • Every write re-runs _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.
  • The sandbox mounts that leaf read-only into pi and DeepSeek children and withholds it from every other child. The agent's own file tools are fenced from it by the existing security/paths_lists.py entry, unchanged.
  • So the pi agent, its tools and every other session can read the directory, but none can create, replace or rename a file in it.
  • Files land 0400 through a mkstemp stage and an atomic rename, so the extension never reads a partial file.

How a message is authenticated.

  • Each steer is sealed with AES-256-GCM. The 32-byte key comes from os.urandom and is minted per launch (per PiLaunch.resolve_spawn). It is carried only in that pi process's environment (KIROCREW_PI_STEER_KEY) and never written to disk.
  • The associated data is kiro-crew-steer \0 <gate nonce> \0 <pi session id> \0 <seq>.
  • The extension delivers a file only when all of these hold:
    • its name carries this launch's stem (kirocrew_pi_gate_<gateway pid>_steer_<nonce>_) and a 10-digit sequence number;
    • the body's marker, nonce and sequence number match;
    • the seal opens under its own key;
    • the sealed body's sequence number and session equal the name's sequence number and pi's own ctx.sessionManager.getSessionId().
  • So a file sealed under another key, for another nonce or another session, renamed to another sequence number, or copied from another launch does not open.
  • Sibling sessions that can read the directory see ciphertext only. That rests on the same assumption the existing MCP handoff key rests on: a sibling pi child cannot read this pi process's environment (/proc/<pid>/environ). File names do expose each launch's nonce, which authenticates nothing on its own.
  • The session's own agent can read its own key from its environment, as it can the MCP handoff key. It still cannot write the directory, so it cannot inject.
  • A same-uid process outside the sandbox is outside this model: it could already read the pi process's environment.

Replay and ordering.

  • Sequence numbers are strictly increasing per launch and assigned under the client's write lock.
  • The extension keeps a floor. At each eligible turn_end it delivers the single lowest-numbered valid steer above the floor and raises the floor to it.
  • So a file is delivered at most once, and steers arrive in write order, one per model call. A replayed, re-landed or renamed file at or below the floor never delivers.

When no turn is running.

On the client side:

  • The client writes only while one of its own prompt turns is open (_pi_steer_turn set by _dispatch_prompt_events, _turn_done not set, not cancelled). It writes under the same lock that closes the turn.
  • The write runs in a thread that is shielded from cancellation and awaited under the lock. So a cancelled steer(), however many cancels arrive, waits its write out and removes the file before releasing the lock.
  • The turn's terminal, and every other exit through a finally, removes every file in the directory that carries this launch's stem, after any write in flight lands.
  • If an old turn's finally runs only after the next turn has opened, it leaves that turn's files alone; their own terminal removes them.

On the extension side:

  • It queues a steer only at a turn_end whose outcome is completed, whose message did not stop with error or aborted, with no aborted signal and pi not idle.
  • It queues through pi.sendMessage, whose path to agent.steer contains no await. The streaming check and the enqueue happen in the same synchronous step, inside the turn_end boundary that pi awaits before it reads the queue.
  • It never passes triggerTurn, so it never starts a run of its own.
  • pi 1.3.0's agent loop reads that queue right after turn_end and before the next model call of the same run. No finishTurn in 1.3.0 ends a run at that point.
  • When a run settles, every steer still on disk is retired (the floor is raised past it), so a steer is never read into a later turn. The client reports it unconsumed and the composer queues it (steer_needs_loss_recovery).

Consumed echo.

  • When pi starts the steer message, the extension calls ctx.ui.notify('{"kiro-crew-steer":1,"nonce":…,"seq":N}'). It identifies the message by its customType and the sequence number in its details, never by text.
  • pi-acp forwards the notify as an agent_message_chunk carrying _meta.piAcp.notify.
  • The client accepts only that exact shape:
    • the notify marker, which model text never carries;
    • exactly those three keys;
    • this launch's nonce;
    • a sequence number it has pending in the open turn.
  • It reports EVENT_STEER_CONSUMED and swallows the frame, so the notify never appears as turn text.
  • A forged echo could at most mark a pending steer consumed so it is not requeued, and producing one requires an extension running inside pi.

Bounds.

  • Text is at most 64,000 characters, with at most 16 pending steers per turn. These are the shared steering bounds, checked under the write lock.
  • The plaintext is UTF-8, not \u escapes, so a steer at the bound stays under the 512 KiB file size the extension reads.

Cleanup on session end.

  • No steer file outlives its turn: each is removed at the turn's terminal and in its finally.
  • A respawn mints a new channel with a new nonce and key.
  • The existing pi-gate leaf sweep reclaims the files of a gateway that died: its kirocrew_pi_gate_<pid>_*.json family, keyed on a dead pid, already covers them.

Fresh-context security review. Two rounds, each a separate spawn_run subagent on GPT 5.5, given only the diff, this statement, and the pinned pi / pi-acp sources.

Round 1 upheld three findings, all fixed:

  1. sendUserMessage could miss the queue read, land in the next run, or start a run while pi was idle. Fixed by moving to sendMessage.
  2. A cancelled write could leave a file that was delivered into a later turn. Fixed with a shielded write that is waited out and undone, and a discard that removes by stem.
  3. Escaped astral characters could exceed the 512 KiB cap. Fixed by writing the plaintext as UTF-8.

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 finally deleted the next turn's files. The close now runs only for its own turn.

Its remaining notes were informational: the /proc/environ assumption, 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_GLOBS in .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_steer False, 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.py and a table-row union in test/fixtures/acp_frames/pi/README.md, and git range-diff shows this patch unchanged apart from context.

Tests

  • test/test_pi_steer.py (new, 28): the channel and the client's half.
    • The channel: sealing, AAD binding to key, nonce and session, the file name and 0400 mode, env(), and a refused moved directory or symlink swap, with the leaf re-secured to 0700.
    • steer_echo_seq accepts only the exact envelope.
    • supports_steer, steer_needs_loss_recovery and supports_refusal_steer for pi.
    • Write and echo through _dispatch_prompt_events. Files are gone at the terminal.
    • An unread steer is left to the caller, and a late echo in the next turn settles nothing.
    • Model text that spells the envelope stays text; an echo under another nonce stays text.
    • No write without an open turn, or after the turn ended or was cancelled. The text and count bounds hold.
    • A close waits out a racing write. A steer cancelled once or twice undoes its write. A late close leaves the open turn's files.
    • discard removes by stem. An astral-character steer at the bound fits. A failed write holds nothing.
    • The live capture replayed through the client's real read loop.
  • test/test_pi_gate_extension_steer.py (new, 16, Node, real_adapter): the shipped extension against a stand-in pi.
    • A steer is queued as a steer, never with triggerTurn, and never on an idle agent. Its start is echoed.
    • Steers go oldest first, one per turn_end.
    • Another key, another nonce, another session, or a renamed file never delivers.
    • A delivered steer never delivers again.
    • No steer at an aborted or error outcome, an aborted or error stop, an aborted signal, or while idle.
    • A steer is retired at settle.
    • A user message with the same text is not an echo, and nothing is echoed after settle.
  • steering-live.expected.json, plus a pi_steer_consumed key in acp_frame_replay_harness.py, pins the parser on the capture.
  • Re-pinned: ACP_BACKENDS_STEERING_REQUEST set 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).
  • Mutation check: 28 of 28 guard mutants fail a test, each with the guard removed one at a time. They cover:
    • seal authentication and the sequence number in the name;
    • the floor and retire-at-settle;
    • aborted, error and idle turns, the abort signal, and triggerTurn;
    • the echo for an undelivered or retired steer, and echo matching by marker and nonce;
    • no open turn, an ended or cancelled turn, and the text and count bounds;
    • the shielded write, single and double cancel undo, and the late-close scope;
    • the stem discard, the UTF-8 plaintext and the strict marker type;
    • the directory re-check, the close lock and close at the terminal;
    • the read loop's swallow of the notify.
  • Focused run: 9,579 passed across every test file that touches the steer sets, pi, the frame corpus, the client facades or the launch goldens. One test fails, 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.
  • Diff-scoped gates pass: brand, comment-history, harness parity with 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, so i18n:check does not apply.

Manual verification

Live capture through Crew's own AcpClient and PiLaunch. 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 scratch models.json. The recording host refuses user namespaces, so the capture driver ran the session with sandbox_mode="off" and neutered the floor that refuses an unsandboxed pi. That change is in the driver only; nothing in src/ differs for it.

The model called bash with sleep 4 && echo done, and the client approved the gate's permission request. One second in, the client steered "Also tell me the word PINEAPPLE." and steer() returned True. After the tool result, the extension queued the steer at turn_end and the client saw EVENT_STEER_CONSUMED. The model's next request carried the steer as its latest user message, and it answered "Steer received: PINEAPPLE." in the same session/prompt, which ended end_turn. No steer file was left in the pi-gate directory afterwards. The frames are in test/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/steering verb), 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.sendUserMessage awaits input handlers before deciding steer-vs-new-run).

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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@kyleseaman
kyleseaman requested review from a team and KiroCrewCaptain as code owners October 21, 2026 22:13
@kyleseaman
kyleseaman requested a review from mbriones98 October 21, 2026 22:13
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 21, 2026
@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision e0c25ee07eaa2bb1ebf158a88bc1c5b8a544c1bd 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 Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • The "consumed" signal goes through ctx.ui.notify, guarded by if (ctx.hasUI). If a pi build runs the extension without UI, no consumed event comes back. The model still reads the steer, but loss recovery then queues it again as the next turn, so the message is delivered twice. Either pin hasUI in the frame-replay test or report "consumed" in a way that doesn't depend on UI.
  • Only one steer is delivered per turn_end. If several steers are written before the last model call, the later ones fall to the queue path. That's acceptable, but the dashboard copy should not suggest every mid-turn message lands in the same turn.

[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 .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 Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of e0c25ee07eaa2bb1ebf158a88bc1c5b8a544c1bd — 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. Every item serves the frozen Goal, the steer reuses the existing pi gate leaf, publisher and extension seal reader, and pi's own agent.steer queue is the fix at the mechanism level.

Notes

  • Item 6 — duplicate of src/kiro_crew/acp/harness/pi.py:691-701: PiSteerChannel.seal restates the MCP handoff's AES-GCM seal and base64 body inline. The TS side shares one reader, openSeal(record, aad, keyEnv), but the Python side now has two sealers. Subtraction: have one seal helper in pi.py take aad and replace both inline blocks with it.

What this change ships

Inventory (8 items) — 7 justified

Intent: 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.

  1. A dashboard composer message sent during a pi turn now reaches that turn instead of running as the next turn — justified
  2. The pi backend card now shows "You can add a message while it works" as available — justified
  3. The pi child gets two new environment variables, KIROCREW_PI_STEER and KIROCREW_PI_STEER_KEY, and the gate leaf gets sealed per-launch steer files — justified
  4. The gate extension delivers one steer per turn_end and drops leftover steers when the run settles — justified
  5. The extension's "consumed" notify is hidden from the transcript and reported as steer-consumed — justified
  6. A second AES-GCM sealer in Python, beside the MCP handoff's — duplicate of pi.py handoff seal
  7. pi joins ACP_BACKENDS_STEERING_REQUEST and loss recovery, so channel, Side Chat and spawn_steer messages still queue — justified
  8. The gate extension digest is re-pinned — justified

[FIRST-PRINCIPLES-REVIEWED] e0c25ee

Description read

[DESCRIPTION-READ] 74a32283dc56ae1015f219e7b54fe8cd63c1119851ab3867743c8074565ddb78

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 Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] e0c25ee

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable e0c25ee07eaa2bb1ebf158a88bc1c5b8a544c1bd: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] e0c25ee

False positive or not applicable? A repository writer can comment:
/ai-review override gpt e0c25ee07eaa2bb1ebf158a88bc1c5b8a544c1bd: <one-sentence reason>

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 21, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 21, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 22, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

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 ctx.hasUI (L446). Without a UI no consumed event returns, so loss recovery would deliver the steer twice. Either pin hasUI in the replay test or show it always holds under pi-acp. Also answer the one-steer-per-turn_end note and First Principles item 6 (a second Python AES-GCM sealer beside the MCP handoff's).

— crew-pr-reviewer (r119)

@iamwhatever
iamwhatever merged commit 384a090 into main Oct 23, 2026
155 of 156 checks passed
@iamwhatever
iamwhatever deleted the feat/pi-steer branch October 23, 2026 06:04
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 23, 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