@atropical/stroq-studio-mcp 0.0.0-stage → 0.1.1

package/dist/modelFile.js

@@ -0,0 +1,255 @@
+// stroq-studio-mcp: the relay between an MCP client and a Strōq World Studio tab.
+// Copyright (C) 2026 Atropical
+// SPDX-License-Identifier: GPL-3.0-only
+/**
+ * import_model_file's local side: the one place the relay reads files. Only a
+ * .glb, a .gltf (with the .bin buffers and PNG/JPEG/WebP/KTX2 images it
+ * names, from its folder and at most two levels down) or a .zip of the same;
+ * no symlinks, no hidden files, nothing outside the model's folder; buffer
+ * sizes must match the glTF and images their type; at most MAX_MODEL_BYTES.
+ */
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { basename, dirname, extname, isAbsolute, join, relative } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+export const MAX_MODEL_BYTES = 100 * 1024 * 1024;
+/** Bytes per chunk sent to the tab (base64 makes a frame about 1.4 MB). */
+export const CHUNK_BYTES = 1024 * 1024;
+export const MODEL_EXTENSIONS = ['.glb', '.gltf', '.zip'];
+/** What a .gltf (or a zip) may carry beside the model. */
+export const SIBLING_EXTENSIONS = ['.bin', '.png', '.jpg', '.jpeg', '.webp', '.ktx2'];
+/** Folders below the model's own that a sibling may sit in. */
+export const MAX_DEPTH = 2;
+const MAX_SIBLINGS = 200;
+export class ModelFileError extends Error {
+}
+const mb = (n) => `${Math.round(n / 1048576)} MB`;
+/** A regular file, not a symlink, whose real path is inside root (a real path). Returns its size. */
+async function plainFileInside(path, root) {
+    let st;
+    try {
+        st = await lstat(path);
+    }
+    catch {
+        throw new ModelFileError(`No file at ${path}`);
+    }
+    if (st.isSymbolicLink())
+        throw new ModelFileError(`${path} is a symlink; give the real file`);
+    if (!st.isFile())
+        throw new ModelFileError(`${path} is not a file`);
+    const rel = relative(root, await realpath(path));
+    if (rel === '' || rel.startsWith('..') || isAbsolute(rel))
+        throw new ModelFileError(`${path} is outside the model's folder`);
+    return st.size;
+}
+/** A relative path's checks: no scheme, absolute, '..' or hidden segment; an allowed type; at most MAX_DEPTH folders down. */
+function checkRelative(p, allowed, what) {
+    const parts = p.replace(/\\/g, '/').split('/');
+    if (!p || /^[a-z][a-z0-9+.-]*:/i.test(p) || /^[\\/]/.test(p) || parts.some((s) => s === '' || s === '..'))
+        throw new ModelFileError(`${what} names a file outside its folder: ${p}`);
+    if (parts.some((s) => s.startsWith('.')))
+        throw new ModelFileError(`${what} names a hidden file: ${p}`);
+    if (parts.length - 1 > MAX_DEPTH)
+        throw new ModelFileError(`${what} names a file more than ${MAX_DEPTH} folders down: ${p}`);
+    if (!allowed.includes(extname(p).toLowerCase()))
+        throw new ModelFileError(`${what} names ${p}: only ${allowed.join(', ')} files may come with a model`);
+    return parts.join('/');
+}
+const IMAGE_EXTENSIONS = SIBLING_EXTENSIONS.filter((e) => e !== '.bin');
+/** The files a .gltf names (buffers and images), checked; data: URIs are inside the file already. */
+export function gltfSiblings(json) {
+    const out = new Map();
+    const doc = (json ?? {});
+    const add = (item, buffer) => {
+        const uri = item?.uri;
+        if (typeof uri !== 'string' || uri.startsWith('data:'))
+            return;
+        let p;
+        try {
+            p = decodeURIComponent(uri);
+        }
+        catch {
+            throw new ModelFileError(`Bad file name in the glTF: ${uri}`);
+        }
+        const path = checkRelative(p, buffer ? ['.bin'] : IMAGE_EXTENSIONS, 'The glTF');
+        const prev = out.get(path) ?? { path };
+        if (buffer) {
+            const len = item?.byteLength;
+            if (typeof len !== 'number' || !Number.isInteger(len) || len < 0)
+                throw new ModelFileError(`The glTF buffer ${uri} has no byteLength`);
+            if (prev.byteLength !== undefined && prev.byteLength !== len)
+                throw new ModelFileError(`The glTF names ${uri} with two sizes`);
+            prev.byteLength = len;
+        }
+        else if (prev.byteLength !== undefined)
+            throw new ModelFileError(`The glTF names ${uri} as a buffer and an image`);
+        out.set(path, prev);
+    };
+    for (const b of Array.isArray(doc.buffers) ? doc.buffers : [])
+        add(b, true);
+    for (const i of Array.isArray(doc.images) ? doc.images : [])
+        add(i, false);
+    if (out.size > MAX_SIBLINGS)
+        throw new ModelFileError(`The glTF names more than ${MAX_SIBLINGS} files`);
+    return [...out.values()];
+}
+const MAGIC = {
+    '.png': [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a],
+    '.jpg': [0xff, 0xd8, 0xff],
+    '.jpeg': [0xff, 0xd8, 0xff],
+    '.ktx2': [0xab, 0x4b, 0x54, 0x58, 0x20, 0x32, 0x30, 0xbb, 0x0d, 0x0a, 0x1a, 0x0a],
+};
+const GLB = [0x67, 0x6c, 0x54, 0x46]; // "glTF"
+const starts = (d, sig, at = 0) => d.length >= at + sig.length && sig.every((b, i) => d[at + i] === b);
+/** An image's first bytes must match its type (a .env renamed .png is refused). */
+export function checkImage(name, d) {
+    const ext = extname(name).toLowerCase();
+    const sig = MAGIC[ext];
+    const ok = ext === '.webp' ? starts(d, [0x52, 0x49, 0x46, 0x46]) && starts(d, [0x57, 0x45, 0x42, 0x50], 8) : !!sig && starts(d, sig);
+    if (!ok)
+        throw new ModelFileError(`${name} is not a ${ext.slice(1).toUpperCase()} image`);
+}
+function checkSibling(s, d) {
+    if (s.byteLength === undefined)
+        return checkImage(s.path, d);
+    if (d.length !== s.byteLength)
+        throw new ModelFileError(`${s.path} is ${d.length} bytes, the glTF says ${s.byteLength}`);
+}
+function parseGltf(d, name) {
+    try {
+        return JSON.parse(new TextDecoder().decode(d));
+    }
+    catch {
+        throw new ModelFileError(`${name} is not valid JSON`);
+    }
+}
+/**
+ * A zip's entries, read and checked without trusting it: only .glb/.gltf and
+ * the sibling types, no hidden segments, at most MAX_DEPTH folders down,
+ * stored or deflated, no encryption or zip64, within max. A .gltf inside is
+ * checked like one on disk (its siblings must be in the zip); images by type.
+ */
+export function checkZip(zip, max = MAX_MODEL_BYTES) {
+    const dv = new DataView(zip.buffer, zip.byteOffset, zip.byteLength);
+    let eocd = -1;
+    for (let i = zip.length - 22; i >= Math.max(0, zip.length - 22 - 65535); i--)
+        if (dv.getUint32(i, true) === 0x06054b50) {
+            eocd = i;
+            break;
+        }
+    if (eocd < 0)
+        throw new ModelFileError('The .zip is not a zip file');
+    const count = dv.getUint16(eocd + 10, true);
+    let at = dv.getUint32(eocd + 16, true);
+    if (count === 0xffff || at === 0xffffffff)
+        throw new ModelFileError('Zip64 files are not supported');
+    if (count > MAX_SIBLINGS + 10)
+        throw new ModelFileError(`The .zip holds more than ${MAX_SIBLINGS + 10} files`);
+    const entries = new Map();
+    let total = 0;
+    let models = 0;
+    const dec = new TextDecoder();
+    for (let n = 0; n < count; n++) {
+        if (at + 46 > zip.length || dv.getUint32(at, true) !== 0x02014b50)
+            throw new ModelFileError('The .zip is damaged');
+        const flags = dv.getUint16(at + 8, true);
+        const method = dv.getUint16(at + 10, true);
+        const csize = dv.getUint32(at + 20, true);
+        const usize = dv.getUint32(at + 24, true);
+        const nlen = dv.getUint16(at + 28, true);
+        const xlen = dv.getUint16(at + 30, true);
+        const clen = dv.getUint16(at + 32, true);
+        const local = dv.getUint32(at + 42, true);
+        const name = dec.decode(zip.subarray(at + 46, at + 46 + nlen));
+        at += 46 + nlen + xlen + clen;
+        if (name.endsWith('/')) {
+            checkRelative(`${name}x.bin`, ['.bin'], 'The .zip'); // folders: same path rules
+            continue;
+        }
+        const path = checkRelative(name, ['.glb', '.gltf', ...SIBLING_EXTENSIONS], 'The .zip');
+        if (flags & 1)
+            throw new ModelFileError('Encrypted zips are not supported');
+        if (method !== 0 && method !== 8)
+            throw new ModelFileError(`${name}: only stored or deflated zip entries`);
+        total += usize;
+        if (total > max)
+            throw new ModelFileError(`The model and its files are over ${mb(max)}`);
+        if (local + 30 > zip.length || dv.getUint32(local, true) !== 0x04034b50)
+            throw new ModelFileError('The .zip is damaged');
+        const start = local + 30 + dv.getUint16(local + 26, true) + dv.getUint16(local + 28, true);
+        const raw = zip.subarray(start, start + csize);
+        let data;
+        try {
+            data = method === 0 ? raw : new Uint8Array(inflateRawSync(raw, { maxOutputLength: Math.max(1, usize) }));
+        }
+        catch {
+            throw new ModelFileError(`${name} in the .zip is damaged`);
+        }
+        if (data.length !== usize)
+            throw new ModelFileError(`${name} in the .zip is damaged`);
+        const ext = extname(path).toLowerCase();
+        if (ext === '.glb' || ext === '.gltf')
+            models++;
+        if (ext === '.glb' && !starts(data, GLB))
+            throw new ModelFileError(`${name} is not a GLB`);
+        if (IMAGE_EXTENSIONS.includes(ext))
+            checkImage(path, data);
+        entries.set(path, data);
+    }
+    if (models === 0)
+        throw new ModelFileError('The .zip holds no .glb or .gltf');
+    for (const [path, data] of entries) {
+        if (extname(path).toLowerCase() !== '.gltf')
+            continue;
+        const dir = path.includes('/') ? path.slice(0, path.lastIndexOf('/') + 1) : '';
+        for (const s of gltfSiblings(parseGltf(data, path))) {
+            const d = entries.get(dir + s.path);
+            if (!d)
+                throw new ModelFileError(`${path} names ${s.path}, which is not in the .zip`);
+            checkSibling(s, d);
+        }
+    }
+}
+/** Reads a model for import, checked as above. Throws ModelFileError with a message for the agent. */
+export async function readModelFiles(path, max = MAX_MODEL_BYTES) {
+    if (typeof path !== 'string' || !isAbsolute(path))
+        throw new ModelFileError('Give the model as an absolute path');
+    const ext = extname(path).toLowerCase();
+    if (!MODEL_EXTENSIONS.includes(ext))
+        throw new ModelFileError(`Only ${MODEL_EXTENSIONS.join(', ')} files (export a GLB from Blender)`);
+    if (basename(path).startsWith('.'))
+        throw new ModelFileError('Hidden files are not models');
+    let root;
+    try {
+        root = await realpath(dirname(path));
+    }
+    catch {
+        throw new ModelFileError(`No folder at ${dirname(path)}`);
+    }
+    const main = join(root, basename(path));
+    let total = await plainFileInside(main, root);
+    if (total > max)
+        throw new ModelFileError(`The file is over ${mb(max)}`);
+    const mainData = new Uint8Array(await readFile(main));
+    if (mainData.length > max)
+        throw new ModelFileError(`The file is over ${mb(max)}`);
+    const files = [{ name: basename(main), data: mainData }];
+    if (ext === '.glb') {
+        if (!starts(mainData, GLB))
+            throw new ModelFileError(`${basename(main)} is not a GLB`);
+        return files;
+    }
+    if (ext === '.zip') {
+        checkZip(mainData, max);
+        return files;
+    }
+    for (const s of gltfSiblings(parseGltf(mainData, basename(main)))) {
+        const p = join(root, ...s.path.split('/'));
+        total += await plainFileInside(p, root);
+        if (total > max)
+            throw new ModelFileError(`The model and its files are over ${mb(max)}`);
+        const data = new Uint8Array(await readFile(p));
+        checkSibling(s, data);
+        files.push({ name: s.path, data });
+    }
+    return files;
+}

