macro-agent 0.2.5 → 0.2.6

package/dist/task/backend/opentasks/backend.js

@@ -0,0 +1,1023 @@
+/**
+ * OpenTasksTaskBackend Implementation
+ *
+ * Implements TaskBackend using OpenTasks as the source of truth for task storage,
+ * with EventStore for local event tracking and subscriptions.
+ *
+ * Tasks are stored as OpenTasks issues. Blocking dependencies use OpenTasks
+ * 'blocks' edges. The pull model uses OpenTasks' ready query and claimed_by field.
+ *
+ * @module task/backend/opentasks/backend
+ */
+import { nanoid } from "nanoid";
+import { mapOpenTasksStatus, mapTaskStatus, isIssueComplete } from "./mapping.js";
+// Valid status transitions
+const VALID_STATUS_TRANSITIONS = {
+    pending: ["assigned", "in_progress", "failed"],
+    assigned: ["in_progress", "pending", "failed"],
+    in_progress: ["completed", "failed", "pending"],
+    completed: [],
+    failed: ["pending"],
+};
+/**
+ * Error thrown by OpenTasksTaskBackend operations
+ */
+export class OpenTasksBackendError extends Error {
+    code;
+    taskId;
+    constructor(message, code, taskId) {
+        super(message);
+        this.code = code;
+        this.taskId = taskId;
+        this.name = "OpenTasksBackendError";
+    }
+}
+const DEFAULT_CONFIG = {
+    socketPath: "",
+    syncStatus: true,
+    sourceLabel: "macro-agent",
+};
+/**
+ * OpenTasksTaskBackend implements TaskBackend using:
+ * - OpenTasks daemon for issue storage and graph relationships
+ * - EventStore for local event tracking and subscriptions
+ *
+ * Key features:
+ * - Tasks are stored as OpenTasks issues with macro-agent metadata
+ * - Blocking dependencies use OpenTasks 'blocks' edges
+ * - Pull model uses OpenTasks ready query and claimed_by
+ * - Bidirectional ID mapping (task_id <-> issue_id) via metadata
+ */
+export class OpenTasksTaskBackend {
+    eventStore;
+    client;
+    config;
+    closed = false;
+    /** Map from macro-agent task ID to OpenTasks issue ID */
+    taskToIssue = new Map();
+    /** Map from OpenTasks issue ID to macro-agent task ID */
+    issueToTask = new Map();
+    constructor(eventStore, client, config) {
+        this.eventStore = eventStore;
+        this.client = client;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Throw if the backend has been closed.
+     */
+    ensureOpen() {
+        if (this.closed) {
+            throw new OpenTasksBackendError("Backend is closed", "BACKEND_CLOSED");
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Lifecycle
+    // ─────────────────────────────────────────────────────────────────────────────
+    async close() {
+        this.closed = true;
+    }
+    async create(options) {
+        this.ensureOpen();
+        const taskId = `task_${nanoid(12)}`;
+        // Resolve parent issue ID if parent task specified
+        let parentIssueId;
+        if (options.parent_task) {
+            parentIssueId = this.taskToIssue.get(options.parent_task);
+            if (!parentIssueId) {
+                // Check EventStore as fallback
+                const parent = this.eventStore.getTask(options.parent_task);
+                if (!parent) {
+                    throw new OpenTasksBackendError(`Parent task not found: ${options.parent_task}`, "PARENT_TASK_NOT_FOUND", options.parent_task);
+                }
+            }
+        }
+        // Create issue in OpenTasks
+        const issue = await this.client.createIssue({
+            title: options.description,
+            status: "open",
+            tags: options.tags,
+            parent_id: parentIssueId,
+            metadata: {
+                macro_agent_task_id: taskId,
+                created_by: options.created_by,
+                source: this.config.sourceLabel,
+            },
+        });
+        // Store bidirectional mapping
+        this.taskToIssue.set(taskId, issue.id);
+        this.issueToTask.set(issue.id, taskId);
+        // Emit to EventStore for local tracking
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: options.created_by },
+            payload: {
+                task_id: taskId,
+                action: "created",
+                details: {
+                    description: options.description,
+                    parent_task: options.parent_task,
+                    tags: options.tags,
+                    external_id: issue.id,
+                },
+            },
+        });
+        // Update parent subtasks in EventStore
+        if (options.parent_task) {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: options.created_by },
+                payload: {
+                    task_id: options.parent_task,
+                    action: "status_change",
+                    details: { subtask_added: taskId },
+                },
+            });
+        }
+        // Return from EventStore (which has the canonical local state)
+        const task = this.eventStore.getTask(taskId);
+        return this.toExtendedTask(task);
+    }
+    async get(id) {
+        // EventStore is the local mirror with richer state
+        // (assigned status, outputs, agent_history, etc.)
+        const task = this.eventStore.getTask(id);
+        if (!task)
+            return null;
+        return this.toExtendedTask(task);
+    }
+    async update(id, updates) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        const source = task.assigned_agent ?? task.created_by;
+        // Handle status update with validation
+        if (updates.status !== undefined) {
+            const validTransitions = VALID_STATUS_TRANSITIONS[task.status];
+            if (!validTransitions.includes(updates.status)) {
+                throw new OpenTasksBackendError(`Invalid status transition: ${task.status} -> ${updates.status}`, "INVALID_STATUS_TRANSITION", id);
+            }
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: source },
+                payload: {
+                    task_id: id,
+                    action: "status_change",
+                    details: { status: updates.status },
+                },
+            });
+            // Sync to OpenTasks
+            await this.syncStatusToOpenTasks(id, updates.status);
+        }
+        // Handle other updates
+        if (updates.outputs !== undefined) {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: source },
+                payload: {
+                    task_id: id,
+                    action: "status_change",
+                    details: { outputs: updates.outputs },
+                },
+            });
+        }
+        if (updates.artifacts !== undefined) {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: source },
+                payload: {
+                    task_id: id,
+                    action: "status_change",
+                    details: { artifacts: updates.artifacts },
+                },
+            });
+        }
+        if (updates.description !== undefined) {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: source },
+                payload: {
+                    task_id: id,
+                    action: "status_change",
+                    details: { description: updates.description },
+                },
+            });
+            // Sync description to OpenTasks
+            const issueId = this.taskToIssue.get(id);
+            if (issueId) {
+                await this.client.updateIssue(issueId, {
+                    title: updates.description,
+                });
+            }
+        }
+        const updated = this.eventStore.getTask(id);
+        return this.toExtendedTask(updated);
+    }
+    async delete(id) {
+        this.ensureOpen();
+        const issueId = this.taskToIssue.get(id);
+        if (issueId) {
+            await this.client.deleteIssue(issueId);
+            this.taskToIssue.delete(id);
+            this.issueToTask.delete(issueId);
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Status Transitions
+    // ─────────────────────────────────────────────────────────────────────────────
+    async assign(id, agentId, options) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: agentId },
+            payload: {
+                task_id: id,
+                action: "assigned",
+                details: {
+                    agent_id: agentId,
+                    role: options?.role,
+                },
+            },
+        });
+        // Sync assignee to OpenTasks
+        const issueId = this.taskToIssue.get(id);
+        if (issueId) {
+            await this.client.updateIssue(issueId, {
+                assignee: agentId,
+                metadata: { claimed_by: agentId },
+            });
+        }
+    }
+    async unassign(id) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        if (!task.assigned_agent) {
+            throw new OpenTasksBackendError(`Task is not assigned: ${id}`, "TASK_NOT_ASSIGNED", id);
+        }
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: task.assigned_agent },
+            payload: {
+                task_id: id,
+                action: "unassigned",
+                details: { agent_id: task.assigned_agent },
+            },
+        });
+        // Clear assignee in OpenTasks
+        const issueId = this.taskToIssue.get(id);
+        if (issueId) {
+            await this.client.updateIssue(issueId, {
+                assignee: null,
+                metadata: { claimed_by: null },
+            });
+        }
+    }
+    async start(id) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        const validTransitions = VALID_STATUS_TRANSITIONS[task.status];
+        if (!validTransitions.includes("in_progress")) {
+            throw new OpenTasksBackendError(`Invalid status transition: ${task.status} -> in_progress`, "INVALID_STATUS_TRANSITION", id);
+        }
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: task.assigned_agent ?? task.created_by },
+            payload: {
+                task_id: id,
+                action: "status_change",
+                details: { status: "in_progress" },
+            },
+        });
+        await this.syncStatusToOpenTasks(id, "in_progress");
+    }
+    async complete(id, outputs) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        const validTransitions = VALID_STATUS_TRANSITIONS[task.status];
+        if (!validTransitions.includes("completed")) {
+            throw new OpenTasksBackendError(`Invalid status transition: ${task.status} -> completed`, "INVALID_STATUS_TRANSITION", id);
+        }
+        const agent = task.assigned_agent ?? task.created_by;
+        // Store outputs
+        if (outputs) {
+            const outputsToStore = {
+                ...(outputs.data ?? {}),
+            };
+            if (outputs.summary !== undefined) {
+                outputsToStore.summary = outputs.summary;
+            }
+            if (Object.keys(outputsToStore).length > 0) {
+                this.eventStore.emit({
+                    type: "task",
+                    source: { agent_id: agent },
+                    payload: {
+                        task_id: id,
+                        action: "status_change",
+                        details: { outputs: outputsToStore },
+                    },
+                });
+            }
+            if (outputs.artifacts) {
+                this.eventStore.emit({
+                    type: "task",
+                    source: { agent_id: agent },
+                    payload: {
+                        task_id: id,
+                        action: "status_change",
+                        details: { artifacts: outputs.artifacts },
+                    },
+                });
+            }
+        }
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: agent },
+            payload: {
+                task_id: id,
+                action: "completed",
+                details: {},
+            },
+        });
+        // Close the issue in OpenTasks
+        await this.syncStatusToOpenTasks(id, "completed");
+    }
+    async fail(id, error) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(id);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${id}`, "TASK_NOT_FOUND", id);
+        }
+        const validTransitions = VALID_STATUS_TRANSITIONS[task.status];
+        if (!validTransitions.includes("failed")) {
+            throw new OpenTasksBackendError(`Invalid status transition: ${task.status} -> failed`, "INVALID_STATUS_TRANSITION", id);
+        }
+        const agent = task.assigned_agent ?? task.created_by;
+        // Store error in outputs
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: agent },
+            payload: {
+                task_id: id,
+                action: "status_change",
+                details: {
+                    outputs: {
+                        error: {
+                            message: error.message,
+                            code: error.code,
+                            details: error.details,
+                        },
+                    },
+                },
+            },
+        });
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: agent },
+            payload: {
+                task_id: id,
+                action: "failed",
+                details: {},
+            },
+        });
+        // Close in OpenTasks with error metadata
+        const issueId = this.taskToIssue.get(id);
+        if (issueId) {
+            await this.client.updateIssue(issueId, {
+                status: "closed",
+                metadata: {
+                    macro_agent_failed: true,
+                    macro_agent_error: error.message,
+                },
+            });
+        }
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Queries
+    // ─────────────────────────────────────────────────────────────────────────────
+    async list(filter) {
+        let tasks = this.eventStore.listTasks();
+        if (filter) {
+            if (filter.status) {
+                const statuses = Array.isArray(filter.status)
+                    ? filter.status
+                    : [filter.status];
+                tasks = tasks.filter((t) => statuses.includes(t.status));
+            }
+            if (filter.assigned_agent) {
+                tasks = tasks.filter((t) => t.assigned_agent === filter.assigned_agent);
+            }
+            if (filter.parent_task) {
+                tasks = tasks.filter((t) => t.parent_task === filter.parent_task);
+            }
+            if (filter.created_by) {
+                tasks = tasks.filter((t) => t.created_by === filter.created_by);
+            }
+            if (filter.rootTasksOnly) {
+                tasks = tasks.filter((t) => !t.parent_task);
+            }
+            if (filter.tags && filter.tags.length > 0) {
+                const filterTags = new Set(filter.tags);
+                tasks = tasks.filter((t) => t.tags?.some((tag) => filterTags.has(tag)));
+            }
+        }
+        // Compute isBlocked using OpenTasks graph for mapped tasks,
+        // EventStore blockers for unmapped tasks
+        const extended = await Promise.all(tasks.map((t) => this.toExtendedTaskAsync(t)));
+        if (!filter?.includeBlocked) {
+            return extended.filter((t) => !t.isBlocked);
+        }
+        return extended;
+    }
+    async listReady(filter) {
+        return this.list({
+            ...filter,
+            status: filter?.status ?? ["pending", "assigned"],
+            includeBlocked: false,
+        });
+    }
+    async getChildren(parentId) {
+        const tasks = this.eventStore.listTasks();
+        const children = tasks.filter((t) => t.parent_task === parentId);
+        return Promise.all(children.map((t) => this.toExtendedTaskAsync(t)));
+    }
+    async getSubtaskStatus(parentId) {
+        const children = await this.getChildren(parentId);
+        const status = {
+            total: children.length,
+            pending: 0,
+            assigned: 0,
+            in_progress: 0,
+            completed: 0,
+            failed: 0,
+            allCompleted: false,
+            anyFailed: false,
+        };
+        for (const task of children) {
+            switch (task.status) {
+                case "pending":
+                    status.pending++;
+                    break;
+                case "assigned":
+                    status.assigned++;
+                    break;
+                case "in_progress":
+                    status.in_progress++;
+                    break;
+                case "completed":
+                    status.completed++;
+                    break;
+                case "failed":
+                    status.failed++;
+                    break;
+            }
+        }
+        status.allCompleted =
+            status.total > 0 && status.completed === status.total;
+        status.anyFailed = status.failed > 0;
+        return status;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Hierarchy
+    // ─────────────────────────────────────────────────────────────────────────────
+    async createSubtask(parentId, options) {
+        return this.create({
+            ...options,
+            parent_task: parentId,
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Dependencies (via OpenTasks edges)
+    // ─────────────────────────────────────────────────────────────────────────────
+    async addBlocker(taskId, blockerId) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        const blocker = this.eventStore.getTask(blockerId);
+        if (!blocker) {
+            throw new OpenTasksBackendError(`Blocker task not found: ${blockerId}`, "TASK_NOT_FOUND", blockerId);
+        }
+        // Record in EventStore
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: task.assigned_agent ?? task.created_by },
+            payload: {
+                task_id: taskId,
+                action: "blocker_added",
+                details: { blocker_id: blockerId },
+            },
+        });
+        // Create 'blocks' edge in OpenTasks if both tasks are mapped
+        const blockerIssueId = this.taskToIssue.get(blockerId);
+        const taskIssueId = this.taskToIssue.get(taskId);
+        if (blockerIssueId && taskIssueId) {
+            await this.client.createEdge(blockerIssueId, taskIssueId, "blocks");
+        }
+    }
+    async removeBlocker(taskId, blockerId) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        // Record in EventStore
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: task.assigned_agent ?? task.created_by },
+            payload: {
+                task_id: taskId,
+                action: "blocker_removed",
+                details: { blocker_id: blockerId },
+            },
+        });
+        // Remove 'blocks' edge in OpenTasks if both are mapped
+        const blockerIssueId = this.taskToIssue.get(blockerId);
+        const taskIssueId = this.taskToIssue.get(taskId);
+        if (blockerIssueId && taskIssueId) {
+            await this.client.removeEdge(blockerIssueId, taskIssueId, "blocks");
+        }
+    }
+    async getBlockers(taskId) {
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        // Try OpenTasks first for mapped tasks
+        const issueId = this.taskToIssue.get(taskId);
+        if (issueId) {
+            try {
+                const blockerSummaries = await this.client.getBlockers(issueId);
+                const blockers = [];
+                for (const summary of blockerSummaries) {
+                    const blockerTaskId = this.issueToTask.get(summary.id);
+                    if (blockerTaskId) {
+                        const blockerTask = this.eventStore.getTask(blockerTaskId);
+                        if (blockerTask) {
+                            blockers.push(this.toExtendedTask(blockerTask));
+                        }
+                    }
+                }
+                return blockers;
+            }
+            catch {
+                // Fall through to EventStore
+            }
+        }
+        // Fallback: use EventStore blockers
+        const blockerIds = task.blockers ?? [];
+        const blockers = [];
+        for (const blockerId of blockerIds) {
+            const blocker = this.eventStore.getTask(blockerId);
+            if (blocker) {
+                blockers.push(this.toExtendedTask(blocker));
+            }
+        }
+        return blockers;
+    }
+    async getBlocking(taskId) {
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        // Try OpenTasks first for mapped tasks
+        const issueId = this.taskToIssue.get(taskId);
+        if (issueId) {
+            try {
+                const blockingSummaries = await this.client.getBlocking(issueId);
+                const blocking = [];
+                for (const summary of blockingSummaries) {
+                    const blockedTaskId = this.issueToTask.get(summary.id);
+                    if (blockedTaskId) {
+                        const blockedTask = this.eventStore.getTask(blockedTaskId);
+                        if (blockedTask) {
+                            blocking.push(this.toExtendedTask(blockedTask));
+                        }
+                    }
+                }
+                return blocking;
+            }
+            catch {
+                // Fall through to EventStore
+            }
+        }
+        // Fallback: scan EventStore
+        const allTasks = this.eventStore.listTasks();
+        const blocking = allTasks.filter((t) => t.blockers?.includes(taskId));
+        return blocking.map((t) => this.toExtendedTask(t));
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Pull Model (Claim/Unclaim)
+    // ─────────────────────────────────────────────────────────────────────────────
+    async claim(agentId, filter) {
+        this.ensureOpen();
+        const candidates = await this.listClaimable(filter);
+        if (candidates.length === 0) {
+            return null;
+        }
+        const task = candidates[0];
+        // Re-check for contention
+        const current = this.eventStore.getTask(task.id);
+        if (!current || current.status !== "pending" || current.assigned_agent) {
+            return null;
+        }
+        // Assign locally
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: agentId },
+            payload: {
+                task_id: task.id,
+                action: "assigned",
+                details: { agent_id: agentId },
+            },
+        });
+        // Claim in OpenTasks
+        const issueId = this.taskToIssue.get(task.id);
+        if (issueId) {
+            await this.client.updateIssue(issueId, {
+                assignee: agentId,
+                metadata: { claimed_by: agentId },
+            });
+        }
+        const assigned = this.eventStore.getTask(task.id);
+        return this.toExtendedTask(assigned);
+    }
+    async unclaim(taskId) {
+        this.ensureOpen();
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        if (!task.assigned_agent) {
+            throw new OpenTasksBackendError(`Task is not assigned: ${taskId}`, "TASK_NOT_ASSIGNED", taskId);
+        }
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: task.assigned_agent },
+            payload: {
+                task_id: taskId,
+                action: "unassigned",
+                details: { agent_id: task.assigned_agent },
+            },
+        });
+        // Unclaim in OpenTasks
+        const issueId = this.taskToIssue.get(taskId);
+        if (issueId) {
+            await this.client.updateIssue(issueId, {
+                assignee: null,
+                metadata: { claimed_by: null },
+            });
+        }
+    }
+    async listClaimable(filter) {
+        let tasks = this.eventStore.listTasks();
+        // Only pending, unassigned tasks
+        tasks = tasks.filter((t) => t.status === "pending" && !t.assigned_agent);
+        if (filter) {
+            if (filter.tags && filter.tags.length > 0) {
+                const filterTags = new Set(filter.tags);
+                tasks = tasks.filter((t) => t.tags?.some((tag) => filterTags.has(tag)));
+            }
+            if (filter.rootTasksOnly) {
+                tasks = tasks.filter((t) => !t.parent_task);
+            }
+            if (filter.created_by) {
+                tasks = tasks.filter((t) => t.created_by === filter.created_by);
+            }
+        }
+        // Filter out blocked tasks
+        const extended = await Promise.all(tasks.map((t) => this.toExtendedTaskAsync(t)));
+        return extended.filter((t) => !t.isBlocked);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // History
+    // ─────────────────────────────────────────────────────────────────────────────
+    async getAgentHistory(taskId) {
+        const task = this.eventStore.getTask(taskId);
+        if (!task) {
+            throw new OpenTasksBackendError(`Task not found: ${taskId}`, "TASK_NOT_FOUND", taskId);
+        }
+        return task.agent_history ?? [];
+    }
+    onTaskChange(callbackOrTaskId, maybeCallback) {
+        const filterTaskId = typeof callbackOrTaskId === "string" ? callbackOrTaskId : undefined;
+        const callback = typeof callbackOrTaskId === "function"
+            ? callbackOrTaskId
+            : maybeCallback;
+        const seenTaskIds = new Set();
+        return this.eventStore.onTaskChange((taskId, task) => {
+            if (filterTaskId && taskId !== filterTaskId)
+                return;
+            let eventType;
+            if (!task) {
+                eventType = "deleted";
+            }
+            else if (seenTaskIds.has(taskId)) {
+                eventType = "updated";
+            }
+            else {
+                eventType = "created";
+                seenTaskIds.add(taskId);
+            }
+            const event = {
+                type: eventType,
+                taskId,
+                task: task ? this.toExtendedTask(task) : {},
+            };
+            callback(event);
+        });
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Public Utility Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Get the OpenTasks issue ID for a macro-agent task.
+     * Returns undefined if the task is not mapped to an issue.
+     */
+    getIssueForTask(taskId) {
+        return this.taskToIssue.get(taskId);
+    }
+    /**
+     * Get the macro-agent task ID for an OpenTasks issue.
+     * Returns undefined if the issue is not mapped to a task.
+     */
+    getTaskForIssue(issueId) {
+        return this.issueToTask.get(issueId);
+    }
+    /**
+     * Import an existing OpenTasks issue as a macro-agent task.
+     * This is useful for pulling tasks from OpenTasks into macro-agent.
+     */
+    async importIssue(issueId, createdBy) {
+        this.ensureOpen();
+        // Check if already imported
+        const existingTaskId = this.issueToTask.get(issueId);
+        if (existingTaskId) {
+            const existing = await this.get(existingTaskId);
+            if (existing)
+                return existing;
+        }
+        const issue = await this.client.getIssue(issueId);
+        if (!issue) {
+            throw new OpenTasksBackendError(`OpenTasks issue not found: ${issueId}`, "NOT_FOUND");
+        }
+        const taskId = `task_${nanoid(12)}`;
+        // Store mapping
+        this.taskToIssue.set(taskId, issueId);
+        this.issueToTask.set(issueId, taskId);
+        // Determine task status from issue
+        const taskStatus = mapOpenTasksStatus(issue.status);
+        // Create in EventStore
+        this.eventStore.emit({
+            type: "task",
+            source: { agent_id: createdBy },
+            payload: {
+                task_id: taskId,
+                action: "created",
+                details: {
+                    description: issue.title,
+                    tags: issue.tags,
+                    external_id: issueId,
+                },
+            },
+        });
+        // If issue is not open/pending, transition to the right status
+        if (taskStatus === "in_progress") {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: createdBy },
+                payload: {
+                    task_id: taskId,
+                    action: "status_change",
+                    details: { status: "in_progress" },
+                },
+            });
+        }
+        else if (taskStatus === "completed") {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: createdBy },
+                payload: {
+                    task_id: taskId,
+                    action: "completed",
+                    details: {},
+                },
+            });
+        }
+        // If issue has an assignee, assign
+        if (issue.assignee) {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: issue.assignee },
+                payload: {
+                    task_id: taskId,
+                    action: "assigned",
+                    details: { agent_id: issue.assignee },
+                },
+            });
+        }
+        return this.issueToExtendedTask(issue, taskId);
+    }
+    /**
+     * Bulk import all open issues from OpenTasks as tasks.
+     */
+    async importOpenIssues(createdBy) {
+        this.ensureOpen();
+        const issues = await this.client.listIssues({
+            status: ["open", "in_progress"],
+            archived: false,
+        });
+        const tasks = [];
+        for (const issue of issues) {
+            // Skip already-imported issues
+            if (this.issueToTask.has(issue.id))
+                continue;
+            // Skip issues not created by macro-agent (unless they have no source)
+            // This allows importing issues from other sources too
+            const task = await this.importIssue(issue.id, createdBy);
+            tasks.push(task);
+        }
+        return tasks;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Private Helpers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Sync a task status change to OpenTasks.
+     */
+    async syncStatusToOpenTasks(taskId, status) {
+        if (!this.config.syncStatus)
+            return;
+        const issueId = this.taskToIssue.get(taskId);
+        if (!issueId)
+            return;
+        const openTasksStatus = mapTaskStatus(status);
+        try {
+            await this.client.updateIssue(issueId, {
+                status: openTasksStatus,
+            });
+        }
+        catch (error) {
+            // Log but don't fail - sync is best-effort
+            console.warn(`Failed to sync status to OpenTasks for ${taskId} (${issueId}): ${error}`);
+        }
+    }
+    /**
+     * Sync a transition that happened via the opentasks daemon's `task` tool.
+     * Updates the EventStore without re-syncing back to opentasks (since the
+     * daemon already processed the transition).
+     *
+     * Accepts either an opentasks issue ID (e.g., "i-xxxx") or an EventStore
+     * task ID (e.g., "task-xxx") — resolves to the EventStore ID either way.
+     *
+     * @param externalId - The opentasks issue ID or EventStore task ID
+     * @param action - The transition action ("complete", "start", "close", "block", "reopen", "assign")
+     * @param agentId - The agent that performed the transition or the assignee for "assign"
+     */
+    async syncExternalTransition(externalId, action, agentId) {
+        // Resolve to EventStore task ID: try opentasks ID lookup first, then direct
+        const taskId = this.issueToTask.get(externalId)
+            ?? (this.eventStore.getTask(externalId) ? externalId : undefined);
+        if (!taskId)
+            return;
+        const task = this.eventStore.getTask(taskId);
+        if (!task)
+            return;
+        const agent = agentId ?? task.assigned_agent ?? task.created_by;
+        // Handle assignment separately — it updates assignee, not status
+        if (action === "assign") {
+            if (task.assigned_agent !== agent) {
+                this.eventStore.emit({
+                    type: "task",
+                    source: { agent_id: agent },
+                    payload: {
+                        task_id: taskId,
+                        action: "assigned",
+                        details: { agent_id: agent },
+                    },
+                });
+            }
+            return;
+        }
+        // Map action to target status
+        const ACTION_TO_STATUS = {
+            complete: "completed",
+            close: "completed",
+            start: "in_progress",
+            block: "pending",
+            reopen: "pending",
+        };
+        const targetStatus = ACTION_TO_STATUS[action];
+        if (!targetStatus || task.status === targetStatus)
+            return;
+        // Emit the appropriate EventStore event
+        if (targetStatus === "completed") {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: agent },
+                payload: { task_id: taskId, action: "completed", details: {} },
+            });
+        }
+        else {
+            this.eventStore.emit({
+                type: "task",
+                source: { agent_id: agent },
+                payload: {
+                    task_id: taskId,
+                    action: "status_change",
+                    details: { status: targetStatus },
+                },
+            });
+        }
+    }
+    /**
+     * Convert an EventStore Task to ExtendedTask with isBlocked computed
+     * from local blockers.
+     */
+    toExtendedTask(task) {
+        const blockerIds = task.blockers ?? [];
+        let isBlocked = false;
+        for (const blockerId of blockerIds) {
+            const blocker = this.eventStore.getTask(blockerId);
+            if (blocker && blocker.status !== "completed") {
+                isBlocked = true;
+                break;
+            }
+        }
+        return {
+            ...task,
+            isBlocked,
+            external_id: this.taskToIssue.get(task.id),
+        };
+    }
+    /**
+     * Convert an EventStore Task to ExtendedTask with isBlocked computed
+     * from OpenTasks graph (async, checks remote blockers).
+     */
+    async toExtendedTaskAsync(task) {
+        const issueId = this.taskToIssue.get(task.id);
+        // If mapped to OpenTasks, use graph-based blocking
+        if (issueId) {
+            try {
+                const blockers = await this.client.getBlockers(issueId);
+                const hasActiveBlockers = blockers.some((b) => b.status && !isIssueComplete(b.status));
+                return {
+                    ...task,
+                    isBlocked: hasActiveBlockers,
+                    external_id: issueId,
+                };
+            }
+            catch {
+                // Fall through to local check
+            }
+        }
+        return this.toExtendedTask(task);
+    }
+    /**
+     * Convert an OpenTasks issue to an ExtendedTask.
+     */
+    issueToExtendedTask(issue, taskId) {
+        const taskStatus = mapOpenTasksStatus(issue.status);
+        return {
+            id: taskId,
+            description: issue.title,
+            status: taskStatus,
+            assigned_agent: issue.assignee,
+            parent_task: undefined, // Resolved separately if needed
+            subtasks: undefined,
+            blockers: undefined,
+            created_at: new Date(issue.created_at).getTime(),
+            started_at: taskStatus === "in_progress"
+                ? new Date(issue.updated_at).getTime()
+                : undefined,
+            completed_at: issue.closed_at
+                ? new Date(issue.closed_at).getTime()
+                : undefined,
+            created_by: issue.metadata?.created_by ?? "unknown",
+            tags: issue.tags,
+            isBlocked: issue.status === "blocked",
+            external_id: issue.id,
+        };
+    }
+}
+/**
+ * Create an OpenTasksTaskBackend instance.
+ */
+export function createOpenTasksTaskBackend(eventStore, client, config) {
+    return new OpenTasksTaskBackend(eventStore, client, config);
+}
+//# sourceMappingURL=backend.js.map