@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/src/rpc.js

@@ -1,904 +0,0 @@
-import { runUploadPipeline } from "./upload/pipeline.js";
-import { applyRecordingChange, readRecordingState, recordingStateOf } from "./recording_state.js";
-import { parseSearch, serializeMerge, } from "./url_params.js";
-/**
- * The embedding Lotics host's origin — present iff the app is bridged.
- *
- * Lazy + memoized so the module's top level doesn't touch `window`. A test
- * runner can pull this module in at evaluation time before its jsdom
- * environment finishes setting up `window.location` — an eager read would
- * crash every suite that transitively imports the SDK.
- *
- * `undefined` = not yet computed; `string | null` = computed result.
- */
-let hostOriginCache;
-function getHostOrigin() {
-    if (hostOriginCache === undefined) {
-        hostOriginCache = new URLSearchParams(window.location.search).get("lotics_host");
-    }
-    return hostOriginCache;
-}
-/**
- * Whether the app is running embedded in a Lotics host (vs. standalone at its
- * own origin). `rpc()`, `useUrlState`, and `AppRouter` use this to
- * pick the transport / behaviour; an app rarely needs it directly.
- */
-export function isEmbedded() {
-    // Truthiness, not `!== null`: a present-but-empty `?lotics_host=` yields "",
-    // which is no usable host origin — so it's standalone, matching how `rpc()`
-    // branches transports below.
-    return Boolean(getHostOrigin());
-}
-export function rpc(op, payload) {
-    const hostOrigin = getHostOrigin();
-    return hostOrigin
-        ? rpcBridged(op, payload, hostOrigin)
-        : rpcStandalone(op, payload);
-}
-// ── URL state (the host address bar as shareable app view-state + screen) ────
-//
-// Two consumers: `useUrlState` (a declared, typed slice of filters/search) and
-// `AppRouter`'s screen mirror (the current screen under `_loc`). Both keep app
-// state in the host's address bar so it survives refresh and is shareable. An
-// embedded app can't touch the cross-origin host URL directly, so reads/writes
-// flow over the bridge: the host writes the params in place (a non-remounting
-// `history.replaceState` — never a navigation, which would reload the iframe) and
-// pushes external changes (browser back/forward) back via the `url-state`
-// broadcast. A standalone app owns its top-level URL and the same ops resolve
-// against `window.location`. (In-app *routing* is not here — the app owns its own
-// url via `@lotics/app-sdk/router`; see that module.)
-/** Read the current app-owned query params — bridged: ask the host; standalone:
- *  the page's own query string. */
-export function getUrlParams() {
-    return rpc("urlState.get", {});
-}
-/** Merge `patch` into the host's address bar (each key set, or cleared when its
- *  value is `undefined`), preserving every other param. The host writes in place
- *  (`history.replaceState`) — view-state changes don't add history entries. */
-export function setUrlParams(patch) {
-    return rpc("urlState.set", { params: patch });
-}
-/** Synchronous best-effort snapshot for first paint. Standalone reads its own
- *  URL (no flash); bridged can't read the cross-origin host URL synchronously,
- *  so it returns `{}` and the hook hydrates via `getUrlParams()` on mount. */
-export function peekUrlParams() {
-    return isEmbedded() ? {} : parseSearch(window.location.search);
-}
-/** Subscribe to external query changes — browser back/forward and edited URLs.
- *  Embedded: the host's `url-state` broadcast; standalone: `popstate`. */
-export function subscribeUrlParams(cb) {
-    if (isEmbedded()) {
-        ensureListener();
-        urlStateSubscribers.add(cb);
-        return () => {
-            urlStateSubscribers.delete(cb);
-        };
-    }
-    const handler = () => cb(parseSearch(window.location.search));
-    window.addEventListener("popstate", handler);
-    return () => window.removeEventListener("popstate", handler);
-}
-// ── Host notifications (app → host, fire-and-forget) ─────────────────────────
-/**
- * Push a fire-and-forget notification to the embedding host — no id, no reply.
- * Only the embedded host can receive it (it owns the chat surface), so this
- * no-ops standalone (the app's own origin has no host to inform) and never
- * throws. Distinct from `rpc()`: this is one-way, app → host.
- */
-export function postHostNotification(message) {
-    const hostOrigin = getHostOrigin();
-    if (!hostOrigin)
-        return;
-    window.parent.postMessage(message, hostOrigin);
-}
-/**
- * Subscribe to the host's `queriesChanged` push, which names the aliases whose
- * underlying tables moved. Returns an unsubscribe fn.
- *
- * The host owns the realtime connection — one per tab, shared by every surface
- * in it — because the app frame deliberately holds no platform credentials, and
- * a second socket per app would only duplicate a subscription the host already
- * has. The host resolves changed tables to aliases (it holds the query ASTs)
- * and names them here, so a mounted hook refetches only when ITS query is
- * affected rather than on every change anywhere in the workspace.
- *
- * A standalone (public) app has no host, so this is inert there — those apps
- * stay on pull-based freshness.
- */
-export function subscribeQueriesChanged(cb) {
-    ensureListener();
-    refetchSubscribers.add(cb);
-    return () => {
-        refetchSubscribers.delete(cb);
-    };
-}
-/**
- * Every alias with a mounted query hook, so a local write can name them.
- *
- * Registered by the hooks themselves rather than derived from the manifest: what
- * matters is what is ON SCREEN, and a screen mounts a handful of an app's
- * queries. Keyed by alias with a count, because two hooks can read one alias at
- * once (a register and the drawer over it) and the first to unmount must not
- * retract the second's registration.
- */
-const mountedAliases = new Map();
-/** Register a mounted query's alias. Returns the matching unregister. */
-export function registerQueryAlias(alias) {
-    mountedAliases.set(alias, (mountedAliases.get(alias) ?? 0) + 1);
-    return () => {
-        const n = (mountedAliases.get(alias) ?? 1) - 1;
-        if (n > 0)
-            mountedAliases.set(alias, n);
-        else
-            mountedAliases.delete(alias);
-    };
-}
-/**
- * Re-read the mounted queries because THIS app just wrote.
- *
- * The host's `queriesChanged` push is for changes the app did not make — it
- * travels the realtime path (a version counter, a socket the host owns, and
- * coalescing that is deliberately lazy under load), which is right for another
- * member's edit and far too slow for your own. A writer already knows, so it
- * rings the same bell locally instead of waiting to be told.
- *
- * It names every mounted alias rather than only the ones the write touched: the
- * app cannot know which tables a workflow wrote, and the alternative — asking
- * every call site to declare what it invalidates — is a list that goes stale
- * silently the first time a workflow body grows a second write. The cost is
- * bounded by what is on screen, and it is the work the app was going to do a
- * moment later anyway.
- */
-export function notifyLocalWrite() {
-    if (mountedAliases.size === 0)
-        return;
-    const aliases = [...mountedAliases.keys()];
-    for (const cb of refetchSubscribers)
-        cb(aliases);
-}
-const pending = new Map();
-const streaming = new Map();
-/** `useUrlState` subscribers — notified when the host broadcasts new params
- *  after browser back/forward. */
-const urlStateSubscribers = new Set();
-/** Query hooks subscribed to the host's `queriesChanged` push — the host sends
- *  it after an ambient app-chat agent turn mutated records. */
-const refetchSubscribers = new Set();
-let nextRpcId = 0;
-let listenerInstalled = false;
-function ensureListener() {
-    if (listenerInstalled)
-        return;
-    listenerInstalled = true;
-    window.addEventListener("message", (event) => {
-        // Accept only messages from the parent window, at the host origin.
-        if (event.source !== window.parent || event.origin !== getHostOrigin())
-            return;
-        const msg = event.data;
-        if (!msg)
-            return;
-        // Broadcast (no id): the host pushes new params after browser back/forward
-        // so `useUrlState` subscribers re-hydrate.
-        if (msg.type === "url-state" && msg.params && typeof msg.params === "object") {
-            for (const cb of urlStateSubscribers)
-                cb(msg.params);
-            return;
-        }
-        // Broadcast (no id): the host names the aliases whose tables changed, from
-        // the realtime channel it holds for the whole tab. Push-only freshness; the
-        // host never reads app data through this path.
-        if (msg.type === "queriesChanged" && Array.isArray(msg.aliases)) {
-            const aliases = msg.aliases.filter((a) => typeof a === "string");
-            for (const cb of refetchSubscribers)
-                cb(aliases);
-            return;
-        }
-        // Broadcast (no id): a recording THIS app started moved — the host sends
-        // no other app's and not the chat's.
-        if (msg.type === "recordingChanged") {
-            const state = readRecordingState(msg.state);
-            if (typeof msg.alias !== "string" || state === null) {
-                console.error("The host sent a malformed recordingChanged push; it is ignored.", msg);
-                return;
-            }
-            const before = recordingStateOf(msg.alias);
-            applyRecordingChange(msg.alias, state);
-            // A filed recording is this app's own successful write, so the screen
-            // re-reads now, as after any workflow, not on the realtime push.
-            const newlyFiled = state.phase === "filed" &&
-                !(before.phase === "filed" && before.execution_id === state.execution_id);
-            if (newlyFiled)
-                notifyLocalWrite();
-            return;
-        }
-        if (typeof msg.id !== "number")
-            return;
-        // Single-response ops.
-        const handler = pending.get(msg.id);
-        if (handler) {
-            pending.delete(msg.id);
-            if (msg.type === "result")
-                handler.resolve(msg.data);
-            else
-                handler.reject(new Error(msg.message ?? "RPC failed"));
-            return;
-        }
-        // Streaming op (agentRun): run-id? chunk* → end | error.
-        const stream = streaming.get(msg.id);
-        if (!stream)
-            return;
-        if (msg.type === "run-id") {
-            if (typeof msg.runId === "string")
-                stream.onRunId?.(msg.runId);
-        }
-        else if (msg.type === "stream-chunk") {
-            if (typeof msg.chunk === "string")
-                stream.onText(msg.chunk);
-        }
-        else if (msg.type === "stream-end") {
-            streaming.delete(msg.id);
-            stream.resolve();
-        }
-        else if (msg.type === "error") {
-            streaming.delete(msg.id);
-            stream.reject(new Error(msg.message ?? "Run failed"));
-        }
-    });
-}
-function rpcBridged(op, payload, host) {
-    ensureListener();
-    return new Promise((resolve, reject) => {
-        const id = nextRpcId++;
-        pending.set(id, { resolve: resolve, reject });
-        window.parent.postMessage({ id, op, payload }, host);
-    });
-}
-// ── Streaming transport (agent runs) ─────────────────────────────────────────
-/**
- * Start a streaming agent run. Each raw SSE text chunk is handed to `onText`
- * (the caller parses it via `agent_stream`); `done` settles when the stream
- * ends. Bridged: the host opens the SSE with its session and forwards chunks;
- * standalone: the SDK reads the public endpoint's body directly.
- */
-export function rpcAgentRun(payload, onText, onRunId) {
-    const hostOrigin = getHostOrigin();
-    return hostOrigin
-        ? agentRunBridged(payload, onText, hostOrigin, onRunId)
-        : agentRunStandalone(payload, onText, onRunId);
-}
-function agentRunBridged(payload, onText, host, onRunId) {
-    ensureListener();
-    const id = nextRpcId++;
-    let settleDone = () => { };
-    const done = new Promise((resolve, reject) => {
-        settleDone = resolve;
-        streaming.set(id, { onText, onRunId, resolve, reject });
-        window.parent.postMessage({ id, op: "agentRun", payload }, host);
-    });
-    return {
-        done,
-        abort: () => {
-            if (!streaming.has(id))
-                return;
-            streaming.delete(id);
-            window.parent.postMessage({ id, type: "abort" }, host);
-            // The caller stopped the run — resolve `done` cleanly so it never hangs
-            // (an abort is not a failure). The host tears down the SSE.
-            settleDone();
-        },
-    };
-}
-/**
- * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
- * pending `ask_user_choice` call — streams the continuation leg exactly like
- * `rpcAgentRun` streams the first.
- */
-export function rpcAgentRunContinue(payload, onText) {
-    const hostOrigin = getHostOrigin();
-    if (hostOrigin) {
-        ensureListener();
-        const id = nextRpcId++;
-        let settleDone = () => { };
-        const done = new Promise((resolve, reject) => {
-            settleDone = resolve;
-            streaming.set(id, { onText, resolve, reject });
-            window.parent.postMessage({ id, op: "agentRunContinue", payload }, hostOrigin);
-        });
-        return {
-            done,
-            abort: () => {
-                if (!streaming.has(id))
-                    return;
-                streaming.delete(id);
-                window.parent.postMessage({ id, type: "abort" }, hostOrigin);
-                settleDone();
-            },
-        };
-    }
-    const controller = new AbortController();
-    const done = (async () => {
-        const { app_id } = await boot();
-        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(`${apiBase()}/v1/apps/${app_id}/agent-runs/${encodeURIComponent(payload.run_id)}/continue`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ tool_call_id: payload.tool_call_id, output: payload.output }),
-            signal: controller.signal,
-        });
-        if (!res.ok || !res.body) {
-            throw await streamStartError(res);
-        }
-        const reader = res.body.getReader();
-        const decoder = new TextDecoder();
-        try {
-            for (;;) {
-                const { value, done: streamDone } = await reader.read();
-                if (streamDone)
-                    break;
-                onText(decoder.decode(value, { stream: true }));
-            }
-            const tail = decoder.decode();
-            if (tail)
-                onText(tail);
-        }
-        catch (err) {
-            if (controller.signal.aborted)
-                return;
-            throw err;
-        }
-    })();
-    return { done, abort: () => controller.abort() };
-}
-function agentRunStandalone(payload, onText, onRunId) {
-    const controller = new AbortController();
-    const done = (async () => {
-        const { app_id } = await boot();
-        const headers = { "content-type": "application/json" };
-        if (sessionToken)
-            headers[APP_PUBLIC_SESSION_HEADER] = sessionToken;
-        const res = await fetch(`${apiBase()}/v1/apps/${app_id}/agents/${encodeURIComponent(payload.alias)}/runs`, {
-            method: "POST",
-            headers,
-            body: JSON.stringify({ session_id: payload.session_id, input: payload.input }),
-            signal: controller.signal,
-        });
-        if (!res.ok || !res.body) {
-            throw await streamStartError(res);
-        }
-        const runId = res.headers.get("x-app-agent-run-id");
-        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 {
-            for (;;) {
-                const { value, done: streamDone } = await reader.read();
-                if (streamDone)
-                    break;
-                onText(decoder.decode(value, { stream: true }));
-            }
-            const tail = decoder.decode(); // flush any bytes held across the final read
-            if (tail)
-                onText(tail);
-        }
-        catch (err) {
-            if (controller.signal.aborted)
-                return; // the caller stopped the run — clean, not an error
-            throw err;
-        }
-    })();
-    return { done, abort: () => controller.abort() };
-}
-// ── Standalone transport ────────────────────────────────────────────────────
-/**
- * Meta the host serving a standalone bundle injects into `index.html`, naming
- * the API the app calls.
- *
- * It is the serving host's to state, not the SDK's to assume: the same bundle
- * is served by whoever runs the instance, and an app that carried a compiled-in
- * API address would call somebody else's server. A bridged app never reads it —
- * there the host's own origin arrives on `?lotics_host=`.
- */
-const API_BASE_META = "lotics-api-base";
-let apiBaseCache = null;
-function apiBase() {
-    if (apiBaseCache !== null)
-        return apiBaseCache;
-    const content = document
-        .querySelector(`meta[name="${API_BASE_META}"]`)
-        ?.getAttribute("content")
-        ?.trim();
-    if (!content) {
-        // No default: guessing would send this app's data to whatever address the
-        // guess named. Say what is missing and who puts it there.
-        throw new Error(`This app has no API address. A standalone app reads it from <meta name="${API_BASE_META}"> ` +
-            "in the page the app host serves, and this page carries none.");
-    }
-    apiBaseCache = content.replace(/\/+$/, "");
-    return apiBaseCache;
-}
-const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
-/**
- * Boot-time resolution result. Promise is shared so concurrent first calls
- * (e.g. two `useQuery` hooks rendering simultaneously) coalesce into one
- * `/by-subdomain` fetch and at most one password prompt.
- */
-let bootPromise = null;
-let appInfoPromise = null;
-let sessionToken = null;
-/**
- * The password-session header. It is deliberately NOT `Authorization`: this
- * token authenticates nobody — it proves the visitor knows the app's shared
- * link password — and the credential header already carries API keys and OAuth
- * bearers. Sharing it meant the server's auth middleware rejected the request
- * as an unknown bearer before the password gate ever ran, which took every
- * password-gated public app offline. Wire constant, mirrored server-side by
- * `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
- * on every data call. Same exposure as the `localStorage` token it replaced,
- * minus the password prompt the SDK no longer owns.
- */
-const SESSION_COOKIE = "lotics_app_session";
-function readSessionCookie() {
-    for (const part of document.cookie.split(";")) {
-        const eq = part.indexOf("=");
-        if (eq < 0)
-            continue;
-        if (part.slice(0, eq).trim() === SESSION_COOKIE) {
-            return decodeURIComponent(part.slice(eq + 1).trim()) || null;
-        }
-    }
-    return null;
-}
-/**
- * Resolve the app's identity from its own subdomain. Shared
- * promise so the context bootstrap and the first data call coalesce into one
- * `/by-subdomain` fetch. Does NOT touch the password gate — the app's own
- * identity is not the gated thing, so a password-gated app still resolves it
- * before the prompt.
- */
-function resolveAppInfo() {
-    if (appInfoPromise)
-        return appInfoPromise;
-    const slug = window.location.hostname.split(".")[0];
-    const attempt = apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`);
-    // Don't cache a rejection — a transient failure on first load would brick
-    // every later data call. Clear the slot so the next call retries.
-    attempt.catch(() => {
-        if (appInfoPromise === attempt)
-            appInfoPromise = null;
-    });
-    appInfoPromise = attempt;
-    return attempt;
-}
-async function boot() {
-    if (bootPromise)
-        return bootPromise;
-    const attempt = (async () => {
-        const info = await resolveAppInfo();
-        if (info.requires_password) {
-            // The visitor already passed the gate — the app-host Worker refuses to
-            // serve a single byte of this bundle otherwise — and handed us the session
-            // in a cookie on this origin. The SDK does not prompt: a password screen
-            // is the serving layer's job, which is why it can be one styled, localized
-            // page for every public app instead of hand-rolled DOM in a data library.
-            sessionToken = readSessionCookie();
-        }
-        return info;
-    })();
-    attempt.catch(() => {
-        if (bootPromise === attempt)
-            bootPromise = null;
-    });
-    bootPromise = attempt;
-    return attempt;
-}
-/**
- * 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.
- *
- * 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) {
-        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 JSON error the API AUTHORED surfaces
- * verbatim — a 4xx carrying a `message`, or a 5xx that also carries `code`, the
- * discriminator every error the API emits is built with. A non-JSON body (a
- * gateway HTML page), a 5xx from something that is not us, or a body without a
- * `message` falls back to a body-free, status-derived message — so a raw HTML
- * body never becomes the message. `parsed` is the JSON.parse of the body, or
- * `null` if it wasn't JSON.
- */
-export function transportErrorMessage(status, parsed) {
-    const jsonMessage = parsed && typeof parsed.message === "string"
-        ? parsed.message
-        : null;
-    if (jsonMessage === null)
-        return gatewayErrorMessage(status);
-    // Below 500 the body is ours. At 500 and above it is ours only if it carries
-    // `code` — the discriminator every error the API emits is built with. Status
-    // alone was the wrong test: it threw away the 503 our OWN backpressure gate
-    // authors and replaced it with a different English sentence, so no wording we
-    // choose for a 5xx could ever reach an app member (GAP-300). A gateway's HTML
-    // does not parse at all, and a proxy's JSON does not carry `code`, so both
-    // still get the body-free message.
-    const authored = typeof parsed.code === "string" &&
-        parsed.code.length > 0;
-    return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
-}
-/**
- * A failed request, carrying the per-input refusals when the API named any.
- *
- * A body that does not match what an alias declares is answered 400 with
- * top-level `field_errors` — one sentence per INPUT name, which is what a form
- * puts on the control that is wrong, where the message can only say it at the
- * screen's scope. It rides the error because the transport's own callers are
- * what turn a failure into the result an app reads. Optional throughout: a
- * server that predates them sends none.
- */
-class ApiRefusal extends Error {
-    field_errors;
-    constructor(message, field_errors) {
-        super(message);
-        this.field_errors = field_errors;
-    }
-}
-/** The `field_errors` of an error body, when it carries a well-formed one. */
-function readFieldErrors(parsed) {
-    if (parsed === null || typeof parsed !== "object" || !("field_errors" in parsed)) {
-        return undefined;
-    }
-    const raw = parsed.field_errors;
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
-        return undefined;
-    const named = Object.entries(raw).filter((entry) => typeof entry[1] === "string");
-    return named.length > 0 ? Object.fromEntries(named) : undefined;
-}
-/**
- * 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
-// the bridged host path already bounds its own (`apiFetch`, 30s): a stalled
-// request fails fast with a gateway-timeout message instead of spinning.
-const API_TIMEOUT_MS = 30_000;
-async function apiCall(method, path, body, opts) {
-    const headers = {};
-    if (body)
-        headers["content-type"] = "application/json";
-    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(() => {
-        didTimeout = true;
-        controller.abort();
-    }, API_TIMEOUT_MS);
-    let res;
-    try {
-        res = await fetch(`${apiBase()}${path}`, {
-            method,
-            headers,
-            body: body ? JSON.stringify(body) : undefined,
-            signal: controller.signal,
-        });
-    }
-    catch (err) {
-        // A timeout abort surfaces as an AbortError — convert it to the same
-        // body-free gateway-timeout message a 524 produces, never a raw abort.
-        if (didTimeout && err instanceof DOMException && err.name === "AbortError") {
-            throw new Error(gatewayErrorMessage(524));
-        }
-        throw err;
-    }
-    finally {
-        clearTimeout(timeoutId);
-    }
-    const text = await res.text();
-    let parsed = null;
-    if (text) {
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            // not JSON — body left as raw text
-        }
-    }
-    if (!res.ok) {
-        const errorBody = parsed;
-        // The session went stale — the owner rotated or cleared the password, so the
-        // token's fingerprint no longer matches. Reloading is the whole recovery:
-        // the app-host Worker re-checks its own cookie and, if that is stale too,
-        // serves the gate. The SDK deliberately owns no re-prompt — the gate is a
-        // page at the serving layer, not a modal inside the data layer.
-        if (res.status === 401 && errorBody?.error_code === PASSWORD_REQUIRED_CODE && !opts?.skipAuth) {
-            sessionToken = null;
-            // `/__gate`, not a plain reload: the edge cookie outlives the API session
-            // (rotation kills the session immediately, the cookie only on expiry), so
-            // reloading would be served the bundle again and loop forever. This route
-            // clears both cookies and re-presents the gate.
-            window.location.assign("/__gate");
-            // Never resolves — navigation replaces the document. Returning would let
-            // callers render an error state during teardown.
-            return new Promise(() => { });
-        }
-        // Never surface a non-JSON body (a gateway HTML error page) or a 5xx body as
-        // the message — emit a body-free, status-derived message instead. The
-        // per-input refusals ride along, for the caller that can place them.
-        throw new ApiRefusal(transportErrorMessage(res.status, parsed), readFieldErrors(parsed));
-    }
-    return parsed ?? (text ? text : {});
-}
-function rpcStandalone(op, payload) {
-    switch (op) {
-        case "query":
-            return standaloneQuery(payload);
-        case "field_options":
-            return standaloneFieldOptions(payload);
-        case "workflow":
-            return standaloneWorkflow(payload);
-        case "agentRuns":
-            return standaloneAgentRuns(payload);
-        case "agentRun.get":
-            return standaloneAgentRunGet(payload);
-        case "agentRun.cancel":
-            return standaloneAgentRunCancel(payload);
-        case "upload":
-            return standaloneUpload(payload.file, payload.fidelity);
-        case "members":
-            return standaloneMembers(payload);
-        case "context":
-            return standaloneContext();
-        case "openExternal":
-            return standaloneOpenExternal(payload);
-        case "openApp":
-            // A standalone app is one page at its own address: no host routing
-            // between apps, no sibling to reach.
-            return Promise.reject(new Error("openApp needs the Lotics host: a standalone app has no sibling apps to open. Gate the control on isEmbedded()."));
-        case "askAi":
-            // The chat surface lives in the Lotics host — a standalone page has
-            // nowhere to hand off to.
-            return Promise.reject(new Error("askAi is only available when the app runs inside Lotics"));
-        case "urlState.get":
-            // Standalone is a top-level page — its own query string IS the store.
-            return Promise.resolve(parseSearch(window.location.search));
-        case "urlState.set":
-            return standaloneUrlStateSet(payload);
-        case "comments.list":
-        case "comments.create":
-        case "comments.update":
-        case "comments.delete":
-        case "comments.counts":
-            return rejectCommentsStandalone();
-        case "recording.start":
-        case "recording.stop":
-            // The host records, as the signed-in member; a standalone visitor is
-            // anonymous and has no host to capture in.
-            return Promise.reject(new Error("Recording needs the Lotics host and a signed-in member. Gate the control on useRecording's `available`."));
-    }
-}
-/**
- * Comments are a members-only collaboration surface. A comment must have an
- * authenticated member as its author, and a thread can carry member-to-member
- * discussion — so a standalone (public, anonymous) app has no member to author
- * as and no business reading other members' threads. `useComments` detects this
- * up front via the null context `member_id` and never sends a comment op; this
- * rejection is the belt-and-braces backstop for any direct `rpc()` caller.
- */
-function rejectCommentsStandalone() {
-    return Promise.reject(new Error("Comments are available only in embedded apps — a signed-in member is required."));
-}
-async function standaloneMembers(p) {
-    const { app_id } = await boot();
-    const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";
-    const r = (await apiCall("GET", `/v1/apps/${app_id}/members${qs}`, undefined, {
-        appId: app_id,
-    }));
-    return { members: r.members ?? [] };
-}
-/**
- * Open an external URL in a new tab, scheme-validated. In standalone mode the
- * app is a normal top-level page on its own origin, so `window.open` is not
- * sandbox-blocked — open directly. (Bridged apps route this op to the host,
- * which opens it in the un-sandboxed parent frame; see `app_iframe_host`.)
- * The scheme is re-validated wherever the open actually happens — never trust a
- * URL handed across the bridge.
- */
-function openValidatedUrl(url) {
-    if (typeof url !== "string")
-        throw new Error("openExternal requires a url string");
-    const parsed = new URL(url);
-    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-        throw new Error(`openExternal: unsupported URL scheme "${parsed.protocol}"`);
-    }
-    window.open(parsed.href, "_blank", "noopener,noreferrer");
-}
-// `async` so a synchronous validation throw surfaces as a rejected Promise.
-async function standaloneOpenExternal(p) {
-    openValidatedUrl(p.url);
-}
-async function standaloneUrlStateSet(p) {
-    const search = serializeMerge(window.location.search, p.params ?? {});
-    const url = window.location.pathname + (search ? `?${search}` : "") + window.location.hash;
-    // View-state writes never add a history entry; replaceState doesn't fire
-    // popstate, so there's no echo — the caller already updated optimistically.
-    window.history.replaceState(null, "", url);
-}
-async function standaloneContext() {
-    const info = await resolveAppInfo();
-    return {
-        // No host session in standalone mode — the visitor is anonymous, so
-        // comments are unavailable regardless of the capability flag.
-        member_id: null,
-        comments_enabled: info.comments_enabled,
-        recording_enabled: false,
-    };
-}
-/**
- * The op payload IS the endpoint's body, and the endpoint's answer IS the op's
- * result: both pass through untouched, so `sort`/`filter`/`count`/`keyset` on
- * the way out and `total`/`truncated`/`next_cursor` on the way back reach a
- * standalone app exactly as they reach a bridged one. Naming fields here is
- * what once made `truncated` a host-only field.
- */
-async function standaloneQuery(payload) {
-    const { app_id } = await boot();
-    return apiCall("POST", `/v1/apps/${app_id}/query`, payload, { appId: app_id });
-}
-async function standaloneFieldOptions(p) {
-    const { app_id } = await boot();
-    const r = (await apiCall("POST", `/v1/apps/${app_id}/field-options`, { alias: p.alias }, { appId: app_id }));
-    return { fields: r.fields ?? {} };
-}
-async function standaloneWorkflow(p) {
-    const { app_id } = await boot();
-    try {
-        return await apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
-    }
-    catch (err) {
-        // A transport/gateway failure resolves to a WorkflowResult error (never a
-        // rejection carrying a raw body) so an app reads `result.status === "error"`
-        // uniformly with a handled workflow error. `apiCall` already sanitized the
-        // message, so it never contains an HTML body.
-        //
-        // A payload the alias refuses is that same shape plus the inputs it named,
-        // which is the half a form can act on — the same key a workflow's own
-        // `return({ field_errors })` arrives under, so a screen wires one control
-        // once whichever half answered.
-        return {
-            status: "error",
-            message: err instanceof Error ? err.message : "The workflow failed to run.",
-            ...(err instanceof ApiRefusal && err.field_errors ? { field_errors: err.field_errors } : {}),
-        };
-    }
-}
-async function standaloneAgentRuns(p) {
-    const { app_id } = await boot();
-    const qs = new URLSearchParams({ session_id: p.session_id });
-    if (p.limit != null)
-        qs.set("limit", String(p.limit));
-    if (p.offset != null)
-        qs.set("offset", String(p.offset));
-    const r = (await apiCall("GET", `/v1/apps/${app_id}/agent-runs?${qs.toString()}`, undefined, {
-        appId: app_id,
-    }));
-    return { runs: r.runs ?? [] };
-}
-/** Poll read for a single run — follows a run to completion after its stream
- *  connection drops. The caller types the run shape via `rpc<T>`. */
-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 };
-}
-/** Request server-side cancellation of an in-flight run (an explicit user stop,
- *  distinct from merely closing the stream). */
-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 };
-}
-async function standaloneUpload(file, fidelity) {
-    if (!(file instanceof File)) {
-        throw new Error("upload payload must include a File");
-    }
-    const { app_id } = await boot();
-    const uploaded = await runUploadPipeline(file, {
-        initUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/upload-url`, input, { appId: app_id }),
-        completeUpload: (input) => apiCall("POST", `/v1/apps/${app_id}/files/complete`, input, { appId: app_id }),
-    }, { fidelity });
-    return uploaded;
-}