@ouro.bot/cli 0.1.0-alpha.954 → 0.1.0-alpha.956

package/dist/heart/auth/auth-flow.js

@@ -361,6 +361,16 @@ async function collectRuntimeAuthCredentials(input, deps) {
         }
         return credentials;
     }
+    if (input.provider === "anthropic" && input.apiKey) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.auth_anthropic_api_key",
+            message: "storing anthropic API key for runtime auth",
+            meta: { agentName: input.agentName, hasBaseUrl: !!input.baseUrl },
+        });
+        writeAuthProgress(input, "using the supplied anthropic API key...");
+        return { apiKey: input.apiKey.trim(), ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}) };
+    }
     if (input.provider === "anthropic") {
         (0, runtime_1.emitNervesEvent)({
             component: "daemon",
@@ -414,12 +424,16 @@ async function collectRuntimeAuthCredentials(input, deps) {
     }
     return creds;
 }
+/** True when the record holds `required` or one of the provider's alternative field sets in full. */
+function hasRequiredProviderCredentials(provider, record) {
+    const requirements = identity_1.PROVIDER_CREDENTIALS[provider];
+    return [requirements.required, ...(requirements.alternativeRequired ?? [])].some((fields) => fields.every((key) => !!record[key]));
+}
 async function resolveHatchCredentials(input) {
     const credentials = { ...(input.credentials ?? {}) };
     // If all required fields are already provided, return as-is
     const cred = credentials;
-    const missing = identity_1.PROVIDER_CREDENTIALS[input.provider].required.some((key) => !cred[key]);
-    if (!missing)
+    if (hasRequiredProviderCredentials(input.provider, cred))
         return credentials;
     // Try the full auth flow (wraps collectRuntimeAuthCredentials + writes secrets)
     if (input.runAuthFlow) {
@@ -431,7 +445,7 @@ async function resolveHatchCredentials(input) {
         });
         Object.assign(credentials, result.credentials);
         /* v8 ignore next 3 -- branch: auth flow always fills all required fields in production @preserve */
-        if (!identity_1.PROVIDER_CREDENTIALS[input.provider].required.some((key) => !credentials[key])) {
+        if (hasRequiredProviderCredentials(input.provider, credentials)) {
             return credentials;
         }
     }

package/dist/heart/config.js

@@ -235,7 +235,11 @@ function getMinimaxConfig() {
 }
 function getAnthropicConfig() {
     const raw = readProviderConfig("anthropic");
-    return { setupToken: typeof raw.setupToken === "string" ? raw.setupToken : "" };
+    return {
+        setupToken: typeof raw.setupToken === "string" ? raw.setupToken : "",
+        ...(typeof raw.apiKey === "string" && raw.apiKey ? { apiKey: raw.apiKey } : {}),
+        ...(typeof raw.baseUrl === "string" && raw.baseUrl ? { baseUrl: raw.baseUrl } : {}),
+    };
 }
 function getOpenAICodexConfig() {
     const raw = readProviderConfig("openai-codex");

package/dist/heart/daemon/cli-exec.js

@@ -5648,8 +5648,24 @@ async function executeProviderRefresh(command, deps) {
     deps.writeStdout(message);
     return message;
 }
+/** Reads an API key from a file (or /dev/stdin) so it never appears in argv. */
+function readApiKeyFile(filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        /* v8 ignore next -- fs.readFileSync only throws Error objects @preserve */
+        throw new Error(`could not read --api-key-file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const key = raw.trim();
+    if (!key)
+        throw new Error(`--api-key-file ${filePath} is empty.`);
+    return key;
+}
 async function executeAuthRun(command, deps) {
     const provider = command.provider ?? (0, auth_flow_1.readAgentConfigForAgent)(command.agent, deps.bundlesRoot).config.humanFacing.provider;
+    const apiKey = command.apiKeyFile ? readApiKeyFile(command.apiKeyFile) : undefined;
     /* v8 ignore next -- tests always inject runAuthFlow; default is for production @preserve */
     const authRunner = deps.runAuthFlow ?? (await Promise.resolve().then(() => __importStar(require("../auth/auth-flow")))).runRuntimeAuthFlow;
     const progress = createHumanCommandProgress(deps, "auth");
@@ -5662,6 +5678,8 @@ async function executeAuthRun(command, deps) {
             promptInput: deps.promptInput,
             promptSecret: deps.promptSecret,
             onProgress: (message) => progress.updateDetail(message),
+            ...(apiKey ? { apiKey } : {}),
+            ...(command.baseUrl ? { baseUrl: command.baseUrl } : {}),
         });
     }
     catch (error) {
@@ -8231,6 +8249,13 @@ async function runOuroCli(args, deps = (0, cli_defaults_1.createDefaultOuroCliDe
     if (command.kind === "a2a.card" || command.kind === "a2a.onboard" || command.kind === "a2a.serve" || command.kind === "a2a.escalation" || command.kind === "a2a.delegatedCommands") {
         return executeA2ACommand(command, deps);
     }
+    if (command.kind === "gateway.serve") {
+        const { runCreditGatewayCommand } = await Promise.resolve().then(() => __importStar(require("../../gateway/server")));
+        return runCreditGatewayCommand(command, {
+            writeStdout: deps.writeStdout,
+            ...(deps.waitForShutdownSignal ? { waitForStop: deps.waitForShutdownSignal } : {}),
+        });
+    }
     // ── provider commands (local, no daemon socket needed) ──
     if (command.kind === "provider.use") {
         return executeProviderUse(command, deps);

package/dist/heart/daemon/cli-help.js

@@ -259,8 +259,8 @@ exports.COMMAND_REGISTRY = {
     },
     auth: {
         category: "Auth",
-        description: "Set up or verify agent credentials",
-        usage: "ouro auth [verify] [--agent <name>] [--provider <provider>]",
+        description: "Set up or verify agent credentials. For Anthropic API-key mode (for example through a credit gateway), pass --api-key-file <path> (use /dev/stdin to pipe it) and optionally --base-url <url>; the key is never taken from the command line.",
+        usage: "ouro auth [verify] [--agent <name>] [--provider <provider>] [--api-key-file <path> [--base-url <url>]]",
         example: "ouro auth",
         subcommands: ["verify"],
     },
@@ -358,6 +358,13 @@ exports.COMMAND_REGISTRY = {
         example: "ouro session list",
         subcommands: ["list"],
     },
+    gateway: {
+        category: "System",
+        description: "Run the credit gateway: one master key for agents, upstream Anthropic API keys spent in a fixed order",
+        usage: "ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>]",
+        example: "ouro gateway serve --keys-dir /mnt/user/appdata/credit-gateway/keys",
+        subcommands: ["serve"],
+    },
     mcp: {
         category: "System",
         description: "Interact with MCP servers",
@@ -497,6 +504,11 @@ const SUBCOMMAND_HELP = {
         usage: "ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         example: "ouro a2a onboard --agent <agent> --card-url https://peer.example/.well-known/agent-card.json --trust friend",
     },
+    "gateway serve": {
+        description: "Run the credit gateway in the foreground. It accepts the master key from <keys-dir>/master.key and forwards each request to the Anthropic API with the first upstream *.key (by file name) whose credits are not exhausted; a key whose credit balance is too low is skipped for the cooldown (default 60 minutes). GET /health needs no key.",
+        usage: "ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]",
+        example: "ouro gateway serve --keys-dir /mnt/user/appdata/credit-gateway/keys --port 8787",
+    },
     "a2a serve": {
         description: "Run this agent's local A2A JSON-RPC sense server",
         usage: "ouro a2a serve [--agent <name>] [--host <host>] [--port <port>] [--base-url <url>] [--path <path>]",

package/dist/heart/daemon/cli-parse.js

@@ -254,6 +254,7 @@ function usage() {
         "  ouro mailbox [--json]",
         "  ouro -v|--version",
         "  ouro auth [--agent <name>] [--provider <provider>]",
+        "  ouro auth --agent <name> --provider anthropic --api-key-file <path> [--base-url <url>]",
         "  ouro account ensure [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro connect [providers|perplexity|embeddings|teams|bluebubbles|mail|voice|a2a|telegram|workbench] [--agent <name>] [--owner-email <email> --source <label>|--no-delegated-source] [--rotate-missing-mail-keys]",
         "  ouro mail import-mbox --file <path> [--owner-email <email>] [--source <label>] [--agent <name>] [--foreground]",
@@ -303,6 +304,7 @@ function usage() {
         "  ouro a2a card [--agent <name>] [--base-url <url>] [--json]",
         "  ouro a2a onboard [--agent <name>] (--card-url <url>|--did <did:key> --name <name>) [--trust <level>] [--name <name>]",
         "  ouro a2a serve [--agent <name>] [--host <host>] [--port <port>] [--base-url <url>] [--path <path>]",
+        "  ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]",
         "  ouro a2a identity [--identity-file <path>] [--json]",
         "  ouro a2a message --to <card-url> --text <text> [--context <id>] [--delegated] [--identity-file <path>] [--json]",
         "  ouro a2a outbox list --to <card-url> [--since <cursor>] [--identity-file <path>] [--json]",
@@ -834,6 +836,8 @@ function parseAuthCommand(args) {
     }
     const { agent, rest } = extractAgentFlag(args);
     let provider;
+    let apiKeyFile;
+    let baseUrl;
     for (let i = 0; i < rest.length; i += 1) {
         if (rest[i] === "--provider") {
             const value = rest[i + 1];
@@ -843,11 +847,33 @@ function parseAuthCommand(args) {
             i += 1;
             continue;
         }
+        // The API key itself is read from a file (or /dev/stdin), never from argv, so it stays out of
+        // shell history and process listings.
+        if (rest[i] === "--api-key-file" || rest[i] === "--base-url") {
+            const value = rest[i + 1];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${rest[i]} requires a value.`);
+            if (rest[i] === "--api-key-file")
+                apiKeyFile = value;
+            else
+                baseUrl = value;
+            i += 1;
+            continue;
+        }
+    }
+    if ((apiKeyFile || baseUrl) && provider !== "anthropic") {
+        throw new Error("--api-key-file and --base-url are only for --provider anthropic (API-key mode).");
     }
+    if (baseUrl && !apiKeyFile)
+        throw new Error("--base-url requires --api-key-file.");
+    if (baseUrl && !/^https?:\/\//.test(baseUrl))
+        throw new Error("--base-url must be an http(s) URL.");
     return {
         kind: "auth.run",
         ...(agent ? { agent } : {}),
         ...(provider ? { provider } : {}),
+        ...(apiKeyFile ? { apiKeyFile } : {}),
+        ...(baseUrl ? { baseUrl } : {}),
     };
 }
 function isVaultUnlockStoreKind(value) {
@@ -1936,6 +1962,61 @@ function parseA2ACommand(args) {
     }
     throw new Error("Usage: ouro a2a card|onboard|serve|message|identity|outbox|escalation|delegated-commands ...");
 }
+const GATEWAY_SERVE_USAGE = "Usage: ouro gateway serve --keys-dir <dir> [--host <host>] [--port <port>] [--state <path>] [--upstream <url>] [--cooldown-minutes <n>]";
+function parseGatewayCommand(args) {
+    const [sub, ...rest] = args;
+    if (sub !== "serve")
+        throw new Error(GATEWAY_SERVE_USAGE);
+    let keysDir;
+    let host;
+    let port;
+    let statePath;
+    let upstream;
+    let cooldownMinutes;
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        const value = rest[i + 1];
+        if (!value || value.startsWith("--"))
+            throw new Error(GATEWAY_SERVE_USAGE);
+        i += 1;
+        if (flag === "--keys-dir")
+            keysDir = value;
+        else if (flag === "--host")
+            host = value;
+        else if (flag === "--state")
+            statePath = value;
+        else if (flag === "--upstream") {
+            if (!/^https?:\/\//.test(value))
+                throw new Error("--upstream must be an http(s) URL");
+            upstream = value;
+        }
+        else if (flag === "--port") {
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535)
+                throw new Error("Gateway port must be 0-65535");
+            port = parsed;
+        }
+        else if (flag === "--cooldown-minutes") {
+            const parsed = Number(value);
+            if (!Number.isFinite(parsed) || parsed <= 0)
+                throw new Error("--cooldown-minutes must be a positive number");
+            cooldownMinutes = parsed;
+        }
+        else
+            throw new Error(GATEWAY_SERVE_USAGE);
+    }
+    if (!keysDir)
+        throw new Error(GATEWAY_SERVE_USAGE);
+    return {
+        kind: "gateway.serve",
+        keysDir,
+        ...(host ? { host } : {}),
+        ...(port !== undefined ? { port } : {}),
+        ...(statePath ? { statePath } : {}),
+        ...(upstream ? { upstream } : {}),
+        ...(cooldownMinutes !== undefined ? { cooldownMinutes } : {}),
+    };
+}
 function parseConfigCommand(args) {
     const { agent, rest: afterAgent } = extractAgentFlag(args);
     const { facing, rest: cleaned } = extractFacingFlag(afterAgent);
@@ -3118,6 +3199,8 @@ function parseOuroCommand(args) {
         return parseFriendCommand(args.slice(1));
     if (head === "a2a")
         return parseA2ACommand(args.slice(1));
+    if (head === "gateway")
+        return parseGatewayCommand(args.slice(1));
     if (head === "config")
         return parseConfigCommand(args.slice(1));
     if (head === "mcp")

package/dist/heart/identity.js

@@ -69,7 +69,7 @@ var autonomy_budget_2 = require("./autonomy-budget");
 Object.defineProperty(exports, "normalizeHabitPaidTurnsPerDay", { enumerable: true, get: function () { return autonomy_budget_2.normalizeHabitPaidTurnsPerDay; } });
 /** Single source of truth for per-provider credential field names, env var mappings, and prompt labels. */
 exports.PROVIDER_CREDENTIALS = {
-    anthropic: { required: ["setupToken"], envVars: { ANTHROPIC_API_KEY: "setupToken" }, promptLabels: { setupToken: "Anthropic setup-token" } },
+    anthropic: { required: ["setupToken"], alternativeRequired: [["apiKey"]], envVars: { ANTHROPIC_API_KEY: "setupToken" }, promptLabels: { setupToken: "Anthropic setup-token" } },
     "openai-codex": { required: ["oauthAccessToken"], envVars: { OPENAI_API_KEY: "oauthAccessToken" }, promptLabels: { oauthAccessToken: "OpenAI Codex OAuth token" } },
     azure: { required: ["apiKey", "endpoint", "deployment"], envVars: { AZURE_OPENAI_API_KEY: "apiKey", AZURE_OPENAI_KEY: "apiKey", AZURE_OPENAI_ENDPOINT: "endpoint", AZURE_OPENAI_DEPLOYMENT: "deployment" }, promptLabels: { apiKey: "Azure API key", endpoint: "Azure endpoint", deployment: "Azure deployment" } },
     minimax: { required: ["apiKey"], envVars: { MINIMAX_API_KEY: "apiKey" }, promptLabels: { apiKey: "MiniMax API key" } },

package/dist/heart/provider-credentials.js

@@ -59,8 +59,8 @@ const VAULT_ITEM_PREFIX = "providers/";
 exports.PROVIDER_CREDENTIAL_POOL_NOT_LOADED_ERROR = "provider credentials have not been loaded from vault";
 const PROVIDER_FIELD_SPLITS = {
     anthropic: {
-        credentials: ["setupToken", "refreshToken", "expiresAt"],
-        config: [],
+        credentials: ["setupToken", "refreshToken", "expiresAt", "apiKey"],
+        config: ["baseUrl"],
     },
     "openai-codex": {
         credentials: ["oauthAccessToken", "refreshToken", "expiresAt"],

package/dist/heart/provider-ping.js

@@ -157,7 +157,8 @@ function hasEmptyCredentials(provider, config) {
         if (hasManagedIdentity)
             return false;
     }
-    return identity_1.PROVIDER_CREDENTIALS[provider].required.some((key) => !record[key]);
+    const requirements = identity_1.PROVIDER_CREDENTIALS[provider];
+    return ![requirements.required, ...(requirements.alternativeRequired ?? [])].some((fields) => fields.every((key) => !!record[key]));
 }
 function createProviderRuntimeForConfig(provider, config, options = {}) {
     // Use the same provider defaults as auth switch and hatch so verification

package/dist/heart/providers/anthropic.js

@@ -225,7 +225,16 @@ function mergeAnthropicToolArguments(current, partial) {
     }
     return current + partial;
 }
+// An org whose prepaid API credits are used up gets HTTP 400 (or 402) with this phrase. That is a
+// usage limit, not a malformed request, so failover tells the human the right thing.
+const ANTHROPIC_CREDIT_LOW_PHRASE = "credit balance is too low";
+function isAnthropicCreditExhausted(error) {
+    const status = error.status;
+    return (status === 400 || status === 402) && error.message.toLowerCase().includes(ANTHROPIC_CREDIT_LOW_PHRASE);
+}
 function classifyAnthropicError(error) {
+    if (isAnthropicCreditExhausted(error))
+        return "usage-limit";
     return (0, error_classification_1.classifyHttpError)(error, {
         isAuthFailure: isAnthropicAuthFailure,
         isServerError: (e) => e.status === 529,
@@ -236,9 +245,10 @@ function isAnthropicAuthFailure(error) {
     return (lower.includes("oauth authentication") ||
         lower.includes("authentication failed") ||
         lower.includes("unauthorized") ||
-        lower.includes("invalid api key"));
+        lower.includes("invalid api key") ||
+        lower.includes("invalid x-api-key"));
 }
-async function streamAnthropicMessages(client, model, request) {
+async function streamAnthropicMessages(client, model, request, options = { claudeCodePreamble: true }) {
     const { system, messages } = toAnthropicMessages(request.messages);
     const additionalSystemParts = request.messages
         .filter((message) => message.role === "system")
@@ -260,13 +270,14 @@ async function streamAnthropicMessages(client, model, request) {
     // prompt when using OAuth setup tokens (sk-ant-oat01). Without it, Opus/Sonnet
     // 4.6 requests are rejected with 400. This is the API's validation that the
     // token is being used by a Claude Code client.
-    const preambleText = "You are Claude Code, Anthropic's official CLI for Claude.";
+    // API-key mode (a plain API key, for example through a credit gateway) needs no such block.
+    const preambleText = options.claudeCodePreamble ? "You are Claude Code, Anthropic's official CLI for Claude." : "";
     if (request.systemPrompt) {
         // Structured SystemPrompt: merge preamble + stable prefix into one cached block,
         // volatile suffix as a separate uncached block.
         const stableBlock = {
             type: "text",
-            text: preambleText + "\n\n" + request.systemPrompt.stable,
+            text: preambleText ? preambleText + "\n\n" + request.systemPrompt.stable : request.systemPrompt.stable,
             cache_control: { type: "ephemeral" },
         };
         params.system = [
@@ -279,9 +290,11 @@ async function streamAnthropicMessages(client, model, request) {
     }
     else if (system) {
         // Fallback: no structured prompt, extract from messages (legacy path)
-        params.system = [{ type: "text", text: preambleText }, { type: "text", text: system }];
+        params.system = preambleText
+            ? [{ type: "text", text: preambleText }, { type: "text", text: system }]
+            : [{ type: "text", text: system }];
     }
-    else {
+    else if (preambleText) {
         params.system = [{ type: "text", text: preambleText }];
     }
     if (anthropicTools.length > 0)
@@ -441,6 +454,48 @@ async function streamAnthropicMessages(client, model, request) {
         ...(settleFinalization ? { settleFinalization } : {}),
     };
 }
+const ANTHROPIC_PING_MODEL = "claude-haiku-4-5-20251001";
+/**
+ * API-key mode: a plain Anthropic API key, optionally against another base URL such as a credit
+ * gateway. No Claude Code identity headers, no Claude Code system preamble and no token refresh;
+ * prompt caching, thinking, tools and streaming work as in setup-token mode.
+ */
+function createAnthropicApiKeyRuntime(model, apiKey, baseUrl) {
+    const modelCaps = (0, model_capabilities_1.getModelCapabilities)(model);
+    const capabilities = new Set();
+    if (modelCaps.reasoningEffort)
+        capabilities.add("reasoning-effort");
+    // authToken: null keeps the SDK from also sending an ANTHROPIC_AUTH_TOKEN from the environment.
+    const client = new sdk_1.default({ apiKey, authToken: null, baseURL: baseUrl, maxRetries: 0 });
+    (0, runtime_1.emitNervesEvent)({
+        component: "engine",
+        event: "engine.anthropic_api_key_mode",
+        message: "anthropic provider using API-key mode",
+        meta: { provider: "anthropic", customBaseUrl: baseUrl !== undefined },
+    });
+    return {
+        id: "anthropic",
+        model,
+        client,
+        capabilities,
+        supportedReasoningEfforts: modelCaps.reasoningEffort,
+        resetTurnState(_messages) {
+            // Anthropic request payload is derived from canonical messages each turn.
+        },
+        appendToolOutput(_callId, _output) {
+            // Anthropic uses canonical messages for tool_result tracking.
+        },
+        streamTurn(request) {
+            return streamAnthropicMessages(client, model, request, { claudeCodePreamble: false });
+        },
+        async ping(signal) {
+            await client.messages.create({ model: ANTHROPIC_PING_MODEL, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal });
+        },
+        classifyError(error) {
+            return classifyAnthropicError(error);
+        },
+    };
+}
 function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.getAnthropicConfig)()) {
     (0, runtime_1.emitNervesEvent)({
         component: "engine",
@@ -448,6 +503,9 @@ function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.ge
         message: "anthropic provider init",
         meta: { provider: "anthropic" },
     });
+    const apiKey = anthropicConfig.apiKey?.trim();
+    if (apiKey)
+        return createAnthropicApiKeyRuntime(model, apiKey, anthropicConfig.baseUrl?.trim() || undefined);
     if (!anthropicConfig.setupToken) {
         throw new Error(getAnthropicReauthGuidance("provider 'anthropic' is selected but anthropic.setupToken is missing in the agent vault."));
     }
@@ -509,7 +567,7 @@ function createAnthropicProviderRuntime(model, anthropicConfig = (0, config_1.ge
         /* v8 ignore start -- ping: tested via provider-ping.test.ts @preserve */
         async ping(signal) {
             const freshClient = await ensureClient();
-            await freshClient.messages.create({ model: "claude-haiku-4-5-20251001", max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal, headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" } });
+            await freshClient.messages.create({ model: ANTHROPIC_PING_MODEL, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }, { signal, headers: { "anthropic-beta": "claude-code-20250219,oauth-2025-04-20" } });
         },
         /* v8 ignore stop */
         /* v8 ignore next 3 -- delegation: classification logic tested via classifyAnthropicError @preserve */

package/dist/heart/runtime-credentials.js

@@ -108,7 +108,8 @@ function isProviderCredentialRecord(value) {
     const provider = value.provider;
     const canonicalCredentials = (0, provider_credentials_1.splitProviderCredentialFields)(provider, credentials).credentials;
     const canonicalConfig = (0, provider_credentials_1.splitProviderCredentialFields)(provider, config).config;
-    if (!identity_1.PROVIDER_CREDENTIALS[provider].required.every((field) => (isPresentCredentialValue(canonicalCredentials[field]) || isPresentCredentialValue(canonicalConfig[field]))))
+    const requirements = identity_1.PROVIDER_CREDENTIALS[provider];
+    if (![requirements.required, ...(requirements.alternativeRequired ?? [])].some((fields) => fields.every((field) => (isPresentCredentialValue(canonicalCredentials[field]) || isPresentCredentialValue(canonicalConfig[field])))))
         return false;
     const provenance = value.provenance;
     if (!isRecord(provenance))

package/dist/senses/bluebubbles/index.js

@@ -106,6 +106,11 @@ const BLUEBUBBLES_VISIBLE_OUTBOUND_STATUSES = new Set([
     "local-visible",
     "delivered",
 ]);
+// A reply whose final send keeps failing stays pending for recovery this many
+// times, then gets a terminal receipt so one message cannot drain the budget.
+const BLUEBUBBLES_REPLY_DELIVERY_MAX_ATTEMPTS = 3;
+// A timed-out send may still land, so wait before checking the chat and retrying.
+const BLUEBUBBLES_REPLY_RETRY_DELAY_MS = 10 * 60_000;
 exports.BLUEBUBBLES_SEMANTIC_GENERATION_RETENTION_MS = 15 * 60_000;
 function pruneBlueBubblesSemanticObservationGenerations(nowMs = Date.now()) {
     let pruned = 0;
@@ -1622,8 +1627,12 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                 const turnStage = createBlueBubblesTurnStage(event.chat.sessionKey);
                 let finalTransportInvoked = false;
                 let finalTransportAccepted = false;
+                let spokeBeforeFinalTransport = false;
                 const outboundRuntimeConfig = (0, config_1.getBlueBubblesConfig)();
-                const callbacks = createBlueBubblesCallbacks(client, event.chat, replyTarget, event.chat.isGroup, () => (0, active_turns_1.noteBlueBubblesActiveTurnVisibleActivity)(agentName, liveTurnId), {
+                const callbacks = createBlueBubblesCallbacks(client, event.chat, replyTarget, event.chat.isGroup, () => {
+                    spokeBeforeFinalTransport = true;
+                    (0, active_turns_1.noteBlueBubblesActiveTurnVisibleActivity)(agentName, liveTurnId);
+                }, {
                     admitOutbound: async () => (!options.lifecycleSignal?.aborted
                         && await (0, latest_turn_1.awaitDeliveryAdmission)(options.latestTurnCapability)
                         && !options.lifecycleSignal?.aborted),
@@ -1976,6 +1985,18 @@ async function handleBlueBubblesNormalizedEvent(event, resolvedDeps, source, opt
                                     reason: error instanceof Error ? error.message : String(error),
                                 },
                             });
+                            if (spokeBeforeFinalTransport) {
+                                // The friend already saw part of this turn; a retry would repeat it.
+                                const failed = (0, outbound_state_1.readBlueBubblesOutboundRecordByIdempotencyKey)((0, identity_1.getAgentRoot)(), blueBubblesInboundReplyIdempotencyKey(options.currentIngressEvidence.captureKeyHash));
+                                if (failed) {
+                                    (0, outbound_state_1.markBlueBubblesOutboundPendingManualVerification)({
+                                        agentRoot: (0, identity_1.getAgentRoot)(),
+                                        recordId: failed.recordId,
+                                        decidedAt: new Date().toISOString(),
+                                        reason: "mid-turn speech was visible before the final send failed",
+                                    });
+                                }
+                            }
                             return {
                                 handled: true,
                                 notifiedAgent: false,
@@ -2406,6 +2427,18 @@ function writeCapturedBlueBubblesHandled(agentName, capture, outcome, detailCode
 function blueBubblesInboundReplyIdempotencyKey(captureKeyHash) {
     return `bluebubbles-inbound-reply:${captureKeyHash}`;
 }
+async function blueBubblesFailedReplyIsVisible(deps, chat, record) {
+    const since = Date.parse(record.createdAt);
+    const recent = await deps.createClient().listRecentMessages?.({
+        chatGuid: chat.chatGuid,
+        limit: 25,
+    }) ?? [];
+    return recent.some((message) => (message.kind === "message"
+        && message.fromMe
+        && message.timestamp >= since
+        && message.chat.chatGuid === chat.chatGuid
+        && (0, outbound_state_1.blueBubblesOutboundTextMatches)(record, message.text)));
+}
 function blueBubblesRecoveredOutboundOutcome(record) {
     return BLUEBUBBLES_VISIBLE_OUTBOUND_STATUSES.has(record.status)
         ? "message_completed"
@@ -2520,7 +2553,13 @@ async function handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, so
             return result;
         }
         const durableOutbound = (0, outbound_state_1.readBlueBubblesOutboundRecordByIdempotencyKey)((0, identity_1.getAgentRoot)(), blueBubblesInboundReplyIdempotencyKey(captured.capture.keyHash));
-        if (durableOutbound) {
+        const retryFailedReply = durableOutbound?.status === "failed"
+            && (durableOutbound.failedAttempts ?? 0) < BLUEBUBBLES_REPLY_DELIVERY_MAX_ATTEMPTS;
+        if (retryFailedReply
+            && Date.now() < Date.parse(durableOutbound.failedAt ?? durableOutbound.updatedAt) + BLUEBUBBLES_REPLY_RETRY_DELAY_MS) {
+            return { handled: true, notifiedAgent: false, kind: captured.normalized.kind, reason: "delivery_failed" };
+        }
+        if (durableOutbound && !retryFailedReply) {
             const outcome = blueBubblesRecoveredOutboundOutcome(durableOutbound);
             (0, runtime_1.emitNervesEvent)({
                 level: "warn",
@@ -2627,11 +2666,74 @@ async function handleCapturedBlueBubblesSemanticEvent(captured, resolvedDeps, so
                 orientationConversationKind: canonicalEvent.chat.isGroup ? "group" : "one_to_one",
                 publishAcceptedReceipt,
             };
+            let failedReplyVisible = false;
+            if (retryFailedReply) {
+                try {
+                    failedReplyVisible = await blueBubblesFailedReplyIsVisible(resolvedDeps, canonicalEvent.chat, durableOutbound);
+                }
+                catch (error) {
+                    // Without the chat history a retry could reply twice; try again later.
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "warn",
+                        component: "senses",
+                        event: "senses.bluebubbles_reply_retry_deferred",
+                        message: "deferred a bluebubbles reply retry because recent chat messages could not be read",
+                        meta: {
+                            messageGuid: captured.normalized.messageGuid,
+                            reason: error instanceof Error ? error.message : String(error),
+                        },
+                    });
+                    return { handled: true, notifiedAgent: false, kind: captured.normalized.kind, reason: "delivery_failed" };
+                }
+            }
+            if (failedReplyVisible) {
+                // The send that timed out reached the chat after all; do not reply twice.
+                (0, runtime_1.emitNervesEvent)({
+                    level: "warn",
+                    component: "senses",
+                    event: "senses.bluebubbles_inbound_reply_recovery_suppressed",
+                    message: "suppressed bluebubbles reply retry because a reply is already in the chat",
+                    meta: { messageGuid: captured.normalized.messageGuid, recordId: durableOutbound.recordId },
+                });
+                publishTerminalReceipt("message_completed", "reply_visible_after_failed_send");
+                semanticHandlingCompleted = true;
+                return { handled: true, notifiedAgent: false, kind: captured.normalized.kind, reason: "already_processed" };
+            }
             result = await handleBlueBubblesNormalizedEvent(canonicalEvent, resolvedDeps, source, capturedOptions);
             // A budget or storm-breaker block defers the message; it was never seen.
             // Leave it pending so a later recovery pass retries it once the block lifts.
             if (result.reason === "autonomy_budget_blocked")
                 return result;
+            if (result.reason === "delivery_failed") {
+                // The reply never reached the chat. Leave the message pending so a later
+                // recovery pass sends it, until the per-message attempt cap is reached.
+                let failed = (0, outbound_state_1.readBlueBubblesOutboundRecordByIdempotencyKey)((0, identity_1.getAgentRoot)(), blueBubblesInboundReplyIdempotencyKey(captured.capture.keyHash));
+                if (failed?.status === "failed") {
+                    if (retryFailedReply && failed.failedAttempts === durableOutbound.failedAttempts) {
+                        // The retry failed before it reached the transport; count it anyway.
+                        failed = (0, outbound_state_1.markBlueBubblesOutboundFailed)({
+                            agentRoot: (0, identity_1.getAgentRoot)(),
+                            recordId: failed.recordId,
+                            failedAt: new Date().toISOString(),
+                            reason: "retry failed before the final transport",
+                        });
+                    }
+                    /* v8 ignore next -- a failed record re-read after a send always carries its count @preserve */
+                    const failedAttempts = failed.failedAttempts ?? 0;
+                    if (failedAttempts < BLUEBUBBLES_REPLY_DELIVERY_MAX_ATTEMPTS)
+                        return result;
+                    (0, runtime_1.emitNervesEvent)({
+                        level: "error",
+                        component: "senses",
+                        event: "senses.bluebubbles_reply_delivery_abandoned",
+                        message: "gave up sending a bluebubbles reply after repeated transport failures",
+                        meta: { messageGuid: captured.normalized.messageGuid, failedAttempts },
+                    });
+                    publishTerminalReceipt("message_observed", "reply_delivery_retries_exhausted");
+                    semanticHandlingCompleted = true;
+                    return result;
+                }
+            }
             handledOutcome = result.notifiedAgent ? "message_completed" : "message_observed";
         }
         if (result.notifiedAgent) {