Bohdan TriapitsynandIuliia Ivashko
c9e31a0e6c
* fix: added desktop app background throttling
* perf: add streaming debug metrics panel
- Show streaming performance metrics in the debug panel
- Auto-enable stream profiling while the panel is open
- Add JSON export for sharing UI and VS Code metrics
* perf: batch streaming updates more aggressively
- Buffer message deltas and metadata updates to cut render churn
- Skip no-op part updates before they touch the message store
- Fix the desktop debug panel shortcut binding
* perf: split streaming event handling and coalesce deltas
- Move streaming content events onto a dedicated fast path
- Defer non-critical stream side effects off the hot path
- Merge repeated message delta events before they reach the UI
* perf: isolate streaming rows from chat rerenders
- Memoize chat rows against render-relevant message changes only
- Read live assistant text directly from store to narrow streaming updates
- Split the active streaming entry from the stable message list path
* perf: streamline chat streaming and SSE proxying
- Reduce chat rerenders around the active streaming path
- Simplify server SSE forwarding to avoid duplicate proxy work
* fix: preserve the first streaming text chunk
- Show the initial text chunk immediately before batched deltas arrive
- Bypass batching for the first text or reasoning part update
- Keep later streaming updates buffered for performance
* perf: align streaming/render hot paths with opencode parity
* perf: harden turn/cache stability and stale delta suppression
* fix: stabilize chat rendering and disable timeline interactions
- Disabled timeline dialog access from shortcuts, commands, and chat input
- Reduced chat render churn by simplifying message list and turn staging behavior
- Improved session-switch stability to prevent update-depth crashes
* perf: track static message rerenders during streaming
* perf: reduce sorted-mode activity rerender fanout
* perf: reduce chat rerender fanout and add active-turn metrics
- Reduced sorted-mode rerender coupling by tightening turn context propagation
- Added a metric for static rerenders outside the active turn during streaming
- Exposed new chat render counters in the debug panel for parity tracking
* fix: keep sorted activity mounted while stream grows
* fix: stabilize session and history scroll rendering
* refactor: decouple server routes from index
* refactor: extract fs module from server index
* refactor: move opencode route ownership into module
* refactor: extract notification route registration
* refactor: extract opencode and notification runtimes from index
* refactor: extract settings runtime and complete server modularization pass
* refactor: modularize server config, skills, icons, and tunnel routes
* refactor: extract server modules from monolithic index.js
Split proxy, routes, runtime helpers, and notification emitter
into dedicated modules under packages/web/server/lib/.
* refactor: replace session/message stores with SSE-driven sync layer
Delete ~9200 lines of old architecture (useEventStream, messageStore,
sessionStore, useSessionStore, questionStore, useTodoStore, client SSE).
New sync layer: event pipeline with coalescing + 16ms flush, pure event
reducer, per-directory child stores with LRU eviction, cursor pagination,
optimistic updates, deferred timeline staging, text throttle.
Migrate all UI consumers to sync hooks (useSessionMessages,
useSessionMessageRecords, useSessionStatus, useSessionPermissions, etc).
Strip session-ui-store to UI-only state, delegate SDK ops to
session-actions with abort-if-busy, optimistic store updates, and
response merging for revert/fork/archive/delete.
Add notification-store for SSE-driven session attention tracking,
cross-directory GlobalSessionStatusStore for sidebar indicators,
client-side diff snapshot sanitization to prevent memory bloat,
and revert message filtering via useVisibleSessionMessages.
* feat: notification store, session actions, activity detection
Add notification-store.ts for SSE-driven attention tracking.
Add sanitize.ts to strip diff snapshot memory bloat.
Add session-actions.ts with optimistic revert/fork/archive/delete.
Improve useSessionActivity with incomplete-message fallback.
Delete useServerSessionStatus polling hook.
* fix: add directory param to all SDK calls, fix command/shell/abort routing
All SDK calls in session-actions.ts now pass directory parameter —
required by OpenCode server to scope session operations. Without it,
abort, commands, revert, fork, and other operations returned 500.
Add routeMessage() in session-ui-store for shell mode (session.shell),
slash commands (session.command), and normal prompts. Command lookup
checks both sync child store and useCommandsStore. Handle /compact
locally via session.summarize().
Implement getContextUsage() to restore header context usage display —
reads token counts from last assistant message in sync store.
* refactor: replace custom API proxy with http-proxy-middleware
Remove ~280 lines of custom proxy code: forwardSseRequest,
forwardGenericApiRequest, collectRequestBodyBuffer, header
manipulation, hop-by-hop filtering, SSE block buffering.
Replace with single createProxyMiddleware() call that handles
SSE streaming, large bodies, and timeouts out of the box.
Dynamic router for OpenCode port changes after restarts.
Auth headers injected via proxyReq hook.
Keep: readiness gate, Windows session merge, API prefix detection.
* perf: targeted event draft cloning to fix streaming render cascade
Event handler was eagerly cloning all state slices on every event,
breaking Zustand selector referential equality. During streaming
(~60 events/sec), this caused every subscriber to re-render regardless
of which slice actually changed.
Now only clones fields the specific event type mutates. Also extracts
StatusRowContainer to isolate high-frequency useAssistantStatus
subscription, removes dead messageStreamStatesMap subscription from
ChatContainer, and narrows useAssistantStatus to only track last
assistant message parts.
MessageList renders: 1972 → 296 per streaming session (-85%).
* fix: null safety for sync state slices
Add defensive ?? {} guards on permission, question, session_status,
and message record access. Prevents crashes when child store state
is partially initialized during bootstrap.
* perf: dedup inflight SDK calls, extract concurrency util, delay PR tracking
Extract mapWithConcurrency to shared lib/concurrency.ts. Add in-flight
dedup for loadProviders/loadAgents to prevent concurrent duplicate SDK
calls. Delay initial PR background tracking by 5s to reduce startup
CPU burst.
* fix: header session lookup across all child stores
Session title and context panel click failed when session belonged to
a different directory than the current child store. Fall back to
getAllSyncSessions() to search all initialized stores.
* chore: bump @opencode-ai/sdk to 1.3.5
* docs: add sync event handling guide
* Optimize session prefetch and improve delete/archive UX
- Add settlement delay to session prefetch to avoid race conditions on
rapid session switches
- Reduce git diff prefetch and session cache limits for better performance
- Implement optimistic UI updates for session delete/archive operations
with proper rollback on failure
- Wire session prefetch hook into SessionSidebar with sync integration
* Add file content cache and sync optimizations
- Wrap FilesAPI with in-memory LRU cache for file content with dual
constraints (entry count and byte size)
- Optimize chat timeline scroll restoration using useLayoutEffect
- Preserve React references in message and part arrays to prevent
unnecessary re-renders when prepending history
- Add session prefetch TTL cache to prevent redundant fetches
- Integrate session prefetch cache clearing with eviction flow
* Improve session sidebar error handling and add diff prefetch filtering
Load active and archived sessions independently using Promise.allSettled
to prevent one failure from blocking the other. Add retry logic to session
API calls and skip large files during diff prefetch to improve performance.
* Replace sendMessage with optimisticSend wrapper
Introduces optimistic UI updates for normal chat messages to provide
instant feedback. Messages appear immediately in the UI while the API
call executes in the background, with automatic rollback on errors.
* perf: split stores, proper optimistic send, fix revert/directory bugs
- split session-ui-store into voice/input/selection/viewport stores
to reduce subscriber re-evaluation during streaming
- wire optimisticSend through useSync shadow Map infrastructure
matching OpenCode's pattern (no heuristic part detection)
- port OpenCode Identifier.ascending ID format for correct sorting
- pass messageID to promptAsync to prevent duplicate messages
- fix worktree directory not propagating to session actions
(dynamic dir() via opencodeClient.getDirectory)
- fix setCurrentSession accepting directoryHint for new sessions
- fix revert not hiding messages (session limit was 5, bumped to match loaded count)
- fix revert optimistic message removal from store
- fix load-more flicker (useLayoutEffect scroll compensation)
- add prefetch TTL cache, file content LRU cache
- add session prefetch for adjacent sessions
- add instant archive/delete (optimistic before SDK call)
- migrate legacy window.__zustand_session_store__ to session-ui-store
- add retry + independent error handling for archived sessions
- add AGENTS.md performance rules
* perf: startup optimization — dedup, caching, light git status, diff rendering gates
- defer diff prefetch to git tab open, reduce concurrency 4→2, skip >500 changed lines
- cap project git checks concurrency (2), directory status probe (3)
- dedup provider/agent loading, github auth, worktree list (in-flight + TTL caches)
- delay PR tracking 5s, cache 403 search failures per-repo
- coalesce settings PUT (200ms debounce), cache settings GET (2s TTL)
- cache canonical directory resolution (60s TTL)
- persist missing directory status to localStorage (10min TTL)
- light/heavy git status: polling skips numstat+line counting+rev-list
- large diff rendering gate (>500 lines → "render anyway" button)
- tokenization degradation for >500KB files in Pierre
- parallelize main.tsx pre-render awaits
- batch sidebar file tree expanded paths restoration (3 at a time)
- remove bare useConfigStore() subscription in AgentsPage
- sync worktree sandboxes to OpenCode SQLite DB
- fix RightSidebarTabs ternary → explicit tab matching
- defensive guards on sync state (session_status, permission, question, message)
* fix: add defensive guards on remaining sync state field accesses
guard session_status, permission, message, todo, part, config with ?? {}
in useDirectorySync selectors, session-cache, and bootstrap
* fix: add missing directory dep to useCallback in use-sync.ts
* fix: preserve diffStats when light-mode polling overwrites status
* perf: optimize startup git status polling and diff rendering
Preserves diff stats when lightweight polling updates repository status
Reduces startup overhead with smarter git polling and store updates
Adds detailed optimization and migration docs for next performance steps
* fix: keep chat diff stats stable during git status updates
Prevents lightweight git polling from dropping diff statistics
Keeps MessageList diff indicators consistent while status refreshes
Improves reliability of git-aware chat rendering
* fix: user animation replay, queued message variant, startup provider loading
- consume animation ID after first play to prevent re-animation
on neighbor assistant message completion
- capture send config (model/agent/variant) at queue time matching
OpenCode's FollowupDraft pattern instead of re-resolving at send time
- replace one-shot startup recovery effect with polling interval
that retries every 2s until providers and agents load
- fix optimistic bridge to avoid re-render loop (stable ref wrappers)
* chore: update tauri to 2.10.3 and all plugins to latest
- tauri 2.9.4 → 2.10.3
- tauri-build 2.5.3 → 2.5.6
- tauri-plugin-dialog 2.4.2 → 2.6.0
- tauri-plugin-log 2.7.1 → 2.8.0
- tauri-plugin-shell 2.3.3 → 2.3.5
- tauri-plugin-updater 2 (floating) → 2.10.0 (pinned)
- @tauri-apps/api ^2.9.0 → ^2.10.1
- wry 0.53.5 → 0.54.4 (transitive)
* refactor: decouple web server index orchestration runtimes
* fix: align VS Code runtime behavior with web and reduce draft view CPU load
- Queue VS Code bridge and SSE startup requests until API readiness to avoid false bootstrap failures
- Make agent manager actions directory-aware and remove real worktrees with safer partial-failure handling
- Replace heavy logo animation path with a lightweight pulse to cut draft-session CPU usage
* fix: restore auto-selected file sending in chat input
- Send server-selected files as proper file URLs in the message payload
- Include server-backed attachments in submit flow instead of dropping them
- Restore queued-message attachments through the refactored input store
* fix: restore session model selection consistently on session switch
- Restore agent, model, and variant from the latest loaded user message for each session
- Wait for session messages before applying restored selections to avoid stale or missing state
- Remove legacy session-choice inference paths that caused overlap and instability
* fix: restore permission replies and auto-accept across sessions
- Scope permission and question replies to the target session directory so answers take effect reliably
- Make permission auto-accept immediately handle pending requests and react to new permission prompts
- Keep parent-session handling working for child-session requests through the shared response path
* feat: add reusable fuzzy branch fuzzy-search helper and dialog integration (#798)
* feat: add reusable fuzzy branch search for worktrees
* chore: drop planning docs from feature branch
* feat: make worktree branch refresh manual
* feat: add configurable session retention action
* refactor: centralize global session state in ui store
* fix: cancel debounced permission push after reply
* docs: clarify global and directory session store architecture
* docs: refine agent development rules and session activity guidance
- Clarify agent code of conduct and durable development patterns
- Add explicit shared-store rerender and live-state guidance
- Narrow session activity fallback to avoid stale working state
* chore: updated .gitignore
---------
Co-authored-by: Iuliia Ivashko <yulia.ivashko@gmail.com>
356 lines
20 KiB
Markdown
356 lines
20 KiB
Markdown
# OpenCode Module Documentation
|
|
|
|
## Purpose
|
|
This module provides OpenCode server integration utilities for the web server runtime, including configuration management, provider authentication, and UI authentication with rate limiting.
|
|
|
|
## Entrypoints and structure
|
|
- `packages/web/server/lib/opencode/index.js`: public entrypoint (currently baseline placeholder).
|
|
- `packages/web/server/lib/opencode/auth.js`: provider authentication file operations.
|
|
- `packages/web/server/lib/opencode/auth-state-runtime.js`: managed OpenCode server auth password/header runtime.
|
|
- `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
|
|
- `packages/web/server/lib/opencode/cli-entry-runtime.js`: CLI entrypoint runtime that detects direct execution, parses CLI options, and starts server bootstrap.
|
|
- `packages/web/server/lib/opencode/routes.js`: OpenCode/provider settings and auth-related route registration.
|
|
- `packages/web/server/lib/opencode/lifecycle.js`: OpenCode process lifecycle runtime (startup, restart, readiness, health monitoring).
|
|
- `packages/web/server/lib/opencode/env-runtime.js`: OpenCode CLI/binary resolution and shell environment runtime.
|
|
- `packages/web/server/lib/opencode/env-config.js`: OpenCode-related environment variable parsing and validation (host/port/hostname).
|
|
- `packages/web/server/lib/opencode/hmr-state-runtime.js`: HMR-persistent runtime state initialization, auth-state bootstrap, and HMR sync helpers.
|
|
- `packages/web/server/lib/opencode/bootstrap-runtime.js`: base app bootstrap runtime for status/auth/tts/notification/OpenChamber route wiring.
|
|
- `packages/web/server/lib/opencode/network-runtime.js`: OpenCode URL construction, health-probe readiness checks, and API prefix runtime.
|
|
- `packages/web/server/lib/opencode/project-directory-runtime.js`: request-scoped and settings-backed project directory resolution/validation runtime.
|
|
- `packages/web/server/lib/opencode/config-entity-routes.js`: route registration for agent/command/MCP config orchestration and reload semantics.
|
|
- `packages/web/server/lib/opencode/cli-options.js`: CLI/environment option parsing for server startup arguments.
|
|
- `packages/web/server/lib/opencode/core-routes.js`: server status/system routes, auth/access guard routes, and settings utility route registration.
|
|
- `packages/web/server/lib/opencode/shutdown-runtime.js`: graceful shutdown orchestration runtime for watcher/session/terminal/process/server teardown.
|
|
- `packages/web/server/lib/opencode/server-startup-runtime.js`: server listen/startup tunnel flow and process/signal handler orchestration runtime.
|
|
- `packages/web/server/lib/opencode/static-routes-runtime.js`: static asset/SPA fallback route registration and manifest route wiring.
|
|
- `packages/web/server/lib/opencode/feature-routes-runtime.js`: feature route composition runtime for dynamic import-backed config/skill/provider route registration.
|
|
- `packages/web/server/lib/opencode/opencode-resolution-runtime.js`: OpenCode binary resolution snapshot runtime for settings routes and diagnostics.
|
|
- `packages/web/server/lib/opencode/tunnel-wiring-runtime.js`: tunnel service/routes composition runtime and active-port wiring for main server startup.
|
|
- `packages/web/server/lib/opencode/startup-pipeline-runtime.js`: server startup tail orchestration runtime for terminal/proxy/static/start-listen flow.
|
|
- `packages/web/server/lib/opencode/server-utils-runtime.js`: shared server runtime utilities for OpenCode proxy wiring, OpenCode port/readiness helpers, and snapshot fetchers.
|
|
- `packages/web/server/lib/opencode/openchamber-routes.js`: OpenChamber update and models metadata route registration.
|
|
- `packages/web/server/lib/opencode/pwa-manifest-routes.js`: PWA manifest route registration with recent-session shortcut resolution and short-lived caching.
|
|
- `packages/web/server/lib/opencode/project-icon-routes.js`: project icon upload/read/discovery route registration and icon storage orchestration.
|
|
- `packages/web/server/lib/opencode/skill-routes.js`: route registration for skill config CRUD, supporting files, and skills catalog scan/install flows.
|
|
- `packages/web/server/lib/opencode/settings-runtime.js`: Settings persistence runtime (disk IO, migrations, normalization, project validation, and persisted update serialization).
|
|
- `packages/web/server/lib/opencode/settings-helpers.js`: Settings payload sanitization/format helpers runtime for response shaping and persisted merge prep.
|
|
- `packages/web/server/lib/opencode/settings-normalization-runtime.js`: path/settings/tunnel normalization and sanitization helpers runtime used by settings/routes/config wiring.
|
|
- `packages/web/server/lib/opencode/theme-runtime.js`: custom theme JSON validation and theme directory loading runtime for settings utility routes.
|
|
- `packages/web/server/lib/opencode/proxy.js`: OpenCode API/SSE forwarding and readiness-gate route registration.
|
|
- `packages/web/server/lib/opencode/session-runtime.js`: session status/attention/activity runtime for OpenCode SSE events.
|
|
- `packages/web/server/lib/opencode/watcher.js`: global SSE watcher runtime for push/session event fanout.
|
|
- `packages/web/server/lib/opencode/shared.js`: shared utilities for config, markdown, skills, and git helpers.
|
|
- `packages/web/server/lib/opencode/ui-auth.js`: UI session authentication with rate limiting.
|
|
|
|
## Public exports (auth.js)
|
|
- `readAuthFile()`: Reads and parses `~/.local/share/opencode/auth.json`.
|
|
- `writeAuthFile(auth)`: Writes auth file with automatic backup.
|
|
- `removeProviderAuth(providerId)`: Removes a provider's auth entry.
|
|
- `getProviderAuth(providerId)`: Returns auth for a specific provider or null.
|
|
- `listProviderAuths()`: Returns list of provider IDs with configured auth.
|
|
- `AUTH_FILE`: Auth file path constant.
|
|
- `OPENCODE_DATA_DIR`: OpenCode data directory path constant.
|
|
|
|
## Public exports (shared.js)
|
|
- `OPENCODE_CONFIG_DIR`, `AGENT_DIR`, `COMMAND_DIR`, `SKILL_DIR`, `CONFIG_FILE`, `CUSTOM_CONFIG_FILE`: Path constants.
|
|
- `AGENT_SCOPE`, `COMMAND_SCOPE`, `SKILL_SCOPE`: Scope constants with USER and PROJECT values.
|
|
- `ensureDirs()`: Creates required OpenCode directories.
|
|
- `parseMdFile(filePath)`, `writeMdFile(filePath, frontmatter, body)`: Markdown file operations with YAML frontmatter.
|
|
- `getConfigPaths(workingDirectory)`, `readConfigLayers(workingDirectory)`, `readConfig(workingDirectory)`: Config file operations with layer merging (user, project, custom).
|
|
- `writeConfig(config, filePath)`: Writes config with automatic backup.
|
|
- `getJsonEntrySource(layers, sectionKey, entryName)`: Resolves which config layer provides an entry.
|
|
- `getJsonWriteTarget(layers, preferredScope)`: Determines write target for config updates.
|
|
- `getAncestors(startDir, stopDir)`, `findWorktreeRoot(startDir)`: Git worktree helpers.
|
|
- `isPromptFileReference(value)`, `resolvePromptFilePath(reference)`, `writePromptFile(filePath, content)`: Prompt file reference handling.
|
|
- `walkSkillMdFiles(rootDir)`: Recursively finds all SKILL.md files.
|
|
- `addSkillFromMdFile(skillsMap, skillMdPath, scope, source)`: Parses and indexes a skill file.
|
|
- `resolveSkillSearchDirectories(workingDirectory)`: Returns skill search path order (config, project, home, custom).
|
|
- `listSkillSupportingFiles(skillDir)`, `readSkillSupportingFile(skillDir, relativePath)`, `writeSkillSupportingFile(skillDir, relativePath, content)`, `deleteSkillSupportingFile(skillDir, relativePath)`: Skill supporting file management.
|
|
|
|
## Public exports (ui-auth.js)
|
|
- `createUiAuth({ password, cookieName, sessionTtlMs })`: Creates UI auth instance with methods:
|
|
- `enabled`: Boolean indicating if auth is configured.
|
|
- `requireAuth(req, res, next)`: Express middleware to enforce authentication.
|
|
- `handleSessionStatus(req, res)`: Returns authentication status.
|
|
- `handleSessionCreate(req, res)`: Handles login with rate limiting.
|
|
- `ensureSessionToken(req, res)`: Returns or creates session token.
|
|
- `dispose()`: Cleans up timers and state.
|
|
|
|
## Public exports (routes.js)
|
|
- `registerOpenCodeRoutes(app, dependencies)`: Registers OpenCode-owned HTTP routes and internal module runtime:
|
|
- `GET /api/config/settings`
|
|
- `PUT /api/config/settings`
|
|
- `GET /api/config/opencode-resolution`
|
|
- `POST /api/opencode/directory`
|
|
- `GET /api/provider/:providerId/source`
|
|
- `DELETE /api/provider/:providerId/auth`
|
|
- Owns lazy auth library loading for provider auth checks/removal.
|
|
- Keeps route behavior independent from composition root; `index.js` now supplies dependencies only.
|
|
|
|
## Public exports (session-runtime.js)
|
|
- `createSessionRuntime({ writeSseEvent, getNotificationClients })`: creates runtime-owned state machine and APIs for session status.
|
|
- Returned API:
|
|
- `processOpenCodeSsePayload(payload)`
|
|
- `getSessionActivitySnapshot()`
|
|
- `getSessionStateSnapshot()`
|
|
- `getSessionAttentionSnapshot()`
|
|
- `getSessionState(sessionId)`
|
|
- `getSessionAttentionState(sessionId)`
|
|
- `markSessionViewed(sessionId, clientId)`
|
|
- `markSessionUnviewed(sessionId, clientId)`
|
|
- `markUserMessageSent(sessionId)`
|
|
- `resetAllSessionActivityToIdle()`
|
|
- `dispose()`
|
|
|
|
## Public exports (lifecycle.js)
|
|
- `createOpenCodeLifecycleRuntime(dependencies)`: creates lifecycle runtime for managed/external OpenCode process orchestration.
|
|
- Returned API:
|
|
- `startOpenCode()`
|
|
- `restartOpenCode()`
|
|
- `waitForOpenCodeReady(timeoutMs?, intervalMs?)`
|
|
- `waitForAgentPresence(agentName, timeoutMs?, intervalMs?)`
|
|
- `refreshOpenCodeAfterConfigChange(reason, options?)`
|
|
- `bootstrapOpenCodeAtStartup()`
|
|
- `startHealthMonitoring(healthCheckIntervalMs)`
|
|
- `killProcessOnPort(port)`
|
|
|
|
## Public exports (env-runtime.js)
|
|
- `createOpenCodeEnvRuntime(dependencies)`: creates runtime that owns OpenCode CLI environment and binary discovery state.
|
|
- Returned API:
|
|
- `applyLoginShellEnvSnapshot()`
|
|
- `getLoginShellEnvSnapshot()`
|
|
- `ensureOpencodeCliEnv()`
|
|
- `applyOpencodeBinaryFromSettings()`
|
|
- `resolveOpencodeCliPath()`
|
|
- `resolveGitBinaryForSpawn()`
|
|
- `resolveWslExecutablePath()`
|
|
- `buildWslExecArgs(execArgs, distroOverride?)`
|
|
- `opencodeShimInterpreter(opencodePath)`
|
|
- `isExecutable(filePath)`
|
|
- `searchPathFor(binaryName)`
|
|
- `clearResolvedOpenCodeBinary()`
|
|
|
|
## Public exports (env-config.js)
|
|
- `resolveOpenCodeEnvConfig(options?)`: resolves and validates OpenCode host/port/hostname environment configuration.
|
|
- Returned object fields:
|
|
- `configuredOpenCodePort`
|
|
- `configuredOpenCodeHost`
|
|
- `effectivePort`
|
|
- `configuredOpenCodeHostname`
|
|
|
|
## Public exports (hmr-state-runtime.js)
|
|
- `createHmrStateRuntime(dependencies)`: creates runtime for HMR state container initialization and runtime<->HMR state synchronization.
|
|
- Returned API:
|
|
- `getOrCreateHmrState()`
|
|
- `ensureUserProvidedOpenCodePassword(hmrState)`
|
|
- `getUserProvidedOpenCodePassword(hmrState)`
|
|
- `resolveOpenCodeAuthFromState({ hmrState, userProvidedOpenCodePassword })`
|
|
- `syncStateFromRuntime(hmrState, runtime)`
|
|
- `restoreRuntimeFromState({ hmrState, userProvidedOpenCodePassword })`
|
|
|
|
## Public exports (bootstrap-runtime.js)
|
|
- `createBootstrapRuntime(dependencies)`: creates runtime for base app route bootstrap and UI auth controller initialization.
|
|
- Returned API:
|
|
- `setupBaseRoutes(app, options)`
|
|
|
|
## Public exports (network-runtime.js)
|
|
- `createOpenCodeNetworkRuntime(dependencies)`: creates runtime for OpenCode network and URL concerns.
|
|
- Returned API:
|
|
- `waitForReady(url, timeoutMs?)`
|
|
- `normalizeApiPrefix(prefix)`
|
|
- `setDetectedOpenCodeApiPrefix()`
|
|
- `buildOpenCodeUrl(path, prefixOverride?)`
|
|
- `ensureOpenCodeApiPrefix()`
|
|
- `scheduleOpenCodeApiDetection()`
|
|
|
|
## Public exports (settings-runtime.js)
|
|
- `createSettingsRuntime(dependencies)`: creates settings lifecycle runtime for read/migrate/persist concerns.
|
|
- Returned API:
|
|
- `readSettingsFromDisk()`
|
|
- `readSettingsFromDiskMigrated()`
|
|
- `writeSettingsToDisk(settings)`
|
|
- `persistSettings(changes)`
|
|
|
|
## Public exports (settings-helpers.js)
|
|
- `createSettingsHelpers(dependencies)`: creates settings helper runtime for settings request/response shaping.
|
|
- Returned API:
|
|
- `normalizePwaAppName(value, fallback?)`
|
|
- `sanitizeSettingsUpdate(payload)`
|
|
- `mergePersistedSettings(current, changes)`
|
|
- `formatSettingsResponse(settings)`
|
|
|
|
## Public exports (settings-normalization-runtime.js)
|
|
- `createSettingsNormalizationRuntime(dependencies)`: creates normalization/sanitization runtime for shared settings and tunnel helper logic.
|
|
- Returned API:
|
|
- `normalizeDirectoryPath(value)`
|
|
- `normalizePathForPersistence(value)`
|
|
- `normalizeSettingsPaths(input)`
|
|
- `normalizeTunnelBootstrapTtlMs(value)`
|
|
- `normalizeTunnelSessionTtlMs(value)`
|
|
- `normalizeManagedRemoteTunnelHostname(value)`
|
|
- `normalizeManagedRemoteTunnelPresets(value)`
|
|
- `normalizeManagedRemoteTunnelPresetTokens(value)`
|
|
- `isUnsafeSkillRelativePath(value)`
|
|
- `sanitizeTypographySizesPartial(input)`
|
|
- `normalizeStringArray(input)`
|
|
- `sanitizeModelRefs(input, limit)`
|
|
- `sanitizeSkillCatalogs(input)`
|
|
- `sanitizeProjects(input)`
|
|
|
|
## Public exports (theme-runtime.js)
|
|
- `createThemeRuntime(dependencies)`: creates custom theme runtime for on-disk theme discovery and JSON normalization/validation.
|
|
- Returned API:
|
|
- `normalizeThemeJson(raw)`
|
|
- `readCustomThemesFromDisk()`
|
|
|
|
## Public exports (project-directory-runtime.js)
|
|
- `createProjectDirectoryRuntime(dependencies)`: creates runtime for request/project directory candidate normalization and validation.
|
|
- Returned API:
|
|
- `resolveDirectoryCandidate(value)`
|
|
- `validateDirectoryPath(candidate)`
|
|
- `resolveProjectDirectory(req)`
|
|
- `resolveOptionalProjectDirectory(req)`
|
|
|
|
## Public exports (config-entity-routes.js)
|
|
- `registerConfigEntityRoutes(app, dependencies)`: registers configuration entity routes:
|
|
- Agents: `/api/config/agents/:name` and `/api/config/agents/:name/config`
|
|
- Commands: `/api/config/commands/:name`
|
|
- MCP servers: `/api/config/mcp` and `/api/config/mcp/:name`
|
|
|
|
## Public exports (auth-state-runtime.js)
|
|
- `createOpenCodeAuthStateRuntime(dependencies)`: creates runtime for managed OpenCode auth password state and request headers.
|
|
- Returned API:
|
|
- `getOpenCodeAuthHeaders()`
|
|
- `isOpenCodeConnectionSecure()`
|
|
- `ensureLocalOpenCodeServerPassword(options?)`
|
|
|
|
## Public exports (core-routes.js)
|
|
- `registerServerStatusRoutes(app, dependencies)`: registers status/system endpoints:
|
|
- `GET /health`
|
|
- `POST /api/system/shutdown`
|
|
- `GET /api/system/info`
|
|
- `registerAuthAndAccessRoutes(app, dependencies)`: registers browser auth/session exchange and API access middleware:
|
|
- `GET /auth/session`
|
|
- `POST /auth/session`
|
|
- `GET /connect`
|
|
- `app.use('/api', ...)` auth/tunnel guard
|
|
- `registerSettingsUtilityRoutes(app, dependencies)`: registers small settings utility endpoints:
|
|
- `GET /api/config/themes`
|
|
- `POST /api/config/reload`
|
|
- `registerCommonRequestMiddleware(app, dependencies)`: registers shared request middleware stack:
|
|
- conditional JSON body parser behavior for `/api/*` vs non-API requests
|
|
- URL-encoded parser setup
|
|
- request logging middleware
|
|
|
|
## Public exports (cli-options.js)
|
|
- `parseServeCliOptions(options)`: parses serve CLI flags and environment-derived defaults:
|
|
- Port/host/ui-password
|
|
- Tunnel provider/mode/config/token/hostname
|
|
- Legacy `--tunnel` shorthand normalization
|
|
|
|
## Public exports (cli-entry-runtime.js)
|
|
- `runCliEntryIfMain(dependencies)`: detects direct CLI execution and runs server startup with parsed CLI options.
|
|
|
|
## Public exports (server-utils-runtime.js)
|
|
- `createServerUtilsRuntime(dependencies)`: creates server utility runtime for OpenCode orchestration helpers.
|
|
- Returned API:
|
|
- `setOpenCodePort(port)`
|
|
- `waitForOpenCodePort(timeoutMs?)`
|
|
- `buildAugmentedPath()`
|
|
- `parseSseDataPayload(block)`
|
|
- `fetchAgentsSnapshot()`
|
|
- `fetchProvidersSnapshot()`
|
|
- `fetchModelsSnapshot()`
|
|
- `setupProxy(app)`
|
|
|
|
## Public exports (shutdown-runtime.js)
|
|
- `createGracefulShutdownRuntime(dependencies)`: creates graceful shutdown runtime for managed OpenCode and web server teardown sequencing.
|
|
- Returned API:
|
|
- `gracefulShutdown(options?)`
|
|
|
|
## Public exports (server-startup-runtime.js)
|
|
- `createServerStartupRuntime(dependencies)`: creates runtime for server bind/startup tunnel and process handler wiring.
|
|
- Returned API:
|
|
- `resolveBindHost(host)`
|
|
- `startListeningAndMaybeTunnel(options)`
|
|
- `attachProcessHandlers(options)`
|
|
|
|
## Public exports (static-routes-runtime.js)
|
|
- `createStaticRoutesRuntime(dependencies)`: creates runtime for static dist resolution and static route registration.
|
|
- Returned API:
|
|
- `registerStaticRoutes(app)`
|
|
|
|
## Public exports (feature-routes-runtime.js)
|
|
- `createFeatureRoutesRuntime(dependencies)`: creates runtime for main feature route registration orchestration.
|
|
- Returned API:
|
|
- `registerRoutes(app, routeDependencies)`
|
|
|
|
## Public exports (opencode-resolution-runtime.js)
|
|
- `createOpenCodeResolutionRuntime(dependencies)`: creates runtime for OpenCode binary/source snapshot resolution.
|
|
- Returned API:
|
|
- `getOpenCodeResolutionSnapshot(settings)`
|
|
|
|
## Public exports (tunnel-wiring-runtime.js)
|
|
- `createTunnelWiringRuntime(dependencies)`: creates runtime for tunnel service construction and tunnel route registration.
|
|
- Returned API:
|
|
- `initialize(app, initialPort)`
|
|
|
|
## Public exports (startup-pipeline-runtime.js)
|
|
- `createStartupPipelineRuntime(dependencies)`: creates runtime for terminal wiring, proxy/bootstrap scheduling, static route registration, and server startup/listen flow.
|
|
- Returned API:
|
|
- `run(options)`
|
|
|
|
## Public exports (openchamber-routes.js)
|
|
- `registerOpenChamberRoutes(app, dependencies)`: registers OpenChamber endpoints:
|
|
- `GET /api/openchamber/update-check`
|
|
- `POST /api/openchamber/update-install`
|
|
- `GET /api/openchamber/models-metadata`
|
|
- `GET /api/zen/models`
|
|
|
|
## Public exports (pwa-manifest-routes.js)
|
|
- `registerPwaManifestRoute(app, dependencies)`: registers PWA manifest endpoint with dynamic app-name resolution and recent-session shortcuts:
|
|
- `GET /manifest.webmanifest`
|
|
|
|
## Public exports (project-icon-routes.js)
|
|
- `registerProjectIconRoutes(app, dependencies)`: registers project icon routes and owns icon storage/discovery flow:
|
|
- `GET /api/projects/:projectId/icon`
|
|
- `PUT /api/projects/:projectId/icon`
|
|
- `DELETE /api/projects/:projectId/icon`
|
|
- `POST /api/projects/:projectId/icon/discover`
|
|
|
|
## Public exports (skill-routes.js)
|
|
- `registerSkillRoutes(app, dependencies)`: registers skills-related routes:
|
|
- Skills config CRUD and metadata under `/api/config/skills*`
|
|
- Skills catalog listing/source pagination, scan, and install routes
|
|
- Supporting skill file read/write/delete routes
|
|
|
|
## Public exports (proxy.js)
|
|
- `registerOpenCodeProxy(app, dependencies)`: registers OpenCode proxy routes and middleware.
|
|
- Owns:
|
|
- SSE forwarders: `GET /api/global/event`, `GET /api/event`
|
|
- Session message forwarder: `POST /api/session/:sessionId/message`
|
|
- Generic `/api/*` forwarding with hop-by-hop header filtering
|
|
- Windows `/session` merge fallback path behavior
|
|
- OpenCode readiness gate for proxied `/api` requests
|
|
|
|
## Public exports (watcher.js)
|
|
- `createOpenCodeWatcherRuntime(dependencies)`: creates global event watcher runtime.
|
|
- Returned API:
|
|
- `start()`
|
|
- `stop()`
|
|
|
|
## Storage and configuration
|
|
- Provider auth: `~/.local/share/opencode/auth.json`.
|
|
- User config: `~/.config/opencode/opencode.json`.
|
|
- Project config: `<workingDirectory>/.opencode/opencode.json` or `opencode.json`.
|
|
- Custom config: `OPENCODE_CONFIG` env var path.
|
|
- Rate limit config: `OPENCHAMBER_RATE_LIMIT_MAX_ATTEMPTS`, `OPENCHAMBER_RATE_LIMIT_NO_IP_MAX_ATTEMPTS` env vars.
|
|
|
|
## Notes for contributors
|
|
- This module serves as foundation for OpenCode-related server utilities.
|
|
- Route ownership moved to module-level `routes.js`; `index.js` wires dependencies only.
|
|
- All file writes include automatic backup before modification.
|
|
- Config merging follows priority: custom > project > user.
|
|
- UI auth uses scrypt for password hashing with constant-time comparison.
|
|
- Tunnel auth treats `host.docker.internal` as local-only when the socket remote IP is private/loopback.
|