@nebutra/agent-runtime 0.2.1 → 2.0.0

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

@@ -1,213 +0,0 @@
-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

@@ -1,188 +0,0 @@
-/**
- * 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

@@ -1,153 +0,0 @@
-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

@@ -1,104 +0,0 @@
-/**
- * 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 }));
-    },
-  };
-}