@anteros/core 0.0.44 → 0.0.47

package/tests/agent-stream-advanced.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, afterAll } from "bun:test";
+import { Agent, define, v } from "../index";
+import { parsePartialJson } from "../lib/partialJson";
+import {
+    at,
+    fakeProvider,
+    openaiStream,
+    openaiText,
+    openaiToolCalls,
+    request,
+    sse,
+    type Fake,
+} from "./fixtures/fake-provider";
+
+/**
+ * The advanced streaming surface: a delegated run streams through its parent,
+ * tool results pass through guardrails, and `streamObject()` yields partial
+ * objects as the answer is written.
+ */
+
+const servers: Fake[] = [];
+function track(fake: Fake): Fake {
+    servers.push(fake);
+    return fake;
+}
+
+afterAll(() => {
+    for (const server of servers) server.stop();
+});
+
+function makeAgent(overrides: Record<string, any> = {}, provider: Record<string, any> = {}) {
+    return new Agent({
+        id: "advanced",
+        description: "An advanced test agent.",
+        instructions: "Answer.",
+        provider: {
+            model: "parent-model",
+            apiKey: "test-key",
+            protocol: "openai",
+            options: { retries: 0 },
+            ...provider,
+        },
+        ...overrides,
+    } as any);
+}
+
+/** A streamed `tool_calls` turn — a streamed call only reads `data:` events. */
+function openaiToolStream(name: string, args: any, id = "call_1"): Response {
+    return sse([
+        JSON.stringify({
+            choices: [{
+                delta: {
+                    tool_calls: [{
+                        index: 0,
+                        id,
+                        type: "function",
+                        function: { name, arguments: JSON.stringify(args) },
+                    }],
+                },
+            }],
+        }),
+        JSON.stringify({ choices: [{ delta: {}, finish_reason: "tool_calls" }] }),
+        "[DONE]",
+    ]);
+}
+
+/** Drain a stream to the end and return what it produced. */
+async function drain<T>(stream: AsyncIterable<T>): Promise<T[]> {
+    const out: T[] = [];
+    for await (const chunk of stream) out.push(chunk);
+    return out;
+}
+
+describe("sub-agent streaming", () => {
+    it("re-emits the child's chunks and folds its tool stats into the parent's", async () => {
+        const child = track(fakeProvider((_body, _req, hits) =>
+            hits === 1 ? openaiToolStream("lookup", {}) : openaiStream(["child ", "answer"])));
+        const parent = track(fakeProvider((_body, _req, hits) =>
+            hits === 1 ? openaiToolStream("helper", { input: "do it" }) : openaiStream(["parent ", "answer"])));
+
+        const helper = define.Agent({
+            id: "helper",
+            description: "A delegated agent",
+            instructions: "Help.",
+            provider: {
+                model: "child-model",
+                apiKey: "k",
+                protocol: "openai",
+                baseUrl: child.url,
+                options: { retries: 0 },
+            },
+            tools: {
+                lookup: define.Tool({
+                    id: "lookup",
+                    description: "Looks something up",
+                    inputSchema: v.object({}),
+                    execute: () => ({ hit: "child tool" }),
+                }),
+            },
+        });
+
+        const agent = makeAgent({ agents: [helper] }, { baseUrl: parent.url });
+        const run = agent.stream("go", { maxSteps: 3 });
+        const chunks = await drain(run.fullStream);
+
+        // The child's text travels **wrapped**, never on the parent's own channel
+        const wrapped = chunks.filter((chunk): chunk is Extract<typeof chunk, { type: "subagent" }> =>
+            chunk.type === "subagent");
+        expect(wrapped.every((chunk) => chunk.name === "helper")).toBe(true);
+        const childText = wrapped
+            .filter((chunk) => chunk.chunk.type === "text")
+            .map((chunk) => (chunk.chunk as { type: "text"; text: string }).text)
+            .join("");
+        expect(childText).toBe("child answer");
+
+        const ownText = chunks
+            .filter((chunk) => chunk.type === "text")
+            .map((chunk) => (chunk as { type: "text"; text: string }).text)
+            .join("");
+        expect(ownText).toBe("parent answer");
+        expect(await run.text).toBe("parent answer");
+
+        const results = await run.toolResults;
+        expect(at(results, 0).result).toBe("child answer");
+
+        // One parent call (the delegation) + one child call (its tool)
+        const stats = await run.toolStats;
+        expect(stats.calls).toBe(2);
+        expect(stats.errors).toBe(0);
+    });
+});
+
+describe("tool-result guardrails", () => {
+    it("blocks a result the model must not read, and finishes the run", async () => {
+        const provider = track(fakeProvider((_body, _req, hits) =>
+            hits === 1
+                ? openaiToolCalls([{ name: "safe", args: {} }, { name: "leaky", args: {} }])
+                : openaiText("done")));
+
+        const agent = makeAgent({
+            tools: {
+                safe: define.Tool({
+                    id: "safe",
+                    description: "Returns something harmless",
+                    inputSchema: v.object({}),
+                    execute: () => ({ ok: true }),
+                }),
+                leaky: define.Tool({
+                    id: "leaky",
+                    description: "Returns a secret",
+                    inputSchema: v.object({}),
+                    execute: () => ({ token: "sk-live-123" }),
+                }),
+            },
+            guardrails: {
+                tool: [{
+                    name: "no-secret",
+                    check: (value: string) => {
+                        if (value.includes("sk-live")) throw new Error("secret in tool result");
+                    },
+                }],
+            },
+        }, { baseUrl: provider.url });
+
+        const result = await agent.generate("go", { maxSteps: 3 });
+
+        // The run finished — the result was blocked, not the run
+        expect(result.text).toBe("done");
+        expect(result.finishReason).toBe("stop");
+
+        const safe = at(result.toolResults, 0);
+        const blocked = at(result.toolResults, 1);
+        expect(safe.name).toBe("safe");
+        expect(safe.error).toBeUndefined();
+        expect(safe.result).toEqual({ ok: true });
+
+        expect(blocked.error).toBe("Guardrail 'no-secret' blocked the tool result: secret in tool result");
+        expect(blocked.errorCode).toBe("AGENT_GUARDRAIL_BLOCKED");
+        expect("result" in blocked).toBe(false);
+        expect(result.toolStats.errors).toBe(1);
+        expect(result.toolStats.byCode.AGENT_GUARDRAIL_BLOCKED).toBe(1);
+
+        // The model reads the refusal as a tool error, with a code it can branch on
+        const toolTurns = request(provider, 1).body.messages.filter((message: any) => message.role === "tool");
+        const leakyTurn = toolTurns.find((message: any) => String(message.content).includes("AGENT_GUARDRAIL_BLOCKED"));
+        expect(leakyTurn).toBeDefined();
+        expect(String(leakyTurn.content)).toContain("Error [AGENT_GUARDRAIL_BLOCKED]");
+        expect(String(leakyTurn.content)).not.toContain("sk-live");
+    });
+});
+
+describe("parsePartialJson", () => {
+    it("closes an open string, an open object and an open array", () => {
+        expect(parsePartialJson('{"city": "Par')).toEqual({ city: "Par" });
+        expect(parsePartialJson('{"cities": ["Paris", "Lyo')).toEqual({ cities: ["Paris", "Lyo"] });
+        expect(parsePartialJson('{"a": {"b": [1, 2')).toEqual({ a: { b: [1, 2] } });
+        expect(parsePartialJson('{"a": 1,')).toEqual({ a: 1 });
+    });
+
+    it("survives a dangling escape and gives up when the JSON cannot be repaired", () => {
+        expect(parsePartialJson('{"a": "x\\')).toEqual({ a: "x" });
+        expect(parsePartialJson('{"a": ')).toBeUndefined();
+        expect(parsePartialJson("")).toBeUndefined();
+        expect(parsePartialJson("not json")).toBeUndefined();
+    });
+
+    it("strips a markdown fence, leading and trailing", () => {
+        expect(parsePartialJson('```json\n{"a": 1}')).toEqual({ a: 1 });
+        expect(parsePartialJson('```json\n{"a": [1, 2]\n```')).toEqual({ a: [1, 2] });
+        expect(parsePartialJson('{"a": {"b": "c')).toEqual({ a: { b: "c" } });
+    });
+});
+
+describe("streamObject", () => {
+    it("yields parsed partials and the final validated object", async () => {
+        const provider = track(fakeProvider(() =>
+            openaiStream(["{", '"cities":', ' ["Paris"', ', "Lyon"]', "}"])));
+
+        const schema = v.object({ cities: v.array().items(v.string()).required() });
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const run = agent.streamObject<{ cities: string[] }>("List cities", { schema });
+        const partials: Array<{ cities: string[] } | undefined> = [];
+        for await (const partial of run.partialObjectStream) partials.push(partial);
+
+        const parsed = partials.filter((partial): partial is { cities: string[] } => partial !== undefined);
+        expect(parsed.length).toBeGreaterThan(0);
+        expect(parsed.some((partial) => Array.isArray(partial.cities))).toBe(true);
+
+        expect(await run.object).toEqual({ cities: ["Paris", "Lyon"] });
+        expect(await run.text).toContain("Lyon");
+    });
+
+    it("rejects without a schema", () => {
+        const agent = makeAgent();
+
+        let error: any;
+        try {
+            agent.streamObject("hi");
+        } catch (err) {
+            error = err;
+        }
+
+        expect(error?.code).toBe("AGENT_SCHEMA_REQUIRED");
+    });
+});

