@voybio/ace-swarm 0.1.0

package/dist/tools-files.js

@@ -0,0 +1,679 @@
+/**
+ * File operation tool registrations + new safe-edit and diff tools.
+ */
+import { readdirSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { z } from "zod";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWrite, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { looksLikeSwarmHandoffPath } from "./shared.js";
+import { validateAgentStateHandoffPayload, validateArtifactManifestPayload, validateProvenanceLogContent, validateStatusEventsNdjsonContent, validateSwarmHandoffPayload, validateTealConfigContent, validateRuntimeExecutorSessionRegistryPayload, validateRuntimeToolSpecRegistryPayload, validateTrackerSnapshotPayload, validateVericifyBridgeSnapshotPayload, validateVericifyProcessPostLogPayload, validateWorkspaceSessionRegistryPayload, lintHandoffPayload, } from "./schemas.js";
+import { syncTodoStateSafe } from "./todo-state.js";
+import { validateRuntimeProfileContent } from "./runtime-profile.js";
+import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanban.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { appendStatusEventSafe } from "./status-events.js";
+import { safeEditFile, diffContents } from "./safe-edit.js";
+export function registerFileTools(server) {
+    // ── Append-only artifact protection ───────────────────────────────
+    // These files must only grow; overwrites from the generic write tool
+    // would violate their immutable-log contract.
+    const APPEND_ONLY_PATHS = new Set([
+        "agent-state/EVIDENCE_LOG.md",
+        "agent-state/DECISIONS.md",
+        "agent-state/STATUS_EVENTS.ndjson",
+        "agent-state/run-ledger.json",
+        "agent-state/handoff-registry.json",
+        "agent-state/PROVENANCE_LOG.md",
+    ]);
+    // ── Core file operations ──────────────────────────────────────────
+    server.tool("read_workspace_file", "Read any workspace file by relative path", {
+        path: z.string().describe("Relative path from workspace root"),
+    }, async ({ path }) => ({
+        content: [{ type: "text", text: safeRead(path) }],
+    }));
+    server.tool("write_workspace_file", "Write or update a workspace file", {
+        path: z.string().describe("Relative path from workspace root"),
+        content: z.string().describe("File content"),
+    }, async ({ path, content }) => {
+        const normalizedPath = normalizePathForValidation(path);
+        const validationNotes = [];
+        // ── Append-only guard ───────────────────────────────────────────
+        if (APPEND_ONLY_PATHS.has(normalizedPath)) {
+            const existing = safeRead(path);
+            const fileExists = !existing.startsWith("[FILE NOT FOUND]") && !existing.startsWith("[ACCESS DENIED]");
+            if (fileExists) {
+                // Only allow writes that are strict supersets (append).
+                const isAppend = content.startsWith(existing.trimEnd());
+                if (!isAppend) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `❌ ${normalizedPath} is append-only. Use the dedicated append API (appendStatusEvent, appendRunLedgerEntry, etc.) instead of overwriting via write_workspace_file.`,
+                            },
+                        ],
+                    };
+                }
+            }
+        }
+        // Enforce schema contracts on key execution artifacts.
+        if (normalizedPath === "agent-state/HANDOFF.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/HANDOFF.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateAgentStateHandoffPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/HANDOFF.json failed schema validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath.startsWith("agent-state/HANDOFF_HISTORY/") &&
+            normalizedPath.endsWith(".json")) {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ HANDOFF history entries must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateAgentStateHandoffPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ HANDOFF history payload failed schema validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/STATUS_EVENTS.ndjson") {
+            const validation = validateStatusEventsNdjsonContent(content);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/STATUS_EVENTS.ndjson failed schema validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/TEAL_CONFIG.md") {
+            const validation = validateTealConfigContent(content);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/TEAL_CONFIG.md failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/PROVENANCE_LOG.md") {
+            const validation = validateProvenanceLogContent(content);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/PROVENANCE_LOG.md failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/ACE_WORKFLOW.md") {
+            const validation = validateRuntimeProfileContent(content);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/ACE_WORKFLOW.md failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/runtime-workspaces.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/runtime-workspaces.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateWorkspaceSessionRegistryPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/runtime-workspaces.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/tracker-snapshot.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/tracker-snapshot.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateTrackerSnapshotPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/tracker-snapshot.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/runtime-tool-specs.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/runtime-tool-specs.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateRuntimeToolSpecRegistryPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/runtime-tool-specs.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/runtime-executor-sessions.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/runtime-executor-sessions.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateRuntimeExecutorSessionRegistryPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/runtime-executor-sessions.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/vericify/ace-bridge.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/vericify/ace-bridge.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateVericifyBridgeSnapshotPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/vericify/ace-bridge.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath === "agent-state/vericify/process-posts.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ agent-state/vericify/process-posts.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateVericifyProcessPostLogPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ agent-state/vericify/process-posts.json failed validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (normalizedPath.endsWith("/ARTIFACT_MANIFEST.json") ||
+            normalizedPath === "ARTIFACT_MANIFEST.json") {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ ARTIFACT_MANIFEST.json must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateArtifactManifestPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ ARTIFACT_MANIFEST.json failed schema validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+        }
+        else if (looksLikeSwarmHandoffPath(normalizedPath)) {
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "❌ SWARM_HANDOFF payloads must be valid JSON before write.",
+                        },
+                    ],
+                };
+            }
+            const validation = validateSwarmHandoffPayload(parsed);
+            if (!validation.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ SWARM_HANDOFF payload failed schema validation.",
+                                `Schema: ${validation.schema}`,
+                                ...validation.errors.map((error) => `- ${error}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            validationNotes.push(`validated ${validation.schema}`);
+            // Deep lint: route legitimacy + evidence existence
+            const lint = lintHandoffPayload(parsed, WORKSPACE_ROOT);
+            if (!lint.ok) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: [
+                                "❌ SWARM_HANDOFF payload failed deep lint checks.",
+                                ...lint.errors.map((e) => `- ERROR: ${e}`),
+                                ...lint.warnings.map((w) => `- WARN: ${w}`),
+                            ].join("\n"),
+                        },
+                    ],
+                };
+            }
+            if (lint.warnings.length > 0) {
+                validationNotes.push(`lint warnings: ${lint.warnings.join("; ")}`);
+            }
+        }
+        const abs = safeWrite(path, content);
+        let todoStateSuffix = "";
+        if (normalizedPath === `${ACE_TASKS_ROOT_REL}/todo.md`) {
+            const synced = await syncTodoStateSafe(content);
+            todoStateSuffix = `\nTODO state synced: ${synced.path}`;
+        }
+        let kanbanSuffix = "";
+        const shouldRefreshKanban = shouldAutoRefreshKanbanForPath(normalizedPath);
+        if (shouldRefreshKanban) {
+            const kanban = refreshKanbanArtifacts(`tool:write_workspace_file:${normalizedPath}`);
+            kanbanSuffix = `\nKanban updated: ${kanban.html_path}\nKanban counts: backlog=${kanban.counts.backlog}, blocked=${kanban.counts.blocked}, in_progress=${kanban.counts.in_progress}, gated=${kanban.counts.gated}, done=${kanban.counts.done}`;
+        }
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "write_workspace_file",
+            category: shouldRefreshKanban ? "major_update" : "info",
+            message: `Wrote workspace file ${normalizedPath}`,
+            artifacts: [normalizedPath],
+            metadata: {
+                validation_notes: validationNotes,
+                auto_refreshed_kanban: shouldRefreshKanban,
+                bytes: content.length,
+            },
+        });
+        const suffix = validationNotes.length > 0
+            ? `\nSchema checks: ${validationNotes.join(", ")}`
+            : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `✅ Written: ${abs}${suffix}${todoStateSuffix}\nRun ledger: ${runLedger.path} (${runLedger.entry.id})${kanbanSuffix}`,
+                },
+            ],
+        };
+    });
+    server.tool("list_workspace", "List files/directories in a workspace path", {
+        path: z
+            .string()
+            .optional()
+            .describe("Relative path (default: workspace root)"),
+    }, async ({ path }) => {
+        const dir = path ? wsPath(path) : WORKSPACE_ROOT;
+        const rel = relative(WORKSPACE_ROOT, dir);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Access denied: path escapes workspace root (${dir})`,
+                    },
+                ],
+            };
+        }
+        try {
+            const entries = readdirSync(dir, { withFileTypes: true })
+                .map((entry) => `${entry.isDirectory() ? "[DIR]" : "[FILE]"} ${entry.name}`)
+                .join("\n");
+            return {
+                content: [{ type: "text", text: `# ${dir}\n\n${entries}` }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `❌ Could not list ${dir}\n${String(err)}`,
+                    },
+                ],
+            };
+        }
+    });
+    // ── Safe-edit (new P0 tool) ───────────────────────────────────────
+    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail.", {
+        path: z.string().describe("Workspace-relative file path to edit"),
+        content: z.string().describe("New file content"),
+        validation_command: z
+            .string()
+            .optional()
+            .describe("Shell command to validate (e.g. 'npx tsc --noEmit')"),
+        test_command: z
+            .string()
+            .optional()
+            .describe("Shell command for tests (e.g. 'npm test')"),
+        backup: z
+            .boolean()
+            .optional()
+            .describe("Keep .ace-backup copy (default: true)"),
+    }, async ({ path, content, validation_command, test_command, backup }) => {
+        const result = safeEditFile({
+            path,
+            content,
+            validation_command,
+            test_command,
+            backup,
+        });
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "safe_edit_file",
+            category: result.ok ? "major_update" : "regression",
+            message: result.ok
+                ? `Safe-edited ${path}`
+                : `Safe-edit FAILED for ${path} — restored original`,
+            artifacts: [path],
+            metadata: {
+                ok: result.ok,
+                original_hash: result.original_hash,
+                new_hash: result.new_hash,
+                restored: result.restored,
+                validation_passed: result.validation_passed,
+                test_passed: result.test_passed,
+            },
+        });
+        if (result.ok) {
+            await appendStatusEventSafe({
+                source_module: "capability-safety",
+                event_type: "SAFE_EDIT_COMPLETED",
+                status: "done",
+                summary: `Safe-edited ${path}`,
+                objective_id: "safe-edit",
+                payload: {
+                    original_hash: result.original_hash,
+                    new_hash: result.new_hash,
+                    evidence_ref: path,
+                },
+            });
+        }
+        else {
+            await appendStatusEventSafe({
+                source_module: "capability-safety",
+                event_type: "SAFE_EDIT_FAILED",
+                status: "fail",
+                summary: `Safe-edit rolled back for ${path}: ${result.error}`,
+                objective_id: "safe-edit",
+                payload: {
+                    evidence_ref: path,
+                },
+            });
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        result.ok ? "✅ Safe-edit succeeded" : "❌ Safe-edit FAILED — original restored",
+                        `Path: ${result.original_path}`,
+                        `Hash: ${result.original_hash} → ${result.new_hash}`,
+                        result.backup_path ? `Backup: ${result.backup_path}` : "",
+                        result.validation_passed !== undefined
+                            ? `Validation: ${result.validation_passed ? "passed" : "FAILED"}`
+                            : "",
+                        result.validation_output
+                            ? `Validation output:\n${result.validation_output.slice(0, 2000)}`
+                            : "",
+                        result.test_passed !== undefined
+                            ? `Tests: ${result.test_passed ? "passed" : "FAILED"}`
+                            : "",
+                        result.test_output
+                            ? `Test output:\n${result.test_output.slice(0, 2000)}`
+                            : "",
+                        result.error ? `Error: ${result.error}` : "",
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    // ── Diff (new P2 tool) ────────────────────────────────────────────
+    server.tool("diff_files", "Compute a line-based diff between two file contents or file paths", {
+        original: z.string().describe("Original content or workspace-relative file path"),
+        modified: z.string().describe("Modified content or workspace-relative file path"),
+        is_path: z
+            .boolean()
+            .optional()
+            .describe("If true, treat original/modified as file paths and read their contents"),
+    }, async ({ original, modified, is_path }) => {
+        let origContent = original;
+        let modContent = modified;
+        if (is_path) {
+            origContent = safeRead(original);
+            modContent = safeRead(modified);
+        }
+        const diff = diffContents(origContent, modContent);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Diff Result",
+                        "",
+                        `Has differences: ${diff.has_diff}`,
+                        `Original lines: ${diff.original_lines}`,
+                        `Modified lines: ${diff.new_lines}`,
+                        `Added: +${diff.added}`,
+                        `Removed: -${diff.removed}`,
+                        "",
+                        "```diff",
+                        diff.diff_summary,
+                        "```",
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-files.js.map

package/dist/tools-framework.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Framework tool registrations: bootstrap, status, config, routing,
+ * plus new run_tests and validate_framework tools.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFrameworkTools(server: McpServer): void;
+//# sourceMappingURL=tools-framework.d.ts.map