@iflow-mcp/jkheadley-instar 0.26.2

package/dist/threadline/client/RelayClient.js

@@ -0,0 +1,249 @@
+/**
+ * RelayClient — WebSocket client for connecting to the Threadline relay.
+ *
+ * Handles authentication, reconnection, heartbeat, and message routing.
+ * Part of Threadline Relay Phase 1.
+ */
+import { WebSocket } from 'ws';
+import { EventEmitter } from 'node:events';
+import { sign } from '../ThreadlineCrypto.js';
+export class RelayClient extends EventEmitter {
+    config;
+    identity;
+    socket = null;
+    state = 'disconnected';
+    sessionId = null;
+    reconnectAttempt = 0;
+    reconnectTimer = null;
+    shouldReconnect = true;
+    heartbeatInterval = null;
+    constructor(config, identity) {
+        super();
+        this.config = {
+            relayUrl: config.relayUrl,
+            name: config.name,
+            framework: config.framework ?? 'unknown',
+            capabilities: config.capabilities ?? [],
+            version: config.version ?? '1.0.0',
+            visibility: config.visibility ?? 'unlisted',
+            reconnectInitialMs: config.reconnectInitialMs ?? 1000,
+            reconnectMaxMs: config.reconnectMaxMs ?? 60000,
+            reconnectJitter: config.reconnectJitter ?? 0.25,
+            stateDir: config.stateDir ?? '.',
+        };
+        this.identity = identity;
+    }
+    /**
+     * Connect to the relay server.
+     */
+    async connect() {
+        if (this.state === 'connected')
+            return this.sessionId;
+        if (this.state === 'connecting' || this.state === 'authenticating') {
+            throw new Error('Already connecting');
+        }
+        this.shouldReconnect = true;
+        return this.doConnect();
+    }
+    /**
+     * Disconnect from the relay server.
+     */
+    disconnect() {
+        this.shouldReconnect = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.socket) {
+            this.socket.close(1000, 'Client disconnect');
+            this.socket = null;
+        }
+        this.state = 'disconnected';
+        this.sessionId = null;
+    }
+    /**
+     * Send a message envelope to the relay.
+     */
+    sendMessage(envelope) {
+        if (this.state !== 'connected' || !this.socket) {
+            throw new Error('Not connected to relay');
+        }
+        this.socket.send(JSON.stringify({ type: 'message', envelope }));
+    }
+    /**
+     * Send an ack for a received message.
+     */
+    sendAck(messageId, status = 'delivered') {
+        if (this.state !== 'connected' || !this.socket)
+            return;
+        this.socket.send(JSON.stringify({ type: 'ack', messageId, status }));
+    }
+    /**
+     * Discover agents on the relay.
+     */
+    discover(filter) {
+        if (this.state !== 'connected' || !this.socket) {
+            throw new Error('Not connected to relay');
+        }
+        this.socket.send(JSON.stringify({ type: 'discover', filter }));
+    }
+    /**
+     * Subscribe to presence changes.
+     */
+    subscribe(agentIds) {
+        if (this.state !== 'connected' || !this.socket) {
+            throw new Error('Not connected to relay');
+        }
+        this.socket.send(JSON.stringify({ type: 'subscribe', agentIds }));
+    }
+    /**
+     * Get current connection state.
+     */
+    get connectionState() {
+        return this.state;
+    }
+    /**
+     * Get the relay session ID.
+     */
+    get relaySessionId() {
+        return this.sessionId;
+    }
+    /**
+     * Get the agent's fingerprint.
+     */
+    get fingerprint() {
+        return this.identity.fingerprint;
+    }
+    // ── Private ─────────────────────────────────────────────────────
+    doConnect() {
+        return new Promise((resolve, reject) => {
+            this.state = 'connecting';
+            try {
+                this.socket = new WebSocket(this.config.relayUrl);
+            }
+            catch (err) {
+                this.state = 'disconnected';
+                reject(err);
+                return;
+            }
+            const connectTimeout = setTimeout(() => {
+                if (this.state !== 'connected') {
+                    this.socket?.close();
+                    reject(new Error('Connection timeout'));
+                }
+            }, 30_000);
+            this.socket.on('open', () => {
+                this.state = 'authenticating';
+                this.reconnectAttempt = 0;
+            });
+            this.socket.on('message', (data) => {
+                let frame;
+                try {
+                    frame = JSON.parse(data.toString());
+                }
+                catch {
+                    return;
+                }
+                switch (frame.type) {
+                    case 'challenge':
+                        this.handleChallenge(frame.nonce);
+                        break;
+                    case 'auth_ok':
+                        clearTimeout(connectTimeout);
+                        this.state = 'connected';
+                        this.sessionId = frame.sessionId;
+                        this.heartbeatInterval = frame.heartbeatInterval;
+                        this.emit('connected', frame.sessionId);
+                        resolve(frame.sessionId);
+                        break;
+                    case 'auth_error':
+                        clearTimeout(connectTimeout);
+                        this.state = 'disconnected';
+                        // If rate-limited, enforce longer backoff before retrying
+                        if (frame.message?.includes('Too many') || frame.message?.includes('rate')) {
+                            this.reconnectAttempt = Math.max(this.reconnectAttempt, 5); // Start at ~32s backoff
+                        }
+                        reject(new Error(`Auth failed: ${frame.message}`));
+                        break;
+                    case 'message':
+                        this.emit('message', frame.envelope);
+                        break;
+                    case 'ack':
+                        this.emit('ack', frame);
+                        break;
+                    case 'ping':
+                        this.socket?.send(JSON.stringify({
+                            type: 'pong',
+                            timestamp: new Date().toISOString(),
+                        }));
+                        break;
+                    case 'error':
+                        this.emit('error', frame);
+                        break;
+                    case 'discover_result':
+                        this.emit('discover-result', frame);
+                        break;
+                    case 'presence_change':
+                        this.emit('presence-change', frame);
+                        break;
+                    case 'displaced':
+                        this.shouldReconnect = false;
+                        this.emit('displaced', frame.reason);
+                        break;
+                }
+            });
+            this.socket.on('close', (code, reason) => {
+                clearTimeout(connectTimeout);
+                const wasConnected = this.state === 'connected';
+                this.state = 'disconnected';
+                this.sessionId = null;
+                if (wasConnected) {
+                    this.emit('disconnected', reason?.toString() ?? `Code: ${code}`);
+                }
+                if (this.shouldReconnect) {
+                    this.scheduleReconnect();
+                }
+            });
+            this.socket.on('error', (err) => {
+                // Error is usually followed by close, so we handle reconnection there
+                if (this.state === 'connecting') {
+                    clearTimeout(connectTimeout);
+                    this.state = 'disconnected';
+                    reject(err);
+                }
+            });
+        });
+    }
+    handleChallenge(nonce) {
+        const nonceBuffer = Buffer.from(nonce, 'utf-8');
+        const signature = sign(this.identity.privateKey, nonceBuffer);
+        this.socket?.send(JSON.stringify({
+            type: 'auth',
+            agentId: this.identity.fingerprint,
+            publicKey: this.identity.publicKey.toString('base64'),
+            signature: signature.toString('base64'),
+            metadata: {
+                name: this.config.name,
+                framework: this.config.framework,
+                capabilities: this.config.capabilities,
+                version: this.config.version,
+            },
+            visibility: this.config.visibility,
+        }));
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const base = Math.min(this.config.reconnectInitialMs * Math.pow(2, this.reconnectAttempt), this.config.reconnectMaxMs);
+        const jitter = base * this.config.reconnectJitter * (Math.random() * 2 - 1);
+        const delay = Math.max(100, base + jitter);
+        this.reconnectAttempt++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.doConnect().catch(() => {
+                // Will trigger another reconnect via close handler
+            });
+        }, delay);
+    }
+}
+//# sourceMappingURL=RelayClient.js.map

