Pi runtime adapter and TS facade boundary

[devkade]

Summary

Implement the first Pi runtime adapter boundary for the #236 single-session TaskStream MVP.

Parent: #236

Scope

Create crates/runtime-pi package ilchul-runtime-pi.

Implement:

RuntimeAdapter for Pi
prompt projection from RunContract
runtime output normalization
turn/output observation
artifact inbox integration

Keep existing TS/Pi extension surfaces as facades/shims where needed.

Boundary

Pi adapter may produce RuntimeOutput, TurnObservation, artifact refs, and evidence candidates. It must not decide completion or directly mutate canonical state.

Acceptance criteria

• Pi adapter implements core RuntimeAdapter port.
• Prompt projection includes mission, boundary, evidence, verification, handoff.
• Runtime output is normalized.
• Runtime output cannot mark a run completed.
• TS facade boundary is documented.

[devkade]

AI-understood issue summary

Issue #244 is the Pi runtime-adapter slice of the #236 single-session TaskStream MVP. The implementation agent will add crates/runtime-pi / ilchul-runtime-pi as the first concrete RuntimeAdapter implementation, project a core RunContract into a Pi prompt, observe and normalize Pi runtime output, surface artifact refs/evidence candidates, and keep TS/Pi extension code as a facade. The boundary is the key point: Pi output may inform the kernel, but it must never decide completion or mutate canonical TaskStream/Run state directly.

Why this issue is needed

• SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 requires a replaceable runtime adapter boundary so the Rust core can own TaskStream state, evidence, verification, and completion decisions while Pi remains one selected runtime session.
• The current repo already has Pi/tmux launch and observation behavior, but it is TypeScript-side runtime glue (src/adapters/pi-runtime.ts:50, src/adapters/pi-runtime.ts:58, src/adapters/pi-runtime.ts:80, src/adapters/pi-runtime.ts:97) rather than a Rust RuntimeAdapter port implementation.
• Existing docs say runtime/presentation adapters should only show or interpret generic status, while core owns generic run projection/evidence/artifact/completion semantics (README.md:230, README.md:231, README.md:232, README.md:236). Pi runtime adapter and TS facade boundary #244 turns that existing design principle into an enforceable Pi adapter boundary.
• The adapter is also needed to preserve thin Pi behavior: existing Pi affordances explicitly avoid taking over ordinary turns and enforce mutation control through prompts/artifacts/completion validation rather than broad live blocking (README.md:271, README.md:275, README.md:277).

Why this issue may not be needed

• If maintainers only want the current Kapi/Pi harness, the TS implementation already launches Pi, probes readiness, dispatches prompts, records evidence, writes artifacts, and exposes start/status/evidence/complete tools (src/adapters/pi-runtime.ts:58, src/adapters/pi-runtime.ts:80, src/presentation/tools.ts:81, src/presentation/tools.ts:262, src/presentation/tools.ts:287, src/presentation/tools.ts:345).
• If runtime output observation is only needed for supervisor hints, current observeRuntimeFromTmux already classifies live panes, candidate completion-looking output, failures, and recommended actions without directly completing state (src/cli/worker-runtime.ts:53, src/cli/worker-runtime.ts:57, src/cli/worker-runtime.ts:63, src/cli/worker-runtime.ts:67).
• However, those existing surfaces are still TypeScript/Pi-first and can mutate workflow state through TS tools (src/presentation/tools.ts:287, src/presentation/tools.ts:301, src/presentation/tools.ts:302). Pi runtime adapter and TS facade boundary #244 remains needed if SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236's Rust core is the intended canonical authority.

Expected Outcome

After approval and implementation, the repo should have:

1. A new Rust crate at crates/runtime-pi named ilchul-runtime-pi.
2. A Pi adapter implementing the core RuntimeAdapter port from the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236/Core services and explicit port contracts #240 core-service work.
3. A prompt-projection function that maps RunContract into a Pi-ready prompt with explicit mission, boundary, evidence, verification, and handoff sections.
4. A normalized runtime-output model that distinguishes progress, candidate evidence, artifact refs, errors, and handoff/completion-looking claims without producing CompletionDecision.
5. Turn/output observation that can summarize bounded Pi/tmux output into TurnObservation / RuntimeOutput records.
6. Artifact inbox integration where Pi-produced raw logs/transcripts/diffs/test output become controlled artifact refs and evidence candidates, not canonical state mutations.
7. TS/Pi extension surfaces documented as facades/shims that call into the Rust/MCP/kernel boundary rather than owning completion authority.
8. Tests proving Pi output cannot mark a run completed and adapter-specific tmux/Pi details do not leak into generic core records.

