@nylorun/runtime 0.7.0-beta → 0.9.0-beta

package/dist/sandbox/manager.d.ts

@@ -0,0 +1,61 @@
+import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
+import type { Store } from "../core/store.js";
+import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
+import { type SandboxToolOutcome } from "./tools.js";
+import type { SandboxBackend } from "./types.js";
+export interface SandboxSessionRef {
+    readonly id: string;
+    readonly activeTurnId: string | null;
+    readonly manifest: AgentManifest;
+}
+export type SandboxState = "creating" | "running" | "stopped";
+interface SandboxRecord {
+    key: string;
+    sessionId: string;
+    backend: string;
+    image: string;
+    state: SandboxState;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SandboxManagerOptions {
+    /** Distinguishes this Runtime's sandboxes from other Runtimes on the same machine. */
+    readonly scope: string;
+    readonly store: Store;
+    readonly backends: readonly SandboxBackend[];
+    /** `auto`, `microsandbox` or `virtual`. Undefined means an invalid NYLORUN_SANDBOX value. */
+    readonly preference: string | undefined;
+    /** Delete sandboxes on close (the Runtime's store does not outlive the process). */
+    readonly ephemeral: boolean;
+    readonly emit: (sessionId: string, turnId: string | null, type: string, payload: unknown) => void;
+}
+/** The sandbox capability that owns this tool call, when the call is a built-in sandbox tool. */
+export declare function sandboxCapabilityOf(manifest: AgentManifest | undefined, capabilityId: string | undefined, toolName: string | undefined): CapabilityManifest | undefined;
+export declare class SandboxManager {
+    private readonly options;
+    private selection?;
+    private readonly live;
+    private readonly prefix;
+    private closing;
+    constructor(options: SandboxManagerOptions);
+    /** Backends are probed once, on first use, and the choice holds for the life of the Runtime. */
+    get ready(): Promise<SandboxSelection>;
+    /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
+    hasRecords(): boolean;
+    keyOf(sessionId: string): string;
+    report(): Promise<SandboxSelectionReport & {
+        readonly defaultImage: string;
+    }>;
+    run(session: SandboxSessionRef, capability: CapabilityManifest, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    private execute;
+    private open;
+    private armIdle;
+    private stop;
+    private record;
+    /** The sandbox record for a session, if one was ever created. */
+    status(sessionId: string): SandboxRecord | undefined;
+    /** Delete sandboxes this Runtime owns whose session no longer exists. */
+    reconcile(sessionExists: (sessionId: string) => boolean): Promise<void>;
+    close(): Promise<void>;
+}
+export {};

package/dist/sandbox/manager.js

@@ -0,0 +1,239 @@
+/**
+ * Sandbox Manager: owns sandbox lifecycle for the Runtime. One sandbox per session, created on
+ * the first sandbox tool call, stopped after its idle timeout, reattached on the next call.
+ * Commands against one sandbox run one at a time.
+ */
+import { createHash } from "node:crypto";
+import { isSandboxToolName, } from "@nylorun/core/define";
+import { DEFAULT_SANDBOX_CPUS, DEFAULT_SANDBOX_IMAGE, describeNetwork, idleMsOf, memoryMiBOf, resolveNetwork, } from "./policy.js";
+import { parseSandboxPreference, reportSelection, selectSandboxBackend, } from "./select.js";
+import { runSandboxTool } from "./tools.js";
+const READ_TOOLS = new Set(["read", "grep", "glob"]);
+/** The sandbox capability that owns this tool call, when the call is a built-in sandbox tool. */
+export function sandboxCapabilityOf(manifest, capabilityId, toolName) {
+    if (!manifest || !capabilityId || !toolName || !isSandboxToolName(toolName))
+        return undefined;
+    const capability = manifest.capabilities.find((item) => item.id === capabilityId);
+    return capability?.sandbox && capability.tools?.some((tool) => tool.name === toolName)
+        ? capability
+        : undefined;
+}
+export class SandboxManager {
+    options;
+    selection;
+    live = new Map();
+    prefix;
+    closing = false;
+    constructor(options) {
+        this.options = options;
+        this.prefix = `nylorun-${options.scope}-`;
+        // Compute is gone after a Runtime restart; files remain and the next call reattaches.
+        options.store.tx(() => {
+            for (const record of options.store.all("sandboxes"))
+                if (record.state !== "stopped")
+                    options.store.put("sandboxes", record.key, { ...record, state: "stopped" });
+        });
+    }
+    /** Backends are probed once, on first use, and the choice holds for the life of the Runtime. */
+    get ready() {
+        if (!this.selection) {
+            const preference = parseSandboxPreference(this.options.preference);
+            this.selection = preference
+                ? selectSandboxBackend(this.options.backends, preference)
+                : Promise.resolve({
+                    preference: "auto",
+                    reason: `NYLORUN_SANDBOX='${this.options.preference}' is not valid; use auto, microsandbox or virtual`,
+                    probes: [],
+                });
+        }
+        return this.selection;
+    }
+    /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
+    hasRecords() {
+        return this.options.store.all("sandboxes").length > 0;
+    }
+    keyOf(sessionId) {
+        return this.prefix + createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+    }
+    async report() {
+        return { ...reportSelection(await this.ready), defaultImage: DEFAULT_SANDBOX_IMAGE };
+    }
+    async run(session, capability, toolName, input, signal) {
+        const selection = await this.ready;
+        const backend = selection.backend;
+        if (!backend)
+            return {
+                kind: "failed",
+                code: "sandbox.unavailable",
+                message: `No sandbox is available: ${selection.reason}. Run \`npx nylorun doctor sandbox\` for options.`,
+            };
+        const key = this.keyOf(session.id);
+        const spec = {
+            key,
+            image: capability.sandbox?.image ?? DEFAULT_SANDBOX_IMAGE,
+            cpus: capability.sandbox?.resources?.cpus ?? DEFAULT_SANDBOX_CPUS,
+            memoryMiB: memoryMiBOf(capability.sandbox),
+            network: resolveNetwork(capability.sandbox),
+        };
+        const unmet = backend.unmet(spec);
+        if (unmet)
+            return {
+                kind: "failed",
+                code: "sandbox.unavailable",
+                message: `This agent's sandbox cannot run on the ${backend.name} backend: ${unmet}.`,
+            };
+        let live = this.live.get(key);
+        if (!live) {
+            live = { sessionId: session.id, backend, idleMs: idleMsOf(capability.sandbox), tail: Promise.resolve() };
+            this.live.set(key, live);
+        }
+        const entry = live;
+        const task = entry.tail.then(() => this.execute(entry, session, spec, toolName, input, signal));
+        entry.tail = task.catch(() => undefined);
+        return task;
+    }
+    async execute(live, session, spec, toolName, input, signal) {
+        if (signal.aborted)
+            throw new Error("Turn cancelled");
+        if (this.closing)
+            throw new Error("Runtime is shutting down");
+        clearTimeout(live.timer);
+        if (!live.handle) {
+            try {
+                live.handle = await this.open(live, session, spec);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                this.record(spec.key, session.id, live.backend.name, spec.image, "stopped");
+                this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
+                    state: "stopped",
+                    backend: live.backend.name,
+                    error: message,
+                });
+                // Nothing ran yet, so a failed start is a definite outcome, not an uncertain one.
+                return {
+                    kind: "failed",
+                    code: "sandbox.start_failed",
+                    message: `The sandbox could not start on ${live.backend.name} (image ${spec.image}): ${message}`,
+                };
+            }
+        }
+        const started = Date.now();
+        let report = {};
+        try {
+            const outcome = await runSandboxTool(live.handle, toolName, (input ?? {}), signal, (value) => {
+                report = value;
+            });
+            this.options.emit(session.id, session.activeTurnId, "sandbox.exec", {
+                tool: toolName,
+                ...report,
+                ...(report.command ? { command: report.command.slice(0, 500) } : {}),
+                outcome: outcome.kind,
+                ...(outcome.kind === "failed" ? { code: outcome.code } : {}),
+                durationMs: Date.now() - started,
+            });
+            return outcome;
+        }
+        catch (error) {
+            // The backend itself failed; reopen on the next call.
+            live.handle = undefined;
+            if (signal.aborted || !READ_TOOLS.has(toolName))
+                throw error;
+            return {
+                kind: "failed",
+                code: "sandbox.error",
+                message: error instanceof Error ? error.message : String(error),
+            };
+        }
+        finally {
+            this.armIdle(spec.key, live);
+        }
+    }
+    async open(live, session, spec) {
+        const existing = this.options.store.get("sandboxes", spec.key);
+        const payload = {
+            backend: live.backend.name,
+            isolation: live.backend.isolation,
+            image: spec.image,
+            network: describeNetwork(spec.network),
+        };
+        this.record(spec.key, session.id, live.backend.name, spec.image, "creating", existing);
+        this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
+            state: "creating",
+            ...payload,
+            ...(existing ? { reattach: true } : {}),
+        });
+        const handle = await live.backend.open(spec);
+        this.record(spec.key, session.id, live.backend.name, spec.image, "running", existing);
+        this.options.emit(session.id, session.activeTurnId, "sandbox.state", { state: "running", ...payload });
+        return handle;
+    }
+    armIdle(key, live) {
+        clearTimeout(live.timer);
+        if (this.closing)
+            return;
+        live.timer = setTimeout(() => {
+            live.tail = live.tail.then(() => this.stop(key, live)).catch(() => undefined);
+        }, live.idleMs);
+        live.timer.unref();
+    }
+    async stop(key, live) {
+        const handle = live.handle;
+        if (!handle)
+            return;
+        live.handle = undefined;
+        try {
+            await handle.stop();
+        }
+        finally {
+            this.record(key, live.sessionId, live.backend.name, undefined, "stopped");
+            this.options.emit(live.sessionId, null, "sandbox.state", { state: "stopped", backend: live.backend.name });
+        }
+    }
+    record(key, sessionId, backend, image, state, existing = this.options.store.get("sandboxes", key)) {
+        const now = new Date().toISOString();
+        this.options.store.tx(() => this.options.store.put("sandboxes", key, {
+            key,
+            sessionId,
+            backend,
+            image: image ?? existing?.image ?? "",
+            state,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        }));
+    }
+    /** The sandbox record for a session, if one was ever created. */
+    status(sessionId) {
+        return this.options.store.get("sandboxes", this.keyOf(sessionId));
+    }
+    /** Delete sandboxes this Runtime owns whose session no longer exists. */
+    async reconcile(sessionExists) {
+        const { backend } = await this.ready;
+        if (!backend)
+            return;
+        for (const key of await backend.list(this.prefix)) {
+            const record = this.options.store.get("sandboxes", key);
+            if (record && sessionExists(record.sessionId))
+                continue;
+            await backend.remove(key);
+            this.options.store.tx(() => this.options.store.delete("sandboxes", key));
+        }
+    }
+    async close() {
+        this.closing = true;
+        if (!this.selection)
+            return;
+        const tasks = [...this.live.entries()].map(async ([key, live]) => {
+            clearTimeout(live.timer);
+            await live.tail;
+            if (this.options.ephemeral) {
+                live.handle = undefined;
+                await live.backend.remove(key);
+            }
+            else
+                await this.stop(key, live);
+        });
+        await Promise.allSettled(tasks);
+        this.live.clear();
+    }
+}

