@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/spoken-summary/agent.ts

@@ -19,7 +19,7 @@
  * The first three are ordinary step work. The fourth was impossible until two
  * things existed, and they are what this template is the reference use of:
  *
- * - **`stepSpeak`** (`@alexkroman1/aai/utils`) synthesizes from inside a step.
+ * - **`stepSpeak`** (`@alexkroman1/aai/step`) synthesizes from inside a step.
  *   The session TTS surface cannot be used here at all: a `TtsSession` is an
  *   event stream wired into a live pipeline's playback, with a turn tracker and
  *   barge-in behind it, and a step has no turn to be part of and has to return
@@ -76,8 +76,9 @@
 
 import { workflow, workflowApp } from "@alexkroman1/aai";
 import { ASSEMBLYAI_TTS_DEFAULT_VOICE, ASSEMBLYAI_TTS_VOICES } from "@alexkroman1/aai/tts";
+import type { WorkflowDef } from "@alexkroman1/aai/workflow-api";
 import { z } from "zod";
-import { spokenSummaryFlow } from "./workflows/summarize.ts";
+import { type SpokenSummary, spokenSummaryFlow } from "./workflows/summarize.ts";
 
 /**
  * The voices the form offers.
@@ -102,28 +103,40 @@ const VOICES = Object.entries(ASSEMBLYAI_TTS_VOICES)
  */
 const [FIRST_VOICE = ASSEMBLYAI_TTS_DEFAULT_VOICE, ...OTHER_VOICES] = VOICES;
 
+/**
+ * The run input, as its own const.
+ *
+ * Named rather than inline because {@link spokenSummary} carries an explicit
+ * type, and that annotation is what lets `workflows/summarize.ts` name
+ * `WorkflowInputOf<typeof spokenSummary>` for its body's parameter: the body's
+ * own signature would otherwise be part of what infers this declaration's type,
+ * and TypeScript refuses the cycle (`TS7022`).
+ */
+const spokenSummaryInput = z.object({
+  // A plain string, because an upload id is what the run really receives.
+  // What makes it a file picker rather than a text box is the `uploads` line
+  // below.
+  recording: z.string().describe("A recording to summarize — WAV, MP3 or M4A"),
+  // An enum, so the form renders a SELECT rather than a text box — which is
+  // the whole reason the list is derived above rather than left free-form.
+  // Optional, so the SDK's own default voice applies when nobody chooses.
+  voice: z
+    .enum([FIRST_VOICE, ...OTHER_VOICES])
+    .optional()
+    .describe("Voice to read the summary in"),
+});
+
 /**
  * The declaration: schema, description, and the directive body.
  *
  * Exported so `WorkflowOutputOf<typeof spokenSummary>` names the output type in
  * one place — including from `client.tsx`, where `import type` is erased and so
- * bundles nothing server-side.
+ * bundles nothing server-side — and so `workflows/summarize.ts` can name
+ * `WorkflowInputOf<typeof spokenSummary>` for the body's parameter.
  */
