experimental-ash 0.26.0 → 0.28.0

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

@@ -1,42 +1 @@
-import { requireSandboxSession } from "#execution/sandbox/require-sandbox.js";
-import { truncateTail } from "#execution/sandbox/truncate-output.js";
-// ---------------------------------------------------------------------------
-// Executor
-// ---------------------------------------------------------------------------
-/**
- * Executes one shell command inside the agent's sandbox via `SandboxKey`
- * on the active runtime context.
- *
- * Both stdout and stderr are tail-truncated to keep the end of the output
- * (where errors and final results typically appear) within the shared
- * {@link MAX_OUTPUT_LINES} / {@link MAX_OUTPUT_BYTES} limits.
- *
- * Used by the framework `bash` tool and by author tools constructed via
- * `defineBashTool`. Centralizing the executor here keeps the error
- * messages and result shape identical across all bash-style tools.
- */
-export async function executeBashOnSandbox(args) {
-    const sandbox = await requireSandboxSession();
-    const raw = await sandbox.runCommand({ command: args.command });
-    const stdoutResult = truncateTail(raw.stdout);
-    const stderrResult = truncateTail(raw.stderr);
-    const truncated = stdoutResult.truncated || stderrResult.truncated;
-    let stdout = stdoutResult.output;
-    if (stdoutResult.truncated) {
-        stdout =
-            `[stdout truncated: showing last ${stdoutResult.outputLines} of ${stdoutResult.totalLines} lines]\n` +
-                stdout;
-    }
-    let stderr = stderrResult.output;
-    if (stderrResult.truncated) {
-        stderr =
-            `[stderr truncated: showing last ${stderrResult.outputLines} of ${stderrResult.totalLines} lines]\n` +
-                stderr;
-    }
-    return {
-        exitCode: raw.exitCode,
-        stderr,
-        stdout,
-        truncated,
-    };
-}
+import{requireSandboxSession}from"#execution/sandbox/require-sandbox.js";import{truncateTail}from"#execution/sandbox/truncate-output.js";async function executeBashOnSandbox(e){let t=await(await requireSandboxSession()).runCommand({command:e.command}),n=truncateTail(t.stdout),r=truncateTail(t.stderr),i=n.truncated||r.truncated,a=n.output;n.truncated&&(a=`[stdout truncated: showing last ${n.outputLines} of ${n.totalLines} lines]\n`+a);let o=r.output;return r.truncated&&(o=`[stderr truncated: showing last ${r.outputLines} of ${r.totalLines} lines]\n`+o),{exitCode:t.exitCode,stderr:o,stdout:a,truncated:i}}export{executeBashOnSandbox};

package/dist/src/execution/sandbox/bindings/local.js

