@lotics/app-sdk 0.100.0 → 0.101.0

package/dist/src/row.d.ts

@@ -1,159 +0,0 @@
-/**
- * Accessors that coerce raw `useQuery` row values into typed values. Each cell
- * of a query row is `unknown`: the query layer serializes a select column as a
- * `{ key, label }` array (one entry per selected option), a date/datetime as a
- * `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
- *
- * These live in app-sdk — next to `useQuery`, whose serialization contract they
- * decode — so a change to that contract updates them in one place, and so apps
- * stop re-implementing the same coercions. They are pure (`unknown` in, value
- * out) and never throw.
- */
-/**
- * Select → first option key. Reads the enriched `{ key, label }` shape (and the
- * legacy bare id / single-element array / `{ id }` shapes for back-compat).
- * Use `readSelect` for the full `{ key, label }[]` on multi-select cells.
- */
-declare function opt(v: unknown): string | null;
-/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
-declare function text(v: unknown): string;
-/**
- * Number → number, or `null` when the cell holds no number — an empty cell, a
- * NaN/Infinity, an unparseable string. Empty and zero usually mean opposite
- * things ("not priced yet" vs "free", "no reading" vs "a reading of 0"), so the
- * absence is preserved the way `date` preserves it. Write `?? 0` where 0 IS the
- * correct reading of an empty cell (a sum, a count).
- */
-declare function num(v: unknown): number | null;
-/**
- * Checkbox/boolean → `true` / `false`, or `null` when the cell holds neither —
- * an empty cell, a value of another kind. (The strings "true"/"false" decode.)
- *
- * AN UNANSWERED CHECKBOX IS NOT A "NO", exactly as an empty number cell is not a
- * 0: the field's default is what the workspace writes when a row states
- * something, and a row nobody has answered states nothing. Read as `false` it
- * drew "No" for every partner nobody had assessed — the rows a gate exists to
- * catch are precisely the ones that answer nothing — so the absence is preserved
- * the way `num` and `date` preserve theirs. Write `=== true` where only the
- * affirmative acts, `?? false` where the safe side IS the reading.
- */
-declare function bool(v: unknown): boolean | null;
-/**
- * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
- * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
- * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
- * rather than vanishing to null. Null only if absent or unparseable. (Range
- * fields are not handled here — they have no consumer yet.)
- */
-declare function date(v: unknown): Date | null;
-/**
- * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
- * `getHours()` / `toLocaleTimeString()` render the time as written. The stored
- * value is a timezone-less workspace wall-clock (see the serialization note
- * above), so it is read verbatim — no UTC conversion. Use this when the time
- * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
- * month/day is the period start (1) and a missing time is midnight — a
- * reduced-precision value decodes rather than vanishing. Null if absent or
- * unparseable.
- */
-declare function datetime(v: unknown): Date | null;
-/** A linked record cell entry — the target record's id + its display text. */
-export interface ResolvedLink {
-    /** The linked record's id (e.g. "rec_…"). Use to correlate/filter. */
-    id: string;
-    /** The linked record's display text (its primary-field value). Use to render. */
-    display: string;
-}
-/**
- * select_record_link → the FIRST linked record as `{ id, display }` (or null).
- * The common single-link case: read `.display` to render the linked record's
- * name, `.id` to correlate/filter (e.g. group rows by a parent record). Use
- * `readLinks` for the full list on multi-link fields.
- */
-declare function link(v: unknown): ResolvedLink | null;
-/**
- * select_record_link → ALL linked records as `{ id, display }[]` (empty if none).
- *
- * A LOOKUP OF A LINK FIELD ARRIVES ONE LEVEL DEEPER — the cell holds one entry
- * per linked record and each entry is THAT record's whole link cell, an array —
- * so read entry-by-entry it decoded to nothing while the value was plainly
- * there. The nesting is flattened here, at the boundary that owns the
- * serialization, rather than at each caller: one level, in order, and a record
- * two linked rows both point at is one link, so ids repeat at most once.
- * Anything else still reads as empty.
- */
-export declare function readLinks(v: unknown): ResolvedLink[];
-/**
- * A `files`-field cell entry, as the app query serializes it. The server
- * presigns each file (24h) so `url`/`thumbnail_url` load directly — including
- * from the sandboxed app iframe and for public apps — so the app can preview or
- * download without deriving its own URL.
- */
-export interface AppFile {
-    id: string;
-    filename: string;
-    mime_type: string;
-    /** Presigned serving URL — render in an <Image>/preview or pass to openExternal. */
-    url: string;
-    /** Presigned thumbnail URL for images, when the server produced one. */
-    thumbnail_url?: string;
-    /** Byte size of the file, resolved from the file object at serving time. Absent
-     *  for older files not yet backfilled — show a size only when present. Prefer a
-     *  dedicated sortable `Table` column over the RAW number (the `tpl_record`
-     *  documents register: a right-aligned "Size" column, formatted at display) —
-     *  not a crammed `FileRow` meta string, which sorts wrong ("8.4 MB" < "96 KB"). */
-    size?: number | null;
-    /** ISO upload timestamp (date-added), resolved at serving time. Show as a
-     *  dedicated "Added" `Table` column (format with `formatDate`), sortable over the
-     *  raw ISO value. */
-    created_at?: string;
-}
-/**
- * files field → the attached files with their presigned `url` (empty if none).
- * Skips entries the server didn't presign (no `url`) so a consumer never renders
- * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
- * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
- * it per app.
- *
- * A LOOKUP OF A FILES FIELD ARRIVES ONE LEVEL DEEPER, exactly as a lookup of a
- * link field does (see {@link readLinks}) — the cell holds one entry per linked
- * record and each entry is THAT record's whole files cell, an array — so read
- * entry-by-entry it decoded to nothing while the pictures were plainly there,
- * and every mark drawn off a looked-up photograph fell back to its glyph. The
- * nesting is flattened here, at the boundary that owns the serialization, rather
- * than at each caller: one level, in the order the rows link, and a file two
- * linked rows both carry is one file, so ids repeat at most once.
- */
-export declare function readFiles(v: unknown): AppFile[];
-/**
- * Record lock state for a `useQuery` row. The query layer emits a row-level
- * `__source_locked` addressing column (alongside `__source_record_id`). A locked
- * record rejects direct writes, so an app reads this to show a locked state and
- * route edits through a `request_locked_field_change` workflow instead of an
- * `update_records` save. Pass the whole row (not a cell). False for any
- * non-object / absent flag.
- */
-export declare function readLocked(rowValue: unknown): boolean;
-/**
- * When the record behind this row was created — the row-level `__created_at`
- * column the compiler emits on every row-level query result. It is a DISPLAY
- * value, so a table with no date field of its own still has a chronological
- * anchor (a kardex date, an "as of" caption) with no schema change. Absent on a
- * grouped/aggregated row, which has no originating record.
- */
-export declare function readCreatedAt(rowValue: unknown): Date | null;
-/** When the record behind this row was last updated — the `__updated_at`
- *  sibling of {@link readCreatedAt}. */
-export declare function readUpdatedAt(rowValue: unknown): Date | null;
-export declare const row: {
-    opt: typeof opt;
-    text: typeof text;
-    num: typeof num;
-    bool: typeof bool;
-    date: typeof date;
-    datetime: typeof datetime;
-    link: typeof link;
-};
-export {};

