feat(egress-gate): add attested Pi prompt admission

[johnnygreco]

Summary

Add an attested rendered-prompt admission path for managed Pi sandboxes while preserving the existing generic HTTP-only Egress Gate mode.

This depends on the reviewed fork PRs:

• Pi: feat(coding-agent): add user message append hook johnnygreco/pi#1
• OpenShell: feat(supervisor): add managed Pi admission bridge johnnygreco/OpenShell#1

Changes

• add a strict versioned Pi admission adapter and OpenAI Chat Completions request adapter
• keep Pi runtime-agnostic: the fork adds only the general-purpose pre-append hook, while this project owns the OpenShell-specific extension loaded through Pi's standard --extension option
• issue short-lived, one-shot Ed25519 receipts bound to the rendered prompt, sandbox, policy, harness version, middleware, and provider target
• verify and strip receipts at egress, then rerun Gates against the actual HTTP request
• add the OpenShell agent-conversation protobuf surface and generated Python bindings
• expose managed receipt enforcement through the service and CLI while retaining explicit unmanaged HTTP-only mode
• provide one real OpenShell policy, Pi Chat Completions model configuration, extension, and end-to-end deny/redact workflow
• provide a small demo.sh helper whose exact commands can always be inspected with --print, with no mock session or provider
• test denial-before-history, redaction, replay rejection, unsupported continuations, malformed inputs, the 32 KiB admission boundary, the deployable policy, and command-printing behavior

Security boundary

The receipt attests the latest rendered prompt. It does not attest the complete conversation/provider payload or authenticate which same-sandbox process called the loopback bridge. Those limits are explicit; unsupported automatic continuations fail closed, and Egress Gate evaluates the actual outgoing HTTP request before forwarding.

Testing

• make check — 340 passed; formatting, lint, type/import checks, security checks, and dependency audit passed
• models.json loaded through the Pi fork and exposed openai-chat-completions/gpt-4o-mini
• independent security, integration, CI, and maintainability review rounds — clean

Related issue

None. This is research integration work coordinated across the linked forks.

[johnnygreco]

Phase 0 Review Record

Frozen range: c7b757d..cc8497e

Scope reviewed: final admission names/contracts, registry-derived bindings, removal of the superseded receipt path, immutable fork/proto pin, runtime/example/docs updates, and provider fixture provenance.

Independent review:

• Correctness/security/interoperability reviewer found one blocker: JavaScript user-envelope key order did not satisfy Python canonical JSON. No other blocker/high/medium findings.
• Maintainability/tests/docs/integration reviewer independently found the same blocker. No other blocker/high/medium findings.
• Minimal fix: cc8497e reorders the two user-envelope object literals and adds one exact-byte assertion covering string and text-block content.
• Both reviewers re-reviewed 8910d79..cc8497e and returned clean.

Validation:

• make check: 368 tests passed; format, lint, typing, imports, and audit green.
• make check-py311: 368 tests passed; all checks green.
• Focused elevated gRPC integration: 9 passed.
• Runtime-extension JavaScript test passed, including the exact canonical request bytes.
• Acceptance grep and git diff --check passed.
• No protobuf or generated-binding changes.

POC scope remained constrained: 22 files in the main Phase 0 commit with net one-line deletion, followed by the focused two-file interoperability fix. No shims, speculative infrastructure, or unrelated cleanup were added.

[johnnygreco]

Phase 1 Review Record

Frozen range: cc8497e..6ddc86e

Scope reviewed: exact seven-origin runtime dispatch, the shared text adapter, distinct assistant/bash adapters, immutable-field validation, Describe bindings, cross-language interoperability, and focused tests.

Independent review found one concrete high-severity interoperability defect: Python byte equality rejected valid JavaScript number spellings in arbitrary assistant tool arguments. The minimal fix in 6ddc86e removes only the assistant envelope's re-encoding byte check while retaining bounded JSON parsing, duplicate-key rejection, strict schema validation, extra-field rejection, and immutable tool-call comparison. A raw JavaScript 1e-7 regression was added. Re-review returned clean.

Scope audit:

• Production is limited to the seven required origin mappings and three required envelope families.
• No Phase 2 context binding, provider redesign, protobuf, compatibility, docs expansion, or new infrastructure.
• Tests are table-driven for shared behavior and focused for assistant/bash differences.

Validation:

• make check: 377 tests passed; format, lint, typing, imports, and audit green.
• make check-py311: 377 tests passed; all checks green.
• Focused runtime-extension JavaScript tests passed.
• Accepted-fix admission suite: 38 passed.
• Source-path TypeScript validation reported no runtime-extension errors; the global command remains non-green only for unrelated Pi source errors and missing declarations. No generated output or validation tooling was committed.

[johnnygreco]

Phase 2 Review Record

Frozen range: 6ddc86e..3fedae0

Scope reviewed: stateless v2 whole-context hash/count binding, ordered user/tool entry derivation, Chat Completions and Responses extraction, send-time replacements, pre/post gate checks, append-time empty attestations, runtime handle lookup, and shared JS/Python vectors.

Independent findings and disposition:

