@prismatic-io/lux 0.0.1

package/src/cli/render/tty.ts

@@ -0,0 +1,314 @@
+/**
+ * Terminal primitives for the live runner. Hand-rolled: the CLI needs
+ * perhaps 40 lines of this, and a dependency here would have to ship as a
+ * runtime dep of the published package for the sake of its `bin`.
+ */
+
+// Assembled from a variable so the escape byte never appears as a literal
+// control character inside a regex or string constant.
+const ESC = String.fromCharCode(27);
+const ANSI_PATTERN = new RegExp(`${ESC}\\[[0-9;?]*[A-Za-z]`, "g");
+const ANSI_PREFIX = new RegExp(`^${ESC}\\[[0-9;?]*[A-Za-z]`);
+const RESET = `${ESC}[0m`;
+
+const CURSOR_HIDE = `${ESC}[?25l`;
+const CURSOR_SHOW = `${ESC}[?25h`;
+const ERASE_BELOW = `${ESC}[0J`;
+const cursorUp = (rows: number): string => (rows > 0 ? `${ESC}[${rows}A` : "");
+
+export const stripAnsi = (text: string): string => text.replace(ANSI_PATTERN, "");
+
+/**
+ * Code points we render that occupy two terminal cells. The CJK/emoji block
+ * ranges cover most of it; the explicit set is the handful of pre-emoji
+ * symbols (⚡ especially) that default to emoji presentation and therefore
+ * render wide despite living below U+1F300.
+ */
+const WIDE_SINGLETONS = new Set([0x231a, 0x231b, 0x23f0, 0x23f3, 0x26a1, 0x2705, 0x274c, 0x2b50]);
+
+const charWidth = (codePoint: number): number => {
+  if (WIDE_SINGLETONS.has(codePoint)) return 2;
+  if (codePoint >= 0x1100 && codePoint <= 0x115f) return 2;
+  if (codePoint >= 0x2e80 && codePoint <= 0xa4cf) return 2;
+  if (codePoint >= 0xac00 && codePoint <= 0xd7a3) return 2;
+  if (codePoint >= 0xf900 && codePoint <= 0xfaff) return 2;
+  if (codePoint >= 0xfe30 && codePoint <= 0xfe6f) return 2;
+  if (codePoint >= 0xff00 && codePoint <= 0xff60) return 2;
+  if (codePoint >= 0xffe0 && codePoint <= 0xffe6) return 2;
+  if (codePoint >= 0x1f300 && codePoint <= 0x1faff) return 2;
+  return 1;
+};
+
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+// Per-code-point counting over-counts ZWJ emoji sequences (a family emoji is
+// seven code points but one two-cell glyph), so width is measured per
+// grapheme cluster: any wide code point inside makes the whole cluster wide.
+const clusterWidth = (cluster: string): number => {
+  for (const char of cluster) {
+    if (charWidth(char.codePointAt(0) ?? 0) === 2) return 2;
+  }
+  return 1;
+};
+
+export const visibleWidth = (text: string): number => {
+  let width = 0;
+  for (const { segment } of graphemes.segment(stripAnsi(text))) width += clusterWidth(segment);
+  return width;
+};
+
+/**
+ * Cut `text` to `maxWidth` visible cells, counting styling as zero-width.
+ * A line wider than the terminal would wrap, and a wrapped line breaks the
+ * cursor arithmetic the live region depends on — so every painted row goes
+ * through here.
+ */
+export const truncate = (text: string, maxWidth: number): string => {
+  if (maxWidth <= 0) return "";
+  if (visibleWidth(text) <= maxWidth) return text;
+
+  let out = "";
+  let width = 0;
+  let index = 0;
+  let styled = false;
+
+  scan: while (index < text.length) {
+    if (text.startsWith(ESC, index)) {
+      const sequence = text.slice(index).match(ANSI_PREFIX)?.[0];
+      if (!sequence) break;
+      out += sequence;
+      styled = true;
+      index += sequence.length;
+      continue;
+    }
+    // Segment the plain-text run up to the next escape so a grapheme cluster
+    // is never split mid-sequence.
+    const nextEsc = text.indexOf(ESC, index);
+    const run = text.slice(index, nextEsc === -1 ? text.length : nextEsc);
+    for (const { segment } of graphemes.segment(run)) {
+      const next = width + clusterWidth(segment);
+      // Reserve one cell for the ellipsis.
+      if (next > maxWidth - 1) break scan;
+      out += segment;
+      width = next;
+    }
+    index += run.length;
+  }
+  return `${out}…${styled ? RESET : ""}`;
+};
+
+export type Theme = {
+  bold: (s: string) => string;
+  dim: (s: string) => string;
+  green: (s: string) => string;
+  red: (s: string) => string;
+  yellow: (s: string) => string;
+  cyan: (s: string) => string;
+  inverse: (s: string) => string;
+};
+
+const wrap =
+  (open: string, close: string) =>
+  (s: string): string =>
+    `${ESC}[${open}m${s}${ESC}[${close}m`;
+
+const plain = (s: string): string => s;
+
+export const makeTheme = (color: boolean): Theme =>
+  color
+    ? {
+        bold: wrap("1", "22"),
+        dim: wrap("2", "22"),
+        green: wrap("32", "39"),
+        red: wrap("31", "39"),
+        yellow: wrap("33", "39"),
+        cyan: wrap("36", "39"),
+        inverse: wrap("7", "27"),
+      }
+    : {
+        bold: plain,
+        dim: plain,
+        green: plain,
+        red: plain,
+        yellow: plain,
+        cyan: plain,
+        inverse: plain,
+      };
+
+/**
+ * Honour the two conventions users actually rely on: `NO_COLOR` to force
+ * plain output anywhere, `FORCE_COLOR` to keep colour through a pipe (CI
+ * log viewers that render ANSI).
+ */
+export const shouldColor = (stream: NodeJS.WriteStream, env: NodeJS.ProcessEnv): boolean => {
+  if (env.NO_COLOR) return false;
+  if (env.FORCE_COLOR) return env.FORCE_COLOR !== "0";
+  return Boolean(stream.isTTY);
+};
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const;
+
+export const spinnerFrame = (tick: number): string =>
+  SPINNER_FRAMES[tick % SPINNER_FRAMES.length] ?? "-";
+
+type Patched = {
+  stream: NodeJS.WriteStream;
+  original: (chunk: string) => void;
+  restore: () => void;
+};
+
+export type LiveRegionOptions = {
+  stdout?: NodeJS.WriteStream | undefined;
+  /** Force live painting on/off. Defaults to `stdout.isTTY`. */
+  live?: boolean | undefined;
+  frameIntervalMs?: number | undefined;
+};
+
+/**
+ * A block of lines pinned to the bottom of the terminal, repainted on a
+ * timer so elapsed clocks tick. Anything else that writes to the terminal
+ * while it is active is intercepted, printed *above* the block, and the
+ * block repainted underneath — otherwise a stray write lands mid-frame and
+ * every subsequent cursor-up is off by one. Off a TTY the whole mechanism
+ * collapses to plain `staticLine` writes.
+ */
+export class LiveRegion {
+  private readonly stdout: NodeJS.WriteStream;
+  private readonly writeRaw: (chunk: string) => void;
+  private readonly frameIntervalMs: number;
+  readonly live: boolean;
+
+  private renderFrame: () => string[] = () => [];
+  private paintedRows = 0;
+  private timer: NodeJS.Timeout | null = null;
+  private patched: Patched[] = [];
+  private held = new Map<NodeJS.WriteStream, string>();
+  private started = false;
+
+  constructor(options: LiveRegionOptions = {}) {
+    this.stdout = options.stdout ?? process.stdout;
+    // Captured before any interception, so the region's own paints never
+    // recurse back through the patched writer.
+    const original = this.stdout.write.bind(this.stdout);
+    this.writeRaw = (chunk) => {
+      original(chunk);
+    };
+    this.live = options.live ?? Boolean(this.stdout.isTTY);
+    this.frameIntervalMs = options.frameIntervalMs ?? 80;
+  }
+
+  start(renderFrame: () => string[]): void {
+    this.renderFrame = renderFrame;
+    if (!this.live || this.started) return;
+    this.started = true;
+    this.writeRaw(CURSOR_HIDE);
+    this.intercept(process.stderr);
+    this.timer = setInterval(() => this.repaint(), this.frameIntervalMs);
+    // Never let the repaint timer be the reason the process stays alive.
+    this.timer.unref();
+    // Interrupt handling belongs to the CLI, which has a run to unwind; the
+    // region only guarantees the cursor comes back however the process ends.
+    process.once("exit", this.onExit);
+    this.paint();
+  }
+
+  /**
+   * Print a permanent line above the live block. Before `start()` and after
+   * `stop()` there is no block to move, so the line goes straight out — which
+   * is also exactly the non-TTY behaviour.
+   */
+  staticLine(text: string): void {
+    if (!this.live || !this.started) {
+      this.writeRaw(`${text}\n`);
+      return;
+    }
+    this.clear();
+    this.writeRaw(`${text}\n`);
+    this.paint();
+  }
+
+  repaint(): void {
+    if (!this.live || !this.started) return;
+    this.clear();
+    this.paint();
+  }
+
+  stop(): void {
+    if (!this.live || !this.started) return;
+    this.started = false;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.clear();
+    for (const { stream, original, restore } of this.patched) {
+      const rest = this.held.get(stream);
+      if (rest) original(`${rest}\n`);
+      restore();
+    }
+    this.patched = [];
+    this.held.clear();
+    this.writeRaw(CURSOR_SHOW);
+    process.off("exit", this.onExit);
+  }
+
+  private readonly onExit = (): void => {
+    if (this.started) this.writeRaw(CURSOR_SHOW);
+  };
+
+  private clear(): void {
+    if (this.paintedRows === 0) return;
+    this.writeRaw(cursorUp(this.paintedRows) + ERASE_BELOW);
+    this.paintedRows = 0;
+  }
+
+  private paint(): void {
+    const columns = this.stdout.columns ?? 80;
+    const maxRows = Math.max(1, (this.stdout.rows ?? 24) - 1);
+    const lines = this.renderFrame()
+      .slice(-maxRows)
+      .map((line) => truncate(line, columns - 1));
+    if (lines.length === 0) return;
+    this.writeRaw(lines.map((line) => `${line}\n`).join(""));
+    this.paintedRows = lines.length;
+  }
+
+  /**
+   * Buffer a foreign stream to whole lines before letting it through: a
+   * half-written line cannot be painted over cleanly, and the subprocess
+   * driver relays agent stderr in arbitrary chunks.
+   */
+  private intercept(stream: NodeJS.WriteStream): void {
+    if (!stream.isTTY) return;
+    const original = stream.write.bind(stream);
+    const emit = (chunk: string): void => {
+      original(chunk);
+    };
+    const patched = (
+      chunk: string | Uint8Array,
+      encoding?: unknown,
+      callback?: unknown,
+    ): boolean => {
+      const done = typeof encoding === "function" ? encoding : callback;
+      const text = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf-8");
+      const buffered = (this.held.get(stream) ?? "") + text;
+      const lastBreak = buffered.lastIndexOf("\n");
+      if (lastBreak === -1) {
+        this.held.set(stream, buffered);
+      } else {
+        this.held.set(stream, buffered.slice(lastBreak + 1));
+        this.clear();
+        emit(buffered.slice(0, lastBreak + 1));
+        this.paint();
+      }
+      if (typeof done === "function") (done as () => void)();
+      return true;
+    };
+    stream.write = patched as unknown as typeof stream.write;
+    this.patched.push({
+      stream,
+      original: emit,
+      restore: () => {
+        stream.write = original as typeof stream.write;
+      },
+    });
+  }
+}

