@lotics/cli 0.185.0 → 0.187.0

package/dist/src/client.js

@@ -1,914 +1,1055 @@
-import { transportErrorMessage } from "@lotics/shared/transport_error";
+// ../shared/src/transport_error.ts
+function gatewayErrorMessage(status) {
+  if (status === 524) {
+    return "The request took too long to finish (gateway timeout). It may still be running \u2014 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.";
+}
+function transportErrorMessage(status, parsed) {
+  const jsonMessage = parsed && typeof parsed.message === "string" ? parsed.message : null;
+  if (jsonMessage === null) return gatewayErrorMessage(status);
+  const authored = typeof parsed.code === "string" && parsed.code.length > 0;
+  return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
+}
+
+// ../shared/src/multipart_parts.ts
+var DEFAULT_MAX_RETRIES = 5;
+var MAX_RETRY_DELAY_MS = 15e3;
+var TIMEOUT_BASE_MS = 3e4;
+var TIMEOUT_PER_MB_MS = 15e3;
+function partTimeoutMs(partSizeBytes) {
+  return TIMEOUT_BASE_MS + Math.ceil(partSizeBytes / (1024 * 1024)) * TIMEOUT_PER_MB_MS;
+}
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var PermanentPartError = class extends Error {
+};
+function isRetryableStatus(status) {
+  return status >= 500 || status === 408 || status === 429;
+}
+function partErrorFor(partNumber, status) {
+  const message = `part ${partNumber} rejected by storage (${status})`;
+  return isRetryableStatus(status) ? new Error(message) : new PermanentPartError(message);
+}
+async function uploadParts(options) {
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const concurrency = Math.max(1, options.concurrency ?? 1);
+  const done = [...options.alreadyUploaded ?? []];
+  const finished = new Set(done.map((part) => part.part_number));
+  const queue = options.parts.filter((part) => !finished.has(part.part_number));
+  const uploadOne = async (part) => {
+    const bytes = options.partBytes(part);
+    for (let attempt = 1; ; attempt += 1) {
+      options.signal?.throwIfAborted();
+      try {
+        const timeout = AbortSignal.timeout(partTimeoutMs(bytes));
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        const etag = await options.putPart(part, await options.readPart(part), signal);
+        if (!etag) {
+          throw new PermanentPartError(`part ${part.part_number} stored without an ETag`);
+        }
+        return { part_number: part.part_number, etag };
+      } catch (error) {
+        if (options.signal?.aborted) throw error;
+        if (error instanceof PermanentPartError) throw error;
+        if (attempt >= maxRetries) {
+          options.onExhausted?.({ partNumber: part.part_number, attempts: attempt, error });
+          throw error;
+        }
+        options.onRetry?.({ partNumber: part.part_number, attempt, error });
+        const base = 1e3 * 2 ** (attempt - 1);
+        await sleep(Math.min(base + Math.random() * base * 0.5, MAX_RETRY_DELAY_MS));
+      }
+    }
+  };
+  const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+    for (let next = queue.shift(); next !== void 0; next = queue.shift()) {
+      const part = await uploadOne(next);
+      done.push(part);
+      options.onPartUploaded?.(part);
+    }
+  });
+  await Promise.all(workers);
+  return done.sort((a, b) => a.part_number - b.part_number);
+}
+
+// src/client.ts
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { getInvocation } from "./invocation.js";
-/**
- * The filename a `Content-Disposition` names, preferring RFC 5987 `filename*`.
- *
- * The server always sends BOTH: `filename*=UTF-8''…` carrying the real name,
- * and a plain `filename=` whose non-ASCII characters are replaced with `_`
- * because HTTP header values are Latin-1. Reading only the plain one turned
- * every accented name into underscores on the way to disk — `GIẤY YÊU CẦU.doc`
- * saved as `GI_Y Y_U C_U.doc` — even though the correct bytes were in the same
- * header. The `*` form wins whenever it parses; the plain form is the fallback
- * it was always meant to be.
- */
+
+// src/invocation.ts
+var invocation = null;
+function getInvocation() {
+  return invocation;
+}
+var IDLE_GAP_MS = 30 * 60 * 1e3;
+
+// src/client.ts
 function parseContentDispositionFilename(disposition) {
-    const extended = disposition.match(/filename\*=\s*([^']*)'[^']*'([^;\n]+)/i);
-    if (extended) {
-        try {
-            return decodeURIComponent(extended[2].trim());
-        }
-        catch {
-            // A malformed percent-escape means this parameter is unusable, not that
-            // the whole header is — fall through to the ASCII form below.
-        }
+  const extended = disposition.match(/filename\*=\s*([^']*)'[^']*'([^;\n]+)/i);
+  if (extended) {
+    try {
+      return decodeURIComponent(extended[2].trim());
+    } catch {
     }
-    const plain = disposition.match(/filename=\s*"?([^";\n]+)"?/i);
-    return plain ? plain[1].trim() : null;
+  }
+  const plain = disposition.match(/filename=\s*"?([^";\n]+)"?/i);
+  return plain ? plain[1].trim() : null;
 }
 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
-    // yet when a peer call races to pick a name.
-    const isTaken = (name) => {
-        const full = path.join(dir, name);
-        if (reserved?.has(full))
-            return true;
-        return fs.existsSync(full);
-    };
-    const claim = (name) => {
-        reserved?.add(path.join(dir, name));
-        return name;
-    };
-    if (!isTaken(filename))
-        return claim(filename);
-    const lastDot = filename.lastIndexOf(".");
-    const base = lastDot > 0 ? filename.slice(0, lastDot) : filename;
-    const ext = lastDot > 0 ? filename.slice(lastDot) : "";
-    let n = 2;
-    while (isTaken(`${base}_${n}${ext}`))
-        n++;
-    return claim(`${base}_${n}${ext}`);
+  const isTaken = (name) => {
+    const full = path.join(dir, name);
+    if (reserved?.has(full)) return true;
+    return fs.existsSync(full);
+  };
+  const claim = (name) => {
+    reserved?.add(path.join(dir, name));
+    return name;
+  };
+  if (!isTaken(filename)) return claim(filename);
+  const lastDot = filename.lastIndexOf(".");
+  const base = lastDot > 0 ? filename.slice(0, lastDot) : filename;
+  const ext = lastDot > 0 ? filename.slice(lastDot) : "";
+  let n = 2;
+  while (isTaken(`${base}_${n}${ext}`)) n++;
+  return claim(`${base}_${n}${ext}`);
 }
-const MIME_MAP = {
-    ".jpg": "image/jpeg",
-    ".jpeg": "image/jpeg",
-    ".png": "image/png",
-    ".gif": "image/gif",
-    ".webp": "image/webp",
-    ".svg": "image/svg+xml",
-    ".pdf": "application/pdf",
-    ".csv": "text/csv",
-    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-    ".txt": "text/plain",
-    ".json": "application/json",
-    ".html": "text/html",
-    ".xml": "application/xml",
-    ".zip": "application/zip",
+var MIME_MAP = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".csv": "text/csv",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".html": "text/html",
+  ".xml": "application/xml",
+  ".zip": "application/zip"
 };
 function getMimeType(filename) {
-    const ext = path.extname(filename).toLowerCase();
-    return MIME_MAP[ext] ?? "application/octet-stream";
+  const ext = path.extname(filename).toLowerCase();
+  return MIME_MAP[ext] ?? "application/octet-stream";
 }
-export const API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
-/**
- * Where a person goes when the CLI cannot finish the job — the one case being a
- * returning user on a machine that holds no key, since every route back in
- * needs one. Held beside the API base so the pair is read together, and named
- * once rather than inlined at each message that has to point somewhere.
- */
-export const WEB_APP_URL = "https://lotics.ai";
-/**
- * The starters Lotics publishes, fetched with no credential.
- *
- * A plain function rather than a `LoticsClient` method because there is no key
- * to build a client around — and that is the point of the endpoint. "Is there a
- * starter for what I do, or should I build?" is decided before an account
- * exists, so needing one to ask means signing up to find out the answer was no.
- */
-export async function fetchOfficialStarters() {
-    // Bounded, because this is the FIRST command a new user runs and a hang with
-    // nothing on screen is the worst version of the failure. `config.ts` bounds
-    // its own unattended fetch for the same reason; `docs/network_reliability.md`
-    // is a log of connections from our users' networks degrading rather than
-    // refusing, which is the shape that hangs.
-    let response;
-    try {
-        response = await fetch(`${API_BASE_URL}/v1/starters/official`, {
-            signal: AbortSignal.timeout(SHELF_FETCH_TIMEOUT_MS),
-        });
-    }
-    catch (error) {
-        // Nothing answered. This is the only branch where "check your connection"
-        // is true — a status code below means the server replied and the network is
-        // demonstrably fine.
-        throw new Error(`Could not reach Lotics to list the starters (${error instanceof Error ? error.message : String(error)}). ` +
-            `Check your connection, or browse ${WEB_APP_URL}/docs/cli.`);
-    }
-    if (!response.ok) {
-        throw new Error(`Lotics answered ${response.status} listing the starters. ` +
-            `If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`);
-    }
-    return (await response.json());
+var MULTIPART_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var API_BASE_URL = process.env.LOTICS_API_URL ?? "https://api.lotics.ai";
+var WEB_APP_URL = "https://lotics.ai";
+async function fetchOfficialStarters() {
+  let response;
+  try {
+    response = await fetch(`${API_BASE_URL}/v1/starters/official`, {
+      signal: AbortSignal.timeout(SHELF_FETCH_TIMEOUT_MS)
+    });
+  } catch (error) {
+    throw new Error(
+      `Could not reach Lotics to list the starters (${error instanceof Error ? error.message : String(error)}). Check your connection, or browse ${WEB_APP_URL}/docs/cli.`
+    );
+  }
+  if (!response.ok) {
+    throw new Error(
+      `Lotics answered ${response.status} listing the starters. If this keeps happening, browse ${WEB_APP_URL}/docs/cli.`
+    );
+  }
+  return await response.json();
 }
-/** Long enough for a slow link, short enough that a dead one still says so. */
-const SHELF_FETCH_TIMEOUT_MS = 10_000;
-/**
- * A short id for one request, short because a person has to read it back to us.
- *
- * Not `generateLocalId` from `@lotics/shared`: this file is the UNBUNDLED
- * library entry, so every bare specifier it imports has to resolve from a
- * package whose `dependencies` are empty. `node:crypto` is a builtin and costs
- * nothing, and the server treats the header as opaque — it logs whatever
- * arrives, so matching its id ALPHABET buys nothing.
- */
+var SHELF_FETCH_TIMEOUT_MS = 1e4;
 function newRequestId() {
-    return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
+  return crypto.randomUUID().replace(/-/g, "").slice(0, 12);
 }
-export class LoticsClient {
-    apiKey;
-    workspaceId;
-    /** The active "View as" target member id, if any. Read-only after
-     *  construction — surfaced so `lotics app dev` can show it in the banner. */
-    viewAsMemberId;
-    /** API URL the client is configured against. Read-only after construction.
-     *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
-     *  shows it in the banner). */
-    baseUrl;
-    constructor(options) {
-        this.apiKey = options.apiKey;
-        this.workspaceId = options.workspaceId;
-        this.viewAsMemberId = options.viewAsMemberId;
-        this.baseUrl = API_BASE_URL;
-    }
-    /**
-     * The id is appended to the MESSAGE rather than carried on a field, because
-     * the only thing that reliably reaches a person is what got printed: the CLI's
-     * top-level handler writes `error.message` to stderr, and the telemetry tail
-     * captures the same bytes. A field would have to be read by every one of ~60
-     * exit sites to be worth anything.
-     *
-     * `requestId` is optional because one caller legitimately has none — a
-     * presigned CDN download is not a request of ours and appears in none of our
-     * logs. Every call against the API passes the id its own headers carry.
-     */
-    async throwResponseError(response, requestId) {
-        const text = await response.text();
-        let message;
-        try {
-            const json = JSON.parse(text);
-            message = json.message ?? text;
-        }
-        catch {
-            message = text;
-        }
-        const trace = requestId === undefined ? "" : `\n\n  Request id: ${requestId} — quote this to Lotics support.`;
-        throw new Error(`${response.status}: ${message}${trace}`);
-    }
-    /**
-     * The backend's `log()` middleware registers `user-agent`,
-     * `x-posthog-session-id` and `x-request-id` onto the per-request Logger, so
-     * they ride EVERY log line that request emits — the validation 400, the tool
-     * error, the timing. Sending them is therefore the whole of the correlation
-     * work: it turns an anonymous API-key request into "`app workflow set`, from
-     * cli 0.117.0, the fourth command of this session".
-     *
-     * The request id is minted HERE, with the other headers, so it cannot reach
-     * some paths and not others: several commands build their own transport around
-     * these headers, and an id threaded only through `request` would leave
-     * `app deploy`, `uploadFiles` and every workflow call unfindable.
-     */
-    buildHeaders() {
-        const invocation = getInvocation();
-        const headers = {
-            "Authorization": `Bearer ${this.apiKey}`,
-            // Unversioned when the SDK is used as a library — there is no CLI process
-            // whose version to name, and a wrong one is worse than none.
-            "user-agent": invocation?.userAgent ?? "lotics-cli",
-        };
-        if (this.workspaceId) {
-            headers["x-workspace-id"] = this.workspaceId;
-        }
-        if (this.viewAsMemberId) {
-            headers["x-view-as-member-id"] = this.viewAsMemberId;
-        }
-        if (invocation) {
-            headers["x-lotics-cli-command"] = invocation.command;
-            if (invocation.session !== null) {
-                headers["x-posthog-session-id"] = invocation.session;
-            }
-        }
-        // Unconditional, unlike the session header: this describes the request
-        // rather than tracking anyone, and it is what makes a failure findable.
-        headers["x-request-id"] = newRequestId();
-        return headers;
-    }
-    async request(method, path, body) {
-        const url = `${this.baseUrl}${path}`;
-        const headers = this.buildHeaders();
-        const init = { method, headers };
-        if (body !== undefined) {
-            headers["Content-Type"] = "application/json";
-            init.body = JSON.stringify(body);
-        }
-        const response = await fetch(url, init);
-        if (!response.ok)
-            await this.throwResponseError(response, headers["x-request-id"]);
+var LoticsClient = class {
+  apiKey;
+  workspaceId;
+  /** The active "View as" target member id, if any. Read-only after
+   *  construction — surfaced so `lotics app dev` can show it in the banner. */
+  viewAsMemberId;
+  /** API URL the client is configured against. Read-only after construction.
+   *  Surfaced for callers that need to display or log it (e.g., `lotics app dev`
+   *  shows it in the banner). */
+  baseUrl;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.workspaceId = options.workspaceId;
+    this.viewAsMemberId = options.viewAsMemberId;
+    this.baseUrl = API_BASE_URL;
+  }
+  /**
+   * The id is appended to the MESSAGE rather than carried on a field, because
+   * the only thing that reliably reaches a person is what got printed: the CLI's
+   * top-level handler writes `error.message` to stderr, and the telemetry tail
+   * captures the same bytes. A field would have to be read by every one of ~60
+   * exit sites to be worth anything.
+   *
+   * `requestId` is optional because one caller legitimately has none — a
+   * presigned CDN download is not a request of ours and appears in none of our
+   * logs. Every call against the API passes the id its own headers carry.
+   */
+  async throwResponseError(response, requestId) {
+    const text = await response.text();
+    let message;
+    try {
+      const json = JSON.parse(text);
+      message = json.message ?? text;
+    } catch {
+      message = text;
+    }
+    const trace = requestId === void 0 ? "" : `
+
+  Request id: ${requestId} \u2014 quote this to Lotics support.`;
+    throw new Error(`${response.status}: ${message}${trace}`);
+  }
+  /**
+   * The backend's `log()` middleware registers `user-agent`,
+   * `x-posthog-session-id` and `x-request-id` onto the per-request Logger, so
+   * they ride EVERY log line that request emits — the validation 400, the tool
+   * error, the timing. Sending them is therefore the whole of the correlation
+   * work: it turns an anonymous API-key request into "`app workflow set`, from
+   * cli 0.117.0, the fourth command of this session".
+   *
+   * The request id is minted HERE, with the other headers, so it cannot reach
+   * some paths and not others: several commands build their own transport around
+   * these headers, and an id threaded only through `request` would leave
+   * `app deploy`, `uploadFiles` and every workflow call unfindable.
+   */
+  buildHeaders() {
+    const invocation2 = getInvocation();
+    const headers = {
+      "Authorization": `Bearer ${this.apiKey}`,
+      // Unversioned when the SDK is used as a library — there is no CLI process
+      // whose version to name, and a wrong one is worse than none.
+      "user-agent": invocation2?.userAgent ?? "lotics-cli"
+    };
+    if (this.workspaceId) {
+      headers["x-workspace-id"] = this.workspaceId;
+    }
+    if (this.viewAsMemberId) {
+      headers["x-view-as-member-id"] = this.viewAsMemberId;
+    }
+    if (invocation2) {
+      headers["x-lotics-cli-command"] = invocation2.command;
+      if (invocation2.session !== null) {
+        headers["x-posthog-session-id"] = invocation2.session;
+      }
+    }
+    headers["x-request-id"] = newRequestId();
+    return headers;
+  }
+  async request(method, path2, body) {
+    const url = `${this.baseUrl}${path2}`;
+    const headers = this.buildHeaders();
+    const init = { method, headers };
+    if (body !== void 0) {
+      headers["Content-Type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const response = await fetch(url, init);
+    if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
+    return response.json();
+  }
+  async whoami() {
+    return this.request("GET", "/v1/cli/whoami");
+  }
+  /**
+   * File a hand-written report. Unlike a telemetry flush, the headers this
+   * stamps are CORRECT: the invocation making the request is the one the report
+   * is about, so the courier and the cargo are the same session.
+   */
+  async sendReport(body) {
+    return this.request("POST", "/v1/cli/report", body);
+  }
+  setWorkspaceId(id) {
+    this.workspaceId = id;
+  }
+  /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
+  getWorkspaceId() {
+    return this.workspaceId;
+  }
+  async listWorkspaces() {
+    return this.request("GET", "/v1/workspaces");
+  }
+  async createWorkspace(body) {
+    return this.request("POST", "/v1/workspaces", body);
+  }
+  /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
+   *  target from the request's workspace, never a path id. */
+  async updateWorkspace(body) {
+    return this.request("PATCH", "/v1/workspace", body);
+  }
+  async deleteWorkspace(id) {
+    return this.request("DELETE", `/v1/workspaces/${encodeURIComponent(id)}`);
+  }
+  async login(body) {
+    return this.request("POST", "/v1/cli/login", body ?? {});
+  }
+  async listTools() {
+    return this.request("GET", "/v1/tools");
+  }
+  async getTool(name) {
+    return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
+  }
+  async execute(tool, args, options) {
+    const body = { tool, args, format: options?.format ?? "text" };
+    if (options?.timeoutMs) {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
+      try {
+        const url = `${this.baseUrl}/v1/tools/execute`;
+        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
+        const response = await fetch(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
         return response.json();
-    }
-    async whoami() {
-        return this.request("GET", "/v1/cli/whoami");
-    }
-    /**
-     * File a hand-written report. Unlike a telemetry flush, the headers this
-     * stamps are CORRECT: the invocation making the request is the one the report
-     * is about, so the courier and the cargo are the same session.
-     */
-    async sendReport(body) {
-        return this.request("POST", "/v1/cli/report", body);
-    }
-    setWorkspaceId(id) {
-        this.workspaceId = id;
-    }
-    /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
-    getWorkspaceId() {
-        return this.workspaceId;
-    }
-    async listWorkspaces() {
-        return this.request("GET", "/v1/workspaces");
-    }
-    async createWorkspace(body) {
-        return this.request("POST", "/v1/workspaces", body);
-    }
-    /** Renames (and re-settings) the CURRENT workspace — the endpoint reads the
-     *  target from the request's workspace, never a path id. */
-    async updateWorkspace(body) {
-        return this.request("PATCH", "/v1/workspace", body);
-    }
-    async deleteWorkspace(id) {
-        return this.request("DELETE", `/v1/workspaces/${encodeURIComponent(id)}`);
-    }
-    async login(body) {
-        return this.request("POST", "/v1/cli/login", body ?? {});
-    }
-    async listTools() {
-        return this.request("GET", "/v1/tools");
-    }
-    async getTool(name) {
-        return this.request("GET", `/v1/tools/${encodeURIComponent(name)}`);
-    }
-    async execute(tool, args, options) {
-        const body = { tool, args, format: options?.format ?? "text" };
-        if (options?.timeoutMs) {
-            const controller = new AbortController();
-            const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
-            try {
-                const url = `${this.baseUrl}/v1/tools/execute`;
-                const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
-                const response = await fetch(url, {
-                    method: "POST",
-                    headers,
-                    body: JSON.stringify(body),
-                    signal: controller.signal,
-                });
-                if (!response.ok)
-                    await this.throwResponseError(response, headers["x-request-id"]);
-                return response.json();
-            }
-            catch (error) {
-                if (error instanceof Error && error.name === "AbortError") {
-                    throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
-                }
-                throw error;
-            }
-            finally {
-                clearTimeout(timeout);
-            }
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") {
+          throw new Error(`Tool execution timed out after ${options.timeoutMs}ms`);
         }
-        return this.request("POST", "/v1/tools/execute", body);
-    }
-    // --- Knowledge docs ---
-    /**
-     * Fetch one knowledge doc with its hydrated `content` — the single content-read
-     * path for a non-sandbox client (the `list_knowledge` tool returns metadata
-     * only, and the sandbox-staging read path is unavailable here). Works for both
-     * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
-     */
-    async getKnowledgeDoc(knowledge_doc_id) {
-        return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
-    }
-    /**
-     * Every doc's metadata — REST rather than the `list_knowledge` tool, because
-     * this is the surface a PERSON manages the corpus from and the tool is bound
-     * to what the assistant may browse. That distinction is the whole point of
-     * `include_hidden`: a hidden doc is out of the assistant's corpus by design,
-     * and someone still has to be able to find it in order to put it back.
-     */
-    async listKnowledgeDocs(opts) {
-        const qs = opts?.includeHidden ? "?include_hidden=true" : "";
-        return this.request("GET", `/v1/knowledge_docs${qs}`);
-    }
-    /** Apply one metadata change to a set of docs. Tags are an add/remove DIFF —
-     *  see the endpoint's own note on why a replacement is the wrong shape here. */
-    async bulkUpdateKnowledgeDocs(body) {
-        return this.request("PATCH", "/v1/knowledge_docs", body);
-    }
-    // --- Apps ---
-    async getApp(app_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
-    }
-    async createApp(body) {
-        return this.request("POST", "/v1/apps", body);
-    }
-    /**
-     * Take a starter off the shelf, or `undo` to put it back (backs `opctl
-     * starter unpublish`). It hides from non-owning orgs and can no longer be
-     * copied; copies already made are unaffected — they never linked back.
-     * Owner-org admin-only.
-     */
-    async unpublishStarter(starter_id, body) {
-        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
-    }
-    /**
-     * Edit a starter's registry listing — the name and description a stranger
-     * reads before copying, and what every copy's app row is created from.
-     *
-     * A version is an immutable snapshot; the listing is not. Omit a field to
-     * leave it, pass `description: null` to clear it. Owner-org admin-only.
-     */
-    async editStarterListing(starter_id, body) {
-        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/listing`, body);
-    }
-    // --- Starters (registry reads + copies) ---
-    // Authoring is server-side, through the publish job (`requestStarterPublish`).
-    // There is no client-side create-starter / upload-bundle path.
-    /**
-     * The starters this organization can copy — Lotics-reviewed ones plus its own,
-     * never a catalogue of everything published. The server returns exactly what
-     * instantiate would accept, so the list cannot offer a refusal. Admin-only.
-     */
-    async listStarters() {
-        return this.request("GET", "/v1/starters");
-    }
-    /**
-     * Copy a starter into the current workspace.
-     *
-     * Server-side this scaffolds the schema, creates the templates, docs and
-     * sample records, creates every app the starter carries and deploys each
-     * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
-     * one that failed carries its `error` and the copy is complete around it.
-     * Admin-only.
-     */
-    async instantiateStarter(starter_id, body) {
-        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/instantiate`, body);
-    }
-    /**
-     * Which starter this app is the origin of. 404 when it has published none.
-     *
-     * The app row carries no pin, so this is the only app→starter direction there
-     * is — provenance lives on the published version. Admin-only.
-     */
-    async getAppOriginStarter(app_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/origin-starter`);
-    }
-    /**
-     * Capture live records from this workspace as a starter's sample data.
-     *
-     * The alias-keyed shape is produced SERVER-side, because the contract alias
-     * space is minted by extract and exists nowhere a project can read it. Pure
-     * read — the caller writes the returned files into the project and reviews
-     * them, which matters: these rows are copied verbatim into every workspace
-     * that takes the starter. Admin-only.
-     */
-    async captureStarterFixtures(app_id, opts = {}) {
-        const params = new URLSearchParams();
-        if (opts.entities !== undefined && opts.entities.length > 0) {
-            params.set("entities", opts.entities.join(","));
+        throw error;
+      } finally {
+        clearTimeout(timeout);
+      }
+    }
+    return this.request("POST", "/v1/tools/execute", body);
+  }
+  // --- Knowledge docs ---
+  /**
+   * Fetch one knowledge doc with its hydrated `content` — the single content-read
+   * path for a non-sandbox client (the `list_knowledge` tool returns metadata
+   * only, and the sandbox-staging read path is unavailable here). Works for both
+   * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
+   */
+  async getKnowledgeDoc(knowledge_doc_id) {
+    return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
+  }
+  /**
+   * Every doc's metadata — REST rather than the `list_knowledge` tool, because
+   * this is the surface a PERSON manages the corpus from and the tool is bound
+   * to what the assistant may browse. That distinction is the whole point of
+   * `include_hidden`: a hidden doc is out of the assistant's corpus by design,
+   * and someone still has to be able to find it in order to put it back.
+   */
+  async listKnowledgeDocs(opts) {
+    const qs = opts?.includeHidden ? "?include_hidden=true" : "";
+    return this.request("GET", `/v1/knowledge_docs${qs}`);
+  }
+  /** Apply one metadata change to a set of docs. Tags are an add/remove DIFF —
+   *  see the endpoint's own note on why a replacement is the wrong shape here. */
+  async bulkUpdateKnowledgeDocs(body) {
+    return this.request("PATCH", "/v1/knowledge_docs", body);
+  }
+  // --- Apps ---
+  async getApp(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
+  }
+  async createApp(body) {
+    return this.request("POST", "/v1/apps", body);
+  }
+  /**
+   * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+   * starter unpublish`). It hides from non-owning orgs and can no longer be
+   * copied; copies already made are unaffected — they never linked back.
+   * Owner-org admin-only.
+   */
+  async unpublishStarter(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
+  }
+  /**
+   * Edit a starter's registry listing — the name and description a stranger
+   * reads before copying, and what every copy's app row is created from.
+   *
+   * A version is an immutable snapshot; the listing is not. Omit a field to
+   * leave it, pass `description: null` to clear it. Owner-org admin-only.
+   */
+  async editStarterListing(starter_id, body) {
+    return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/listing`, body);
+  }
+  // --- Starters (registry reads + copies) ---
+  // Authoring is server-side, through the publish job (`requestStarterPublish`).
+  // There is no client-side create-starter / upload-bundle path.
+  /**
+   * The starters this organization can copy — Lotics-reviewed ones plus its own,
+   * never a catalogue of everything published. The server returns exactly what
+   * instantiate would accept, so the list cannot offer a refusal. Admin-only.
+   */
+  async listStarters() {
+    return this.request("GET", "/v1/starters");
+  }
+  /**
+   * Copy a starter into the current workspace.
+   *
+   * Server-side this scaffolds the schema, creates the templates, docs and
+   * sample records, creates every app the starter carries and deploys each
+   * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+   * one that failed carries its `error` and the copy is complete around it.
+   * Admin-only.
+   */
+  async instantiateStarter(starter_id, body) {
+    return this.request(
+      "POST",
+      `/v1/starters/${encodeURIComponent(starter_id)}/instantiate`,
+      body
+    );
+  }
+  /**
+   * Which starter this app is the origin of. 404 when it has published none.
+   *
+   * The app row carries no pin, so this is the only app→starter direction there
+   * is — provenance lives on the published version. Admin-only.
+   */
+  async getAppOriginStarter(app_id) {
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/origin-starter`);
+  }
+  /**
+   * Capture live records from this workspace as a starter's sample data.
+   *
+   * The alias-keyed shape is produced SERVER-side, because the contract alias
+   * space is minted by extract and exists nowhere a project can read it. Pure
+   * read — the caller writes the returned files into the project and reviews
+   * them, which matters: these rows are copied verbatim into every workspace
+   * that takes the starter. Admin-only.
+   */
+  async captureStarterFixtures(app_id, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.entities !== void 0 && opts.entities.length > 0) {
+      params.set("entities", opts.entities.join(","));
+    }
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    const qs = params.toString();
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/fixtures-capture${qs ? `?${qs}` : ""}`
+    );
+  }
+  /**
+   * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
+   * `is_official` trust badge). Admin-only; cross-tenant by id.
+   */
+  async getStarter(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
+  }
+  /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+  async listStarterVersions(starter_id) {
+    return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
+  }
+  /**
+   * One version's contract — what a copy of it is supposed to produce. The
+   * history above omits it (heavy per row); this is the read that carries it,
+   * so a check compares a copy against the declaration itself rather than
+   * against a description of it. Admin-only; cross-tenant by id like
+   * `getStarter`.
+   */
+  async getStarterVersion(starter_id, version) {
+    return this.request(
+      "GET",
+      `/v1/starters/${encodeURIComponent(starter_id)}/versions/${encodeURIComponent(String(version))}`
+    );
+  }
+  /**
+   * Workspace-wide dangling-reference sweep — active app/workflow artifacts
+   * whose prefixed schema ids no longer resolve. Backs
+   * `lotics workspace doctor`. Admin-only.
+   */
+  async getWorkspaceDanglingReferences() {
+    return this.request("GET", "/v1/workspaces/dangling-references");
+  }
+  // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
+  /**
+   * Preview publishing a set of this workspace's apps as one starter version —
+   * the GET behind `opctl starter publish` (no `--yes`). The server runs the
+   * same extraction the publish runs and reports which starter it would
+   * release into (null: it would mint one), the next version, the aliases a
+   * first publish can still rename, the diff against the current version, the
+   * knowledge delta, and the findings (an `error` blocks the publish). No
+   * writes. Admin-only.
+   */
+  async previewStarterPublish(opts) {
+    const params = new URLSearchParams();
+    params.set("app_ids", opts.app_ids.join(","));
+    if (opts.knowledge_doc_ids !== void 0) params.set("knowledge_doc_ids", opts.knowledge_doc_ids.join(","));
+    if (opts.renames !== void 0 && opts.renames.length > 0) params.set("renames", JSON.stringify(opts.renames));
+    if (opts.name !== void 0) params.set("name", opts.name);
+    if (opts.description !== void 0) params.set("description", opts.description);
+    if (opts.icon !== void 0) params.set("icon", opts.icon);
+    if (opts.color !== void 0) params.set("color", opts.color);
+    return this.request("GET", `/v1/starters/publish-preview?${params.toString()}`);
+  }
+  /**
+   * Publish this workspace's apps as a starter version — a JOB, because every
+   * app is built once against sentinel field keys and eleven builds outlast a
+   * request. Everything a request can refuse is refused here with nothing
+   * written: a blocking finding or another publish still running for this
+   * org (409), a missing deploy or a bad declaration (400). The response is
+   * the job to poll with `getStarterPublish`. Admin-only.
+   */
+  async requestStarterPublish(body) {
+    const { color, ...rest } = body;
+    return this.request("POST", "/v1/starters/publishes", {
+      ...rest,
+      ...color !== void 0 ? { theme: { color } } : {}
+    });
+  }
+  /** The state of a publish: which app is building, and the version once every dist is in. */
+  async getStarterPublish(publish_id) {
+    return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
+  }
+  /**
+   * Resolve the display name + fields (incl. select options) of the given tables
+   * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`
+   * alias maps. One `get_table` call per id (the tool surface has no batch
+   * variant); a missing/inaccessible table is dropped rather than throwing, so a
+   * stale id in the scope set never fails codegen.
+   */
+  async getWorkspaceSchema(tableIds) {
+    const tables = await Promise.all(
+      tableIds.map(async (table_id) => {
+        const res = await this.execute("get_table", { table_id });
+        if (res.error || res.result === null || typeof res.result !== "object") return null;
+        const table = res.result;
+        if (typeof table.id !== "string" || typeof table.name !== "string" || !Array.isArray(table.fields)) {
+          return null;
         }
-        if (opts.limit !== undefined)
-            params.set("limit", String(opts.limit));
-        const qs = params.toString();
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/fixtures-capture${qs ? `?${qs}` : ""}`);
-    }
-    /**
-     * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
-     * `is_official` trust badge). Admin-only; cross-tenant by id.
-     */
-    async getStarter(starter_id) {
-        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
-    }
-    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
-    async listStarterVersions(starter_id) {
-        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
-    }
-    /**
-     * One version's contract — what a copy of it is supposed to produce. The
-     * history above omits it (heavy per row); this is the read that carries it,
-     * so a check compares a copy against the declaration itself rather than
-     * against a description of it. Admin-only; cross-tenant by id like
-     * `getStarter`.
-     */
-    async getStarterVersion(starter_id, version) {
-        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions/${encodeURIComponent(String(version))}`);
-    }
-    /**
-     * Workspace-wide dangling-reference sweep — active app/workflow artifacts
-     * whose prefixed schema ids no longer resolve. Backs
-     * `lotics workspace doctor`. Admin-only.
-     */
-    async getWorkspaceDanglingReferences() {
-        return this.request("GET", "/v1/workspaces/dangling-references");
-    }
-    // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
-    /**
-     * Preview publishing a set of this workspace's apps as one starter version —
-     * the GET behind `opctl starter publish` (no `--yes`). The server runs the
-     * same extraction the publish runs and reports which starter it would
-     * release into (null: it would mint one), the next version, the aliases a
-     * first publish can still rename, the diff against the current version, the
-     * knowledge delta, and the findings (an `error` blocks the publish). No
-     * writes. Admin-only.
-     */
-    async previewStarterPublish(opts) {
-        const params = new URLSearchParams();
-        params.set("app_ids", opts.app_ids.join(","));
-        if (opts.knowledge_doc_ids !== undefined)
-            params.set("knowledge_doc_ids", opts.knowledge_doc_ids.join(","));
-        if (opts.renames !== undefined && opts.renames.length > 0)
-            params.set("renames", JSON.stringify(opts.renames));
-        if (opts.name !== undefined)
-            params.set("name", opts.name);
-        if (opts.description !== undefined)
-            params.set("description", opts.description);
-        if (opts.icon !== undefined)
-            params.set("icon", opts.icon);
-        if (opts.color !== undefined)
-            params.set("color", opts.color);
-        return this.request("GET", `/v1/starters/publish-preview?${params.toString()}`);
-    }
-    /**
-     * Publish this workspace's apps as a starter version — a JOB, because every
-     * app is built once against sentinel field keys and eleven builds outlast a
-     * request. Everything a request can refuse is refused here with nothing
-     * written: a blocking finding or another publish still running for this
-     * org (409), a missing deploy or a bad declaration (400). The response is
-     * the job to poll with `getStarterPublish`. Admin-only.
-     */
-    async requestStarterPublish(body) {
-        const { color, ...rest } = body;
-        return this.request("POST", "/v1/starters/publishes", {
-            ...rest,
-            ...(color !== undefined ? { theme: { color } } : {}),
+        const fields = table.fields.flatMap((field) => {
+          if (field === null || typeof field !== "object") return [];
+          const f = field;
+          if (typeof f.key !== "string" || typeof f.name !== "string" || typeof f.type !== "string") return [];
+          const options = Array.isArray(f.options) ? f.options.flatMap((opt) => {
+            if (opt === null || typeof opt !== "object") return [];
+            const o = opt;
+            return typeof o.key === "string" && typeof o.name === "string" ? [{ id: o.key, label: o.name }] : [];
+          }) : void 0;
+          return [{ id: f.key, name: f.name, type: f.type, ...options && options.length > 0 ? { options } : {} }];
         });
+        return { id: table.id, name: table.name, fields };
+      })
+    );
+    return tables.filter((t) => t !== null);
+  }
+  /**
+   * Rename an app's public subdomain — its `<slug>.lotics.app` address.
+   * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
+   * resolving once the change lands.
+   */
+  async setAppSubdomain(app_id, public_subdomain) {
+    return this.request(
+      "PUT",
+      `/v1/apps/${encodeURIComponent(app_id)}/subdomain`,
+      { public_subdomain }
+    );
+  }
+  async getAppVersion(app_id, version_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}`
+    );
+  }
+  async getAppVersionSourceUrl(app_id, version_id) {
+    const result = await this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`
+    );
+    return result.url;
+  }
+  /** Deploy history for an app — newest first. Backs `lotics app versions`. */
+  async listAppVersions(app_id, opts) {
+    const qs = new URLSearchParams();
+    if (opts?.limit != null) qs.set("limit", String(opts.limit));
+    if (opts?.offset != null) qs.set("offset", String(opts.offset));
+    const suffix = qs.toString() ? `?${qs.toString()}` : "";
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions${suffix}`);
+  }
+  // ── App iframe RPC endpoints ──────────────────────────────────────────────
+  // These mirror the two ops handled by frontend/features/app_ui/app_iframe_host.tsx.
+  // The deployed iframe sends postMessage to the parent frontend, which calls
+  // these same endpoints via the user's session cookie. `lotics app dev`
+  // forwards the iframe's postMessage to these methods using the CLI's API key.
+  /**
+   * Run a named query declared in the app's manifest, scoped to the app's IAM
+   * principal. Mirrors POST /v1/apps/{app_id}/query.
+   */
+  async appQuery(app_id, body) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/query`, body);
+  }
+  async appMembers(app_id, group_id) {
+    const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
+    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
+  }
+  /**
+   * Resolve the full option set (key, label, color) of a named query's select
+   * columns — the picker companion to `appQuery`. Mirrors
+   * POST /v1/apps/{app_id}/field-options.
+   */
+  async appFieldOptions(app_id, alias) {
+    return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias });
+  }
+  /**
+   * Execute a workflow by alias declared in package.json#lotics.workflows.
+   * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
+   */
+  async appWorkflow(app_id, alias, inputs) {
+    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 {
+      }
+    }
+    if (response.ok) return parsed ?? {};
+    return { status: "error", message: transportErrorMessage(response.status, parsed) };
+  }
+  /**
+   * Bind (create or replace) an app workflow by alias via the `set_app_workflow`
+   * tool — the SINGLE author of `apps.workflows` + the workflow row. `source` is
+   * the verbatim JS-subset body (no `on({...})` trigger). `inputs`/`outputs` are
+   * the typed schemas declared in `package.json#lotics.workflows.<alias>`. The
+   * server re-verifies the body and echoes the bound `outputs` (declared, else
+   * DERIVED from `return({ data })`), so the CLI can show the author what shape
+   * `result.data` will carry. Wraps the tool rather than a bespoke endpoint so
+   * the file flow stays a convenience over the existing single-author contract.
+   */
+  async setAppWorkflow(app_id, alias, body) {
+    return this.execute("set_app_workflow", {
+      app_id,
+      alias,
+      source: body.source,
+      ...body.inputs ? { inputs: body.inputs } : {},
+      ...body.outputs ? { outputs: body.outputs } : {},
+      ...body.name ? { name: body.name } : {},
+      ...body.description ? { description: body.description } : {},
+      ...body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}
+    });
+  }
+  /**
+   * Bind (create or replace) an app query by alias via the `set_app_query` tool
+   * — the deploy-free authoring path for `apps.queries`, parallel to
+   * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
+   * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
+   * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
+   * so the next `lotics app deploy` overwrites this from the manifest.
+   */
+  async setAppQuery(app_id, alias, declaration, expected_sha) {
+    return this.execute("set_app_query", {
+      app_id,
+      alias,
+      declaration,
+      ...expected_sha ? { expected_sha } : {}
+    });
+  }
+  /**
+   * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
+   * — the deploy-free authoring path for `apps.agents`, parallel to
+   * `setAppWorkflow`/`setAppQuery`.
+   *
+   * `set_app_agent` REPLACES the whole declaration, so this takes the whole
+   * declaration. `lotics app agent set` is the caller that assembles it (prose
+   * from `src/agents/<alias>.md`, typed fields from the manifest) precisely so
+   * no caller has to remember that a partial payload silently drops
+   * `instructions`, `outputs` and the model pin.
+   */
+  async setAppAgent(app_id, alias, patch) {
+    return this.execute("set_app_agent", { app_id, alias, ...patch });
+  }
+  /**
+   * Fetch one app workflow's faithful source + bound input/output schemas via
+   * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
+   * persisted step tree (incl. the `return({ data })` clause, opaque field/option
+   * keys) — the exact text `lotics app workflow set` would push back. Feeds
+   * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
+   */
+  async getAppWorkflow(app_id, alias) {
+    return this.execute("get_app_workflow", { app_id, alias });
+  }
+  /**
+   * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
+   * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
+   * The server is the single source of the type model — the CLI never
+   * re-implements it. `envelope_prefix`/`envelope_suffix` are the exact
+   * `async function __workflow(): …` wrapper the server compiles inside, so the
+   * local typecheck mirrors the set-time verdict. Mirrors
+   * POST /v1/apps/{app_id}/workflows/{alias}/dts.
+   *
+   * `declaration` (the manifest's `{ inputs?, outputs? }`) is posted as the body
+   * `{ declaration }` ONLY when the alias isn't `set` on the server yet — the
+   * server then synthesizes the dts from the declared schemas instead of 400ing
+   * "no workflow alias". A registered alias needs no declaration (the server's
+   * own bound contract wins), so the field is omitted in that case.
+   */
+  async getAppWorkflowDts(app_id, alias, declaration) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`,
+      declaration ? { declaration } : void 0
+    );
+  }
+  /**
+   * Open a streaming agent run and return the RAW streamed `Response` (the
+   * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
+   * body — it's the SSE stream the `lotics app dev` harness proxies to the
+   * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
+   */
+  async appAgentRunStream(app_id, alias, body, signal) {
+    const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
+    const res = await fetch(
+      `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`,
+      { method: "POST", headers, body: JSON.stringify(body), signal }
+    );
+    if (!res.ok) await this.throwResponseError(res, headers["x-request-id"]);
+    return res;
+  }
+  /**
+   * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
+   * pending `ask_user_choice` — returns the RAW streamed continuation `Response`,
+   * exactly like `appAgentRunStream`. Mirrors
+   * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
+   */
+  async appAgentRunContinueStream(app_id, run_id, body, signal) {
+    const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
+    const res = await fetch(
+      `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`,
+      { method: "POST", headers, body: JSON.stringify(body), signal }
+    );
+    if (!res.ok) await this.throwResponseError(res, headers["x-request-id"]);
+    return res;
+  }
+  /**
+   * A session's app-agent run history, oldest-first (the run just started is the
+   * last, and its exact id is on the stream response's `x-app-agent-run-id`
+   * header). Transcript excluded; structured `output`/`input` included. Mirrors
+   * GET /v1/apps/{app_id}/agent-runs.
+   */
+  async listAgentRuns(app_id, session_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`
+    );
+  }
+  /**
+   * A single run by id — the poll read a client follows after its stream drops
+   * (a parked `awaiting_input` row carries `pending_interactive` so the question
+   * survives reconnection). Mirrors GET /v1/apps/{app_id}/agent-runs/{run_id}.
+   */
+  async getAgentRun(app_id, run_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}`
+    );
+  }
+  /**
+   * Request cancellation of an in-flight (or parked) run. Mirrors
+   * POST /v1/apps/{app_id}/agent-runs/{run_id}/cancel.
+   */
+  async cancelAgentRun(app_id, run_id) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/cancel`
+    );
+  }
+  /**
+   * Mint a presigned URL for uploading a file into an app. Mirrors
+   * POST /v1/apps/{app_id}/files/upload-url.
+   */
+  async appRequestFileUpload(app_id, body) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/files/upload-url`,
+      body
+    );
+  }
+  /**
+   * Finalize a presigned upload once the bytes are in storage. Mirrors
+   * POST /v1/apps/{app_id}/files/complete.
+   */
+  async appCompleteFileUpload(app_id, body) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/files/complete`,
+      body
+    );
+  }
+  // App-scoped record comments — the `lotics app dev` loop forwards the iframe's
+  // `comments.*` ops to these (production routes them through the iframe host).
+  // App authority + tenant floor are enforced server-side; these are thin.
+  async appGetRecordComments(app_id, record_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments`
+    );
+  }
+  async appCreateRecordComment(app_id, record_id, body) {
+    return this.request(
+      "POST",
+      `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments`,
+      body
+    );
+  }
+  async appUpdateRecordComment(app_id, record_id, comment_id, body) {
+    return this.request(
+      "PATCH",
+      `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments/${encodeURIComponent(comment_id)}`,
+      body
+    );
+  }
+  async appDeleteRecordComment(app_id, record_id, comment_id) {
+    await this.request(
+      "DELETE",
+      `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments/${encodeURIComponent(comment_id)}`
+    );
+  }
+  async appGetTableCommentCounts(app_id, table_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/tables/${encodeURIComponent(table_id)}/comment-counts`
+    );
+  }
+  async deployAppVersion(args) {
+    const formData = new FormData();
+    formData.append(
+      "source",
+      new Blob([new Uint8Array(args.source_archive)], { type: "application/gzip" }),
+      "source.tar.gz"
+    );
+    formData.append(
+      "dist",
+      new Blob([new Uint8Array(args.dist_archive)], { type: "application/gzip" }),
+      "dist.tar.gz"
+    );
+    if (args.prev_version_id) {
+      formData.append("prev_version_id", args.prev_version_id);
+    }
+    if (args.message) {
+      formData.append("message", args.message);
+    }
+    formData.append("queries", JSON.stringify(args.queries ?? {}));
+    if (args.capabilities !== void 0) {
+      formData.append("capabilities", JSON.stringify(args.capabilities));
+    }
+    formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
+    formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
+    formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
+    const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
+    const headers = this.buildHeaders();
+    const response = await fetch(url, { method: "POST", headers, body: formData });
+    if (response.status === 409) {
+      const conflict = await response.json();
+      const err = new Error(conflict.message ?? "Deploy conflict \u2014 pull required");
+      err.code = "VERSION_CONFLICT";
+      err.current_version_id = conflict.current_version_id ?? null;
+      throw err;
     }
-    /** The state of a publish: which app is building, and the version once every dist is in. */
-    async getStarterPublish(publish_id) {
-        return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
-    }
-    /**
-     * Resolve the display name + fields (incl. select options) of the given tables
-     * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`
-     * alias maps. One `get_table` call per id (the tool surface has no batch
-     * variant); a missing/inaccessible table is dropped rather than throwing, so a
-     * stale id in the scope set never fails codegen.
-     */
-    async getWorkspaceSchema(tableIds) {
-        const tables = await Promise.all(tableIds.map(async (table_id) => {
-            // JSON (the default) — `res.result` is the structured `get_table` output
-            // already; `text` would only also run `toModelOutput` per table for
-            // nothing. The field id is `key` and an option's id is `key` / label is
-            // `name` (the `TableField` / select-option schema shapes).
-            const res = await this.execute("get_table", { table_id });
-            if (res.error || res.result === null || typeof res.result !== "object")
-                return null;
-            const table = res.result;
-            if (typeof table.id !== "string" || typeof table.name !== "string" || !Array.isArray(table.fields)) {
-                return null;
-            }
-            const fields = table.fields.flatMap((field) => {
-                if (field === null || typeof field !== "object")
-                    return [];
-                const f = field;
-                if (typeof f.key !== "string" || typeof f.name !== "string" || typeof f.type !== "string")
-                    return [];
-                const options = Array.isArray(f.options)
-                    ? f.options.flatMap((opt) => {
-                        if (opt === null || typeof opt !== "object")
-                            return [];
-                        const o = opt;
-                        return typeof o.key === "string" && typeof o.name === "string"
-                            ? [{ id: o.key, label: o.name }]
-                            : [];
-                    })
-                    : undefined;
-                return [{ id: f.key, name: f.name, type: f.type, ...(options && options.length > 0 ? { options } : {}) }];
-            });
-            return { id: table.id, name: table.name, fields };
-        }));
-        return tables.filter((t) => t !== null);
-    }
-    /**
-     * Rename an app's public subdomain — its `<slug>.lotics.app` address.
-     * Mirrors PUT /v1/apps/{app_id}/subdomain. The old subdomain stops
-     * resolving once the change lands.
-     */
-    async setAppSubdomain(app_id, public_subdomain) {
-        return this.request("PUT", `/v1/apps/${encodeURIComponent(app_id)}/subdomain`, { public_subdomain });
-    }
-    async getAppVersion(app_id, version_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}`);
-    }
-    async getAppVersionSourceUrl(app_id, version_id) {
-        const result = await this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions/${encodeURIComponent(version_id)}/source`);
-        return result.url;
-    }
-    /** Deploy history for an app — newest first. Backs `lotics app versions`. */
-    async listAppVersions(app_id, opts) {
-        const qs = new URLSearchParams();
-        if (opts?.limit != null)
-            qs.set("limit", String(opts.limit));
-        if (opts?.offset != null)
-            qs.set("offset", String(opts.offset));
-        const suffix = qs.toString() ? `?${qs.toString()}` : "";
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/versions${suffix}`);
-    }
-    // ── App iframe RPC endpoints ──────────────────────────────────────────────
-    // These mirror the two ops handled by frontend/features/app_ui/app_iframe_host.tsx.
-    // The deployed iframe sends postMessage to the parent frontend, which calls
-    // these same endpoints via the user's session cookie. `lotics app dev`
-    // forwards the iframe's postMessage to these methods using the CLI's API key.
-    /**
-     * Run a named query declared in the app's manifest, scoped to the app's IAM
-     * principal. Mirrors POST /v1/apps/{app_id}/query.
-     */
-    async appQuery(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/query`, body);
-    }
-    async appMembers(app_id, group_id) {
-        const qs = group_id ? `?group_id=${encodeURIComponent(group_id)}` : "";
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/members${qs}`);
-    }
-    /**
-     * Resolve the full option set (key, label, color) of a named query's select
-     * columns — the picker companion to `appQuery`. Mirrors
-     * POST /v1/apps/{app_id}/field-options.
-     */
-    async appFieldOptions(app_id, alias) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/field-options`, { alias });
-    }
-    /**
-     * Execute a workflow by alias declared in package.json#lotics.workflows.
-     * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
-     */
-    async appWorkflow(app_id, alias, 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) };
-    }
-    /**
-     * Bind (create or replace) an app workflow by alias via the `set_app_workflow`
-     * tool — the SINGLE author of `apps.workflows` + the workflow row. `source` is
-     * the verbatim JS-subset body (no `on({...})` trigger). `inputs`/`outputs` are
-     * the typed schemas declared in `package.json#lotics.workflows.<alias>`. The
-     * server re-verifies the body and echoes the bound `outputs` (declared, else
-     * DERIVED from `return({ data })`), so the CLI can show the author what shape
-     * `result.data` will carry. Wraps the tool rather than a bespoke endpoint so
-     * the file flow stays a convenience over the existing single-author contract.
-     */
-    async setAppWorkflow(app_id, alias, body) {
-        return this.execute("set_app_workflow", {
-            app_id,
-            alias,
-            source: body.source,
-            ...(body.inputs ? { inputs: body.inputs } : {}),
-            ...(body.outputs ? { outputs: body.outputs } : {}),
-            ...(body.name ? { name: body.name } : {}),
-            ...(body.description ? { description: body.description } : {}),
-            ...(body.expected_body_sha ? { expected_body_sha: body.expected_body_sha } : {}),
-        });
+    if (!response.ok) {
+      await this.throwResponseError(response, headers["x-request-id"]);
     }
-    /**
-     * Bind (create or replace) an app query by alias via the `set_app_query` tool
-     * — the deploy-free authoring path for `apps.queries`, parallel to
-     * `setAppWorkflow`. `declaration` is the `{ ast, params? }` from
-     * `package.json#lotics.queries.<alias>`. The server validates it exactly as a
-     * deploy validates the manifest. Note: `apps.queries` is manifest-authoritative,
-     * so the next `lotics app deploy` overwrites this from the manifest.
-     */
-    async setAppQuery(app_id, alias, declaration, 
-    /** The fingerprint this edit was based on — makes the write conditional. */
-    expected_sha) {
-        return this.execute("set_app_query", {
-            app_id,
-            alias,
-            declaration,
-            ...(expected_sha ? { expected_sha } : {}),
+    return response.json();
+  }
+  async downloadFile(url, outputPath) {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`${response.status}: Failed to download file`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const absolutePath = path.resolve(outputPath);
+    await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
+    await fs.promises.writeFile(absolutePath, buffer);
+    return absolutePath;
+  }
+  async downloadFileById(fileId, outputDir, options) {
+    const signedHeaders = this.buildHeaders();
+    const signedUrlRes = await fetch(
+      `${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`,
+      { headers: signedHeaders }
+    );
+    if (!signedUrlRes.ok) {
+      await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
+    }
+    const { url } = await signedUrlRes.json();
+    const response = await fetch(url);
+    if (!response.ok) await this.throwResponseError(response);
+    const disposition = response.headers.get("content-disposition") ?? "";
+    const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
+    const buffer = Buffer.from(await response.arrayBuffer());
+    const dir = outputDir ? path.resolve(outputDir) : process.cwd();
+    await fs.promises.mkdir(dir, { recursive: true });
+    const filename = findAvailableFilename(dir, originalFilename, options?.reserved);
+    const absolutePath = path.join(dir, filename);
+    await fs.promises.writeFile(absolutePath, buffer);
+    return { path: absolutePath, filename };
+  }
+  async downloadRecordFiles(recordId, fieldKey, outputDir) {
+    const result = await this.execute("get_record", { record_id: recordId }, { format: "text" });
+    if (result.error) throw new Error(result.error);
+    const record = result.result;
+    const files = record?.data?.[fieldKey];
+    if (!Array.isArray(files)) {
+      throw new Error(`Field ${fieldKey} on ${recordId} is not a file field or has no value`);
+    }
+    const fileIds = files.map((f, i) => {
+      if (typeof f !== "object" || f === null || !("id" in f) || typeof f.id !== "string") {
+        throw new Error(`Invalid file entry [${i}] in ${recordId}.${fieldKey}: ${JSON.stringify(f)}`);
+      }
+      return f.id;
+    });
+    const reserved = /* @__PURE__ */ new Set();
+    return Promise.all(
+      fileIds.map(async (fileId) => {
+        const res = await this.downloadFileById(fileId, outputDir, { reserved });
+        return { ...res, file_id: fileId };
+      })
+    );
+  }
+  async uploadFiles(filePaths, options) {
+    const small = [];
+    const large = [];
+    for (let i = 0; i < filePaths.length; i++) {
+      const absolutePath = path.resolve(filePaths[i]);
+      const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
+      const { size } = await fs.promises.stat(absolutePath);
+      if (size >= MULTIPART_THRESHOLD_BYTES) {
+        large.push({ absolutePath, filename, size });
+      } else {
+        small.push({ bytes: await fs.promises.readFile(absolutePath), filename });
+      }
+    }
+    const files = [];
+    const errors = [];
+    if (small.length > 0) {
+      const result = await this.uploadFileBytes(small);
+      files.push(...result.files);
+      errors.push(...result.errors);
+    }
+    for (const item of large) {
+      try {
+        files.push(await this.uploadLargeFile(item));
+      } catch (error) {
+        errors.push({
+          filename: item.filename,
+          error: error instanceof Error ? error.message : String(error)
         });
-    }
-    /**
-     * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
-     * — the deploy-free authoring path for `apps.agents`, parallel to
-     * `setAppWorkflow`/`setAppQuery`.
-     *
-     * `set_app_agent` REPLACES the whole declaration, so this takes the whole
-     * declaration. `lotics app agent set` is the caller that assembles it (prose
-     * from `src/agents/<alias>.md`, typed fields from the manifest) precisely so
-     * no caller has to remember that a partial payload silently drops
-     * `instructions`, `outputs` and the model pin.
-     */
-    async setAppAgent(app_id, alias, 
-    /** ONLY the fields being changed. The server merges against the stored
-     *  declaration, so nothing a caller omits is lost and a field the server adds
-     *  later needs no change here. Pass `null` to clear an optional field. */
-    patch) {
-        return this.execute("set_app_agent", { app_id, alias, ...patch });
-    }
-    /**
-     * Fetch one app workflow's faithful source + bound input/output schemas via
-     * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
-     * persisted step tree (incl. the `return({ data })` clause, opaque field/option
-     * keys) — the exact text `lotics app workflow set` would push back. Feeds
-     * `lotics app pull`, which writes it to `src/workflows/<alias>.ts`.
-     */
-    async getAppWorkflow(app_id, alias) {
-        return this.execute("get_app_workflow", { app_id, alias });
-    }
-    /**
-     * Fetch the server-generated workspace `.d.ts` + the wrapper envelope that
-     * make a `src/workflows/<alias>.ts` body locally typecheckable (GAP-59).
-     * The server is the single source of the type model — the CLI never
-     * re-implements it. `envelope_prefix`/`envelope_suffix` are the exact
-     * `async function __workflow(): …` wrapper the server compiles inside, so the
-     * local typecheck mirrors the set-time verdict. Mirrors
-     * POST /v1/apps/{app_id}/workflows/{alias}/dts.
-     *
-     * `declaration` (the manifest's `{ inputs?, outputs? }`) is posted as the body
-     * `{ declaration }` ONLY when the alias isn't `set` on the server yet — the
-     * server then synthesizes the dts from the declared schemas instead of 400ing
-     * "no workflow alias". A registered alias needs no declaration (the server's
-     * own bound contract wins), so the field is omitted in that case.
-     */
-    async getAppWorkflowDts(app_id, alias, declaration) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/dts`, declaration ? { declaration } : undefined);
-    }
-    /**
-     * Open a streaming agent run and return the RAW streamed `Response` (the
-     * caller reads `res.body`). Unlike `request`, this does not buffer/parse the
-     * body — it's the SSE stream the `lotics app dev` harness proxies to the
-     * iframe. Mirrors POST /v1/apps/{app_id}/agents/{alias}/runs.
-     */
-    async appAgentRunStream(app_id, alias, body, signal) {
-        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
-        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agents/${encodeURIComponent(alias)}/runs`, { method: "POST", headers, body: JSON.stringify(body), signal });
-        if (!res.ok)
-            await this.throwResponseError(res, headers["x-request-id"]);
-        return res;
-    }
-    /**
-     * Continue a PARKED (`awaiting_input`) agent run with the user's answer to its
-     * pending `ask_user_choice` — returns the RAW streamed continuation `Response`,
-     * exactly like `appAgentRunStream`. Mirrors
-     * POST /v1/apps/{app_id}/agent-runs/{run_id}/continue.
-     */
-    async appAgentRunContinueStream(app_id, run_id, body, signal) {
-        const headers = { ...this.buildHeaders(), "Content-Type": "application/json" };
-        const res = await fetch(`${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/continue`, { method: "POST", headers, body: JSON.stringify(body), signal });
-        if (!res.ok)
-            await this.throwResponseError(res, headers["x-request-id"]);
-        return res;
-    }
-    /**
-     * A session's app-agent run history, oldest-first (the run just started is the
-     * last, and its exact id is on the stream response's `x-app-agent-run-id`
-     * header). Transcript excluded; structured `output`/`input` included. Mirrors
-     * GET /v1/apps/{app_id}/agent-runs.
-     */
-    async listAgentRuns(app_id, session_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`);
-    }
-    /**
-     * A single run by id — the poll read a client follows after its stream drops
-     * (a parked `awaiting_input` row carries `pending_interactive` so the question
-     * survives reconnection). Mirrors GET /v1/apps/{app_id}/agent-runs/{run_id}.
-     */
-    async getAgentRun(app_id, run_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}`);
-    }
-    /**
-     * Request cancellation of an in-flight (or parked) run. Mirrors
-     * POST /v1/apps/{app_id}/agent-runs/{run_id}/cancel.
-     */
-    async cancelAgentRun(app_id, run_id) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/agent-runs/${encodeURIComponent(run_id)}/cancel`);
-    }
-    /**
-     * Mint a presigned URL for uploading a file into an app. Mirrors
-     * POST /v1/apps/{app_id}/files/upload-url.
-     */
-    async appRequestFileUpload(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/files/upload-url`, body);
-    }
-    /**
-     * Finalize a presigned upload once the bytes are in storage. Mirrors
-     * POST /v1/apps/{app_id}/files/complete.
-     */
-    async appCompleteFileUpload(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/files/complete`, body);
-    }
-    // App-scoped record comments — the `lotics app dev` loop forwards the iframe's
-    // `comments.*` ops to these (production routes them through the iframe host).
-    // App authority + tenant floor are enforced server-side; these are thin.
-    async appGetRecordComments(app_id, record_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments`);
-    }
-    async appCreateRecordComment(app_id, record_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments`, body);
-    }
-    async appUpdateRecordComment(app_id, record_id, comment_id, body) {
-        return this.request("PATCH", `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments/${encodeURIComponent(comment_id)}`, body);
-    }
-    async appDeleteRecordComment(app_id, record_id, comment_id) {
-        await this.request("DELETE", `/v1/apps/${encodeURIComponent(app_id)}/records/${encodeURIComponent(record_id)}/comments/${encodeURIComponent(comment_id)}`);
-    }
-    async appGetTableCommentCounts(app_id, table_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/tables/${encodeURIComponent(table_id)}/comment-counts`);
-    }
-    async deployAppVersion(args) {
-        const formData = new FormData();
-        // Wrap Buffers as Uint8Array views so the Blob constructor accepts them
-        // (Node Buffer's `ArrayBufferLike` underlying buffer doesn't match the
-        // BlobPart contract directly under strict TS).
-        formData.append("source", new Blob([new Uint8Array(args.source_archive)], { type: "application/gzip" }), "source.tar.gz");
-        formData.append("dist", new Blob([new Uint8Array(args.dist_archive)], { type: "application/gzip" }), "dist.tar.gz");
-        if (args.prev_version_id) {
-            formData.append("prev_version_id", args.prev_version_id);
-        }
-        if (args.message) {
-            formData.append("message", args.message);
-        }
-        // Always send queries — empty object clears any previously-declared
-        // named queries. Server validates each template. (Workflow bindings are
-        // not sent: set_app_workflow / remove_app_workflow own apps.workflows.)
-        formData.append("queries", JSON.stringify(args.queries ?? {}));
-        // capabilities is manifest-authoritative — the caller always passes it
-        // (`{}` when none declared), so a deploy turns off any capability the
-        // manifest no longer declares. JSON-encoded.
-        if (args.capabilities !== undefined) {
-            formData.append("capabilities", JSON.stringify(args.capabilities));
-        }
-        // Always send the declared workflow aliases (empty array when none) so the
-        // server records what the served version calls — the remove_app_workflow
-        // guard reads this back. These are the manifest KEYS only, never bindings.
-        formData.append("workflow_aliases", JSON.stringify(args.workflow_aliases ?? []));
-        formData.append("agent_aliases", JSON.stringify(args.agent_aliases ?? []));
-        formData.append("query_aliases", JSON.stringify(args.query_aliases ?? []));
-        const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(args.app_id)}/versions`;
-        const headers = this.buildHeaders(); // no Content-Type — fetch sets multipart boundary
-        const response = await fetch(url, { method: "POST", headers, body: formData });
-        if (response.status === 409) {
-            const conflict = (await response.json());
-            const err = new Error(conflict.message ?? "Deploy conflict — pull required");
-            err.code = "VERSION_CONFLICT";
-            err.current_version_id =
-                conflict.current_version_id ?? null;
-            throw err;
-        }
-        if (!response.ok) {
-            await this.throwResponseError(response, headers["x-request-id"]);
-        }
-        return response.json();
-    }
-    async downloadFile(url, outputPath) {
-        const response = await fetch(url);
-        if (!response.ok) {
-            throw new Error(`${response.status}: Failed to download file`);
-        }
-        const buffer = Buffer.from(await response.arrayBuffer());
-        const absolutePath = path.resolve(outputPath);
-        await fs.promises.mkdir(path.dirname(absolutePath), { recursive: true });
-        await fs.promises.writeFile(absolutePath, buffer);
-        return absolutePath;
-    }
-    async downloadFileById(fileId, outputDir, options) {
-        // Resolve a presigned URL (the file proxy is auth-gated and served by an
-        // edge Worker that doesn't accept the API key). The signed_url endpoint
-        // takes the API key and returns a short-lived, directly-fetchable URL
-        // whose Content-Disposition carries the original filename.
-        const signedHeaders = this.buildHeaders();
-        const signedUrlRes = await fetch(`${this.baseUrl}/v1/files/${encodeURIComponent(fileId)}/signed_url`, { headers: signedHeaders });
-        if (!signedUrlRes.ok) {
-            await this.throwResponseError(signedUrlRes, signedHeaders["x-request-id"]);
-        }
-        const { url } = (await signedUrlRes.json());
-        const response = await fetch(url);
-        if (!response.ok)
-            await this.throwResponseError(response);
-        const disposition = response.headers.get("content-disposition") ?? "";
-        const originalFilename = parseContentDispositionFilename(disposition) ?? fileId;
-        const buffer = Buffer.from(await response.arrayBuffer());
-        const dir = outputDir ? path.resolve(outputDir) : process.cwd();
-        // The bytes are already fetched by this point, so a missing output directory
-        // would throw away paid network work — and it threw `ENOENT … open
-        // '<dir>/<file>'`, which the CLI renders as "File not found: <the file it was
-        // creating>". That reads as a bad file id or a deleted attachment and sends
-        // the reader to re-query the record. `-o` names a directory to write into;
-        // creating it is what the flag means.
-        await fs.promises.mkdir(dir, { recursive: true });
-        const filename = findAvailableFilename(dir, originalFilename, options?.reserved);
-        const absolutePath = path.join(dir, filename);
-        await fs.promises.writeFile(absolutePath, buffer);
-        return { path: absolutePath, filename };
-    }
-    async downloadRecordFiles(recordId, fieldKey, outputDir) {
-        const result = await this.execute("get_record", { record_id: recordId }, { format: "text" });
-        if (result.error)
-            throw new Error(result.error);
-        const record = result.result;
-        const files = record?.data?.[fieldKey];
-        if (!Array.isArray(files)) {
-            throw new Error(`Field ${fieldKey} on ${recordId} is not a file field or has no value`);
-        }
-        const fileIds = files.map((f, i) => {
-            if (typeof f !== "object" || f === null || !("id" in f) || typeof f.id !== "string") {
-                throw new Error(`Invalid file entry [${i}] in ${recordId}.${fieldKey}: ${JSON.stringify(f)}`);
+      }
+    }
+    return { files, errors };
+  }
+  /**
+   * Store one file by handing its bytes straight to object storage.
+   *
+   * The API mints presigned part URLs and registers the row; the bytes go
+   * directly from disk to the bucket and never enter the API process. That is
+   * what makes the ceiling "what a workspace may store" rather than "what one
+   * request may cost the server" — the reason `POST /v1/files` and the ticketed
+   * upload are both capped far lower, and the reason this exists at all.
+   *
+   * Parts are read one at a time rather than streamed as a request body: a part
+   * is bounded (the server picks 5–10 MiB), a `fetch` body needs a length the
+   * bucket will check anyway, and reading a slice keeps peak memory at one part
+   * instead of one file.
+   *
+   * The PUT loop itself — retry, backoff, part timeout, ordering — is
+   * `@lotics/shared/multipart_parts`, shared with the browser client so the
+   * hardening cannot exist on one side only.
+   */
+  async uploadLargeFile(input) {
+    const mimeType = getMimeType(input.filename);
+    const init = await this.request("POST", "/v1/files/multipart/init", {
+      filename: input.filename,
+      mime_type: mimeType,
+      file_size: input.size
+    });
+    const partLength = (part) => Math.min(init.part_size, input.size - (part.part_number - 1) * init.part_size);
+    const handle = await fs.promises.open(input.absolutePath, "r");
+    let uploaded;
+    try {
+      uploaded = await uploadParts({
+        parts: init.parts,
+        partBytes: partLength,
+        // Sequential. Peak memory is then one part rather than one file, which
+        // is the property that lets this run against a 2 GiB upload at all;
+        // raising it trades that for wall-clock, and no upload has asked yet.
+        concurrency: 1,
+        putPart: async (part, body, signal) => {
+          const response = await fetch(part.url, { method: "PUT", body, signal });
+          if (!response.ok) throw partErrorFor(part.part_number, response.status);
+          return response.headers.get("etag") ?? "";
+        },
+        readPart: async (part) => {
+          const offset = (part.part_number - 1) * init.part_size;
+          const length = partLength(part);
+          const buffer = Buffer.alloc(length);
+          let filled = 0;
+          while (filled < length) {
+            const { bytesRead } = await handle.read(buffer, filled, length - filled, offset + filled);
+            if (bytesRead === 0) {
+              throw new PermanentPartError(
+                `${input.filename} ended after ${offset + filled} bytes, short of the ${input.size} it reported \u2014 it changed while uploading`
+              );
             }
-            return f.id;
-        });
-        const reserved = new Set();
-        return Promise.all(fileIds.map(async (fileId) => {
-            const res = await this.downloadFileById(fileId, outputDir, { reserved });
-            return { ...res, file_id: fileId };
-        }));
-    }
-    async uploadFiles(filePaths, options) {
-        // Sequential, not `Promise.all`: `lotics upload <dir>` expands a directory to
-        // every file in it, and reading them all at once opens one handle per file —
-        // EMFILE on a large directory. The upload itself is a single request either
-        // way, so concurrency here buys nothing.
-        const items = [];
-        for (let i = 0; i < filePaths.length; i++) {
-            const absolutePath = path.resolve(filePaths[i]);
-            items.push({
-                bytes: await fs.promises.readFile(absolutePath),
-                filename: options?.filenames?.[i] ?? path.basename(absolutePath),
-            });
-        }
-        return this.uploadFileBytes(items);
-    }
-    /**
-     * Store files from bytes the caller already holds — the path for a caller that
-     * never had them on disk (an email attachment decoded in memory, a generated
-     * document, a fetched URL). `uploadFiles` is this with a read in front, so
-     * both routes hit one endpoint and one mime-derivation rule.
-     */
-    async uploadFileBytes(
-    // `Uint8Array<ArrayBuffer>`, not a bare `Uint8Array`: `Blob` takes a
-    // `BufferSource`, which excludes a `SharedArrayBuffer`-backed view. Every
-    // real source here (`readFile`, `Buffer.concat`, `response.arrayBuffer()`)
-    // is already ArrayBuffer-backed, so the narrower type states the
-    // requirement rather than casting it away at the call site.
-    items) {
-        const formData = new FormData();
-        for (const item of items) {
-            const mimeType = item.mimeType ?? getMimeType(item.filename);
-            // `Blob` copies a BufferSource by the VIEW's offset+length, so passing a
-            // pooled `Buffer` from `readFile` straight in is correct — no defensive
-            // re-copy, which would double peak memory on every upload.
-            formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
+            filled += bytesRead;
+          }
+          return buffer;
         }
-        const url = `${this.baseUrl}/v1/files`;
-        const headers = this.buildHeaders();
-        const response = await fetch(url, { method: "POST", headers, body: formData });
-        if (!response.ok)
-            await this.throwResponseError(response, headers["x-request-id"]);
-        return response.json();
-    }
-}
+      });
+    } catch (error) {
+      await this.request("POST", "/v1/files/multipart/abort", {
+        upload_id: init.upload_id,
+        file_storage_key: init.file_storage_key
+      }).catch(() => {
+      });
+      throw error;
+    } finally {
+      await handle.close();
+    }
+    const result = await this.request("POST", "/v1/files/multipart/complete", {
+      file_id: init.file_id,
+      upload_id: init.upload_id,
+      file_storage_key: init.file_storage_key,
+      filename: input.filename,
+      mime_type: mimeType,
+      parts: uploaded
+    });
+    const stored = result.files[0];
+    if (!stored) {
+      throw new Error(result.errors[0]?.error ?? "upload completed but stored no file");
+    }
+    return stored;
+  }
+  /**
+   * Store files from bytes the caller already holds — the path for a caller that
+   * never had them on disk (an email attachment decoded in memory, a generated
+   * document, a fetched URL). `uploadFiles` is this with a read in front, so
+   * both routes hit one endpoint and one mime-derivation rule.
+   */
+  async uploadFileBytes(items) {
+    const formData = new FormData();
+    for (const item of items) {
+      const mimeType = item.mimeType ?? getMimeType(item.filename);
+      formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
+    }
+    const url = `${this.baseUrl}/v1/files`;
+    const headers = this.buildHeaders();
+    const response = await fetch(url, { method: "POST", headers, body: formData });
+    if (!response.ok) await this.throwResponseError(response, headers["x-request-id"]);
+    return response.json();
+  }
+};
+export {
+  API_BASE_URL,
+  LoticsClient,
+  WEB_APP_URL,
+  fetchOfficialStarters
+};