agent-relay 2.0.0 → 2.0.4

package/packages/sdk/dist/discovery.js

@@ -0,0 +1,126 @@
+/**
+ * Socket Discovery for Agent Relay SDK
+ *
+ * Discovers the daemon socket path for local development and cloud environments.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+/**
+ * Find project root by looking for common markers.
+ * Scans up from startDir until it finds a marker or hits the filesystem root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+    let current = startDir;
+    const markers = ['.git', 'package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', '.agent-relay'];
+    // Limit iterations to prevent infinite loops
+    for (let i = 0; i < 100; i++) {
+        for (const marker of markers) {
+            if (existsSync(join(current, marker))) {
+                return current;
+            }
+        }
+        const parent = join(current, '..');
+        if (parent === current)
+            break; // Reached root
+        current = parent;
+    }
+    return null;
+}
+/**
+ * Discover the relay daemon socket path.
+ *
+ * Discovery order:
+ * 1. RELAY_SOCKET environment variable (explicit override)
+ * 2. Cloud workspace socket (if WORKSPACE_ID is set)
+ * 3. Project-local socket ({projectRoot}/.agent-relay/relay.sock)
+ * 4. Legacy fallback (/tmp/agent-relay.sock)
+ *
+ * @param cwd - Working directory to start search from (default: process.cwd())
+ * @returns Discovery result with socket path and metadata
+ */
+export function discoverSocket(cwd) {
+    const startDir = cwd || process.cwd();
+    // 1. Explicit socket path from environment
+    const socketEnv = process.env.RELAY_SOCKET;
+    if (socketEnv && existsSync(socketEnv)) {
+        return {
+            socketPath: socketEnv,
+            projectId: process.env.RELAY_PROJECT || 'env',
+            source: 'env',
+        };
+    }
+    // 2. Cloud workspace socket (if WORKSPACE_ID is set)
+    const workspaceId = process.env.WORKSPACE_ID;
+    if (workspaceId) {
+        const cloudSocket = `/tmp/relay/${workspaceId}/sockets/daemon.sock`;
+        if (existsSync(cloudSocket)) {
+            return {
+                socketPath: cloudSocket,
+                projectId: workspaceId,
+                source: 'cloud',
+            };
+        }
+    }
+    // 3. Project-local socket
+    // First try cwd, then scan up to find project root
+    const projectRoot = findProjectRoot(startDir);
+    const searchDirs = [startDir];
+    if (projectRoot && projectRoot !== startDir) {
+        searchDirs.push(projectRoot);
+    }
+    for (const dir of searchDirs) {
+        const projectLocalSocket = join(dir, '.agent-relay', 'relay.sock');
+        if (existsSync(projectLocalSocket)) {
+            // Read project ID from marker file if available
+            let projectId = 'local';
+            const markerPath = join(dir, '.agent-relay', '.project');
+            if (existsSync(markerPath)) {
+                try {
+                    const marker = JSON.parse(readFileSync(markerPath, 'utf-8'));
+                    projectId = marker.projectId || 'local';
+                }
+                catch {
+                    // Ignore marker read errors
+                }
+            }
+            return {
+                socketPath: projectLocalSocket,
+                projectId,
+                source: 'project',
+            };
+        }
+    }
+    // 4. Legacy fallback
+    const legacySocket = '/tmp/agent-relay.sock';
+    if (existsSync(legacySocket)) {
+        return {
+            socketPath: legacySocket,
+            projectId: 'legacy',
+            source: 'legacy',
+        };
+    }
+    // Also check ~/.agent-relay for legacy global installations
+    const homeSocket = join(homedir(), '.agent-relay', 'relay.sock');
+    if (existsSync(homeSocket)) {
+        return {
+            socketPath: homeSocket,
+            projectId: 'home',
+            source: 'legacy',
+        };
+    }
+    // Return legacy path even if it doesn't exist (will fail on connect)
+    return {
+        socketPath: legacySocket,
+        projectId: 'unknown',
+        source: 'legacy',
+    };
+}
+/**
+ * Get the default socket path using discovery.
+ * Convenience function that returns just the path.
+ */
+export function getDefaultSocketPath(cwd) {
+    return discoverSocket(cwd).socketPath;
+}
+//# sourceMappingURL=discovery.js.map

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

