@sema-ai/core 1.275.1

package/dist/tools/fs/safety.js

@@ -0,0 +1,479 @@
+import { createHash } from "node:crypto";
+/**
+ * batch-B (CC 2.1.187 parity): Read/Edit/Write take the file path as `file_path`, with the legacy `path` as a
+ * durable back-compat alias. Read the target the same way EVERYWHERE the path is consumed from a tool-call's args —
+ * not just the tool body but ALSO every gate that extracts the write target to confine it (sensitive-path,
+ * skill allowPaths, session allowDirs). A gate that only read `args.path` would see `undefined` for a `file_path`
+ * call and either fail-OPEN (bypass the guard — a real hole) or fail-closed (deny a legitimate write). Single source.
+ */
+export function fileArgPath(args) {
+    const a = args;
+    // file_path (CC) wins; an empty/non-string file_path falls back to the legacy `path`. Empty string ⇒ undefined
+    // (treated as "no path") so every caller's `=== undefined` check is sufficient — no separate length-0 guard needed.
+    const fp = a?.file_path;
+    if (typeof fp === "string" && fp.length > 0)
+        return fp;
+    const p = a?.path;
+    return typeof p === "string" && p.length > 0 ? p : undefined;
+}
+/** SHA-256 hex of UTF-8 content — the staleness/identity key (design/44 §4 inv 2, jury M1). */
+export function sha256(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+const SEP = "/";
+// ── channel [384] bug A:this layer sees BOTH path families — POSIX from linux/remote envs AND
+// Windows drive-letter form from a win32 NodeExecutionEnv (env.canonicalPath/realpath output is
+// backslash-native there). The original "/"-hardcoded helpers judged every win32 path outside root
+// (Read/Write/Edit 全瘫). All helpers below are FORM-aware (never keyed on process.platform — the env
+// may be remote and of the OTHER family than the host). UNC is refused earlier (isUncPath).
+/** Absolute in EITHER family: POSIX `/…` or drive-letter `C:\…`/`C:/…`. */
+function isAbsolutePathForm(p) {
+    return p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p);
+}
+/** Comparable form: backslashes → `/`, drive letter case-folded (`C:` vs `c:` — Windows FS ignores it). */
+function normalizeForCompare(p) {
+    let n = p.replace(/\\/g, "/");
+    if (/^[A-Za-z]:(\/|$)/.test(n))
+        n = n[0].toLowerCase() + n.slice(1);
+    return n;
+}
+/** The separator to REJOIN with, matching the path's native family (Node accepts `/` on win32, but we
+ *  keep keys family-consistent so one file can't get two map keys via mixed separators). */
+function nativeSepOf(p) {
+    return p.includes("\\") ? "\\" : "/";
+}
+function lastSepIndex(p) {
+    return Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+}
+/**
+ * Device/special files that hang or corrupt a UTF-8 read — checked by PATH only, never opened (opening
+ * `/dev/zero` blocks the process forever, design/64 §7.2(1), CC `FileReadTool` BLOCKED_DEVICE_PATHS).
+ * `/dev/null` is intentionally absent (a safe empty read/write). Plus any `/dev/fd/*` and `/proc/<pid>/fd/[0-2]`.
+ */
+const BLOCKED_DEVICE_PATHS = new Set([
+    "/dev/zero", "/dev/random", "/dev/urandom", "/dev/full",
+    "/dev/stdin", "/dev/stdout", "/dev/stderr", "/dev/tty", "/dev/console",
+    "/dev/fd/0", "/dev/fd/1", "/dev/fd/2",
+]);
+// /proc stdio aliases (design/64 §16.1): /proc/self/fd/{0,1,2} and /proc/<pid>/fd/{0,1,2} hang the same
+// way as /dev/stdin — more common to hit than /dev/fd/* on a Linux exec-env. Match any /proc/.../fd/[0-2].
+const PROC_FD_RE = /^\/proc\/[^/]+\/fd\/[0-2]$/;
+/** True for a device/special path that must never be opened (pure path check — no I/O). Matches CC's exact
+ *  12-entry blocklist (only `/dev/fd/0,1,2` — a plain `/dev/fd/7` is a readable fd file, so don't over-block,
+ *  channel [65]/clay) plus `/proc/<pid|self>/fd/[0-2]`. */
+// [K-PLATFORM-SWEEP] MINOR#9: win32 reserved device names — opening CON/PRN/AUX/NUL/COM1-9/LPT1-9 on a
+// Windows filesystem hangs or hits the device regardless of directory (and classically regardless of an
+// extension). Gated on WIN-FORM keys only: on a POSIX env `CON` is a perfectly legal filename.
+const WIN_RESERVED_RE = /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(\.[^\\/]*)?$/i;
+function isWinReservedDeviceKey(key) {
+    // codex 1.237 F6: win-form = drive-rooted, UNC, or a RELATIVE path using "\" — a POSIX absolute path
+    // ("/"-rooted) containing a literal backslash in a file name is legal and must NOT trip the block.
+    if (!(/^[A-Za-z]:[\\/]/.test(key) || key.startsWith("\\\\") || (!key.startsWith("/") && key.includes("\\"))))
+        return false;
+    const t = key.replace(/[\\/]+$/, "");
+    const base = t.slice(Math.max(t.lastIndexOf("/"), t.lastIndexOf("\\")) + 1);
+    return WIN_RESERVED_RE.test(base);
+}
+export function isBlockedDevicePath(key) {
+    return BLOCKED_DEVICE_PATHS.has(key) || PROC_FD_RE.test(key) || isWinReservedDeviceKey(key);
+}
+/**
+ * Extensions whose content is binary and would be garbage (or worse, hang) read as UTF-8 text
+ * (design/64 §7.2(2), CC `hasBinaryExtension`). Images/PDF are included here too: until multimodal read
+ * exists (design/64 §13.4 P3) they are also non-text, so reject rather than emit mojibake. Source files
+ * for app-dev (`.dart`/`.kt`/`.kts`/`.swift`/`.gradle`) are text and stay readable.
+ */
+const BINARY_EXTENSIONS = new Set([
+    ".exe", ".dll", ".so", ".dylib", ".o", ".a", ".obj", ".lib", ".bin", ".class", ".pyc", ".pyo", ".wasm",
+    ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".jar", ".war", ".ear", ".lz4", ".zst",
+    ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".tif", ".ico", ".heic", ".avif",
+    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".mp4", ".mov", ".avi", ".mkv", ".webm", ".wmv", ".flv",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".odt", ".ods", ".odp",
+    ".woff", ".woff2", ".ttf", ".otf", ".eot",
+    ".db", ".sqlite", ".sqlite3", ".mdb", ".dat", ".pdb", ".ipa", ".apk", ".dmg", ".iso", ".img",
+]);
+/** True if `path`'s extension is a known binary format (pure check — no I/O). Used by read_file and grep. */
+export function hasBinaryExtension(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot < 0)
+        return false;
+    return BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Extension → MIME for the image formats the Anthropic content API accepts (png/jpeg/gif/webp). Other image
+ *  extensions (bmp/tiff/ico/heic/avif) are NOT API-supported and would need conversion (a heavy dep), so they
+ *  stay in the binary-refused set — no silent garbage. (design/64 §13.4: Read-image, batch-C.) */
+const IMAGE_MIME_BY_EXT = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+};
+/** The MIME type to return an image file AS (a visual `ImageContent` block), or `undefined` if `path` is not a
+ *  Read-supported image. Pure — no I/O. */
+export function imageMimeForRead(path) {
+    const dot = path.lastIndexOf(".");
+    if (dot < 0)
+        return undefined;
+    return IMAGE_MIME_BY_EXT[path.slice(dot).toLowerCase()];
+}
+/** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
+ *  is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
+ *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. (batch-C, codex review.) */
+export function imageMagicMatches(bytes, mimeType) {
+    const b = bytes;
+    switch (mimeType) {
+        case "image/png": // 89 50 4E 47 0D 0A 1A 0A
+            return b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 && b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a;
+        case "image/jpeg": // FF D8 FF
+            return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
+        case "image/gif": // "GIF87a" / "GIF89a"
+            return b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 && (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61;
+        case "image/webp": // "RIFF" .... "WEBP"
+            return b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50;
+        default:
+            return false;
+    }
+}
+/**
+ * Content sniff for binary data (design/64 §17.1, CC `constants/files.ts` `isBinaryContent`): a NUL byte,
+ * or more than 10% non-printable characters in the sample, means binary. Second layer behind
+ * {@link hasBinaryExtension} — catches extension-less or mis-named binaries (a `Dockerfile` that is really
+ * a compiled blob) that would otherwise be read as mojibake. Plain text (incl. UTF-8, tabs/newlines) passes.
+ */
+export function isBinaryContent(sample) {
+    if (sample.length === 0)
+        return false;
+    let nonPrintable = 0;
+    for (let i = 0; i < sample.length; i++) {
+        const c = sample.charCodeAt(i);
+        if (c === 0)
+            return true; // a NUL byte is a definitive binary signal
+        // 编码 parity 批 (codex 镜头2 HIGH, probe-confirmed 500/500): random bytes behind a FORGED
+        // `FF FE` BOM decode via utf16le into a sea of "printable" BMP codepoints the counters here
+        // never catch. Real text NEVER contains a lone surrogate or the U+FFFE/U+FFFF noncharacters;
+        // random 16-bit units hit one with p≈1−0.963^n (≈certain past a few hundred units). Zero false
+        // positives on well-formed text (valid decodes always pair surrogates).
+        if (c >= 0xd800 && c <= 0xdbff) {
+            const next = i + 1 < sample.length ? sample.charCodeAt(i + 1) : -1;
+            if (next < 0xdc00 || next > 0xdfff)
+                return true; // lone HIGH surrogate
+            i++; // valid pair — skip the low half
+            continue;
+        }
+        if (c >= 0xdc00 && c <= 0xdfff)
+            return true; // LOW surrogate with no preceding high
+        if (c === 0xfffe || c === 0xffff)
+            return true; // noncharacters — never in real text
+        // Control chars except common text whitespace (\t \n \r \f \v) and the UTF-8 replacement char.
+        if ((c < 0x20 && c !== 0x09 && c !== 0x0a && c !== 0x0d && c !== 0x0c && c !== 0x0b) || c === 0xfffd) {
+            nonPrintable++;
+        }
+    }
+    return nonPrintable / sample.length > 0.1;
+}
+/** True for a Windows/SMB UNC path (`\\host\share`) or a `//`-prefixed network path — refused to avoid
+ *  NTLM credential leaks (design/64 §7.2(8), CC validateInput). Pure check on the RAW model path. */
+export function isUncPath(path) {
+    return path.startsWith("\\\\") || path.startsWith("//");
+}
+/** True if `p` is the rootCanonical itself or strictly inside it (path-segment-aware, not a raw prefix). */
+function within(rootCanonical, p) {
+    if (!rootCanonical)
+        return false; // defense in depth: an empty root would prefix-match EVERYTHING ("" + SEP)
+    const rootN = normalizeForCompare(rootCanonical);
+    const pN = normalizeForCompare(p);
+    if (!rootN)
+        return false;
+    if (pN === rootN)
+        return true;
+    const base = rootN.endsWith(SEP) ? rootN : rootN + SEP;
+    return pN.startsWith(base);
+}
+/**
+ * Resolve a model-supplied path to a canonical key AND enforce rootPath containment (design/44 §4
+ * inv 5/6/7). Existing paths use `canonicalPath` (resolves symlinks, so the same file can't get two
+ * keys). New paths canonicalize the **deepest existing ancestor** then rejoin the missing tail — a
+ * symlinked parent therefore can't smuggle the target outside root. Returns the canonical key, or a
+ * `path_not_in_root` violation. (Defense-in-depth at the tool layer; NOT a substitute for a sandboxed
+ * `executionEnv` — see design/44 §5.)
+ */
+export async function resolveKey(env, rootCanonical, path, signal, baseCwd, 
+// design/119 (CC --add-dir parity): extra ALLOWED containment roots (canonicalized by the caller).
+// The primary root keeps its cwd/base-path role; these only widen the containment check.
+additionalRootsCanonical) {
+    // Canonicalize the model-supplied path to its real on-disk target FIRST (shared with the
+    // sensitive-path policy, design/72 §2.1) — then layer containment + device checks on the result.
+    const canon = await canonicalizeTarget(env, path, signal, baseCwd);
+    if (!canon.ok)
+        return { ok: false, violation: { code: "invalid", message: canon.message } };
+    const key = canon.key;
+    // Blocked device/special file — checked on the canonical key (so a symlink-to-/dev/zero is caught too)
+    // BEFORE containment, so the model gets the precise "blocked device" reason (design/64 §7.2(1)).
+    if (isBlockedDevicePath(key)) {
+        return { ok: false, violation: { code: "invalid", message: `path "${path}" is a blocked device/special file (reading it can hang the process); refused.` } };
+    }
+    if (!within(rootCanonical, key) && !additionalRootsCanonical?.some((r) => within(r, key))) {
+        const roots = [rootCanonical, ...(additionalRootsCanonical ?? [])];
+        return {
+            ok: false,
+            violation: { code: "path_not_in_root", message: `path "${path}" resolves outside the allowed root${roots.length > 1 ? "s" : ""} (${roots.join(", ")}); access denied` },
+        };
+    }
+    return { ok: true, key };
+}
+/**
+ * Canonicalize a model-supplied path to its real on-disk target (symlinks resolved; for a path that
+ * doesn't exist yet, the deepest EXISTING ancestor is canonicalized then the missing tail rejoined —
+ * so a symlinked parent can't smuggle the target elsewhere). NO containment check — this is the pure
+ * canonicalization shared by `resolveKey` (which adds rootPath containment) and
+ * `createSensitivePathPolicy` (design/72 §2.1, which matches the real target against a guarded list).
+ * A single source of truth for symlink resolution: a sensitive-path guard that matched the raw path
+ * instead of the real target would be one-shot bypassable by a symlink (the bug §2.1 calls out).
+ */
+export async function canonicalizeTarget(env, path, signal, baseCwd) {
+    // UNC/network path: refuse on the RAW path before any fs op (credential-leak surface, design/64 §7.2(8)).
+    if (isUncPath(path)) {
+        return { ok: false, message: `path "${path}" is a UNC/network path; refused (potential credential leak).` };
+    }
+    // A relative path resolves against the per-task tracked cwd (design/64 §16.3): `cd`-persistence applies
+    // to the fs tools too. `baseCwd` is the RAW tracked path (never canonicalized) — containment is NOT
+    // skipped by callers that need it (the join is fed through `canonicalPath` below, so a `cd` through a
+    // symlink pointing out of root is still caught per-op). Absolute paths ignore `baseCwd`.
+    const target = baseCwd && !isAbsolutePathForm(path) ? `${baseCwd.replace(/[\\/]+$/, "")}/${path}` : path;
+    const absR = await env.absolutePath(target, signal);
+    if (!absR.ok)
+        return { ok: false, message: `cannot resolve path "${path}": ${absR.error.message}` };
+    let abs = absR.value;
+    // Follow a leaf symlink chain manually (bounded) so a DANGLING symlink — one whose target doesn't
+    // exist yet, which `canonicalPath`'s `realpath` cannot resolve — still reveals its real target.
+    // Without this, `write_file innocent.txt` where `innocent.txt -> .git/hooks/payload` would
+    // canonicalize to the innocent name and slip past the sensitive-path guard (design/72 §2.1 🔴).
+    for (let hop = 0; hop < 16; hop++) {
+        const exists = await env.exists(abs, signal);
+        if (!(exists.ok && exists.value)) {
+            // Target doesn't exist: canonicalize the deepest existing ancestor so a symlinked PARENT can't escape.
+            return { ok: true, key: await canonicalizeNewPath(env, abs, signal) };
+        }
+        const canon = await env.canonicalPath(abs, signal);
+        if (canon.ok)
+            return { ok: true, key: canon.value };
+        // `exists` (lstat) is true but `realpath` failed ⇒ a leaf symlink to a non-existent target.
+        const info = await env.fileInfo(abs, signal);
+        if (!(info.ok && info.value.kind === "symlink")) {
+            return { ok: true, key: abs }; // genuinely not a symlink (realpath failed for another reason) — best-effort raw
+        }
+        if (!env.readLink) {
+            // It IS a symlink but this env can't read links → the real target is unknown. Fail-closed (P-5):
+            // returning the raw innocent path here let `write_file innocent.txt -> .git/hooks/payload` slip the guard.
+            return { ok: false, message: `cannot resolve symlink "${path}" (env has no readLink)`, unresolvedSymlink: true };
+        }
+        const link = await env.readLink(abs, signal);
+        if (!link.ok) {
+            return { ok: false, message: `cannot read symlink "${path}": ${link.error.message}`, unresolvedSymlink: true };
+        }
+        // Resolve the (possibly relative) link target against the symlink's own directory, then loop.
+        const linkTarget = isAbsolutePathForm(link.value) ? link.value : `${parentDir(abs)}${nativeSepOf(abs)}${link.value}`;
+        const reabs = await env.absolutePath(linkTarget, signal);
+        abs = reabs.ok ? reabs.value : linkTarget;
+    }
+    // Symlink-cycle/chain cap hit — we never reached a real target. Fail-closed (don't fall to the raw path).
+    return { ok: false, message: `symlink chain for "${path}" exceeded the hop cap; target unresolved`, unresolvedSymlink: true };
+}
+/** Directory of an absolute path (drop the last segment, either family); root stays root. */
+function parentDir(abs) {
+    const i = lastSepIndex(abs);
+    if (i <= 0)
+        return SEP;
+    const head = abs.slice(0, i);
+    // `C:\x` → head `C:` is drive-RELATIVE on Windows; keep the separator so the drive root stays a root.
+    return /^[A-Za-z]:$/.test(head) ? head + abs[i] : head;
+}
+/** Canonicalize the deepest existing ancestor of a non-existent path, then rejoin the missing segments. */
+async function canonicalizeNewPath(env, abs, signal) {
+    const sep = nativeSepOf(abs);
+    const parts = abs.split(/[\\/]/);
+    const tail = [];
+    while (parts.length > 1) {
+        const candidate = parts.join(sep) || sep;
+        const ex = await env.exists(candidate, signal);
+        if (ex.ok && ex.value) {
+            const canon = await env.canonicalPath(candidate, signal);
+            const baseCanon = canon.ok ? canon.value : candidate;
+            // Rejoin with the CANONICAL base's own family (realpath output) so the key stays consistent.
+            return [baseCanon, ...tail.reverse()].join(nativeSepOf(baseCanon));
+        }
+        tail.push(parts.pop());
+    }
+    return abs; // nothing on the chain exists (unusual) — fall back to the absolute path
+}
+/** Render a `FsViolation` as the model-facing tool error text (returned, never thrown — model retries). */
+export function violationText(toolName, v) {
+    return `Error (${toolName}): ${v.message}`;
+}
+/** inv 1 (read-before-edit): a file must have been read this task before it can be edited/overwritten.
+ *  Message is CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1/§3.1/§5.1 — one message for
+ *  Edit/Write/NotebookEdit: "before writing to it", not the old sema "before editing"). */
+export function requireRead(state, key) {
+    if (!state.has(key)) {
+        return { code: "not_read", message: "File has not been read yet. Read it first before writing to it." };
+    }
+    return undefined;
+}
+/**
+ * Edit "no-op" guard (design/64 §7.2(4), CC `FileEditTool:148-153`): refuse an edit whose `old_string`
+ * equals `new_string` — without it the edit passes the match check and writes the file back unchanged (a
+ * silent no-op that wastes a turn and dirties mtime). Verbatim CC message so a CC-trained model recognizes it.
+ */
+export function checkNoChange(oldString, newString) {
+    if (oldString === newString) {
+        return { code: "invalid", message: "No changes to make: old_string and new_string are exactly the same." };
+    }
+    return undefined;
+}
+/** inv 2 (staleness): the file's current content hash must match what was recorded at read time. */
+export function checkStale(entry, currentHash) {
+    if (entry.hash !== currentHash) {
+        return { code: "stale", message: "File has been modified since it was read; read it again before editing." };
+    }
+    return undefined;
+}
+/** Count non-overlapping occurrences of `needle` in `haystack` (`needle` must be non-empty). */
+export function countOccurrences(haystack, needle) {
+    if (needle === "")
+        return 0;
+    return haystack.split(needle).length - 1;
+}
+// ── 批④ CC-parity小件 #1: ENOENT "Did you mean" correction (CC 2.1.198 findSimilarFile + the
+// case-variant class named by the sweep doc). Pure: the caller lists the parent directory.
+/**
+ * Suggest a sibling filename for a missing path (CC `File does not exist… Did you mean X?` self-heal
+ * path, bundle :335883/:478419). Honest scope (1.253 双轨终审): this is the FALLBACK tier — an
+ * approximation of CC's Cxe same-directory scan plus a sema-added case-insensitive exact-name match
+ * (the case-typo class CC misses). CC's FIRST preference (aY: re-resolve the filename against cwd
+ * and suggest the cwd path on an exists hit) needs env probing and therefore lives at the call site
+ * (fs/index.ts enoentMessage) — this function stays pure over a listed sibling set. (a) CC's
+ * findSimilarFile rule — same stem, different extension/name in the same directory; (b) the
+ * case-insensitive exact-name match. Returns the suggested NAME (not a full path), or undefined.
+ */
+export function similarNameSuggestion(siblingNames, missingName) {
+    const stemOf = (n) => {
+        const dot = n.lastIndexOf(".");
+        return dot > 0 ? n.slice(0, dot) : n;
+    };
+    const missingLower = missingName.toLowerCase();
+    const missingStem = stemOf(missingName);
+    // Case-insensitive exact match wins (closest correction), then CC's same-stem-different-ext rule.
+    const caseHit = siblingNames.find((n) => n !== missingName && n.toLowerCase() === missingLower);
+    if (caseHit)
+        return caseHit;
+    return siblingNames.find((n) => n !== missingName && stemOf(n) === missingStem);
+}
+// ── 批④ CC-parity小件 #4: curly↔straight quote-normalized Edit matching (CC 2.1.198 bundle
+// :290189-290307 — the forgiving match layer behind exact `includes`). The normalization is
+// per-character (length-preserving), so a hit in the normalized coordinate maps back to the file's
+// ACTUAL bytes at the same span — the edit always rewrites what is really in the file.
+const CURLY_TO_STRAIGHT = { "‘": "'", "’": "'", "“": '"', "”": '"' };
+/** Replace curly single/double quotes with their straight ASCII forms (CC qDa, 1:1 char mapping). */
+export function normalizeQuotes(s) {
+    return s.replace(/[‘’“”]/g, (c) => CURLY_TO_STRAIGHT[c] ?? c);
+}
+/**
+ * Resolve `oldString` against `content` with the CC quote-forgiveness layer: exact match first; on a
+ * miss, match in the curly→straight normalized coordinate and return the ACTUAL file substring at
+ * that span (CC kOe). Returns undefined when even the normalized form does not appear.
+ */
+export function resolveQuoteMatch(content, oldString) {
+    if (oldString === "")
+        return undefined;
+    if (content.includes(oldString))
+        return oldString;
+    const normOld = normalizeQuotes(oldString);
+    const idx = normalizeQuotes(content).indexOf(normOld);
+    if (idx === -1)
+        return undefined;
+    return content.substring(idx, idx + oldString.length);
+}
+/** True when the char before index `i` allows an OPENING quote (CC VDa: start, whitespace, brackets, dashes). */
+function isQuoteOpenerPosition(chars, i) {
+    if (i === 0)
+        return true;
+    const p = chars[i - 1];
+    return p === " " || p === "\t" || p === "\n" || p === "\r" || p === "(" || p === "[" || p === "{" || p === "—" || p === "–";
+}
+/**
+ * When the quote-forgiving match resolved to a curly-quoted file span, convert the straight quotes in
+ * `newString` to the matching curly forms so the replacement stays style-consistent with the file
+ * (CC Dmt/yPp/TPp: openers vs closers by preceding char; a letter-adjacent single quote is an
+ * apostrophe U+2019). Call ONLY when the matched span differs from the model's old_string.
+ */
+export function adaptNewStringQuotes(matchedOld, newString) {
+    const wantsDouble = matchedOld.includes("“") || matchedOld.includes("”");
+    const wantsSingle = matchedOld.includes("‘") || matchedOld.includes("’");
+    if (!wantsDouble && !wantsSingle)
+        return newString;
+    const chars = [...newString];
+    const out = [];
+    for (let i = 0; i < chars.length; i++) {
+        const c = chars[i];
+        if (wantsDouble && c === '"')
+            out.push(isQuoteOpenerPosition(chars, i) ? "“" : "”");
+        else if (wantsSingle && c === "'") {
+            const prev = i > 0 ? chars[i - 1] : undefined;
+            const next = i < chars.length - 1 ? chars[i + 1] : undefined;
+            const letterBefore = prev !== undefined && /\p{L}/u.test(prev);
+            const letterAfter = next !== undefined && /\p{L}/u.test(next);
+            if (letterBefore && letterAfter)
+                out.push("’"); // apostrophe
+            else
+                out.push(isQuoteOpenerPosition(chars, i) ? "‘" : "’");
+        }
+        else
+            out.push(c);
+    }
+    return out.join("");
+}
+// ── 批④ CC-parity小件 #3: whole-line deletion swallows the trailing newline (CC 2.1.198 KDa,
+// bundle :290312): deleting text (new_string === "") whose old_string does NOT end in `\n` but which
+// IS followed by one in the file removes the newline too — no orphan blank line left behind.
+/**
+ * The effective old_string a DELETION should replace: `oldString + "\n"` when new_string is empty,
+ * old_string doesn't already end with a newline, and the newline-suffixed form exists in the content;
+ * otherwise old_string unchanged (CC KDa parity). SINGLE (non-replace_all) edits only: a widened
+ * needle under replace_all would miss occurrences not followed by a newline and desync the
+ * replacement count — the Edit tool restricts the widening to single edits (1.253 双轨终审 MED).
+ */
+export function deletionOldString(content, oldString, newString) {
+    if (newString !== "")
+        return oldString;
+    if (!oldString.endsWith("\n") && content.includes(oldString + "\n"))
+        return oldString + "\n";
+    return oldString;
+}
+/**
+ * inv 3 (edit uniqueness): `oldString` must match exactly once unless `replaceAll`. Zero → not found;
+ * >1 without replaceAll → ambiguous. `truncated` adds a hint that unseen content may hold more matches (S2).
+ * Messages are CC 2.1.198 live-verbatim (all-tools-live-probe 2026-07-08 §2.1): first sentence(s) byte-exact,
+ * then a `String: <needle>` echo line (CC form). The sema truncated-read hint survives as a parenthetical
+ * appended to the sentence (probe verdict: "truncated 提示可并入括注保留").
+ */
+export function checkEditMatch(content, oldString, replaceAll, truncated) {
+    if (oldString === "") {
+        return { code: "invalid", message: "old_string must not be empty." };
+    }
+    const n = countOccurrences(content, oldString);
+    if (n === 0) {
+        return {
+            code: "ambiguous_edit",
+            message: `String to replace not found in file.${truncated ? " (note: the read was truncated — it may be in the unshown portion)" : ""}\nString: ${oldString}`,
+        };
+    }
+    if (n > 1 && !replaceAll) {
+        return {
+            code: "ambiguous_edit",
+            message: `Found ${n} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.${truncated ? " (the read was truncated; some matches may be in the unshown portion)" : ""}\nString: ${oldString}`,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=safety.js.map

package/dist/tools/fs/safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safety.js","sourceRoot":"","sources":["../../../src/tools/fs/safety.ts"],"names":[],"mappings":"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"}

package/dist/tools/fs/search.d.ts

@@ -0,0 +1,118 @@
+import type { ExecutionEnv } from "../../internal/harness.js";
+/** Directories never worth crawling (design/64 §10.3) — dependency/build/cache trees. */
+export declare const DEFAULT_IGNORE_DIRS: ReadonlySet<string>;
+export interface GrepParams {
+    pattern: string;
+    /** Treat `pattern` as a regex; default false = literal substring (CC's `-F`). */
+    regex?: boolean;
+    /** Restrict the search to this sub-path (relative to root, or absolute within root). */
+    path?: string;
+    /** Only search files matching this glob (e.g. `*.ts`, `*.{ts,tsx}`). 批④ #6 (CC parity): a
+     *  comma/whitespace-separated list (`"*.ts,*.tsx"`) is split into multiple globs (brace globs kept whole). */
+    glob?: string;
+    /** 批④ #5 (CC 2.1.201 `-o`): print only the matched (non-empty) parts of each matching line, one match
+     *  per output line (rg -o / --only-matching). content mode only; ignored otherwise (CC parity).
+     *  1.253: with `multiline` the JS fallback emits the matched SEGMENT's lines (rg -U -o shape). */
+    only_matching?: boolean;
+    /** content (default): `path:line:text`. files_with_matches: `path`. count: `path:count`. */
+    output_mode?: "content" | "files_with_matches" | "count";
+    /** Lines of context around a match (content mode only) — CC's `-C`. */
+    context?: number;
+    /** Lines of context BEFORE each match (content mode) — CC's `-B`. Wins over `context` for the before-window. */
+    context_before?: number;
+    /** Lines of context AFTER each match (content mode) — CC's `-A`. Wins over `context` for the after-window. */
+    context_after?: number;
+    /** File type filter — CC's `type` (rg `--type`): "js", "py", "rust", "go", "ts", … The rg path uses rg's
+     *  built-in type table; the JS fallback maps common types to globs (unknown types are ignored with a note). */
+    type?: string;
+    /** Case-insensitive match — CC's `-i`. */
+    ignore_case?: boolean;
+    /** Match across line boundaries — CC's multiline `-U`. JS fallback approximates per-file. */
+    multiline?: boolean;
+    /** Cap the number of output items (default 250) — CC's `head_limit`. */
+    head_limit?: number;
+    /** Skip the first N output lines — CC's `offset` (pagination partner of head_limit). */
+    offset?: number;
+}
+/** 批④ #6 (CC 2.1.198 Grep call, bundle :333383-333390): split the `glob` param into individual glob
+ *  tokens — whitespace-separated first; a token WITHOUT braces is further split on commas
+ *  (`"*.ts,*.tsx"` → two globs), while a brace token (`*.{ts,tsx}`) is kept whole (its commas are
+ *  alternation syntax, not separators). CC-verbatim splitting rules. */
+export declare function splitGlobParam(glob: string): string[];
+/** 批④ #8 (CC 2.1.198 RWp, bundle :332987): decompose an ABSOLUTE glob pattern into a base directory +
+ *  relative pattern — cut at the last separator before the first glob metachar (`* ? [ {`); a pattern
+ *  with no metachar splits dirname/basename. Returns undefined for a relative pattern (caller keeps it
+ *  as-is) or when no usable base can be derived. */
+export declare function splitAbsoluteGlobPattern(pattern: string): {
+    baseDir: string;
+    relativePattern: string;
+} | undefined;
+/**
+ * POSIX-safe single-quote so an arbitrary model-supplied string can't break out of the shell command that
+ * runs ripgrep. Wraps in single quotes (inside which the shell expands nothing — no `$()`, backtick, `;`, or
+ * glob) and escapes any embedded single quote via the `'\''` idiom (close, escaped-quote, reopen). Exported
+ * for direct injection testing (council [R145]). Renamed from `shq` for legibility.
+ */
+export declare function shellQuote(s: string): string;
+/** Lightweight `.gitignore` matcher (handles comments, negation, dir-only `/`, anchoring, `*`/`?`). */
+export declare function gitignoreMatcher(content: string): (rel: string, isDir: boolean) => boolean;
+/** Build the combined ignore predicate (ignore-set ∪ .gitignore) for a JS-fallback walk.
+ *  Exported so repo-map (design/72 §1) walks with the SAME ignore semantics as grep/glob. */
+export declare function buildIgnore(env: ExecutionEnv, root: string, signal?: AbortSignal): Promise<(rel: string, isDir: boolean) => boolean>;
+/** What a bounded walk actually saw — so consumers can be HONEST about incompleteness (A-4 class sweep:
+ *  silently bounded results must never read as exhaustive). */
+export interface WalkResult {
+    /** Greppable text files (binary-extension and oversize files excluded). */
+    files: string[];
+    /** Name-only entries: binary-extension + over-{@link FILE_MAX_BYTES} files. Content search skips them
+     *  (grep semantics / memory bound), but globbing matches NAMES — these must still be visible to it
+     *  (previously `glob *.png` could never match anything). */
+    nameOnly: string[];
+    /** True when the walk hit its file-count or depth ceiling — results MAY be missing files. */
+    incomplete: boolean;
+    /** Non-binary files skipped by content search for being over {@link FILE_MAX_BYTES} (also in
+     *  `nameOnly`). Surfaced by grep so "No matches." can't silently mean "didn't look". */
+    skippedLarge: number;
+}
+/** Bounded, ignore-aware recursive walk. Returns absolute file paths under `start`. Exported for
+ *  repo-map (design/72 §1) — same bounded/ignore-aware traversal as grep/glob, one source of truth. */
+export declare function walk(env: ExecutionEnv, root: string, start: string, ignore: (rel: string, isDir: boolean) => boolean, signal?: AbortSignal): Promise<WalkResult>;
+/** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit. */
+export declare function jsGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
+/** Detect ripgrep once per env (cached). */
+export declare function detectRipgrep(env: ExecutionEnv): Promise<boolean>;
+/** ripgrep grep: build flags from params, run, normalize to the same output as {@link jsGrep}. */
+export declare function rgGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
+/** grep dispatch: ripgrep when the env has it, else the hardened JS fallback (design/64 §10.3). */
+export declare function runGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
+/** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths (design/64 §10.4). */
+export declare function runGlob(env: ExecutionEnv, root: string, pattern: string, opts?: {
+    path?: string;
+    max?: number;
+}, signal?: AbortSignal): Promise<string>;
+/** Structured sibling of {@link runGlob} (design/116 W3): same walk/match, plus the CC-shaped facts a
+ *  shell renders (`filenames`/`numFiles`/`truncated`/`durationMs`/`totalMatches`/`countIsComplete`)
+ *  without re-parsing the text.
+ *
+ *  CC207 backlog P2-2 (CC 2.1.206:397761-398004 = 2.1.207:342454-342633, node-sliced verbatim):
+ *   · `totalMatches` — "Total number of matching files before truncation. A lower bound when
+ *     countIsComplete is false." (CC: `totalMatches: g.length`)
+ *   · `countIsComplete` — "Whether totalMatches is the exact total (true) or a floor because the
+ *     underlying search truncated its own output (false)." (CC: `countIsComplete: !m`, m = the rg
+ *     enumeration cut its own output; sema equivalent = the bounded walk hit its file/depth ceiling)
+ *   · `numFiles` — "Number of file paths returned (after any truncation)" (CC: `numFiles: u.length`
+ *     post-slice; was matchedAll.length here — pre-truncation total — fixed to the CC contract)
+ *   · `truncated` — CC: `y = m || g.length > n + r` (underlying-incomplete OR over the result cap). */
+export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern: string, opts?: {
+    path?: string;
+    max?: number;
+}, signal?: AbortSignal): Promise<{
+    text: string;
+    filenames: string[];
+    numFiles: number;
+    truncated: boolean;
+    durationMs: number;
+    totalMatches: number;
+    countIsComplete: boolean;
+}>;
+//# sourceMappingURL=search.d.ts.map