@sandbank.dev/relay 0.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @sandbank.dev/relay
+
+> WebSocket relay server for multi-agent communication in [Sandbank](../../README.md).
+
+Provides HTTP (long-polling) and WebSocket transport with JSON-RPC 2.0 protocol for real-time messaging and shared context between sandboxes.
+
+## Install
+
+```bash
+pnpm add @sandbank.dev/relay
+```
+
+## Usage
+
+Usually used internally by `createSession()` from `@sandbank.dev/core`, but can be started standalone:
+
+```typescript
+import { startRelay } from '@sandbank.dev/relay'
+
+const relay = await startRelay({ port: 4000 })
+console.log(relay.wsUrl) // ws://127.0.0.1:4000
+
+// Later...
+await relay.close()
+```
+
+## Protocol
+
+- **Transport:** HTTP `POST /rpc` + WebSocket, dual-channel
+- **Format:** JSON-RPC 2.0
+- **Auth:** `X-Session-Id` + `X-Auth-Token` headers
+
+### RPC Methods
+
+| Method | Description |
+|--------|-------------|
+| `session.auth` | WebSocket authentication |
+| `message.send` | Point-to-point messaging |
+| `message.broadcast` | Broadcast to all agents |
+| `message.recv` | Pull messages (supports long-polling) |
+| `context.get/set/delete/keys` | Shared context CRUD |
+| `sandbox.complete` | Mark agent as completed |
+
+## License
+
+MIT

package/dist/context-store.d.ts

@@ -0,0 +1,13 @@
+import type { ConnectedClient } from './types.js';
+export declare class ContextStoreServer {
+    private data;
+    private watchers;
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    keys(): string[];
+    watch(fn: (key: string, value: unknown) => void): () => void;
+    /** 通知所有 WebSocket 客户端上下文变更（排除变更来源） */
+    notifyClients(clients: Set<ConnectedClient>, key: string, value: unknown, changedBy: string): void;
+}
+//# sourceMappingURL=context-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context-store.d.ts","sourceRoot":"","sources":["../src/context-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,QAAQ,CAAmD;IAEnE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAI5C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAOtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B,IAAI,IAAI,MAAM,EAAE;IAIhB,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI;IAK5D,sCAAsC;IACtC,aAAa,CAAC,OAAO,EAAE,GAAG,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;CAcnG"}

package/dist/context-store.js