package/dist/sandbox/policy.d.ts

@@ -0,0 +1,13 @@
+import { type SandboxManifest } from "@nylorun/core/define";
+import type { ResolvedNetwork } from "./types.js";
+/** Docker Official Image: Debian with bash, coreutils and Python 3; small first pull. */
+export declare const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
+export declare const DEFAULT_SANDBOX_CPUS = 2;
+export declare const DEFAULT_SANDBOX_MEMORY_MIB = 1024;
+export declare const DEFAULT_SANDBOX_IDLE_MS: number;
+/** Package registries and code hosts. Concrete names so every backend can express them. */
+export declare const DEV_PRESET_HOSTS: readonly string[];
+export declare function resolveNetwork(manifest: SandboxManifest | undefined): ResolvedNetwork;
+export declare function idleMsOf(manifest: SandboxManifest | undefined): number;
+export declare function memoryMiBOf(manifest: SandboxManifest | undefined): number;
+export declare function describeNetwork(network: ResolvedNetwork): string;

package/dist/sandbox/policy.js

@@ -0,0 +1,67 @@
+import { parseSandboxDuration, parseSandboxSize, } from "@nylorun/core/define";
+/** Docker Official Image: Debian with bash, coreutils and Python 3; small first pull. */
+export const DEFAULT_SANDBOX_IMAGE = "python:3.13-slim";
+export const DEFAULT_SANDBOX_CPUS = 2;
+export const DEFAULT_SANDBOX_MEMORY_MIB = 1024;
+export const DEFAULT_SANDBOX_IDLE_MS = 15 * 60_000;
+/** Package registries and code hosts. Concrete names so every backend can express them. */
+export const DEV_PRESET_HOSTS = Object.freeze([
+    // npm and yarn
+    "registry.npmjs.org",
+    "registry.yarnpkg.com",
+    // Python
+    "pypi.org",
+    "files.pythonhosted.org",
+    // Rust
+    "crates.io",
+    "index.crates.io",
+    "static.crates.io",
+    // Go
+    "proxy.golang.org",
+    "sum.golang.org",
+    // Debian and Ubuntu package mirrors
+    "deb.debian.org",
+    "security.debian.org",
+    "archive.ubuntu.com",
+    "security.ubuntu.com",
+    "ports.ubuntu.com",
+    // Code hosts
+    "github.com",
+    "api.github.com",
+    "codeload.github.com",
+    "objects.githubusercontent.com",
+    "raw.githubusercontent.com",
+    "gitlab.com",
+]);
+export function resolveNetwork(manifest) {
+    const preset = manifest?.network?.preset ?? "dev";
+    const hosts = new Set(preset === "dev" ? DEV_PRESET_HOSTS : []);
+    const suffixes = new Set();
+    for (const entry of manifest?.network?.allow ?? []) {
+        const host = entry.toLowerCase();
+        if (host.startsWith("*."))
+            suffixes.add(host.slice(1));
+        else
+            hosts.add(host);
+    }
+    return Object.freeze({
+        preset,
+        hosts: Object.freeze([...hosts].sort()),
+        suffixes: Object.freeze([...suffixes].sort()),
+    });
+}
+export function idleMsOf(manifest) {
+    return (manifest?.idle && parseSandboxDuration(manifest.idle)) || DEFAULT_SANDBOX_IDLE_MS;
+}
+export function memoryMiBOf(manifest) {
+    const bytes = manifest?.resources?.memory
+        ? parseSandboxSize(manifest.resources.memory)
+        : undefined;
+    return bytes ? Math.max(128, Math.ceil(bytes / 1024 ** 2)) : DEFAULT_SANDBOX_MEMORY_MIB;
+}
+export function describeNetwork(network) {
+    const extra = network.preset === "dev"
+        ? network.hosts.length - DEV_PRESET_HOSTS.length + network.suffixes.length
+        : network.hosts.length + network.suffixes.length;
+    return extra > 0 ? `${network.preset} +${extra} host(s)` : network.preset;
+}

