@herjarsa/omo-meta-governor 0.14.2 → 0.14.3
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.
- package/README.md +84 -82
- 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
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
35
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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]`.
|
|
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
|
|
96
|
-
|
|
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
|
|
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
|
-
"
|
|
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` | `"
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
|
|
150
|
-
|
|
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
|
|
package/package.json
CHANGED