opencode-raven 2.1.1 → 2.1.3

package/README.md

@@ -2,27 +2,27 @@
 
 <table>
 <tr>
-<td><img src="Raven.png" alt="Raven" width="768" /></td>
+<td width="40%"><img src="Raven.png" alt="Raven" width="100%" /></td>
 <td>
-<strong>Context firewall for <a href="https://opencode.ai">OpenCode</a></strong><br/>
-Raven routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model, saving cost and context.
+Raven gives OpenCode useful search tools by default and optional on-demand MCPs for any remote or local MCP you want to add. It keeps noisy tool work behind a focused Raven agent, so your main model gets compact answers instead of raw search results, docs pages, GitHub examples, MCP output, or large MCP schemas.
+
+## Why Use Raven?
+
+* Routed search, fetch, and bash discovery work through Raven.
+* Context7, Exa, and Grep.app are bundled as on-demand MCP defaults.
+* Any extra MCP can be added under `onDemandMcpServers` when you want it.
+* Configured noisy tools and MCPs are blocked for non-Raven agents and forced through `raven_seek`.
 </td>
 </tr>
 </table>
 
-## What Raven Does
-
-Tool-heavy work floods context. Search, docs, web, GitHub examples, and verbose MCP calls can dump raw results into your expensive main model. Raven is a hard blocker-rerouter: configured tools fail closed for non-Raven agents and must be delegated through `raven_seek`, where a focused Raven agent performs the work and returns a compact answer.
-
-Raven fixes three problems:
-
-1. **Context flooding** - Keep noisy tool results out of the main session. Raven summarizes tool/MCP output before returning it.
-2. **Cost** - Use a cheaper model like `opencode/deepseek-v4-flash-free` for tool-heavy work while saving your main model's context for decisions and edits.
-3. **Enforcement** - This is not soft nudging. Raven blocks configured tools/MCP prefixes for non-Raven agents and gives them the exact `raven_seek` retry path.
+## Example
 
-Raven defaults to routing noisy search/fetch tools and bundles Context7, Exa, and Grep.app as on-demand MCPs that are always handled behind Raven.
+<p align="center">
+  <img src="example.gif" alt="Raven example: searching today's top 30 AI news items while saving 71K context" />
+</p>
 
-Important limitation: MCPs enabled directly in OpenCode config still load their tool schemas into the main session. Raven saves context from tool calls and raw results for those global MCPs, but schema hiding requires putting the MCP in Raven's `onDemandMcpServers`. **Strongly recommended:** configure noisy/search/docs/web MCPs as on-demand MCPs unless you need direct main-agent access.
+In this example, the main model asks for the top 30 AI news items from today. Raven handles the noisy search/web work in a focused agent and returns the compact result, saving about 71K context that would otherwise have landed in the main session.
 
 ## Install
 
@@ -36,6 +36,8 @@ Add Raven to your `opencode.jsonc` plugins:
 
 Restart opencode. It will resolve Raven from npm and cache the plugin automatically.
 
+That is enough to start using Raven. The default config already includes routed search/fetch tools and bundled on-demand MCPs for Context7, Exa, and Grep.app. Add any other MCP under `onDemandMcpServers` only if you want more capabilities.
+
 Raven checks for package updates and notifies you when a newer version is available. Run `/raven update`, then restart opencode.
 
 ## Quick Use
@@ -78,17 +80,11 @@ The main agent does not see Raven's internal tool calls or raw tool output, just
 
 Config persists across restarts in `~/.config/opencode/opencode-raven/raven-config.json`. It is global and shared across all projects.
 
-## Example
-
-<p align="center">
-  <img src="example.gif" alt="Raven example: searching today's top 30 AI news items while saving 71K context" />
-</p>
-
-In this example, the main model asks for the top 30 AI news items from today. Raven handles the noisy search/web work in a focused agent and returns the compact result, saving about 71K context that would otherwise have landed in the main session.
-
 ## Recommended MCP Setup
 
-Raven's bundled Context7, Exa, and Grep.app MCPs are on-demand by default. They live in `onDemandMcpServers`, so Raven connects to them internally through `raven_mcp` instead of registering their full tool schemas in OpenCode's global MCP config.
+You do not need to configure MCPs just to try Raven. Raven gives you the search tools up front, supports any MCP as an on-demand MCP, and bundles Context7, Exa, and Grep.app as defaults. Add more MCPs only when you want extra capabilities.
+
+On-demand MCPs live in `onDemandMcpServers`, so Raven connects to them internally through `raven_mcp` only when needed instead of registering their full tool schemas in OpenCode's global MCP config. Context7, Exa, and Grep.app are included there by default, but the same setup works for any remote or local MCP you want to add.
 
 On-demand MCPs are always behind Raven and do not need routing entries.
 