package/tests/agent-tracing-eval.test.ts

@@ -0,0 +1,219 @@
+import { describe, it, expect, afterAll } from "bun:test";
+import { Agent, define, evaluateAgent, v } from "../index";
+import type { AgentTraceEvent } from "../index";
+import {
+    at,
+    fakeProvider,
+    openaiText,
+    openaiTool,
+    request,
+    type Fake,
+} from "./fixtures/fake-provider";
+
+/**
+ * The tracing hook (`onTrace`) and the evaluation helper (`evaluateAgent`).
+ */
+
+const servers: Fake[] = [];
+function track(fake: Fake): Fake {
+    servers.push(fake);
+    return fake;
+}
+
+afterAll(() => {
+    for (const server of servers) server.stop();
+});
+
+function makeAgent(overrides: Record<string, any> = {}, provider: Record<string, any> = {}) {
+    return new Agent({
+        id: "traced",
+        description: "A traced test agent.",
+        instructions: "Answer.",
+        provider: {
+            model: "test-model",
+            apiKey: "test-key",
+            protocol: "openai",
+            options: { retries: 0 },
+            ...provider,
+        },
+        ...overrides,
+    } as any);
+}
+
+function echoTool() {
+    return define.Tool({
+        id: "echo",
+        description: "Echoes the text back.",
+        inputSchema: v.object({ text: v.string().required() }),
+        execute: ({ text }: any) => `echo:${text}`,
+    });
+}
+
+describe("agent tracing", () => {
+    it("emits the six event types, in order, with their fields", async () => {
+        const provider = track(fakeProvider((_body, _req, hits) =>
+            hits === 1 ? openaiTool("echo", { text: "hello" }) : openaiText("done")));
+        const agent = makeAgent({ tools: { echo: echoTool() } }, { baseUrl: provider.url });
+
+        const events: AgentTraceEvent[] = [];
+        const result = await agent.generate("echo hello", { onTrace: (event) => events.push(event) });
+
+        expect(result.text).toBe("done");
+        expect(events.map((event) => event.type)).toEqual([
+            "run.start",
+            "step.start",
+            "model.end",
+            "tool.start",
+            "tool.end",
+            "step.start",
+            "model.end",
+            "run.end",
+        ]);
+
+        expect(at(events, 0)).toMatchObject({ type: "run.start", agentId: "traced" });
+        expect(at(events, 1)).toMatchObject({ type: "step.start", step: 0 });
+        expect(at(events, 2)).toMatchObject({ type: "model.end", step: 0, model: "test-model", finishReason: "tool_use" });
+        expect(at(events, 3)).toMatchObject({ type: "tool.start", step: 0, tool: "echo", toolCallId: "call_1" });
+
+        const toolEnd = at(events, 4) as Extract<AgentTraceEvent, { type: "tool.end" }>;
+        expect(toolEnd).toMatchObject({ type: "tool.end", step: 0, tool: "echo", toolCallId: "call_1" });
+        expect(toolEnd.durationMs).toBeGreaterThanOrEqual(0);
+        expect(toolEnd.errorCode).toBeUndefined();
+
+        const lastModel = at(events, 6) as Extract<AgentTraceEvent, { type: "model.end" }>;
+        expect(lastModel).toMatchObject({ step: 1, model: "test-model", finishReason: "stop" });
+        expect(lastModel.durationMs).toBeGreaterThanOrEqual(0);
+        expect(lastModel.usage.requests).toBe(1);
+
+        const end = at(events, 7) as Extract<AgentTraceEvent, { type: "run.end" }>;
+        expect(end).toMatchObject({ type: "run.end", finishReason: "stop" });
+        expect(end.durationMs).toBeGreaterThanOrEqual(0);
+        expect(end.toolStats.calls).toBe(1);
+        expect(end.usage.requests).toBe(2);
+        expect(end.error).toBeUndefined();
+    });
+
+    it("never breaks a run when the tracer throws", async () => {
+        const provider = track(fakeProvider(() => openaiText("still fine")));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const result = await agent.generate("hi", {
+            onTrace: () => {
+                throw new Error("tracer boom");
+            },
+        });
+
+        expect(result.text).toBe("still fine");
+        expect(provider.hits()).toBe(1);
+    });
+
+    it("hands the call's runId to run.start", async () => {
+        const provider = track(fakeProvider(() => openaiText("ok")));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const events: AgentTraceEvent[] = [];
+        await agent.generate("hi", { runId: "run-42", onTrace: (event) => events.push(event) });
+
+        expect(at(events, 0)).toMatchObject({ type: "run.start", runId: "run-42" });
+    });
+
+    it("traces nothing when an input guardrail blocks the prompt", async () => {
+        const provider = track(fakeProvider(() => openaiText("never")));
+        const agent = makeAgent({
+            guardrails: {
+                input: [{ name: "no-secrets", check: () => { throw new Error("blocked"); } }],
+            },
+        }, { baseUrl: provider.url });
+
+        const events: AgentTraceEvent[] = [];
+        await expect(agent.generate("a secret", { onTrace: (event) => events.push(event) }))
+            .rejects.toMatchObject({ code: "AGENT_GUARDRAIL_BLOCKED" });
+
+        expect(events).toEqual([]);
+        expect(provider.hits()).toBe(0);
+    });
+
+    it("traces the end of a run that throws", async () => {
+        const provider = track(fakeProvider(() => Response.json({ error: "boom" }, { status: 400 })));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const events: AgentTraceEvent[] = [];
+        await expect(agent.generate("hi", { onTrace: (event) => events.push(event) })).rejects.toBeDefined();
+
+        const end = at(events, events.length - 1) as Extract<AgentTraceEvent, { type: "run.end" }>;
+        expect(end.type).toBe("run.end");
+        expect(end.finishReason).toBe("error");
+        expect(end.error).toBeTruthy();
+        expect(end.error).not.toContain("\n");
+    });
+});
+
+describe("evaluateAgent", () => {
+    it("scores cases sequentially with their graders, merging the case options last", async () => {
+        const provider = track(fakeProvider((body) => {
+            const messages = body.messages as Array<{ role: string; content: string }>;
+            const lastUser = [...messages].reverse().find((message) => message.role === "user");
+            return openaiText(`answer:${lastUser?.content ?? ""}`);
+        }));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const seen: string[] = [];
+        const report = await evaluateAgent({
+            agent,
+            cases: [
+                { name: "alpha", input: "alpha" },
+                { name: "beta", input: "beta", options: { instructions: "case-two" } },
+            ],
+            graders: [
+                (result, testCase) => {
+                    seen.push(`${testCase.name}:${result.text}`);
+                    return { score: 1, reason: `answered ${testCase.name}` };
+                },
+                () => {
+                    throw new Error("grader exploded");
+                },
+            ],
+            options: { instructions: "shared" },
+        });
+
+        expect(report.score).toBe(0.5);
+        expect(report.passed).toBe(2);
+        expect(report.cases.map((testCase) => testCase.name)).toEqual(["alpha", "beta"]);
+        expect(report.cases.map((testCase) => testCase.score)).toEqual([0.5, 0.5]);
+        expect(report.cases.map((testCase) => testCase.reasons)).toEqual([
+            ["answered alpha", "grader exploded"],
+            ["answered beta", "grader exploded"],
+        ]);
+        expect(at(report.cases, 0).finishReason).toBe("stop");
+        expect(at(report.cases, 0).usage.requests).toBe(1);
+
+        // Sequential: the cases ran one after the other, in order
+        expect(seen).toEqual(["alpha:answer:alpha", "beta:answer:beta"]);
+        expect(provider.hits()).toBe(2);
+
+        // The case's options win over the shared ones
+        expect(at(request(provider, 0).body.messages, 0)).toMatchObject({ role: "system", content: "shared" });
+        expect(at(request(provider, 1).body.messages, 0)).toMatchObject({ role: "system", content: "case-two" });
+    });
+
+    it("reports nothing to score for an empty list of cases", async () => {
+        const provider = track(fakeProvider(() => openaiText("unused")));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const report = await evaluateAgent({ agent, cases: [], graders: [() => 1] });
+
+        expect(report).toEqual({ score: 0, passed: 0, cases: [] });
+        expect(provider.hits()).toBe(0);
+    });
+
+    it("gives a case score 0 when it has no grader", async () => {
+        const provider = track(fakeProvider(() => openaiText("ok")));
+        const agent = makeAgent({}, { baseUrl: provider.url });
+
+        const report = await evaluateAgent({ agent, cases: [{ name: "ungraded", input: "hi" }], graders: [] });
+
+        expect(report.score).toBe(0);
+        expect(report.passed).toBe(0);
+        expect(at(report.cases, 0)).toMatchObject({ name: "ungraded", score: 0, reasons: [] });
+    });
+});

