docs: document session services

steipete · steipete · commit f84460e62534 · 2026-06-04T10:01:18.000-04:00
diff --git a/src/agents/session-agent-binding.ts b/src/agents/session-agent-binding.ts
@@ -1,3 +1,8 @@
+/**
+ * Session-to-agent binding resolver.
+ *
+ * Derives the trusted active agent from explicit agent ids, agent session keys, or configured main-session aliases.
+ */
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalString,
diff --git a/src/agents/session-runtime-compat.ts b/src/agents/session-runtime-compat.ts
@@ -1,3 +1,8 @@
+/**
+ * Session runtime compatibility helpers.
+ *
+ * Resolves persisted runtime overrides without leaking provider-specific CLI runtime bindings across model routes.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { SessionEntry } from "../config/sessions.js";
 import { isDefaultAgentRuntimeId } from "./agent-runtime-id.js";
diff --git a/src/agents/session-suspension.ts b/src/agents/session-suspension.ts
@@ -1,3 +1,8 @@
+/**
+ * Session suspension and lane auto-resume helpers.
+ *
+ * Records quota/manual/circuit suspensions and temporarily lowers command-lane concurrency.
+ */
 import path from "node:path";
 import { resolveAgentMaxConcurrent, resolveSubagentMaxConcurrent } from "../config/agent-limits.js";
 import { resolveCronMaxConcurrentRuns } from "../config/cron-limits.js";
