@lotics/app-sdk 0.52.0 → 0.52.1

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.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) {
@@ -487,16 +487,33 @@ export function useAgentRun(alias) {
             },
         };
         return handle.done
-            .then(() => {
+            .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 +527,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;
                 }

package/docs/ai.md

@@ -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.1",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {