macro-agent 0.2.4 → 0.2.6

package/src/adapters/types.ts

@@ -1,286 +0,0 @@
-/**
- * Adapter interfaces for subsystem integration.
- *
- * InboxAdapter wraps agent-inbox for messaging.
- * TasksAdapter wraps opentasks for task management.
- *
- * These are the only two touch points between macro-agent
- * and the external subsystems.
- *
- * @module adapters/types
- */
-
-import type { Message, MessageContent, Importance } from "agent-inbox";
-
-// ─────────────────────────────────────────────────────────────────
-// InboxAdapter
-// ─────────────────────────────────────────────────────────────────
-
-/**
- * Event emitted when a message is delivered to an agent's inbox.
- */
-export interface InboxDeliveryEvent {
-  /** Recipient agent ID */
-  agentId: string;
-  /** Recipient kind (to, cc, bcc) */
-  recipientKind: "to" | "cc" | "bcc";
-  /** The delivered message */
-  message: Message;
-}
-
-/**
- * Signal filter: returns false to suppress delivery to a specific agent.
- * Used by TeamRuntime to enforce subscription-based signal filtering.
- */
-export type SignalFilterFn = (
-  from: string,
-  to: string,
-  message: Message
-) => boolean;
-
-/**
- * Emission validator: returns a rejection reason string to block the send,
- * or null to allow it. Used by TeamRuntime to enforce per-role emission rules.
- */
-export type EmissionValidatorFn = (
-  from: string,
-  message: Message
-) => string | null;
-
-/**
- * Options for registering an agent with agent-inbox.
- */
-export interface RegisterAgentOptions {
-  name?: string;
-  role: string;
-  scope: string;
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Options for sending a message through agent-inbox.
- */
-export interface SendMessageOptions {
-  threadTag?: string;
-  importance?: Importance;
-  scope?: string;
-  subject?: string;
-  inReplyTo?: string;
-}
-
-/**
- * Delivery event handler callback.
- */
-export type DeliveryHandler = (event: InboxDeliveryEvent) => void;
-
-/**
- * InboxAdapter — macro-agent's interface to agent-inbox.
- *
- * Owns adapter-side signal filtering and emission validation.
- * Embeds agent-inbox in-process for zero-latency event access,
- * with IPC server running for agent MCP subprocesses.
- */
-export interface InboxAdapter {
-  // ── Agent Lifecycle ──────────────────────────────────────────
-
-  /** Register an agent in agent-inbox's storage and warm registry. */
-  registerAgent(
-    agentId: string,
-    opts: RegisterAgentOptions
-  ): Promise<void>;
-
-  /** Deregister an agent (set status to offline). */
-  deregisterAgent(agentId: string): Promise<void>;
-
-  // ── Messaging ────────────────────────────────────────────────
-
-  /**
-   * Send a message. Emission validation runs before forwarding
-   * to agent-inbox. Returns the message ID on success.
-   *
-   * @throws if emission validator rejects the send.
-   */
-  send(
-    from: string,
-    to: string | string[],
-    content: MessageContent | string,
-    opts?: SendMessageOptions
-  ): Promise<string>;
-
-  // ── Delivery Subscription ────────────────────────────────────
-
-  /**
-   * Subscribe to delivery events. Signal filtering runs before
-   * invoking the handler — filtered messages are silently dropped.
-   */
-  onDelivery(handler: DeliveryHandler): void;
-
-  /** Remove a delivery handler. */
-  offDelivery(handler: DeliveryHandler): void;
-
-  // ── Queries ──────────────────────────────────────────────────
-
-  /** Check an agent's inbox. */
-  checkInbox(
-    agentId: string,
-    opts?: { unreadOnly?: boolean; limit?: number }
-  ): Promise<Message[]>;
-
-  /** Read a message thread by tag. */
-  readThread(
-    threadTag: string,
-    scope?: string
-  ): Promise<Message[]>;
-
-  // ── Policy Hooks (set by TeamRuntime) ────────────────────────
-
-  /** Install a signal filter (replaces any existing filter). */
-  setSignalFilter(filter: SignalFilterFn): void;
-
-  /** Install an emission validator (replaces any existing validator). */
-  setEmissionValidator(validator: EmissionValidatorFn): void;
-
-  // ── Multi-Team Policy Hooks ─────────────────────────────────
-
-  /** Add a named signal filter (for multi-team). */
-  addSignalFilter(id: string, filter: SignalFilterFn): void;
-
-  /** Remove a named signal filter. */
-  removeSignalFilter(id: string): void;
-
-  /** Add a named emission validator (for multi-team). */
-  addEmissionValidator(id: string, validator: EmissionValidatorFn): void;
-
-  /** Remove a named emission validator. */
-  removeEmissionValidator(id: string): void;
-
-  // ── Lifecycle ────────────────────────────────────────────────
-
-  /** The IPC socket path for agent subprocesses to connect to. */
-  readonly socketPath: string;
-
-  /** Stop the embedded agent-inbox (IPC server, storage, etc.). */
-  stop(): Promise<void>;
-}
-
-// ─────────────────────────────────────────────────────────────────
-// TasksAdapter
-// ─────────────────────────────────────────────────────────────────
-
-/**
- * Task status values used by macro-agent.
- * Maps to opentasks canonical statuses.
- */
-export type TaskStatus = "open" | "in_progress" | "blocked" | "closed";
-
-/**
- * Semantic actions for task state transitions.
- */
-export type TaskAction = "start" | "complete" | "fail" | "block" | "reopen";
-
-/**
- * Options for creating a task.
- */
-export interface CreateTaskOptions {
-  title: string;
-  content?: string;
-  assignee?: string;
-  parent?: string;
-  tags?: string[];
-  priority?: number;
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Options for querying tasks.
- */
-export interface TaskQueryOptions {
-  status?: TaskStatus;
-  assignee?: string;
-  tags?: string[];
-  limit?: number;
-}
-
-/**
- * Simplified task record returned by the adapter.
- * Flattened from opentasks' graph node model.
- */
-export interface TaskRecord {
-  id: string;
-  title: string;
-  content?: string;
-  status: TaskStatus;
-  assignee?: string;
-  parent?: string;
-  tags?: string[];
-  priority?: number;
-  claimed_by?: string;
-  created_at?: string;
-  closed_at?: string;
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * TasksAdapter — macro-agent's interface to opentasks.
- *
- * Wraps OpenTasksClient via IPC to the opentasks daemon.
- * macro-agent ensures the daemon is running at boot.
- */
-export interface TasksAdapter {
-  // ── Task Lifecycle ───────────────────────────────────────────
-
-  /** Create a new task. Returns the task ID. */
-  createTask(opts: CreateTaskOptions): Promise<string>;
-
-  /** Assign a task to an agent. */
-  assignTask(taskId: string, agentId: string): Promise<void>;
-
-  /** Transition a task to a new state via semantic action. */
-  transitionTask(taskId: string, action: TaskAction): Promise<void>;
-
-  // ── Queries ──────────────────────────────────────────────────
-
-  /** Get a single task by ID. */
-  getTask(taskId: string): Promise<TaskRecord>;
-
-  /** Query tasks ready to work on (no active blockers). */
-  queryReady(opts?: { tags?: string[]; limit?: number }): Promise<TaskRecord[]>;
-
-  /** List tasks with optional filters. */
-  listTasks(filter?: TaskQueryOptions): Promise<TaskRecord[]>;
-
-  // ── Dependencies ─────────────────────────────────────────────
-
-  /** Add a blocking dependency: blockerId blocks taskId. */
-  addBlocker(taskId: string, blockerId: string): Promise<void>;
-
-  /** Remove a blocking dependency. */
-  removeBlocker(taskId: string, blockerId: string): Promise<void>;
-
-  // ── Pull Mode (claim-based) ──────────────────────────────────
-
-  /** Claim the next available task matching the filter. */
-  claimTask(
-    agentId: string,
-    filter?: { tags?: string[] }
-  ): Promise<TaskRecord | null>;
-
-  /** Release a claimed task back to the pool. */
-  unclaimTask(taskId: string): Promise<void>;
-
-  /** List tasks available for claiming. */
-  listClaimable(
-    filter?: { tags?: string[]; limit?: number }
-  ): Promise<TaskRecord[]>;
-
-  // ── Connection Lifecycle ─────────────────────────────────────
-
-  /** Connect to the opentasks daemon. Auto-starts if needed. */
-  connect(): Promise<void>;
-
-  /** Disconnect from the opentasks daemon. */
-  disconnect(): void;
-
-  /** Whether the adapter is connected to the daemon. */
-  readonly connected: boolean;
-}

package/src/agent/__tests__/agent-manager-topology.test.ts

@@ -1,73 +0,0 @@
-/**
- * AgentManagerV2 + TopologyPolicy integration (Phase 4).
- *
- * Verifies that when a TopologyPolicy is set, workspace allocation goes
- * through the V3 path (YamlDrivenTopology → WorkspaceDecision → V3 methods).
- * When unset, legacy role-name dispatch is preserved (regression guard).
- */
-
-import { describe, it, expect, beforeEach, vi } from 'vitest';
-import { YamlDrivenTopology } from '../../workspace/topology/yaml-driven.js';
-import { parseTeamWorkspaceConfig } from '../../workspace/yaml-schema.js';
-
-// Isolated test: verify the TopologyPolicy → WorkspaceDecision compilation
-// happens when policy is set. Full AgentManagerV2 spawn integration is
-// covered by E2E tests; here we validate the delegation logic in isolation.
-
-describe('AgentManagerV2 + TopologyPolicy (Phase 4)', () => {
-  describe('policy presence', () => {
-    it('YamlDrivenTopology is the primary policy for declarative teams', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          peer: {
-            workspace: 'new_stream',
-            stream_lineage: 'fork_from_team_root',
-          },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-
-      // Policy name is stable (used for introspection)
-      expect(topology.name).toBe('yaml-driven');
-    });
-
-    it('onAgentSpawn is invocable via policy reference', async () => {
-      const config = parseTeamWorkspaceConfig({
-        roles: {
-          peer: { workspace: 'none' },
-        },
-      });
-      const topology = new YamlDrivenTopology(config!);
-
-      const mockWs = {
-        createStreamV3: vi.fn(() => 'stream-1'),
-        allocateWorktree: vi.fn(),
-      } as unknown as import('../../workspace/types.js').WorkspaceManager;
-
-      await topology.onTeamStart({
-        teamName: 't',
-        teamInstanceId: 't-1',
-        workspaceConfig: config,
-        workspaceManager: mockWs,
-      });
-
-      const decision = await topology.onAgentSpawn({
-        agentId: 'a1',
-        role: 'peer',
-        workspaceManager: mockWs,
-      });
-
-      expect(decision.kind).toBe('none');
-    });
-  });
-
-  describe('policy absence (legacy path)', () => {
-    it('policy=null means AgentManagerV2 uses role-name dispatch (regression guard)', () => {
-      // This test documents the behavior contract: when
-      // setTopologyPolicy(null) or never called, the legacy switch(role)
-      // path in agent-manager-v2.ts:createWorkspaceForRole is the active
-      // code path. Validated by existing E2E tests for self-driving.
-      expect(true).toBe(true);
-    });
-  });
-});

package/src/agent/__tests__/agent-manager-v2.permission-interception.test.ts

@@ -1,296 +0,0 @@
-/**
- * Unit tests for AgentManagerV2's prompt iterator permission overlay
- * interception (Phase 3). Pins the contract that:
- *
- *   - When a `permission_request` session update fires AND a per-agent
- *     overlay is set, the iterator intercepts, evaluates against the
- *     overlay, and answers via `respondToPermission`. The update is
- *     NOT yielded to the consumer.
- *   - When NO overlay is set, the update IS yielded through (chat
- *     surfaces' UI permission dialogs depend on this).
- *   - Overlay errors fail closed (deny).
- *   - Non-permission_request updates pass through unchanged.
- */
-
-import {
-  describe,
-  it,
-  expect,
-  vi,
-  beforeEach,
-  afterEach,
-} from "vitest";
-
-const createSessionSpy = vi.fn();
-let mockSessionPrompt: ((message: string) => AsyncIterable<unknown>) | null =
-  null;
-const respondToPermissionSpy = vi.fn();
-
-vi.mock("acp-factory", () => ({
-  AgentFactory: {
-    spawn: vi.fn().mockResolvedValue({
-      createSession: (...args: unknown[]) => {
-        createSessionSpy(...args);
-        return Promise.resolve({
-          id: "provider-session-1",
-          prompt: vi.fn().mockImplementation(
-            (message: string) => mockSessionPrompt?.(message) ?? emptyIterable(),
-          ),
-          respondToPermission: respondToPermissionSpy,
-        });
-      },
-      close: vi.fn().mockResolvedValue(undefined),
-      isRunning: vi.fn().mockReturnValue(true),
-    }),
-  },
-}));
-
-import { createAgentManagerV2 } from "../agent-manager-v2.js";
-import { AgentStore } from "../agent-store.js";
-import type { AgentManager } from "../agent-manager.js";
-import type { InboxAdapter, TasksAdapter } from "../../adapters/types.js";
-import {
-  setPermissionOverlay,
-  clearPermissionOverlay,
-} from "../../dispatch/permission-overlay.js";
-
-function emptyIterable<T>(): AsyncIterable<T> {
-  return {
-    [Symbol.asyncIterator]: () => ({
-      next: () => Promise.resolve({ done: true, value: undefined as never }),
-    }),
-  };
-}
-
-function fromArray<T>(items: T[]): AsyncIterable<T> {
-  let i = 0;
-  return {
-    [Symbol.asyncIterator]: () => ({
-      next: () => {
-        if (i < items.length) {
-          return Promise.resolve({ done: false, value: items[i++]! });
-        }
-        return Promise.resolve({ done: true, value: undefined as never });
-      },
-    }),
-  };
-}
-
-function permRequest(opts: {
-  requestId: string;
-  toolTitle: string;
-  toolKind?: string;
-  rawInput?: unknown;
-}): unknown {
-  return {
-    sessionUpdate: "permission_request",
-    requestId: opts.requestId,
-    toolCall: {
-      toolCallId: "tc-1",
-      title: opts.toolTitle,
-      kind: opts.toolKind ?? "read",
-      status: "pending",
-      rawInput: opts.rawInput ?? {},
-    },
-    options: [
-      { kind: "allow_always", optionId: "allow_always" },
-      { kind: "allow_once", optionId: "allow" },
-      { kind: "reject_once", optionId: "reject" },
-    ],
-  };
-}
-
-function createMockInboxAdapter(): InboxAdapter {
-  return {
-    registerAgent: vi.fn().mockResolvedValue(undefined),
-    deregisterAgent: vi.fn().mockResolvedValue(undefined),
-    send: vi.fn().mockResolvedValue("msg-1"),
-    onDelivery: vi.fn(),
-    offDelivery: vi.fn(),
-    checkInbox: vi.fn().mockResolvedValue([]),
-    readThread: vi.fn().mockResolvedValue([]),
-    setSignalFilter: vi.fn(),
-    setEmissionValidator: vi.fn(),
-    socketPath: "/tmp/test-inbox.sock",
-    stop: vi.fn().mockResolvedValue(undefined),
-  } as unknown as InboxAdapter;
-}
-
-function createMockTasksAdapter(): TasksAdapter {
-  return {
-    createTask: vi.fn().mockResolvedValue("ot-task-1"),
-    assignTask: vi.fn().mockResolvedValue(undefined),
-    transitionTask: vi.fn().mockResolvedValue(undefined),
-    getTask: vi.fn().mockResolvedValue({ id: "t-1", title: "x", status: "open" }),
-    queryReady: vi.fn().mockResolvedValue([]),
-    listTasks: vi.fn().mockResolvedValue([]),
-    addBlocker: vi.fn().mockResolvedValue(undefined),
-    removeBlocker: vi.fn().mockResolvedValue(undefined),
-    claimTask: vi.fn().mockResolvedValue(null),
-    unclaimTask: vi.fn().mockResolvedValue(undefined),
-    listClaimable: vi.fn().mockResolvedValue([]),
-    connect: vi.fn().mockResolvedValue(undefined),
-    disconnect: vi.fn(),
-    connected: true,
-  } as unknown as TasksAdapter;
-}
-
-describe("AgentManagerV2 prompt iterator — permission overlay interception", () => {
-  let agentStore: AgentStore;
-  let inboxAdapter: InboxAdapter;
-  let tasksAdapter: TasksAdapter;
-  let manager: AgentManager;
-
-  beforeEach(() => {
-    createSessionSpy.mockClear();
-    respondToPermissionSpy.mockClear();
-    mockSessionPrompt = null;
-    agentStore = new AgentStore(":memory:");
-    inboxAdapter = createMockInboxAdapter();
-    tasksAdapter = createMockTasksAdapter();
-    manager = createAgentManagerV2(agentStore, inboxAdapter, tasksAdapter, {
-      defaultCwd: "/tmp/test",
-    });
-  });
-
-  afterEach(async () => {
-    await manager.close();
-    agentStore.close();
-  });
-
-  it("overlay set + deny rule matches → respondToPermission called with reject; update NOT yielded", async () => {
-    const spawned = await manager.spawn({ task: "Test", role: "worker" });
-    setPermissionOverlay(spawned.id, {
-      deny: ["Read(/tmp/secret.txt)"],
-    });
-    try {
-      mockSessionPrompt = () =>
-        fromArray([
-          permRequest({
-            requestId: "req-1",
-            toolTitle: "Read /tmp/secret.txt",
-            toolKind: "read",
-            rawInput: { file_path: "/tmp/secret.txt" },
-          }),
-        ]);
-
-      const yielded: unknown[] = [];
-      for await (const update of manager.prompt(spawned.id, "do it")) {
-        yielded.push(update);
-      }
-
-      expect(respondToPermissionSpy).toHaveBeenCalledTimes(1);
-      expect(respondToPermissionSpy).toHaveBeenCalledWith("req-1", "reject");
-      expect(yielded).toHaveLength(0);
-    } finally {
-      clearPermissionOverlay(spawned.id);
-    }
-  });
-
-  it("overlay set + no rule matches → respondToPermission called with allow; update NOT yielded", async () => {
-    const spawned = await manager.spawn({ task: "Test", role: "worker" });
-    setPermissionOverlay(spawned.id, {
-      deny: ["Read(/etc/*)"],
-    });
-    try {
-      mockSessionPrompt = () =>
-        fromArray([
-          permRequest({
-            requestId: "req-2",
-            toolTitle: "Read /tmp/safe.txt",
-            toolKind: "read",
-            rawInput: { file_path: "/tmp/safe.txt" },
-          }),
-        ]);
-
-      const yielded: unknown[] = [];
-      for await (const update of manager.prompt(spawned.id, "do it")) {
-        yielded.push(update);
-      }
-
-      expect(respondToPermissionSpy).toHaveBeenCalledTimes(1);
-      expect(respondToPermissionSpy).toHaveBeenCalledWith("req-2", "allow");
-      expect(yielded).toHaveLength(0);
-    } finally {
-      clearPermissionOverlay(spawned.id);
-    }
-  });
-
-  it("no overlay → permission_request IS yielded to consumer (chat path)", async () => {
-    const spawned = await manager.spawn({ task: "Test", role: "worker" });
-    // No overlay set on this agent.
-    mockSessionPrompt = () =>
-      fromArray([
-        permRequest({
-          requestId: "req-3",
-          toolTitle: "Read /tmp/anything.txt",
-          toolKind: "read",
-          rawInput: { file_path: "/tmp/anything.txt" },
-        }),
-      ]);
-
-    const yielded: Array<{ sessionUpdate?: string; requestId?: string }> = [];
-    for await (const update of manager.prompt(spawned.id, "do it")) {
-      yielded.push(update as { sessionUpdate?: string; requestId?: string });
-    }
-
-    expect(respondToPermissionSpy).not.toHaveBeenCalled();
-    expect(yielded).toHaveLength(1);
-    expect(yielded[0]?.sessionUpdate).toBe("permission_request");
-    expect(yielded[0]?.requestId).toBe("req-3");
-  });
-
-  it("non-permission_request updates always pass through to consumer", async () => {
-    const spawned = await manager.spawn({ task: "Test", role: "worker" });
-    setPermissionOverlay(spawned.id, { deny: ["Read(/secret)"] });
-    try {
-      mockSessionPrompt = () =>
-        fromArray([
-          { sessionUpdate: "agent_message_chunk", text: "hello" },
-          { sessionUpdate: "tool_call", title: "Read /tmp/x" },
-          { sessionUpdate: "agent_thought_chunk", text: "thinking" },
-        ]);
-
-      const yielded: Array<{ sessionUpdate?: string }> = [];
-      for await (const update of manager.prompt(spawned.id, "do it")) {
-        yielded.push(update as { sessionUpdate?: string });
-      }
-
-      expect(respondToPermissionSpy).not.toHaveBeenCalled();
-      expect(yielded).toHaveLength(3);
-      expect(yielded.map((u) => u.sessionUpdate)).toEqual([
-        "agent_message_chunk",
-        "tool_call",
-        "agent_thought_chunk",
-      ]);
-    } finally {
-      clearPermissionOverlay(spawned.id);
-    }
-  });
-
-  it("MCP tool — overlay rule matches by canonical mcp__ name", async () => {
-    const spawned = await manager.spawn({ task: "Test", role: "worker" });
-    setPermissionOverlay(spawned.id, {
-      deny: ["mcp__agent-inbox__list_agents"],
-    });
-    try {
-      mockSessionPrompt = () =>
-        fromArray([
-          permRequest({
-            requestId: "req-mcp",
-            toolTitle: "mcp__agent-inbox__list_agents",
-            toolKind: "other",
-            rawInput: {},
-          }),
-        ]);
-
-      for await (const _ of manager.prompt(spawned.id, "do it")) {
-        /* drain */
-      }
-
-      expect(respondToPermissionSpy).toHaveBeenCalledWith("req-mcp", "reject");
-    } finally {
-      clearPermissionOverlay(spawned.id);
-    }
-  });
-});