@alexkroman1/aai-cli 9.2.0 → 10.0.1

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -13,13 +13,57 @@
  * | Temporal sample | Ported here as |
  * | --- | --- |
  * | `saga` — `openAccount`'s compensation stack | {@link recapFlow}'s `compensations`, unwound by {@link compensate} |
- * | `polling` — infrequent polling | {@link awaitTranscript}: a bounded loop of one step plus one durable `sleep` |
- * | `timer-examples` — `processOrderWorkflow` | the `Promise.race` against {@link PATIENCE}, then the "still going" note |
- * | `expense` — `timeoutOrUserAction` | the RETENTION GATE: a hook raced against {@link RETENTION_WINDOW}, three outcomes and a safe default |
+ * | `polling` — infrequent polling | {@link awaitTranscript}'s loop: one step plus one durable `sleep`, and the BACKSTOP under the callback below |
+ * | `timer-examples` — `processOrderWorkflow` | the "still going" note, at {@link PATIENCE_POLLS} turns of the loop or one closed {@link CALLBACK_WINDOW_MS} |
+ * | `expense` — `timeoutOrUserAction` | the RETENTION GATE: one `ctx.waitFor` with {@link RETENTION_WINDOW_MS}, three outcomes and a safe default |
  *
  * The voice half — start, query, cancel, and the answer to the gate — is ported
  * in `agent.ts`.
  *
+ * ## The provider CALLS BACK, and the poll is what makes that safe
+ *
+ * AssemblyAI's async API takes a `webhook_url` on submission, so the ordinary
+ * case does not need a poll at all: {@link callbackUrl} mints one with
+ * `stepWebhookUrl`, {@link submitRecording} hands it over, and the body parks on
+ * `ctx.waitFor` until the delivery lands. The run is SUSPENDED throughout — the
+ * same as a `sleep`, so this is not a saving on resident process time; what it
+ * buys is one status read instead of nine, and a recap that starts being written
+ * the second the transcript exists rather than up to fifteen seconds later.
+ *
+ * **`stepWebhookUrl` is the step-side half of
+ * `ctx.workflows.publicWebhookUrl`,** and until it existed this conversion was
+ * not available to a workflow at all: the tool-side accessor needs a
+ * `ToolContext`, and a body and its steps are handed none. This template could
+ * have reached it through its own tools — it has five — but the URL would then
+ * have had to travel as run input, which is a shape the three `workflowApp()`
+ * templates (no tools at all) could not copy. The step helper is the one both
+ * can use.
+ *
+ * **The poll did not go away, and it must not.** A webhook is one HTTP POST from
+ * a third party with no delivery guarantee anyone here controls: AssemblyAI
+ * retries ten times at ten-second intervals and then gives up permanently, a
+ * deployment may not know its own public URL at all, and a delivery that arrives
+ * in the milliseconds before the body reaches its wait is answered `404` and
+ * dropped. So the callback is an OPTIMIZATION OVER A RECONCILING READ, never a
+ * replacement for one: {@link awaitTranscript} reads the status before it parks
+ * and again after, and if nothing ever arrives it degrades to exactly the loop
+ * it always was. A template that hung forever on a dropped delivery would be
+ * strictly worse than one that polls. That rule generalizes to every event
+ * source in this product — the event tells you WHEN to look, and the read is
+ * what tells you what happened.
+ *
+ * **The delivery cannot be the answer even in principle, and that is what makes
+ * an unauthenticated callback safe here.** AssemblyAI's payload is
+ * `{transcript_id, status}` and nothing else — no text, no error detail — so the
+ * run has to `GET` the transcript regardless of who knocked. This body therefore
+ * does not read the payload at all: a forged delivery on a guessed token costs
+ * exactly one extra status read and changes no decision, because every decision
+ * is made from what the provider's own endpoint says under this desk's own
+ * credential. That is a better guarantee than a shared secret would be — it
+ * holds by construction rather than by a credential somebody has to rotate. See
+ * {@link awaitTranscript} for the auth header the provider offers and why this
+ * template does not set one.
+ *
  * ## The gate is the one that needed a new SDK primitive
  *
  * Temporal's `expense` sample parks a workflow on a signal until a human
