@rivet-dev/agentos-core 0.2.14 → 0.2.16-rc.1

package/dist/agent-os.js

@@ -3,6 +3,8 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join, posix as posixPath, resolve as resolveHostPath, } from "node:path";
 import { fileURLToPath } from "node:url";
+import * as executionProtocol from "@rivet-dev/agentos-runtime-core/protocol";
+import { SidecarRejectedError } from "@rivet-dev/agentos-runtime-core/sidecar-errors";
 import { validateBindings } from "./bindings.js";
 import { zodToJsonSchema } from "./bindings-zod.js";
 import { parseAgentOsOptions } from "./options-schema.js";
@@ -12,6 +14,7 @@ import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
 const ACP_PROTOCOL_VERSION = 1;
 const ACP_EXTENSION_NAMESPACE = "dev.rivet.agent-os.acp";
 const SHELL_DISPOSE_TIMEOUT_MS = 5_000;
+const PROCESS_OUTPUT_EVENT_LIMIT = 1_024;
 function safeWireU64(value) {
     const result = Number(value);
     if (!Number.isSafeInteger(result) || result < 0) {
@@ -1428,12 +1431,212 @@ async function registerBindingsOnSidecar(client, session, vm, bindings) {
     }
     return buildBindingReference(bindings);
 }
+function executionIdentity(options) {
+    return {
+        contextId: options.contextId ?? null,
+    };
+}
+function executionOutput(options, background = false) {
+    if (options.output?.retainEvents && !options.contextId && !background) {
+        throw new Error("retainEvents is available only for spawned processes; use output.capture for attached runs");
+    }
+    const capture = options.output?.capture;
+    return {
+        capture: capture === "all"
+            ? executionProtocol.ExecutionOutputCapture.All
+            : capture === "stderr"
+                ? executionProtocol.ExecutionOutputCapture.Stderr
+                : capture === "none"
+                    ? executionProtocol.ExecutionOutputCapture.None
+                    : null,
+        retainEvents: options.output?.retainEvents ?? null,
+    };
+}
+function executionBytes(data) {
+    if (data === undefined)
+        return null;
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    return bytes.slice().buffer;
+}
+function processExecutionOptions(options = {}, internal) {
+    const background = internal?.background ?? false;
+    return {
+        identity: executionIdentity(options),
+        output: executionOutput(options, background),
+        operationId: internal?.executionId ?? null,
+        background,
+        cwd: options.cwd ?? null,
+        env: options.env ? new Map(Object.entries(options.env)) : null,
+        args: options.args ?? [],
+        stdin: executionBytes(options.stdin),
+        timeoutMs: protocolTimeout(options.timeoutMs),
+        pty: options.pty
+            ? {
+                cols: options.pty.cols === undefined
+                    ? null
+                    : protocolUnsigned(options.pty.cols, 0xffff, "pty.cols"),
+                rows: options.pty.rows === undefined
+                    ? null
+                    : protocolUnsigned(options.pty.rows, 0xffff, "pty.rows"),
+            }
+            : null,
+    };
+}
+function protocolUnsigned(value, maximum, name) {
+    if (!Number.isSafeInteger(value) || value < 0 || value > maximum) {
+        throw new RangeError(`${name} must be an integer between 0 and ${maximum}`);
+    }
+    return value;
+}
+function protocolTimeout(value) {
+    if (value === undefined)
+        return null;
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new RangeError("timeoutMs must be a non-negative safe integer");
+    }
+    return BigInt(value);
+}
+function safeProtocolNumber(value, name) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result)) {
+        throw new RangeError(`${name} exceeds JavaScript's safe integer range`);
+    }
+    return result;
+}
+function mapExecutionState(state) {
+    const mapped = state.toLowerCase();
+    return (mapped === "creating" ? "idle" : mapped);
+}
+function mapExecutionOutcome(outcome) {
+    return outcome === executionProtocol.ExecutionOutcome.TimedOut
+        ? "timed_out"
+        : outcome.toLowerCase();
+}
+function mapExecutionDescriptor(descriptor) {
+    return {
+        contextId: descriptor.executionId,
+        state: mapExecutionState(descriptor.state),
+        ...(descriptor.retainedLanguage
+            ? {
+                language: descriptor.retainedLanguage ===
+                    executionProtocol.RetainedExecutionLanguage.JavaScript
+                    ? "javascript"
+                    : "python",
+            }
+            : {}),
+        createdAtMs: safeProtocolNumber(descriptor.createdAtMs, "createdAtMs"),
+        ...(descriptor.lastStartedAtMs !== null
+            ? {
+                lastStartedAtMs: safeProtocolNumber(descriptor.lastStartedAtMs, "lastStartedAtMs"),
+            }
+            : {}),
+        ...(descriptor.lastCompletedAtMs !== null
+            ? {
+                lastCompletedAtMs: safeProtocolNumber(descriptor.lastCompletedAtMs, "lastCompletedAtMs"),
+            }
+            : {}),
+    };
+}
+function mapExecutionError(error) {
+    if (!error)
+        return undefined;
+    return {
+        code: error.code,
+        name: error.name,
+        message: error.message,
+        ...(error.stack ? { stack: error.stack } : {}),
+        ...(error.details
+            ? { details: JSON.parse(error.details) }
+            : {}),
+    };
+}
+function mapExecutionResult(result) {
+    const base = {
+        ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
+        ...(result.stdout !== null
+            ? { stdout: new TextDecoder().decode(result.stdout) }
+            : {}),
+        ...(result.stderr !== null
+            ? { stderr: new TextDecoder().decode(result.stderr) }
+            : {}),
+        ...(result.stdoutTruncated !== null
+            ? { stdoutTruncated: result.stdoutTruncated }
+            : {}),
+        ...(result.stderrTruncated !== null
+            ? { stderrTruncated: result.stderrTruncated }
+            : {}),
+        ...(result.evaluationValue
+            ? { evaluationValue: JSON.parse(result.evaluationValue) }
+            : {}),
+        ...(result.typeScriptCheckResult
+            ? {
+                typeScriptCheckResult: JSON.parse(result.typeScriptCheckResult),
+            }
+            : {}),
+    };
+    const outcome = mapExecutionOutcome(result.outcome);
+    if (outcome === "succeeded") {
+        return { ...base, outcome };
+    }
+    return {
+        ...base,
+        outcome,
+        error: mapExecutionError(result.error) ?? {
+            code: "execution_failed",
+            name: "ExecutionError",
+            message: `execution completed with ${outcome}`,
+        },
+    };
+}
+function mapTypeScriptCheckResult(result) {
+    if (result.outcome !== "succeeded") {
+        return { ...result, diagnostics: [] };
+    }
+    const data = result.typeScriptCheckResult;
+    if (!data || Array.isArray(data) || typeof data !== "object") {
+        throw new Error("TypeScript checker returned no diagnostic result");
+    }
+    const hasErrors = data.hasErrors;
+    const diagnostics = data.diagnostics;
+    if (typeof hasErrors !== "boolean" || !Array.isArray(diagnostics)) {
+        throw new Error("TypeScript checker returned an invalid diagnostic result");
+    }
+    return {
+        ...result,
+        hasErrors,
+        diagnostics: diagnostics,
+    };
+}
+function mapExecutionOutputEvent(event) {
+    return {
+        executionId: event.executionId,
+        generation: safeProtocolNumber(event.generation, "execution generation"),
+        ...(event.processId ? { processId: event.processId } : {}),
+        sequence: safeProtocolNumber(event.sequence, "execution output sequence"),
+        channel: event.channel.toLowerCase(),
+        chunk: new Uint8Array(event.chunk),
+        timestampMs: safeProtocolNumber(event.timestampMs, "execution timestamp"),
+    };
+}
+function mapExecutionCompletedEvent(event) {
+    return {
+        executionId: event.executionId,
+        generation: safeProtocolNumber(event.generation, "execution generation"),
+        outcome: mapExecutionOutcome(event.outcome),
+        ...(event.exitCode !== null ? { exitCode: event.exitCode } : {}),
+        ...(event.error ? { error: mapExecutionError(event.error) } : {}),
+    };
+}
 export class AgentOs {
     #kernel;
     sidecar;
     _durableSessionEventHandlers = new Map();
     _agentExitHandlers = new Map();
     _processes = new Map();
+    _languageProcesses = new Map();
+    _languageProcessIds = new Map();
+    _executionOutputHandlers = new Map();
+    _executionCompletedHandlers = new Map();
     _shells = new Map();
     // Value is the recorded exit code (undefined until/unless the exit
     // resolves) so waitShell can still report it after the entry is dropped.
@@ -1459,6 +1662,119 @@ export class AgentOs {
     _agentExitHandler;
     _limitWarningHandler;
     _disposeHooks = [];
+    /**
+     * Execute commands and manage child processes in the VM.
+     *
+     * `exec` evaluates a command with the configured shell, while `execFile`
+     * invokes an executable directly with an argv array.
+     */
+    process = {
+        exec: this._exec.bind(this),
+        execFile: this._execFile.bind(this),
+        spawn: this._spawnProcess.bind(this),
+        get: this._getProcess.bind(this),
+        list: this._listProcesses.bind(this),
+        tree: this._processTree.bind(this),
+        wait: this._waitProcess.bind(this),
+        signal: this._signalProcess.bind(this),
+        kill: this._killProcess.bind(this),
+        writeStdin: this._writeProcessStdin.bind(this),
+        closeStdin: this._closeProcessStdin.bind(this),
+        resizePty: this._resizeProcessPty.bind(this),
+        readOutput: this._readProcessOutput.bind(this),
+    };
+    javascript = {
+        execute: this._executeJavaScript.bind(this),
+        evaluate: this._evaluateJavaScript.bind(this),
+        executeFile: this._executeJavaScriptFile.bind(this),
+        spawn: this._spawnJavaScript.bind(this),
+        spawnFile: this._spawnJavaScriptFile.bind(this),
+        npm: {
+            install: this._installNpmPackages.bind(this),
+            runScript: this._executeNpmScript.bind(this),
+            runPackage: this._executeNpmPackage.bind(this),
+        },
+    };
+    typescript = {
+        execute: this._executeTypeScript.bind(this),
+        evaluate: this._evaluateTypeScript.bind(this),
+        executeFile: this._executeTypeScriptFile.bind(this),
+        spawn: this._spawnTypeScript.bind(this),
+        spawnFile: this._spawnTypeScriptFile.bind(this),
+        check: this._checkTypeScript.bind(this),
+        checkProject: this._checkTypeScriptProject.bind(this),
+    };
+    python = {
+        execute: this._executePython.bind(this),
+        evaluate: this._evaluatePython.bind(this),
+        executeFile: this._executePythonFile.bind(this),
+        executeModule: this._executePythonModule.bind(this),
+        spawn: this._spawnPython.bind(this),
+        spawnFile: this._spawnPythonFile.bind(this),
+        spawnModule: this._spawnPythonModule.bind(this),
+        install: this._installPythonPackages.bind(this),
+    };
+    contexts = {
+        get: this._getContext.bind(this),
+        list: this._listContexts.bind(this),
+        reset: this._resetContext.bind(this),
+        delete: this._deleteContext.bind(this),
+    };
+    terminal = {
+        open: this._openTerminal.bind(this),
+        write: this._writeTerminal.bind(this),
+        resize: this._resizeTerminal.bind(this),
+        wait: this._waitTerminal.bind(this),
+        close: this._closeTerminal.bind(this),
+    };
+    filesystem = {
+        readFile: this._readFile.bind(this),
+        writeFile: this._writeFile.bind(this),
+        readFiles: this._readFiles.bind(this),
+        writeFiles: this._writeFiles.bind(this),
+        stat: this._stat.bind(this),
+        mkdir: this._mkdir.bind(this),
+        readdir: this._readdir.bind(this),
+        readdirEntries: this._readdirEntries.bind(this),
+        readdirRecursive: this._readdirRecursive.bind(this),
+        exists: this._exists.bind(this),
+        move: this._move.bind(this),
+        remove: this._remove.bind(this),
+        export: this._exportRootFilesystem.bind(this),
+        mount: this._mountFs.bind(this),
+        unmount: this._unmountFs.bind(this),
+        listMounts: this._listMounts.bind(this),
+    };
+    network = {
+        httpRequest: this._httpRequest.bind(this),
+    };
+    software = {
+        list: this._listSoftware.bind(this),
+        link: this._linkSoftware.bind(this),
+    };
+    agents = {
+        list: this._listAgents.bind(this),
+    };
+    sessions = {
+        open: this._openSession.bind(this),
+        get: this._getSession.bind(this),
+        list: this._listSessions.bind(this),
+        delete: this._deleteSession.bind(this),
+        unload: this._unloadSession.bind(this),
+        prompt: this._prompt.bind(this),
+        cancelPrompt: this._cancelPrompt.bind(this),
+        respondPermission: this._respondPermission.bind(this),
+        readHistory: this._readHistory.bind(this),
+        getConfig: this._getSessionConfig.bind(this),
+        setConfigOption: this._setSessionConfigOption.bind(this),
+        getCapabilities: this._getSessionCapabilities.bind(this),
+        getAgentInfo: this._getSessionAgentInfo.bind(this),
+    };
+    cron = {
+        schedule: this._scheduleCron.bind(this),
+        list: this._listCronJobs.bind(this),
+        cancel: this._cancelCronJob.bind(this),
+    };
     constructor(kernel, sidecar, softwareRoots, hostMounts, env, rootFilesystem, sidecarClient, sidecarSession, sidecarVm, agentStderrHandler, agentExitHandler, limitWarningHandler) {
         this.#kernel = kernel;
         this.sidecar = sidecar;
@@ -1761,18 +2077,673 @@ export class AgentOs {
             throw error;
         }
     }
+    async createContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "create_context", request: { contextId } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected createContext response: ${response.type}`);
+        }
+    }
+    async _executionOperation(payload, options, background = false) {
+        if (options.signal?.aborted) {
+            throw options.signal.reason ?? new DOMException("Aborted", "AbortError");
+        }
+        let executionId;
+        const earlyOutput = [];
+        const completedBeforeAdmission = new Set();
+        let resolveCompletion;
+        const completion = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        let warnedAboutEarlyEvents = false;
+        const warnAboutEarlyEvents = () => {
+            if (warnedAboutEarlyEvents)
+                return;
+            warnedAboutEarlyEvents = true;
+            console.warn("[agentos] execution admission received more than 1024 early events; use process.readOutput() to replay any omitted output");
+        };
+        const deliverOutput = (event) => {
+            if (event.channel === "stderr")
+                options.onStderr?.(event.chunk);
+            else
+                options.onStdout?.(event.chunk);
+        };
+        const unsubscribeOutput = this._onExecutionOutput("*", (event) => {
+            if (executionId === undefined) {
+                if (earlyOutput.length < 1_024)
+                    earlyOutput.push(event);
+                else
+                    warnAboutEarlyEvents();
+                return;
+            }
+            if (event.executionId === executionId)
+                deliverOutput(event);
+        });
+        let completed = false;
+        const unsubscribeCompleted = this._onExecutionCompleted("*", (event) => {
+            if (executionId === undefined) {
+                if (completedBeforeAdmission.size < 1_024) {
+                    completedBeforeAdmission.add(event.executionId);
+                }
+                else
+                    warnAboutEarlyEvents();
+                return;
+            }
+            if (event.executionId === executionId) {
+                completed = true;
+                resolveCompletion?.();
+            }
+        });
+        let response;
+        try {
+            response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, payload);
+        }
+        catch (error) {
+            unsubscribeOutput();
+            unsubscribeCompleted();
+            throw error;
+        }
+        if (response.type !== "execution_accepted") {
+            unsubscribeOutput();
+            unsubscribeCompleted();
+            throw new Error(`unexpected execution response: ${response.type}`);
+        }
+        const descriptor = response.response.execution;
+        executionId = response.response.operationId;
+        for (const event of earlyOutput) {
+            if (event.executionId === executionId)
+                deliverOutput(event);
+        }
+        completed = completedBeforeAdmission.has(executionId);
+        if (completed)
+            resolveCompletion?.();
+        let rejectAbort;
+        const aborted = !background && options.signal
+            ? new Promise((_resolve, reject) => {
+                rejectAbort = reject;
+            })
+            : undefined;
+        const abort = () => {
+            void this._cancelExecution(response.response.operationId).catch((error) => {
+                console.error("[agentos] failed to cancel aborted execution", error);
+            });
+            rejectAbort?.(options.signal?.reason ?? new DOMException("Aborted", "AbortError"));
+        };
+        options.signal?.addEventListener("abort", abort, { once: true });
+        if (options.signal?.aborted)
+            abort();
+        const cleanup = () => {
+            unsubscribeOutput();
+            unsubscribeCompleted();
+            options.signal?.removeEventListener("abort", abort);
+        };
+        if (background) {
+            if (!descriptor || descriptor.pid === null) {
+                cleanup();
+                throw new Error("spawned execution admission returned no process id");
+            }
+            if (completed)
+                cleanup();
+            else {
+                const unsubscribeBackgroundCompletion = this._onExecutionCompleted(descriptor.executionId, () => {
+                    unsubscribeBackgroundCompletion();
+                    cleanup();
+                });
+            }
+            return {
+                executionId: descriptor.executionId,
+                pid: descriptor.pid,
+                completed,
+                completion,
+                createdAtMs: safeProtocolNumber(descriptor.createdAtMs, "process startedAtMs"),
+            };
+        }
+        try {
+            await (aborted ? Promise.race([completion, aborted]) : completion);
+            return await this._waitExecutionResult(response.response.operationId);
+        }
+        finally {
+            cleanup();
+        }
+    }
+    async _spawnLanguageOperation(buildPayload, options, language) {
+        if ("contextId" in options) {
+            throw new Error("contextId is not supported for spawned processes; contexts are for attached operations");
+        }
+        const executionId = `process-${randomUUID()}`;
+        const internalOptions = {
+            ...options,
+            output: options.output,
+        };
+        const admitted = (await this._executionOperation(buildPayload(internalOptions, executionId), internalOptions, true));
+        const descriptor = {
+            pid: admitted.pid,
+            state: "running",
+            language,
+            startedAtMs: admitted.createdAtMs,
+        };
+        this._languageProcesses.set(admitted.pid, {
+            executionId: admitted.executionId,
+            descriptor,
+            outputHandlers: new Set(),
+            exitHandlers: new Set(),
+        });
+        this._languageProcessIds.set(admitted.executionId, admitted.pid);
+        const reconcileCompletion = async () => {
+            if (!this._languageProcesses.get(admitted.pid)?.exit) {
+                await this._waitProcess(admitted.pid);
+            }
+        };
+        if (admitted.completed)
+            await reconcileCompletion();
+        else {
+            void admitted.completion
+                .then(reconcileCompletion)
+                .catch((error) => console.error("[agentos] failed to reconcile spawned process completion", error));
+        }
+        if (options.signal) {
+            const abort = () => {
+                void this._killProcess(admitted.pid);
+            };
+            options.signal.addEventListener("abort", abort, { once: true });
+        }
+        return this._languageProcesses.get(admitted.pid)?.descriptor ?? descriptor;
+    }
+    async _exec(command, options = {}) {
+        return (await this._executionOperation({
+            type: "shell_execution",
+            request: { process: processExecutionOptions(options), command },
+        }, options));
+    }
+    async _execFile(command, args = [], options = {}) {
+        const operationOptions = { ...options, args: [...args] };
+        return (await this._executionOperation({
+            type: "argv_execution",
+            request: {
+                process: processExecutionOptions(operationOptions),
+                command,
+            },
+        }, operationOptions));
+    }
+    /** @deprecated Use `process.exec()` for lifecycle-aware execution. */
     async exec(command, options) {
         return this.#kernel.exec(command, options);
     }
+    /** @deprecated Use `process.execFile()` for lifecycle-aware execution. */
     async execArgv(command, args = [], options) {
         const kernel = this.#kernel;
         return kernel.execArgv(command, args, options);
     }
-    _trackProcess(proc, command, args, outputHandlers, exitHandlers) {
+    async _executeJavaScript(source, options = {}) {
+        return (await this._executionOperation({
+            type: "javascript_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                format: options.format === "commonjs"
+                    ? executionProtocol.JavaScriptModuleFormat.CommonJs
+                    : executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: options.filePath ?? null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
+    }
+    async _evaluationOperation(payload, options) {
+        const result = (await this._executionOperation(payload, options));
+        if (result.outcome !== "succeeded")
+            return result;
+        const value = result.evaluationValue;
+        if (value === undefined) {
+            throw new Error("successful evaluation did not return a JSON-serializable value");
+        }
+        return { ...result, value: value };
+    }
+    async _evaluateJavaScript(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "javascript_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                format: options.format === "commonjs"
+                    ? executionProtocol.JavaScriptModuleFormat.CommonJs
+                    : executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: options.filePath ?? null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options);
+    }
+    async _executeJavaScriptFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "javascript_file_execution",
+            request: { process: processExecutionOptions(options), path },
+        }, options));
+    }
+    _spawnJavaScript(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "javascript_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                format: executionProtocol.JavaScriptModuleFormat.Module,
+                filePath: null,
+                inputs: null,
+            },
+        }), options, "javascript");
+    }
+    _spawnJavaScriptFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "javascript_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+            },
+        }), options, "javascript");
+    }
+    async _executeTypeScript(source, options = {}) {
+        return (await this._executionOperation({
+            type: "typescript_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
+    }
+    async _evaluateTypeScript(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "typescript_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options);
+    }
+    async _executeTypeScriptFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "typescript_file_execution",
+            request: {
+                process: processExecutionOptions(options),
+                path,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+            },
+        }, options));
+    }
+    _spawnTypeScript(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "typescript_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                filePath: null,
+                tsconfigPath: null,
+                compilerOptions: null,
+                inputs: null,
+            },
+        }), options, "javascript");
+    }
+    _spawnTypeScriptFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "typescript_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+                tsconfigPath: null,
+                compilerOptions: null,
+            },
+        }), options, "javascript");
+    }
+    async _checkTypeScript(source, options = {}) {
+        const result = (await this._executionOperation({
+            type: "typescript_check",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                source,
+                cwd: options.cwd ?? null,
+                filePath: options.filePath ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                compilerOptions: options.compilerOptions
+                    ? JSON.stringify(options.compilerOptions)
+                    : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+            },
+        }, options));
+        return mapTypeScriptCheckResult(result);
+    }
+    async _checkTypeScriptProject(options = {}) {
+        const result = (await this._executionOperation({
+            type: "typescript_project_check",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                tsconfigPath: options.tsconfigPath ?? null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+            },
+        }, options));
+        return mapTypeScriptCheckResult(result);
+    }
+    async _installNpmPackages(packagesOrOptions = {}, maybeOptions = {}) {
+        if (typeof packagesOrOptions === "string" ||
+            Array.isArray(packagesOrOptions)) {
+            const packages = Array.isArray(packagesOrOptions)
+                ? packagesOrOptions
+                : [packagesOrOptions];
+            return (await this._executionOperation({
+                type: "npm_package_install",
+                request: {
+                    identity: executionIdentity(maybeOptions),
+                    output: executionOutput(maybeOptions),
+                    cwd: maybeOptions.cwd ?? null,
+                    env: maybeOptions.env
+                        ? new Map(Object.entries(maybeOptions.env))
+                        : null,
+                    timeoutMs: protocolTimeout(maybeOptions.timeoutMs),
+                    packages,
+                    dev: maybeOptions.dev ?? null,
+                    global: maybeOptions.global ?? null,
+                },
+            }, maybeOptions));
+        }
+        const options = packagesOrOptions;
+        return (await this._executionOperation({
+            type: "npm_project_install",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                env: options.env ? new Map(Object.entries(options.env)) : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+                frozen: options.frozen ?? null,
+            },
+        }, options));
+    }
+    async _executeNpmScript(script, options = {}) {
+        return (await this._executionOperation({
+            type: "npm_script_execution",
+            request: { process: processExecutionOptions(options), script },
+        }, options));
+    }
+    async _executeNpmPackage(packageSpec, options = {}) {
+        return (await this._executionOperation({
+            type: "npm_package_execution",
+            request: {
+                process: processExecutionOptions(options),
+                packageSpec,
+                binary: options.binary ?? null,
+            },
+        }, options));
+    }
+    async _executePython(source, options = {}) {
+        return (await this._executionOperation({
+            type: "python_execution",
+            request: {
+                process: processExecutionOptions(options),
+                source,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options));
+    }
+    async _evaluatePython(expression, options = {}) {
+        return this._evaluationOperation({
+            type: "python_evaluation",
+            request: {
+                process: processExecutionOptions(options),
+                expression,
+                inputs: options.inputs ? JSON.stringify(options.inputs) : null,
+            },
+        }, options);
+    }
+    async _executePythonFile(path, options = {}) {
+        return (await this._executionOperation({
+            type: "python_file_execution",
+            request: { process: processExecutionOptions(options), path },
+        }, options));
+    }
+    async _executePythonModule(module, options = {}) {
+        return (await this._executionOperation({
+            type: "python_module_execution",
+            request: { process: processExecutionOptions(options), module },
+        }, options));
+    }
+    _spawnPython(source, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                source,
+                inputs: null,
+            },
+        }), options, "python");
+    }
+    _spawnPythonFile(path, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_file_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                path,
+            },
+        }), options, "python");
+    }
+    _spawnPythonModule(module, options = {}) {
+        return this._spawnLanguageOperation((operationOptions, executionId) => ({
+            type: "python_module_execution",
+            request: {
+                process: processExecutionOptions(operationOptions, {
+                    background: true,
+                    executionId,
+                }),
+                module,
+            },
+        }), options, "python");
+    }
+    async _installPythonPackages(packagesOrOptions = {}, maybeOptions = {}) {
+        const packages = typeof packagesOrOptions === "string"
+            ? [packagesOrOptions]
+            : Array.isArray(packagesOrOptions)
+                ? packagesOrOptions
+                : [];
+        const options = typeof packagesOrOptions === "string" || Array.isArray(packagesOrOptions)
+            ? maybeOptions
+            : packagesOrOptions;
+        return (await this._executionOperation({
+            type: "python_install",
+            request: {
+                identity: executionIdentity(options),
+                output: executionOutput(options),
+                cwd: options.cwd ?? null,
+                env: options.env ? new Map(Object.entries(options.env)) : null,
+                timeoutMs: protocolTimeout(options.timeoutMs),
+                packages,
+                upgrade: options.upgrade ?? null,
+                requirementsFile: options.requirementsFile ?? null,
+                indexUrl: options.indexUrl ?? null,
+                extraIndexUrls: options.extraIndexUrls ?? [],
+            },
+        }, options));
+    }
+    async _getContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "get_execution", request: { executionId: contextId } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected getContext response: ${response.type}`);
+        }
+        return mapExecutionDescriptor(response.response.execution);
+    }
+    async _listContexts() {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "list_executions" });
+        if (response.type !== "execution_list") {
+            throw new Error(`unexpected listContexts response: ${response.type}`);
+        }
+        return response.response.executions.map(mapExecutionDescriptor);
+    }
+    async _waitExecutionResult(executionId) {
+        let resolveCompletion;
+        const completion = new Promise((resolve) => {
+            resolveCompletion = resolve;
+        });
+        const unsubscribe = this._onExecutionCompleted(executionId, () => {
+            resolveCompletion?.();
+        });
+        let response;
+        try {
+            try {
+                response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "wait_execution", request: { executionId } });
+            }
+            catch (error) {
+                if (!(error instanceof SidecarRejectedError) ||
+                    error.detail.code !== "execution_busy") {
+                    throw error;
+                }
+                await completion;
+                response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "wait_execution", request: { executionId } });
+            }
+        }
+        finally {
+            unsubscribe();
+        }
+        if (response.type !== "execution_completed") {
+            throw new Error(`unexpected waitExecution response: ${response.type}`);
+        }
+        return mapExecutionResult(response.response);
+    }
+    async _cancelExecution(executionId) {
+        await this._descriptorLifecycleRequest("cancel_execution", executionId);
+    }
+    async _signalExecution(executionId, signal) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "signal_execution", request: { executionId, signal } });
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected signalExecution response: ${response.type}`);
+        }
+    }
+    async _resetContext(contextId) {
+        await this._descriptorLifecycleRequest("reset_execution", contextId);
+    }
+    async _descriptorLifecycleRequest(type, executionId) {
+        const payload = type === "cancel_execution"
+            ? { type, request: { executionId } }
+            : { type, request: { executionId } };
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, payload);
+        if (response.type !== "execution_descriptor") {
+            throw new Error(`unexpected ${type} response: ${response.type}`);
+        }
+        return mapExecutionDescriptor(response.response.execution);
+    }
+    async _deleteContext(contextId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "delete_execution", request: { executionId: contextId } });
+        if (response.type !== "execution_deleted") {
+            throw new Error(`unexpected deleteContext response: ${response.type}`);
+        }
+    }
+    async _writeExecutionStdin(executionId, data) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "write_execution_stdin",
+            request: { executionId, chunk: executionBytes(data) },
+        });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected writeExecutionStdin response: ${response.type}`);
+        }
+    }
+    async _closeExecutionStdin(executionId) {
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, { type: "close_execution_stdin", request: { executionId } });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected closeExecutionStdin response: ${response.type}`);
+        }
+    }
+    async _resizeExecutionPty(executionId, size) {
+        const cols = protocolUnsigned(size.cols, 0xffff, "size.cols");
+        const rows = protocolUnsigned(size.rows, 0xffff, "size.rows");
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "resize_execution_pty",
+            request: { executionId, cols, rows },
+        });
+        if (response.type !== "execution_io") {
+            throw new Error(`unexpected resizeExecutionPty response: ${response.type}`);
+        }
+    }
+    async _readExecutionOutput(executionId, options = {}) {
+        const limit = options.limit === undefined
+            ? null
+            : protocolUnsigned(options.limit, 0xffff_ffff, "limit");
+        const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
+            type: "read_execution_output",
+            request: {
+                executionId,
+                cursor: options.cursor ?? null,
+                limit,
+            },
+        });
+        if (response.type !== "execution_output_page") {
+            throw new Error(`unexpected readExecutionOutput response: ${response.type}`);
+        }
+        return {
+            events: response.response.events.map(mapExecutionOutputEvent),
+            nextCursor: response.response.nextCursor,
+            hasMore: response.response.hasMore,
+            truncated: response.response.truncated,
+        };
+    }
+    _onExecutionOutput(executionId, handler) {
+        const handlers = this._executionOutputHandlers.get(executionId) ?? new Set();
+        handlers.add(handler);
+        this._executionOutputHandlers.set(executionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._executionOutputHandlers.delete(executionId);
+        };
+    }
+    _onExecutionCompleted(executionId, handler) {
+        const handlers = this._executionCompletedHandlers.get(executionId) ?? new Set();
+        handlers.add(handler);
+        this._executionCompletedHandlers.set(executionId, handlers);
+        return () => {
+            handlers.delete(handler);
+            if (handlers.size === 0)
+                this._executionCompletedHandlers.delete(executionId);
+        };
+    }
+    _trackProcess(proc, command, args, retainEvents, outputHandlers, exitHandlers) {
         const entry = {
             proc,
             command,
             args,
+            startedAtMs: Date.now(),
+            retainEvents,
+            events: [],
+            nextSequence: 0,
+            signal: undefined,
+            exit: undefined,
             outputHandlers,
             exitHandlers,
         };
@@ -1783,40 +2754,83 @@ export class AgentOs {
         // `_processes` is a process table for this VM's lifetime; it is freed wholesale
         // in dispose(). (H5: the leak was that dispose() never cleared it.)
         void proc.wait().then((code) => {
+            const exit = {
+                pid: proc.pid,
+                outcome: entry.signal ? "signalled" : "exited",
+                exitCode: code,
+                ...(entry.signal ? { signal: entry.signal } : {}),
+            };
+            entry.exit = exit;
             for (const h of exitHandlers)
-                h({ pid: proc.pid, exitCode: code });
+                h(exit);
         });
-        return { pid: proc.pid };
+        return {
+            pid: proc.pid,
+            state: "running",
+            command,
+            startedAtMs: entry.startedAtMs,
+        };
     }
-    spawn(command, args, options) {
+    async _spawnProcess(command, args = [], options = {}) {
         const outputHandlers = new Set();
         const exitHandlers = new Set();
+        const recordOutput = (channel, data) => {
+            const entry = this._processes.get(proc.pid);
+            if (!entry?.retainEvents)
+                return;
+            if (entry.events.length >= PROCESS_OUTPUT_EVENT_LIMIT) {
+                entry.events.shift();
+            }
+            entry.events.push({
+                pid: proc.pid,
+                sequence: entry.nextSequence++,
+                channel,
+                chunk: data,
+                timestampMs: Date.now(),
+            });
+        };
         const proc = this.#kernel.spawn(command, args, {
-            ...options,
+            cwd: options.cwd,
+            env: options.env,
+            stdin: options.stdin,
+            timeout: options.timeoutMs,
             onStdout: (data) => {
+                recordOutput("stdout", data);
                 options?.onStdout?.(data);
                 for (const h of outputHandlers) {
                     h({ pid: proc.pid, stream: "stdout", data });
                 }
             },
             onStderr: (data) => {
+                recordOutput("stderr", data);
                 options?.onStderr?.(data);
                 for (const h of outputHandlers) {
                     h({ pid: proc.pid, stream: "stderr", data });
                 }
             },
         });
-        return this._trackProcess(proc, command, args, outputHandlers, exitHandlers);
+        return this._trackProcess(proc, command, args, options.output?.retainEvents ?? false, outputHandlers, exitHandlers);
+    }
+    spawn(command, args = [], options) {
+        return this.process.spawn(command, args, options);
     }
     /** Write data to a process's stdin. */
-    writeProcessStdin(pid, data) {
+    _writeProcessStdin(pid, data) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            return this._writeExecutionStdin(language.executionId, data);
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
         return entry.proc.writeStdin(data);
     }
     /** Close a process's stdin stream. */
-    closeProcessStdin(pid) {
+    _closeProcessStdin(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            return this._closeExecutionStdin(language.executionId);
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
@@ -1824,7 +2838,7 @@ export class AgentOs {
     }
     /** Subscribe to stdout and stderr from a process. */
     onProcessOutput(pid, handler) {
-        const entry = this._processes.get(pid);
+        const entry = this._processes.get(pid) ?? this._languageProcesses.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
         entry.outputHandlers.add(handler);
@@ -1834,12 +2848,12 @@ export class AgentOs {
     }
     /** Subscribe to process exit. Returns an unsubscribe function. */
     onProcessExit(pid, handler) {
-        const entry = this._processes.get(pid);
+        const entry = this._processes.get(pid) ?? this._languageProcesses.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
         // If already exited, call immediately.
-        if (entry.proc.exitCode !== null) {
-            handler({ pid, exitCode: entry.proc.exitCode });
+        if ("exit" in entry && entry.exit) {
+            handler(entry.exit);
             return () => { };
         }
         entry.exitHandlers.add(handler);
@@ -1848,11 +2862,39 @@ export class AgentOs {
         };
     }
     /** Wait for a process to exit. Returns the exit code. */
-    waitProcess(pid) {
+    async _waitProcess(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            if (language.exit)
+                return language.exit;
+            const result = await this._waitExecutionResult(language.executionId);
+            const exit = {
+                pid,
+                outcome: result.outcome === "timed_out"
+                    ? "timed_out"
+                    : result.outcome === "cancelled"
+                        ? "signalled"
+                        : "exited",
+                ...(result.exitCode !== undefined ? { exitCode: result.exitCode } : {}),
+                ...(language.signal ? { signal: language.signal } : {}),
+            };
+            language.exit = exit;
+            language.descriptor = { ...language.descriptor, state: "exited" };
+            for (const handler of language.exitHandlers)
+                handler(exit);
+            return exit;
+        }
         const entry = this._processes.get(pid);
         if (!entry)
             throw new Error(`Process not found: ${pid}`);
-        return entry.proc.wait();
+        if (entry.exit)
+            return entry.exit;
+        const exitCode = await entry.proc.wait();
+        return (entry.exit ?? {
+            pid,
+            outcome: "exited",
+            exitCode,
+        });
     }
     _assertSafeAbsolutePath(path) {
         if (!path.startsWith("/")) {
@@ -1871,15 +2913,15 @@ export class AgentOs {
     _vfs() {
         return this.#kernel.vfs;
     }
-    async readFile(path) {
+    async _readFile(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readFile(path);
     }
-    async writeFile(path, content) {
+    async _writeFile(path, content) {
         this._assertWritableAbsolutePath(path);
         return this.#kernel.writeFile(path, content);
     }
-    async writeFiles(entries) {
+    async _writeFiles(entries) {
         const results = [];
         for (const entry of entries) {
             try {
@@ -1902,7 +2944,7 @@ export class AgentOs {
         }
         return results;
     }
-    async readFiles(paths) {
+    async _readFiles(paths) {
         const results = [];
         for (const path of paths) {
             try {
@@ -1931,18 +2973,18 @@ export class AgentOs {
         // exists() loop makes `mkdir -p` cost O(components * tree).
         await this.#kernel.mkdir(path);
     }
-    async mkdir(path, options) {
+    async _mkdir(path, options) {
         if (options?.recursive) {
             return this._mkdirp(path);
         }
         this._assertSafeAbsolutePath(path);
         return this.#kernel.mkdir(path);
     }
-    async readdir(path) {
+    async _readdir(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.readdir(path);
     }
-    async readdirEntries(path) {
+    async _readdirEntries(path) {
         this._assertSafeAbsolutePath(path);
         const entries = await this.#kernel.readdirRecursive(path, { maxDepth: 0 });
         return entries.map((entry) => ({
@@ -1951,7 +2993,7 @@ export class AgentOs {
             isSymbolicLink: entry.isSymbolicLink,
         }));
     }
-    async readdirRecursive(path, options) {
+    async _readdirRecursive(path, options) {
         this._assertSafeAbsolutePath(path);
         const exclude = options?.exclude ? new Set(options.exclude) : undefined;
         const entries = await this.#kernel.readdirRecursive(path, {
@@ -1981,15 +3023,15 @@ export class AgentOs {
         }
         return results;
     }
-    async stat(path) {
+    async _stat(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.stat(path);
     }
-    async exists(path) {
+    async _exists(path) {
         this._assertSafeAbsolutePath(path);
         return this.#kernel.exists(path);
     }
-    async exportRootFilesystem(options) {
+    async _exportRootFilesystem(options) {
         if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
             throw new RangeError("maxBytes must be a positive safe integer");
         }
@@ -2009,7 +3051,7 @@ export class AgentOs {
      * after the returned promise settles; a delivery failure rejects instead of
      * leaving the mount silently host-only.
      */
-    async mountFs(descriptor) {
+    async _mountFs(descriptor) {
         this._assertSafeAbsolutePath(descriptor.path);
         if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
             throw new Error("portable dynamic mounts require the native sidecar");
@@ -2023,30 +3065,94 @@ export class AgentOs {
             },
         });
     }
-    async unmountFs(path) {
+    async _unmountFs(path) {
         this._assertSafeAbsolutePath(path);
         if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
             throw new Error("portable dynamic mounts require the native sidecar");
         }
         await this.#kernel.unmountDescriptor(path);
     }
-    async listMounts() {
+    async _listMounts() {
         if (!(this.#kernel instanceof NativeSidecarKernelProxy))
             return [];
         return this.#kernel.listMounts();
     }
-    async move(from, to) {
+    async _move(from, to) {
         this._assertWritableAbsolutePath(from);
         this._assertWritableAbsolutePath(to);
         await this.#kernel.movePath(from, to);
     }
-    async remove(path, options) {
+    async _remove(path, options) {
         this._assertWritableAbsolutePath(path);
         await this.#kernel.removePath(path, {
             recursive: options?.recursive ?? false,
         });
     }
-    async httpRequest(request) {
+    /** @deprecated Use `filesystem.readFile()`. */
+    readFile(path) {
+        return this.filesystem.readFile(path);
+    }
+    /** @deprecated Use `filesystem.writeFile()`. */
+    writeFile(path, content) {
+        return this.filesystem.writeFile(path, content);
+    }
+    /** @deprecated Use `filesystem.writeFiles()`. */
+    writeFiles(entries) {
+        return this.filesystem.writeFiles(entries);
+    }
+    /** @deprecated Use `filesystem.readFiles()`. */
+    readFiles(paths) {
+        return this.filesystem.readFiles(paths);
+    }
+    /** @deprecated Use `filesystem.mkdir()`. */
+    mkdir(path, options) {
+        return this.filesystem.mkdir(path, options);
+    }
+    /** @deprecated Use `filesystem.readdir()`. */
+    readdir(path) {
+        return this.filesystem.readdir(path);
+    }
+    /** @deprecated Use `filesystem.readdirEntries()`. */
+    readdirEntries(path) {
+        return this.filesystem.readdirEntries(path);
+    }
+    /** @deprecated Use `filesystem.readdirRecursive()`. */
+    readdirRecursive(path, options) {
+        return this.filesystem.readdirRecursive(path, options);
+    }
+    /** @deprecated Use `filesystem.stat()`. */
+    stat(path) {
+        return this.filesystem.stat(path);
+    }
+    /** @deprecated Use `filesystem.exists()`. */
+    exists(path) {
+        return this.filesystem.exists(path);
+    }
+    /** @deprecated Use `filesystem.export()`. */
+    exportRootFilesystem(options) {
+        return this.filesystem.export(options);
+    }
+    /** @deprecated Use `filesystem.mount()`. */
+    mountFs(descriptor) {
+        return this.filesystem.mount(descriptor);
+    }
+    /** @deprecated Use `filesystem.unmount()`. */
+    unmountFs(path) {
+        return this.filesystem.unmount(path);
+    }
+    /** @deprecated Use `filesystem.listMounts()`. */
+    listMounts() {
+        return this.filesystem.listMounts();
+    }
+    /** @deprecated Use `filesystem.move()`. */
+    move(from, to) {
+        return this.filesystem.move(from, to);
+    }
+    /** @deprecated Use `filesystem.remove()`. */
+    remove(path, options) {
+        return this.filesystem.remove(path, options);
+    }
+    async _httpRequest(request) {
         this._assertSafeAbsolutePath(request.path.split("?")[0] || "/");
         const method = request.method?.toUpperCase() ?? "GET";
         const body = typeof request.body === "string"
@@ -2074,9 +3180,13 @@ export class AgentOs {
             body: new Uint8Array(Buffer.from(responsePayload.body ?? "", "base64")),
         };
     }
+    /** @deprecated Use `network.httpRequest()`. */
+    httpRequest(request) {
+        return this.network.httpRequest(request);
+    }
     /**
      * Fetch an HTTP endpoint inside the VM while preserving duplicate response
-     * headers and arbitrary binary bodies. AgentOS Apps uses this compatibility
+     * headers and arbitrary binary bodies. agentOS Apps uses this compatibility
      * surface for its direct actor API.
      */
     async fetch(port, request) {
@@ -2142,7 +3252,7 @@ export class AgentOs {
             streamId,
         });
     }
-    openShell(options) {
+    _openTerminal(options) {
         const shellId = `shell-${++this._shellCounter}`;
         this._closedShellIds.delete(shellId);
         const dataHandlers = new Set();
@@ -2193,7 +3303,7 @@ export class AgentOs {
         return this.#kernel.connectTerminal(options);
     }
     /** Write data to a shell's PTY input. */
-    writeShell(shellId, data) {
+    _writeTerminal(shellId, data) {
         const entry = this._shells.get(shellId);
         if (!entry)
             throw new Error(`Shell not found: ${shellId}`);
@@ -2236,7 +3346,7 @@ export class AgentOs {
         return () => entry.exitHandlers.delete(handler);
     }
     /** Notify a shell of terminal resize. */
-    resizeShell(shellId, cols, rows) {
+    _resizeTerminal(shellId, cols, rows) {
         const entry = this._shells.get(shellId);
         if (!entry)
             throw new Error(`Shell not found: ${shellId}`);
@@ -2247,7 +3357,7 @@ export class AgentOs {
      * immediately for a shell that has already exited (within the closed-shell
      * retention window).
      */
-    waitShell(shellId) {
+    _waitTerminal(shellId) {
         const entry = this._shells.get(shellId);
         if (!entry) {
             const exitCode = this._closedShellIds.get(shellId);
@@ -2258,7 +3368,7 @@ export class AgentOs {
         return entry.exitPromise;
     }
     /** Kill a shell process and remove it from tracking. */
-    closeShell(shellId) {
+    _closeTerminal(shellId) {
         const entry = this._shells.get(shellId);
         if (!entry) {
             if (this._closedShellIds.has(shellId)) {
@@ -2270,6 +3380,26 @@ export class AgentOs {
         this._shells.delete(shellId);
         this._closedShellIds.add(shellId);
     }
+    /** @deprecated Use `terminal.open()`. */
+    openShell(options) {
+        return this.terminal.open(options);
+    }
+    /** @deprecated Use `terminal.write()`. */
+    writeShell(shellId, data) {
+        return this.terminal.write(shellId, data);
+    }
+    /** @deprecated Use `terminal.resize()`. */
+    resizeShell(shellId, cols, rows) {
+        this.terminal.resize(shellId, cols, rows);
+    }
+    /** @deprecated Use `terminal.wait()`. */
+    waitShell(shellId) {
+        return this.terminal.wait(shellId);
+    }
+    /** @deprecated Use `terminal.close()`. */
+    closeShell(shellId) {
+        this.terminal.close(shellId);
+    }
     _resolveVmPathToHostPath(vmPath) {
         const normalizedVmPath = posixPath.normalize(vmPath);
         for (const mount of this._hostMounts) {
@@ -2285,34 +3415,51 @@ export class AgentOs {
         return null;
     }
     /** Returns info about all processes spawned via spawn(). */
-    listProcesses() {
-        return [...this._processes.values()].map(({ proc, command, args }) => ({
-            pid: proc.pid,
-            command,
-            args,
-            running: proc.exitCode === null,
-            exitCode: proc.exitCode,
-        }));
+    async _listProcesses() {
+        return [
+            ...[...this._processes.values()].map(({ proc, command, startedAtMs }) => ({
+                pid: proc.pid,
+                command,
+                state: proc.exitCode === null ? "running" : "exited",
+                startedAtMs,
+            })),
+            ...[...this._languageProcesses.values()].map((entry) => entry.descriptor),
+        ];
     }
     /** Returns all kernel processes across all active runtimes (WASM and Node). */
-    allProcesses() {
+    _listAllProcesses() {
         if (this.#kernel instanceof NativeSidecarKernelProxy) {
             return this.#kernel.snapshotProcesses();
         }
         return [...this.#kernel.processes.values()];
     }
     /** Returns processes organized as a tree using ppid relationships. */
-    processTree() {
-        const all = this.allProcesses();
+    async _processTree() {
+        const all = this._listAllProcesses();
         const nodeMap = new Map();
         // Index: create a tree node for each process
         for (const proc of all) {
-            nodeMap.set(proc.pid, { ...proc, children: [] });
+            nodeMap.set(proc.pid, {
+                pid: proc.pid,
+                ppid: proc.ppid,
+                command: proc.command,
+                state: proc.status,
+                startedAtMs: proc.startTime,
+                children: [],
+            });
+        }
+        for (const process of this._languageProcesses.values()) {
+            if (!nodeMap.has(process.descriptor.pid)) {
+                nodeMap.set(process.descriptor.pid, {
+                    ...process.descriptor,
+                    children: [],
+                });
+            }
         }
         // Wire: attach each node to its parent
         const roots = [];
         for (const node of nodeMap.values()) {
-            const parent = nodeMap.get(node.ppid);
+            const parent = node.ppid === undefined ? undefined : nodeMap.get(node.ppid);
             if (parent) {
                 parent.children.push(node);
             }
@@ -2323,7 +3470,10 @@ export class AgentOs {
         return roots;
     }
     /** Returns info about a specific process by PID. Throws if not found. */
-    getProcess(pid) {
+    async _getProcess(pid) {
+        const language = this._languageProcesses.get(pid);
+        if (language)
+            return language.descriptor;
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
@@ -2331,32 +3481,76 @@ export class AgentOs {
         return {
             pid: entry.proc.pid,
             command: entry.command,
-            args: entry.args,
-            running: entry.proc.exitCode === null,
-            exitCode: entry.proc.exitCode,
+            state: entry.proc.exitCode === null ? "running" : "exited",
+            startedAtMs: entry.startedAtMs,
         };
     }
-    /** Send SIGTERM to gracefully stop a process. No-op if already exited. */
-    stopProcess(pid) {
+    async _signalProcess(pid, signal) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            language.signal = signal;
+            await this._signalExecution(language.executionId, signal);
+            return;
+        }
         const entry = this._processes.get(pid);
         if (!entry) {
             throw new Error(`Process not found: ${pid}`);
         }
         if (entry.proc.exitCode !== null)
             return;
-        entry.proc.kill();
+        entry.signal = signal;
+        const number = signal === "SIGKILL" ? 9 : signal === "SIGINT" ? 2 : 15;
+        entry.proc.kill(number);
     }
     /** Send SIGKILL to force-kill a process. No-op if already exited. */
-    killProcess(pid) {
+    async _killProcess(pid) {
+        await this._signalProcess(pid, "SIGKILL");
+    }
+    async _resizeProcessPty(pid, size) {
+        const language = this._languageProcesses.get(pid);
+        if (!language) {
+            throw new Error(`Process ${pid} does not have a managed PTY`);
+        }
+        await this._resizeExecutionPty(language.executionId, size);
+    }
+    async _readProcessOutput(pid, options = {}) {
+        const language = this._languageProcesses.get(pid);
+        if (language) {
+            const page = await this._readExecutionOutput(language.executionId, {
+                cursor: options.after === undefined ? undefined : `1:${options.after + 1}`,
+            });
+            return {
+                pid,
+                events: page.events.map((event) => ({
+                    pid,
+                    sequence: event.sequence,
+                    channel: event.channel,
+                    chunk: event.chunk,
+                    timestampMs: event.timestampMs,
+                })),
+                nextCursor: page.nextCursor,
+                hasMore: page.hasMore,
+                truncated: page.truncated,
+            };
+        }
         const entry = this._processes.get(pid);
-        if (!entry) {
+        if (!entry)
             throw new Error(`Process not found: ${pid}`);
+        if (!entry.retainEvents) {
+            throw new Error(`Process ${pid} was not spawned with output.retainEvents enabled`);
         }
-        if (entry.proc.exitCode !== null)
-            return;
-        entry.proc.kill(9);
+        const after = options.after ?? -1;
+        const events = entry.events.filter((event) => event.sequence > after);
+        return {
+            pid,
+            events,
+            nextCursor: String(events.at(-1)?.sequence ?? after),
+            hasMore: false,
+            truncated: entry.events.length === PROCESS_OUTPUT_EVENT_LIMIT &&
+                after < (entry.events[0]?.sequence ?? 0) - 1,
+        };
     }
-    async openSession(input) {
+    async _openSession(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpOpenSessionRequest",
             val: {
@@ -2379,7 +3573,7 @@ export class AgentOs {
             throw new Error(`unexpected openSession response: ${response.tag}`);
         }
     }
-    async getSession(input) {
+    async _getSession(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpGetDurableSessionRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2389,7 +3583,7 @@ export class AgentOs {
         }
         return decodeDurableSessionInfo(response.val.session);
     }
-    async listSessions(input) {
+    async _listSessions(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpListDurableSessionsRequest",
             val: { cursor: input?.cursor ?? null, limit: input?.limit ?? null },
@@ -2402,7 +3596,7 @@ export class AgentOs {
             nextCursor: response.val.nextCursor,
         };
     }
-    async deleteSession(input = {}) {
+    async _deleteSession(input = {}) {
         const response = await this._sendAcpRequest({
             tag: "AcpDeleteSessionRequest",
             val: { sessionId: input.sessionId ?? null },
@@ -2411,7 +3605,7 @@ export class AgentOs {
             throw new Error(`unexpected deleteSession response: ${response.tag}`);
         }
     }
-    async unloadSession(input) {
+    async _unloadSession(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpUnloadSessionRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2420,7 +3614,7 @@ export class AgentOs {
             throw new Error(`unexpected unloadSession response: ${response.tag}`);
         }
     }
-    async prompt(input) {
+    async _prompt(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpPromptRequest",
             val: {
@@ -2438,7 +3632,7 @@ export class AgentOs {
             stopReason: response.val.stopReason,
         };
     }
-    async cancelPrompt(input) {
+    async _cancelPrompt(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpCancelPromptRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2452,7 +3646,7 @@ export class AgentOs {
         }
         return { status: response.val.status };
     }
-    async respondPermission(input) {
+    async _respondPermission(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpRespondPermissionRequest",
             val: {
@@ -2479,7 +3673,7 @@ export class AgentOs {
             reason: permissionTerminalReason(response.val.reason),
         };
     }
-    async readHistory(input) {
+    async _readHistory(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpReadHistoryRequest",
             val: {
@@ -2498,7 +3692,7 @@ export class AgentOs {
             hasMoreAfter: response.val.hasMoreAfter,
         };
     }
-    async getSessionConfig(input) {
+    async _getSessionConfig(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpGetSessionConfigRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2511,7 +3705,7 @@ export class AgentOs {
             options: JSON.parse(response.val.options),
         };
     }
-    async setSessionConfigOption(input) {
+    async _setSessionConfigOption(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpSetSessionConfigOptionRequest",
             val: {
@@ -2528,7 +3722,7 @@ export class AgentOs {
             options: JSON.parse(response.val.options),
         };
     }
-    async getSessionCapabilities(input) {
+    async _getSessionCapabilities(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpGetSessionCapabilitiesRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2540,7 +3734,7 @@ export class AgentOs {
             ? null
             : normalizeSessionCapabilities(JSON.parse(response.val.capabilities));
     }
-    async getSessionAgentInfo(input) {
+    async _getSessionAgentInfo(input) {
         const response = await this._sendAcpRequest({
             tag: "AcpGetSessionAgentInfoRequest",
             val: { sessionId: input?.sessionId ?? null },
@@ -2552,6 +3746,58 @@ export class AgentOs {
             ? null
             : JSON.parse(response.val.agentInfo);
     }
+    /** @deprecated Use `sessions.open()`. */
+    openSession(input) {
+        return this.sessions.open(input);
+    }
+    /** @deprecated Use `sessions.get()`. */
+    getSession(input) {
+        return this.sessions.get(input);
+    }
+    /** @deprecated Use `sessions.list()`. */
+    listSessions(input) {
+        return this.sessions.list(input);
+    }
+    /** @deprecated Use `sessions.delete()`. */
+    deleteSession(input = {}) {
+        return this.sessions.delete(input);
+    }
+    /** @deprecated Use `sessions.unload()`. */
+    unloadSession(input) {
+        return this.sessions.unload(input);
+    }
+    /** @deprecated Use `sessions.prompt()`. */
+    prompt(input) {
+        return this.sessions.prompt(input);
+    }
+    /** @deprecated Use `sessions.cancelPrompt()`. */
+    cancelPrompt(input) {
+        return this.sessions.cancelPrompt(input);
+    }
+    /** @deprecated Use `sessions.respondPermission()`. */
+    respondPermission(input) {
+        return this.sessions.respondPermission(input);
+    }
+    /** @deprecated Use `sessions.readHistory()`. */
+    readHistory(input) {
+        return this.sessions.readHistory(input);
+    }
+    /** @deprecated Use `sessions.getConfig()`. */
+    getSessionConfig(input) {
+        return this.sessions.getConfig(input);
+    }
+    /** @deprecated Use `sessions.setConfigOption()`. */
+    setSessionConfigOption(input) {
+        return this.sessions.setConfigOption(input);
+    }
+    /** @deprecated Use `sessions.getCapabilities()`. */
+    getSessionCapabilities(input) {
+        return this.sessions.getCapabilities(input);
+    }
+    /** @deprecated Use `sessions.getAgentInfo()`. */
+    getSessionAgentInfo(input) {
+        return this.sessions.getAgentInfo(input);
+    }
     /**
      * Dynamically link a software package into the RUNNING VM. The package's
      * `bin/` commands appear under `/opt/agentos/bin` (on `$PATH`) and its `share/man`
@@ -2560,7 +3806,7 @@ export class AgentOs {
      * block registers the package for `openSession({ agent: name })`. Persists for the VM's
      * lifetime (and across a snapshot iff the volume persists).
      */
-    async linkSoftware(descriptor) {
+    async _linkSoftware(descriptor) {
         // Forward to the sidecar, which owns the `/opt/agentos` projection and
         // appends the package to its live host-backed staging dir; the commands
         // appear under `/opt/agentos/bin` immediately. The sidecar rejects a
@@ -2580,7 +3826,7 @@ export class AgentOs {
         // picked up by the sidecar (it owns the projected `/opt/agentos` and answers
         // openSession/listAgents from it). Nothing to record client-side.
     }
-    async listSoftware() {
+    async _listSoftware() {
         return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
     }
     /**
@@ -2589,7 +3835,7 @@ export class AgentOs {
      * projected `/opt/agentos` packages (the client parses no manifests). Every such
      * agent is a package materialized into the VM, so `installed` is always `true`.
      */
-    async listAgents() {
+    async _listAgents() {
         const response = await this._sendAcpRequest({
             tag: "AcpListAgentsRequest",
             val: { reserved: false },
@@ -2602,6 +3848,18 @@ export class AgentOs {
             installed: agent.installed,
         }));
     }
+    /** @deprecated Use `software.link()`. */
+    linkSoftware(descriptor) {
+        return this.software.link(descriptor);
+    }
+    /** @deprecated Use `software.list()`. */
+    listSoftware() {
+        return this.software.list();
+    }
+    /** @deprecated Use `agents.list()`. */
+    listAgents() {
+        return this.agents.list();
+    }
     _recordAgentStderr(event) {
         if (!event.sessionId) {
             return;
@@ -2655,6 +3913,81 @@ export class AgentOs {
         }
     }
     _handleSidecarEvent(event) {
+        if (event.payload.type === "execution_output") {
+            const output = mapExecutionOutputEvent(event.payload.event);
+            const pid = this._languageProcessIds.get(output.executionId);
+            if (pid !== undefined) {
+                const process = this._languageProcesses.get(pid);
+                if (process) {
+                    const publicOutput = {
+                        pid,
+                        stream: output.channel === "stderr" ? "stderr" : "stdout",
+                        data: output.chunk,
+                    };
+                    for (const handler of process.outputHandlers) {
+                        try {
+                            handler(publicOutput);
+                        }
+                        catch (error) {
+                            console.error("AgentOS process output handler failed", error);
+                        }
+                    }
+                }
+            }
+            for (const key of ["*", output.executionId]) {
+                for (const handler of this._executionOutputHandlers.get(key) ?? []) {
+                    try {
+                        handler(output);
+                    }
+                    catch (error) {
+                        console.error("AgentOS execution output handler failed", error);
+                    }
+                }
+            }
+            return;
+        }
+        if (event.payload.type === "execution_completed") {
+            const completed = mapExecutionCompletedEvent(event.payload.event);
+            const pid = this._languageProcessIds.get(completed.executionId);
+            if (pid !== undefined) {
+                const process = this._languageProcesses.get(pid);
+                if (process && !process.exit) {
+                    const exit = {
+                        pid,
+                        outcome: completed.outcome === "timed_out"
+                            ? "timed_out"
+                            : completed.outcome === "cancelled"
+                                ? "signalled"
+                                : "exited",
+                        ...(completed.exitCode !== undefined
+                            ? { exitCode: completed.exitCode }
+                            : {}),
+                        ...(process.signal ? { signal: process.signal } : {}),
+                    };
+                    process.exit = exit;
+                    process.descriptor = { ...process.descriptor, state: "exited" };
+                    for (const handler of process.exitHandlers) {
+                        try {
+                            handler(exit);
+                        }
+                        catch (error) {
+                            console.error("AgentOS process exit handler failed", error);
+                        }
+                    }
+                }
+            }
+            for (const key of ["*", completed.executionId]) {
+                for (const handler of this._executionCompletedHandlers.get(key) ?? []) {
+                    try {
+                        handler(completed);
+                    }
+                    catch (error) {
+                        console.error("AgentOS execution completion handler failed", error);
+                    }
+                }
+            }
+            return;
+        }
         if (event.payload.type === "ext") {
             this._handleAcpExtEvent(event.payload.envelope);
             return;
@@ -3056,12 +4389,12 @@ export class AgentOs {
         this._acpTerminals.set(terminalId, terminal);
         return { terminalId };
     }
-    _handleAcpWriteTerminal(params) {
+    async _handleAcpWriteTerminal(params) {
         const method = "terminal/write";
         const terminal = this._requireAcpTerminal(params, method);
         const data = this._requireAcpStringParam(params, "data", method);
         const encoding = this._optionalAcpStringParam(params, "encoding", method);
-        terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
+        await terminal.handle.write(encoding === "base64" ? Buffer.from(data, "base64") : data);
         return null;
     }
     _handleAcpReadTerminal(params) {
@@ -3151,17 +4484,29 @@ export class AgentOs {
     }
     // ── Cron ────────────────────────────────────────────────────
     /** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
-    scheduleCron(options) {
+    _scheduleCron(options) {
         return this._cronManager.schedule(options);
     }
     /** List all registered cron jobs. */
-    listCronJobs() {
+    _listCronJobs() {
         return this._cronManager.list();
     }
     /** Cancel a cron job by ID. */
-    cancelCronJob(id) {
+    _cancelCronJob(id) {
         this._cronManager.cancel(id);
     }
+    /** @deprecated Use `cron.schedule()`. */
+    scheduleCron(options) {
+        return this.cron.schedule(options);
+    }
+    /** @deprecated Use `cron.list()`. */
+    listCronJobs() {
+        return this.cron.list();
+    }
+    /** @deprecated Use `cron.cancel()`. */
+    cancelCronJob(id) {
+        this.cron.cancel(id);
+    }
     /** Subscribe to cron lifecycle events (fire, complete, error). */
     onCronEvent(handler) {
         this._cronManager.onEvent(handler);
@@ -3180,6 +4525,8 @@ export class AgentOs {
         }
         this._acpTerminals.clear();
         this._processes.clear();
+        this._executionOutputHandlers.clear();
+        this._executionCompletedHandlers.clear();
         await waitForTrackedExitPromises([...shellExitPromises, ...terminalExitPromises], SHELL_DISPOSE_TIMEOUT_MS);
         this._disposeSidecarEventListener();
         const sidecarLease = this._sidecarLease;