agent-relay 1.5.2 → 2.0.0

package/packages/wrapper/dist/id-generator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Monotonic ID Generator
+ *
+ * Generates unique, lexicographically sortable IDs that are faster than UUID v4.
+ *
+ * Format: <timestamp-base36>-<counter-base36>-<nodeId>
+ * Example: "lxyz5g8-0001-7d2a"
+ *
+ * Properties:
+ * - Lexicographically sortable by time
+ * - Unique across processes (node prefix)
+ * - ~16x faster than UUID v4
+ * - Shorter (20-24 chars vs 36 chars)
+ */
+export declare class IdGenerator {
+    private counter;
+    private readonly prefix;
+    private lastTs;
+    constructor(nodeId?: string);
+    /**
+     * Generate a unique, monotonically increasing ID.
+     */
+    next(): string;
+    /**
+     * Generate a short ID (just timestamp + counter, no node prefix).
+     * Use when you don't need cross-process uniqueness.
+     */
+    short(): string;
+}
+export declare const idGen: IdGenerator;
+/**
+ * Generate a unique ID (drop-in replacement for uuid()).
+ */
+export declare function generateId(): string;
+//# sourceMappingURL=id-generator.d.ts.map

package/packages/wrapper/dist/id-generator.js

@@ -0,0 +1,60 @@
+/**
+ * Monotonic ID Generator
+ *
+ * Generates unique, lexicographically sortable IDs that are faster than UUID v4.
+ *
+ * Format: <timestamp-base36>-<counter-base36>-<nodeId>
+ * Example: "lxyz5g8-0001-7d2a"
+ *
+ * Properties:
+ * - Lexicographically sortable by time
+ * - Unique across processes (node prefix)
+ * - ~16x faster than UUID v4
+ * - Shorter (20-24 chars vs 36 chars)
+ */
+export class IdGenerator {
+    counter = 0;
+    prefix;
+    lastTs = 0;
+    constructor(nodeId) {
+        // Use process ID + random suffix for uniqueness across processes
+        this.prefix = nodeId ?? `${process.pid.toString(36)}${Math.random().toString(36).slice(2, 6)}`;
+    }
+    /**
+     * Generate a unique, monotonically increasing ID.
+     */
+    next() {
+        const now = Date.now();
+        // Reset counter if timestamp changed
+        if (now !== this.lastTs) {
+            this.lastTs = now;
+            this.counter = 0;
+        }
+        const ts = now.toString(36);
+        const seq = (this.counter++).toString(36).padStart(4, '0');
+        return `${ts}-${seq}-${this.prefix}`;
+    }
+    /**
+     * Generate a short ID (just timestamp + counter, no node prefix).
+     * Use when you don't need cross-process uniqueness.
+     */
+    short() {
+        const now = Date.now();
+        if (now !== this.lastTs) {
+            this.lastTs = now;
+            this.counter = 0;
+        }
+        const ts = now.toString(36);
+        const seq = (this.counter++).toString(36).padStart(4, '0');
+        return `${ts}-${seq}`;
+    }
+}
+// Singleton instance for the process
+export const idGen = new IdGenerator();
+/**
+ * Generate a unique ID (drop-in replacement for uuid()).
+ */
+export function generateId() {
+    return idGen.next();
+}
+//# sourceMappingURL=id-generator.js.map

package/packages/wrapper/dist/idle-detector.d.ts

