@ouro.bot/cli 0.1.0-alpha.2 → 0.1.0-alpha.200

package/dist/heart/presence.js

@@ -0,0 +1,185 @@
+"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.derivePresence = derivePresence;
+exports.writePresence = writePresence;
+exports.readPresence = readPresence;
+exports.readPeerPresence = readPeerPresence;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const runtime_1 = require("../nerves/runtime");
+function presenceDir(agentRoot) {
+    return path.join(agentRoot, "state", "presence");
+}
+function deriveAvailability(inputs) {
+    if (inputs.currentTempo === "crisis")
+        return "dnd";
+    if (inputs.activeSessions > 0)
+        return "active";
+    if (inputs.openObligations > 0)
+        return "idle";
+    return "away";
+}
+function deriveLane(inputs) {
+    const hasCoding = inputs.codingLanes > 0;
+    const hasBridges = inputs.activeBridges > 0;
+    if (hasCoding && hasBridges)
+        return "mixed";
+    if (hasCoding)
+        return "coding";
+    if (hasBridges)
+        return "conversation";
+    return "idle";
+}
+function deriveMission(inputs) {
+    const parts = [];
+    if (inputs.openObligations > 0) {
+        parts.push(`${inputs.openObligations} open obligation${inputs.openObligations !== 1 ? "s" : ""}`);
+    }
+    if (inputs.activeBridges > 0) {
+        parts.push(`${inputs.activeBridges} active bridge${inputs.activeBridges !== 1 ? "s" : ""}`);
+    }
+    if (inputs.codingLanes > 0) {
+        parts.push(`${inputs.codingLanes} coding lane${inputs.codingLanes !== 1 ? "s" : ""}`);
+    }
+    if (parts.length === 0)
+        return "no active work";
+    return parts.join(", ");
+}
+function derivePresence(_agentRoot, agentName, inputs) {
+    const presence = {
+        agentName,
+        availability: deriveAvailability(inputs),
+        lane: deriveLane(inputs),
+        mission: deriveMission(inputs),
+        tempo: inputs.currentTempo,
+        updatedAt: new Date().toISOString(),
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.presence_derived",
+        message: `presence derived: ${presence.availability}/${presence.lane}`,
+        meta: {
+            agentName,
+            availability: presence.availability,
+            lane: presence.lane,
+            tempo: presence.tempo,
+        },
+    });
+    return presence;
+}
+function writePresence(agentRoot, _agentName, presence) {
+    const dir = presenceDir(agentRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "self.json"), JSON.stringify(presence, null, 2), "utf-8");
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.presence_written",
+        message: `presence written for ${presence.agentName}`,
+        meta: { agentName: presence.agentName },
+    });
+}
+function readPresence(agentRoot, _agentName) {
+    const filePath = path.join(presenceDir(agentRoot), "self.json");
+    if (!fs.existsSync(filePath)) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.presence_read",
+            message: "presence file not found",
+            meta: { found: false },
+        });
+        return null;
+    }
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        const presence = JSON.parse(raw);
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.presence_read",
+            message: `presence read: ${presence.availability}`,
+            meta: { agentName: presence.agentName, found: true },
+        });
+        return presence;
+    }
+    catch {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.presence_read_error",
+            message: "failed to read presence file",
+            meta: { error: "parse error" },
+        });
+        return null;
+    }
+}
+function readPeerPresence(agentRoot) {
+    const friendsDir = path.join(agentRoot, "friends");
+    if (!fs.existsSync(friendsDir)) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.peer_presence_read",
+            message: "no friends directory, no peers",
+            meta: { peerCount: 0 },
+        });
+        return [];
+    }
+    const files = fs.readdirSync(friendsDir).filter((f) => f.endsWith(".json"));
+    const peers = [];
+    for (const file of files) {
+        try {
+            const raw = fs.readFileSync(path.join(friendsDir, file), "utf-8");
+            const friend = JSON.parse(raw);
+            if (friend.kind !== "agent")
+                continue;
+            peers.push({
+                agentName: friend.name ?? path.basename(file, ".json"),
+                availability: "idle",
+                lane: "idle",
+                mission: "",
+                tempo: "brief",
+                updatedAt: friend.updatedAt ?? new Date().toISOString(),
+            });
+        }
+        catch {
+            // Skip malformed or unreadable files
+        }
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.peer_presence_read",
+        message: `read ${peers.length} agent peer records from friends`,
+        meta: { peerCount: peers.length },
+    });
+    return peers;
+}

