AGENTS.md

1# src/ - Plugin Source
2 
3**Generated:** 2026-08-07 / 51ab1e5b6
4 
5## STOP. THIS IS THE OPENCODE PLUGIN. QA IS MANDATORY. EVERY SINGLE TIME YOU CHANGE ANYTHING HERE.
6 
7> **EVERYTHING UNDER THIS `src/` IS WIRED DIRECTLY INTO OPENCODE. IF YOU EDIT A HOOK, A TOOL, AN AGENT, A FEATURE, A CONFIG SCHEMA, AN MCP, A CLI COMMAND, A PLUGIN HANDLER, OR ANYTHING ELSE IN HERE, YOU MUST QA IT AGAINST REAL OPENCODE. ALWAYS. EVERY SINGLE TIME. NO EXCEPTIONS.**
8 
9**"It typechecks" is NOT QA. "`bun test` is green" is NOT QA.** YOU MUST DRIVE REAL OPENCODE AND RECORD THE EVIDENCE TO DISK. NO EVIDENCE == NO QA == NO COMMIT == NO PUSH.
10 
11**ALWAYS RUN THE `opencode-qa` SKILL** (`.agents/skills/opencode-qa/`) to map the EXPECTED IMPACT and the FULL CHANGE SCOPE of your edit:
12 
131. **MAP THE BLAST RADIUS** with the skill router (CLI / server + SSE hook proof / TUI smoke / DB inspection), BEFORE and AFTER your change.
142. **ISOLATE EVERYTHING.** Any QA that SPAWNS opencode MUST run in an isolated XDG sandbox (`XDG_DATA_HOME` / `XDG_CONFIG_HOME` / `XDG_STATE_HOME` / `XDG_CACHE_HOME` pointed at temp dirs). **NEVER pollute the real `~/.local/share/opencode/opencode.db`.** PROVE it: `SELECT count(*) FROM session` unchanged before vs after.
153. **PROVE THE HOOK / EVENT FIRED.** Changed a lifecycle hook? Prove the matching event hit the wire (`scripts/sse-hook-probe.sh --event <name>`). Changed a tool? Drive it via `opencode run --format json` and assert on the structured events.
164. **USE tmux** for TUI smoke (`scripts/tui-smoke.sh`) and interactive driving; assert REAL behavior via `opencode run` or the server API + SSE, not the TUI pane.
17 
18**RECORD THE EVIDENCE UNDER `.omo/evidence/<YYYYMMDD>-<short-slug>/`** (one organized subfolder per change): WHY THERE IS NO REGRESSION (before/after + isolation proof + exact commands and output) and PROOF THAT EVERY INTENDED CHANGE LANDED (new behavior observed on real opencode). See the root [`AGENTS.md`](../../../AGENTS.md) "STOP. QA IS MANDATORY" section for the full mandate, which also covers the Codex side.
19 
20**ALWAYS. EVERY TIME. NO EXCEPTIONS.**
21 
22## OVERVIEW
23 
24Entry `index.ts` orchestrates a staged initialization across the directories below. Cross-cutting adapter helpers live in `shared/`; barrel `index.ts` files establish module boundaries. Several former implementation directories now act partly as OpenCode-facing shims over extracted Core packages.
25 
26## KEY FILES
27 
28| File | Purpose |
29|------|---------|
30| `index.ts` | Plugin entry; default-exports `pluginModule: PluginModule` with `{ id, server }` |
31| `plugin-config.ts` | JSONC parse, multi-level merge (user + walked project), Zod v4 validation, migration |
32| `plugin-state.ts` | `createModelCacheState()`: model resolution cache shared across handlers |
33| `plugin-interface.ts` | 12 OpenCode hook handlers wired into `Hooks` (a further 2, `experimental.session.compacting` + `experimental.compaction.autocontinue`, are wired in `src/testing/create-plugin-module.ts`, for 14 total) |
34| `create-managers.ts` | TmuxSessionManager, BackgroundManager, SkillMcpManager, ConfigHandler |
35| `create-tools.ts` | SkillContext + AvailableCategories + ToolRegistry composition |
36| `create-hooks.ts` | 5-tier composition: `createCoreHooks() + createContinuationHooks() + createSkillHooks()` |
37| `create-runtime-tmux-config.ts` | `isTmuxIntegrationEnabled()` + `createRuntimeTmuxConfig()` |
38 
39## INITIALIZATION (7 STEPS)
40 
41```
42serverPlugin(input, options)
43  1. installAgentSortShim()        # patches Array.prototype.{toSorted,sort} for canonical agent ordering
44  2. initConfigContext()           # detects opencode-vs-openagent config layout
45  3. detectExternalSkillPlugin()   # warn if conflicting plugin loaded
46  4. injectServerAuthIntoClient()  # wire auth headers into shared SDK client
47  5. loadPluginConfig()            # walk project + user JSONC → Zod safeParse → migrate
48  6a. initializeOpenClaw()         # if openclaw config present (start reply-listener daemon)
49  6b. checkTeamModeDependencies()  # if team_mode.enabled (verify git, tmux, ensure ~/.omo/teams/)
50  7. createManagers/Tools/Hooks/PluginInterface
51```
52 
53## CONFIG LOADING (Phase pipeline)
54 
55```
56loadPluginConfig(directory, ctx)
57  1. User: ~/.omo/omo.jsonc
58  2. Walked configs: <pwd up to $HOME>/.omo/omo.jsonc
59  3. mergeConfigs(user, walked)
60     - agents/categories/claude_code: deepMerge (recursive, prototype-pollution safe)
61     - disabled_*: Set union
62     - mcp_env_allowlist: user-only (security)
63     - playwright_mcp_args: user-only (security)
64     - others: override replaces
65  4. Zod safeParse → defaults for omitted fields
66  5. Legacy configuration is migrated once at startup into the unified OMO chain
67```
68 
69## HOOK COMPOSITION (5-tier)
70 
71Counts verified from each composer's return object. Numbers in brackets show counts when `team_mode.enabled`.
72 
73```
74createHooks()
75  ├─→ createCoreHooks()
76  │   ├─ createSessionHooks()     # 22: preemptiveCompaction,
77  │   │                             sessionNotification, thinkMode, modelFallback,
78  │   │                             anthropicContextWindowLimitRecovery, autoUpdateChecker,
79  │   │                             agentUsageReminder, nonInteractiveEnv, interactiveBashSession,
80  │   │                             goal, editErrorRecovery, delegateTaskRetry, startWork,
81  │   │                             prometheusMdOnly, sisyphusJuniorNotepad, noSisyphusGpt,
82  │   │                             noHephaestusNonGpt, hephaestusAgentsMdInjector,
83  │   │                             questionLabelTruncator, taskResumeInfo,
84  │   │                             runtimeFallback, legacyPluginToast
85  │   ├─ createToolGuardHooks()   # 17 [+1 with team-mode]: commentChecker, toolOutputTruncator,
86  │   │                             directoryAgentsInjector, directoryReadmeInjector,
87  │   │                             emptyTaskResponseDetector, rulesInjector, tasksTodowriteDisabler,
88  │   │                             writeExistingFileGuard, bashFileReadGuard, hashlineReadEnhancer,
89  │   │                             jsonErrorRecovery, readImageResizer, todoDescriptionOverride,
90  │   │                             webfetchRedirectGuard, fsyncSkipWarning,
91  │   │                             notepadWriteGuard, planFormatValidator [+ teamToolGating]
92  │   └─ createTransformHooks()   # 4 [+2 with team-mode]: claudeCodeHooks, keywordDetector,
93  │                                  contextInjectorMessagesTransform,
94  │                                  toolPairValidator [+ teamModeStatusInjector, teamMailboxInjector]
95  ├─→ createContinuationHooks()   # 7: stopContinuationGuard, compactionContextInjector,
96  │                                  compactionTodoPreserver, todoContinuationEnforcer (boulder),
97  │                                  unstableAgentBabysitter, backgroundNotificationHook, atlasHook
98  └─→ createSkillHooks()          # 2: categorySkillReminder, autoSlashCommand
99 
100  Direct event handlers (src/plugin/event.ts, when team_mode.enabled): +4
101    team-idle-wake-hint, team-lead-orphan-handler,
102    team-member-error-handler, team-member-status-handler
103```
104 
105Total: 53 base, 60 with team-mode. Each tier produces an object whose values are `(input, output) => void` handlers; the matching OpenCode handler invokes them in registration order via `safeHook()` wrappers.
106 
107## SUBSYSTEM INVENTORY
108 
109| Subdir | Purpose | Has AGENTS.md |
110|--------|---------|---------------|
111| `agents/` | 11 agent factories + dynamic prompt builder | yes (+ atlas, hephaestus, prometheus, sisyphus, sisyphus-junior, builtin-agents) |
112| `hooks/` | 53-60 lifecycle hooks across 60 dirs | yes (+ atlas, anthropic-context-window-limit-recovery, auto-update-checker, claude-code-hooks, comment-checker, compaction-context-injector, keyword-detector, ralph-loop, rules-injector, runtime-fallback, todo-continuation-enforcer) |
113| `tools/` | 14 native tool dirs (+1 shared utilities dir); LSP + AST-grep moved to built-in MCPs | yes (+ background-task, call-omo-agent, delegate-task, hashline-edit, look-at, skill) |
114| `features/` | 23 feature modules (some now shimming `team-core`, `tmux-core`, `skills-loader-core`, `mcp-client-core`, and `claude-code-compat-core`) | yes (+ 11 sub-AGENTS.md including builtin-skills, team-mode, background-agent, claude-code-*) |
115| `shared/` | Cross-cutting adapter utilities plus shims over extracted Core packages, barrel-exported | yes |
116| `cli/` | Commander.js CLI: install, run, doctor, mcp-oauth, boulder | yes (+ config-manager, doctor, run) |
117| `plugin/` | 12 OpenCode hook handlers + hook composition | yes |
118| `config/` | Zod v4 schema files | yes |
119| `plugin-handlers/` | 6-phase config loading pipeline | yes |
120| `openclaw/` | Bidirectional Discord/Telegram/HTTP integration | yes |
121| `__tests__/` | Plugin-level integration tests + perf fixtures | yes |
122| `mcp/` | 5 built-in MCPs (3 remote + local stdio lsp + codegraph) | yes |
123| `testing/` | Test utilities + `create-plugin-module.ts` | yes |
124| `config-migration/` | Legacy config discovery + transform plans (consumed by senpi config-startup + codex startup) | yes |
125| `types/` | Ambient `.d.ts` declarations (markdown modules) | no |
126| `help/` | CLI help schema definitions (acp, doctor, sandbox, status) | no |
127| `locales/` | i18n strings (en, zh): toasts + model-fallback labels | no |
128 
129## NOTES
130 
131- `plugin-interface.ts` is the **only** layer that talks to OpenCode's `Plugin` API. Every other file goes through it.
132- Reach for `shared/` before adding helpers anywhere else; duplicate utilities WILL be flagged in review.
133- Path aliases are forbidden. Use relative imports within a module, barrel imports across modules.
134