agent-relay 1.3.2 → 1.5.0

package/dist/wrapper/client.js

@@ -82,6 +82,14 @@ export class RelayClient {
      * @param originalTo - Original 'to' field from sender (e.g., '*' for broadcasts)
      */
     onMessage;
+    /**
+     * Callback for channel messages.
+     * @param from - Sender name
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param envelope - Full envelope for additional data
+     */
+    onChannelMessage;
     onStateChange;
     onError;
     constructor(config = {}) {
@@ -217,6 +225,120 @@ export class RelayClient {
     broadcast(body, kind = 'message', data) {
         return this.sendMessage('*', body, kind, data);
     }
+    // =============================================================================
+    // Channel Operations
+    // =============================================================================
+    /**
+     * Join a channel.
+     * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
+     * @param displayName - Optional display name for this member
+     */
+    joinChannel(channel, displayName) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'CHANNEL_JOIN',
+            id: generateId(),
+            ts: Date.now(),
+            payload: {
+                channel,
+                displayName,
+            },
+        };
+        return this.send(envelope);
+    }
+    /**
+     * Admin join: Add any member to a channel (does not require member to be connected).
+     * Used by dashboard to sync channel memberships for agents.
+     * @param channel - Channel name (e.g., '#general')
+     * @param member - Name of the member to add
+     */
+    adminJoinChannel(channel, member) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'CHANNEL_JOIN',
+            id: generateId(),
+            ts: Date.now(),
+            payload: {
+                channel,
+                member, // Admin mode: specify member to add
+            },
+        };
+        return this.send(envelope);
+    }
+    /**
+     * Leave a channel.
+     * @param channel - Channel name to leave
+     * @param reason - Optional reason for leaving
+     */
+    leaveChannel(channel, reason) {
+        if (this._state !== 'READY')
+            return false;
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'CHANNEL_LEAVE',
+            id: generateId(),
+            ts: Date.now(),
+            payload: {
+                channel,
+                reason,
+            },
+        };
+        return this.send(envelope);
+    }
+    /**
+     * Admin remove: Remove any member from a channel (does not require member to be connected).
+     * Used by dashboard to remove channel members.
+     * @param channel - Channel name (e.g., '#general')
+     * @param member - Name of the member to remove
+     */
+    adminRemoveMember(channel, member) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'CHANNEL_LEAVE',
+            id: generateId(),
+            ts: Date.now(),
+            payload: {
+                channel,
+                member, // Admin mode: specify member to remove
+            },
+        };
+        return this.send(envelope);
+    }
+    /**
+     * Send a message to a channel.
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param options - Optional thread, mentions, attachments
+     */
+    sendChannelMessage(channel, body, options) {
+        if (this._state !== 'READY') {
+            return false;
+        }
+        const envelope = {
+            v: PROTOCOL_VERSION,
+            type: 'CHANNEL_MESSAGE',
+            id: generateId(),
+            ts: Date.now(),
+            payload: {
+                channel,
+                body,
+                thread: options?.thread,
+                mentions: options?.mentions,
+                attachments: options?.attachments,
+                data: options?.data,
+            },
+        };
+        return this.send(envelope);
+    }
     /**
      * Subscribe to a topic.
      */
