@lotics/app-sdk 0.55.0 → 0.55.2

package/dist/src/agent_stream.d.ts

@@ -45,6 +45,14 @@ export interface SettledAgentRun {
     status: string;
     output?: unknown;
     error_message?: string | null;
+    /** Present on a polled `awaiting_input` row: the pending ask derived from the
+     *  server-side transcript, so a client that lost the stream (or reloaded) can
+     *  rebuild the question without ever having received the part. */
+    pending_interactive?: {
+        tool_call_id: string;
+        tool_name: string;
+        input: unknown;
+    } | null;
 }
 /**
  * Fold a POLLED settled run row into the stream-accumulated state — the shared

package/dist/src/agent_stream.js

@@ -41,10 +41,26 @@ export function adoptSettledRun(state, settled) {
         const structured = settled.output !== null && typeof settled.output === "object" ? settled.output : undefined;
         return { ...state, status: "completed", output: structured ?? state.output };
     }
-    // A PARKED row is a live, resumable state — the pending ask is already in the
-    // transcript parts; never coerce it into an error.
+    // A PARKED row is a live, resumable state — never coerce it into an error.
+    // The invariant the hook layer relies on: `awaiting_input` always yields an
+    // answerable pending part. When the stream died before the ask part arrived,
+    // rebuild it from the row's derived `pending_interactive`.
     if (settled.status === "awaiting_input") {
-        return { ...state, status: "awaiting_input" };
+        const next = { ...state, status: "awaiting_input" };
+        if (pendingInteractiveCall(next))
+            return next;
+        const p = settled.pending_interactive;
+        const alreadyPresent = p && state.parts.some((part) => part.type === "dynamic-tool" && part.toolCallId === p.tool_call_id);
+        if (p && INTERACTIVE_TOOLS.has(p.tool_name) && !alreadyPresent) {
+            return {
+                ...next,
+                parts: [
+                    ...state.parts,
+                    { type: "dynamic-tool", toolName: p.tool_name, toolCallId: p.tool_call_id, state: "input-available", input: p.input },
+                ],
+            };
+        }
+        return next;
     }
     return { ...state, status: "error", error: settled.error_message ?? "The run was stopped." };
 }
@@ -103,7 +119,7 @@ export function buildChoiceOutput(questions, answers) {
         if (!answer || value.length === 0) {
             return { type: "skipped", question_index: index, question_number: questionNumber, question_text: question.question };
         }
-        const optionIndex = answer.custom ? -1 : question.options.findIndex((o) => o.label === answer.value);
+        const optionIndex = answer.custom ? -1 : question.options.findIndex((o) => o.label === value);
         if (optionIndex >= 0) {
             const option = question.options[optionIndex];
             return {

package/dist/src/hooks.d.ts

@@ -531,6 +531,14 @@ export interface AgentRunRecord {
     error_message: string | null;
     started_at: string;
     completed_at: string | null;
+    /** Single-run GET only, while `status` is "awaiting_input": the pending ask
+     *  derived server-side from the transcript — lets a reconnecting client
+     *  rebuild the question without the live stream. */
+    pending_interactive?: {
+        tool_call_id: string;
+        tool_name: string;
+        input: unknown;
+    } | null;
 }
 interface AgentRunsState {
     runs: AgentRunRecord[];

package/dist/src/hooks.js

@@ -467,12 +467,36 @@ export function useAgentRun(alias) {
      * connection, so a truncation polls the row instead of surfacing a network
      * error. A leg that ends `awaiting_input` resolves with `undefined`; the
      * final leg resolves with the structured output.
+     *
+     * `revertTo` (the continuation leg): the leg's initial state is an OPTIMISTIC
+     * commit (the ask settled locally before the server accepted the answer). A
+     * request that fails before ANY chunk arrives means the server rejected it and
+     * the row never left `awaiting_input` — restore the pre-answer state so the
+     * question is answerable again, and REJECT so the app surfaces the error.
+     * Without this, a 400/409 would be misread as a mid-run connection drop,
+     * poll-adopted, and silently swallowed.
      */
-    const streamLeg = useCallback((start, initial) => {
+    const streamLeg = useCallback((start, initial, revertTo) => {
         let acc = initial;
         let buffer = "";
         let aborted = false;
+        let received = false;
         safeSetState(acc);
+        // Enforce the invariant the wizard relies on: `awaiting_input` always
+        // yields an answerable pendingChoice. A polled parked row whose question
+        // cannot be rebuilt (no part in the stream, none derivable from the row)
+        // must fail loud and retryable, never sit as a silent dead end.
+        const adoptGuarded = (state, settled) => {
+            const adopted = adoptSettledRun(state, settled);
+            if (adopted.status === "awaiting_input" && !pendingInteractiveCall(adopted)) {
+                return {
+                    ...adopted,
+                    status: "error",
+                    error: "The run is waiting for an answer that could not be recovered. Run it again.",
+                };
+            }
+            return adopted;
+        };
         const handle = start((textChunk) => {
             if (aborted)
                 return;
@@ -481,6 +505,7 @@ export function useAgentRun(alias) {
             buffer = rest;
             if (chunks.length === 0)
                 return;
+            received = true;
             for (const c of chunks)
                 acc = reduceAgentChunk(acc, c);
             safeSetState({ ...acc });
@@ -521,7 +546,7 @@ export function useAgentRun(alias) {
                 // a fake "completed": a structured consumer reading a completed
                 // state with no output would render success around a missing result.
                 acc = settled
-                    ? adoptSettledRun(acc, settled)
+                    ? adoptGuarded(acc, settled)
                     : {
                         ...acc,
                         status: "error",
@@ -542,6 +567,14 @@ export function useAgentRun(alias) {
             .catch(async (err) => {
             if (aborted)
                 return undefined;
+            // 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;
+            // this is a request failure, not a stream truncation.
+            if (revertTo && !received) {
+                safeSetState(revertTo);
+                throw err;
+            }
             // The stream connection dropped, but the run is decoupled from it and
             // keeps executing server-side. Poll the persisted run to completion and
             // surface its result instead of a network error — work is never lost.
@@ -551,7 +584,7 @@ export function useAgentRun(alias) {
                 if (aborted)
                     return undefined;
                 if (settled) {
-                    acc = adoptSettledRun(acc, settled);
+                    acc = adoptGuarded(acc, settled);
                     safeSetState(acc);
                 }
                 // The same fleet-visibility beacon as the clean-end path — a dropped
@@ -593,23 +626,29 @@ export function useAgentRun(alias) {
         });
         inflightRef.current = tracked;
         return tracked;
-    }, [alias, safeSetState, streamLeg]);
+    }, [alias, streamLeg]);
     // The run's pending ask — non-null exactly while it is parked on a question.
     const pendingChoice = state ? pendingInteractiveCall(state) : null;
     const answerChoice = useCallback((answers) => {
+        // Join first: a double-submit (the wizard's button pressed twice) must
+        // land on the in-flight continuation, not reject on the already-settled
+        // pending check below.
+        if (inflightRef.current)
+            return inflightRef.current;
         const current = stateRef.current;
         const runId = runIdRef.current;
         const pending = current ? pendingInteractiveCall(current) : null;
         if (!current || !runId || !pending) {
             return Promise.reject(new Error("No pending question to answer."));
         }
-        if (inflightRef.current)
-            return inflightRef.current;
         const output = buildChoiceOutput(pending.questions, answers);
-        const inflight = streamLeg((onText) => rpcAgentRunContinue({ run_id: runId, tool_call_id: pending.toolCallId, output: output }, onText), 
+        const inflight = streamLeg((onText) => rpcAgentRunContinue({ run_id: runId, tool_call_id: pending.toolCallId, output }, onText), 
         // The answered part settles locally (its output rides the feed's
         // on-demand reveal) and the state re-enters streaming for the leg.
-        applyInteractiveAnswer(current, pending.toolCallId, output));
+        applyInteractiveAnswer(current, pending.toolCallId, output), 
+        // On a rejected request the leg restores this pre-answer state, so the
+        // wizard reappears and the rejection reaches the app.
+        current);
         const tracked = inflight.finally(() => {
             if (inflightRef.current === tracked)
                 inflightRef.current = null;

package/dist/src/rpc.d.ts

@@ -1,3 +1,4 @@
+import type { AskUserChoiceOutput } from "./agent_stream.js";
 import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
 /**
  * RPC bridge for a custom-code app's data operations.
@@ -151,7 +152,7 @@ export interface AgentRunContinuePayload {
     run_id: string;
     tool_call_id: string;
     /** The `ask_user_choice` output the user assembled (validated server-side). */
-    output: Record<string, unknown>;
+    output: AskUserChoiceOutput;
 }
 /**
  * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
@@ -159,6 +160,16 @@ export interface AgentRunContinuePayload {
  * `rpcAgentRun` streams the first.
  */
 export declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, onText: (chunk: string) => void): AgentRunHandle;
+/**
+ * The password-session header. It is deliberately NOT `Authorization`: this
+ * token authenticates nobody — it proves the visitor knows the app's shared
+ * link password — and the credential header already carries API keys and OAuth
+ * bearers. Sharing it meant the server's auth middleware rejected the request
+ * as an unknown bearer before the password gate ever ran, which took every
+ * password-gated public app offline. Wire constant, mirrored server-side by
+ * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
+ */
+export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any

package/dist/src/rpc.js

@@ -250,7 +250,7 @@ export function rpcAgentRunContinue(payload, onText) {
         const { app_id } = await boot();
         const headers = { "content-type": "application/json" };
         if (sessionToken)
-            headers["authorization"] = `Bearer ${sessionToken}`;
+            headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
         const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
             method: "POST",
             headers,
@@ -288,7 +288,7 @@ function agentRunStandalone(payload, onText, onRunId) {
         const { app_id } = await boot();
         const headers = { "content-type": "application/json" };
         if (sessionToken)
-            headers["authorization"] = `Bearer ${sessionToken}`;
+            headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
         const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agents/${encodeURIComponent(payload.alias)}/runs`, {
             method: "POST",
             headers,
@@ -336,6 +336,16 @@ const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
 let bootPromise = null;
 let appInfoPromise = null;
 let sessionToken = null;
+/**
+ * The password-session header. It is deliberately NOT `Authorization`: this
+ * token authenticates nobody — it proves the visitor knows the app's shared
+ * link password — and the credential header already carries API keys and OAuth
+ * bearers. Sharing it meant the server's auth middleware rejected the request
+ * as an unknown bearer before the password gate ever ran, which took every
+ * password-gated public app offline. Wire constant, mirrored server-side by
+ * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
+ */
+export const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
 function sessionStorageKey(appId) {
     return `lotics_app_session:${appId}`;
 }
@@ -478,7 +488,7 @@ async function apiCall(method, path, body, opts) {
     if (body)
         headers["content-type"] = "application/json";
     if (sessionToken && !opts?.skipAuth) {
-        headers["authorization"] = `Bearer ${sessionToken}`;
+        headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
     }
     const controller = new AbortController();
     let didTimeout = false;

package/docs/ai.md

@@ -54,7 +54,7 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 | `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 |
+| `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 |
 | `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 |
@@ -109,9 +109,16 @@ 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. `cancel()` on a parked
-run settles it `aborted` immediately; an unanswered park expires after an hour (`error`,
-"timed out waiting for an answer"). Multi-ask runs work — each answer may park again.
+continuation's promise (from `answerChoice`) carries the final output. 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
+a silent dead end). If the server refuses an answer (an invalid submission, a raced cancel
+or expiry, a connection failure), `answerChoice` REJECTS and the pending question is
+restored — surface the error and let the user submit again; nothing is half-committed.
+`cancel()` on a parked run settles it `aborted` immediately; an unanswered park expires
+after an hour (`error`, "timed out waiting for an answer"). Multi-ask runs work — each
+answer may park again.
 
 ### `output` typing and the inner-field caveat
 

package/docs/runtime.md

@@ -132,8 +132,12 @@ coalesce; a transient failure isn't cached, the next call retries). If the app
 is password-protected, the SDK renders its own full-screen password overlay
 (plain DOM, so it works before React data arrives), exchanges the password for a
 session token, and stores it in `localStorage` under
-`lotics_app_session:<app_id>` with its expiry. The token rides as a `Bearer`
-header on subsequent calls; a `401` with error code `PASSWORD_REQUIRED` (the
+`lotics_app_session:<app_id>` with its expiry. The token rides on subsequent
+calls in its own `X-Lotics-App-Session` header — deliberately not
+`Authorization`, which carries API keys and OAuth bearers: this token
+authenticates nobody, it proves the visitor knows the shared password, and
+sharing the credential header made the auth layer reject it before the password
+gate could read it. A `401` with error code `PASSWORD_REQUIRED` (the
 owner rotated or cleared the password) drops the stored token, re-prompts, and
 retries the original call once. There is no cancel button — the visitor enters
 the password or leaves. When `localStorage` is unavailable (private browsing,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.55.0",
+  "version": "0.55.2",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -26,19 +26,16 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "ai": "^7.0.30",
     "posthog-js": "^1.352.0",
     "swr": "^2.4.1"
   },
   "peerDependencies": {
-    "ai": ">=7.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-router-dom": "^7.0.0"
   },
   "peerDependenciesMeta": {
-    "ai": {
-      "optional": true
-    },
     "react-router-dom": {
       "optional": true
     }