@alexkroman1/aai-ui 13.2.0 → 13.3.0

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

@@ -1,9 +1,9 @@
-import { t as pageBaseUrl } from "./_utils-B6498_bm.js";
+import { t as pageBaseUrl } from "./_utils-CyzjK0gW.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { errorMessage } from "@alexkroman1/aai";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient, isTerminal, isTerminal as isTerminal$1, readEventStream } from "@alexkroman1/aai/workflow-api";
-//#region workflow-client.ts
+//#region src/workflow-client.ts
 /**
 * Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
 *
@@ -73,7 +73,7 @@ function createWorkflowApi(opts = {}) {
 	});
 }
 //#endregion
-//#region _workflow-api-ref.ts
+//#region src/_workflow-api-ref.ts
 /**
 * The client preamble every workflow hook needs, once.
 *
@@ -121,7 +121,7 @@ function useWorkflowApiRef(api) {
 	}, []);
 }
 //#endregion
-//#region _repeat-until.ts
+//#region src/_repeat-until.ts
 /**
 * A bounded read, re-armed from the SETTLED read — the loop both workflow
 * watchers are built out of.
@@ -165,256 +165,7 @@ function repeatUntil(intervalMs, step) {
 	};
 }
 //#endregion
-//#region workflow-events.ts
-/**
-* Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
-*
-* Its own module because the seam is clean: everything in `workflow-client.ts`
-* is request/response shaping plus the poll, and this is one long-lived stream
-* and the SSE parser it needs.
-*
-* @internal
-*/
-/**
-* Watch a run over SSE, falling back to the caller's poll on any failure.
-*
-* The poll stays the fallback rather than being replaced, and that is the whole
-* shape of this: a stream is an optimisation over a mechanism that already
-* works, so every way it can fail — an older agent with no `/events` route, a
-* proxy that buffers, a network that drops it — has to degrade to the thing that
-* does. What it buys is real, though: on the platform every polled read BROKERS,
-* so N open tabs at `DEFAULT_WORKFLOW_POLL_MS` is N/2 brokered requests a
-* second, each able to boot a sandbox. One stream per tab replaces all of it.
-*
-* `EventSource` is not used, for two reasons that both matter here: it cannot
-* send an `Authorization` header (an agent with `AAI_WORKFLOW_API_TOKEN` set
-* would be unreachable), and it reconnects on its own schedule, which would
-* fight the caller's. A `fetch` stream gives both back.
-*
-* Returns a stop function. `onFallback` is called at most once, when this stream
-* cannot be relied on and the poll should take over.
-*/
-function watchRunEvents(getClient, runId, onRun, onSettled, onFallback) {
-	const controller = new AbortController();
-	let handedOver = false;
-	const handOver = () => {
-		if (handedOver || controller.signal.aborted) return;
-		handedOver = true;
-		onFallback();
-	};
-	/**
-	* Consume the stream. Resolves `"settled"` when the run reached a state
-	* nothing will change, and `"fallback"` for every other ending — including a
-	* clean end with no final frame, which is a dropped connection.
-	*
-	* A named function rather than an inline IIFE so `watchRunEvents` stays under
-	* the cognitive-complexity cap, and so the two outcomes are a return value
-	* instead of two callbacks invoked from six places.
-	*/
-	const pump = async () => {
-		const res = await getClient().watch(runId, controller.signal);
-		if (!(res.ok && res.body)) return "fallback";
-		for await (const frame of readEventStream(res.body, controller.signal)) {
-			if (frame.event === "run" && frame.data) onRun(frame.data);
-			const outcome = endingFor(frame.event);
-			if (outcome) return outcome;
-		}
-		return "fallback";
-	};
-	pump().then((outcome) => outcome === "settled" ? onSettled() : handOver(), () => handOver());
-	return () => controller.abort();
-}
-/**
-* Does this frame END the stream, and does the run need watching afterwards?
-*
-* `done` and `missing` are both final and neither wants a reconnect: the run is
-* terminal, or the id will never exist (a 404 is a stable answer — the world's
-* record is durable). `idle` is the stream handing ITSELF back after its
-* duration cap, so that one falls back to the poll. Anything else is not an
-* ending.
-*/
-function endingFor(event) {
-	if (event === "done" || event === "missing") return "settled";
-	return event === "idle" ? "fallback" : void 0;
-}
-//#endregion
-//#region use-workflow-run.ts
-/**
-* `useWorkflowRun` — watch one run until it settles.
-*
-* Split from `workflow-client.ts` on the seam that module's doc already draws:
-* everything there is a REQUEST (one call, one answer, no React), and everything
-* here is the loop that keeps asking. They are read for different reasons — the
-* client is what a script or a `curl` equivalent needs, this is what a page needs
-* — and only this half imports React.
-*
-* `workflow-events.ts` sits under it as the streaming fast path, and
-* `use-workflow-form.ts` above it as the form-shaped caller.
-*/
-/** How often {@link useWorkflowRun} re-reads a live run when it has to poll. */
-const DEFAULT_WORKFLOW_POLL_MS = 2e3;
-/**
-* Consecutive "no such run" reads {@link useWorkflowRun} tolerates before giving
-* up on the id.
-*
-* Small on purpose: a 404 is a stable answer, so the budget exists only to
-* absorb a first read that races the run's creation — not to keep hoping.
-* Unbounded, a stale id polls (and, on the platform, BROKERS) for as long as the
-* tab is open.
-*/
-const MAX_MISSING_READS = 3;
-/**
-* Poll `runId` until it is terminal, reporting each read. Returns a stop
-* function.
-*
-* Module-level rather than inline in the hook below, so neither function carries
-* the whole loop's branching — and so the loop can be read without React in the
-* way.
-*/
-function pollUntilTerminal(getClient, runId, intervalMs, onRun, onError, onStopped) {
-	let missing = 0;
-	/**
-	* A read that came back empty. Resolves whether the loop should STOP.
-	*
-	* A 404 is a STABLE answer — a run the agent does not know about now will not
-	* appear later — and retrying it unbounded is how a stale id (one restored
-	* from `localStorage`, or one whose agent was redeployed onto a fresh
-	* database) polls forever: the page stays `polling` and therefore busy, and on
-	* the platform every read BROKERS, so a tab's worth of dead ids keeps
-	* sandboxes resident. A small budget is kept anyway, because the first read
-	* can race a replica that has not yet seen the run.
-	*/
-	const onMissing = (signal) => {
-		missing += 1;
-		if (missing < 3) return false;
-		if (!signal.aborted) onError(`No workflow run ${runId}`);
-		return true;
-	};
-	const read = async (signal) => {
-		try {
-			const next = await getClient().get(runId);
-			if (signal.aborted) return true;
-			if (!next) return onMissing(signal);
-			missing = 0;
-			onRun(next);
-			return isTerminal(next);
-		} catch (err) {
-			if (!signal.aborted) onError(errorMessage(err));
-			return false;
-		}
-	};
-	return repeatUntil(intervalMs, async (signal) => {
-		if (!await read(signal)) return false;
-		if (!signal.aborted) onStopped();
-		return true;
-	});
-}
-/**
-* Watch one run until it reaches a terminal status.
-*
-* A watch rather than a subscription because a run is durable and the page is
-* 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
-* `undefined` (nothing started yet) also costs nothing.
-*
-* @example
-* ```tsx
-* import type { ToolInputSchema, WorkflowDef } from "@alexkroman1/aai";
-* import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
-* import { useWorkflowRun } from "@alexkroman1/aai-ui";
-*
-* // A real page writes `import type { digest } from "./agent.ts"`. Stood in
-* // for here so the example compiles on its own.
-* declare const digest: WorkflowDef<ToolInputSchema, Promise<{ points: string[] }>>;
-*
-* type Digest = WorkflowOutputOf<typeof digest>;
-*
-* function RunPanel({ runId }: { runId: string | undefined }) {
-*   // The type argument is what makes `run.output` a `Digest` below.
-*   const { run, error, polling } = useWorkflowRun<Digest>(runId);
-*   if (error !== undefined) return <p role="alert">{error}</p>;
-*   if (run?.status === "completed") {
-*     return (
-*       <ul>
-*         {run.output.points.map((point) => (
-*           <li key={point}>{point}</li>
-*         ))}
-*       </ul>
-*     );
-*   }
-*   return <p>{polling ? "Working…" : "Nothing running."}</p>;
-* }
-* ```
-*
-* @typeParam R - The workflow's output type. Supplying it is what makes
-*   `run.status === "completed"` narrow to a typed `run.output` instead of
-*   `unknown`. Derive it with `WorkflowOutputOf<typeof myWorkflow>` — a
-*   type-only import of `agent.ts` is erased, so it costs the bundle nothing.
-* @param runId - The run to watch. `undefined` costs nothing, so a page may
-*   pass its state straight through before a run exists.
-* @param opts - `api` when the page holds its own client; `intervalMs` to
-*   change the poll interval the stream falls back to.
-* @returns The latest snapshot, the last read's error, and whether the watch
-*   is still going — see {@link UseWorkflowRunResult}.
-*
-* @public
-*/
-function useWorkflowRun(runId, opts = {}) {
-	const { api, intervalMs = DEFAULT_WORKFLOW_POLL_MS } = opts;
-	const [run, setRun] = useState(void 0);
-	const [error, setError] = useState(void 0);
-	/**
-	* Has the watch stopped for a reason the snapshot does not show?
-	*
-	* Only one such reason exists — an id the agent kept reporting as unknown,
-	* past {@link MAX_MISSING_READS} — and it leaves `run` undefined, so `polling`
-	* derived from `isTerminal(run)` alone would stay true forever.
-	*/
-	const [stopped, setStopped] = useState(false);
-	const getClient = useWorkflowApiRef(api);
-	useEffect(() => {
-		setRun(void 0);
-		setError(void 0);
-		setStopped(false);
-		if (!runId) return;
-		const onRun = (next) => {
-			setRun(next);
-			setError(void 0);
-		};
-		let stopPoll;
-		const stopStream = watchRunEvents(getClient, runId, onRun, () => setStopped(true), () => {
-			stopPoll = pollUntilTerminal(getClient, runId, intervalMs, onRun, setError, () => setStopped(true));
-		});
-		return () => {
-			stopStream();
-			stopPoll?.();
-		};
-	}, [
-		runId,
-		intervalMs,
-		getClient
-	]);
-	return {
-		run,
-		error,
-		polling: runId !== void 0 && !stopped && !isTerminal(run)
-	};
-}
-//#endregion
-//#region use-workflow-progress.ts
+//#region src/use-workflow-progress.ts
 /**
 * `useWorkflowProgress` — read what a run has WRITTEN while it runs.
 *
@@ -560,7 +311,7 @@ async function consumeFrames(body, signal) {
 * 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
+* `packages/aai-runtime/src/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
@@ -684,4 +435,253 @@ function useWorkflowProgress(runId, opts = {}) {
 	};
 }
 //#endregion
-export { useWorkflowRun as a, isTerminal$1 as c, MAX_MISSING_READS as i, useWorkflowProgress as n, useWorkflowApiRef as o, DEFAULT_WORKFLOW_POLL_MS as r, createWorkflowApi as s, DEFAULT_PROGRESS_POLL_MS as t };
+//#region src/workflow-events.ts
+/**
+* Watching a run over server-sent events — the PUSH half of `useWorkflowRun`.
+*
+* Its own module because the seam is clean: everything in `workflow-client.ts`
+* is request/response shaping plus the poll, and this is one long-lived stream
+* and the SSE parser it needs.
+*
+* @internal
+*/
+/**
+* Watch a run over SSE, falling back to the caller's poll on any failure.
+*
+* The poll stays the fallback rather than being replaced, and that is the whole
+* shape of this: a stream is an optimisation over a mechanism that already
+* works, so every way it can fail — an older agent with no `/events` route, a
+* proxy that buffers, a network that drops it — has to degrade to the thing that
+* does. What it buys is real, though: on the platform every polled read BROKERS,
+* so N open tabs at `DEFAULT_WORKFLOW_POLL_MS` is N/2 brokered requests a
+* second, each able to boot a sandbox. One stream per tab replaces all of it.
+*
+* `EventSource` is not used, for two reasons that both matter here: it cannot
+* send an `Authorization` header (an agent with `AAI_WORKFLOW_API_TOKEN` set
+* would be unreachable), and it reconnects on its own schedule, which would
+* fight the caller's. A `fetch` stream gives both back.
+*
+* Returns a stop function. `onFallback` is called at most once, when this stream
+* cannot be relied on and the poll should take over.
+*/
+function watchRunEvents(getClient, runId, onRun, onSettled, onFallback) {
+	const controller = new AbortController();
+	let handedOver = false;
+	const handOver = () => {
+		if (handedOver || controller.signal.aborted) return;
+		handedOver = true;
+		onFallback();
+	};
+	/**
+	* Consume the stream. Resolves `"settled"` when the run reached a state
+	* nothing will change, and `"fallback"` for every other ending — including a
+	* clean end with no final frame, which is a dropped connection.
+	*
+	* A named function rather than an inline IIFE so `watchRunEvents` stays under
+	* the cognitive-complexity cap, and so the two outcomes are a return value
+	* instead of two callbacks invoked from six places.
+	*/
+	const pump = async () => {
+		const res = await getClient().watch(runId, controller.signal);
+		if (!(res.ok && res.body)) return "fallback";
+		for await (const frame of readEventStream(res.body, controller.signal)) {
+			if (frame.event === "run" && frame.data) onRun(frame.data);
+			const outcome = endingFor(frame.event);
+			if (outcome) return outcome;
+		}
+		return "fallback";
+	};
+	pump().then((outcome) => outcome === "settled" ? onSettled() : handOver(), () => handOver());
+	return () => controller.abort();
+}
+/**
+* Does this frame END the stream, and does the run need watching afterwards?
+*
+* `done` and `missing` are both final and neither wants a reconnect: the run is
+* terminal, or the id will never exist (a 404 is a stable answer — the world's
+* record is durable). `idle` is the stream handing ITSELF back after its
+* duration cap, so that one falls back to the poll. Anything else is not an
+* ending.
+*/
+function endingFor(event) {
+	if (event === "done" || event === "missing") return "settled";
+	return event === "idle" ? "fallback" : void 0;
+}
+//#endregion
+//#region src/use-workflow-run.ts
+/**
+* `useWorkflowRun` — watch one run until it settles.
+*
+* Split from `workflow-client.ts` on the seam that module's doc already draws:
+* everything there is a REQUEST (one call, one answer, no React), and everything
+* here is the loop that keeps asking. They are read for different reasons — the
+* client is what a script or a `curl` equivalent needs, this is what a page needs
+* — and only this half imports React.
+*
+* `workflow-events.ts` sits under it as the streaming fast path, and
+* `use-workflow-form.ts` above it as the form-shaped caller.
+*/
+/** How often {@link useWorkflowRun} re-reads a live run when it has to poll. */
+const DEFAULT_WORKFLOW_POLL_MS = 2e3;
+/**
+* Consecutive "no such run" reads {@link useWorkflowRun} tolerates before giving
+* up on the id.
+*
+* Small on purpose: a 404 is a stable answer, so the budget exists only to
+* absorb a first read that races the run's creation — not to keep hoping.
+* Unbounded, a stale id polls (and, on the platform, BROKERS) for as long as the
+* tab is open.
+*/
+const MAX_MISSING_READS = 3;
+/**
+* Poll `runId` until it is terminal, reporting each read. Returns a stop
+* function.
+*
+* Module-level rather than inline in the hook below, so neither function carries
+* the whole loop's branching — and so the loop can be read without React in the
+* way.
+*/
+function pollUntilTerminal(getClient, runId, intervalMs, onRun, onError, onStopped) {
+	let missing = 0;
+	/**
+	* A read that came back empty. Resolves whether the loop should STOP.
+	*
+	* A 404 is a STABLE answer — a run the agent does not know about now will not
+	* appear later — and retrying it unbounded is how a stale id (one restored
+	* from `localStorage`, or one whose agent was redeployed onto a fresh
+	* database) polls forever: the page stays `polling` and therefore busy, and on
+	* the platform every read BROKERS, so a tab's worth of dead ids keeps
+	* sandboxes resident. A small budget is kept anyway, because the first read
+	* can race a replica that has not yet seen the run.
+	*/
+	const onMissing = (signal) => {
+		missing += 1;
+		if (missing < 3) return false;
+		if (!signal.aborted) onError(`No workflow run ${runId}`);
+		return true;
+	};
+	const read = async (signal) => {
+		try {
+			const next = await getClient().get(runId);
+			if (signal.aborted) return true;
+			if (!next) return onMissing(signal);
+			missing = 0;
+			onRun(next);
+			return isTerminal(next);
+		} catch (err) {
+			if (!signal.aborted) onError(errorMessage(err));
+			return false;
+		}
+	};
+	return repeatUntil(intervalMs, async (signal) => {
+		if (!await read(signal)) return false;
+		if (!signal.aborted) onStopped();
+		return true;
+	});
+}
+/**
+* Watch one run until it reaches a terminal status.
+*
+* A watch rather than a subscription because a run is durable and the page is
+* 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
+* `undefined` (nothing started yet) also costs nothing.
+*
+* @example
+* ```tsx
+* import type { ToolInputSchema, WorkflowDef } from "@alexkroman1/aai";
+* import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+* import { useWorkflowRun } from "@alexkroman1/aai-ui";
+*
+* // A real page writes `import type { digest } from "./agent.ts"`. Stood in
+* // for here so the example compiles on its own.
+* declare const digest: WorkflowDef<ToolInputSchema, Promise<{ points: string[] }>>;
+*
+* type Digest = WorkflowOutputOf<typeof digest>;
+*
+* function RunPanel({ runId }: { runId: string | undefined }) {
+*   // The type argument is what makes `run.output` a `Digest` below.
+*   const { run, error, polling } = useWorkflowRun<Digest>(runId);
+*   if (error !== undefined) return <p role="alert">{error}</p>;
+*   if (run?.status === "completed") {
+*     return (
+*       <ul>
+*         {run.output.points.map((point) => (
+*           <li key={point}>{point}</li>
+*         ))}
+*       </ul>
+*     );
+*   }
+*   return <p>{polling ? "Working…" : "Nothing running."}</p>;
+* }
+* ```
+*
+* @typeParam R - The workflow's output type. Supplying it is what makes
+*   `run.status === "completed"` narrow to a typed `run.output` instead of
+*   `unknown`. Derive it with `WorkflowOutputOf<typeof myWorkflow>` — a
+*   type-only import of `agent.ts` is erased, so it costs the bundle nothing.
+* @param runId - The run to watch. `undefined` costs nothing, so a page may
+*   pass its state straight through before a run exists.
+* @param opts - `api` when the page holds its own client; `intervalMs` to
+*   change the poll interval the stream falls back to.
+* @returns The latest snapshot, the last read's error, and whether the watch
+*   is still going — see {@link UseWorkflowRunResult}.
+*
+* @public
+*/
+function useWorkflowRun(runId, opts = {}) {
+	const { api, intervalMs = DEFAULT_WORKFLOW_POLL_MS } = opts;
+	const [run, setRun] = useState(void 0);
+	const [error, setError] = useState(void 0);
+	/**
+	* Has the watch stopped for a reason the snapshot does not show?
+	*
+	* Only one such reason exists — an id the agent kept reporting as unknown,
+	* past {@link MAX_MISSING_READS} — and it leaves `run` undefined, so `polling`
+	* derived from `isTerminal(run)` alone would stay true forever.
+	*/
+	const [stopped, setStopped] = useState(false);
+	const getClient = useWorkflowApiRef(api);
+	useEffect(() => {
+		setRun(void 0);
+		setError(void 0);
+		setStopped(false);
+		if (!runId) return;
+		const onRun = (next) => {
+			setRun(next);
+			setError(void 0);
+		};
+		let stopPoll;
+		const stopStream = watchRunEvents(getClient, runId, onRun, () => setStopped(true), () => {
+			stopPoll = pollUntilTerminal(getClient, runId, intervalMs, onRun, setError, () => setStopped(true));
+		});
+		return () => {
+			stopStream();
+			stopPoll?.();
+		};
+	}, [
+		runId,
+		intervalMs,
+		getClient
+	]);
+	return {
+		run,
+		error,
+		polling: runId !== void 0 && !stopped && !isTerminal(run)
+	};
+}
+//#endregion
+export { useWorkflowProgress as a, isTerminal$1 as c, DEFAULT_PROGRESS_POLL_MS as i, MAX_MISSING_READS as n, useWorkflowApiRef as o, useWorkflowRun as r, createWorkflowApi as s, DEFAULT_WORKFLOW_POLL_MS as t };

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

