s-app-scoder-agent 0.9.3 → 0.9.6

package/dist/mcp/transport-stdio.js

@@ -0,0 +1,98 @@
+import { spawn, spawnSync } from "node:child_process";
+import { expandEnv } from "./env.js";
+/** stdio transport — spawn process, line-delimited JSON-RPC trên stdin/stdout. */
+export class StdioTransport {
+    cfg;
+    kind = "stdio";
+    proc = null;
+    /** Tail of the server's stderr (last 4KB) — surfaced on connect failures. */
+    stderrTail = "";
+    buf = "";
+    msgCb = null;
+    downCb = null;
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    get alive() {
+        return this.proc !== null && this.proc.exitCode === null;
+    }
+    onMessage(cb) {
+        this.msgCb = cb;
+    }
+    onDown(cb) {
+        this.downCb = cb;
+    }
+    async start() {
+        const command = this.cfg.command;
+        if (!command)
+            throw new Error("MCP stdio transport requires \"command\" in the server config");
+        const p = spawn(command, this.cfg.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: { ...process.env, ...expandEnv(this.cfg.env) },
+            // Windows: npx/foo.cmd chỉ spawn được qua shell (libuv không tự tìm .cmd).
+            shell: process.platform === "win32",
+        });
+        this.proc = p;
+        p.stderr?.on("data", (c) => {
+            // Keep the tail for diagnostics (server logs/help output on crash);
+            // otherwise stderr is intentionally ignored.
+            this.stderrTail = (this.stderrTail + c.toString("utf8")).slice(-4096);
+        });
+        p.on("error", (e) => this.downCb?.(new Error(`spawn: ${e.message}`)));
+        p.on("exit", (code) => this.downCb?.(new Error(`process exited (code ${code ?? "?"})`)));
+        p.stdout?.on("data", (c) => this.onChunk(c));
+    }
+    send(msg) {
+        if (!this.proc?.stdin?.writable)
+            return Promise.resolve();
+        try {
+            this.proc.stdin.write(JSON.stringify(msg) + "\n");
+        }
+        catch { /* ignore */ }
+        return Promise.resolve();
+    }
+    close() {
+        const p = this.proc;
+        this.proc = null;
+        if (!p)
+            return;
+        // Release pipe handles so the parent process can exit immediately.
+        // On Windows shell:true (cmd.exe wrapper), p.kill() only kills cmd.exe —
+        // the real node child is orphaned and keeps stdout open. Use taskkill /T
+        // to kill the whole process tree; this also works for the plain node case.
+        try {
+            p.stdin?.end();
+        }
+        catch { /* ignore */ }
+        try {
+            p.stdout?.destroy();
+        }
+        catch { /* ignore */ }
+        try {
+            p.stderr?.destroy();
+        }
+        catch { /* ignore */ }
+        try {
+            p.kill();
+        }
+        catch { /* ignore */ }
+        if (process.platform === "win32" && p.pid) {
+            // Fire-and-forget; ignore errors — process may already be gone.
+            spawnSync("taskkill", ["/pid", String(p.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true });
+        }
+    }
+    onChunk(chunk) {
+        this.buf += chunk.toString("utf8");
+        let i;
+        while ((i = this.buf.indexOf("\n")) !== -1) {
+            const line = this.buf.slice(0, i).trim();
+            this.buf = this.buf.slice(i + 1);
+            if (!line)
+                continue;
+            try {
+                this.msgCb?.(JSON.parse(line));
+            }
+            catch { /* skip malformed */ }
+        }
+    }
+}

package/dist/mcp/types.js

@@ -0,0 +1,11 @@
+export const MCP_TOOL_PREFIX = "mcp__";
+export function mcpToolKey(serverName, toolName) {
+    return `${MCP_TOOL_PREFIX}${serverName}__${toolName}`;
+}
+/** Phase 4: generic MCP resource/prompt tools (advertised only when available). */
+export const MCP_RESOURCE_TOOL_NAMES = new Set([
+    "mcp_list_resources",
+    "mcp_read_resource",
+    "mcp_list_prompts",
+    "mcp_get_prompt",
+]);

package/dist/media/image.js

