@herjarsa/omo-meta-governor 0.1.0

package/dist/memory-aggregator.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Cross-system memory aggregator for MetaGovernor.
+ *
+ * PR 2 of 8. Reads from all three memory systems (agentmemory, magic-context,
+ * boulder-state) in parallel and returns a `MemoryRead` that conforms to the
+ * PR 1 contract (types.ts).
+ *
+ * Design choices:
+ * - Parallel reads with per-source timeouts. No sequential I/O.
+ * - Graceful degrade: a failing source does NOT fail the whole read.
+ *   It populates `degradedSources[]` (string tags per the contract) and
+ *   the caller (`score()`) can decide the policy.
+ * - Lessons are sorted by confidence DESC. Slots by label. Tasks by priority
+ *   ASC then recency DESC.
+ * - Result is bounded: respects `limits`.
+ * - Per-source error messages are stored separately (`errorMessages`) for
+ *   debugging but NOT in the contract type (the contract only has the string tags).
+ *
+ * Future PRs that wire this:
+ * - PR 3 (closed-loop): calls `aggregateRead()` from `observeErrorAndLearn`
+ *   and `preflightCheck`.
+ * - PR 5 (score): calls `aggregateRead()` to build `lessonsRelevant` slice
+ *   of `DecisionContext`.
+ * - PR 6 (post-repair): calls `aggregateRead()` after a fix to verify.
+ *
+ * Internal raw types (Lesson, Crystal, Slot, BoulderTask) are defined here
+ * as private interfaces representing what each backend actually returns.
+ * The aggregator maps them to the contract types from types.ts.
+ */
+import type { MemoryRead, MemorySource } from "./types";
+interface RawLesson {
+    readonly id: string;
+    readonly title: string;
+    readonly content: string;
+    readonly type: string;
+    readonly concepts: readonly string[];
+    readonly confidence: number;
+    readonly files: readonly string[];
+}
+interface RawCrystal {
+    readonly id: string;
+    readonly title: string;
+    readonly content: string;
+    readonly type: string;
+    readonly concepts: readonly string[];
+    readonly confidence: number;
+    readonly files: readonly string[];
+}
+interface RawSlot {
+    readonly label: string;
+    readonly content: string;
+    readonly pinned?: boolean;
+    readonly scope?: string;
+    readonly sizeLimit?: number;
+    readonly updatedAt?: number;
+}
+interface RawBoulderTask {
+    readonly id: string;
+    readonly title: string;
+    readonly priority: number;
+    readonly status: string;
+    readonly description: string;
+    readonly createdAtMs: number;
+    readonly updatedAtMs: number;
+}
+export interface AgentmemoryBackend {
+    smartSearch(input: {
+        query: string;
+        limit?: number;
+    }): Promise<{
+        lessons: RawLesson[];
+        crystals: RawCrystal[];
+    }>;
+}
+export interface MagicContextBackend {
+    slotList(input: {
+        directory?: string;
+        labelPrefix?: string;
+    }): Promise<RawSlot[]>;
+}
+export interface BoulderStateBackend {
+    boulderRead(input: {
+        directory: string;
+        sessionID: string;
+        query?: string;
+    }): Promise<RawBoulderTask[]>;
+}
+export interface AggregateReadInput {
+    /** Working directory. Scopes the read. */
+    readonly directory: string;
+    /** Session ID. Used for boulder-state keying. */
+    readonly sessionID: string;
+    /** Natural-language query. Passed to agentmemory (semantic) and boulder. */
+    readonly query: string;
+    /** Result-size bounds. */
+    readonly limits?: {
+        readonly maxLessons?: number;
+        readonly maxSlots?: number;
+        readonly maxTasks?: number;
+    };
+    /** Per-source timeout in ms. Default 2000 for agentmemory (network), 1000 for local. */
+    readonly timeouts?: {
+        readonly agentmemoryMs?: number;
+        readonly magicContextMs?: number;
+        readonly boulderStateMs?: number;
+    };
+}
+export interface AggregateReadResult extends MemoryRead {
+    /** Wall-clock duration of the whole read, in ms. */
+    readonly durationMs: number;
+    /** Per-source error messages (for debugging; not in the contract type). */
+    readonly errorMessages: Partial<Record<MemorySource, string>>;
+}
+export interface Backends {
+    agentmemory: AgentmemoryBackend;
+    magicContext: MagicContextBackend;
+    boulderState: BoulderStateBackend;
+}
+/**
+ * Read from all three memory systems in parallel. Never throws — a failing
+ * source populates `degradedSources` and the read still returns a valid result.
+ */
+export declare function aggregateRead(input: AggregateReadInput, backends: Backends): Promise<AggregateReadResult>;
+export {};

