@nebutra/agent-runtime 0.2.0

package/src/adapters/mcp-catalog.test.ts

@@ -0,0 +1,213 @@
+import type { MCPContext, ToolExecutionResult } from "@nebutra/mcp";
+import { MCPServerRegistry } from "@nebutra/mcp";
+import { describe, expect, it, vi } from "vitest";
+import type { z } from "zod";
+import { activateMcpTools, type McpServerCatalogPort } from "../mcp-bridge";
+import { ToolRegistry } from "../tools";
+
+import { createMcpClientPort, createMcpServerCatalog } from "./mcp-catalog.js";
+
+/**
+ * Build a fresh, isolated registry seeded with two servers gated by plan and
+ * tenant. No network — `local` transport with in-process handlers.
+ */
+function seedRegistry(): MCPServerRegistry {
+  const registry = new MCPServerRegistry();
+
+  registry.register({
+    id: "weather",
+    name: "Weather",
+    description: "Weather tools",
+    endpoint: "local://weather",
+    transport: "local",
+    tools: [
+      {
+        name: "forecast",
+        description: "Get a forecast",
+        parameters: {
+          city: { type: "string", description: "City name", required: true },
+          days: { type: "number", description: "Day count" },
+        },
+      },
+      {
+        name: "alerts",
+        description: "Severe weather alerts (pro only)",
+        allowedPlans: ["pro", "enterprise"],
+      },
+    ],
+    handlers: {
+      forecast: (args) => ({ ok: true, echo: args }),
+      alerts: () => ({ ok: true, alerts: [] }),
+    },
+  });
+
+  registry.register({
+    id: "acme-private",
+    name: "Acme Private",
+    description: "Tenant-scoped server",
+    endpoint: "local://acme",
+    transport: "local",
+    allowedTenants: ["tenant-acme"],
+    tools: [{ name: "acme_secret", description: "Acme-only tool" }],
+    handlers: { acme_secret: () => ({ ok: true }) },
+  });
+
+  return registry;
+}
+
+describe("createMcpServerCatalog", () => {
+  it("fails closed on empty tenantId before touching the registry", async () => {
+    const registry = new MCPServerRegistry();
+    const spy = vi.spyOn(registry, "getAccessibleTools");
+    const catalog = createMcpServerCatalog(registry);
+
+    await expect(catalog.listTools({ tenantId: "" })).rejects.toThrow();
+    await expect(catalog.listTools({ tenantId: "   " })).rejects.toThrow();
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it("plan-gates: a free tenant sees fewer tools than a pro tenant", async () => {
+    const catalog = createMcpServerCatalog(seedRegistry());
+
+    const free = await catalog.listTools({ tenantId: "tenant-1", plan: "free" });
+    const pro = await catalog.listTools({ tenantId: "tenant-1", plan: "pro" });
+
+    const freeNames = free.map((e) => e.definition.name).sort();
+    const proNames = pro.map((e) => e.definition.name).sort();
+
+    expect(freeNames).toEqual(["forecast"]);
+    expect(proNames).toEqual(["alerts", "forecast"]);
+    expect(pro.length).toBeGreaterThan(free.length);
+  });
+
+  it("isolates tenants: only the allowed tenant sees its private server", async () => {
+    const catalog = createMcpServerCatalog(seedRegistry());
+
+    const other = await catalog.listTools({ tenantId: "tenant-other", plan: "enterprise" });
+    const acme = await catalog.listTools({ tenantId: "tenant-acme", plan: "enterprise" });
+
+    expect(other.map((e) => e.definition.name)).not.toContain("acme_secret");
+    expect(acme.map((e) => e.definition.name)).toContain("acme_secret");
+  });
+
+  it("produces a usable ToolDefinition even for a schema-less MCP tool", async () => {
+    const catalog = createMcpServerCatalog(seedRegistry());
+    const pro = await catalog.listTools({ tenantId: "tenant-1", plan: "pro" });
+
+    const alerts = pro.find((e) => e.definition.name === "alerts");
+    expect(alerts).toBeDefined();
+    // No `parameters` → permissive object schema, never throws on parse.
+    expect(() => alerts?.definition.inputSchema.parse({})).not.toThrow();
+    expect(() => alerts?.definition.inputSchema.parse({ anything: 1 })).not.toThrow();
+    expect(alerts?.server).toBe("weather");
+  });
+
+  it("derives a Zod schema from MCP `parameters`", async () => {
+    const catalog = createMcpServerCatalog(seedRegistry());
+    const free = await catalog.listTools({ tenantId: "tenant-1", plan: "free" });
+    const forecast = free.find((e) => e.definition.name === "forecast");
+
+    expect(forecast).toBeDefined();
+    if (!forecast) throw new Error("forecast tool missing");
+    const schema = forecast.definition.inputSchema as z.ZodType;
+    // Required `city` enforced.
+    expect(() => schema.parse({})).toThrow();
+    expect(schema.parse({ city: "NYC" })).toMatchObject({ city: "NYC" });
+    expect(schema.parse({ city: "NYC", days: 3 })).toMatchObject({ days: 3 });
+  });
+});
+
+describe("createMcpClientPort", () => {
+  it("forwards tenantId into the MCPContext and unwraps the result envelope", async () => {
+    let seen: MCPContext | undefined;
+    const fake = {
+      async executeTool(
+        _name: string,
+        _args: Record<string, unknown>,
+        ctx: MCPContext,
+      ): Promise<ToolExecutionResult> {
+        seen = ctx;
+        return { success: true, result: { value: 42 }, duration: 1 };
+      },
+    };
+
+    const port = createMcpClientPort(fake);
+    const out = await port.executeTool(
+      "forecast",
+      { city: "NYC" },
+      {
+        requestId: "req-1",
+        tenantId: "tenant-xyz",
+      },
+    );
+
+    expect(out).toEqual({ value: 42 });
+    expect(seen?.tenantId).toBe("tenant-xyz");
+    expect(seen?.requestId).toBe("req-1");
+  });
+
+  it("fails closed when the MCP client reports failure", async () => {
+    const fake = {
+      async executeTool(): Promise<ToolExecutionResult> {
+        return { success: false, error: "Access denied", duration: 1 };
+      },
+    };
+    const port = createMcpClientPort(fake);
+
+    await expect(port.executeTool("x", {}, { requestId: "r", tenantId: "t" })).rejects.toThrow(
+      /Access denied/,
+    );
+  });
+
+  it("rejects an empty tenantId at the client boundary (fail-closed)", async () => {
+    const fake = {
+      executeTool: vi.fn(
+        async (): Promise<ToolExecutionResult> => ({
+          success: true,
+          result: null,
+          duration: 0,
+        }),
+      ),
+    };
+    const port = createMcpClientPort(fake);
+
+    await expect(port.executeTool("x", {}, { requestId: "r", tenantId: "" })).rejects.toThrow();
+    expect(fake.executeTool).not.toHaveBeenCalled();
+  });
+});
+
+describe("composition with agent-runtime activateMcpTools", () => {
+  it("registers catalog tools into a ToolRegistry and dispatches through the client port", async () => {
+    const catalog: McpServerCatalogPort = createMcpServerCatalog(seedRegistry());
+    const calls: { name: string; ctx: MCPContext }[] = [];
+    const client = createMcpClientPort({
+      async executeTool(
+        name: string,
+        args: Record<string, unknown>,
+        ctx: MCPContext,
+      ): Promise<ToolExecutionResult> {
+        calls.push({ name, ctx });
+        return { success: true, result: { echoed: args }, duration: 1 };
+      },
+    });
+
+    const registry = new ToolRegistry();
+    const result = await activateMcpTools(registry, catalog, client, {
+      tenantId: "tenant-1",
+      plan: "pro",
+    });
+
+    expect([...result.registered].sort()).toEqual(["alerts", "forecast"]);
+    expect(result.skipped).toEqual([]);
+
+    const out = await registry.dispatch(
+      "forecast",
+      { city: "NYC" },
+      { tenantId: "tenant-1", threadId: "thread-1" },
+    );
+
+    expect(out).toEqual({ echoed: { city: "NYC" } });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.ctx.tenantId).toBe("tenant-1");
+  });
+});

package/src/adapters/mcp-catalog.ts

@@ -0,0 +1,188 @@
+/**
+ * MCP catalog adapter — concrete wiring of `@nebutra/mcp` into
+ * `@nebutra/agent-runtime`'s injectable ports.
+ *
+ * `@nebutra/agent-runtime` is intentionally dependency-free: it declares the
+ * `McpServerCatalogPort` / `McpClientLike` ports and an `activateMcpTools`
+ * composer, but never imports `@nebutra/mcp`. This module supplies the only
+ * concrete bridge so apps/backends reuse it instead of re-implementing glue.
+ *
+ * Invariants:
+ *  - tenantId is mandatory and validated *before* any registry/client call
+ *    (fail-closed): an empty/blank tenant can never enumerate or execute.
+ *  - Plan/tenant gating is delegated to `MCPServerRegistry` — a tenant only
+ *    ever sees the tools its plan/tenant policy permits.
+ *  - MCP `parameters` are translated into a Zod `inputSchema`; a tool with no
+ *    usable schema still yields a permissive, never-crashing definition.
+ *  - The MCP `ToolExecutionResult` envelope is unwrapped: a non-success
+ *    result throws (fail-closed) rather than leaking a falsy value upstream.
+ *
+ * Both factories accept an injected dependency (registry / client) and default
+ * to the `@nebutra/mcp` singletons, keeping the module free of hidden globals
+ * and fully unit-testable.
+ */
+
+import type { MCPContext, MCPServerRegistry, ToolExecutionResult } from "@nebutra/mcp";
+import { mcpClient, serverRegistry } from "@nebutra/mcp";
+import { z } from "zod";
+import type { McpServerCatalogPort } from "../mcp-bridge";
+import type { McpClientLike, ToolDefinition } from "../tools";
+
+/** Narrow structural shapes — we depend on behaviour, not concrete classes. */
+
+/** The slice of `MCPServerRegistry` the catalog port needs. */
+export type McpRegistryLike = Pick<MCPServerRegistry, "getAccessibleTools">;
+
+/** The slice of `mcpClient` the client port needs. */
+export interface McpExecutorLike {
+  executeTool(
+    name: string,
+    args: Record<string, unknown>,
+    ctx: MCPContext,
+  ): Promise<ToolExecutionResult>;
+}
+
+type McpParameter = {
+  type?: "string" | "number" | "boolean" | "object" | "array";
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+};
+
+type McpToolShape = {
+  name: string;
+  description?: string;
+  parameters?: Record<string, McpParameter> | undefined;
+  serverId: string;
+};
+
+/** Fail-closed tenant guard — the single chokepoint for both ports. */
+const tenantSchema = z
+  .string({ message: "tenantId is required (fail-closed)" })
+  .trim()
+  .min(1, "tenantId is required (fail-closed)");
+
+const catalogCtxSchema = z.object({
+  tenantId: tenantSchema,
+  plan: z.string().min(1).optional(),
+});
+
+const clientCtxSchema = z.object({
+  requestId: z.string().min(1, "requestId is required"),
+  tenantId: tenantSchema,
+});
+
+/** Map one MCP parameter to its Zod leaf type. Unknown → permissive. */
+function paramToZod(param: McpParameter): z.ZodTypeAny {
+  switch (param.type) {
+    case "string":
+      return z.string();
+    case "number":
+      return z.number();
+    case "boolean":
+      return z.boolean();
+    case "array":
+      return z.array(z.unknown());
+    case "object":
+      return z.record(z.string(), z.unknown());
+    default:
+      return z.unknown();
+  }
+}
+
+/**
+ * Build a Zod `inputSchema` from an MCP tool's `parameters`. A tool with no
+ * declared parameters becomes a permissive passthrough object (never throws on
+ * unknown keys) so schema-less MCP tools remain dispatchable.
+ */
+function toInputSchema(parameters: Record<string, McpParameter> | undefined): z.ZodType {
+  const entries = parameters ? Object.entries(parameters) : [];
+  if (entries.length === 0) {
+    return z.record(z.string(), z.unknown());
+  }
+
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const [key, param] of entries) {
+    let leaf = paramToZod(param);
+    if (param.required !== true) {
+      leaf = leaf.optional();
+    }
+    shape[key] = leaf;
+  }
+  // `passthrough` keeps unknown keys: MCP schemas are advisory, not strict.
+  return z.object(shape).passthrough();
+}
+
+/** Adapt one registry tool entry into an agent-runtime `ToolDefinition`. */
+function toToolDefinition(tool: McpToolShape): ToolDefinition {
+  return {
+    name: tool.name,
+    description: tool.description ?? tool.name,
+    inputSchema: toInputSchema(tool.parameters),
+  };
+}
+
+/**
+ * Adapt `MCPServerRegistry`'s plan/tenant-gated tool listing into the
+ * agent-runtime `McpServerCatalogPort`.
+ *
+ * @param registry  Defaults to `@nebutra/mcp`'s `serverRegistry` singleton;
+ *                   inject a fresh `MCPServerRegistry` for tests/multi-tenant
+ *                   isolation.
+ */
+export function createMcpServerCatalog(
+  registry: McpRegistryLike = serverRegistry,
+): McpServerCatalogPort {
+  return {
+    async listTools(ctx) {
+      const scope = catalogCtxSchema.parse(ctx); // fail-closed first
+
+      const mcpCtx: MCPContext = {
+        requestId: "catalog-list",
+        tenantId: scope.tenantId,
+        ...(scope.plan === undefined ? {} : { plan: scope.plan }),
+      };
+
+      const tools = registry.getAccessibleTools(mcpCtx) as McpToolShape[];
+
+      return tools.map((tool) => ({
+        server: tool.serverId,
+        definition: toToolDefinition(tool),
+      }));
+    },
+  };
+}
+
+/**
+ * Adapt `@nebutra/mcp`'s `mcpClient` into agent-runtime's `McpClientLike`.
+ *
+ * Maps `{ requestId, tenantId }` → the richer `MCPContext`, and unwraps the
+ * `ToolExecutionResult` envelope: a non-success result throws so a failed MCP
+ * call never silently surfaces as a falsy tool output.
+ *
+ * @param client  Defaults to `@nebutra/mcp`'s `mcpClient` singleton;
+ *                inject a fake for tests.
+ */
+export function createMcpClientPort(client: McpExecutorLike = mcpClient): McpClientLike {
+  return {
+    async executeTool(name, args, ctx) {
+      const scope = clientCtxSchema.parse(ctx); // fail-closed first
+
+      const mcpCtx: MCPContext = {
+        requestId: scope.requestId,
+        tenantId: scope.tenantId,
+      };
+
+      const result = await client.executeTool(
+        name,
+        (args ?? {}) as Record<string, unknown>,
+        mcpCtx,
+      );
+
+      if (!result.success) {
+        throw new Error(`MCP tool "${name}" failed: ${result.error ?? "unknown error"}`);
+      }
+      return result.result;
+    },
+  };
+}

