@sandbank.dev/core 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# @sandbank.dev/core
+
+> Unified sandbox SDK for AI agents — provider abstraction, capability system, and error types.
+
+## Install
+
+```bash
+pnpm add @sandbank.dev/core
+```
+
+## Usage
+
+```typescript
+import { createProvider, withTerminal, connectTerminal } from '@sandbank.dev/core'
+import { DaytonaAdapter } from '@sandbank.dev/daytona'
+
+const provider = createProvider(
+  new DaytonaAdapter({ apiKey: process.env.DAYTONA_API_KEY! })
+)
+
+// Create and use a sandbox
+const sandbox = await provider.create({ image: 'node:22' })
+const { stdout } = await sandbox.exec('node --version')
+await sandbox.writeFile('/app/index.js', 'console.log("hi")')
+
+// Capability detection
+const terminal = withTerminal(sandbox)
+if (terminal) {
+  const info = await terminal.startTerminal()
+  const session = connectTerminal(info)
+  await session.ready
+  session.onData((data) => process.stdout.write(data))
+  session.write('ls\n')
+}
+
+await provider.destroy(sandbox.id)
+```
+
+## Capabilities
+
+Use `hasCapability(provider, name)` to check provider support, and `withTerminal(sandbox)` / `withStreaming(sandbox)` / etc. for type-safe downcasting.
+
+| Capability | Description |
+|------------|-------------|
+| `exec.stream` | Real-time stdout/stderr streaming |
+| `terminal` | Interactive web terminal (ttyd) |
+| `sleep` | Hibernate and wake sandboxes |
+| `volumes` | Persistent volume management |
+| `snapshot` | Snapshot and restore sandbox state |
+| `port.expose` | Expose sandbox ports to the internet |
+
+## Multi-Agent Sessions
+
+```typescript
+import { createSession } from '@sandbank.dev/core'
+
+const session = await createSession({ provider, relay: { type: 'memory' } })
+const agent = await session.spawn('worker', { image: 'node:22' })
+await session.waitForAll()
+await session.close()
+```
+
+## License
+
+MIT

package/dist/capabilities.d.ts

@@ -0,0 +1,16 @@
+import type { Capability, PortExposeSandbox, Sandbox, SandboxProvider, SleepableSandbox, SnapshotSandbox, StreamableSandbox, TerminalSandbox, VolumeProvider } from './types.js';
+/** 检查 provider 是否支持某个能力 */
+export declare function hasCapability(provider: SandboxProvider, capability: Capability): boolean;
+/** 向下转型为支持流式执行的 Sandbox，不支持则返回 null */
+export declare function withStreaming(sandbox: Sandbox): StreamableSandbox | null;
+/** 向下转型为支持终端的 Sandbox，不支持则返回 null */
+export declare function withTerminal(sandbox: Sandbox): TerminalSandbox | null;
+/** 向下转型为支持休眠的 Sandbox，不支持则返回 null */
+export declare function withSleep(sandbox: Sandbox): SleepableSandbox | null;
+/** 向下转型为支持端口暴露的 Sandbox，不支持则返回 null */
+export declare function withPortExpose(sandbox: Sandbox): PortExposeSandbox | null;
+/** 向下转型为支持快照的 Sandbox，不支持则返回 null */
+export declare function withSnapshot(sandbox: Sandbox): SnapshotSandbox | null;
+/** 向下转型为支持卷管理的 Provider，不支持则返回 null */
+export declare function withVolumes(provider: SandboxProvider): VolumeProvider | null;
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAA;AAEnB,2BAA2B;AAC3B,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,eAAe,EACzB,UAAU,EAAE,UAAU,GACrB,OAAO,CAET;AAED,uCAAuC;AACvC,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAKxE;AAED,qCAAqC;AACrC,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAKrE;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAKnE;AAED,uCAAuC;AACvC,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAKzE;AAED,qCAAqC;AACrC,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,eAAe,GAAG,IAAI,CAKrE;AAED,uCAAuC;AACvC,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,GAAG,IAAI,CAK5E"}

package/dist/capabilities.js

