aegis-bridge 2.3.11 → 2.4.0

package/dist/error-categories.d.ts

@@ -0,0 +1,39 @@
+/**
+ * error-categories.ts — Structured error categorization and retry guidance.
+ *
+ * Issue #701: Provides an ErrorCode enum, categorize() function to inspect
+ * unknown errors and return structured metadata, and shouldRetry() helper.
+ */
+/** String enum of Aegis error codes. */
+export declare enum ErrorCode {
+    /** Session not found, already deleted, or in wrong state. */
+    SESSION_NOT_FOUND = "SESSION_NOT_FOUND",
+    /** Session creation failed (tmux window, CC launch). */
+    SESSION_CREATE_FAILED = "SESSION_CREATE_FAILED",
+    /** Permission request was rejected by the user. */
+    PERMISSION_REJECTED = "PERMISSION_REJECTED",
+    /** Tmux command timed out. */
+    TMUX_TIMEOUT = "TMUX_TIMEOUT",
+    /** Tmux operation failed (non-timeout). */
+    TMUX_ERROR = "TMUX_ERROR",
+    /** Request body or parameter failed validation. */
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    /** Authentication failed (missing/invalid token). */
+    AUTH_ERROR = "AUTH_ERROR",
+    /** Rate limit exceeded. */
+    RATE_LIMITED = "RATE_LIMITED",
+    /** Network or I/O error (transient). */
+    NETWORK_ERROR = "NETWORK_ERROR",
+    /** Unexpected internal error. */
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+/** Structured result returned by categorize(). */
+export interface CategorizedError {
+    code: ErrorCode;
+    message: string;
+    retryable: boolean;
+}
+/** Inspect an unknown error and return a structured categorization. */
+export declare function categorize(error: unknown): CategorizedError;
+/** Return true if the error is worth retrying. */
+export declare function shouldRetry(error: unknown): boolean;

package/dist/error-categories.js

@@ -0,0 +1,74 @@
+/**
+ * error-categories.ts — Structured error categorization and retry guidance.
+ *
+ * Issue #701: Provides an ErrorCode enum, categorize() function to inspect
+ * unknown errors and return structured metadata, and shouldRetry() helper.
+ */
+import { TmuxTimeoutError } from './tmux.js';
+/** String enum of Aegis error codes. */
+export var ErrorCode;
+(function (ErrorCode) {
+    /** Session not found, already deleted, or in wrong state. */
+    ErrorCode["SESSION_NOT_FOUND"] = "SESSION_NOT_FOUND";
+    /** Session creation failed (tmux window, CC launch). */
+    ErrorCode["SESSION_CREATE_FAILED"] = "SESSION_CREATE_FAILED";
+    /** Permission request was rejected by the user. */
+    ErrorCode["PERMISSION_REJECTED"] = "PERMISSION_REJECTED";
+    /** Tmux command timed out. */
+    ErrorCode["TMUX_TIMEOUT"] = "TMUX_TIMEOUT";
+    /** Tmux operation failed (non-timeout). */
+    ErrorCode["TMUX_ERROR"] = "TMUX_ERROR";
+    /** Request body or parameter failed validation. */
+    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
+    /** Authentication failed (missing/invalid token). */
+    ErrorCode["AUTH_ERROR"] = "AUTH_ERROR";
+    /** Rate limit exceeded. */
+    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
+    /** Network or I/O error (transient). */
+    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
+    /** Unexpected internal error. */
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
+})(ErrorCode || (ErrorCode = {}));
+/** Inspect an unknown error and return a structured categorization. */
+export function categorize(error) {
+    // 1. Known typed errors
+    if (error instanceof TmuxTimeoutError) {
+        return { code: ErrorCode.TMUX_TIMEOUT, message: error.message, retryable: true };
+    }
+    if (error instanceof Error) {
+        const msg = error.message;
+        const lower = msg.toLowerCase();
+        // 2. Message-based heuristics for common Aegis error patterns
+        if (lower.includes('session not found') || lower.includes('no session with id')) {
+            return { code: ErrorCode.SESSION_NOT_FOUND, message: msg, retryable: false };
+        }
+        if (lower.includes('permission denied') || lower.includes('permission rejected')) {
+            return { code: ErrorCode.PERMISSION_REJECTED, message: msg, retryable: false };
+        }
+        if (lower.includes('unauthorized') || lower.includes('invalid token') || lower.includes('authentication')) {
+            return { code: ErrorCode.AUTH_ERROR, message: msg, retryable: false };
+        }
+        if (lower.includes('rate limit') || lower.includes('too many requests')) {
+            return { code: ErrorCode.RATE_LIMITED, message: msg, retryable: true };
+        }
+        if (lower.includes('validation') || lower.includes('invalid ') || lower.includes('required')) {
+            return { code: ErrorCode.VALIDATION_ERROR, message: msg, retryable: false };
+        }
+        if (lower.includes('econnrefused') || lower.includes('econnreset') || lower.includes('etimedout') || lower.includes('fetch failed')) {
+            return { code: ErrorCode.NETWORK_ERROR, message: msg, retryable: true };
+        }
+        if (lower.includes('tmux')) {
+            return { code: ErrorCode.TMUX_ERROR, message: msg, retryable: true };
+        }
+        // 3. Generic Error fallback
+        return { code: ErrorCode.INTERNAL_ERROR, message: msg, retryable: false };
+    }
+    // 4. Non-Error values
+    const msg = typeof error === 'string' ? error : String(error);
+    return { code: ErrorCode.INTERNAL_ERROR, message: msg, retryable: false };
+}
+/** Return true if the error is worth retrying. */
+export function shouldRetry(error) {
+    return categorize(error).retryable;
+}
+//# sourceMappingURL=error-categories.js.map

package/dist/tmux-capture-cache.d.ts

@@ -0,0 +1,18 @@
+/**
+ * tmux-capture-cache.ts — TTL-based cache for capture-pane results.
+ *
+ * Avoids redundant tmux capture-pane CLI calls when the same window
+ * is polled multiple times within a short window (e.g. monitor poll +
+ * status check hitting the same pane).
+ */
+export declare class TmuxCaptureCache {
+    private cache;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /** Return cached capture-pane text if within TTL, otherwise call `captureFn` and cache. */
+    get(windowId: string, captureFn: () => Promise<string>): Promise<string>;
+    /** Invalidate a single window's cached result. */
+    invalidate(windowId: string): void;
+    /** Clear all cached entries. */
+    clear(): void;
+}

package/dist/tmux-capture-cache.js

@@ -0,0 +1,35 @@
+/**
+ * tmux-capture-cache.ts — TTL-based cache for capture-pane results.
+ *
+ * Avoids redundant tmux capture-pane CLI calls when the same window
+ * is polled multiple times within a short window (e.g. monitor poll +
+ * status check hitting the same pane).
+ */
+const DEFAULT_TTL_MS = 500;
+export class TmuxCaptureCache {
+    cache = new Map();
+    ttlMs;
+    constructor(ttlMs = DEFAULT_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    /** Return cached capture-pane text if within TTL, otherwise call `captureFn` and cache. */
+    async get(windowId, captureFn) {
+        const now = Date.now();
+        const entry = this.cache.get(windowId);
+        if (entry && now - entry.at < this.ttlMs) {
+            return entry.text;
+        }
+        const text = await captureFn();
+        this.cache.set(windowId, { text, at: now });
+        return text;
+    }
+    /** Invalidate a single window's cached result. */
+    invalidate(windowId) {
+        this.cache.delete(windowId);
+    }
+    /** Clear all cached entries. */
+    clear() {
+        this.cache.clear();
+    }
+}
+//# sourceMappingURL=tmux-capture-cache.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-bridge",
-  "version": "2.3.11",
+  "version": "2.4.0",
   "type": "module",
   "description": "Orchestrate Claude Code sessions via API. Create, brief, monitor, refine, ship.",
   "main": "dist/server.js",