@voybio/ace-swarm 0.2.5 → 2.4.1

package/dist/tools-files.js

@@ -1,18 +1,466 @@
 /**
  * File operation tool registrations + new safe-edit and diff tools.
  */
-import { readdirSync } from "node:fs";
-import { isAbsolute, relative } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } 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 { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveWorkspaceWritePath, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { isInside, looksLikeSwarmHandoffPath, normalizeRelPath } 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";
+import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
+import { detectAstgrepCommand, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
+import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
+import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+function reasonCodeFromError(error) {
+    return typeof error === "object" && error !== null && "reason_code" in error
+        ? String(error.reason_code)
+        : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function appendWriteWorkspaceRejection(input) {
+    await appendRunLedgerEntrySafe({
+        tool: "write_workspace_file",
+        category: "regression",
+        message: input.message,
+        artifacts: [],
+        metadata: {
+            reason_code: input.reason_code,
+            path: input.path,
+            workspace_path: input.workspace_path,
+        },
+    }).catch(() => undefined);
+    await appendStatusEventSafe({
+        source_module: "capability-safety",
+        event_type: "WORKSPACE_WRITE_REJECTED",
+        status: "blocked",
+        summary: input.message,
+        objective_id: "workspace-write-safety",
+        payload: {
+            reason_code: input.reason_code,
+            path: input.path,
+            workspace_path: input.workspace_path,
+        },
+    }).catch(() => undefined);
+}
+export function planAstgrepRewriteTargets(files) {
+    const affected = [...new Set(files.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+    if (affected.length > 1) {
+        return {
+            ok: false,
+            affected_files: affected,
+            error: `astgrep_rewrite refuses multi-file rewrites (${affected.length} files): ${affected.slice(0, 5).join(", ")}`,
+        };
+    }
+    return {
+        ok: true,
+        affected_files: affected,
+        target_file: affected[0],
+    };
+}
+async function appendAstgrepRewriteTransition(sessionId, to, reason, evidenceRefs) {
+    if (!sessionId)
+        return;
+    await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => {
+        await repo.appendTransitionRecord({
+            subject_kind: "plan_step",
+            subject_id: `${sessionId}/astgrep_rewrite`,
+            from: "staged",
+            to,
+            reason,
+            reason_code: to === "promoted" ? "surgical_rewrite" : "surgical_rewrite_failed",
+            evidence_refs: evidenceRefs,
+        });
+    }).catch(() => undefined);
+}
+function astgrepFileToWorkspaceRel(file) {
+    const abs = isAbsolute(file) ? file : resolve(WORKSPACE_ROOT, file);
+    if (!isInside(WORKSPACE_ROOT, abs))
+        return undefined;
+    return normalizeRelPath(relative(WORKSPACE_ROOT, abs));
+}
+const STRUCTURAL_EDIT_ARTIFACTS_REL = "agent-state/structural-edits";
+function contentSha256(content) {
+    return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+function structuralEditArtifactRelPath(prefix, id) {
+    return `${STRUCTURAL_EDIT_ARTIFACTS_REL}/${prefix}-${id}.json`;
+}
+async function writeJsonArtifact(artifact) {
+    await safeWriteAsync(artifact.artifact_path, JSON.stringify(artifact, null, 2));
+    return artifact;
+}
+function readJsonArtifact(relPath) {
+    const raw = safeRead(relPath);
+    if (raw.startsWith("[FILE NOT FOUND]") || raw.startsWith("[ACCESS DENIED]"))
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function jsonResponse(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+async function storeLocateArtifact(input, result) {
+    const locatorId = randomUUID();
+    return writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_locate",
+        locator_id: locatorId,
+        created_at: new Date().toISOString(),
+        artifact_path: structuralEditArtifactRelPath("locate", locatorId),
+        input,
+        astgrep_command: result.astgrep_command,
+        total_matches: result.total_matches,
+        matches: result.matches,
+    });
+}
+function listStructuralEditArtifacts(prefix) {
+    const dir = wsPath(STRUCTURAL_EDIT_ARTIFACTS_REL);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith(".json"))
+        .sort((a, b) => b.localeCompare(a))
+        .map((name) => normalizeRelPath(relative(WORKSPACE_ROOT, resolve(dir, name))));
+}
+function findStoredMatch(matchId) {
+    for (const relPath of listStructuralEditArtifacts("locate")) {
+        const artifact = readJsonArtifact(relPath);
+        if (!artifact)
+            continue;
+        const match = artifact.matches.find((candidate) => candidate.match_id === matchId);
+        if (match)
+            return { artifact, match };
+    }
+    return undefined;
+}
+function loadStructuralEditPlan(planId) {
+    return readJsonArtifact(structuralEditArtifactRelPath("plan", planId));
+}
+function planScopeFromMatches(matches) {
+    return [...new Set(matches.map((match) => match.file))].sort((a, b) => a.localeCompare(b));
+}
+function rewriteCaptureRefs(rewriteTemplate) {
+    const refs = new Set();
+    const regex = /\$([A-Z][A-Z0-9_]*)/g;
+    let match;
+    while ((match = regex.exec(rewriteTemplate)) !== null) {
+        refs.add(match[1]);
+    }
+    return [...refs].sort((a, b) => a.localeCompare(b));
+}
+function missingRewriteCaptures(rewriteTemplate, captures) {
+    const available = new Set(Object.keys(captures ?? {}));
+    return rewriteCaptureRefs(rewriteTemplate).filter((ref) => !available.has(ref));
+}
+async function compileStructuralEditPlan(input) {
+    const scopedMatches = input.selectedMatch
+        ? input.locateArtifact.matches.filter((match) => match.file === input.selectedMatch?.file)
+        : input.locateArtifact.matches;
+    const targetFile = input.selectedMatch?.file ?? scopedMatches[0]?.file ?? "";
+    const selectedMatch = input.selectedMatch ?? scopedMatches.find((match) => match.file === targetFile) ?? scopedMatches[0];
+    const rewriteTemplate = input.rewriteTemplate ?? input.desiredChange;
+    const missingCaptures = missingRewriteCaptures(rewriteTemplate, selectedMatch?.captures);
+    if (missingCaptures.length > 0) {
+        throw new Error(`bad_capture: rewrite references missing capture(s): ${missingCaptures.join(", ")}`);
+    }
+    const planId = randomUUID();
+    return writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_edit_plan",
+        plan_id: planId,
+        created_at: new Date().toISOString(),
+        artifact_path: structuralEditArtifactRelPath("plan", planId),
+        locator_artifact_path: input.locateArtifact.artifact_path,
+        locator: input.locator,
+        target: {
+            file: targetFile,
+            file_hash: selectedMatch?.file_hash ?? "sha256:none",
+            selected_match_id: selectedMatch?.match_id,
+            selected_range: selectedMatch?.range,
+            selected_text_preview: selectedMatch?.text_preview,
+            captures: selectedMatch?.captures,
+            node_kind: selectedMatch?.node_kind,
+            match_count_in_file: scopedMatches.length,
+            scope_match_count: input.locateArtifact.matches.length,
+            scope_affected_files: planScopeFromMatches(input.locateArtifact.matches),
+        },
+        rewrite: {
+            desired_change: input.desiredChange,
+            rewrite_template: rewriteTemplate,
+            rewrite_source: input.rewriteTemplate ? "rewrite_template" : "desired_change",
+        },
+        validation_command: input.validationCommand,
+        test_command: input.testCommand,
+    });
+}
+function previewDiffText(diffText) {
+    const lines = diffText.trimEnd().split("\n");
+    const limited = lines.slice(0, 80).join("\n");
+    const bounded = limited.slice(0, 4000);
+    return bounded.length < diffText.length ? `${bounded}\n…` : bounded;
+}
+function parseChangedRanges(diffText) {
+    const ranges = [];
+    const regex = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm;
+    let match;
+    while ((match = regex.exec(diffText)) !== null) {
+        const originalStart = Number(match[1] ?? "0");
+        const originalLength = Number(match[2] ?? "1");
+        const updatedStart = Number(match[3] ?? "0");
+        const updatedLength = Number(match[4] ?? "1");
+        ranges.push({
+            original_start_line: originalStart,
+            original_end_line: Math.max(originalStart, originalStart + Math.max(originalLength, 1) - 1),
+            updated_start_line: updatedStart,
+            updated_end_line: Math.max(updatedStart, updatedStart + Math.max(updatedLength, 1) - 1),
+        });
+    }
+    return ranges;
+}
+async function buildStructuralPreview(plan) {
+    const previewId = randomUUID();
+    const artifactPath = structuralEditArtifactRelPath("preview", previewId);
+    const finalize = (artifact) => writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_preview",
+        preview_id: previewId,
+        created_at: new Date().toISOString(),
+        artifact_path: artifactPath,
+        plan_id: plan.plan_id,
+        ...artifact,
+    });
+    const currentContent = safeRead(plan.target.file);
+    if (currentContent.startsWith("[FILE NOT FOUND]") || currentContent.startsWith("[ACCESS DENIED]")) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_unreadable",
+                error: `Cannot read ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const currentFileHash = contentSha256(currentContent);
+    if (currentFileHash !== plan.target.file_hash) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "stale_hash",
+                error: `Plan ${plan.plan_id} is stale for ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    let locateResult;
+    try {
+        locateResult = locateAstgrepMatches(plan.locator);
+    }
+    catch (error) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "scope_escape",
+                error: error instanceof Error ? error.message : String(error),
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    if (!locateResult.ok) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "locate_failed",
+                error: locateResult.error ?? "Failed to locate structural matches",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    if (locateResult.matches.length === 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "no_matches",
+                error: `No matches found for plan ${plan.plan_id}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const affectedFiles = planScopeFromMatches(locateResult.matches);
+    const targetPlan = planAstgrepRewriteTargets(affectedFiles);
+    if (!targetPlan.ok) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "ambiguous_multi_file",
+                error: targetPlan.error ?? "astgrep_rewrite refused a multi-file preview",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const targetMatches = locateResult.matches.filter((match) => match.file === plan.target.file);
+    if (targetMatches.length === 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_mismatch",
+                error: `Plan ${plan.plan_id} no longer resolves ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const astgrepCmd = detectAstgrepCommand();
+    if (!astgrepCmd) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "astgrep_unavailable",
+                error: "ast-grep command not available",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const stagingDir = wsPath(".ace-staging", `structural-edit-${plan.plan_id}-${Date.now()}`);
+    const stagedOriginal = resolve(stagingDir, `original__${plan.target.file.replace(/\//g, "__")}`);
+    const stagedRewrite = resolve(stagingDir, `rewrite__${plan.target.file.replace(/\//g, "__")}`);
+    mkdirSync(dirname(stagedOriginal), { recursive: true });
+    writeFileSync(stagedOriginal, currentContent, "utf-8");
+    writeFileSync(stagedRewrite, currentContent, "utf-8");
+    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, stagedRewrite, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    if (rewriteResult.status !== 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "rewrite_failed",
+                error: rewriteResult.stderr || rewriteResult.stdout || "ast-grep rewrite failed",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+                staging_path: stagingDir,
+            }),
+        };
+    }
+    const rewrittenContent = readFileSync(stagedRewrite, "utf-8");
+    const rewriteHash = contentSha256(rewrittenContent);
+    const diff = diffContents(currentContent, rewrittenContent);
+    const diffProcess = spawnSync("diff", ["-u", "--label", `a/${plan.target.file}`, "--label", `b/${plan.target.file}`, stagedOriginal, stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    const diffText = diffProcess.status === 1
+        ? diffProcess.stdout
+        : diffProcess.status === 0
+            ? ""
+            : diff.diff_summary;
+    return {
+        artifact: await finalize({
+            ok: true,
+            target_file: plan.target.file,
+            expected_file_hash: plan.target.file_hash,
+            current_file_hash: currentFileHash,
+            rewritten_file_hash: rewriteHash,
+            matched_count: targetMatches.length,
+            affected_file_count: affectedFiles.length,
+            changed_ranges: parseChangedRanges(diffText),
+            diff_summary: diff.diff_summary,
+            diff_preview: diffText ? previewDiffText(diffText) : diff.diff_summary,
+            promotable: diff.has_diff,
+            staging_path: stagingDir,
+        }),
+        rewritten_content: rewrittenContent,
+    };
+}
+async function resolveReadFileLinesBudget() {
+    let modelClass;
+    const statuses = await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => repo.listRuntimeStatuses()).catch(() => undefined);
+    modelClass = statuses?.[0]?.model_class;
+    const profile = readRuntimeProfile();
+    const resolved = resolveEffectiveSurgicalReadBudget(profile, modelClass);
+    return {
+        ...resolved,
+        source: modelClass ? "runtime-status" : "runtime-profile",
+    };
+}
 export function registerFileTools(server) {
     // ── Append-only artifact protection ───────────────────────────────
     // These files must only grow; overwrites from the generic write tool
@@ -26,17 +474,70 @@ export function registerFileTools(server) {
         "agent-state/PROVENANCE_LOG.md",
     ]);
     // ── Core file operations ──────────────────────────────────────────
