@alexkroman1/aai-ui 9.2.0 → 10.0.0

package/dist/default-client/index.html

@@ -6,7 +6,7 @@
     <title>aai</title>
     <link rel="icon" href="./favicon.ico" />
     <style>html, body { background: #FBF8F2; margin: 0; }</style>
-    <script type="module" crossorigin src="./assets/index-CA2w_SUi.js"></script>
+    <script type="module" crossorigin src="./assets/index-DS-RCrri.js"></script>
     <link rel="modulepreload" crossorigin href="./assets/client-audio-constants-Ck0IJO4c.js">
     <link rel="stylesheet" crossorigin href="./assets/index-S5fkKi6B.css">
   </head>

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export type { AgentCustomEvent, SessionCore, SessionSnapshot, } from "./session-
 export type { AgentState, ChatMessage, ClientTheme, SessionError, SessionErrorCode, ToolCallInfo, VoiceSessionOptions, WebSocketConstructor, } from "./types.ts";
 export { type ConversationItem, type UseConversationResult, useConversation, } from "./use-conversation.ts";
 export { type UseDownloadUrlOptions, type UseDownloadUrlResult, useDownloadUrl, } from "./use-download-url.ts";
+export { useRunKey } from "./use-run-key.ts";
 export { type UseUserTranscriptResult, useUserTranscript } from "./use-user-transcript.ts";
 export { type UploadStatus, type UseWorkflowSubmitOptions, type UseWorkflowsOptions, type UseWorkflowsResult, useWorkflowSubmit, useWorkflows, type WorkflowSubmission, } from "./use-workflow-form.ts";
 export { type UseWorkflowProgressResult, useWorkflowProgress, } from "./use-workflow-progress.ts";

package/dist/index.js

@@ -10,7 +10,7 @@ import { n as useUserTranscript } from "./use-user-transcript-C14qWFu2.js";
 import { n as ToolCallRow } from "./tool-call-block-B7KlhaWl.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { a as useWorkflowRun, c as isTerminal, n as useWorkflowProgress, o as useWorkflowApiRef, s as createWorkflowApi } from "./use-workflow-progress-C4KgVldr.js";
+import { a as useWorkflowRun, c as isTerminal, n as useWorkflowProgress, o as useWorkflowApiRef, s as createWorkflowApi } from "./use-workflow-progress-Cu0SxMyg.js";
 import { t as createSessionCore } from "./session-core-0hClhPz-.js";
 import { client, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
@@ -760,6 +760,94 @@ function UploadProgressBar({ upload, onPause, onResume, className }) {
 	});
 }
 //#endregion
