@nebutra/agent-runtime 0.2.1 → 2.0.0

package/src/pulsar.test.ts

@@ -1,156 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { z } from "zod";
-import type { ApprovalGate, ModelInvoker, ModelRoundResult } from "./loop";
-import type { ThreadEvent, TurnConfig } from "./model";
-import type { ReviewDecision } from "./policy";
-import { Pulsar } from "./pulsar";
-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;
-  },
-};
-
-function quickModel(): ModelInvoker {
-  return {
-    async invoke(): Promise<ModelRoundResult> {
-      return {
-        emissions: [{ kind: "text", text: "done" }],
-        usage: { inputTokens: 2, outputTokens: 1 },
-      };
-    },
-  };
-}
-
-function registry(): ToolRegistry {
-  const tools = new ToolRegistry();
-  tools.register(
-    { name: "echo", description: "echo", inputSchema: z.object({ v: z.string() }) },
-    async (input: { v: string }) => input.v,
-  );
-  return tools;
-}
-
-async function collect(gen: AsyncGenerator<ThreadEvent>): Promise<ThreadEvent[]> {
-  const events: ThreadEvent[] = [];
-  for await (const event of gen) events.push(event);
-  return events;
-}
-
-function fakeEventLog() {
-  const commits: Array<{
-    traceId: string;
-    kind: string;
-    affected: readonly string[];
-    parent: string | null;
-  }> = [];
-  const branches: Array<{ id: string; name: string }> = [];
-  return {
-    commits,
-    branches,
-    async commit(event: {
-      traceId: string;
-      kind: string;
-      affected: readonly string[];
-      parent: string | null;
-    }) {
-      commits.push(event);
-      return `event_${commits.length}`;
-    },
-    async branchFrom(id: string, name: string) {
-      branches.push({ id, name });
-      return { name, from: id, at: "now" };
-    },
-  };
-}
-
-describe("Pulsar facade", () => {
-  it("starts a tenant-scoped thread, streams item-level events, and mirrors items to event-log", async () => {
-    const store = new InMemoryRolloutStore();
-    const eventLog = fakeEventLog();
-    const pulsar = Pulsar.builder()
-      .withTenant("org_1")
-      .withConfig(config)
-      .withModel(quickModel())
-      .withTools(registry())
-      .withRolloutStore(store)
-      .withApprovalGate(approveAll)
-      .withEventLog(eventLog)
-      .build();
-
-    const thread = await pulsar.startPlay("hello_play", "say hi");
-    const events = await collect(thread.subscribe());
-
-    expect(events[0]).toEqual({ type: "thread.started", threadId: thread.id });
-    expect(events.some((event) => event.type === "item.completed")).toBe(true);
-    expect(events.at(-1)?.type).toBe("turn.completed");
-    expect(eventLog.commits).toMatchObject([
-      { traceId: thread.id, kind: "llm_call", affected: [], parent: null },
-    ]);
-
-    const rollout = await store.read("org_1", thread.id);
-    expect(rollout[0]).toMatchObject({ type: "session_meta", threadId: thread.id });
-    expect(rollout.every((line) => line.tenantId === "org_1")).toBe(true);
-  });
-
-  it("resumes a completed thread by replaying recorded events instead of calling the model again", async () => {
-    let invokes = 0;
-    const model: ModelInvoker = {
-      async invoke() {
-        invokes += 1;
-        return { emissions: [{ kind: "text", text: "done" }] };
-      },
-    };
-    const pulsar = Pulsar.builder()
-      .withTenant("org_1")
-      .withConfig(config)
-      .withModel(model)
-      .withTools(registry())
-      .withRolloutStore(new InMemoryRolloutStore())
-      .withApprovalGate(approveAll)
-      .build();
-
-    const thread = await pulsar.startPlay("hello_play", "say hi");
-    const first = await collect(thread.subscribe());
-    const resumed = await pulsar.resume(thread.id);
-    const replayed = await collect(resumed.subscribe());
-
-    expect(invokes).toBe(1);
-    expect(replayed.map((event) => event.type)).toEqual(first.map((event) => event.type));
-  });
-
-  it("branches from an item by resolving the item-level event-log commit", async () => {
-    const eventLog = fakeEventLog();
-    const pulsar = Pulsar.builder()
-      .withTenant("org_1")
-      .withConfig(config)
-      .withModel(quickModel())
-      .withTools(registry())
-      .withRolloutStore(new InMemoryRolloutStore())
-      .withApprovalGate(approveAll)
-      .withEventLog(eventLog)
-      .build();
-
-    const thread = await pulsar.startPlay("hello_play", "say hi");
-    const events = await collect(thread.subscribe());
-    const item = events.find((event) => event.type === "item.completed")?.item;
-    if (!item) throw new Error("expected completed item");
-
-    await pulsar.branchFromItem(thread.id, item.id, "variant");
-
-    expect(eventLog.branches).toEqual([{ id: "event_1", name: "variant" }]);
-  });
-
-  it("fails closed without tenant context", () => {
-    expect(() => Pulsar.builder().withTenant("")).toThrow(/tenant/i);
-  });
-});

