@alexkroman1/aai-cli 10.0.0 → 11.0.0

package/dist/templates/research-workflow/agent.test.ts

@@ -4,20 +4,26 @@
 /**
  * Specs for the research desk's four tools.
  *
- * All are exercised against a STUBBED `ctx.workflows`, which is the only honest
- * way to unit-test them: the real client needs a Workflow DevKit world, and the
- * bodies in `workflows/` are only durable once the build has transformed them.
+ * All are exercised against a STUBBED `ctx.workflows`, which is the honest way
+ * to unit-test a TOOL: what a tool owns is the call it makes, not what the run
+ * does afterwards.
  * What these assert is the agent's half of the contract — that the handoff tool
  * passes the correlation key, that the status tool narrows a snapshot correctly
  * before reading it aloud, and that the two tools reaching PAST a status (the
  * progress stream, the early wake) ask for what a voice reply can use.
  *
- * The STEPS are exercised separately, and directly: imported through vitest with
- * a step is an ordinary exported async function,
- * so its prompt handling, its parsing and its `FatalError` guards are all
- * testable — while durability, suspension and replay are not. The body itself is
- * not driven here for that reason; `aai-cli`'s `dev-workflow.scenario.test.ts`
- * builds a project and runs one.
+ * The STEPS are exercised separately, and directly: a step is an ordinary
+ * exported async function, so its prompt handling, its parsing and its
+ * `FatalError` guards are all testable without an engine.
+ *
+ * The BODY is driven here only through `createWorkflowCtx`, which records what
+ * it asked for and replays nothing. That is a choice rather than a limit now:
+ * `runWorkflow` from `@alexkroman1/aai-runtime/testing` will run this body on
+ * the real engine, and `link-digest` is the template that shows it — three
+ * steps and one suspension, where this desk's body is six model steps deep and a
+ * durable spec of it would be mostly stubs. `aai-cli`'s
+ * `dev-workflow.scenario.test.ts` is the tier above both, with a built project
+ * and a real queue.
  */
 
 import type { WorkflowClient } from "@alexkroman1/aai";
