@anteros/core 0.0.40 → 0.0.42

package/tests/file-collection-replication.test.ts

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { startReplication, stopReplication, replicateTenant } from "../database/replication";
+
+const TEST_TENANT = "files-repl";
+const SRC_DB = "mongodb://localhost:27017/_FILES_REPL_SRC";
+const DEST_DB = "mongodb://localhost:27017/_FILES_REPL_DEST";
+const SLUG = "photos";
+
+let rest: InstanceType<typeof useRest>;
+let sourceClient: MongoClient;
+let destClient: MongoClient;
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "src",
+            database: { uri: SRC_DB },
+            replication: {
+                runOnBoot: false,
+                schedule: { interval: "1h" },
+                destinations: [{ id: "backup", uri: DEST_DB }],
+            },
+        }],
+    });
+
+    sourceClient = new MongoClient(SRC_DB, { serverSelectionTimeoutMS: 3000 });
+    await sourceClient.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = sourceClient;
+    tenant.database.db = sourceClient.db();
+
+    (cfg as any).fileCollections = [{
+        _tenant_: TEST_TENANT,
+        _isFileCollection_: true,
+        slug: SLUG,
+        fields: [{ name: "label", type: "string" }],
+        api: { access: { "*": true } },
+        // Opt the file collection's documents into the data replication engine.
+        replication: { enabled: true },
+    }];
+
+    await startReplication();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+    destClient = new MongoClient(DEST_DB, { serverSelectionTimeoutMS: 3000 });
+    await destClient.connect();
+});
+
+afterAll(async () => {
+    await stopReplication();
+    try { await sourceClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.db().dropDatabase(); } catch (_) {}
+    try { await destClient.close(); } catch (_) {}
+    try { await sourceClient.close(); } catch (_) {}
+});
+
+const destDoc = (label: string) => destClient.db().collection(SLUG).findOne({ label });
+
+describe("file collection replication", () => {
+    it("replicates file-collection documents", async () => {
+        await rest.insertOne(SLUG, { label: "a", _file: { filename: "a.png" } });
+        await replicateTenant(TEST_TENANT);
+
+        const dest = await destDoc("a");
+        expect(dest).toBeDefined();
+        expect((dest as any)._file.filename).toBe("a.png");
+    });
+
+    it("propagates deletions via tombstones", async () => {
+        const doc: any = await rest.insertOne(SLUG, { label: "del-me" });
+        await replicateTenant(TEST_TENANT);
+        expect(await destDoc("del-me")).toBeDefined();
+
+        await rest.deleteOne(SLUG, doc._id);
+        await replicateTenant(TEST_TENANT);
+        expect(await destDoc("del-me")).toBeNull();
+    });
+
+    it("does not replicate a file collection that did not opt in", async () => {
+        (cfg as any).fileCollections.push({
+            _tenant_: TEST_TENANT,
+            _isFileCollection_: true,
+            slug: "private-files",
+            fields: [],
+            api: { access: { "*": true } },
+        });
+
+        await rest.insertOne("private-files", { label: "secret" });
+        await replicateTenant(TEST_TENANT);
+
+        expect(await destClient.db().collection("private-files").findOne({ label: "secret" })).toBeNull();
+    });
+});

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

package/tests/fixtures/fake-provider.ts