package/dist/protocol.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The wire protocol between the relay and the Studio tab: JSON text frames
+ * over one WebSocket.
+ *
+ * Pairing is mutual and the secret never crosses the wire. The key is the
+ * pairing token (26 base32 characters, ~130 bits; dashes and case ignored)
+ * or, to reconnect after a reload, the resume key both sides derived when
+ * they last paired. Every proof names the port the tab dialled, so a relay in
+ * the middle on another port cannot pass them on.
+ *
+ *   tab → relay   hello     { type, protocol, mode, port, nonce }   mode 'token' | 'resume'; nonce: 32 random bytes, hex
+ *   relay → tab   challenge { type, nonce, proof }    proof = HMAC-SHA256(key, "relay|" + port + "|" + tabNonce + "|" + relayNonce), hex
+ *   tab → relay   prove     { type, proof }           after checking the relay's proof: HMAC(key, "tab|" + port + "|" + …)
+ *   relay → tab   wait      { type, ms }              the challenge comes late (many failed handshakes lately)
+ *   relay → tab   refused   { type, reason }          then the relay closes the socket
+ *
+ * Then both hold session = HMAC(key, "session|…") and resume = HMAC(key,
+ * "resume|…"), never sent. Every later frame, both ways, is sealed:
+ *
+ *   { type: "sealed", seq, body, mac }   body: the frame's JSON; seq counts from 0 per direction;
+ *                                        mac = HMAC(session, dir + "|" + seq + "|" + body), dir "relay" or "tab"
+ *
+ * A bad MAC or a sequence number out of order closes the socket. Sealed bodies:
+ *
+ *   relay → tab   welcome { type, protocol }          first sealed frame: paired
+ *   tab → relay   tools   { type, tools: ToolInfo[] } any time; the relay tells the MCP client the list changed
+ *   relay → tab   call    { type, id, name, arguments }
+ *   tab → relay   result  { type, id, content, isError? }  content is MCP content (text and image blocks)
+ *   either        ping / pong { type }                keep-alive
+ */
+export declare const PROTOCOL = 3;
+/** The pairing token as a key: upper case, letters and digits only. */
+export declare const tokenKey: (t: string) => string;
+export type ProofKind = 'relay' | 'tab' | 'resume' | 'session';
+export declare const proofText: (who: ProofKind, port: number, tabNonce: string, relayNonce: string) => string;
+export declare const macText: (dir: "relay" | "tab", seq: number, body: string) => string;
+export interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: {
+        type: 'object';
+        [k: string]: unknown;
+    };
+}
+export type Content = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    data: string;
+    mimeType: string;
+};
+export type TabMessage = {
+    type: 'hello';
+    protocol: number;
+    mode: 'token' | 'resume';
+    port: number;
+    nonce: string;
+} | {
+    type: 'sealed';
+    seq: number;
+    body: string;
+    mac: string;
+} | {
+    type: 'prove';
+    proof: string;
+} | {
+    type: 'tools';
+    tools: ToolInfo[];
+} | {
+    type: 'result';
+    id: number;
+    content: Content[];
+    isError?: boolean;
+} | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+export type RelayMessage = {
+    type: 'challenge';
+    nonce: string;
+    proof: string;
+} | {
+    type: 'welcome';
+    protocol: number;
+} | {
+    type: 'sealed';
+    seq: number;
+    body: string;
+    mac: string;
+} | {
+    type: 'wait';
+    ms: number;
+} | {
+    type: 'refused';
+    reason: string;
+} | {
+    type: 'call';
+    id: number;
+    name: string;
+    arguments: Record<string, unknown>;
+} | {
+    type: 'ping';
+} | {
+    type: 'pong';
+};
+/**
+ * import_model_file runs in the relay: it reads the file and sends it as
+ * import_model_part calls { upload, file, size, offset, data (base64) }, then
+ * calls the tab's import_model_file { upload, files: [{ name, size }], name?,
+ * category?, tags? }. The relay lists it only when the tab lists both, and
+ * never lists import_model_part.
+ */
+export declare const IMPORT_FILE = "import_model_file";
+export declare const IMPORT_PART = "import_model_part";
+/** Largest frame the relay accepts from the tab (screenshots are big). */
+export declare const MAX_FRAME: number;
+/** A frame from the tab, checked; null when it is not one. */
+export declare function parseTabMessage(raw: string): TabMessage | null;

