docs: document agent utility contracts

src/agents/live-target-matcher.ts

@@ -1,3 +1,8 @@
+/**
+ * Builds provider/model filters for live test lanes. Provider matches can
+ * follow plugin ownership aliases so scoped live runs include equivalent
+ * provider IDs.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import { normalizeGooglePreviewModelId } from "@openclaw/model-catalog-core/provider-model-id-normalize";
 import {

src/agents/model-ref-shared.ts

@@ -1,3 +1,8 @@
+/**
+ * Shared provider/model reference normalization for static catalogs,
+ * allowlists, and display paths. Manifest policies are optional so tests can
+ * isolate built-in normalization behavior.
+ */
 import { normalizeProviderId } from "@openclaw/model-catalog-core/provider-id";
 import {
   collectManifestModelIdNormalizationPolicies,
@@ -9,8 +14,6 @@ import {
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { normalizeProviderModelIdWithManifest } from "../plugins/manifest-model-id-normalization.js";
 
-// Shared provider/model ref normalization for static catalogs, allowlists, and
-// display paths. Manifest policies are optional so tests can isolate built-ins.
 type StaticModelRef = {
   provider: string;
   model: string;

src/agents/provider-api-families.ts

@@ -1,3 +1,7 @@
+/**
+ * Small API-family predicates used when constructing provider payloads. The
+ * sets here encode transport-level compatibility, not provider identity.
+ */
 const GPT_PARALLEL_TOOL_CALLS_APIS = new Set([
   "openai-completions",
   "openai-responses",

src/agents/pty-keys.ts

@@ -1,3 +1,8 @@
+/**
+ * Encodes terminal key, hex, literal, and paste inputs into PTY byte
+ * sequences. The encoder handles xterm modifiers and DECCKM application
+ * cursor mode.
+ */
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 import { escapeRegExp } from "../utils.js";
 
@@ -6,7 +11,9 @@ const CR = "\r";
 const TAB = "\t";
 const BACKSPACE = "\x7f";
 
+/** Bracketed-paste prefix emitted before pasted text. */
 export const BRACKETED_PASTE_START = `${ESC}[200~`;
+/** Bracketed-paste suffix emitted after pasted text. */
 export const BRACKETED_PASTE_END = `${ESC}[201~`;
 
 type Modifiers = {
@@ -113,6 +120,7 @@ type KeyEncodingResult = {
   warnings: string[];
 };
 
+/** True when request keys depend on normal vs application cursor-key mode. */
 export function hasCursorModeSensitiveKeys(request: KeyEncodingRequest): boolean {
   return (
     request.keys?.some((raw) => {
@@ -129,6 +137,7 @@ export function hasCursorModeSensitiveKeys(request: KeyEncodingRequest): boolean
   );
 }
 
+/** Encodes literal, hex, and named key tokens into one PTY input string. */
 export function encodeKeySequence(
   request: KeyEncodingRequest,
   cursorKeyMode?: "normal" | "application",
@@ -160,6 +169,7 @@ export function encodeKeySequence(
   return { data, warnings };
 }
 
+/** Wraps pasted text in bracketed-paste markers when enabled. */
 export function encodePaste(text: string, bracketed = true): string {
   if (!bracketed) {
     return text;

src/agents/session-tool-result-state.ts

@@ -1,3 +1,8 @@
+/**
+ * Tracks pending tool-call ids while repairing sanitized transcript messages.
+ * The state object decides when dropped or reordered messages need synthetic
+ * tool results flushed.
+ */
 type PendingToolCall = { id: string; name?: string };
 
 type PendingToolCallState = {

src/agents/workspace-dir.ts

@@ -1,3 +1,7 @@
+/**
+ * Workspace directory normalization helpers. They expand user paths, reject
+ * filesystem roots, and provide cwd fallback for runtime callers.
+ */
 import path from "node:path";
 import { resolveUserPath } from "../utils.js";