@@ -0,0 +1,46 @@
+/** 检查 provider 是否支持某个能力 */
+export function hasCapability(provider, capability) {
+    return provider.capabilities.has(capability);
+}
+/** 向下转型为支持流式执行的 Sandbox，不支持则返回 null */
+export function withStreaming(sandbox) {
+    if ('execStream' in sandbox && typeof sandbox.execStream === 'function') {
+        return sandbox;
+    }
+    return null;
+}
+/** 向下转型为支持终端的 Sandbox，不支持则返回 null */
+export function withTerminal(sandbox) {
+    if ('startTerminal' in sandbox && typeof sandbox.startTerminal === 'function') {
+        return sandbox;
+    }
+    return null;
+}
+/** 向下转型为支持休眠的 Sandbox，不支持则返回 null */
+export function withSleep(sandbox) {
+    if ('sleep' in sandbox && typeof sandbox.sleep === 'function') {
+        return sandbox;
+    }
+    return null;
+}
+/** 向下转型为支持端口暴露的 Sandbox，不支持则返回 null */
+export function withPortExpose(sandbox) {
+    if ('exposePort' in sandbox && typeof sandbox.exposePort === 'function') {
+        return sandbox;
+    }
+    return null;
+}
+/** 向下转型为支持快照的 Sandbox，不支持则返回 null */
+export function withSnapshot(sandbox) {
+    if ('createSnapshot' in sandbox && typeof sandbox.createSnapshot === 'function') {
+        return sandbox;
+    }
+    return null;
+}
+/** 向下转型为支持卷管理的 Provider，不支持则返回 null */
+export function withVolumes(provider) {
+    if ('createVolume' in provider && typeof provider.createVolume === 'function') {
+        return provider;
+    }
+    return null;
+}

package/dist/errors.d.ts

@@ -0,0 +1,38 @@
+import type { Capability, SandboxState } from './types.js';
+/** 所有 SDK 错误的基类 */
+export declare class SandboxError extends Error {
+    readonly provider: string;
+    readonly sandboxId?: string;
+    constructor(message: string, provider: string, sandboxId?: string);
+}
+/** 沙箱不存在（已销毁或从未创建） */
+export declare class SandboxNotFoundError extends SandboxError {
+    constructor(provider: string, sandboxId: string);
+}
+/** 沙箱状态不对（如在 stopped 状态下 exec） */
+export declare class SandboxStateError extends SandboxError {
+    readonly currentState: SandboxState;
+    readonly requiredState: SandboxState;
+    constructor(provider: string, sandboxId: string, currentState: SandboxState, requiredState: SandboxState);
+}
+/** 命令执行超时 */
+export declare class ExecTimeoutError extends SandboxError {
+    readonly timeout: number;
+    constructor(provider: string, sandboxId: string, timeout: number);
+}
+/** Provider 返回速率限制 */
+export declare class RateLimitError extends SandboxError {
+    readonly retryAfter?: number;
+    constructor(provider: string, retryAfter?: number);
+}
+/** Provider 自身错误（500、网络问题等） */
+export declare class ProviderError extends SandboxError {
+    readonly cause: unknown;
+    constructor(provider: string, cause: unknown, sandboxId?: string);
+}
+/** 不支持的能力 */
+export declare class CapabilityNotSupportedError extends SandboxError {
+    readonly capability: Capability;
+    constructor(provider: string, capability: Capability);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE1D,mBAAmB;AACnB,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;gBAEf,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM;CAMlE;AAED,sBAAsB;AACtB,qBAAa,oBAAqB,SAAQ,YAAY;gBACxC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAIhD;AAED,kCAAkC;AAClC,qBAAa,iBAAkB,SAAQ,YAAY;IACjD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAA;gBAExB,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY;CAUzG;AAED,aAAa;AACb,qBAAa,gBAAiB,SAAQ,YAAY;IAChD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;gBAEZ,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAKjE;AAED,sBAAsB;AACtB,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;gBAEhB,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAUlD;AAED,+BAA+B;AAC/B,qBAAa,aAAc,SAAQ,YAAY;IAC7C,SAAkB,KAAK,EAAE,OAAO,CAAA;gBAEpB,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM;CAMjE;AAED,aAAa;AACb,qBAAa,2BAA4B,SAAQ,YAAY;IAC3D,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;gBAEnB,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CAKrD"}

package/dist/errors.js

@@ -0,0 +1,68 @@
+/** 所有 SDK 错误的基类 */
+export class SandboxError extends Error {
+    provider;
+    sandboxId;
+    constructor(message, provider, sandboxId) {
+        super(message);
+        this.name = 'SandboxError';
+        this.provider = provider;
+        this.sandboxId = sandboxId;
+    }
+}
+/** 沙箱不存在（已销毁或从未创建） */
+export class SandboxNotFoundError extends SandboxError {
+    constructor(provider, sandboxId) {
+        super(`Sandbox '${sandboxId}' not found`, provider, sandboxId);
+        this.name = 'SandboxNotFoundError';
+    }
+}
+/** 沙箱状态不对（如在 stopped 状态下 exec） */
+export class SandboxStateError extends SandboxError {
+    currentState;
+    requiredState;
+    constructor(provider, sandboxId, currentState, requiredState) {
+        super(`Sandbox '${sandboxId}' is '${currentState}', expected '${requiredState}'`, provider, sandboxId);
+        this.name = 'SandboxStateError';
+        this.currentState = currentState;
+        this.requiredState = requiredState;
+    }
+}
+/** 命令执行超时 */
+export class ExecTimeoutError extends SandboxError {
+    timeout;
+    constructor(provider, sandboxId, timeout) {
+        super(`Command timed out after ${timeout}ms`, provider, sandboxId);
+        this.name = 'ExecTimeoutError';
+        this.timeout = timeout;
+    }
+}
+/** Provider 返回速率限制 */
+export class RateLimitError extends SandboxError {
+    retryAfter;
+    constructor(provider, retryAfter) {
+        super(retryAfter
+            ? `Rate limited, retry after ${retryAfter}s`
+            : 'Rate limited', provider);
+        this.name = 'RateLimitError';
+        this.retryAfter = retryAfter;
+    }
+}
+/** Provider 自身错误（500、网络问题等） */
+export class ProviderError extends SandboxError {
+    cause;
+    constructor(provider, cause, sandboxId) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(`Provider error: ${message}`, provider, sandboxId);
+        this.name = 'ProviderError';
+        this.cause = cause;
+    }
+}
+/** 不支持的能力 */
+export class CapabilityNotSupportedError extends SandboxError {
+    capability;
+    constructor(provider, capability) {
+        super(`Capability '${capability}' is not supported by '${provider}'`, provider);
+        this.name = 'CapabilityNotSupportedError';
+        this.capability = capability;
+    }
+}