• One medium defect was fixed in 01823dd: Chat rejected valid multi-text-block users. Chat, Responses, and JavaScript now join strict text blocks with \n, pinned by the same compact shared vector. Re-review clean.
• One transport-boundary availability limitation was reproduced: Pi may rewrite tool IDs or synthesize missing tool results after provider-context admission during cross-transport history replay. Eliminating it exactly requires a new provider-preparation contract across Pi AI transports, auth/header ordering, and coding-agent; that architectural expansion was rejected for this POC. 3fedae0 documents the supported workaround: start a fresh session when switching transports and complete tool-call/result sequences. The behavior fails closed with hash/count mismatch before credential delivery; reviewers confirmed no security bypass and accepted the limitation for the supported scope.
• Security/correctness review otherwise returned clean. Scope/minimality and cross-language re-reviews returned clean at the final head.

Scope audit:

• Production/runtime: +380/-139 in the main Phase 2 commit; v1 claims/candidate/token logic replaced in place.
• One compact shared vector; existing test paths converted rather than duplicated.
• No ledger/state, Phase 2b, assistant/system hashing, caller identity, provider redesign, protobuf change, compatibility shim, or canonicalization framework.

Validation:

• make check: 376 passed; format, Ruff, ty, imports, and audit green.
• make check-py311: 376 passed; all checks green.
• Focused admission tests after fixes: 36 passed.
• Runtime JavaScript tests/shared vector: 8 passed.
• Pi focused admission tests: 25 passed; Pi worktree unchanged.
• Pi npm run check remains non-green only for existing generated model-catalog drift outside this phase.
• git diff --check: passed.

[johnnygreco]

Phase 3 Review Record

Frozen range: 3fedae0..b03c8ea

Scope reviewed: real self-verifying demo cases, printable commands, content-safe reason-code logging, workload readiness removal, base64 runtime bodies, architecture/example docs, and generated mirror workflow.

Independent findings and fixes:

• The best-effort tool check could false-pass by finding replacement text outside the toolResult record. b03c8ea scopes expected/forbidden checks to actual tool-result JSONL records and preserves the model-dependent SKIP. Re-review clean.
• Two example README passages still named only user/tool appends. b03c8ea now accurately describes every supported history origin and the generic Pi append boundary. Re-review clean.
• Demo/privacy, docs/minimality, and cross-repo base64 reviewers found no other blocker/high/medium issue at final head.

Scope audit:

• Main Phase 3 commit: 15 handwritten files; only 46 net production/runtime lines, the real verifier, focused tests, and one 76-line canonical architecture page.
• No mock fallback, caller-token work, deployment automation, logging framework, legacy number-array compatibility, or broad docs cleanup.
• The ignored generated documentation mirror was produced only through the documented staging workflow and byte-matched the canonical page.

Validation:

• make check: 377 passed.
• make check-py311: 377 passed.
• Documentation renderer and strict site build passed; built admission page served locally with HTTP 200 and expected v2 content.
• Runtime JS/base64 tests and focused command/logging/service tests passed.
• bash -n and git diff --check passed.
• Real ./demo.sh verify was not faked. This checkout lacks the prepared ignored OpenShell runtime/CLI (projects/egress-gate/.workspaces/pi-attested-admission/OpenShell/scripts/bin/openshell), .env, and JSON log, so real E2E remains externally blocked until the documented prepare/serve workflow is run with provider credentials.

[github-actions]

Documentation preview

View the deployed preview

Built from cc696bc.

[johnnygreco]

Phase 4 Review Record

Reviewed head: 9b6b53850daa7b17e075b106289c4c986f03e06f

Scope remained POC-bounded: the launcher consumes and closes the inherited capability FD, the bridge adapter attaches one bearer header, the existing demo adds an unauthenticated negative control, and focused documentation/tests describe the capability and residual same-user memory-reading risk. Pi and provider behavior are untouched.

The final documentation follow-up replaces the stale middleware-field opt-out with the actual supervisor startup flag and updates the canonical architecture page. Its generated mirror was staged and byte-checked through the documented workflow.

Independent security and scope reviews: clean; no remaining blocker/high/medium findings.

Validation:

• make check: 377 passed
• make check-py311: 377 passed
• focused example tests: 10/10
• runtime JS test and focused TypeScript compile: pass
• shell syntax, printed verify workflow, documentation staging/renderer/build/serve, and diff checks: pass
• exact 43-byte token succeeds; missing/malformed delivery fails clearly before Pi starts
• live demo.sh verify remains externally blocked by absent provider/gateway configuration; no mock fallback was introduced

[johnnygreco]

Final Review Record

Reviewed head: 0bf33ca
Upstream base merged: 743839dae47621c13a3bc339bad2a2c8d0167591

Independent Research, documentation, security, and holistic cross-repository reviews are clean: no remaining blocker, high, or medium findings. The final documentation accurately states the implemented POC boundaries, including assistant-thinking coverage, immutable assistant tool calls, transport-history fail-closed limits, capability residual risk, and the checked-in endpoint/catalog scope of verify.

Validation:

• make check: 377/377
• make check-py311: 377/377
• example command tests: 10/10
• documentation renderer: 11/11
• strict docs build and served artifact: pass
• final GitHub checks for Python 3.11/3.14, docs, license, Dev Notes, and long-horizon evals: pass

The real ./demo.sh verify was not replaced with a mock. It remains externally blocked on this host by absent prepared ignored workspaces/runtime and unset PI_MODEL_API_KEY, EGRESS_GATE_HOST_IP, and PI_MODELS_PATH. Exact commands are available through ./demo.sh --print verify; a configured environment must run ./demo.sh reset && ./demo.sh verify before promotion beyond draft.

The PR remains draft; no merge/readiness change was made.