@alexkroman1/aai-cli 9.1.0 → 10.0.0

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

@@ -3,9 +3,8 @@
  * Specs for the spoken-summary app's declaration and its four legs.
  *
  * **The body itself is not driven here**, and that is a property of what a
- * workflow template demonstrates rather than a gap: imported through vitest
- * with no bundler in the path, a `"use step"` function is an ordinary async
- * function — so its HTTP handling, its fatal/retryable classification and what
+ * workflow template demonstrates rather than a gap: a step is an ordinary
+ * exported async function — so its HTTP handling, its fatal/retryable classification and what
  * it returns are all testable, while durability, suspension and replay are not.
  * A body test that looked like a durability test would be the worse failure;
  * the real thing is exercised end to end by `aai-cli`'s
@@ -18,6 +17,8 @@
  */
 
 import { readUpload, uploadInfo } from "@alexkroman1/aai/step";
+import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
+import { createWorkflowCtx } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -26,7 +27,6 @@ import {
   installStubUploads,
 } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { FatalError, RetryableError } from "workflow";
 import agentDef, { spokenSummary } from "./agent.ts";
 import { speak, spokenSummaryFlow, summarize } from "./workflows/summarize.ts";
 import { createJob, pollTranscript, uploadToProvider } from "./workflows/transcribe.ts";
