@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.10

package/src/skill-loader.ts

@@ -0,0 +1,288 @@
+/** Resolve named preloaded skills through Pi's configured resource discovery. */
+
+import { type Dirent, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadSkills, type ResolvedResource, SettingsManager, type SettingsManager as SettingsManagerType } from "@earendil-works/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
+import { createHomePackageManager } from "./resource-loader.js";
+
+/** Discovery is inspect-only: missing sources are never installed or activated. */
+const skipMissingSource = async (): Promise<"skip"> => "skip";
+
+export interface PreloadedSkill {
+  name: string;
+  content: string;
+}
+
+export interface SkillPreloadOptions {
+  agentDir: string;
+  settingsManager: SettingsManagerType;
+  homeDir?: string;
+}
+
+/**
+ * Load named skills through Pi, retaining the preloader's legacy user roots.
+ *
+ * Pi owns configured package discovery, parsing, trust, and missing-package
+ * handling. A second untrusted manager exposes the user/package candidates
+ * which Pi's realpath collapse can hide behind a rejected project symlink.
+ */
+export async function preloadSkills(
+  skillNames: string[],
+  cwd: string,
+  options: SkillPreloadOptions,
+): Promise<PreloadedSkill[]> {
+  if (skillNames.length === 0) return [];
+  const primary = createHomePackageManager({ cwd, agentDir: options.agentDir, settingsManager: options.settingsManager }, options.homeDir);
+  const primaryResources = await primary.resolve(skipMissingSource);
+  const fallbackSettings = SettingsManager.create(cwd, options.agentDir, { projectTrusted: false });
+  const fallback = createHomePackageManager({ cwd, agentDir: options.agentDir, settingsManager: fallbackSettings }, options.homeDir);
+  const fallbackResources = await fallback.resolve(skipMissingSource);
+
+  const rejectedProjectPaths = new Set(primaryResources.skills
+    .filter(resource => isTier(resource, "project") && isSymlinkedProjectSkill(resource, cwd))
+    .map(resource => canonicalPath(resource.path)));
+  // A path that cannot be canonicalized never matches, so it is never restored.
+  const isBehindRejectedAlias = (resource: ResolvedResource): boolean => {
+    const canonical = canonicalPath(resource.path);
+    return canonical !== undefined && rejectedProjectPaths.has(canonical);
+  };
+  // Package candidates collapsed behind a rejected project alias, resolved with
+  // Pi's own project package filters applied.
+  const aliasFreeSkills = rejectedProjectPaths.size === 0 ? [] : await resolveAliasFreePackageSkills(cwd, options);
+  const recoveredPackages = aliasFreeSkills.filter(isBehindRejectedAlias);
+
+  // Resolve native disabled paths through Pi's parser, preserving every filter form it supports.
+  const disabledNames = new Set(loadTier(
+    [...primaryResources.skills, ...fallbackResources.skills, ...recoveredPackages].filter(resource => !resource.enabled),
+    cwd,
+    options.agentDir,
+  ).map(skill => skill.name));
+  const project = discoveredSkills(
+    primaryResources.skills.filter(resource => resource.enabled && isTier(resource, "project") && !isSymlinkedProjectSkill(resource, cwd)),
+    cwd,
+    options.agentDir,
+  );
+  const user = discoveredSkills(
+    [
+      ...primaryResources.skills,
+      // Only restore a user candidate Pi collapsed behind a rejected project alias.
+      // Other fallback user resources could bypass Pi's project filters.
+      ...fallbackResources.skills.filter(isBehindRejectedAlias),
+    ].filter(resource => resource.enabled && isTier(resource, "user") && !isAmbientUserAgentsSkill(resource, options.homeDir)),
+    cwd,
+    options.agentDir,
+  );
+  const packages = discoveredSkills(
+    [
+      ...primaryResources.skills,
+      // Only restore a package candidate Pi collapsed behind a rejected project alias.
+      ...recoveredPackages,
+    ].filter(resource => resource.enabled && isTier(resource, "package") && !isAmbientUserAgentsSkill(resource, options.homeDir)),
+    cwd,
+    options.agentDir,
+  );
+
+  // Historical user roots, including their raw top-level `<name>.md` lookup.
+  const home = resolve(options.homeDir ?? homedir());
+  const legacyUserRoots = [join(options.agentDir, "skills"), join(home, ".agents", "skills"), join(home, ".pi", "skills")];
+  return skillNames.map(name => {
+    const native = project.get(name) ?? user.get(name) ?? packages.get(name);
+    const content = native
+      ?? (disabledNames.has(name)
+        ? undefined
+        : (options.settingsManager.isProjectTrusted() ? findInRoots(projectSkillRoots(cwd).map(root => join(root, "skills")), name, false) : undefined)
+          ?? findInRoots(legacyUserRoots, name, true));
+    return { name, content: content ?? `(Skill "${name}" not found in Pi's configured skill resources)` };
+  });
+}
+
+/** Precedence tier of a resolved skill: top-level project or user resources, or package resources. */
+function isTier(resource: ResolvedResource, tier: "project" | "user" | "package"): boolean {
+  return tier === "package" ? resource.metadata.origin === "package" : resource.metadata.origin === "top-level" && resource.metadata.scope === tier;
+}
+
+/** Absolutize an existing local project package source, which Pi resolves against `<cwd>/.pi`. */
+function absolutizeProjectSource(source: string, cwd: string): string {
+  const local = resolve(cwd, ".pi", source);
+  return !source.startsWith("npm:") && existsSync(local) ? local : source;
+}
+
+/**
+ * Resolve package skills as Pi would, minus the project's top-level skill dirs.
+ *
+ * Pi collapses resources by realpath, so a rejected project symlink can hide a
+ * package skill together with the project package filter that applies to it.
+ * Resolving from an empty scratch cwd, with the real project settings and
+ * npm/git install roots carried over, keeps Pi as the owner of those filters.
+ */
+async function resolveAliasFreePackageSkills(cwd: string, options: SkillPreloadOptions): Promise<ResolvedResource[]> {
+  const scratch = mkdtempSync(join(tmpdir(), "skill-preload-"));
+  try {
+    for (const dir of ["npm", "git"]) {
+      const real = join(cwd, ".pi", dir);
+      if (!existsSync(real)) continue;
+      mkdirSync(join(scratch, ".pi"), { recursive: true });
+      symlinkSync(real, join(scratch, ".pi", dir), "dir");
+    }
+    const project = options.settingsManager.getProjectSettings();
+    const settings = {
+      global: options.settingsManager.getGlobalSettings(),
+      project: { ...project, packages: project.packages?.map(pkg => typeof pkg === "string"
+        ? absolutizeProjectSource(pkg, cwd)
+        : { ...pkg, source: absolutizeProjectSource(pkg.source, cwd) }) },
+    };
+    // Pi's public storage seam replaces the scratch cwd's settings with the real
+    // ones. `normalizeHomeResourceSettings` cannot: it only rewrites a manager's
+    // own settings, and `createHomePackageManager` still applies it on top.
+    const settingsManager = SettingsManager.fromStorage(
+      { withLock: (scope, read) => void read(JSON.stringify(settings[scope])) },
+      { projectTrusted: options.settingsManager.isProjectTrusted() },
+    );
+    const manager = createHomePackageManager({ cwd: scratch, agentDir: options.agentDir, settingsManager }, options.homeDir);
+    return (await manager.resolve(skipMissingSource)).skills.filter(resource => resource.metadata.origin === "package");
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/** Parse resolved skill paths with Pi's own loader and validation. */
+function loadTier(resources: ResolvedResource[], cwd: string, agentDir: string): ReturnType<typeof loadSkills>["skills"] {
+  return loadSkills({ cwd, agentDir, skillPaths: resources.map(resource => resource.path), includeDefaults: false }).skills;
+}
+
+/** Load Pi-valid skills from a precedence tier, retaining the first declared name. */
+function discoveredSkills(resources: ResolvedResource[], cwd: string, agentDir: string): Map<string, string> {
+  return new Map(loadTier(resources, cwd, agentDir).map(skill => [skill.name, readFileSync(skill.filePath, "utf-8").trim()]));
+}
+
+/** Find a named legacy skill under roots in order without broadening Pi discovery. */
+function findInRoots(roots: string[], name: string, trusted: boolean): string | undefined {
+  if (isUnsafeName(name)) return undefined;
+  for (const root of roots) {
+    const content = findInRoot(root, name, trusted);
+    if (content !== undefined) return content;
+  }
+  return undefined;
+}
+
+/** Match the former preloader's flat-file and recursive Agent Skills lookup. */
+function findInRoot(root: string, name: string, trusted: boolean): string | undefined {
+  if (!trusted && isPathThroughSymlink(dirname(root), root)) return undefined;
+  const flat = readSkillFile(join(root, `${name}.md`), trusted)?.trim();
+  if (flat !== undefined) return flat;
+  if (!existsSync(root)) return undefined;
+
+  const queue = [root];
+  const seen = new Set<string>();
+  // `root` passed the symlink check above and every queued directory passed it before it was
+  // pushed, so `current` needs no second check. Iteration visits entries pushed meanwhile, in order.
+  for (const current of queue) {
+    if (trusted) {
+      const canonical = canonicalPath(current);
+      // A directory raced away since it was queued has nothing left to read.
+      if (canonical === undefined || seen.has(canonical)) continue;
+      seen.add(canonical);
+    }
+    let entries: Dirent<string>[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => Number(left.name > right.name) - Number(left.name < right.name));
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const path = join(current, entry.name);
+      if (!trusted && isPathThroughSymlink(dirname(root), path)) continue;
+      const isDirectory = entry.isDirectory() || (trusted && entry.isSymbolicLink() && isDirectoryTarget(path));
+      if (!isDirectory) continue;
+      const skillFile = join(path, "SKILL.md");
+      if (existsSync(skillFile)) {
+        const content = entry.name === name ? readSkillFile(skillFile, trusted)?.trim() : undefined;
+        if (content !== undefined) return content;
+        continue;
+      }
+      queue.push(path);
+    }
+  }
+  return undefined;
+}
+
+function readSkillFile(path: string, trusted: boolean): string | undefined {
+  if (!trusted) return safeReadFile(path);
+  try {
+    return statSync(path).isFile() ? readFileSync(path, "utf-8") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isDirectoryTarget(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Match Pi's realpath identity without importing its private path utility.
+ *
+ * Unlike Pi, an uncanonicalizable path (raced away, EACCES) yields undefined
+ * rather than the raw path, so it can never match a rejected alias. That is
+ * also why `realOrSelf` in `package-resources.ts` is not reused: it falls back
+ * to the realpath of the nearest existing parent.
+ */
+function canonicalPath(path: string): string | undefined {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Exclude Pi's ambient user root when a caller supplies a distinct injected home. */
+export function isAmbientUserAgentsSkill(resource: ResolvedResource, homeDir?: string, runtimeHome = homedir()): boolean {
+  if (homeDir === undefined || resource.metadata.scope !== "user" || resource.metadata.source !== "auto") return false;
+  const injectedRoot = join(resolve(homeDir), ".agents", "skills");
+  return !isPathWithin(injectedRoot, resource.path) && isPathWithin(join(runtimeHome, ".agents", "skills"), resource.path);
+}
+
+/** Reject project symlinks before accepting their resources or resolving collisions. Callers pass project-tier resources only. */
+function isSymlinkedProjectSkill(resource: ResolvedResource, cwd: string): boolean {
+  return projectSkillRoots(cwd).some(root => isPathThroughSymlink(root, resource.path));
+}
+
+/** Match Pi's project skill roots while checking their parent directories too. */
+function projectSkillRoots(cwd: string): string[] {
+  const roots = [join(cwd, ".pi")];
+  let directory = resolve(cwd);
+  while (true) {
+    roots.push(join(directory, ".agents"));
+    if (existsSync(join(directory, ".git"))) break;
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  return roots;
+}
+
+/** Textual containment. Unlike `isInside` in `package-resources.ts`, it must not canonicalize: that would erase the symlinks callers look for. */
+function isPathWithin(root: string, path: string): boolean {
+  const relativePath = relative(resolve(root), resolve(path));
+  return relativePath === "" || (!relativePath.startsWith(`..${sep}`) && relativePath !== ".." && !isAbsolute(relativePath));
+}
+
+function isPathThroughSymlink(root: string, path: string): boolean {
+  const absoluteRoot = resolve(root);
+  if (!isPathWithin(absoluteRoot, path)) return false;
+  const relativePath = relative(absoluteRoot, resolve(path));
+  let current = absoluteRoot;
+  if (isSymlink(current)) return true;
+  for (const segment of relativePath.split(sep)) {
+    current = join(current, segment);
+    if (isSymlink(current)) return true;
+  }
+  return false;
+}

package/src/stale-ctx.ts

@@ -0,0 +1,16 @@
+/**
+ * stale-ctx.ts -- recognising pi's "extension ctx is stale" failure.
+ *
+ * pi invalidates an extension runner on reload and on session replacement
+ * (/new, /fork, /resume). Anything that still reaches the old runner or its
+ * `pi` throws this message (#145).
+ */
+
+/** Matched on the stable prefix of core's message. */
+export const STALE_CTX_RE = /extension ctx is stale after session replacement or reload/i;
+
+/** Whether `error` (an `Error` or a message string) is the stale-ctx failure. */
+export function isStaleCtxError(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  return STALE_CTX_RE.test(message);
+}

package/src/startup-error.ts

@@ -0,0 +1,29 @@
+/**
+ * startup-error.ts — bridge to the host SDK's optional `ExtensionStartupError`.
+ *
+ * A `session_start` handler that throws `ExtensionStartupError` makes the host
+ * fail the bind (no provider request, nonzero exit in the CLI modes). Hosts
+ * predating that class export nothing of the sort, and this package's peer
+ * range still admits them, so the class cannot be a static named import: on an
+ * older host the import would fail to link and take the whole extension down
+ * with an opaque error. The namespace is probed at runtime instead, and callers
+ * that need the fatal path refuse clearly when it is absent.
+ */
+
+import * as hostSdk from "@earendil-works/pi-coding-agent";
+
+/** Shape of the host's `ExtensionStartupError`: a normal `Error` constructor. */
+export type StartupErrorConstructor = new (message: string, options?: ErrorOptions) => Error;
+
+function isStartupErrorConstructor(value: unknown): value is StartupErrorConstructor {
+  return typeof value === "function" && value.prototype instanceof Error;
+}
+
+/**
+ * The host's `ExtensionStartupError` class, or `undefined` on a host that does
+ * not export one. `sdk` defaults to the real host module; tests pass a stand-in.
+ */
+export function hostStartupErrorClass(sdk: object = hostSdk): StartupErrorConstructor | undefined {
+  const candidate: unknown = Reflect.get(sdk, "ExtensionStartupError");
+  return isStartupErrorConstructor(candidate) ? candidate : undefined;
+}

package/src/status-note.ts

@@ -0,0 +1,113 @@
+/**
+ * status-note.ts — Honest framing for an agent result: the parenthetical status
+ * note for a non-normal outcome, and the salvaged partial output of a failure.
+ *
+ * Lives here rather than in an index.ts closure because both entry points need
+ * it — the top-level tools and the nested delegation tools, which can't import
+ * from index.ts (that is the extension entry, and it already reaches these tools
+ * through agent-runner).
+ */
+
+import type { AgentRecord } from "./types.js";
+
+/** Who stopped a `stopped` record: the spawning agent, or (unset) a human. */
+type StoppedBy = AgentRecord["stoppedBy"];
+
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff. A stop the parent itself made with `stop_subagent`
+ * (`stoppedBy: "parent"`) is stated plainly instead: shouting a human
+ * intervention that never happened would misreport its own decision back to it.
+ */
+export function getStatusNote(status: string, stoppedBy?: StoppedBy): string {
+  switch (status) {
+    case "stopped":
+      return stoppedBy === "parent"
+        ? " (stopped by the parent with stop_subagent before completion — output is partial; the task was NOT finished)"
+        : " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+    case "aborted":
+      return " (aborted — hit the turn limit before completion; output may be incomplete)";
+    case "steered":
+      return " (wrapped up at the turn limit — output may be partial)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Foreground variant of `getStatusNote`. A foreground caller is in a different
+ * position from a background one, so it needs different text:
+ *
+ *   - It already holds the agent's ENTIRE output inline, whereas the background
+ *     notification carries a 500-char preview. So only here can we truthfully
+ *     say there is nothing more to fetch — which is the whole point, because
+ *   - it has no agent id. The id travels in the tool result's renderer
+ *     `details`, which is never serialized to the model. A parent that reads
+ *     "output may be partial" as "truncated, go retrieve the rest" therefore
+ *     has nothing valid to call `get_subagent_result` with, and will invent an
+ *     id (#174).
+ *
+ * Only the lead clause varies between the three, and each variation carries
+ * information: `wrapped up` vs `aborted` tells the parent whether the output is
+ * a considered final answer or a fragment, and `stopped` shouts because a human
+ * intervening outranks everything else in the string. Only `steered` hedges on
+ * completion — it was told to wrap up and did, so it may well have finished at
+ * the limit; an aborted run blew through its grace turns while still working,
+ * and `stopped` can only fire on a running agent, so neither ever delivered a
+ * final answer. Identical confidence gets identical wording: phrasing one fact
+ * two ways invites a hunt for a distinction that isn't there.
+ *
+ * Every clause is a statement about state, never an instruction to act, and
+ * `get_subagent_result` is never named — naming the tool we steer away from only
+ * raises its salience. Two instructions were tried here and cut: "re-spawn with
+ * a higher max_turns" (pushes a fresh multi-minute run to save one wasted tool
+ * call) and, on `stopped`, "ask before restarting it" (restates the lead, and
+ * presumes someone is present to ask — false under `pi -p`, in scheduled jobs,
+ * and in any background-driven run). Nothing here can measure whether wording
+ * improves parent behavior, so removing a false cue (which cannot induce new
+ * behavior) and adding an instruction (which can) are not equally safe bets.
+ * Don't add either back without a way to measure it.
+ */
+export function getForegroundOutcomeNote(status: string, stoppedBy?: StoppedBy): string {
+  switch (status) {
+    case "stopped":
+      return stoppedBy === "parent"
+        ? " (stopped by the parent with stop_subagent — everything the agent produced is above; the task is unfinished)"
+        : " (STOPPED BY THE USER — everything the agent produced is above; the task is unfinished)";
+    case "aborted":
+      return " (aborted at the turn limit — everything the agent produced is above; the task is unfinished)";
+    case "steered":
+      return " (wrapped up at the turn limit — everything the agent produced is above; the task may be unfinished)";
+    default:
+      return "";
+  }
+}
+
+/**
+ * For an `error` run whose session survived, the hint that resuming it
+ * continues the work, naming the agent; "" otherwise. A provider or auth
+ * failure (e.g. a credential helper that failed transiently, #456) ends the
+ * turn but keeps the whole transcript, so the parent should resume the agent
+ * rather than re-spawn it and repay its context. A run that never got a
+ * session has nothing to resume.
+ */
+export function resumeHint(record: Pick<AgentRecord, "id" | "status" | "session">): string {
+  return record.status === "error" && record.session
+    ? `transcript intact; resume agent ${record.id} to continue`
+    : "";
+}
+
+/**
+ * Salvaged partial output of a failed run, as a labeled suffix for the error
+ * surfaces (or "" if the run produced nothing). `record.result` is bounded to
+ * the run's own turns, so this is never a stale earlier answer (#144).
+ */
+export function partialOutputSuffix(record: AgentRecord): string {
+  const partial = record.result?.trim();
+  return partial ? `\n\nPartial output before the failure:\n${partial}` : "";
+}

package/src/structured-output.ts

@@ -0,0 +1,130 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CompiledSchema } from "./workflow/json-schema.js";
+
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+
+/** What the child produced, filled in as the tool is called. */
+export interface StructuredCapture {
+  /** The last payload that validated, canonicalised. Absent until one does. */
+  json?: string;
+  /** Why the most recent attempt was rejected, for the retry prompt. */
+  lastError?: string;
+  /** Whether the tool was called at all — "never tried" reads differently. */
+  called: boolean;
+}
+
+export function createStructuredCapture(): StructuredCapture {
+  return { called: false };
+}
+
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export function createStructuredOutputTool(
+  compiled: CompiledSchema,
+  capture: StructuredCapture,
+): ToolDefinition {
+  return defineTool({
+    name: STRUCTURED_OUTPUT_TOOL_NAME,
+    label: "Structured Output",
+    description:
+      "Report your final answer. Call this exactly once, with the complete result, and put everything the "
+      + "caller needs inside the arguments — text written outside this call is discarded. If a call is "
+      + "rejected for not matching the schema, fix the reported fields and call it again.",
+    promptSnippet: "Report your final answer as structured data",
+    promptGuidelines: [
+      "Your final answer MUST be reported by calling StructuredOutput. Prose outside that call is discarded.",
+    ],
+    // The caller's schema *is* the tool's input schema, verbatim — that is what
+    // makes the provider fill the fields. pi types this as TypeBox's `TSchema`,
+    // which v1 defines as an open interface, so a plain JSON Schema satisfies
+    // it without a cast at runtime or a conversion at author time.
+    parameters: compiled.schema as never,
+    // "prefer", not "require": a provider that cannot constrain sampling should
+    // fall through to validation-and-retry rather than fail the call outright.
+    constrainedSampling: { type: "json_schema", strict: "prefer" },
+    // Models occasionally send the whole payload as one JSON string instead of
+    // an object. Recovering that costs nothing and saves a whole retry.
+    prepareArguments: (args: unknown) => {
+      if (typeof args !== "string") return args as never;
+      try {
+        return JSON.parse(args) as never;
+      } catch {
+        return args as never;
+      }
+    },
+    execute: async (_toolCallId, params) => {
+      capture.called = true;
+      const verdict = compiled.check(params);
+      if (verdict !== true) {
+        capture.lastError = verdict;
+        // `isError` puts the reason in front of the model as a tool result, so
+        // it can correct itself inside this same run. This is where most
+        // mismatches are resolved; the prompt-level retry is the backstop.
+        return {
+          content: [{
+            type: "text",
+            text: `StructuredOutput did not match the required schema:\n${verdict}\nCall it again with a corrected value.`,
+          }],
+          isError: true,
+          details: {},
+        };
+      }
+      // Last valid call wins: a model that calls twice meant the second one.
+      capture.json = JSON.stringify(params);
+      capture.lastError = undefined;
+      return { content: [{ type: "text", text: "Recorded." }], details: {} };
+    },
+  }) as ToolDefinition;
+}
+
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export function structuredRetryPrompt(capture: StructuredCapture): string {
+  const reason = capture.called && capture.lastError !== undefined
+    ? `Your last ${STRUCTURED_OUTPUT_TOOL_NAME} call did not match the required schema: ${capture.lastError}`
+    : `You did not call ${STRUCTURED_OUTPUT_TOOL_NAME}, so your answer was not recorded.`;
+  return `${reason}\n\nCall ${STRUCTURED_OUTPUT_TOOL_NAME} now with your complete final answer. Do not reply with prose.`;
+}