@cairnvibe/sdk 0.2.13 → 0.4.0

package/src/server.ts

@@ -5,19 +5,44 @@
 
 import Anthropic from "@anthropic-ai/sdk";
 import Groq from "groq-sdk";
+import { z } from "zod";
 import {
+  classifyUiPattern,
   CopilotRequestSchema,
+  CriticVerdictSchema,
+  deriveStructureSignals,
+  isTerminalVerb,
+  PlannerOutputSchema,
+  renderPlaybookHint,
+  slugifySkillId,
+  TaskSchema,
+  UI_PATTERNS,
   VERBS,
   VerbResponseSchema,
+  type CriticVerdict,
   type HistoryTurn,
   type LiveElement,
   type Manifest,
+  type Plan,
+  type PlannerOutput,
+  type Skill,
+  type SkillSummary,
+  type Task,
+  type UiPatternId,
   type VerbResponse,
   type WebMcpTool,
 } from "@cairnvibe/core";
+import { looksMultiStep, MAX_HISTORY_TURNS, summarizeVerbForHistory } from "./agent-loop";
+import { formatArchivedFacts, formatRememberedFacts, seedHistoryFromMemory, type MemoryStore } from "./memory-sqlite";
+export { KeyRotator } from "./key-rotator";
 import { KeyRotator } from "./key-rotator";
+import type { SkillStore } from "./skill-store";
 
 const VERB_TOOL_NAME = "respond_with_verb";
+const PLAN_TOOL_NAME = "create_plan";
+const PLAN_TOOL_DESCRIPTION = "Submit an ordered task plan for achieving the user's real end goal.";
+const CRITIC_TOOL_NAME = "submit_verdict";
+const CRITIC_TOOL_DESCRIPTION = "Submit your verdict on whether the current task is actually done, based on the real resulting state.";
 
 /**
  * What the agent is allowed to do, independent of which specific "do"
@@ -43,13 +68,69 @@ export interface CreateCopilotHandlerOptions {
   /** Single API key. For groq, prefer `apiKeys` to round-robin; falls back to GROQ_API_KEYS env. */
   apiKey?: string;
   apiKeys?: string[];
+  /**
+   * A pre-built rotator to share across multiple LLM roles (verb, plan,
+   * critic) instead of each one building its own from `apiKeys`/`apiKey`/
+   * env. Real, live-found gap this closes: createVerbLLM/createPlanLLM/
+   * createCriticLLM each called createToolLLM independently, and each one
+   * built a BRAND NEW KeyRotator from the same GROQ_API_KEYS list — so a
+   * key one of them confirmed dead via a real 401 (KeyRotator.markDead)
+   * stayed invisible to the other two, which went on rediscovering the
+   * exact same dead key from scratch on every one of their own calls,
+   * wasting real round trips and, worse, stacking up wasted attempts
+   * against the SAME small number of retries each call is bounded to.
+   * Takes precedence over `apiKeys`/`apiKey`/env when provided. See
+   * groq-llm.ts in examples/demo-app for the intended usage: build one
+   * KeyRotator at module scope, pass it to all three createXLLM calls.
+   */
+  keyRotator?: KeyRotator;
   model?: string;
   /** Action ids this deployment actually supports. "do" is refused for anything else. */
   registeredActions?: string[];
+  /**
+   * Phase 4, layer 5 — real, human-written descriptions for `registeredActions`
+   * ids, e.g. `{ archiveInvoice: "Archives the invoice; cannot be undone." }`.
+   * Optional and purely additive: an id with no entry here still works
+   * exactly as before (rendered bare, no description) — this was the
+   * weakest-typed of Cairn's three action-invocation mechanisms (a
+   * registered action id carried literally zero server-visible metadata,
+   * unlike a WebMCP tool's own description or an element's `does` text);
+   * this closes that gap without changing what the model must echo back
+   * in "action" (still the bare id — see renderRegisteredActions).
+   */
+  actionDescriptions?: Record<string, string>;
   /** What the agent is allowed to do at all. Defaults to "act". See `CapabilityTier`. */
   capability?: CapabilityTier;
   /** Display name / identity for the agent, woven into its system prompt and shown in the widget. Defaults to "Cairn". */
   persona?: string;