+//#region _recover-run.ts
+/**
+* Finding a run again when the page has lost its id.
+*
+* A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
+* which was only half true of the hooks above it: the run id lived in plain
+* `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
+* live run with nothing anywhere able to name it. The run really did continue;
+* the person really could not get back to it.
+*
+* `StartOptions.key` is the handle that survives that, and it always was — a
+* caller's own name for a run, indexed by the agent, read back with
+* `find(workflow, key)`. What was missing is the two lines that ASK. This is
+* them, plus the four decisions they turn out to carry.
+*
+* ## It is a MOUNT-time act, not "whenever there is no run"
+*
+* The tempting spelling is "if we hold no run id, look one up", and it breaks
+* `reset()`: a form put back to its initial state holds no run id, so the next
+* pass would re-adopt the very run the person had just dismissed — a Clear
+* button that clears nothing. So the lookup runs once per mount (and again only
+* if the KEY changes, which is a different person's run), and every later
+* absence of a run id is taken at face value.
+*
+* ## The lookup NEVER wins a race against a submit
+*
+* A person who reloads and immediately submits has started the run they want,
+* and an answer that was already in flight names an older one. The caller
+* therefore adopts through `current ?? found`: the recovered id fills an empty
+* slot and never replaces a full one.
+*
+* ## A failed lookup is REPORTED
+*
+* The alternative is a page that quietly shows an empty form to somebody whose
+* run is live, who then starts a second one — the duplicated work the key
+* exists to prevent, and on a workflow app that is real money. A person who has
+* never run anything pays a banner they can ignore. Same trade as
+* `useWorkflows`, for the same reason: an empty answer here is a confident
+* false statement.
+*
+* ## It is OPT-IN
+*
+* A `key` on its own still means only "record this with the run", which is what
+* a voice agent's `ctx.workflows.start({ key })` means and what a page passing
+* an account id may well want. Adopting a run is a decision about the PAGE, so
+* it is `recover: true` and the two together read as what they do.
+*/
+/**
+* Look up the newest run for a key, once, as the component mounts.
+*
+* @param opts - See {@link RecoverRunOptions}.
+* @returns Whether the lookup is still out. A caller folds it into its own
+*   `pending`, because a form offering Submit while a live run is arriving is a
+*   form inviting a second one.
+*
+* @internal
+*/
+function useRecoveredRun(opts) {
+	const { workflow, key, enabled, getClient } = opts;
+	const [recovering, setRecovering] = useState(enabled && key !== void 0);
+	const handlers = useRef(opts);
+	handlers.current = opts;
+	useEffect(() => {
+		if (!enabled || key === void 0) return;
+		let cancelled = false;
+		setRecovering(true);
+		getClient().find(workflow, key, { limit: 1 }).then((found) => {
+			if (cancelled) return;
+			const newest = found[0];
+			if (newest !== void 0) handlers.current.onFound(newest.runId);
+			setRecovering(false);
+		}).catch((err) => {
+			if (cancelled) return;
+			handlers.current.onError(errorMessage(err));
+			setRecovering(false);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		enabled,
+		key,
+		workflow,
+		getClient
+	]);
+	return recovering;
+}
+//#endregion
 //#region _run-controls.ts
 /**
 * The two things a page does TO a run it started, bound to the run it has.
@@ -838,7 +926,7 @@ function useRunControls(runId, getClient) {
 * under a blocking policy, and an upload that cannot be REMEMBERED must degrade
 * to the upload we would have done anyway rather than failing to start.
 */
-const PREFIX = "aai:upload:";
+const PREFIX$1 = "aai:upload:";
 /**
 * How many ids one form keeps.
 *
@@ -850,7 +938,7 @@ const PREFIX = "aai:upload:";
 const MAX_REMEMBERED = 32;
 /** One form's slot in storage. */
 function keyFor(scope) {
-	return `${PREFIX}${scope}`;
+	return `${PREFIX$1}${scope}`;
 }
 /**
 * What names this file across a reload.
@@ -1406,7 +1494,7 @@ function useWorkflows(opts = {}) {
 * @public
 */
 function useWorkflowSubmit(workflow, opts = {}) {
-	const { api, key, wait, intervalMs, parallel } = opts;
+	const { api, key, recover = false, wait, intervalMs, parallel } = opts;
 	const [runId, setRunId] = useState(void 0);
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
@@ -1418,6 +1506,16 @@ function useWorkflowSubmit(workflow, opts = {}) {
 		intervalMs
 	}));
 	const { wake, cancel } = useRunControls(runId, getClient);
+	const recovering = useRecoveredRun({
+		workflow,
+		key,
+		enabled: recover,
+		getClient,
+		onFound: (found) => {
+			setRunId((current) => current ?? found);
+		},
+		onError: setStartError
+	});
 	const submit = useCallback(async (input) => {
 		const client = getClient();
 		setStarting(true);
@@ -1466,7 +1564,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 		pauseUpload,
 		resumeUpload,
 		run: tracked.run,
-		pending: starting || tracked.polling,
+		pending: recovering || starting || tracked.polling,
 		upload,
 		error: startError ?? tracked.error
 	};
@@ -1814,6 +1912,134 @@ function useDownloadUrl(uploadId, opts = {}) {
 	return state;
 }
 //#endregion
+//#region use-run-key.ts
+/**
+* The handle a page keeps on the runs it started, across a reload.
+*
+* `useWorkflowSubmit({ key, recover: true })` is what makes a run survivable —
+* the run id is that hook's own state, so a refresh loses it while the run
+* carries on — and the `key` is deliberately the caller's to choose, because it
+* is a lookup CAPABILITY: there is no per-user filtering behind `find`, so the
+* key IS the scoping mechanism. Choosing one is easy to get wrong in three
+* separate ways, and six shipped templates had each written the same twenty
+* lines to get it right. This is those lines.
+*
+* ## Three properties, and the rejected alternatives are why each one matters
+*
+* - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
+*   A key derived from the input collides the moment two people submit the same
+*   thing, and they then recover each other's runs; it also carries what they
+*   typed into a lookup token the platform deliberately stopped logging.
+* - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
+*   `POST /workflows/runs` allows a key.
+* - **Minted once per load and written back for the next one**, which is the
+*   whole mechanism: the load that presses the button records the key with the
+*   run, and the load after it finds the run by producing the same key.
+*
+* Storage rather than the page's own URL, for all of them. A `?key=` parameter
+* survives more (a new tab, a bookmark, a shared link) and that is the problem:
+* a URL is pasted into chats, copied into referrers and kept in history, and
+* what a leaked one buys is somebody else's work — reading it, and `cancel()` on
+* it. An app with accounts should pass the ACCOUNT's own id here instead, and
+* then a run follows the person to a new device, which is a promise only a login
+* can keep.
+*
+* ## The storage is the caller's decision, and it is not a detail
+*
+* `"session"` (the default) dies with the tab, which covers exactly the
+* interruption most pages have — a reload, a same-tab navigation, a crashed tab
+* — and is the same lifetime as this package's other two stores, the session
+* resume id (`session-resume-store.ts`) and the upload recall
+* (`_upload-recall.ts`), so both halves of a reload make the same promise.
+*
+* `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
+* between digests and may live a month, where closing the browser on Tuesday and
+* coming back on Friday to press Stop is the ordinary case rather than an edge
+* one, and a tab-scoped key would answer that with an empty form beside a run
+* still posting somewhere. It is as far as a key can go without a login, and no
+* further. `podcast-digest` is that template; the other five ship the default.
+*
+* ## Anything ELSE a page stores back must be VALIDATED on read
+*
+* This key needs no validation, and it is worth saying why, because it is the
+* exception: any string is a legal key, so a value from storage can only fail to
+* match a run. A page that remembers something more — which MODE submitted, say
+* — is remembering a value it will turn into a name, and storage hands back a
+* string some earlier version of that page wrote: a renamed mode, a hand-edited
+* value, a slot another app on the origin happens to share. Unchecked, that
+* starts a run called `undefined` and answers a 400 nobody typed. Check it
+* against the page's own list on the way out (`recalledMode` in
+* `transcription-workflow/recover.ts` is the worked example) — the recall is the
+* page's, the validation is not optional.
+*
+* ## The slot is keyed by the page's own URL
+*
+* Every deployed agent is served from one origin at `/:slug/`, so a fixed name
+* would have two agents scaffolded from the same template recover each other's
+* runs. The key is the page's own directory — resolved through `"./"`, which
+* drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
+* find the same key. Same call `session-resume-store.ts` makes, for the same
+* reason.
+*
+* One key per PAGE is right even for a page driving several workflows: `find` is
+* scoped by workflow as well as by key, so three hooks sharing one key recover
+* three separate runs. `transcription-workflow` is that page.
+*
+* Every access is guarded. Storage THROWS outright in some contexts (Safari
+* private mode, an iframe blocked by policy) and is ABSENT in others (any
+* server-side render), and a page that cannot remember its key must degrade to
+* the behaviour it would have had anyway — one run per load — rather than
+* failing to render.
+*/
+/** Where a run key lives, namespaced like this package's two other stores. */
+const PREFIX = "aai:run-key:";
+/** This page's own slot — see "The slot is keyed by the page's own URL". */
+function slotFor() {
+	const href = globalThis.location?.href;
+	if (href === void 0) return PREFIX;
+	try {
+		return `${PREFIX}${new URL("./", href).href}`;
+	} catch {
+		return `${PREFIX}${href}`;
+	}
+}
+/**
+* Read the key this page already has, or mint and remember one.
+*
+* Not exported: a page that wants a key wants it for the life of a component,
+* which is what the hook is. Calling this per render would mint a fresh key and
+* hand `recover` one nothing was ever started under.
+*/
+function mintRunKey(storage) {
+	try {
+		const store = storage === "local" ? globalThis.localStorage : globalThis.sessionStorage;
+		const slot = slotFor();
+		const stored = store?.getItem(slot);
+		if (stored !== null && stored !== void 0) return stored;
+		const minted = crypto.randomUUID();
+		store?.setItem(slot, minted);
+		return minted;
+	} catch {
+		return crypto.randomUUID();
+	}
+}
+/**
+* A lookup key for `useWorkflowSubmit({ key, recover: true })`, stable across
+* reloads.
+*
+* @param options - See the module doc for the whole argument. The storage kind
+*   is read once, when the key is minted: a value that changed afterwards would
+*   be asking to move a key that has already been recorded with a run.
+* @returns The key to record runs under and to look them up by — the same one
+*   for the life of the component, and for the next load in the same tab (or the
+*   same browser, under `"local"`).
+*/
+function useRunKey(options = {}) {
+	const { storage = "session" } = options;
+	const [key] = useState(() => mintRunKey(storage));
+	return key;
+}
+//#endregion
 //#region use-workflow-runs.ts
 /**
 * The RUNS a workflow has had — the list a page shows beside its form.
@@ -2217,4 +2443,4 @@ const WORKFLOW_STATUS_LABELS = {
 	cancelled: "Cancelled"
 };
 //#endregion
-export { AutoScroll, Button, ChatView, CheckboxField, ConsoleShell, Controls, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SidebarLayout, StartScreen, SubmitButton, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowProgress, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, page, useAgentState, useConversation, useDownloadUrl, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };
+export { AutoScroll, Button, ChatView, CheckboxField, ConsoleShell, Controls, Field, FileField, Form, Markdown, MessageList, NumberField, SelectField, SidebarLayout, StartScreen, SubmitButton, TextAreaField, TextField, ToolCallRow, UploadProgressBar, WORKFLOW_STATUS_LABELS, WorkflowFields, WorkflowProgress, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, page, useAgentState, useConversation, useDownloadUrl, useEvent, useRunKey, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };

package/dist/internal.js

@@ -3,6 +3,6 @@ import { SessionProvider, ThemeProvider } from "./context.js";
 import { n as SessionUrlChips, r as UiUrlChip, t as ApiUrlChip } from "./url-chips-DxXKgyL9.js";
 import { t as TRANSCRIBING_PLACEHOLDER } from "./use-user-transcript-C14qWFu2.js";
 import { t as ToolConfigContext } from "./tool-config-context-DzAofqi_.js";
-import { i as MAX_MISSING_READS, r as DEFAULT_WORKFLOW_POLL_MS, t as DEFAULT_PROGRESS_POLL_MS } from "./use-workflow-progress-C4KgVldr.js";
+import { i as MAX_MISSING_READS, r as DEFAULT_WORKFLOW_POLL_MS, t as DEFAULT_PROGRESS_POLL_MS } from "./use-workflow-progress-Cu0SxMyg.js";
 import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
 export { ApiUrlChip, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS, SessionProvider, SessionUrlChips, TRANSCRIBING_PLACEHOLDER, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, loadClientConfig };

package/dist/use-run-key.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The handle a page keeps on the runs it started, across a reload.
+ *
+ * `useWorkflowSubmit({ key, recover: true })` is what makes a run survivable —
+ * the run id is that hook's own state, so a refresh loses it while the run
+ * carries on — and the `key` is deliberately the caller's to choose, because it
+ * is a lookup CAPABILITY: there is no per-user filtering behind `find`, so the
+ * key IS the scoping mechanism. Choosing one is easy to get wrong in three
+ * separate ways, and six shipped templates had each written the same twenty
+ * lines to get it right. This is those lines.
+ *
+ * ## Three properties, and the rejected alternatives are why each one matters
+ *
+ * - **Opaque** — `crypto.randomUUID()`, never derived from what was submitted.
+ *   A key derived from the input collides the moment two people submit the same
+ *   thing, and they then recover each other's runs; it also carries what they
+ *   typed into a lookup token the platform deliberately stopped logging.
+ * - **Short.** A `randomUUID` is 36 characters, well inside the 256 that
+ *   `POST /workflows/runs` allows a key.
+ * - **Minted once per load and written back for the next one**, which is the
+ *   whole mechanism: the load that presses the button records the key with the
+ *   run, and the load after it finds the run by producing the same key.
+ *
+ * Storage rather than the page's own URL, for all of them. A `?key=` parameter
+ * survives more (a new tab, a bookmark, a shared link) and that is the problem:
+ * a URL is pasted into chats, copied into referrers and kept in history, and
+ * what a leaked one buys is somebody else's work — reading it, and `cancel()` on
+ * it. An app with accounts should pass the ACCOUNT's own id here instead, and
+ * then a run follows the person to a new device, which is a promise only a login
+ * can keep.
+ *
+ * ## The storage is the caller's decision, and it is not a detail
+ *
+ * `"session"` (the default) dies with the tab, which covers exactly the
+ * interruption most pages have — a reload, a same-tab navigation, a crashed tab
+ * — and is the same lifetime as this package's other two stores, the session
+ * resume id (`session-resume-store.ts`) and the upload recall
+ * (`_upload-recall.ts`), so both halves of a reload make the same promise.
+ *
+ * `"local"` is for a run that outlives all of that BY DESIGN — one that sleeps
+ * between digests and may live a month, where closing the browser on Tuesday and
+ * coming back on Friday to press Stop is the ordinary case rather than an edge
+ * one, and a tab-scoped key would answer that with an empty form beside a run
+ * still posting somewhere. It is as far as a key can go without a login, and no
+ * further. `podcast-digest` is that template; the other five ship the default.
+ *
+ * ## Anything ELSE a page stores back must be VALIDATED on read
+ *
+ * This key needs no validation, and it is worth saying why, because it is the
+ * exception: any string is a legal key, so a value from storage can only fail to
+ * match a run. A page that remembers something more — which MODE submitted, say
+ * — is remembering a value it will turn into a name, and storage hands back a
+ * string some earlier version of that page wrote: a renamed mode, a hand-edited
+ * value, a slot another app on the origin happens to share. Unchecked, that
+ * starts a run called `undefined` and answers a 400 nobody typed. Check it
+ * against the page's own list on the way out (`recalledMode` in
+ * `transcription-workflow/recover.ts` is the worked example) — the recall is the
+ * page's, the validation is not optional.
+ *
+ * ## The slot is keyed by the page's own URL
+ *
+ * Every deployed agent is served from one origin at `/:slug/`, so a fixed name
+ * would have two agents scaffolded from the same template recover each other's
+ * runs. The key is the page's own directory — resolved through `"./"`, which
+ * drops the query and the hash, since a reload carrying `?foo` or `#bar` has to
+ * find the same key. Same call `session-resume-store.ts` makes, for the same
+ * reason.
+ *
+ * One key per PAGE is right even for a page driving several workflows: `find` is
+ * scoped by workflow as well as by key, so three hooks sharing one key recover
+ * three separate runs. `transcription-workflow` is that page.
+ *
+ * Every access is guarded. Storage THROWS outright in some contexts (Safari
+ * private mode, an iframe blocked by policy) and is ABSENT in others (any
+ * server-side render), and a page that cannot remember its key must degrade to
+ * the behaviour it would have had anyway — one run per load — rather than
+ * failing to render.
+ */
+/**
+ * A lookup key for `useWorkflowSubmit({ key, recover: true })`, stable across
+ * reloads.
+ *
+ * @param options - See the module doc for the whole argument. The storage kind
+ *   is read once, when the key is minted: a value that changed afterwards would
+ *   be asking to move a key that has already been recorded with a run.
+ * @returns The key to record runs under and to look them up by — the same one
+ *   for the life of the component, and for the next load in the same tab (or the
+ *   same browser, under `"local"`).
+ */
+export declare function useRunKey(options?: {
+    /**
+     * Which store keeps the key between loads.
+     *
+     * `"session"` (the default) dies with the tab; `"local"` survives the
+     * browser closing, which is what a run that sleeps for days needs. See "The
+     * storage is the caller's decision".
+     */
+    storage?: "session" | "local";
+}): string;

package/dist/use-workflow-form.d.ts

@@ -231,6 +231,29 @@ export type UseWorkflowSubmitOptions = {
     api?: WorkflowApi;
     /** Correlation key recorded with the run, for finding it again without the id. */
     key?: string;
+    /**
+     * On mount, adopt the newest run this `key` already has.
+     *
+     * **This is what makes a reload survivable.** The run id is this hook's own
+     * state, so a refresh loses it while the run carries on — and a page that
+     * cannot name a run cannot show it, cancel it or wake it. With a `key` and
+     * this flag the hook asks `find(workflow, key)` once as it mounts and follows
+     * whatever comes back, so the answer, the progress and the controls are all
+     * there again.
+     *
+     * Inert without a `key`, because the key IS the lookup. Opt-in because a
+     * `key` on its own means only "record this with the run", which is what a
+     * page passing an account id may well want; adopting a run is a decision
+     * about the page.
+     *
+     * The key has to be one the next load can produce, and choosing it is the
+     * caller's: it is a lookup CAPABILITY (there is no per-user filtering behind
+     * `find`), it must fit the route's 256-character bound, and anything derived
+     * from a person's own input both collides and carries what they typed.
+     * `useRunKey()` is that key, and its module argues every alternative; a page
+     * with accounts passes the account's own id instead.
+     */
+    recover?: boolean;
     /**
      * Hold the `POST` open until the run settles, up to this many ms — the
      * synchronous mode. Omitted (the default) returns as soon as the run exists.

package/dist/{use-workflow-progress-C4KgVldr.js → use-workflow-progress-Cu0SxMyg.js}

@@ -316,6 +316,15 @@ function pollUntilTerminal(getClient, runId, intervalMs, onRun, onError, onStopp
 * not: it can complete while the tab is closed, on a different sandbox, hours
 * later. There is no session to reconnect — the id is the whole state.
 *
+* Which is also the limit of what this hook can do on its own. An id is state a
+* RELOAD destroys, so a page holding nothing else comes back unable to name a
+* run that is still going. The durable handle is `StartOptions.key`, read back
+* with `find(workflow, key)`, and the hook that owns the id is where that
+* belongs: `useWorkflowSubmit({ key, recover: true })` adopts the key's newest
+* run as it mounts and passes the id here. See `_recover-run.ts` — the reason
+* recovery is NOT in this hook is `reset()`, which leaves the owner holding no
+* id on purpose, and a watcher that re-resolved one from a key would undo it.
+*
 * The stream (`GET /runs/:id/events`) is tried first and the poll is its
 * fallback, so an agent deployed before that route existed still works. Watching
 * STOPS on a terminal status, so a finished run costs nothing; passing
@@ -448,9 +457,67 @@ function useWorkflowRun(runId, opts = {}) {
 * log rather than a socket — but it is a poll of a CHEAP shape: each read asks
 * only for chunks past the last index it saw, so a quiet run costs an empty
 * answer rather than the whole log again.
+*
+* ## A FAILED read is not an absent route, whether or not it carried a status
+*
+* Because the loop stops for good once it decides the route is absent, that
+* decision is the one place a single bad request can cost a live run its entire
+* narration — and it did. Every non-2xx used to read as "this agent serves no
+* progress route", so one transient answer hid the log permanently while the run
+* carried on and the status line went on saying `running`. See
+* {@link isTransientRead} for the split and `readOnce` for what each arm costs.
+*/
+/**
+* How often a live run's progress is re-read once a bounded read has ended.
+*
+* **Five seconds, up from one, because narration is the cheapest thing on the
+* page and it was the most expensive thing on the wire.**
+*
+* On the platform every one of these reads BROKERS (see `useWorkflowRun`'s note
+* on the same hazard), and a page routinely mounts TWO of these hooks against one
+* run — `transcription-workflow` renders `<WorkflowProgress>` for the run's own
+* narration and `<LiveTranscript>` for the segments as they land. At one second
+* that is 2 requests/second from a single tab, which is exactly the platform's
+* whole per-IP surface budget (`WORKFLOW_IP_RATE_LIMIT`, 600 per 5 minutes) — so
+* one tab watching one run, with a history entry expanded, answers
+* `429 Too many workflow requests` partway through its own run.
+*
+* It is also contending for the link with the UPLOAD, which on this page is the
+* thing the reader is actually waiting for: a workflow app's whole wall clock is
+* bytes going out, and progress polling spends the same uplink to describe it.
+*
+* What five costs is that a line appears up to five seconds after the run wrote
+* it. That is the right trade for a log a person SKIMS while waiting minutes —
+* and it is not the run's completion, which arrives on `useWorkflowRun`'s event
+* stream (see {@link DEFAULT_WORKFLOW_POLL_MS}, deliberately left at two seconds
+* because it answers "is it done", not "what is it doing").
+*
+* A page that really wants a live feed passes `intervalMs` and owns the
+* consequence. That option is the authoring surface for this choice, which is why
+* this constant is `/internal` rather than public.
 */
-/** How often a live run's progress is re-read once a bounded read has ended. */
-const DEFAULT_PROGRESS_POLL_MS = 1e3;
+const DEFAULT_PROGRESS_POLL_MS = 5e3;
+/**
+* Whether a non-2xx says "come back" rather than "there is nothing here".
+*
+* The 408/429/5xx split, and it is a THIRD copy of that rule stated
+* deliberately: the SDK's own `isTransientStatus` is on
+* `@alexkroman1/aai/step` and `RETRYABLE_STATUS` is `sdk/_upload-retry.ts`'s
+* internal, so neither is reachable from a browser bundle — this package may
+* not import the step surface, and an `_`-prefixed module may not be imported
+* cross-package at all. Hoisting one of them onto `/utils` (where this guide's
+* own prose already claims `isTransientStatus` lives) is the fix that would
+* delete this; it is a published-surface change and therefore not this one.
+*
+* Everything else is treated as a stable answer, which keeps a permanent
+* refusal — a 401 against an agent whose `AAI_WORKFLOW_API_TOKEN` this page has
+* no token for — from brokering a request every interval for as long as the tab
+* is open. A 404 is the specific case the route documents: an agent deployed
+* before progress streams existed, or one serving no workflow API at all.
+*/
+function isTransientRead(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
 /**
 * Drain one bounded read's frames, reporting how it ended and everything it
 * carried.
@@ -487,6 +554,15 @@ async function consumeFrames(body, signal) {
 * poll cheap: a quiet run answers with a bare `done` rather than the whole log
 * again.
 *
+* `next` is a COUNT of chunks consumed, and `startIndex` is an INCLUSIVE floor,
+* so the two are the same number and no adjustment sits between them. That
+* identity is the whole correctness argument here, and it is why the store's
+* floor is inclusive rather than exclusive — read exclusively, this loop lost the
+* chunk sitting AT its cursor on every re-open, so a run writing one line per
+* poll delivered every other line.
+* `packages/aai-runtime/workflow-stream-cursor.test.ts` states it as a property
+* over generated polling schedules; this module's own spec pins the URLs.
+*
 * ## A negative `startIndex` is resolved on the FIRST read, not carried
 *
 * "The last N lines" names no position a later read can resume from — the tail
@@ -518,6 +594,7 @@ function readProgressUntilComplete(getClient, runId, options, intervalMs, onChun
 			}),
 			signal
 		});
+		if (!res.ok && isTransientRead(res.status)) return "partial";
 		if (!(res.ok && res.body)) return "unsupported";
 		const { ending, chunks } = await consumeFrames(res.body, signal);
 		next += chunks.length;

package/dist/use-workflow-progress.d.ts

@@ -40,6 +40,15 @@
  * log rather than a socket — but it is a poll of a CHEAP shape: each read asks
  * only for chunks past the last index it saw, so a quiet run costs an empty
  * answer rather than the whole log again.
+ *
+ * ## A FAILED read is not an absent route, whether or not it carried a status
+ *
+ * Because the loop stops for good once it decides the route is absent, that
+ * decision is the one place a single bad request can cost a live run its entire
+ * narration — and it did. Every non-2xx used to read as "this agent serves no
+ * progress route", so one transient answer hid the log permanently while the run
+ * carried on and the status line went on saying `running`. See
+ * {@link isTransientRead} for the split and `readOnce` for what each arm costs.
  */
 import type { WorkflowApi } from "./workflow-client.ts";
 /** The slice of the client this needs: one method. */
@@ -60,8 +69,36 @@ export type UseWorkflowProgressResult<T = string> = {
      */
     supported: boolean;
 };
-/** How often a live run's progress is re-read once a bounded read has ended. */
-export declare const DEFAULT_PROGRESS_POLL_MS = 1000;
+/**
+ * How often a live run's progress is re-read once a bounded read has ended.
+ *
+ * **Five seconds, up from one, because narration is the cheapest thing on the
+ * page and it was the most expensive thing on the wire.**
+ *
+ * On the platform every one of these reads BROKERS (see `useWorkflowRun`'s note
+ * on the same hazard), and a page routinely mounts TWO of these hooks against one
+ * run — `transcription-workflow` renders `<WorkflowProgress>` for the run's own
+ * narration and `<LiveTranscript>` for the segments as they land. At one second
+ * that is 2 requests/second from a single tab, which is exactly the platform's
+ * whole per-IP surface budget (`WORKFLOW_IP_RATE_LIMIT`, 600 per 5 minutes) — so
+ * one tab watching one run, with a history entry expanded, answers
+ * `429 Too many workflow requests` partway through its own run.
+ *
+ * It is also contending for the link with the UPLOAD, which on this page is the
+ * thing the reader is actually waiting for: a workflow app's whole wall clock is
+ * bytes going out, and progress polling spends the same uplink to describe it.
+ *
+ * What five costs is that a line appears up to five seconds after the run wrote
+ * it. That is the right trade for a log a person SKIMS while waiting minutes —
+ * and it is not the run's completion, which arrives on `useWorkflowRun`'s event
+ * stream (see {@link DEFAULT_WORKFLOW_POLL_MS}, deliberately left at two seconds
+ * because it answers "is it done", not "what is it doing").
+ *
+ * A page that really wants a live feed passes `intervalMs` and owns the
+ * consequence. That option is the authoring surface for this choice, which is why
+ * this constant is `/internal` rather than public.
+ */
+export declare const DEFAULT_PROGRESS_POLL_MS = 5000;
 /**
  * Follow one run's progress stream.
  *

package/dist/use-workflow-run.d.ts

@@ -38,6 +38,15 @@ export type UseWorkflowRunResult<R = unknown> = {
  * not: it can complete while the tab is closed, on a different sandbox, hours
  * later. There is no session to reconnect — the id is the whole state.
  *
+ * Which is also the limit of what this hook can do on its own. An id is state a
+ * RELOAD destroys, so a page holding nothing else comes back unable to name a
+ * run that is still going. The durable handle is `StartOptions.key`, read back
+ * with `find(workflow, key)`, and the hook that owns the id is where that
+ * belongs: `useWorkflowSubmit({ key, recover: true })` adopts the key's newest
+ * run as it mounts and passes the id here. See `_recover-run.ts` — the reason
+ * recovery is NOT in this hook is `reset()`, which leaves the owner holding no
+ * id on purpose, and a watcher that re-resolved one from a key would undo it.
+ *
  * The stream (`GET /runs/:id/events`) is tried first and the poll is its
  * fallback, so an agent deployed before that route existed still works. Watching
  * STOPS on a terminal status, so a finished run costs nothing; passing

package/dist/use-workflow-stream.d.ts

@@ -86,13 +86,22 @@ import type { SubmitInputOf } from "./workflow-def-types.ts";
  * mode: it holds the `POST` open until the run settles, and here the run is
  * started before its bytes are, so there is nothing left to hold it for.
  *
+ * Without `recover` either, and REFUSED rather than ignored: an option a hook
+ * accepts and does nothing with is the silent-no-op failure this repo keeps
+ * paying for. Adopting an earlier run by key would hand this hook a run whose
+ * input names an upload id it did not mint and is not filling — so the run
+ * would sit waiting for bytes nobody is sending until its own abandonment
+ * bound. That is the same reason `_upload-recall.ts` deliberately does not
+ * recall for this hook, one layer up: here the id is part of a run's INPUT.
+ * `key` itself still works, and still makes the run findable.
+ *
  * `parallel` COMPOSES with what this hook is for rather than competing with it.
  * The run still starts before the bytes, and the store still publishes how far
  * the file is readable — that number is the CONTIGUOUS prefix, so a run reading
  * ahead of the uplink sees the same growing file whether one connection or four
  * are filling it. What changes is only how fast it grows.
  */
-export type UseWorkflowStreamOptions = Omit<UseWorkflowSubmitOptions, "wait">;
+export type UseWorkflowStreamOptions = Omit<UseWorkflowSubmitOptions, "wait" | "recover">;
 /**
  * What {@link useWorkflowStream} returns: a {@link WorkflowSubmission}, exactly.
  *