Evidence-based implementation plan

Feasibility from in-repo research

Reusable code exists; this is not a greenfield adapter.

• Current Pi launch/probe/dispatch behavior is concentrated in TmuxPiRuntimeLauncher, including launch input/result types, readiness probing, prompt dispatch, and probe behavior (src/adapters/pi-runtime.ts:4, src/adapters/pi-runtime.ts:36, src/adapters/pi-runtime.ts:45, src/adapters/pi-runtime.ts:50, src/adapters/pi-runtime.ts:58, src/adapters/pi-runtime.ts:80, src/adapters/pi-runtime.ts:97).
• Existing tests document the expected readiness and prompt-dispatch semantics, including exact readiness markers, polling, absence of markers, live panes, stale sessions, and dispatch failures (test/pi-runtime.test.ts:5, test/pi-runtime.test.ts:21, test/pi-runtime.test.ts:30, test/pi-runtime.test.ts:74, test/pi-runtime.test.ts:91, test/pi-runtime.test.ts:141, test/pi-runtime.test.ts:155).
• Current runtime observation already treats completion-like output as a candidate for inspection, not as authoritative completion: marker classification identifies completed-output-present (src/cli/worker-runtime.ts:39, src/cli/worker-runtime.ts:42), while observeRuntimeFromTmux maps it to candidate-output-present with recommended action inspect-report (src/cli/worker-runtime.ts:53, src/cli/worker-runtime.ts:63).
• Existing prompt projection can be harvested for sectioning and lifecycle/artifact guidance: renderRunContractPrompt supports workflow/runtime layouts (src/domain/run-contract-prompt-renderer.ts:29, src/domain/run-contract-prompt-renderer.ts:39, src/domain/run-contract-prompt-renderer.ts:46, src/domain/run-contract-prompt-renderer.ts:48), runtime context fields (src/domain/run-contract-prompt-renderer.ts:59, src/domain/run-contract-prompt-renderer.ts:62, src/domain/run-contract-prompt-renderer.ts:65), shared lifecycle (src/domain/run-contract-prompt-renderer.ts:80, src/domain/run-contract-prompt-renderer.ts:87), and runtime rules (src/domain/run-contract-prompt-renderer.ts:109, src/domain/run-contract-prompt-renderer.ts:111, src/domain/run-contract-prompt-renderer.ts:114).
• Existing RunContract projection has the right vocabulary for mission/contract/evidence/artifacts/completion-quality inputs, but should remain an input projection rather than Pi authority (src/domain/run-contract.ts:49, src/domain/run-contract.ts:58, src/domain/run-contract.ts:69, src/domain/run-contract.ts:70, src/domain/run-contract.ts:71, src/domain/run-contract.ts:73, src/domain/run-contract.ts:78).
• Existing external-adapter pattern is useful: the GitHub adapter maps RunContractView to an adapter-specific view with an explicit boundary and does not mutate external state (src/application/github-run-contract-adapter.ts:18, src/application/github-run-contract-adapter.ts:28, src/application/github-run-contract-adapter.ts:39, src/application/github-run-contract-adapter.ts:49, src/application/github-run-contract-adapter.ts:53). The Pi adapter should use the same “adapter view/output, not authority” discipline.
• Existing artifact store hardening should be reused conceptually for the artifact inbox: it rejects empty names/path separators, confines artifact paths to the workflow root, rejects symlink hazards, and writes under controlled roots (src/adapters/file-store.ts:53, src/adapters/file-store.ts:131, src/adapters/file-store.ts:143, src/adapters/file-store.ts:180, src/adapters/file-store.ts:185, src/adapters/file-store.ts:298).
• Existing evidence shape already includes command, exit code, artifact refs, changed files, acceptance criteria, worker id, actor, and authority fields that can inform normalized evidence candidates (src/domain/types.ts:74, src/domain/types.ts:79, src/domain/types.ts:80, src/domain/types.ts:84, src/domain/types.ts:85, src/domain/types.ts:86, src/domain/types.ts:89, src/domain/types.ts:90).
• Existing TS facade/tool surface is the compatibility target, but currently owns direct workflow mutation paths such as kapi_complete_workflow; those should become facade calls into the Rust authority boundary for SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236 behavior (src/presentation/tools.ts:81, src/presentation/tools.ts:121, src/presentation/tools.ts:262, src/presentation/tools.ts:287, src/presentation/tools.ts:301).
• Current architecture docs already require presentation/Pi code to stay in src/presentation and core domain to avoid Pi/filesystem/tmux/git/process dependencies (README.md:282, README.md:283, README.md:284, README.md:285, README.md:319, README.md:327).

