@lotics/cli 0.55.0 → 0.57.0

package/dist/app_commands.d.ts

@@ -31,7 +31,7 @@ export type AppQueryDeclaration = {
  *   `"alias": { instructions, tool_names, model_id, inputs?, outputs? }`
  *
  * A read-only reflection of the live App row (`apps.agents`, owned by
- * `set_app_agent`), refreshed by `lotics app pull` and used only to codegen
+ * `set_app_agent` / `remove_app_agent`), refreshed by `lotics app pull` and used only to codegen
  * `useAgentRun` typings. `inputs`/`outputs` drive the typed call site; the rest
  * is carried for fidelity.
  */

package/dist/client.d.ts

@@ -1,3 +1,11 @@
+/**
+ * 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
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /** One sort key forwarded to the app query RPC (wire shape of a `TableRecordSort` entry). */
 export interface AppQuerySortKey {
     field_key: string;

package/dist/client.js

@@ -1,5 +1,36 @@
 import fs from "node:fs";
 import path from "node:path";
+/**
+ * A user-facing message for a transport/gateway failure — derived from the HTTP
+ * status, never from the response body. A 524 (edge timeout on a long run), any
+ * 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw body. In
+ * parity (by value, no shared dep) with the published transport in
+ * `packages/app-sdk/src/rpc.ts`.
+ */
+function gatewayErrorMessage(status) {
+    if (status === 524) {
+        return "The request took too long to finish (gateway timeout). It may still be running — check back in a moment, or try again.";
+    }
+    if (status >= 500) {
+        return "The service is temporarily unavailable. Please try again shortly.";
+    }
+    return "The service returned an unexpected response. Please try again.";
+}
+/**
+ * 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
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+export function transportErrorMessage(status, parsed) {
+    const jsonMessage = parsed && typeof parsed.message === "string"
+        ? parsed.message
+        : null;
+    return parsed === null || status >= 500 || jsonMessage === null
+        ? gatewayErrorMessage(status)
+        : jsonMessage;
+}
 function findAvailableFilename(dir, filename, reserved) {
     // `reserved` tracks absolute paths claimed by in-flight downloads in the same
     // batch — required for parallel callers because the file may not be on disk
@@ -200,7 +231,34 @@ export class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     async appWorkflow(app_id, alias, inputs) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
+        // Its own transport (not the generic `request`, whose `throwResponseError`
+        // shape is the CLI contract elsewhere): a transport/gateway failure resolves
+        // to a `WorkflowResult` error `{ status, message }` — never a thrown HTML
+        // body — so the dev RPC bridge forwards `{status:"error"}` to the iframe,
+        // matching the deployed standalone SDK (`@lotics/app-sdk` standaloneWorkflow).
+        const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`;
+        const headers = this.buildHeaders();
+        headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await fetch(url, { method: "POST", headers, body: JSON.stringify({ inputs }) });
+        }
+        catch (err) {
+            return { status: "error", message: err instanceof Error ? err.message : "The workflow request failed." };
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // non-JSON body (e.g. a gateway HTML error page) — never echoed
+            }
+        }
+        if (response.ok)
+            return parsed ?? {};
+        return { status: "error", message: transportErrorMessage(response.status, parsed) };
     }
     /**
      * Open a streaming agent run and return the RAW streamed `Response` (the

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { LoticsClient, transportErrorMessage } from "./client.js";
+describe("transportErrorMessage", () => {
+    it("returns a body-free gateway message for a non-JSON 524 (never the HTML)", () => {
+        const msg = transportErrorMessage(524, null);
+        expect(msg).not.toMatch(/<html|<!DOCTYPE/i);
+        expect(msg.toLowerCase()).toContain("gateway timeout");
+    });
+    it("returns a friendly message for any 5xx, ignoring a JSON body", () => {
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toBe("internal detail");
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toMatch(/<html/i);
+    });
+    it("surfaces a genuine 4xx JSON error message verbatim", () => {
+        expect(transportErrorMessage(400, { message: "record_id is required" })).toBe("record_id is required");
+    });
+    it("never leaks a non-JSON 4xx body (WAF / redirect HTML)", () => {
+        expect(transportErrorMessage(403, null)).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("falls back to a friendly message for a JSON body with no message field", () => {
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).toBeTruthy();
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).not.toMatch(/<html/i);
+    });
+});
+describe("LoticsClient.appWorkflow", () => {
+    afterEach(() => vi.unstubAllGlobals());
+    const client = new LoticsClient({ apiKey: "ltk_test", workspaceId: "wsp_test" });
+    it("normalizes a 524 HTML gateway response to a WorkflowResult error (no raw HTML)", async () => {
+        const html = "<!DOCTYPE html><html><head><title>error</title></head><body>524: A timeout occurred</body></html>";
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(html, { status: 524 })));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("passes a 200 workflow result through unchanged", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ status: "success", data: { x: 1 } }), { status: 200 })));
+        const result = await client.appWorkflow("app_1", "wf", {});
+        expect(result).toEqual({ status: "success", data: { x: 1 } });
+    });
+    it("returns a WorkflowResult error (not a throw) on a network failure", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => {
+            throw new Error("ECONNREFUSED");
+        }));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).toContain("ECONNREFUSED");
+    });
+});

package/dist/dev/wrapper_page.d.ts

@@ -24,9 +24,11 @@
  *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
  *   streaming (op "agentRun"): { id, type: "stream-chunk", chunk } * → { id, type: "stream-end" };
  *     the iframe aborts with { id, type: "abort" }.
- *   urlState (useUrlState + router adapter): the iframe reads/writes the wrapper's
- *     address bar via urlState.get/set/go; set push/replace and go drive history,
- *     and back/forward broadcast { type: "url-state", params } back to the iframe.
+ *   urlState (useUrlState): the iframe reads/writes the wrapper's address bar via
+ *     urlState.get/set; set writes in place (replaceState), and browser
+ *     back/forward broadcast { type: "url-state", params } back to the iframe.
+ *     (In-app routing isn't here — the app owns the iframe's own url; see
+ *     @lotics/app-sdk/router.)
  */
 export interface WrapperPageArgs {
     app_name: string;

package/dist/dev/wrapper_page.js

@@ -24,9 +24,11 @@
  *   wrapper → iframe: { id, type: "result", data } | { id, type: "error", message }
  *   streaming (op "agentRun"): { id, type: "stream-chunk", chunk } * → { id, type: "stream-end" };
  *     the iframe aborts with { id, type: "abort" }.
- *   urlState (useUrlState + router adapter): the iframe reads/writes the wrapper's
- *     address bar via urlState.get/set/go; set push/replace and go drive history,
- *     and back/forward broadcast { type: "url-state", params } back to the iframe.
+ *   urlState (useUrlState): the iframe reads/writes the wrapper's address bar via
+ *     urlState.get/set; set writes in place (replaceState), and browser
+ *     back/forward broadcast { type: "url-state", params } back to the iframe.
+ *     (In-app routing isn't here — the app owns the iframe's own url; see
+ *     @lotics/app-sdk/router.)
  */
 export function buildWrapperPage(args) {
     const { app_name, app_id, workspace_id, vite_url, api_url } = args;
@@ -78,9 +80,28 @@ export function buildWrapperPage(args) {
       const iframe = document.getElementById("app");
 
       // Pass the wrapper's own origin to the app via ?lotics_host= so the app
-      // SDK can origin-lock its postMessage bridge.
-      iframe.src = VITE_URL + (VITE_URL.indexOf("?") >= 0 ? "&" : "?")
-        + "lotics_host=" + encodeURIComponent(window.location.origin);
+      // SDK can origin-lock its postMessage bridge, and bake the saved screen
+      // (the wrapper url's _loc, kept current by AppRouter's mirror) into the src
+      // path so a refresh boots the app at that screen — mirrors the production
+      // host. _loc is honoured only when it resolves same-origin to the Vite
+      // server (a url param flowing into an iframe src is a redirect vector);
+      // anything else falls back to the app root.
+      const appSrc = new URL(VITE_URL);
+      const savedLoc = new URLSearchParams(window.location.search).get("_loc");
+      if (savedLoc) {
+        try {
+          const resolved = new URL(savedLoc, VITE_ORIGIN);
+          if (resolved.origin === VITE_ORIGIN) {
+            appSrc.pathname = resolved.pathname;
+            appSrc.search = resolved.search;
+            appSrc.hash = resolved.hash;
+          }
+        } catch (e) {
+          // malformed _loc -> app root
+        }
+      }
+      appSrc.searchParams.set("lotics_host", window.location.origin);
+      iframe.src = appSrc.toString();
 
       async function rpc(op, payload) {
         const res = await fetch("/_rpc", {
@@ -185,7 +206,6 @@ export function buildWrapperPage(args) {
         });
         return out;
       }
-      var lastPushAt = 0;
       function handleUrlStateSet(payload) {
         const params = (payload && payload.params) || {};
         const sp = new URLSearchParams(window.location.search);
@@ -198,21 +218,9 @@ export function buildWrapperPage(args) {
         });
         const qs = sp.toString();
         const url = window.location.pathname + (qs ? "?" + qs : "") + window.location.hash;
-        // push adds a back-able entry (the router adapter); replace for filter
-        // churn. Flood guard: coerce sub-100ms pushes to replace. pushState/
-        // replaceState don't fire popstate, so no echo. Mirrors the production host.
-        const now = Date.now();
-        if (payload && payload.push && now - lastPushAt > 100) {
-          lastPushAt = now;
-          window.history.pushState(null, "", url);
-        } else {
-          window.history.replaceState(null, "", url);
-        }
-        return undefined;
-      }
-      function handleUrlStateGo(payload) {
-        const delta = payload && payload.delta;
-        if (typeof delta === "number") window.history.go(delta);
+        // View-state writes in place — never a history entry. replaceState doesn't
+        // fire popstate, so no echo. Mirrors the production host.
+        window.history.replaceState(null, "", url);
         return undefined;
       }
 
@@ -281,8 +289,6 @@ export function buildWrapperPage(args) {
             ? readUrlParams()
             : msg.op === "urlState.set"
             ? handleUrlStateSet(msg.payload)
-            : msg.op === "urlState.go"
-            ? handleUrlStateGo(msg.payload)
             : await rpc(msg.op, msg.payload);
           const ms = Math.round(performance.now() - startedAt);
           console.debug("[lotics-dev] " + msg.op + " " + ms + "ms", data);
@@ -300,9 +306,9 @@ export function buildWrapperPage(args) {
         }
       });
 
-      // Browser/adapter back/forward → broadcast the new params so useUrlState and
-      // the router adapter re-hydrate (the app's own set writes use push/replace
-      // State — no popstate — so there's no echo). Mirrors the production host.
+      // Browser back/forward → broadcast the new params so useUrlState re-hydrates
+      // (the app's own set writes use replaceState — no popstate — so there's no
+      // echo). Mirrors the production host.
       window.addEventListener("popstate", function () {
         iframe.contentWindow.postMessage(
           { type: "url-state", params: readUrlParams() },