agent-relay 1.2.0 → 1.3.0

package/dist/wrapper/base-wrapper.js

@@ -0,0 +1,393 @@
+/**
+ * BaseWrapper - Abstract base class for agent wrappers
+ *
+ * Provides shared functionality between TmuxWrapper and PtyWrapper:
+ * - Message queue management and deduplication
+ * - Spawn/release command parsing and execution
+ * - Continuity integration (agent ID, summary saving)
+ * - Relay command handling
+ * - Line joining for multi-line commands
+ *
+ * Subclasses implement:
+ * - start() - Initialize and start the agent process
+ * - stop() - Stop the agent process
+ * - performInjection() - Inject content into the agent
+ * - getCleanOutput() - Get cleaned output for parsing
+ */
+import { EventEmitter } from 'node:events';
+import { RelayClient } from './client.js';
+import { isPlaceholderTarget } from './parser.js';
+import { getDefaultRelayPrefix, detectCliType, createInjectionMetrics, } from './shared.js';
+import { getContinuityManager, parseContinuityCommand, hasContinuityCommand, } from '../continuity/index.js';
+/**
+ * Abstract base class for agent wrappers
+ */
+export class BaseWrapper extends EventEmitter {
+    config;
+    client;
+    relayPrefix;
+    cliType;
+    running = false;
+    // Message queue state
+    messageQueue = [];
+    sentMessageHashes = new Set();
+    isInjecting = false;
+    receivedMessageIds = new Set();
+    injectionMetrics = createInjectionMetrics();
+    // Spawn/release state
+    processedSpawnCommands = new Set();
+    processedReleaseCommands = new Set();
+    pendingFencedSpawn = null;
+    // Continuity state
+    continuity;
+    agentId;
+    processedContinuityCommands = new Set();
+    sessionEndProcessed = false;
+    sessionEndData;
+    lastSummaryRawContent = '';
+    constructor(config) {
+        super();
+        this.config = config;
+        this.relayPrefix = config.relayPrefix ?? getDefaultRelayPrefix();
+        this.cliType = config.cliType ?? detectCliType(config.command);
+        // Initialize relay client with full config
+        this.client = new RelayClient({
+            agentName: config.name,
+            socketPath: config.socketPath,
+            cli: this.cliType,
+            task: config.task,
+            workingDirectory: config.cwd,
+            quiet: true,
+        });
+        // Initialize continuity manager
+        this.continuity = getContinuityManager({ defaultCli: this.cliType });
+        // Set up message handler
+        this.client.onMessage = (from, payload, messageId, meta, originalTo) => {
+            this.handleIncomingMessage(from, payload, messageId, meta, originalTo);
+        };
+    }
+    // =========================================================================
+    // Common getters
+    // =========================================================================
+    get isRunning() {
+        return this.running;
+    }
+    get name() {
+        return this.config.name;
+    }
+    getAgentId() {
+        return this.agentId;
+    }
+    getInjectionMetrics() {
+        const total = this.injectionMetrics.total;
+        const successes = this.injectionMetrics.successFirstTry + this.injectionMetrics.successWithRetry;
+        const successRate = total > 0
+            ? (successes / total) * 100
+            : 100;
+        return {
+            ...this.injectionMetrics,
+            successRate,
+        };
+    }
+    get pendingMessageCount() {
+        return this.messageQueue.length;
+    }
+    // =========================================================================
+    // Message handling
+    // =========================================================================
+    /**
+     * Handle incoming message from relay
+     */
+    handleIncomingMessage(from, payload, messageId, meta, originalTo) {
+        // 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
+        const queuedMsg = {
+            from,
+            body: payload.body,
+            messageId,
+            thread: payload.thread,
+            importance: meta?.importance,
+            data: payload.data,
+            originalTo,
+        };
+        this.messageQueue.push(queuedMsg);
+    }
+    /**
+     * Send a relay command via the client
+     */
+    sendRelayCommand(cmd) {
+        // Validate target
+        if (isPlaceholderTarget(cmd.to))
+            return;
+        // Create hash for deduplication (use first 100 chars of body)
+        const hash = `${cmd.to}:${cmd.body.substring(0, 100)}`;
+        if (this.sentMessageHashes.has(hash))
+            return;
+        this.sentMessageHashes.add(hash);
+        // Limit hash set size
+        if (this.sentMessageHashes.size > 500) {
+            const oldest = this.sentMessageHashes.values().next().value;
+            if (oldest)
+                this.sentMessageHashes.delete(oldest);
+        }
+        // Only send if client ready
+        if (this.client.state !== 'READY')
+            return;
+        this.client.sendMessage(cmd.to, cmd.body, cmd.kind, cmd.data, cmd.thread);
+    }
+    // =========================================================================
+    // Spawn/release handling
+    // =========================================================================
+    /**
+     * Parse spawn and release commands from output
+     */
+    parseSpawnReleaseCommands(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;
+            const cmdHash = `spawn:${name}:${cli}:${task}`;
+            if (!this.processedSpawnCommands.has(cmdHash)) {
+                this.processedSpawnCommands.add(cmdHash);
+                this.executeSpawn(name, cli, task);
+            }
+        }
+        // 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 fencedSpawnMatch = content.match(fencedSpawnPattern);
+        if (fencedSpawnMatch) {
+            const [, name, cli, task] = fencedSpawnMatch;
+            const cmdHash = `spawn:${name}:${cli}:${task.trim()}`;
+            if (!this.processedSpawnCommands.has(cmdHash)) {
+                this.processedSpawnCommands.add(cmdHash);
+                this.executeSpawn(name, cli, task.trim());
+            }
+        }
+        // Release: ->relay:release Name
+        const releasePattern = new RegExp(`${this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}release\\s+(\\w+)`);
+        const releaseMatch = content.match(releasePattern);
+        if (releaseMatch) {
+            const name = releaseMatch[1];
+            const cmdHash = `release:${name}`;
+            if (!this.processedReleaseCommands.has(cmdHash)) {
+                this.processedReleaseCommands.add(cmdHash);
+                this.executeRelease(name);
+            }
+        }
+    }
+    /**
+     * Execute a spawn command
+     */
+    async executeSpawn(name, cli, task) {
+        // Try dashboard API first
+        if (this.config.dashboardPort) {
+            try {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/agents/spawn`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ name, cli, task }),
+                });
+                if (response.ok)
+                    return;
+            }
+            catch {
+                // Fall through to callback
+            }
+        }
+        // Use callback
+        if (this.config.onSpawn) {
+            await this.config.onSpawn(name, cli, task);
+        }
+    }
+    /**
+     * Execute a release command
+     */
+    async executeRelease(name) {
+        // Try dashboard API first
+        if (this.config.dashboardPort) {
+            try {
+                const response = await fetch(`http://localhost:${this.config.dashboardPort}/api/agents/${name}`, { method: 'DELETE' });
+                if (response.ok)
+                    return;
+            }
+            catch {
+                // Fall through to callback
+            }
+        }
+        // Use callback
+        if (this.config.onRelease) {
+            await this.config.onRelease(name);
+        }
+    }
+    // =========================================================================
+    // Continuity handling
+    // =========================================================================
+    /**
+     * Initialize agent ID for continuity/resume
+     */
+    async initializeAgentId() {
+        if (!this.continuity)
+            return;
+        try {
+            let ledger;
+            // If resuming, try to find previous ledger
+            if (this.config.resumeAgentId) {
+                ledger = await this.continuity.findLedgerByAgentId(this.config.resumeAgentId);
+                if (ledger) {
+                    console.log(`[${this.config.name}] Resuming agent ID: ${ledger.agentId}`);
+                }
+            }
+            // Otherwise get or create
+            if (!ledger) {
+                ledger = await this.continuity.getOrCreateLedger(this.config.name, this.cliType);
+                console.log(`[${this.config.name}] Agent ID: ${ledger.agentId}`);
+            }
+            this.agentId = ledger.agentId;
+        }
+        catch (err) {
+            console.error(`[${this.config.name}] Failed to initialize agent ID: ${err.message}`);
+        }
+    }
+    /**
+     * Parse continuity commands from output
+     */
+    async parseContinuityCommands(content) {
+        if (!this.continuity)
+            return;
+        if (!hasContinuityCommand(content))
+            return;
+        const command = parseContinuityCommand(content);
+        if (!command)
+            return;
+        // Deduplication
+        const cmdHash = `${command.type}:${command.content || command.query || command.item || 'no-content'}`;
+        if (command.content && this.processedContinuityCommands.has(cmdHash))
+            return;
+        this.processedContinuityCommands.add(cmdHash);
+        // Limit dedup set size
+        if (this.processedContinuityCommands.size > 100) {
+            const oldest = this.processedContinuityCommands.values().next().value;
+            if (oldest)
+                this.processedContinuityCommands.delete(oldest);
+        }
+        try {
+            const response = await this.continuity.handleCommand(this.config.name, command);
+            if (response) {
+                // Queue response for injection
+                this.messageQueue.push({
+                    from: 'system',
+                    body: response,
+                    messageId: `continuity-${Date.now()}`,
+                    thread: 'continuity-response',
+                });
+            }
+        }
+        catch (err) {
+            console.error(`[${this.config.name}] Continuity command error: ${err.message}`);
+        }
+    }
+    /**
+     * Save a parsed summary to the continuity ledger
+     */
+    async saveSummaryToLedger(summary) {
+        if (!this.continuity)
+            return;
+        const updates = {};
+        if (summary.currentTask) {
+            updates.currentTask = summary.currentTask;
+        }
+        if (summary.completedTasks && summary.completedTasks.length > 0) {
+            updates.completed = summary.completedTasks;
+        }
+        if (summary.context) {
+            updates.inProgress = [summary.context];
+        }
+        if (summary.files && summary.files.length > 0) {
+            updates.fileContext = summary.files.map((f) => ({ path: f }));
+        }
+        if (Object.keys(updates).length > 0) {
+            await this.continuity.saveLedger(this.config.name, updates);
+            console.log(`[${this.config.name}] Saved summary to continuity ledger`);
+        }
+    }
+    /**
+     * Reset session-specific state for wrapper reuse
+     */
+    resetSessionState() {
+        this.sessionEndProcessed = false;
+        this.lastSummaryRawContent = '';
+        this.sessionEndData = undefined;
+    }
+    // =========================================================================
+    // Utility methods
+    // =========================================================================
+    /**
+     * Join continuation lines for multi-line relay/continuity commands.
+     * TUIs like Claude Code insert real newlines in output, causing
+     * messages to span multiple lines. This joins indented
+     * continuation lines back to the command line.
+     */
+    joinContinuationLines(content) {
+        const lines = content.split('\n');
+        const result = [];
+        // Pattern to detect relay OR continuity command line (with optional bullet prefix)
+        const escapedPrefix = this.relayPrefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const commandPattern = new RegExp(`^(?:\\s*(?:[>$%#→➜›»●•◦‣⁃\\-*⏺◆◇○□■]\\s*)*)?(?:${escapedPrefix}|->continuity:)`);
+        // Pattern to detect a continuation line (starts with spaces, no bullet/command)
+        const continuationPattern = /^[ \t]+[^>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■\s]/;
+        // Pattern to detect a new block/bullet (stops continuation)
+        const newBlockPattern = /^(?:\s*)?[>$%#→➜›»●•◦‣⁃\-*⏺◆◇○□■]/;
+        let i = 0;
+        while (i < lines.length) {
+            const line = lines[i];
+            // Check if this is a command line
+            if (commandPattern.test(line)) {
+                let joined = line;
+                let j = i + 1;
+                // Look ahead for continuation lines
+                while (j < lines.length) {
+                    const nextLine = lines[j];
+                    // Empty line stops continuation
+                    if (nextLine.trim() === '')
+                        break;
+                    // New bullet/block stops continuation
+                    if (newBlockPattern.test(nextLine))
+                        break;
+                    // Check if it looks like a continuation (indented text)
+                    if (continuationPattern.test(nextLine)) {
+                        // Join with newline to preserve multi-line message content
+                        joined += '\n' + nextLine.trim();
+                        j++;
+                    }
+                    else {
+                        break;
+                    }
+                }
+                result.push(joined);
+                i = j; // Skip the lines we joined
+            }
+            else {
+                result.push(line);
+                i++;
+            }
+        }
+        return result.join('\n');
+    }
+    /**
+     * Clean up resources
+     */
+    destroyClient() {
+        this.client.destroy();
+    }
+}
+//# sourceMappingURL=base-wrapper.js.map