@@ -0,0 +1,149 @@
+/**
+ * T7: image render trong chat — detect terminal protocol + halfblock preview.
+ * Không thêm dependency: halfblock qua unicode upper-half ▀ với truecolor
+ * (iTerm2/kitty hỗ trợ COLORTERM=truecolor). Terminal không hỗ trợ → fallback
+ * link text. ponytail: 40px width cố định, không đo cell size thật — nâng
+ * cấp khi cần aspect ratio chuẩn.
+ */
+import { inflateSync } from "node:zlib";
+export function detectImageCaps(env = process.env) {
+    const truecolor = env.COLORTERM === "truecolor" || env.COLORTERM === "24bit";
+    const iterm = env.TERM_PROGRAM === "iTerm.app";
+    const kitty = env.TERM === "xterm-kitty" || env.KITTY_WINDOW_ID !== undefined;
+    return { truecolor, iterm, kitty };
+}
+const IMG_MAGIC = [
+    { ext: "png", test: (b) => b.length > 8 && b[0] === 0x89 && b[1] === 0x50 },
+    { ext: "jpg", test: (b) => b.length > 3 && b[0] === 0xff && b[1] === 0xd8 },
+    { ext: "gif", test: (b) => b.length > 6 && b.toString("ascii", 0, 3) === "GIF" },
+    { ext: "bmp", test: (b) => b.length > 2 && b[0] === 0x42 && b[1] === 0x4d },
+];
+/** Detect image từ magic bytes (đuôi file không đáng tin). */
+export function detectImageBytes(buf) {
+    return IMG_MAGIC.find((m) => m.test(buf))?.ext ?? null;
+}
+/** Decode PNG/JPG size (width/height) — chỉ PNG (IHDR) và JPEG (SOF markers). */
+export function imageSize(buf) {
+    if (detectImageBytes(buf) === "png" && buf.length > 24) {
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    if (detectImageBytes(buf) === "jpg") {
+        let i = 2;
+        while (i + 9 < buf.length) {
+            if (buf[i] !== 0xff)
+                break;
+            const marker = buf[i + 1];
+            const len = buf.readUInt16BE(i + 2);
+            if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+                return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) };
+            }
+            i += 2 + len;
+        }
+    }
+    return null;
+}
+/**
+ * Render buffer ảnh thành mảng dòng "▀" (2 pixel ảnh / 1 dòng terminal).
+ * Trả về null khi terminal không truecolor (caller fallback link).
+ */
+export function halfblockRows(buf, maxCols = 40) {
+    const png = detectImageBytes(buf) === "png";
+    if (!png)
+        return null; // ponytail: chỉ decode PNG thuần (zlib builtin); JPG → null
+    const size = imageSize(buf);
+    if (!size || size.width === 0 || size.height === 0)
+        return null;
+    // Decode IDAT: zlib inflate + unfilter scanlines.
+    let rows;
+    try {
+        rows = decodePngPixels(buf, size.width, size.height);
+    }
+    catch {
+        return null;
+    }
+    const w = size.width;
+    const cols = Math.min(maxCols, w);
+    const step = w / cols; // downsample theo cột
+    const out = [];
+    for (let py = 0; py < size.height; py += 2) {
+        let line = "";
+        for (let cx = 0; cx < cols; cx++) {
+            const px = Math.min(w - 1, Math.floor(cx * step));
+            const top = pixelAt(rows, w, px, py);
+            const bot = py + 1 < size.height ? pixelAt(rows, w, px, py + 1) : [0, 0, 0];
+            line += `\x1b[38;2;${top[0]};${top[1]};${top[2]};48;2;${bot[0]};${bot[1]};${bot[2]}m▀`;
+        }
+        out.push({ text: line + "\x1b[0m" });
+    }
+    return out;
+}
+function pixelAt(rows, w, x, y) {
+    const o = (y * w + x) * 3;
+    return [rows[o], rows[o + 1], rows[o + 2]];
+}
+/** PNG IDAT decode (zlib builtin) + unfilter — RGB/RGBA 8-bit không interlace. */
+function decodePngPixels(buf, w, h) {
+    // Scan chunks: gather IDAT data.
+    let off = 8;
+    const idat = [];
+    let bitDepth = 8;
+    let colorType = 2;
+    while (off + 8 <= buf.length) {
+        const len = buf.readUInt32BE(off);
+        const type = buf.toString("ascii", off + 4, off + 8);
+        if (type === "IHDR") {
+            bitDepth = buf[off + 16];
+            colorType = buf[off + 17];
+        }
+        if (type === "IDAT")
+            idat.push(buf.subarray(off + 8, off + 8 + len));
+        if (type === "IEND")
+            break;
+        off += 12 + len;
+    }
+    if (bitDepth !== 8 || (colorType !== 2 && colorType !== 6))
+        throw new Error("unsupported png");
+    const bpp = colorType === 6 ? 4 : 3;
+    const raw = inflateSync(Buffer.concat(idat));
+    const stride = w * bpp;
+    const px = new Uint8Array(w * h * 3);
+    let prev = new Uint8Array(stride);
+    for (let y = 0; y < h; y++) {
+        const f = raw[y * (stride + 1)];
+        const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+        const cur = new Uint8Array(stride);
+        for (let x = 0; x < stride; x++) {
+            const a = x >= bpp ? cur[x - bpp] : 0;
+            const b = prev[x];
+            const c = x >= bpp ? prev[x - bpp] : 0;
+            let v = line[x];
+            switch (f) {
+                case 1:
+                    v += a;
+                    break;
+                case 2:
+                    v += b;
+                    break;
+                case 3:
+                    v += (a + b) >> 1;
+                    break;
+                case 4: {
+                    const p = a + b - c;
+                    const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+                    v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+                    break;
+                }
+            }
+            cur[x] = v & 0xff;
+        }
+        for (let x = 0; x < w; x++) {
+            const so = x * bpp;
+            const do_ = (y * w + x) * 3;
+            px[do_] = cur[so];
+            px[do_ + 1] = cur[so + 1];
+            px[do_ + 2] = cur[so + 2];
+        }
+        prev = cur;
+    }
+    return px;
+}

