@alexkroman1/aai-cli 6.10.0 → 6.11.0

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

@@ -0,0 +1,225 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The page: a form, a progress log, a summary, and a player.
+ *
+ * `link-digest` shows these primitives raw and `transcription-workflow` shows
+ * the form layer in full; neither is restated here. What this page adds is the
+ * one thing a workflow app could not do before — **playing a file the RUN
+ * produced.**
+ *
+ * ## An upload id is not a URL, and `api.download` is why
+ *
+ * The run's output carries `audio`, which is an upload id in the agent's own
+ * store. The obvious next line is `<audio src={`/workflows/uploads/${id}`}>`,
+ * and it is wrong in a way that only shows up after a deploy: the byte route
+ * takes the same `Authorization` header every other route does, and neither
+ * `<audio src>` nor `<a href>` can send one. So a page built on a URL works
+ * against `aai dev`, where there is no token, and 401s the moment the agent has
+ * one.
+ *
+ * `api.download(id)` reads it with the header and answers a `Blob`;
+ * `URL.createObjectURL` turns that into something both elements take. The
+ * object URL is REVOKED when the run changes, which is not tidiness — an object
+ * URL pins its blob for the life of the document, so a page that summarized
+ * five recordings would be holding five files it can no longer reach.
+ *
+ * ## The form is DECLARED, not written
+ *
+ * There is no field markup here at all. `<WorkflowFields>` renders a control
+ * per property of the workflow's own input schema, read from `GET /workflows` —
+ * so the file picker exists because `agent.ts` declares `recording` in
+ * `uploads`, and the voice SELECT exists because it declares `voice` as an
+ * enum. Adding a field there adds a control here with no edit.
+ */
+
+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 {
+  createWorkflowApi,
+  Form,
+  page,
+  SubmitButton,
+  UploadProgressBar,
+  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. */
+type Summary = WorkflowOutputOf<typeof spokenSummary>;
+
+/**
+ * The workflow's name, as a page starts a run by one.
+ *
+ * A rename in `agent.ts` is a runtime 400 rather than a compile error, which is
+ * why `agent.test.ts` pins this string.
+ */
+const WORKFLOW = "spokenSummary";
+
+/**
+ * Hoisted out of the component deliberately.
+ *
+ * The hooks hold the client in a ref precisely so a fresh object per render
+ * cannot restart their watch, but building one in render is still a new `fetch`
+ * closure every time and reads as though it were free.
+ */
+const api = createWorkflowApi();
+
+/**
+ * The spoken text as a one-cue WebVTT track, inline.
+ *
+ * A data URL rather than another stored file: the words are already on the page
+ * and the whole track is a few hundred bytes, so a second upload — and a second
+ * `download` round trip to read it — would buy nothing.
+ */
+function captionsUrl(text: string, durationMs: number): string {
+  // `hh:mm:ss.mmm`, which is the only timestamp shape WebVTT accepts.
+  const end = new Date(durationMs).toISOString().slice(11, 23);
+  const vtt = `WEBVTT\n\n00:00:00.000 --> ${end}\n${text}\n`;
+  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);
+
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
+      <header className="flex flex-col gap-1">
+        <h1 className="text-2xl font-medium">Spoken Summary</h1>
+        <p className="text-sm opacity-70">
+          Upload a recording. It comes back summarized — in writing, and read aloud.
+        </p>
+      </header>
+
+      <Form onSubmit={submit} error={error} className="flex flex-col gap-4">
+        {/* Every control, from the workflow's own input schema. See the module doc. */}
+        <WorkflowFields workflow={WORKFLOW} />
+        <SubmitButton pending={pending} pendingLabel="Working…">
+          Summarize
+        </SubmitButton>
+      </Form>
+
+      {/* The upload is its own wait, and the one nothing else can describe: the
+          run does not EXIST until the bytes are in, so there is no run id and
+          nothing for `<WorkflowProgress>` to read. */}
+      <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
+
+      {/* What the run itself says, from `report()` in the workflow's steps. */}
+      <WorkflowProgress runId={run?.runId} api={api} />
+
+      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+
+      {output !== undefined && (
+        <article className="flex flex-col gap-5">
+          <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
+            </p>
+          </div>
+
+          <ul className="flex list-disc flex-col gap-1 pl-5">
+            {output.points.map((point) => (
+              <li key={point}>{point}</li>
+            ))}
+          </ul>
+
+          <section className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium opacity-70">
+              Read aloud · {duration(output.audioDurationMs)}
+            </h3>
+            {audio.error !== undefined && (
+              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+            )}
+            {audio.url !== undefined && (
+              <>
+                <audio controls src={audio.url} className="w-full">
+                  {/* A real caption track, not a suppression: the summary was
+                      written before it was spoken, so the words are already
+                      here and one cue spanning the clip is an honest
+                      transcript of it. */}
+                  <track
+                    kind="captions"
+                    srcLang="en"
+                    label="Summary"
+                    default
+                    src={captionsUrl(output.spoken, output.audioDurationMs)}
+                  />
+                </audio>
+                {/* `download` works on an object URL because the bytes are
+                    already in the tab; it is the href that could not carry the
+                    agent's bearer, not the attribute. */}
+                <a href={audio.url} download="summary.wav" className="text-sm underline">
+                  Download summary.wav
+                </a>
+              </>
+            )}
+            <p className="text-sm opacity-70">{output.spoken}</p>
+          </section>
+
+          <details className="text-sm">
+            <summary className="cursor-pointer opacity-70">Transcript</summary>
+            <p className="mt-2 whitespace-pre-wrap">{output.transcript}</p>
+          </details>
+        </article>
+      )}
+    </main>
+  );
+}
+
+page({ name: "Spoken Summary", component: App });

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

