@nebutra/agent-runtime 0.2.1 → 0.2.2

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 }));
-    },
-  };
-}

package/src/agent-runtime.test.ts

@@ -1,176 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import { isTurnTerminal, mergeTurnConfig, type TurnConfig } from "./model";
-import { DEFAULT_CAPABILITY_POLICY, DENIED, isApproval, resolveRuleDecision } from "./policy";
-import { METHOD_REGISTRY, resolveScope, scopeKey } from "./protocol";
-import {
-  InMemoryRolloutStore,
-  PERSISTED_OUTPUT_MAX_BYTES,
-  replay,
-  sanitizeForPersist,
-} from "./rollout";
-import {
-  assertSafePosture,
-  createHttpSandbox,
-  NoExecutorConfiguredError,
-  REFUSING_SANDBOX,
-  SandboxDelegationError,
-} from "./sandbox";
-import { ToolRegistry } from "./tools";
-
-const baseConfig: TurnConfig = {
-  model: "m",
-  provider: "p",
-  approvalPolicy: "on_request",
-  capabilityPolicy: "external_sandbox",
-};
-
-describe("model", () => {
-  it("merges overrides immutably", () => {
-    const merged = mergeTurnConfig(baseConfig, { model: "x" });
-    expect(merged.model).toBe("x");
-    expect(baseConfig.model).toBe("m");
-  });
-  it("detects terminal turn events", () => {
-    expect(
-      isTurnTerminal({
-        type: "turn.completed",
-        usage: { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0, reasoningOutputTokens: 0 },
-      }),
-    ).toBe(true);
-    expect(isTurnTerminal({ type: "turn.started" })).toBe(false);
-  });
-});
-
-describe("policy", () => {
-  it("defaults to external_sandbox posture", () => {
-    expect(DEFAULT_CAPABILITY_POLICY.kind).toBe("external_sandbox");
-  });
-  it("forbidden rule auto-rejects regardless of policy", () => {
-    expect(resolveRuleDecision("forbidden", { kind: "on_request" })).toBe("auto_reject");
-  });
-  it("prompt rule under never policy auto-rejects", () => {
-    expect(resolveRuleDecision("prompt", { kind: "never" })).toBe("auto_reject");
-  });
-  it("prompt rule under granular respects the rules gate", () => {
-    expect(
-      resolveRuleDecision("prompt", {
-        kind: "granular",
-        config: {
-          sandboxApproval: true,
-          rules: false,
-          skillApproval: false,
-          requestPermissions: false,
-          mcpElicitations: true,
-        },
-      }),
-    ).toBe("auto_reject");
-  });
-  it("denied is not an approval", () => {
-    expect(isApproval(DENIED)).toBe(false);
-    expect(isApproval({ kind: "approved_for_session" })).toBe(true);
-  });
-});
-
-describe("protocol", () => {
-  it("scope key is tenant-prefixed and thread-isolated", () => {
-    const a = resolveScope(METHOD_REGISTRY.turnStart, "t1", { threadId: "th1" });
-    const b = resolveScope(METHOD_REGISTRY.turnStart, "t2", { threadId: "th1" });
-    expect(scopeKey(a)).not.toBe(scopeKey(b)); // cross-tenant never shares a lane
-    expect(scopeKey(a)).toContain("t:t1");
-  });
-  it("thread-scoped method without threadId fails closed", () => {
-    expect(() => resolveScope(METHOD_REGISTRY.turnStart, "t1", {})).toThrow();
-  });
-});
-
-describe("rollout", () => {
-  it("caps oversized command output", () => {
-    const big = "x".repeat(PERSISTED_OUTPUT_MAX_BYTES + 100);
-    const out = sanitizeForPersist({
-      id: "1",
-      type: "command_execution",
-      command: "c",
-      aggregatedOutput: big,
-      status: "completed",
-    });
-    expect((out as { aggregatedOutput: string }).aggregatedOutput.length).toBeLessThan(big.length);
-  });
-  it("replays an append-only log into derived state, bounded by compaction", async () => {
-    const store = new InMemoryRolloutStore();
-    const at = new Date().toISOString();
-    await store.append({
-      tenantId: "t",
-      threadId: "th",
-      type: "session_meta",
-      config: baseConfig,
-      at,
-    });
-    await store.append({
-      tenantId: "t",
-      threadId: "th",
-      type: "event",
-      at,
-      event: { type: "item.completed", item: { id: "i1", type: "agent_message", text: "hi" } },
-    });
-    await store.append({
-      tenantId: "t",
-      threadId: "th",
-      type: "compacted",
-      summary: "summary",
-      droppedThrough: "i1",
-      at,
-    });
-    const proj = replay(await store.read("t", "th"));
-    expect(proj?.compactionSummary).toBe("summary");
-    expect(proj?.items).toHaveLength(0);
-  });
-});
-
-describe("sandbox", () => {
-  it("refuses execution by default (no in-process untrusted exec)", async () => {
-    await expect(
-      REFUSING_SANDBOX.exec({
-        tenantId: "t",
-        threadId: "th",
-        command: "rm -rf /",
-        capabilityPolicy: DEFAULT_CAPABILITY_POLICY,
-      }),
-    ).rejects.toBeInstanceOf(NoExecutorConfiguredError);
-  });
-  it("refuses danger_full_access without explicit opt-in", () => {
-    expect(() => assertSafePosture({ kind: "danger_full_access" })).toThrow();
-    expect(() => assertSafePosture({ kind: "danger_full_access" }, true)).not.toThrow();
-  });
-  it("surfaces a fail-closed isolator refusal as an error, never a fake result", async () => {
-    const fakeFetch = (async () =>
-      new Response(JSON.stringify({ error: "execution_refused" }), {
-        status: 403,
-      })) as unknown as typeof fetch;
-    const sandbox = createHttpSandbox("http://isolator:8020", fakeFetch);
-    await expect(
-      sandbox.exec({
-        tenantId: "org_a",
-        threadId: "th_1",
-        command: "rm -rf /",
-        capabilityPolicy: DEFAULT_CAPABILITY_POLICY,
-      }),
-    ).rejects.toBeInstanceOf(SandboxDelegationError);
-  });
-});
-
-describe("tools", () => {
-  it("validates input and dispatches with tenant context", async () => {
-    const reg = new ToolRegistry();
-    reg.register(
-      { name: "echo", description: "echo", inputSchema: z.object({ v: z.string() }) },
-      async (input: { v: string }, ctx) => `${ctx.tenantId}:${input.v}`,
-    );
-    expect(await reg.dispatch("echo", { v: "hi" }, { tenantId: "t1", threadId: "th" })).toBe(
-      "t1:hi",
-    );
-    await expect(
-      reg.dispatch("echo", { v: 1 }, { tenantId: "t1", threadId: "th" }),
-    ).rejects.toBeTruthy();
-  });
-});