@lotics/cli 0.83.0 → 0.86.1

package/README.md

@@ -227,7 +227,7 @@ lotics package config app_... --set show_done=false           # edit a live inst
 lotics uninstall app_... [--archive-tables]                   # remove an installation; workflows stop firing
 lotics package doctor app_...              # version pin vs latest + drift + local edits (exit 1 on findings)
 lotics upgrade app_...                     # preview, then apply (additive; overlay preserved)
-lotics upgrade apg_...                      # FLEET: upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
+lotics upgrade apg_...                      # APP package → FLEET: upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
 lotics upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
 lotics upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
 lotics upgrade app_... --resolve template.quote=revert        # a locally-edited template (clean ones auto-update; or =keep)
@@ -238,7 +238,7 @@ lotics package eject app_...               # one-way: sever the package link
 lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
 ```
 
-After the first publish **the origin is the master** — develop it in its workspace (`app pull` / `app deploy` / `app workflow set` / table tools), and `lotics app release` snapshots each version. Its **binding-aware re-extract** keeps aliases stable through the origin's current binding, so re-extraction never churns the upgrade diff (which is why extract-again is the loop, not a hazard).
+After the first publish **the origin is the master** — develop it in its workspace (`app pull` / `app deploy` / `app workflow set` / table tools), and `lotics app release` snapshots each version. Its **binding-aware re-extract** keeps aliases stable through the origin's current binding, so re-extraction never churns the upgrade diff (which is why extract-again is the loop, not a hazard). Release is also the **bundled-knowledge declaration surface**: run from the app project, the manifest's `lotics.knowledge` (`[{alias,doc_id}]`) re-declares which docs the package bundles — an alias added ships as a new doc, a bound alias dropped surfaces to consumers as `removed` (archive|keep), a present one re-snapshots; a bare id from elsewhere reconstructs the current corpus from the pin (never drops it). So a published app package evolves its bundled docs across versions without ejecting.
 
 ### Content packages
 
@@ -257,15 +257,16 @@ lotics run release_content '{"package_id":"apg_...","changelog":"v2: revised SOP
 lotics install apg_...                          # app OR content, shape-branched
 lotics install apg_... --bind-to policy=kdc_... # adopt an existing doc as package-managed
 
-# Discover installed content (the source for a pci_ id — install prints it once)
-lotics package list-content                           # id · package · version (standalone content installs)
+# Discover installed content (each row leads with the PACKAGE id)
+lotics package list-content                           # package id · package · version (standalone content installs)
 
-# Refresh a standalone content install (pci_ id from install / list-content) — one gate over docs + templates
-lotics upgrade pci_...                          # preview, then apply
-lotics upgrade pci_... --resolve knowledge.policy=apply   # a doc: apply|keep|archive|recreate|unbind
-lotics upgrade pci_... --resolve template.quote=revert    # a locally-edited template: revert|keep (clean ones auto-update)
-lotics upgrade pci_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
-lotics uninstall pci_... --keep-content            # remove the pin; keep docs + templates (default archives them)
+# Refresh this workspace's content install — addressed by PACKAGE id (one install per
+# package per workspace, so the package id is the address; one gate over docs + templates)
+lotics upgrade apg_...                          # CONTENT package → preview, then apply (this workspace's install)
+lotics upgrade apg_... --resolve knowledge.policy=apply   # a doc: apply|keep|archive|recreate|unbind
+lotics upgrade apg_... --resolve template.quote=revert    # a locally-edited template: revert|keep (clean ones auto-update)
+lotics upgrade apg_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
+lotics uninstall apg_... --keep-content            # remove the pin; keep docs + templates (default archives them)
 ```
 
 A package's knowledge can also arrive **bundled with an app**. Upgrading such an app (`lotics upgrade <app_id>`) previews its bundled-knowledge changes alongside the plan and resolves them in the SAME namespaced grammar — `--resolve knowledge.<alias>=apply|keep|archive|recreate|unbind` (the flags pass to the server verbatim; no routing, no ambiguity), `--bind-to` consents an added-doc collision, `--apply-all` takes the package's version for every consent-requiring doc.

