@beeos-ai/bma-executor-sdk 0.0.0-stage → 0.4.1

package/dist/transport.js

@@ -0,0 +1,177 @@
+// Transports carry protocol frames unchanged: one JSON-RPC message (control
+// channel) or one raw MCP JSON-RPC message (MCP channel) per frame. Two
+// transports exist: WebSocket, over TCP (ws://, wss://) or a local socket
+// (unix://, npipe://, see local.ts), and in-process pairs.
+import { connect } from 'node:net';
+import WebSocket from 'ws';
+import { NotConnectedError } from './errors.js';
+import { localSocketPath } from './local.js';
+/** Largest frame accepted on any transport (1 MiB), as in the Go SDK. */
+export const MAX_FRAME_BYTES = 1 << 20;
+class BaseConn {
+    protocol;
+    closed = false;
+    handlers;
+    queue = [];
+    closeInfo;
+    constructor(protocol) {
+        this.protocol = protocol;
+    }
+    setHandlers(handlers) {
+        this.handlers = handlers;
+        const queued = this.queue;
+        this.queue = [];
+        for (const frame of queued)
+            handlers.message(frame);
+        if (this.closeInfo)
+            handlers.close(...this.closeInfo);
+    }
+    deliver(frame) {
+        if (this.closeInfo)
+            return;
+        if (this.handlers)
+            this.handlers.message(frame);
+        else
+            this.queue.push(frame);
+    }
+    closedWith(code, reason) {
+        if (this.closeInfo)
+            return;
+        this.closed = true;
+        this.closeInfo = [code, reason];
+        this.handlers?.close(code, reason);
+    }
+}
+class InProcessConn extends BaseConn {
+    peer;
+    send(frame) {
+        if (this.closed)
+            throw new NotConnectedError();
+        const peer = this.peer;
+        queueMicrotask(() => peer.deliver(frame));
+    }
+    close(code = 1000, reason = '') {
+        if (this.closed)
+            return;
+        this.closedWith(code, reason);
+        const peer = this.peer;
+        queueMicrotask(() => peer.closedWith(code, reason));
+    }
+}
+/** Two connected in-process ends, for a brain and a hand in one process. */
+export function inProcessPair(protocol) {
+    const a = new InProcessConn(protocol);
+    const b = new InProcessConn(protocol);
+    a.peer = b;
+    b.peer = a;
+    return [a, b];
+}
+class WebSocketConn extends BaseConn {
+    ws;
+    constructor(ws) {
+        super(ws.protocol);
+        this.ws = ws;
+        ws.on('message', (data) => this.deliver(data.toString()));
+        ws.on('close', (code, reason) => this.closedWith(code, reason.toString()));
+        // An error is always followed by close; the listener keeps it from throwing.
+        ws.on('error', () => { });
+    }
+    send(frame) {
+        if (this.ws.readyState !== WebSocket.OPEN)
+            throw new NotConnectedError();
+        this.ws.send(frame);
+    }
+    close(code = 1000, reason = '') {
+        if (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)
+            this.ws.close(code, reason);
+    }
+}
+/** Wraps an open `ws` WebSocket. */
+export function webSocketConn(ws) {
+    return new WebSocketConn(ws);
+}
+/**
+ * Dials a WebSocket and resolves once it is open. unix:// and npipe:// URLs
+ * run the same handshake over the local socket; their query is the request's.
+ */
+export function dialWebSocket(url, options) {
+    return new Promise((resolve, reject) => {
+        const socketPath = localSocketPath(url);
+        const target = socketPath === undefined ? url : `ws://localhost/v1/executors/channel${new URL(url).search}`;
+        const ws = new WebSocket(target, options.protocols, {
+            headers: options.token ? { Authorization: `Bearer ${options.token}` } : {},
+            maxPayload: options.maxPayload ?? MAX_FRAME_BYTES,
+            ...(socketPath === undefined ? {} : { createConnection: () => connect(socketPath) }),
+        });
+        const onAbort = () => ws.terminate();
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        ws.once('open', () => {
+            options.signal?.removeEventListener('abort', onAbort);
+            resolve(webSocketConn(ws));
+        });
+        ws.once('unexpected-response', (_request, response) => {
+            reject(new Error(`websocket dial ${url}: HTTP ${response.statusCode}`));
+            ws.terminate();
+        });
+        ws.once('error', (error) => reject(new Error(`websocket dial ${url}: ${error.message}`)));
+    });
+}
+/**
+ * FrameChannel reads frames from a Conn one at a time: the raw MCP channel
+ * on both ends. read() rejects with NotConnectedError once the channel closed
+ * and every queued frame was read.
+ */
+export class FrameChannel {
+    conn;
+    frames = [];
+    waiters = [];
+    closeError;
+    closedPromise;
+    markClosed;
+    constructor(conn) {
+        this.conn = conn;
+        this.closedPromise = new Promise((resolve) => (this.markClosed = resolve));
+        conn.setHandlers({
+            message: (frame) => {
+                const waiter = this.waiters.shift();
+                if (waiter)
+                    waiter.resolve(frame);
+                else
+                    this.frames.push(frame);
+            },
+            close: (code, reason) => {
+                this.closeError = new NotConnectedError(`channel closed (${code}${reason ? `: ${reason}` : ''})`);
+                for (const waiter of this.waiters)
+                    waiter.reject(this.closeError);
+                this.waiters = [];
+                this.markClosed();
+            },
+        });
+    }
+    /** Resolves when the channel has closed. */
+    get done() {
+        return this.closedPromise;
+    }
+    read(signal) {
+        const frame = this.frames.shift();
+        if (frame !== undefined)
+            return Promise.resolve(frame);
+        if (this.closeError)
+            return Promise.reject(this.closeError);
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            this.waiters.push(waiter);
+            signal?.addEventListener('abort', () => {
+                this.waiters = this.waiters.filter((candidate) => candidate !== waiter);
+                reject(signal.reason);
+            }, { once: true });
+        });
+    }
+    write(frame) {
+        this.conn.send(frame);
+    }
+    close() {
+        this.conn.close(1000, 'mcp channel closed');
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@beeos-ai/bma-executor-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "BMA executor protocol (bma.executor.v1.1): executor, harness and agent ends with WebSocket, local socket and in-process transports.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/beeos-ai/bma-sdks.git",
+    "directory": "executor/typescript"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && node --test build-test/test/*.test.js"
+  },
+  "dependencies": {
+    "ws": "8.22.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "8.18.2",
+    "typescript": "5.9.3"
+  }
+}