02 — Shared runner contract + adapters (gateway, MCP, prompt, tools, stream→TUI)

[gewenyu99]

🔄 Re-spec — 2026-06-26 (consumes the router/pairs core from #521)

Land the substrate in runner/shared/ (beside #688's bootstrap.ts/types.ts/errors.ts). It
consumes BootstrapResult/ProgramRun and the resolved pair's model from #521's resolver — it does
not re-derive run context or pick a model itself. Stays runner-neutral so the pi runner (and any future
runner) needs no rework.

Epic: #520 · Behavior change: none (defaults preserved) · Depends on: #521

Summary

Build the runner-neutral surface the pi runner consumes, so it doesn't re-derive what anthropic already
has. No agent SDK here — just shared scaffolding any runner reuses.

Scope

1. Run context — working dir; gateway transport (baseURL from getLlmGatewayUrlFromHost, bearer =
   posthog API key, Bedrock-fallback + metadata/flag headers — reuse buildAgentEnv/buildGatewayHeaders
   semantics as a header map). Model is not chosen here — the runner receives model: string resolved
   from the pair (MODELS[pair.model], see 01 — Selection surface: config map + insertion points (each flag its own middleware) #521).
2. System prompt — wizard commandments (+ skills) as the system-prompt string (Pi consumes it via
   DefaultResourceLoader({ systemPromptOverride })).
3. MCP wiring — posthog-wizard remote MCP (bearer) + wizard-tools, expressed so a runner can mount them.
4. Stream→TUI bridge — backend stream events (assistant text, tool calls) → existing UI updates
   ([STATUS]/[DASHBOARD_URL]/[NOTEBOOK_URL], collectedText); reuse handleSDKMessage's marker logic.
5. Error mapping — transport/loop errors → AgentErrorType (ABORT/RATE_LIMIT/API_ERROR…).

Acceptance criteria

• Header builder unit-tested (bedrock + property + flag prefixes), matches buildAgentEnv.
• Stream→TUI + error-mapping helpers unit-tested.
• No agent SDK dependency added in this PR.

Files

• src/lib/agent/runner/shared/ (gateway, mcp, prompt, stream-bridge, errors)

Notes

Reuses the bits salvaged from the scrapped harness work (the seam, run-bridge, conclude,
buildGatewayHeaders). The from-scratch Messages client and hand-rolled loop are not carried over — the
Pi SDK owns the loop.

[gewenyu99]

Delivered — the shared runner contract landed on main (src/lib/agent/runner/shared/, via #778).