@alexkroman1/aai-cli 6.5.1 → 6.7.0

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.1",
-    "@alexkroman1/aai-ui": "^6.5.1",
+    "@alexkroman1/aai": "^6.7.0",
+    "@alexkroman1/aai-ui": "^6.7.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.1",
+    "@alexkroman1/aai-cli": "^6.7.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

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
  *
@@ -104,6 +106,22 @@
  * whose schema has an object or array property writes those fields itself, in
  * the same `<Form>` — every field in `@alexkroman1/aai-ui` is a plain named
  * control, so declared and hand-written ones mix freely.
+ *
+ * ## Two waits, ONE number
+ *
+ * The two bars describe the two stretches separately, and neither answers the
+ * question a reader comparing the three modes is actually asking: how long from
+ * pressing Transcribe to having a transcript. Nothing on the server can answer it
+ * either — `output.elapsedMs` is the RUN's own wall clock, so it starts after the
+ * bytes are stored in two of the three modes and misses the whole upload, which is
+ * most of the wait on a long file over a slow link. Only the browser holds both
+ * ends, so `useTotalLatency` is a stopwatch here: started by the submit, ticking
+ * across the upload and the run alike, and frozen the moment the run settles.
+ *
+ * `<TotalLatency>` also prints the SPLIT once the run reports its own elapsed —
+ * before the run and inside it — because the two numbers on screen otherwise
+ * disagree with no way to see why, and their difference is exactly what picking a
+ * mode or unchecking `parallel` moves.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -122,7 +140,7 @@ import {
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { transcribe } from "./agent.ts";
 import { ApiHelp } from "./api-help.tsx";
 import {
@@ -185,6 +203,132 @@ const MODES: readonly { mode: Mode; label: string; note: string }[] = [
 /** Most past runs the history list shows. */
 const HISTORY_LIMIT = 10;
 
+/**
+ * How often the running stopwatch re-renders.
+ *
+ * Under a second, so the displayed seconds turn over promptly rather than up to a
+ * second late; nothing reads this value, since the elapsed time is measured from
+ * the clock at render (see {@link useTotalLatency}).
+ */
+const STOPWATCH_TICK_MS = 250;
+
+/** What {@link useTotalLatency} reports. */
+type TotalLatency = {
+  /**
+   * Milliseconds since the submit — ticking while the submission is in flight,
+   * frozen at the finish, and undefined before the first one.
+   */
+  elapsedMs: number | undefined;
+  /** Whether the clock is still running, which is what makes the label honest. */
+  running: boolean;
+  /** Start (or restart) the clock. Called from the form's own submit handler. */
+  start: () => void;
+  /** Drop it, for a panel that no longer describes the submission it timed. */
+  clear: () => void;
+};
+
+/**
+ * Wall clock from the submit to the finish, across both waits.
+ *
+ * `inFlight` is the submission's own `pending` — true from `submit()` until the run
+ * reaches a terminal status — so the clock covers the upload, the run, and the
+ * gap between them, which is the whole of what a reader waits for and is the one
+ * measurement no server-side number can make.
+ *
+ * Two details it would be easy to get wrong:
+ *
+ * - **The interval re-renders; it does not accumulate.** The elapsed time is read
+ *   from the clock at render, so a tick the tab throttled or dropped cannot make
+ *   the number lag behind real time.
+ * - **`performance.now()`, not `Date.now()`.** It is monotonic, so a clock
+ *   correction (NTP, a laptop waking up) cannot make a transcription look
+ *   instant — or negative.
+ */
+function useTotalLatency(inFlight: boolean): TotalLatency {
+  const [startedAt, setStartedAt] = useState<number | undefined>(undefined);
+  const [frozenMs, setFrozenMs] = useState<number | undefined>(undefined);
+  // Re-render trigger only — see the doc above.
+  const [, tick] = useState(0);
+  // Whether `inFlight` has been seen true since the last `start()`. Without it,
+  // a start that lands one render before the submission reports itself in flight
+  // would freeze the clock at zero instead of running it.
+  const began = useRef(false);
+
+  useEffect(() => {
+    if (startedAt === undefined || frozenMs !== undefined) return;
+    if (inFlight) {
+      began.current = true;
+      const id = setInterval(() => tick((n) => n + 1), STOPWATCH_TICK_MS);
+      return () => clearInterval(id);
+    }
+    // Measured here rather than at render, so the frozen number is the one at the
+    // moment the run settled rather than whenever this page next drew.
+    if (began.current) setFrozenMs(performance.now() - startedAt);
+  }, [startedAt, frozenMs, inFlight]);
+
+  const start = useCallback(() => {
+    began.current = false;
+    setFrozenMs(undefined);
+    setStartedAt(performance.now());
+  }, []);
+
+  const clear = useCallback(() => {
+    began.current = false;
+    setStartedAt(undefined);
+    setFrozenMs(undefined);
+  }, []);
+
+  return {
+    elapsedMs: frozenMs ?? (startedAt === undefined ? undefined : performance.now() - startedAt),
+    running: startedAt !== undefined && frozenMs === undefined,
+    start,
+    clear,
+  };
+}
+
+/**
+ * The one number the two bars cannot give: click to transcript.
+ *
+ * Rendered above the run panel rather than inside it, because the stretch it
+ * covers starts before there IS a run — in two of the three modes the run does
+ * not exist until the upload finishes, so a clock living in the panel would
+ * appear only after the wait it is supposed to be timing.
+ *
+ * `runMs` is the run's own elapsed, once it reports one. The remainder is
+ * everything the run could not see: storing the file (or, in streaming mode,
+ * minting the upload id), the `POST` that starts the run, and the poll that
+ * notices it finished. Clamped at zero, because the two numbers come from two
+ * different clocks on two different machines and a few milliseconds the wrong way
+ * would otherwise print a negative.
+ */
+function TotalLatency({
+  elapsedMs,
+  running,
+  runMs,
+}: {
+  elapsedMs: number | undefined;
+  running: boolean;
+  runMs: number | undefined;
+}) {
+  if (elapsedMs === undefined) return null;
+  const outside = runMs === undefined ? undefined : Math.max(0, elapsedMs - runMs);
+  return (
+    <section className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1 rounded-md border px-5 py-3">
+      <h2 className="text-sm font-medium uppercase tracking-[1.2px]">
+        {running ? "Elapsed" : "Total latency"}
+      </h2>
+      <span className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
+        <span className="text-sm tabular-nums">{duration(elapsedMs)}</span>
+        {runMs !== undefined && outside !== undefined && (
+          <span className="text-xs tabular-nums opacity-60">
+            {duration(outside)} before the run · {duration(runMs)} inside it
+          </span>
+        )}
+      </span>
+    </section>
+  );
+}
+
 function TranscriptionDesk() {
   const [mode, setMode] = useState<Mode>("streaming");
   // Whether the browser cuts the recording up and sends the pieces at once. One
@@ -209,6 +353,8 @@ function TranscriptionDesk() {
   // Which past run the reader is looking at, if any. Its own state rather than
   // a route, because a workflow app is one page and a run id is not a place.
   const [openId, setOpenId] = useState<string | undefined>(undefined);
+  // Click to transcript, measured here because only the browser sees both ends.
+  const total = useTotalLatency(pending);
 
   // The list is read once and re-read on demand (see `useWorkflowRuns`), and
   // this is the "on demand": the moment the run this page started settles, the
@@ -231,14 +377,34 @@ function TranscriptionDesk() {
         </p>
       </header>
 
-      <ModePicker mode={mode} onPick={setMode} disabled={pending} />
+      {/* The clock goes with the mode: switching swaps `active` for another hook's
+          run, and a total measured over a different submission would be a number
+          for something the panel below is no longer showing. */}
+      <ModePicker
+        mode={mode}
+        onPick={(next) => {
+          setMode(next);
+          total.clear();
+        }}
+        disabled={pending}
+      />
 
       <UploadPicker parallel={parallel} onPick={setParallel} disabled={pending} />
 
       {/* No mapping: the collected values already match the input schema. All three
           workflows declare `recording` as an upload, so the same picker serves every
           mode — how the bytes travel is not a question to ask a person. */}
-      <Form onSubmit={(values) => submit(values)} error={error}>
+      {/* The clock starts HERE, which is as close to the press as a page can get:
+          `<Form>` calls this once the browser's own validation has passed and it has
+          read the controls, and an upload field contributes its `File` unread — so
+          what separates this line from the click is a microtask, not the file. */}
+      <Form
+        onSubmit={(values) => {
+          total.start();
+          return submit(values);
+        }}
+        error={error}
+      >
         {/* The NAME, so the schema is fetched here rather than by this page. */}
         <WorkflowFields workflow={WORKFLOWS[mode]} />
         {/* Unguarded on purpose: it renders nothing until there are bytes in
@@ -247,7 +413,21 @@ function TranscriptionDesk() {
         <SubmitButton pending={pending}>Transcribe</SubmitButton>
       </Form>
 
-      {run && <RunPanel run={run} onClear={reset} />}
+      <TotalLatency
+        elapsedMs={total.elapsedMs}
+        running={total.running}
+        runMs={run?.status === "completed" ? run.output.elapsedMs : undefined}
+      />
+
+      {run && (
+        <RunPanel
+          run={run}
+          onClear={() => {
+            reset();
+            total.clear();
+          }}
+        />
+      )}
 
       <History
         runs={history.runs}
@@ -342,7 +522,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.5.1",
+  "version": "6.7.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,8 +44,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "6.5.1",
-    "@alexkroman1/aai-ui": "6.5.1"
+    "@alexkroman1/aai": "6.7.0",
+    "@alexkroman1/aai-ui": "6.7.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",