@minionry/sdk 0.4.23

package/dist/transports/post-message.d.ts

@@ -0,0 +1,11 @@
+import type { Transport } from '../transport.js';
+import type { MinionryProvider } from '../types.js';
+export interface PostMessageTransportOptions {
+    hostOrigins?: string[];
+    timeoutMs?: number;
+    announceIntervalMs?: number;
+    requestTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+export declare function createPostMessageTransport(options?: PostMessageTransportOptions): Promise<Transport>;
+export declare function connectPostMessage(options?: PostMessageTransportOptions): Promise<MinionryProvider>;

package/dist/transports/post-message.js

@@ -0,0 +1,294 @@
+import { HOST_CONNECT_TYPE, SDK_CONNECT_ACK_TYPE, SDK_EVENT_TYPE, SDK_HELLO_TYPE, SDK_NOTIFICATION_TYPE, SDK_PROTOCOL_VERSION, SDK_KEYDOWN_TYPE, SDK_REQUEST_TYPE, SDK_RESPONSE_TYPE, SDK_TOOL_CALL_TYPE, } from '../protocol.js';
+import { createProvider } from '../provider.js';
+import { MinionryError } from '../types.js';
+const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5_000;
+const DEFAULT_ANNOUNCE_INTERVAL_MS = 250;
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+const INDEFINITE_METHODS = new Set([
+    'connect',
+    'agents.result',
+    'notifications.request',
+    'quality.result',
+    'quality.installTools',
+    'inference.result',
+]);
+const isRecord = (data) => typeof data === 'object' && data !== null;
+const isHostConnectFrame = (data) => {
+    if (!isRecord(data))
+        return false;
+    return (data.type === HOST_CONNECT_TYPE &&
+        data.sdkVersion === SDK_PROTOCOL_VERSION &&
+        typeof data.nonce === 'string' &&
+        data.nonce.length > 0);
+};
+const isResponseError = (data) => isRecord(data) && typeof data.code === 'string' && typeof data.message === 'string';
+const warnDrop = (detail) => {
+    console.warn(`[@minionry/sdk] postMessage transport dropped a frame: ${detail}`);
+};
+const createPortTransport = (port, requestTimeoutMs) => {
+    let handlers;
+    let closed = false;
+    const requestTimers = new Map();
+    const clearRequestTimer = (requestId) => {
+        const timer = requestTimers.get(requestId);
+        if (timer !== undefined) {
+            clearTimeout(timer);
+            requestTimers.delete(requestId);
+        }
+    };
+    const shutdown = () => {
+        if (closed)
+            return;
+        closed = true;
+        for (const timer of requestTimers.values())
+            clearTimeout(timer);
+        requestTimers.clear();
+        port.removeEventListener('close', shutdown);
+        port.onmessage = null;
+        port.close();
+        handlers?.onClose();
+    };
+    port.addEventListener('close', shutdown);
+    const onPortMessage = (event) => {
+        if (closed || !handlers)
+            return;
+        const data = event.data;
+        if (!isRecord(data))
+            return;
+        switch (data.type) {
+            case SDK_RESPONSE_TYPE: {
+                if (typeof data.requestId !== 'string') {
+                    warnDrop('response frame without a string requestId');
+                    return;
+                }
+                if (data.ok === true) {
+                    clearRequestTimer(data.requestId);
+                    handlers.onResponse({ requestId: data.requestId, ok: true, result: data.result });
+                }
+                else if (data.ok === false && isResponseError(data.error)) {
+                    clearRequestTimer(data.requestId);
+                    handlers.onResponse({
+                        requestId: data.requestId,
+                        ok: false,
+                        error: { code: data.error.code, message: data.error.message },
+                    });
+                }
+                else {
+                    warnDrop(`malformed response frame for requestId '${data.requestId}'`);
+                }
+                return;
+            }
+            case SDK_EVENT_TYPE: {
+                if (typeof data.requestId !== 'string' || typeof data.event !== 'string') {
+                    warnDrop('malformed event frame');
+                    return;
+                }
+                handlers.onEvent({
+                    requestId: data.requestId,
+                    event: data.event,
+                    payload: data.payload,
+                    ...(typeof data.seq === 'number' ? { seq: data.seq } : {}),
+                });
+                return;
+            }
+            case SDK_NOTIFICATION_TYPE: {
+                if (typeof data.event !== 'string') {
+                    warnDrop('malformed notification frame');
+                    return;
+                }
+                handlers.onNotification({ event: data.event, payload: data.payload });
+                return;
+            }
+            case SDK_TOOL_CALL_TYPE: {
+                if (typeof data.callId !== 'string' || typeof data.requestId !== 'string') {
+                    warnDrop('tool-call frame without string callId/requestId');
+                    return;
+                }
+                if (data.op === 'cancel') {
+                    handlers.onToolCall?.({ op: 'cancel', callId: data.callId, requestId: data.requestId });
+                    return;
+                }
+                if (data.op !== 'call' || typeof data.tool !== 'string') {
+                    warnDrop(`malformed tool-call frame for callId '${data.callId}'`);
+                    return;
+                }
+                handlers.onToolCall?.({
+                    op: 'call',
+                    callId: data.callId,
+                    requestId: data.requestId,
+                    tool: data.tool,
+                    input: data.input,
+                });
+                return;
+            }
+            default:
+                return;
+        }
+    };
+    return {
+        start(startHandlers) {
+            if (closed)
+                throw new Error('postMessage transport is closed');
+            if (handlers)
+                throw new Error('postMessage transport already started — create one transport per provider');
+            handlers = startHandlers;
+            port.onmessage = onPortMessage;
+        },
+        send(frame) {
+            if (closed)
+                throw new Error('postMessage transport is closed');
+            if (!handlers)
+                throw new Error('postMessage transport not started');
+            const wire = { type: SDK_REQUEST_TYPE, requestId: frame.requestId, method: frame.method };
+            if (frame.params !== undefined)
+                wire.params = frame.params;
+            port.postMessage(wire);
+            if (requestTimeoutMs > 0 && !INDEFINITE_METHODS.has(frame.method)) {
+                const { requestId, method } = frame;
+                requestTimers.set(requestId, setTimeout(() => {
+                    requestTimers.delete(requestId);
+                    handlers?.onResponse({
+                        requestId,
+                        ok: false,
+                        error: {
+                            code: 'TIMEOUT',
+                            message: `${method} timed out after ${requestTimeoutMs}ms — no response from the Minionry host`,
+                        },
+                    });
+                }, requestTimeoutMs));
+            }
+        },
+        sendKeydown(event) {
+            if (closed || !handlers)
+                return;
+            const wire = {
+                type: SDK_KEYDOWN_TYPE,
+                code: event.code,
+                key: event.key,
+                altKey: event.altKey,
+                ctrlKey: event.ctrlKey,
+                metaKey: event.metaKey,
+                shiftKey: event.shiftKey,
+            };
+            if (event.isComposing)
+                wire.isComposing = true;
+            port.postMessage(wire);
+        },
+        close() {
+            shutdown();
+        },
+    };
+};
+export function createPostMessageTransport(options = {}) {
+    const hostOrigins = options.hostOrigins?.length ? [...options.hostOrigins] : null;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+    const announceIntervalMs = options.announceIntervalMs ?? DEFAULT_ANNOUNCE_INTERVAL_MS;
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const signal = options.signal;
+    return new Promise((resolve, reject) => {
+        if (typeof window === 'undefined') {
+            reject(new MinionryError('TIMEOUT', 'postMessage handshake requires a browser window (no window in this environment)'));
+            return;
+        }
+        if (signal?.aborted) {
+            reject(new MinionryError('TIMEOUT', 'postMessage handshake aborted before it started'));
+            return;
+        }
+        const parent = window.parent;
+        let settled = false;
+        let adopted = null;
+        let announceTimer;
+        let deadlineTimer;
+        let finalizeTimer;
+        const stopWaiting = () => {
+            window.removeEventListener('message', onWindowMessage);
+            signal?.removeEventListener('abort', onAbort);
+            if (announceTimer !== undefined)
+                clearInterval(announceTimer);
+            if (deadlineTimer !== undefined)
+                clearTimeout(deadlineTimer);
+        };
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            stopWaiting();
+            if (finalizeTimer !== undefined)
+                clearTimeout(finalizeTimer);
+            if (adopted !== null) {
+                adopted.port.close();
+                adopted = null;
+            }
+            reject(new MinionryError('TIMEOUT', 'postMessage handshake aborted by the caller before a host session was established'));
+        };
+        const announce = () => {
+            const hello = { type: SDK_HELLO_TYPE, sdkVersion: SDK_PROTOCOL_VERSION };
+            for (const targetOrigin of hostOrigins ?? ['*']) {
+                try {
+                    parent.postMessage(hello, targetOrigin);
+                }
+                catch {
+                }
+            }
+        };
+        const finalize = () => {
+            finalizeTimer = undefined;
+            if (settled || adopted === null)
+                return;
+            settled = true;
+            stopWaiting();
+            const { nonce, port } = adopted;
+            adopted = null;
+            const ack = { type: SDK_CONNECT_ACK_TYPE, nonce };
+            try {
+                port.postMessage(ack);
+            }
+            catch (cause) {
+                port.close();
+                reject(new MinionryError('SPACE_DISCONNECTED', `postMessage handshake failed: could not ack the host offer (${String(cause)})`));
+                return;
+            }
+            resolve(createPortTransport(port, requestTimeoutMs));
+        };
+        const onWindowMessage = (event) => {
+            if (settled)
+                return;
+            if (!isHostConnectFrame(event.data))
+                return;
+            if (event.source !== parent)
+                return;
+            if (hostOrigins && !hostOrigins.includes(event.origin))
+                return;
+            if (event.ports.length !== 1)
+                return;
+            if (adopted !== null)
+                adopted.port.close();
+            adopted = { nonce: event.data.nonce, port: event.ports[0] };
+            if (announceTimer !== undefined) {
+                clearInterval(announceTimer);
+                announceTimer = undefined;
+            }
+            finalizeTimer ??= setTimeout(finalize, 0);
+        };
+        window.addEventListener('message', onWindowMessage);
+        signal?.addEventListener('abort', onAbort);
+        if (timeoutMs > 0) {
+            deadlineTimer = setTimeout(() => {
+                if (settled || adopted !== null)
+                    return;
+                settled = true;
+                stopWaiting();
+                if (finalizeTimer !== undefined)
+                    clearTimeout(finalizeTimer);
+                reject(new MinionryError('TIMEOUT', `postMessage handshake timed out after ${timeoutMs}ms — no Minionry host answered; is this page running inside a Minionry app frame?`));
+            }, timeoutMs);
+        }
+        announce();
+        announceTimer = setInterval(announce, announceIntervalMs);
+    });
+}
+export async function connectPostMessage(options = {}) {
+    const provider = createProvider(await createPostMessageTransport(options));
+    window.minionry = provider;
+    return provider;
+}