@skanl/brambo-sandbox 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createSandboxProviderResolver } from './sandbox.ts';
+export type { ResolvedSandboxSession, SandboxProviderResolver } from './sandbox.ts';

package/dist/index.js

@@ -0,0 +1 @@
+export { createSandboxProviderResolver } from './sandbox.js';

package/dist/sandbox.d.ts

@@ -0,0 +1,16 @@
+import type { SandboxExecutionRequest, SandboxExecutionResult, SandboxCapabilityFacts, SandboxPolicy, SandboxProvider, SandboxSessionRequest, SandboxSnapshot, SandboxStdioSession } from '@skanl/brambo-contracts';
+export interface ResolvedSandboxSession {
+    readonly id: string;
+    readonly providerId: string;
+    readonly capabilities?: SandboxCapabilityFacts;
+    execute(request: SandboxExecutionRequest): Promise<SandboxExecutionResult>;
+    openStdio?(request: SandboxExecutionRequest): Promise<SandboxStdioSession>;
+    snapshot?(paths: readonly string[]): Promise<readonly SandboxSnapshot[]>;
+    restore?(snapshots: readonly SandboxSnapshot[]): Promise<void>;
+    dispose(): Promise<void>;
+}
+export interface SandboxProviderResolver {
+    select(policy: SandboxPolicy): SandboxProvider;
+    createSession(request: SandboxSessionRequest): Promise<ResolvedSandboxSession>;
+}
+export declare function createSandboxProviderResolver(providers: readonly SandboxProvider[]): SandboxProviderResolver;

package/dist/sandbox.js

