@nebutra/agent-runtime 0.2.1 → 0.2.2

package/src/loop.test.ts

@@ -1,161 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import { type ApprovalGate, type ModelInvoker, type ModelRoundResult, runTurn } from "./loop";
-import type { ThreadEvent, TurnConfig } from "./model";
-import type { ReviewDecision } from "./policy";
-import { InMemoryRolloutStore } from "./rollout";
-import { ToolRegistry } from "./tools";
-
-const config: TurnConfig = {
-  model: "m",
-  provider: "p",
-  approvalPolicy: "on_request",
-  capabilityPolicy: "external_sandbox",
-};
-
-const approveAll: ApprovalGate = {
-  async request() {
-    return { kind: "approved" } as ReviewDecision;
-  },
-};
-const denyAll: ApprovalGate = {
-  async request() {
-    return { kind: "denied" } as ReviewDecision;
-  },
-};
-
-/** Model that calls `echo` once, then finishes with text. */
-function scriptedModel(): ModelInvoker {
-  let round = 0;
-  return {
-    async invoke(): Promise<ModelRoundResult> {
-      round += 1;
-      if (round === 1) {
-        return {
-          emissions: [{ kind: "tool_call", id: "tc_1", name: "echo", args: { v: "hi" } }],
-          usage: { outputTokens: 5 },
-        };
-      }
-      return { emissions: [{ kind: "text", text: "done" }] };
-    },
-  };
-}
-
-function registry(): ToolRegistry {
-  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}`,
-  );
-  return reg;
-}
-
-async function collect(gen: AsyncGenerator<ThreadEvent>): Promise<ThreadEvent[]> {
-  const out: ThreadEvent[] = [];
-  for await (const e of gen) out.push(e);
-  return out;
-}
-
-describe("loop runner", () => {
-  it("drives model → tool → result → completion and persists the rollout", async () => {
-    const store = new InMemoryRolloutStore();
-    const events = await collect(
-      runTurn("do it", {
-        tenantId: "org_a",
-        threadId: "th_1",
-        config,
-        approvalPolicy: { kind: "on_request" },
-        model: scriptedModel(),
-        tools: registry(),
-        store,
-        approvalGate: approveAll,
-        ruleEvaluator: () => "allow",
-      }),
-    );
-    const types = events.map((e) => e.type);
-    expect(types[0]).toBe("turn.started");
-    expect(types).toContain("item.completed");
-    expect(types[types.length - 1]).toBe("turn.completed");
-
-    const lines = await store.read("org_a", "th_1");
-    expect(lines.length).toBe(events.length); // every event persisted, tenant-scoped
-    expect(lines.every((l) => l.tenantId === "org_a")).toBe(true);
-  });
-
-  it("fails closed when a tool is not approved — never dispatches it", async () => {
-    let dispatched = false;
-    const reg = new ToolRegistry();
-    reg.register(
-      { name: "echo", description: "echo", inputSchema: z.object({ v: z.string() }) },
-      async () => {
-        dispatched = true;
-        return "ran";
-      },
-    );
-    const events = await collect(
-      runTurn("do it", {
-        tenantId: "org_a",
-        threadId: "th_1",
-        config,
-        approvalPolicy: { kind: "on_request" },
-        model: scriptedModel(),
-        tools: reg,
-        store: new InMemoryRolloutStore(),
-        approvalGate: denyAll,
-        ruleEvaluator: () => "prompt",
-      }),
-    );
-    expect(dispatched).toBe(false);
-    expect(events.some((e) => e.type === "item.completed" && e.item.type === "error")).toBe(true);
-    expect(events[events.length - 1]?.type).toBe("turn.completed");
-  });
-
-  it("surfaces an internal failure as turn.failed, never throws to caller", async () => {
-    const brokenModel: ModelInvoker = {
-      async invoke() {
-        throw new Error("model exploded");
-      },
-    };
-    const events = await collect(
-      runTurn("x", {
-        tenantId: "t",
-        threadId: "th",
-        config,
-        approvalPolicy: { kind: "on_request" },
-        model: brokenModel,
-        tools: new ToolRegistry(),
-        store: new InMemoryRolloutStore(),
-        approvalGate: approveAll,
-      }),
-    );
-    expect(events[events.length - 1]).toEqual({
-      type: "turn.failed",
-      error: { message: "model exploded" },
-    });
-  });
-
-  it("respects the bounded step ceiling", async () => {
-    const loopingModel: ModelInvoker = {
-      async invoke() {
-        return { emissions: [{ kind: "tool_call", id: "x", name: "echo", args: { v: "1" } }] };
-      },
-    };
-    const events = await collect(
-      runTurn("x", {
-        tenantId: "t",
-        threadId: "th",
-        config,
-        approvalPolicy: { kind: "on_request" },
-        model: loopingModel,
-        tools: registry(),
-        store: new InMemoryRolloutStore(),
-        approvalGate: approveAll,
-        ruleEvaluator: () => "allow",
-        maxSteps: 3,
-      }),
-    );
-    // 3 steps × 1 tool item + turn.started + turn.completed
-    expect(events.filter((e) => e.type === "item.completed")).toHaveLength(3);
-    expect(events[events.length - 1]?.type).toBe("turn.completed");
-  });
-});

package/src/loop.ts

@@ -1,211 +0,0 @@
-/**
- * Agent loop runner (WRAP — the turn engine).
- *
- * Faithful re-expression of the upstream loop: a turn is
- * `loop { model_call → emit items → execute tools → feed results back }`
- * until the model stops requesting tools or a bounded step ceiling is hit.
- * Single-threaded (Cognition teaching: shared context, no conflicting
- * sub-agent decisions). Every item is appended to the tenant-scoped rollout
- * as it reaches a terminal state, so the turn is resumable by replay.
- *
- * The model call is abstracted behind {@link ModelInvoker} so this WRAPs an
- * existing model stack (e.g. `@nebutra/agents`) rather than re-porting
- * provider/routing/fallback. No untrusted code runs here — command items are
- * dispatched through the tool registry / external-sandbox seam.
- */
-
-import type { AgentMessageItem, ThreadEvent, ThreadItem, TurnConfig, TurnUsage } from "./model";
-import {
-  type ApprovalPolicy,
-  DENIED,
-  isApproval,
-  type ReviewDecision,
-  type RuleDecision,
-  resolveRuleDecision,
-} from "./policy";
-import type { ServerRequest } from "./protocol";
-import { type RolloutLine, type RolloutStore, sanitizeForPersist } from "./rollout";
-import type { RuntimeToolRegistry, ToolDispatchContext } from "./tools";
-
-/** A single thing the model emitted in one round. */
-export type ModelEmission =
-  | { readonly kind: "text"; readonly text: string }
-  | {
-      readonly kind: "tool_call";
-      readonly id: string;
-      readonly name: string;
-      readonly args: unknown;
-    };
-
-export interface ModelRoundResult {
-  readonly emissions: readonly ModelEmission[];
-  readonly usage?: Partial<TurnUsage>;
-}
-
-export interface ModelRoundRequest {
-  readonly config: TurnConfig;
-  /** Running transcript: user input, agent text, and tool results. */
-  readonly history: readonly { readonly role: string; readonly content: string }[];
-  readonly toolNames: readonly string[];
-}
-
-/** Abstracts the model stack — implement over `@nebutra/agents`, etc. */
-export interface ModelInvoker {
-  invoke(request: ModelRoundRequest): Promise<ModelRoundResult>;
-}
-
-/** Server-initiated approval transport (see {@link ServerRequest}). */
-export interface ApprovalGate {
-  request(serverRequest: ServerRequest): Promise<ReviewDecision>;
-}
-
-/** Classifies a tool call into a static rule decision before approval. */
-export type RuleEvaluator = (toolName: string, args: unknown) => RuleDecision;
-
-export interface RunTurnDeps {
-  readonly tenantId: string;
-  readonly threadId: string;
-  readonly config: TurnConfig;
-  readonly approvalPolicy: ApprovalPolicy;
-  readonly model: ModelInvoker;
-  readonly tools: RuntimeToolRegistry;
-  readonly store: RolloutStore;
-  readonly approvalGate: ApprovalGate;
-  /** Defaults to: everything requires a prompt (safe). */
-  readonly ruleEvaluator?: RuleEvaluator;
-  /** Bounded steps (parity with upstream step ceiling). Default 20. */
-  readonly maxSteps?: number;
-}
-
-const DEFAULT_MAX_STEPS = 20;
-const requirePrompt: RuleEvaluator = () => "prompt";
-
-function newId(prefix: string): string {
-  return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`}`;
-}
-
-/**
- * Drive one turn to completion. Yields the {@link ThreadEvent} stream and
- * appends each terminal item + the turn outcome to the rollout store.
- * Never throws to the caller — failures surface as a `turn.failed` event.
- */
-export async function* runTurn(userInput: string, deps: RunTurnDeps): AsyncGenerator<ThreadEvent> {
-  const at = () => new Date().toISOString();
-  const ruleEvaluator = deps.ruleEvaluator ?? requirePrompt;
-  const maxSteps = deps.maxSteps ?? DEFAULT_MAX_STEPS;
-  const ctx: ToolDispatchContext = { tenantId: deps.tenantId, threadId: deps.threadId };
-
-  const append = async (line: RolloutLine): Promise<void> => deps.store.append(line);
-  const event = async (e: ThreadEvent): Promise<ThreadEvent> => {
-    await append({
-      tenantId: deps.tenantId,
-      threadId: deps.threadId,
-      type: "event",
-      event:
-        e.type === "item.completed"
-          ? { type: "item.completed", item: sanitizeForPersist(e.item) }
-          : e,
-      at: at(),
-    });
-    return e;
-  };
-
-  yield await event({ type: "turn.started" });
-
-  const history: { role: string; content: string }[] = [{ role: "user", content: userInput }];
-  let usage: TurnUsage = {
-    inputTokens: 0,
-    cachedInputTokens: 0,
-    outputTokens: 0,
-    reasoningOutputTokens: 0,
-  };
-
-  try {
-    for (let step = 0; step < maxSteps; step++) {
-      const round = await deps.model.invoke({
-        config: deps.config,
-        history,
-        toolNames: deps.tools.list().map((t) => t.definition.name),
-      });
-      if (round.usage) {
-        const u = round.usage;
-        usage = {
-          inputTokens: usage.inputTokens + (u.inputTokens ?? 0),
-          cachedInputTokens: usage.cachedInputTokens + (u.cachedInputTokens ?? 0),
-          outputTokens: usage.outputTokens + (u.outputTokens ?? 0),
-          reasoningOutputTokens: usage.reasoningOutputTokens + (u.reasoningOutputTokens ?? 0),
-        };
-      }
-
-      const toolCalls = round.emissions.filter(
-        (e): e is Extract<ModelEmission, { kind: "tool_call" }> => e.kind === "tool_call",
-      );
-
-      for (const e of round.emissions) {
-        if (e.kind !== "text") continue;
-        const item: AgentMessageItem = { id: newId("msg"), type: "agent_message", text: e.text };
-        history.push({ role: "assistant", content: e.text });
-        yield await event({ type: "item.completed", item });
-      }
-
-      if (toolCalls.length === 0) break; // model is done
-
-      for (const call of toolCalls) {
-        const decision = await gateToolCall(call.name, call.args, deps, ruleEvaluator);
-        if (!isApproval(decision)) {
-          const failed: ThreadItem = {
-            id: call.id,
-            type: "error",
-            message: `tool '${call.name}' not approved (${decision.kind})`,
-          };
-          history.push({ role: "tool", content: `DENIED: ${call.name}` });
-          yield await event({ type: "item.completed", item: failed });
-          continue;
-        }
-        try {
-          const output = await deps.tools.dispatch(call.name, call.args, ctx);
-          const item: ThreadItem = {
-            id: call.id,
-            type: "mcp_tool_call",
-            server: "native",
-            tool: call.name,
-            arguments: call.args,
-            result: { content: output },
-            status: "completed",
-          };
-          history.push({ role: "tool", content: JSON.stringify(output) });
-          yield await event({ type: "item.completed", item });
-        } catch (err) {
-          const message = err instanceof Error ? err.message : String(err);
-          history.push({ role: "tool", content: `ERROR: ${message}` });
-          yield await event({
-            type: "item.completed",
-            item: { id: call.id, type: "error", message },
-          });
-        }
-      }
-    }
-
-    yield await event({ type: "turn.completed", usage });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    yield await event({ type: "turn.failed", error: { message } });
-  }
-}
-
-/** Resolve a tool call's approval, raising a server-initiated request if asked. */
-async function gateToolCall(
-  name: string,
-  args: unknown,
-  deps: RunTurnDeps,
-  ruleEvaluator: RuleEvaluator,
-): Promise<ReviewDecision> {
-  const outcome = resolveRuleDecision(ruleEvaluator(name, args), deps.approvalPolicy);
-  if (outcome === "auto_allow") return { kind: "approved" };
-  if (outcome === "auto_reject") return DENIED;
-  return deps.approvalGate.request({
-    type: "permissions.request_approval",
-    requestId: newId("appr"),
-    summary: `tool '${name}'`,
-  });
-}

package/src/mcp-bridge.test.ts

@@ -1,165 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { z } from "zod";
-
-import { activateMcpTools, type McpServerCatalogPort } from "./mcp-bridge";
-import { type McpClientLike, type ToolDefinition, ToolRegistry } from "./tools";
-
-function def(name: string): ToolDefinition {
-  return {
-    name,
-    description: `tool ${name}`,
-    inputSchema: z.object({ q: z.string() }),
-  };
-}
-
-/** Catalog fake: tenant- and plan-scoped tool listings. */
-function fakeCatalog(
-  byTenant: Record<
-    string,
-    {
-      free: { server: string; definition: ToolDefinition }[];
-      pro: { server: string; definition: ToolDefinition }[];
-    }
-  >,
-): McpServerCatalogPort {
-  return {
-    async listTools(ctx) {
-      const t = byTenant[ctx.tenantId];
-      if (!t) return [];
-      return ctx.plan === "pro" ? t.pro : t.free;
-    },
-  };
-}
-
-function fakeClient(): McpClientLike & {
-  calls: { name: string; args: unknown; tenantId: string }[];
-} {
-  const calls: { name: string; args: unknown; tenantId: string }[] = [];
-  return {
-    calls,
-    async executeTool(name, args, ctx) {
-      calls.push({ name, args, tenantId: ctx.tenantId });
-      return { ok: true, name };
-    },
-  };
-}
-
-describe("activateMcpTools", () => {
-  it("registers tenant-scoped tools dispatchable through the registry with the right tenantId", async () => {
-    const registry = new ToolRegistry();
-    const catalog = fakeCatalog({
-      org_a: {
-        free: [{ server: "weather", definition: def("get_weather") }],
-        pro: [],
-      },
-    });
-    const client = fakeClient();
-
-    const res = await activateMcpTools(registry, catalog, client, { tenantId: "org_a" });
-
-    expect(res.registered).toEqual(["get_weather"]);
-    expect(res.skipped).toEqual([]);
-    expect(registry.list().map((r) => r.definition.name)).toEqual(["get_weather"]);
-
-    const out = await registry.dispatch(
-      "get_weather",
-      { q: "NYC" },
-      {
-        tenantId: "org_a",
-        threadId: "t1",
-      },
-    );
-    expect(out).toEqual({ ok: true, name: "get_weather" });
-    expect(client.calls).toHaveLength(1);
-    expect(client.calls[0]).toMatchObject({
-      name: "get_weather",
-      tenantId: "org_a",
-      args: { q: "NYC" },
-    });
-  });
-
-  it("gates by plan — low-plan tenant gets fewer tools", async () => {
-    const catalog = fakeCatalog({
-      org_a: {
-        free: [{ server: "s", definition: def("basic") }],
-        pro: [
-          { server: "s", definition: def("basic") },
-          { server: "s", definition: def("premium") },
-        ],
-      },
-    });
-    const client = fakeClient();
-
-    const freeReg = new ToolRegistry();
-    const free = await activateMcpTools(freeReg, catalog, client, {
-      tenantId: "org_a",
-      plan: "free",
-    });
-    expect(free.registered).toEqual(["basic"]);
-
-    const proReg = new ToolRegistry();
-    const pro = await activateMcpTools(proReg, catalog, client, { tenantId: "org_a", plan: "pro" });
-    expect(pro.registered).toEqual(["basic", "premium"]);
-  });
-
-  it("skips a duplicate-name tool instead of throwing", async () => {
-    const registry = new ToolRegistry();
-    registry.register(def("get_weather"), async () => ({ native: true }));
-
-    const catalog = fakeCatalog({
-      org_a: {
-        free: [
-          { server: "weather", definition: def("get_weather") },
-          { server: "weather", definition: def("get_forecast") },
-        ],
-        pro: [],
-      },
-    });
-
-    const res = await activateMcpTools(registry, catalog, fakeClient(), { tenantId: "org_a" });
-
-    expect(res.registered).toEqual(["get_forecast"]);
-    expect(res.skipped).toEqual(["get_weather"]);
-    expect(registry.list()).toHaveLength(2);
-  });
-
-  it("fails closed on empty tenantId before touching the catalog", async () => {
-    const catalog = fakeCatalog({});
-    const spy = vi.spyOn(catalog, "listTools");
-    await expect(
-      activateMcpTools(new ToolRegistry(), catalog, fakeClient(), { tenantId: "" }),
-    ).rejects.toThrow(/tenantId/i);
-    expect(spy).not.toHaveBeenCalled();
-  });
-
-  it("fails closed on whitespace-only tenantId", async () => {
-    await expect(
-      activateMcpTools(new ToolRegistry(), fakeCatalog({}), fakeClient(), { tenantId: "   " }),
-    ).rejects.toThrow(/tenantId/i);
-  });
-
-  it("isolates tenants — tenant A never sees tenant B's catalog", async () => {
-    const catalog = fakeCatalog({
-      org_a: { free: [{ server: "s", definition: def("a_tool") }], pro: [] },
-      org_b: { free: [{ server: "s", definition: def("b_tool") }], pro: [] },
-    });
-    const client = fakeClient();
-
-    const regA = new ToolRegistry();
-    const a = await activateMcpTools(regA, catalog, client, { tenantId: "org_a" });
-    expect(a.registered).toEqual(["a_tool"]);
-    expect(regA.list().map((r) => r.definition.name)).not.toContain("b_tool");
-
-    await regA.dispatch("a_tool", { q: "x" }, { tenantId: "org_a", threadId: "t1" });
-    expect(client.calls.every((c) => c.tenantId === "org_a")).toBe(true);
-  });
-
-  it("returns mcp origin so adapted tools are provenance-tagged", async () => {
-    const registry = new ToolRegistry();
-    const catalog = fakeCatalog({
-      org_a: { free: [{ server: "weather", definition: def("get_weather") }], pro: [] },
-    });
-    await activateMcpTools(registry, catalog, fakeClient(), { tenantId: "org_a" });
-    expect(registry.list()[0]?.origin).toEqual({ kind: "mcp", server: "weather" });
-  });
-});

package/src/mcp-bridge.ts

@@ -1,81 +0,0 @@
-/**
- * MCP activation bridge (WRAP — capability #9, activation seam).
- *
- * Concrete bridge that registers external MCP-server tools into the runtime's
- * uniform tool model. It does NOT import `@nebutra/mcp` (WIP / do-not-import):
- * instead it defines minimal injectable ports so callers wire `@nebutra/mcp`
- * (`serverRegistry` + `mcpClient`) without this package taking a hard dep.
- *
- * Tenant-scoped by construction: the catalog port is always queried with the
- * caller's `{ tenantId, plan }`, so a tenant only ever sees its own MCP
- * servers/tools. Fail-closed on missing tenant.
- */
-
-import { z } from "zod";
-
-import {
-  adaptMcpTool,
-  type McpClientLike,
-  type RuntimeToolRegistry,
-  type ToolDefinition,
-} from "./tools";
-
-/**
- * Port over an MCP server catalog (satisfied by `@nebutra/mcp`'s
- * `serverRegistry` + plan middleware). Returns only the tools visible to the
- * given tenant/plan — visibility/plan-gating is the port's responsibility.
- */
-export interface McpServerCatalogPort {
-  listTools(ctx: {
-    tenantId: string;
-    plan?: string;
-  }): Promise<{ server: string; definition: ToolDefinition }[]>;
-}
-
-const ctxSchema = z.object({
-  tenantId: z.string().trim().min(1, "tenantId is required (fail-closed)"),
-  plan: z.string().min(1).optional(),
-});
-
-export interface ActivateMcpToolsResult {
-  /** Tool names newly registered into the registry, in catalog order. */
-  readonly registered: readonly string[];
-  /** Tool names skipped because the name was already registered. */
-  readonly skipped: readonly string[];
-}
-
-/**
- * List the tenant/plan-visible MCP tools, adapt each via {@link adaptMcpTool},
- * and register them into the {@link RuntimeToolRegistry}. A tool whose name is already
- * registered is skipped (reported, never thrown). Empty/blank tenantId fails
- * closed before any catalog call.
- */
-export async function activateMcpTools(
-  registry: RuntimeToolRegistry,
-  catalog: McpServerCatalogPort,
-  client: McpClientLike,
-  ctx: { tenantId: string; plan?: string },
-): Promise<ActivateMcpToolsResult> {
-  const scope = ctxSchema.parse(ctx);
-
-  const entries = await catalog.listTools(
-    scope.plan === undefined
-      ? { tenantId: scope.tenantId }
-      : { tenantId: scope.tenantId, plan: scope.plan },
-  );
-
-  const registered: string[] = [];
-  const skipped: string[] = [];
-
-  for (const { server, definition } of entries) {
-    if (registry.list().some((r) => r.definition.name === definition.name)) {
-      skipped.push(definition.name);
-      continue;
-    }
-    const adapted = adaptMcpTool(server, definition, client);
-    registry.register(adapted.definition, adapted.handler, adapted.origin);
-    registered.push(definition.name);
-  }
-
-  return { registered, skipped };
-}