docs: document cli runner history helpers

steipete · steipete · commit 087fcf40858b · 2026-06-04T09:08:46.000-04:00
diff --git a/src/agents/cli-runner.ts b/src/agents/cli-runner.ts
@@ -1,3 +1,6 @@
+/**
+ * Top-level CLI-backed agent runner orchestration.
+ */
 import type { ReplyPayload } from "../auto-reply/reply-payload.js";
 import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";
 import { formatErrorMessage } from "../infra/errors.js";
@@ -44,10 +47,12 @@ const cliRunnerDeps = {
   },
 };
 
+/** Overrides top-level CLI runner dependencies for tests. */
 export function setCliRunnerTestDeps(overrides: Partial<typeof cliRunnerDeps>): void {
   Object.assign(cliRunnerDeps, overrides);
 }
 
+/** Restores default top-level CLI runner dependencies after tests. */
 export function restoreCliRunnerTestDeps(): void {
   cliRunnerDeps.claudeCliSessionTranscriptHasContent = claudeCliSessionTranscriptHasContentImpl;
   cliRunnerDeps.delay = async (delayMs: number) => {
@@ -80,6 +85,7 @@ function shouldRetryFreshCliSessionAfterFailover(params: {
   }
 }
 
+/** Checks whether a Claude CLI session binding has reached its transcript file. */
 export async function isCliBindingFlushed(
   sessionId: string | undefined,
   provider: string | undefined,
@@ -281,6 +287,7 @@ async function finalizeCliContextEngineTurn(params: {
   }
 }
 
+/** Prepares and runs one CLI-backed agent turn. */
 export async function runCliAgent(params: RunCliAgentParams): Promise<EmbeddedAgentRunResult> {
   // Cron gate must fire before prepareCliRunContext — that call allocates
   // backend resources released only by runPreparedCliAgent's try…finally.
@@ -351,6 +358,7 @@ export async function runCliAgent(params: RunCliAgentParams): Promise<EmbeddedAg
   }
 }
 
+/** Runs an already-prepared CLI agent context through hooks and execution. */
 export async function runPreparedCliAgent(
   context: PreparedCliRunContext,
 ): Promise<EmbeddedAgentRunResult> {
@@ -850,11 +858,13 @@ export async function runPreparedCliAgent(
   }
 }
 
+/** Legacy Claude-specific wrapper params for the generic CLI runner. */
 export type RunClaudeCliAgentParams = Omit<RunCliAgentParams, "provider" | "cliSessionId"> & {
   provider?: string;
   claudeSessionId?: string;
 };
 
+/** Converts legacy Claude CLI wrapper params into generic CLI runner params. */
 export function buildRunClaudeCliAgentParams(params: RunClaudeCliAgentParams): RunCliAgentParams {
   return {
     sessionId: params.sessionId,
@@ -892,6 +902,7 @@ export function buildRunClaudeCliAgentParams(params: RunClaudeCliAgentParams): R
   };
 }
 
+/** Runs the legacy Claude CLI wrapper through the generic CLI runner. */
 export async function runClaudeCliAgent(
   params: RunClaudeCliAgentParams,
 ): Promise<EmbeddedAgentRunResult> {
diff --git a/src/agents/cli-runner/session-history.ts b/src/agents/cli-runner/session-history.ts
@@ -1,3 +1,7 @@
+/**
+ * Loads and renders persisted session history for CLI session reseeding and
+ * context-engine synchronization.
+ */
 import fsp from "node:fs/promises";
 import path from "node:path";
 import {
@@ -14,9 +18,13 @@ import {
 import type { AgentMessage } from "../runtime/index.js";
 import { migrateSessionEntries, parseSessionEntries } from "../sessions/session-manager.js";
 
+/** Maximum transcript size read for CLI session history. */
 export const MAX_CLI_SESSION_HISTORY_FILE_BYTES = 5 * 1024 * 1024;
+/** Maximum transcript messages exposed to CLI hook history. */
 export const MAX_CLI_SESSION_HISTORY_MESSAGES = MAX_AGENT_HOOK_HISTORY_MESSAGES;
+/** Minimum reseed-history prompt budget for fresh CLI sessions. */
 export const MAX_CLI_SESSION_RESEED_HISTORY_CHARS = 12 * 1024;
+/** Maximum automatic reseed-history prompt budget derived from context size. */
 export const MAX_AUTO_CLI_SESSION_RESEED_HISTORY_CHARS = 256 * 1024;
 const CLI_SESSION_RESEED_HISTORY_CONTEXT_SHARE = 0.08;
 const CHARS_PER_TOKEN_ESTIMATE = 4;
@@ -60,6 +68,7 @@ const RAW_TRANSCRIPT_RESEED_ALLOWED_REASONS = new Set<RawTranscriptReseedReason>
   "session-expired",
 ]);
 
+/** Resolves how much prior transcript text may reseed a fresh CLI session. */
 export function resolveAutoCliSessionReseedHistoryChars(contextWindowTokens: number): number {
   if (!Number.isFinite(contextWindowTokens) || contextWindowTokens <= 0) {
     return MAX_CLI_SESSION_RESEED_HISTORY_CHARS;
@@ -157,6 +166,7 @@ function renderHistoryMessage(message: unknown): string | undefined {
   return text ? `${role}: ${text}` : undefined;
 }
 
+/** Builds a reseed prompt that carries prior OpenClaw transcript context. */
 export function buildCliSessionHistoryPrompt(params: {
   messages: unknown[];
   prompt: string;
@@ -325,6 +335,7 @@ async function loadCliSessionEntries(params: {
   }
 }
 
+/** Checks whether a safe, bounded transcript file exists for a CLI session. */
 export async function hasCliSessionTranscript(params: {
   sessionId: string;
   sessionFile: string;
@@ -354,6 +365,7 @@ export async function hasCliSessionTranscript(params: {
   }
 }
 
+/** Loads transcript messages for CLI lifecycle hook context. */
 export async function loadCliSessionHistoryMessages(params: {
   sessionId: string;
   sessionFile: string;
@@ -368,6 +380,7 @@ export async function loadCliSessionHistoryMessages(params: {
   return limitAgentHookHistoryMessages(history, MAX_CLI_SESSION_HISTORY_MESSAGES);
 }
 
+/** Loads transcript messages formatted for context-engine updates. */
 export async function loadCliSessionContextEngineMessages(params: {
   sessionId: string;
   sessionFile: string;
@@ -411,6 +424,7 @@ export async function loadCliSessionContextEngineMessages(params: {
   ];
 }
 
+/** Loads compacted/raw transcript messages eligible for CLI session reseeding. */
 export async function loadCliSessionReseedMessages(params: {
   sessionId: string;
   sessionFile: string;
diff --git a/src/agents/cli-runner/toml-inline.ts b/src/agents/cli-runner/toml-inline.ts
@@ -1,6 +1,8 @@
+/**
+ * Minimal TOML inline serializer for CLI config overrides.
+ */
 import { isRecord } from "@openclaw/normalization-core/record-coerce";
 
-// Minimal TOML inline serializer for CLI config overrides.
 function escapeTomlString(value: string): string {
   return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');
 }

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,6 @@`
	`1`	`+/**`
	`2`	`+ * Top-level CLI-backed agent runner orchestration.`
	`3`	`+ */`
`1`	`4`	`import type { ReplyPayload } from "../auto-reply/reply-payload.js";`
`2`	`5`	`import { SILENT_REPLY_TOKEN } from "../auto-reply/tokens.js";`
`3`	`6`	`import { formatErrorMessage } from "../infra/errors.js";`
`@@ -44,10 +47,12 @@ const cliRunnerDeps = {`
`44`	`47`	`},`
`45`	`48`	`};`
`46`	`49`
	`50`	`+/** Overrides top-level CLI runner dependencies for tests. */`
`47`	`51`	`export function setCliRunnerTestDeps(overrides: Partial<typeof cliRunnerDeps>): void {`
`48`	`52`	`Object.assign(cliRunnerDeps, overrides);`
`49`	`53`	`}`
`50`	`54`
	`55`	`+/** Restores default top-level CLI runner dependencies after tests. */`
`51`	`56`	`export function restoreCliRunnerTestDeps(): void {`
`52`	`57`	`cliRunnerDeps.claudeCliSessionTranscriptHasContent = claudeCliSessionTranscriptHasContentImpl;`
`53`	`58`	`cliRunnerDeps.delay = async (delayMs: number) => {`
`@@ -80,6 +85,7 @@ function shouldRetryFreshCliSessionAfterFailover(params: {`
`80`	`85`	`}`
`81`	`86`	`}`
`82`	`87`
	`88`	`+/** Checks whether a Claude CLI session binding has reached its transcript file. */`
`83`	`89`	`export async function isCliBindingFlushed(`
`84`	`90`	`sessionId: string \| undefined,`
`85`	`91`	`provider: string \| undefined,`
`@@ -281,6 +287,7 @@ async function finalizeCliContextEngineTurn(params: {`
`281`	`287`	`}`
`282`	`288`	`}`
`283`	`289`
	`290`	`+/** Prepares and runs one CLI-backed agent turn. */`
`284`	`291`	`export async function runCliAgent(params: RunCliAgentParams): Promise<EmbeddedAgentRunResult> {`
`285`	`292`	`// Cron gate must fire before prepareCliRunContext — that call allocates`
`286`	`293`	`// backend resources released only by runPreparedCliAgent's try…finally.`
`@@ -351,6 +358,7 @@ export async function runCliAgent(params: RunCliAgentParams): Promise<EmbeddedAg`
`351`	`358`	`}`
`352`	`359`	`}`
`353`	`360`
	`361`	`+/** Runs an already-prepared CLI agent context through hooks and execution. */`
`354`	`362`	`export async function runPreparedCliAgent(`
`355`	`363`	`context: PreparedCliRunContext,`
`356`	`364`	`): Promise<EmbeddedAgentRunResult> {`
`@@ -850,11 +858,13 @@ export async function runPreparedCliAgent(`
`850`	`858`	`}`
`851`	`859`	`}`
`852`	`860`
	`861`	`+/** Legacy Claude-specific wrapper params for the generic CLI runner. */`
`853`	`862`	`export type RunClaudeCliAgentParams = Omit<RunCliAgentParams, "provider" \| "cliSessionId"> & {`
`854`	`863`	`provider?: string;`
`855`	`864`	`claudeSessionId?: string;`
`856`	`865`	`};`
`857`	`866`
	`867`	`+/** Converts legacy Claude CLI wrapper params into generic CLI runner params. */`
`858`	`868`	`export function buildRunClaudeCliAgentParams(params: RunClaudeCliAgentParams): RunCliAgentParams {`
`859`	`869`	`return {`
`860`	`870`	`sessionId: params.sessionId,`
`@@ -892,6 +902,7 @@ export function buildRunClaudeCliAgentParams(params: RunClaudeCliAgentParams): R`
`892`	`902`	`};`
`893`	`903`	`}`
`894`	`904`
	`905`	`+/** Runs the legacy Claude CLI wrapper through the generic CLI runner. */`
`895`	`906`	`export async function runClaudeCliAgent(`
`896`	`907`	`params: RunClaudeCliAgentParams,`
`897`	`908`	`): Promise<EmbeddedAgentRunResult> {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,8 @@`
	`1`	`+/**`
	`2`	`+ * Minimal TOML inline serializer for CLI config overrides.`
	`3`	`+ */`
`1`	`4`	`import { isRecord } from "@openclaw/normalization-core/record-coerce";`
`2`	`5`
`3`		`-// Minimal TOML inline serializer for CLI config overrides.`
`4`	`6`	`function escapeTomlString(value: string): string {`
`5`	`7`	`return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"');`
`6`	`8`	`}`