@@ -0,0 +1,110 @@
+/**
+ * UniversalIdleDetector - Detect when an agent is waiting for input
+ *
+ * Works across all CLI tools (Claude, Codex, Gemini, Aider, etc.) by combining:
+ * 1. Process state inspection via /proc/{pid}/stat (Linux, 95% confidence)
+ * 2. Output silence analysis (cross-platform, 60-80% confidence)
+ * 3. Natural ending detection (heuristic, 60% confidence)
+ *
+ * The hybrid approach ensures reliable idle detection regardless of CLI type.
+ */
+export interface IdleSignal {
+    source: 'process_state' | 'output_silence' | 'natural_ending';
+    confidence: number;
+    timestamp: number;
+    details?: string;
+}
+export interface IdleResult {
+    isIdle: boolean;
+    confidence: number;
+    signals: IdleSignal[];
+    /** True if agent appears to be in an editor mode (vim INSERT, etc.) */
+    inEditorMode?: boolean;
+}
+export interface IdleDetectorConfig {
+    /** Minimum silence duration to consider for idle (ms) */
+    minSilenceMs?: number;
+    /** Output buffer size limit */
+    bufferLimit?: number;
+    /** Confidence threshold for idle detection (0-1) */
+    confidenceThreshold?: number;
+}
+/**
+ * Universal idle detector for any CLI-based agent.
+ */
+export declare class UniversalIdleDetector {
+    private lastOutputTime;
+    private outputBuffer;
+    private pid;
+    private config;
+    constructor(config?: IdleDetectorConfig);
+    /**
+     * Set the PID of the agent process to monitor.
+     * Required for Linux process state inspection.
+     */
+    setPid(pid: number): void;
+    /**
+     * Get the current PID being monitored.
+     */
+    getPid(): number | null;
+    /**
+     * Process output chunk from the agent.
+     * Call this for every output received from the agent process.
+     */
+    onOutput(chunk: string): void;
+    /**
+     * Check if the agent process is blocked on read (waiting for input).
+     * This is the most reliable signal - the OS knows when a process is waiting.
+     *
+     * Linux-only; returns null on other platforms.
+     */
+    private isProcessWaitingForInput;
+    /**
+     * Get milliseconds since last output.
+     */
+    private getOutputSilenceMs;
+    /**
+     * Check if the agent is in an editor mode (vim INSERT, REPLACE, etc.).
+     * When in editor mode, message injection should be delayed.
+     */
+    isInEditorMode(): boolean;
+    /**
+     * Check if the last output ends "naturally" (complete thought vs mid-sentence).
+     * Helps distinguish between pauses in output and waiting for input.
+     */
+    private hasNaturalEnding;
+    /**
+     * Determine if the agent is idle and ready for input.
+     * Combines multiple signals for reliability across all CLI types.
+     */
+    checkIdle(options?: {
+        minSilenceMs?: number;
+    }): IdleResult;
+    /**
+     * Wait for idle state with timeout.
+     * Returns the idle result when achieved or after timeout.
+     */
+    waitForIdle(timeoutMs?: number, pollMs?: number): Promise<IdleResult>;
+    /**
+     * Reset state (call when agent starts new response).
+     */
+    reset(): void;
+    /**
+     * Get time since last output in milliseconds.
+     */
+    getTimeSinceLastOutput(): number;
+}
+/**
+ * Get the PID of a process running in a tmux pane.
+ * Uses tmux list-panes with format specifier.
+ */
+export declare function getTmuxPanePid(tmuxPath: string, sessionName: string): Promise<number | null>;
+/**
+ * Create an idle detector configured for the current platform.
+ * On non-Linux platforms, process state inspection is unavailable but
+ * output silence analysis still works.
+ */
+export declare function createIdleDetector(config?: IdleDetectorConfig, options?: {
+    quiet?: boolean;
+}): UniversalIdleDetector;
+//# sourceMappingURL=idle-detector.d.ts.map

package/packages/wrapper/dist/idle-detector.js

