@douglas-agent/sandbank-aio 0.1.0

package/dist/AIOSandboxAdapter.d.ts

@@ -0,0 +1,38 @@
+import type { AdapterSandbox, Capability, CreateConfig, ListFilter, SandboxAdapter, SandboxInfo } from '@douglas-agent/sandbank-core';
+import { type AIOSandboxAdapterConfig } from './types.js';
+/**
+ * AIOSandboxAdapter — wraps `ghcr.io/agent-infra/sandbox` Docker container
+ * lifecycle with dockerode, exposes business operations through
+ * `@agent-infra/sandbox` `SandboxClient`.
+ *
+ * Each `createSandbox()` call:
+ *   1. allocates a free host port from the configured range
+ *   2. `docker run` the AIO Sandbox image with port `8080` → host port mapping
+ *   3. polls container's `/health` until 200 (or timeout)
+ *   4. wraps the connected `SandboxClient` in an `AdapterSandbox`
+ *
+ * `destroySandbox(id)` runs `docker rm -f`. `listSandboxes()` enumerates
+ * containers labeled `sandbank-aio=true` to avoid touching unrelated containers
+ * on the host.
+ */
+export declare class AIOSandboxAdapter implements SandboxAdapter {
+    readonly name = "aio";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly docker;
+    private readonly image;
+    private readonly portRange;
+    private readonly healthTimeoutSec;
+    private readonly apiKey?;
+    constructor(cfg?: AIOSandboxAdapterConfig);
+    createSandbox(config: CreateConfig): Promise<AdapterSandbox>;
+    getSandbox(id: string): Promise<AdapterSandbox>;
+    listSandboxes(filter?: ListFilter): Promise<SandboxInfo[]>;
+    destroySandbox(id: string): Promise<void>;
+    private makeClient;
+    private allocPort;
+    private portFree;
+    private waitHealth;
+    private extractHostPort;
+    private wrap;
+}
+//# sourceMappingURL=AIOSandboxAdapter.d.ts.map

package/dist/AIOSandboxAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIOSandboxAdapter.d.ts","sourceRoot":"","sources":["../src/AIOSandboxAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,YAAY,EAGZ,UAAU,EACV,cAAc,EACd,WAAW,EAEZ,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAoB,KAAK,uBAAuB,EAAE,MAAM,YAAY,CAAC;AA2B5E;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,YAAW,cAAc;IACtD,QAAQ,CAAC,IAAI,SAAS;IACtB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAoB;IAElE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,GAAG,GAAE,uBAA4B;IAcvC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAiC5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuB/C,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAsB1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa/C,OAAO,CAAC,UAAU;YASJ,SAAS;YAUT,QAAQ;YAYR,UAAU;IAmBxB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,IAAI;CASb"}

package/dist/AIOSandboxAdapter.js

