@alexkroman1/aai-cli 6.5.0 → 6.6.0

package/dist/{dev-C6SWaAZP.mjs → dev-Uq5ujP8a.mjs}

@@ -12,7 +12,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-DQ1t9sbw.mjs");
+	const { startDevServer } = await import("./_dev-server-LLLWnFBs.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{eject-Zrzk5KV3.mjs → eject-31gjtaHF.mjs}

@@ -2,7 +2,7 @@
 import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
 import { l as readJson, o as errorMessage, p as writeJson, s as fileExists } from "./_utils-B8QmtFhK.mjs";
-import { scaffoldDir } from "./_templates-iDGjGiPf.mjs";
+import { scaffoldDir } from "./_templates-Dxb_P2Wz.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region eject.ts
@@ -69,7 +69,7 @@ async function ensureStartScript(cwd) {
 	const existing = manifest.scripts?.start;
 	if (existing === START_SCRIPT && manifest.scripts?.prestart === "aai build --skip-tests") return false;
 	if (existing !== void 0 && existing !== START_SCRIPT) {
-		log.warn(`Kept your existing "start" script (${existing}) — run \`${PRESTART_SCRIPT}\` then \`node ${SERVER_ENTRY}\`.`);
+		log.warn(`Kept your existing "start" script (${existing}) — run \`${PRESTART_SCRIPT}\` then \`${START_SCRIPT}\`.`);
 		return false;
 	}
 	manifest.scripts = {

package/dist/{init-BTRGiPQr.mjs → init-l6xfU4xX.mjs}

@@ -2,7 +2,7 @@
 import { a as ok } from "./_output-CKkmWs7i.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-u7T4YooX.mjs";
 import { d as resolveCwd, l as readJson, o as errorMessage, s as fileExists, t as AGENT_ENTRY } from "./_utils-B8QmtFhK.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-vGW5SBnX.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DpH2pBJd.mjs";
 import path from "node:path";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
@@ -105,7 +105,7 @@ function collectWarnings() {
 }
 /** Publish after init and return deploy metadata if successful. */
 async function tryPublish(cwd, server, warn) {
-	const { executePublish } = await import("./studio-BGVmCA2G.mjs");
+	const { executePublish } = await import("./studio-BCNUpDgP.mjs");
 	try {
 		const result = await executePublish({
 			cwd,
@@ -126,7 +126,7 @@ async function tryPublish(cwd, server, warn) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-CpISqoR8.mjs");
+	const { runInit } = await import("./_init-C57bWAQ8.mjs");
 	await withSpinner(silent, {
 		start: `Creating ${dir}`,
 		done: "Project created",

package/dist/{login-k0Z3VQu9.mjs → login-C71-qz8F.mjs}

@@ -2,7 +2,7 @@
 import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
 import { o as updateGlobalConfig, r as readGlobalConfig, t as approveServer } from "./_config-D_s09e7g.mjs";
-import { o as resolveServerUrl } from "./_agent-vGW5SBnX.mjs";
+import { o as resolveServerUrl } from "./_agent-DpH2pBJd.mjs";
 import { linkConfirmationCode } from "@alexkroman1/aai/utils";
 import { spawn } from "node:child_process";
 import { sleep } from "@alexkroman1/aai/internal";

package/dist/scaffold/.env.example

@@ -9,3 +9,24 @@
 # Required only if your agent enables the `web_search` builtin
 # (free key: https://brave.com/search/api/):
 # BRAVE_API_KEY=
+
+# --- Durable workflows and uploads -----------------------------------------
+#
+# A durable run needs a database; `api.upload(file)` needs a database AND
+# somewhere to put the bytes. A DEPLOYED agent gets both from the platform
+# (`aai storage enable`), so these four are the LOCAL equivalents and none of
+# them is needed by an agent that has no workflow.
+#
+# All three storage keys or none: two of three resolves to nothing and refuses
+# by name rather than half-working. Nothing creates the bucket for you — a
+# bucket is dashboard state, not a migration.
+#
+# From the Supabase CLI: `supabase start`, then `supabase status -o env` for
+# API_URL and SERVICE_ROLE_KEY. The local stack declares one bucket, `blobs`,
+# and uploads land under an `uploads/` prefix inside it — the same layout
+# production uses beside its `blobs/<sha256>` deploy artifacts.
+#
+# DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
+# AAI_UPLOAD_STORAGE_URL=http://127.0.0.1:54321
+# AAI_UPLOAD_STORAGE_KEY=<SERVICE_ROLE_KEY>
+# AAI_UPLOAD_STORAGE_BUCKET=blobs

package/dist/scaffold/CLAUDE.md

@@ -1155,6 +1155,29 @@ A query returning more than 1000 rows throws — always bound reads with
   preview and published agents, each with its own schema)
 - `aai dev`: set `DATABASE_URL` in the project `.env`
 
+**A workflow UPLOAD needs one more thing locally: somewhere to put the bytes.**
+A deployed agent gets it from the platform; under `aai dev` the bytes go to a
+bucket you point it at, and the Supabase CLI prints the two values
+(`supabase start`, then `supabase status -o env`):
+
+```sh
+DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres
+AAI_UPLOAD_STORAGE_URL=http://127.0.0.1:54321
+AAI_UPLOAD_STORAGE_KEY=<SERVICE_ROLE_KEY>
+AAI_UPLOAD_STORAGE_BUCKET=blobs
+```
+
+`blobs`, not `uploads`: that is the one bucket the local stack declares
+(`supabase/config.toml`, applied by `supabase start`), and uploads land under an
+`uploads/` PREFIX inside it — the same layout production uses beside its
+`blobs/<sha256>` deploy artifacts. Nothing creates a bucket for you.
+
+`.env.example` in a scaffolded project carries this block commented out.
+
+Without both halves `api.upload(file)` fails naming the one that is missing —
+never quietly into a directory, which is what it used to do and then lose by the
+time a resumed run read it.
+
 Create tables lazily from tool code and upsert with `on conflict`:
 
 ```ts no-check

package/dist/scaffold/package.json

@@ -13,8 +13,8 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.5.0",
-    "@alexkroman1/aai-ui": "^6.5.0",
+    "@alexkroman1/aai": "^6.6.0",
+    "@alexkroman1/aai-ui": "^6.6.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -23,7 +23,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^6.5.0",
+    "@alexkroman1/aai-cli": "^6.6.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/{secret-DzSQx1Ds.mjs → secret-BuMuFR4B.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 { a as isStringArray, i as checkedResponse } from "./_api-client-LgLksMhN.mjs";
-import { t as secretRequest } from "./_slug-api-D2heILuC.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-U3jhKlA3.mjs";
+import { t as secretRequest } from "./_slug-api-BxrsJXVI.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";

package/dist/{storage-C-Do0mIA.mjs → storage-DzRZ-eCw.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
-import { i as checkedResponse } from "./_api-client-LgLksMhN.mjs";
-import { n as slugRequest } from "./_slug-api-D2heILuC.mjs";
+import { f as checkedResponse } from "./_studio-U3jhKlA3.mjs";
+import { n as slugRequest } from "./_slug-api-BxrsJXVI.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 //#region storage.ts

package/dist/{studio-BGVmCA2G.mjs → studio-BCNUpDgP.mjs}

@@ -3,10 +3,9 @@ import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
 import { s as updateProjectConfig } from "./_config-D_s09e7g.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
-import { a as resolveDeployTarget } from "./_agent-vGW5SBnX.mjs";
-import { layerScaffold } from "./_templates-iDGjGiPf.mjs";
-import { i as checkedResponse, n as apiRequest } from "./_api-client-LgLksMhN.mjs";
-import { a as publishStudioProject, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectUrl, t as collectSourceFiles } from "./_studio-zAJycZ8j.mjs";
+import { a as resolveDeployTarget } from "./_agent-DpH2pBJd.mjs";
+import { layerScaffold } from "./_templates-Dxb_P2Wz.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-U3jhKlA3.mjs";
 import path from "node:path";
 import { isRecord } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
@@ -148,7 +147,7 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, project) {
 	const env = await resolveServerEnv(cwd);
 	const names = Object.keys(env);
 	if (names.length === 0) return [];
-	await apiRequest(`${serverUrl}/studio/projects/${encodeURIComponent(project)}/secret`, {
+	await apiRequest(`${studioProjectApiUrl(serverUrl, project)}/secret`, {
 		apiKey,
 		action: "secret",
 		method: "PUT",

package/dist/templates/retail/resolve.ts

@@ -10,9 +10,25 @@
  */
 
 import { isToolFailure, resolveOne, spokenDigits, type ToolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
 import type { Order, OrderStatus, Product, RetailState } from "./shared.ts";
 import { authenticatedUser } from "./store.ts";
 
+/**
+ * The `order_id` parameter, for the seven tools that take one.
+ *
+ * Same reasoning as `AddressFields` in `address.ts`, and here the stakes are the
+ * DESCRIPTION: it is the sentence that tells the model a spoken reference is
+ * acceptable, so a copy that lost the second half would quietly make one tool
+ * demand a literal id while its six siblings accept "the last one". It belongs in
+ * this module because "what an order id looks like when a caller reads it aloud"
+ * is exactly what {@link resolveOrder} implements.
+ */
+export const OrderIdField = z
+  .string()
+  .max(120)
+  .describe("Order id such as '#W0000000', or a spoken reference to one of their orders");
+
 /** `#W5866402` from anything STT plausibly produces for it. */
 export function normalizeOrderId(spoken: string): string {
   const compact = spoken.toUpperCase().replace(/[^A-Z0-9]/g, "");

package/dist/templates/retail/store.ts

@@ -158,6 +158,26 @@ export function requireOwnOrder(state: RetailState, orderId: string): Order | To
   return order;
 }
 
+/**
+ * The authenticated customer, when `userId` names them.
+ *
+ * The wrapper's auth gate says a customer is on the call; a tool whose schema
+ * takes a `user_id` also needs to know the caller named THAT customer, and only
+ * one message is right for the second. Two tools had the pair of guards written
+ * out, so the message was maintained in two places — the same reason
+ * {@link requireOwnOrder} exists one rule up.
+ */
+export function requireOwnUser(state: RetailState, userId: string): User | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+  if (user.user_id !== userId) {
+    return {
+      error: `${userId} is not the customer on this call. You can help only one customer per conversation.`,
+    };
+  }
+  return user;
+}
+
 // ─── The tool wrapper ────────────────────────────────────────────────────────
 
 interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {

package/dist/templates/retail/tools/cancel_pending_order.ts

@@ -1,7 +1,7 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { creditRefund, REFUND_DELAY_NOTE, REFUND_IMMEDIATE_NOTE } from "../refund.ts";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { authenticatedUser, retailTool, setFocus } from "../store.ts";
 
 /** tau2 accepts exactly these two. Anything else is refused. */
@@ -15,10 +15,7 @@ export default retailTool({
     "State the order, its total and the refund destination to the caller and get an explicit yes " +
     "before calling this.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     reason: z
       .enum(CANCEL_REASONS)
       .describe("Either 'no longer needed' or 'ordered by mistake' — no other reason is accepted"),

package/dist/templates/retail/tools/exchange_delivered_order_items.ts

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { authenticatedUser, money, retailTool, setFocus } from "../store.ts";
 import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
@@ -13,10 +13,7 @@ export default retailTool({
     "back, and get an explicit yes. No new order is needed — the customer gets an email explaining " +
     "how to send the originals back.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     item_ids: z
       .array(z.string().max(60))
       .max(20)

package/dist/templates/retail/tools/get_order_details.ts

@@ -1,6 +1,7 @@
 import { isToolFailure } from "@alexkroman1/aai";
+import { omitUndefined } from "@alexkroman1/aai/utils";
 import { z } from "zod";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
@@ -10,10 +11,7 @@ export default retailTool({
     "order id (e.g. '#W0000000' — note the leading '#'), or a spoken reference such as " +
     "'my pending order', 'the delivered one', or 'the second pending order'.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
   }),
   execute: (args, state) => {
     const order = resolveOrder(state, args.order_id);
@@ -31,7 +29,7 @@ export default retailTool({
         options: item.options,
       })),
       payment_history: order.payment_history,
-      ...(order.fulfillments ? { fulfillments: order.fulfillments } : {}),
+      ...omitUndefined({ fulfillments: order.fulfillments }),
       ...(order.cancel_reason ? { cancel_reason: order.cancel_reason } : {}),
     };
   },

package/dist/templates/retail/tools/get_user_details.ts

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { authenticatedUser, retailTool } from "../store.ts";
+import { requireOwnUser, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "get_user_details",
@@ -11,13 +11,8 @@ export default retailTool({
     user_id: z.string().max(100).describe("The user id, e.g. 'sara_doe_496'"),
   }),
   execute: (args, state) => {
-    const user = authenticatedUser(state);
+    const user = requireOwnUser(state, args.user_id);
     if (isToolFailure(user)) return user;
-    if (user.user_id !== args.user_id) {
-      return {
-        error: `${args.user_id} is not the customer on this call. You can help only one customer per conversation.`,
-      };
-    }
     return {
       user_id: user.user_id,
       name: `${user.name.first_name} ${user.name.last_name}`,

package/dist/templates/retail/tools/modify_pending_order_address.ts

@@ -1,7 +1,7 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { AddressFields, formatAddress, toAddress } from "../address.ts";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
@@ -10,10 +10,7 @@ export default retailTool({
     "Change the shipping address of a pending order. Read the new address back to the caller and " +
     "get an explicit yes before calling this. This does not change the customer's default address.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     ...AddressFields,
   }),
   execute: (args, state) => {

package/dist/templates/retail/tools/modify_pending_order_items.ts

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { authenticatedUser, isGiftCard, money, retailTool, setFocus } from "../store.ts";
 import { applySwap, assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
@@ -13,10 +13,7 @@ export default retailTool({
     "list and the price difference back, and get an explicit yes first. The item and replacement " +
     "lists are positional and must be the same length.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     item_ids: z
       .array(z.string().max(60))
       .max(20)

package/dist/templates/retail/tools/modify_pending_order_payment.ts

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import {
   authenticatedUser,
   findPaymentMethod,
@@ -17,10 +17,7 @@ export default retailTool({
     "from the current one, and a gift card must hold enough to cover the whole order. The original " +
     "method is refunded. Read the change back and get an explicit yes before calling this.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     payment_method_id: z
       .string()
       .max(80)

package/dist/templates/retail/tools/modify_user_address.ts

@@ -1,7 +1,7 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { AddressFields, formatAddress, toAddress } from "../address.ts";
-import { authenticatedUser, retailTool } from "../store.ts";
+import { requireOwnUser, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "modify_user_address",
@@ -14,13 +14,8 @@ export default retailTool({
     ...AddressFields,
   }),
   execute: (args, state) => {
-    const user = authenticatedUser(state);
+    const user = requireOwnUser(state, args.user_id);
     if (isToolFailure(user)) return user;
-    if (user.user_id !== args.user_id) {
-      return {
-        error: `${args.user_id} is not the customer on this call. You can help only one customer per conversation.`,
-      };
-    }
 
     user.address = toAddress(args);
     return {

package/dist/templates/retail/tools/return_delivered_order_items.ts

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { resolveOrder } from "../resolve.ts";
+import { OrderIdField, resolveOrder } from "../resolve.ts";
 import {
   authenticatedUser,
   findPaymentMethod,
@@ -18,10 +18,7 @@ export default retailTool({
     "explicit yes before calling this. The customer gets an email explaining how to send the " +
     "items back.",
   inputSchema: z.object({
-    order_id: z
-      .string()
-      .max(120)
-      .describe("Order id such as '#W0000000', or a spoken reference to one of their orders"),
+    order_id: OrderIdField,
     item_ids: z
       .array(z.string().max(60))
       .max(20)

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

@@ -18,14 +18,13 @@
  */
 
 import { stubReporter, stubStepFetch, stubUploads } from "@alexkroman1/aai/testing";
-import { readUpload } from "@alexkroman1/aai/utils";
+import { omitUndefined, readUpload } from "@alexkroman1/aai/utils";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError, RetryableError } from "workflow";
 import { z } from "zod";
 import agentDef, { transcribe, transcribeBatch, transcribeStream } from "./agent.ts";
 import { createJob, pollTranscript, readTranscript, uploadToProvider } from "./workflows/batch.ts";
 import { planStreamed, probeUpload } from "./workflows/stream.ts";
-
 import {
   clock,
   mergeTranscript,
@@ -539,7 +538,7 @@ describe("transcribeSegment", () => {
     const stub = stubStepFetch(() => ({
       status: sync.status ?? 200,
       body: sync.body ?? { text: "hello there" },
-      ...(sync.headers && { headers: sync.headers }),
+      ...omitUndefined({ headers: sync.headers }),
     }));
     stubs.push(stub.restore);
     return stub.calls;

package/dist/templates/transcription-workflow/client.tsx

@@ -61,11 +61,13 @@
  * CONTIGUOUS prefix, which is honest whether one connection or four are filling
  * it).
  *
- * It is selectable rather than always-on for the reason the modes are: this is the
- * template where a reader runs both over the same recording and sees what each
- * costs. It also degrades on its own — a small file, or an agent deployed before
- * the `/parts` routes existed, sends the single request instead — so leaving it on
- * is safe.
+ * The SDK does this by DEFAULT, so the checkbox is an opt-OUT rather than an
+ * opt-in — and it is here for the reason the mode radios are: this is the template
+ * where a reader runs both over the same recording and sees what each costs. It
+ * also degrades on its own — a small file, or an agent deployed before the
+ * `/parts` routes existed, sends the single request instead — so leaving it on is
+ * safe, and turning it off costs retries as well as speed (a single request is the
+ * one upload path that cannot be re-sent).
  *
  * ## The transcript ARRIVES, rather than appearing at the end
  *
@@ -342,7 +344,8 @@ function UploadPicker({
           <span>Split the file across connections</span>
           <span className="text-xs opacity-70">
             Sends the recording as several parts at once instead of in one request, which is most of
-            the wait on a long file. Falls back to the single request on a small one.
+            the wait on a long file — and is the only upload a dropped connection can resume. Falls
+            back to the single request on a small one.
           </span>
         </span>
       </label>

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

@@ -45,8 +45,9 @@
  */
 
 import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
-import { readUpload, report, requireStepEnv, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
+import { readUpload, report, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
+import { apiKeyOrFatal } from "./sync-api.ts";
 import { countWords, startClock, type Transcript } from "./transcribe.ts";
 
 /** The async API's base. */
@@ -66,9 +67,6 @@ const API = "https://api.assemblyai.com";
  */
 const MODELS = ["universal-3-5-pro"];
 
-/** The key a step reads out of the agent env. Declared in `agent.ts`'s `requiredEnv`. */
-const API_KEY_ENV = "ASSEMBLYAI_API_KEY";
-
 /** How much of our stored upload one outbound window carries. */
 const UPLOAD_WINDOW_BYTES = 4 * 1024 * 1024;
 
@@ -277,15 +275,6 @@ async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Arr
   }
 }
 
-/** The API key, or a terminal failure — three more attempts find the same gap. */
-function apiKeyOrFatal(): string {
-  try {
-    return requireStepEnv(API_KEY_ENV);
-  } catch (err: unknown) {
-    return throwFatalStepError(err);
-  }
-}
-
 /** A failed call, classified for the DevKit — see `sync-api.ts` for the three-way rule. */
 async function failure(res: Response, what: string): Promise<Error> {
   const body = (await res.json().catch(() => ({}))) as { error?: string };

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

@@ -123,6 +123,7 @@ import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/
 import { sleep } from "workflow";
 import {
   clock,
+  fatalOnUnsupported,
   mergeTranscript,
   type SegmentTranscript,
   segmentConcurrency,
@@ -323,16 +324,6 @@ function expectedSegments(plan: StreamPlan, size: number): number {
   return plan.segments.filter((segment) => segment.start < size).length;
 }
 
-/** Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure. */
-function fatalOnUnsupported<T>(read: () => T): T {
-  try {
-    return read();
-  } catch (err: unknown) {
-    if (err instanceof UnsupportedRecordingError) return throwFatalStepError(err);
-    throw err;
-  }
-}
-
 /**
  * Give up on an upload that stopped arriving.
  *

package/dist/templates/transcription-workflow/workflows/sync-api.ts

@@ -104,8 +104,14 @@ export async function transcribeWav(
   return (body.text ?? "").trim();
 }
 
-/** The API key, or a terminal failure — three more attempts find the same gap. */
-function apiKeyOrFatal(): string {
+/**
+ * The API key, or a terminal failure — three more attempts find the same gap.
+ *
+ * Exported because `batch.ts` calls the same provider on the same key and had
+ * written this, and its own `API_KEY_ENV`, again. The key belongs to the
+ * PROVIDER; only the endpoint and its failure shapes belong to this module.
+ */
+export function apiKeyOrFatal(): string {
   try {
     return requireStepEnv(API_KEY_ENV);
   } catch (err: unknown) {

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

@@ -422,8 +422,14 @@ export {
 
 // ---- I/O helpers ------------------------------------------------------------
 
-/** Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure. */
-function fatalOnUnsupported<T>(read: () => T): T {
+/**
+ * Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure.
+ *
+ * Exported for the same reason `countWords` is: `stream.ts` plans with the same
+ * `wav.ts` helpers and owes the same classification, and it had this byte for
+ * byte.
+ */
+export function fatalOnUnsupported<T>(read: () => T): T {
   try {
     return read();
   } catch (err: unknown) {

package/dist/{test-B6ZBxSpk.mjs → test-9kPKJI-w.mjs}

@@ -38,9 +38,7 @@ function resolveVitestCommand(cwd, resolve = createRequire(path.join(cwd, "packa
 * Throws on test failure.
 */
 function runVitest(cwd) {
-	let testFile = null;
-	if (existsSync(path.join(cwd, "agent.test.ts"))) testFile = "agent.test.ts";
-	else if (existsSync(path.join(cwd, "agent.test.js"))) testFile = "agent.test.js";
+	const testFile = ["agent.test.ts", "agent.test.js"].find((name) => existsSync(path.join(cwd, name)));
 	if (!testFile) return false;
 	const { cmd, args } = resolveVitestCommand(cwd);
 	execaSync(cmd, [

package/dist/typecheck.mjs

@@ -155,12 +155,11 @@ async function typecheckProject(cwd) {
 		});
 		let output = "";
 		const keep = (s) => s.length > OUTPUT_CAP ? `…${s.slice(-16e3)}` : s;
-		child.stdout.on("data", (chunk) => {
+		const append = (chunk) => {
 			output = keep(output + chunk.toString());
-		});
-		child.stderr.on("data", (chunk) => {
-			output = keep(output + chunk.toString());
-		});
+		};
+		child.stdout.on("data", append);
+		child.stderr.on("data", append);
 		child.on("error", reject);
 		child.on("close", (code, signal) => {
 			if (signal) {