@sandbank.dev/core 0.1.0

package/dist/session-types.d.ts

@@ -0,0 +1,101 @@
+import type { SandboxProvider, Sandbox, CreateConfig } from './types.js';
+export type MessagePriority = 'normal' | 'steer';
+export interface SessionMessage {
+    from: string;
+    to: string | null;
+    type: string;
+    payload: unknown;
+    priority: MessagePriority;
+    timestamp: string;
+}
+export interface ContextStore {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set<T = unknown>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+    keys(): Promise<string[]>;
+    watch(key: string, fn: (value: unknown) => void): () => void;
+    watchAll(fn: (key: string, value: unknown) => void): () => void;
+}
+export type CompletionStatus = 'success' | 'failure' | 'cancelled';
+export interface SandboxCompletion {
+    sandboxName: string;
+    status: CompletionStatus;
+    summary: string;
+    timestamp: string;
+}
+export interface Session {
+    /** Session 唯一标识 */
+    readonly id: string;
+    /** 注册并创建沙箱 */
+    spawn(name: string, config: CreateConfig): Promise<Sandbox>;
+    /** 获取已注册的沙箱 */
+    getSandbox(name: string): Sandbox | undefined;
+    /** 列出已注册的沙箱名 */
+    listSandboxes(): string[];
+    /** 发送消息给指定沙箱 */
+    send(to: string, type: string, payload?: unknown, options?: SendOptions): void;
+    /** 广播消息给所有沙箱 */
+    broadcast(type: string, payload?: unknown, options?: SendOptions): void;
+    /** 共享上下文存储 */
+    readonly context: ContextStore;
+    /** 监听收到的消息 */
+    onMessage(fn: (msg: SessionMessage) => void): () => void;
+    /** 监听沙箱状态变化 */
+    onSandboxState(fn: (info: {
+        name: string;
+        status: CompletionStatus;
+        summary: string;
+    }) => void): () => void;
+    /** 等待指定沙箱完成 */
+    waitFor(name: string, timeoutMs?: number): Promise<SandboxCompletion>;
+    /** 等待所有沙箱完成 */
+    waitForAll(timeoutMs?: number): Promise<SandboxCompletion[]>;
+    /** 关闭 session（销毁所有沙箱、关闭 relay） */
+    close(): Promise<void>;
+}
+export interface SendOptions {
+    priority?: MessagePriority;
+}
+export type RelayConfig = {
+    type: 'memory';
+} | {
+    type: 'hosted';
+    url: string;
+    token?: string;
+};
+export interface CreateSessionConfig {
+    provider: SandboxProvider;
+    relay?: RelayConfig;
+    timeoutMinutes?: number;
+    maxSandboxes?: number;
+    onError?: (error: Error) => void;
+}
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcResponse {
+    jsonrpc: '2.0';
+    id: number | string | null;
+    result?: unknown;
+    error?: JsonRpcError;
+}
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+export interface Transport {
+    send(data: string): void;
+    onMessage(fn: (data: string) => void): void;
+    close(): void;
+    readonly readyState: 'connecting' | 'open' | 'closed';
+}
+//# sourceMappingURL=session-types.d.ts.map

package/dist/session-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-types.d.ts","sourceRoot":"","sources":["../src/session-types.ts"],"names":[],"mappings":"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"}

package/dist/session-types.js

@@ -0,0 +1 @@
+export {};

package/dist/session.d.ts

@@ -0,0 +1,3 @@
+import type { Session, CreateSessionConfig } from './session-types.js';
+export declare function createSession(config: CreateSessionConfig): Promise<Session>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,OAAO,EACP,mBAAmB,EASpB,MAAM,oBAAoB,CAAA;AAI3B,wBAAsB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,CAAC,CA6VjF"}

package/dist/session.js

