@herjarsa/omo-meta-governor 0.12.0 → 0.13.1

package/dist/custom-tools.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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";
+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>;
+};

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,94 @@
+/**
+ * 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;
+}
+/** 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";