@alexkroman1/aai-ui 5.14.0 → 6.2.0

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

@@ -4,8 +4,23 @@ export declare const HANDSHAKE_ERROR: SessionError;
 export type HandshakeGuard = {
     /** Start the deadline for the attempt that just opened. */
     arm(): void;
-    /** Stop it — `config` arrived, or this socket is closing. */
+    /** Stop it — this socket is closing, or the connection is being torn down. */
     disarm(): void;
+    /**
+     * The `config` frame arrived: stop the deadline AND spend nothing.
+     *
+     * Separate from {@link HandshakeGuard.disarm} because the budget is
+     * CONSECUTIVE, and only a completed handshake proves the peer is healthy. One
+     * guard covers a whole `connect()`, partysocket's retries included, so with a
+     * plain disarm the count survived every successful session in between: an
+     * hour-long call whose socket dropped three times, each drop timing out once
+     * before the next attempt succeeded, surfaced the permanent
+     * "Agent did not complete the session handshake" error against a peer that
+     * had answered every time. A close must NOT reset it — a wedged peer closes
+     * and reopens on its own, and resetting there is the unbounded re-dial loop
+     * the budget exists to bound.
+     */
+    succeeded(): void;
 };
 /**
  * Watch one connection's handshake.

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

@@ -1,7 +1,7 @@
 import type { ConnState, SessionSnapshot } from "./session-core-types.ts";
 /**
  * Snapshot fields cleared when a session's conversation state is wiped —
- * shared by the initial snapshot, `resetState()`, and the server `reset` event.
+ * shared by the initial snapshot, `resetState()`, and `session.reset`.
  * The empty arrays are safe to share: snapshot collections are never mutated
  * in place, only replaced.
  */