package/dist/src/row.js

@@ -1,254 +0,0 @@
-/**
- * Accessors that coerce raw `useQuery` row values into typed values. Each cell
- * of a query row is `unknown`: the query layer serializes a select column as a
- * `{ key, label }` array (one entry per selected option), a date/datetime as a
- * `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
- *
- * These live in app-sdk — next to `useQuery`, whose serialization contract they
- * decode — so a change to that contract updates them in one place, and so apps
- * stop re-implementing the same coercions. They are pure (`unknown` in, value
- * out) and never throw.
- */
-/**
- * Select → first option key. Reads the enriched `{ key, label }` shape (and the
- * legacy bare id / single-element array / `{ id }` shapes for back-compat).
- * Use `readSelect` for the full `{ key, label }[]` on multi-select cells.
- */
-function opt(v) {
-    if (typeof v === "string")
-        return v || null;
-    if (Array.isArray(v))
-        return v.length ? opt(v[0]) : null;
-    if (v && typeof v === "object") {
-        const key = v.key;
-        if (typeof key === "string")
-            return key || null;
-        const id = v.id;
-        return typeof id === "string" ? id || null : null;
-    }
-    return null;
-}
-/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
-function text(v) {
-    if (typeof v === "string")
-        return v;
-    if (typeof v === "number" && Number.isFinite(v))
-        return String(v);
-    return "";
-}
-/**
- * Number → number, or `null` when the cell holds no number — an empty cell, a
- * NaN/Infinity, an unparseable string. Empty and zero usually mean opposite
- * things ("not priced yet" vs "free", "no reading" vs "a reading of 0"), so the
- * absence is preserved the way `date` preserves it. Write `?? 0` where 0 IS the
- * correct reading of an empty cell (a sum, a count).
- */
-function num(v) {
-    if (typeof v === "number")
-        return Number.isFinite(v) ? v : null;
-    if (typeof v === "string" && v.trim()) {
-        const n = Number(v);
-        return Number.isFinite(n) ? n : null;
-    }
-    return null;
-}
-/**
- * Checkbox/boolean → `true` / `false`, or `null` when the cell holds neither —
- * an empty cell, a value of another kind. (The strings "true"/"false" decode.)
- *
- * AN UNANSWERED CHECKBOX IS NOT A "NO", exactly as an empty number cell is not a
- * 0: the field's default is what the workspace writes when a row states
- * something, and a row nobody has answered states nothing. Read as `false` it
- * drew "No" for every partner nobody had assessed — the rows a gate exists to
- * catch are precisely the ones that answer nothing — so the absence is preserved
- * the way `num` and `date` preserve theirs. Write `=== true` where only the
- * affirmative acts, `?? false` where the safe side IS the reading.
- */
-function bool(v) {
-    if (v === true || v === "true")
-        return true;
-    if (v === false || v === "false")
-        return false;
-    return null;
-}
-/**
- * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
- * calendar/gantt placement never shifts across timezones. Parses the leading
- * `YYYY[-MM[-DD]]` of the serialized string — a reduced-precision `date` value
- * ("2026-05" / "2026") decodes to its PERIOD START (missing month/day → 1)
- * rather than vanishing to null. Null only if absent or unparseable. (Range
- * fields are not handled here — they have no consumer yet.)
- */
-function date(v) {
-    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?/.exec(text(v));
-    if (!m)
-        return null;
-    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1);
-}
-/**
- * Date/datetime field → a LOCAL Date that KEEPS the stored wall-clock time, so
- * `getHours()` / `toLocaleTimeString()` render the time as written. The stored
- * value is a timezone-less workspace wall-clock (see the serialization note
- * above), so it is read verbatim — no UTC conversion. Use this when the time
- * matters (a check-in time, an appointment); `date` keeps only the calendar day.
- * Parses `YYYY[-MM[-DD]]` with an optional `T`-or-space `HH:mm[:ss]`; a missing
- * month/day is the period start (1) and a missing time is midnight — a
- * reduced-precision value decodes rather than vanishing. Null if absent or
- * unparseable.
- */
-function datetime(v) {
-    const m = /^(\d{4})(?:-(\d{2}))?(?:-(\d{2}))?(?:[ T](\d{2}):(\d{2}))?/.exec(text(v));
-    if (!m)
-        return null;
-    return new Date(Number(m[1]), (m[2] ? Number(m[2]) : 1) - 1, m[3] ? Number(m[3]) : 1, m[4] ? Number(m[4]) : 0, m[5] ? Number(m[5]) : 0);
-}
-/**
- * One `{ id, display }` object → ResolvedLink, or null if absent/malformed.
- *
- * A MISSING `display` IS NOT A LINK. Other cells carry `{ id }` without one — a
- * member is the everyday case — and answering `display: ""` for them made every
- * assignee read as a blank-named link wherever a reader tried links first. A
- * link the server resolved always states its display, even as the empty string,
- * so requiring the KEY costs a real link nothing.
- */
-function asLink(v) {
-    if (!v || typeof v !== "object")
-        return null;
-    const id = v.id;
-    if (typeof id !== "string" || !id)
-        return null;
-    const display = v.display;
-    return typeof display === "string" ? { id, display } : null;
-}
-/**
- * select_record_link → the FIRST linked record as `{ id, display }` (or null).
- * The common single-link case: read `.display` to render the linked record's
- * name, `.id` to correlate/filter (e.g. group rows by a parent record). Use
- * `readLinks` for the full list on multi-link fields.
- */
-function link(v) {
-    return readLinks(v)[0] ?? null;
-}
-/**
- * select_record_link → ALL linked records as `{ id, display }[]` (empty if none).
- *
- * A LOOKUP OF A LINK FIELD ARRIVES ONE LEVEL DEEPER — the cell holds one entry
- * per linked record and each entry is THAT record's whole link cell, an array —
- * so read entry-by-entry it decoded to nothing while the value was plainly
- * there. The nesting is flattened here, at the boundary that owns the
- * serialization, rather than at each caller: one level, in order, and a record
- * two linked rows both point at is one link, so ids repeat at most once.
- * Anything else still reads as empty.
- */
-export function readLinks(v) {
-    const cell = Array.isArray(v) ? v : [v];
-    const out = [];
-    const seen = new Set();
-    for (const entry of cell) {
-        const held = Array.isArray(entry) ? entry : [entry];
-        for (const one of held) {
-            const linked = asLink(one);
-            if (linked === null || seen.has(linked.id))
-                continue;
-            seen.add(linked.id);
-            out.push(linked);
-        }
-    }
-    return out;
-}
-/**
- * files field → the attached files with their presigned `url` (empty if none).
- * Skips entries the server didn't presign (no `url`) so a consumer never renders
- * an unservable file. Pass one to `toDisplayFile` from `@lotics/ui/file_thumbnail`
- * for FileThumbnail/Gallery — the kit owns that conversion, so don't re-declare
- * it per app.
- *
- * A LOOKUP OF A FILES FIELD ARRIVES ONE LEVEL DEEPER, exactly as a lookup of a
- * link field does (see {@link readLinks}) — the cell holds one entry per linked
- * record and each entry is THAT record's whole files cell, an array — so read
- * entry-by-entry it decoded to nothing while the pictures were plainly there,
- * and every mark drawn off a looked-up photograph fell back to its glyph. The
- * nesting is flattened here, at the boundary that owns the serialization, rather
- * than at each caller: one level, in the order the rows link, and a file two
- * linked rows both carry is one file, so ids repeat at most once.
- */
-export function readFiles(v) {
-    if (!Array.isArray(v))
-        return [];
-    const out = [];
-    const seen = new Set();
-    for (const entry of v) {
-        const held = Array.isArray(entry) ? entry : [entry];
-        for (const f of held) {
-            if (!f || typeof f !== "object")
-                continue;
-            const id = f.id;
-            const url = f.url;
-            if (typeof id !== "string" || !id || typeof url !== "string" || !url || seen.has(id))
-                continue;
-            seen.add(id);
-            const filename = f.filename;
-            const mime = f.mime_type;
-            const thumb = f.thumbnail_url;
-            const size = f.size;
-            const created_at = f.created_at;
-            out.push({
-                id,
-                filename: typeof filename === "string" ? filename : "",
-                mime_type: typeof mime === "string" ? mime : "",
-                url,
-                thumbnail_url: typeof thumb === "string" ? thumb : undefined,
-                size: typeof size === "number" ? size : undefined,
-                created_at: typeof created_at === "string" ? created_at : undefined,
-            });
-        }
-    }
-    return out;
-}
-/**
- * Record lock state for a `useQuery` row. The query layer emits a row-level
- * `__source_locked` addressing column (alongside `__source_record_id`). A locked
- * record rejects direct writes, so an app reads this to show a locked state and
- * route edits through a `request_locked_field_change` workflow instead of an
- * `update_records` save. Pass the whole row (not a cell). False for any
- * non-object / absent flag.
- */
-export function readLocked(rowValue) {
-    if (!rowValue || typeof rowValue !== "object")
-        return false;
-    // A row that says NOTHING about its lock is not locked — this is the flag's
-    // absence, not a record's unanswered question, so the safe side is the reading.
-    return bool(rowValue["__source_locked"]) === true;
-}
-/**
- * The stored record's timestamp on a `useQuery` row, read off the addressing
- * column named. Unlike a `date`/`datetime` CELL — a timezone-less workspace
- * wall-clock at minute precision — these are true INSTANTS (ISO-8601 with an
- * offset), so they are parsed as such and render in the viewer's zone. Pass the
- * whole row (not a cell). Null for any non-object / absent / unparseable value.
- */
-function rowInstant(rowValue, column) {
-    if (!rowValue || typeof rowValue !== "object")
-        return null;
-    const raw = rowValue[column];
-    if (typeof raw !== "string" || !raw)
-        return null;
-    const d = new Date(raw);
-    return Number.isNaN(d.getTime()) ? null : d;
-}
-/**
- * When the record behind this row was created — the row-level `__created_at`
- * column the compiler emits on every row-level query result. It is a DISPLAY
- * value, so a table with no date field of its own still has a chronological
- * anchor (a kardex date, an "as of" caption) with no schema change. Absent on a
- * grouped/aggregated row, which has no originating record.
- */
-export function readCreatedAt(rowValue) {
-    return rowInstant(rowValue, "__created_at");
-}
-/** When the record behind this row was last updated — the `__updated_at`
- *  sibling of {@link readCreatedAt}. */
-export function readUpdatedAt(rowValue) {
-    return rowInstant(rowValue, "__updated_at");
-}
-export const row = { opt, text, num, bool, date, datetime, link };

