@jmylchreest/aide-plugin 0.0.42 → 0.0.44

package/package.json

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

package/skills/context-usage/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: context-usage
+description: Analyze current session context and token usage from OpenCode SQLite database
+platforms:
+  - opencode
+triggers:
+  - context usage
+  - token usage
+  - session stats
+  - how much context
+  - context budget
+  - how big is this session
+  - session size
+---
+
+# Context Usage Analysis
+
+**Recommended model tier:** balanced (sonnet) - straightforward SQL queries
+
+Analyze the current session's context window consumption, tool usage breakdown,
+and token costs by querying the OpenCode SQLite database directly.
+
+## Prerequisites
+
+- This skill **only works on OpenCode**. Verify by checking the environment:
+  - `$OPENCODE=1` — set by the OpenCode runtime
+  - `$AIDE_PLATFORM=opencode` — set by aide when running under OpenCode
+  - `$AIDE_SESSION_ID` — the current session ID (injected by aide)
+- The OpenCode database is at `~/.local/share/opencode/opencode.db`.
+- `sqlite3` must be available on the system.
+
+If `$OPENCODE` is not `1` or `$AIDE_PLATFORM` is not `opencode`, abort immediately
+and inform the user that this skill is only supported on OpenCode.
+Do **not** attempt to query other databases (e.g. Claude Code's storage) — the
+schema is OpenCode-specific.
+
+If `$AIDE_SESSION_ID` is not set, abort with a message explaining that the
+session ID could not be determined.
+
+## Workflow
+
+Run the following queries **sequentially** in a single Bash call (chain with `&&`).
+Present results to the user in a formatted summary after all queries complete.
+
+### Step 1: Validate environment
+
+```bash
+test "$OPENCODE" = "1" && echo "Platform: OpenCode" || echo "ERROR: Not running on OpenCode (OPENCODE=$OPENCODE)"
+test "$AIDE_PLATFORM" = "opencode" && echo "AIDE Platform: opencode" || echo "WARNING: AIDE_PLATFORM=$AIDE_PLATFORM"
+test -n "$AIDE_SESSION_ID" && echo "Session: $AIDE_SESSION_ID" || echo "ERROR: AIDE_SESSION_ID not set"
+```
+
+If `OPENCODE` is not `1`, stop immediately — this skill cannot work outside OpenCode.
+If `AIDE_SESSION_ID` is not set, stop and inform the user.
+
+### Step 2: Session overview
+
+```bash
+sqlite3 ~/.local/share/opencode/opencode.db "
+SELECT
+  s.title,
+  s.slug,
+  ROUND((julianday('now') - julianday(datetime(s.time_created/1000, 'unixepoch'))) * 24, 1) as hours_old,
+  (SELECT COUNT(*) FROM message m WHERE m.session_id = s.id) as messages,
+  CASE WHEN s.time_compacting IS NOT NULL THEN 'yes' ELSE 'no' END as compacted
+FROM session s
+WHERE s.id = '$AIDE_SESSION_ID';
+"
+```
+
+### Step 3: Token totals
+
+Sum tokens from `step-finish` parts (each represents one LLM turn):
+
+```bash
+sqlite3 ~/.local/share/opencode/opencode.db "
+SELECT
+  SUM(json_extract(data, '$.tokens.input')) as input_tokens,
+  SUM(json_extract(data, '$.tokens.output')) as output_tokens,
+  SUM(json_extract(data, '$.tokens.cache.read')) as cache_read_tokens,
+  SUM(json_extract(data, '$.tokens.cache.write')) as cache_write_tokens,
+  SUM(json_extract(data, '$.tokens.total')) as total_tokens,
+  COUNT(*) as llm_turns
+FROM part
+WHERE session_id = '$AIDE_SESSION_ID'
+  AND json_extract(data, '$.type') = 'step-finish';
+"
+```
+
+### Step 4: Tool output breakdown
+
+Show tool usage ranked by total output size:
+
+```bash
+sqlite3 ~/.local/share/opencode/opencode.db "
+SELECT
+  json_extract(data, '$.tool') as tool,
+  COUNT(*) as calls,
+  SUM(length(json_extract(data, '$.state.output'))) as total_output_bytes,
+  ROUND(AVG(length(json_extract(data, '$.state.output')))) as avg_bytes,
+  MAX(length(json_extract(data, '$.state.output'))) as max_bytes
+FROM part
+WHERE session_id = '$AIDE_SESSION_ID'
+  AND json_extract(data, '$.type') = 'tool'
+GROUP BY tool
+ORDER BY total_output_bytes DESC;
+"
+```
+
+### Step 5: Total session size
+
+```bash
+sqlite3 ~/.local/share/opencode/opencode.db "
+SELECT
+  SUM(length(json_extract(data, '$.state.output'))) as tool_output_bytes,
+  SUM(length(json_extract(data, '$.state.input'))) as tool_input_bytes,
+  SUM(length(data)) as total_part_bytes
+FROM part
+WHERE session_id = '$AIDE_SESSION_ID'
+  AND json_extract(data, '$.type') = 'tool';
+"
+```
+
+## Output Format
+
+Present the results as a structured summary:
+
+```
+## Session Context Usage
+
+**Session:** <title> (<slug>)
+**Age:** <hours> hours | **Messages:** <count> | **Compacted:** yes/no
+
+### Token Usage
+| Metric | Count |
+|--------|-------|
+| Input tokens | <n> |
+| Output tokens | <n> |
+| Cache read | <n> |
+| Cache write | <n> |
+| **Total tokens** | **<n>** |
+| LLM turns | <n> |
+
+### Tool Output Breakdown (by total bytes)
+| Tool | Calls | Total Output | Avg/call | Max |
+|------|-------|-------------|----------|-----|
+| ... | ... | ... | ... | ... |
+
+### Session Size
+- Tool outputs: <n> KB
+- Tool inputs: <n> KB
+- Total part storage: <n> KB (includes JSON metadata overhead)
+```
+
+Format byte values as KB (divide by 1024, round to 1 decimal).
+Highlight the top 3 tools by total output as the biggest context consumers.
+If any single tool call exceeds 20KB, flag it as a potential optimization target.

package/skills/survey/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: survey
+description: Explore codebase structure, entry points, tech stack, hotspots, and call graphs
+triggers:
+  - survey
+  - codebase structure
+  - what is this codebase
+  - tech stack
+  - entry points
+  - entrypoints
+  - what modules
+  - what packages
+  - code churn
+  - hotspots
+  - call graph
+  - who calls
+  - what calls
+  - orient me
+  - onboard
+  - codebase overview
+---
+
+# Codebase Survey
+
+**Recommended model tier:** balanced (sonnet) - this skill performs structured queries
+
+Understand the structure, technology, entry points, and change hotspots of a codebase.
+Survey describes WHAT the codebase IS — not code problems (use `findings` for that).
+
+## Available Tools
+
+### 1. Survey Stats (`mcp__plugin_aide_aide__survey_stats`)
+
+**Start here.** Get an overview of what has been surveyed: total entries, breakdown by analyzer and kind.
+
+```
+Is the codebase surveyed?
+→ Uses survey_stats
+→ Returns: counts by analyzer (topology, entrypoints, churn) and kind
+```
+
+### 2. Survey Run (`mcp__plugin_aide_aide__survey_run`)
+
+Run analyzers to populate survey data. Three analyzers available:
+
+- **topology** — Modules, packages, workspaces, build systems, tech stack detection
+- **entrypoints** — main() functions, HTTP handlers, gRPC services, CLI roots (cobra/urfave). Uses code index when available; falls back to file scanning
+- **churn** — Git history hotspots (files/dirs that change most often)
+
+```
+Survey this codebase
+→ Uses survey_run (no analyzer param = run all)
+→ Returns: entry counts per analyzer
+```
+
+### 3. Survey List (`mcp__plugin_aide_aide__survey_list`)
+
+Browse entries filtered by analyzer, kind, or file path. No search query needed.
+
+**Kinds:** module, entrypoint, dependency, tech_stack, churn, submodule, workspace, arch_pattern
+
+```
+What modules are in this codebase?
+→ Uses survey_list with kind=module
+→ Returns: all module entries
+
+What technologies does this use?
+→ Uses survey_list with kind=tech_stack
+→ Returns: detected frameworks, languages, build systems
+
+What files change most?
+→ Uses survey_list with kind=churn
+→ Returns: high-churn files ranked by commit count
+```
+
+### 4. Survey Search (`mcp__plugin_aide_aide__survey_search`)
+
+Full-text search across entry names, titles, and details. Use when looking for specific modules or technologies.
+
+```
+Find anything related to "auth"
+→ Uses survey_search with query="auth"
+→ Returns: modules, entrypoints, churn entries matching "auth"
+```
+
+### 5. Call Graph (`mcp__plugin_aide_aide__survey_graph`)
+
+Build a call graph for a symbol showing callers, callees, or both. BFS traversal over the code index.
+
+```
+Who calls BuildCallGraph?
+→ Uses survey_graph with symbol="BuildCallGraph" direction="callers"
+→ Returns: graph of calling symbols with file:line locations
+
+What does handleSurveyRun call?
+→ Uses survey_graph with symbol="handleSurveyRun" direction="callees"
+→ Returns: graph of called symbols
+
+Show call neighborhood of RunTopology
+→ Uses survey_graph with symbol="RunTopology" direction="both"
+→ Returns: both callers and callees
+```
+
+**Parameters:**
+
+- `symbol` (required): Function/method name
+- `direction`: "both" (default), "callers", "callees"
+- `max_depth`: BFS hops (default 2)
+- `max_nodes`: Max nodes (default 50)
+
+**Requires:** Code index must be populated (`aide code index`).
+
+## Workflow
+
+### Orienting in an unfamiliar codebase
+
+1. **Check survey status:**
+   - Use `survey_stats` to see if data exists
+   - If empty, run `survey_run` to populate
+
+2. **Understand the structure:**
+   - `survey_list kind=module` — What are the major modules?
+   - `survey_list kind=tech_stack` — What technologies are used?
+   - `survey_list kind=workspace` — Is this a monorepo?
+
+3. **Find entry points:**
+   - `survey_list kind=entrypoint` — Where does execution start?
+   - Identifies main() functions, HTTP handlers, CLI roots
+
+4. **Identify hotspots:**
+   - `survey_list kind=churn` — What files change most? (complexity/bug magnets)
+
+5. **Trace call relationships:**
+   - `survey_graph symbol="handleRequest"` — Map the call neighborhood
+   - Use `direction=callers` to find who invokes a function
+   - Use `direction=callees` to understand what a function depends on
+
+### Answering specific questions
+
+| Question                      | Tool            | Parameters                  |
+| ----------------------------- | --------------- | --------------------------- |
+| "What is this codebase?"      | `survey_list`   | kind=module                 |
+| "What tech stack?"            | `survey_list`   | kind=tech_stack             |
+| "Where are the entry points?" | `survey_list`   | kind=entrypoint             |
+| "What changes most?"          | `survey_list`   | kind=churn                  |
+| "Is there an auth module?"    | `survey_search` | query="auth"                |
+| "Who calls this function?"    | `survey_graph`  | symbol=X, direction=callers |
+| "What does this call?"        | `survey_graph`  | symbol=X, direction=callees |
+
+## Survey vs Findings vs Code Search
+
+| Tool            | Purpose              | Example                                  |
+| --------------- | -------------------- | ---------------------------------------- |
+| **Survey**      | WHAT the codebase IS | Modules, tech stack, entry points, churn |
+| **Findings**    | Code PROBLEMS        | Complexity, security issues, duplication |
+| **Code Search** | Symbol DEFINITIONS   | Find function signatures, call sites     |
+
+Survey gives you the big picture. Code search gives you specific symbols. Findings gives you problems to fix.
+
+## Prerequisites
+
+- **Survey data:** Run `aide survey run` or use `survey_run` tool
+- **Code index (for entrypoints + graph):** Run `aide code index`
+- **Git history (for churn):** Must be a git repository (uses go-git, no git binary needed)
+
+**Binary location:** The aide binary is at `.aide/bin/aide`. If it's on your `$PATH`, you can use `aide` directly.
+
+## Notes
+
+- Survey results are cached in BoltDB — re-run analyzers to refresh after significant changes
+- Topology analyzer inspects the filesystem (build files, directory structure)
+- Entrypoints analyzer uses the code index when available; falls back to file scanning
+- Churn analyzer uses go-git to read git history directly (no git binary required)
+- Call graph is computed on demand from the code index (not stored)

package/src/core/context-pruning/dedup.ts

@@ -0,0 +1,173 @@
+/**
+ * Dedup strategy: replace repeated identical tool outputs with a short pointer.
+ *
+ * Safe-to-dedup tools: Read (with mtime check), Glob, Grep, and aide MCP tools
+ * like code_search, code_symbols, code_outline, code_references,
+ * findings_list, findings_search, memory_list, memory_search.
+ *
+ * NEVER dedup: Bash, Write, Edit, or any tool with side effects.
+ */
+
+import type { PruneResult, PruneStrategy, ToolRecord } from "./types.js";
+import { statSync } from "fs";
+import { resolve, isAbsolute } from "path";
+
+/** Tools that are safe to deduplicate. */
+const SAFE_DEDUP_TOOLS = new Set([
+  // Host built-in read-only tools
+  "read",
+  "glob",
+  "grep",
+  // aide MCP tools (read-only)
+  "mcp__aide__code_search",
+  "mcp__aide__code_symbols",
+  "mcp__aide__code_outline",
+  "mcp__aide__code_references",
+  "mcp__aide__code_stats",
+  "mcp__aide__findings_list",
+  "mcp__aide__findings_search",
+  "mcp__aide__findings_stats",
+  "mcp__aide__memory_list",
+  "mcp__aide__memory_search",
+  "mcp__aide__decision_list",
+  "mcp__aide__decision_get",
+  "mcp__aide__decision_history",
+  "mcp__aide__state_get",
+  "mcp__aide__state_list",
+  "mcp__aide__task_list",
+  "mcp__aide__task_get",
+  "mcp__aide__message_list",
+  // Claude Code naming convention (no mcp__ prefix)
+  "code_search",
+  "code_symbols",
+  "code_outline",
+  "code_references",
+  "code_stats",
+  "findings_list",
+  "findings_search",
+  "findings_stats",
+  "memory_list",
+  "memory_search",
+  "decision_list",
+  "decision_get",
+  "decision_history",
+  "state_get",
+  "state_list",
+  "task_list",
+  "task_get",
+  "message_list",
+]);
+
+/** Extract the dedup key from tool args (the args that define "same call"). */
+function dedupKey(toolName: string, args: Record<string, unknown>): string {
+  const normalized = toolName.toLowerCase();
+  // For Read, the key is filePath + offset + limit
+  if (normalized === "read") {
+    return JSON.stringify({
+      tool: "read",
+      filePath: args.filePath ?? args.file_path ?? args.path,
+      offset: args.offset ?? 0,
+      limit: args.limit ?? 2000,
+    });
+  }
+  // For Glob, the key is pattern + path
+  if (normalized === "glob") {
+    return JSON.stringify({
+      tool: "glob",
+      pattern: args.pattern,
+      path: args.path,
+    });
+  }
+  // For Grep, the key is pattern + path + include
+  if (normalized === "grep") {
+    return JSON.stringify({
+      tool: "grep",
+      pattern: args.pattern,
+      path: args.path,
+      include: args.include,
+    });
+  }
+  // For MCP tools, use all args as the key
+  return JSON.stringify({ tool: normalized, ...args });
+}
+
+/** Check file mtime for Read dedup safety. */
+function getFileMtime(
+  args: Record<string, unknown>,
+  cwd?: string,
+): number | undefined {
+  const filePath =
+    (args.filePath as string) ??
+    (args.file_path as string) ??
+    (args.path as string);
+  if (!filePath) return undefined;
+
+  try {
+    const resolved = isAbsolute(filePath)
+      ? filePath
+      : resolve(cwd || process.cwd(), filePath);
+    return statSync(resolved).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
+export class DedupStrategy implements PruneStrategy {
+  name = "dedup" as const;
+  private cwd?: string;
+
+  constructor(cwd?: string) {
+    this.cwd = cwd;
+  }
+
+  apply(
+    toolName: string,
+    args: Record<string, unknown>,
+    output: string,
+    history: ToolRecord[],
+  ): PruneResult {
+    const normalized = toolName.toLowerCase();
+
+    // Only apply to safe tools
+    if (!SAFE_DEDUP_TOOLS.has(normalized)) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    const key = dedupKey(toolName, args);
+
+    // Find the most recent matching call in history
+    for (let i = history.length - 1; i >= 0; i--) {
+      const prev = history[i];
+      const prevKey = dedupKey(prev.toolName, prev.args);
+
+      if (prevKey !== key) continue;
+
+      // For Read: check mtime hasn't changed (file might have been edited)
+      if (normalized === "read") {
+        const currentMtime = getFileMtime(args, this.cwd);
+        if (
+          currentMtime !== undefined &&
+          prev.fileMtime !== undefined &&
+          currentMtime !== prev.fileMtime
+        ) {
+          // File changed — don't dedup
+          continue;
+        }
+      }
+
+      // Check if output is identical
+      const prevOutput = prev.prunedOutput ?? prev.originalOutput;
+      if (output === prevOutput) {
+        const replacement = `[aide:dedup] Identical to previous ${toolName} call (callId: ${prev.callId}). Output unchanged.`;
+        return {
+          output: replacement,
+          modified: true,
+          strategy: "dedup",
+          bytesSaved: output.length - replacement.length,
+        };
+      }
+    }
+
+    return { output, modified: false, bytesSaved: 0 };
+  }
+}

package/src/core/context-pruning/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Context Pruning — reduces context/token usage by deduplicating,
+ * superseding, and purging tool outputs.
+ *
+ * Platform adapters integrate via the ContextPruningTracker:
+ * - OpenCode: tool.execute.after hook modifies output.output
+ * - Claude Code: PostToolUse hook returns updatedMCPToolOutput
+ */
+
+export { ContextPruningTracker } from "./tracker.js";
+export { DedupStrategy } from "./dedup.js";
+export { SupersedeStrategy } from "./supersede.js";
+export { PurgeErrorsStrategy } from "./purge.js";
+export type {
+  ToolRecord,
+  PruneResult,
+  PruneStrategy,
+  PruningStats,
+} from "./types.js";

package/src/core/context-pruning/purge.ts

@@ -0,0 +1,80 @@
+/**
+ * Purge-errors strategy: replace large error outputs (stack traces, build
+ * failures) with a compact summary.
+ *
+ * When a Bash command fails and produces a large error output, most of the
+ * context is stack frames that aren't useful for the model. This strategy
+ * trims the output to the first meaningful error lines.
+ */
+
+import type { PruneResult, PruneStrategy, ToolRecord } from "./types.js";
+
+/** Minimum output size to trigger purging (2KB). */
+const MIN_SIZE_FOR_PURGE = 2048;
+
+/** Max lines to keep from an error output. */
+const MAX_ERROR_LINES = 30;
+
+/** Patterns that indicate an error output. */
+const ERROR_PATTERNS = [
+  /^error/im,
+  /^ERR!/im,
+  /exit code [1-9]/i,
+  /FAILED/i,
+  /panic:/i,
+  /Traceback/i,
+  /^Exception/im,
+  /compilation failed/i,
+  /build failed/i,
+  /TypeError:/,
+  /SyntaxError:/,
+  /ReferenceError:/,
+];
+
+export class PurgeErrorsStrategy implements PruneStrategy {
+  name = "purge" as const;
+
+  apply(
+    toolName: string,
+    _args: Record<string, unknown>,
+    output: string,
+    _history: ToolRecord[],
+  ): PruneResult {
+    const normalized = toolName.toLowerCase();
+
+    // Only apply to Bash output
+    if (normalized !== "bash") {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    // Only purge if output is large enough to matter
+    if (output.length < MIN_SIZE_FOR_PURGE) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    // Check if output looks like an error
+    const isError = ERROR_PATTERNS.some((p) => p.test(output));
+    if (!isError) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    // Trim to first MAX_ERROR_LINES lines + a note
+    const lines = output.split("\n");
+    if (lines.length <= MAX_ERROR_LINES) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    const kept = lines.slice(0, MAX_ERROR_LINES).join("\n");
+    const trimmedCount = lines.length - MAX_ERROR_LINES;
+    const replacement =
+      kept +
+      `\n\n[aide:purge] ... ${trimmedCount} additional error lines trimmed. Re-run the command to see full output.`;
+
+    return {
+      output: replacement,
+      modified: true,
+      strategy: "purge",
+      bytesSaved: output.length - replacement.length,
+    };
+  }
+}

package/src/core/context-pruning/supersede.ts

@@ -0,0 +1,67 @@
+/**
+ * Supersede strategy: when a Write or Edit completes, mark prior Read outputs
+ * of the same file as stale so the model doesn't rely on outdated content.
+ *
+ * This doesn't replace the current tool output — it annotates previous Read
+ * records so that if they're re-read (dedup check), the stale content is flagged.
+ *
+ * For now, this strategy only adds a note to the current Write/Edit output
+ * reminding the model that prior reads of this file are now stale.
+ */
+
+import type { PruneResult, PruneStrategy, ToolRecord } from "./types.js";
+
+/** Tools that supersede prior reads. */
+const WRITE_TOOLS = new Set(["write", "edit"]);
+
+/** Extract the file path from tool args. */
+function getFilePath(args: Record<string, unknown>): string | undefined {
+  return (
+    (args.filePath as string) ??
+    (args.file_path as string) ??
+    (args.path as string) ??
+    undefined
+  );
+}
+
+export class SupersedeStrategy implements PruneStrategy {
+  name = "supersede" as const;
+
+  apply(
+    toolName: string,
+    args: Record<string, unknown>,
+    output: string,
+    history: ToolRecord[],
+  ): PruneResult {
+    const normalized = toolName.toLowerCase();
+
+    if (!WRITE_TOOLS.has(normalized)) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    const filePath = getFilePath(args);
+    if (!filePath) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    // Check if there are prior Read calls for this same file
+    const priorReads = history.filter((rec) => {
+      if (rec.toolName.toLowerCase() !== "read") return false;
+      const recPath = getFilePath(rec.args);
+      return recPath === filePath;
+    });
+
+    if (priorReads.length === 0) {
+      return { output, modified: false, bytesSaved: 0 };
+    }
+
+    // Annotate: prior reads of this file are now stale
+    const note = `\n[aide:supersede] Note: ${priorReads.length} prior Read(s) of "${filePath}" are now stale after this ${toolName}. Re-read if you need current content.`;
+    return {
+      output: output + note,
+      modified: true,
+      strategy: "supersede",
+      bytesSaved: 0, // We're adding, not saving bytes
+    };
+  }
+}