@@ -96,6 +92,8 @@ Raven checks configured on-demand MCPs after startup. `/raven` and `/raven mcp`
 
 Raven also warns if the same MCP server name is configured both globally in OpenCode and in Raven's `onDemandMcpServers`. Prefer one location: on-demand for schema hiding, or global only when direct main-agent access is required.
 
+Important limitation: MCPs enabled directly in OpenCode config still load their tool schemas into the main session. Raven saves context from tool calls and raw results for those global MCPs, but schema hiding requires putting the MCP in Raven's `onDemandMcpServers`. **Strongly recommended:** configure noisy/search/docs/web MCPs as on-demand MCPs unless you need direct main-agent access.
+
 All three bundled MCPs work without API keys. Add keys for higher rate limits:
 
 | MCP | URL | API key |
@@ -119,23 +117,36 @@ To add an API key to an on-demand MCP, edit Raven config:
 }
 ```
 
-To add a local stdio MCP:
+### Add Your Own On-Demand MCP
+
+To add another MCP, put it under `onDemandMcpServers`. Raven will connect to it only when needed, discover its tools, and generate guidance automatically. Your main model does not need to load that MCP's full schema up front.
+
+Use `remote` for hosted MCPs and `local` for command-based MCPs.
+
+To add an OpenCode-style local MCP:
 
 ```jsonc
 {
   "onDemandMcpServers": {
-    "localServer": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": ["some-mcp-server"],
-      "env": { "API_KEY": "{env:API_KEY}" },
-      "cwd": "/optional/path",
-      "description": "Local MCP server."
+    "unityMCP": {
+      "type": "local",
+      "command": [
+        "C:\\Users\\evila\\.local\\bin\\uvx.exe",
+        "--offline",
+        "--from",
+        "mcpforunityserver==9.7.1",
+        "mcp-for-unity",
+        "--transport",
+        "stdio"
+      ],
+      "enabled": true
     }
   }
 }
 ```
 
+This matches OpenCode's local MCP shape: `type: "local"`, `command` as an array, optional `environment`, optional `timeout`, and optional `enabled`. Raven also supports `cwd` and `description`. `enabled` defaults to `true`; set it to `false` to keep a server in config without loading it.
+
 `description` is user-authored and never overwritten. Raven fills missing generated metadata after startup or when you run `/raven mcp refresh [server]`, storing tool summaries, MCP health, and avoided schema-load estimates separately in `~/.config/opencode/opencode-raven/autogenerated-on-demand-mcp-metadata.json`.
 
 Raven also writes generated main-model guidance to `~/.config/opencode/opencode-raven/autogenerated-on-demand-guidance.md` and injects that file into OpenCode instructions at startup.
@@ -157,16 +168,19 @@ Edit config manually or use `/raven` commands:
   "onDemandMcpDescriptionDetail": "full",
   "onDemandMcpServers": {
     "context7": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.context7.com/mcp",
       "description": "Library/framework documentation lookup."
     },
     "exa": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.exa.ai/mcp",
       "description": "Live web search and webpage fetching."
     },
     "grep_app": {
+      "enabled": true,
       "type": "remote",
       "url": "https://mcp.grep.app",
       "description": "Public GitHub code search and real-world examples."
@@ -174,7 +188,7 @@ Edit config manually or use `/raven` commands:
   },
   "excludeAgents": [],
   "excludeTools": [],
-  "timeout": 180
+  "timeout": 600
 }
 ```
 
@@ -187,10 +201,10 @@ Edit config manually or use `/raven` commands:
 | `routeTools` | built-in search/fetch tools plus `bash` | Exact tool names hard-routed through Raven. `bash` routes only search-like bash commands, not every bash call. |
 | `routeToolKeywords` | `[]` | Case-insensitive substrings hard-routed through Raven for globally registered tools with non-standard names. Catches suffix-style names like `web_search_exa`. |
 | `onDemandMcpDescriptionDetail` | `"full"` | On-demand MCP guidance detail. `full` includes tool names/descriptions; `minimized` uses compact capability summaries. |
-| `onDemandMcpServers` | Context7, Exa, Grep.app | MCPs Raven connects to internally on demand, without registering full schemas in OpenCode global MCP config. Supports `remote` and `stdio`. |
+| `onDemandMcpServers` | Context7, Exa, Grep.app | MCPs Raven connects to internally on demand, without registering full schemas in OpenCode global MCP config. Supports OpenCode-style `remote` and `local` entries. Each server supports `enabled`, defaulting to `true`. |
 | `excludeAgents` | `[]` | Agents that bypass Raven routing, case-insensitive. |
 | `excludeTools` | `[]` | Exact tools that never get blocked, even if matched by auto-routed global MCP prefixes. |
