@lotics/app-sdk 0.61.1 → 0.62.0

package/AGENTS.md

@@ -21,7 +21,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
 | [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions`, `useViewer`, `useComments`, and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
-| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`** (`run_app_query` / `run_app_workflow`); the raw record read/write tools are rejected. |
+| [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics, auto query-refetch on chat mutation). **A `file` input carries its own content** — images/PDFs are perceived natively, Word/Excel/CSV/text are materialized into the run; no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`** (`run_app_query` / `run_app_workflow`); the raw record read/write tools are rejected., a leg's `AgentRunLanding` (`settled`/`parked`/`failed`/`aborted` — never a bare `undefined`) |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |
 | [docs/runtime.md](./docs/runtime.md) | `mount()`, the two transports, `rpc()`, `openExternal`/`downloadFile`, geofencing, analytics, `useConfig` (App-Packages installation config), `getAppBinding` (package apps' runtime `F`/`OPT`/`ROLE` resolution via the generated `.lotics/app_fields.ts`), and the publish chain for package contributors. |
 

package/dist/src/agent_stream.d.ts

@@ -145,4 +145,56 @@ export declare function parseSseChunks(buffer: string): {
     chunks: Chunk[];
     rest: string;
 };
+/**
+ * How one run LEG ended — the whole answer, in the resolved value.
+ *
+ * A leg used to resolve `TOutput | undefined`, and `undefined` meant three
+ * different things: the run parked on a question, the run died, or the client
+ * stopped listening. Telling them apart needed the hook's state, which has not
+ * committed yet when the promise resolves — so every consumer raced, and none
+ * could win. Minh Tín's app lost live `awaiting_input` runs to exactly that: the
+ * dialog closed over a healthy, answerable row and the run expired on its TTL.
+ *
+ * Discriminating here makes the race unrepresentable rather than guarded. A run
+ * FAILURE is data (`failed`) — the caller needs no try/catch for it.
+ *
+ * The promise still REJECTS for the two cases that are not run outcomes at all:
+ * API misuse (`answerChoice` with nothing pending), and a refused answer (400
+ * invalid / 409 raced cancel), where the run stays PARKED and answerable — a
+ * landing there would report `parked` and swallow the reason the answer bounced.
+ */
+export type AgentRunLanding<TOutput> = 
+/** The leg finished. `output` is the structured result (absent for a free-text
+ *  agent, where `text` is the result). */
+{
+    kind: "settled";
+    output?: TOutput;
+    text: string;
+}
+/** Parked on a question. `pendingChoice` carries it and `answerChoice`
+ *  continues — there is nothing for the caller to do here, which is the point:
+ *  it is no longer indistinguishable from a dead run. */
+ | {
+    kind: "parked";
+}
+/** The run failed and its error is user-facing. */
+ | {
+    kind: "failed";
+    error: string;
+}
+/** The CLIENT stopped listening (`abort`, unmount, a newer run replacing this
+ *  one). The run itself keeps executing server-side and lands in the session
+ *  history — never surface this as a failure. */
+ | {
+    kind: "aborted";
+};
+/** The client stopped listening; the run itself continues server-side. Shared so
+ *  the four exit points cannot drift, and so the literal keeps its type. */
+export declare const ABORTED: AgentRunLanding<never>;
+/** All prose parts concatenated — a free-text agent's actual result. Shared so
+ *  the hook's `text` and a landing's can never disagree about what was said. */
+export declare function proseOf(parts: readonly AgentUIPart[]): string;
+/** The landing a settled accumulator describes. One place decides, so `run` and
+ *  `answerChoice` can never disagree about what an outcome was called. */
+export declare function landingOf(state: AgentRunState): AgentRunLanding<unknown>;
 export {};

package/dist/src/agent_stream.js

@@ -283,3 +283,32 @@ export function parseSseChunks(buffer) {
     }
     return { chunks, rest };
 }
+/** The client stopped listening; the run itself continues server-side. Shared so
+ *  the four exit points cannot drift, and so the literal keeps its type. */
+export const ABORTED = { kind: "aborted" };
+/** All prose parts concatenated — a free-text agent's actual result. Shared so
+ *  the hook's `text` and a landing's can never disagree about what was said. */
+export function proseOf(parts) {
+    return parts.reduce((acc, p) => (p.type === "text" ? acc + p.text : acc), "");
+}
+/** The landing a settled accumulator describes. One place decides, so `run` and
+ *  `answerChoice` can never disagree about what an outcome was called. */
+export function landingOf(state) {
+    switch (state.status) {
+        case "awaiting_input":
+            return { kind: "parked" };
+        case "error":
+            return { kind: "failed", error: state.error ?? "The run failed." };
+        case "completed":
+            return { kind: "settled", output: state.output, text: proseOf(state.parts) };
+        case "streaming":
+            // A leg that is still streaming has not landed. Every internal caller has
+            // already resolved this state — by polling the persisted row — before
+            // asking, so this branch is unreachable there. It is named rather than
+            // left to a fallthrough because the fallthrough answered "settled", which
+            // would report a live run as finished and hand a consumer a partial
+            // `output` as if it were the result. Unconfirmed is the truthful answer,
+            // and it matches what the poll path says for the same situation.
+            return { kind: "failed", error: "The run has not finished — its result cannot be confirmed yet." };
+    }
+}

package/dist/src/hooks.d.ts

@@ -1,10 +1,10 @@
 import { type ImageFidelity } from "./upload/optimize.js";
 import { type AiContextValue } from "./rpc.js";
-import { type AgentUIPart, type PendingChoice } from "./agent_stream.js";
+import { type AgentUIPart, type PendingChoice, type AgentRunLanding } from "./agent_stream.js";
 import type { AppWorkflows, AppWorkflowResults, AppQueries, AppAgents, AppAgentResults } from "./types.js";
 import type { ResolvedMember } from "./members.js";
 import type { ResolvedOption } from "./select.js";
-export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput } from "./agent_stream.js";
+export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, AgentRunLanding } from "./agent_stream.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
@@ -472,10 +472,12 @@ export interface AgentRunOptions {
 }
 /** The live state + controls returned by `useAgentRun`. */
 export interface UseAgentRun<TInput, TOutput> {
-    /** Start a run — streams progress into this hook's state and resolves to the
-     *  structured output (undefined for a free-text or failed run). Calling again
-     *  aborts any run still in flight. */
-    run: (input: TInput, opts: AgentRunOptions) => Promise<TOutput | undefined>;
+    /** Start a run — streams progress into this hook's state and resolves with how
+     *  the leg ENDED (`settled` / `parked` / `failed` / `aborted`). Read `kind`
+     *  rather than the hook's state: this value is a snapshot at settle, whereas
+     *  the state has not committed yet when the promise resolves. SINGLE-FLIGHT —
+     *  a second call while one is streaming joins the first (see `replace`). */
+    run: (input: TInput, opts: AgentRunOptions) => Promise<AgentRunLanding<TOutput>>;
     /** Stop listening locally (no server effect) — the run keeps executing
      *  server-side and its result lands in the session history. Used on unmount. */
     abort: () => void;
@@ -497,12 +499,13 @@ export interface UseAgentRun<TInput, TOutput> {
     /** Answer the pending ask and CONTINUE the run — one `{value, custom}` per
      *  question, aligned by index (exactly what `ClarifyWizard`'s `onSubmit`
      *  yields). Streams the continuation into the same `parts` and resolves like
-     *  `run` (the structured output, or `undefined`). Rejects when nothing is
-     *  pending. */
+     *  `run` — a landing, which may be `parked` again for a follow-up ask. Rejects
+     *  when nothing is pending, or when the server refuses the answer (the run
+     *  stays parked; show the error and keep the wizard open). */
     answerChoice: (answers: {
         value: string;
         custom: boolean;
-    }[]) => Promise<TOutput | undefined>;
+    }[]) => Promise<AgentRunLanding<TOutput>>;
     /** The agent's ANSWER prose (every `text` part concatenated), accumulating live —
      *  excludes thinking (`reasoning` is its own part). For a FREE-TEXT agent this IS
      *  the result; a structured agent's result is `output`. Derived from `parts`. */

package/dist/src/hooks.js

@@ -20,7 +20,7 @@ import { DEFAULT_IMAGE_FIDELITY } from "./upload/optimize.js";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
 import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
-import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, } from "./agent_stream.js";
+import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
 import { getMockRows, hasMockFlag } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
 export { buildChoiceOutput } from "./agent_stream.js";
@@ -536,7 +536,7 @@ export function useAgentRun(alias) {
         return handle.done
             .then(async () => {
             if (aborted)
-                return undefined;
+                return ABORTED;
             // A clean stream end WITHOUT a `finish` frame is a truncation, not a
             // completion — an edge can close a long SSE gracefully mid-run (seen
             // in production on ~2-minute runs), swallowing the frames that carry
@@ -551,7 +551,7 @@ export function useAgentRun(alias) {
                     ? await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current)
                     : null;
                 if (aborted)
-                    return undefined;
+                    return ABORTED;
                 // No settled row after the full poll window means the run's status
                 // could NOT be confirmed (an orphan the server's reaper hasn't
                 // repaired yet, or no run id ever arrived) — that is an error, never
@@ -574,11 +574,11 @@ export function useAgentRun(alias) {
                     has_output: acc.output !== undefined,
                 });
             }
-            return acc.output;
+            return landingOf(acc);
         })
             .catch(async (err) => {
             if (aborted)
-                return undefined;
+                return ABORTED;
             // The continue request itself was rejected — the server never resumed
             // the run (400 invalid answer, 409 raced cancel/expiry, network at
             // connect). Restore the pre-answer parked state and surface the error;
@@ -594,7 +594,7 @@ export function useAgentRun(alias) {
             if (runId) {
                 const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
                 if (aborted)
-                    return undefined;
+                    return ABORTED;
                 if (settled) {
                     acc = adoptGuarded(acc, settled);
                     safeSetState(acc);
@@ -610,11 +610,14 @@ export function useAgentRun(alias) {
                     has_output: acc.output !== undefined,
                 });
                 if (settled)
-                    return acc.output;
+                    return landingOf(acc);
             }
+            // A run failure is DATA — the landing carries it, so no consumer needs
+            // try/catch to tell "the run died" from "the run parked". Only API
+            // MISUSE still rejects (answering when nothing is pending).
             acc = { ...acc, status: "error", error: err.message };
             safeSetState(acc);
-            throw err;
+            return landingOf(acc);
         });
     }, [safeSetState]);
     const run = useCallback((input, opts) => {
@@ -679,7 +682,7 @@ export function useAgentRun(alias) {
     // `parts` is the source of truth; `text` (all prose concatenated) is the derived
     // answer view.
     const parts = state?.parts ?? EMPTY_PARTS;
-    const text = useMemo(() => parts.reduce((acc, p) => (p.type === "text" ? acc + p.text : acc), ""), [parts]);
+    const text = useMemo(() => proseOf(parts), [parts]);
     return {
         run,
         abort,

package/docs/ai.md

@@ -56,12 +56,12 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 
 | Member | Type | What it is |
 |---|---|---|
-| `run` | `(input, { sessionId, replace? }) => Promise<TOutput \| undefined>` | Start a run. Streams progress into the hook's state and resolves to the structured output (`undefined` for a free-text or failed run). **Single-flight:** while a run is in flight, calling it again returns the in-flight run's promise — an accidental double-press joins the first run instead of billing a second one (each dedup emits the `app_agent_run_deduped` analytics event). Pass `replace: true` to deliberately abort-and-restart; the replaced run still executes and bills server-side |
+| `run` | `(input, { sessionId, replace? }) => Promise<AgentRunLanding<TOutput>>` | Start a run. Streams progress into the hook's state and resolves with **how the leg ended** — `{kind:"settled", output?, text}`, `{kind:"parked"}`, `{kind:"failed", error}` or `{kind:"aborted"}`. Switch on `kind`; do NOT read the hook's state to tell them apart, because it has not committed when the promise resolves (that race closed dialogs over live, answerable runs). A run failure is DATA here, so no try/catch is needed for it. **Single-flight:** while a run is in flight, calling it again returns the in-flight run's promise — an accidental double-press joins the first run instead of billing a second one (each dedup emits the `app_agent_run_deduped` analytics event). Pass `replace: true` to deliberately abort-and-restart; the replaced run still executes and bills server-side |
 | `cancel` | `() => void` | Stop the run **server-side** (saves tokens) and locally. Wire a user-facing Stop button to this |
 | `abort` | `() => void` | Stop listening **locally only** — the run keeps executing server-side and its result is still persisted. This is the unmount path (the hook calls it automatically on unmount) |
 | `status` | `"idle" \| "streaming" \| "awaiting_input" \| "completed" \| "error"` | Whole-run state. `awaiting_input` = the run is PARKED on a question the agent asked (see the ask-back section below). `abort`/`cancel` reset it to `"idle"` (and clear the partial transcript) |
 | `pendingChoice` | `PendingChoice \| null` | The agent's pending question(s) — non-null exactly while `status` is `awaiting_input`. `questions` maps 1:1 onto `@lotics/ui`'s `ClarifyWizard` (`{question, options: {label, description}[], allow_custom}`) |
-| `answerChoice` | `(answers: {value, custom}[]) => Promise<TOutput \| undefined>` | Answer the pending question(s) and CONTINUE the run — one entry per question, aligned by index (exactly what `ClarifyWizard`'s `onSubmit` yields). Streams the continuation into the same `parts`; resolves like `run`. Rejects when nothing is pending — and when the server refuses the answer, in which case the pending question is restored for a retry |
+| `answerChoice` | `(answers: {value, custom}[]) => Promise<AgentRunLanding<TOutput>>` | Answer the pending question(s) and CONTINUE the run — one entry per question, aligned by index (exactly what `ClarifyWizard`'s `onSubmit` yields). Streams the continuation into the same `parts`; resolves like `run`. Rejects when nothing is pending — and when the server refuses the answer, in which case the pending question is restored for a retry |
 | `parts` | `AgentUIPart[]` | The ordered live transcript as **ai-sdk `UIMessage.parts`** — answer prose, thinking, and tool calls, in stream order. The single source of truth for the feed; hand it straight to `@lotics/ui` `AgentRun` |
 | `text` | `string` | The agent's **answer prose** (every `text` part concatenated), accumulating live. Excludes thinking. For a free-text agent this IS the result |
 | `output` | `TOutput \| undefined` | The structured result once the run completes. `undefined` when the run produced none |
@@ -125,8 +125,9 @@ const run = useAgentRun("importer");
 ```
 
 The ask renders in the feed as a settled tool row once answered (the answer rides its
-on-demand reveal). `run()`'s promise resolves `undefined` when the run parks — the
-continuation's promise (from `answerChoice`) carries the final output. The question is as
+on-demand reveal). `run()` resolves `{kind:"parked"}` when the run parks — nothing for you
+to do there, the wizard renders off `pendingChoice` — and the continuation's landing (from
+`answerChoice`) carries the final output, or `parked` again for a follow-up ask. The question is as
 connection-decoupled as the run: a dropped stream can't lose it — the hook's recovery poll
 rebuilds the pending question from the persisted run, so `awaiting_input` always yields an
 answerable `pendingChoice` (the one unrecoverable corner surfaces a retryable `error`, never
@@ -382,3 +383,4 @@ The floors below are when each capability shipped in `@lotics/app-sdk`; an app p
 | `askAi` | `@lotics/app-sdk` 0.45 |
 | `useAiContext` (ambient-chat view state + auto query refetch on chat mutation) | `@lotics/app-sdk` 0.52 |
 | The agent asks back (`pendingChoice`/`answerChoice`, `awaiting_input`) | `@lotics/app-sdk` 0.55 |
+| A leg resolves an `AgentRunLanding` (`settled`/`parked`/`failed`/`aborted`) instead of `TOutput \| undefined` | `@lotics/app-sdk` 0.62 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {