@jmylchreest/aide-plugin 0.0.40 → 0.0.43

package/package.json

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

package/skills/assess-findings/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: assess-findings
+description: Triage static analysis findings, assess merit, and accept noise or irrelevant items
+triggers:
+  - assess findings
+  - analyse findings
+  - analyze findings
+  - triage findings
+  - review findings
+  - accept findings
+  - dismiss findings
+  - clean up findings
+---
+
+# Assess Findings
+
+**Recommended model tier:** balanced (sonnet) - this skill requires reading code and making judgement calls
+
+Triage static analysis findings by reading the actual code, assessing whether each finding
+is genuine or noise, and accepting (dismissing) irrelevant ones using `findings_accept`.
+Accepted findings are hidden from future output by default.
+
+## Prerequisites
+
+- Findings must already exist. If `findings_stats` returns zero counts, tell the user to run:
+  ```bash
+  ./.aide/bin/aide findings run --path .
+  ```
+- The `findings_accept` tool must be available (provided by the aide MCP server).
+
+## Available Tools
+
+### Read-only (shared with `patterns` skill)
+
+| Tool              | Purpose                                                 |
+| ----------------- | ------------------------------------------------------- |
+| `findings_stats`  | Counts by analyzer and severity — start here            |
+| `findings_list`   | Browse findings with filters (analyzer, severity, file) |
+| `findings_search` | Full-text search across finding titles and details      |
+
+### Write (unique to this skill)
+
+| Tool              | Purpose                                             |
+| ----------------- | --------------------------------------------------- |
+| `findings_accept` | Mark findings as accepted/dismissed by ID or filter |
+
+### Code inspection
+
+| Tool           | Purpose                                             |
+| -------------- | --------------------------------------------------- |
+| `code_outline` | Get collapsed file structure to understand context  |
+| `Read`         | Read specific line ranges to evaluate finding merit |
+
+## Workflow
+
+### 1. Get the Landscape
+
+Call `findings_stats` to understand the scope:
+
+```
+findings_stats
+-> Returns: counts per analyzer (complexity, coupling, secrets, clones) and severity
+```
+
+If the user asked to focus on a specific analyzer or severity, note that and filter accordingly.
+Otherwise, work through all findings systematically.
+
+### 2. Prioritise Review Order
+
+Work through findings in this order:
+
+1. **Secrets** (critical first) — these need immediate attention; false positives are common in test fixtures
+2. **Complexity** (critical, then warning) — assess whether high complexity is inherent or decomposable
+3. **Clones** (all) — determine if duplication is extractable or structural boilerplate
+4. **Coupling** (all) — assess whether high fan-in/fan-out is expected for the file's role
+
+### 3. Assess Each Finding
+
+For each finding or group of related findings:
+
+1. **Read the finding details** — note the file, line range, and metric values
+2. **Read the actual code** — use `code_outline` first, then `Read` with offset/limit on the flagged section
+3. **Make a judgement call** using these criteria:
+
+#### Accept (dismiss) when:
+
+- **Complexity**: The function is inherently complex (CLI dispatch, protocol handling, state machines) and cannot be meaningfully decomposed without harming readability
+- **Clones**: The duplication is structural boilerplate (e.g., CLI subcommand wiring, store method patterns) where extraction would require framework-level abstraction
+- **Coupling**: High fan-in/fan-out is expected for the file's architectural role (e.g., a main entry point, a facade, a registry)
+- **Secrets**: The flagged string is a test fixture, example config, documentation placeholder, or env var name (not an actual secret)
+
+#### Keep (do NOT accept) when:
+
+- The finding points to a genuine problem that should be fixed
+- Complexity can be reduced by extracting helper functions
+- Duplication can be resolved by creating a shared utility
+- A coupling cycle exists that indicates poor module boundaries
+- A string looks like it could be a real secret or credential
+
+### 4. Accept Findings
+
+Use `findings_accept` to dismiss noise. You can accept:
+
+- **By IDs** — for individual findings after assessment:
+  ```
+  findings_accept ids=["finding-id-1", "finding-id-2"]
+  ```
+- **By filter** — for bulk dismissal of an entire category:
+  ```
+  findings_accept analyzer="clones" file="cmd/"
+  ```
+
+Always explain **why** each finding is being accepted before calling the tool.
+
+### 5. Report Summary
+
+After completing the triage, produce a summary:
+
+```markdown
+## Findings Triage Summary
+
+### Before
+
+- Total: X findings (Y critical, Z warnings, W info)
+
+### Accepted (Dismissed)
+
+- N findings accepted as noise/irrelevant
+  - Complexity: X (inherent complexity in [files])
+  - Clones: Y (structural boilerplate in [area])
+  - Coupling: Z (expected for [role])
+  - Secrets: W (test fixtures / placeholders)
+
+### Remaining (Genuine)
+
+- M findings require attention
+  - [List each with file:line and brief description]
+
+### Recommendations
+
+1. [Prioritised action items for genuine findings]
+```
+
+## Decision Criteria Reference
+
+| Analyzer   | Accept If                                                                                                                            | Keep If                                                         |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
+| complexity | Cyclomatic complexity is inherent to the problem domain; function handles unavoidable branching (CLI dispatch, protocol negotiation) | Function can be decomposed into smaller, testable units         |
+| clones     | Duplication is cross-cutting boilerplate (CLI wiring, store CRUD patterns)                                                           | A shared utility or abstraction would reduce maintenance burden |
+| coupling   | File is an intentional integration point (main, facade, registry)                                                                    | Circular dependencies or unexpected transitive coupling exists  |
+| secrets    | Test fixture, documentation example, env var name, or placeholder                                                                    | Looks like a real credential, API key, or connection string     |
+
+## Failure Handling
+
+1. **No findings** — Tell user to run `./.aide/bin/aide findings run --path .` first
+2. **`findings_accept` not available** — The aide MCP server may not expose this tool; tell the user to update aide
+3. **Uncertain about a finding** — When in doubt, **keep it**. It's better to flag a false positive for human review than to dismiss a real issue
+4. **Large number of findings** — Work in batches by analyzer. Accept obvious noise first, then do detailed code review for borderline cases
+
+## Verification
+
+- [ ] Called `findings_stats` for baseline counts
+- [ ] Reviewed each finding category (secrets, complexity, clones, coupling)
+- [ ] Read actual code for every finding before accepting
+- [ ] Provided rationale for each acceptance
+- [ ] Produced summary with before/after counts
+- [ ] Remaining findings are genuinely actionable

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/patterns/SKILL.md

@@ -10,7 +10,6 @@ triggers:
   - clones
   - secrets
   - coupling
-  - findings
   - static analysis
   - code health
 ---
@@ -47,6 +46,7 @@ Findings must be generated first by running analyzers via the CLI:
 Full-text search across all findings. Supports Bleve query syntax for advanced searches.
 
 **Parameters:**
+
 - `query` (required) — Search term or Bleve query
 - `analyzer` (optional) — Filter to one analyzer: `complexity`, `coupling`, `secrets`, `clones`
 - `severity` (optional) — Filter by severity: `info`, `warning`, `critical`
@@ -66,6 +66,7 @@ Search for: "high complexity"
 List findings with filters. Use when you want to browse rather than search.
 
 **Parameters:**
+
 - `analyzer` (optional) — Filter to one analyzer
 - `severity` (optional) — Filter by severity
 - `file` (optional) — Filter by file path substring
@@ -133,13 +134,13 @@ How healthy is the codebase?
 
 Beyond the automated analyzers, look for these patterns using findings as starting points:
 
-| Finding | Likely Anti-Pattern | Action |
-|---------|-------------------|--------|
-| Complexity > 20 | God function | Decompose into smaller functions |
-| Fan-out > 15 | Kitchen sink module | Split responsibilities |
-| Fan-in > 20 | Fragile dependency | Consider interface/abstraction |
-| Multiple clones | Copy-paste programming | Extract shared utility |
-| Import cycle | Circular dependency | Restructure module boundaries |
+| Finding         | Likely Anti-Pattern    | Action                           |
+| --------------- | ---------------------- | -------------------------------- |
+| Complexity > 20 | God function           | Decompose into smaller functions |
+| Fan-out > 15    | Kitchen sink module    | Split responsibilities           |
+| Fan-in > 20     | Fragile dependency     | Consider interface/abstraction   |
+| Multiple clones | Copy-paste programming | Extract shared utility           |
+| Import cycle    | Circular dependency    | Restructure module boundaries    |
 
 ## Output Format
 
@@ -147,18 +148,22 @@ Beyond the automated analyzers, look for these patterns using findings as starti
 ## Code Health Report
 
 ### Overview
+
 - Total findings: X (Y critical, Z warnings)
 - Top concern: [area/file with most issues]
 
 ### Hotspots
+
 1. **`file:line`** - [description] (severity)
    - Impact: [why this matters]
    - Recommendation: [what to do]
 
 ### Patterns Detected
+
 - [List of anti-patterns found with evidence]
 
 ### Recommendations
+
 1. [Prioritized action items]
 ```
 

package/src/cli/config.ts

@@ -51,7 +51,10 @@ export function readConfig(configPath: string): OpenCodeConfig {
   }
   try {
     const raw = readFileSync(configPath, "utf-8");
-    return JSON.parse(raw) as OpenCodeConfig;
+    const parsed: unknown = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+      return {};
+    return parsed as OpenCodeConfig;
   } catch {
     return {};
   }

package/src/core/aide-client.ts

@@ -8,7 +8,7 @@
  * platform-specific options instead of relying on CLAUDE_PLUGIN_ROOT.
  */
 
-import { execSync, execFileSync } from "child_process";
+import { execFileSync } from "child_process";
 import { existsSync, realpathSync } from "fs";
 import { join } from "path";
 import type { FindBinaryOptions } from "./types.js";
@@ -64,7 +64,10 @@ export function findAideBinary(opts: FindBinaryOptions = {}): string | null {
 
   // 4. PATH fallback
   try {
-    const result = execSync("which aide", { stdio: "pipe", timeout: 2000 })
+    const result = execFileSync("which", ["aide"], {
+      stdio: "pipe",
+      timeout: 2000,
+    })
       .toString()
       .trim();
     if (result) return result;
@@ -187,15 +190,15 @@ export function clearAgentState(
 }
 
 /**
- * Escape a string for safe shell usage (when shell is unavoidable)
+ * Sanitize a string for safe inclusion in log messages and CLI arguments.
+ *
+ * Strips control characters and limits length. This is NOT shell escaping —
+ * use execFileSync (which avoids shells entirely) for subprocess execution.
  */
-export function shellEscape(str: string): string {
-  return str
-    .replace(/\\/g, "\\\\")
-    .replace(/"/g, '\\"')
-    .replace(/\$/g, "\\$")
-    .replace(/`/g, "\\`")
-    .replace(/!/g, "\\!")
-    .replace(/\n/g, " ")
-    .slice(0, 1000);
+export function sanitizeForLog(str: string): string {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 1000);
 }
+
+/** @deprecated Use sanitizeForLog instead */
+export const shellEscape = sanitizeForLog;

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";