macro-agent 0.2.4 → 0.2.6

package/src/lifecycle/cascade.ts

@@ -1,335 +0,0 @@
-/**
- * Cascade Termination Module
- *
- * Handles cascading termination of child agents when a parent agent completes.
- * Children are terminated depth-first (grandchildren before children).
- *
- * Change consolidation merges child branches back to parent branches.
- *
- * @module lifecycle/cascade
- * @see s-32xs Self-Cleaning Workers spec
- * @see s-bcqm Change Management spec
- */
-
-import type { AgentId } from "../store/types/index.js";
-import type {
-  CascadeOptions,
-  CascadeResult,
-  ConsolidationResult,
-  ConsolidationOptions,
-} from "./types.js";
-import type { Workspace, WorkspaceManager } from "../workspace/types.js";
-import { attemptMerge, abortMerge, getCurrentBranch } from "./cleanup.js";
-
-// =============================================================================
-// Agent Manager Interface (to avoid circular dependency)
-// =============================================================================
-
-/**
- * Minimal agent interface for cascade operations
- */
-export interface CascadeAgent {
-  id: AgentId;
-  state: "running" | "spawning" | "stopped" | "failed";
-  parent?: AgentId | null;
-}
-
-/**
- * Agent manager interface for cascade operations
- */
-export interface CascadeAgentManager {
-  /** Get children of an agent */
-  getChildren(agentId: AgentId): CascadeAgent[];
-
-  /** Terminate an agent */
-  terminate(agentId: AgentId, reason: string): Promise<void>;
-}
-
-// =============================================================================
-// Cascade Termination
-// =============================================================================
-
-/**
- * Cascade terminate all children of an agent (depth-first)
- *
- * This terminates grandchildren before children to ensure proper cleanup order.
- *
- * @param agentId - Parent agent ID
- * @param agentManager - Agent manager for terminate operations
- * @param options - Cascade options
- * @returns Cascade result with terminated agent IDs
- */
-export async function cascadeTerminateChildren(
-  agentId: AgentId,
-  agentManager: CascadeAgentManager,
-  options: CascadeOptions = { reason: "parent_stopped" }
-): Promise<CascadeResult> {
-  const terminatedIds: AgentId[] = [];
-  const errors: Array<{ agentId: AgentId; error: string }> = [];
-
-  // Get direct children
-  const children = agentManager.getChildren(agentId);
-
-  // Process each child depth-first
-  for (const child of children) {
-    // Skip already stopped agents
-    if (child.state === "stopped") {
-      continue;
-    }
-
-    try {
-      // Recursively terminate grandchildren first
-      const childCascade = await cascadeTerminateChildren(
-        child.id,
-        agentManager,
-        options
-      );
-
-      // Accumulate results from grandchildren
-      terminatedIds.push(...childCascade.terminatedIds);
-      if (childCascade.errors) {
-        errors.push(...childCascade.errors);
-      }
-
-      // Now terminate this child
-      await agentManager.terminate(child.id, options.reason);
-      terminatedIds.push(child.id);
-    } catch (error) {
-      errors.push({
-        agentId: child.id,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-
-  return {
-    childrenTerminated: terminatedIds.length,
-    terminatedIds,
-    errors: errors.length > 0 ? errors : undefined,
-  };
-}
-
-// =============================================================================
-// Change Consolidation (Phase 6)
-// =============================================================================
-
-/**
- * Workspace provider interface for change consolidation.
- * Allows injection of workspace lookup without tight coupling.
- */
-export interface WorkspaceProvider {
-  /** Get workspace for an agent */
-  getWorkspace(agentId: AgentId): Workspace | null;
-}
-
-/**
- * Terminate a child with change consolidation
- *
- * Merges the child's branch into the parent's branch before terminating.
- * If a merge conflict occurs, the merge is aborted and the child is
- * terminated with a "merge_conflict" reason.
- *
- * When a `workspaceManager` is provided AND both workspaces carry stream
- * ids, the merge is routed through `workspaceManager.mergeStream()` so
- * it flows through git-cascade's tracker — gaining a `stream.merged`
- * cascade event that propagates to the hub via CascadeBridge. This is
- * the primary observability win of A3 in the integration plan.
- *
- * Falls back to raw `attemptMerge` (unchanged behavior) when either
- * workspace lacks a stream id or no manager is passed — so
- * programmatic/legacy callers keep working unchanged.
- *
- * @param childId - Child agent to terminate
- * @param parentId - Parent agent to consolidate changes into
- * @param agentManager - Agent manager for operations
- * @param workspaceProvider - Optional workspace provider for getting agent workspaces
- * @param options - Optional consolidation options
- * @param workspaceManager - Optional workspace manager; enables cascade-
- *   event emission on the consolidation merge when both workspaces are
- *   stream-backed.
- * @returns ConsolidationResult indicating success or failure
- */
-export async function terminateWithChangeConsolidation(
-  childId: AgentId,
-  parentId: AgentId,
-  agentManager: CascadeAgentManager,
-  workspaceProvider?: WorkspaceProvider,
-  options?: ConsolidationOptions,
-  workspaceManager?: WorkspaceManager,
-  /**
-   * Optional task reference inherited from the parent agent's metadata.
-   * When provided + routing through the tracker, threaded into the
-   * `x-cascade/stream.merged` emit so the hub's cascade_merges row records
-   * which task drove the consolidation.
-   */
-  taskRef?: { resource_id: string; node_id: string }
-): Promise<ConsolidationResult> {
-  // If no workspace provider, just terminate normally
-  if (!workspaceProvider) {
-    await agentManager.terminate(childId, "parent_stopped");
-    return { success: true, merged: false };
-  }
-
-  // Get workspaces for both child and parent
-  const childWorkspace = workspaceProvider.getWorkspace(childId);
-  const parentWorkspace = workspaceProvider.getWorkspace(parentId);
-
-  // If either has no workspace, just terminate normally
-  if (!childWorkspace || !parentWorkspace) {
-    await agentManager.terminate(childId, "parent_stopped");
-    return { success: true, merged: false };
-  }
-
-  // Get the child's branch name
-  const childBranch = childWorkspace.branch;
-
-  // Verify the parent worktree is on the expected branch
-  const currentParentBranch = getCurrentBranch(parentWorkspace.path);
-  if (currentParentBranch !== parentWorkspace.branch) {
-    console.warn(
-      `[cascade] Parent worktree is on '${currentParentBranch}' but expected '${parentWorkspace.branch}'`
-    );
-    // Continue with merge anyway - use the actual current branch
-  }
-
-  // Attempt to merge child branch into parent's worktree.
-  //
-  // Preferred path: route through workspaceManager.mergeStream when both
-  // workspaces have stream ids. Goes via git-cascade's tracker.mergeStream,
-  // which fires `x-cascade/stream.merged` with source/target stream ids so
-  // the hub's cascade projection + the source stream's `merged` status
-  // update in lockstep with the actual git operation.
-  if (
-    workspaceManager &&
-    childWorkspace.streamId &&
-    parentWorkspace.streamId
-  ) {
-    try {
-      const result = workspaceManager.mergeStream({
-        sourceStreamId: childWorkspace.streamId,
-        targetStreamId: parentWorkspace.streamId,
-        agentId: parentId,
-        worktree: parentWorkspace.path,
-        metadata: taskRef ? { task_ref: taskRef } : undefined,
-      });
-      if (result.success) {
-        await agentManager.terminate(childId, "changes_consolidated");
-        return {
-          success: true,
-          merged: true,
-          mergeCommit: result.newHead,
-        };
-      }
-      if (result.conflicts && result.conflicts.length > 0) {
-        // Tracker already aborted; emit and terminate with conflict reason.
-        console.warn(
-          `[cascade] Merge conflict consolidating ${childId} -> ${parentId} via tracker: ${result.conflicts.join(", ")}`
-        );
-        await agentManager.terminate(childId, "merge_conflict");
-        return {
-          success: false,
-          merged: false,
-          conflicts: result.conflicts,
-        };
-      }
-      // Tracker returned a non-conflict failure — fall through to raw
-      // git path so we don't regress the consolidation semantics for
-      // cases the tracker can't handle (e.g., stream in unexpected
-      // status, detached HEAD, branch-name mismatches).
-    } catch (err) {
-      console.warn(
-        `[cascade] tracker.mergeStream failed consolidating ${childId} -> ${parentId}; falling back to raw git: ${err instanceof Error ? err.message : String(err)}`
-      );
-      // Fall through to raw-git path below.
-    }
-  }
-
-  // Fallback: raw git merge. Preserves pre-A3 behavior when streams
-  // aren't available (programmatic callers, legacy role-shaped
-  // workspaces) or when the tracker path bailed.
-  const mergeMessage =
-    options?.mergeMessage ??
-    `Merge changes from ${childId} (${childBranch})`;
-
-  const mergeResult = attemptMerge(childBranch, parentWorkspace.path, mergeMessage);
-
-  if (mergeResult.success) {
-    // Merge succeeded - terminate child normally
-    await agentManager.terminate(childId, "changes_consolidated");
-    return {
-      success: true,
-      merged: true,
-      mergeCommit: mergeResult.mergeCommit,
-    };
-  }
-
-  // Merge failed
-  if (mergeResult.conflicts && mergeResult.conflicts.length > 0) {
-    // Conflict detected - abort the merge and terminate with conflict status
-    abortMerge(parentWorkspace.path);
-
-    console.warn(
-      `[cascade] Merge conflict consolidating ${childId} -> ${parentId}: ${mergeResult.conflicts.join(", ")}`
-    );
-
-    // Terminate child with conflict reason
-    await agentManager.terminate(childId, "merge_conflict");
-
-    return {
-      success: false,
-      merged: false,
-      conflicts: mergeResult.conflicts,
-    };
-  }
-
-  // Non-conflict error
-  console.error(
-    `[cascade] Merge failed consolidating ${childId} -> ${parentId}: ${mergeResult.error}`
-  );
-
-  // Still terminate the child, but note the failure
-  await agentManager.terminate(childId, "merge_failed");
-
-  return {
-    success: false,
-    merged: false,
-    error: mergeResult.error,
-  };
-}
-
-// =============================================================================
-// Utility Functions
-// =============================================================================
-
-/**
- * Get all descendants of an agent (children, grandchildren, etc.)
- */
-export function getAllDescendants(
-  agentId: AgentId,
-  agentManager: CascadeAgentManager
-): CascadeAgent[] {
-  const descendants: CascadeAgent[] = [];
-  const children = agentManager.getChildren(agentId);
-
-  for (const child of children) {
-    descendants.push(child);
-    // Recursively get grandchildren
-    const grandchildren = getAllDescendants(child.id, agentManager);
-    descendants.push(...grandchildren);
-  }
-
-  return descendants;
-}
-
-/**
- * Check if cascade termination is needed (agent has running children)
- */
-export function needsCascadeTermination(
-  agentId: AgentId,
-  agentManager: CascadeAgentManager
-): boolean {
-  const children = agentManager.getChildren(agentId);
-  return children.some(
-    (child) => child.state === "running" || child.state === "spawning"
-  );
-}

package/src/lifecycle/cleanup.ts

@@ -1,373 +0,0 @@
-/**
- * Cleanup Status Detection
- *
- * Auto-detects workspace cleanup readiness by checking:
- * - Uncommitted changes via git status
- *
- * @module lifecycle/cleanup
- * @see s-32xs Self-Cleaning Workers spec
- */
-
-import * as fs from "fs";
-import * as path from "path";
-import { execSync, execFileSync } from "child_process";
-import type { CleanupStatus, LifecycleContext } from "./types.js";
-
-// =============================================================================
-// Cleanup Detection Interface
-// =============================================================================
-
-/**
- * Dependencies for cleanup detection (currently empty — extend for V2 adapters if needed)
- */
-export interface CleanupDependencies {}
-
-// =============================================================================
-// Git Status Helpers
-// =============================================================================
-
-/**
- * Check if a workspace has uncommitted changes
- */
-export function hasUncommittedChanges(workspacePath: string): boolean {
-  try {
-    const status = execSync("git status --porcelain", {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    });
-    return status.trim() !== "";
-  } catch {
-    // If git command fails, assume there are uncommitted changes
-    return true;
-  }
-}
-
-/**
- * Get list of uncommitted files in a workspace
- */
-export function getUncommittedFiles(workspacePath: string): string[] {
-  try {
-    const status = execSync("git status --porcelain", {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    });
-    if (!status.trim()) return [];
-
-    // Split by newlines, filter empty lines, then extract filename
-    // Git status format: XY FILENAME (2 char status + space + filename)
-    return status
-      .split("\n")
-      .filter((line) => line.length > 3)
-      .map((line) => line.slice(3).trim())
-      .filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Get current branch name
- */
-export function getCurrentBranch(workspacePath: string): string | undefined {
-  try {
-    return execSync("git rev-parse --abbrev-ref HEAD", {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    }).trim();
-  } catch {
-    return undefined;
-  }
-}
-
-// =============================================================================
-// Main Detection Function
-// =============================================================================
-
-/**
- * Detect cleanup status for an agent
- *
- * Checks uncommitted changes in workspace.
- * Pending message checks are handled by agent-inbox directly.
- *
- * @param context - Lifecycle context with agent info
- * @param _deps - Dependencies (currently unused, reserved for future)
- * @returns Cleanup status indicating readiness
- */
-export function detectCleanupStatus(
-  context: LifecycleContext,
-  _deps: CleanupDependencies = {}
-): CleanupStatus {
-  const reasons: string[] = [];
-  let uncommittedFiles: string[] = [];
-
-  // Check uncommitted changes if workspace path is available
-  if (context.workspacePath) {
-    uncommittedFiles = getUncommittedFiles(context.workspacePath);
-    if (uncommittedFiles.length > 0) {
-      reasons.push(
-        `${uncommittedFiles.length} uncommitted file(s): ${uncommittedFiles.slice(0, 3).join(", ")}${uncommittedFiles.length > 3 ? "..." : ""}`
-      );
-    }
-  }
-
-  const ready = reasons.length === 0;
-
-  return {
-    ready,
-    reason: ready ? undefined : reasons.join("; "),
-    uncommittedFiles: uncommittedFiles.length > 0 ? uncommittedFiles : undefined,
-  };
-}
-
-// =============================================================================
-// Commit Changes Helper
-// =============================================================================
-
-/**
- * Optional handle for routing commits through git-cascade so the resulting
- * commit gets a Change-Id trailer and emits an `x-cascade/stream.committed`
- * event. When omitted, commits are made via raw git (no Change-Id, no
- * cascade event) — used by legacy/null-workspace paths.
- */
-export interface TrackedCommitHandle {
-  /** WorkspaceManager-style commitChanges signature */
-  commitChanges(opts: {
-    streamId: string;
-    agentId: string;
-    worktree: string;
-    message: string;
-    metadata?: Record<string, unknown>;
-  }): { commit: string; changeId: string };
-  /** Stream this commit belongs to */
-  streamId: string;
-  /** Agent making the commit */
-  agentId: string;
-  /** Optional metadata threaded into the cascade event (e.g. `{ task_ref }`) */
-  metadata?: Record<string, unknown>;
-}
-
-/**
- * Commit all uncommitted changes in a workspace.
- *
- * When a `TrackedCommitHandle` is supplied, the commit goes through
- * git-cascade's tracker — gaining a stable Change-Id trailer and emitting
- * `x-cascade/stream.committed` so OpenHive sees the work. Without a handle,
- * falls back to raw git (legacy behavior).
- *
- * @param workspacePath - Path to the workspace
- * @param message - Commit message
- * @param tracked - Optional handle to commit via the cascade tracker
- * @returns Commit hash if successful, undefined if nothing to commit
- */
-export function commitChanges(
-  workspacePath: string,
-  message: string,
-  tracked?: TrackedCommitHandle
-): string | undefined {
-  try {
-    // Check if there are changes to commit
-    if (!hasUncommittedChanges(workspacePath)) {
-      return undefined;
-    }
-
-    // Tracked path: stage + commit through git-cascade so Change-Id +
-    // x-cascade events fire.
-    if (tracked) {
-      try {
-        const { commit } = tracked.commitChanges({
-          streamId: tracked.streamId,
-          agentId: tracked.agentId,
-          worktree: workspacePath,
-          message,
-          metadata: tracked.metadata,
-        });
-        return commit;
-      } catch {
-        // Fall through to raw-git path on tracker failure (e.g., stream
-        // conflicted) so callers still get a commit. Caveat: no Change-Id
-        // and no cascade event in this fallback.
-      }
-    }
-
-    // Raw-git path: stage all changes
-    execFileSync("git", ["add", "--all"], {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    });
-
-    // Commit - use execFileSync with array args to prevent command injection
-    execFileSync("git", ["commit", "-m", message], {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    });
-
-    // Get commit hash
-    const hash = execSync("git rev-parse HEAD", {
-      cwd: workspacePath,
-      encoding: "utf-8",
-    }).trim();
-
-    return hash;
-  } catch {
-    return undefined;
-  }
-}
-
-// =============================================================================
-// Merge Helpers (Phase 6 - Change Consolidation)
-// =============================================================================
-
-/**
- * Result of a merge attempt
- */
-export interface MergeResult {
-  /** Whether the merge succeeded */
-  success: boolean;
-
-  /** Merge commit hash if successful (only set if a new merge commit was created) */
-  mergeCommit?: string;
-
-  /** True if branches were already merged (no new commit created) */
-  alreadyMerged?: boolean;
-
-  /** List of conflicting files if merge failed */
-  conflicts?: string[];
-
-  /** Error message if merge failed for non-conflict reason */
-  error?: string;
-}
-
-/**
- * Attempt to merge a source branch into the target branch.
- *
- * This performs the merge in the specified worktree, which should already
- * be on the target branch.
- *
- * @param sourceBranch - Branch to merge from
- * @param worktreePath - Path to worktree (should be on target branch)
- * @param message - Optional merge commit message
- * @returns MergeResult indicating success or conflict details
- */
-export function attemptMerge(
-  sourceBranch: string,
-  worktreePath: string,
-  message?: string
-): MergeResult {
-  try {
-    // Capture HEAD before merge to detect "already up-to-date" scenario
-    const headBefore = execSync("git rev-parse HEAD", {
-      cwd: worktreePath,
-      encoding: "utf-8",
-    }).trim();
-
-    // Merge with execFileSync to prevent command injection
-    const mergeMessage = message ?? `Merge branch '${sourceBranch}'`;
-    execFileSync("git", ["merge", sourceBranch, "--no-ff", "-m", mergeMessage], {
-      cwd: worktreePath,
-      encoding: "utf-8",
-      stdio: "pipe",
-    });
-
-    // Get HEAD after merge
-    const headAfter = execSync("git rev-parse HEAD", {
-      cwd: worktreePath,
-      encoding: "utf-8",
-    }).trim();
-
-    // Check if HEAD changed - if not, branches were already merged
-    if (headBefore === headAfter) {
-      return {
-        success: true,
-        alreadyMerged: true,
-      };
-    }
-
-    return {
-      success: true,
-      mergeCommit: headAfter,
-    };
-  } catch (error) {
-    // Check if this is a merge conflict
-    try {
-      const status = execSync("git status --porcelain", {
-        cwd: worktreePath,
-        encoding: "utf-8",
-      });
-
-      // Look for unmerged files (UU, AA, DD, etc.)
-      // Note: Using regex without /g flag since we test one line at a time
-      const conflictPattern = /^(UU|AA|DD|AU|UA|DU|UD) /;
-      const conflicts: string[] = [];
-
-      for (const line of status.split("\n")) {
-        if (conflictPattern.test(line)) {
-          // Extract filename (after the status prefix)
-          const filename = line.slice(3).trim();
-          if (filename) {
-            conflicts.push(filename);
-          }
-        }
-      }
-
-      if (conflicts.length > 0) {
-        return {
-          success: false,
-          conflicts,
-        };
-      }
-    } catch {
-      // Ignore status check errors
-    }
-
-    // Non-conflict error
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-/**
- * Abort an in-progress merge.
- *
- * @param worktreePath - Path to worktree with merge in progress
- * @returns true if abort succeeded, false otherwise
- */
-export function abortMerge(worktreePath: string): boolean {
-  try {
-    execSync("git merge --abort", {
-      cwd: worktreePath,
-      encoding: "utf-8",
-      stdio: "pipe",
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a worktree has a merge in progress.
- *
- * @param worktreePath - Path to worktree
- * @returns true if merge is in progress
- */
-export function hasMergeInProgress(worktreePath: string): boolean {
-  try {
-    const gitDir = execSync("git rev-parse --git-dir", {
-      cwd: worktreePath,
-      encoding: "utf-8",
-    }).trim();
-
-    // Check for MERGE_HEAD file
-    return fs.existsSync(path.join(worktreePath, gitDir, "MERGE_HEAD"));
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get the current branch of a worktree.
- * Alias for getCurrentBranch for clarity.
- */
-export { getCurrentBranch as getWorktreeBranch };