@oscharko-dev/keiko 0.1.0-beta.0

package/dist/tools/patch.js

@@ -0,0 +1,403 @@
+// Patch workflow: validate (all checks, structured report), renderDryRun (preview, never
+// writes), and applyPatch (fail-closed, atomic with multi-file rollback). Every target path is
+// validated via resolveWithinWorkspace + isDenied; the validated absolute path is the ONLY value
+// handed to the WorkspaceWriter, so a static analyser's path sanitizer sits on this boundary
+// (ADR-0006 D4). node:fs is never imported here — reads go through WorkspaceFs, writes through
+// WorkspaceWriter, both injected.
+import { isDenied } from "../workspace/ignore.js";
+import { resolveWithinWorkspace } from "../workspace/paths.js";
+import { containedRealPathInfo } from "../workspace/realpath.js";
+import { PathDeniedError, PathEscapeError } from "../workspace/errors.js";
+import { nodeWorkspaceFs } from "../workspace/fs.js";
+import { CommandCancelledError, PatchApplyDisabledError, PatchApplyError, PatchValidationError, } from "./errors.js";
+import { computeFileContent } from "./patch-content.js";
+import { normalizeUnifiedDiffHunks } from "./patch-normalize.js";
+import { parseUnifiedDiff, PatchParseError } from "./patch-parse.js";
+import { nodeWorkspaceWriter } from "./writer.js";
+import { DEFAULT_PATCH_LIMITS, } from "./types.js";
+function containsNul(value) {
+    return value.includes("\u0000");
+}
+function isBinaryDiff(diff) {
+    return (diff.includes("GIT binary patch") || /^Binary files .* differ$/m.test(diff) || containsNul(diff));
+}
+function hasEscapedDiffLineBreak(diff) {
+    return diff.includes("\\n+") || diff.includes("\\n-") || diff.includes("\\n ");
+}
+function enforcePath(workspace, fs, path) {
+    let resolved;
+    try {
+        resolved = resolveWithinWorkspace(workspace.root, path);
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            throw error;
+        }
+        throw error;
+    }
+    const rel = resolved.slice(workspace.root.length).replace(/^[/\\]/, "");
+    if (isDenied(rel === "" ? path : rel)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", path);
+    }
+    const info = containedRealPathInfo(fs, workspace.root, resolved);
+    if (!realPathMatchesLexicalTarget(fs, resolved, rel, info.realRelative)) {
+        throw new PathDeniedError("path resolves through an in-workspace alias", path);
+    }
+    if (fs.exists(resolved) && (fs.stat(resolved).hardLinkCount ?? 1) > 1) {
+        throw new PathDeniedError("path resolves through a hard-linked alias", path);
+    }
+    if (isDenied(info.realRelative)) {
+        throw new PathDeniedError("path matches an always-on deny pattern", path);
+    }
+    return resolved;
+}
+function realPathMatchesLexicalTarget(fs, absolutePath, rel, realRelative) {
+    if (fs.exists(absolutePath)) {
+        return realRelative === rel;
+    }
+    return realRelative === "" || rel === realRelative || rel.startsWith(`${realRelative}/`);
+}
+function safePath(workspace, fs, path) {
+    try {
+        enforcePath(workspace, fs, path);
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof PathEscapeError) {
+            return { code: "path-unsafe", message: "path escapes the workspace", path };
+        }
+        if (error instanceof PathDeniedError) {
+            return { code: "path-denied", message: "path matches an always-on deny pattern", path };
+        }
+        throw error;
+    }
+}
+function collectPathReasons(workspace, fs, files) {
+    const reasons = [];
+    for (const file of files) {
+        const rejection = safePath(workspace, fs, file.path);
+        if (rejection !== undefined) {
+            reasons.push(rejection);
+        }
+    }
+    return reasons;
+}
+function readCurrent(workspace, fs, path) {
+    const absolute = resolveWithinWorkspace(workspace.root, path);
+    if (!fs.exists(absolute)) {
+        return undefined;
+    }
+    return fs.readFileUtf8(absolute);
+}
+function toLines(content) {
+    if (content.length === 0) {
+        return [];
+    }
+    const lines = content.split("\n");
+    if (lines.at(-1) === "") {
+        lines.pop();
+    }
+    return lines;
+}
+function hunkPreimageLines(file, hunkIndex) {
+    const hunk = file.hunks[hunkIndex];
+    if (hunk === undefined) {
+        return [];
+    }
+    return hunk.lines
+        .filter((line) => line.startsWith(" ") || line.startsWith("-"))
+        .map((line) => line.slice(1));
+}
+function startsWithSequence(lines, index, needle) {
+    return needle.every((line, offset) => lines[index + offset] === line);
+}
+function uniqueSequenceIndex(lines, needle) {
+    if (needle.length === 0 || needle.length > lines.length) {
+        return undefined;
+    }
+    let found;
+    for (let index = 0; index <= lines.length - needle.length; index += 1) {
+        if (!startsWithSequence(lines, index, needle)) {
+            continue;
+        }
+        if (found !== undefined) {
+            return undefined;
+        }
+        found = index;
+    }
+    return found;
+}
+function alignFileHunks(file, current) {
+    if (file.kind !== "modify") {
+        return file;
+    }
+    if (current === undefined) {
+        return isCreateOnlyModify(file) ? { ...file, kind: "create" } : file;
+    }
+    const currentLines = toLines(current);
+    const hunks = file.hunks.map((hunk, index) => {
+        const preimage = hunkPreimageLines(file, index);
+        if (hunk.oldStart > 0 && startsWithSequence(currentLines, hunk.oldStart - 1, preimage)) {
+            return hunk;
+        }
+        const anchor = uniqueSequenceIndex(currentLines, preimage);
+        if (anchor === undefined) {
+            return hunk;
+        }
+        const start = anchor + 1;
+        return { ...hunk, oldStart: start, newStart: start };
+    });
+    if (hunks.every((hunk, index) => hunk === file.hunks[index])) {
+        return file;
+    }
+    return { ...file, hunks };
+}
+function isCreateOnlyModify(file) {
+    return (file.hunks.length > 0 &&
+        file.hunks.every((hunk) => hunk.oldLines === 0 && hunk.lines.every((line) => line.startsWith("+"))));
+}
+function alignHunksToCurrentContent(workspace, fs, files) {
+    return files.map((file) => alignFileHunks(file, readCurrent(workspace, fs, file.path)));
+}
+function unanchoredModifyReasons(files) {
+    return files
+        .filter((file) => file.kind === "modify" && file.hunks.some((hunk) => hunk.oldStart <= 0))
+        .map((file) => ({
+        code: "malformed",
+        message: "modify hunk has no unique anchor",
+        path: file.path,
+    }));
+}
+function collectConflicts(workspace, fs, files) {
+    const conflicts = [];
+    for (const file of files) {
+        const current = readCurrent(workspace, fs, file.path);
+        const outcome = computeFileContent(file, current);
+        for (const conflict of outcome.conflicts) {
+            conflicts.push({ path: file.path, hunkIndex: conflict.hunkIndex, reason: conflict.reason });
+        }
+    }
+    return conflicts;
+}
+function sizeAndCountReasons(diff, files, totalChangedLines, limits, totalBytes) {
+    const reasons = [];
+    if (diff.trim().length > 0 && files.length === 0) {
+        reasons.push({ code: "malformed", message: "diff does not contain any file changes" });
+    }
+    if (totalBytes > limits.maxPatchBytes) {
+        reasons.push({
+            code: "size-limit",
+            message: `patch exceeds ${String(limits.maxPatchBytes)} bytes`,
+        });
+    }
+    if (isBinaryDiff(diff)) {
+        reasons.push({ code: "binary", message: "binary patches are not supported" });
+    }
+    if (hasEscapedDiffLineBreak(diff)) {
+        reasons.push({
+            code: "malformed",
+            message: "diff contains escaped newline markers; use real line breaks",
+        });
+    }
+    if (totalChangedLines > limits.maxChangedLines) {
+        reasons.push({
+            code: "line-limit",
+            message: `changed lines exceed ${String(limits.maxChangedLines)}`,
+        });
+    }
+    if (files.length > limits.maxFilesChanged) {
+        reasons.push({
+            code: "file-limit",
+            message: `files changed exceed ${String(limits.maxFilesChanged)}`,
+        });
+    }
+    return reasons;
+}
+function renderHeader(file) {
+    if (file.kind === "create") {
+        return ["--- /dev/null", `+++ b/${file.path}`];
+    }
+    if (file.kind === "delete") {
+        return [`--- a/${file.path}`, "+++ /dev/null"];
+    }
+    return [`--- a/${file.path}`, `+++ b/${file.path}`];
+}
+function renderParsedPatch(files) {
+    const lines = [];
+    for (const file of files) {
+        lines.push(...renderHeader(file));
+        for (const hunk of file.hunks) {
+            lines.push(`@@ -${String(hunk.oldStart)},${String(hunk.oldLines)} +${String(hunk.newStart)},${String(hunk.newLines)} @@`, ...hunk.lines);
+        }
+    }
+    return lines.join("\n");
+}
+function parseDiffForValidation(diff) {
+    try {
+        return { files: parseUnifiedDiff(diff).files, effectiveDiff: diff, normalized: false };
+    }
+    catch (error) {
+        if (!(error instanceof PatchParseError)) {
+            throw error;
+        }
+        const normalizedDiff = normalizeUnifiedDiffHunks(diff);
+        if (normalizedDiff === diff) {
+            throw error;
+        }
+        return {
+            files: parseUnifiedDiff(normalizedDiff).files,
+            effectiveDiff: normalizedDiff,
+            normalized: true,
+        };
+    }
+}
+function malformedValidation(diff, error) {
+    const message = error instanceof PatchParseError ? error.message : "unparseable diff";
+    return {
+        ok: false,
+        files: [],
+        totalChangedLines: 0,
+        totalBytes: Buffer.byteLength(diff, "utf8"),
+        reasons: [{ code: "malformed", message }],
+        conflicts: [],
+    };
+}
+function completeValidation(workspace, fs, limits, diff, parsed) {
+    const files = parsed.files;
+    const totalBytes = Buffer.byteLength(parsed.effectiveDiff, "utf8");
+    const totalChangedLines = files.reduce((sum, f) => sum + f.addedLines + f.removedLines, 0);
+    const pathAndSizeReasons = [
+        ...sizeAndCountReasons(parsed.effectiveDiff, files, totalChangedLines, limits, totalBytes),
+        ...collectPathReasons(workspace, fs, files),
+    ];
+    const alignedFiles = pathAndSizeReasons.length === 0 ? alignHunksToCurrentContent(workspace, fs, files) : files;
+    const aligned = alignedFiles.some((file, index) => file !== files[index]);
+    const effectiveDiff = parsed.normalized || aligned ? renderParsedPatch(alignedFiles) : diff;
+    const reasons = [...pathAndSizeReasons, ...unanchoredModifyReasons(alignedFiles)];
+    const conflicts = reasons.length === 0 ? collectConflicts(workspace, fs, alignedFiles) : [];
+    return {
+        ok: reasons.length === 0 && conflicts.length === 0,
+        files: alignedFiles,
+        totalChangedLines,
+        totalBytes: Buffer.byteLength(effectiveDiff, "utf8"),
+        ...(effectiveDiff === diff ? {} : { normalizedDiff: effectiveDiff }),
+        reasons,
+        conflicts,
+    };
+}
+export function validatePatch(workspace, diff, deps = {}) {
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const limits = deps.limits ?? DEFAULT_PATCH_LIMITS;
+    try {
+        return completeValidation(workspace, fs, limits, diff, parseDiffForValidation(diff));
+    }
+    catch (error) {
+        return malformedValidation(diff, error);
+    }
+}
+function renderFileLine(file) {
+    return `${file.kind} ${file.path} (+${String(file.addedLines)} -${String(file.removedLines)})`;
+}
+// Human-readable preview returned by propose_patch. NEVER writes. Lists per-file +/- counts,
+// any rejection reasons, and any conflicts so the reviewer sees exactly what apply would do.
+export function renderDryRun(validation) {
+    const header = validation.ok
+        ? `PATCH OK — ${String(validation.files.length)} file(s), ${String(validation.totalChangedLines)} changed line(s)`
+        : "PATCH REJECTED";
+    const fileLines = validation.files.map(renderFileLine);
+    const reasonLines = validation.reasons.map((r) => `reject[${r.code}]: ${r.message}${r.path === undefined ? "" : ` (${r.path})`}`);
+    const conflictLines = validation.conflicts.map((c) => `conflict: ${c.path} hunk#${String(c.hunkIndex)}: ${c.reason}`);
+    return [header, ...fileLines, ...reasonLines, ...conflictLines].join("\n");
+}
+function planWrites(workspace, fs, signal, files) {
+    const plans = [];
+    for (const file of files) {
+        if (signal.aborted) {
+            throw new CommandCancelledError("apply cancelled before write planning completed");
+        }
+        const absolute = enforcePath(workspace, fs, file.path);
+        const original = readCurrent(workspace, fs, file.path);
+        const outcome = computeFileContent(file, original);
+        plans.push({
+            path: file.path,
+            absolute,
+            kind: file.kind,
+            newContent: outcome.content,
+            original,
+        });
+    }
+    return plans;
+}
+function applyOne(writer, plan) {
+    if (plan.kind === "delete") {
+        writer.remove(plan.absolute);
+        return;
+    }
+    const dir = plan.absolute.replace(/[/\\][^/\\]*$/, "");
+    writer.mkdirp(dir);
+    writer.writeFileUtf8(plan.absolute, plan.newContent ?? "");
+}
+function rollback(writer, done) {
+    for (const plan of done) {
+        if (plan.original === undefined) {
+            writer.remove(plan.absolute);
+        }
+        else {
+            writer.writeFileUtf8(plan.absolute, plan.original);
+        }
+    }
+}
+function commit(writer, plans, signal) {
+    const done = [];
+    for (const plan of plans) {
+        if (isAbortRequested(signal)) {
+            rollback(writer, done);
+            throw new CommandCancelledError("apply cancelled during write phase");
+        }
+        try {
+            applyOne(writer, plan);
+            done.push(plan);
+        }
+        catch (error) {
+            rollback(writer, done);
+            const message = error instanceof Error ? error.message : "write failed";
+            throw new PatchApplyError(`apply failed, rolled back: ${message}`, plan.path);
+        }
+        if (isAbortRequested(signal)) {
+            rollback(writer, done);
+            throw new CommandCancelledError("apply cancelled during write phase");
+        }
+    }
+}
+function isAbortRequested(signal) {
+    return signal.aborted;
+}
+function summarize(plans) {
+    return {
+        changedFiles: plans.map((p) => p.path),
+        created: plans.filter((p) => p.kind === "create").map((p) => p.path),
+        deleted: plans.filter((p) => p.kind === "delete").map((p) => p.path),
+    };
+}
+// Applies a validated patch atomically. Fail-closed: no write unless applyEnabled === true.
+// Order: gate → validate → abort check → plan (pure) → write with multi-file rollback.
+export function applyPatch(workspace, diff, deps) {
+    if (!deps.applyEnabled) {
+        throw new PatchApplyDisabledError("apply is disabled (applyEnabled is false)");
+    }
+    const fs = deps.fs ?? nodeWorkspaceFs;
+    const writer = deps.writer ?? nodeWorkspaceWriter;
+    const validation = validatePatch(workspace, diff, {
+        fs,
+        ...(deps.limits ? { limits: deps.limits } : {}),
+    });
+    if (!validation.ok) {
+        throw new PatchValidationError("patch failed validation", validation.reasons, validation.conflicts);
+    }
+    if (deps.signal.aborted) {
+        throw new CommandCancelledError("apply cancelled before write phase");
+    }
+    const plans = planWrites(workspace, fs, deps.signal, validation.files);
+    commit(writer, plans, deps.signal);
+    return summarize(plans);
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,36 @@
+import type { ToolDefinition } from "../gateway/types.js";
+import type { ToolCallRequest, ToolCallResult, ToolPort } from "../harness/ports.js";
+import { type WorkspaceFs } from "../workspace/fs.js";
+import type { WorkspaceInfo } from "../workspace/types.js";
+import { type ExecutableResolver, type SpawnFn } from "./exec.js";
+import { type WorkspaceWriter } from "./writer.js";
+import { type ToolHostConfigInput } from "./types.js";
+export declare class WorkspaceToolHost implements ToolPort {
+    private readonly workspace;
+    private readonly fs;
+    private readonly writer;
+    private readonly spawn;
+    private readonly resolveExecutable;
+    private readonly config;
+    private readonly processEnv;
+    private readonly now;
+    constructor(deps: {
+        readonly workspace: WorkspaceInfo;
+        readonly fs?: WorkspaceFs | undefined;
+        readonly writer?: WorkspaceWriter | undefined;
+        readonly spawn?: SpawnFn | undefined;
+        readonly resolveExecutable?: ExecutableResolver | undefined;
+        readonly config?: ToolHostConfigInput | undefined;
+        readonly processEnv?: NodeJS.ProcessEnv | undefined;
+        readonly now?: (() => number) | undefined;
+    });
+    listTools(): readonly ToolDefinition[];
+    execute(request: ToolCallRequest): Promise<ToolCallResult>;
+    private dispatch;
+    private readFile;
+    private listFiles;
+    private inspectScripts;
+    private runCommandTool;
+    private proposePatch;
+    private applyPatchTool;
+}

package/dist/tools/registry.js

@@ -0,0 +1,231 @@
+// The tool host: WorkspaceToolHost implements the harness ToolPort. It narrows untrusted
+// `Record<string,unknown>` arguments, dispatches the 6 tools through a handler map, and returns
+// a ToolCallResult whose `output` is already redacted. run_command is the only tool that sets
+// commandExecuted:true (the executor counts those against maxCommandExecutions). All filesystem
+// reads go through the workspace layer; all writes through the WorkspaceWriter; all spawns through
+// the injected SpawnFn — so a unit test needs no real secrets and no real processes.
+import { discoverWithStats, readWorkspaceFile } from "../workspace/discovery.js";
+import { nodeWorkspaceFs } from "../workspace/fs.js";
+import { nodeSpawnFn, runCommand } from "./exec.js";
+import { CommandCancelledError, ToolArgumentError, UnknownToolError } from "./errors.js";
+import { applyPatch, renderDryRun, validatePatch } from "./patch.js";
+import { TOOL_DEFINITIONS } from "./schemas.js";
+import { nodeWorkspaceWriter } from "./writer.js";
+import { resolveToolHostConfig, } from "./types.js";
+function requireString(args, key, tool) {
+    const value = args[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ToolArgumentError(`argument '${key}' must be a non-empty string`, tool);
+    }
+    return value;
+}
+function optionalString(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new ToolArgumentError(`argument '${key}' must be a string`, tool);
+    }
+    return value;
+}
+function optionalNumber(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new ToolArgumentError(`argument '${key}' must be a non-negative number`, tool);
+    }
+    return value;
+}
+function optionalBoolean(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new ToolArgumentError(`argument '${key}' must be a boolean`, tool);
+    }
+    return value;
+}
+function optionalStringArray(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new ToolArgumentError(`argument '${key}' must be a string array`, tool);
+    }
+    return value;
+}
+function summarizeCommand(result) {
+    return JSON.stringify({
+        exitCode: result.exitCode,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    });
+}
+export class WorkspaceToolHost {
+    workspace;
+    fs;
+    writer;
+    spawn;
+    resolveExecutable;
+    config;
+    processEnv;
+    now;
+    constructor(deps) {
+        this.workspace = deps.workspace;
+        this.fs = deps.fs ?? nodeWorkspaceFs;
+        this.writer = deps.writer ?? nodeWorkspaceWriter;
+        this.spawn = deps.spawn ?? nodeSpawnFn;
+        this.resolveExecutable = deps.resolveExecutable;
+        this.config = resolveToolHostConfig(deps.config);
+        this.processEnv = deps.processEnv ?? process.env;
+        this.now = deps.now ?? Date.now;
+    }
+    listTools() {
+        return TOOL_DEFINITIONS;
+    }
+    async execute(request) {
+        if (request.signal.aborted) {
+            throw new CommandCancelledError("tool call cancelled before dispatch");
+        }
+        const startedAt = this.now();
+        const handled = await this.dispatch(request);
+        return {
+            toolCallId: request.toolCallId,
+            output: handled.output,
+            durationMs: this.now() - startedAt,
+            commandExecuted: handled.commandExecuted,
+            ...(handled.metadata === undefined ? {} : { metadata: handled.metadata }),
+        };
+    }
+    dispatch(request) {
+        const args = request.arguments;
+        switch (request.toolName) {
+            case "read_file":
+                return Promise.resolve(this.readFile(args));
+            case "list_files":
+                return Promise.resolve(this.listFiles(args));
+            case "inspect_package_scripts":
+                return Promise.resolve(this.inspectScripts(args));
+            case "run_command":
+                return this.runCommandTool(args, request.signal);
+            case "propose_patch":
+                return Promise.resolve(this.proposePatch(args));
+            case "apply_patch":
+                return Promise.resolve(this.applyPatchTool(args, request.signal));
+            default:
+                throw new UnknownToolError(`no such tool: ${request.toolName}`, request.toolName);
+        }
+    }
+    readFile(args) {
+        const path = requireString(args, "path", "read_file");
+        const maxBytes = optionalNumber(args, "maxBytes", "read_file") ?? this.config.maxReadBytes;
+        const content = readWorkspaceFile(this.workspace, path, { maxBytes }, this.fs);
+        return { output: JSON.stringify(content), commandExecuted: false };
+    }
+    listFiles(args) {
+        const maxDepth = optionalNumber(args, "maxDepth", "list_files");
+        const maxFiles = optionalNumber(args, "maxFiles", "list_files");
+        const applyGitignore = optionalBoolean(args, "applyGitignore", "list_files");
+        const result = discoverWithStats(this.workspace, {
+            maxDepth: maxDepth ?? 12,
+            maxFiles: maxFiles ?? 5_000,
+            applyGitignore: applyGitignore ?? true,
+        }, this.fs);
+        return { output: JSON.stringify(result), commandExecuted: false };
+    }
+    inspectScripts(args) {
+        const path = optionalString(args, "path", "inspect_package_scripts") ?? "package.json";
+        const content = readWorkspaceFile(this.workspace, path, { maxBytes: this.config.maxReadBytes }, this.fs);
+        const scripts = parseScripts(content.text, path);
+        return { output: JSON.stringify({ path, scripts }), commandExecuted: false };
+    }
+    async runCommandTool(args, signal) {
+        const command = requireString(args, "command", "run_command");
+        const cmdArgs = optionalStringArray(args, "args", "run_command") ?? [];
+        const cwd = optionalString(args, "cwd", "run_command");
+        const timeoutMs = optionalNumber(args, "timeoutMs", "run_command");
+        const result = await runCommand({ command, args: cmdArgs, cwd, timeoutMs, signal }, {
+            workspace: this.workspace,
+            policy: this.config.sandbox,
+            commandRules: this.config.commandRules,
+            spawn: this.spawn,
+            resolveExecutable: this.resolveExecutable,
+            processEnv: this.processEnv,
+            now: this.now,
+        });
+        return {
+            output: summarizeCommand(result),
+            commandExecuted: true,
+            metadata: {
+                kind: "command",
+                executable: command,
+                argCount: cmdArgs.length,
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                sandbox: {
+                    envAllowlist: this.config.sandbox.envAllowlist,
+                    network: this.config.sandbox.network,
+                    maxOutputBytes: this.config.sandbox.maxOutputBytes,
+                    timeoutMs: timeoutMs ?? this.config.sandbox.defaultTimeoutMs,
+                    terminationGraceMs: this.config.sandbox.terminationGraceMs,
+                    cwdRequested: cwd !== undefined,
+                },
+            },
+        };
+    }
+    proposePatch(args) {
+        const diff = requireString(args, "diff", "propose_patch");
+        const validation = validatePatch(this.workspace, diff, {
+            fs: this.fs,
+            limits: this.config.patchLimits,
+        });
+        return {
+            output: JSON.stringify({ validation, preview: renderDryRun(validation) }),
+            commandExecuted: false,
+        };
+    }
+    applyPatchTool(args, signal) {
+        const diff = requireString(args, "diff", "apply_patch");
+        const result = applyPatch(this.workspace, diff, {
+            applyEnabled: this.config.applyEnabled,
+            signal,
+            fs: this.fs,
+            writer: this.writer,
+            limits: this.config.patchLimits,
+        });
+        return {
+            output: JSON.stringify(result),
+            commandExecuted: false,
+            metadata: {
+                kind: "patch-apply",
+                changedFiles: result.changedFiles.length,
+                created: result.created.length,
+                deleted: result.deleted.length,
+            },
+        };
+    }
+}
+function parseScripts(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ToolArgumentError(`${path} is not valid JSON`, "inspect_package_scripts");
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {};
+    }
+    const scripts = parsed.scripts;
+    return typeof scripts === "object" && scripts !== null
+        ? scripts
+        : {};
+}

package/dist/tools/sandbox.d.ts

@@ -0,0 +1,8 @@
+import type { CommandRule } from "./types.js";
+export declare function buildSandboxEnv(processEnv: NodeJS.ProcessEnv, allowlist: readonly string[]): Record<string, string>;
+export declare function collectSensitiveEnvValues(processEnv: NodeJS.ProcessEnv, allowlist: readonly string[]): readonly string[];
+export interface CommandDecision {
+    readonly allowed: boolean;
+    readonly reason?: string | undefined;
+}
+export declare function isCommandAllowed(rules: readonly CommandRule[], executable: string, args: readonly string[]): CommandDecision;