opencode-raven 1.2.1 → 1.2.3

package/README.md

@@ -5,7 +5,7 @@
 <td><img src="Raven.png" alt="Raven" width="768" /></td>
 <td>
 <strong>Search-first subagent for <a href="https://opencode.ai">opencode</a></strong><br/>
-Intercepts search tool calls and routes them to a hidden Raven agent with Context7, Exa AI, and Grep.app MCPs.
+Intercepts search tool calls and routes them to a Raven agent with full local filesystem access plus Context7, Exa AI, and Grep.app MCPs.
 </td>
 </tr>
 </table>
@@ -16,7 +16,7 @@ Search is the most common thing agents do — and the most wasteful. Every searc
 
 1. **Cost** — Use a free model like `opencode/deepseek-v4-flash-free` for all search, saving your expensive model's context for actual work.
 2. **Reliability** — Hard-enforced interception. Other plugins suggest delegation; Raven *blocks* search tools for non-Raven agents and redirects them. No more agents ignoring your instructions and searching directly.
-3. **Simplicity** — One plugin, one agent, auto-configured. No bundled agents or features you don't need. Works with any agent or workflow. Just add it to `opencode.jsonc` and restart.
+3. **Simplicity** — One plugin, one agent, auto-configured. No bundled agents or features you don't need. Call Raven directly with `@Raven` or let agents use `raven_seek`. Works with any agent or workflow. Just add it to `opencode.jsonc` and restart.
 
 ## Install
 
@@ -40,18 +40,23 @@ Restart opencode.
 
 | Command | Action |
 |---------|--------|
-| `/raven` | Show status — enabled/disabled, current model, reasoning effort |
+| `/raven` | Show status — enabled/disabled, model, reasoning effort, timeout |
 | `/raven on` | Enable search tool redirection (default) |
 | `/raven off` | Disable interception — all agents can use search tools directly |
 | `/raven model <name>` | Change Raven's model (requires restart) |
 | `/raven effort <value>` | Change Raven's reasoning effort (requires restart) |
-| `/raven stats` | Show blocked calls, context saved (session + global) |
+| `/raven timeout <seconds>` | Change raven_seek timeout (min 10s, takes effect immediately) |
+| `/raven stats` | Show context processed (session + all-time, bytes + tokens) |
 
 Config persists across restarts in `~/.config/opencode/raven-config.json` (global, shared across all projects). Auto-created on first run.
 
+## Direct access
+
+You can call Raven directly with `@Raven` in any opencode chat. The Raven agent runs with full filesystem and MCP access — no permission prompts.
+
 ## raven_seek
 
-When search tools are blocked, agents use **`raven_seek`** — a tool that creates a hidden Raven session, runs the search, and returns compact results:
+When search tools are blocked, agents use **`raven_seek`** — a unified tool that handles ALL search types (local codebase, web, docs, GitHub examples). Output includes elapsed time and tokens processed.
 
 ```
 raven_seek(query: "how to use useEffect cleanup")
@@ -71,7 +76,8 @@ Located at `~/.config/opencode/raven-config.json`. Auto-created on first run. Ed
   "model": "opencode/deepseek-v4-flash-free",
   "reasoning_effort": "low",
   "excludeAgents": [],
-  "excludeTools": []
+  "excludeTools": [],
+  "timeout": 180
 }
 ```
 
@@ -82,7 +88,8 @@ Located at `~/.config/opencode/raven-config.json`. Auto-created on first run. Ed
 | `reasoning_effort` | *(from Raven.md)* | Override Raven's reasoning effort (e.g. `"low"`, `"medium"`, `"high"`) |
 | `excludeAgents` | `[]` | Agents that bypass search tool blocking (case-insensitive). e.g. `["librarian", "explorer"]` |
 | `excludeTools` | `[]` | Tools that never get blocked. e.g. `["glob", "webfetch"]` |
-| `stats` | *(auto)* | Global blocked call count and context saved. Managed automatically. |
+| `timeout` | `180` | Max seconds for a `raven_seek` call. On timeout the session is kept for inspection. |
+| `stats` | *(auto)* | Session + global context processed by Raven (bytes + tokens). Managed automatically. |
 
 ### MCP servers
 
@@ -124,10 +131,10 @@ To disable an MCP entirely:
 | Hook | What it does |
 |------|--------------|
 | `config` | Registers Raven agent, adds Context7/Exa/Grep.app MCPs, loads MCP guidance |
