@herjarsa/omo-meta-governor 0.12.1 → 0.14.0

package/dist/codegraph-tools.d.ts

@@ -0,0 +1,100 @@
+/**
+ * codegraph-tools — high-level wrappers around codegraph's sub-commands
+ * (node, callers, impact, files) for use in custom tools.
+ *
+ * codegraph is invoked via the `codegraph` CLI (not via MCP). Available
+ * sub-commands we wrap here:
+ *   - codegraph node <symbol>      → get source + callers of a symbol
+ *   - codegraph callers <symbol>   → list call sites of a symbol
+ *   - codegraph impact <symbol>    → full impact analysis (callers + tests + docs)
+ *   - codegraph files              → list indexed files
+ *
+ * v0.14.0 adds these on top of the v0.13.0 `omo_search` (which uses
+ * `codegraph explore`). Together they give the LLM a full codegraph
+ * toolkit: search, find, callers, impact, files.
+ *
+ * Design:
+ * - Pure CLI invocation via GraphRetrieval (which already handles
+ *   timeout, error catching, and graceful degradation)
+ * - Each function returns null when the tool is unavailable — the
+ *   caller decides what to do (e.g., suggest a fallback)
+ * - All functions take cwd + optional cli path override
+ */
+import { type GraphRetrieval } from "./graph-retrieval";
+export interface OmoFindResult {
+    /** The symbol that was searched */
+    symbol: string;
+    /** Source code of the definition (formatted) */
+    source: string | null;
+    /** List of call sites (file:line format) */
+    callers: Array<{
+        file: string;
+        line: number;
+        context: string;
+    }>;
+    /** True if the symbol was found */
+    found: boolean;
+    /** Tool that produced the result */
+    kind: "codegraph" | "graphify" | null;
+    /** Total time taken */
+    durationMs: number;
+}
+export interface OmoImpactResult {
+    /** The symbol being analyzed */
+    symbol: string;
+    /** Direct callers (file:line) */
+    directCallers: Array<{
+        file: string;
+        line: number;
+        context: string;
+    }>;
+    /** Transitive callers (if available from the tool) */
+    transitiveCallers: Array<{
+        file: string;
+        line: number;
+        context: string;
+    }>;
+    /** Test files affected (if available) */
+    testFiles: string[];
+    /** Documentation files affected (if available) */
+    docFiles: string[];
+    /** Total affected file count */
+    totalAffectedFiles: number;
+    /** Tool that produced the result */
+    kind: "codegraph" | "graphify" | null;
+    /** Total time taken */
+    durationMs: number;
+    /** Whether the analysis timed out */
+    timedOut: boolean;
+}
+export interface OmoFilesResult {
+    files: string[];
+    count: number;
+    kind: "codegraph" | "graphify" | null;
+    durationMs: number;
+}
+/**
+ * Default entry point: use the singleton GraphRetrieval.
+ * Tests can construct their own CodeGraphTools with a custom instance.
+ */
+export declare class CodeGraphTools {
+    private retrieval;
+    constructor(retrieval?: GraphRetrieval);
+    /**
+     * Find a symbol's definition and direct callers.
+     * Uses `codegraph node <symbol>` for codegraph, `graphify query <symbol>` for graphify.
+     */
+    find(symbol: string, cwd: string, timeoutMs?: number): Promise<OmoFindResult>;
+    /**
+     * Analyze the impact of changing a symbol. Lists direct callers,
+     * transitive callers, and affected test/doc files.
+     * Uses `codegraph impact <symbol>` if available, else `codegraph callers`.
+     */
+    impact(symbol: string, cwd: string, timeoutMs?: number): Promise<OmoImpactResult>;
+    /**
+     * List indexed files. Uses `codegraph files`.
+     */
+    listFiles(cwd: string, timeoutMs?: number): Promise<OmoFilesResult>;
+}
+/** Returns the process-wide CodeGraphTools singleton. */
+export declare function getDefaultCodeGraphTools(): CodeGraphTools;

