agent-relay 1.3.2 → 1.5.0

package/dist/protocol/relay-pty-schemas.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Relay PTY Protocol Schemas
+ *
+ * This file documents the data formats used in the relay-pty message flow:
+ *
+ * 1. Agent → File (outbox)     : RelayFileFormat
+ * 2. relay-pty → Orchestrator  : ParsedRelayCommand (JSON on stderr)
+ * 3. Orchestrator → Socket     : InjectRequest (JSON)
+ * 4. Socket → Agent PTY        : Plain text injection
+ */
+/**
+ * File format that agents write to /tmp/relay-outbox/$AGENT_RELAY_NAME/<filename>
+ *
+ * Header-based format (preferred over JSON):
+ * - Headers are key: value pairs, one per line
+ * - Blank line separates headers from body
+ * - Body is free-form text (no escaping needed)
+ *
+ * @example Message
+ * ```
+ * TO: Bob
+ * THREAD: feature-123
+ *
+ * Hello Bob, can you review PR #42?
+ * ```
+ *
+ * @example Spawn
+ * ```
+ * KIND: spawn
+ * NAME: ReviewerAgent
+ * CLI: claude
+ *
+ * You are a code reviewer.
+ * Review the changes in src/auth/*.ts
+ * ```
+ *
+ * @example Release
+ * ```
+ * KIND: release
+ * NAME: ReviewerAgent
+ * ```
+ */
+export interface RelayFileFormat {
+    /** Target agent name, "*" for broadcast, or "#channel" */
+    TO?: string;
+    /** Message type: "message" (default), "spawn", or "release" */
+    KIND?: 'message' | 'spawn' | 'release';
+    /** Agent name (required for spawn/release) */
+    NAME?: string;
+    /** CLI to use for spawning (required for spawn) */
+    CLI?: string;
+    /** Thread identifier for grouping related messages */
+    THREAD?: string;
+    /** Message content or task description (for spawn) */
+    body?: string;
+}
+/**
+ * JSON format emitted by relay-pty to stderr when it detects a relay command.
+ * The orchestrator parses this to route messages.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "relay_command",
+ *   "kind": "message",
+ *   "from": "Alice",
+ *   "to": "Bob",
+ *   "body": "Hello!",
+ *   "raw": "->relay-file:msg-001"
+ * }
+ * ```
+ */
+export interface ParsedRelayCommand {
+    /** Always "relay_command" */
+    type: 'relay_command';
+    /** Command type */
+    kind: 'message' | 'spawn' | 'release';
+    /** Sender agent name */
+    from: string;
+    /** Target agent name (or "spawn"/"release" for those commands) */
+    to: string;
+    /** Message body or task description */
+    body: string;
+    /** Original raw text that was parsed */
+    raw: string;
+    /** Thread identifier (optional) */
+    thread?: string;
+    /** For spawn: agent name to spawn */
+    spawn_name?: string;
+    /** For spawn: CLI to use */
+    spawn_cli?: string;
+    /** For spawn: task description */
+    spawn_task?: string;
+    /** For release: agent name to release */
+    release_name?: string;
+}
+/**
+ * JSON format sent to the relay-pty Unix socket for message injection.
+ * Socket path: /tmp/relay-pty-{agentName}.sock
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "inject",
+ *   "id": "msg-abc123",
+ *   "from": "Alice",
+ *   "body": "Hello Bob!",
+ *   "priority": 0
+ * }
+ * ```
+ */
+export type InjectRequest = {
+    type: 'inject';
+    /** Unique message ID for tracking */
+    id: string;
+    /** Sender name (shown as "Relay message from {from}") */
+    from: string;
+    /** Message body to inject */
+    body: string;
+    /** Priority (lower = higher priority, default 0) */
+    priority?: number;
+} | {
+    type: 'status';
+} | {
+    type: 'shutdown';
+};
+/**
+ * Response from relay-pty socket
+ */
+export type InjectResponse = {
+    type: 'inject_result';
+    id: string;
+    status: 'queued' | 'injecting' | 'delivered' | 'failed';
+    timestamp: number;
+    error?: string;
+} | {
+    type: 'status_result';
+    agent_idle: boolean;
+    queue_length: number;
+    last_output_ms: number;
+};
+/**
+ * The final format injected into the recipient agent's PTY as plain text.
+ * NOT JSON - this is human-readable text that appears in the agent's terminal.
+ *
+ * Format: "Relay message from {sender} [{shortId}]: {body}"
+ *
+ * @example First attempt
+ * ```
+ * Relay message from Alice [abc1234]: Hello Bob, can you review PR #42?
+ * ```
+ *
+ * @example Retry (1st retry)
+ * ```
+ * [RETRY] Relay message from Alice [abc1234]: Hello Bob, can you review PR #42?
+ * ```
+ *
+ * @example Urgent (2+ retries)
+ * ```
+ * [URGENT - PLEASE ACKNOWLEDGE] Relay message from Alice [abc1234]: Hello Bob!
+ * ```
+ */
+export type InjectedMessageFormat = string;
+/**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────────────┐
+ * │                        COMPLETE MESSAGE FLOW                                 │
+ * │                                                                              │
+ * │  STEP 1: Agent writes file                                                   │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/msg-001 << 'EOF'           │   │
+ * │  │ TO: Bob                                                               │   │
+ * │  │ THREAD: feature-123                                                   │   │
+ * │  │                                                                       │   │
+ * │  │ Hello Bob, can you review PR #42?                                     │   │
+ * │  │ EOF                                                                   │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 2: Agent outputs trigger                                               │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ ->relay-file:msg-001                                                  │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 3: relay-pty reads file, emits JSON to stderr                          │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ {"type":"relay_command","kind":"message","from":"Alice",             │   │
+ * │  │  "to":"Bob","body":"Hello Bob, can you review PR #42?",              │   │
+ * │  │  "thread":"feature-123","raw":"->relay-file:msg-001"}                │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 4: Orchestrator routes to Bob's relay-pty socket                       │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ {"type":"inject","id":"msg-abc123","from":"Alice",                   │   │
+ * │  │  "body":"Hello Bob, can you review PR #42?","priority":0}            │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 5: Bob's relay-pty injects plain text into PTY                         │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ Relay message from Alice [abc1234]: Hello Bob, can you review PR #42?│   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                                                                              │
+ * └─────────────────────────────────────────────────────────────────────────────┘
+ * ```
+ */
+//# sourceMappingURL=relay-pty-schemas.d.ts.map