package/src/adapters/prisma-rollout.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { type ApprovalGate, type ModelInvoker, runTurn } from "../loop";
+import { type RolloutLine, replay } from "../rollout";
+import { PersistentRolloutStore } from "../rollout-store-persistent";
+import { ToolRegistry } from "../tools";
+import { createPrismaRolloutPersistence, type PrismaRolloutDelegate } from "./prisma-rollout.js";
+
+/** In-memory fake mirroring the agent_rollout_lines table semantics. */
+function fakeDelegate() {
+  const rows: { tenantId: string; threadId: string; seq: number; at: Date; payload: string }[] = [];
+  const delegate: PrismaRolloutDelegate = {
+    async create({ data }) {
+      if (
+        rows.some(
+          (r) => r.tenantId === data.tenantId && r.threadId === data.threadId && r.seq === data.seq,
+        )
+      ) {
+        // Mirrors the unique (tenant,thread,seq) constraint — fail loud.
+        throw new Error("unique constraint violation");
+      }
+      rows.push({ ...data });
+      return data;
+    },
+    async findMany({ where }) {
+      return rows
+        .filter((r) => r.tenantId === where.tenantId && r.threadId === where.threadId)
+        .sort((a, b) => a.seq - b.seq)
+        .map((r) => ({ seq: r.seq, payload: r.payload }));
+    },
+  };
+  return { delegate, rows };
+}
+
+const line = (tenantId: string, threadId: string): RolloutLine => ({
+  tenantId,
+  threadId,
+  type: "session_meta",
+  config: {
+    model: "m",
+    provider: "p",
+    approvalPolicy: "on_request",
+    capabilityPolicy: "external_sandbox",
+  },
+  at: new Date().toISOString(),
+});
+
+describe("createPrismaRolloutPersistence", () => {
+  it("round-trips through PersistentRolloutStore and replays faithfully", async () => {
+    const { delegate } = fakeDelegate();
+    const store = new PersistentRolloutStore(createPrismaRolloutPersistence(delegate));
+    await store.append(line("org_a", "th_1"));
+    await store.append({
+      tenantId: "org_a",
+      threadId: "th_1",
+      type: "event",
+      at: new Date().toISOString(),
+      event: { type: "item.completed", item: { id: "i1", type: "agent_message", text: "hi" } },
+    });
+    const proj = replay(await store.read("org_a", "th_1"));
+    expect(proj?.items.map((i) => i.id)).toEqual(["i1"]);
+  });
+
+  it("isolates tenants — B cannot read A's thread", async () => {
+    const { delegate } = fakeDelegate();
+    const store = new PersistentRolloutStore(createPrismaRolloutPersistence(delegate));
+    await store.append(line("org_a", "th_1"));
+    expect(await store.read("org_b", "th_1")).toHaveLength(0);
+  });
+
+  it("fails loud on a persistence rejection (never silently drops)", async () => {
+    const failing: PrismaRolloutDelegate = {
+      async create() {
+        throw new Error("db down");
+      },
+      async findMany() {
+        return [];
+      },
+    };
+    const port = createPrismaRolloutPersistence(failing);
+    await expect(
+      port.put({
+        tenantId: "t",
+        threadId: "th",
+        seq: 0,
+        at: new Date().toISOString(),
+        payload: "{}",
+      }),
+    ).rejects.toThrow("db down");
+  });
+
+  it("fails closed on empty tenant / bad timestamp", async () => {
+    const { delegate } = fakeDelegate();
+    const port = createPrismaRolloutPersistence(delegate);
+    await expect(
+      port.put({ tenantId: "", threadId: "th", seq: 0, at: "x", payload: "{}" }),
+    ).rejects.toBeTruthy();
+    await expect(
+      port.put({ tenantId: "t", threadId: "th", seq: 0, at: "not-a-date", payload: "{}" }),
+    ).rejects.toThrow(/invalid timestamp/);
+  });
+
+  it("resolves a per-tenant delegate (RLS client per call)", async () => {
+    const a = fakeDelegate();
+    const b = fakeDelegate();
+    const port = createPrismaRolloutPersistence((tenantId) =>
+      tenantId === "org_a" ? a.delegate : b.delegate,
+    );
+    await port.put({
+      tenantId: "org_a",
+      threadId: "th",
+      seq: 0,
+      at: new Date().toISOString(),
+      payload: "{}",
+    });
+    expect(a.rows).toHaveLength(1);
+    expect(b.rows).toHaveLength(0);
+  });
+
+  it("drives a full turn whose rollout survives in the durable backend", async () => {
+    const { delegate, rows } = fakeDelegate();
+    const store = new PersistentRolloutStore(createPrismaRolloutPersistence(delegate));
+    const model: ModelInvoker = {
+      async invoke() {
+        return { emissions: [{ kind: "text", text: "done" }] };
+      },
+    };
+    const gate: ApprovalGate = {
+      async request() {
+        return { kind: "denied" };
+      },
+    };
+    const events = [];
+    for await (const e of runTurn("hi", {
+      tenantId: "org_a",
+      threadId: "th_x",
+      config: {
+        model: "m",
+        provider: "p",
+        approvalPolicy: "on_request",
+        capabilityPolicy: "external_sandbox",
+      },
+      approvalPolicy: { kind: "on_request" },
+      model,
+      tools: new ToolRegistry(),
+      store,
+      approvalGate: gate,
+    })) {
+      events.push(e);
+    }
+    expect(rows.length).toBe(events.length);
+    expect(rows.every((r) => r.tenantId === "org_a")).toBe(true);
+  });
+});

