opencode-raven 2.1.3 → 2.1.5

package/README.md

@@ -1,5 +1,9 @@
 # opencode-raven
 
+[![npm version](https://img.shields.io/npm/v/opencode-raven.svg)](https://www.npmjs.com/package/opencode-raven)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-raven.svg)](https://www.npmjs.com/package/opencode-raven)
+[![license](https://img.shields.io/npm/l/opencode-raven.svg)](LICENSE)
+
 <table>
 <tr>
 <td width="40%"><img src="Raven.png" alt="Raven" width="100%" /></td>
@@ -285,10 +289,10 @@ MCPs configured directly in OpenCode `opencode.jsonc` still load globally and ma
 | `chat.message` | Tracks agent to session mapping for allowlist and Raven exclusion. |
 | `event` | Shows startup update and MCP failure notifications after the TUI event stream is ready. |
 | `command.execute.before` | Handles `/raven help`, routing commands, MCP commands, update checks, model settings, timeout, and stats. |
-| `tool.execute.before` | Hard-blocks configured tools/MCPs for non-Raven, non-excluded agents. Error output gives the next `raven_seek(query="...")` call. Injects dynamic `<raven_guidance>` with configured routes into subagent prompts. |
+| `tool.execute.before` | Hard-blocks configured tools/MCPs for non-Raven, non-excluded agents. Error output gives the next `raven_seek(query="...")` call or recovery instructions if Raven's provider is unavailable. Tracks direct Raven subagent calls for stats. |
 | `tool.execute.after` | Tracks direct `@Raven` calls for context-saved stats. |
 
-Every non-Raven, non-excluded subagent gets `<raven_guidance>` injected into its prompt at spawn time. The injected guidance includes `routeTools`, auto-detected global MCP prefixes, `routeToolKeywords`, and on-demand MCP capabilities.
+Raven routing guidance is loaded through OpenCode instructions at startup. Subagent prompts are not modified; if a non-Raven agent calls a routed tool, Raven blocks it and returns the exact `raven_seek(query="...")` call to use.
 
 ## Agent Capabilities
 
@@ -308,6 +312,6 @@ Raven itself has access to these tools, blocked for other agents when configured
 
 Raven returns compact findings: answer, sources, relevant details, recommended next step, and uncertainty.
 
-## License
+## Disclaimer
 
-MIT
+opencode-raven is not built by the OpenCode team and is not affiliated with OpenCode in any way.

package/index.ts

@@ -475,12 +475,12 @@ export default ((input: PluginInput) => {
     } catch { /* non-fatal: generated metadata can be refreshed */ }
   }
 
-  function saveDynamicGuidance() {
-    try {
-      mkdirSync(ravenConfigDir, { recursive: true })
-      writeFileSync(dynamicGuidanceFile, `## Raven on-demand MCP capabilities\n\n${onDemandMcpGuidance("delegate")}\n`, "utf-8")
-    } catch { /* non-fatal: guidance still exists in tool/subagent paths */ }
-  }
+  function saveDynamicGuidance() {
+    try {
+      mkdirSync(ravenConfigDir, { recursive: true })
+      writeFileSync(dynamicGuidanceFile, `## Raven on-demand MCP capabilities\n\n${onDemandMcpGuidance("delegate", dynamicGuidanceMcpOrder())}\n`, "utf-8")
+    } catch { /* non-fatal: guidance still exists in tool/subagent paths */ }
+  }
 
   function cleanupOldRootFiles() {
     try {
@@ -531,13 +531,6 @@ export default ((input: PluginInput) => {
     return config.excludeAgents.some((a) => a.toLowerCase() === lower)
   }
 
-  function ravenGuidance(): string {
-    const tools = config.routeTools?.length ? config.routeTools.join(", ") : "none"
-    const mcps = globalMcpServers.length ? globalMcpServers.map((server) => `${server}_*`).join(", ") : "none"
-    const keywords = config.routeToolKeywords?.length ? config.routeToolKeywords.join(", ") : "none"
-    return `Some tools/MCPs are routed through Raven to save context. Routed tools: ${tools}. Auto-routed global MCP prefixes: ${mcps}. Routed tool-name keywords: ${keywords}. ${onDemandMcpGuidance("delegate")} If one is blocked, your next tool call should be raven_seek(query="<same request>"). Include the original tool/MCP name and relevant arguments.`
-  }
-
   function isRouteConfigured(toolName: string): boolean {
     const tool = toolName.toLowerCase()
     if (NEVER_ROUTE_TOOLS.has(tool)) return false
@@ -622,32 +615,73 @@ Then restart opencode for the model change to take effect. If the task can be co
     return extra ? `${prompt}\n\nAdditional user instructions:\n${extra}` : prompt
   }
 
-  function truncateText(value: unknown, max = 240): string {
-    const text = String(value ?? "").replace(/\s+/g, " ").trim()
-    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text
-  }
-
-  function onDemandMcpGuidance(target: "delegate" | "raven" = "delegate"): string {
-    const servers = config.onDemandMcpServers ?? {}
-    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"
-    const lines = entries.map(([name, server]) => {
-      const metadata = mcpMetadata[name] ?? {}
-      const userDescription = truncateText(server.description, 220)
-      const generated = truncateText(metadata.autoGeneratedDescription, 260)
-      const parts = [userDescription, generated ? `Discovered capabilities: ${generated}` : ""].filter(Boolean)
-      const summary = parts.length ? parts.join(" ") : "Description discovery pending."
-      if (detail === "minimized" || !metadata.autoGeneratedTools?.length) return `- ${name}: ${summary}`
-      const tools = metadata.autoGeneratedTools
-        .map((item) => `${item.name}${item.description ? ` - ${truncateText(item.description, 140)}` : ""}`)
-        .join("; ")
-      return `- ${name}: ${summary} Tools: ${tools}`
-    })
+  function compactText(value: unknown): string {
+    return String(value ?? "").replace(/\s+/g, " ").trim()
+  }
+
+  function truncateText(value: unknown, max = 240): string {
+    const text = compactText(value)
+    return text.length > max ? `${text.slice(0, Math.max(0, max - 3))}...` : text
+  }
+
+  function dynamicGuidanceMcpOrder(): string[] | undefined {
+    try {
+      if (!existsSync(dynamicGuidanceFile)) return undefined
+      const names: string[] = []
+      for (const line of readFileSync(dynamicGuidanceFile, "utf-8").split("\n")) {
+        const name = line.match(/^-\s+([^:]+):/)?.[1]?.trim()
+        if (name && !names.includes(name)) names.push(name)
+      }
+      return names
+    } catch {
+      return undefined
+    }
+  }
+
+  function orderedOnDemandMcpEntries(entries: [string, OnDemandMcpServer][], preferredOrder?: string[]): [string, OnDemandMcpServer][] {
+    if (!preferredOrder?.length) return entries
+    const order = new Map(preferredOrder.map((name, index) => [name.toLowerCase(), index]))
+    const existing = entries
+      .filter(([name]) => order.has(name.toLowerCase()))
+      .sort(([left], [right]) => order.get(left.toLowerCase())! - order.get(right.toLowerCase())!)
+    const added = entries.filter(([name]) => !order.has(name.toLowerCase()))
+    return [...existing, ...added]
+  }
+
+  function fullGuidanceText(value: unknown): string {
+    return compactText(value)
+  }
+
+  function firstSentenceText(value: unknown): string {
+    const text = compactText(value)
+    const period = text.indexOf(".")
+    return period === -1 ? text : text.slice(0, period + 1)
+  }
+
+  function onDemandMcpGuidance(target: "delegate" | "raven" = "delegate", preferredOrder?: string[]): string {
+    const servers = config.onDemandMcpServers ?? {}
+    const activeEntries = activeOnDemandMcpEntries()
+    const entries = orderedOnDemandMcpEntries(
+      activeEntries.filter(([name]) => onDemandMcpRuntimeStatus(name) === "ready"),
+      preferredOrder,
+    )
+    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"
+    const lines = entries.map(([name, server]) => {
+      const metadata = mcpMetadata[name] ?? {}
+      const userDescription = firstSentenceText(server.description)
+      const generated = firstSentenceText(metadata.autoGeneratedDescription)
+      const parts = [userDescription, generated ? `Discovered capabilities: ${generated}` : ""].filter(Boolean)
+      const summary = parts.length ? parts.join(" ") : "Description discovery pending."
+      if (detail === "minimized" || !metadata.autoGeneratedTools?.length) return `- ${name}: ${summary}`
+      const tools = metadata.autoGeneratedTools
+        .map((item) => `${item.name}${item.description ? ` - ${firstSentenceText(item.description)}` : ""}`)
+        .join("; ")
+      return `- ${name}: ${summary} Tools: ${tools}`
+    })
     if (target === "raven") {
       return `Raven can handle these on-demand MCP capabilities through raven_mcp:\n${lines.join("\n")}`
     }
@@ -870,11 +904,11 @@ Then restart opencode for the model change to take effect. If the task can be co
 
   function generatedToolsFromMcpTools(tools: any[]): OnDemandMcpToolInfo[] {
     return tools
-      .filter((item) => item?.name)
-      .map((item) => ({
-        name: String(item.name),
-        ...(item.description ? { description: truncateText(item.description, 500) } : {}),
-      }))
+      .filter((item) => item?.name)
+      .map((item) => ({
+        name: String(item.name),
+        ...(item.description ? { description: compactText(item.description) } : {}),
+      }))
   }
 
   function estimateAvoidedMcpSchemaBytes(tools: any[]): number {
@@ -883,11 +917,11 @@ Then restart opencode for the model change to take effect. If the task can be co
   }
 
   function synthesizeMcpDescription(serverName: string, tools: OnDemandMcpToolInfo[]): string {
-    if (!tools.length) return `${serverName} exposes on-demand MCP capabilities. Use list_tools for available operations.`
-    const descriptions = tools.map((item) => item.description || item.name).filter(Boolean)
-    const joined = descriptions.slice(0, 6).join("; ")
-    return truncateText(`${serverName} provides on-demand MCP tools for ${joined}.`, 300)
-  }
+    if (!tools.length) return `${serverName} exposes on-demand MCP capabilities. Use list_tools for available operations.`
+    const descriptions = tools.map((item) => item.description || item.name).filter(Boolean)
+    const joined = descriptions.slice(0, 6).join("; ")
+    return compactText(`${serverName} provides on-demand MCP tools for ${joined}.`)
+  }
 
   async function refreshOnDemandMcpDescriptions(force = false, serverName?: string): Promise<{ refreshed: string[]; failed: string[] }> {
     const entries = activeOnDemandMcpEntries()
@@ -1682,18 +1716,8 @@ Then restart opencode for the model change to take effect. If the task can be co
       if (isExcluded(sessionAgents.get(input.sessionID))) return
       if (config.excludeTools?.some((name) => name.toLowerCase() === input.tool.toLowerCase())) return
 
-      // ── Subagent prompt injection: inject Raven guidance into every subagent ──
-      if ((input.tool === "task" || input.tool === "subtask") && output.args) {
-        const subagentType = input.tool === "task" ? (output.args.subagent_type ?? "") : ""
-        if (subagentType === "raven") {
-          ravenTaskCalls.add(input.callID)
-        }
-        if (subagentType !== "raven" && !isExcluded(subagentType)) {
-          const field = ["prompt", "description", "request", "objective", "query"].find(
-            (f) => f in output.args
-          ) ?? "prompt"
-          output.args[field] = `${output.args[field] ?? ""}\n\n<raven_guidance>\n${ravenGuidance()}\n</raven_guidance>`
-        }
+      if (input.tool === "task" && output.args?.subagent_type === "raven") {
+        ravenTaskCalls.add(input.callID)
       }
 
       // ── Block routed tools/MCPs for non-Raven agents ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-raven",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "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": {