@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -0,0 +1,138 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The first leg: the uploaded recording becomes text.
+ *
+ * Three steps and a durable wait, over AssemblyAI's ASYNC transcription API:
+ *
+ * ```text
+ *   uploadToProvider   one step   →  the file, streamed, and the URL it answered
+ *   createJob          one step   →  the transcript id
+ *   pollTranscript     one step + a durable sleep, until the text comes back
+ * ```
+ *
+ * **Every one of them is four lines, because the SDK owns the endpoint.**
+ * `stepTranscribeUpload` / `stepTranscribeSubmit` / `stepTranscribePoll` on
+ * `@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
+ * identical in behaviour. What is left here is what is genuinely this app's:
+ * which steps to cut the job into, how long to wait, and what to report.
+ *
+ * ## The steps are still OURS, and they have to be
+ *
+ * The SDK cannot ship a `"use step"`: the Workflow DevKit's builder transforms
+ * exactly the files under this `workflows/` directory, so a directive inside a
+ * dependency would be transformed by nothing and would run inline with no
+ * journal and no retry, silently. The SDK owns what happens INSIDE a step; the
+ * boundaries — which is to say, what gets journaled and what a retry repeats —
+ * are the app's.
+ *
+ * **The async API rather than the sync one, and the choice is about the FORM.**
+ * The sync endpoint (`stepTranscribeSync`) answers inside the request and pays
+ * for it with a hard 120-second, 40 MB cap, so a longer recording has to be cut
+ * into segments and fanned out — which is a whole subject, and it has a
+ * template (`transcription-workflow`, which shows that cut three ways and
+ * measures them). This app's subject is the ROUND TRIP, so the transcription is
+ * the one leg that should be as boring as possible.
+ */
+
+import { report, uploadInfo } from "@alexkroman1/aai/step";
+import {
+  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";
+
+/**
+ * Polls before the run gives up on a job.
+ *
+ * At {@link POLL_INTERVAL} this is an hour, well past what the async API takes
+ * for any recording it accepts. Bounded rather than endless because a job that
+ * never leaves `queued` is a run that would otherwise be replayed forever.
+ */
+export const MAX_POLLS = 360;
+
+/** What the first leg hands the second. */
+export type Transcript = {
+  /** The FILENAME the uploader gave, not the opaque id — this reaches the page. */
+  source: string;
+  /** The provider's own measurement of the recording, in milliseconds. */
+  durationMs: number;
+  /** What was said. */
+  text: string;
+};
+
+/**
+ * Upload the recording to the provider and answer with the URL it gave.
+ *
+ * Its OWN step, and that is a measurement rather than a preference: folded into
+ * the submit, a fault in the JSON body — a deprecated field, a bad model name —
+ * makes the DevKit retry the whole step and re-upload the recording on every
+ * attempt. A retry that repeats the expensive half to fix the cheap half is not
+ * a retry. The `upload_url` is short-lived, so the risk being taken is that it
+ * expires before the next step runs; that costs one fresh upload, once, instead
+ * of five.
+ *
+ * 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} (${formatBytes(stored.size)}) for transcription.`,
+  );
+  return await stepTranscribeUploadClassified(uploadId);
+}
+
+/** Retries beyond the default 3: an upload is the one call here worth another attempt. */
+uploadToProvider.maxRetries = 5;
+
+/** Create the transcription job, and answer with the id that outlives this run. */
+export async function createJob(audioUrl: string): Promise<{ id: string }> {
+  "use step";
+
+  const job = await stepTranscribeSubmitClassified(audioUrl);
+  await report(`Transcribing — job ${job.id}.`);
+  return job;
+}
+
+/**
+ * Ask once whether the job has finished, and read it when it has.
+ *
+ * One request answers both, which is the SDK's doing and worth knowing: this
+ * used to poll for a status and then fetch the identical URL a second time for
+ * the text. The body still branches on `done` rather than on a status string —
+ * a provider's vocabulary must not be interpreted in a body, where a new status
+ * would read as "not finished yet" forever.
+ */
+export async function pollTranscript(
+  uploadId: string,
+  id: string,
+): Promise<{ done: false } | { done: true; transcript: Transcript }> {
+  "use step";
+
+  const progress = await stepTranscribePollClassified(id);
+  if (!progress.done) return { done: false };
+
+  const stored = await uploadInfo(uploadId);
+  await report(`Transcribed ${countWords(progress.transcript.text)} words.`);
+  return {
+    done: true,
+    transcript: {
+      source: stored.name || uploadId,
+      durationMs: progress.transcript.durationMs,
+      text: progress.transcript.text,
+    },
+  };
+}

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}`);
+}