@@ -0,0 +1,320 @@
+import { randomUUID } from 'node:crypto';
+export async function createSession(config) {
+    let rpcId = 1;
+    function createRpcRequest(method, params) {
+        return { jsonrpc: '2.0', id: rpcId++, method, ...(params ? { params } : {}) };
+    }
+    const sessionId = `session-${randomUUID()}`;
+    const relayConfig = config.relay ?? { type: 'memory' };
+    const onError = config.onError ?? (() => { });
+    // 启动 relay（memory 模式：动态 import @sandbank.dev/relay）
+    let relayUrl;
+    let wsUrl;
+    let closeRelay;
+    if (relayConfig.type === 'memory') {
+        // Dynamic import: @sandbank.dev/relay is an optional peer dep (no static dependency)
+        const specifier = '@sandbank.dev/relay';
+        const relayMod = await import(specifier);
+        const relay = await relayMod.startRelay({ port: 0 });
+        relayUrl = relay.url;
+        wsUrl = relay.wsUrl;
+        closeRelay = () => relay.close();
+    }
+    else {
+        relayUrl = relayConfig.url;
+        wsUrl = relayConfig.url.replace(/^https?/, (p) => p === 'https' ? 'wss' : 'ws');
+        closeRelay = async () => { };
+    }
+    // 编排者 WebSocket 连接
+    const ws = new WebSocket(wsUrl);
+    await new Promise((resolve, reject) => {
+        ws.addEventListener('open', () => resolve());
+        ws.addEventListener('error', () => reject(new Error('Failed to connect to relay')));
+    });
+    const pending = new Map();
+    const messageListeners = [];
+    const stateListeners = [];
+    const completions = new Map();
+    const completionWaiters = new Map();
+    // 路由 WebSocket 消息
+    ws.addEventListener('message', (evt) => {
+        const data = typeof evt.data === 'string' ? evt.data : String(evt.data);
+        try {
+            const msg = JSON.parse(data);
+            // RPC 响应
+            if ('id' in msg && msg.id != null) {
+                const entry = pending.get(msg.id);
+                if (entry) {
+                    pending.delete(msg.id);
+                    if (msg.error) {
+                        entry.reject(new Error(`RPC error: ${msg.error.message}`));
+                    }
+                    else {
+                        entry.resolve(msg.result);
+                    }
+                }
+                return;
+            }
+            // 通知
+            if ('method' in msg) {
+                if (msg.method === 'message' && msg.params) {
+                    const sessionMsg = msg.params;
+                    for (const fn of messageListeners)
+                        fn(sessionMsg);
+                }
+                else if (msg.method === 'sandbox.state' && msg.params) {
+                    const { name, status, summary } = msg.params;
+                    const completion = {
+                        sandboxName: name,
+                        status,
+                        summary,
+                        timestamp: new Date().toISOString(),
+                    };
+                    completions.set(name, completion);
+                    for (const fn of stateListeners)
+                        fn({ name, status, summary });
+                    // 唤醒 waitFor
+                    const waiters = completionWaiters.get(name);
+                    if (waiters) {
+                        for (const w of waiters) {
+                            if (w.timer)
+                                clearTimeout(w.timer);
+                            w.resolve(completion);
+                        }
+                        completionWaiters.delete(name);
+                    }
+                }
+                else if (msg.method === 'context.changed') {
+                    // context 变更 → 通知 context watchers
+                    const { key, value } = msg.params;
+                    for (const fn of contextKeyWatchers.get(key) ?? [])
+                        fn(value);
+                    for (const fn of contextAllWatchers)
+                        fn(key, value);
+                }
+            }
+        }
+        catch {
+            // ignore parse errors
+        }
+    });
+    // Handle unexpected disconnects: reject all pending calls and waiters
+    ws.addEventListener('close', () => {
+        const err = new Error('Relay connection closed');
+        for (const [, entry] of pending)
+            entry.reject(err);
+        pending.clear();
+        for (const [, waiters] of completionWaiters) {
+            for (const w of waiters) {
+                if (w.timer)
+                    clearTimeout(w.timer);
+                w.reject(err);
+            }
+        }
+        completionWaiters.clear();
+    });
+    const RPC_TIMEOUT_MS = 30_000;
+    async function rpcCall(method, params) {
+        const req = createRpcRequest(method, params);
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(req.id);
+                reject(new Error(`RPC timeout: ${method} (${RPC_TIMEOUT_MS}ms)`));
+            }, RPC_TIMEOUT_MS);
+            pending.set(req.id, {
+                resolve: (result) => { clearTimeout(timer); resolve(result); },
+                reject: (err) => { clearTimeout(timer); reject(err); },
+            });
+            try {
+                ws.send(JSON.stringify(req));
+            }
+            catch (sendErr) {
+                clearTimeout(timer);
+                pending.delete(req.id);
+                reject(sendErr instanceof Error ? sendErr : new Error(String(sendErr)));
+            }
+        });
+    }
+    // 生成 session token
+    const token = (relayConfig.type === 'hosted' && relayConfig.token)
+        ? relayConfig.token
+        : crypto.randomUUID();
+    // 认证
+    const authResult = await rpcCall('session.auth', {
+        sessionId,
+        token,
+        role: 'orchestrator',
+    });
+    const sessionToken = authResult.token ?? token;
+    const sandboxes = new Map();
+    const contextKeyWatchers = new Map();
+    const contextAllWatchers = new Set();
+    // Context 代理
+    const context = {
+        async get(key) {
+            const result = await rpcCall('context.get', { key });
+            return result.value ?? undefined;
+        },
+        async set(key, value) {
+            await rpcCall('context.set', { key, value });
+        },
+        async delete(key) {
+            await rpcCall('context.delete', { key });
+        },
+        async keys() {
+            const result = await rpcCall('context.keys');
+            return result.keys;
+        },
+        watch(key, fn) {
+            if (!contextKeyWatchers.has(key))
+                contextKeyWatchers.set(key, new Set());
+            contextKeyWatchers.get(key).add(fn);
+            return () => { contextKeyWatchers.get(key)?.delete(fn); };
+        },
+        watchAll(fn) {
+            contextAllWatchers.add(fn);
+            return () => { contextAllWatchers.delete(fn); };
+        },
+    };
+    const session = {
+        id: sessionId,
+        async spawn(name, sandboxConfig) {
+            if (sandboxes.has(name)) {
+                throw new Error(`Sandbox name already in use: "${name}"`);
+            }
+            const maxSandboxes = config.maxSandboxes ?? 10;
+            if (sandboxes.size >= maxSandboxes) {
+                throw new Error(`Max sandboxes (${maxSandboxes}) reached`);
+            }
+            // Reserve the name to prevent concurrent spawn with same name or exceeding max
+            sandboxes.set(name, null);
+            try {
+                // 注入 relay 环境变量
+                const env = {
+                    ...sandboxConfig.env,
+                    SANDBANK_RELAY_URL: relayUrl,
+                    SANDBANK_WS_URL: wsUrl,
+                    SANDBANK_SESSION_ID: sessionId,
+                    SANDBANK_SANDBOX_NAME: name,
+                    SANDBANK_AUTH_TOKEN: sessionToken,
+                };
+                const sandbox = await config.provider.create({ ...sandboxConfig, env });
+                // 在 relay 注册沙箱
+                try {
+                    await rpcCall('session.register', { name, sandboxId: sandbox.id });
+                }
+                catch (err) {
+                    await config.provider.destroy(sandbox.id).catch(() => { });
+                    throw err;
+                }
+                sandboxes.set(name, sandbox);
+                return sandbox;
+            }
+            catch (err) {
+                sandboxes.delete(name);
+                throw err;
+            }
+        },
+        getSandbox(name) {
+            const sb = sandboxes.get(name);
+            return sb ?? undefined; // filter out null placeholders from in-flight spawns
+        },
+        listSandboxes() {
+            return [...sandboxes.entries()]
+                .filter(([, sb]) => sb != null)
+                .map(([name]) => name);
+        },
+        // Fire-and-forget: errors are passed to the onError callback (default: silent).
+        // Use onError in CreateSessionConfig to handle delivery failures.
+        send(to, type, payload, options) {
+            rpcCall('message.send', {
+                to,
+                type,
+                payload: payload ?? null,
+                priority: options?.priority ?? 'normal',
+            }).catch(onError);
+        },
+        broadcast(type, payload, options) {
+            rpcCall('message.broadcast', {
+                type,
+                payload: payload ?? null,
+                priority: options?.priority ?? 'normal',
+            }).catch(onError);
+        },
+        context,
+        onMessage(fn) {
+            messageListeners.push(fn);
+            return () => {
+                const idx = messageListeners.indexOf(fn);
+                if (idx >= 0)
+                    messageListeners.splice(idx, 1);
+            };
+        },
+        onSandboxState(fn) {
+            stateListeners.push(fn);
+            return () => {
+                const idx = stateListeners.indexOf(fn);
+                if (idx >= 0)
+                    stateListeners.splice(idx, 1);
+            };
+        },
+        waitFor(name, timeoutMs) {
+            // 已经完成
+            const existing = completions.get(name);
+            if (existing)
+                return Promise.resolve(existing);
+            return new Promise((resolve, reject) => {
+                const waiter = { resolve, reject };
+                if (timeoutMs) {
+                    waiter.timer = setTimeout(() => {
+                        const waiters = completionWaiters.get(name);
+                        if (waiters) {
+                            const idx = waiters.indexOf(waiter);
+                            if (idx >= 0)
+                                waiters.splice(idx, 1);
+                        }
+                        reject(new Error(`Timeout waiting for sandbox "${name}" (${timeoutMs}ms)`));
+                    }, timeoutMs);
+                }
+                if (!completionWaiters.has(name))
+                    completionWaiters.set(name, []);
+                completionWaiters.get(name).push(waiter);
+            });
+        },
+        async waitForAll(timeoutMs) {
+            // Note: uses a snapshot of sandbox names at call time.
+            // Sandboxes spawned after this call will not be waited for.
+            const names = [...sandboxes.keys()];
+            const promises = names.map((name) => session.waitFor(name, timeoutMs));
+            return Promise.all(promises);
+        },
+        async close() {
+            // 先清理 pending，避免 unhandled rejection
+            for (const [, entry] of pending) {
+                entry.reject(new Error('Session closed'));
+            }
+            pending.clear();
+            // 清理 waitFor：reject 所有挂起的 waiter
+            for (const [, waiters] of completionWaiters) {
+                for (const w of waiters) {
+                    if (w.timer)
+                        clearTimeout(w.timer);
+                    w.reject(new Error('Session closed'));
+                }
+            }
+            completionWaiters.clear();
+            // 并行销毁所有沙箱（在断开 WebSocket 前，确保 relay 仍可达）
+            // Filter out null placeholders from in-progress spawns
+            await Promise.allSettled([...sandboxes.values()].filter(Boolean).map(sandbox => config.provider.destroy(sandbox.id)));
+            sandboxes.clear();
+            // 断开 WebSocket 并等待关闭完成
+            await new Promise((resolve) => {
+                ws.addEventListener('close', () => resolve(), { once: true });
+                ws.close();
+            });
+            // 关闭 relay
+            await closeRelay();
+        },
+    };
+    return session;
+}

