@alexkroman1/aai-cli 9.2.0 → 10.0.0

package/dist/scaffold/server.mjs

@@ -20,6 +20,7 @@ import { parseEnv } from "node:util";
 import {
   createAgentServer,
   ensureSessionStateSchema,
+  ensureWorkflowJournalSchema,
   withHostCredentialFallback,
 } from "@alexkroman1/aai-runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
@@ -61,20 +62,6 @@ if (!existsSync(workerPath)) {
 const worker = await import(pathToFileURL(workerPath).href);
 const agent = worker.default;
 
-/**
- * The compiled workflow surface, carried on the bundle as two string exports.
- *
- * A `"use workflow"` body has to go through the DevKit's compiler, which happens
- * at BUILD time — a deployed agent is handed one ESM string and has no bundler —
- * so `aai build` leaves the result here as data. Passing them is what makes
- * durable workflows actually run: without them the server accepts a run and no
- * world is ever started to execute it, so it sits `pending` with no error
- * anywhere. Both are absent for a project with no `workflows/` directory.
- */
-const workflowCode =
-  typeof worker.__aaiWorkflowCode === "string" ? worker.__aaiWorkflowCode : undefined;
-const stepCode = typeof worker.__aaiStepCode === "string" ? worker.__aaiStepCode : undefined;
-
 /**
  * Parse a dotenv-syntax file into a record; `{}` when it does not exist.
  *
@@ -167,6 +154,10 @@ const publicUrl = process.env.PUBLIC_URL?.trim();
  */
 if (env.DATABASE_URL) {
   await ensureSessionStateSchema({ url: env.DATABASE_URL, logger: console });
+  // And the durable-run journal's, which is a separate set of tables owned by
+  // the same deployment. Without it a project with a `DATABASE_URL` boots
+  // claiming durable runs and fails on the first one.
+  await ensureWorkflowJournalSchema({ url: env.DATABASE_URL, logger: console });
 }
 
 const server = createAgentServer({
@@ -178,16 +169,14 @@ const server = createAgentServer({
   providerEnv: withHostCredentialFallback(env),
   clientDir: resolveClientDir(),
   ...(publicUrl ? { publicUrl } : {}),
-  // Durable workflows. A `DATABASE_URL` in `env` puts the runs in Postgres and
-  // they survive a restart; without one they live in a per-process directory and
-  // do not, which is the same trade `aai dev` makes.
+  // Durable workflows need nothing passed here. A `DATABASE_URL` in `env` puts
+  // the runs in Postgres and they survive a restart; without one they live in a
+  // per-process directory and do not, which is the same trade `aai dev` makes.
   //
-  // Passed straight through rather than conditionally spread: both fields accept
-  // `undefined` explicitly, so a project with no `workflows/` directory needs no
-  // guard here — and a truthiness-guarded spread is what `guard-invariants`
-  // rule 22 counts.
-  workflowCode,
-  stepCode,
+  // Two options used to sit here — the compiled workflow surface, carried on the
+  // bundle as `__aaiWorkflowCode`/`__aaiStepCode` because a `"use workflow"` body
+  // had to go through a compiler at BUILD time. The engine reads the agent's own
+  // `workflows` declaration instead, so there is no artifact to hand over.
 });
 
 // Loopback by default: this server has no request authentication of its own,

package/dist/{secret-CwgDLpSy.mjs → secret-B-3T5tvr.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-u7T4YooX.mjs";
-import { f as checkedResponse, p as isStringArray } from "./_studio-CKrsixd0.mjs";
-import { t as secretRequest } from "./_slug-api--ZBmIGH-.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-B1waXMuR.mjs";
+import { t as secretRequest } from "./_slug-api-CfGQq1Tt.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";

package/dist/{studio-D3-HWIfk.mjs → studio-wVWNLREn.mjs}

@@ -4,12 +4,13 @@ import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
 import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
-import { layerScaffold } from "./_templates-4WcKOjS5.mjs";
-import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-CKrsixd0.mjs";
+import { layerScaffold } from "./_templates-0Zr2z6yA.mjs";
+import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-B1waXMuR.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
+import { isPathInside } from "@alexkroman1/aai-runtime/internal";
 //#region studio.ts
 /**
 * The studio-workspace commands: `aai list`, `aai pull`, `aai push`,
@@ -35,7 +36,7 @@ async function executeList(opts) {
 async function materializeFiles(dir, files) {
 	const targets = Object.entries(files).map(([rel, content]) => {
 		const abs = path.resolve(dir, rel);
-		if (abs !== dir && !abs.startsWith(dir + path.sep)) throw new Error(`Pulled file path escapes the project directory: ${rel}`);
+		if (!isPathInside(dir, abs)) throw new Error(`Pulled file path escapes the project directory: ${rel}`);
 		return {
 			abs,
 			content

package/dist/templates/call-audit/agent.eval.test.ts

@@ -45,7 +45,7 @@
 //   * the VOICE — see `speakATone` below, which carries both reasons.
 //
 // 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 is NOT exercised and a rate-limited live run fails where a deployed
 // one would have ridden it out. `aai-cli`'s `dev-workflow.scenario.test.ts` is

package/dist/templates/call-audit/agent.test.ts

@@ -25,7 +25,8 @@
 
 import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { stubSpeech } from "@alexkroman1/aai/testing";
+import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
+import { createWorkflowCtx, stubSpeech } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -34,9 +35,14 @@ import {
   installStubUploads,
 } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import { FatalError, RetryableError } from "workflow";
 import agentDef, { audit } from "./agent.ts";
-import { joinSegments, now, SEGMENT_CONCURRENCY, transcribeSegment } from "./workflows/audit.ts";
+import {
+  auditFlow,
+  joinSegments,
+  now,
+  SEGMENT_CONCURRENCY,
+  transcribeSegment,
+} from "./workflows/audit.ts";
 import { analyse, ingestRecording } from "./workflows/ingest.ts";
 import {
   ANALYSIS_FORMAT,
@@ -626,11 +632,11 @@ describe("transcribing one segment", () => {
   });
 
   test("a rate limit is RETRYABLE, so one busy minute does not fail the run", async () => {
-    // The expected failure of a 32-wide fan-out, and the reason this step's
-    // `maxRetries` is above the default.
+    // The expected failure of a 32-wide fan-out, and the reason the BODY calls
+    // this step with more attempts than the default — asserted where the policy
+    // now lives, in `the whole run` below.
     stubProvider({ status: 429, message: "slow down" });
     await expect(transcribeSegment(UPLOAD_ID, SEGMENT)).rejects.toBeInstanceOf(RetryableError);
-    expect(transcribeSegment.maxRetries).toBe(5);
   });
 
   test("a rejected request is FATAL, so it is not asked five more times", async () => {
@@ -783,8 +789,6 @@ describe("the ffmpeg steps, up to the spawn", () => {
     // Fatal, not retryable: four more attempts find the same missing binary, and the
     // message already carries the install instructions.
     await expect(ingestRecording(UPLOAD_ID)).rejects.toBeInstanceOf(FatalError);
-    // And the retry budget is still raised, for the I/O halves that ARE transient.
-    expect(ingestRecording.maxRetries).toBe(5);
   });
 
   test("narrate speaks first, then fails fatally with no ffmpeg to master with", async () => {
@@ -815,3 +819,71 @@ describe("the ffmpeg steps, up to the spawn", () => {
     );
   });
 });
+
+describe("the body's step policy", () => {
+  /**
+   * A `ctx` that walks the whole body without running a single step.
+   *
+   * `runSteps: false` plus one journaled result per step name: no ffmpeg, no
+   * provider, no model. Both specs below need the identical skeleton and each
+   * only reads `ctx.steps` afterwards, so it is built once.
+   */
+  const walkedCtx = () =>
+    createWorkflowCtx({
+      runSteps: false,
+      results: {
+        clockStart: 1000,
+        clockEnd: 4000,
+        ingestRecording: {
+          audio: "upl_pcm",
+          source: "call.wav",
+          codec: "pcm_s16le",
+          durationMs: 20_000,
+          bytes: 60 * BYTES_PER_SECOND,
+          silences: pauses(10, 20, 30),
+          loudness: MEASURED,
+        },
+        transcribeSegment: { index: 0, text: "hello" },
+        summarize: { headline: "H", risks: [], actions: [], spoken: "S." },
+        narrate: { audio: "upl_wav", durationMs: 500, bytes: 32 },
+      },
+    });
+
+  test("raises the attempt budget on both steps whose failure is transient I/O", async () => {
+    // The retry policy is an argument to `ctx.step` now rather than a
+    // `maxRetries` property, so the CALL is the only place it is observable —
+    // which is also the honest place for it, since the same function called from
+    // two sites may deserve different patience.
+    const ctx = walkedCtx();
+
+    await auditFlow({ recording: UPLOAD_ID }, ctx);
+
+    const budgets = new Map(ctx.steps.map((step) => [step.name, step.maxAttempts]));
+    // The EXACT number, not `toBeGreaterThan(3)`: the value is a literal in the
+    // body and a typo'd `maxAttempts: 4` is exactly what this should catch.
+    expect(budgets.get("ingestRecording")).toBe(6);
+    expect(budgets.get("transcribeSegment")).toBe(6);
+    // The clock and the two model-shaped steps take the default, which is the
+    // other half of the claim: a raised budget is a decision about ONE step.
+    // 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 ["clockStart", "summarize"]) {
+      expect(budgets.has(name)).toBe(true);
+      expect(budgets.get(name)).toBeUndefined();
+    }
+  });
+
+  test("reads the clock at each end under its own name, so a run's history is legible", async () => {
+    // `(name, occurrence)` would tell two `now` calls apart on its own
+    // (`now#0`, `now#1`); distinct names are for the person reading the history.
+    const ctx = walkedCtx();
+
+    const output = await auditFlow({ recording: UPLOAD_ID }, ctx);
+
+    expect(ctx.steps[0]?.name).toBe("clockStart");
+    expect(ctx.steps.at(-1)?.name).toBe("clockEnd");
+    // Subtracted in the BODY from two journaled values, so a replay reports the
+    // same elapsed rather than re-reading a clock.
+    expect(output.elapsedMs).toBe(3000);
+  });
+});

package/dist/templates/call-audit/client.tsx

@@ -22,6 +22,51 @@
  *   lines here, because the two lines that matter are the ones around them: the
  *   `URL.revokeObjectURL` on cleanup, and the guard that stops a slow first
  *   download landing under a second run's output.
+ *
+ * ## A reload here costs the UPLOAD as well as the run
+ *
+ * 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 desk carried on decoding,
+ * cutting and auditing. On this template that is the most expensive orphaning
+ * in `templates/`: the recording is already stored, so the work is paid for, and
+ * a page with no handle on it invites somebody to upload a 700 MB call a second
+ * time and run the whole pipeline again. `key` is the handle that survives a
+ * reload and `recover: true` is what reads it back.
+ *
+ * The upload half of a reload is already the SDK's: `useWorkflowSubmit`
+ * remembers the id it minted, so picking the same file again sends only the
+ * windows that did not land. What it needs from the page is the same LIFETIME
+ * on both halves, which is the first reason this desk takes `useRunKey()`'s
+ * default — `sessionStorage`, the same store the upload recall uses. A handle
+ * that outlived it would promise a return the other half cannot keep.
+ *
+ * ## Why the artifact being shareable does NOT make the key shareable
+ *
+ * This is the template where a `?key=` parameter is most tempting: what a run
+ * produces is an audit somebody wants to send a colleague, and a URL is how
+ * people send things. Weigh what the parameter would actually hand over, though,
+ * because there is no per-user filtering behind `find` — the key IS the access
+ * control, so anyone holding it gets, on this agent:
+ *
+ * - the full TRANSCRIPT of a recorded call, plus the risks and actions somebody
+ *   had audited out of it,
+ * - the audio, which is a real person's voice, recorded with consent to record
+ *   and not consent to circulate,
+ * - `cancel()` and `wake()` on a live run, and
+ * - every other run this desk has filed under the same key, not just the one
+ *   that was shared.
+ *
+ * And a URL leaks by ordinary use: pasted into a chat, kept in history, sent as
+ * a referrer to whatever the page links out to. Against that, sharing the ARTIFACT
+ * needs none of it — the page renders the audit and offers `Download audit.mp3`,
+ * so a person sends the file and the findings deliberately, to exactly who they
+ * meant. A shareable key would trade a deliberate send for an accidental one, on
+ * the most sensitive input any template here accepts. It stays in
+ * `sessionStorage`, which covers the reload this section is about and dies with
+ * the tab.
+ *
+ * A key derived from the recording would be worse still: two desks auditing one
+ * call would recover each other's runs.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -36,10 +81,12 @@ import {
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
+  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
+import { useState } from "react";
 import type { audit } from "./agent.ts";
 
 /**
@@ -59,6 +106,20 @@ const WORKFLOW = "audit";
  */
 const api = createWorkflowApi();
 
+/**
+ * What the desk 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 an audit appearing in front of them,
+ * and it is the line that keeps them from uploading the call again.
+ */
+function pendingNote(startedHere: boolean, found: boolean): string {
+  if (startedHere) return "Reloading is safe — this page will find the audit again.";
+  if (!found) return "Looking for an audit this tab started earlier…";
+  return "Still auditing a call this tab uploaded earlier — no need to send it again.";
+}
+
 /** One labelled number in the pipeline panel. */
 function Stat({ label, value }: { label: string; value: string }) {
   return (
@@ -85,11 +146,20 @@ function Findings({ title, items }: { title: string; items: string[] }) {
 }
 
 export function App() {
+  // This tab's handle on its own audits, in the store the upload recall uses —
+  // see the module doc for why a `?key=` is the wrong trade on this desk.
+  const key = useRunKey();
+  // Did THIS load start the run? A reload cannot have, and that is the only way
+  // the page can tell "auditing what you just uploaded" 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 audit
-  >(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
@@ -106,7 +176,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="Auditing…">
@@ -114,6 +191,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 700 MB upload of the same call. */}
+      {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/call-audit/workflows/audit.ts

@@ -34,17 +34,18 @@
  *
  * ## The plan is made in the BODY, and that is legal
  *
- * `planSegments` runs in the directive body rather than in a step, which looks
- * like a rule violation and is not: it is a pure function of `ingested.silences`
- * and `ingested.durationMs`, both of which came out of a journaled step result.
- * So a replay re-derives the identical list in the identical order, which is
- * exactly what `mapConcurrent` needs — the DevKit correlates a journal entry to a
- * step call by the ORDER the call was issued in.
+ * `planSegments` runs in the BODY rather than in a step, which looks like a rule
+ * violation and is not: it is a pure function of `ingested.silences` and
+ * `ingested.durationMs`, both of which came out of a journaled step result. So a
+ * replay re-derives the identical list in the identical order, which is exactly
+ * what `mapConcurrent` needs — every call shares the name `transcribeSegment`, so
+ * a journal entry is matched by the ORDER its call was issued in.
  *
  * Putting it in a step would journal the same list twice (once as part of the
  * ingest result, once as the plan) and buy nothing.
  */
 
+import type { WorkflowCtx } from "@alexkroman1/aai";
 import { encodeWav, mapConcurrent, readUpload, report } from "@alexkroman1/aai/step";
 import { countWords, formatDuration } from "@alexkroman1/aai/utils";
 // ERASED at build time, so the body can name the schema's own output type without
@@ -79,15 +80,18 @@ import { transcribeSpan } from "./sync-api.ts";
  * the byte bound never binds and what is left is the endpoint's own knee, which it
  * measured at 32. Its `BYTES_IN_FLIGHT` and `MAX_SEGMENT_CONCURRENCY` docs carry
  * both measurements; this is the one number that survives them. *
- * **What EXECUTES at this width is the world's call, not this number's.**
+ * **What EXECUTES at this width is the engine's call, not this number's.**
  * `mapConcurrent` bounds how many step calls the body has in flight; how many
- * run at once is the workflow world's worker concurrency, which on the
- * `DATABASE_URL` path defaults to three — so on a default deployment a width
- * above three is inert while still costing a queued job per item. That makes
- * this the FAR SIDE's knee and the width to use once an operator has raised
- * the ceiling, not a promise about a stock deployment. See "The WINDOW is not
- * the concurrency" in `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers
- * above were measured against the endpoint and say nothing about that layer.
+ * run at once is `DEFAULT_STEP_CONCURRENCY` (`aai-runtime`), which is **16** —
+ * measured against a real microVM at Modal's guaranteed reservation, where a
+ * concurrent segment of 48 kHz stereo costs 26.1 MB. So a width above 16 is
+ * inert on a stock deployment while still costing a queued job per item, and
+ * this number is the FAR SIDE's knee: the one to use once an operator has
+ * raised `AAI_WORKFLOW_STEP_CONCURRENCY` for a larger guest. It was three,
+ * inherited from graphile-worker and never measured, which made every number
+ * in the table above unreachable. See "The WINDOW is not the concurrency" in
+ * `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers above were measured
+ * against the endpoint and say nothing about that layer.
  */
 export const SEGMENT_CONCURRENCY = 32;
 
@@ -150,14 +154,30 @@ export type CallAudit = {
  * The input is what `POST /workflows/runs` carries — see `agent.ts` for the schema
  * it is validated against before a run exists.
  */
-export async function auditFlow(input: WorkflowInputOf<typeof audit>): Promise<CallAudit> {
-  "use workflow";
-
+export async function auditFlow(
+  input: WorkflowInputOf<typeof audit>,
+  ctx: WorkflowCtx,
+): Promise<CallAudit> {
   // Both at once: neither needs the other, and issued together they are one round
   // trip instead of two before any audio moves. The ORDER is still a pure function
   // of this expression — the two calls go out synchronously, left to right — which
   // is what a replay reproduces.
-  const [startedAt, ingested] = await Promise.all([now(), ingestRecording(input.recording)]);
+  //
+  // `clockStart` and `clockEnd` are two NAMES for one function, deliberately.
+  // `(name, occurrence)` step identity would tell two `now` calls apart on its
+  // own (`now#0`, `now#1`), but a run's history is read by a person: `clockEnd`
+  // says which end it is where `now#1` makes the reader count call sites.
+  // `maxAttempts: 6` was `ingestRecording.maxRetries = 5` — five retries AFTER
+  // the first, so six in all. More than the default 3, and not because a
+  // conversion is flaky: a corrupt file fails identically forever, and
+  // `throwFfmpegStepError` is what stops the engine retrying that. It is the two
+  // I/O halves that are worth another attempt — the step reads a whole recording
+  // out of the store and writes a whole one back, and either can lose a
+  // connection on a file this size.
+  const [startedAt, ingested] = await Promise.all([
+    ctx.step("clockStart", () => now()),
+    ctx.step("ingestRecording", () => ingestRecording(input.recording), { maxAttempts: 6 }),
+  ]);
 
   // Pure, in the body, from journaled values. See the module doc. Planned against
   // the stored BYTE COUNT rather than the reported duration — `durationSeconds`
@@ -169,14 +189,24 @@ export async function auditFlow(input: WorkflowInputOf<typeof audit>): Promise<C
   // already journaled, so a resume replays those for free and re-issues only what
   // is missing — where catching here to salvage a partial transcript would return
   // a recording with a silent hole in it and report success.
+  // `mapConcurrent` hands out items from a monotonic cursor, so the Nth call
+  // ISSUED is segment N whatever order they settle in — which is what makes
+  // `transcribeSegment#N` stable across a replay. `maxAttempts: 6` was
+  // `transcribeSegment.maxRetries = 5` — more than the default 3 because a rate
+  // limit is the expected failure here, and a segment that 429s is not a segment
+  // that is wrong.
   const parts = await mapConcurrent(segments, SEGMENT_CONCURRENCY, (segment) =>
-    transcribeSegment(ingested.audio, segment),
+    ctx.step("transcribeSegment", () => transcribeSegment(ingested.audio, segment), {
+      maxAttempts: 6,
+    }),
   );
 
   const transcript = joinSegments(segments, parts);
-  const summary = await summarize(transcript, ingested.source, ingested.durationMs);
-  const spoken = await narrate(summary.spoken, input.voice);
-  const finishedAt = await now();
+  const summary = await ctx.step("summarize", () =>
+    summarize(transcript, ingested.source, ingested.durationMs),
+  );
+  const spoken = await ctx.step("narrate", () => narrate(summary.spoken, input.voice));
+  const finishedAt = await ctx.step("clockEnd", () => now());
 
   // Whatever this returns is what a caller reads as `output` on a completed run —
   // so it is what the page renders, typed through `WorkflowOutputOf`. Assembled in
@@ -221,8 +251,6 @@ export async function auditFlow(input: WorkflowInputOf<typeof audit>): Promise<C
  * no reason for a second copy of it to exist.
  */
 export async function transcribeSegment(audioId: string, segment: Segment): Promise<SegmentText> {
-  "use step";
-
   // One line per segment, which is what makes the fan-out legible to a page: the
   // status is `running` for the whole thing, so without this a sixty-segment
   // recording and a one-segment recording look identical while they run.
@@ -245,12 +273,6 @@ export async function transcribeSegment(audioId: string, segment: Segment): Prom
   return { index: segment.index, text };
 }
 
-/**
- * Retries beyond the default 3, because a rate limit is the expected failure and a
- * segment that 429s is not a segment that is wrong.
- */
-transcribeSegment.maxRetries = 5;
-
 /**
  * When it is now, as epoch ms.
  *
@@ -266,8 +288,6 @@ transcribeSegment.maxRetries = 5;
  * smaller thing.
  */
 export async function now(): Promise<number> {
-  "use step";
-
   return Date.now();
 }
 

package/dist/templates/call-audit/workflows/ingest.ts

@@ -63,7 +63,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { probeMedia, runFfmpeg } from "@alexkroman1/aai/ffmpeg";
-import { pcmDurationMs, report, uploadInfo } from "@alexkroman1/aai/step";
+import { pcmDurationMs, report, requireCompleteUpload } from "@alexkroman1/aai/step";
 import { throwFatalStepError, throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
 import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
 import { formatBytes, formatDuration, plural } from "@alexkroman1/aai/utils";
@@ -120,10 +120,21 @@ export type Ingested = {
  * normalization writes a file, so journaling the id means a resumed run reads the
  * file that already exists instead of paying to make a second one.
  */
+// This file sits in `scripts/coverage-per-file-baseline.json` at 46.8%, and the
+// reason is worth having in place. What is uncovered is `ingestRecording`'s HAPPY
+// path — three ffmpeg invocations — which needs a real binary and so belongs to
+// the scenario tier, not here; the two failure paths ARE covered, and every
+// decision the step makes lives in `media.ts` as a pure function at 95%.
+//
+// It measured exactly 50.0% before the DevKit removal, and the two statements it
+// lost were `"use step";` and `ingestRecording.maxRetries = 5;` — both of which
+// the two failure tests EXECUTED, so both counted as covered while testing
+// nothing. Removing them is what took the file under the floor: a directive
+// propping a coverage number up is the least useful statement in the tree.
 export async function ingestRecording(uploadId: string): Promise<Ingested> {
-  "use step";
-
-  const stored = await uploadInfo(uploadId);
+  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, so
+  // an upload still arriving would be copied short and levelled as the whole call.
+  const stored = await requireCompleteUpload(uploadId);
   await report(`Reading ${stored.name || uploadId} (${formatBytes(stored.size)}).`);
 
   return await withTempDir(
@@ -206,17 +217,6 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
   );
 }
 
-/**
- * Retries beyond the default 3.
- *
- * Not because a conversion is flaky — a corrupt file fails identically forever,
- * and `throwFfmpegStepError` is what stops the DevKit retrying that. It is the
- * two I/O halves that are worth another attempt: this step reads a whole
- * recording out of the store and writes a whole one back, and either can lose a
- * connection on a file this size.
- */
-ingestRecording.maxRetries = 5;
-
 /**
  * Run a `media.ts` reader, turning "I cannot read this analysis" into a terminal
  * failure.

package/dist/templates/call-audit/workflows/media.ts

@@ -5,7 +5,7 @@
  *
  * No directive in this file, which is what lets it sit under `workflows/`: the
  * Workflow DevKit's builder scans this directory and transforms only what carries
- * a `"use workflow"` / `"use step"` body. Everything here is a pure function of a
+ * a workflow body or a step. Everything here is a pure function of a
  * journaled value, and that is deliberate rather than tidy — **an ffmpeg pipeline
  * is untestable exactly where it spawns**, so every decision this desk makes is
  * pushed out of the steps and into this module, where a spec drives it with no

package/dist/templates/call-audit/workflows/summarize.ts

@@ -105,8 +105,6 @@ export async function summarize(
   source: string,
   durationMs: number,
 ): Promise<CallSummary> {
-  "use step";
-
   await report("Reading the transcript.");
   const reply = await stepGenerateJsonClassified(
     `Audit this transcript of a recorded call (${source}, ${formatDuration(durationMs)}).\n\n` +
@@ -161,8 +159,6 @@ export async function narrate(
   script: string,
   voice?: string,
 ): Promise<{ audio: string; durationMs: number; bytes: number }> {
-  "use step";
-
   const spoken = await stepSpeak(script, omitUndefined({ voice }));
 
   return await withTempDir(

package/dist/templates/link-digest/agent.eval.test.ts

@@ -18,17 +18,19 @@
 //     each one is answered in memory. It proves the wiring, not the summary.
 //
 // 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, no retry, and the `sleep` is RECORDED rather than taken.
 // `run.slept` below is that admission written as an assertion. The tier that
 // really suspends and resumes a run is `aai-cli`'s
 // `dev-workflow.scenario.test.ts`.
+
 import { createServer, type Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect, onTestFinished } from "vitest";
 import agentDef, { digest } from "./agent.ts";
+import { SETTLE_MS } from "./workflows/digest.ts";
 
 /** The gateway leg, so one handler can route the page and the model apart. */
 const isModelCall = (url: string): boolean => url.includes("/chat/completions");
@@ -150,7 +152,7 @@ describeWorkflowEval(agentDef, (test) => {
     expect(run.reported).toContain("Filing the digest.");
     // The one thing this harness cannot do, stated as an assertion rather than
     // left implied: the durable wait was ASKED FOR and not taken.
-    expect(run.slept).toEqual([{ duration: "10 seconds" }]);
+    expect(run.slept).toEqual([{ duration: SETTLE_MS }]);
   });
 
   test("fails terminally on a page with no readable text", async ({ app, mode }) => {