@@ -233,7 +233,7 @@ describe("the whole run", () => {
   /**
    * Answer every leg's HTTP, so the BODY can be driven end to end.
    *
-   * Imported through vitest with no bundler in the path, a `"use workflow"`
+   * Imported through vitest, a workflow
    * function is an ordinary async function — so what this exercises is the
    * ORDER the legs are wired in and the shape they hand each other, which is
    * the one thing the per-leg specs above cannot see. Durability, suspension
@@ -276,7 +276,7 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID });
+    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx());
 
     expect(summary).toEqual({
       source: "standup.wav",
@@ -298,7 +298,7 @@ describe("the whole run", () => {
     installStubReporter();
     const speech = installStubSpeech();
 
-    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" });
+    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" }, createWorkflowCtx());
 
     expect(speech.calls[0]).toMatchObject({ text: "Spoken.", voice: "michael" });
   });
@@ -308,6 +308,8 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    await expect(spokenSummaryFlow({ recording: UPLOAD_ID })).rejects.toThrow("corrupt audio");
+    await expect(spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx())).rejects.toThrow(
+      "corrupt audio",
+    );
   });
 });

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

@@ -30,6 +30,36 @@
  * 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.
+ *
+ * ## A reload used to lose a run whose input was already paid for
+ *
+ * A `runId` names a run for as long as something holds it, and this page held it
+ * in React state — so a refresh lost it while the recording carried on being
+ * transcribed, summarized and spoken. The bytes were already stored, so the
+ * expensive half had happened; what an empty form invites is somebody uploading
+ * the recording again and paying for all four legs twice. `key` is the handle
+ * that survives a reload, `recover: true` is what reads it back, and the upload
+ * half is already the SDK's — picking the same file again sends only the windows
+ * that did not land.
+ *
+ * **The key is `useRunKey()`** — opaque, and in `sessionStorage`, which is the
+ * same lifetime as that upload recall, so both halves of a reload make the same
+ * promise. What that rules out is a `?key=` parameter, and it is worth being
+ * plain about the trade because this template exists to produce something
+ * sendable: a summary you can listen to is exactly the sort of thing somebody
+ * forwards, and a URL is how people forward things. But there is no per-user
+ * filtering behind `find`, so the key IS the access control — a leaked one
+ * grants, on this agent, the whole TRANSCRIPT of the recording, the summary,
+ * the synthesized audio, and every other run filed under the same key. And URLs
+ * leak by ordinary use: chats, history, referrers. Sharing the artifact needs
+ * none of that — the page offers `Download summary.wav` and renders the words,
+ * so a person sends the file to exactly who they meant. Deriving the key from
+ * the recording would be worse again: two people summarizing one file would
+ * recover each other's runs.
+ *
+ * A real app with accounts passes the account's own id instead, and then a
+ * summary follows the person to another device — a promise only a login can
+ * keep.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -44,10 +74,12 @@ import {
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
+  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
+import { useState } from "react";
 import type { spokenSummary } from "./agent.ts";
 
 /**
@@ -67,6 +99,20 @@ const WORKFLOW = "spokenSummary";
  */
 const api = createWorkflowApi();
 
+/**
+ * What the page says while a run is in flight — three situations, one line
+ * each.
+ *
+ * The reload case gets its own words deliberately: somebody who did not press
+ * the button is owed an explanation for a summary appearing in front of them,
+ * and it is the line that keeps them from uploading the recording again.
+ */
+function pendingNote(startedHere: boolean, found: boolean): string {
+  if (startedHere) return "Reloading is safe — this page will find the summary again.";
+  if (!found) return "Looking for a summary this tab started earlier…";
+  return "Still working on a recording this tab uploaded earlier — no need to send it again.";
+}
+
 /**
  * The spoken text as a one-cue WebVTT track, inline.
  *
@@ -82,11 +128,20 @@ function captionsUrl(text: string, durationMs: number): string {
 }
 
 export function App() {
+  // This tab's handle on its own summaries, in the store the upload recall uses
+  // — see the module doc for why a `?key=` is the wrong trade here.
+  const key = useRunKey();
+  // Did THIS load start the run? A reload cannot have, and that is the only way
+  // the page can tell "working on what you just sent" from "picking up where
+  // you left off" — the hook reports the run, not who asked for it.
+  const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
-  // `run.output` instead of `unknown`.
+  // `run.output` instead of `unknown`. Neither half of the recovery is useful
+  // alone: without `key` there is nothing to find the run by, and without
+  // `recover` the key is only ever written.
   const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
     typeof spokenSummary
-  >(WORKFLOW, { api });
+  >(WORKFLOW, { api, key, recover: true });
   const output = run?.status === "completed" ? run.output : undefined;
   // `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
@@ -102,7 +157,14 @@ export function App() {
         </p>
       </header>
 
-      <Form onSubmit={submitForm} error={error} className="flex flex-col gap-4">
+      <Form
+        onSubmit={(values) => {
+          setStartedHere(true);
+          return submitForm(values);
+        }}
+        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…">
@@ -110,6 +172,13 @@ export function App() {
         </SubmitButton>
       </Form>
 
+      {/* `pending` covers the RUN rather than the request, and on a reload it is
+          also true while the run is being looked up by key — the stretch where
+          an empty form would invite a second upload of the same recording. */}
+      {pending && (
+        <p className="text-sm opacity-70">{pendingNote(startedHere, run !== undefined)}</p>
+      )}
+
       {/* 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. */}

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

@@ -49,6 +49,7 @@
  * expensive one.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import { report, stepSpeak, TRANSCRIBE_API, writeUpload } from "@alexkroman1/aai/step";
 import { stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
 import { countWords, omitUndefined } from "@alexkroman1/aai/utils";
@@ -56,13 +57,12 @@ import { countWords, omitUndefined } from "@alexkroman1/aai/utils";
 // 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 {
   createJob,
   MAX_POLLS,
-  POLL_INTERVAL,
+  POLL_INTERVAL_MS,
   pollTranscript,
   type Transcript,
   uploadToProvider,
@@ -128,12 +128,11 @@ export type SpokenSummary = {
 /** Transcribe a recording, summarize it, and read the summary back. */
 export async function spokenSummaryFlow(
   input: WorkflowInputOf<typeof spokenSummary>,
+  ctx: WorkflowCtx,
 ): Promise<SpokenSummary> {
-  "use workflow";
-
-  const transcript = await transcribe(input.recording);
-  const summary = await summarize(transcript.text);
-  const spoken = await speak(summary.spoken, input.voice);
+  const transcript = await transcribe(input.recording, ctx);
+  const summary = await ctx.step("summarize", () => summarize(transcript.text));
+  const spoken = await ctx.step("speak", () => speak(summary.spoken, input.voice));
 
   return {
     source: transcript.source,
@@ -151,20 +150,29 @@ export async function spokenSummaryFlow(
 /**
  * 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.
+ * Part of the BODY rather than a step, and NOT because it is small: it CALLS
+ * steps and it sleeps durably between polls, neither of which may happen inside
+ * one. So it is replayed with the body — which is legal for the ordinary reason,
+ * that everything it does is either a `ctx.step` or a `ctx.sleep`, so a replay
+ * re-derives exactly the same sequence. It takes the `ctx` for that reason: a
+ * helper that reaches the journal has to be handed the handle.
  */
-async function transcribe(recording: string): Promise<Transcript> {
-  const { audioUrl } = await uploadToProvider(recording);
-  const job = await createJob(audioUrl);
+async function transcribe(recording: string, ctx: WorkflowCtx): Promise<Transcript> {
+  // `maxAttempts: 6` was `uploadToProvider.maxRetries = 5` — five retries after
+  // the first attempt. It is the one step here worth extra patience: it streams
+  // the whole recording, so a transient failure is expensive to reach again.
+  const { audioUrl } = await ctx.step("uploadToProvider", () => uploadToProvider(recording), {
+    maxAttempts: 6,
+  });
+  const job = await ctx.step("createJob", () => createJob(audioUrl));
 
   for (let poll = 0; poll < MAX_POLLS; poll += 1) {
-    const progress = await pollTranscript(recording, job.id);
+    // One call site in a loop, so each poll is its own journal entry
+    // (`pollTranscript#0`, `#1`, …) and a resume replays the polls already made
+    // rather than starting the wait over.
+    const progress = await ctx.step("pollTranscript", () => pollTranscript(recording, job.id));
     if (progress.done) return progress.transcript;
-    await sleep(POLL_INTERVAL);
+    await ctx.sleep(POLL_INTERVAL_MS);
   }
   // 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
@@ -179,8 +187,6 @@ async function transcribe(recording: string): Promise<Transcript> {
 export async function summarize(
   text: string,
 ): Promise<{ headline: string; points: string[]; spoken: string }> {
-  "use step";
-
   await report("Summarizing the transcript.");
   const reply = await stepGenerateJsonClassified(
     "Summarize this transcript of a recording.\n\n" +
@@ -219,8 +225,6 @@ 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

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

@@ -22,12 +22,14 @@
  *
  * ## 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.
+ * A step is a `ctx.step(name, fn)` in the BODY, and only the body holds a `ctx` —
+ * so the SDK could not declare one even if it wanted to. That is a better
+ * boundary than the one it replaced: under the DevKit a step directive shipped
+ * inside a dependency was transformed by nothing and ran inline with no journal
+ * and no retry, SILENTLY, and the rule was a convention this comment had to
+ * state. Now the SDK owns what happens INSIDE a step and the app owns which
+ * steps exist — which is to say what gets journaled and what a retry repeats —
+ * and neither can accidentally take the other's half.
  *
  * **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
@@ -46,13 +48,17 @@ import {
 } 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";
+/**
+ * How long between polls of a submitted job.
+ *
+ * Milliseconds: `ctx.sleep` takes a number or a `Date` and no duration STRING.
+ */
+export const POLL_INTERVAL_MS = 10_000;
 
 /**
  * Polls before the run gives up on a job.
  *
- * At {@link POLL_INTERVAL} this is an hour, well past what the async API takes
+ * At {@link POLL_INTERVAL_MS} 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.
  */
@@ -86,8 +92,6 @@ export type Transcript = {
  * 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.`,
@@ -95,13 +99,8 @@ export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: st
   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;
@@ -120,8 +119,6 @@ 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 };
 

package/dist/templates/transcription-workflow/agent.eval.test.ts

@@ -24,7 +24,7 @@
 // that answers "is the transcript really of the recording".
 //
 // WHAT NO EVAL HERE COVERS: durability. Imported through vitest with no bundler
-// in the path, a `"use workflow"` body is an ordinary async function — no
+// in the path, a workflow body is an ordinary async function — no
 // journal, no replay, and no per-step retry, so the resume-after-segment-27
 // property this template exists to demonstrate is NOT exercised here, and a
 // rate-limited live run fails where a deployed one would have ridden it out.