@@ -29,4 +29,5 @@ export { RelayClient, type ClientState, type ClientConfig, type SyncOptions, } f
 export { createRelay, createPair, type Relay, type RelayConfig, } from './standalone.js';
 export { PROTOCOL_VERSION, type MessageType, type PayloadKind, type Envelope, type EntityType, type SendPayload, type SendMeta, type SyncMeta, type DeliveryInfo, type AckPayload, type ErrorCode, type ErrorPayload, type SpeakOnTrigger, type ShadowConfig, type SpawnPayload, type SpawnResultPayload, type ReleasePayload, type ReleaseResultPayload, type ChannelMessagePayload, type ChannelJoinPayload, type ChannelLeavePayload, } from './protocol/index.js';
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+export { discoverSocket, getDefaultSocketPath, type DiscoveryResult, } from './discovery.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/sdk/dist/index.js

@@ -33,4 +33,6 @@ export { createRelay, createPair, } from './standalone.js';
 export { PROTOCOL_VERSION, } from './protocol/index.js';
 // Framing utilities
 export { encodeFrame, encodeFrameLegacy, FrameParser, MAX_FRAME_BYTES, } from './protocol/index.js';
+// Socket discovery utilities
+export { discoverSocket, getDefaultSocketPath, } from './discovery.js';
 //# sourceMappingURL=index.js.map

package/packages/sdk/dist/standalone.js

@@ -52,6 +52,7 @@ export async function createRelay(config = {}) {
     // Lazy-load daemon to keep SDK lightweight for client-only users
     let Daemon;
     try {
+        // @ts-ignore - daemon is an optional peer dependency, may not be installed
         const daemonModule = await import('@agent-relay/daemon');
         Daemon = daemonModule.Daemon;
     }

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Lightweight SDK for agent-to-agent communication via Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.0"
+    "@agent-relay/protocol": "2.0.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/packages/spawner/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/spawner",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Agent spawning types and utilities for Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/AgentWorkforce/relay.git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
     "directory": "packages/spawner"
   },
   "license": "MIT"

package/packages/state/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/state",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Agent state persistence for non-hook CLIs (Codex, Gemini, etc.)",
   "type": "module",
   "main": "dist/index.js",
@@ -28,5 +28,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/state"
   }
 }

package/packages/storage/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/storage",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Storage adapters and interfaces for Relay message/session persistence",
   "type": "module",
   "main": "dist/index.js",
@@ -56,7 +56,7 @@
     }
   },
   "dependencies": {
-    "@agent-relay/protocol": "2.0.0"
+    "@agent-relay/protocol": "2.0.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",
@@ -65,5 +65,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/storage"
   }
 }

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "2.0.0"
+    "@agent-relay/config": "2.0.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",
@@ -31,5 +31,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/trajectory"
   }
 }

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/resiliency": "2.0.0"
+    "@agent-relay/resiliency": "2.0.4"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",
@@ -31,5 +31,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/user-directory"
   }
 }

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "2.0.0",
+  "version": "2.0.4",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/index.js",
@@ -71,5 +71,10 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentWorkforce/relay.git",
+    "directory": "packages/utils"
   }
 }

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

