@herjarsa/omo-meta-governor 0.14.2 → 0.14.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +84 -82
  2. package/dist/index.js +47 -47
  3. package/dist/index.js.map +6 -6
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # @herjarsa/omo-meta-governor
2
2
 
3
3
  Self-judging agent orchestration layer for OpenCode. Observes tool executions,
4
- reads session state, scores progress, and dispatches decisions.
4
+ reads session state, scores progress, and dispatches decisions. Includes **15 custom tools**
5
+ that the agent can invoke across CodeGraph, Graphify, AFT, AgentMemory, Magic Context, and SQLite.
5
6
 
6
7
  ## Install
7
8
 
@@ -19,30 +20,87 @@ Add as a plugin in your OpenCode config:
19
20
  }
20
21
  ```
21
22
 
22
- Configure:
23
+ The 15 custom tools register automatically (even without setting enabled:true).
24
+ To also enable the governance pipeline (intervention, protocol enforcement):
23
25
 
24
26
  ```jsonc
25
27
  {
26
28
  "meta_governor": {
27
- "enabled": true
29
+ "enabled": true,
30
+ "intervention": {
31
+ "mode": "message",
32
+ "minActionForMessage": "warn"
33
+ }
28
34
  }
29
35
  }
30
36
  ```
31
37
 
32
- ## How it works
38
+ ## 15 Custom Tools
39
+
40
+ The plugin registers 15 tools the LLM can invoke. All available immediately on install.
41
+
42
+ ### Code Search & Navigation
43
+
44
+ | Tool | What it does | Use case |
45
+ |------|-------------|----------|
46
+ | `omo_search` | Semantic code search via codegraph/graphify with AFT fallback | Architecture questions, finding features — USE THIS FIRST |
47
+ | `omo_find` | Exact symbol lookup (definition + direct callers) via codegraph node | "Find the function `validateToken`" |
48
+ | `omo_impact` | Impact analysis: callers, transitive callers, test files, doc files | Run BEFORE modifying a function |
49
+ | `omo_path` | Shortest conceptual path between two concepts via graphify | "How does auth connect to database?" |
50
+ | `omo_explain` | Plain-language explanation of a concept via graphify | "What is the SwinTransformer?" |
51
+ | `omo_outline` | Structural outline of files/directories via AFT | Understanding a new file's structure |
52
+
53
+ ### Lesson & Memory
54
+
55
+ | Tool | What it does | Use case |
56
+ |------|-------------|----------|
57
+ | `omo_recall` | Search past lessons via local SQLite FTS5 (fast, always available) | "How did we set up auth before?" |
58
+ | `omo_recall_mcp` | Search cross-session memory via AgentMemory | "What did we learn about X in previous sessions?" |
59
+ | `omo_remember` | Save a fact/observation to cross-session AgentMemory | "Remember this bug pattern for next time" |
60
+
61
+ ### Rules & Notes
62
+
63
+ | Tool | What it does | Use case |
64
+ |------|-------------|----------|
65
+ | `omo_rule` | Save a durable rule to Magic Context (ctx_memory) | "Always use bun:sqlite, not better-sqlite3" |
66
+ | `omo_history` | Search git history + past messages via ctx_search | "When did we add this feature?" |
67
+ | `omo_note` | Write ephemeral session note via ctx_note | "Currently debugging auth in module X" |
68
+
69
+ ### Safety & Status
70
+
71
+ | Tool | What it does | Use case |
72
+ |------|-------------|----------|
73
+ | `omo_checkpoint` | Create a named AFT snapshot before risky changes | Undo protection before refactoring |
74
+ | `omo_undo` | Revert to most recent AFT checkpoint | "That broke things, revert it" |
75
+ | `omo_health` | Show plugin runtime status: metrics, decisions, errors | "Is the plugin working?" |
76
+
77
+ ## Health & Observability
78
+
79
+ The plugin exposes a health JSON file at `~/.config/opencode/meta-governor-health.json`:
80
+
81
+ ```bash
82
+ cat ~/.config/opencode/meta-governor-health.json
83
+ ```
84
+
85
+ Or the agent can call `omo_health` directly to get a formatted report.
33
86
 
34
- After every tool call, MetaGovernor:
35
- - Reads session signals (deviations, iteration budget, progress)
36
- - Scores the session against weighted evidence
37
- - Dispatches: `continue | warn | escalate | stop`
87
+ Structured JSONL logs at `~/.config/opencode/meta-governor.log` with size-based rotation
88
+ (10MB max, 5 rotated files).
38
89
 
39
- See [docs/guide/meta-governor.md](docs/guide/meta-governor.md) for full docs.
90
+ ## Persistence
91
+
92
+ Lessons learned by the plugin persist in **SQLite** at `~/.omo-meta-governor/meta-governor.db`
93
+ with full-text search (FTS5) for fast recall. Zero dependencies needed — uses Bun's built-in
94
+ `bun:sqlite`.
95
+
96
+ Optionally, the Opción A tools (`omo_remember`, `omo_recall_mcp`, `omo_rule`, `omo_history`,
97
+ `omo_note`) can bridge to AgentMemory and Magic Context via `session.prompt()` — the LLM
98
+ receives a structured instruction to call the appropriate MCP tool.
40
99
 
41
100
  ## Graph Sync (v0.11.0)
42
101
 
43
102
  MetaGovernor wires the plugin into the native git hooks of **codegraph** and
44
- **graphify** so each commit automatically reindexes both graphs. No more
45
- polling loops, no more stale indexes.
103
+ **graphify** so each commit automatically reindexes both graphs.
46
104
 
47
105
  ### What it does on first load in a project
48
106
 
@@ -52,71 +110,24 @@ polling loops, no more stale indexes.
52
110
  2. **Run `codegraph init`** + **`graphify . --no-viz`** to build the initial
53
111
  indexes for the project.
54
112
  3. **Run `graphify hook install`** to wire up the native `post-commit` and
55
- `post-checkout` git hooks. From that point on, every `git commit`
56
- triggers `graphify update` automatically (deterministic clustering with
57
- `PYTHONHASHSEED=0`, rebase/merge/cherry-pick detection, detached
58
- subprocess for non-blocking rebuild).
113
+ `post-checkout` git hooks.
59
114
 
60
115
  ### What it does on each `git commit`
61
116
 
62
117
  - **Primary path** (native git hook): `graphify update` runs in background.
63
118
  - **Backup path** (plugin's `tool.execute.after`): detects `git commit` in
64
- bash commands and runs `codegraph sync -q [path]`. Catches the case
65
- where the user manually deleted the native hook.
66
-
67
- ### Plan enforcement
68
-
69
- On the first message of each session, if the project has no `PLAN.md` and
70
- no `## Plan` section in `AGENTS.md`, the plugin injects a one-time reminder:
71
- "create a plan, commit per phase, push to fork + upstream". The reminder
72
- honors the same gates as intervention (max 3, DONE+Oracle disables).
73
-
74
- ### PR reviewer bot feedback
75
-
76
- When a bash command matches `gh pr ...` (e.g. `gh pr checks 42`, `gh pr view
77
- 42 --comments`), the plugin extracts failing check runs and review
78
- comments. The next LLM turn receives them as actionable feedback so the
79
- agent can apply fixes to keep the PR mergeable. Recognizes: codecov,
80
- claude-code-review, CodeRabbit, etc.
81
-
82
- ## Auto-upgrade (v0.12.0)
83
-
84
- On plugin load, queries npm/pip registries to check whether newer versions
85
- of **codegraph** or **graphify** exist. If a newer version is found AND the
86
- installed version is older, the plugin upgrades automatically.
87
-
88
- - **Upgrade check TTL**: 24h by default. Cached to
89
- `~/.config/opencode/omo-meta-governor-upgrade-check.json`.
90
- - **Config**: `graphSync.autoUpgrade` (default `true`),
91
- `graphSync.upgradeCheckTtlMs` (default `86400000`).
119
+ bash commands and runs `codegraph sync -q [path]`.
92
120
 