@@ -0,0 +1,304 @@
+/**
+ * UniversalIdleDetector - Detect when an agent is waiting for input
+ *
+ * Works across all CLI tools (Claude, Codex, Gemini, Aider, etc.) by combining:
+ * 1. Process state inspection via /proc/{pid}/stat (Linux, 95% confidence)
+ * 2. Output silence analysis (cross-platform, 60-80% confidence)
+ * 3. Natural ending detection (heuristic, 60% confidence)
+ *
+ * The hybrid approach ensures reliable idle detection regardless of CLI type.
+ */
+import fs from 'node:fs';
+const DEFAULT_CONFIG = {
+    minSilenceMs: 500,
+    bufferLimit: 10000,
+    confidenceThreshold: 0.7,
+};
+/**
+ * Universal idle detector for any CLI-based agent.
+ */
+export class UniversalIdleDetector {
+    lastOutputTime = 0;
+    outputBuffer = '';
+    pid = null;
+    config;
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        // Initialize lastOutputTime to now to avoid immediate false positives
+        this.lastOutputTime = Date.now();
+    }
+    /**
+     * Set the PID of the agent process to monitor.
+     * Required for Linux process state inspection.
+     */
+    setPid(pid) {
+        this.pid = pid;
+    }
+    /**
+     * Get the current PID being monitored.
+     */
+    getPid() {
+        return this.pid;
+    }
+    /**
+     * Process output chunk from the agent.
+     * Call this for every output received from the agent process.
+     */
+    onOutput(chunk) {
+        this.lastOutputTime = Date.now();
+        this.outputBuffer += chunk;
+        // Keep buffer bounded
+        if (this.outputBuffer.length > this.config.bufferLimit) {
+            this.outputBuffer = this.outputBuffer.slice(-Math.floor(this.config.bufferLimit / 2));
+        }
+    }
+    /**
+     * Check if the agent process is blocked on read (waiting for input).
+     * This is the most reliable signal - the OS knows when a process is waiting.
+     *
+     * Linux-only; returns null on other platforms.
+     */
+    isProcessWaitingForInput() {
+        if (process.platform !== 'linux' || !this.pid) {
+            return null; // Can't determine on non-Linux
+        }
+        try {
+            // Check process state from /proc/{pid}/stat
+            // State codes: R=running, S=sleeping, D=disk sleep, Z=zombie, T=stopped
+            const statPath = `/proc/${this.pid}/stat`;
+            const stat = fs.readFileSync(statPath, 'utf-8');
+            const fields = stat.split(' ');
+            const state = fields[2]; // Third field is state
+            // S (sleeping) often means waiting for I/O
+            if (state !== 'S') {
+                return { waiting: false }; // Running or other state = not waiting
+            }
+            // More precise: check what the process is blocked on
+            const wchanPath = `/proc/${this.pid}/wchan`;
+            const wchan = fs.readFileSync(wchanPath, 'utf-8').trim();
+            // Common wait channels for terminal input
+            const inputWaitChannels = [
+                'wait_woken',
+                'poll_schedule_timeout',
+                'do_select',
+                'n_tty_read',
+                'unix_stream_read_generic',
+                'pipe_read',
+                'ep_poll', // epoll wait
+                'futex_wait_queue', // sometimes seen
+            ];
+            const isWaiting = inputWaitChannels.some(ch => wchan.includes(ch));
+            return { waiting: isWaiting, wchan };
+        }
+        catch {
+            return null; // Process may have exited or permission denied
+        }
+    }
+    /**
+     * Get milliseconds since last output.
+     */
+    getOutputSilenceMs() {
+        return Date.now() - this.lastOutputTime;
+    }
+    /**
+     * Check if the agent is in an editor mode (vim INSERT, REPLACE, etc.).
+     * When in editor mode, message injection should be delayed.
+     */
+    isInEditorMode() {
+        // Check the last portion of output for editor mode indicators
+        const lastOutput = this.outputBuffer.slice(-500);
+        // Vim/Neovim mode indicators
+        const editorModePatterns = [
+            /-- INSERT --/i,
+            /-- REPLACE --/i,
+            /-- VISUAL --/i,
+            /-- VISUAL LINE --/i,
+            /-- VISUAL BLOCK --/i,
+            /-- SELECT --/i,
+            /-- TERMINAL --/i,
+            // Emacs indicators
+            /\*\*\* Emacs/,
+            /M-x/,
+            // nano indicators
+            /GNU nano/,
+            /\^G Get Help/,
+            // less/more pager
+            /:\s*$/, // Pager prompt
+            /lines \d+-\d+/, // Pager line indicator
+            // Git interactive rebase
+            /pick [a-f0-9]+/,
+            /# Rebase [a-f0-9]+/,
+        ];
+        return editorModePatterns.some(pattern => pattern.test(lastOutput));
+    }
+    /**
+     * Check if the last output ends "naturally" (complete thought vs mid-sentence).
+     * Helps distinguish between pauses in output and waiting for input.
+     */
+    hasNaturalEnding() {
+        const lastChars = this.outputBuffer.slice(-100).trim();
+        if (lastChars.length === 0)
+            return true;
+        // Positive signals: output ended cleanly
+        const naturalEndings = [
+            /[.!?]\s*$/, // Sentence ended
+            /```\s*$/, // Code block closed
+            /\n\n$/, // Paragraph break
+            />\s*$/, // Prompt character
+            /\$\s*$/, // Shell prompt
+            />>>\s*$/, // Python/Aider prompt
+            /❯\s*$/, // Fancy prompts
+            /λ\s*$/, // Lambda prompts
+            /→\s*$/, // Arrow prompts
+        ];
+        // Negative signals: output mid-thought
+        const midThought = [
+            /[,;:]\s*$/, // Comma, semicolon = more coming
+            /\w$/, // Ended mid-word (no trailing space)
+            /[-–—]\s*$/, // Dash = continuation
+            /\(\s*$/, // Open paren
+            /\[\s*$/, // Open bracket
+            /\{\s*$/, // Open brace
+            /\\\s*$/, // Line continuation
+        ];
+        for (const pattern of midThought) {
+            if (pattern.test(lastChars)) {
+                return false;
+            }
+        }
+        for (const pattern of naturalEndings) {
+            if (pattern.test(lastChars)) {
+                return true;
+            }
+        }
+        // Default: assume natural if no negative signals and some silence
+        return true;
+    }
+    /**
+     * Determine if the agent is idle and ready for input.
+     * Combines multiple signals for reliability across all CLI types.
+     */
+    checkIdle(options = {}) {
+        const minSilence = options.minSilenceMs ?? this.config.minSilenceMs;
+        const signals = [];
+        // Signal 1: Process state (most reliable on Linux)
+        const processState = this.isProcessWaitingForInput();
+        if (processState !== null) {
+            if (processState.waiting) {
+                signals.push({
+                    source: 'process_state',
+                    confidence: 0.95, // Very high - OS-level truth
+                    timestamp: Date.now(),
+                    details: processState.wchan,
+                });
+            }
+            else {
+                // Process is actively running - definitely not idle
+                return {
+                    isIdle: false,
+                    confidence: 0.95,
+                    signals: [{
+                            source: 'process_state',
+                            confidence: 0.95,
+                            timestamp: Date.now(),
+                            details: 'process running',
+                        }],
+                    inEditorMode: this.isInEditorMode(),
+                };
+            }
+        }
+        // processState === null means we can't determine (non-Linux)
+        // Signal 2: Output silence
+        const silenceMs = this.getOutputSilenceMs();
+        if (silenceMs > minSilence) {
+            // Confidence scales with silence duration (up to 0.8)
+            // 500ms = 0.13, 1000ms = 0.27, 2000ms = 0.53, 3000ms = 0.8
+            const silenceConfidence = Math.min(silenceMs / 3000, 0.8);
+            signals.push({
+                source: 'output_silence',
+                confidence: silenceConfidence,
+                timestamp: Date.now(),
+                details: `${silenceMs}ms`,
+            });
+        }
+        // Signal 3: Natural ending (only if some silence)
+        if (silenceMs > 200 && this.hasNaturalEnding()) {
+            signals.push({
+                source: 'natural_ending',
+                confidence: 0.6,
+                timestamp: Date.now(),
+            });
+        }
+        // No signals = not idle
+        if (signals.length === 0) {
+            return { isIdle: false, confidence: 0, signals: [], inEditorMode: this.isInEditorMode() };
+        }
+        // Combine signals
+        // Use max confidence, boosted if multiple signals agree
+        const maxConfidence = Math.max(...signals.map(s => s.confidence));
+        const boost = signals.length > 1 ? 0.1 : 0;
+        const combinedConfidence = Math.min(maxConfidence + boost, 1.0);
+        return {
+            isIdle: combinedConfidence >= this.config.confidenceThreshold,
+            confidence: combinedConfidence,
+            signals,
+            inEditorMode: this.isInEditorMode(),
+        };
+    }
+    /**
+     * Wait for idle state with timeout.
+     * Returns the idle result when achieved or after timeout.
+     */
+    async waitForIdle(timeoutMs = 30000, pollMs = 200) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < timeoutMs) {
+            const result = this.checkIdle();
+            if (result.isIdle) {
+                return result;
+            }
+            await new Promise(r => setTimeout(r, pollMs));
+        }
+        // Timeout - return current state
+        return this.checkIdle();
+    }
+    /**
+     * Reset state (call when agent starts new response).
+     */
+    reset() {
+        this.outputBuffer = '';
+        this.lastOutputTime = Date.now();
+    }
+    /**
+     * Get time since last output in milliseconds.
+     */
+    getTimeSinceLastOutput() {
+        return this.getOutputSilenceMs();
+    }
+}
+/**
+ * Get the PID of a process running in a tmux pane.
+ * Uses tmux list-panes with format specifier.
+ */
+export async function getTmuxPanePid(tmuxPath, sessionName) {
+    const { exec } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execAsync = promisify(exec);
+    try {
+        // Get the PID of the command running in the pane
+        const { stdout } = await execAsync(`"${tmuxPath}" list-panes -t ${sessionName} -F "#{pane_pid}" 2>/dev/null`);
+        const pid = parseInt(stdout.trim(), 10);
+        return isNaN(pid) ? null : pid;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create an idle detector configured for the current platform.
+ * On non-Linux platforms, process state inspection is unavailable but
+ * output silence analysis still works.
+ */
+export function createIdleDetector(config = {}, options = {}) {
+    return new UniversalIdleDetector(config);
+}
+//# sourceMappingURL=idle-detector.js.map

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

@@ -0,0 +1,37 @@
+/**
+ * @agent-relay/wrapper
+ *
+ * CLI agent wrappers for Agent Relay.
+ * Phase 2B extraction - utilities and types.
+ */
+export { IdGenerator, idGen, generateId } from './id-generator.js';
+export { getTmuxPath, resolveTmux, isTmuxAvailable, checkTmuxVersion, getBundledTmuxDir, getBundledTmuxPath, getPlatformIdentifier, TmuxNotFoundError, type TmuxInfo, BUNDLED_TMUX_DIR, BUNDLED_TMUX_PATH, MIN_TMUX_VERSION, } from './tmux-resolver.js';
+export { OutputParser, parseSummaryFromOutput, parseSummaryWithDetails, parseSessionEndFromOutput, parseRelayMetadataFromOutput, isPlaceholderTarget, type ParsedCommand, type ParserOptions, type ParsedSummary, type ParsedMessageMetadata, type MetadataParseResult, type SummaryParseResult, type SessionEndMarker, } from './parser.js';
+export { stripAnsi, sleep, getDefaultRelayPrefix, buildInjectionString, injectWithRetry, INJECTION_CONSTANTS, CLI_QUIRKS, type QueuedMessage, type InjectionResult, type InjectionMetrics, type CliType, type InjectionCallbacks, } from './shared.js';
+export { AUTH_REVOCATION_PATTERNS, AUTH_FALSE_POSITIVE_PATTERNS, PROVIDER_AUTH_PATTERNS, detectProviderAuthRevocation, type AuthRevocationResult, } from './auth-detection.js';
+export { UniversalIdleDetector, getTmuxPanePid, type IdleSignal, type IdleResult, type IdleDetectorConfig, } from './idle-detector.js';
+export { TrajectoryIntegration, getTrajectoryIntegration, detectPhaseFromContent, detectToolCalls, detectErrors, getCompactTrailInstructions, getTrailEnvVars, getTrailInstructions, isTrailAvailable, startTrajectory, getTrajectoryStatus, transitionPhase, recordDecision, recordEvent, recordMessage, completeTrajectory, abandonTrajectory, listTrajectorySteps, getTrajectoryHistory, type PDEROPhase, type StartTrajectoryOptions, type CompleteTrajectoryOptions, type DecisionOptions, type TrajectoryStepData, type TrajectoryHistoryEntry, type DetectedToolCall, type DetectedError, } from './trajectory-integration.js';
+export { type InjectionFailedEvent, type SummaryEvent, type SessionEndEvent, type AuthRevokedEvent, } from './wrapper-types.js';
+export { StuckDetector, type StuckEvent, type StuckReason, type StuckDetectorConfig, } from './stuck-detector.js';
+export { composeForAgent, getAvailableRoles, parseRoleFromProfile, clearPromptCache, type AgentRole, type AgentProfile, type ComposedPrompt, } from './prompt-composer.js';
+/**
+ * Relay client (internal use only)
+ *
+ * @deprecated **MIGRATION REQUIRED** - Use `@agent-relay/sdk` instead.
+ *
+ * ```typescript
+ * // BEFORE (deprecated)
+ * import { RelayClient } from '@agent-relay/wrapper';
+ *
+ * // AFTER (recommended)
+ * import { RelayClient } from '@agent-relay/sdk';
+ * ```
+ *
+ * This export is retained only for internal daemon/wrapper integration.
+ * External consumers should migrate to `@agent-relay/sdk`.
+ * This export will be removed in a future major version.
+ */
+export { RelayClient, type ClientState, type ClientConfig, type SyncOptions, } from './client.js';
+export { BaseWrapper, type BaseWrapperConfig, } from './base-wrapper.js';
+export { RelayPtyOrchestrator, type RelayPtyOrchestratorConfig, } from './relay-pty-orchestrator.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/wrapper/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * @agent-relay/wrapper
+ *
+ * CLI agent wrappers for Agent Relay.
+ * Phase 2B extraction - utilities and types.
+ */
+// ID generation
+export { IdGenerator, idGen, generateId } from './id-generator.js';
+// Tmux binary resolution
+export { getTmuxPath, resolveTmux, isTmuxAvailable, checkTmuxVersion, getBundledTmuxDir, getBundledTmuxPath, getPlatformIdentifier, TmuxNotFoundError, BUNDLED_TMUX_DIR, BUNDLED_TMUX_PATH, MIN_TMUX_VERSION, } from './tmux-resolver.js';
+// Output parser
+export { OutputParser, parseSummaryFromOutput, parseSummaryWithDetails, parseSessionEndFromOutput, parseRelayMetadataFromOutput, isPlaceholderTarget, } from './parser.js';
+// Shared wrapper utilities and types
+export { stripAnsi, sleep, getDefaultRelayPrefix, buildInjectionString, injectWithRetry, INJECTION_CONSTANTS, CLI_QUIRKS, } from './shared.js';
+// Auth revocation detection
+export { AUTH_REVOCATION_PATTERNS, AUTH_FALSE_POSITIVE_PATTERNS, PROVIDER_AUTH_PATTERNS, detectProviderAuthRevocation, } from './auth-detection.js';
+// Idle detection
+export { UniversalIdleDetector, getTmuxPanePid, } from './idle-detector.js';
+// Trajectory integration (PDERO paradigm tracking)
+export { TrajectoryIntegration, getTrajectoryIntegration, detectPhaseFromContent, detectToolCalls, detectErrors, getCompactTrailInstructions, getTrailEnvVars, getTrailInstructions, isTrailAvailable, startTrajectory, getTrajectoryStatus, transitionPhase, recordDecision, recordEvent, recordMessage, completeTrajectory, abandonTrajectory, listTrajectorySteps, getTrajectoryHistory, } from './trajectory-integration.js';
+// Stuck detection
+export { StuckDetector, } from './stuck-detector.js';
+// Prompt composition
+export { composeForAgent, getAvailableRoles, parseRoleFromProfile, clearPromptCache, } from './prompt-composer.js';
+/**
+ * Relay client (internal use only)
+ *
+ * @deprecated **MIGRATION REQUIRED** - Use `@agent-relay/sdk` instead.
+ *
+ * ```typescript
+ * // BEFORE (deprecated)
+ * import { RelayClient } from '@agent-relay/wrapper';
+ *
+ * // AFTER (recommended)
+ * import { RelayClient } from '@agent-relay/sdk';
+ * ```
+ *
+ * This export is retained only for internal daemon/wrapper integration.
+ * External consumers should migrate to `@agent-relay/sdk`.
+ * This export will be removed in a future major version.
+ */
+export { RelayClient, } from './client.js';
+// Base wrapper class
+export { BaseWrapper, } from './base-wrapper.js';
+// RelayPtyOrchestrator (relay-pty Rust binary)
+export { RelayPtyOrchestrator, } from './relay-pty-orchestrator.js';
+//# sourceMappingURL=index.js.map