oh-my-openagent/src/shared/AGENTS.md

SHARED UTILITIES KNOWLEDGE BASE

OVERVIEW

50 cross-cutting utilities: path resolution, token truncation, config parsing, model resolution.

STRUCTURE

shared/
├── logger.ts              # File-based logging
├── permission-compat.ts   # Agent tool restrictions
├── dynamic-truncator.ts   # Token-aware truncation
├── frontmatter.ts         # YAML frontmatter
├── jsonc-parser.ts        # JSON with Comments
├── data-path.ts           # XDG-compliant storage
├── opencode-config-dir.ts # ~/.config/opencode
├── claude-config-dir.ts   # ~/.claude
├── migration.ts           # Legacy config migration
├── opencode-version.ts    # Version comparison
├── external-plugin-detector.ts # OAuth spoofing detection
├── env-expander.ts        # ${VAR} expansion
├── model-requirements.ts  # Agent/Category requirements
├── model-availability.ts  # Models fetch + fuzzy match
├── model-resolver.ts      # 3-step resolution
├── shell-env.ts           # Cross-platform shell
├── prompt-parts-helper.ts # Prompt manipulation
└── *.test.ts              # Colocated tests

WHEN TO USE

Task	Utility
Debug logging	log(message, data)
Limit context	dynamicTruncate(ctx, sessionId, output)
Parse frontmatter	parseFrontmatter(content)
Load JSONC	parseJsonc(text) or readJsoncFile(path)
Restrict tools	createAgentToolAllowlist(tools)
Resolve paths	getOpenCodeConfigDir()
Compare versions	isOpenCodeVersionAtLeast("1.1.0")
Resolve model	resolveModelWithFallback()

PATTERNS

// Token-aware truncation
const { result } = await dynamicTruncate(ctx, sessionID, buffer)

// JSONC config
const settings = readJsoncFile<Settings>(configPath)

// Version-gated
if (isOpenCodeVersionAtLeast("1.1.0")) { /* ... */ }

// Model resolution
const model = await resolveModelWithFallback(client, requirements, override)

ANTI-PATTERNS

• Raw JSON.parse: Use jsonc-parser.ts
• Hardcoded paths: Use *-config-dir.ts
• console.log: Use logger.ts for background
• Unbounded output: Use dynamic-truncator.ts