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

[kostandinang]

Stack Context

Stacks on FE-864 (#212). 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-881: Cook agent loads the target repo's sandbox-scoped skills #227
• FE-883: Orchestrator operational improvements (serve reliability + Opus 4.8) #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: Orchestrator improvements umbrella — brownfield feature delivery from spec #212 : 1 other dependent PR (#223 )
• FE-843: Expand cook toolchain profiles, selected at plan time #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
Contract and test-only changes with zero runtime behavior change; main risk is witness tests breaking when cook actions or interviewer tools are added without updating the witness.

Overview
Slice 1 (FE-867) adds the dual-mode agent-extension-host contract as a serialization point with the parallel pi-harness work: metadata-only types (AgentExtensionMode, capability/plugin/consumer-witness) plus flattenCapabilityIds, with no imports so the core stays mode-neutral.

Tests enforce that invariant and a two-consumer witness: 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. No interview or cook runtime is migrated.

memory/PLAN.md updates the agent-extension-host frontier to in-progress slice 1 landed and tweaks Linear/stack wording; runtime host/dispatch remains deferred.

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