@jmylchreest/aide-plugin 0.0.59 → 0.0.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmylchreest/aide-plugin",
-  "version": "0.0.59",
+  "version": "0.0.61",
   "description": "aide plugin for OpenCode and Codex CLI — multi-agent orchestration, memory, skills, and persistence",
   "type": "module",
   "main": "./src/opencode/index.ts",

package/src/cli/codex-config.ts

@@ -183,6 +183,11 @@ function generateHooksJson(hookPrefix: string): CodexHooksJson {
               command: `${hookPrefix} context-guard`,
               timeout: 2,
             },
+            {
+              type: "command",
+              command: `${hookPrefix} search-enrichment`,
+              timeout: 3,
+            },
           ],
         },
       ],
@@ -190,6 +195,16 @@ function generateHooksJson(hookPrefix: string): CodexHooksJson {
         {
           matcher: "*",
           hooks: [
+            {
+              type: "command",
+              command: `${hookPrefix} tool-observe`,
+              timeout: 3,
+            },
+            {
+              type: "command",
+              command: `${hookPrefix} hud-updater`,
+              timeout: 3,
+            },
             {
               type: "command",
               command: `${hookPrefix} comment-checker`,

package/src/cli/hook.ts

@@ -23,7 +23,9 @@ const HOOK_MAP: Record<string, string> = {
   "write-guard": "write-guard.ts",
   "pre-tool-enforcer": "pre-tool-enforcer.ts",
   "context-guard": "context-guard.ts",
+  "search-enrichment": "search-enrichment.ts",
   "hud-updater": "hud-updater.ts",
+  "tool-observe": "tool-observe.ts",
   "comment-checker": "comment-checker.ts",
   "context-pruning": "context-pruning.ts",
   "persistence": "persistence.ts",

package/src/core/mcp-sync.ts

@@ -1047,22 +1047,6 @@ export function syncMcpServers(
   return { user, project };
 }
 
-/**
- * Get the list of currently synced MCP servers (for display/logging).
- */
-export function listSyncedServers(cwd: string): {
-  user: string[];
-  project: string[];
-} {
-  const userServers = readAideConfig(aideUserMcpPath());
-  const projectServers = readAideConfig(aideProjectMcpPath(cwd));
-
-  return {
-    user: Object.keys(userServers),
-    project: Object.keys(projectServers),
-  };
-}
-
 /**
  * Get the current removed (blocked) server names.
  * Derived from the v2 journal: a server is "removed" if its latest

package/src/core/read-tracking.ts

@@ -143,9 +143,43 @@ export function recordTokenEvent(
 }
 
 /**
- * Estimate tokens for a file by its size, using the default ratio.
- * This is a rough client-side estimate; the Go binary has per-language ratios.
+ * Record an arbitrary observe event via `aide observe record`.
+ * Use when you need richer fields than recordTokenEvent (per-skill name with
+ * a stable subtype, attrs, etc.). Fire-and-forget.
  */
-export function estimateTokensFromSize(sizeBytes: number): number {
-  return Math.round(sizeBytes / 3.0);
+export function recordObserveEvent(
+  binary: string,
+  cwd: string,
+  opts: {
+    kind: string;
+    name: string;
+    category?: string;
+    subtype?: string;
+    tokens?: number;
+    saved?: number;
+    file?: string;
+    session?: string;
+    attrs?: Record<string, string>;
+  },
+): void {
+  try {
+    const args = ["observe", "record", `--kind=${opts.kind}`, `--name=${opts.name}`];
+    if (opts.category) args.push(`--category=${opts.category}`);
+    if (opts.subtype) args.push(`--subtype=${opts.subtype}`);
+    if (opts.tokens !== undefined) args.push(`--tokens=${opts.tokens}`);
+    if (opts.saved !== undefined) args.push(`--saved=${opts.saved}`);
+    if (opts.file) args.push(`--file=${opts.file}`);
+    if (opts.session) args.push(`--session=${opts.session}`);
+    for (const [k, v] of Object.entries(opts.attrs ?? {})) {
+      args.push(`--attr=${k}=${v}`);
+    }
+    execFileSync(binary, args, {
+      cwd,
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    debug(SOURCE, `Observe event: ${opts.kind} ${opts.name} subtype=${opts.subtype ?? ""} tokens=${opts.tokens ?? 0}`);
+  } catch (err) {
+    debug(SOURCE, `Failed to record observe event: ${err}`);
+  }
 }

package/src/core/search-enrichment.ts

@@ -0,0 +1,208 @@
+/**
+ * Search Enrichment — platform-agnostic core logic.
+ *
+ * Enriches Grep tool calls with structural context from the code index.
+ * When an agent greps for a symbol name, this appends metadata about
+ * matching symbol definitions (file, kind, ref count) so the agent
+ * knows where the symbol is defined and how widely it's used — without
+ * making additional tool calls.
+ *
+ * Behaviour:
+ *   - Triggers on Grep tool calls where the pattern looks like a symbol name
+ *   - Calls `aide code search <pattern> --json --limit=5` to find definitions
+ *   - For each match, calls `aide code references <name> --json --limit=0` for ref count
+ *   - Returns a compact enrichment string (~50-150 tokens)
+ *   - Never blocks — purely additive context
+ *
+ * Gated behind AIDE_CODE_WATCH=1 (requires code index to be populated).
+ *
+ * Used by both Claude Code hooks (PreToolUse) and OpenCode plugin.
+ */
+
+import { execFileSync } from "child_process";
+import { debug } from "../lib/logger.js";
+
+const SOURCE = "search-enrichment";
+
+/** Minimum pattern length to attempt enrichment (avoid single-char patterns) */
+const MIN_PATTERN_LENGTH = 3;
+
+/** Maximum time to wait for aide binary responses */
+const EXEC_TIMEOUT_MS = 3000;
+
+/**
+ * Patterns that are clearly regex, not symbol names.
+ * Skip enrichment for these — the code index won't have useful matches.
+ */
+const REGEX_INDICATORS = /[.*+?^${}()|[\]\\]/;
+
+export interface SearchEnrichmentResult {
+  /** Whether to inject enrichment context */
+  shouldEnrich: boolean;
+  /** Enrichment context to append */
+  enrichment?: string;
+}
+
+interface SymbolHit {
+  name: string;
+  kind: string;
+  file: string;
+  start: number;
+  end: number;
+  signature: string;
+  lang: string;
+}
+
+/**
+ * Check whether a Grep tool call should receive code index enrichment.
+ *
+ * Extracts the search pattern, looks it up in the code index, and returns
+ * a compact summary of matching symbol definitions with ref counts.
+ */
+export function checkSearchEnrichment(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  cwd: string,
+  binary: string | null,
+): SearchEnrichmentResult {
+  const normalizedTool = toolName.toLowerCase();
+
+  // Only enrich Grep tool calls
+  if (normalizedTool !== "grep") {
+    return { shouldEnrich: false };
+  }
+
+  // Require code watcher to be enabled (implies code index exists)
+  if (process.env.AIDE_CODE_WATCH !== "1") {
+    return { shouldEnrich: false };
+  }
+
+  if (!binary) {
+    return { shouldEnrich: false };
+  }
+
+  // Extract the search pattern
+  const pattern =
+    (toolInput.pattern as string) ||
+    (toolInput.query as string) ||
+    (toolInput.search as string);
+
+  if (!pattern || pattern.length < MIN_PATTERN_LENGTH) {
+    return { shouldEnrich: false };
+  }
+
+  // Skip patterns that are clearly regex (not symbol names)
+  if (REGEX_INDICATORS.test(pattern)) {
+    return { shouldEnrich: false };
+  }
+
+  // Skip patterns with spaces (likely searching for phrases, not symbols)
+  if (pattern.includes(" ")) {
+    return { shouldEnrich: false };
+  }
+
+  // Look up matching symbols in the code index
+  const symbols = searchSymbols(binary, cwd, pattern);
+  if (symbols.length === 0) {
+    return { shouldEnrich: false };
+  }
+
+  // Build compact enrichment string
+  const lines: string[] = [];
+  lines.push(`[aide:code-index] Symbol definitions matching "${pattern}":`);
+
+  for (const sym of symbols) {
+    const refCount = countReferences(binary, cwd, sym.name);
+    const refs = refCount > 0 ? `, ${refCount} refs` : ", 0 refs";
+    lines.push(`  ${sym.kind} ${sym.name} — ${sym.file}:${sym.start}${refs}`);
+  }
+
+  if (symbols.length > 0) {
+    lines.push(
+      `Use code_read_symbol for source, code_references for call sites.`,
+    );
+  }
+
+  const enrichment = lines.join("\n");
+  debug(SOURCE, `Enriching grep for "${pattern}": ${symbols.length} symbols`);
+
+  return { shouldEnrich: true, enrichment };
+}
+
+/**
+ * Search the code index for symbol definitions matching a pattern.
+ */
+function searchSymbols(
+  binary: string,
+  cwd: string,
+  pattern: string,
+): SymbolHit[] {
+  try {
+    const output = execFileSync(
+      binary,
+      ["code", "search", pattern, "--json", "--limit=5"],
+      {
+        cwd,
+        encoding: "utf-8",
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+
+    const trimmed = output.trim();
+    if (!trimmed || trimmed.startsWith("No matching")) {
+      return [];
+    }
+
+    const parsed = JSON.parse(trimmed);
+    if (!Array.isArray(parsed)) return [];
+
+    return parsed.map(
+      (s: Record<string, unknown>): SymbolHit => ({
+        name: (s.name as string) || "",
+        kind: (s.kind as string) || "",
+        file: (s.file as string) || "",
+        start: (s.start as number) || 0,
+        end: (s.end as number) || 0,
+        signature: (s.signature as string) || "",
+        lang: (s.lang as string) || "",
+      }),
+    );
+  } catch (err) {
+    debug(SOURCE, `Symbol search failed: ${err}`);
+    return [];
+  }
+}
+
+/**
+ * Count references to a symbol name in the code index.
+ * Returns the count, or 0 on error.
+ */
+function countReferences(
+  binary: string,
+  cwd: string,
+  symbolName: string,
+): number {
+  try {
+    const output = execFileSync(
+      binary,
+      ["code", "references", symbolName, "--json", "--limit=100"],
+      {
+        cwd,
+        encoding: "utf-8",
+        timeout: EXEC_TIMEOUT_MS,
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+
+    const trimmed = output.trim();
+    if (!trimmed || trimmed.startsWith("No references")) {
+      return 0;
+    }
+
+    const parsed = JSON.parse(trimmed);
+    return Array.isArray(parsed) ? parsed.length : 0;
+  } catch {
+    return 0;
+  }
+}

package/src/core/tool-observe.ts

@@ -0,0 +1,284 @@
+/**
+ * Tool observability — single source of truth for native tool → observe.Event
+ * mapping. Used by both the Claude Code PostToolUse hook and the OpenCode
+ * tool.execute.after handler so dashboard categorisation stays consistent
+ * across plugins.
+ *
+ * Mirror image of the MCP-side mcpToolTaxonomy in cmd_mcp.go: native tools
+ * (Read, Edit, Bash, ...) flow through here; MCP tools (code_outline,
+ * findings_search, ...) flow through the middleware. Together they give
+ * complete tool-call coverage in the observe store.
+ */
+
+import { execFileSync } from "child_process";
+import { statSync } from "fs";
+import { isAbsolute, resolve } from "path";
+import { debug } from "../lib/logger.js";
+import { recordFileRead } from "./read-tracking.js";
+
+const SOURCE = "tool-observe";
+
+/**
+ * Category + subtype for one native tool. Categories mirror the MCP taxonomy:
+ *   consume   — pulls content into context (Read)
+ *   modify    — changes files (Edit, Write, NotebookEdit)
+ *   search    — finds things without consuming much (Grep, Glob)
+ *   execute   — runs external commands (Bash)
+ *   network   — fetches over the network (WebFetch, WebSearch)
+ *   coordinate— delegates work (Task)
+ *   navigate  — read-only state queries (TodoWrite read-side, etc.)
+ */
+interface ToolTax {
+  category: string;
+  subtype: string;
+}
+
+/**
+ * Native tool → (category, subtype). Names use Claude Code's canonical casing
+ * (PascalCase). The OpenCode call site lowercases before lookup so the same
+ * table serves both ("read" → "Read").
+ */
+const NATIVE_TOOL_TAXONOMY: Record<string, ToolTax> = {
+  Read: { category: "consume", subtype: "file" },
+  Edit: { category: "modify", subtype: "file" },
+  Write: { category: "modify", subtype: "file" },
+  NotebookEdit: { category: "modify", subtype: "notebook" },
+  Grep: { category: "search", subtype: "content" },
+  Glob: { category: "search", subtype: "path" },
+  Bash: { category: "execute", subtype: "shell" },
+  WebFetch: { category: "network", subtype: "fetch" },
+  WebSearch: { category: "network", subtype: "search" },
+  Task: { category: "coordinate", subtype: "subagent" },
+  TodoWrite: { category: "coordinate", subtype: "todo" },
+};
+
+/**
+ * Cross-harness aliases. Codex and other harnesses name the same primitives
+ * differently — `update`/`apply_patch` for Edit, `view` for Read, `shell`
+ * for Bash, etc. Mapping them to Claude Code's canonical names keeps the
+ * dashboard's per-tool aggregation coherent across plugins (no separate
+ * "update" + "Edit" buckets that mean the same thing).
+ *
+ * Lookup is case-insensitive; aliases here are the lowercase form.
+ */
+const TOOL_ALIASES: Record<string, string> = {
+  // Codex / OpenAI-style tool names
+  update: "Edit",
+  apply_patch: "Edit",
+  str_replace_editor: "Edit",
+  view: "Read",
+  read_file: "Read",
+  get: "Read",
+  create: "Write",
+  shell: "Bash",
+  exec: "Bash",
+  fetch: "WebFetch",
+  search_web: "WebSearch",
+};
+
+/** Tools whose tokens we estimate from on-disk file size (the Read path). */
+const FILE_SIZED_TOOLS = new Set(["Read"]);
+
+/**
+ * Tools whose token cost is the size of content the agent *writes* — the
+ * `new_string` for Edit, the `content` for Write. We track these so the
+ * "modify" category in per-tool efficiency surfaces something other than
+ * a flat zero.
+ */
+const CONTENT_WRITE_TOOLS: Record<string, string> = {
+  Edit: "new_string",
+  Write: "content",
+  NotebookEdit: "new_source",
+};
+
+/**
+ * Tools whose cost is the size of the *output* they produce — Bash stdout,
+ * WebFetch page body, WebSearch results, Grep match lines. The PostToolUse
+ * payload carries the tool's response so we can estimate the tokens that
+ * flowed back into the agent's context.
+ */
+const OUTPUT_SIZED_TOOLS = new Set(["Bash", "WebFetch", "WebSearch", "Grep"]);
+
+/**
+ * Pull the textual output from a tool_response / tool_result payload. The
+ * shape varies by tool and by harness (Claude Code passes string for Bash,
+ * objects for others; OpenCode wraps things differently), so we try the
+ * common keys defensively and return "" when there's no text to count.
+ */
+function extractOutputText(payload: unknown): string {
+  if (!payload) return "";
+  if (typeof payload === "string") return payload;
+  if (typeof payload === "object") {
+    const obj = payload as Record<string, unknown>;
+    for (const key of ["output", "stdout", "content", "text", "result"]) {
+      const v = obj[key];
+      if (typeof v === "string") return v;
+    }
+  }
+  return "";
+}
+
+export interface ToolObserveInput {
+  toolName: string;
+  toolInput?: {
+    file_path?: string;
+    offset?: number;
+    limit?: number;
+    command?: string;
+    pattern?: string;
+    new_string?: string;
+    content?: string;
+    new_source?: string;
+    [key: string]: unknown;
+  };
+  /**
+   * The tool's response payload, used to estimate output token cost for
+   * Bash/WebFetch/WebSearch/Grep. Shape varies per tool and per harness;
+   * extractOutputText handles the common cases.
+   */
+  toolResponse?: unknown;
+  success?: boolean;
+  sessionId?: string;
+}
+
+/**
+ * Resolve a native tool name (any casing) to its taxonomy entry. Returns
+ * `null` for tools we don't classify — callers skip recording rather than
+ * pollute the dashboard with an "other" bucket.
+ *
+ * Lookup order: exact → case-insensitive → cross-harness alias.
+ */
+function lookupTool(name: string): ToolTax | null {
+  if (NATIVE_TOOL_TAXONOMY[name]) return NATIVE_TOOL_TAXONOMY[name];
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(NATIVE_TOOL_TAXONOMY)) {
+    if (k.toLowerCase() === lower) return v;
+  }
+  const canonical = TOOL_ALIASES[lower];
+  if (canonical && NATIVE_TOOL_TAXONOMY[canonical]) {
+    return NATIVE_TOOL_TAXONOMY[canonical];
+  }
+  return null;
+}
+
+/**
+ * Resolve to the canonical tool name (Edit/Read/Write/...) so observe
+ * events from different harnesses aggregate into the same bucket on the
+ * dashboard. Falls back to the original name when no alias matches.
+ */
+function canonicalToolName(name: string): string {
+  if (NATIVE_TOOL_TAXONOMY[name]) return name;
+  const lower = name.toLowerCase();
+  for (const k of Object.keys(NATIVE_TOOL_TAXONOMY)) {
+    if (k.toLowerCase() === lower) return k;
+  }
+  return TOOL_ALIASES[lower] ?? name;
+}
+
+/**
+ * Estimate tokens for the Read tool. If offset/limit are present, scale by
+ * the portion actually read. Returns 0 on stat failure (caller still records
+ * the event so the call shows up in the timeline).
+ */
+function estimateReadTokens(
+  cwd: string,
+  filePath: string,
+  offset?: number,
+  limit?: number,
+): number {
+  try {
+    const abs = isAbsolute(filePath) ? filePath : resolve(cwd, filePath);
+    const stat = statSync(abs);
+    const fullTokens = Math.round(stat.size / 3.0);
+    if (limit !== undefined && limit > 0 && stat.size > 0) {
+      const estTotalLines = Math.max(1, Math.round(stat.size / 35));
+      const linesRead = Math.min(limit, estTotalLines - (offset || 0));
+      return Math.round(fullTokens * (linesRead / estTotalLines));
+    }
+    return fullTokens;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Record a native tool invocation as an observe.KindToolCall event. Pure
+ * fire-and-forget: failures are logged but never thrown so this is safe to
+ * call from tight hook hot paths. Callers should pass success=true; we still
+ * record on success=false so failed invocations are visible in the timeline.
+ */
+export function recordToolEvent(
+  binary: string,
+  cwd: string,
+  input: ToolObserveInput,
+): void {
+  const tax = lookupTool(input.toolName);
+  if (!tax) {
+    debug(SOURCE, `Skipping unclassified tool: ${input.toolName}`);
+    return;
+  }
+
+  const filePath = input.toolInput?.file_path as string | undefined;
+  let tokens = 0;
+  let startLine: number | undefined;
+  let endLine: number | undefined;
+  if (FILE_SIZED_TOOLS.has(input.toolName) && filePath) {
+    const offset = input.toolInput?.offset as number | undefined;
+    const limit = input.toolInput?.limit as number | undefined;
+    tokens = estimateReadTokens(cwd, filePath, offset, limit);
+    // Read tool offset/limit are line-based (1-based when present, default
+    // 1..end). Persist the range so the dashboard's file viewer can
+    // scroll/highlight the slice the agent actually consumed.
+    startLine = offset && offset > 0 ? offset : 1;
+    if (limit && limit > 0) {
+      endLine = startLine + limit - 1;
+    }
+    // Smart-read-hint state: record that this file was read so subsequent
+    // re-reads can be flagged as candidates for code_outline/code_symbols.
+    // No-op when AIDE_CODE_WATCH is unset.
+    recordFileRead(binary, cwd, filePath);
+  } else if (CONTENT_WRITE_TOOLS[input.toolName]) {
+    // Modify tools: the cost is the new content the agent generates,
+    // not the existing file. Same chars/3 estimator the Read path uses.
+    const field = CONTENT_WRITE_TOOLS[input.toolName];
+    const content = input.toolInput?.[field];
+    if (typeof content === "string" && content.length > 0) {
+      tokens = Math.round(content.length / 3.0);
+    }
+  } else if (OUTPUT_SIZED_TOOLS.has(input.toolName)) {
+    // Output-sized tools: cost = how much text came back into context.
+    // Stays 0 when the harness didn't pass a tool_response (some hooks
+    // strip it for size). That's still useful — we get the call count.
+    const text = extractOutputText(input.toolResponse);
+    if (text.length > 0) {
+      tokens = Math.round(text.length / 3.0);
+    }
+  }
+
+  try {
+    const args = [
+      "observe",
+      "record",
+      "--kind=tool_call",
+      `--name=${input.toolName}`,
+      `--category=${tax.category}`,
+      `--subtype=${tax.subtype}`,
+    ];
+    if (tokens > 0) args.push(`--tokens=${tokens}`);
+    if (filePath) args.push(`--file=${filePath}`);
+    if (input.sessionId) args.push(`--session=${input.sessionId}`);
+    if (startLine !== undefined) args.push(`--attr=start_line=${startLine}`);
+    if (endLine !== undefined) args.push(`--attr=end_line=${endLine}`);
+    execFileSync(binary, args, {
+      cwd,
+      timeout: 3000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    debug(
+      SOURCE,
+      `Recorded ${input.toolName} ${tax.category}/${tax.subtype} tokens=${tokens}`,
+    );
+  } catch (err) {
+    debug(SOURCE, `Failed to record ${input.toolName}: ${err}`);
+  }
+}

package/src/hooks/hud-updater.ts

@@ -8,8 +8,6 @@
  * Output is written to .aide/state/hud.txt for the terminal to display.
  */
 
-import { statSync } from "fs";
-import { resolve, isAbsolute } from "path";
 import { Logger, debug } from "../lib/logger.js";
 import { readStdin } from "../lib/hook-utils.js";
 
@@ -17,7 +15,6 @@ const SOURCE = "hud-updater";
 import { findAideBinary } from "../core/aide-client.js";
 import { updateToolStats } from "../core/tool-tracking.js";
 import { storePartialMemory } from "../core/partial-memory.js";
-import { recordFileRead, recordTokenEvent, estimateTokensFromSize } from "../core/read-tracking.js"; // estimateTokensFromSize used for read events
 import {
   getAgentStates,
   loadHudConfig,
@@ -90,26 +87,6 @@ async function main(): Promise<void> {
           success: data.tool_result?.success,
         });
 
-        // Record file reads for smart-read-hint feature
-        if (
-          toolName === "Read" &&
-          data.tool_result?.success &&
-          data.tool_input?.file_path
-        ) {
-          const fp = data.tool_input.file_path as string;
-          recordFileRead(binary, cwd, fp);
-
-          // Record token event for the read (estimate from file size)
-          try {
-            const abs = isAbsolute(fp) ? fp : resolve(cwd, fp);
-            const stat = statSync(abs);
-            const tokens = estimateTokensFromSize(stat.size);
-            recordTokenEvent(binary, cwd, "read", "Read", fp, tokens);
-          } catch {
-            // stat failed — skip token recording
-          }
-        }
-
       }
       log.end("updateSessionState");
     }