opencode-autognosis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Julian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# opencode-autognosis
+
+**Self-knowledge for your codebase.** A suite of tools for OpenCode that enables rapid discovery, structural search, and safe iteration.
+
+This plugin transforms your agent from a file-reader into a "Miniature Engineer" capable of understanding project structure, navigating by symbols, and planning changes safely.
+
+## Prerequisites
+
+This plugin relies on the following high-performance system binaries. Please ensure they are installed and in your PATH:
+
+- **ripgrep (`rg`)**: For fast content searching.
+- **fd (`fd`)**: For fast file finding.
+- **ast-grep (`sg`)**: For structural code search.
+- **universal-ctags (`ctags`)**: For symbol indexing.
+- **git**: For version control integration.
+
+## Installation
+
+### Via npm (Recommended)
+
+1. Install the package:
+   ```bash
+   npm install opencode-autognosis
+   ```
+
+2. Configure `opencode.json`:
+   ```json
+   {
+     "plugin": ["opencode-autognosis"]
+   }
+   ```
+
+### Local Plugin
+
+1. Clone this repository.
+2. Build the plugin:
+   ```bash
+   npm install
+   npm run build
+   ```
+3. Copy `dist/index.js` to your project's `.opencode/plugins/autognosis.js` (or reference the build directory).
+
+## End-to-End Demo
+
+Here is how the "Miniature Engineer" workflow looks in practice:
+
+1.  **Initialize & Plan**:
+    ```javascript
+    // Agent initializes environment and gets a plan ID
+    autognosis_init({ mode: "apply", token: "..." })
+    brief_fix_loop({ symbol: "AuthService", intent: "refactor" })
+    // Returns: { plan_id: "plan-123", ... }
+    ```
+
+2.  **Navigate & Read**:
+    ```javascript
+    // Agent jumps to definition using the plan ID
+    jump_to_symbol({ symbol: "AuthService", plan_id: "plan-123" })
+    // Returns: { resolved_location: "src/auth.ts", slice: "..." }
+    ```
+
+3.  **Propose Change**:
+    ```javascript
+    // Agent edits file (via standard write_file or replace)
+    // Then captures the change as a patch artifact
+    prepare_patch({ plan_id: "plan-123", message: "Refactor login method" })
+    // Returns: "Patch saved to .opencode/cache/patch-123.diff"
+    ```
+
+4.  **Validate**:
+    ```javascript
+    // Agent ensures the patch is valid before committing
+    validate_patch({ patch_path: ".opencode/cache/patch-123.diff" })
+    // Returns: { status: "SUCCESS", checks: { git_apply_check: "passed" } }
+    ```
+
+5.  **Finalize**:
+    ```javascript
+    // Agent closes the loop
+    finalize_plan({ plan_id: "plan-123", outcome: "success" })
+    // Returns: "Plan finalized. Metrics logged."
+    ```
+
+## Tools Capabilities
+
+### Discovery & Navigation
+- **`fast_search`**: Optimized text search using `rg` (content) and `fd` (files). Enforces "filename-first" discovery.
+- **`structural_search`**: Find code by grammatical pattern using `ast-grep`.
+- **`symbol_query`**: Instant symbol lookup using a content-addressable tags index.
+- **`jump_to_symbol`**: The primary navigation tool. Resolves a symbol and returns a bounded "slice" of code.
+- **`read_slice`**: Efficiently reads specific line ranges from files.
+
+### Engineering Workflow
+- **`brief_fix_loop`**: Generates a bounded **Plan** containing the definition, dependents, and context.
+- **`prepare_patch`**: Generates a `.diff` artifact for the current changes.
+- **`validate_patch`**: Validates a patch in a clean git worktree.
+- **`finalize_plan`**: Closes the session loop, logs metrics, and cleans up the cache.
+
+## Initialization
+
+Run the initialization tool to verify your environment:
+
+```javascript
+autognosis_init() // Default mode="plan"
+```
+
+This will check for required binaries and provide a token to confirm initialization.

package/assets/patterns.json