package/dist/wrapper/client.d.ts

@@ -2,11 +2,13 @@
  * Relay Client
  * Connects to the daemon and handles message sending/receiving.
  */
-import { type SendPayload, type SendMeta, type PayloadKind, type SpeakOnTrigger } from '../protocol/types.js';
+import { type SendPayload, type SendMeta, type PayloadKind, type SpeakOnTrigger, type EntityType } from '../protocol/types.js';
 export type ClientState = 'DISCONNECTED' | 'CONNECTING' | 'HANDSHAKING' | 'READY' | 'BACKOFF';
 export interface ClientConfig {
     socketPath: string;
     agentName: string;
+    /** Entity type: 'agent' (default) or 'user' for human users */
+    entityType?: EntityType;
     /** Optional CLI identifier to surface to the dashboard */
     cli?: string;
     /** Optional program identifier (e.g., 'claude', 'gpt-4o') */
@@ -17,6 +19,10 @@ export interface ClientConfig {
     task?: string;
     /** Optional working directory to surface in registry/dashboard */
     workingDirectory?: string;
+    /** Display name for human users */
+    displayName?: string;
+    /** Avatar URL for human users */
+    avatarUrl?: string;
     /** Suppress client-side console logging */
     quiet?: boolean;
     reconnect: boolean;

package/dist/wrapper/client.js

@@ -280,11 +280,14 @@ export class RelayClient {
             ts: Date.now(),
             payload: {
                 agent: this.config.agentName,
+                entityType: this.config.entityType,
                 cli: this.config.cli,
                 program: this.config.program,
                 model: this.config.model,
                 task: this.config.task,
                 workingDirectory: this.config.workingDirectory,
+                displayName: this.config.displayName,
+                avatarUrl: this.config.avatarUrl,
                 capabilities: {
                     ack: true,
                     resume: true,

package/dist/wrapper/index.d.ts

@@ -1,3 +1,4 @@
 export * from './client.js';
 export * from './parser.js';
+export * from './base-wrapper.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/wrapper/index.js

@@ -1,6 +1,7 @@
 export * from './client.js';
 export * from './parser.js';
-// Note: tmux-wrapper.ts is intentionally not exported here.
-// It's dynamically imported in CLI only, as it has different
-// runtime requirements (tmux must be installed).
+export * from './base-wrapper.js';
+// Note: tmux-wrapper.ts and pty-wrapper.ts are intentionally not exported here.
+// They're dynamically imported in CLI only, as they have different
+// runtime requirements (tmux/pty must be available).
 //# sourceMappingURL=index.js.map