@alexkroman1/aai-ui 0.12.2 → 0.13.0

package/dist/use-workflow-run-DdhWmbx-.js

@@ -0,0 +1,697 @@
+import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
+import { errorMessage } from "@alexkroman1/aai";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+import { createAgentClient, isTerminal, isTerminal as isTerminal$1, readEventStream } from "@alexkroman1/aai/workflow-api";
+//#region src/workflow-client.ts
+/**
+* Browser client for the workflow HTTP API (`aai/host/workflow-api.ts`).
+*
+* This is the whole client half of a WORKFLOW APP: an agent whose front door is
+* a form rather than a microphone (`workflowApp()`) starts runs
+* here and watches them for the answer. It deliberately does NOT go through
+* `BrowserSession` — there is no socket, no audio graph, and no session to resume.
+*
+* **The requests themselves are the SDK's now**
+* (`createWorkflowApiClient`, `@alexkroman1/aai/workflow-api`), and what is left
+* here is the one thing that is genuinely a BROWSER's: the default base URL.
+* Every route, every query, the 404-is-an-answer rule and the `wait` clamp were
+* written three times over — here, in the studio's Workflows card, and in
+* `aai workflow` — and the parts the copies disagreed on were exactly the ones a
+* reader cannot check by eye. The SDK module's doc carries that argument; this
+* file must not grow a second implementation of any of it.
+*
+* The one thing worth knowing before using it: **a run outlives the page.**
+* Starting one resolves as soon as the run is created, so `runId` is the only
+* handle that matters and it stays valid across a reload, a different device, or
+* `curl` — which is what makes `useWorkflowRun` a watch rather than a
+* subscription to something the page owns.
+*
+* The loop that keeps asking lives in `use-workflow-run.ts`, and the streaming
+* fast path under it in `workflow-events.ts`.
+*/
+/**
+* Create a client for the agent serving this page.
+*
+* **You usually do not need one.** Every hook and component here builds this
+* exact client lazily and once when no `api` is passed
+* (`_workflow-api-ref.ts`), so `useWorkflowSubmit("digest")` already talks to
+* the right agent. Reach for this when the client has to be DIFFERENT from that
+* default — another agent's `baseUrl`, or a `token` — or when a page wants
+* `config()` and the run calls on one object.
+*
+* If you do build one, hoist it out of the component that uses it.
+* `useWorkflowRun` holds the client in a ref precisely so a fresh object per
+* render does not restart its watch, but a client built in render is still a new
+* `fetch` closure every time and reads as though it were free.
+*
+* @example
+* ```tsx
+* import { createWorkflowApi, useWorkflowRun } from "@alexkroman1/aai-ui";
+* import { useState } from "react";
+*
+* // A DIFFERENT agent than the one serving this page, so the client is
+* // explicit — and module scope, not render scope, per above.
+* const api = createWorkflowApi({ baseUrl: "https://agents.example/digest" });
+*
+* function StartDigest() {
+*   const [runId, setRunId] = useState<string>();
+*   const { run } = useWorkflowRun(runId, { api });
+*   return (
+*     <button
+*       type="button"
+*       onClick={() => void api.start("digest", { url: "…" }).then(setRunId)}
+*     >
+*       {run ? run.status : "Start"}
+*     </button>
+*   );
+* }
+* ```
+*
+* @param options - See {@link WorkflowApiOptions}. Both fields are optional; the
+* default base URL is the page's own origin and path.
+* @returns Every workflow call plus `config()` and `baseUrl` — see
+* {@link AgentClient}. It was the narrow {@link WorkflowApi}, which left a page
+* that also wanted the agent's own name building a SECOND client (or a bare
+* `fetch` and a hand-written URL join) for one read; the SDK documents
+* `createAgentClient` as a superset of the same routes, so delegating to it
+* widens the return without a second implementation of anything.
+*
+* @public
+*/
+function createWorkflowApi(options = {}) {
+	return createAgentClient({
+		baseUrl: options.baseUrl ?? pageBaseUrl(),
+		...omitUndefined({ token: options.token })
+	});
+}
+//#endregion
+//#region src/_workflow-api-ref.ts
+/**
+* The client preamble every workflow hook needs, once.
+*
+* Five hooks (`useWorkflowRun`, `useWorkflowProgress`, `useWorkflowRuns`,
+* `useWorkflows`, `useWorkflowSubmit`) opened with the same two refs and the
+* same two paragraphs explaining them, and both halves are load-bearing rather
+* than stylistic — which is exactly why they should not be re-derived per hook:
+*
+* - **The caller's client lives in a REF, never in an effect's dependency
+*   array.** The natural call site is
+*   `useWorkflowRun(id, { api: createWorkflowApi() })`, which passes a NEW
+*   object every render; as a dependency that tears the effect down and
+*   restarts it on each one, and because a restart clears state and re-renders,
+*   it schedules the next. The result is an unbounded request loop against the
+*   agent — on the platform, against the BROKER — with `error` wiped before
+*   anything can read it, presenting as "the page polls forever" rather than as
+*   a mistake at the call site.
+* - **The no-client default is built lazily and ONCE.** As a render-time
+*   default (`api ?? createWorkflowApi()`) it is a fresh object per render,
+*   which is the same hazard one layer down; built inside an effect it is a
+*   fresh object per watch.
+*
+* The returned getter is stable for the life of the component and reads the ref
+* on every call, so a caller that SWAPS clients mid-watch — a token arriving
+* after login — is picked up by the next request without the watch restarting.
+*/
+/**
+* Resolve the client a workflow hook should use, now.
+*
+* @param api - The caller's client, or undefined for one aimed at the page's
+*   own agent.
+* @returns A stable getter. Call it per request, never once per watch.
+*
+* @internal
+*/
+function useWorkflowApiRef(api) {
+	const apiRef = useRef(api);
+	apiRef.current = api;
+	const fallbackRef = useRef(void 0);
+	return useCallback(() => {
+		const current = apiRef.current;
+		if (current) return current;
+		fallbackRef.current ??= createWorkflowApi();
+		return fallbackRef.current;
+	}, []);
+}
+//#endregion
+//#region src/_repeat-until.ts
+/**
+* A bounded read, re-armed from the SETTLED read — the loop both workflow
+* watchers are built out of.
+*
+* `pollUntilTerminal` (`use-workflow-run.ts`) and `readProgressUntilComplete`
+* (`use-workflow-progress.ts`) each open a request, decide from its answer
+* whether to come back, and stop when told to. What they had in common was not
+* the decision — one reads a snapshot, the other drains an SSE body — but the
+* scaffold around it, and that scaffold is where the two rules live:
+*
+* - **Re-armed from the settled read, never on an interval.** A slow response
+*   would otherwise stack overlapping requests on an agent that is already
+*   struggling, and on the platform every one of them BROKERS.
+* - **Cancellation is a signal, not a flag.** The teardown has to reach the
+*   in-flight request too — an abandoned progress read otherwise keeps pulling
+*   chunks out of a run for a page that has navigated away — so `step` is
+*   handed the signal rather than being trusted to check a boolean.
+*/
+/**
+* Call `step` until it reports it is finished, or until the returned stop
+* function is called.
+*
+* `step` resolves `true` when there is nothing left to come back for. It is
+* responsible for its own failures: a rejection would leave the loop stopped
+* with nobody told, so each caller decides whether its failure is terminal or
+* just another reason to try again.
+*
+* @internal
+*/
+function repeatUntil(intervalMs, step) {
+	const controller = new AbortController();
+	let timer;
+	const tick = async () => {
+		if (await step(controller.signal) || controller.signal.aborted) return;
+		timer = setTimeout(() => void tick(), intervalMs);
+	};
+	tick();
+	return () => {
+		controller.abort();
+		if (timer !== void 0) clearTimeout(timer);
+	};
+}
+//#endregion
+//#region src/use-workflow-progress.ts
+/**
+* `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.
+*
+* ## A FAILED read is not an absent route, whether or not it carried a status
+*
+* Because the loop stops for good once it decides the route is absent, that
+* decision is the one place a single bad request can cost a live run its entire
+* narration — and it did. Every non-2xx used to read as "this agent serves no
+* progress route", so one transient answer hid the log permanently while the run
+* carried on and the status line went on saying `running`. See
+* {@link isTransientRead} for the split and `readOnce` for what each arm costs.
+*/
+/**
+* How often a live run's progress is re-read once a bounded read has ended.
+*
+* **Five seconds, up from one, because narration is the cheapest thing on the
+* page and it was the most expensive thing on the wire.**
+*
+* On the platform every one of these reads BROKERS (see `useWorkflowRun`'s note
+* on the same hazard), and a page routinely mounts TWO of these hooks against one
+* run — `transcription-workflow` renders `<WorkflowProgress>` for the run's own
+* narration and `<LiveTranscript>` for the segments as they land. At one second
+* that is 2 requests/second from a single tab, which is exactly the platform's
+* whole per-IP surface budget (`WORKFLOW_IP_RATE_LIMIT`, 600 per 5 minutes) — so
+* one tab watching one run, with a history entry expanded, answers
+* `429 Too many workflow requests` partway through its own run.
+*
+* It is also contending for the link with the UPLOAD, which on this page is the
+* thing the reader is actually waiting for: a workflow app's whole wall clock is
+* bytes going out, and progress polling spends the same uplink to describe it.
+*
+* What five costs is that a line appears up to five seconds after the run wrote
+* it. That is the right trade for a log a person SKIMS while waiting minutes —
+* and it is not the run's completion, which arrives on `useWorkflowRun`'s event
+* stream (see {@link DEFAULT_WORKFLOW_POLL_MS}, deliberately left at two seconds
+* because it answers "is it done", not "what is it doing").
+*
+* A page that really wants a live feed passes `intervalMs` and owns the
+* consequence. That option is the authoring surface for this choice, which is why
+* this constant is `/internal` rather than public.
+*/
+const DEFAULT_PROGRESS_POLL_MS = 5e3;
+/**
+* Whether a non-2xx says "come back" rather than "there is nothing here".
+*
+* The 408/429/5xx split, and it is a THIRD copy of that rule stated
+* deliberately: the SDK's own `isTransientStatus` is on
+* `@alexkroman1/aai/step` and `RETRYABLE_STATUS` is `sdk/_upload-retry.ts`'s
+* internal, so neither is reachable from a browser bundle — this package may
+* not import the step surface, and an `_`-prefixed module may not be imported
+* cross-package at all. Hoisting one of them onto `/utils` (the SDK's
+* `/step` subpath is where `isTransientStatus` lives today) is the fix that would
+* delete this; it is a published-surface change and therefore not this one.
+*
+* Everything else is treated as a stable answer, which keeps a permanent
+* refusal — a 401 against an agent whose `AAI_WORKFLOW_API_TOKEN` this page has
+* no token for — from brokering a request every interval for as long as the tab
+* is open. A 404 is the specific case the route documents: an agent deployed
+* before progress streams existed, or one serving no workflow API at all.
+*/
+function isTransientRead(status) {
+	return status === 408 || status === 429 || status >= 500;
+}
+/**
+* Drain one bounded read's frames, reporting how it ended and everything it
+* carried.
+*
+* The chunks are RETURNED rather than handed over one at a time, and that is
+* what lets the hook commit a whole read in one React update: a per-chunk
+* callback re-rendered the page once per progress line and rebuilt the list
+* each time, which for a fan-out writing a line per segment is an O(n²) copy of
+* the log a reader can already only see one frame at a time. A read is bounded
+* by construction (see the module doc), so buffering one is bounded too.
+*/
+async function consumeFrames(body, signal) {
+	const chunks = [];
+	let ending = "partial";
+	for await (const frame of readEventStream(body, signal)) if (frame.event === "chunk") chunks.push(frame.data);
+	else if (frame.event === "done") ending = frame.data?.complete ? "complete" : "partial";
+	else if (frame.event === "missing") return {
+		ending: "complete",
+		chunks
+	};
+	return {
+		ending,
+		chunks
+	};
+}
+/**
+* Read one run's progress until it is complete, reporting each read's chunks.
+*
+* Module-level rather than inline in the hook, so the loop reads without React in
+* the way — the same split `useWorkflowRun` makes with `pollUntilTerminal`.
+*
+* Every re-open asks from an ABSOLUTE position past the last chunk read, so a
+* read only ever fetches what this reader has not seen. That is what keeps the
+* poll cheap: a quiet run answers with a bare `done` rather than the whole log
+* again.
+*
+* `next` is a COUNT of chunks consumed, and `startIndex` is an INCLUSIVE floor,
+* so the two are the same number and no adjustment sits between them. That
+* identity is the whole correctness argument here, and it is why the store's
+* 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/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
+*
+* "The last N lines" names no position a later read can resume from — the tail
+* it counts back from moves with every line the run writes. Carrying it meant a
+* re-open asking for everything from 0 and dropping `seen` chunks off the
+* FRONT, which is a different set entirely: a reader that opened at
+* `startIndex: -3` on a 10-line log holds lines 7-9, and its next read handed
+* over lines 3 onwards — four lines it never asked for, then the three it
+* already had, in that order. The dedupe the old comment claimed would need the
+* first read's absolute tail, which the reader never learned.
+*
+* So the first read is issued from 0 instead, and only its last N chunks are
+* handed over. The window the caller asked for is unchanged, and the reader now
+* knows exactly where it is — every read after it is the ordinary absolute case.
+* The cost is that the first read transfers the whole log, which is what the
+* DEFAULT (`startIndex: 0`, "replay everything") already does.
+*/
+function readProgressUntilComplete(getClient, runId, options, intervalMs, onChunks, onEnded) {
+	const start = options.startIndex ?? 0;
+	const tail = start < 0 ? -start : void 0;
+	let next = tail === void 0 ? start : 0;
+	let firstRead = true;
+	/** One bounded read. Resolves how it ended. */
+	const readOnce = async (signal) => {
+		const res = await getClient().streamOutput(runId, {
+			...omitUndefined({
+				namespace: options.namespace,
+				startIndex: next === 0 ? void 0 : next
+			}),
+			signal
+		});
+		if (!res.ok && isTransientRead(res.status)) return "partial";
+		if (!(res.ok && res.body)) return "unsupported";
+		const { ending, chunks } = await consumeFrames(res.body, signal);
+		next += chunks.length;
+		const fresh = firstRead && tail !== void 0 ? chunks.slice(-tail) : chunks;
+		firstRead = false;
+		if (fresh.length > 0 && !signal.aborted) onChunks(fresh);
+		return ending;
+	};
+	return repeatUntil(intervalMs, async (signal) => {
+		let ending;
+		try {
+			ending = await readOnce(signal);
+		} catch {
+			ending = "partial";
+		}
+		if (signal.aborted) return true;
+		if (ending === "partial") return false;
+		onEnded(ending);
+		return true;
+	});
+}
+/**
+* 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
+*/
+function useWorkflowProgress(runId, options = {}) {
+	const { api, namespace, startIndex, intervalMs = DEFAULT_PROGRESS_POLL_MS } = options;
+	const [progress, setProgress] = useState([]);
+	const [streaming, setStreaming] = useState(false);
+	const [supported, setSupported] = useState(true);
+	const getClient = useWorkflowApiRef(api);
+	useEffect(() => {
+		setProgress([]);
+		setSupported(true);
+		setStreaming(false);
+		if (!runId) return;
+		setStreaming(true);
+		const stop = readProgressUntilComplete(getClient, runId, {
+			namespace,
+			startIndex
+		}, intervalMs, (chunks) => setProgress((seen) => [...seen, ...chunks]), (ending) => {
+			setStreaming(false);
+			if (ending === "unsupported") setSupported(false);
+		});
+		return () => {
+			stop();
+			setStreaming(false);
+		};
+	}, [
+		runId,
+		namespace,
+		startIndex,
+		intervalMs,
+		getClient
+	]);
+	return {
+		progress,
+		latest: progress.at(-1),
+		streaming,
+		supported
+	};
+}
+//#endregion
+//#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();
+	const handOver = () => {
+		if (!controller.signal.aborted) 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 options - `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, options = {}) {
+	const { api, intervalMs = DEFAULT_WORKFLOW_POLL_MS } = options;
+	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 };