package/dist/file-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { AdapterSandbox } from './types.js';
+/**
+ * 基于 exec 的 writeFile 默认实现。
+ * 将内容 base64 编码后通过 printf | base64 -d 写入文件。
+ */
+export declare function writeFileViaExec(sandbox: AdapterSandbox, path: string, content: string | Uint8Array): Promise<void>;
+/**
+ * 基于 exec 的 readFile 默认实现。
+ * 通过 base64 编码读取文件内容。
+ */
+export declare function readFileViaExec(sandbox: AdapterSandbox, path: string): Promise<Uint8Array>;
+/**
+ * 基于 exec 的 uploadArchive 默认实现。
+ * 将 tar.gz 数据 base64 编码后传输并解压。
+ */
+export declare function uploadArchiveViaExec(sandbox: AdapterSandbox, archive: Uint8Array | ReadableStream, destDir?: string): Promise<void>;
+/**
+ * 基于 exec 的 downloadArchive 默认实现。
+ * 将指定目录打包为 tar.gz 并通过 base64 传输。
+ */
+export declare function downloadArchiveViaExec(sandbox: AdapterSandbox, srcDir?: string): Promise<ReadableStream>;
+//# sourceMappingURL=file-helpers.d.ts.map

package/dist/file-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-helpers.d.ts","sourceRoot":"","sources":["../src/file-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAMhD;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,UAAU,GAC3B,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,UAAU,CAAC,CAarB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,UAAU,GAAG,cAAc,EACpC,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgDf;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,EACvB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,CAsCzB"}

package/dist/file-helpers.js