package/dist/protocol/relay-pty-schemas.js

@@ -0,0 +1,60 @@
+/**
+ * Relay PTY Protocol Schemas
+ *
+ * This file documents the data formats used in the relay-pty message flow:
+ *
+ * 1. Agent → File (outbox)     : RelayFileFormat
+ * 2. relay-pty → Orchestrator  : ParsedRelayCommand (JSON on stderr)
+ * 3. Orchestrator → Socket     : InjectRequest (JSON)
+ * 4. Socket → Agent PTY        : Plain text injection
+ */
+export {};
+// =============================================================================
+// Complete Flow Diagram
+// =============================================================================
+/**
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────────────┐
+ * │                        COMPLETE MESSAGE FLOW                                 │
+ * │                                                                              │
+ * │  STEP 1: Agent writes file                                                   │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ cat > /tmp/relay-outbox/$AGENT_RELAY_NAME/msg-001 << 'EOF'           │   │
+ * │  │ TO: Bob                                                               │   │
+ * │  │ THREAD: feature-123                                                   │   │
+ * │  │                                                                       │   │
+ * │  │ Hello Bob, can you review PR #42?                                     │   │
+ * │  │ EOF                                                                   │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 2: Agent outputs trigger                                               │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ ->relay-file:msg-001                                                  │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 3: relay-pty reads file, emits JSON to stderr                          │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ {"type":"relay_command","kind":"message","from":"Alice",             │   │
+ * │  │  "to":"Bob","body":"Hello Bob, can you review PR #42?",              │   │
+ * │  │  "thread":"feature-123","raw":"->relay-file:msg-001"}                │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 4: Orchestrator routes to Bob's relay-pty socket                       │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ {"type":"inject","id":"msg-abc123","from":"Alice",                   │   │
+ * │  │  "body":"Hello Bob, can you review PR #42?","priority":0}            │   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                              │                                               │
+ * │                              ▼                                               │
+ * │  STEP 5: Bob's relay-pty injects plain text into PTY                         │
+ * │  ┌──────────────────────────────────────────────────────────────────────┐   │
+ * │  │ Relay message from Alice [abc1234]: Hello Bob, can you review PR #42?│   │
+ * │  └──────────────────────────────────────────────────────────────────────┘   │
+ * │                                                                              │
+ * └─────────────────────────────────────────────────────────────────────────────┘
+ * ```
+ */
+//# sourceMappingURL=relay-pty-schemas.js.map

