@lotics/app-sdk 0.52.1 → 0.52.3

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

@@ -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,7 +496,7 @@ export function useAgentRun(alias) {
                 safeSetState(null);
             },
         };
-        return handle.done
+        const inflight = handle.done
             .then(async () => {
             if (aborted)
                 return undefined;
@@ -538,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) |

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