package/src/pulsar.ts

@@ -1,322 +0,0 @@
-import { type ApprovalGate, type ModelInvoker, runTurn } from "./loop";
-import type { ThreadEvent, ThreadItem, TurnConfig } from "./model";
-import { isTurnTerminal } from "./model";
-import type { ApprovalPolicy } from "./policy";
-import { DEFAULT_APPROVAL_POLICY } from "./policy";
-import type { RolloutLine, RolloutStore } from "./rollout";
-import { replay } from "./rollout";
-import { RuntimeToolRegistry } from "./tools";
-
-type EventLogKind = "llm_call" | "tool_call" | "sub_agent_call" | "content_write";
-
-export interface PulsarEventInput {
-  readonly traceId: string;
-  readonly kind: EventLogKind;
-  readonly affected: readonly string[];
-  readonly parent: string | null;
-  readonly snapshot?: Record<string, string>;
-}
-
-export interface PulsarBranchRecord {
-  readonly name: string;
-  readonly from: string;
-  readonly at: string;
-}
-
-export interface PulsarEventLogPort {
-  commit(event: PulsarEventInput): Promise<string>;
-  branchFrom(id: string, name: string): Promise<PulsarBranchRecord>;
-}
-
-export interface StartThreadOptions {
-  readonly threadId?: string;
-  readonly maxSteps?: number;
-}
-
-export interface PulsarDeps {
-  readonly tenantId: string;
-  readonly config: TurnConfig;
-  readonly model: ModelInvoker;
-  readonly tools: RuntimeToolRegistry;
-  readonly store: RolloutStore;
-  readonly approvalGate: ApprovalGate;
-  readonly approvalPolicy: ApprovalPolicy;
-  readonly eventLog?: PulsarEventLogPort;
-}
-
-function newId(prefix: string): string {
-  return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`}`;
-}
-
-function requireNonEmpty(value: string, label: string): string {
-  const trimmed = value.trim();
-  if (!trimmed) {
-    throw new Error(`${label} is required. Suggestion: pass a non-empty ${label}.`);
-  }
-  return trimmed;
-}
-
-function recordedEvents(lines: readonly RolloutLine[]): ThreadEvent[] {
-  return lines.flatMap((line) => (line.type === "event" ? [line.event] : []));
-}
-
-function mapItemToEvent(item: ThreadItem): PulsarEventInput["kind"] {
-  switch (item.type) {
-    case "agent_message":
-    case "reasoning":
-      return "llm_call";
-    case "file_change":
-      return "content_write";
-    case "command_execution":
-    case "mcp_tool_call":
-      return "tool_call";
-    case "error":
-    case "todo_list":
-    case "web_search":
-      return "tool_call";
-  }
-}
-
-function affectedPaths(item: ThreadItem): readonly string[] {
-  return item.type === "file_change" ? item.changes.map((change) => change.path) : [];
-}
-
-export class PulsarThread {
-  readonly id: string;
-  readonly playId: string;
-  readonly tenantId: string;
-  readonly #deps: PulsarDeps;
-  readonly #input: string;
-  readonly #maxSteps: number | undefined;
-  readonly #mode: "start" | "resume";
-  #events: ThreadEvent[] | undefined;
-
-  constructor(input: {
-    readonly id: string;
-    readonly playId: string;
-    readonly tenantId: string;
-    readonly deps: PulsarDeps;
-    readonly mode: "start" | "resume";
-    readonly userInput: string;
-    readonly maxSteps?: number;
-  }) {
-    this.id = input.id;
-    this.playId = input.playId;
-    this.tenantId = input.tenantId;
-    this.#deps = input.deps;
-    this.#input = input.userInput;
-    this.#mode = input.mode;
-    this.#maxSteps = input.maxSteps;
-  }
-
-  async *subscribe(): AsyncGenerator<ThreadEvent> {
-    if (this.#events) {
-      for (const event of this.#events) yield event;
-      return;
-    }
-
-    const events: ThreadEvent[] = [];
-    const emit = async (event: ThreadEvent): Promise<ThreadEvent> => {
-      events.push(event);
-      if (event.type === "item.completed") {
-        await this.#mirrorItem(event.item);
-      }
-      return event;
-    };
-
-    if (this.#mode === "resume") {
-      const lines = await this.#deps.store.read(this.tenantId, this.id);
-      const projection = replay(lines);
-      const recorded = recordedEvents(lines);
-      const last = recorded.at(-1);
-      if (projection && last && isTurnTerminal(last)) {
-        this.#events = recorded;
-        for (const event of recorded) yield event;
-        return;
-      }
-    }
-
-    yield await emit({ type: "thread.started", threadId: this.id });
-    await this.#deps.store.append({
-      tenantId: this.tenantId,
-      threadId: this.id,
-      type: "event",
-      event: { type: "thread.started", threadId: this.id },
-      at: new Date().toISOString(),
-    });
-
-    const stream = runTurn(this.#input, {
-      tenantId: this.tenantId,
-      threadId: this.id,
-      config: this.#deps.config,
-      approvalPolicy: this.#deps.approvalPolicy,
-      model: this.#deps.model,
-      tools: this.#deps.tools,
-      store: this.#deps.store,
-      approvalGate: this.#deps.approvalGate,
-      ruleEvaluator: () => "allow",
-      ...(this.#maxSteps !== undefined ? { maxSteps: this.#maxSteps } : {}),
-    });
-
-    for await (const event of stream) {
-      yield await emit(event);
-    }
-    this.#events = events;
-  }
-
-  async #mirrorItem(item: ThreadItem): Promise<void> {
-    const eventLog = this.#deps.eventLog;
-    if (!eventLog) return;
-    const parent = Pulsar.itemCommitIds.get(`${this.id}::__last`) ?? null;
-    const commitId = await eventLog.commit({
-      traceId: this.id,
-      kind: mapItemToEvent(item),
-      affected: affectedPaths(item),
-      parent,
-    });
-    Pulsar.itemCommitIds.set(`${this.id}:${item.id}`, commitId);
-    Pulsar.itemCommitIds.set(`${this.id}::__last`, commitId);
-  }
-}
-
-export class PulsarBuilder {
-  #tenantId?: string;
-  #config?: TurnConfig;
-  #model?: ModelInvoker;
-  #tools: RuntimeToolRegistry = new RuntimeToolRegistry();
-  #store?: RolloutStore;
-  #approvalGate?: ApprovalGate;
-  #approvalPolicy: ApprovalPolicy = DEFAULT_APPROVAL_POLICY;
-  #eventLog?: PulsarEventLogPort;
-
-  withTenant(tenantId: string): this {
-    this.#tenantId = requireNonEmpty(tenantId, "tenantId");
-    return this;
-  }
-
-  withConfig(config: TurnConfig): this {
-    this.#config = config;
-    return this;
-  }
-
-  withModel(model: ModelInvoker): this {
-    this.#model = model;
-    return this;
-  }
-
-  withTools(tools: RuntimeToolRegistry): this {
-    this.#tools = tools;
-    return this;
-  }
-
-  withRolloutStore(store: RolloutStore): this {
-    this.#store = store;
-    return this;
-  }
-
-  withApprovalGate(approvalGate: ApprovalGate): this {
-    this.#approvalGate = approvalGate;
-    return this;
-  }
-
-  withApprovalPolicy(policy: ApprovalPolicy): this {
-    this.#approvalPolicy = policy;
-    return this;
-  }
-
-  withEventLog(eventLog: PulsarEventLogPort): this {
-    this.#eventLog = eventLog;
-    return this;
-  }
-
-  build(): Pulsar {
-    if (!this.#tenantId) throw new Error("tenantId is required. Suggestion: call withTenant().");
-    if (!this.#config) throw new Error("config is required. Suggestion: call withConfig().");
-    if (!this.#model) throw new Error("model is required. Suggestion: call withModel().");
-    if (!this.#store) {
-      throw new Error("rollout store is required. Suggestion: call withRolloutStore().");
-    }
-    if (!this.#approvalGate) {
-      throw new Error("approval gate is required. Suggestion: call withApprovalGate().");
-    }
-    const deps: PulsarDeps = {
-      tenantId: this.#tenantId,
-      config: this.#config,
-      model: this.#model,
-      tools: this.#tools,
-      store: this.#store,
-      approvalGate: this.#approvalGate,
-      approvalPolicy: this.#approvalPolicy,
-      ...(this.#eventLog !== undefined ? { eventLog: this.#eventLog } : {}),
-    };
-    return new Pulsar(deps);
-  }
-}
-
-export class Pulsar {
-  static readonly itemCommitIds = new Map<string, string>();
-  readonly #deps: PulsarDeps;
-
-  constructor(deps: PulsarDeps) {
-    this.#deps = deps;
-  }
-
-  static builder(): PulsarBuilder {
-    return new PulsarBuilder();
-  }
-
-  async startPlay(
-    playId: string,
-    input: string,
-    options: StartThreadOptions = {},
-  ): Promise<PulsarThread> {
-    const threadId = options.threadId ?? newId("thread");
-    await this.#deps.store.append({
-      tenantId: this.#deps.tenantId,
-      threadId,
-      type: "session_meta",
-      config: this.#deps.config,
-      at: new Date().toISOString(),
-    });
-    return new PulsarThread({
-      id: threadId,
-      playId: requireNonEmpty(playId, "playId"),
-      tenantId: this.#deps.tenantId,
-      deps: this.#deps,
-      mode: "start",
-      userInput: input,
-      ...(options.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
-    });
-  }
-
-  async resume(threadId: string): Promise<PulsarThread> {
-    return new PulsarThread({
-      id: requireNonEmpty(threadId, "threadId"),
-      playId: "resume",
-      tenantId: this.#deps.tenantId,
-      deps: this.#deps,
-      mode: "resume",
-      userInput: "",
-    });
-  }
-
-  async branchFromItem(
-    threadId: string,
-    itemId: string,
-    name: string,
-  ): Promise<PulsarBranchRecord> {
-    const eventLog = this.#deps.eventLog;
-    if (!eventLog) {
-      throw new Error("event-log is required. Suggestion: call withEventLog() before branching.");
-    }
-    const commitId = Pulsar.itemCommitIds.get(
-      `${requireNonEmpty(threadId, "threadId")}:${requireNonEmpty(itemId, "itemId")}`,
-    );
-    if (!commitId) {
-      throw new Error(
-        "item has no event-log commit. Suggestion: subscribe to the thread before branching.",
-      );
-    }
-    return eventLog.branchFrom(commitId, requireNonEmpty(name, "branch name"));
-  }
-}

package/src/rollout-store-persistent.test.ts

@@ -1,217 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { ThreadItem } from "./model";
-import { InMemoryRolloutStore, type RolloutLine, replay } from "./rollout";
-import {
-  PersistentRolloutStore,
-  type RolloutPersistencePort,
-  RoundTripError,
-} from "./rollout-store-persistent";
-
-/** In-memory fake satisfying the injectable persistence port. */
-class FakePort implements RolloutPersistencePort {
-  readonly records = new Map<string, { seq: number; payload: string }[]>();
-
-  #key(tenantId: string, threadId: string): string {
-    return `${tenantId}::${threadId}`;
-  }
-
-  async put(record: {
-    tenantId: string;
-    threadId: string;
-    seq: number;
-    at: string;
-    payload: string;
-  }): Promise<void> {
-    const key = this.#key(record.tenantId, record.threadId);
-    const list = this.records.get(key) ?? [];
-    list.push({ seq: record.seq, payload: record.payload });
-    this.records.set(key, list);
-  }
-
-  async list(tenantId: string, threadId: string): Promise<{ seq: number; payload: string }[]> {
-    const list = this.records.get(this.#key(tenantId, threadId)) ?? [];
-    // Return deliberately shuffled to prove the store re-sorts by seq.
-    return [...list].sort(() => Math.random() - 0.5);
-  }
-}
-
-const T = "org_A";
-const TH = "thread_1";
-
-function metaLine(tenantId = T, threadId = TH): RolloutLine {
-  return {
-    tenantId,
-    threadId,
-    type: "session_meta",
-    config: {
-      model: "m",
-      provider: "p",
-      approvalPolicy: "on_request",
-      capabilityPolicy: "external_sandbox",
-    },
-    at: "2026-05-17T00:00:00.000Z",
-  };
-}
-
-function eventLine(item: ThreadItem, tenantId = T, threadId = TH): RolloutLine {
-  return {
-    tenantId,
-    threadId,
-    type: "event",
-    event: { type: "item.completed", item },
-    at: "2026-05-17T00:00:01.000Z",
-  };
-}
-
-function compactedLine(tenantId = T, threadId = TH): RolloutLine {
-  return {
-    tenantId,
-    threadId,
-    type: "compacted",
-    summary: "earlier history summarized",
-    droppedThrough: "item_9",
-    at: "2026-05-17T00:00:02.000Z",
-  };
-}
-
-const msgItem: ThreadItem = {
-  id: "item_1",
-  type: "agent_message",
-  text: "hello world",
-};
-
-describe("PersistentRolloutStore round-trip", () => {
-  it("round-trips every RolloutLine variant faithfully", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    const lines: RolloutLine[] = [
-      metaLine(),
-      eventLine(msgItem),
-      {
-        tenantId: T,
-        threadId: TH,
-        type: "turn_context",
-        config: {
-          model: "m2",
-          provider: "p2",
-          approvalPolicy: "never",
-          capabilityPolicy: "read_only",
-          reasoningEffort: "high",
-        },
-        at: "2026-05-17T00:00:03.000Z",
-      },
-      compactedLine(),
-    ];
-    for (const l of lines) await store.append(l);
-    const read = await store.read(T, TH);
-    expect(read).toEqual(lines);
-  });
-
-  it("preserves append ordering", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    for (let i = 0; i < 25; i++) {
-      await store.append(eventLine({ id: `item_${i}`, type: "agent_message", text: `m${i}` }));
-    }
-    const read = await store.read(T, TH);
-    expect(read.map((l) => (l.type === "event" ? l.event : null))).toEqual(
-      Array.from({ length: 25 }, (_, i) => ({
-        type: "item.completed",
-        item: { id: `item_${i}`, type: "agent_message", text: `m${i}` },
-      })),
-    );
-  });
-
-  it("replay over persistent output equals replay over in-memory", async () => {
-    const persistent = new PersistentRolloutStore(new FakePort());
-    const memory = new InMemoryRolloutStore();
-    const lines: RolloutLine[] = [
-      metaLine(),
-      eventLine({ id: "i1", type: "agent_message", text: "a" }),
-      eventLine({ id: "i2", type: "reasoning", text: "thinking" }),
-      compactedLine(),
-      eventLine({ id: "i3", type: "agent_message", text: "post" }),
-    ];
-    for (const l of lines) {
-      await persistent.append(l);
-      await memory.append(l);
-    }
-    const pj = replay(await persistent.read(T, TH));
-    const mj = replay(await memory.read(T, TH));
-    expect(pj).toEqual(mj);
-  });
-});
-
-describe("PersistentRolloutStore tenant isolation", () => {
-  it("tenant B cannot read tenant A's thread", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    await store.append(metaLine("org_A", "shared_thread"));
-    await store.append(eventLine(msgItem, "org_A", "shared_thread"));
-    const aRead = await store.read("org_A", "shared_thread");
-    const bRead = await store.read("org_B", "shared_thread");
-    expect(aRead).toHaveLength(2);
-    expect(bRead).toEqual([]);
-  });
-
-  it("seq is independent per (tenant, thread)", async () => {
-    const port = new FakePort();
-    const store = new PersistentRolloutStore(port);
-    await store.append(metaLine("org_A", "th"));
-    await store.append(metaLine("org_B", "th"));
-    await store.append(metaLine("org_A", "th"));
-    expect(port.records.get("org_A::th")?.map((r) => r.seq)).toEqual([0, 1]);
-    expect(port.records.get("org_B::th")?.map((r) => r.seq)).toEqual([0]);
-  });
-});
-
-describe("PersistentRolloutStore fail-closed", () => {
-  it("throws on empty tenantId in append", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    await expect(store.append(metaLine("", TH))).rejects.toThrow();
-  });
-
-  it("throws on empty threadId in append", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    await expect(store.append(metaLine(T, ""))).rejects.toThrow();
-  });
-
-  it("throws on empty tenantId in read", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    await expect(store.read("", TH)).rejects.toThrow();
-  });
-
-  it("throws on empty threadId in read", async () => {
-    const store = new PersistentRolloutStore(new FakePort());
-    await expect(store.read(T, "")).rejects.toThrow();
-  });
-
-  it("throws RoundTripError on malformed stored payload (never silently drops)", async () => {
-    const port = new FakePort();
-    const store = new PersistentRolloutStore(port);
-    await store.append(metaLine());
-    port.records.get(`${T}::${TH}`)?.push({ seq: 1, payload: "{not json" });
-    await expect(store.read(T, TH)).rejects.toBeInstanceOf(RoundTripError);
-  });
-
-  it("throws RoundTripError on structurally-invalid stored payload", async () => {
-    const port = new FakePort();
-    const store = new PersistentRolloutStore(port);
-    await store.append(metaLine());
-    port.records.get(`${T}::${TH}`)?.push({ seq: 1, payload: JSON.stringify({ type: "bogus" }) });
-    await expect(store.read(T, TH)).rejects.toBeInstanceOf(RoundTripError);
-  });
-});
-
-describe("PersistentRolloutStore concurrency", () => {
-  it("concurrent appends to the same thread do not collide on seq", async () => {
-    const port = new FakePort();
-    const store = new PersistentRolloutStore(port);
-    await Promise.all(
-      Array.from({ length: 50 }, (_, i) =>
-        store.append(eventLine({ id: `c_${i}`, type: "agent_message", text: `${i}` })),
-      ),
-    );
-    const seqs = (port.records.get(`${T}::${TH}`) ?? []).map((r) => r.seq).sort((a, b) => a - b);
-    expect(seqs).toEqual(Array.from({ length: 50 }, (_, i) => i));
-    const read = await store.read(T, TH);
-    expect(read).toHaveLength(50);
-  });
-});