@@ -67,17 +111,18 @@
  * just your shell.
  */
 
-import { report, requireStepEnv, stepFetch } from "@alexkroman1/aai/step";
+import { isWorkflowSuspend, type WorkflowCtx } from "@alexkroman1/aai";
+import { report, requireStepEnv, stepFetch, stepWebhookUrl } from "@alexkroman1/aai/step";
 import {
+  FatalError,
   stepFetchOk,
   stepGenerateJsonClassified,
   stepTranscribeSubmitClassified,
   toStepError,
 } from "@alexkroman1/aai/step-errors";
 import { errorMessage, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
-import { createHook, FatalError, sleep } from "workflow";
 import { z } from "zod";
-import { retentionToken } from "./tokens.ts";
+import { retentionToken, transcriptToken } from "./tokens.ts";
 
 /** AssemblyAI's pre-recorded (batch) transcription collection. */
 const TRANSCRIPT_ENDPOINT = "https://api.assemblyai.com/v2/transcript";
@@ -94,7 +139,7 @@ const API_KEY_ENV = "ASSEMBLYAI_API_KEY";
  * file, and the docs' own 1–2 second advice is for a load test with a
  * rate-limit budget to spend.
  */
-const POLL_INTERVAL = "15 seconds";
+const POLL_INTERVAL_MS = 15_000;
 
 /**
  * Polls before the desk gives up.
@@ -102,33 +147,79 @@ const POLL_INTERVAL = "15 seconds";
  * A bound rather than a deadline, because it is what the LOOP can enforce with
  * nothing but journaled values: attempt N is attempt N on every replay, where a
  * wall-clock deadline read in the body would move under it. At
- * {@link POLL_INTERVAL} this is twenty minutes, which is far past the
+ * {@link POLL_INTERVAL_MS} this is twenty minutes, which is far past the
  * turnaround of any recording a phone caller will name.
  */
 const MAX_POLLS = 80;
 
 /**
- * How long the desk waits before admitting a recording is a long one.
+ * How many polls before the desk admits a recording is a long one.
+ *
+ * The port of Temporal's `processOrderWorkflow`, and the ONE place this port
+ * changes shape rather than vocabulary. There the pattern is a `Promise.race`
+ * between the work and a timer; here both a `ctx.sleep` and the work's own polls
+ * SUSPEND, and a suspend unwinds the stack — so racing them stops the body on
+ * whichever suspends first, before the other has been reached. Counting polls
+ * says the same thing with journaled values only: attempt N is attempt N on
+ * every replay, which is the property {@link MAX_POLLS} already rests on.
+ *
+ * NINE rather than eight, and the off-by-one is the whole subtlety of counting
+ * polls instead of watching a clock: the note goes out at the TOP of a poll, so
+ * what has elapsed by then is the sleeps BEHIND it — N-1 of them. At
+ * {@link POLL_INTERVAL_MS} that makes this two minutes, the wait the timer named;
+ * eight said the same sentence at 1:45, which is a desk calling a recording a
+ * long one a quarter of a minute before it is entitled to.
+ */
+const PATIENCE_POLLS = 9;
+
+/**
+ * How long one park on the provider's callback lasts.
+ *
+ * The same two minutes {@link PATIENCE_POLLS} counts out, and deliberately the
+ * same number: whichever arm the run is on, the caller hears "still transcribing"
+ * after two minutes of waiting and not before. What differs is only how many
+ * times the desk asked the provider to get there — nine reads, or one.
+ *
+ * **This is the first thing in the template that is a REAL timed race**, which
+ * is worth stopping on because {@link PATIENCE_POLLS}'s doc apologises at length
+ * for not being one. Temporal's `processOrderWorkflow` races the work against a
+ * timer; a poll count can only approximate that, and this file could not do
+ * better while both sides of the race were suspending calls. `waitFor(token,
+ * { timeoutMs })` IS the race — the delivery or the deadline, journaled as ONE
+ * decision — so the ported pattern finally has the shape it has upstream.
+ *
+ * Two minutes rather than the twenty the loop budgets, because the window is
+ * what a DROPPED delivery costs: nothing is lost when it closes, the run simply
+ * goes back to reading, so a short window buys most of the saving and bounds the
+ * worst case.
+ */
+const CALLBACK_WINDOW_MS = 120_000;
+
+/**
+ * Polls before the desk admits a recording is a long one, on the callback arm.
  *
- * The port of Temporal's `processOrderWorkflow`: race the work against a timer,
- * and if the timer wins, do the other thing — there the delayed-order email,
- * here a progress line the caller hears when they ask. Then keep waiting for
- * the work either way.
+ * The same off-by-one {@link PATIENCE_POLLS} explains, one window instead of
+ * eight sleeps: the note goes out at the TOP of a poll, so what has elapsed by
+ * then is the waiting BEHIND it. Attempt 2 is the first turn with a whole closed
+ * {@link CALLBACK_WINDOW_MS} behind it, which is the two minutes.
  */
-const PATIENCE = "2 minutes";
+const PATIENCE_POLLS_WITH_CALLBACK = 2;
 
 /**
  * How long the desk holds the transcript waiting for an answer.
  *
  * The port of `timeoutOrUserAction`: Temporal races a `condition()` against a
- * timeout, this races a hook against a `sleep`, and both have THREE outcomes —
- * approved, declined, nobody answered. The window is a `sleep`, so a caller who
- * hangs up costs nothing while it runs.
+ * timeout, this passes the window to `ctx.waitFor` as `timeoutMs`, and both have
+ * THREE outcomes — approved, declined, nobody answered. A parameter rather than
+ * a race for the reason {@link PATIENCE_POLLS} gives, and it is the better shape
+ * anyway: the deadline is journaled once, so a replay cannot extend the window,
+ * and the engine CLOSES the hook when it shuts so a late answer cannot be taken.
+ * The run is suspended throughout, so a caller who hangs up costs nothing.
  *
  * Two minutes because a caller is on the line; a desk whose approver is on email
- * would write `"2 days"` and nothing else in this file would change.
+ * would write two days and nothing else in this file would change.
  */
-const RETENTION_WINDOW = "2 minutes";
+const RETENTION_WINDOW_MS = 120_000;
 
 /** Every HTTP call's deadline. `fetch` has none of its own, and a hung step never ends. */
 const REQUEST_TIMEOUT_MS = 30_000;
@@ -204,9 +295,7 @@ export type Compensation = { label: string; undo: () => Promise<void> };
  * `agent.ts` reads back down the phone, so it is shaped for an ear rather than
  * a page.
  */
-export async function recapFlow(input: { url: string; requestedBy: string }) {
-  "use workflow";
-
+export async function recapFlow(input: { url: string; requestedBy: string }, ctx: WorkflowCtx) {
   // The compensation stack, newest first — `unshift` after each successful
   // acquisition, exactly as Temporal's `openAccount` does. Registering the undo
   // AFTER the step it undoes is the whole discipline: a step that never
@@ -215,34 +304,52 @@ export async function recapFlow(input: { url: string; requestedBy: string }) {
   const compensations: Compensation[] = [];
 
   try {
-    const job = await submitRecording(input.url);
+    // The token this run's callback URL is minted for, and the one
+    // `awaitTranscript` parks on — derived from the run's own input in ONE place
+    // so the URL the provider is given and the string the body waits on cannot
+    // drift. They are separated by a third party on the public internet, which
+    // is as far apart as two halves of a contract get.
+    const nudge = transcriptToken(input.requestedBy);
+    // `callbackUrl` is evaluated INSIDE the step's function, so it runs once —
+    // on first execution — and never on a replay, which returns the journaled
+    // result without calling this at all. That is what makes the mint a
+    // journaled decision rather than one re-taken on every walk.
+    const job = await ctx.step("submitRecording", () =>
+      submitRecording(input.url, callbackUrl(nudge)),
+    );
     compensations.unshift({
       label: `transcript ${job.id}`,
-      undo: () => discardTranscript(job.id),
+      undo: () => ctx.step("discardTranscript", () => discardTranscript(job.id)),
     });
 
-    // Temporal's `processOrderWorkflow`, line for line: start the work, race it
-    // against a timer, and if the timer wins first say so and then go on
-    // waiting. `ready` is an ordinary local — deterministic, because the only
-    // thing that flips it is a journaled step result.
-    let ready = false;
-    const work = awaitTranscript(job.id).then((state) => {
-      ready = true;
-      return state;
-    });
-    await Promise.race([work, sleep(PATIENCE)]);
-    if (!ready) await note("Still transcribing — this is a long one. I'll keep going.");
-    const transcript = await work;
+    // `job.callback` rather than a fresh mint: the branch has to come out of the
+    // JOURNAL, or a redeploy mid-run could flip it — see {@link submitRecording}.
+    const transcript = await awaitTranscript(job.id, ctx, job.callback ? nudge : undefined);
 
-    const recap = await summarize(input.url, transcript);
-    const retention = await askWhetherToKeep(input.requestedBy, job.id, compensations);
+    const recap = await ctx.step("summarize", () => summarize(input.url, transcript), {
+      // Was `summarize.maxRetries = 5` — five retries after the first attempt.
+      maxAttempts: 6,
+    });
+    const retention = await askWhetherToKeep(input.requestedBy, job.id, compensations, ctx);
     return { ...recap, ...retention, requestedBy: input.requestedBy };
   } catch (err) {
+    // **A suspend is not a failure, and this catch is why that matters.** The
+    // body above WAITS three ways now — `awaitTranscript` parks on the
+    // provider's callback, then sleeps between polls, and the gate waits for an
+    // answer — and every one of them suspends by throwing, so it lands here.
+    // Without this line the first poll that had to wait unwound the compensation
+    // stack, DELETED the transcript the run was waiting for, journaled the
+    // deletion as successful and re-threw; the engine saw its own signal come
+    // back out and recorded the run as healthily suspended. The data was gone and
+    // every signal said fine. `replayRun` now also fails a run that swallows one,
+    // so a body that forgets this is loud rather than silently destructive — but
+    // the body is the place it belongs.
+    if (isWorkflowSuspend(err)) throw err;
     // The saga's whole point. Everything acquired above is released, in reverse,
     // before the failure is re-thrown — and because each undo is a STEP, a crash
     // during the unwind resumes with the finished ones replayed from the journal
     // rather than run twice.
-    await compensate(compensations, errorMessage(err));
+    await compensate(compensations, errorMessage(err), ctx);
     throw err;
   }
 }
@@ -252,28 +359,90 @@ export async function recapFlow(input: { url: string; requestedBy: string }) {
  *
  * A body-side helper, not a step: it `sleep`s, and a step cannot — a step runs
  * to completion in a worker, where the body is what may suspend. Splitting it
- * out keeps `recapFlow` readable and costs nothing, since the WDK transform
- * rewrites a step's DECLARATION rather than its call sites, so a step called
- * from a helper is still a real step (`mapConcurrent` rests on the same
- * property).
+ * out keeps `recapFlow` readable and costs nothing: `ctx` is an ordinary value,
+ * so a helper handed one issues real steps. Note the occurrence counter is per
+ * RUN and not per function, so a name used here may not also be used in the body
+ * — the two call sites would alias onto one journal entry.
  *
  * The loop is deterministic despite looking like it is not: every branch turns
- * on a journaled step result, so a replay takes the same number of turns it took
- * live.
+ * on a journaled step result or on a journaled input field, so a replay takes
+ * the same number of turns it took live.
+ *
+ * ## Read first, then park ONCE, then read on a timer
+ *
+ * `nudge` is the callback token when `request_recap` managed to mint a URL, and
+ * `undefined` otherwise — in which case every line below behaves exactly as it
+ * did before there was a callback at all.
+ *
+ * The order matters and each part of it is paid for:
+ *
+ * - **The first read happens BEFORE the park**, so a job that finished while the
+ *   submit response was in flight, or a delivery that arrived in the milliseconds
+ *   before this body reached its wait and was dropped, costs nothing.
+ * - **The park happens ONCE, on the first turn only, and it HAS to.** A hook
+ *   token may be claimed at most once per run: `claimHook` (both journal
+ *   backends) throws `token … is already held by run …` for a second claim under
+ *   a different occurrence key, and the token is given back only when the run
+ *   goes TERMINAL — so a `ctx.waitFor` written inside this loop would fail the
+ *   second time round. That is not a hypothetical. The comment block at
+ *   `aai-runtime/workflow-journal-memory.ts:140-148` records this template
+ *   getting it wrong once already: a `claimHook` conflict is a throw and a throw
+ *   is not a suspend, so `recapFlow`'s `catch` treated it as a failed run, ran
+ *   the compensation stack and DELETED the transcript. A template that teaches
+ *   the wrong nesting here costs somebody their data.
+ * - **Every later turn is the plain cadence**, because a delivery that has not
+ *   arrived within {@link CALLBACK_WINDOW_MS} is one to stop counting on. The
+ *   loop from there is the `polling` port, unchanged, and it is what finishes the
+ *   run whether the delivery was late, dropped, never sent, or forged.
+ *
+ * **The payload is not read, and that is the security argument.** `waitFor` is
+ * called for its EDGE — "something happened, go look" — and the answer comes
+ * from {@link checkTranscript} under this desk's own credential, so nothing a
+ * caller could POST to the public callback route changes an outcome. AssemblyAI
+ * does offer `webhook_auth_header_name`/`webhook_auth_header_value`, and this
+ * template sets neither: the receiving route
+ * (`/.well-known/workflow/v1/webhook/:token`) authorizes on the TOKEN and reads
+ * no other header, so a header set here would be sent and ignored — security
+ * theatre, and worse than none because it reads as a control.
  */
-export async function awaitTranscript(id: string): Promise<TranscriptState> {
+export async function awaitTranscript(
+  id: string,
+  ctx: WorkflowCtx,
+  nudge?: string,
+): Promise<TranscriptState> {
+  // Which turn says "still going". A pure function of `nudge`, which the body
+  // derived from a journaled step result, so a replay picks the same turn.
+  const patienceAt = nudge === undefined ? PATIENCE_POLLS : PATIENCE_POLLS_WITH_CALLBACK;
+
   for (let attempt = 1; attempt <= MAX_POLLS; attempt++) {
-    const state = await checkTranscript(id);
+    const state = await ctx.step("checkTranscript", () => checkTranscript(id));
     if (state.status === "completed") return state;
     if (state.status === "error") {
       // The provider's own terminal answer. A plain `Error`, not a
       // `FatalError`: this is the BODY, and a body's throw is never retried —
-      // `FatalError` is the vocabulary for telling the DevKit not to retry a
+      // `FatalError` is the vocabulary for telling the ENGINE not to retry a
       // STEP, and using it here would claim a distinction that does not exist.
       throw new Error(`The provider could not transcribe that recording: ${state.error}`);
     }
-    // Suspended, not blocked: nothing is resident while this waits.
-    await sleep(POLL_INTERVAL);
+    // Once, at the point the timer used to fire — which is the top of the poll
+    // that follows two minutes of waiting, see {@link PATIENCE_POLLS} for the
+    // off-by-one. `attempt` is a journaled-value function, so a replay says it
+    // at the same turn or not at all.
+    if (attempt === patienceAt) {
+      await ctx.step("noteSlow", () =>
+        note("Still transcribing — this is a long one. I'll keep going."),
+      );
+    }
+    // Both arms SUSPEND — nothing is resident while either waits — and the only
+    // difference is what can end the wait early. The callback park is first-turn
+    // only; see this function's doc for why it cannot be every turn.
+    if (attempt === 1 && nudge !== undefined) {
+      // The payload is DISCARDED on purpose: this waits for the edge, and the
+      // read at the top of the next turn is what establishes the fact.
+      await ctx.waitFor(nudge, { timeoutMs: CALLBACK_WINDOW_MS });
+    } else {
+      await ctx.sleep(POLL_INTERVAL_MS);
+    }
   }
   throw new Error(`Gave up on that recording after ${MAX_POLLS} checks.`);
 }
@@ -282,8 +451,8 @@ export async function awaitTranscript(id: string): Promise<TranscriptState> {
  * Ask the caller whether the transcript stays on file, and act on the answer.
  *
  * The port of Temporal's `timeoutOrUserAction`, and a body-side helper for the
- * same reason {@link awaitTranscript} is: it opens a hook and `sleep`s, neither
- * of which a step can do.
+ * same reason {@link awaitTranscript} is: it waits, which only a body may do —
+ * so it takes the `ctx`.
  *
  * The default is DELETE, which is what makes the timeout meaningful. A gate
  * whose no-answer branch keeps the data is not a gate — it is a prompt with a
@@ -294,25 +463,27 @@ export async function askWhetherToKeep(
   requestedBy: string,
   transcriptId: string,
   compensations: Compensation[],
+  ctx: WorkflowCtx,
 ): Promise<Retention> {
-  // `using`, so the token is released when this scope exits — including the
-  // timeout branch, where nothing ever arrives. A hook left registered holds
-  // its token against the caller's NEXT run, which `getConflict()` below would
-  // then report as a conflict.
-  using decision = createHook<{ keep: boolean }>({ token: retentionToken(requestedBy) });
-  // Claim the token BEFORE anyone is told to signal it. `createHook()` registers
-  // nothing on its own — registration is committed when the workflow suspends —
-  // so without this the caller's answer races a token no hook owns yet and is
-  // answered "nobody is listening", which is indistinguishable from being late.
-  await decision.getConflict();
-
-  await note(
-    `Recap ready. Keep the transcript on file, or delete it? Deleting in ${RETENTION_WINDOW} otherwise.`,
+  await ctx.step("noteGate", () =>
+    note(
+      "Recap ready. Keep the transcript on file, or delete it? Deleting in two minutes otherwise.",
+    ),
   );
-  const answer = await Promise.race([decision, sleep(RETENTION_WINDOW).then(() => undefined)]);
+
+  // ONE call, not a race — and the ordering worry the DevKit version opened with
+  // is gone with it. `createHook()` registered nothing until the workflow
+  // suspended, so a caller's answer could reach a token no hook owned yet and be
+  // told "nobody is listening", indistinguishable from being late; hence the
+  // `getConflict()` claim on the line above it. `ctx.waitFor` registers the
+  // token BEFORE it suspends, by construction, because registering it is how it
+  // knows what to wait for.
+  const answer = await ctx.waitFor<{ keep: boolean }>(retentionToken(requestedBy), {
+    timeoutMs: RETENTION_WINDOW_MS,
+  });
 
   if (answer?.keep === true) return { kept: true, answered: true };
-  await discardTranscript(transcriptId);
+  await ctx.step("discardOnDecline", () => discardTranscript(transcriptId));
   // Drop the undo now that the run has DONE what it undoes. Leaving it would be
   // harmless (`discardTranscript` treats a 404 as success, as every compensation
   // must) and would still be wrong to read: an unwind that reverses something
@@ -331,14 +502,26 @@ export async function askWhetherToKeep(
  * reported and stepped over rather than thrown. The `label` is what makes that
  * report actionable.
  */
-export async function compensate(compensations: Compensation[], because: string): Promise<void> {
+export async function compensate(
+  compensations: Compensation[],
+  because: string,
+  ctx: WorkflowCtx,
+): Promise<void> {
   if (compensations.length === 0) return;
-  await note(`Recap failed (${because}) — undoing ${compensations.length} step(s).`);
+  // The narration is a STEP like every other, so an unwind interrupted by a
+  // crash resumes with the lines already said replayed from the journal rather
+  // than said twice. Each undo is a step too — registered as one by whoever
+  // stacked it — which is what makes an interrupted unwind resumable at all.
+  await ctx.step("noteUnwind", () =>
+    note(`Recap failed (${because}) — undoing ${compensations.length} step(s).`),
+  );
   for (const compensation of compensations) {
     try {
       await compensation.undo();
     } catch (err) {
-      await note(`Could not undo ${compensation.label}: ${errorMessage(err)}`);
+      await ctx.step("noteUndoFailed", () =>
+        note(`Could not undo ${compensation.label}: ${errorMessage(err)}`),
+      );
     }
   }
 }
@@ -349,11 +532,26 @@ export async function compensate(compensations: Compensation[], because: string)
  * Hand the recording to the provider.
  *
  * Returns in milliseconds with a job id — the batch API's whole shape, and what
- * makes the poll below a real wait rather than a simulated one.
+ * makes the wait below a real wait rather than a simulated one.
+ *
+ * `webhookUrl` is where the provider should POST when the job settles, and
+ * {@link callbackUrl} is what produces it. The body passes the result IN rather
+ * than this minting it, which keeps every HTTP decision in a function a spec can
+ * call with a plain string — and keeps the mint in one place.
+ *
+ * **It answers `callback` as well as `id`, and that is a determinism
+ * requirement rather than a convenience.** Whether a callback was registered
+ * decides whether {@link awaitTranscript} parks on a hook, and a body may only
+ * branch on values that come out of the JOURNAL — so the fact is returned by the
+ * step that established it. Reading it in the body instead would re-evaluate it
+ * on every replay, and a redeploy that changed the deployment's public URL
+ * mid-run would flip the branch: the walk would then look for a `waitFor` the
+ * journal never recorded, or skip one it did.
  */
-export async function submitRecording(url: string): Promise<{ id: string }> {
-  "use step";
-
+export async function submitRecording(
+  url: string,
+  webhookUrl?: string,
+): Promise<{ id: string; callback: boolean }> {
   await report(`Submitting ${new URL(url).hostname} for transcription…`);
 
   // `stepTranscribeSubmitClassified` owns the endpoint, the raw-key auth, the
@@ -362,8 +560,56 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
   // `throwStepError` already applied, so a provider refusal stays terminal and a
   // rate limit waits out the delay the provider itself named. `speaker_labels`
   // is this desk's own request, which is what `params` is for — the async API's
-  // surface is large and the SDK deliberately does not mirror it.
-  return await stepTranscribeSubmitClassified(url, { params: { speaker_labels: true } });
+  // surface is large and the SDK deliberately does not mirror it, and
+  // `webhook_url` is a second field on the same passthrough.
+  //
+  // No `omitUndefined` here, unlike `checkTranscript` below, and the difference
+  // is which boundary the value crosses: `params` is serialized, and
+  // `JSON.stringify` drops a property whose value is `undefined` — so an absent
+  // callback is an absent KEY on the wire, which is what the provider needs.
+  // What must not creep in is a `?? null` or a `?? ""` to "be explicit": either
+  // one puts the key back, and a provider handed a null for a URL is entitled to
+  // refuse the whole submission.
+  const job = await stepTranscribeSubmitClassified(url, {
+    params: { speaker_labels: true, webhook_url: webhookUrl },
+  });
+  return { id: job.id, callback: webhookUrl !== undefined };
+}
+
+/**
+ * The URL the provider should POST to when this run's transcript is ready, or
+ * `undefined` when this deployment cannot offer one.
+ *
+ * `stepWebhookUrl` (`@alexkroman1/aai/step`) is the step-side half of
+ * `ctx.workflows.publicWebhookUrl` — one concept, two surfaces — and it exists
+ * because a workflow body and the steps it calls are handed no `ToolContext`.
+ * Note it cannot be replaced by `requireStepEnv("AAI_PUBLIC_BASE_URL")`: the
+ * public base URL is a boot parameter of the DEPLOYMENT, living in the guest's
+ * exec env, while the step env is the tenant's own `.env` and
+ * `aai secret put` keys — so that read is `undefined` in production precisely
+ * where the value exists.
+ *
+ * **It THROWS rather than answering `undefined`, and catching it is the whole
+ * job of this function.** A callback URL has no legitimate default — it is
+ * either the one a third party can reach or it is a lie — so the SDK refuses to
+ * invent one. What a template must not do is let that throw reach the step: the
+ * recap would fail over a missing optimization. So the throw is converted to
+ * "no callback", which puts the run on the poll arm it used to be on always.
+ *
+ * The cases with no usable URL are a self-hosted server started without
+ * `publicUrl`, any spec (which publishes no minter), and **local development
+ * either way**: `aai dev`'s origin is a `localhost` one, so it either throws or
+ * mints a URL no third party can dial. So a local run always exercises the poll
+ * arm. Point a tunnel at the dev server's BACKEND port — the Vite port a
+ * developer opens does not proxy `/.well-known/` — and set `PUBLIC_URL` to it to
+ * exercise the callback at all.
+ */
+export function callbackUrl(token: string): string | undefined {
+  try {
+    return stepWebhookUrl(token);
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -385,8 +631,6 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
  * template.
  */
 export async function checkTranscript(id: string): Promise<TranscriptState> {
-  "use step";
-
   const response = await request(`${TRANSCRIPT_ENDPOINT}/${id}`);
   const body = await response.json();
   const status = readString(body, "status");
@@ -426,8 +670,6 @@ export async function checkTranscript(id: string): Promise<TranscriptState> {
  * a replay is exactly that world.
  */
 export async function discardTranscript(id: string): Promise<void> {
-  "use step";
-
   await report(`Discarding transcript ${id}.`);
   // Not through `request` above, because a 404 is a SUCCESS here — see below.
   // `stepFetch` for the same reason it does; only the status handling differs.
@@ -454,8 +696,6 @@ export async function discardTranscript(id: string): Promise<void> {
  * journal instead of submitting the recording again.
  */
 export async function summarize(url: string, transcript: TranscriptState): Promise<Recap> {
-  "use step";
-
   await report("Writing the recap.");
 
   const text = (transcript.text ?? "").slice(0, MAX_TRANSCRIPT_CHARS);
@@ -489,9 +729,6 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
   };
 }
 
-/** A rate limit — and a model that ignored the format — are both expected here. */
-summarize.maxRetries = 5;
-
 /**
  * Say one line into the run's progress channel.
  *
@@ -501,7 +738,6 @@ summarize.maxRetries = 5;
  * `recap_progress` is what reads it back down the phone.
  */
 export async function note(line: string): Promise<void> {
-  "use step";
   await report(line);
 }
 

package/dist/templates/recap-workflow/workflows/tokens.ts

@@ -24,3 +24,24 @@
 export function retentionToken(sessionId: string): string {
   return `retention:${sessionId}`;
 }
+
+/**
+ * The nudge that says a transcript is ready.
+ *
+ * The other end of this one is not a tool but ASSEMBLYAI: `request_recap` mints
+ * `ctx.workflows.publicWebhookUrl(transcriptToken(ctx.sessionId))` and hands it
+ * to the provider as `webhook_url`, and the provider's `POST` to that URL is
+ * what resolves the body's wait. So the two sides that have to agree are a file
+ * in this template and a third party on the public internet — which is the
+ * strongest case there is for deriving the string in one place.
+ *
+ * **A token is held for the life of its run and given back only when the run
+ * goes TERMINAL**, so deriving it from the session is what makes a second recap
+ * in the same call legal: `claimHook` refuses a token another run still holds,
+ * and a refusal is not a suspend, so it would unwind the saga and delete the
+ * transcript the run was waiting for. `request_recap` allows one LIVE run per
+ * caller, which is the invariant that keeps this safe.
+ */
+export function transcriptToken(sessionId: string): string {
+  return `transcript:${sessionId}`;
+}

package/dist/templates/redline/agent.eval.test.ts

@@ -25,7 +25,7 @@
 // evidence.
 //
 // 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 a rate-limited live run FAILS
 // where a deployed one would have ridden it out. The tier that really resumes a
 // run is `aai-cli`'s `dev-workflow.scenario.test.ts`.

package/dist/templates/redline/agent.test.ts

@@ -17,10 +17,10 @@
  * of that lives.
  */
 
+import { FatalError } from "@alexkroman1/aai/step-errors";
 import { parseSchemaInput, schemaInputIssues } from "@alexkroman1/aai/testing";
 import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { FatalError } from "workflow";
 import agentDef, { MAX_ROUNDS, redline } from "./agent.ts";
 import {
   briefBlock,