@lotics/app-sdk 0.60.3 → 0.61.0

package/dist/src/rpc.d.ts

@@ -170,6 +170,8 @@ export declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, on
  * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
  */
 export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
+/** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
+export declare const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any

package/dist/src/rpc.js

@@ -250,6 +250,11 @@ export function rpcAgentRunContinue(payload, onText) {
         const headers = { "content-type": "application/json" };
         if (sessionToken)
             headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
+        // Continuing an anonymous parked run is authorized by the same per-run
+        // capability that reads it — there is no member to authorize instead.
+        const continueToken = runTokens.get(payload.run_id);
+        if (continueToken)
+            headers[APP_AGENT_RUN_TOKEN_HEADER] = continueToken;
         const res = await fetch(`${API_BASE}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
             method: "POST",
             headers,
@@ -297,8 +302,12 @@ function agentRunStandalone(payload, onText, onRunId) {
             throw await streamStartError(res);
         }
         const runId = res.headers.get("x-app-agent-run-id");
-        if (runId)
+        if (runId) {
+            // Anonymous runs carry their retrieval capability here; a member run does
+            // not, and `rememberRunToken` no-ops on the null.
+            rememberRunToken(runId, res.headers.get(APP_AGENT_RUN_TOKEN_HEADER));
             onRunId?.(runId);
+        }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
         try {
@@ -343,6 +352,40 @@ let sessionToken = null;
  * `APP_PUBLIC_SESSION_HEADER`; both sides are pinned by tests.
  */
 export const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
+/**
+ * Per-run retrieval credentials for ANONYMOUS agent runs, keyed by run id.
+ *
+ * A member's run is authorized by their identity, so reading it back needs
+ * nothing extra. An anonymous run on a publicly-shared app has no member to key
+ * on (`triggered_by_member_id` is null by design), so the server mints a
+ * capability token bound to that one run and returns it on the run response.
+ * Without it the recovery poll 404s and a completed answer is lost to any
+ * dropped connection — routine on mobile for a run measured in tens of seconds.
+ *
+ * Transport-level, like `sessionToken` above and for the same reason: it is a
+ * credential, not app state. Threading it through the hook would put a bearer
+ * into the app's typed surface for every app to forward by hand.
+ *
+ * Only the STANDALONE transport needs this — an embedded app always runs under
+ * a member session, so it never produces an anonymous run.
+ */
+const runTokens = new Map();
+/** Bound the map so a long-lived page cannot accumulate tokens without limit.
+ *  Insertion-ordered, so the oldest entry is the first key. */
+const MAX_TRACKED_RUN_TOKENS = 8;
+function rememberRunToken(runId, token) {
+    if (!token)
+        return;
+    runTokens.set(runId, token);
+    while (runTokens.size > MAX_TRACKED_RUN_TOKENS) {
+        const oldest = runTokens.keys().next();
+        if (oldest.done)
+            break;
+        runTokens.delete(oldest.value);
+    }
+}
+/** The run token header — mirrored server-side by `APP_AGENT_RUN_TOKEN_HEADER`. */
+export const APP_AGENT_RUN_TOKEN_HEADER = "x-app-agent-run-token";
 /**
  * The cookie the app-host Worker sets after the visitor clears the password
  * gate. Readable by design — the SDK forwards its value as the session header
@@ -473,6 +516,11 @@ async function apiCall(method, path, body, opts) {
     if (sessionToken && !opts?.skipAuth) {
         headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
     }
+    // The per-run capability for an ANONYMOUS run — the only thing that authorizes
+    // reading or cancelling it, since there is no member identity to check.
+    if (opts?.runToken) {
+        headers[APP_AGENT_RUN_TOKEN_HEADER] = opts.runToken;
+    }
     const controller = new AbortController();
     let didTimeout = false;
     const timeoutId = setTimeout(() => {
@@ -716,6 +764,7 @@ 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,
+        runToken: runTokens.get(p.run_id),
     }));
     return { run: r.run };
 }
@@ -725,6 +774,7 @@ 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,
+        runToken: runTokens.get(p.run_id),
     });
     return { ok: true };
 }

package/docs/ai.md

@@ -21,7 +21,7 @@ A declaration carries:
 |---|---|
 | `instructions` | System instructions — the task the agent performs per run |
 | `tool_names` | The tools the agent may call, resolved against the platform's automation tool registry. The capability boundary for everything EXCEPT workspace data — the run can use nothing else. May be empty — including for an agent that reads documents, since a [`file` input carries its own content](#file-inputs--what-the-agent-can-actually-see) |
-| `knowledge_doc_ids` | The knowledge docs the agent may read. Small docs are materialized into the run's system context; a doc too large to inline is read by staging it into a code run, which requires `code_exec` in `tool_names` |
+| `knowledge_doc_ids` | The knowledge docs the agent may read, and the whole set it can reach — a doc absent from this list is unreadable even if the agent names its id. Declare `grep_knowledge` / `read_knowledge` in `tool_names` to read them. There is no size limit and nothing is inlined, so a multi-megabyte reference corpus (a full tariff, a regulation set) is a normal declaration. Reach for `code_exec` only to COMPUTE across the corpus — counting, cross-referencing — never merely to read it |
 | `query_aliases` | The app's own named queries the agent may run via `run_app_query` — its **entire read surface** over records |
 | `workflow_aliases` | The app's own workflows the agent may invoke via `run_app_workflow` — its **entire write surface** |
 | `model_id` | Optional chat model pin. Omit (preferred) to follow the platform default chat model, resolved at run time — the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
@@ -184,6 +184,8 @@ The run's lifetime is decoupled from the stream: the server drives it to complet
 
 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.
 
+**Anonymous runs poll with a capability token, handled for you.** On a publicly-shared app a visitor has no member identity, so the server cannot authorize their poll by ownership — `triggered_by_member_id` is null by design. Instead the run response carries a per-run token (`x-app-agent-run-token`); the SDK stores it against that run id and replays it on the poll, on `cancel`, and on `answerChoice`. It is transport-level, like the password-session token — never surfaced to app code, and never issued for a member run (identity already authorizes those). Nothing to wire: an app calls `useAgentRun` the same way on both. The token is bound to ONE run, so it cannot read another visitor's, and it is why a dropped connection on a public app recovers rather than losing the answer.
+
 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`; the full settled answer is persisted server-side but is not currently client-readable (`useAgentRuns` can't reach it on any transport — see the limitation below), so treat the streamed prefix as terminal for now.

package/package.json

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