package/dist/wrapper/auth-detection.js

@@ -34,8 +34,10 @@ export const AUTH_REVOCATION_PATTERNS = [
     // OAuth specific
     /oauth\s+error.*401/i,
     /oauth\s+error.*403/i,
+    /oauth\s+token\s+(has\s+)?expired/i,
     /refresh\s+token\s+(is\s+)?invalid/i,
     /failed\s+to\s+refresh/i,
+    /please\s+obtain\s+a\s+new\s+token/i,
     // API errors that indicate auth issues
     /api\s+error.*401/i,
     /api\s+error.*403/i,
@@ -111,8 +113,11 @@ function getConfidenceLevel(pattern, _matchedText) {
         patternStr.includes('please') && patternStr.includes('log') ||
         patternStr.includes('authentication required') ||
         patternStr.includes('token') && patternStr.includes('expired') ||
+        patternStr.includes('oauth') && patternStr.includes('expired') ||
+        patternStr.includes('authentication_error') ||
         patternStr.includes('signed out') ||
-        patternStr.includes('session revoked')) {
+        patternStr.includes('session revoked') ||
+        patternStr.includes('obtain') && patternStr.includes('token')) {
         return 'high';
     }
     // Medium confidence: General auth errors
@@ -150,6 +155,8 @@ export const PROVIDER_AUTH_PATTERNS = {
         /anthropic.*unauthorized/i,
         /claude.*not\s+authenticated/i,
         /please\s+run\s+claude\s+login/i,
+        /please\s+run\s+\/login/i,
+        /authentication_error/i,
     ],
     codex: [
         /codex.*session.*expired/i,

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

@@ -17,7 +17,8 @@
 import { EventEmitter } from 'node:events';
 import { RelayClient } from './client.js';
 import type { ParsedCommand, ParsedSummary } from './parser.js';
-import type { SendPayload, SendMeta, SpeakOnTrigger } from '../protocol/types.js';
+import type { SendPayload, SendMeta, SpeakOnTrigger, Envelope } from '../protocol/types.js';
+import type { ChannelMessagePayload } from '../protocol/channels.js';
 import { type QueuedMessage, type InjectionMetrics, type CliType } from './shared.js';
 import { type ContinuityManager } from '../continuity/index.js';
 import { UniversalIdleDetector } from './idle-detector.js';
@@ -60,6 +61,10 @@ export interface BaseWrapperConfig {
     idleBeforeInjectMs?: number;
     /** Confidence threshold for idle detection (0-1, default: 0.7) */
     idleConfidenceThreshold?: number;
+    /** Skip initial instruction injection (when using --append-system-prompt) */
+    skipInstructions?: boolean;
+    /** Skip continuity loading (for spawned agents that don't need session recovery) */
+    skipContinuity?: boolean;
 }
 /**
  * Abstract base class for agent wrappers
@@ -142,6 +147,11 @@ export declare abstract class BaseWrapper extends EventEmitter {
      * Handle incoming message from relay
      */
     protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
+    /**
+     * Handle incoming channel message from relay.
+     * Channel messages include a channel indicator so the agent knows to reply to the channel.
+     */
+    protected handleIncomingChannelMessage(from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>): void;
     /**
      * Send a relay command via the client
      */

package/dist/wrapper/base-wrapper.js

@@ -63,17 +63,23 @@ export class BaseWrapper extends EventEmitter {
             workingDirectory: config.cwd,
             quiet: true,
         });
-        // Initialize continuity manager
-        this.continuity = getContinuityManager({ defaultCli: this.cliType });
+        // Initialize continuity manager (skip for spawned agents that don't need session recovery)
+        if (!config.skipContinuity) {
+            this.continuity = getContinuityManager({ defaultCli: this.cliType });
+        }
         // Initialize universal idle detector for robust injection timing
         this.idleDetector = new UniversalIdleDetector({
             minSilenceMs: config.idleBeforeInjectMs ?? DEFAULT_IDLE_BEFORE_INJECT_MS,
             confidenceThreshold: config.idleConfidenceThreshold ?? DEFAULT_IDLE_CONFIDENCE_THRESHOLD,
         });
-        // Set up message handler
+        // Set up message handler for direct messages
         this.client.onMessage = (from, payload, messageId, meta, originalTo) => {
             this.handleIncomingMessage(from, payload, messageId, meta, originalTo);
         };
+        // Set up channel message handler
+        this.client.onChannelMessage = (from, channel, body, envelope) => {
+            this.handleIncomingChannelMessage(from, channel, body, envelope);
+        };
     }
     // =========================================================================
     // Common getters