package/dist/orchestrator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * MetaGovernor Orchestrator — PR 7 of 8.
+ *
+ * Unified pipeline integrating all 6 prior modules:
+ * - Memory Aggregator (PR 2): parallel reads from 3 memory systems
+ * - Token Predictor (PR 4): burn rate + context pressure estimation
+ * - Scoring Engine (PR 5): weighted evidence scoring → action decision
+ * - Decision Handler (PR 6): dispatch + history tracking + force-continue
+ * - Closed-Loop Learning (PR 3): lesson persistence for future sessions
+ *
+ * Architecture:
+ * - Pure pipeline: input → memory → predict → score → decide → learn → output
+ * - Each stage is independently testable and DI-friendly
+ * - Graceful degradation: if any module throws, returns partial output with skipped=true
+ */
+import type { DecisionContext, MemoryRead, MetaGovernorInput, MetaGovernorOutput, OrchestratorConfig } from "./types";
+export declare const defaultOrchestratorConfig: () => OrchestratorConfig;
+/**
+ * Build a DecisionContext from orchestrator input + memory read.
+ * Exported for direct testing.
+ */
+export declare function buildDecisionContext(input: MetaGovernorInput, memoryRead?: MemoryRead): DecisionContext;
+/**
+ * Run the full MetaGovernor pipeline.
+ *
+ * 1. Read memory via aggregator
+ * 2. Predict token pressure (skipped if no usage data)
+ * 3. Build DecisionContext + score
+ * 4. Dispatch decision
+ * 5. Learn from outcome
+ * 6. Return unified output
+ */
+export declare function runMetaGovernor(input: MetaGovernorInput, config?: Partial<OrchestratorConfig>): Promise<MetaGovernorOutput>;

package/dist/plugin.d.ts

@@ -0,0 +1,23 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import type { AgentmemoryWriteBackend, MemoryBackends } from "./types";
+/**
+ * Dependencies required by the MetaGovernor plugin.
+ * All are optional — features degrade gracefully when backends are unavailable.
+ */
+export interface MetaGovernorPluginDeps {
+    /** Backends for reading memory (agentmemory, magic-context, boulder-state). Optional — degrades gracefully. */
+    backends?: MemoryBackends;
+    /** Backend for writing lessons/decisions back to agentmemory. Optional — degrades gracefully. */
+    writeBackend?: AgentmemoryWriteBackend;
+    /** Provider ID for the current session (for token predictor). */
+    providerID?: () => string | undefined;
+    /** Model ID for the current session (for token predictor). */
+    modelID?: () => string | undefined;
+}
+/**
+ * Create a MetaGovernor plugin that registers a `tool.execute.after` hook.
+ *
+ * The plugin observes every tool call, runs the MetaGovernor pipeline,
+ * and dispatches decisions (continue/warn/escalate/stop).
+ */
+export declare function createMetaGovernorPlugin(deps?: MetaGovernorPluginDeps): Plugin;

