@anteros/core 0.0.41 → 0.0.42

package/tests/attachment.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "bun:test";
+import { deflateRawSync } from "node:zlib";
+import { openZip } from "../lib/zip";
+import { docxText, resolveAttachments, xlsxText, MAX_FILE_BYTES } from "../lib/attachment";
+import { openaiMessages, anthropicMessages } from "../lib/providers";
+
+/**
+ * Attachments — a file becomes text, an image or a document part, and the zip
+ * reader behind `.docx` / `.xlsx` is exercised against **real** archives built by
+ * `makeZip` (the same bytes Office writes: local headers + central directory).
+ */
+
+/** Minimal ZIP writer (deflate or stored) — enough to build a .docx/.xlsx fixture. */
+function makeZip(entries: Record<string, string>, options: { store?: boolean } = {}): Uint8Array {
+    const encoder = new TextEncoder();
+    const locals: Uint8Array[] = [];
+    const central: Uint8Array[] = [];
+    let offset = 0;
+
+    const crcTable = (() => {
+        const table = new Uint32Array(256);
+        for (let i = 0; i < 256; i++) {
+            let c = i;
+            for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            table[i] = c >>> 0;
+        }
+        return table;
+    })();
+
+    const crc32 = (bytes: Uint8Array): number => {
+        let crc = 0xffffffff;
+        for (const byte of bytes) crc = crcTable[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
+        return (crc ^ 0xffffffff) >>> 0;
+    };
+
+    for (const [name, content] of Object.entries(entries)) {
+        const raw = encoder.encode(content);
+        const method = options.store ? 0 : 8;
+        const data = options.store ? raw : new Uint8Array(deflateRawSync(raw));
+        const nameBytes = encoder.encode(name);
+        const crc = crc32(raw);
+
+        const local = new Uint8Array(30 + nameBytes.length + data.length);
+        const localView = new DataView(local.buffer);
+        localView.setUint32(0, 0x04034b50, true);
+        localView.setUint16(4, 20, true);           // version
+        localView.setUint16(8, method, true);
+        localView.setUint32(14, crc, true);
+        localView.setUint32(18, data.length, true); // compressed
+        localView.setUint32(22, raw.length, true);  // uncompressed
+        localView.setUint16(26, nameBytes.length, true);
+        local.set(nameBytes, 30);
+        local.set(data, 30 + nameBytes.length);
+        locals.push(local);
+
+        const entry = new Uint8Array(46 + nameBytes.length);
+        const entryView = new DataView(entry.buffer);
+        entryView.setUint32(0, 0x02014b50, true);
+        entryView.setUint16(4, 20, true);           // version made by
+        entryView.setUint16(6, 20, true);           // version needed
+        entryView.setUint16(10, method, true);
+        entryView.setUint32(16, crc, true);
+        entryView.setUint32(20, data.length, true);
+        entryView.setUint32(24, raw.length, true);
+        entryView.setUint16(28, nameBytes.length, true);
+        entryView.setUint32(42, offset, true);      // local header offset
+        entry.set(nameBytes, 46);
+        central.push(entry);
+
+        offset += local.length;
+    }
+
+    const centralSize = central.reduce((total, entry) => total + entry.length, 0);
+    const end = new Uint8Array(22);
+    const endView = new DataView(end.buffer);
+    endView.setUint32(0, 0x06054b50, true);
+    endView.setUint16(8, central.length, true);
+    endView.setUint16(10, central.length, true);
+    endView.setUint32(12, centralSize, true);
+    endView.setUint32(16, offset, true);
+
+    const total = offset + centralSize + 22;
+    const zip = new Uint8Array(total);
+    let cursor = 0;
+    for (const chunk of [...locals, ...central, end]) {
+        zip.set(chunk, cursor);
+        cursor += chunk.length;
+    }
+    return zip;
+}
+
+const DOCX = makeZip({
+    "[Content_Types].xml": "<Types/>",
+    "word/document.xml":
+        '<w:body><w:p><w:r><w:t>Invoice INV-2026-001</w:t></w:r></w:p>'
+        + "<w:p><w:r><w:t>Total: 1 200 &amp; 50 EUR</w:t></w:r></w:p>"
+        + "<w:p><w:r><w:tab/><w:t>Paid</w:t></w:r></w:p></w:body>",
+});
+
+const XLSX = makeZip({
+    "xl/sharedStrings.xml":
+        "<sst><si><t>Product</t></si><si><r><t>Widget</t></r><r><t> A</t></r></si>"
+        + "<si><t>Invoice INV-2026-001</t></si></sst>",
+    "xl/worksheets/sheet1.xml":
+        "<worksheet><sheetData>"
+        + '<row r="1"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c></row>'
+        + '<row r="2"><c r="A2" t="s"><v>2</v></c><c r="B2"><v>99.5</v></c><c r="C2" t="inlineStr"><is><t>x,y</t></is></c></row>'
+        + "</sheetData></worksheet>",
+});
+
+const qr = await resolveAttachments({ name: "photo.png", mimeType: "image/png", data: Buffer.from("PNG!").toString("base64") });
+
+describe("openZip", () => {
+    it("lists and reads the entries of a deflated archive", () => {
+        const zip = openZip(XLSX);
+        expect(zip.names().sort()).toEqual(["xl/sharedStrings.xml", "xl/worksheets/sheet1.xml"]);
+        expect(new TextDecoder().decode(zip.read("xl/sharedStrings.xml")!)).toContain("Invoice");
+        expect(zip.read("nope.xml")).toBeNull();
+    });
+
+    it("reads stored entries too, and refuses a non-archive", () => {
+        const zip = openZip(makeZip({ "a.txt": "hello" }, { store: true }));
+        expect(new TextDecoder().decode(zip.read("a.txt")!)).toBe("hello");
+
+        expect(() => openZip(new TextEncoder().encode("not a zip at all"))).toThrow(/central directory/);
+    });
+});
+
+describe("office extraction", () => {
+    it("extracts the text of a .docx, one line per paragraph", () => {
+        const text = docxText(openZip(DOCX));
+        expect(text).toContain("Invoice INV-2026-001");
+        expect(text).toContain("Total: 1 200 & 50 EUR"); // entities decoded
+        expect(text.split("\n").filter(Boolean)).toHaveLength(3);
+    });
+
+    it("extracts the rows of a .xlsx as CSV, shared strings resolved", () => {
+        const text = xlsxText(openZip(XLSX));
+        expect(text).toContain("### Sheet 1");
+        expect(text).toContain("Product,Widget A");           // concatenated runs
+        expect(text).toContain("Invoice INV-2026-001,99.5");  // shared string + number
+        expect(text).toContain('"x,y"');                      // a value with a comma is quoted
+    });
+});
+
+describe("resolveAttachments", () => {
+    it("turns text formats into a text part naming the file", async () => {
+        const parts = await resolveAttachments(
+            { name: "data.csv", data: Buffer.from("a,b\n1,2").toString("base64") },
+        );
+        expect(parts).toHaveLength(1);
+        expect(parts[0]).toEqual({ type: "text", text: "--- data.csv ---\na,b\n1,2" });
+    });
+
+    it("accepts UTF-8 payloads without base64", async () => {
+        const parts = await resolveAttachments({ name: "notes.md", data: "# Hi", encoding: "utf8" });
+        expect((parts[0] as any).text).toBe("--- notes.md ---\n# Hi");
+    });
+
+    it("keeps an image as an image part", () => {
+        expect(qr[0]).toEqual({ type: "image", data: Buffer.from("PNG!").toString("base64"), mimeType: "image/png" });
+    });
+
+    it("keeps a PDF as a document part", async () => {
+        const parts = await resolveAttachments({ name: "invoice.pdf", data: Buffer.from("%PDF-1.7").toString("base64") });
+        expect(parts[0]).toEqual({
+            type: "file",
+            name: "invoice.pdf",
+            mimeType: "application/pdf",
+            data: Buffer.from("%PDF-1.7").toString("base64"),
+        });
+    });
+
+    it("extracts .docx and .xlsx to text", async () => {
+        const [docx, xlsx] = await resolveAttachments([
+            { name: "invoice.docx", data: Buffer.from(DOCX).toString("base64") },
+            { name: "sales.xlsx", data: Buffer.from(XLSX).toString("base64") },
+        ]);
+
+        expect((docx as any).text).toContain("--- invoice.docx ---");
+        expect((docx as any).text).toContain("Invoice INV-2026-001");
+        expect((xlsx as any).text).toContain("Product,Widget A");
+    });
+
+    it("reads a path on the server — relative to the base dir", async () => {
+        const parts = await resolveAttachments("./fixtures/attachment/data.csv", {
+            baseDir: "packages/core/tests",
+        });
+        expect((parts[0] as any).text).toBe("--- data.csv ---\nref,total\nA-1,99");
+    });
+
+    it("refuses what a model cannot read, and says why", async () => {
+        await expect(resolveAttachments(
+            { name: "legacy.doc", data: Buffer.from("D0CF11E0").toString("base64") },
+        )).rejects.toMatchObject({ code: "AGENT_FILE_UNSUPPORTED" });
+
+        await expect(resolveAttachments(
+            { name: "archive.tar.gz", data: Buffer.from("...").toString("base64") },
+        )).rejects.toThrow(/supported attachments/);
+
+        await expect(resolveAttachments("./fixtures/attachment/missing.pdf", {
+            baseDir: "packages/core/tests",
+        })).rejects.toMatchObject({ code: "AGENT_FILE_NOT_FOUND" });
+    });
+
+    it("refuses a file over the size limit", async () => {
+        const oversized = { name: "big.pdf", data: new Uint8Array(MAX_FILE_BYTES + 1) };
+        await expect(resolveAttachments(oversized)).rejects.toMatchObject({ code: "AGENT_FILE_TOO_LARGE" });
+    });
+});
+
+describe("attachments through a provider", () => {
+    it("maps an image and a PDF to both protocols", () => {
+        const messages = [{
+            role: "user" as const,
+            content: [
+                { type: "text" as const, text: "What is this?" },
+                { type: "image" as const, data: "AAAA", mimeType: "image/png" },
+                { type: "file" as const, name: "invoice.pdf", mimeType: "application/pdf", data: "BBBB" },
+            ],
+        }];
+
+        const openai = openaiMessages(undefined, messages as any)[0];
+        expect(openai.content[0]).toEqual({ type: "text", text: "What is this?" });
+        expect(openai.content[1].image_url.url).toBe("data:image/png;base64,AAAA");
+        expect(openai.content[2]).toEqual({
+            type: "file",
+            file: { filename: "invoice.pdf", file_data: "data:application/pdf;base64,BBBB" },
+        });
+
+        const anthropic = anthropicMessages(messages as any).messages[0];
+        expect(anthropic.content[1]).toEqual({
+            type: "image",
+            source: { type: "base64", media_type: "image/png", data: "AAAA" },
+        });
+        expect(anthropic.content[2]).toEqual({
+            type: "document",
+            source: { type: "base64", media_type: "application/pdf", data: "BBBB" },
+        });
+    });
+});

package/tests/audit-operations.test.ts

@@ -145,7 +145,7 @@ describe("audit — services", () => {
         const before = await internalRest.db.collection(AUDIT_COLLECTION)
             .countDocuments({ "operation.action": "runService" });
 
-        const res = await fetch(`${url}/services/${TENANT}/${SERVICE}/charge`, {
+        const res = await fetch(`${url}/api/${TENANT}/services/${SERVICE}/charge`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ data: { amount: 7 } }),

package/tests/audit-redact.test.ts

@@ -77,10 +77,36 @@ afterAll(async () => {
     delete (cfg.server as any).audit;
 });
 
+// The URL shape, pinned here — every surface moved to `/api/:tenant_id/<family>/…`
+describe("API layout", () => {
+    it("serves nothing on a pre-refactor path", async () => {
+        // `/api/<tenant>/<collection>/<action>` used to be a collection action. No alias
+        // is mounted, so it is a plain 404 — never a silent misroute on another handler.
+        const legacy = await fetch(`${url}/api/${TENANT}/${SLUG}/find`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ $limit: 1 }),
+        });
+        expect(legacy.status).toBe(404);
+
+        // Same for a surface that moved with its own family
+        expect((await fetch(`${url}/services/${TENANT}/billing/charge`, { method: "POST" })).status).toBe(404);
+        expect((await fetch(`${url}/upload/${TENANT}/${SLUG}`, { method: "POST" })).status).toBe(404);
+
+        // …and the new shape is what answers
+        const current = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/find`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ $limit: 1 }),
+        });
+        expect(current.status).toBe(200);
+    });
+});
+
 describe("audit redaction — defaults", () => {
     it("masks the password of a login payload (success path)", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/login`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/login`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ payload: { email: "ada@example.com", password: "SuperSecret123!" } }),
@@ -95,7 +121,7 @@ describe("audit redaction — defaults", () => {
 
     it("masks the password of a login payload (failure path)", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/login`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/login`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ payload: { email: "bad", password: "WrongOne!" } }),
@@ -156,7 +182,7 @@ describe("audit redaction — defaults", () => {
 
     it("redacts the request headers and query string", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/find?token=query-secret&page=2`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/find?token=query-secret&page=2`, {
             method: "POST",
             headers: {
                 "Content-Type": "application/json",

package/tests/audit-run-action.test.ts

@@ -81,7 +81,7 @@ describe("audit — custom actions (runAction)", () => {
 
     it("audits the HTTP route as well, and marks it as not internal", async () => {
         const since = new Date();
-        const res = await fetch(`${url}/api/${TENANT}/${SLUG}/greet`, {
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/greet`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ data: { name: "Grace" } }),

package/tests/endpoints.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "bun:test";
+import { endpoints, FAMILIES, isReservedFamily, patterns, segment } from "../lib/endpoints";
+
+/**
+ * The URL of everything — pinned here so a change of shape is a **deliberate**
+ * change (the whole surface moved to `/api/:tenant_id/<family>/…` once already,
+ * and every client, doc and skill had to follow).
+ */
+
+describe("endpoints — the server patterns", () => {
+    it("keeps every surface under `/api/:tenant_id/<family>`", () => {
+        for (const pattern of Object.values(patterns)) {
+            expect(pattern.startsWith("/api/:tenant_id/")).toBe(true);
+        }
+    });
+
+    it("names a family the builders also use", () => {
+        const families = new Set<string>(FAMILIES);
+        for (const pattern of Object.values(patterns)) {
+            const [, , , family] = pattern.split("/");
+            expect(families.has(family!)).toBe(true);
+        }
+    });
+
+    it("registers no pattern that could shadow a collection action", () => {
+        // A collection lives under `/collections/`, so `services`, `vars` or `login`
+        // are usable as collection names — that is the point of the layout.
+        expect(patterns.collection.split("/")[3]).toBe("collections");
+        expect(patterns.login).toBe("/api/:tenant_id/collections/:collection/login");
+    });
+});
+
+describe("endpoints — the builders", () => {
+    it("builds the documented paths", () => {
+        expect(endpoints.collection("v1", "orders", "find")).toBe("/api/v1/collections/orders/find");
+        expect(endpoints.collection("v1", "users", "login")).toBe("/api/v1/collections/users/login");
+        expect(endpoints.service("v1", "billing", "charge")).toBe("/api/v1/services/billing/charge");
+        expect(endpoints.vars("v1", "get")).toBe("/api/v1/vars/get");
+        expect(endpoints.upload("v1", "photos")).toBe("/api/v1/upload/photos");
+        expect(endpoints.file("v1", "photos", "507f1f77.jpg")).toBe("/api/v1/files/photos/507f1f77.jpg");
+        expect(endpoints.agent("v1", "support", "generate")).toBe("/api/v1/agents/support/generate");
+        expect(endpoints.mcp("v1")).toBe("/api/v1/mcp");
+    });
+
+    it("matches the pattern it maps to", () => {
+        const mapped: Array<[string, string]> = [
+            [patterns.collection, endpoints.collection("t", "c", "a")],
+            [patterns.login, endpoints.collection("t", "c", "login")],
+            [patterns.service, endpoints.service("t", "s", "a")],
+            [patterns.vars, endpoints.vars("t", "a")],
+            [patterns.upload, endpoints.upload("t", "c")],
+            [patterns.file, endpoints.file("t", "c", "f")],
+            [patterns.agent, endpoints.agent("t", "ag", "a")],
+            [patterns.mcp, endpoints.mcp("t")],
+        ];
+
+        for (const [pattern, path] of mapped) {
+            const expected = pattern.split("/").slice(1);
+            expect(path.split("/").slice(1)).toHaveLength(expected.length);
+            // Same shape: each `:param` is one segment, the literals are identical
+            for (const [index, part] of expected.entries()) {
+                if (part.startsWith(":")) continue;
+                expect(path.split("/").slice(1)[index]).toBe(part);
+            }
+        }
+    });
+
+    it("encodes a segment, so an id with a slash cannot forge a path", () => {
+        expect(segment("a/b c")).toBe("a%2Fb%20c");
+        expect(endpoints.file("v1", "photos", "../etc/passwd")).toBe("/api/v1/files/photos/..%2Fetc%2Fpasswd");
+    });
+});
+
+describe("endpoints — reserved families", () => {
+    it("recognises what a tenant route must not shadow", () => {
+        for (const family of FAMILIES) expect(isReservedFamily(family)).toBe(true);
+        expect(isReservedFamily("orders")).toBe(false);
+        expect(isReservedFamily("Collections")).toBe(false);
+    });
+});

package/tests/fixtures/agent-tenant/agents/support.agent.ts

@@ -0,0 +1,9 @@
+import { define } from "../../../../index";
+
+/** A second agent of the fixture tenant — no tool, no memory. */
+export default define.Agent({
+    id: "support",
+    description: "Answers support questions.",
+    instructions: "You are a support agent.",
+    provider: { model: "claude-test", compatible: "anthropic", apiKey: "fixture-key" },
+});

package/tests/fixtures/agent-tenant/agents/weather.agent.ts

@@ -0,0 +1,21 @@
+import { define, v } from "../../../../index";
+
+/**
+ * Loader fixture — `{tenant.dir}/agents/**\/*.agent.ts`.
+ * No call is ever made against the provider here: only the loader is exercised.
+ */
+export default define.Agent({
+    id: "weather",
+    name: "Weather Agent",
+    description: "Answers weather questions with a tool call",
+    instructions: "You are a concise weather assistant.",
+    provider: { model: "test-model", compatible: "openai", apiKey: "fixture-key" },
+    tools: {
+        forecast: define.Tool({
+            id: "forecast",
+            description: "Current weather for a city",
+            inputSchema: v.object({ city: v.string().required() }),
+            execute: async ({ city }) => ({ city, celsius: 21 }),
+        }),
+    },
+});

package/tests/fixtures/agents-api/agents/assistant.agent.ts

@@ -0,0 +1,46 @@
+import { define, v, agents } from "../../../../index";
+
+/**
+ * HTTP-API fixture — exposed through `POST /api/:tenant_id/agents/:agent/:action`.
+ *
+ * The provider endpoint comes from the environment so the test can point it at
+ * its own fake provider (the port is chosen by the OS).
+ */
+export default define.Agent({
+    id: "assistant",
+    name: "Assistant",
+    description: "Fixture agent for the HTTP API",
+    instructions: "You are a fixture agent.",
+    provider: {
+        model: "test-model",
+        compatible: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+    maxSteps: 3,
+    memory: new agents.memory.InMemory(),
+    tools: {
+        echo: define.Tool({
+            id: "echo",
+            description: "Echoes the given text",
+            inputSchema: v.object({ text: v.string().required() }),
+            execute: async ({ text }) => ({ echoed: text }),
+        }),
+    },
+    api: {
+        access: {
+            // public metadata — no token needed
+            info: true,
+            generate: (ctx) => !!ctx.token.value,
+            stream: (ctx) => !!ctx.token.value,
+            object: (ctx) => !!ctx.token.value,
+            history: (ctx) => !!ctx.token.value,
+            threads: (ctx) => !!ctx.token.value,
+            clear: (ctx) => !!ctx.token.value,
+        },
+        object: {
+            schema: v.object({ city: v.string().required(), celsius: v.number().required() }),
+        },
+    },
+});

package/tests/fixtures/agents-api/agents/plain.agent.ts

@@ -0,0 +1,23 @@
+import { define } from "../../../../index";
+
+/**
+ * Public agent — `generate` is allowed without a token. Declares no memory and
+ * no `api.object`, to exercise `AGENT_NO_MEMORY` / `AGENT_NO_OBJECT_SCHEMA`.
+ */
+export default define.Agent({
+    id: "plain",
+    description: "A plain agent with no memory and no object schema.",
+    instructions: "You are a plain agent.",
+    provider: {
+        model: "test-model",
+        compatible: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+    api: {
+        // public on purpose: `object` also needs a rule so the *missing schema*
+        // error can be exercised (otherwise the action is denied first)
+        access: { generate: true, object: true },
+    },
+});

package/tests/fixtures/agents-api/agents/private.agent.ts

@@ -0,0 +1,15 @@
+import { define } from "../../../../index";
+
+/** Declares no `api` at all — every action must be denied (secure by default). */
+export default define.Agent({
+    id: "private",
+    description: "Not exposed over HTTP.",
+    instructions: "You are a private agent.",
+    provider: {
+        model: "test-model",
+        compatible: "openai",
+        apiKey: "test-key",
+        baseUrl: Bun.env.AGENT_API_TEST_URL ?? "http://127.0.0.1:1",
+        options: { retries: 0 },
+    },
+});

package/tests/fixtures/agents-api/collections/notes.model.ts

@@ -0,0 +1,26 @@
+import { define } from "../../../../index";
+
+/**
+ * A collection whose hook uses `agents` — proving the LLM registry is injected
+ * into the hook context exactly like `rest` and `io`.
+ *
+ * The observation is published on `globalThis` (the test reads it back): a hook
+ * must not stuff arbitrary keys into `meta.data`, the collection schema rejects
+ * them (`allowUnknown: false`).
+ */
+export default define.Collection({
+    slug: "notes",
+    fields: [{ name: "title", type: "string" }],
+    hooks: {
+        beforeOperation: define.Hook(async ({ agents, api, rest, meta }) => {
+            if (meta.action !== "insertOne") return;
+            (globalThis as any).__agentsHookProbe = {
+                ids: agents.ids().sort(),
+                bound: agents.get("assistant")?.getRest() === rest,
+                // The in-process facade, bound to the same `rest`
+                slug: api.collection("notes").getSlug(),
+                notes: await api.collection("notes").countDocuments(),
+            };
+        }),
+    },
+});

package/tests/fixtures/agents-api/routes/probe.route.ts

@@ -0,0 +1,21 @@
+import { define } from "../../../../index";
+
+/** A route reading the LLM registry **and the in-process facade** from its context. */
+export default define.Route({
+    method: "GET",
+    path: "/probe",
+    handler: async ({ agents, api, rest }) => Response.json({
+        agents: agents.ids().sort(),
+        hasAssistant: !!agents.get("assistant"),
+        // `api` groups the same calls as `rest` — bound and namespaced
+        slug: api.collection("notes").getSlug(),
+        notes: await api.collection("notes").countDocuments(),
+        sameAsRest: (await api.collection("notes").find()) .length === (await rest.find("notes")).length,
+        agentBound: api.agent("assistant")?.getRest() === rest,
+        unknownAgent: api.agent("ghost"),
+        vars: typeof api.vars.get,
+        serviceRun: typeof api.service("probe").run,
+        serviceCall: await api.service("probe").run("echo", { from: "route" }),
+        fileUrl: api.files.url("invoices", "f1.pdf", { width: 800 }),
+    }),
+});

package/tests/fixtures/agents-api/services/probe.service.ts

@@ -0,0 +1,19 @@
+import { define } from "../../../../index";
+
+/** A service action reading the LLM registry and the facade from its context. */
+export default define.Service({
+    name: "probe",
+    enabled: true,
+    actions: {
+        check: async ({ agents, api, rest }) => ({
+            agents: agents.ids().sort(),
+            hasAssistant: !!agents.get("assistant"),
+            bound: agents.get("assistant")?.getRest() === rest,
+            tenant: rest.tenant_id,
+            // `api.service(name).run` is the grouped `rest.runService`
+            nested: await api.service("probe").run("echo", { from: "api" }),
+            varType: typeof api.vars.get,
+        }),
+        echo: async ({ data }) => data,
+    },
+});

package/tests/fixtures/attachment/data.csv

@@ -0,0 +1,2 @@
+ref,total
+A-1,99