-    server.tool("read_workspace_file", "Read any workspace file by relative path", {
+    server.tool("read_workspace_file", "Read any workspace file by relative path. Prefer outline_file for discovery, read_file_lines for known regions, astgrep_query for symbol lookup. For small_local runs, this is the fallback after surgical reads are insufficient. Cost: heavy for large files.", {
         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", {
+    server.tool("write_workspace_file", "Write or update a workspace file. Prefer apply_patch for targeted edits, astgrep_rewrite for structural rewrites. Cost: heavy.", {
         path: z.string().describe("Relative path from workspace root"),
         content: z.string().describe("File content"),
-    }, async ({ path, content }) => {
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Required workspace root for model/runtime writes"),
+    }, async ({ path, content, workspace_path }) => {
+        if (!workspace_path?.trim()) {
+            const message = "write_workspace_file requires workspace_path for workspace-root write safety.";
+            await appendWriteWorkspaceRejection({
+                reason_code: "missing_workspace_path",
+                message,
+                path,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            reason_code: "missing_workspace_path",
+                            message,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const workspaceRoot = resolve(workspace_path);
         const normalizedPath = normalizePathForValidation(path);
         const validationNotes = [];
+        let targetPath;
+        try {
+            targetPath = resolveWorkspaceWritePath(path, workspaceRoot);
+        }
+        catch (error) {
+            const reasonCode = reasonCodeFromError(error) ?? "path_escape";
+            const message = errorMessage(error);
+            await appendWriteWorkspaceRejection({
+                reason_code: reasonCode,
+                message,
+                path,
+                workspace_path,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            reason_code: reasonCode,
+                            message,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         // ── Append-only guard ───────────────────────────────────────────
         if (APPEND_ONLY_PATHS.has(normalizedPath)) {
             const existing = safeRead(path);
@@ -475,8 +976,21 @@ export function registerFileTools(server) {
             const synced = await syncTodoStateSafe(content);
             todoStateSuffix = `\nTODO state synced: ${synced.path}`;
         }
+        const storeFallbackKeys = resolveStoreFallbackKeysForPath(normalizedPath);
+        const useAsyncStoreAdmission = storeFallbackKeys.length > 0 && workspaceRoot === WORKSPACE_ROOT;
         // Keep the file as a materialized projection after the canonical store update.
-        const abs = safeWrite(path, content);
+        let abs;
+        if (useAsyncStoreAdmission) {
+            abs = await safeWriteAsync(path, content);
+        }
+        else if (workspaceRoot === WORKSPACE_ROOT) {
+            abs = safeWrite(path, content);
+        }
+        else {
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, content, "utf-8");
+            abs = targetPath;
+        }
         let kanbanSuffix = "";
         const shouldRefreshKanban = shouldAutoRefreshKanbanForPath(normalizedPath);
         if (shouldRefreshKanban) {
@@ -544,7 +1058,7 @@ export function registerFileTools(server) {
         }
     });
     // ── 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.", {
+    server.tool("safe_edit_file", "Edit a file using copy→validate→swap pattern. Automatically rolls back if validation or tests fail. Prefer apply_patch for small targeted edits. Cost: heavy for large files.", {
         path: z.string().describe("Workspace-relative file path to edit"),
         content: z.string().describe("New file content"),
         validation_command: z
@@ -676,5 +1190,482 @@ export function registerFileTools(server) {
             ],
         };
     });
+    // ── Surgical read / query / patch tools ──────────────────────────
+    server.tool("read_file_lines", "Read a specific line range from a workspace file. Prefer this over read_workspace_file for large files. Cost: moderate.", {
+        path: z.string().describe("Workspace-relative file path"),
+        start_line: z.number().int().min(1).describe("First line to read (1-indexed)"),
+        end_line: z.number().int().min(1).describe("Last line to read (inclusive)"),
+        symbol_anchor: z.string().optional().describe("Optional symbol name hint for context (informational only)"),
+    }, async ({ path: relPath, start_line, end_line, symbol_anchor }) => {
+        const budget = await resolveReadFileLinesBudget();
+        const requestedLines = end_line - start_line + 1;
+        const budgetText = budget.read_file_lines_max_lines === null
+            ? "unbounded"
+            : String(budget.read_file_lines_max_lines);
+        const headerLines = [
+            `# Budget: model_class=${budget.model_class}; read_file_lines_max_lines=${budgetText}`,
+            `# Budget source: ${budget.source}`,
+        ];
+        if (budget.read_file_lines_max_lines !== null &&
+            requestedLines > budget.read_file_lines_max_lines) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            ...headerLines,
+                            `Error: requested range (${requestedLines} lines) exceeds ${budget.model_class} budget of ${budgetText} lines.`,
+                            "Use outline_file for discovery or astgrep_query for symbol lookup.",
+                        ].join("\n"),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const slice = lines.slice(start_line - 1, end_line);
+        const result = slice.map((l, i) => `${start_line + i}: ${l}`).join("\n");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: [
+                        ...headerLines,
+                        `# ${relPath} (lines ${start_line}–${end_line})`,
+                        symbol_anchor ? `# Symbol context: ${symbol_anchor}` : "",
+                        "",
+                        result,
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                },
+            ],
+        };
+    });
+    server.tool("outline_file", "Return symbol signatures and top-level structure of a file without bodies. Use for discovery before reading specific regions. Cost: cheap.", {
+        path: z.string().describe("Workspace-relative file path"),
+    }, async ({ path: relPath }) => {
+        const content = safeRead(relPath);
+        const lines = content.split("\n");
+        const outlinePatterns = [
+            /^export\s+(async\s+)?function\s+\w+/,
+            /^export\s+(class|interface|type|enum|const|abstract)\s+\w+/,
+            /^(export\s+)?default\s+/,
+            /^\s+(async\s+)?(\w+\s+)?\w+\s*\([^)]*\)\s*[:{]/,
+            /^(function|class|interface|type|enum|const|let|var)\s+\w+/,
+        ];
+        const outline = [];
+        lines.forEach((line, idx) => {
+            if (outlinePatterns.some(p => p.test(line))) {
+                outline.push(`${idx + 1}: ${line.trimEnd()}`);
+            }
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# Outline: ${relPath} (${lines.length} lines total)`,
+                        "",
+                        outline.length > 0 ? outline.join("\n") : "(no symbols found)",
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_query", "Search for a structural pattern in workspace files using ast-grep. Returns matching ranges without reading whole files. Cost: cheap.", {
+        pattern: z.string().describe("ast-grep pattern, e.g. 'export function $NAME($$$)'"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory to search (default: src)"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max results to return (default: 50)"),
+    }, async ({ pattern, lang, scope, max_results }) => {
+        const root = wsPath(scope ?? "src");
+        const matches = runAstgrepQuery(pattern, lang, [root]);
+        const limited = matches.slice(0, max_results ?? 50);
+        const lines = limited.map((m) => `${m.file}:${m.line}: ${m.text}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_query: ${pattern} (${lang})`,
+                        `# Found ${matches.length} matches, showing ${limited.length}`,
+                        "",
+                        ...lines,
+                    ].join("\n"),
+                }],
+        };
+    });
+    server.tool("astgrep_locate", "Locate structural matches and persist a reusable locator artifact with match IDs, ranges, previews, captures, and file hashes. Cost: cheap.", {
+        pattern: z.string().describe("ast-grep pattern to match"),
+        lang: z.string().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
+        symbol_hint: z.string().optional().describe("Optional symbol name or text hint used to narrow or prioritize matches"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max results to persist/return (default: 50)"),
+    }, async ({ pattern, lang, scope, symbol_hint, max_results }) => {
+        const locatorInput = {
+            pattern,
+            lang,
+            scope: scope ?? "src",
+            symbol_hint,
+            max_results,
+        };
+        try {
+            const result = locateAstgrepMatches(locatorInput);
+            const artifact = await storeLocateArtifact(locatorInput, result);
+            return jsonResponse({
+                ok: result.ok,
+                locator_id: artifact.locator_id,
+                artifact_path: artifact.artifact_path,
+                pattern,
+                lang,
+                scope: locatorInput.scope,
+                symbol_hint,
+                total_matches: artifact.total_matches,
+                matches: artifact.matches.map(({ matched_text: _matchedText, ...match }) => match),
+                error: result.error,
+            }, !result.ok);
+        }
+        catch (error) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "scope_escape",
+                error: error instanceof Error ? error.message : String(error),
+                pattern,
+                lang,
+                scope: locatorInput.scope,
+            }, true);
+        }
+    });
+    server.tool("compile_structural_edit", "Compile a one-file structural edit plan from a selected match ID or locator input and persist the plan artifact without touching files. Cost: moderate.", {
+        match_id: z.string().optional().describe("Previously returned astgrep_locate match ID"),
+        pattern: z.string().optional().describe("ast-grep pattern to locate when no match_id is provided"),
+        lang: z.string().optional().describe("Language: ts, py, rust, go, js when using locator input"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src) when using locator input"),
+        symbol_hint: z.string().optional().describe("Optional symbol name or text hint for locator input"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max locator matches to keep (default: 50)"),
+        desired_change: z.string().describe("Plain-language edit intent; used as rewrite_template when no explicit template is provided"),
+        rewrite_template: z.string().optional().describe("Explicit ast-grep rewrite template; preferred when provided"),
+        validation_command: z.string().optional().describe("Shell command to validate before promotion"),
+        test_command: z.string().optional().describe("Shell command to run before promotion"),
+    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, validation_command, test_command, }) => {
+        if (!match_id && (!pattern || !lang)) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "locator_required",
+                error: "compile_structural_edit requires either match_id or pattern+lang locator input",
+            }, true);
+        }
+        let locateArtifact;
+        let selectedMatch;
+        let locator;
+        if (match_id) {
+            const stored = findStoredMatch(match_id);
+            if (!stored) {
+                return jsonResponse({
+                    ok: false,
+                    reason_code: "match_not_found",
+                    error: `No persisted locator match found for ${match_id}`,
+                    match_id,
+                }, true);
+            }
+            const narrowedMatches = stored.artifact.matches.filter((match) => match.file === stored.match.file);
+            locator = {
+                ...stored.artifact.input,
+                scope: stored.match.file,
+            };
+            locateArtifact = {
+                ...stored.artifact,
+                input: locator,
+                matches: narrowedMatches,
+                total_matches: narrowedMatches.length,
+            };
+            selectedMatch = stored.match;
+        }
+        else {
+            locator = {
+                pattern: pattern,
+                lang: lang,
+                scope: scope ?? "src",
+                symbol_hint,
+                max_results,
+            };
+            try {
+                const locateResult = locateAstgrepMatches(locator);
+                locateArtifact = await storeLocateArtifact(locator, locateResult);
+                if (!locateResult.ok) {
+                    return jsonResponse({
+                        ok: false,
+                        reason_code: "locate_failed",
+                        error: locateResult.error ?? "Failed to locate structural matches",
+                        locator_id: locateArtifact.locator_id,
+                        artifact_path: locateArtifact.artifact_path,
+                    }, true);
+                }
+                if (locateArtifact.matches.length === 0) {
+                    return jsonResponse({
+                        ok: false,
+                        reason_code: "no_matches",
+                        error: "No matches found for locator input",
+                        locator_id: locateArtifact.locator_id,
+                        artifact_path: locateArtifact.artifact_path,
+                    }, true);
+                }
+                selectedMatch = locateArtifact.matches[0];
+            }
+            catch (error) {
+                return jsonResponse({
+                    ok: false,
+                    reason_code: "scope_escape",
+                    error: error instanceof Error ? error.message : String(error),
+                }, true);
+            }
+        }
+        if (!locateArtifact) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "locator_missing",
+                error: "Structural locator artifact was not available",
+            }, true);
+        }
+        const scopedMatches = selectedMatch
+            ? locateArtifact.matches.filter((match) => match.file === selectedMatch?.file)
+            : locateArtifact.matches;
+        const scopeFiles = planScopeFromMatches(locateArtifact.matches);
+        if (scopeFiles.length > 1) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "ambiguous_multi_file",
+                error: `compile_structural_edit refuses multi-file locators (${scopeFiles.length} files)`,
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+                affected_files: scopeFiles,
+            }, true);
+        }
+        if (scopedMatches.length === 0) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "no_matches",
+                error: "No matches remained in the selected file for plan compilation",
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+            }, true);
+        }
+        const plan = await compileStructuralEditPlan({
+            locator,
+            locateArtifact,
+            selectedMatch,
+            desiredChange: desired_change,
+            rewriteTemplate: rewrite_template,
+            validationCommand: validation_command,
+            testCommand: test_command,
+        }).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                error: message,
+                reason_code: message.startsWith("bad_capture:") ? "bad_capture" : "plan_compile_failed",
+            };
+        });
+        if ("error" in plan) {
+            return jsonResponse({
+                ok: false,
+                reason_code: plan.reason_code,
+                error: plan.error,
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+            }, true);
+        }
+        return jsonResponse(plan);
+    });
+    server.tool("preview_structural_edit", "Stage a compiled structural edit plan, return bounded diff and changed ranges, and refuse stale-hash or multi-file previews. Cost: heavy.", {
+        plan_id: z.string().describe("Compiled structural edit plan id"),
+    }, async ({ plan_id }) => {
+        const plan = loadStructuralEditPlan(plan_id);
+        if (!plan) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "plan_not_found",
+                error: `No structural edit plan found for ${plan_id}`,
+                plan_id,
+            }, true);
+        }
+        const preview = (await buildStructuralPreview(plan)).artifact;
+        return jsonResponse(preview, !preview.ok);
+    });
+    server.tool("astgrep_rewrite", "Apply a structural rewrite to one workspace file using a compiled plan_id or direct ast-grep pattern + replacement. Multi-file rewrites are refused; staged through safe_edit_file. Emits transition-compatible result details. Cost: heavy.", {
+        plan_id: z.string().optional().describe("Compiled structural edit plan id; preferred over direct pattern+rewrite"),
+        pattern: z.string().optional().describe("ast-grep pattern to match"),
+        rewrite: z.string().optional().describe("Replacement template (use $NAME etc. from pattern)"),
+        lang: z.string().optional().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
+        confirm_multi_file: z.boolean().optional().describe("Deprecated; multi-file rewrites are always refused"),
+        validation_command: z.string().optional().describe("Shell command to validate the staged rewrite before promotion"),
+        test_command: z.string().optional().describe("Shell command to test the staged rewrite before promotion"),
+        session_id: z.string().optional().describe("Optional runtime session id for transition-record emission"),
+    }, async ({ plan_id, pattern, rewrite, lang, scope, validation_command, test_command, session_id }) => {
+        let compiledPlan;
+        if (plan_id) {
+            compiledPlan = loadStructuralEditPlan(plan_id);
+            if (!compiledPlan) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: no structural edit plan found for ${plan_id}` }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            if (!pattern || !rewrite || !lang) {
+                return {
+                    content: [{ type: "text", text: "astgrep_rewrite requires plan_id or direct pattern+rewrite+lang input." }],
+                    isError: true,
+                };
+            }
+            const locatorInput = {
+                pattern,
+                lang,
+                scope: scope ?? "src",
+                max_results: 200,
+            };
+            let locateResult;
+            try {
+                locateResult = locateAstgrepMatches(locatorInput);
+            }
+            catch {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: scope escapes workspace root (${scope})` }],
+                    isError: true,
+                };
+            }
+            const locateArtifact = await storeLocateArtifact(locatorInput, locateResult);
+            if (!locateResult.ok) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: ${locateResult.error ?? "locator failed"}` }],
+                    isError: true,
+                };
+            }
+            if (locateArtifact.matches.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No matches found for pattern. No files modified." }],
+                };
+            }
+            const scopeFiles = planScopeFromMatches(locateArtifact.matches);
+            const targetPlan = planAstgrepRewriteTargets(scopeFiles);
+            if (!targetPlan.ok) {
+                await appendAstgrepRewriteTransition(session_id, "refused", targetPlan.error ?? "astgrep_rewrite refused the requested rewrite", [locateArtifact.artifact_path, ...targetPlan.affected_files]);
+                return {
+                    content: [{
+                            type: "text",
+                            text: targetPlan.error ?? "astgrep_rewrite refused the requested rewrite",
+                        }],
+                    isError: true,
+                };
+            }
+            const directPlan = await compileStructuralEditPlan({
+                locator: locatorInput,
+                locateArtifact,
+                selectedMatch: locateArtifact.matches[0],
+                desiredChange: rewrite,
+                rewriteTemplate: rewrite,
+                validationCommand: validation_command,
+                testCommand: test_command,
+            }).catch((error) => ({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            if ("error" in directPlan) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: ${directPlan.error}` }],
+                    isError: true,
+                };
+            }
+            compiledPlan = directPlan;
+        }
+        const preview = await buildStructuralPreview(compiledPlan);
+        if (!preview.artifact.ok || !preview.artifact.promotable || !preview.rewritten_content) {
+            await appendAstgrepRewriteTransition(session_id, "refused", preview.artifact.error ?? "astgrep_rewrite preview refused promotion", [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            "astgrep_rewrite failed before promotion",
+                            `Plan: ${compiledPlan.artifact_path}`,
+                            `Preview: ${preview.artifact.artifact_path}`,
+                            `Path: ${compiledPlan.target.file}`,
+                            `Reason: ${preview.artifact.error ?? "preview was not promotable"}`,
+                        ].join("\n"),
+                    }],
+                isError: true,
+            };
+        }
+        const safeResult = safeEditFile({
+            path: compiledPlan.target.file,
+            content: preview.rewritten_content,
+            validation_command: validation_command ?? compiledPlan.validation_command,
+            test_command: test_command ?? compiledPlan.test_command,
+        });
+        if (!safeResult.ok) {
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed before promotion for ${compiledPlan.target.file}: ${safeResult.error ?? "unknown error"}`, [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `astgrep_rewrite failed before promotion`,
+                            `Plan: ${compiledPlan.artifact_path}`,
+                            `Preview: ${preview.artifact.artifact_path}`,
+                            `Path: ${compiledPlan.target.file}`,
+                            `Error: ${safeResult.error ?? "unknown error"}`,
+                            safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "FAILED"}` : "Validation: not requested",
+                            safeResult.validation_output ? `Validation output:\n${safeResult.validation_output}` : "",
+                            safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "FAILED"}` : "Tests: not requested",
+                            safeResult.test_output ? `Test output:\n${safeResult.test_output}` : "",
+                            `Staging: ${safeResult.staging_path || preview.artifact.staging_path || ""}`,
+                        ].filter(Boolean).join("\n"),
+                    }],
+                isError: true,
+            };
+        }
+        await appendAstgrepRewriteTransition(session_id, "promoted", `astgrep_rewrite promoted staged rewrite for ${compiledPlan.target.file}`, [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# astgrep_rewrite completed`,
+                        `Plan: ${compiledPlan.artifact_path}`,
+                        `Preview: ${preview.artifact.artifact_path}`,
+                        `Pattern: ${compiledPlan.locator.pattern}`,
+                        `Rewrite: ${compiledPlan.rewrite.rewrite_template}`,
+                        `Files affected: ${preview.artifact.affected_file_count}`,
+                        `Path: ${compiledPlan.target.file}`,
+                        `Hash: ${safeResult.original_hash} → ${safeResult.new_hash}`,
+                        safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "failed"}` : "Validation: not requested",
+                        safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "failed"}` : "Tests: not requested",
+                        `Staging: ${safeResult.staging_path}`,
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
+    server.tool("apply_patch", "Apply a unified diff patch to a workspace file. Applies the patch to staged content, runs optional validation/tests, and promotes to the target only on success. Cost: moderate.", {
+        path: z.string().describe("Workspace-relative file path to patch"),
+        patch: z.string().describe("Unified diff patch (output of diff -u or similar)"),
+        validation_command: z.string().optional().describe("Shell command to validate after applying (e.g. 'npx tsc --noEmit')"),
+        test_command: z.string().optional().describe("Shell command to run tests after applying"),
+    }, async ({ path: relPath, patch, validation_command, test_command }) => {
+        const result = applyPatch({ path: relPath, patch, validation_command, test_command });
+        if (!result.ok) {
+            return {
+                content: [{ type: "text", text: `apply_patch failed: ${result.error ?? "unknown error"}\n${result.validation_output ?? ""}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: [
+                        `# apply_patch: ${relPath}`,
+                        `Status: success`,
+                        result.validation_passed !== undefined ? `Validation: ${result.validation_passed ? "passed" : "failed"}` : "",
+                        result.test_passed !== undefined ? `Tests: ${result.test_passed ? "passed" : "failed"}` : "",
+                        `Staging: ${result.staging_path}`,
+                    ].filter(Boolean).join("\n"),
+                }],
+        };
+    });
 }
 //# sourceMappingURL=tools-files.js.map