network-ai 5.10.2 → 5.11.0

package/dist/esm/lib/agent-runtime.js

@@ -0,0 +1,818 @@
+"use strict";
+/**
+ * Agent Runtime — Sandboxed execution environment for AI agents
+ *
+ * Provides controlled access to shell commands, file system, and system
+ * resources with policy enforcement, approval gates, and audit logging.
+ *
+ * Components:
+ *   - SandboxPolicy — defines what agents are allowed to do
+ *   - ShellExecutor — spawns child processes within policy constraints
+ *   - FileAccessor — scoped file read/write with traversal protection
+ *   - ApprovalGate — human-in-the-loop approval for sensitive operations
+ *   - AgentRuntime — unified facade combining all components
+ *
+ * @module AgentRuntime
+ * @version 1.0.0
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeExecutionError = exports.RuntimeApprovalError = exports.RuntimePolicyError = exports.AgentRuntime = exports.ApprovalGate = exports.FileAccessor = exports.ShellExecutor = exports.SandboxPolicy = exports.SourceProtectionError = void 0;
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const events_1 = require("events");
+const security_1 = require("../security");
+// ============================================================================
+// ERRORS
+// ============================================================================
+/**
+ * Thrown when an agent attempts to access source code files or directories
+ * while `sourceProtection` is enabled on the sandbox policy.
+ */
+class SourceProtectionError extends Error {
+    /** The path that was blocked */
+    blockedPath;
+    /** The agent that attempted access */
+    agentId;
+    constructor(blockedPath, agentId) {
+        super(`Source protection: access to '${blockedPath}' is blocked for agent '${agentId}'`);
+        this.name = 'SourceProtectionError';
+        this.blockedPath = blockedPath;
+        this.agentId = agentId;
+    }
+}
+exports.SourceProtectionError = SourceProtectionError;
+// ============================================================================
+// COMMAND PARSING
+// ============================================================================
+/**
+ * Shell metacharacters that enable command chaining, substitution, or
+ * redirection. Any of these appearing OUTSIDE of quotes turns a scoped
+ * allowlist entry (e.g. `git *`) into arbitrary execution and must be
+ * rejected (GHSA-qw6v-5fcf-5666).
+ */
+const SHELL_METACHARACTERS = new Set([
+    ';', '&', '|', '$', '`', '(', ')', '<', '>', '{', '}', '\n', '\r',
+]);
+/**
+ * Tokenize a command string into an argv array, honoring single and double
+ * quotes, and report whether any shell metacharacter appears OUTSIDE of quotes.
+ *
+ * Commands are executed with `shell: false`, so no shell ever interprets the
+ * result — quoted metacharacters are therefore safe, literal data. Unquoted
+ * metacharacters indicate an attempt to chain, substitute, or redirect commands
+ * and cause the command to be rejected before it can run.
+ *
+ * @param command - Raw command string to parse.
+ * @returns Parsed argv plus flags for unquoted metacharacters and malformed quoting.
+ */
+function parseCommandLine(command) {
+    const argv = [];
+    let current = '';
+    let tokenOpen = false;
+    let quote = null;
+    let hasUnquotedMetacharacter = false;
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else {
+                current += ch;
+            }
+            tokenOpen = true;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            tokenOpen = true;
+            continue;
+        }
+        if (ch === ' ' || ch === '\t') {
+            if (tokenOpen) {
+                argv.push(current);
+                current = '';
+                tokenOpen = false;
+            }
+            continue;
+        }
+        if (SHELL_METACHARACTERS.has(ch)) {
+            // Unquoted metacharacter — reject the whole command. Do not include it
+            // in argv so the result can never be silently executed.
+            hasUnquotedMetacharacter = true;
+            continue;
+        }
+        current += ch;
+        tokenOpen = true;
+    }
+    if (tokenOpen)
+        argv.push(current);
+    return { argv, hasUnquotedMetacharacter, unterminatedQuote: quote !== null };
+}
+// ============================================================================
+// SANDBOX POLICY
+// ============================================================================
+const DEFAULT_POLICY = {
+    allowedCommands: [],
+    blockedCommands: [
+        'rm -rf /',
+        'rm -rf /*',
+        'rmdir /s /q C:\\',
+        'format *',
+        'mkfs*',
+        'dd if=*',
+        ':(){:|:&};:', // fork bomb
+        'shutdown*',
+        'reboot*',
+        'halt*',
+        'init 0',
+        'init 6',
+        'del /f /s /q C:\\*',
+        'reg delete*',
+        'net user*',
+        'net localgroup*',
+    ],
+    allowedPaths: ['.'],
+    blockedPaths: [],
+    maxConcurrentProcesses: 5,
+    defaultTimeoutMs: 30_000,
+    defaultMaxOutputBytes: 1_048_576,
+    approvalRequired: [
+        'rm *',
+        'del *',
+        'rmdir *',
+        'git push*',
+        'git reset --hard*',
+        'npm publish*',
+        'docker *',
+        'kubectl *',
+    ],
+    autoApproveReads: true,
+};
+/**
+ * Sandbox policy engine — determines what agents are allowed to do.
+ *
+ * @example
+ * ```typescript
+ * const policy = new SandboxPolicy({
+ *   basePath: '/project',
+ *   allowedCommands: ['npm *', 'node *', 'git status'],
+ * });
+ * policy.isCommandAllowed('npm test'); // true
+ * policy.isCommandAllowed('rm -rf /'); // false
+ * ```
+ */
+class SandboxPolicy {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_POLICY, ...config };
+        this.config.basePath = (0, path_1.resolve)(this.config.basePath);
+    }
+    /** Check if a command matches the policy's allowed list and isn't blocked */
+    isCommandAllowed(command) {
+        const trimmed = command.trim();
+        if (!trimmed)
+            return false;
+        // Reject shell metacharacters and malformed quoting BEFORE pattern matching.
+        // Commands run with `shell: false`, but a scoped allowlist entry such as
+        // `git *` must never be escapable into arbitrary execution via `;`, `|`,
+        // `&&`, `$(...)`, backticks, redirection, or newlines (GHSA-qw6v-5fcf-5666).
+        const parsed = parseCommandLine(trimmed);
+        if (parsed.hasUnquotedMetacharacter || parsed.unterminatedQuote || parsed.argv.length === 0) {
+            return false;
+        }
+        // Check blocked first (always wins)
+        if (this.matchesAny(trimmed, this.config.blockedCommands))
+            return false;
+        // If no allowedCommands, deny all
+        if (this.config.allowedCommands.length === 0)
+            return false;
+        // Check allowed
+        return this.matchesAny(trimmed, this.config.allowedCommands);
+    }
+    /**
+     * Tokenize a command into an argv array suitable for `shell: false`
+     * execution. Returns `null` for any command that contains unquoted shell
+     * metacharacters or malformed quoting — i.e. exactly the inputs that
+     * {@link isCommandAllowed} rejects. Quoted metacharacters are preserved as
+     * literal data within their token.
+     *
+     * @param command - Raw command string to tokenize.
+     * @returns The argv array, or `null` if the command is unsafe to execute.
+     */
+    tokenizeCommand(command) {
+        const parsed = parseCommandLine(command.trim());
+        if (parsed.hasUnquotedMetacharacter || parsed.unterminatedQuote || parsed.argv.length === 0) {
+            return null;
+        }
+        return parsed.argv;
+    }
+    /** Check if a command requires human approval */
+    requiresApproval(command) {
+        return this.matchesAny(command.trim(), this.config.approvalRequired);
+    }
+    /** Assess risk level of a command */
+    assessRisk(command) {
+        const trimmed = command.trim().toLowerCase();
+        const highRisk = ['rm ', 'del ', 'format', 'drop ', 'delete ', 'truncate ', 'git push', 'git reset', 'docker', 'kubectl'];
+        const medRisk = ['git ', 'npm ', 'pip ', 'mv ', 'move ', 'cp ', 'copy ', 'chmod ', 'chown '];
+        if (highRisk.some(p => trimmed.startsWith(p) || trimmed.includes(' ' + p)))
+            return 'high';
+        if (medRisk.some(p => trimmed.startsWith(p) || trimmed.includes(' ' + p)))
+            return 'medium';
+        return 'low';
+    }
+    /** Validate that a file path is within allowed scope */
+    isPathAllowed(filePath) {
+        const normalized = this.resolvePath(filePath);
+        if (!normalized)
+            return false;
+        // Check blocked paths
+        for (const blocked of this.config.blockedPaths) {
+            const blockedAbs = (0, path_1.resolve)(this.config.basePath, blocked);
+            if (normalized.startsWith(blockedAbs))
+                return false;
+        }
+        // Check allowed paths
+        for (const allowed of this.config.allowedPaths) {
+            const allowedAbs = (0, path_1.resolve)(this.config.basePath, allowed);
+            if (normalized.startsWith(allowedAbs))
+                return true;
+        }
+        return false;
+    }
+    /** Resolve and validate a path against basePath (returns null if traversal detected) */
+    resolvePath(filePath) {
+        const normalized = (0, path_1.normalize)(filePath);
+        const absolute = (0, path_1.isAbsolute)(normalized)
+            ? normalized
+            : (0, path_1.join)(this.config.basePath, normalized);
+        const resolved = (0, path_1.resolve)(absolute);
+        // Traversal check
+        if (!resolved.startsWith(this.config.basePath))
+            return null;
+        return resolved;
+    }
+    /** Get a copy of the current policy config */
+    getConfig() {
+        return { ...this.config };
+    }
+    /** Update allowed commands */
+    allowCommand(pattern) {
+        if (!this.config.allowedCommands.includes(pattern)) {
+            this.config.allowedCommands.push(pattern);
+        }
+    }
+    /** Remove an allowed command pattern */
+    disallowCommand(pattern) {
+        this.config.allowedCommands = this.config.allowedCommands.filter(c => c !== pattern);
+    }
+    /** Update allowed paths */
+    allowPath(path) {
+        if (!this.config.allowedPaths.includes(path)) {
+            this.config.allowedPaths.push(path);
+        }
+    }
+    /** Block a path */
+    blockPath(path) {
+        if (!this.config.blockedPaths.includes(path)) {
+            this.config.blockedPaths.push(path);
+        }
+    }
+    get basePath() { return this.config.basePath; }
+    get maxConcurrentProcesses() { return this.config.maxConcurrentProcesses; }
+    get defaultTimeoutMs() { return this.config.defaultTimeoutMs; }
+    get defaultMaxOutputBytes() { return this.config.defaultMaxOutputBytes; }
+    get autoApproveReads() { return this.config.autoApproveReads; }
+    /** Simple glob matching: supports * as wildcard */
+    matchesAny(value, patterns) {
+        return patterns.some(pattern => this.globMatch(pattern, value));
+    }
+    /** Match a simple glob pattern against a string */
+    globMatch(pattern, value) {
+        // Escape regex special chars except *
+        const regexStr = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*/g, '.*');
+        return new RegExp(`^${regexStr}$`, 'i').test(value);
+    }
+}
+exports.SandboxPolicy = SandboxPolicy;
+// ============================================================================
+// SHELL EXECUTOR
+// ============================================================================
+/**
+ * Sandboxed shell command executor with timeout, output limits, and
+ * concurrent process tracking.
+ *
+ * @example
+ * ```typescript
+ * const executor = new ShellExecutor(policy);
+ * const result = await executor.execute('npm test', { agentId: 'tester' });
+ * console.log(result.exitCode, result.stdout);
+ * ```
+ */
+class ShellExecutor {
+    policy;
+    activeProcesses = 0;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /** Execute a shell command within policy constraints */
+    async execute(command, opts = {}) {
+        // Policy check
+        if (!this.policy.isCommandAllowed(command)) {
+            throw new RuntimePolicyError(`Command blocked by policy: ${command}`);
+        }
+        // Concurrency check
+        if (this.activeProcesses >= this.policy.maxConcurrentProcesses) {
+            throw new RuntimePolicyError(`Concurrency limit reached (${this.policy.maxConcurrentProcesses} max)`);
+        }
+        const cwd = opts.cwd
+            ? (this.policy.resolvePath(opts.cwd) ?? this.policy.basePath)
+            : this.policy.basePath;
+        const timeoutMs = opts.timeoutMs ?? this.policy.defaultTimeoutMs;
+        const maxBytes = opts.maxOutputBytes ?? this.policy.defaultMaxOutputBytes;
+        this.activeProcesses++;
+        try {
+            return await this.spawnCommand(command, cwd, timeoutMs, maxBytes, opts.env);
+        }
+        finally {
+            this.activeProcesses--;
+        }
+    }
+    /** Get the number of currently running processes */
+    get running() { return this.activeProcesses; }
+    spawnCommand(command, cwd, timeoutMs, maxBytes, env) {
+        return new Promise((resolvePromise, reject) => {
+            // Execute with `shell: false` using a parsed argv. The command was already
+            // validated by `isCommandAllowed`, but we re-tokenize here as the single
+            // source of truth for what actually runs — no string is ever handed to a
+            // shell, so metacharacters cannot be interpreted (GHSA-qw6v-5fcf-5666).
+            const argv = this.policy.tokenizeCommand(command);
+            if (!argv || argv.length === 0) {
+                reject(new RuntimePolicyError(`Command rejected — shell metacharacters are not permitted: ${command}`));
+                return;
+            }
+            const file = argv[0];
+            const args = argv.slice(1);
+            const child = (0, child_process_1.spawn)(file, args, {
+                cwd,
+                env: env ? { ...process.env, ...env } : process.env,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+                shell: false,
+            });
+            let stdout = '';
+            let stderr = '';
+            let totalBytes = 0;
+            let timedOut = false;
+            let truncated = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                setTimeout(() => { if (!child.killed)
+                    child.kill('SIGKILL'); }, 2000);
+            }, timeoutMs);
+            child.stdout?.on('data', (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes <= maxBytes) {
+                    stdout += chunk.toString();
+                }
+                else if (!truncated) {
+                    truncated = true;
+                    stdout += '\n[OUTPUT TRUNCATED — exceeded limit]';
+                    child.kill('SIGTERM');
+                }
+            });
+            child.stderr?.on('data', (chunk) => {
+                totalBytes += chunk.length;
+                if (totalBytes <= maxBytes) {
+                    stderr += chunk.toString();
+                }
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                resolvePromise({
+                    exitCode: code ?? (timedOut ? 124 : 1),
+                    stdout,
+                    stderr,
+                    durationMs: Date.now() - startTime,
+                    timedOut,
+                    truncated,
+                });
+            });
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                reject(new RuntimeExecutionError(`Failed to spawn: ${err.message}`));
+            });
+            const startTime = Date.now();
+        });
+    }
+}
+exports.ShellExecutor = ShellExecutor;
+// ============================================================================
+// FILE ACCESSOR
+// ============================================================================
+/**
+ * Policy-scoped file system accessor. All paths are validated against
+ * the sandbox policy before any I/O.
+ *
+ * **Error contract:** All public methods (`read`, `write`, `list`) return a
+ * `{success: boolean, ...}` result object — they never throw. All access-denied
+ * paths (path traversal, out-of-scope under `sourceProtection`, policy-blocked
+ * reads/writes, and `SourceProtectionError`) are caught at the method boundary
+ * and converted to `{success: false, error: <message>}`. The `error` field
+ * contains a short description without leaking internal path details.
+ *
+ * @example
+ * ```typescript
+ * const files = new FileAccessor(policy);
+ * const result = await files.read('src/index.ts', 'reader-agent');
+ * ```
+ */
+class FileAccessor {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /**
+     * Checks whether the resolved absolute path is blocked by source protection.
+     * Throws SourceProtectionError if access is denied.
+     */
+    checkSourceProtection(resolvedPath, agentId) {
+        const cfg = this.policy.getConfig();
+        if (!cfg.sourceProtection)
+            return;
+        const base = cfg.basePath;
+        const env = cfg.env ?? '';
+        // The only permitted subtree under source protection is data/<env>/ (when env
+        // is set) or data/ (legacy). All source code paths are blocked.
+        const dataEnvDir = env
+            ? (0, path_1.resolve)(base, 'data', env)
+            : (0, path_1.resolve)(base, 'data');
+        if (resolvedPath.startsWith(dataEnvDir + require('path').sep) || resolvedPath === dataEnvDir) {
+            return; // allowed
+        }
+        throw new SourceProtectionError(resolvedPath, agentId);
+    }
+    /** Read a file within the sandbox scope */
+    async read(filePath, agentId) {
+        const start = Date.now();
+        const resolved = this.policy.resolvePath(filePath);
+        if (!resolved) {
+            return { success: false, path: filePath, error: 'Path traversal blocked', durationMs: Date.now() - start };
+        }
+        if (!this.policy.isPathAllowed(filePath)) {
+            return { success: false, path: filePath, error: 'Path not in allowed scope', durationMs: Date.now() - start };
+        }
+        try {
+            this.checkSourceProtection(resolved, agentId);
+        }
+        catch (err) {
+            if (err instanceof SourceProtectionError) {
+                return { success: false, path: resolved, error: err.message, durationMs: Date.now() - start };
+            }
+            throw err;
+        }
+        try {
+            const content = await (0, promises_1.readFile)(resolved, 'utf-8');
+            return { success: true, path: resolved, content, durationMs: Date.now() - start };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, path: resolved, error: msg, durationMs: Date.now() - start };
+        }
+    }
+    /** Write a file within the sandbox scope */
+    async write(filePath, content, agentId) {
+        const start = Date.now();
+        const resolved = this.policy.resolvePath(filePath);
+        if (!resolved) {
+            return { success: false, path: filePath, error: 'Path traversal blocked', durationMs: Date.now() - start };
+        }
+        if (!this.policy.isPathAllowed(filePath)) {
+            return { success: false, path: filePath, error: 'Path not in allowed scope', durationMs: Date.now() - start };
+        }
+        try {
+            this.checkSourceProtection(resolved, agentId);
+        }
+        catch (err) {
+            if (err instanceof SourceProtectionError) {
+                return { success: false, path: resolved, error: err.message, durationMs: Date.now() - start };
+            }
+            throw err;
+        }
+        try {
+            await (0, promises_1.mkdir)((0, path_1.dirname)(resolved), { recursive: true });
+            await (0, promises_1.writeFile)(resolved, content, 'utf-8');
+            return { success: true, path: resolved, durationMs: Date.now() - start };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, path: resolved, error: msg, durationMs: Date.now() - start };
+        }
+    }
+    /** List directory contents within the sandbox scope */
+    async list(dirPath, agentId) {
+        const start = Date.now();
+        const resolved = this.policy.resolvePath(dirPath);
+        if (!resolved) {
+            return { success: false, path: dirPath, error: 'Path traversal blocked', durationMs: Date.now() - start };
+        }
+        if (!this.policy.isPathAllowed(dirPath)) {
+            return { success: false, path: dirPath, error: 'Path not in allowed scope', durationMs: Date.now() - start };
+        }
+        try {
+            this.checkSourceProtection(resolved, agentId);
+        }
+        catch (err) {
+            if (err instanceof SourceProtectionError) {
+                return { success: false, path: resolved, error: err.message, durationMs: Date.now() - start };
+            }
+            throw err;
+        }
+        try {
+            const items = await (0, promises_1.readdir)(resolved);
+            const entries = [];
+            for (const item of items) {
+                const itemPath = (0, path_1.join)(resolved, item);
+                const info = await (0, promises_1.stat)(itemPath);
+                entries.push(info.isDirectory() ? `${item}/` : item);
+            }
+            return { success: true, path: resolved, entries, durationMs: Date.now() - start };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return { success: false, path: resolved, error: msg, durationMs: Date.now() - start };
+        }
+    }
+}
+exports.FileAccessor = FileAccessor;
+// ============================================================================
+// APPROVAL GATE
+// ============================================================================
+/**
+ * Human-in-the-loop approval gate. Queues requests and waits for
+ * a decision from the configured callback.
+ *
+ * @example
+ * ```typescript
+ * const gate = new ApprovalGate(async (req) => {
+ *   return { approved: true, approvedBy: 'operator' };
+ * });
+ * const decision = await gate.request({ type: 'shell', target: 'npm publish', ... });
+ * ```
+ */
+class ApprovalGate extends events_1.EventEmitter {
+    callback;
+    autoApproveAll;
+    history = [];
+    constructor(callback, autoApproveAll = false) {
+        super();
+        this.callback = callback ?? null;
+        this.autoApproveAll = autoApproveAll;
+    }
+    /** Request approval for an operation */
+    async request(req) {
+        this.emit('requested', req);
+        if (this.autoApproveAll) {
+            const decision = { approved: true, approvedBy: 'auto-approve-all' };
+            this.history.push({ request: req, decision });
+            this.emit('decided', req, decision);
+            return decision;
+        }
+        if (!this.callback) {
+            const decision = { approved: false, reason: 'No approval callback configured' };
+            this.history.push({ request: req, decision });
+            this.emit('decided', req, decision);
+            return decision;
+        }
+        const decision = await this.callback(req);
+        this.history.push({ request: req, decision });
+        this.emit('decided', req, decision);
+        return decision;
+    }
+    /** Get approval history */
+    getHistory() {
+        return this.history;
+    }
+    /** Get count of approvals/denials */
+    getStats() {
+        const approved = this.history.filter(h => h.decision.approved).length;
+        return { total: this.history.length, approved, denied: this.history.length - approved };
+    }
+}
+exports.ApprovalGate = ApprovalGate;
+// ============================================================================
+// AGENT RUNTIME (Facade)
+// ============================================================================
+/**
+ * Unified agent execution runtime. Combines policy, shell, file access,
+ * and approval into a single interface for agent consumption.
+ *
+ * @example
+ * ```typescript
+ * const runtime = new AgentRuntime({
+ *   policy: {
+ *     basePath: '/project',
+ *     allowedCommands: ['npm *', 'node *', 'git status', 'git diff'],
+ *   },
+ *   onApproval: async (req) => {
+ *     console.log(`Approve? ${req.type}: ${req.target}`);
+ *     return { approved: true, approvedBy: 'operator' };
+ *   },
+ * });
+ *
+ * const result = await runtime.exec('npm test', 'tester-agent');
+ * ```
+ */
+class AgentRuntime extends events_1.EventEmitter {
+    policy;
+    shell;
+    files;
+    gate;
+    auditLog = [];
+    receiptManager = new security_1.SecureTokenManager();
+    constructor(opts) {
+        super();
+        this.policy = new SandboxPolicy(opts.policy);
+        this.shell = new ShellExecutor(this.policy);
+        this.files = new FileAccessor(this.policy);
+        this.gate = new ApprovalGate(opts.onApproval, opts.autoApproveAll);
+        // Wire approval events
+        this.gate.on('requested', (req) => {
+            this.emit('approval:requested', req);
+            this.audit({ action: 'approval_requested', agentId: req.agentId, target: req.target, result: 'success' });
+        });
+        this.gate.on('decided', (req, dec) => {
+            this.emit('approval:decided', req, dec);
+            this.audit({
+                action: dec.approved ? 'approval_granted' : 'approval_denied',
+                agentId: req.agentId,
+                target: req.target,
+                result: dec.approved ? 'success' : 'denied',
+                details: { approvedBy: dec.approvedBy, reason: dec.reason },
+            });
+        });
+    }
+    /**
+     * Execute a shell command with policy + approval checks.
+     * Returns ShellResult on success, throws on policy violation.
+     */
+    async exec(command, agentId, opts = {}) {
+        // Policy check
+        if (!this.policy.isCommandAllowed(command)) {
+            this.emit('policy:violation', agentId, command, 'Command not allowed by policy');
+            this.audit({ action: 'shell_execute', agentId, target: command, result: 'blocked' });
+            throw new RuntimePolicyError(`Command blocked by policy: ${command}`);
+        }
+        // Approval check
+        const needsApproval = opts.requiresApproval ?? this.policy.requiresApproval(command);
+        if (needsApproval) {
+            const decision = await this.gate.request({
+                type: 'shell',
+                target: command,
+                agentId,
+                risk: this.policy.assessRisk(command),
+                timestamp: Date.now(),
+            });
+            if (!decision.approved) {
+                this.audit({ action: 'shell_execute', agentId, target: command, result: 'denied', details: { reason: decision.reason } });
+                throw new RuntimeApprovalError(`Command denied: ${decision.reason ?? 'no reason given'}`);
+            }
+        }
+        // Execute
+        this.emit('command:start', agentId, command);
+        const result = await this.shell.execute(command, { ...opts, agentId });
+        this.emit('command:complete', agentId, command, result);
+        // Issue outcome-bound receipt — runtime authority, not agent's word
+        const outputHash = (0, crypto_1.createHash)('sha256')
+            .update(result.stdout + result.stderr + String(result.exitCode))
+            .digest('hex');
+        result.receipt = this.receiptManager.generateReceipt(agentId, 'shell_execute', command, result.exitCode, outputHash);
+        this.audit({
+            action: 'shell_execute',
+            agentId,
+            target: command,
+            result: result.exitCode === 0 ? 'success' : (result.timedOut ? 'timeout' : 'error'),
+            durationMs: result.durationMs,
+            details: { exitCode: result.exitCode, timedOut: result.timedOut },
+        });
+        return result;
+    }
+    /** Read a file with policy + optional approval */
+    async readFile(filePath, agentId) {
+        if (!this.policy.isPathAllowed(filePath)) {
+            this.emit('policy:violation', agentId, filePath, 'Path not allowed');
+            this.audit({ action: 'file_read', agentId, target: filePath, result: 'blocked' });
+            return { success: false, path: filePath, error: 'Path not allowed by policy', durationMs: 0 };
+        }
+        // Reads can auto-approve
+        if (!this.policy.autoApproveReads) {
+            const decision = await this.gate.request({
+                type: 'file_read', target: filePath, agentId, risk: 'low', timestamp: Date.now(),
+            });
+            if (!decision.approved) {
+                this.audit({ action: 'file_read', agentId, target: filePath, result: 'denied' });
+                return { success: false, path: filePath, error: 'Read denied', durationMs: 0 };
+            }
+        }
+        this.emit('file:access', agentId, filePath, 'read');
+        const result = await this.files.read(filePath, agentId);
+        this.audit({
+            action: 'file_read', agentId, target: filePath,
+            result: result.success ? 'success' : 'error', durationMs: result.durationMs,
+        });
+        return result;
+    }
+    /** Write a file with policy + approval */
+    async writeFile(filePath, content, agentId) {
+        if (!this.policy.isPathAllowed(filePath)) {
+            this.emit('policy:violation', agentId, filePath, 'Path not allowed');
+            this.audit({ action: 'file_write', agentId, target: filePath, result: 'blocked' });
+            return { success: false, path: filePath, error: 'Path not allowed by policy', durationMs: 0 };
+        }
+        const decision = await this.gate.request({
+            type: 'file_write', target: filePath, agentId, risk: 'medium', timestamp: Date.now(),
+        });
+        if (!decision.approved) {
+            this.audit({ action: 'file_write', agentId, target: filePath, result: 'denied' });
+            return { success: false, path: filePath, error: `Write denied: ${decision.reason ?? 'no reason'}`, durationMs: 0 };
+        }
+        this.emit('file:access', agentId, filePath, 'write');
+        const result = await this.files.write(filePath, content, agentId);
+        // Issue outcome-bound receipt on successful write
+        if (result.success) {
+            const contentHash = (0, crypto_1.createHash)('sha256').update(content).digest('hex');
+            result.receipt = this.receiptManager.generateReceipt(agentId, 'file_write', result.path, 0, contentHash);
+        }
+        this.audit({
+            action: 'file_write', agentId, target: filePath,
+            result: result.success ? 'success' : 'error', durationMs: result.durationMs,
+        });
+        return result;
+    }
+    /** List a directory with policy check */
+    async listDir(dirPath, agentId) {
+        if (!this.policy.isPathAllowed(dirPath)) {
+            this.emit('policy:violation', agentId, dirPath, 'Path not allowed');
+            this.audit({ action: 'file_list', agentId, target: dirPath, result: 'blocked' });
+            return { success: false, path: dirPath, error: 'Path not allowed by policy', durationMs: 0 };
+        }
+        this.emit('file:access', agentId, dirPath, 'list');
+        const result = await this.files.list(dirPath, agentId);
+        this.audit({
+            action: 'file_list', agentId, target: dirPath,
+            result: result.success ? 'success' : 'error', durationMs: result.durationMs,
+        });
+        return result;
+    }
+    /** Get the internal audit log */
+    getAuditLog() {
+        return this.auditLog;
+    }
+    /** Clear the internal audit log */
+    clearAuditLog() {
+        this.auditLog = [];
+    }
+    audit(entry) {
+        const full = { ...entry, timestamp: new Date().toISOString() };
+        this.auditLog.push(full);
+        this.emit('audit', full);
+    }
+}
+exports.AgentRuntime = AgentRuntime;
+// ============================================================================
+// ERROR TYPES
+// ============================================================================
+/** Thrown when an operation violates the sandbox policy */
+class RuntimePolicyError extends Error {
+    code = 'POLICY_VIOLATION';
+    constructor(message) {
+        super(message);
+        this.name = 'RuntimePolicyError';
+    }
+}
+exports.RuntimePolicyError = RuntimePolicyError;
+/** Thrown when an operation is denied by the approval gate */
+class RuntimeApprovalError extends Error {
+    code = 'APPROVAL_DENIED';
+    constructor(message) {
+        super(message);
+        this.name = 'RuntimeApprovalError';
+    }
+}
+exports.RuntimeApprovalError = RuntimeApprovalError;
+/** Thrown when a command fails to spawn */
+class RuntimeExecutionError extends Error {
+    code = 'EXECUTION_ERROR';
+    constructor(message) {
+        super(message);
+        this.name = 'RuntimeExecutionError';
+    }
+}
+exports.RuntimeExecutionError = RuntimeExecutionError;
+//# sourceMappingURL=agent-runtime.js.map