@ouro.bot/cli 0.1.0-alpha.28 → 0.1.0-alpha.280

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

@@ -0,0 +1,7 @@
+"use strict";
+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.OUTLOOK_PRODUCT_NAME = "Ouro Outlook";
+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

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOutlookMachineView = buildOutlookMachineView;
+exports.buildOutlookAgentView = buildOutlookAgentView;
+const runtime_1 = require("../../nerves/runtime");
+const outlook_types_1 = require("./outlook-types");
+function deriveAttention(agent) {
+    if (agent.degraded.status === "degraded") {
+        return { level: "degraded", label: "Degraded" };
+    }
+    if (agent.freshness.status === "stale") {
+        return { level: "stale", label: "Stale" };
+    }
+    if (agent.tasks.blockedCount > 0 || agent.coding.blockedCount > 0) {
+        return { level: "blocked", label: "Blocked" };
+    }
+    if (agent.tasks.liveCount > 0 || agent.coding.activeCount > 0 || agent.obligations.openCount > 0) {
+        return { level: "active", label: "Active" };
+    }
+    return { level: "idle", label: "Idle" };
+}
+function deriveAgentAttention(agent) {
+    return deriveAttention({
+        agentName: agent.agentName,
+        enabled: agent.enabled,
+        freshness: agent.freshness,
+        degraded: agent.degraded,
+        tasks: {
+            liveCount: agent.tasks.liveCount,
+            blockedCount: agent.tasks.blockedCount,
+        },
+        obligations: {
+            openCount: agent.obligations.openCount,
+        },
+        coding: {
+            activeCount: agent.coding.activeCount,
+            blockedCount: agent.coding.blockedCount,
+        },
+    });
+}
+function buildTotals(machine) {
+    return machine.agents.reduce((totals, agent) => ({
+        agents: totals.agents + 1,
+        enabledAgents: totals.enabledAgents + (agent.enabled ? 1 : 0),
+        degradedAgents: totals.degradedAgents + (agent.degraded.status === "degraded" ? 1 : 0),
+        staleAgents: totals.staleAgents + (agent.freshness.status === "stale" ? 1 : 0),
+        liveTasks: totals.liveTasks + agent.tasks.liveCount,
+        blockedTasks: totals.blockedTasks + agent.tasks.blockedCount,
+        openObligations: totals.openObligations + agent.obligations.openCount,
+        activeCodingAgents: totals.activeCodingAgents + (agent.coding.activeCount > 0 ? 1 : 0),
+        blockedCodingAgents: totals.blockedCodingAgents + (agent.coding.blockedCount > 0 ? 1 : 0),
+    }), {
+        agents: 0,
+        enabledAgents: 0,
+        degradedAgents: 0,
+        staleAgents: 0,
+        liveTasks: 0,
+        blockedTasks: 0,
+        openObligations: 0,
+        activeCodingAgents: 0,
+        blockedCodingAgents: 0,
+    });
+}
+function deriveMood(machine, daemon) {
+    if (machine.degraded.status === "degraded" || daemon.health === "warn") {
+        return "strained";
+    }
+    if (machine.freshness.status === "stale") {
+        return "watchful";
+    }
+    return "calm";
+}
+function buildOutlookMachineView(input) {
+    const totals = buildTotals(input.machine);
+    const agents = input.machine.agents
+        .map((agent) => ({
+        ...agent,
+        attention: deriveAttention(agent),
+    }))
+        .sort((left, right) => {
+        const leftAt = left.freshness.latestActivityAt ?? "";
+        const rightAt = right.freshness.latestActivityAt ?? "";
+        return rightAt.localeCompare(leftAt);
+    });
+    return {
+        overview: {
+            productName: outlook_types_1.OUTLOOK_PRODUCT_NAME,
+            observedAt: input.machine.observedAt,
+            primaryEntryPoint: input.daemon.outlookUrl,
+            daemon: input.daemon,
+            runtime: input.machine.runtime,
+            freshness: input.machine.freshness,
+            degraded: input.machine.degraded,
+            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" },
+            ],
+        },
+        agents,
+    };
+}
+function normalizeViewer(viewer) {
+    return {
+        kind: viewer?.kind ?? "human",
+        agentName: viewer?.agentName,
+        innerDetail: viewer?.innerDetail ?? "summary",
+    };
+}
+function buildInnerView(inner, viewer) {
+    if (viewer.innerDetail === "deep") {
+        return {
+            mode: "deep",
+            status: inner.status,
+            summary: inner.surfacedSummary,
+            hasPending: inner.hasPending,
+            origin: inner.origin,
+            obligationStatus: inner.obligationStatus,
+        };
+    }
+    return {
+        mode: "summary",
+        status: inner.status,
+        summary: inner.surfacedSummary,
+        hasPending: inner.hasPending,
+    };
+}
+function buildRecentActivity(agent) {
+    const items = [
+        ...agent.coding.items.map((item) => ({
+            kind: "coding",
+            at: item.lastActivityAt,
+            label: item.checkpoint ?? `${item.runner} ${item.status}`,
+            detail: item.workdir,
+        })),
+        ...agent.sessions.items.map((item) => ({
+            kind: "session",
+            at: item.lastActivityAt,
+            label: `${item.friendName} via ${item.channel}`,
+            detail: item.key,
+        })),
+        ...agent.obligations.items.map((item) => ({
+            kind: "obligation",
+            at: item.updatedAt,
+            label: item.content,
+            detail: item.nextAction ?? item.status,
+        })),
+    ];
+    if (agent.inner.latestActivityAt) {
+        items.push({
+            kind: "inner",
+            at: agent.inner.latestActivityAt,
+            label: agent.inner.surfacedSummary ?? agent.inner.status,
+            detail: agent.inner.hasPending ? "pending inner work" : agent.inner.obligationStatus ?? "no linked obligation",
+        });
+    }
+    return items
+        .filter((item) => Number.isFinite(Date.parse(item.at)))
+        .sort((left, right) => right.at.localeCompare(left.at))
+        .slice(0, 4);
+}
+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 } });
+    const viewer = normalizeViewer(input.viewer);
+    return {
+        productName: outlook_types_1.OUTLOOK_PRODUCT_NAME,
+        interactionModel: outlook_types_1.OUTLOOK_RELEASE_INTERACTION_MODEL,
+        viewer,
+        agent: {
+            agentName: input.agent.agentName,
+            agentRoot: input.agent.agentRoot,
+            enabled: input.agent.enabled,
+            provider: input.agent.provider,
+            senses: input.agent.senses,
+            freshness: input.agent.freshness,
+            degraded: input.agent.degraded,
+            attention: deriveAgentAttention(input.agent),
+        },
+        work: {
+            tasks: input.agent.tasks,
+            obligations: input.agent.obligations,
+            sessions: input.agent.sessions,
+            coding: input.agent.coding,
+            bridges: input.agent.tasks.activeBridges,
+        },
+        inner: buildInnerView(input.agent.inner, viewer),
+        activity: {
+            freshness: input.agent.freshness,
+            recent: buildRecentActivity(input.agent),
+        },
+    };
+}

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,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeErrorMessage = sanitizeErrorMessage;
+exports.pingProvider = pingProvider;
+exports.runHealthInventory = runHealthInventory;
+const identity_1 = require("./identity");
+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("./auth/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) {
+    const record = config;
+    return identity_1.PROVIDER_CREDENTIALS[provider].required.some((key) => !record[key]);
+}
+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 */