macro-agent 0.2.4 → 0.2.6

package/src/lifecycle/types.ts

@@ -1,260 +0,0 @@
-/**
- * Lifecycle Module Types
- *
- * Types for agent lifecycle management including done() signaling,
- * cleanup status detection, and role-specific handlers.
- *
- * @module lifecycle/types
- * @see s-32xs Self-Cleaning Workers spec
- */
-
-import type { AgentId, TaskId } from "../store/types/index.js";
-import type { TaskRef } from "git-cascade/events";
-
-// =============================================================================
-// Done Status Types
-// =============================================================================
-
-/**
- * Status values for done() signaling
- */
-export type DoneStatus = "completed" | "failed" | "blocked" | "deferred";
-
-/**
- * Cleanup status indicating workspace readiness
- */
-export interface CleanupStatus {
-  /** Whether the workspace is ready for cleanup */
-  ready: boolean;
-
-  /** Reason if not ready for cleanup */
-  reason?: string;
-
-  /** Uncommitted files if any */
-  uncommittedFiles?: string[];
-
-  /** Pending message count if any */
-  pendingMessages?: number;
-}
-
-// =============================================================================
-// Done Arguments and Results
-// =============================================================================
-
-/**
- * Arguments for the done() MCP tool
- */
-export interface DoneArgs {
-  /** Completion status */
-  status: DoneStatus;
-
-  /** Summary of work completed */
-  summary?: string;
-
-  /** Additional details */
-  details?: Record<string, unknown>;
-
-  /** Explicit cleanup status (auto-detected if not provided) */
-  cleanupStatus?: CleanupStatus;
-
-  /** Task ID to update (optional, uses agent's bound task if not specified) */
-  taskId?: TaskId;
-}
-
-/**
- * Result from the done() MCP tool
- */
-export interface DoneResult {
-  /** Whether the done operation was successful */
-  success: boolean;
-
-  /** Whether the agent should terminate after this call */
-  shouldTerminate: boolean;
-
-  /** Status that was recorded */
-  status: DoneStatus;
-
-  /** Cleanup status that was detected/used */
-  cleanupStatus: CleanupStatus;
-
-  /** Any warnings during processing */
-  warnings?: string[];
-
-  /** Error message if success is false */
-  error?: string;
-}
-
-// =============================================================================
-// Handler Context and Types
-// =============================================================================
-
-/**
- * Context provided to lifecycle handlers
- */
-export interface LifecycleContext {
-  /** ID of the agent calling done() */
-  agentId: AgentId;
-
-  /** Role name of the agent */
-  role: string;
-
-  /** Task ID if agent is bound to a task */
-  taskId?: TaskId;
-
-  /** Parent agent ID if any */
-  parentId?: AgentId;
-
-  /** Workspace path for the agent */
-  workspacePath?: string;
-
-  /** Branch name for the agent's workspace */
-  branch?: string;
-
-  /** Integration branch for merge requests (target branch) */
-  integrationBranch?: string;
-
-  /** Stream ID for the agent's workspace (used by integrators for merge queue) */
-  streamId?: string;
-
-  /** Merge request ID (for resolver workers to track which MR they're resolving) */
-  mrId?: string;
-
-  /** Resolved capabilities for the agent's role (for capability-based handler dispatch) */
-  capabilities?: string[];
-
-  /**
-   * Optional reference to an external task this agent is working on. When
-   * present, threaded into commit metadata so cascade events carry the
-   * binding (enabling task↔stream queries on the OpenHive hub).
-   *
-   * Sourced from `SpawnAgentOptions.taskRef` at spawn time and propagated
-   * via the agent manager. Late-binding (mid-session pull-mode claim) can
-   * mutate this on the live context.
-   */
-  taskRef?: TaskRef;
-}
-
-/**
- * Handler function signature for role-specific done() processing
- */
-export type DoneHandler = (
-  context: LifecycleContext,
-  args: DoneArgs,
-  cleanupStatus: CleanupStatus
-) => Promise<DoneHandlerResult>;
-
-/**
- * Result from a role-specific done handler
- */
-export interface DoneHandlerResult {
-  /** Whether to terminate the agent */
-  shouldTerminate: boolean;
-
-  /** Any signals that were emitted */
-  signalsEmitted?: string[];
-
-  /** Any cleanup actions performed */
-  cleanupActions?: string[];
-
-  /** Warnings from the handler */
-  warnings?: string[];
-}
-
-// =============================================================================
-// Handler Registry Types
-// =============================================================================
-
-/**
- * Map of role names to their done handlers
- */
-export type DoneHandlerRegistry = Map<string, DoneHandler>;
-
-/**
- * Configuration for the lifecycle module
- */
-export interface LifecycleConfig {
-  /** Whether to auto-commit uncommitted changes on done() */
-  autoCommitOnDone?: boolean;
-
-  /** Whether to auto-detect cleanup status */
-  autoDetectCleanupStatus?: boolean;
-
-  /** Default timeout for cleanup operations (ms) */
-  cleanupTimeoutMs?: number;
-}
-
-/**
- * Default lifecycle configuration
- */
-export const DEFAULT_LIFECYCLE_CONFIG: LifecycleConfig = {
-  autoCommitOnDone: false,
-  autoDetectCleanupStatus: true,
-  cleanupTimeoutMs: 30000,
-};
-
-// =============================================================================
-// Cascade Types
-// =============================================================================
-
-/**
- * Options for cascade termination
- */
-export interface CascadeOptions {
-  /** Reason for termination */
-  reason: "parent_stopped" | "self_cleanup" | "forced";
-
-  /** Whether to consolidate changes before terminating children */
-  consolidateChanges?: boolean;
-
-  /** Timeout for the cascade operation (ms) */
-  timeoutMs?: number;
-}
-
-/**
- * Result of cascade termination
- */
-export interface CascadeResult {
-  /** Number of children terminated */
-  childrenTerminated: number;
-
-  /** IDs of children that were terminated */
-  terminatedIds: AgentId[];
-
-  /** Any errors during cascade */
-  errors?: Array<{ agentId: AgentId; error: string }>;
-}
-
-// =============================================================================
-// Change Consolidation Types (Phase 6)
-// =============================================================================
-
-/**
- * Result of change consolidation during termination
- */
-export interface ConsolidationResult {
-  /** Whether the consolidation was successful */
-  success: boolean;
-
-  /** Whether changes were actually merged */
-  merged: boolean;
-
-  /** Merge commit hash if merge was performed */
-  mergeCommit?: string;
-
-  /** List of conflicting files if merge failed */
-  conflicts?: string[];
-
-  /** Error message if consolidation failed */
-  error?: string;
-}
-
-/**
- * Options for change consolidation
- */
-export interface ConsolidationOptions {
-  /** Whether to emit CONFLICT_DETECTED signal on merge failure */
-  emitConflictSignal?: boolean;
-
-  /** Custom merge commit message */
-  mergeMessage?: string;
-}