@@ -0,0 +1,45 @@
+export class ContextStoreServer {
+    data = new Map();
+    watchers = new Set();
+    get(key) {
+        return this.data.get(key);
+    }
+    set(key, value) {
+        this.data.set(key, value);
+        for (const fn of this.watchers) {
+            fn(key, value);
+        }
+    }
+    delete(key) {
+        const existed = this.data.delete(key);
+        if (existed) {
+            for (const fn of this.watchers) {
+                fn(key, null);
+            }
+        }
+        return existed;
+    }
+    keys() {
+        return [...this.data.keys()];
+    }
+    watch(fn) {
+        this.watchers.add(fn);
+        return () => { this.watchers.delete(fn); };
+    }
+    /** 通知所有 WebSocket 客户端上下文变更（排除变更来源） */
+    notifyClients(clients, key, value, changedBy) {
+        const notification = JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'context.changed',
+            params: { key, value, changedBy },
+        });
+        for (const client of clients) {
+            const clientName = client.sandboxName ?? (client.role === 'orchestrator' ? 'orchestrator' : '');
+            if (clientName === changedBy)
+                continue;
+            if (client.ws.readyState === client.ws.OPEN) {
+                client.ws.send(notification);
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { startRelay } from './server.js';
+export type { RelayServer, RelayServerOptions } from './server.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,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

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

package/dist/protocol.d.ts

@@ -0,0 +1,12 @@
+import type { JsonRpcRequest, JsonRpcResponse } from '@sandbank.dev/core';
+import type { ConnectedClient } from './types.js';
+import type { SessionStore } from './session-store.js';
+/** 处理 JSON-RPC 请求，返回响应 */
+export declare function handleRpc(store: SessionStore, request: JsonRpcRequest, client: {
+    sessionId: string;
+    sandboxName: string | null;
+    role: 'orchestrator' | 'agent';
+}): JsonRpcResponse | Promise<JsonRpcResponse>;
+/** WebSocket 认证：首条消息 */
+export declare function handleAuth(store: SessionStore, request: JsonRpcRequest, wsClient: ConnectedClient): JsonRpcResponse;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACzE,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,YAAY,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,0BAA0B;AAC1B,wBAAgB,SAAS,CACvB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAA;CAAE,GACxF,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAmC5C;AAED,wBAAwB;AACxB,wBAAgB,UAAU,CACxB,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,eAAe,GACxB,eAAe,CA6CjB"}

package/dist/protocol.js

@@ -0,0 +1,201 @@
+/** 处理 JSON-RPC 请求，返回响应 */
+export function handleRpc(store, request, client) {
+    const { method, params, id } = request;
+    const p = (params ?? {});
+    switch (method) {
+        case 'session.register':
+            return handleRegister(store, id, client.sessionId, p);
+        case 'message.send':
+            return handleSend(store, id, client.sessionId, client.sandboxName, p);
+        case 'message.broadcast':
+            return handleBroadcast(store, id, client.sessionId, client.sandboxName, p);
+        case 'message.recv':
+            return handleRecv(store, id, client.sessionId, client.sandboxName, p);
+        case 'context.get':
+            return handleContextGet(store, id, client.sessionId, p);
+        case 'context.set':
+            return handleContextSet(store, id, client.sessionId, client.sandboxName ?? 'orchestrator', p);
+        case 'context.delete':
+            return handleContextDelete(store, id, client.sessionId, client.sandboxName ?? 'orchestrator', p);
+        case 'context.keys':
+            return handleContextKeys(store, id, client.sessionId);
+        case 'sandbox.complete':
+            return handleComplete(store, id, client.sessionId, client.sandboxName, p);
+        default:
+            return rpcError(id, -32601, `Method not found: ${method}`);
+    }
+}
+/** WebSocket 认证：首条消息 */
+export function handleAuth(store, request, wsClient) {
+    const { id, params } = request;
+    const p = (params ?? {});
+    const sessionId = p['sessionId'];
+    const sandboxName = p['sandboxName'];
+    const token = p['token'];
+    const role = p['role'];
+    if (!sessionId) {
+        return rpcError(id, -32602, 'Missing sessionId');
+    }
+    const existing = store.getSession(sessionId);
+    let session;
+    if (existing) {
+        // Session 已存在 → 必须提供有效 token
+        if (!token) {
+            return rpcError(id, -32600, 'Missing token for existing session');
+        }
+        if (!store.validateToken(sessionId, token)) {
+            return rpcError(id, -32600, 'Invalid token');
+        }
+        session = existing;
+    }
+    else {
+        // Session 不存在 → 创建。This is the primary session creation path for
+        // orchestrators connecting via WebSocket. The relay should be bound to
+        // trusted networks (default: 127.0.0.1). maxSessions limits DoS risk.
+        session = store.getOrCreateSession(sessionId, token);
+    }
+    // Validate sandboxName: agents must claim a registered sandbox name
+    if (sandboxName && !session.sandboxes.has(sandboxName)) {
+        return rpcError(id, -32600, `Sandbox not registered: ${sandboxName}`);
+    }
+    wsClient.sessionId = sessionId;
+    wsClient.sandboxName = sandboxName ?? null;
+    wsClient.role = role === 'orchestrator' ? 'orchestrator' : 'agent';
+    // 加入 session
+    session.clients.add(wsClient);
+    return rpcResult(id, { ok: true, sessionId, sandboxName: sandboxName ?? null, token: session.token });
+}
+// --- Handlers ---
+function handleRegister(store, id, sessionId, params) {
+    const name = params['name'];
+    const sandboxId = params['sandboxId'];
+    if (!name || !sandboxId) {
+        return rpcError(id, -32602, 'Missing name or sandboxId');
+    }
+    try {
+        store.registerSandbox(sessionId, name, sandboxId);
+        return rpcResult(id, { ok: true });
+    }
+    catch (e) {
+        return rpcError(id, -32000, e.message);
+    }
+}
+function handleSend(store, id, sessionId, fromName, params) {
+    const session = store.getSession(sessionId);
+    if (!session)
+        return rpcError(id, -32000, 'Session not found');
+    const to = params['to'];
+    const type = params['type'];
+    const payload = params['payload'];
+    const priority = params['priority'] === 'steer' ? 'steer' : 'normal';
+    if (!to || !type) {
+        return rpcError(id, -32602, 'Missing to or type');
+    }
+    const msg = {
+        from: fromName ?? 'orchestrator',
+        to,
+        type,
+        payload: payload ?? null,
+        priority,
+        timestamp: new Date().toISOString(),
+    };
+    store.enqueueMessage(session, to, msg);
+    return rpcResult(id, { ok: true });
+}
+function handleBroadcast(store, id, sessionId, fromName, params) {
+    const session = store.getSession(sessionId);
+    if (!session)
+        return rpcError(id, -32000, 'Session not found');
+    const type = params['type'];
+    const payload = params['payload'];
+    const priority = params['priority'] === 'steer' ? 'steer' : 'normal';
+    if (!type) {
+        return rpcError(id, -32602, 'Missing type');
+    }
+    const msg = {
+        from: fromName ?? 'orchestrator',
+        to: null,
+        type,
+        payload: payload ?? null,
+        priority,
+        timestamp: new Date().toISOString(),
+    };
+    store.broadcastMessage(session, msg, fromName ?? '');
+    return rpcResult(id, { ok: true });
+}
+function handleRecv(store, id, sessionId, sandboxName, params) {
+    const session = store.getSession(sessionId);
+    if (!session)
+        return rpcError(id, -32000, 'Session not found');
+    if (!sandboxName)
+        return rpcError(id, -32602, 'No sandbox name — cannot recv');
+    const limit = params['limit'] ?? 100;
+    const wait = params['wait'] ?? 0;
+    if (wait <= 0) {
+        const msgs = store.drainQueue(session, sandboxName, limit);
+        return rpcResult(id, { messages: msgs });
+    }
+    // Long polling
+    return store.waitForMessages(session, sandboxName, wait, limit).then((msgs) => {
+        return rpcResult(id, { messages: msgs });
+    });
+}
+function handleContextGet(store, id, sessionId, params) {
+    const ctx = store.getContext(sessionId);
+    if (!ctx)
+        return rpcError(id, -32000, 'Session not found');
+    const key = params['key'];
+    if (!key)
+        return rpcError(id, -32602, 'Missing key');
+    const value = ctx.get(key);
+    return rpcResult(id, { value: value ?? null });
+}
+function handleContextSet(store, id, sessionId, changedBy, params) {
+    const session = store.getSession(sessionId);
+    const ctx = store.getContext(sessionId);
+    if (!session || !ctx)
+        return rpcError(id, -32000, 'Session not found');
+    const key = params['key'];
+    const value = params['value'];
+    if (!key)
+        return rpcError(id, -32602, 'Missing key');
+    ctx.set(key, value);
+    ctx.notifyClients(session.clients, key, value, changedBy);
+    return rpcResult(id, { ok: true });
+}
+function handleContextDelete(store, id, sessionId, changedBy, params) {
+    const session = store.getSession(sessionId);
+    const ctx = store.getContext(sessionId);
+    if (!ctx || !session)
+        return rpcError(id, -32000, 'Session not found');
+    const key = params['key'];
+    if (!key)
+        return rpcError(id, -32602, 'Missing key');
+    ctx.delete(key);
+    ctx.notifyClients(session.clients, key, null, changedBy);
+    return rpcResult(id, { ok: true });
+}
+function handleContextKeys(store, id, sessionId) {
+    const ctx = store.getContext(sessionId);
+    if (!ctx)
+        return rpcError(id, -32000, 'Session not found');
+    return rpcResult(id, { keys: ctx.keys() });
+}
+function handleComplete(store, id, sessionId, sandboxName, params) {
+    const session = store.getSession(sessionId);
+    if (!session)
+        return rpcError(id, -32000, 'Session not found');
+    if (!sandboxName)
+        return rpcError(id, -32602, 'No sandbox name — cannot complete');
+    const status = params['status'] ?? 'success';
+    const summary = params['summary'] ?? '';
+    store.completeSandbox(session, sandboxName, status, summary);
+    return rpcResult(id, { ok: true });
+}
+// --- Helpers ---
+function rpcResult(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function rpcError(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+import type { SessionStoreOptions } from './types.js';
+export interface RelayServerOptions extends SessionStoreOptions {
+    port?: number;
+    host?: string;
+}
+export interface RelayServer {
+    port: number;
+    url: string;
+    wsUrl: string;
+    close(): Promise<void>;
+}
+export declare function startRelay(options?: RelayServerOptions): Promise<RelayServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAmB,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAItE,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,wBAAsB,UAAU,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAqCvF"}

package/dist/server.js

@@ -0,0 +1,203 @@
+import { createServer } from 'node:http';
+import { WebSocketServer } from 'ws';
+import { SessionStore } from './session-store.js';
+import { handleRpc, handleAuth } from './protocol.js';
+export async function startRelay(options = {}) {
+    const port = options.port ?? 0;
+    const host = options.host ?? '127.0.0.1';
+    const store = new SessionStore(options);
+    const httpServer = createServer((req, res) => handleHttp(store, req, res));
+    const wss = new WebSocketServer({ server: httpServer });
+    wss.on('connection', (ws) => {
+        handleWsConnection(store, ws);
+    });
+    return new Promise((resolve) => {
+        httpServer.listen(port, host, () => {
+            const addr = httpServer.address();
+            const assignedPort = typeof addr === 'string' ? port : addr.port;
+            const url = `http://${host}:${assignedPort}`;
+            const wsUrl = `ws://${host}:${assignedPort}`;
+            resolve({
+                port: assignedPort,
+                url,
+                wsUrl,
+                async close() {
+                    store.dispose();
+                    // 关闭所有 WebSocket 连接
+                    for (const ws of wss.clients) {
+                        ws.close(1000, 'relay shutting down');
+                    }
+                    wss.close();
+                    return new Promise((res, rej) => {
+                        httpServer.close((err) => err ? rej(err) : res());
+                    });
+                },
+            });
+        });
+    });
+}
+// --- HTTP Handler ---
+function handleHttp(store, req, res) {
+    if (req.method !== 'POST' || req.url !== '/rpc') {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+        return;
+    }
+    // 读取请求头
+    const sessionId = req.headers['x-session-id'];
+    const sandboxName = req.headers['x-sandbox-name'];
+    const authToken = req.headers['x-auth-token'];
+    if (!sessionId) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Missing X-Session-Id header' } }));
+        return;
+    }
+    // Token 验证：所有请求都必须提供 token
+    if (!authToken) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Missing X-Auth-Token header' } }));
+        return;
+    }
+    const responseHeaders = {
+        'Content-Type': 'application/json',
+    };
+    const MAX_BODY_SIZE = 1 * 1024 * 1024; // 1MB
+    let body = '';
+    let bodySize = 0;
+    let aborted = false;
+    req.on('data', (chunk) => {
+        bodySize += chunk.length;
+        if (bodySize > MAX_BODY_SIZE) {
+            aborted = true;
+            res.writeHead(413, responseHeaders);
+            res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Payload too large' } }));
+            req.destroy();
+            return;
+        }
+        body += chunk.toString();
+    });
+    req.on('end', () => {
+        if (aborted)
+            return;
+        let request;
+        try {
+            request = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400, responseHeaders);
+            res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
+            return;
+        }
+        // Session resolution: existing sessions require valid token;
+        // new sessions can only be created via session.register
+        let session = store.getSession(sessionId);
+        if (session) {
+            if (!store.validateToken(sessionId, authToken)) {
+                res.writeHead(403, responseHeaders);
+                res.end(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32600, message: 'Invalid token' } }));
+                return;
+            }
+        }
+        else {
+            if (request.method !== 'session.register') {
+                res.writeHead(403, responseHeaders);
+                res.end(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32600, message: 'Session not found' } }));
+                return;
+            }
+            session = store.createSession(sessionId, authToken);
+        }
+        store.touch(session);
+        // Validate sandboxName against registered sandboxes (skip for session.register itself)
+        if (sandboxName && request.method !== 'session.register' && !session.sandboxes.has(sandboxName)) {
+            res.writeHead(403, responseHeaders);
+            res.end(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32600, message: `Sandbox not registered: ${sandboxName}` } }));
+            return;
+        }
+        const client = {
+            sessionId,
+            sandboxName: sandboxName ?? null,
+            role: sandboxName ? 'agent' : 'orchestrator',
+        };
+        const result = handleRpc(store, request, client);
+        if (result instanceof Promise) {
+            result.then((response) => {
+                res.writeHead(200, responseHeaders);
+                res.end(JSON.stringify(response));
+            }).catch((err) => {
+                res.writeHead(500, responseHeaders);
+                res.end(JSON.stringify({ jsonrpc: '2.0', id: request.id, error: { code: -32000, message: err.message } }));
+            });
+        }
+        else {
+            res.writeHead(200, responseHeaders);
+            res.end(JSON.stringify(result));
+        }
+    });
+}
+// --- WebSocket Handler ---
+function handleWsConnection(store, ws) {
+    const client = {
+        ws,
+        sessionId: '',
+        sandboxName: null,
+        role: 'agent',
+    };
+    let authenticated = false;
+    ws.on('message', (data) => {
+        let request;
+        try {
+            request = JSON.parse(data.toString());
+        }
+        catch {
+            ws.send(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
+            return;
+        }
+        // 未认证时，只接受 session.auth
+        if (!authenticated) {
+            if (request.method !== 'session.auth') {
+                ws.send(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: request.id,
+                    error: { code: -32600, message: 'Must authenticate first (session.auth)' },
+                }));
+                return;
+            }
+            const response = handleAuth(store, request, client);
+            authenticated = !response.error;
+            ws.send(JSON.stringify(response));
+            return;
+        }
+        // 已认证，处理 RPC
+        const result = handleRpc(store, request, {
+            sessionId: client.sessionId,
+            sandboxName: client.sandboxName,
+            role: client.role,
+        });
+        if (result instanceof Promise) {
+            result.then((response) => {
+                if (ws.readyState === ws.OPEN)
+                    ws.send(JSON.stringify(response));
+            }).catch((err) => {
+                if (ws.readyState === ws.OPEN) {
+                    ws.send(JSON.stringify({
+                        jsonrpc: '2.0',
+                        id: request.id,
+                        error: { code: -32000, message: err.message },
+                    }));
+                }
+            });
+        }
+        else {
+            if (ws.readyState === ws.OPEN)
+                ws.send(JSON.stringify(result));
+        }
+    });
+    ws.on('close', () => {
+        if (client.sessionId) {
+            const session = store.getSession(client.sessionId);
+            if (session) {
+                session.clients.delete(client);
+            }
+        }
+    });
+}

