@lotics/app-sdk 0.100.1 → 0.101.1

package/package.json

@@ -1,57 +1,56 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.100.1",
-  "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
+  "version": "0.101.1",
+  "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./router": {
-      "types": "./dist/src/router.d.ts",
-      "default": "./dist/src/router.js"
+      "types": "./dist/router.d.ts",
+      "default": "./dist/router.js"
     }
   },
-  "types": "./dist/src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist",
     "AGENTS.md",
     "docs"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "build": "tsgo -p tsconfig.build.json",
-    "typecheck": "tsgo --noEmit",
+    "build": "tsgo -p tsconfig.build.json && node scripts/build_sdk.mjs",
+    "lint": "oxlint",
     "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "typecheck": "tsgo --noEmit",
+    "prepack": "npm run build"
   },
   "dependencies": {
-    "ai": "^7.0.30",
-    "swr": "^2.4.1"
+    "ai": "^7.0.30"
   },
   "peerDependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-router": "^7.0.0 || ^8.0.0"
   },
-  "peerDependenciesMeta": {
-    "react-router": {
-      "optional": true
-    }
-  },
   "devDependencies": {
+    "@lotics/shared": "*",
+    "@testing-library/react": "^16.3.0",
     "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.0.0",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
-    "react-router": "7.18.2"
+    "@types/react-dom": "~19.2.2",
+    "@vitejs/plugin-react": "^4.3.4",
+    "esbuild": "^0.28.1",
+    "jsdom": "^27.0.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "react-router": "^7.18.2",
+    "typescript": "~6.0.3",
+    "vite": "^7.2.4"
   },
-  "keywords": [
-    "lotics",
-    "app-sdk",
-    "react",
-    "iframe"
-  ],
   "engines": {
     "node": ">=18"
   },
@@ -59,6 +58,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/lotics/lotics.git",
-    "directory": "packages/app-sdk"
+    "directory": "packages/app_sdk"
   }
 }

package/dist/src/agent_stream.d.ts

@@ -1,200 +0,0 @@
-/**
- * Parse a backend app-agent run stream into the app's agent-run model.
- *
- * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
- * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
- * `data: [DONE]`. We fold the chunk types that matter into an ordered `parts` array
- * — the SAME ai-sdk `UIMessagePart[]` shape `@lotics/ui`'s `AgentRun` renders, so
- * `<AgentRun parts={run.parts} />` needs no adapter. `ai` is a TYPE-ONLY import here
- * (tool calls are hand-built as concrete `dynamic-tool` parts); NO `ai` runtime
- * enters the sandboxed app bundle. Unknown chunk types are ignored, so a newer
- * AI-SDK never breaks the SDK.
- *
- * An agent can be either kind: a STRUCTURED agent (declares `outputs`) emits its
- * result as the input of the injected `submit_result` tool → `output` (NOT a part);
- * a FREE-TEXT agent's result is its prose → a text part. `output` is NEVER the
- * free-text (see `AgentRunState.output`). Pure + reducer-shaped so it is fully
- * unit-testable against recorded frames — no live model needed.
- */
-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" | "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. */
-    parts: AgentUIPart[];
-    /** The structured result — the `submit_result` tool's input — or `undefined`.
-     *  NEVER the free-text answer: a free-text agent (or a structured one that
-     *  finished without submitting) has no `output`; its answer is the transcript's
-     *  text. Coercing text here would hand a consumer reading `output.<field>` a bare
-     *  string, crashing it ("... is not iterable"). */
-    output?: unknown;
-    error?: string;
-}
-/** A settled run row, as the poll endpoint returns it. */
-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
- * adoption step for BOTH recovery paths (a dropped stream, and a stream that
- * ended cleanly WITHOUT a `finish` frame — an edge can close a long SSE
- * gracefully mid-run, which looks like completion but is a truncation).
- *
- * The row is the source of truth for status and the STRUCTURED output. A
- * free-text run's row `output` is its prose string — that never enters
- * `state.output` (a structured consumer reads `output.<field>`; a stray string
- * 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[];
-}
-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 {
-    type?: string;
-    delta?: string;
-    /** Partial tool-argument text, streamed while a tool call's input is generated
-     *  (`tool-input-delta`) — distinct from `delta` (answer/thinking prose). */
-    inputTextDelta?: string;
-    toolName?: string;
-    toolCallId?: string;
-    input?: unknown;
-    output?: unknown;
-    errorText?: string;
-    finishReason?: string;
-}
-/** Fold one chunk into the run state. Returns a new state (immutable). */
-export declare function reduceAgentChunk(state: AgentRunState, chunk: Chunk): AgentRunState;
-/**
- * Incremental SSE frame splitter. Feed it raw text as it arrives; it returns the
- * complete chunks parsed so far and the leftover partial frame to carry forward.
- * `[DONE]` is dropped (the `finish` chunk already settles the state).
- */
-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