@@ -0,0 +1,128 @@
+/**
+ * Fake model providers for the agent tests — one local HTTP endpoint per
+ * protocol, recording what the runtime sent.
+ *
+ * Shared by `agent.test.ts` (runtime) and `agents-api.test.ts` (HTTP surface),
+ * so a change in the wire format is fixed in one place.
+ */
+
+export type Recorded = { path: string; body: any; headers: Record<string, string> };
+
+export type Fake = {
+    requests: Recorded[];
+    url: string;
+    hits: () => number;
+    stop: () => void;
+};
+
+/** A local endpoint that records the requests and answers from `handler`. */
+export function fakeProvider(handler: (body: any, req: Request, hits: number) => Response | Promise<Response>): Fake {
+    const requests: Recorded[] = [];
+    let hits = 0;
+    const server = Bun.serve({
+        port: 0,
+        hostname: "127.0.0.1",
+        fetch: async (req) => {
+            const body = await req.json().catch(() => null);
+            requests.push({
+                path: new URL(req.url).pathname,
+                body,
+                headers: Object.fromEntries(req.headers.entries()),
+            });
+            hits += 1;
+            return handler(body, req, hits);
+        },
+    });
+    return {
+        requests,
+        url: `http://127.0.0.1:${server.port}`,
+        hits: () => hits,
+        stop: () => server.stop(true),
+    };
+}
+
+/** Typed element access (`noUncheckedIndexedAccess` is on). */
+export function at<T>(list: T[], index = 0): T {
+    const item = list[index];
+    if (item === undefined) throw new Error(`No element #${index} (length ${list.length})`);
+    return item;
+}
+
+export function request(provider: Fake, index = 0): Recorded {
+    const recorded = provider.requests[index];
+    if (!recorded) throw new Error(`No request #${index} was recorded (got ${provider.requests.length})`);
+    return recorded;
+}
+
+export const USAGE = { prompt_tokens: 11, completion_tokens: 4, total_tokens: 15 };
+export const A_USAGE = { input_tokens: 13, output_tokens: 6 };
+
+/** An SSE response from a list of already-serialized events. */
+export function sse(events: string[]): Response {
+    return new Response(events.map((event) => `data: ${event}\n\n`).join(""), {
+        headers: { "Content-Type": "text/event-stream" },
+    });
+}
+
+// ─── OpenAI-compatible ───────────────────────────────────────────────────
+
+export function openaiText(text: string, finishReason = "stop"): Response {
+    return Response.json({
+        choices: [{ message: { role: "assistant", content: text }, finish_reason: finishReason }],
+        usage: USAGE,
+    });
+}
+
+export function openaiTool(name: string, args: any, id = "call_1"): Response {
+    return Response.json({
+        choices: [{
+            message: {
+                role: "assistant",
+                content: null,
+                tool_calls: [{ id, type: "function", function: { name, arguments: JSON.stringify(args) } }],
+            },
+            finish_reason: "tool_calls",
+        }],
+        usage: USAGE,
+    });
+}
+
+export function openaiStream(pieces: string[]): Response {
+    const events = pieces.map((text) => JSON.stringify({ choices: [{ delta: { content: text } }] }));
+    events.push(JSON.stringify({ choices: [], usage: USAGE }));
+    events.push(JSON.stringify({ choices: [{ delta: {}, finish_reason: "stop" }] }));
+    events.push("[DONE]");
+    return sse(events);
+}
+
+// ─── Anthropic ───────────────────────────────────────────────────────────
+
+export function anthropicText(text: string, stopReason = "end_turn"): Response {
+    return Response.json({
+        content: [{ type: "text", text }],
+        stop_reason: stopReason,
+        usage: A_USAGE,
+    });
+}
+
+export function anthropicTool(name: string, input: any, id = "toolu_1"): Response {
+    return Response.json({
+        content: [{ type: "tool_use", id, name, input }],
+        stop_reason: "tool_use",
+        usage: A_USAGE,
+    });
+}
+
+export function anthropicStream(pieces: string[]): Response {
+    const events: string[] = [
+        JSON.stringify({ type: "message_start", message: { usage: { input_tokens: 9, output_tokens: 0 } } }),
+        JSON.stringify({ type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }),
+    ];
+    for (const text of pieces) {
+        events.push(JSON.stringify({ type: "content_block_delta", index: 0, delta: { type: "text_delta", text } }));
+    }
+    events.push(JSON.stringify({ type: "content_block_stop", index: 0 }));
+    events.push(JSON.stringify({ type: "message_delta", delta: { stop_reason: "end_turn" }, usage: { output_tokens: 5 } }));
+    events.push(JSON.stringify({ type: "message_stop" }));
+    return sse(events);
+}

package/tests/fixtures/lc-disabled/lifecycle.ts