@@ -1,296 +1 @@
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { resolveSandboxCacheDirectory } from "#internal/application/paths.js";
-import { shellQuote } from "#execution/sandbox/shell-quote.js";
-import { SandboxTemplateNotProvisionedError } from "#public/definitions/sandbox-backend.js";
-import { WORKSPACE_ROOT } from "#runtime/workspace/types.js";
-import { buildSandboxSession } from "#execution/sandbox/session.js";
-import { bufferToStream, streamToBuffer } from "#execution/sandbox/stream-utils.js";
-const LOCAL_SANDBOX_SNAPSHOT_VERSION = 1;
-/**
- * Creates the local just-bash-backed sandbox backend.
- *
- * The cache directory is derived from the runtime context's `appRoot`
- * on every `create` call so the backend stays stateless and matches
- * the framework's per-call dispatch contract.
- *
- * Accepts `createOptions` for parity with other backends; the local
- * backend currently has no consumer-controllable create options so the
- * value is reserved for future widening of {@link LocalSandboxCreateOptions}.
- */
-export function createLocalSandboxBackend(_input = {}) {
-    return {
-        name: "local",
-        async prewarm(prewarmInput) {
-            const cacheDirectory = resolveSandboxCacheDirectory(prewarmInput.runtimeContext.appRoot);
-            const templateSnapshotPath = resolveTemplateSnapshotPath(cacheDirectory, prewarmInput.templateKey);
-            if (await doesPathExist(templateSnapshotPath)) {
-                return;
-            }
-            const templateSandbox = await createBashSandbox({
-                sessionKey: prewarmInput.templateKey,
-                snapshotPath: templateSnapshotPath,
-            });
-            const templateSession = buildSandboxSession(createLocalInternalSandboxSession(templateSandbox));
-            try {
-                if (prewarmInput.bootstrap !== undefined) {
-                    await prewarmInput.bootstrap({ use: async () => templateSession });
-                }
-                for (const file of prewarmInput.seedFiles) {
-                    if (typeof file.content === "string") {
-                        await templateSession.writeTextFile({ content: file.content, path: file.path });
-                    }
-                    else {
-                        await templateSession.writeBinaryFile({ content: file.content, path: file.path });
-                    }
-                }
-                const captured = await templateSandbox.captureSnapshot();
-                if (captured === null) {
-                    throw new Error(`Failed to capture local sandbox template state for "${prewarmInput.templateKey}".`);
-                }
-            }
-            finally {
-                await templateSandbox.dispose();
-            }
-        },
-        async create(createInput) {
-            const cacheDirectory = resolveSandboxCacheDirectory(createInput.runtimeContext.appRoot);
-            const templateSnapshotPath = resolveTemplateSnapshotPath(cacheDirectory, createInput.templateKey);
-            const templateSnapshot = await readLocalSnapshot(templateSnapshotPath);
-            if (templateSnapshot === null) {
-                throw new SandboxTemplateNotProvisionedError({
-                    backendName: "local",
-                    templateKey: createInput.templateKey,
-                });
-            }
-            const sessionSnapshotPath = getLocalSnapshotPath(createInput.existingMetadata) ??
-                resolveSessionSnapshotPath(cacheDirectory, createInput.sessionKey);
-            if (!(await doesPathExist(sessionSnapshotPath))) {
-                await writeLocalSnapshot(sessionSnapshotPath, templateSnapshot);
-            }
-            const sandbox = await createBashSandbox({
-                sessionKey: createInput.sessionKey,
-                snapshotPath: sessionSnapshotPath,
-            });
-            return createHandle(sandbox);
-        },
-    };
-}
-async function createBashSandbox(input) {
-    const { Bash, InMemoryFs } = await import("#compiled/just-bash/index.js");
-    const snapshot = await readLocalSnapshot(input.snapshotPath);
-    const filesystem = new InMemoryFs(createInitialFiles(snapshot));
-    await ensureLocalSandboxDirectories(filesystem);
-    await restoreLocalSandboxDirectories(filesystem, snapshot?.entries ?? []);
-    const bash = new Bash({
-        cwd: WORKSPACE_ROOT,
-        env: snapshot?.env,
-        fs: filesystem,
-        network: {
-            dangerouslyAllowFullInternetAccess: true,
-        },
-    });
-    return {
-        async captureSnapshot() {
-            const nextSnapshot = await captureLocalSnapshot({ filesystem, sandbox: bash });
-            await writeLocalSnapshot(input.snapshotPath, nextSnapshot);
-            return { snapshotPath: input.snapshotPath };
-        },
-        async dispose() {
-            const disposableBash = bash;
-            await disposableBash.dispose?.();
-        },
-        async executeCommand(options) {
-            if (options.abortSignal?.aborted) {
-                throw new DOMException("The operation was aborted.", "AbortError");
-            }
-            const wrapped = options.workingDirectory !== undefined
-                ? `( cd ${shellQuote(options.workingDirectory)} && ${options.command} )`
-                : options.command;
-            const execPromise = bash.exec(wrapped);
-            const result = options.abortSignal
-                ? await raceAbort(execPromise, options.abortSignal)
-                : await execPromise;
-            return { exitCode: result.exitCode, stderr: result.stderr, stdout: result.stdout };
-        },
-        async readFileBytes(path) {
-            let bytes;
-            try {
-                bytes = await filesystem.readFileBuffer(path);
-            }
-            catch {
-                return null;
-            }
-            return Buffer.from(bytes);
-        },
-        async readFileText(path) {
-            let bytes;
-            try {
-                bytes = await filesystem.readFileBuffer(path);
-            }
-            catch {
-                return null;
-            }
-            return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-        },
-        sessionKey: input.sessionKey,
-        snapshotPath: input.snapshotPath,
-        async writeFiles(files) {
-            for (const file of files) {
-                const dir = dirname(file.path);
-                await filesystem.mkdir(dir, { recursive: true });
-                // Preserve Buffer content byte-for-byte so binary assets (for
-                // example images under a skill's `assets/` directory) survive
-                // the write. `Buffer` is a `Uint8Array` subclass, which the
-                // just-bash filesystem accepts directly alongside strings.
-                await filesystem.writeFile(file.path, file.content);
-            }
-        },
-    };
-}
-function createHandle(sandbox) {
-    const session = buildSandboxSession(createLocalInternalSandboxSession(sandbox));
-    return {
-        session,
-        useSessionFn: async () => session,
-        async captureState() {
-            const metadata = (await sandbox.captureSnapshot()) ?? {};
-            return {
-                backendName: "local",
-                metadata,
-                sessionKey: sandbox.sessionKey,
-            };
-        },
-        async dispose() {
-            await sandbox.dispose();
-        },
-    };
-}
-function createLocalInternalSandboxSession(sandbox) {
-    return {
-        id: sandbox.sessionKey,
-        resolvePath: resolveLocalPath,
-        async runCommand(options) {
-            return await sandbox.executeCommand(options);
-        },
-        async readFile(options) {
-            const buf = await sandbox.readFileBytes(options.path);
-            return buf === null ? null : bufferToStream(buf);
-        },
-        async writeFile(options) {
-            const buf = await streamToBuffer(options.content);
-            await sandbox.writeFiles([{ content: buf, path: options.path }]);
-        },
-    };
-}
-async function raceAbort(promise, signal) {
-    return await new Promise((resolve, reject) => {
-        const onAbort = () => {
-            reject(new DOMException("The operation was aborted.", "AbortError"));
-        };
-        if (signal.aborted) {
-            onAbort();
-            return;
-        }
-        signal.addEventListener("abort", onAbort, { once: true });
-        promise.then((value) => {
-            signal.removeEventListener("abort", onAbort);
-            resolve(value);
-        }, (error) => {
-            signal.removeEventListener("abort", onAbort);
-            reject(error);
-        });
-    });
-}
-function resolveLocalPath(path) {
-    if (path.startsWith("/")) {
-        return path;
-    }
-    return `${WORKSPACE_ROOT}/${path}`;
-}
-function resolveTemplateSnapshotPath(cacheDirectory, templateKey) {
-    return join(cacheDirectory, "local", "templates", `${templateKey}.json`);
-}
-function resolveSessionSnapshotPath(cacheDirectory, sessionKey) {
-    return join(cacheDirectory, "local", "sessions", `${sessionKey}.json`);
-}
-function createInitialFiles(snapshot) {
-    const files = {};
-    for (const entry of snapshot?.entries ?? []) {
-        if (entry.kind !== "file") {
-            continue;
-        }
-        files[entry.path] = Buffer.from(entry.contentBase64, "base64");
-    }
-    return files;
-}
-async function ensureLocalSandboxDirectories(filesystem) {
-    await filesystem.mkdir(WORKSPACE_ROOT, {
-        recursive: true,
-    });
-}
-async function restoreLocalSandboxDirectories(filesystem, entries) {
-    const directoryPaths = entries
-        .filter((entry) => entry.kind === "directory")
-        .map((entry) => entry.path)
-        .sort((left, right) => left.localeCompare(right));
-    for (const directoryPath of directoryPaths) {
-        if (directoryPath === WORKSPACE_ROOT) {
-            continue;
-        }
-        await filesystem.mkdir(directoryPath, {
-            recursive: true,
-        });
-    }
-}
-async function captureLocalSnapshot(input) {
-    const entries = [];
-    const paths = input.filesystem.getAllPaths().sort((left, right) => left.localeCompare(right));
-    for (const path of paths) {
-        const stat = await input.filesystem.stat(path);
-        if (stat.isSymbolicLink) {
-            continue;
-        }
-        if (stat.isDirectory) {
-            entries.push({ kind: "directory", path });
-            continue;
-        }
-        if (!stat.isFile) {
-            continue;
-        }
-        const content = await input.filesystem.readFileBuffer(path);
-        entries.push({ contentBase64: Buffer.from(content).toString("base64"), kind: "file", path });
-    }
-    return {
-        entries,
-        env: { ...input.sandbox.getEnv() },
-        version: LOCAL_SANDBOX_SNAPSHOT_VERSION,
-    };
-}
-async function readLocalSnapshot(snapshotPath) {
-    if (!(await doesPathExist(snapshotPath))) {
-        return null;
-    }
-    const snapshotJson = JSON.parse(await readFile(snapshotPath, "utf8"));
-    if (snapshotJson.version !== LOCAL_SANDBOX_SNAPSHOT_VERSION) {
-        return null;
-    }
-    return snapshotJson;
-}
-async function writeLocalSnapshot(snapshotPath, snapshot) {
-    await mkdir(dirname(snapshotPath), { recursive: true });
-    await writeFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}\n`);
-}
-async function doesPathExist(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function getLocalSnapshotPath(metadata) {
-    const snapshotPath = metadata?.snapshotPath;
-    return typeof snapshotPath === "string" ? snapshotPath : undefined;
-}
+import{dirname,join}from"node:path";import{access,mkdir,readFile,writeFile}from"node:fs/promises";import{resolveSandboxCacheDirectory}from"#internal/application/paths.js";import{shellQuote}from"#execution/sandbox/shell-quote.js";import{SandboxTemplateNotProvisionedError}from"#public/definitions/sandbox-backend.js";import{WORKSPACE_ROOT}from"#runtime/workspace/types.js";import{buildSandboxSession}from"#execution/sandbox/session.js";import{bufferToStream,streamToBuffer}from"#execution/sandbox/stream-utils.js";var LOCAL_SANDBOX_SNAPSHOT_VERSION=1;function createLocalSandboxBackend(e={}){return{name:`local`,async prewarm(e){let t=resolveTemplateSnapshotPath(resolveSandboxCacheDirectory(e.runtimeContext.appRoot),e.templateKey);if(await doesPathExist(t))return;let n=await createBashSandbox({sessionKey:e.templateKey,snapshotPath:t}),r=buildSandboxSession(createLocalInternalSandboxSession(n));try{e.bootstrap!==void 0&&await e.bootstrap({use:async()=>r});for(let t of e.seedFiles)typeof t.content==`string`?await r.writeTextFile({content:t.content,path:t.path}):await r.writeBinaryFile({content:t.content,path:t.path});if(await n.captureSnapshot()===null)throw Error(`Failed to capture local sandbox template state for "${e.templateKey}".`)}finally{await n.dispose()}},async create(e){let t=resolveSandboxCacheDirectory(e.runtimeContext.appRoot),n=await readLocalSnapshot(resolveTemplateSnapshotPath(t,e.templateKey));if(n===null)throw new SandboxTemplateNotProvisionedError({backendName:`local`,templateKey:e.templateKey});let r=getLocalSnapshotPath(e.existingMetadata)??resolveSessionSnapshotPath(t,e.sessionKey);return await doesPathExist(r)||await writeLocalSnapshot(r,n),createHandle(await createBashSandbox({sessionKey:e.sessionKey,snapshotPath:r}))}}}async function createBashSandbox(t){let{Bash:n,InMemoryFs:r}=await import(`#compiled/just-bash/index.js`),i=await readLocalSnapshot(t.snapshotPath),a=new r(createInitialFiles(i));await ensureLocalSandboxDirectories(a),await restoreLocalSandboxDirectories(a,i?.entries??[]);let o=new n({cwd:WORKSPACE_ROOT,env:i?.env,fs:a,network:{dangerouslyAllowFullInternetAccess:!0}});return{async captureSnapshot(){let e=await captureLocalSnapshot({filesystem:a,sandbox:o});return await writeLocalSnapshot(t.snapshotPath,e),{snapshotPath:t.snapshotPath}},async dispose(){await o.dispose?.()},async executeCommand(e){if(e.abortSignal?.aborted)throw new DOMException(`The operation was aborted.`,`AbortError`);let t=e.workingDirectory===void 0?e.command:`( cd ${shellQuote(e.workingDirectory)} && ${e.command} )`,n=o.exec(t),r=e.abortSignal?await raceAbort(n,e.abortSignal):await n;return{exitCode:r.exitCode,stderr:r.stderr,stdout:r.stdout}},async readFileBytes(e){let t;try{t=await a.readFileBuffer(e)}catch{return null}return Buffer.from(t)},async readFileText(e){let t;try{t=await a.readFileBuffer(e)}catch{return null}return new TextDecoder(`utf-8`,{fatal:!0}).decode(t)},sessionKey:t.sessionKey,snapshotPath:t.snapshotPath,async writeFiles(t){for(let n of t){let t=dirname(n.path);await a.mkdir(t,{recursive:!0}),await a.writeFile(n.path,n.content)}}}}function createHandle(e){let t=buildSandboxSession(createLocalInternalSandboxSession(e));return{session:t,useSessionFn:async()=>t,async captureState(){return{backendName:`local`,metadata:await e.captureSnapshot()??{},sessionKey:e.sessionKey}},async dispose(){await e.dispose()}}}function createLocalInternalSandboxSession(e){return{id:e.sessionKey,resolvePath:resolveLocalPath,async runCommand(t){return await e.executeCommand(t)},async readFile(t){let n=await e.readFileBytes(t.path);return n===null?null:bufferToStream(n)},async writeFile(t){let n=await streamToBuffer(t.content);await e.writeFiles([{content:n,path:t.path}])}}}async function raceAbort(e,t){return await new Promise((n,r)=>{let onAbort=()=>{r(new DOMException(`The operation was aborted.`,`AbortError`))};if(t.aborted){onAbort();return}t.addEventListener(`abort`,onAbort,{once:!0}),e.then(e=>{t.removeEventListener(`abort`,onAbort),n(e)},e=>{t.removeEventListener(`abort`,onAbort),r(e)})})}function resolveLocalPath(e){return e.startsWith(`/`)?e:`${WORKSPACE_ROOT}/${e}`}function resolveTemplateSnapshotPath(e,n){return join(e,`local`,`templates`,`${n}.json`)}function resolveSessionSnapshotPath(e,n){return join(e,`local`,`sessions`,`${n}.json`)}function createInitialFiles(e){let t={};for(let n of e?.entries??[])n.kind===`file`&&(t[n.path]=Buffer.from(n.contentBase64,`base64`));return t}async function ensureLocalSandboxDirectories(e){await e.mkdir(WORKSPACE_ROOT,{recursive:!0})}async function restoreLocalSandboxDirectories(e,t){let n=t.filter(e=>e.kind===`directory`).map(e=>e.path).sort((e,t)=>e.localeCompare(t));for(let t of n)t!==WORKSPACE_ROOT&&await e.mkdir(t,{recursive:!0})}async function captureLocalSnapshot(e){let t=[],n=e.filesystem.getAllPaths().sort((e,t)=>e.localeCompare(t));for(let r of n){let n=await e.filesystem.stat(r);if(n.isSymbolicLink)continue;if(n.isDirectory){t.push({kind:`directory`,path:r});continue}if(!n.isFile)continue;let i=await e.filesystem.readFileBuffer(r);t.push({contentBase64:Buffer.from(i).toString(`base64`),kind:`file`,path:r})}return{entries:t,env:{...e.sandbox.getEnv()},version:LOCAL_SANDBOX_SNAPSHOT_VERSION}}async function readLocalSnapshot(e){if(!await doesPathExist(e))return null;let t=JSON.parse(await readFile(e,`utf8`));return t.version===LOCAL_SANDBOX_SNAPSHOT_VERSION?t:null}async function writeLocalSnapshot(t,n){await mkdir(dirname(t),{recursive:!0}),await writeFile(t,`${JSON.stringify(n,null,2)}\n`)}async function doesPathExist(e){try{return await access(e),!0}catch{return!1}}function getLocalSnapshotPath(e){let t=e?.snapshotPath;return typeof t==`string`?t:void 0}export{createLocalSandboxBackend};