package/dist/post-repair-recorder.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Post-Repair Recorder for MetaGovernor — PR 9 of 9.
+ *
+ * After each recovery hook repairs an error, this module records the
+ * outcome into agentmemory. This ensures the MetaGovernor learns from
+ * recovery attempts across sessions.
+ *
+ * Architecture invariants:
+ * - DI: AgentmemoryWriteBackend injected via function parameter.
+ * - No-op when backend is null (graceful degradation).
+ * - Bypasses observeAndLearn() to preserve custom severity/category.
+ * - Success → leve deviation (low severity, lesson saved for pattern).
+ * - Failure → grave deviation (high severity, lesson saved as bug).
+ */
+import type { AgentmemoryWriteBackend, ClosedLoopConfig, LearnFromOutcomeOutput } from "./types";
+import { defaultClosedLoopConfig } from "./closed-loop-learning";
+/**
+ * Outcome of a recovery hook repair attempt.
+ */
+export interface RecoveryOutcome {
+    /** Error code or category (e.g. "TOOL_TIMEOUT", "JSON_PARSE_ERROR"). */
+    readonly errorCode: string;
+    /** Recovery strategy used (e.g. "retry", "fallback", "compact"). */
+    readonly fixStrategy: string;
+    /** Whether the repair succeeded. */
+    readonly success: boolean;
+    /** Session ID where the repair happened. */
+    readonly sessionID: string;
+    /** Directory context. */
+    readonly directory: string;
+    /** Files changed during the repair, if any. */
+    readonly filesChanged?: readonly string[];
+    /** Additional context about the error. */
+    readonly context?: string;
+}
+/**
+ * Record a recovery outcome to agentmemory.
+ *
+ * This bypasses observeAndLearn() to preserve custom severity and category
+ * from the recovery outcome (observeAndLearn hardcodes severity: "media").
+ *
+ * When `writeBackend` is null, this is a silent no-op.
+ */
+export declare function recordRecovery(outcome: RecoveryOutcome, writeBackend: AgentmemoryWriteBackend | null, options?: {
+    config?: ClosedLoopConfig;
+}): Promise<LearnFromOutcomeOutput | null>;
+export { defaultClosedLoopConfig };

package/dist/scoring-engine.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MetaGovernor Scoring Engine — PR 5 of 8.
+ *
+ * The core decision engine. Takes a DecisionContext (built from signals
+ * gathered by the memory-aggregator, token-predictor, and hooks) and
+ * produces a Decision via weighted evidence scoring.
+ *
+ * Architecture invariants:
+ * - Pure function: no side effects, no I/O, no MCP calls
+ * - Deterministic: same input → same output (no randomness)
+ * - All thresholds configurable via ScoringConfig
+ * - Paralysis prevention: N consecutive stops → force continue with warning
+ * - Cite-or-abstain: evidence required when action !== "continue" silently
+ *
+ * Score ranges (default thresholds):
+ *   >= +0.3  → continue silently
+ *   [-0.3, +0.3] → continue with log
+ *   [-0.6, -0.3] → warn
+ *   [-0.8, -0.6] → escalate
+ *   < -0.8   → stop
+ */
+import type { DecisionContext, ScoringConfig, ScoringResult } from "./types";
+export declare const defaultScoringConfig: () => ScoringConfig;
+/**
+ * Core scoring function. Pure, deterministic, no side effects.
+ *
+ * @param ctx - DecisionContext assembled from all signal sources
+ * @param config - Scoring thresholds (defaults if omitted)
+ * @returns ScoringResult with Decision, evidence breakdown, and metadata
+ */
+export declare function score(ctx: DecisionContext, config?: Partial<ScoringConfig>): ScoringResult;

package/dist/token-predictor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Token Predictor for MetaGovernor.
+ *
+ * PR 4 of 8. Computes token burn rate from recent turn metrics and recommends
+ * preemptive actions (compact, switch model, delegate) before context window
+ * exhaustion.
+ *
+ * Design:
+ * - Pure function with no I/O — takes input, returns prediction.
+ * - Configurable thresholds via TokenPredictorConfig.
+ * - Burn rate = avg tokens/turn over sliding window.
+ * - Overflow prediction: budgetLeft / burnRate = turns left.
+ * - Recommendations layered: compact-now > switch-model > delegate > no-action.
+ */
+import type { TokenPredictorConfig, TokenPredictorInput, TokenPredictorOutput } from "./types";
+/**
+ * Default configuration for the token predictor.
+ */
+export declare function defaultTokenPredictorConfig(): TokenPredictorConfig;
+/**
+ * Calculate burn rate (avg tokens/turn) from recent turn tokens.
+ * Returns 0 if no turns provided.
+ */
+export declare function calculateBurnRate(recentTurnTokens: readonly number[]): number;
+/**
+ * Core prediction function. Analyzes recent turn tokens and recommends
+ * an action to prevent context window exhaustion.
+ */
+export declare function predict(input: TokenPredictorInput): TokenPredictorOutput;