@lotics/ui 44.9.1 → 44.10.0

package/docs/ai_patterns.md

@@ -464,12 +464,21 @@ Reach for it whenever an agent run happens inside a dialog — which is nearly a
 const run = useAgentRun("intake");            // @lotics/app-sdk
 <AgentRunScope>                                {/* wraps the Dialog, like ClarifyWizardScope */}
   <Dialog …>
-    <AgentRunPane run={run} onCancel={back} />                              {/* content */}
+    <AgentRunPane run={run} onCancel={back} onLanding={landed} />           {/* content */}
     <DialogFooter><AgentRunActions run={run} onStop={back} /></DialogFooter> {/* actions */}
   </Dialog>
 </AgentRunScope>
 ```
 
+**Pass `onLanding` if the run's RESULT drives anything.** The pane owns the `answerChoice` call, so
+after a question it is the only thing holding how the answered leg ended — your own `run()` promise
+already resolved, with `parked`, and never resolves again. Give `onLanding` the same handler you
+give `run()`: it is typed from your run (no cast), and it re-fires if answering leads to a follow-up
+ask. Omit it and an answered run completes with the host none the wiser — the transcript reads
+"done", your review step never opens, and the paid read is discarded. A host that instead reads its
+result off `status`/`output` does not need it, but is then re-deriving from a render what it was
+handed directly.
+
 **The parked question REPLACES the feed — that is the contract, not a style.** The run is blocked
 on the answer, so the question is the only thing to act on; it gets the dialog's own scroller and
 its actions sit outside it. Stacked under the transcript in an unscrollable box — the arrangement

package/docs/catalog.md

@@ -2144,7 +2144,10 @@ component rather than showing it at zero.
   works and, the moment it asks, renders the question IN PLACE OF the feed — in the dialog's own
   scroller, with the wizard's verbs pinned in the `DialogFooter` via `AgentRunActions`. Replacing
   rather than stacking is the CONTRACT: stacked under the transcript a multi-question ask clips
-  its own Submit and strands a live `awaiting_input` run. `run` is a structural shape
+  its own Submit and strands a live `awaiting_input` run. `onLanding` hands back how the ANSWERED
+  leg ended — the pane makes that call, so without it the continuation's outcome is lost and a host
+  waiting on its own `run()` promise waits forever (that promise already resolved `parked`). A
+  refused answer keeps the question up and shows why, rather than a dead Submit. `run` is a structural shape
   (`AgentRunLike`), so `useAgentRun()` satisfies it with no `@lotics/app-sdk` dependency and a
   mock satisfies it with no backend — `AgentRunQuestion` names the question shape so a template
   or test DECLARES one rather than mapping from `ClarifyWizardQuestion` (an option is a label +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "44.9.1",
+  "version": "44.10.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/agent_run_pane.tsx

@@ -1,7 +1,8 @@
-import { useCallback, useMemo, type ReactNode } from "react";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { AgentRun, type AgentRunProps } from "./agent_run";
 import { Button } from "./button";
+import { Text } from "./text";
 import { useLoticsLocale } from "./locale";
 import type { AgentUIPart } from "./agent_transform";
 import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer } from "./clarify_wizard";
@@ -31,12 +32,20 @@ export interface AgentRunQuestion {
   allow_custom?: boolean;
 }
 
-export interface AgentRunLike {
+export interface AgentRunLike<TLanding = unknown> {
   status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
   parts: readonly AgentUIPart[];
   /** Non-null exactly while parked. */
   pendingChoice: { questions: AgentRunQuestion[] } | null;
-  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<unknown>;
+  /**
+   * GENERIC in what it resolves, and that is the whole point of the parameter.
+   * A run leg reports HOW it ended — settled with an output, parked again on a
+   * follow-up, failed, aborted — and this pane is the thing that calls it, so it
+   * is the only thing holding that answer. Naming the type would mean importing
+   * `@lotics/app-sdk` and breaking the one-way boundary above; inferring it from
+   * the caller's own run costs nothing and hands `onLanding` back fully typed.
+   */
+  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<TLanding>;
   /**
    * STOP the run — server-side, not just locally. `useAgentRun().cancel` is
    * exactly this; do NOT pass its `abort`, which detaches the listener and
@@ -61,12 +70,30 @@ export function AgentRunScope({ children }: { children: ReactNode }) {
   return <ClarifyWizardScope>{children}</ClarifyWizardScope>;
 }
 
-export interface AgentRunPaneProps {
-  run: AgentRunLike;
+export interface AgentRunPaneProps<TLanding = unknown> {
+  run: AgentRunLike<TLanding>;
   labelForCall?: AgentRunProps["labelForCall"];
   renderToolOutput?: AgentRunProps["renderToolOutput"];
   /** Abandon a parked question — the run is left for the operator to retry. */
   onCancel: () => void;
+  /**
+   * How the ANSWERED leg ended. Required for correctness in any host that acts
+   * on a run's result, because this pane owns the `answerChoice` call and the
+   * caller's own `run()` promise already resolved — with `parked` — and will
+   * never resolve again.
+   *
+   * Without it the continuation's outcome had nowhere to go: the pane discarded
+   * it, and a host that had been told a landing is how you learn an outcome sat
+   * on a finished transcript with nothing to advance to. That shipped, and cost
+   * a paid extraction every time an agent asked a question.
+   *
+   * Re-fires for a follow-up ask: answering can land `parked` again.
+   *
+   * A host reading its result off hook state instead does not need this — but it
+   * is then re-deriving from a render what it was handed directly, which is the
+   * pattern the landing union exists to retire.
+   */
+  onLanding?: (landing: TLanding) => void;
 }
 
 /**
@@ -80,8 +107,9 @@ export interface AgentRunPaneProps {
  * dialog's height and clipped its own Submit. Every app rebuilt this arrangement
  * by hand and it only had to be got wrong once.
  */
-export function AgentRunPane(props: AgentRunPaneProps) {
-  const { run, labelForCall, renderToolOutput, onCancel } = props;
+export function AgentRunPane<TLanding>(props: AgentRunPaneProps<TLanding>) {
+  const { run, labelForCall, renderToolOutput, onCancel, onLanding } = props;
+  const loc = useLoticsLocale().agentRun;
   // The DIALOG's gutter, not this pane's own container measurement. Asking
   // `useContainerSize()` here answered "small" for a 760px dialog while the
   // header, scroll area and footer asked the SCREEN and answered "not small" —
@@ -101,17 +129,35 @@ export function AgentRunPane(props: AgentRunPaneProps) {
       })),
     [pending],
   );
+  // A REFUSED answer (400 invalid, 409 raced cancel) leaves the run parked and
+  // still answerable, so the wizard stays up and the reason goes above it. It
+  // used to be a bare `void`, which made that an unhandled rejection: the button
+  // did nothing, the question stayed, and nothing said why.
+  const [answerError, setAnswerError] = useState<string | null>(null);
   const submit = useCallback(
     (answers: ClarifyWizardAnswer[]) => {
-      void run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom })));
+      setAnswerError(null);
+      run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom }))).then(
+        (landing) => onLanding?.(landing),
+        // A rejection is always an `Error` on the SDK's path, but a promise can
+        // carry anything, so the fallback is the localized label rather than
+        // whatever `String()` makes of a non-Error — "[object Object]" is not a
+        // thing to show an operator who is mid-answer.
+        (e: unknown) => setAnswerError(e instanceof Error ? e.message : loc.error),
+      );
     },
-    [run],
+    [run, onLanding, loc],
   );
 
   if (pending) {
     return (
       <DialogScrollArea>
-        <View style={{ paddingVertical: 4 }}>
+        <View style={{ paddingVertical: 4, gap: 8 }}>
+          {answerError !== null ? (
+            <Text size="sm" color="danger">
+              {answerError}
+            </Text>
+          ) : null}
           <ClarifyWizard questions={questions} onSubmit={submit} onCancel={onCancel} />
         </View>
       </DialogScrollArea>