@nebutra/agent-runtime 0.2.1 → 2.0.0

package/src/dispatcher.ts

@@ -1,189 +0,0 @@
-/**
- * Transport-agnostic JSON-RPC dispatcher for the app-server protocol.
- *
- * Pure and testable: no sockets. WS/SSE/stdio adapters wrap this dispatcher
- * and are intentionally out of scope here.
- *
- * Faithful concurrency model (see `protocol.ts`): requests sharing a
- * `scopeKey` are serialized FIFO; distinct scope keys run concurrently.
- * Because every scope is tenant-prefixed, cross-tenant requests can never
- * share a serial lane (fail-closed multi-tenancy by construction).
- */
-
-import {
-  METHOD_REGISTRY,
-  type MethodSpec,
-  NOTIFICATIONS,
-  type NotificationName,
-  requestEnvelopeSchema,
-  resolveScope,
-  type SerializationScope,
-  scopeKey,
-} from "./protocol";
-
-// ── Public types ─────────────────────────────────────────────────────────────
-
-export type MethodHandler = (params: unknown, scope: SerializationScope) => Promise<unknown>;
-
-export type NotificationListener = (payload: unknown) => void;
-
-interface JsonRpcSuccess {
-  readonly jsonrpc: "2.0";
-  readonly id: string | number | null;
-  readonly result: unknown;
-}
-
-interface JsonRpcFailure {
-  readonly jsonrpc: "2.0";
-  readonly id: string | number | null;
-  readonly error: { readonly code: number; readonly message: string };
-}
-
-export type JsonRpcResponse = JsonRpcSuccess | JsonRpcFailure;
-
-// ── JSON-RPC error codes (spec-aligned) ──────────────────────────────────────
-
-const ERR_INVALID_REQUEST = -32600;
-const ERR_METHOD_NOT_FOUND = -32601;
-const ERR_INVALID_PARAMS = -32602;
-const ERR_INTERNAL = -32603;
-
-function success(id: string | number | null, result: unknown): JsonRpcSuccess {
-  return { jsonrpc: "2.0", id, result };
-}
-
-function failure(id: string | number | null, code: number, message: string): JsonRpcFailure {
-  return { jsonrpc: "2.0", id, error: { code, message } };
-}
-
-const NOTIFICATION_NAMES: ReadonlySet<string> = new Set(NOTIFICATIONS);
-
-const METHOD_SPEC_BY_WIRE: ReadonlyMap<string, MethodSpec> = new Map(
-  Object.values(METHOD_REGISTRY).map((spec) => [spec.method, spec]),
-);
-
-/** Recover a best-effort id from an unvalidated payload for error responses. */
-function extractId(raw: unknown): string | number | null {
-  if (raw && typeof raw === "object" && "id" in raw) {
-    const id = (raw as { id: unknown }).id;
-    if (typeof id === "string" || typeof id === "number") return id;
-  }
-  return null;
-}
-
-export class ProtocolDispatcher {
-  readonly #handlers = new Map<string, MethodHandler>();
-  readonly #notificationListeners = new Map<NotificationName, Set<NotificationListener>>();
-  /** Per-scope-key serial promise chains (tail-of-lane). */
-  readonly #lanes = new Map<string, Promise<void>>();
-
-  /** Register a handler for a wire method name (e.g. `"turn/start"`). */
-  register(methodName: string, handler: MethodHandler): this {
-    this.#handlers.set(methodName, handler);
-    return this;
-  }
-
-  /** Subscribe to a server→client notification. */
-  onNotification(name: NotificationName, listener: NotificationListener): () => void {
-    let set = this.#notificationListeners.get(name);
-    if (!set) {
-      set = new Set();
-      this.#notificationListeners.set(name, set);
-    }
-    set.add(listener);
-    return () => {
-      set?.delete(listener);
-    };
-  }
-
-  /**
-   * Emit a server→client notification. Validates the name against the
-   * `NOTIFICATIONS` allow-list (fail-closed: unknown name throws).
-   */
-  emitNotification(name: NotificationName, payload: unknown): void {
-    if (!NOTIFICATION_NAMES.has(name)) {
-      throw new Error(`Unknown notification name: ${String(name)}`);
-    }
-    const listeners = this.#notificationListeners.get(name);
-    if (!listeners) return;
-    for (const listener of listeners) listener(payload);
-  }
-
-  /**
-   * Dispatch a single raw envelope. Never throws — every failure path maps
-   * to a JSON-RPC error response.
-   */
-  async dispatch(rawEnvelope: unknown): Promise<JsonRpcResponse> {
-    const parsed = requestEnvelopeSchema.safeParse(rawEnvelope);
-    if (!parsed.success) {
-      return failure(
-        extractId(rawEnvelope),
-        ERR_INVALID_REQUEST,
-        "Invalid request envelope (tenantId is mandatory)",
-      );
-    }
-    const envelope = parsed.data;
-
-    const spec = METHOD_SPEC_BY_WIRE.get(envelope.method);
-    if (!spec) {
-      return failure(envelope.id, ERR_METHOD_NOT_FOUND, `Method not found: ${envelope.method}`);
-    }
-
-    const handler = this.#handlers.get(envelope.method);
-    if (!handler) {
-      return failure(
-        envelope.id,
-        ERR_METHOD_NOT_FOUND,
-        `No handler registered for method: ${envelope.method}`,
-      );
-    }
-
-    const params: { threadId?: string } =
-      envelope.params && typeof envelope.params === "object"
-        ? (envelope.params as { threadId?: string })
-        : {};
-
-    let scope: SerializationScope;
-    try {
-      scope = resolveScope(spec, envelope.tenantId, params);
-    } catch {
-      return failure(
-        envelope.id,
-        ERR_INVALID_PARAMS,
-        `Method ${envelope.method} requires a threadId for scoping`,
-      );
-    }
-
-    const key = scopeKey(scope);
-    return this.#runSerialized(key, async () => {
-      try {
-        const result = await handler(envelope.params, scope);
-        return success(envelope.id, result);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : "Internal handler error";
-        return failure(envelope.id, ERR_INTERNAL, message);
-      }
-    });
-  }
-
-  /**
-   * Run `task` after every previously-enqueued task on the same scope key.
-   * A failing/slow task never poisons or blocks the lane permanently.
-   */
-  #runSerialized<T>(key: string, task: () => Promise<T>): Promise<T> {
-    const previous = this.#lanes.get(key) ?? Promise.resolve();
-    const run = previous.then(task, task);
-    // Keep the lane's tail; swallow rejections in the chain link so a thrown
-    // task does not break FIFO ordering for the next request.
-    const tail = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    this.#lanes.set(key, tail);
-    // Garbage-collect the lane once drained to avoid unbounded key growth.
-    void tail.then(() => {
-      if (this.#lanes.get(key) === tail) this.#lanes.delete(key);
-    });
-    return run;
-  }
-}