package/src/map/__tests__/cascade-bridge.test.ts

@@ -1,229 +0,0 @@
-/**
- * Unit tests for createCascadeBridge.
- *
- * Exercises the GitCascadeEvent → x-cascade/* MAP call translation directly
- * via a mock adapter + mock connection, avoiding real git operations. E2E
- * coverage lives elsewhere (workspace-v3 tests + OpenHive hub round-trips).
- */
-
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { createCascadeBridge } from '../cascade-bridge.js';
-import type {
-  GitCascadeEvent,
-  GitCascadeEventCallback,
-  GitCascadeAdapter,
-} from '../../workspace/git-cascade-adapter.js';
-import type { LifecycleBridgeConnection } from '../lifecycle-bridge.js';
-
-interface MockConnection extends LifecycleBridgeConnection {
-  calls: Array<{ method: string; params: unknown }>;
-  connected: boolean;
-}
-
-function createMockConnection(connected = true): MockConnection {
-  const calls: Array<{ method: string; params: unknown }> = [];
-  return {
-    calls,
-    connected,
-    get isConnected() {
-      return this.connected;
-    },
-    async callExtension(method: string, params?: unknown): Promise<unknown> {
-      this.calls.push({ method, params });
-      return { ok: true };
-    },
-  };
-}
-
-interface MockAdapter {
-  emit: (event: GitCascadeEvent) => void;
-  onEvent(callback: GitCascadeEventCallback): () => void;
-}
-
-function createMockAdapter(): MockAdapter {
-  const listeners = new Set<GitCascadeEventCallback>();
-  return {
-    emit(event: GitCascadeEvent) {
-      for (const listener of listeners) {
-        listener(event);
-      }
-    },
-    onEvent(callback: GitCascadeEventCallback): () => void {
-      listeners.add(callback);
-      return () => listeners.delete(callback);
-    },
-  };
-}
-
-function mkEvent<T extends GitCascadeEvent['type']>(
-  type: T,
-  data: Record<string, unknown>
-): GitCascadeEvent {
-  return { type, timestamp: Date.now(), data } as GitCascadeEvent;
-}
-
-describe('createCascadeBridge', () => {
-  let connection: MockConnection;
-  let adapter: MockAdapter;
-
-  beforeEach(() => {
-    connection = createMockConnection();
-    adapter = createMockAdapter();
-  });
-
-  async function flushMicrotasks() {
-    // The bridge's callExtension is fire-and-forget (void + .catch). Yield
-    // to the microtask queue so the promise settles before assertions.
-    await new Promise((resolve) => setImmediate(resolve));
-  }
-
-  it('forwards stream:created as x-cascade/stream.opened with snake_case params', async () => {
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(
-      mkEvent('stream:created', {
-        streamId: 's1',
-        name: 'feat',
-        agentId: 'a1',
-        baseCommit: 'base',
-        branchName: 'stream/s1',
-        metadata: { task_ref: { resource_id: 'r', node_id: 'n' } },
-      })
-    );
-    await flushMicrotasks();
-
-    expect(connection.calls).toHaveLength(1);
-    expect(connection.calls[0].method).toBe('x-cascade/stream.opened');
-    expect(connection.calls[0].params).toMatchObject({
-      stream_id: 's1',
-      name: 'feat',
-      agent_id: 'a1',
-      base_commit: 'base',
-      branch_name: 'stream/s1',
-      metadata: { task_ref: { resource_id: 'r', node_id: 'n' } },
-    });
-  });
-
-  it('forwards stream:committed with commit_hash and files_touched', async () => {
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(
-      mkEvent('stream:committed', {
-        streamId: 's1',
-        commit: 'abc',
-        changeId: 'c-123',
-        agentId: 'a',
-        messageSummary: 'feat: x',
-        filesTouched: ['a.ts', 'b.ts'],
-        parentCommit: 'base',
-      })
-    );
-    await flushMicrotasks();
-
-    expect(connection.calls[0].method).toBe('x-cascade/stream.committed');
-    expect(connection.calls[0].params).toMatchObject({
-      stream_id: 's1',
-      commit_hash: 'abc',
-      change_id: 'c-123',
-      files_touched: ['a.ts', 'b.ts'],
-      parent_commit: 'base',
-    });
-  });
-
-  it('forwards cascade:rebased with new_commits array', async () => {
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(
-      mkEvent('cascade:rebased', {
-        streamId: 'dep',
-        agentId: 'a',
-        triggeredByStreamId: 'root',
-        triggeredByAgentId: 'a',
-        newBaseCommit: 'nb',
-        newHead: 'nh',
-        newCommits: [
-          {
-            commit_hash: 'r1',
-            change_id: 'chg',
-            parent_commit: 'nb',
-            message_summary: 'rebased',
-            files_touched: ['x.ts'],
-          },
-        ],
-      })
-    );
-    await flushMicrotasks();
-
-    expect(connection.calls[0].method).toBe('x-cascade/cascade.rebased');
-    expect(connection.calls[0].params).toMatchObject({
-      stream_id: 'dep',
-      triggered_by_stream_id: 'root',
-      new_base_commit: 'nb',
-      new_head: 'nh',
-    });
-    expect((connection.calls[0].params as { new_commits: unknown[] }).new_commits).toHaveLength(1);
-  });
-
-  it('forwards cascade:completed with summary fields', async () => {
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(
-      mkEvent('cascade:completed', {
-        rootStreamId: 'root',
-        agentId: 'a',
-        strategy: 'stop_on_conflict',
-        updatedStreams: ['d1'],
-        failedStreams: [],
-        skippedStreams: [],
-      })
-    );
-    await flushMicrotasks();
-
-    expect(connection.calls[0].method).toBe('x-cascade/cascade.completed');
-    expect(connection.calls[0].params).toMatchObject({
-      root_stream_id: 'root',
-      strategy: 'stop_on_conflict',
-      updated_streams: ['d1'],
-    });
-  });
-
-  it('drops events while disconnected (standalone mode)', async () => {
-    connection.connected = false;
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(mkEvent('stream:created', { streamId: 's', name: 'n', agentId: 'a' }));
-    await flushMicrotasks();
-    expect(connection.calls).toHaveLength(0);
-  });
-
-  it('ignores events that have no MAP counterpart (e.g. worktree:created, mergeQueue:added)', async () => {
-    createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(mkEvent('worktree:created', { agentId: 'a' }));
-    adapter.emit(mkEvent('mergeQueue:added', { streamId: 's' }));
-    adapter.emit(mkEvent('task:started', { taskId: 't' }));
-    await flushMicrotasks();
-    expect(connection.calls).toHaveLength(0);
-  });
-
-  it('dispose() unsubscribes — no more forwarding after call', async () => {
-    const disposable = createCascadeBridge(connection, adapter as unknown as GitCascadeAdapter);
-    adapter.emit(mkEvent('stream:created', { streamId: 's1', name: 'x', agentId: 'a' }));
-    await flushMicrotasks();
-    expect(connection.calls).toHaveLength(1);
-
-    disposable.dispose();
-
-    adapter.emit(mkEvent('stream:created', { streamId: 's2', name: 'y', agentId: 'a' }));
-    await flushMicrotasks();
-    expect(connection.calls).toHaveLength(1);
-  });
-
-  it('swallows callExtension errors (does not throw or block the event loop)', async () => {
-    const errConnection = createMockConnection();
-    errConnection.callExtension = vi.fn().mockRejectedValue(new Error('hub broke'));
-    createCascadeBridge(errConnection, adapter as unknown as GitCascadeAdapter);
-
-    expect(() =>
-      adapter.emit(
-        mkEvent('stream:abandoned', { streamId: 's', reason: 'testing' })
-      )
-    ).not.toThrow();
-    await flushMicrotasks();
-    expect(errConnection.callExtension).toHaveBeenCalledTimes(1);
-  });
-});