package/dist/threadline/client/RelayClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelayClient.js","sourceRoot":"","sources":["../../../src/threadline/client/RelayClient.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC/B,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AA0B9C,MAAM,OAAO,WAAY,SAAQ,YAAY;IAC1B,MAAM,CAA8B;IACpC,QAAQ,CAAe;IAChC,MAAM,GAAqB,IAAI,CAAC;IAChC,KAAK,GAAoB,cAAc,CAAC;IACxC,SAAS,GAAkB,IAAI,CAAC;IAChC,gBAAgB,GAAG,CAAC,CAAC;IACrB,cAAc,GAAyC,IAAI,CAAC;IAC5D,eAAe,GAAG,IAAI,CAAC;IACvB,iBAAiB,GAAkB,IAAI,CAAC;IAEhD,YAAY,MAAyB,EAAE,QAAsB;QAC3D,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,MAAM,GAAG;YACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,SAAS;YACxC,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,EAAE;YACvC,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,OAAO;YAClC,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,UAAU;YAC3C,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI,IAAI;YACrD,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,KAAK;YAC9C,eAAe,EAAE,MAAM,CAAC,eAAe,IAAI,IAAI;YAC/C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,GAAG;SACjC,CAAC;QACF,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW;YAAE,OAAO,IAAI,CAAC,SAAU,CAAC;QACvD,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,IAAI,IAAI,CAAC,KAAK,KAAK,gBAAgB,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;QACxC,CAAC;QAED,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;QAC7B,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACxB,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAClC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;YAC7C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,cAAc,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAyB;QACnC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAClE,CAAC;IAED;;OAEG;IACH,OAAO,CAAC,SAAiB,EAAE,SAAsB,WAAW;QAC1D,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAO;QACvD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACvE,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,MAAmE;QAC1E,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,QAA6B;QACrC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACpE,CAAC;IAED;;OAEG;IACH,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED;;OAEG;IACH,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED;;OAEG;IACH,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC;IACnC,CAAC;IAED,mEAAmE;IAE3D,SAAS;QACf,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,CAAC,KAAK,GAAG,YAAY,CAAC;YAE1B,IAAI,CAAC;gBACH,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YACpD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,KAAK,GAAG,cAAc,CAAC;gBAC5B,MAAM,CAAC,GAAG,CAAC,CAAC;gBACZ,OAAO;YACT,CAAC;YAED,MAAM,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;gBACrC,IAAI,IAAI,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;oBAC/B,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;oBACrB,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC;gBAC1C,CAAC;YACH,CAAC,EAAE,MAAM,CAAC,CAAC;YAEX,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;gBAC1B,IAAI,CAAC,KAAK,GAAG,gBAAgB,CAAC;gBAC9B,IAAI,CAAC,gBAAgB,GAAG,CAAC,CAAC;YAC5B,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;gBACjC,IAAI,KAAkB,CAAC;gBACvB,IAAI,CAAC;oBACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACtC,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO;gBACT,CAAC;gBAED,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;oBACnB,KAAK,WAAW;wBACd,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;wBAClC,MAAM;oBAER,KAAK,SAAS;wBACZ,YAAY,CAAC,cAAc,CAAC,CAAC;wBAC7B,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC;wBACzB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;wBACjC,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,iBAAiB,CAAC;wBACjD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;wBACxC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;wBACzB,MAAM;oBAER,KAAK,YAAY;wBACf,YAAY,CAAC,cAAc,CAAC,CAAC;wBAC7B,IAAI,CAAC,KAAK,GAAG,cAAc,CAAC;wBAC5B,0DAA0D;wBAC1D,IAAI,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;4BAC3E,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,CAAC,wBAAwB;wBACtF,CAAC;wBACD,MAAM,CAAC,IAAI,KAAK,CAAC,gBAAgB,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;wBACnD,MAAM;oBAER,KAAK,SAAS;wBACZ,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;wBACrC,MAAM;oBAER,KAAK,KAAK;wBACR,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;wBACxB,MAAM;oBAER,KAAK,MAAM;wBACT,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;4BAC/B,IAAI,EAAE,MAAM;4BACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;yBACpC,CAAC,CAAC,CAAC;wBACJ,MAAM;oBAER,KAAK,OAAO;wBACV,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;wBAC1B,MAAM;oBAER,KAAK,iBAAiB;wBACpB,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;wBACpC,MAAM;oBAER,KAAK,iBAAiB;wBACpB,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE,KAAK,CAAC,CAAC;wBACpC,MAAM;oBAER,KAAK,WAAW;wBACd,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC;wBAC7B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;wBACrC,MAAM;gBACV,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;gBACvC,YAAY,CAAC,cAAc,CAAC,CAAC;gBAC7B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,KAAK,WAAW,CAAC;gBAChD,IAAI,CAAC,KAAK,GAAG,cAAc,CAAC;gBAC5B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;gBAEtB,IAAI,YAAY,EAAE,CAAC;oBACjB,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,SAAS,IAAI,EAAE,CAAC,CAAC;gBACnE,CAAC;gBAED,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;oBACzB,IAAI,CAAC,iBAAiB,EAAE,CAAC;gBAC3B,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;gBAC9B,sEAAsE;gBACtE,IAAI,IAAI,CAAC,KAAK,KAAK,YAAY,EAAE,CAAC;oBAChC,YAAY,CAAC,cAAc,CAAC,CAAC;oBAC7B,IAAI,CAAC,KAAK,GAAG,cAAc,CAAC;oBAC5B,MAAM,CAAC,GAAG,CAAC,CAAC;gBACd,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,eAAe,CAAC,KAAa;QACnC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC;QAE9D,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;YAC/B,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,WAAW;YAClC,SAAS,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACrD,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACvC,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI;gBACtB,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;gBAChC,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;gBACtC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;aAC7B;YACD,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;SACnC,CAAC,CAAC,CAAC;IACN,CAAC;IAEO,iBAAiB;QACvB,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO;QAEhC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CACnB,IAAI,CAAC,MAAM,CAAC,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,gBAAgB,CAAC,EACnE,IAAI,CAAC,MAAM,CAAC,cAAc,CAC3B,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,eAAe,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC;QAE3C,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACxB,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE;YACpC,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;YAC3B,IAAI,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBAC1B,mDAAmD;YACrD,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;CACF"}

