Files

T

YeonGyu-Kim 64825158a7 feat(agents): add Hephaestus - autonomous deep worker agent (#1287 )

* 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>

2026-02-01 19:26:57 +09:00

3.7 KiB

Raw Blame History

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):

const model = resolveModelWithFallback({
  userModel: config.agents.sisyphus.model,
  fallbackChain: AGENT_MODEL_REQUIREMENTS.sisyphus.fallbackChain,
  availableModels: fetchedModels,
})

System Directive Filtering:

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

3.7 KiB Raw Blame History