@alexkroman1/aai-ui 8.2.0 → 9.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-Bp1iPrLa.js"></script>
+    <script type="module" crossorigin src="./assets/index-CA2w_SUi.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/define-client.js

@@ -5,7 +5,7 @@ import { n as setPageTitle, t as pageBaseUrl } from "./_utils-B6498_bm.js";
 import { t as ToolConfigContext } from "./tool-config-context-DzAofqi_.js";
 import { SidebarLayout } from "./components/sidebar-layout.js";
 import { StartScreen } from "./components/start-screen.js";
-import { t as createSessionCore } from "./session-core-CMEpwRP1.js";
+import { t as createSessionCore } from "./session-core-0hClhPz-.js";
 import { jsx } from "react/jsx-runtime";
 import { createElement, useEffect, useState } from "react";
 import { flushSync } from "react-dom";

package/dist/index.d.ts

@@ -31,5 +31,6 @@ export { type UseWorkflowProgressResult, useWorkflowProgress, } from "./use-work
 export { 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 WorkflowRunStatus, type WorkflowSummary, } from "./workflow-client.ts";
+export { createWorkflowApi, isTerminal, type WorkflowApi, type WorkflowApiOptions, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRun, type WorkflowRunStatus, type WorkflowSummary, } from "./workflow-client.ts";
+export type { SubmitInputOf } from "./workflow-def-types.ts";
 export { WORKFLOW_STATUS_LABELS } from "./workflow-status-labels.ts";

package/dist/index.js

@@ -11,7 +11,7 @@ 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 { t as createSessionCore } from "./session-core-CMEpwRP1.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";
 import clsx from "clsx";
@@ -690,13 +690,14 @@ const TRACK_TINT_PCT = 12;
 * parent's state) has nothing to pause.
 *
 * @example
-* ```tsx
+* ```tsx no-check
 * import { Form, SubmitButton, UploadProgressBar, useWorkflowSubmit, WorkflowFields } from "@alexkroman1/aai-ui";