@@ -0,0 +1,11 @@
+// Test fixture — disabled lifecycle (must be skipped).
+const calls: string[] = [];
+(globalThis as any).__lcDisabled = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: false,
+    beforeBoot: async () => { calls.push("beforeBoot"); },
+    afterBoot: async () => { calls.push("afterBoot"); },
+    onDestroy: async () => { calls.push("onDestroy"); },
+};

package/tests/fixtures/lc-hang/lifecycle.ts

@@ -0,0 +1,13 @@
+// Test fixture — `onDestroy` never resolves (used to test destroyTimeout).
+const calls: string[] = [];
+(globalThis as any).__lcHang = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    destroyTimeout: 100,
+    onDestroy: async () => {
+        calls.push("onDestroy:start");
+        await new Promise(() => { /* never resolves */ });
+    },
+};

package/tests/fixtures/lc-normal/lifecycle.ts

@@ -0,0 +1,23 @@
+// Test fixture — records lifecycle calls on globalThis.
+const calls: string[] = [];
+(globalThis as any).__lcNormal = calls;
+
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    destroyTimeout: 200,
+    beforeBoot: async ({ replication }: any) => {
+        calls.push("beforeBoot");
+        // The API is tenant-bound (like `rest`) — no tenant id is passed, and the
+        // implicit tenant must match this lifecycle's tenant.
+        const seeded = await replication.seed("latest");
+        (globalThis as any).__lcReplicationApi =
+            typeof replication?.seed === "function" &&
+            typeof replication?.reset === "function" &&
+            typeof replication?.now === "function" &&
+            typeof replication?.state === "function" &&
+            seeded?.tenant === "normal";
+    },
+    afterBoot: async () => { calls.push("afterBoot"); },
+    onDestroy: async ({ reason }: any) => { calls.push(`onDestroy:${reason}`); },
+};

package/tests/fixtures/lc-throw/lifecycle.ts

@@ -0,0 +1,6 @@
+// Test fixture — `beforeBoot` throws.
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    beforeBoot: async () => { throw new Error("boom"); },
+};

package/tests/fixtures/repl-only/app.ts

@@ -0,0 +1,26 @@
+/**
+ * Fixture — boots the server through `bootApp`, to be launched with a boot mode
+ * flag (see `packages/core/tests/replication-only.test.ts`).
+ * Port and database URIs are overridable through the environment so the same
+ * fixture serves every mode without clashes.
+ *
+ * Run manually:
+ *   bun packages/core/tests/fixtures/repl-only/app.ts --replication-only
+ *   bun packages/core/tests/fixtures/repl-only/app.ts --no-replication
+ */
+import { bootApp } from "../../../server/boot";
+
+await bootApp({
+    server: { port: Number(Bun.env.RO_PORT ?? 5556) },
+    tenants: [{
+        id: "ro",
+        dir: "packages/core/tests/fixtures/repl-only/tenant",
+        database: { uri: Bun.env.RO_SRC ?? "mongodb://localhost:27017/_RO_SRC" },
+        replication: {
+            enabled: true,
+            runOnBoot: true,
+            schedule: { interval: "1h" },
+            destinations: [{ id: "backup", uri: Bun.env.RO_DST ?? "mongodb://localhost:27017/_RO_DST" }],
+        },
+    }],
+});

package/tests/fixtures/repl-only/tenant/collections/orders.model.ts

@@ -0,0 +1,14 @@
+// Test fixture — a replicable collection (plain object + marker, no import needed).
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "orders",
+    fields: [
+        { name: "ref", type: "string" },
+        { name: "total", type: "number" },
+    ],
+    api: { access: { "*": true } },
+    // Opt this collection into the data replication engine
+    replication: { enabled: true },
+};

package/tests/fixtures/repl-only/tenant/lifecycle.ts

