@lotics/app-sdk 0.52.0 → 0.52.2

package/dist/src/agent_stream.d.ts

@@ -68,6 +68,24 @@ export interface AgentRunState {
     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;
+}
+/**
+ * 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 declare function initialAgentRunState(): AgentRunState;
 /** A parsed UI-message chunk — only the fields we read, all optional. */
 interface Chunk {

package/dist/src/agent_stream.js

@@ -20,6 +20,24 @@
  */
 /** 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 };
+    }
+    return { ...state, status: "error", error: settled.error_message ?? "The run was stopped." };
+}
 export function initialAgentRunState() {
     return { status: "streaming", items: [] };
 }

package/dist/src/hooks.d.ts

@@ -449,6 +449,13 @@ export interface AgentRunOptions {
     /** Groups this run with prior runs in the same working session; the agent
      *  re-reads them for context. Mint a new id to "clear context". */
     sessionId: string;
+    /** Deliberately abort the run in flight and start this one in its place.
+     *  Without it, `run()` is SINGLE-FLIGHT: a call while a run is streaming
+     *  returns the in-flight run's promise instead of starting (and billing) a
+     *  second run — so an accidental double-press resolves with the first run's
+     *  result. The aborted-and-replaced run still executes and bills server-side;
+     *  replacement is a deliberate act, never a side effect of an extra click. */
+    replace?: boolean;
 }
 /** The live state + controls returned by `useAgentRun`. */
 export interface UseAgentRun<TInput, TOutput> {

package/dist/src/hooks.js

@@ -19,7 +19,7 @@ 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, } from "./agent_stream.js";
+import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, } from "./agent_stream.js";
 import { getMockRows, hasMockFlag } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
 export function useWorkflow(alias) {
@@ -440,6 +440,7 @@ export function useAgentRun(alias) {
     // 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);
+    const inflightRef = 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);
@@ -455,6 +456,15 @@ export function useAgentRun(alias) {
             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();
@@ -486,17 +496,34 @@ export function useAgentRun(alias) {
                 safeSetState(null);
             },
         };
-        return handle.done
-            .then(() => {
+        const inflight = handle.done
+            .then(async () => {
             if (aborted)
                 return undefined;
-            // `finish` normally settles status; guard a stream that ended without one.
-            // Keep `output` as whatever `submit_result` set (else undefined) — never
-            // coerce the free-text into it (that string would crash a structured
-            // consumer reading `output.<field>`; the answer stays in `text`).
+            // A clean stream end WITHOUT a `finish` frame is a truncation, not a
+            // completion — an edge can close a long SSE gracefully mid-run (seen
+            // in production on ~2-minute runs), swallowing the frames that carry
+            // the structured result. The run is decoupled and settles server-side
+            // regardless, so the row is the source of truth: poll it, exactly
+            // like the dropped-with-error path below. (2026-07-18: four NOXH
+            // extractions completed server-side while every client showed
+            // failure through this hole.)
             if (acc.status === "streaming") {
-                acc = { ...acc, status: "completed" };
+                const runId = runIdRef.current;
+                const settled = runId
+                    ? await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current)
+                    : null;
+                if (aborted)
+                    return undefined;
+                acc = settled ? adoptSettledRun(acc, settled) : { ...acc, status: "completed" };
                 safeSetState(acc);
+                // Fleet visibility: how often edges cut agent SSE streams. One
+                // event per truncation, with whether the row rescued the result.
+                captureAppEvent("app_agent_stream_truncated", {
+                    recovered: settled != null,
+                    settled_status: settled?.status ?? null,
+                    has_output: acc.output !== undefined,
+                });
             }
             return acc.output;
         })
@@ -510,10 +537,7 @@ export function useAgentRun(alias) {
             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." };
+                    acc = adoptSettledRun(acc, settled);
                     safeSetState(acc);
                     return acc.output;
                 }
@@ -524,6 +548,12 @@ export function useAgentRun(alias) {
             safeSetState(acc);
             throw err;
         });
+        const tracked = inflight.finally(() => {
+            if (inflightRef.current === tracked)
+                inflightRef.current = null;
+        });
+        inflightRef.current = tracked;
+        return tracked;
     }, [alias, safeSetState]);
     const abort = useCallback(() => handleRef.current?.abort(), []);
     const cancel = useCallback(() => {

package/docs/ai.md

@@ -49,7 +49,7 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 
 | Member | Type | What it is |
 |---|---|---|
-| `run` | `(input, { sessionId }) => 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). Calling it again **aborts any run still in flight** |
+| `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) |
@@ -121,9 +121,14 @@ Both settle the in-flight `run()` promise cleanly with `undefined` — a stop is
 
 ### Runs survive dropped connections
 
-The run's lifetime is decoupled from the stream: the server drives it to completion and persists the result even if the connection drops. The hook reads the run id from the stream's start; if the connection then fails, it **polls the persisted run to completion** (every 2.5 s, bounded at 11 minutes) and resolves with the settled result instead of surfacing a network error — so a run that settles within that 11-minute poll window survives a flaky connection. A run still going when the poll deadline passes (the hard cap is 20 min) is **not** recovered on the client: the poll gives up and the drop surfaces as an error, though the result is still persisted server-side. Only when no run id was ever received (the run never started) does the failure reject before any polling.
+The run's lifetime is decoupled from the stream: the server drives it to completion and persists the result even if the connection drops. The hook reads the run id from the stream's start and recovers through the **persisted run row** — the source of truth — in BOTH failure shapes:
 
-**Warning:** on this recovery path the hook adopts the *persisted* run's output — and a **free-text** run is persisted with its final answer text as the output. So after a connection-drop recovery, a free-text agent's `output` can carry the answer **string** (the one place the "never a stray string" rule doesn't hold), while `text` keeps only what streamed before the drop. If you consume free-text agents, guard with `typeof output === "string"` on the resolved value.
+- **The connection drops with an error** → the hook polls the persisted run to completion (every 2.5 s, bounded at 11 minutes) and resolves with the settled result instead of surfacing a network error.
+- **The stream ends cleanly WITHOUT a `finish` frame** — an edge/proxy can close a long SSE gracefully mid-run, which looks like completion but swallowed the trailing frames (including the structured result). The hook detects the missing `finish` and polls the row the same way. Each such truncation emits the `app_agent_stream_truncated` analytics event (with whether the row rescued the result), so edge-cut frequency is visible fleet-wide.
+
+A run still going when the poll deadline passes (the hard cap is 20 min) is **not** recovered on the client: the poll gives up and the drop surfaces as an error, though the result is still persisted server-side. Only when no run id was ever received (the run never started) does the failure reject before any polling.
+
+On recovery, `output` adopts the row's output **only when it is an object** (a structured result) — the "`output` is never a stray string" rule holds on every path. A **free-text** run recovered from truncation keeps only the streamed prefix in `text`; read the full settled answer via `useAgentRuns(sessionId)` if you need it.
 
 ### Sessions
 

package/package.json

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