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

package/changelog.json

@@ -1,6 +1,14 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.956",
+      "changes": [
+        "A new credit gateway (ouro gateway serve) lets agents use one master key while it spends several Anthropic API keys in a fixed order, moving to the next key only when one runs out of credits, with a health page and a runbook for running it next to the Butler on Unraid.",
+        "The Anthropic provider can now use a plain API key and a custom base URL (ouro auth --provider anthropic --api-key-file <path> --base-url <url>, which reads the key from a file or standard input and never from the command line), so an agent can run on API credits through the credit gateway; the existing setup-token login works as before.",
+        "The credit gateway refuses any request path that would send a key to a host other than the Anthropic API."
+      ]
+    },
     {
       "version": "0.1.0-alpha.955",
       "changes": [

package/deploy/unraid/credit-gateway.md

@@ -0,0 +1,95 @@
+# Credit gateway runbook
+
+The credit gateway lets the Butler run on the API credits of several Claude Max plans through one key. Agents present a single master key; the gateway holds the real Anthropic API keys and spends them in a fixed order: it uses the first key until the API says that key's credit balance is too low, then the second, then the third. It never spreads load across keys.
+
+It runs from the same image as the Butler (no separate image), as a second container named `ouro-credit-gateway`. Both containers use host networking, so the gateway listens on `127.0.0.1:8787` and the Butler reaches it at `http://127.0.0.1:8787`. Nothing is published to the network.
+
+## How it behaves
+
+- `master.key` in the keys folder is the key clients must send, as `x-api-key` or `Authorization: Bearer`. A wrong or missing key gets HTTP 401 `invalid x-api-key`.
+- Every other `*.key` file is an upstream Anthropic API key. The gateway uses them in file-name order (`acct1.key`, `acct2.key`, `acct3.key`). The label in logs and health is the file name without `.key`. Key contents are never logged.
+- The gateway reads the keys once at start. Restart the container after changing a key file.
+- When the API answers HTTP 400, 402 or 403 with "credit balance is too low", the gateway skips that key for the cooldown (60 minutes by default), logs `gateway: <label> out of credits; moving on`, and retries the same request with the next key. After the cooldown it tries the key again, which is how a key comes back once its org's credits refresh. A rejected credit check is not billed.
+- The skip list is saved in `gateway-state.json` in the keys folder (mode 0600), so a restart remembers it. Delete that file to retry every key at once.
+- When every key is out of credits, clients get HTTP 400 with the API's last credit-balance error.
+- If the API cannot be reached, clients get HTTP 502 and the gateway does not move to the next key.
+- Every request logs one line: `gateway: <label> <method> <path> <status> <ms>ms`. Read them with `docker logs ouro-credit-gateway`.
+
+## One-time setup (as root on the Unraid host)
+
+1. Create the keys folder, owned by the image's user (UID/GID 10001) and closed to everyone else:
+
+   ```sh
+   install -d -o 10001 -g 10001 -m 0700 /mnt/user/appdata/credit-gateway /mnt/user/appdata/credit-gateway/keys
+   ```
+
+2. Put one upstream API key per account in the folder, one key per file, each file mode 0600. Copy the key files in rather than pasting keys on the command line, so they stay out of shell history:
+
+   ```sh
+   cd /mnt/user/appdata/credit-gateway/keys
+   install -o 10001 -g 10001 -m 0600 /path/to/acct1.key acct1.key
+   install -o 10001 -g 10001 -m 0600 /path/to/acct2.key acct2.key
+   install -o 10001 -g 10001 -m 0600 /path/to/acct3.key acct3.key
+   ```
+
+3. Generate the master key:
+
+   ```sh
+   cd /mnt/user/appdata/credit-gateway/keys
+   (umask 077; printf 'ouro-gw-%s\n' "$(openssl rand -hex 32)" > master.key)
+   chown 10001:10001 master.key
+   ```
+
+4. Check the result. Every file should be `-rw------- 10001 10001`:
+
+   ```sh
+   ls -ln /mnt/user/appdata/credit-gateway/keys
+   ```
+
+The folder must stay writable by UID 10001, because the gateway saves `gateway-state.json` there.
+
+## Run the gateway
+
+Use the same image tag the Butler runs (the `<Repository>` in `sanctuary.xml`). The image's entrypoint starts the agent daemon, so override it with `--entrypoint node`. The image's built-in health check probes the agent, so replace it with a check of the gateway's own health URL:
+
+```sh
+docker run -d --name ouro-credit-gateway \
+  --network host \
+  --restart unless-stopped \
+  --entrypoint node \
+  -v /mnt/user/appdata/credit-gateway/keys:/keys \
+  --health-cmd 'curl -fsS http://127.0.0.1:8787/health || exit 1' \
+  --health-interval 30s --health-timeout 5s --health-retries 3 \
+  ghcr.io/ourostack/ouroboros-butler:<same tag as ouro-butler> \
+  /opt/ouro/dist/heart/daemon/ouro-entry.js gateway serve --keys-dir /keys --host 127.0.0.1 --port 8787
+```
+
+Port 8787 is also the default port of Readarr and its forks (such as Bookshelf). If `ss -ltn | grep 8787` shows it in use, pick a free port (for example 8788) and use it in `--port`, the health check and the Butler's `--base-url`.
+
+Optional flags after `gateway serve`: `--cooldown-minutes <n>` (default 60), `--state <path>` (default `<keys-dir>/gateway-state.json`), `--upstream <url>` (default `https://api.anthropic.com`).
+
+## Check it
+
+```sh
+docker inspect --format '{{.State.Status}} {{.State.Health.Status}}' ouro-credit-gateway
+curl -fsS http://127.0.0.1:8787/health
+docker logs --tail 20 ouro-credit-gateway
+```
+
+`/health` needs no key and returns, for example, `{"ok":true,"keys":[{"label":"acct1","available":true},{"label":"acct2","available":false,"skipUntil":"2026-11-01T10:00:00.000Z"},{"label":"acct3","available":true}]}`.
+
+## Point the Butler at it
+
+Store the master key and the gateway URL as the Butler's Anthropic credentials (API-key mode). The key is read from a file or standard input, never from the command line:
+
+```sh
+docker exec -i -u 10001 ouro-butler node /opt/ouro/dist/heart/daemon/ouro-entry.js \
+  auth --agent sanctuary --provider anthropic --api-key-file /dev/stdin --base-url http://127.0.0.1:8787 \
+  < /mnt/user/appdata/credit-gateway/keys/master.key
+```
+
+Then select an Anthropic model for the Butler's lanes with `ouro use`. In API-key mode the agent sends a plain API key, with no Claude Code identity headers, no Claude Code system preamble and no token refresh.
+
+## Change or rotate keys
+
+Replace the file (keep owner 10001 and mode 0600), then `docker restart ouro-credit-gateway`. After rotating `master.key`, run the `auth` step above again so the Butler sends the new master key.

package/deploy/unraid/sanctuary.ouro/bundle-meta.json

@@ -1,5 +1,5 @@
 {
-  "runtimeVersion": "0.1.0-alpha.955",
+  "runtimeVersion": "0.1.0-alpha.956",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0"?>
 <Container version="2">
   <Name>ouro-butler</Name>
-  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.955</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.956</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/gateway/keys.js

@@ -0,0 +1,117 @@
+"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.loadGatewayKeys = loadGatewayKeys;
+exports.loadGatewayState = loadGatewayState;
+exports.saveGatewayState = saveGatewayState;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const MASTER_KEY_FILE = "master.key";
+const KEY_SUFFIX = ".key";
+function readTrimmed(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8").trim();
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Reads the master key and the upstream keys from a directory, once. Every `*.key` file other than
+ * `master.key` is an upstream key; the gateway drains them in file-name order.
+ */
+function loadGatewayKeys(keysDir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(keysDir);
+    }
+    catch (error) {
+        /* v8 ignore next -- defensive: fs always throws Error instances @preserve */
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`gateway: cannot read keys directory ${keysDir}: ${reason}`);
+    }
+    const masterKey = readTrimmed(path.join(keysDir, MASTER_KEY_FILE));
+    if (!masterKey)
+        throw new Error(`gateway: ${path.join(keysDir, MASTER_KEY_FILE)} is missing or empty`);
+    const upstream = [];
+    for (const name of entries.filter((entry) => entry.endsWith(KEY_SUFFIX) && entry !== MASTER_KEY_FILE).sort()) {
+        const key = readTrimmed(path.join(keysDir, name));
+        if (!key)
+            throw new Error(`gateway: upstream key file ${path.join(keysDir, name)} is empty`);
+        upstream.push({ label: name.slice(0, -KEY_SUFFIX.length), key });
+    }
+    if (upstream.length === 0)
+        throw new Error(`gateway: no upstream *.key files in ${keysDir} (besides master.key)`);
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.keys_loaded",
+        message: "credit gateway keys loaded",
+        meta: { keysDir, labels: upstream.map((entry) => entry.label) },
+    });
+    return { masterKey, upstream };
+}
+/** Loads the skip list. A missing or corrupt file starts empty; entries that are not valid times are dropped. */
+function loadGatewayState(statePath) {
+    const exhausted = {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(statePath, "utf8"));
+    }
+    catch {
+        return { exhausted };
+    }
+    const raw = parsed && typeof parsed === "object" ? parsed.exhausted : undefined;
+    if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+        for (const [label, until] of Object.entries(raw)) {
+            if (typeof until === "string" && Number.isFinite(Date.parse(until)))
+                exhausted[label] = until;
+        }
+    }
+    return { exhausted };
+}
+/** Writes the skip list with mode 0600, through a temporary file so a crash never leaves half a file. */
+function saveGatewayState(statePath, state) {
+    const tmpPath = `${statePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmpPath, 0o600);
+    fs.renameSync(tmpPath, statePath);
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.state_saved",
+        message: "credit gateway state saved",
+        meta: { statePath, exhausted: Object.keys(state.exhausted) },
+    });
+}

package/dist/gateway/server.js

@@ -0,0 +1,429 @@
+"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.GATEWAY_MAX_REQUEST_BYTES = exports.GATEWAY_DEFAULT_COOLDOWN_MS = exports.GATEWAY_DEFAULT_UPSTREAM = exports.GATEWAY_DEFAULT_PORT = exports.GATEWAY_DEFAULT_HOST = void 0;
+exports.isCreditExhaustedBody = isCreditExhaustedBody;
+exports.creditGatewayOptionsFromCli = creditGatewayOptionsFromCli;
+exports.startCreditGateway = startCreditGateway;
+exports.waitForShutdownSignal = waitForShutdownSignal;
+exports.runCreditGatewayCommand = runCreditGatewayCommand;
+const http = __importStar(require("node:http"));
+const https = __importStar(require("node:https"));
+const path = __importStar(require("node:path"));
+const zlib = __importStar(require("node:zlib"));
+const node_crypto_1 = require("node:crypto");
+const node_stream_1 = require("node:stream");
+const runtime_1 = require("../nerves/runtime");
+const keys_1 = require("./keys");
+exports.GATEWAY_DEFAULT_HOST = "127.0.0.1";
+exports.GATEWAY_DEFAULT_PORT = 8787;
+exports.GATEWAY_DEFAULT_UPSTREAM = "https://api.anthropic.com";
+exports.GATEWAY_DEFAULT_COOLDOWN_MS = 60 * 60 * 1000;
+exports.GATEWAY_MAX_REQUEST_BYTES = 32 * 1024 * 1024;
+const CREDIT_LOW_PHRASE = "credit balance is too low";
+const CREDIT_CHECK_STATUSES = new Set([400, 402, 403]);
+const HOP_BY_HOP_HEADERS = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "proxy-connection",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+]);
+class RequestTooLargeError extends Error {
+}
+function anthropicError(type, message) {
+    return JSON.stringify({ type: "error", error: { type, message } });
+}
+/* v8 ignore start -- defensive: Node and the HTTP stack always throw Error instances @preserve */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/* v8 ignore stop */
+function digest(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest();
+}
+/** Compares digests so the comparison takes the same time whatever the presented key's length. */
+function matchesMasterKey(presented, masterDigest) {
+    if (!presented)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(digest(presented), masterDigest);
+}
+function presentedKey(req) {
+    const apiKey = req.headers["x-api-key"];
+    if (typeof apiKey === "string" && apiKey.trim())
+        return apiKey.trim();
+    const bearer = /^Bearer\s+(.+)$/i.exec(req.headers.authorization ?? "");
+    return bearer ? bearer[1].trim() : undefined;
+}
+function readRequestBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                reject(new RequestTooLargeError());
+                req.pause();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function readAll(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on("data", (chunk) => chunks.push(chunk));
+        stream.on("end", () => resolve(Buffer.concat(chunks)));
+        stream.on("error", reject);
+    });
+}
+function forwardedRequestHeaders(req, upstreamKey, bodyLength) {
+    const headers = {};
+    for (const [name, value] of Object.entries(req.headers)) {
+        if (HOP_BY_HOP_HEADERS.has(name) || name === "host" || name === "content-length" || name === "x-api-key" || name === "authorization")
+            continue;
+        headers[name] = value;
+    }
+    headers["x-api-key"] = upstreamKey;
+    if (bodyLength > 0)
+        headers["content-length"] = String(bodyLength);
+    return headers;
+}
+function responseHeaders(headers) {
+    const result = {};
+    for (const [name, value] of Object.entries(headers)) {
+        if (HOP_BY_HOP_HEADERS.has(name))
+            continue;
+        result[name] = value;
+    }
+    return result;
+}
+/** Decodes a compressed body for inspection only; the client still gets the original bytes. */
+function decodeForInspection(body, encoding) {
+    try {
+        const normalized = (encoding ?? "").trim().toLowerCase();
+        if (normalized === "gzip" || normalized === "x-gzip")
+            return zlib.gunzipSync(body).toString("utf8");
+        if (normalized === "deflate")
+            return zlib.inflateSync(body).toString("utf8");
+        if (normalized === "br")
+            return zlib.brotliDecompressSync(body).toString("utf8");
+        return body.toString("utf8");
+    }
+    catch {
+        return body.toString("utf8");
+    }
+}
+function isCreditExhaustedBody(body, encoding) {
+    return decodeForInspection(body, encoding).toLowerCase().includes(CREDIT_LOW_PHRASE);
+}
+function upstreamUrl(base, requestUrl) {
+    const prefix = base.pathname.replace(/\/+$/, "");
+    return new URL(`${prefix}${requestUrl}`, base.origin);
+}
+function sendUpstream(target, method, headers, body) {
+    return new Promise((resolve, reject) => {
+        const transport = target.protocol === "https:" ? https : http;
+        const request = transport.request(target, { method, headers }, (response) => resolve({ response, request }));
+        request.on("error", reject);
+        request.end(body.length > 0 ? body : undefined);
+    });
+}
+function writeBuffered(res, buffered) {
+    res.writeHead(buffered.status, { ...buffered.headers, "content-length": String(buffered.body.length) });
+    res.end(buffered.body);
+}
+function writeJsonError(res, status, type, message) {
+    const body = Buffer.from(anthropicError(type, message));
+    writeBuffered(res, { status, headers: { "content-type": "application/json" }, body });
+}
+/** Maps `ouro gateway serve` flags to gateway options. */
+function creditGatewayOptionsFromCli(command) {
+    return {
+        keysDir: command.keysDir,
+        ...(command.statePath ? { statePath: command.statePath } : {}),
+        ...(command.host ? { host: command.host } : {}),
+        ...(command.port !== undefined ? { port: command.port } : {}),
+        ...(command.upstream ? { upstream: command.upstream } : {}),
+        ...(command.cooldownMinutes !== undefined ? { cooldownMs: command.cooldownMinutes * 60 * 1000 } : {}),
+    };
+}
+/* v8 ignore start -- the default log writes to the real stderr; tests inject log @preserve */
+function defaultLog(line) {
+    process.stderr.write(`${line}\n`);
+}
+/* v8 ignore stop */
+/**
+ * Starts the credit gateway: a byte-passthrough proxy to the Anthropic API that accepts one master key
+ * and spends the upstream keys in a fixed order, moving to the next key only when the current one
+ * reports that its credit balance is too low.
+ */
+async function startCreditGateway(options) {
+    const keys = (0, keys_1.loadGatewayKeys)(options.keysDir);
+    const statePath = options.statePath ?? path.join(options.keysDir, "gateway-state.json");
+    const state = (0, keys_1.loadGatewayState)(statePath);
+    const host = options.host ?? exports.GATEWAY_DEFAULT_HOST;
+    const upstreamBase = new URL(options.upstream ?? exports.GATEWAY_DEFAULT_UPSTREAM);
+    const cooldownMs = options.cooldownMs ?? exports.GATEWAY_DEFAULT_COOLDOWN_MS;
+    const maxRequestBytes = options.maxRequestBytes ?? exports.GATEWAY_MAX_REQUEST_BYTES;
+    const now = options.now ?? Date.now;
+    const log = options.log ?? defaultLog;
+    const masterDigest = digest(keys.masterKey);
+    function persist() {
+        try {
+            (0, keys_1.saveGatewayState)(statePath, state);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "gateway",
+                event: "gateway.state_save_error",
+                message: "credit gateway could not save its state",
+                meta: { statePath, error: errorMessage(error) },
+            });
+        }
+    }
+    /** Returns the skip-until time for a label, or undefined when the key is usable. Expired entries are dropped. */
+    function skipUntil(label) {
+        const until = state.exhausted[label];
+        if (!until)
+            return undefined;
+        if (Date.parse(until) > now())
+            return until;
+        delete state.exhausted[label];
+        persist();
+        return undefined;
+    }
+    function markExhausted(entry) {
+        state.exhausted[entry.label] = new Date(now() + cooldownMs).toISOString();
+        persist();
+        log(`gateway: ${entry.label} out of credits; moving on`);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "gateway",
+            event: "gateway.key_exhausted",
+            message: "credit gateway key is out of credits",
+            meta: { label: entry.label, skipUntil: state.exhausted[entry.label] },
+        });
+    }
+    function logRequest(label, method, pathname, status, startedAt) {
+        const ms = now() - startedAt;
+        log(`gateway: ${label} ${method} ${pathname} ${status} ${ms}ms`);
+        (0, runtime_1.emitNervesEvent)({
+            component: "gateway",
+            event: "gateway.request",
+            message: "credit gateway request",
+            meta: { label, method, path: pathname, status, ms },
+        });
+    }
+    async function handle(req, res) {
+        const startedAt = now();
+        /* v8 ignore start -- Node always supplies url and method for accepted HTTP requests @preserve */
+        const requestUrl = req.url ?? "/";
+        const method = req.method ?? "GET";
+        /* v8 ignore stop */
+        const pathname = new URL(requestUrl, "http://gateway.local").pathname;
+        if (method === "GET" && pathname === "/health") {
+            const body = JSON.stringify({
+                ok: true,
+                keys: keys.upstream.map((entry) => {
+                    const until = skipUntil(entry.label);
+                    return until ? { label: entry.label, available: false, skipUntil: until } : { label: entry.label, available: true };
+                }),
+            });
+            writeBuffered(res, { status: 200, headers: { "content-type": "application/json" }, body: Buffer.from(body) });
+            logRequest("-", method, pathname, 200, startedAt);
+            return;
+        }
+        if (!matchesMasterKey(presentedKey(req), masterDigest)) {
+            writeJsonError(res, 401, "authentication_error", "invalid x-api-key");
+            logRequest("-", method, pathname, 401, startedAt);
+            return;
+        }
+        const target = upstreamUrl(upstreamBase, requestUrl);
+        if (target.origin !== upstreamBase.origin) {
+            writeJsonError(res, 400, "invalid_request_error", "invalid request path");
+            logRequest("-", method, pathname, 400, startedAt);
+            return;
+        }
+        let body;
+        try {
+            body = await readRequestBody(req, maxRequestBytes);
+        }
+        catch (error) {
+            /* v8 ignore start -- the client went away while sending its body; there is no one to answer @preserve */
+            if (!(error instanceof RequestTooLargeError)) {
+                res.destroy();
+                return;
+            }
+            /* v8 ignore stop */
+            res.setHeader("connection", "close");
+            writeJsonError(res, 413, "request_too_large", `request body exceeds ${maxRequestBytes} bytes`);
+            logRequest("-", method, pathname, 413, startedAt);
+            return;
+        }
+        let lastCredit;
+        let lastCreditLabel = "-";
+        for (const entry of keys.upstream) {
+            if (skipUntil(entry.label))
+                continue;
+            let upstream;
+            try {
+                upstream = await sendUpstream(target, method, forwardedRequestHeaders(req, entry.key, body.length), body);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "gateway",
+                    event: "gateway.upstream_error",
+                    message: "credit gateway could not reach the upstream API",
+                    meta: { label: entry.label, error: errorMessage(error) },
+                });
+                writeJsonError(res, 502, "api_error", "credit gateway could not reach the upstream API");
+                logRequest(entry.label, method, pathname, 502, startedAt);
+                return;
+            }
+            /* v8 ignore next -- Node always sets statusCode on an upstream response @preserve */
+            const status = upstream.response.statusCode ?? 502;
+            if (CREDIT_CHECK_STATUSES.has(status)) {
+                const buffered = {
+                    status,
+                    headers: responseHeaders(upstream.response.headers),
+                    body: await readAll(upstream.response),
+                };
+                if (isCreditExhaustedBody(buffered.body, upstream.response.headers["content-encoding"])) {
+                    markExhausted(entry);
+                    lastCredit = buffered;
+                    lastCreditLabel = entry.label;
+                    continue;
+                }
+                writeBuffered(res, buffered);
+                logRequest(entry.label, method, pathname, status, startedAt);
+                return;
+            }
+            res.writeHead(status, responseHeaders(upstream.response.headers));
+            res.flushHeaders();
+            (0, node_stream_1.pipeline)(upstream.response, res, (error) => {
+                if (error)
+                    upstream.request.destroy();
+                logRequest(entry.label, method, pathname, status, startedAt);
+            });
+            return;
+        }
+        if (lastCredit) {
+            writeBuffered(res, { ...lastCredit, status: 400 });
+        }
+        else {
+            writeJsonError(res, 400, "invalid_request_error", "Your credit balance is too low on every gateway key");
+        }
+        logRequest(lastCreditLabel, method, pathname, 400, startedAt);
+    }
+    const server = http.createServer((req, res) => {
+        handle(req, res).catch((error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "gateway",
+                event: "gateway.request_error",
+                message: "credit gateway request failed",
+                meta: { error: errorMessage(error) },
+            });
+            /* v8 ignore next 4 -- failures after the headers went out are reported by the stream pipeline instead @preserve */
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            writeJsonError(res, 502, "api_error", "credit gateway request failed");
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        /* v8 ignore next -- tests always bind port 0; the default is for production @preserve */
+        const port = options.port ?? exports.GATEWAY_DEFAULT_PORT;
+        server.listen(port, host, () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const url = `http://${host}:${address.port}`;
+    (0, runtime_1.emitNervesEvent)({
+        component: "gateway",
+        event: "gateway.server_started",
+        message: "credit gateway started",
+        meta: { url, upstream: upstreamBase.origin, labels: keys.upstream.map((entry) => entry.label), statePath },
+    });
+    return {
+        server,
+        url,
+        port: address.port,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "gateway",
+                    event: "gateway.server_stopped",
+                    message: "credit gateway stopped",
+                    meta: { url },
+                });
+                resolve();
+            });
+        }),
+    };
+}
+/* v8 ignore start -- waits for real process signals; tests inject waitForStop @preserve */
+function waitForShutdownSignal() {
+    return new Promise((resolve) => {
+        process.once("SIGINT", () => resolve());
+        process.once("SIGTERM", () => resolve());
+    });
+}
+/* v8 ignore stop */
+/** Runs `ouro gateway serve` in the foreground until `waitForStop` resolves. */
+async function runCreditGatewayCommand(command, deps) {
+    const handle = await startCreditGateway(creditGatewayOptionsFromCli(command));
+    const message = `credit gateway listening on ${handle.url}\nhealth: ${handle.url}/health`;
+    deps.writeStdout(message);
+    /* v8 ignore next -- production waits for SIGINT/SIGTERM; tests inject waitForStop @preserve */
+    await (deps.waitForStop ?? waitForShutdownSignal)();
+    await handle.close();
+    return message;
+}

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/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.955",
+  "version": "0.1.0-alpha.956",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.955",
+      "version": "0.1.0-alpha.956",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.78.0",
         "@azure/identity": "^4.13.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.955",
+  "version": "0.1.0-alpha.956",
   "engines": {
     "node": ">=22"
   },