FE-867: Agent extension host — dual-mode pi-harness contract

[kostandinang]

Stacks on FE-864. First Arc-1 frontier and the base of the cook stack -- every Arc-1 frontier lands on this contract.

What?

The dual-mode (elicit/execute) agent-extension-host contract -- src/agent-extension-host.ts, transport-safe metadata only: AgentExtensionMode, the capability/plugin/consumer-witness types, and flattenCapabilityIds.

          agent-extension-host (contract)
          +---------------------------------+
          | CORE (mode-agnostic)            |  <- runtime owned by the pi-harness thread
          +---------------------------------+
            ^ loads plugins per mode
     +------+-------+          +---------------+
     | elicit       |          | execute       |
     | -> interview  |          | -> cook        |
     +--------------+          +---------------+

Dependency-free and names no execute-only concept (slice/epic/plan/worktree/toolchain) -- neutrality is a checkable invariant. Two-consumer proof, no runtime migration:

• cook's execute surface matches createPiActions() ids exactly
• the interview's elicit surface is witnessed against createExplorationTools() + a keyof InterviewerTools coverage check

Why?

The pi harness is reused for spec elicitation and cook execution; one dual-mode host (not two) keeps dispatch, confinement, and tool-scoping shared. This file is the serialization point with the unpublished pi-harness thread that owns the core runtime -- targeting the contract, not pi, keeps the dispatch-seam frontiers decoupled from that rewrite.

Tests

Two-consumer witnesses, no runtime touched: cook's execute surface set-equals Object.keys(createPiActions()); the interview's elicit surface equals Object.keys(createExplorationTools(...)), with the native interviewer tools covered type-level via keyof InterviewerTools under lint --type-check. Mode-neutrality is the module's zero-import invariant -- mechanically checkable, not asserted.

Deferred

Runtime host/dispatch + a pi adapter wait until a real driver lands. Contract-first, zero behavior change.

Co-authored-by: Amp amp@ampcode.com

[kostandinang]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• FE-864: Raise pi-action timeout to 600s #224
• FE-878: Brunch serve — one-shot plan-then-cook capstone #222
• FE-877: Brownfield promotion — commit the cook result onto cook/<runId> #221
• FE-876: Integration oracle — reachability gate + grounding seam #220
• FE-875: App runtime probe — boot, probe, classify #219
• FE-872: Install-failure classification — infra-vs-test split #218
• FE-871: Brunch toolchain detection — detect + plan-emitter wiring #214
• FE-867: Agent extension host — dual-mode pi-harness contract #213 👈 (View in Graphite)
• FE-864: Plan orchestrator brownfield enhancements #212 : 1 other dependent PR (#223 )
• FE-843: Toolchain profile expansion — TS runtimes + live profile selection #198
• FE-841: Embed pi as an in-process SDK to drop the external pi CLI dependency #194 : 1 other dependent PR (#211 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[cursor]

PR Summary

Low Risk
Adds types and test-only witness checks with no production dispatch or interview/cook runtime changes.

Overview
Slice 1 (FE-867) introduces the mode-neutral agent-extension-host contract as the serialization point with the parallel pi-harness runtime work: metadata-only types (AgentExtensionMode, capability/plugin/consumer-witness, flattenCapabilityIds) in src/agent-extension-host.ts, deliberately import-free so neutrality is structural.

Tests (src/agent-extension-host.test.ts) provide the two-consumer proof without touching either runtime: cook execute capability ids must set-equal Object.keys(createPiActions()); interview elicit exploration tools must match createExplorationTools, with keyof InterviewerTools type coverage for native interviewer tools; per-mode plugin registration is asserted.

Plan (memory/PLAN.md) updates agent-extension-host status to in-progress slice 1 landed and notes runtime host/dispatch and pi adapter remain deferred.

No behavior change — contract + tests only; interview still uses the Vercel AI SDK, cook still uses existing pi wiring.

^{Reviewed by Cursor Bugbot for commit bcccd55. Bugbot is set up for automated code reviews on this repo. Configure here.}