@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/discovery-runtime-wrappers.js

@@ -0,0 +1,615 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isIP } from "node:net";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { dirname } from "node:path";
+import { isReadError, normalizePathForValidation, resolveWorkspaceArtifactPath, resolveWorkspaceRoot, safeRead, safeWriteAsync, wsPath, } from "./helpers.js";
+import { appendRunLedgerEntrySafe } from "./run-ledger.js";
+import { runShellCommand } from "./runtime-command.js";
+import { executeRuntimeTool, loadRuntimeToolRegistry, persistRuntimeToolInvocationArtifacts, } from "./runtime-tool-specs.js";
+import { refreshAstgrepIndex } from "./astgrep-index.js";
+const BLOCKED_HOSTNAMES = new Set(["localhost", "localhost.localdomain"]);
+const SAFE_EXTERNAL_ENV_KEYS = new Set(["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "USER", "LANG", "LC_ALL"]);
+const DEFAULT_WEB_RESEARCH_TOOL = "web_research_packet";
+const DEFAULT_CODEMUNCH_TOOL = "codemunch_snapshot";
+const DEFAULT_CODEMUNCH_COMMAND = "npx -y codemunch";
+const WEB_RESEARCH_MAX_CITATIONS = 12;
+const WEB_RESEARCH_MAX_SEARCH_RESULTS = 20;
+const WEB_RESEARCH_MAX_FETCH_DOCS = 10;
+const WEB_RESEARCH_MAX_SNIPPET_CHARS = 280;
+const WEB_RESEARCH_MAX_FETCH_CHARS = 6000;
+const defaultDeps = {
+    executeRuntimeTool,
+    loadRuntimeToolRegistry,
+    persistRuntimeToolInvocationArtifacts,
+    runShellCommand,
+    refreshAstgrepIndex,
+    now: () => new Date(),
+    randomId: () => randomUUID(),
+};
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function pickString(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "string" && value.trim().length > 0) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+function pickNumber(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === "number" && Number.isFinite(value))
+            return value;
+    }
+    return undefined;
+}
+function truncate(value, maxChars) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    return `${trimmed.slice(0, Math.max(0, maxChars - 1)).trimEnd()}…`;
+}
+function slugify(value, fallback = "artifact") {
+    const slug = value
+        .toLowerCase()
+        .replace(/https?:\/\//g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    return slug || fallback;
+}
+function artifactStamp(now, id, seed) {
+    return `${now.toISOString().replace(/[:.]/g, "-")}-${slugify(seed)}-${id.slice(0, 8)}`;
+}
+function runtimeToolConfigured(name, deps) {
+    const registry = deps.loadRuntimeToolRegistry();
+    return Boolean(registry.ok && registry.registry?.tools.some((tool) => tool.name === name));
+}
+function extractArrays(output, keys) {
+    const rows = [];
+    for (const key of keys) {
+        const value = output[key];
+        if (!Array.isArray(value))
+            continue;
+        for (const entry of value) {
+            if (isRecord(entry))
+                rows.push(entry);
+        }
+    }
+    return rows;
+}
+function normalizeCitations(output) {
+    const rows = extractArrays(output, ["citations", "results", "search_results", "sources"]);
+    const seen = new Set();
+    const citations = [];
+    for (const row of rows) {
+        const url = pickString(row, ["url", "link", "source_url"]);
+        if (!url || seen.has(url))
+            continue;
+        seen.add(url);
+        citations.push({
+            title: pickString(row, ["title", "name", "label"]) ?? url,
+            url,
+            snippet: truncate(pickString(row, ["snippet", "summary", "excerpt", "description"]), WEB_RESEARCH_MAX_SNIPPET_CHARS),
+        });
+        if (citations.length >= WEB_RESEARCH_MAX_CITATIONS)
+            break;
+    }
+    return citations;
+}
+function normalizeFetchDocs(output) {
+    const rows = extractArrays(output, ["fetches", "fetched", "pages", "documents", "fetched_pages"]);
+    return rows.slice(0, WEB_RESEARCH_MAX_FETCH_DOCS).map((row) => ({
+        url: pickString(row, ["url", "source_url", "link"]),
+        title: pickString(row, ["title", "name"]),
+        content: truncate(pickString(row, ["content", "text", "excerpt", "markdown", "body", "html"]), WEB_RESEARCH_MAX_FETCH_CHARS),
+    }));
+}
+function readWorkspaceContent(path) {
+    const raw = safeRead(path);
+    if (isReadError(raw)) {
+        throw new Error(raw);
+    }
+    return raw;
+}
+function resolveOutputCxml(output) {
+    const inline = pickString(output, ["cxml", "snapshot_cxml"]);
+    if (inline)
+        return { content: inline };
+    const candidatePath = pickString(output, ["cxml_path", "snapshot_path", "output_path", "path"]);
+    if (!candidatePath) {
+        throw new Error("Codemunch wrapper expected 'cxml' or 'cxml_path' in the tool output.");
+    }
+    const resolved = resolveWorkspaceArtifactPath(candidatePath, "read");
+    if (!existsSync(resolved)) {
+        throw new Error(`Codemunch output path not found: ${candidatePath}`);
+    }
+    return { content: readFileSync(resolved, "utf-8"), source_path: resolved };
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+function isPrivateIp(hostname) {
+    const kind = isIP(hostname);
+    if (kind === 0)
+        return false;
+    if (kind === 6) {
+        const lower = hostname.toLowerCase();
+        return lower === "::1" || lower.startsWith("fc") || lower.startsWith("fd") || lower.startsWith("fe80:");
+    }
+    const parts = hostname.split(".").map((part) => Number(part));
+    const [a, b] = parts;
+    return (a === 10 ||
+        a === 127 ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        a === 0);
+}
+function assertPublicHttpUrl(raw, label) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new Error(`${label} must be a valid URL.`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`${label} must use http or https.`);
+    }
+    const hostname = parsed.hostname.toLowerCase();
+    if (BLOCKED_HOSTNAMES.has(hostname) || isPrivateIp(hostname)) {
+        throw new Error(`${label} targets a private or local address.`);
+    }
+}
+function assertGitHubUrl(raw) {
+    assertPublicHttpUrl(raw, "repo_url");
+    const parsed = new URL(raw);
+    if (parsed.hostname.toLowerCase() !== "github.com") {
+        throw new Error("repo_url must be a GitHub URL for codemunch snapshots.");
+    }
+}
+function safeExternalEnv(extra = {}) {
+    const env = {};
+    for (const key of SAFE_EXTERNAL_ENV_KEYS) {
+        const value = process.env[key];
+        if (typeof value === "string")
+            env[key] = value;
+    }
+    for (const [key, value] of Object.entries(extra)) {
+        env[key] = value;
+    }
+    return env;
+}
+async function appendWrapperLedgerEntry(tool, message, artifacts, metadata) {
+    await appendRunLedgerEntrySafe({
+        tool,
+        category: "info",
+        message,
+        artifacts: artifacts.filter((artifact) => Boolean(artifact)).map((artifact) => normalizePathForValidation(artifact)),
+        metadata,
+    }).catch(() => undefined);
+}
+export async function createWebResearchPacket(input, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    try {
+        for (const url of input.fetch_urls ?? []) {
+            assertPublicHttpUrl(url, "fetch_urls");
+        }
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: "Web research request failed SSRF guard validation.",
+            tool_name: DEFAULT_WEB_RESEARCH_TOOL,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    if (!runtimeToolConfigured(DEFAULT_WEB_RESEARCH_TOOL, resolved)) {
+        return {
+            ok: false,
+            summary: `Runtime tool '${DEFAULT_WEB_RESEARCH_TOOL}' is not configured.`,
+            tool_name: DEFAULT_WEB_RESEARCH_TOOL,
+            error: `Unknown runtime tool spec: ${DEFAULT_WEB_RESEARCH_TOOL}`,
+        };
+    }
+    const runtimeResult = await resolved.executeRuntimeTool(DEFAULT_WEB_RESEARCH_TOOL, {
+        query: input.query,
+        sources_required: input.sources_required,
+        fetch_urls: input.fetch_urls,
+    }, {
+        session_id: input.session_id,
+        turn_number: input.turn_number,
+        workspace_path: input.workspace_path,
+    });
+    if (!runtimeResult.ok || !isRecord(runtimeResult.output)) {
+        return {
+            ok: false,
+            summary: runtimeResult.summary,
+            tool_name: DEFAULT_WEB_RESEARCH_TOOL,
+            request_path: runtimeResult.request_path,
+            response_path: runtimeResult.response_path,
+            error: runtimeResult.error ? JSON.stringify(runtimeResult.error) : "Invalid runtime tool output.",
+        };
+    }
+    const now = resolved.now();
+    const id = artifactStamp(now, resolved.randomId(), input.query);
+    const researchDir = `agent-state/research/${id}`;
+    const citations = normalizeCitations(runtimeResult.output);
+    const searchResultsPath = await safeWriteAsync(`${researchDir}/search-results.json`, JSON.stringify({
+        query: input.query,
+        generated_at: now.toISOString(),
+        sources_required: input.sources_required,
+        results: citations.slice(0, WEB_RESEARCH_MAX_SEARCH_RESULTS),
+    }, null, 2));
+    const fetchedPaths = [];
+    const fetchedDocs = normalizeFetchDocs(runtimeResult.output);
+    for (const [index, doc] of fetchedDocs.entries()) {
+        if (!doc.content)
+            continue;
+        const fetchPath = await safeWriteAsync(`${researchDir}/fetch-${String(index + 1).padStart(2, "0")}-${slugify(doc.title ?? doc.url ?? "page")}.txt`, doc.content);
+        fetchedPaths.push(fetchPath);
+        const match = doc.url ? citations.find((citation) => citation.url === doc.url) : undefined;
+        if (match)
+            match.fetched_path = fetchPath;
+    }
+    const packetPath = await safeWriteAsync(`${researchDir}/packet.json`, JSON.stringify({
+        schema: "ace-web-research-packet@1",
+        generated_at: now.toISOString(),
+        query: input.query,
+        sources_required: input.sources_required,
+        fetch_urls: input.fetch_urls ?? [],
+        summary: pickString(runtimeResult.output, ["summary", "answer", "overview"]) ?? runtimeResult.summary,
+        citations,
+        fetched_documents: fetchedDocs.map((doc, index) => ({
+            ...doc,
+            artifact_path: fetchedPaths[index],
+        })),
+        runtime_tool: {
+            name: DEFAULT_WEB_RESEARCH_TOOL,
+            summary: runtimeResult.summary,
+            request_path: runtimeResult.request_path,
+            response_path: runtimeResult.response_path,
+        },
+    }, null, 2));
+    const summary = pickString(runtimeResult.output, ["summary", "answer", "overview"]) ??
+        `Stored ${citations.length} citations and ${fetchedPaths.length} fetched pages for '${input.query}'.`;
+    await appendWrapperLedgerEntry("web_research_packet", summary, [packetPath, searchResultsPath, ...fetchedPaths, runtimeResult.request_path, runtimeResult.response_path], {
+        query: input.query,
+        citations: citations.length,
+        fetched_documents: fetchedPaths.length,
+        runtime_tool: DEFAULT_WEB_RESEARCH_TOOL,
+    });
+    return {
+        ok: true,
+        summary,
+        tool_name: DEFAULT_WEB_RESEARCH_TOOL,
+        packet_path: packetPath,
+        search_results_path: searchResultsPath,
+        fetched_paths: fetchedPaths,
+        request_path: runtimeResult.request_path,
+        response_path: runtimeResult.response_path,
+        citations: citations.slice(0, 5),
+    };
+}
+export async function createCodemunchSnapshot(input, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    try {
+        assertGitHubUrl(input.repo_url);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            summary: "Codemunch snapshot request failed repository guard validation.",
+            mode: "runtime_tool",
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const now = resolved.now();
+    const id = artifactStamp(now, resolved.randomId(), input.repo_url);
+    const researchDir = `agent-state/research/codemunch/${id}`;
+    const snapshotPath = resolveWorkspaceArtifactPath(`${researchDir}/snapshot.cxml`, "write");
+    mkdirSync(dirname(snapshotPath), { recursive: true });
+    let mode = "runtime_tool";
+    let requestPath;
+    let responsePath;
+    let runtimeSummary = "";
+    let sourceContent = "";
+    let sourcePath;
+    let provenanceSource = {};
+    if (runtimeToolConfigured(DEFAULT_CODEMUNCH_TOOL, resolved)) {
+        const runtimeResult = await resolved.executeRuntimeTool(DEFAULT_CODEMUNCH_TOOL, {
+            repo_url: input.repo_url,
+            branch: input.branch,
+            max_bytes: input.max_bytes,
+        }, {
+            session_id: input.session_id,
+            turn_number: input.turn_number,
+            workspace_path: input.workspace_path,
+        });
+        requestPath = runtimeResult.request_path;
+        responsePath = runtimeResult.response_path;
+        runtimeSummary = runtimeResult.summary;
+        if (!runtimeResult.ok || !isRecord(runtimeResult.output)) {
+            return {
+                ok: false,
+                summary: runtimeResult.summary,
+                mode,
+                request_path: requestPath,
+                response_path: responsePath,
+                error: runtimeResult.error ? JSON.stringify(runtimeResult.error) : "Invalid runtime tool output.",
+            };
+        }
+        const resolvedOutput = resolveOutputCxml(runtimeResult.output);
+        sourceContent = resolvedOutput.content;
+        sourcePath = resolvedOutput.source_path;
+        provenanceSource = {
+            tool_name: DEFAULT_CODEMUNCH_TOOL,
+            cache_path: pickString(runtimeResult.output, ["cache_path", "cache_dir"]),
+            generated_at: pickString(runtimeResult.output, ["generated_at", "created_at"]),
+            source_path: sourcePath,
+        };
+    }
+    else {
+        mode = "external_cli";
+        const commandBase = process.env.ACE_CODEMUNCH_COMMAND?.trim() || DEFAULT_CODEMUNCH_COMMAND;
+        const command = [
+            commandBase,
+            shellQuote(input.repo_url),
+            "--out",
+            shellQuote(snapshotPath),
+            typeof input.max_bytes === "number" ? `--max-bytes ${Math.trunc(input.max_bytes)}` : "",
+            input.branch ? `--branch ${shellQuote(input.branch)}` : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+        const requestPayload = JSON.stringify({
+            tool: { name: DEFAULT_CODEMUNCH_TOOL, mode: "external_cli", command_base: commandBase },
+            input: {
+                repo_url: input.repo_url,
+                branch: input.branch,
+                max_bytes: input.max_bytes,
+            },
+            workspace_path: input.workspace_path ?? resolveWorkspaceRoot(),
+            timestamp: now.toISOString(),
+        }, null, 2);
+        const shellResult = await resolved.runShellCommand(command, {
+            cwd: resolveWorkspaceRoot(),
+            env: safeExternalEnv({
+                ACE_CODEMUNCH_REPO_URL: input.repo_url,
+                ACE_CODEMUNCH_BRANCH: input.branch ?? "",
+                ACE_CODEMUNCH_MAX_BYTES: typeof input.max_bytes === "number" ? String(Math.trunc(input.max_bytes)) : "",
+                ACE_CODEMUNCH_OUT_PATH: snapshotPath,
+            }),
+            timeout_ms: 120_000,
+        });
+        const responsePayload = JSON.stringify({
+            ok: shellResult.exit_code === 0 && existsSync(snapshotPath),
+            summary: shellResult.exit_code === 0 && existsSync(snapshotPath)
+                ? `Codemunch snapshot generated for ${input.repo_url}`
+                : `Codemunch CLI failed for ${input.repo_url}`,
+            output: shellResult.exit_code === 0 && existsSync(snapshotPath)
+                ? {
+                    cxml_path: snapshotPath,
+                    repo_url: input.repo_url,
+                    branch: input.branch,
+                    max_bytes: input.max_bytes,
+                    command,
+                }
+                : undefined,
+            error: shellResult.exit_code === 0 && existsSync(snapshotPath)
+                ? undefined
+                : {
+                    exit_code: shellResult.exit_code,
+                    stdout: shellResult.stdout,
+                    stderr: shellResult.stderr,
+                },
+        }, null, 2);
+        const persisted = await resolved.persistRuntimeToolInvocationArtifacts(resolved.randomId(), requestPayload, responsePayload);
+        requestPath = persisted.requestPath;
+        responsePath = persisted.responsePath;
+        runtimeSummary =
+            shellResult.exit_code === 0 && existsSync(snapshotPath)
+                ? `Codemunch snapshot generated for ${input.repo_url}`
+                : `Codemunch CLI failed for ${input.repo_url}`;
+        if (shellResult.exit_code !== 0 || !existsSync(snapshotPath)) {
+            return {
+                ok: false,
+                summary: runtimeSummary,
+                mode,
+                request_path: requestPath,
+                response_path: responsePath,
+                error: shellResult.stderr || shellResult.stdout || "Codemunch CLI did not produce snapshot output.",
+            };
+        }
+        sourceContent = readFileSync(snapshotPath, "utf-8");
+        sourcePath = snapshotPath;
+        provenanceSource = {
+            command,
+            exit_code: shellResult.exit_code,
+            duration_ms: shellResult.duration_ms,
+            source_path: snapshotPath,
+        };
+    }
+    const persistedSnapshotPath = await safeWriteAsync(`${researchDir}/snapshot.cxml`, sourceContent);
+    const checksum = sha256(sourceContent);
+    const provenancePath = await safeWriteAsync(`${researchDir}/provenance.json`, JSON.stringify({
+        schema: "ace-codemunch-snapshot@1",
+        generated_at: now.toISOString(),
+        repo_url: input.repo_url,
+        branch: input.branch ?? null,
+        max_bytes: typeof input.max_bytes === "number" ? Math.trunc(input.max_bytes) : null,
+        snapshot_path: persistedSnapshotPath,
+        checksum,
+        request_path: requestPath,
+        response_path: responsePath,
+        mode,
+        source: provenanceSource,
+    }, null, 2));
+    await appendWrapperLedgerEntry("codemunch_snapshot", runtimeSummary, [persistedSnapshotPath, provenancePath, requestPath, responsePath], {
+        repo_url: input.repo_url,
+        branch: input.branch ?? null,
+        checksum,
+        mode,
+        source_path: sourcePath ? normalizePathForValidation(sourcePath) : null,
+    });
+    return {
+        ok: true,
+        summary: runtimeSummary,
+        mode,
+        snapshot_path: persistedSnapshotPath,
+        checksum,
+        provenance_path: provenancePath,
+        request_path: requestPath,
+        response_path: responsePath,
+    };
+}
+export async function createMcpIngestionProbe(input, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    const callId = resolved.randomId();
+    const now = resolved.now();
+    const requestPayload = JSON.stringify({
+        schema: "ace-mcp-ingestion-probe@1",
+        generated_at: now.toISOString(),
+        name: input.name,
+        transport: input.transport,
+        command: input.transport === "stdio" ? input.command : undefined,
+        args: input.transport === "stdio" ? input.args ?? [] : undefined,
+        url: input.transport === "http" ? input.url : undefined,
+        env_keys: Object.keys(input.env ?? {}).sort(),
+    }, null, 2);
+    let error;
+    let reasonCode;
+    if (!input.name.trim()) {
+        error = "MCP server name is required.";
+        reasonCode = "invalid_name";
+    }
+    else if (input.transport === "stdio" && !input.command?.trim()) {
+        error = "stdio MCP ingestion requires command.";
+        reasonCode = "command_missing";
+    }
+    else if (input.transport === "http") {
+        try {
+            if (!input.url)
+                throw new Error("http MCP ingestion requires url.");
+            assertPublicHttpUrl(input.url, "mcp_server.url");
+        }
+        catch (caught) {
+            error = caught instanceof Error ? caught.message : String(caught);
+            reasonCode = "ssrf_blocked";
+        }
+    }
+    if (!error) {
+        const forbiddenEnv = Object.keys(input.env ?? {}).filter((key) => /(SECRET|TOKEN|KEY|PASSWORD|PASS|CREDENTIAL|AUTH|COOKIE|SESSION)/i.test(key));
+        if (forbiddenEnv.length > 0) {
+            error = `MCP server env contains secret-like keys: ${forbiddenEnv.join(", ")}`;
+            reasonCode = "secret_env_blocked";
+        }
+    }
+    const tools = (input.declared_tools ?? []).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.input_schema,
+    })).filter((tool) => tool.name?.trim());
+    const responsePayload = JSON.stringify({
+        ok: !error,
+        summary: error
+            ? `MCP ingestion probe blocked for ${input.name}: ${error}`
+            : `MCP ingestion probe configured ${tools.length} declared tool(s) for ${input.name}.`,
+        output: !error
+            ? {
+                health: "configured",
+                tools,
+                transport: input.transport,
+            }
+            : undefined,
+        error: error ? { reason_code: reasonCode, message: error } : undefined,
+    }, null, 2);
+    const persisted = await resolved.persistRuntimeToolInvocationArtifacts(callId, requestPayload, responsePayload);
+    return {
+        ok: !error,
+        summary: error
+            ? `MCP ingestion probe blocked for ${input.name}: ${error}`
+            : `MCP ingestion probe configured ${tools.length} declared tool(s) for ${input.name}.`,
+        server_name: input.name,
+        transport: input.transport,
+        health: error ? "blocked" : "configured",
+        tools,
+        request_path: persisted.requestPath,
+        response_path: persisted.responsePath,
+        error,
+        reason_code: reasonCode,
+    };
+}
+export async function createCodemunchIndex(input, deps = {}) {
+    const resolved = { ...defaultDeps, ...deps };
+    const now = resolved.now();
+    const id = artifactStamp(now, resolved.randomId(), input.cxml_path);
+    const researchDir = `agent-state/research/codemunch/${id}`;
+    const sourceContent = readWorkspaceContent(input.cxml_path);
+    const checksum = sha256(sourceContent);
+    const repPath = wsPath("rep_astgrep.cxml");
+    const priorRep = existsSync(repPath) ? readFileSync(repPath, "utf-8") : undefined;
+    mkdirSync(resolveWorkspaceArtifactPath(researchDir, "write"), { recursive: true });
+    try {
+        const routedRepPath = await safeWriteAsync("rep_astgrep.cxml", sourceContent);
+        const discoveryResult = await resolved.refreshAstgrepIndex({
+            scope: researchDir,
+            append_evidence: input.append_evidence ?? false,
+            emit_event: input.emit_event ?? false,
+            include_rep_corpus: true,
+        });
+        const indexJsonContent = readWorkspaceContent(discoveryResult.output_json_path);
+        const indexMdContent = readWorkspaceContent(discoveryResult.output_md_path);
+        const summaryJsonPath = await safeWriteAsync(`${researchDir}/structural-summary.json`, indexJsonContent);
+        const summaryMdPath = await safeWriteAsync(`${researchDir}/structural-summary.md`, indexMdContent);
+        const parsedSummary = JSON.parse(indexJsonContent);
+        const routingHints = Array.isArray(parsedSummary.routing_hints)
+            ? parsedSummary.routing_hints.filter((value) => typeof value === "string").slice(0, 5)
+            : [];
+        const provenancePath = await safeWriteAsync(`${researchDir}/index-provenance.json`, JSON.stringify({
+            schema: "ace-codemunch-index@1",
+            generated_at: now.toISOString(),
+            source_cxml_path: input.cxml_path,
+            checksum,
+            routed_rep_corpus_path: routedRepPath,
+            discovery_output_json_path: discoveryResult.output_json_path,
+            discovery_output_md_path: discoveryResult.output_md_path,
+            copied_summary_json_path: summaryJsonPath,
+            copied_summary_md_path: summaryMdPath,
+        }, null, 2));
+        await appendWrapperLedgerEntry("codemunch_index", `Indexed codemunch snapshot ${normalizePathForValidation(input.cxml_path)}`, [summaryJsonPath, summaryMdPath, provenancePath, routedRepPath], {
+            checksum,
+            rep_sources: discoveryResult.stats.rep_sources,
+            hotspot_files: discoveryResult.stats.hotspot_files,
+        });
+        return {
+            ok: true,
+            summary: `Indexed codemunch snapshot with ${discoveryResult.stats.rep_sources} rep sources.`,
+            source_cxml_path: input.cxml_path,
+            checksum,
+            rep_corpus_path: routedRepPath,
+            structural_summary_json_path: summaryJsonPath,
+            structural_summary_md_path: summaryMdPath,
+            provenance_path: provenancePath,
+            routing_hints: routingHints,
+        };
+    }
+    finally {
+        if (typeof priorRep === "string") {
+            await safeWriteAsync("rep_astgrep.cxml", priorRep);
+        }
+        else if (existsSync(repPath)) {
+            rmSync(repPath, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=discovery-runtime-wrappers.js.map

package/dist/handoff-registry.js

@@ -4,7 +4,7 @@ import { openStore } from "./store/ace-packed-store.js";
 import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { HandoffRepository } from "./store/repositories/handoff-repository.js";
 import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
-import { withStoreWriteQueue } from "./store/write-queue.js";
+import { withStoreWriteCoordinator } from "./store/write-coordinator.js";
 import { waitForPendingStatusEventMirrors } from "./status-events.js";
 import { waitForTodoStoreMirror } from "./todo-state.js";
 const HANDOFF_REGISTRY_REL = "agent-state/handoff-registry.json";
@@ -299,7 +299,7 @@ export async function registerHandoffSafe(input) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => registerHandoff(input));
     }
     return withFileLock(HANDOFF_REGISTRY_REL, async () => {
-        return withStoreWriteQueue(storePath, async () => {
+        return withStoreWriteCoordinator(storePath, async () => {
             const store = await openStore(storePath);
             try {
                 const repo = new HandoffRepository(store);
@@ -346,7 +346,7 @@ export async function registerHandoffSafe(input) {
             finally {
                 await store.close();
             }
-        });
+        }, { operation_label: "registerHandoffSafe" });
     });
 }
 /**
@@ -361,7 +361,7 @@ export async function acknowledgeHandoffSafe(input) {
         return withFileLock(HANDOFF_REGISTRY_REL, () => acknowledgeHandoff(input));
     }
     return withFileLock(HANDOFF_REGISTRY_REL, async () => {
-        return withStoreWriteQueue(storePath, async () => {
+        return withStoreWriteCoordinator(storePath, async () => {
             const store = await openStore(storePath);
             try {
                 const repo = new HandoffRepository(store);
@@ -420,7 +420,7 @@ export async function acknowledgeHandoffSafe(input) {
             finally {
                 await store.close();
             }
-        });
+        }, { operation_label: "acknowledgeHandoffSafe" });
     });
 }
 //# sourceMappingURL=handoff-registry.js.map

package/dist/helpers/artifacts.d.ts

@@ -0,0 +1,19 @@
+import { type AgentRole, type KernelKey, type TaskKey } from "./constants.js";
+export interface SkillReference {
+    name: string;
+    path: string;
+    source: "workspace" | "package-defaults" | "store";
+}
+export declare function getAgentInstructionPath(role: AgentRole): string | undefined;
+export declare function getAgentManifestPath(role: AgentRole): string | undefined;
+export declare function readAgentInstructions(role: AgentRole): string;
+export declare function readAgentManifest(role: AgentRole): string;
+export declare function getTaskArtifactPath(key: TaskKey): string | undefined;
+export declare function readTaskArtifact(key: TaskKey): string;
+export declare function getKernelArtifactPath(key: KernelKey): string | undefined;
+export declare function readKernelArtifact(key: KernelKey): string;
+export declare function resolveWritableTaskPath(key: TaskKey): string;
+export declare function listAvailableSkills(): SkillReference[];
+export declare function getSkillPath(name: string): string | undefined;
+export declare function readSkillInstructions(name: string): string;
+//# sourceMappingURL=artifacts.d.ts.map