agent-relay 1.6.0 → 2.0.4

package/packages/wrapper/dist/__fixtures__/gemini-outputs.js

@@ -0,0 +1,144 @@
+/**
+ * Gemini CLI output fixtures for parser regression testing.
+ *
+ * Gemini has unique characteristics:
+ * - Uses sparkle character (✦) as output prefix
+ * - Can drop into shell mode ($ prompt)
+ * - Has specific keyword interpretation issues
+ */
+/**
+ * Gemini-specific characters and patterns
+ */
+export const GEMINI = {
+    SPARKLE: '✦',
+    SHELL_PROMPT: '$',
+};
+export const geminiOutputFixtures = [
+    // =====================================================================
+    // Sparkle prefix handling
+    // =====================================================================
+    {
+        name: 'gemini-sparkle-prefix',
+        description: 'Relay command with Gemini sparkle prefix',
+        input: `${GEMINI.SPARKLE} ->relay:Lead STATUS: Ready for task
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'STATUS: Ready for task' },
+        ],
+    },
+    {
+        name: 'gemini-sparkle-with-space',
+        description: 'Sparkle with extra spacing',
+        input: `${GEMINI.SPARKLE}  ->relay:Lead Message with extra space
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'Message with extra space' },
+        ],
+    },
+    {
+        name: 'gemini-multiple-sparkle-lines',
+        description: 'Multiple lines with sparkle prefix',
+        input: `${GEMINI.SPARKLE} Processing your request...
+${GEMINI.SPARKLE} ->relay:Lead Task complete
+${GEMINI.SPARKLE} Ready for next task.
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'Task complete' },
+        ],
+        expectedOutputContains: ['Processing your request', 'Ready for next task'],
+    },
+    // =====================================================================
+    // Shell mode detection
+    // =====================================================================
+    {
+        name: 'gemini-shell-mode-output',
+        description: 'Output that includes shell prompt',
+        input: `${GEMINI.SPARKLE} Let me run that command for you.
+$ ls -la
+total 48
+drwxr-xr-x  5 user user 4096 Jan 23 10:00 .
+${GEMINI.SPARKLE} ->relay:Lead Command executed successfully
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'Command executed successfully' },
+        ],
+        expectedOutputContains: ['$ ls -la', 'total 48'],
+    },
+    // =====================================================================
+    // Gemini-specific edge cases
+    // =====================================================================
+    {
+        name: 'gemini-fenced-with-sparkle',
+        description: 'Fenced message with sparkle prefix',
+        input: `${GEMINI.SPARKLE} ->relay:Lead <<<
+Here's my detailed analysis:
+
+The issue is in the authentication flow.
+Consider these changes:
+1. Update token validation
+2. Add refresh logic
+>>>
+`,
+        expectedCommands: [
+            {
+                to: 'Lead',
+                body: `Here's my detailed analysis:
+
+The issue is in the authentication flow.
+Consider these changes:
+1. Update token validation
+2. Add refresh logic`,
+            },
+        ],
+    },
+    {
+        name: 'gemini-mixed-output',
+        description: 'Mix of sparkle and non-sparkle output',
+        input: `Processing...
+${GEMINI.SPARKLE} Analyzing the codebase
+${GEMINI.SPARKLE} Found 3 issues
+->relay:Lead Analysis complete with 3 issues found
+${GEMINI.SPARKLE} Done!
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'Analysis complete with 3 issues found' },
+        ],
+    },
+    // =====================================================================
+    // Complex Gemini scenarios
+    // =====================================================================
+    {
+        name: 'gemini-code-execution-output',
+        description: 'Gemini executing code with relay after',
+        input: `${GEMINI.SPARKLE} I'll run the tests for you.
+
+$ npm test
+
+> project@1.0.0 test
+> vitest run
+
+ ✓ src/auth.test.ts (5 tests)
+ ✓ src/api.test.ts (12 tests)
+
+Test Files  2 passed
+Tests       17 passed
+
+${GEMINI.SPARKLE} ->relay:Lead Tests passed: 17/17. Build is green.
+`,
+        expectedCommands: [
+            { to: 'Lead', body: 'Tests passed: 17/17. Build is green.' },
+        ],
+        expectedOutputContains: ['npm test', '17 passed'],
+    },
+    {
+        name: 'gemini-broadcast',
+        description: 'Gemini sending broadcast message',
+        input: `${GEMINI.SPARKLE} ->relay:* All agents: deployment starting in 5 minutes
+`,
+        expectedCommands: [
+            { to: '*', body: 'All agents: deployment starting in 5 minutes' },
+        ],
+    },
+];
+export default geminiOutputFixtures;
+//# sourceMappingURL=gemini-outputs.js.map

package/packages/wrapper/dist/__fixtures__/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Parser regression test fixtures
+ *
+ * This module exports CLI output fixtures for testing the parser
+ * against real-world terminal output patterns.
+ *
+ * To add new fixtures:
+ * 1. Capture the problematic output from a real CLI session
+ * 2. Add it to the appropriate CLI-specific fixture file
+ * 3. Run tests to ensure parser handles it correctly
+ *
+ * When a parser bug is fixed, add a regression test fixture
+ * to prevent the bug from recurring.
+ */
+export { claudeOutputFixtures, type OutputFixture, ANSI } from './claude-outputs.js';
+export { geminiOutputFixtures, GEMINI } from './gemini-outputs.js';
+export { codexOutputFixtures } from './codex-outputs.js';
+/**
+ * All fixtures combined for comprehensive testing
+ */
+export declare const allFixtures: ({
+    cli: "claude";
+    name: string;
+    description: string;
+    input: string;
+    expectedCommands: Array<{
+        to: string;
+        body: string;
+        kind?: string;
+        thread?: string;
+        project?: string;
+    }>;
+    expectedOutputContains?: string[];
+    expectedOutputNotContains?: string[];
+} | {
+    cli: "gemini";
+    name: string;
+    description: string;
+    input: string;
+    expectedCommands: Array<{
+        to: string;
+        body: string;
+        kind?: string;
+        thread?: string;
+        project?: string;
+    }>;
+    expectedOutputContains?: string[];
+    expectedOutputNotContains?: string[];
+} | {
+    cli: "codex";
+    name: string;
+    description: string;
+    input: string;
+    expectedCommands: Array<{
+        to: string;
+        body: string;
+        kind?: string;
+        thread?: string;
+        project?: string;
+    }>;
+    expectedOutputContains?: string[];
+    expectedOutputNotContains?: string[];
+})[];
+/**
+ * Get fixtures by CLI type
+ */
+export declare function getFixturesByCli(cli: 'claude' | 'gemini' | 'codex'): import("./claude-outputs.js").OutputFixture[];
+//# sourceMappingURL=index.d.ts.map

package/packages/wrapper/dist/__fixtures__/index.js

@@ -0,0 +1,44 @@
+/**
+ * Parser regression test fixtures
+ *
+ * This module exports CLI output fixtures for testing the parser
+ * against real-world terminal output patterns.
+ *
+ * To add new fixtures:
+ * 1. Capture the problematic output from a real CLI session
+ * 2. Add it to the appropriate CLI-specific fixture file
+ * 3. Run tests to ensure parser handles it correctly
+ *
+ * When a parser bug is fixed, add a regression test fixture
+ * to prevent the bug from recurring.
+ */
+export { claudeOutputFixtures, ANSI } from './claude-outputs.js';
+export { geminiOutputFixtures, GEMINI } from './gemini-outputs.js';
+export { codexOutputFixtures } from './codex-outputs.js';
+import { claudeOutputFixtures } from './claude-outputs.js';
+import { geminiOutputFixtures } from './gemini-outputs.js';
+import { codexOutputFixtures } from './codex-outputs.js';
+/**
+ * All fixtures combined for comprehensive testing
+ */
+export const allFixtures = [
+    ...claudeOutputFixtures.map(f => ({ ...f, cli: 'claude' })),
+    ...geminiOutputFixtures.map(f => ({ ...f, cli: 'gemini' })),
+    ...codexOutputFixtures.map(f => ({ ...f, cli: 'codex' })),
+];
+/**
+ * Get fixtures by CLI type
+ */
+export function getFixturesByCli(cli) {
+    switch (cli) {
+        case 'claude':
+            return claudeOutputFixtures;
+        case 'gemini':
+            return geminiOutputFixtures;
+        case 'codex':
+            return codexOutputFixtures;
+        default:
+            return [];
+    }
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,249 @@
+/**
+ * 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 type { ParsedCommand, ParsedSummary } from './parser.js';
+import type { SendPayload, SendMeta, SpeakOnTrigger, Envelope } from '@agent-relay/protocol/types';
+import type { ChannelMessagePayload } from '@agent-relay/protocol/channels';
+import { type QueuedMessage, type InjectionMetrics, type CliType, type MessagePriority } from './shared.js';
+import { type ContinuityManager } from '@agent-relay/continuity';
+import { UniversalIdleDetector } from './idle-detector.js';
+import { StuckDetector, type StuckReason } from './stuck-detector.js';
+/**
+ * Base configuration shared by all wrapper types
+ */
+export interface BaseWrapperConfig {
+    /** Agent name (must be unique) */
+    name: string;
+    /** Command to execute */
+    command: string;
+    /** Command arguments */
+    args?: string[];
+    /** Relay daemon socket path */
+    socketPath?: string;
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Relay prefix pattern (default: '->relay:') */
+    relayPrefix?: string;
+    /** CLI type (auto-detected if not set) */
+    cliType?: CliType;
+    /** Dashboard port for spawn/release API */
+    dashboardPort?: number;
+    /** Callback when spawn command is parsed */
+    onSpawn?: (name: string, cli: string, task: string) => Promise<void>;
+    /** Callback when release command is parsed */
+    onRelease?: (name: string) => Promise<void>;
+    /** Agent ID to resume from (for continuity) */
+    resumeAgentId?: string;
+    /** Stream logs to daemon */
+    streamLogs?: boolean;
+    /** Task/role description */
+    task?: string;
+    /** Shadow configuration */
+    shadowOf?: string;
+    shadowSpeakOn?: SpeakOnTrigger[];
+    /** Milliseconds of idle time before injection is allowed (default: 1500) */
+    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
+ */
+export declare abstract class BaseWrapper extends EventEmitter {
+    protected config: BaseWrapperConfig;
+    protected client: RelayClient;
+    protected relayPrefix: string;
+    protected cliType: CliType;
+    protected running: boolean;
+    protected messageQueue: QueuedMessage[];
+    protected sentMessageHashes: Set<string>;
+    protected isInjecting: boolean;
+    protected receivedMessageIds: Set<string>;
+    protected injectionMetrics: InjectionMetrics;
+    protected processedSpawnCommands: Set<string>;
+    protected processedReleaseCommands: Set<string>;
+    protected pendingFencedSpawn: {
+        name: string;
+        cli: string;
+        taskLines: string[];
+    } | null;
+    protected continuity?: ContinuityManager;
+    protected agentId?: string;
+    protected processedContinuityCommands: Set<string>;
+    protected sessionEndProcessed: boolean;
+    protected sessionEndData?: {
+        summary?: string;
+        completedTasks?: string[];
+    };
+    protected lastSummaryRawContent: string;
+    protected idleDetector: UniversalIdleDetector;
+    protected stuckDetector: StuckDetector;
+    constructor(config: BaseWrapperConfig);
+    /** Start the agent process */
+    abstract start(): Promise<void>;
+    /** Stop the agent process */
+    abstract stop(): Promise<void> | void;
+    /** Inject content into the agent */
+    protected abstract performInjection(content: string): Promise<void>;
+    /** Get cleaned output for parsing */
+    protected abstract getCleanOutput(): string;
+    get isRunning(): boolean;
+    get name(): string;
+    getAgentId(): string | undefined;
+    getInjectionMetrics(): InjectionMetrics & {
+        successRate: number;
+    };
+    get pendingMessageCount(): number;
+    /**
+     * Set the PID for process state inspection (Linux only).
+     * Call this after the agent process is started.
+     */
+    protected setIdleDetectorPid(pid: number): void;
+    /**
+     * Start stuck detection. Call after the agent process starts.
+     */
+    protected startStuckDetection(): void;
+    /**
+     * Stop stuck detection. Call when the agent process stops.
+     */
+    protected stopStuckDetection(): void;
+    /**
+     * Check if the agent is currently stuck.
+     */
+    isStuck(): boolean;
+    /**
+     * Get the reason for being stuck (if stuck).
+     */
+    getStuckReason(): StuckReason | null;
+    /**
+     * Feed output to the idle and stuck detectors.
+     * Call this whenever new output is received from the agent.
+     */
+    protected feedIdleDetectorOutput(output: string): void;
+    /**
+     * Check if the agent is idle and ready for injection.
+     * Returns idle state with confidence signals.
+     */
+    protected checkIdleForInjection(): {
+        isIdle: boolean;
+        confidence: number;
+        signals: Array<{
+            source: string;
+            confidence: number;
+        }>;
+    };
+    /**
+     * Wait for the agent to become idle.
+     * Returns when idle or after timeout.
+     */
+    protected waitForIdleState(timeoutMs?: number, pollMs?: number): Promise<{
+        isIdle: boolean;
+        confidence: number;
+    }>;
+    /**
+     * Sort the message queue by priority (urgent first).
+     * Call this before processing messages to ensure proper ordering.
+     */
+    protected sortQueueByPriority(): void;
+    /**
+     * Get the next message from the queue (highest priority first).
+     * Does not remove the message - call dequeueMessage() to remove.
+     */
+    protected peekNextMessage(): QueuedMessage | undefined;
+    /**
+     * Remove and return the next message from the queue.
+     * Messages are sorted by priority before dequeue.
+     */
+    protected dequeueMessage(): QueuedMessage | undefined;
+    /**
+     * Get the priority of the next message in queue.
+     * Returns MESSAGE_PRIORITY.NORMAL if queue is empty.
+     */
+    protected getNextMessagePriority(): MessagePriority;
+    /**
+     * Check if there are urgent messages that should bypass normal idle wait.
+     */
+    protected hasUrgentMessages(): boolean;
+    /**
+     * Handle incoming message from relay
+     */
+    protected handleIncomingMessage(from: string, payload: SendPayload, messageId: string, meta?: SendMeta, originalTo?: string): void;
+    /**
+     * Send an ACK for a sync message after processing completes.
+     * @param messageId - The message ID being acknowledged
+     * @param sync - Sync metadata from the original message
+     * @param response - Response status: 'OK' for success, 'ERROR' for failure
+     * @param responseData - Optional structured response data
+     */
+    protected sendSyncAck(messageId: string, sync: SendMeta['sync'] | undefined, response: 'OK' | 'ERROR' | string, responseData?: unknown): 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
+     */
+    protected sendRelayCommand(cmd: ParsedCommand): void;
+    /**
+     * Parse spawn and release commands from output
+     */
+    protected parseSpawnReleaseCommands(content: string): void;
+    /**
+     * Execute a spawn command
+     */
+    protected executeSpawn(name: string, cli: string, task: string): Promise<void>;
+    /**
+     * Execute a release command
+     */
+    protected executeRelease(name: string): Promise<void>;
+    /**
+     * Initialize agent ID for continuity/resume
+     */
+    protected initializeAgentId(): Promise<void>;
+    /**
+     * Parse continuity commands from output
+     */
+    protected parseContinuityCommands(content: string): Promise<void>;
+    /**
+     * Save a parsed summary to the continuity ledger
+     */
+    protected saveSummaryToLedger(summary: ParsedSummary): Promise<void>;
+    /**
+     * Reset session-specific state for wrapper reuse
+     */
+    resetSessionState(): void;
+    /**
+     * 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.
+     */
+    protected joinContinuationLines(content: string): string;
+    /**
+     * Clean up resources
+     */
+    protected destroyClient(): void;
+}
+//# sourceMappingURL=base-wrapper.d.ts.map