@lotics/app-sdk 0.54.1 → 0.55.0

package/AGENTS.md

@@ -20,7 +20,7 @@ signature; open the file.**
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments`, `readFiles`/presigned URLs, workflow-generated files, preview pairing, filter operators, the server-side delivery bounds. |
 | [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`), `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). |
+| [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). |
 | [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. |
 | [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

@@ -19,8 +19,15 @@
 import type { UIMessagePart, UIDataTypes, UITools } from "ai";
 /** An ai-sdk message part — the render model, tool-set-agnostic. */
 export type AgentUIPart = UIMessagePart<UIDataTypes, UITools>;
+/**
+ * The MANDATORY interactive tools every app-agent run carries (mirrors the
+ * server's `INTERACTIVE_APP_TOOLS`). A call to one PARKS the run awaiting the
+ * user's answer: its part stays `input-available` through `finish`, the state
+ * reads `awaiting_input`, and `useAgentRun().answerChoice` continues the run.
+ */
+export declare const INTERACTIVE_TOOLS: ReadonlySet<string>;
 export interface AgentRunState {
-    status: "streaming" | "completed" | "error";
+    status: "streaming" | "awaiting_input" | "completed" | "error";
     /** The ordered transcript as ai-sdk `parts` — prose interleaved with the tool
      *  calls (`dynamic-tool` parts), as it streamed. The single source of truth for
      *  the feed; `useAgentRun` derives `text` / `steps` from it. */
@@ -51,6 +58,61 @@ export interface SettledAgentRun {
  * would crash it). The free-text answer stays in the transcript text.
  */
 export declare function adoptSettledRun(state: AgentRunState, settled: SettledAgentRun): AgentRunState;
+export type ChoiceOption = {
+    label: string;
+    description: string;
+};
+export type ChoiceQuestion = {
+    question: string;
+    options: ChoiceOption[];
+    allow_custom?: boolean;
+};
+export type AskUserChoiceAnswer = {
+    type: "option";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+    option_index: number;
+    option_letter: string;
+    option_label: string;
+    option_description: string;
+} | {
+    type: "custom";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+    text: string;
+} | {
+    type: "skipped";
+    question_index: number;
+    question_number: number;
+    question_text: string;
+};
+export type AskUserChoiceOutput = {
+    answers: AskUserChoiceAnswer[];
+    skipped_by_user?: boolean;
+};
+export interface PendingChoice {
+    toolCallId: string;
+    questions: ChoiceQuestion[];
+}
+/** The run's pending `ask_user_choice`, parsed for rendering (a `ClarifyWizard`
+ *  maps 1:1) — non-null exactly while the run is parked awaiting the answer. */
+export declare function pendingInteractiveCall(state: AgentRunState): PendingChoice | null;
+/**
+ * Fold the user's picks into the tool's output shape — `answers` aligns to
+ * `questions` by index (the `ClarifyWizard` contract: `{ value, custom }` per
+ * question, value = the picked option's label or the free text). A missing or
+ * empty entry is a skipped question.
+ */
+export declare function buildChoiceOutput(questions: ChoiceQuestion[], answers: {
+    value: string;
+    custom: boolean;
+}[]): AskUserChoiceOutput;
+/** The user answered: settle the pending part (the answer rides its `output` for
+ *  the feed's on-demand reveal) and put the run back into `streaming` for the
+ *  continuation leg's chunks. */
+export declare function applyInteractiveAnswer(state: AgentRunState, toolCallId: string, output: AskUserChoiceOutput): AgentRunState;
 export declare function initialAgentRunState(): AgentRunState;
 /** A parsed UI-message chunk — only the fields we read, all optional. */
 interface Chunk {

package/dist/src/agent_stream.js

@@ -16,6 +16,13 @@
  * free-text (see `AgentRunState.output`). Pure + reducer-shaped so it is fully
  * unit-testable against recorded frames — no live model needed.
  */
+/**
+ * The MANDATORY interactive tools every app-agent run carries (mirrors the
+ * server's `INTERACTIVE_APP_TOOLS`). A call to one PARKS the run awaiting the
+ * user's answer: its part stays `input-available` through `finish`, the state
+ * reads `awaiting_input`, and `useAgentRun().answerChoice` continues the run.
+ */
+export const INTERACTIVE_TOOLS = new Set(["ask_user_choice"]);
 /** The tool the backend injects to carry a typed structured result. */
 const SUBMIT_TOOL = "submit_result";
 /**
@@ -34,8 +41,96 @@ 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.
+    if (settled.status === "awaiting_input") {
+        return { ...state, status: "awaiting_input" };
+    }
     return { ...state, status: "error", error: settled.error_message ?? "The run was stopped." };
 }
+/** The run's pending `ask_user_choice`, parsed for rendering (a `ClarifyWizard`
+ *  maps 1:1) — non-null exactly while the run is parked awaiting the answer. */
+export function pendingInteractiveCall(state) {
+    if (state.status !== "awaiting_input")
+        return null;
+    for (let i = state.parts.length - 1; i >= 0; i--) {
+        const p = state.parts[i];
+        if (p.type !== "dynamic-tool" || !INTERACTIVE_TOOLS.has(p.toolName))
+            continue;
+        if (p.state !== "input-available" && p.state !== "input-streaming")
+            continue;
+        const questions = parseChoiceQuestions(p.input);
+        return questions.length > 0 ? { toolCallId: p.toolCallId, questions } : null;
+    }
+    return null;
+}
+function parseChoiceQuestions(input) {
+    if (!input || typeof input !== "object")
+        return [];
+    const record = input;
+    if (!Array.isArray(record.questions))
+        return [];
+    const questions = [];
+    for (const raw of record.questions) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const q = raw;
+        if (typeof q.question !== "string" || !Array.isArray(q.options))
+            continue;
+        const options = [];
+        for (const o of q.options) {
+            if (o && typeof o === "object" && typeof o.label === "string") {
+                const opt = o;
+                options.push({ label: opt.label, description: typeof opt.description === "string" ? opt.description : "" });
+            }
+        }
+        questions.push({ question: q.question, options, allow_custom: q.allow_custom === true });
+    }
+    return questions;
+}
+/**
+ * Fold the user's picks into the tool's output shape — `answers` aligns to
+ * `questions` by index (the `ClarifyWizard` contract: `{ value, custom }` per
+ * question, value = the picked option's label or the free text). A missing or
+ * empty entry is a skipped question.
+ */
+export function buildChoiceOutput(questions, answers) {
+    const toLetter = (i) => String.fromCharCode("A".charCodeAt(0) + i);
+    const built = questions.map((question, index) => {
+        const questionNumber = index + 1;
+        const answer = answers[index];
+        const value = answer?.value.trim() ?? "";
+        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);
+        if (optionIndex >= 0) {
+            const option = question.options[optionIndex];
+            return {
+                type: "option",
+                question_index: index,
+                question_number: questionNumber,
+                question_text: question.question,
+                option_index: optionIndex,
+                option_letter: toLetter(optionIndex),
+                option_label: option.label,
+                option_description: option.description,
+            };
+        }
+        return { type: "custom", question_index: index, question_number: questionNumber, question_text: question.question, text: value };
+    });
+    const answeredCount = built.filter((a) => a.type !== "skipped").length;
+    return { answers: built, skipped_by_user: answeredCount === 0 };
+}
+/** The user answered: settle the pending part (the answer rides its `output` for
+ *  the feed's on-demand reveal) and put the run back into `streaming` for the
+ *  continuation leg's chunks. */
+export function applyInteractiveAnswer(state, toolCallId, output) {
+    const parts = state.parts.map((p) => p.type === "dynamic-tool" && p.toolCallId === toolCallId
+        ? { type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-available", input: p.input, output }
+        : p);
+    return { ...state, status: "streaming", parts };
+}
 export function initialAgentRunState() {
     return { status: "streaming", parts: [] };
 }
@@ -110,8 +205,14 @@ export function reduceAgentChunk(state, chunk) {
             // is whatever `submit_result` set (else undefined) — NEVER the accumulated text:
             // a structured-output consumer reads `output.<field>`, so a stray free-text
             // string there would crash it. The free-text answer is always in a text part.
+            // ONE exemption: a pending INTERACTIVE call (`ask_user_choice`) is the run
+            // PARKING, not finishing — its part stays `input-available` and the state
+            // reads `awaiting_input` so the app renders the question and continues.
+            const awaiting = state.parts.some((p) => p.type === "dynamic-tool" && INTERACTIVE_TOOLS.has(p.toolName) && (p.state === "input-available" || p.state === "input-streaming"));
             const parts = state.parts.map((p) => {
-                if (p.type === "dynamic-tool" && (p.state === "input-available" || p.state === "input-streaming")) {
+                if (p.type === "dynamic-tool" &&
+                    (p.state === "input-available" || p.state === "input-streaming") &&
+                    !INTERACTIVE_TOOLS.has(p.toolName)) {
                     return { type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-available", input: p.input, output: undefined };
                 }
                 if ((p.type === "text" || p.type === "reasoning") && p.state === "streaming") {
@@ -119,7 +220,8 @@ export function reduceAgentChunk(state, chunk) {
                 }
                 return p;
             });
-            return { ...state, status: state.status === "error" ? "error" : "completed", parts };
+            const status = state.status === "error" ? "error" : awaiting ? "awaiting_input" : "completed";
+            return { ...state, status, parts };
         }
         default:
             return state;

package/dist/src/hooks.d.ts

@@ -1,9 +1,10 @@
 import { type AiContextValue } from "./rpc.js";
-import { type AgentUIPart } from "./agent_stream.js";
+import { type AgentUIPart, type PendingChoice } 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 } from "./agent_stream.js";
+export type { AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput } from "./agent_stream.js";
+export { buildChoiceOutput } from "./agent_stream.js";
 /** Fields shared by every query hook's return value. */
 interface QueryStateBase {
     /**
@@ -469,12 +470,27 @@ export interface UseAgentRun<TInput, TOutput> {
     /** Explicitly stop the run server-side (saves tokens) AND locally. Wire a
      *  user-facing "Stop" button to this, not `abort`. */
     cancel: () => void;
-    status: "idle" | "streaming" | "completed" | "error";
+    /** `awaiting_input` = the run is PARKED on a question the agent asked
+     *  (`pendingChoice` carries it); `answerChoice` continues the run. */
+    status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
     /** The ordered run transcript as ai-sdk `parts` — prose interleaved with tool
      *  calls, in stream order. Feed straight to `@lotics/ui` `AgentRun`:
      *  `<AgentRun parts={run.parts} state={run.status === "streaming" ? "streaming" : run.status === "error" ? "error" : "done"} />`
      *  — no hand-assembly. */
     parts: AgentUIPart[];
+    /** The agent's pending ask — non-null exactly while `status` is
+     *  `awaiting_input`. `questions` maps 1:1 onto `@lotics/ui`'s `ClarifyWizard`
+     *  (`{question, options: {label, description}[], allow_custom}`). */
+    pendingChoice: PendingChoice | null;
+    /** 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. */
+    answerChoice: (answers: {
+        value: string;
+        custom: boolean;
+    }[]) => Promise<TOutput | undefined>;
     /** 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

@@ -18,10 +18,11 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import useSWR from "swr";
 import useSWRInfinite from "swr/infinite";
-import { rpc, rpcAgentRun, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
-import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, } from "./agent_stream.js";
+import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
+import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, } from "./agent_stream.js";
 import { getMockRows, hasMockFlag } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
+export { buildChoiceOutput } from "./agent_stream.js";
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
 }
@@ -451,27 +452,28 @@ export function useAgentRun(alias) {
             handleRef.current?.abort();
         };
     }, []);
+    // The latest state, readable synchronously (answerChoice needs the pending
+    // call + parts without waiting a render).
+    const stateRef = useRef(null);
     const safeSetState = useCallback((s) => {
+        stateRef.current = s;
         if (mountedRef.current)
             setState(s);
     }, []);
-    const run = useCallback((input, opts) => {
-        // Single-flight: an extra press must not become a second paid run — the
-        // old abort-and-restart default kept the first run executing (and
-        // billing) server-side while the client went blind to it. Joining the
-        // in-flight promise makes a double-click resolve with the first run's
-        // result; `replace: true` is the explicit opt-in to abort-and-restart.
-        if (inflightRef.current && !opts.replace) {
-            captureAppEvent("app_agent_run_deduped", { alias });
-            return inflightRef.current;
-        }
-        handleRef.current?.abort();
-        runIdRef.current = null;
-        let acc = initialAgentRunState();
+    /**
+     * Drive ONE streaming leg (the initial run, or a continuation after an
+     * answered ask) into shared state: fold SSE chunks from `initial`, and on a
+     * cut stream fall back to the persisted row — the run is decoupled from the
+     * 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.
+     */
+    const streamLeg = useCallback((start, initial) => {
+        let acc = initial;
         let buffer = "";
         let aborted = false;
         safeSetState(acc);
-        const handle = rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, (textChunk) => {
+        const handle = start((textChunk) => {
             if (aborted)
                 return;
             buffer += textChunk;
@@ -482,8 +484,6 @@ export function useAgentRun(alias) {
             for (const c of chunks)
                 acc = reduceAgentChunk(acc, c);
             safeSetState({ ...acc });
-        }, (runId) => {
-            runIdRef.current = runId;
         });
         // Wrap abort so a stop (user or unmount) marks the run cancelled and clears
         // the partial state back to idle — `done` resolves cleanly, never an error.
@@ -496,7 +496,7 @@ export function useAgentRun(alias) {
                 safeSetState(null);
             },
         };
-        const inflight = handle.done
+        return handle.done
             .then(async () => {
             if (aborted)
                 return undefined;
@@ -571,13 +571,52 @@ export function useAgentRun(alias) {
             safeSetState(acc);
             throw err;
         });
+    }, [safeSetState]);
+    const run = useCallback((input, opts) => {
+        // Single-flight: an extra press must not become a second paid run — the
+        // old abort-and-restart default kept the first run executing (and
+        // billing) server-side while the client went blind to it. Joining the
+        // in-flight promise makes a double-click resolve with the first run's
+        // result; `replace: true` is the explicit opt-in to abort-and-restart.
+        if (inflightRef.current && !opts.replace) {
+            captureAppEvent("app_agent_run_deduped", { alias });
+            return inflightRef.current;
+        }
+        handleRef.current?.abort();
+        runIdRef.current = null;
+        const inflight = streamLeg((onText) => rpcAgentRun({ alias, session_id: opts.sessionId, input: input ?? {} }, onText, (runId) => {
+            runIdRef.current = runId;
+        }), initialAgentRunState());
+        const tracked = inflight.finally(() => {
+            if (inflightRef.current === tracked)
+                inflightRef.current = null;
+        });
+        inflightRef.current = tracked;
+        return tracked;
+    }, [alias, safeSetState, 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) => {
+        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), 
+        // 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));
         const tracked = inflight.finally(() => {
             if (inflightRef.current === tracked)
                 inflightRef.current = null;
         });
         inflightRef.current = tracked;
         return tracked;
-    }, [alias, safeSetState]);
+    }, [streamLeg]);
     const abort = useCallback(() => handleRef.current?.abort(), []);
     const cancel = useCallback(() => {
         // Stop server-side too (saves tokens on an unwanted run), then locally.
@@ -596,6 +635,8 @@ export function useAgentRun(alias) {
         cancel,
         status: state?.status ?? "idle",
         parts,
+        pendingChoice,
+        answerChoice,
         text,
         output: state?.output,
         error: state?.error,

package/dist/src/index.d.ts

@@ -16,8 +16,8 @@
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, } from "./hooks.js";
-export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentUIPart, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
+export type { UploadedFile, AttachedFile, BaseQueryOptions, QueryOptions, InfiniteQueryOptions, PaginatedQueryOptions, QuerySortKey, QueryFilter, QueryFilterCondition, QueryFilterGroup, WorkflowResult, MembersOptions, AgentRunOptions, UseAgentRun, AgentRunRecord, AgentRunState, AgentUIPart, PendingChoice, ChoiceQuestion, ChoiceOption, AskUserChoiceOutput, FieldOptions, FieldOptionsState, FieldOptionsOptions, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useViewer } from "./viewer.js";

package/dist/src/index.js

@@ -15,7 +15,7 @@
  * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, } from "./hooks.js";
+export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export { useViewer } from "./viewer.js";
 export { useConfig } from "./config.js";

package/dist/src/row.d.ts

@@ -74,9 +74,9 @@ export interface AppFile {
     thumbnail_url?: string;
     /** Byte size of the file, resolved from the file object at serving time. Absent
      *  for older files not yet backfilled — show a size only when present. Prefer a
-     *  dedicated sortable `Table` column over the RAW number (the `tpl_documents`
-     *  register: a right-aligned "Size" column, formatted at display) — not a crammed
-     *  `FileRow` meta string, which sorts wrong ("8.4 MB" < "96 KB"). */
+     *  dedicated sortable `Table` column over the RAW number (the `tpl_record`
+     *  documents register: a right-aligned "Size" column, formatted at display) —
+     *  not a crammed `FileRow` meta string, which sorts wrong ("8.4 MB" < "96 KB"). */
     size?: number | null;
     /** ISO upload timestamp (date-added), resolved at serving time. Show as a
      *  dedicated "Added" `Table` column (format with `formatDate`), sortable over the

package/dist/src/rpc.d.ts

@@ -147,6 +147,18 @@ export declare function subscribeHostRefetch(cb: () => void): () => void;
  * standalone: the SDK reads the public endpoint's body directly.
  */
 export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;
+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>;
+}
+/**
+ * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+ * pending `ask_user_choice` call — streams the continuation leg exactly like
+ * `rpcAgentRun` streams the first.
+ */
+export declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, onText: (chunk: string) => void): AgentRunHandle;
 /**
  * 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

@@ -218,6 +218,70 @@ function agentRunBridged(payload, onText, host, onRunId) {
         },
     };
 }
+/**
+ * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+ * pending `ask_user_choice` call — streams the continuation leg exactly like
+ * `rpcAgentRun` streams the first.
+ */
+export function rpcAgentRunContinue(payload, onText) {
+    const hostOrigin = getHostOrigin();
+    if (hostOrigin) {
+        ensureListener();
+        const id = nextRpcId++;
+        let settleDone = () => { };
+        const done = new Promise((resolve, reject) => {
+            settleDone = resolve;
+            streaming.set(id, { onText, resolve, reject });
+            window.parent.postMessage({ id, op: "agentRunContinue", payload }, hostOrigin);
+        });
+        return {
+            done,
+            abort: () => {
+                if (!streaming.has(id))
+                    return;
+                streaming.delete(id);
+                window.parent.postMessage({ id, type: "abort" }, hostOrigin);
+                settleDone();
+            },
+        };
+    }
+    const controller = new AbortController();
+    const done = (async () => {
+        const { app_id } = await boot();
+        const headers = { "content-type": "application/json" };
+        if (sessionToken)
+            headers["authorization"] = `Bearer ${sessionToken}`;
+        const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ tool_call_id: payload.tool_call_id, output: payload.output }),
+            signal: controller.signal,
+        });
+        if (!res.ok || !res.body) {
+            const text = await res.text().catch(() => "");
+            throw new Error(text || `HTTP ${res.status}`);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        try {
+            for (;;) {
+                const { value, done: streamDone } = await reader.read();
+                if (streamDone)
+                    break;
+                onText(decoder.decode(value, { stream: true }));
+            }
+            const tail = decoder.decode();
+            if (tail)
+                onText(tail);
+        }
+        catch (err) {
+            if (controller.signal.aborted)
+                return;
+            throw err;
+        }
+    })();
+    return { done, abort: () => controller.abort() };
+}
 function agentRunStandalone(payload, onText, onRunId) {
     const controller = new AbortController();
     const done = (async () => {

package/docs/ai.md

@@ -52,7 +52,9 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 | `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 |
 | `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" \| "completed" \| "error"` | Whole-run state. `abort`/`cancel` reset it to `"idle"` (and clear the partial transcript) |
