@sandbank.dev/core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,189 @@
+export interface SandboxProvider {
+    /** Provider 标识，如 'daytona', 'flyio', 'cloudflare' */
+    readonly name: string;
+    /** 该 provider 支持的能力集 */
+    readonly capabilities: ReadonlySet<Capability>;
+    /** 创建一个新的沙箱 */
+    create(config: CreateConfig): Promise<Sandbox>;
+    /** 获取已存在的沙箱（不存在则抛 SandboxNotFoundError） */
+    get(id: string): Promise<Sandbox>;
+    /** 列出当前所有沙箱 */
+    list(filter?: ListFilter): Promise<SandboxInfo[]>;
+    /** 销毁沙箱（幂等：已销毁的不报错） */
+    destroy(id: string): Promise<void>;
+}
+export interface SkillDefinition {
+    /** Skill 名称，用作文件名（不含 .md 后缀） */
+    name: string;
+    /** Skill 内容（markdown 文本） */
+    content: string;
+}
+export interface CreateConfig {
+    /** 容器镜像（如 'node:22-slim', 'ubuntu:24.04'） */
+    image: string;
+    /** 环境变量注入 */
+    env?: Record<string, string>;
+    /** 资源配置（provider 会映射到最接近的规格） */
+    resources?: {
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+    };
+    /** 区域偏好（provider 可忽略） */
+    region?: string;
+    /** 自动销毁时间（分钟）。0 或不设 = 不自动销毁 */
+    autoDestroyMinutes?: number;
+    /** 挂载的持久卷（需 provider 支持 'volumes' 能力） */
+    volumes?: Array<{
+        id: string;
+        mountPath: string;
+    }>;
+    /** 创建超时（秒）。默认由 provider 决定（Daytona 默认 60s） */
+    timeout?: number;
+    /**
+     * 注入到沙箱的 skill 文件列表。
+     * 每个 skill 会被写入沙箱的 `~/.claude/skills/` 目录。
+     */
+    skills?: SkillDefinition[];
+}
+export interface ListFilter {
+    state?: SandboxState | SandboxState[];
+    limit?: number;
+}
+export interface Sandbox {
+    /** 沙箱唯一 ID */
+    readonly id: string;
+    /** 当前状态 */
+    readonly state: SandboxState;
+    /** 创建时间 */
+    readonly createdAt: string;
+    /** 执行命令，等待完成 */
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    /** 写入单个文件 */
+    writeFile(path: string, content: string | Uint8Array): Promise<void>;
+    /** 读取单个文件 */
+    readFile(path: string): Promise<Uint8Array>;
+    /** 上传 tar.gz 归档并解压到指定目录 */
+    uploadArchive(archive: Uint8Array | ReadableStream, destDir?: string): Promise<void>;
+    /** 将指定目录打包为 tar.gz 下载 */
+    downloadArchive(srcDir?: string): Promise<ReadableStream>;
+}
+export type SandboxState = 'creating' | 'running' | 'stopped' | 'error' | 'terminated';
+export interface ExecOptions {
+    /** 超时时间（毫秒），默认 120_000 */
+    timeout?: number;
+    /** 工作目录 */
+    cwd?: string;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface SandboxInfo {
+    id: string;
+    state: SandboxState;
+    createdAt: string;
+    image: string;
+    region?: string;
+}
+export type Capability = 'exec.stream' | 'terminal' | 'sleep' | 'volumes' | 'snapshot' | 'port.expose';
+export interface StreamableSandbox extends Sandbox {
+    execStream(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array>>;
+}
+export interface TerminalSandbox extends Sandbox {
+    startTerminal(options?: TerminalOptions): Promise<TerminalInfo>;
+}
+export interface TerminalOptions {
+    shell?: string;
+    hostname?: string;
+}
+export interface TerminalInfo {
+    url: string;
+    port: number;
+}
+export interface Disposable {
+    dispose(): void;
+}
+export interface TerminalSession {
+    /** 向 PTY 发送输入 */
+    write(data: string): void;
+    /** 监听 PTY 输出 */
+    onData(cb: (data: string) => void): Disposable;
+    /** 调整终端尺寸 */
+    resize(cols: number, rows: number): void;
+    /** 关闭连接 */
+    close(): void;
+    /** 连接状态 */
+    readonly state: 'connecting' | 'open' | 'closed';
+    /** 连接打开时 resolve */
+    readonly ready: Promise<void>;
+}
+export interface SleepableSandbox extends Sandbox {
+    sleep(): Promise<void>;
+    wake(): Promise<void>;
+}
+export interface PortExposeSandbox extends Sandbox {
+    exposePort(port: number, options?: {
+        hostname?: string;
+    }): Promise<{
+        url: string;
+    }>;
+}
+export interface SnapshotSandbox extends Sandbox {
+    createSnapshot(name?: string): Promise<{
+        snapshotId: string;
+    }>;
+    restoreSnapshot(snapshotId: string): Promise<void>;
+}
+export interface VolumeProvider extends SandboxProvider {
+    createVolume(config: VolumeConfig): Promise<VolumeInfo>;
+    deleteVolume(id: string): Promise<void>;
+    listVolumes(): Promise<VolumeInfo[]>;
+}
+export interface VolumeConfig {
+    name: string;
+    region?: string;
+    sizeGB?: number;
+}
+export interface VolumeInfo {
+    id: string;
+    name: string;
+    sizeGB: number;
+    attachedTo: string | null;
+}
+export interface SandboxAdapter {
+    readonly name: string;
+    readonly capabilities: ReadonlySet<Capability>;
+    createSandbox(config: CreateConfig): Promise<AdapterSandbox>;
+    getSandbox(id: string): Promise<AdapterSandbox>;
+    listSandboxes(filter?: ListFilter): Promise<SandboxInfo[]>;
+    destroySandbox(id: string): Promise<void>;
+    createVolume?(config: VolumeConfig): Promise<VolumeInfo>;
+    deleteVolume?(id: string): Promise<void>;
+    listVolumes?(): Promise<VolumeInfo[]>;
+}
+export interface AdapterSandbox {
+    id: string;
+    state: SandboxState;
+    createdAt: string;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    writeFile?(path: string, content: string | Uint8Array): Promise<void>;
+    readFile?(path: string): Promise<Uint8Array>;
+    uploadArchive?(archive: Uint8Array | ReadableStream, destDir?: string): Promise<void>;
+    downloadArchive?(srcDir?: string): Promise<ReadableStream>;
+    execStream?(command: string, options?: ExecOptions): Promise<ReadableStream<Uint8Array>>;
+    sleep?(): Promise<void>;
+    wake?(): Promise<void>;
+    startTerminal?(options?: TerminalOptions): Promise<TerminalInfo>;
+    exposePort?(port: number, options?: {
+        hostname?: string;
+    }): Promise<{
+        url: string;
+    }>;
+    createSnapshot?(name?: string): Promise<{
+        snapshotId: string;
+    }>;
+    restoreSnapshot?(snapshotId: string): Promise<void>;
+}
+//# 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":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+// --- Provider（工厂） ---
+export {};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sandbank.dev/core",
+  "version": "0.1.0",
+  "description": "Unified sandbox SDK for AI agents — provider abstraction, capability system, and error types",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sandbank.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chekusu/sandbank.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "cloud",
+    "provider",
+    "sdk"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@sandbank.dev/relay": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@sandbank.dev/relay": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.7.3",
+    "ws": "^8.18.0",
+    "@types/ws": "^8.18.0",
+    "@sandbank.dev/relay": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}