@alexkroman1/aai-cli 13.3.0 → 14.0.0

package/dist/scaffold/server.mjs

@@ -122,6 +122,71 @@ function resolveClientDir() {
   return defaultClientDir();
 }
 
+/**
+ * The error classes that mean a DEFECT in this code rather than a mistake in
+ * the configuration.
+ *
+ * Everything below turns a boot failure into two lines and a non-zero exit,
+ * which is right for "ASSEMBLYAI_API_KEY is not set" and wrong for a
+ * `TypeError`, where the traceback is the only thing that can locate the bug.
+ * Those are re-thrown untouched.
+ */
+const BUG_ERRORS = [TypeError, ReferenceError, RangeError, SyntaxError];
+
+/**
+ * Every distinct message on an error and its `cause` chain, outermost first.
+ *
+ * A driver failure states the useful half one hop down — `connect to database
+ * failed: getaddrinfo ENOTFOUND db` — so printing only the top message is how a
+ * tidy envelope ends up less informative than the stack it replaced.
+ *
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errorText(err) {
+  /** @type {string[]} */
+  const messages = [];
+  /** @type {unknown} */
+  let cursor = err;
+  while (cursor instanceof Error) {
+    if (cursor.message !== "" && !messages.includes(cursor.message)) messages.push(cursor.message);
+    cursor = cursor.cause;
+  }
+  return messages.length > 0 ? messages.join(": ") : String(err);
+}
+
+/**
+ * Run one step of BOOT, and answer a failure the way this file already answers
+ * a missing build artifact: what is wrong, then what to do, then exit 1.
+ *
+ * Without this, a missing provider key — the commonest way a first `npm start`
+ * fails — killed the process with a ten-frame traceback pointing into
+ * `node_modules/@alexkroman1/aai-runtime/dist/host-env-*.js`. The MESSAGE was
+ * already good ("AssemblyAI LLM: missing API key. Set ASSEMBLYAI_API_KEY in the
+ * agent env."); what it arrived wrapped in was a crash report about somebody
+ * else's bundle, in a container that then restarted and did it again.
+ *
+ * Exiting is deliberate rather than binding anyway and serving an unhealthy
+ * `/health`: a process that stays up tells an orchestrator it started, and a
+ * misconfigured deployment that reports itself healthy is worse than one that
+ * refuses to run. The non-zero exit is what a supervisor, a `docker run`, and
+ * CI all already read.
+ *
+ * @template T
+ * @param {string} fix - What the operator should change, in one sentence.
+ * @param {() => T | Promise<T>} work
+ * @returns {Promise<T>}
+ */
+async function bootOrExit(fix, work) {
+  try {
+    return await work();
+  } catch (err) {
+    if (BUG_ERRORS.some((kind) => err instanceof kind)) throw err;
+    console.error(`Cannot start the agent: ${errorText(err)}\n${fix}`);
+    process.exit(1);
+  }
+}
+
 const env = await resolveAgentEnv();
 
 /**
@@ -152,38 +217,77 @@ const publicUrl = process.env.PUBLIC_URL?.trim();
  * Best-effort: if a real migration already created them and this role may not
  * CREATE, it warns and the server starts anyway.
  */
-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 });
+// Read into a const: `env.DATABASE_URL` is a record lookup, so its narrowing
+// does not survive into the callback below.
+const databaseUrl = env.DATABASE_URL;
+if (databaseUrl) {
+  await bootOrExit(
+    "Check DATABASE_URL: this server has to reach that database at boot to create the tables it owns.",
+    async () => {
+      await ensureSessionStateSchema({ url: databaseUrl, 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: databaseUrl, logger: console });
+    },
+  );
+} else {
+  /**
+   * Say that this process is the only place the state lives, because the next
+   * thing an operator does with a container is run two of them.
+   *
+   * Session state (slots, the event log) is keyed by session id and held in
+   * memory here — the boot line below reports it as `sessionState: { backend:
+   * 'memory', durable: false }`, which is true and easy to read as being about
+   * restarts alone. It is also about REPLICAS: the browser reconnects with
+   * `?sessionId=<id>`, so a reconnect that lands on a different process resumes
+   * a session that process has never heard of and the agent's context is gone
+   * mid-call. One replica has no such problem, which is exactly why nothing
+   * catches this until the deployment grows a second one.
+   */
+  console.warn(
+    "No DATABASE_URL: session state and durable runs live in THIS process's memory.\n" +
+      "One replica is fine. Behind a load balancer, enable sticky sessions so a reconnect " +
+      "(the client re-dials with ?sessionId=) reaches the same process — or set DATABASE_URL " +
+      "and let every replica share the state.",
+  );
 }
 