+* import type { transcribe } from "./agent.ts";
 *
 * function TranscribeForm() {
-*   const { submit, upload, pending, error } = useWorkflowSubmit("transcribe");
+*   const { submitForm, upload, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
 *   return (
-*     <Form onSubmit={(values) => submit(values)} error={error}>
+*     <Form onSubmit={submitForm} error={error}>
 *       <WorkflowFields workflow="transcribe" />
 *       <UploadProgressBar upload={upload} />
 *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
@@ -1373,21 +1374,30 @@ function useWorkflows(opts = {}) {
 /**
 * Start a workflow from a form, and follow the run it creates.
 *
-* @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>`.
+* @typeParam D - The workflow DEFINITION, which types both halves of the
+*   submission: `submit(input)` takes what the workflow's schema parses to, and
+*   `run.status === "completed"` narrows to a typed `run.output`.
+*
+*   It used to be the OUTPUT type alone, and the asymmetry was the bug: a page
+*   already wrote `WorkflowOutputOf<typeof digest>` to get the output, while
+*   `submit` took `unknown`, so `submit({ ur1: 42 })` compiled and arrived as a
+*   400 in the browser. Naming the def instead types the input from the same
+*   declaration — and `import type` is ERASED, so it costs the bundle nothing.
+*   Passing an output type where a def belongs is now a compile error rather
+*   than a silent loss of typing, which is the point.
 *
 * @example
-* ```tsx
+* ```tsx no-check
 * import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+* import type { digest } from "./agent.ts";
 *
 * function DigestForm() {
-*   const { submit, run, pending, error } = useWorkflowSubmit("digest");
+*   const { submit, run, pending, error } = useWorkflowSubmit<typeof digest>("digest");
 *   return (
 *     <Form onSubmit={(values) => submit(values)} error={error}>
 *       <TextField name="url" label="Link" type="url" required />
 *       <SubmitButton pending={pending}>Digest</SubmitButton>
-*       {run?.status === "completed" && <p>Done.</p>}
+*       {run?.status === "completed" && <p>{run.output.title}</p>}
 *     </Form>
 *   );
 * }
@@ -1449,6 +1459,7 @@ function useWorkflowSubmit(workflow, opts = {}) {
 	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => session.current?.gate, []), setUpload);
 	return {
 		submit,
+		submitForm: submit,
 		reset,
 		wake,
 		cancel,
@@ -1498,14 +1509,15 @@ function useWorkflowSubmit(workflow, opts = {}) {
 * beside it are not reordered when the schema lands.
 *
 * @example
-* ```tsx
+* ```tsx no-check
 * import { Form, SubmitButton, WorkflowFields, useWorkflowSubmit }
 *   from "@alexkroman1/aai-ui";
+* import type { transcribe } from "./agent.ts";
 *
 * function StartRun() {
-*   const { submit, pending, error } = useWorkflowSubmit("transcribe");
+*   const { submitForm, pending, error } = useWorkflowSubmit<typeof transcribe>("transcribe");
 *   return (
-*     <Form onSubmit={(values) => submit(values)} error={error}>
+*     <Form onSubmit={submitForm} error={error}>
 *       <WorkflowFields workflow="transcribe" />
 *       <SubmitButton pending={pending}>Transcribe</SubmitButton>
 *     </Form>
@@ -1750,11 +1762,12 @@ const PENDING = { pending: true };
 * @returns See {@link UseDownloadUrlResult}.
 *
 * @example
-* ```tsx
+* ```tsx no-check
 * import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+* import type { spokenSummary } from "./agent.ts";
 *
 * function Playback() {
-*   const { run } = useWorkflowSubmit<{ audio: string }>("spokenSummary");
+*   const { run } = useWorkflowSubmit<typeof spokenSummary>("spokenSummary");
 *   const output = run?.status === "completed" ? run.output : undefined;
 *   const audio = useDownloadUrl(output?.audio);
 *   if (audio.pending) return <p>Fetching audio…</p>;
@@ -2073,6 +2086,7 @@ function useWorkflowStream(workflow, opts = {}) {
 	const { pauseUpload, resumeUpload } = useUploadPause(useCallback(() => gateRef.current, []), setUpload);
 	return {
 		submit,
+		submitForm: submit,
 		reset,
 		wake,
 		cancel,

package/dist/{session-core-CMEpwRP1.js → session-core-0hClhPz-.js}

@@ -119,6 +119,47 @@ async function initAudioCapture(conn, msg, deps) {
 	}
 }
 //#endregion
+//#region session-core-close.ts
+/**
+* What a socket's CLOSE means to the caller.
+*
+* One decision, in its own module because `session-core.ts` is at its length cap
+* and because the decision is worth reading on its own: which endings are
+* ordinary, and which carry something the user has to be told.
+*
+* @module
+*/
+/**
+* The one close code whose reason is never worth showing.
+*
+* `1000` is a deliberate, successful close — the caller hanging up, or the
+* server retiring a session it finished with. A browser reports a socket that
+* closed with no status as `1005`, which carries no reason either, so testing
+* for text is enough to exclude it.
+*/
+const NORMAL_CLOSE = 1e3;
+/**
+* What to REPORT for a socket that closed for good, or null for an ordinary end.
+*
+* A sentence the peer wrote beats one this file invented. A guest that cannot
+* build its runtime closes 1011 with the remedy already in it — "Anthropic LLM:
+* missing API key. Set ANTHROPIC_API_KEY in the agent env." — and this handler
+* used to discard `event.reason` entirely, so the one thing a misconfigured
+* deployment needed to be told surfaced as "WebSocket connection error", or as a
+* plain disconnect with nothing at all. Measured against a deployed agent with no
+* provider key.
+*
+* A NORMAL close carries no reason worth showing (1000 is the caller hanging up
+* or the server retiring a finished session; a browser reports a status-less
+* close as 1005, which has no reason either), so the two ordinary endings are
+* untouched.
+*/
+function closeFailure(event, socketErrored) {
+	const refusal = event.reason.trim();
+	if (refusal !== "" && event.code !== NORMAL_CLOSE) return refusal;
+	return socketErrored ? "WebSocket connection error" : null;
+}
+//#endregion
 //#region session-core-reconnect.ts
 /**
 * Automatic reconnection for the browser session socket, built on
@@ -1172,11 +1213,11 @@ function createSessionCore(options) {
 		socket.addEventListener("error", () => {
 			socketErrored = true;
 		}, { signal: sig });
-		socket.addEventListener("close", () => {
+		socket.addEventListener("close", (event) => {
 			if (sig.aborted) return;
 			handshake.disarm();
 			cleanupAudio();
-			if (!conn.retiredByServer && reconnectPending(socket)) {
+			if (!(conn.retiredByServer || agentState.fatal()) && reconnectPending(socket)) {
 				conn.generation.bump();
 				socketErrored = false;
 				updateState({
@@ -1188,14 +1229,15 @@ function createSessionCore(options) {
 			controller.abort();
 			socket.close();
 			conn.ws = null;
+			const failure = closeFailure(event, socketErrored);
 			updateState({
-				...socketErrored ? agentState.apply({
+				...failure === null ? agentState.apply({ type: "CLOSED" }) : agentState.apply({
 					type: "FAILED",
 					error: {
 						code: "connection",
-						message: "WebSocket connection error"
+						message: failure
 					}
-				}) : agentState.apply({ type: "CLOSED" }),
+				}),
 				running: false,
 				recording: false
 			});

package/dist/session-core-close.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What a socket's CLOSE means to the caller.
+ *
+ * One decision, in its own module because `session-core.ts` is at its length cap
+ * and because the decision is worth reading on its own: which endings are
+ * ordinary, and which carry something the user has to be told.
+ *
+ * @module
+ */
+/**
+ * What to REPORT for a socket that closed for good, or null for an ordinary end.
+ *
+ * A sentence the peer wrote beats one this file invented. A guest that cannot
+ * build its runtime closes 1011 with the remedy already in it — "Anthropic LLM:
+ * missing API key. Set ANTHROPIC_API_KEY in the agent env." — and this handler
+ * used to discard `event.reason` entirely, so the one thing a misconfigured
+ * deployment needed to be told surfaced as "WebSocket connection error", or as a
+ * plain disconnect with nothing at all. Measured against a deployed agent with no
+ * provider key.
+ *
+ * A NORMAL close carries no reason worth showing (1000 is the caller hanging up
+ * or the server retiring a finished session; a browser reports a status-less
+ * close as 1005, which has no reason either), so the two ordinary endings are
+ * untouched.
+ */
+export declare function closeFailure(event: CloseEvent, socketErrored: boolean): string | null;

package/dist/session-core.js

@@ -1,2 +1,2 @@
-import { t as createSessionCore } from "./session-core-CMEpwRP1.js";
+import { t as createSessionCore } from "./session-core-0hClhPz-.js";
 export { createSessionCore };

package/dist/use-download-url.d.ts

@@ -61,11 +61,12 @@ export type UseDownloadUrlResult = {
  * @returns See {@link UseDownloadUrlResult}.
  *
  * @example
- * ```tsx
+ * ```tsx no-check
  * import { useDownloadUrl, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ * import type { spokenSummary } from "./agent.ts";
  *
  * function Playback() {
- *   const { run } = useWorkflowSubmit<{ audio: string }>("spokenSummary");
+ *   const { run } = useWorkflowSubmit<typeof spokenSummary>("spokenSummary");
  *   const output = run?.status === "completed" ? run.output : undefined;
  *   const audio = useDownloadUrl(output?.audio);
  *   if (audio.pending) return <p>Fetching audio…</p>;

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

@@ -32,8 +32,10 @@
  * `wait` here when the page really does want one request, and the run is
  * followed from the same id either way.
  */
-import type { UploadParallel, UploadProgress, WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+import type { AnyWorkflowDef, UploadParallel, UploadProgress, WorkflowOutputOf, WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+import type { FormValues } from "./components/form-types.ts";
 import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+import type { SubmitInputOf } from "./workflow-def-types.ts";
 /** Options for {@link useWorkflows}. */
 export type UseWorkflowsOptions = {
     /** The client to read the listing with. Defaults to one for the page's own agent. */
@@ -138,13 +140,30 @@ export type UploadStatus = UploadProgress & {
  * in, so a page can render `<WorkflowProgress>` beside the upload bar instead
  * of after it. Here the run does not exist until the last byte lands.
  */
-export type WorkflowSubmission<R = unknown> = {
+export type WorkflowSubmission<R = unknown, I = unknown> = {
     /**
      * Start a run with this input. Resolves once the run EXISTS — progress
      * arrives through `run` — so a `<Form>`'s handler can await it to know the
      * submission was accepted.
      */
-    submit: (input: unknown) => Promise<void>;
+    submit: (input: I) => Promise<void>;
+    /**
+     * Start a run from a `<Form>`'s values, which are UNVALIDATED.
+     *
+     * The same function as {@link WorkflowSubmission.submit}, with the type the
+     * form path can honestly offer. `FormValues` is `Record<string, unknown>`
+     * scraped off the DOM at submit time — a `<TextField name="limit">`
+     * contributes a string whatever the schema says — so the shape is not known
+     * here and the SERVER is what checks it against the workflow's schema.
+     *
+     * Two doors rather than one loose one: `submit` takes the workflow's own
+     * input type, so a hand-built object is checked at compile time and
+     * `submit({ ur1: 42 })` is an error; widening it to accept `FormValues` would
+     * have made every object satisfy it and given the typing back. Reaching for
+     * this one is the author saying "these came from a form", which is a fact
+     * about the values and not a cast.
+     */
+    submitForm: (values: FormValues) => Promise<void>;
     /** Clear the run and any error, putting the form back to its initial state. */
     reset: () => void;
     /**
@@ -236,21 +255,30 @@ export type UseWorkflowSubmitOptions = {
 /**
  * Start a workflow from a form, and follow the run it creates.
  *
- * @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>`.
+ * @typeParam D - The workflow DEFINITION, which types both halves of the
+ *   submission: `submit(input)` takes what the workflow's schema parses to, and
+ *   `run.status === "completed"` narrows to a typed `run.output`.
+ *
+ *   It used to be the OUTPUT type alone, and the asymmetry was the bug: a page
+ *   already wrote `WorkflowOutputOf<typeof digest>` to get the output, while
+ *   `submit` took `unknown`, so `submit({ ur1: 42 })` compiled and arrived as a
+ *   400 in the browser. Naming the def instead types the input from the same
+ *   declaration — and `import type` is ERASED, so it costs the bundle nothing.
+ *   Passing an output type where a def belongs is now a compile error rather
+ *   than a silent loss of typing, which is the point.
  *
  * @example
- * ```tsx
+ * ```tsx no-check
  * import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ * import type { digest } from "./agent.ts";
  *
  * function DigestForm() {
- *   const { submit, run, pending, error } = useWorkflowSubmit("digest");
+ *   const { submit, run, pending, error } = useWorkflowSubmit<typeof digest>("digest");
  *   return (
  *     <Form onSubmit={(values) => submit(values)} error={error}>
  *       <TextField name="url" label="Link" type="url" required />
  *       <SubmitButton pending={pending}>Digest</SubmitButton>
- *       {run?.status === "completed" && <p>Done.</p>}
+ *       {run?.status === "completed" && <p>{run.output.title}</p>}
  *     </Form>
  *   );
  * }
@@ -258,4 +286,4 @@ export type UseWorkflowSubmitOptions = {
  *
  * @public
  */
-export declare function useWorkflowSubmit<R = unknown>(workflow: string, opts?: UseWorkflowSubmitOptions): WorkflowSubmission<R>;
+export declare function useWorkflowSubmit<D extends AnyWorkflowDef>(workflow: string, opts?: UseWorkflowSubmitOptions): WorkflowSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

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

@@ -76,7 +76,9 @@
  * `stream.ts`'s idle bound (five minutes of no new bytes) is what decides that a
  * pause has become an abandonment.
  */
+import type { AnyWorkflowDef, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import type { UseWorkflowSubmitOptions, WorkflowSubmission } from "./use-workflow-form.ts";
+import type { SubmitInputOf } from "./workflow-def-types.ts";
 /**
  * Options for {@link useWorkflowStream}.
  *
@@ -111,7 +113,7 @@ export type UseWorkflowStreamOptions = Omit<UseWorkflowSubmitOptions, "wait">;
  *   are in. That is what lets a page render `<WorkflowProgress>` beside the
  *   upload bar rather than after it.
  */
-export type WorkflowStreamSubmission<R = unknown> = WorkflowSubmission<R>;
+export type WorkflowStreamSubmission<R = unknown, I = unknown> = WorkflowSubmission<R, I>;
 /**
  * Start a workflow run and stream a file into it while it works.
  *
@@ -137,4 +139,4 @@ export type WorkflowStreamSubmission<R = unknown> = WorkflowSubmission<R>;
  *
  * @public
  */
-export declare function useWorkflowStream<R = unknown>(workflow: string, opts?: UseWorkflowStreamOptions): WorkflowStreamSubmission<R>;
+export declare function useWorkflowStream<D extends AnyWorkflowDef>(workflow: string, opts?: UseWorkflowStreamOptions): WorkflowStreamSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

package/dist/workflow-client.d.ts

@@ -57,7 +57,7 @@ export type WorkflowRun<R = unknown> = WorkflowRunSnapshot<R>;
  * and a structural restatement would be a second thing to keep in step with the
  * routes for no gain.
  */
-export type { WorkflowApi, WorkflowOutputOf, WorkflowRunStatus, WorkflowSummary, } from "@alexkroman1/aai/workflow-api";
+export type { WorkflowApi, WorkflowInputOf, WorkflowOutputOf, WorkflowRunStatus, WorkflowSummary, } from "@alexkroman1/aai/workflow-api";
 /**
  * A run status nothing will change again.
  *

package/dist/workflow-def-types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The narrowing the workflow hooks apply to a DEF's input type.
+ *
+ * It used to fall back to `unknown` so an un-parameterized
+ * `useWorkflowSubmit("digest")` kept compiling. It does not any more — the def
+ * is required — because the fallback was the last way to get an untyped
+ * `submit` back, and an escape hatch nobody needs is one somebody uses.
+ *
+ * There used to be a `SubmitOutputOf<D>` beside it. It was `WorkflowOutputOf<D>`
+ * spelled a second way and nothing else, so the hooks name `WorkflowOutputOf`
+ * directly — the SDK type this package already re-exports, and the one a page
+ * reading the rendered signature can click through to.
+ */
+import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
+/**
+ * What `submit()` takes for `D` — `undefined` when `D` declares no schema.
+ *
+ * This is what {@link WorkflowInputOf} cannot say on its own: a def whose
+ * `input` schema is absent has no parsed input, and `never` as a parameter type
+ * accepts nothing at all — not even `undefined` — so a workflow that declares
+ * no schema would have an uncallable `submit`. It gets `undefined` instead, i.e.
+ * `submit(undefined)`. Explicit rather than `void`, which would let the argument
+ * be omitted and which Biome's `noConfusingVoidType` rejects outside a return or
+ * type-parameter position.
+ *
+ * The `[T] extends [never]` spelling is deliberate: a bare `T extends never`
+ * distributes over a naked type parameter and answers `never` for a union.
+ *
+ * @public
+ */
+export type SubmitInputOf<D> = [WorkflowInputOf<D>] extends [never] ? undefined : WorkflowInputOf<D>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-ui",
-  "version": "8.2.0",
+  "version": "9.0.0",
   "type": "module",
   "files": [
     "dist",
@@ -33,7 +33,7 @@
     "use-stick-to-bottom": "^1.1.6",
     "use-sync-external-store": "^1.6.0",
     "xstate": "^5.32.5",
-    "@alexkroman1/aai": "8.2.0"
+    "@alexkroman1/aai": "9.0.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",