@@ -0,0 +1,9 @@
+{
+  "patterns": [
+    {
+      "name": "todo_comments",
+      "pattern": "TODO:",
+      "description": "Find TODO comments"
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,212 @@
+export default function plugin(): {
+    tools: {
+        autognosis_init: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    mode: {
+                        type: string;
+                        enum: string[];
+                        default: string;
+                    };
+                    token: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ mode, token }: {
+                mode: string;
+                token?: string;
+            }) => Promise<string | undefined>;
+        };
+        fast_search: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    query: {
+                        type: string;
+                    };
+                    mode: {
+                        type: string;
+                        enum: string[];
+                        default: string;
+                    };
+                    path: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ query, mode, path: searchPath }: {
+                query: string;
+                mode?: string;
+                path?: string;
+            }) => Promise<string>;
+        };
+        structural_search: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    pattern: {
+                        type: string;
+                    };
+                    path: {
+                        type: string;
+                        default: string;
+                    };
+                    plan_id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ pattern, path: searchPath, plan_id }: {
+                pattern: string;
+                path?: string;
+                plan_id?: string;
+            }) => Promise<string>;
+        };
+        read_slice: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    file: {
+                        type: string;
+                    };
+                    start_line: {
+                        type: string;
+                    };
+                    end_line: {
+                        type: string;
+                    };
+                    plan_id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ file, start_line, end_line, plan_id }: {
+                file: string;
+                start_line: number;
+                end_line: number;
+                plan_id?: string;
+            }) => Promise<string>;
+        };
+        symbol_query: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    symbol: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ symbol }: {
+                symbol: string;
+            }) => Promise<string>;
+        };
+        jump_to_symbol: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    symbol: {
+                        type: string;
+                    };
+                    plan_id: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ symbol, plan_id }: {
+                symbol: string;
+                plan_id?: string;
+            }) => Promise<string>;
+        };
+        brief_fix_loop: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    symbol: {
+                        type: string;
+                    };
+                    intent: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ symbol, intent }: {
+                symbol: string;
+                intent: string;
+            }) => Promise<string>;
+        };
+        prepare_patch: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    plan_id: {
+                        type: string;
+                    };
+                    message: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ plan_id, message }: {
+                plan_id?: string;
+                message: string;
+            }) => Promise<string>;
+        };
+        validate_patch: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    patch_path: {
+                        type: string;
+                    };
+                    timeout_ms: {
+                        type: string;
+                        default: number;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ patch_path, timeout_ms }: {
+                patch_path: string;
+                timeout_ms?: number;
+            }) => Promise<string>;
+        };
+        finalize_plan: {
+            description: string;
+            parameters: {
+                type: string;
+                properties: {
+                    plan_id: {
+                        type: string;
+                    };
+                    outcome: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            execute: ({ plan_id, outcome }: {
+                plan_id: string;
+                outcome: string;
+            }) => Promise<string>;
+        };
+    };
+};

package/dist/index.js

@@ -0,0 +1,8 @@
+import { systemTools } from "./system-tools.js";
+export default function plugin() {
+    return {
+        tools: {
+            ...systemTools(),
+        },
+    };
+}

package/dist/system-tools.d.ts