@@ -163,6 +169,40 @@ export class BaseWrapper extends EventEmitter {
         };
         this.messageQueue.push(queuedMsg);
     }
+    /**
+     * Handle incoming channel message from relay.
+     * Channel messages include a channel indicator so the agent knows to reply to the channel.
+     */
+    handleIncomingChannelMessage(from, channel, body, envelope) {
+        const messageId = envelope.id;
+        // Deduplicate by message ID
+        if (this.receivedMessageIds.has(messageId))
+            return;
+        this.receivedMessageIds.add(messageId);
+        // Limit dedup set size
+        if (this.receivedMessageIds.size > 1000) {
+            const oldest = this.receivedMessageIds.values().next().value;
+            if (oldest)
+                this.receivedMessageIds.delete(oldest);
+        }
+        // Queue the message with channel indicator in the body
+        // Format: "Relay message from Alice [abc123] [#general]: message body"
+        // This lets the agent know to reply to the channel, not the sender
+        const queuedMsg = {
+            from,
+            body,
+            messageId,
+            thread: envelope.payload.thread,
+            data: {
+                _isChannelMessage: true,
+                _channel: channel,
+                _mentions: envelope.payload.mentions,
+            },
+            originalTo: channel, // Set channel as the reply target
+        };
+        console.error(`[base-wrapper] Received channel message: from=${from} channel=${channel} id=${messageId.substring(0, 8)}`);
+        this.messageQueue.push(queuedMsg);
+    }
     /**
      * Send a relay command via the client
      */
@@ -186,9 +226,24 @@ export class BaseWrapper extends EventEmitter {
                 this.sentMessageHashes.delete(oldest);
         }
         // Only send if client ready
-        if (this.client.state !== 'READY')
+        if (this.client.state !== 'READY') {
+            console.error(`[base-wrapper] Client not ready (state=${this.client.state}), dropping message to ${cmd.to}`);
             return;
-        this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread);
+        }
+        console.error(`[base-wrapper] sendRelayCommand: to=${cmd.to}, body=${cmd.body.substring(0, 50)}...`);
+        // Check if target is a channel (starts with #)
+        if (cmd.to.startsWith('#')) {
+            // Use CHANNEL_MESSAGE protocol for channel targets
+            console.error(`[base-wrapper] Sending CHANNEL_MESSAGE to ${cmd.to}`);
+            this.client.sendChannelMessage(cmd.to, cmd.body, {
+                thread: cmd.thread,
+                data: cmd.data,
+            });
+        }
+        else {
+            // Use SEND protocol for direct messages and broadcasts
+            this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread);
+        }
     }
     // =========================================================================
     // Spawn/release handling
