@alexkroman1/aai-ui 6.3.0 → 6.4.0

package/dist/_workflow-files.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare function filesOf(value: unknown): File[];

package/dist/index.d.ts

@@ -30,4 +30,5 @@ export { type UploadStatus, type UseWorkflowSubmitOptions, type UseWorkflowsOpti
 export { DEFAULT_PROGRESS_POLL_MS, type UseWorkflowProgressResult, useWorkflowProgress, } from "./use-workflow-progress.ts";
 export { DEFAULT_WORKFLOW_POLL_MS, MAX_MISSING_READS, type UseWorkflowRunResult, useWorkflowRun, } from "./use-workflow-run.ts";
 export { type UseWorkflowRunsOptions, type UseWorkflowRunsResult, useWorkflowRuns, } from "./use-workflow-runs.ts";
+export { type UseWorkflowStreamOptions, useWorkflowStream, type WorkflowStreamSubmission, } from "./use-workflow-stream.ts";
 export { createWorkflowApi, isTerminal, type WorkflowApi, type WorkflowApiOptions, type WorkflowOutputOf, type WorkflowRun, type WorkflowSummary, } from "./workflow-client.ts";

package/dist/index.js

@@ -625,6 +625,31 @@ 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 : [];
+}
+//#endregion
 //#region _repeat-until.ts
 /**
 * A bounded read, re-armed from the SETTLED read — the loop both workflow
@@ -1031,19 +1056,6 @@ function useWorkflows(opts = {}) {
 	return state;
 }
 /**
-* 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 : [];
-}
-/**
 * Replace every `File` in a submitted form with the id of a stored upload,
 * reporting how far each one has got.
 *
@@ -1761,4 +1773,171 @@ function useWorkflowRuns(workflow, opts = {}) {
 	};
 }
 //#endregion
-export { ApiUrlChip, AutoScroll, Button, ChatView, CheckboxField, Controls, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, Field, FileField, Form, MAX_MISSING_READS, Markdown, MessageList, NumberField, SelectField, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, SubmitButton, TRANSCRIBING_PLACEHOLDER, TextAreaField, TextField, ThemeProvider, ToolCallRow, ToolConfigContext, UiUrlChip, UploadProgressBar, VOICE_CAPTURE_CONSTRAINTS, WorkflowFields, WorkflowProgress, buildAgentUrl, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, loadClientConfig, page, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowSubmit, useWorkflows };
+//#region use-workflow-stream.ts
+/**
+* Starting a run BEFORE its file has finished uploading.
+*
+* `useWorkflowSubmit` (`use-workflow-form.ts`) stores every file and then starts the
+* run, because a `POST /workflows/uploads` cannot answer with an id until the last
+* byte is in — the store writes an ordinary upload's record last, so "incomplete"
+* and "no such upload" are deliberately the same answer. For a long recording that
+* order is most of the wall clock.
+*
+* This hook inverts it, and it takes ONE extra idea to do so: the id is the
+* CLIENT's. It mints one, starts the run on it, and `PUT`s the whole file in a
+* single streaming request; the upload record exists from the first byte with
+* `complete: false` and its `size` grows, so the run reads whatever has arrived.
+*
+* ```text
+*   start run ─┬──────────────────────────────────────────────► (still running)
+*              │
+*   PUT /uploads/<id>  ═══════════════════════════════════►  wake
+*              (one request; the run polls `size` and `complete`)
+* ```
+*
+* ## What it does NOT do, which is the point
+*
+* There is no cutting, no part numbering, no terminator and no per-part request. An
+* earlier version of this hook took a `cut` callback and uploaded N parts into a
+* "group" that a separate call had to seal; it worked, and every piece of it was
+* something the caller had to get right. The whole of that is replaced by the store
+* publishing `size` as bytes land — which `readUpload` already clamped to — so the
+* run does exactly what it does over a finished file and simply waits for windows to
+* become present.
+*
+* It also means the FORMAT knowledge stays where it already was. Deciding where a
+* recording may be divided is the run's business (`planSegments` in the
+* transcription template), and nothing here needs to know it is audio at all.
+*
+* ## Three things it owns
+*
+* - **The id.** Minted here, put in the run input where the workflow's `uploads`
+*   list says, and never seen by the page. It is a capability — anyone holding it
+*   can read the bytes back — so it is a `crypto.randomUUID()` rather than anything
+*   derived from the file, and the store refuses a second `PUT` to it.
+* - **The wake after the upload.** `POST /workflows/runs/:id/wake` ends a pending
+*   `sleep`, and a run waiting on an upload is asleep between polls — so without
+*   this it learns the file is complete up to a poll interval late, every time. On
+*   the transcription template's 5-second interval that is most of the tail it has
+*   left to pay. Best-effort, because a wake that finds nothing sleeping answers 0
+*   and a missed one costs latency rather than correctness.
+* - **Reporting the bytes.** The same `UploadStatus` `useWorkflowSubmit` reports,
+*   so `<UploadProgressBar>` renders either without knowing which hook it came from.
+*
+* ## A failed upload 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. Cancelling is the honest
+* end to a submission that did not happen. The cost is that work already done is
+* thrown away with the run; a caller who wants to resume instead drives
+* `api.uploadStream` and `api.uploadInfo` directly.
+*/
+/**
+* Start a workflow run and stream a file into it while it works.
+*
+* The workflow declares which input property carries the upload
+* (`workflow({ uploads: ["recording"] })`) — the same declaration
+* `useWorkflowSubmit` reads, because what the property carries is an upload id
+* either way. What differs is only WHEN the id becomes valid.
+*
+* @typeParam R - The workflow's output type, which is what makes
+*   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
+*   `WorkflowOutputOf<typeof myWorkflow>`.
+*
+* @example
+* ```tsx no-check
+* const { submit, run, upload, pending, error } = useWorkflowStream("transcribe");
+*
+* <Form onSubmit={(values) => submit(values)} error={error}>
+*   <WorkflowFields workflow="transcribe" />
+*   <UploadProgressBar upload={upload} />
+*   <SubmitButton pending={pending}>Transcribe</SubmitButton>
+* </Form>
+* ```
+*
+* @public
+*/
+function useWorkflowStream(workflow, opts = {}) {
+	const { api, key, intervalMs } = opts;
+	const [runId, setRunId] = useState(void 0);
+	const [starting, setStarting] = useState(false);
+	const [startError, setStartError] = useState(void 0);
+	const [upload, setUpload] = useState(void 0);
+	const getClient = useWorkflowApiRef(api);
+	const tracked = useWorkflowRun(runId, {
+		...api && { api },
+		...omitUndefined({ intervalMs })
+	});
+	return {
+		submit: useCallback(async (input) => {
+			const client = getClient();
+			setStarting(true);
+			setStartError(void 0);
+			setRunId(void 0);
+			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;
+				started = await client.start(workflow, payload, omitUndefined({ key }));
+				setRunId(started);
+				if (!chosen) return;
+				await client.uploadStream(id, chosen, {
+					name: chosen.name,
+					onProgress: (progress) => setUpload({
+						...progress,
+						name: chosen.name,
+						index: 1,
+						count: 1
+					})
+				});
+				await client.wake(started).catch(() => void 0);
+			} catch (err) {
+				setStartError(errorMessage(err));
+				if (started) await client.cancel(started).catch(() => void 0);
+			} finally {
+				setStarting(false);
+				setUpload(void 0);
+			}
+		}, [
+			workflow,
+			key,
+			getClient
+		]),
+		reset: useCallback(() => {
+			setRunId(void 0);
+			setStartError(void 0);
+			setUpload(void 0);
+		}, []),
+		run: tracked.run,
+		pending: starting || tracked.polling,
+		upload,
+		error: startError ?? tracked.error
+	};
+}
+/** 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.
+*
+* `undefined` when the workflow declares none, which is not an error: the caller
+* may be using this hook against a workflow that takes no file at all, and the run
+* then starts with the input untouched.
+*/
+async function uploadField(client, workflow) {
+	return (await client.list()).find((one) => one.name === workflow)?.uploads?.[0];
+}
+/** The `File` at `field`, if that is what the form put there. */
+function fileAt(input, field) {
+	if (!isRecord(input)) return void 0;
+	return filesOf(input[field])[0];
+}
+//#endregion
+export { ApiUrlChip, AutoScroll, Button, ChatView, CheckboxField, Controls, DEFAULT_PROGRESS_POLL_MS, DEFAULT_WORKFLOW_POLL_MS, Field, FileField, Form, MAX_MISSING_READS, Markdown, MessageList, NumberField, SelectField, SessionProvider, SessionUrlChips, SidebarLayout, StartScreen, SubmitButton, TRANSCRIBING_PLACEHOLDER, TextAreaField, TextField, ThemeProvider, ToolCallRow, ToolConfigContext, UiUrlChip, UploadProgressBar, VOICE_CAPTURE_CONSTRAINTS, WorkflowFields, WorkflowProgress, buildAgentUrl, client, createSessionCore, createWorkflowApi, fetchClientConfig, isTerminal, loadClientConfig, page, useAgentState, useEvent, useSession, useSessionSelector, useTheme, useToolCallStart, useToolResult, useUserTranscript, useWorkflowProgress, useWorkflowRun, useWorkflowRuns, useWorkflowStream, useWorkflowSubmit, useWorkflows };

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