package/dist/threadline/client/ThreadlineClient.d.ts

@@ -0,0 +1,117 @@
+/**
+ * ThreadlineClient — Unified API for Threadline relay communication.
+ *
+ * The high-level client that agent developers use. Wraps RelayClient,
+ * MessageEncryptor, and IdentityManager into a simple interface.
+ *
+ * Part of Threadline Relay Phase 1.
+ */
+import { EventEmitter } from 'node:events';
+import type { AgentFingerprint, MessageEnvelope } from '../relay/types.js';
+import { type PlaintextMessage } from './MessageEncryptor.js';
+export interface ThreadlineClientConfig {
+    name: string;
+    relayUrl?: string;
+    framework?: string;
+    capabilities?: string[];
+    version?: string;
+    visibility?: 'public' | 'unlisted' | 'private';
+    stateDir?: string;
+}
+export interface KnownAgent {
+    agentId: AgentFingerprint;
+    name: string;
+    publicKey: Buffer;
+    x25519PublicKey: Buffer;
+    framework?: string;
+    capabilities?: string[];
+    lastSeen?: string;
+}
+export interface ReceivedMessage {
+    from: AgentFingerprint;
+    fromName?: string;
+    threadId: string;
+    messageId: string;
+    content: PlaintextMessage;
+    timestamp: string;
+    envelope: MessageEnvelope;
+}
+export declare class ThreadlineClient extends EventEmitter {
+    private readonly config;
+    private readonly identityManager;
+    private encryptor;
+    private relayClient;
+    private identity;
+    private readonly knownAgents;
+    constructor(config: ThreadlineClientConfig);
+    /**
+     * Connect to the relay and start communicating.
+     */
+    connect(): Promise<string>;
+    /**
+     * Auto-discover all agents on the relay after connecting.
+     * Populates knownAgents cache so name-based sends work immediately.
+     */
+    private autoDiscover;
+    /**
+     * Send a message to another agent.
+     */
+    send(recipientId: AgentFingerprint, content: string | PlaintextMessage, threadId?: string): string;
+    /**
+     * Send a plaintext message to another agent via the relay.
+     * Unlike send(), this does NOT require the recipient to be in knownAgents
+     * and does NOT use E2E encryption. The relay provides transport-level
+     * security (TLS + Ed25519 auth). Use this for replying to unknown senders
+     * who contacted us through the relay.
+     */
+    sendPlaintext(recipientId: AgentFingerprint, content: string, threadId?: string): string;
+    /**
+     * Send a message — tries E2E encrypted first, falls back to plaintext.
+     * This is the recommended send method for the relay-send endpoint.
+     */
+    sendAuto(recipientId: AgentFingerprint, content: string, threadId?: string): string;
+    /**
+     * Discover agents on the relay.
+     */
+    discover(filter?: {
+        capability?: string;
+        framework?: string;
+        name?: string;
+    }): Promise<KnownAgent[]>;
+    /**
+     * Resolve an agent name or fingerprint to a fingerprint.
+     * Tries: exact fingerprint match → name match in cache → re-discover → name match.
+     * Returns null if not found.
+     */
+    resolveAgent(nameOrId: string): Promise<AgentFingerprint | null>;
+    /**
+     * Find an agent by name (case-insensitive, partial match).
+     */
+    private findAgentByName;
+    /**
+     * Register a known agent (for direct messaging without discovery).
+     */
+    registerAgent(agent: KnownAgent): void;
+    /**
+     * Disconnect from the relay.
+     */
+    disconnect(): void;
+    /**
+     * Get the agent's fingerprint.
+     */
+    get fingerprint(): AgentFingerprint | null;
+    /**
+     * Get the agent's public key.
+     */
+    get publicKey(): Buffer | null;
+    /**
+     * Get connection state.
+     */
+    get connectionState(): string;
+    /**
+     * Get all known agents.
+     */
+    getKnownAgents(): KnownAgent[];
+    private handleIncomingMessage;
+}
+//# sourceMappingURL=ThreadlineClient.d.ts.map

