macro-agent 0.1.0 → 0.1.2

package/src/task/backend/opentasks/daemon-manager.ts

@@ -0,0 +1,256 @@
+/**
+ * OpenTasks Daemon Manager
+ *
+ * Manages the lifecycle of the central opentasks daemon as part of the
+ * task backend lifecycle. The daemon is auto-started by createTaskBackend()
+ * and stopped via TaskBackendResult.shutdown().
+ *
+ * Architecture:
+ * - Central daemon lives at ~/.multiagent/opentasks/
+ * - If a daemon is already running, we connect to it (ownsDaemon=false)
+ * - If not, we start one and own its lifecycle (ownsDaemon=true)
+ * - On shutdown, we only stop the daemon if we started it
+ *
+ * @module task/backend/opentasks/daemon-manager
+ */
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { checkExistingDaemon, createDaemonWithStore } from "opentasks";
+import { IPCOpenTasksClient } from "./client.js";
+import type { OpenTasksClient } from "./client.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/**
+ * Configuration for the DaemonManager.
+ */
+export interface DaemonManagerConfig {
+  /** Central daemon location (default: ~/.multiagent/opentasks) */
+  centralPath?: string;
+
+  /** Whether to auto-connect project .opentasks/ on connectProject() */
+  connectOnSpawn?: boolean;
+}
+
+/**
+ * Result from ensureDaemon() — the running daemon's connection info.
+ */
+export interface DaemonManagerResult {
+  /** Connected OpenTasks client */
+  client: OpenTasksClient;
+
+  /** Daemon socket path */
+  socketPath: string;
+
+  /** Whether we started the daemon (vs connecting to existing) */
+  ownsDaemon: boolean;
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CENTRAL_PATH = path.join(
+  process.env.MACRO_AGENT_HOME || path.join(os.homedir(), ".multiagent"),
+  "opentasks",
+);
+
+/** Grace period (ms) between client disconnect and daemon.stop() to let children finish disconnecting */
+const DAEMON_DRAIN_MS = 500;
+
+// =============================================================================
+// DaemonManager Implementation
+// =============================================================================
+
+/**
+ * Manages the central opentasks daemon lifecycle.
+ *
+ * Internal to the opentasks backend module — not exposed as a standalone service.
+ */
+export class DaemonManager {
+  private readonly centralPath: string;
+  private readonly connectOnSpawn: boolean;
+  private daemon: any = null;
+  private client: OpenTasksClient | null = null;
+  private ownsDaemon = false;
+  private connectedProjects = new Set<string>();
+
+  constructor(config?: DaemonManagerConfig) {
+    this.centralPath = config?.centralPath ?? DEFAULT_CENTRAL_PATH;
+    this.connectOnSpawn = config?.connectOnSpawn ?? true;
+  }
+
+  /**
+   * Ensure the central daemon is running and return a connected client.
+   *
+   * 1. Check if a daemon is already running at the central path
+   * 2. If running, connect to it (ownsDaemon=false)
+   * 3. If not running, start one (ownsDaemon=true)
+   * 4. Return connected client + socket path
+   */
+  async ensureDaemon(): Promise<DaemonManagerResult> {
+    // Ensure the central directory exists
+    fs.mkdirSync(this.centralPath, { recursive: true });
+
+    // Check if a daemon is already running at this location
+    const existing = await checkExistingDaemon(this.centralPath);
+
+    if (existing.running && existing.socketPath) {
+      // Connect to the existing daemon
+      console.error(`[opentasks] Connecting to existing daemon at ${existing.socketPath} (pid: ${existing.pid})`);
+
+      const client = new IPCOpenTasksClient({
+        socketPath: existing.socketPath,
+      });
+      await client.connect();
+
+      this.client = client;
+      this.ownsDaemon = false;
+
+      return {
+        client,
+        socketPath: existing.socketPath,
+        ownsDaemon: false,
+      };
+    }
+
+    // No daemon running — start one
+    console.error(`[opentasks] Starting daemon at ${this.centralPath}`);
+
+    const daemon = await createDaemonWithStore({
+      locationPath: this.centralPath,
+      version: "0.0.3",
+    });
+    await daemon.start();
+
+    this.daemon = daemon;
+    this.ownsDaemon = true;
+
+    const socketPath = daemon.socketPath as string;
+    console.error(`[opentasks] Daemon started (socket: ${socketPath})`);
+
+    // Connect client to the daemon
+    const client = new IPCOpenTasksClient({ socketPath });
+    await client.connect();
+
+    this.client = client;
+
+    return {
+      client,
+      socketPath,
+      ownsDaemon: true,
+    };
+  }
+
+  /**
+   * Connect a project's .opentasks/ directory to the central daemon.
+   *
+   * This is a fire-and-forget operation — connection failures are logged
+   * but do not affect the caller.
+   *
+   * @param projectPath - Path to the project root (will look for .opentasks/ subdirectory)
+   */
+  async connectProject(projectPath: string): Promise<void> {
+    if (!this.connectOnSpawn) return;
+    if (!this.client) return;
+
+    const opentasksDir = path.join(projectPath, ".opentasks");
+
+    // Check if project has .opentasks/
+    if (!fs.existsSync(opentasksDir)) return;
+
+    // Check if already connected
+    if (this.connectedProjects.has(opentasksDir)) return;
+
+    try {
+      // Read the project's config.json to get its location hash
+      const configPath = path.join(opentasksDir, "config.json");
+      const configContent = fs.readFileSync(configPath, "utf-8");
+      const config = JSON.parse(configContent);
+      const hash = config?.location?.hash;
+
+      if (!hash) {
+        console.error(`[opentasks] No location hash in ${configPath}, skipping`);
+        return;
+      }
+
+      // Register the location with the daemon via IPC
+      const client = this.client as any;
+      if (typeof client.call === "function") {
+        await client.call("location.register", {
+          hash,
+          opentasksPath: opentasksDir,
+        });
+      }
+
+      this.connectedProjects.add(opentasksDir);
+      console.error(`[opentasks] Connected to project: ${opentasksDir}`);
+    } catch (error) {
+      // Non-fatal — log and continue
+      console.error(`[opentasks] Failed to connect project ${opentasksDir}: ${error}`);
+    }
+  }
+
+  /**
+   * Check if a project is already connected to the central daemon.
+   */
+  isProjectConnected(projectPath: string): boolean {
+    const opentasksDir = path.join(projectPath, ".opentasks");
+    return this.connectedProjects.has(opentasksDir);
+  }
+
+  /**
+   * Get list of connected project .opentasks/ paths.
+   */
+  getConnectedProjects(): string[] {
+    return Array.from(this.connectedProjects);
+  }
+
+  /**
+   * Shut down the daemon manager.
+   *
+   * - Disconnects the client
+   * - Stops the daemon if we started it (ownsDaemon=true)
+   * - Leaves the daemon running if someone else started it
+   */
+  async shutdown(): Promise<void> {
+    // Disconnect client
+    if (this.client) {
+      try {
+        this.client.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+      this.client = null;
+    }
+
+    // Stop daemon only if we own it
+    if (this.ownsDaemon && this.daemon) {
+      try {
+        // Grace period to let child agents finish disconnecting from the daemon
+        await new Promise<void>(resolve => setTimeout(resolve, DAEMON_DRAIN_MS));
+        console.error("[opentasks] Stopping daemon");
+        await this.daemon.stop();
+      } catch (error) {
+        console.error(`[opentasks] Error stopping daemon: ${error}`);
+      }
+      this.daemon = null;
+      this.ownsDaemon = false;
+    }
+
+    this.connectedProjects.clear();
+  }
+}
+
+/**
+ * Create a DaemonManager instance.
+ */
+export function createDaemonManager(
+  config?: DaemonManagerConfig
+): DaemonManager {
+  return new DaemonManager(config);
+}

package/src/task/backend/opentasks/index.ts

@@ -0,0 +1,69 @@
+/**
+ * OpenTasks Task Backend Module
+ *
+ * Integrates macro-agent's task system with OpenTasks, a graph connector
+ * for linking heterogeneous task and issue systems.
+ *
+ * Tasks are stored as OpenTasks issues with bidirectional ID mapping.
+ * Blocking dependencies use OpenTasks 'blocks' edges.
+ * The pull model leverages OpenTasks' ready query and claimed_by field.
+ *
+ * @module task/backend/opentasks
+ */
+
+// Backend
+export {
+  OpenTasksTaskBackend,
+  OpenTasksBackendError,
+  createOpenTasksTaskBackend,
+} from "./backend.js";
+export type { OpenTasksBackendConfig } from "./backend.js";
+
+// Client
+export {
+  IPCOpenTasksClient,
+  OpenTasksClientError,
+  createOpenTasksClient,
+} from "./client.js";
+export type {
+  OpenTasksClient,
+  OpenTasksClientConfig,
+  OpenTasksIssue,
+  OpenTasksEdge,
+  OpenTasksNodeSummary,
+  CreateIssueInput,
+  UpdateIssueInput,
+  IssueChangeType,
+  IssueChangeEvent,
+  IssueChangeCallback,
+  ClientUnsubscribe,
+  // Task lifecycle types (tools.task)
+  TaskAction,
+  TaskParams,
+  TaskResult,
+  TaskTransitionData,
+  TaskReadyData,
+  TaskAssignData,
+  TaskValidActionsData,
+  TaskNodeSummary,
+  ProviderSummary,
+} from "./client.js";
+
+// Daemon Manager
+export {
+  DaemonManager,
+  createDaemonManager,
+} from "./daemon-manager.js";
+export type {
+  DaemonManagerConfig,
+  DaemonManagerResult,
+} from "./daemon-manager.js";
+
+// Mapping
+export {
+  mapOpenTasksStatus,
+  mapTaskStatus,
+  isIssueComplete,
+  isIssueBlocked,
+} from "./mapping.js";
+export type { OpenTasksIssueStatus } from "./mapping.js";

package/src/task/backend/opentasks/mapping.ts

@@ -0,0 +1,94 @@
+/**
+ * Status Mapping Utilities for OpenTasks Integration
+ *
+ * Maps between OpenTasks issue statuses and macro-agent task statuses.
+ *
+ * @module task/backend/opentasks/mapping
+ */
+
+import type { TaskStatus } from "../../../store/types/index.js";
+
+/**
+ * OpenTasks issue status values.
+ * These are the canonical statuses used by OpenTasks issues.
+ */
+export type OpenTasksIssueStatus =
+  | "open"
+  | "in_progress"
+  | "blocked"
+  | "closed";
+
+/**
+ * Map OpenTasks issue status to macro-agent task status.
+ *
+ * OpenTasks statuses:
+ * - open: Not started
+ * - in_progress: Currently being worked on
+ * - blocked: Blocked by dependencies (handled via isBlocked flag)
+ * - closed: Completed
+ *
+ * Macro-agent statuses:
+ * - pending: Not started
+ * - assigned: Assigned to an agent but not started
+ * - in_progress: Currently executing
+ * - completed: Finished successfully
+ * - failed: Finished with error
+ */
+export function mapOpenTasksStatus(
+  openTasksStatus: string
+): TaskStatus {
+  switch (openTasksStatus) {
+    case "open":
+      return "pending";
+    case "in_progress":
+      return "in_progress";
+    case "blocked":
+      // Blocked issues map to pending - the isBlocked flag handles blocking
+      return "pending";
+    case "closed":
+      return "completed";
+    default:
+      return "pending";
+  }
+}
+
+/**
+ * Map macro-agent task status to OpenTasks issue status.
+ *
+ * Note: Some task statuses don't have direct OpenTasks equivalents:
+ * - assigned: No direct equivalent (maps to open, assignee set separately)
+ * - failed: No direct equivalent (maps to closed with error in metadata)
+ */
+export function mapTaskStatus(taskStatus: TaskStatus): OpenTasksIssueStatus {
+  switch (taskStatus) {
+    case "pending":
+      return "open";
+    case "assigned":
+      // Assigned tasks remain open in OpenTasks; assignee field handles assignment
+      return "open";
+    case "in_progress":
+      return "in_progress";
+    case "completed":
+      return "closed";
+    case "failed":
+      // Failed tasks are closed in OpenTasks (failure tracked in metadata)
+      return "closed";
+    default:
+      return "open";
+  }
+}
+
+/**
+ * Check if an OpenTasks issue status indicates completion.
+ */
+export function isIssueComplete(status: string): boolean {
+  return status === "closed";
+}
+
+/**
+ * Check if an OpenTasks issue has an explicit blocked status.
+ * Note: This is the explicit 'blocked' status, not dependency-based blocking.
+ */
+export function isIssueBlocked(status: string): boolean {
+  return status === "blocked";
+}

package/src/task/backend/types.ts

@@ -5,7 +5,6 @@
  * internal task system to be backed by external task management systems.
  *
  * @module task/backend
- * @see s-8472 Pluggable Task Backend Integration with Sudocode
  */
 
 import type {
@@ -33,8 +32,11 @@ export interface ExtendedTask extends Task {
   /** True if blocked by dependencies (computed, not stored) */
   isBlocked?: boolean;
 
-  /** Binding to external system (e.g., sudocode issue ID "i-xxxx") */
+  /** Binding to external system (e.g., OpenTasks issue ID "i-xxxx") */
   external_id?: string;
+
+  /** Source project location (e.g., opentasks path or URI) for federated tasks */
+  source_location?: string;
 }
 
 // =============================================================================
@@ -54,7 +56,7 @@ export interface CreateTaskOptions {
   /** Optional parent task for subtask hierarchy */
   parent_task?: TaskId;
 
-  /** Optional binding to external system (e.g., sudocode issue ID) */
+  /** Optional binding to external system (e.g., OpenTasks issue ID) */
   external_id?: string;
 
   /** Optional tags for classification and filtering (pull model) */
@@ -243,11 +245,13 @@ export type Unsubscribe = () => void;
  *
  * Abstraction over task storage allowing different implementations:
  * - InMemoryTaskBackend - Current behavior (default)
- * - SudocodeTaskBackend - Backed by sudocode issues
- * - Future: LinearTaskBackend, JiraTaskBackend, etc.
+ * - OpenTasksTaskBackend - Backed by OpenTasks graph
  */
 export interface TaskBackend {
   // ─── Lifecycle ───────────────────────────────────────────────
+  /** Gracefully close the backend. After close(), write operations may throw. */
+  close?(): Promise<void>;
+
   /** Create a new task */
   create(options: CreateTaskOptions): Promise<ExtendedTask>;
 
@@ -331,6 +335,16 @@ export interface TaskBackend {
   /** Get agent assignment history for a task */
   getAgentHistory(taskId: TaskId): Promise<AgentHistoryEntry[]>;
 
+  // ─── External Sync ──────────────────────────────────────────
+  /**
+   * Sync a task transition that happened externally (e.g., via opentasks daemon).
+   * Updates the internal store without re-syncing to the external system.
+   * @param externalId - The external system's task ID (e.g., opentasks issue ID)
+   * @param action - The transition action (e.g., "complete", "start", "close")
+   * @param agentId - The agent that performed the transition
+   */
+  syncExternalTransition?(externalId: string, action: string, agentId?: string): Promise<void>;
+
   // ─── Event Subscriptions ─────────────────────────────────────
   /** Subscribe to all task changes */
   onTaskChange(callback: TaskChangeCallback): Unsubscribe;
@@ -360,15 +374,6 @@ export interface MCPToolDefinition {
   handler: (params: unknown) => Promise<unknown>;
 }
 
-/**
- * Task tool mode
- */
-export type TaskToolMode =
-  | "abstract" // Always use generic task tools (create_task, etc.)
-  | "native" // Use backend-native tools (upsert_issue for sudocode)
-  | "both" // Expose both tool sets
-  | "auto"; // Backend decides (default)
-
 /**
  * Task Tool Provider Interface
  *
@@ -394,57 +399,34 @@ export interface InMemoryBackendConfig {
 }
 
 /**
- * Execution tracking configuration
- */
-export type ExecutionTrackingConfig =
-  | { mode: "none" } // No execution records
-  | { mode: "bound-only" } // Only tasks with external binding (default)
-  | { mode: "all" } // All agent runs
-  | { mode: "filter"; filter: ExecutionFilter }; // Custom filter
-
-/**
- * Execution filter options
- */
-export interface ExecutionFilter {
-  /** Only create executions for these agent roles */
-  roles?: string[];
-
-  /** Only when task has external binding */
-  requireExternalBinding?: boolean;
-
-  /** Exclude coordination-only agents (no code changes) */
-  excludeCoordinationOnly?: boolean;
-}
-
-/**
- * Sudocode backend configuration
+ * OpenTasks backend configuration
  */
-export interface SudocodeBackendConfig {
-  type: "sudocode";
+export interface OpenTasksBackendConfig {
+  type: "opentasks";
 
-  /** Path to sudocode project root (contains .sudocode/) */
-  projectPath: string;
+  /** Path to the OpenTasks daemon socket (auto-discovered if not set) */
+  socketPath?: string;
 
-  /** ID strategy (default: 'dual') */
-  idStrategy?: "dual";
+  /** Whether to sync status changes to OpenTasks (default: true) */
+  syncStatus?: boolean;
 
-  /** Sync mode for event subscriptions */
-  syncMode?: "realtime" | "batch";
+  /** Source label for issues created by this backend (default: "macro-agent") */
+  sourceLabel?: string;
 
-  /** Execution tracking configuration */
-  executionTracking?: ExecutionTrackingConfig;
+  /** Auto-start the central opentasks daemon (default: true) */
+  autoStart?: boolean;
 
-  /** Auto-link tasks to specs when created from spec context */
-  autoLinkSpecs?: boolean;
+  /** Central daemon location (default: ~/.multiagent/opentasks) */
+  centralPath?: string;
 
-  /** Tool mode for this backend (overrides global if set) */
-  toolMode?: "native" | "mapped" | "both";
+  /** Auto-connect project .opentasks/ dirs on agent spawn (default: true) */
+  connectOnSpawn?: boolean;
 }
 
 /**
  * Task backend configuration
  */
-export type TaskBackendConfig = InMemoryBackendConfig | SudocodeBackendConfig;
+export type TaskBackendConfig = InMemoryBackendConfig | OpenTasksBackendConfig;
 
 /**
  * Macro-agent task configuration
@@ -452,9 +434,6 @@ export type TaskBackendConfig = InMemoryBackendConfig | SudocodeBackendConfig;
 export interface TaskConfig {
   /** Task backend configuration */
   backend: TaskBackendConfig;
-
-  /** Task tool mode (default: 'auto') */
-  toolMode?: TaskToolMode;
 }
 
 // =============================================================================
@@ -465,18 +444,15 @@ export interface TaskConfig {
  * Default task configuration
  */
 export const DEFAULT_TASK_CONFIG: TaskConfig = {
-  backend: { type: "memory" },
-  toolMode: "auto",
+  backend: { type: "opentasks" },
 };
 
 /**
- * Default sudocode backend configuration
+ * Default OpenTasks backend configuration
  */
-export const DEFAULT_SUDOCODE_CONFIG: Omit<SudocodeBackendConfig, "type"> = {
-  projectPath: process.cwd(),
-  idStrategy: "dual",
-  syncMode: "realtime",
-  executionTracking: { mode: "bound-only" },
-  autoLinkSpecs: true,
-  toolMode: "mapped",
+export const DEFAULT_OPENTASKS_CONFIG: Omit<OpenTasksBackendConfig, "type"> = {
+  syncStatus: true,
+  sourceLabel: "macro-agent",
+  autoStart: true,
+  connectOnSpawn: true,
 };