@@ -197,11 +252,16 @@ export class BaseWrapper extends EventEmitter {
      * Parse spawn and release commands from output
      */
     parseSpawnReleaseCommands(content) {
+        // Debug: check for spawn keyword
+        if (content.includes('->relay:spawn')) {
+            console.log(`[base-wrapper:${this.config.name}] Found spawn keyword in content`);
+        }
         // Single-line spawn: ->relay:spawn Name cli "task"
         const spawnPattern = new RegExp(`${this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}spawn\\s+(\\w+)\\s+(\\w+)\\s+"([^"]+)"`);
         const spawnMatch = content.match(spawnPattern);
         if (spawnMatch) {
             const [, name, cli, task] = spawnMatch;
+            console.log(`[base-wrapper:${this.config.name}] Single-line spawn match: ${name} ${cli}`);
             const cmdHash = `spawn:${name}:${cli}:${task}`;
             if (!this.processedSpawnCommands.has(cmdHash)) {
                 this.processedSpawnCommands.add(cmdHash);
@@ -209,10 +269,11 @@ export class BaseWrapper extends EventEmitter {
             }
         }
         // Fenced spawn: ->relay:spawn Name cli <<<\ntask\n>>>
-        const fencedSpawnPattern = new RegExp(`${this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}spawn\\s+(\\w+)\\s+(\\w+)\\s+<<<\\n?([\\s\\S]*?)>>>`);
+        const fencedSpawnPattern = new RegExp(`${this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}spawn\\s+(\\w+)\\s+(\\w+)\\s*<<<[\\s]*([\\s\\S]*?)>>>`);
         const fencedSpawnMatch = content.match(fencedSpawnPattern);
         if (fencedSpawnMatch) {
             const [, name, cli, task] = fencedSpawnMatch;
+            console.log(`[base-wrapper:${this.config.name}] Fenced spawn match: ${name} ${cli}`);
             const cmdHash = `spawn:${name}:${cli}:${task.trim()}`;
             if (!this.processedSpawnCommands.has(cmdHash)) {
                 this.processedSpawnCommands.add(cmdHash);

package/dist/wrapper/client.d.ts

@@ -7,7 +7,8 @@
  * - Write coalescing (batch socket writes)
  * - Circular dedup cache (O(1) eviction)
  */
-import { type SendPayload, type SendMeta, type PayloadKind, type SpeakOnTrigger, type EntityType } from '../protocol/types.js';
+import { type Envelope, type SendPayload, type SendMeta, type PayloadKind, type SpeakOnTrigger, type EntityType } from '../protocol/types.js';
+import type { ChannelMessagePayload, MessageAttachment } from '../protocol/channels.js';
 export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
 export interface ClientConfig {
     socketPath: string;
@@ -58,6 +59,14 @@ export declare class RelayClient {
      * @param originalTo - Original 'to' field from sender (e.g., '*' for broadcasts)
      */
     onMessage?: (from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string) => void;
+    /**
+     * Callback for channel messages.
+     * @param from - Sender name
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param envelope - Full envelope for additional data
+     */
+    onChannelMessage?: (from: string, channel: string, body: string, envelope: Envelope<ChannelMessagePayload>) => void;
     onStateChange?: (state: ClientState) => void;
     onError?: (error: Error) => void;
     constructor(config?: Partial<ClientConfig>);
@@ -91,6 +100,44 @@ export declare class RelayClient {
      * Broadcast a message to all agents.
      */
     broadcast(body: string, kind?: PayloadKind, data?: Record<string, unknown>): boolean;
+    /**
+     * Join a channel.
+     * @param channel - Channel name (e.g., '#general', 'dm:alice:bob')
+     * @param displayName - Optional display name for this member
+     */
+    joinChannel(channel: string, displayName?: string): boolean;
+    /**
+     * 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: string, member: string): boolean;
+    /**
+     * Leave a channel.
+     * @param channel - Channel name to leave
+     * @param reason - Optional reason for leaving
+     */
+    leaveChannel(channel: string, reason?: string): boolean;
+    /**
+     * 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: string, member: string): boolean;
+    /**
+     * Send a message to a channel.
+     * @param channel - Channel name
+     * @param body - Message content
+     * @param options - Optional thread, mentions, attachments
+     */
+    sendChannelMessage(channel: string, body: string, options?: {
+        thread?: string;
+        mentions?: string[];
+        attachments?: MessageAttachment[];
+        data?: Record<string, unknown>;
+    }): boolean;
     /**
      * Subscribe to a topic.
      */
@@ -136,6 +183,7 @@ export declare class RelayClient {
     private processFrame;
     private handleWelcome;
     private handleDeliver;
+    private handleChannelMessage;
     private handlePing;
     private handleErrorFrame;
     private handleDisconnect;