package/src/durable-turn.test.ts

@@ -1,209 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import { createDurableTurn, type DurableTurnQueuePort } from "./durable-turn";
-import type { ApprovalGate, ModelInvoker, ModelRoundResult } from "./loop";
-import { runTurn } from "./loop";
-import type { ThreadEvent, TurnConfig } from "./model";
-import type { ReviewDecision } from "./policy";
-import { InMemoryRolloutStore, type RolloutStore } 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;
-  },
-};
-
-/** Model that finishes immediately with text. */
-function quickModel(): ModelInvoker {
-  return {
-    async invoke(): Promise<ModelRoundResult> {
-      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 }) => input.v,
-  );
-  return reg;
-}
-
-/**
- * Fake in-process queue: records enqueues, runs handlers synchronously on
- * demand (so a test can simulate "crash" = never drain, then "resume").
- */
-function fakeQueue(): DurableTurnQueuePort & {
-  pending: Map<string, () => Promise<void>>;
-  drain: (jobId: string) => Promise<void>;
-} {
-  const handlers = new Map<string, (payload: unknown) => Promise<void>>();
-  const pending = new Map<string, () => Promise<void>>();
-  return {
-    pending,
-    async enqueue(job) {
-      const handler = handlers.get(job.name);
-      if (!handler) throw new Error(`no handler for ${job.name}`);
-      pending.set(job.jobId, () => handler(job.payload));
-    },
-    registerHandler(name, handler) {
-      handlers.set(name, handler);
-    },
-    async drain(jobId) {
-      const run = pending.get(jobId);
-      if (!run) return;
-      await run();
-      pending.delete(jobId);
-    },
-  };
-}
-
-function runner(model: ModelInvoker, tools: ToolRegistry) {
-  return (input: string, ctx: { tenantId: string; threadId: string }) =>
-    runTurn(input, {
-      tenantId: ctx.tenantId,
-      threadId: ctx.threadId,
-      config,
-      approvalPolicy: { kind: "on_request" },
-      model,
-      tools,
-      store: storeRef,
-      approvalGate: approveAll,
-      ruleEvaluator: () => "allow",
-    });
-}
-
-let storeRef: RolloutStore;
-
-async function collect(gen: AsyncGenerator<ThreadEvent>): Promise<ThreadEvent[]> {
-  const out: ThreadEvent[] = [];
-  for await (const e of gen) out.push(e);
-  return out;
-}
-
-describe("durable / resumable turn", () => {
-  it("crash-then-resume continues an unfinished turn", async () => {
-    const store = new InMemoryRolloutStore();
-    storeRef = store;
-    const queue = fakeQueue();
-    const durable = createDurableTurn({
-      store,
-      queue,
-      runner: runner(quickModel(), registry()),
-    });
-
-    const { turnId } = await durable.start("hello", {
-      tenantId: "org_a",
-      threadId: "th_1",
-    });
-    expect(turnId).toBeTruthy();
-
-    // Simulate crash: job enqueued but never drained — no rollout yet.
-    const before = await store.read("org_a", "th_1");
-    expect(before.length).toBe(0);
-
-    // Resume re-drives the unfinished turn to completion.
-    const events = await collect(durable.resume("org_a", "th_1"));
-    expect(events[events.length - 1]?.type).toBe("turn.completed");
-
-    const lines = await store.read("org_a", "th_1");
-    expect(lines.length).toBeGreaterThan(0);
-    expect(lines.every((l) => l.tenantId === "org_a")).toBe(true);
-  });
-
-  it("resume of a completed turn replays recorded terminal events", async () => {
-    const store = new InMemoryRolloutStore();
-    storeRef = store;
-    const queue = fakeQueue();
-    const durable = createDurableTurn({
-      store,
-      queue,
-      runner: runner(quickModel(), registry()),
-    });
-
-    const { turnId } = await durable.start("hello", {
-      tenantId: "org_a",
-      threadId: "th_done",
-    });
-    await queue.drain(turnId); // job ran to completion (no crash)
-
-    const replayed = await collect(durable.resume("org_a", "th_done"));
-    expect(replayed.some((e) => e.type === "turn.completed")).toBe(true);
-
-    // Idempotent: a second resume replays the same terminal stream.
-    const replayedAgain = await collect(durable.resume("org_a", "th_done"));
-    expect(replayedAgain.map((e) => e.type)).toEqual(replayed.map((e) => e.type));
-    // Resume must NOT append more lines when already terminal.
-    const lines = await store.read("org_a", "th_done");
-    const afterResume = await store.read("org_a", "th_done");
-    expect(afterResume.length).toBe(lines.length);
-  });
-
-  it("cross-tenant resume is impossible (isolation)", async () => {
-    const store = new InMemoryRolloutStore();
-    storeRef = store;
-    const queue = fakeQueue();
-    const durable = createDurableTurn({
-      store,
-      queue,
-      runner: runner(quickModel(), registry()),
-    });
-
-    const { turnId } = await durable.start("hello", {
-      tenantId: "org_a",
-      threadId: "th_secret",
-    });
-    await queue.drain(turnId);
-
-    // Another tenant asking for the same threadId sees nothing of org_a's data.
-    const events = await collect(durable.resume("org_b", "th_secret"));
-    expect(events.some((e) => e.type === "turn.completed")).toBe(true);
-    const orgB = await store.read("org_b", "th_secret");
-    const orgA = await store.read("org_a", "th_secret");
-    expect(orgB.every((l) => l.tenantId === "org_b")).toBe(true);
-    expect(orgA.every((l) => l.tenantId === "org_a")).toBe(true);
-    expect(orgA.length).not.toBe(0);
-  });
-
-  it("fails closed on missing tenant or thread", async () => {
-    const store = new InMemoryRolloutStore();
-    storeRef = store;
-    const durable = createDurableTurn({
-      store,
-      queue: fakeQueue(),
-      runner: runner(quickModel(), registry()),
-    });
-
-    await expect(durable.start("x", { tenantId: "", threadId: "th" })).rejects.toThrow();
-    await expect(durable.start("x", { tenantId: "t", threadId: "" })).rejects.toThrow();
-    await expect(collect(durable.resume("", "th"))).rejects.toThrow();
-    await expect(collect(durable.resume("t", ""))).rejects.toThrow();
-  });
-
-  it("start enqueues a tenant+thread scoped jobId", async () => {
-    const store = new InMemoryRolloutStore();
-    storeRef = store;
-    const queue = fakeQueue();
-    const durable = createDurableTurn({
-      store,
-      queue,
-      runner: runner(quickModel(), registry()),
-    });
-
-    const a = await durable.start("x", { tenantId: "org_a", threadId: "th_1" });
-    const b = await durable.start("x", { tenantId: "org_b", threadId: "th_1" });
-    expect(a.turnId).not.toBe(b.turnId);
-    expect([...queue.pending.keys()]).toContain(a.turnId);
-    expect([...queue.pending.keys()]).toContain(b.turnId);
-  });
-});

