@nebutra/agent-runtime 0.2.0 → 0.2.2

package/src/subagents.test.ts

@@ -1,290 +0,0 @@
-import { describe, expect, it } from "vitest";
-import type { Definition, Frontmatter } from "./definitions";
-import { DefinitionResolver } from "./definitions";
-import type { ThreadItem, TurnUsage } from "./model";
-import {
-  assertNotPeeking,
-  prepareDispatch,
-  resolveSubagentTools,
-  type SubagentRecord,
-  settleDeferred,
-  TaskRegistry,
-} from "./subagents";
-
-const fm = (over: Partial<Frontmatter> = {}): Frontmatter => ({
-  name: "researcher",
-  description: "",
-  allowedTools: [],
-  disallowedTools: [],
-  argNames: [],
-  modelInvocable: true,
-  userInvocable: true,
-  executionMode: "fork",
-  paths: [],
-  ...over,
-});
-
-const def = (over: Partial<Frontmatter> = {}, slug = "researcher"): SubagentRecord => ({
-  slug,
-  tenantId: "org_1",
-  sourceTier: "workspace",
-  frontmatter: fm(over),
-  bodyRef: "ref://researcher",
-});
-
-const usage: TurnUsage = {
-  inputTokens: 10,
-  cachedInputTokens: 0,
-  outputTokens: 5,
-  reasoningOutputTokens: 0,
-};
-
-const msg = (id: string, text: string): ThreadItem => ({ id, type: "agent_message", text });
-
-describe("resolveSubagentTools", () => {
-  it("computes allow minus deny", () => {
-    const tools = resolveSubagentTools(
-      fm({ allowedTools: ["read", "write", "exec"], disallowedTools: ["exec"] }),
-      ["read", "write", "exec", "search"],
-    );
-    expect(tools).toEqual(["read", "write"]);
-  });
-
-  it("falls back to all-except-deny when allow empty", () => {
-    const tools = resolveSubagentTools(fm({ allowedTools: [], disallowedTools: ["exec"] }), [
-      "read",
-      "write",
-      "exec",
-    ]);
-    expect(tools).toEqual(["read", "write"]);
-  });
-
-  it("intersects allow with the universe (no phantom tools)", () => {
-    const tools = resolveSubagentTools(fm({ allowedTools: ["read", "ghost"] }), ["read", "write"]);
-    expect(tools).toEqual(["read"]);
-  });
-});
-
-describe("prepareDispatch spawn", () => {
-  it("throws when brief missing in spawn mode", () => {
-    expect(() =>
-      prepareDispatch({
-        definition: def(),
-        mode: "spawn",
-        brief: "",
-        ctx: { tenantId: "org_1" },
-      }),
-    ).toThrow(/brief/i);
-  });
-
-  it("starts with zero inherited context", () => {
-    const parentItems = [msg("p1", "parent secret")];
-    const out = prepareDispatch({
-      definition: def({ allowedTools: ["read"] }),
-      mode: "spawn",
-      parentItems,
-      brief: "do the thing",
-      ctx: { tenantId: "org_1" },
-      allTools: ["read", "write"],
-    });
-    expect(out.initialContext).toHaveLength(1);
-    expect(out.initialContext[0]).toMatchObject({ type: "agent_message" });
-    expect(JSON.stringify(out.initialContext)).not.toContain("parent secret");
-    expect(out.toolScope).toEqual(["read"]);
-  });
-
-  it("passes model override through", () => {
-    const out = prepareDispatch({
-      definition: def({ model: "fast-tier" }),
-      mode: "spawn",
-      brief: "go",
-      ctx: { tenantId: "org_1" },
-    });
-    expect(out.modelOverride).toBe("fast-tier");
-  });
-});
-
-describe("prepareDispatch fork", () => {
-  it("inherits parentItems with incomplete tool calls filtered", () => {
-    const parentItems: ThreadItem[] = [
-      msg("a", "hello"),
-      {
-        id: "tc1",
-        type: "mcp_tool_call",
-        server: "s",
-        tool: "t",
-        arguments: {},
-        status: "completed",
-      },
-      msg("b", "world"),
-      {
-        id: "tc2",
-        type: "mcp_tool_call",
-        server: "s",
-        tool: "t",
-        arguments: {},
-        status: "in_progress",
-      },
-    ];
-    const snapshot = JSON.stringify(parentItems);
-    const out = prepareDispatch({
-      definition: def(),
-      mode: "fork",
-      parentItems,
-      brief: "continue",
-      ctx: { tenantId: "org_1" },
-    });
-    const ids = out.initialContext.map((i) => i.id);
-    expect(ids).toContain("a");
-    expect(ids).toContain("tc1");
-    expect(ids).toContain("b");
-    expect(ids).not.toContain("tc2");
-    // brief appended as a directive
-    expect(out.initialContext.at(-1)).toMatchObject({ type: "agent_message" });
-    // parentItems untouched
-    expect(JSON.stringify(parentItems)).toBe(snapshot);
-  });
-
-  it("fork without parentItems yields just the directive", () => {
-    const out = prepareDispatch({
-      definition: def(),
-      mode: "fork",
-      brief: "lone directive",
-      ctx: { tenantId: "org_1" },
-    });
-    expect(out.initialContext).toHaveLength(1);
-  });
-});
-
-describe("DispatchEnvelope sync normalization", () => {
-  it("normalizes empty content to an explicit marker item", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    const env = settleDeferred(
-      { taskId: id, channel: "ch", tenantId: "org_1", registry: reg },
-      [],
-      usage,
-    );
-    expect(env.kind).toBe("sync");
-    if (env.kind === "sync") {
-      expect(env.content).toHaveLength(1);
-      expect(env.content[0]).toMatchObject({ type: "error" });
-      expect(env.agentId).toBe(id);
-    }
-  });
-
-  it("settleDeferred yields sync shape with metrics", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    const env = settleDeferred(
-      { taskId: id, channel: "ch", tenantId: "org_1", registry: reg },
-      [
-        msg("r1", "result"),
-        {
-          id: "u1",
-          type: "mcp_tool_call",
-          server: "s",
-          tool: "t",
-          arguments: {},
-          status: "completed",
-        },
-      ],
-      usage,
-    );
-    expect(env.kind).toBe("sync");
-    if (env.kind === "sync") {
-      expect(env.content).toHaveLength(2);
-      expect(env.toolUses).toBe(1);
-      expect(env.usage).toEqual(usage);
-      expect(env.durationMs).toBeGreaterThanOrEqual(0);
-    }
-    expect(reg.get(id, "org_1")?.status).toBe("completed");
-  });
-});
-
-describe("assertNotPeeking", () => {
-  it("throws while task is in-flight", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    expect(() => assertNotPeeking(reg.get(id, "org_1")!)).toThrow(/in-flight|peek/i);
-  });
-
-  it("does not throw once settled", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    reg.transition(id, "completed", "org_1");
-    expect(() => assertNotPeeking(reg.get(id, "org_1")!)).not.toThrow();
-  });
-});
-
-describe("TaskRegistry state machine + tenancy", () => {
-  it("creates prefixed ids", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    expect(id.startsWith("task_")).toBe(true);
-  });
-
-  it("allows legal transitions", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    reg.transition(id, "completed", "org_1");
-    expect(reg.get(id, "org_1")?.status).toBe("completed");
-  });
-
-  it("rejects illegal transitions", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    reg.transition(id, "completed", "org_1");
-    expect(() => reg.transition(id, "running", "org_1")).toThrow(/transition/i);
-  });
-
-  it("stop() kills a task", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    reg.transition(id, "running", "org_1");
-    reg.stop(id, "org_1");
-    expect(reg.get(id, "org_1")?.status).toBe("killed");
-  });
-
-  it("fails closed on cross-tenant access", () => {
-    const reg = new TaskRegistry();
-    const id = reg.create("org_1", "subagent");
-    expect(() => reg.transition(id, "running", "org_2")).toThrow(/tenant/i);
-    expect(() => reg.stop(id, "org_2")).toThrow(/tenant/i);
-    expect(reg.get(id, "org_2")).toBeUndefined();
-  });
-
-  it("throws on empty tenant", () => {
-    const reg = new TaskRegistry();
-    expect(() => reg.create("", "subagent")).toThrow(/tenant/i);
-    const id = reg.create("org_1", "subagent");
-    expect(() => reg.transition(id, "running", "")).toThrow(/tenant/i);
-    expect(() => reg.get(id, "")).toThrow(/tenant/i);
-  });
-
-  it("prepareDispatch fails closed on tenant mismatch", () => {
-    const d: SubagentRecord = def();
-    expect(() =>
-      prepareDispatch({
-        definition: d,
-        mode: "spawn",
-        brief: "x",
-        ctx: { tenantId: "org_2" },
-      }),
-    ).toThrow(/tenant/i);
-  });
-
-  it("resolver-backed registry is reusable as a DefinitionResolver", () => {
-    const resolver = new DefinitionResolver<SubagentRecord>([def(), def({}, "writer")]);
-    const resolved = resolver.resolveOne("researcher", { tenantId: "org_1" });
-    expect(resolved?.slug).toBe("researcher");
-    const d: Definition | undefined = resolved;
-    expect(d).toBeDefined();
-  });
-});

