@lotics/app-sdk 0.44.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/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/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.44.0",
+  "version": "0.45.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {