@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/record/append.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The only write path into the record (Durable Streams §6, blueprint D27): the session's log
+ * head allocates the next sequence, the event is built on the envelope and checked against the
+ * catalog, and its row is written, both in the caller's transaction. The database holds one
+ * Tenant, so rows are keyed by session alone; the Tenant id is the caller's and goes into the
+ * envelope only. The caller holds the session row lock, which orders the session's appends,
+ * and passes the epoch it read under that lock.
+ *
+ * The two statements run through `RecordWriter`, which the store implements on its
+ * transaction (`store/postgres/record-writer.ts`): the database driver stays behind
+ * `store/postgres/` (session-store.md §3), and this module decides what is written.
+ */
+import type { EventPayload, EventType, LiveEvent, SessionEventOf } from "@nylorun/core/contracts";
+/** The record's two statements, in the caller's transaction. */
+export interface RecordWriter {
+    /**
+     * Advances the session's log head: the seq its next event takes, and the basin generation
+     * its events go to (a session's first event takes the Tenant's current one).
+     */
+    advance(sessionId: string): Promise<{
+        seq: number;
+        generation: number;
+    }>;
+    /** Writes the event's row. */
+    insert(row: {
+        sessionId: string;
+        seq: number;
+        generation: number;
+        type: string;
+        body: LiveEvent;
+    }): Promise<void>;
+}
+export interface AppendInput<T extends EventType> {
+    /** The database's one Tenant, for the envelope. */
+    tenantId: string;
+    sessionId: string;
+    turnId: string | null;
+    /** The session's ownership epoch, read under the caller's session row lock. */
+    epoch: number;
+    time: Date;
+    type: T;
+    payload: EventPayload<T>;
+}
+/**
+ * Appends one event through `writer`. An event the catalog does not describe throws
+ * `InvalidEventError` before its row is written; the caller's transaction then rolls back.
+ */
+export declare function appendEvent<T extends EventType>(writer: RecordWriter, input: AppendInput<T>): Promise<{
+    event: SessionEventOf<T>;
+    generation: number;
+}>;

package/dist/record/append.js

@@ -0,0 +1,20 @@
+import { buildEvent } from "./envelope.js";
+/**
+ * Appends one event through `writer`. An event the catalog does not describe throws
+ * `InvalidEventError` before its row is written; the caller's transaction then rolls back.
+ */
+export async function appendEvent(writer, input) {
+    const { seq, generation } = await writer.advance(input.sessionId);
+    const event = buildEvent({
+        tenantId: input.tenantId,
+        sessionId: input.sessionId,
+        turnId: input.turnId,
+        seq,
+        epoch: input.epoch,
+        time: input.time,
+        type: input.type,
+        payload: input.payload,
+    });
+    await writer.insert({ sessionId: input.sessionId, seq, generation, type: input.type, body: event });
+    return { event, generation };
+}

package/dist/record/envelope.d.ts

@@ -0,0 +1,19 @@
+import { type EventPayload, type EventType, type SessionEventOf } from "@nylorun/core/contracts";
+/** A write of an event the catalog does not describe: a bug in the writer. */
+export declare class InvalidEventError extends Error {
+    readonly eventType: string;
+    constructor(eventType: string, detail: string);
+}
+export interface EventInput<T extends EventType> {
+    tenantId: string;
+    sessionId: string;
+    turnId: string | null;
+    seq: number;
+    /** The session's ownership epoch when the event is written. */
+    epoch: number;
+    time: Date;
+    type: T;
+    payload: EventPayload<T>;
+}
+/** The event as stored and streamed: JSON-normalized, validated. Throws `InvalidEventError`. */
+export declare function buildEvent<T extends EventType>(input: EventInput<T>): SessionEventOf<T>;

package/dist/record/envelope.js

@@ -0,0 +1,49 @@
+/**
+ * Builds a session event on the `nylorun.event/2` envelope and checks it against the event
+ * catalog (Durable Streams §9.5) before a store writes it. Both stores call it inside
+ * `Tx.event`, so nothing the catalog does not describe reaches a stream.
+ */
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { EVENT_CATALOG, EVENT_SCHEMA, EVENT_SCHEMAS, isEventType, } from "@nylorun/core/contracts";
+import { encodeCursor } from "./cursor.js";
+/** A write of an event the catalog does not describe: a bug in the writer. */
+export class InvalidEventError extends Error {
+    eventType;
+    constructor(eventType, detail) {
+        super(`Event ${eventType} does not match the event catalog: ${detail}`);
+        this.eventType = eventType;
+        this.name = "InvalidEventError";
+    }
+}
+/** The event as stored and streamed: JSON-normalized, validated. Throws `InvalidEventError`. */
+export function buildEvent(input) {
+    const type = input.type;
+    if (!isEventType(type))
+        throw new InvalidEventError(type, "unknown type");
+    const entry = EVENT_CATALOG[type];
+    const event = JSON.parse(JSON.stringify({
+        schema: EVENT_SCHEMA,
+        eventId: randomUUID(),
+        tenantId: input.tenantId,
+        sessionId: input.sessionId,
+        runId: null,
+        turnId: input.turnId,
+        incarnation: 0,
+        epoch: input.epoch,
+        seq: input.seq,
+        cursor: encodeCursor(input.sessionId, input.seq),
+        time: input.time.toISOString(),
+        schemaVersion: entry.version,
+        source: { kind: entry.source, id: "runtime" },
+        evidence: "observed",
+        visibility: entry.visibility ?? "public",
+        retention: "full",
+        type,
+        payload: input.payload,
+    }));
+    const checked = EVENT_SCHEMAS[type].safeParse(event);
+    if (!checked.success)
+        throw new InvalidEventError(type, z.prettifyError(checked.error));
+    return event;
+}

package/dist/record/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The record module (blueprint D27): the one write path into the record. It builds each event
+ * on the `nylorun.event/2` envelope, checks it against the event catalog, and holds the only
+ * insert into `session_events` and `session_log_heads`, whose Postgres statements it runs
+ * through the store's `RecordWriter` (`store/postgres/record-writer.ts`;
+ * `scripts/check-boundaries.mjs` refuses an insert anywhere else). Other folders import this
+ * file, never the module's own files.
+ */
+export { buildEvent, InvalidEventError, type EventInput } from "./envelope.js";
+export { decodeCursor, encodeCursor } from "./cursor.js";
+export { appendEvent, type AppendInput, type RecordWriter } from "./append.js";

package/dist/record/index.js

@@ -0,0 +1,11 @@
+/**
+ * The record module (blueprint D27): the one write path into the record. It builds each event
+ * on the `nylorun.event/2` envelope, checks it against the event catalog, and holds the only
+ * insert into `session_events` and `session_log_heads`, whose Postgres statements it runs
+ * through the store's `RecordWriter` (`store/postgres/record-writer.ts`;
+ * `scripts/check-boundaries.mjs` refuses an insert anywhere else). Other folders import this
+ * file, never the module's own files.
+ */
+export { buildEvent, InvalidEventError } from "./envelope.js";
+export { decodeCursor, encodeCursor } from "./cursor.js";
+export { appendEvent } from "./append.js";

package/dist/sandbox/manager.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 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.
+ *
+ * The manager keeps no timers. The Tenant sweep calls `sweep`, which stops sandboxes idle
+ * past their timeout, marks records of compute this process no longer holds as stopped
+ * (after a restart), and, once per process, removes sandboxes whose session is gone.
+ */
+import type { EventPayload } from "@nylorun/core/contracts";
 import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
 import type { SessionStore } from "../store/types.js";
 import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
@@ -34,8 +44,10 @@ export interface SandboxManagerOptions {
     /** Delete sandboxes on close (the Runtime's store does not outlive the process). */
     readonly ephemeral: boolean;
     /** Writes a session event in its own transaction; never called inside one. */
-    readonly emit: (sessionId: string, turnId: string | null, type: string, payload: unknown) => void | Promise<void>;
+    readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>) => void | Promise<void>;
 }
+/** The session events a sandbox writes. */
+export type SandboxEventType = "sandbox.state" | "sandbox.exec";
 /** 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 {

package/dist/sandbox/manager.js

@@ -1,12 +1,3 @@
-/**
- * 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.
- *
- * The manager keeps no timers. The Tenant sweep calls `sweep`, which stops sandboxes idle
- * past their timeout, marks records of compute this process no longer holds as stopped
- * (after a restart), and, once per process, removes sandboxes whose session is gone.
- */
 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";