External references / candidate libraries:

• Extensions - pi - https://hochej.github.io/pi-mono/coding-agent/extensions/ — documents the Pi extension API shape and importing ExtensionAPI from @mariozechner/pi-coding-agent, useful for keeping TS facade/shim code compatible.
• @mariozechner/pi-ai - npm - https://www.npmjs.com/package/%40mariozechner/pi-ai — current Pi ecosystem package reference; useful only for TS facade compatibility, not Rust core authority.
• Command in tokio::process - Rust - https://docs.rs/tokio/latest/tokio/process/struct.Command.html — suitable for async process/tmux command execution if ilchul-runtime-pi launches or probes Pi/tmux from Rust.
• Using derive · Serde - https://serde.rs/derive.html — suitable for serializing/deserializing RuntimeOutput, TurnObservation, artifact refs, and prompt-projection test fixtures.
• async_trait - Rust - https://docs.rs/async-trait — suitable if the core RuntimeAdapter port must be dyn-dispatchable with async methods; otherwise native async traits may be enough if object safety is not needed.
• SDKs - Model Context Protocol - https://modelcontextprotocol.io/docs/sdk and GitHub - modelcontextprotocol/rust-sdk - https://github.com/modelcontextprotocol/rust-sdk — relevant because Pi runtime adapter and TS facade boundary #244 will sit behind the SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236/MCP control-plane adapter for TaskStream kernel #243 MCP control plane; isolate usage outside ilchul-runtime-pi unless the adapter directly needs MCP types.

Concrete instructions for the implementation agent

