@ouro.bot/cli 0.1.0-alpha.851 → 0.1.0-alpha.853

package/changelog.json

@@ -1,6 +1,18 @@
 {
   "_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.853",
+      "changes": [
+        "The Butler's override grab sends the release's quality and languages, which Sonarr v4 requires (it returned HTTP 500 without them)"
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.852",
+      "changes": [
+        "An orientation hold no longer blocks read-only tools from the agent's own MCP servers (readOnlyHint); the Butler's media lookups are marked read-only. The media tools treat a 200 with an empty body as success, so clearing a stuck download goes on to re-search"
+      ]
+    },
     {
       "version": "0.1.0-alpha.851",
       "changes": [

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

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

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

@@ -63,7 +63,9 @@ async function req(base, path, { key, header = "X-Api-Key", method = "GET", body
     throw new ServiceError(`${serviceOf(base)}_http_${res.status}`, `${serviceOf(base)} returned ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`)
   }
   if (res.status === 204) return null
-  return res.json()
+  // Sonarr/Radarr answer some DELETEs with 200 and an empty body; that is success, not a parse failure.
+  const raw = await res.text()
+  return raw.trim() ? JSON.parse(raw) : null
 }
 
 function serviceOf(base) {
@@ -1010,7 +1012,10 @@ export async function mediaReleaseSearch(a) {
     raw = await sonarr("/release", { query: { seriesId: serviceId, seasonNumber: a.season_number }, timeoutMs: SEARCH_TIMEOUT_MS })
   } else return { result: "season_number_or_episode_ids_required" }
   const seen = new Set()
-  let rows = (Array.isArray(raw) ? raw : []).filter((r) => (seen.has(r.guid) ? false : seen.add(r.guid))).map((r) => releaseRow(a.kind, r))
+  const unique = (Array.isArray(raw) ? raw : []).filter((r) => (seen.has(r.guid) ? false : seen.add(r.guid)))
+  // Sonarr's override grab needs the release's own quality and languages objects back.
+  const rawByGuid = new Map(unique.map((r) => [r.guid, r]))
+  let rows = unique.map((r) => releaseRow(a.kind, r))
   const total = rows.length
   if (a.query) {
     const q = String(a.query).toLowerCase()
@@ -1018,7 +1023,11 @@ export async function mediaReleaseSearch(a) {
   }
   rows.sort((x, y) => Number(y.seeders ?? 0) - Number(x.seeders ?? 0))
   const limit = Math.min(Math.max(Number(a.limit) || 40, 1), 100)
-  for (const r of rows) cacheRelease(`${a.kind}:${r.guid}`, { ...r, service_id: serviceId, season_number: a.season_number ?? null })
+  for (const r of rows) {
+    const source = rawByGuid.get(r.guid)
+    cacheRelease(`${a.kind}:${r.guid}`, { ...r, service_id: serviceId, season_number: a.season_number ?? null,
+      quality_raw: source?.quality ?? null, languages_raw: source?.languages ?? null })
+  }
   return { kind: a.kind, service_id: serviceId, total_found: total, matched: rows.length, releases: rows.slice(0, limit) }
 }
 
@@ -1047,7 +1056,10 @@ export async function mediaReleaseGrab(a) {
       const own = new Set((await seriesEpisodes(seriesId)).map((e) => e.id))
       const foreign = a.episode_ids.filter((id) => !own.has(id))
       if (foreign.length) return { result: "episode_id_not_for_series", foreign_episode_ids: foreign }
-      Object.assign(body, { seriesId, episodeIds: a.episode_ids.map(Number), shouldOverride: true })
+      // Sonarr v4 refuses an override without quality and languages (ArgumentNullException, HTTP 500).
+      if (!cached.quality_raw) return { result: "release_quality_unknown", message: "Sonarr's search did not report this release's quality; search again." }
+      Object.assign(body, { seriesId, episodeIds: a.episode_ids.map(Number), shouldOverride: true,
+        quality: cached.quality_raw, languages: Array.isArray(cached.languages_raw) ? cached.languages_raw : [] })
       if (a.download_client_id !== undefined && a.download_client_id !== null) body.downloadClientId = Number(a.download_client_id)
     }
   }
@@ -1135,9 +1147,10 @@ export async function mediaManualImport(a) {
 
 // ------------------------------------------------------------------- schema
 
-const TOOLS = [
+export const TOOLS = [
   {
     name: "media_search",
+    annotations: { readOnlyHint: true },
     description: "Search or browse the household media catalogue. Use `query` for a title lookup: partial and misspelled titles are matched against the library first (Sonarr, Radarr, Jellyfin) and returned as `library_matches` with their kind and service id, and when nothing in the library matches, `lookup_candidates` (TVDB/TMDB) cover titles not in the library. Never say a title does not exist without reading both; use `genres`/`keywords`/`year_range` to browse by vibe (e.g. keywords ['autumn','thanksgiving'] for cozy fall films). `on_shelf: true` restricts to what is already downloaded, `false` to what is not, omit for both. Every item says whether it is on the shelf and carries its tmdb_id so a follow-up media_request needs no second lookup.",
     inputSchema: { type: "object", properties: {
       query: { type: "string", description: "Title or free text. Omit to browse by filters." },
@@ -1163,6 +1176,7 @@ const TOOLS = [
   },
   {
     name: "media_request_status",
+    annotations: { readOnlyHint: true },
     description: "One call, every stage: request, indexer search, download, file on disk, plus acquisition-chain health and a deterministic `diagnosis` block naming what is stuck, why, and the fix. Use this for any 'is it here yet?' or 'why hasn't X downloaded?' question. A queue row is not proof of progress: a release sitting at zero bytes comes back as stalled, not as downloading. Never infer the cause yourself — read diagnosis.summary.",
     inputSchema: { type: "object", properties: {
       request_id: { type: "string", description: "e.g. jellyseerr:42" },
@@ -1181,6 +1195,7 @@ const TOOLS = [
   },
   {
     name: "media_chain_health",
+    annotations: { readOnlyHint: true },
     description: "Health of the whole acquisition chain: Prowlarr indexers, their failure state, and whether Prowlarr is syncing to Sonarr/Radarr. Call this when several things are stuck at once, or before telling anyone a specific title is the problem — a dead chain blocks everything and is the single most likely cause.",
     inputSchema: { type: "object", properties: {} },
   },
@@ -1213,6 +1228,7 @@ const TOOLS = [
   },
   {
     name: "media_episodes",
+    annotations: { readOnlyHint: true },
     description: "List a Sonarr series' episodes (optionally one season): episode_id, SxxEyy code, scene_code (the numbering release names use, when Sonarr has a mapping), title, air date, has_file. Use it to see what the TVDB numbering calls each episode before searching for releases by hand.",
     inputSchema: { type: "object", properties: {
       service_id: { type: "number", description: "Sonarr series id." },
@@ -1221,6 +1237,7 @@ const TOOLS = [
   },
   {
     name: "media_indexer_search",
+    annotations: { readOnlyHint: true },
     description: "Free-text search across every indexer (Prowlarr), sorted by seeders. Discovery only, it grabs nothing. Use it when Sonarr/Radarr's own search finds nothing: try the scene code from media_episodes, 'Season N', the year, or an episode title, to learn whether any release exists and how it is named. Zero seeders means it cannot download right now.",
     inputSchema: { type: "object", properties: {
       query: { type: "string" },
@@ -1229,6 +1246,7 @@ const TOOLS = [
   },
   {
     name: "media_release_search",
+    annotations: { readOnlyHint: true },
     description: "Interactive release search for a series or movie already in the library: what the indexers offer and how Sonarr/Radarr parsed each release (full_season, parsed_season, parsed_episodes, mapped_episodes), whether it is rejected and why, and whether it is blocklisted. Series: give season_number or episode_ids. Can take a minute or more. `query` filters returned titles. Use it when the automatic search found nothing, then grab with media_release_grab.",
     inputSchema: { type: "object", properties: {
       kind: { type: "string", enum: ["series", "movie"] },

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.851</Repository>
+  <Repository>ghcr.io/ourostack/ouroboros-butler:0.1.0-alpha.853</Repository>
   <Registry>https://github.com/ourostack/ouroboros/pkgs/container/ouroboros-butler</Registry>
   <Network>host</Network>
   <Shell>sh</Shell>

package/dist/repertoire/mcp-tools.js

@@ -67,11 +67,15 @@ function mcpToolsAsDefinitions(view) {
         });
         return {
             tool: schema,
-            riskProfile: {
-                mutates: "external_side_effect",
-                risk: "high",
-                reason: "MCP tools may mutate external systems",
-            },
+            // A read-only hint is trusted only from the agent's own bundle (agent.json mcpServers),
+            // so an orientation hold still lets the agent inspect through those tools.
+            riskProfile: entry.source === "builtin" && tool.annotations?.readOnlyHint === true
+                ? { mutates: "none", risk: "low", reason: "read-only tool from the agent's own MCP server" }
+                : {
+                    mutates: "external_side_effect",
+                    risk: "high",
+                    reason: "MCP tools may mutate external systems",
+                },
             handler: async (args, ctx) => {
                 if (ctx?.agentName !== binding.agentName || ctx.agentRoot !== binding.agentRoot) {
                     (0, runtime_1.emitNervesEvent)({

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.851",
+  "version": "0.1.0-alpha.853",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ouro.bot/cli",
-      "version": "0.1.0-alpha.851",
+      "version": "0.1.0-alpha.853",
       "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.851",
+  "version": "0.1.0-alpha.853",
   "engines": {
     "node": ">=22"
   },