@alexkroman1/aai-ui 0.12.3 → 0.13.0

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

@@ -0,0 +1,137 @@
+/**
+ * `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.
+ */
+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.
+ *
+ * **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.
+ */
+export declare const DEFAULT_PROGRESS_POLL_MS = 5000;
+/**
+ * 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, options?: {
+    api?: WorkflowApi;
+    namespace?: string;
+    startIndex?: number;
+    intervalMs?: number;
+}): UseWorkflowProgressResult<T>;