@alexkroman1/aai-ui 0.12.3 → 0.14.0

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

@@ -0,0 +1,100 @@
+/**
+ * `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.
+ *
+ * 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
+ */
+export declare function useWorkflowRun<R = unknown>(runId: string | undefined, options?: {
+    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, options?: UseWorkflowRunsOptions): UseWorkflowRunsResult<R>;

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

@@ -0,0 +1,154 @@
+/**
+ * Starting a run BEFORE its file has finished uploading.
+ *
+ * `useWorkflowSubmit` (`use-workflow-form.ts`) stores every file and then starts the
+ * run, because a `POST /workflows/uploads` cannot answer with an id until the last
+ * byte is in — the store writes an ordinary upload's record last, so "incomplete"
+ * and "no such upload" are deliberately the same answer. For a long recording that
+ * order is most of the wall clock.
+ *
+ * This hook inverts it, and it takes ONE extra idea to do so: the id is the
+ * CLIENT's. It mints one, starts the run on it, and `PUT`s the whole file in a
+ * single streaming request; the upload record exists from the first byte with
+ * `complete: false` and its `size` grows, so the run reads whatever has arrived.
+ *
+ * ```text
+ *   start run ─┬──────────────────────────────────────────────► (still running)
+ *              │
+ *   PUT /uploads/<id>  ═══════════════════════════════════►  wake
+ *              (one request; the run polls `size` and `complete`)
+ * ```
+ *
+ * ## What it does NOT do, which is the point
+ *
+ * There is no cutting, no part numbering, no terminator and no per-part request. An
+ * earlier version of this hook took a `cut` callback and uploaded N parts into a
+ * "group" that a separate call had to seal; it worked, and every piece of it was
+ * something the caller had to get right. The whole of that is replaced by the store
+ * publishing `size` as bytes land — which `stepReadUpload` already clamped to — so the
+ * run does exactly what it does over a finished file and simply waits for windows to
+ * become present.
+ *
+ * It also means the FORMAT knowledge stays where it already was. Deciding where a
+ * recording may be divided is the run's business (`planSegments` in the
+ * transcription template), and nothing here needs to know it is audio at all.
+ *
+ * ## Three things it owns
+ *
+ * - **The id.** Minted here, put in the run input where the workflow's `uploads`
+ *   list says, and never seen by the page. It is a capability — anyone holding it
+ *   can read the bytes back — so it is a `crypto.randomUUID()` rather than anything
+ *   derived from the file, and the store refuses a second `PUT` to it.
+ * - **The wake after the upload.** `POST /workflows/runs/:id/wake` ends a pending
+ *   `sleep`, and a run waiting on an upload is asleep between polls — so without
+ *   this it learns the file is complete up to a poll interval late, every time. On
+ *   the transcription template's 5-second interval that is most of the tail it has
+ *   left to pay. Best-effort, because a wake that finds nothing sleeping answers 0
+ *   and a missed one costs latency rather than correctness.
+ * - **Reporting the bytes.** The same `UploadStatus` `useWorkflowSubmit` reports,
+ *   so `<UploadProgressBar>` renders either without knowing which hook it came from.
+ *
+ * ## A failed upload is RESUMED, and only a spent budget cancels the run
+ *
+ * An upload that dies stays in the store, incomplete, and `complete` never becomes
+ * true — so a run left behind polls until its own abandonment bound and then fails,
+ * minutes after the page has already reported the error.
+ *
+ * That used to be the whole story, and it threw away a run and a file together for
+ * what is usually one dropped connection near the end. **The resume lives in the
+ * SDK now** (`aai/sdk/_upload-resume.ts`): a round that fails for a reason that
+ * looks like an outage is re-entered with `resume: true`, sending only the windows
+ * the store does not already have, on a budget sized to outlast a redeploy. The run
+ * is still waiting on the same id, so a resume that succeeds is invisible to it.
+ *
+ * This hook used to hand-roll one such retry and no longer does — one resume with
+ * no wait in front of it covers a dropped connection and cannot cover the case that
+ * actually strands people, which is the agent restarting underneath the upload.
+ * Cancelling the run is what happens when the whole budget is spent, and it is the
+ * honest end to a submission that did not happen.
+ *
+ * ## Pausing is the same mechanism, asked for
+ *
+ * `pauseUpload()` aborts the bytes in flight and holds the uploader;
+ * `resumeUpload()` sends what is missing. The store cannot tell that from an
+ * outage, because there is nothing to tell apart — see `upload/session.ts`. The
+ * RUN is untouched either way: it goes on polling the id it was started with, and
+ * `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}.
+ *
+ * {@link UseWorkflowSubmitOptions} without `wait`, which is the synchronous
+ * mode: it holds the `POST` open until the run settles, and here the run is
+ * started before its bytes are, so there is nothing left to hold it for.
+ *
+ * Without `recover` either, and REFUSED rather than ignored: an option a hook
+ * accepts and does nothing with is the silent-no-op failure this repo keeps
+ * paying for. Adopting an earlier run by key would hand this hook a run whose
+ * input names an upload id it did not mint and is not filling — so the run
+ * 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 — 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
+ * the file is readable — that number is the CONTIGUOUS prefix, so a run reading
+ * ahead of the uplink sees the same growing file whether one connection or four
+ * are filling it. What changes is only how fast it grows.
+ */
+export type UseWorkflowStreamOptions = Omit<UseWorkflowSubmitOptions, "wait" | "recover">;
+/**
+ * What {@link useWorkflowStream} returns: a {@link WorkflowSubmission}, exactly.
+ *
+ * The same eight fields `useWorkflowSubmit` returns, of which this hook is a
+ * drop-in sibling — same `<Form>`, same `<UploadProgressBar>`, same
+ * `<WorkflowProgress>`. An ALIAS rather than a second declaration of the eight:
+ * the two have to agree field for field to be drop-in, and two copies of a type
+ * that have to agree are two copies that can stop agreeing.
+ *
+ * Exactly two of the fields mean something different here, and both differences
+ * follow from WHEN the run is created — it exists before its bytes do:
+ *
+ * - `submit()` resolves when the UPLOAD finishes, not when the run is accepted;
+ *   the run's own progress arrives through `run`. It still resolves rather than
+ *   rejecting on a failed upload — the failure is reported through `error`, the
+ *   way a form expects.
+ * - `run` is set from the moment the run EXISTS, which here is before the bytes
+ *   are in. That is what lets a page render `<WorkflowProgress>` beside the
+ *   upload bar rather than after it.
+ */
+export type WorkflowStreamSubmission<R = unknown, I = unknown> = WorkflowSubmission<R, I>;
+/**
+ * Start a workflow run and stream a file into it while it works.
+ *
+ * The workflow declares which input property carries the upload
+ * (`workflow({ uploads: ["recording"] })`) — the same declaration
+ * `useWorkflowSubmit` reads, because what the property carries is an upload id
+ * either way. What differs is only WHEN the id becomes valid.
+ *
+ * @typeParam R - The workflow's output type, which is what makes
+ *   `run.status === "completed"` narrow to a typed `run.output`. Derive it with
+ *   `WorkflowOutputOf<typeof myWorkflow>`.
+ *
+ * @example
+ * ```tsx no-check
+ * const { submit, run, upload, pending, error } = useWorkflowStream("transcribe");
+ *
+ * <Form onSubmit={(values) => submit(values)} error={error}>
+ *   <WorkflowFields workflow="transcribe" />
+ *   <UploadProgressBar upload={upload} />
+ *   <SubmitButton pending={pending}>Transcribe</SubmitButton>
+ * </Form>
+ * ```
+ *
+ * @public
+ */
+export declare function useWorkflowStream<D extends AnyWorkflowDef>(workflow: string, options?: UseWorkflowStreamOptions): WorkflowStreamSubmission<WorkflowOutputOf<D>, SubmitInputOf<D>>;

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 options - See {@link UseWorkflowsOptions}.
+ * @returns The listing, its loading flag and its failure — see
+ * {@link UseWorkflowsResult}.
+ *
+ * @public
+ */
+export declare function useWorkflows(options?: UseWorkflowsOptions): UseWorkflowsResult;

package/dist/workflow-client.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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`.
+ */
+import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
+import { type AgentClient } from "@alexkroman1/aai/workflow-api";
+/**
+ * A run's observable state.
+ *
+ * Aliased from the SDK rather than restated. `import type` is erased entirely,
+ * so a second definition of the fields and the five-member status union would
+ * buy nothing and cost the one thing that matters — nothing would assert the two
+ * agree, so a status added to the SDK would never reach the browser type.
+ *
+ * `WorkflowRun` keeps the shorter name because it is what a page's own code
+ * writes; nothing in a browser needs the word "snapshot" to know a read returns
+ * one.
+ *
+ * It is GENERIC on the run's output, and a page supplies it — see
+ * {@link useWorkflowRun}. It does NOT have to restate that type: a page can name
+ * its own workflow and derive the rest with `WorkflowOutputOf`, pulling no
+ * server graph into the bundle.
+ *
+ * @public
+ */
+export type WorkflowRun<R = unknown> = WorkflowRunSnapshot<R>;
+/**
+ * A workflow's own output type, and the shape `GET /workflows` lists — both
+ * re-exported so a page needs ONE import to type its runs and render its form.
+ */
+/**
+ * The workflow half of what {@link createWorkflowApi} returns — every hook here
+ * takes it, because a run is all a hook needs.
+ *
+ * Re-exported from the SDK rather than declared here: it IS the SDK's client,
+ * and a structural restatement would be a second thing to keep in step with the
+ * routes for no gain.
+ */
+export type { AgentClient, WorkflowApi, WorkflowInputOf, WorkflowOutputOf, WorkflowRunStatus, WorkflowSummary, } from "@alexkroman1/aai/workflow-api";
+/**
+ * A run status nothing will change again.
+ *
+ * Re-exported from the SDK rather than defined here. A second implementation
+ * listing two of the three terminal statuses would leave a cancelled run polled
+ * forever by a page while the agent considered it finished — the kind of drift a
+ * status predicate beside the status union cannot have.
+ */
+export { isTerminal } from "@alexkroman1/aai/workflow-api";
+export type WorkflowApiOptions = {
+    /**
+     * Base URL of the agent. Defaults to the page's own origin + path, which is
+     * right for a page the agent itself serves — the only case that exists today,
+     * and the reason this wrapper exists at all: the SDK client requires a base
+     * URL, because `location` does not exist in that half of the SDK.
+     */
+    baseUrl?: string;
+    /**
+     * Bearer for an agent whose operator set `AAI_WORKFLOW_API_TOKEN`. A page
+     * served to the public has nothing to put here (and should not — it would be
+     * readable in the bundle); this exists for a programmatic caller written
+     * against the same client.
+     */
+    token?: string;
+};
+/**
+ * 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
+ */
+export declare function createWorkflowApi(options?: WorkflowApiOptions): AgentClient;

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/dist/workflow-events.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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
+ */
+import type { WorkflowApi, WorkflowRun } from "./workflow-client.ts";
+/**
+ * The slice of the client this needs: one method.
+ *
+ * Narrowed rather than taking the whole `WorkflowApi`, and the narrowing is the
+ * honest statement — nothing here reads a run, starts one, or cancels one, it
+ * opens ONE stream. It also makes a test double a plain object rather than a
+ * six-method stub cast into shape. A real client satisfies it structurally.
+ */
+export type RunWatcher = Pick<WorkflowApi, "watch">;
+/**
+ * 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.
+ */
+export declare function watchRunEvents<R>(getClient: () => RunWatcher, runId: string, onRun: (run: WorkflowRun<R>) => void, onSettled: () => void, onFallback: () => void): () => void;