@debugg-ai/debugg-ai-mcp 2.4.1 → 2.5.0

package/dist/handlers/triggerCrawlHandler.js

@@ -20,8 +20,20 @@ import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
+import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
+import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
 const TEMPLATE_KEYWORD = 'raw crawl';
+// Bead kbo9: same env-driven retry budget as testPageChangesHandler (kbxy).
+function getMaxTransientRetries() {
+    const raw = process.env.DEBUGGAI_TRANSIENT_RETRIES;
+    if (raw === undefined || raw === '')
+        return 1;
+    const n = parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return 1;
+    return Math.min(n, 3);
+}
 export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     const startTime = Date.now();
     logger.toolStart('trigger_crawl', input);
@@ -151,32 +163,64 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         if (progressCallback) {
             await progressCallback({ progress: 3, total: 4, message: 'Queuing crawl execution...' });
         }
-        const executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
-        const executionUuid = executeResponse.executionUuid;
-        logger.info(`Crawl execution queued: ${executionUuid}`);
-        // --- Poll ---
-        // Bead 0bq: emit the final progress (4/4 "Complete:...") INSIDE onUpdate
-        // when terminal status detected, so there's no post-resolve emission that
-        // could race the response and cause stale-progressToken transport tear-down.
+        // --- Execute + Poll (with bounded retry on transient errors, bead kbo9) ---
         const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
-        const finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
-            if (ctx.tunnelId)
-                touchTunnelById(ctx.tunnelId);
-            if (!progressCallback)
-                return;
-            const nodeCount = (exec.nodeExecutions ?? []).length;
-            if (TERMINAL_STATUSES.has(exec.status)) {
+        const MAX_RETRIES = getMaxTransientRetries();
+        let executeResponse;
+        let executionUuid = '';
+        let finalExecution;
+        let attempt = 0;
+        while (true) {
+            attempt++;
+            if (attempt > 1) {
+                Telemetry.capture(TelemetryEvents.WORKFLOW_TRANSIENT_RETRY, {
+                    tool: 'trigger_crawl',
+                    attempt,
+                    reason: transientReasonTag(finalExecution),
+                    previousExecutionId: executionUuid,
+                    previousErrorMessage: finalExecution?.errorMessage?.slice(0, 200),
+                    previousStateError: finalExecution?.state?.error?.slice(0, 200),
+                });
+                if (progressCallback) {
+                    await progressCallback({
+                        progress: 3, total: 4,
+                        message: `Transient backend error — retrying crawl (attempt ${attempt}/${MAX_RETRIES + 1})...`,
+                    });
+                }
+                await new Promise(r => setTimeout(r, 1000 * (attempt - 1)));
+            }
+            executeResponse = await client.workflows.executeWorkflow(templateUuid, contextData, Object.keys(env).length > 0 ? env : undefined);
+            executionUuid = executeResponse.executionUuid;
+            logger.info(`Crawl execution queued: ${executionUuid}${attempt > 1 ? ` (retry ${attempt - 1}/${MAX_RETRIES})` : ''}`);
+            // --- Poll ---
+            // Bead 0bq: emit the final progress (4/4 "Complete:...") INSIDE onUpdate
+            // when terminal status detected, so there's no post-resolve emission that
+            // could race the response and cause stale-progressToken transport tear-down.
+            finalExecution = await client.workflows.pollExecution(executionUuid, async (exec) => {
+                if (ctx.tunnelId)
+                    touchTunnelById(ctx.tunnelId);
+                if (!progressCallback)
+                    return;
+                const nodeCount = (exec.nodeExecutions ?? []).length;
+                if (TERMINAL_STATUSES.has(exec.status)) {
+                    await progressCallback({
+                        progress: 4, total: 4,
+                        message: `Crawl ${exec.status} (${nodeCount} nodes)`,
+                    });
+                    return;
+                }
                 await progressCallback({
                     progress: 4, total: 4,
                     message: `Crawl ${exec.status} (${nodeCount} nodes)`,
                 });
-                return;
-            }
-            await progressCallback({
-                progress: 4, total: 4,
-                message: `Crawl ${exec.status} (${nodeCount} nodes)`,
-            });
-        }, abortController.signal);
+            }, abortController.signal);
+            if (attempt > MAX_RETRIES)
+                break;
+            if (!isTransientWorkflowError(finalExecution))
+                break;
+            logger.warn(`Transient backend error detected on crawl (${transientReasonTag(finalExecution) ?? 'unknown'}) — ` +
+                `retrying (attempt ${attempt + 1}/${MAX_RETRIES + 1})`);
+        }
         const duration = Date.now() - startTime;
         const nodes = finalExecution.nodeExecutions ?? [];
         // --- Format response ---