package/dist/protocol.js

@@ -0,0 +1,108 @@
+// stroq-studio-mcp: the relay between an MCP client and a Strōq World Studio tab.
+// Copyright (C) 2026 Atropical
+// SPDX-License-Identifier: GPL-3.0-only
+/**
+ * The wire protocol between the relay and the Studio tab: JSON text frames
+ * over one WebSocket.
+ *
+ * Pairing is mutual and the secret never crosses the wire. The key is the
+ * pairing token (26 base32 characters, ~130 bits; dashes and case ignored)
+ * or, to reconnect after a reload, the resume key both sides derived when
+ * they last paired. Every proof names the port the tab dialled, so a relay in
+ * the middle on another port cannot pass them on.
+ *
+ *   tab → relay   hello     { type, protocol, mode, port, nonce }   mode 'token' | 'resume'; nonce: 32 random bytes, hex
+ *   relay → tab   challenge { type, nonce, proof }    proof = HMAC-SHA256(key, "relay|" + port + "|" + tabNonce + "|" + relayNonce), hex
+ *   tab → relay   prove     { type, proof }           after checking the relay's proof: HMAC(key, "tab|" + port + "|" + …)
+ *   relay → tab   wait      { type, ms }              the challenge comes late (many failed handshakes lately)
+ *   relay → tab   refused   { type, reason }          then the relay closes the socket
+ *
+ * Then both hold session = HMAC(key, "session|…") and resume = HMAC(key,
+ * "resume|…"), never sent. Every later frame, both ways, is sealed:
+ *
+ *   { type: "sealed", seq, body, mac }   body: the frame's JSON; seq counts from 0 per direction;
+ *                                        mac = HMAC(session, dir + "|" + seq + "|" + body), dir "relay" or "tab"
+ *
+ * A bad MAC or a sequence number out of order closes the socket. Sealed bodies:
+ *
+ *   relay → tab   welcome { type, protocol }          first sealed frame: paired
+ *   tab → relay   tools   { type, tools: ToolInfo[] } any time; the relay tells the MCP client the list changed
+ *   relay → tab   call    { type, id, name, arguments }
+ *   tab → relay   result  { type, id, content, isError? }  content is MCP content (text and image blocks)
+ *   either        ping / pong { type }                keep-alive
+ */
+export const PROTOCOL = 3;
+/** The pairing token as a key: upper case, letters and digits only. */
+export const tokenKey = (t) => t.trim().toUpperCase().replace(/[^A-Z0-9]/g, '');
+export const proofText = (who, port, tabNonce, relayNonce) => `${who}|${port}|${tabNonce}|${relayNonce}`;
+export const macText = (dir, seq, body) => `${dir}|${seq}|${body}`;
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * import_model_file runs in the relay: it reads the file and sends it as
+ * import_model_part calls { upload, file, size, offset, data (base64) }, then
+ * calls the tab's import_model_file { upload, files: [{ name, size }], name?,
+ * category?, tags? }. The relay lists it only when the tab lists both, and
+ * never lists import_model_part.
+ */
+export const IMPORT_FILE = 'import_model_file';
+export const IMPORT_PART = 'import_model_part';
+/** Largest frame the relay accepts from the tab (screenshots are big). */
+export const MAX_FRAME = 32 * 1024 * 1024;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function isContent(v) {
+    if (!isObj(v))
+        return false;
+    if (v.type === 'text')
+        return typeof v.text === 'string';
+    if (v.type === 'image')
+        return typeof v.data === 'string' && typeof v.mimeType === 'string' && /^image\/(png|jpeg|webp|gif)$/.test(v.mimeType);
+    return false;
+}
+function isTool(v) {
+    return (isObj(v) &&
+        typeof v.name === 'string' &&
+        /^[A-Za-z0-9_-]{1,64}$/.test(v.name) &&
+        (v.description === undefined || typeof v.description === 'string') &&
+        isObj(v.inputSchema) &&
+        v.inputSchema.type === 'object');
+}
+/** A frame from the tab, checked; null when it is not one. */
+export function parseTabMessage(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isObj(v))
+        return null;
+    switch (v.type) {
+        case 'hello':
+            if (typeof v.protocol !== 'number')
+                return null;
+            // Another protocol version gets a clear refusal, whatever else it sent.
+            if (v.protocol !== PROTOCOL)
+                return { type: 'hello', protocol: v.protocol, mode: 'token', port: 0, nonce: '' };
+            return (v.mode === 'token' || v.mode === 'resume') && Number.isInteger(v.port) && typeof v.nonce === 'string' && HEX64.test(v.nonce)
+                ? { type: 'hello', protocol: v.protocol, mode: v.mode, port: v.port, nonce: v.nonce }
+                : null;
+        case 'sealed':
+            return Number.isInteger(v.seq) && v.seq >= 0 && typeof v.body === 'string' && typeof v.mac === 'string' && HEX64.test(v.mac)
+                ? { type: 'sealed', seq: v.seq, body: v.body, mac: v.mac }
+                : null;
+        case 'prove':
+            return typeof v.proof === 'string' && HEX64.test(v.proof) ? { type: 'prove', proof: v.proof } : null;
+        case 'tools':
+            return Array.isArray(v.tools) && v.tools.length <= 500 && v.tools.every(isTool) ? { type: 'tools', tools: v.tools } : null;
+        case 'result':
+            return Number.isInteger(v.id) && Array.isArray(v.content) && v.content.every(isContent)
+                ? { type: 'result', id: v.id, content: v.content, isError: v.isError === true }
+                : null;
+        case 'ping':
+        case 'pong':
+            return { type: v.type };
+        default:
+            return null;
+    }
+}