package/dist/{server.js → server/server.js}

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 import process from "node:process";
-import { Agent } from "./agent.js";
+import { Agent } from "../agent.js";
 const MAX_BODY_BYTES = 1024 * 1024;
 function readBody(req, maxBytes = MAX_BODY_BYTES) {
     return new Promise((resolve, reject) => {

package/dist/{cost.js → session/cost.js}

@@ -9,7 +9,7 @@
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { resolveModelPricing } from "./constants.js";
+import { resolveModelPricing } from "../shared/constants.js";
 /** Extract `llm_usage` events from a list of raw log events. */
 export function extractUsageEvents(sessionId, events) {
     const out = [];

package/dist/{session.js → session/session.js}

@@ -174,7 +174,7 @@ export class EventSessionStore {
     get finished() {
         return this._finished;
     }
-    /** Persist a manifest (cheap summary for /sessions listing). */
+    /** Persist a manifest (cheap summary for the session picker / `scoder list`). */
     writeManifest(meta) {
         if (!this.enabled)
             return;

package/dist/{version.js → shared/version.js}

@@ -6,7 +6,7 @@
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../package.json");
+const pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), "../../package.json");
 export const CLIENT_NAME = "app-scoder-agent";
 export function getVersion() {
     try {

package/dist/tools/apply-patch.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, statSync } from "node:fs";
+import { unifiedDiff } from "../workspace/diff.js";
+import { safePath, MAX_FILE_SIZE_BYTES } from "./path-safety.js";
+import { gateWrite, toToolDiff, formatFile, applyOneEdit } from "./file-edit-common.js";
+export async function toolApplyPatch(ctx, args) {
+    let abs;
+    try {
+        abs = safePath(ctx.workdir, args.path);
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: ${err.message}` };
+    }
+    if (!Array.isArray(args.edits) || args.edits.length === 0) {
+        return { ok: false, output: "ERROR: edits must be a non-empty array." };
+    }
+    if (args.edits.length > 50) {
+        return { ok: false, output: `ERROR: too many edits (${args.edits.length}); split into chunks of at most 50.` };
+    }
+    let content;
+    try {
+        if (statSync(abs).size > MAX_FILE_SIZE_BYTES) {
+            return { ok: false, output: `ERROR: ${args.path} exceeds the ${MAX_FILE_SIZE_BYTES / 1024 / 1024}MB patch limit.` };
+        }
+        content = readFileSync(abs, "utf8");
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: cannot read ${args.path}: ${err.message}` };
+    }
+    const original = content;
+    let fuzzy = 0;
+    for (let i = 0; i < args.edits.length; i++) {
+        const e = args.edits[i];
+        if (!e || typeof e.old_string !== "string" || typeof e.new_string !== "string") {
+            return { ok: false, output: `ERROR: edit #${i + 1} must have string old_string and new_string. No changes written.` };
+        }
+        const outcome = applyOneEdit(content, args.path, e.old_string, e.new_string);
+        if (!outcome.ok) {
+            return {
+                ok: false,
+                output: `ERROR: edit #${i + 1}/${args.edits.length} failed — ${outcome.error} No changes written.`,
+            };
+        }
+        content = outcome.content;
+        if (outcome.fuzzy)
+            fuzzy++;
+    }
+    if (content === original) {
+        return { ok: true, output: `No changes to ${args.path} (all edits were no-ops).` };
+    }
+    const diff = unifiedDiff(args.path, original, content);
+    const gate = await gateWrite(ctx, args.path, diff);
+    if (gate)
+        return gate;
+    writeFileSync(abs, content, "utf8");
+    const fmtNote = formatFile(ctx, abs);
+    const fuzzyNote = fuzzy > 0 ? ` (${fuzzy} fuzzy whitespace match${fuzzy === 1 ? "" : "es"})` : "";
+    return {
+        ok: true,
+        output: `Applied ${args.edits.length} edit${args.edits.length === 1 ? "" : "s"} to ${args.path}${fuzzyNote}${fmtNote ? `\n${fmtNote}` : ""}`,
+        diff: toToolDiff(args.path, diff),
+    };
+}

package/dist/tools/edit-file.js

@@ -0,0 +1,29 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { unifiedDiff } from "../workspace/diff.js";
+import { safePath } from "./path-safety.js";
+import { gateWrite, toToolDiff, formatFile, applyOneEdit } from "./file-edit-common.js";
+export async function toolEditFile(ctx, args) {
+    let abs;
+    try {
+        abs = safePath(ctx.workdir, args.path);
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: ${err.message}` };
+    }
+    const content = readFileSync(abs, "utf8");
+    const outcome = applyOneEdit(content, args.path, args.old_string, args.new_string);
+    if (!outcome.ok)
+        return { ok: false, output: outcome.error };
+    const newContent = outcome.content;
+    const diff = unifiedDiff(args.path, content, newContent);
+    const gate = await gateWrite(ctx, args.path, diff);
+    if (gate)
+        return gate;
+    writeFileSync(abs, newContent, "utf8");
+    const fmtNote = formatFile(ctx, abs);
+    return {
+        ok: true,
+        output: `Edited ${args.path}${outcome.fuzzy ? " (fuzzy whitespace match)" : ""}${fmtNote ? `\n${fmtNote}` : ""}`,
+        diff: toToolDiff(args.path, diff),
+    };
+}

package/dist/tools/file-edit-common.js

@@ -0,0 +1,124 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { consoleReporter } from "../io/console-reporter.js";
+const FORMATTER_TIMEOUT_MS = 30_000;
+export function toToolDiff(path, diff) {
+    if (!diff.text && !diff.truncated)
+        return undefined;
+    return { path, text: diff.text, added: diff.added, removed: diff.removed, truncated: diff.truncated };
+}
+/** Shared permission/diff gate for file writes. Returns null = approved. */
+export async function gateWrite(ctx, path, diff) {
+    const mode = ctx.permissionMode ?? "auto";
+    if (mode === "readonly") {
+        if (diff.text)
+            (ctx.reporter ?? consoleReporter).printDiff(diff.text);
+        return {
+            ok: false,
+            output: `ERROR: readonly mode — write to ${path} denied. The diff above is shown for review only; nothing was written.`,
+            diff: toToolDiff(path, diff),
+        };
+    }
+    if (mode === "ask" && ctx.permissions) {
+        if (diff.text)
+            (ctx.reporter ?? consoleReporter).printDiff(diff.text);
+        const allowed = await ctx.permissions.confirmEdit(path, diff.text);
+        if (!allowed) {
+            return {
+                ok: false,
+                output: `ERROR: user rejected the write to ${path}. Try a different approach or explain why it is needed.`,
+                diff: toToolDiff(path, diff),
+            };
+        }
+    }
+    else if (diff.text && !diff.truncated) {
+        (ctx.reporter ?? consoleReporter).printDiff(diff.text);
+    }
+    else if (diff.truncated) {
+        (ctx.reporter ?? consoleReporter).diffSummary(path, diff.added, diff.removed);
+    }
+    return null;
+}
+/** Run the project formatter on a just-written file. */
+export function formatFile(ctx, abs) {
+    const fmt = ctx.formatter;
+    if (!fmt)
+        return null;
+    let cmd;
+    if (typeof fmt === "string" && fmt !== "auto") {
+        cmd = fmt.startsWith("npm:")
+            ? ["npm", "run", fmt.slice(4), "--", abs]
+            : [fmt, "--write", abs];
+    }
+    else {
+        const localBin = (name) => {
+            const base = join(ctx.workdir, "node_modules", ".bin", name);
+            if (process.platform === "win32" && existsSync(`${base}.cmd`))
+                return `${base}.cmd`;
+            if (existsSync(base))
+                return base;
+            return null;
+        };
+        const prettier = localBin("prettier");
+        const biome = localBin("biome");
+        const eslint = localBin("eslint");
+        if (prettier)
+            cmd = [prettier, "--write", abs];
+        else if (biome)
+            cmd = [biome, "format", "--write", abs];
+        else if (eslint)
+            cmd = [eslint, "--fix", abs];
+        else
+            return null;
+    }
+    const r = spawnSync(cmd[0], cmd.slice(1), {
+        cwd: ctx.workdir,
+        encoding: "utf8",
+        timeout: FORMATTER_TIMEOUT_MS,
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32",
+    });
+    if (r.error)
+        return `formatter notice: ${r.error.message.split("\n")[0]}`;
+    if (r.status !== 0) {
+        return `formatter notice: ${cmd[0]} exited ${r.status}\n${(r.stderr ?? r.stdout ?? "").slice(0, 500)}`;
+    }
+    return null;
+}
+/** v2: whitespace-insensitive regex for edit_file fuzzy fallback. */
+export function wsInsensitiveRegex(s) {
+    let rx = "";
+    for (const ch of s) {
+        if (/\s/.test(ch))
+            rx += "\\s+";
+        else
+            rx += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(rx);
+}
+/** Apply one exact (or whitespace-tolerant) replacement to in-memory content. */
+export function applyOneEdit(content, path, oldString, newString) {
+    if (typeof oldString !== "string" || oldString.length === 0) {
+        return { ok: false, error: "old_string must be a non-empty string." };
+    }
+    if (content.includes(oldString)) {
+        const count = content.split(oldString).length - 1;
+        if (count > 1) {
+            return { ok: false, error: `old_string matches ${count} locations in ${path}; include more surrounding context to make it unique.` };
+        }
+        return { ok: true, content: content.replace(oldString, () => newString), fuzzy: false };
+    }
+    const all = [...content.matchAll(new RegExp(wsInsensitiveRegex(oldString).source, "g"))];
+    if (all.length === 0) {
+        return { ok: false, error: `old_string not found in ${path}. Read the file again and retry with exact text.` };
+    }
+    if (all.length > 1) {
+        return { ok: false, error: `old_string not found exactly and ${all.length} whitespace-tolerant matches exist in ${path}; include more surrounding context to disambiguate.` };
+    }
+    return {
+        ok: true,
+        content: content.slice(0, all[0].index) + newString + content.slice(all[0].index + all[0][0].length),
+        fuzzy: true,
+    };
+}

package/dist/tools/list-files.js

@@ -0,0 +1,64 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { safePath, toPosInt, toResult, clamp } from "./path-safety.js";
+import { globToRegExp } from "./search.js";
+export function toolListFiles(workdir, args) {
+    return toResult(() => {
+        const root = safePath(workdir, args.path ?? ".");
+        const skip = new Set(["node_modules", ".git", "dist", "build", ".next", "__pycache__", ".venv"]);
+        // v2: configurable depth (default 4, cap 8), hidden-dotfiles opt-in, exclude globs.
+        const maxDepth = Math.min(toPosInt(args.depth, 4), 8);
+        const includeHidden = args.include_hidden === true || args.include_hidden === "true";
+        const excludeRx = args.exclude
+            ? new RegExp(args.exclude.split(/[,\s]+/).filter(Boolean)
+                .map((g) => globToRegExp(g).source)
+                .join("|"))
+            : null;
+        const out = [];
+        const walk = (dir, depth) => {
+            if (depth > maxDepth || out.length > 500)
+                return;
+            let entries;
+            try {
+                entries = readdirSync(dir).sort();
+            }
+            catch {
+                return;
+            }
+            for (const e of entries) {
+                if (skip.has(e))
+                    continue;
+                if (!includeHidden && e.startsWith(".") && e !== ".github")
+                    continue;
+                if (excludeRx?.test(e))
+                    continue;
+                const full = join(dir, e);
+                let st;
+                try {
+                    safePath(workdir, relative(workdir, full));
+                    st = statSync(full);
+                }
+                catch {
+                    continue;
+                }
+                const rel = relative(workdir, full).split(sep).join("/");
+                if (st.isDirectory()) {
+                    out.push(`${rel}/`);
+                    walk(full, depth + 1);
+                }
+                else {
+                    out.push(`${rel} (${st.size}b)`);
+                }
+                if (out.length > 500) {
+                    out.push("... [truncated]");
+                    return;
+                }
+            }
+        };
+        walk(root, 0);
+        return { ok: true, output: out.length > 0 ? clamp(out.join("\n")) : "(empty directory)" };
+    });
+}
+// ---------------------------------------------------------------------------
+// grep / glob (I-07)
+// ---------------------------------------------------------------------------

package/dist/tools/path-safety.js

@@ -0,0 +1,75 @@
+import { realpathSync } from "node:fs";
+import { resolve, dirname, basename, relative, isAbsolute } from "node:path";
+export let MAX_OUTPUT_CHARS = 20_000;
+export function setMaxOutputChars(n) {
+    if (Number.isFinite(n) && n > 0)
+        MAX_OUTPUT_CHARS = Math.floor(n);
+}
+export const MAX_FILE_SIZE_BYTES = 2 * 1024 * 1024; // refuse to read files > 2MB
+export function clamp(s, max = MAX_OUTPUT_CHARS) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + `\n... [truncated, ${s.length - max} more chars]`;
+}
+/** Resolve a user-supplied path inside workdir; reject escapes and symlink traversal. */
+export function safePath(workdir, p) {
+    const abs = isAbsolute(p) ? resolve(p) : resolve(workdir, p);
+    const relLex = relative(workdir, abs);
+    if (relLex.startsWith("..") || isAbsolute(relLex)) {
+        throw new Error(`Path escapes working directory: ${p}`);
+    }
+    let realWorkdir = workdir;
+    try {
+        realWorkdir = realpathSync(workdir);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT") {
+            throw new Error(`Cannot resolve working directory "${workdir}": ${err.message}`, { cause: err });
+        }
+    }
+    let probe = abs;
+    const missing = [];
+    for (;;) {
+        try {
+            const real = realpathSync(probe);
+            const reconstructed = real + [...missing].reverse().map((s) => `/${s}`).join("");
+            const rel = relative(realWorkdir, reconstructed.length > 0 ? reconstructed : real);
+            if (rel.startsWith("..") || isAbsolute(rel)) {
+                throw new Error(`Path escapes working directory: ${p}`);
+            }
+            return abs;
+        }
+        catch (err) {
+            if (err.code === "ENOENT" && probe !== dirname(probe)) {
+                missing.push(basename(probe));
+                probe = dirname(probe);
+                continue;
+            }
+            throw err;
+        }
+    }
+}
+/** Turn a sync tool step into a ToolResult, converting thrown errors (e.g. path escapes) into structured results. */
+export function toResult(fn) {
+    try {
+        return fn();
+    }
+    catch (err) {
+        return { ok: false, output: `ERROR: ${err.message}` };
+    }
+}
+const PROTECTED_READ_PATTERNS = [/^\.env$/, /\/\.env$/, /^\.env\.[^/]+$/, /\/\.env\.[^/]+$/];
+const PROTECTED_READ_EXEMPT = [/^\.env\.example$/, /\/\.env\.example$/, /^\.env\.sample$/, /\/\.env\.sample$/, /^\.env\.template$/, /\/\.env\.template$/];
+export function isProtectedEnvFile(relPath) {
+    if (PROTECTED_READ_EXEMPT.some((rx) => rx.test(relPath)))
+        return "allow";
+    if (PROTECTED_READ_PATTERNS.some((rx) => rx.test(relPath)))
+        return "ask";
+    return null;
+}
+/** Coerce a schema-provided numeric-ish arg to a positive int, else fallback. */
+export function toPosInt(v, fallback) {
+    const n = typeof v === "number" ? v : Number(v);
+    return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;
+}