agent-orcha 0.0.5 → 0.0.7

package/dist/lib/sandbox/sandbox-browser.js

@@ -0,0 +1,303 @@
+import { z } from 'zod';
+import { tool } from "../types/tool-factory.js";
+import { htmlToMarkdown } from "./html-to-markdown.js";
+import { CDPClient } from "./cdp-client.js";
+import { PageReadiness } from "./page-readiness.js";
+/** Hard cap on content() output to prevent 50K+ char dumps blowing up context. */
+const CONTENT_MAX_CHARS = 15_000;
+export function createBrowserTools(config) {
+    const cdpUrl = config.browserCdpUrl;
+    let client = null;
+    let readiness = null;
+    async function getReady() {
+        if (client?.connected && readiness) {
+            return { cdp: client, ready: readiness };
+        }
+        client = new CDPClient();
+        await client.connect(cdpUrl);
+        readiness = new PageReadiness(client);
+        await readiness.attach();
+        return { cdp: client, ready: readiness };
+    }
+    function errorResult(error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return JSON.stringify({ error: msg });
+    }
+    // -- observe: cheap text snapshot of the page (primary verification tool) --
+    const observe = tool(async () => {
+        try {
+            const { ready } = await getReady();
+            const snapshot = await ready.observe();
+            return JSON.stringify(snapshot);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_observe',
+        description: 'Text snapshot of current page: URL, title, headings, textExcerpt (first 2000 chars of visible text), interactive elements with refs. Check textExcerpt first — it often has what you need.',
+        schema: z.object({}),
+    });
+    // -- navigate: go to URL, wait for readiness, return observe snapshot --
+    const navigate = tool(async ({ url }) => {
+        try {
+            const { cdp, ready } = await getReady();
+            ready.resetForNavigation();
+            await cdp.send('Page.navigate', { url });
+            await ready.waitForReady(config.commandTimeout);
+            const snapshot = await ready.observe();
+            return JSON.stringify(snapshot);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_navigate',
+        description: 'Navigate to URL. Waits for load+idle. Returns text snapshot with textExcerpt and interactive elements.',
+        schema: z.object({
+            url: z.string().describe('The URL to navigate to'),
+        }),
+    });
+    // -- screenshot: expensive visual capture, use only when text observation is insufficient --
+    const screenshot = tool(async () => {
+        try {
+            const { cdp } = await getReady();
+            const result = await cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 75 });
+            const data = result.data;
+            return [
+                { type: 'image', data, mediaType: 'image/jpeg' },
+                { type: 'text', text: 'Screenshot captured.' },
+            ];
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_screenshot',
+        description: 'JPEG screenshot. Expensive — only when observe/content insufficient (CAPTCHAs, charts).',
+        schema: z.object({}),
+    });
+    // -- content: full page or element as markdown --
+    const content = tool(async ({ selector }) => {
+        try {
+            const { cdp } = await getReady();
+            const expression = selector
+                ? `(() => { const el = document.querySelector(${JSON.stringify(selector)}); return el ? el.outerHTML : null; })()`
+                : 'document.documentElement.outerHTML';
+            const result = await cdp.send('Runtime.evaluate', { expression });
+            const html = result.result?.value;
+            if (!html) {
+                return JSON.stringify({ error: selector ? `Element not found: ${selector}` : 'No content' });
+            }
+            const markdown = htmlToMarkdown(html, { includeNavigation: !!selector, includeInteractiveElements: true, includeImages: true });
+            const maxChars = Math.min(CONTENT_MAX_CHARS, config.maxOutputChars);
+            let output = JSON.stringify({ content: markdown, selector: selector ?? null });
+            if (output.length > maxChars) {
+                const truncated = markdown.substring(0, maxChars);
+                output = JSON.stringify({ content: truncated, truncated: true, selector: selector ?? null });
+            }
+            return output;
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_content',
+        description: 'Page content as markdown (capped at 15K chars). Use a CSS selector to target a specific section instead of fetching the full page.',
+        schema: z.object({
+            selector: z
+                .string()
+                .optional()
+                .describe('CSS selector to extract a specific element (optional, defaults to full page)'),
+        }),
+    });
+    // -- evaluate: run arbitrary JS, report side effects --
+    const evaluate = tool(async ({ expression }) => {
+        try {
+            const { cdp, ready } = await getReady();
+            const preUrl = await cdp.send('Runtime.evaluate', {
+                expression: 'location.href',
+                returnByValue: true,
+            });
+            const preUrlValue = preUrl.result?.value;
+            ready.resetNetworkFlag();
+            const result = await cdp.send('Runtime.evaluate', {
+                expression,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            const val = result.result;
+            if (val?.subtype === 'error' || result.exceptionDetails) {
+                const errMsg = result.exceptionDetails?.exception?.description ??
+                    val?.description ??
+                    'Evaluation error';
+                return JSON.stringify({ error: errMsg });
+            }
+            await ready.waitForSettle(300);
+            const postUrl = await cdp.send('Runtime.evaluate', {
+                expression: 'location.href',
+                returnByValue: true,
+            });
+            const postUrlValue = postUrl.result?.value;
+            const sideEffects = {};
+            if (preUrlValue !== postUrlValue) {
+                sideEffects.urlChanged = { from: preUrlValue, to: postUrlValue };
+            }
+            if (ready.hadNetworkActivity()) {
+                sideEffects.networkTriggered = true;
+            }
+            return JSON.stringify({
+                result: val?.value ?? null,
+                type: val?.type ?? 'undefined',
+                ...(Object.keys(sideEffects).length > 0 ? { sideEffects } : {}),
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_evaluate',
+        description: 'Run JavaScript in browser. Returns result + side effects. Prefer click/type for interactions.',
+        schema: z.object({
+            expression: z.string().describe('JavaScript expression to evaluate in the page'),
+        }),
+    });
+    // -- click: find element, scroll, click, return lightweight result --
+    const click = tool(async ({ ref, text }) => {
+        try {
+            const { cdp, ready } = await getReady();
+            // Resolve ref (e.g. "e3") to CSS selector
+            const selector = ref ? ready.resolveRef(ref) : undefined;
+            const findExpr = selector
+                ? `(() => {
+              const el = document.querySelector(${JSON.stringify(selector)});
+              if (!el) return { error: 'Element not found: ' + ${JSON.stringify(ref)} };
+              return { found: true, tag: el.tagName.toLowerCase(), text: (el.textContent||'').trim().substring(0,40) };
+            })()`
+                : `(() => {
+              const searchText = ${JSON.stringify(text ?? '')};
+              const clickable = document.querySelectorAll('a, button, [role="button"], input[type="submit"], input[type="button"], [onclick], [tabindex]');
+              for (const el of clickable) {
+                if (el.offsetParent === null) continue;
+                if (el.textContent && el.textContent.trim().toLowerCase().includes(searchText.toLowerCase())) {
+                  return { found: true, tag: el.tagName.toLowerCase(), text: (el.textContent||'').trim().substring(0,40) };
+                }
+              }
+              return { error: 'No clickable element found containing text: ' + searchText };
+            })()`;
+            const findResult = await cdp.send('Runtime.evaluate', {
+                expression: findExpr,
+                returnByValue: true,
+            });
+            const found = findResult.result?.value;
+            if (found?.error)
+                return JSON.stringify(found);
+            const preUrl = await cdp.send('Runtime.evaluate', {
+                expression: 'location.href',
+                returnByValue: true,
+            });
+            const clickExpr = selector
+                ? `(() => {
+              const el = document.querySelector(${JSON.stringify(selector)});
+              el.scrollIntoView({ block: 'center', behavior: 'instant' });
+              el.click();
+              return true;
+            })()`
+                : `(() => {
+              const searchText = ${JSON.stringify(text ?? '')};
+              const clickable = document.querySelectorAll('a, button, [role="button"], input[type="submit"], input[type="button"], [onclick], [tabindex]');
+              for (const el of clickable) {
+                if (el.offsetParent === null) continue;
+                if (el.textContent && el.textContent.trim().toLowerCase().includes(searchText.toLowerCase())) {
+                  el.scrollIntoView({ block: 'center', behavior: 'instant' });
+                  el.click();
+                  return true;
+                }
+              }
+              return false;
+            })()`;
+            ready.resetNetworkFlag();
+            await cdp.send('Runtime.evaluate', {
+                expression: clickExpr,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            await ready.waitForSettle(500);
+            const postUrl = await cdp.send('Runtime.evaluate', {
+                expression: 'location.href',
+                returnByValue: true,
+            });
+            const preUrlVal = preUrl.result?.value;
+            const postUrlVal = postUrl.result?.value;
+            const navigated = preUrlVal !== postUrlVal;
+            if (navigated) {
+                ready.resetForNavigation();
+                await ready.waitForReady(config.commandTimeout);
+            }
+            const titleResult = await cdp.send('Runtime.evaluate', {
+                expression: 'document.title',
+                returnByValue: true,
+            });
+            return JSON.stringify({
+                clicked: found,
+                navigated,
+                url: postUrlVal,
+                title: titleResult.result?.value ?? '',
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_click',
+        description: 'Click an element by ref from observe output (e.g. "e3") or visible text. Scrolls into view, clicks, waits for effects.',
+        schema: z.object({
+            ref: z.string().optional().describe('Element ref from observe output (e.g. "e3")'),
+            text: z.string().optional().describe('Visible text to find and click'),
+        }),
+    });
+    // -- type: fill an input field --
+    const type_ = tool(async ({ ref, text, clear }) => {
+        try {
+            const { cdp, ready } = await getReady();
+            const selector = ready.resolveRef(ref);
+            const expr = `(() => {
+          const el = document.querySelector(${JSON.stringify(selector)});
+          if (!el) return { error: 'Element not found: ' + ${JSON.stringify(ref)} };
+          if (!('value' in el)) return { error: 'Element is not an input: ' + el.tagName };
+
+          el.scrollIntoView({ block: 'center', behavior: 'instant' });
+          el.focus();
+          ${clear !== false ? "el.value = '';" : ''}
+          el.value = ${JSON.stringify(text)};
+          el.dispatchEvent(new Event('input', { bubbles: true }));
+          el.dispatchEvent(new Event('change', { bubbles: true }));
+
+          return { typed: true, value: el.value };
+        })()`;
+            const result = await cdp.send('Runtime.evaluate', {
+                expression: expr,
+                returnByValue: true,
+                awaitPromise: true,
+            });
+            const val = result.result?.value;
+            if (val?.error)
+                return JSON.stringify(val);
+            await ready.waitForSettle(300);
+            return JSON.stringify(val);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    }, {
+        name: 'sandbox_browser_type',
+        description: 'Type text into an input/textarea by ref from observe output (e.g. "e5"). Handles focus and input/change events.',
+        schema: z.object({
+            ref: z.string().describe('Element ref from observe output (e.g. "e5")'),
+            text: z.string().describe('Text to type'),
+            clear: z.boolean().optional().describe('Clear first (default: true)'),
+        }),
+    });
+    return [observe, navigate, screenshot, content, evaluate, click, type_];
+}
+//# sourceMappingURL=sandbox-browser.js.map

package/dist/lib/sandbox/sandbox-browser.js.map

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

package/dist/lib/sandbox/sandbox-file.d.ts

@@ -0,0 +1,4 @@
+import type { StructuredTool } from '../types/llm-types.ts';
+import type { SandboxConfig } from './types.ts';
+export declare function createFileTools(config: SandboxConfig): StructuredTool[];
+//# sourceMappingURL=sandbox-file.d.ts.map

package/dist/lib/sandbox/sandbox-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-file.d.ts","sourceRoot":"","sources":["../../../lib/sandbox/sandbox-file.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA0BhD,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,EAAE,CAyKvE"}

package/dist/lib/sandbox/sandbox-file.js

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { tool } from "../types/tool-factory.js";
+import { z } from 'zod';
+const ALLOWED_ROOT = '/tmp';
+// On macOS, /tmp is a symlink to /private/tmp
+const REAL_ALLOWED_ROOT = existsSync(ALLOWED_ROOT) ? realpathSync(ALLOWED_ROOT) : ALLOWED_ROOT;
+function isUnderRoot(p) {
+    return (p.startsWith(ALLOWED_ROOT + '/') || p === ALLOWED_ROOT ||
+        p.startsWith(REAL_ALLOWED_ROOT + '/') || p === REAL_ALLOWED_ROOT);
+}
+function validatePath(rawPath) {
+    const resolved = resolve(ALLOWED_ROOT, rawPath);
+    if (!isUnderRoot(resolved)) {
+        throw new Error(`Path must be under ${ALLOWED_ROOT}. Got: ${rawPath}`);
+    }
+    // If the file exists, check the real path to prevent symlink escape
+    if (existsSync(resolved)) {
+        const real = realpathSync(resolved);
+        if (!isUnderRoot(real)) {
+            throw new Error(`Symlink escapes ${ALLOWED_ROOT}. Real path: ${real}`);
+        }
+    }
+    return resolved;
+}
+export function createFileTools(config) {
+    const readTool = tool(async ({ path }) => {
+        try {
+            const resolved = validatePath(path);
+            const raw = readFileSync(resolved, 'utf-8');
+            const lines = raw.split('\n');
+            const numbered = lines.map((line, i) => `${i + 1}\t${line}`).join('\n');
+            const truncated = numbered.length > config.maxOutputChars;
+            return JSON.stringify({
+                content: truncated ? numbered.substring(0, config.maxOutputChars) : numbered,
+                lines: lines.length,
+                size: raw.length,
+                ...(truncated && { truncated: true }),
+            });
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message });
+        }
+    }, {
+        name: 'sandbox_file_read',
+        description: 'Read a file from the sandbox filesystem. ' +
+            'Path must be under /tmp. Returns the file content as a string.',
+        schema: z.object({
+            path: z.string().describe('Absolute or relative path to the file (resolved under /tmp)'),
+        }),
+    });
+    const writeTool = tool(async ({ path, content }) => {
+        try {
+            const resolved = validatePath(path);
+            const created = !existsSync(resolved);
+            mkdirSync(dirname(resolved), { recursive: true });
+            writeFileSync(resolved, content, 'utf-8');
+            return JSON.stringify({
+                path: resolved,
+                size: content.length,
+                created,
+            });
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message });
+        }
+    }, {
+        name: 'sandbox_file_write',
+        description: 'Create or overwrite a file in the sandbox filesystem. ' +
+            'Path must be under /tmp. Parent directories are created automatically.',
+        schema: z.object({
+            path: z.string().describe('Absolute or relative path to the file (resolved under /tmp)'),
+            content: z.string().describe('The full content to write to the file'),
+        }),
+    });
+    const editTool = tool(async ({ path, old_string, new_string }) => {
+        try {
+            const resolved = validatePath(path);
+            const content = readFileSync(resolved, 'utf-8');
+            const occurrences = content.split(old_string).length - 1;
+            if (occurrences === 0) {
+                return JSON.stringify({ error: 'old_string not found in the file' });
+            }
+            if (occurrences > 1) {
+                return JSON.stringify({
+                    error: `old_string found ${occurrences} times — must be unique. Provide more surrounding context to match exactly once.`,
+                });
+            }
+            const updated = content.replace(old_string, new_string);
+            writeFileSync(resolved, updated, 'utf-8');
+            return JSON.stringify({ path: resolved, replacements: 1 });
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message });
+        }
+    }, {
+        name: 'sandbox_file_edit',
+        description: 'Find and replace a unique string in a file. ' +
+            'The old_string must appear exactly once in the file. ' +
+            'Use this for precise edits instead of rewriting the whole file.',
+        schema: z.object({
+            path: z.string().describe('Absolute or relative path to the file (resolved under /tmp)'),
+            old_string: z.string().describe('The exact string to find (must appear exactly once)'),
+            new_string: z.string().describe('The replacement string'),
+        }),
+    });
+    const insertLinesTool = tool(async ({ path, line, content, position }) => {
+        try {
+            const resolved = validatePath(path);
+            const fileContent = readFileSync(resolved, 'utf-8');
+            const lines = fileContent.split('\n');
+            if (line < 1 || line > lines.length) {
+                return JSON.stringify({ error: `Line ${line} out of range. File has ${lines.length} lines (1-indexed).` });
+            }
+            const newLines = content.split('\n');
+            const idx = position === 'before' ? line - 1 : line;
+            lines.splice(idx, 0, ...newLines);
+            writeFileSync(resolved, lines.join('\n'), 'utf-8');
+            return JSON.stringify({ path: resolved, insertedLines: newLines.length, atLine: idx + 1 });
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message });
+        }
+    }, {
+        name: 'sandbox_file_insert',
+        description: 'Insert lines before or after a specific line number in a file. ' +
+            'Line numbers are 1-indexed. Use sandbox_file_read first to see the file with line numbers.',
+        schema: z.object({
+            path: z.string().describe('Absolute or relative path to the file (resolved under /tmp)'),
+            line: z.number().int().min(1).describe('The line number to insert before or after (1-indexed)'),
+            content: z.string().describe('The content to insert (can be multiple lines)'),
+            position: z.enum(['before', 'after']).default('after').describe('Insert before or after the specified line'),
+        }),
+    });
+    const replaceLinesTool = tool(async ({ path, start_line, end_line, content }) => {
+        try {
+            const resolved = validatePath(path);
+            const fileContent = readFileSync(resolved, 'utf-8');
+            const lines = fileContent.split('\n');
+            if (start_line < 1 || start_line > lines.length) {
+                return JSON.stringify({ error: `start_line ${start_line} out of range. File has ${lines.length} lines (1-indexed).` });
+            }
+            if (end_line < start_line || end_line > lines.length) {
+                return JSON.stringify({ error: `end_line ${end_line} out of range. Must be >= start_line (${start_line}) and <= ${lines.length}.` });
+            }
+            const newLines = content.split('\n');
+            const removedCount = end_line - start_line + 1;
+            lines.splice(start_line - 1, removedCount, ...newLines);
+            writeFileSync(resolved, lines.join('\n'), 'utf-8');
+            return JSON.stringify({ path: resolved, removedLines: removedCount, insertedLines: newLines.length });
+        }
+        catch (err) {
+            return JSON.stringify({ error: err.message });
+        }
+    }, {
+        name: 'sandbox_file_replace_lines',
+        description: 'Replace a range of lines in a file with new content. ' +
+            'Line numbers are 1-indexed and inclusive. Use sandbox_file_read first to see the file with line numbers.',
+        schema: z.object({
+            path: z.string().describe('Absolute or relative path to the file (resolved under /tmp)'),
+            start_line: z.number().int().min(1).describe('First line to replace (1-indexed, inclusive)'),
+            end_line: z.number().int().min(1).describe('Last line to replace (1-indexed, inclusive)'),
+            content: z.string().describe('The replacement content (can be fewer or more lines than the range)'),
+        }),
+    });
+    return [readTool, writeTool, editTool, insertLinesTool, replaceLinesTool];
+}
+//# sourceMappingURL=sandbox-file.js.map

package/dist/lib/sandbox/sandbox-file.js.map

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

package/dist/lib/sandbox/sandbox-shell.d.ts

@@ -0,0 +1,4 @@
+import type { StructuredTool } from '../types/llm-types.ts';
+import type { SandboxConfig } from './types.ts';
+export declare function createSandboxShellTool(config: SandboxConfig): StructuredTool;
+//# sourceMappingURL=sandbox-shell.d.ts.map

package/dist/lib/sandbox/sandbox-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-shell.d.ts","sourceRoot":"","sources":["../../../lib/sandbox/sandbox-shell.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAC;AAuB7D,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAgD5E"}

package/dist/lib/sandbox/sandbox-shell.js

@@ -0,0 +1,93 @@
+import { execFile } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { tool } from "../types/tool-factory.js";
+import { z } from 'zod';
+const SANDBOX_UID = 10000;
+const SANDBOX_GID = 10000;
+function isRunningInContainer() {
+    // Docker creates this file
+    if (existsSync('/.dockerenv'))
+        return true;
+    // Podman and other OCI runtimes use /run/.containerenv
+    if (existsSync('/run/.containerenv'))
+        return true;
+    // Check cgroup for container markers (docker, containerd, lxc, podman)
+    try {
+        const cgroup = readFileSync('/proc/1/cgroup', 'utf-8');
+        if (/docker|containerd|kubepods|lxc|podman/.test(cgroup))
+            return true;
+    }
+    catch {
+        // /proc/1/cgroup may not exist (e.g., macOS)
+    }
+    return false;
+}
+export function createSandboxShellTool(config) {
+    const inDocker = isRunningInContainer();
+    const allowUnsafe = process.env['ALLOW_UNSAFE_HOST_EXECUTION'] === 'true';
+    return tool(async ({ command, timeout }) => {
+        if (!inDocker && !allowUnsafe) {
+            return JSON.stringify({
+                stdout: '',
+                stderr: '',
+                exitCode: -1,
+                error: 'Shell execution is disabled outside Docker. Set ALLOW_UNSAFE_HOST_EXECUTION=true to enable.',
+            });
+        }
+        const effectiveTimeout = timeout
+            ? Math.min(timeout, config.commandTimeout)
+            : config.commandTimeout;
+        const result = await executeShell(command, effectiveTimeout, inDocker);
+        let output = JSON.stringify(result);
+        if (output.length > config.maxOutputChars) {
+            const truncated = {
+                ...result,
+                stdout: result.stdout.substring(0, config.maxOutputChars),
+                _truncated: true,
+            };
+            output = JSON.stringify(truncated);
+        }
+        return output;
+    }, {
+        name: 'sandbox_shell',
+        description: 'Execute a shell command on the host system. ' +
+            'Commands run in an isolated context with limited permissions. ' +
+            'Returns JSON with stdout, stderr, exitCode, and error fields.',
+        schema: z.object({
+            command: z.string().describe('The shell command to execute'),
+            timeout: z
+                .number()
+                .optional()
+                .describe('Execution timeout in milliseconds (capped by sandbox config)'),
+        }),
+    });
+}
+function executeShell(command, timeout, inDocker) {
+    return new Promise((resolve) => {
+        const options = {
+            timeout,
+            maxBuffer: 10 * 1024 * 1024,
+            cwd: '/tmp',
+        };
+        if (inDocker) {
+            options.uid = SANDBOX_UID;
+            options.gid = SANDBOX_GID;
+        }
+        execFile('/bin/sh', ['-c', command], options, (error, stdout, stderr) => {
+            let exitCode = 0;
+            if (error && 'code' in error && typeof error.code === 'number') {
+                exitCode = error.code;
+            }
+            else if (error) {
+                exitCode = 1;
+            }
+            resolve({
+                stdout: stdout ?? '',
+                stderr: stderr ?? '',
+                exitCode,
+                ...(error && typeof error.code !== 'number' ? { error: error.message } : {}),
+            });
+        });
+    });
+}
+//# sourceMappingURL=sandbox-shell.js.map

package/dist/lib/sandbox/sandbox-shell.js.map

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

package/dist/lib/sandbox/sandbox-web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-web.d.ts","sourceRoot":"","sources":["../../../lib/sandbox/sandbox-web.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqBhD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CAwG/E;AAED,wBAAgB,0BAA0B,IAAI,cAAc,CAsE3D"}
+{"version":3,"file":"sandbox-web.d.ts","sourceRoot":"","sources":["../../../lib/sandbox/sandbox-web.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiDhD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,CA0F/E;AAED,wBAAgB,0BAA0B,IAAI,cAAc,CAsE3D"}