-| `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |
+| `timeout` | `600` | Max seconds for a `raven_seek` call. Provider/API retry errors and no-initial-response startup failures are reported quickly; after provider failures, routed tools tell the user how to switch Raven's model instead of retrying Raven. On timeout the session is kept for inspection. |
 | `stats` | auto | Session and global estimated context saved by Raven. Managed automatically. |
 
 Use `ravenInstructions` for extra Raven-only guidance, such as how to use custom MCPs:
@@ -285,7 +299,7 @@ Raven itself has access to these tools, blocked for other agents when configured
 | `read`, `glob`, `grep`, `list` | Local codebase inspection |
 | `bash` | Full local shell access, including `rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, and `find` |
 | `external_directory` | Allowed, with no permission prompts when accessing paths outside the workspace |
-| `raven_mcp` | Raven-only bridge to on-demand remote/stdio MCP servers |
+| `raven_mcp` | Raven-only bridge to on-demand remote/local MCP servers |
 | Context7 | On-demand library/framework/SDK/API docs |
 | Exa AI | On-demand web search, news, pages, products |
 | Grep.app | On-demand public GitHub examples |

package/index.ts

@@ -31,16 +31,19 @@ const DEFAULT_ROUTE_TOOL_KEYWORDS: string[] = []
 
 const DEFAULT_ON_DEMAND_MCP_SERVERS: Record<string, OnDemandMcpServer> = {
   context7: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.context7.com/mcp",
     description: "Library/framework documentation lookup.",
   },
   exa: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.exa.ai/mcp",
     description: "Live web search and webpage fetching.",
   },
   grep_app: {
+    enabled: true,
     type: "remote",
     url: "https://mcp.grep.app",
     description: "Public GitHub code search and real-world examples.",
@@ -138,6 +141,8 @@ interface OnDemandMcpToolInfo {
 }
 
 interface BaseOnDemandMcpServer {
+  enabled?: boolean
+  timeout?: number
   description?: string
 }
 
@@ -154,17 +159,17 @@ interface RemoteOnDemandMcpServer extends BaseOnDemandMcpServer {
   type: "remote"
   url: string
   headers?: Record<string, string>
+  oauth?: Record<string, unknown> | false
 }
 
-interface StdioOnDemandMcpServer extends BaseOnDemandMcpServer {
-  type: "stdio"
-  command: string
-  args?: string[]
-  env?: Record<string, string>
+interface LocalOnDemandMcpServer extends BaseOnDemandMcpServer {
+  type: "local"
+  command: string[]
+  environment?: Record<string, string>
   cwd?: string
 }
 
-type OnDemandMcpServer = RemoteOnDemandMcpServer | StdioOnDemandMcpServer
+type OnDemandMcpServer = RemoteOnDemandMcpServer | LocalOnDemandMcpServer
 type OnDemandMcpDescriptionDetail = "full" | "minimized"
 type RavenMcpOperation = "list_tools" | "call_tool" | "list_resources" | "read_resource" | "list_prompts" | "get_prompt"
 
@@ -198,7 +203,7 @@ const DEFAULT_CONFIG: RavenConfig = {
   onDemandMcpServers: DEFAULT_ON_DEMAND_MCP_SERVERS,
   excludeAgents: [],
   excludeTools: [],
-  timeout: 180,
+  timeout: 600,
 }
 
 function parseRavenMd(raw: string): { frontmatter: Record<string, any>; prompt: string } {
@@ -303,32 +308,45 @@ function normalizeToolInfo(value: unknown): OnDemandMcpToolInfo[] | undefined {
   return tools.length ? tools : undefined
 }
 
+function normalizeStringRecord(value: unknown): Record<string, string> | undefined {
+  if (!value || typeof value !== "object") return undefined
+  const entries = Object.entries(value).filter((entry): entry is [string, string] => typeof entry[1] === "string")
+  return entries.length ? Object.fromEntries(entries) : undefined
+}
+
 function normalizeOnDemandMcpServer(value: unknown): OnDemandMcpServer | undefined {
   if (!value || typeof value !== "object") return undefined
   const source = value as Record<string, any>
   const base = {
+    enabled: source.enabled !== false,
+    ...(typeof source.timeout === "number" && source.timeout > 0 ? { timeout: Math.floor(source.timeout) } : {}),
     ...(typeof source.description === "string" && source.description.trim() ? { description: source.description.trim() } : {}),
   }
 
-  if (source.type === "stdio") {
-    if (typeof source.command !== "string" || !source.command.trim()) return undefined
+  if (source.type === "local") {
+    const commandParts = Array.isArray(source.command)
+      ? source.command.filter((arg: unknown): arg is string => typeof arg === "string" && arg.trim())
+      : []
+    if (!commandParts.length) return undefined
+    const environment = normalizeStringRecord(source.environment)
     return {
       ...base,
-      type: "stdio",
-      command: source.command.trim(),
-      ...(Array.isArray(source.args) ? { args: source.args.filter((arg: unknown) => typeof arg === "string") } : {}),
-      ...(source.env && typeof source.env === "object" ? { env: Object.fromEntries(Object.entries(source.env).filter((entry): entry is [string, string] => typeof entry[1] === "string")) } : {}),
+      type: "local",
+      command: commandParts,
+      ...(environment ? { environment } : {}),
       ...(typeof source.cwd === "string" && source.cwd.trim() ? { cwd: source.cwd.trim() } : {}),
     }
   }
 
   if (source.type === "remote" || typeof source.url === "string") {
     if (typeof source.url !== "string" || !source.url.trim()) return undefined
+    const headers = normalizeStringRecord(source.headers)
     return {
       ...base,
       type: "remote",
       url: source.url.trim(),
-      ...(source.headers && typeof source.headers === "object" ? { headers: Object.fromEntries(Object.entries(source.headers).filter((entry): entry is [string, string] => typeof entry[1] === "string")) } : {}),
+      ...(headers ? { headers } : {}),
+      ...(source.oauth === false ? { oauth: false } : source.oauth && typeof source.oauth === "object" ? { oauth: source.oauth } : {}),
     }
   }
 
@@ -476,6 +494,8 @@ export default ((input: PluginInput) => {
   const ravenTaskCalls = new Set<string>()
   const sessionAgents = new Map<string, string>()
   const ravenSessionParents = new Map<string, string>()
+  const ravenErrorWaiters = new Map<string, (error: Error) => void>()
+  const ravenProgressWaiters = new Map<string, () => void>()
   let globalMcpServers: string[] = []
   let duplicateMcpServers: string[] = []
   let updateInfo: { current: string; latest?: string; available: boolean } | undefined
@@ -486,12 +506,13 @@ export default ((input: PluginInput) => {
   let mcpRefreshScheduled = false
   let mcpRefreshPromise: Promise<{ refreshed: string[]; failed: string[] }> | undefined
   let lastNotifiedMcpFailureKey = ""
+  let ravenProviderIssue: string | undefined
 
   resetOnDemandMcpRuntimeStatuses()
 
   function resetOnDemandMcpRuntimeStatuses() {
     let changed = false
-    for (const name of Object.keys(config.onDemandMcpServers ?? {})) {
+    for (const [name] of activeOnDemandMcpEntries()) {
       const metadata = mcpMetadata[name] ?? {}
       if (metadata.status !== "pending" || metadata.lastError || metadata.lastCheckedAt) {
         mcpMetadata[name] = { ...metadata, status: "pending" }
@@ -552,9 +573,26 @@ export default ((input: PluginInput) => {
   }
 
   function rerouteMessage(tool: string, args: any): string {
+    if (ravenProviderIssue) {
+      return `Raven is currently unavailable: ${ravenProviderIssue}
+
+${ravenRecoveryInstructions()}`
+    }
     return `The '${tool}' tool call is blocked by Raven. Your next tool call should be raven_seek(query="${attemptedQuery(tool, args).replace(/"/g, "'")}").`
   }
 
+  function ravenRecoveryInstructions(): string {
+    return `Stop trying Raven-routed tools or MCPs for this request. Inform the user that Raven cannot run until its model/provider is changed or fixed.
+
+Tell the user to switch Raven's model with:
+  /raven model <provider/model>
+
+Example:
+  /raven model openai/gpt-5.5
+
+Then restart opencode for the model change to take effect. If the task can be completed without Raven, continue without routed tools and clearly mention what could not be checked.`
+  }
+
   function routeSummary(): string {
     const tools = config.routeTools?.length ? config.routeTools.join(", ") : "(none)"
     const mcps = globalMcpServers.length ? `${globalMcpServers.join(", ")} (auto-detected)` : "none detected"
@@ -591,8 +629,10 @@ export default ((input: PluginInput) => {
 
   function onDemandMcpGuidance(target: "delegate" | "raven" = "delegate"): string {
     const servers = config.onDemandMcpServers ?? {}
-    const entries = Object.entries(servers).filter(([name]) => onDemandMcpRuntimeStatus(name) === "ready")
+    const activeEntries = activeOnDemandMcpEntries()
+    const entries = activeEntries.filter(([name]) => onDemandMcpRuntimeStatus(name) === "ready")
     if (!Object.keys(servers).length) return "No on-demand MCPs are configured."
+    if (!activeEntries.length) return "No enabled on-demand MCPs are configured."
     if (!entries.length) return "No loaded on-demand MCPs are available."
 
     const detail = config.onDemandMcpDescriptionDetail ?? "full"
@@ -653,6 +693,49 @@ export default ((input: PluginInput) => {
     }
   }
 
+  function providerErrorMessage(error: any): string {
+    const name = String(error?.name ?? "")
+    const data = error?.data && typeof error.data === "object" ? error.data : {}
+    const status = typeof data.statusCode === "number" ? ` HTTP ${data.statusCode}.` : ""
+    const body = typeof data.responseBody === "string" && data.responseBody.trim() ? ` ${truncateText(data.responseBody, 500)}` : ""
+    const message = String(data.message ?? error?.message ?? error ?? "Unknown provider error")
+    return `Raven provider/API error${name ? ` (${name})` : ""}.${status} ${message}${body}`.trim()
+  }
+
+  function waitForRavenProviderError(sessionId: string): Promise<never> {
+    return new Promise((_resolve, reject) => {
+      ravenErrorWaiters.set(sessionId, reject)
+    })
+  }
+
+  function waitForRavenFirstProgress(sessionId: string, ms: number): Promise<never> {
+    return new Promise((_resolve, reject) => {
+      const timer = setTimeout(() => {
+        ravenProgressWaiters.delete(sessionId)
+        reject(new Error(`Raven did not produce an initial response within ${Math.round(ms / 1000)}s. If the Raven provider showed a retry dialog, this is likely an auth/quota/subscription issue. Check the Raven subagent/provider account, or retry after switching Raven to a working model.`))
+      }, ms)
+      ravenProgressWaiters.set(sessionId, () => {
+        clearTimeout(timer)
+        ravenProgressWaiters.delete(sessionId)
+      })
+    })
+  }
+
+  function reportRavenProviderError(sessionId: string, error: any) {
+    const waiter = ravenErrorWaiters.get(sessionId)
+    if (!waiter) return
+    waiter(new Error(providerErrorMessage(error)))
+  }
+
+  function reportRavenProgress(sessionId: string) {
+    ravenProgressWaiters.get(sessionId)?.()
+  }
+
+  function clearRavenWaiters(sessionId: string) {
+    ravenErrorWaiters.delete(sessionId)
+    ravenProgressWaiters.get(sessionId)?.()
+  }
+
   type McpConnection = {
     client: Client
     transport: any
@@ -694,22 +777,29 @@ export default ((input: PluginInput) => {
   }
 
   function getOnDemandMcpServer(serverName: string): [string, OnDemandMcpServer] | undefined {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    const entries = activeOnDemandMcpEntries()
     return entries.find(([name]) => name.toLowerCase() === serverName.toLowerCase())
   }
 
+  function activeOnDemandMcpEntries(): [string, OnDemandMcpServer][] {
+    return Object.entries(config.onDemandMcpServers ?? {}).filter(([, server]) => server.enabled !== false)
+  }
+
   async function connectOnDemandMcp(serverName: string, server: OnDemandMcpServer): Promise<McpConnection> {
-    const timeout = (config.timeout ?? 180) * 1000
+    const timeout = server.timeout ?? (config.timeout ?? 180) * 1000
     const client = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION })
 
-    if (server.type === "stdio") {
-      const env = { ...cleanProcessEnv(), ...resolveStringRecord(server.env) }
+    if (server.type === "local") {
+      const env = { ...cleanProcessEnv(), ...resolveStringRecord(server.environment) }
       const transport = new StdioClientTransport({
-        command: resolveEnvPlaceholders(server.command),
-        args: server.args?.map((arg) => resolveEnvPlaceholders(arg)),
+        command: resolveEnvPlaceholders(server.command[0]),
+        args: server.command.slice(1).map((arg) => resolveEnvPlaceholders(arg)),
         env,
+        stderr: "pipe",
         cwd: server.cwd ? resolveEnvPlaceholders(server.cwd) : undefined,
       })
+      transport.stderr?.on("data", () => {})
+      transport.stderr?.on("error", () => {})
       await withTimeout(client.connect(transport), timeout, `Connecting to ${serverName}`)
       return { client, transport, serverName, lastUsed: Date.now() }
     }
@@ -800,7 +890,7 @@ export default ((input: PluginInput) => {
   }
 
   async function refreshOnDemandMcpDescriptions(force = false, serverName?: string): Promise<{ refreshed: string[]; failed: string[] }> {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
+    const entries = activeOnDemandMcpEntries()
       .filter(([name]) => !serverName || name.toLowerCase() === serverName.toLowerCase())
       .filter(([name]) => {
         const metadata = mcpMetadata[name]
@@ -870,7 +960,7 @@ export default ((input: PluginInput) => {
 
   function onDemandMcpStatusBuckets(): { loaded: string[]; failed: string[]; pending: string[] } {
     const buckets = { loaded: [] as string[], failed: [] as string[], pending: [] as string[] }
-    for (const name of Object.keys(config.onDemandMcpServers ?? {})) {
+    for (const [name] of activeOnDemandMcpEntries()) {
       const status = onDemandMcpRuntimeStatus(name)
       if (status === "ready") buckets.loaded.push(name)
       else if (status === "failed") buckets.failed.push(name)
@@ -880,7 +970,7 @@ export default ((input: PluginInput) => {
   }
 
   function failedOnDemandMcpNames(names?: string[]): string[] {
-    const configured = Object.keys(config.onDemandMcpServers ?? {})
+    const configured = activeOnDemandMcpEntries().map(([name]) => name)
     const wanted = names?.length ? names : configured
     return wanted.filter((name) => configured.includes(name) && onDemandMcpRuntimeStatus(name) === "failed")
   }
@@ -903,8 +993,9 @@ export default ((input: PluginInput) => {
   }
 
   function onDemandMcpStatus(): string {
-    const entries = Object.entries(config.onDemandMcpServers ?? {})
-    if (!entries.length) return "Raven on-demand MCPs: none configured."
+    const entries = activeOnDemandMcpEntries()
+    if (!Object.keys(config.onDemandMcpServers ?? {}).length) return "Raven on-demand MCPs: none configured."
+    if (!entries.length) return "Raven on-demand MCPs: none enabled."
     const buckets = onDemandMcpStatusBuckets()
     const lines = entries.map(([name, server]) => {
       const metadata = mcpMetadata[name]
@@ -920,7 +1011,7 @@ export default ((input: PluginInput) => {
   }
 
   function avoidedMcpSchemaBytes(): number {
-    return Object.keys(config.onDemandMcpServers ?? {}).reduce((sum, name) => {
+    return activeOnDemandMcpEntries().reduce((sum, [name]) => {
       const metadata = mcpMetadata[name]
       if (onDemandMcpRuntimeStatus(name) !== "ready") return sum
       return sum + Math.max(0, metadata?.avoidedSchemaBytes ?? 0)
@@ -1157,7 +1248,7 @@ export default ((input: PluginInput) => {
       globalMcpServers = uniqueStrings(Object.entries(configInput.mcp ?? {})
         .filter(([, value]) => !value || typeof value !== "object" || (value as any).enabled !== false)
         .map(([name]) => name))
-      const onDemandNames = new Set(Object.keys(config.onDemandMcpServers ?? {}).map((name) => name.toLowerCase()))
+      const onDemandNames = new Set(activeOnDemandMcpEntries().map(([name]) => name.toLowerCase()))
       duplicateMcpServers = globalMcpServers.filter((name) => onDemandNames.has(name.toLowerCase()))
 
       // Inject MCP guidance as a startup instruction file (absolute path for npm compat).
@@ -1210,7 +1301,7 @@ export default ((input: PluginInput) => {
         },
         async execute(args, context) {
           const started = Date.now()
-          const timeout = (config.timeout ?? 180) * 1000
+          const timeout = (config.timeout ?? 600) * 1000
           try {
             // Create a Raven session
             const session = await client.session.create({
@@ -1238,55 +1329,76 @@ export default ((input: PluginInput) => {
               appendFileSync(logFile, `${ts} ${sessionId} "${q}"\n`)
             } catch { /* non-fatal */ }
 
-            // Send the query to Raven with timeout
-            const result = await Promise.race([
-              client.session.prompt({
-                path: { id: sessionId },
-                body: {
-                  agent: "raven",
-                  parts: [{ type: "text", text: args.query }],
-                },
-              }),
-              new Promise<never>((_, reject) =>
-                setTimeout(() => reject(new Error(`Raven timed out after ${timeout / 1000}s — session kept: ${sessionId}`)), timeout)
-              ),
-            ])
-
-            const elapsed = ((Date.now() - started) / 1000).toFixed(1)
-
-            // Extract text from the response
-            const parts = (result as any)?.data?.parts ?? []
-            const textParts = parts
-              .filter((p: any) => p.type === "text" && p.text)
-              .map((p: any) => p.text)
-            const output = textParts.join("\n") || "Raven returned no results."
-
-            // Context saved = Raven output/reasoning/cache context - compact answer returned to main session.
-            let savedCandidate = 0
+            // Send the query to Raven with timeout. Provider/API errors are also
+            // surfaced through message.updated events; fail as soon as one lands
+            // so the caller does not wait for the full timeout on quota/auth issues.
+            let timer: ReturnType<typeof setTimeout> | undefined
+            const providerError = waitForRavenProviderError(sessionId)
+            const firstProgress = waitForRavenFirstProgress(sessionId, Math.min(timeout, 30_000))
             try {
-              savedCandidate = await countRavenSavedCandidateBytes(sessionId)
-            } catch { /* best-effort */ }
-            if (savedCandidate <= 0) {
-              for (const part of parts) {
-                if (part.args) savedCandidate += JSON.stringify(part.args).length
-                if (part.content) savedCandidate += typeof part.content === "string" ? part.content.length : JSON.stringify(part.content).length
+              const result = await Promise.race([
+                client.session.prompt({
+                  path: { id: sessionId },
+                  body: {
+                    agent: "raven",
+                    parts: [{ type: "text", text: args.query }],
+                  },
+                }),
+                providerError,
+                firstProgress,
+                new Promise<never>((_, reject) => {
+                  timer = setTimeout(() => reject(new Error(`Raven timed out after ${timeout / 1000}s — session kept: ${sessionId}`)), timeout)
+                }),
+              ])
+              if (timer) clearTimeout(timer)
+              clearRavenWaiters(sessionId)
+
+              const elapsed = ((Date.now() - started) / 1000).toFixed(1)
+
+              // Extract text from the response
+              const parts = (result as any)?.data?.parts ?? []
+              const textParts = parts
+                .filter((p: any) => p.type === "text" && p.text)
+                .map((p: any) => p.text)
+              const output = textParts.join("\n") || "Raven returned no results."
+
+              // Context saved = Raven output/reasoning/cache context - compact answer returned to main session.
+              let savedCandidate = 0
+              try {
+                savedCandidate = await countRavenSavedCandidateBytes(sessionId)
+              } catch { /* best-effort */ }
+              if (savedCandidate <= 0) {
+                for (const part of parts) {
+                  if (part.args) savedCandidate += JSON.stringify(part.args).length
+                  if (part.content) savedCandidate += typeof part.content === "string" ? part.content.length : JSON.stringify(part.content).length
+                }
               }
+              const saved = Math.max(0, savedCandidate - output.length)
+              addBytes(saved)
+              ravenProviderIssue = undefined
+
+              return { title: "Raven Seek", metadata: { sessionId }, output: `${output}\n\n*Raven searched for ${elapsed}s — ${formatBytes(savedCandidate)} handled, ${formatTokens(savedCandidate)} tokens*` }
+            } finally {
+              if (timer) clearTimeout(timer)
+              clearRavenWaiters(sessionId)
             }
-            const saved = Math.max(0, savedCandidate - output.length)
-            addBytes(saved)
-
-            return { title: "Raven Seek", metadata: { sessionId }, output: `${output}\n\n*Raven searched for ${elapsed}s — ${formatBytes(savedCandidate)} handled, ${formatTokens(savedCandidate)} tokens*` }
           } catch (err: any) {
             const elapsed = ((Date.now() - started) / 1000).toFixed(1)
             const msg = String(err?.message ?? err ?? "").toLowerCase()
             const hint =
               /rate.?limit|too many requests|429/i.test(msg) ? "Raven rate limited — wait 30s then retry with a narrower query."
-              : /quota|usage.?limit|billing|insufficient.*(?:credit|balance|quota)/i.test(msg) ? "Raven API quota exhausted — proceed without search, tell user what's missing."
+              : /quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|insufficient.*(?:credit|balance|quota)/i.test(msg) ? "Raven API quota/subscription exhausted — proceed without Raven, tell the user Raven could not run, and mention what information may be missing."
+              : /auth|unauthorized|forbidden|401|403|api key|login/i.test(msg) ? "Raven provider authentication failed — proceed without Raven and tell the user to check the Raven model/provider login or API key."
               : /token|context.?length|too large|too long/i.test(msg) ? "Raven query too large — shorten your query and retry."
               : /model|unavailable|down|not found/i.test(msg) ? "Raven model unavailable — retry later, or proceed without search."
+              : /did not produce an initial response|retry dialog/i.test(msg) ? err.message
               : /timeout|timed.?out|session kept/i.test(msg) ? err.message
               : `Raven search failed. Proceed without search — note gaps for the user. [${err.message || err}]`
-            return { title: "Raven Seek", output: `${hint}\n\n*Attempt took ${elapsed}s*` }
+            if (/quota|usage.?limit|usage exceeded|free usage|subscribe to go|subscription|billing|auth|unauthorized|forbidden|401|403|api key|login|model|unavailable|down|not found|did not produce an initial response|retry dialog/i.test(msg)) {
+              ravenProviderIssue = hint
+            }
+            const recovery = ravenProviderIssue ? `\n\n${ravenRecoveryInstructions()}` : ""
+            return { title: "Raven Seek", output: `${hint}${recovery}\n\n*Attempt took ${elapsed}s*` }
           }
         },
       }),
@@ -1304,7 +1416,7 @@ export default ((input: PluginInput) => {
           }
 
           const operation = args.operation as RavenMcpOperation
-          const timeout = (config.timeout ?? 180) * 1000
+          const timeout = (config.timeout ?? 600) * 1000
           let connected = false
           try {
             const connection = await getMcpConnection(context.sessionID, args.server)
@@ -1387,6 +1499,37 @@ export default ((input: PluginInput) => {
       if (evt?.type === "session.created" && evt?.properties?.parentID) {
         ravenSessionParents.set(evt.properties.parentID, evt.properties.id)
       }
+      if (evt?.type === "message.updated") {
+        const info = evt.properties?.info
+        if (info?.role === "assistant" && info?.sessionID && info.error && ravenSessions.has(info.sessionID)) {
+          reportRavenProviderError(info.sessionID, info.error)
+        }
+      }
+      if (evt?.type === "message.part.updated") {
+        const part = evt.properties?.part
+        if (part?.sessionID && ravenSessions.has(part.sessionID)) {
+          if (part.type === "retry" && part.error) {
+            reportRavenProviderError(part.sessionID, part.error)
+          } else {
+            reportRavenProgress(part.sessionID)
+          }
+        }
+      }
+      if (evt?.type === "session.status") {
+        const sessionId = evt.properties?.sessionID
+        const status = evt.properties?.status
+        if (sessionId && ravenSessions.has(sessionId)) {
+          if (status?.type === "retry") {
+            reportRavenProviderError(sessionId, { name: "RetryError", data: { message: status.message } })
+          }
+        }
+      }
+      if (evt?.type === "session.error") {
+        const sessionId = evt.properties?.sessionID
+        if (sessionId && evt.properties?.error && ravenSessions.has(sessionId)) {
+          reportRavenProviderError(sessionId, evt.properties.error)
+        }
+      }
 
       if (updateToastPending) {
         updateToastPending = false
@@ -1487,6 +1630,7 @@ export default ((input: PluginInput) => {
         } else {
           config.model = model
           saveConfig(config)
+          ravenProviderIssue = undefined
           output.parts.push({ type: "text", text: `Raven model set to: ${model}\nRestart opencode for the change to take effect.` })
         }
       } else if (arg.startsWith("effort ")) {
@@ -1501,7 +1645,7 @@ export default ((input: PluginInput) => {
       } else if (arg.startsWith("timeout ")) {
         const secs = parseInt(raw.slice(8).trim(), 10)
         if (!secs || secs < 10) {
-          output.parts.push({ type: "text", text: `Usage: /raven timeout <seconds>\nMust be at least 10. Current: ${config.timeout ?? 180}s` })
+          output.parts.push({ type: "text", text: `Usage: /raven timeout <seconds>\nMust be at least 10. Current: ${config.timeout ?? 600}s` })
         } else {
           config.timeout = secs
           saveConfig(config)
@@ -1511,7 +1655,8 @@ export default ((input: PluginInput) => {
         const enabled = config.enabled ? "enabled" : "disabled"
         const model = config.model || fm.model || "(default)"
         const effort = config.reasoning_effort || fm.reasoning_effort || "(default)"
-        const timeout = config.timeout ?? 180
+        const timeout = config.timeout ?? 600
+        const providerIssue = ravenProviderIssue ? `\nProvider issue: ${ravenProviderIssue}` : ""
         let update = "Update: unable to check npm."
         try {
           const info = await getUpdateInfo()
@@ -1519,7 +1664,7 @@ export default ((input: PluginInput) => {
             ? `Update: ${info.latest} available. Run /raven update, then restart opencode.`
             : `Update: up to date${info.latest ? ` (latest ${info.latest})` : ""}.`
         } catch { /* keep fallback */ }
-        output.parts.push({ type: "text", text: `Raven is ${enabled}. Version: ${PACKAGE_VERSION}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\n${update}\n\n${routeSummary()}\n\n${mcpSummary()}\n\n${statsText()}\n\nRun /raven help for commands.` })
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Version: ${PACKAGE_VERSION}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s${providerIssue}\n${update}\n\n${routeSummary()}\n\n${mcpSummary()}\n\n${statsText()}\n\nRun /raven help for commands.` })
       }
     },
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-raven",
-  "version": "2.1.1",
-  "description": "Raven is a context firewall for OpenCode. It routes noisy search, docs, web, GitHub, and MCP calls through a free focused agent before they hit your main model, saving cost and context!",
+  "version": "2.1.3",
+  "description": "Ready-to-use search tools and optional on-demand MCPs for OpenCode, routed through Raven to save your main model's context and cost.",
   "main": "./index.ts",
   "exports": {
     ".": "./index.ts"