1. Verify prerequisites from child issues. Confirm ilchul-core defines the RuntimeAdapter port and core types (RunContract, RuntimeOutput, TurnObservation, ArtifactRef, evidence candidate/envelope, and any runtime-session ids). If Core services and explicit port contracts #240/MCP control-plane adapter for TaskStream kernel #243 are not landed, add only the minimum core interfaces needed for Pi runtime adapter and TS facade boundary #244 and keep them adapter-neutral.
2. Create crates/runtime-pi as ilchul-runtime-pi. Keep Pi/tmux/process details inside this crate. Do not add tmux/Pi fields to generic core TaskStream, Run, or CompletionDecision records; current README architecture already keeps domain free of Pi/tmux/process dependencies (README.md:282).
3. Implement the RuntimeAdapter trait for Pi. The adapter should expose operations such as project/dispatch/observe/collect-output/collect-artifacts according to the core port. Use the TypeScript launcher behavior as the behavioral reference: launch pi, send a readiness probe, require an exact KAPI_READY <slug> <nonce> response, dispatch the prompt only after readiness, and report dispatch failure separately from runtime readiness (src/adapters/pi-runtime.ts:58, src/adapters/pi-runtime.ts:65, src/adapters/pi-runtime.ts:74, src/adapters/pi-runtime.ts:80, src/adapters/pi-runtime.ts:87).
4. Port readiness and observation tests into Rust. Recreate the meaningful cases from test/pi-runtime.test.ts: exact readiness success, polling, echoed probe ignored, marker absent, live-but-unverified panes, missing tmux sessions, and prompt-dispatch failure (test/pi-runtime.test.ts:5, test/pi-runtime.test.ts:30, test/pi-runtime.test.ts:74, test/pi-runtime.test.ts:91, test/pi-runtime.test.ts:125, test/pi-runtime.test.ts:141, test/pi-runtime.test.ts:155). Use a fake command runner rather than launching real Pi in unit tests.
5. Add prompt projection from RunContract. Build a Pi prompt renderer in Rust that uses the existing renderRunContractPrompt shape only as reference (src/domain/run-contract-prompt-renderer.ts:29, src/domain/run-contract-prompt-renderer.ts:80, src/domain/run-contract-prompt-renderer.ts:109). The new projection must explicitly include these sections: mission, boundary, evidence, verification, handoff. Boundary text must say runtime output is not completion authority.
6. Normalize runtime output into bounded records. Implement parsing/classification that can produce RuntimeOutput and TurnObservation values for: progress text, command/test output, artifact mention/ref, error/failure, blocked/manual attach, and completion-looking claims. Use current marker classification only as a starting point (src/cli/worker-runtime.ts:39, src/cli/worker-runtime.ts:42, src/cli/worker-runtime.ts:48, src/cli/worker-runtime.ts:53).
7. Enforce “candidate, not completion.” Add a test where Pi output says “done”, “complete”, or “completed” and assert the adapter returns a candidate observation/evidence candidate but cannot emit or request CompletionDecision. The current TS runtime observation already models this as candidate-output-present + inspect-report, not state completion (src/cli/worker-runtime.ts:63). Preserve that invariant in Rust.
8. Integrate artifact inbox by reference. When Pi output points to logs, diffs, transcripts, or test output, write/copy through the artifact inbox adapter from Filesystem artifact inbox and projection adapter #242 if available, or return artifact-intent records for core to commit. Mirror the current file-store safety invariants: reject unsafe names/separators, keep paths under the artifact root, and reject symlink hazards (src/adapters/file-store.ts:131, src/adapters/file-store.ts:143, src/adapters/file-store.ts:180, src/adapters/file-store.ts:298).
9. Keep TS/Pi surfaces as facades. Update src/presentation/* only as needed to call the Rust/MCP boundary or document that it is a legacy/shim surface. Existing tools show the compatibility UX shape (src/presentation/tools.ts:81, src/presentation/tools.ts:121, src/presentation/tools.ts:262, src/presentation/tools.ts:345), but for TaskStream MVP they must not directly decide completion from runtime output.
10. Document the facade boundary. Add README/docs language explaining that TS/Pi extension commands are facade/shim surfaces, ilchul-runtime-pi is a runtime adapter, and only the Rust TaskStream kernel can accept evidence/verification and decide completion. This repo requires README alignment when behavior, commands, validation gates, artifacts, hooks, CLI usage, tools, or workflow semantics change.
11. Add acceptance tests. Include Rust tests for adapter trait conformance, prompt section coverage, runtime-output normalization, completion-output non-authority, artifact-ref/inbox confinement, and no Pi/tmux fields in core types. If TS facade code changes, add targeted TS tests to prove existing command/tool UX still works or is clearly documented as shimmed.

Risks / assumptions surfaced by research

• There is no Rust workspace visible in the current root package metadata; package.json is TypeScript/Pi-oriented. The implementation agent should expect crate setup to depend on Rust workspace scaffold + DDD core skeleton #238/Core services and explicit port contracts #240 landing state.
• The current TS prompt renderer has lifecycle/artifact/runtime sections but not the exact required mission/boundary/evidence/verification/handoff section contract; Pi runtime adapter and TS facade boundary #244 should add explicit section tests rather than relying on wording similarity.
• Existing TS tools can complete workflows (src/presentation/tools.ts:287, src/presentation/tools.ts:301), so facade documentation and routing matter; otherwise the TS shim could accidentally preserve old authority semantics.
• The Pi adapter likely needs async command execution; tokio::process::Command is suitable, but tests should keep process execution behind a fakeable runner to avoid flaky tmux/Pi dependencies.
• If RuntimeAdapter from Core services and explicit port contracts #240 is not yet stable, the implementation agent should keep ilchul-runtime-pi narrow and avoid baking temporary Pi details into core trait names.

Assumptions / human decisions to resolve asynchronously before /approve

• Assumption: Pi is the first runtime adapter for SSOT: Ilchul Agent OS — MCP TaskStream control plane MVP #236, not Codex, because this issue explicitly scopes crates/runtime-pi / ilchul-runtime-pi and the repo has existing Pi/tmux behavior to harvest.
• Assumption: acceptable Rust dependencies include tokio, serde, and possibly async-trait; MCP SDK usage should remain in the MCP adapter unless the already-approved core/control-plane design says otherwise.
• Assumption: this issue should not broaden into canonical store, MCP server, or end-to-end fixture work beyond the adapter tests needed for Pi runtime adapter and TS facade boundary #244; those belong to sibling issues SQLite canonical store adapter #241, MCP control-plane adapter for TaskStream kernel #243, and End-to-end coding_test_fix TaskStream fixture #245.

Approval reminder

Implementation starts only after a human comment containing /approve. Until then, this is a planning handoff only; the implementation agent will use this comment plus the issue body/discussion as its starting context.

Agent Signature

[devkade]

/approve