-| `tool` | Registers `raven_seek` — hidden Raven sessions with error recovery for API failures |
+| `tool` | Registers `raven_seek` — creates Raven sessions with timeout, error recovery, and timing. Tracks context processed for stats. |
 | `chat.message` | Tracks agent ↔ session mapping for allowlist and Raven exclusion |
-| `command.execute.before` | Handles `/raven on\|off\|model\|effort\|status` |
-| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents. Injects `<raven_guidance>` into subagent prompts. Throttled: full message once per session, silent after. Tracks blocked calls + context saved. |
+| `command.execute.before` | Handles `/raven on\|off\|model\|effort\|timeout\|stats\|status` |
+| `tool.execute.before` | Blocks search tools for non-Raven, non-excluded agents (respects `excludeTools`). Injects `<raven_guidance>` into subagent prompts. |
 
 ### Blocked tools (redirected except for Raven and any agents in `excludeAgents`)
 
@@ -135,7 +142,7 @@ To disable an MCP entirely:
 
 | Tool | Source |
 |------|--------|
-| `grep`, `glob`, `webfetch`, `fetch` | Built-in |
+| `grep`, `glob`, `webfetch`, `fetch`, `websearch` | Built-in |
 | `websearch_web_search_exa` | WebSearch MCP |
 | `context7_resolve-library-id`, `context7_query-docs` | Context7 MCP |
 | `exa_web_search_exa`, `exa_web_fetch_exa`, `exa_web_search_advanced_exa` | Exa AI MCP |
@@ -150,6 +157,7 @@ To disable an MCP entirely:
 |---------|----------|
 | Content search | `rg`, `grep`, `egrep`, `fgrep`, `git grep`, `ack`, `ag`, `findstr`, `Select-String` |
 | Filesystem exploration | `Get-ChildItem`, `gci`, `find -name`, `find -type`, `ls -R`, `dir /s` |
+| Shell bypass | `cmd /c dir`, `cmd /c findstr`, `cmd /c find`, `cmd /c where`, `cmd /c tree` |
 
 **Unrestricted**: `read`, `task`, `subtask`, `raven_seek`, and non-search `bash` commands.
 
@@ -164,7 +172,8 @@ Raven itself has access to these tools (blocked for other agents by the plugin):
 | Tool / MCP | Purpose |
 |------------|---------|
 | `read`, `glob`, `grep`, `list` | Local codebase inspection |
-| `bash` (`rg`, `grep`, `git grep`) | Local search commands |
+| `bash` (all commands) | Full local shell access (`rg`, `grep`, `dir`, `ls`, `Get-ChildItem`, `find`, etc.) |
+| `external_directory` | Allowed — no permission prompts when accessing paths outside the workspace |
 | Context7 | Library/framework/SDK/API docs |
 | Exa AI | Web search, news, pages, products |
 | Grep.app | Public GitHub examples |

package/Raven.md

@@ -1,7 +1,7 @@
 ---
 description: Search-only agent for web, docs, code, examples, and Unity project inspection.
 mode: subagent
-hidden: true
+hidden: false
 model: opencode/deepseek-v4-flash-free
 reasoning_effort: low
 permission:
@@ -10,14 +10,9 @@ permission:
   grep: allow
   list: allow
   edit: deny
-  bash:
-
-    "rg *": allow
-    "grep *": allow
-    "git grep *": allow
-    "*": deny
-
+  bash: allow
   task: deny
+  external_directory: allow
 ---
 
 You are Raven.

package/index.ts

@@ -1,8 +1,8 @@
 import type { Plugin, PluginInput } from "@opencode-ai/plugin"
 import { tool } from "@opencode-ai/plugin"
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs"
+import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } from "node:fs"
 import { join } from "node:path"
-import { homedir } from "node:os"
+import { homedir, tmpdir } from "node:os"
 
 // ── Resolve paths relative to this package (works in node_modules/) ──
 const PKG_DIR = import.meta.dirname!
