@alexkroman1/aai-ui 6.7.1 → 6.8.0

package/dist/index.js

@@ -14,12 +14,98 @@ import { client, mountRoot, resolveContainer } from "./define-client.js";
 import { useAgentState, useEvent, useToolCallStart, useToolResult } from "./hooks.js";
 import clsx from "clsx";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { createElement, useCallback, useEffect, useId, useRef, useState } from "react";
+import { createContext, createElement, useCallback, useContext, useEffect, useId, useRef, useState } from "react";
 import { errorMessage, isTerminal, isTerminal as isTerminal$1 } from "@alexkroman1/aai";
 import { isRecord, omitUndefined, safeJsonParse as safeJsonParse$1 } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
 import { createParser } from "eventsource-parser";
 import { createEpoch } from "@alexkroman1/aai/internal";
+//#region components/_form-readiness.ts
+/**
+* Whether a form's own fields exist yet.
+*
+* `<Form>` leans entirely on NATIVE validation — it is a real `<form>` with no
+* `noValidate`, so a `required` field is what stops an empty submit, and the
+* module doc next door says so. That has one hole, and it is the whole reason
+* this exists: a field set declared REMOTELY is not in the DOM while its
+* declaration is in flight, so there is nothing for the browser to validate and
+* an empty submit sails through.
+*
+* It is not theoretical. `<WorkflowFields>` renders `null` until the workflow
+* listing lands, so the transcription desk's first click — before the one-request
+* lookup answered — submitted a form holding only its button. The browser was
+* happy, the payload was `{}`, and the run was refused by the agent with
+* `Invalid input for workflow "transcribeStream": recording: Invalid input`: a
+* schema complaint about a field the person had not been shown, naming a workflow
+* they did not choose by name, for a file picker that appeared a moment later.
+*
+* ## Readiness is DECLARED by the children, because only they know
+*
+* `Form` cannot ask. It renders `{children}` and reads the DOM on submit, and a
+* pending fetch leaves no trace in the DOM at all — which is exactly the
+* difference from `data-aai-read`, the other thing a child tells the form: that
+* one describes an element that EXISTS. So this is a context rather than an
+* attribute, and it carries the one fact a DOM read cannot recover.
+*
+* A form with no such children is ready by definition — `useFormFieldsPending`
+* outside a provider reports nothing pending, so every hand-written form is
+* unaffected and `Form` keeps working outside this package.
+*/
+/**
+* Set by `Form`, read by any field set that fetches its own declaration.
+*
+* `undefined` means no `Form` above, which is legal: the fields render, they are
+* simply not gating anything.
+*/
+const FormReadinessContext = createContext(void 0);
+const FormReadinessProvider = FormReadinessContext.Provider;
+/**
+* Track which children are still waiting for their fields.
+*
+* A SET keyed by the child's own `useId`, not a counter: a child that re-renders
+* while pending must not increment twice, and one that unmounts mid-flight must
+* not leave the form disabled forever. Both are the ordinary lifecycle here — a
+* page that switches workflows swaps one `<WorkflowFields>` for another.
+*/
+function useFormReadiness() {
+	const [waiting, setWaiting] = useState(() => /* @__PURE__ */ new Set());
+	const declare = useCallback((key, pending) => {
+		setWaiting((held) => {
+			if (pending === held.has(key)) return held;
+			const next = new Set(held);
+			if (pending) next.add(key);
+			else next.delete(key);
+			return next;
+		});
+	}, []);
+	return {
+		pending: waiting.size > 0,
+		declare
+	};
+}
+/**
+* Declare from a child that its fields are, or are no longer, still loading.
+*
+* Reports through an EFFECT rather than during render, because this writes to a
+* parent's state — doing it in the render body is the "cannot update a component
+* while rendering a different component" warning, and under StrictMode it is a
+* double report the parent has to be idempotent about anyway. The cleanup
+* releases the claim, so an unmounted field set never holds the form shut.
+*/
+function useDeclareFieldsPending(pending) {
+	const declare = useContext(FormReadinessContext);
+	const key = useId();
+	useEffect(() => {
+		if (!declare) return;
+		declare(key, pending);
+		return () => declare(key, false);
+	}, [
+		declare,
+		key,
+		pending
+	]);
+}
+//#endregion
 //#region components/_form-values.ts
 /**
 * Read one `<form>`'s named controls into a plain object.
@@ -172,10 +258,11 @@ function dataUrl(file) {
 function Form({ onSubmit, error, children, className, ...rest }) {
 	const theme = useTheme();
 	const [busy, setBusy] = useState(false);
+	const { pending: fieldsPending, declare } = useFormReadiness();
 	return /* @__PURE__ */ jsxs("form", {
 		onSubmit: useCallback((event) => {
 			event.preventDefault();
-			if (busy) return;
+			if (busy || fieldsPending) return;
 			const form = event.currentTarget;
 			setBusy(true);
 			(async () => {
@@ -185,13 +272,20 @@ function Form({ onSubmit, error, children, className, ...rest }) {
 					setBusy(false);
 				}
 			})();
-		}, [busy, onSubmit]),
+		}, [
+			busy,
+			fieldsPending,
+			onSubmit
+		]),
 		className: clsx("flex flex-col gap-5 font-aai", className),
 		...rest,
 		children: [/* @__PURE__ */ jsx("fieldset", {
-			disabled: busy,
+			disabled: busy || fieldsPending,
 			className: "contents",
-			children
+			children: /* @__PURE__ */ jsx(FormReadinessProvider, {
+				value: declare,
+				children
+			})
 		}), error !== void 0 && error !== "" && /* @__PURE__ */ jsx("p", {
 			role: "alert",
 			className: "text-sm",
@@ -496,6 +590,14 @@ function formatBytes(bytes) {
 * - **The file is NAMED, and counted when there is more than one.** Files are
 *   sent one after another, so a single bar otherwise appears to restart from
 *   zero partway through with nothing to say why.
+* - **A paused upload SAYS SO, rather than being a bar that stopped.** Those look
+*   identical, which is the whole reason `UploadStatus.paused` exists, and the
+*   fill stops animating so the difference is visible without reading.
+*
+* The pause control appears only when a handler for it is passed. That is not
+* politeness about props: a button whose press does nothing is worse than no
+* button, and a page holding an `upload` it did not produce (a saved status, a
+* parent's state) has nothing to pause.
 *
 * @example
 * ```tsx
@@ -515,16 +617,20 @@ function formatBytes(bytes) {
 *
 * @param upload - What `useWorkflowSubmit` reports. `undefined` renders nothing,
 *   so a page may pass its state straight through.
+* @param onPause - The hook's `pauseUpload`. Pass it together with `onResume` to
+*   get the control; pass neither for a bar that only reports.
+* @param onResume - The hook's `resumeUpload`.
 * @param className - Replaces the default classes rather than extending them,
 *   so a custom chrome is not fighting a default it did not ask for.
 *
 * @public
 */
-function UploadProgressBar({ upload, className }) {
+function UploadProgressBar({ upload, onPause, onResume, className }) {
 	const theme = useTheme();
 	const labelId = useId();
 	if (!upload) return null;
-	const { name, index, count, loaded, total, fraction } = upload;
+	const { name, index, count, loaded, total, fraction, paused } = upload;
+	const control = onPause && onResume ? paused ? onResume : onPause : void 0;
 	const percent = fraction === void 0 ? void 0 : Math.round(fraction * 100);
 	const faint = inkTint(theme.text, theme.surface, 65);
 	return /* @__PURE__ */ jsxs("div", {
@@ -535,11 +641,20 @@ function UploadProgressBar({ upload, className }) {
 				id: labelId,
 				className: "truncate",
 				style: { color: faint },
-				children: count > 1 ? `Uploading ${name} (${index} of ${count})` : `Uploading ${name}`
-			}), /* @__PURE__ */ jsx("span", {
-				className: "shrink-0 tabular-nums",
-				style: { color: faint },
-				children: total === void 0 ? formatBytes(loaded) : `${formatBytes(loaded)} of ${formatBytes(total)}`
+				children: `${paused ? "Paused" : "Uploading"} ${name}${count > 1 ? ` (${index} of ${count})` : ""}`
+			}), /* @__PURE__ */ jsxs("div", {
+				className: "flex shrink-0 items-baseline gap-3",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "tabular-nums",
+					style: { color: faint },
+					children: total === void 0 ? formatBytes(loaded) : `${formatBytes(loaded)} of ${formatBytes(total)}`
+				}), control && /* @__PURE__ */ jsx(Button, {
+					type: "button",
+					variant: "ghost",
+					className: "h-6 px-2 text-[0.625rem]",
+					onClick: control,
+					children: paused ? "Resume" : "Pause"
+				})]
 			})]
 		}), /* @__PURE__ */ jsx("div", {
 			role: "progressbar",
@@ -550,7 +665,7 @@ function UploadProgressBar({ upload, className }) {
 			className: "h-1.5 w-full overflow-hidden rounded-full",
 			style: { backgroundColor: inkTint(theme.text, theme.surface, TRACK_TINT_PCT) },
 			children: /* @__PURE__ */ jsx("div", {
-				className: clsx("h-full rounded-full transition-[width] duration-200 ease-out", percent === void 0 && "animate-pulse"),
+				className: clsx("h-full rounded-full transition-[width] duration-200 ease-out", percent === void 0 && !paused && "animate-pulse"),
 				style: {
 					backgroundColor: theme.primary,
 					width: percent === void 0 ? "100%" : `${percent}%`
@@ -560,6 +675,243 @@ function UploadProgressBar({ upload, className }) {
 	});
 }
 //#endregion
+//#region _upload-session.ts
+/** Whether this rejection is an abort, in either of the two shapes runtimes throw. */
+function isAbortError(err) {
+	return err instanceof Error && err.name === "AbortError";
+}
+/** A fresh upload id: a capability, so it is random rather than derived. */
+function randomUploadId() {
+	return crypto.randomUUID().replaceAll("-", "");
+}
+/**
+* Send one file, waiting out however many pauses the person takes.
+*
+* The loop from the module doc, written once: both hooks need exactly this and a
+* second copy of it is a second place for the abort/pause distinction to be got
+* wrong. `send` is handed whether this attempt must CLAIM the id as its own —
+* false the first time, since a fresh id has nothing to resume and saying
+* otherwise waives the refusal that makes a caller-chosen id safe.
+*
+* Throws whatever `send` threw, except an abort the gate caused. A cancelled gate
+* throws too: the caller distinguishes it by reading `gate.cancelled`, which is
+* how an abandoned submission unwinds without being reported as a failure.
+*/
+async function sendThroughGate(gate, send) {
+	let tried = false;
+	for (;;) {
+		await gate.settle();
+		if (gate.cancelled) throw new Error("Upload cancelled.");
+		const resume = tried;
+		tried = true;
+		try {
+			await send(resume);
+			return;
+		} catch (err) {
+			if (gate.cancelled || !isAbortError(err)) throw err;
+		}
+	}
+}
+/**
+* A gate, open.
+*
+* One per upload rather than one per hook: the id and the windows already stored
+* belong to a file, so a gate that outlived its file would resume something else.
+*/
+function createUploadGate() {
+	let controller = new AbortController();
+	let paused = false;
+	let cancelled = false;
+	let open;
+	let closed;
+	return {
+		get paused() {
+			return paused;
+		},
+		get cancelled() {
+			return cancelled;
+		},
+		get signal() {
+			return controller.signal;
+		},
+		pause() {
+			if (paused || cancelled) return;
+			paused = true;
+			const gate = Promise.withResolvers();
+			closed = gate.promise;
+			open = gate.resolve;
+			controller.abort();
+		},
+		resume() {
+			if (!paused || cancelled) return;
+			paused = false;
+			controller = new AbortController();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		cancel() {
+			if (cancelled) return;
+			cancelled = true;
+			paused = false;
+			controller.abort();
+			open?.();
+			open = void 0;
+			closed = void 0;
+		},
+		async settle() {
+			if (closed) await closed;
+		}
+	};
+}
+//#endregion
+//#region _workflow-files.ts
+/**
+* Which of a submitted form's values are FILES.
+*
+* Its own module because both submit hooks need the identical answer and then do
+* two different things with it — `useWorkflowSubmit` stores each file and passes
+* its id, `useWorkflowStream` cuts it into parts and passes the group they share.
+* A second copy of this predicate would be a form field that one hook treats as a
+* file and the other does not, which is invisible until the run reads the wrong
+* kind of string.
+*/
+/**
+* The files a submitted field carries, if that is what it carries.
+*
+* An array counts only when it is files ALL the way through — a mixed array is
+* some other field's value that happens to contain one, and turning half of it
+* into ids would corrupt it silently.
+*/
+function filesOf(value) {
+	if (value instanceof File) return [value];
+	if (!Array.isArray(value)) return [];
+	const files = value.filter((one) => one instanceof File);
+	return files.length > 0 && files.length === value.length ? files : [];
+}
+/**
+* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
+* being sent.
+*
+* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
+* own enumerable properties. So a File left in a payload does not fail to send: it
+* arrives as an empty object, and the workflow rejects it against whatever its own
+* schema says the property should be. Measured in production as
+* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
+* about a type, on a form where the user had picked a perfectly good file.
+*
+* Exported beside {@link filesOf} because it is the same question asked at the
+* other end: that one decides which fields to UPLOAD, this one checks that none
+* were missed. Both hooks are the callers.
+*/
+function fileFields(input) {
+	if (!isRecord(input)) return [];
+	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
+}
+//#endregion
+//#region _upload-files.ts
+/**
+* Turning a form's `File`s into stored upload ids, pauses and all.
+*
+* Split out of `use-workflow-form.ts` for the 500-line cap, and the seam is a
+* real one: that module is the two HOOKS and the state between them, where this
+* is the walk over a submitted input — which is the only part of it that knows
+* what a `File` is, holds a loop, and survives being re-entered.
+*
+* `_`-internal. `useWorkflowSubmit` is the only caller; `useWorkflowStream` sends
+* one file rather than walking an input and shares only the gate underneath both
+* (`_upload-session.ts`).
+*/
+/** A fresh session for one submission. */
+function createUploadSession() {
+	return {
+		ids: /* @__PURE__ */ new Map(),
+		stored: /* @__PURE__ */ new Map(),
+		tried: /* @__PURE__ */ new Set(),
+		gate: createUploadGate()
+	};
+}
+/**
+* Replace every `File` in a submitted form with the id of a stored upload,
+* reporting how far each one has got.
+*
+* Sequential rather than `Promise.all`: these are large bodies, and a form with
+* two 200 MB recordings should send them one after another rather than compete
+* for the same connection. That is also what makes a single bar honest — one
+* file is in flight at a time, and `index`/`count` say which.
+*
+* Anything that is not a `File` (or an array of them) passes through untouched,
+* so this is invisible to every form that has none — including one whose values
+* are not an object at all, which `submit` accepts.
+*
+* ## `uploadStream`, not `upload`, and the id is the reason
+*
+* The difference between the two calls is only who mints the id — and that is
+* exactly what decides whether an interrupted upload can be picked up again. An
+* `upload` mints its own at the END and hands it back, so a caller whose upload
+* died has nothing to name what was stored and no choice but to send the file
+* again. A `uploadStream` is told the id up front, so the windows already in the
+* store are addressable, which is what both a pause and a server restart need.
+*
+* Nothing else about the submission changes: the run is still started after the
+* last byte lands, so the incomplete record a streamed upload leaves along the
+* way is one nobody reads.
+*/
+async function uploadFiles(api, input, report, parallel, session) {
+	if (!isRecord(input)) return input;
+	const entries = Object.entries(input);
+	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
+	let index = 0;
+	const store = async (file) => {
+		index += 1;
+		const done = session.stored.get(file);
+		if (done !== void 0) return done;
+		let id = session.ids.get(file);
+		if (id === void 0) {
+			id = randomUploadId();
+			session.ids.set(file, id);
+		}
+		const position = {
+			name: file.name,
+			index,
+			count
+		};
+		await sendThroughGate(session.gate, async (resume) => {
+			await api.uploadStream(id, file, {
+				name: file.name,
+				signal: session.gate.signal,
+				onProgress: (progress) => report({
+					...position,
+					...progress,
+					paused: session.gate.paused
+				}),
+				...omitUndefined({
+					parallel,
+					resume: resume ? true : void 0
+				})
+			});
+		});
+		session.stored.set(file, id);
+		return id;
+	};
+	const out = {};
+	for (const [name, value] of entries) {
+		if (value instanceof File) {
+			out[name] = await store(value);
+			continue;
+		}
+		const chosen = filesOf(value);
+		if (chosen.length === 0) {
+			out[name] = value;
+			continue;
+		}
+		const ids = [];
+		for (const file of chosen) ids.push(await store(file));
+		out[name] = ids;
+	}
+	return out;
+}
+//#endregion
 //#region workflow-client.ts
 /**
 * Create a workflow API client aimed at the agent serving this page.
@@ -626,50 +978,6 @@ function useWorkflowApiRef(api) {
 	}, []);
 }
 //#endregion
-//#region _workflow-files.ts
-/**
-* Which of a submitted form's values are FILES.
-*
-* Its own module because both submit hooks need the identical answer and then do
-* two different things with it — `useWorkflowSubmit` stores each file and passes
-* its id, `useWorkflowStream` cuts it into parts and passes the group they share.
-* A second copy of this predicate would be a form field that one hook treats as a
-* file and the other does not, which is invisible until the run reads the wrong
-* kind of string.
-*/
-/**
-* The files a submitted field carries, if that is what it carries.
-*
-* An array counts only when it is files ALL the way through — a mixed array is
-* some other field's value that happens to contain one, and turning half of it
-* into ids would corrupt it silently.
-*/
-function filesOf(value) {
-	if (value instanceof File) return [value];
-	if (!Array.isArray(value)) return [];
-	const files = value.filter((one) => one instanceof File);
-	return files.length > 0 && files.length === value.length ? files : [];
-}
-/**
-* The input properties still carrying a `File` — i.e. the ones that CANNOT survive
-* being sent.
-*
-* A run input is JSON, and `JSON.stringify(new File(…))` is `{}` — no `toJSON`, no
-* own enumerable properties. So a File left in a payload does not fail to send: it
-* arrives as an empty object, and the workflow rejects it against whatever its own
-* schema says the property should be. Measured in production as
-* `Invalid input for workflow "transcribe": recording: Invalid input` — a message
-* about a type, on a form where the user had picked a perfectly good file.
-*
-* Exported beside {@link filesOf} because it is the same question asked at the
-* other end: that one decides which fields to UPLOAD, this one checks that none
-* were missed. Both hooks are the callers.
-*/
-function fileFields(input) {
-	if (!isRecord(input)) return [];
-	return Object.entries(input).filter(([, value]) => filesOf(value).length > 0).map(([key]) => key);
-}
-//#endregion
 //#region _repeat-until.ts
 /**
 * A bounded read, re-armed from the SETTLED read — the loop both workflow
@@ -1076,56 +1384,6 @@ function useWorkflows(opts = {}) {
 	return state;
 }
 /**
-* Replace every `File` in a submitted form with the id of a stored upload,
-* reporting how far each one has got.
-*
-* Sequential rather than `Promise.all`: these are large bodies, and a form with
-* two 200 MB recordings should send them one after another rather than compete
-* for the same connection. That is also what makes a single bar honest — one
-* file is in flight at a time, and `index`/`count` say which.
-*
-* Anything that is not a `File` (or an array of them) passes through untouched,
-* so this is invisible to every form that has none — including one whose values
-* are not an object at all, which `submit` accepts.
-*/
-async function uploadFiles(api, input, report, parallel) {
-	if (!isRecord(input)) return input;
-	const entries = Object.entries(input);
-	const count = entries.reduce((total, [, value]) => total + filesOf(value).length, 0);
-	let index = 0;
-	const store = async (file) => {
-		index += 1;
-		const position = {
-			name: file.name,
-			index,
-			count
-		};
-		return (await api.upload(file, {
-			onProgress: (progress) => report({
-				...position,
-				...progress
-			}),
-			...omitUndefined({ parallel })
-		})).id;
-	};
-	const out = {};
-	for (const [name, value] of entries) {
-		if (value instanceof File) {
-			out[name] = await store(value);
-			continue;
-		}
-		const chosen = filesOf(value);
-		if (chosen.length === 0) {
-			out[name] = value;
-			continue;
-		}
-		const ids = [];
-		for (const file of chosen) ids.push(await store(file));
-		out[name] = ids;
-	}
-	return out;
-}
-/**
 * Start a workflow from a form, and follow the run it creates.
 *
 * @typeParam R - The workflow's output type, which is what makes
@@ -1156,6 +1414,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
 	const [upload, setUpload] = useState(void 0);
+	const session = useRef(void 0);
 	const getClient = useWorkflowApiRef(api);
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
@@ -1167,18 +1426,24 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			setStarting(true);
 			setStartError(void 0);
 			setRunId(void 0);
+			session.current?.gate.cancel();
+			const current = createUploadSession();
+			session.current = current;
 			try {
 				const options = omitUndefined({ key });
-				const started = await uploadFiles(client, input, setUpload, parallel);
+				const started = await uploadFiles(client, input, setUpload, parallel, current);
 				setRunId(wait === void 0 ? await client.start(workflow, started, options) : (await client.startAndWait(workflow, started, {
 					...options,
 					wait
 				})).runId);
 			} catch (err) {
-				setStartError(errorMessage(err));
+				if (!current.gate.cancelled) setStartError(errorMessage(err));
 			} finally {
-				setStarting(false);
-				setUpload(void 0);
+				if (session.current === current) {
+					session.current = void 0;
+					setStarting(false);
+					setUpload(void 0);
+				}
 			}
 		}, [
 			workflow,
@@ -1188,10 +1453,26 @@ function useWorkflowSubmit(workflow, opts = {}) {
 			getClient
 		]),
 		reset: useCallback(() => {
+			session.current?.gate.cancel();
+			session.current = void 0;
 			setRunId(void 0);
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		pauseUpload: useCallback(() => {
+			session.current?.gate.pause();
+			setUpload((current) => current ? {
+				...current,
+				paused: true
+			} : current);
+		}, []),
+		resumeUpload: useCallback(() => {
+			session.current?.gate.resume();
+			setUpload((current) => current ? {
+				...current,
+				paused: false
+			} : current);
+		}, []),
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -1234,8 +1515,9 @@ function useWorkflowSubmit(workflow, opts = {}) {
 * @public
 */
 function WorkflowFields({ workflow }) {
-	const { workflows } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
+	const { workflows, loading } = useWorkflows(typeof workflow === "string" ? {} : { skip: true });
 	const summary = typeof workflow === "string" ? workflows.find((entry) => entry.name === workflow) : workflow;
+	useDeclareFieldsPending(loading);
 	const schema = asObjectSchema(summary?.inputSchema);
 	if (!schema?.properties) return null;
 	const required = new Set(schema.required ?? []);
@@ -1849,18 +2131,33 @@ function useWorkflowRuns(workflow, opts = {}) {
 * - **Reporting the bytes.** The same `UploadStatus` `useWorkflowSubmit` reports,
 *   so `<UploadProgressBar>` renders either without knowing which hook it came from.
 *
-* ## A failed upload is RESUMED once, and only then cancels the run
+* ## A failed upload is RESUMED, and only a spent budget cancels the run
 *
 * An upload that dies stays in the store, incomplete, and `complete` never becomes
 * true — so a run left behind polls until its own abandonment bound and then fails,
 * minutes after the page has already reported the error.
 *
 * That used to be the whole story, and it threw away a run and a file together for
-* what is usually one dropped connection near the end. So a failure gets one more
-* attempt with `resume: true`, which sends only the windows the store does not
-* already have (`UploadInfo.ranges`) — the run is still waiting on the same id, so
-* a resume that succeeds is invisible to it. Cancelling is what happens when THAT
-* fails too, and it is the honest end to a submission that did not happen.
+* what is usually one dropped connection near the end. **The resume lives in the
+* SDK now** (`aai/sdk/_upload-resume.ts`): a round that fails for a reason that
+* looks like an outage is re-entered with `resume: true`, sending only the windows
+* the store does not already have, on a budget sized to outlast a redeploy. The run
+* is still waiting on the same id, so a resume that succeeds is invisible to it.
+*
+* This hook used to hand-roll one such retry and no longer does — one resume with
+* no wait in front of it covers a dropped connection and cannot cover the case that
+* actually strands people, which is the agent restarting underneath the upload.
+* Cancelling the run is what happens when the whole budget is spent, and it is the
+* honest end to a submission that did not happen.
+*
+* ## Pausing is the same mechanism, asked for
+*
+* `pauseUpload()` aborts the bytes in flight and holds the uploader;
+* `resumeUpload()` sends what is missing. The store cannot tell that from an
+* outage, because there is nothing to tell apart — see `_upload-session.ts`. The
+* RUN is untouched either way: it goes on polling the id it was started with, and
+* `stream.ts`'s idle bound (five minutes of no new bytes) is what decides that a
+* pause has become an abandonment.
 */
 /**
 * Start a workflow run and stream a file into it while it works.
@@ -1893,6 +2190,7 @@ function useWorkflowStream(workflow, opts = {}) {
 	const [starting, setStarting] = useState(false);
 	const [startError, setStartError] = useState(void 0);
 	const [upload, setUpload] = useState(void 0);
+	const gateRef = useRef(void 0);
 	const getClient = useWorkflowApiRef(api);
 	const tracked = useWorkflowRun(runId, omitUndefined({
 		api,
@@ -1904,42 +2202,41 @@ function useWorkflowStream(workflow, opts = {}) {
 			setStarting(true);
 			setStartError(void 0);
 			setRunId(void 0);
+			gateRef.current?.cancel();
+			const gate = createUploadGate();
+			gateRef.current = gate;
 			let started;
 			try {
-				const field = await uploadField(client, workflow);
-				const chosen = field === void 0 ? void 0 : fileAt(input, field);
 				const id = randomUploadId();
-				const payload = chosen && field ? {
-					...input,
-					[field]: id
-				} : input;
-				assertSendable(workflow, payload, field);
-				started = await client.start(workflow, payload, omitUndefined({ key }));
+				const begun = await beginRun({
+					client,
+					workflow,
+					input,
+					id,
+					...omitUndefined({ key })
+				});
+				started = begun.runId;
+				const chosen = begun.file;
 				setRunId(started);
 				if (!chosen) return;
-				const send = async (resume) => {
-					await client.uploadStream(id, chosen, {
-						name: chosen.name,
-						onProgress: (progress) => setUpload({
-							...progress,
-							name: chosen.name,
-							index: 1,
-							count: 1
-						}),
-						...omitUndefined({
-							parallel,
-							resume: resume ? true : void 0
-						})
-					});
-				};
-				await send(false).catch(async () => await send(true));
+				await streamFile({
+					client,
+					gate,
+					id,
+					file: chosen,
+					parallel,
+					report: setUpload
+				});
 				await client.wake(started).catch(() => void 0);
 			} catch (err) {
-				setStartError(errorMessage(err));
+				if (!gate.cancelled) setStartError(errorMessage(err));
 				if (started) await client.cancel(started).catch(() => void 0);
 			} finally {
-				setStarting(false);
-				setUpload(void 0);
+				if (gateRef.current === gate) {
+					gateRef.current = void 0;
+					setStarting(false);
+					setUpload(void 0);
+				}
 			}
 		}, [
 			workflow,
@@ -1948,10 +2245,26 @@ function useWorkflowStream(workflow, opts = {}) {
 			getClient
 		]),
 		reset: useCallback(() => {
+			gateRef.current?.cancel();
+			gateRef.current = void 0;
 			setRunId(void 0);
 			setStartError(void 0);
 			setUpload(void 0);
 		}, []),
+		pauseUpload: useCallback(() => {
+			gateRef.current?.pause();
+			setUpload((current) => current ? {
+				...current,
+				paused: true
+			} : current);
+		}, []),
+		resumeUpload: useCallback(() => {
+			gateRef.current?.resume();
+			setUpload((current) => current ? {
+				...current,
+				paused: false
+			} : current);
+		}, []),
 		run: tracked.run,
 		pending: starting || tracked.polling,
 		upload,
@@ -1959,6 +2272,56 @@ function useWorkflowStream(workflow, opts = {}) {
 	};
 }
 /**
+* Read the declaration, substitute the id, and start the run.
+*
+* Everything that has to happen BEFORE a byte moves, which is the inversion this
+* hook exists for. One small `list()` per submit, deliberately: holding the
+* listing in state would make a submit before it landed a race, and the failure
+* mode of that race is a `File` reaching a run input.
+*/
+async function beginRun(opts) {
+	const { client, workflow, input, id } = opts;
+	const field = await uploadField(client, workflow);
+	const chosen = field === void 0 ? void 0 : fileAt(input, field);
+	const payload = chosen && field ? {
+		...input,
+		[field]: id
+	} : input;
+	assertSendable(workflow, payload, field);
+	return {
+		runId: await client.start(workflow, payload, omitUndefined({ key: opts.key })),
+		file: chosen
+	};
+}
+/**
+* Send the file, waiting out however many pauses the person takes.
+*
+* Its own function rather than a block inside `submit` because `submit` is
+* already carrying the ORDER this hook exists for — read the declaration, mint
+* the id, start the run, then the bytes, then the wake — and the sending is the
+* one step of that list with a loop in it.
+*/
+async function streamFile(opts) {
+	const { client, gate, id, file, parallel, report } = opts;
+	await sendThroughGate(gate, async (resume) => {
+		await client.uploadStream(id, file, {
+			name: file.name,
+			signal: gate.signal,
+			onProgress: (progress) => report({
+				...progress,
+				name: file.name,
+				index: 1,
+				count: 1,
+				paused: gate.paused
+			}),
+			...omitUndefined({
+				parallel,
+				resume: resume ? true : void 0
+			})
+		});
+	});
+}
+/**
 * Refuse a payload carrying a `File`, before a run is started over it.
 *
 * A File cannot be SENT: a run input is JSON and `JSON.stringify(new File(…))` is
@@ -1985,10 +2348,6 @@ function assertSendable(workflow, payload, field) {
 	const declares = field === void 0 ? "" : ` (it declares "${field}")`;
 	throw new Error(`Cannot start "${workflow}": ${unsendable.join(", ")} ${carries} the workflow does not declare as an upload${declares}. Add the property to \`workflow({ uploads: [...] })\`, or submit an upload id.`);
 }
-/** A fresh upload id: a capability, so it is random rather than derived. */
-function randomUploadId() {
-	return crypto.randomUUID().replaceAll("-", "");
-}
 /**
 * Which input property this workflow says carries an upload id.
 *