Skip to content

codemap.md

Latest commit

 

History

History
61 lines (46 loc) · 4.32 KB

codemap.md

File metadata and controls

61 lines (46 loc) · 4.32 KB

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