docs: document agent workspace helpers

src/agents/context-cache.ts

@@ -1,5 +1,7 @@
+/** Process-local model context window cache keyed by model id. */
 export const MODEL_CONTEXT_TOKEN_CACHE = new Map<string, number>();
 
+/** Looks up cached context-token count for a model id. */
 export function lookupCachedContextTokens(modelId?: string): number | undefined {
   if (!modelId) {
     return undefined;

src/agents/live-target-matcher.ts

@@ -63,6 +63,7 @@ function parseModelTarget(raw: string): ModelTarget | null {
   };
 }
 
+/** Creates provider/model predicates for live test target filters. */
 export function createLiveTargetMatcher(params: {
   providerFilter: Set<string> | null;
   modelFilter: Set<string> | null;

src/agents/openclaw-tools.nodes-workspace-guard.ts

@@ -2,6 +2,7 @@ import { wrapToolWorkspaceRootGuardWithOptions } from "./agent-tools.read.js";
 import type { ToolFsPolicy } from "./tool-fs-policy.js";
 import type { AnyAgentTool } from "./tools/common.js";
 
+/** Wraps the nodes tool with a workspace-only output-path guard when policy requires it. */
 export function applyNodesToolWorkspaceGuard(
   nodesToolBase: AnyAgentTool,
   options: {

src/agents/provider-api-families.ts

@@ -5,6 +5,7 @@ const GPT_PARALLEL_TOOL_CALLS_APIS = new Set([
   "azure-openai-responses",
 ]);
 
+/** True when a provider API accepts GPT parallel-tool-call payload settings. */
 export function supportsGptParallelToolCallsPayload(api: unknown): boolean {
   return typeof api === "string" && GPT_PARALLEL_TOOL_CALLS_APIS.has(api);
 }

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

@@ -13,6 +13,7 @@ type PendingToolCallState = {
   shouldFlushBeforeNewToolCalls: (toolCallCount: number) => boolean;
 };
 
+/** Tracks pending tool calls so sanitized transcript repair can flush in order. */
 export function createPendingToolCallState(): PendingToolCallState {
   const pending = new Map<string, string | undefined>();
 

src/agents/workspace-dir.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { resolveUserPath } from "../utils.js";
 
+/** Normalizes a workspace directory and rejects filesystem roots. */
 export function normalizeWorkspaceDir(workspaceDir?: string): string | null {
   const trimmed = workspaceDir?.trim();
   if (!trimmed) {
@@ -15,6 +16,7 @@ export function normalizeWorkspaceDir(workspaceDir?: string): string | null {
   return resolved;
 }
 
+/** Resolves the effective workspace root, falling back to cwd. */
 export function resolveWorkspaceRoot(workspaceDir?: string): string {
   return normalizeWorkspaceDir(workspaceDir) ?? process.cwd();
 }

src/agents/workspace-run.ts

@@ -67,10 +67,12 @@ function resolveRunAgentId(params: {
   };
 }
 
+/** Redacts a run/session identifier for logs and prompts. */
 export function redactRunIdentifier(value: string | undefined): string {
   return redactIdentifier(value, { len: 12 });
 }
 
+/** Resolves the workspace directory used for an agent run. */
 export function resolveRunWorkspaceDir(params: {
   workspaceDir: unknown;
   sessionKey?: string;