diff --git a/src/agents/session-tool-result-guard-wrapper.ts b/src/agents/session-tool-result-guard-wrapper.ts
@@ -1,3 +1,8 @@
+/**
+ * Session manager wrapper for tool-result transcript guards.
+ *
+ * Installs message-write hooks, input provenance handling, and pending tool-result flush behavior once per manager.
+ */
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { getGlobalHookRunner } from "../plugins/hook-runner-global.js";
 import {
diff --git a/src/agents/session-tool-result-guard.ts b/src/agents/session-tool-result-guard.ts
@@ -1,3 +1,8 @@
+/**
+ * Session transcript guard for tool-call/result consistency.
+ *
+ * Caps large tool results, repairs missing results, applies redaction, and emits transcript update events.
+ */
 import { resolveIntegerOption } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import {
diff --git a/src/agents/session-transcript-repair.ts b/src/agents/session-transcript-repair.ts
@@ -1,3 +1,8 @@
+/**
+ * Transcript repair helpers for tool-call replay.
+ *
+ * Normalizes raw tool-call blocks and synthesizes missing tool results without rewriting trusted local payloads.
+ */
 import {
   hasNonEmptyString as hasNonEmptyStringField,
   normalizeOptionalString,
diff --git a/src/agents/session-write-lock.ts b/src/agents/session-write-lock.ts
@@ -1,3 +1,8 @@
+/**
+ * Session write-lock implementation.
+ *
+ * Uses lock files with owner metadata, stale detection, signal cleanup, and watchdog checks to serialize writes.
+ */
 import "../infra/fs-safe-defaults.js";
 import type fsSync from "node:fs";
 import fs from "node:fs/promises";
diff --git a/src/agents/sessions/agent-session-runtime.ts b/src/agents/sessions/agent-session-runtime.ts
@@ -1,3 +1,8 @@
+/**
+ * Agent session runtime factory.
+ *
+ * Builds cwd-bound services, imports optional session history, and emits shutdown events for replaced sessions.
+ */
 import { copyFileSync, existsSync, mkdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import type {
diff --git a/src/agents/sessions/agent-session-services.ts b/src/agents/sessions/agent-session-services.ts
@@ -1,3 +1,8 @@
+/**
+ * Agent session service factory.
+ *
+ * Creates cwd-bound auth, settings, model registry, resource loader, and session instances for the CLI runtime.
+ */
 import { join } from "node:path";
 import type { Model } from "../../llm/types.js";
 import { getAgentDir } from "../config.js";
diff --git a/src/agents/sessions/auth-guidance.ts b/src/agents/sessions/auth-guidance.ts
@@ -1,12 +1,11 @@
-import { join } from "node:path";
-import { getDocsPath } from "../config.js";
-
 /**
  * Shared user-facing auth guidance for session/model selection failures.
  *
- * Messages include docs paths instead of provider-specific instructions so they
- * stay correct across OAuth/API-key providers.
+ * Uses docs paths instead of provider-specific instructions so guidance stays correct across OAuth/API-key providers.
  */
+import { join } from "node:path";
+import { getDocsPath } from "../config.js";
+
 const UNKNOWN_PROVIDER = "unknown";
 
 /** Returns the standard provider login help block. */
diff --git a/src/agents/sessions/compaction/branch-summarization.ts b/src/agents/sessions/compaction/branch-summarization.ts
@@ -1,3 +1,8 @@
+/**
+ * Branch-summary bridge from session managers to the shared agent-core summarizer.
+ *
+ * Keeps session-manager branch traversal local while delegating summary generation to agent-core.
+ */
 import type { Model } from "../../../llm/types.js";
 import {
   collectEntriesForBranchSummaryFromBranches,
@@ -10,9 +15,6 @@ import {
 } from "../../runtime/index.js";
 import type { SessionEntry, ReadonlySessionManager } from "../session-manager.js";
 
-/**
- * Branch-summary bridge from session managers to the shared agent-core summarizer.
- */
 export type { BranchPreparation, BranchSummaryDetails, FileOperations };
 export { prepareBranchEntries };
 
diff --git a/src/agents/sessions/compaction/compaction.ts b/src/agents/sessions/compaction/compaction.ts
@@ -1,3 +1,8 @@
+/**
+ * Session compaction compatibility bridge over the shared agent-core implementation.
+ *
+ * Local callers keep the historic throwing API while agent-core returns explicit Result objects.
+ */
 import type { StreamFn as CoreStreamFn } from "../../../../packages/llm-core/src/index.js";
 import type { Model } from "../../../llm/types.js";
 import {
@@ -24,11 +29,6 @@ import {
 import type { AgentMessage, StreamFn, ThinkingLevel } from "../../runtime/index.js";
 import type { SessionEntry } from "../session-manager.js";
 
-/**
- * Session compaction compatibility bridge over the shared agent-core implementation.
- *
- * Local callers keep the historic throwing API while agent-core returns explicit Result objects.
- */
 export {
   calculateContextTokens,
   DEFAULT_COMPACTION_SETTINGS,
diff --git a/src/agents/sessions/defaults.ts b/src/agents/sessions/defaults.ts
@@ -1,3 +1,8 @@
+/**
+ * Session defaults.
+ *
+ * Centralizes fallback thinking settings for sessions without model-specific overrides.
+ */
 import type { ThinkingLevel } from "../runtime/index.js";
 
 /** Default thinking level for sessions that do not specify a model-specific override. */
diff --git a/src/agents/sessions/diagnostics.ts b/src/agents/sessions/diagnostics.ts
@@ -1,3 +1,8 @@
+/**
+ * Session resource diagnostic types.
+ *
+ * Describes collisions and warnings discovered while loading extensions, skills, prompts, and themes.
+ */
 export interface ResourceCollision {
   resourceType: "extension" | "skill" | "prompt" | "theme";
   name: string; // skill name, command/tool/flag name, prompt name, theme name
diff --git a/src/agents/sessions/event-bus.ts b/src/agents/sessions/event-bus.ts
@@ -1,10 +1,10 @@
-import { EventEmitter } from "node:events";
-
 /**
  * Tiny event bus abstraction for session UI/runtime notifications.
  *
- * Handlers are isolated so one bad subscriber cannot break later listeners.
+ * Isolates handler failures so one bad subscriber cannot break later listeners.
  */
+import { EventEmitter } from "node:events";
+
 /** Minimal publish/subscribe interface used by session components. */
 export interface EventBus {
   emit(channel: string, data: unknown): void;
diff --git a/src/agents/sessions/footer-data-provider.ts b/src/agents/sessions/footer-data-provider.ts
@@ -1,3 +1,8 @@
+/**
+ * Footer data provider for session UI.
+ *
+ * Watches git metadata and exposes current branch/repository state without blocking rendering.
+ */
 import { type ExecFileException, execFile, spawnSync } from "node:child_process";
 import {
   existsSync,
diff --git a/src/agents/sessions/http-dispatcher.ts b/src/agents/sessions/http-dispatcher.ts
@@ -1,8 +1,10 @@
-import { parseStrictNonNegativeInteger } from "../../infra/parse-finite-number.js";
-
 /**
- * HTTP session dispatcher idle-timeout parsing shared by server and config surfaces.
+ * HTTP session dispatcher config helpers.
+ *
+ * Parses idle-timeout values shared by server and config surfaces.
  */
+import { parseStrictNonNegativeInteger } from "../../infra/parse-finite-number.js";
+
 export const DEFAULT_HTTP_IDLE_TIMEOUT_MS = 300_000;
 
 /** Parses idle timeout values, using `0` for the explicit disabled sentinel. */
diff --git a/src/agents/sessions/keybindings.ts b/src/agents/sessions/keybindings.ts
@@ -1,3 +1,8 @@
+/**
+ * Application keybinding definitions and user-config migration helpers.
+ *
+ * Wraps pi-tui keybindings with OpenClaw-specific actions and per-agent overrides.
+ */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import {
@@ -10,12 +15,6 @@ import {
 } from "@earendil-works/pi-tui";
 import { getAgentDir } from "../config.js";
 
-/**
- * Application keybinding definitions and user-config migration helpers.
- *
- * The exported manager wraps pi-tui keybindings with OpenClaw-specific actions
- * and loads optional per-agent keybindings.json overrides.
- */
 /** OpenClaw-specific key ids added to the shared pi-tui keybinding registry. */
 export interface AppKeybindings {
   "app.interrupt": true;
diff --git a/src/agents/sessions/package-manager.ts b/src/agents/sessions/package-manager.ts
@@ -1,3 +1,8 @@
+/**
+ * Session package/resource manager.
+ *
+ * Resolves extension, skill, prompt, and theme sources from npm, git, local paths, and project manifests.
+ */
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
diff --git a/src/agents/sessions/prompt-templates.ts b/src/agents/sessions/prompt-templates.ts
@@ -1,3 +1,8 @@
+/**
+ * Prompt template discovery and loading.
+ *
+ * Reads markdown prompt templates from user, project, and package sources with frontmatter metadata.
+ */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
diff --git a/src/agents/sessions/resource-loader.ts b/src/agents/sessions/resource-loader.ts
@@ -1,3 +1,8 @@
+/**
+ * Session resource loader.
+ *
+ * Loads extensions, skills, prompts, themes, AGENTS files, and system prompt fragments for a cwd.
+ */
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, sep } from "node:path";
diff --git a/src/agents/sessions/sdk.ts b/src/agents/sessions/sdk.ts
@@ -1,3 +1,8 @@
+/**
+ * Agent session SDK factory.
+ *
+ * Selects models, wires built-in/custom tools, loads resources, and creates AgentSession instances.
+ */
 import { join } from "node:path";
 import { clampThinkingLevel } from "../../llm/model-utils.js";
 import { streamSimple } from "../../llm/stream.js";
diff --git a/src/agents/sessions/session-cwd.ts b/src/agents/sessions/session-cwd.ts
@@ -1,10 +1,10 @@
-import { existsSync } from "node:fs";
-
 /**
- * Detects when a resumed session points at a working directory that no longer exists.
+ * Missing session cwd detection.
  *
- * Callers use this to decide whether to stop, prompt, or continue in the current process cwd.
+ * Helps resume flows decide whether to stop, prompt, or continue in the current process cwd.
  */
+import { existsSync } from "node:fs";
+
 export interface SessionCwdIssue {
   sessionFile?: string;
   sessionCwd: string;
diff --git a/src/agents/sessions/session-manager.ts b/src/agents/sessions/session-manager.ts
@@ -1,3 +1,8 @@
+/**
+ * JSONL-backed session tree manager.
+ *
+ * Reads, writes, forks, labels, and exports persisted session entries while preserving branch structure.
+ */
 import { randomUUID } from "node:crypto";
 import {
   closeSync,
diff --git a/src/agents/sessions/settings-manager.ts b/src/agents/sessions/settings-manager.ts
@@ -1,3 +1,8 @@
+/**
+ * Session settings manager.
+ *
+ * Loads and persists user/session defaults for models, transports, retry policy, UI, packages, and telemetry.
+ */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
diff --git a/src/agents/sessions/slash-commands.ts b/src/agents/sessions/slash-commands.ts
@@ -1,9 +1,11 @@
+/**
+ * Slash command metadata registry.
+ *
+ * Defines built-in command metadata and the source shape used by prompts, skills, and extensions.
+ */
 import { APP_NAME } from "../config.js";
 import type { SourceInfo } from "./source-info.js";
 
-/**
- * Slash command metadata surfaced by built-ins, prompt packs, skills, and extensions.
- */
 export type SlashCommandSource = "extension" | "prompt" | "skill";
 
 export interface SlashCommandInfo {
diff --git a/src/agents/sessions/source-info.ts b/src/agents/sessions/source-info.ts
@@ -1,8 +1,10 @@
-import type { PathMetadata } from "./package-manager.js";
-
 /**
- * Source metadata attached to prompts, skills, and extension-provided session assets.
+ * Source metadata helpers for session resources.
+ *
+ * Tracks where prompts, skills, and extension-provided assets came from for diagnostics and UI.
  */
+import type { PathMetadata } from "./package-manager.js";
+
 export type SourceScope = "user" | "project" | "temporary";
 export type SourceOrigin = "package" | "top-level";
 
diff --git a/src/agents/sessions/telemetry.ts b/src/agents/sessions/telemetry.ts
@@ -1,11 +1,10 @@
-import type { SettingsManager } from "./settings-manager.js";
-
 /**
- * Install telemetry switch shared by session startup and settings.
+ * Install telemetry switch.
  *
- * Environment overrides win over persisted settings so CI and packaged launchers
- * can force the telemetry posture without editing user config.
+ * Environment overrides win over persisted settings for CI and packaged launcher control.
  */
+import type { SettingsManager } from "./settings-manager.js";
+
 function isTruthyEnvFlag(value: string | undefined): boolean {
   if (!value) {
     return false;
