01 — Selection surface: config map + insertion points (each flag its own middleware)

[gewenyu99]

🔄 Re-spec — 2026-06-26 (config map + insertion points; each flag its own middleware)

Supersedes the earlier AgentBackend + selectBackend framing. The selection surface becomes a central
config map (the base) + named insertion points (middleware): two registries (ROUTERS, RUNNERS) and a
ROUTES map define per-program defaults ({ router, runner, model }); each decision then flows through an
ordered middleware chain at a named point (resolveRouter, resolvePair) that terminates in the map —
no default-resolver functions. Each existing flag is its own middleware, named for it
(wizard-orchestrator → wizardOrchestrator, wizard-runner → wizardRunner) — nothing renamed, replaced,
or created. Two stacked PRs: the map + empty points first, then the per-flag middleware.

Epic: #520 · Behavior change: none (defaults reproduce today exactly) · Depends on: #688

Summary

Replace the two switch points and the 4 hardcoded model constants with a config map + insertion points.
The base is just the map; control is asserted by middleware, one per flag. New capability: per-program
model selection (today model is hardcoded sonnet). Existing flags keep exact behavior, now as middleware.

Scope — PR #692a (config map + empty insertion points, NO flags)

• runner-plan.ts:
  • RUNNERS: Record<RunnerName, AgentRunner> — leaf engines (anthropic now; pi in 04 — pi.dev runner (pi) #524).
    AgentRunner.run(inputs & { model: string }) — drop-in for today's linear body, consuming
    BootstrapResult.
  • MODELS alias→gateway-id map (sonnet/opus). Replaces the hardcoded model in agent-interface.ts,
    agent-prompt-loader.ts, mcp-prompt-streaming.ts (+ 04 — pi.dev runner (pi) #524 pi).
  • ROUTERS — linearRouter now; orchestratorRouter is a separate stack.
  • ROUTES: Partial<Record<ProgramId, Route>> where Route = { router, runner, model, roles? };
    DEFAULT_ROUTE = { linear, anthropic, sonnet }. This map is the base — no defaultRouter/defaultPair
    functions.
  • Insertion-point plumbing: Mw<D> = (ctx, next) => D, run(chain, ctx, base), two chains
    ROUTER_MIDDLEWARE / PAIR_MIDDLEWARE initialized empty, exposed as resolveRouter / resolvePair
    whose terminal reads ROUTES[program] ?? DEFAULT_ROUTE (pair = { runner, model, ...roles?.[role] }).
• Rewire runner/index.ts to ROUTERS[resolveRouter(ctx)].run(...); routers call resolvePair(ctx, role)
  per leaf. Empty chains → every program resolves to linear / anthropic / sonnet → byte-identical to today.
  Extract today's linear body into RUNNERS.anthropic verbatim.
• Log the resolved router + runner + model every run.

Scope — PR #692b (per-flag middleware for the existing flags — adds no flags)

• Add one middleware per existing flag, named for the flag:
  • wizardOrchestrator (ROUTER_MIDDLEWARE): wizard-orchestrator === 'true' → assert orchestrator,
    else next().
  • wizardRunner (PAIR_MIDDLEWARE): defers-then-modifies — ALWAYS calls next() first to get the
    base pair, then overlays only the runner field iff wizard-runner ∈ {anthropic, pi}. The model
    always comes from the config map, never the flag. (Note: this is not the assert-or-defer shape of
    wizardOrchestrator — it never short-circuits; pattern: const p = next(); const r = flags['wizard-runner']; return (r==='anthropic'||r==='pi') ? {...p, runner:r} : p.)
• Construct ResolveCtx (flags + env) once after bootstrap; hand resolvePair into the RouterContext so
  every leaf (linear's one, orchestrator's many) flows through the same point.
• No PostHog flag changes. wizard-orchestrator / wizard-runner keep their current definitions.
• (No standalone guard middleware — dropped.)

Acceptance criteria

• pnpm build && pnpm test && pnpm fix pass; existing e2e unchanged; with the flag middleware and no flag
  set, every program resolves to linear / anthropic / sonnet (behavior identical).
• Chains unit-tested: empty chains → map defaults; wizardOrchestrator / wizardRunner each in
  isolation (assert-vs-defer).
• wizard-orchestrator / wizard-runner behave exactly as before — asserted by test.
• Resolved router + runner + model log line present.

Files

• src/lib/agent/runner/runner-plan.ts (registries, MODELS, ROUTES/DEFAULT_ROUTE, run/chains,
  resolveRouter/resolvePair, linearRouter, the per-flag middleware), runner/index.ts,
  runner/backends/anthropic.ts, agent-interface.ts, agent-prompt-loader.ts, mcp-prompt-streaming.ts.
  (src/lib/constants.ts flag keys unchanged.)

Notes

The orchestrator is not a runner — it's a Router (separate stack on this core). #692a is the config map

• empty points (the "clean base"); #692b adds one named middleware per existing flag. Future controls (cost
  caps, per-org policy, A/B, a model-override flag) are each their own new middleware at these same points — no
  rewrite.

---

Landed as (2026-06-27)

Implemented across #692 (pi/01-seam-flag) and #693 (pi/02-pi-backend), not a separate #692a/#692b:

• feat(runner): central runner plan + anthropic runner seam (#521) #692 — runner-plan.ts (config map + resolvePair over an empty PAIR_MIDDLEWARE chain, RUNNERS/MODELS/ROUTES), the anthropic runner seam, the 4 model literals → DEFAULT_AGENT_MODEL/MODELS, WIZARD_RUNNER_FLAG_KEY. Behavior identical.
• feat(runner): pi.dev runner — gateway provider, model from pair, in RUNNERS (#524) #693 — adds the wizardRunner pair-middleware (reads the existing wizard-runner flag) alongside the pi runner it selects.
• The router side (resolveRouter + wizardOrchestrator middleware) was not added; the existing isOrchestratorEnabled fork in runner/index.ts is untouched. That stays the future additive step.

[gewenyu99]

Delivered — the switchboard config map + per-flag middleware landed on main (src/lib/agent/runner/switchboard/, via #780).