@anteros/core 0.0.41 → 0.0.44

package/tests/fixtures/workflow-engine/workflows/simple.workflow.ts

@@ -0,0 +1,19 @@
+// Test fixture — one step, always succeeds. Shared in-process state:
+// `globalThis.__wfEngine = { log: string[], attempts: Record<string, number> }`
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "simple",
+    name: "Simple",
+    version: 1,
+    steps: [
+        {
+            id: "one",
+            exec: async ({ data }: any) => {
+                state.log.push("simple:one");
+                return { echo: data?.echo ?? null };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/slow.workflow.ts

@@ -0,0 +1,23 @@
+// Test fixture — three steps, the middle one slow: lets a test pause or cancel
+// the run while it is executing (and check that the last step never runs).
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "slow",
+    name: "Slow",
+    version: 1,
+    steps: [
+        { id: "fast", exec: async () => { state.log.push("slow:fast"); return { fast: true }; } },
+        {
+            id: "slow",
+            exec: async ({ data }: any) => {
+                state.log.push("slow:slow:start");
+                await new Promise((resolve) => setTimeout(resolve, data?.ms ?? 300));
+                state.log.push("slow:slow:end");
+                return { slow: true };
+            },
+        },
+        { id: "last", exec: async () => { state.log.push("slow:last"); return { last: true }; } },
+    ],
+};

package/tests/fixtures/workflow-engine/workflows/versioned.workflow.ts

@@ -0,0 +1,19 @@
+// Test fixture — used to check the resume version guard: the test mutates
+// `version` on the registered definition after a run has started.
+const state = ((globalThis as any).__wfEngine ??= { log: [], attempts: {} });
+
+export default {
+    _isWorkflow_: true,
+    id: "versioned",
+    name: "Versioned",
+    version: 1,
+    steps: [
+        {
+            id: "v",
+            exec: async () => {
+                state.log.push("versioned:v");
+                return { ok: true };
+            },
+        },
+    ],
+};

package/tests/fixtures/workflow-tenant/workflows/broken.workflow.ts

@@ -0,0 +1,3 @@
+// Test fixture — throws while being imported: the loader must isolate the
+// failure and keep loading the other workflows of the tenant.
+throw new Error("boom — broken workflow fixture");

package/tests/fixtures/workflow-tenant/workflows/disabled.workflow.ts

@@ -0,0 +1,8 @@
+// Test fixture — `enabled: false` must not be registered.
+export default {
+    _isWorkflow_: true,
+    enabled: false,
+    id: "nightly",
+    name: "Nightly",
+    steps: [{ id: "run", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/invoice.workflow.ts

@@ -0,0 +1,21 @@
+// Test fixture — a second valid workflow, with a different `version` so tests
+// can assert on a definition that is not the duplicated `order`.
+export default {
+    _isWorkflow_: true,
+    id: "invoice",
+    name: "Invoices",
+    version: 3,
+    context: {
+        companyId: { type: "string", index: true },   // → index context.companyId_1
+        processedAt: { type: "date" },                 // validated + coerced to a Date
+    },
+    // Beyond `context.index`: compound, unique, sparse, named
+    indexes: [
+        { key: { "context.companyId": 1, status: 1 } },
+        { key: { "context.batchId": 1 }, unique: true, sparse: true, name: "uniq_batch" },
+    ],
+    steps: [
+        { id: "generate", exec: async ({ data }: any) => ({ generated: data?.ref ?? null }) },
+        { id: "send", exec: async () => ({ sent: true }) },
+    ],
+};

package/tests/fixtures/workflow-tenant/workflows/no-id.workflow.ts

@@ -0,0 +1,7 @@
+// Test fixture — no `id`: must be ignored (with a warning), not registered
+// under a bogus `undefined` key.
+export default {
+    _isWorkflow_: true,
+    name: "Anonymous",
+    steps: [{ id: "run", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/order-duplicate.workflow.ts

@@ -0,0 +1,13 @@
+// Test fixture — same `id` as order.workflow.ts: the duplicate must be reported
+// and only one definition kept (never two entries, never a crash). The context
+// declaration is identical on purpose: whichever file wins, the indexes exist.
+export default {
+    _isWorkflow_: true,
+    id: "order",
+    name: "Orders (duplicate definition)",
+    context: {
+        customerId: { type: "string", index: true },
+        total: { type: "number", index: -1 },
+    },
+    steps: [{ id: "charge", exec: async () => ({ charged: false }) }],
+};

package/tests/fixtures/workflow-tenant/workflows/order.workflow.ts

@@ -0,0 +1,17 @@
+// Test fixture — a valid, enabled workflow with declared context fields.
+export default {
+    _isWorkflow_: true,
+    enabled: true,
+    id: "order",
+    name: "Orders",
+    version: 2,
+    context: {
+        customerId: { type: "string", index: true },   // → index context.customerId_1
+        total: { type: "number", index: -1 },          // → index context.total_-1
+        note: { type: "string" },                      // not indexed
+    },
+    steps: [
+        { id: "charge", exec: async ({ data }: any) => ({ charged: data?.ref ?? null }) },
+        { id: "notify", exec: async () => ({ notified: true }) },
+    ],
+};

package/tests/hono.test.ts

@@ -182,16 +182,19 @@ describe("rate limiting (in-memory)", () => {
     it("login limiter uses a distinct counter (not blocked by global)", async () => {
         cfg.server.rateLimit = { enabled: true, windowMs: 60_000, max: 100, login: { max: 2 } };
         const app = createApp();
-        app.post("/api/x/login", (c) => c.json({ ok: true }));
         app.get("/echo", (c) => c.json({ ok: true }));
         const server = Bun.serve({ port: 0, fetch: app.fetch });
         const url = `${base(server)}`;
 
+        // The login limiter has its own bucket: the third call is refused even though
+        // the global limit (100) is nowhere near. What the framework answers before
+        // that (unknown tenant here) is not the point.
         const statuses: number[] = [];
         for (let i = 0; i < 3; i++) {
-            statuses.push((await fetch(`${url}/api/x/login`, { method: "POST" })).status);
+            statuses.push((await fetch(`${url}/api/x/collections/users/login`, { method: "POST" })).status);
         }
-        expect(statuses).toEqual([200, 200, 429]);
+        expect(statuses.slice(0, 2).some((status) => status === 429)).toBe(false);
+        expect(statuses[2]).toBe(429);
 
         // same IP on a normal route → still allowed (distinct key)
         expect((await fetch(`${url}/echo`)).status).toBe(200);

package/tests/locks.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import os from "node:os";
+import { useRest } from "../database/rest";
+import { formatConfig } from "../server/config";
+import { syncTenants } from "../database/tenant";
+
+const TENANT = "locks-test";
+const DB = "mongodb://localhost:27017/_LOCKS_TEST";
+
+let rest: InstanceType<typeof useRest>;
+
+/** Write a lock document as if another process had taken it */
+async function seedLock(name: string, opts: { pid?: number; hostname?: string; expiresAt: number }) {
+    await rest.db.collection("_locks_").insertOne({
+        _id: `${TENANT}:${name}` as any,
+        tid: TENANT,
+        name,
+        acquiredAt: Date.now() - 1000,
+        expiresAt: opts.expiresAt,
+        ...(opts.pid !== undefined ? { pid: opts.pid } : {}),
+        ...(opts.hostname !== undefined ? { hostname: opts.hostname } : {}),
+    } as any);
+}
+
+const lockDoc = (name: string) => rest.db.collection("_locks_").findOne({ _id: `${TENANT}:${name}` as any });
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: "src", database: { uri: DB } }],
+    });
+    await syncTenants();
+    rest = new useRest({ tenant_id: TENANT, internal: true });
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("_locks_").drop(); } catch (_) {}
+    try { await rest.db.collection("_workflows_").drop(); } catch (_) {}
+    try { await rest.db.collection("_replication_").drop(); } catch (_) {}
+});
+
+describe("distributed lock", () => {
+    it("records the owning pid and hostname", async () => {
+        await rest.lock("l-pid");
+        const doc: any = await lockDoc("l-pid");
+        expect(doc.pid).toBe(process.pid);
+        expect(doc.hostname).toBe(os.hostname());
+        await rest.unlock("l-pid");
+    });
+
+    it("refuses a second acquisition from the same process (its own pid is not stale)", async () => {
+        await rest.lock("l-self");
+        await expect(rest.lock("l-self")).rejects.toThrow(/already held/);
+        await rest.unlock("l-self");
+    });
+
+    it("takes over a lock whose local process is gone, without waiting for the TTL", async () => {
+        // A process that has exited: its pid no longer exists
+        const dead = Bun.spawn(["true"]);
+        const deadPid = dead.pid;
+        await dead.exited;
+
+        await seedLock("l-dead", { pid: deadPid, hostname: os.hostname(), expiresAt: Date.now() + 60_000 });
+
+        await rest.lock("l-dead");
+        const doc: any = await lockDoc("l-dead");
+        expect(doc.pid).toBe(process.pid);
+        await rest.unlock("l-dead");
+    });
+
+    it("waits for a lock whose local process is still alive", async () => {
+        const alive = Bun.spawn(["sleep", "5"]);
+        try {
+            await seedLock("l-alive", { pid: alive.pid, hostname: os.hostname(), expiresAt: Date.now() + 60_000 });
+
+            await expect(rest.lock("l-alive")).rejects.toThrow(/already held/);
+
+            // …and the lock is taken over as soon as that process is gone
+            alive.kill();
+            await alive.exited;
+
+            await rest.lock("l-alive");
+            const doc: any = await lockDoc("l-alive");
+            expect(doc.pid).toBe(process.pid);
+            await rest.unlock("l-alive");
+        } finally {
+            try { alive.kill(); } catch (_) {}
+        }
+    }, 20_000);
+
+    it("takes over an expired lock", async () => {
+        await seedLock("l-expired", { pid: 999_999, hostname: "another-host", expiresAt: Date.now() - 1000 });
+
+        await rest.lock("l-expired");
+        const doc: any = await lockDoc("l-expired");
+        expect(doc.pid).toBe(process.pid);
+        await rest.unlock("l-expired");
+    });
+
+    it("never releases a lock owned by another process", async () => {
+        await seedLock("l-other", { pid: 4242, hostname: "another-host", expiresAt: Date.now() + 60_000 });
+
+        await rest.unlock("l-other"); // not ours
+        expect(await lockDoc("l-other")).not.toBeNull();
+
+        // Ours is released
+        await rest.lock("l-ours");
+        await rest.unlock("l-ours");
+        expect(await lockDoc("l-ours")).toBeNull();
+
+        await rest.db.collection("_locks_").deleteOne({ name: "l-other" });
+    });
+
+    it("only takes over a remote lock when it expired (a foreign pid cannot be probed)", async () => {
+        await seedLock("l-remote", { pid: 1, hostname: "some-other-host", expiresAt: Date.now() + 60_000 });
+
+        await expect(rest.lock("l-remote")).rejects.toThrow(/already held/);
+        await rest.db.collection("_locks_").deleteOne({ name: "l-remote" });
+    });
+});

package/tests/mcp.test.ts

@@ -62,7 +62,7 @@ describe("syncMcpTools", () => {
     });
 });
 
-describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
+describe("MCP protocol (GET/POST /api/:tenant_id/mcp)", () => {
     it("serves tools/list and tools/call over JSON-RPC", async () => {
         cfg.tenants = [{ id: TENANT, dir: TENANT_DIR, database: { uri: "mongodb://localhost:27017/none" } }];
         await syncMcpTools();
@@ -72,7 +72,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         const url = server.url.href.replace(/\/$/, "");
 
         // 1. tools/list
-        const listRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const listRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }),
@@ -84,7 +84,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(tools.some((t: any) => t.name === "badge")).toBe(true);
 
         // 1b. resources/list — static resources
-        const resListRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const resListRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 9, method: "resources/list", params: {} }),
@@ -94,7 +94,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(resources.some((r: any) => r.uri === "orders://summary")).toBe(true);
 
         // 1c. resources/templates/list
-        const tmplRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const tmplRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 10, method: "resources/templates/list", params: {} }),
@@ -104,7 +104,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(templates.some((t: any) => t.uriTemplate === "users://{id}")).toBe(true);
 
         // 1d. resources/read — static URI
-        const readRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 11, method: "resources/read", params: { uri: "orders://summary" } }),
@@ -114,7 +114,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readText).toContain("\"total\":42");
 
         // 1e. resources/read — template URI with params