@@ -17,6 +17,7 @@ const SEARCH_TOOLS = [
   "glob",
   "webfetch",
   "fetch",
+  "websearch",
   // WebSearch MCP
   "websearch_web_search_exa",
   // Context7 MCP
@@ -39,7 +40,7 @@ const SEARCH_TOOLS = [
 ]
 
 // ── Bash commands that look like search workarounds ──
-const SEARCH_BASH_RE = /\b(rg|ripgrep|grep|egrep|fgrep|git\s+grep|ack|ag\b|findstr|Select-String|Get-ChildItem|gci\b|dir\b\s+[/-][sS]|ls\b\s+-[rR]|find\b\s+.*-name|find\b\s+.*-type)\b/
+const SEARCH_BASH_RE = /\b(rg|ripgrep|grep|egrep|fgrep|git\s+grep|ack|ag\b|findstr|Select-String|Get-ChildItem|gci\b|dir\b\s+[/-][sS]|ls\b\s+-[rR]|find\b\s+.*-name|find\b\s+.*-type)\b/i
 
 // Strip quoted content to avoid false positives (e.g. echo "use grep here")
 function stripHeredocs(cmd: string): string {
@@ -54,9 +55,11 @@ function stripQuotedContent(cmd: string): string {
 
 function isSearchBash(tool: string, args: any): boolean {
   if (tool !== "bash") return false
-  const cmd = stripQuotedContent(String(args?.command ?? ""))
+  const raw = String(args?.command ?? "")
+  const cmd = stripQuotedContent(raw)
   const desc = stripQuotedContent(String(args?.description ?? ""))
-  return SEARCH_BASH_RE.test(cmd) || SEARCH_BASH_RE.test(desc)
+  const lower = raw.toLowerCase().trim()
+  return SEARCH_BASH_RE.test(cmd) || SEARCH_BASH_RE.test(desc) || /^cmd\s+\/c\s+"?(dir|findstr|find|where|tree)\b/.test(lower)
 }
 
 // ── Config file shape ──
@@ -66,7 +69,8 @@ interface RavenConfig {
   reasoning_effort?: string
   excludeAgents?: string[]
   excludeTools?: string[]
-  stats?: { blocked: number; bytesSaved: number; tools: Record<string, number> }
+  timeout?: number
+  stats?: { bytes: number }
 }
 
 // ── Parse Raven.md frontmatter ──
@@ -79,6 +83,7 @@ const DEFAULT_CONFIG: RavenConfig = {
   reasoning_effort: fm.reasoning_effort,
   excludeAgents: [],
   excludeTools: [],
+  timeout: 180,
 }
 
 function parseRavenMd(raw: string): { frontmatter: Record<string, any>; prompt: string } {
@@ -134,6 +139,8 @@ function parseYaml(yaml: string): Record<string, any> {
         value = true
       } else if (value === "false") {
         value = false
+      } else if (/^\d+$/.test(value)) {
+        value = parseInt(value, 10)
       }
       current[key] = value
     }
@@ -174,6 +181,7 @@ export default ((input: PluginInput) => {
           reasoning_effort: raw.reasoning_effort,
           excludeAgents: Array.isArray(raw.excludeAgents) ? raw.excludeAgents : [],
           excludeTools: Array.isArray(raw.excludeTools) ? raw.excludeTools : [],
+          timeout: typeof raw.timeout === "number" ? raw.timeout : undefined,
           stats: raw.stats || undefined,
         }
       }
@@ -201,55 +209,16 @@ export default ((input: PluginInput) => {
     return config.excludeAgents.some((a) => a.toLowerCase() === lower)
   }
 
-  // Throttle: show the full error message once per session, then silent
-  const throttledSessions = new Set<string>()
-  const REROUTE_MSG = "Search tools are blocked. Use raven_seek(query=\"...\") to search through Raven."
-
-  // ── Session stats: track blocked calls + estimated context saved ──
-  const sessionStats = new Map<string, { blocked: number; tools: Map<string, number>; bytesSaved: number }>()
-  const globalStats = { blocked: 0, tools: new Map<string, number>(), bytesSaved: 0 }
-  // Restore global stats from config
-  if (config.stats) {
-    globalStats.blocked = config.stats.blocked ?? 0
-    globalStats.bytesSaved = config.stats.bytesSaved ?? 0
-    for (const [t, n] of Object.entries(config.stats.tools ?? {})) {
-      globalStats.tools.set(t, n)
-    }
-  }
+  const REROUTE_MSG = "Search tools are blocked. Use raven_seek(query=\"...\") for all searches — local codebase, web, docs, and GitHub examples."
 
-  function getBytesEstimate(tool: string): number {
-    const ESTIMATES: Record<string, number> = {
-      grep: 2000, glob: 2000,
-      webfetch: 16000, fetch: 16000,
-      websearch_web_search_exa: 8000,
-      context7_resolve_library_id: 1000, context7_query_docs: 4000,
-      exa_web_search_exa: 8000, exa_web_fetch_exa: 16000,
-      exa_web_search_advanced_exa: 8000, exa_company_research_exa: 8000,
-      exa_crawling_exa: 12000, exa_people_search_exa: 6000,
-      exa_linkedin_search_exa: 6000, exa_get_code_context_exa: 4000,
-      exa_deep_researcher_start: 8000, exa_deep_researcher_check: 2000,
-      exa_deep_search_exa: 8000,
-      grep_app_searchGitHub: 4000,
-    }
-    return ESTIMATES[tool] ?? 2000 // default for bash search / unknown
-  }
+  // ── Context processed by raven_seek ──
+  let sessionBytes = 0
+  let totalBytes = config.stats?.bytes ?? 0
 
-  function trackBlock(sessionID: string, tool: string) {
-    // Session stats
-    let stats = sessionStats.get(sessionID)
-    if (!stats) {
-      stats = { blocked: 0, tools: new Map(), bytesSaved: 0 }
-      sessionStats.set(sessionID, stats)
-    }
-    stats.blocked++
-    stats.tools.set(tool, (stats.tools.get(tool) ?? 0) + 1)
-    stats.bytesSaved += getBytesEstimate(tool)
-    // Global stats
-    globalStats.blocked++
-    globalStats.tools.set(tool, (globalStats.tools.get(tool) ?? 0) + 1)
-    globalStats.bytesSaved += getBytesEstimate(tool)
-    // Persist to config
-    config.stats = { blocked: globalStats.blocked, bytesSaved: globalStats.bytesSaved, tools: Object.fromEntries(globalStats.tools) }
+  function addBytes(bytes: number) {
+    sessionBytes += bytes
+    totalBytes += bytes
+    config.stats = { bytes: totalBytes }
     saveConfig(config)
   }
 
@@ -312,11 +281,13 @@ export default ((input: PluginInput) => {
     // Register raven_seek tool — lets agents with task:false still search through Raven
     tool: {
       "raven_seek": tool({
-        description: "Fallback search tool — use only when task delegation to Raven (subagent_type=\"raven\") is unavailable. Raven has access to Context7, Exa AI, and Grep.app for web search, docs lookup, and GitHub examples.",
+        description: "Unified search tool — use only when task delegation to Raven (subagent_type=\"raven\") is unavailable. Handles ALL searches: local codebase, web, docs, and GitHub examples via Context7, Exa AI, and Grep.app.",
         args: {
           query: tool.schema.string().describe("What to search for — be specific about what you need (docs, code examples, web info, etc.)"),
         },
         async execute(args, context) {
+          const started = Date.now()
+          const timeout = (config.timeout ?? 180) * 1000
           try {
             // Create a Raven session
             const session = await client.session.create({
@@ -328,14 +299,29 @@ export default ((input: PluginInput) => {
               return { title: "Raven Seek", output: "Failed to create Raven session." }
             }
 
-            // Send the query to Raven
-            const result = await client.session.prompt({
-              path: { id: sessionId },
-              body: {
-                agent: "raven",
-                parts: [{ type: "text", text: args.query }],
-              },
-            })
+            // Log session for debugging
+            try {
+              const logFile = join(tmpdir(), "raven-sessions.log")
+              const ts = new Date().toISOString()
+              const q = String(args.query).slice(0, 100)
+              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 ?? []
@@ -344,22 +330,21 @@ export default ((input: PluginInput) => {
               .map((p: any) => p.text)
             const output = textParts.join("\n") || "Raven returned no results."
 
-            // Clean up the session
-            try {
-              await client.session.delete({ path: { id: sessionId } })
-            } catch { /* non-fatal */ }
+            // Track context saved
+            addBytes(output.length)
 
-            return { title: "Raven Seek", output }
+            return { title: "Raven Seek", output: `${output}\n\n*Raven searched for ${elapsed}s — ${formatBytes(output.length)}, ~${formatTokens(output.length)} 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."
               : /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."
-              : /timeout|timed.?out|econnrefused/i.test(msg) ? "Raven timed out — retry with a narrower query."
+              : /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 }
+            return { title: "Raven Seek", output: `${hint}\n\n*Attempt took ${elapsed}s*` }
           }
         },
       }),
@@ -375,7 +360,7 @@ export default ((input: PluginInput) => {
       }
     },
 
-    // /raven on|off|model <name>|status
+    // /raven on|off|model <name>|effort <value>|timeout <seconds>|stats|status
     "command.execute.before"(input: any, output: any) {
       if (input.command !== "raven") return
       output.parts.length = 0
@@ -391,14 +376,7 @@ export default ((input: PluginInput) => {
         saveConfig(config)
         output.parts.push({ type: "text", text: "Raven search interception disabled. All agents can use search tools directly." })
       } else if (arg === "stats") {
-        const session = sessionStats.get(input.sessionID)
-        const sessionStr = !session || session.blocked === 0
-          ? "  No blocks this session."
-          : `  Session: ${session.blocked} blocked, ~${formatBytes(session.bytesSaved)} (~${formatTokens(session.bytesSaved)} tokens)`
-        const globalStr = globalStats.blocked === 0
-          ? "  Global: no blocks yet."
-          : `  Global: ${globalStats.blocked} blocked, ~${formatBytes(globalStats.bytesSaved)} (~${formatTokens(globalStats.bytesSaved)} tokens)`
-        output.parts.push({ type: "text", text: `Raven stats:\n${sessionStr}\n${globalStr}` })
+        output.parts.push({ type: "text", text: `Raven context processed:\n  This session: ${formatBytes(sessionBytes)} (~${formatTokens(sessionBytes)} tokens)\n  All time: ${formatBytes(totalBytes)} (~${formatTokens(totalBytes)} tokens)` })
       } else if (arg.startsWith("model ")) {
         const model = raw.slice(6).trim()
         if (!model) {
@@ -417,11 +395,21 @@ export default ((input: PluginInput) => {
           saveConfig(config)
           output.parts.push({ type: "text", text: `Raven reasoning effort set to: ${effort}\nRestart opencode for the change to take effect.` })
         }
+      } 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` })
+        } else {
+          config.timeout = secs
+          saveConfig(config)
+          output.parts.push({ type: "text", text: `Raven timeout set to ${secs}s. Takes effect immediately.` })
+        }
       } else {
         const enabled = config.enabled ? "enabled" : "disabled"
         const model = config.model || fm.model || "(default)"
         const effort = config.reasoning_effort || fm.reasoning_effort || "(default)"
-        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}. Reasoning: ${effort}\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven stats   — show blocked calls and context saved` })
+        const timeout = config.timeout ?? 180
+        output.parts.push({ type: "text", text: `Raven is ${enabled}. Model: ${model}. Reasoning: ${effort}. Timeout: ${timeout}s\n\nCommands:\n  /raven on      — enable search interception\n  /raven off     — disable search interception\n  /raven model <name> — change Raven's model (requires restart)\n  /raven effort <value> — change Raven's reasoning effort (requires restart)\n  /raven timeout <seconds> — change raven_seek timeout\n  /raven stats   — show blocked calls and context saved` })
       }
     },
 
@@ -438,7 +426,7 @@ export default ((input: PluginInput) => {
           const field = ["prompt", "description", "request", "objective", "query"].find(
             (f) => f in output.args
           ) ?? "prompt"
-          output.args[field] = `${output.args[field] ?? ""}\n\n<raven_guidance>\nSearch tools (grep, glob, Context7, Exa, Grep.app, bash search) are blocked. Use raven_seek(query="...") to search through Raven.\n</raven_guidance>`
+          output.args[field] = `${output.args[field] ?? ""}\n\n<raven_guidance>\nSearch tools (grep, glob, ls, dir, bash search commands) are blocked. Use raven_seek(query=\"...\") for ALL searches — local codebase, web, docs, and GitHub examples.\n</raven_guidance>`
         }
       }
 
@@ -447,17 +435,12 @@ export default ((input: PluginInput) => {
       const isSearchBashCmd = isSearchBash(input.tool, output.args || input.args)
 
       if (isSearchTool || isSearchBashCmd) {
-        trackBlock(input.sessionID, isSearchBashCmd ? "bash(search)" : input.tool)
-        if (throttledSessions.has(input.sessionID)) {
-          throw new Error("")
-        }
-        throttledSessions.add(input.sessionID)
         throw new Error(REROUTE_MSG)
       }
     },
 
     "tool.execute.after"(input: any, output: any) {
-      // Reserved for future analytics / redirect tracking (#5)
+      // Context saved is tracked in raven_seek instead
     },
   }
 }) satisfies Plugin

package/mcp-guidance.md

@@ -6,4 +6,4 @@
 
 ## Built-in search tools (grep, glob, search-like bash) are blocked and routed to Raven automatically.
 
-Use raven_seek(query="...") to search through Raven.
+Use raven_seek(query="...") for ALL searches — local codebase, web, docs, and GitHub examples.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-raven",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "Search-first subagent for opencode — intercepts search tools and routes them through a hidden Raven agent with Context7, Exa AI, and Grep.app MCPs",
   "main": "./index.ts",
   "exports": {