package/src/durable-turn.ts

@@ -1,135 +0,0 @@
-/**
- * Durable / resumable turn (WRAP — capability #10).
- *
- * Wraps the existing {@link runTurn} async generator so a turn survives a
- * process crash. `start` enqueues a tenant+thread-scoped durable job whose
- * handler drains `runTurn` (the loop runner already appends every event to the
- * tenant-scoped {@link RolloutStore}); the durable layer guarantees the job is
- * replayable if the worker dies mid-turn. `resume` inspects the persisted
- * rollout: if the last recorded event is non-terminal the turn is re-driven to
- * completion, otherwise the recorded terminal stream is replayed.
- *
- * Queue binding is interface-only — callers wire `@nebutra/queue` by
- * implementing {@link DurableTurnQueuePort}; this package never depends on it.
- * Tenant scoping is mandatory and fail-closed: a missing tenant or thread
- * throws, and resume can never read another tenant's rollout.
- */
-
-import { z } from "zod";
-import type { ThreadEvent } from "./model";
-import { isTurnTerminal } from "./model";
-import { type RolloutLine, type RolloutStore, replay } from "./rollout";
-
-/** A durable job handed to the queue. Mirrors `@nebutra/queue` job shape. */
-export interface DurableTurnJob {
-  /** Logical job name — used for handler routing. */
-  readonly name: string;
-  /** Tenant+thread-scoped id; the queue must de-dupe / make idempotent on it. */
-  readonly jobId: string;
-  /** Opaque Zod-validated payload (kept narrow on purpose). */
-  readonly payload: unknown;
-}
-
-/**
- * Minimal injectable queue seam (enqueue + handler registration). Mirrors
- * `@nebutra/queue`'s `defineQueueJob` / `createJobRouter` contract without a
- * hard dependency, so this package stays provider-agnostic.
- */
-export interface DurableTurnQueuePort {
-  enqueue(job: DurableTurnJob): Promise<void>;
-  registerHandler(name: string, handler: (payload: unknown) => Promise<void>): void;
-}
-
-/** Drives one turn, yielding the event stream (persists internally). */
-export type DurableTurnRunner = (input: string, ctx: TurnContext) => AsyncGenerator<ThreadEvent>;
-
-export interface TurnContext {
-  readonly tenantId: string;
-  readonly threadId: string;
-}
-
-export interface CreateDurableTurnDeps {
-  readonly store: RolloutStore;
-  readonly queue: DurableTurnQueuePort;
-  readonly runner: DurableTurnRunner;
-}
-
-export interface DurableTurn {
-  start(input: string, ctx: TurnContext): Promise<{ readonly turnId: string }>;
-  resume(tenantId: string, threadId: string): AsyncGenerator<ThreadEvent>;
-}
-
-const DURABLE_TURN_JOB = "agent-runtime.durable-turn";
-
-const contextSchema = z.object({
-  tenantId: z.string().min(1),
-  threadId: z.string().min(1),
-});
-
-const jobPayloadSchema = z.object({
-  tenantId: z.string().min(1),
-  threadId: z.string().min(1),
-  input: z.string(),
-});
-
-/** Tenant+thread-scoped, stable job id (idempotency key on the queue). */
-function turnIdFor(tenantId: string, threadId: string): string {
-  return `${DURABLE_TURN_JOB}:${tenantId}:${threadId}`;
-}
-
-/** Recorded `ThreadEvent`s in append order, tenant-scoped via the store read. */
-function recordedEvents(lines: readonly RolloutLine[]): ThreadEvent[] {
-  return lines.flatMap((line) => (line.type === "event" ? [line.event] : []));
-}
-
-export function createDurableTurn(deps: CreateDurableTurnDeps): DurableTurn {
-  const { store, queue, runner } = deps;
-
-  // Register the durable handler once: drain the runner so every event is
-  // persisted by the loop runner. Crash before/within = job stays replayable.
-  queue.registerHandler(DURABLE_TURN_JOB, async (payload: unknown) => {
-    const { tenantId, threadId, input } = jobPayloadSchema.parse(payload);
-    const gen = runner(input, { tenantId, threadId });
-    for await (const _event of gen) {
-      // The runner persists each event; nothing to do but exhaust it.
-    }
-  });
-
-  async function start(input: string, ctx: TurnContext): Promise<{ readonly turnId: string }> {
-    const { tenantId, threadId } = contextSchema.parse(ctx);
-    const turnId = turnIdFor(tenantId, threadId);
-    await queue.enqueue({
-      name: DURABLE_TURN_JOB,
-      jobId: turnId,
-      payload: { tenantId, threadId, input },
-    });
-    return { turnId };
-  }
-
-  async function* resume(tenantId: string, threadId: string): AsyncGenerator<ThreadEvent> {
-    const scope = contextSchema.parse({ tenantId, threadId });
-    // Tenant-scoped read — cross-tenant resume is structurally impossible.
-    const lines = await store.read(scope.tenantId, scope.threadId);
-    const projection = replay(lines);
-    const events = recordedEvents(lines);
-    const last = events[events.length - 1];
-
-    if (projection && last && isTurnTerminal(last)) {
-      // Completed turn — replay the recorded stream, append nothing.
-      for (const event of events) yield event;
-      return;
-    }
-
-    // Unfinished (crash) or never-started — re-drive to completion. The runner
-    // appends fresh lines; we recover the original input from the rollout if
-    // present, else an empty resume prompt (turn is replay-driven thereafter).
-    const input = "";
-    const gen = runner(input, {
-      tenantId: scope.tenantId,
-      threadId: scope.threadId,
-    });
-    for await (const event of gen) yield event;
-  }
-
-  return { start, resume };
-}