package/tests/agent-working-memory.test.ts

@@ -396,9 +396,12 @@ describe("working memory — Anthropic", () => {
 });
 
 describe("working memory — the registry exposes nothing new by accident", () => {
-    it("keeps `agents.memory` as the only store factory", () => {
-        // `summarize` is the one deliberate addition: a **processor** factory (it needs
-        // your model and your prompt), not a store
-        expect(Object.keys(agents.memory).sort()).toEqual(["InMemory", "Mongo", "Redis", "summarize"]);
+    it("lists exactly the store and processor factories", () => {
+        // Stores: InMemory, Mongo, Redis, custom (your own handlers).
+        // Processors: `semanticRecall` (your embeddings + vector index) and
+        // `summarize` (your model + prompt) — they shape the prompt, they store nothing.
+        expect(Object.keys(agents.memory).sort()).toEqual([
+            "InMemory", "Mongo", "Redis", "custom", "semanticRecall", "summarize",
+        ]);
     });
 });

package/tests/agent.test.ts

@@ -147,6 +147,15 @@ describe("agent … files", () => {
         expect(content).not.toContain("%PDF-1.7");
     });
 
+    it("refuses a path that escapes the base directory", async () => {
+        const provider = track(fakeProvider(() => openaiText("ok")));
+        const agent = attachmentAgent({ baseUrl: provider.url });
+
+        await expect(agent.generate("hi", { files: ["../../../package.json"] }))
+            .rejects.toMatchObject({ code: "AGENT_FILE_INVALID" });
+        expect(provider.hits()).toBe(0);
+    });
+
     it("refuses an unreadable file before calling the model", async () => {
         const provider = track(fakeProvider(() => openaiText("ok")));
         const agent = attachmentAgent({ baseUrl: provider.url });
@@ -585,7 +594,7 @@ describe("Agent", () => {
         expect(definition._isAgent_).toBe(true);
         expect(definition.enabled).toBe(true);
 
-        const tool = define.Tool({ id: "t", execute: () => 1 });
+        const tool = define.Tool({ id: "t", description: "t", execute: () => 1 });
         expect(tool._isTool_).toBe(true);
         expect(tool.enabled).toBe(true);
     });
@@ -617,6 +626,13 @@ describe("Agent", () => {
         expect(agent.toJSON().tools).toEqual(["forecast"]);
     });
 
+    it("never exposes sensitive provider headers in getProvider() / toJSON()", () => {
+        const agent = makeAgent({}, { headers: { "x-api-key": "header-secret", "x-team": "core" } });
+
+        expect(agent.getProvider().headers).toEqual({ "x-team": "core" });
+        expect(JSON.stringify(agent.toJSON())).not.toContain("header-secret");
+    });
+
     it("keeps the provider's options under `provider.options`", () => {
         const agent = makeAgent({}, {}, { temperature: 0.2, maxTokens: 1000 });
         const declared = {
@@ -741,7 +757,7 @@ describe("agent.generate", () => {
 
         expect(cities).toEqual([]);
         expect(at(result.toolResults, 0).error).toContain("Invalid arguments for tool 'forecast'");
-        expect(request(provider, 1).body.messages[3].content).toContain("Error:");
+        expect(request(provider, 1).body.messages[3].content).toContain("Error [AGENT_TOOL_ARGS_INVALID]:");
     });
 
     it("reports an unknown tool and a throwing tool, and keeps going", async () => {
@@ -754,7 +770,7 @@ describe("agent.generate", () => {
 
         const agent = makeAgent({
             tools: {
-                boom: define.Tool({ id: "boom", execute: () => { throw new Error("kaboom"); } }),
+                boom: define.Tool({ id: "boom", description: "Fails", execute: () => { throw new Error("kaboom"); } }),
             },
         }, { baseUrl: provider.url });
 
@@ -1239,3 +1255,38 @@ describe("syncAgents", () => {
         expect(agents.reload).toBe(syncAgents);
     });
 });
+
+describe("syncAgents — ai/ layout", () => {
+    const TENANT = "ai-fixture";
+    const TENANT_DIR = "packages/core/tests/fixtures/ai-tenant";
+
+    beforeAll(async () => {
+        cfg.tenants = [{ id: TENANT, dir: TENANT_DIR, database: { uri: "mongodb://localhost:27017/none" } }] as any;
+        await syncAgents();
+    });
+
+    afterAll(() => {
+        cfg.agents = [];
+        cfg.mcpTools = [];
+        cfg.mcpResources = [];
+        cfg.tenants = [];
+    });
+
+    it("loads agents from ai/agents, with the tools declared beside them", () => {
+        const registry = createAgents(TENANT);
+        expect(registry.ids().sort()).toEqual(["billing", "support"]);
+
+        // `support.agent.ts` + `support.tool.ts`, same directory
+        expect(registry.get("support")!.hasTool("greet")).toBe(true);
+        // `support/billing.agent.ts` + `support/billing.tool.ts`, sub-directory
+        expect(registry.get("billing")!.hasTool("refund")).toBe(true);
+    });
+
+    it("reads ai/mcp for tools and resources", async () => {
+        const { syncMcpTools } = await import("../lib/mcp");
+        await syncMcpTools();
+
+        expect(cfg.mcpTools?.some((tool) => tool._tenant_ === TENANT && tool.name === "echo")).toBe(true);
+        expect(cfg.mcpResources?.some((resource) => resource._tenant_ === TENANT && resource.name === "readme")).toBe(true);
+    });
+});

package/tests/agents-api.test.ts

@@ -398,6 +398,27 @@ describe("agents HTTP API — actions", () => {
         expect(before).toBeLessThan(provider.hits());
     });
 
+    it("refuses a server path in `files` — content only over HTTP", async () => {
+        const before = provider.hits();
+        const invalid = [
+            ["../../../package.json"],
+            ["/etc/hosts"],
+            [{ name: "a.csv" }],
+            [{ name: "a.csv", data: 42 }],
+            [{ name: "a.csv", data: "AAAA", encoding: "hex" }],
+            "not-an-array",
+            [null],
+        ];
+
+        for (const files of invalid) {
+            const res = await json("assistant", "generate", { input: "hi", files });
+            expect({ files, status: res.status, code: res.body.code })
+                .toEqual({ files, status: 400, code: "AGENT_FILES_INVALID" });
+        }
+        // Nothing reached the model
+        expect(provider.hits()).toBe(before);
+    });
+
     it("refuses a file a model cannot read", async () => {
         const res = await json("assistant", "generate", {
             input: "hi",