package/dist/cli.js

@@ -14,7 +14,7 @@ import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
-import { packageInstall, packageUninstall, packageListContent, packageConfig, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeKnowledge, parseBindToFlags, appPublish, appRelease, appUnpublish, packageFleetUpgrade, packageYank, } from "./package_commands.js";
+import { packageInstall, packageUninstall, packageListContent, packageConfig, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeByPackageId, redirectContentPciForm, parseBindToFlags, appPublish, appRelease, appUnpublish, packageYank, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -114,18 +114,19 @@ COMMANDS
                                        Install a package (app: scaffolds/deploys/materializes,
                                        --config sets its knobs; content: installs the doc corpus,
                                        --bind-to consents to adopt a same-named doc on a collision)
-  lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]
+  lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]
                                        Uninstall — dispatched by id. App (app_id): archives
                                        artifacts (+ --archive-tables also archives scaffolded
-                                       tables). Content (pci_): archives its package-bound docs
-                                       unless --keep-content
-  lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
+                                       tables). Content package (apg_): archives its package-bound
+                                       docs unless --keep-content
+  lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
                                        Preview-then-apply an upgrade, dispatched by id. App
                                        (app_id): refuses while any drift/modified/bundled-knowledge
-                                       finding lacks a --resolve. Content (pci_): --resolve
-                                       <alias>=apply|keep|archive|recreate|unbind. Package (apg_):
-                                       FLEET — every installation across your org (clean apply,
-                                       findings skip). --apply-all accepts the package's version
+                                       finding lacks a --resolve. Package (apg_): a CONTENT package
+                                       upgrades THIS workspace's install (--resolve
+                                       <alias>=apply|keep|archive|recreate|unbind); an APP package
+                                       FLEET-upgrades every installation across your org (clean
+                                       apply, findings skip). --apply-all accepts the package's version
   lotics package doctor [app_id]       Installation health: version pin vs latest, binding
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
@@ -135,7 +136,8 @@ COMMANDS
                                        (re-deploys the pinned source as a bespoke app)
   lotics package show <package_id>     Registry metadata + version history
   lotics package list-content          List the workspace's content installations
-                                       (standalone content installs) — source for a pci_ id
+                                       (standalone content installs) — each row leads with
+                                       the package id for upgrade/uninstall
   lotics package yank <package_id> <version> [--undo]
                                        Refuse new installs/upgrades of a broken published
                                        version (pinned installations keep running)
