oh-my-opencode-slim/src/utils/codemap.md

src/utils/

Shared utility modules providing low-level services: TMUX orchestration, environment variables, polling, logging, ZIP extraction, agent variant resolution, and internal agent marker handling.

Responsibility

• tmux.ts: Terminal multiplexer pane lifecycle management—spawning, closing, layout rebalancing, and server health probing for background task sessions
• env.ts: Cross-platform environment variable access supporting Bun and Node.js runtime with empty string filtering
• internal-initiator.ts: Marker-based identification for internal agent text parts in MCP protocol communication
• polling.ts: Generic polling utility with stability detection and abort signal support for asynchronous condition waiting
• zip-extractor.ts: Cross-platform ZIP/TAR extraction supporting Windows (tar, pwsh, powershell) and Unix (unzip)
• logger.ts: File-based structured logging to temp directory with timestamp and JSON serialization
• agent-variant.ts: Agent name normalization and variant resolution from plugin configuration with non-overriding application
• index.ts: Central re-export barrel for all utils

Design

• Lazy initialization: TMUX binary path discovery is deferred and cached after first check
• Defensive guards: Empty string filtering on env vars, server availability checks before pane spawns, abort signal propagation in polling
• Graceful shutdown protocol: TMUX panes receive SIGINT (Ctrl+C) before termination to allow clean process exit
• Layout persistence: Stored config enables rebalancing remaining panes after pane closure
• Server health probing: HTTP /health endpoint validation with retry logic and result caching
• Platform detection: process.env.TMUX check for tmux context, process.platform for OS-specific extraction strategy
• Stability threshold: Polling waits for N consecutive stable results before returning success
• Non-overriding variant application: Agent variant is applied only if body doesn't already contain one
• PowerShell path escaping: Single quotes escaped as doubled single quotes for Windows archive extraction

Flow

tmux.ts:

• spawnTmuxPane() → validate config.enabled → check tmux context → probe server health → discover tmux binary → split pane with opencode attach <url> --session <id> → rename pane → apply layout → return paneId
• closeTmuxPane() → send Ctrl+C → wait 250ms → kill-pane → reapply layout to rebalance
• isServerRunning() → GET /health with 3s timeout → retry up to 2 times → cache result

env.ts:

• getEnv(name) → check Bun.env first → fallback to process.env → filter empty strings

internal-initiator.ts:

• createInternalAgentTextPart() → append marker to text
• hasInternalInitiatorMarker() → check if part.type === 'text' and contains marker

polling.ts:

• pollUntilStable() → loop with configurable interval → call fetchFn → check stability predicate → increment stable count on match → reset on failure → return on threshold or timeout
• delay(ms) → Promise-wrapped setTimeout

zip-extractor.ts:

• extractZip() → detect platform → Windows: check build number for tar support, fallback to pwsh/powershell → Unix: use unzip → spawn process → await exit code → throw on failure

logger.ts:

• log() → construct timestamp → serialize data to JSON → append to temp log file → catch and ignore errors

agent-variant.ts:

• normalizeAgentName() → trim whitespace → strip @ prefix
• resolveAgentVariant() → normalize name → lookup in config.agents → validate type and non-empty → return trimmed variant
• applyAgentVariant() → return original body if variant falsy or body already has variant → spread merge variant into body

Integration

• Consumers: Background task manager spawns/closes tmux panes, MCP protocol layer checks for internal initiator markers, polling used by background task status monitoring, ZIP extraction for plugin updates, agent variant applied in request pipeline
• Dependencies: Imports TmuxConfig, TmuxLayout from ../config/schema, constants from ../config (POLL_INTERVAL_MS, MAX_POLL_TIME_MS, STABLE_POLLS_THRESHOLD), logging from ./logger, PluginConfig type from ../config
• Exports: All modules re-exported via src/utils/index.ts barrel file