@@ -0,0 +1,134 @@
+function shellEscape(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+/**
+ * 基于 exec 的 writeFile 默认实现。
+ * 将内容 base64 编码后通过 printf | base64 -d 写入文件。
+ */
+export async function writeFileViaExec(sandbox, path, content) {
+    const bytes = typeof content === 'string'
+        ? new TextEncoder().encode(content)
+        : content;
+    let binary = '';
+    const chunkSize = 8192;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    const base64 = btoa(binary);
+    // 确保目标目录存在
+    const dir = path.substring(0, path.lastIndexOf('/'));
+    if (dir) {
+        await sandbox.exec(`mkdir -p ${shellEscape(dir)}`);
+    }
+    const result = await sandbox.exec(`printf '%s' ${shellEscape(base64)} | base64 -d > ${shellEscape(path)}`);
+    if (result.exitCode !== 0) {
+        throw new Error(`writeFile failed: ${result.stderr}`);
+    }
+}
+/**
+ * 基于 exec 的 readFile 默认实现。
+ * 通过 base64 编码读取文件内容。
+ */
+export async function readFileViaExec(sandbox, path) {
+    const result = await sandbox.exec(`base64 ${shellEscape(path)}`);
+    if (result.exitCode !== 0) {
+        throw new Error(`readFile failed: ${result.stderr}`);
+    }
+    const clean = result.stdout.replace(/\s/g, '');
+    const binary = atob(clean);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/**
+ * 基于 exec 的 uploadArchive 默认实现。
+ * 将 tar.gz 数据 base64 编码后传输并解压。
+ */
+export async function uploadArchiveViaExec(sandbox, archive, destDir) {
+    // ReadableStream → Uint8Array
+    let bytes;
+    if (archive instanceof Uint8Array) {
+        bytes = archive;
+    }
+    else {
+        const reader = archive.getReader();
+        const chunks = [];
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            chunks.push(value);
+        }
+        const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+        bytes = new Uint8Array(totalLength);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bytes.set(chunk, offset);
+            offset += chunk.length;
+        }
+    }
+    // base64 编码
+    let binary = '';
+    const chunkSize = 8192;
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    const base64 = btoa(binary);
+    const target = destDir ?? '/';
+    const tmp = `/tmp/_sb_archive_${Date.now()}_${Math.random().toString(36).slice(2)}.tar.gz`;
+    // 写入临时文件
+    const writeResult = await sandbox.exec(`printf '%s' ${shellEscape(base64)} | base64 -d > ${tmp}`);
+    if (writeResult.exitCode !== 0) {
+        throw new Error(`uploadArchive: write failed: ${writeResult.stderr}`);
+    }
+    // 解压
+    const extractResult = await sandbox.exec(`tar xzf ${tmp} -C ${shellEscape(target)}`);
+    if (extractResult.exitCode !== 0) {
+        await sandbox.exec(`rm -f ${tmp}`);
+        throw new Error(`uploadArchive: extract failed: ${extractResult.stderr}`);
+    }
+    // 清理
+    await sandbox.exec(`rm -f ${tmp}`);
+}
+/**
+ * 基于 exec 的 downloadArchive 默认实现。
+ * 将指定目录打包为 tar.gz 并通过 base64 传输。
+ */
+export async function downloadArchiveViaExec(sandbox, srcDir) {
+    const source = srcDir ?? '/';
+    const tmp = `/tmp/_sb_archive_${Date.now()}_${Math.random().toString(36).slice(2)}.tar.gz`;
+    // 打包
+    const tarResult = await sandbox.exec(`tar czf ${tmp} -C ${shellEscape(source)} .`);
+    if (tarResult.exitCode !== 0) {
+        await sandbox.exec(`rm -f ${tmp}`).catch(() => { });
+        throw new Error(`downloadArchive: tar failed: ${tarResult.stderr}`);
+    }
+    let readResult;
+    try {
+        // 读取 base64
+        readResult = await sandbox.exec(`base64 ${tmp}`);
+        if (readResult.exitCode !== 0) {
+            throw new Error(`downloadArchive: read failed: ${readResult.stderr}`);
+        }
+    }
+    finally {
+        // 清理临时文件（无论成功或失败）
+        await sandbox.exec(`rm -f ${tmp}`).catch(() => { });
+    }
+    // 解码为 Uint8Array
+    const clean = readResult.stdout.replace(/\s/g, '');
+    const binaryStr = atob(clean);
+    const bytes = new Uint8Array(binaryStr.length);
+    for (let i = 0; i < binaryStr.length; i++) {
+        bytes[i] = binaryStr.charCodeAt(i);
+    }
+    // 包装为 ReadableStream
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export type { SandboxProvider, Sandbox, CreateConfig, ExecOptions, ExecResult, SandboxState, SandboxInfo, ListFilter, Capability, StreamableSandbox, TerminalSandbox, TerminalOptions, TerminalInfo, TerminalSession, Disposable, SleepableSandbox, PortExposeSandbox, SnapshotSandbox, VolumeProvider, VolumeConfig, VolumeInfo, SandboxAdapter, AdapterSandbox, SkillDefinition, } from './types.js';
+export { createProvider } from './provider.js';
+export { hasCapability, withStreaming, withTerminal, withSleep, withPortExpose, withSnapshot, withVolumes, } from './capabilities.js';
+export { SandboxError, SandboxNotFoundError, SandboxStateError, ExecTimeoutError, RateLimitError, ProviderError, CapabilityNotSupportedError, } from './errors.js';
+export { connectTerminal } from './terminal.js';
+export { injectSkills } from './skill-inject.js';
+export { writeFileViaExec, readFileViaExec, uploadArchiveViaExec, downloadArchiveViaExec } from './file-helpers.js';
+export type { MessagePriority, SessionMessage, ContextStore, CompletionStatus, SandboxCompletion, SendOptions, Session, RelayConfig, CreateSessionConfig, JsonRpcRequest, JsonRpcResponse, JsonRpcNotification, JsonRpcError, Transport, } from './session-types.js';
+export { createSession } from './session.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":"AACA,YAAY,EAEV,eAAe,EACf,OAAO,EACP,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EAEV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,YAAY,EACZ,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,UAAU,EAEV,cAAc,EACd,cAAc,EAEd,eAAe,GAChB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAG9C,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,SAAS,EACT,cAAc,EACd,YAAY,EACZ,WAAW,GACZ,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,aAAa,EACb,2BAA2B,GAC5B,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAG/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAGnH,YAAY,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,OAAO,EACP,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,SAAS,GACV,MAAM,oBAAoB,CAAA;AAG3B,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,14 @@
+// Provider factory
+export { createProvider } from './provider.js';
+// Capability detection
+export { hasCapability, withStreaming, withTerminal, withSleep, withPortExpose, withSnapshot, withVolumes, } from './capabilities.js';
+// Errors
+export { SandboxError, SandboxNotFoundError, SandboxStateError, ExecTimeoutError, RateLimitError, ProviderError, CapabilityNotSupportedError, } from './errors.js';
+// Terminal session
+export { connectTerminal } from './terminal.js';
+// Skill injection
+export { injectSkills } from './skill-inject.js';
+// File helpers (for adapter authors)
+export { writeFileViaExec, readFileViaExec, uploadArchiveViaExec, downloadArchiveViaExec } from './file-helpers.js';
+// Session factory
+export { createSession } from './session.js';

package/dist/provider.d.ts

@@ -0,0 +1,4 @@
+import type { SandboxAdapter, SandboxProvider } from './types.js';
+/** 创建一个 SandboxProvider */
+export declare function createProvider(adapter: SandboxAdapter): SandboxProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAQV,cAAc,EAEd,eAAe,EAMhB,MAAM,YAAY,CAAA;AA0GnB,2BAA2B;AAC3B,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,GAAG,eAAe,CAmDvE"}

package/dist/provider.js

@@ -0,0 +1,134 @@
+import { CapabilityNotSupportedError, ProviderError } from './errors.js';
+import { injectSkills } from './skill-inject.js';
+import { readFileViaExec, writeFileViaExec, uploadArchiveViaExec, downloadArchiveViaExec } from './file-helpers.js';
+/**
+ * 将 AdapterSandbox 包装为完整的 Sandbox 接口。
+ * 自动补充缺失的 writeFile/readFile 默认实现。
+ */
+function wrapSandbox(raw, providerName) {
+    const sandbox = {
+        get id() { return raw.id; },
+        get state() { return raw.state; },
+        get createdAt() { return raw.createdAt; },
+        exec(command, options) {
+            return raw.exec(command, options);
+        },
+        writeFile(path, content) {
+            if (raw.writeFile)
+                return raw.writeFile(path, content);
+            return writeFileViaExec(raw, path, content);
+        },
+        readFile(path) {
+            if (raw.readFile)
+                return raw.readFile(path);
+            return readFileViaExec(raw, path);
+        },
+        uploadArchive(archive, destDir) {
+            if (raw.uploadArchive)
+                return raw.uploadArchive(archive, destDir);
+            return uploadArchiveViaExec(raw, archive, destDir);
+        },
+        downloadArchive(srcDir) {
+            if (raw.downloadArchive)
+                return raw.downloadArchive(srcDir);
+            return downloadArchiveViaExec(raw, srcDir);
+        },
+    };
+    // 转发可选能力方法（只有 adapter 真正实现的才转发）
+    if (raw.execStream) {
+        sandbox['execStream'] = raw.execStream.bind(raw);
+    }
+    if (raw.sleep) {
+        sandbox['sleep'] = raw.sleep.bind(raw);
+    }
+    if (raw.wake) {
+        sandbox['wake'] = raw.wake.bind(raw);
+    }
+    if (raw.startTerminal) {
+        sandbox['startTerminal'] = (options) => raw.startTerminal(options);
+    }
+    if (raw.exposePort) {
+        sandbox['exposePort'] = (port, options) => raw.exposePort(port, options);
+    }
+    if (raw.createSnapshot) {
+        sandbox['createSnapshot'] = (name) => raw.createSnapshot(name);
+    }
+    if (raw.restoreSnapshot) {
+        sandbox['restoreSnapshot'] = (snapshotId) => raw.restoreSnapshot(snapshotId);
+    }
+    return sandbox;
+}
+/** 能力到 AdapterSandbox 方法的映射 */
+const CAPABILITY_METHOD_MAP = {
+    'exec.stream': 'execStream',
+    'terminal': 'startTerminal',
+    'sleep': 'sleep',
+    'volumes': '', // checked at adapter level, not sandbox level
+    'snapshot': 'createSnapshot',
+    'port.expose': 'exposePort',
+};
+/**
+ * 交叉验证 adapter 声明的能力。
+ *
+ * 对于 sandbox 级别的能力（exec.stream, terminal, sleep, snapshot, port.expose），
+ * 我们无法在不创建沙箱的情况下验证方法是否存在，所以信任 adapter 的声明。
+ *
+ * 对于 provider 级别的能力（volumes），直接检查 adapter 上的方法。
+ */
+function detectCapabilities(adapter) {
+    const validated = new Set();
+    for (const cap of adapter.capabilities) {
+        if (cap === 'volumes') {
+            // volumes 是 provider 级别能力，可以直接验证
+            if (adapter.createVolume && adapter.deleteVolume && adapter.listVolumes) {
+                validated.add(cap);
+            }
+        }
+        else {
+            // sandbox 级别能力，信任 adapter 声明
+            validated.add(cap);
+        }
+    }
+    return validated;
+}
+/** 创建一个 SandboxProvider */
+export function createProvider(adapter) {
+    const capabilities = detectCapabilities(adapter);
+    const provider = {
+        get name() { return adapter.name; },
+        get capabilities() { return capabilities; },
+        async create(config) {
+            const raw = await adapter.createSandbox(config);
+            const sandbox = wrapSandbox(raw, adapter.name);
+            if (config.skills?.length) {
+                try {
+                    await injectSkills(sandbox, config.skills);
+                }
+                catch (err) {
+                    await adapter.destroySandbox(raw.id).catch(() => { });
+                    throw err;
+                }
+            }
+            return sandbox;
+        },
+        async get(id) {
+            const raw = await adapter.getSandbox(id);
+            return wrapSandbox(raw, adapter.name);
+        },
+        async list(filter) {
+            return adapter.listSandboxes(filter);
+        },
+        async destroy(id) {
+            return adapter.destroySandbox(id);
+        },
+    };
+    // 如果 adapter 支持 volume 操作，扩展为 VolumeProvider
+    if (capabilities.has('volumes') && adapter.createVolume && adapter.deleteVolume && adapter.listVolumes) {
+        const volumeProvider = provider;
+        volumeProvider.createVolume = (config) => adapter.createVolume(config);
+        volumeProvider.deleteVolume = (id) => adapter.deleteVolume(id);
+        volumeProvider.listVolumes = () => adapter.listVolumes();
+        return volumeProvider;
+    }
+    return provider;
+}