docs(agents): regenerate all AGENTS.md with deep codebase analysis
This commit is contained in:
YeonGyu-Kim
@@ -2,83 +2,92 @@
|
||||
|
||||
## OVERVIEW
|
||||
|
||||
88 cross-cutting utilities. Import via barrel pattern: `import { log, deepMerge } from "../../shared"`
|
||||
|
||||
**Categories**: Path resolution, Token truncation, Config parsing, Model resolution, System directives, Tool restrictions
|
||||
84 cross-cutting utilities across 6 subdirectories. Import via barrel: `import { log, deepMerge } from "../../shared"`
|
||||
|
||||
## STRUCTURE
|
||||
```
|
||||
shared/
|
||||
├── git-worktree/ # Git worktree operations (311 lines)
|
||||
├── tmux/ # Tmux TUI integration (227 lines)
|
||||
├── logger.ts # File-based logging (/tmp/oh-my-opencode.log) - 53 imports
|
||||
├── dynamic-truncator.ts # Token-aware context window management (201 lines)
|
||||
├── model-resolver.ts # 3-step resolution (Override → Fallback → Default)
|
||||
├── model-requirements.ts # Agent/category model fallback chains (160 lines)
|
||||
├── model-availability.ts # Provider model fetching & fuzzy matching (358 lines)
|
||||
├── model-sanitizer.ts # Model name sanitization
|
||||
├── model-suggestion-retry.ts # Model suggestion on failure
|
||||
├── jsonc-parser.ts # JSONC parsing with comment support
|
||||
├── frontmatter.ts # YAML frontmatter extraction (JSON_SCHEMA only) - 9 imports
|
||||
├── data-path.ts # XDG-compliant storage resolution
|
||||
├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines) - 9 imports
|
||||
├── claude-config-dir.ts # ~/.claude resolution - 9 imports
|
||||
├── migration.ts # Legacy config migration logic (341 lines across dir)
|
||||
├── opencode-version.ts # Semantic version comparison
|
||||
├── permission-compat.ts # Agent tool restriction enforcement - 6 imports
|
||||
├── system-directive.ts # Unified system message prefix & types - 8 imports
|
||||
├── session-utils.ts # Session cursor, orchestrator detection
|
||||
├── session-cursor.ts # Session message cursor tracking
|
||||
├── shell-env.ts # Cross-platform shell environment
|
||||
├── agent-variant.ts # Agent variant from config
|
||||
├── zip-extractor.ts # Binary/Resource ZIP extraction
|
||||
├── deep-merge.ts # Recursive object merging (proto-pollution safe, MAX_DEPTH=50)
|
||||
├── command-executor.ts # Shell command execution (213 lines across dir)
|
||||
├── snake-case.ts # Case conversion utilities
|
||||
├── tool-name.ts # Tool naming conventions
|
||||
├── pattern-matcher.ts # Pattern matching utilities
|
||||
├── port-utils.ts # Port management
|
||||
├── file-utils.ts # File operation utilities
|
||||
├── file-reference-resolver.ts # File reference resolution
|
||||
├── connected-providers-cache.ts # Provider caching
|
||||
├── external-plugin-detector.ts # Plugin detection
|
||||
├── first-message-variant.ts # Message variant types
|
||||
├── opencode-server-auth.ts # Authentication utilities
|
||||
└── index.ts # Barrel export for all utilities
|
||||
├── logger.ts # File logging (/tmp/oh-my-opencode.log) — 62 imports
|
||||
├── dynamic-truncator.ts # Token-aware context window management (201 lines)
|
||||
├── model-resolver.ts # 3-step resolution (Override → Fallback → Default)
|
||||
├── model-availability.ts # Provider model fetching & fuzzy matching (358 lines)
|
||||
├── model-requirements.ts # Agent/category fallback chains (160 lines)
|
||||
├── model-resolution-pipeline.ts # Pipeline orchestration (175 lines)
|
||||
├── model-resolution-types.ts # Resolution request/provenance types
|
||||
├── model-sanitizer.ts # Model name sanitization
|
||||
├── model-name-matcher.ts # Model name matching (91 lines)
|
||||
├── model-suggestion-retry.ts # Suggest models on failure (129 lines)
|
||||
├── model-cache-availability.ts # Cache availability checking
|
||||
├── fallback-model-availability.ts # Fallback model logic (67 lines)
|
||||
├── available-models-fetcher.ts # Fetch models from providers (114 lines)
|
||||
├── models-json-cache-reader.ts # Read models.json cache
|
||||
├── provider-models-cache-model-reader.ts # Provider cache reader
|
||||
├── connected-providers-cache.ts # Provider caching (196 lines)
|
||||
├── system-directive.ts # Unified message prefix & types (61 lines) — 11 imports
|
||||
├── session-utils.ts # Session cursor, orchestrator detection
|
||||
├── session-cursor.ts # Message cursor tracking (85 lines)
|
||||
├── session-injected-paths.ts # Injected file path tracking
|
||||
├── permission-compat.ts # Tool restriction enforcement (86 lines)
|
||||
├── agent-tool-restrictions.ts # Tool restriction definitions
|
||||
├── agent-variant.ts # Agent variant from config (91 lines)
|
||||
├── agent-display-names.ts # Agent display name mapping
|
||||
├── first-message-variant.ts # First message variant types
|
||||
├── opencode-config-dir.ts # ~/.config/opencode resolution (138 lines)
|
||||
├── claude-config-dir.ts # ~/.claude resolution
|
||||
├── data-path.ts # XDG-compliant storage (47 lines)
|
||||
├── jsonc-parser.ts # JSONC with comment support (66 lines)
|
||||
├── frontmatter.ts # YAML frontmatter extraction (31 lines) — 10 imports
|
||||
├── deep-merge.ts # Recursive merge (proto-pollution safe, MAX_DEPTH=50)
|
||||
├── shell-env.ts # Cross-platform shell environment (111 lines)
|
||||
├── opencode-version.ts # Semantic version comparison (74 lines)
|
||||
├── external-plugin-detector.ts # Plugin conflict detection (137 lines)
|
||||
├── opencode-server-auth.ts # Authentication utilities (69 lines)
|
||||
├── safe-create-hook.ts # Hook error wrapper (24 lines)
|
||||
├── pattern-matcher.ts # Pattern matching (40 lines)
|
||||
├── file-utils.ts # File operations (40 lines) — 9 imports
|
||||
├── file-reference-resolver.ts # File reference resolution (85 lines)
|
||||
├── snake-case.ts # Case conversion (44 lines)
|
||||
├── tool-name.ts # Tool naming conventions
|
||||
├── truncate-description.ts # Description truncation
|
||||
├── port-utils.ts # Port management (48 lines)
|
||||
├── zip-extractor.ts # ZIP extraction (83 lines)
|
||||
├── binary-downloader.ts # Binary download (60 lines)
|
||||
├── skill-path-resolver.ts # Skill path resolution
|
||||
├── hook-disabled.ts # Hook disable checking
|
||||
├── config-errors.ts # Config error types
|
||||
├── disabled-tools.ts # Disabled tools tracking
|
||||
├── record-type-guard.ts # Record type guard
|
||||
├── open-code-client-accessors.ts # Client accessor utilities
|
||||
├── open-code-client-shapes.ts # Client shape types
|
||||
├── command-executor/ # Shell execution (6 files, 213 lines)
|
||||
├── git-worktree/ # Git status/diff parsing (8 files, 311 lines)
|
||||
├── migration/ # Legacy config migration (5 files, 341 lines)
|
||||
│ ├── config-migration.ts # Migration orchestration (126 lines)
|
||||
│ ├── agent-names.ts # Agent name mapping (70 lines)
|
||||
│ ├── hook-names.ts # Hook name mapping (36 lines)
|
||||
│ └── model-versions.ts # Model version migration (49 lines)
|
||||
└── tmux/ # Tmux TUI integration (12 files, 427 lines)
|
||||
└── tmux-utils/ # Pane spawn, close, replace, layout, health
|
||||
```
|
||||
|
||||
## MOST IMPORTED
|
||||
|
||||
| Utility | Imports | Purpose |
|
||||
|---------|---------|---------|
|
||||
| logger.ts | 53 | Background task visibility |
|
||||
| opencode-config-dir.ts | 9 | Path resolution |
|
||||
| claude-config-dir.ts | 9 | Path resolution |
|
||||
| frontmatter.ts | 9 | YAML parsing |
|
||||
| system-directive.ts | 8 | Message filtering |
|
||||
| permission-compat.ts | 6 | Tool restrictions |
|
||||
|
||||
## WHEN TO USE
|
||||
| Task | Utility |
|
||||
|------|---------|
|
||||
| Path Resolution | `getOpenCodeConfigDir()`, `getDataPath()` |
|
||||
| Token Truncation | `dynamicTruncate(ctx, sessionId, output)` |
|
||||
| Config Parsing | `readJsoncFile<T>(path)`, `parseJsonc(text)` |
|
||||
| Model Resolution | `resolveModelWithFallback(client, reqs, override)` |
|
||||
| Version Gating | `isOpenCodeVersionAtLeast(version)` |
|
||||
| YAML Metadata | `parseFrontmatter(content)` |
|
||||
| Tool Security | `createAgentToolAllowlist(tools)` |
|
||||
| System Messages | `createSystemDirective(type)`, `isSystemDirective(msg)` |
|
||||
| Deep Merge | `deepMerge(target, source)` |
|
||||
| logger.ts | 62 | Background task visibility |
|
||||
| data-path.ts | 11 | XDG storage resolution |
|
||||
| model-requirements.ts | 11 | Agent fallback chains |
|
||||
| system-directive.ts | 11 | System message filtering |
|
||||
| frontmatter.ts | 10 | YAML metadata extraction |
|
||||
| permission-compat.ts | 9 | Tool restrictions |
|
||||
| file-utils.ts | 9 | File operations |
|
||||
| dynamic-truncator.ts | 7 | Token-aware truncation |
|
||||
|
||||
## KEY PATTERNS
|
||||
|
||||
**3-Step Resolution** (Override → Fallback → Default):
|
||||
**3-Step Model Resolution** (Override → Fallback → Default):
|
||||
```typescript
|
||||
const model = resolveModelWithFallback({
|
||||
userModel: config.agents.sisyphus.model,
|
||||
fallbackChain: AGENT_MODEL_REQUIREMENTS.sisyphus.fallbackChain,
|
||||
availableModels: fetchedModels,
|
||||
})
|
||||
resolveModelWithFallback({ userModel, fallbackChain, availableModels })
|
||||
```
|
||||
|
||||
**System Directive Filtering**:
|
||||
@@ -88,8 +97,9 @@ const directive = createSystemDirective("TODO CONTINUATION")
|
||||
```
|
||||
|
||||
## ANTI-PATTERNS
|
||||
|
||||
- **Raw JSON.parse**: Use `jsonc-parser.ts` for comment support
|
||||
- **Hardcoded Paths**: Use `*-config-dir.ts` or `data-path.ts`
|
||||
- **Hardcoded paths**: Use `opencode-config-dir.ts` or `data-path.ts`
|
||||
- **console.log**: Use `logger.ts` for background task visibility
|
||||
- **Unbounded Output**: Use `dynamic-truncator.ts` to prevent overflow
|
||||
- **Manual Version Check**: Use `opencode-version.ts` for semver safety
|
||||
- **Unbounded output**: Use `dynamic-truncator.ts` to prevent overflow
|
||||
- **Manual version check**: Use `opencode-version.ts` for semver safety
|
||||
|
||||
Reference in New Issue
Block a user