@@ -713,8 +715,8 @@ async function main() {
         console.error("Usage (low-traffic consumer / registry ops — author verbs live on `lotics app`):");
         console.error("  The high-traffic consumer verbs are top-level:");
         console.error("    lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
-        console.error("    lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
-        console.error("    lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade — app / content / whole fleet (apg_)");
+        console.error("    lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
+        console.error("    lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade — app install / content install / whole app fleet (apg_)");
         console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
         console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
@@ -902,12 +904,17 @@ async function main() {
     if (command === "uninstall") {
         const id = subcommand;
         if (!id) {
-            console.error("Usage: lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]");
+            console.error("Usage: lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]");
             console.error("Dispatched by id: an app installation (app_id; --archive-tables to also archive its " +
-                "scaffolded tables) or a standalone content installation (pci_ id from `lotics install` / " +
+                "scaffolded tables) or a content package (apg_ id from `lotics install` / " +
                 "lotics package list-content; --keep-content to retain its docs).");
             process.exit(1);
         }
+        // A `pci_` resource id is retired from human sight — redirect to the package-id form.
+        if (id.startsWith("pci_")) {
+            await redirectContentPciForm(client, id, "uninstall");
+            return;
+        }
         await packageUninstall(client, {
             id,
             keep_content: flags.keepContent,
@@ -918,9 +925,9 @@ async function main() {
     if (command === "upgrade") {
         const target = subcommand;
         if (!target) {
-            console.error("Usage: lotics upgrade <app_id | pci_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]");
-            console.error("Dispatched by id: an app installation (app_id), a standalone content installation (pci_ id), " +
-                "or a package id (apg_ — fleet-upgrades every installation across your org).");
+            console.error("Usage: lotics upgrade <app_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]");
+            console.error("Dispatched by id: an app installation (app_id), or a package id (apg_) — a CONTENT package " +
+                "upgrades this workspace's install; an APP package fleet-upgrades every installation across your org.");
             process.exit(1);
         }
         let version;
@@ -931,22 +938,24 @@ async function main() {
                 process.exit(1);
             }
         }
-        // A package id fleet-upgrades every installation across the org; a `pci_` id
-        // is a standalone content installation; anything else is an app installation.
-        if (target.startsWith("apg_")) {
-            await packageFleetUpgrade(client, { package_id: target, version });
+        // A `pci_` resource id is retired from human sight — redirect to the package-id form.
+        if (target.startsWith("pci_")) {
+            await redirectContentPciForm(client, target, "upgrade");
             return;
         }
-        if (target.startsWith("pci_")) {
-            await packageUpgradeKnowledge(client, {
-                installation_id: target,
+        // A package id (apg_) is kind-branched: a content package upgrades THIS
+        // workspace's install; an app package fleet-upgrades the whole org.
+        if (target.startsWith("apg_")) {
+            await packageUpgradeByPackageId(client, {
+                package_id: target,
                 version,
                 resolve: flags.resolve,
-                bind_to: parseBindToFlags(flags.bindTo),
+                bindTo: flags.bindTo,
                 applyAll: flags.applyAll,
             });
             return;
         }
+        // Anything else is an app installation (addressed by its app id).
         await packageUpgrade(client, {
             app_id: target,
             version,
@@ -1019,8 +1028,8 @@ async function main() {
         // `lotics package <verb>` forms loudly with a redirect, never a silent no-op.
         const movedVerbs = {
             install: "lotics install <package_id>",
-            uninstall: "lotics uninstall <app_id|pci_id>",
-            upgrade: "lotics upgrade <app_id|pci_id|package_id>",
+            uninstall: "lotics uninstall <app_id|package_id>",
+            upgrade: "lotics upgrade <app_id|package_id>",
             "fleet-upgrade": "lotics upgrade <package_id>",
         };
         if (subcommand !== undefined && subcommand in movedVerbs) {
@@ -1330,8 +1339,10 @@ async function main() {
                 console.log(JSON.stringify({ error: result.error }, null, 2));
             }
             else {
+                // Execution errors (not-found, refusals) carry the server's message;
+                // the input already passed schema validation, so no schema hint —
+                // validation 400s bring the server's own hint via throwResponseError.
                 console.error(result.error);
-                console.error(`\nHint: run "lotics tools ${toolName}" to see the expected input schema.`);
             }
             process.exit(1);
         }

package/dist/cli_dispatch.test.js

@@ -104,8 +104,8 @@ describe("lotics top-level consumer-verb dispatch", () => {
     // bare invocation — reaching it fires before any network work.
     const usageCases = [
         ["install", /Usage: lotics install <package_id>/],
-        ["uninstall", /Usage: lotics uninstall <app_id\|pci_id>/],
-        ["upgrade", /Usage: lotics upgrade <app_id \| pci_id \| package_id>/],
+        ["uninstall", /Usage: lotics uninstall <app_id\|package_id>/],
+        ["upgrade", /Usage: lotics upgrade <app_id \| package_id>/],
     ];
     for (const [verb, usage] of usageCases) {
         it(`routes top-level "${verb}" to its handler (usage on missing id)`, () => {
@@ -115,6 +115,19 @@ describe("lotics top-level consumer-verb dispatch", () => {
             expect(status).toBe(1);
         });
     }
+    // CLEAN BREAK: content installs are addressed by their PACKAGE id — an explicit
+    // `pci_` resource id must get a loud redirect to the package-id form. The redirect
+    // header prints SYNCHRONOUSLY (before the best-effort list-content resolution that
+    // spells out the exact command), so it is observable without a live registry; the
+    // process exits 1 either way (best-effort resolution fails on the fake key).
+    for (const verb of ["upgrade", "uninstall"]) {
+        it(`redirects an explicit pci_ id on "${verb}" to the package-id form`, () => {
+            const { status, stderr } = runCli([verb, "pci_dispatch_smoke_fake"]);
+            expect(stderr).toMatch(/addressed by their PACKAGE id now/);
+            expect(stderr).not.toMatch(/Unknown command/);
+            expect(status).toBe(1);
+        });
+    }
 });
 describe("lotics app author-verb dispatch", () => {
     // `app publish` (no id, empty cwd) must fail on the missing local app

package/dist/client.d.ts

@@ -542,31 +542,60 @@ export declare class LoticsClient {
     /**
      * Preview a release — the dry run behind `lotics app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, and
-     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * binding) and reports the next version number, the new + changed aliases, the
+     * bundled-knowledge delta, and any extract findings (an `error` blocks the
+     * apply). An optional `knowledge` declaration (from the pulled app manifest)
+     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
+     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
      * owning-org only.
      */
-    previewPackageRelease(app_id: string): Promise<{
+    previewPackageRelease(app_id: string, opts?: {
+        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
+    }): Promise<{
         package_id: string;
         version: number;
         added_aliases: string[];
         changed_artifacts: string[];
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        knowledge?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
         findings: ExtractFinding[];
     }>;
     /**
      * Release — snapshot the origin app into the next registry version. The server
      * binding-aware-extracts it, repackages its deployed source + dist as the
      * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * re-pins the origin. An optional `knowledge` declaration re-declares the
+     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
+     * the current corpus). Error findings from extract surface as a 409; a
+     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
      * owning-org only. Backs `lotics app release --yes`.
      */
     releasePackage(app_id: string, body: {
         changelog: string;
+        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
     }): Promise<{
         package_id: string;
         version: number;
         added_aliases: string[];
         changed_artifacts: string[];
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        knowledge?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
     }>;
     /**
      * Dry-run preview of a first-release — the `GET` behind `lotics app publish`

package/dist/client.js

@@ -353,18 +353,29 @@ export class LoticsClient {
     /**
      * Preview a release — the dry run behind `lotics app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
-     * binding) and reports the next version number, the new + changed aliases, and
-     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * binding) and reports the next version number, the new + changed aliases, the
+     * bundled-knowledge delta, and any extract findings (an `error` blocks the
+     * apply). An optional `knowledge` declaration (from the pulled app manifest)
+     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
+     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
      * owning-org only.
      */
-    async previewPackageRelease(app_id) {
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release`);
+    async previewPackageRelease(app_id, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
+            params.set("knowledge", JSON.stringify(opts.knowledge));
+        }
+        const query = params.toString();
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
     }
     /**
      * Release — snapshot the origin app into the next registry version. The server
      * binding-aware-extracts it, repackages its deployed source + dist as the
      * bundle, publishes the next `release`-channel version with the changelog, and
-     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * re-pins the origin. An optional `knowledge` declaration re-declares the
+     * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
+     * the current corpus). Error findings from extract surface as a 409; a
+     * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
      * owning-org only. Backs `lotics app release --yes`.
      */
     async releasePackage(app_id, body) {

package/dist/dev/file_relay.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Dev-only GET relay: the read half of the same problem `upload_relay.ts` solves.
+ *
+ * The server presigns every file cell an app query returns (`url` / `thumbnail_url` /
+ * `preview_url` on each file object), and those URLs point at the PROD bucket, whose
+ * CORS admits `https://*.lotics.app` and not `http://localhost:<port>`. Displaying
+ * such a URL is fine — `<img>` and `<video>` loads are not CORS-gated, and neither is
+ * the top-level navigation `openExternal` performs. But **fetching the bytes** is, and
+ * that is exactly what every preview engine does (PDF, Word, Excel all read the file
+ * into memory), so file preview could never work in `lotics app dev`.
+ *
+ * So the dev server hands the app same-origin URLs and fetches the bytes itself.
+ *
+ * The security property is the one that governs the upload relay: the app never names
+ * a destination. It receives an opaque token, and the relay reads ONLY from a URL the
+ * server itself observed the API return for that token. No client-controlled target,
+ * nothing to allowlist, no SSRF surface.
+ *
+ * Production is untouched: it serves presigned URLs straight from storage.
+ */
+export interface FileRelay {
+    /**
+     * Deep-copy an RPC result with every presigned file URL swapped for one served by
+     * this dev server. Immutable: the input is never mutated. Anything that isn't a
+     * presigned URL on a file object passes through byte-identical.
+     */
+    rewrite(result: unknown): unknown;
+    /** The URL this token stands for — `null` if unknown or expired. */
+    destinationFor(token: string): string | null;
+    /** Live tokens — for tests. */
+    size(): number;
+}
+/**
+ * `wrapperOrigin` — e.g. `http://localhost:5174`. The URL must be ABSOLUTE: these
+ * URLs are consumed inside the app **iframe**, which is served from Vite's origin, so
+ * a relative `/_file/…` would resolve against Vite and 404. (The upload relay's URL is
+ * consumed by the wrapper page itself, where relative is correct.)
+ */
+export declare function createFileRelay(wrapperOrigin: string, now?: () => number): FileRelay;

package/dist/dev/file_relay.js

@@ -0,0 +1,87 @@
+/**
+ * Dev-only GET relay: the read half of the same problem `upload_relay.ts` solves.
+ *
+ * The server presigns every file cell an app query returns (`url` / `thumbnail_url` /
+ * `preview_url` on each file object), and those URLs point at the PROD bucket, whose
+ * CORS admits `https://*.lotics.app` and not `http://localhost:<port>`. Displaying
+ * such a URL is fine — `<img>` and `<video>` loads are not CORS-gated, and neither is
+ * the top-level navigation `openExternal` performs. But **fetching the bytes** is, and
+ * that is exactly what every preview engine does (PDF, Word, Excel all read the file
+ * into memory), so file preview could never work in `lotics app dev`.
+ *
+ * So the dev server hands the app same-origin URLs and fetches the bytes itself.
+ *
+ * The security property is the one that governs the upload relay: the app never names
+ * a destination. It receives an opaque token, and the relay reads ONLY from a URL the
+ * server itself observed the API return for that token. No client-controlled target,
+ * nothing to allowlist, no SSRF surface.
+ *
+ * Production is untouched: it serves presigned URLs straight from storage.
+ */
+import { createHash } from "node:crypto";
+/** Presigned GETs live ~24h; a token outlives its URL by nothing. */
+const TTL_MS = 24 * 60 * 60 * 1000;
+/** A long dev session re-queries constantly; each query re-presigns. Bound the table. */
+const MAX_ENTRIES = 5000;
+/**
+ * The keys the backend presigns on a file object (`file_url_resolver.ts`). Only these,
+ * and only on something that is actually a file, get rewritten — a record's own text
+ * cell holding a link (a public app URL, say) must keep pointing where it points.
+ */
+const PRESIGNED_KEYS = new Set(["url", "thumbnail_url", "preview_url"]);
+const isFileObject = (o) => typeof o.filename === "string" && typeof o.mime_type === "string";
+const isRemoteUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+/**
+ * `wrapperOrigin` — e.g. `http://localhost:5174`. The URL must be ABSOLUTE: these
+ * URLs are consumed inside the app **iframe**, which is served from Vite's origin, so
+ * a relative `/_file/…` would resolve against Vite and 404. (The upload relay's URL is
+ * consumed by the wrapper page itself, where relative is correct.)
+ */
+export function createFileRelay(wrapperOrigin, now = Date.now) {
+    const seen = new Map();
+    // A stable token per URL: the same file re-queried doesn't mint a new entry, so the
+    // table tracks distinct presigns, not query volume. (Truncated — this is a lookup
+    // key in a localhost-only process, not a secret.)
+    const tokenFor = (url) => createHash("sha256").update(url).digest("hex").slice(0, 24);
+    const remember = (url) => {
+        const token = tokenFor(url);
+        seen.set(token, { url, at: now() });
+        if (seen.size > MAX_ENTRIES) {
+            // Insertion-ordered: drop the oldest.
+            const oldest = seen.keys().next();
+            if (!oldest.done)
+                seen.delete(oldest.value);
+        }
+        return token;
+    };
+    const walk = (node) => {
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (!node || typeof node !== "object")
+            return node;
+        const obj = node;
+        const file = isFileObject(obj);
+        const out = {};
+        for (const [key, value] of Object.entries(obj)) {
+            out[key] =
+                file && PRESIGNED_KEYS.has(key) && isRemoteUrl(value)
+                    ? `${wrapperOrigin}/_file/${remember(value)}`
+                    : walk(value);
+        }
+        return out;
+    };
+    return {
+        rewrite: (result) => walk(result),
+        destinationFor(token) {
+            const entry = seen.get(token);
+            if (!entry)
+                return null;
+            if (now() - entry.at > TTL_MS) {
+                seen.delete(token);
+                return null;
+            }
+            return entry.url;
+        },
+        size: () => seen.size,
+    };
+}

package/dist/dev/file_relay.test.d.ts

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

package/dist/dev/file_relay.test.js

@@ -0,0 +1,87 @@
+import { describe, it, expect } from "vitest";
+import { createFileRelay } from "./file_relay.js";
+const ORIGIN = "http://localhost:5174";
+const PRESIGNED = "https://production.r2.cloudflarestorage.com/org/files/fil_a/photo.jpg?X-Amz-Signature=abc";
+const THUMB = "https://production.r2.cloudflarestorage.com/org/files/fil_a/thumb.jpg?X-Amz-Signature=def";
+const fileCell = {
+    id: "fil_a",
+    filename: "photo.jpg",
+    mime_type: "image/jpeg",
+    url: PRESIGNED,
+    thumbnail_url: THUMB,
+};
+/** A query result, shaped like the real thing: rows, each with a files cell. */
+const queryResult = { rows: [{ id: "rec_1", giay_to: [fileCell] }] };
+describe("file relay — the app reads bytes from us, not from storage", () => {
+    it("rewrites every presigned URL on a file cell to an absolute URL on the dev server", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        const cell = out.rows[0].giay_to[0];
+        // ABSOLUTE: the app runs in the Vite-origin iframe, so a relative path would
+        // resolve against Vite and 404.
+        expect(cell.url).toMatch(/^http:\/\/localhost:5174\/_file\/[a-f0-9]{24}$/);
+        expect(cell.thumbnail_url).toMatch(/^http:\/\/localhost:5174\/_file\/[a-f0-9]{24}$/);
+        expect(cell.url).not.toBe(cell.thumbnail_url);
+    });
+    it("reads back the exact storage URL the token stands for", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        const token = out.rows[0].giay_to[0].url.split("/_file/")[1];
+        expect(relay.destinationFor(token)).toBe(PRESIGNED);
+    });
+    it("leaves the rest of the payload byte-identical and never mutates the input", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite(queryResult);
+        expect(out.rows[0].id).toBe("rec_1");
+        expect(out.rows[0].giay_to[0].filename).toBe("photo.jpg");
+        expect(fileCell.url).toBe(PRESIGNED); // input untouched
+    });
+});
+describe("file relay — it rewrites file URLs, not every URL it sees", () => {
+    it("does NOT touch a link that lives in a record's own text cell", () => {
+        // The customer's "Link tự khai" field holds a real URL the user clicks. Relaying it
+        // would send them to the dev server instead of the site.
+        const relay = createFileRelay(ORIGIN);
+        const row = { id: "rec_1", link_tu_khai: "https://dang-ky-noxh.lotics.app?kh=KH-2026-919" };
+        const out = relay.rewrite({ rows: [row] });
+        expect(out.rows[0].link_tu_khai).toBe("https://dang-ky-noxh.lotics.app?kh=KH-2026-919");
+        expect(relay.size()).toBe(0);
+    });
+    it("does NOT touch a `url` key on something that isn't a file", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite({ webhook: { url: "https://example.com/hook" } });
+        expect(out.webhook.url).toBe("https://example.com/hook");
+        expect(relay.size()).toBe(0);
+    });
+    it("reaches file cells wherever they are nested — a workflow's generated files, too", () => {
+        const relay = createFileRelay(ORIGIN);
+        const out = relay.rewrite({
+            data: { status: "ok" },
+            files: [{ id: "fil_z", filename: "don.docx", mime_type: "application/vnd...", url: PRESIGNED }],
+        });
+        expect(out.files[0].url).toContain("/_file/");
+    });
+});
+describe("file relay — it reads ONLY what it handed out", () => {
+    it("refuses a token it never minted", () => {
+        const relay = createFileRelay(ORIGIN);
+        expect(relay.destinationFor("deadbeefdeadbeefdeadbeef")).toBeNull();
+    });
+    it("refuses a token whose presign has aged out", () => {
+        let clock = 0;
+        const relay = createFileRelay(ORIGIN, () => clock);
+        const out = relay.rewrite(queryResult);
+        const token = out.rows[0].giay_to[0].url.split("/_file/")[1];
+        clock += 25 * 60 * 60 * 1000; // presigned GETs live ~24h
+        expect(relay.destinationFor(token)).toBeNull();
+    });
+});
+describe("file relay — a long dev session re-queries constantly", () => {
+    it("mints one stable token per URL rather than growing on every query", () => {
+        const relay = createFileRelay(ORIGIN);
+        const a = relay.rewrite(queryResult);
+        const b = relay.rewrite(queryResult);
+        expect(b.rows[0].giay_to[0].url).toBe(a.rows[0].giay_to[0].url);
+        expect(relay.size()).toBe(2); // the file and its thumbnail — not four
+    });
+});

package/dist/dev/server.d.ts

@@ -5,11 +5,29 @@
  *   1. Vite dev server (npx vite --port <vite-port>) — child_process.spawn,
  *      stdio inherited so Vite's own logging surfaces to the developer.
  *   2. node:http server on <port> serving:
- *        GET  /        → wrapper HTML (cached: no)
- *        POST /_rpc    → JSON in, dispatched via rpc_handler, JSON out
- *        *             → 404
+ *        GET  /               → wrapper HTML (cached: no)
+ *        POST /_rpc           → JSON in, dispatched via rpc_handler, JSON out
+ *        POST /_agent_run     → SSE, piped from the run
+ *        PUT  /_upload/:id    → file bytes in  (relayed to storage)
+ *        GET  /_file/:token   → file bytes out (relayed from storage)
+ *        *                    → 404
  *
  * SIGINT (Ctrl-C) → kill Vite child, close HTTP server, exit 0.
+ *
+ * Why the byte relays exist: dev runs against the PROD bucket (there is no dev
+ * bucket), whose CORS allowlist holds the real app origins (`https://*.lotics.app`),
+ * not `http://localhost:<port>`. So a browser transfer straight to/from the presigned
+ * URL is blocked before it leaves the page — no upload could complete, and no preview
+ * engine (PDF/Word/Excel all FETCH the bytes) could read a file. Relaying through THIS
+ * server fixes both: Node has no same-origin policy, and the one cross-origin hop that
+ * remains (the app iframe reading from us) is OUR response to allow.
+ *
+ * Neither relay ever takes a destination from the client: the page sends a `file_id`
+ * or an opaque token, and the server transfers only to/from a URL IT minted or observed
+ * for that id. No client-controlled target ⇒ no SSRF surface, nothing to allowlist.
+ *
+ * Production is untouched — it transfers direct-to-storage, keeping every byte off the
+ * API server.
  */
 import { type ChildProcess } from "node:child_process";
 import { LoticsClient } from "../client.js";