-const server = createAgentServer({
-  agent,
-  env,
-  // Provider credentials may ALSO arrive straight from the environment without
-  // being declared, and without becoming ctx.env — the ordinary way to hand
-  // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
-  providerEnv: withHostCredentialFallback(env),
-  clientDir: resolveClientDir(),
-  ...(publicUrl ? { publicUrl } : {}),
-  // 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.
-  //
-  // 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.
-});
+const server = await bootOrExit(
+  // The commonest first-run failure, and the one whose stack this replaces: a
+  // provider credential that is not there. `.env` is what `aai dev` reads too,
+  // so the fix is the same one in both places.
+  "Set the missing value in .env, or pass it as a real environment variable (`docker run -e NAME=value`), then start again.",
+  () =>
+    createAgentServer({
+      agent,
+      env,
+      // Provider credentials may ALSO arrive straight from the environment without
+      // being declared, and without becoming ctx.env — the ordinary way to hand
+      // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
+      providerEnv: withHostCredentialFallback(env),
+      clientDir: resolveClientDir(),
+      ...(publicUrl ? { publicUrl } : {}),
+      // 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.
+      //
+      // 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,
 // so exposing it is a deliberate act. Set HOST=0.0.0.0 to bind every interface
 // behind your own proxy or auth. An empty HOST means unset, not "everything".
 const host = process.env.HOST?.trim() || undefined;
-await server.listen(Number(process.env.PORT ?? 3000), host);
+const port = Number(process.env.PORT ?? 3000);
+await bootOrExit(
+  `Nothing is listening yet — port ${port} is in use, or this process may not bind it. Set PORT to a free one.`,
+  () => server.listen(port, host),
+);
 console.log(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
 
 for (const signal of ["SIGINT", "SIGTERM"]) {

package/dist/{secret-V1w7y9-j.mjs → secret-Cjp912yF.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { a as ok, n as fail, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { a as ok, n as fail, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
-import { f as checkedResponse, p as isStringArray } from "./_studio-DTi3EdXQ.mjs";
-import { t as secretRequest } from "./_slug-api-DlKpj91X.mjs";
-import { isRecord } from "@alexkroman1/aai/utils";
+import { f as checkedResponse, p as isStringArray } from "./_studio-DnR_BqFp.mjs";
+import { t as secretRequest } from "./_slug-api-CGvc2YSQ.mjs";
+import { isRecord, plural } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import pTimeout from "p-timeout";
 //#region src/secret.ts
@@ -153,7 +153,7 @@ async function executeSecretList(cwd, server) {
 	const { vars } = checkedResponse(data, (value) => isRecord(value) && isStringArray(value.vars), `the secret list for ${target}`);
 	if (vars.length === 0) log.info("No secrets set. Use `aai secret put <name>` to add one.");
 	else {
-		log.message(`${vars.length} secret${vars.length === 1 ? "" : "s"}:`);
+		log.message(`${vars.length} ${plural(vars.length, "secret")}:`);
 		for (const v of vars) log.message(`  ${v}`);
 	}
 	return ok({ secrets: vars });

package/dist/secret.d.ts

@@ -38,10 +38,12 @@ export type SecretValueIo = {
  *   sitting at a terminal has no reason to send.
  */
 export declare function resolveSecretValue(name: string, mode: OutputMode, io?: SecretValueIo): Promise<string | undefined>;
-type SecretPutData = {
-    name: string;
-};
-type SecretDeleteData = {
+/**
+ * Both the put and the delete result — one shape, so one name. They were two
+ * distinct aliases for `{ name: string }`, which implied a difference that does
+ * not exist and left "which alias meant the secret result" to be re-decided.
+ */
+type SecretNameData = {
     name: string;
 };
 type SecretListData = {
@@ -52,7 +54,7 @@ type SecretListData = {
  * path). If not, prompt for it — masked — which is what
  * {@link resolveSecretValue} returning `undefined` asks for.
  */
-export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretPutData>>;
-export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretDeleteData>>;
+export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretNameData>>;
+export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretNameData>>;
 export declare function executeSecretList(cwd: string, server: string | undefined): Promise<CommandResult<SecretListData>>;
 export {};

package/dist/{studio-BpMCfUNx.mjs → studio-CpHlNHUZ.mjs}

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { a as ok, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
-import { s as updateProjectConfig } from "./_config-ZY2euhdh.mjs";
-import { t as resolveServerEnv } from "./_server-common-BV4_CrP3.mjs";
-import { a as resolveDeployTarget } from "./_agent-Clbq3a4h.mjs";
-import { layerScaffold } from "./_templates-V4l5sZJy.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-DTi3EdXQ.mjs";
+import { l as formatCappedList } from "./_utils-D5JGcjiW.mjs";
+import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
+import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
+import { layerScaffold } from "./_templates-CK4oKoeX.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-DnR_BqFp.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
+import { isRecord, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { isPathInside } from "@alexkroman1/aai-runtime/internal";
 //#region src/studio.ts
@@ -62,7 +63,7 @@ async function notFoundHint(serverUrl, apiKey) {
 	const projects = await listStudioProjects(serverUrl, apiKey).catch(() => null);
 	if (projects === null) return "Run `aai list` to see your projects.";
 	if (projects.length === 0) return "This login has no studio projects at all. If yours are in the studio, the CLI is linked to a different account — run `aai login` again, approve it in a browser signed in to the account that owns the project, then `aai list`.";
-	return `Your projects: ${projects.slice(0, 10).join(", ")}${projects.length > 10 ? `, and ${projects.length - 10} more` : ""}.`;
+	return `Your projects: ${formatCappedList(projects)}.`;
 }
 async function executePull(opts) {
 	const { serverUrl, apiKey } = await resolveDeployTarget(opts.cwd, opts.server);
@@ -159,17 +160,14 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, project) {
 		method: "PUT",
 		body: env
 	});
-	log.info(`Synced ${names.length} secret${names.length === 1 ? "" : "s"} from .env`);
+	log.info(`Synced ${names.length} ${plural(names.length, "secret")} from .env`);
 	return names;
 }
 async function executePublish(opts) {
-	if (!opts.skipTypecheck) {
-		const { assertTypechecks } = await import("./_typecheck-gate-sV4N5F93.mjs");
-		await assertTypechecks(opts.cwd);
-	}
+	const { assertTypechecks } = await import("./_typecheck-gate-U3jcil8L.mjs");
+	await assertTypechecks(opts.cwd, { skip: opts.skipTypecheck });
 	const pushed = await pushProject(opts);
 	const { project, serverUrl, apiKey } = pushed;
-	const hadSlug = pushed.slug !== void 0;
 	if (pushed.slug) await syncEnvSecrets(opts.cwd, serverUrl, apiKey, project);
 	log.step(`Publishing ${project} (builds in the project's sandbox)…`);
 	const result = checkedResponse(await publishStudioProject(serverUrl, apiKey, project, { skipTypecheck: opts.skipTypecheck }), (value) => isRecord(value) && typeof value.slug === "string" && typeof value.output === "string", `the publish route at ${serverUrl}`);
@@ -178,7 +176,7 @@ async function executePublish(opts) {
 		serverUrl,
 		slug: result.slug
 	});
-	if (!hadSlug) {
+	if (!pushed.slug) {
 		if ((await syncEnvSecrets(opts.cwd, serverUrl, apiKey, result.slug)).length > 0) log.info("They apply on the next `aai publish`.");
 	}
 	const agentUrl = `${serverUrl}/${result.slug}`;

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

@@ -32,7 +32,7 @@
 import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx, stubSpeech, WORKFLOW_CTX_NOW } from "@alexkroman1/aai/testing";
+import { createWorkflowContext, stubSpeech, WORKFLOW_CONTEXT_NOW } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -516,7 +516,7 @@ describe("planning where to cut", () => {
   test("the last segment never addresses a byte the file does not have", () => {
     // The twelve-byte bug this API shape exists to prevent: planning from a
     // duration rounded to whole milliseconds put `endByte` at 640,512 for a
-    // 640,500-byte file. `readUpload` clamps a window to the stored size, so
+    // 640,500-byte file. `stepReadUpload` clamps a window to the stored size, so
     // nothing threw — the plan was simply describing audio that does not exist.
     // Found by running the real argv against a real ffmpeg, which is the only
     // place a twelve-byte error was ever going to surface.
@@ -867,14 +867,14 @@ describe("the body's step policy", () => {
    * only reads `ctx.steps` afterwards, so it is built once.
    */
   const walkedCtx = () =>
-    createWorkflowCtx({
+    createWorkflowContext({
       runSteps: false,
       // The body reads the clock at both ends with `ctx.now()`, which the engine
       // journals under `now!0` and `now!1`. A PRODUCER here rather than a fixed
       // number, so the two reaches differ and `elapsedMs` is assertable — based
-      // on `WORKFLOW_CTX_NOW`, the instant the fake otherwise freezes at, rather
+      // on `WORKFLOW_CONTEXT_NOW`, the instant the fake otherwise freezes at, rather
       // than on a second arbitrary epoch nobody can relate to the first.
-      now: clockReads(WORKFLOW_CTX_NOW, WORKFLOW_CTX_NOW + 3000),
+      now: clockReads(WORKFLOW_CONTEXT_NOW, WORKFLOW_CONTEXT_NOW + 3000),
       results: {
         ingestRecording: {
           audio: "upl_pcm",
@@ -937,7 +937,7 @@ describe("the body's step policy", () => {
 /**
  * `auditFlow` on the real replay engine — as far as this tier can take it.
  *
- * The block above drives the body through `createWorkflowCtx` with
+ * The block above drives the body through `createWorkflowContext` with
  * `runSteps: false` and a journaled result per step, which is what makes it
  * affordable: `ingestRecording` shells out to the ffmpeg toolchain, which this
  * tier cannot usefully feed — the `ingestRecording` and `narrate` specs above
@@ -970,6 +970,11 @@ describe("the run is DURABLE, as far as ffmpeg allows", () => {
     });
     installStubReporter();
     vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+    // Neither binary is this block's subject (see its doc), and a real
+    // conversion here would make a developer with ffmpeg installed run a
+    // slower, different test from CI, which has none.
+    vi.stubEnv("AAI_FFMPEG_PATH", "/nonexistent/ffmpeg");
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/ffprobe");
   });
 
   test("a FatalError in the first step fails the run on ONE attempt, not six", async () => {

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

@@ -20,7 +20,7 @@
  * - `transcription-workflow` owns the FAN-OUT — why the sync transcription
  *   endpoint's 120-second cap forces one, and how a run survives dying on segment
  *   27 of 60.
- * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `writeUpload`, and
+ * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `stepWriteUpload`, and
  *   why a page needs `api.download` rather than a URL.
  *
  * **What this template adds is a decoder**, and everything downstream changes
@@ -153,7 +153,7 @@ export const audit: WorkflowDef<typeof auditInput, CallAudit> = workflow({
   input: auditInput,
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and the
-  // ingest step reads it back with `readUpload`.
+  // ingest step reads it back with `stepReadUpload`.
   uploads: ["recording"],
   run: auditFlow,
 });

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

@@ -76,9 +76,11 @@ import "@alexkroman1/aai-ui/styles.css";
 // already declares.
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
 import {
+  BulletList,
   createWorkflowApi,
+  Facts,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
@@ -86,7 +88,6 @@ import {
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { audit } from "./agent.ts";
 
 /**
@@ -130,33 +131,13 @@ function Stat({ label, value }: { label: string; value: string }) {
   );
 }
 
-/** A list that renders nothing rather than an empty box — see `risks` in the schema. */
-function Findings({ title, items }: { title: string; items: string[] }) {
-  if (items.length === 0) return null;
-  return (
-    <section className="flex flex-col gap-1">
-      <h3 className="text-sm font-medium opacity-70">{title}</h3>
-      <ul className="flex list-disc flex-col gap-1 pl-5">
-        {items.map((item) => (
-          <li key={item}>{item}</li>
-        ))}
-      </ul>
-    </section>
-  );
-}
-
 export function App() {
-  // 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`. The reload — both halves of it — is the
   // hook's own doing; see the module doc for why the key it mints is the one
   // this desk wants.
-  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
-    typeof audit
-  >(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error, startedHere } =
+    useWorkflowSubmit<typeof audit>(WORKFLOW, { api });
   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
@@ -173,14 +154,7 @@ export function App() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-        className="flex flex-col gap-4"
-      >
+      <Form onSubmit={(values) => 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…">
@@ -200,20 +174,26 @@ export function App() {
           for `<WorkflowProgress>` to read. */}
       <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
 
-      {/* What the run itself says, from `report()` in the workflow's steps — which
+      {/* What the run itself says, from `stepReport()` in the workflow's steps — which
           for this template is the ffmpeg narration: what the file was, what it
           measured, how many pauses were found. */}
       <WorkflowProgress runId={run?.runId} api={api} />
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {output !== undefined && (
         <article className="flex flex-col gap-6">
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
-            <p className="text-sm opacity-70">
-              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
-            </p>
+            <Facts
+              items={[output.source, formatDuration(output.durationMs), `${output.words} words`]}
+            />
           </div>
 
           {/* What the pipeline did, which is this template's subject. Rendered rather
@@ -231,8 +211,11 @@ export function App() {
             <Stat label="Run time" value={formatDuration(output.elapsedMs)} />
           </dl>
 
-          <Findings title="Risks" items={output.risks} />
-          <Findings title="Actions" items={output.actions} />
+          {/* Either list can come back empty — see `risks` in the schema — and
+              `<BulletList>` renders nothing at all when it does, heading
+              included, rather than a stray heading over an empty box. */}
+          <BulletList title="Risks" items={output.risks} />
+          <BulletList title="Actions" items={output.actions} />
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
@@ -241,7 +224,9 @@ export function App() {
             </h3>
             {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
-              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+              <p role="alert" className="text-red-600">
+                Could not load the audio: {audio.error}
+              </p>
             )}
             {audio.url !== undefined && (
               <>
@@ -251,7 +236,7 @@ export function App() {
                     track would carry. `spoken-summary` serves a one-cue WebVTT
                     data URL instead — worth reading for how, if a real track is
                     what a page needs. */}
-                <audio controls src={audio.url} className="w-full" />
+                <audio aria-label="Audit read aloud" controls src={audio.url} className="w-full" />
                 {/* `download` works on an object URL because the bytes are already in
                     the tab; it is the href that could not carry the agent's bearer,
                     not the attribute. */}
@@ -273,4 +258,4 @@ export function App() {
   );
 }
 
-page({ name: "Call Audit", component: App });
+mountPage({ name: "Call Audit", component: App });

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

@@ -45,8 +45,8 @@
  * 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 type { WorkflowContext } from "@alexkroman1/aai";
+import { encodeWav, mapConcurrent, stepReadUpload, stepReport } 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
 // a runtime cycle back through `agent.ts` — the same mechanism `client.tsx` uses
@@ -156,7 +156,7 @@ export type CallAudit = {
  */
 export async function auditFlow(
   input: WorkflowInputOf<typeof audit>,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): 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
@@ -259,12 +259,14 @@ export async function transcribeSegment(audioId: string, segment: Segment): Prom
   // ORDER is not guaranteed here and does not need to be — the calls go out
   // together, so their lines interleave by completion, and `segment.index` is what
   // puts the TRANSCRIPT back in order.
-  await report(`Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
+  await stepReport(
+    `Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`,
+  );
 
   // `[start, end)`, the same half-open pair `planSegments` produced — the store
   // owns the conversion to HTTP's inclusive range, so there is no `- 1` here to get
   // wrong.
-  const audio = await readUpload(audioId, { start: segment.startByte, end: segment.endByte });
+  const audio = await stepReadUpload(audioId, { start: segment.startByte, end: segment.endByte });
   const text = await transcribeSpan(
     encodeWav(audio.bytes, ANALYSIS_FORMAT),
     `segment-${segment.index}.wav`,

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, requireCompleteUpload } from "@alexkroman1/aai/step";
+import { pcmDurationMs, stepReport, stepRequireCompleteUpload } 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";
@@ -132,10 +132,10 @@ export type Ingested = {
 // 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> {
-  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, so
+  // `stepRequireCompleteUpload`, not `stepUploadInfo`: `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)}).`);
+  const stored = await stepRequireCompleteUpload(uploadId);
+  await stepReport(`Reading ${stored.name || uploadId} (${formatBytes(stored.size)}).`);
 
   return await withTempDir(
     async (dir) => {
@@ -148,7 +148,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
       // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
       // completeness myself", which is what a body polling a still-arriving
       // upload needs and is the opposite of what happened above: this step has
-      // already called `requireCompleteUpload`, so the file IS whole and the
+      // already called `stepRequireCompleteUpload`, so the file IS whole and the
       // windows may land in any order. Omitting it lets `readUploadToFile`
       // establish that for itself and fan out. The cost is one metadata round
       // trip, against the dozens of window reads it overlaps.
@@ -162,7 +162,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
         throwFfmpegStepError,
       );
       const codec = probed.audio?.codec ?? "unknown";
-      await report(
+      await stepReport(
         `Levelling ${describeSource(codec, probed.durationSec)} to ${ANALYSIS_FORMAT.sampleRate / 1000} kHz mono.`,
       );
 
@@ -206,7 +206,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
         type: "application/octet-stream",
       });
 
-      await report(
+      await stepReport(
         `Levelled ${formatDuration(durationMs)} from ${loudness.inputLufs} LUFS, ` +
           `${Math.round(speechFraction(silences, durationMs / 1000) * 100)}% speech across ` +
           `${silences.length} ${plural(silences.length, "pause")}.`,