@douglas-agent/sandbank-agent 0.2.0

package/README.md

@@ -0,0 +1,62 @@
+# @douglas-agent/sandbank-agent
+
+> Lightweight client for AI agents running inside [Sandbank](../../README.md) sandboxes.
+
+Connects to the relay server via WebSocket, enabling messaging, shared context, and task completion signaling.
+
+## Install
+
+```bash
+pnpm add @douglas-agent/sandbank-agent
+```
+
+## Usage
+
+Runs inside a sandbox. Connection parameters are read from `SANDBANK_*` environment variables injected by `createSession()`:
+
+```typescript
+import { connect } from '@douglas-agent/sandbank-agent'
+
+const session = await connect()
+
+// Listen for messages
+session.on('message', async (msg) => {
+  if (msg.type === 'task') {
+    const result = await doWork(msg.payload)
+    await session.send(msg.from, 'done', result)
+  }
+})
+
+// Shared context
+const spec = await session.context.get('spec')
+await session.context.set('output', { files: ['index.ts'] })
+
+// Signal completion
+await session.complete({ status: 'success', summary: 'Built 5 endpoints' })
+session.close()
+```
+
+## CLI
+
+Also available as a CLI tool for shell scripts inside sandboxes:
+
+```bash
+sandbank-agent send <to> <type> [payload]
+sandbank-agent recv [--wait 5000]
+sandbank-agent context get <key>
+sandbank-agent context set <key> <value>
+sandbank-agent complete <status> <summary>
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SANDBANK_WS_URL` | Relay WebSocket URL |
+| `SANDBANK_SESSION_ID` | Session identifier |
+| `SANDBANK_SANDBOX_NAME` | This agent's sandbox name |
+| `SANDBANK_AUTH_TOKEN` | Authentication token |
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+import { sendMessage, recvMessages, contextGet, contextSet, contextDelete, contextKeys, complete, } from './http-client.js';
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    if (!command) {
+        printUsage();
+        process.exit(1);
+    }
+    switch (command) {
+        case 'send':
+            await handleSend(args.slice(1));
+            break;
+        case 'recv':
+            await handleRecv(args.slice(1));
+            break;
+        case 'context':
+            await handleContext(args.slice(1));
+            break;
+        case 'complete':
+            await handleComplete(args.slice(1));
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+            printUsage();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            printUsage();
+            process.exit(1);
+    }
+}
+async function handleSend(args) {
+    // sandbank-agent send <to> <type> [payload] [--steer]
+    const steerIdx = args.indexOf('--steer');
+    const priority = steerIdx >= 0 ? 'steer' : 'normal';
+    const cleanArgs = args.filter((a) => a !== '--steer');
+    const to = cleanArgs[0];
+    const type = cleanArgs[1];
+    const payloadStr = cleanArgs[2];
+    if (!to || !type) {
+        console.error('Usage: sandbank-agent send <to> <type> [payload] [--steer]');
+        process.exit(1);
+    }
+    let payload = payloadStr ?? null;
+    if (typeof payloadStr === 'string') {
+        try {
+            payload = JSON.parse(payloadStr);
+        }
+        catch {
+            // keep as string
+        }
+    }
+    await sendMessage(to, type, payload, priority);
+    console.log('OK');
+}
+async function handleRecv(args) {
+    // sandbank-agent recv [--wait <seconds>] [--limit <n>]
+    let wait = 0;
+    let limit = 100;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--wait' && args[i + 1]) {
+            wait = parseInt(args[i + 1], 10) * 1000; // seconds → ms
+            i++;
+        }
+        else if (args[i] === '--limit' && args[i + 1]) {
+            limit = parseInt(args[i + 1], 10);
+            i++;
+        }
+    }
+    const messages = await recvMessages(limit, wait);
+    console.log(JSON.stringify(messages, null, 2));
+}
+async function handleContext(args) {
+    const sub = args[0];
+    switch (sub) {
+        case 'get': {
+            const key = args[1];
+            if (!key) {
+                console.error('Usage: sandbank-agent context get <key>');
+                process.exit(1);
+            }
+            const value = await contextGet(key);
+            console.log(JSON.stringify(value, null, 2));
+            break;
+        }
+        case 'set': {
+            const key = args[1];
+            const valueStr = args[2];
+            if (!key || valueStr === undefined) {
+                console.error('Usage: sandbank-agent context set <key> <value>');
+                process.exit(1);
+            }
+            let value = valueStr;
+            try {
+                value = JSON.parse(valueStr);
+            }
+            catch {
+                // keep as string
+            }
+            await contextSet(key, value);
+            console.log('OK');
+            break;
+        }
+        case 'delete': {
+            const key = args[1];
+            if (!key) {
+                console.error('Usage: sandbank-agent context delete <key>');
+                process.exit(1);
+            }
+            await contextDelete(key);
+            console.log('OK');
+            break;
+        }
+        case 'keys': {
+            const keys = await contextKeys();
+            console.log(JSON.stringify(keys, null, 2));
+            break;
+        }
+        default:
+            console.error('Usage: sandbank-agent context <get|set|delete|keys> [args]');
+            process.exit(1);
+    }
+}
+async function handleComplete(args) {
+    // sandbank-agent complete --status <status> --summary <text>
+    let status = 'success';
+    let summary = '';
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--status' && args[i + 1]) {
+            status = args[i + 1];
+            i++;
+        }
+        else if (args[i] === '--summary' && args[i + 1]) {
+            summary = args[i + 1];
+            i++;
+        }
+    }
+    await complete(status, summary);
+    console.log('OK');
+}
+function printUsage() {
+    console.log(`sandbank-agent — Sandbank Agent CLI
+
+Commands:
+  send <to> <type> [payload] [--steer]   Send a message
+  recv [--wait <sec>] [--limit <n>]      Receive messages
+  context get <key>                      Get context value
+  context set <key> <value>              Set context value
+  context delete <key>                   Delete context key
+  context keys                           List all context keys
+  complete --status <s> --summary <text> Mark sandbox as complete
+
+Environment variables:
+  SANDBANK_RELAY_URL     Relay HTTP URL
+  SANDBANK_SESSION_ID    Session ID
+  SANDBANK_SANDBOX_NAME  This sandbox's name
+  SANDBANK_AUTH_TOKEN    Auth token (required)`);
+}
+main().catch((err) => {
+    console.error(err.message);
+    process.exit(1);
+});

