@douglas-agent/sandbank-core 0.3.6

package/README.md

@@ -0,0 +1,71 @@
+# @douglas-agent/sandbank-core
+
+> Unified sandbox SDK for AI agents — provider abstraction, capability system, and error types.
+
+## Install
+
+```bash
+pnpm add @douglas-agent/sandbank-core
+```
+
+## Usage
+
+```typescript
+import { createProvider, withTerminal, connectTerminal } from '@douglas-agent/sandbank-core'
+import { DaytonaAdapter } from '@douglas-agent/sandbank-daytona'
+
+const provider = createProvider(
+  new DaytonaAdapter({ apiKey: process.env.DAYTONA_API_KEY! })
+)
+
+// Create a sandbox with a non-root user
+const sandbox = await provider.create({
+  image: 'node:22',
+  user: 'sandbank',            // creates non-root user with sudo
+})
+const { stdout } = await sandbox.exec('node --version')
+await sandbox.writeFile('/app/index.js', 'console.log("hi")')
+
+// Run privileged commands with asRoot
+await sandbox.exec('apt-get update', { asRoot: true })
+
+// 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 '@douglas-agent/sandbank-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,18 @@
+import type { Capability, PortExposeSandbox, Sandbox, SandboxProvider, ServiceProvider, 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;
+/** 向下转型为支持服务管理的 Provider，不支持则返回 null */
+export declare function withServices(provider: SandboxProvider): ServiceProvider | 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,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,CAS5E;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,GAAG,eAAe,GAAG,IAAI,CAU9E"}

package/dist/capabilities.js

@@ -0,0 +1,58 @@
+/** 检查 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' &&
+        'deleteVolume' in provider && typeof provider.deleteVolume === 'function' &&
+        'listVolumes' in provider && typeof provider.listVolumes === 'function') {
+        return provider;
+    }
+    return null;
+}
+/** 向下转型为支持服务管理的 Provider，不支持则返回 null */
+export function withServices(provider) {
+    if ('createService' in provider && typeof provider.createService === 'function' &&
+        'getService' in provider && typeof provider.getService === 'function' &&
+        'listServices' in provider && typeof provider.listServices === 'function' &&
+        'destroyService' in provider && typeof provider.destroyService === '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,CAmDf;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,136 @@
+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}`);
+    }
+    // 确保目标目录存在
+    await sandbox.exec(`mkdir -p ${shellEscape(target)}`);
+    // 解压
+    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/hooks.d.ts

@@ -0,0 +1,78 @@
+import type { Sandbox } from './types.js';
+export type ClaudeHookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'Stop';
+export interface InjectHooksConfig {
+    /**
+     * Event destination.
+     * - http: 使用 Claude Code 内置 HTTP hook 类型（sandbox 需能访问该 URL）
+     * - file: 使用 command hook 将事件追加到 JSONL 文件
+     */
+    endpoint: {
+        type: 'http';
+        url: string;
+        headers?: Record<string, string>;
+    } | {
+        type: 'file';
+        path?: string;
+    };
+    /** 要捕获的事件。默认: ['PostToolUse', 'Stop'] */
+    events?: ClaudeHookEvent[];
+    /** 是否异步执行 hook（不阻塞 agent）。默认: true */
+    async?: boolean;
+    /**
+     * settings.json 写入路径。默认: 自动检测 $HOME/.claude/settings.json
+     * 传入目录时会追加 /.claude/settings.json
+     */
+    settingsDir?: string;
+}
+export interface HookEventData {
+    /** Unix timestamp (ms) */
+    ts: number;
+    /** 原始 hook 输入数据 */
+    data: Record<string, unknown>;
+}
+export interface ClaudeLoginConfig {
+    /** 每次按 Enter 的间隔秒数。默认: 2 */
+    enterInterval?: number;
+    /** 最大按 Enter 次数。默认: 30 */
+    maxRetries?: number;
+    /** 安装依赖的命令。默认: apt-get update -qq && apt-get install -y -qq screen */
+    installCommand?: string;
+}
+export interface ClaudeLoginResult {
+    /** OAuth 授权 URL，用户需要在浏览器中打开 */
+    url: string;
+    /**
+     * 将 OAuth 回调返回的 auth code 发送到沙箱内的 claude login 进程。
+     * 使用 screen -X source 注入字符到 PTY，避免 shell 转义问题。
+     */
+    sendCode: (code: string) => Promise<void>;
+    /**
+     * 等待登录完成。用户在浏览器中完成授权后，此函数 resolve。
+     * 超时则 reject。
+     */
+    waitForCredentials: (timeoutMs?: number) => Promise<void>;
+}
+export declare const DEFAULT_EVENTS_FILE = "/tmp/sandbank-hook-events.jsonl";
+/**
+ * 将 Claude Code hooks 配置注入沙箱。
+ * hooks 会在 agent 的每次工具调用后自动触发，将事件发送到指定端点。
+ */
+export declare function injectClaudeHooks(sandbox: Sandbox, config: InjectHooksConfig): Promise<void>;
+/**
+ * 从沙箱内的 JSONL 文件读取 hook 事件。
+ * 用于 file 模式下拉取事件。
+ */
+export declare function readHookEvents(sandbox: Sandbox, path?: string): Promise<HookEventData[]>;
+/**
+ * 在沙箱内自动化 `claude login`，捕获 OAuth 授权 URL。
+ *
+ * 使用 GNU screen 管理 PTY:
+ * - screen 提供真实 PTY，满足 claude login 的 TUI 需求
+ * - screen -X stuff 注入按键（导航 TUI）
+ * - screen -X hardcopy 截取屏幕纯文本（无 ANSI 转义码）
+ * - screen -X source 执行 stuff 命令文件（精确控制注入内容）
+ *
+ * 返回 URL 和 sendCode/waitForCredentials 回调。
+ */
+export declare function startClaudeLogin(sandbox: Sandbox, config?: ClaudeLoginConfig): Promise<ClaudeLoginResult>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAIzC,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,aAAa,GAAG,oBAAoB,GAAG,MAAM,CAAA;AAE1F,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,EACJ;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAC/D;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAEnC,yCAAyC;IACzC,MAAM,CAAC,EAAE,eAAe,EAAE,CAAA;IAE1B,sCAAsC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAA;IAEf;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,0BAA0B;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACzC;;;OAGG;IACH,kBAAkB,EAAE,CAAC,SAAS,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAID,eAAO,MAAM,mBAAmB,oCAAoC,CAAA;AAOpE;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,iBAAiB,GACxB,OAAO,CAAC,IAAI,CAAC,CAoCf;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,EAAE,CAAC,CAU1B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,MAAM,CAAC,EAAE,iBAAiB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAwH5B"}