package/dist/threadline/client/ThreadlineClient.d.ts.map

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

package/dist/threadline/client/ThreadlineClient.js

@@ -0,0 +1,286 @@
+/**
+ * ThreadlineClient — Unified API for Threadline relay communication.
+ *
+ * The high-level client that agent developers use. Wraps RelayClient,
+ * MessageEncryptor, and IdentityManager into a simple interface.
+ *
+ * Part of Threadline Relay Phase 1.
+ */
+import { EventEmitter } from 'node:events';
+import { IdentityManager } from './IdentityManager.js';
+import { MessageEncryptor } from './MessageEncryptor.js';
+import { RelayClient } from './RelayClient.js';
+const DEFAULT_RELAY_URL = 'wss://relay.threadline.dev/v1/connect';
+export class ThreadlineClient extends EventEmitter {
+    config;
+    identityManager;
+    encryptor = null;
+    relayClient = null;
+    identity = null;
+    knownAgents = new Map();
+    constructor(config) {
+        super();
+        this.config = config;
+        this.identityManager = new IdentityManager(config.stateDir ?? '.');
+    }
+    /**
+     * Connect to the relay and start communicating.
+     */
+    async connect() {
+        // 1. Get or create identity
+        this.identity = this.identityManager.getOrCreate();
+        this.encryptor = new MessageEncryptor(this.identity.privateKey, this.identity.publicKey);
+        // 2. Create relay client
+        const relayConfig = {
+            relayUrl: this.config.relayUrl ?? DEFAULT_RELAY_URL,
+            name: this.config.name,
+            framework: this.config.framework,
+            capabilities: this.config.capabilities,
+            version: this.config.version,
+            visibility: this.config.visibility,
+            stateDir: this.config.stateDir,
+        };
+        this.relayClient = new RelayClient(relayConfig, this.identity);
+        // Wire up events
+        this.relayClient.on('message', (envelope) => {
+            this.handleIncomingMessage(envelope);
+        });
+        this.relayClient.on('connected', (sessionId) => {
+            this.emit('connected', sessionId);
+        });
+        this.relayClient.on('disconnected', (reason) => {
+            this.emit('disconnected', reason);
+        });
+        this.relayClient.on('displaced', (reason) => {
+            this.emit('displaced', reason);
+        });
+        this.relayClient.on('error', (err) => {
+            this.emit('error', err);
+        });
+        this.relayClient.on('discover-result', (result) => {
+            // Update known agents
+            for (const agent of result.agents) {
+                this.knownAgents.set(agent.agentId, agent);
+            }
+            this.emit('discover-result', result);
+        });
+        this.relayClient.on('presence-change', (change) => {
+            this.emit('presence-change', change);
+        });
+        // 3. Connect
+        const sessionId = await this.relayClient.connect();
+        // 4. Auto-discover agents on the relay (non-blocking)
+        this.autoDiscover().catch(() => {
+            // Non-fatal — agent can still send to known fingerprints
+        });
+        return sessionId;
+    }
+    /**
+     * Auto-discover all agents on the relay after connecting.
+     * Populates knownAgents cache so name-based sends work immediately.
+     */
+    async autoDiscover() {
+        try {
+            const agents = await this.discover();
+            if (agents.length > 0) {
+                // Emit for logging
+                this.emit('auto-discovered', { count: agents.length });
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    /**
+     * Send a message to another agent.
+     */
+    send(recipientId, content, threadId) {
+        if (!this.encryptor || !this.relayClient) {
+            throw new Error('Not connected');
+        }
+        // Look up recipient's keys
+        const known = this.knownAgents.get(recipientId);
+        if (!known?.publicKey || !known?.x25519PublicKey) {
+            throw new Error(`Unknown agent: ${recipientId}. Run discover() first.`);
+        }
+        const message = typeof content === 'string'
+            ? { content }
+            : content;
+        const tId = threadId ?? `thread-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const envelope = this.encryptor.encrypt(known.publicKey, known.x25519PublicKey, tId, message);
+        this.relayClient.sendMessage(envelope);
+        return envelope.messageId;
+    }
+    /**
+     * Send a plaintext message to another agent via the relay.
+     * Unlike send(), this does NOT require the recipient to be in knownAgents
+     * and does NOT use E2E encryption. The relay provides transport-level
+     * security (TLS + Ed25519 auth). Use this for replying to unknown senders
+     * who contacted us through the relay.
+     */
+    sendPlaintext(recipientId, content, threadId) {
+        if (!this.relayClient || !this.identity) {
+            throw new Error('Not connected');
+        }
+        const tId = threadId ?? `thread-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const messageId = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        // Encode as base64 JSON payload (same format as inbound unknown-sender messages)
+        const payload = Buffer.from(JSON.stringify({
+            text: content,
+            type: 'chat',
+        })).toString('base64');
+        // Send as a raw envelope through the relay
+        const envelope = {
+            from: this.identity.fingerprint,
+            to: recipientId,
+            threadId: tId,
+            messageId,
+            payload,
+            timestamp: new Date().toISOString(),
+        };
+        this.relayClient.sendMessage(envelope);
+        return messageId;
+    }
+    /**
+     * Send a message — tries E2E encrypted first, falls back to plaintext.
+     * This is the recommended send method for the relay-send endpoint.
+     */
+    sendAuto(recipientId, content, threadId) {
+        // If we know the agent's keys, use encrypted send
+        const known = this.knownAgents.get(recipientId);
+        if (known?.publicKey && known?.x25519PublicKey) {
+            return this.send(recipientId, content, threadId);
+        }
+        // Otherwise, use plaintext relay send
+        return this.sendPlaintext(recipientId, content, threadId);
+    }
+    /**
+     * Discover agents on the relay.
+     */
+    async discover(filter) {
+        if (!this.relayClient)
+            throw new Error('Not connected');
+        return new Promise((resolve) => {
+            const handler = (result) => {
+                this.relayClient.removeListener('discover-result', handler);
+                resolve(result.agents);
+            };
+            this.relayClient.on('discover-result', handler);
+            this.relayClient.discover(filter);
+            // Timeout after 10 seconds
+            setTimeout(() => {
+                this.relayClient?.removeListener('discover-result', handler);
+                resolve([]);
+            }, 10_000);
+        });
+    }
+    /**
+     * Resolve an agent name or fingerprint to a fingerprint.
+     * Tries: exact fingerprint match → name match in cache → re-discover → name match.
+     * Returns null if not found.
+     */
+    async resolveAgent(nameOrId) {
+        // 1. Exact fingerprint match (hex string, typically 32 chars)
+        if (this.knownAgents.has(nameOrId)) {
+            return nameOrId;
+        }
+        // 2. Name match in cache (case-insensitive)
+        const byName = this.findAgentByName(nameOrId);
+        if (byName)
+            return byName.agentId;
+        // 3. Re-discover and try again
+        if (this.relayClient) {
+            await this.autoDiscover();
+            const byNameRetry = this.findAgentByName(nameOrId);
+            if (byNameRetry)
+                return byNameRetry.agentId;
+        }
+        return null;
+    }
+    /**
+     * Find an agent by name (case-insensitive, partial match).
+     */
+    findAgentByName(name) {
+        const lower = name.toLowerCase();
+        // Exact name match first
+        for (const agent of this.knownAgents.values()) {
+            if (agent.name.toLowerCase() === lower)
+                return agent;
+        }
+        // Partial match (contains)
+        for (const agent of this.knownAgents.values()) {
+            if (agent.name.toLowerCase().includes(lower))
+                return agent;
+        }
+        return undefined;
+    }
+    /**
+     * Register a known agent (for direct messaging without discovery).
+     */
+    registerAgent(agent) {
+        this.knownAgents.set(agent.agentId, agent);
+    }
+    /**
+     * Disconnect from the relay.
+     */
+    disconnect() {
+        this.relayClient?.disconnect();
+        this.relayClient = null;
+        this.encryptor = null;
+    }
+    /**
+     * Get the agent's fingerprint.
+     */
+    get fingerprint() {
+        return this.identity?.fingerprint ?? null;
+    }
+    /**
+     * Get the agent's public key.
+     */
+    get publicKey() {
+        return this.identity?.publicKey ?? null;
+    }
+    /**
+     * Get connection state.
+     */
+    get connectionState() {
+        return this.relayClient?.connectionState ?? 'disconnected';
+    }
+    /**
+     * Get all known agents.
+     */
+    getKnownAgents() {
+        return [...this.knownAgents.values()];
+    }
+    // ── Private ─────────────────────────────────────────────────────
+    handleIncomingMessage(envelope) {
+        if (!this.encryptor)
+            return;
+        // Look up sender's public key
+        const sender = this.knownAgents.get(envelope.from);
+        if (!sender?.publicKey || !sender?.x25519PublicKey) {
+            // Unknown sender — we can't decrypt without their keys
+            this.emit('unknown-sender', envelope);
+            return;
+        }
+        try {
+            const plaintext = this.encryptor.decrypt(envelope, sender.publicKey, sender.x25519PublicKey);
+            const received = {
+                from: envelope.from,
+                fromName: sender.name,
+                threadId: envelope.threadId,
+                messageId: envelope.messageId,
+                content: plaintext,
+                timestamp: envelope.timestamp,
+                envelope,
+            };
+            this.emit('message', received);
+            // Send delivery ack
+            this.relayClient?.sendAck(envelope.messageId);
+        }
+        catch (err) {
+            this.emit('decrypt-error', { envelope, error: err });
+        }
+    }
+}
+//# sourceMappingURL=ThreadlineClient.js.map