package/dist/src/rpc.d.ts

@@ -1,207 +0,0 @@
-import type { AskUserChoiceOutput } from "./agent_stream.js";
-import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
-/**
- * RPC bridge for a custom-code app's data operations.
- *
- * An app reaches the Lotics API one of two ways, chosen automatically:
- *
- *  - **Bridged** — the app is embedded by a Lotics host (the authenticated
- *    product, or `lotics app dev`), which passes its origin via the
- *    `?lotics_host=` query param. The host holds the session; the app posts
- *    ops over postMessage and the host makes the API call. Used by internal
- *    apps — the member's credentials must never reach the app.
- *
- *  - **Standalone** — the app is served on its own origin, with no host. It
- *    calls the public `/v1/apps/{id}/*` endpoints directly, at the API address
- *    the serving host injected into the page (`API_BASE_META`); those are
- *    anonymous-accessible for a publicly-shared app. The app holds no
- *    credentials, so there is nothing to protect.
- *
- * Wire protocol (bridged — must match `app_iframe_host.tsx`):
- *   app  → host: { id, op, payload }
- *   host → app:  { id, type: "result", data } | { id, type: "error", message }
- */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "recording.start" | "recording.stop";
-/** Payload for starting a streaming agent run. */
-export interface AgentRunPayload {
-    alias: string;
-    session_id: string;
-    input: Record<string, unknown>;
-}
-/** Handle to a running stream — `done` settles at the end (or rejects on
- *  error); `abort` stops it. The caller feeds each text chunk to the parser. */
-export interface AgentRunHandle {
-    done: Promise<void>;
-    abort: () => void;
-}
-/**
- * The app's identity, resolved once at startup to tag PostHog events.
- * Assembled by whichever transport is active:
- *
- *  - **Bridged** — the host (authenticated) supplies `member_id`, plus
- *    org/workspace/app from its own context.
- *  - **Standalone** — the public `/by-subdomain` endpoint returns identity;
- *    `member_id` is null (anonymous visitor).
- */
-/** A raw reference to one record — table + record id, passed through UNRESOLVED.
- *  The member's own chat agent may act on it only where that member's IAM already
- *  allows; the app never resolves it into data here. */
-export interface AiContextRecordRef {
-    table_id: string;
-    record_id: string;
-}
-/**
- * A snapshot of what the app RENDERED to this member on the current screen —
- * published to the ambient app chat agent via `useAiContext` so the member's
- * agent knows what they are looking at. Push-only: this is data the app already
- * showed, never a channel for chat to pull app-authority data back out.
- */
-export interface AiContextValue {
-    /** Human-readable summary of the view — enters the agent prompt as labeled
-     *  DATA (never instructions). Host-capped to 1000 chars. */
-    description: string;
-    /** Records the screen is showing, as raw `{ table_id, record_id }` refs
-     *  (unresolved). Host-capped to 20. */
-    records?: AiContextRecordRef[];
-    /** Optional structured detail (filters, sort, form values). Host JSON-encodes
-     *  it and DROPS the field past its size cap, keeping the description. */
-    data?: unknown;
-}
-/** A fire-and-forget notification the app pushes UP to its embedding host — no
- *  id, no reply, distinct from the request/reply `rpc()` bridge. */
-export type HostNotification = {
-    type: "aiContext";
-    slot: string;
-    context: AiContextValue | null;
-};
-export interface AppContext {
-    member_id: string | null;
-    /**
-     * Whether the app declared the `comments` capability. `useComments` is
-     * available only when this is true AND a member is signed in. False for any
-     * app that didn't opt in, and (vacuously) for standalone visitors.
-     */
-    comments_enabled: boolean;
-    /**
-     * Whether this host records for the app: true only from a host that has the
-     * `recording.*` ops, for a signed-in member, on an instance that transcribes.
-     * A host that predates recording omits it, which reads as false.
-     */
-    recording_enabled?: boolean;
-    /** The recordings this app started that the host still tracks, by alias —
-     *  the state a newly loaded frame starts from. */
-    recordings?: Record<string, unknown>;
-}
-/**
- * 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 declare function isEmbedded(): boolean;
-export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;
-/** Read the current app-owned query params — bridged: ask the host; standalone:
- *  the page's own query string. */
-export declare function getUrlParams(): Promise<UrlParams>;
-/** 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 declare function setUrlParams(patch: UrlParamsPatch): Promise<void>;
-/** 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 declare function peekUrlParams(): UrlParams;
-/** Subscribe to external query changes — browser back/forward and edited URLs.
- *  Embedded: the host's `url-state` broadcast; standalone: `popstate`. */
-export declare function subscribeUrlParams(cb: (params: UrlParams) => void): () => void;
-/**
- * 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 declare function postHostNotification(message: HostNotification): void;
-/**
- * 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 declare function subscribeQueriesChanged(cb: (aliases: string[]) => void): () => void;
-/** Register a mounted query's alias. Returns the matching unregister. */
-export declare function registerQueryAlias(alias: string): () => void;
-/**
- * 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 declare function notifyLocalWrite(): void;
-/**
- * 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 declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;
-export interface AgentRunContinuePayload {
-    run_id: string;
-    tool_call_id: string;
-    /** The `ask_user_choice` output the user assembled (validated server-side). */
-    output: AskUserChoiceOutput;
-}
-/**
- * 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 declare function rpcAgentRunContinue(payload: AgentRunContinuePayload, onText: (chunk: string) => void): AgentRunHandle;
-/**
- * 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 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 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 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>;