@@ -0,0 +1,253 @@
+import Docker from 'dockerode';
+import { SandboxClient } from '@agent-infra/sandbox';
+import { SandboxNotFoundError, ProviderError } from '@douglas-agent/sandbank-core';
+import { AIO_CAPABILITIES } from './types.js';
+const DEFAULT_IMAGE = 'ghcr.io/agent-infra/sandbox:latest';
+const DEFAULT_PORT_RANGE = [49152, 65535];
+const DEFAULT_HEALTH_TIMEOUT_SEC = 60;
+const SANDBOX_INTERNAL_PORT = 8080;
+/** Docker container state → sandbank SandboxState */
+function mapDockerState(s) {
+    switch (s) {
+        case 'created':
+            return 'creating';
+        case 'running':
+            return 'running';
+        case 'paused':
+        case 'restarting':
+            return 'stopped';
+        case 'exited':
+        case 'dead':
+            return 'terminated';
+        case 'removing':
+            return 'stopped';
+        default:
+            return 'error';
+    }
+}
+/**
+ * AIOSandboxAdapter — wraps `ghcr.io/agent-infra/sandbox` Docker container
+ * lifecycle with dockerode, exposes business operations through
+ * `@agent-infra/sandbox` `SandboxClient`.
+ *
+ * Each `createSandbox()` call:
+ *   1. allocates a free host port from the configured range
+ *   2. `docker run` the AIO Sandbox image with port `8080` → host port mapping
+ *   3. polls container's `/health` until 200 (or timeout)
+ *   4. wraps the connected `SandboxClient` in an `AdapterSandbox`
+ *
+ * `destroySandbox(id)` runs `docker rm -f`. `listSandboxes()` enumerates
+ * containers labeled `sandbank-aio=true` to avoid touching unrelated containers
+ * on the host.
+ */
+export class AIOSandboxAdapter {
+    name = 'aio';
+    capabilities = AIO_CAPABILITIES;
+    docker;
+    image;
+    portRange;
+    healthTimeoutSec;
+    apiKey;
+    constructor(cfg = {}) {
+        this.docker = new Docker(cfg.dockerSocketPath
+            ? { socketPath: cfg.dockerSocketPath }
+            : cfg.dockerHost
+                ? { host: cfg.dockerHost }
+                : undefined);
+        this.image = cfg.image ?? DEFAULT_IMAGE;
+        this.portRange = cfg.portRange ?? DEFAULT_PORT_RANGE;
+        this.healthTimeoutSec = cfg.healthTimeoutSec ?? DEFAULT_HEALTH_TIMEOUT_SEC;
+        this.apiKey = cfg.apiKey;
+    }
+    async createSandbox(config) {
+        const port = await this.allocPort();
+        const envArr = Object.entries(config.env ?? {}).map(([k, v]) => `${k}=${v}`);
+        let container;
+        try {
+            container = await this.docker.createContainer({
+                Image: config.image ?? this.image,
+                Env: envArr,
+                Labels: { 'sandbank-aio': 'true' },
+                HostConfig: {
+                    PortBindings: {
+                        [`${SANDBOX_INTERNAL_PORT}/tcp`]: [{ HostPort: String(port) }],
+                    },
+                    SecurityOpt: ['seccomp=unconfined'],
+                    AutoRemove: true,
+                },
+            });
+            await container.start();
+        }
+        catch (e) {
+            throw new ProviderError('aio', e);
+        }
+        const baseUrl = `http://localhost:${port}`;
+        await this.waitHealth(baseUrl);
+        const client = this.makeClient(baseUrl);
+        const createdAt = new Date().toISOString();
+        return this.wrap(container.id, baseUrl, client, 'running', createdAt);
+    }
+    async getSandbox(id) {
+        const container = this.docker.getContainer(id);
+        let info;
+        try {
+            info = await container.inspect();
+        }
+        catch (e) {
+            if (e.statusCode === 404) {
+                throw new SandboxNotFoundError('aio', id);
+            }
+            throw new ProviderError('aio', e, id);
+        }
+        const port = this.extractHostPort(info);
+        const baseUrl = port ? `http://localhost:${port}` : '';
+        const client = baseUrl ? this.makeClient(baseUrl) : undefined;
+        return this.wrap(info.Id, baseUrl, client, mapDockerState(info.State.Status), info.Created);
+    }
+    async listSandboxes(filter) {
+        const containers = await this.docker.listContainers({
+            all: true,
+            filters: { label: ['sandbank-aio=true'] },
+        });
+        const states = filter?.state
+            ? Array.isArray(filter.state)
+                ? filter.state
+                : [filter.state]
+            : null;
+        const limit = filter?.limit ?? Infinity;
+        return containers
+            .map((c) => ({
+            id: c.Id,
+            state: mapDockerState(c.State),
+            createdAt: new Date(c.Created * 1000).toISOString(),
+            image: c.Image,
+        }))
+            .filter((info) => (states ? states.includes(info.state) : true))
+            .slice(0, limit);
+    }
+    async destroySandbox(id) {
+        try {
+            await this.docker.getContainer(id).remove({ force: true });
+        }
+        catch (e) {
+            if (e.statusCode === 404) {
+                return; // idempotent
+            }
+            throw new ProviderError('aio', e, id);
+        }
+    }
+    // ── internals ────────────────────────────────────────
+    makeClient(baseUrl) {
+        const headers = {};
+        if (this.apiKey)
+            headers['X-API-Key'] = this.apiKey;
+        return new SandboxClient({
+            environment: () => baseUrl,
+            headers: Object.keys(headers).length ? headers : undefined,
+        });
+    }
+    async allocPort() {
+        // Naive linear probe within range. dockerode's `PortBindings` returns
+        // EADDRINUSE if the port is taken, so we retry. Good enough for POC.
+        const [lo, hi] = this.portRange;
+        for (let p = lo; p <= hi; p++) {
+            if (await this.portFree(p))
+                return p;
+        }
+        throw new ProviderError('aio', new Error(`portRange [${lo},${hi}] exhausted`));
+    }
+    async portFree(port) {
+        // Best-effort host-side check. dockerode does the authoritative bind.
+        return new Promise((resolve) => {
+            const net = globalThis.require?.('net');
+            if (!net)
+                return resolve(true); // skip in test environments
+            const srv = net.createServer();
+            srv.once('error', () => resolve(false));
+            srv.once('listening', () => srv.close(() => resolve(true)));
+            srv.listen(port, '127.0.0.1');
+        });
+    }
+    async waitHealth(baseUrl) {
+        const deadline = Date.now() + this.healthTimeoutSec * 1000;
+        let lastErr;
+        while (Date.now() < deadline) {
+            try {
+                const res = await fetch(`${baseUrl}/health`, { method: 'GET' });
+                if (res.ok)
+                    return;
+                lastErr = new Error(`HTTP ${res.status}`);
+            }
+            catch (e) {
+                lastErr = e;
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+        throw new ProviderError('aio', new Error(`/health did not become ready within ${this.healthTimeoutSec}s: ${lastErr?.message ?? 'unknown'}`));
+    }
+    extractHostPort(info) {
+        const bindings = info.NetworkSettings?.Ports?.[`${SANDBOX_INTERNAL_PORT}/tcp`];
+        const first = bindings?.[0];
+        if (!first?.HostPort)
+            return null;
+        const port = parseInt(first.HostPort, 10);
+        return Number.isFinite(port) ? port : null;
+    }
+    wrap(id, baseUrl, client, state, createdAt) {
+        return new AIOAdapterSandbox(id, baseUrl, client, state, createdAt, this.docker);
+    }
+}
+/** AdapterSandbox impl: delegates exec/file ops to SandboxClient (HTTP). */
+class AIOAdapterSandbox {
+    id;
+    baseUrl;
+    client;
+    state;
+    createdAt;
+    docker;
+    constructor(id, baseUrl, client, state, createdAt, docker) {
+        this.id = id;
+        this.baseUrl = baseUrl;
+        this.client = client;
+        this.state = state;
+        this.createdAt = createdAt;
+        this.docker = docker;
+    }
+    async exec(command, options) {
+        if (!this.client) {
+            throw new ProviderError('aio', new Error('no API baseUrl (likely stopped)'), this.id);
+        }
+        // Delegate to SandboxClient.bash.exec.
+        // NOTE: the exact SDK shape varies by @agent-infra/sandbox version —
+        // implementation-phase task confirms current API & wires up timeout/cwd.
+        try {
+            const result = (await this.client.bash?.exec?.({
+                command,
+                cwd: options?.cwd,
+                timeout_ms: options?.timeout,
+            }));
+            return {
+                stdout: result?.stdout ?? '',
+                stderr: result?.stderr ?? '',
+                exitCode: result?.exit_code ?? 0,
+            };
+        }
+        catch (e) {
+            throw new ProviderError('aio', e, this.id);
+        }
+    }
+    async writeFile(path, content) {
+        if (!this.client) {
+            throw new ProviderError('aio', new Error('no API baseUrl'), this.id);
+        }
+        const body = typeof content === 'string' ? content : Buffer.from(content).toString('utf8');
+        await this.client.file?.write?.({ path, content: body });
+    }
+    async readFile(path) {
+        if (!this.client) {
+            throw new ProviderError('aio', new Error('no API baseUrl'), this.id);
+        }
+        const result = (await this.client.file?.read?.({ path }));
+        return new TextEncoder().encode(result?.content ?? '');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { AIOSandboxAdapter } from './AIOSandboxAdapter.js';
+export type { AIOSandboxAdapterConfig } from './types.js';
+export { AIO_CAPABILITIES } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { AIOSandboxAdapter } from './AIOSandboxAdapter.js';
+export { AIO_CAPABILITIES } from './types.js';

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+import type { Capability } from '@douglas-agent/sandbank-core';
+/**
+ * Configuration for AIOSandboxAdapter.
+ *
+ * The adapter uses dockerode to manage container lifecycle (create / destroy)
+ * and `@agent-infra/sandbox` `SandboxClient` to talk to the sandbox HTTP API
+ * once the container is healthy.
+ */
+export interface AIOSandboxAdapterConfig {
+    /**
+     * AIO Sandbox container image. Defaults to upstream release.
+     * @default 'ghcr.io/agent-infra/sandbox:latest'
+     */
+    image?: string;
+    /**
+     * Docker daemon socket path. When undefined, dockerode falls back to its
+     * default (Unix socket on Linux/macOS, named pipe on Windows).
+     * @example '/var/run/docker.sock'
+     */
+    dockerSocketPath?: string;
+    /**
+     * Docker daemon TCP endpoint (alternative to socket path).
+     * @example 'tcp://localhost:2375'
+     */
+    dockerHost?: string;
+    /**
+     * Host port range to allocate for sandbox HTTP API binding.
+     * Each `createSandbox` reserves one port from this range.
+     * @default [49152, 65535]   // standard ephemeral range
+     */
+    portRange?: [number, number];
+    /**
+     * Max seconds to wait for sandbox /health to respond 200 after `docker start`.
+     * @default 60
+     */
+    healthTimeoutSec?: number;
+    /**
+     * Optional API key forwarded to SandboxClient via `X-API-Key` header.
+     * Most self-hosted AIO Sandbox deployments leave this unset.
+     */
+    apiKey?: string;
+}
+/** Capabilities declared by AIOSandboxAdapter. */
+export declare const AIO_CAPABILITIES: ReadonlySet<Capability>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,UAAU,CAInD,CAAC"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/** Capabilities declared by AIOSandboxAdapter. */
+export const AIO_CAPABILITIES = new Set([
+    'exec.stream',
+    'terminal',
+    'port.expose',
+]);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@douglas-agent/sandbank-aio",
+  "version": "0.1.0",
+  "description": "AIO Sandbox adapter (字节 agent-infra/sandbox) for Sandbank — dockerode lifecycle + @agent-infra/sandbox SDK for in-container ops",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/Xeonice/sandbank-douglas-agent",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeonice/sandbank-douglas-agent.git",
+    "directory": "packages/aio"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "aio-sandbox",
+    "agent-infra",
+    "bytedance"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@douglas-agent/sandbank-core": "^0.3.6",
+    "@agent-infra/sandbox": "^1.0.16",
+    "dockerode": "^4.0.10"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.40",
+    "typescript": "^5.7.3"
+  }
+}