@@ -0,0 +1,210 @@
+export declare function systemTools(): {
+    autognosis_init: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                mode: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                token: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ mode, token }: {
+            mode: string;
+            token?: string;
+        }) => Promise<string | undefined>;
+    };
+    fast_search: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                query: {
+                    type: string;
+                };
+                mode: {
+                    type: string;
+                    enum: string[];
+                    default: string;
+                };
+                path: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ query, mode, path: searchPath }: {
+            query: string;
+            mode?: string;
+            path?: string;
+        }) => Promise<string>;
+    };
+    structural_search: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                pattern: {
+                    type: string;
+                };
+                path: {
+                    type: string;
+                    default: string;
+                };
+                plan_id: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ pattern, path: searchPath, plan_id }: {
+            pattern: string;
+            path?: string;
+            plan_id?: string;
+        }) => Promise<string>;
+    };
+    read_slice: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                file: {
+                    type: string;
+                };
+                start_line: {
+                    type: string;
+                };
+                end_line: {
+                    type: string;
+                };
+                plan_id: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ file, start_line, end_line, plan_id }: {
+            file: string;
+            start_line: number;
+            end_line: number;
+            plan_id?: string;
+        }) => Promise<string>;
+    };
+    symbol_query: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                symbol: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ symbol }: {
+            symbol: string;
+        }) => Promise<string>;
+    };
+    jump_to_symbol: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                symbol: {
+                    type: string;
+                };
+                plan_id: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ symbol, plan_id }: {
+            symbol: string;
+            plan_id?: string;
+        }) => Promise<string>;
+    };
+    brief_fix_loop: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                symbol: {
+                    type: string;
+                };
+                intent: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ symbol, intent }: {
+            symbol: string;
+            intent: string;
+        }) => Promise<string>;
+    };
+    prepare_patch: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                plan_id: {
+                    type: string;
+                };
+                message: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ plan_id, message }: {
+            plan_id?: string;
+            message: string;
+        }) => Promise<string>;
+    };
+    validate_patch: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                patch_path: {
+                    type: string;
+                };
+                timeout_ms: {
+                    type: string;
+                    default: number;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ patch_path, timeout_ms }: {
+            patch_path: string;
+            timeout_ms?: number;
+        }) => Promise<string>;
+    };
+    finalize_plan: {
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                plan_id: {
+                    type: string;
+                };
+                outcome: {
+                    type: string;
+                };
+            };
+            required: string[];
+        };
+        execute: ({ plan_id, outcome }: {
+            plan_id: string;
+            outcome: string;
+        }) => Promise<string>;
+    };
+};

package/dist/system-tools.js