package/dist/relay.d.ts

@@ -0,0 +1,96 @@
+import { type Content, type ToolInfo } from './protocol.js';
+export declare const hmac: (key: string, text: string) => string;
+export declare const DEFAULT_PORT = 3021;
+export declare const DEFAULT_ORIGINS: string[];
+/** A handshake must finish within this time. */
+export declare const HANDSHAKE_MS = 30000;
+/** Longest a tool call may take (wait_for_comments waits up to 10 min). */
+export declare const CALL_TIMEOUT_MS: number;
+/** Wrong proofs before the token is replaced; replaced at most once per ROTATE_MS. */
+export declare const MAX_WRONG = 5;
+export declare const ROTATE_MS = 60000;
+/** Failed or unfinished handshakes a minute before token hellos are slowed down. */
+export declare const FREE_STRIKES_PER_MIN = 30;
+/** Delay per strike past the free ones, and its cap. */
+export declare const STRIKE_DELAY_MS = 250;
+export declare const MAX_DELAY_MS = 5000;
+/** The one string the person pastes into the Studio: port and token. */
+export declare const pairingString: (port: number, token: string) => string;
+/** A 26-character base32 token (130 random bits), grouped for pasting: XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX. */
+export declare function newToken(): string;
+export type RelayStatus = {
+    state: 'waiting';
+    pairing: string;
+    token: string;
+    port: number;
+} | {
+    state: 'connected';
+    origin: string;
+    tools: number;
+    port: number;
+};
+export interface RelayOptions {
+    /** A fixed port (fails when busy). Without it: DEFAULT_PORT, else any free port. */
+    port?: number;
+    origins?: string[];
+    /** Where messages for the person go (stderr in the CLI; stdout belongs to MCP). */
+    log?: (line: string) => void;
+    onToolsChanged?: () => void;
+}
+export declare class Relay {
+    private fixedPort;
+    /** The port it listens on (known once started). */
+    port: number;
+    readonly origins: string[];
+    private wss;
+    private token;
+    private resume;
+    private tab;
+    private wrong;
+    private lastRotate;
+    /** When failed or unfinished token handshakes ended (last minute). */
+    private strikes;
+    private toolList;
+    private nextId;
+    private pending;
+    private log;
+    private onToolsChanged;
+    constructor(opts?: RelayOptions);
+    get pairingToken(): string;
+    /** What the person pastes: "port:TOKEN". */
+    get pairing(): string;
+    get tools(): ToolInfo[];
+    status(): RelayStatus;
+    /** Starts listening on 127.0.0.1: the fixed port, else DEFAULT_PORT, else any free port (said on the log). */
+    start(): Promise<void>;
+    private listen;
+    stop(): Promise<void>;
+    /** Runs a tool in the tab. Never throws: errors come back as isError content. */
+    call(name: string, args: Record<string, unknown>): Promise<{
+        content: Content[];
+        isError: boolean;
+    }>;
+    /** Whether the tab takes model files (it lists both import tools). */
+    get canImport(): boolean;
+    /**
+     * import_model_file: reads the model here (modelFile.ts checks), sends it to
+     * the tab in CHUNK_BYTES parts (one import_model_part call each, in order,
+     * each answered before the next), then asks the tab to import it.
+     */
+    importModelFile(args: Record<string, unknown>): Promise<{
+        content: Content[];
+        isError: boolean;
+    }>;
+    private allowed;
+    private announce;
+    private accept;
+    /** How long a token hello waits: 0 up to FREE_STRIKES_PER_MIN strikes in the last minute, then growing to MAX_DELAY_MS. */
+    delay(now?: number): number;
+    /** A wrong token proof: counted; MAX_WRONG of them replace the token, at most once per ROTATE_MS. */
+    private wrongProof;
+    private failAll;
+    /** Before pairing: challenge and refused only. */
+    private sendPlain;
+    /** To the paired tab: sealed with the session key and the next sequence number. */
+    private send;
+}