@@ -93,7 +93,10 @@ import type { SubmitInputOf } from "./workflow-def-types.ts";
  * 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.
+ * `key` itself still works, and still makes the run findable — but it is NOT
+ * defaulted here the way `useWorkflowSubmit` defaults it, because the whole
+ * value of that default is the lookup this hook refuses, and minting a key
+ * nothing will ever read back is a slot left in storage for no one.
  *
  * `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

package/dist/use-workflows.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The agent's declared workflows — what a form is rendered FROM.
+ *
+ * Split out of `use-workflow-form.ts` at the 500-line cap, along the seam that
+ * file's own doc already drew: it held "the two hooks a FORM needs", and only
+ * one of them is about a RUN. This is the other one, and it shares nothing with
+ * its former neighbours but the client ref every hook here uses — no state, no
+ * run id, no upload.
+ */
+import type { WorkflowSummary } from "@alexkroman1/aai/workflow-api";
+import type { WorkflowApi } from "./workflow-client.ts";
+/** Options for {@link useWorkflows}. */
+export type UseWorkflowsOptions = {
+    /** The client to read the listing with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /**
+     * Skip the lookup entirely, reporting an empty listing that is not loading.
+     *
+     * For a caller that may or may not need the listing and cannot decide with a
+     * conditional hook — `<WorkflowFields>` handed a summary rather than a name is
+     * the one in this package. It reports `loading: false`, because a skipped
+     * lookup is finished rather than pending.
+     */
+    skip?: boolean;
+};
+/** What {@link useWorkflows} reports. */
+export type UseWorkflowsResult = {
+    /** The agent's declared workflows, each with the JSON Schema of its input. */
+    workflows: WorkflowSummary[];
+    /** True until the listing lands, so a form can hold its fields back. */
+    loading: boolean;
+    /** The lookup's failure. Set alongside an EMPTY list, which is why it exists. */
+    error: string | undefined;
+};
+/**
+ * Read the agent's declared workflows.
+ *
+ * What `<WorkflowFields>` renders a form FROM: each summary carries the JSON
+ * Schema of that workflow's input, converted server-side precisely so a browser
+ * can read it.
+ *
+ * The failure is reported rather than swallowed, because the alternative is an
+ * empty list — which renders as a form with no fields and reads as "this agent
+ * declares no workflows" about an agent that was merely unreachable.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflows } from "@alexkroman1/aai-ui";
+ *
+ * // A page rendering its own chrome from the listing — a picker, say. A form
+ * // for ONE workflow wants `<WorkflowFields workflow="name" />` instead,
+ * // which does this lookup itself.
+ * function WorkflowPicker({ onPick }: { onPick: (name: string) => void }) {
+ *   const { workflows, loading, error } = useWorkflows();
+ *   if (loading) return <p>Loading…</p>;
+ *   if (error !== undefined) return <p role="alert">{error}</p>;
+ *   return (
+ *     <ul>
+ *       {workflows.map((summary) => (
+ *         <li key={summary.name}>
+ *           <button type="button" onClick={() => onPick(summary.name)}>
+ *             {summary.description ?? summary.name}
+ *           </button>
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ *
+ * @param opts - See {@link UseWorkflowsOptions}.
+ * @returns The listing, its loading flag and its failure — see
+ * {@link UseWorkflowsResult}.
+ *
+ * @public
+ */
+export declare function useWorkflows(opts?: UseWorkflowsOptions): UseWorkflowsResult;

package/dist/worklets/capture-processor.js

@@ -1,6 +1,6 @@
 import { MIC_BUFFER_SECONDS, MIC_SILENCE_PROBE_MS } from "../types.js";
-import { t as workletModuleUrl } from "../_module-url-C_4gRVL0.js";
-//#region worklets/capture-processor.ts
+import { t as workletModuleUrl } from "../_module-url-C13kAJ87.js";
+//#region src/worklets/capture-processor.ts
 /** Raw worklet source — exported so tests can evaluate the processor directly. */
 const captureProcessorSource = `
 class CaptureProcessor extends AudioWorkletProcessor {

package/dist/worklets/playback-processor.js

@@ -1,6 +1,6 @@
 import { PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS } from "../types.js";
-import { t as workletModuleUrl } from "../_module-url-C_4gRVL0.js";
-//#region worklets/playback-processor.ts
+import { t as workletModuleUrl } from "../_module-url-C13kAJ87.js";
+//#region src/worklets/playback-processor.ts
 /** Raw worklet source — exported so tests can evaluate the processor directly. */
 const playbackProcessorSource = `
 class PlaybackProcessor extends AudioWorkletProcessor {