@lotics/app-sdk 0.43.0 → 0.45.0

package/AGENTS.md

@@ -112,6 +112,15 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   **`openExternal(url)`** opens a link in a new tab (scheme-validated; host-mediated in the embed).
   **`downloadFile(name, data, mime?)`** saves browser-built bytes (a `Uint8Array | Blob | string`) —
   call it synchronously from the click that produced them.
+- **Chat handoff** — **`askAi({ prompt?, file_ids?, record_ids?, context? })`** opens the Lotics
+  messenger on a FRESH chat seeded with the given files (attached + previewed beside the chat),
+  records (the agent can read/act on them under the viewer's authority), a prefilled *editable*
+  prompt, and free-text grounding; the host stamps the app's identity automatically. Nothing runs
+  until the user presses send. **The razor**: outcome lands in *fields* → `useAgentRun` + a
+  review surface (the app's own structured commit path); outcome is a *file or an open-ended
+  answer* (edit this invoice, draft an email about this shipment) → `askAi`. Embedded-only —
+  rejects in standalone/dev. Name the task in `prompt` (Word/Excel bytes aren't inlined; a clear
+  brief makes the agent read the file first).
 
 ### Decoding query cells — never hand-roll the serialization contract
 

package/dist/src/agent_stream.d.ts

@@ -31,6 +31,11 @@ export interface AgentRunStep {
     output?: unknown;
     /** The tool failure message, when `status` is `"error"`. */
     errorText?: string;
+    /** Running count of streamed argument characters. While a tool call's arguments
+     *  are still generating, the reducer writes a live size into `detail` ("18 KB")
+     *  off this accumulator, so a long generation reads as progressing, not frozen;
+     *  both are cleared when the call settles. */
+    streamedChars?: number;
 }
 /** One entry in the ordered run transcript, in the order it streamed: the agent's
  *  answer prose (`text`), its thinking (`reasoning` — shown collapsed, revealed on
@@ -68,6 +73,9 @@ export declare function initialAgentRunState(): AgentRunState;
 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;

package/dist/src/agent_stream.js

@@ -23,6 +23,10 @@ const SUBMIT_TOOL = "submit_result";
 export function initialAgentRunState() {
     return { status: "streaming", items: [] };
 }
+/** A live size for a step's still-streaming arguments — B under 1 KB, else KB. */
+function formatStreamSize(chars) {
+    return chars < 1024 ? `${chars} B` : `${Math.round(chars / 1024)} KB`;
+}
 /** Grow the trailing prose segment 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. */
@@ -73,8 +77,24 @@ export function reduceAgentChunk(state, chunk) {
                 items: [...state.items, { type: "step", id, label: name, kind: "tool", status: "running", input: chunk.input }],
             };
         }
+        case "tool-input-delta": {
+            // A tool's arguments streaming in — grow the step's live size so a long
+            // generation reads as progressing. `submit_result` created no step (it sets
+            // `output`), so its deltas find no matching step and this no-ops.
+            const len = (chunk.inputTextDelta ?? "").length;
+            if (!len)
+                return state;
+            return {
+                ...state,
+                items: updateStep(state.items, chunk.toolCallId, (s) => {
+                    const chars = (s.streamedChars ?? 0) + len;
+                    return { ...s, streamedChars: chars, detail: formatStreamSize(chars) };
+                }),
+            };
+        }
         case "tool-output-available":
-            return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "done", output: chunk.output })) };
+            // Settled — drop the live streaming size; the row is just label + done.
+            return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "done", output: chunk.output, detail: undefined, streamedChars: undefined })) };
         case "tool-output-error":
             return { ...state, items: updateStep(state.items, chunk.toolCallId, (s) => ({ ...s, status: "error", errorText: chunk.errorText ?? "The tool failed." })) };
         case "error":

package/dist/src/ask_ai.d.ts

@@ -0,0 +1,40 @@
+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>;

package/dist/src/ask_ai.js

@@ -0,0 +1,35 @@
+import { rpc } from "./rpc.js";
+/**
+ * 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 function askAi(args) {
+    const hasPayload = (args.prompt ?? "") !== "" ||
+        (args.file_ids?.length ?? 0) > 0 ||
+        (args.record_ids?.length ?? 0) > 0 ||
+        (args.context ?? "") !== "";
+    if (!hasPayload) {
+        return Promise.reject(new Error("askAi requires at least one of prompt, file_ids, record_ids, context"));
+    }
+    return rpc("askAi", args);
+}

package/dist/src/index.d.ts

@@ -26,6 +26,7 @@ export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "
 export { rpc, isEmbedded } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";

package/dist/src/index.js

@@ -21,6 +21,7 @@ export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";

package/dist/src/router.d.ts

@@ -1,4 +1,4 @@
 import { type RouteObject } from "react-router-dom";
 export declare function AppRouter({ routes }: {
     routes: RouteObject[];
-}): import("react/jsx-runtime").JSX.Element;
+}): import("react").JSX.Element;

package/dist/src/rpc.d.ts

@@ -19,7 +19,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;

package/dist/src/rpc.js

@@ -427,6 +427,10 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "askAi":
+            // The chat surface lives in the Lotics host — a standalone page has
+            // nowhere to hand off to.
+            return Promise.reject(new Error("askAi is only available when the app runs inside Lotics"));
         case "urlState.get":
             // Standalone is a top-level page — its own query string IS the store.
             return Promise.resolve(parseSearch(window.location.search));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -39,11 +39,11 @@
     }
   },
   "devDependencies": {
-    "@types/react": "^19.0.0",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.0.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "react-router-dom": "^7.0.0"
+    "react-router-dom": "^7.18.1"
   },
   "keywords": [
     "lotics",
@@ -60,4 +60,4 @@
     "url": "https://github.com/lotics/lotics.git",
     "directory": "packages/app-sdk"
   }
-}
+}