@lotics/app-sdk 0.59.1 → 0.60.0

package/dist/src/hooks.js

@@ -30,10 +30,20 @@ export function useWorkflow(alias) {
 // Shared SWR config: surface a failed query immediately, keep the last good
 // rows (no retry loop that masks the error), and honor the focus/reconnect
 // opt-out.
+//
+// `revalidateIfStale: false` — SWR defaults this to `true`, and its initial
+// -revalidation decision is `isUndefined(data) || revalidateIfStale`, so every
+// re-mount of a screen that already had rows re-queried the backend. An app
+// that navigates between screens (or re-opens a drawer) paid a full query set
+// each time for data it was already showing. A cold mount still fetches
+// (`isUndefined(data)` short-circuits), focus/reconnect still refresh, and the
+// host's `refetchQueries` poke still forces a refresh after a chat turn mutates
+// records — so freshness keeps every path it had except "re-mounted".
 function swrConfig(revalidateOnFocus) {
     return {
         revalidateOnFocus,
         revalidateOnReconnect: revalidateOnFocus,
+        revalidateIfStale: false,
         shouldRetryOnError: false,
     };
 }

package/dist/src/rpc.d.ts

@@ -178,6 +178,16 @@ export declare const APP_PUBLIC_SESSION_HEADER = "x-lotics-app-session";
  * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
  */
 export declare function transportErrorMessage(status: number, parsed: unknown): string;
+/**
+ * The error a stream that never started should throw.
+ *
+ * A streaming endpoint fails BEFORE the first byte like any other request — a 402 when the
+ * workspace is out of credits, a 403, a 404. Those bodies are structured errors, and throwing
+ * the body TEXT put the whole JSON on screen: `{"message":"Credit quota exceeded…","error":
+ * "quota_exceeded","plan_id":"free",…}`. Same rule as every other call: the `message` is the
+ * message, and a non-JSON or 5xx body never becomes one.
+ */
+export declare function streamStartError(res: Response): Promise<Error>;
 /**
  * A package installation's alias→concrete-id maps — what the generated
  * `.lotics/app_fields.ts` of a package project resolves `F`/`OPT`/`ROLE`

package/dist/src/rpc.js

@@ -257,8 +257,7 @@ export function rpcAgentRunContinue(payload, onText) {
             signal: controller.signal,
         });
         if (!res.ok || !res.body) {
-            const text = await res.text().catch(() => "");
-            throw new Error(text || `HTTP ${res.status}`);
+            throw await streamStartError(res);
         }
         const reader = res.body.getReader();
         const decoder = new TextDecoder();
@@ -295,8 +294,7 @@ function agentRunStandalone(payload, onText, onRunId) {
             signal: controller.signal,
         });
         if (!res.ok || !res.body) {
-            const text = await res.text().catch(() => "");
-            throw new Error(text || `HTTP ${res.status}`);
+            throw await streamStartError(res);
         }
         const runId = res.headers.get("x-app-agent-run-id");
         if (runId)
@@ -410,8 +408,11 @@ async function boot() {
  * A user-facing message for a transport/gateway failure — derived from the HTTP
  * status, never from the response body. A 524 (Cloudflare edge timeout on a long
  * run), any 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw
- * body as the error message. Kept in parity (by value, no shared dep) with the
- * dev-loop transport in `packages/sdk/src/client.ts`.
+ * body as the error message.
+ *
+ * A by-value MIRROR of `@lotics/shared/transport_error`, which is canonical. This
+ * package ships to npm with zero internal dependencies, so it cannot import it;
+ * every other transport does. Change one, change both.
  */
 function gatewayErrorMessage(status) {
     if (status === 524) {
@@ -437,6 +438,28 @@ export function transportErrorMessage(status, parsed) {
         ? gatewayErrorMessage(status)
         : jsonMessage;
 }
+/**
+ * The error a stream that never started should throw.
+ *
+ * A streaming endpoint fails BEFORE the first byte like any other request — a 402 when the
+ * workspace is out of credits, a 403, a 404. Those bodies are structured errors, and throwing
+ * the body TEXT put the whole JSON on screen: `{"message":"Credit quota exceeded…","error":
+ * "quota_exceeded","plan_id":"free",…}`. Same rule as every other call: the `message` is the
+ * message, and a non-JSON or 5xx body never becomes one.
+ */
+export async function streamStartError(res) {
+    const text = await res.text().catch(() => "");
+    let parsed = null;
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // not JSON — a gateway HTML page; transportErrorMessage will not surface it
+        }
+    }
+    return new Error(transportErrorMessage(res.status, parsed));
+}
 // Standalone requests carried no timeout: a hung or slow backend pinned the
 // fetch — and one of the browser's few per-origin connections — indefinitely,
 // surfacing as an app that "loads forever". Bound every standalone call the way

package/docs/ai.md

@@ -90,6 +90,16 @@ The terminal `submit_result` call is captured into `output`, **not** rendered as
 
 `AgentRun` renders thinking collapsed, groups consecutive tool calls, and expands each tool's input/output in place on press — all for free. Running it in a bounded container (a dialog, a panel)? Wrap it in `@lotics/ui`'s `FollowScroll` so the container follows the stream instead of letting new content grow below the fold. **Errors surface two ways:** a per-tool failure is an `output-error` part (amber dot, reason in the expanded Error panel — the feed flows on, exactly like a run that retried and recovered); a **breaking** error that killed the run lives in `run.error` (not in `parts`) — pass it as `error` and it renders as a terminal danger row. Never rebuild this feed by hand.
 
+`run.error` is always a **sentence to show a person**, never a payload — on both the ways a run can fail.
+
+*Before it starts*: the request is refused (most often a 402 when the workspace is out of AI credits — "Credit quota exceeded. Upgrade your plan for continued AI access." — or a 403/404). You get that response's `message` alone; the rest of the body (`error`, `plan_id`, `credits_used`, …) never reaches the string, and a non-JSON body or any 5xx is replaced by a status-derived message.
+
+*After it starts*: the run dies mid-flight, and the message is written **in the triggering member's language** (the workspace default when an anonymous visitor triggered it). An error the platform wrote surfaces as-is, so running out of credits **during** a run still says to upgrade rather than to retry. A provider or tool failure does NOT — its wording is a debugging string that names our request shape, so it becomes one of two sentences: the request itself was rejected (an attachment that is corrupt or too large — retrying unchanged cannot help), or it broke transiently and is worth another run. The raw error is kept in error tracking with the run id.
+
+Two caveats on that language guarantee. A message written at its throw site rather than fixed on its error class stays English — those strings are also what the chat agent reads to correct its own tool calls, so they are deliberately one language. And the *before it starts* case above is the API response's own `message`, which is not localized either. So an app that must be wholly in one language should render its own copy on failure rather than the platform's.
+
+So `error={run.error}` is safe to render verbatim. What it is NOT is machine-readable: `status` tells you a run failed, not why, and the difference between "worth retrying" and "retrying cannot help" lives in the sentence rather than in a code. **Do not parse it** — the wording is copy and will change. If your app needs to act on the distinction (a retry button that disables itself when a retry is futile, an upgrade prompt on a quota hit), that discriminator can be exposed; it is classified server-side already and simply is not on the wire yet.
+
 ### The agent asks back — `pendingChoice` / `answerChoice`
 
 Every app agent carries the platform's MANDATORY interactive tool `ask_user_choice` —

package/docs/data_fetching.md

@@ -68,8 +68,13 @@ server validates system conditions by `type` and never reads `field_key` on them
   the paged hooks). Object *contents* are hashed, not references — passing a fresh inline
   `{ status: "open" }` each render is the same key; you never need to memoize params.
 - The cache **survives unmount/remount**: returning to a screen renders the cached rows instantly
-  and revalidates in the background (stale-while-revalidate). Identical concurrent reads dedupe to
-  one request.
+  and **sends no request**. Identical concurrent reads dedupe to one request.
+- **A re-mount is not a refresh event.** Freshness comes from window focus / tab return / network
+  reconnect (`revalidateOnFocus`, default on), the host's post-chat-turn refetch poke, and explicit
+  `refetch()`. Re-mounting a screen you already loaded is none of those, so it re-uses the cache.
+  A **cold** key (never loaded, or a new `(alias, params, pageSize, sort, filter)` tuple) always
+  fetches — this only affects keys that already hold rows.
+  After a write the user is watching for, call `refetch()`; never rely on navigation to refresh.
 - **`loading`** is `true` only on the *initial* load of a key — a request is in flight and there
   are no rows yet. It stays `false` during background revalidation of a key that already has rows,
   so consumers never blank loaded data to a spinner on refetch. A key *change* (new params, sort,

package/package.json

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