@skytalesh/sdk 0.4.0

package/js/envelope.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Message envelope for multi-protocol support.
+ *
+ * Wraps payloads with protocol identification so receivers can deserialize
+ * correctly when different protocols share a channel or bridge.
+ *
+ * Wire format: `[header_len:4 LE][json header][payload]`
+ *
+ * The header is a compact JSON object:
+ * ```json
+ * {"p": "a2a", "ct": "application/json", "md": {"key": "val"}}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Envelope, Protocol } from "@skytalesh/sdk";
+ *
+ * const env: Envelope = {
+ *   protocol: Protocol.A2A,
+ *   contentType: "application/json",
+ *   payload: Buffer.from('{"parts":[]}'),
+ * };
+ * const data = serializeEnvelope(env);
+ * const env2 = deserializeEnvelope(data);
+ * ```
+ */
+/** Supported wire protocols. */
+export declare const Protocol: {
+    readonly RAW: "raw";
+    readonly A2A: "a2a";
+    readonly MCP: "mcp";
+    readonly SLIM: "slim";
+    readonly ACP: "acp";
+    readonly ANP: "anp";
+    readonly LMOS: "lmos";
+    readonly NLIP: "nlip";
+};
+export type Protocol = (typeof Protocol)[keyof typeof Protocol];
+/** Protocol-tagged message envelope. */
+export interface Envelope {
+    protocol: Protocol;
+    contentType: string;
+    payload: Buffer;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serialize an envelope to wire format: `[header_len:4 LE][json header][payload]`.
+ *
+ * @example
+ * ```typescript
+ * const data = serializeEnvelope({
+ *   protocol: Protocol.RAW,
+ *   contentType: "text/plain",
+ *   payload: Buffer.from("hello"),
+ * });
+ * ```
+ */
+export declare function serializeEnvelope(env: Envelope): Buffer;
+/**
+ * Deserialize from wire format.
+ *
+ * @throws {Error} If data is too short, header length is invalid, or header
+ *   JSON is malformed.
+ *
+ * @example
+ * ```typescript
+ * const env = deserializeEnvelope(data);
+ * console.log(env.protocol, env.payload);
+ * ```
+ */
+export declare function deserializeEnvelope(data: Buffer): Envelope;

package/js/envelope.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * Message envelope for multi-protocol support.
+ *
+ * Wraps payloads with protocol identification so receivers can deserialize
+ * correctly when different protocols share a channel or bridge.
+ *
+ * Wire format: `[header_len:4 LE][json header][payload]`
+ *
+ * The header is a compact JSON object:
+ * ```json
+ * {"p": "a2a", "ct": "application/json", "md": {"key": "val"}}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { Envelope, Protocol } from "@skytalesh/sdk";
+ *
+ * const env: Envelope = {
+ *   protocol: Protocol.A2A,
+ *   contentType: "application/json",
+ *   payload: Buffer.from('{"parts":[]}'),
+ * };
+ * const data = serializeEnvelope(env);
+ * const env2 = deserializeEnvelope(data);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Protocol = void 0;
+exports.serializeEnvelope = serializeEnvelope;
+exports.deserializeEnvelope = deserializeEnvelope;
+/** Supported wire protocols. */
+exports.Protocol = {
+    RAW: "raw",
+    A2A: "a2a",
+    MCP: "mcp",
+    SLIM: "slim",
+    ACP: "acp",
+    ANP: "anp",
+    LMOS: "lmos",
+    NLIP: "nlip",
+};
+// 4-byte little-endian unsigned int prefix
+const HEADER_SIZE = 4;
+// Minimum valid envelope: 4-byte header length + 2-byte JSON "{}" + 0-byte payload
+const MIN_ENVELOPE_SIZE = HEADER_SIZE + 2;
+// Maximum allowed header length to prevent memory exhaustion
+const MAX_HEADER_LEN = 65536;
+const VALID_PROTOCOLS = new Set(Object.values(exports.Protocol));
+/**
+ * Serialize an envelope to wire format: `[header_len:4 LE][json header][payload]`.
+ *
+ * @example
+ * ```typescript
+ * const data = serializeEnvelope({
+ *   protocol: Protocol.RAW,
+ *   contentType: "text/plain",
+ *   payload: Buffer.from("hello"),
+ * });
+ * ```
+ */
+function serializeEnvelope(env) {
+    const header = {
+        p: env.protocol,
+        ct: env.contentType,
+    };
+    if (env.metadata && Object.keys(env.metadata).length > 0) {
+        header.md = env.metadata;
+    }
+    const headerBytes = Buffer.from(JSON.stringify(header), "utf-8");
+    const buf = Buffer.alloc(HEADER_SIZE + headerBytes.length + env.payload.length);
+    buf.writeUInt32LE(headerBytes.length, 0);
+    headerBytes.copy(buf, HEADER_SIZE);
+    env.payload.copy(buf, HEADER_SIZE + headerBytes.length);
+    return buf;
+}
+/**
+ * Deserialize from wire format.
+ *
+ * @throws {Error} If data is too short, header length is invalid, or header
+ *   JSON is malformed.
+ *
+ * @example
+ * ```typescript
+ * const env = deserializeEnvelope(data);
+ * console.log(env.protocol, env.payload);
+ * ```
+ */
+function deserializeEnvelope(data) {
+    if (data.length < MIN_ENVELOPE_SIZE) {
+        throw new Error(`envelope too short: ${data.length} bytes (minimum ${MIN_ENVELOPE_SIZE})`);
+    }
+    const headerLen = data.readUInt32LE(0);
+    if (headerLen > MAX_HEADER_LEN) {
+        throw new Error(`header length ${headerLen} exceeds maximum (${MAX_HEADER_LEN} bytes)`);
+    }
+    if (headerLen > data.length - HEADER_SIZE) {
+        throw new Error(`header length ${headerLen} exceeds available data (${data.length - HEADER_SIZE} bytes)`);
+    }
+    const headerBytes = data.subarray(HEADER_SIZE, HEADER_SIZE + headerLen);
+    let header;
+    try {
+        header = JSON.parse(headerBytes.toString("utf-8"));
+    }
+    catch (e) {
+        throw new Error(`malformed envelope header: ${e}`);
+    }
+    const protocolValue = header.p;
+    if (!protocolValue || !VALID_PROTOCOLS.has(protocolValue)) {
+        throw new Error(`invalid protocol in envelope header: ${protocolValue}`);
+    }
+    const protocol = protocolValue;
+    const contentType = header.ct ?? "application/octet-stream";
+    const metadata = header.md;
+    const payload = Buffer.from(data.subarray(HEADER_SIZE + headerLen));
+    return { protocol, contentType, payload, metadata };
+}

package/js/errors.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Typed exception hierarchy for the Skytale SDK.
+ *
+ * All exceptions extend `Error` and carry structured attributes for
+ * programmatic handling:
+ *
+ * - `code` — machine-readable error code (e.g. `"auth_failed"`)
+ * - `httpStatus` — HTTP status that triggered the error (if applicable)
+ * - `docUrl` — link to troubleshooting documentation
+ *
+ * @example
+ * ```typescript
+ * import { ChannelError, AuthError } from "@skytalesh/sdk";
+ *
+ * try {
+ *   mgr.create("bad-name");
+ * } catch (e) {
+ *   if (e instanceof ChannelError) {
+ *     console.log(`channel problem: ${e.message}`);
+ *     console.log(`error code: ${e.code}`);
+ *     console.log(`docs: ${e.docUrl}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class SkytaleError extends Error {
+    readonly code: string;
+    readonly httpStatus?: number;
+    readonly docUrl: string;
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+export declare class AuthError extends SkytaleError {
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+export declare class TransportError extends SkytaleError {
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+export declare class ChannelError extends SkytaleError {
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+export declare class MlsError extends SkytaleError {
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+export declare class QuotaExceededError extends SkytaleError {
+    constructor(message: string, options?: {
+        code?: string;
+        httpStatus?: number;
+        docUrl?: string;
+    });
+}
+/**
+ * Parse a native error message with `[CODE]` prefix into a typed SkytaleError.
+ *
+ * Native Rust errors are formatted as `[error_code] human message`.
+ * This function extracts the code and maps to the appropriate error class.
+ */
+export declare function parseNativeError(e: Error): SkytaleError;

package/js/errors.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Typed exception hierarchy for the Skytale SDK.
+ *
+ * All exceptions extend `Error` and carry structured attributes for
+ * programmatic handling:
+ *
+ * - `code` — machine-readable error code (e.g. `"auth_failed"`)
+ * - `httpStatus` — HTTP status that triggered the error (if applicable)
+ * - `docUrl` — link to troubleshooting documentation
+ *
+ * @example
+ * ```typescript
+ * import { ChannelError, AuthError } from "@skytalesh/sdk";
+ *
+ * try {
+ *   mgr.create("bad-name");
+ * } catch (e) {
+ *   if (e instanceof ChannelError) {
+ *     console.log(`channel problem: ${e.message}`);
+ *     console.log(`error code: ${e.code}`);
+ *     console.log(`docs: ${e.docUrl}`);
+ *   }
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QuotaExceededError = exports.MlsError = exports.ChannelError = exports.TransportError = exports.AuthError = exports.SkytaleError = void 0;
+exports.parseNativeError = parseNativeError;
+class SkytaleError extends Error {
+    code;
+    httpStatus;
+    docUrl;
+    constructor(message, options) {
+        super(message);
+        this.name = "SkytaleError";
+        this.code = options?.code ?? "unknown_error";
+        this.httpStatus = options?.httpStatus;
+        this.docUrl =
+            options?.docUrl ?? `https://skytale.sh/docs/sdk/errors#${this.code}`;
+    }
+}
+exports.SkytaleError = SkytaleError;
+class AuthError extends SkytaleError {
+    constructor(message, options) {
+        super(message, { code: "auth_failed", ...options });
+        this.name = "AuthError";
+    }
+}
+exports.AuthError = AuthError;
+class TransportError extends SkytaleError {
+    constructor(message, options) {
+        super(message, { code: "transport_error", ...options });
+        this.name = "TransportError";
+    }
+}
+exports.TransportError = TransportError;
+class ChannelError extends SkytaleError {
+    constructor(message, options) {
+        super(message, { code: "channel_error", ...options });
+        this.name = "ChannelError";
+    }
+}
+exports.ChannelError = ChannelError;
+class MlsError extends SkytaleError {
+    constructor(message, options) {
+        super(message, { code: "mls_error", ...options });
+        this.name = "MlsError";
+    }
+}
+exports.MlsError = MlsError;
+class QuotaExceededError extends SkytaleError {
+    constructor(message, options) {
+        super(message, { code: "quota_exceeded", ...options });
+        this.name = "QuotaExceededError";
+    }
+}
+exports.QuotaExceededError = QuotaExceededError;
+/**
+ * Parse a native error message with `[CODE]` prefix into a typed SkytaleError.
+ *
+ * Native Rust errors are formatted as `[error_code] human message`.
+ * This function extracts the code and maps to the appropriate error class.
+ */
+function parseNativeError(e) {
+    const match = e.message.match(/^\[(\w+)]\s*(.*)/s);
+    if (!match) {
+        return new SkytaleError(e.message);
+    }
+    const code = match[1];
+    const message = match[2];
+    const codeMap = {
+        auth_failed: AuthError,
+        unauthorized: AuthError,
+        transport_error: TransportError,
+        connection_error: TransportError,
+        listener_died: TransportError,
+        channel_error: ChannelError,
+        not_found: ChannelError,
+        bad_request: ChannelError,
+        mls_error: MlsError,
+        quota_exceeded: QuotaExceededError,
+    };
+    const ErrorClass = codeMap[code] ?? SkytaleError;
+    return new ErrorClass(message, { code });
+}

package/js/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Skytale SDK: Encrypted channels for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleChannelManager, Protocol } from "@skytalesh/sdk";
+ *
+ * const mgr = new SkytaleChannelManager({ identity: "my-agent" });
+ * await mgr.create("org/team/research");
+ * mgr.send("org/team/research", "Hello, encrypted world!");
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { SkytaleChannelManager, type ChannelManagerOptions, } from "./channel-manager";
+export { Protocol, type Envelope, serializeEnvelope, deserializeEnvelope } from "./envelope";
+export { SkytaleAPI } from "./api";
+export { SkytaleError, AuthError, TransportError, ChannelError, MlsError, QuotaExceededError, parseNativeError, } from "./errors";
+export { SkytaleTransport } from "./mcp-transport";

package/js/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Skytale SDK: Encrypted channels for AI agents.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleChannelManager, Protocol } from "@skytalesh/sdk";
+ *
+ * const mgr = new SkytaleChannelManager({ identity: "my-agent" });
+ * await mgr.create("org/team/research");
+ * mgr.send("org/team/research", "Hello, encrypted world!");
+ * ```
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkytaleTransport = exports.parseNativeError = exports.QuotaExceededError = exports.MlsError = exports.ChannelError = exports.TransportError = exports.AuthError = exports.SkytaleError = exports.SkytaleAPI = exports.deserializeEnvelope = exports.serializeEnvelope = exports.Protocol = exports.SkytaleChannelManager = void 0;
+var channel_manager_1 = require("./channel-manager");
+Object.defineProperty(exports, "SkytaleChannelManager", { enumerable: true, get: function () { return channel_manager_1.SkytaleChannelManager; } });
+var envelope_1 = require("./envelope");
+Object.defineProperty(exports, "Protocol", { enumerable: true, get: function () { return envelope_1.Protocol; } });
+Object.defineProperty(exports, "serializeEnvelope", { enumerable: true, get: function () { return envelope_1.serializeEnvelope; } });
+Object.defineProperty(exports, "deserializeEnvelope", { enumerable: true, get: function () { return envelope_1.deserializeEnvelope; } });
+var api_1 = require("./api");
+Object.defineProperty(exports, "SkytaleAPI", { enumerable: true, get: function () { return api_1.SkytaleAPI; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "SkytaleError", { enumerable: true, get: function () { return errors_1.SkytaleError; } });
+Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_1.AuthError; } });
+Object.defineProperty(exports, "TransportError", { enumerable: true, get: function () { return errors_1.TransportError; } });
+Object.defineProperty(exports, "ChannelError", { enumerable: true, get: function () { return errors_1.ChannelError; } });
+Object.defineProperty(exports, "MlsError", { enumerable: true, get: function () { return errors_1.MlsError; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return errors_1.QuotaExceededError; } });
+Object.defineProperty(exports, "parseNativeError", { enumerable: true, get: function () { return errors_1.parseNativeError; } });
+var mcp_transport_1 = require("./mcp-transport");
+Object.defineProperty(exports, "SkytaleTransport", { enumerable: true, get: function () { return mcp_transport_1.SkytaleTransport; } });

package/js/mcp-transport.d.ts

@@ -0,0 +1,96 @@
+/**
+ * MCP JSON-RPC transport over MLS-encrypted Skytale channels.
+ *
+ * Provides {@link SkytaleTransport} — a drop-in MCP transport that replaces
+ * plaintext HTTP/stdio with end-to-end encrypted messaging. Each JSON-RPC
+ * message is serialized as JSON and sent through an MLS-encrypted channel.
+ *
+ * This module is *not* the MCP tool server (`@skytalesh/mcp-server`). This
+ * module provides Skytale **as** the transport layer for arbitrary MCP
+ * protocol messages.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleChannelManager } from "@skytalesh/sdk";
+ * import { SkytaleTransport } from "@skytalesh/sdk/mcp-transport";
+ * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+ *
+ * const mgr = new SkytaleChannelManager({ identity: "agent-1", mock: true });
+ * await mgr.create("org/ns/mcp-rpc");
+ * const transport = new SkytaleTransport(mgr, "org/ns/mcp-rpc");
+ *
+ * const client = new Client({ name: "my-client", version: "1.0.0" });
+ * await client.connect(transport);
+ * ```
+ */
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * Subset of SkytaleChannelManager used by the transport.
+ * Decouples from the concrete class for testability.
+ */
+interface ChannelManagerLike {
+    create(channelName: string): Promise<void>;
+    send(channelName: string, message: string): void;
+    receive(channelName: string, timeoutMs?: number): Promise<string[]>;
+}
+/**
+ * MCP Transport that routes JSON-RPC messages over a Skytale encrypted channel.
+ *
+ * Implements the MCP SDK's `Transport` interface so it can be used with both
+ * MCP clients and servers as a drop-in replacement for stdio or HTTP transports.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SkytaleTransport(manager, "org/ns/mcp");
+ * await transport.start();
+ * await transport.send({ jsonrpc: "2.0", method: "ping", id: 1 });
+ * ```
+ */
+export declare class SkytaleTransport implements Transport {
+    private manager;
+    private channelName;
+    private running;
+    private pollTimer;
+    private pollIntervalMs;
+    onclose?: () => void;
+    onerror?: (error: Error) => void;
+    onmessage?: (message: JSONRPCMessage) => void;
+    /**
+     * @param manager - A SkytaleChannelManager instance with the channel
+     *   already created or joined.
+     * @param channelName - Channel name in `org/namespace/service` format.
+     * @param pollIntervalMs - How often to poll for incoming messages
+     *   (default 200ms).
+     */
+    constructor(manager: ChannelManagerLike, channelName: string, pollIntervalMs?: number);
+    /**
+     * Start listening for messages on the encrypted channel.
+     *
+     * Creates the channel if it does not already exist (errors are silently
+     * ignored since the channel may have been created or joined externally).
+     * Starts a polling loop that delivers incoming messages to the
+     * {@link onmessage} callback.
+     */
+    start(): Promise<void>;
+    /**
+     * Send a JSON-RPC message over the encrypted channel.
+     *
+     * @param message - The JSON-RPC message to send.
+     * @throws {Error} If the transport has been closed.
+     */
+    send(message: JSONRPCMessage): Promise<void>;
+    /**
+     * Stop the transport and clean up resources.
+     *
+     * After closing, any subsequent {@link send} call will throw. The
+     * {@link onclose} callback is invoked if set.
+     */
+    close(): Promise<void>;
+    /**
+     * Internal polling loop. Uses recursive setTimeout to avoid overlapping
+     * polls when receive() takes longer than the interval.
+     */
+    private poll;
+}
+export {};

package/js/mcp-transport.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * MCP JSON-RPC transport over MLS-encrypted Skytale channels.
+ *
+ * Provides {@link SkytaleTransport} — a drop-in MCP transport that replaces
+ * plaintext HTTP/stdio with end-to-end encrypted messaging. Each JSON-RPC
+ * message is serialized as JSON and sent through an MLS-encrypted channel.
+ *
+ * This module is *not* the MCP tool server (`@skytalesh/mcp-server`). This
+ * module provides Skytale **as** the transport layer for arbitrary MCP
+ * protocol messages.
+ *
+ * @example
+ * ```typescript
+ * import { SkytaleChannelManager } from "@skytalesh/sdk";
+ * import { SkytaleTransport } from "@skytalesh/sdk/mcp-transport";
+ * import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+ *
+ * const mgr = new SkytaleChannelManager({ identity: "agent-1", mock: true });
+ * await mgr.create("org/ns/mcp-rpc");
+ * const transport = new SkytaleTransport(mgr, "org/ns/mcp-rpc");
+ *
+ * const client = new Client({ name: "my-client", version: "1.0.0" });
+ * await client.connect(transport);
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SkytaleTransport = void 0;
+const DEFAULT_POLL_INTERVAL_MS = 200;
+/**
+ * MCP Transport that routes JSON-RPC messages over a Skytale encrypted channel.
+ *
+ * Implements the MCP SDK's `Transport` interface so it can be used with both
+ * MCP clients and servers as a drop-in replacement for stdio or HTTP transports.
+ *
+ * @example
+ * ```typescript
+ * const transport = new SkytaleTransport(manager, "org/ns/mcp");
+ * await transport.start();
+ * await transport.send({ jsonrpc: "2.0", method: "ping", id: 1 });
+ * ```
+ */
+class SkytaleTransport {
+    manager;
+    channelName;
+    running = false;
+    pollTimer = null;
+    pollIntervalMs;
+    onclose;
+    onerror;
+    onmessage;
+    /**
+     * @param manager - A SkytaleChannelManager instance with the channel
+     *   already created or joined.
+     * @param channelName - Channel name in `org/namespace/service` format.
+     * @param pollIntervalMs - How often to poll for incoming messages
+     *   (default 200ms).
+     */
+    constructor(manager, channelName, pollIntervalMs) {
+        this.manager = manager;
+        this.channelName = channelName;
+        this.pollIntervalMs = pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    }
+    /**
+     * Start listening for messages on the encrypted channel.
+     *
+     * Creates the channel if it does not already exist (errors are silently
+     * ignored since the channel may have been created or joined externally).
+     * Starts a polling loop that delivers incoming messages to the
+     * {@link onmessage} callback.
+     */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        // Attempt to create the channel; ignore errors if it already exists.
+        try {
+            await this.manager.create(this.channelName);
+        }
+        catch {
+            // Channel may already exist — that's fine.
+        }
+        void this.poll();
+    }
+    /**
+     * Send a JSON-RPC message over the encrypted channel.
+     *
+     * @param message - The JSON-RPC message to send.
+     * @throws {Error} If the transport has been closed.
+     */
+    async send(message) {
+        if (!this.running) {
+            throw new Error("transport is closed");
+        }
+        const payload = JSON.stringify(message);
+        this.manager.send(this.channelName, payload);
+    }
+    /**
+     * Stop the transport and clean up resources.
+     *
+     * After closing, any subsequent {@link send} call will throw. The
+     * {@link onclose} callback is invoked if set.
+     */
+    async close() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.pollTimer !== null) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.onclose?.();
+    }
+    /**
+     * Internal polling loop. Uses recursive setTimeout to avoid overlapping
+     * polls when receive() takes longer than the interval.
+     */
+    async poll() {
+        if (!this.running)
+            return;
+        try {
+            // Use a short timeout (0) so receive returns immediately with whatever
+            // is buffered, avoiding blocking the event loop.
+            const messages = await this.manager.receive(this.channelName, 0);
+            for (const raw of messages) {
+                try {
+                    const parsed = JSON.parse(raw);
+                    this.onmessage?.(parsed);
+                }
+                catch (err) {
+                    this.onerror?.(new Error(`failed to parse incoming MCP message: ${err instanceof Error ? err.message : String(err)}`));
+                }
+            }
+        }
+        catch (err) {
+            this.onerror?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        // Schedule next poll.
+        if (this.running) {
+            this.pollTimer = setTimeout(() => { void this.poll(); }, this.pollIntervalMs);
+        }
+    }
+}
+exports.SkytaleTransport = SkytaleTransport;