docs: document apply patch helpers

steipete · steipete · commit f7ef52e66d97 · 2026-06-04T05:47:45.000-04:00
diff --git a/src/agents/api-key-rotation.test.ts b/src/agents/api-key-rotation.test.ts
@@ -1,3 +1,8 @@
+/**
+ * Tests provider API-key rotation behavior.
+ * Covers rate-limit key rotation, same-key transient retries, aborts, and
+ * thrown-object preservation.
+ */
 import { describe, expect, it, vi } from "vitest";
 import type { TransientProviderRetryParams } from "../provider-runtime/operation-retry.js";
 import { executeWithApiKeyRotation } from "./api-key-rotation.js";
diff --git a/src/agents/api-key-rotation.ts b/src/agents/api-key-rotation.ts
@@ -1,3 +1,8 @@
+/**
+ * Provider API-key rotation wrapper.
+ * Runs provider calls across configured keys on rate-limit failures and keeps
+ * same-key transient retries separate from key rotation.
+ */
 import { normalizeUniqueStringEntries } from "@openclaw/normalization-core/string-normalization";
 import { sleepWithAbort } from "../infra/backoff.js";
 import { formatErrorMessage } from "../infra/errors.js";
@@ -10,8 +15,6 @@ import {
 } from "../provider-runtime/operation-retry.js";
 import { collectProviderApiKeys, isApiKeyRateLimitError } from "./live-auth-keys.js";
 
-// API-key rotation wrapper for provider calls. It tries configured keys in order
-// on rate-limit-like failures and can also retry transient errors on the same key.
 type ApiKeyRetryParams = {
   apiKey: string;
   error: unknown;
diff --git a/src/agents/apply-patch-paths.test.ts b/src/agents/apply-patch-paths.test.ts
@@ -1,3 +1,8 @@
+/**
+ * Tests apply_patch destination path extraction.
+ * Ensures pre-execution policy checks see add/update/delete/move paths in
+ * host and sandbox forms without requiring full parser success.
+ */
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it } from "vitest";
diff --git a/src/agents/apply-patch-paths.ts b/src/agents/apply-patch-paths.ts
@@ -1,3 +1,8 @@
+/**
+ * Path extraction for the apply_patch envelope grammar.
+ * Used by pre-execution policy hooks that only need destination paths, not the
+ * full strict patch parser.
+ */
 import path from "node:path";
 import { resolveSandboxInputPath } from "./sandbox-paths.js";
 import type { SandboxFsBridge } from "./sandbox/fs-bridge.js";
diff --git a/src/agents/apply-patch-update.ts b/src/agents/apply-patch-update.ts
@@ -1,9 +1,11 @@
+/**
+ * Update-hunk application for the apply_patch parser.
+ * Locates expected old lines with tolerant matching, applies chunks in order,
+ * and returns normalized file contents with a trailing newline.
+ */
 import fs from "node:fs/promises";
 import { formatErrorMessage } from "../infra/errors.js";
 
-// Update-hunk application for the apply_patch parser. It locates expected old
-// lines with tolerant matching, applies chunks in order, and returns normalized
-// file contents with a trailing newline.
 type UpdateFileChunk = {
   changeContext?: string;
   oldLines: string[];
diff --git a/src/agents/apply-patch.test.ts b/src/agents/apply-patch.test.ts
@@ -1,3 +1,8 @@
+/**
+ * Tests apply_patch execution and path safety.
+ * Covers host/sandbox file operations, workspace guards, symlink races, and
+ * update hunk behavior.
+ */
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/agents/apply-patch.ts b/src/agents/apply-patch.ts
@@ -1,3 +1,8 @@
+/**
+ * Runtime apply_patch tool and parser.
+ * Parses OpenAI-style patch envelopes and applies add/update/delete/move hunks
+ * through guarded host or sandbox filesystem operations.
+ */
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -82,6 +87,7 @@ const applyPatchSchema = Type.Object({
   }),
 });
 
+/** Create the agent tool wrapper for applying patch-envelope input. */
 export function createApplyPatchTool(
   options: { cwd?: string; sandbox?: SandboxApplyPatchConfig; workspaceOnly?: boolean } = {},
 ): AgentTool<typeof applyPatchSchema, ApplyPatchToolDetails> {
@@ -122,6 +128,7 @@ export function createApplyPatchTool(
   };
 }
 
+/** Parse and apply a patch envelope to the configured filesystem target. */
 export async function applyPatch(
   input: string,
   options: ApplyPatchOptions,