@@ -41,7 +41,7 @@ type MessageHandlers = {
     handleMessage(data: unknown): SessionConfigMessage | undefined;
     /**
      * Wait for `io`'s playback queue to drain, then transition to `"listening"`
-     * — guarded by the same turn-boundary generation the live `audio_done`
+     * — guarded by the same turn-boundary generation the live `audio.completed`
      * path uses. `initAudioCapture` routes the pre-init greeting replay
      * through this so a barge-in mid-greeting can't be stomped by the
      * replayed completion resolving late.

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

@@ -1,16 +1,11 @@
-/**
- * Automatic reconnection for the browser session socket, built on
- * partysocket's `ReconnectingWebSocket`. Kept out of `session-core.ts` so
- * the state machine there reads as protocol logic, not socket plumbing.
- */
-import ReconnectingWebSocket from "partysocket/ws";
+import type { WebSocketConstructor } from "./types.ts";
 /**
  * Open partysocket's reconnecting WebSocket. The URL is a *provider*,
  * re-evaluated on every attempt (async supported), so each retry picks up
  * the current broker-named endpoint and resume URL rather than the ones the
  * session started with.
  */
-export declare function openReconnectingSocket(urlProvider: () => Promise<string>): ReconnectingWebSocket;
+export declare function openReconnectingSocket(urlProvider: () => Promise<string>): InstanceType<WebSocketConstructor>;
 /**
  * True while `socket` is a reconnecting socket that will retry after the
  * close event currently being handled. partysocket schedules the retry

package/dist/session-core.js

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

package/dist/session-resume-store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Where a session id survives a page RELOAD.
+ *
+ * The id is what `?sessionId=` presents on reconnect, and it is the key the
+ * agent's slot state and event log live under — so a reload that cannot produce
+ * it starts a brand-new session, and a UI driven by `useAgentState` comes back
+ * empty even though the agent still holds the cart. The server side of the
+ * reconstitution was already built (`pushStateSnapshot` force-pushes the
+ * projection after hydration on every start, `state.updated` lands in
+ * `agentState`); what was missing is that nothing in the browser remembered the
+ * id across a reload. `onSessionId`/`resumeSessionId` let a client wire it by
+ * hand and exactly one of fourteen templates did, which is the shape of a
+ * default in the wrong place.
+ *
+ * **`sessionStorage`, deliberately, and this is the opposite call from the
+ * studio's session token.** A reload and a same-tab navigation survive it; a new
+ * tab and a visit tomorrow do not, which is what we want here rather than a
+ * limitation: presenting a day-old id suppresses the greeting
+ * (`parseWsUpgradeParams` keys that off the id's mere presence) and rejoins a
+ * conversation whose context is long gone. The studio token is a credential
+ * whose value is not being asked to sign out; this is a pointer into a live call.
+ *
+ * Keyed by the agent's own URL, so two agents served from one origin — which is
+ * every deployed agent, at `/:slug/` — cannot inherit each other's session.
+ *
+ * Every access is guarded: storage throws outright in some contexts (Safari
+ * private mode, storage blocked by policy), and a session that cannot be
+ * remembered must degrade to today's behaviour rather than failing to start.
+ */
+/** The stored session id for this agent, or undefined. @internal */
+export declare function readStoredSessionId(platformUrl: string): string | undefined;
+/** Remember this agent's session id for the next load. @internal */
+export declare function writeStoredSessionId(platformUrl: string, sessionId: string): void;
+/**
+ * Forget it, so the next load is a NEW session.
+ *
+ * Called from `end()`, which is the clear-and-forget the "New Conversation"
+ * button runs: leaving the id behind there would have the next load rejoin the
+ * conversation the user just discarded, greeting suppressed.
+ *
+ * @internal
+ */
+export declare function clearStoredSessionId(platformUrl: string): void;

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { DefaultToolResult } from "@alexkroman1/aai";
 import type { SessionErrorCode } from "@alexkroman1/aai/protocol";
-export { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS, } from "@alexkroman1/aai";
+export { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PACER_BURST_MS, PIPELINE_PLAYBACK_GRACE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS, } from "@alexkroman1/aai/internal";
 /**
  * `getUserMedia` audio constraints for every capture path in this package.
  *

package/dist/types.js

@@ -1,4 +1,4 @@
-import { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS } from "@alexkroman1/aai";
+import { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PACER_BURST_MS, PIPELINE_PLAYBACK_GRACE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS } from "@alexkroman1/aai/internal";
 //#region types.ts
 /**
 * `getUserMedia` audio constraints for every capture path in this package.
@@ -32,4 +32,4 @@ const VOICE_CAPTURE_CONSTRAINTS = {
 	voiceIsolation: false
 };
 //#endregion
-export { CAPTURE_STOP_ACK_TIMEOUT_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_JITTER_MS, PLAYBACK_PROGRESS_INTERVAL_MS, PLAYBACK_REFILL_MS, VOICE_CAPTURE_CONSTRAINTS };
+export { CAPTURE_STOP_ACK_TIMEOUT_MS, CLIENT_AUDIO_LEAD_MS, HEARD_AUDIO_LAG_MS, MIC_BUFFER_SECONDS, MIC_SEND_MAX_BUFFERED_BYTES, MIC_SILENCE_PROBE_MS, PACER_BURST_MS, PIPELINE_PLAYBACK_GRACE_MS, PLAYBACK_BUFFER_SECONDS, PLAYBACK_CONCEAL_FADE_MS, PLAYBACK_CONCEAL_FLOOR, PLAYBACK_DONE_MAX_WAIT_MS, PLAYBACK_DONE_POLL_MS, PLAYBACK_FILL_MS, PLAYBACK_PROGRESS_INTERVAL_MS, VOICE_CAPTURE_CONSTRAINTS };

package/dist/use-user-transcript.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
+ *
+ * `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
+ * mean different things:
+ *
+ * - `null` — nobody is speaking. There is no partial turn.
+ * - `""` — speech HAS been detected and no words have come back yet. A live
+ *   session sits here for a few hundred milliseconds at the start of every turn.
+ *
+ * Read as one falsy check, those collapse and the indicator never appears at the
+ * start of a turn — which is the moment it is for. So every custom chrome writes
+ * `transcript !== null && (transcript === "" ? "…" : transcript)`, three
+ * templates did exactly that, and each one re-derived a protocol distinction
+ * from the type rather than from anything that told them.
+ *
+ * This is the same distinction as two named booleans, so a component can say
+ * what it means: render on `speaking`, show `text`, and use the SDK's own
+ * placeholder when there is nothing to show yet.
+ */
+/**
+ * Placeholder for "listening, no words yet" — the `""` case above.
+ *
+ * A one-character ellipsis rather than three dots, because it is read by a
+ * screen reader as an ellipsis and it does not reflow the row when the first
+ * real word replaces it.
+ *
+ * @public
+ */
+export declare const TRANSCRIBING_PLACEHOLDER = "\u2026";
+/** What {@link useUserTranscript} returns. */
+export interface UseUserTranscriptResult {
+    /**
+     * True while the caller holds the turn — from speech detection to the final
+     * transcript. This is the flag a live-transcript row renders on.
+     */
+    speaking: boolean;
+    /**
+     * The words so far, or {@link TRANSCRIBING_PLACEHOLDER} while there are none.
+     * Empty string when nobody is speaking.
+     */
+    text: string;
+    /**
+     * The raw partial: the words so far, `""` while there are none, and `null`
+     * when nobody is speaking. For a chrome that wants to render its own
+     * placeholder (or none).
+     */
+    partial: string | null;
+}
+/**
+ * Subscribe to the caller's in-progress turn.
+ *
+ * Narrowly subscribed — a component using this re-renders at STT-partial rate,
+ * which is exactly what it is for and exactly what a whole-page `useSession()`
+ * should not do.
+ *
+ * @example
+ * ```tsx
+ * import { useUserTranscript } from "@alexkroman1/aai-ui";
+ *
+ * function LiveTranscript() {
+ *   const { speaking, text } = useUserTranscript();
+ *   if (!speaking) return null;
+ *   return <div className="italic opacity-60">{text}</div>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useUserTranscript(): UseUserTranscriptResult;

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

@@ -0,0 +1,136 @@
+/**
+ * The two hooks a FORM needs, as against the one a status view does.
+ *
+ * `useWorkflowRun` (`workflow-client.ts`) watches a run you already have.
+ * These two are what comes before it: `useWorkflows` reads the declared
+ * workflows so `<WorkflowFields>` can render a form from a schema, and
+ * `useWorkflowSubmit` starts a run and hands the id straight to
+ * `useWorkflowRun`.
+ *
+ * ## `useWorkflowSubmit` — a form's two halves in one hook
+ *
+ * A page that submits a workflow always needs the same four pieces of state:
+ * the run id, whether a submit is in flight, whether the RUN is still going, and
+ * whichever of the two failed. `link-digest` writes them out by hand, which is
+ * the right shape for a template teaching the primitives and the wrong shape to
+ * write a third time — and it is easy to get subtly wrong: dropping the previous
+ * run id before the new `POST` returns is what stops a finished result sitting
+ * under a form that is already submitting again.
+ *
+ * So this is `api.start` plus {@link useWorkflowRun}, with the state between
+ * them. It adds no transport of its own and holds no run state of its own; the
+ * watching (stream first, poll as its fallback, terminal stops) is entirely
+ * `useWorkflowRun`'s, and `run` here IS its run.
+ *
+ * ## Why it starts ASYNCHRONOUSLY even though a synchronous call exists
+ *
+ * `api.startAndWait` would collapse this to one request, and it is the wrong
+ * default for a page: it holds a socket open for up to a minute, answers nothing
+ * until it settles, and a page has `useWorkflowRun` — which survives a reload,
+ * shows progress, and costs one stream. The synchronous call is for callers with
+ * nowhere to put a watch (a script, a cron, a form POST from a server). Pass
+ * `wait` here when the page really does want one request, and the run is
+ * followed from the same id either way.
+ */
+import { type WorkflowSummary } from "@alexkroman1/aai";
+import type { WorkflowApi, WorkflowRun } 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.
+ *
+ * @public
+ */
+export declare function useWorkflows(opts?: UseWorkflowsOptions): UseWorkflowsResult;
+/** What {@link useWorkflowSubmit} returns. */
+export type WorkflowSubmission<R = 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>;
+    /** Clear the run and any error, putting the form back to its initial state. */
+    reset: () => void;
+    /** The run, once started, followed to completion. */
+    run: WorkflowRun<R> | undefined;
+    /**
+     * True from `submit()` until the run reaches a terminal status.
+     *
+     * The WORK, not the request: a run outlives its `POST`, and a submit button
+     * that re-enabled on the response would invite a second submission of work
+     * already in flight.
+     */
+    pending: boolean;
+    /** The submit's own failure (a rejected input), or the watch's. */
+    error: string | undefined;
+};
+/** Options for {@link useWorkflowSubmit}. */
+export type UseWorkflowSubmitOptions = {
+    /** 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;
+    /**
+     * Hold the `POST` open until the run settles, up to this many ms — the
+     * synchronous mode. Omitted (the default) returns as soon as the run exists.
+     */
+    wait?: number;
+    /** How often the fallback poll re-reads a live run. */
+    intervalMs?: number;
+};
+/**
+ * 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>`.
+ *
+ * @example
+ * ```tsx
+ * import { Form, SubmitButton, TextField, useWorkflowSubmit } from "@alexkroman1/aai-ui";
+ *
+ * function DigestForm() {
+ *   const { submit, run, pending, error } = useWorkflowSubmit("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>}
+ *     </Form>
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowSubmit<R = unknown>(workflow: string, opts?: UseWorkflowSubmitOptions): WorkflowSubmission<R>;

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

@@ -0,0 +1,100 @@
+/**
+ * `useWorkflowProgress` — read what a run has WRITTEN while it runs.
+ *
+ * The sibling of `useWorkflowRun`, and the split between them is the whole
+ * reason this exists. That hook reports a run's STATE: the status transitions
+ * the world records, which every run has. This reports what the run itself
+ * wrote through `getWritable()`, which is the only thing a long run can say
+ * before it finishes — a snapshot carries a status and, once terminal, an
+ * output, and nothing in between. A page that shows only status shows
+ * "Working…" for ten minutes and then a result.
+ *
+ * ## There is no poll fallback, and that is not an omission
+ *
+ * `useWorkflowRun` degrades to polling `GET /runs/:id` because a run's STATE is
+ * readable that way. A run's written chunks are not: the stream is the only
+ * route to them, so an agent that does not serve it has no progress to give and
+ * `supported` says so once, rather than a poll pretending to look for something
+ * that is not there. A page renders its status line either way.
+ *
+ * ## Chunks are RETAINED, so this is a replay as much as a tail
+ *
+ * The run's stream keeps every chunk, so a page that mounts late — a reload, a
+ * second tab, a link opened tomorrow — reads the whole history from index 0 and
+ * arrives at the same list as one that watched throughout. That is what makes a
+ * durable run's progress durable too, and it is why the default `startIndex` is
+ * 0 rather than "from now": a tail-only default would make the same page show
+ * different things depending on when it opened.
+ *
+ * ## It RE-OPENS while the run is live, because a progress read is bounded
+ *
+ * The route answers with the chunks written when the request arrived and then
+ * ends, reporting `complete` — whether the run itself was terminal. It has to:
+ * a workflow stream signals its end only once CLOSED, and a progress channel
+ * written by one step after another is never closed, so a read that waited for
+ * the end would hang forever on a finished run. (It did: see the route's own
+ * doc.)
+ *
+ * So this hook re-opens from where it left off until a read comes back
+ * `complete`. That is a poll, and the honest description of progress is a durable
+ * log rather than a socket — but it is a poll of a CHEAP shape: each read asks
+ * only for chunks past the last index it saw, so a quiet run costs an empty
+ * answer rather than the whole log again.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** The slice of the client this needs: one method. */
+export type RunProgressReader = Pick<WorkflowApi, "streamOutput">;
+export type UseWorkflowProgressResult<T = string> = {
+    /** Every chunk the run has written, oldest first. */
+    progress: T[];
+    /** The newest chunk, or undefined before the first one lands. */
+    latest: T | undefined;
+    /** True while the run is still being read — it may yet say more. */
+    streaming: boolean;
+    /**
+     * False once the agent has answered that it does not serve this route.
+     *
+     * Distinguishes "this deploy predates progress streams" from "the run has not
+     * written anything yet", which look identical from `progress` alone. A page
+     * uses it to hide the section rather than show an empty one forever.
+     */
+    supported: boolean;
+};
+/** How often a live run's progress is re-read once a bounded read has ended. */
+export declare const DEFAULT_PROGRESS_POLL_MS = 1000;
+/**
+ * Follow one run's progress stream.
+ *
+ * Passing `undefined` (nothing started yet) costs nothing, and reading stops for
+ * good once a read reports the run terminal — so a finished run costs one read.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowProgress } from "@alexkroman1/aai-ui";
+ *
+ * function Progress({ runId }: { runId?: string }) {
+ *   const { progress, streaming, supported } = useWorkflowProgress(runId);
+ *   if (!supported) return null;
+ *   return (
+ *     <pre>
+ *       {progress.join("\n")}
+ *       {streaming && "\n…"}
+ *     </pre>
+ *   );
+ * }
+ * ```
+ *
+ * @typeParam T - What the workflow writes. Defaults to `string`, which is what
+ *   a progress channel usually carries; a workflow writing objects names its own
+ *   shape. Nothing in the browser can verify it — the route describes no type —
+ *   so this is the page's assertion about its own agent, narrowed once here
+ *   rather than at every read.
+ *
+ * @public
+ */
+export declare function useWorkflowProgress<T = string>(runId: string | undefined, opts?: {
+    api?: WorkflowApi;
+    namespace?: string;
+    startIndex?: number;
+    intervalMs?: number;
+}): UseWorkflowProgressResult<T>;

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