package/dist/connect.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSession, ConnectOptions } from './types.js';
+export declare function connect(options?: ConnectOptions): Promise<AgentSession>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../src/connect.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAgB,cAAc,EAAE,MAAM,YAAY,CAAA;AAK5E,wBAAsB,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2HjF"}

package/dist/connect.js

@@ -0,0 +1,120 @@
+import { createWebSocketTransport } from './transport.js';
+import { createRequest, RpcPendingMap } from './rpc.js';
+import { createWsContextClient } from './context-client.js';
+export async function connect(options = {}) {
+    const wsUrl = options.wsUrl ?? process.env['SANDBANK_WS_URL'];
+    const sessionId = options.sessionId ?? process.env['SANDBANK_SESSION_ID'];
+    const sandboxName = options.sandboxName ?? process.env['SANDBANK_SANDBOX_NAME'];
+    const token = options.token ?? process.env['SANDBANK_AUTH_TOKEN'];
+    if (!wsUrl)
+        throw new Error('Missing wsUrl (set SANDBANK_WS_URL)');
+    if (!sessionId)
+        throw new Error('Missing sessionId (set SANDBANK_SESSION_ID)');
+    if (!sandboxName)
+        throw new Error('Missing sandboxName (set SANDBANK_SANDBOX_NAME)');
+    const transport = await createWebSocketTransport(wsUrl);
+    const pending = new RpcPendingMap();
+    const messageListeners = [];
+    // 路由所有 WebSocket 消息
+    transport.onMessage((data) => {
+        try {
+            const msg = JSON.parse(data);
+            // RPC 响应
+            if ('id' in msg && msg.id != null) {
+                pending.resolve(msg);
+                return;
+            }
+            // 通知：消息推送
+            if ('method' in msg && msg.method === 'message' && msg.params) {
+                const agentMsg = msg.params;
+                for (const fn of messageListeners) {
+                    fn(agentMsg);
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    });
+    // 认证
+    const authReq = createRequest('session.auth', {
+        sessionId,
+        sandboxName,
+        token: token ?? undefined,
+        role: 'agent',
+    });
+    const authPromise = pending.add(authReq.id);
+    transport.send(JSON.stringify(authReq));
+    let authResult;
+    try {
+        authResult = await authPromise;
+    }
+    catch (err) {
+        transport.close();
+        throw err;
+    }
+    if (!authResult.ok) {
+        transport.close();
+        throw new Error('Authentication failed');
+    }
+    const context = createWsContextClient(transport, pending);
+    const session = {
+        async send(to, type, payload, opts) {
+            const req = createRequest('message.send', {
+                to,
+                type,
+                payload: payload ?? null,
+                priority: opts?.priority ?? 'normal',
+            });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            await promise;
+        },
+        async broadcast(type, payload, opts) {
+            const req = createRequest('message.broadcast', {
+                type,
+                payload: payload ?? null,
+                priority: opts?.priority ?? 'normal',
+            });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            await promise;
+        },
+        async recv(opts) {
+            const req = createRequest('message.recv', {
+                limit: opts?.limit ?? 100,
+                wait: opts?.wait ?? 0,
+            });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            const result = await promise;
+            return result.messages;
+        },
+        on(event, fn) {
+            if (event === 'message') {
+                messageListeners.push(fn);
+                return () => {
+                    const idx = messageListeners.indexOf(fn);
+                    if (idx >= 0)
+                        messageListeners.splice(idx, 1);
+                };
+            }
+            return () => { };
+        },
+        context,
+        async complete(result) {
+            const req = createRequest('sandbox.complete', {
+                status: result.status,
+                summary: result.summary,
+            });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            await promise;
+        },
+        close() {
+            pending.rejectAll('Connection closed');
+            transport.close();
+        },
+    };
+    return session;
+}

package/dist/context-client.d.ts

@@ -0,0 +1,5 @@
+import type { ContextStore, Transport } from '@douglas-agent/sandbank-core';
+import { RpcPendingMap } from './rpc.js';
+/** WebSocket 模式下的 ContextStore 代理 */
+export declare function createWsContextClient(transport: Transport, pending: RpcPendingMap): ContextStore;
+//# sourceMappingURL=context-client.d.ts.map

package/dist/context-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-client.d.ts","sourceRoot":"","sources":["../src/context-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAwC,MAAM,8BAA8B,CAAA;AACjH,OAAO,EAAiB,aAAa,EAAE,MAAM,UAAU,CAAA;AAEvD,qCAAqC;AACrC,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,GAAG,YAAY,CA+DhG"}

package/dist/context-client.js

@@ -0,0 +1,63 @@
+import { createRequest, RpcPendingMap } from './rpc.js';
+/** WebSocket 模式下的 ContextStore 代理 */
+export function createWsContextClient(transport, pending) {
+    const watchers = new Map();
+    const allWatchers = new Set();
+    // 监听 context.changed 通知
+    transport.onMessage((data) => {
+        try {
+            const msg = JSON.parse(data);
+            if ('method' in msg && msg.method === 'context.changed' && msg.params) {
+                const { key, value } = msg.params;
+                const fns = watchers.get(key);
+                if (fns) {
+                    for (const fn of fns)
+                        fn(value);
+                }
+                for (const fn of allWatchers)
+                    fn(key, value);
+            }
+        }
+        catch {
+            // ignore non-JSON or irrelevant messages
+        }
+    });
+    return {
+        async get(key) {
+            const req = createRequest('context.get', { key });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            const result = await promise;
+            return result.value ?? undefined;
+        },
+        async set(key, value) {
+            const req = createRequest('context.set', { key, value });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            await promise;
+        },
+        async delete(key) {
+            const req = createRequest('context.delete', { key });
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            await promise;
+        },
+        async keys() {
+            const req = createRequest('context.keys');
+            const promise = pending.add(req.id);
+            transport.send(JSON.stringify(req));
+            const result = await promise;
+            return result.keys;
+        },
+        watch(key, fn) {
+            if (!watchers.has(key))
+                watchers.set(key, new Set());
+            watchers.get(key).add(fn);
+            return () => { watchers.get(key)?.delete(fn); };
+        },
+        watchAll(fn) {
+            allWatchers.add(fn);
+            return () => { allWatchers.delete(fn); };
+        },
+    };
+}

package/dist/http-client.d.ts

@@ -0,0 +1,14 @@
+export interface HttpClientConfig {
+    relayUrl: string;
+    sessionId: string;
+    sandboxName: string;
+    token: string;
+}
+export declare function sendMessage(to: string, type: string, payload: unknown, priority?: 'normal' | 'steer'): Promise<void>;
+export declare function recvMessages(limit?: number, waitMs?: number): Promise<unknown[]>;
+export declare function contextGet(key: string): Promise<unknown>;
+export declare function contextSet(key: string, value: unknown): Promise<void>;
+export declare function contextDelete(key: string): Promise<void>;
+export declare function contextKeys(): Promise<string[]>;
+export declare function complete(status: string, summary: string): Promise<void>;
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd;AAsCD,wBAAsB,WAAW,CAC/B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,QAAQ,GAAE,QAAQ,GAAG,OAAkB,GACtC,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,YAAY,CAChC,KAAK,SAAM,EACX,MAAM,SAAI,GACT,OAAO,CAAC,OAAO,EAAE,CAAC,CAGpB;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG9D;AAED,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3E;AAED,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9D;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAGrD;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7E"}

package/dist/http-client.js

@@ -0,0 +1,59 @@
+import { createRequest } from './rpc.js';
+function getConfig() {
+    const relayUrl = process.env['SANDBANK_RELAY_URL'];
+    const sessionId = process.env['SANDBANK_SESSION_ID'];
+    const sandboxName = process.env['SANDBANK_SANDBOX_NAME'];
+    const token = process.env['SANDBANK_AUTH_TOKEN'];
+    if (!relayUrl)
+        throw new Error('Missing SANDBANK_RELAY_URL');
+    if (!sessionId)
+        throw new Error('Missing SANDBANK_SESSION_ID');
+    if (!sandboxName)
+        throw new Error('Missing SANDBANK_SANDBOX_NAME');
+    if (!token)
+        throw new Error('Missing SANDBANK_AUTH_TOKEN');
+    return { relayUrl, sessionId, sandboxName, token };
+}
+async function rpcCall(method, params) {
+    const config = getConfig();
+    const request = createRequest(method, params);
+    const response = await fetch(`${config.relayUrl}/rpc`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'X-Session-Id': config.sessionId,
+            'X-Sandbox-Name': config.sandboxName,
+            'X-Auth-Token': config.token,
+        },
+        body: JSON.stringify(request),
+    });
+    const result = await response.json();
+    if (result.error) {
+        throw new Error(`RPC error ${result.error.code}: ${result.error.message}`);
+    }
+    return result.result;
+}
+export async function sendMessage(to, type, payload, priority = 'normal') {
+    await rpcCall('message.send', { to, type, payload, priority });
+}
+export async function recvMessages(limit = 100, waitMs = 0) {
+    const result = await rpcCall('message.recv', { limit, wait: waitMs });
+    return result.messages;
+}
+export async function contextGet(key) {
+    const result = await rpcCall('context.get', { key });
+    return result.value ?? undefined;
+}
+export async function contextSet(key, value) {
+    await rpcCall('context.set', { key, value });
+}
+export async function contextDelete(key) {
+    await rpcCall('context.delete', { key });
+}
+export async function contextKeys() {
+    const result = await rpcCall('context.keys');
+    return result.keys;
+}
+export async function complete(status, summary) {
+    await rpcCall('sandbox.complete', { status, summary });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { connect } from './connect.js';
+export type { AgentSession, AgentMessage, ConnectOptions } 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,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1 @@
+export { connect } from './connect.js';

package/dist/rpc.d.ts

@@ -0,0 +1,10 @@
+import type { JsonRpcRequest, JsonRpcResponse } from '@douglas-agent/sandbank-core';
+export declare function createRequest(method: string, params?: Record<string, unknown>): JsonRpcRequest;
+/** 管理 RPC 请求的 pending promise */
+export declare class RpcPendingMap {
+    private pending;
+    add(id: number | string, timeoutMs?: number): Promise<unknown>;
+    resolve(response: JsonRpcResponse): boolean;
+    rejectAll(reason: string): void;
+}
+//# sourceMappingURL=rpc.d.ts.map

package/dist/rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc.d.ts","sourceRoot":"","sources":["../src/rpc.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAEnF,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,cAAc,CAO9F;AAED,iCAAiC;AACjC,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAGX;IAEJ,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAa9D,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO;IAc3C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAMhC"}

package/dist/rpc.js

@@ -0,0 +1,45 @@
+export function createRequest(method, params) {
+    return {
+        jsonrpc: '2.0',
+        id: crypto.randomUUID(),
+        method,
+        ...(params ? { params } : {}),
+    };
+}
+/** 管理 RPC 请求的 pending promise */
+export class RpcPendingMap {
+    pending = new Map();
+    add(id, timeoutMs = 30_000) {
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`RPC timeout (${timeoutMs}ms)`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (result) => { clearTimeout(timer); resolve(result); },
+                reject: (err) => { clearTimeout(timer); reject(err); },
+            });
+        });
+    }
+    resolve(response) {
+        if (response.id == null)
+            return false;
+        const entry = this.pending.get(response.id);
+        if (!entry)
+            return false;
+        this.pending.delete(response.id);
+        if (response.error) {
+            entry.reject(new Error(`RPC error ${response.error.code}: ${response.error.message}`));
+        }
+        else {
+            entry.resolve(response.result);
+        }
+        return true;
+    }
+    rejectAll(reason) {
+        for (const [, entry] of this.pending) {
+            entry.reject(new Error(reason));
+        }
+        this.pending.clear();
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,4 @@
+import type { Transport } from '@douglas-agent/sandbank-core';
+/** 使用 Node 内置 WebSocket 的 Transport 实现 */
+export declare function createWebSocketTransport(url: string): Promise<Transport>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AAE7D,0CAA0C;AAC1C,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAgDxE"}

package/dist/transport.js

@@ -0,0 +1,45 @@
+/** 使用 Node 内置 WebSocket 的 Transport 实现 */
+export function createWebSocketTransport(url) {
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const listeners = [];
+        let state = 'connecting';
+        ws.addEventListener('open', () => {
+            state = 'open';
+            resolve(transport);
+        });
+        ws.addEventListener('error', (evt) => {
+            if (state === 'connecting') {
+                reject(new Error(`WebSocket connection failed: ${url}`));
+            }
+            state = 'closed';
+        });
+        ws.addEventListener('message', (evt) => {
+            const data = typeof evt.data === 'string' ? evt.data : String(evt.data);
+            for (const fn of listeners) {
+                fn(data);
+            }
+        });
+        ws.addEventListener('close', () => {
+            state = 'closed';
+        });
+        const transport = {
+            send(data) {
+                if (state !== 'open') {
+                    throw new Error('WebSocket is not open');
+                }
+                ws.send(data);
+            },
+            onMessage(fn) {
+                listeners.push(fn);
+            },
+            close() {
+                listeners.length = 0;
+                ws.close();
+            },
+            get readyState() {
+                return state;
+            },
+        };
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,46 @@
+import type { MessagePriority, ContextStore } from '@douglas-agent/sandbank-core';
+export interface AgentMessage {
+    from: string;
+    to: string | null;
+    type: string;
+    payload: unknown;
+    priority: MessagePriority;
+    timestamp: string;
+}
+export interface AgentSession {
+    /** 发送消息给指定沙箱 */
+    send(to: string, type: string, payload?: unknown, options?: {
+        priority?: MessagePriority;
+    }): Promise<void>;
+    /** 广播消息给所有沙箱 */
+    broadcast(type: string, payload?: unknown, options?: {
+        priority?: MessagePriority;
+    }): Promise<void>;
+    /** 拉取待处理消息 */
+    recv(options?: {
+        limit?: number;
+        wait?: number;
+    }): Promise<AgentMessage[]>;
+    /** 监听实时消息（WebSocket 模式） */
+    on(event: 'message', fn: (msg: AgentMessage) => void): () => void;
+    /** 共享上下文 */
+    readonly context: ContextStore;
+    /** 标记当前沙箱完成 */
+    complete(result: {
+        status: string;
+        summary: string;
+    }): Promise<void>;
+    /** 关闭连接 */
+    close(): void;
+}
+export interface ConnectOptions {
+    /** Relay WebSocket URL（默认读 SANDBANK_WS_URL） */
+    wsUrl?: string;
+    /** Session ID（默认读 SANDBANK_SESSION_ID） */
+    sessionId?: string;
+    /** 沙箱名（默认读 SANDBANK_SANDBOX_NAME） */
+    sandboxName?: string;
+    /** 认证 token（默认读 SANDBANK_AUTH_TOKEN） */
+    token?: string;
+}
+//# 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,eAAe,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAEjF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,eAAe,CAAA;IACzB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,gBAAgB;IAChB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1G,gBAAgB;IAChB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,eAAe,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnG,cAAc;IACd,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAA;IAE1E,2BAA2B;IAC3B,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAEjE,YAAY;IACZ,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAE9B,eAAe;IACf,QAAQ,CAAC,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAEpE,WAAW;IACX,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@douglas-agent/sandbank-agent",
+  "version": "0.2.0",
+  "description": "Lightweight client for AI agents running inside Sandbank sandboxes",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sandbank.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeonice/sandbank-douglas-agent.git",
+    "directory": "packages/agent"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "client",
+    "cli"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "sandbank-agent": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "@douglas-agent/sandbank-core": "^0.3.6"
+  },
+  "devDependencies": {
+    "@douglas-agent/sandbank-core": "^0.3.6",
+    "@douglas-agent/sandbank-relay": "^0.2.1",
+    "@types/node": "^22.15.0",
+    "typescript": "^5.7.3",
+    "ws": "^8.18.0",
+    "@types/ws": "^8.18.0"
+  }
+}