docs: document runner model helpers

steipete · steipete · commit 6719528316c0 · 2026-06-04T09:30:31.000-04:00
diff --git a/src/agents/embedded-agent-runner/manual-compaction-boundary.ts b/src/agents/embedded-agent-runner/manual-compaction-boundary.ts
@@ -1,3 +1,6 @@
+/**
+ * Hardens manual compaction transcript boundaries after explicit `/compact`.
+ */
 import type { AgentMessage } from "../runtime/index.js";
 import type { SessionEntry } from "../sessions/index.js";
 import {
@@ -69,6 +72,7 @@ function hasMessagesToSummarizeBeforeKeptTail(params: {
     .some((entry) => entryCreatesCompactionInputMessage(entry));
 }
 
+/** Rewrite the latest manual compaction leaf so replay starts from its summary. */
 export async function hardenManualCompactionBoundary(params: {
   sessionFile: string;
   preserveRecentTail?: boolean;
diff --git a/src/agents/embedded-agent-runner/message-action-discovery-input.ts b/src/agents/embedded-agent-runner/message-action-discovery-input.ts
@@ -1,3 +1,6 @@
+/**
+ * Builds scoped message-action discovery inputs for embedded-agent tool setup.
+ */
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
 
 /**
@@ -6,6 +9,7 @@ import type { OpenClawConfig } from "../../config/types.openclaw.js";
  * Discovery expects absent optional fields as `undefined`; preserving nulls would create
  * different cache/input shapes for the same missing runtime fact.
  */
+/** Collect the current sender/channel hints used to discover message actions. */
 export function buildEmbeddedMessageActionDiscoveryInput(params: {
   cfg?: OpenClawConfig;
   channel: string;
diff --git a/src/agents/embedded-agent-runner/model-context-tokens.ts b/src/agents/embedded-agent-runner/model-context-tokens.ts
@@ -1,3 +1,6 @@
+/**
+ * Reads normalized context-token metadata from resolved model definitions.
+ */
 import type { Model } from "../../llm/types.js";
 
 /**
@@ -8,6 +11,7 @@ type AgentModelWithOptionalContextTokens = Model & {
 };
 
 /** Returns finite context-token metadata when a model discovery source provided it. */
+/** Prefer contextTokens, then contextWindow, when present on model metadata. */
 export function readAgentModelContextTokens(model: Model | null | undefined): number | undefined {
   const value = (model as AgentModelWithOptionalContextTokens | null | undefined)?.contextTokens;
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
diff --git a/src/agents/embedded-agent-runner/model-discovery-cache.ts b/src/agents/embedded-agent-runner/model-discovery-cache.ts
@@ -1,3 +1,6 @@
+/**
+ * Discovers cached model/provider state from configured agent stores.
+ */
 import { statSync } from "node:fs";
 import path from "node:path";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/embedded-agent-runner/model.inline-provider.ts b/src/agents/embedded-agent-runner/model.inline-provider.ts
@@ -1,3 +1,6 @@
+/**
+ * Converts inline provider model config into runtime model definitions.
+ */
 import { normalizeOptionalLowercaseString } from "@openclaw/normalization-core/string-coerce";
 import type { ModelDefinitionConfig, ModelProviderConfig } from "../../config/types.js";
 import { normalizeGoogleApiBaseUrl } from "../../infra/google-api-base-url.js";
diff --git a/src/agents/embedded-agent-runner/model.provider-normalization.ts b/src/agents/embedded-agent-runner/model.provider-normalization.ts
@@ -1,3 +1,6 @@
+/**
+ * Normalizes resolved provider/model ids on model records.
+ */
 import type { Model } from "../../llm/types.js";
 import { normalizeModelCompat } from "../../plugins/provider-model-compat.js";
 
diff --git a/src/agents/embedded-agent-runner/model.static-catalog.ts b/src/agents/embedded-agent-runner/model.static-catalog.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves bundled static catalog rows for embedded-agent model selection.
+ */
 import type { NormalizedModelCatalogRow } from "@openclaw/model-catalog-core/model-catalog-types";
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/embedded-agent-runner/model.ts b/src/agents/embedded-agent-runner/model.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves embedded-agent provider/model selections from config, registry, and catalogs.
+ */
 import { finiteSecondsToTimerSafeMilliseconds } from "@openclaw/normalization-core/number-coercion";
 import type { ModelCompatConfig, ModelMediaInputConfig } from "../../config/types.models.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/embedded-agent-runner/post-compaction-loop-guard.ts b/src/agents/embedded-agent-runner/post-compaction-loop-guard.ts
@@ -1,3 +1,6 @@
+/**
+ * Guards against repeated tool-loop compactions that never make progress.
+ */
 import type { ToolLoopPostCompactionGuardConfig } from "../../config/types.tools.js";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 
diff --git a/src/agents/embedded-agent-runner/prompt-cache-observability.ts b/src/agents/embedded-agent-runner/prompt-cache-observability.ts
@@ -1,3 +1,6 @@
+/**
+ * Tracks prompt-cache snapshot changes for observability diagnostics.
+ */
 import crypto from "node:crypto";
 import type { NormalizedUsage } from "../usage.js";
 
diff --git a/src/agents/embedded-agent-runner/prompt-cache-retention.ts b/src/agents/embedded-agent-runner/prompt-cache-retention.ts
@@ -1,3 +1,6 @@
+/**
+ * Resolves provider/model prompt-cache retention behavior.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { resolveAnthropicCacheRetentionFamily } from "../../llm/providers/stream-wrappers/anthropic-family-cache-semantics.js";
 
diff --git a/src/agents/embedded-agent-runner/replay-history.ts b/src/agents/embedded-agent-runner/replay-history.ts
@@ -1,3 +1,6 @@
+/**
+ * Sanitizes and validates replayed session history before model calls.
+ */
 import { stripInternalMetadataForDisplay } from "../../auto-reply/reply/display-text-sanitize.js";
 import { isSilentReplyPayloadText, SILENT_REPLY_TOKEN } from "../../auto-reply/tokens.js";
 import type { OpenClawConfig } from "../../config/types.openclaw.js";
diff --git a/src/agents/embedded-agent-runner/resource-loader.ts b/src/agents/embedded-agent-runner/resource-loader.ts
@@ -1,3 +1,6 @@
+/**
+ * Creates the resource loader used by embedded-agent sessions.
+ */
 import { DefaultResourceLoader } from "../sessions/index.js";
 
 /**
diff --git a/src/agents/embedded-agent-runner/result-fallback-classifier.ts b/src/agents/embedded-agent-runner/result-fallback-classifier.ts
@@ -1,3 +1,6 @@
+/**
+ * Classifies embedded-agent run results for model fallback decisions.
+ */
 import { isSilentReplyPayloadText } from "../../auto-reply/tokens.js";
 import { classifyFailoverReason } from "../embedded-agent-helpers/errors.js";
 import type { FailoverReason } from "../embedded-agent-helpers/types.js";
