@voybio/ace-swarm 0.1.0

package/dist/tools-discovery.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Discovery tool registrations: AST indexing and workspace delta scanning.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDiscoveryTools(server: McpServer): void;
+//# sourceMappingURL=tools-discovery.d.ts.map

package/dist/tools-discovery.js

@@ -0,0 +1,178 @@
+/**
+ * Discovery tool registrations: AST indexing and workspace delta scanning.
+ */
+import { z } from "zod";
+import { normalizePathForValidation } from "./helpers.js";
+import { refreshAstgrepIndex } from "./astgrep-index.js";
+import { scanWorkspaceDelta } from "./index-store.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+export function registerDiscoveryTools(server) {
+    server.tool("refresh_astgrep_index", "Run deterministic AST discovery indexing and persist AST_GREP_INDEX artifacts", {
+        scope: z
+            .string()
+            .optional()
+            .describe("Workspace-relative scope for discovery scan (default: .)"),
+        append_evidence: z
+            .boolean()
+            .optional()
+            .describe("Append summary evidence entry to agent-state/EVIDENCE_LOG.md (default: true)"),
+        emit_event: z
+            .boolean()
+            .optional()
+            .describe("Emit STATUS_EVENT entry for discovery result (default: true)"),
+        include_rep_corpus: z
+            .boolean()
+            .optional()
+            .describe("Include rep_astgrep.cxml corpus mining when available (default: true)"),
+    }, async ({ scope, append_evidence, emit_event, include_rep_corpus }) => {
+        const result = refreshAstgrepIndex({
+            scope,
+            append_evidence,
+            emit_event,
+            include_rep_corpus,
+        });
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "refresh_astgrep_index",
+            category: "info",
+            message: `AST discovery index refreshed for scope ${result.scope}`,
+            artifacts: [
+                normalizePathForValidation(result.output_md_path),
+                normalizePathForValidation(result.output_json_path),
+            ],
+            metadata: {
+                scope: result.scope,
+                astgrep_command: result.astgrep_command,
+                hotspots: result.stats.hotspot_files,
+                rep_sources: result.stats.rep_sources,
+                todo_signals: result.stats.todo_signals,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# AST Discovery Refresh",
+                        "",
+                        `Generated at: ${result.generated_at}`,
+                        `Scope: ${result.scope}`,
+                        `ast-grep command: ${result.astgrep_command ?? "not found"}`,
+                        `AST index markdown: ${result.output_md_path}`,
+                        `AST index json: ${result.output_json_path}`,
+                        `Evidence appended: ${result.evidence_appended ? "yes" : "no"}`,
+                        result.event_id
+                            ? `Status event: ${result.event_id} (${result.event_path})`
+                            : "Status event: skipped",
+                        `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
+                        "",
+                        "## Stats",
+                        `- language profile entries: ${result.stats.language_profile_entries}`,
+                        `- hotspot files: ${result.stats.hotspot_files}`,
+                        `- rep sources: ${result.stats.rep_sources}`,
+                        `- todo signals: ${result.stats.todo_signals}`,
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("scan_workspace_delta", "Compute changed/unchanged/deleted file deltas and persist an index snapshot", {
+        path: z
+            .string()
+            .optional()
+            .describe("Workspace-relative scan root (default: .)"),
+        depth: z
+            .number()
+            .int()
+            .min(0)
+            .max(20)
+            .optional()
+            .describe("Maximum directory depth (default: 6)"),
+        max_files: z
+            .number()
+            .int()
+            .min(1)
+            .max(50000)
+            .optional()
+            .describe("Maximum files to scan before truncation"),
+        include_hidden: z
+            .boolean()
+            .optional()
+            .describe("Include hidden files/directories"),
+        exclude: z
+            .array(z.string())
+            .optional()
+            .describe("Directory/file names to skip"),
+        file_entry_cap: z
+            .number()
+            .int()
+            .min(0)
+            .max(5000)
+            .optional()
+            .describe("Maximum file entries persisted into index.json (default: 0)"),
+        index_path: z
+            .string()
+            .optional()
+            .describe("Relative path for index snapshot JSON (default: agent-state/index.json)"),
+    }, async ({ path, depth, max_files, include_hidden, exclude, file_entry_cap, index_path, }) => {
+        const delta = scanWorkspaceDelta({
+            path,
+            depth,
+            max_files,
+            include_hidden,
+            exclude,
+            file_entry_cap,
+            index_path,
+        });
+        const runLedger = await appendRunLedgerEntrySafe({
+            tool: "scan_workspace_delta",
+            category: "info",
+            message: `Delta scan completed for root ${delta.snapshot.root}`,
+            artifacts: [
+                normalizePathForValidation(delta.index_path),
+                normalizePathForValidation(delta.fingerprint_path),
+            ],
+            metadata: {
+                root: delta.snapshot.root,
+                changed: delta.changed.length,
+                unchanged: delta.unchanged.length,
+                deleted: delta.deleted.length,
+                truncated: delta.truncated,
+            },
+        });
+        const changedPreview = delta.changed.slice(0, 20);
+        const deletedPreview = delta.deleted.slice(0, 20);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Workspace Delta Scan",
+                        "",
+                        `Index path: ${delta.index_path}`,
+                        `Fingerprint path: ${delta.fingerprint_path}`,
+                        `Root: ${delta.snapshot.root}`,
+                        `Scanned files: ${delta.scanned_count}`,
+                        `Stored file entries: ${delta.snapshot.stored_file_count}`,
+                        `File entry cap: ${delta.snapshot.options.file_entry_cap}`,
+                        `Changed: ${delta.changed.length}`,
+                        `Unchanged: ${delta.unchanged.length}`,
+                        `Deleted: ${delta.deleted.length}`,
+                        `Truncated: ${delta.truncated ? "yes" : "no"}`,
+                        `Run ledger: ${runLedger.path} (${runLedger.entry.id})`,
+                        "",
+                        "## Changed (sample)",
+                        ...(changedPreview.length > 0
+                            ? changedPreview.map((file) => `- ${file}`)
+                            : ["- (none)"]),
+                        "",
+                        "## Deleted (sample)",
+                        ...(deletedPreview.length > 0
+                            ? deletedPreview.map((file) => `- ${file}`)
+                            : ["- (none)"]),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+//# sourceMappingURL=tools-discovery.js.map

package/dist/tools-drift.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MCP tools for semantic drift detection and state snapshot management.
+ *
+ * Tools:
+ *   • snapshot_state       — Take a semantic snapshot of tracked directories
+ *   • semantic_diff        — Compare two snapshots for semantic delta
+ *   • drift_report         — Full drift analysis with budget gates
+ *   • list_snapshots       — List available cached snapshots
+ *   • rewrite_targets      — Extract targeted rewrite locations from a delta
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDriftTools(server: McpServer): void;
+//# sourceMappingURL=tools-drift.d.ts.map

package/dist/tools-drift.js

@@ -0,0 +1,357 @@
+/**
+ * MCP tools for semantic drift detection and state snapshot management.
+ *
+ * Tools:
+ *   • snapshot_state       — Take a semantic snapshot of tracked directories
+ *   • semantic_diff        — Compare two snapshots for semantic delta
+ *   • drift_report         — Full drift analysis with budget gates
+ *   • list_snapshots       — List available cached snapshots
+ *   • rewrite_targets      — Extract targeted rewrite locations from a delta
+ */
+import { z } from "zod";
+import { takeSnapshot, listSnapshots, computeSemanticDelta, postCycleSnapshot, extractRewriteTargets, } from "./semantic-cache.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+export function registerDriftTools(server) {
+    // ──────────────────────────────────────────────────────────────────
+    // snapshot_state
+    // ──────────────────────────────────────────────────────────────────
+    server.tool("snapshot_state", "Take a semantic snapshot of agent-state documents (MinHash signatures + section hashes). " +
+        "Use before and after each cycle for drift detection.", {
+        snapshot_id: z
+            .string()
+            .min(1)
+            .describe("Unique ID for this snapshot (e.g. 'cycle_003_pre', 'cycle_003_post')"),
+        tracked_dirs: z
+            .array(z.string())
+            .optional()
+            .describe("Workspace-relative directories to scan (default: agent-state, global-state, engineering-state, venture-state)"),
+        files: z
+            .array(z.string())
+            .optional()
+            .describe("Specific files to snapshot (overrides tracked_dirs scan)"),
+    }, async ({ snapshot_id, tracked_dirs, files }) => {
+        const snapshot = takeSnapshot({
+            snapshot_id,
+            tracked_dirs,
+            files,
+        });
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "snapshot_state",
+            category: "info",
+            message: `Semantic snapshot '${snapshot_id}' created`,
+            artifacts: [],
+            metadata: {
+                snapshot_id,
+                file_count: snapshot.file_count,
+                total_size: snapshot.total_size,
+                minhash_params: snapshot.minhash_params,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Semantic Snapshot",
+                        "",
+                        `Snapshot ID: ${snapshot.snapshot_id}`,
+                        `Timestamp: ${snapshot.timestamp}`,
+                        `Files tracked: ${snapshot.file_count}`,
+                        `Total size: ${(snapshot.total_size / 1024).toFixed(1)} KB`,
+                        `MinHash: ${snapshot.minhash_params.num_permutations} perms, k=${snapshot.minhash_params.shingle_size}, seed=${snapshot.minhash_params.seed}`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        "",
+                        "## Files",
+                        ...Object.entries(snapshot.files)
+                            .slice(0, 30)
+                            .map(([path, sig]) => `- ${path} (${sig.size}B, ${sig.sections.length} sections)`),
+                        ...(snapshot.file_count > 30
+                            ? [`... and ${snapshot.file_count - 30} more`]
+                            : []),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // semantic_diff
+    // ──────────────────────────────────────────────────────────────────
+    server.tool("semantic_diff", "Compare two semantic snapshots and produce a delta map showing " +
+        "unchanged/modified/added/deleted files and sections with similarity scores.", {
+        before: z
+            .string()
+            .min(1)
+            .describe("Snapshot ID of the 'before' state"),
+        after: z
+            .string()
+            .min(1)
+            .describe("Snapshot ID of the 'after' state"),
+        include_diffs: z
+            .boolean()
+            .optional()
+            .describe("Include surgical token-level diffs for modified sections (more expensive)"),
+    }, async ({ before, after, include_diffs }) => {
+        let delta;
+        try {
+            delta = computeSemanticDelta({
+                before,
+                after,
+                include_diffs,
+            });
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error computing semantic diff: ${String(err)}`,
+                    },
+                ],
+            };
+        }
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "semantic_diff",
+            category: "info",
+            message: `Semantic diff: ${before} → ${after}`,
+            artifacts: [],
+            metadata: {
+                before,
+                after,
+                summary: delta.summary,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: formatDeltaReport(delta, ledger.path, ledger.entry.id),
+                },
+            ],
+        };
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // drift_report
+    // ──────────────────────────────────────────────────────────────────
+    server.tool("drift_report", "Full drift analysis with budget gates. Takes a post-cycle snapshot, " +
+        "compares against the pre-cycle snapshot, and evaluates drift budget constraints. " +
+        "Use after completing a cycle to verify document state hasn't drifted excessively.", {
+        cycle_id: z
+            .string()
+            .min(1)
+            .describe("Cycle identifier — expects a '{cycle_id}_pre' snapshot to already exist"),
+        tracked_dirs: z
+            .array(z.string())
+            .optional()
+            .describe("Directories to track"),
+        max_growth_pct: z
+            .number()
+            .optional()
+            .describe("Max allowed total size growth percentage (default: 25)"),
+        max_churn_pct: z
+            .number()
+            .optional()
+            .describe("Max allowed file churn percentage (default: 40)"),
+        max_new_files: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max allowed new files per cycle (default: 10)"),
+        max_deleted_files: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max allowed deleted files per cycle (default: 5)"),
+        include_diffs: z
+            .boolean()
+            .optional()
+            .describe("Include surgical diffs in report"),
+    }, async ({ cycle_id, tracked_dirs, max_growth_pct, max_churn_pct, max_new_files, max_deleted_files, include_diffs, }) => {
+        const budget = {
+            max_growth_pct: max_growth_pct ?? 25,
+            max_churn_pct: max_churn_pct ?? 40,
+            max_new_files: max_new_files ?? 10,
+            max_deleted_files: max_deleted_files ?? 5,
+        };
+        let result;
+        try {
+            result = postCycleSnapshot(cycle_id, tracked_dirs, budget, include_diffs);
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error generating drift report: ${String(err)}. Did you run snapshot_state with '${cycle_id}_pre' first?`,
+                    },
+                ],
+            };
+        }
+        const { delta } = result;
+        const passStatus = delta.drift_budget?.passed ? "PASS" : "FAIL";
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "drift_report",
+            category: delta.drift_budget?.passed ? "info" : "regression",
+            message: `Drift report for cycle '${cycle_id}': ${passStatus}`,
+            artifacts: [],
+            metadata: {
+                cycle_id,
+                summary: delta.summary,
+                drift_budget: delta.drift_budget,
+            },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        `# Drift Report — Cycle: ${cycle_id}`,
+                        "",
+                        `## Gate: ${passStatus}`,
+                        "",
+                        ...(delta.drift_budget
+                            ? [
+                                `Growth: ${delta.drift_budget.actual_growth_pct.toFixed(1)}% (limit: ±${budget.max_growth_pct}%)`,
+                                `Churn: ${delta.drift_budget.actual_churn_pct.toFixed(1)}% (limit: ${budget.max_churn_pct}%)`,
+                                `New files: ${delta.drift_budget.new_files} (limit: ${budget.max_new_files})`,
+                                `Deleted files: ${delta.drift_budget.deleted_files} (limit: ${budget.max_deleted_files})`,
+                                ...(delta.drift_budget.violations.length > 0
+                                    ? [
+                                        "",
+                                        "### Violations",
+                                        ...delta.drift_budget.violations.map((v) => `- ⚠ ${v}`),
+                                    ]
+                                    : []),
+                            ]
+                            : []),
+                        "",
+                        formatDeltaReport(delta, ledger.path, ledger.entry.id),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // list_snapshots
+    // ──────────────────────────────────────────────────────────────────
+    server.tool("list_snapshots", "List all cached semantic snapshots in .tmp/cache/semantic/", {}, async () => {
+        const snapshots = listSnapshots();
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: snapshots.length > 0
+                        ? [
+                            "# Cached Snapshots",
+                            "",
+                            ...snapshots.map((s) => `- ${s}`),
+                        ].join("\n")
+                        : "No snapshots cached. Use `snapshot_state` to create one.",
+                },
+            ],
+        };
+    });
+    // ──────────────────────────────────────────────────────────────────
+    // rewrite_targets
+    // ──────────────────────────────────────────────────────────────────
+    server.tool("rewrite_targets", "Extract targeted rewrite locations from a semantic delta. " +
+        "Returns file paths and section headings/line-ranges that changed, " +
+        "for use with ast-grep node targeting (code) or heading search (markdown).", {
+        before: z.string().min(1).describe("Before snapshot ID"),
+        after: z.string().min(1).describe("After snapshot ID"),
+    }, async ({ before, after }) => {
+        let delta;
+        try {
+            delta = computeSemanticDelta({ before, after });
+        }
+        catch (err) {
+            return {
+                content: [
+                    { type: "text", text: `Error: ${String(err)}` },
+                ],
+            };
+        }
+        const targets = extractRewriteTargets(delta);
+        const ledger = await appendRunLedgerEntrySafe({
+            tool: "rewrite_targets",
+            category: "info",
+            message: `Extracted ${targets.length} rewrite targets from ${before} → ${after}`,
+            artifacts: [],
+            metadata: { target_count: targets.length },
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        "# Rewrite Targets",
+                        "",
+                        `Total targets: ${targets.length}`,
+                        `Run ledger: ${ledger.path} (${ledger.entry.id})`,
+                        "",
+                        ...targets.map((t) => {
+                            if (t.type === "full") {
+                                return `- **${t.file}** (full file, sim: ${(t.similarity * 100).toFixed(0)}%)`;
+                            }
+                            return `- ${t.file} → \`${t.heading}\` (section, sim: ${(t.similarity * 100).toFixed(0)}%)`;
+                        }),
+                    ].join("\n"),
+                },
+            ],
+        };
+    });
+}
+// ────────────────────────────────────────────────────────────────────
+// Report formatting
+// ────────────────────────────────────────────────────────────────────
+function formatDeltaReport(delta, ledgerPath, ledgerId) {
+    const lines = [
+        `## Summary (${delta.before_snapshot} → ${delta.after_snapshot})`,
+        "",
+        `| Metric | Count |`,
+        `|--------|-------|`,
+        `| Unchanged | ${delta.summary.unchanged_files} |`,
+        `| Modified | ${delta.summary.modified_files} |`,
+        `| Added | ${delta.summary.added_files} |`,
+        `| Deleted | ${delta.summary.deleted_files} |`,
+        `| Section changes | ${delta.summary.total_section_changes} |`,
+        "",
+    ];
+    // Show modified files with section detail
+    const modifiedFiles = Object.entries(delta.files).filter(([, d]) => d.status === "modified");
+    if (modifiedFiles.length > 0) {
+        lines.push("## Modified Files", "");
+        for (const [path, fileDelta] of modifiedFiles.slice(0, 20)) {
+            lines.push(`### ${path}`, `Similarity: ${(fileDelta.file_similarity * 100).toFixed(0)}% | ` +
+                `Size: ${fileDelta.size_before}B → ${fileDelta.size_after}B (${fileDelta.growth_pct > 0 ? "+" : ""}${fileDelta.growth_pct.toFixed(1)}%)`);
+            if (fileDelta.section_changes.length > 0) {
+                for (const sec of fileDelta.section_changes) {
+                    const icon = sec.status === "unchanged"
+                        ? "✓"
+                        : sec.status === "modified"
+                            ? "~"
+                            : sec.status === "added"
+                                ? "+"
+                                : "-";
+                    lines.push(`  ${icon} ${sec.heading} (${sec.status}, ${(sec.similarity * 100).toFixed(0)}%)`);
+                    if (sec.diff_summary) {
+                        lines.push("  ```", ...sec.diff_summary.split("\n").map((l) => `  ${l}`), "  ```");
+                    }
+                }
+            }
+            lines.push("");
+        }
+    }
+    // Show added files
+    const addedFiles = Object.entries(delta.files).filter(([, d]) => d.status === "added");
+    if (addedFiles.length > 0) {
+        lines.push("## Added Files", "", ...addedFiles.slice(0, 20).map(([path, d]) => `- ${path} (${d.size_after}B)`), "");
+    }
+    // Show deleted files
+    const deletedFiles = Object.entries(delta.files).filter(([, d]) => d.status === "deleted");
+    if (deletedFiles.length > 0) {
+        lines.push("## Deleted Files", "", ...deletedFiles.slice(0, 20).map(([path, d]) => `- ${path} (was ${d.size_before}B)`), "");
+    }
+    lines.push(`Run ledger: ${ledgerPath} (${ledgerId})`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=tools-drift.js.map

package/dist/tools-files.d.ts

@@ -0,0 +1,6 @@
+/**
+ * File operation tool registrations + new safe-edit and diff tools.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerFileTools(server: McpServer): void;
+//# sourceMappingURL=tools-files.d.ts.map