package/src/cli/run-options.ts

@@ -0,0 +1,82 @@
+import { InvalidArgumentError } from "commander";
+
+export type RunOptions = {
+  tag?: string[];
+  loop?: number;
+  concurrency?: number;
+  list?: boolean;
+  listTags?: boolean;
+  interactive?: boolean;
+  claudeAnswerer?: boolean;
+  runsRoot?: string;
+  profile?: string;
+  subjectRoot?: string;
+  verbose?: boolean;
+};
+
+export const collectTags = (value: string, previous: string[]): string[] =>
+  previous.concat(
+    value
+      .split(",")
+      .map((tag) => tag.trim())
+      .filter(Boolean),
+  );
+
+export const collectValues = (value: string, previous: string[]): string[] => [...previous, value];
+
+export const parseAnnotationAssertion = (
+  value: string,
+): [string, { passed: boolean; score?: number }] => {
+  const match = /^(.+)=(pass|fail)(?::(.+))?$/.exec(value);
+  if (!match?.[1] || !match[2]) {
+    throw new InvalidArgumentError("--assertion must use id=pass, id=fail, or id=pass:0.8 syntax");
+  }
+  const score = match[3] === undefined ? undefined : parseUnitInterval(match[3]);
+  return [
+    match[1],
+    {
+      passed: match[2] === "pass",
+      ...(score !== undefined ? { score } : {}),
+    },
+  ];
+};
+
+export const parsePositiveInt = (value: string): number => {
+  // Number() rejects partial numbers such as "3abc" and "2.9".
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new InvalidArgumentError("must be a positive integer");
+  }
+  return parsed;
+};
+
+export const parseUnitInterval = (value: string): number => {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new InvalidArgumentError("must be a number between 0 and 1");
+  }
+  return parsed;
+};
+
+export const resolveConcurrency = (
+  options: Pick<RunOptions, "concurrency" | "interactive" | "claudeAnswerer">,
+  configured: number,
+): { concurrency: number; note?: string } => {
+  const requested = options.concurrency ?? configured;
+  let liveFlag: "--interactive" | "--claude-answerer" | null = null;
+  if (options.interactive) liveFlag = "--interactive";
+  else if (options.claudeAnswerer) liveFlag = "--claude-answerer";
+  if (liveFlag && requested > 1) {
+    return {
+      concurrency: 1,
+      note: `lux: ${liveFlag} is a live session; running one case at a time (ignoring concurrency ${requested})\n`,
+    };
+  }
+  return { concurrency: requested };
+};
+
+export const resolveAnswererOverride = (options: RunOptions): string | undefined => {
+  if (options.interactive) return "terminal";
+  if (options.claudeAnswerer) return "claude-code";
+  return undefined;
+};

