experimental-ash 0.26.0 → 0.28.0

package/dist/src/execution/sandbox/grep-tool.js

@@ -1,183 +1,3 @@
-import { normalizeModelPath } from "#runtime/framework-tools/file-state.js";
-import { requireSandboxSession, validateAbsoluteFilePath, } from "#execution/sandbox/require-sandbox.js";
-import { ripgrepIsAvailable } from "#execution/sandbox/ripgrep-probe.js";
-import { shellQuote } from "#execution/sandbox/shell-quote.js";
-import { capLineLength, MAX_OUTPUT_BYTES } from "#execution/sandbox/truncate-output.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const DEFAULT_GREP_LIMIT = 100;
-const MAX_GREP_LIMIT = 1000;
-const DEFAULT_PATH = "/workspace";
-// ---------------------------------------------------------------------------
-// Executor
-// ---------------------------------------------------------------------------
-/**
- * Searches file contents for a pattern inside the sandbox.
- */
-export async function executeGrepOnSandbox(args) {
-    const effectivePath = args.path ?? DEFAULT_PATH;
-    validateAbsoluteFilePath(effectivePath);
-    const normalizedPath = normalizeModelPath(effectivePath);
-    const effectiveLimit = Math.min(Math.max(1, args.limit ?? DEFAULT_GREP_LIMIT), MAX_GREP_LIMIT);
-    const contextLines = args.context !== undefined && args.context > 0 ? args.context : 0;
-    const sandbox = await requireSandboxSession();
-    const command = (await ripgrepIsAvailable(sandbox))
-        ? buildRipgrepCommand({
-            contextLines,
-            effectiveLimit,
-            glob: args.glob,
-            ignoreCase: args.ignoreCase ?? false,
-            literal: args.literal ?? false,
-            normalizedPath,
-            pattern: args.pattern,
-        })
-        : buildPosixGrepCommand({
-            contextLines,
-            effectiveLimit,
-            glob: args.glob,
-            ignoreCase: args.ignoreCase ?? false,
-            literal: args.literal ?? false,
-            normalizedPath,
-            pattern: args.pattern,
-        });
-    const result = await sandbox.runCommand({ command });
-    // Both ripgrep and POSIX grep use the same conventional exit codes:
-    //   0 — one or more matches were found
-    //   1 — no matches found (legitimate empty result)
-    //   2 — error occurred (e.g. regex compile failure, IO error)
-    // Any other exit code (e.g. 127 from bash when the tool is missing)
-    // indicates a real failure. Surface these as structured errors
-    // rather than silently pretending the search returned zero matches.
-    if (result.exitCode !== 0 && result.exitCode !== 1) {
-        throw buildGrepExecutionError(command, result.exitCode, result.stderr);
-    }
-    const stdout = result.stdout;
-    if (stdout.trim().length === 0) {
-        return {
-            content: "No matches found",
-            matchCount: 0,
-            path: normalizedPath,
-            truncated: false,
-        };
-    }
-    return processOutput({ effectiveLimit, normalizedPath, stdout });
-}
-/**
- * Builds the ripgrep form of the grep command. Preferred whenever
- * `rg` is on PATH — ripgrep respects `.gitignore` out of the box,
- * handles hidden-file semantics cleanly, and is substantially faster
- * than GNU grep on large repositories.
- *
- * `--no-messages` is intentionally *not* passed — we want ripgrep's
- * error messages to flow through stderr so callers can distinguish a
- * real failure (missing binary, unreadable path) from a legitimate
- * empty result.
- */
-function buildRipgrepCommand(input) {
-    const parts = ["rg", "--line-number", "--color=never", "--hidden", "--glob '!.git/*'"];
-    if (input.ignoreCase) {
-        parts.push("--ignore-case");
-    }
-    if (input.literal) {
-        parts.push("--fixed-strings");
-    }
-    if (input.glob !== undefined) {
-        parts.push(`--glob ${shellQuote(input.glob)}`);
-    }
-    if (input.contextLines > 0) {
-        parts.push(`--context ${input.contextLines}`);
-    }
-    // `--max-count` limits matches per file; we use it to bound total output.
-    parts.push(`--max-count ${input.effectiveLimit}`);
-    parts.push("--");
-    parts.push(shellQuote(input.pattern));
-    parts.push(shellQuote(input.normalizedPath));
-    return parts.join(" ");
-}
-/**
- * Builds the POSIX fallback form of the grep command using `grep -rn`.
- */
-function buildPosixGrepCommand(input) {
-    const parts = ["grep", "-r", "-n", "--color=never", "--exclude-dir=.git"];
-    if (input.ignoreCase) {
-        parts.push("-i");
-    }
-    if (input.literal) {
-        parts.push("-F");
-    }
-    else {
-        // Default to ERE so the pattern semantics line up with ripgrep's
-        // default (which uses a Rust regex dialect close to ERE).
-        parts.push("-E");
-    }
-    if (input.glob !== undefined) {
-        parts.push(`--include=${shellQuote(input.glob)}`);
-    }
-    if (input.contextLines > 0) {
-        parts.push(`-C ${input.contextLines}`);
-    }
-    // `-m` limits matches per file, analogous to ripgrep's `--max-count`.
-    parts.push(`-m ${input.effectiveLimit}`);
-    parts.push("--");
-    parts.push(shellQuote(input.pattern));
-    parts.push(shellQuote(input.normalizedPath));
-    return parts.join(" ");
-}
-function processOutput(input) {
-    // Process output: truncate long lines, cap total bytes.
-    const rawLines = input.stdout.split("\n");
-    const outputLines = [];
-    let outputBytes = 0;
-    let matchCount = 0;
-    let truncatedByBytes = false;
-    for (const rawLine of rawLines) {
-        // Skip empty trailing line from split.
-        if (rawLine.length === 0 && rawLines.indexOf(rawLine) === rawLines.length - 1) {
-            continue;
-        }
-        // Count match lines (not context separators like `--`).
-        if (rawLine !== "--" && rawLine.length > 0) {
-            // Match lines from both rg and POSIX grep have format `file:linenum:text`.
-            // Context lines use `file-linenum-text` (rg) or `file-linenum-text` (grep).
-            const isMatchLine = /^.+:\d+:/.test(rawLine);
-            if (isMatchLine) {
-                matchCount++;
-            }
-        }
-        const line = capLineLength(rawLine);
-        const lineBytes = Buffer.byteLength(line, "utf8") + 1; // +1 for \n
-        if (outputBytes + lineBytes > MAX_OUTPUT_BYTES && outputLines.length > 0) {
-            truncatedByBytes = true;
-            break;
-        }
-        outputLines.push(line);
-        outputBytes += lineBytes;
-    }
-    const truncated = truncatedByBytes || matchCount >= input.effectiveLimit;
-    let content = outputLines.join("\n");
-    if (truncated) {
-        const notices = [];
-        if (matchCount >= input.effectiveLimit) {
-            notices.push(`Match limit reached (${input.effectiveLimit}). Use a larger limit or more specific pattern.`);
-        }
-        if (truncatedByBytes) {
-            notices.push("Output truncated due to size. Use a more specific path or pattern.");
-        }
-        content += `\n\n[${notices.join(" ")}]`;
-    }
-    return {
-        content,
-        matchCount,
-        path: input.normalizedPath,
-        truncated,
-    };
-}
-// ---------------------------------------------------------------------------
-// Error helpers
-// ---------------------------------------------------------------------------
-function buildGrepExecutionError(command, exitCode, stderr) {
-    const trimmed = stderr.trim();
-    const detail = trimmed.length > 0 ? trimmed : "no stderr output";
-    return new Error(`grep failed (exit ${exitCode}): ${detail}\nCommand: ${command}`);
-}
+import{requireSandboxSession,validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{normalizeModelPath}from"#runtime/framework-tools/file-state.js";import{ripgrepIsAvailable}from"#execution/sandbox/ripgrep-probe.js";var DEFAULT_GREP_LIMIT=100,MAX_GREP_LIMIT=1e3,DEFAULT_PATH=`/workspace`;async function executeGrepOnSandbox(n){let r=n.path??DEFAULT_PATH;validateAbsoluteFilePath(r);let i=normalizeModelPath(r),u=Math.min(Math.max(1,n.limit??DEFAULT_GREP_LIMIT),MAX_GREP_LIMIT),d=n.context!==void 0&&n.context>0?n.context:0,f=await requireSandboxSession(),p=await ripgrepIsAvailable(f)?buildRipgrepCommand({contextLines:d,effectiveLimit:u,glob:n.glob,ignoreCase:n.ignoreCase??!1,literal:n.literal??!1,normalizedPath:i,pattern:n.pattern}):buildPosixGrepCommand({contextLines:d,effectiveLimit:u,glob:n.glob,ignoreCase:n.ignoreCase??!1,literal:n.literal??!1,normalizedPath:i,pattern:n.pattern}),m=await f.runCommand({command:p});if(m.exitCode!==0&&m.exitCode!==1)throw buildGrepExecutionError(p,m.exitCode,m.stderr);let h=m.stdout;return h.trim().length===0?{content:`No matches found`,matchCount:0,path:i,truncated:!1}:processOutput({effectiveLimit:u,normalizedPath:i,stdout:h})}function buildRipgrepCommand(e){let t=[`rg`,`--line-number`,`--color=never`,`--hidden`,`--glob '!.git/*'`];return e.ignoreCase&&t.push(`--ignore-case`),e.literal&&t.push(`--fixed-strings`),e.glob!==void 0&&t.push(`--glob ${shellQuote(e.glob)}`),e.contextLines>0&&t.push(`--context ${e.contextLines}`),t.push(`--max-count ${e.effectiveLimit}`),t.push(`--`),t.push(shellQuote(e.pattern)),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function buildPosixGrepCommand(e){let t=[`grep`,`-r`,`-n`,`--color=never`,`--exclude-dir=.git`];return e.ignoreCase&&t.push(`-i`),e.literal?t.push(`-F`):t.push(`-E`),e.glob!==void 0&&t.push(`--include=${shellQuote(e.glob)}`),e.contextLines>0&&t.push(`-C ${e.contextLines}`),t.push(`-m ${e.effectiveLimit}`),t.push(`--`),t.push(shellQuote(e.pattern)),t.push(shellQuote(e.normalizedPath)),t.join(` `)}function processOutput(e){let t=e.stdout.split(`
+`),i=[],a=0,o=0,s=!1;for(let e of t){if(e.length===0&&t.indexOf(e)===t.length-1)continue;e!==`--`&&e.length>0&&/^.+:\d+:/.test(e)&&o++;let c=capLineLength(e),l=Buffer.byteLength(c,`utf8`)+1;if(a+l>MAX_OUTPUT_BYTES&&i.length>0){s=!0;break}i.push(c),a+=l}let c=s||o>=e.effectiveLimit,l=i.join(`
+`);if(c){let t=[];o>=e.effectiveLimit&&t.push(`Match limit reached (${e.effectiveLimit}). Use a larger limit or more specific pattern.`),s&&t.push(`Output truncated due to size. Use a more specific path or pattern.`),l+=`\n\n[${t.join(` `)}]`}return{content:l,matchCount:o,path:e.normalizedPath,truncated:c}}function buildGrepExecutionError(e,t,n){let r=n.trim(),i=r.length>0?r:`no stderr output`;return Error(`grep failed (exit ${t}): ${i}\nCommand: ${e}`)}export{executeGrepOnSandbox};

package/dist/src/execution/sandbox/lazy-backend.js

@@ -1,33 +1 @@
-/**
- * Wraps a backend-producing function in a `SandboxBackend` proxy that
- * invokes the function exactly once, on first access to any of `.name`,
- * `.create`, or `.prewarm`. Subsequent accesses return the same cached
- * underlying backend.
- *
- * Used by `defaultBackend()` for env-conditional selection, and by the
- * authored-definition normalizer when an author passes a callback to
- * `SandboxDefinition.backend` (e.g. `backend: () => vercelBackend({...})`)
- * so the factory runs at first use rather than at module load — while
- * still preserving backend-internal state (such as the Vercel backend's
- * prewarmed-templates map) across every framework call.
- */
-export function lazyBackend(factory) {
-    let resolved;
-    function resolve() {
-        if (resolved === undefined) {
-            resolved = factory();
-        }
-        return resolved;
-    }
-    return {
-        get name() {
-            return resolve().name;
-        },
-        create(input) {
-            return resolve().create(input);
-        },
-        async prewarm(input) {
-            await resolve().prewarm(input);
-        },
-    };
-}
+function lazyBackend(e){let t;function resolve(){return t===void 0&&(t=e()),t}return{get name(){return resolve().name},create(e){return resolve().create(e)},async prewarm(e){await resolve().prewarm(e)}}}export{lazyBackend};

package/dist/src/execution/sandbox/prewarm.js

@@ -1,132 +1 @@
-import { loadCompiledModuleMapFromAuthoredSource } from "#internal/authored-module-map-loader.js";
-import { createAuthoredSourceRuntimeCompiledArtifactsSource } from "#internal/application/runtime-compiled-artifacts-source.js";
-import { ROOT_RUNTIME_AGENT_NODE_ID } from "#runtime/graph.js";
-import { loadCompiledManifest } from "#runtime/loaders/manifest.js";
-import { resolveRuntimeCompilerArtifactPaths } from "#runtime/loaders/artifact-paths.js";
-import { resolveRuntimeAgentGraph } from "#runtime/resolve-agent-graph.js";
-import { createRuntimeSandboxTemplateKey } from "#runtime/sandbox/keys.js";
-import { materializeWorkspaceDirectory } from "#runtime/workspace/seed-files.js";
-import { toErrorMessage } from "#shared/errors.js";
-/**
- * Prewarms every backend sandbox template required by one compiled
- * runtime graph.
- *
- * Iterates every registered sandbox and invokes `backend.prewarm(...)`
- * for each backend template.
- */
-export async function prewarmSandboxes(input) {
-    const targets = await collectPrewarmTargets(input);
-    if (targets.length === 0) {
-        return;
-    }
-    input.log?.(`Ash: initializing ${targets.length} sandbox ${pluralize(targets.length, "template")}...`);
-    const dispatch = input.dispatch ??
-        (async ({ backend, input: prewarmInput }) => {
-            await backend.prewarm(prewarmInput);
-        });
-    await Promise.all(targets.map(async ({ backend, label, input: prewarmInput }) => {
-        input.log?.(`Ash: initializing sandbox template "${label}"...`);
-        try {
-            await dispatch({ backend, input: prewarmInput });
-        }
-        catch (error) {
-            input.log?.(`Ash: failed to initialize sandbox template "${label}" on backend "${backend.name}": ${toErrorMessage(error)}`);
-            throw error;
-        }
-        input.log?.(`Ash: sandbox template "${label}" initialized.`);
-    }));
-    input.log?.(`Ash: initialized ${targets.length} sandbox ${pluralize(targets.length, "template")}.`);
-}
-/**
- * Loads the compiled runtime graph for one authored app root and
- * prewarms every backend's sandbox templates required by that graph.
- *
- * Hydrates the module map directly from authored source so callers
- * don't need a pre-existing `module-map.mjs` import in Node's cache.
- * Shared entrypoint for `ash dev` startup, the dev watcher, and the
- * Vercel build hook.
- */
-export async function prewarmAppSandboxes(input) {
-    const compiledArtifactsSource = createAuthoredSourceRuntimeCompiledArtifactsSource(input.appRoot);
-    const graph = await (input.loadAgentGraph ?? loadGraphFromArtifacts)({
-        compiledArtifactsSource,
-    });
-    await prewarmSandboxes({
-        compiledArtifactsSource,
-        dispatch: input.dispatch,
-        graph,
-        log: input.log,
-    });
-}
-async function collectPrewarmTargets(input) {
-    const compileDirectoryPath = resolveRuntimeCompilerArtifactPaths(input.compiledArtifactsSource.appRoot).compileDirectoryPath;
-    const runtimeContext = { appRoot: input.compiledArtifactsSource.appRoot };
-    const targets = await Promise.all(collectNodeSandboxes(input.graph).map(async ({ definition, nodeId, workspaceResourceRoot }) => {
-        const templateKey = await createRuntimeSandboxTemplateKey({
-            backendName: definition.backend.name,
-            compiledArtifactsSource: input.compiledArtifactsSource,
-            nodeId,
-            sourceId: definition.sourceId,
-        });
-        return {
-            backend: definition.backend,
-            label: formatLabel(nodeId),
-            input: {
-                bootstrap: definition.bootstrap,
-                seedFiles: await loadResourceRootSeedFiles({
-                    compileDirectoryPath,
-                    workspaceResourceRoot,
-                }),
-                runtimeContext,
-                templateKey,
-            },
-        };
-    }));
-    // Template keys factor in nodeId (see runtime/sandbox/keys.ts), so each
-    // node already produces a distinct templateKey; no dedup is needed.
-    return [...targets].sort((left, right) => left.label.localeCompare(right.label));
-}
-/**
- * Resolves the per-node compiled workspace resource root to an absolute
- * disk path under `.ash/compile/` and materializes its contents into the
- * `{path, content}` shape consumed by sandbox backends.
- *
- * Returns an empty array when the resource root descriptor advertises no
- * root entries (the materializer would emit no files anyway).
- */
-async function loadResourceRootSeedFiles(input) {
-    if (input.workspaceResourceRoot.rootEntries.length === 0) {
-        return [];
-    }
-    const materialized = await materializeWorkspaceDirectory(`${input.compileDirectoryPath}/${input.workspaceResourceRoot.logicalPath}`);
-    return materialized.map((file) => ({
-        content: file.content,
-        path: file.path,
-    }));
-}
-async function loadGraphFromArtifacts(input) {
-    const [manifest, moduleMap] = await Promise.all([
-        loadCompiledManifest({
-            compiledArtifactsSource: input.compiledArtifactsSource,
-        }),
-        loadCompiledModuleMapFromAuthoredSource({
-            compiledArtifactsSource: input.compiledArtifactsSource,
-        }),
-    ]);
-    return await resolveRuntimeAgentGraph({
-        manifest,
-        moduleMap,
-    });
-}
-function collectNodeSandboxes(graph) {
-    return [...graph.nodesByNodeId.entries()].flatMap(([nodeId, node]) => {
-        const registered = node.sandboxRegistry.sandbox;
-        return registered === null ? [] : [{ ...registered, nodeId }];
-    });
-}
-function pluralize(count, singular) {
-    return count === 1 ? singular : `${singular}s`;
-}
-function formatLabel(nodeId) {
-    return nodeId === ROOT_RUNTIME_AGENT_NODE_ID ? "root" : nodeId;
-}
+import{toErrorMessage}from"#shared/errors.js";import{createRuntimeSandboxTemplateKey}from"#runtime/sandbox/keys.js";import{loadCompiledModuleMapFromAuthoredSource}from"#internal/authored-module-map-loader.js";import{createAuthoredSourceRuntimeCompiledArtifactsSource}from"#internal/application/runtime-compiled-artifacts-source.js";import{ROOT_RUNTIME_AGENT_NODE_ID}from"#runtime/graph.js";import{loadCompiledManifest}from"#runtime/loaders/manifest.js";import{resolveRuntimeCompilerArtifactPaths}from"#runtime/loaders/artifact-paths.js";import{resolveRuntimeAgentGraph}from"#runtime/resolve-agent-graph.js";import{materializeWorkspaceDirectory}from"#runtime/workspace/seed-files.js";async function prewarmSandboxes(t){let n=await collectPrewarmTargets(t);if(n.length===0)return;t.log?.(`Ash: initializing ${n.length} sandbox ${pluralize(n.length,`template`)}...`);let r=t.dispatch??(async({backend:e,input:t})=>{await e.prewarm(t)});await Promise.all(n.map(async({backend:n,label:i,input:a})=>{t.log?.(`Ash: initializing sandbox template "${i}"...`);try{await r({backend:n,input:a})}catch(r){throw t.log?.(`Ash: failed to initialize sandbox template "${i}" on backend "${n.name}": ${toErrorMessage(r)}`),r}t.log?.(`Ash: sandbox template "${i}" initialized.`)})),t.log?.(`Ash: initialized ${n.length} sandbox ${pluralize(n.length,`template`)}.`)}async function prewarmAppSandboxes(e){let t=createAuthoredSourceRuntimeCompiledArtifactsSource(e.appRoot),n=await(e.loadAgentGraph??loadGraphFromArtifacts)({compiledArtifactsSource:t});await prewarmSandboxes({compiledArtifactsSource:t,dispatch:e.dispatch,graph:n,log:e.log})}async function collectPrewarmTargets(e){let n=resolveRuntimeCompilerArtifactPaths(e.compiledArtifactsSource.appRoot).compileDirectoryPath,r={appRoot:e.compiledArtifactsSource.appRoot};return[...await Promise.all(collectNodeSandboxes(e.graph).map(async({definition:i,nodeId:a,workspaceResourceRoot:o})=>{let s=await createRuntimeSandboxTemplateKey({backendName:i.backend.name,compiledArtifactsSource:e.compiledArtifactsSource,nodeId:a,sourceId:i.sourceId});return{backend:i.backend,label:formatLabel(a),input:{bootstrap:i.bootstrap,seedFiles:await loadResourceRootSeedFiles({compileDirectoryPath:n,workspaceResourceRoot:o}),runtimeContext:r,templateKey:s}}}))].sort((e,t)=>e.label.localeCompare(t.label))}async function loadResourceRootSeedFiles(e){return e.workspaceResourceRoot.rootEntries.length===0?[]:(await materializeWorkspaceDirectory(`${e.compileDirectoryPath}/${e.workspaceResourceRoot.logicalPath}`)).map(e=>({content:e.content,path:e.path}))}async function loadGraphFromArtifacts(e){let[t,r]=await Promise.all([loadCompiledManifest({compiledArtifactsSource:e.compiledArtifactsSource}),loadCompiledModuleMapFromAuthoredSource({compiledArtifactsSource:e.compiledArtifactsSource})]);return await resolveRuntimeAgentGraph({manifest:t,moduleMap:r})}function collectNodeSandboxes(e){return[...e.nodesByNodeId.entries()].flatMap(([e,t])=>{let n=t.sandboxRegistry.sandbox;return n===null?[]:[{...n,nodeId:e}]})}function pluralize(e,t){return e===1?t:`${t}s`}function formatLabel(e){return e===ROOT_RUNTIME_AGENT_NODE_ID?`root`:e}export{prewarmAppSandboxes,prewarmSandboxes};

package/dist/src/execution/sandbox/read-file-tool.js

@@ -1,118 +1,3 @@
-import { loadContext } from "#context/container.js";
-import { buildReadFileTargetKey, createReadFileStamp, normalizeModelPath, setReadFileStamp, } from "#runtime/framework-tools/file-state.js";
-import { requireSandboxSession, validateAbsoluteFilePath, } from "#execution/sandbox/require-sandbox.js";
-import { capLineLength, MAX_OUTPUT_BYTES } from "#execution/sandbox/truncate-output.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const DEFAULT_OFFSET = 1;
-const DEFAULT_LIMIT = 2000;
-// ---------------------------------------------------------------------------
-// Executor
-// ---------------------------------------------------------------------------
-/**
- * Reads one text file from the sandbox, applies output shaping
- * (offset, limit, line numbering, truncation), and persists a full-file
- * stamp into durable read-file state for stale-write detection.
- *
- * Used by the framework `read_file` tool and by author tools constructed
- * via `defineReadFileTool`.
- */
-export async function executeReadFileOnSandbox(args) {
-    const { filePath, offset, limit } = args;
-    validateAbsoluteFilePath(filePath);
-    const sandbox = await requireSandboxSession();
-    const normalizedPath = normalizeModelPath(filePath);
-    // ── Validate offset / limit ─────────────────────────────────────────
-    const effectiveOffset = offset ?? DEFAULT_OFFSET;
-    const effectiveLimit = limit ?? DEFAULT_LIMIT;
-    if (effectiveOffset < 1) {
-        throw new Error(`offset must be >= 1. Received: ${effectiveOffset}.`);
-    }
-    // ── Read full file for fingerprinting ───────────────────────────────
-    const rawContent = await sandbox.readTextFile({ path: filePath });
-    if (rawContent === null) {
-        throw new Error(`File not found: ${filePath}. Verify the path exists and is accessible in the sandbox.`);
-    }
-    // ── Reject non-text (NUL bytes) ─────────────────────────────────────
-    if (rawContent.includes("\0")) {
-        throw new Error(`File "${filePath}" contains NUL bytes and appears to be a binary file. ` +
-            "read_file only supports text files.");
-    }
-    // ── Split into lines ────────────────────────────────────────────────
-    // Uses a simple newline split (not the ending-preserving variant in
-    // session.ts) because the model-facing output re-joins with plain `\n`
-    // and prepends line numbers — original endings are not preserved.
-    const allLines = rawContent.split("\n");
-    // Trailing newline produces an empty last element — preserve the line
-    // count the way the user expects (a file ending with \n has N lines).
-    const totalLines = allLines.length > 0 && allLines[allLines.length - 1] === ""
-        ? allLines.length - 1
-        : allLines.length;
-    // ── Handle empty file ───────────────────────────────────────────────
-    if (totalLines === 0) {
-        if (effectiveOffset > 1) {
-            throw new Error(`offset ${effectiveOffset} is past the end of the file (0 lines). ` +
-                "Use the default offset to read an empty file.");
-        }
-        return {
-            content: "",
-            path: normalizedPath,
-            totalLines: 0,
-            truncated: false,
-        };
-    }
-    // ── Validate offset against file length ─────────────────────────────
-    if (effectiveOffset > totalLines) {
-        throw new Error(`offset ${effectiveOffset} is past the end of the file (${totalLines} lines).`);
-    }
-    // ── Persist full-file stamp ─────────────────────────────────────────
-    // Placed after all validation that can throw so a failed read_file call
-    // (e.g. offset past end) never records a stamp, preserving the
-    // read-before-write guarantee in write_file.
-    const stamp = createReadFileStamp({
-        content: rawContent,
-        filePath: normalizedPath,
-    });
-    const targetKey = buildReadFileTargetKey(normalizedPath);
-    setReadFileStamp(loadContext(), targetKey, stamp);
-    // ── Apply offset and limit ──────────────────────────────────────────
-    const startIndex = effectiveOffset - 1;
-    const endIndex = Math.min(startIndex + effectiveLimit, totalLines);
-    const selectedLines = allLines.slice(startIndex, endIndex);
-    // ── Number and truncate lines, cap at MAX_OUTPUT_BYTES ──────────────
-    const outputLines = [];
-    let outputBytes = 0;
-    let truncatedByBytes = false;
-    for (let i = 0; i < selectedLines.length; i++) {
-        const lineNumber = effectiveOffset + i;
-        const line = capLineLength(selectedLines[i] ?? "");
-        const numbered = `${lineNumber}: ${line}`;
-        const lineBytes = Buffer.byteLength(numbered, "utf8") + 1; // +1 for \n
-        if (outputBytes + lineBytes > MAX_OUTPUT_BYTES && outputLines.length > 0) {
-            truncatedByBytes = true;
-            break;
-        }
-        outputLines.push(numbered);
-        outputBytes += lineBytes;
-    }
-    const content = outputLines.join("\n");
-    const linesReturned = outputLines.length;
-    const lastLineReturned = effectiveOffset + linesReturned - 1;
-    const isTruncated = lastLineReturned < totalLines || truncatedByBytes;
-    if (isTruncated) {
-        return {
-            content,
-            nextOffset: lastLineReturned + 1,
-            path: normalizedPath,
-            totalLines,
-            truncated: true,
-        };
-    }
-    return {
-        content,
-        path: normalizedPath,
-        totalLines,
-        truncated: false,
-    };
-}
+import{loadContext}from"#context/container.js";import{requireSandboxSession,validateAbsoluteFilePath}from"#execution/sandbox/require-sandbox.js";import{MAX_OUTPUT_BYTES,capLineLength}from"#execution/sandbox/truncate-output.js";import{buildReadFileTargetKey,createReadFileStamp,normalizeModelPath,setReadFileStamp}from"#runtime/framework-tools/file-state.js";var DEFAULT_OFFSET=1,DEFAULT_LIMIT=2e3;async function executeReadFileOnSandbox(r){let{filePath:i,offset:a,limit:o}=r;validateAbsoluteFilePath(i);let s=await requireSandboxSession(),c=normalizeModelPath(i),l=a??DEFAULT_OFFSET,u=o??DEFAULT_LIMIT;if(l<1)throw Error(`offset must be >= 1. Received: ${l}.`);let d=await s.readTextFile({path:i});if(d===null)throw Error(`File not found: ${i}. Verify the path exists and is accessible in the sandbox.`);if(d.includes(`\0`))throw Error(`File "${i}" contains NUL bytes and appears to be a binary file. read_file only supports text files.`);let f=d.split(`
+`),p=f.length>0&&f[f.length-1]===``?f.length-1:f.length;if(p===0){if(l>1)throw Error(`offset ${l} is past the end of the file (0 lines). Use the default offset to read an empty file.`);return{content:``,path:c,totalLines:0,truncated:!1}}if(l>p)throw Error(`offset ${l} is past the end of the file (${p} lines).`);let m=createReadFileStamp({content:d,filePath:c}),h=buildReadFileTargetKey(c);setReadFileStamp(loadContext(),h,m);let g=l-1,_=Math.min(g+u,p),v=f.slice(g,_),y=[],b=0,x=!1;for(let e=0;e<v.length;e++){let t=`${l+e}: ${capLineLength(v[e]??``)}`,n=Buffer.byteLength(t,`utf8`)+1;if(b+n>MAX_OUTPUT_BYTES&&y.length>0){x=!0;break}y.push(t),b+=n}let S=y.join(`
+`),C=l+y.length-1;return C<p||x?{content:S,nextOffset:C+1,path:c,totalLines:p,truncated:!0}:{content:S,path:c,totalLines:p,truncated:!1}}export{executeReadFileOnSandbox};

package/dist/src/execution/sandbox/require-sandbox.js

@@ -1,32 +1 @@
-import { loadContext } from "#context/container.js";
-import { SandboxKey } from "#context/keys.js";
-/**
- * Resolves the active sandbox session from the runtime context.
- *
- * Shared preamble for every sandbox-backed tool executor (`bash`,
- * `read_file`, `write_file`, `glob`, `grep`). Centralizes the context
- * lookup, null checks, and error messages so each executor does not
- * duplicate them.
- */
-export async function requireSandboxSession() {
-    const sandboxAccess = loadContext().get(SandboxKey);
-    if (sandboxAccess === undefined) {
-        throw new Error("This tool requires sandbox access on the runtime context. " +
-            "Ensure the step is running inside a managed runtime context with sandbox support.");
-    }
-    const sandbox = await sandboxAccess.get();
-    if (sandbox === null) {
-        throw new Error("The sandbox is not available in the current runtime context.");
-    }
-    return sandbox;
-}
-/**
- * Validates that a model-supplied file path is absolute. Throws a
- * descriptive error when the path does not start with `/`.
- */
-export function validateAbsoluteFilePath(filePath) {
-    if (!filePath.startsWith("/")) {
-        throw new Error(`filePath must be an absolute path. Received: "${filePath}". ` +
-            "Use an absolute path such as /workspace/foo.ts.");
-    }
-}
+import{loadContext}from"#context/container.js";import{SandboxKey}from"#context/keys.js";async function requireSandboxSession(){let t=loadContext().get(SandboxKey);if(t===void 0)throw Error(`This tool requires sandbox access on the runtime context. Ensure the step is running inside a managed runtime context with sandbox support.`);let n=await t.get();if(n===null)throw Error(`The sandbox is not available in the current runtime context.`);return n}function validateAbsoluteFilePath(e){if(!e.startsWith(`/`))throw Error(`filePath must be an absolute path. Received: "${e}". Use an absolute path such as /workspace/foo.ts.`)}export{requireSandboxSession,validateAbsoluteFilePath};

package/dist/src/execution/sandbox/ripgrep-probe.js

@@ -1,36 +1 @@
-/**
- * Memoizes the result of probing for `rg` (ripgrep) once per sandbox
- * session. The probe runs exactly one `command -v rg` per distinct
- * session object, regardless of how many grep/glob tool calls happen.
- */
-const probes = new Map();
-/**
- * Returns `true` when `rg` is on PATH in the given sandbox session,
- * `false` otherwise. Result is cached per session.
- *
- * Framework `grep` and `glob` tools call this to decide whether to use
- * ripgrep or the POSIX `grep`/`find` fallback.
- */
-export async function ripgrepIsAvailable(session) {
-    const existing = probes.get(session.id);
-    if (existing !== undefined) {
-        return existing;
-    }
-    const pending = runProbe(session);
-    probes.set(session.id, pending);
-    try {
-        return await pending;
-    }
-    catch {
-        // If the probe itself threw, treat rg as unavailable and clear the
-        // cache so a later call can retry. A failed probe usually means the
-        // sandbox session is in a bad state; letting the next call retry is
-        // safer than permanently marking rg as missing.
-        probes.delete(session.id);
-        return false;
-    }
-}
-async function runProbe(session) {
-    const result = await session.runCommand({ command: "command -v rg >/dev/null 2>&1" });
-    return result.exitCode === 0;
-}
+var probes=new Map;async function ripgrepIsAvailable(t){let n=probes.get(t.id);if(n!==void 0)return n;let r=runProbe(t);probes.set(t.id,r);try{return await r}catch{return probes.delete(t.id),!1}}async function runProbe(e){return(await e.runCommand({command:`command -v rg >/dev/null 2>&1`})).exitCode===0}export{ripgrepIsAvailable};