@@ -395,6 +517,9 @@ export class RelayClient {
             case 'DELIVER':
                 this.handleDeliver(envelope);
                 break;
+            case 'CHANNEL_MESSAGE':
+                this.handleChannelMessage(envelope);
+                break;
             case 'PING':
                 this.handlePing(envelope);
                 break;
@@ -417,6 +542,7 @@ export class RelayClient {
         }
     }
     handleDeliver(envelope) {
+        console.log(`[relay-client:${this.config.agentName}] Received DELIVER from ${envelope.from}: "${envelope.payload.body?.substring(0, 40)}..."`);
         // Send ACK
         this.send({
             v: PROTOCOL_VERSION,
@@ -430,6 +556,7 @@ export class RelayClient {
         });
         const duplicate = this.markDelivered(envelope.id);
         if (duplicate) {
+            console.log(`[relay-client:${this.config.agentName}] Duplicate delivery, skipping`);
             return;
         }
         // Notify handler
@@ -437,6 +564,46 @@ export class RelayClient {
         if (this.onMessage && envelope.from) {
             this.onMessage(envelope.from, envelope.payload, envelope.id, envelope.payload_meta, envelope.delivery.originalTo);
         }
+        else {
+            console.log(`[relay-client:${this.config.agentName}] No onMessage handler or no from field`);
+        }
+    }
+    handleChannelMessage(envelope) {
+        if (!this.config.quiet) {
+            console.log(`[client] handleChannelMessage: from=${envelope.from}, channel=${envelope.payload.channel}`);
+        }
+        const duplicate = this.markDelivered(envelope.id);
+        if (duplicate) {
+            if (!this.config.quiet) {
+                console.log(`[client] handleChannelMessage: duplicate message ${envelope.id}, skipping`);
+            }
+            return;
+        }
+        // Notify channel message handler
+        if (this.onChannelMessage && envelope.from) {
+            if (!this.config.quiet) {
+                console.log(`[client] Calling onChannelMessage callback`);
+            }
+            this.onChannelMessage(envelope.from, envelope.payload.channel, envelope.payload.body, envelope);
+        }
+        else if (!this.config.quiet) {
+            console.log(`[client] No onChannelMessage handler set (handler=${!!this.onChannelMessage}, from=${envelope.from})`);
+        }
+        // Also call onMessage for backwards compatibility
+        // Convert to SendPayload format (channel is passed as 5th argument, not in payload)
+        if (this.onMessage && envelope.from) {
+            const sendPayload = {
+                kind: 'message',
+                body: envelope.payload.body,
+                data: {
+                    _isChannelMessage: true,
+                    _channel: envelope.payload.channel,
+                    _mentions: envelope.payload.mentions,
+                },
+                thread: envelope.payload.thread,
+            };
+            this.onMessage(envelope.from, sendPayload, envelope.id, undefined, envelope.payload.channel);
+        }
     }
     handlePing(envelope) {
         this.send({

package/dist/wrapper/parser.d.ts

@@ -137,10 +137,6 @@ export declare class OutputParser {
      */
     reset(): void;
 }
-/**
- * Format a relay command for injection into agent input.
- */
-export declare function formatIncomingMessage(from: string, body: string, kind?: PayloadKind): string;
 /**
  * Parsed message metadata block from agent output.
  */

package/dist/wrapper/parser.js

@@ -49,6 +49,9 @@ const MAX_INLINE_CONTINUATION_LINES = 30;
 // They are handled separately by the wrappers (pty-wrapper.ts, tmux-wrapper.ts)
 const SPAWN_COMMAND_PATTERN = /->relay:spawn\s+\S+/i;
 const RELEASE_COMMAND_PATTERN = /->relay:release\s+\S+/i;
+// JSON relay format: ->relay.json:{...}
+// Simple single-line format that's resilient and won't interfere with normal conversation
+const JSON_RELAY_PATTERN = /->relay\.json:(\{[^\n]+\})/;
 /**
  * Check if a line is a spawn or release command that should be handled
  * by the wrapper's spawn subsystem, not parsed as a relay message.
@@ -653,9 +656,41 @@ export class OutputParser {
         const thinkingBase = this.options.thinkingPrefix.replace(/:$/, '');
         const hasRelayPattern = line.includes(relayBase) || line.includes(thinkingBase);
         const hasBlockPattern = line.includes('[[') || line.includes('```');
-        if (!hasRelayPattern && !hasBlockPattern) {
+        const hasJsonRelay = line.includes('->relay.json:');
+        if (!hasRelayPattern && !hasBlockPattern && !hasJsonRelay) {
             return { command: null, output: line };
         }
+        // Check for JSON relay format first (preferred): ->relay.json:{...}
+        if (hasJsonRelay) {
+            const stripped = stripAnsi(line);
+            const jsonMatch = stripped.match(JSON_RELAY_PATTERN);
+            if (jsonMatch) {
+                try {
+                    const parsed = JSON.parse(jsonMatch[1]);
+                    const kind = parsed.kind || 'message';
+                    // Handle different command kinds
+                    if (kind === 'message' && parsed.to) {
+                        return {
+                            command: {
+                                to: parsed.to,
+                                kind: 'message',
+                                body: parsed.body || '',
+                                thread: parsed.thread,
+                                raw: jsonMatch[0],
+                            },
+                            output: null,
+                        };
+                    }
+                    // spawn/release are handled by the wrapper, not here
+                    // But we still strip the line from output
+                    return { command: null, output: null };
+                }
+                catch {
+                    // Invalid JSON, pass through
+                    console.error('[parser] Invalid JSON in ->relay.json:', jsonMatch[1]);
+                }
+            }
+        }
         // Strip ANSI codes for pattern matching (only when potentially needed)
         const stripped = stripAnsi(line);
         // Handle code fences
@@ -811,12 +846,12 @@ export class OutputParser {
     shouldFilterFencedInline(target, body) {
         // Check for placeholder target names
         if (isPlaceholderTarget(target)) {
-            console.error(`[parser] Filtered message - placeholder target: ${target}`);
+            // Silently filter placeholder targets (common in documentation)
             return true;
         }
         // Check for instructional body content
         if (isInstructionalText(body)) {
-            console.error(`[parser] Filtered message to ${target} - instructional text detected. Body preview: ${body.substring(0, 100)}`);
+            // Silently filter instructional text (common in system prompts)
             return true;
         }
         return false;
@@ -1049,13 +1084,6 @@ export class OutputParser {
         this.fencedInlineKind = 'message';
     }
 }
-/**
- * Format a relay command for injection into agent input.
- */
-export function formatIncomingMessage(from, body, kind = 'message') {
-    const prefix = kind === 'thinking' ? '[THINKING]' : '[MSG]';
-    return `\n${prefix} from ${from}: ${body}\n`;
-}
 /**
  * Parse [[RELAY_METADATA]]...[[/RELAY_METADATA]] blocks from agent output.
  * Agents can output metadata to enhance messages.

package/dist/wrapper/pty-wrapper.d.ts

@@ -230,9 +230,15 @@ export declare class PtyWrapper extends BaseWrapper {
     protected parseSpawnReleaseCommands(content: string): void;
     /**
      * Execute spawn via API or callback.
-     * Overrides BaseWrapper to add PTY-specific logging and API path.
+     * After spawning, waits for the agent to come online and sends the task via relay.
      */
     protected executeSpawn(name: string, cli: string, task: string): Promise<void>;
+    /**
+     * Wait for a spawned agent to come online, then send the task via relay.
+     * Uses the wrapper's own relay client so the message comes "from" this agent,
+     * not from the dashboard's relay client.
+     */
+    private waitAndSendTask;
     /**
      * Execute release via API or callback.
      * Overrides BaseWrapper to add PTY-specific logging and API path.
@@ -243,6 +249,11 @@ export declare class PtyWrapper extends BaseWrapper {
      * Extends BaseWrapper to add PTY-specific behavior.
      */
     protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
+    /**
+     * Handle incoming channel message from relay.
+     * Extends BaseWrapper to add PTY-specific queue processing.
+     */
+    protected handleIncomingChannelMessage(from: string, channel: string, body: string, envelope: import('../protocol/types.js').Envelope<import('../protocol/channels.js').ChannelMessagePayload>): void;
     /**
      * Wait for output to stabilize before injection.
      * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.

package/dist/wrapper/pty-wrapper.js

@@ -134,8 +134,11 @@ export class PtyWrapper extends BaseWrapper {
             }
         }
         // Connect to relay daemon
+        const socketPath = this.config.socketPath ?? 'DEFAULT';
+        console.log(`[pty:${this.config.name}] Connecting to relay daemon at: ${socketPath}`);
         try {
             await this.client.connect();
+            console.log(`[pty:${this.config.name}] Relay connected (state: ${this.client.state})`);
             // If this is a shadow agent, bind to the primary after connecting
             if (this.config.shadowOf) {
                 const speakOn = this.config.shadowSpeakOn ?? ['EXPLICIT_ASK'];
@@ -150,6 +153,7 @@ export class PtyWrapper extends BaseWrapper {
         }
         catch (err) {
             console.error(`[pty:${this.config.name}] Relay connect failed: ${err.message}`);
+            console.error(`[pty:${this.config.name}] Relay client state: ${this.client.state}`);
         }
         // Build command args
         const args = this.config.args ?? [];
@@ -220,6 +224,7 @@ export class PtyWrapper extends BaseWrapper {
                 this.injectInstructions();
             }
             this.readyForMessages = true;
+            console.log(`[pty:${this.config.name}] Agent ready for messages (queueLen=${this.messageQueue.length}, interactive=${this.config.interactive})`);
             // Process any messages that arrived while waiting (skip in interactive mode)
             if (!this.config.interactive) {
                 this.processMessageQueue();
@@ -228,6 +233,7 @@ export class PtyWrapper extends BaseWrapper {
             console.error(`[pty:${this.config.name}] Failed to wait for agent ready:`, err);
             // Fall back to marking ready anyway to avoid blocking forever
             this.readyForMessages = true;
+            console.log(`[pty:${this.config.name}] Agent ready for messages (fallback, queueLen=${this.messageQueue.length})`);
         });
     }
     /**
@@ -608,6 +614,14 @@ export class PtyWrapper extends BaseWrapper {
         // 500 chars is enough to capture most relay message headers
         const lookbackStart = Math.max(0, this.lastParsedLength - 500);
         const contentToParse = cleanContent.substring(lookbackStart);
+        // Debug: Check if content contains relay pattern
+        if (contentToParse.includes('->relay:')) {
+            const relayLines = contentToParse.split('\n').filter(l => l.includes('->relay:'));
+            console.log(`[pty:${this.config.name}] [RELAY-DEBUG] Found ${relayLines.length} lines with ->relay: pattern`);
+            relayLines.slice(0, 3).forEach((line, i) => {
+                console.log(`[pty:${this.config.name}] [RELAY-DEBUG] Line ${i}: "${line.substring(0, 80)}..."`);
+            });
+        }
         // First, try to find fenced multi-line messages: ->relay:Target <<<\n...\n>>>
         this.parseFencedMessages(contentToParse);
         // Then parse single-line messages
@@ -625,9 +639,14 @@ export class PtyWrapper extends BaseWrapper {
         // Thread is optional, can be [thread:id] or [thread:project:id] for cross-project
         const escapedPrefix = this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
         const fenceStartPattern = new RegExp(`${escapedPrefix}(\\S+)(?:\\s+\\[thread:(?:([\\w-]+):)?([\\w-]+)\\])?\\s*<<<`, 'g');
+        // Debug: Log if content contains relay prefix with fenced syntax
+        if (content.includes(this.relayPrefix) && content.includes('<<<')) {
+            console.error(`[pty:${this.config.name}] parseFencedMessages: Found relay+<<< in content`);
+        }
         let match;
         while ((match = fenceStartPattern.exec(content)) !== null) {
             const target = match[1];
+            console.error(`[pty:${this.config.name}] parseFencedMessages: MATCHED target=${target}`);
             const threadProject = match[2]; // Optional: project part of thread
             const threadId = match[3]; // Thread ID
             const startIdx = match.index + match[0].length;
@@ -985,22 +1004,24 @@ export class PtyWrapper extends BaseWrapper {
     }
     /**
      * Execute spawn via API or callback.
-     * Overrides BaseWrapper to add PTY-specific logging and API path.
+     * After spawning, waits for the agent to come online and sends the task via relay.
      */
     async executeSpawn(name, cli, task) {
         console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] executeSpawn called: name=${name}, cli=${cli}, task="${task.substring(0, 50)}..."`);
         console.log(`[pty:${this.config.name}] [SPAWN-DEBUG] dashboardPort=${this.config.dashboardPort}, hasOnSpawn=${!!this.config.onSpawn}`);
+        let spawned = false;
         if (this.config.dashboardPort) {
             // Use dashboard API for spawning (works from spawned agents)
             try {
                 const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/spawn`, {
                     method: 'POST',
                     headers: { 'Content-Type': 'application/json' },
-                    body: JSON.stringify({ name, cli, task }),
+                    body: JSON.stringify({ name, cli }), // No task - we send it after agent is online
                 });
                 const result = await response.json();
                 if (result.success) {
                     console.log(`[pty:${this.config.name}] Spawned ${name} via API`);
+                    spawned = true;
                 }
                 else {
                     console.error(`[pty:${this.config.name}] Spawn failed: ${result.error}`);
@@ -1014,11 +1035,57 @@ export class PtyWrapper extends BaseWrapper {
             // Fall back to callback
             try {
                 await this.config.onSpawn(name, cli, task);
+                spawned = true;
             }
             catch (err) {
                 console.error(`[pty:${this.config.name}] Spawn failed: ${err.message}`);
             }
         }
+        // If spawn succeeded and we have a task, wait for agent to come online and send it
+        if (spawned && task && task.trim() && this.config.dashboardPort) {
+            await this.waitAndSendTask(name, task);
+        }
+    }
+    /**
+     * Wait for a spawned agent to come online, then send the task via relay.
+     * Uses the wrapper's own relay client so the message comes "from" this agent,
+     * not from the dashboard's relay client.
+     */
+    async waitAndSendTask(agentName, task) {
+        const maxWaitMs = 30000;
+        const pollIntervalMs = 500;
+        const startTime = Date.now();
+        console.log(`[pty:${this.config.name}] Waiting for ${agentName} to come online...`);
+        // Poll for agent to be online using dedicated status endpoint
+        while (Date.now() - startTime < maxWaitMs) {
+            try {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/agents/${encodeURIComponent(agentName)}/online`);
+                const data = await response.json();
+                if (data.online) {
+                    console.log(`[pty:${this.config.name}] ${agentName} is online, sending task...`);
+                    // Send task directly via our relay client (not dashboard API)
+                    // This ensures the message comes "from" this agent, not from _DashboardUI
+                    if (this.client.state === 'READY') {
+                        const sent = this.client.sendMessage(agentName, task, 'message');
+                        if (sent) {
+                            console.log(`[pty:${this.config.name}] Task sent to ${agentName}`);
+                        }
+                        else {
+                            console.error(`[pty:${this.config.name}] Failed to send task to ${agentName}: sendMessage returned false`);
+                        }
+                    }
+                    else {
+                        console.error(`[pty:${this.config.name}] Failed to send task to ${agentName}: relay client not ready (state: ${this.client.state})`);
+                    }
+                    return;
+                }
+            }
+            catch (err) {
+                // Ignore poll errors, keep trying
+            }
+            await sleep(pollIntervalMs);
+        }
+        console.error(`[pty:${this.config.name}] Timeout waiting for ${agentName} to come online`);
     }
     /**
      * Execute release via API or callback.
@@ -1058,6 +1125,8 @@ export class PtyWrapper extends BaseWrapper {
      * Extends BaseWrapper to add PTY-specific behavior.
      */
     handleIncomingMessage(from, payload, messageId, meta, originalTo) {
+        const bodyPreview = payload.body.substring(0, 50).replace(/\n/g, '\\n');
+        console.log(`[pty:${this.config.name}] Message received from ${from}: "${bodyPreview}..." (readyForMessages=${this.readyForMessages}, queueLen=${this.messageQueue.length})`);
         // Call base class to handle deduplication and queuing
         super.handleIncomingMessage(from, payload, messageId, meta, originalTo);
         // PTY-specific: Process the message queue immediately
@@ -1067,6 +1136,20 @@ export class PtyWrapper extends BaseWrapper {
             console.error(`[pty:${this.config.name}] Message received hook error:`, err);
         });
     }
+    /**
+     * Handle incoming channel message from relay.
+     * Extends BaseWrapper to add PTY-specific queue processing.
+     */
+    handleIncomingChannelMessage(from, channel, body, envelope) {
+        // Call base class to handle deduplication and queuing
+        super.handleIncomingChannelMessage(from, channel, body, envelope);
+        // PTY-specific: Process the message queue immediately
+        this.processMessageQueue();
+        // PTY-specific: Dispatch message received hook with channel info
+        this.hookRegistry.dispatchMessageReceived(from, body, envelope.id).catch(err => {
+            console.error(`[pty:${this.config.name}] Channel message received hook error:`, err);
+        });
+    }
     /**
      * Wait for output to stabilize before injection.
      * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
@@ -1114,6 +1197,8 @@ export class PtyWrapper extends BaseWrapper {
             this.isInjecting = false;
             return;
         }
+        const bodyPreview = msg.body.substring(0, 50).replace(/\n/g, '\\n');
+        console.log(`[pty:${this.config.name}] Processing message from ${msg.from}: "${bodyPreview}..." (remaining=${this.messageQueue.length})`);
         try {
             // Wait for output to stabilize before injecting
             await this.waitForOutputStable();
@@ -1152,9 +1237,21 @@ export class PtyWrapper extends BaseWrapper {
                     if (!this.ptyProcess || !this.running) {
                         throw new Error('PTY process not running');
                     }
-                    // Write message to PTY, then send Enter separately after a small delay
-                    this.ptyProcess.write(inj);
-                    await sleep(INJECTION_CONSTANTS.ENTER_DELAY_MS);
+                    // Use bracketed paste mode for CLIs that support it (claude, codex, gemini)
+                    // This prevents interleaving with CLI output and ensures clean input
+                    const useBracketedPaste = this.cliType === 'claude' || this.cliType === 'codex' || this.cliType === 'gemini';
+                    if (useBracketedPaste) {
+                        // Bracketed paste: \x1b[200~ starts paste, \x1b[201~ ends paste
+                        this.ptyProcess.write('\x1b[200~' + inj + '\x1b[201~');
+                    }
+                    else {
+                        this.ptyProcess.write(inj);
+                    }
+                    // Wait longer for CLI to process the pasted content before sending Enter.
+                    // The standard 50ms delay is too short for CLIs like Claude that need time
+                    // to process bracketed paste content before accepting Enter.
+                    await sleep(200);
+                    // Send Enter key - use \r for PTY (carriage return)
                     this.ptyProcess.write('\r');
                 },
                 log: (message) => console.log(`[pty:${this.config.name}] ${message}`),
@@ -1199,6 +1296,8 @@ export class PtyWrapper extends BaseWrapper {
     injectInstructions() {
         if (!this.running)
             return;
+        if (this.config.skipInstructions)
+            return;
         // Guard: Only inject once per session
         if (this.instructionsInjected) {
             console.log(`[pty:${this.config.name}] Init instructions already injected, skipping`);