@nebutra/agent-runtime 0.2.0 → 0.2.1

package/src/orchestration.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { type Brief, costReport, fanOutSubagents, planSubagentDispatch } from "./orchestration";
+
+function brief(name: string, dependsOn: readonly string[] = []): Brief {
+  return {
+    id: name,
+    objective: `do ${name}`,
+    outputFormat: { type: "object", properties: { value: { type: "string" } } },
+    allowedTools: ["read"],
+    contextRefs: [],
+    boundaries: ["do not write outside scope"],
+    budget: { durationMs: 1_000, costUsd: 0.01, tokenLimit: 1_000 },
+    dependsOn,
+  };
+}
+
+describe("subagent orchestration", () => {
+  it("defaults dependent briefs to sequential dispatch", () => {
+    const plan = planSubagentDispatch([brief("research"), brief("write", ["research"])]);
+    expect(plan.strategy).toBe("sequential");
+    expect(plan.order.map((item) => item.id)).toEqual(["research", "write"]);
+  });
+
+  it("refuses fan-out when briefs depend on each other", () => {
+    expect(() =>
+      planSubagentDispatch([brief("research"), brief("write", ["research"])], {
+        strategy: "fanout",
+      }),
+    ).toThrow(/fan-out|depend/i);
+  });
+
+  it("runs independent fan-out briefs and preserves result ownership", async () => {
+    const results = await fanOutSubagents([brief("logo"), brief("copy")], async (item) => ({
+      briefId: item.id,
+      output: { value: item.objective },
+      usage: { inputTokens: 10, cachedInputTokens: 0, outputTokens: 3, reasoningOutputTokens: 0 },
+      durationMs: 5,
+    }));
+
+    expect(results.map((result) => result.briefId)).toEqual(["logo", "copy"]);
+    expect(costReport(results)).toEqual({
+      totalInputTokens: 20,
+      totalOutputTokens: 6,
+      totalReasoningTokens: 0,
+      maxDurationMs: 5,
+      subagents: 2,
+    });
+  });
+
+  it("requires precise brief fields", () => {
+    expect(() => planSubagentDispatch([{ ...brief("bad"), objective: "" }])).toThrow(/objective/i);
+  });
+});

package/src/orchestration.ts

@@ -0,0 +1,146 @@
+import type { TurnUsage } from "./model";
+
+export interface BudgetCap {
+  readonly durationMs: number;
+  readonly costUsd: number;
+  readonly tokenLimit: number;
+}
+
+export interface Brief {
+  readonly id: string;
+  readonly objective: string;
+  readonly outputFormat: Record<string, unknown>;
+  readonly allowedTools: readonly string[];
+  readonly contextRefs: readonly string[];
+  readonly boundaries: readonly string[];
+  readonly budget: BudgetCap;
+  readonly dependsOn?: readonly string[];
+}
+
+export type DispatchStrategy = "auto" | "sequential" | "fanout";
+
+export interface DispatchPlan {
+  readonly strategy: Exclude<DispatchStrategy, "auto">;
+  readonly order: readonly Brief[];
+}
+
+export interface DispatchPlanOptions {
+  readonly strategy?: DispatchStrategy;
+}
+
+export interface SubagentResult {
+  readonly briefId: string;
+  readonly output: unknown;
+  readonly usage: TurnUsage;
+  readonly durationMs: number;
+}
+
+export interface SubagentCostReport {
+  readonly totalInputTokens: number;
+  readonly totalOutputTokens: number;
+  readonly totalReasoningTokens: number;
+  readonly maxDurationMs: number;
+  readonly subagents: number;
+}
+
+function fail(message: string, suggestion: string): never {
+  throw new Error(`${message}. Suggestion: ${suggestion}`);
+}
+
+function validateBrief(brief: Brief): void {
+  if (!brief.id.trim()) fail("brief.id is required", "Use a stable role or task id.");
+  if (!brief.objective.trim()) {
+    fail("brief.objective is required", "Write a concrete objective before dispatching.");
+  }
+  if (brief.allowedTools.length === 0) {
+    fail("brief.allowedTools is required", "Constrain each subagent to an explicit tool scope.");
+  }
+  if (brief.boundaries.length === 0) {
+    fail("brief.boundaries is required", "State at least one boundary for the worker.");
+  }
+  if (brief.budget.tokenLimit <= 0 || brief.budget.durationMs <= 0 || brief.budget.costUsd < 0) {
+    fail("brief.budget is invalid", "Set positive token/time caps and a non-negative cost cap.");
+  }
+}
+
+function dependencySet(briefs: readonly Brief[]): Set<string> {
+  const dependencies = new Set<string>();
+  for (const brief of briefs) {
+    for (const dep of brief.dependsOn ?? []) dependencies.add(dep);
+  }
+  return dependencies;
+}
+
+function topologicalOrder(briefs: readonly Brief[]): Brief[] {
+  const byId = new Map(briefs.map((brief) => [brief.id, brief]));
+  const visited = new Set<string>();
+  const visiting = new Set<string>();
+  const ordered: Brief[] = [];
+
+  const visit = (brief: Brief): void => {
+    if (visited.has(brief.id)) return;
+    if (visiting.has(brief.id)) {
+      fail(
+        `subagent dependency cycle includes '${brief.id}'`,
+        "Remove the cycle or collapse the dependent work into one sequential brief.",
+      );
+    }
+    visiting.add(brief.id);
+    for (const dep of brief.dependsOn ?? []) {
+      const dependency = byId.get(dep);
+      if (dependency) visit(dependency);
+    }
+    visiting.delete(brief.id);
+    visited.add(brief.id);
+    ordered.push(brief);
+  };
+
+  for (const brief of briefs) visit(brief);
+  return ordered;
+}
+
+export function planSubagentDispatch(
+  briefs: readonly Brief[],
+  options: DispatchPlanOptions = {},
+): DispatchPlan {
+  if (briefs.length === 0) {
+    fail("at least one brief is required", "Create a concrete worker brief before dispatching.");
+  }
+  for (const brief of briefs) validateBrief(brief);
+
+  const dependencies = dependencySet(briefs);
+  if ((options.strategy ?? "auto") === "fanout" && dependencies.size > 0) {
+    fail(
+      "fan-out cannot run briefs that depend on each other",
+      "Use sequential dispatch for dependent work or split independent briefs only.",
+    );
+  }
+
+  const order = topologicalOrder(briefs);
+  const strategy =
+    options.strategy === "fanout" || (options.strategy === "auto" && dependencies.size === 0)
+      ? "fanout"
+      : "sequential";
+  return { strategy, order };
+}
+
+export async function fanOutSubagents(
+  briefs: readonly Brief[],
+  run: (brief: Brief) => Promise<SubagentResult>,
+): Promise<readonly SubagentResult[]> {
+  const plan = planSubagentDispatch(briefs, { strategy: "fanout" });
+  return Promise.all(plan.order.map((brief) => run(brief)));
+}
+
+export function costReport(results: readonly SubagentResult[]): SubagentCostReport {
+  return {
+    totalInputTokens: results.reduce((sum, result) => sum + result.usage.inputTokens, 0),
+    totalOutputTokens: results.reduce((sum, result) => sum + result.usage.outputTokens, 0),
+    totalReasoningTokens: results.reduce(
+      (sum, result) => sum + result.usage.reasoningOutputTokens,
+      0,
+    ),
+    maxDurationMs: results.reduce((max, result) => Math.max(max, result.durationMs), 0),
+    subagents: results.length,
+  };
+}