-        const readTplRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readTplRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 12, method: "resources/read", params: { uri: "users://abc123" } }),
@@ -123,7 +123,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readTpl?.result?.contents?.[0]?.text ?? "").toContain("\"id\":\"abc123\"");
 
         // 1f. resources/read — unknown URI → error
-        const readBadRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const readBadRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 13, method: "resources/read", params: { uri: "nope://x" } }),
@@ -132,7 +132,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(readBad?.error).toBeDefined();
 
         // 2. tools/call (valid args + Joi defaults)
-        const callRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const callRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -148,7 +148,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(block.text ?? "").toContain("\"times\":1");
 
         // 2b. protocol content blocks pass through unchanged (image block)
-        const badgeRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const badgeRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -161,7 +161,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(badge?.result?.content?.[0]?.mimeType).toBe("image/png");
 
         // 2b. invalid args → isError (Joi validation)
-        const badRes = await fetch(`${url}/mcp/${TENANT}`, {
+        const badRes = await fetch(`${url}/api/${TENANT}/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({
@@ -174,7 +174,7 @@ describe("MCP protocol (GET/POST /mcp/:tenant_id)", () => {
         expect(bad?.result?.content?.[0]?.text ?? "").toContain("Invalid arguments");
 
         // 3. unknown tenant → 404
-        const notFound = await fetch(`${url}/mcp/ghost`, {
+        const notFound = await fetch(`${url}/api/ghost/mcp`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ jsonrpc: "2.0", id: 4, method: "tools/list", params: {} }),

package/tests/messages.test.ts

@@ -0,0 +1,258 @@
+import { describe, it, expect, afterAll } from "bun:test";
+import { normalizeMessages } from "../lib/messages";
+import { MAX_FILE_BYTES } from "../lib/attachment";
+
+/** A tiny local file server — the `file: { url }` path downloads through `fetch`. */
+const servers: Array<ReturnType<typeof Bun.serve>> = [];
+function serve(body: Uint8Array | string, contentType = "application/pdf") {
+    const server = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: () => new Response(body as any, { headers: { "Content-Type": contentType } }),
+    });
+    servers.push(server);
+    return `http://127.0.0.1:${server.port}/report.pdf`;
+}
+
+afterAll(() => {
+    for (const server of servers) server.stop(true);
+});
+
+const first = async (input: any) => (await normalizeMessages(input))[0] as any;
+
+describe("normalizeMessages — the shapes it accepts", () => {
+    it("turns a string into one user turn", async () => {
+        expect(await normalizeMessages("hi")).toEqual([{ role: "user", content: "hi" }]);
+    });
+
+    it("accepts a single message — with or without an array", async () => {
+        const message = { role: "user", content: "hi" } as const;
+        expect(await normalizeMessages(message)).toEqual([{ role: "user", content: "hi" }]);
+        expect(await normalizeMessages([message])).toEqual([{ role: "user", content: "hi" }]);
+    });
+
+    it("keeps a whole conversation in order", async () => {
+        const messages = await normalizeMessages([
+            { role: "user", content: "hi" },
+            { role: "assistant", content: "hello" },
+            { role: "user", content: "and?" },
+        ]);
+        expect(messages.map((message) => message.role)).toEqual(["user", "assistant", "user"]);
+        expect((messages[1] as any).content).toBe("hello");
+    });
+
+    it("keeps only the canonical fields — a stray key never reaches the wire", async () => {
+        const [message] = await normalizeMessages([{ role: "user", content: "hi", threadId: "t", bogus: 1 } as any]);
+        expect(message).toEqual({ role: "user", content: "hi" });
+    });
+});
+
+describe("normalizeMessages — content parts", () => {
+    it("keeps text, image and file parts, url or base64", async () => {
+        const [message] = await normalizeMessages([{
+            role: "user",
+            content: [
+                { type: "text", text: "look" },
+                { type: "image", url: "https://example.com/a.png" },
+                { type: "image", data: "AAAA", mimeType: "image/png" },
+                { type: "file", name: "a.pdf", data: "BBBB", mimeType: "application/pdf" },
+            ],
+        }] as any);
+
+        expect((message as any).content).toEqual([
+            { type: "text", text: "look" },
+            { type: "image", url: "https://example.com/a.png" },
+            { type: "image", mimeType: "image/png", data: "AAAA" },
+            { type: "file", name: "a.pdf", mimeType: "application/pdf", data: "BBBB" },
+        ]);
+    });
+
+    it("joins a system message written as parts", async () => {
+        const [message] = await normalizeMessages([
+            { role: "system", content: [{ type: "text", text: "a" }, { type: "text", text: "b" }] },
+        ] as any);
+        expect(message).toEqual({ role: "system", content: "a\nb" });
+    });
+
+    it("downloads a remote file and inlines it as base64", async () => {
+        const url = serve("%PDF-1.7 payload");
+        const [message] = await normalizeMessages([
+            { role: "user", content: [{ type: "file", url, name: "invoice.pdf" }] },
+        ] as any);
+
+        const part: any = (message as any).content[0];
+        expect(part.type).toBe("file");
+        expect(part.name).toBe("invoice.pdf");
+        // The URL is gone — the payload travels as base64, which every provider takes
+        expect(part.url).toBeUndefined();
+        expect(Buffer.from(part.data, "base64").toString()).toBe("%PDF-1.7 payload");
+    });
+
+    it("leaves a remote image as a URL — the provider fetches it", async () => {
+        const message: any = await first([{ role: "user", content: [{ type: "image", url: "https://example.com/a.png" }] }]);
+        expect(message.content[0].url).toBe("https://example.com/a.png");
+        expect(message.content[0].data).toBeUndefined();
+    });
+
+    it("refuses a part without a payload, an unknown address, or an unsupported scheme", async () => {
+        const cases = [
+            [{ type: "image" }],
+            [{ type: "file", name: "a.pdf" }],
+            [{ type: "image", url: "ftp://example.com/a.png" }],
+            [{ type: "image", url: "./local.png" }],
+        ];
+        for (const content of cases) {
+            const error: any = await normalizeMessages([{ role: "user", content }] as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses a file that is too large", async () => {
+        const url = serve(new Uint8Array(MAX_FILE_BYTES + 1));
+        const error: any = await normalizeMessages([
+            { role: "user", content: [{ type: "file", url, name: "huge.pdf" }] },
+        ] as any).catch((err) => err);
+        expect(error.code).toBe("AGENT_FILE_TOO_LARGE");
+    });
+});
+
+describe("normalizeMessages — tool parts", () => {
+    it("hoists `tool-call` parts onto the assistant message", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "tool-call", id: "call_1", name: "forecast", arguments: { city: "Paris" } }],
+        }] as any);
+
+        expect(message).toEqual({
+            role: "assistant",
+            content: null,
+            toolCalls: [{ id: "call_1", name: "forecast", args: { city: "Paris" } }],
+        });
+    });
+
+    it("merges inline calls with the ones declared as `toolCalls`", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "text", text: "let me check" }, { type: "tool-call", id: "b", name: "two" }],
+            toolCalls: [{ id: "a", name: "one", args: {} }],
+        }] as any) as any[];
+
+        expect(message.content).toBe("let me check");
+        expect(message.toolCalls.map((call: any) => call.id)).toEqual(["a", "b"]);
+    });
+
+    it("keeps a raw `argsText` when the caller had one", async () => {
+        const [message] = await normalizeMessages([{
+            role: "assistant",
+            content: [{ type: "tool-call", id: "c", name: "f", argsText: '{"city":"Lyon"}', arguments: { city: "Lyon" } }],
+        }] as any) as any[];
+        expect(message.toolCalls[0]).toEqual({ id: "c", name: "f", args: { city: "Lyon" }, argsText: '{"city":"Lyon"}' });
+    });
+
+    it("turns a `tool-result` part into the `tool` message it means", async () => {
+        const messages = await normalizeMessages([{
+            role: "user",
+            content: [
+                { type: "text", text: "and?" },
+                { type: "tool-result", id: "call_1", name: "forecast", result: { celsius: 21 } },
+                { type: "tool-result", id: "call_2", name: "boom", error: "timeout" },
+            ],
+        }] as any) as any[];
+
+        expect(messages.map((message) => message.role)).toEqual(["user", "tool", "tool"]);
+        expect(messages[0].content).toEqual([{ type: "text", text: "and?" }]);
+        expect(messages[1]).toEqual({
+            role: "tool", toolCallId: "call_1", name: "forecast", content: '{"celsius":21}',
+        });
+        expect(messages[2]).toEqual({
+            role: "tool", toolCallId: "call_2", name: "boom", content: "Error: timeout", isError: true,
+        });
+    });
+
+    it("expands a `tool` message carrying several results", async () => {
+        const messages = await normalizeMessages([{
+            role: "tool",
+            content: [
+                { type: "tool-result", id: "a", result: "one" },
+                { type: "tool-result", id: "b", result: "two" },
+            ],
+        }] as any) as any[];
+
+        expect(messages).toEqual([
+            { role: "tool", toolCallId: "a", name: "tool", content: "one" },
+            { role: "tool", toolCallId: "b", name: "tool", content: "two" },
+        ]);
+    });
+
+    it("keeps a `tool` message written the classic way", async () => {
+        const [message] = await normalizeMessages([
+            { role: "tool", toolCallId: "call_1", name: "forecast", content: "21°C" },
+        ] as any);
+        expect(message).toEqual({ role: "tool", toolCallId: "call_1", name: "forecast", content: "21°C" });
+    });
+});
+
+describe("normalizeMessages — what it refuses", () => {
+    it("refuses an unknown role and a message without one", async () => {
+        for (const input of [[{ role: "robot", content: "hi" }], [{ content: "hi" }], [null]]) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+            expect(error.status).toBe(400);
+        }
+    });
+
+    it("refuses a part the role cannot carry", async () => {
+        const cases: any[] = [
+            [{ role: "user", content: [{ type: "tool-call", id: "a", name: "f" }] }],
+            [{ role: "assistant", content: [{ type: "image", url: "https://example.com/a.png" }] }],
+            [{ role: "system", content: [{ type: "image", url: "https://example.com/a.png" }] }],
+            [{ role: "tool", content: [{ type: "text", text: "no" }] }],
+            [{ role: "tool", content: "orphan" }], // no `toolCallId`
+            [{ role: "user", content: [{ type: "tool-result" }] }], // no id
+        ];
+        for (const input of cases) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses a message without content", async () => {
+        for (const role of ["user", "system", "tool"]) {
+            const error: any = await normalizeMessages([{ role }] as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+    });
+
+    it("refuses an empty content array rather than sending an empty turn", async () => {
+        for (const input of [
+            [{ role: "user", content: [] }],
+            [{ role: "tool", content: [] }],
+            [{ role: "developer", content: [] }],
+        ]) {
+            const error: any = await normalizeMessages(input as any).catch((err) => err);
+            expect(error.code).toBe("INVALID_INPUT");
+        }
+
+        // An assistant turn with no text is legitimate — a tool call carries the turn
+        expect(await normalizeMessages([{ role: "assistant", content: [] }] as any))
+            .toEqual([{ role: "assistant", content: null }]);
+    });
+});
+
+describe("normalizeMessages — developer role and names", () => {
+    it("keeps the `developer` role and a message name", async () => {
+        const messages = await normalizeMessages([
+            { role: "developer", content: "answer concisely", name: "policy" },
+            { role: "user", content: "hi", name: "ada" },
+        ] as any);
+
+        expect(messages[0]).toEqual({ role: "developer", content: "answer concisely", name: "policy" });
+        expect(messages[1]).toEqual({ role: "user", content: "hi", name: "ada" });
+    });
+
+    it("keeps the raw thinking blocks of a replayed assistant turn", async () => {
+        const thinking = [{ type: "thinking", thinking: "…", signature: "sig" }];
+        const [message] = await normalizeMessages([{ role: "assistant", content: "done", thinking }] as any) as any[];
+        expect(message.thinking).toEqual(thinking);
+    });
+});