@herjarsa/omo-meta-governor 0.9.8 → 0.10.0

package/README.md

@@ -38,11 +38,28 @@ After every tool call, MetaGovernor:
 
 See [docs/guide/meta-governor.md](docs/guide/meta-governor.md) for full docs.
 
-## Intervention (v0.3.0)
+## Intervention
 
 MetaGovernor can inject its decisions into the active agent's context
 so the agent is aware of governance warnings, escalations, or stop signals.
 
+### v0.10.0 — Loop prevention
+
+The plugin now self-disables intervention when the agent's task is verifiably
+complete. This fixes the v0.3.0–v0.9.x bug where the plugin kept injecting
+synthetic user messages indefinitely after the agent had finished.
+
+Three mechanisms enforce the cap:
+
+1. **`<promise>DONE</promise>` + Oracle verified** — the agent emits this signal
+   to mark the task complete. If Oracle has verified the work (the agent
+   invoked `task(subagent_type="oracle")` and got a PASS verdict), the plugin
+   disables intervention for that session.
+2. **`maxInterventionsPerSession`** — hard cap (default `3`) on the number of
+   times a session can receive an injection. Once reached, no more injections.
+3. **Cross-session scoping** — decisions are now scoped to the current
+   sessionID. The plugin no longer pulls decisions from unrelated sessions.
+
 ### Modes
 
 | Mode | Mechanism | Effect |
@@ -61,20 +78,24 @@ so the agent is aware of governance warnings, escalations, or stop signals.
       "mode": "message",
       "includeDecisionHistory": true,
       "maxHistoryMessages": 5,
-      "minActionForMessage": "warn"
+      "minActionForMessage": "stop",
+      "maxInterventionsPerSession": 3,
+      "respectDoneSignal": true
     }
   }
 }