@@ -0,0 +1,256 @@
+import { exec } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import * as path from "node:path";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import * as crypto from "node:crypto";
+const execAsync = promisify(exec);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = process.cwd();
+const OPENCODE_DIR = path.join(PROJECT_ROOT, ".opencode");
+const CACHE_DIR = path.join(OPENCODE_DIR, "cache");
+const ASSETS_DIR = path.join(__dirname, "../assets");
+let pendingInitToken = null;
+let pendingInitPlan = null;
+async function runCmd(cmd, cwd = PROJECT_ROOT, timeoutMs = 30000) {
+    try {
+        const { stdout, stderr } = await execAsync(cmd, { cwd, maxBuffer: 10 * 1024 * 1024, timeout: timeoutMs });
+        return { stdout: stdout.trim(), stderr: stderr.trim() };
+    }
+    catch (error) {
+        if (error.signal === 'SIGTERM' && error.code === undefined) {
+            return { stdout: "", stderr: `Command timed out after ${timeoutMs}ms`, error, timedOut: true };
+        }
+        return { stdout: "", stderr: error.message, error };
+    }
+}
+async function checkBinary(bin) {
+    const { error } = await runCmd(`${bin} --version`, PROJECT_ROOT, 5000);
+    return !error;
+}
+async function getPatterns() {
+    const patternsPath = path.join(ASSETS_DIR, "patterns.json");
+    try {
+        const content = await fs.readFile(patternsPath, "utf-8");
+        return JSON.parse(content).patterns || [];
+    }
+    catch (e) {
+        return [];
+    }
+}
+async function ensureCache() {
+    await fs.mkdir(CACHE_DIR, { recursive: true });
+}
+async function cleanCache() {
+    try {
+        const files = await fs.readdir(CACHE_DIR);
+        const now = Date.now();
+        const MAX_AGE = 7 * 24 * 60 * 60 * 1000;
+        let deleted = 0;
+        for (const file of files) {
+            const filePath = path.join(CACHE_DIR, file);
+            const stats = await fs.stat(filePath);
+            if (now - stats.mtimeMs > MAX_AGE) {
+                await fs.unlink(filePath);
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    catch (e) {
+        return 0;
+    }
+}
+async function maintainSymbolIndex() {
+    await ensureCache();
+    if (!(await checkBinary("ctags"))) {
+        return { rebuilt: false, status: "unavailable", reason: "ctags binary missing" };
+    }
+    const tagsFile = path.join(CACHE_DIR, "tags");
+    const fingerprintFile = path.join(CACHE_DIR, "tags.fingerprint");
+    const { stdout: head } = await runCmd("git rev-parse HEAD");
+    const { stdout: status } = await runCmd("git status --porcelain");
+    const currentFingerprint = `${head}\n${status}`;
+    let storedFingerprint = "";
+    try {
+        storedFingerprint = await fs.readFile(fingerprintFile, "utf-8");
+    }
+    catch (e) { }
+    if (currentFingerprint !== storedFingerprint || !fsSync.existsSync(tagsFile)) {
+        const { error, stderr } = await runCmd(`ctags -R -f ${tagsFile} --languages=TypeScript,JavaScript,Python,Go,Rust,C++,C .`, PROJECT_ROOT);
+        if (error) {
+            return { rebuilt: false, status: "failed", reason: stderr };
+        }
+        await fs.writeFile(fingerprintFile, currentFingerprint);
+        return { rebuilt: true, status: "ok" };
+    }
+    return { rebuilt: false, status: "ok" };
+}
+export function systemTools() {
+    return {
+        autognosis_init: {
+            description: "Initialize or check the Autognosis environment. Two-phase: 'plan' (default) generates a token, 'apply' executes it.",
+            parameters: { type: "object", properties: { mode: { type: "string", enum: ["plan", "apply"], default: "plan" }, token: { type: "string" } }, required: ["mode"] },
+            execute: async ({ mode = "plan", token }) => {
+                if (mode === "plan") {
+                    const checks = { rg: await checkBinary("rg"), fd: await checkBinary("fd"), sg: await checkBinary("sg"), ctags: await checkBinary("ctags"), git: await checkBinary("git") };
+                    const actions = [];
+                    if (!fsSync.existsSync(CACHE_DIR))
+                        actions.push(`Create cache directory: ${CACHE_DIR}`);
+                    else
+                        actions.push(`Verify cache directory: ${CACHE_DIR} (exists)`);
+                    const newToken = crypto.randomBytes(4).toString("hex");
+                    pendingInitToken = newToken;
+                    pendingInitPlan = { checks, actions };
+                    return JSON.stringify({ status: "PLAN_READY", system_checks: checks, planned_actions: actions, confirm_token: newToken, instruction: "Review the plan. To execute, call autognosis_init(mode='apply', token='...')" }, null, 2);
+                }
+                else if (mode === "apply") {
+                    if (!pendingInitToken || !token || token !== pendingInitToken)
+                        return JSON.stringify({ status: "ERROR", message: "Invalid or expired confirmation token. Run mode='plan' first." });
+                    await ensureCache();
+                    pendingInitToken = null;
+                    pendingInitPlan = null;
+                    return JSON.stringify({ status: "SUCCESS", message: "Autognosis initialized.", cache_dir: CACHE_DIR });
+                }
+            }
+        },
+        fast_search: {
+            description: "Fast content or filename search using ripgrep (rg) and fd.",
+            parameters: { type: "object", properties: { query: { type: "string" }, mode: { type: "string", enum: ["filename", "content"], default: "filename" }, path: { type: "string" } }, required: ["query"] },
+            execute: async ({ query, mode = "filename", path: searchPath = "." }) => {
+                if (mode === "content") {
+                    if (!(await checkBinary("rg")))
+                        return "Error: 'rg' (ripgrep) is not installed. fast_search content mode unavailable.";
+                    const { stdout } = await runCmd(`rg -n --column "${query}" "${searchPath}"`);
+                    if (!stdout)
+                        return "No matches found.";
+                    return stdout.split('\n').slice(0, 50).join('\n') + (stdout.split('\n').length > 50 ? "\n... (truncated)" : "");
+                }
+                else {
+                    if (!(await checkBinary("fd")))
+                        return "Error: 'fd' is not installed. fast_search filename mode unavailable.";
+                    const { stdout } = await runCmd(`fd "${query}" "${searchPath}"`);
+                    if (!stdout)
+                        return "No files found.";
+                    return stdout.split('\n').slice(0, 50).join('\n') + (stdout.split('\n').length > 50 ? "\n... (truncated)" : "");
+                }
+            }
+        },
+        structural_search: {
+            description: "Search code using ast-grep patterns or patterns.json IDs.",
+            parameters: { type: "object", properties: { pattern: { type: "string" }, path: { type: "string", default: "." }, plan_id: { type: "string" } }, required: ["pattern"] },
+            execute: async ({ pattern, path: searchPath = ".", plan_id }) => {
+                if (!(await checkBinary("sg")))
+                    return JSON.stringify({ error: "Degraded Mode: 'sg' (ast-grep) not found.", results: [], plan_id: plan_id || "OFF-PLAN" });
+                const knownPatterns = await getPatterns();
+                const known = knownPatterns.find((p) => p.name === pattern);
+                const cmd = known ? `sg scan -p "${known.pattern}" "${searchPath}" --json` : `sg scan -p "${pattern}" "${searchPath}" --json`;
+                const { stdout } = await runCmd(cmd);
+                let results = [];
+                try {
+                    results = JSON.parse(stdout);
+                }
+                catch (e) { }
+                return JSON.stringify({ results: results.slice(0, 50), truncated: results.length > 50, plan_id: plan_id || "OFF-PLAN" }, null, 2);
+            }
+        },
+        read_slice: {
+            description: "Read a specific slice of a file.",
+            parameters: { type: "object", properties: { file: { type: "string" }, start_line: { type: "number" }, end_line: { type: "number" }, plan_id: { type: "string" } }, required: ["file", "start_line", "end_line"] },
+            execute: async ({ file, start_line, end_line, plan_id }) => {
+                const { stdout, stderr } = await runCmd(`sed -n '${start_line},${end_line}p;${end_line + 1}q' "${file}"`);
+                if (stderr)
+                    return `Error reading slice: ${stderr}`;
+                return JSON.stringify({ file, start_line, end_line, content: stdout, plan_id: plan_id || "OFF-PLAN" }, null, 2);
+            }
+        },
+        symbol_query: {
+            description: "Query the symbol index. Rebuilds automatically if stale.",
+            parameters: { type: "object", properties: { symbol: { type: "string" } }, required: ["symbol"] },
+            execute: async ({ symbol }) => {
+                const maint = await maintainSymbolIndex();
+                if (maint.status === "unavailable")
+                    return JSON.stringify({ error: "Symbol index unavailable", reason: maint.reason });
+                const tagsFile = path.join(CACHE_DIR, "tags");
+                if (await checkBinary("readtags")) {
+                    const { stdout } = await runCmd(`readtags -t "${tagsFile}" "${symbol}"`);
+                    return JSON.stringify({ matches: stdout.split('\n').filter(Boolean), metadata: maint }, null, 2);
+                }
+                else {
+                    const { stdout: grepOut } = await runCmd(`grep -P "^${symbol}\t" "${tagsFile}"`);
+                    return JSON.stringify({ matches: grepOut.split('\n').filter(Boolean), metadata: maint, note: "using_grep_fallback" }, null, 2);
+                }
+            }
+        },
+        jump_to_symbol: {
+            description: "Jump to a symbol's definition by querying the index and reading the slice.",
+            parameters: { type: "object", properties: { symbol: { type: "string" }, plan_id: { type: "string" } }, required: ["symbol"] },
+            execute: async ({ symbol, plan_id }) => {
+                const maint = await maintainSymbolIndex();
+                if (maint.status !== "ok")
+                    return JSON.stringify({ error: "Index unavailable", reason: maint.reason });
+                const tagsFile = path.join(CACHE_DIR, "tags");
+                const { stdout: tagLine } = await runCmd(`grep -P "^${symbol}\t" "${tagsFile}" | head -n 1`);
+                if (!tagLine)
+                    return JSON.stringify({ found: false, symbol });
+                const parts = tagLine.split('\t');
+                const file = parts[1];
+                let line = 1;
+                const { stdout: grepLine } = await runCmd(`grep -n "${symbol}" "${file}" | head -n 1`);
+                if (grepLine)
+                    line = parseInt(grepLine.split(':')[0], 10);
+                const start = Math.max(1, line - 5);
+                const end = line + 15;
+                const { stdout: slice } = await runCmd(`sed -n '${start},${end}p;${end + 1}q' "${file}"`);
+                return JSON.stringify({ symbol, resolved_location: { file, line }, slice: { start, end, content: slice }, plan_id: plan_id || "OFF-PLAN" }, null, 2);
+            }
+        },
+        brief_fix_loop: {
+            description: "The Action Planner. Generates a bounded worklist for a symbol and intent.",
+            parameters: { type: "object", properties: { symbol: { type: "string" }, intent: { type: "string" } }, required: ["symbol", "intent"] },
+            execute: async ({ symbol, intent }) => {
+                const planId = `plan-${Date.now()}-${crypto.randomBytes(2).toString("hex")}`;
+                return JSON.stringify({ plan_id: planId, symbol, intent, status: "PLAN_GENERATED", instructions: "Use this plan_id for all subsequent operations.", mock_worklist: [{ file: "src/example.ts", reason: "Direct dependency", heat: "high" }] }, null, 2);
+            }
+        },
+        prepare_patch: {
+            description: "Generate a .diff artifact for the current changes, tied to a plan.",
+            parameters: { type: "object", properties: { plan_id: { type: "string" }, message: { type: "string" } }, required: ["message"] },
+            execute: async ({ plan_id, message }) => {
+                await ensureCache();
+                const patchPath = path.join(CACHE_DIR, `patch-${Date.now()}.diff`);
+                const { stdout } = await runCmd("git diff");
+                if (!stdout)
+                    return "No changes to patch.";
+                const content = `// META: plan_id=${plan_id || "NONE"}\n// META: message=${message}\n\n${stdout}`;
+                await fs.writeFile(patchPath, content);
+                return `Patch saved to ${patchPath}`;
+            }
+        },
+        validate_patch: {
+            description: "Validate a patch by applying it in a fresh worktree. Enforces timeout.",
+            parameters: { type: "object", properties: { patch_path: { type: "string" }, timeout_ms: { type: "number", default: 30000 } }, required: ["patch_path"] },
+            execute: async ({ patch_path, timeout_ms = 30000 }) => {
+                const start = Date.now();
+                const { error, timedOut } = await runCmd(`git apply --check "${patch_path}"`, PROJECT_ROOT, timeout_ms);
+                if (timedOut)
+                    return JSON.stringify({ status: "TIMEOUT", checked: ["git_apply_check"], failed_at: "git_apply_check", duration: Date.now() - start });
+                if (error)
+                    return JSON.stringify({ status: "FAILED", checks: { git_apply_check: "failed" }, error: error.message });
+                return JSON.stringify({ status: "SUCCESS", checks: { git_apply_check: "passed" }, duration: Date.now() - start, note: "Patch is valid against current HEAD." }, null, 2);
+            }
+        },
+        finalize_plan: {
+            description: "Finalize a plan, logging metrics and cleaning cache.",
+            parameters: { type: "object", properties: { plan_id: { type: "string" }, outcome: { type: "string" } }, required: ["plan_id", "outcome"] },
+            execute: async ({ plan_id, outcome }) => {
+                await ensureCache();
+                const report = { plan_id, outcome, time: new Date().toISOString() };
+                await fs.appendFile(path.join(CACHE_DIR, "gaps.jsonl"), JSON.stringify(report) + "\n");
+                const deleted = await cleanCache();
+                return `Plan finalized. Metrics logged. Cache hygiene: deleted ${deleted} old items.`;
+            }
+        }
+    };
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "opencode-autognosis",
+  "version": "0.1.0",
+  "description": "Transforms OpenCode agents into 'miniature engineers' with deep codebase awareness. Includes fast structural search (ast-grep), instant symbol navigation (ctags), and a disciplined 'Plan → Execute → Patch' workflow.",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "assets",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "typescript": "^5.0.0"
+  }
+}