@@ -0,0 +1,14 @@
+// Test fixture — `beforeBoot` / `onDestroy` must still run in replication-only
+// mode (the documented place to seed or reset a replication before it starts).
+// Each hook drops a marker file the test can assert on.
+// (`enabled` mirrors what `define.Lifecycle` sets by default.)
+export default {
+    _isLifecycle_: true,
+    enabled: true,
+    beforeBoot: async () => {
+        await Bun.write(new URL("./.markers/lifecycle.txt", import.meta.url), "beforeBoot");
+    },
+    onDestroy: async () => {
+        await Bun.write(new URL("./.markers/onDestroy.txt", import.meta.url), "onDestroy");
+    },
+};

package/tests/fixtures/repl-only/tenant/scripts/probe.run.ts

@@ -0,0 +1,8 @@
+// Test fixture — must NOT run in replication-only mode (no `runScripts`).
+export default {
+    _isScript_: true,
+    enabled: true,
+    exec: async () => {
+        await Bun.write(new URL("../.markers/script.txt", import.meta.url), "ran");
+    },
+};

package/tests/fixtures/replication-meta/agents/chat.agent.ts

@@ -0,0 +1,16 @@
+import { define, agents } from "../../../../index";
+
+/**
+ * The collection this tenant names for its agent memory. The loader publishes it
+ * (`cfg.agentMemories`), so the replication engine copies it like a declared
+ * collection — `replication.exclude: ['memory']` is the opt-out.
+ */
+export const AGENT_THREADS = "agent_threads";
+
+export default define.Agent({
+    id: "chat",
+    description: "Fixture agent whose memory lives in a tenant-named collection.",
+    instructions: "Fixture agent — no model call is ever made in these tests.",
+    provider: { model: "test-model", compatible: "openai", apiKey: "fixture" },
+    memory: new agents.memory.Mongo({ collection: AGENT_THREADS }),
+});

package/tests/fixtures/replication-meta/collections/counters.model.ts

@@ -0,0 +1,13 @@
+// Test fixture — a collection whose replication key is a **number** (not a date).
+// The delete guard must still match on the destination.
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "counters",
+    fields: [
+        { name: "seq", type: "number" },
+        { name: "title", type: "string" },
+    ],
+    replication: { enabled: true, key: "seq" },
+};

package/tests/fixtures/replication-meta/collections/orders.model.ts

@@ -0,0 +1,9 @@
+// Test fixture — a declared collection that opted into replication.
+export default {
+    _isCollection_: true,
+    _isTimeSerie_: false,
+    type: "document",
+    slug: "orders",
+    fields: [{ name: "title", type: "string" }],
+    replication: { enabled: true },
+};

package/tests/fixtures/replication-meta/workflows/run.workflow.ts

@@ -0,0 +1,8 @@
+// Test fixture — a workflow whose runs must follow the data to the destination.
+export default {
+    _isWorkflow_: true,
+    id: "run",
+    name: "Run",
+    version: 1,
+    steps: [{ id: "one", exec: async () => ({ ok: true }) }],
+};

package/tests/fixtures/vars-tenant/vars/config.var.ts

@@ -0,0 +1,23 @@
+// Test fixture — a `define.Vars` definition (plain object + marker).
+export default {
+    _isVars_: true,
+    namespace: "config",
+    scope: { name: "company", type: "relationship", relation: { to: "companies" } },
+    meta: [
+        { name: "note", type: "string" },
+        { name: "expiresAt", type: "datetime-local" },
+    ],
+    vars: {
+        licence: "RDX00",
+        maxUsers: { type: "number", defaultValue: 100 },
+        session: { type: "string", ttl: "1h" },
+    },
+    api: {
+        access: {
+            "*": true,
+            set: true,
+        },
+    },
+    // Opt this namespace into replication (per-namespace filter on `ns`).
+    replication: { enabled: true },
+};

package/tests/fixtures/vars-tenant/vars/private.var.ts

@@ -0,0 +1,9 @@
+// Test fixture — a namespace WITHOUT `api.access` (must be denied over HTTP),
+// and which explicitly opts OUT of replication.
+export default {
+    _isVars_: true,
+    namespace: "private",
+    vars: { secret: "shh" },
+    // Framework collections are replicated by default: opting out is explicit
+    replication: { enabled: false },
+};