mixdog 0.7.1

package/src/agent/orchestrator/smart-bridge/registry.mjs

@@ -0,0 +1,348 @@
+/**
+ * Smart Bridge — Cache Registry (Phase D-2: provider × profile matrix)
+ *
+ * Each provider caches independently (Anthropic workspace+model shard,
+ * OpenAI prompt_cache_key, Gemini implicit cache observations). Tracking a
+ * single entry per profile-id — as v1 did — means a profile used across two
+ * providers silently overwrites the warm state of the other. v2 indexes by
+ * (profileId, provider), preserving per-shard hit/miss/TTL independently.
+ *
+ * Persistence: <plugin-data>/cache-registry.json. v1 files auto-migrate
+ * on load.
+ */
+
+import { existsSync, readFileSync, mkdirSync } from 'fs';
+import { createHash } from 'crypto';
+import { dirname, join } from 'path';
+import { getPluginData } from '../config.mjs';
+import { writeJsonAtomicSync } from '../../../shared/atomic-file.mjs';
+
+const REGISTRY_VERSION = 2;
+
+function registryPath() {
+    return join(getPluginData(), 'cache-registry.json');
+}
+
+function emptyRegistry() {
+    return {
+        version: REGISTRY_VERSION,
+        // profiles: profileId → provider → entry
+        //   entry = { prefixHash, createdAt, expiresAt, hitCount, missCount, observedOnly }
+        profiles: {},
+        openaiKeys: {}, // cacheKey → { retention, lastUsedAt }
+        updatedAt: new Date().toISOString(),
+    };
+}
+
+// shape: profiles[profileId][provider] = { prefixHash, createdAt, ... }
+function migrateV1ToV2(raw) {
+    const migrated = emptyRegistry();
+    migrated.openaiKeys = raw.openaiKeys || {};
+    for (const [profileId, entry] of Object.entries(raw.profiles || {})) {
+        if (!entry || typeof entry !== 'object') continue;
+        const provider = entry.provider || 'unknown';
+        const { provider: _p, ...rest } = entry;
+        migrated.profiles[profileId] = { [provider]: rest };
+    }
+    return migrated;
+}
+
+export class CacheRegistry {
+    constructor() {
+        this.data = emptyRegistry();
+        this.loaded = false;
+        this.dirty = false;
+    }
+
+    load() {
+        const path = registryPath();
+        if (!existsSync(path)) {
+            this.data = emptyRegistry();
+            this.loaded = true;
+            return;
+        }
+        try {
+            const raw = JSON.parse(readFileSync(path, 'utf8'));
+            if (raw.version === REGISTRY_VERSION) {
+                this.data = {
+                    version: REGISTRY_VERSION,
+                    profiles: raw.profiles || {},
+                    openaiKeys: raw.openaiKeys || {},
+                    updatedAt: raw.updatedAt || new Date().toISOString(),
+                };
+            } else if (raw.version === 1 || raw.version === undefined) {
+                process.stderr.write(`[cache-registry] migrating v${raw.version || '?'} → v${REGISTRY_VERSION}\n`);
+                this.data = migrateV1ToV2(raw);
+                this.dirty = true;
+            } else {
+                process.stderr.write(`[cache-registry] unknown version ${raw.version}, resetting\n`);
+                this.data = emptyRegistry();
+            }
+        } catch (err) {
+            process.stderr.write(`[cache-registry] load failed: ${err.message}\n`);
+            this.data = emptyRegistry();
+        }
+        this.cleanupExpired();
+        this.loaded = true;
+    }
+
+    save() {
+        if (!this.loaded) return;
+        const path = registryPath();
+        try {
+            mkdirSync(dirname(path), { recursive: true });
+            this.data.updatedAt = new Date().toISOString();
+            writeJsonAtomicSync(path, this.data, { lock: true });
+            this.dirty = false;
+        } catch (err) {
+            process.stderr.write(`[cache-registry] save failed: ${err.message}\n`);
+        }
+    }
+
+    _getEntry(profileId, provider) {
+        return this.data.profiles[profileId]?.[provider] || null;
+    }
+
+    _setEntry(profileId, provider, entry) {
+        if (!this.data.profiles[profileId]) this.data.profiles[profileId] = {};
+        this.data.profiles[profileId][provider] = entry;
+    }
+
+    // --- Profile × provider cache warm state ---
+
+    /**
+     * Record that a (profile, provider) shard was just written to provider
+     * cache. prefixContent should be deterministic (system + tools + context
+     * chunks) so re-hashing produces the same hash on next run. TTL seconds
+     * is provider-specific and decided by the caller.
+     */
+    markWarm(profileId, provider, prefixContent, ttlSeconds) {
+        if (!this.loaded) this.load();
+        if (!profileId || !provider) return;
+        const now = Date.now();
+        const prefixHash = hashContent(prefixContent);
+        const existing = this._getEntry(profileId, provider);
+        const samePrefix = existing && existing.prefixHash === prefixHash;
+        this._setEntry(profileId, provider, {
+            prefixHash,
+            createdAt: samePrefix ? (existing.createdAt || now) : now,
+            expiresAt: now + ttlSeconds * 1000,
+            hitCount: samePrefix ? (existing.hitCount || 0) : 0,
+            missCount: existing?.missCount || 0,
+            observedOnly: false,
+        });
+        this.dirty = true;
+    }
+
+    /**
+     * Record that a provider returned cache metrics for this prefix without
+     * implying the next request can rely on a warm shard. Gemini implicit
+     * caching is the main case: hits are useful telemetry, but no explicit
+     * cache object or stable warm contract exists.
+     */
+    markObserved(profileId, provider, prefixContent, ttlSeconds) {
+        if (!this.loaded) this.load();
+        if (!profileId || !provider) return;
+        const now = Date.now();
+        const prefixHash = hashContent(prefixContent);
+        const existing = this._getEntry(profileId, provider);
+        const samePrefix = existing && existing.prefixHash === prefixHash;
+        this._setEntry(profileId, provider, {
+            prefixHash,
+            createdAt: samePrefix ? (existing.createdAt || now) : now,
+            expiresAt: now + ttlSeconds * 1000,
+            hitCount: samePrefix ? (existing.hitCount || 0) : 0,
+            missCount: samePrefix ? (existing.missCount || 0) : 0,
+            observedOnly: true,
+        });
+        this.dirty = true;
+    }
+
+    /**
+     * Check whether a (profile, provider) shard is still warm for the given
+     * prefix content. warm=true is only returned for providers we deliberately
+     * mark as reusable. Observation-only providers may have hit/miss stats,
+     * but still return warm=false because the provider has no explicit warm
+     * contract.
+     */
+    checkWarm(profileId, provider, prefixContent) {
+        if (!this.loaded) this.load();
+        const entry = this._getEntry(profileId, provider);
+        if (!entry) return { warm: false, expiresIn: 0, reason: 'no-entry' };
+        const now = Date.now();
+        if ((entry.expiresAt || 0) < now) return { warm: false, expiresIn: 0, reason: 'expired' };
+        if (entry.observedOnly) {
+            return { warm: false, expiresIn: entry.expiresAt - now, reason: 'observed-only' };
+        }
+        const currentHash = hashContent(prefixContent);
+        if (currentHash !== entry.prefixHash) {
+            return { warm: false, expiresIn: 0, reason: 'hash-mismatch' };
+        }
+        return { warm: true, expiresIn: entry.expiresAt - now, reason: 'warm' };
+    }
+
+    recordHit(profileId, provider) {
+        if (!this.loaded) this.load();
+        const entry = this._getEntry(profileId, provider);
+        if (entry) {
+            entry.hitCount = (entry.hitCount || 0) + 1;
+            this.dirty = true;
+        }
+    }
+
+    recordMiss(profileId, provider) {
+        if (!this.loaded) this.load();
+        const entry = this._getEntry(profileId, provider);
+        if (entry) {
+            entry.missCount = (entry.missCount || 0) + 1;
+            this.dirty = true;
+        }
+    }
+
+    /**
+     * Invalidate a single provider shard when `provider` is given, or every
+     * provider shard under that profile when omitted.
+     */
+    invalidate(profileId, provider) {
+        if (!profileId || !this.data.profiles[profileId]) return;
+        if (provider) {
+            if (this.data.profiles[profileId][provider]) {
+                delete this.data.profiles[profileId][provider];
+                if (Object.keys(this.data.profiles[profileId]).length === 0) {
+                    delete this.data.profiles[profileId];
+                }
+                this.dirty = true;
+            }
+        } else {
+            delete this.data.profiles[profileId];
+            this.dirty = true;
+        }
+    }
+
+    // --- OpenAI cache_key tracking ---
+
+    trackOpenAIKey(cacheKey, retention) {
+        if (!this.loaded) this.load();
+        this.data.openaiKeys[cacheKey] = {
+            retention,
+            lastUsedAt: new Date().toISOString(),
+        };
+        this.dirty = true;
+    }
+
+    // --- Stats & maintenance ---
+
+    cleanupExpired() {
+        if (!this.loaded) return;
+        const now = Date.now();
+        let removed = 0;
+        for (const [profileId, providers] of Object.entries(this.data.profiles)) {
+            for (const [provider, entry] of Object.entries(providers)) {
+                if ((entry?.expiresAt || 0) < now) {
+                    delete providers[provider];
+                    removed += 1;
+                }
+            }
+            if (Object.keys(providers).length === 0) {
+                delete this.data.profiles[profileId];
+            }
+        }
+        if (removed > 0) this.dirty = true;
+    }
+
+    /**
+     * Matrix-shaped stats. profiles[profileId][provider] = { hitCount,
+     * missCount, hitRate, expiresIn, prefixHash }. shardCount totals every
+     * (profile, provider) pair; profileCount counts distinct profiles.
+     */
+    getStats() {
+        if (!this.loaded) this.load();
+        const now = Date.now();
+        const profiles = {};
+        let shardCount = 0;
+        for (const [profileId, providers] of Object.entries(this.data.profiles)) {
+            profiles[profileId] = {};
+            for (const [provider, entry] of Object.entries(providers)) {
+                const total = (entry.hitCount || 0) + (entry.missCount || 0);
+                profiles[profileId][provider] = {
+                    prefixHash: entry.prefixHash || null,
+                    hitCount: entry.hitCount || 0,
+                    missCount: entry.missCount || 0,
+                    hitRate: total > 0 ? (entry.hitCount || 0) / total : 0,
+                    expiresIn: Math.max(0, (entry.expiresAt || 0) - now),
+                    createdAt: entry.createdAt || null,
+                    observedOnly: entry.observedOnly === true,
+                };
+                shardCount += 1;
+            }
+        }
+        return {
+            profileCount: Object.keys(this.data.profiles).length,
+            shardCount,
+            profiles,
+            openaiKeyCount: Object.keys(this.data.openaiKeys).length,
+        };
+    }
+
+    // --- Singleton-style access (callers import a shared instance) ---
+
+    static _shared = null;
+    static shared() {
+        if (!this._shared) {
+            this._shared = new CacheRegistry();
+            this._shared.load();
+        }
+        return this._shared;
+    }
+}
+
+// --- Helpers ---
+
+/**
+ * Deep stable stringifier — deterministic key order at every nesting level.
+ * Arrays preserve positional order (tool order matters); objects sort keys
+ * alphabetically. Primitives and null are serialized via JSON.stringify.
+ *
+ * Replaces the previous replacer-array form, which acted as a top-level
+ * allowlist and silently emptied nested tool objects (name/description/
+ * inputSchema were dropped → falsely stable hash across schema changes).
+ */
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(v => stableStringify(v)).join(',') + ']';
+    }
+    const keys = Object.keys(value).sort();
+    const parts = [];
+    for (const k of keys) {
+        const v = value[k];
+        if (v === undefined) continue;
+        parts.push(JSON.stringify(k) + ':' + stableStringify(v));
+    }
+    return '{' + parts.join(',') + '}';
+}
+
+/**
+ * Stable content hash — deterministic across runs as long as structure is identical.
+ * Used to detect when a profile's prefix content has drifted.
+ */
+export function hashContent(content) {
+    const canonical = typeof content === 'string'
+        ? content
+        : stableStringify(content);
+    return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+
+/**
+ * Default TTL (seconds) per cache layer. Providers pick their own; callers
+ * that don't specify land on the shortest safe default.
+ */
+export const DEFAULT_TTL_SECONDS = {
+    '1h': 3600,
+    '5m': 300,
+    '24h': 86400,
+    in_memory: 600, // optimistic estimate
+    none: 0,
+};

package/src/agent/orchestrator/smart-bridge/session-builder.mjs

@@ -0,0 +1,116 @@
+/**
+ * Smart Bridge — shared session builder.
+ *
+ * Single source of truth for bridge session creation + role/preset
+ * telemetry. Both entry points route through this helper:
+ *
+ *   - `smart-bridge/bridge-llm.mjs` — internal callers
+ *     (memory-cycle, scheduler, webhook) dispatching via
+ *     `makeBridgeLlm`.
+ *   - `src/agent/index.mjs` `case 'bridge'` — Lead-originated MCP
+ *     bridge dispatches into user-workflow roles.
+ *
+ * Before this helper, the two paths carried separate `createSession` +
+ * `traceBridgePreset` blocks. Lead-direct dispatches silently skipped
+ * the trace so cache-hit analysis missed every user-workflow role call.
+ *
+ * Preset resolution stays with each caller since they read from
+ * different sources (MCP: user-workflow.json only; Smart Bridge:
+ * hidden-role map first, then user-workflow.json). The helper takes
+ * already-resolved primitives.
+ */
+
+import { createSession } from '../session/manager.mjs';
+import { traceBridgePreset } from '../bridge-trace.mjs';
+import { resolveBridgeSessionPermission } from '../internal-roles.mjs';
+
+/**
+ * @param {object} opts
+ * @param {string}  opts.role          — canonical role name ('worker', 'explorer', ...)
+ * @param {string}  opts.presetName    — resolved preset identifier
+ * @param {object}  opts.preset        — resolved preset object from agent-config
+ * @param {object}  opts.runtimeSpec   — resolveRuntimeSpec output; must carry .scopeKey / .lane
+ * @param {string}  [opts.permission]  — 'read' | 'read-write' | null (preset/full default when unset)
+ * @param {string|null} [opts.cwd]     — absolute working dir; null is the fixed bridge sentinel meaning "no caller workspace context"
+ * @param {string}  [opts.owner='bridge']
+ * @param {string}  [opts.permissionMode] — Claude Code permissionMode forwarded from the MCP payload ('bypassPermissions', 'acceptEdits', 'plan', 'dontAsk', 'default')
+ * @param {string[]} [opts.schemaAllowedTools] — schema-level allowlist from a hidden-role toolSchemaProfile
+ * @param {string}  [opts.sourceType]
+ * @param {string}  [opts.sourceName]
+ * @param {string}  [opts.taskType]
+ * @param {number}  [opts.maxLoopIterations]
+ * @param {string}  [opts.parentSessionId]
+ * @param {string|null} [opts.ownerSessionId] - owning Mixdog MCP instance id for statusline isolation
+ * @param {boolean} [opts.skipRoleReminder=false] — Pool C suppresses Tier 3 reminder
+ * @returns {{ session: object, effectiveCwd: string|null }}
+ */
+export function prepareBridgeSession({
+    role,
+    presetName,
+    preset,
+    runtimeSpec,
+    permission,
+    cwd,
+    owner = 'bridge',
+    permissionMode,
+    sourceType,
+    sourceName,
+    taskType,
+    maxLoopIterations,
+    parentSessionId,
+    ownerSessionId,
+    clientHostPid,
+    bridgeTag,
+    skipRoleReminder = false,
+    cacheKeyOverride,
+    schemaAllowedTools,
+}) {
+    const effectivePermission = resolveBridgeSessionPermission(role, permission);
+    // Pass cwd through verbatim — null is the fixed bridge sentinel meaning
+    // "no caller workspace context" (cycle1-agent shards, etc). Upgrading
+    // null → process.cwd() here would defeat cache-shard fork suppression.
+    // Downstream collectors (collect.mjs) handle null as "no project cwd".
+    const effectiveCwd = cwd == null ? null : cwd;
+    const effectiveOwnerSessionId = ownerSessionId === undefined
+        ? (process.env.MIXDOG_OWNER_SESSION_ID || null)
+        : ownerSessionId;
+    const sessionOpts = {
+        preset,
+        owner,
+        scopeKey: runtimeSpec.scopeKey,
+        lane: runtimeSpec.lane,
+        cwd: effectiveCwd,
+        role: role || undefined,
+        taskType: taskType || undefined,
+        maxLoopIterations: Number.isFinite(maxLoopIterations) ? maxLoopIterations : undefined,
+        sourceType: sourceType || undefined,
+        sourceName: sourceName || undefined,
+        ownerSessionId: effectiveOwnerSessionId || null,
+        clientHostPid: clientHostPid || null,
+    };
+    if (bridgeTag) sessionOpts.bridgeTag = bridgeTag;
+    if (effectivePermission) sessionOpts.permission = effectivePermission;
+    if (permissionMode) sessionOpts.permissionMode = permissionMode;
+    if (skipRoleReminder) sessionOpts.skipRoleReminder = true;
+    if (cacheKeyOverride) sessionOpts.cacheKeyOverride = cacheKeyOverride;
+    if (Array.isArray(schemaAllowedTools)) {
+        sessionOpts.schemaAllowedTools = schemaAllowedTools;
+    }
+    const session = createSession(sessionOpts);
+    try {
+        traceBridgePreset({
+            sessionId: session.id,
+            role: role || null,
+            presetName: presetName || null,
+            // runtimeSpec carries scopeKey/lane but resolveRuntimeSpec does not
+            // populate model/provider — fall back to preset fields.
+            model: runtimeSpec?.model || preset?.model || null,
+            provider: runtimeSpec?.provider || preset?.provider || null,
+            parentSessionId: parentSessionId || null,
+            permission: effectivePermission || null,
+            sourceName: sourceName || null,
+            cacheKeyOverride: cacheKeyOverride || null,
+        });
+    } catch { /* telemetry best-effort */ }
+    return { session, effectiveCwd };
+}

package/src/agent/orchestrator/stall-policy.mjs

@@ -0,0 +1,195 @@
+import { getHiddenRole } from './internal-roles.mjs';
+
+const SECOND_MS = 1000;
+const MIN_PROVIDER_TIMEOUT_MS = 30_000;
+
+export const STALL_TICK_MS = 15_000;
+export const DEFAULT_STALL_WARN_S = 300;
+export const DEFAULT_STALL_ABORT_S = 600;
+// First-byte (no-stream-delta) abort for the bridge stall watchdog. A wedged
+// socket can sit at stage=requesting with zero server events. The 30s deadline
+// trialed here false-aborted slow high-reasoning first bytes (e.g. gpt-5.5
+// XHIGH, which can legitimately think >30s before the first delta) and, paired
+// with dispatch auto-retry, produced premature aborts + duplicate re-dispatches.
+// Auto-retry is now removed (bridge-retry.mjs MAX_ATTEMPTS = 1), so a single
+// attempt must get a generous first-byte window: 300s (5 min). Env-overridable.
+export const DEFAULT_STALL_FIRST_BYTE_ABORT_S = (() => {
+    const raw = process.env.MIXDOG_STALL_FIRST_BYTE_ABORT_S;
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) return Math.min(Math.max(n, 5), 600);
+    return 300;
+})();
+
+export function envThresholdSeconds(env = process.env) {
+    const raw = env.STALL_TIMEOUT_S;
+    if (!raw) return null;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0) return null;
+    return n;
+}
+
+export function resolveBaseStallThresholds(env = process.env) {
+    const abort = envThresholdSeconds(env) ?? DEFAULT_STALL_ABORT_S;
+    const warn = abort > DEFAULT_STALL_WARN_S ? DEFAULT_STALL_WARN_S : Math.floor(abort / 2);
+    return { warn, abort };
+}
+
+const _baseThresholds = resolveBaseStallThresholds();
+export const STALL_WARN_S = _baseThresholds.warn;
+export const STALL_ABORT_S = _baseThresholds.abort;
+export const STALL_WARN_MS = STALL_WARN_S * SECOND_MS;
+export const STALL_ABORT_MS = STALL_ABORT_S * SECOND_MS;
+
+export const PROVIDER_MAX_BEFORE_WARN_MS = Math.max(
+    SECOND_MS,
+    STALL_WARN_MS - STALL_TICK_MS,
+);
+
+export function resolveTimeoutMs(envNames, fallbackMs, { minMs = 1_000, maxMs = Number.POSITIVE_INFINITY, env = process.env } = {}) {
+    const names = Array.isArray(envNames) ? envNames : [envNames].filter(Boolean);
+    for (const name of names) {
+        const raw = env?.[name];
+        if (raw == null || raw === '') continue;
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0) {
+            return Math.min(Math.max(n, minMs), maxMs);
+        }
+    }
+    return Math.min(Math.max(fallbackMs, minMs), maxMs);
+}
+
+export const PROVIDER_FIRST_BYTE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_FIRST_BYTE_TIMEOUT_MS',
+    Math.min(120_000, PROVIDER_MAX_BEFORE_WARN_MS),
+    { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_GENERATE_TOTAL_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_GENERATE_TOTAL_TIMEOUT_MS',
+    PROVIDER_MAX_BEFORE_WARN_MS,
+    { minMs: PROVIDER_FIRST_BYTE_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_CACHE_CREATE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_CACHE_CREATE_TIMEOUT_MS',
+    Math.min(120_000, PROVIDER_GENERATE_TOTAL_TIMEOUT_MS),
+    { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_CACHE_CREATE_TOTAL_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_CACHE_CREATE_TOTAL_TIMEOUT_MS',
+    Math.min(180_000, PROVIDER_GENERATE_TOTAL_TIMEOUT_MS),
+    { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_HTTP_RESPONSE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_HTTP_RESPONSE_TIMEOUT_MS',
+    60_000,
+    { minMs: 10_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+// Stream idle watchdog is OFF by default — matches Claude Code native
+// behaviour (its watchdog is gated behind CLAUDE_ENABLE_STREAM_WATCHDOG).
+// The bridge stall watchdog (STALL_ABORT_S, 600s) is the backstop for
+// genuinely dead streams; this short inter-chunk idle watchdog only adds
+// value when explicitly enabled, and otherwise prematurely kills slow
+// high-reasoning streams. Enable with MIXDOG_ENABLE_STREAM_WATCHDOG=1.
+const _sseWatchdogRaw = process.env.MIXDOG_ENABLE_STREAM_WATCHDOG;
+export const PROVIDER_SSE_IDLE_WATCHDOG_ENABLED =
+    _sseWatchdogRaw === '1' || _sseWatchdogRaw === 'true' || _sseWatchdogRaw === 'yes';
+
+export const PROVIDER_SSE_IDLE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_SSE_IDLE_TIMEOUT_MS',
+    90_000,
+    { minMs: 10_000, maxMs: STALL_WARN_MS },
+);
+
+export const PROVIDER_WS_HANDSHAKE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_HANDSHAKE_TIMEOUT_MS',
+    30_000,
+    { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_WS_ACQUIRE_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_ACQUIRE_TIMEOUT_MS',
+    15_000,
+    { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_FIRST_MEANINGFUL_TIMEOUT_MS',
+    PROVIDER_GENERATE_TOTAL_TIMEOUT_MS,
+    { minMs: MIN_PROVIDER_TIMEOUT_MS, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+export const PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_INTER_CHUNK_TIMEOUT_MS',
+    STALL_ABORT_MS,
+    { minMs: STALL_WARN_MS, maxMs: STALL_ABORT_MS },
+);
+
+export const PROVIDER_RETRY_BACKOFF_MS = Object.freeze([0, 1000, 2000, 4000, 8000]);
+export const PROVIDER_RETRY_MAX_ATTEMPTS = PROVIDER_RETRY_BACKOFF_MS.length;
+export const PROVIDER_RETRY_JITTER_RATIO = (() => {
+    const raw = process.env.MIXDOG_PROVIDER_RETRY_JITTER_RATIO;
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return Math.min(n, 1);
+    return 0.2;
+})();
+
+export function resolveBridgeStallThresholds(role, env = process.env) {
+    const cfg = role ? getHiddenRole(role) : null;
+    const cfgAbort = cfg?.stallCap?.idleSeconds > 0 ? cfg.stallCap.idleSeconds : STALL_ABORT_S;
+    const envOverride = envThresholdSeconds(env);
+    const abort = envOverride != null ? envOverride : cfgAbort;
+    // Mid-stream "slow" warning disabled — a bridge stall now notifies ONLY at
+    // the abort deadline (10 min default). warn === abort means the watchdog's
+    // warn branch (verdict 'ok' && stale >= warn) can never fire before 'stall',
+    // so the only notification a stalled bridge worker emits is at the deadline.
+    const warn = abort;
+    // First-byte deadline: a request still in 'requesting' that never produced a
+    // single SSE delta is hung, not slow-reasoning. Abort on this shorter deadline
+    // so the lead is notified in minutes, not at the full mid-stream window.
+    const firstByteAbort = Math.min(abort, DEFAULT_STALL_FIRST_BYTE_ABORT_S);
+    return { warn, abort, firstByteAbort };
+}
+
+export function resolveBridgeToolThresholdSeconds(role, thresholdSeconds) {
+    const cfg = role ? getHiddenRole(role) : null;
+    if (cfg?.stallCap?.toolRunningSeconds > 0) return cfg.stallCap.toolRunningSeconds;
+    return thresholdSeconds;
+}
+
+export function providerTimeoutError(label, timeoutMs) {
+    const err = new Error(`${label} timed out after ${timeoutMs}ms`);
+    err.name = 'ProviderTimeoutError';
+    err.code = 'EPROVIDERTIMEOUT';
+    return err;
+}
+
+export function createTimeoutSignal(parentSignal, timeoutMs, label) {
+    const ac = new AbortController();
+    let timer = null;
+    let parentListener = null;
+    const cleanup = () => {
+        if (timer) { clearTimeout(timer); timer = null; }
+        if (parentListener && parentSignal) {
+            try { parentSignal.removeEventListener('abort', parentListener); } catch {}
+            parentListener = null;
+        }
+    };
+    const abort = (reason) => {
+        try { ac.abort(reason); } catch {}
+    };
+    if (parentSignal) {
+        parentListener = () => abort(parentSignal.reason);
+        if (parentSignal.aborted) {
+            parentListener();
+        } else {
+            parentSignal.addEventListener('abort', parentListener, { once: true });
+        }
+    }
+    timer = setTimeout(() => abort(providerTimeoutError(label, timeoutMs)), timeoutMs);
+    if (typeof timer.unref === 'function') timer.unref();
+    return { signal: ac.signal, cleanup };
+}