package/dist/session-store.d.ts

@@ -0,0 +1,40 @@
+import { ContextStoreServer } from './context-store.js';
+import type { RelaySession, QueuedMessage, SessionStoreOptions } from './types.js';
+export declare class SessionStore {
+    private sessions;
+    private contexts;
+    private sweepTimer;
+    readonly sessionTtlMs: number;
+    readonly maxSessions: number;
+    readonly maxQueueSize: number;
+    constructor(options?: SessionStoreOptions);
+    /** 停止清扫定时器（用于优雅关闭） */
+    dispose(): void;
+    /** 获取当前 session 数量 */
+    get size(): number;
+    createSession(id: string, token?: string): RelaySession;
+    getSession(id: string): RelaySession | undefined;
+    getOrCreateSession(id: string, token?: string): RelaySession;
+    /** 更新 session 的最后活跃时间 */
+    touch(session: RelaySession): void;
+    validateToken(sessionId: string, token: string): boolean;
+    getContext(sessionId: string): ContextStoreServer | undefined;
+    deleteSession(id: string): void;
+    /** 清扫过期且无活跃连接的 session */
+    sweep(): number;
+    /** 注册沙箱名 */
+    registerSandbox(sessionId: string, name: string, sandboxId: string): void;
+    /** 发送消息到指定沙箱的队列 */
+    enqueueMessage(session: RelaySession, to: string, msg: QueuedMessage): void;
+    /** 广播消息到所有沙箱 */
+    broadcastMessage(session: RelaySession, msg: QueuedMessage, excludeSender: string): void;
+    /** 消耗队列：steer 优先排序 */
+    drainQueue(session: RelaySession, sandboxName: string, limit?: number): QueuedMessage[];
+    /** Long polling：等待消息到达 */
+    waitForMessages(session: RelaySession, sandboxName: string, waitMs: number, limit: number): Promise<QueuedMessage[]>;
+    /** 标记沙箱完成 */
+    completeSandbox(session: RelaySession, sandboxName: string, status: string, summary: string): void;
+    private pushToWebSocketClient;
+    private pushToOrchestrator;
+}
+//# sourceMappingURL=session-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"session-store.d.ts","sourceRoot":"","sources":["../src/session-store.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,YAAY,EAAgB,aAAa,EAAmB,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAOjH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAAwC;IACxD,OAAO,CAAC,UAAU,CAA8C;IAEhE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;gBAEjB,OAAO,GAAE,mBAAwB;IAY7C,sBAAsB;IACtB,OAAO,IAAI,IAAI;IAOf,sBAAsB;IACtB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY;IA2BvD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIhD,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY;IAI5D,yBAAyB;IACzB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAIlC,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAQxD,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI7D,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAqB/B,0BAA0B;IAC1B,KAAK,IAAI,MAAM;IAqBf,YAAY;IACZ,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAWzE,mBAAmB;IACnB,cAAc,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,GAAG,IAAI;IAoC3E,gBAAgB;IAChB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAYxF,sBAAsB;IACtB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,aAAa,EAAE;IAoBpF,0BAA0B;IAC1B,eAAe,CACb,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,aAAa,EAAE,CAAC;IA+B3B,aAAa;IACb,eAAe,CACb,OAAO,EAAE,YAAY,EACrB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,IAAI;IA+BP,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,kBAAkB;CAY3B"}

