@nebutra/agent-runtime 0.2.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@nebutra/agent-runtime",
+  "version": "0.2.0",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "wip",
+    "productionReady": false,
+    "requires": [
+      "@nebutra/agents for model execution",
+      "@nebutra/tenant for tenant scoping"
+    ],
+    "gaps": [
+      "Track-B kernel sidecar transport not yet wired",
+      "Durable-turn queue binding is interface-only",
+      "Rollout store backed by in-memory reference impl only"
+    ],
+    "featureId": "agent-runtime",
+    "category": "ai",
+    "summary": "Multi-tenant agent-runtime grammar: thread/turn/item model, approval+capability policy, tool/MCP abstraction, event-sourced rollout, external-sandbox delegation seam"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./model": "./src/model.ts",
+    "./protocol": "./src/protocol.ts",
+    "./policy": "./src/policy.ts",
+    "./tools": "./src/tools.ts",
+    "./rollout": "./src/rollout.ts",
+    "./sandbox": "./src/sandbox.ts",
+    "./adapters": "./src/adapters/index.ts",
+    "./adapters/mcp-catalog": "./src/adapters/mcp-catalog.ts",
+    "./adapters/dispatcher-sse": "./src/adapters/dispatcher-sse.ts",
+    "./adapters/prisma-rollout": "./src/adapters/prisma-rollout.ts"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@nebutra/mcp": "0.1.1"
+  },
+  "peerDependenciesMeta": {
+    "@nebutra/mcp": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "@nebutra/mcp": "0.1.1"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/agent-runtime#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/agent-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/adapters/dispatcher-sse.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Web-standard transport binding tests — no server, no framework.
+ *
+ * Every test constructs a `new Request(...)` and inspects a `Response` via
+ * Web-standard APIs only (`response.text()`, `response.body!.getReader()`).
+ */
+
+import { describe, expect, it } from "vitest";
+import { ProtocolDispatcher } from "../dispatcher";
+import type { ThreadEvent } from "../model";
+import { createRpcHandler, sseResponse, subscribeNotifications } from "./dispatcher-sse.js";
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** A dispatcher with one echo handler bound to a real registered method. */
+function freshDispatcher(): ProtocolDispatcher {
+  const d = new ProtocolDispatcher();
+  // `thread/start` is in the method registry; echo its params back.
+  d.register("thread/start", async (params) => ({ echoed: params }));
+  return d;
+}
+
+function jsonRequest(body: unknown): Request {
+  return new Request("https://edge.test/rpc", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: typeof body === "string" ? body : JSON.stringify(body),
+  });
+}
+
+/** Drain an SSE Response body into its raw decoded text. */
+async function drainSse(res: Response): Promise<string> {
+  if (!res.body) throw new Error("SSE response body is missing");
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    out += decoder.decode(value, { stream: true });
+  }
+  out += decoder.decode();
+  return out;
+}
+
+async function* eventsOf(...events: ThreadEvent[]): AsyncIterable<ThreadEvent> {
+  for (const e of events) yield e;
+}
+
+// ── createRpcHandler ─────────────────────────────────────────────────────────
+
+describe("createRpcHandler", () => {
+  it("returns a JSON-RPC success envelope (200, application/json) on happy path", async () => {
+    const handler = createRpcHandler(freshDispatcher());
+    const res = await handler(
+      jsonRequest({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "thread/start",
+        tenantId: "org_123",
+        params: { hello: "world" },
+      }),
+    );
+
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+    const body = await res.json();
+    expect(body).toEqual({
+      jsonrpc: "2.0",
+      id: 1,
+      result: { echoed: { hello: "world" } },
+    });
+  });
+
+  it("returns a well-formed JSON-RPC parse error (400) on malformed JSON — never throws", async () => {
+    const handler = createRpcHandler(freshDispatcher());
+    const res = await handler(jsonRequest("{ not valid json"));
+
+    expect(res.status).toBe(400);
+    expect(res.headers.get("content-type")).toContain("application/json");
+    const body = await res.json();
+    expect(body.jsonrpc).toBe("2.0");
+    expect(body.id).toBeNull();
+    expect(body.error.code).toBe(-32700);
+    expect(typeof body.error.message).toBe("string");
+  });
+
+  it("fails closed on a missing-tenant envelope (200 JSON-RPC business error)", async () => {
+    const handler = createRpcHandler(freshDispatcher());
+    const res = await handler(
+      jsonRequest({ jsonrpc: "2.0", id: 7, method: "thread/start", params: {} }),
+    );
+
+    // Envelope was parseable JSON → 200, but dispatch fails closed.
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.jsonrpc).toBe("2.0");
+    expect(body.error).toBeDefined();
+    expect(body.error.code).toBe(-32600);
+  });
+
+  it("returns method-not-found JSON-RPC error for an unknown method", async () => {
+    const handler = createRpcHandler(freshDispatcher());
+    const res = await handler(
+      jsonRequest({ jsonrpc: "2.0", id: 9, method: "totally/unknown", tenantId: "org_1" }),
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.error.code).toBe(-32601);
+  });
+});
+
+// ── sseResponse ──────────────────────────────────────────────────────────────
+
+describe("sseResponse", () => {
+  it("sets text/event-stream + no-cache headers", () => {
+    const res = sseResponse(eventsOf({ type: "turn.started" }));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+    expect(res.headers.get("cache-control")).toContain("no-cache");
+  });
+
+  it("streams multiple events in order with correct SSE framing", async () => {
+    const stream = eventsOf(
+      { type: "thread.started", threadId: "t1" },
+      { type: "turn.started" },
+      {
+        type: "turn.completed",
+        usage: { inputTokens: 1, cachedInputTokens: 0, outputTokens: 2, reasoningOutputTokens: 0 },
+      },
+    );
+    const text = await drainSse(sseResponse(stream));
+
+    const frames = text.split("\n\n").filter(Boolean);
+    expect(frames).toHaveLength(3);
+    expect(frames[0]).toBe(
+      `event: thread.started\ndata: ${JSON.stringify({ type: "thread.started", threadId: "t1" })}`,
+    );
+    expect(frames[1]).toBe(
+      `event: turn.started\ndata: ${JSON.stringify({ type: "turn.started" })}`,
+    );
+    expect((frames[2] ?? "").startsWith("event: turn.completed\n")).toBe(true);
+  });
+
+  it("surfaces a mid-stream iterable error as a final `event: error` frame then closes", async () => {
+    async function* boom(): AsyncIterable<ThreadEvent> {
+      yield { type: "turn.started" };
+      throw new Error("upstream exploded");
+    }
+    const text = await drainSse(sseResponse(boom()));
+    const frames = text.split("\n\n").filter(Boolean);
+
+    expect(frames[0]).toBe(
+      `event: turn.started\ndata: ${JSON.stringify({ type: "turn.started" })}`,
+    );
+    const last = frames.at(-1) ?? "";
+    expect(last.startsWith("event: error\n")).toBe(true);
+    expect(last).toContain("upstream exploded");
+  });
+
+  it("cancels promptly when the provided AbortSignal aborts", async () => {
+    const ac = new AbortController();
+    let produced = 0;
+    async function* infinite(): AsyncIterable<ThreadEvent> {
+      for (;;) {
+        produced += 1;
+        yield { type: "turn.started" };
+        if (produced === 2) ac.abort();
+        await new Promise((r) => setTimeout(r, 1));
+      }
+    }
+    const res = sseResponse(infinite(), { signal: ac.signal });
+    const text = await drainSse(res);
+    // Stream terminated; did not run forever.
+    expect(text.length).toBeGreaterThan(0);
+    expect(produced).toBeLessThan(50);
+  });
+
+  it("does not throw when aborted before the first read", async () => {
+    const ac = new AbortController();
+    ac.abort();
+    const res = sseResponse(eventsOf({ type: "turn.started" }), { signal: ac.signal });
+    const text = await drainSse(res);
+    expect(typeof text).toBe("string");
+  });
+});
+
+// ── subscribeNotifications ───────────────────────────────────────────────────
+
+describe("subscribeNotifications", () => {
+  it("bridges dispatcher notifications into an async iterable", async () => {
+    const d = new ProtocolDispatcher();
+    const iter = subscribeNotifications(d, ["turn/started", "turn/completed"]);
+    const reader = iter[Symbol.asyncIterator]();
+
+    queueMicrotask(() => {
+      d.emitNotification("turn/started", { a: 1 });
+      d.emitNotification("turn/completed", { b: 2 });
+    });
+
+    const first = await reader.next();
+    const second = await reader.next();
+    expect(first.value).toEqual({ name: "turn/started", payload: { a: 1 } });
+    expect(second.value).toEqual({ name: "turn/completed", payload: { b: 2 } });
+
+    await reader.return?.();
+  });
+
+  it("stops yielding after return() unsubscribes", async () => {
+    const d = new ProtocolDispatcher();
+    const iter = subscribeNotifications(d, ["turn/started"]);
+    const reader = iter[Symbol.asyncIterator]();
+    const done = await reader.return?.();
+    expect(done?.done).toBe(true);
+    // Emitting after teardown must not throw or buffer indefinitely.
+    expect(() => d.emitNotification("turn/started", {})).not.toThrow();
+  });
+});

package/src/adapters/dispatcher-sse.ts

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

@@ -0,0 +1,18 @@
+/**
+ * @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";