package/dist/services/ngrok/tunnelManager.js

@@ -49,6 +49,17 @@ class TunnelManager {
     pendingTunnels = new Map();
     initialized = false;
     TUNNEL_TIMEOUT_MS = 55 * 60 * 1000;
+    /**
+     * Bead `3th`: registry-entry freshness window. An entry not touched within
+     * this many ms is treated as stale even if its owner PID is alive — defends
+     * against PID-reuse (OS reassigns dead-owner's PID to a different process).
+     */
+    REGISTRY_FRESHNESS_TTL_MS = 30 * 60 * 1000;
+    /**
+     * Bead `mdp`: prune-on-startup eviction window. Entries older than this OR
+     * with dead owner PID get swept out when TunnelManager initializes.
+     */
+    REGISTRY_PRUNE_THRESHOLD_MS = 60 * 60 * 1000;
     /**
      * Backoff schedule (ms) between ngrok.connect() retry attempts. Bead ixh.
      * Exposed on the class so tests can override with short delays without
@@ -57,6 +68,26 @@ class TunnelManager {
     connectBackoffMs = [500, 1500];
     constructor(reg = getDefaultRegistry()) {
         this.reg = reg;
+        // Bead `mdp`: sweep stale entries on startup so the registry doesn't grow
+        // unboundedly across MCP processes that exited without stopAllTunnels
+        // (SIGKILL / crash). Best-effort — no-op registries don't actually prune.
+        try {
+            const result = this.reg.prune({ staleAfterMs: this.REGISTRY_PRUNE_THRESHOLD_MS });
+            if (result.pruned > 0) {
+                logger.info(`Pruned ${result.pruned} stale registry entries on startup (${result.remaining} remaining)`);
+            }
+        }
+        catch (err) {
+            logger.warn(`Registry prune-on-startup failed (non-fatal): ${err}`);
+        }
+    }
+    /**
+     * Bead `3th`: freshness check used at borrow sites. Returns true if the
+     * entry is BOTH owner-alive AND touched recently enough to trust.
+     */
+    isEntryUsable(entry, nowMs = Date.now()) {
+        return (this.reg.isPidAlive(entry.ownerPid) &&
+            (nowMs - entry.lastAccessedAt) <= this.REGISTRY_FRESHNESS_TTL_MS);
     }
     // ── Public API ──────────────────────────────────────────────────────────────
     async processUrl(url, authToken, specificTunnelId, keyId, revokeKey) {
@@ -82,11 +113,18 @@ class TunnelManager {
         if (!existing)
             return undefined;
         if (!existing.isOwned) {
-            // Verify the owning process is still alive
+            // Verify the owning process is still alive AND the entry is fresh
+            // (lastAccessedAt within REGISTRY_FRESHNESS_TTL_MS — defends against
+            // PID-reuse per bead 3th).
             const entry = this.reg.read()[String(port)];
-            if (!entry || !this.reg.isPidAlive(entry.ownerPid)) {
+            if (!entry || !this.isEntryUsable(entry)) {
                 this.activeTunnels.delete(existing.tunnelId);
-                logger.info(`Evicted stale borrowed tunnel ${existing.tunnelId} (owner PID ${entry?.ownerPid} dead)`);
+                const reason = !entry
+                    ? 'no registry entry'
+                    : !this.reg.isPidAlive(entry.ownerPid)
+                        ? `owner PID ${entry.ownerPid} dead`
+                        : `entry stale (last accessed ${Math.round((Date.now() - entry.lastAccessedAt) / 1000)}s ago)`;
+                logger.info(`Evicted stale borrowed tunnel ${existing.tunnelId} (${reason})`);
                 return undefined;
             }
         }
@@ -223,10 +261,12 @@ class TunnelManager {
             const info = await pending;
             return { url: info.publicUrl, tunnelId: info.tunnelId, isLocalhost: true };
         }
-        // 3. Check cross-process registry — another MCP instance may own a tunnel
+        // 3. Check cross-process registry — another MCP instance may own a tunnel.
+        //    Borrow only if the entry is fresh (PID alive AND touched within
+        //    REGISTRY_FRESHNESS_TTL_MS — defends against PID-reuse, bead 3th).
         const registry = this.reg.read();
         const regEntry = registry[String(port)];
-        if (regEntry && this.reg.isPidAlive(regEntry.ownerPid)) {
+        if (regEntry && this.isEntryUsable(regEntry)) {
             logger.info(`Borrowing tunnel from PID ${regEntry.ownerPid} for port ${port}: ${regEntry.publicUrl}`);
             const now = Date.now();
             const borrowed = {
@@ -293,7 +333,6 @@ class TunnelManager {
         //   (existing "agent died" recovery path)
         // - Attempt 3: after 1500ms backoff, retry with the already-reset agent
         // Auth-token errors short-circuit at any attempt — no point looping.
-        const self = this;
         // Bead 42g: fault injection + trace. Only active when NODE_ENV !== 'production'
         // AND DEBUGG_TUNNEL_FAULT_MODE env var is set. Zero overhead when disabled.
         const faultMode = getFaultModeFromEnv();
@@ -302,7 +341,7 @@ class TunnelManager {
         trace.emit('createTunnel.start', { port, tunnelId, hasFaultMode: !!faultMode });
         const connectWithRetry = async () => {
             const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-            const BACKOFF_MS = self.connectBackoffMs; // bead ixh: test-overridable
+            const BACKOFF_MS = this.connectBackoffMs; // bead ixh: test-overridable
             const MAX_ATTEMPTS = BACKOFF_MS.length + 1; // N sleeps between N+1 attempts
             const connectOpts = {
                 proto: 'http',

package/dist/services/ngrok/tunnelRegistry.js

@@ -14,7 +14,7 @@ import { join } from 'path';
 // ── File-backed implementation (production) ───────────────────────────────────
 const REGISTRY_FILE = join(tmpdir(), 'debugg-ai-tunnels.json');
 export function createFileRegistry() {
-    return {
+    const store = {
         read() {
             try {
                 if (!existsSync(REGISTRY_FILE))
@@ -38,22 +38,29 @@ export function createFileRegistry() {
         isPidAlive(pid) {
             return checkPid(pid);
         },
+        prune(opts) {
+            return pruneRegistryData(store, opts);
+        },
     };
+    return store;
 }
 // ── In-memory implementation (tests / injectable) ─────────────────────────────
 export function createInMemoryRegistry(isPidAliveImpl) {
-    let store = {};
-    return {
-        read: () => ({ ...store }),
-        write: (data) => { store = { ...data }; },
+    let data = {};
+    const store = {
+        read: () => ({ ...data }),
+        write: (next) => { data = { ...next }; },
         isPidAlive: isPidAliveImpl ?? checkPid,
+        prune: (opts) => pruneRegistryData(store, opts),
     };
+    return store;
 }
 // ── No-op implementation (tests that don't exercise registry) ─────────────────
 export const noopRegistry = {
     read: () => ({}),
     write: () => { },
     isPidAlive: () => false,
+    prune: () => ({ pruned: 0, remaining: 0 }),
 };
 // ── Default selection ─────────────────────────────────────────────────────────
 /**
@@ -73,3 +80,30 @@ function checkPid(pid) {
         return false;
     }
 }
+/**
+ * Shared prune logic — read, filter, write back. Used by both the file-backed
+ * and in-memory implementations so the eviction policy lives in one place.
+ *
+ * Eviction rule: drop entries where EITHER the owner PID is dead OR the entry
+ * hasn't been touched within `staleAfterMs`. The freshness check is what
+ * defends against PID-reuse (bead 3th).
+ */
+function pruneRegistryData(store, opts) {
+    const now = opts.nowMs ?? Date.now();
+    const data = store.read();
+    const next = {};
+    let pruned = 0;
+    for (const [port, entry] of Object.entries(data)) {
+        const aliveAndFresh = store.isPidAlive(entry.ownerPid) &&
+            (now - entry.lastAccessedAt) <= opts.staleAfterMs;
+        if (aliveAndFresh) {
+            next[port] = entry;
+        }
+        else {
+            pruned++;
+        }
+    }
+    if (pruned > 0)
+        store.write(next);
+    return { pruned, remaining: Object.keys(next).length };
+}

package/dist/services/ngrok/types.js

@@ -1,2 +1 @@
 export {};
-/* eslint-enable */

package/dist/tools/index.js

@@ -1,5 +1,6 @@
 import { buildTestPageChangesTool, buildValidatedTestPageChangesTool } from './testPageChanges.js';
 import { buildTriggerCrawlTool, buildValidatedTriggerCrawlTool } from './triggerCrawl.js';
+import { buildProbePageTool, buildValidatedProbePageTool } from './probePage.js';
 import { buildSearchProjectsTool, buildValidatedSearchProjectsTool } from './searchProjects.js';
 import { buildSearchEnvironmentsTool, buildValidatedSearchEnvironmentsTool } from './searchEnvironments.js';
 import { buildSearchExecutionsTool, buildValidatedSearchExecutionsTool } from './searchExecutions.js';
@@ -19,6 +20,7 @@ export function initTools(ctx) {
     const tools = [
         buildTestPageChangesTool(ctx),
         buildTriggerCrawlTool(ctx),
+        buildProbePageTool(),
         buildSearchProjectsTool(),
         buildSearchEnvironmentsTool(),
         buildCreateEnvironmentTool(),
@@ -32,6 +34,7 @@ export function initTools(ctx) {
     const validated = [
         buildValidatedTestPageChangesTool(ctx),
         buildValidatedTriggerCrawlTool(ctx),
+        buildValidatedProbePageTool(),
         buildValidatedSearchProjectsTool(),
         buildValidatedSearchEnvironmentsTool(),
         buildValidatedCreateEnvironmentTool(),

package/dist/tools/probePage.js

@@ -0,0 +1,89 @@
+/**
+ * Probe Page Tool Definition.
+ *
+ * Lightweight no-LLM batch page probe — navigate + capture state for 1-20
+ * URLs in one backend execution. Returns screenshots, page metadata,
+ * structured console errors, and per-URL networkSummary (origin+pathname
+ * aggregation that surfaces refetch loops as a single entry).
+ *
+ * NOT an agent: no LLM in the critical path; no interaction (clicks/fills);
+ * no scenario verification. For those, use check_app_in_browser.
+ */
+import { ProbePageInputSchema } from '../types/index.js';
+import { probePageHandler } from '../handlers/probePageHandler.js';
+const DESCRIPTION = `Probe one or more URLs and return their rendered state — screenshot, page metadata (title/finalUrl/statusCode/loadTimeMs), structured console errors, and per-URL network summary (refetch loops collapse into one row by origin+pathname).
+
+WHEN TO USE: "did I just break /settings?" / "smoke-test these 5 routes after my refactor" / "what's actually rendering at /dashboard?" — fast (<10s for 1 URL, <25s for 20), no LLM cost, no agent loop.
+
+NOT FOR: scenario verification (sign in → click X → assert Y), interaction (clicks, form fills, scrolls), or anything requiring agent decisions. Use check_app_in_browser for those.
+
+LOCALHOST SUPPORT: any localhost URL is auto-tunneled. Pre-flight TCP probe fails fast (<2s) if the dev server isn't listening.
+
+BATCH MODE: pass up to 20 targets in one call to share browser session + tunnel — dramatically faster than firing parallel single-URL probes (one execution unit, not N). Per-URL waitForSelector / waitForLoadState / timeoutMs override defaults.
+
+A single failed target's error appears in result.error without failing the whole batch — the other results stay valid.`;
+const TARGET_PROPERTIES = {
+    url: {
+        type: 'string',
+        description: 'URL to probe. Public URL or localhost URL (auto-tunneled).',
+    },
+    waitForSelector: {
+        type: 'string',
+        description: 'Optional CSS selector to wait for after navigation completes. Useful for SPAs that mount content asynchronously.',
+    },
+    waitForLoadState: {
+        type: 'string',
+        enum: ['load', 'domcontentloaded', 'networkidle'],
+        description: "When to consider the page 'loaded' before capturing. Default 'load'. Use 'networkidle' for SPAs to wait until the bundle finishes rendering.",
+    },
+    timeoutMs: {
+        type: 'number',
+        description: 'Per-URL navigation timeout in milliseconds (1000-30000, default 10000).',
+    },
+};
+export function buildProbePageTool() {
+    return {
+        name: 'probe_page',
+        title: 'Probe Page',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                targets: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 20,
+                    items: {
+                        type: 'object',
+                        properties: TARGET_PROPERTIES,
+                        required: ['url'],
+                        additionalProperties: false,
+                    },
+                    description: '1-20 URLs to probe. Each entry can carry its own per-URL wait config.',
+                },
+                includeHtml: {
+                    type: 'boolean',
+                    description: "If true, each result includes the page's outerHTML. Default false to keep response size sane.",
+                },
+                captureScreenshots: {
+                    type: 'boolean',
+                    description: 'If true (default), one PNG screenshot is returned per target. Set false for very large batches or when only the structured data matters.',
+                },
+                repoName: {
+                    type: 'string',
+                    description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this to scope the probe to a different project context.",
+                },
+            },
+            required: ['targets'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedProbePageTool() {
+    const tool = buildProbePageTool();
+    return {
+        ...tool,
+        inputSchema: ProbePageInputSchema,
+        handler: probePageHandler,
+    };
+}

package/dist/types/index.js

@@ -152,3 +152,20 @@ export var LogLevel;
     LogLevel["INFO"] = "info";
     LogLevel["DEBUG"] = "debug";
 })(LogLevel || (LogLevel = {}));
+// ── probe-page ────────────────────────────────────────────────────────────
+// Lightweight no-LLM page-probe tool. Each target gets its own wait config;
+// targets[] is the batch — one workflow execution covers up to 20 URLs sharing
+// browser session + tunnel. Strict schema: forbidden agent fields like
+// `description` and `credentialId` reject (zero-LLM contract).
+export const ProbePageTargetSchema = z.object({
+    url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),
+    waitForSelector: z.string().optional(),
+    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('load'),
+    timeoutMs: z.number().int().min(1000, 'timeoutMs minimum is 1000 (1s)').max(30000, 'timeoutMs maximum is 30000 (30s) — longer probes should use check_app_in_browser').default(10000),
+}).strict();
+export const ProbePageInputSchema = z.object({
+    targets: z.array(ProbePageTargetSchema).min(1, 'targets must have at least one URL').max(20, 'targets capped at 20 per call — split larger sweeps across multiple calls'),
+    includeHtml: z.boolean().default(false),
+    captureScreenshots: z.boolean().default(true),
+    repoName: z.string().optional(),
+}).strict();

package/dist/utils/errors.js

@@ -83,7 +83,6 @@ export function handleConfigurationError(error) {
  * Handle external service errors (e.g., API calls)
  */
 export function handleExternalServiceError(error, serviceName, operation) {
-    const context = `${serviceName}${operation ? `:${operation}` : ''}`;
     if (error instanceof Error) {
         logger.error('External service error', {
             serviceName,

package/dist/utils/harSummarizer.js

@@ -0,0 +1,105 @@
+/**
+ * harSummarizer — pure HAR + console aggregation utilities.
+ *
+ * Aggregation key for networkSummary: `origin + pathname` (per system reqs).
+ * Refetch loops with varying query strings collapse into a single entry.
+ *
+ * Pure functions — no I/O, no async — so they can be reused by the future
+ * `summarize_execution` tool.
+ */
+/**
+ * Aggregate HAR `log.entries` into per-endpoint NetworkSummary[], sorted
+ * descending by request count (hottest endpoints first). Malformed entries
+ * (missing request.url or response.status) are skipped, not thrown.
+ */
+export function summarizeHar(harEntries) {
+    if (!Array.isArray(harEntries))
+        return [];
+    const buckets = new Map();
+    for (const entry of harEntries) {
+        try {
+            const reqUrl = entry?.request?.url;
+            const status = entry?.response?.status;
+            if (typeof reqUrl !== 'string' || typeof status !== 'number')
+                continue;
+            // Aggregation key: origin + pathname (refetch loops collapse).
+            let parsed;
+            try {
+                parsed = new URL(reqUrl);
+            }
+            catch {
+                continue;
+            }
+            const key = `${parsed.origin}${parsed.pathname}`;
+            const bytesRaw = entry?.response?.content?.size;
+            const bytes = typeof bytesRaw === 'number' && bytesRaw >= 0 ? bytesRaw : 0;
+            const mime = entry?.response?.content?.mimeType;
+            const mimeStr = typeof mime === 'string' && mime ? mime : '';
+            const existing = buckets.get(key);
+            if (existing) {
+                existing.count++;
+                const sk = String(status);
+                existing.statuses[sk] = (existing.statuses[sk] ?? 0) + 1;
+                existing.totalBytes += bytes;
+                if (mimeStr)
+                    existing.mimeTypes.add(mimeStr);
+            }
+            else {
+                buckets.set(key, {
+                    url: key,
+                    count: 1,
+                    statuses: { [String(status)]: 1 },
+                    totalBytes: bytes,
+                    mimeTypes: mimeStr ? new Set([mimeStr]) : new Set(),
+                });
+            }
+        }
+        catch {
+            // malformed — skip
+        }
+    }
+    return [...buckets.values()]
+        .map(({ mimeTypes, url, count, statuses, totalBytes }) => {
+        const out = { url, count, statuses, totalBytes };
+        // Only attach mimeType when homogeneous — mixed types omit the field.
+        if (mimeTypes.size === 1) {
+            out.mimeType = [...mimeTypes][0];
+        }
+        return out;
+    })
+        .sort((a, b) => b.count - a.count);
+}
+/**
+ * Normalize a console-log JSON array into ConsoleErrorEntry[].
+ * Maps backend's snake_case (`line_number`, `url`) to MCP's camelCase
+ * (`lineNumber`, `source`). Drops entries that aren't plain objects.
+ */
+export function summarizeConsole(consoleEntries) {
+    if (!Array.isArray(consoleEntries))
+        return [];
+    const out = [];
+    for (const e of consoleEntries) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const entry = {
+            level: typeof e.level === 'string' ? e.level : 'log',
+            text: typeof e.text === 'string' ? e.text : '',
+        };
+        // source: prefer `url` (backend convention), fall back to `source`
+        const sourceVal = typeof e.url === 'string' && e.url
+            ? e.url
+            : (typeof e.source === 'string' && e.source ? e.source : undefined);
+        if (sourceVal)
+            entry.source = sourceVal;
+        // lineNumber: snake_case from backend → camelCase
+        const lineVal = typeof e.line_number === 'number'
+            ? e.line_number
+            : (typeof e.lineNumber === 'number' ? e.lineNumber : undefined);
+        if (typeof lineVal === 'number')
+            entry.lineNumber = lineVal;
+        if (typeof e.timestamp === 'number')
+            entry.timestamp = e.timestamp;
+        out.push(entry);
+    }
+    return out;
+}

package/dist/utils/projectAnalyzer.js

@@ -45,7 +45,7 @@ export class ProjectAnalyzer {
     /**
      * Analyze codebase for context extraction
      */
-    async analyzeCodebase(repoPath, repoName, branchName, includeChanges = true) {
+    async analyzeCodebase(repoPath, repoName, branchName, _includeChanges = true) {
         try {
             logger.info('Starting codebase analysis', { repoPath, repoName, branchName });
             const analysis = await this.analyzeProject(repoPath);
@@ -384,7 +384,7 @@ export class ProjectAnalyzer {
                     }
                 }
             }
-            catch (error) {
+            catch {
                 // Skip directories we can't read
             }
         };

package/dist/utils/telemetry.js

@@ -52,6 +52,7 @@ export const TelemetryEvents = {
     TOOL_EXECUTED: 'tool.executed',
     TOOL_FAILED: 'tool.failed',
     WORKFLOW_EXECUTED: 'workflow.executed',
+    WORKFLOW_TRANSIENT_RETRY: 'workflow.transient_retry',
     TUNNEL_PROVISIONED: 'tunnel.provisioned',
     TUNNEL_PROVISION_RETRY: 'tunnel.provision_retry',
     TUNNEL_STOPPED: 'tunnel.stopped',

package/dist/utils/transientErrors.js

@@ -0,0 +1,82 @@
+/**
+ * Detect well-known transient failure signatures in completed workflow
+ * executions. When `isTransientWorkflowError` returns true, the MCP handler
+ * auto-retries the workflow (cost: one extra quota unit) — saving the caller
+ * from the 'pure infrastructure noise' failure mode the original client
+ * called out in their feedback (Pydantic JSON parse errors, etc.).
+ *
+ * Be CONSERVATIVE: only patterns documented as transient. False positives
+ * waste quota; false negatives leave existing behavior, which is fine — the
+ * caller still gets a clear error and can decide what to do.
+ *
+ * Bead `kbxy`. Patterns are extracted (not inlined) so they're easy to audit
+ * + extend as new transient signatures get observed in production.
+ */
+/**
+ * Patterns that match transient backend failures worth retrying. Each entry
+ * is a regex tested against `errorMessage` AND `state.error`. Matching ANY
+ * pattern in EITHER field flags the execution as transient.
+ *
+ * To add a new pattern: confirm by sampling production telemetry that the
+ * signature recovers on retry (a one-shot reproduce-then-retry test is
+ * sufficient evidence). Document the source in the comment.
+ */
+const TRANSIENT_PATTERNS = [
+    // The original client complaint. Backend agent's brain.step occasionally
+    // returns malformed JSON for the structured output — Pydantic chokes on
+    // EOF / partial JSON. A fresh agent invocation reliably recovers.
+    { pattern: /Invalid JSON.*EOF while parsing/i, reason: 'pydantic-eof' },
+    { pattern: /Failed to parse AgentOutput/i, reason: 'agent-output-parse' },
+    // Backend-side infrastructure flakes (nginx 502 from upstream + timeouts).
+    // Both observed in production during 2026-04-26 + 2026-04-27 deploys —
+    // recovery on next request is the rule, not the exception.
+    { pattern: /502 Bad Gateway/i, reason: 'nginx-502' },
+    { pattern: /upstream connect timeout/i, reason: 'upstream-timeout' },
+    // Network-layer transient — TCP reset between MCP↔backend or backend↔model.
+    { pattern: /ECONNRESET|connection reset by peer/i, reason: 'econnreset' },
+];
+/**
+ * @returns true if the execution's error fields contain a known transient
+ * signature, indicating a retry has a reasonable chance of succeeding.
+ */
+export function isTransientWorkflowError(execution) {
+    if (!execution)
+        return false;
+    const candidates = [];
+    if (typeof execution.errorMessage === 'string' && execution.errorMessage) {
+        candidates.push(execution.errorMessage);
+    }
+    if (typeof execution.state?.error === 'string' && execution.state.error) {
+        candidates.push(execution.state.error);
+    }
+    if (candidates.length === 0)
+        return false;
+    for (const text of candidates) {
+        for (const { pattern } of TRANSIENT_PATTERNS) {
+            if (pattern.test(text))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * @returns the reason tag for the matched transient pattern (for telemetry),
+ *   or undefined if no pattern matched. Useful when you want to attach a
+ *   classifier to a `workflow.transient_retry` event.
+ */
+export function transientReasonTag(execution) {
+    if (!execution)
+        return undefined;
+    const fields = [];
+    if (typeof execution.errorMessage === 'string' && execution.errorMessage)
+        fields.push(execution.errorMessage);
+    if (typeof execution.state?.error === 'string' && execution.state.error)
+        fields.push(execution.state.error);
+    for (const text of fields) {
+        for (const { pattern, reason } of TRANSIENT_PATTERNS) {
+            if (pattern.test(text))
+                return reason;
+        }
+    }
+    return undefined;
+}

package/dist/utils/urlParser.js

@@ -54,7 +54,7 @@ export function parseUrl(urlString) {
             hash: url.hash
         };
     }
-    catch (error) {
+    catch {
         throw new Error(`Invalid URL format: ${urlString}`);
     }
 }

package/dist/utils/validation.js

@@ -81,7 +81,7 @@ export function validatePort(port) {
     try {
         return commonSchemas.port.parse(port);
     }
-    catch (error) {
+    catch {
         throw new MCPError(MCPErrorCode.VALIDATION_ERROR, `Invalid port number: ${port}. Port must be between 1 and 65535.`, { port });
     }
 }