@alexkroman1/aai-ui 9.1.0 → 10.0.0

package/README.md

@@ -22,7 +22,7 @@ still React, still the same theme tokens.
 `client()` mounts the default chat shell with your sidebar, or replaces the
 whole UI with a custom component:
 
-```tsx no-check
+```tsx
 import "@alexkroman1/aai-ui/styles.css";
 import { client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
 

package/dist/_recover-run.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Finding a run again when the page has lost its id.
+ *
+ * A run is durable and a page is not — which `useWorkflowRun`'s doc says, and
+ * which was only half true of the hooks above it: the run id lived in plain
+ * `useState`, so a refresh (or a same-tab navigation, or a crashed tab) left a
+ * live run with nothing anywhere able to name it. The run really did continue;
+ * the person really could not get back to it.
+ *
+ * `StartOptions.key` is the handle that survives that, and it always was — a
+ * caller's own name for a run, indexed by the agent, read back with
+ * `find(workflow, key)`. What was missing is the two lines that ASK. This is
+ * them, plus the four decisions they turn out to carry.
+ *
+ * ## It is a MOUNT-time act, not "whenever there is no run"
+ *
+ * The tempting spelling is "if we hold no run id, look one up", and it breaks
+ * `reset()`: a form put back to its initial state holds no run id, so the next
+ * pass would re-adopt the very run the person had just dismissed — a Clear
+ * button that clears nothing. So the lookup runs once per mount (and again only
+ * if the KEY changes, which is a different person's run), and every later
+ * absence of a run id is taken at face value.
+ *
+ * ## The lookup NEVER wins a race against a submit
+ *
+ * A person who reloads and immediately submits has started the run they want,
+ * and an answer that was already in flight names an older one. The caller
+ * therefore adopts through `current ?? found`: the recovered id fills an empty
+ * slot and never replaces a full one.
+ *
+ * ## A failed lookup is REPORTED
+ *
+ * The alternative is a page that quietly shows an empty form to somebody whose
+ * run is live, who then starts a second one — the duplicated work the key
+ * exists to prevent, and on a workflow app that is real money. A person who has
+ * never run anything pays a banner they can ignore. Same trade as
+ * `useWorkflows`, for the same reason: an empty answer here is a confident
+ * false statement.
+ *
+ * ## It is OPT-IN
+ *
+ * A `key` on its own still means only "record this with the run", which is what
+ * a voice agent's `ctx.workflows.start({ key })` means and what a page passing
+ * an account id may well want. Adopting a run is a decision about the PAGE, so
+ * it is `recover: true` and the two together read as what they do.
+ */
+import type { WorkflowApi } from "./workflow-client.ts";
+/** What {@link useRecoveredRun} needs. */
+export type RecoverRunOptions = {
+    /** The workflow whose runs are indexed under `key`. */
+    workflow: string;
+    /** The caller's handle on its own run, or undefined for a page with none. */
+    key: string | undefined;
+    /** Whether the caller asked for this at all — `recover` at the call site. */
+    enabled: boolean;
+    /** The stable getter from `useWorkflowApiRef`. */
+    getClient: () => WorkflowApi;
+    /** Adopt this run. Called at most once, and never with an empty answer. */
+    onFound: (runId: string) => void;
+    /** The lookup failed, and the page has to say so. */
+    onError: (message: string) => void;
+};
+/**
+ * Look up the newest run for a key, once, as the component mounts.
+ *
+ * @param opts - See {@link RecoverRunOptions}.
+ * @returns Whether the lookup is still out. A caller folds it into its own
+ *   `pending`, because a form offering Submit while a live run is arriving is a
+ *   form inviting a second one.
+ *
+ * @internal
+ */
+export declare function useRecoveredRun(opts: RecoverRunOptions): boolean;