AGENTS.md

1# src/shared/ — Shared Adapter Utilities
2 
3**Generated:** 2026-05-20
4 
5## OVERVIEW
6 
7Cross-cutting adapter utilities used throughout the plugin. Barrel-exported from `index.ts`. Logger writes `oh-my-opencode.log` to the OS temp dir (Node's `os.tmpdir()` — `/tmp` on Linux, `%TEMP%` on Windows, etc.); rotated at 50 MB; up to 2 backups at `.1` / `.2`. Includes runtime shims for `Bun.file`, `Bun.write`, `Bun.hash`, `Bun.which`, `Bun.spawn` to support non-Bun runtimes (Electron-hosted OpenCode). Many former utility implementations are now extracted to Core packages such as `utils`, `model-core`, `tmux-core`, `telemetry-core`, and `skills-loader-core`; keep local files as stable OpenCode import shims when existing wiring depends on their paths.
8 
9## CATEGORY MAP
10 
11| Category | Files | Key Exports |
12|----------|-------|-------------|
13| **Model Resolution** | ~22 | `resolveModel()`, `checkModelAvailability()`, `AGENT_MODEL_REQUIREMENTS` |
14| **Tmux Integration** | 11 | `createTmuxSession()`, `spawnPane()`, `closePane()`, server health |
15| **Configuration & Paths** | 10 | `resolveOpenCodeConfigDir()`, `getDataPath()`, `parseJSONC()` |
16| **Session Management** | 8 | `SessionCursor`, `trackInjectedPath()`, `SessionToolsStore` |
17| **Git Worktree** | 7 | `parseGitStatusPorcelain()`, `collectGitDiffStats()`, `formatFileChanges()` |
18| **Command Execution** | 7 | `executeCommand()`, `executeHookCommand()`, embedded command registry |
19| **Migration** | 6 | `migrateConfigFile()`, AGENT_NAME_MAP, HOOK_NAME_MAP, MODEL_VERSION_MAP |
20| **String & Tool Utils** | 6 | `toSnakeCase()`, `normalizeToolName()`, `parseFrontmatter()` |
21| **Agent Configuration** | 5 | `getAgentVariant()`, `AGENT_DISPLAY_NAMES`, `AGENT_TOOL_RESTRICTIONS` |
22| **OpenCode Integration** | 5 | `injectServerAuth()`, `detectExternalPlugins()`, client accessors |
23| **Type Helpers** | 4 | `deepMerge()`, `DynamicTruncator`, `matchPattern()`, `isRecord()` |
24| **Misc** | 8 | `log()`, `readFile()`, `extractZip()`, `downloadBinary()`, `findAvailablePort()` |
25 
26## MODEL RESOLUTION PIPELINE
27 
28```
29resolveModel(input)
30  1. Override: UI-selected model (primary agents only)
31  2. Category default: From category config
32  3. Provider fallback: AGENT_MODEL_REQUIREMENTS chains
33  4. System default: Ultimate fallback
34```
35 
36Key files: `model-resolver.ts` (entry), `model-resolution-pipeline.ts` (orchestration), `model-requirements.ts` (fallback chains), `model-availability.ts` (fuzzy matching).
37 
38## MIGRATION SYSTEM
39 
40Automatically transforms legacy config on load:
41- `agent-names.ts`: Old agent names → new (e.g., `junior` → `sisyphus-junior`)
42- `hook-names.ts`: Old hook names → new
43- `model-versions.ts`: Old model IDs → current
44- `agent-category.ts`: Legacy agent configs → category system
45 
46## MOST IMPORTED
47 
48| Utility | Import Count | Purpose |
49|---------|-------------|---------|
50| `logger.ts` | 62 | `oh-my-opencode.log` in `os.tmpdir()` (50 MB cap, rotates to `.1`/`.2`) |
51| `data-path.ts` | 11 | XDG storage resolution |
52| `model-requirements.ts` | 11 | Agent fallback chains |
53| `system-directive.ts` | 11 | System message filtering |
54| `frontmatter.ts` | 10 | YAML metadata extraction |
55