@voybio/ace-swarm 0.1.0

package/dist/tools-handoff.js

@@ -0,0 +1,489 @@
+/**
+ * Handoff management tool registrations.
+ */
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, readTaskArtifact, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ROLE_ENUM, HANDOFF_VALIDATION_MODE, HANDOFF_LIFECYCLE_STATUS_ENUM, } from "./shared.js";
+import { validateHandoffPayload, validateSwarmHandoffPayload, lintHandoffPayload, } from "./schemas.js";
+import { acknowledgeHandoffSafe, getHandoffRegistryPath, readHandoffRegistry, registerHandoffSafe, } from "./handoff-registry.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { refreshKanbanArtifacts } from "./kanban.js";
+import { dispatchJobs, enqueueJob } from "./job-scheduler.js";
+import { appendStatusEventSafe } from "./status-events.js";
+const DEFAULT_SCHEDULER_OWNER = "capability-ops";
+function toSchedulerPriority(input) {
+    if (input === "P0" || input === "P1" || input === "P2" || input === "P3") {
+        return input;
+    }
+    return "P2";
+}
+function handoffSchedulerJobId(handoffId) {
+    const normalized = handoffId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return `HNDJOB-${normalized}`;
+}
+function buildHandoffResources(record) {
+    const resources = ["agent-state/handoff-registry.json"];
+    if (record.source_file && record.source_file.trim().length > 0) {
+        resources.push(record.source_file.trim());
+    }
+    else {
+        resources.push(`${ACE_TASKS_ROOT_REL}/SWARM_HANDOFF.json`);
+    }
+    return Array.from(new Set(resources));
+}
+async function recordHandoffSchedulerSyncEffects(record, sync) {
+    if (sync.enqueued) {
+        await appendStatusEventSafe({
+            source_module: "capability-ops",
+            event_type: "HANDOFF_SCHEDULER_SYNCED",
+            status: "started",
+            summary: `Handoff ${record.handoff_id} synced as scheduler job ${sync.job_id}`,
+            payload: {
+                handoff_id: record.handoff_id,
+                job_id: sync.job_id,
+                priority: toSchedulerPriority(record.priority),
+                kind: "handoff.lifecycle",
+                resource_requirements: buildHandoffResources(record),
+            },
+        });
+        await appendRunLedgerEntrySafe({
+            tool: "sync_handoff_into_scheduler",
+            category: "major_update",
+            message: `Synced handoff ${record.handoff_id} into scheduler as ${sync.job_id}`,
+            artifacts: ["agent-state/job-queue.json", "agent-state/handoff-registry.json"],
+            metadata: {
+                handoff_id: record.handoff_id,
+                job_id: sync.job_id,
+                priority: toSchedulerPriority(record.priority),
+            },
+        });
+    }
+}
+export async function syncHandoffIntoScheduler(record, options = {}) {
+    const owner = options.owner?.trim() || DEFAULT_SCHEDULER_OWNER;
+    const jobId = handoffSchedulerJobId(record.handoff_id);
+    const enqueue = await enqueueJob({
+        job_id: jobId,
+        kind: "handoff.lifecycle",
+        priority: toSchedulerPriority(record.priority),
+        payload: {
+            handoff_id: record.handoff_id,
+            from: record.from,
+            to: record.to,
+            title: record.title,
+            status: record.status,
+            task_type: record.task_type ?? "",
+        },
+        dependencies: [
+            {
+                kind: "handoff",
+                ref: record.handoff_id,
+                expected: "accepted|completed",
+            },
+        ],
+        resource_requirements: buildHandoffResources(record),
+    });
+    const enqueued = enqueue.ok;
+    const enqueueReason = enqueue.ok || !enqueue.nack
+        ? undefined
+        : `${enqueue.nack.reason_code}: ${enqueue.nack.reason}`;
+    const tick = await dispatchJobs({
+        owner,
+        ...(options.now_iso ? { now_iso: options.now_iso } : {}),
+    });
+    const syncResult = {
+        ok: enqueue.ok || enqueue.nack?.reason_code === "duplicate_job_id",
+        job_id: jobId,
+        enqueued,
+        enqueue_reason: enqueueReason,
+        tick,
+    };
+    await recordHandoffSchedulerSyncEffects(record, syncResult);
+    return syncResult;
+}
+export async function backfillHandoffsIntoScheduler(options = {}) {
+    const registry = readHandoffRegistry();
+    const active = Object.values(registry.handoffs)
+        .filter((record) => record.status !== "completed")
+        .sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+    const result = {
+        scanned: active.length,
+        synced: 0,
+        enqueued: 0,
+        failures: [],
+    };
+    for (const record of active) {
+        try {
+            const sync = await syncHandoffIntoScheduler(record, options);
+            if (sync.ok) {
+                result.synced += 1;
+                if (sync.enqueued) {
+                    result.enqueued += 1;
+                }
+            }
+            else {
+                result.failures.push({
+                    handoff_id: record.handoff_id,
+                    error: sync.enqueue_reason ?? "scheduler sync returned not-ok",
+                });
+            }
+        }
+        catch (error) {
+            result.failures.push({
+                handoff_id: record.handoff_id,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return result;
+}
+export function registerHandoffTools(server) {
+    server.tool("create_handoff", "Generate a SWARM_HANDOFF.json payload for routing work between ACE agents", {
+        from: ROLE_ENUM.describe("Source agent"),
+        to: ROLE_ENUM.describe("Target agent"),
+        title: z.string().describe("Short task title"),
+        task_type: z
+            .enum(["venture", "ux", "engineering", "mixed"])
+            .describe("Domain"),
+        priority: z.enum(["P0", "P1", "P2"]).describe("Priority level"),
+        directive: z.string().describe("Plain-language action directive"),
+        acceptance_criteria: z
+            .array(z.string())
+            .min(1)
+            .describe("Measurable acceptance criteria"),
+        context_pointers: z
+            .object({
+            business_requirement: z.string().optional(),
+            design_constraint: z.string().optional(),
+            engineering_constraint: z.string().optional(),
+        })
+            .optional()
+            .describe("File:line pointers for context"),
+    }, async ({ from, to, title, task_type, priority, directive, acceptance_criteria, context_pointers, }) => {
+        const now = new Date();
+        const dateStr = now.toISOString().slice(0, 10).replace(/-/g, "");
+        const shortId = randomUUID().replace(/-/g, "").slice(0, 8);
+        const handoff = {
+            handoff_id: `HND-${dateStr}-${shortId}`,
+            timestamp_utc: now.toISOString(),
+            router: {
+                from: `ACE-${from.charAt(0).toUpperCase() + from.slice(1)}`,
+                via: "ACE-Orchestrator",
+                to: `ACE-${to.charAt(0).toUpperCase() + to.slice(1)}`,
+            },
+            task: {
+                title,
+                type: task_type,
+                priority,
+                owner: `ACE-${to.toUpperCase()}`,
+                depends_on: [],
+                scope: title,
+            },
+            context: {
+                business_requirement: context_pointers?.business_requirement || "",
+                design_constraint: context_pointers?.design_constraint || "",
+                engineering_constraint: context_pointers?.engineering_constraint || "",
+                directive,
+            },
+            acceptance_criteria,
+            deliverables: [],
+            verification: {
+                required_evidence: ["artifact_pointers", "verification_evidence"],
+                review_check: "Would a staff engineer approve this?",
+                status: "pending",
+            },
+            risks: [],
+            open_questions: [],
+            lessons_hook: {
+                on_correction_update: "tasks/lessons.md",
+                rule_format: "Never <bad pattern>; always <guardrail>.",
+            },
+            return_payload_contract: {
+                must_include: [
+                    "updated_artifact_pointers",
+                    "verification_evidence",
+                    "residual_risks",
+                    "explicit_blockers_or_done_state",
+                ],
+            },
+        };
+        const validation = validateSwarmHandoffPayload(handoff);
+        if (!validation.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "❌ Generated handoff failed schema validation.",
+                            `Schema: ${validation.schema}`,
+                            "",
+                            ...validation.errors.map((error) => `- ${error}`),
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        // Deep lint: route legitimacy + evidence existence
+        const lint = lintHandoffPayload(handoff, WORKSPACE_ROOT);
+        if (!lint.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            "❌ Handoff failed deep lint checks.",
+                            "",
+                            ...lint.errors.map((e) => `- ERROR: ${e}`),
+                            ...lint.warnings.map((w) => `- WARN: ${w}`),
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        const timeStr = now
+            .toISOString()
+            .replace(/[-:]/g, "")
+            .replace("T", "-")
+            .slice(0, 15);
+        const filePath = wsPath("tasks", `SWARM_HANDOFF.${from}_to_${to}_${timeStr}_${shortId}.json`);
+        safeWrite(filePath, JSON.stringify(handoff, null, 2));
+        const registry = await registerHandoffSafe({
+            handoff_id: handoff.handoff_id,
+            from: handoff.router.from,
+            to: handoff.router.to,
+            title: handoff.task.title,
+            task_type: handoff.task.type,
+            priority: handoff.task.priority,
+            source_file: normalizePathForValidation(filePath),
+        });
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "create_handoff",
+            category: "major_update",
+            message: `Created handoff ${handoff.handoff_id} (${handoff.router.from} -> ${handoff.router.to})`,
+            artifacts: [
+                normalizePathForValidation(filePath),
+                "agent-state/handoff-registry.json",
+            ],
+            metadata: {
+                handoff_id: handoff.handoff_id,
+                priority: handoff.task.priority,
+                task_type: handoff.task.type,
+                status: registry.record.status,
+            },
+        });
+        const schedulerSync = await syncHandoffIntoScheduler(registry.record);
+        const kanban = refreshKanbanArtifacts("tool:create_handoff");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Handoff Created",
+                        "",
+                        `Schema: ${validation.schema}`,
+                        `Saved to: ${filePath}`,
+                        `Handoff registry: ${registry.path}`,
+                        `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
+                        `Scheduler job: ${schedulerSync.job_id} (${schedulerSync.enqueued ? "enqueued" : "already_exists"})`,
+                        `Scheduler dispatch: lease_acquired=${schedulerSync.tick.lease_acquired}, started=${schedulerSync.tick.summary.started_jobs}, ready=${schedulerSync.tick.summary.ready_jobs}`,
+                        schedulerSync.enqueue_reason
+                            ? `Scheduler enqueue detail: ${schedulerSync.enqueue_reason}`
+                            : "",
+                        "",
+                        `Kanban updated: ${kanban.html_path}`,
+                        `Kanban counts: backlog=${kanban.counts.backlog}, blocked=${kanban.counts.blocked}, in_progress=${kanban.counts.in_progress}, gated=${kanban.counts.gated}, done=${kanban.counts.done}`,
+                        "",
+                        "```json",
+                        JSON.stringify(handoff, null, 2),
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("validate_handoff", "Validate handoff payloads against SWARM or agent-state schema contracts", {
+        handoff_json: z.string().describe("The handoff JSON string to validate"),
+        schema_mode: HANDOFF_VALIDATION_MODE.describe("Validation mode: auto, swarm, or agent-state"),
+    }, async ({ handoff_json, schema_mode }) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(handoff_json);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "❌ Invalid JSON: could not parse payload.",
+                    },
+                ],
+            };
+        }
+        const validation = validateHandoffPayload(parsed, schema_mode ?? "auto");
+        if (!validation.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Validation failed (${validation.errors.length} issues):\nSchema: ${validation.schema}\n\n${validation.errors
+                            .map((error) => `- ${error}`)
+                            .join("\n")}`,
+                    },
+                ],
+            };
+        }
+        const lint = lintHandoffPayload(parsed, WORKSPACE_ROOT);
+        if (!lint.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `❌ Handoff deep lint failed (${lint.errors.length} issues).`,
+                            `Schema: ${validation.schema}`,
+                            "",
+                            ...lint.errors.map((error) => `- ${error}`),
+                            ...lint.warnings.map((warning) => `- WARN: ${warning}`),
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        const warningBlock = lint.warnings.length > 0
+            ? `\nWarnings:\n${lint.warnings.map((warning) => `- ${warning}`).join("\n")}`
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `✅ Handoff payload is valid.\nSchema: ${validation.schema}${warningBlock}`,
+                },
+            ],
+        };
+    });
+    server.tool("get_handoff_template", "Get the canonical SWARM_HANDOFF.json template", {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: `# Handoff Template\n\n\`\`\`json\n${readTaskArtifact("handoff_template")}\n\`\`\``,
+            },
+        ],
+    }));
+    server.tool("get_handoff_status", "Read persisted handoff lifecycle registry and optional specific handoff status", {
+        handoff_id: z
+            .string()
+            .optional()
+            .describe("Optional handoff id; omit for full registry"),
+    }, async ({ handoff_id }) => {
+        const registry = readHandoffRegistry();
+        const path = getHandoffRegistryPath();
+        if (handoff_id) {
+            const record = registry.handoffs[handoff_id];
+            if (!record) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `❌ handoff_id not found: ${handoff_id}\nRegistry: ${path}`,
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `# Handoff Status\n\nRegistry: ${path}\n\n\`\`\`json\n${JSON.stringify(record, null, 2)}\n\`\`\``,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `# Handoff Registry\n\nPath: ${path}\n\n\`\`\`json\n${JSON.stringify(registry, null, 2)}\n\`\`\``,
+                },
+            ],
+        };
+    });
+    server.tool("ack_handoff", "Update persisted handoff lifecycle status (open/accepted/blocked/completed)", {
+        handoff_id: z.string().describe("Handoff identifier"),
+        status: HANDOFF_LIFECYCLE_STATUS_ENUM.describe("Lifecycle status"),
+        note: z.string().optional().describe("Optional status note"),
+    }, async ({ handoff_id, status, note }) => {
+        const ack = await acknowledgeHandoffSafe({
+            handoff_id,
+            status,
+            note,
+        });
+        if (!ack.ok) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `❌ ${ack.error ?? "Handoff acknowledgement failed."}`,
+                            ack.previous_status
+                                ? `Current status: ${ack.previous_status}`
+                                : "",
+                            ack.allowed?.length
+                                ? `Allowed transitions: ${ack.allowed.join(", ")}`
+                                : "",
+                            `Registry: ${ack.path}`,
+                        ]
+                            .filter(Boolean)
+                            .join("\n"),
+                    },
+                ],
+            };
+        }
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "ack_handoff",
+            category: status === "blocked" ? "regression" : "major_update",
+            message: `Handoff ${handoff_id} transitioned ${ack.previous_status ?? "unknown"} -> ${status}`,
+            artifacts: ["agent-state/handoff-registry.json"],
+            metadata: {
+                handoff_id,
+                from: ack.previous_status ?? "",
+                to: status,
+                note: note ?? "",
+            },
+        });
+        const schedulerSync = ack.record
+            ? await syncHandoffIntoScheduler(ack.record)
+            : undefined;
+        const kanban = refreshKanbanArtifacts("tool:ack_handoff");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Handoff Status Updated",
+                        "",
+                        `handoff_id: ${handoff_id}`,
+                        `status: ${ack.previous_status ?? status} -> ${status}`,
+                        `registry: ${ack.path}`,
+                        `run-ledger: ${runLedger.path} (${runLedger.entry.id})`,
+                        schedulerSync
+                            ? `scheduler-job: ${schedulerSync.job_id} (${schedulerSync.enqueued ? "enqueued" : "already_exists"})`
+                            : "",
+                        schedulerSync
+                            ? `scheduler-dispatch: lease_acquired=${schedulerSync.tick.lease_acquired}, started=${schedulerSync.tick.summary.started_jobs}, ready=${schedulerSync.tick.summary.ready_jobs}`
+                            : "",
+                        schedulerSync?.enqueue_reason
+                            ? `scheduler-enqueue-detail: ${schedulerSync.enqueue_reason}`
+                            : "",
+                        `kanban: ${kanban.html_path}`,
+                        `kanban-counts: backlog=${kanban.counts.backlog}, blocked=${kanban.counts.blocked}, in_progress=${kanban.counts.in_progress}, gated=${kanban.counts.gated}, done=${kanban.counts.done}`,
+                        note ? `note: ${note}` : "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-handoff.js.map

package/dist/tools-lifecycle.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Lifecycle tool registrations: status events, circuit breaker, and kanban.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerLifecycleTools(server: McpServer): void;
+//# sourceMappingURL=tools-lifecycle.d.ts.map