@@ -19,7 +19,7 @@ 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 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';
@@ -161,6 +161,30 @@ export declare abstract class BaseWrapper extends EventEmitter {
         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
      */

package/packages/wrapper/dist/base-wrapper.js

@@ -17,7 +17,7 @@
 import { EventEmitter } from 'node:events';
 import { RelayClient } from './client.js';
 import { isPlaceholderTarget } from './parser.js';
-import { getDefaultRelayPrefix, detectCliType, createInjectionMetrics, } from './shared.js';
+import { getDefaultRelayPrefix, detectCliType, createInjectionMetrics, sortByPriority, getPriorityFromImportance, MESSAGE_PRIORITY, } from './shared.js';
 import { DEFAULT_IDLE_BEFORE_INJECT_MS, DEFAULT_IDLE_CONFIDENCE_THRESHOLD, } from '@agent-relay/config/relay-config';
 import { getContinuityManager, parseContinuityCommand, hasContinuityCommand, } from '@agent-relay/continuity';
 import { UniversalIdleDetector } from './idle-detector.js';
@@ -168,7 +168,7 @@ export class BaseWrapper extends EventEmitter {
      */
     checkIdleForInjection() {
         return this.idleDetector.checkIdle({
-            minSilenceMs: this.config.idleBeforeInjectMs ?? 1500,
+            minSilenceMs: this.config.idleBeforeInjectMs ?? DEFAULT_IDLE_BEFORE_INJECT_MS,
         });
     }
     /**
@@ -179,6 +179,48 @@ export class BaseWrapper extends EventEmitter {
         return this.idleDetector.waitForIdle(timeoutMs, pollMs);
     }
     // =========================================================================
+    // Priority queue management
+    // =========================================================================
+    /**
+     * Sort the message queue by priority (urgent first).
+     * Call this before processing messages to ensure proper ordering.
+     */
+    sortQueueByPriority() {
+        if (this.messageQueue.length > 1) {
+            this.messageQueue = sortByPriority(this.messageQueue);
+        }
+    }
+    /**
+     * Get the next message from the queue (highest priority first).
+     * Does not remove the message - call dequeueMessage() to remove.
+     */
+    peekNextMessage() {
+        this.sortQueueByPriority();
+        return this.messageQueue[0];
+    }
+    /**
+     * Remove and return the next message from the queue.
+     * Messages are sorted by priority before dequeue.
+     */
+    dequeueMessage() {
+        this.sortQueueByPriority();
+        return this.messageQueue.shift();
+    }
+    /**
+     * Get the priority of the next message in queue.
+     * Returns MESSAGE_PRIORITY.NORMAL if queue is empty.
+     */
+    getNextMessagePriority() {
+        const next = this.messageQueue[0];
+        return next ? getPriorityFromImportance(next.importance) : MESSAGE_PRIORITY.NORMAL;
+    }
+    /**
+     * Check if there are urgent messages that should bypass normal idle wait.
+     */
+    hasUrgentMessages() {
+        return this.messageQueue.some(msg => getPriorityFromImportance(msg.importance) === MESSAGE_PRIORITY.URGENT);
+    }
+    // =========================================================================
     // Message handling
     // =========================================================================
     /**

package/packages/wrapper/dist/relay-pty-orchestrator.d.ts

@@ -98,6 +98,8 @@ export declare class RelayPtyOrchestrator extends BaseWrapper {
     private hasReceivedOutput;
     private queueMonitorTimer?;
     private readonly QUEUE_MONITOR_INTERVAL_MS;
+    private injectionStartTime;
+    private readonly MAX_INJECTION_STUCK_MS;
     private protocolWatcher?;
     private protocolReminderCooldown;
     private readonly PROTOCOL_REMINDER_COOLDOWN_MS;

package/packages/wrapper/dist/relay-pty-orchestrator.js

@@ -74,6 +74,8 @@ export class RelayPtyOrchestrator extends BaseWrapper {
     // Queue monitor for stuck message detection
     queueMonitorTimer;
     QUEUE_MONITOR_INTERVAL_MS = 30000; // Check every 30 seconds
+    injectionStartTime = 0; // Track when isInjecting was set to true
+    MAX_INJECTION_STUCK_MS = 60000; // Force reset after 60 seconds
     // Protocol monitor for detecting agent mistakes (e.g., empty AGENT_RELAY_NAME)
     protocolWatcher;
     protocolReminderCooldown = 0; // Prevent spam
@@ -130,8 +132,15 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         else {
             // Local mode: use ~/.agent-relay paths directly (no symlinks needed)
             this._outboxPath = this._canonicalOutboxPath;
-            // Socket at ~/.agent-relay/{projectId}/sockets/{agentName}.sock
-            this.socketPath = join(projectPaths.dataDir, 'sockets', `${config.name}.sock`);
+            // Socket at {projectRoot}/.agent-relay/sockets/{agentName}.sock
+            let localSocketPath = join(projectPaths.dataDir, 'sockets', `${config.name}.sock`);
+            // If socket path is too long, fall back to /tmp/relay-local/{projectId}/sockets/
+            if (localSocketPath.length > MAX_SOCKET_PATH_LENGTH) {
+                const tmpSocketPath = `/tmp/relay-local/${projectPaths.projectId}/sockets/${config.name}.sock`;
+                console.warn(`[relay-pty-orchestrator:${config.name}] Socket path too long (${localSocketPath.length} chars); using /tmp fallback`);
+                localSocketPath = tmpSocketPath;
+            }
+            this.socketPath = localSocketPath;
             // No legacy path needed for local mode
             this._legacyOutboxPath = this._outboxPath;
         }
@@ -226,7 +235,7 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                     if (existsSync(linkPath)) {
                         try {
                             const stats = lstatSync(linkPath);
-                            if (stats.isSymbolicLink()) {
+                            if (stats.isSymbolicLink() || stats.isFile()) {
                                 unlinkSync(linkPath);
                             }
                             else if (stats.isDirectory()) {
@@ -946,6 +955,23 @@ export class RelayPtyOrchestrator extends BaseWrapper {
                 this.log(` Message ${pending.shortId} delivered (interactive mode) ✓`);
                 return;
             }
+            // Skip verification if queue is backing up - trust Rust's delivery status
+            // relay-pty writes directly to PTY which is more reliable than tmux
+            const queueBackingUp = this.messageQueue.length >= 2;
+            if (queueBackingUp) {
+                this.log(` Queue backing up (${this.messageQueue.length} pending), skipping verification for ${pending.shortId}`);
+                clearTimeout(pending.timeout);
+                this.pendingInjections.delete(response.id);
+                if (pending.retryCount === 0) {
+                    this.injectionMetrics.successFirstTry++;
+                }
+                else {
+                    this.injectionMetrics.successWithRetry++;
+                }
+                this.injectionMetrics.total++;
+                pending.resolve(true);
+                return;
+            }
             // Give a brief moment for output to be captured
             await sleep(100);
             // Verify the message pattern appears in captured output
@@ -1146,6 +1172,7 @@ export class RelayPtyOrchestrator extends BaseWrapper {
             return;
         }
         this.isInjecting = true;
+        this.injectionStartTime = Date.now();
         const msg = this.messageQueue.shift();
         const retryCount = msg._retryCount ?? 0;
         const bodyPreview = msg.body.substring(0, 50).replace(/\n/g, '\\n');
@@ -1189,6 +1216,7 @@ export class RelayPtyOrchestrator extends BaseWrapper {
         }
         finally {
             this.isInjecting = false;
+            this.injectionStartTime = 0;
             // Process next message after adaptive delay (faster when healthy, slower under stress)
             if (this.messageQueue.length > 0 && !this.backpressureActive) {
                 const delay = this.throttle.getDelay();
@@ -1354,19 +1382,20 @@ EOF
 Then output: \`->relay-file:msg\``,
             file_in_root: `⚠️ **Protocol Issue Detected**
 
-Found file "${filename}" directly in the outbox directory instead of in your agent's subdirectory.
+Found file "${filename}" directly in the outbox root instead of using the proper path.
 Your agent name is: **${this.config.name}**
 
-Correct outbox path: \`$AGENT_RELAY_OUTBOX\`
+The \`$AGENT_RELAY_OUTBOX\` path already points to your agent's directory.
+Write files directly inside it:
 
-Files should be created in your agent's directory:
 \`\`\`bash
-cat > $AGENT_RELAY_OUTBOX/${filename} << 'EOF'
+cat > $AGENT_RELAY_OUTBOX/msg << 'EOF'
 TO: TargetAgent
 
 Your message here
 EOF
-\`\`\``,
+\`\`\`
+Then output: \`->relay-file:msg\``,
         };
         const reminder = reminders[issue];
         if (reminder) {
@@ -1482,9 +1511,25 @@ Then output: \`->relay-file:spawn\`
         if (this.messageQueue.length === 0) {
             return;
         }
-        // Skip if currently injecting (processing is in progress)
+        // Check if currently injecting
         if (this.isInjecting) {
-            return;
+            // Check if injection has been stuck for too long
+            const stuckDuration = Date.now() - this.injectionStartTime;
+            if (stuckDuration > this.MAX_INJECTION_STUCK_MS) {
+                this.logError(` ⚠️ Injection stuck for ${Math.round(stuckDuration / 1000)}s - force resetting`);
+                this.isInjecting = false;
+                this.injectionStartTime = 0;
+                // Clear any pending injections that might be stuck
+                for (const [id, pending] of this.pendingInjections) {
+                    clearTimeout(pending.timeout);
+                    this.logError(` Clearing stuck pending injection: ${id.substring(0, 8)}`);
+                }
+                this.pendingInjections.clear();
+                // Continue to process the queue below
+            }
+            else {
+                return; // Still within normal injection time
+            }
         }
         // Skip if backpressure is active
         if (this.backpressureActive) {

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

@@ -5,6 +5,31 @@
  * wrapper implementations and reduce duplication.
  */
 import type { SyncMeta } from '@agent-relay/protocol/types';
+/**
+ * Message priority levels for queue ordering.
+ * Lower numbers = higher priority (processed first).
+ */
+export declare const MESSAGE_PRIORITY: {
+    /** System-critical messages (sync ACKs, errors) - skip idle wait */
+    readonly URGENT: 0;
+    /** Time-sensitive messages (user requests) - reduced idle wait */
+    readonly HIGH: 1;
+    /** Normal agent-to-agent messages */
+    readonly NORMAL: 2;
+    /** Batch/background messages - can wait longer */
+    readonly LOW: 3;
+};
+export type MessagePriority = typeof MESSAGE_PRIORITY[keyof typeof MESSAGE_PRIORITY];
+/**
+ * Get priority from importance value or default to NORMAL.
+ * Maps importance number to priority level.
+ */
+export declare function getPriorityFromImportance(importance?: number): MessagePriority;
+/**
+ * Sort messages by priority (lower number = higher priority).
+ * Stable sort - maintains order within same priority.
+ */
+export declare function sortByPriority(messages: QueuedMessage[]): QueuedMessage[];
 /**
  * Message queued for injection into an agent's terminal
  */

package/packages/wrapper/dist/shared.js

@@ -4,6 +4,46 @@
  * This module contains common code to prevent drift between the two
  * wrapper implementations and reduce duplication.
  */
+/**
+ * Message priority levels for queue ordering.
+ * Lower numbers = higher priority (processed first).
+ */
+export const MESSAGE_PRIORITY = {
+    /** System-critical messages (sync ACKs, errors) - skip idle wait */
+    URGENT: 0,
+    /** Time-sensitive messages (user requests) - reduced idle wait */
+    HIGH: 1,
+    /** Normal agent-to-agent messages */
+    NORMAL: 2,
+    /** Batch/background messages - can wait longer */
+    LOW: 3,
+};
+/**
+ * Get priority from importance value or default to NORMAL.
+ * Maps importance number to priority level.
+ */
+export function getPriorityFromImportance(importance) {
+    if (importance === undefined)
+        return MESSAGE_PRIORITY.NORMAL;
+    if (importance >= 90)
+        return MESSAGE_PRIORITY.URGENT;
+    if (importance >= 70)
+        return MESSAGE_PRIORITY.HIGH;
+    if (importance >= 30)
+        return MESSAGE_PRIORITY.NORMAL;
+    return MESSAGE_PRIORITY.LOW;
+}
+/**
+ * Sort messages by priority (lower number = higher priority).
+ * Stable sort - maintains order within same priority.
+ */
+export function sortByPriority(messages) {
+    return [...messages].sort((a, b) => {
+        const priorityA = getPriorityFromImportance(a.importance);
+        const priorityB = getPriorityFromImportance(b.importance);
+        return priorityA - priorityB;
+    });
+}
 /**
  * Injection timing constants
  *

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

@@ -271,6 +271,7 @@ export declare class TmuxWrapper extends BaseWrapper {
     /**
      * Check if we should inject a message.
      * Uses UniversalIdleDetector (from BaseWrapper) for robust cross-CLI idle detection.
+     * Processes messages by priority (urgent first).
      */
     private checkForInjectionOpportunity;
     /**
@@ -335,6 +336,12 @@ export declare class TmuxWrapper extends BaseWrapper {
     private capturePaneSignature;
     /**
      * Wait for pane output to stabilize before injecting to avoid interleaving with ongoing output.
+     * Uses adaptive timeout based on idle detector confidence for faster injection when safe.
+     *
+     * @param maxWaitMs - Maximum time to wait (default from config)
+     * @param pollIntervalMs - Polling interval (default from config)
+     * @param requiredStablePolls - Consecutive stable polls needed (default 2)
+     * @param priority - Message priority (lower = more urgent, can use shorter timeout)
      */
     private waitForStablePane;
     /**