@alexkroman1/aai-cli 6.7.1 → 6.8.0

package/dist/scaffold/package.json

@@ -13,8 +13,8 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.7.1",
-    "@alexkroman1/aai-ui": "^6.7.1",
+    "@alexkroman1/aai": "^6.8.0",
+    "@alexkroman1/aai-ui": "^6.8.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.7.1",
+    "@alexkroman1/aai-cli": "^6.8.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

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

@@ -107,6 +107,32 @@
  * the same `<Form>` — every field in `@alexkroman1/aai-ui` is a plain named
  * control, so declared and hand-written ones mix freely.
  *
+ * ## A long upload can be PAUSED, and survives the agent restarting
+ *
+ * The same wait is the one thing on this page a person may want to interrupt: a
+ * 600 MB recording is minutes of a laptop's uplink, and needing it back for a
+ * call should not cost the upload. So `<UploadProgressBar>` takes the hook's
+ * `pauseUpload`/`resumeUpload` and draws a button — every mode, because every
+ * mode is sending a file.
+ *
+ * **Nothing in this template implements it**, which is the part worth reading.
+ * Pausing is an abort plus an id: the windows already sent are stored under an
+ * upload id the hook minted, so resuming reads back which ranges landed and sends
+ * only the rest. That is the same mechanism the SDK uses on its own when a round
+ * fails for a reason that looks like an outage — a redeploy, a sandbox reclaimed
+ * on idle, `aai dev` restarting on a save — so an agent that goes away mid-upload
+ * is a pause nobody asked for, and the upload picks up where it stopped.
+ *
+ * The two flows differ in what a pause costs, and only in that:
+ *
+ * - **"After it uploads"** and **"the async API"** have no run yet, so a pause
+ *   costs nothing at all. The form simply has not been submitted.
+ * - **"While it uploads"** has a run watching the id already, and to a run a
+ *   paused upload is one whose `size` stopped growing — which is exactly what a
+ *   slow uplink looks like. `workflows/stream.ts` gives that five minutes
+ *   (`MAX_IDLE_POLLS`) before it calls the uploader gone and fails the run, so a
+ *   pause longer than a coffee ends the run rather than the upload.
+ *
  * ## Two waits, ONE number
  *
  * The two bars describe the two stretches separately, and neither answers the
@@ -345,7 +371,7 @@ function TranscriptionDesk() {
   // store — so it is the SAME hook against a different workflow. Only the streaming
   // mode needs the other one, because only it needs the id before the bytes.
   const active = mode === "streaming" ? streamed : mode === "batch" ? batched : stored;
-  const { submit, run, upload, pending, error, reset } = active;
+  const { submit, run, upload, pending, error, reset, pauseUpload, resumeUpload } = active;
   // History is per WORKFLOW, so the list follows the mode: two flows that produce
   // the same output are still two different things to have run, and merging them
   // would put a run under a heading that cannot explain it.
@@ -408,8 +434,10 @@ function TranscriptionDesk() {
         {/* 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
-            flight, and nothing again once they have landed. */}
-        <UploadProgressBar upload={upload} />
+            flight, and nothing again once they have landed. The handlers are what
+            turn the bar into a control — see "A long upload can be PAUSED" above;
+            all three hooks expose the same pair, so `active` needs no branch. */}
+        <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
         <SubmitButton pending={pending}>Transcribe</SubmitButton>
       </Form>
 

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

@@ -91,9 +91,29 @@
  * realtime, so a recording long enough for the difference to matter is a recording
  * whose upload dominates either way.
  *
- * It grows with LENGTH rather than with size, because concurrency is capped: a
- * 97-minute recording is ~65 segments in ~9 rounds, and eight of those rounds happen
- * behind the upload instead of after it.
+ * Precisely: both flows are `upload + rounds x one segment`, streaming is always
+ * ONE round (only the last segment is left when the bytes land), and the classic
+ * flow is `ceil(segments / segmentConcurrency)`. So the saving is
+ * `(rounds - 1) x segment latency` and **it is ZERO whenever the classic fan-out
+ * fits in one round** — which is most files, because that width is 32:
+ *
+ * | recording | segments | classic rounds | saving |
+ * | --- | --- | --- | --- |
+ * | 12 min, 48 kHz stereo (130 MB) | 8 | 1 | none, by construction |
+ * | 60 min, 48 kHz stereo (660 MB) | 41 | 2 | one segment |
+ * | 6 h, 16 kHz mono (660 MB) | 241 | 8 | seven segments |
+ *
+ * It therefore grows with the SEGMENT COUNT, which is duration over bitrate — not
+ * with file size. The two 660 MB rows are the point: same bytes, same width, and
+ * the low-bitrate one has six times the segments and six times the benefit.
+ *
+ * This paragraph used to claim a 97-minute recording was "~65 segments in ~9
+ * rounds, and eight of those rounds happen behind the upload". The segment count
+ * was right and the rounds were not: at width 32 that is 3 rounds, so at most 2
+ * are hidden. It described a width of ~7, which is what `mapInBatches` and a
+ * smaller `BYTES_IN_FLIGHT` gave before either moved — and it overstated this
+ * flow's benefit about fourfold, which is exactly the expectation a reader brings
+ * to the mode picker and then finds unmet.
  *
  * What it always buys, at any length, is the thing a table cannot show: the page
  * shows real progress — segment timings, arriving — while the bytes are still

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.7.1",
+  "version": "6.8.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-ui": "6.7.1",
-    "@alexkroman1/aai": "6.7.1"
+    "@alexkroman1/aai-ui": "6.8.0",
+    "@alexkroman1/aai": "6.8.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",