package/src/permission-ruleset.ts

@@ -1,200 +1 @@
-/**
- * Permission ruleset evaluator.
- *
- * A small, pure, stateless re-expression of a two-dimensional wildcard
- * permission model plus a bash-command-prefix extractor. No global state,
- * no I/O, no mutation of inputs — every function is referentially transparent.
- *
- * The model has two independent dimensions per rule:
- *   - `permission` — the capability namespace (e.g. "bash", "edit", "net")
- *   - `pattern`    — the concrete subject within that namespace
- * A rule applies only when BOTH dimensions match the query via {@link wildcardMatch}.
- */
-
-/** The decision a rule yields. Unknown queries fail safe to "ask". */
-export type Action = "allow" | "deny" | "ask";
-
-/** A single permission rule. Both dimensions are matched as wildcard globs. */
-export interface Rule {
-  permission: string;
-  pattern: string;
-  action: Action;
-}
-
-/** An ordered list of rules. Earlier rules take precedence. */
-export type Ruleset = Rule[];
-
-/**
- * Anchored full-string glob matcher.
- *
- * Semantics:
- *   - `*` matches any run of characters, including the empty run.
- *   - `?` matches exactly one character.
- *   - Every other character is matched literally (regex metacharacters in
- *     `pattern` carry no special meaning).
- *   - The match is anchored: the entire `str` must be consumed.
- *
- * Special rule (ported faithfully): if `pattern` ends with `" *"` (a single
- * space immediately followed by `*`), that trailing ` *` is OPTIONAL. The
- * pattern then matches both `"<head> <rest>"` and exactly `"<head>"` with
- * nothing after it. For example `"git *"` matches `"git"` and `"git status"`.
- *
- * Implemented with a backtracking two-pointer scan whose `*` handling uses a
- * single saved restart position, giving O(|str| * |pattern|) worst case with
- * no catastrophic blow-up.
- */
-export function wildcardMatch(str: string, pattern: string): boolean {
-  if (isOptionalTrailingStar(pattern)) {
-    const head = pattern.slice(0, -2); // drop the trailing " *"
-    // Head-only branch: the whole string equals the head, matched as a glob.
-    if (globMatch(str, head)) {
-      return true;
-    }
-    // Otherwise the full "<head> *" pattern must match (space is consumed).
-    return globMatch(str, pattern);
-  }
-  return globMatch(str, pattern);
-}
-
-/**
- * True when `pattern` ends in a literal space followed by `*`, and that `*`
- * is the final character. A bare `"*"` (no preceding space) is NOT treated
- * as the optional-suffix form.
- */
-function isOptionalTrailingStar(pattern: string): boolean {
-  return pattern.length >= 2 && pattern.endsWith(" *");
-}
-
-/**
- * Core anchored glob match using linear-time backtracking. Only `*` can
- * backtrack, and it uses a single restart marker (the classic two-pointer
- * algorithm), so there is no exponential backtracking.
- */
-function globMatch(str: string, pattern: string): boolean {
-  let s = 0;
-  let p = 0;
-  let starP = -1;
-  let starS = 0;
-
-  while (s < str.length) {
-    const pc = p < pattern.length ? pattern[p] : undefined;
-    if (pc === "*") {
-      // Record the restart point and tentatively consume zero chars.
-      starP = p;
-      starS = s;
-      p += 1;
-    } else if (pc === "?" || pc === str[s]) {
-      p += 1;
-      s += 1;
-    } else if (starP !== -1) {
-      // Backtrack: let the last `*` swallow one more character.
-      p = starP + 1;
-      starS += 1;
-      s = starS;
-    } else {
-      return false;
-    }
-  }
-
-  // Consume any trailing `*` segments in the pattern.
-  while (p < pattern.length && pattern[p] === "*") {
-    p += 1;
-  }
-
-  return p === pattern.length;
-}
-
-/**
- * Resolve a permission query against one or more rulesets.
- *
- * Rulesets are concatenated in argument order (no mutation) and scanned
- * front-to-back. The FIRST rule whose `permission` and `pattern` both match
- * the query (via {@link wildcardMatch}) is returned. If no rule matches, a
- * fail-safe default is returned: the queried permission/pattern with action
- * `"ask"` (unknown → ask, never silently allow).
- */
-export function evaluate(permission: string, pattern: string, ...rulesets: Ruleset[]): Rule {
-  for (const ruleset of rulesets) {
-    for (const rule of ruleset) {
-      if (wildcardMatch(permission, rule.permission) && wildcardMatch(pattern, rule.pattern)) {
-        return rule;
-      }
-    }
-  }
-  return { permission, pattern: "*", action: "ask" };
-}
-
-/**
- * Built-in command arity table. Maps a (possibly multi-word) command prefix
- * to the number of leading tokens that constitute its "human-understandable
- * command" for permission matching. Longest matching prefix wins.
- *
- * Frozen so the shared default cannot be mutated by callers.
- */
-export const BUILTIN_ARITY: Readonly<Record<string, number>> = Object.freeze({
-  git: 2,
-  npm: 2,
-  "npm run": 3,
-  docker: 2,
-  kubectl: 2,
-  cargo: 2,
-  pnpm: 2,
-  yarn: 2,
-  go: 2,
-  ls: 1,
-  cat: 1,
-  cd: 1,
-  rm: 1,
-  cp: 1,
-  mv: 1,
-  mkdir: 1,
-  echo: 1,
-  grep: 1,
-  python: 1,
-  node: 1,
-});
-
-/**
- * Extract the human-understandable command from already-split, flag-free
- * shell tokens.
- *
- * Strategy: try the longest prefix first. For `len` from `tokens.length` down
- * to 1, if `tokens.slice(0, len).join(" ")` is a key in the (merged) arity
- * table, return `tokens.slice(0, arity[thatPrefix])`. If the tokens are empty,
- * return `[]`. Otherwise default to the first token only.
- *
- * `arity` is shallow-merged OVER the built-in table; neither the caller's
- * object nor the built-in table is mutated.
- */
-export function commandPrefix(
-  tokens: string[],
-  arity?: Record<string, number> | undefined,
-): string[] {
-  if (tokens.length === 0) {
-    return [];
-  }
-  const table: Record<string, number> = { ...BUILTIN_ARITY, ...(arity ?? {}) };
-
-  for (let len = tokens.length; len >= 1; len -= 1) {
-    const prefixKey = tokens.slice(0, len).join(" ");
-    const take = table[prefixKey];
-    if (take !== undefined) {
-      // Clamp to the available token count; never expand beyond the input.
-      return tokens.slice(0, Math.min(take, tokens.length));
-    }
-  }
-
-  return tokens.slice(0, 1);
-}
-
-/**
- * Derive the `pattern` to feed {@link evaluate} for a bash permission.
- *
- * Splits `command` on arbitrary whitespace, drops tokens that begin with `-`
- * (flags are not conceptually part of the command identity), applies
- * {@link commandPrefix}, and joins the result with single spaces.
- */
-export function commandPermissionKey(command: string): string {
-  const tokens = command.split(/\s+/).filter((token) => token.length > 0 && !token.startsWith("-"));
-  return commandPrefix(tokens).join(" ");
-}
+export * from "@nebutra/execution-policy";

package/src/pulsar.test.ts

@@ -0,0 +1,156 @@
+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);
+  });
+});