@@ -0,0 +1,56 @@
+/**
+ * `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.
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** How often {@link useWorkflowRun} re-reads a live run when it has to poll. */
+export declare const DEFAULT_WORKFLOW_POLL_MS = 2000;
+/**
+ * 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.
+ */
+export declare const MAX_MISSING_READS = 3;
+export type UseWorkflowRunResult<R = unknown> = {
+    /** Latest snapshot, or undefined before the first read lands. */
+    run: WorkflowRun<R> | undefined;
+    /** The last read's failure, cleared by the next successful one. */
+    error: string | undefined;
+    /** True while a non-terminal run is still being watched. */
+    polling: boolean;
+};
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * @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.
+ *
+ * @public
+ */
+export declare function useWorkflowRun<R = unknown>(runId: string | undefined, opts?: {
+    api?: WorkflowApi;
+    intervalMs?: number;
+}): UseWorkflowRunResult<R>;

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

@@ -0,0 +1,71 @@
+/**
+ * The RUNS a workflow has had — the list a page shows beside its form.
+ *
+ * `useWorkflowRun` watches one run you already hold an id for, which is the
+ * right shape for the run a page just started and the wrong one for everything
+ * before it. A workflow app that only offers that leaves its own history
+ * unreachable: a page reload drops the id, and the only way back to yesterday's
+ * transcript is to have written the id down — which is what
+ * `transcription-workflow` asked people to do, with a text box for pasting one.
+ *
+ * `GET /workflows/runs?workflow=…` has always been able to answer this. This is
+ * the hook over it, so a page renders history instead of asking for an id.
+ *
+ * ## It re-reads on demand, and does not poll on its own
+ *
+ * A list is not a live view: the run a page cares about right now is already
+ * being watched by `useWorkflowRun`, and a second polling loop over the whole
+ * history would broker N requests a minute on the platform to re-learn what the
+ * first one already knows. So this reads once and hands back `refresh` — which
+ * a page calls when its own run settles, which is exactly when the list is
+ * stale.
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/** Options for {@link useWorkflowRuns}. */
+export type UseWorkflowRunsOptions = {
+    /** The client to read with. Defaults to one for the page's own agent. */
+    api?: WorkflowApi;
+    /** Most runs to return, newest first. The agent clamps its own ceiling. */
+    limit?: number;
+    /**
+     * Narrow to one correlation key — the `key` a run was started with.
+     *
+     * Omitted, the list is every recent run of the workflow, which is what an
+     * operator's page wants. A page showing "your" runs passes the key it started
+     * them with; there is no per-user filtering behind this, so the key IS the
+     * scoping mechanism.
+     */
+    key?: string;
+    /** Skip the read entirely — for a page that does not know its workflow yet. */
+    skip?: boolean;
+};
+/** What {@link useWorkflowRuns} reports. */
+export type UseWorkflowRunsResult<R = unknown> = {
+    /** The runs, newest first. Empty until the first read lands. */
+    runs: WorkflowRun<R>[];
+    /** True until the first read settles, and during an explicit refresh. */
+    loading: boolean;
+    /** The read's failure, alongside an empty list — which is why it exists. */
+    error: string | undefined;
+    /** Re-read now. Call it when a run this page started reaches a terminal status. */
+    refresh: () => void;
+};
+/**
+ * Read a workflow's recent runs.
+ *
+ * @typeParam R - The workflow's output type, so a completed run's `output` is
+ *   typed rather than `unknown`. Derive it with `WorkflowOutputOf`.
+ *
+ * @example
+ * ```tsx
+ * import { useWorkflowRuns } from "@alexkroman1/aai-ui";
+ *
+ * function History() {
+ *   const { runs } = useWorkflowRuns("transcribe", { limit: 10 });
+ *   return <ul>{runs.map((run) => <li key={run.runId}>{run.status}</li>)}</ul>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowRuns<R = unknown>(workflow: string | undefined, opts?: UseWorkflowRunsOptions): UseWorkflowRunsResult<R>;