-
 ```
 
+### Fields
+
 | Field | Default | Description |
 |-------|---------|-------------|
 | `mode` | `"silent"` | How to inject: `"silent"`, `"message"`, or `"system"` |
 | `includeDecisionHistory` | `true` | Whether to include recent decision history |
 | `maxHistoryMessages` | `5` | Max history entries when includeDecisionHistory is true |
-| `minActionForMessage` | `"warn"` | Minimum action: `"warn"` (all non-continue), `"escalate"`, or `"stop"` |
-
+| `minActionForMessage` | `"stop"` (v0.10.0) | Minimum action: `"warn"`, `"escalate"`, or `"stop"`. Default is now `"stop"` so warnings do not auto-trigger injection. Opt UP to `"warn"` explicitly. |
+| `maxInterventionsPerSession` | `3` (v0.10.0) | Hard cap on injections per session. Once reached, no more injections until session restart. |
+| `respectDoneSignal` | `true` (v0.10.0) | When true, the plugin stops injecting the moment the agent emits `<promise>DONE</promise>` AND Oracle has verified the work. |
 ### How it works
 
 1. After every tool call, MetaGovernor runs the orchestrator pipeline.

package/dist/closed-loop-learning.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Closed-loop learning for MetaGovernor.
+ *
+ * PR 3 of 8. After every repair/action cycle, observeAndLearn() decides
+ * whether to persist a lesson or decision record to agentmemory. Future
+ * sessions retrieve these via aggregateRead() (PR 2) and factor them into
+ * scoring (PR 5).
+ *
+ * Design:
+ * - Pure function with DI backend (no side effects without backend).
+ * - config.enabled=false → returns no-op with reason.
+ * - Severity threshold: minSeverityToLearn filters what gets saved.
+ * - Session cap: maxLessonsPerSession prevents flooding.
+ * - Lessons go to agentmemory_memory_save (type: "pattern").
+ * - Decisions go to agentmemory_memory_save (type: "fact").
+ * - No file I/O, no MCP calls — just decision logic + DI write.
+ */
+import type { AgentmemoryWriteBackend, ClosedLoopConfig, LearnFromOutcomeInput, LearnFromOutcomeOutput } from "./types";
+/** Severity ordering for threshold comparison. */
+declare const SEVERITY_ORDER: Record<string, number>;
+/**
+ * Core learning function. Decides whether to save a lesson and/or decision
+ * to agentmemory based on the outcome of a repair/action cycle.
+ *
+ * Returns LearnFromOutcomeOutput describing what was saved (or why nothing was saved).
+ */
+export declare function observeAndLearn(input: LearnFromOutcomeInput, backend: AgentmemoryWriteBackend): Promise<LearnFromOutcomeOutput>;
+/**
+ * Helper: create a default ClosedLoopConfig.
+ */
+export declare function defaultClosedLoopConfig(): ClosedLoopConfig;
+export { SEVERITY_ORDER };

package/dist/config-file.d.ts

@@ -0,0 +1,71 @@
+/**
+ * JSONC config file loader for omo-meta-governor.
+ *
+ * Loads `omo-meta-governor.jsonc` from three layers (closer wins):
+ *   1. CLI inline options (opts object) — highest priority
+ *   2. Project config: `.opencode/omo-meta-governor.jsonc`
+ *   3. User config: `~/.config/opencode/omo-meta-governor.jsonc`
+ *   4. Defaults — lowest priority
+ *
+ * JSONC support: comments (//, /* * /) and trailing commas are stripped
+ * before parsing. The raw JSON object is then projected into
+ * `MetaGovernorPluginConfig` via `loadOrchestratorConfig()`.
+ */
+import type { MetaGovernorPluginConfig } from "./config";
+/**
+ * Strip JSONC comments (single-line // style and multi-line bracket style)
+ * and trailing commas from a JSONC string so it can be parsed by JSON.parse.
+ *
+ * Handles:
+ *   - // single-line comments
+ *   - /asterisk ... asterisk/ multi-line comments
+ *   - Trailing commas before ] or }
+ *   - Strings containing comments (preserved)
+ */
+export declare function stripJsoncComments(jsonc: string): string;
+/**
+ * Parse a JSONC string into a JavaScript object.
+ * Returns undefined on parse failure.
+ */
+export declare function parseJsonc<T = Record<string, unknown>>(jsonc: string): T | undefined;
+/**
+ * Get the user-level config file path.
+ */
+export declare function getUserConfigPath(): string;
+/**
+ * Get the project-level config file path for a given project directory.
+ */
+export declare function getProjectConfigPath(projectDir?: string): string;
+/**
+ * Read and parse a single JSONC config file.
+ * Returns undefined if the file does not exist or is unparseable.
+ */
+export declare function loadJsoncFile<T = Record<string, unknown>>(filePath: string): Promise<T | undefined>;
+/**
+ * Deep-merge two config objects. Arrays are replaced (not concatenated).
+ * The `source` values win when both exist.
+ * Mutually recursive with mergeArrays=false for sub-objects.
+ */
+export declare function deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
+export interface ConfigFileSources {
+    /** CLI inline options (highest priority) */
+    cliOptions?: Partial<MetaGovernorPluginConfig>;
+    /** Project directory for project-level config lookup */
+    projectDir?: string;
+}
+export interface ConfigFileResult {
+    /** The merged MetaGovernorPluginConfig */
+    config: Partial<MetaGovernorPluginConfig>;
+    /** Which source files were loaded */
+    sources: string[];
+    /** Which source was the effective highest-priority non-empty source */
+    effectiveSource: "cli" | "project" | "user" | "defaults";
+}
+/**
+ * Load the MetaGovernor config from all available sources with priority:
+ *   CLI inline > project `.opencode/omo-meta-governor.jsonc` >
+ *   user `~/.config/opencode/omo-meta-governor.jsonc` > defaults
+ *
+ * Higher-priority sources override lower-priority ones.
+ */
+export declare function loadMetaGovernorConfig(sources?: ConfigFileSources): Promise<ConfigFileResult>;

package/dist/config.d.ts

@@ -0,0 +1,83 @@
+import type { ModelOverrideConfig, OrchestratorConfig } from "./types";
+import type { ConfigFileSources } from "./config-file";
+/**
+ * MetaGovernor config schema exposed to users.
+ * This is a Zod-free config interface since Zod parsing is optional
+ * in the standalone plugin — the user provides JSON, we coerce with defaults.
+ */
+export interface MetaGovernorPluginConfig {
+    /** Master feature flag — must be true to run the orchestrator. */
+    enabled?: boolean;
+    /** Decision handler (PR 6) */
+    decision?: {
+        maxHistoryPerSession?: number;
+        forceContinueAfterStops?: number;
+    };
+    /** Memory aggregator (PR 2) */
+    memory?: {
+        agentmemoryTimeoutMs?: number;
+        magicContextTimeoutMs?: number;
+        boulderStateTimeoutMs?: number;
+        query?: string;
+    };
+    /** Token predictor (PR 4) */
+    tokenPredictor?: {
+        compactBurnRateThreshold?: number;
+        compactUsageThreshold?: number;
+        switchModelUsageThreshold?: number;
+        delegateConsecutiveHighBurn?: number;
+    };
+    /** Scoring engine (PR 5) */
+    scoring?: {
+        continueThreshold?: number;
+        warnThreshold?: number;
+        escalateThreshold?: number;
+        stopThreshold?: number;
+    };
+    /** Closed-loop learning (PR 3) */
+    closedLoop?: {
+        saveDecisions?: boolean;
+        saveLessons?: boolean;
+    };
+    /** Model override for MetaGovernor internal LLM usage. */
+    modelOverride?: ModelOverrideConfig;
+    /** Intervention config for visible decision injection. */
+    intervention?: {
+        mode?: "silent" | "message" | "system";
+        includeDecisionHistory?: boolean;
+        maxHistoryMessages?: number;
+        minActionForMessage?: "warn" | "escalate" | "stop";
+        /** v0.10.0: rate-limit interventions to break instruction loops. */
+        maxInterventionsPerSession?: number;
+        /** v0.10.0: stop injecting after <promise>DONE</promise> + Oracle verified. */
+        respectDoneSignal?: boolean;
+    };
+    /** Sisyphus protocol enforcement config. */
+    protocolEnforcement?: {
+        enabled?: boolean;
+        path?: string;
+        injectIntoSystem?: boolean;
+        auditToolCalls?: boolean;
+    };
+    /** Graph sync config for auto-initializing codegraph/graphify. */
+    graphSync?: {
+        enabled?: boolean;
+        watch?: boolean;
+        autoInstall?: boolean;
+        installTimeoutMs?: number;
+    };
+}
+/**
+ * Project the full MetaGovernorPluginConfig into OrchestratorConfig.
+ * Missing sub-configs fall back to module defaults.
+ */
+export declare function loadOrchestratorConfig(pluginConfig: Partial<MetaGovernorPluginConfig> | undefined): OrchestratorConfig;
+/**
+ * Check whether the MetaGovernor is enabled. Returns false if config is undefined.
+ */
+export declare function isMetaGovernorEnabled(config: MetaGovernorPluginConfig | undefined): boolean;
+/**
+ * Load orchestrator config from all available sources: config file (JSONC)
+ * with priority: CLI inline > project config > user config > defaults.
+ */
+export declare function loadOrchestratorConfigFromSources(sources?: ConfigFileSources): Promise<OrchestratorConfig>;

package/dist/decision-handler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MetaGovernor Decision Handler — PR 6 of 8.
+ *
+ * Takes a ScoringResult from the scoring engine and dispatches to the
+ * appropriate action: continue, warn, escalate, or stop. This is the
+ * "executor" that translates scoring decisions into concrete outcomes.
+ *
+ * Architecture invariants:
+ * - Pure dispatch: no I/O, no MCP calls, no side effects
+ * - DI pattern: backends injected via DecisionHandlerConfig
+ * - Audit trail: every decision + outcome recorded in DecisionHistory
+ * - Configurable: all thresholds and behaviors overridable
+ */
+import type { DecisionHandlerConfig, DecisionHandlerInput, DecisionHandlerOutput } from "./types";
+export declare const defaultDecisionHandlerConfig: () => DecisionHandlerConfig;
+/**
+ * Core decision handler. Takes a ScoringResult and dispatches to the
+ * appropriate action. Pure function — no side effects.
+ *
+ * @param input - ScoringResult + session context
+ * @param config - Handler configuration
+ * @returns DecisionHandlerOutput with action taken + message + history entry
+ */
+export declare function handleDecision(input: DecisionHandlerInput, config?: Partial<DecisionHandlerConfig>): DecisionHandlerOutput;
+/**
+ * Trim history to max size. Returns trimmed array + entries dropped count.
+ */
+export declare function trimHistory(history: readonly DecisionHandlerOutput["historyEntry"][], maxSize: number): {
+    trimmed: DecisionHandlerOutput["historyEntry"][];
+    dropped: number;
+};
+/**
+ * Count consecutive stops in history (most recent first).
+ */
+export declare function countConsecutiveStops(history: readonly DecisionHandlerOutput["historyEntry"][]): number;

package/dist/decision-store.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MetaGovernor decision store — in-memory Map for intervention feature.
+ *
+ * Stores decisions produced by tool.execute.after so they can be
+ * consumed by experimental.chat.messages.transform and
+ * experimental.chat.system.transform hooks.
+ *
+ * The store is keyed by sessionID. For hooks that receive a sessionID
+ * (system.transform), use takeDecision(sessionID). For hooks that
+ * receive no sessionID (messages.transform), use takeAnyDecision().
+ */
+import type { DecisionHandlerOutput } from "./types";
+/**
+ * Store a decision for a session.
+ * Overwrites any previous pending decision for the same session.
+ */
+export declare function storeDecision(sessionID: string, decision: DecisionHandlerOutput): void;
+/**
+ * Take (retrieve and remove) the pending decision for a session.
+ * Returns undefined if no decision is pending.
+ */
+export declare function takeDecision(sessionID: string): DecisionHandlerOutput | undefined;
+/**
+ * Check whether a session has a pending decision without consuming it.
+ */
+export declare function hasDecision(sessionID: string): boolean;
+/**
+ * Take any pending decision across all sessions.
+ * Useful for hooks that do not receive a sessionID.
+ * Returns the first pending decision found, or undefined if none.
+ */
+export declare function takeAnyDecision(): DecisionHandlerOutput | undefined;
+/**
+ * Clear all stored decisions. Useful in tests or when a session ends.
+ */
+export declare function clearAll(): void;

package/dist/file-logger.d.ts

@@ -0,0 +1 @@
+export declare function logToFile(level: "info" | "warn" | "error", message: string, data?: unknown): void;

package/dist/generate-schema.d.ts

@@ -0,0 +1,45 @@
+/**
+ * JSON Schema generator for omo-meta-governor.jsonc.
+ *
+ * Generates a JSON Schema (draft-07) from the MetaGovernorPluginConfig
+ * interface definition. The schema is used for IDE autocompletion and
+ * validation when editing the .jsonc config file.
+ *
+ * Usage:
+ *   import { generateSchema } from "./generate-schema"
+ *   const schema = generateSchema()
+ *   await Bun.write("assets/omo-meta-governor.schema.json", JSON.stringify(schema, null, 2))
+ */
+export interface JsonSchema {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    additionalProperties: boolean;
+    definitions?: Record<string, JsonSchemaProperty>;
+}
+export interface JsonSchemaProperty {
+    type?: string | string[];
+    description?: string;
+    default?: unknown;
+    properties?: Record<string, JsonSchemaProperty>;
+    items?: JsonSchemaProperty;
+    additionalProperties?: boolean;
+    required?: string[];
+    enum?: string[];
+    oneOf?: JsonSchemaProperty[];
+    anyOf?: JsonSchemaProperty[];
+    $ref?: string;
+    minimum?: number;
+    maximum?: number;
+}
+/**
+ * Generate the full JSON Schema for the omo-meta-governor.jsonc config file.
+ */
+export declare function generateSchema(): JsonSchema;
+/**
+ * Write the schema to a file.
+ */
+export declare function writeSchemaFile(outputPath: string): Promise<void>;

package/dist/graph-sync.d.ts

@@ -0,0 +1,90 @@
+/**
+ * graphSync — Auto-initialize codegraph and graphify for a project.
+ *
+ * On first session in a project, checks whether:
+ *   - `npx codegraph` is available on PATH (or node_modules)
+ *   - `graphify` / `graphifyy` is available as a Python package
+ *
+ * If a tool is available but the project has no index yet, runs the
+ * initialization automatically. With `--watch` mode, spawns a background
+ * process that re-indexes on file changes.
+ *
+ * Architecture invariants:
+ *   - Never blocks the session — init runs async, best-effort
+ *   - Never throws — all errors are silently caught and logged
+ *   - Tracks session init once per project via an in-memory Set
+ */
+export interface GraphSyncConfig {
+    /** Enable auto-initialization. Default: true */
+    enabled: boolean;
+    /** Enable watch mode (re-index on file changes). Default: false */
+    watch: boolean;
+    /** Project directory to initialize in. Default: cwd */
+    projectDir?: string;
+    /**
+     * Auto-install missing backends. Default: true.
+     * - codegraph: installed via `npm i -D @colbymchenry/codegraph` in the project
+     * - graphify: installed via `pip install graphifyy --break-system-packages` (or `uv tool install graphifyy`)
+     */
+    autoInstall: boolean;
+    /** Max ms to wait for each install. Default: 60_000 */
+    installTimeoutMs: number;
+}
+export type InstallCode = "codegraph-installed" | "codegraph-install-failed" | "codegraph-install-skipped" | "graphify-installed" | "graphify-install-failed" | "graphify-install-skipped";
+/**
+ * Install codegraph via `npm i -D @colbymchenry/codegraph`.
+ * Best-effort, never throws.
+ */
+export declare function installCodegraph(projectDir: string, timeoutMs?: number): Promise<InstallCode>;
+/**
+ * Install graphify via `pip install graphifyy --break-system-packages`.
+ * Falls back to `uv tool install graphifyy`.
+ * Best-effort, never throws.
+ */
+export declare function installGraphify(timeoutMs?: number): Promise<InstallCode>;
+export declare function resetInitializedProjects(): void;
+/**
+ * Track a new session for a project. Increments reference count.
+ * Returns the new count.
+ */
+export declare function trackSession(projectDir: string): number;
+/**
+ * Untrack a session for a project. Decrements reference count.
+ * When count drops to 0, all watch processes for that project
+ * are automatically stopped.
+ * Returns the remaining count.
+ */
+export declare function untrackSession(projectDir: string): number;
+/** Get active session count for a project. */
+export declare function getSessionCount(projectDir: string): number;
+export interface ToolAvailability {
+    /** Whether codegraph is available (via npx or node_modules) */
+    codegraph: boolean;
+    /** Whether graphify/graphifyy is available (via pip) */
+    graphify: boolean;
+    /** Whether .codegraph/ directory already exists in the project */
+    codegraphIndexExists: boolean;
+    /** Whether graphify-out/ directory already exists in the project */
+    graphifyIndexExists: boolean;
+}
+/**
+ * Stop all active watch processes for a project.
+ */
+export declare function stopWatches(projectDir?: string): void;
+/** Check if watches are active for a project. */
+export declare function hasActiveWatcher(projectDir: string, tool?: "codegraph" | "graphify"): boolean;
+export interface GraphSyncResult {
+    /** Whether synchronization was attempted */
+    attempted: boolean;
+    /** Codes that describe the outcome */
+    codes: GraphSyncCode[];
+    /** Tool availability before init */
+    availability: ToolAvailability;
+    /** Whether this project was already initialized this session */
+    alreadyInitialized: boolean;
+}
+export type GraphSyncCode = "codegraph-initialized" | "codegraph-already-exists" | "codegraph-unavailable" | "codegraph-install-failed" | "codegraph-install-skipped" | "graphify-initialized" | "graphify-already-exists" | "graphify-unavailable" | "graphify-install-failed" | "graphify-install-skipped" | "watch-started-codegraph" | "watch-started-graphify" | "disabled" | "error";
+/**
+ * Run the graphSync pipeline. Best-effort, never throws.
+ */
+export declare function runGraphSync(config?: GraphSyncConfig): Promise<GraphSyncResult>;

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { PluginModule } from "@opencode-ai/plugin";
+/**
+ * @sisyphuslabs/omo-meta-governor — Self-judging agent orchestration layer.
+ *
+ * Default export is an OpenCode PluginModule that registers a
+ * `tool.execute.after` hook. The MetaGovernor reads session signals,
+ * scores them against weighted evidence, and dispatches decisions.
+ *
+ * Install:
+ *   npm install @sisyphuslabs/omo-meta-governor
+ *
+ * Configure:
+ * ```jsonc
+ * {
+ *   "meta_governor": {
+ *     "enabled": true
+ *   }
+ * }
+ * ```
+ */
+declare const pluginModule: PluginModule;
+export default pluginModule;
+export { createMetaGovernorPlugin, type MetaGovernorPluginDeps } from "./plugin";
+export { logToFile } from "./file-logger";
+export { runMetaGovernor, buildDecisionContext, defaultOrchestratorConfig, } from "./orchestrator";
+export { loadOrchestratorConfig, isMetaGovernorEnabled, type MetaGovernorPluginConfig, } from "./config";
+export { score, defaultScoringConfig } from "./scoring-engine";
+export { predict, defaultTokenPredictorConfig, calculateBurnRate } from "./token-predictor";
+export { handleDecision, defaultDecisionHandlerConfig, trimHistory, countConsecutiveStops } from "./decision-handler";
+export { observeAndLearn, defaultClosedLoopConfig } from "./closed-loop-learning";
+export { aggregateRead } from "./memory-aggregator";
+export { recordRecovery, type RecoveryOutcome } from "./post-repair-recorder";
+export { storeDecision, takeDecision, hasDecision, takeAnyDecision, clearAll, } from "./decision-store";
+export type { Decision, DecisionContext, DecisionHandlerConfig, DecisionHandlerInput, DecisionHandlerOutput, Deviation, Evidence, EvidenceContribution, InterventionConfig, InterventionMode, LearnFromOutcomeInput, LearnFromOutcomeOutput, MemoryRead, MemoryBackends, AgentmemoryWriteBackend, MetaGovernorInput, MetaGovernorOutput, OrchestratorConfig, ScoringConfig, ScoringResult, SlotMemory, TokenPredictorConfig, TokenPredictorInput, TokenPredictorOutput, ClosedLoopConfig, } from "./types";
+export { loadProtocol, buildSystemInjection, auditToolCall, DEFAULT_PROTOCOL_PATH, } from "./protocol-enforcer";
+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 { loadOrchestratorConfigFromSources } from "./config";
+export type { ProtocolViolation, ProtocolEnforcementSessionState } from "./types";