+| `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 |
 | `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 |
@@ -81,6 +83,36 @@ The terminal `submit_result` call is captured into `output`, **not** rendered as
 
 `AgentRun` renders thinking collapsed, groups consecutive tool calls, and expands each tool's input/output in place on press — all for free. Running it in a bounded container (a dialog, a panel)? Wrap it in `@lotics/ui`'s `FollowScroll` so the container follows the stream instead of letting new content grow below the fold. **Errors surface two ways:** a per-tool failure is an `output-error` part (amber dot, reason in the expanded Error panel — the feed flows on, exactly like a run that retried and recovered); a **breaking** error that killed the run lives in `run.error` (not in `parts`) — pass it as `error` and it renders as a terminal danger row. Never rebuild this feed by hand.
 
+### The agent asks back — `pendingChoice` / `answerChoice`
+
+Every app agent carries the platform's MANDATORY interactive tool `ask_user_choice` —
+nothing to declare. When the agent hits a genuine ambiguity mid-run it asks: the run PARKS
+(`status: "awaiting_input"`, no tokens burning, resumable for an hour), the pending question(s)
+surface as `pendingChoice`, and answering CONTINUES the same run — same `parts`, same session,
+same eventual `output`:
+
+```tsx
+const run = useAgentRun("importer");
+// …
+{run.pendingChoice ? (
+  <ClarifyWizard
+    questions={run.pendingChoice.questions.map((q) => ({
+      question: q.question,
+      answers: q.options.map((o) => ({ value: o.label, label: o.label, description: o.description })),
+      allowCustom: q.allow_custom,
+    }))}
+    onSubmit={(answers) => { void run.answerChoice(answers); }}
+    onCancel={() => run.cancel()}
+  />
+) : null}
+```
+
+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.
+
 ### `output` typing and the inner-field caveat
 
 The server validates the agent's submitted result strictly (unknown keys rejected, required fields present, types checked, `select` values bound to the declared options); an invalid submission is rejected back to the agent with the validation errors, and the agent retries. A run only settles **completed** with a result that passed this — so on a completed run, `output.items.map(...)` on a declared array field is safe. What that does **not** guarantee:
@@ -269,3 +301,4 @@ The floors below are when each capability shipped in `@lotics/app-sdk`; an app p
 | `parts` transcript (ai-sdk `UIMessagePart[]` — reasoning + per-tool `input`/`output`) | `@lotics/app-sdk` 0.54; renders with `@lotics/ui` ≥ 14.0 (`AgentRun` `parts` prop) |
 | `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 |

package/docs/files.md

@@ -52,13 +52,18 @@ use-access to the app itself.
 The pipeline is: optimize (images only) → mint a presigned upload URL → `PUT` the bytes straight
 to object storage → finalize. The API server never proxies the bytes.
 
-- **Image optimization.** JPEG/PNG/WebP/HEIC/HEIF images larger than 1280 px on the long edge are
+- **Image optimization.** JPEG/PNG/WebP images larger than 1280 px on the long edge are
   resized to ≤1280 px and re-encoded as JPEG at quality 0.75 before upload — phone photos
   typically shrink 10–20×. Non-image files pass through unchanged, and any optimization failure
   falls back to uploading the original bytes (never an upload error).
-  **Warning:** PNG/WebP/HEIC/HEIF larger than 1280 px on the long edge are *converted to JPEG* —
+  **Warning:** PNG/WebP larger than 1280 px on the long edge are *converted to JPEG* —
   transparency is lost and the stored filename's extension becomes `.jpg`. If you need lossless
-  originals, keep images ≤1280 px or upload them as non-image MIME types.
+  originals, keep PNG/WebP ≤1280 px or upload them as non-image MIME types.
+- **HEIC/HEIF always becomes JPEG, regardless of size.** Most browsers cannot decode HEIC
+  (the Samsung/iPhone camera default), so where the browser can't convert it client-side the
+  server converts it at finalize under the same ≤1280 px / q0.75 policy (conversion failure
+  stores the original bytes — never an upload error). Either way the stored file — and the
+  file identity your app gets back — is `name.jpg` with `mime_type: "image/jpeg"`.
 - **Transport resilience.** The storage `PUT` has a 5-minute per-request timeout and retries
   network errors / timeouts / 5xx up to 3 attempts with 1 s → 2 s backoff between attempts. 4xx
   responses are terminal (no retry). The presigned upload URL itself is valid for 10 minutes.

package/package.json

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