package/dist/custom-tools.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Custom tools that omo-meta-governor registers for the LLM to invoke
+ * explicitly. v0.13.1 upgrade.
+ *
+ * Three tools:
+ * - `omo_search`  — semantic code search via codegraph/graphify
+ * - `omo_recall`  — search past lessons learned in this project's history
+ * - `omo_health`  — show plugin runtime status + metrics
+ *
+ * Design:
+ * - Tools are registered via the `tool` field in the returned Hooks object
+ * - All tools have Zod-validated args (typed at compile time)
+ * - Each tool calls into the modules we already built (GraphRetrieval, SqliteBackend)
+ * - Failure modes return a friendly string so the LLM can recover
+ *
+ * The key insight: instead of fire-and-forget invocations in tool.execute.before
+ * (v0.13.0), the LLM now EXPLICITLY chooses when to call these tools via its
+ * tool schema. This makes governance visible and intentional rather than
+ * ambient and invisible.
+ */
+import { type ToolContext, type ToolResult } from "@opencode-ai/plugin";
+import type { SqliteBackend } from "./sqlite-backend";
+import type { GraphRetrieval } from "./graph-retrieval";
+import type { MetricsCollector } from "./metrics";
+import { type CodeGraphTools } from "./codegraph-tools";
+export interface OmoSearchDeps {
+    graphRetrieval: GraphRetrieval;
+    cwd: string;
+}
+/**
+ * Build the `omo_search` tool. The LLM sees it in its tool schema with a
+ * description that biases it toward graph-first queries.
+ */
+export declare function buildOmoSearchTool(deps: OmoSearchDeps): {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        maxResults: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        query: string;
+        maxResults?: number | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoRecallDeps {
+    sqlite: SqliteBackend;
+}
+/**
+ * Build the `omo_recall` tool. The LLM uses this to retrieve lessons learned
+ * in past sessions, enabling genuine cross-session learning.
+ */
+export declare function buildOmoRecallTool(deps: OmoRecallDeps): {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        query: string;
+        limit?: number | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoHealthDeps {
+    metrics: MetricsCollector;
+    logFilePath: string;
+    healthFilePath: string;
+}
+/**
+ * Build the `omo_health` tool. Lets the agent (and the user) see exactly
+ * what the plugin is doing — closes the v0.10.0 "silent governance" complaint.
+ */
+export declare function buildOmoHealthTool(deps: OmoHealthDeps): {
+    description: string;
+    args: {};
+    execute(args: Record<string, never>, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoFindDeps {
+    codeGraph?: CodeGraphTools;
+    cwd: string;
+}
+/**
+ * Build the `omo_find` tool. Resolves a symbol to its source code location
+ * and lists direct call sites. Uses `codegraph node <symbol>` (with
+ * `graphify query <symbol>` as fallback when codegraph is unavailable).
+ */
+export declare function buildOmoFindTool(deps: OmoFindDeps): {
+    description: string;
+    args: {
+        symbol: import("zod").ZodString;
+    };
+    execute(args: {
+        symbol: string;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoImpactDeps {
+    codeGraph?: CodeGraphTools;
+    cwd: string;
+}
+/**
+ * Build the `omo_impact` tool. Lists all call sites of a symbol plus
+ * affected test and doc files. Uses `codegraph impact <symbol>` (falls
+ * back to `codegraph callers` when impact is unavailable).
+ */
+export declare function buildOmoImpactTool(deps: OmoImpactDeps): {
+    description: string;
+    args: {
+        symbol: import("zod").ZodString;
+    };
+    execute(args: {
+        symbol: string;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoRememberDeps {
+}
+/**
+ * Build the `omo_remember` tool. Persists a fact/observation/lesson to
+ * AgentMemory by instructing the LLM to call `agentmemory_memory_save`.
+ */
+export declare function buildOmoRememberTool(deps: OmoRememberDeps): {
+    description: string;
+    args: {
+        content: import("zod").ZodString;
+        concepts: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodString>>;
+        type: import("zod").ZodOptional<import("zod").ZodEnum<{
+            pattern: "pattern";
+            fact: "fact";
+            observation: "observation";
+        }>>;
+    };
+    execute(args: {
+        content: string;
+        concepts?: string[] | undefined;
+        type?: "pattern" | "fact" | "observation" | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoRecallMcpDeps {
+}
+/**
+ * Build the `omo_recall_mcp` tool. Searches AgentMemory by sending a
+ * query to the LLM that triggers `agentmemory_memory_smart_search`.
+ *
+ * Note: prefer `omo_recall` (which queries SQLite FTS5 locally) for fast
+ * local recall. Use `omo_recall_mcp` when you specifically need to search
+ * AgentMemory's persistent cross-session memory.
+ */
+export declare function buildOmoRecallMcpTool(deps: OmoRecallMcpDeps): {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    };
+    execute(args: {
+        query: string;
+        limit?: number | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoRuleDeps {
+}
+/**
+ * Build the `omo_rule` tool. Saves a durable rule to Magic Context that
+ * persists across sessions. Categorized by type (PROJECT_RULES, ARCHITECTURE,
+ * CONSTRAINTS, CONFIG_VALUES, NAMING). Uses `ctx_memory(action="write")`.
+ */
+export declare function buildOmoRuleTool(deps: OmoRuleDeps): {
+    description: string;
+    args: {
+        category: import("zod").ZodEnum<{
+            PROJECT_RULES: "PROJECT_RULES";
+            ARCHITECTURE: "ARCHITECTURE";
+            CONSTRAINTS: "CONSTRAINTS";
+            CONFIG_VALUES: "CONFIG_VALUES";
+            NAMING: "NAMING";
+        }>;
+        content: import("zod").ZodString;
+    };
+    execute(args: {
+        category: "PROJECT_RULES" | "ARCHITECTURE" | "CONSTRAINTS" | "CONFIG_VALUES" | "NAMING";
+        content: string;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoHistoryDeps {
+}
+/**
+ * Build the `omo_history` tool. Searches git commit history and prior
+ * conversations via Magic Context. Uses `ctx_search` with sources=["git_commit", "message"].
+ */
+export declare function buildOmoHistoryTool(deps: OmoHistoryDeps): {
+    description: string;
+    args: {
+        query: import("zod").ZodString;
+        sources: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodEnum<{
+            message: "message";
+            git_commit: "git_commit";
+        }>>>;
+    };
+    execute(args: {
+        query: string;
+        sources?: ("message" | "git_commit")[] | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};
+export interface OmoNoteDeps {
+}
+/**
+ * Build the `omo_note` tool. Writes a session-scoped working note via
+ * Magic Context. Notes are for the current task only (ephemeral context).
+ * Uses `ctx_note(action="write")`.
+ */
+export declare function buildOmoNoteTool(deps: OmoNoteDeps): {
+    description: string;
+    args: {
+        content: import("zod").ZodString;
+        surfaceCondition: import("zod").ZodOptional<import("zod").ZodString>;
+    };
+    execute(args: {
+        content: string;
+        surfaceCondition?: string | undefined;
+    }, context: ToolContext): Promise<ToolResult>;
+};

package/dist/file-logger.d.ts

@@ -1 +1,47 @@
+/**
+ * JSONL structured file logger with size-based rotation. v0.13.0 upgrade
+ * of the original text-based logger.
+ *
+ * Output format: one JSON object per line, with fields:
+ *   { timestamp, level, event, message, sessionID?, data? }
+ *
+ * Rotation: when the active log file exceeds MAX_FILE_SIZE_BYTES (10MB),
+ * the current file is renamed to .1, .1 to .2, etc. Files past MAX_ROTATED_FILES
+ * are deleted. Atomic on POSIX (rename is atomic for same-filesystem moves).
+ *
+ * Backwards compatibility: the existing `logToFile(level, message, data?)`
+ * API is preserved with 14 existing call sites. New code can use
+ * `logStructured({ level, event, message, ... })` for structured fields.
+ */
+declare const LOG_PATH: string;
+export type LogLevel = "info" | "warn" | "error";
+export interface LogEntry {
+    /** ISO 8601 timestamp. Auto-filled if omitted. */
+    timestamp?: string;
+    level: LogLevel;
+    /** Optional structured event name (e.g. "plugin_loaded", "intervention_delivered"). */
+    event?: string;
+    message: string;
+    /** Optional sessionID for correlation across logs. */
+    sessionID?: string;
+    /** Optional structured data (JSON-serializable). */
+    data?: unknown;
+}
+/**
+ * Legacy API — preserves the signature of the pre-0.13.0 logger so all 14
+ * existing call sites in src/plugin.ts continue to work unchanged.
+ */
 export declare function logToFile(level: "info" | "warn" | "error", message: string, data?: unknown): void;
+/**
+ * Structured API for new code. Adds `event` and `sessionID` fields.
+ */
+export declare function logStructured(entry: LogEntry): void;
+/**
+ * Returns the current log file size in bytes (for health monitoring).
+ */
+export declare function getLogFileSize(): number;
+/**
+ * Returns the number of rotated log files (e.g. 0-5).
+ */
+export declare function getRotatedLogCount(): number;
+export { LOG_PATH };

package/dist/graph-retrieval.d.ts

@@ -0,0 +1,120 @@
+/**
+ * GraphRetrieval — invokes codegraph/graphify and caches results for
+ * injection into the agent's context. v0.13.0 fix for C2: the plugin
+ * previously only told the agent to use graph tools via prompt text; now
+ * it actually invokes them and injects the results.
+ *
+ * Design:
+ * - Re-detects graph directories on EVERY call (fixes the race condition
+ *   in src/plugin.ts:74-81 where static booleans were set once at load time
+ *   before async `runGraphSync()` could create the directories).
+ * - Async with timeout (5s default) — never blocks tool.execute.before.
+ * - Per-session cache keyed by (sessionID, queryHash) with 5min TTL.
+ * - LRU eviction at 10 entries per session.
+ * - Graceful degradation: missing CLI → null result, errors are swallowed.
+ *
+ * Invocation strategy:
+ * - If `.codegraph/` exists and `codegraph` CLI is available: invoke `codegraph explore <query>`
+ * - Else if `graphify-out/` exists and `graphify` is available: invoke `graphify query <query>`
+ * - Else: return null
+ *
+ * The plugin can override CLI paths via the `invoke()` options for testing
+ * and for users who have the tools in non-standard locations.
+ */
+import { existsSync } from "node:fs";
+export type GraphToolKind = "codegraph" | "graphify" | null;
+export interface GraphInvocationResult {
+    /** Which tool was actually invoked. */
+    kind: GraphToolKind;
+    /** The query that was executed. */
+    query: string;
+    /** Result text from the tool, or null on failure / no-tool. */
+    result: string | null;
+    /** True if the subprocess was killed by timeout. */
+    timedOut: boolean;
+    /** Wall-clock duration in ms. */
+    durationMs: number;
+}
+export interface GraphRetrievalConfig {
+    /** Subprocess timeout in ms. Default: 5000. */
+    timeoutMs?: number;
+    /** Cache entry TTL in ms. Default: 300000 (5min). */
+    cacheTtlMs?: number;
+    /** Max cache entries per session. Default: 10. */
+    maxEntriesPerSession?: number;
+}
+export interface InvokeOptions {
+    /** Override codegraph CLI path (default: lookup in PATH). */
+    codegraphBin?: string;
+    /** Override graphify CLI path (default: lookup in PATH). */
+    graphifyBin?: string;
+    /** Override timeout for this call. */
+    timeoutMs?: number;
+}
+/** Deterministic hash for a query string. Used as cache key suffix. */
+export declare function hashQuery(query: string): string;
+export declare class GraphRetrieval {
+    private readonly timeoutMs;
+    private readonly cacheTtlMs;
+    private readonly maxEntriesPerSession;
+    private readonly cache;
+    constructor(config?: GraphRetrievalConfig);
+    /** Returns true if .codegraph/ exists in the project dir. */
+    hasCodegraphDir(projectDir: string): boolean;
+    /** Returns true if graphify-out/ exists in the project dir. */
+    hasGraphifyDir(projectDir: string): boolean;
+    /**
+     * Cache graph context for a session. The most recent entry per session is
+     * returned by `getCachedContext()` with no query arg (used by
+     * system.transform to inject the latest graph context).
+     */
+    cacheContext(sessionID: string, query: string, content: string): void;
+    /**
+     * Get cached context for a session.
+     * - If `query` is provided, returns the exact match (or null).
+     * - If `query` is omitted, returns the most recent non-expired entry.
+     */
+    getCachedContext(sessionID: string, query?: string): string | null;
+    clear(): void;
+    clearSession(sessionID: string): void;
+    /**
+     * Invoke a graph tool for the given query. Returns structured result.
+     * Never throws — all errors are caught and returned as `result: null`.
+     *
+     * Selection logic:
+     * 1. If `.codegraph/` exists and `codegraph` CLI is found → invoke codegraph
+     * 2. Else if `graphify-out/` exists and `graphify` CLI is found → invoke graphify
+     * 3. Else → return null result
+     */
+    invoke(projectDir: string, query: string, options?: InvokeOptions): Promise<GraphInvocationResult>;
+    private spawnWithTimeout;
+    /**
+     * Get the source code and direct callers of a symbol.
+     * Runs `codegraph node <symbol> --project-path <cwd>`.
+     */
+    invokeNode(symbol: string, projectDir: string, options?: InvokeOptions): Promise<GraphInvocationResult>;
+    /**
+     * List all call sites of a symbol.
+     * Runs `codegraph callers <symbol> --project-path <cwd>`.
+     */
+    invokeCallers(symbol: string, projectDir: string, options?: InvokeOptions): Promise<GraphInvocationResult>;
+    /**
+     * Full impact analysis: direct callers, transitive callers,
+     * affected test files, affected doc files.
+     * Runs `codegraph impact <symbol> --project-path <cwd>`.
+     */
+    invokeImpact(symbol: string, projectDir: string, options?: InvokeOptions): Promise<GraphInvocationResult>;
+    /**
+     * List all indexed files.
+     * Runs `codegraph files --project-path <cwd>`.
+     */
+    invokeFiles(projectDir: string, options?: InvokeOptions): Promise<GraphInvocationResult>;
+    /**
+     * Run a codegraph sub-command and return the result.
+     * Returns null result if codegraph is not available.
+     */
+    private invokeCodegraphSubcommand;
+}
+/** Returns the process-wide singleton, creating it on first use. */
+export declare function getDefaultGraphRetrieval(): GraphRetrieval;
+export { existsSync };

package/dist/health.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Plugin health state — observable proof that omo-meta-governor is doing work.
+ * Closes the C3/C4 invisibility gap: the user can `cat` the health JSON to
+ * see exactly what the plugin is doing, instead of wondering "is this thing
+ * alive?".
+ *
+ * Design:
+ * - Atomic writes (write to .tmp, then rename) — never produces partial reads
+ * - Pure functions: writeHealthToFile() and readHealthFromFile() take an
+ *   explicit path so they're testable without environment setup
+ * - Returns null on missing/malformed file (not throwing) — the health file
+ *   is observability, not a control plane; failure is non-fatal
+ */
+export interface PluginHealth {
+    version: string;
+    status: "healthy" | "degraded" | "error";
+    enabled: boolean;
+    startedAtISO: string;
+    uptimeMs: number;
+    metrics: {
+        decisionsTaken: number;
+        decisionsStored: number;
+        interventionsDelivered: number;
+        orchestratorRuns: number;
+        orchestratorErrors: number;
+        lastDecisionISO: string | null;
+        lastInterventionISO: string | null;
+    };
+    logFile: {
+        path: string;
+        sizeBytes: number;
+        rotatedFiles: number;
+    };
+    session: {
+        id: string;
+        toolCallsObserved: number;
+        violationsDetected: number;
+        interventionsSkipped: number;
+        firstSeenISO: string;
+        lastSeenISO: string;
+    };
+}
+/**
+ * Atomically write the health state to the given path. Writes to a
+ * .tmp sibling first, then renames. Creates parent directory if needed.
+ */
+export declare function writeHealthToFile(health: PluginHealth, path: string): void;
+/**
+ * Read the health state from the given path. Returns null on missing or
+ * malformed file. Never throws — the health file is observability, not
+ * a control plane.
+ */
+export declare function readHealthFromFile(path: string): PluginHealth | null;
+/**
+ * Compute the current log file size and rotated file count. Used to
+ * populate the `logFile` field in PluginHealth.
+ */
+export declare function describeLogFile(logPath: string): {
+    path: string;
+    sizeBytes: number;
+    rotatedFiles: number;
+};

package/dist/index.d.ts

@@ -36,5 +36,7 @@ export { loadProtocol, buildSystemInjection, auditToolCall, DEFAULT_PROTOCOL_PAT
 export { stripJsoncComments, parseJsonc, loadJsoncFile, deepMerge, loadMetaGovernorConfig, getUserConfigPath, getProjectConfigPath, type ConfigFileSources, type ConfigFileResult, } from "./config-file";
 export { runGraphSync, stopWatches, resetInitializedProjects, type GraphSyncConfig, type GraphSyncResult, type GraphSyncCode, type ToolAvailability, } from "./graph-sync";
 export { generateSchema, writeSchemaFile, type JsonSchema, type JsonSchemaProperty } from "./generate-schema";
+export { SqliteBackend, getDefaultSqliteBackend } from "./sqlite-backend";
+export { GraphRetrieval, getDefaultGraphRetrieval, hashQuery, type GraphToolKind, type GraphInvocationResult, type GraphRetrievalConfig, type InvokeOptions } from "./graph-retrieval";
 export { loadOrchestratorConfigFromSources } from "./config";
 export type { ProtocolViolation, ProtocolEnforcementSessionState } from "./types";