@nebutra/agent-runtime 0.2.0 → 0.2.2

package/src/adapters/dispatcher-sse.ts

@@ -1,222 +0,0 @@
-/**
- * Runtime-agnostic SSE / HTTP transport binding for `ProtocolDispatcher`.
- *
- * Built on Web-standard primitives ONLY — `Request`, `Response`,
- * `ReadableStream`, `TextEncoder`, `AbortSignal`. There is no Hono / Express /
- * `node:http` dependency, so the same code runs unchanged on edge runtimes,
- * Cloudflare Workers, Deno, Bun, and Node (>=18, where these globals exist).
- *
- * Design goals:
- *  - Pure functions returning Web objects; nothing is mutated in place.
- *  - The dispatcher already fails closed on a missing `tenantId` (its
- *    `requestEnvelopeSchema` makes `tenantId` mandatory). This binding does
- *    not re-implement that policy — it faithfully relays the JSON-RPC error.
- *  - Never throw across the transport boundary and never leak a stack trace:
- *    a malformed body becomes a well-formed JSON-RPC parse error.
- *
- * Wire framing (SSE): each event is emitted as
- *   `event: <ThreadEvent.type>\n` + `data: <JSON(event)>\n\n`
- */
-
-import type { ProtocolDispatcher } from "../dispatcher";
-import type { ThreadEvent } from "../model";
-import type { NotificationName } from "../protocol";
-
-// ── JSON-RPC constants ───────────────────────────────────────────────────────
-
-/** Spec code for "Parse error" — the request body was not valid JSON. */
-const ERR_PARSE = -32700;
-
-const JSON_HEADERS: Readonly<Record<string, string>> = {
-  "content-type": "application/json; charset=utf-8",
-};
-
-/** A self-contained JSON-RPC failure envelope (used only for parse errors;
- *  every other failure path is produced by the dispatcher itself). */
-function parseErrorEnvelope(message: string): {
-  readonly jsonrpc: "2.0";
-  readonly id: null;
-  readonly error: { readonly code: number; readonly message: string };
-} {
-  return { jsonrpc: "2.0", id: null, error: { code: ERR_PARSE, message } };
-}
-
-function jsonResponse(payload: unknown, status: number): Response {
-  return new Response(JSON.stringify(payload), { status, headers: { ...JSON_HEADERS } });
-}
-
-// ── HTTP / JSON-RPC handler ──────────────────────────────────────────────────
-
-/**
- * Build a Web-standard request handler bound to a dispatcher.
- *
- * Contract:
- *  - Unparseable body → `400` with a JSON-RPC parse-error envelope.
- *  - Any parseable body (incl. missing tenant / unknown method / handler
- *    failure) → `200` with the dispatcher's own JSON-RPC envelope. The HTTP
- *    layer stays `200` for business-level JSON-RPC errors per JSON-RPC-over-
- *    HTTP convention; the error lives in the envelope, not the status line.
- *  - The returned function never throws and never emits a 500-with-stack.
- */
-export function createRpcHandler(
-  dispatcher: ProtocolDispatcher,
-): (request: Request) => Promise<Response> {
-  return async (request: Request): Promise<Response> => {
-    let raw: unknown;
-    try {
-      raw = await request.json();
-    } catch {
-      return jsonResponse(parseErrorEnvelope("Request body is not valid JSON"), 400);
-    }
-
-    // `dispatch` is documented to never throw; the try/catch is defence in
-    // depth so the transport boundary is total under any future change.
-    try {
-      const envelope = await dispatcher.dispatch(raw);
-      return jsonResponse(envelope, 200);
-    } catch {
-      return jsonResponse(parseErrorEnvelope("Dispatcher failure"), 400);
-    }
-  };
-}
-
-// ── SSE streaming ────────────────────────────────────────────────────────────
-
-export interface SseOptions {
-  /** Cancels the stream cleanly; closing the consumer also cancels it. */
-  readonly signal?: AbortSignal;
-}
-
-/** Encode one `ThreadEvent` as a single SSE frame. */
-function frame(event: ThreadEvent): string {
-  return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
-}
-
-/** Encode a terminal transport-level error as an `event: error` SSE frame. */
-function errorFrame(message: string): string {
-  return `event: error\ndata: ${JSON.stringify({ type: "error", message })}\n\n`;
-}
-
-/**
- * Adapt an async `ThreadEvent` stream into a Web-standard
- * `text/event-stream` `Response`.
- *
- * Guarantees:
- *  - Incremental flush: each event is enqueued as soon as it is produced.
- *  - Clean termination: the stream closes when the iterable is exhausted.
- *  - Error surfacing: an iterable error is emitted as a final
- *    `event: error` frame, then the stream closes (it never hangs).
- *  - Cancellation: an aborted `signal` (or a cancelled reader) stops
- *    pulling from the source and releases its iterator.
- */
-export function sseResponse(stream: AsyncIterable<ThreadEvent>, opts?: SseOptions): Response {
-  const encoder = new TextEncoder();
-  const signal = opts?.signal;
-
-  const body = new ReadableStream<Uint8Array>({
-    async start(controller) {
-      const iterator = stream[Symbol.asyncIterator]();
-
-      const onAbort = () => {
-        void iterator.return?.(undefined);
-      };
-      if (signal) {
-        if (signal.aborted) {
-          await iterator.return?.(undefined);
-          controller.close();
-          return;
-        }
-        signal.addEventListener("abort", onAbort, { once: true });
-      }
-
-      try {
-        for (;;) {
-          if (signal?.aborted) break;
-          const next = await iterator.next();
-          if (next.done) break;
-          controller.enqueue(encoder.encode(frame(next.value)));
-        }
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Stream error";
-        controller.enqueue(encoder.encode(errorFrame(message)));
-      } finally {
-        signal?.removeEventListener("abort", onAbort);
-        controller.close();
-      }
-    },
-    cancel() {
-      // Consumer hung up: best-effort release of the upstream iterator.
-      void stream[Symbol.asyncIterator]().return?.(undefined);
-    },
-  });
-
-  return new Response(body, {
-    status: 200,
-    headers: {
-      "content-type": "text/event-stream; charset=utf-8",
-      "cache-control": "no-cache, no-transform",
-      connection: "keep-alive",
-    },
-  });
-}
-
-// ── Notification → async-iterable bridge ─────────────────────────────────────
-
-export interface NotificationFrame {
-  readonly name: NotificationName;
-  readonly payload: unknown;
-}
-
-/**
- * Bridge `dispatcher.onNotification` (a push listener API) into a pull-based
- * `AsyncIterable`. A bounded backlog buffers events that arrive between
- * `next()` calls; pending readers are resolved immediately when an event
- * arrives. Calling `return()` (or breaking a `for await`) unsubscribes every
- * underlying listener — no leaks, fail-closed teardown.
- */
-export function subscribeNotifications(
-  dispatcher: ProtocolDispatcher,
-  names: readonly NotificationName[],
-): AsyncIterable<NotificationFrame> {
-  return {
-    [Symbol.asyncIterator](): AsyncIterator<NotificationFrame> {
-      const backlog: NotificationFrame[] = [];
-      const waiters: Array<(r: IteratorResult<NotificationFrame>) => void> = [];
-      let closed = false;
-
-      const unsubscribers = names.map((name) =>
-        dispatcher.onNotification(name, (payload) => {
-          if (closed) return;
-          const value: NotificationFrame = { name, payload };
-          const waiter = waiters.shift();
-          if (waiter) waiter({ value, done: false });
-          else backlog.push(value);
-        }),
-      );
-
-      const teardown = (): void => {
-        if (closed) return;
-        closed = true;
-        for (const off of unsubscribers) off();
-        let waiter = waiters.shift();
-        while (waiter) {
-          waiter({ value: undefined, done: true });
-          waiter = waiters.shift();
-        }
-      };
-
-      return {
-        next(): Promise<IteratorResult<NotificationFrame>> {
-          const buffered = backlog.shift();
-          if (buffered) return Promise.resolve({ value: buffered, done: false });
-          if (closed) return Promise.resolve({ value: undefined, done: true });
-          return new Promise((resolve) => waiters.push(resolve));
-        },
-        return(): Promise<IteratorResult<NotificationFrame>> {
-          teardown();
-          return Promise.resolve({ value: undefined, done: true });
-        },
-      };
-    },
-  };
-}

package/src/adapters/index.ts

@@ -1,18 +0,0 @@
-/**
- * @nebutra/agent-runtime/adapters — concrete, reusable port adapters.
- *
- * The root runtime keeps its pure grammar and injectable ports. These subpath
- * exports supply concrete wirings so apps/backends reuse them instead of
- * re-implementing glue:
- *
- *  - `./mcp-catalog`    — McpServerCatalogPort + McpClientLike over @nebutra/mcp
- *  - `./dispatcher-sse` — runtime-agnostic SSE transport for ProtocolDispatcher
- *
- * The durable rollout-store backend adapter is pending a governance decision
- * (a correct system-of-record needs a fail-loud datastore; @nebutra/audit's
- * log() swallows transient failures and is not suitable as source-of-truth).
- */
-
-export * from "./dispatcher-sse.js";
-export * from "./mcp-catalog.js";
-export * from "./prisma-rollout.js";

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