package/src/cli/skills.ts

@@ -0,0 +1,129 @@
+import { lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+
+const PlatformSchema = z.enum(["claude", "claude-code", "codex", "all"]);
+export type SkillsPlatform = z.infer<typeof PlatformSchema>;
+const SkillNameSchema = z.enum(["lux", "lux-answerer"]);
+export type BundledSkillName = z.infer<typeof SkillNameSchema>;
+
+const InstallSkillsOptionsSchema = z
+  .object({
+    cwd: z.string().min(1),
+    platform: PlatformSchema,
+    project: z.boolean().default(false),
+    dir: z.string().min(1).optional(),
+    name: SkillNameSchema.optional(),
+  })
+  .strict();
+
+export interface InstalledSkill {
+  name: BundledSkillName;
+  platform: "claude-code" | "codex";
+  path: string;
+}
+
+const BUNDLED_SKILLS = [
+  {
+    name: "lux",
+    description: "Author and drive coding-agent evals with Lux",
+    platforms: ["claude-code", "codex"],
+  },
+  {
+    name: "lux-answerer",
+    description: "Play a simulated user for a running Lux eval",
+    platforms: ["claude-code"],
+  },
+] as const satisfies readonly {
+  name: BundledSkillName;
+  description: string;
+  platforms: readonly ("claude-code" | "codex")[];
+}[];
+
+export const formatSkillsList = (): string =>
+  BUNDLED_SKILLS.map(
+    ({ name, description, platforms }) => `${name}\t${description}\t${platforms.join(",")}`,
+  ).join("\n");
+
+const targetsFor = (
+  platform: SkillsPlatform,
+  cwd: string,
+  project: boolean,
+  dir?: string,
+  name?: BundledSkillName,
+): (InstalledSkill & { source: string })[] => {
+  const platforms =
+    platform === "all"
+      ? (["claude-code", "codex"] as const)
+      : ([platform === "claude" ? "claude-code" : platform] as const);
+  const scopeRoot = project ? resolve(cwd) : homedir();
+  const skills = name ? BUNDLED_SKILLS.filter((skill) => skill.name === name) : BUNDLED_SKILLS;
+  return platforms.flatMap((platformName) =>
+    skills
+      .filter((skill) =>
+        (skill.platforms as readonly ("claude-code" | "codex")[]).includes(platformName),
+      )
+      .map((skill) => ({
+        name: skill.name,
+        platform: platformName,
+        source: fileURLToPath(new URL(`../../skills/${skill.name}`, import.meta.url)),
+        path: dir
+          ? join(resolve(dir), skill.name)
+          : join(
+              scopeRoot,
+              platformName === "claude-code" ? ".claude" : ".codex",
+              "skills",
+              skill.name,
+            ),
+      })),
+  );
+};
+
+const copySkillDirectory = async (source: string, target: string): Promise<void> => {
+  const sourceInfo = await lstat(source);
+  if (!sourceInfo.isDirectory() || sourceInfo.isSymbolicLink()) {
+    throw new Error(`lux skills: bundled skill source is not a real directory: ${source}`);
+  }
+  await mkdir(target, { recursive: true });
+  for (const entry of await readdir(source, { withFileTypes: true })) {
+    const sourcePath = join(source, entry.name);
+    const targetPath = join(target, entry.name);
+    if (entry.isSymbolicLink()) {
+      throw new Error(`lux skills: bundled skill contains a symbolic link: ${sourcePath}`);
+    }
+    if (entry.isDirectory()) {
+      await copySkillDirectory(sourcePath, targetPath);
+    } else if (entry.isFile()) {
+      await mkdir(dirname(targetPath), { recursive: true });
+      await writeFile(targetPath, await readFile(sourcePath));
+    } else {
+      throw new Error(`lux skills: bundled skill contains an unsupported entry: ${sourcePath}`);
+    }
+  }
+};
+
+export const installSkills = async (
+  options: z.input<typeof InstallSkillsOptionsSchema>,
+): Promise<InstalledSkill[]> => {
+  const parsed = InstallSkillsOptionsSchema.parse(options);
+  const targets = targetsFor(parsed.platform, parsed.cwd, parsed.project, parsed.dir, parsed.name);
+  if (targets.length === 0) {
+    throw new Error(
+      `lux skills: '${parsed.name}' is not available for platform '${parsed.platform}'`,
+    );
+  }
+  for (const target of targets) await copySkillDirectory(target.source, target.path);
+  return targets.map(({ source: _, ...installed }) => installed);
+};
+
+export const formatSkillsInstall = (installed: InstalledSkill[], cwd: string): string =>
+  installed
+    .map(
+      ({ name, platform, path }) =>
+        `installed ${name} skill for ${platform} at ${
+          relative(cwd, path).split(sep).join("/") || "."
+        }`,
+    )
+    .join("\n");

package/src/core/annotation.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { formatZodIssues } from "./zod.js";
+
+const ExpectedBooleanLabelSchema = z
+  .object({
+    passed: z.boolean(),
+    score: z.number().min(0).max(1).optional(),
+  })
+  .strict();
+
+export const GraderAnnotationSchema = z
+  .object({
+    /** Stable label identity within the dataset. */
+    id: z.string().min(1),
+    /** Persisted Lux run containing the evidence to grade. */
+    runDir: z.string().min(1),
+    /** Candidate-relative declarative rubric whose assertions grade this run. */
+    rubricPath: z
+      .string()
+      .min(1)
+      .transform((path) => path.replaceAll("\\", "/")),
+    /** Optional selection labels used by experiment split selectors. */
+    tags: z.array(z.string()).default([]),
+    expected: z
+      .object({
+        casePassed: z.boolean().optional(),
+        caseScore: z.number().min(0).max(1).optional(),
+        assertions: z.record(z.string(), ExpectedBooleanLabelSchema).default({}),
+      })
+      .strict(),
+    /** Whether the label was independently authored or generated as test data. */
+    source: z.enum(["human", "synthetic"]),
+    annotator: z.string().min(1).optional(),
+    labeledAt: z.string().datetime().optional(),
+    reviewer: z.string().min(1).optional(),
+    /** Human rationale supplied to the rubric optimizer on mismatches. */
+    feedback: z.string().optional(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+  .superRefine((annotation, ctx) => {
+    if (
+      annotation.expected.casePassed === undefined &&
+      annotation.expected.caseScore === undefined &&
+      Object.keys(annotation.expected.assertions).length === 0
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["expected"],
+        message: "annotation requires a case pass/score label or at least one assertion label",
+      });
+    }
+    if (
+      annotation.rubricPath.startsWith("/") ||
+      annotation.rubricPath.split(/[\\/]/).includes("..")
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["rubricPath"],
+        message: "rubricPath must stay within the experiment subject root",
+      });
+    }
+    if (!annotation.rubricPath.toLowerCase().endsWith(".json")) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["rubricPath"],
+        message: "grader experiments require a declarative .json rubric",
+      });
+    }
+  });
+export type GraderAnnotation = z.output<typeof GraderAnnotationSchema>;
+
+export const GraderAnnotationDatasetSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    annotations: z.array(GraderAnnotationSchema).min(1),
+    meta: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+  .superRefine((dataset, ctx) => {
+    const ids = new Set<string>();
+    for (const [index, annotation] of dataset.annotations.entries()) {
+      if (ids.has(annotation.id)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["annotations", index, "id"],
+          message: `duplicate annotation id '${annotation.id}'`,
+        });
+      }
+      ids.add(annotation.id);
+    }
+  });
+export type GraderAnnotationDatasetInput = z.input<typeof GraderAnnotationDatasetSchema>;
+export type GraderAnnotationDataset = z.output<typeof GraderAnnotationDatasetSchema>;
+
+export const defineGraderAnnotations = (
+  input: GraderAnnotationDatasetInput,
+): GraderAnnotationDataset => {
+  const parsed = GraderAnnotationDatasetSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new Error(`Invalid Lux grader annotations: ${formatZodIssues(parsed.error)}`);
+  }
+  return parsed.data;
+};