@@ -34,6 +40,7 @@ import {
 import { mockWorkflows, installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
+import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { research } from "./shared.ts";
 import {
@@ -42,6 +49,7 @@ import {
   findGaps,
   investigate,
   planAngles,
+  REVIEW_DELAY_MS,
   researchFlow,
   writeBrief,
   writeReport,
@@ -538,3 +546,117 @@ describe("the steps that research", () => {
     ).rejects.toThrow(/empty completion/);
   });
 });
+
+/**
+ * `researchFlow` itself, on the real replay engine.
+ *
+ * The block above drives this body through `createWorkflowCtx`, which records
+ * what it ASKED for and replays nothing — right for the retry policy and the
+ * step order, and silent about the desk's actual promise: **answer the caller
+ * now, finish the work later**. `runWorkflow`
+ * (`@alexkroman1/aai-runtime/testing`) is the engine `aai dev` runs, over an
+ * in-memory journal, so the review wait really suspends and the resume really
+ * comes off the journal.
+ *
+ * The model is scripted POSITIONALLY, which is only safe because the run is made
+ * sequential: one angle, and a researcher that stops on its first turn, so the
+ * `mapConcurrent` fan-out has a single item and nothing races. A case that wants
+ * two angles at once wants a router keyed on the system prompt instead — the
+ * shape `link-digest` uses — because the order two concurrent step bodies reach
+ * the gateway in is the scheduler's business.
+ *
+ * Five calls make a whole run: the brief, the angles, the researcher's first
+ * action, the gap pass, and the report — plus its summary, which is a second
+ * call on the same step.
+ */
+describe("the run is DURABLE", () => {
+  const SCRIPT = [
+    // writeBrief
+    JSON.stringify({ brief: "How otters use tools", criteria: ["Which species"] }),
+    // planAngles — ONE, so the fan-out is sequential and the script positional.
+    JSON.stringify({ angles: ["Tool use"] }),
+    // investigate#0's first action: stop, which also skips `compress` (nothing
+    // was seen, so there is nothing to compress).
+    JSON.stringify({ action: "stop", why: "nothing to add" }),
+    // findGaps — none, so there is no second wave.
+    JSON.stringify({ angles: [] }),
+    // writeReport, then its summary.
+    "The report about otters.",
+    "Otters use tools.",
+  ];
+  const INPUT = { topic: "otters", requestedBy: "sess_1" };
+
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  test("suspends on the review wait with the whole report already journaled", async () => {
+    const started = Date.now();
+    const model = stubGateway(SCRIPT);
+    const run = await runWorkflow(research, INPUT, { name: "research" });
+
+    // Not blocked — suspended. The sandbox is free here, which is the whole
+    // reason a caller can hang up.
+    expect(run.status).toBe("running");
+    expect(run.wakeAt).toBeGreaterThanOrEqual(started + REVIEW_DELAY_MS);
+    // Everything except the filing is durable already, and `file` has not run.
+    expect(run.steps.map((step) => step.key)).toEqual([
+      "findGaps#0",
+      "investigate#0",
+      "planAngles#0",
+      "writeBrief#0",
+      "writeReport#0",
+    ]);
+    expect(model).toHaveLength(6);
+  });
+
+  test("resumes past the review wait and files, without researching again", async () => {
+    const model = stubGateway(SCRIPT);
+    const run = await runWorkflow(research, INPUT, { name: "research" });
+    // `advanceSleep` is `ctx.workflows.wakeUp`'s own mechanism, which is what
+    // the `file_it_now` tool calls to cut the review short — so this is that
+    // tool's effect, asserted on the run rather than on the tool.
+    await run.advanceSleep();
+
+    expect(run.status).toBe("completed");
+    expect(run.output).toMatchObject({
+      topic: "otters",
+      summary: "Otters use tools.",
+      report: "The report about otters.",
+      angles: ["Tool use"],
+    });
+    expect(run.output?.filedAt).toBeTruthy();
+    expect(run.deliveries).toBe(2);
+    // The second walk re-entered the body from the top and paid the model
+    // NOTHING: every step above the wait came back out of the journal.
+    expect(model).toHaveLength(6);
+  });
+
+  test("a worker that dies at the report replays the research rather than repeating it", async () => {
+    // The expensive claim. A deep-research pass is five to twelve model calls
+    // and as many searches; a resume that redid them would cost the run twice.
+    const model = stubGateway(SCRIPT);
+    const run = await runWorkflow(research, INPUT, {
+      name: "research",
+      crashAt: "writeReport",
+    });
+
+    expect(run.crashed).toBe(true);
+    expect(run.steps.map((step) => step.key)).toEqual([
+      "findGaps#0",
+      "investigate#0",
+      "planAngles#0",
+      "writeBrief#0",
+    ]);
+    const spentBeforeTheCrash = model.length;
+    expect(spentBeforeTheCrash).toBe(4);
+
+    await run.restart();
+    await run.advanceSleep();
+    expect(run.status).toBe("completed");
+    // Six in total: the four the crash already paid for came back out of the
+    // journal, and only the report and its summary were re-issued.
+    expect(model).toHaveLength(6);
+    expect(run.output?.report).toBe("The report about otters.");
+  });
+});

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

@@ -246,7 +246,7 @@ export async function researchFlow(
   // Suspended, not blocked. On resume the body re-runs from the top and every
   // step above returns its journaled result rather than researching again —
   // which is also what `file_it_now` ends early, through `ctx.workflows.wakeUp`.
-  await ctx.sleep(REVIEW_DELAY_MS);
+  await ctx.sleep("reviewWindow", REVIEW_DELAY_MS);
 
   // Whatever this returns is what `ctx.workflows.get(runId)` reports as `output`
   // on a completed run — so it is what the agent reads back, and what the

package/dist/templates/retail/client.tsx

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { AgentState, ConversationItem } from "@alexkroman1/aai-ui";
+import type { AgentState, ConversationItem, Session } from "@alexkroman1/aai-ui";
 import {
   AutoScroll,
   client,
@@ -417,8 +417,21 @@ function ErrorBanner() {
   );
 }
 
+/**
+ * Start a fresh conversation without leaving the console.
+ *
+ * Written out here rather than reached for on the session, because there is no
+ * one method that does it: `reset()` clears the CONVERSATION and keeps the
+ * session, which is wrong for any agent that also keeps session-scoped state —
+ * this one's store would come back with the next tool call.
+ */
+function newConversation(session: Session): void {
+  session.end();
+  session.start();
+}
+
 /** The call controls: the one place a whole-session read is what is wanted —
- *  `started`, `running` and three methods, in three buttons. */
+ *  `started`, `running` and four methods, in four buttons. */
 function CallControls({ productCount }: { productCount: number }) {
   const session = useSession();
   return (
@@ -448,6 +461,21 @@ function CallControls({ productCount }: { productCount: number }) {
           >
             {session.running ? "Hold" : "Resume"}
           </button>
+          {/* The one-click new conversation the default shell's
+              `<Controls>` gives every other template — a custom
+              `component:` renders no `<Controls>`, so a console like
+              this one has to say it itself. end() then start(), so the
+              redial is a brand-new session (fresh store, greeting
+              included) and the console stays on the call rather than
+              dropping back to "Start call". */}
+          <button
+            type="button"
+            className="px-4 py-2 rounded-md text-xs font-semibold cursor-pointer"
+            style={{ background: "#ffffff", color: "#18181b", border: "1px solid #e4e4e7" }}
+            onClick={() => newConversation(session)}
+          >
+            New Conversation
+          </button>
           {/* end() hangs up and flips `started` back, so the UI
               returns to "Start call" and the next start is a brand-new
               session (fresh store, greeting included). reset() would

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

@@ -271,7 +271,10 @@ describeWorkflowEval(
       expect(run.output?.transcript).toBe(TRANSCRIPT);
       // Two waits for three polls: asked for and — this being an eval rather
       // than a deployment — recorded rather than taken.
-      expect(run.slept).toEqual([{ duration: POLL_INTERVAL_MS }, { duration: POLL_INTERVAL_MS }]);
+      expect(run.slept).toEqual([
+        { label: "poll", duration: POLL_INTERVAL_MS },
+        { label: "poll", duration: POLL_INTERVAL_MS },
+      ]);
       expect(provider.calls.filter((call) => call.leg === "poll")).toHaveLength(3);
       // The expensive half happened ONCE, which is the whole reason the upload
       // and the submit are separate steps.

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

@@ -2,13 +2,14 @@
 /**
  * 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: 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
- * `dev-workflow.scenario.test.ts`.
+ * The four legs are ordinary exported async functions, so their HTTP handling,
+ * their fatal/retryable classification and what they return are all testable
+ * directly. **And the body IS driven**, on the real replay engine — the last
+ * block — which this file used to say was another tier's job. It is still true
+ * that a body test dressed up as a durability test would be the worse failure;
+ * what changed is that the durable one is available, so the claim can be made
+ * honestly rather than deferred. `aai-cli`'s `dev-workflow.scenario.test.ts`
+ * remains the tier above, with a built project and a real queue.
  *
  * The two legs worth their own sections are the ones the SDK grew for this
  * template. `speak` is where a step SPEAKS and STORES, and the assertion that
@@ -18,7 +19,7 @@
 
 import { readUpload, uploadInfo } from "@alexkroman1/aai/step";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx } from "@alexkroman1/aai/testing";
+import { createWorkflowCtx, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -26,6 +27,7 @@ import {
   installStubTranscribe,
   installStubUploads,
 } from "@alexkroman1/aai/testing/vitest";
+import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import agentDef, { spokenSummary } from "./agent.ts";
 import { speak, spokenSummaryFlow, summarize } from "./workflows/summarize.ts";
@@ -313,3 +315,110 @@ describe("the whole run", () => {
     );
   });
 });
+
+/**
+ * The whole run, on the real replay engine.
+ *
+ * `runWorkflow` (`@alexkroman1/aai-runtime/testing`) starts the declared
+ * workflow on the engine `aai dev` uses, over an in-memory journal, and records
+ * a suspension rather than waiting it out. That is what makes the poll cadence
+ * — fifteen seconds a turn in a deployment — free here, and it is the only tier
+ * at which this app's central claim is checkable: **the recording is uploaded
+ * and transcribed ONCE**, however many times the body is walked.
+ *
+ * Three published slots have to agree for a whole run, and one of them is a
+ * shared seam: `stubTranscribe` publishes `stepFetch`, and publishing REPLACES —
+ * so the model call cannot have a stub of its own and is routed through
+ * `otherwise` instead. `installStubSpeech` and `installStubUploads` are
+ * different slots and compose freely.
+ */
+describe("the run is DURABLE", () => {
+  const SUMMARY = JSON.stringify({
+    headline: "Launch is on",
+    points: ["Ship Tuesday"],
+    spoken: "The launch is on for Tuesday.",
+  });
+
+  /** The provider, the model and the voice — one world for a whole run. */
+  function stubWorld({ pendingPolls = 0 } = {}) {
+    const model = stubGatewayRoute(SUMMARY);
+    const provider = installStubTranscribe({
+      pendingPolls,
+      text: "We shipped it on Tuesday.",
+      durationSec: 30,
+      // Anything that is not a transcription leg — which here is the model call
+      // — because this fake owns the one published `stepFetch`.
+      otherwise: (request) => model.route(request),
+    });
+    const speech = installStubSpeech({ pcmBytes: 48_000 });
+    installStubReporter();
+    return { model, provider, speech };
+  }
+
+  const INPUT = { recording: UPLOAD_ID };
+
+  test("uploads, submits, then parks on the poll cadence", async () => {
+    const world = stubWorld({ pendingPolls: 1 });
+    const started = Date.now();
+    const run = await runWorkflow(spokenSummary, INPUT, { name: "spokenSummary" });
+
+    expect(run.status).toBe("running");
+    expect(run.wakeAt).toBeGreaterThan(started);
+    expect(run.steps.map((step) => step.key)).toEqual([
+      "createJob#0",
+      "pollTranscript#0",
+      "uploadToProvider#0",
+    ]);
+    // The recording has crossed the wire once. It is the expensive step — it
+    // streams the whole file, which is why it is the one with extra patience.
+    expect(world.provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+  });
+
+  test("resumes past the poll and finishes, without re-uploading the recording", async () => {
+    const world = stubWorld({ pendingPolls: 1 });
+    const run = await runWorkflow(spokenSummary, INPUT, { name: "spokenSummary" });
+    await run.advanceSleep();
+
+    expect(run.status).toBe("completed");
+    expect(run.output).toMatchObject({
+      headline: "Launch is on",
+      points: ["Ship Tuesday"],
+      transcript: "We shipped it on Tuesday.",
+      // An ID, never the bytes: audio in a journaled step result is megabytes
+      // replayed on every resume.
+      audio: "upl_stub_1",
+    });
+    expect(run.deliveries).toBe(2);
+    // ONE upload and ONE submit across two walks — both came back out of the
+    // journal on the second.
+    expect(world.provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+    expect(world.provider.calls.filter((call) => call.leg === "submit")).toHaveLength(1);
+    // Two polls, which is the loop doing its job: `pollTranscript#0` was
+    // journaled and `#1` is the one that found it done.
+    expect(run.steps.filter((step) => step.name === "pollTranscript")).toHaveLength(2);
+  });
+
+  test("a worker that dies at the voice keeps the transcript and the summary", async () => {
+    // The whole point of three steps rather than one: reading a summary aloud
+    // is cheap, transcribing a recording is not, and a crash at the cheap end
+    // must not buy the expensive one again.
+    const world = stubWorld();
+    const run = await runWorkflow(spokenSummary, INPUT, {
+      name: "spokenSummary",
+      crashAt: "speak",
+    });
+
+    expect(run.crashed).toBe(true);
+    expect(run.steps.map((step) => step.name)).toContain("summarize");
+    expect(world.speech.calls).toHaveLength(0);
+
+    await run.restart();
+    expect(run.status).toBe("completed");
+    expect(run.output?.audio).toBe("upl_stub_1");
+    // The voice ran once, and neither the provider nor the model was asked
+    // again.
+    expect(world.speech.calls).toHaveLength(1);
+    expect(world.provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+    expect(world.model.calls).toHaveLength(1);
+  });
+});

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

@@ -172,7 +172,7 @@ async function transcribe(recording: string, ctx: WorkflowCtx): Promise<Transcri
     // rather than starting the wait over.
     const progress = await ctx.step("pollTranscript", () => pollTranscript(recording, job.id));
     if (progress.done) return progress.transcript;
-    await ctx.sleep(POLL_INTERVAL_MS);
+    await ctx.sleep("poll", 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

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

@@ -3,13 +3,15 @@
  * Specs for the transcription desk's declaration, its WAV arithmetic, and its
  * steps.
  *
- * **The body itself is not driven here, and that is a property of what this
- * template demonstrates rather than a gap in the spec.** A step is an ordinary
- * exported async function — so its retries, its `FatalError` guards, its HTTP handling and its
- * merge 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
- * `dev-workflow.scenario.test.ts`, which builds a project and runs one.
+ * A step is an ordinary exported async function, so its retries, its
+ * `FatalError` guards, its HTTP handling and its merge are all testable
+ * directly. **And one of the three bodies IS driven**, on the real replay
+ * engine — `transcribeBatch`, in the last block, which is the flow that reaches
+ * no ffmpeg. The other two normalize the recording first and this repo's test
+ * environment has no ffmpeg, so their durability stays `aai-cli`'s
+ * `dev-workflow.scenario.test.ts`'s. Saying which of the three is covered is
+ * the point: a body test dressed up as a durability test would be the worse
+ * failure, and so would a durable one that implied it covered all three.
  *
  * The WAV half is worth its own section because it is where a silent bug lives:
  * a cut that lands mid-frame, or an off-by-one in the chunk walk, produces audio
@@ -27,6 +29,7 @@ import {
   installStubTranscribe,
   installStubUploads,
 } from "@alexkroman1/aai/testing/vitest";
+import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { z } from "zod";
 import agentDef, { transcribe, transcribeBatch, transcribeStream } from "./agent.ts";
@@ -77,10 +80,10 @@ const UPLOAD_ID = "upl_test";
 /**
  * A fixed run-start epoch, so `elapsedMs` is assertable at all.
  *
- * `startClock` is a step in production; a spec supplies the value directly, which is
- * the point of threading it as an argument rather than reading a clock inside the
- * merge — the duration is then a function of journaled values and not of how long the
- * test took.
+ * The body reads it with `ctx.now()`, which the engine journals; a spec supplies
+ * the value directly, which is the point of threading it as an argument rather
+ * than reading a clock inside the merge — the duration is then a function of
+ * journaled values and not of how long the test took.
  */
 const STARTED_AT = 1_000_000;
 
@@ -946,7 +949,6 @@ describe("transcribeSegment", () => {
     const ctx = createWorkflowCtx({
       runSteps: false,
       results: {
-        startClock: 0,
         normalizeRecording: { recording: UPLOAD_ID, converted: false },
         splitRecording: { format: FORMAT, segments: [SEGMENT], durationMs: 1000 },
         transcribeSegment: { index: 0, text: "hello" },
@@ -977,7 +979,7 @@ describe("transcribeSegment", () => {
     // And the two that take the default, which is the other half of the claim.
     // Asserted as PRESENT-with-no-budget rather than as `get(…) === undefined`,
     // which a step the body never reached at all would also satisfy.
-    for (const name of ["startClock", "splitRecording"]) {
+    for (const name of ["mergeTranscript", "splitRecording"]) {
       expect(budgets.has(name)).toBe(true);
       expect(budgets.get(name)).toBeUndefined();
     }
@@ -1759,3 +1761,115 @@ describe("nextPollDelay", () => {
     expect(delay).toBe(5000);
   });
 });
+
+/**
+ * `transcribeBatch`, on the real replay engine.
+ *
+ * The batch flow is the one of this desk's three that reaches no ffmpeg — it
+ * uploads, submits and polls — so it is the one a unit spec can drive end to
+ * end. `transcribe` and `transcribeStream` both normalize the recording first,
+ * and this repo's test environment has no ffmpeg (the `normalizeRecording` specs
+ * above assert the FatalError that produces). Their durability is
+ * `aai-cli`'s `dev-workflow.scenario.test.ts`'s to cover; what is asserted here
+ * is the half that is honestly reachable, which is better than a body test
+ * dressed up as a durability test.
+ *
+ * Two claims, and the second is the one no other tier can make:
+ *
+ * - **The recording is uploaded ONCE**, however many times the body is walked.
+ *   That is why the upload is a step of its own with a raised attempt budget.
+ * - **`ctx.now()` is JOURNALED**, so `startedAt` — which the poll step subtracts
+ *   to report `elapsedMs` — is the instant the run really began and not the
+ *   instant the latest walk began. A body that read `Date.now()` there would
+ *   report a shrinking elapsed on every resume, which is `guard-invariants`
+ *   rule 30 and the whole reason the affordance exists.
+ */
+describe("the batch run is DURABLE", () => {
+  const INPUT = { recording: UPLOAD_ID };
+
+  beforeEach(() => {
+    installStubUploads({
+      [UPLOAD_ID]: { bytes: new Uint8Array(4096), name: "standup.wav", type: "audio/wav" },
+    });
+    installStubReporter();
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+  });
+
+  test("parks on the poll cadence with the upload already journaled", async () => {
+    const provider = installStubTranscribe({ pendingPolls: 1, text: "We shipped it." });
+    const started = Date.now();
+    const run = await runWorkflow(transcribeBatch, INPUT, { name: "transcribeBatch" });
+
+    expect(run.status).toBe("running");
+    expect(run.wakeAt).toBeGreaterThan(started);
+    expect(run.steps.map((step) => step.key)).toEqual([
+      "createJob#0",
+      "pollTranscript#0",
+      "uploadToProvider#0",
+    ]);
+    // The clock the body read alongside the upload is journaled too, in its own
+    // reserved key space — `run.reads`, not `run.steps`.
+    expect(run.reads.map((read) => read.key)).toEqual(["now!0"]);
+    expect(provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+  });
+
+  test("resumes past the poll without moving the recording again", async () => {
+    const provider = installStubTranscribe({ pendingPolls: 1, text: "We shipped it." });
+    const run = await runWorkflow(transcribeBatch, INPUT, { name: "transcribeBatch" });
+    await run.advanceSleep();
+
+    expect(run.status).toBe("completed");
+    expect(run.output).toMatchObject({
+      transcript: "We shipped it.",
+      // ONE, which is the difference this flow exists to show against the two
+      // that segment.
+      segments: 1,
+      source: "standup.wav",
+    });
+    expect(run.deliveries).toBe(2);
+    // The whole recording crossed the wire once, on the first walk.
+    expect(provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+    expect(provider.calls.filter((call) => call.leg === "submit")).toHaveLength(1);
+  });
+
+  test("reports the elapsed from the run's OWN start, not the resuming walk's", async () => {
+    // The affordance's claim. `ctx.now()` is journaled under its own key, so the
+    // second walk re-reads the first walk's instant — and `elapsedMs`, which the
+    // poll step computes as `Date.now() - startedAt`, therefore counts the whole
+    // run rather than the delivery it finished on.
+    const provider = installStubTranscribe({ pendingPolls: 1, text: "We shipped it." });
+    const run = await runWorkflow(transcribeBatch, INPUT, { name: "transcribeBatch" });
+    await run.advanceSleep();
+
+    expect(run.status).toBe("completed");
+    // A journaled clock cannot go backwards across a resume, and a re-read one
+    // routinely would — the second walk starts later than the first.
+    expect(run.output?.elapsedMs).toBeGreaterThanOrEqual(0);
+    expect(provider.calls.filter((call) => call.leg === "poll")).toHaveLength(2);
+  });
+
+  test("a worker that dies before the job is created re-uploads, because nothing settled", async () => {
+    // The other side of exactly-once, and the honest one: a step whose entry was
+    // never written IS re-run, because the journal is what makes a step skippable
+    // and a crashed one left none.
+    const provider = installStubTranscribe({ text: "We shipped it." });
+    const run = await runWorkflow(transcribeBatch, INPUT, {
+      name: "transcribeBatch",
+      crashAt: "createJob",
+    });
+
+    expect(run.crashed).toBe(true);
+    expect(run.steps.map((step) => step.name)).toEqual(["uploadToProvider"]);
+    // The clock the body read in the same `Promise.all` survived the crash with
+    // it, which is what makes the resumed run's elapsed the WHOLE run's.
+    expect(run.reads.map((read) => read.key)).toEqual(["now!0"]);
+    expect(provider.calls.filter((call) => call.leg === "submit")).toHaveLength(0);
+
+    await run.restart();
+    expect(run.status).toBe("completed");
+    // The upload SURVIVED — it settled before the crash — and only the job
+    // creation was re-issued.
+    expect(provider.calls.filter((call) => call.leg === "upload")).toHaveLength(1);
+    expect(provider.calls.filter((call) => call.leg === "submit")).toHaveLength(1);
+  });
+});

package/dist/templates/transcription-workflow/workflows/batch.ts

@@ -61,7 +61,7 @@ import {
   stepTranscribeUploadClassified,
 } from "@alexkroman1/aai/step-errors";
 import { countWords, formatBytes } from "@alexkroman1/aai/utils";
-import { startClock, type Transcript } from "./transcribe.ts";
+import type { Transcript } from "./transcribe.ts";
 
 /** How long between polls of a submitted job. */
 const POLL_INTERVAL_MS = 10_000;
@@ -88,7 +88,7 @@ export async function transcribeBatchFlow(
   // one call here worth another attempt: it moves the whole recording, and a lost
   // connection on a file this size is the expected failure.
   const [startedAt, { audioUrl }] = await Promise.all([
-    ctx.step("startClock", () => startClock()),
+    ctx.now(),
     ctx.step("uploadToProvider", () => uploadToProvider(input.recording), { maxAttempts: 6 }),
   ]);
   const job = await ctx.step("createJob", () => createJob(audioUrl));
@@ -98,7 +98,7 @@ export async function transcribeBatchFlow(
       pollTranscript(input.recording, job.id, startedAt),
     );
     if (progress.done) return progress.transcript;
-    await ctx.sleep(POLL_INTERVAL_MS);
+    await ctx.sleep("poll", POLL_INTERVAL_MS);
   }
   // A plain throw: this is the BODY, where the fatal/retryable distinction has
   // nothing to apply to — see `stream.ts`'s `abandon` for the same reasoning.
@@ -175,9 +175,9 @@ export async function pollTranscript(
       // The provider's own measurement — the only one of the three flows that does
       // not have to derive this from byte offsets.
       durationMs: progress.transcript.durationMs,
-      // Wall clock, the same way both sync flows measure it — see `startClock`. For
-      // this flow it is mostly the provider's queue, which is exactly the thing a
-      // reader comparing the three wants to see.
+      // Wall clock, the same way both sync flows measure it — the body's
+      // `ctx.now()`, subtracted inside this step. For this flow it is mostly the
+      // provider's queue, which is exactly the thing a reader wants to see.
       elapsedMs: Date.now() - startedAt,
       words: countWords(transcript),
       transcript,

package/dist/templates/transcription-workflow/workflows/stream.ts

@@ -182,7 +182,6 @@ import {
   mergeTranscript,
   type SegmentTranscript,
   segmentConcurrency,
-  startClock,
   transcribeSegment,
 } from "./transcribe.ts";
 import {
@@ -288,7 +287,9 @@ export type StreamPlan = {
  * it and the bytes are still on their way.
  */
 export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowCtx) {
-  const startedAt = await ctx.step("startClock", () => startClock());
+  // `ctx.now()`, not a step: the engine journals the read under its own key, so
+  // every walk of this line sees the instant the first one did.
+  const startedAt = await ctx.now();
   let plan: StreamPlan | undefined;
   // Body state, and legal because every value in it came out of a journaled step
   // result — a replay rebuilds the identical sets in the identical order.
@@ -380,7 +381,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
     // Sleep until the next segment should HAVE landed, rather than for a fixed
     // interval — see `nextPollDelay`. Both arguments are journaled step results,
     // so a replay computes the same delay from the same two samples.
-    await ctx.sleep(nextPollDelay(at, previous, plan, done));
+    await ctx.sleep("poll", nextPollDelay(at, previous, plan, done));
     previous = at;
   }