@rivet-dev/agentos-core0.4.9174.9 kB
import { execFileSync } from "node:child_process";
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 { hostFunctionDescription, resolveHostFunctions, } from "@rivet-dev/agentos-runtime-core/host-functions";
import { zodToJsonSchema } from "@rivet-dev/agentos-runtime-core/host-functions-zod";
import { parseAgentOsOptions } from "./options-schema.js";
import { buildProcessForest } from "./process-forest.js";
import { getSandboxDisposeHooks, resolveSandboxOptions, } from "./sandbox.js";
import { resolvePublishedSidecarBinary } from "./sidecar/binary.js";
import { replayPage, replayPageLimits, replayWirePageLimits, } from "./output-replay.js";
import { findCargoBinary, resolveCargoBinary } from "./sidecar/cargo.js";
const VM_DISPOSE_DRAIN_TIMEOUT_MS = 5_000;
async function waitForTrackedExitPromises(promises, timeoutMs) {
if (promises.length === 0) {
return;
}
await Promise.race([
Promise.allSettled(promises).then(() => undefined),
new Promise((resolve) => {
setTimeout(resolve, timeoutMs);
}),
]);
}
function headersToRecord(headers) {
const result = {};
headers.forEach((value, name) => {
result[name] = value;
});
return result;
}
import { OPT_AGENTOS_ROOT, } from "./agentos-package.js";
import { getBaseEnvironment } from "./base-filesystem.js";
import { CronManager } from "./cron/cron-manager.js";
import { TimerScheduleDriver } from "./cron/timer-driver.js";
import { resolveDefaultSoftware } from "./default-software.js";
import { snapshotVirtualFilesystem, sortFilesystemEntries, } from "./filesystem-snapshot.js";
import { serializeMountConfigForSidecar, } from "./js-bridge.js";
import { createSnapshotExport, } from "./layers.js";
import { allowAll } from "./runtime-compat.js";
import { serializePermissionsForSidecar } from "./sidecar/permissions.js";
import { createAgentOsSidecarClient, NativeSidecarKernelProxy, SidecarProcess, serializeRootFilesystemForSidecar, } from "./sidecar/rpc-client.js";
import { resolveRegistrySoftware, } from "./software-registry.js";
function toRecord(value) {
return value && typeof value === "object" && !Array.isArray(value)
? value
: {};
}
function normalizePackageRef(value) {
// The single package reference is `packagePath`: the packed `.aospkg` file
// (registry-built packages export `{ packagePath }`), or a package dir for
// local transition fixtures. A raw string is shorthand for the same path.
if (typeof value === "string") {
return { path: value };
}
const record = toRecord(value);
if (typeof record.packagePath === "string") {
return { path: record.packagePath };
}
// Recognizably-legacy shapes fail loudly: silently dropping a software
// entry boots a VM with missing packages and no diagnostic.
for (const legacy of ["packageTar", "packageDir", "dir"]) {
if (typeof record[legacy] === "string") {
throw new Error(`agentOS package ref uses removed field "${legacy}" (value: ${JSON.stringify(record[legacy])}); ` +
"packages are referenced by a single `packagePath` — update the package " +
"(rebuild @agentos-software/* dependencies) or pass { packagePath }");
}
}
return undefined;
}
// Every create-time entry must be recognized: silently dropping one would boot
// a VM without the package and with no diagnostic.
function classifySoftwareEntry(entry) {
const ref = normalizePackageRef(entry);
if (ref)
return { kind: "path", path: ref.path };
const record = toRecord(entry);
if (typeof record.registry === "string") {
if (record.version !== undefined && typeof record.version !== "string") {
throw new Error(`agentOS \`software\` registry entry "${record.registry}" has a non-string version; pass { registry, version: "0.4.2" }`);
}
return {
kind: "registry",
name: record.registry,
...(record.version !== undefined
? { version: record.version }
: {}),
};
}
if (typeof record.url === "string") {
if (record.digest !== undefined && typeof record.digest !== "string") {
throw new Error(`agentOS \`software\` URL entry ${record.url} has a non-string digest; pass { url, digest: "sha256:<64 lowercase hex>" }`);
}
return {
kind: "url",
url: record.url,
...(record.digest !== undefined
? { digest: record.digest }
: {}),
};
}
throw new Error(`agentOS \`software\` entry is not a package ref (got ${entry === null ? "null" : typeof entry}); pass { packagePath }, { registry: "<name>" }, or { url, digest }`);
}
function packageResolverWireOptions(options) {
if (!options)
return {};
return {
...(options.maxPackageBytes !== undefined
? { max_package_bytes: BigInt(options.maxPackageBytes) }
: {}),
...(options.downloadTimeoutMs !== undefined
? { download_timeout_ms: BigInt(options.downloadTimeoutMs) }
: {}),
...(options.connectTimeoutMs !== undefined
? { connect_timeout_ms: BigInt(options.connectTimeoutMs) }
: {}),
...(options.maxRedirects !== undefined
? { max_redirects: options.maxRedirects }
: {}),
...(options.allowInsecureLocalHttp !== undefined
? { allow_insecure_local_http: options.allowInsecureLocalHttp }
: {}),
};
}
const CLOSED_SHELL_ID_RETENTION_LIMIT = 2048;
const TERMINAL_LIMIT = 1024;
const PROCESS_REGISTRY_LIMIT = 1024;
class BoundedSet {
limit;
#entries = new Map();
constructor(limit) {
if (!Number.isInteger(limit) || limit <= 0) {
throw new Error(`BoundedSet limit must be a positive integer: ${limit}`);
}
this.limit = limit;
}
add(value, associated) {
if (this.#entries.has(value)) {
this.#entries.delete(value);
}
this.#entries.set(value, associated);
if (this.#entries.size <= this.limit) {
return;
}
const oldest = this.#entries.keys().next();
if (!oldest.done) {
this.#entries.delete(oldest.value);
}
}
has(value) {
return this.#entries.has(value);
}
get(value) {
return this.#entries.get(value);
}
delete(value) {
return this.#entries.delete(value);
}
get size() {
return this.#entries.size;
}
}
function isOverlayMountConfig(config) {
return "filesystem" in config;
}
function isNativeMountConfig(config) {
return "plugin" in config;
}
function asMountConfigJsonObject(value) {
if (value && typeof value === "object" && !Array.isArray(value)) {
return value;
}
return {};
}
function getHostDirMountPluginConfig(config) {
const object = asMountConfigJsonObject(config);
if (typeof object.hostPath !== "string") {
return null;
}
const hostPathConfig = {
hostPath: object.hostPath,
};
if (typeof object.readOnly === "boolean") {
hostPathConfig.readOnly = object.readOnly;
}
return hostPathConfig;
}
function getSandboxAgentMountPluginConfig(config) {
const object = asMountConfigJsonObject(config);
if (typeof object.baseUrl !== "string") {
return null;
}
const sandboxConfig = {
baseUrl: object.baseUrl,
};
if (typeof object.token === "string") {
sandboxConfig.token = object.token;
}
if (typeof object.basePath === "string") {
sandboxConfig.basePath = object.basePath;
}
if (typeof object.timeoutMs === "number") {
sandboxConfig.timeoutMs = object.timeoutMs;
}
if (typeof object.maxFullReadBytes === "number") {
sandboxConfig.maxFullReadBytes = object.maxFullReadBytes;
}
if (object.headers &&
typeof object.headers === "object" &&
!Array.isArray(object.headers)) {
const headers = Object.entries(object.headers)
.filter(([, value]) => typeof value === "string")
.map(([name, value]) => [name, value]);
if (headers.length > 0) {
sandboxConfig.headers = Object.fromEntries(headers);
}
}
return sandboxConfig;
}
function getS3MountPluginConfig(config) {
const object = asMountConfigJsonObject(config);
if (typeof object.bucket !== "string") {
return null;
}
const s3Config = {
bucket: object.bucket,
};
if (typeof object.prefix === "string") {
s3Config.prefix = object.prefix;
}
if (typeof object.region === "string") {
s3Config.region = object.region;
}
if (typeof object.endpoint === "string") {
s3Config.endpoint = object.endpoint;
}
if (typeof object.chunkSize === "number") {
s3Config.chunkSize = object.chunkSize;
}
if (typeof object.inlineThreshold === "number") {
s3Config.inlineThreshold = object.inlineThreshold;
}
if (object.credentials &&
typeof object.credentials === "object" &&
!Array.isArray(object.credentials) &&
typeof object.credentials.accessKeyId === "string" &&
typeof object.credentials.secretAccessKey === "string") {
s3Config.credentials = {
accessKeyId: object.credentials.accessKeyId,
secretAccessKey: object.credentials.secretAccessKey,
};
}
return s3Config;
}
function getGoogleDriveMountPluginConfig(config) {
const object = asMountConfigJsonObject(config);
if (typeof object.folderId !== "string") {
return null;
}
if (!object.credentials ||
typeof object.credentials !== "object" ||
Array.isArray(object.credentials) ||
typeof object.credentials.clientEmail !== "string" ||
typeof object.credentials.privateKey !== "string") {
return null;
}
const googleDriveConfig = {
credentials: {
clientEmail: object.credentials.clientEmail,
privateKey: object.credentials.privateKey,
},
folderId: object.folderId,
};
if (typeof object.keyPrefix === "string") {
googleDriveConfig.keyPrefix = object.keyPrefix;
}
if (typeof object.chunkSize === "number") {
googleDriveConfig.chunkSize = object.chunkSize;
}
if (typeof object.inlineThreshold === "number") {
googleDriveConfig.inlineThreshold = object.inlineThreshold;
}
return googleDriveConfig;
}
const KERNEL_POSIX_BOOTSTRAP_DIRS = [
"/dev",
"/proc",
"/tmp",
"/bin",
"/lib",
"/sbin",
"/boot",
"/etc",
"/root",
"/run",
"/srv",
"/sys",
"/opt",
"/mnt",
"/media",
"/home",
"/home/agentos",
"/workspace",
"/usr",
"/usr/bin",
"/usr/games",
"/usr/include",
"/usr/lib",
"/usr/libexec",
"/usr/man",
"/usr/local",
"/usr/local/bin",
"/usr/sbin",
"/usr/share",
"/usr/share/man",
"/var",
"/var/cache",
"/var/empty",
"/var/lib",
"/var/lock",
"/var/log",
"/var/run",
"/var/spool",
"/var/tmp",
"/etc/agentos",
];
// Standard POSIX metadata for the bootstrap dirs whose mode/owner is NOT the
// default (`755`, root:root). Replicated as a constant so building the no-base
// bootstrap layer needs no `base-filesystem.json` read — when a base IS present
// the sidecar's embedded base layer is authoritative and these are never emitted.
const KERNEL_POSIX_BOOTSTRAP_DIR_METADATA = {
"/tmp": { mode: "1777", uid: 0, gid: 0 },
"/root": { mode: "700", uid: 0, gid: 0 },
"/sys": { mode: "555", uid: 0, gid: 0 },
"/home/agentos": { mode: "2755", uid: 1000, gid: 1000 },
"/workspace": { mode: "755", uid: 1000, gid: 1000 },
"/var/empty": { mode: "555", uid: 0, gid: 0 },
"/var/lock": { mode: "777", uid: 0, gid: 0 },
"/var/run": { mode: "777", uid: 0, gid: 0 },
"/var/tmp": { mode: "1777", uid: 0, gid: 0 },
};
const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
const SIDECAR_BINARY = join(REPO_ROOT, "target/debug/agentos-native-sidecar");
const SIDECAR_BUILD_INPUTS = [
join(REPO_ROOT, "Cargo.toml"),
join(REPO_ROOT, "Cargo.lock"),
join(REPO_ROOT, "crates/bridge"),
join(REPO_ROOT, "crates/build-support"),
join(REPO_ROOT, "crates/execution"),
join(REPO_ROOT, "crates/kernel"),
join(REPO_ROOT, "crates/native-sidecar"),
join(REPO_ROOT, "crates/native-sidecar-core"),
join(REPO_ROOT, "crates/sidecar-protocol"),
join(REPO_ROOT, "crates/v8-runtime"),
join(REPO_ROOT, "crates/vfs"),
join(REPO_ROOT, "crates/vm-config"),
join(REPO_ROOT, "packages/build-tools/bridge-src"),
join(REPO_ROOT, "packages/build-tools/package.json"),
join(REPO_ROOT, "packages/build-tools/scripts/build-v8-bridge.mjs"),
join(REPO_ROOT, "packages/core/fixtures/base-filesystem.json"),
join(REPO_ROOT, "packages/runtime-core/fixtures/base-filesystem.json"),
join(REPO_ROOT, "pnpm-lock.yaml"),
];
let ensuredSidecarBinary = null;
function collectConfiguredLowerPaths(config) {
const paths = new Set();
for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
if (lower.kind !== "snapshot-export") {
continue;
}
for (const entry of lower.source.filesystem.entries) {
paths.add(entry.path);
}
}
return paths;
}
function findBootstrapSeedEntry(config, path) {
for (const lower of config?.type === "native" ? [] : (config?.lowers ?? [])) {
if (lower.kind !== "snapshot-export") {
continue;
}
const entry = lower.source.filesystem.entries.find((candidate) => candidate.path === path);
if (entry) {
return entry;
}
}
// No base-filesystem JSON read: standard non-default dir metadata comes from
// the constant table. When a base layer IS present these dirs are never
// emitted (see createKernelBootstrapLower), so this only seeds the no-base case.
const meta = KERNEL_POSIX_BOOTSTRAP_DIR_METADATA[path];
return meta ? { path, type: "directory", ...meta } : undefined;
}
function createKernelBootstrapLower(config, extraEntries = []) {
if (config?.type === "native") {
return null;
}
const includesBundledBaseLayer = !(config?.disableDefaultBaseLayer ?? false);
const existingPaths = collectConfiguredLowerPaths(config);
const entries = [
{
path: "/",
type: "directory",
mode: "755",
uid: 0,
gid: 0,
},
];
// Only run the FS bootstrap (creating the POSIX dir tree) when there is NO
// base layer. When the bundled base IS present, the sidecar's embedded base
// layer already provides every POSIX dir with the correct mode/owner, so we
// emit nothing here and never read its filesystem table.
if (!includesBundledBaseLayer) {
for (const dir of KERNEL_POSIX_BOOTSTRAP_DIRS) {
if (existingPaths.has(dir)) {
continue;
}
const seed = findBootstrapSeedEntry(config, dir);
entries.push({
path: dir,
type: "directory",
mode: seed?.type === "directory" ? seed.mode : "755",
uid: seed?.uid ?? 0,
gid: seed?.gid ?? 0,
});
}
}
if (!includesBundledBaseLayer && !existingPaths.has("/usr/bin/env")) {
entries.push({
path: "/usr/bin/env",
type: "file",
mode: "644",
uid: 0,
gid: 0,
content: "AA==",
encoding: "base64",
});
}
for (const entry of sortFilesystemEntries(extraEntries)) {
if (existingPaths.has(entry.path)) {
continue;
}
entries.push(entry);
}
return entries.length > 1 ? createSnapshotExport(entries) : null;
}
function toSnapshotModeString(mode, kind) {
const fallback = kind === "directory" ? 0o755 : kind === "symlink" ? 0o777 : 0o644;
return `0${((mode ?? fallback) & 0o7777).toString(8)}`;
}
function convertSidecarRootSnapshotEntries(entries) {
return entries.map((entry) => {
const baseEntry = {
path: entry.path,
type: entry.kind,
mode: toSnapshotModeString(entry.mode, entry.kind),
uid: entry.uid ?? 0,
gid: entry.gid ?? 0,
};
if (entry.kind === "file") {
return {
...baseEntry,
content: entry.content ?? "",
encoding: entry.encoding ?? "utf8",
};
}
if (entry.kind === "symlink") {
if (entry.target === undefined) {
throw new Error(`sidecar root snapshot for ${entry.path} is missing a symlink target`);
}
return {
...baseEntry,
target: entry.target,
};
}
return baseEntry;
});
}
function ensureNativeSidecarBinary() {
// A published install has no in-repo Cargo workspace to build from: resolve
// the prebuilt platform binary (or the AGENTOS_SIDECAR_BIN override).
if (process.env.AGENTOS_SIDECAR_BIN ||
!existsSync(join(REPO_ROOT, "Cargo.toml"))) {
return resolvePublishedSidecarBinary();
}
if (ensuredSidecarBinary &&
existsSync(ensuredSidecarBinary) &&
!sidecarBinaryNeedsBuild()) {
return ensuredSidecarBinary;
}
if (sidecarBinaryNeedsBuild()) {
const cargoBinary = findCargoBinary();
if (cargoBinary) {
execFileSync(cargoBinary, ["build", "-q", "-p", "agentos-native-sidecar"], {
cwd: REPO_ROOT,
stdio: "pipe",
});
}
else if (!existsSync(SIDECAR_BINARY)) {
execFileSync(resolveCargoBinary(), ["build", "-q", "-p", "agentos-native-sidecar"], {
cwd: REPO_ROOT,
stdio: "pipe",
});
}
}
ensuredSidecarBinary = SIDECAR_BINARY;
return ensuredSidecarBinary;
}
function sidecarBinaryNeedsBuild() {
if (!existsSync(SIDECAR_BINARY)) {
return true;
}
const binaryMtimeMs = statSync(SIDECAR_BINARY).mtimeMs;
return SIDECAR_BUILD_INPUTS.some((path) => existsSync(path) && latestMtimeMs(path) > binaryMtimeMs);
}
function latestMtimeMs(path) {
const stats = statSync(path);
if (!stats.isDirectory()) {
return stats.mtimeMs;
}
let latest = stats.mtimeMs;
for (const entry of readdirSync(path)) {
latest = Math.max(latest, latestMtimeMs(join(path, entry)));
}
return latest;
}
async function resolveCompatLocalMounts(mounts) {
if (!mounts) {
return [];
}
const resolved = [];
for (const mount of mounts) {
if (isNativeMountConfig(mount)) {
continue;
}
if (!isOverlayMountConfig(mount)) {
resolved.push({
path: posixPath.normalize(mount.path),
fs: mount.driver,
readOnly: mount.readOnly ?? false,
});
continue;
}
const mode = mount.filesystem.mode ?? "ephemeral";
const fs = mode === "read-only"
? mount.filesystem.store.createOverlayFilesystem({
mode: "read-only",
lowers: mount.filesystem.lowers,
})
: mount.filesystem.store.createOverlayFilesystem({
upper: await mount.filesystem.store.createWritableLayer(),
lowers: mount.filesystem.lowers,
});
resolved.push({
path: posixPath.normalize(mount.path),
fs,
readOnly: mode === "read-only",
});
}
return resolved;
}
function collectSidecarMountPlan(options) {
const sidecarMounts = [];
const hostMounts = [];
const hostPathMappings = [];
const seenMounts = new Set();
function pushMount(mount) {
const serialized = serializeMountConfigForSidecar(mount);
const key = `${serialized.guestPath}\0${serialized.plugin.id}\0${JSON.stringify(serialized.plugin.config)}`;
if (seenMounts.has(key)) {
return;
}
seenMounts.add(key);
sidecarMounts.push(serialized);
if (mount.plugin.id === "host_dir") {
const config = getHostDirMountPluginConfig(mount.plugin.config);
if (config) {
hostPathMappings.push({
vmPath: posixPath.normalize(mount.path),
hostPath: resolveHostPath(config.hostPath),
readOnly: mount.readOnly ?? config.readOnly ?? true,
});
}
if (config && options.mounts?.some((candidate) => candidate === mount)) {
hostMounts.push({
vmPath: posixPath.normalize(mount.path),
hostPath: resolveHostPath(config.hostPath),
readOnly: mount.readOnly ?? config.readOnly ?? true,
});
}
}
}
for (const mount of options.mounts ?? []) {
if (!isNativeMountConfig(mount)) {
sidecarMounts.push({
guestPath: mount.path,
readOnly: isOverlayMountConfig(mount)
? (mount.filesystem.mode ?? "ephemeral") === "read-only"
: (mount.readOnly ?? false),
plugin: {
id: "js_bridge",
config: {},
},
});
continue;
}
pushMount(mount);
}
hostMounts.sort((left, right) => right.vmPath.length - left.vmPath.length);
hostPathMappings.sort((left, right) => right.vmPath.length - left.vmPath.length);
return { sidecarMounts, hostMounts, hostPathMappings };
}
function collectHostFunctionBootstrapCommands(hostFunctions) {
if (hostFunctions.length === 0) {
return [];
}
return [
"agentos",
...hostFunctions.map((hostFunctionCollection) => `agentos-${hostFunctionCollection.name}`),
];
}
function validationMessage(error) {
if (typeof error === "object" &&
error !== null &&
"issues" in error &&
Array.isArray(error.issues)) {
return error.issues
.map((issue) => {
const path = Array.isArray(issue.path) && issue.path.length > 0
? ` at "${issue.path.join(".")}"`
: "";
return `${issue.message}${path}`;
})
.join("; ");
}
return error instanceof Error ? error.message : String(error);
}
function hostFunctionToSidecarDefinition(definition) {
return {
description: hostFunctionDescription(definition),
inputSchema: zodToJsonSchema(definition.inputSchema),
...(definition.timeout !== undefined
? { timeoutMs: definition.timeout }
: {}),
...(definition.examples && definition.examples.length > 0
? {
examples: definition.examples.map((example) => ({
description: example.description,
input: example.input,
})),
}
: {}),
};
}
function combineInstructions(additionalInstructions, hostFunctionReference) {
const parts = [additionalInstructions, hostFunctionReference]
.map((part) => part?.trim())
.filter((part) => Boolean(part));
if (parts.length === 0) {
return null;
}
return parts.join("\n\n");
}
function buildHostFunctionReference(hostFunctions) {
if (hostFunctions.length === 0) {
return "";
}
const lines = [
"## Available Host Functions",
"",
"Run `agentos list-host-functions` to see all available host functions.",
"",
];
for (const hostFunctionCollection of hostFunctions) {
lines.push(`### ${hostFunctionCollection.name}`);
lines.push("");
for (const [functionName, definition] of Object.entries(hostFunctionCollection.functions)) {
const sidecarHostFunction = hostFunctionToSidecarDefinition(definition);
const signature = buildHostFunctionFlagSignature(sidecarHostFunction.inputSchema);
const suffix = signature.length > 0 ? ` ${signature}` : "";
const description = hostFunctionDescription(definition);
lines.push(description.length > 0
? `- \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\` - ${description}`
: `- \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\``);
}
lines.push("");
const functionsWithExamples = Object.entries(hostFunctionCollection.functions).filter(([, definition]) => definition.examples && definition.examples.length > 0);
if (functionsWithExamples.length > 0) {
lines.push("**Examples:**");
lines.push("");
for (const [functionName, definition] of functionsWithExamples) {
for (const example of definition.examples ?? []) {
const args = inputToHostFunctionFlags(example.input);
const suffix = args.length > 0 ? ` ${args}` : "";
lines.push(`- ${example.description}: \`agentos-${hostFunctionCollection.name} ${functionName}${suffix}\``);
}
}
lines.push("");
}
lines.push(`Run \`agentos-${hostFunctionCollection.name} <function> --help\` for details.`);
lines.push("");
}
return lines.join("\n");
}
function buildHostFunctionFlagSignature(schema) {
return describeHostFunctionFlags(schema)
.map((flag) => {
if (flag.required) {
return `${flag.name} <${flag.type}>`;
}
return `[${flag.name} <${flag.type}>]`;
})
.join(" ");
}
function describeHostFunctionFlags(schema) {
const schemaObject = asRecord(schema);
const properties = asRecord(schemaObject.properties);
const required = Array.isArray(schemaObject.required)
? new Set(schemaObject.required.filter((item) => typeof item === "string"))
: new Set();
return Object.entries(properties).map(([fieldName, fieldSchema]) => ({
name: `--${camelToKebab(fieldName)}`,
type: describeHostFunctionFlagType(fieldSchema),
required: required.has(fieldName),
}));
}
function describeHostFunctionFlagType(schema) {
const schemaObject = asRecord(schema);
const type = typeof schemaObject.type === "string" ? schemaObject.type : undefined;
if (type === "array") {
const itemType = describeJsonSchemaScalarType(schemaObject.items);
return `${itemType}[]`;
}
if (type === "string") {
const enumValues = Array.isArray(schemaObject.enum)
? schemaObject.enum.filter((item) => typeof item === "string")
: [];
return enumValues.length > 0 ? enumValues.join("|") : "string";
}
return type ?? "string";
}
function describeJsonSchemaScalarType(schema) {
const schemaObject = asRecord(schema);
return typeof schemaObject.type === "string" ? schemaObject.type : "string";
}
function inputToHostFunctionFlags(input) {
const inputObject = asRecord(input);
return Object.entries(inputObject)
.flatMap(([key, value]) => {
const flag = `--${camelToKebab(key)}`;
if (value === true) {
return [flag];
}
if (value === false) {
return [`--no-${camelToKebab(key)}`];
}
if (Array.isArray(value)) {
return value.map((item) => `${flag} ${hostFunctionCliString(item)}`);
}
return [`${flag} ${hostFunctionCliString(value)}`];
})
.join(" ");
}
function hostFunctionCliString(value) {
return typeof value === "string" ? value : (JSON.stringify(value) ?? "null");
}
function camelToKebab(value) {
return value.replace(/[A-Z]/g, (ch, index) => `${index > 0 ? "-" : ""}${ch.toLowerCase()}`);
}
function asRecord(value) {
if (typeof value === "object" && value !== null && !Array.isArray(value)) {
return value;
}
return {};
}
async function handleHostCallback(request, context) {
const payload = request.payload;
if (payload.type !== "host_callback") {
return {
type: "host_callback_result",
invocation_id: "unknown",
error: `unsupported sidecar request type: ${payload.type}`,
};
}
if (payload.callback_key === "agentos") {
const command = parseHostCommandCallbackInput(payload.input);
if (!command || command.command !== payload.callback_key) {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
error: `Invalid registry callback for "${payload.callback_key}"`,
};
}
try {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
result: await handleHostCommandCallback(command, context),
};
}
catch (error) {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
error: validationMessage(error),
};
}
}
const definition = context.hostFunctionMap.get(payload.callback_key);
if (!definition) {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
error: `Unknown host function "${payload.callback_key}"`,
};
}
// The sidecar authorizes this exact callback key before forwarding it. Never
// reinterpret direct callback input as a registry command: a valid function
// schema may itself accept command-shaped data.
const parsed = definition.inputSchema.safeParse(payload.input);
if (!parsed.success) {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
error: validationMessage(parsed.error),
};
}
try {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
result: await executeHostFunction(definition, payload.callback_key, parsed.data),
};
}
catch (error) {
return {
type: "host_callback_result",
invocation_id: payload.invocation_id,
error: validationMessage(error),
};
}
}
function buildHostFunctionMap(hostFunctions) {
const hostFunctionMap = new Map();
for (const hostFunctionCollection of hostFunctions) {
for (const [functionName, definition] of Object.entries(hostFunctionCollection.functions)) {
hostFunctionMap.set(`${hostFunctionCollection.name}:${functionName}`, definition);
}
}
return hostFunctionMap;
}
function bridgeErrorMessage(error) {
return error instanceof Error ? error.message : String(error);
}
function toBridgeArgs(value) {
if (!value || typeof value !== "object" || Array.isArray(value)) {
throw new Error("js_bridge args must be an object");
}
return value;
}
function bridgePath(mountId, value) {
if (!mountId.startsWith("/")) {
throw new Error(`Unsupported js_bridge mount id: ${mountId}`);
}
if (typeof value !== "string") {
throw new Error("js_bridge path argument must be a string");
}
return posixPath.normalize(posixPath.join(mountId, value));
}
function requireBridgeNumber(value, field) {
if (typeof value !== "number" || !Number.isFinite(value)) {
throw new Error(`js_bridge args.${field} must be a number`);
}
return value;
}
function decodeBridgeBytes(value, field) {
if (typeof value === "string") {
return new Uint8Array(Buffer.from(value, "base64"));
}
if (Array.isArray(value) &&
value.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
return new Uint8Array(value);
}
throw new Error(`js_bridge args.${field} must be base64 bytes`);
}
async function handleJsBridgeCall(request, context) {
try {
const args = toBridgeArgs(request.args);
const fs = context.filesystem;
const path = () => bridgePath(request.mount_id, args.path);
let result;
switch (request.operation) {
case "readFile":
result = Buffer.from(await fs.readFile(path())).toString("base64");
break;
case "readDir":
result = await fs.readDir(path());
break;
case "readDirWithTypes":
result = await fs.readDirWithTypes(path());
break;
case "writeFile":
await fs.writeFile(path(), decodeBridgeBytes(args.content, "content"));
break;
case "createDir":
await fs.createDir(path());
break;
case "mkdir":
await fs.mkdir(path(), { recursive: args.recursive !== false });
break;
case "exists":
result = await fs.exists(path());
break;
case "stat":
result = await fs.stat(path());
break;
case "removeFile":
await fs.removeFile(path());
break;
case "removeDir":
await fs.removeDir(path());
break;
case "rename":
await fs.rename(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
break;
case "realpath":
result = await fs.realpath(path());
break;
case "symlink": {
if (typeof args.target !== "string") {
throw new Error("js_bridge args.target must be a string");
}
await fs.symlink(args.target, bridgePath(request.mount_id, args.linkPath));
break;
}
case "readlink":
result = await fs.readlink(path());
break;
case "lstat":
result = await fs.lstat(path());
break;
case "link":
await fs.link(bridgePath(request.mount_id, args.oldPath), bridgePath(request.mount_id, args.newPath));
break;
case "chmod":
await fs.chmod(path(), requireBridgeNumber(args.mode, "mode"));
break;
case "chown":
await fs.chown(path(), requireBridgeNumber(args.uid, "uid"), requireBridgeNumber(args.gid, "gid"), { followSymlinks: args.followSymlinks !== false });
break;
case "utimes":
await fs.utimes(path(), requireBridgeNumber(args.atimeMs, "atimeMs"), requireBridgeNumber(args.mtimeMs, "mtimeMs"));
break;
case "truncate":
await fs.truncate(path(), requireBridgeNumber(args.length, "length"));
break;
case "pread":
result = Buffer.from(await fs.pread(path(), requireBridgeNumber(args.offset, "offset"), requireBridgeNumber(args.length, "length"))).toString("base64");
break;
case "pwrite":
await fs.pwrite(path(), requireBridgeNumber(args.offset, "offset"), decodeBridgeBytes(args.content, "content"));
break;
default:
throw new Error(`Unsupported js_bridge operation: ${request.operation}`);
}
return {
type: "js_bridge_result",
call_id: request.call_id,
...(result === undefined ? {} : { result }),
};
}
catch (error) {
return {
type: "js_bridge_result",
call_id: request.call_id,
error: bridgeErrorMessage(error),
};
}
}
function parseHostCommandCallbackInput(input) {
const value = asRecord(input);
if (value.type !== "command" ||
typeof value.command !== "string" ||
typeof value.cwd !== "string" ||
!Array.isArray(value.args) ||
!value.args.every((arg) => typeof arg === "string")) {
return null;
}
return {
type: "command",
command: value.command,
args: value.args,
cwd: value.cwd,
};
}
async function handleHostCommandCallback(command, context) {
const directHostFunctions = context.hostFunctions.find((hostFunctionCollection) => `agentos-${hostFunctionCollection.name}` === command.command);
if (command.command === "agentos") {
return handleAgentOsRegistryCommand(command, context);
}
if (directHostFunctions) {
return handleAgentOsHostFunctionCommand(command, context, directHostFunctions);
}
throw new Error(`Unknown host callback command "${command.command}"`);
}
async function handleAgentOsRegistryCommand(command, context) {
const [subcommand, collectionName, functionName, ...functionArgs] = command.args;
if (!subcommand || isHelpFlag(subcommand)) {
return {
usage: "agentos <command>: list-host-functions [collection], <collection> --help, or <collection> <function> ...",
};
}
if (subcommand === "list-host-functions" || subcommand === "list-bindings") {
return collectionName
? describeHostFunctionsPayload(context.hostFunctions, collectionName)
: listHostFunctionsPayload(context.hostFunctions);
}
const hostFunctionCollection = context.hostFunctions.find((collection) => collection.name === subcommand);
if (!hostFunctionCollection) {
throw new Error(`No host function collection "${subcommand}". Available: ${hostFunctionsNames(context.hostFunctions)}`);
}
if (!collectionName || isHelpFlag(collectionName)) {
return describeHostFunctionsPayload(context.hostFunctions, subcommand);
}
if (functionName && isHelpFlag(functionName)) {
return describeHostFunctionPayload(hostFunctionCollection, collectionName);
}
return invokeHostFunction({
hostFunctionCollection,
functionName: collectionName,
args: [functionName, ...functionArgs].filter((value) => typeof value === "string"),
cwd: command.cwd,
context,
});
}
async function handleAgentOsHostFunctionCommand(command, context, hostFunctionCollection) {
const [functionName, helpOrFirstArg, ...rest] = command.args;
if (!functionName || isHelpFlag(functionName)) {
return describeHostFunctionsPayload(context.hostFunctions, hostFunctionCollection.name);
}
if (helpOrFirstArg && isHelpFlag(helpOrFirstArg)) {
return describeHostFunctionPayload(hostFunctionCollection, functionName);
}
return invokeHostFunction({
hostFunctionCollection,
functionName,
args: [helpOrFirstArg, ...rest].filter((value) => typeof value === "string"),
cwd: command.cwd,
context,
});
}
async function invokeHostFunction({ hostFunctionCollection, functionName, args, cwd, context, }) {
const definition = hostFunctionCollection.functions[functionName];
if (!definition) {
throw new Error(`No host function "${functionName}" in collection "${hostFunctionCollection.name}". Available: ${hostFunctionNames(hostFunctionCollection)}`);
}
// The sidecar checks the `hostFunction` permission scope for registry commands
// before forwarding them, the same as for collection commands.
const callbackKey = `${hostFunctionCollection.name}:${functionName}`;
const input = await parseHostFunctionInput(definition, args, cwd, context.readFile);
return executeHostFunction(definition, callbackKey, input);
}
async function executeHostFunction(definition, callbackKey, input) {
const parsed = definition.inputSchema.safeParse(input);
if (!parsed.success) {
throw new Error(validationMessage(parsed.error));
}
return Promise.race([
Promise.resolve(definition.execute(parsed.data)),
new Promise((_, reject) => {
if (definition.timeout === undefined) {
return;
}
setTimeout(() => reject(new Error(`Host function "${callbackKey}" timed out after ${definition.timeout}ms`)), definition.timeout);
}),
]);
}
async function parseHostFunctionInput(definition, args, cwd, readFile) {
if (args[0] === "--json") {
const value = args[1];
if (value === undefined) {
throw new Error("Flag --json requires a value");
}
return JSON.parse(value);
}
if (args[0] === "--json-file") {
const value = args[1];
if (value === undefined) {
throw new Error("Flag --json-file requires a value");
}
const guestPath = value.startsWith("/")
? posixPath.normalize(value)
: posixPath.normalize(`${cwd}/${value}`);
const text = new TextDecoder().decode(await readFile(guestPath));
return JSON.parse(text);
}
return parseHostFunctionArgv(hostFunctionToSidecarDefinition(definition).inputSchema, args);
}
function parseHostFunctionArgv(schema, argv) {
const schemaObject = asRecord(schema);
const properties = asRecord(schemaObject.properties);
const required = Array.isArray(schemaObject.required)
? new Set(schemaObject.required.filter((value) => typeof value === "string"))
: new Set();
const flagToField = new Map();
for (const [fieldName, fieldSchema] of Object.entries(properties)) {
flagToField.set(camelToKebab(fieldName), [fieldName, fieldSchema]);
}
const input = {};
for (let index = 0; index < argv.length;) {
const arg = argv[index];
if (!arg?.startsWith("--")) {
throw new Error(`Unexpected positional argument: "${arg}"`);
}
const rawFlag = arg.slice(2);
const negated = rawFlag.startsWith("no-");
const flagName = negated ? rawFlag.slice(3) : rawFlag;
const entry = flagToField.get(flagName);
if (!entry) {
throw new Error(`Unknown flag: --${rawFlag}`);
}
const [fieldName, fieldSchema] = entry;
const fieldType = jsonSchemaType(fieldSchema);
if (negated) {
if (fieldType !== "boolean") {
throw new Error(`Unknown flag: --${rawFlag}`);
}
input[fieldName] = false;
index += 1;
continue;
}
if (fieldType === "boolean") {
input[fieldName] = true;
index += 1;
continue;
}
const value = argv[index + 1];
if (value === undefined) {
throw new Error(`Flag --${rawFlag} requires a value`);
}
if (fieldType === "number" || fieldType === "integer") {
const number = Number(value);
if (!Number.isFinite(number)) {
throw new Error(`Flag --${rawFlag} expects a number, got "${value}"`);
}
input[fieldName] = number;
index += 2;
continue;
}
if (fieldType === "array") {
const current = Array.isArray(input[fieldName])
? input[fieldName]
: [];
const itemSchema = asRecord(fieldSchema).items;
const itemType = jsonSchemaType(itemSchema);
current.push(itemType === "number" || itemType === "integer" ? Number(value) : value);
input[fieldName] = current;
index += 2;
continue;
}
input[fieldName] = value;
index += 2;
}
for (const fieldName of required) {
if (!(fieldName in input)) {
throw new Error(`Missing required flag: --${camelToKebab(fieldName)}`);
}
}
return input;
}
function listHostFunctionsPayload(hostFunctions) {
return {
hostFunctions: hostFunctions.map((hostFunctionCollection) => ({
name: hostFunctionCollection.name,
functions: Object.keys(hostFunctionCollection.functions),
})),
};
}
function describeHostFunctionsPayload(hostFunctions, collectionName) {
const hostFunctionCollection = hostFunctions.find((collection) => collection.name === collectionName);
if (!hostFunctionCollection) {
throw new Error(`No host function collection "${collectionName}". Available: ${hostFunctionsNames(hostFunctions)}`);
}
return {
name: hostFunctionCollection.name,
functions: Object.fromEntries(Object.entries(hostFunctionCollection.functions).map(([functionName, definition]) => [
functionName,
{
description: hostFunctionDescription(definition),
flags: describeHostFunctionFlags(hostFunctionToSidecarDefinition(definition).inputSchema),
},
])),
};
}
function describeHostFunctionPayload(hostFunctionCollection, functionName) {
const definition = hostFunctionCollection.functions[functionName];
if (!definition) {
throw new Error(`No host function "${functionName}" in collection "${hostFunctionCollection.name}". Available: ${hostFunctionNames(hostFunctionCollection)}`);
}
return {
collection: hostFunctionCollection.name,
function: functionName,
description: hostFunctionDescription(definition),
flags: describeHostFunctionFlags(hostFunctionToSidecarDefinition(definition).inputSchema),
examples: definition.examples?.map((example) => ({
description: example.description,
input: example.input,
})) ?? [],
};
}
function hostFunctionsNames(hostFunctions) {
return hostFunctions
.map((hostFunctionCollection) => hostFunctionCollection.name)
.join(", ");
}
function hostFunctionNames(hostFunctionCollection) {
return Object.keys(hostFunctionCollection.functions).join(", ");
}
function isHelpFlag(value) {
return value === "--help" || value === "-h";
}
function jsonSchemaType(schema) {
const schemaObject = asRecord(schema);
return typeof schemaObject.type === "string" ? schemaObject.type : undefined;
}
async function registerHostFunctionsOnSidecar(client, session, vm, hostFunctions) {
if (hostFunctions.length === 0) {
return "";
}
for (const hostFunctionCollection of hostFunctions) {
await client.registerHostCallbacks(session, vm, {
name: hostFunctionCollection.name,
description: "",
commandAliases: [`agentos-${hostFunctionCollection.name}`],
registryCommandAliases: ["agentos"],
callbacks: Object.fromEntries(Object.entries(hostFunctionCollection.functions).map(([functionName, definition]) => [
functionName,
hostFunctionToSidecarDefinition(definition),
])),
});
}
return buildHostFunctionReference(hostFunctions);
}
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;
_processes = new Map();
_languageProcesses = new Map();
_languageProcessIds = new Map();
_pendingProcessRegistrations = 0;
_executionOutputHandlers = new Map();
_executionCompletedHandlers = new Map();
// No completion event can arrive after the sidecar exits, so its close
// rejects every execution still waiting for one.
_pendingCompletionRejects = new Set();
/** Set while dispose() runs; resolves once running processes are settled. */
_vmDisposal = null;
_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.
_closedShellIds = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
_closedShellErrors = new BoundedSet(CLOSED_SHELL_ID_RETENTION_LIMIT);
_pendingShellExitPromises = new Set();
_shellCounter = 0;
_softwareRoots;
_installedSoftware = new Map();
_softwareRegistry;
_packageResolver;
_vmMutationActive = false;
_cronManager;
_hostFunctions = [];
_hostFunctionReference = "";
_hostMounts;
_env;
_rootFilesystem;
_sidecarLease = null;
_sidecarClient;
_sidecarSession;
_sidecarVm;
_disposeSidecarEventListener;
_disposeSidecarCloseListener;
_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),
install: this._installSoftware.bind(this),
uninstall: this._uninstallSoftware.bind(this),
installed: this._installedSoftwareList.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, limitWarningHandler) {
this.#kernel = kernel;
this.sidecar = sidecar;
this._softwareRoots = softwareRoots;
this._hostMounts = hostMounts;
this._env = env;
this._rootFilesystem = rootFilesystem;
this._sidecarClient = sidecarClient;
this._sidecarSession = sidecarSession;
this._sidecarVm = sidecarVm;
this._limitWarningHandler = limitWarningHandler;
this._disposeSidecarEventListener = this._sidecarClient.onEvent((event) => {
this._handleSidecarEvent(event);
});
this._disposeSidecarCloseListener = this._sidecarClient.onClose((error) => {
for (const reject of this._pendingCompletionRejects)
reject(error);
});
agentOsRuntimeAdmins.set(this, {
kernel,
rootView: rootFilesystem,
env,
sidecar,
});
}
static async createSidecar(options = {}) {
return createAgentOsSidecarInternal(options);
}
static async getSharedSidecar(options = {}) {
return getSharedAgentOsSidecarInternal(options);
}
static async create(options,
/** @internal Product wrappers select a sidecar-owned default profile here. */
defaultsProfile = "agent_os") {
options = parseAgentOsOptions(options);
// Default software is resolved from immutable `.aospkg` files vendored in
// this package. Runtime package resolution never consults npm.
const defaultSoftware = options?.defaultSoftware === false ? [] : resolveDefaultSoftware();
const software = options?.defaultSoftware === false
? (options.software ?? [])
: [...defaultSoftware, ...(options?.software ?? [])];
// Packages are projected by the SIDECAR: the client forwards only the
// package `path` over `configureVm` and the sidecar reads metadata from
// the packed vbare manifest (chunk1 of the `.aospkg`).
const flatSoftware = software.flat();
// Honor the AgentOsOptions.defaultSoftware contract ("entries already present
// in `software` are not duplicated"): the default bundle and an explicitly
// passed one resolve to the same package paths, so dedup by path. Without
// this the sidecar rejects the second projection with a duplicate-command
// error (e.g. coreutils' `[`).
const seenPackagePaths = new Set();
const sidecarPackages = [];
const pendingSoftware = [];
for (const entry of flatSoftware) {
const classified = classifySoftwareEntry(entry);
if (classified.kind !== "path") {
pendingSoftware.push(classified);
continue;
}
if (seenPackagePaths.has(classified.path))
continue;
seenPackagePaths.add(classified.path);
sidecarPackages.push({ path: classified.path });
}
// Resolve registry names before allocating a sidecar, so an unknown
// package or release fails without booting a VM. The packages themselves
// are downloaded and verified by the sidecar once the VM exists.
const seenSoftwareUrls = new Set();
const postBootSoftware = [];
for (const pending of pendingSoftware) {
const source = pending.kind === "registry"
? await resolveRegistrySoftware(pending.name, {
version: pending.version,
registry: options?.softwareRegistry,
}).then((resolved) => ({
type: "url",
url: resolved.url,
expectedDigest: resolved.digest,
}))
: {
type: "url",
url: pending.url,
expectedDigest: pending.digest,
};
if (seenSoftwareUrls.has(source.url))
continue;
seenSoftwareUrls.add(source.url);
postBootSoftware.push(source);
}
// All package software is projected into `/opt/agentos` by the sidecar. The
// client stages nothing host-side and parses no package manifests.
const localMounts = await resolveCompatLocalMounts(options?.mounts);
// Keys become command names, so resolve and check them before anything
// else in `create()` allocates a sidecar or a sandbox.
const resolvedHostFunctions = options?.hostFunctions
? resolveHostFunctions(options.hostFunctions)
: [];
// Resolve the sidecar handle before starting an external sandbox so option
// validation failures cannot leak provider resources.
const sidecar = resolveAgentOsSidecar(options?.sidecar);
options = await resolveSandboxOptions(options);
const sandboxDisposeHooks = getSandboxDisposeHooks(options);
const hostFunctions = resolvedHostFunctions;
const createVmAdmin = async () => {
// The `/opt/agentos` projection is built by the sidecar from the
// forwarded `packages` (it owns the staging dir + read-only mount, and
// runtime `linkSoftware` appends to that live dir). The client no longer
// stages packages host-side.
const hostFunctionBootstrapCommands = collectHostFunctionBootstrapCommands(hostFunctions);
const bootstrapLower = createKernelBootstrapLower(options?.rootFilesystem);
let hostFunctionReference = "";
let rootBridge = null;
let kernel = null;
let client = null;
let createdNativeVm = null;
let nativeSession = null;
let cleanedUp = false;
const cleanup = async () => {
if (cleanedUp) {
return;
}
cleanedUp = true;
// Runs after the sidecar disposed the VM, so teardown callbacks work.
if (client && createdNativeVm) {
client.setVmSidecarRequestHandler(createdNativeVm.vmId, null);
}
};
try {
const env = options?.environment !== undefined
? { ...options.environment }
: getBaseEnvironment();
// Guest command paths. The sidecar owns the `/opt/agentos` projection and
// reports the exact projected package commands after `configureVm`.
// HostFunction-shim commands are added below.
const commandGuestPaths = new Map();
const { sidecarMounts, hostMounts, hostPathMappings } = collectSidecarMountPlan({
mounts: options?.mounts,
});
// Reuse the sidecar handle's single shared native process; this VM
// becomes another tenant of it rather than spawning its own process.
const shared = await ensureSharedSidecarNativeProcess(sidecar);
client = shared.client;
const session = shared.session;
nativeSession = session;
const hostPermissions = options?.permissions ?? {
...allowAll,
binding: "allow",
};
const sidecarPermissions = options?.permissions
? serializePermissionsForSidecar(options.permissions)
: undefined;
const createVmConfig = {
defaultsProfile,
...(options?.environment !== undefined
? { env: { ...options.environment } }
: {}),
database: options?.database,
...(options?.user ? { user: options.user } : {}),
rootFilesystem: serializeRootFilesystemForSidecar(options?.rootFilesystem, bootstrapLower),
...(sidecarPermissions ? { permissions: sidecarPermissions } : {}),
limits: options?.limits,
loopbackExemptPorts: options?.loopbackExemptPorts ?? [],
...(hostFunctionBootstrapCommands.length > 0
? { bootstrapCommands: hostFunctionBootstrapCommands }
: {}),
...(options?.rootFilesystem?.type === "native"
? {
nativeRoot: {
plugin: {
id: options.rootFilesystem.plugin.id,
config: options.rootFilesystem.plugin.config ?? {},
},
readOnly: options.rootFilesystem.readOnly ?? false,
},
}
: {}),
// 0.3: the Node builtin allow-list moved from configureVm to
// VM creation. `undefined` => engine default allow-list;
// `[]` => deny all; `[..]` => exactly those. Platform and
// module resolution keep their engine defaults (full Node
// emulation), matching the prior behavior where Agent OS only
// constrained the builtin allow-list.
...(options?.allowedNodeBuiltins !== undefined ||
options?.highResolutionTime !== undefined ||
options?.snapshotEntrypoints !== undefined
? {
jsRuntime: {
platform: "node",
moduleResolution: "node",
...(options?.allowedNodeBuiltins !== undefined
? { allowedBuiltins: options.allowedNodeBuiltins }
: {}),
...(options?.highResolutionTime !== undefined
? { highResolutionTime: options.highResolutionTime }
: {}),
...(options?.snapshotEntrypoints !== undefined
? { snapshotEntrypoints: options.snapshotEntrypoints }
: {}),
},
}
: {}),
};
const nativeVm = await client.createVm(session, {
runtime: "java_script",
config: createVmConfig,
});
createdNativeVm = nativeVm;
// Scope the readiness wait to THIS VM's ownership; on a shared process
// other VMs are emitting their own lifecycle events concurrently.
await client.waitForEvent((event) => event.payload.type === "vm_lifecycle" &&
event.payload.state === "ready" &&
event.ownership.scope === "vm" &&
event.ownership.vm_id === nativeVm.vmId, 10_000);
const configuredVm = await client.configureVm(session, nativeVm, {
mounts: sidecarMounts,
permissions: undefined,
commandPermissions: {},
loopbackExemptPorts: options?.loopbackExemptPorts,
packages: sidecarPackages,
packagesMountAt: OPT_AGENTOS_ROOT,
hostFunctionShimCommands: hostFunctionBootstrapCommands,
});
for (const command of configuredVm.projectedCommands) {
commandGuestPaths.set(command.name, command.guestPath);
}
if (hostFunctions.length > 0) {
hostFunctionReference = await registerHostFunctionsOnSidecar(client, session, nativeVm, hostFunctions);
commandGuestPaths.set("agentos", "/bin/agentos");
for (const hostFunctionCollection of hostFunctions) {
commandGuestPaths.set(`agentos-${hostFunctionCollection.name}`, `/bin/agentos-${hostFunctionCollection.name}`);
}
}
rootBridge = new NativeSidecarKernelProxy({
client,
session,
vm: nativeVm,
env,
cwd: "/workspace",
localMounts,
sidecarMounts,
permissions: undefined,
commandPermissions: {},
loopbackExemptPorts: options?.loopbackExemptPorts,
// Retained for runtime mount reconfigures: `configure_vm` is
// replace-on-write for the whole payload, so post-boot mountFs
// must resend the boot packages and host-function shims.
packages: sidecarPackages,
packagesMountAt: OPT_AGENTOS_ROOT,
hostFunctionShimCommands: hostFunctionBootstrapCommands,
commandGuestPaths,
onDispose: cleanup,
// The native process is owned by the AgentOsSidecar handle and
// shared across VMs; disposing this VM must not kill the process.
ownsClient: false,
});
kernel = rootBridge;
const snapshotClient = client;
return {
env,
hostMounts,
kernel,
rootView: rootBridge.createRootView(),
sidecarMounts,
sidecarPermissions: undefined,
commandPermissions: {},
loopbackExemptPorts: options?.loopbackExemptPorts,
sidecarClient: client,
sidecarSession: session,
sidecarVm: nativeVm,
snapshotRootFilesystem: async (maxBytes) => createSnapshotExport(convertSidecarRootSnapshotEntries(await snapshotClient.snapshotRootFilesystem(session, nativeVm, maxBytes))),
hostFunctions,
hostFunctionReference,
async dispose() {
if (kernel) {
const currentKernel = kernel;
kernel = null;
await currentKernel.dispose();
}
if (rootBridge) {
const currentRootBridge = rootBridge;
rootBridge = null;
await currentRootBridge.dispose();
return;
}
await cleanup();
},
};
}
catch (error) {
// The native process is shared and owned by the sidecar handle, so
// never dispose the client here — only tear down this VM's resources.
if (kernel) {
await kernel.dispose().catch(() => { });
}
if (rootBridge) {
await rootBridge.dispose().catch(() => { });
}
else {
if (createdNativeVm && nativeSession && client) {
await client
.disposeVm(nativeSession, createdNativeVm)
.catch(() => { });
}
await cleanup();
}
throw error;
}
};
let sidecarLease = null;
let createdVm;
try {
sidecarLease = await leaseAgentOsSidecarVm(sidecar, {
createVm: async () => createVmAdmin(),
});
const vmAdmin = sidecarLease.admin;
const vm = new AgentOs(vmAdmin.kernel, sidecar, [], vmAdmin.hostMounts, vmAdmin.env, vmAdmin.rootView, vmAdmin.sidecarClient, vmAdmin.sidecarSession, vmAdmin.sidecarVm, options?.onLimitWarning);
vm._sidecarLease = sidecarLease;
vm._softwareRegistry = options?.softwareRegistry;
vm._packageResolver = options?.packageResolver;
vm._hostFunctions = vmAdmin.hostFunctions;
vm._hostFunctionReference = vmAdmin.hostFunctionReference;
vm._disposeHooks.push(...sandboxDisposeHooks);
vm._installSidecarRequestHandler();
vm._cronManager = new CronManager(vm, options?.scheduleDriver ?? new TimerScheduleDriver());
createdVm = vm;
}
catch (error) {
const cleanupErrors = [];
try {
await sidecarLease?.dispose();
}
catch (disposeError) {
cleanupErrors.push(disposeError);
}
const sandboxCleanupResults = await Promise.allSettled(sandboxDisposeHooks.map((hook) => hook()));
cleanupErrors.push(...sandboxCleanupResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
if (cleanupErrors.length > 0) {
throw new AggregateError([error, ...cleanupErrors], "AgentOS VM creation and cleanup failed");
}
throw error;
}
// Registry and URL entries install through the same sidecar path as
// `software.install`, so the bytes are digest-verified before the VM is
// returned. A failed install disposes the VM instead of returning one
// without the requested software.
try {
for (const source of postBootSoftware) {
await createdVm._installSoftware(source);
}
}
catch (error) {
try {
await createdVm.dispose();
}
catch (disposeError) {
throw new AggregateError([error, disposeError], "AgentOS VM software install and cleanup failed");
}
throw error;
}
return createdVm;
}
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();
const { completion, resolve: resolveCompletion, release: releaseCompletion, } = this._pendingCompletion();
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();
releaseCompletion();
throw error;
}
if (response.type !== "execution_accepted") {
unsubscribeOutput();
unsubscribeCompleted();
releaseCompletion();
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();
const abort = () => {
// Admitted executions report cancellation through their structured result.
void this._cancelExecution(response.response.operationId).catch((error) => {
console.error("[agentos] failed to cancel aborted execution", error);
});
};
options.signal?.addEventListener("abort", abort, { once: true });
if (options.signal?.aborted)
abort();
const cleanup = () => {
unsubscribeOutput();
unsubscribeCompleted();
releaseCompletion();
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 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 releaseRegistrySlot = this._reserveProcessRegistrySlot();
const executionId = `process-${randomUUID()}`;
const internalOptions = {
...options,
output: options.output,
};
try {
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);
releaseRegistrySlot();
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) => {
// dispose() settles the exit of every process it terminates.
if (this._vmDisposal)
return;
console.error("[agentos] failed to reconcile spawned process completion", error);
});
}
return (this._languageProcesses.get(admitted.pid)?.descriptor ?? descriptor);
}
finally {
releaseRegistrySlot();
}
}
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);
}
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) {
const { completion, resolve: resolveCompletion, release: releaseCompletion, } = this._pendingCompletion();
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();
releaseCompletion();
}
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);
};
}
/**
* Settle every language process after DisposeVm. A process that finished
* before the dispose was already settled by the completion the dispose
* delivered. On success the sidecar terminated the rest, so each reports a
* signalled exit. On failure their termination is unproven, so their waits
* fail with the disposal error.
*/
_settleLanguageProcessesAfterDisposal(failure) {
if (!failure) {
for (const [pid, process] of this._languageProcesses) {
if (process.exit)
continue;
const exit = {
pid,
outcome: "signalled",
signal: "SIGKILL",
};
process.exit = exit;
process.descriptor = { ...process.descriptor, state: "exited" };
for (const handler of process.exitHandlers)
handler(exit);
}
}
const pendingError = failure ??
new Error("ERR_AGENTOS_VM_DISPOSED: the VM was disposed before the execution reported completion");
for (const reject of this._pendingCompletionRejects)
reject(pendingError);
this._pendingCompletionRejects.clear();
this._languageProcesses.clear();
this._languageProcessIds.clear();
}
/** A completion signal that rejects if the sidecar exits before it resolves. */
_pendingCompletion() {
let resolve;
let reject;
const completion = new Promise((res, rej) => {
resolve = res;
reject = rej;
});
// Callers await the signal only on some paths; an unawaited rejection
// must not surface as an unhandled rejection.
completion.catch(() => { });
this._pendingCompletionRejects.add(reject);
return {
completion,
resolve,
release: () => this._pendingCompletionRejects.delete(reject),
};
}
_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,
processId: proc.processId,
signal: undefined,
exit: undefined,
outputHandlers,
exitHandlers,
};
this._processes.set(proc.pid, entry);
// NOTE: do NOT delete from `_processes` on exit — the public API contract
// (getProcess/listProcesses/stopProcess, see process-management.test.ts)
// requires exited processes to stay queryable (running:false, exitCode set).
// `_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) => {
this._recordProcessExit(proc.pid, code);
})
.catch((error) => {
// A failed wait is not an exit event. Explicit process.wait calls retain
// the error, and callers may still signal an unconfirmed live process.
console.error(`[agentOS] process ${proc.pid} exit observation failed`, error);
});
return {
pid: proc.pid,
state: "running",
command,
startedAtMs: entry.startedAtMs,
};
}
_recordProcessExit(pid, exitCode) {
const entry = this._processes.get(pid);
if (!entry || entry.exit)
return;
const exit = {
pid,
exitCode,
outcome: entry.signal ? "signalled" : "exited",
...(entry.signal ? { signal: entry.signal } : {}),
};
entry.exit = exit;
for (const handler of entry.exitHandlers) {
try {
handler(exit);
}
catch (error) {
console.error("[agentOS] process exit handler failed", error);
}
}
}
_reserveProcessRegistrySlot() {
this._pruneExitedProcesses(this._pendingProcessRegistrations + 1);
const retained = this._processes.size + this._languageProcesses.size;
const admitted = retained + this._pendingProcessRegistrations + 1;
if (admitted > PROCESS_REGISTRY_LIMIT) {
throw Object.assign(new Error(`process registry limit ${PROCESS_REGISTRY_LIMIT} reached; wait for an exited process to be evicted or raise PROCESS_REGISTRY_LIMIT`), {
code: "ERR_AGENTOS_RESOURCE_LIMIT",
limitName: "process_registry_entries",
configuredLimit: PROCESS_REGISTRY_LIMIT,
requested: admitted,
configurationPath: "PROCESS_REGISTRY_LIMIT",
unit: "processes",
scope: "vm",
operation: "process.spawn",
retryable: true,
});
}
this._pendingProcessRegistrations += 1;
if (admitted >= PROCESS_REGISTRY_LIMIT * 0.8) {
console.warn("[agentos] process registry admission approaches PROCESS_REGISTRY_LIMIT", { admitted, limit: PROCESS_REGISTRY_LIMIT });
}
let active = true;
return () => {
if (!active)
return;
active = false;
this._pendingProcessRegistrations -= 1;
};
}
_pruneExitedProcesses(reserveSlots) {
const retained = this._processes.size + this._languageProcesses.size;
const target = Math.max(0, PROCESS_REGISTRY_LIMIT - reserveSlots);
let removeCount = retained - target;
if (removeCount <= 0)
return;
const exited = [
...[...this._processes.entries()]
.filter(([, entry]) => entry.exit !== undefined)
.map(([pid, entry]) => ({
kind: "process",
pid,
startedAtMs: entry.startedAtMs,
})),
...[...this._languageProcesses.entries()]
.filter(([, entry]) => entry.exit !== undefined)
.map(([pid, entry]) => ({
kind: "language",
pid,
startedAtMs: entry.descriptor.startedAtMs,
})),
].sort((left, right) => left.startedAtMs - right.startedAtMs || left.pid - right.pid);
for (const entry of exited) {
if (removeCount <= 0)
break;
if (entry.kind === "process") {
this._processes.delete(entry.pid);
}
else {
const language = this._languageProcesses.get(entry.pid);
if (language)
this._languageProcessIds.delete(language.executionId);
this._languageProcesses.delete(entry.pid);
}
removeCount -= 1;
}
}
async _spawnProcess(command, args = [], options = {}) {
const releaseRegistrySlot = this._reserveProcessRegistrySlot();
const outputHandlers = new Set();
const exitHandlers = new Set();
let proc;
try {
proc = this.#kernel.spawn(command, args, {
cwd: options.cwd,
env: options.env,
stdin: options.stdin,
timeout: options.timeoutMs,
streamStdin: options.streamStdin ?? true,
retainOutput: options.output?.retainEvents ?? false,
onStdout: (data, metadata) => {
options?.onStdout?.(data);
for (const h of outputHandlers) {
h({ pid: proc.pid, stream: "stdout", data, ...metadata });
}
},
onStderr: (data, metadata) => {
options?.onStderr?.(data);
for (const h of outputHandlers) {
h({ pid: proc.pid, stream: "stderr", data, ...metadata });
}
},
});
return this._trackProcess(proc, command, args, options.output?.retainEvents ?? false, outputHandlers, exitHandlers);
}
finally {
releaseRegistrySlot();
}
}
spawn(command, args = [], options) {
return this.process.spawn(command, args, options);
}
/** Write data to a process's stdin. */
_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) {
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}`);
return entry.proc.closeStdin();
}
/** Subscribe to stdout and stderr from a process. */
onProcessOutput(pid, handler) {
const entry = this._processes.get(pid) ?? this._languageProcesses.get(pid);
if (!entry)
throw new Error(`Process not found: ${pid}`);
entry.outputHandlers.add(handler);
return () => {
entry.outputHandlers.delete(handler);
};
}
/** Subscribe to process exit. Returns an unsubscribe function. */
onProcessExit(pid, handler) {
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 ("exit" in entry && entry.exit) {
handler(entry.exit);
return () => { };
}
entry.exitHandlers.add(handler);
return () => {
entry.exitHandlers.delete(handler);
};
}
/** Wait for a process to exit. Returns the exit code. */
async _waitProcess(pid) {
const language = this._languageProcesses.get(pid);
if (language) {
if (language.exit)
return language.exit;
let result;
try {
result = await this._waitExecutionResult(language.executionId);
}
catch (error) {
// Disposal terminates the process in the sidecar and settles its
// exit here, so a wait it interrupts reports that exit.
if (this._vmDisposal) {
await this._vmDisposal;
if (language.exit)
return language.exit;
}
throw error;
}
if (language.exit)
return language.exit;
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}`);
if (entry.exit)
return entry.exit;
const exitCode = await entry.proc.wait();
return (entry.exit ?? {
pid,
outcome: "exited",
exitCode,
});
}
_assertSafeAbsolutePath(path) {
if (!path.startsWith("/")) {
throw new Error(`Path must be absolute: ${path}`);
}
if (posixPath.normalize(path) !== path) {
throw new Error(`Path must be normalized: ${path}`);
}
}
_assertWritableAbsolutePath(path) {
this._assertSafeAbsolutePath(path);
if (path === "/proc" || path.startsWith("/proc/")) {
throw new Error(`Path is read-only: ${path}`);
}
}
_vfs() {
return this.#kernel.vfs;
}
async _readFile(path) {
this._assertSafeAbsolutePath(path);
return this.#kernel.readFile(path);
}
async _writeFile(path, content) {
this._assertWritableAbsolutePath(path);
return this.#kernel.writeFile(path, content);
}
async _writeFiles(entries) {
if (this.#kernel instanceof NativeSidecarKernelProxy) {
const results = entries.map((entry) => ({
path: entry.path,
success: true,
}));
const writable = [];
entries.forEach((entry, index) => {
try {
this._assertWritableAbsolutePath(entry.path);
writable.push({ index, entry });
}
catch (err) {
results[index] = {
path: entry.path,
success: false,
error: err instanceof Error ? err.message : String(err),
};
}
});
const errors = await this.#kernel.writeFiles(writable.map(({ entry }) => entry));
errors.forEach((error, position) => {
if (error !== null) {
const { index, entry } = writable[position];
results[index] = { path: entry.path, success: false, error };
}
});
return results;
}
const results = [];
for (const entry of entries) {
try {
this._assertWritableAbsolutePath(entry.path);
// Create parent directories as needed
const parentDir = entry.path.substring(0, entry.path.lastIndexOf("/"));
if (parentDir) {
await this._mkdirp(parentDir);
}
await this.#kernel.writeFile(entry.path, entry.content);
results.push({ path: entry.path, success: true });
}
catch (err) {
results.push({
path: entry.path,
success: false,
error: err instanceof Error ? err.message : String(err),
});
}
}
return results;
}
async _readFiles(paths) {
const results = [];
for (const path of paths) {
try {
this._assertSafeAbsolutePath(path);
const content = await this.#kernel.readFile(path);
results.push({ path, content });
}
catch (err) {
results.push({
path,
content: null,
error: err instanceof Error ? err.message : String(err),
});
}
}
return results;
}
/** Recursively create directories (mkdir -p). */
async _mkdirp(path) {
this._assertWritableAbsolutePath(path);
// `kernel.mkdir` is already recursive (it defaults to recursive=true on both
// the native sidecar and compat kernels) and creating an existing directory is
// a no-op, so a single call is sufficient. Do NOT probe each ancestor with
// `exists()` first: on the native sidecar every read-side op
// (exists/stat/readFile) triggers a full shadow-tree walk, so a per-component
// exists() loop makes `mkdir -p` cost O(components * tree).
await this.#kernel.mkdir(path);
}
async _mkdir(path, options) {
if (options?.recursive) {
return this._mkdirp(path);
}
this._assertSafeAbsolutePath(path);
return this.#kernel.mkdir(path);
}
async _readdir(path) {
this._assertSafeAbsolutePath(path);
return this.#kernel.readdir(path);
}
async _readdirEntries(path) {
this._assertSafeAbsolutePath(path);
const entries = await this.#kernel.readdirRecursive(path, { maxDepth: 0 });
return entries.map((entry) => ({
name: entry.name,
isDirectory: entry.isDirectory,
isSymbolicLink: entry.isSymbolicLink,
}));
}
async _readdirRecursive(path, options) {
this._assertSafeAbsolutePath(path);
const exclude = options?.exclude ? new Set(options.exclude) : undefined;
const entries = await this.#kernel.readdirRecursive(path, {
maxDepth: options?.maxDepth,
});
const excludedPrefixes = [];
const results = [];
for (const entry of entries) {
if (excludedPrefixes.some((prefix) => entry.path === prefix || entry.path.startsWith(`${prefix}/`))) {
continue;
}
if (exclude?.has(entry.name)) {
if (entry.isDirectory && !entry.isSymbolicLink) {
excludedPrefixes.push(entry.path);
}
continue;
}
results.push({
path: entry.path,
type: entry.isSymbolicLink
? "symlink"
: entry.isDirectory
? "directory"
: "file",
size: entry.size,
});
}
return results;
}
async _stat(path) {
this._assertSafeAbsolutePath(path);
return this.#kernel.stat(path);
}
async _exists(path) {
this._assertSafeAbsolutePath(path);
return this.#kernel.exists(path);
}
async _exportRootFilesystem(options) {
if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes <= 0) {
throw new RangeError("maxBytes must be a positive safe integer");
}
const nativeSnapshot = this._sidecarLease?.admin.snapshotRootFilesystem;
const snapshot = nativeSnapshot
? await nativeSnapshot(options.maxBytes)
: createSnapshotExport(await snapshotVirtualFilesystem(this._rootFilesystem));
const size = Buffer.byteLength(JSON.stringify(snapshot));
if (size > options.maxBytes) {
throw new RangeError(`root filesystem export is ${size} bytes, limit is ${options.maxBytes}; raise maxBytes to export this filesystem`);
}
return snapshot;
}
/**
* Mount a filesystem into the running VM. Resolves once the mount has been
* delivered to the native sidecar, so guest code can use it immediately
* after the returned promise settles; a delivery failure rejects instead of
* leaving the mount silently host-only.
*/
async _mountFs(descriptor) {
return this._withVmMutation(async () => {
this._assertSafeAbsolutePath(descriptor.path);
if (!(this.#kernel instanceof NativeSidecarKernelProxy)) {
throw new Error("portable dynamic mounts require the native sidecar");
}
await this.#kernel.mountDescriptor({
guestPath: descriptor.path,
readOnly: descriptor.readOnly ?? false,
plugin: {
id: descriptor.plugin.id,
config: descriptor.plugin.config ?? {},
},
});
});
}
async _unmountFs(path) {
return this._withVmMutation(async () => {
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() {
if (!(this.#kernel instanceof NativeSidecarKernelProxy))
return [];
return this.#kernel.listMounts();
}
async _move(from, to) {
this._assertWritableAbsolutePath(from);
this._assertWritableAbsolutePath(to);
await this.#kernel.movePath(from, to);
}
async _remove(path, options) {
this._assertWritableAbsolutePath(path);
await this.#kernel.removePath(path, {
recursive: options?.recursive ?? false,
});
}
/** @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"
? request.body
: request.body === undefined
? undefined
: new TextDecoder().decode(request.body);
const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
port: request.port,
method,
path: request.path,
headersJson: JSON.stringify(request.headers ?? {}),
...(method !== "GET" && method !== "HEAD" && body !== undefined
? { body }
: {}),
}));
const headers = {};
for (const [key, value] of responsePayload.headers ?? []) {
headers[key] = value;
}
return {
status: responsePayload.status,
statusText: responsePayload.statusText ?? "",
headers,
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. This compatibility surface supports
* fetch-like callers that proxy requests into a guest VM.
*/
async fetch(port, request) {
const url = new URL(request.url);
const responsePayload = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
port,
method: request.method,
path: `${url.pathname}${url.search}`,
headersJson: JSON.stringify(headersToRecord(request.headers)),
...(request.method !== "GET" && request.method !== "HEAD"
? {
bodyBase64: Buffer.from(await request.arrayBuffer()).toString("base64"),
}
: {}),
}));
const headers = new Headers();
for (const [key, value] of responsePayload.headers ?? []) {
headers.append(key, value);
}
return new Response(Buffer.from(responsePayload.body ?? "", "base64"), {
status: responsePayload.status,
statusText: responsePayload.statusText ?? "",
headers,
});
}
async fetchStreamStart(port, request) {
const url = new URL(request.url);
return JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
port,
method: request.method,
path: `${url.pathname}${url.search}`,
headersJson: JSON.stringify(headersToRecord(request.headers)),
...(request.method !== "GET" && request.method !== "HEAD"
? {
bodyBase64: Buffer.from(await request.arrayBuffer()).toString("base64"),
}
: {}),
streamOperation: "start",
}));
}
async fetchStreamRead(streamId, maxBytes = 64 * 1024) {
const response = JSON.parse(await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
port: 0,
method: "GET",
path: "/",
headersJson: "{}",
streamOperation: "read",
streamId,
maxBytes,
}));
return {
body: new Uint8Array(Buffer.from(response.body, "base64")),
done: response.done,
};
}
async fetchStreamCancel(streamId) {
await this._sidecarClient.vmFetch(this._sidecarSession, this._sidecarVm, {
port: 0,
method: "GET",
path: "/",
headersJson: "{}",
streamOperation: "cancel",
streamId,
});
}
_openTerminal(options) {
// Include closed-but-not-yet-exited terminals: close is not proof of exit.
if (this._pendingShellExitPromises.size >= TERMINAL_LIMIT) {
throw Object.assign(new Error(`terminal limit ${TERMINAL_LIMIT} reached; wait for existing terminals to exit or raise TERMINAL_LIMIT`), {
code: "ERR_AGENTOS_RESOURCE_LIMIT",
limitName: "active_terminals",
configuredLimit: TERMINAL_LIMIT,
requested: TERMINAL_LIMIT + 1,
configurationPath: "TERMINAL_LIMIT",
unit: "terminals",
scope: "vm",
retryable: true,
});
}
if (this._pendingShellExitPromises.size + 1 >= TERMINAL_LIMIT * 0.8) {
console.warn("[agentos] terminal admission approaches TERMINAL_LIMIT; close unused terminals", {
active: this._pendingShellExitPromises.size + 1,
limit: TERMINAL_LIMIT,
});
}
const shellId = `shell-${++this._shellCounter}`;
this._closedShellIds.delete(shellId);
const dataHandlers = new Set();
const stderrHandlers = new Set();
const exitHandlers = new Set();
const handle = this.#kernel.openShell({
...options,
onStderr: (data) => {
for (const handler of stderrHandlers)
handler({ shellId, data });
},
});
handle.onData = (data) => {
for (const handler of dataHandlers)
handler({ shellId, data });
};
const entry = {
handle,
dataHandlers,
stderrHandlers,
exitHandlers,
exitPromise: Promise.resolve(0),
};
const exitPromise = handle.wait();
const finalize = (exitCode) => {
this._pendingShellExitPromises.delete(entry.exitPromise);
if (this._shells.get(shellId) === entry) {
this._shells.delete(shellId);
}
// Record the exit code even when closeShell already dropped the
// entry, so a waitShell issued after exit still resolves with it.
this._closedShellIds.add(shellId, exitCode);
};
entry.exitPromise = exitPromise.then((exitCode) => {
finalize(exitCode);
for (const handler of exitHandlers)
handler({ shellId, exitCode });
return exitCode;
}, (error) => {
this._closedShellErrors.add(shellId, error);
finalize();
throw error;
});
// Preserve rejection for wait() without leaving an unobserved promise.
void entry.exitPromise.catch((error) => {
console.error("[agentos] terminal ended without a confirmed exit", {
shellId,
error,
});
});
this._pendingShellExitPromises.add(entry.exitPromise);
this._shells.set(shellId, entry);
return { shellId };
}
async connectTerminal(options) {
return this.#kernel.connectTerminal(options);
}
/** Write data to a shell's PTY input. */
_writeTerminal(shellId, data) {
const entry = this._shells.get(shellId);
if (!entry)
throw new Error(`Shell not found: ${shellId}`);
return entry.handle.write(data);
}
/**
* Subscribe to ordered PTY output (stdout and stderr). Returns an unsubscribe
* function. `OpenShellOptions.onStderr` is a diagnostic tap for callers that
* need channel identity; do not render both surfaces.
*/
onShellData(shellId, handler) {
const entry = this._shells.get(shellId);
if (!entry)
throw new Error(`Shell not found: ${shellId}`);
entry.dataHandlers.add(handler);
return () => {
entry.dataHandlers.delete(handler);
};
}
/** Subscribe to the stderr-only diagnostic stream for a shell. */
onShellStderr(shellId, handler) {
const entry = this._shells.get(shellId);
if (!entry)
throw new Error(`Shell not found: ${shellId}`);
entry.stderrHandlers.add(handler);
return () => entry.stderrHandlers.delete(handler);
}
/** Subscribe to shell exit. */
onShellExit(shellId, handler) {
const entry = this._shells.get(shellId);
if (!entry) {
const exitCode = this._closedShellIds.get(shellId);
if (exitCode !== undefined) {
handler({ shellId, exitCode });
return () => { };
}
throw new Error(`Shell not found: ${shellId}`);
}
entry.exitHandlers.add(handler);
return () => entry.exitHandlers.delete(handler);
}
/** Notify a shell of terminal resize. */
_resizeTerminal(shellId, cols, rows) {
const entry = this._shells.get(shellId);
if (!entry)
throw new Error(`Shell not found: ${shellId}`);
entry.handle.resize(cols, rows);
}
/**
* Wait for a shell to exit and return its process exit code. Resolves
* immediately for a shell that has already exited (within the closed-shell
* retention window).
*/
_waitTerminal(shellId) {
const entry = this._shells.get(shellId);
if (!entry) {
if (this._closedShellErrors.has(shellId)) {
return Promise.reject(this._closedShellErrors.get(shellId));
}
const exitCode = this._closedShellIds.get(shellId);
if (exitCode !== undefined)
return Promise.resolve(exitCode);
throw new Error(`Shell not found: ${shellId}`);
}
return entry.exitPromise;
}
/** Kill a shell process and remove it from tracking. */
_closeTerminal(shellId) {
const entry = this._shells.get(shellId);
if (!entry) {
if (this._closedShellIds.has(shellId)) {
return;
}
throw new Error(`Shell not found: ${shellId}`);
}
entry.handle.kill();
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) {
if (normalizedVmPath === mount.vmPath ||
normalizedVmPath.startsWith(`${mount.vmPath}/`)) {
const relativePath = posixPath.relative(mount.vmPath, normalizedVmPath);
if (!relativePath) {
return mount.hostPath;
}
return join(mount.hostPath, ...relativePath.split("/").filter(Boolean));
}
}
return null;
}
/** Returns info about all processes spawned via spawn(). */
async _listProcesses() {
return [
...[...this._processes.values()].map(({ proc, command, startedAtMs, exit }) => ({
pid: proc.pid,
command,
state: exit || proc.exitCode !== null ? "exited" : "running",
startedAtMs,
})),
...[...this._languageProcesses.values()].map((entry) => entry.descriptor),
];
}
/** Returns processes organized as a tree using ppid relationships. */
async _processTree() {
const records = this.#kernel instanceof NativeSidecarKernelProxy
? await this.#kernel.snapshotProcessTopology()
: [...this.#kernel.processes.values()].map((info) => ({
info,
key: `kernel:${info.pid}`,
parentKey: `kernel:${info.ppid}`,
}));
const roots = buildProcessForest(records, (proc, children) => ({
pid: proc.pid,
ppid: proc.ppid,
command: proc.command,
state: proc.status,
startedAtMs: proc.startTime,
children,
}));
const kernelKeys = new Set(records.map((record) => record.key));
for (const process of this._languageProcesses.values()) {
// Language admission returns a raw kernel PID and bypasses the proxy's
// synthetic spawn registry. A matching display PID is not identity.
if (!kernelKeys.has(`kernel:${process.descriptor.pid}`)) {
roots.push({
...process.descriptor,
children: [],
});
}
}
return roots;
}
/** Returns info about a specific process by PID. Throws if not found. */
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}`);
}
return {
pid: entry.proc.pid,
command: entry.command,
state: entry.exit || entry.proc.exitCode !== null ? "exited" : "running",
startedAtMs: entry.startedAtMs,
};
}
async _signalProcess(pid, signal) {
const language = this._languageProcesses.get(pid);
if (language) {
if (language.exit)
return;
language.signal = signal;
try {
await this._signalExecution(language.executionId, signal);
}
catch (error) {
if (!(error instanceof SidecarRejectedError) ||
error.detail.code !== "execution_not_running") {
throw error;
}
// The execution can finish between the local state check and the
// signal request. Reconcile its final state and preserve kill/signal's
// documented already-exited no-op behavior.
await this._waitProcess(pid);
}
return;
}
const entry = this._processes.get(pid);
if (!entry) {
throw new Error(`Process not found: ${pid}`);
}
if (entry.proc.exitCode !== null)
return;
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. */
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 { maxEvents } = replayPageLimits(options);
const language = this._languageProcesses.get(pid);
if (language) {
const page = await this._readExecutionOutput(language.executionId, {
limit: maxEvents,
cursor: options.after === undefined ? undefined : `1:${options.after + 1}`,
});
const replay = replayPage(pid, page.events.map((event) => ({
pid,
sequence: event.sequence,
channel: event.channel,
chunk: event.chunk,
timestampMs: event.timestampMs,
})), options, page.truncated ? (options.after ?? -1) + 1 : undefined, page.hasMore);
return { ...replay, exitCode: language.exit?.exitCode ?? null };
}
const entry = this._processes.get(pid);
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.processId) {
throw new Error(`Process ${pid} does not expose a sidecar replay identity`);
}
const wireLimits = replayWirePageLimits(options);
const response = await this._sidecarClient.sendVmRequest(this._sidecarSession, this._sidecarVm, {
type: "read_process_output",
process_id: entry.processId,
...(options.after === undefined ? {} : { after: options.after }),
max_events: wireLimits.maxEvents,
max_bytes: wireLimits.maxBytes,
});
if (response.type !== "process_output_page") {
throw new Error(`unexpected readProcessOutput response: ${response.type}`);
}
const exitCode = response.response.exitCode;
if (exitCode !== null && this._processes.get(pid) === entry) {
if (this.#kernel instanceof NativeSidecarKernelProxy) {
this.#kernel.reconcileReplayExit(entry.processId, exitCode);
}
this._recordProcessExit(pid, exitCode);
}
return {
pid,
exitCode,
events: response.response.events.map((event) => ({
pid,
sequence: safeProtocolNumber(event.sequence, "process output sequence"),
channel: event.channel.toLowerCase(),
chunk: new Uint8Array(event.chunk),
timestampMs: safeProtocolNumber(event.timestampMs, "process output timestamp"),
})),
nextCursor: response.response.nextCursor === null
? null
: safeProtocolNumber(response.response.nextCursor, "process output cursor"),
hasMore: response.response.hasMore,
truncated: response.response.truncated,
};
}
async _withVmMutation(operation) {
if (this._vmMutationActive) {
throw new Error("invalid_state: another VM mount or software mutation is already in progress; wait for it to finish before retrying");
}
this._vmMutationActive = true;
try {
return await operation();
}
finally {
this._vmMutationActive = false;
}
}
async _linkSoftware(descriptor) {
return this._withVmMutation(async () => {
// 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
// duplicate command, surfaced here as a thrown error.
const commands = await this._sidecarClient.linkPackage(this._sidecarSession, this._sidecarVm, descriptor);
if (this.#kernel instanceof NativeSidecarKernelProxy) {
this.#kernel.registerCommandGuestPaths(new Map(commands.projectedCommands.map((command) => [
command.name,
command.guestPath,
])));
}
});
}
async _installSoftware(source) {
return this._withVmMutation(async () => {
let wireSource;
switch (source.type) {
case "url":
wireSource = {
type: "url",
url: source.url,
expected_digest: source.expectedDigest,
};
break;
case "path":
wireSource = {
type: "path",
path: source.path,
expected_digest: source.expectedDigest,
};
break;
case "registry": {
// Resolved on this host; the sidecar verifies the bytes against
// the manifest digest exactly as for an explicit URL source.
const resolved = await resolveRegistrySoftware(source.name, {
version: source.version,
registry: this._softwareRegistry,
});
wireSource = {
type: "url",
url: resolved.url,
expected_digest: resolved.digest,
};
break;
}
default:
throw new Error(`unsupported software source type ${JSON.stringify(source.type)}; use "registry", "url", or "path"`);
}
const result = await this._sidecarClient.installPackage(this._sidecarSession, this._sidecarVm, {
source: wireSource,
...packageResolverWireOptions(this._packageResolver),
});
const packageInfo = result.package;
const installed = {
packageId: packageInfo.package_id,
digest: packageInfo.digest,
sizeBytes: packageInfo.size,
packageName: packageInfo.package_name,
version: packageInfo.version,
commands: [...packageInfo.commands],
};
this._installedSoftware.set(installed.packageId, installed);
if (this.#kernel instanceof NativeSidecarKernelProxy) {
this.#kernel.registerCommandGuestPaths(new Map(result.projected_commands.map((command) => [
command.name,
command.guest_path,
])));
}
return { ...installed, commands: [...installed.commands] };
});
}
async _uninstallSoftware(packageId) {
return this._withVmMutation(async () => {
const installed = this._installedSoftware.get(packageId);
if (!installed)
throw new Error(`Software not found: ${packageId}`);
const removedCommands = await this._sidecarClient.unlinkPackage(this._sidecarSession, this._sidecarVm, packageId);
this._installedSoftware.delete(packageId);
if (this.#kernel instanceof NativeSidecarKernelProxy) {
this.#kernel.unregisterCommandGuestPaths(removedCommands);
}
return { ...installed, commands: [...installed.commands] };
});
}
_installedSoftwareList() {
return [...this._installedSoftware.values()]
.sort((left, right) => left.packageId.localeCompare(right.packageId))
.map((software) => ({ ...software, commands: [...software.commands] }));
}
async _listSoftware() {
return this._sidecarClient.providedCommands(this._sidecarSession, this._sidecarVm);
}
/** @deprecated Use `software.link()`. */
linkSoftware(descriptor) {
return this.software.link(descriptor);
}
/** @deprecated Use `software.list()`. */
listSoftware() {
return this.software.list();
}
_handleSidecarEvent(event) {
// onEvent is process-wide: execution IDs are only unique inside one VM.
// Keep sibling VMs' output/completion and warnings on their own handles.
if (event.ownership.scope === "vm" &&
(event.ownership.connection_id !== this._sidecarSession.connectionId ||
event.ownership.session_id !== this._sidecarSession.sessionId ||
event.ownership.vm_id !== this._sidecarVm.vmId))
return;
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,
sequence: output.sequence,
timestampMs: output.timestampMs,
};
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 !== "structured") {
return;
}
if (event.payload.name === "limit_warning") {
this._handleLimitWarning(event.payload.detail);
}
}
_handleLimitWarning(detail) {
if (!this._limitWarningHandler) {
return;
}
const toNumber = (value) => {
const parsed = Number(value);
return Number.isFinite(parsed) ? parsed : 0;
};
try {
this._limitWarningHandler({
limit: detail.limit ?? "",
category: detail.category ?? "",
observed: toNumber(detail.observed),
capacity: toNumber(detail.capacity),
fillPercent: toNumber(detail.fillPercent),
});
}
catch (error) {
console.error("AgentOS limit-warning handler failed", error);
}
}
_installSidecarRequestHandler() {
const context = {
hostFunctions: this._hostFunctions,
hostFunctionMap: buildHostFunctionMap(this._hostFunctions),
readFile: (path) => this.readFile(path),
};
const vmId = this._sidecarVm.vmId;
this._sidecarClient.setVmSidecarRequestHandler(vmId, (request) => {
switch (request.payload.type) {
case "host_callback":
return handleHostCallback(request, context);
case "js_bridge_call":
return handleJsBridgeCall(request.payload, {
filesystem: this.#kernel.vfs,
});
case "ext":
return {
type: "ext_result",
envelope: {
namespace: request.payload.envelope.namespace,
payload: Buffer.from("extension handlers are not configured", "utf8"),
},
};
}
});
}
// ── Cron ────────────────────────────────────────────────────
/** Schedule a cron job. Returns a handle with the job ID and a cancel method. */
_scheduleCron(options) {
return this._cronManager.schedule(options);
}
/** List all registered cron jobs. */
_listCronJobs() {
return this._cronManager.list();
}
/** Cancel a cron job by 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);
}
async dispose() {
this._cronManager.dispose();
const errors = [];
let settleDisposal;
this._vmDisposal = new Promise((resolve) => {
settleDisposal = resolve;
});
for (const entry of this._shells.values()) {
entry.handle.kill();
}
await waitForTrackedExitPromises([...this._pendingShellExitPromises], VM_DISPOSE_DRAIN_TIMEOUT_MS);
this._shells.clear();
this._processes.clear();
this._executionOutputHandlers.clear();
this._executionCompletedHandlers.clear();
// One request tears the VM down: the sidecar's DisposeVm terminates every
// process still running in it, so there is no kill per process first.
const sidecarLease = this._sidecarLease;
this._sidecarLease = null;
const disposeVm = sidecarLease
? sidecarLease.dispose()
: this.#kernel.dispose();
const hooks = this._disposeHooks.splice(0);
let disposalError = null;
try {
await disposeVm;
}
catch (error) {
errors.push(error);
disposalError = error instanceof Error ? error : new Error(String(error));
}
// The event listener stays until DisposeVm resolves: the dispose
// delivers the completion of every execution that finished before it,
// so a process that exited just before reports its real exit status.
this._disposeSidecarEventListener();
this._disposeSidecarCloseListener();
this._settleLanguageProcessesAfterDisposal(disposalError);
settleDisposal();
const hookResults = await Promise.allSettled(hooks.map((hook) => hook()));
errors.push(...hookResults.flatMap((result) => result.status === "rejected" ? [result.reason] : []));
if (errors.length === 1)
throw errors[0];
if (errors.length > 1) {
throw new AggregateError(errors, "AgentOS VM disposal failed");
}
}
}
const agentOsRuntimeAdmins = new WeakMap();
export function getAgentOsRuntimeAdmin(vm) {
const admin = agentOsRuntimeAdmins.get(vm);
if (!admin) {
throw new Error("Agent OS runtime admin is not available for this VM");
}
return admin;
}
export function getAgentOsKernel(vm) {
return getAgentOsRuntimeAdmin(vm).kernel;
}
function resolveAgentOsSidecar(config) {
if (!config || config.kind === "shared") {
return getSharedAgentOsSidecarInternal(config?.kind === "shared"
? { pool: config.pool, runtime: config.runtime }
: undefined);
}
return config.handle;
}
const sidecarStates = new WeakMap();
const sharedSidecars = new Map();
let sidecarProcessExitHookInstalled = false;
/**
* Install a one-time, synchronous `process.on("exit")` hook that SIGKILLs any
* pooled shared sidecar child. Once a one-shot host process is allowed to exit
* (its sidecar handles are unref'd at 0 leases), this reaps the sidecar
* immediately instead of waiting for its stdin-EOF grace window — no orphan, no
* delay. We deliberately do NOT install SIGINT/SIGTERM handlers: a library
* should not hijack the host's signal handling. SIGINT still reaches the sidecar
* via the process group, and SIGTERM-driven exit still closes its stdin.
*/
function ensureSidecarProcessExitCleanup() {
if (sidecarProcessExitHookInstalled)
return;
sidecarProcessExitHookInstalled = true;
process.on("exit", () => {
for (const sidecar of sharedSidecars.values()) {
try {
sidecarStates.get(sidecar)?.sharedChild?.kill?.("SIGKILL");
}
catch {
// best-effort reap; the process is exiting regardless
}
}
});
}
function sidecarChildHandle(client) {
// SidecarProcess -> StdioSidecarProtocolClient.child (the spawned ChildProcess).
const protocolClient = client?.protocolClient;
return protocolClient?.child ?? undefined;
}
/**
* Apply the current hold state to the shared sidecar's child + stdio: ref them
* while ≥1 hold is live so in-flight VM work keeps the host process alive; unref
* them at 0 so a one-shot script exits on its own after `dispose()`. The sidecar
* process itself stays running (reusable) and self-exits on stdin EOF when the
* host finally goes away. Best-effort: never let ref/unref break VM lifecycle.
*/
function applySharedSidecarHold(state) {
const child = state.sharedChild;
if (!child)
return;
const hold = (state.eventLoopHolds ?? 0) > 0;
// Include the complete stdio array, not just the named fd0-fd2 aliases.
// Protocol v8 carries responses over fd3; leaving that control socket
// referenced pins Node's event loop after the final VM lease is disposed.
const handles = new Set([
child,
child.stdin,
child.stdout,
child.stderr,
...(child.stdio ?? []),
]);
for (const handle of handles) {
if (!handle)
continue;
try {
if (hold)
handle.ref?.();
else
handle.unref?.();
}
catch {
// ref/unref is an optimization, not correctness-critical
}
}
}
/**
* Take a hold for the entire create→use→dispose lifetime of one VM lease. Taken
* BEFORE VM creation starts (not when the lease lands in `activeLeases`) so a VM
* that is still mid-creation keeps the sidecar ref'd and a concurrent dispose
* cannot unref it out from under the in-flight create.
*/
function acquireSharedSidecarHold(state) {
state.eventLoopHolds = (state.eventLoopHolds ?? 0) + 1;
if (state.eventLoopHolds === 1)
applySharedSidecarHold(state);
}
/** Release a hold taken by {@link acquireSharedSidecarHold}; unref at 0. */
function releaseSharedSidecarHold(state) {
const current = state.eventLoopHolds ?? 0;
if (current <= 0) {
// The `holdReleased` guard makes each lease release exactly once, so this
// should be unreachable. Warn rather than silently floor, per the repo's
// no-silent-masking rule, so an accounting bug surfaces instead of hiding.
state.eventLoopHolds = 0;
console.warn("[agentos] shared sidecar event-loop hold released more than acquired");
return;
}
state.eventLoopHolds = current - 1;
if (state.eventLoopHolds === 0)
applySharedSidecarHold(state);
}
/**
* Spawn-once accessor for a sidecar handle's shared native process. Concurrent
* callers await the same promise, so one `AgentOsSidecar` maps to exactly one
* `agent-os-sidecar` OS process for its whole lifetime.
*/
function ensureSharedSidecarNativeProcess(sidecar) {
const state = getSidecarState(sidecar);
if (!state.nativeProcess) {
ensureSidecarProcessExitCleanup();
state.nativeProcess = (async () => {
const client = SidecarProcess.spawn({
cwd: REPO_ROOT,
command: ensureNativeSidecarBinary(),
args: sidecarRuntimeArgs(state.runtime),
});
// Track the child immediately — BEFORE the handshake await — so a
// failed `authenticateAndOpenSession()` can still reap it (otherwise
// the spawned child is untracked, unreapable, and pins the loop).
state.sharedChild = sidecarChildHandle(client);
if (!state.sharedChild) {
// We reached into @rivet-dev/agentos-runtime-core internals to get the child for
// idle-unref. If that shape ever changes this returns undefined and
// the optimization silently stops working (one-shot scripts would
// hang again). Make it loud rather than a silent regression.
console.warn("[agentos] could not resolve the shared sidecar child handle; " +
"standalone scripts may not exit cleanly after dispose(). " +
"This usually means @rivet-dev/agentos-runtime-core internals changed.");
}
// Apply the current hold state to the just-spawned child.
applySharedSidecarHold(state);
try {
const session = await client.authenticateAndOpenSession();
// A transport that fails for good (process exit, silence watchdog,
// event buffer overflow, undecodable frame) leaves the VMs out of
// reach. Stop the process, as the Rust client does, and report the
// handle disposed so a shared pool spawns a fresh sidecar.
const child = state.sharedChild;
client.onClose(() => {
child?.kill?.("SIGKILL");
if (state.description.state === "ready") {
state.description.state = "disposed";
}
});
return { client, session };
}
catch (error) {
// Spawn/handshake failed: reap the child, drop the cached handle,
// and CLEAR the rejected promise so the next create() retries
// instead of permanently wedging on a rejected `nativeProcess`.
try {
state.sharedChild?.kill?.("SIGKILL");
}
catch {
// already gone
}
state.sharedChild = undefined;
state.nativeProcess = undefined;
throw error;
}
})();
}
return state.nativeProcess;
}
/** Dispose a sidecar handle's shared native process, if one was spawned. */
async function disposeSharedSidecarNativeProcess(state) {
const pending = state.nativeProcess;
if (!pending) {
return;
}
state.nativeProcess = undefined;
// The cached child is now dead; drop it (symmetric with the assignment in
// ensureSharedSidecarNativeProcess). We deliberately do NOT zero
// `eventLoopHolds` here: this runs only from `AgentOsSidecar.dispose()`, which
// has already set the handle to `disposing` (so no new lease can acquire) and
// drained `activeLeases`; the disposed handle's state is then abandoned. Force-
// zeroing a shared counter could clobber a hold on a freshly re-acquired
// process generation, so it is left to the balanced acquire/release pairs.
state.sharedChild = undefined;
try {
const { client } = await pending;
await client.dispose();
}
catch {
// Process may have already exited; nothing to reclaim.
}
}
export class AgentOsSidecar {
constructor(sidecarId, placement, sharedPool, runtime) {
sidecarStates.set(this, {
description: {
sidecarId,
placement: cloneSidecarPlacement(placement),
state: "ready",
activeVmCount: 0,
},
activeLeases: new Set(),
sharedPool,
runtime: normalizeSidecarRuntimeConfig(runtime),
});
}
describe() {
const state = getSidecarState(this);
return cloneSidecarDescription(state.description);
}
async dispose() {
const state = getSidecarState(this);
if (state.description.state === "disposed") {
return;
}
state.description.state = "disposing";
const errors = [];
for (const lease of [...state.activeLeases]) {
try {
await lease.dispose();
}
catch (error) {
errors.push(error instanceof Error ? error : new Error(String(error)));
}
}
state.activeLeases.clear();
state.description.activeVmCount = 0;
// Tear down the shared native process after all leased VMs are gone.
await disposeSharedSidecarNativeProcess(state);
state.description.state = "disposed";
if (state.sharedPool && sharedSidecars.get(state.sharedPool) === this) {
sharedSidecars.delete(state.sharedPool);
}
if (errors.length > 0) {
throw new Error(errors.map((error) => error.message).join("; "));
}
}
}
function createAgentOsSidecarInternal(options = {}) {
const sidecarId = options.sidecarId ?? `agentos-sidecar-${randomUUID()}`;
return new AgentOsSidecar(sidecarId, {
kind: "explicit",
sidecarId,
}, undefined, options.runtime);
}
/**
* Test-only escape hatch: dispose every cached shared sidecar so vitest
* workers can exit cleanly. The shared sidecar is normally process-global and
* keeps its native subprocess alive across `AgentOs.create()` calls; without
* this hook the vitest worker can hold open piped stdio handles after the
* test suite finishes and stall `pnpm test` indefinitely.
*/
export async function __disposeAllSharedSidecarsForTesting() {
const sidecars = Array.from(sharedSidecars.values());
sharedSidecars.clear();
const errors = [];
for (const sidecar of sidecars) {
try {
await sidecar.dispose();
}
catch (error) {
errors.push(error instanceof Error ? error : new Error(String(error)));
}
}
if (errors.length > 0) {
throw new Error(`failed to dispose shared sidecars: ${errors.map((error) => error.message).join("; ")}`);
}
}
function getSharedAgentOsSidecarInternal(options = {}) {
const pool = options.pool ?? "default";
const existing = sharedSidecars.get(pool);
if (existing && existing.describe().state !== "disposed") {
if (options.runtime !== undefined) {
const requested = normalizeSidecarRuntimeConfig(options.runtime);
const configured = getSidecarState(existing).runtime;
if (!sidecarRuntimeConfigsEqual(requested, configured)) {
throw new Error(`Shared sidecar pool ${JSON.stringify(pool)} already exists with different runtime settings`);
}
}
return existing;
}
const sidecar = new AgentOsSidecar(`agentos-shared-sidecar:${pool}`, { kind: "shared", ...(pool ? { pool } : {}) }, pool, options.runtime);
sharedSidecars.set(pool, sidecar);
return sidecar;
}
function normalizeSidecarRuntimeConfig(runtime) {
const maxActiveVms = runtime?.executor?.maxActiveVms;
if (maxActiveVms === undefined)
return {};
if (!Number.isSafeInteger(maxActiveVms) || maxActiveVms <= 0) {
throw new Error("runtime.executor.maxActiveVms must be a positive safe integer");
}
return { executor: { maxActiveVms } };
}
function sidecarRuntimeConfigsEqual(left, right) {
return left.executor?.maxActiveVms === right.executor?.maxActiveVms;
}
function sidecarRuntimeArgs(runtime) {
const maxActiveVms = runtime.executor?.maxActiveVms;
return maxActiveVms === undefined
? []
: ["--max-active-vms", String(maxActiveVms)];
}
async function leaseAgentOsSidecarVm(sidecar, options) {
const state = getSidecarState(sidecar);
if (state.description.state !== "ready") {
throw new Error(`Cannot lease VM from sidecar ${state.description.sidecarId} while it is ${state.description.state}`);
}
let transport;
const client = createAgentOsSidecarClient({
async createOwnershipTransport(sessionBootstrap) {
transport = await createInProcessSidecarTransport(sessionBootstrap, options);
return transport;
},
});
// Hold the shared sidecar's event-loop ref for this lease's WHOLE lifetime —
// taken now, before VM creation, so a concurrent dispose cannot unref the
// sidecar while this create is still in flight. Released exactly once on
// dispose or on a failed create.
acquireSharedSidecarHold(state);
let holdReleased = false;
const releaseHold = () => {
if (holdReleased)
return;
holdReleased = true;
releaseSharedSidecarHold(state);
};
let disposed = false;
let leaseRecord;
try {
const session = await client.createOwnershipSession({
placement: cloneSidecarPlacement(state.description.placement),
});
const vm = await session.createVm();
const admin = transport?.getVmAdmin(vm.vmId);
if (!admin) {
throw new Error(`Sidecar VM admin was not registered for ${vm.vmId}`);
}
const lease = {
sidecar,
session,
vm,
admin,
async dispose() {
if (disposed) {
return;
}
disposed = true;
state.activeLeases.delete(leaseRecord);
state.description.activeVmCount = state.activeLeases.size;
await client.dispose();
// Release this lease's hold; the shared sidecar is unref'd only
// once the last hold (across all in-flight + active leases) drops,
// so a one-shot host process can then exit on its own.
releaseHold();
},
};
leaseRecord = {
dispose: () => lease.dispose(),
};
state.activeLeases.add(leaseRecord);
state.description.activeVmCount = state.activeLeases.size;
return lease;
}
catch (error) {
await client.dispose().catch(() => { });
releaseHold();
throw error;
}
}
async function createInProcessSidecarTransport(sessionBootstrap, options) {
const vmAdmins = new Map();
let disposed = false;
async function disposeVmAdmin(vmId) {
const admin = vmAdmins.get(vmId);
if (!admin) {
return;
}
vmAdmins.delete(vmId);
await admin.dispose();
}
return {
async createVm(vmBootstrap) {
if (disposed) {
throw new Error(`Cannot create VM ${vmBootstrap.vmId} for disposed sidecar session ${sessionBootstrap.sessionId}`);
}
const admin = await options.createVm(sessionBootstrap, vmBootstrap);
vmAdmins.set(vmBootstrap.vmId, admin);
},
async disposeVm(vmId) {
await disposeVmAdmin(vmId);
},
async dispose() {
if (disposed) {
return;
}
disposed = true;
const errors = [];
for (const vmId of [...vmAdmins.keys()]) {
try {
await disposeVmAdmin(vmId);
}
catch (error) {
errors.push(error instanceof Error ? error : new Error(String(error)));
}
}
if (errors.length > 0) {
throw new Error(errors.map((error) => error.message).join("; "));
}
},
getVmAdmin(vmId) {
return vmAdmins.get(vmId);
},
};
}
function getSidecarState(sidecar) {
const state = sidecarStates.get(sidecar);
if (!state) {
throw new Error("Unknown Agent OS sidecar handle");
}
return state;
}
function cloneSidecarDescription(description) {
return {
...description,
placement: cloneSidecarPlacement(description.placement),
};
}
function cloneSidecarPlacement(placement) {
if (placement.kind === "shared") {
return {
kind: "shared",
...(placement.pool ? { pool: placement.pool } : {}),
};
}
return {
kind: "explicit",
sidecarId: placement.sidecarId,
};
}
Shown as plain text from the published tarball, after apm checked it against the version's checksum. Nothing in it runs on this page.