package/dist/session-store.js

@@ -0,0 +1,282 @@
+import { randomUUID, timingSafeEqual } from 'node:crypto';
+import { ContextStoreServer } from './context-store.js';
+const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_MAX_SESSIONS = 1000;
+const DEFAULT_MAX_QUEUE_SIZE = 10_000;
+const DEFAULT_SWEEP_INTERVAL_MS = 60 * 1000; // 60 seconds
+export class SessionStore {
+    sessions = new Map();
+    contexts = new Map();
+    sweepTimer = null;
+    sessionTtlMs;
+    maxSessions;
+    maxQueueSize;
+    constructor(options = {}) {
+        this.sessionTtlMs = options.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+        this.maxSessions = options.maxSessions ?? DEFAULT_MAX_SESSIONS;
+        this.maxQueueSize = options.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE;
+        const sweepInterval = options.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+        if (this.sessionTtlMs > 0) {
+            this.sweepTimer = setInterval(() => this.sweep(), sweepInterval);
+            this.sweepTimer.unref();
+        }
+    }
+    /** 停止清扫定时器（用于优雅关闭） */
+    dispose() {
+        if (this.sweepTimer) {
+            clearInterval(this.sweepTimer);
+            this.sweepTimer = null;
+        }
+    }
+    /** 获取当前 session 数量 */
+    get size() {
+        return this.sessions.size;
+    }
+    createSession(id, token) {
+        // 容量检查
+        if (this.sessions.size >= this.maxSessions) {
+            // 先尝试清扫过期 session
+            this.sweep();
+            if (this.sessions.size >= this.maxSessions) {
+                throw new Error(`Max sessions reached (${this.maxSessions})`);
+            }
+        }
+        const now = Date.now();
+        const session = {
+            id,
+            token: token ?? randomUUID(),
+            sandboxes: new Map(),
+            context: new Map(),
+            clients: new Set(),
+            messageQueues: new Map(),
+            pollWaiters: new Map(),
+            createdAt: now,
+            lastActivityAt: now,
+        };
+        this.sessions.set(id, session);
+        this.contexts.set(id, new ContextStoreServer());
+        return session;
+    }
+    getSession(id) {
+        return this.sessions.get(id);
+    }
+    getOrCreateSession(id, token) {
+        return this.getSession(id) ?? this.createSession(id, token);
+    }
+    /** 更新 session 的最后活跃时间 */
+    touch(session) {
+        session.lastActivityAt = Date.now();
+    }
+    validateToken(sessionId, token) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            return false;
+        const a = Buffer.from(session.token);
+        const b = Buffer.from(token);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    getContext(sessionId) {
+        return this.contexts.get(sessionId);
+    }
+    deleteSession(id) {
+        const session = this.sessions.get(id);
+        if (session) {
+            // 清理 poll waiters
+            for (const waiters of session.pollWaiters.values()) {
+                for (const w of waiters) {
+                    clearTimeout(w.timer);
+                    w.resolve([]);
+                }
+            }
+            // 关闭所有客户端连接
+            for (const client of session.clients) {
+                if (client.ws.readyState === client.ws.OPEN) {
+                    client.ws.close(1000, 'session closed');
+                }
+            }
+        }
+        this.sessions.delete(id);
+        this.contexts.delete(id);
+    }
+    /** 清扫过期且无活跃连接的 session */
+    sweep() {
+        if (this.sessionTtlMs <= 0)
+            return 0;
+        const now = Date.now();
+        let evicted = 0;
+        const toEvict = [];
+        for (const [id, session] of this.sessions) {
+            const idle = now - session.lastActivityAt;
+            if (idle > this.sessionTtlMs && session.clients.size === 0) {
+                toEvict.push(id);
+            }
+        }
+        for (const id of toEvict) {
+            this.deleteSession(id);
+            evicted++;
+        }
+        return evicted;
+    }
+    /** 注册沙箱名 */
+    registerSandbox(sessionId, name, sandboxId) {
+        const session = this.getSession(sessionId);
+        if (!session)
+            throw new Error(`Session not found: ${sessionId}`);
+        if (name === 'orchestrator')
+            throw new Error('Reserved name: orchestrator');
+        if (session.sandboxes.has(name))
+            throw new Error(`Sandbox already registered: ${name}`);
+        this.touch(session);
+        session.sandboxes.set(name, { name, sandboxId, state: 'running' });
+        session.messageQueues.set(name, []);
+    }
+    /** 发送消息到指定沙箱的队列 */
+    enqueueMessage(session, to, msg) {
+        const queue = session.messageQueues.get(to);
+        if (!queue) {
+            // 目标不是已注册沙箱 — 可能是发给 orchestrator
+            this.pushToOrchestrator(session, msg);
+            return;
+        }
+        // 队列大小限制：丢弃最旧的 normal 消息
+        if (queue.length >= this.maxQueueSize) {
+            const normalIdx = queue.findIndex(m => m.priority === 'normal');
+            if (normalIdx >= 0) {
+                queue.splice(normalIdx, 1);
+            }
+            else {
+                // 全是 steer 消息，丢弃最旧的
+                queue.shift();
+            }
+        }
+        queue.push(msg);
+        this.touch(session);
+        // 检查是否有 long-polling 等待者（优先于 WebSocket 推送，避免双重投递）
+        const waiters = session.pollWaiters.get(to);
+        if (waiters && waiters.length > 0) {
+            const waiter = waiters.shift();
+            clearTimeout(waiter.timer);
+            const msgs = this.drainQueue(session, to);
+            waiter.resolve(msgs);
+            return;
+        }
+        // WebSocket 实时推送
+        this.pushToWebSocketClient(session, to, msg);
+    }
+    /** 广播消息到所有沙箱 */
+    broadcastMessage(session, msg, excludeSender) {
+        for (const [name] of session.sandboxes) {
+            if (name !== excludeSender) {
+                this.enqueueMessage(session, name, msg);
+            }
+        }
+        // 也推送给编排者（除非发送者就是编排者）
+        if (excludeSender !== '') {
+            this.pushToOrchestrator(session, msg);
+        }
+    }
+    /** 消耗队列：steer 优先排序 */
+    drainQueue(session, sandboxName, limit = 100) {
+        const queue = session.messageQueues.get(sandboxName);
+        if (!queue || queue.length === 0)
+            return [];
+        // steer 优先，保持插入顺序（stable partition）
+        const steer = [];
+        const normal = [];
+        for (const m of queue) {
+            if (m.priority === 'steer')
+                steer.push(m);
+            else
+                normal.push(m);
+        }
+        const sorted = [...steer, ...normal];
+        queue.length = 0;
+        queue.push(...sorted);
+        this.touch(session);
+        const msgs = queue.splice(0, limit);
+        return msgs;
+    }
+    /** Long polling：等待消息到达 */
+    waitForMessages(session, sandboxName, waitMs, limit) {
+        // 先检查队列是否已有消息
+        const existing = this.drainQueue(session, sandboxName, limit);
+        if (existing.length > 0)
+            return Promise.resolve(existing);
+        // 限制每个沙箱的并发 long-poll waiter 数
+        const MAX_POLL_WAITERS = 10;
+        const currentWaiters = session.pollWaiters.get(sandboxName);
+        if (currentWaiters && currentWaiters.length >= MAX_POLL_WAITERS) {
+            return Promise.resolve([]);
+        }
+        // 没有消息，挂起等待
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                // 超时，返回空数组
+                const waiters = session.pollWaiters.get(sandboxName);
+                if (waiters) {
+                    const idx = waiters.findIndex((w) => w.resolve === resolve);
+                    if (idx >= 0)
+                        waiters.splice(idx, 1);
+                }
+                resolve([]);
+            }, waitMs);
+            if (!session.pollWaiters.has(sandboxName)) {
+                session.pollWaiters.set(sandboxName, []);
+            }
+            session.pollWaiters.get(sandboxName).push({ resolve, timer });
+        });
+    }
+    /** 标记沙箱完成 */
+    completeSandbox(session, sandboxName, status, summary) {
+        const entry = session.sandboxes.get(sandboxName);
+        if (!entry)
+            return;
+        entry.state = 'completed';
+        entry.completion = {
+            status,
+            summary,
+            timestamp: new Date().toISOString(),
+        };
+        this.touch(session);
+        // 通知编排者
+        const notification = JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'sandbox.state',
+            params: {
+                name: sandboxName,
+                state: 'completed',
+                status,
+                summary,
+            },
+        });
+        for (const client of session.clients) {
+            if (client.role === 'orchestrator' && client.ws.readyState === client.ws.OPEN) {
+                client.ws.send(notification);
+            }
+        }
+    }
+    pushToWebSocketClient(session, targetName, msg) {
+        const notification = JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'message',
+            params: msg,
+        });
+        for (const client of session.clients) {
+            if (client.sandboxName === targetName && client.ws.readyState === client.ws.OPEN) {
+                client.ws.send(notification);
+            }
+        }
+    }
+    pushToOrchestrator(session, msg) {
+        const notification = JSON.stringify({
+            jsonrpc: '2.0',
+            method: 'message',
+            params: msg,
+        });
+        for (const client of session.clients) {
+            if (client.role === 'orchestrator' && client.ws.readyState === client.ws.OPEN) {
+                client.ws.send(notification);
+            }
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,56 @@
+import type { WebSocket } from 'ws';
+/** Session 内已注册的沙箱 */
+export interface SandboxEntry {
+    name: string;
+    sandboxId: string;
+    state: 'running' | 'completed';
+    completion?: {
+        status: string;
+        summary: string;
+        timestamp: string;
+    };
+}
+/** 已认证的客户端连接 */
+export interface ConnectedClient {
+    ws: WebSocket;
+    sessionId: string;
+    sandboxName: string | null;
+    role: 'orchestrator' | 'agent';
+}
+/** 消息队列中的消息 */
+export interface QueuedMessage {
+    from: string;
+    to: string | null;
+    type: string;
+    payload: unknown;
+    priority: 'normal' | 'steer';
+    timestamp: string;
+}
+/** Relay 会话状态 */
+export interface RelaySession {
+    id: string;
+    token: string;
+    sandboxes: Map<string, SandboxEntry>;
+    context: Map<string, unknown>;
+    clients: Set<ConnectedClient>;
+    messageQueues: Map<string, QueuedMessage[]>;
+    /** Long-polling 等待者：sandbox name -> resolve 函数 */
+    pollWaiters: Map<string, Array<{
+        resolve: (msgs: QueuedMessage[]) => void;
+        timer: ReturnType<typeof setTimeout>;
+    }>>;
+    createdAt: number;
+    lastActivityAt: number;
+}
+/** SessionStore 配置选项 */
+export interface SessionStoreOptions {
+    /** Session 空闲超时（毫秒），默认 30 分钟 */
+    sessionTtlMs?: number;
+    /** 最大 session 数，默认 1000 */
+    maxSessions?: number;
+    /** 每个沙箱的最大消息队列长度，默认 10000 */
+    maxQueueSize?: number;
+    /** 清扫间隔（毫秒），默认 60 秒 */
+    sweepIntervalMs?: number;
+}
+//# 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,SAAS,EAAE,MAAM,IAAI,CAAA;AAEnC,sBAAsB;AACtB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,SAAS,GAAG,WAAW,CAAA;IAC9B,UAAU,CAAC,EAAE;QACX,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,SAAS,EAAE,MAAM,CAAA;KAClB,CAAA;CACF;AAED,gBAAgB;AAChB,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,SAAS,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,IAAI,EAAE,cAAc,GAAG,OAAO,CAAA;CAC/B;AAED,eAAe;AACf,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,GAAG,IAAI,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,iBAAiB;AACjB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACpC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,GAAG,CAAC,eAAe,CAAC,CAAA;IAC7B,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;IAC3C,kDAAkD;IAClD,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC;QAC7B,OAAO,EAAE,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,IAAI,CAAA;QACxC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAA;KACrC,CAAC,CAAC,CAAA;IACH,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,wBAAwB;AACxB,MAAM,WAAW,mBAAmB;IAClC,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,2BAA2B;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,uBAAuB;IACvB,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@sandbank.dev/relay",
+  "version": "0.1.0",
+  "description": "WebSocket relay server for multi-agent communication in Sandbank",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sandbank.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chekusu/sandbank.git",
+    "directory": "packages/relay"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "relay",
+    "websocket",
+    "multi-agent"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.0",
+    "typescript": "^5.7.3",
+    "@sandbank.dev/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "@sandbank.dev/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}