@anteros/core 0.0.42 → 0.0.44

package/tests/agent-mcp.test.ts

@@ -0,0 +1,116 @@
+/**
+ * The MCP **client** — an agent consuming a remote server's tools.
+ *
+ * The endpoint under test is the framework's own (`/api/:tenant/mcp`, served by
+ * `@hono/mcp`): the SDK client and our server are two independent implementations of
+ * the protocol, which is exactly what makes the round trip worth testing end to end —
+ * list, call, and back into the conversation as if the tool were local.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { Agent, define, v } from "../index";
+import { cfg, formatConfig } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { syncMcpTools } from "../lib/mcp";
+import { closeMcpClients } from "../lib/mcpClient";
+import { createApp } from "../server/hono";
+import { at, fakeProvider, openaiText, openaiTool, request, type Fake } from "./fixtures/fake-provider";
+
+const TENANT = "mcp-client";
+const DIR = "packages/core/tests/fixtures/mcp-tenant";
+
+let server: any;
+let mcpUrl: string;
+const servers: Fake[] = [];
+
+const track = (fake: Fake): Fake => (servers.push(fake), fake);
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: DIR, database: { uri: "mongodb://localhost:27017/none" } }],
+    });
+    await syncTenants();
+    await syncMcpTools();
+
+    server = Bun.serve({ port: 0, fetch: createApp().fetch });
+    mcpUrl = `${server.url.href.replace(/\/$/, "")}/api/${TENANT}/mcp`;
+});
+
+afterAll(async () => {
+    for (const fake of servers) fake.stop();
+    await closeMcpClients();
+    try { server?.stop(true); } catch (_) {}
+    cfg.agents = [];
+});
+
+function makeAgent(provider: Fake, overrides: Record<string, any> = {}) {
+    return new Agent({
+        id: "test",
+        description: "A test agent.",
+        instructions: "You are a test agent.",
+        provider: { model: "test-model", apiKey: "test-key", baseUrl: provider.url, options: { retries: 0 } },
+        mcp: [mcpUrl],
+        ...overrides,
+    } as any);
+}
+
+describe("agent mcp — a remote server's tools", () => {
+    it("lists them as tools, calls one, and feeds the result back", async () => {
+        const provider = track(fakeProvider((_body, _req, hits) =>
+            hits === 1 ? openaiTool("echo", { msg: "hello mcp", times: 1 }) : openaiText("done")));
+        const agent = makeAgent(provider);
+
+        const result = await agent.generate("echo something");
+
+        // The remote tools are offered like any other
+        const names = request(provider, 0).body.tools.map((tool: any) => tool.function.name);
+        expect(names).toContain("echo");
+        expect(names).toContain("badge");
+
+        // …and the call really crossed the wire: the answer is the server's
+        const entry = at(result.toolResults, 0);
+        expect(entry.error).toBeUndefined();
+        expect(entry.result.content[0].text).toContain("hello mcp");
+        // What the model saw is the flattened text, not the protocol envelope
+        const toolMessage = result.messages.find((message) => message.role === "tool");
+        expect(toolMessage?.content).toContain("hello mcp");
+        expect(result.text).toBe("done");
+    });
+
+    it("lets a declared tool win over a remote one of the same name", async () => {
+        const provider = track(fakeProvider(() => openaiText("done")));
+        const local = define.Tool({
+            id: "echo",
+            description: "The tenant's own echo.",
+            inputSchema: v.object({}),
+            execute: async () => "local",
+        });
+        const agent = makeAgent(provider, { tools: { echo: local } });
+
+        await agent.generate("hi");
+
+        const offered = request(provider, 0).body.tools.filter((tool: any) => tool.function.name === "echo");
+        expect(offered).toHaveLength(1);
+        expect(offered[0].function.description).toBe("The tenant's own echo.");
+    });
+
+    it("contacts nothing with `tools: false`", async () => {
+        const provider = track(fakeProvider(() => openaiText("direct")));
+        const agent = makeAgent(provider);
+
+        await agent.generate("hi", { tools: false });
+
+        expect(request(provider, 0).body.tools).toBeUndefined();
+    });
+
+    it("runs anyway when the server is unreachable", async () => {
+        const provider = track(fakeProvider(() => openaiText("still here")));
+        const agent = makeAgent(provider, { mcp: ["http://127.0.0.1:9/mcp"] });
+
+        const result = await agent.generate("hi");
+
+        // A remote that is down costs its tools, not the run
+        expect(result.text).toBe("still here");
+        expect(request(provider, 0).body.tools).toBeUndefined();
+    }, 20_000);
+});

package/tests/agent-memory.test.ts

@@ -336,7 +336,7 @@ describe("agent memory — end to end", () => {
             id: "memo",
             description: "A test agent.",
             instructions: "You are a test agent.",
-            provider: { model: "test-model", apiKey: "test-key", compatible: "openai", baseUrl: provider.url, options: { retries: 0 } },
+            provider: { model: "test-model", apiKey: "test-key", protocol: "openai", baseUrl: provider.url, options: { retries: 0 } },
             memory,
         } as any);
         agent.setRest(rest);
@@ -371,7 +371,7 @@ describe("agent memory — end to end", () => {
             id: "shorthand",
             description: "A test agent.",
             instructions: "You are a test agent.",
-            provider: { model: "test-model", apiKey: "test-key", compatible: "openai", baseUrl: provider.url, options: { retries: 0 } },
+            provider: { model: "test-model", apiKey: "test-key", protocol: "openai", baseUrl: provider.url, options: { retries: 0 } },
             memory: new MongoAgentMemory({ collection: MEMORY }),
         } as any);
         agent.setRest(rest);
@@ -397,7 +397,7 @@ describe("agent memory — end to end", () => {
             id: "preview",
             description: "A test agent.",
             instructions: "You are a test agent.",
-            provider: { model: "test-model", apiKey: "test-key", compatible: "openai", baseUrl: provider.url, options: { retries: 0 } },
+            provider: { model: "test-model", apiKey: "test-key", protocol: "openai", baseUrl: provider.url, options: { retries: 0 } },
             memory: new MongoAgentMemory({ collection: MEMORY }),
         } as any);
         agent.setRest(rest);
@@ -416,7 +416,7 @@ describe("agent memory — end to end", () => {
             id: "plain",
             description: "x",
             instructions: "x",
-            provider: { model: "m", compatible: "openai", apiKey: "k" },
+            provider: { model: "m", protocol: "openai", apiKey: "k" },
         } as any);
         expect(await agent.listThreads()).toEqual([]);
 
@@ -424,7 +424,7 @@ describe("agent memory — end to end", () => {
             id: "minimal",
             description: "x",
             instructions: "x",
-            provider: { model: "m", compatible: "openai", apiKey: "k" },
+            provider: { model: "m", protocol: "openai", apiKey: "k" },
             // A custom store only has to implement get / save / clear
             memory: { get: () => [], save: () => { }, clear: () => { } },
         } as any);
@@ -599,7 +599,7 @@ describe("agents.memory.Redis", () => {
             id: "redis-agent",
             description: "A test agent.",
             instructions: "You are a test agent.",
-            provider: { model: "test-model", apiKey: "test-key", compatible: "openai", baseUrl: provider.url, options: { retries: 0 } },
+            provider: { model: "test-model", apiKey: "test-key", protocol: "openai", baseUrl: provider.url, options: { retries: 0 } },
             memory: new RedisAgentMemory({ client }),
         } as any);
         agent._tenant_ = "v1";

package/tests/agent-provider.test.ts

@@ -0,0 +1,288 @@
+/**
+ * What an agent puts **on the wire** for the two things the provider can enforce
+ * better than a prompt: a JSON **schema**, and the prompt **cache** of the stable
+ * prefix.
+ *
+ * Anthropic has no `response_format` — the schema travels as a tool the model is
+ * forced to call, and the adapter turns that call back into text, so the runtime
+ * never sees a tool call it would try to execute. A streaming run gets the same
+ * treatment, delta by delta.
+ */
+import { describe, it, expect, afterAll } from "bun:test";
+import { define, v, Agent } from "../index";
+import {
+    anthropicText,
+    anthropicTool,
+    at,
+    fakeProvider,
+    openaiText,
+    request,
+    sse,
+    type Fake,
+} from "./fixtures/fake-provider";
+
+const servers: Fake[] = [];
+function track(fake: Fake): Fake {
+    servers.push(fake);
+    return fake;
+}
+
+afterAll(() => {
+    for (const server of servers) server.stop();
+});
+
+const priority = v.object({ priority: v.string().required() });
+
+function makeAgent(
+    overrides: Record<string, any> = {},
+    provider: Record<string, any> = {},
+    options: Record<string, any> = {},
+) {
+    return new Agent({
+        id: "test",
+        description: "A test agent.",
+        instructions: "You are a test agent.",
+        provider: {
+            model: "test-model",
+            apiKey: "test-key",
+            protocol: "openai",
+            options: { retries: 0, ...options },
+            ...provider,
+        },
+        ...overrides,
+    } as any);
+}
+
+const tool = () => define.Tool({
+    id: "forecast",
+    description: "Current weather for a city",
+    inputSchema: v.object({ city: v.string().required() }),
+    execute: async ({ city }: any) => ({ city, celsius: 21 }),
+});
+
+describe("structured output on an OpenAI-compatible gateway", () => {
+    it("sends the real `json_schema`, not just `json_object`", async () => {
+        const provider = track(fakeProvider(() => openaiText('{"priority":"high"}')));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const result = await agent.generate("Triage this", { schema: priority });
+
+        expect(result.object).toEqual({ priority: "high" });
+
+        const format = request(provider, 0).body.response_format;
+        expect(format.type).toBe("json_schema");
+        // The agent id names the schema when nothing else does
+        expect(format.json_schema.name).toBe("test");
+        expect(format.json_schema.schema.type).toBe("object");
+        expect(format.json_schema.schema.properties.priority.type).toBe("string");
+    });
+
+    it("names it from `api.object`, and describes it", async () => {
+        const provider = track(fakeProvider(() => openaiText('{"priority":"low"}')));
+        // What the HTTP `object` action runs: a structured call carrying `api.object`
+        const api = { object: { schema: priority, name: "triage", description: "The triage verdict." } };
+        const agent = makeAgent({ api }, { baseUrl: provider.url });
+
+        await agent.generate("Triage this", { structuredOutput: api.object });
+
+        const format = request(provider, 0).body.response_format.json_schema;
+        expect(format.name).toBe("triage");
+        expect(format.description).toBe("The triage verdict.");
+    });
+
+    it("sanitizes a name a provider would refuse", async () => {
+        const provider = track(fakeProvider(() => openaiText('{"priority":"low"}')));
+        const agent = makeAgent({
+            api: { object: { schema: priority, name: "support.billing" } },
+        }, { baseUrl: provider.url });
+
+        await agent.generate("Triage this", { structuredOutput: { schema: priority, name: "support.billing" } });
+
+        expect(request(provider, 0).body.response_format.json_schema.name).toBe("support_billing");
+    });
+
+    it("falls back to `json_object` once when the gateway refuses the schema", async () => {
+        const provider = track(fakeProvider((body) => {
+            if (body.response_format?.type === "json_schema") {
+                return new Response(JSON.stringify({ error: { message: "response_format json_schema is not supported" } }), {
+                    status: 400,
+                    headers: { "Content-Type": "application/json" },
+                });
+            }
+            return openaiText('{"priority":"high"}');
+        }));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const result = await agent.generate("Triage this", { schema: priority });
+
+        expect(result.object).toEqual({ priority: "high" });
+        expect(request(provider, 0).body.response_format.type).toBe("json_schema");
+        expect(request(provider, 1).body.response_format).toEqual({ type: "json_object" });
+    });
+
+    it("does not mask an unrelated 400", async () => {
+        const provider = track(fakeProvider(() => new Response(
+            JSON.stringify({ error: { message: "I do not like your temperature" } }),
+            { status: 400, headers: { "Content-Type": "application/json" } },
+        )));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        await expect(agent.generate("Triage this", { schema: priority }))
+            .rejects.toMatchObject({ code: "AGENT_PROVIDER_ERROR" });
+        expect(provider.hits()).toBe(1); // no retry: the schema was not the problem
+    });
+});
+
+describe("structured output on Anthropic", () => {
+    it("forces a schema tool, and turns its call back into the answer", async () => {
+        const provider = track(fakeProvider(() => anthropicTool("structured_output", { priority: "high" })));
+        const agent = makeAgent({}, { protocol: "anthropic", baseUrl: provider.url });
+
+        const result = await agent.generate("Triage this", { schema: priority });
+
+        const body = request(provider, 0).body;
+        expect(body.tool_choice).toEqual({ type: "tool", name: "structured_output" });
+        expect(body.tools).toHaveLength(1);
+        expect(body.tools[0].name).toBe("structured_output");
+        expect(body.tools[0].input_schema.type).toBe("object");
+
+        // The forced call **is** the answer: parsed and validated, never a tool call
+        expect(result.object).toEqual({ priority: "high" });
+        expect(result.toolCalls).toEqual([]);
+    });
+
+    it("keeps the agent's own tools, and the schema tool beside them", async () => {
+        const provider = track(fakeProvider(() => anthropicTool("structured_output", { priority: "low" })));
+        const agent = makeAgent({ tools: { forecast: tool() } }, { protocol: "anthropic", baseUrl: provider.url });
+
+        await agent.generate("Triage this", { schema: priority });
+
+        expect(request(provider, 0).body.tools.map((tool: any) => tool.name))
+            .toEqual(["forecast", "structured_output"]);
+    });
+
+    it("does not force a tool when extended thinking is on, and still parses", async () => {
+        const provider = track(fakeProvider(() => anthropicText('{"priority":"high"}')));
+        const agent = makeAgent({}, { protocol: "anthropic", baseUrl: provider.url });
+
+        const result = await agent.generate("Triage this", { schema: priority, thinking: true });
+
+        const body = request(provider, 0).body;
+        expect(body.thinking).toEqual({ type: "enabled", budget_tokens: 4096 });
+        // `tool_choice` is refused alongside thinking — the prompt carries the schema
+        expect(body.tool_choice).toBeUndefined();
+        expect(body.tools).toBeUndefined();
+        expect(result.object).toEqual({ priority: "high" });
+    });
+
+    it("streams the forced tool's JSON as text", async () => {
+        const provider = track(fakeProvider(() => sse([
+            JSON.stringify({ type: "message_start", message: { usage: { input_tokens: 5, output_tokens: 0 } } }),
+            JSON.stringify({ type: "content_block_start", index: 0, content_block: { type: "tool_use", id: "toolu_1", name: "structured_output" } }),
+            JSON.stringify({ type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: '{"priority"' } }),
+            JSON.stringify({ type: "content_block_delta", index: 0, delta: { type: "input_json_delta", partial_json: ':"high"}' } }),
+            JSON.stringify({ type: "content_block_stop", index: 0 }),
+            JSON.stringify({ type: "message_delta", delta: { stop_reason: "tool_use" }, usage: { output_tokens: 7 } }),
+            JSON.stringify({ type: "message_stop" }),
+        ])));
+        const agent = makeAgent({}, { protocol: "anthropic", baseUrl: provider.url });
+
+        const stream = agent.stream("Triage this", { schema: priority });
+        const chunks: any[] = [];
+        for await (const chunk of stream.fullStream) chunks.push(chunk);
+
+        expect(await stream.text).toBe('{"priority":"high"}');
+        expect(await stream.object).toEqual({ priority: "high" });
+        expect(await stream.toolCalls).toEqual([]);
+        // It arrived as text deltas — never as a tool call the run would execute
+        expect(chunks.filter((chunk) => chunk.type === "tool_call")).toHaveLength(0);
+        expect(at<any>(chunks, 0).type).toBe("text");
+    });
+});
+
+describe("prompt cache", () => {
+    it("marks the stable prefix on Anthropic — system and last tool", async () => {
+        const provider = track(fakeProvider(() => anthropicText("ok")));
+        const agent = makeAgent({ tools: { forecast: tool() } }, { protocol: "anthropic", baseUrl: provider.url }, { cache: true });
+
+        await agent.generate("hi");
+
+        const body = request(provider, 0).body;
+        expect(body.system).toEqual([{ type: "text", text: "You are a test agent.", cache_control: { type: "ephemeral" } }]);
+        expect(body.tools[body.tools.length - 1].cache_control).toEqual({ type: "ephemeral" });
+    });
+
+    it("leaves the payload alone when it is not asked for", async () => {
+        const provider = track(fakeProvider(() => anthropicText("ok")));
+        const agent = makeAgent({ tools: { forecast: tool() } }, { protocol: "anthropic", baseUrl: provider.url });
+
+        await agent.generate("hi");
+
+        const body = request(provider, 0).body;
+        expect(body.system).toBe("You are a test agent.");
+        expect(body.tools[0].cache_control).toBeUndefined();
+    });
+
+    it("is a no-op on an OpenAI-compatible gateway, which caches by itself", async () => {
+        const provider = track(fakeProvider(() => openaiText("ok")));
+        const agent = makeAgent({}, { baseUrl: provider.url }, { cache: true });
+
+        await agent.generate("hi");
+
+        expect(request(provider, 0).body.messages[0]).toEqual({ role: "system", content: "You are a test agent." });
+    });
+});
+
+describe("provider protocol", () => {
+    /** An agent whose provider is exactly what is passed — no injected default. */
+    function providerAgent(provider: Record<string, any>) {
+        return new Agent({
+            id: "test",
+            description: "A test agent.",
+            instructions: "You are a test agent.",
+            provider: { model: "test-model", apiKey: "test-key", options: { retries: 0 }, ...provider },
+        } as any);
+    }
+
+    it("calls the Messages API when `protocol: 'anthropic'`", async () => {
+        const provider = track(fakeProvider(() => anthropicText("ok")));
+        const agent = providerAgent({ protocol: "anthropic", baseUrl: provider.url });
+
+        await agent.generate("hi");
+
+        expect(request(provider, 0).path).toBe("/v1/messages");
+    });
+
+    it("still accepts the deprecated `compatible` alias", async () => {
+        const provider = track(fakeProvider(() => anthropicText("ok")));
+        const agent = providerAgent({ compatible: "anthropic", baseUrl: provider.url });
+
+        await agent.generate("hi");
+
+        expect(request(provider, 0).path).toBe("/v1/messages");
+    });
+
+    it("lets `protocol` win when the deprecated alias is set too", async () => {
+        const provider = track(fakeProvider(() => openaiText("ok")));
+        const agent = providerAgent({ compatible: "anthropic", protocol: "openai", baseUrl: provider.url });
+
+        await agent.generate("hi");
+
+        // A bare host gets `/v1` appended by the OpenAI adapter
+        expect(request(provider, 0).path).toBe("/v1/chat/completions");
+    });
+
+    it("normalizes to `protocol` in the serializable view, never leaking the alias", () => {
+        const agent = providerAgent({ compatible: "anthropic" });
+
+        const info = agent.toJSON();
+        expect(info.provider.protocol).toBe("anthropic");
+        expect(info.provider.compatible).toBeUndefined();
+    });
+
+    it("refuses an unknown protocol with `AGENT_PROVIDER_INVALID`", async () => {
+        const agent = providerAgent({ protocol: "gemini" });
+
+        await expect(agent.generate("hi")).rejects.toThrow(/Unknown provider 'protocol'/);
+    });
+});