package/src/subagents.ts

@@ -1,332 +0,0 @@
-/**
- * Subagent / task dispatch (WRAP — isolated-child-agent model, the delta).
- *
- * Faithful re-expression of the source harness's child-agent dispatch grammar:
- * a registry decides WHICH definition runs, a context-boundary contract decides
- * WITH WHAT inherited context it starts, and a typed terminal envelope decides
- * HOW its result re-enters the parent. The child loop, child policy, and
- * rollout store live elsewhere in agent-runtime and are intentionally NOT
- * reimplemented here — this layer is pure decision + data + state machine.
- *
- * Multi-tenant: every task operation is keyed by `tenantId` and fails closed.
- * Pure data/logic — no FS scan, no shell, no network.
- *
- * NOTE on dropped task kinds: the source harness models several local execution
- * task kinds (local_bash / monitor_mcp / worktree). Those are deliberately NOT
- * represented here: this package never executes locally — execution is delegated
- * via the external-sandbox seam — so only the agent-facing `subagent` kind (and
- * its `deferred` sibling) is modelled.
- */
-
-import { z } from "zod";
-import type { Definition, Frontmatter } from "./definitions";
-import type { ThreadItem, TurnUsage } from "./model";
-
-/* ───────────────────────── Subagent definition ─────────────────────────── */
-
-/** A subagent definition is just a `Definition` (same loader as skills/commands). */
-export type SubagentRecord = Definition;
-
-/**
- * Effective tool set for a subagent: `allowedTools` minus `disallowedTools`,
- * intersected with the runtime tool universe so a definition can never widen
- * its scope past what the host exposes. When `allowedTools` is empty the
- * contract is "all tools except the denied ones" (all-except-deny).
- *
- * Pure — order follows `allTools` for determinism.
- */
-export function resolveSubagentTools(fm: Frontmatter, allTools: readonly string[]): string[] {
-  const deny = new Set(fm.disallowedTools);
-  const allow = fm.allowedTools;
-  if (allow.length === 0) {
-    return allTools.filter((t) => !deny.has(t));
-  }
-  const allowSet = new Set(allow);
-  return allTools.filter((t) => allowSet.has(t) && !deny.has(t));
-}
-
-/* ───────────────────── Context-boundary contract ───────────────────────── */
-
-export type DispatchMode = "spawn" | "fork";
-
-export interface DispatchCtx {
-  readonly tenantId: string;
-}
-
-export interface PrepareDispatchInput {
-  readonly definition: SubagentRecord;
-  readonly mode: DispatchMode;
-  readonly parentItems?: readonly ThreadItem[];
-  /** Caller's directive. Mandatory & non-empty in `spawn` mode. */
-  readonly brief: string;
-  readonly ctx: DispatchCtx;
-  /** Runtime tool universe; defaults to the definition's own allow list. */
-  readonly allTools?: readonly string[];
-}
-
-export interface PreparedDispatch {
-  readonly initialContext: readonly ThreadItem[];
-  readonly toolScope: readonly string[];
-  /** Opaque reference to the system prompt body (resolved by the child loop). */
-  readonly systemPromptRef: string;
-  readonly modelOverride?: string;
-}
-
-/** True for a trailing tool-call item that never received a terminal result. */
-function isIncompleteToolCall(item: ThreadItem): boolean {
-  if (item.type === "mcp_tool_call" || item.type === "command_execution") {
-    return item.status === "in_progress";
-  }
-  return false;
-}
-
-/**
- * Drop trailing incomplete tool-call items so a forked child never inherits a
- * dangling tool_use without its result. Pure — input array is never mutated.
- */
-function filterIncompleteToolCalls(items: readonly ThreadItem[]): ThreadItem[] {
-  return items.filter((it) => !isIncompleteToolCall(it));
-}
-
-function directiveItem(idSeed: string, brief: string): ThreadItem {
-  return { id: `brief_${idSeed}`, type: "agent_message", text: brief };
-}
-
-/**
- * Decide the child's starting context boundary.
- *
- * - `spawn`: zero inherited context. The caller MUST fully brief the child;
- *   an empty brief is a programming error and throws.
- * - `fork`: inherit a defensive copy of `parentItems` with incomplete tool
- *   calls filtered out, then append the brief as a directive.
- *
- * `parentItems` is never mutated. Cross-tenant dispatch fails closed.
- */
-export function prepareDispatch(input: PrepareDispatchInput): PreparedDispatch {
-  const { definition, mode, parentItems, brief, ctx, allTools } = input;
-  if (!ctx.tenantId) throw new Error("DispatchCtx.tenantId is required");
-  if (definition.tenantId !== ctx.tenantId) {
-    throw new Error("subagent definition belongs to a different tenant (fail closed)");
-  }
-
-  const trimmedBrief = brief.trim();
-  const fm = definition.frontmatter;
-  const toolScope = resolveSubagentTools(fm, allTools ?? fm.allowedTools);
-
-  let initialContext: ThreadItem[];
-  if (mode === "spawn") {
-    if (!trimmedBrief) {
-      throw new Error(
-        "spawn dispatch requires a non-empty brief — caller must fully brief the child",
-      );
-    }
-    initialContext = [directiveItem(definition.slug, trimmedBrief)];
-  } else {
-    const inherited = parentItems ? filterIncompleteToolCalls(parentItems) : [];
-    initialContext = trimmedBrief
-      ? [...inherited, directiveItem(definition.slug, trimmedBrief)]
-      : [...inherited];
-  }
-
-  const modelOverride = fm.model && fm.model !== "inherit" ? fm.model : undefined;
-
-  return {
-    initialContext,
-    toolScope,
-    systemPromptRef: definition.bodyRef,
-    ...(modelOverride ? { modelOverride } : {}),
-  };
-}
-
-/* ─────────────────── Uniform Task lifecycle registry ───────────────────── */
-
-export const TASK_KINDS = ["subagent", "deferred"] as const;
-export type TaskKind = (typeof TASK_KINDS)[number];
-
-export const TASK_STATUSES = ["pending", "running", "completed", "failed", "killed"] as const;
-export type TaskStatus = (typeof TASK_STATUSES)[number];
-
-export interface TaskRecord {
-  readonly taskId: string;
-  readonly tenantId: string;
-  readonly status: TaskStatus;
-  readonly notified: boolean;
-  readonly kind: TaskKind;
-  readonly createdAtMs: number;
-}
-
-/** Legal status transitions. Any pair absent here is rejected. */
-const LEGAL: Readonly<Record<TaskStatus, readonly TaskStatus[]>> = {
-  pending: ["running", "killed", "failed"],
-  running: ["completed", "failed", "killed"],
-  completed: [],
-  failed: [],
-  killed: [],
-};
-
-const TERMINAL: ReadonlySet<TaskStatus> = new Set(["completed", "failed", "killed"]);
-
-let __seq = 0;
-function nextTaskId(): string {
-  __seq += 1;
-  return `task_${Date.now().toString(36)}_${__seq.toString(36)}`;
-}
-
-function requireTenant(tenantId: string): void {
-  if (!tenantId) throw new Error("tenantId is required (fail closed)");
-}
-
-/**
- * Tenant-scoped task registry. Every mutating op verifies the caller's
- * tenant against the stored record; a mismatch is treated as "not found"
- * for reads and throws for mutations — cross-tenant access is impossible.
- */
-export class TaskRegistry {
-  readonly #tasks = new Map<string, TaskRecord>();
-
-  create(tenantId: string, kind: TaskKind): string {
-    requireTenant(tenantId);
-    const taskId = nextTaskId();
-    this.#tasks.set(taskId, {
-      taskId,
-      tenantId,
-      status: "pending",
-      notified: false,
-      kind,
-      createdAtMs: Date.now(),
-    });
-    return taskId;
-  }
-
-  /** Tenant-checked read. Returns undefined for unknown or cross-tenant ids. */
-  get(taskId: string, tenantId: string): TaskRecord | undefined {
-    requireTenant(tenantId);
-    const rec = this.#tasks.get(taskId);
-    if (!rec || rec.tenantId !== tenantId) return undefined;
-    return rec;
-  }
-
-  #ownedOrThrow(taskId: string, tenantId: string): TaskRecord {
-    requireTenant(tenantId);
-    const rec = this.#tasks.get(taskId);
-    if (!rec) throw new Error(`task ${taskId} not found`);
-    if (rec.tenantId !== tenantId) {
-      throw new Error("cross-tenant task access denied (fail closed)");
-    }
-    return rec;
-  }
-
-  transition(taskId: string, to: TaskStatus, tenantId: string): TaskRecord {
-    const rec = this.#ownedOrThrow(taskId, tenantId);
-    const allowed = LEGAL[rec.status];
-    if (!allowed.includes(to)) {
-      throw new Error(`illegal task transition ${rec.status} → ${to}`);
-    }
-    const next: TaskRecord = { ...rec, status: to };
-    this.#tasks.set(taskId, next);
-    return next;
-  }
-
-  /** Unified kill — drives any non-terminal task to `killed`. */
-  stop(taskId: string, tenantId: string): TaskRecord {
-    const rec = this.#ownedOrThrow(taskId, tenantId);
-    if (TERMINAL.has(rec.status)) return rec;
-    return this.transition(taskId, "killed", tenantId);
-  }
-
-  markNotified(taskId: string, tenantId: string): TaskRecord {
-    const rec = this.#ownedOrThrow(taskId, tenantId);
-    const next: TaskRecord = { ...rec, notified: true };
-    this.#tasks.set(taskId, next);
-    return next;
-  }
-}
-
-/**
- * No-peek / no-race guard. Throws if a parent tries to read an in-flight
- * deferred task's transcript before it has settled.
- */
-export function assertNotPeeking(task: TaskRecord): void {
-  if (!TERMINAL.has(task.status)) {
-    throw new Error(
-      `cannot peek at in-flight task ${task.taskId} (status=${task.status}); await settlement`,
-    );
-  }
-}
-
-/* ─────────────── Typed terminal-envelope result contract ────────────────── */
-
-export interface SyncEnvelope {
-  readonly kind: "sync";
-  readonly content: readonly ThreadItem[];
-  readonly usage: TurnUsage;
-  readonly agentId: string;
-  readonly toolUses: number;
-  readonly durationMs: number;
-}
-
-export interface DeferredEnvelope {
-  readonly kind: "deferred";
-  readonly taskId: string;
-  readonly channel: string;
-}
-
-export type DispatchEnvelope = SyncEnvelope | DeferredEnvelope;
-
-const NO_OUTPUT_MARKER: ThreadItem = {
-  id: "subagent_no_output",
-  type: "error",
-  message: "subagent completed but returned no output",
-};
-
-const threadItemShape = z.object({ id: z.string(), type: z.string() });
-
-/** Empty content is never silently empty — normalize to one explicit marker. */
-function normalizeContent(content: readonly ThreadItem[]): readonly ThreadItem[] {
-  for (const item of content) threadItemShape.parse(item);
-  return content.length === 0 ? [NO_OUTPUT_MARKER] : content;
-}
-
-function countToolUses(content: readonly ThreadItem[]): number {
-  return content.filter((i) => i.type === "mcp_tool_call" || i.type === "command_execution").length;
-}
-
-/** Build a fire-and-forget deferred envelope for a registered task. */
-export function makeDeferred(taskId: string, channel: string): DeferredEnvelope {
-  if (!channel) throw new Error("deferred envelope requires a delivery channel");
-  return { kind: "deferred", taskId, channel };
-}
-
-export interface SettleDeferredTarget {
-  readonly taskId: string;
-  readonly channel: string;
-  readonly tenantId: string;
-  readonly registry: TaskRegistry;
-}
-
-/**
- * Settle a previously-deferred task: drive it to `completed` (tenant-checked)
- * and produce the eventual sync-shaped result. Empty content is normalized to
- * the explicit no-output marker.
- */
-export function settleDeferred(
-  target: SettleDeferredTarget,
-  content: readonly ThreadItem[],
-  usage: TurnUsage,
-): SyncEnvelope {
-  const { taskId, tenantId, registry } = target;
-  const rec = registry.get(taskId, tenantId);
-  if (!rec) throw new Error("cannot settle unknown or cross-tenant task (fail closed)");
-  if (!TERMINAL.has(rec.status)) {
-    registry.transition(taskId, "completed", tenantId);
-  }
-  const normalized = normalizeContent(content);
-  return {
-    kind: "sync",
-    content: normalized,
-    usage,
-    agentId: taskId,
-    toolUses: countToolUses(normalized),
-    durationMs: Math.max(0, Date.now() - rec.createdAtMs),
-  };
-}