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

src/utils/

Cross-cutting runtime utilities used by orchestration, hooks, and plugin I/O.

Responsibility

• tmux.ts: Multiplexer-safe pane lifecycle helpers (spawnPane, closePane) used by tmux and zellij adapters.
• subagent-depth.ts: Tracks delegated session depth and enforces max nested delegation depth.
• agent-variant.ts: Normalizes agent names and applies optional variant labels without overriding existing body configuration.
• env.ts: Unified environment lookup across Bun/Node with empty-string filtering.
• session-manager.ts: Tracks resumable task tool sessions by parent session + agent type, normalizes user labels, assigns stable short aliases, and exposes prompt rendering/eviction behavior.
• session.ts: Session extraction helpers for multi-turn synthesis and prompt/result post-processing.
• polling.ts: Shared polling with stability thresholds and abort-signal support.
• zip-extractor.ts: Cross-platform zip/tar extraction with Windows fallback tooling.
• task.ts: Parses task tool CLI output to recover task_id for resumption.
• system-collapse.ts: Collapses multiple system prompt fragments into one array element while mutating the original array reference.
• logger.ts: Structured JSON logging to temporary files.
• internal-initiator.ts: Marker utilities for internal orchestrator text-part tagging.
• compat.ts: Backward compatibility helpers.
• index.ts: Public re-export barrel for utility modules.

Design

• Deterministic lifecycle tracking: SubagentDepthTracker maps session IDs → depth and is cleaned on session deletion.
• Parent-scoped resumable session store: SessionManager groups tasks by {parentSessionId, agentType} and maintains LRU-ish ordering by last-used counter so active resumable sessions stay in memory.
• Provider-safe env access: getEnv falls back from Bun.env to process.env and normalizes blank values.
• Graceful shutdown protocol: Multiplexer pane close path sends Ctrl+C before kill, then rebalances layout state.
• Session extraction model: extractSessionResult/parseModelReference style helpers are centralized under session.ts.
• In-place system normalization: collapseSystemInPlace purposely mutates system array to preserve references held by OpenCode internals.
• Resilient polling: pollUntilStable requires consecutive confirmations before success.

Flow

subagent-depth.ts

• registerChild(parentSessionId, childSessionId) computes childDepth = parentDepth + 1.
• Blocks registration when depth exceeds DEFAULT_MAX_SUBAGENT_DEPTH.
• cleanup(sessionId) and cleanupAll() remove depth state for terminated sessions.

session-manager.ts

• deriveTaskSessionLabel computes a deterministic prompt hint:
  • uses description if provided,
  • falls back to first non-empty normalized line of prompt,
  • else returns recent {agentType} task.
• remember creates/reuses entries keyed by {parentSessionId, agentType} and enforces a per-agent max via trimGroup.
• Alias generation is monotonic within each parent+agent (exp-1, lib-2, etc.).
• markUsed, resolve, drop, dropTask, clearParent keep the store consistent on reuse and teardown.
• formatForPrompt returns grouped and ranked prompt text (### Resumable Sessions ...) for use in system transforms.

tmux.ts

• spawnPane flow: validate enabled state → check multiplexer availability → resolve binary → execute attach command with layout handling.
• closePane flow: send SIGINT-equivalent key sequence → delay → terminate pane → rebalance layout if needed.
• isServerRunning flow: bounded /health checks with retries and caching.

polling.ts

• pollUntilStable(fn, options) repeatedly calls async predicate and tracks consecutive true states.
• Returns once stable threshold is met, timeout elapses, or abort signal is raised.

session.ts

• Composes prompt parts and extracts normalized session output for text/call/result flows.
• Hosts shared parsing/formatting utilities used by council and tool execution layers.

task.ts

• Scans task output line-by-line and extracts task_id from task_id: <id> format.

system-collapse.ts

• collapseSystemInPlace(system: string[]) joins all system entries using \n\n, clears and repopulates the same array reference, and preserves empty-array behavior.

Integration

• Consumers

  • src/multiplexer/*: SubagentDepthTracker and tmux.ts integration.
  • src/council/council-manager.ts: depth control and session extraction helpers.
  • src/hooks/*: marker detection, polling, and session-aware state helpers.
  • src/hooks/task-session-manager: SessionManager, parseTaskIdFromTaskOutput, and deriveTaskSessionLabel provide resumable-session workflow; the plugin’s system-transform passes the hook output through collapseSystemInPlace after this manager injects prompts.

• Dependencies

  • Pulls constants from ../config (DEFAULT_MAX_SUBAGENT_DEPTH, polling intervals/timeouts).
  • index.ts re-exports utility API (agent-variant, env, polling, logger, session, subagent-depth, etc.).