Port Pi v1.0.4 runtime modules to Rust

[AnthonyRonning]

Phase 1 of the Pi Rust port, stacked above #1099.

Status

Draft — the reference spike, harness skeleton and Steps 1–2 are complete. Steps 3–8 are in progress; Phase 1 is not complete.

• Commits: spike d95727f0, skeleton f413acc6, Step 1 d39c0a68, Step 2 7ac5718c.
• Coverage: 4,970 collected upstream cases (including 910 skipped/todo): 110 ported, 190 adapted, 1,028 pending and 3,642 excluded. Steps 1–2 cover 300 selected cases. The selected TypeScript reference run has 1,515 passing and 7 skipped tests across 138 files.
• Corpus: 430 source-recorded function cases across 15 groups and six wire scenarios pass integrated Rust replay. Nine function groups and 33 scenario entries remain pending.
• Manifest: 25 selected source files implemented; 56 remain pending. Selection and review scripts currently live under apps/maple-agent/pi-conformance/selection/.
• Step 1 measures 9,770 production code lines against the initial 3,100–3,800 estimate: 7,791 mapped and 1,979 JavaScript representation/access helpers. Step 2 adds 3,176 against the 2,600–3,200 estimate. Counts exclude tests, blank/comment-only lines, environment seams and harness infrastructure.
• Authorized provisional ownership boundary: tool definitions and provider request/configuration inputs use owned values. Streaming messages and mutable hook arguments/results retain shared identity. The owner authorized continuing on 2026-10-08, subject to planning review.
• Approved scheduling boundary: compare live partials at explicit input gates, retaining every compared field and shared identity. In a parsed-transport diagnostic, 12 of 58 immediate-consumer runs differed only in intermediate partial snapshots; all 58 result-first runs matched. Event order, deltas, final values and retained objects matched. The owner explicitly approved documenting this limitation on 2026-10-08; six narrowly scoped executable rules enforce gated inputs without field exclusions.
• Development validation focuses on macOS; the final gate requires all three operating systems. Step 1 hosted macOS and reference checks passed; Step 2 hosted checks are pending. Both steps passed local pinned just ci and full selected commit hooks.
• Owner-requested repository split: before final review, move the recorder, corpus, selection/coverage tooling and Rust conformance runner to a separate repository. Keep translated upstream Rust tests and deterministic helpers in Maple so public CI remains self-contained. The separate repository is local only for now; publication waits until Phase 1 is complete.
• Next: finish the staged agent-core integration, including early observer-rejection semantics and the approved typed cleared-model boundary, then integrate session/resources in commit order.

Scope

Ports selected Pi v1.0.4 modules into independent pi-ai, pi-agent-core, pi-coding-agent, and pi-mcp crates, with dev-only pi-testkit and pi-conformance. The upstream pin is 7c10bd4337495ee613f2224843ecdf349b80d1df. Runtime integration, host tools, transport/auth integration, and the existing embedded runtime remain phase 2.

The reference flake is isolated from the product toolchain. Its recorder uses Pi's faux provider, deterministic time and randomness, and source aliases. Test inventory and selection tooling live under apps/maple-agent/pi-conformance/selection/.

Spike evidence

• Native Apple Silicon macOS Nix derivations passed with Node v22.23.2 and the pinned 866,386-byte model catalog; no native-module fallback was needed. This machine does not enforce the Linux Nix sandbox, so Linux sandbox execution is still unverified.
• Upstream agent-loop, agent, session-context-edit, and extensions-runner: 151 tests passed.
• Two fresh recordings of the basic text turn were byte-identical, including 15 events. Event digest: 05a34a03254d6e13bc761d1f3d087f15303c2b88ab47350db692ed744eda9aee.
• Vitest list JSON contains file/name/location entries but omits skipped/todo tests. The complete inventory uses Vitest's programmatic collection API and retains those entries.
• Local pinned just ci, root nix flake check --no-update-lock-file, and reference-flake evaluation passed. The spike's hosted Agent CI passed on macOS, Linux and Windows (run).

Harness validation

• Pinned macOS just ci and every selected repository pre-commit component passed at the skeleton commit. Root flake checks passed.

• Two independent upstream reference executions produced identical normalized inventory/results; both corpus recordings were byte-identical. pi-corpus-check passed. The catalog and toolchain pins remain unchanged.

• The skeleton validates complete test inventory, source correspondence, coverage accounting, corpus schema and content hashes, crate dependency boundaries, and explicitly pending work. It includes deterministic time/random/ID injection and an owned task driver tested against the TypeScript fake timers.

• The skeleton passed hosted Agent CI on macOS, Linux and Windows, and the Pi reference job (run). This validates the skeleton, not the uncommitted later port.

• Step 1 passed pinned macOS just ci, full selected pre-commit checks, pi-upstream-tests and pi-corpus-check. Its 68 library and 201 integration tests pass; the latter include the 144 translated cases plus supplementary regressions. Fresh TypeScript output was recorded through the pinned Nix recorder. The corpus includes lossless UTF-16, binary64, field-presence, JSON ordering, validation-error and shared-state observations.

• Step 2 passed pinned macOS just ci, full selected pre-commit checks, upstream reference tests and corpus freshness. Its 78 library and 357 integration tests pass; the latter include all 300 selected Step 1–2 cases plus regressions. Six gated wire fixtures compare bodies, deltas, shared partials, final values and retained events; 103 new direct-function cases use 44 frozen source model records. Cache retention uses an optional host-supplied environment key.

Decisions applied

The crates may depend on the planned third-party Rust libraries, but must have no direct or transitive dependency on Maple crates or local packages outside the six-crate boundary. MCP uses rmcp =3.4.1 protocol types without transport features. Validation uses jsonschema =0.55.1 with remote and filesystem retrieval disabled explicitly. Existing ACP and process-wrapper versions remain unchanged.

Auth-only upstream cases exercise a replaced seam: the missing-auth synchronous throw and Cloudflare auth base-URL resolution are excluded as replace-module. Mixed request-shaping tests retain their assertions using resolved auth fixtures. The port does not recreate the upstream auth registry.

The owner also approved documenting the low-level cleared-model boundary: after callers clear Agent.model, Rust cannot invoke the typed provider with JavaScript undefined. It retains the source events, user history, final error and cleanup; the ordinary session no-model guard remains exact. Its two-case executable comparison is being integrated in Step 3.

The package-manager selection is corrected to follow the explicit source cuts: the manifest-glob-only case at upstream line 1740 will be excluded, and line 1767 retains its applicable exact local-path and symlink assertions. Restoring a cut discovery API solely for these tests would expand the selected runtime. The owner authorized this judgment on 2026-10-08; the exact correction and rationale will accompany Step 5.

Review ownership and final gate

Code-owned surfaces touched by this PR include workspace/crate Cargo.toml files and Cargo.lock, the Agent justfile, the isolated reference flake and lock, .github/workflows/, and scripts/ci/.

The PR stays draft until translated tests and all recorded scenarios pass with zero pending entries, the manifest is complete, any behavioral deviations have owner approval, dependency/branding checks pass, and Agent CI passes on Linux, macOS, and Windows with pi-reference green. Nothing merges as part of this work.