YeonGyu-Kim
64825158a7
* refactor(keyword-detector): split constants into domain-specific modules * feat(shared): add requiresAnyModel and isAnyFallbackModelAvailable * feat(config): add hephaestus to agent schemas * feat(agents): add Hephaestus autonomous deep worker * feat(cli): update model-fallback for hephaestus support * feat(plugin): add hephaestus to config handler with ordering * test(delegate-task): update tests for hephaestus agent * docs: update AGENTS.md files for hephaestus * docs: add hephaestus to READMEs * chore: regenerate config schema * fix(delegate-task): bypass requiresModel check when user provides explicit config * docs(hephaestus): add 4-part context structure for explore/librarian prompts * docs: fix review comments from cubic (non-breaking changes) - Move Hephaestus from Primary Agents to Subagents (uses own fallback chain) - Fix Hephaestus fallback chain documentation (claude-opus-4-5 → gemini-3-pro) - Add settings.local.json to claude-code-hooks config sources - Fix delegate_task parameters in ultrawork prompt (agent→subagent_type, background→run_in_background, add load_skills) - Update line counts in AGENTS.md (index.ts: 788, manager.ts: 1440) * docs: fix additional documentation inconsistencies from oracle review - Fix delegate_task parameters in Background Agents example (docs/features.md) - Fix Hephaestus fallback chain in root AGENTS.md to match model-requirements.ts * docs: clarify Hephaestus has no fallback (requires gpt-5.2-codex only) Hephaestus uses requiresModel constraint - it only activates when gpt-5.2-codex is available. The fallback chain in code is unreachable, so documentation should not mention fallbacks. * fix(hephaestus): remove unreachable fallback chain entries Hephaestus has requiresModel: gpt-5.2-codex which means the agent only activates when that specific model is available. The fallback entries (claude-opus-4-5, gemini-3-pro) were unreachable and misleading. --------- Co-authored-by: justsisyphus <justsisyphus@users.noreply.github.com>
82 lines
3.7 KiB
Markdown
82 lines
3.7 KiB
Markdown
# SHARED UTILITIES KNOWLEDGE BASE
|
|
|
|
## OVERVIEW
|
|
|
|
55 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
|
|
|
|
## STRUCTURE
|
|
```
|
|
shared/
|
|
├── tmux/ # Tmux TUI integration (types, utils, constants)
|
|
├── logger.ts # File-based logging (/tmp/oh-my-opencode.log)
|
|
├── dynamic-truncator.ts # Token-aware context window management (194 lines)
|
|
├── model-resolver.ts # 3-step resolution (Override → Fallback → Default)
|
|
├── model-requirements.ts # Agent/category model fallback chains (162 lines)
|
|
├── model-availability.ts # Provider model fetching & fuzzy matching (154 lines)
|
|
├── jsonc-parser.ts # JSONC parsing with comment support
|
|
├── frontmatter.ts # YAML frontmatter extraction (JSON_SCHEMA only)
|
|
├── data-path.ts # XDG-compliant storage resolution
|
|
├── opencode-config-dir.ts # ~/.config/opencode resolution (143 lines)
|
|
├── claude-config-dir.ts # ~/.claude resolution
|
|
├── migration.ts # Legacy config migration logic (231 lines)
|
|
├── opencode-version.ts # Semantic version comparison
|
|
├── permission-compat.ts # Agent tool restriction enforcement
|
|
├── system-directive.ts # Unified system message prefix & types
|
|
├── session-utils.ts # Session cursor, orchestrator detection
|
|
├── 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)
|
|
├── case-insensitive.ts # Case-insensitive object lookups
|
|
├── session-cursor.ts # Session message cursor tracking
|
|
├── command-executor.ts # Shell command execution (225 lines)
|
|
└── index.ts # Barrel export for all utilities
|
|
```
|
|
|
|
## MOST IMPORTED
|
|
| Utility | Users | Purpose |
|
|
|---------|-------|---------|
|
|
| logger.ts | 16+ | Background task visibility |
|
|
| system-directive.ts | 8+ | Message filtering |
|
|
| opencode-config-dir.ts | 8+ | Path resolution |
|
|
| 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)` |
|
|
|
|
## KEY PATTERNS
|
|
|
|
**3-Step Resolution** (Override → Fallback → Default):
|
|
```typescript
|
|
const model = resolveModelWithFallback({
|
|
userModel: config.agents.sisyphus.model,
|
|
fallbackChain: AGENT_MODEL_REQUIREMENTS.sisyphus.fallbackChain,
|
|
availableModels: fetchedModels,
|
|
})
|
|
```
|
|
|
|
**System Directive Filtering**:
|
|
```typescript
|
|
if (isSystemDirective(message)) return // Skip system-generated
|
|
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`
|
|
- **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
|