-export const spokenSummary = workflow({
+export const spokenSummary: WorkflowDef<typeof spokenSummaryInput, SpokenSummary> = workflow({
   description: "Transcribe a recording, summarize it, and read the summary back as audio",
-  input: z.object({
-    // A plain string, because an upload id is what the run really receives.
-    // What makes it a file picker rather than a text box is the `uploads` line
-    // below.
-    recording: z.string().describe("A recording to summarize — WAV, MP3 or M4A"),
-    // An enum, so the form renders a SELECT rather than a text box — which is
-    // the whole reason the list is derived above rather than left free-form.
-    // Optional, so the SDK's own default voice applies when nobody chooses.
-    voice: z
-      .enum([FIRST_VOICE, ...OTHER_VOICES])
-      .optional()
-      .describe("Voice to read the summary in"),
-  }),
+  input: spokenSummaryInput,
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and
   // the step that transcribes it reads it back with `readUpload`.

package/dist/templates/spoken-summary/client.tsx

@@ -36,18 +36,19 @@ import "@alexkroman1/aai-ui/styles.css";
 // ERASED at build time, so naming the agent's own type costs the browser bundle
 // nothing — and it is what stops this file restating a shape
 // `workflows/summarize.ts` already declares.
-import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import { formatDuration } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   createWorkflowApi,
   Form,
   page,
   SubmitButton,
   UploadProgressBar,
+  useDownloadUrl,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useEffect, useState } from "react";
 import type { spokenSummary } from "./agent.ts";
 
 /** What a completed run reports, derived from the workflow rather than restated. */
@@ -84,58 +85,16 @@ function captionsUrl(text: string, durationMs: number): string {
   return `data:text/vtt;charset=utf-8,${encodeURIComponent(vtt)}`;
 }
 
-/** Seconds a person can read, from the milliseconds a run reports. */
-function duration(ms: number): string {
-  const total = Math.round(ms / 1000);
-  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
-}
-
-/**
- * The finished run's audio, as something the browser will play.
- *
- * A hook rather than four lines in the component because the CLEANUP is the
- * part worth keeping in one place: an object URL pins its blob for the life of
- * the document, so it is revoked when the id changes and when the page goes
- * away. The `cancelled` flag covers the other half — a second run settling
- * while the first download is still in flight would otherwise set state from
- * the stale one.
- */
-function useAudioUrl(uploadId: string | undefined): { url?: string; error?: string } {
-  const [state, setState] = useState<{ url?: string; error?: string }>({});
-
-  useEffect(() => {
-    if (uploadId === undefined) {
-      setState({});
-      return;
-    }
-    let cancelled = false;
-    let objectUrl: string | undefined;
-    api
-      .download(uploadId)
-      .then((blob) => {
-        if (cancelled) return;
-        objectUrl = URL.createObjectURL(blob);
-        setState({ url: objectUrl });
-      })
-      .catch((err: unknown) => {
-        if (!cancelled) setState({ error: err instanceof Error ? err.message : String(err) });
-      });
-    return () => {
-      cancelled = true;
-      if (objectUrl !== undefined) URL.revokeObjectURL(objectUrl);
-    };
-  }, [uploadId]);
-
-  return state;
-}
-
 export function App() {
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`.
   const { submit, run, pending, upload, pauseUpload, resumeUpload, error } =
     useWorkflowSubmit<Summary>(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
-  const audio = useAudioUrl(output?.audio);
+  // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
+  // bytes have to be FETCHED and handed to the element as an object URL — and the
+  // object URL has to be revoked, which is the half a page written by hand forgets.
+  const audio = useDownloadUrl(output?.audio, { api });
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
@@ -169,7 +128,7 @@ export function App() {
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
             <p className="text-sm opacity-70">
-              {output.source} · {duration(output.durationMs)} · {output.words} words
+              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
             </p>
           </div>
 
@@ -181,8 +140,9 @@ export function App() {
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
-              Read aloud · {duration(output.audioDurationMs)}
+              Read aloud · {formatDuration(output.audioDurationMs)}
             </h3>
+            {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
               <p className="text-red-600">Could not load the audio: {audio.error}</p>
             )}

package/dist/templates/spoken-summary/workflows/summarize.ts

@@ -24,7 +24,7 @@
  *   run. The bytes go to the store, the output carries the id, and the page
  *   turns it back into something to play with `api.download(id)`.
  *
- * Both are on `@alexkroman1/aai/utils`, imported from THERE rather than the
+ * Both are on `@alexkroman1/aai/step`, imported from THERE rather than the
  * root: a `workflows/*.ts` module is bundled separately by the WDK builder, so
  * the root barrel's module graph would ride into the step bundle.
  *
@@ -49,19 +49,17 @@
  * expensive one.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import {
-  omitUndefined,
-  report,
-  stepGenerateJson,
-  stepSpeak,
-  TRANSCRIBE_API,
-  writeUpload,
-} from "@alexkroman1/aai/utils";
+import { report, stepSpeak, TRANSCRIBE_API, writeUpload } from "@alexkroman1/aai/step";
+import { stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { countWords, omitUndefined } from "@alexkroman1/aai/utils";
+// ERASED at build time, so the body can name the schema's own output type without
+// a runtime cycle back through `agent.ts` — the same mechanism `client.tsx` uses
+// for `WorkflowOutputOf`.
+import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
 import { sleep } from "workflow";
 import { z } from "zod";
+import type { spokenSummary } from "../agent.ts";
 import {
-  countWords,
   createJob,
   MAX_POLLS,
   POLL_INTERVAL,
@@ -128,13 +126,9 @@ export type SpokenSummary = {
 };
 
 /** Transcribe a recording, summarize it, and read the summary back. */
-export async function spokenSummaryFlow(input: {
-  recording: string;
-  // `| undefined` explicitly, not merely optional: `exactOptionalPropertyTypes`
-  // is on repo-wide, and what a zod `.optional()` infers is a property that may
-  // be PRESENT and undefined.
-  voice?: string | undefined;
-}): Promise<SpokenSummary> {
+export async function spokenSummaryFlow(
+  input: WorkflowInputOf<typeof spokenSummary>,
+): Promise<SpokenSummary> {
   "use workflow";
 
   const transcript = await transcribe(input.recording);
@@ -188,7 +182,7 @@ export async function summarize(
   "use step";
 
   await report("Summarizing the transcript.");
-  const reply = await stepGenerateJson(
+  const reply = await stepGenerateJsonClassified(
     "Summarize this transcript of a recording.\n\n" +
       "Answer with JSON only, in this shape:\n" +
       `{"headline": "...", "points": ["..."], "spoken": "..."}\n\n` +
@@ -204,9 +198,10 @@ export async function summarize(
       system: "You summarize recordings. You answer with JSON and nothing else.",
       schema: SummaryReply,
     },
-    // Classified off the gateway's own status: a 429 is worth another attempt
-    // and a 400 is not, and `throwStepError` is what tells the DevKit which.
-  ).catch(throwStepError);
+    // The `Classified` caller is `stepGenerateJson` plus `throwStepError`, which
+    // reads the gateway's own status: a 429 is worth another attempt and a 400
+    // is not, and that is what tells the DevKit which.
+  );
 
   return { headline: reply.headline, points: reply.points.slice(0, POINTS), spoken: reply.spoken };
 }

package/dist/templates/spoken-summary/workflows/transcribe.ts

@@ -12,7 +12,8 @@
  *
  * **Every one of them is four lines, because the SDK owns the endpoint.**
  * `stepTranscribeUpload` / `stepTranscribeSubmit` / `stepTranscribePoll` on
- * `@alexkroman1/aai/utils` carry the URL, the raw-key auth, the windowed
+ * `@alexkroman1/aai/step` — reached here through their `*Classified` callers on
+ * `@alexkroman1/aai/step-errors` — carry the URL, the raw-key auth, the windowed
  * streaming upload, the PLURAL `speech_models` field and the failure
  * classification — all of which this file used to spell out, and all of which
  * `transcription-workflow` used to spell out again, differently worded and
@@ -37,14 +38,13 @@
  * the one leg that should be as boring as possible.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
+import { report, uploadInfo } from "@alexkroman1/aai/step";
 import {
-  report,
-  stepTranscribePoll,
-  stepTranscribeSubmit,
-  stepTranscribeUpload,
-  uploadInfo,
-} from "@alexkroman1/aai/utils";
+  stepTranscribePollClassified,
+  stepTranscribeSubmitClassified,
+  stepTranscribeUploadClassified,
+} from "@alexkroman1/aai/step-errors";
+import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 
 /** How long between polls of a submitted job. */
 export const POLL_INTERVAL = "10s";
@@ -79,16 +79,20 @@ export type Transcript = {
  * expires before the next step runs; that costs one fresh upload, once, instead
  * of five.
  *
- * `.catch(throwStepError)` is what turns the SDK's `TranscribeError` into the
- * DevKit's verdict — a missing key and a 400 stop, a 429 waits as long as the
- * service asked. Every step here ends the same way for the same reason.
+ * The `Classified` callers on `@alexkroman1/aai/step-errors` are the SDK's own
+ * `stepTranscribe*` plus `throwStepError` and nothing else, which is what turns
+ * the SDK's `TranscribeError` into the DevKit's verdict — a missing key and a
+ * 400 stop, a 429 waits as long as the service asked. Every step here ends the
+ * same way for the same reason.
  */
 export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
   "use step";
 
   const stored = await uploadInfo(uploadId);
-  await report(`Uploading ${stored.name || uploadId} (${mb(stored.size)}) for transcription.`);
-  return await stepTranscribeUpload(uploadId).catch(throwStepError);
+  await report(
+    `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) for transcription.`,
+  );
+  return await stepTranscribeUploadClassified(uploadId);
 }
 
 /** Retries beyond the default 3: an upload is the one call here worth another attempt. */
@@ -98,7 +102,7 @@ uploadToProvider.maxRetries = 5;
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
   "use step";
 
-  const job = await stepTranscribeSubmit(audioUrl).catch(throwStepError);
+  const job = await stepTranscribeSubmitClassified(audioUrl);
   await report(`Transcribing — job ${job.id}.`);
   return job;
 }
@@ -118,7 +122,7 @@ export async function pollTranscript(
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
   "use step";
 
-  const progress = await stepTranscribePoll(id).catch(throwStepError);
+  const progress = await stepTranscribePollClassified(id);
   if (!progress.done) return { done: false };
 
   const stored = await uploadInfo(uploadId);
@@ -132,14 +136,3 @@ export async function pollTranscript(
     },
   };
 }
-
-/** Words in a transcript, for the counts a page shows. */
-export function countWords(text: string): number {
-  const trimmed = text.trim();
-  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
-}
-
-/** A size a person can read, because the number that matters is the scale. */
-function mb(bytes: number): string {
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}

package/dist/templates/support-line/agent.test.ts

@@ -1,10 +1,9 @@
 /// <reference types="vite/client" />
 
-import type { GenerateFn, ToolContext } from "@alexkroman1/aai";
 import {
   createToolContext,
-  runTool,
   stubGenerate,
+  toolRunner,
   withDiscoveredTools,
 } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
@@ -23,7 +22,7 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { MAX_ATTEMPTS, runCorrectiveRag } from "./graph.ts";
+import { MAX_ATTEMPTS, runCorrectiveRag } from "./procedure.ts";
 import {
   ANSWER_SYSTEM,
   ANSWERS_SYSTEM,
@@ -95,15 +94,11 @@ function scriptedModel(script: Script = {}) {
   return { generate, calls };
 }
 
-function makeCtx(generate: GenerateFn, sessionId?: string) {
-  return createToolContext({ generate, ...(sessionId ? { sessionId } : {}) });
-}
-
-/** A tool by the name the model calls it by, bound to this agent. The lookup
- *  and its "no such tool" message are `runTool`'s (`@alexkroman1/aai/testing`);
- *  what is local is only which agent they run against. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
-  runTool(agentDef, name, args, ctx);
+/** A tool by the name the model calls it by, bound to this agent. The lookup,
+ *  its "no such tool" message and the args-or-context shape are all
+ *  `toolRunner`'s (`@alexkroman1/aai/testing`); what is local is only which
+ *  agent it runs against. */
+const run = toolRunner(agentDef);
 
 /** Node names without the per-call suffix, for sequence assertions. */
 function nodes(calls: string[]): string[] {
@@ -254,7 +249,7 @@ describe("answer_question", () => {
       relevant: (id) => id === "D8",
       answers: ["Area outages are on the status page, and rebooting will not help."],
     });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     const result = (await run("answer_question", { question: "is there an outage" }, ctx)) as {
       answer: string;
       sources: string[];
@@ -276,7 +271,7 @@ describe("answer_question", () => {
 
   test("with nothing grounded it returns no answer and points at the ticket", async () => {
     const { generate } = scriptedModel({ relevant: () => false });
-    const ctx = makeCtx(generate);
+    const ctx = createToolContext({ generate });
     const result = (await run("answer_question", { question: "do you sell phones" }, ctx)) as {
       answer: null;
       guidance: string;
@@ -302,8 +297,8 @@ describe("answer_question", () => {
     // session ids would prove nothing extra, and `sessionSlot` could stop
     // keying by session with this still passing.
     const { generate } = scriptedModel({ relevant: (id) => id === "D2", answers: ["Reboot it."] });
-    const first = makeCtx(generate);
-    const second = makeCtx(generate);
+    const first = createToolContext({ generate });
+    const second = createToolContext({ generate });
 
     await run("answer_question", { question: "how do I reboot" }, first);
     expect(supportSlot.get(second).trace).toBeNull();

package/dist/templates/support-line/agent.ts

@@ -3,7 +3,7 @@ import { PRODUCT, supportProjection } from "./shared.ts";
 
 /**
  * A support line that grades its own retrieval before it speaks — the
- * self-RAG / CRAG graph, ported to voice. `graph.ts` holds the loop, `prompts.ts`
+ * self-RAG / CRAG graph, ported to voice. `procedure.ts` holds the loop, `prompts.ts`
  * the attribution and the graders, `shared.ts` the knowledge base and why its
  * retriever is lexical.
  *

package/dist/templates/support-line/client.tsx

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
+import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
 import { PRODUCT, supportProjection } from "./shared.ts";
 
 /**
@@ -11,12 +11,11 @@ import { PRODUCT, supportProjection } from "./shared.ts";
  * support line nobody can tell apart from one that just guesses well.
  */
 function TraceSidebar() {
-  const theme = useTheme();
   const support = useAgentState(supportProjection);
   const trace = support.trace;
 
   return (
-    <div className="flex h-full min-h-0 flex-col gap-4 p-4" style={{ color: theme.text }}>
+    <div className="flex h-full min-h-0 flex-col gap-4 p-4 text-aai-text">
       <div>
         <h3 className="text-sm font-bold uppercase tracking-wide opacity-60">{support.product}</h3>
         <p className="text-xs opacity-50">
@@ -36,7 +35,7 @@ function TraceSidebar() {
           scrollClassName="min-h-0 overflow-y-auto"
           contentClassName="flex flex-col gap-4 pr-1"
         >
-          <div className="rounded-lg p-3" style={{ background: theme.surface }}>
+          <div className="rounded-lg p-3 bg-aai-surface">
             <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Question</p>
             <p className="text-sm">{trace.question}</p>
             {trace.rewrites > 0 && (
@@ -54,10 +53,11 @@ function TraceSidebar() {
             {trace.docs.map((doc) => (
               <div
                 key={doc.id}
-                className="flex items-start gap-2 rounded-lg p-2"
-                style={{ background: theme.surface, opacity: doc.relevant ? 1 : 0.5 }}
+                className={`flex items-start gap-2 rounded-lg p-2 bg-aai-surface ${
+                  doc.relevant ? "" : "opacity-50"
+                }`}
               >
-                <span style={{ color: doc.relevant ? theme.primary : theme.text }}>
+                <span className={doc.relevant ? "text-aai-primary" : "text-aai-text"}>
                   {doc.relevant ? "✓" : "×"}
                 </span>
                 <div className="min-w-0">
@@ -69,7 +69,7 @@ function TraceSidebar() {
           </div>
 
           <div className="flex flex-col gap-1">
-            <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Graph</p>
+            <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Procedure</p>
             {trace.steps.map((entry, index) => (
               // Steps are append-only within a run, so the index is stable.
               <p key={`${index}-${entry.node}`} className="text-xs">
@@ -79,7 +79,7 @@ function TraceSidebar() {
             ))}
           </div>
 
-          <div className="rounded-lg p-3" style={{ background: theme.surface }}>
+          <div className="rounded-lg p-3 bg-aai-surface">
             <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Verdict</p>
             {trace.answer ? (
               <p className="text-sm">{trace.answer}</p>

package/dist/templates/support-line/nodes.ts

@@ -0,0 +1,100 @@
+/**
+ * The CRAG nodes' BODIES — one model call each, and nothing about routing.
+ *
+ * Split from `procedure.ts` when that file became an actual machine: the machine
+ * there declares which node runs next, and these are what each node does. The
+ * seam is worth having beyond the line count — everything here is a plain async
+ * function of its arguments, so a spec can drive one directly, and the machine
+ * holds no prompt text at all.
+ */
+
+import type { GenerateFn } from "@alexkroman1/aai";
+import {
+  ANSWER_SYSTEM,
+  ANSWERS_SYSTEM,
+  binaryScore,
+  DOC_GRADER_SYSTEM,
+  GROUNDED_SYSTEM,
+  REWRITE_SYSTEM,
+} from "./prompts.ts";
+import type { Doc, GradedDoc } from "./shared.ts";
+import { formatDoc } from "./shared.ts";
+
+/** A closed verdict from one of the graders. */
+export interface Verdict {
+  pass: boolean;
+  reason: string;
+}
+
+/** `grade_documents` — one closed question per document, all at once. */
+export async function gradeDocuments(
+  generate: GenerateFn,
+  question: string,
+  docs: readonly Doc[],
+): Promise<GradedDoc[]> {
+  return await Promise.all(
+    docs.map(async (doc) => {
+      const { object } = await generate({
+        system: DOC_GRADER_SYSTEM,
+        prompt: `Caller's question: ${question}\n\nDocument:\n${formatDoc(doc)}`,
+        schema: binaryScore,
+      });
+      return {
+        id: doc.id,
+        title: doc.title,
+        relevant: object.score === "yes",
+        reason: object.reason,
+      };
+    }),
+  );
+}
+
+/** `transform_query` — their question re-writer, aimed at a keyword index. */
+export async function transformQuery(generate: GenerateFn, question: string): Promise<string> {
+  const { text } = await generate({
+    system: REWRITE_SYSTEM,
+    prompt: `Caller's question: ${question}`,
+  });
+  const rewritten = text.trim().replace(/^["']|["']$/g, "");
+  // A rewriter that returns nothing usable must not empty the query — that
+  // would retrieve zero documents and read as "we have nothing on this".
+  return rewritten.length > 0 ? rewritten : question;
+}
+
+/** `generate` — the answer, from the graded-relevant documents only. */
+export async function generateAnswer(
+  generate: GenerateFn,
+  question: string,
+  docs: readonly Doc[],
+): Promise<string> {
+  const { text } = await generate({
+    system: ANSWER_SYSTEM,
+    prompt: `Documents:\n\n${docs.map(formatDoc).join("\n\n")}\n\nCaller's question: ${question}`,
+  });
+  return text.trim();
+}
+
+/** The two generation graders — same closed question, different subject. */
+async function grade(generate: GenerateFn, system: string, prompt: string): Promise<Verdict> {
+  const { object } = await generate({ system, prompt, schema: binaryScore });
+  return { pass: object.score === "yes", reason: object.reason };
+}
+
+/** `grade_generation_v_documents` — is the answer IN the documents? */
+export async function gradeGrounded(
+  generate: GenerateFn,
+  docs: readonly Doc[],
+  answer: string,
+): Promise<Verdict> {
+  const facts = docs.map(formatDoc).join("\n\n");
+  return await grade(generate, GROUNDED_SYSTEM, `Facts:\n\n${facts}\n\nAnswer: ${answer}`);
+}
+
+/** `grade_generation_v_question` — grounded is not the same as useful. */
+export async function gradeUseful(
+  generate: GenerateFn,
+  question: string,
+  answer: string,
+): Promise<Verdict> {
+  return await grade(generate, ANSWERS_SYSTEM, `Question: ${question}\n\nAnswer: ${answer}`);
+}