@lotics/app-sdk 0.37.0 → 0.38.0

package/AGENTS.md

@@ -53,7 +53,11 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   data→UI adapter; the SDK never imports `@lotics/ui`) for
   `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
   `sendDisabled` gates on `uploading` and the send payload is `fileIds`. Don't hand-roll
-  `createObjectURL`/upload/revoke per app.
+  `createObjectURL`/upload/revoke per app. For a full add-files SCREEN (not the composer pill), map
+  each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file }`, else
+  `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `@lotics/ui`
+  `FileGrid`'s `uploads` — it renders the uploading/error/retry tiles itself (see the kit AGENTS.md
+  Attachments recipe).
 - **List members** — **`useMembers(opts?)`** → `{ members: {id,name,email,image}[], loading, error }`
   — the candidate set for an assign/picker. Gated: the app must declare a `member`-typed input
   (`opts.group` restricts to a declared group). Render with `@lotics/ui` `MemberSelect` / `MemberChip`.
@@ -183,15 +187,24 @@ Two of the most common cells render the platform way with zero hand-rolling; han
 ## Previewing files
 
 Render any uploaded file inline — image, PDF, video, audio, Word, Excel, CSV — with `@lotics/ui`; never
-hand-roll per-type rendering.
-
-- **`FileGalleryModal`** (full-screen viewer) delegates to **`FilePreview`** (single-file), dispatching
-  by MIME; the frontend gallery uses the same renderer.
+hand-roll per-type rendering, and don't fall back to `openExternal` for a preview (that's "download /
+open elsewhere", not viewing).
+
+- **`FileGalleryModal`** (full-screen viewer: toolbar = filename · counter · ⋯actions · close-✕, plus
+  prev/next + ESC) delegates to **`FilePreview`** (single-file), dispatching by MIME; the frontend
+  gallery uses the same renderer. Wire `onFilePress` → a `number|null` `activeIndex`.
+- **PDF renders INLINE** — bytes fetched and painted to a canvas (with a selectable text layer) via
+  `pdfjs-dist`, NOT a native `<iframe>` viewer: a nested PDF browsing context is blocked inside the
+  sandboxed, cross-origin app iframe; a canvas isn't, so preview works. `pdfjs-dist` ships in the app
+  starter (lazy-loaded — non-PDF apps pay no bundle cost).
 - File cells already carry presigned URLs — decode with **`readFiles`** → `AppFile[]`, map to
   `DisplayFile` (`mime_type`→`mimeType`, `thumbnail_url`→`thumbnailUrl`). No round-trip, no URL
   derivation, no server-side doc→PDF (rendering is client-side).
-- Word/Excel preview lazy-imports `@lotics/docx` + `@lotics/xlsx` (optional peer deps) — an image/PDF
-  app installs neither. `@lotics/ui` is i18n/analytics-free: pass `labels` + an `onError`.
+- PDF (`pdfjs-dist`), Word (`@lotics/docx`), and Excel/CSV (`@lotics/xlsx`) all ship in the app starter,
+  lazy-imported — an app that never previews a type pays no bundle cost. Excel renders to a canvas with
+  live formula recalc; Word renders OOXML to the DOM. `@lotics/ui` is i18n/analytics-free: pass `labels`
+  + an `onError`. The toolbar's "open in new tab" can't pop a window in the sandbox — pass `onOpenExternal`
+  wired to the SDK's `openExternal` (omit it and the action hides).
 
 ## Composable optional filters (one query, many scopes)
 

package/dist/src/hooks.d.ts

@@ -414,7 +414,12 @@ export interface UseAgentRun<TInput, TOutput> {
      *  structured output (undefined for a free-text or failed run). Calling again
      *  aborts any run still in flight. */
     run: (input: TInput, opts: AgentRunOptions) => Promise<TOutput | undefined>;
+    /** Stop listening locally (no server effect) — the run keeps executing
+     *  server-side and its result lands in the session history. Used on unmount. */
     abort: () => void;
+    /** 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";
     /** The agent's streamed reasoning / answer text, accumulating live. */
     text: string;

package/dist/src/hooks.js

@@ -351,6 +351,10 @@ export function useMembers(opts) {
 export function useAgentRun(alias) {
     const [state, setState] = useState(null);
     const handleRef = useRef(null);
+    // The run id of the in-flight run (reported by the transport off the response
+    // header). Lets the hook poll the run to completion if the stream connection
+    // drops, and cancel it server-side on an explicit stop.
+    const runIdRef = useRef(null);
     // Guards setState after unmount and aborts any in-flight run on unmount, so a
     // stream never keeps writing to a dead component (or leaks the transport).
     const mountedRef = useRef(true);
@@ -367,6 +371,7 @@ export function useAgentRun(alias) {
     }, []);
     const run = useCallback((input, opts) => {
         handleRef.current?.abort();
+        runIdRef.current = null;
         let acc = initialAgentRunState();
         let buffer = "";
         let aborted = false;
@@ -382,6 +387,8 @@ 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.
@@ -406,9 +413,27 @@ export function useAgentRun(alias) {
             captureAppEvent("app_agent_run", { alias, ok: acc.status !== "error" });
             return acc.output;
         })
-            .catch((err) => {
+            .catch(async (err) => {
             if (aborted)
                 return undefined;
+            // 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.
+            const runId = runIdRef.current;
+            if (runId) {
+                const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
+                if (settled && !aborted) {
+                    acc =
+                        settled.status === "completed"
+                            ? { ...acc, status: "completed", output: settled.output ?? acc.output }
+                            : { ...acc, status: "error", error: settled.error_message ?? "The run was stopped." };
+                    safeSetState(acc);
+                    captureAppEvent("app_agent_run", { alias, ok: settled.status === "completed" });
+                    return acc.output;
+                }
+                if (aborted)
+                    return undefined;
+            }
             acc = { ...acc, status: "error", error: err.message };
             safeSetState(acc);
             captureAppEvent("app_agent_run", { alias, ok: false });
@@ -416,9 +441,17 @@ export function useAgentRun(alias) {
         });
     }, [alias, safeSetState]);
     const abort = useCallback(() => handleRef.current?.abort(), []);
+    const cancel = useCallback(() => {
+        // Stop server-side too (saves tokens on an unwanted run), then locally.
+        const runId = runIdRef.current;
+        if (runId)
+            void rpc("agentRun.cancel", { run_id: runId }).catch(() => { });
+        handleRef.current?.abort();
+    }, []);
     return {
         run,
         abort,
+        cancel,
         status: state?.status ?? "idle",
         text: state?.text ?? "",
         steps: state?.steps ?? [],
@@ -426,6 +459,29 @@ export function useAgentRun(alias) {
         error: state?.error,
     };
 }
+/**
+ * Poll a single run until it leaves `running` — the resume path when a run's
+ * stream connection drops mid-flight. Bounded just past the server-side max-run
+ * cap so a hung run can never poll forever, and bails the moment the caller
+ * aborts or unmounts. Returns the settled run, or null if it never settled.
+ */
+async function pollAgentRunToSettle(runId, cancelled) {
+    const deadline = Date.now() + 11 * 60_000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 2500));
+        if (cancelled())
+            return null;
+        try {
+            const { run } = await rpc("agentRun.get", { run_id: runId });
+            if (run.status !== "running")
+                return run;
+        }
+        catch {
+            // transient read failure — keep polling until the deadline
+        }
+    }
+    return null;
+}
 /**
  * The run history of a session, oldest-first — the persisted outputs the app
  * renders as a session log (NOT a chat: a flat list of past runs). Refetch

package/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "upload" | "members" | "context" | "openExternal" | "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" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;
@@ -64,4 +64,4 @@ export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T
  * ends. Bridged: the host opens the SSE with its session and forwards chunks;
  * standalone: the SDK reads the public endpoint's body directly.
  */
-export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void): AgentRunHandle;
+export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;

package/dist/src/rpc.js

@@ -48,11 +48,15 @@ function ensureListener() {
                 handler.reject(new Error(msg.message ?? "RPC failed"));
             return;
         }
-        // Streaming op (agentRun): chunk* → end | error.
+        // Streaming op (agentRun): run-id? chunk* → end | error.
         const stream = streaming.get(msg.id);
         if (!stream)
             return;
-        if (msg.type === "stream-chunk") {
+        if (msg.type === "run-id") {
+            if (typeof msg.runId === "string")
+                stream.onRunId?.(msg.runId);
+        }
+        else if (msg.type === "stream-chunk") {
             if (typeof msg.chunk === "string")
                 stream.onText(msg.chunk);
         }
@@ -81,17 +85,19 @@ function rpcBridged(op, payload, host) {
  * ends. Bridged: the host opens the SSE with its session and forwards chunks;
  * standalone: the SDK reads the public endpoint's body directly.
  */
-export function rpcAgentRun(payload, onText) {
+export function rpcAgentRun(payload, onText, onRunId) {
     const hostOrigin = getHostOrigin();
-    return hostOrigin ? agentRunBridged(payload, onText, hostOrigin) : agentRunStandalone(payload, onText);
+    return hostOrigin
+        ? agentRunBridged(payload, onText, hostOrigin, onRunId)
+        : agentRunStandalone(payload, onText, onRunId);
 }
-function agentRunBridged(payload, onText, host) {
+function agentRunBridged(payload, onText, host, onRunId) {
     ensureListener();
     const id = nextRpcId++;
     let settleDone = () => { };
     const done = new Promise((resolve, reject) => {
         settleDone = resolve;
-        streaming.set(id, { onText, resolve, reject });
+        streaming.set(id, { onText, onRunId, resolve, reject });
         window.parent.postMessage({ id, op: "agentRun", payload }, host);
     });
     return {
@@ -107,7 +113,7 @@ function agentRunBridged(payload, onText, host) {
         },
     };
 }
-function agentRunStandalone(payload, onText) {
+function agentRunStandalone(payload, onText, onRunId) {
     const controller = new AbortController();
     const done = (async () => {
         const { app_id } = await boot();
@@ -124,6 +130,9 @@ function agentRunStandalone(payload, onText) {
             const text = await res.text().catch(() => "");
             throw new Error(text || `HTTP ${res.status}`);
         }
+        const runId = res.headers.get("x-app-agent-run-id");
+        if (runId)
+            onRunId?.(runId);
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         try {
@@ -307,6 +316,10 @@ function rpcStandalone(op, payload) {
             return standaloneWorkflow(payload);
         case "agentRuns":
             return standaloneAgentRuns(payload);
+        case "agentRun.get":
+            return standaloneAgentRunGet(payload);
+        case "agentRun.cancel":
+            return standaloneAgentRunCancel(payload);
         case "upload":
             return standaloneUpload(payload.file);
         case "members":
@@ -402,6 +415,24 @@ async function standaloneAgentRuns(p) {
     }));
     return { runs: r.runs ?? [] };
 }
+/** Poll read for a single run — follows a run to completion after its stream
+ *  connection drops. The caller types the run shape via `rpc<T>`. */
+async function standaloneAgentRunGet(p) {
+    const { app_id } = await boot();
+    const r = (await apiCall("GET", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}`, undefined, {
+        appId: app_id,
+    }));
+    return { run: r.run };
+}
+/** Request server-side cancellation of an in-flight run (an explicit user stop,
+ *  distinct from merely closing the stream). */
+async function standaloneAgentRunCancel(p) {
+    const { app_id } = await boot();
+    await apiCall("POST", `/v1/apps/${app_id}/agent-runs/${encodeURIComponent(p.run_id)}/cancel`, {}, {
+        appId: app_id,
+    });
+    return { ok: true };
+}
 async function standaloneUpload(file) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");

package/package.json

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