docs: document session helpers

src/sessions/classify-session-kind.ts

@@ -1,3 +1,4 @@
+// Session kind helpers classify cron, interactive, and channel-backed sessions.
 import { isCronSessionKey } from "./session-key-utils.js";
 
 export type SessionKind = "cron" | "direct" | "group" | "global" | "spawn-child" | "unknown";

src/sessions/input-provenance.test.ts

@@ -1,3 +1,4 @@
+// Input provenance tests cover source metadata attached to session inputs.
 import { describe, expect, it } from "vitest";
 import {
   annotateInterSessionPromptText,

src/sessions/input-provenance.ts

@@ -1,3 +1,4 @@
+// Input provenance helpers normalize source metadata for session messages.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { AgentMessage } from "../agents/runtime/index.js";
 

src/sessions/level-overrides.ts

@@ -1,3 +1,4 @@
+// Session level override helpers normalize per-session logging and behavior levels.
 import {
   normalizeTraceLevel,
   normalizeVerboseLevel,

src/sessions/model-overrides.test.ts

@@ -1,3 +1,4 @@
+// Session model override tests cover model override parsing and validation.
 import { describe, expect, it } from "vitest";
 import type { SessionEntry } from "../config/sessions.js";
 import {

src/sessions/model-overrides.ts

@@ -1,3 +1,4 @@
+// Session model override helpers normalize per-session provider model choices.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { SessionEntry } from "../config/sessions.js";
 

src/sessions/send-policy.test.ts

@@ -1,3 +1,4 @@
+// Session send policy tests cover message send eligibility decisions.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import type { SessionEntry } from "../config/sessions.js";

src/sessions/send-policy.ts

@@ -1,3 +1,4 @@
+// Session send policy helpers decide when session output can be sent to targets.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

src/sessions/session-chat-type-shared.ts

@@ -1,3 +1,4 @@
+// Shared session chat type helpers expose cross-module chat type classification.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { parseAgentSessionKey } from "./session-key-utils.js";
 

src/sessions/session-chat-type.ts

@@ -1,3 +1,4 @@
+// Session chat type helpers classify chat surfaces from session metadata.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { getBootstrapChannelPlugin } from "../channels/plugins/bootstrap-registry.js";
 import {

src/sessions/session-id-resolution.test.ts

@@ -1,3 +1,4 @@
+// Session id resolution tests cover resolving aliases and explicit ids.
 import { describe, expect, it } from "vitest";
 import type { SessionEntry } from "../config/sessions/types.js";
 import {

src/sessions/session-id-resolution.ts

@@ -1,3 +1,4 @@
+// Session id resolution helpers resolve user-provided session references.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import type { SessionEntry } from "../config/sessions.js";
 import { toAgentRequestSessionKey } from "../routing/session-key.js";

src/sessions/session-id.test.ts

@@ -1,3 +1,4 @@
+// Session id tests cover session id parsing and generation helpers.
 import { describe, expect, it } from "vitest";
 import { SESSION_ID_RE, looksLikeSessionId } from "./session-id.js";
 

src/sessions/session-key-case-preservation.test.ts

@@ -1,3 +1,4 @@
+// Session key case tests cover preserving meaningful case in session keys.
 import { describe, expect, it } from "vitest";
 import { resolveSessionStoreEntry } from "../config/sessions/store-entry.js";
 import type { SessionEntry } from "../config/sessions/types.js";

src/sessions/session-key-utils.ts

@@ -1,3 +1,4 @@
+// Session key utilities normalize and classify persisted session keys.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,

src/sessions/session-lifecycle-events.test.ts

@@ -1,3 +1,4 @@
+// Session lifecycle event tests cover lifecycle event ordering and serialization.
 import { describe, expect, it } from "vitest";
 import { emitSessionLifecycleEvent, onSessionLifecycleEvent } from "./session-lifecycle-events.js";
 

src/sessions/transcript-events.test.ts

@@ -1,3 +1,4 @@
+// Transcript event tests cover transcript event parsing and compaction.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { emitSessionTranscriptUpdate, onSessionTranscriptUpdate } from "./transcript-events.js";
 

src/sessions/transcript-events.ts

@@ -1,3 +1,4 @@
+// Transcript event helpers serialize and trim session transcript events.
 import { asPositiveSafeInteger } from "@openclaw/normalization-core/number-coercion";
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 

src/sessions/user-turn-transcript.test.ts

@@ -1,3 +1,4 @@
+// User turn transcript tests cover transcript extraction for user turns.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/sessions/user-turn-transcript.ts

@@ -1,3 +1,4 @@
+// User turn transcript helpers extract user-turn text from session transcripts.
 import path from "node:path";
 import { mimeTypeFromFilePath } from "@openclaw/media-core/mime";
 import type { AgentMessage } from "../agents/runtime/index.js";