@voybio/ace-swarm 0.1.0

package/dist/tools-lifecycle.js

@@ -0,0 +1,205 @@
+/**
+ * Lifecycle tool registrations: status events, circuit breaker, and kanban.
+ */
+import { z } from "zod";
+import { safeRead, safeWrite } from "./helpers.js";
+import { appendStatusEventSafe, getStatusEventsPath, readStatusEvents, } from "./status-events.js";
+import { refreshKanbanArtifacts } from "./kanban.js";
+export function registerLifecycleTools(server) {
+    server.tool("emit_status_event", "Append a schema-valid lifecycle event into agent-state/STATUS_EVENTS.ndjson", {
+        source_module: z
+            .string()
+            .describe("Module id (capability-* or agent-*), e.g. capability-ops, agent-astgrep"),
+        event_type: z.string().describe("Event type label"),
+        status: z
+            .enum(["started", "in_progress", "pass", "fail", "blocked", "done"])
+            .describe("Lifecycle status"),
+        summary: z.string().describe("Concise summary for the event payload"),
+        payload_json: z
+            .string()
+            .optional()
+            .describe("Optional JSON object string merged into payload"),
+        trace_id: z
+            .string()
+            .optional()
+            .describe("Optional trace id for cross-event linkage"),
+        objective_id: z.string().optional(),
+        decision_id: z.string().optional(),
+    }, async ({ source_module, event_type, status, summary, payload_json, trace_id, objective_id, decision_id, }) => {
+        let payload;
+        if (payload_json) {
+            try {
+                const parsed = JSON.parse(payload_json);
+                if (!parsed ||
+                    typeof parsed !== "object" ||
+                    Array.isArray(parsed)) {
+                    throw new Error("payload_json must parse to an object");
+                }
+                payload = parsed;
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `❌ Invalid payload_json: ${error instanceof Error ? error.message : "parse error"}`,
+                        },
+                    ],
+                };
+            }
+        }
+        const appended = await appendStatusEventSafe({
+            source_module,
+            event_type,
+            status,
+            summary,
+            payload,
+            trace_id,
+            objective_id,
+            decision_id,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "✅ Status event appended",
+                        `Path: ${appended.path}`,
+                        `Event: ${appended.event.event_id}`,
+                        `Trace: ${appended.event.trace_id}`,
+                        `Type: ${appended.event.event_type}`,
+                        `Status: ${appended.event.status}`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("list_status_events", "Read recent STATUS_EVENT entries", {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(500)
+            .optional()
+            .describe("Maximum events to return (default: 100)"),
+    }, async ({ limit }) => {
+        const events = readStatusEvents(limit ?? 100);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Status Events",
+                        "",
+                        `Path: ${getStatusEventsPath()}`,
+                        `Returned: ${events.length}`,
+                        "",
+                        "```json",
+                        JSON.stringify(events, null, 2),
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("open_circuit_breaker", "Open circuit breaker state and emit CIRCUIT_BREAKER_OPENED event", {
+        reason: z
+            .string()
+            .describe("Why downstream execution must be paused"),
+        owner: z
+            .string()
+            .optional()
+            .describe("Owner responsible for unblock"),
+        trace_id: z.string().optional(),
+    }, async ({ reason, owner, trace_id }) => {
+        const timestamp = new Date().toISOString();
+        const current = safeRead("agent-state/STATUS.md");
+        const seed = current.startsWith("[FILE NOT FOUND]") ||
+            current.startsWith("[ACCESS DENIED]")
+            ? "# STATUS\n\n"
+            : current.trimEnd();
+        const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_OPENED: ${reason}${owner ? ` (owner: ${owner})` : ""}\n`;
+        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const event = await appendStatusEventSafe({
+            source_module: "capability-ops",
+            event_type: "CIRCUIT_BREAKER_OPENED",
+            status: "blocked",
+            summary: reason,
+            objective_id: "circuit-breaker",
+            payload: {
+                ...(owner ? { owner } : {}),
+                evidence_ref: "agent-state/STATUS.md",
+            },
+            trace_id,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "✅ Circuit breaker opened",
+                        `Status: ${statusPath}`,
+                        `Event: ${event.event.event_id} (${event.path})`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("close_circuit_breaker", "Close circuit breaker state and emit CIRCUIT_BREAKER_CLOSED event", {
+        reason: z
+            .string()
+            .describe("Why downstream execution can resume"),
+        trace_id: z.string().optional(),
+    }, async ({ reason, trace_id }) => {
+        const timestamp = new Date().toISOString();
+        const current = safeRead("agent-state/STATUS.md");
+        const seed = current.startsWith("[FILE NOT FOUND]") ||
+            current.startsWith("[ACCESS DENIED]")
+            ? "# STATUS\n\n"
+            : current.trimEnd();
+        const next = `${seed}\n- [${timestamp}] CIRCUIT_BREAKER_CLOSED: ${reason}\n`;
+        const statusPath = safeWrite("agent-state/STATUS.md", next);
+        const event = await appendStatusEventSafe({
+            source_module: "capability-ops",
+            event_type: "CIRCUIT_BREAKER_CLOSED",
+            status: "pass",
+            summary: reason,
+            objective_id: "circuit-breaker",
+            payload: {
+                evidence_ref: "agent-state/STATUS.md",
+            },
+            trace_id,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "✅ Circuit breaker closed",
+                        `Status: ${statusPath}`,
+                        `Event: ${event.event.event_id} (${event.path})`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("generate_kanban_ui", "Generate and persist lightweight Kanban HTML snapshot", {}, async () => {
+        const snapshot = refreshKanbanArtifacts("tool:generate_kanban_ui");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Kanban Updated",
+                        "",
+                        `JSON: ${snapshot.json_path}`,
+                        `HTML: ${snapshot.html_path}`,
+                        `Updated: ${snapshot.generated_at}`,
+                        `Counts: backlog=${snapshot.counts.backlog}, blocked=${snapshot.counts.blocked}, in_progress=${snapshot.counts.in_progress}, gated=${snapshot.counts.gated}, done=${snapshot.counts.done}`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-lifecycle.js.map

package/dist/tools-memory.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Memory tool registrations – context snapshots and recall.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerMemoryTools(server: McpServer): void;
+//# sourceMappingURL=tools-memory.d.ts.map

package/dist/tools-memory.js

@@ -0,0 +1,260 @@
+/**
+ * Memory tool registrations – context snapshots and recall.
+ */
+import { z } from "zod";
+import { safeRead, safeWrite, wsPath } from "./helpers.js";
+import { isReadError } from "./shared.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { appendStatusEvent } from "./status-events.js";
+import { readRuntimeProfile } from "./runtime-profile.js";
+import { buildAceContinuityPacket, formatAceContinuityPacketMarkdown, normalizeContinuityPolicy, } from "./ace-autonomy.js";
+const CONTEXT_STORE_REL = "agent-state/context-snapshots";
+export function registerMemoryTools(server) {
+    server.tool("context_snapshot", "Capture a named context snapshot for later retrieval (decisions, progress, state)", {
+        name: z.string().describe("Snapshot name/label for retrieval"),
+        summary: z.string().describe("Brief summary of current context"),
+        decisions: z
+            .array(z.string())
+            .optional()
+            .describe("Key decisions made"),
+        open_questions: z
+            .array(z.string())
+            .optional()
+            .describe("Unresolved questions"),
+        artifacts: z
+            .array(z.string())
+            .optional()
+            .describe("Key artifact paths"),
+        metadata: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Additional metadata"),
+    }, async ({ name, summary, decisions, open_questions, artifacts, metadata }) => {
+        const timestamp = new Date().toISOString();
+        const snapshot = {
+            name,
+            timestamp,
+            summary,
+            decisions: decisions ?? [],
+            open_questions: open_questions ?? [],
+            artifacts: artifacts ?? [],
+            metadata: metadata ?? {},
+        };
+        const slug = name
+            .trim()
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .slice(0, 48);
+        const filename = `${slug}.json`;
+        const path = wsPath(CONTEXT_STORE_REL, filename);
+        safeWrite(path, JSON.stringify(snapshot, null, 2));
+        // Update index
+        const indexPath = wsPath(CONTEXT_STORE_REL, "index.json");
+        const indexRaw = safeRead(indexPath);
+        let index = { snapshots: [] };
+        if (!isReadError(indexRaw)) {
+            try {
+                index = JSON.parse(indexRaw);
+            }
+            catch {
+                /* keep default */
+            }
+        }
+        index.snapshots = index.snapshots.filter((s) => s.name !== name);
+        index.snapshots.push({ name, file: filename, timestamp, summary });
+        index.snapshots.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        safeWrite(indexPath, JSON.stringify(index, null, 2));
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "context_snapshot",
+            category: "info",
+            message: `Context snapshot captured: ${name}`,
+            artifacts: [path],
+            metadata: {
+                name,
+                decisions_count: (decisions ?? []).length,
+            },
+        });
+        appendStatusEvent({
+            source_module: "capability-memory",
+            event_type: "CONTEXT_SNAPSHOT",
+            status: "done",
+            summary: `Snapshot: ${name} — ${summary}`,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "✅ Context snapshot saved",
+                        `Name: ${name}`,
+                        `Path: ${path}`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("build_continuity_packet", "Build a compact ACE continuity packet derived from file-backed truth and recent runtime telemetry", {
+        snapshot_name: z
+            .string()
+            .optional()
+            .describe("Optional context snapshot name to include"),
+        source_paths: z
+            .array(z.string())
+            .optional()
+            .describe("Optional override for the continuity source path order"),
+        state_sources: z
+            .array(z.string())
+            .optional()
+            .describe("Backward-compatible alias for continuity source paths"),
+        max_sources: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional cap on included state sources"),
+        max_excerpt_chars: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional per-source excerpt cap"),
+        max_total_chars: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional total excerpt character budget"),
+        max_status_events: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional recent status-event window"),
+        max_run_ledger_entries: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Optional recent run-ledger window"),
+        include_snapshot: z
+            .boolean()
+            .optional()
+            .describe("Whether to include the selected snapshot summary"),
+    }, async ({ snapshot_name, source_paths, state_sources, max_sources, max_excerpt_chars, max_total_chars, max_status_events, max_run_ledger_entries, include_snapshot, }) => {
+        const runtimeProfile = readRuntimeProfile();
+        const continuity = normalizeContinuityPolicy({
+            ...runtimeProfile.continuity,
+            ...((source_paths ?? state_sources) == null
+                ? {}
+                : { source_paths: source_paths ?? state_sources }),
+            ...(max_sources == null ? {} : { max_sources }),
+            ...(max_excerpt_chars == null ? {} : { max_excerpt_chars }),
+            ...(max_total_chars == null ? {} : { max_total_chars }),
+            ...(max_status_events == null ? {} : { max_status_events }),
+            ...(max_run_ledger_entries == null ? {} : { max_run_ledger_entries }),
+            ...(include_snapshot == null ? {} : { include_snapshot }),
+        });
+        const packet = buildAceContinuityPacket({
+            snapshot_name,
+            policy: continuity,
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# ACE Continuity Packet",
+                        "",
+                        formatAceContinuityPacketMarkdown(packet),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("recall_context", "Retrieve a previously saved context snapshot by name, or list all snapshots", {
+        name: z
+            .string()
+            .optional()
+            .describe("Snapshot name to retrieve (omit for list)"),
+    }, async ({ name }) => {
+        const indexPath = wsPath(CONTEXT_STORE_REL, "index.json");
+        const indexRaw = safeRead(indexPath);
+        if (isReadError(indexRaw)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "No context snapshots found. Use `context_snapshot` to create one.",
+                    },
+                ],
+            };
+        }
+        let index;
+        try {
+            index = JSON.parse(indexRaw);
+        }
+        catch {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "❌ Corrupt context index. Re-capture snapshots.",
+                    },
+                ],
+            };
+        }
+        if (!name) {
+            const lines = index.snapshots.map((s) => `- **${s.name}** (${s.timestamp.slice(0, 10)}) — ${s.summary}`);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            `# Context Snapshots (${index.snapshots.length})`,
+                            "",
+                            ...(lines.length > 0 ? lines : ["(none)"]),
+                        ].join("\n"),
+                    },
+                ],
+            };
+        }
+        const match = index.snapshots.find((s) => s.name.toLowerCase() === name.toLowerCase());
+        if (!match) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Snapshot not found: "${name}"\n\nAvailable: ${index.snapshots.map((s) => s.name).join(", ") || "(none)"}`,
+                    },
+                ],
+            };
+        }
+        const content = safeRead(wsPath(CONTEXT_STORE_REL, match.file));
+        if (isReadError(content)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Snapshot file missing: ${match.file}`,
+                    },
+                ],
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# Context Snapshot: ${match.name}`,
+                        "",
+                        "```json",
+                        content,
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-memory.js.map

package/dist/tools-scheduler.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Job scheduler tool registrations.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSchedulerTools(server: McpServer): void;
+//# sourceMappingURL=tools-scheduler.d.ts.map