@@ -0,0 +1,242 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The workflow body, and the two legs after the transcript: a model reads it,
+ * and a voice reads the model back.
+ *
+ * ```text
+ *   transcribe   (workflows/transcribe.ts)   →  the words
+ *   summarize    one step, LLM Gateway       →  a headline, points, and a script
+ *   speak        one step, streaming TTS     →  a WAV, stored, and its id
+ * ```
+ *
+ * ## Audio in, audio out — and the second half is the part that needed the SDK
+ *
+ * Reading a file and transcribing it is what `transcription-workflow` already
+ * shows. What this template is for is the return trip, which until recently a
+ * workflow could not make at all:
+ *
+ * - **`stepSpeak`** synthesizes from inside a step. The session TTS surface
+ *   cannot: a `TtsSession` is an event stream wired into a live pipeline's
+ *   playback, and a step has no turn to be part of and has to return a VALUE.
+ * - **`writeUpload`** puts that value somewhere. A run's OUTPUT is read back as
+ *   JSON, so audio cannot travel in one — the same rule that keeps a
+ *   recording's bytes out of a run's INPUT, arriving at the other end of the
+ *   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
+ * 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.
+ *
+ * ## The model is asked for TWO things, and the difference is the point
+ *
+ * `points` is for reading and `spoken` is for hearing, and a template that
+ * synthesized the bullet list would produce something nobody wants to listen
+ * to — a voice reading "one. two. three." with no connective tissue. So the
+ * schema asks for a script as well, in sentences, and that is what
+ * {@link speak} is handed. It is the same decision `recap-workflow` makes for
+ * the sentence it reads down a phone, and it is one prompts get wrong when the
+ * shape does not force it.
+ *
+ * ## Why each leg is its own step
+ *
+ * They fail differently and cost differently. The transcription is minutes of a
+ * provider's queue; the model call is seconds and rate-limited; the synthesis
+ * is a socket. Splitting them means a rate-limited model call replays the
+ * transcript from the journal instead of transcribing the recording again, and
+ * a synthesis that failed does not re-run the model — which is the ordinary
+ * reason to split steps, made sharp here because the first leg is the
+ * expensive one.
+ */
+
+import { throwStepError } from "@alexkroman1/aai/step-errors";
+import {
+  omitUndefined,
+  report,
+  stepGenerateJson,
+  stepSpeak,
+  TRANSCRIBE_API,
+  writeUpload,
+} from "@alexkroman1/aai/utils";
+import { sleep } from "workflow";
+import { z } from "zod";
+import {
+  countWords,
+  createJob,
+  MAX_POLLS,
+  POLL_INTERVAL,
+  pollTranscript,
+  type Transcript,
+  uploadToProvider,
+} from "./transcribe.ts";
+
+/** Points the summary is reduced to. Enough to be a summary, few enough to scan. */
+const POINTS = 4;
+
+/**
+ * Characters of transcript handed to the model.
+ *
+ * The pass-an-id-not-a-payload rule meeting a case where the payload IS the
+ * work: the text has to cross the queue between two steps, so it is bounded
+ * rather than trusted. 40k characters is roughly four hours of speech — past
+ * where another paragraph changes a four-point summary.
+ */
+const MAX_TRANSCRIPT_CHARS = 40_000;
+
+/**
+ * The shape the model must answer in, as something that CHECKS.
+ *
+ * `stepGenerateJson` validates against this and throws plainly when the reply
+ * misses, which is what a retry is for: a model that answered with prose may
+ * well obey on the next attempt.
+ */
+const SummaryReply = z.object({
+  headline: z.string().trim().min(1),
+  points: z.array(z.string().trim().min(1)).min(1),
+  // NOT `.default("")` — the whole second half of this workflow has nothing to
+  // say without it, and a default would turn a missing field into a silent
+  // half-second of audio rather than a retry.
+  spoken: z.string().trim().min(1),
+});
+
+/** What a finished run reports. Small and JSON-shaped, like every step result. */
+export type SpokenSummary = {
+  /** The uploaded file's own name. */
+  source: string;
+  /** The recording's length, as the provider measured it. */
+  durationMs: number;
+  /** Words in the transcript. */
+  words: number;
+  /** One line naming what the recording was about. */
+  headline: string;
+  /** The summary, for reading. */
+  points: string[];
+  /** The summary, for hearing — what {@link speak} was handed. */
+  spoken: string;
+  /** The whole transcript, so the page can show its work. */
+  transcript: string;
+  /**
+   * The upload id of the spoken summary — a WAV, in this app's own store.
+   *
+   * An ID rather than the bytes, and that is the rule rather than a
+   * preference: a run's output is read back as JSON. `api.download(id)` is the
+   * browser half.
+   */
+  audio: string;
+  /** How long the spoken summary lasts. */
+  audioDurationMs: number;
+};
+
+/** 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> {
+  "use workflow";
+
+  const transcript = await transcribe(input.recording);
+  const summary = await summarize(transcript.text);
+  const spoken = await speak(summary.spoken, input.voice);
+
+  return {
+    source: transcript.source,
+    durationMs: transcript.durationMs,
+    words: countWords(transcript.text),
+    headline: summary.headline,
+    points: summary.points,
+    spoken: summary.spoken,
+    transcript: transcript.text,
+    audio: spoken.audio,
+    audioDurationMs: spoken.durationMs,
+  };
+}
+
+/**
+ * The whole first leg, factored out of the body.
+ *
+ * A plain async function rather than a step, and NOT because it is small: it
+ * calls steps and it `sleep`s durably between polls, neither of which a step
+ * may do. So it runs as part of the BODY and is replayed with it — which is
+ * legal here for the ordinary reason, that everything it does is either a step
+ * call or a `sleep`, so a replay re-derives exactly the same sequence.
+ */
+async function transcribe(recording: string): Promise<Transcript> {
+  const { audioUrl } = await uploadToProvider(recording);
+  const job = await createJob(audioUrl);
+
+  for (let poll = 0; poll < MAX_POLLS; poll += 1) {
+    const progress = await pollTranscript(recording, job.id);
+    if (progress.done) return progress.transcript;
+    await sleep(POLL_INTERVAL);
+  }
+  // A plain throw: this is the BODY, where the fatal/retryable distinction has
+  // nothing to apply to. The transcript is not lost, so the message says where
+  // it is rather than only that the wait ran out.
+  throw new Error(
+    `Transcript ${job.id} was still unfinished after ${MAX_POLLS} polls. It is not lost — ` +
+      `read it directly with GET ${TRANSCRIBE_API}/v2/transcript/${job.id}.`,
+  );
+}
+
+/** Reduce the transcript to a headline, {@link POINTS} points, and a script. */
+export async function summarize(
+  text: string,
+): Promise<{ headline: string; points: string[]; spoken: string }> {
+  "use step";
+
+  await report("Summarizing the transcript.");
+  const reply = await stepGenerateJson(
+    "Summarize this transcript of a recording.\n\n" +
+      "Answer with JSON only, in this shape:\n" +
+      `{"headline": "...", "points": ["..."], "spoken": "..."}\n\n` +
+      "- headline: one line naming what the recording was about.\n" +
+      `- points: at most ${POINTS} short points, each a complete thought. Concrete ` +
+      `specifics — decisions, numbers, names, what happens next — never "the ` +
+      `speaker discussed several topics".\n` +
+      "- spoken: the same summary written to be READ ALOUD. Full sentences that " +
+      "flow, under 120 words, no bullet markers, no headings, no markdown. " +
+      "Someone will hear this without seeing the points.\n\n" +
+      `Transcript:\n${text.slice(0, MAX_TRANSCRIPT_CHARS)}`,
+    {
+      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);
+
+  return { headline: reply.headline, points: reply.points.slice(0, POINTS), spoken: reply.spoken };
+}
+
+/**
+ * Read the summary aloud, store the WAV, and answer with its id.
+ *
+ * **Both halves belong in ONE step**, and the reason is what a journal records:
+ * a step is replayed by its RETURN VALUE, so an id is replayed and bytes are
+ * not. Split in two, the audio would have to cross the queue between them —
+ * megabytes of it, on every resume. Together, a resumed run replays the id and
+ * re-reads a file that is already there.
+ */
+export async function speak(
+  script: string,
+  voice?: string,
+): Promise<{ audio: string; durationMs: number }> {
+  "use step";
+
+  const spoken = await stepSpeak(script, omitUndefined({ voice }));
+  const stored = await writeUpload(spoken.audio, {
+    // Named, because this is what a person sees on the download link rather
+    // than an opaque id — and typed, because the byte route serves the type it
+    // was given and a browser will not play a file it was handed as bytes.
+    name: "summary.wav",
+    type: "audio/wav",
+  });
+
+  await report(
+    `Recorded a ${Math.round(spoken.durationMs / 1000)}s summary in ${spoken.voice}'s voice.`,
+  );
+  return { audio: stored.id, durationMs: spoken.durationMs };
+}

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

@@ -0,0 +1,145 @@
+// 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/utils` 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 { throwStepError } from "@alexkroman1/aai/step-errors";
+import {
+  report,
+  stepTranscribePoll,
+  stepTranscribeSubmit,
+  stepTranscribeUpload,
+  uploadInfo,
+} 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.
+ *
+ * `.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.
+ */
+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);
+}
+
+/** 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 stepTranscribeSubmit(audioUrl).catch(throwStepError);
+  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 stepTranscribePoll(id).catch(throwStepError);
+  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,
+    },
+  };
+}
+
+/** 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`;
+}