@@ -0,0 +1,122 @@
+/**
+ * Starting a run BEFORE its file has finished uploading.
+ *
+ * `useWorkflowSubmit` (`use-workflow-form.ts`) stores every file and then starts the
+ * run, because a `POST /workflows/uploads` cannot answer with an id until the last
+ * byte is in — the store writes an ordinary upload's record last, so "incomplete"
+ * and "no such upload" are deliberately the same answer. For a long recording that
+ * order is most of the wall clock.
+ *
+ * This hook inverts it, and it takes ONE extra idea to do so: the id is the
+ * CLIENT's. It mints one, starts the run on it, and `PUT`s the whole file in a
+ * single streaming request; the upload record exists from the first byte with
+ * `complete: false` and its `size` grows, so the run reads whatever has arrived.
+ *
+ * ```text
+ *   start run ─┬──────────────────────────────────────────────► (still running)
+ *              │
+ *   PUT /uploads/<id>  ═══════════════════════════════════►  wake
+ *              (one request; the run polls `size` and `complete`)
+ * ```
+ *
+ * ## What it does NOT do, which is the point
+ *
+ * There is no cutting, no part numbering, no terminator and no per-part request. An
+ * earlier version of this hook took a `cut` callback and uploaded N parts into a
+ * "group" that a separate call had to seal; it worked, and every piece of it was
+ * something the caller had to get right. The whole of that is replaced by the store
+ * publishing `size` as bytes land — which `readUpload` already clamped to — so the
+ * run does exactly what it does over a finished file and simply waits for windows to
+ * become present.
+ *
+ * It also means the FORMAT knowledge stays where it already was. Deciding where a
+ * recording may be divided is the run's business (`planSegments` in the
+ * transcription template), and nothing here needs to know it is audio at all.
+ *
+ * ## Three things it owns
+ *
+ * - **The id.** Minted here, put in the run input where the workflow's `uploads`
+ *   list says, and never seen by the page. It is a capability — anyone holding it
+ *   can read the bytes back — so it is a `crypto.randomUUID()` rather than anything
+ *   derived from the file, and the store refuses a second `PUT` to it.
+ * - **The wake after the upload.** `POST /workflows/runs/:id/wake` ends a pending
+ *   `sleep`, and a run waiting on an upload is asleep between polls — so without
+ *   this it learns the file is complete up to a poll interval late, every time. On
+ *   the transcription template's 5-second interval that is most of the tail it has
+ *   left to pay. Best-effort, because a wake that finds nothing sleeping answers 0
+ *   and a missed one costs latency rather than correctness.
+ * - **Reporting the bytes.** The same `UploadStatus` `useWorkflowSubmit` reports,
+ *   so `<UploadProgressBar>` renders either without knowing which hook it came from.
+ *
+ * ## A failed upload 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. Cancelling is the honest
+ * end to a submission that did not happen. The cost is that work already done is
+ * thrown away with the run; a caller who wants to resume instead drives
+ * `api.uploadStream` and `api.uploadInfo` directly.
+ */
+import type { UploadStatus } from "./use-workflow-form.ts";
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** Options for {@link useWorkflowStream}. */
+export type UseWorkflowStreamOptions = {
+    /** The client to start runs with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /** Correlation key recorded with the run, for finding it again without the id. */
+    key?: string;
+    /** How often the fallback poll re-reads a live run. */
+    intervalMs?: number;
+};
+/** What {@link useWorkflowStream} returns. */
+export type WorkflowStreamSubmission<R = unknown> = {
+    /**
+     * Start a run and stream this input's file into it.
+     *
+     * Resolves when the upload finishes, NOT when the run does — the run's own
+     * progress arrives through `run`. It resolves rather than rejecting on a failed
+     * upload; the failure is reported through `error`, the way a form expects.
+     */
+    submit: (input: unknown) => Promise<void>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /**
+     * The run, from the moment it EXISTS — which here is before its bytes are in.
+     *
+     * That is the whole difference from `useWorkflowSubmit`, and what lets a page
+     * render `<WorkflowProgress>` beside the upload bar rather than after it.
+     */
+    run: WorkflowRun<R> | undefined;
+    /** True from `submit()` until the run reaches a terminal status. */
+    pending: boolean;
+    /** How far the upload has got, while it is still going. */
+    upload: UploadStatus | undefined;
+    /** The submit's own failure (a rejected input, or an upload that would not store). */
+    error: string | undefined;
+};
+/**
+ * Start a workflow run and stream a file into it while it works.
+ *
+ * The workflow declares which input property carries the upload
+ * (`workflow({ uploads: ["recording"] })`) — the same declaration
+ * `useWorkflowSubmit` reads, because what the property carries is an upload id
+ * either way. What differs is only WHEN the id becomes valid.
+ *
+ * @typeParam R - The workflow's output type, which is what makes
+ *   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
+ *   `WorkflowOutputOf<typeof myWorkflow>`.
+ *
+ * @example
+ * ```tsx no-check
+ * const { submit, run, upload, pending, error } = useWorkflowStream("transcribe");
+ *
+ * <Form onSubmit={(values) => submit(values)} error={error}>
+ *   <WorkflowFields workflow="transcribe" />
+ *   <UploadProgressBar upload={upload} />
+ *   <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ * </Form>
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowStream<R = unknown>(workflow: string, opts?: UseWorkflowStreamOptions): WorkflowStreamSubmission<R>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "type": "module",
   "files": [
     "dist",
@@ -29,7 +29,7 @@
     "remark-gfm": "^4.0.1",
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.6.0",
-    "@alexkroman1/aai": "6.3.0"
+    "@alexkroman1/aai": "6.4.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",