{"slug": "pi-rust-high-performance-ai-coding-agent-cli-written-in-rust", "title": "Pi (Rust): High-performance AI coding agent CLI written in Rust", "summary": "Pi (Rust), a high-performance AI coding agent CLI written in Rust, has been released as a port of the original Pi Agent. It offers instant startup, stable streaming, and a smaller memory footprint compared to Node.js or Python-based tools, with security features like capability-gated hostcalls and two-stage extension enforcement. The tool is designed for large-session, multi-agent, and extension-heavy workloads.", "body_md": "**pi_agent_rust - High-performance AI coding agent CLI written in Rust**\n\n[Why Should You Care?](#why-should-you-care) •\n[TL;DR](#tldr-piopenclaw-users) •\n[Methodology](#benchmark-methodology-and-claim-integrity) •\n[Quick Start](#quick-start) •\n[Features](#features) •\n[Installation](#installation) •\n[Commands](#commands) •\n[Configuration](#configuration)\n\n```\n# Install latest release\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | bash\n```\n\nYou want an AI coding assistant in your terminal, but existing tools are:\n\n**Slow to start**: Node.js/Python runtimes add 500ms+ before you can type** Memory hungry**: Electron apps or heavy runtimes eat gigabytes** Unreliable**: Streaming breaks, sessions corrupt, tools fail silently** Hard to extend**: Closed ecosystems or complex plugin systems\n\n**pi_agent_rust** is a from-scratch Rust port of [Pi Agent](https://github.com/badlogic/pi) by [Mario Zechner](https://github.com/badlogic) (made with his blessing!). Single binary, instant startup, stable streaming, and 8 built-in tools.\n\nRather than a direct line-by-line translation, this port builds on two purpose-built Rust libraries:\n\n: A structured concurrency async runtime with built-in HTTP, TLS, and SQLite[asupersync](https://github.com/Dicklesworthstone/asupersync): A Rust port of[rich_rust](https://github.com/Dicklesworthstone/rich_rust)[Rich](https://github.com/Textualize/rich)by[Will McGugan](https://github.com/willmcgugan), providing beautiful terminal output with markup syntax\n\n```\n# Start a session\npi \"Help me refactor this function to use async/await\"\n\n# Continue a previous session\npi --continue\n\n# Single-shot mode (no session)\npi -p \"What does this error mean?\" < error.log\n```\n\nIf you already use Pi Agent, especially through OpenClaw, this project keeps the core workflow while upgrading the engine under the hood:\n\n**Substantially faster in realistic end-to-end flows**(not synthetic microbenchmarks)** Dramatically smaller memory footprint**in long-running sessions** Materially stronger security model**for extension/tool execution, including command-level blocking of dangerous extension shell patterns\n\nSecurity is a first-class design goal here, not a bolt-on:\n\n- Capability-gated hostcalls (\n`tool`\n\n/`exec`\n\n/`http`\n\n/`session`\n\n/`ui`\n\n/`events`\n\n) - Two-stage extension\n`exec`\n\nenforcement: capability gate first, then command mediation that blocks critical shell classes by default (for example recursive delete, disk/device writes, reverse shell) and can tighten to block high-tier classes in strict/safe policy - Policy + runtime risk + quota enforcement on the execution path\n- Per-extension trust lifecycle (\n`pending`\n\n->`acknowledged`\n\n->`trusted`\n\n->`killed`\n\n) with kill-switch audit logs and explicit operator provenance - Hostcall-lane emergency controls that can force compatibility-lane execution globally or for one extension when fast-lane behavior needs immediate containment\n- Structured concurrency via\n`asupersync`\n\nfor more predictable cancellation/lifecycle behavior - Auditable runtime signals/ledgers and redacted security alerts for extension behavior\n\nThe Rust port is designed around large-session, multi-agent, and extension-heavy workloads. Release-facing performance numbers are published only when the checked-in evidence artifacts are current, have matching run provenance, and report no CI no-data or data-contract failures. Historical benchmark snapshots are retained in planning/evidence artifacts, but they are not treated as current README claims until the performance evidence gate is regenerated cleanly.\n\nExtension runtime guarantees are also concrete:\n\n| Extension assurance signal | Why you should care |\n|---|---|\nTwo-stage `exec` guard (`exec` capability policy + command-level mediation + DCG/heredoc AST signals) |\nDangerous shell intent is caught before spawn, including destructive payloads hidden in multiline wrappers |\nTrust lifecycle + kill switch (`pending/acknowledged/trusted/killed` ) |\nYou can quarantine an extension instantly, log who pulled the switch and why, and require explicit re-acknowledgement before restoring access |\nHostcall lane kill-switch controls (`forced_compat_global_kill_switch` , `forced_compat_extension_kill_switch` ) |\nFast-path regressions can be contained immediately by forcing compatibility-lane execution without disabling the extension system |\n| Deterministic hostcall reactor mesh (shard affinity, bounded SPSC lanes, backpressure telemetry, optional NUMA slab tracking) | Runtime behavior stays predictable under contention; queue pressure and routing decisions are observable instead of opaque |\n| Startup prewarm + warm isolate reuse for JS runtimes | Runtime creation overlaps startup and warm reuse keeps repeated extension runs low-latency without a Node/Bun process model |\nTamper-evident runtime risk ledger (`verify` / `replay` / `calibrate` ) |\nSecurity decisions are hash-linked and can be replayed or threshold-tuned from real runtime traces |\n\nBottom line: Pi's architecture targets lower latency, lower memory use, and stronger extension runtime safety under real workload pressure; current numeric claims must come from fresh, provenance-matched evidence artifacts.\n\nData source: docs/planning/BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md (latest secure-path + full orchestrator checkpoints, 2026-04-23).\n\nAll numeric performance claims in this README include inline citations with format:\n`*(from [artifact-path], run [correlation-id])*`\n\nExample: `*(from [artifact-path], run [correlation-id])*`\n\nCI checks both file freshness and artifact content so stale, no-data, or correlation-mismatched evidence cannot back user-facing performance claims. The README evidence checker reports line-numbered proof obligations for cited claims and extracts claim-gated performance phrases for reviewer audit. Explicit historical snapshot citations are mapped separately and do not satisfy current release-facing claims.\n\nIn this README, `we`\n\nmeans the project owner and collaborating coding agents.\n\nThe speed gains come from runtime design, not one trick.\n\n| Technique | What we do | Runtime effect |\n|---|---|---|\n| Cold-start minimization | Single static binary, no Node/Bun runtime bootstrap, no JIT warmup, startup prewarm for extension runtime paths | Faster time-to-first-interaction |\n| Less copying on hot paths | `Arc` /`Cow` message flow, zero-copy hostcall/tool payload handling, reduced clone-heavy provider/session paths |\nLower CPU and allocation pressure |\n| Deterministic dispatch core | Typed hostcall opcodes, fast-lane/compat-lane routing, bounded shard queues with reactor-mesh telemetry | Better tail latency under concurrent extension load |\n| Efficient long-session storage | SQLite session index + v2 sidecar (segmented log + offset index) with O(index+tail) reopen path | Fast resume on large histories |\n| Streaming parser tuned for real networks | SSE parser tracks scanned bytes, handles UTF-8 tails, normalizes chunk boundaries, interns event-type strings | Lower streaming overhead and fewer parser stalls |\n| Safe fast-path controls | Shadow dual execution sampling, automatic backoff on divergence/overhead, compatibility-lane kill switches for containment | Keeps optimizations fast without silent behavior drift |\n| CI-level performance governance | Scenario matrices, strict artifact contracts, fail-closed perf gates | Regressions are caught before release |\n\nIf you want the full implementation inventory, see [Performance Engineering](#performance-engineering).\n\nThe benchmark evidence policy is designed to keep results realistic, reproducible, and hard to game.\n\nWhat we measured:\n\n**Matched-state workloads**: resume a large session and append the same 10 messages.** Realistic E2E workloads**: resume + append + extension activity + slash-style state changes + forks + exports + compactions.** Scale levels**: from`100k`\n\nup to`5M`\n\ntoken-class session states.**Startup/readiness**: command-level readiness (`--help`\n\n,`--version`\n\n) separately from long-session workflows.\n\nHow we kept comparisons fair:\n\n**Two scopes** in the benchmark report:- apples-to-apples (\n`pi_agent_rust`\n\nvs legacy`coding-agent`\n\n) - apples-to-oranges (legacy stack components included where legacy behavior is outsourced)\n\n- apples-to-apples (\n**Release-mode binaries** and repeated runs per matrix cell.**No paid-provider noise** in core latency/footprint tables (provider-call costs are excluded from these core comparisons).\n\nHow we kept claims honest:\n\n**Security controls stayed on** during secure-path measurements (no policy/risk/quota bypasses for speed claims).**Raw artifacts are preserved**(JSON/trace/time outputs) and called out in the benchmark report.** Blockers are explicitly disclosed**: when direct legacy reruns were blocked by missing workspace deps, we state that and compare against prior validated legacy artifacts instead of pretending reruns succeeded.**Interpretation notes are explicit**: the report distinguishes baseline sections vs fresh reruns so readers can see exactly which values came from which run set.**Reproducibility over marketing**: methodology, caveats, and known limits are included alongside wins.\n\nIf you want full details, see:\n\n`docs/planning/BENCHMARK_COMPARISON_BETWEEN_RUST_VERSION_AND_ORIGINAL__GPT.md`\n\n(methodology + results + caveats + raw artifact paths)\n\n| Feature | Pi (Rust) | Typical TS/Python CLI |\n|---|---|---|\nStartup |\n<100ms | 500ms-2s |\nBinary size |\n~21.1 MiB (default release) | 100MB+ (with runtime) |\nMemory (idle) |\n<50MB | 200MB+ |\nStreaming |\nNative SSE parser | Library-dependent |\nTool execution |\nProcess tree management | Basic subprocess |\nSessions |\nJSONL with branching | Varies |\nUnsafe code |\nForbidden | N/A |\n\n```\n# 1) Start an interactive session\npi\n\n# 2) Ask a codebase question\npi \"Summarize the architecture in src/\"\n\n# 3) Attach a file inline\npi @src/main.rs \"Explain startup flow\"\n\n# 4) Run single-shot mode for scripting\npi -p \"List likely regression risks for this diff\"\n\n# 5) Continue your last project session\npi --continue\n\n# 6) Inspect available models/providers\npi --list-models\npi --list-providers\n```\n\n[asupersync](https://github.com/Dicklesworthstone/asupersync) is a structured concurrency async runtime designed for applications that need predictable resource cleanup. Key features used by pi_agent_rust:\n\n**Capability-based context (**: Async functions receive an explicit context that controls what they can do (HTTP, filesystem, time). This makes testing deterministic.`Cx`\n\n)**HTTP client with TLS**: Built-in HTTP API with rustls, avoiding OpenSSL dependency hell** Structured cancellation**: When a parent task cancels, all child tasks cancel cleanly. No orphaned futures.\n\n`pi_agent_rust`\n\nruns on `asupersync`\n\nend-to-end today (runtime + HTTP/TLS + cancellation). Provider streaming uses a minimal HTTP client (`src/http/client.rs`\n\n) feeding a custom SSE parser (`src/sse.rs`\n\n).\n\n[rich_rust](https://github.com/Dicklesworthstone/rich_rust) is a Rust port of Will McGugan's [Rich](https://github.com/Textualize/rich) Python library. It provides:\n\n**Markup syntax**:`[bold red]error[/]`\n\nrenders as bold red text**Tables**: ASCII/Unicode table rendering with alignment and borders** Panels**: Boxed content with titles** Progress bars**: Animated progress indicators** Markdown**: Terminal-rendered markdown with syntax highlighting** Themes**: Consistent color schemes across components\n\nThe terminal UI uses rich_rust for all output formatting, providing the same visual quality as Rich-based Python tools.\n\n```\n# Install latest release binary\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | bash\n```\n\nIf you already have the original TypeScript `pi`\n\ninstalled, the installer asks\nwhether to make Rust Pi canonical as `pi`\n\nand automatically create `legacy-pi`\n\nfor the old command.\n\n```\nexport ANTHROPIC_API_KEY=\"sk-ant-...\"\n# Interactive mode\npi\n\n# With an initial message\npi \"Explain this codebase structure\"\n\n# Read files as context\npi @src/main.rs \"What does this do?\"\n```\n\nReal-time token streaming with extended thinking support:\n\n```\npi \"Write a quicksort implementation\"\n```\n\nWatch the response appear token-by-token, with thinking blocks shown inline.\n\n| Tool | Description | Example |\n|---|---|---|\n`read` |\nRead file contents, supports images | Read src/main.rs |\n`write` |\nCreate or overwrite files | Write a new config file |\n`edit` |\nSurgical string replacement | Fix the typo on line 42 |\n`hashline_edit` |\nPrecise edits using LINE#HASH tags | Apply edits to specific lines using hashline anchors |\n`bash` |\nExecute shell commands with timeout | Run the test suite |\n`grep` |\nSearch file contents with context | Find all TODO comments |\n`find` |\nDiscover files by pattern | Find all *.rs files |\n`ls` |\nList directory contents | What's in src/? |\n\nAll tools include:\n\n- Automatic truncation for large outputs (2000 lines / 1MB)\n- Detailed metadata in responses\n- Process tree cleanup for bash (no orphaned processes)\n\nSessions persist as JSONL files with full conversation history:\n\n```\n# Continue most recent session\npi --continue\n\n# Open specific session\npi --session ~/.pi/agent/sessions/--home-user-project--/2024-01-15T10-30-00.jsonl\n\n# Ephemeral (no persistence)\npi --no-session\n```\n\nSessions support:\n\n- Tree structure for conversation branching\n- Model/thinking level change tracking\n- Automatic compaction for long conversations\n\nEnable deep reasoning for complex problems:\n\n```\npi --thinking high \"Design a distributed rate limiter\"\n```\n\nThinking levels: `off`\n\n, `minimal`\n\n, `low`\n\n, `medium`\n\n, `high`\n\n, `xhigh`\n\n**Skills**: Drop`SKILL.md`\n\nunder`~/.pi/agent/skills/`\n\nor`.pi/skills/`\n\nand invoke with`/skill:name`\n\n.**Prompt templates**: Markdown files under`~/.pi/agent/prompts/`\n\nor`.pi/prompts/`\n\n; invoke via`/<template> [args]`\n\n.**Packages**: Share bundles with`pi install npm:@org/pi-packages`\n\n(skills, prompts, themes, extensions).\n\nPi provides context-aware autocomplete in the interactive editor:\n\n: Type`@`\n\nfile references`@`\n\nfollowed by a path fragment to attach file contents. The completion engine indexes project files (respecting`.gitignore`\n\n) via the`ignore`\n\ncrate's`WalkBuilder`\n\n, capping at 5,000 entries.: Built-in commands (`/`\n\nslash commands`/help`\n\n,`/model`\n\n,`/tree`\n\n,`/clear`\n\n,`/compact`\n\n,`/exit`\n\n) and user-defined prompt templates and skills all appear as completions.**Fuzzy scoring**: Prefix matches rank above substring matches. Results are sorted by match quality, then by kind (commands > templates > skills > files > paths).**Background refresh**: A background thread re-indexes the project file tree every 30 seconds, so completions stay current without blocking the input loop.\n\nPi runs in three modes, each suited to different workflows:\n\n| Mode | Invocation | Use Case |\n|---|---|---|\nInteractive |\n`pi` (default) |\nFull TUI with streaming, tools, session branching, autocomplete |\nPrint |\n`pi -p \"...\"` |\nSingle response to stdout, no TUI, scriptable |\nRPC |\n`pi --mode rpc` |\nHeadless JSON protocol over stdin/stdout for IDE integrations |\n\n**Interactive mode** provides the full experience: a multi-line text editor with history, scrollable conversation viewport, model selector (`Ctrl+L`\n\n), scoped model cycling (`Ctrl+P`\n\n/`Ctrl+Shift+P`\n\n), session branch navigator (`/tree`\n\n), and real-time token/cost tracking.\n\n**Print mode** sends one message, streams the response to stdout, and exits. Useful for shell scripts and one-off queries.\n\n**RPC mode** exposes a line-delimited JSON protocol for programmatic control. Clients send commands (`prompt`\n\n, `steer`\n\n, `follow-up`\n\n, `abort`\n\n, `get-state`\n\n, `compact`\n\n) and receive streaming events. This is how IDE extensions and custom frontends integrate with Pi. See [RPC Protocol](#rpc-protocol) for the wire format.\n\nPi supports two extension runtime families with capability-gated host connectors:\n\n-\nJS/TS entrypoints run\n\n**without Node or Bun** in an embedded QuickJS runtime. -\n`*.native.json`\n\ndescriptors run in the native-rust descriptor runtime. -\nExtension entrypoints are auto-detected:\n\n`.js/.ts/.mjs/.cjs/.tsx/.mts/.cts`\n\nrun directly in embedded QuickJS (no descriptor conversion).`*.native.json`\n\nloads the native-rust descriptor runtime.- One session currently uses one runtime family at a time (JS/TS or native descriptor).\n\n-\n**Sub-100ms cold load**(P95),** sub-1ms warm load**(P99) -\nNode API shims for\n\n`fs`\n\n,`path`\n\n,`os`\n\n,`crypto`\n\n,`child_process`\n\n,`url`\n\n, and more -\nCapability-based security: extensions call explicit connectors (\n\n`tool/exec/http/session/ui`\n\n) with audit logging -\nCommand-level exec mediation: dangerous shell signatures are classified and blocked before spawn, with redacted denial alerts and mediation ledger entries\n\n-\nTrust-state lifecycle and kill-switch controls with audited state transitions (\n\n`pending`\n\n/`acknowledged`\n\n/`trusted`\n\n/`killed`\n\n) -\nHostcall reactor mesh with deterministic shard routing, bounded queue backpressure, and optional NUMA-aware telemetry\n\n-\nRuntime prewarm path with warm isolate reuse so extension startup cost is mostly paid before the first prompt\n\n`/model`\n\n(or`Ctrl+L`\n\n) opens a selector focused on models that are ready to run with current credentials.`Ctrl+P`\n\nand`Ctrl+Shift+P`\n\ncycle through the scoped model set without opening the overlay.- Provider IDs and aliases are matched case-insensitively in model selection and\n`/login`\n\n. - Models that do not require configured credentials can run keyless.\n\nExtensions can register tools, slash commands, event hooks, flags, providers,\nand shortcuts. See [EXTENSIONS.md](/Dicklesworthstone/pi_agent_rust/blob/main/docs/planning/EXTENSIONS.md) for the full architecture\nand [docs/extension-catalog.json](/Dicklesworthstone/pi_agent_rust/blob/main/docs/extension-catalog.json) for the\n223-entry catalog with per-extension conformance status and perf budgets.\n\nThis project validates extension compatibility with a three-track pipeline:\n\n**Vendored corpus (224)**: deterministic conformance, compatibility matrix, and scenario suites.** Unvendored corpus (777)**: source acquisition and onboarding prioritization.** Release-binary live-provider E2E**: real`target/release/pi`\n\nexecution against a non-mocked provider/model path.\n\n- Catch runtime/API regressions in QuickJS host shims and capability policy.\n- Catch dangerous extension shell call patterns with real command mediation on the release binary path.\n- Verify extension behavior against real provider responses, not just fixture/mocked flows.\n- Keep extension support measurable instead of anecdotal.\n- Produce a prioritized queue for onboarding unvendored candidates into vendored conformance.\n\n-\n**Fetch unvendored source corpus**- Binary:\n`ext_unvendored_fetch_run`\n\n- Typical command:\n`cargo run --example ext_unvendored_fetch_run -- run-all --workers 8 --no-probe`\n\n- Purpose:\n- Clones GitHub repos and unpacks npm tarballs into\n`.tmp-codex-unvendored-cache/`\n\n- Produces machine-readable acquisition status for all unvendored candidates\n\n- Clones GitHub repos and unpacks npm tarballs into\n- Artifacts:\n`tests/ext_conformance/reports/pipeline/unvendored_fetch_probe_report.json`\n\n`tests/ext_conformance/reports/pipeline/unvendored_fetch_probe_events.jsonl`\n\n- Binary:\n-\n**Run end-to-end validation orchestration**- Binary:\n`ext_full_validation`\n\n- Typical command:\n`cargo run --example ext_full_validation --`\n\n- Stages (in order):\n`refresh_onboarding_queue`\n\n(runs`ext_onboarding_queue`\n\n)`conformance_shard_0..N`\n\n(runs`ext_conformance_generated`\n\nsharded matrix)`conformance_failure_dossiers`\n\n`provider_compat_matrix`\n\n`scenario_conformance_suite`\n\n`auto_repair_full_corpus`\n\n`differential_suite`\n\n(optional, enabled via`--run-diff`\n\n; npm diff via`--run-npm-diff`\n\n)\n\n- Artifacts:\n`tests/ext_conformance/reports/pipeline/full_validation_report.json`\n\n`tests/ext_conformance/reports/pipeline/full_validation_report.md`\n\n- Plus stage-specific reports under\n`tests/ext_conformance/reports/**`\n\n- Binary:\n-\n**Run dev-firstset live-provider gate (must pass before release build)**- Binary:\n`ext_release_binary_e2e`\n\n- Typical command:\n`cargo build --bin pi --bin ext_release_binary_e2e`\n\n`PI_HTTP_REQUEST_TIMEOUT_SECS=0 target/debug/ext_release_binary_e2e --pi-bin target/debug/pi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --max-cases 20 --extension-policy balanced --out-json tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.json --out-md tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.md`\n\n- Purpose:\n- Proves the current codepath works end-to-end on a representative first-set before paying release-build cost.\n- Serves as the promotion gate to full release-binary validation.\n\n- Gate:\n- Require\n`pass=20 / total=20`\n\nwith`fail=0`\n\n.\n\n- Require\n- Artifacts:\n`tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.json`\n\n`tests/ext_conformance/reports/release_binary_e2e/ollama_firstset_dev_20260219_jobs10_timeout600.md`\n\n- Binary:\n-\n**Run full release-binary live-provider E2E (after step 3 passes)**- Binary:\n`ext_release_binary_e2e`\n\n- Typical command:\n`cargo build --release --bin pi --bin ext_release_binary_e2e`\n\n`PI_HTTP_REQUEST_TIMEOUT_SECS=0 target/release/ext_release_binary_e2e --pi-bin target/release/pi --provider ollama --model qwen2.5:0.5b --jobs 10 --timeout-secs 600 --extension-policy balanced --out-json tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.json --out-md tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.md`\n\n- Purpose:\n- Executes\n`target/release/pi`\n\ndirectly for each selected extension case. - Uses a live provider/model path (default\n`ollama`\n\n+`qwen2.5:0.5b`\n\n) to exercise non-mocked end-to-end behavior. - Emits per-case stdout/stderr captures plus summary artifacts (\n`pi.ext.release_binary_e2e.v1`\n\n).\n\n- Executes\n- Artifacts:\n`tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.json`\n\n`tests/ext_conformance/reports/release_binary_e2e/ollama_full_release_20260219_jobs10_timeout600.md`\n\n`tests/ext_conformance/reports/release_binary_e2e/cases/*`\n\n- Binary:\n-\n**Aggregate and triage**`full_validation_report.json`\n\ncombines:- Stage-level pass/fail (\n`stageSummary`\n\n,`stageResults`\n\n) - Corpus counts (\n`corpus`\n\n) - Vendored conformance totals (\n`conformance`\n\n) - Provider matrix totals (\n`providerCompat`\n\n) - Scenario totals (\n`scenario`\n\n) - Review queue + verdict classification (\n`reviewQueue`\n\n,`verdictCounts`\n\n)\n\n- Stage-level pass/fail (\n- Important interpretation rule:\n`not_tested_unvendored`\n\nindicates unvendored candidates not yet in vendored conformance; this is inventory status, not a vendored regression.\n\nThese runs compile many crates and can be disk-heavy. Point Cargo artifacts and temp files to a large volume:\n\n```\nexport CARGO_TARGET_DIR=\"/data/tmp/pi_agent_rust_cargo/${USER:-agent}/target\"\nexport TMPDIR=\"/data/tmp/pi_agent_rust_cargo/${USER:-agent}/tmp\"\nmkdir -p \"$CARGO_TARGET_DIR\" \"$TMPDIR\"\n```\n\nThen run:\n\n```\ncargo run --example ext_unvendored_fetch_run -- run-all --workers 8 --no-probe\ncargo run --example ext_full_validation --\n```\n\nFrom:\n\n-\n`tests/ext_conformance/reports/gate/must_pass_gate_verdict.json`\n\n(generated`2026-05-15T17:03:02.000Z`\n\n, run`local-20260515T170218075Z`\n\n) -\n`tests/ext_conformance/reports/health_delta/health_delta_report.json`\n\n(generated`2026-05-13T03:37:59.568Z`\n\n) -\n`tests/ext_conformance/reports/journeys/journey_report.json`\n\n(generated`2026-05-13T02:59:58.302Z`\n\n) -\n`tests/evidence_bundle/index.json`\n\n(generated`2026-05-12T19:26:21.441Z`\n\n, run`local-20260512T192621Z`\n\n) -\n`tests/full_suite_gate/certification_verdict.json`\n\n(generated`2026-05-14T19:59:37.227Z`\n\n) -\n`docs/evidence/dropin-certification-verdict.json`\n\n(generated`2026-05-18T19:37:26Z`\n\n) -\nStrict drop-in status:\n\n**22/22 certification gates PASS, 16/16 blocking gates PASS**-`CERTIFIED`\n\n*(from docs/evidence/dropin-certification-verdict.json; strict replacement wording remains governed by docs/contracts/dropin-certification-contract.json and this verdict artifact)* -\nUnified evidence bundle:\n\n`29/29`\n\nsections present,`0`\n\nmissing,`0`\n\ninvalid*(from tests/evidence_bundle/index.json)* -\nExtension must-pass gate:\n\n`123/123`\n\nmust-pass extensions passed; informational stretch set`100/101`\n\npassed with one non-blocking stretch failure*(from tests/ext_conformance/reports/gate/must_pass_gate_verdict.json)* -\nExtension health delta:\n\n`223/223`\n\ntested extensions passed (`100.0%`\n\n),`0`\n\nregressions,`13`\n\nfixes vs the 2026-02-07 baseline, with`1`\n\nintentionally excluded test fixture disclosed in the report*(from tests/ext_conformance/reports/health_delta/health_delta_report.json)* -\nHealth-delta full-manifest non-pass extensions:\n\n`0`\n\n;`base_fixtures`\n\nis a test-only negative fixture excluded from release-facing pass-rate claims with disposition recorded in`docs/evidence/extension-health-delta-failure-disposition.json`\n\n. -\nExtension journey coverage:\n\n`123/123`\n\njourney scenarios passed (`100.0%`\n\n); command, event-subscriber, multi-capability, passive, and tool-provider categories are green*(from tests/ext_conformance/reports/journeys/journey_report.json)* -\nStress triage:\n\n`1,500`\n\nevents,`0`\n\nerrors, p99 latency`396us`\n\n, RSS growth`0.0%`\n\n*(from tests/perf/reports/stress_triage.json, run bd-2zcs5.71-darkgoose-20260510T0058Z)*\n\n```\n# Latest release\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | bash\n\n# Non-interactive + auto PATH update\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | bash -s -- --yes --easy-mode\n\n# Pin a release tag\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | bash -s -- --version v0.1.0\n\n# Install from explicit artifact URL + checksum URL\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | \\\n  bash -s -- \\\n    --artifact-url \"https://github.com/Dicklesworthstone/pi_agent_rust/releases/download/v0.1.0/pi-linux-amd64.tar.xz\" \\\n    --checksum-url \"https://github.com/Dicklesworthstone/pi_agent_rust/releases/download/v0.1.0/SHA256SUMS\"\n\n# Skip completion setup (CI/non-interactive minimal install)\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/install.sh?$(date +%s)\" | \\\n  bash -s -- --yes --no-completions\n```\n\nThe installer is idempotent and supports a migration path from TypeScript Pi:\n\n- Detect existing TS\n`pi`\n\ncommand - Prompt to install Rust Pi as canonical\n`pi`\n\n- Preserve old CLI behind\n`legacy-pi`\n\n- Record state for clean uninstall/restore\n\nNotable installer flags:\n\n`--offline [TARBALL]`\n\n: enforce offline mode; optional local artifact path (`.tar.gz`\n\n,`.tar.xz`\n\n,`.zip`\n\n, or raw binary)`--artifact-url`\n\n: force a specific release artifact URL`--checksum`\n\n/`--checksum-url`\n\n: override checksum source for explicit artifacts`--sigstore-bundle-url`\n\n: override Sigstore bundle URL used by`cosign verify-blob`\n\n`--completions auto|off|bash|zsh|fish`\n\n: force shell completion install target (`off`\n\nis equivalent to`--no-completions`\n\n)`--no-completions`\n\n: disable completion installation`--no-agent-skills`\n\n: skip automatic installation of the`pi-agent-rust`\n\nskill into`~/.claude/skills/`\n\nand`~/.codex/skills/`\n\n`--no-verify`\n\n: skip checksum + signature verification (testing only)`--artifact-url`\n\nwithout`--version`\n\nuses a synthetic tag for release mode only; if artifact download fails, install exits instead of attempting source fallback- Installer honors\n`HTTPS_PROXY`\n\n/`HTTP_PROXY`\n\nfor all network fetches\n\nBy default, the installer also installs a `pi-agent-rust`\n\nskill for both Claude Code and Codex CLI:\n\n- Claude Code:\n`~/.claude/skills/pi-agent-rust/SKILL.md`\n\n- Codex CLI:\n`~/.codex/skills/pi-agent-rust/SKILL.md`\n\n(or`$CODEX_HOME/skills/pi-agent-rust/SKILL.md`\n\nif`CODEX_HOME`\n\nis set) - During upgrades, installer-managed legacy pre-tool entries from older versions are removed automatically (idempotent, path-scoped, and non-destructive) when prior installer state is present.\n\nInstaller regression harness (options + checksum + signature + completions):\n\n```\nbash tests/installer_regression.sh\n```\n\nFor migration adoption, packaging and invocation compatibility follows this contract:\n\n-\nThis section covers packaging/invocation behavior only; functional parity and certification status are tracked in\n\n`docs/contracts/dropin-certification-contract.json`\n\n. -\nCanonical executable name is\n\n`pi`\n\nacross release assets and installer-managed installs. -\nInstaller-managed installs also create an\n\n`rpi`\n\ncompatibility launcher when no conflicting`rpi`\n\ncommand already exists on your PATH. -\nExisting TypeScript\n\n`pi`\n\ninstalls can be migrated in place; the prior command is preserved as`legacy-pi`\n\n. -\nIf you keep TypeScript\n\n`pi`\n\nas canonical (`--keep-existing-pi`\n\n), Rust Pi is installed as`pi-rust`\n\n. -\nOn Apple Silicon, the installer prefers the native arm64 artifact even when launched from a Rosetta-translated shell.\n\n-\nVersion-pinned installs are supported via\n\n`install.sh --version vX.Y.Z`\n\nfor deterministic rollouts. -\nEvery GitHub release ships platform binaries plus\n\n`SHA256SUMS`\n\nfor integrity validation.\n\nRepresentative smoke checks:\n\n```\n# Canonical command should exist and execute\ncommand -v pi\npi --version\npi --help >/dev/null\n\n# If a TS migration was performed, legacy command remains available\ncommand -v legacy-pi && legacy-pi --version\n```\n\nRequires Rust nightly (2024 edition features):\n\n```\n# Install Rust nightly\nrustup install nightly\nrustup default nightly\n\n# Clone and build\ngit clone https://github.com/Dicklesworthstone/pi_agent_rust.git\ncd pi_agent_rust\ncargo build --release\n\n# Binary is at target/release/pi\n./target/release/pi --version\n\n# To install system-wide (--locked ensures reproducible dependency resolution)\ncargo install --path . --locked\n```\n\nPi has minimal runtime dependencies:\n\n`fd`\n\n: Required for the`find`\n\ntool (install via`apt install fd-find`\n\nor`brew install fd`\n\n)`rg`\n\n: Required for the`grep`\n\ntool (install via`apt install ripgrep`\n\nor`brew install ripgrep`\n\n)\n\n```\ncurl -fsSL \"https://raw.githubusercontent.com/Dicklesworthstone/pi_agent_rust/main/uninstall.sh\" | bash\n```\n\nBy default, uninstall removes installer-managed Rust binaries/aliases and skill directories,\nthen restores a migrated TypeScript `pi`\n\nif one was preserved.\n\n```\npi [OPTIONS] [MESSAGE]...\n\n# Examples\npi                              # Start interactive session\npi \"Hello\"                      # Start with message\npi @file.rs \"Explain this\"      # Include file as context\npi -p \"Quick question\"          # Print mode (no session)\n```\n\nInteractive file references:\n\n- Type\n`@relative/path`\n\nin the editor to attach a file’s contents (autocomplete inserts the`@`\n\nform).\n\n| Option | Description |\n|---|---|\n`-c, --continue` |\nContinue most recent session |\n`-r, --resume` |\nOpen session picker UI |\n`--session <PATH>` |\nOpen specific session file |\n`--session-dir <DIR>` |\nOverride session storage directory for this run |\n| `--session-durability strict | balanced |\n`--no-session` |\nDon't persist conversation |\n`-p, --print` |\nSingle response, no interaction |\n| `--mode text | json |\n`--provider <NAME>` |\nForce provider for this run (aliases supported) |\n`--model <MODEL>` |\nModel to use (auto-select fallback: `anthropic/claude-sonnet-4-6` , then `anthropic/claude-opus-4-7` , then `openai/gpt-5.1-codex` ) |\n`--thinking <LEVEL>` |\nThinking level: off/minimal/low/medium/high/xhigh |\n`--tools <TOOLS>` |\nComma-separated tool list |\n`--api-key <KEY>` |\nAPI key (or use provider-specific env vars such as `ANTHROPIC_API_KEY` , `OPENAI_API_KEY` , etc.) |\n| `--extension-policy safe | balanced |\n| `--repair-policy off | suggest |\n`--list-models [PATTERN]` |\nList available models (optional fuzzy filter) |\n`--list-providers` |\nList canonical provider IDs, aliases, and auth env keys |\n`--export <PATH>` |\nExport session file to HTML |\n\nAdditional high-leverage flags:\n\n`--no-migrations`\n\nto skip startup migration checks`--explain-extension-policy`\n\nto print effective capability decisions and exit`--explain-repair-policy`\n\nto print effective repair-policy resolution and exit\n\n```\n# Package management\npi install <source> [-l|--local]    # Install a package source and add to settings\npi remove <source> [-l|--local]     # Remove a package source from settings\npi update [source]                 # Update all (or one) non-pinned packages\npi list                            # List user + project packages from settings\n\n# Configuration\npi config                          # Show settings paths + precedence\n```\n\nMore utility subcommands:\n\n```\n# Extension catalog index + discovery\npi update-index\npi search \"git\"\npi info pi-search-agent\n\n# Environment and extension diagnostics\npi doctor\npi doctor --only sessions --format json\npi doctor --only swarm --format json\npi doctor ./path/to/extension --policy safe --fix\n\n# Read-only swarm progress SLO evaluation from normalized evidence\npi swarm-progress --input progress-slo-input.json --format json\npi swarm-progress --input progress-slo-input.json --since HEAD~1 --out-json progress-slo.json\n\n# Session storage migration (JSONL -> v2 sidecar store)\npi migrate ~/.pi/agent/sessions --dry-run\npi migrate ~/.pi/agent/sessions\n```\n\n`update-index`\n\nrefreshes extension index metadata used by`search`\n\nand`info`\n\n.`search`\n\nand`info`\n\nlet you discover and inspect extension metadata without leaving the CLI.`doctor`\n\nchecks config, directories, auth, shell setup, sessions, swarm coordination readiness, and extension compatibility.`pi doctor --only swarm --format json`\n\nalso reports cgroup CPU quota, cpuset size, NUMA topology, cgroup memory limits, target/tmp headroom, and recommended concurrency budgets before large multi-agent runs.`swarm-progress`\n\nevaluates a normalized progress SLO snapshot and emits advisory JSON/text only; it does not mutate Beads, git, Agent Mail, RCH, validation broker slots, runpacks, or source files. Operator workflow, privacy boundaries, degraded Agent Mail/RCH interpretation, stale-Beads handling, and no-open-work convergence guidance lives in[docs/swarm-operations-runbook.md#progress-slo-operator-workflow](/Dicklesworthstone/pi_agent_rust/blob/main/docs/swarm-operations-runbook.md#progress-slo-operator-workflow).`migrate`\n\nvalidates or creates the v2 session sidecar format for faster resume on larger histories.\n\nPi reads configuration from `~/.pi/agent/settings.json`\n\n:\n\n```\n{\n  \"default_provider\": \"anthropic\",\n  \"default_model\": \"claude-opus-4-5\",\n  \"default_thinking_level\": \"medium\",\n\n  \"compaction\": {\n    \"enabled\": true,\n    \"reserve_tokens\": 8192,\n    \"keep_recent_tokens\": 20000\n  },\n\n  \"retry\": {\n    \"enabled\": true,\n    \"max_retries\": 3,\n    \"base_delay_ms\": 1000,\n    \"max_delay_ms\": 30000\n  },\n\n  \"images\": {\n    \"auto_resize\": true,\n    \"block_images\": false\n  },\n\n  \"terminal\": {\n    \"show_images\": true,\n    \"clear_on_shrink\": false\n  },\n\n  \"shell_path\": \"/bin/bash\",\n  \"shell_command_prefix\": \"set -e\"\n}\n```\n\nSettings are resolved in priority order (first match wins):\n\n**CLI flags**(`--model`\n\n,`--thinking`\n\n,`--provider`\n\n, etc.)**Environment variables**(`ANTHROPIC_API_KEY`\n\n,`PI_CONFIG_PATH`\n\n, etc.)**Project settings**(`.pi/settings.json`\n\nin the working directory)**Global settings**(`~/.pi/agent/settings.json`\n\n)**Built-in defaults**\n\nThis means a CLI flag always overrides a `settings.json`\n\nvalue, and a project-level setting overrides the global one.\n\nSkills, prompt templates, themes, and extensions follow the same resolution order:\n\n- CLI-specified paths (\n`--skill`\n\n,`--prompt-template`\n\n,`--theme`\n\n,`-e`\n\n) - Project directory (\n`.pi/skills/`\n\n,`.pi/prompts/`\n\n,`.pi/themes/`\n\n,`.pi/extensions/`\n\n) - Global directory (\n`~/.pi/agent/skills/`\n\n,`~/.pi/agent/prompts/`\n\n, etc.) - Installed packages (\n`~/.pi/agent/packages/`\n\n)\n\nWhen multiple resources share the same name, the first occurrence wins. Collisions are logged as diagnostics.\n\n**Prompt template expansion** supports positional arguments: `$1`\n\n, `$2`\n\n, `$@`\n\n(all args), and slice syntax `${@:start}`\n\n, `${@:start:length}`\n\n. For example, a template invoked as `/review src/main.rs --strict`\n\nreceives `src/main.rs`\n\nas `$1`\n\nand `--strict`\n\nas `$2`\n\n.\n\n| Variable | Description |\n|---|---|\n`ANTHROPIC_API_KEY` |\nAnthropic API key |\n`OPENAI_API_KEY` |\nOpenAI API key |\n`GOOGLE_API_KEY` |\nGoogle Gemini API key |\n`AZURE_OPENAI_API_KEY` |\nAzure OpenAI API key |\n`COHERE_API_KEY` |\nCohere API key |\n`GROQ_API_KEY` |\nGroq API key (OpenAI-compatible) |\n`DEEPINFRA_API_KEY` |\nDeepInfra API key (OpenAI-compatible) |\n`CEREBRAS_API_KEY` |\nCerebras API key (OpenAI-compatible) |\n`OPENROUTER_API_KEY` |\nOpenRouter API key (OpenAI-compatible) |\n`MISTRAL_API_KEY` |\nMistral API key (OpenAI-compatible) |\n`MOONSHOT_API_KEY` |\nMoonshot/Kimi API key (OpenAI-compatible) |\n`DASHSCOPE_API_KEY` |\nDashScope/Qwen API key (OpenAI-compatible) |\n`DEEPSEEK_API_KEY` |\nDeepSeek API key (OpenAI-compatible) |\n`FIREWORKS_API_KEY` |\nFireworks API key (OpenAI-compatible) |\n`TOGETHER_API_KEY` |\nTogether API key (OpenAI-compatible) |\n`PERPLEXITY_API_KEY` |\nPerplexity API key (OpenAI-compatible) |\n`XAI_API_KEY` |\nxAI API key (OpenAI-compatible) |\n`PI_CONFIG_PATH` |\nCustom config file path |\n`PI_CODING_AGENT_DIR` |\nOverride the global config directory |\n`PI_PACKAGE_DIR` |\nOverride the packages directory |\n`PI_SESSIONS_DIR` |\nCustom sessions directory |\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                           CLI (clap)                            │\n│  • Argument parsing    • @file expansion    • Subcommands       │\n└─────────────────────────────────┬───────────────────────────────┘\n                                  │\n┌─────────────────────────────────▼───────────────────────────────┐\n│                          Agent Loop                             │\n│  • Message history     • Tool iteration    • Event callbacks    │\n└────────┬──────────────────────┬──────────────────────┬──────────┘\n         │                      │                      │\n┌────────▼────────┐  ┌─────────▼──────────┐  ┌───────▼──────────┐\n│ Provider Layer  │  │  Tool Registry     │  │  Extension Mgr     │\n│ • Anthropic     │  │  • read  • bash    │  │  • QuickJS JS/TS   │\n│ • OpenAI (Chat/ │  │  • write • grep    │  │  • Native descriptor│\n│   Responses)    │  │  • edit  • find    │  │    runtime          │\n│ • Gemini/Cohere │  │  • ls              │  │  • Capability policy│\n│ • Azure/Bedrock │  │  • ext-registered  │  │  • Node shims       │\n│ • Vertex/Copilot│  │                    │  │  • Event hooks      │\n│ • GitLab/Ext    │  │                    │  │  • Runtime risk ctl │\n└────────┬────────┘  └─────────┬──────────┘  └───────┬──────────┘\n         │                     │                      │\n┌────────▼─────────────────────▼──────────────────────▼──────────┐\n│                     Session Persistence                         │\n│  • JSONL format (v3)   • Tree structure   • Session index/cache  │\n│  • Per-project dirs    • Default-enabled SQLite backend support │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nProvider-count rule: Pi has 10 native provider implementation modules, counted as the Rust files under `src/providers/`\n\nexcluding `mod.rs`\n\n. Those modules are `anthropic`\n\n, `openai`\n\n, `openai_responses`\n\n, `gemini`\n\n, `cohere`\n\n, `azure`\n\n, `bedrock`\n\n, `vertex`\n\n, `copilot`\n\n, and `gitlab`\n\n. User-visible provider IDs, aliases, OpenAI-compatible presets, and extension-provided `streamSimple`\n\nproviders are counted separately because several native modules expose multiple routes.\n\n**No unsafe code**:`#![forbid(unsafe_code)]`\n\nenforced project-wide**Streaming-first**: Custom SSE parser, no blocking on responses** Process tree management**:`sysinfo`\n\ncrate ensures no orphaned processes**Structured errors**:`thiserror`\n\nwith specific error types per component**Size-budgeted release profile**: LTO + strip +`opt-level = \"z\"`\n\nfor budget-compliant shipping artifacts\n\nThis Rust port preserves Pi's user experience, but intentionally changes the runtime substrate. The original TypeScript Pi (`pi-mono`\n\n, `packages/coding-agent`\n\n) is built on Node.js + package-level abstractions. `pi_agent_rust`\n\nmoves those same behaviors onto `asupersync`\n\nprimitives so lifecycle guarantees are explicit in the runtime model.\n\n| Concern | TypeScript Pi (pi-mono baseline) | pi_agent_rust + asupersync |\n|---|---|---|\nRuntime model |\nNode event loop + Promise/AbortSignal conventions | `RuntimeBuilder` + explicit reactor and runtime handle |\nAsync ownership |\nTask lifetimes coordinated by framework/library code | Structured task ownership and explicit cross-thread channels (TUI/RPC bridging) |\nCancellation semantics |\nPrimarily API- and tool-layer conventions | Runtime-aware cancellation checks + bounded timeout handling in tools |\nI/O capability shape |\nAmbient Node APIs + extension layer policies | Capability-scoped context (`AgentCx` over `asupersync::Cx` ) and explicit hostcall policy |\nHTTP streaming |\nProvider/client dependent | Purpose-built asupersync HTTP/TLS client feeding custom SSE parser |\nDeterministic test hooks |\nConventional async test setup | asupersync test/runtime hooks used widely in unit/integration tests |\n\nWhy this is useful in practice:\n\n**More predictable failure behavior** during aborts/timeouts because cancellation is checked in explicit loop boundaries and tool runners.**Cleaner resource lifetimes** because the runtime, timers, and I/O paths all share one concurrency substrate.**Less hidden coupling** because the main invariants live in Rust types/algorithms rather than spread across framework conventions.\n\nThese are the concrete invariants we rely on in this implementation:\n\n-\n**Turn-scoped agent lifecycle**- The main loop emits\n`AgentStart`\n\n,`TurnStart`\n\n,`TurnEnd`\n\n, and`AgentEnd`\n\nin a stable order. - Tool recursion is bounded by\n`max_tool_iterations`\n\n(default`50`\n\n) to avoid unbounded self-tool loops. - Benefit: stable event ordering for TUI/RPC consumers and predictable termination behavior.\n\n- The main loop emits\n-\n**Abort and timeout behavior is explicit**- Agent abort checks happen at turn boundaries and around tool execution.\n`bash`\n\ntimeout follows a clear escalation path: terminate process tree, grace period, then hard kill.- Benefit: fewer \"hung\" sessions and reduced orphan-process risk during aggressive tool use.\n\n-\n**Session writes are crash-resilient**- JSONL saves write to a temp file and persist atomically.\n- Session indexing uses SQLite WAL + lock file coordination for concurrent instances.\n- Benefit: better durability and resume reliability under multi-process usage.\n\n-\n**Compaction is threshold-driven and boundary-aware**- Trigger: estimated context tokens exceed\n`context_window - reserve_tokens`\n\n. - Cut-point logic prefers user-turn boundaries and preserves recent context budget.\n- Benefit: compaction recovers context without collapsing near-term task continuity.\n\n- Trigger: estimated context tokens exceed\n-\n**Capability policy is fail-closed and precedence-defined**- Resolution order: per-extension deny -> global deny -> per-extension allow -> default caps -> mode fallback.\n- Benefit: policy outcomes are explainable, deterministic, and auditable.\n\n-\n**Streaming parser tolerates real network chunking**- SSE parser handles CR/LF variants, multi-line\n`data:`\n\nfields, partial UTF-8 tails, and end-of-stream flush. - Benefit: incremental rendering remains robust across providers and network fragmentation.\n\n- SSE parser handles CR/LF variants, multi-line\n\nThe following `asupersync`\n\nprinciples are reflected directly in `pi_agent_rust`\n\narchitecture:\n\n**Single async substrate**: runtime, timers, fs, and HTTP/TLS all run on one coherent foundation.** Explicit context threading**:`AgentCx`\n\nwraps`asupersync::Cx`\n\nat subsystem boundaries (agent/tools/session/rpc).**Bounded operations over best-effort cleanup**: timeout paths and compaction thresholds are parameterized and enforceable.** Determinism hooks for tests**: timer-driver aware sleeps and asupersync test helpers reduce nondeterministic flakiness.\n\nCompared to the original TypeScript implementation, this shifts more correctness responsibility into the runtime and core algorithms themselves, instead of relying primarily on ecosystem conventions.\n\nThis is a second comparison pass focused on high-impact architectural deltas and rationale.\n\n| Area | Original pi-mono (`packages/coding-agent` ) |\n`pi_agent_rust` |\nWhy this divergence exists |\n|---|---|---|---|\nDistribution model |\nnpm package (`npm install -g @mariozechner/pi-coding-agent` ) |\nSingle Rust binary (`pi` ) |\nRemove Node runtime dependency and improve startup/deployment portability |\nExecution surfaces |\nInteractive + print + JSON mode + RPC + SDK | Interactive + print + JSON mode + RPC + Rust SDK | Rust SDK provides idiomatic companion API for embedding Pi programmatically (documented in `docs/sdk.md` ) |\nDefault built-in tool posture |\nDefaults to `read/write/edit/bash` (others available) |\nEight built-ins treated as first-class (`read/write/edit/bash/grep/find/ls/hashline_edit` ) |\nKeep common code-navigation, shell, and hashline-anchored edit workflows available without extra configuration |\nExtension trust model |\nExtension/package model documented as full system access | Embedded runtime with capability-gated hostcalls and policy profiles | Reduce ambient authority and make extension behavior auditable/deny-by-default |\nSession architecture emphasis |\nJSONL tree session model and branch navigation | JSONL v3 tree + explicit session index (SQLite sidecar) + default-enabled SQLite session backend support | Faster resume/lookups at scale and safer multi-instance coordination |\nStreaming transport stack |\nNode runtime networking stack | Purpose-built HTTP/TLS client + custom SSE parser on asupersync | Tighter control over chunking, parsing, and failure handling in long streams |\nCancellation/timeout mechanics |\nPlatform/event-loop cancellation conventions | Explicit abort signaling, bounded tool iterations, process-tree termination | Minimize hangs/orphans and make stop behavior deterministic under load |\nRuntime context model |\nFramework-level conventions and extension APIs | Explicit `AgentCx` /`asupersync::Cx` capability-scoped context threading |\nMake effect boundaries and testability first-class architectural constraints |\n\nPractical consequence of these deltas:\n\n- Extension/package workflows are compatible across both implementations.\n- The goal is functional equivalence to pi-mono with Rust-idiomatic patterns and performance improvements.\n- The Rust SDK provides a companion API that delivers equivalent capabilities without requiring TypeScript-specific adaptation patterns.\n`docs/parity-certification.json`\n\ntracks functional parity progress and certification status.\n\nThis section compares concrete implementation mechanics for equivalent high-level behavior.\n\n| Algorithm | pi-mono baseline mechanism | Rust implementation mechanism | Why the Rust variant exists |\n|---|---|---|---|\nSession context rebuild after compaction |\n`buildSessionContext()` emits compaction summary, then messages from `firstKeptEntryId` (pre-compaction path), then post-compaction entries |\n`to_messages_for_current_path()` uses the same ordering and adds a fallback if `first_kept_entry_id` is missing |\nAvoid silent context loss when compaction anchors are orphaned/corrupted |\nJSONL persistence |\nIncremental append (`appendFileSync` ) plus full rewrite (`writeFileSync` ) for migrations/rewrites |\nSave via temp file + atomic persist/replace | Keep on-disk session state crash-resilient during save operations |\nSession discovery/resume |\nDirectory/file scan and mtime sorting of JSONL files | SQLite session index sidecar + WAL + lock file + staleness-triggered full reindex | Bound resume lookup cost and coordinate concurrent processes |\nCompaction token accounting |\nUses assistant usage (`totalTokens` else `input+output+cacheRead+cacheWrite` ) plus heuristic trailing estimates |\nUses assistant usage (`total_tokens` else `input+output` ) plus heuristic trailing estimates; fixed image token estimate |\nKeep accounting stable across providers with uneven cache-token reporting while staying conservative |\nCut-point + split-turn handling |\nValid cut points exclude tool results; split turns are summarized as history + turn-prefix context | Same cut-point class and split-turn strategy, implemented in Rust entry/message model | Preserve tool-call/result adjacency and turn coherence under budget pressure |\nBash timeout/process cleanup |\nTimeout/abort kills process tree (`killProcessTree` ) and returns tail-truncated output |\nTimeout escalation (`TERM` then grace then `KILL` ) + process-tree walk + shell exit trap + tail truncation |\nEnforce bounded cleanup and reduce descendant-process leaks from background jobs |\nStreaming event decoding |\nTransport semantics are exposed (`sse` /`websocket` /`auto` ); parser details are runtime-internal |\nExplicit SSE parser with BOM stripping, CR/LF normalization, UTF-8 tail buffering, and flush-on-end | Make byte-to-event behavior deterministic and provider-SDK-independent |\n\nThe sections above compare mechanics. This section calls out concrete features present in this Rust port that are not part of the pi-mono baseline implementation model.\n\n| Rust-port feature | Why it is useful/compelling |\n|---|---|\n(`pi doctor` diagnostics command`text` /`json` /`markdown` , `--only` , `--fix` , swarm preflight, extension compatibility checks) |\nGives actionable environment + compatibility diagnostics, supports CI gating (non-zero on failures), can auto-fix safe issues like missing dirs/permissions, and reports read-only multi-agent readiness before swarm work |\nCapability-gated extension policy profiles (`safe` / `balanced` / `permissive` ) with per-extension overrides |\nLets operators run shared extensions with explicit capability boundaries instead of ambient full-system access |\nSecret-aware extension env filtering (`pi.env()` blocklist for keys/tokens/secrets) |\nReduces accidental credential exposure from extension code paths |\nPer-extension trust lifecycle + kill-switch audit trail (`pending` /`acknowledged` /`trusted` /`killed` , `kill_switch` , `lift_kill_switch` ) |\nSupports immediate containment, explicit operator provenance, and controlled re-entry after review |\nHostcall compatibility-lane emergency controls (global/per-extension forced-compat switches + reason codes) |\nGives operators a deterministic rollback path for fast-lane incidents without losing extension availability |\nRuntime risk controller for extension hostcalls (configurable, fail-closed by default) |\nAdds another enforcement layer beyond static policy for suspicious runtime behavior in extension call flows |\nArgument-aware runtime risk scoring for shell paths (`dcg_rule_hit` , `dcg_heredoc_hit` , heredoc AST inspection across Bash/Python/JS/TS/Ruby) |\nDetects destructive intent hidden in multiline scripts and wrapper commands before hostcall execution |\nTamper-evident runtime risk ledger tooling (`ext_runtime_risk_ledger verify |\nreplay |\nUnified incident evidence bundle export (risk ledger, security alerts, hostcall telemetry, exec mediation, secret-broker events) |\nIncident response can triage from one structured artifact set instead of stitching ad-hoc logs |\nDeterministic hostcall reactor mesh with optional NUMA slab pool (shard affinity, global-order drain, bounded SPSC lanes, telemetry) |\nKeeps extension dispatch predictable under load and surfaces queue/backpressure behavior for tuning |\nWarm isolate pool + startup prewarm handoff |\nMoves JS runtime preparation off the first interactive turn and reuses warmed state safely between runs |\nExtension preflight static analysis (imports/forbidden-pattern scan with policy-aware hints) |\nCatches risky extension patterns before runtime execution |\nNode/Bun-compatible extension runtime without Node/Bun dependency (embedded QuickJS + shims) |\nRuns legacy extension workflows in a single native binary deployment model |\nExtension compatibility scanner + conformance harness |\nMakes extension support measurable and auditable instead of anecdotal |\nSQLite session index sidecar (WAL + lock + stale reindex path) |\nGives fast session resume/list operations at scale without scanning every JSONL file on each query |\nSession Store V2 rollback and migration ledger (segmented log + checkpoints + rollback events) |\nLong-session recovery can unwind to a known checkpoint with explicit migration/rollback provenance |\nDefault-enabled SQLite session storage support (`sqlite-sessions` feature) |\nSupports deployments that want database-backed session persistence in addition to JSONL; disable with `--no-default-features` when building a minimal binary |\nCrash-resilient session save path (temp file + atomic persist) |\nImproves session-file durability during writes and reduces partial-write failure modes |\nUnified hostcall dispatcher with typed taxonomy mapping (`timeout` / `denied` / `io` / `invalid_request` / `internal` ) |\nProduces consistent extension/runtime error semantics and easier client handling |\nFail-closed evidence-lineage gates (`run_id` /`correlation_id` + cross-artifact lineage checks) |\nRejects stale or cherry-picked conformance/perf artifacts at release-gate time |\nStructured auth diagnostics with stable machine codes |\nImproves troubleshooting and operational visibility without leaking sensitive credential material |\n\nPi deliberately uses advanced math where it improves runtime behavior or benchmark confidence. The goal is not “fancy formulas in docs”; it is safer policy decisions, faster recovery from workload shifts, and more trustworthy performance attribution.\n\nIn the extension dispatcher, Pi combines CUSUM and Bayesian online change-point detection to detect load-regime changes early (for example when hostcall traffic suddenly spikes or stalls).\n\nIntuition: CUSUM catches persistent drift; BOCPD catches sudden regime changes without brittle fixed thresholds.\n\nPi tracks nonconformity scores (absolute residuals from the running mean) and treats out-of-interval events as anomalies.\n\nIntuition: thresholds adapt from recent behavior instead of hard-coding one static latency cutoff.\n\nPi’s safety envelope includes a PAC-Bayes-kl bound over extension outcomes, and can veto aggressive optimization when the bound is too high.\n\nIntuition: this gives an explicit uncertainty-aware ceiling on true error risk before allowing more aggressive runtime behavior.\n\nBefore approving policy moves, Pi evaluates candidate behavior from trace data:\n\nIntuition: Pi fails closed if sample support is weak, uncertainty is high, or estimated regret is above threshold.\n\nThe VOI planner prioritizes probes that provide the most expected learning under a strict overhead budget.\n\nIntuition: run only the experiments that are likely to change decisions; skip stale or low-value probes.\n\nFor phase-1 matrix benchmarking, Pi computes stage attribution weighted by realistic workload size (`session_messages`\n\n) and reports confidence intervals.\n\n\\frac{\\sum_i w_i,m_{i,s}}{\\sum_i w_i,t_i}\\cdot 100, \\quad w_i=\\text{session_messages}_i $$\n\nIntuition: prioritize what dominates real end-to-end latency, not just isolated microbench hotspots.\n\nPi also includes an online tuner path for batch/time-slice controls with explicit rollback behavior:\n\n\\mathrm{clip}!\\left(\\tau_t - \\eta\\nabla_{\\tau}\\mathcal{L}*t,;\\tau*{\\min},\\tau_{\\max}\\right)\n$$\n\nIntuition: the system adapts continuously, but if instantaneous loss exceeds a rollback threshold it immediately returns to a safer profile.\n\n| Technique | Where in Pi | Why it helps |\n|---|---|---|\n| CUSUM + BOCPD | Extension dispatcher regime detector | Detects traffic regime shifts early and robustly |\n| Conformal intervals | Safety envelope | Adaptive anomaly gating without static magic numbers |\n| PAC-Bayes bound | Safety envelope veto path | Fails closed when uncertainty/risk is too high |\n| IPS/WIS/DR + ESS | Off-policy evaluator | Approves policy changes only with adequate support |\n| VOI planning | Experiment scheduler | Uses overhead budget on highest-value probes |\n| Weighted attribution + CI | Phase-1 perf matrix reports | Ranks optimization work by realistic user impact |\n| OCO + regret rollback | Runtime controller | Adapts under load while bounding unsafe drift |\n\nThe SSE (Server-Sent Events) parser is a custom implementation that handles Anthropic's streaming response format. Unlike library-based approaches, the parser operates as a state machine that processes bytes incrementally:\n\n```\nBytes → Line Accumulator → Event Parser → Typed StreamEvent\n```\n\n**Key characteristics:**\n\n| Property | Implementation |\n|---|---|\nBuffering |\nZero-copy where possible; lines accumulated only when incomplete |\nEvent types |\n12 distinct variants: MessageStart, ContentBlockStart, ContentBlockDelta, ContentBlockStop, MessageDelta, MessageStop, Ping, Error, and thinking-specific events |\nError recovery |\nMalformed events logged but don't crash the stream |\nMemory |\nFixed-size rolling buffer prevents unbounded growth |\n\nThe parser handles edge cases like:\n\n- Multi-line\n`data:`\n\nfields (concatenated with newlines) - Events split across TCP packet boundaries\n- The\n`event:`\n\nfield appearing before or after`data:`\n\n- CRLF and LF line endings interchangeably\n\nLarge outputs from tools (file reads, command output, grep results) must be truncated to avoid exhausting the LLM's context window. The truncation algorithm preserves usefulness while staying within limits:\n\n```\n┌─────────────────────────────────────────┐\n│           Original Content              │\n│         (potentially huge)              │\n└─────────────────────────────────────────┘\n                    │\n                    ▼\n┌─────────────────────────────────────────┐\n│  HEAD: First N/2 lines                  │\n│  ─────────────────────────              │\n│  [... X lines truncated ...]            │\n│  ─────────────────────────              │\n│  TAIL: Last N/2 lines                   │\n└─────────────────────────────────────────┘\n```\n\n**Constants:**\n\n| Limit | Value | Rationale |\n|---|---|---|\n`MAX_LINES` |\n2000 | Balances context usage vs. completeness |\n`MAX_BYTES` |\n1MB | Prevents binary file accidents |\n`GREP_MAX_LINE_LENGTH` |\n500 chars | Truncates minified code |\n\nThe algorithm:\n\n- Splits content into lines\n- If line count exceeds\n`MAX_LINES`\n\n, takes first 1000 and last 1000 - Inserts a marker showing how many lines were omitted\n- If byte count still exceeds\n`MAX_BYTES`\n\n, applies byte-level truncation - Returns metadata indicating truncation occurred, enabling the LLM to request specific ranges\n\nThe `bash`\n\ntool must handle runaway processes, infinite loops, and fork bombs without leaving orphans. The implementation uses the `sysinfo`\n\ncrate to walk the process tree:\n\n```\n// Pseudocode for process cleanup\nfn kill_process_tree(root_pid: Pid) {\n    let system = System::new();\n    let children = find_all_descendants(root_pid, &system);\n\n    // Kill children first (deepest first), then parent\n    for child in children.iter().rev() {\n        kill(child, SIGKILL);\n    }\n    kill(root_pid, SIGKILL);\n}\n```\n\n**Timeout behavior:**\n\n- Command starts with configurable timeout (default 120s)\n- Output streams to a rolling buffer in real-time\n- On timeout: SIGTERM sent, 5s grace period, then SIGKILL\n- Process tree walked and all descendants killed\n- Exit code set to indicate timeout vs. normal termination\n\nTo avoid orphaned background jobs (e.g. `cmd &`\n\n), the bash script installs an `EXIT`\n\ntrap that waits for any remaining child processes and then exits with the original command's status.\n\nThis prevents the common failure mode where killing a shell leaves its children running.\n\nSessions use a tree structure rather than a flat list, enabling conversation branching (useful when exploring different approaches):\n\n```\n                    ┌─────────┐\n                    │ Message │ (root)\n                    │   #1    │\n                    └────┬────┘\n                         │\n                    ┌────▼────┐\n                    │ Message │\n                    │   #2    │\n                    └────┬────┘\n                         │\n              ┌──────────┼──────────┐\n              │                     │\n         ┌────▼────┐          ┌────▼────┐\n         │ Message │          │ Message │ (branch)\n         │   #3    │          │   #3b   │\n         └────┬────┘          └────┬────┘\n              │                    │\n         ┌────▼────┐          ┌────▼────┐\n         │ Message │          │ Message │\n         │   #4    │          │   #4b   │\n         └─────────┘          └─────────┘\n```\n\n**JSONL format (v3):**\n\nEach line is a self-contained JSON object with a `type`\n\ndiscriminator:\n\n```\n{\"type\":\"session\",\"version\":3,\"cwd\":\"/project\",\"created\":\"2024-01-15T10:30:00Z\"}\n{\"type\":\"message\",\"id\":\"a1b2c3d4\",\"parent\":\"root\",\"role\":\"user\",\"content\":[...]}\n{\"type\":\"message\",\"id\":\"e5f6g7h8\",\"parent\":\"a1b2c3d4\",\"role\":\"assistant\",\"content\":[...]}\n{\"type\":\"model_change\",\"id\":\"i9j0k1l2\",\"parent\":\"e5f6g7h8\",\"model\":\"claude-sonnet-4-20250514\"}\n```\n\nThe `parent`\n\nfield creates the tree. Replaying a session walks the tree from root to the current leaf. Branching creates a new message with a different `parent`\n\nthan the previous continuation.\n\nThe `Provider`\n\ntrait abstracts over different LLM backends:\n\n``` php\n#[async_trait]\npub trait Provider: Send + Sync {\n    fn name(&self) -> &str;\n    fn models(&self) -> &[Model];\n\n    async fn stream(\n        &self,\n        context: &Context,\n        options: &StreamOptions,\n    ) -> Result<impl Stream<Item = Result<StreamEvent>>>;\n}\n```\n\n**Context structure:**\n\n```\npub struct Context {\n    pub system: Option<String>,      // System prompt\n    pub messages: Vec<Message>,       // Conversation history\n    pub tools: Vec<ToolDef>,          // Available tools with JSON schemas\n}\n```\n\n**StreamOptions:**\n\n```\npub struct StreamOptions {\n    pub model: String,\n    pub max_tokens: u32,\n    pub temperature: Option<f32>,\n    pub thinking: Option<ThinkingConfig>,  // Extended thinking settings\n    pub stop_sequences: Vec<String>,\n}\n```\n\nThis design allows adding new providers (OpenAI, Gemini) without modifying the agent loop. Each provider translates the common types to its wire format and emits a unified `StreamEvent`\n\nstream.\n\nLong conversations eventually exceed the model's context window. Pi's compaction algorithm reclaims space by summarizing older messages while preserving recent context.\n\nThe algorithm runs automatically after each agent turn when estimated token usage exceeds `context_window - reserve_tokens`\n\n:\n\n```\n┌──────────────────────────────────────────────────────────────┐\n│                     Full Conversation                         │\n│  msg1 → msg2 → msg3 → ... → msgN-5 → msgN-4 → ... → msgN   │\n│  ├──── older messages ─────┤ ├─── recent messages ──────────┤ │\n│                                                              │\n│  Step 1: Find cut point at a valid turn boundary             │\n│  Step 2: LLM summarizes msgs 1..N-5 into compact paragraph  │\n│  Step 3: Store Compaction entry in session JSONL             │\n│  Step 4: Next agent call uses [summary] + msgs N-4..N       │\n└──────────────────────────────────────────────────────────────┘\n```\n\n**Token estimation** uses a conservative `chars ÷ 4`\n\nheuristic for text and a flat 1,200 tokens per image. When an assistant message includes a `usage`\n\nfield from the API, that measured value takes precedence over the heuristic.\n\n**Cut point selection** prefers boundaries between complete user-assistant turns. If the budget forces a mid-turn cut, the algorithm includes prefix messages from the split turn so the model retains context about what was being discussed at the boundary.\n\n**File operation tracking** extracts `read`\n\n, `write`\n\n, and `edit`\n\ntool calls from the messages being summarized. The compaction prompt includes these paths so the summary preserves awareness of which files were examined or modified:\n\n```\n<read-files>\nsrc/main.rs\nsrc/config.rs\n</read-files>\n\n<modified-files>\nsrc/auth.rs\n</modified-files>\n```\n\n**Configurable parameters:**\n\n| Parameter | Default | Purpose |\n|---|---|---|\n`reserve_tokens` |\n8% of context window | Safety margin for response generation |\n`keep_recent_tokens` |\n10% of context window | Minimum recent context preserved |\n\nCompaction can also be triggered manually with `/compact`\n\nin interactive mode or the `compact`\n\nRPC command.\n\nPi routes model requests through a provider factory that resolves the correct backend implementation from a `(provider, model, api)`\n\ntuple.\n\n**Resolution flow:**\n\n```\nUser specifies --provider openai --model gpt-4o\n               │\n               ▼\n  ┌──────────────────────────┐\n  │  Provider Metadata Table  │  Maps \"openai\" → canonical ID,\n  │                           │  determines API type (Completions\n  │                           │  vs Responses vs custom)\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  URL Normalization         │  Appends /chat/completions,\n  │                            │  /responses, or /chat depending\n  │                            │  on detected API type\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  Compat Config             │  Applies per-model overrides:\n  │                            │  system_role_name, max_tokens\n  │                            │  field name, feature flags\n  └────────────┬──────────────┘\n               │\n  ┌────────────▼──────────────┐\n  │  Provider Instance         │  Anthropic | OpenAI | Gemini\n  │                            │  Cohere | Azure | Bedrock | ...\n  └───────────────────────────┘\n```\n\n** models.json overrides**: Users can define custom providers in\n\n`~/.pi/agent/models.json`\n\nor `.pi/models.json`\n\n. Each entry specifies a model ID, base URL, API type, and optional compat flags, letting you route to self-hosted models, proxies, or providers that Pi does not natively support.**Compat config** handles the differences between OpenAI-compatible APIs:\n\n| Override | Example | Purpose |\n|---|---|---|\n`system_role_name` |\n`\"developer\"` |\no1 models use \"developer\" instead of \"system\" |\n`max_tokens_field` |\n`\"max_completion_tokens\"` |\nSome models require a different field name |\n`supports_tools` |\n`false` |\nSuppress tool definitions for models that reject them |\n`supports_streaming` |\n`false` |\nFall back to non-streaming for incompatible endpoints |\n`custom_headers` |\n`{\"X-Custom\": \"val\"}` |\nPer-provider header injection |\n\n**Fuzzy matching**: When a provider name doesn't match any known provider, Pi computes edit distance against all registered names and suggests the closest match in the error message.\n\nExtensions run in an embedded QuickJS runtime (`rquickjs`\n\ncrate) and communicate with Pi through a structured hostcall protocol. This is the mechanism that lets JavaScript code invoke Pi's built-in tools, make HTTP requests, and interact with the session, all without direct OS access.\n\n**Execution model:**\n\n```\n┌─────────────────── QuickJS VM ───────────────────┐\n│                                                   │\n│  extension.js calls:                              │\n│    pi.tool(\"read\", {path: \"src/main.rs\"})         │\n│      │                                            │\n│      ▼                                            │\n│    enqueue HostcallRequest {                      │\n│      call_id: \"hc-0042\",                          │\n│      kind: Tool { name: \"read\" },                 │\n│      payload: { path: \"src/main.rs\" },            │\n│    }                                              │\n│      │                                            │\n│      ▼                                            │\n│    return Promise (resolve/reject stored in map)  │\n│                                                   │\n└────────────────────────┬──────────────────────────┘\n                         │\n    drain_hostcall_requests()\n                         │\n                         ▼\n┌─────────────── ExtensionDispatcher ──────────────┐\n│                                                   │\n│  1. Check capability policy:                      │\n│     read tool → requires \"read\" capability        │\n│     → Policy says: Allow / Deny / Prompt          │\n│                                                   │\n│  2. If allowed → dispatch to ToolRegistry         │\n│     → Execute read tool                           │\n│     → Get ToolOutput                              │\n│                                                   │\n│  3. complete_hostcall(\"hc-0042\", Ok(result))      │\n│     → Resolves the Promise in QuickJS             │\n│                                                   │\n│  4. runtime.tick()                                │\n│     → Drains Promise .then() chains               │\n│     → Extension JS continues execution            │\n│                                                   │\n└───────────────────────────────────────────────────┘\n```\n\n**Capability mapping**: Each hostcall kind maps to a required capability:\n\n| Hostcall | Required Capability | Dangerous? |\n|---|---|---|\n`pi.tool(\"read\", ...)` |\n`read` |\nNo |\n`pi.tool(\"write\", ...)` |\n`write` |\nNo |\n`pi.tool(\"bash\", ...)` |\n`exec` |\nYes |\n`pi.http(request)` |\n`http` |\nNo |\n`pi.exec(cmd, args)` |\n`exec` |\nYes |\n`pi.env(key)` |\n`env` |\nYes |\n`pi.session(op, ...)` |\n`session` |\nNo |\n`pi.ui(op, ...)` |\n`ui` |\nNo |\n`pi.log(entry)` |\n`log` |\nNo (always allowed) |\n\n**Deduplication**: Each hostcall's parameters are canonicalized (object keys sorted, structure normalized) and SHA-256 hashed. Identical requests within a short window can be deduplicated to avoid redundant tool executions.\n\n**Fast lane vs compatibility lane**: Pi has two execution lanes for hostcalls:\n\n**Fast lane** is used when the call shape matches known safe patterns (for example common`tool`\n\nand`session`\n\noperations). This avoids extra allocation and parsing work.**Compatibility lane** is the fallback for uncommon or partially-specified calls.- Both lanes still enforce the same capability policy and permission checks.\n- Operators can force compatibility-lane routing globally or per extension as an emergency control path.\n\nFor observability, each call is tagged with a stable lane key (for example `tool|tool.read|filesystem`\n\nor `tool|fallback|filesystem`\n\n) so latency and failure trends can be grouped consistently.\n\n**Built-in consistency guard (shadow dual execution)**: Pi can sample a small subset of read-only hostcalls, execute them through both lanes, and compare canonical output fingerprints. If divergence crosses a configured budget, Pi automatically backs off the fast lane for a period. This gives performance wins without silently changing behavior.\n\n**Adaptive dispatch mode under load**: Pi can switch between:\n\n`sequential_fast_path`\n\nfor simpler/low-contention workloads`interleaved_batching`\n\nwhen contention and queue pressure rise\n\nMode changes are gated by sample coverage and risk checks, so Pi does not switch based on thin or cherry-picked evidence.\n\n**Runtime telemetry for debugging and tuning**: Pi records structured hostcall telemetry (`pi.ext.hostcall_telemetry.v1`\n\n) with lane choice, fallback reason, dispatch latency share, marshalling path, and optimization hit/miss fields. This is used by perf reports and reliability diagnostics.\n\n**Auto-repair pipeline**: When an extension fails to load or produces runtime errors, Pi's repair system can automatically fix common issues:\n\n| Repair Mode | Behavior |\n|---|---|\n`Off` |\nNo repairs |\n`Suggest` |\nLog suggestions, don't apply |\n`AutoSafe` (default) |\nApply provably safe fixes (missing file paths, asset references) |\n`AutoStrict` |\nApply aggressive heuristic fixes (pattern-based transforms) |\n\n**Compatibility scanner**: Before loading, Pi statically analyzes extension source code for imports, `require()`\n\ncalls, and forbidden patterns (`eval`\n\n, `Function()`\n\n, `process.binding`\n\n, `dlopen`\n\n). The scan produces a capability evidence ledger that informs policy decisions.\n\n**Environment variable filtering**: Extensions calling `pi.env()`\n\nhit a blocklist that denies access to API keys, credentials, tokens, and private keys. The filter blocks exact matches (`ANTHROPIC_API_KEY`\n\n, `AWS_SECRET_ACCESS_KEY`\n\n), suffix patterns (`*_API_KEY`\n\n, `*_SECRET`\n\n, `*_TOKEN`\n\n), and prefix patterns (`AWS_SECRET_*`\n\n, `AWS_SESSION_*`\n\n). Only `PI_*`\n\nvariables are unconditionally allowed.\n\n**Trust lifecycle and kill switch**: Extension trust state is tracked explicitly (`pending`\n\n, `acknowledged`\n\n, `trusted`\n\n, `killed`\n\n). A kill switch demotes an extension to `killed`\n\n, quarantines it in the runtime risk controller, emits a critical alert, and writes an audit record. Lifting the switch requires an explicit operator action and moves the extension back to `acknowledged`\n\n.\n\nThe extension runtime includes a few small decision engines so behavior stays stable as workload patterns change:\n\n**Value-of-information planner (VOI)**: Ranks candidate probes by \"expected learning per millisecond\" and picks the best set under a strict overhead budget. Stale or low-value candidates are skipped with explicit reasons.**Shard load controller**: Adjusts routing weights, batch budgets, and backoff/help factors based on queue pressure, latency, and starvation risk. Damping and oscillation guards prevent overreaction.**Policy safety evaluator**: Replays historical samples with multiple estimators and only approves a policy when sample support is strong, uncertainty is low, and predicted regret stays within limit.\n\nThese pieces are intentionally conservative: if confidence is weak, Pi holds steady instead of making an aggressive switch.\n\nThe interactive mode uses the **Elm Architecture** (Model-Update-View) via the `charmed_rust`\n\nlibrary family, which is a Rust port of Go's [Bubble Tea](https://github.com/charmbracelet/bubbletea) framework.\n\n**Component stack:**\n\n```\n┌────────────────────────────────────────────────────┐\n│                 Terminal (crossterm)                │\n│  Raw mode │ Alt screen │ Keyboard/Mouse events      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             bubbletea Program Loop                  │\n│  Init() → Update(Msg) → View() → render cycle      │\n└──────────────────────┬─────────────────────────────┘\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│                  PiApp (Model)                      │\n│                                                     │\n│  ┌─────────────┐ ┌──────────────┐ ┌─────────────┐  │\n│  │  TextArea    │ │  Viewport    │ │  Spinner     │  │\n│  │  (editor)    │ │  (convo)     │ │  (status)    │  │\n│  └─────────────┘ └──────────────┘ └─────────────┘  │\n│                                                     │\n│  ┌─────────────────────────────────────────────┐    │\n│  │           Overlay Stack                      │    │\n│  │  Model Selector │ Session Picker │ /tree     │    │\n│  │  Settings UI    │ Theme Picker   │ Branches  │    │\n│  │  Capability Prompt (extension UI)            │    │\n│  └─────────────────────────────────────────────┘    │\n└──────────────────────┬─────────────────────────────┘\n                       │\n              async channels (mpsc)\n                       │\n┌──────────────────────▼─────────────────────────────┐\n│             Agent Async Task                        │\n│  Runs on asupersync runtime                         │\n│  Streams provider responses                         │\n│  Executes tools                                     │\n│  Sends PiMsg events back to TUI thread              │\n└────────────────────────────────────────────────────┘\n```\n\n**The async/sync bridge**: The agent runs on the `asupersync`\n\nasync runtime in a separate thread. It communicates with the bubbletea UI thread through `mpsc`\n\nchannels. Each streaming event (text delta, tool start, tool update, agent done) becomes a `PiMsg`\n\nvariant delivered to `PiApp::update()`\n\n, keeping the UI responsive during API streaming and tool execution.\n\n**Viewport scrolling**: The conversation viewport tracks whether the user is at the bottom. When new content arrives and the user hasn't scrolled up, the viewport auto-follows the stream tail. Scrolling up disables auto-follow; pressing `End`\n\nor typing a new message re-enables it.\n\n**Overlay system**: Modal UIs (model selector, session picker, branch navigator, extension capability prompts) stack on top of the main conversation view. Each overlay captures keyboard input until dismissed. Only the topmost active overlay receives events.\n\n**Slash commands** available in the interactive editor:\n\n| Command | Action |\n|---|---|\n`/help` |\nShow available commands and keybindings |\n`/model` or `Ctrl+L` |\nOpen model selector with fuzzy search |\n`Ctrl+P` / `Ctrl+Shift+P` |\nCycle scoped models forward/backward |\n`/tree` |\nBrowse and fork the conversation tree |\n`/clear` |\nClear conversation and start fresh |\n`/compact` |\nTrigger manual compaction |\n`/thinking <level>` |\nChange thinking level mid-conversation |\n`/share` |\nExport session to GitHub Gist |\n`/exit` or `Ctrl+C` |\nExit Pi |\n\nThe RPC mode (`pi --mode rpc`\n\n) exposes a line-delimited JSON protocol over stdin/stdout for programmatic integration. Each line is a self-contained JSON object.\n\n**Client → Pi (stdin):**\n\n```\n{\"type\": \"prompt\", \"message\": \"Explain this function\", \"id\": \"req-001\"}\n{\"type\": \"steer\", \"message\": \"Focus on error handling\"}\n{\"type\": \"follow_up\", \"message\": \"Now add tests\"}\n{\"type\": \"abort\"}\n{\"type\": \"get_state\"}\n{\"type\": \"compact\", \"reserveTokens\": 8192, \"keepRecentTokens\": 20000}\n```\n\n**Pi → Client (stdout):**\n\n```\n{\"type\": \"agent_start\", \"sessionId\": \"...\"}\n{\"type\": \"message_update\", \"message\": {...}, \"assistantMessageEvent\": {\"type\": \"text_delta\", \"delta\": \"The function\", \"contentIndex\": 0}}\n{\"type\": \"tool_execution_start\", \"toolCallId\": \"...\", \"toolName\": \"read\", \"args\": {}}\n{\"type\": \"tool_execution_end\", \"toolCallId\": \"...\", \"toolName\": \"read\", \"result\": {}, \"isError\": false}\n{\"type\": \"agent_end\", \"sessionId\": \"...\", \"messages\": [...]}\n{\"type\": \"response\", \"id\": \"req-001\", \"command\": \"prompt\", \"success\": true, \"data\": {\"status\": \"ok\"}}\n```\n\n**I/O architecture**: Two dedicated threads handle stdin reading and stdout writing, bridged to the async agent runtime via channels. The stdin thread retries on transient errors to prevent dropped input. The stdout thread flushes after every line to prevent buffering delays.\n\n**Message queuing**: While the agent is streaming a response, incoming messages are routed to one of two queues:\n\n| Queue | Behavior | Use Case |\n|---|---|---|\nSteering |\nInterrupts current response; processed on next turn | Course corrections |\nFollow-up |\nQueued until current response completes | Sequential instructions |\n\nQueue modes (`All`\n\nor `OneAtATime`\n\n) control whether multiple queued messages are batched into a single turn or processed individually.\n\n**Extension UI over RPC**: When an extension requests user input (capability prompt, selection dialog), Pi emits an `extension_ui_request`\n\nevent. The client renders the prompt in its own UI and responds with an `extension_ui_response`\n\nmessage. IDE extensions can then present native UI for capability decisions instead of falling back to terminal prompts.\n\nSession resume (`pi -c`\n\nor `pi -r`\n\n) needs to find the most recent session for the current project without scanning every JSONL file on disk. Pi maintains a SQLite index (`session-index.sqlite`\n\n) that provides constant-time lookups.\n\n**Schema:**\n\n```\nCREATE TABLE sessions (\n    path            TEXT PRIMARY KEY,\n    id              TEXT NOT NULL,\n    cwd             TEXT NOT NULL,\n    timestamp       TEXT NOT NULL,\n    message_count   INTEGER NOT NULL,\n    last_modified   INTEGER NOT NULL,\n    size_bytes      INTEGER NOT NULL,\n    name            TEXT\n);\n```\n\n**Update lifecycle:**\n\n- After saving a session JSONL file, Pi upserts its metadata into the index\n`pi -c`\n\nqueries`WHERE cwd = ? ORDER BY last_modified DESC LIMIT 1`\n\n`pi -r`\n\nqueries the same table and presents a picker sorted by recency\n\n**Concurrency**: A file-based lock (`session-index.lock`\n\n) serializes writes from concurrent Pi instances. Reads use WAL mode for non-blocking access.\n\n**Staleness-based reindexing**: If the index is older than a configurable threshold, Pi runs a full re-scan of the sessions directory to catch files created by other instances or manual edits. The re-scan keeps the index accurate without a centralized daemon.\n\nPi also supports a v2 sidecar store next to JSONL sessions for faster resume and stronger corruption checks on long histories.\n\n**What it adds:**\n\n- Segmented append log files (instead of one ever-growing JSONL file)\n- Offset index rows for direct seeks and fast tail reads\n- Periodic checkpoints and a manifest snapshot\n- Migration ledger entries for auditability\n- Checkpoint-based rollback path with explicit rollback event logging\n\n**How resume works:**\n\n- If a v2 sidecar exists and is fresh, Pi opens from the sidecar index + segments.\n- If sidecar data is stale relative to the source JSONL, Pi falls back to JSONL parsing.\n- If index data is missing/corrupt but segments are valid, Pi rebuilds the index.\n\n**Integrity strategy:**\n\n- Segment frames carry payload and chain hashes.\n- Index rows store byte offsets plus CRC32C checksums.\n- Validation checks offset bounds, checksum matches, and frame/index alignment before trusting the sidecar.\n- Truncated trailing frames are recoverable during rebuild; non-EOF frame corruption fails closed instead of silently dropping data.\n\n**CLI support:**\n\n`pi migrate <path> --dry-run`\n\nvalidates migration without writing.`pi migrate <path>`\n\nperforms JSONL-to-v2 migration and verifies parity.\n\nBeyond simple API keys, Pi supports OAuth, AWS credential chains, service key exchange, and bearer-token auth. Credentials are stored in `~/.pi/agent/auth.json`\n\nwith file-locked access to prevent corruption from concurrent instances. Stored API keys can be literal strings, `$ENV:VAR_NAME`\n\nreferences, or `$CMD:shell command`\n\n/ `$COMMAND:shell command`\n\nsources that resolve trimmed stdout at request time.\n\n| Mechanism | Providers | Details |\n|---|---|---|\nAPI Key |\nAnthropic, OpenAI, Gemini, Cohere, and many OpenAI-compatible providers | Static key via env var or settings |\nOAuth |\nAnthropic, OpenAI Codex, Google Gemini CLI, Google Antigravity, Kimi for Coding, GitHub Copilot, GitLab, and extension-defined OAuth providers | PKCE/state-validated flow with automatic refresh; Kimi uses device flow |\nAWS Credentials |\nBedrock | Access key + secret + optional session token; region-aware |\nService Key |\nSAP AI Core | Client ID/secret exchange for bearer token |\nBearer Token |\nCustom providers | Static token in auth storage |\n\n**OAuth token lifecycle:**\n\n- User runs\n`pi`\n\nwith an OAuth-configured provider - Pi checks\n`auth.json`\n\nfor an existing token - If missing: opens browser to authorization URL, user authenticates, Pi receives authorization code, exchanges it for access + refresh tokens, stores both with expiry timestamp\n- If expired but refresh token valid: exchanges refresh token for new access token, updates\n`auth.json`\n\n- Bearer token attached to API requests\n\nGoogle CLI-style OAuth providers carry project metadata with the token payload. Pi preserves and refreshes that payload and can resolve project IDs from `GOOGLE_CLOUD_PROJECT`\n\nor local `gcloud`\n\nconfig when needed.\n\n**Credential status reporting**: `pi config`\n\nshows the status of each configured provider's credentials: `Missing`\n\n, `ApiKey`\n\n, `OAuthValid`\n\n(with time until expiry), `OAuthExpired`\n\n(with time since expiry), `AwsCredentials`\n\n, or `BearerToken`\n\n.\n\n**Diagnostic codes**: Auth failures produce specific diagnostic codes (`MissingApiKey`\n\n, `InvalidApiKey`\n\n, `QuotaExceeded`\n\n, `OAuthTokenRefreshFailed`\n\n, `MissingAzureDeployment`\n\n, `MissingRegion`\n\n, etc.) with context-specific error hints rather than generic messages.\n\nRead file contents (optionally images):\n\n```\nInput: { \"path\": \"src/main.rs\", \"offset\": 10, \"limit\": 50 }\n```\n\n- Supports images (jpg, png, gif, webp) with optional auto-resize\n- Streams file bytes in chunks with hard size limits to reduce peak memory usage\n- Applies defensive image decode limits to block decompression-bomb/OOM inputs\n- Truncates at 2000 lines or 1MB\n- Returns continuation hint if truncated\n\nExecute shell commands with timeout and output capture:\n\n```\nInput: { \"command\": \"cargo test\", \"timeout\": 120 }\n```\n\n- Default 120s timeout, configurable per-call\n- Set\n`timeout: 0`\n\nto disable the default timeout - Process tree cleanup on timeout (kills children)\n- Rolling buffer for real-time output\n- Full output saved to temp file if truncated\n\nSurgical string replacement:\n\n```\nInput: { \"path\": \"src/lib.rs\", \"old\": \"fn foo()\", \"new\": \"fn bar()\" }\n```\n\n- Exact string matching (no regex)\n- Fails if old string not found or ambiguous\n- Returns diff preview\n\nSearch file contents:\n\n```\nInput: { \"pattern\": \"TODO\", \"path\": \"src/\", \"context\": 2, \"limit\": 100 }\n```\n\n- Regex patterns supported\n- Context lines before/after matches\n- Respects .gitignore\n\nDiscover files by pattern:\n\n```\nInput: { \"pattern\": \"*.rs\", \"path\": \"src/\", \"limit\": 1000 }\n```\n\n- Glob patterns via\n`fd`\n\n- Sorted by modification time\n- Respects .gitignore\n\nList directory contents:\n\n```\nInput: { \"path\": \"src/\", \"limit\": 500 }\n```\n\n- Alphabetically sorted\n- Directories marked with trailing\n`/`\n\n- Truncates at limit\n\nCLI tools have different performance requirements than servers or GUI applications. The critical metric is **time-to-first-interaction**: how quickly can the user start typing after invoking the command?", "url": "https://wpnews.pro/news/pi-rust-high-performance-ai-coding-agent-cli-written-in-rust", "canonical_source": "https://github.com/Dicklesworthstone/pi_agent_rust", "published_at": "2026-07-07 01:54:19+00:00", "updated_at": "2026-07-07 02:30:28.165703+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "ai-agents", "ai-infrastructure"], "entities": ["Pi Agent", "Mario Zechner", "Will McGugan", "asupersync", "rich_rust", "OpenClaw", "Dicklesworthstone"], "alternates": {"html": "https://wpnews.pro/news/pi-rust-high-performance-ai-coding-agent-cli-written-in-rust", "markdown": "https://wpnews.pro/news/pi-rust-high-performance-ai-coding-agent-cli-written-in-rust.md", "text": "https://wpnews.pro/news/pi-rust-high-performance-ai-coding-agent-cli-written-in-rust.txt", "jsonld": "https://wpnews.pro/news/pi-rust-high-performance-ai-coding-agent-cli-written-in-rust.jsonld"}}