package/src/adapters/prisma-rollout.ts

@@ -0,0 +1,104 @@
+/**
+ * Durable rollout-store backend: `RolloutPersistencePort` over Prisma.
+ *
+ * This is the fail-loud system-of-record adapter (table `agent_rollout_lines`,
+ * migration `20260519000000_add_agent_rollout_store`). Unlike a best-effort
+ * audit log it never swallows a failed write — a rejected `put` propagates so
+ * the caller's "never silently drop" contract holds.
+ *
+ * Reusability: it depends only on a minimal injected delegate (the
+ * `PrismaAuditDelegate` pattern), NOT on the generated Prisma client or
+ * `@nebutra/db`. Any tenant-scoped Prisma client (`getTenantDb(orgId)`)
+ * structurally satisfies it, so this package stays dependency-light.
+ */
+
+import { z } from "zod";
+import type { RolloutPersistencePort } from "../rollout-store-persistent";
+
+/**
+ * Minimal structural slice of `prisma.agentRolloutLine`. Decoupled from the
+ * generated client on purpose — only these two operations are needed.
+ */
+export interface PrismaRolloutDelegate {
+  create(args: {
+    data: {
+      tenantId: string;
+      threadId: string;
+      seq: number;
+      at: Date;
+      payload: string;
+    };
+  }): Promise<unknown>;
+  findMany(args: {
+    where: { tenantId: string; threadId: string };
+    orderBy: { seq: "asc" };
+    select: { seq: true; payload: true };
+  }): Promise<{ seq: number; payload: string }[]>;
+}
+
+/** Resolves the delegate per call so a request-scoped (RLS) client can be used. */
+export type RolloutDelegateResolver =
+  | PrismaRolloutDelegate
+  | ((tenantId: string) => PrismaRolloutDelegate | Promise<PrismaRolloutDelegate>);
+
+const recordSchema = z.object({
+  tenantId: z.string().min(1, "tenantId is required"),
+  threadId: z.string().min(1, "threadId is required"),
+  seq: z.number().int().nonnegative(),
+  at: z.string().min(1),
+  payload: z.string(),
+});
+
+const querySchema = z.object({
+  tenantId: z.string().min(1, "tenantId is required"),
+  threadId: z.string().min(1, "threadId is required"),
+});
+
+async function resolve(
+  resolver: RolloutDelegateResolver,
+  tenantId: string,
+): Promise<PrismaRolloutDelegate> {
+  return typeof resolver === "function" ? resolver(tenantId) : resolver;
+}
+
+/**
+ * Build a {@link RolloutPersistencePort} backed by Prisma.
+ *
+ * @param delegate a `PrismaRolloutDelegate`, or a resolver mapping a tenantId
+ *   to one (use the latter to obtain a per-tenant RLS client per call).
+ */
+export function createPrismaRolloutPersistence(
+  delegate: RolloutDelegateResolver,
+): RolloutPersistencePort {
+  return {
+    async put(record): Promise<void> {
+      const r = recordSchema.parse(record);
+      const at = new Date(r.at);
+      if (Number.isNaN(at.getTime())) {
+        throw new Error(`invalid timestamp: ${r.at}`);
+      }
+      const db = await resolve(delegate, r.tenantId);
+      // Fail-loud: any persistence rejection propagates to the caller.
+      await db.create({
+        data: {
+          tenantId: r.tenantId,
+          threadId: r.threadId,
+          seq: r.seq,
+          at,
+          payload: r.payload,
+        },
+      });
+    },
+
+    async list(tenantId, threadId): Promise<{ seq: number; payload: string }[]> {
+      const q = querySchema.parse({ tenantId, threadId });
+      const db = await resolve(delegate, q.tenantId);
+      const rows = await db.findMany({
+        where: { tenantId: q.tenantId, threadId: q.threadId },
+        orderBy: { seq: "asc" },
+        select: { seq: true, payload: true },
+      });
+      return rows.map((row) => ({ seq: row.seq, payload: row.payload }));
+    },
+  };
+}