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

package/changelog.json

@@ -1,6 +1,30 @@
 {
   "_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.957",
+      "changes": [
+        "Butler no longer starts a model turn just to close a problem that fixed itself, unless he had told you about it.",
+        "Background turns that run out of steps now wrap up cleanly instead of failing.",
+        "Turns started by server events now count against Butler's daily allowance, and repeated failures pause them for 30 minutes.",
+        "Media lookups now say whether a title was actually requested and whether it is downloading, instead of claiming it is being processed.",
+        "Questions and reports Butler sends you are written in plain words, separate from his internal notes.",
+        "A web endpoint must fail two health checks in a row before Butler treats it as down, and informational Unraid notices are ignored.",
+        "The house digest stops repeating the same stuck items as new.",
+        "Butler sends at most three unprompted messages a day and none between 23:00 and 08:00, except disk, parity and array alerts.",
+        "Server events blocked by Butler's daily allowance or failure pause now wait and retry instead of being dropped, and disk, parity and array events are never held back.",
+        "The health acceptance probe keeps checking a web endpoint once per sweep, so its scripted scenarios still match what Butler does.",
+        "Media request and request-status answers use the same plain shelf states (downloading, in Radarr or Sonarr but not downloading, available) instead of \"processing\"."
+      ]
+    },
+    {
+      "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.957",
   "bundleSchemaVersion": 3,
   "lastUpdated": "2026-09-03T00:00:00.000Z"
 }

package/deploy/unraid/sanctuary.ouro/mcp/media-mcp.mjs

@@ -94,7 +94,7 @@ const prowlarr = (path, opts = {}) => req(PROWLARR.url, `/api/v1${path}`, { key:
 // ------------------------------------------------------------------ mapping
 
 // Jellyseerr media status codes.
-const MEDIA_STATUS = { 1: "unknown", 2: "pending", 3: "processing", 4: "partially_available", 5: "available" }
+const MEDIA_STATUS = { 1: "unknown", 2: "pending", 4: "partially_available", 5: "available" }
 const REQUEST_STATUS = { 1: "pending_approval", 2: "approved", 3: "declined", 4: "failed" }
 
 const TMDB_GENRES = {
@@ -110,11 +110,25 @@ function genreNames(item) {
   return ids.map((id) => TMDB_GENRES[id]).filter(Boolean)
 }
 
-function shelfItem(item) {
+// Jellyseerr's media status 3 only means Sonarr/Radarr track the title; it says nothing about
+// a download or a request. Name what is actually known so nobody reads it as "processing".
+function shelfStateOf(kind, info) {
+  if (info.status === 3) return info.downloadStatus?.length ? "downloading" : `in_${kind === "series" ? "sonarr" : "radarr"}_not_downloading`
+  return MEDIA_STATUS[info.status] ?? "not_on_shelf"
+}
+
+// A request exists only if Jellyseerr lists one; the media status is not a request.
+function requestStateOf(info) {
+  if (!Array.isArray(info.requests)) return info.status ? "unknown_check_media_request_status" : "never_requested"
+  if (info.requests.length === 0) return "never_requested"
+  return REQUEST_STATUS[info.requests[info.requests.length - 1].status] ?? "requested"
+}
+
+export function shelfItem(item) {
   const kind = item.mediaType === "tv" ? "series" : item.mediaType === "movie" ? "movie" : (item.firstAirDate ? "series" : "movie")
   const date = item.releaseDate ?? item.firstAirDate ?? ""
   const info = item.mediaInfo ?? {}
-  const status = MEDIA_STATUS[info.status] ?? "not_on_shelf"
+  const status = shelfStateOf(kind, info)
   return {
     title: item.title ?? item.name ?? null,
     year: date ? Number(date.slice(0, 4)) : null,
@@ -126,8 +140,8 @@ function shelfItem(item) {
     // The two fields that stop a second call:
     on_shelf: status === "available" || status === "partially_available",
     shelf_state: status,
-    request_state: info.status ? (status === "available" ? "available" : status) : "never_requested",
-    sonarr_id: info.externalServiceId ?? null,
+    request_state: requestStateOf(info),
+    sonarr_id: kind === "series" ? (info.externalServiceId ?? null) : null,
     radarr_id: kind === "movie" ? (info.externalServiceId ?? null) : null,
     poster_path: item.posterPath ? `https://image.tmdb.org/t/p/w500${item.posterPath}` : null,
     vote_average: item.voteAverage ?? null,
@@ -385,7 +399,7 @@ async function mediaRequest(a) {
 
   const existing = await findExistingRequest(tmdbId, kind)
   if (existing?.hasRequest) {
-    const shelf = MEDIA_STATUS[existing.media?.status] ?? "unknown"
+    const shelf = shelfStateOf(kind, existing.media ?? {})
     return {
       resolved: true, title: resolvedTitle ?? existing.media?.title ?? null, year: resolvedYear, kind, tmdb_id: tmdbId,
       request_id: `jellyseerr:${existing.id}`,
@@ -412,7 +426,7 @@ async function mediaRequest(a) {
     approval_state: REQUEST_STATUS[created.status] ?? "submitted",
     duplicate_of: null,
     jellyseerr_status: REQUEST_STATUS[created.status] ?? "submitted",
-    shelf_state: MEDIA_STATUS[created.media?.status] ?? "processing",
+    shelf_state: created.media?.status ? shelfStateOf(kind, created.media) : "not_on_shelf",
     submitted_at: created.createdAt,
     tvdb_id: created.media?.tvdbId ?? null,
     sonarr_id: kind === "series" ? (created.media?.externalServiceId ?? null) : null,
@@ -520,7 +534,7 @@ export async function mediaRequestStatus(a) {
 
   const kind = request.type === "tv" ? "series" : "movie"
   const media = request.media ?? {}
-  const shelf = MEDIA_STATUS[media.status] ?? "unknown"
+  const shelf = shelfStateOf(kind, media)
   const svcId = media.externalServiceId ?? null
 
   const result = {

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.957</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) },
+    });
+}