+  /**
+   * Phase 5 step 4 — real cross-session memory for the typed/HTTP
+   * transport (packages/sdk/src/memory-sqlite.ts, or any store
+   * implementing the same interface). Optional — omitting it keeps
+   * every request exactly as memory-less as before this existed.
+   * Scoped by whatever `scopeId` string the request itself carries
+   * (`CopilotRequestSchema.scopeId`) — this SDK invents no identity of
+   * its own. Unlike the realtime relay (one persistent connection
+   * remembers a scopeId once), this transport is stateless per
+   * request: `resolveVerb`'s own callers seed from memory only when the
+   * REQUEST's own `history` arrives empty (a genuinely fresh session —
+   * see `createCopilotHandlerWithLLM`), never on every request, so a
+   * session already accumulating its own history client-side isn't
+   * re-seeded on top of itself.
+   */
+  memory?: MemoryStore;
+  /**
+   * Architecture Pillar 3 (Skill half) — real, per-deployment Skill
+   * storage (packages/sdk/src/skill-store.ts). A DIFFERENT scope axis
+   * than `memory` above — see skill-store.ts's own doc comment. Optional;
+   * omitting it keeps every request exactly as it was before this
+   * existed. Consumed by `createPlanHandler` (retrieval — a matching
+   * Skill's full instructions get surfaced to the Planner) and
+   * `createSkillSaveHandler` (the Formulator's own save side).
+   */
+  skills?: SkillStore;
+  /** The deployment-wide scope Skills are stored/looked up under when `skills` is configured. Defaults to "default" when omitted. */
+  skillsScopeId?: string;
 }
 
 export interface CopilotHandlerResult {
@@ -81,25 +162,71 @@ export function createCopilotHandler(manifest: Manifest, options: CreateCopilotH
   const registeredActions = options.registeredActions ?? [];
   const capability = options.capability ?? "act";
   const llm = createVerbLLM(options);
-  return createCopilotHandlerWithLLM(manifest, llm, { registeredActions, capability, persona: options.persona });
+  return createCopilotHandlerWithLLM(manifest, llm, {
+    registeredActions,
+    capability,
+    persona: options.persona,
+    actionDescriptions: options.actionDescriptions,
+    memory: options.memory,
+  });
 }
 
 /** Same as `createCopilotHandler`, but with the LLM injected — used by tests to fake it. */
 export function createCopilotHandlerWithLLM(
   manifest: Manifest,
   llm: VerbLLM,
-  options: { registeredActions?: string[]; capability?: CapabilityTier; persona?: string } = {},
+  options: { registeredActions?: string[]; capability?: CapabilityTier; persona?: string; actionDescriptions?: Record<string, string>; memory?: MemoryStore } = {},
 ): CopilotHandler {
   const registeredActions = options.registeredActions ?? [];
   const capability = options.capability ?? "act";
-  const systemPrompt = buildSystemPrompt(manifest, registeredActions, options.persona);
+  const actionDescriptions = options.actionDescriptions ?? {};
+  const systemPrompt = buildSystemPrompt(manifest, registeredActions, options.persona, actionDescriptions);
 
   return async function handleCopilotRequest(body: unknown): Promise<CopilotHandlerResult> {
     const parsedRequest = CopilotRequestSchema.safeParse(body);
     if (!parsedRequest.success) {
       return { status: 400, body: { error: "invalid request body" } };
     }
-    const verb = await resolveVerb(llm, systemPrompt, manifest, registeredActions, capability, parsedRequest.data);
+    const input = parsedRequest.data;
+
+    // Phase 5 step 4 — real cross-session memory for the typed/HTTP
+    // transport. Unlike the realtime relay (one persistent connection,
+    // seeded once), this is stateless per request — seeded only when
+    // the CLIENT's own history arrives empty, the real signal for "this
+    // is a genuinely fresh session" (a session already accumulating its
+    // own history client-side is never re-seeded on top of itself; see
+    // CreateCopilotHandlerOptions.memory's own doc comment).
+    let effectiveHistory = input.history ?? [];
+    if (options.memory && input.scopeId && effectiveHistory.length === 0) {
+      const priorTurns = options.memory.recentTurns(input.scopeId);
+      effectiveHistory = seedHistoryFromMemory([], priorTurns, MAX_HISTORY_TURNS);
+      const factsSummary = formatRememberedFacts(options.memory.recallFacts(input.scopeId));
+      if (factsSummary) effectiveHistory = [{ role: "assistant", text: factsSummary }, ...effectiveHistory];
+    }
+
+    // Architecture Pillar 5 — the Archive tier, checked on EVERY request
+    // (not just a fresh session — unlike Core facts above, an archived
+    // fact is never always-injected, only surfaced when THIS question
+    // actually relates to it, which can happen at any point in an
+    // ongoing conversation, not only at its start).
+    if (options.memory && input.scopeId) {
+      const archivedMatch = options.memory.recallArchivedFacts(input.scopeId, input.question);
+      const archivedSummary = formatArchivedFacts(archivedMatch);
+      if (archivedSummary) effectiveHistory = [...effectiveHistory, { role: "assistant", text: archivedSummary }];
+    }
+
+    const verb = await resolveVerb(llm, systemPrompt, manifest, registeredActions, capability, { ...input, history: effectiveHistory });
+
+    // Recorded only for a TERMINAL verb — matching the realtime relay's
+    // own discipline exactly: a continuing step (click/fill/read/
+    // call_tool/batch, or now a navigate marked continueAfter — see
+    // isTerminalVerb's own doc comment) is an internal implementation
+    // detail of one logical exchange, never its own remembered "turn".
+    if (options.memory && input.scopeId && isTerminalVerb(verb)) {
+      options.memory.recordTurn(input.scopeId, "user", input.question);
+      options.memory.recordTurn(input.scopeId, "assistant", summarizeVerbForHistory(verb));
+    }
+
     return { status: 200, body: verb };
   };
 }
@@ -127,13 +254,25 @@ export async function resolveVerb(
 ): Promise<VerbResponse> {
   let candidate: unknown;
   try {
+    // Architecture Pillar 2 — classified from the SAME liveElements this
+    // request already carries for element resolution, no new client
+    // wiring or payload field needed. Real, checkable evidence (which
+    // labels/roles matched), never a bare guess — see ui-patterns.ts's own
+    // doc comment. Absent entirely when nothing matched (a page that's
+    // none of the known patterns), rather than forcing a hint that isn't real.
+    const patternMatches = input.liveElements?.length ? classifyUiPattern(deriveStructureSignals(input.liveElements)) : [];
     // Element-level detail for the current page only, attached here rather
     // than baked into the (static, cached) system prompt — see
     // buildSystemPrompt's comment for why. This payload is already
     // per-request and was never cached, so there's nothing to lose by
     // making it bigger; the system prompt is what has to stay small and
     // route-independent.
-    const userMessage = JSON.stringify({ ...input, currentPageElements: buildPageElements(manifest, input.route) });
+    const userMessage = JSON.stringify({
+      ...input,
+      currentPageElements: buildPageElements(manifest, input.route),
+      currentPageDataShapes: buildPageDataShapes(manifest, input.route),
+      ...(patternMatches.length ? { suggestedApproach: renderPlaybookHint(patternMatches[0].pattern) } : {}),
+    });
     candidate = await llm.respond(systemPrompt, userMessage);
   } catch (err) {
     console.error("[cairn] copilot LLM call failed:", err);
@@ -189,11 +328,22 @@ export async function resolveVerb(
   const isKnownTarget = (target: string) => pageElements.some((e) => e.id === target) || (input.liveElements ?? []).some((e) => e.id === target);
   const isKnownTool = (name: string) => (input.webMcpTools ?? []).some((t) => t.name === name);
 
-  if (parsedVerb.data.verb === "click" || parsedVerb.data.verb === "fill" || parsedVerb.data.verb === "read") {
+  if (parsedVerb.data.verb === "click" || parsedVerb.data.verb === "fill" || parsedVerb.data.verb === "read" || parsedVerb.data.verb === "select" || parsedVerb.data.verb === "scroll" || parsedVerb.data.verb === "wait_for") {
     if (!isKnownTarget(parsedVerb.data.target)) {
       return { verb: "explain", text: "I don't see that on this page right now." };
     }
   }
+  if (parsedVerb.data.verb === "drag") {
+    if (!isKnownTarget(parsedVerb.data.target) || !isKnownTarget(parsedVerb.data.to)) {
+      return { verb: "explain", text: "I don't see everything I'd need for that on this page right now." };
+    }
+  }
+  // key's target is optional (omitted means "whatever's currently
+  // focused") — only check it against real state when the model actually
+  // named one, same "never invented" invariant as every other target.
+  if (parsedVerb.data.verb === "key" && parsedVerb.data.target && !isKnownTarget(parsedVerb.data.target)) {
+    return { verb: "explain", text: "I don't see that on this page right now." };
+  }
   if (parsedVerb.data.verb === "call_tool") {
     if (!isKnownTool(parsedVerb.data.name)) {
       return { verb: "explain", text: "That isn't something I can do here." };
@@ -204,9 +354,12 @@ export async function resolveVerb(
     // partially execute a batch whose later step names something the
     // model invented; refuse the whole turn instead of guessing which
     // steps were "safe enough" to run.
-    const allKnown = parsedVerb.data.actions.every((action) =>
-      action.verb === "call_tool" ? isKnownTool(action.name) : isKnownTarget(action.target),
-    );
+    const allKnown = parsedVerb.data.actions.every((action) => {
+      if (action.verb === "call_tool") return isKnownTool(action.name);
+      if (action.verb === "drag") return isKnownTarget(action.target) && isKnownTarget(action.to);
+      if (action.verb === "key") return !action.target || isKnownTarget(action.target);
+      return isKnownTarget(action.target);
+    });
     if (!allKnown) {
       return { verb: "explain", text: "I don't see everything I'd need for that on this page right now." };
     }
@@ -230,28 +383,379 @@ export async function resolveVerb(
   return parsedVerb.data;
 }
 
-/** Builds the provider-appropriate VerbLLM from the same options createCopilotHandler accepts — reused by the realtime relay. */
-export function createVerbLLM(options: CreateCopilotHandlerOptions = {}): VerbLLM {
-  const registeredActions = options.registeredActions ?? [];
-  const toolSchema = buildVerbToolSchema(registeredActions);
+/**
+ * Phase 3, step 2 (see DEVELOPMENT.md/the plan file) — the Planner half
+ * of the Planner/Executor/Critic/Talker redesign. Decomposes a real end
+ * goal into an ordered task list BEFORE any execution happens, mirroring
+ * resolveVerb's own resilience discipline: never throws to the caller,
+ * degrades to a real, usable single-task fallback plan on any failure
+ * (a bad LLM response, a schema mismatch, a network error) rather than
+ * blocking the turn on a Planner hiccup. `version`/each task's `status`
+ * are harness-owned, not asked of the model (PlannerOutputSchema's own
+ * doc comment) — assembled here around the model's raw output.
+ *
+ * Deliberately does NOT yet change what the loop actually does with the
+ * result — step 2's own scope is observability only (see the doc comment
+ * on this function's call site in realtime-server.ts). The Critic (step
+ * 3) is what makes a Plan's tasks/doneContracts actually drive behavior.
+ */
+export async function resolvePlan(llm: VerbLLM, goal: string, version = 1, manifest?: Manifest, actionsText?: string, skills?: { summariesText?: string; suggestedInstructions?: string }): Promise<Plan> {
+  let candidate: unknown;
+  try {
+    // manifest/actionsText are appended, optional, and default to absent —
+    // additive on purpose (see this function's own exported-API note
+    // above): an existing 2- or 3-arg call site (own or a published
+    // consumer's) keeps building the exact same {goal} userMessage it
+    // always has. Real page/data grounding (Phase 4 step 3) only applies
+    // when a caller has a manifest to pass — see buildPlannerPageDirectory's
+    // own doc comment for the token-budget discipline behind what it
+    // includes. actionsText (Phase 4 step 4) is the SAME rendering
+    // buildSystemPrompt/buildVerbToolSchema use for registered actions —
+    // pass renderRegisteredActions(...)'s own output, not a hand-rolled
+    // string, so the Planner and Executor never describe the same
+    // capability two different ways. skills (Architecture Pillar 3) is
+    // the same additive shape: `summariesText` (renderSkillSummaries'
+    // output — every this-deployment Skill's name+description, cheap to
+    // always include) and `suggestedInstructions` (matchSkillByGoal's own
+    // match, full instructions, only when one genuinely matched this
+    // goal) — both optional, both absent by default for a caller with no
+    // SkillStore configured.
+    const payload: Record<string, unknown> = { goal };
+    if (manifest) payload.pages = buildPlannerPageDirectory(manifest);
+    if (actionsText) payload.actions = actionsText;
+    if (skills?.summariesText) payload.skills = skills.summariesText;
+    if (skills?.suggestedInstructions) payload.suggestedSkill = skills.suggestedInstructions;
+    const userMessage = JSON.stringify(payload);
+    candidate = await llm.respond(buildPlannerSystemPrompt(), userMessage);
+  } catch (err) {
+    console.error("[cairn] planner LLM call failed:", err);
+    return fallbackPlan(goal, version);
+  }
+
+  const parsed = PlannerOutputSchema.safeParse(candidate);
+  if (!parsed.success) return fallbackPlan(goal, version);
+  return assemblePlan(parsed.data, version);
+}
+
+function assemblePlan(output: PlannerOutput, version: number): Plan {
+  return {
+    version,
+    goal: output.goal,
+    facts: output.facts,
+    tasks: output.tasks.map((task, i) => ({ ...task, status: i === 0 ? "in_progress" : "pending" })),
+  };
+}
+
+/** The real, single-task plan used when the Planner call itself fails —
+ * "do the whole goal as one task" is always a valid (if unstructured)
+ * plan, so a Planner hiccup degrades the redesign back to today's
+ * behavior instead of blocking the turn. Exported so every caller that
+ * needs "a plan, even a trivial one, right now" (e.g. a Critic call that
+ * fires before a real Planner result has come back) builds the exact
+ * same shape instead of hand-rolling a duplicate literal — realtime-
+ * server.ts's own finalizeTurn and index.tsx's runTypedAgentLoop both do
+ * this, for the same reason. */
+export function fallbackPlan(goal: string, version: number): Plan {
+  return {
+    version,
+    goal,
+    facts: [],
+    tasks: [{ id: "t1", description: goal, doneContract: "The stated goal has been achieved.", status: "in_progress" }],
+  };
+}
+
+/**
+ * Phase 3, step 3 — the Critic. A genuinely SEPARATE pass over the
+ * step's real observation, decoupled from the Executor/model's own
+ * self-report — this is the direct fix for the diagnosed bug (a batch
+ * of 2 clicks succeeded, and the model kept looping 4 more iterations
+ * before giving up, never recognizing its own success). Mirrors
+ * packages/evals/src/judge.ts's own judgeScenario shape on purpose (a
+ * separate model looking at real state, forced tool call, structured
+ * verdict) — same real precedent already proven and tested in this repo,
+ * not a new pattern invented for this. Same resilience discipline as
+ * resolveVerb/resolvePlan: never throws, degrades to a real "continue"
+ * verdict (harmless — the loop just behaves as if the Critic weren't
+ * there for this one step) on any failure.
+ */
+export async function resolveCritic(llm: VerbLLM, task: Task, goal: string, verb: VerbResponse, observation: string | null | undefined): Promise<CriticVerdict> {
+  let candidate: unknown;
+  try {
+    candidate = await llm.respond(
+      buildCriticSystemPrompt(),
+      JSON.stringify({
+        goal,
+        taskDescription: task.description,
+        doneContract: task.doneContract,
+        action: summarizeVerbForHistory(verb),
+        observation: observation ?? "no result",
+      }),
+    );
+  } catch (err) {
+    console.error("[cairn] critic LLM call failed:", err);
+    return { verdict: "continue", reasoning: "Critic call failed — defaulting to continue rather than blocking the turn." };
+  }
+
+  const parsed = CriticVerdictSchema.safeParse(candidate);
+  if (!parsed.success) return { verdict: "continue", reasoning: "Critic response failed validation — defaulting to continue rather than blocking the turn." };
+  return parsed.data;
+}
+
+/** Same real rotation/model-selection logic as createVerbLLM/createPlanLLM,
+ * configured for the Critic's own tool instead — see resolveCritic. */
+export function createCriticLLM(options: CreateCopilotHandlerOptions = {}): VerbLLM {
+  return createToolLLM(options, buildCriticToolSchema(), CRITIC_TOOL_NAME, CRITIC_TOOL_DESCRIPTION);
+}
+
+/** Builds a provider-appropriate forced-single-tool-call LLM for ANY tool
+ * shape (verb resolution, planning, ...) — the real rotation/model-
+ * selection logic every such caller needs, factored out once so
+ * createVerbLLM/createPlanLLM stay thin, tool-specific wrappers around it. */
+function createToolLLM(options: CreateCopilotHandlerOptions, toolSchema: Record<string, unknown>, toolName: string, toolDescription: string): VerbLLM {
   const provider = options.provider ?? "anthropic";
 
   if (provider === "groq") {
-    const rotator = options.apiKeys
-      ? new KeyRotator(options.apiKeys)
-      : options.apiKey
-        ? new KeyRotator([options.apiKey])
-        : KeyRotator.fromEnvList(process.env.GROQ_API_KEYS);
+    const rotator = options.keyRotator
+      ?? (options.apiKeys
+        ? new KeyRotator(options.apiKeys)
+        : options.apiKey
+          ? new KeyRotator([options.apiKey])
+          : KeyRotator.fromEnvList(process.env.GROQ_API_KEYS));
     if (!rotator) {
-      throw new Error("createVerbLLM: provider 'groq' needs apiKey(s), or GROQ_API_KEYS in env");
+      throw new Error("createToolLLM: provider 'groq' needs apiKey(s), or GROQ_API_KEYS in env");
     }
     const model = options.model ?? process.env.GROQ_MODEL ?? GROQ_DEFAULT_MODEL;
-    return new GroqVerbLLM(rotator, model, toolSchema);
+    return new GroqVerbLLM(rotator, model, toolSchema, undefined, toolName, toolDescription);
   }
 
   const client = new Anthropic({ apiKey: options.apiKey });
   const model = options.model ?? process.env.CAIRN_RUNTIME_MODEL ?? "claude-opus-5";
-  return new AnthropicVerbLLM(client, model, toolSchema);
+  return new AnthropicVerbLLM(client, model, toolSchema, toolName, toolDescription);
+}
+
+/** Builds the provider-appropriate VerbLLM from the same options createCopilotHandler accepts — reused by the realtime relay. */
+export function createVerbLLM(options: CreateCopilotHandlerOptions = {}): VerbLLM {
+  const registeredActions = options.registeredActions ?? [];
+  return createToolLLM(options, buildVerbToolSchema(registeredActions, options.actionDescriptions ?? {}), VERB_TOOL_NAME, VERB_TOOL_DESCRIPTION);
+}
+
+/** Same real rotation/model-selection logic as createVerbLLM, configured
+ * for the Planner's own tool instead — see resolvePlan. */
+export function createPlanLLM(options: CreateCopilotHandlerOptions = {}): VerbLLM {
+  return createToolLLM(options, buildPlanToolSchema(), PLAN_TOOL_NAME, PLAN_TOOL_DESCRIPTION);
+}
+
+/**
+ * Architecture Pillar 3 (Skill half) — the Formulator. Runs once a task
+ * genuinely completes (not per-step — cheap on purpose, matching the plan
+ * file's own framing), compiling whatever real, Critic-verified
+ * `learnedFact`s were collected along the way (CriticVerdictSchema's own
+ * doc comment is the enforcement point for "never user data") into one
+ * Skill. Deliberately DETERMINISTIC, not a fourth kind of real LLM call —
+ * every fact it compiles already passed through the Critic's own
+ * verification, so there's nothing left to "figure out" that would
+ * justify the added cost/latency/failure surface of another model round
+ * trip; see DEVELOPMENT.md's own entry for the real cost reasoning
+ * (this session already hit genuine Groq quota exhaustion more than once
+ * from cumulative call volume). Returns null when nothing was learned —
+ * the common case, not an error; a caller should simply not save anything.
+ */
+export function compileSkill(goal: string, learnedFacts: string[], pattern?: UiPatternId): Skill | null {
+  if (learnedFacts.length === 0) return null;
+  const name = goal.length > 80 ? `${goal.slice(0, 79)}…` : goal;
+  const firstFact = learnedFacts[0];
+  return {
+    id: slugifySkillId(name),
+    name,
+    description: firstFact.length > 120 ? `${firstFact.slice(0, 119)}…` : firstFact,
+    instructions: learnedFacts.join(" "),
+    pattern,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+const SIGNIFICANT_WORD_MIN_LENGTH = 4;
+// Real, common phrasing variance between a Skill's own name (usually a
+// gerund, "Connecting nodes...") and a later goal restating the same idea
+// ("connect the node...") means exact word equality misses obvious
+// matches ("connecting" vs "connect", "nodes" vs "node"). A crude 4-
+// character-prefix "stem" — not a real stemming library, deliberately —
+// catches this common case without a new dependency, at the cost of
+// occasional false-positive stems on short unrelated words; the min
+// significant-word length above already screens out the shortest, most
+// collision-prone words.
+const STEM_LENGTH = 4;
+
+function significantWordStems(text: string): Set<string> {
+  return new Set(
+    text
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((w) => w.length >= SIGNIFICANT_WORD_MIN_LENGTH)
+      .map((w) => w.slice(0, STEM_LENGTH)),
+  );
+}
+
+/**
+ * Architecture Pillar 3 (Skill half) — the retrieval side. A cheap,
+ * deterministic keyword-overlap match against a NEW goal (never another
+ * real LLM call, same reasoning as compileSkill above) — real progressive
+ * disclosure: every Skill's summary is cheap enough to always list (see
+ * SkillStore's own doc comment), but only the ONE Skill whose own name
+ * shares real, significant words with the current goal gets its full
+ * instructions loaded. A caller still needs its own SkillStore.getSkill
+ * call to fetch those full instructions for whatever this returns — this
+ * function only ever sees cheap summaries, never a full Skill.
+ */
+export function matchSkillByGoal(summaries: SkillSummary[], goal: string): SkillSummary | null {
+  const goalStems = significantWordStems(goal);
+  if (goalStems.size === 0) return null;
+
+  let best: SkillSummary | null = null;
+  let bestScore = 0;
+  for (const summary of summaries) {
+    const score = Array.from(significantWordStems(summary.name)).filter((stem) => goalStems.has(stem)).length;
+    if (score > bestScore) {
+      bestScore = score;
+      best = summary;
+    }
+  }
+  return best;
+}
+
+/** Same rendering discipline as renderRegisteredActions — "id (description)" per Skill, for the Planner's own userMessage. */
+export function renderSkillSummaries(summaries: SkillSummary[]): string {
+  return summaries.map((s) => `${s.name} (${s.description})`).join("; ");
+}
+
+const PlanRequestSchema = z
+  .object({
+    goal: z.string().min(1),
+    version: z.number().int().min(1).optional(),
+  })
+  .strict();
+
+const CriticRequestSchema = z
+  .object({
+    task: TaskSchema,
+    goal: z.string().min(1),
+    verb: VerbResponseSchema,
+    observation: z.string().nullable().optional(),
+  })
+  .strict();
+
+export type PlanHandler = (body: unknown) => Promise<{ status: number; body: Plan | { error: string } }>;
+export type CriticHandler = (body: unknown) => Promise<{ status: number; body: CriticVerdict | { error: string } }>;
+
+/**
+ * Architecture Pillar 4 — the typed/HTTP transport's own real Planner
+ * endpoint, closing the gap the plan file names directly: "the typed/
+ * HTTP path (index.tsx's runTypedAgentLoop) has zero Planner/Critic
+ * wiring at all... today explicitly realtime-only by deferral, not by
+ * decision." A thin HTTP wrapper around the exact same resolvePlan the
+ * realtime relay already calls in-process — the LLM call itself only
+ * ever needs to happen server-side (it holds the real API key), so a
+ * client-side caller (index.tsx) reaches it over a real request instead
+ * of importing resolvePlan directly, same reasoning as createCopilotHandler
+ * itself.
+ */
+export function createPlanHandler(manifest: Manifest, options: CreateCopilotHandlerOptions = {}): PlanHandler {
+  return createPlanHandlerWithLLM(manifest, createPlanLLM(options), options);
+}
+
+/** Same as createPlanHandler, but with the LLM injected — used by tests to fake it, same pattern as createCopilotHandlerWithLLM. */
+export function createPlanHandlerWithLLM(
+  manifest: Manifest,
+  planLLM: VerbLLM,
+  options: { registeredActions?: string[]; actionDescriptions?: Record<string, string>; skills?: SkillStore; skillsScopeId?: string } = {},
+): PlanHandler {
+  const actionsText = renderRegisteredActions(options.registeredActions ?? [], options.actionDescriptions ?? {});
+  const skillsScopeId = options.skillsScopeId ?? "default";
+  return async function handlePlanRequest(body: unknown) {
+    const parsed = PlanRequestSchema.safeParse(body);
+    if (!parsed.success) return { status: 400, body: { error: "invalid request body" } };
+
+    // Architecture Pillar 3 (Skill half) — the typed transport's own
+    // retrieval side, same shape realtime-server.ts's finalizeTurn
+    // already computes in-process. Absent `options.skills` (the
+    // overwhelming majority of deployments today) means zero overhead —
+    // this whole block is skipped entirely.
+    const skillSummaries = options.skills ? options.skills.listSkillSummaries(skillsScopeId) : [];
+    const matchedSkillSummary = skillSummaries.length ? matchSkillByGoal(skillSummaries, parsed.data.goal) : null;
+    const skillsPayload = skillSummaries.length
+      ? {
+          summariesText: renderSkillSummaries(skillSummaries) || undefined,
+          suggestedInstructions: matchedSkillSummary ? (options.skills!.getSkill(skillsScopeId, matchedSkillSummary.id)?.instructions ?? undefined) : undefined,
+        }
+      : undefined;
+
+    const plan = await resolvePlan(planLLM, parsed.data.goal, parsed.data.version ?? 1, manifest, actionsText || undefined, skillsPayload);
+    return { status: 200, body: plan };
+  };
+}
+
+/** Architecture Pillar 4's Critic counterpart to createPlanHandler — see
+ * its own doc comment. A thin HTTP wrapper around the same resolveCritic
+ * the realtime relay already calls in-process. */
+export function createCriticHandler(options: CreateCopilotHandlerOptions = {}): CriticHandler {
+  return createCriticHandlerWithLLM(createCriticLLM(options));
+}
+
+/** Same as createCriticHandler, but with the LLM injected — used by tests to fake it. */
+export function createCriticHandlerWithLLM(criticLLM: VerbLLM): CriticHandler {
+  return async function handleCriticRequest(body: unknown) {
+    const parsed = CriticRequestSchema.safeParse(body);
+    if (!parsed.success) return { status: 400, body: { error: "invalid request body" } };
+    const verdict = await resolveCritic(criticLLM, parsed.data.task, parsed.data.goal, parsed.data.verb, parsed.data.observation);
+    return { status: 200, body: verdict };
+  };
+}
+
+const SkillSaveRequestSchema = z
+  .object({
+    goal: z.string().min(1),
+    learnedFacts: z.array(z.string().min(1)),
+    pattern: z.enum(UI_PATTERNS).optional(),
+  })
+  .strict();
+
+export type SkillSaveHandler = (body: unknown) => Promise<{ status: number; body: { saved: boolean } | { error: string } }>;
+
+/**
+ * Architecture Pillar 3 (Skill half) — the typed transport's own save
+ * side (the Formulator's HTTP counterpart to realtime-server.ts's own
+ * in-process `compileSkill`+`saveSkill` call at the end of `finalizeTurn`).
+ * No LLM involved — `compileSkill` is deterministic (see its own doc
+ * comment for why) — so this needs no `-WithLLM` variant; it's real
+ * client-callable storage access, nothing more. The caller (index.tsx's
+ * runTypedAgentLoop) accumulates `learnedFacts` from its own Critic calls
+ * across one whole turn and posts here exactly once, after the turn
+ * concludes — never per-step, matching the Formulator's own "cheap on
+ * purpose" framing.
+ */
+export function createSkillSaveHandler(skills: SkillStore, skillsScopeId = "default"): SkillSaveHandler {
+  return async function handleSkillSaveRequest(body: unknown) {
+    const parsed = SkillSaveRequestSchema.safeParse(body);
+    if (!parsed.success) return { status: 400, body: { error: "invalid request body" } };
+    const skill = compileSkill(parsed.data.goal, parsed.data.learnedFacts, parsed.data.pattern);
+    if (skill) skills.saveSkill(skillsScopeId, skill);
+    return { status: 200, body: { saved: skill !== null } };
+  };
+}
+
+/**
+ * Phase 2 step 1 — a genuinely UNSTRUCTURED, streamed call: no tools, no
+ * forced choice, just the model's plain spoken answer to the user's
+ * question, delivered incrementally. Exists because a real, live spike
+ * against Groq's actual API (see DEVELOPMENT.md/the plan file's Phase 2
+ * entry) found that a FORCED tool call never streams at the field level
+ * even with stream:true — the whole structured object arrives in one
+ * chunk. Plain, unforced generation genuinely streams token-by-token on
+ * both providers, and finishes faster besides — this is what makes "LLM
+ * tokens streamed straight into TTS" possible at all.
+ */
+export interface StreamingTextLLM {
+  respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string>;
 }
 
 // ---------------------------------------------------------------------------
@@ -263,6 +767,8 @@ export class AnthropicVerbLLM implements VerbLLM {
     private client: MessagesClient,
     private model: string,
     private toolSchema: Record<string, unknown>,
+    private toolName: string = VERB_TOOL_NAME,
+    private toolDescription: string = VERB_TOOL_DESCRIPTION,
   ) {}
 
   async respond(systemPrompt: string, userMessage: string): Promise<unknown> {
@@ -272,23 +778,58 @@ export class AnthropicVerbLLM implements VerbLLM {
       system: [{ type: "text", text: systemPrompt, cache_control: { type: "ephemeral" } }],
       tools: [
         {
-          name: VERB_TOOL_NAME,
-          description: VERB_TOOL_DESCRIPTION,
+          name: this.toolName,
+          description: this.toolDescription,
           input_schema: this.toolSchema,
           strict: true,
         },
       ],
-      tool_choice: { type: "tool", name: VERB_TOOL_NAME },
+      tool_choice: { type: "tool", name: this.toolName },
       messages: [{ role: "user", content: userMessage }],
     });
 
     const toolUse = response.content.find(
-      (block: any): block is Anthropic.ToolUseBlock => block?.type === "tool_use" && block?.name === VERB_TOOL_NAME,
+      (block: any): block is Anthropic.ToolUseBlock => block?.type === "tool_use" && block?.name === this.toolName,
     );
     return toolUse?.input;
   }
 }
 
+/** Minimal shape AnthropicStreamingTextLLM needs — narrow enough to fake in tests (a plain async generator, no real SDK stream class). */
+export interface StreamingMessagesClient {
+  messages: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    create: (params: any) => Promise<AsyncIterable<any>>;
+  };
+}
+
+/** No tools, no tool_choice — see StreamingTextLLM's own doc comment for why plain, unforced generation is what streams. */
+export class AnthropicStreamingTextLLM implements StreamingTextLLM {
+  constructor(
+    private client: StreamingMessagesClient,
+    private model: string,
+  ) {}
+
+  async respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string> {
+    const stream = await this.client.messages.create({
+      model: this.model,
+      max_tokens: 1024,
+      stream: true,
+      system: [{ type: "text", text: systemPrompt, cache_control: { type: "ephemeral" } }],
+      messages: [{ role: "user", content: userMessage }],
+    });
+
+    let full = "";
+    for await (const event of stream) {
+      if (event?.type === "content_block_delta" && event?.delta?.type === "text_delta" && typeof event.delta.text === "string") {
+        full += event.delta.text;
+        onChunk(event.delta.text);
+      }
+    }
+    return full;
+  }
+}
+
 // Groq's chat-completions API is OpenAI-compatible: function-calling tools
 // instead of Anthropic's native tool_use blocks, arguments come back as a
 // JSON *string* to parse. Model list verified live against
@@ -310,41 +851,114 @@ export class GroqVerbLLM implements VerbLLM {
     private keys: KeyRotator,
     private model: string,
     private toolSchema: Record<string, unknown>,
-    private clientFactory: (apiKey: string) => GroqLikeClient = (apiKey) => new Groq({ apiKey }),
+    // maxRetries: 0 — real, live-found latency bug this closes: the Groq
+    // SDK's own default (2 automatic retries with exponential backoff) ran
+    // UNDERNEATH respond()'s own key-rotation retry loop, so a single 429
+    // key attempt could silently eat several real seconds of SDK-internal
+    // backoff before respond() ever saw the rejection and moved on to a
+    // DIFFERENT key. With several keys in rotation genuinely rate-limited
+    // at once (the common case this closes for), that compounded into a
+    // real, live-reported multi-second-to-a-minute hang with no visible
+    // progress — worse than useless, since respond()'s own retry already
+    // tries a different key/quota entirely, which the SDK's blind same-key
+    // backoff can never fix. respond() is the sole source of retry policy
+    // here now.
+    private clientFactory: (apiKey: string) => GroqLikeClient = (apiKey) => new Groq({ apiKey, maxRetries: 0 }),
+    private toolName: string = VERB_TOOL_NAME,
+    private toolDescription: string = VERB_TOOL_DESCRIPTION,
   ) {}
 
   async respond(systemPrompt: string, userMessage: string): Promise<unknown> {
-    try {
-      return await this.attemptRespond(systemPrompt, userMessage);
-    } catch (err) {
-      // Real, live bugs, not theoretical — two distinct non-deterministic
-      // failure modes from openai/gpt-oss-120b (a reasoning-capable open
-      // model), both rejected by Groq's own server-side validation before
-      // this code ever sees a real response to work with, and both found
-      // to recover cleanly on an identical retry a moment later:
-      //  - "output_parse_failed": the model "thinks out loud" in plain
-      //    prose instead of emitting the forced tool call.
-      //  - "tool_use_failed": the model hallucinates a slightly-wrong tool
-      //    name ("json", "response_with_verb" — seen live, both against
-      //    the real, correctly-configured VERB_TOOL_NAME) instead of the
-      //    one forced tool it was actually given. This one was the actual
-      //    cause behind a real "voice keeps breaking" report — found live
-      //    running the new eval harness's synthetic-voice scenario, where
-      //    it surfaced as "Something went wrong on my end" with no other
-      //    symptom, exactly matching what got reported.
-      // One retry — not exponential backoff, this is a latency-sensitive
-      // voice/chat path — genuinely helps rather than just delaying the
-      // same failure. Anything else still propagates to resolveVerb's own
-      // catch, unchanged.
-      if (isRetryableToolCallFailure(err)) {
-        return await this.attemptRespond(systemPrompt, userMessage);
+    // Three independent, real retry policies, combined in one loop:
+    //  - Invalid key (401): the key itself is confirmed dead (see
+    //    isInvalidKeyError/KeyRotator.markDead) — excluded from rotation
+    //    for the rest of this process's life, then retried on a
+    //    DIFFERENT configured key, same bound as rate-limit retries
+    //    below. Real, live-found gap this closes: before this existed, a
+    //    single expired/invalid key in the rotation silently sabotaged
+    //    roughly (dead keys / total keys) of every real request forever
+    //    — GroqVerbLLM only ever retried a 429, never a 401, so hitting a
+    //    dead key on the rotation just failed the whole turn outright
+    //    even when other, genuinely working keys were configured.
+    //  - Rate-limit (429): retried on a DIFFERENT configured key, up to
+    //    once per distinct key. Found live — a Groq account's own daily
+    //    token quota exhausting mid-session doesn't mean every OTHER
+    //    configured account/key is also exhausted; KeyRotator.take()
+    //    already advances on every call, so simply retrying reaches a
+    //    different key automatically. With only one key configured this
+    //    never fires (nothing else to fall back to) — same behavior as
+    //    before this existed.
+    //  - Tool-call failure (see below): exactly one retry, regardless of
+    //    key count — unrelated to which key was used.
+    const maxKeyAttempts = Math.max(this.keys.size, 1);
+    let keyAttempts = 0;
+    let usedToolCallRetry = false;
+
+    for (;;) {
+      const key = this.keys.take();
+      try {
+        return await this.attemptRespond(key, systemPrompt, userMessage);
+      } catch (err) {
+        if (isInvalidKeyError(err)) {
+          this.keys.markDead(key);
+          if (keyAttempts < maxKeyAttempts - 1) {
+            keyAttempts++;
+            continue;
+          }
+          throw err;
+        }
+        if (isRateLimitError(err) && keyAttempts < maxKeyAttempts - 1) {
+          keyAttempts++;
+          continue;
+        }
+        // Real, live bugs, not theoretical — two distinct non-deterministic
+        // failure modes from openai/gpt-oss-120b (a reasoning-capable open
+        // model), both rejected by Groq's own server-side validation before
+        // this code ever sees a real response to work with, and both found
+        // to recover cleanly on an identical retry a moment later:
+        //  - "output_parse_failed": the model "thinks out loud" in plain
+        //    prose instead of emitting the forced tool call.
+        //  - "tool_use_failed": the model hallucinates a slightly-wrong tool
+        //    name ("json", "response_with_verb" — seen live, both against
+        //    the real, correctly-configured VERB_TOOL_NAME) instead of the
+        //    one forced tool it was actually given. This one was the actual
+        //    cause behind a real "voice keeps breaking" report — found live
+        //    running the new eval harness's synthetic-voice scenario, where
+        //    it surfaced as "Something went wrong on my end" with no other
+        //    symptom, exactly matching what got reported.
+        // Real, live bug found AFTER the single-retry mitigation above had
+        // already shipped: the SAME hallucinated-tool-name failure can hit
+        // twice in a row (seen live, back to back, on one otherwise-normal
+        // question), exhausting the one retry and still falling through to
+        // the generic fallback — even though Groq's own error response
+        // carries the model's complete, correctly-shaped answer right there
+        // in `failed_generation` (it parsed the arguments fine; it only
+        // picked the wrong TOOL NAME to wrap them in). Recovering that
+        // directly costs nothing (no extra round trip) and can't make
+        // things worse than today — resolveVerb's own VerbResponseSchema
+        // check right after this returns is the same safety net a normal,
+        // successful response already goes through, so a malformed
+        // extraction just falls to its existing "I'm not sure" fallback.
+        // Tried before spending the one real retry on output_parse_failed's
+        // case, where there's genuinely nothing to extract (no forced tool
+        // call was even produced).
+        const recovered = extractFailedGenerationArguments(err);
+        if (recovered !== undefined) return recovered;
+        // One retry — not exponential backoff, this is a latency-sensitive
+        // voice/chat path — genuinely helps rather than just delaying the
+        // same failure. Anything else still propagates to resolveVerb's own
+        // catch, unchanged.
+        if (isRetryableToolCallFailure(err) && !usedToolCallRetry) {
+          usedToolCallRetry = true;
+          continue;
+        }
+        throw err;
       }
-      throw err;
     }
   }
 
-  private async attemptRespond(systemPrompt: string, userMessage: string): Promise<unknown> {
-    const client = this.clientFactory(this.keys.take());
+  private async attemptRespond(apiKey: string, systemPrompt: string, userMessage: string): Promise<unknown> {
+    const client = this.clientFactory(apiKey);
     const completion = await client.chat.completions.create({
       model: this.model,
       messages: [
@@ -355,13 +969,13 @@ export class GroqVerbLLM implements VerbLLM {
         {
           type: "function",
           function: {
-            name: VERB_TOOL_NAME,
-            description: VERB_TOOL_DESCRIPTION,
+            name: this.toolName,
+            description: this.toolDescription,
             parameters: this.toolSchema,
           },
         },
       ],
-      tool_choice: { type: "function", function: { name: VERB_TOOL_NAME } },
+      tool_choice: { type: "function", function: { name: this.toolName } },
     });
 
     const toolCall = completion.choices[0]?.message?.tool_calls?.[0];
@@ -374,15 +988,103 @@ export class GroqVerbLLM implements VerbLLM {
   }
 }
 
+/** Minimal shape GroqStreamingTextLLM needs — narrow enough to fake in tests (a plain async generator, no real SDK stream class). */
+export interface GroqLikeStreamingClient {
+  chat: {
+    completions: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      create: (params: any) => Promise<AsyncIterable<any>>;
+    };
+  };
+}
+
+/** No tools, no tool_choice — see StreamingTextLLM's own doc comment for why plain, unforced generation is what streams. No retry-on-hallucinated-tool-name logic here (GroqVerbLLM's own real, live-found bug) — there's no tool to hallucinate the name of. */
+export class GroqStreamingTextLLM implements StreamingTextLLM {
+  constructor(
+    private keys: KeyRotator,
+    private model: string,
+    // maxRetries: 0 — same real latency bug as GroqVerbLLM's own
+    // clientFactory default; see its doc comment for the full reasoning.
+    // respondStreamed below already has its own key-rotation retry loop
+    // (maxAttempts bounded by keys.size), which makes the SDK's blind
+    // same-key backoff redundant AND a source of silent multi-second
+    // delay stacked underneath it.
+    private clientFactory: (apiKey: string) => GroqLikeStreamingClient = (apiKey) => new Groq({ apiKey, maxRetries: 0 }),
+  ) {}
+
+  async respondStreamed(systemPrompt: string, userMessage: string, onChunk: (delta: string) => void): Promise<string> {
+    // Same rate-limit/invalid-key-retries-on-a-different-key policy as
+    // GroqVerbLLM.respond (see its own doc comment, including the real,
+    // live-found "a dead key sabotages roughly 1/N of every request"
+    // gap markDead closes). The one thing this path has to guard against
+    // that the non-streaming call doesn't: a real chunk already having
+    // reached the caller via onChunk before something fails mid-stream —
+    // both a 429 and a 401 always arrive on the initial request, before
+    // any chunk streams, so retrying is only ever attempted when nothing
+    // has been emitted yet; a genuinely different mid-stream failure is
+    // never retried, since doing so would duplicate output already sent.
+    const maxAttempts = Math.max(this.keys.size, 1);
+    let lastErr: unknown;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      let emittedAnyChunk = false;
+      const key = this.keys.take();
+      try {
+        const client = this.clientFactory(key);
+        const stream = await client.chat.completions.create({
+          model: this.model,
+          stream: true,
+          messages: [
+            { role: "system", content: systemPrompt },
+            { role: "user", content: userMessage },
+          ],
+        });
+
+        let full = "";
+        for await (const chunk of stream) {
+          const delta = chunk?.choices?.[0]?.delta?.content;
+          if (typeof delta === "string" && delta) {
+            full += delta;
+            emittedAnyChunk = true;
+            onChunk(delta);
+          }
+        }
+        return full;
+      } catch (err) {
+        lastErr = err;
+        if (emittedAnyChunk) throw err;
+        if (isInvalidKeyError(err)) this.keys.markDead(key);
+        if ((isInvalidKeyError(err) || isRateLimitError(err)) && attempt < maxAttempts - 1) continue;
+        throw err;
+      }
+    }
+    throw lastErr;
+  }
+}
+
 /** Groq's SDK doesn't export a stable error shape to import and check
  * against, so this checks defensively across the ways the real error has
  * actually been observed to surface — a thrown APIError with a nested
  * `.error.code`, a plain `.code`, or just the code string showing up
- * somewhere in the message — rather than relying on exactly one of them. */
+ * somewhere in the message — rather than relying on exactly one of them.
+ *
+ * Real, live bug found AFTER this function had already shipped and been
+ * unit-tested: the actual Groq SDK error is doubly-nested
+ * (`err.error.error.code`, matching isRateLimitError's own real-shape
+ * fix below) but this only ever checked ONE level (`err.error?.code`) —
+ * so `code` always came back `undefined` against the real API surface,
+ * and the retry this function exists for NEVER actually fired, despite
+ * every unit test passing (they all hand-built a shallow, one-level
+ * mock that doesn't match what Groq really throws). Caught live: a
+ * `tool_use_failed`/hallucinated-tool-name error with a perfectly good
+ * answer sitting right there in `failed_generation` fell straight to
+ * the generic "Something went wrong on my end" fallback instead of
+ * retrying — exactly the failure mode this function's own doc comment
+ * already claimed to fix. Now checks the same depth `isRateLimitError`
+ * does. */
 function isRetryableToolCallFailure(err: unknown): boolean {
   if (!err || typeof err !== "object") return false;
-  const e = err as { code?: unknown; error?: { code?: unknown }; message?: unknown };
-  const code = e.code ?? e.error?.code;
+  const e = err as { code?: unknown; error?: { code?: unknown; error?: { code?: unknown } }; message?: unknown };
+  const code = e.code ?? e.error?.code ?? e.error?.error?.code;
   const message = typeof e.message === "string" ? e.message : "";
   if (code === "output_parse_failed" || message.includes("output_parse_failed")) return true;
   // "attempted to call tool 'json' which was not in request.tools" — the
@@ -393,13 +1095,94 @@ function isRetryableToolCallFailure(err: unknown): boolean {
   return false;
 }
 
+/**
+ * Recovers the model's real, already-generated answer straight out of a
+ * `tool_use_failed` error, instead of spending a retry re-asking for
+ * something Groq already has. Same doubly-nested shape
+ * isRetryableToolCallFailure/isRateLimitError check against
+ * (`err.error.error.*`) plus the one extra field this specific error
+ * carries: `failed_generation`, a JSON-encoded string of exactly what the
+ * model produced — `{"name": "<hallucinated tool name>", "arguments":
+ * {...the real verb payload...}}`. Deliberately narrow: only fires for
+ * `tool_use_failed` specifically (never `output_parse_failed`, where the
+ * model didn't produce a forced tool call at all, so there's nothing real
+ * to recover here), and only returns something when `arguments` actually
+ * parses as an object — anything else (a missing field, a non-JSON
+ * string, a differently-shaped error) returns undefined and the caller
+ * falls through to its existing retry/throw path, unchanged.
+ */
+function extractFailedGenerationArguments(err: unknown): unknown {
+  if (!err || typeof err !== "object") return undefined;
+  const e = err as { error?: { error?: { code?: unknown; failed_generation?: unknown } } };
+  if (e.error?.error?.code !== "tool_use_failed") return undefined;
+  const raw = e.error.error.failed_generation;
+  if (typeof raw !== "string") return undefined;
+  try {
+    const parsed = JSON.parse(raw) as { arguments?: unknown };
+    return parsed && typeof parsed === "object" && parsed.arguments && typeof parsed.arguments === "object" ? parsed.arguments : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Same defensive-shape-checking approach as isRetryableToolCallFailure —
+ * the real error observed live (see DEVELOPMENT.md) is a thrown APIError
+ * with `.status === 429` and a doubly-nested `.error.error.code ===
+ * "rate_limit_exceeded"`, but checks a couple of shallower shapes too
+ * rather than depending on exactly that nesting. */
+function isRateLimitError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { status?: unknown; code?: unknown; error?: { code?: unknown; error?: { code?: unknown } }; message?: unknown };
+  if (e.status === 429) return true;
+  const code = e.code ?? e.error?.code ?? e.error?.error?.code;
+  if (code === "rate_limit_exceeded") return true;
+  const message = typeof e.message === "string" ? e.message : "";
+  return message.includes("rate_limit_exceeded") || message.includes("Rate limit reached");
+}
+
+/**
+ * Same defensive-shape-checking approach as isRateLimitError — the real
+ * error was checked directly against the live Groq API before writing
+ * this (not guessed): a real 401 from an invalid/expired key throws with
+ * `.status === 401` and the SAME doubly-nested `.error.error.code ===
+ * "invalid_api_key"` shape isRateLimitError already has to check for its
+ * own 429 case, confirmed via `Groq({apiKey}).chat.completions.create(...)`
+ * against a genuinely dead key and inspecting the thrown error's own
+ * `.status`/`.error`/`.message` fields directly.
+ */
+function isInvalidKeyError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { status?: unknown; code?: unknown; error?: { code?: unknown; error?: { code?: unknown } }; message?: unknown };
+  if (e.status === 401) return true;
+  const code = e.code ?? e.error?.code ?? e.error?.error?.code;
+  if (code === "invalid_api_key") return true;
+  const message = typeof e.message === "string" ? e.message : "";
+  return message.includes("invalid_api_key") || message.includes("Invalid API Key");
+}
+
 // ---------------------------------------------------------------------------
 // Shared tool schema / system prompt
 // ---------------------------------------------------------------------------
 
 const VERB_TOOL_DESCRIPTION = "Respond with exactly one action for the UI to take. Never invent selectors, routes, or code.";
 
-export function buildVerbToolSchema(registeredActions: string[]): Record<string, unknown> {
+/**
+ * Phase 4, layer 5 — the ONE place a registered action id is rendered
+ * with its (optional) real description, shared by buildVerbToolSchema,
+ * buildSystemPrompt's own do-verb text, and resolvePlan's userMessage —
+ * so the Executor and the Planner describe the exact same capability the
+ * exact same way, and there's no risk of the three drifting out of sync.
+ * Deliberately renders "id (description)" rather than baking the
+ * description into what the model must echo back — resolveVerb's own
+ * `registeredActions.includes(parsedVerb.data.action)` check (server.ts)
+ * needs the RAW id back, verbatim, or a real registered action would
+ * silently stop being recognized.
+ */
+export function renderRegisteredActions(registeredActions: string[], actionDescriptions: Record<string, string> = {}): string {
+  return registeredActions.map((id) => (actionDescriptions[id] ? `${id} (${actionDescriptions[id]})` : id)).join(", ");
+}
+
+export function buildVerbToolSchema(registeredActions: string[], actionDescriptions: Record<string, string> = {}): Record<string, unknown> {
   // Every genuinely-optional field allows `null` as well as its real type
   // (`["string", "null"]`, not just `"string"`) — found live, not
   // theoretical: real models (verified against Groq's openai/gpt-oss-120b)
@@ -420,17 +1203,24 @@ export function buildVerbToolSchema(registeredActions: string[]): Record<string,
       verb: { type: "string", enum: [...VERBS] },
       text: nullableString("Shown to the user. Required for explain. null (or omitted) if not applicable."),
       target: nullableString(
-        "An id from currentPageElements or liveElements. Required for highlight/open/click/fill/read. For do, the id of what the action applies to, if it needs one — prefer a liveElements id when the user means one specific item among several. Not used for batch — each of its own actions carries its own target instead. null (or omitted) if not applicable.",
+        "An id from currentPageElements or liveElements. Required for highlight/open/click/fill/read/select/scroll/wait_for, and for drag (the thing being dragged). For do, the id of what the action applies to, if it needs one — prefer a liveElements id when the user means one specific item among several. For key, the element to press the key on — omit to press it on whatever's currently focused. Not used for batch — each of its own actions carries its own target instead. null (or omitted) if not applicable.",
       ),
+      to: nullableString("Required for drag — the id (from currentPageElements or liveElements) of where to drop it. null (or omitted) if not applicable."),
+      key: nullableString('Required for key — one real key name: Escape, Enter, Tab, ArrowUp, ArrowDown, ArrowLeft, or ArrowRight. null (or omitted) if not applicable.'),
       route: nullableString("A route from the manifest. Required for navigate. null (or omitted) if not applicable."),
+      continueAfter: {
+        type: ["boolean", "null"],
+        description:
+          'Only for navigate. Set to true when the user\'s real goal needs MORE than just arriving at the new page — e.g. "buy earbuds" means navigate there, then search, then report back what you found, not just navigate. When true, you\'ll be asked again once you\'ve arrived, with that page\'s own real elements, so you can decide the next real step (or say you\'re done). Leave false/null for a plain "take me to X" request, where arriving IS the whole answer — setting this needlessly costs an extra real turn for no reason.',
+      },
       action: nullableString(
         "Required for do. A short label for what's being done, e.g. \"archive-invoice\" " +
           (registeredActions.length
-            ? `— either one of this deployment's registered actions [${registeredActions.join(", ")}], or, for any other element from currentPageElements or liveElements whose own description/label says it performs a real action, any short label describing it.`
+            ? `— either the exact id (never its description in parens) of one of this deployment's registered actions [${renderRegisteredActions(registeredActions, actionDescriptions)}], or, for any other element from currentPageElements or liveElements whose own description/label says it performs a real action, any short label describing it.`
             : "for any element from currentPageElements or liveElements whose own description/label says it performs a real action — no actions are separately registered in this deployment, but that path still works.") +
           " null (or omitted) if not applicable.",
       ),
-      value: nullableString('Required for fill — the exact text to type into "target". null (or omitted) if not applicable.'),
+      value: nullableString('Required for fill — the exact text to type into "target". Required for select — the option\'s visible text, never its raw internal value. null (or omitted) if not applicable.'),
       name: nullableString("Required for call_tool — a tool name from this turn's webMcpTools list, exactly as given. null (or omitted) if not applicable."),
       args: {
         type: ["object", "null"],
@@ -463,14 +1253,18 @@ export function buildVerbToolSchema(registeredActions: string[]): Record<string,
       actions: {
         type: ["array", "null"],
         description:
-          "Required for batch, 2-5 items. Several click/fill/read/call_tool steps executed in order in ONE round trip, instead of one round trip each — use this when you already know several steps are needed and don't need to see one step's real result before choosing the next (e.g. filling three known fields, or clicking through a sequence you're already sure about). If a later step genuinely depends on what an earlier one turns up, use a single step instead and decide the next one once you see its real result. text (if any) is spoken once for the whole batch, not per step. null (or omitted) if not applicable.",
+          "Required for batch, 2-5 items. Several click/fill/read/call_tool/drag/select/key/scroll/wait_for steps executed in order in ONE round trip, instead of one round trip each — use this when you already know several steps are needed and don't need to see one step's real result before choosing the next (e.g. filling three known fields, or clicking through a sequence you're already sure about). If a later step genuinely depends on what an earlier one turns up, use a single step instead and decide the next one once you see its real result. text (if any) is spoken once for the whole batch, not per step. null (or omitted) if not applicable.",
         items: {
           type: "object",
           properties: {
-            verb: { type: "string", enum: ["click", "fill", "read", "call_tool"] },
-            target: nullableString("An id from currentPageElements or liveElements. Required for click/fill/read. null (or omitted) if not applicable."),
-            value: nullableString('Required for fill — the exact text to type into "target". null (or omitted) if not applicable.'),
+            verb: { type: "string", enum: ["click", "fill", "read", "call_tool", "drag", "select", "key", "scroll", "wait_for"] },
+            target: nullableString(
+              "An id from currentPageElements or liveElements. Required for click/fill/read/select/scroll/wait_for/drag (the thing being dragged). For key, omit to press it on whatever's currently focused. null (or omitted) if not applicable.",
+            ),
+            value: nullableString('Required for fill — the exact text to type into "target". Required for select — the option\'s visible text. null (or omitted) if not applicable.'),
             name: nullableString("Required for call_tool — a tool name from this turn's webMcpTools list. null (or omitted) if not applicable."),
+            to: nullableString("Required for drag — the id of where to drop it. null (or omitted) if not applicable."),
+            key: nullableString("Required for key — one real key name (Escape, Enter, Tab, ArrowUp, ArrowDown, ArrowLeft, ArrowRight). null (or omitted) if not applicable."),
             args: {
               type: ["object", "null"],
               description: "For call_tool — the arguments object, matching that tool's own inputSchema. null (or omitted) if the tool takes none.",
@@ -501,7 +1295,7 @@ export function buildVerbToolSchema(registeredActions: string[]): Record<string,
  * element detail is attached separately, per request, in resolveVerb —
  * see buildPageElements.
  */
-export function buildSystemPrompt(manifest: Manifest, registeredActions: string[], persona = "Cairn"): string {
+export function buildSystemPrompt(manifest: Manifest, registeredActions: string[], persona = "Cairn", actionDescriptions: Record<string, string> = {}): string {
   const pageSummaries = manifest.pages.map((p) => `- ${p.route}: ${p.purpose}`).join("\n");
 
   return `You are ${persona}, an in-app assistant. You help users of this web app by
@@ -528,9 +1322,41 @@ directory below plus three things attached to each request:
   directly (name, description, and its own input schema) — when a real
   tool exists for what the user's asking, it's the most reliable way to do
   it (see "call_tool" below), more so than clicking around.
+- "currentPageDataShapes": the real shape of the data this page works
+  with — a type name and its real fields, e.g. Invoice { status: "Paid" |
+  "Overdue" | "Archived" }. Use this to know a field's REAL possible
+  values (e.g. what "status" can actually be set to) or what a record on
+  this page actually looks like, instead of guessing from a button label
+  or making up a value. "none" means this page's real data shape wasn't
+  traced — don't treat that as "this page has no data," just don't invent
+  field names or values for it.
+- "suggestedApproach": present only when this page's real, live-scanned
+  elements matched a known UI pattern (a data table, a kanban board, a
+  node/workflow canvas, a search/filter list, a multi-step wizard) — a
+  short, general hint for how that KIND of page is usually best operated
+  (e.g. "check whether this canvas connects nodes via a dropdown or a
+  drag gesture before choosing"). A starting point, never a script — still
+  verify everything against the real liveElements/currentPageElements
+  exactly as you always would; absent entirely when nothing matched, which
+  is not itself a signal of anything.
+Every id in currentPageElements/liveElements is for YOUR use only, to put
+in "target" so the right element gets acted on — it is never something to
+say or write to the user, in any answer, for any reason, even one that
+directly asks how to tell two identical-looking items apart, or asks
+outright what the "technical" or "internal" way something works is. That
+question still has a real answer without ever printing the id string
+itself: name the CONCEPT ("each one gets its own internal identifier
+behind the scenes") without the literal value, exactly the way you'd
+describe a database having primary keys without reading one out loud.
+Wrong: "its own unique ID (for example, board-card-card-1788625210797)."
+Right: "its own internal identifier, though that's not something you'd
+normally see or need." If nothing else actually distinguishes two items
+on screen, say so plainly — position, column, or other real visible text
+first; the CONCEPT of an internal id only as a last resort, and even then
+never its actual value.
 Never invent a page, route, id, action, or tool name that isn't listed in
-one of these four places (the route directory, currentPageElements,
-liveElements, or webMcpTools). If a question is about a page other than
+one of these five places (the route directory, currentPageElements,
+liveElements, webMcpTools, or currentPageDataShapes). If a question is about a page other than
 the current one, you know its route and purpose from the directory but not
 its elements — say so and offer to navigate there rather than guessing at
 a button that page might have.
@@ -545,6 +1371,11 @@ Always call ${VERB_TOOL_NAME} exactly once with one of these verbs:
   panel — this one actually clicks the element after highlighting it, so
   only use it when the element is meant to reveal something on click.
 - navigate: send the user to a route that appears in the manifest, in "route".
+  Set "continueAfter" to true only when the real goal needs more than just
+  arriving there (e.g. "buy earbuds" — navigate, then search, then report
+  back) — you'll be asked again once you've arrived, with that page's own
+  real elements, to decide the next step. Leave it false/null for a plain
+  "take me to X" request, where arriving is the whole answer.
 - tour: 2-6 ordered "steps", each with its own "text" and (usually) a
   "target". Use this whenever explaining the answer means touching more
   than one element — e.g. "what can I do on this page" or "give me a tour" —
@@ -570,7 +1401,7 @@ Always call ${VERB_TOOL_NAME} exactly once with one of these verbs:
      "target" and a short label in "action". Works even when the action has
      no network call at all (e.g. a button that just reveals a form) — it
      still gets clicked for real.
-  3. One of this deployment's registered action ids: [${registeredActions.join(", ") || "none registered"}] — put that exact id in "action".
+  3. One of this deployment's registered actions: [${renderRegisteredActions(registeredActions, actionDescriptions) || "none registered"}] — put that exact id (never its description in parens) in "action".
   If none applies — the target isn't in liveElements or currentPageElements
   and isn't a registered action — use "explain" and say you can't do that
   from here. Never invent a target or action id that isn't in one of those
@@ -596,21 +1427,41 @@ response; once you do, answer with one of the verbs above instead):
   listed in "webMcpTools" — "name" (exactly as given) and "args" (matching
   that tool's own schema). This is the most reliable way to do something
   when a real tool for it exists — prefer it over do/click when it does.
-All four require a real id/name from currentPageElements, liveElements, or
+- drag: drag a real element onto another one — "target" (what's being
+  dragged) and "to" (where it's dropped), both real ids. Use this for
+  anything click/fill can't reach: connecting two nodes on a canvas/
+  workflow editor, reordering a list, moving a card between columns on a
+  kanban board.
+- select: choose a real dropdown/listbox option — "target" (the dropdown)
+  and "value" (the option's exact VISIBLE text, never an internal value
+  you're guessing at).
+- key: press one real key — Escape, Enter, Tab, ArrowUp, ArrowDown,
+  ArrowLeft, or ArrowRight, in "key". "target" is optional — omit it to
+  press the key on whatever's currently focused (e.g. right after a fill),
+  or name an element to focus it first.
+- scroll: bring a real, already-known element into view — "target" — for
+  content you (or the user) need to actually see before acting on it or
+  narrating it, without clicking or reading it.
+- wait_for: explicitly pause until a real, already-known element appears
+  or becomes findable — "target" — use this when you know something
+  should show up after an earlier step (a confirmation toast, a panel
+  that opens async) and want to confirm it actually did before reporting
+  success, instead of guessing that enough time has passed.
+All nine require a real id/name from currentPageElements, liveElements, or
 webMcpTools — never invent one. You'll be shown the real result of each
 step and asked again what to do next; after a small number of steps,
 answer with a terminal verb even if incomplete, explaining what you found.
 
-- batch: 2-5 of the four steps above (click/fill/read/call_tool, each in
-  its own shape — no separate "text"), run in order, in "actions" — use
-  this INSTEAD of separate single steps when you already know every step
-  you need and none of them depends on seeing an earlier one's real result
-  first (e.g. filling three fields you can already see, or a known
-  sequence of clicks). If a later step needs to react to what an earlier
-  one turns up, or depends on something an earlier step's click would
-  newly reveal, use single steps instead — a batch only sees the page as
-  it is right now, not as an earlier step in the same batch leaves it. One
-  step failing stops the rest of that batch.
+- batch: 2-5 of the nine steps above (click/fill/read/call_tool/drag/
+  select/key/scroll/wait_for, each in its own shape — no separate "text"),
+  run in order, in "actions" — use this INSTEAD of separate single steps
+  when you already know every step you need and none of them depends on
+  seeing an earlier one's real result first (e.g. filling three fields you
+  can already see, or a known sequence of clicks). If a later step needs to
+  react to what an earlier one turns up, or depends on something an earlier
+  step's click would newly reveal, use single steps instead — a batch only
+  sees the page as it is right now, not as an earlier step in the same
+  batch leaves it. One step failing stops the rest of that batch.
 
 Every "text" field (in explain, or per-step in tour, or the optional text on
 any other verb) is read aloud AND shown on screen, so it must sound like a
@@ -618,9 +1469,63 @@ person talking, not documentation:
 - No markdown — no "**bold**", no bullet lists, no backticks, no headings.
 - Never say an element's internal id (e.g. never say "create-invoice" or
   "the element id invoice-table") — describe it the way a user sees it
-  instead (its visible label, e.g. "the Create Invoice button").
+  instead (its visible label, e.g. "the Create Invoice button"). This
+  holds even when asked how to tell two same-named/identical-looking
+  items apart — that question feels like it needs the id, but it doesn't:
+  describe them by what's actually visible instead (their column, their
+  position, any other real text on them), or say plainly that they look
+  identical on screen and the user would need to open each one to tell
+  which is which. Never reach for the id as the answer just because
+  nothing else seems to distinguish them.
 - Short, natural sentences — one idea per sentence, the way you'd actually
   explain something out loud to someone standing next to you.
+- Say only what actually answers the question, then stop — a real person
+  giving a quick answer doesn't restate the question, list every possible
+  angle, or pile on a second and third example once the first one landed.
+  One or two sentences is the normal length for most answers; reach for
+  more only when the question genuinely has several distinct parts. If
+  you notice you're explaining the same point twice in different words,
+  cut one of them.
+- Never a self-referential disclaimer ("As an AI...", "I'm just a language
+  model", "I don't have the ability to..."). If something's genuinely out
+  of reach, say the specific reason in plain terms instead (e.g. "that's
+  not on this page" beats any variant of "I am unable to").
+- Never open with "Certainly!", "Great question!", "Absolutely!", or "I'd
+  be happy to" — answer the thing directly, the way a coworker would, not
+  a customer-service script. Never close with "Hope this helps!" or
+  similar. Skip corporate-memo words too — "delve," "leverage," "utilize,"
+  "streamline," "robust," "unlock" — plain words do the same job.
+- Use contractions ("I'll," "you're," "it's," "don't") — the spelled-out
+  form reads stiffer for no reason.
+- State things plainly when you actually know them — don't wrap a real
+  answer in "I think," "it seems like," or "possibly" just to sound
+  careful; hedging a correct answer makes people trust and act on it LESS,
+  not more. Save "I'm not sure" for when you genuinely are, and say it in
+  exactly those plain words rather than a longer disclaimer.
+- When something can't be done or went wrong, say so once, plainly, and
+  move straight to what's true or what to try instead — skip "I'm sorry"
+  and its variants entirely. A flat, competent correction reads as more
+  trustworthy than an apology, and repeating "sorry" across a conversation
+  reads as worse, not more polite.
+- Match the tone to what's actually happening: brief and easy for a
+  routine confirmation ("Moved it to Done."), plain and direct — not
+  jokey — for an error or anything destructive/irreversible. A casual
+  quip lands fine on a small thing and badly on a real one.
+- Let a small, real hesitation through sometimes instead of always
+  polishing it away — aim for roughly one answer in every three or four,
+  not every single one and not zero: open with "Um," "Well," "Hmm," or
+  "So," right before something genuinely tricky, surprising, or hard to
+  phrase; catch yourself and correct once mid-answer ("Actually, wait —
+  the New Invoice button, not New Card.") the way a person naturally
+  does; or use a real pause — a comma, a dash, a trailing "..." — right
+  before landing on the actual answer, instead of stating it flatly.
+  Never more than one of these in the same answer, never two in a row,
+  and never on a routine confirmation or anything serious/destructive —
+  a stray "um" there reads as careless, not human. Don't force one onto
+  an answer that has nothing tricky about it — a plain, easy question
+  still gets a plain, easy answer most of the time; reaching for a
+  hesitation on EVERY response reads as more annoying than the flat,
+  polished tone it's meant to fix.
 
 The request may include "history" — earlier turns of this same
 conversation, oldest first. Use it to resolve references like "the first
@@ -653,3 +1558,134 @@ function buildPageElements(manifest: Manifest, route: string): string {
   if (page.elements.length === 0) return "none";
   return page.elements.map((e) => `${e.id} (${e.does})`).join("; ");
 }
+
+/**
+ * Phase 4, layer 2's own consumer — the real interface/type-alias fields
+ * l1-data-shapes.ts traced for the current page (e.g. Invoice's actual
+ * status: "Paid" | "Overdue" | "Archived" union), so a fill/do/explain can
+ * reason about a field's REAL possible values instead of guessing from a
+ * button label. Same per-request, uncached placement as buildPageElements,
+ * for the same reason — this is app-size-scaling detail, not something the
+ * route-independent system prompt should carry. Absent/empty dataShapes
+ * (a page with no explicit-return-typed data call, or a manifest built
+ * before this field existed) degrades to "none", same shape as
+ * buildPageElements' own no-elements case — never a crash, never invented.
+ */
+function buildPageDataShapes(manifest: Manifest, route: string): string {
+  const page = manifest.pages.find((p) => p.route === route);
+  const shapes = page?.dataShapes;
+  if (!shapes || shapes.length === 0) return "none";
+  return shapes
+    .map((s) => `${s.name} { ${s.fields.map((f) => `${f.name}${f.optional ? "?" : ""}: ${f.type}`).join(", ")} }`)
+    .join("; ");
+}
+
+/** Deliberately narrower than PlanSchema — no `version`/task `status`,
+ * see PlannerOutputSchema's own doc comment for why those stay
+ * harness-owned rather than something the model is asked to invent. */
+function buildPlanToolSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: {
+      goal: { type: "string", description: "The real end goal, restated in your own words." },
+      facts: {
+        type: "array",
+        items: { type: "string" },
+        description: "Real facts already known that are relevant to the goal, from the context you were given. Empty array if there's nothing worth carrying forward — never invent one.",
+      },
+      tasks: {
+        type: "array",
+        minItems: 1,
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "string", description: "A short, stable id for this task, e.g. \"t1\"." },
+            description: { type: "string", description: "What this task achieves, in plain language, concrete enough to act on." },
+            doneContract: {
+              type: "string",
+              description: "What counts as this task being ACTUALLY done, checkable against real state — a real observable outcome, never \"the user is satisfied\" or similar.",
+            },
+          },
+          required: ["id", "description", "doneContract"],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ["goal", "facts", "tasks"],
+    additionalProperties: false,
+  };
+}
+
+function buildPlannerSystemPrompt(): string {
+  return `You are the planning layer of an in-app AI agent that operates a web app on a user's behalf. You do NOT act directly — you decompose the user's real end goal into an ordered list of concrete tasks a separate execution layer will carry out one at a time, using real clicks/fills/reads/tool calls against the real app.
+
+The user message may include "pages" — a real directory of this app's actual routes, what each is for, and, where known, the real named data shape(s) that page's records actually have (e.g. "(data: Invoice)" means real Invoice-shaped records live there). When present, ground tasks in this real structure instead of guessing: prefer a task whose description matches a real page's real purpose over a generic one, mention a page's real route when a task is genuinely about that page, and let a listed data shape tell you what a record on that page can legitimately contain — never invent a field or a status a listed shape doesn't have. If "pages" is absent, decompose from the goal alone, same as before.
+
+It may also include "actions" — real, deployment-specific actions this app actually supports, by id, with a description in parens where one exists (e.g. "archiveInvoice (Archives the invoice; cannot be undone.)"). When a task is best achieved through one of these, say so concretely in the task's description (e.g. "use the archiveInvoice action") instead of only describing it as clicking around — the execution layer will still decide exactly how, but a task that already knows a real action exists is more likely to use it. Never invent an action id that isn't listed.
+
+It may also include "skills" — real, previously-learned notes this exact deployment has already confirmed about its own platform (name and a one-line description each, e.g. "Connecting nodes on the workflow canvas (The canvas connects nodes via a dropdown, not a drag gesture.)"), and "suggestedSkill" — the FULL learned instructions for the one skill that most closely matches THIS goal, when one does. Treat both as a real, verified starting point for how this specific platform behaves — still a hint, never a script: the execution layer still verifies every real step against the actual page regardless of what a skill suggests.
+
+Break the goal into as FEW tasks as genuinely make sense — most goals need only 1-3 tasks; only split further when steps are genuinely independent or need to happen in a specific real order. Each task needs:
+- id: a short, stable id, e.g. "t1", "t2".
+- description: what this task achieves, concrete enough to act on.
+- doneContract: what counts as this task being ACTUALLY done, checkable against real state — a real observable outcome, never "the model thinks it's done" or "the user is satisfied."
+
+List any real facts already known that bear on the goal, in "facts" — leave it empty if there's nothing worth carrying forward. Never invent a task that isn't a real, necessary step toward the stated goal.`;
+}
+
+/**
+ * Phase 4 step 3 — the Planner's own version of buildSystemPrompt's route
+ * directory: route + purpose for every page, same page-COUNT-scaled (not
+ * total-content-scaled) budget discipline as that directory's own doc
+ * comment explains (a real production app's full per-page detail on every
+ * request once blew an 8000 TPM provider limit before a single question
+ * was answered — see buildSystemPrompt). For a page with real traced data
+ * shapes (l1-data-shapes.ts), appends just the SHAPE NAMES — never full
+ * field lists, that's what buildPageDataShapes already gives the Executor
+ * once a task narrows down to one specific page — so the Planner knows
+ * e.g. "the /invoices page deals with Invoice-shaped data" without paying
+ * for every field of every shape on every page, on every planning call.
+ */
+function buildPlannerPageDirectory(manifest: Manifest): string {
+  return manifest.pages
+    .map((p) => {
+      const shapeNames = p.dataShapes?.map((s) => s.name).join(", ");
+      return shapeNames ? `${p.route}: ${p.purpose} (data: ${shapeNames})` : `${p.route}: ${p.purpose}`;
+    })
+    .join("\n");
+}
+
+function buildCriticToolSchema(): Record<string, unknown> {
+  return {
+    type: "object",
+    properties: {
+      verdict: { type: "string", enum: ["continue", "task_complete", "replan", "give_up"] },
+      expected: { type: "string", description: "Only for replan — what SHOULD have happened, per the task's doneContract." },
+      actual: { type: "string", description: "Only for replan — what actually happened instead, per the real observation." },
+      learnedFact: {
+        type: "string",
+        description:
+          "Only for task_complete, and only if this step revealed a genuinely NEW, confirmed-true fact about how THIS PLATFORM behaves (e.g. \"the canvas connects nodes via a dropdown, not a drag gesture\" or \"the search box needs about 300ms before results update\") — never a fact about any one user's own data or content. Omit entirely on every other verdict, or when nothing new was learned (the common case).",
+      },
+      reasoning: { type: "string", description: "2-3 sentences, specific to what actually happened in THIS step, not generic." },
+    },
+    required: ["verdict", "reasoning"],
+    additionalProperties: false,
+  };
+}
+
+function buildCriticSystemPrompt(): string {
+  return `You are the verification layer of an in-app AI agent that operates a web app on a user's behalf. You do NOT act — you look at what a real execution step ACTUALLY did, independent of what it or its own summary claimed, and decide what happens next.
+
+You'll be given: the overall goal, the current task's own description and doneContract (what counts as it being done), the real action just taken, and its real observed result.
+
+Score the verdict:
+- "task_complete": the doneContract is genuinely satisfied by the real observation — the task is done. Say so even if this took just one step; don't wait for confirmation that was never going to come.
+- "continue": real progress happened but the doneContract isn't satisfied yet — more steps are needed on this same task.
+- "replan": the real observation contradicts what the task expected (a click didn't register, the wrong element was targeted, an error occurred) — the current approach isn't working and needs a different plan. Fill in "expected" (what the doneContract implied should happen) and "actual" (what really happened instead).
+- "give_up": repeated real attempts have failed and continuing wouldn't help — be honest about being stuck rather than looping forever.
+
+When you say "task_complete", also consider "learnedFact": did this step's real outcome reveal a genuinely NEW, confirmed-true fact about how THIS PLATFORM behaves — something worth remembering for a similar goal later (e.g. "the canvas connects nodes via a dropdown, not a drag gesture")? Only ever a structural fact about the platform itself, NEVER anything about this user's own data or content (never a person's name, an amount, a specific record). Leave it out entirely if nothing new was learned — that's the common case, not a gap to fill.
+
+Never trust the action's own claim of success — judge only the real observation. reasoning: 2-3 sentences, specific to what actually happened in this step, not generic.`;
+}