@@ -0,0 +1,252 @@
+import { BRAMBO_ERROR_CODES, BramboError, validateSandboxCapabilities, validateSandboxExecutionRequest, validateSandboxExecutionResult, validateSandboxPolicy, validateSandboxSnapshot, } from '@skanl/brambo-contracts';
+function unavailable(message, cause) {
+    return new BramboError(BRAMBO_ERROR_CODES.sandboxUnavailable, message, cause === undefined ? {} : { cause });
+}
+function requestInvalid(message) {
+    return new BramboError(BRAMBO_ERROR_CODES.sandboxRequestInvalid, message);
+}
+function validatedSessionRequest(request) {
+    const policy = validateSandboxPolicy(request.policy);
+    if (!Array.isArray(request.snapshots))
+        throw requestInvalid('sandbox session snapshots must be an array');
+    const snapshots = Object.freeze(request.snapshots.map((snapshot) => validateSandboxSnapshot(snapshot)));
+    return Object.freeze({ policy, snapshots });
+}
+function snapshotCapabilities(value) {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const candidate = value;
+    const controls = candidate['controls'];
+    return Object.freeze({
+        version: candidate['version'],
+        providerId: candidate['providerId'],
+        enforcement: candidate['enforcement'],
+        controls: typeof controls !== 'object' || controls === null
+            ? controls
+            : Object.freeze({
+                filesystem: controls['filesystem'],
+                network: controls['network'],
+                process: controls['process'],
+                resources: controls['resources'],
+            }),
+    });
+}
+function snapshotExecutionResult(value) {
+    if (typeof value !== 'object' || value === null)
+        return value;
+    const candidate = value;
+    const error = candidate['error'];
+    const normalizedError = typeof error !== 'object' || error === null
+        ? error
+        : Object.freeze({ code: error['code'], message: error['message'] });
+    return Object.freeze({
+        status: candidate['status'],
+        stdout: candidate['stdout'],
+        stderr: candidate['stderr'],
+        enforcement: snapshotCapabilities(candidate['enforcement']),
+        exitCode: candidate['exitCode'],
+        ...(normalizedError === undefined ? {} : { error: normalizedError }),
+    });
+}
+function selectProvider(providers, policy) {
+    let firstCapabilityFailure;
+    for (const provider of providers) {
+        try {
+            // Provider-owned getters run once, at this boundary. Everything past this
+            // point uses frozen values brambo owns rather than mutable provider state.
+            const providerId = provider.id;
+            const capabilities = validateSandboxCapabilities(policy, snapshotCapabilities(provider.capabilities));
+            const createSession = provider.createSession;
+            if (typeof createSession !== 'function')
+                continue;
+            if (providerId !== capabilities.providerId)
+                continue;
+            return Object.freeze({ provider, providerId, capabilities, createSession: createSession.bind(provider) });
+        }
+        catch (error) {
+            if (error instanceof BramboError && error.code === BRAMBO_ERROR_CODES.sandboxCapabilityUnavailable && firstCapabilityFailure === undefined) {
+                firstCapabilityFailure = error;
+            }
+        }
+    }
+    if (firstCapabilityFailure !== undefined)
+        throw firstCapabilityFailure;
+    throw new BramboError(BRAMBO_ERROR_CODES.sandboxCapabilityUnavailable, 'no sandbox provider proves every required capability');
+}
+function normalizedSession(value) {
+    if (typeof value !== 'object' || value === null)
+        throw new Error('sandbox provider returned a non-object session');
+    const candidate = value;
+    const { id, execute, openStdio, snapshot, restore, dispose } = candidate;
+    if (typeof id !== 'string' || id.length === 0 || typeof execute !== 'function' || typeof dispose !== 'function') {
+        throw new Error('sandbox provider returned an invalid session');
+    }
+    return Object.freeze({
+        id,
+        execute: execute.bind(value),
+        ...(typeof openStdio === 'function' ? { openStdio: openStdio.bind(value) } : {}),
+        ...(typeof snapshot === 'function' ? { snapshot: snapshot.bind(value) } : {}),
+        ...(typeof restore === 'function' ? { restore: restore.bind(value) } : {}),
+        dispose: dispose.bind(value),
+    });
+}
+class ManagedSandboxSession {
+    session;
+    policy;
+    providerId;
+    capabilitiesValue;
+    #state = 'active';
+    #disposePromise;
+    constructor(session, policy, providerId, capabilitiesValue) {
+        this.session = session;
+        this.policy = policy;
+        this.providerId = providerId;
+        this.capabilitiesValue = capabilitiesValue;
+    }
+    get id() {
+        return this.session.id;
+    }
+    get capabilities() {
+        return this.capabilitiesValue;
+    }
+    async execute(request) {
+        if (this.#state !== 'active')
+            throw unavailable(`sandbox session '${this.id}' is not reusable after teardown begins`);
+        const validated = validateSandboxExecutionRequest(request);
+        if (!samePolicy(this.policy, validated.policy)) {
+            throw requestInvalid(`sandbox execution policy does not match session '${this.id}' policy`);
+        }
+        let executionResult;
+        try {
+            executionResult = await this.session.execute(validated);
+        }
+        catch (error) {
+            this.#state = 'uncertain';
+            throw unavailable(`sandbox session '${this.id}' execution failed without a structured result`, error);
+        }
+        try {
+            let resultSnapshot;
+            try {
+                // Snapshot every provider-owned result property before local validation so
+                // hostile getters cannot choose brambo's outward error vocabulary.
+                resultSnapshot = snapshotExecutionResult(executionResult);
+            }
+            catch (error) {
+                throw unavailable(`sandbox session '${this.id}' execution result could not be normalized`, error);
+            }
+            const result = validateSandboxExecutionResult(resultSnapshot);
+            const enforcement = validateSandboxCapabilities(this.policy, result.enforcement);
+            if (enforcement.providerId !== this.capabilitiesValue.providerId) {
+                throw new BramboError(BRAMBO_ERROR_CODES.sandboxResponseInvalid, `sandbox session '${this.id}' returned enforcement for provider '${enforcement.providerId}', not selected provider '${this.providerId}'`);
+            }
+            return result;
+        }
+        catch (error) {
+            this.#state = 'uncertain';
+            if (error instanceof BramboError)
+                throw error;
+            throw unavailable(`sandbox session '${this.id}' execution result could not be validated`, error);
+        }
+    }
+    async openStdio(request) {
+        if (this.#state !== 'active')
+            throw unavailable(`sandbox session '${this.id}' is not reusable after teardown begins`);
+        const validated = validateSandboxExecutionRequest(request);
+        if (!samePolicy(this.policy, validated.policy))
+            throw requestInvalid(`sandbox execution policy does not match session '${this.id}' policy`);
+        const openStdio = this.session.openStdio;
+        if (typeof openStdio !== 'function')
+            throw unavailable(`sandbox session '${this.id}' does not expose stdio`);
+        try {
+            return await openStdio(validated);
+        }
+        catch (error) {
+            this.#state = 'uncertain';
+            throw unavailable(`sandbox session '${this.id}' stdio could not be opened`, error);
+        }
+    }
+    async snapshot(paths) {
+        if (this.#state !== 'active')
+            throw unavailable(`sandbox session '${this.id}' is not reusable after teardown begins`);
+        const snapshot = this.session.snapshot;
+        if (typeof snapshot !== 'function')
+            throw unavailable(`sandbox session '${this.id}' does not expose snapshots`);
+        try {
+            return Object.freeze((await snapshot.call(this.session, Object.freeze([...paths]))).map((entry) => validateSandboxSnapshot(entry)));
+        }
+        catch (error) {
+            this.#state = 'uncertain';
+            throw unavailable(`sandbox session '${this.id}' snapshots could not be created`, error);
+        }
+    }
+    async restore(snapshots) {
+        if (this.#state !== 'active')
+            throw unavailable(`sandbox session '${this.id}' is not reusable after teardown begins`);
+        const restore = this.session.restore;
+        if (typeof restore !== 'function')
+            throw unavailable(`sandbox session '${this.id}' does not expose snapshot restore`);
+        try {
+            await restore.call(this.session, Object.freeze(snapshots.map((entry) => validateSandboxSnapshot(entry))));
+        }
+        catch (error) {
+            this.#state = 'uncertain';
+            throw unavailable(`sandbox session '${this.id}' snapshots could not be restored`, error);
+        }
+    }
+    dispose() {
+        if (this.#disposePromise !== undefined)
+            return this.#disposePromise;
+        this.#state = 'disposing';
+        this.#disposePromise = Promise.resolve()
+            .then(() => this.session.dispose())
+            .then(() => {
+            this.#state = 'disposed';
+        }, (error) => {
+            this.#state = 'uncertain';
+            throw unavailable(`sandbox session '${this.id}' teardown outcome is uncertain`, error);
+        });
+        return this.#disposePromise;
+    }
+}
+function samePolicy(left, right) {
+    if (left.version !== right.version ||
+        left.mode !== right.mode ||
+        left.workspaceRoot !== right.workspaceRoot ||
+        (left.networkMode ?? 'deny') !== (right.networkMode ?? 'deny') ||
+        left.allowDangerous !== right.allowDangerous) {
+        return false;
+    }
+    const leftEntries = Object.entries(left.requiredCapabilities).sort(([a], [b]) => a.localeCompare(b));
+    const rightEntries = Object.entries(right.requiredCapabilities).sort(([a], [b]) => a.localeCompare(b));
+    if (!(leftEntries.length === rightEntries.length && leftEntries.every(([key, value], index) => rightEntries[index]?.[0] === key && rightEntries[index]?.[1] === value)))
+        return false;
+    const leftLimits = Object.entries(left.resourceLimits ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    const rightLimits = Object.entries(right.resourceLimits ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    return leftLimits.length === rightLimits.length && leftLimits.every(([key, value], index) => rightLimits[index]?.[0] === key && rightLimits[index]?.[1] === value);
+}
+export function createSandboxProviderResolver(providers) {
+    const available = Object.freeze([...providers]);
+    function select(policy) {
+        const validated = validateSandboxPolicy(policy);
+        if (available.length === 0)
+            throw unavailable('no sandbox providers are registered');
+        return selectProvider(available, validated).provider;
+    }
+    return Object.freeze({
+        select,
+        async createSession(request) {
+            const validated = validatedSessionRequest(request);
+            if (available.length === 0)
+                throw unavailable('no sandbox providers are registered');
+            const selected = selectProvider(available, validated.policy);
+            let session;
+            try {
+                session = normalizedSession(await selected.createSession(validated));
+            }
+            catch (error) {
+                throw unavailable('sandbox provider could not create a session', error);
+            }
+            return new ManagedSandboxSession(session, validated.policy, selected.providerId, selected.capabilities);
+        },
+    });
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@skanl/brambo-sandbox",
+  "version": "0.1.1",
+  "description": "Provider-neutral sandbox selection, capability negotiation, and session lifecycle management.",
+  "keywords": [
+    "ai-agent",
+    "brambo",
+    "sandbox",
+    "capability"
+  ],
+  "homepage": "https://github.com/SKANL/brambo#readme",
+  "bugs": {
+    "url": "https://github.com/SKANL/brambo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SKANL/brambo.git",
+    "directory": "packages/sandbox"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "brambo-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@skanl/brambo-contracts": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~7.0.2",
+    "vitest": "^4.1.11"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.build.json"
+  }
+}