@agent-relay/wrapper 0.1.0

package/dist/base-wrapper.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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 } 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;
+    }>;
+    /**
+     * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-wrapper.d.ts","sourceRoot":"","sources":["../src/base-wrapper.ts"],"names":[],"mappings":"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"}