package/dist/heart/progress-story.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProgressStory = buildProgressStory;
+exports.renderProgressStory = renderProgressStory;
+const runtime_1 = require("../nerves/runtime");
+function labelForScope(scope) {
+    return scope === "inner-delegation" ? "inner work" : "shared work";
+}
+function compactDetail(text) {
+    if (typeof text !== "string")
+        return null;
+    const trimmed = text.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function buildProgressStory(input) {
+    const detailLines = [
+        compactDetail(input.objective),
+        compactDetail(input.outcomeText),
+        compactDetail(input.bridgeId ? `bridge: ${input.bridgeId}` : null),
+        compactDetail(input.taskName ? `task: ${input.taskName}` : null),
+    ].filter((line) => Boolean(line));
+    const story = {
+        statusLine: `${labelForScope(input.scope)}: ${input.phase}`,
+        detailLines,
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.progress_story_build",
+        message: "built shared progress story",
+        meta: {
+            scope: input.scope,
+            phase: input.phase,
+            detailLines: detailLines.length,
+            hasBridge: Boolean(input.bridgeId),
+            hasTask: Boolean(input.taskName),
+        },
+    });
+    return story;
+}
+function renderProgressStory(story) {
+    return [story.statusLine, ...story.detailLines].join("\n");
+}

package/dist/heart/provider-failover.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFailoverContext = buildFailoverContext;
+exports.handleFailoverReply = handleFailoverReply;
+const runtime_1 = require("../nerves/runtime");
+const FAILING_PROVIDER_LABELS = {
+    "auth-failure": "its credentials need to be refreshed",
+    "usage-limit": "has also hit its usage limit",
+    "rate-limit": "is also being rate limited",
+    "server-error": "is also experiencing an outage",
+    "network-error": "could not be reached",
+    "unknown": "could not be reached",
+};
+const CLASSIFICATION_LABELS = {
+    "auth-failure": "authentication failed",
+    "usage-limit": "hit its usage limit",
+    "rate-limit": "is being rate limited",
+    "server-error": "is experiencing an outage",
+    "network-error": "is unreachable (network error)",
+    "unknown": "encountered an error",
+};
+function buildFailoverContext(_errorMessage, classification, currentProvider, currentModel, agentName, inventory, providerModels) {
+    const label = CLASSIFICATION_LABELS[classification];
+    const providerWithModel = currentModel ? `${currentProvider} (${currentModel})` : currentProvider;
+    const errorSummary = `${providerWithModel} ${label}`;
+    const workingProviders = [];
+    const unconfiguredProviders = [];
+    const failingProviders = [];
+    for (const [provider, result] of Object.entries(inventory)) {
+        if (result.ok) {
+            workingProviders.push(provider);
+        }
+        else if (result.classification === "auth-failure" && result.message === "no credentials configured") {
+            unconfiguredProviders.push(provider);
+        }
+        else {
+            // Configured but ping failed (expired token, provider also down, etc.)
+            failingProviders.push({ provider, classification: result.classification });
+        }
+    }
+    const lines = [`${errorSummary}.`];
+    if (workingProviders.length > 0) {
+        const switchDescriptions = workingProviders.map((p) => {
+            const model = providerModels[p];
+            return model ? `${p} (${model})` : /* v8 ignore next -- defensive: model always present in secrets @preserve */ p;
+        });
+        const switchOptions = workingProviders.map((p) => `"switch to ${p}"`).join(" or ");
+        lines.push(`these providers are ready to go: ${switchDescriptions.join(", ")}.`);
+        lines.push(`reply ${switchOptions} to continue.`);
+    }
+    if (failingProviders.length > 0) {
+        for (const { provider, classification } of failingProviders) {
+            /* v8 ignore next -- defensive: all classifications have labels @preserve */
+            const detail = FAILING_PROVIDER_LABELS[classification] ?? "could not be reached";
+            lines.push(`${provider} is configured but ${detail}. run \`ouro auth --agent ${agentName} --provider ${provider}\` to refresh.`);
+        }
+    }
+    if (unconfiguredProviders.length > 0) {
+        lines.push(`to set up ${unconfiguredProviders.join(", ")}, run \`ouro auth --agent ${agentName}\` in terminal.`);
+    }
+    if (workingProviders.length === 0 && unconfiguredProviders.length === 0 && failingProviders.length === 0) {
+        lines.push(`no other providers are available. run \`ouro auth --agent ${agentName}\` in terminal to configure one.`);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.failover_context_built",
+        message: "built provider failover context",
+        meta: { currentProvider, classification, workingProviders, unconfiguredProviders },
+    });
+    return {
+        errorSummary,
+        classification,
+        currentProvider,
+        agentName,
+        workingProviders,
+        unconfiguredProviders,
+        userMessage: lines.join(" "),
+    };
+}
+function handleFailoverReply(reply, context) {
+    const lower = reply.toLowerCase().trim();
+    for (const provider of context.workingProviders) {
+        if (lower.includes(`switch to ${provider}`) || lower === provider) {
+            return { action: "switch", provider };
+        }
+    }
+    return { action: "dismiss" };
+}

