@herjarsa/omo-meta-governor 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @herjarsa/omo-meta-governor
+
+Self-judging agent orchestration layer for OpenCode. Observes tool executions,
+reads session state, scores progress, and dispatches decisions.
+
+## Install
+
+```bash
+npm install @herjarsa/omo-meta-governor
+```
+
+## Usage
+
+Add as a plugin in your OpenCode config:
+
+```jsonc
+{
+  "plugins": ["@herjarsa/omo-meta-governor"]
+}
+```
+
+Configure:
+
+```jsonc
+{
+  "meta_governor": {
+    "enabled": true
+  }
+}
+```
+
+## How it works
+
+After every tool call, MetaGovernor:
+- Reads session signals (deviations, iteration budget, progress)
+- Scores the session against weighted evidence
+- Dispatches: `continue | warn | escalate | stop`
+
+See [docs/guide/meta-governor.md](docs/guide/meta-governor.md) for full docs.
+
+## License
+
+MIT

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.d.ts

@@ -0,0 +1,50 @@
+import type { OrchestratorConfig } from "./types";
+/**
+ * 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;
+    };
+}
+/**
+ * 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;

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/index.d.ts

@@ -0,0 +1,32 @@
+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 { 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 type { Decision, DecisionContext, DecisionHandlerConfig, DecisionHandlerInput, DecisionHandlerOutput, Deviation, Evidence, EvidenceContribution, LearnFromOutcomeInput, LearnFromOutcomeOutput, MemoryRead, MemoryBackends, AgentmemoryWriteBackend, MetaGovernorInput, MetaGovernorOutput, OrchestratorConfig, ScoringConfig, ScoringResult, SlotMemory, TokenPredictorConfig, TokenPredictorInput, TokenPredictorOutput, ClosedLoopConfig, } from "./types";