@@ -172,7 +163,7 @@ export class SandboxManager {
                 return {
                     kind: "failed",
                     code: "sandbox.start_failed",
-                    message: `The sandbox could not start on ${live.backend.name} (image ${spec.image}): ${message}`,
+                    message: `The sandbox could not start on ${live.backend.name} (image ${spec.image ?? "the backend's default"}): ${message}`,
                 };
             }
         }
@@ -220,7 +211,13 @@ export class SandboxManager {
         });
         const handle = await live.backend.open(spec);
         await this.record(spec.key, session.id, live.backend.name, spec.image, "running", existing);
-        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", { state: "running", ...payload });
+        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
+            state: "running",
+            ...payload,
+            ...(existing && handle.created
+                ? { lost: true, note: "The sandbox was gone and was created again; its earlier files are lost." }
+                : {}),
+        });
         return handle;
     }
     async stop(key, live) {

package/dist/sandbox/resolve.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolves the sandbox a session asks for when it is opened against its Tenant's configuration.
+ * Pure: the caller supplies the configuration and who is asking. Every problem is
+ * reported, not only the first, so one response lists all of them.
+ */
+import type { SandboxInlineRequest } from "@nylorun/core/contracts";
+import type { SandboxManifest } from "@nylorun/core/define";
+import { type EffectiveSandboxConfig } from "./tenant-config.js";
+export type SandboxSource = "default" | "inline";
+export type SandboxResolution = {
+    readonly kind: "none";
+} | {
+    readonly kind: "sandbox";
+    readonly spec: SandboxManifest;
+    readonly source: SandboxSource;
+} | {
+    readonly kind: "error";
+    readonly status: 400 | 403;
+    readonly errors: readonly string[];
+};
+export interface ResolveSandboxInput {
+    /** `PutSessionRequest.sandbox` other than `{ session }`, which the caller handles. */
+    readonly request: false | SandboxInlineRequest | undefined;
+    readonly config: EffectiveSandboxConfig;
+    /** The request acts for a subject (`Nylorun-Subject`) rather than as the application. */
+    readonly actingForSubject: boolean;
+}
+export declare const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
+export declare function resolveSandbox(input: ResolveSandboxInput): SandboxResolution;
+/** Whether `host` (a name or `*.suffix` pattern) is inside one of the ceiling's patterns. */
+export declare function withinCeiling(host: string, ceiling: readonly string[]): boolean;
+/** Problems with a Tenant configuration, checked when an operator saves it. */
+export declare function sandboxConfigErrors(config: EffectiveSandboxConfig): string[];

package/dist/sandbox/resolve.js

@@ -0,0 +1,81 @@
+import { memoryMiB } from "./tenant-config.js";
+export const SUBJECT_INLINE_MESSAGE = "Defining a sandbox needs an application key. Use the Tenant default, or open the session from the application backend.";
+export function resolveSandbox(input) {
+    const { request, config } = input;
+    if (request === false)
+        return { kind: "none" };
+    if (request === undefined) {
+        const fallback = config.default;
+        if (fallback === "none")
+            return { kind: "none" };
+        return build(fallback === "virtual" ? {} : fallback, "default", input);
+    }
+    if (input.actingForSubject)
+        return { kind: "error", status: 403, errors: [SUBJECT_INLINE_MESSAGE] };
+    return build(request, "inline", input);
+}
+function build(request, source, input) {
+    const { limits } = input.config;
+    const errors = [];
+    if (request.image !== undefined)
+        errors.push("sandbox.image is not supported: the virtual sandbox has no images.");
+    const allow = (request.network?.allow ?? []).map((host) => host.toLowerCase());
+    for (const host of allow) {
+        if (!withinCeiling(host, limits.network))
+            errors.push(`sandbox.network.allow includes ${host}, which this Tenant does not allow.`);
+        else if (host.startsWith("*."))
+            errors.push(`sandbox.network.allow includes ${host}; the virtual sandbox allows exact host names only, such as ${host.slice(2)}.`);
+    }
+    const cpus = request.resources?.cpus ?? limits.defaultResources.cpus;
+    const memory = request.resources?.memory === undefined
+        ? limits.defaultResources.memoryMiB
+        : memoryMiB(request.resources.memory);
+    if (cpus > limits.resources.cpus)
+        errors.push(`sandbox.resources.cpus asks for ${cpus}; this Tenant allows at most ${limits.resources.cpus}.`);
+    if (memory > limits.resources.memoryMiB)
+        errors.push(`sandbox.resources.memory asks for ${memory}MiB; this Tenant allows at most ${limits.resources.memoryMiB}MiB.`);
+    if (errors.length > 0)
+        return { kind: "error", status: 400, errors };
+    const unique = [...new Set(allow)].sort();
+    const spec = {
+        ...(request.image === undefined ? {} : { image: request.image }),
+        network: { preset: "none", ...(unique.length > 0 ? { allow: unique } : {}) },
+        resources: { cpus, memory: `${memory}MiB` },
+        idle: limits.idle,
+    };
+    return { kind: "sandbox", spec, source };
+}
+/** Whether `host` (a name or `*.suffix` pattern) is inside one of the ceiling's patterns. */
+export function withinCeiling(host, ceiling) {
+    const name = host.toLowerCase();
+    for (const entry of ceiling.map((item) => item.toLowerCase())) {
+        if (entry === name)
+            return true;
+        if (entry.startsWith("*.")) {
+            const suffix = entry.slice(1);
+            const target = name.startsWith("*.") ? name.slice(1) : name;
+            if (target.endsWith(suffix))
+                return true;
+        }
+    }
+    return false;
+}
+/** Problems with a Tenant configuration, checked when an operator saves it. */
+export function sandboxConfigErrors(config) {
+    const errors = [];
+    const { limits } = config;
+    if (limits.defaultResources.cpus > limits.resources.cpus)
+        errors.push("limits.defaultResources.cpus is above limits.resources.cpus.");
+    if (limits.defaultResources.memoryMiB > limits.resources.memoryMiB)
+        errors.push("limits.defaultResources.memory is above limits.resources.memory.");
+    if (config.default !== "none" && config.default !== "virtual") {
+        const resolved = resolveSandbox({
+            request: undefined,
+            config,
+            actingForSubject: false,
+        });
+        if (resolved.kind === "error")
+            errors.push(...resolved.errors.map((message) => `default: ${message}`));
+    }
+    return errors;
+}

package/dist/sandbox/session-sandbox.d.ts

@@ -0,0 +1,11 @@
+import { type AgentManifest, type SandboxManifest } from "@nylorun/core/define";
+export type SandboxedManifest = {
+    readonly ok: true;
+    readonly manifest: AgentManifest;
+    readonly manifestHash: string;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** The agent's manifest with the sandbox capability added, or why it cannot take one. */
+export declare function withSandboxCapability(manifest: AgentManifest, spec: SandboxManifest): SandboxedManifest;

package/dist/sandbox/session-sandbox.js

@@ -0,0 +1,51 @@
+/**
+ * Gives a session the sandbox chosen when it was opened. An agent session's pinned manifest is
+ * its definition plus the `nylorun.sandbox` capability (the six built-in tools, the sandbox
+ * instructions and the resolved spec), also added to each agent it uses as a tool, so the tree
+ * shares one spec. The definition in the registry never changes.
+ */
+import { AgentManifestSchema } from "@nylorun/core/contracts";
+import { hashManifest, sandboxCapabilityManifest, } from "@nylorun/core/define";
+import { sandboxSpecOf } from "./share.js";
+function isAgentManifest(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind !== "workflow" &&
+        Array.isArray(value.capabilities));
+}
+function addCapability(manifest, spec) {
+    const capabilities = manifest.capabilities.map((capability) => capability.tools === undefined
+        ? capability
+        : {
+            ...capability,
+            tools: capability.tools.map((tool) => {
+                // Agents used as tools share the session's sandbox; flow agents used as tools run
+                // in linked sessions that inherit it.
+                if (tool.agent === undefined || !isAgentManifest(tool.agent))
+                    return tool;
+                if (sandboxSpecOf(tool.agent) !== undefined)
+                    return tool;
+                return { ...tool, agent: addCapability(tool.agent, spec) };
+            }),
+        });
+    return {
+        ...manifest,
+        capabilities: [...capabilities, sandboxCapabilityManifest(spec)],
+    };
+}
+/** The agent's manifest with the sandbox capability added, or why it cannot take one. */
+export function withSandboxCapability(manifest, spec) {
+    const sandboxed = addCapability(manifest, spec);
+    const parsed = AgentManifestSchema.safeParse(sandboxed);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => issue.message);
+        const clash = issues.some((message) => message === "Tool names must be unique");
+        return {
+            ok: false,
+            message: clash
+                ? `'${manifest.id}' declares a tool named like a sandbox tool (bash, read, write, edit, grep, glob). Rename it, or open the session with sandbox: false.`
+                : `'${manifest.id}' cannot take this sandbox: ${[...new Set(issues)].join("; ")}`,
+        };
+    }
+    return { ok: true, manifest: sandboxed, manifestHash: hashManifest(sandboxed) };
+}

