@lotics/app-sdk 0.52.2 → 0.52.4

package/dist/src/hooks.js

@@ -515,11 +515,23 @@ export function useAgentRun(alias) {
                     : null;
                 if (aborted)
                     return undefined;
-                acc = settled ? adoptSettledRun(acc, settled) : { ...acc, status: "completed" };
+                // No settled row after the full poll window means the run's status
+                // could NOT be confirmed (an orphan the server's reaper hasn't
+                // repaired yet, or no run id ever arrived) — that is an error, never
+                // a fake "completed": a structured consumer reading a completed
+                // state with no output would render success around a missing result.
+                acc = settled
+                    ? adoptSettledRun(acc, settled)
+                    : {
+                        ...acc,
+                        status: "error",
+                        error: "The run was interrupted and its result could not be confirmed. Run it again.",
+                    };
                 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", {
+                    kind: "clean_end",
                     recovered: settled != null,
                     settled_status: settled?.status ?? null,
                     has_output: acc.output !== undefined,
@@ -536,13 +548,24 @@ export function useAgentRun(alias) {
             const runId = runIdRef.current;
             if (runId) {
                 const settled = await pollAgentRunToSettle(runId, () => aborted || !mountedRef.current);
-                if (settled && !aborted) {
+                if (aborted)
+                    return undefined;
+                if (settled) {
                     acc = adoptSettledRun(acc, settled);
                     safeSetState(acc);
-                    return acc.output;
                 }
-                if (aborted)
-                    return undefined;
+                // The same fleet-visibility beacon as the clean-end path — a dropped
+                // connection is the OTHER way a stream dies mid-run, and it was
+                // previously invisible (the beacon fired only on clean-end
+                // truncations, undercounting every network-error cut).
+                captureAppEvent("app_agent_stream_truncated", {
+                    kind: "connection_error",
+                    recovered: settled != null,
+                    settled_status: settled?.status ?? null,
+                    has_output: acc.output !== undefined,
+                });
+                if (settled)
+                    return acc.output;
             }
             acc = { ...acc, status: "error", error: err.message };
             safeSetState(acc);
@@ -583,6 +606,16 @@ export function useAgentRun(alias) {
 /** Stable empty transcript so an idle hook returns a constant `items` reference
  *  (no new [] each render → dependents don't re-run needlessly). */
 const EMPTY_ITEMS = [];
+/**
+ * Bounded PAST the server-side max-run cap (20 min) plus settle grace. The
+ * server guarantees a LIVE run settles by its own cap timer, so a row still
+ * `running` at this deadline is an orphan (its process died mid-run) — the
+ * server's reapers repair the row; the client stops polling and surfaces the
+ * error. An earlier 11-minute bound gave up BEFORE the cap: a slow run that
+ * lost its stream showed failure while the server later completed it — the
+ * exact result-loss class this poll exists to prevent.
+ */
+const POLL_DEADLINE_MS = 22 * 60_000;
 /**
  * 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
@@ -590,7 +623,7 @@ const EMPTY_ITEMS = [];
  * 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;
+    const deadline = Date.now() + POLL_DEADLINE_MS;
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, 2500));
         if (cancelled())

package/docs/ai.md

@@ -123,10 +123,12 @@ Both settle the in-flight `run()` promise cleanly with `undefined` — a stop is
 
 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:
 
-- **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.
+- **The connection drops with an error** → the hook polls the persisted run to completion (every 2.5 s) 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.
 
-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.
+Both truncation shapes emit the `app_agent_stream_truncated` analytics event (`kind: "connection_error" | "clean_end"`, with whether the row rescued the result), so edge-cut frequency is visible fleet-wide.
+
+The poll is bounded at 22 minutes — deliberately PAST the server's 20-minute hard run cap, so a live run always settles before the client gives up. A row still `running` at the deadline means the run's process died mid-flight (e.g. a crash that skipped the server's shutdown drain); the poll surfaces an error and the server's reaper repairs the row. 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.
 

package/docs/mutations.md

@@ -199,6 +199,11 @@ When the alias declares `inputs`, the server validates the payload before the wo
   is treated as *omitted* (HTML form controls emit `""` for "left blank"). Nested optional
   object fields are plain-optional: omit the key. A required `text` input does accept `""` —
   emptiness is not a type error; validate non-emptiness in the workflow body if it matters.
+- **Required reference inputs reject empty** — a required `record_link` / `member` / `file`
+  must resolve to at least one real id: the single form rejects `""`, and the multi form
+  rejects `[]` (an empty array is the multi-analog of an empty value — it would otherwise slip
+  past both the required check and the reference bindings below and write an empty link). Make
+  the input `required: false` if "attach nothing" is valid; then `""` omits and `[]` clears.
 - **Server-side reference bindings** — every `record_link` id must reference an existing
   record in its declared `table_id`; every group-scoped `member` id must belong to the
   declared group; every `file` id must live in the app's workspace. These are real write-time

package/package.json

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