@@ -1,314 +0,0 @@
-/**
- * Parse a backend app-agent run stream into the app's agent-run model.
- *
- * The backend streams the AI-SDK "UI message" SSE protocol (the same wire format
- * the chat uses) — `data: <json>\n\n` frames, each a typed chunk, terminated by
- * `data: [DONE]`. We fold the chunk types that matter into an ordered `parts` array
- * — the SAME ai-sdk `UIMessagePart[]` shape `@lotics/ui`'s `AgentRun` renders, so
- * `<AgentRun parts={run.parts} />` needs no adapter. `ai` is a TYPE-ONLY import here
- * (tool calls are hand-built as concrete `dynamic-tool` parts); NO `ai` runtime
- * enters the sandboxed app bundle. Unknown chunk types are ignored, so a newer
- * AI-SDK never breaks the SDK.
- *
- * An agent can be either kind: a STRUCTURED agent (declares `outputs`) emits its
- * result as the input of the injected `submit_result` tool → `output` (NOT a part);
- * a FREE-TEXT agent's result is its prose → a text part. `output` is NEVER the
- * 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";
-/**
- * Fold a POLLED settled run row into the stream-accumulated state — the shared
- * adoption step for BOTH recovery paths (a dropped stream, and a stream that
- * ended cleanly WITHOUT a `finish` frame — an edge can close a long SSE
- * gracefully mid-run, which looks like completion but is a truncation).
- *
- * The row is the source of truth for status and the STRUCTURED output. A
- * free-text run's row `output` is its prose string — that never enters
- * `state.output` (a structured consumer reads `output.<field>`; a stray string
- * would crash it). The free-text answer stays in the transcript text.
- */
-export function adoptSettledRun(state, settled) {
-    if (settled.status === "completed") {
-        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 — 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") {
-        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." };
-}
-/** 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. */
-/** Untrusted model output — a non-JSON string is data, not an exception. */
-function decodeJson(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-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) {
-    // A model may hand the tool its arguments as a JSON STRING rather than an
-    // object. The SERVER accepts either and parks the run, so refusing the string
-    // here strands a live `awaiting_input` run: the question exists, the run is
-    // answerable, and the UI reports it as unrecoverable. Parse before validating
-    // — a string that isn't JSON falls through to the same empty result as any
-    // other malformed input, which `adoptGuarded` surfaces loudly and retryably.
-    const decoded = typeof input === "string" ? decodeJson(input) : input;
-    if (!decoded || typeof decoded !== "object")
-        return [];
-    const record = decoded;
-    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 === 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: [] };
-}
-/** Grow the trailing prose part of the given kind, or open a new one (after a tool
- *  ran, or when the kind flips text↔reasoning) — so the transcript interleaves
- *  answer prose, thinking, and tools in the order they streamed. */
-function appendProse(parts, kind, piece) {
-    const last = parts[parts.length - 1];
-    if (last && last.type === kind) {
-        return [...parts.slice(0, -1), { ...last, text: last.text + piece }];
-    }
-    const opened = kind === "text" ? { type: "text", text: piece, state: "streaming" } : { type: "reasoning", text: piece, state: "streaming" };
-    return [...parts, opened];
-}
-/** Apply an update to the `dynamic-tool` part with the given call id (by identity),
- *  leaving the rest untouched. A missing id (older frame) or no match is a no-op. */
-function updateTool(parts, toolCallId, fn) {
-    if (!toolCallId)
-        return parts;
-    return parts.map((p) => (p.type === "dynamic-tool" && p.toolCallId === toolCallId ? fn(p) : p));
-}
-/** Fold one chunk into the run state. Returns a new state (immutable). */
-export function reduceAgentChunk(state, chunk) {
-    switch (chunk.type) {
-        case "text-delta": {
-            const piece = chunk.delta ?? "";
-            return piece ? { ...state, parts: appendProse(state.parts, "text", piece) } : state;
-        }
-        case "reasoning-delta": {
-            // Thinking is its OWN part (not folded into the answer prose) so the UI can
-            // keep it collapsed / revealed-on-demand rather than inline in the answer.
-            const piece = chunk.delta ?? "";
-            return piece ? { ...state, parts: appendProse(state.parts, "reasoning", piece) } : state;
-        }
-        case "tool-input-start":
-        case "tool-input-available": {
-            const name = chunk.toolName ?? "tool";
-            if (name === SUBMIT_TOOL) {
-                // The agent emitted its structured result — routed to `output`, not a part.
-                return { ...state, output: chunk.input };
-            }
-            const id = chunk.toolCallId ?? `${name}-${state.parts.length}`;
-            // Upsert by call id: the tool part opens "input-available" (a running step in
-            // the feed) the moment the call fires and settles when its output arrives
-            // (below), so the feed shows a live tool, not an instantly-done one.
-            const existing = state.parts.some((p) => p.type === "dynamic-tool" && p.toolCallId === id);
-            if (existing) {
-                return { ...state, parts: updateTool(state.parts, id, (p) => ({ type: "dynamic-tool", toolName: p.toolName || name, toolCallId: id, state: "input-available", input: chunk.input ?? p.input })) };
-            }
-            return {
-                ...state,
-                parts: [...state.parts, { type: "dynamic-tool", toolName: name, toolCallId: id, state: "input-available", input: chunk.input }],
-            };
-        }
-        case "tool-input-delta":
-            // A tool's arguments streaming in. The ai-parts model carries no live size, so
-            // this is a no-op — the part already reads as running.
-            return state;
-        case "tool-output-available":
-            return { ...state, parts: updateTool(state.parts, chunk.toolCallId, (p) => ({ type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-available", input: p.input, output: chunk.output })) };
-        case "tool-output-error":
-            return { ...state, parts: updateTool(state.parts, chunk.toolCallId, (p) => ({ type: "dynamic-tool", toolName: p.toolName, toolCallId: p.toolCallId, state: "output-error", input: p.input, errorText: chunk.errorText ?? "The tool failed." })) };
-        case "error":
-            return { ...state, status: "error", error: chunk.errorText ?? "The run failed." };
-        case "abort":
-            return { ...state, status: state.status === "streaming" ? "error" : state.status, error: state.error ?? "The run was stopped." };
-        case "finish": {
-            // Settle the status, and settle anything still streaming so nothing reads as
-            // in-progress on a completed run: a tool with no output frame → output-available
-            // (its output never came); a text/reasoning part still "streaming" → "done" (the
-            // stream's `text-end`/`reasoning-end` markers aren't tracked per-part). `output`
-            // 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") &&
-                    !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") {
-                    return { ...p, state: "done" };
-                }
-                return p;
-            });
-            const status = state.status === "error" ? "error" : awaiting ? "awaiting_input" : "completed";
-            return { ...state, status, parts };
-        }
-        default:
-            return state;
-    }
-}
-/**
- * Incremental SSE frame splitter. Feed it raw text as it arrives; it returns the
- * complete chunks parsed so far and the leftover partial frame to carry forward.
- * `[DONE]` is dropped (the `finish` chunk already settles the state).
- */
-export function parseSseChunks(buffer) {
-    const chunks = [];
-    const frames = buffer.split("\n\n");
-    const rest = frames.pop() ?? ""; // last element is the incomplete frame
-    for (const frame of frames) {
-        for (const line of frame.split("\n")) {
-            const trimmed = line.startsWith("data:") ? line.slice(5).trim() : "";
-            if (!trimmed || trimmed === "[DONE]")
-                continue;
-            try {
-                chunks.push(JSON.parse(trimmed));
-            }
-            catch {
-                // a non-JSON data line — skip it, never throw on the stream
-            }
-        }
-    }
-    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/ask_ai.d.ts

@@ -1,40 +0,0 @@
-export interface AskAiArgs {
-    /** Prefills the chat composer — the user sees, edits, and sends it
-     *  themselves. Nothing runs until they do. */
-    prompt?: string;
-    /** Files to attach to the chat (by id, from `readFiles(cell)`). The host
-     *  resolves each id itself and opens the file preview beside the chat. */
-    file_ids?: string[];
-    /** Records the chat should know about (ids from query rows). The host
-     *  resolves them to table context — the agent can then read and act on
-     *  them under the signed-in user's authority. */
-    record_ids?: string[];
-    /** Free-text grounding for the agent ("Shipment SGN-2481, customer …").
-     *  The host stamps the app's identity alongside it automatically. */
-    context?: string;
-}
-/**
- * Hand off to the Lotics chat agent — opens the messenger on a FRESH chat
- * seeded with the given files, records, and prompt.
- *
- * Use this for dialogue-shaped work: iterating on a document ("edit this
- * invoice"), drafting from record context, open-ended questions. For
- * structured judgment that commits back into the app's own data
- * (extract/check/match/rank), use `useAgentRun` with a review surface
- * instead — the outcome of `askAi` lands in chat, not in your workflows.
- *
- * The user stays in control: the prompt is only prefilled, attachments are
- * visible in the composer, and nothing is sent until they press send.
- *
- * ```tsx
- * import { askAi } from "@lotics/app-sdk";
- * await askAi({
- *   file_ids: [file.id],
- *   record_ids: [row.id],
- *   prompt: "Update the header of this invoice to match our letterhead.",
- * });
- * ```
- *
- * Only available embedded in Lotics — rejects in standalone/dev mode.
- */
-export declare function askAi(args: AskAiArgs): Promise<void>;