@ouro.bot/cli 0.1.0-alpha.482 → 0.1.0-alpha.484

package/dist/heart/mail-import-discovery.js

@@ -0,0 +1,318 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultMailImportDiscoveryDirs = defaultMailImportDiscoveryDirs;
+exports.listDiscoveredMboxCandidates = listDiscoveredMboxCandidates;
+exports.rankDiscoveredMboxCandidates = rankDiscoveredMboxCandidates;
+exports.discoverMailImportFilePath = discoverMailImportFilePath;
+exports.listAmbientMailImportOperations = listAmbientMailImportOperations;
+exports.listVisibleBackgroundOperations = listVisibleBackgroundOperations;
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const background_operations_1 = require("./background-operations");
+const identity = __importStar(require("./identity"));
+const DEFAULT_RECENT_IMPORT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_VISIBLE_BACKGROUND_OPERATION_LIMIT = 5;
+const DEFAULT_VISIBLE_IMPORT_CANDIDATE_LIMIT = 3;
+const DEFAULT_WORKTREE_POOL_SEARCH_DEPTH = 2;
+const DEFAULT_AGENT_WORKSPACE_SCAN_LIMIT = 20;
+const SKIPPED_HOME_SCAN_DIRS = new Set([
+    ".Trash",
+    "Applications",
+    "Library",
+    "Movies",
+    "Music",
+    "Pictures",
+    "Public",
+    "node_modules",
+]);
+function sortBackgroundOperationsNewestFirst(left, right) {
+    return Date.parse(right.updatedAt) - Date.parse(left.updatedAt);
+}
+function recentImportFingerprint(candidates) {
+    return candidates
+        .map((candidate) => `${candidate.path}:${candidate.mtimeMs}`)
+        .sort((left, right) => left.localeCompare(right))
+        .join("|");
+}
+function specText(spec, key) {
+    const value = spec?.[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function latestComparableOperationTimestamp(record) {
+    const fileModifiedAt = specText(record.spec, "fileModifiedAt");
+    if (fileModifiedAt) {
+        const parsed = Date.parse(fileModifiedAt);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    const candidates = [record.finishedAt, record.updatedAt];
+    for (const candidate of candidates) {
+        if (typeof candidate !== "string")
+            continue;
+        const parsed = Date.parse(candidate);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+function candidateAlreadyCoveredByOperation(candidate, operation) {
+    if (operation.kind !== "mail.import-mbox")
+        return false;
+    if (specText(operation.spec, "filePath") !== candidate.path)
+        return false;
+    if (operation.status !== "succeeded")
+        return false;
+    const operationTimestamp = latestComparableOperationTimestamp(operation);
+    return operationTimestamp !== null && candidate.mtimeMs <= operationTimestamp;
+}
+function listChildDirs(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(dir, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+function findWorktreePools(rootDir, maxDepth) {
+    const seen = new Set();
+    const found = [];
+    function visit(currentDir, depth) {
+        if (depth > maxDepth || seen.has(currentDir))
+            return;
+        seen.add(currentDir);
+        let entries;
+        try {
+            entries = fs.readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith(".") && entry.name !== ".playwright-mcp")
+                continue;
+            if (SKIPPED_HOME_SCAN_DIRS.has(entry.name))
+                continue;
+            const childDir = path.join(currentDir, entry.name);
+            if (entry.name === "_worktrees") {
+                found.push(childDir);
+                continue;
+            }
+            visit(childDir, depth + 1);
+        }
+    }
+    visit(rootDir, 0);
+    return found;
+}
+function listAgentWorkspaceSandboxDirs(agentName) {
+    if (!agentName)
+        return [];
+    const getAgentRepoWorkspacesRoot = Object.getOwnPropertyDescriptor(identity, "getAgentRepoWorkspacesRoot")?.value;
+    const workspacesRoot = typeof getAgentRepoWorkspacesRoot === "function"
+        ? getAgentRepoWorkspacesRoot(agentName)
+        : "";
+    if (!workspacesRoot)
+        return [];
+    return listChildDirs(workspacesRoot)
+        .slice(0, DEFAULT_AGENT_WORKSPACE_SCAN_LIMIT)
+        .map((workspaceDir) => path.join(workspaceDir, ".playwright-mcp"));
+}
+function listWorktreePoolSandboxDirs(homeDir) {
+    return findWorktreePools(homeDir, DEFAULT_WORKTREE_POOL_SEARCH_DEPTH)
+        .flatMap((poolDir) => listChildDirs(poolDir))
+        .map((worktreeDir) => path.join(worktreeDir, ".playwright-mcp"));
+}
+function defaultMailImportDiscoveryDirs(input = {}) {
+    const repoRoot = path.resolve(input.repoRoot ?? process.cwd());
+    const homeDir = path.resolve(input.homeDir ?? os.homedir());
+    return [...new Set([
+            path.join(repoRoot, ".playwright-mcp"),
+            ...listAgentWorkspaceSandboxDirs(input.agentName),
+            ...listWorktreePoolSandboxDirs(homeDir),
+            path.join(homeDir, ".playwright-mcp"),
+            path.join(homeDir, "Downloads"),
+        ].map((dir) => path.resolve(dir)))];
+}
+function listDiscoveredMboxCandidates(dir) {
+    if (!fs.existsSync(dir))
+        return [];
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(".mbox"))
+            .map((entry) => {
+            const candidatePath = path.join(dir, entry.name);
+            const stat = fs.statSync(candidatePath);
+            return { path: candidatePath, name: entry.name, mtimeMs: stat.mtimeMs };
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function normalizeMboxDiscoveryText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, " ")
+        .trim();
+}
+function tokenizeMboxDiscoveryHint(value) {
+    if (!value)
+        return [];
+    return normalizeMboxDiscoveryText(value)
+        .split(" ")
+        .filter((token) => token.length > 0);
+}
+function scoreDiscoveredMboxCandidate(fileName, mtimeMs, ownerEmail, source) {
+    const normalized = normalizeMboxDiscoveryText(fileName);
+    const ownerTokens = tokenizeMboxDiscoveryHint(ownerEmail);
+    const sourceTokens = tokenizeMboxDiscoveryHint(source);
+    const ownerScore = ownerTokens.reduce((score, token) => score + (normalized.includes(token) ? 50 : 0), 0);
+    const sourceScore = sourceTokens.reduce((score, token) => score + (normalized.includes(token) ? 20 : 0), 0);
+    const recencyScore = Math.floor(mtimeMs / 1000);
+    return ownerScore + sourceScore + recencyScore;
+}
+function rankDiscoveredMboxCandidates(candidates, ownerEmail, source) {
+    return candidates
+        .map((candidate) => ({
+        path: candidate.path,
+        score: scoreDiscoveredMboxCandidate(candidate.name, candidate.mtimeMs, ownerEmail, source),
+    }))
+        .sort((left, right) => right.score - left.score);
+}
+function discoverMailImportFilePath(input) {
+    const searchDirs = defaultMailImportDiscoveryDirs({
+        agentName: input.agentName,
+        repoRoot: input.repoRoot,
+        homeDir: input.homeDir,
+    });
+    const candidates = searchDirs.flatMap((dir) => listDiscoveredMboxCandidates(dir));
+    const ranked = rankDiscoveredMboxCandidates(candidates, input.ownerEmail, input.source);
+    if (ranked.length === 0) {
+        throw new Error(`could not discover an MBOX file in ${searchDirs.join(", ")}`);
+    }
+    const topScore = ranked[0].score;
+    const topCandidates = ranked.filter((candidate) => candidate.score === topScore);
+    if (topCandidates.length > 1) {
+        throw new Error(`multiple candidate MBOX files found: ${topCandidates.map((candidate) => candidate.path).join(", ")}`);
+    }
+    return topCandidates[0].path;
+}
+function summarizeAmbientImportCandidates(candidates, candidateLimit) {
+    const visibleCandidates = candidates.slice(0, candidateLimit);
+    const hiddenCount = Math.max(0, candidates.length - visibleCandidates.length);
+    const summary = visibleCandidates.length === 1
+        ? "recent MBOX archive ready for import"
+        : `${visibleCandidates.length} recent MBOX archives ready for import`;
+    const detailLines = [
+        "recent candidates:",
+        ...visibleCandidates.map((candidate) => `- ${candidate.path}`),
+        ...(hiddenCount > 0 ? [`- ...and ${hiddenCount} more recent archive${hiddenCount === 1 ? "" : "s"}`] : []),
+        "next: if one matches an outstanding mail backfill, run `ouro mail import-mbox --discover` with owner/source hints so Ouro can select the right archive or report ambiguity.",
+    ];
+    return {
+        summary,
+        detail: detailLines.join("\n"),
+        spec: {
+            fingerprint: recentImportFingerprint(candidates),
+            candidatePaths: visibleCandidates.map((candidate) => candidate.path),
+            newestCandidatePath: visibleCandidates[0]?.path ?? null,
+            newestCandidateMtime: visibleCandidates[0] ? new Date(visibleCandidates[0].mtimeMs).toISOString() : null,
+        },
+    };
+}
+function listAmbientMailImportOperations(input) {
+    const existingOperations = input.existingOperations ?? [];
+    const hasLiveImport = existingOperations.some((operation) => operation.kind === "mail.import-mbox"
+        && (operation.status === "queued" || operation.status === "running"));
+    if (hasLiveImport)
+        return [];
+    const nowMs = input.nowMs ?? Date.now();
+    const recentWindowMs = input.recentWindowMs ?? DEFAULT_RECENT_IMPORT_WINDOW_MS;
+    const candidateLimit = input.candidateLimit ?? DEFAULT_VISIBLE_IMPORT_CANDIDATE_LIMIT;
+    const recentCandidates = defaultMailImportDiscoveryDirs({
+        agentName: input.agentName,
+        repoRoot: input.repoRoot,
+        homeDir: input.homeDir,
+    })
+        .flatMap((dir) => listDiscoveredMboxCandidates(dir))
+        .filter((candidate) => (nowMs - candidate.mtimeMs) <= recentWindowMs)
+        .filter((candidate) => !existingOperations.some((operation) => candidateAlreadyCoveredByOperation(candidate, operation)))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs);
+    if (recentCandidates.length === 0)
+        return [];
+    const newestCandidate = recentCandidates[0];
+    const rendered = summarizeAmbientImportCandidates(recentCandidates, candidateLimit);
+    return [{
+            schemaVersion: 1,
+            id: "ambient_mail_import_ready",
+            agentName: input.agentName,
+            kind: "mail.import-discovered",
+            title: "mail import ready",
+            status: "queued",
+            summary: rendered.summary,
+            detail: rendered.detail,
+            createdAt: new Date(newestCandidate.mtimeMs).toISOString(),
+            updatedAt: new Date(newestCandidate.mtimeMs).toISOString(),
+            spec: rendered.spec,
+        }];
+}
+function listVisibleBackgroundOperations(input) {
+    const limit = input.limit ?? DEFAULT_VISIBLE_BACKGROUND_OPERATION_LIMIT;
+    const persisted = (0, background_operations_1.listBackgroundOperations)({
+        agentName: input.agentName,
+        agentRoot: input.agentRoot,
+        limit,
+    });
+    const ambient = listAmbientMailImportOperations({
+        agentName: input.agentName,
+        agentRoot: input.agentRoot,
+        existingOperations: persisted,
+        repoRoot: input.repoRoot,
+        homeDir: input.homeDir,
+        nowMs: input.nowMs,
+        recentWindowMs: input.recentWindowMs,
+        candidateLimit: input.candidateLimit,
+    });
+    return [...persisted, ...ambient]
+        .sort(sortBackgroundOperationsNewestFirst)
+        .slice(0, limit);
+}

package/dist/heart/outlook/outlook-http-routes.js

@@ -53,7 +53,7 @@ function createOutlookHttpRequestHandler(options) {
             (0, outlook_http_response_1.writeJson)(response, 404, { ok: false, error: "asset not found" });
             return;
         }
-        if (pathname === "/outlook") {
+        if (pathname === "/outlook" || pathname === "/mailbox") {
             response.writeHead(301, { location: "/" });
             response.end();
             return;

package/dist/heart/outlook/outlook-http-static.js

@@ -61,6 +61,10 @@ function normalizeLegacyOutlookApiPath(pathname) {
         return pathname.slice("/outlook".length);
     if (pathname === "/outlook/api")
         return "/api";
+    if (pathname.startsWith("/mailbox/api/"))
+        return pathname.slice("/mailbox".length);
+    if (pathname === "/mailbox/api")
+        return "/api";
     return pathname;
 }
 function defaultSpaDistCandidates() {

package/dist/heart/outlook/outlook-http.js

@@ -76,7 +76,7 @@ async function startOutlookHttpServer(options = {}) {
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.outlook_http_started",
-        message: "started Outlook HTTP server",
+        message: "started Mailbox HTTP server",
         meta: { origin },
     });
     return {
@@ -91,7 +91,7 @@ async function startOutlookHttpServer(options = {}) {
             (0, runtime_1.emitNervesEvent)({
                 component: "daemon",
                 event: "daemon.outlook_http_stopped",
-                message: "stopped Outlook HTTP server",
+                message: "stopped Mailbox HTTP server",
                 meta: { origin },
             });
         },

package/dist/heart/outlook/outlook-types.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OUTLOOK_DEFAULT_PORT = exports.OUTLOOK_DEFAULT_INNER_VISIBILITY = exports.OUTLOOK_RELEASE_INTERACTION_MODEL = exports.OUTLOOK_PRODUCT_NAME = void 0;
 exports.getOutlookTranscriptMessageText = getOutlookTranscriptMessageText;
 exports.getOutlookTranscriptTimestamp = getOutlookTranscriptTimestamp;
-exports.OUTLOOK_PRODUCT_NAME = "Ouro Outlook";
+exports.OUTLOOK_PRODUCT_NAME = "Ouro Mailbox";
 exports.OUTLOOK_RELEASE_INTERACTION_MODEL = "read-only";
 exports.OUTLOOK_DEFAULT_INNER_VISIBILITY = "summary";
 exports.OUTLOOK_DEFAULT_PORT = 6876;

package/dist/heart/outlook/outlook-view.js

@@ -94,8 +94,8 @@ function buildOutlookMachineView(input) {
             totals,
             mood: deriveMood(input.machine, input.daemon),
             entrypoints: [
-                { kind: "web", label: "Open Outlook", target: input.daemon.outlookUrl },
-                { kind: "cli", label: "CLI JSON", target: "ouro outlook --json" },
+                { kind: "web", label: "Open Mailbox", target: input.daemon.outlookUrl },
+                { kind: "cli", label: "CLI JSON", target: "ouro mailbox --json" },
             ],
         },
         agents,
@@ -162,7 +162,7 @@ function buildRecentActivity(agent) {
 }
 function buildOutlookAgentView(input) {
     /* v8 ignore next */
-    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.outlook_view_agent", message: `building outlook view for ${input.agent.agentName}`, meta: { agent: input.agent.agentName } });
+    (0, runtime_1.emitNervesEvent)({ component: "daemon", event: "daemon.outlook_view_agent", message: `building mailbox view for ${input.agent.agentName}`, meta: { agent: input.agent.agentName } });
     const viewer = normalizeViewer(input.viewer);
     return {
         productName: outlook_types_1.OUTLOOK_PRODUCT_NAME,

package/dist/heart/outlook/readers/agent-machine.js

@@ -115,19 +115,42 @@ function readTaskSummary(agentRoot) {
         issues,
     };
 }
+const STALE_CODING_SURFACE_WINDOW_MS = 60 * 60 * 1000;
+function buildLiveCodingSurfaceLabels(agentRoot) {
+    return new Set(readCodingSummary(agentRoot).items
+        .filter((item) => shared_1.ACTIVE_CODING_STATUSES.has(item.status))
+        .map((item) => `${item.runner} ${item.id}`));
+}
+function normalizeObligationCurrentSurface(currentSurface, updatedAt, liveCodingSurfaceLabels) {
+    if (!currentSurface || currentSurface.kind !== "coding")
+        return currentSurface;
+    const liveLabel = currentSurface.label.trim();
+    if (!liveLabel)
+        return null;
+    if (liveCodingSurfaceLabels.has(liveLabel))
+        return currentSurface;
+    const updatedAtMs = Date.parse(updatedAt);
+    const recentlyTouched = Number.isFinite(updatedAtMs)
+        && (Date.now() - updatedAtMs) <= STALE_CODING_SURFACE_WINDOW_MS;
+    return recentlyTouched ? currentSurface : null;
+}
 function readObligationSummary(agentRoot) {
+    const liveCodingSurfaceLabels = buildLiveCodingSurfaceLabels(agentRoot);
     const items = (0, obligations_1.readPendingObligations)(agentRoot)
-        .map((obligation) => ({
-        id: obligation.id,
-        status: obligation.status,
-        content: obligation.content,
-        updatedAt: obligation.updatedAt ?? obligation.createdAt,
-        nextAction: obligation.nextAction ?? null,
-        /* v8 ignore start */
-        origin: obligation.origin ?? null,
-        currentSurface: obligation.currentSurface ?? null,
-        /* v8 ignore stop */
-    }))
+        .map((obligation) => {
+        const updatedAt = obligation.updatedAt ?? obligation.createdAt;
+        return {
+            id: obligation.id,
+            status: obligation.status,
+            content: obligation.content,
+            updatedAt,
+            nextAction: obligation.nextAction ?? null,
+            /* v8 ignore start */
+            origin: obligation.origin ?? null,
+            currentSurface: normalizeObligationCurrentSurface(obligation.currentSurface ?? null, updatedAt, liveCodingSurfaceLabels),
+            /* v8 ignore stop */
+        };
+    })
         .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
     return { items };
 }

package/dist/heart/outlook/readers/continuity-readers.js

@@ -49,6 +49,7 @@ const presence_1 = require("../../../arc/presence");
 const scanner_1 = require("../../../repertoire/tasks/scanner");
 const active_work_1 = require("../../active-work");
 const session_activity_1 = require("../../session-activity");
+const agent_machine_1 = require("./agent-machine");
 function sortOpenObligations(obligations) {
     const statusPriority = {
         returning: 0,
@@ -185,6 +186,7 @@ function readObligationDetailView(agentRoot) {
     const openObligations = obligations.filter(obligations_1.isOpenObligation);
     const sorted = sortOpenObligations(openObligations);
     const primary = sorted[0] ?? null;
+    const normalizedSummary = new Map((0, agent_machine_1.readObligationSummary)(agentRoot).items.map((item) => [item.id, item.currentSurface]));
     const items = openObligations.map((ob) => ({
         id: ob.id,
         status: ob.status,
@@ -192,7 +194,9 @@ function readObligationDetailView(agentRoot) {
         updatedAt: ob.updatedAt ?? ob.createdAt,
         nextAction: ob.nextAction ?? null,
         origin: ob.origin ?? null,
-        currentSurface: ob.currentSurface ? { kind: ob.currentSurface.kind, label: ob.currentSurface.label } : null,
+        currentSurface: normalizedSummary.has(ob.id)
+            ? (normalizedSummary.get(ob.id) ?? null)
+            : (ob.currentSurface ? { kind: ob.currentSurface.kind, label: ob.currentSurface.label } : null),
         meaning: ob.meaning ? { waitingOn: ob.meaning.waitingOn?.detail ?? null } : null,
         isPrimary: ob.id === primary.id,
     }));

package/dist/heart/outlook/readers/mail.js

@@ -247,7 +247,7 @@ function emitMailRead(agentName, mode, status) {
     (0, runtime_1.emitNervesEvent)({
         component: "heart",
         event: "heart.outlook_mail_read",
-        message: "reading Outlook mail surface",
+        message: "reading Mailbox mail surface",
         meta: { agentName, mode, status },
     });
 }
@@ -271,7 +271,7 @@ async function readMailView(agentName) {
         await resolved.store.recordAccess({
             agentId: agentName,
             tool: "outlook_mail_list",
-            reason: "outlook read-only mailbox",
+            reason: "mailbox read-only mailbox",
         });
         const accessLog = accessEntries(await resolved.store.listAccessLog(agentName));
         emitMailRead(agentName, "list", "ready");
@@ -325,7 +325,7 @@ async function readMailMessageView(agentName, messageId) {
             agentId: agentName,
             messageId,
             tool: "outlook_mail_message",
-            reason: "outlook read-only message body",
+            reason: "mailbox read-only message body",
             ...accessProvenance(decrypted),
         });
         const body = decrypted.private.text.length > OUTLOOK_MAIL_BODY_LIMIT

package/dist/heart/provider-failover.js

@@ -5,6 +5,7 @@ exports.formatReadyProviderLabel = formatReadyProviderLabel;
 exports.buildFailoverContext = buildFailoverContext;
 exports.handleFailoverReply = handleFailoverReply;
 exports.runMachineProviderFailoverInventory = runMachineProviderFailoverInventory;
+exports.validateFailoverSwitchCandidate = validateFailoverSwitchCandidate;
 const identity_1 = require("./identity");
 const provider_ping_1 = require("./provider-ping");
 const provider_models_1 = require("./provider-models");
@@ -170,6 +171,7 @@ function buildFailoverContext(errorMessage, classification, currentProvider, cur
         errorSummary,
         classification,
         currentProvider,
+        currentModel,
         currentLane,
         agentName,
         workingProviders,
@@ -264,3 +266,36 @@ async function runMachineProviderFailoverInventory(agentName, currentProvider, o
     });
     return inventory;
 }
+/**
+ * Re-verify a failover candidate is actually reachable right before we mutate
+ * provider state. The inventory ping that produced the candidate may be stale
+ * (creds revoked between inventory and reply); without this preflight, an
+ * agent-driven "switch to <provider>" can move the lane onto an unreachable
+ * provider and brick the next turn.
+ */
+async function validateFailoverSwitchCandidate(agentName, candidate, options = {}) {
+    const ping = options.ping ?? provider_ping_1.pingProvider;
+    const refreshPool = options.refreshPool ?? provider_credentials_1.refreshProviderCredentialPool;
+    const poolResult = await refreshPool(agentName);
+    if (!poolResult.ok) {
+        return {
+            ok: false,
+            classification: "auth-failure",
+            message: `provider credential pool unavailable (${poolResult.reason}): ${poolResult.error}`,
+        };
+    }
+    const record = poolResult.pool.providers[candidate.provider];
+    if (!record) {
+        return {
+            ok: false,
+            classification: "auth-failure",
+            message: `no credentials configured for ${candidate.provider}`,
+        };
+    }
+    const config = { ...record.credentials, ...record.config };
+    const result = await ping(candidate.provider, config, { model: candidate.model });
+    if (!result.ok) {
+        return { ok: false, classification: result.classification, message: result.message };
+    }
+    return { ok: true };
+}