package/src/core/answerer.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import type { Answer, Interrupt } from "./events.js";
+import { type TokenUsage, TokenUsageSchema } from "./usage.js";
+
+export type AnswerHistoryEntry = {
+  interrupt: Interrupt;
+  answer: Answer;
+  durationMs: number;
+};
+
+export type AnswererContext = {
+  persona: string | null;
+  prompt: string;
+  history: AnswerHistoryEntry[];
+  runDir: string;
+  /**
+   * Fires when the run is being torn down. Answerers that spawn subprocesses
+   * or block on external input must abandon the in-flight answer, or a
+   * Ctrl-C leaves billable agent calls running past the run's end.
+   */
+  abortSignal?: AbortSignal;
+  /**
+   * Persists a model-attempt start before a model-backed answerer invokes its
+   * provider.
+   */
+  recordModelAttemptStart?: (kind: "answerer") => Promise<string>;
+  /**
+   * Atomically settles one model-backed answer and re-checks campaign limits
+   * before another interrupt may invoke the provider.
+   */
+  recordModelAttemptComplete?: (
+    attemptId: string,
+    accounting: AnswererModelCallAccounting,
+  ) => Promise<void>;
+};
+
+export const AnswererModelCallAccountingSchema = z
+  .object({
+    usage: TokenUsageSchema,
+    costUsd: z.number().nonnegative().optional(),
+    unpricedModelCalls: z.number().int().nonnegative(),
+  })
+  .strict();
+export type AnswererModelCallAccounting = z.infer<typeof AnswererModelCallAccountingSchema>;
+
+export const AnswererModelAccountingSchema = z
+  .object({
+    calls: z.number().int().nonnegative(),
+    reportedCostUsd: z.number().nonnegative(),
+    unpricedModelCalls: z.number().int().nonnegative(),
+  })
+  .strict();
+export type AnswererModelAccounting = z.infer<typeof AnswererModelAccountingSchema>;
+
+export interface Answerer {
+  prepare(ctx: AnswererContext): Promise<void>;
+  /**
+   * Must settle within a bounded time (every bundled answerer enforces its
+   * own wait budget). Drivers pause their idle clock while a question is
+   * outstanding — the user's thinking time is not the agent's — so an
+   * answer() that never settles hangs the run until its abort signal fires.
+   */
+  answer(interrupt: Interrupt, ctx: AnswererContext): Promise<Answer>;
+  close(): Promise<void>;
+  /** Tokens spent playing the user, accumulated across every answer. */
+  usage?(): TokenUsage;
+  /** Model calls made by the answerer, kept separate from the subject driver. */
+  modelAccounting?(): AnswererModelAccounting;
+}
+
+export type AnswererPlugin<Cfg = unknown> = {
+  name: string;
+  configSchema?: z.ZodTypeAny;
+  create: (config: Cfg) => Answerer | Promise<Answerer>;
+};