93
121
  ## Intervention
94
122
 
95
- MetaGovernor can inject its decisions into the active agent's context
96
- so the agent is aware of governance warnings, escalations, or stop signals.
97
-
98
- ### v0.10.0 — Loop prevention
99
-
100
- The plugin now self-disables intervention when the agent's task is verifiably
101
- complete. This fixes the v0.3.0–v0.9.x bug where the plugin kept injecting
102
- synthetic user messages indefinitely after the agent had finished.
103
-
104
- Three mechanisms enforce the cap:
105
-
106
- 1. **`<promise>DONE</promise>` + Oracle verified** — the agent emits this signal
107
- to mark the task complete. If Oracle has verified the work (the agent
108
- invoked `task(subagent_type="oracle")` and got a PASS verdict), the plugin
109
- disables intervention for that session.
110
- 2. **`maxInterventionsPerSession`** — hard cap (default `3`) on the number of
111
- times a session can receive an injection. Once reached, no more injections.
112
- 3. **Cross-session scoping** — decisions are now scoped to the current
113
- sessionID. The plugin no longer pulls decisions from unrelated sessions.
123
+ MetaGovernor can inject governance decisions into the agent's context.
124
+ Enabled when `meta_governor.enabled: true` in config.
114
125
 
115
126
  ### Modes
116
127
 
117
128
  | Mode | Mechanism | Effect |
118
129
  |------|-----------|--------|
119
- | `silent` | (none) | Decision is logged only — no injection |
130
+ | `silent` | (none) | Decision is logged only |
120
131
  | `message` | `experimental.chat.messages.transform` | Injects a synthetic user message visible to the LLM |
121
132
  | `system` | `experimental.chat.system.transform` | Appends guidance to the system prompt |
122
133
 
@@ -128,9 +139,7 @@ Three mechanisms enforce the cap:
128
139
  "enabled": true,
129
140
  "intervention": {
130
141
  "mode": "message",
131
- "includeDecisionHistory": true,
132
- "maxHistoryMessages": 5,
133
- "minActionForMessage": "stop",
142
+ "minActionForMessage": "warn",
134
143
  "maxInterventionsPerSession": 3,
135
144
  "respectDoneSignal": true
136
145
  }
@@ -142,23 +151,16 @@ Three mechanisms enforce the cap:
142
151
 
143
152
  | Field | Default | Description |
144
153
  |-------|---------|-------------|
145
- | `mode` | `"silent"` | How to inject: `"silent"`, `"message"`, or `"system"` |
146
- | `includeDecisionHistory` | `true` | Whether to include recent decision history |
147
- | `maxHistoryMessages` | `5` | Max history entries when includeDecisionHistory is true |
148
- | `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. |
149
- | `maxInterventionsPerSession` | `3` (v0.10.0) | Hard cap on injections per session. Once reached, no more injections until session restart. |
150
- | `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. |
151
- ### How it works
152
-
153
- 1. After every tool call, MetaGovernor runs the orchestrator pipeline.
154
- 2. If the decision is non-continue and meets `minActionForMessage`, it is
155
- stored in an in-memory decision store keyed by session ID.
156
- 3. When the next LLM call starts, the appropriate transform hook fires:
157
- - `message` mode: a synthetic `UserMessage` with `synthetic: true` flag
158
- is prepended to the message list.
159
- - `system` mode: the decision message is appended to the system prompt.
160
- 4. The decision is removed from the store after injection (one-shot).
154
+ | `mode` | `"message"` | How to inject: `"silent"`, `"message"`, or `"system"` |
155
+ | `minActionForMessage` | `"warn"` | Minimum action: `"warn"`, `"escalate"`, or `"stop"` |
156
+ | `maxInterventionsPerSession` | `3` | Hard cap on injections per session |
157
+ | `respectDoneSignal` | `true` | Stop injecting after DONE + Oracle verified |
158
+
159
+ ## Auto-upgrade (v0.12.0)
161
160
 
161
+ On plugin load, queries npm/pip registries to check whether newer versions
162
+ of **codegraph** or **graphify** exist. Config: `graphSync.autoUpgrade` (default `true`),
163
+ `graphSync.upgradeCheckTtlMs` (default `86400000`).
162
164
 
163
165
  ## License
164
166