package/dist/sandbox/select.d.ts

@@ -0,0 +1,35 @@
+import type { SandboxBackend, SandboxBackendName, SandboxIsolation, SandboxProbe } from "./types.js";
+export type SandboxPreference = "auto" | SandboxBackendName;
+export interface SandboxSelection {
+    readonly preference: SandboxPreference;
+    readonly backend?: SandboxBackend;
+    /** Why this backend was chosen, or why none could be. */
+    readonly reason: string;
+    readonly probes: readonly SandboxProbe[];
+}
+/** Serializable view of a selection for the CLI and `GET /v1/host/sandbox`. */
+export interface SandboxSelectionReport {
+    readonly preference: SandboxPreference;
+    readonly backend: SandboxBackendName | null;
+    readonly isolation: SandboxIsolation | null;
+    readonly reason: string;
+    readonly probes: readonly SandboxProbe[];
+}
+/** The default order: strongest isolation first, then the backend that always works. */
+export declare function defaultSandboxBackends(options: {
+    readonly root: string;
+}): SandboxBackend[];
+export declare function parseSandboxPreference(value: string | undefined): SandboxPreference | undefined;
+/**
+ * Probe backends in order and pick one. An explicit preference never falls back, so a
+ * production Runtime cannot silently run with weaker isolation than it was configured for.
+ */
+export declare function selectSandboxBackend(backends: readonly SandboxBackend[], preference: SandboxPreference): Promise<SandboxSelection>;
+export declare function reportSelection(selection: SandboxSelection): SandboxSelectionReport;
+/**
+ * Probe this machine the way a Runtime would at startup. Used by `nylorun doctor sandbox`.
+ * Nothing is created or booted.
+ */
+export declare function probeSandboxBackends(options?: {
+    readonly preference?: string;
+}): Promise<SandboxSelectionReport>;