package/dist/sandbox/share.d.ts

@@ -1,6 +1,8 @@
 /**
- * Shared workflow sandbox: one sandbox per owning session, attached via
- * PutSession.sandbox = { session }. Specs must match; keys use the owner id.
+ * Shared sandboxes: one sandbox per owning session, attached via PutSession.sandbox =
+ * { session }; keys use the owner id. A sandbox is either declared by the definition (an agent
+ * capability or a workflow's `sandbox`) or chosen when the session was opened and pinned on the
+ * session record (`sandbox`).
  */
 import { type AgentManifest, type CapabilityManifest, type SandboxManifest, type WorkflowManifest } from "@nylorun/core/define";
 export type SessionSandboxRef = {
@@ -9,9 +11,19 @@ export type SessionSandboxRef = {
     readonly manifest: AgentManifest | WorkflowManifest | Record<string, unknown>;
     /** Session whose id keys the sandbox. Absent means this session owns its own. */
     readonly sandboxOwnerId?: string | null;
+    /** The sandbox chosen when the session was opened (or inherited from its owner), resolved. */
+    readonly sandbox?: SandboxManifest;
 };
+/** The session's sandbox spec: the one pinned at open, else the one its definition declares. */
+export declare function sessionSandboxSpec(session: SessionSandboxRef): SandboxManifest | undefined;
 /** Sandbox spec declared on an agent capability or a workflow manifest. */
 export declare function sandboxSpecOf(manifest: AgentManifest | WorkflowManifest | Record<string, unknown> | undefined): SandboxManifest | undefined;
+/**
+ * Where a definition document declares a sandbox: agent capabilities, the agents inlined as
+ * tools or embedded in a flow agent, and a workflow's `sandbox`. Definitions no longer declare
+ * one (Sandboxes v3), so registration refuses any of these.
+ */
+export declare function declaredSandboxes(manifest: unknown, into?: string[]): string[];
 export declare function sandboxSpecsEqual(a: SandboxManifest | undefined, b: SandboxManifest | undefined): boolean;
 /** Synthetic capability so SandboxManager.run can use a workflow (or shared) spec. */
 export declare function capabilityForSandbox(sandbox: SandboxManifest): CapabilityManifest;

package/dist/sandbox/share.js

@@ -1,8 +1,14 @@
 /**
- * Shared workflow sandbox: one sandbox per owning session, attached via
- * PutSession.sandbox = { session }. Specs must match; keys use the owner id.
+ * Shared sandboxes: one sandbox per owning session, attached via PutSession.sandbox =
+ * { session }; keys use the owner id. A sandbox is either declared by the definition (an agent
+ * capability or a workflow's `sandbox`) or chosen when the session was opened and pinned on the
+ * session record (`sandbox`).
  */
 import { canonical, } from "@nylorun/core/define";
+/** The session's sandbox spec: the one pinned at open, else the one its definition declares. */
+export function sessionSandboxSpec(session) {
+    return session.sandbox ?? sandboxSpecOf(session.manifest);
+}
 /** Sandbox spec declared on an agent capability or a workflow manifest. */
 export function sandboxSpecOf(manifest) {
     if (!manifest || typeof manifest !== "object")
@@ -17,6 +23,30 @@ export function sandboxSpecOf(manifest) {
             return capability.sandbox;
     return undefined;
 }
+/**
+ * Where a definition document declares a sandbox: agent capabilities, the agents inlined as
+ * tools or embedded in a flow agent, and a workflow's `sandbox`. Definitions no longer declare
+ * one (Sandboxes v3), so registration refuses any of these.
+ */
+export function declaredSandboxes(manifest, into = []) {
+    if (!manifest || typeof manifest !== "object")
+        return into;
+    const document = manifest;
+    if (document.kind === "workflow") {
+        if (document.sandbox !== undefined)
+            into.push(`flow agent '${document.id}'`);
+        for (const agent of Object.values(document.agents ?? {}))
+            declaredSandboxes(agent, into);
+        return into;
+    }
+    for (const capability of document.capabilities ?? []) {
+        if (capability.sandbox !== undefined)
+            into.push(`'${document.id}' (capability '${capability.id}')`);
+        for (const tool of capability.tools ?? [])
+            declaredSandboxes(tool.agent, into);
+    }
+    return into;
+}
 export function sandboxSpecsEqual(a, b) {
     if (a === undefined && b === undefined)
         return true;
@@ -54,5 +84,5 @@ export function owningSandboxSessionId(session, lookup) {
 export function sessionHasSandbox(session, lookup) {
     const ownerId = owningSandboxSessionId(session, lookup);
     const owner = ownerId === session.id ? session : lookup(ownerId) ?? session;
-    return sandboxSpecOf(owner.manifest) !== undefined || sandboxSpecOf(session.manifest) !== undefined;
+    return sessionSandboxSpec(owner) !== undefined || sessionSandboxSpec(session) !== undefined;
 }

package/dist/sandbox/tenant-config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A Tenant's sandbox configuration, stored as Tenant setting `sandbox.config`: the sandbox a
+ * session gets when it names none, and the limits every session's sandbox must fit. Unset
+ * fields take the defaults below.
+ */
+import { type SandboxInlineRequest, type TenantSandboxConfig } from "@nylorun/core/contracts";
+export declare const SANDBOX_CONFIG_SETTING = "sandbox.config";
+/** The most a session may ask for when the Tenant sets no maximum. */
+export declare const DEFAULT_MAX_CPUS = 4;
+export declare const DEFAULT_MAX_MEMORY_MIB = 8192;
+export declare const DEFAULT_SANDBOX_IDLE = "15m";
+export interface SandboxResourcesLimit {
+    readonly cpus: number;
+    readonly memoryMiB: number;
+}
+/** A configuration with every default applied. */
+export interface EffectiveSandboxConfig {
+    readonly default: "none" | "virtual" | SandboxInlineRequest;
+    readonly limits: {
+        readonly network: readonly string[];
+        readonly resources: SandboxResourcesLimit;
+        readonly defaultResources: SandboxResourcesLimit;
+        readonly idle: string;
+    };
+}
+interface SettingsReader {
+    getSetting(key: string): Promise<string | undefined>;
+}
+interface SettingsWriter extends SettingsReader {
+    putSetting(key: string, value: string): Promise<void>;
+}
+export declare function memoryMiB(value: string): number;
+export declare function effectiveSandboxConfig(config: TenantSandboxConfig): EffectiveSandboxConfig;
+/** The stored configuration, or `{}` when the Tenant has none. */
+export declare function readSandboxConfig(t: SettingsReader): Promise<TenantSandboxConfig>;
+export declare function writeSandboxConfig(t: SettingsWriter, config: TenantSandboxConfig): Promise<void>;
+export {};

package/dist/sandbox/tenant-config.js

@@ -0,0 +1,51 @@
+/**
+ * A Tenant's sandbox configuration, stored as Tenant setting `sandbox.config`: the sandbox a
+ * session gets when it names none, and the limits every session's sandbox must fit. Unset
+ * fields take the defaults below.
+ */
+import { TenantSandboxConfigSchema, } from "@nylorun/core/contracts";
+import { parseSandboxSize } from "@nylorun/core/define";
+import { DEFAULT_SANDBOX_CPUS, DEFAULT_SANDBOX_MEMORY_MIB, DEV_PRESET_HOSTS, } from "./policy.js";
+export const SANDBOX_CONFIG_SETTING = "sandbox.config";
+/** The most a session may ask for when the Tenant sets no maximum. */
+export const DEFAULT_MAX_CPUS = 4;
+export const DEFAULT_MAX_MEMORY_MIB = 8192;
+export const DEFAULT_SANDBOX_IDLE = "15m";
+export function memoryMiB(value) {
+    const bytes = parseSandboxSize(value);
+    return bytes === undefined ? 0 : Math.max(128, Math.ceil(bytes / 1024 ** 2));
+}
+function resources(value, fallback) {
+    return {
+        cpus: value?.cpus ?? fallback.cpus,
+        memoryMiB: value?.memory === undefined ? fallback.memoryMiB : memoryMiB(value.memory),
+    };
+}
+export function effectiveSandboxConfig(config) {
+    const limits = config.limits ?? {};
+    return {
+        default: config.default ?? "none",
+        limits: {
+            network: limits.network ?? DEV_PRESET_HOSTS,
+            resources: resources(limits.resources, {
+                cpus: DEFAULT_MAX_CPUS,
+                memoryMiB: DEFAULT_MAX_MEMORY_MIB,
+            }),
+            defaultResources: resources(limits.defaultResources, {
+                cpus: DEFAULT_SANDBOX_CPUS,
+                memoryMiB: DEFAULT_SANDBOX_MEMORY_MIB,
+            }),
+            idle: limits.idle ?? DEFAULT_SANDBOX_IDLE,
+        },
+    };
+}
+/** The stored configuration, or `{}` when the Tenant has none. */
+export async function readSandboxConfig(t) {
+    const raw = await t.getSetting(SANDBOX_CONFIG_SETTING);
+    if (raw === undefined)
+        return {};
+    return TenantSandboxConfigSchema.parse(JSON.parse(raw));
+}
+export async function writeSandboxConfig(t, config) {
+    await t.putSetting(SANDBOX_CONFIG_SETTING, JSON.stringify(config));
+}

package/dist/sandbox/tools.d.ts

@@ -1,13 +1,7 @@
+import type { SandboxToolOutcome } from "@nylorun/core/contracts";
 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;
-};
+export type { SandboxToolOutcome };
 /** What the Runtime reports about a tool call on the session stream. */
 export interface SandboxToolReport {
     readonly command?: string;
@@ -16,7 +10,11 @@ export interface SandboxToolReport {
     readonly killed?: boolean;
 }
 export declare function quote(value: string): string;
-export declare function resolvePath(path: string): string;
+/**
+ * An absolute path inside the sandbox. Relative paths are relative to the workspace; on a backend
+ * whose workspace is not `/workspace`, `/workspace/…` still names it.
+ */
+export declare function resolveSandboxPath(path: string, workspace?: 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;

package/dist/sandbox/tools.js

@@ -14,8 +14,14 @@ const GLOB_SCAN_LIMIT = 20_000;
 export function quote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
-export function resolvePath(path) {
-    return posix.normalize(path.startsWith("/") ? path : posix.join(SANDBOX_WORKSPACE, path));
+/**
+ * An absolute path inside the sandbox. Relative paths are relative to the workspace; on a backend
+ * whose workspace is not `/workspace`, `/workspace/…` still names it.
+ */
+export function resolveSandboxPath(path, workspace = SANDBOX_WORKSPACE) {
+    if (workspace !== SANDBOX_WORKSPACE && (path === SANDBOX_WORKSPACE || path.startsWith(`${SANDBOX_WORKSPACE}/`)))
+        path = workspace + path.slice(SANDBOX_WORKSPACE.length);
+    return posix.normalize(path.startsWith("/") ? path : posix.join(workspace, path));
 }
 /** Keep the head and tail of long output so the model sees both the start and the error. */
 export function truncateMiddle(value, limit = OUTPUT_LIMIT) {
@@ -34,7 +40,9 @@ const failed = (code, message) => ({
     message,
 });
 export async function runSandboxTool(handle, name, input, signal, report) {
-    const exec = (command, timeoutMs = 60_000) => handle.exec({ command, cwd: SANDBOX_WORKSPACE, timeoutMs }, signal);
+    const workspace = handle.workspace ?? SANDBOX_WORKSPACE;
+    const resolvePath = (path) => resolveSandboxPath(path, workspace);
+    const exec = (command, timeoutMs = 60_000) => handle.exec({ command, cwd: workspace, timeoutMs }, signal);
     switch (name) {
         case "bash": {
             const command = String(input.command);