package/dist/skill-inject.d.ts

@@ -0,0 +1,3 @@
+import type { Sandbox, SkillDefinition } from './types.js';
+export declare function injectSkills(sandbox: Sandbox, skills: SkillDefinition[], skillDir?: string): Promise<void>;
+//# sourceMappingURL=skill-inject.d.ts.map

package/dist/skill-inject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-inject.d.ts","sourceRoot":"","sources":["../src/skill-inject.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAc1D,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,eAAe,EAAE,EACzB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/skill-inject.js

@@ -0,0 +1,23 @@
+const DEFAULT_SKILL_DIR = '/root/.claude/skills';
+function shellEscape(s) {
+    return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function validateSkillName(name) {
+    if (name === '' || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+        throw new Error(`Invalid skill name: "${name}" — must not contain path separators or be empty`);
+    }
+}
+export async function injectSkills(sandbox, skills, skillDir) {
+    if (skills.length === 0)
+        return;
+    const dir = skillDir ?? DEFAULT_SKILL_DIR;
+    for (const skill of skills) {
+        validateSkillName(skill.name);
+    }
+    // Ensure target directory exists
+    await sandbox.exec(`mkdir -p ${shellEscape(dir)}`);
+    for (const skill of skills) {
+        const path = `${dir}/${skill.name}.md`;
+        await sandbox.writeFile(path, skill.content);
+    }
+}

package/dist/terminal.d.ts

@@ -0,0 +1,8 @@
+import type { TerminalInfo, TerminalSession } from './types.js';
+/**
+ * 连接 ttyd WebSocket 端点，返回 TerminalSession。
+ *
+ * 使用全局 WebSocket（Node.js 22+ 和浏览器均原生支持）。
+ */
+export declare function connectTerminal(info: TerminalInfo): TerminalSession;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../src/terminal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqB3E;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,eAAe,CA4EnE"}

package/dist/terminal.js

@@ -0,0 +1,92 @@
+/**
+ * ttyd binary protocol constants.
+ *
+ * Client → Server:
+ *   0x00 + UTF-8 text  = user input
+ *   0x01 + JSON string = resize {"columns":N,"rows":N}
+ *
+ * Server → Client:
+ *   0x00 + UTF-8 text  = terminal output
+ *   0x01              = auth required (ignored)
+ *   0x02 + text       = window title  (ignored)
+ */
+const MSG_INPUT = 0;
+const MSG_RESIZE = 1;
+const MSG_OUTPUT = 0;
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+/**
+ * 连接 ttyd WebSocket 端点，返回 TerminalSession。
+ *
+ * 使用全局 WebSocket（Node.js 22+ 和浏览器均原生支持）。
+ */
+export function connectTerminal(info) {
+    const listeners = new Set();
+    let state = 'connecting';
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    const ws = new WebSocket(info.url);
+    ws.binaryType = 'arraybuffer';
+    ws.addEventListener('open', () => {
+        state = 'open';
+        resolveReady();
+    });
+    ws.addEventListener('message', (event) => {
+        const buf = new Uint8Array(event.data);
+        if (buf.length === 0)
+            return;
+        const type = buf[0];
+        if (type === MSG_OUTPUT) {
+            const text = decoder.decode(buf.subarray(1));
+            for (const fn of listeners)
+                fn(text);
+        }
+        // type 1 (auth) and type 2 (title) are ignored
+    });
+    ws.addEventListener('close', () => {
+        state = 'closed';
+    });
+    ws.addEventListener('error', (event) => {
+        if (state === 'connecting') {
+            rejectReady(new Error(`WebSocket connection failed: ${info.url}`));
+        }
+        state = 'closed';
+    });
+    return {
+        write(data) {
+            if (state !== 'open')
+                return;
+            const payload = encoder.encode(data);
+            const frame = new Uint8Array(1 + payload.length);
+            frame[0] = MSG_INPUT;
+            frame.set(payload, 1);
+            ws.send(frame);
+        },
+        onData(cb) {
+            listeners.add(cb);
+            return { dispose: () => { listeners.delete(cb); } };
+        },
+        resize(cols, rows) {
+            if (state !== 'open')
+                return;
+            const json = JSON.stringify({ columns: cols, rows });
+            const payload = encoder.encode(json);
+            const frame = new Uint8Array(1 + payload.length);
+            frame[0] = MSG_RESIZE;
+            frame.set(payload, 1);
+            ws.send(frame);
+        },
+        close() {
+            if (state === 'closed')
+                return;
+            state = 'closed';
+            ws.close();
+        },
+        get state() { return state; },
+        get ready() { return ready; },
+    };
+}