package/dist/sandbox/select.js

@@ -0,0 +1,76 @@
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { microsandboxBackend } from "../adapters/sandbox/microsandbox.js";
+import { virtualBackend } from "../adapters/sandbox/virtual.js";
+const PREFERENCES = ["auto", "microsandbox", "virtual"];
+/** The default order: strongest isolation first, then the backend that always works. */
+export function defaultSandboxBackends(options) {
+    return [microsandboxBackend(), virtualBackend({ root: options.root })];
+}
+export function parseSandboxPreference(value) {
+    const normalized = (value ?? "auto").trim().toLowerCase() || "auto";
+    return PREFERENCES.includes(normalized)
+        ? normalized
+        : undefined;
+}
+/**
+ * Probe backends in order and pick one. An explicit preference never falls back, so a
+ * production Runtime cannot silently run with weaker isolation than it was configured for.
+ */
+export async function selectSandboxBackend(backends, preference) {
+    const probes = [];
+    for (const backend of backends)
+        probes.push(await backend.probe());
+    const probeOf = (name) => probes.find((probe) => probe.name === name);
+    if (preference !== "auto") {
+        const backend = backends.find((item) => item.name === preference);
+        const probe = probeOf(preference);
+        if (backend && probe?.available)
+            return { preference, backend, reason: `${preference} selected by NYLORUN_SANDBOX`, probes };
+        return {
+            preference,
+            reason: `NYLORUN_SANDBOX=${preference} but ${preference} is unavailable: ${probe?.reason ?? "unknown backend"}. Fix it, or unset NYLORUN_SANDBOX to use the best available backend`,
+            probes,
+        };
+    }
+    const index = backends.findIndex((_, i) => probes[i].available);
+    if (index < 0)
+        return {
+            preference,
+            reason: `no sandbox backend is available (${probes.map((probe) => `${probe.name}: ${probe.reason}`).join("; ")})`,
+            probes,
+        };
+    const skipped = probes.slice(0, index).map((probe) => `${probe.name} unavailable: ${probe.reason}`);
+    return {
+        preference,
+        backend: backends[index],
+        reason: skipped.length ? skipped.join("; ") : probes[index].reason ?? backends[index].name,
+        probes,
+    };
+}
+export function reportSelection(selection) {
+    return {
+        preference: selection.preference,
+        backend: selection.backend?.name ?? null,
+        isolation: selection.backend?.isolation ?? null,
+        reason: selection.reason,
+        probes: selection.probes,
+    };
+}
+/**
+ * Probe this machine the way a Runtime would at startup. Used by `nylorun doctor sandbox`.
+ * Nothing is created or booted.
+ */
+export async function probeSandboxBackends(options = {}) {
+    const preference = parseSandboxPreference(options.preference ?? process.env.NYLORUN_SANDBOX);
+    const backends = defaultSandboxBackends({ root: join(tmpdir(), "nylorun-sandbox-probe") });
+    if (!preference)
+        return {
+            preference: "auto",
+            backend: null,
+            isolation: null,
+            reason: "NYLORUN_SANDBOX must be auto, microsandbox or virtual",
+            probes: await Promise.all(backends.map((backend) => backend.probe())),
+        };
+    return reportSelection(await selectSandboxBackend(backends, preference));
+}

package/dist/sandbox/tools.d.ts

@@ -0,0 +1,25 @@
+import { type SandboxToolName } from "@nylorun/core/define";
+import type { SandboxHandle } from "./types.js";
+export type SandboxToolOutcome = {
+    readonly kind: "completed";
+    readonly output: unknown;
+} | {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+};
+/** What the Runtime reports about a tool call on the session stream. */
+export interface SandboxToolReport {
+    readonly command?: string;
+    readonly path?: string;
+    readonly exitCode?: number;
+    readonly killed?: boolean;
+}
+export declare function quote(value: string): string;
+export declare function resolvePath(path: string): string;
+/** Keep the head and tail of long output so the model sees both the start and the error. */
+export declare function truncateMiddle(value: string, limit?: number): {
+    text: string;
+    truncated: boolean;
+};
+export declare function runSandboxTool(handle: SandboxHandle, name: SandboxToolName, input: Record<string, any>, signal: AbortSignal, report: (value: SandboxToolReport) => void): Promise<SandboxToolOutcome>;