package/dist/heart/provider-ping.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeErrorMessage = sanitizeErrorMessage;
+exports.pingProvider = pingProvider;
+exports.runHealthInventory = runHealthInventory;
+const anthropic_1 = require("./providers/anthropic");
+const azure_1 = require("./providers/azure");
+const minimax_1 = require("./providers/minimax");
+const openai_codex_1 = require("./providers/openai-codex");
+const github_copilot_1 = require("./providers/github-copilot");
+const auth_flow_1 = require("./daemon/auth-flow");
+const runtime_1 = require("../nerves/runtime");
+const PING_TIMEOUT_MS = 10_000;
+/**
+ * Strip raw JSON/HTML API response bodies from error messages.
+ * SDK errors often include the full response: "400 {"type":"error",...}" or "403 <html>...".
+ * Extract just the HTTP status and a short human-readable summary.
+ */
+function sanitizeErrorMessage(message) {
+    const statusMatch = message.match(/^(\d{3})\s/);
+    if (!statusMatch)
+        return message;
+    const status = statusMatch[1];
+    const body = message.slice(status.length).trim();
+    // HTML response (Cloudflare challenge, error pages, etc.)
+    if (body.startsWith("<") || body.includes("<!DOCTYPE") || body.includes("<html")) {
+        return `HTTP ${status}`;
+    }
+    // JSON response
+    if (body.startsWith("{")) {
+        try {
+            const json = JSON.parse(body);
+            const inner = json?.error?.message;
+            if (typeof inner === "string" && inner && inner !== "Error") {
+                return `${status} ${inner}`;
+            }
+        }
+        catch { /* not valid JSON */ }
+        return `HTTP ${status}`;
+    }
+    // Already clean (e.g., "401 Provided authentication token is expired.")
+    return message;
+}
+function hasEmptyCredentials(provider, config) {
+    switch (provider) {
+        case "anthropic":
+            return !config.setupToken;
+        case "openai-codex":
+            return !config.oauthAccessToken;
+        case "minimax":
+            return !config.apiKey;
+        case "azure": {
+            const azure = config;
+            return !(azure.apiKey && azure.endpoint && azure.deployment);
+        }
+        case "github-copilot": {
+            const copilot = config;
+            return !(copilot.githubToken && copilot.baseUrl);
+        }
+        /* v8 ignore next 2 -- exhaustive: all providers handled above @preserve */
+        default:
+            return true;
+    }
+}
+function createRuntimeForPing(provider, _config) {
+    // The provider constructors read credentials from the active config via getXxxConfig().
+    // For ping, this is acceptable because verifyProviderCredentials patches the runtime
+    // config before calling ping. The model string is a default — for anthropic the ping
+    // overrides it with haiku anyway, and for others it's used in a minimal API call.
+    const DEFAULT_MODELS = {
+        anthropic: "claude-haiku-4-5-20251001",
+        azure: "gpt-4o",
+        minimax: "MiniMax-M2.7",
+        "openai-codex": "codex-mini-latest",
+        "github-copilot": "gpt-4o",
+    };
+    /* v8 ignore next -- fallback: all known providers are in DEFAULT_MODELS @preserve */
+    const model = DEFAULT_MODELS[provider] ?? "unknown";
+    switch (provider) {
+        case "anthropic":
+            return (0, anthropic_1.createAnthropicProviderRuntime)(model);
+        case "azure":
+            return (0, azure_1.createAzureProviderRuntime)(model);
+        case "minimax":
+            return (0, minimax_1.createMinimaxProviderRuntime)(model);
+        case "openai-codex":
+            return (0, openai_codex_1.createOpenAICodexProviderRuntime)(model);
+        case "github-copilot":
+            return (0, github_copilot_1.createGithubCopilotProviderRuntime)(model);
+        /* v8 ignore next 2 -- exhaustive: all providers handled above @preserve */
+        default:
+            throw new Error(`unsupported provider for ping: ${provider}`);
+    }
+}
+async function pingProvider(provider, config) {
+    if (hasEmptyCredentials(provider, config)) {
+        return { ok: false, classification: "auth-failure", message: "no credentials configured" };
+    }
+    let runtime;
+    try {
+        runtime = createRuntimeForPing(provider, config);
+        /* v8 ignore start -- factory creation failure: tested via individual provider init tests @preserve */
+    }
+    catch (error) {
+        return {
+            ok: false,
+            classification: "auth-failure",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
+    /* v8 ignore stop */
+    try {
+        const controller = new AbortController();
+        /* v8 ignore next -- timeout callback: only fires after 10s, tests resolve faster @preserve */
+        const timeout = setTimeout(() => controller.abort(), PING_TIMEOUT_MS);
+        try {
+            // Minimal API call — no thinking, no reasoning, no tools.
+            if (provider === "anthropic") {
+                // Use haiku for the ping — setup tokens may not have access to newer
+                // models, but if haiku works, the credentials are valid.
+                // Override the beta header to exclude thinking (which requires a
+                // thinking param in the request body).
+                const client = runtime.client;
+                await client.messages.create({ model: "claude-haiku-4-5-20251001", max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal: controller.signal, headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" } });
+            }
+            else if (provider === "openai-codex") {
+                // Codex uses the Responses API (chatgpt.com/backend-api/codex/responses),
+                // not the Chat Completions API. Ping via responses endpoint.
+                const client = runtime.client;
+                await client.responses.create({ model: runtime.model, input: "ping", store: false }, { signal: controller.signal });
+            }
+            else {
+                // OpenAI-compatible providers (azure, minimax, github-copilot)
+                const client = runtime.client;
+                await client.chat.completions.create({ model: runtime.model, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal: controller.signal });
+            }
+            return { ok: true };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    catch (error) {
+        const err = error instanceof Error ? error : /* v8 ignore next -- defensive @preserve */ new Error(String(error));
+        let classification;
+        try {
+            classification = runtime.classifyError(err);
+        }
+        catch {
+            /* v8 ignore next -- defensive: classifyError should not throw @preserve */
+            classification = "unknown";
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.provider_ping_fail",
+            message: `provider ping failed: ${provider}`,
+            meta: { provider, classification, error: err.message },
+        });
+        return { ok: false, classification, message: sanitizeErrorMessage(err.message) };
+    }
+}
+const PINGABLE_PROVIDERS = ["anthropic", "openai-codex", "azure", "minimax", "github-copilot"];
+async function runHealthInventory(agentName, currentProvider, deps = {}) {
+    /* v8 ignore next -- default: tests inject ping dep @preserve */
+    const ping = deps.ping ?? pingProvider;
+    const { secrets } = (0, auth_flow_1.loadAgentSecrets)(agentName);
+    const providers = PINGABLE_PROVIDERS.filter((p) => p !== currentProvider);
+    const results = await Promise.all(providers.map(async (provider) => {
+        const config = secrets.providers[provider];
+        const result = await ping(provider, config);
+        return [provider, result];
+    }));
+    const inventory = {};
+    for (const [provider, result] of results) {
+        inventory[provider] = result;
+    }
+    return inventory;
+}

package/dist/heart/providers/anthropic-token.js

@@ -0,0 +1,163 @@
+"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.needsRefresh = needsRefresh;
+exports.refreshAnthropicToken = refreshAnthropicToken;
+exports.persistTokenState = persistTokenState;
+exports.ensureFreshToken = ensureFreshToken;
+/* v8 ignore start -- OAuth token lifecycle: requires live API calls, tested via integration @preserve */
+const fs = __importStar(require("fs"));
+const runtime_1 = require("../../nerves/runtime");
+const identity_1 = require("../identity");
+const OAUTH_TOKEN_ENDPOINT = "https://console.anthropic.com/v1/oauth/token";
+const OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+const REFRESH_MARGIN_MS = 5 * 60 * 1000; // refresh 5 minutes before expiry
+/**
+ * Check if the Anthropic OAuth token needs refreshing.
+ * Returns true if no expiresAt is set (legacy token) or if within 5 min of expiry.
+ */
+function needsRefresh(expiresAt) {
+    if (!expiresAt)
+        return true; // legacy token with no expiry — always try refresh
+    return Date.now() > expiresAt - REFRESH_MARGIN_MS;
+}
+/**
+ * Refresh an Anthropic OAuth access token using the refresh token.
+ * Returns the new token state or null if refresh fails.
+ */
+async function refreshAnthropicToken(refreshToken, fetchImpl = fetch) {
+    try {
+        const response = await fetchImpl(OAUTH_TOKEN_ENDPOINT, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: OAUTH_CLIENT_ID,
+            }),
+        });
+        if (!response.ok) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "engine",
+                event: "engine.anthropic_token_refresh_failed",
+                message: `token refresh failed: ${response.status}`,
+                meta: { status: response.status },
+            });
+            return null;
+        }
+        const json = await response.json();
+        if (!json.access_token) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "engine",
+                event: "engine.anthropic_token_refresh_failed",
+                message: "token refresh returned no access_token",
+                meta: {},
+            });
+            return null;
+        }
+        const state = {
+            accessToken: json.access_token,
+            refreshToken: json.refresh_token ?? refreshToken, // keep old if not returned
+            expiresAt: Date.now() + (json.expires_in ?? 28800) * 1000, // default 8h
+        };
+        (0, runtime_1.emitNervesEvent)({
+            component: "engine",
+            event: "engine.anthropic_token_refreshed",
+            message: "anthropic OAuth token refreshed",
+            meta: { expiresAt: new Date(state.expiresAt).toISOString() },
+        });
+        return state;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "engine",
+            event: "engine.anthropic_token_refresh_error",
+            message: "token refresh threw",
+            meta: { error: error instanceof Error ? error.message : String(error) },
+        });
+        return null;
+    }
+}
+/**
+ * Persist refreshed token state back to secrets.json.
+ */
+function persistTokenState(agentName, state) {
+    try {
+        const secretsPath = (0, identity_1.getAgentSecretsPath)(agentName);
+        const raw = fs.readFileSync(secretsPath, "utf-8");
+        const secrets = JSON.parse(raw);
+        secrets.providers = secrets.providers ?? {};
+        secrets.providers.anthropic = secrets.providers.anthropic ?? {};
+        secrets.providers.anthropic.setupToken = state.accessToken;
+        secrets.providers.anthropic.refreshToken = state.refreshToken;
+        secrets.providers.anthropic.expiresAt = state.expiresAt;
+        fs.writeFileSync(secretsPath, JSON.stringify(secrets, null, 2) + "\n", "utf-8");
+        /* v8 ignore start -- defensive: persistence failure must not crash the provider @preserve */
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "engine",
+            event: "engine.anthropic_token_persist_error",
+            message: "failed to persist refreshed token",
+            meta: { error: error instanceof Error ? error.message : String(error) },
+        });
+    }
+    /* v8 ignore stop */
+}
+/**
+ * Ensure the Anthropic token is fresh. If expired, refresh and persist.
+ * Returns the current valid access token, or null if refresh failed and
+ * the existing token is expired.
+ */
+async function ensureFreshToken(currentToken, refreshToken, expiresAt, agentName, fetchImpl) {
+    if (!needsRefresh(expiresAt)) {
+        return currentToken; // still fresh
+    }
+    if (!refreshToken) {
+        // No refresh token — use the current token as-is (may be expired)
+        return currentToken;
+    }
+    const newState = await refreshAnthropicToken(refreshToken, fetchImpl);
+    if (!newState) {
+        return currentToken; // refresh failed — try the old token
+    }
+    persistTokenState(agentName, newState);
+    return newState.accessToken;
+}
+/* v8 ignore stop */