From bd94eda53a967ca116ddbdcf29258f20df9101d5 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 08:48:00 -0400
Subject: [PATCH] docs: document codex trajectory progress helpers

---
 .../src/app-server/tool-progress-normalization.ts   | 10 ++++++++++
 extensions/codex/src/app-server/trajectory.ts       | 13 +++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/extensions/codex/src/app-server/tool-progress-normalization.ts b/extensions/codex/src/app-server/tool-progress-normalization.ts
index 6ef648a0125e..e5b91105f75c 100644
--- a/extensions/codex/src/app-server/tool-progress-normalization.ts
+++ b/extensions/codex/src/app-server/tool-progress-normalization.ts
@@ -1,3 +1,7 @@
+/**
+ * Normalizes and sanitizes Codex dynamic-tool progress payloads before they are
+ * emitted into OpenClaw events or logs.
+ */
 import {
   inferToolMetaFromArgs,
   type EmbeddedRunAttemptParams,
@@ -11,12 +15,14 @@ import {
   type JsonValue,
 } from "./protocol.js";
 
+/** Maps OpenClaw tool-progress config to the mode used by Codex progress metadata. */
 export function resolveCodexToolProgressDetailMode(
   value: EmbeddedRunAttemptParams["toolProgressDetail"],
 ): ToolProgressDetailMode {
   return value === "raw" ? "raw" : "explain";
 }
 
+/** Recursively redacts sensitive strings and handles circular values in event payloads. */
 export function sanitizeCodexAgentEventValue(
   value: unknown,
   seen = new WeakSet<object>(),
@@ -48,12 +54,14 @@ export function sanitizeCodexAgentEventValue(
   return value;
 }
 
+/** Sanitizes a record-shaped Codex agent event payload. */
 export function sanitizeCodexAgentEventRecord(
   value: Record<string, unknown>,
 ): Record<string, unknown> {
   return sanitizeCodexAgentEventValue(value) as Record<string, unknown>;
 }
 
+/** Sanitizes dynamic-tool arguments before diagnostic/event emission. */
 export function sanitizeCodexToolArguments(
   value: JsonValue | undefined,
 ): Record<string, unknown> | undefined {
@@ -63,12 +71,14 @@ export function sanitizeCodexToolArguments(
   return sanitizeCodexAgentEventRecord(value);
 }
 
+/** Sanitizes a Codex dynamic-tool response before diagnostic/event emission. */
 export function sanitizeCodexToolResponse(
   response: CodexDynamicToolCallResponse,
 ): Record<string, unknown> {
   return sanitizeCodexAgentEventRecord(response as unknown as Record<string, unknown>);
 }
 
+/** Infers compact human-readable tool metadata from Codex dynamic-tool arguments. */
 export function inferCodexDynamicToolMeta(
   call: Pick<CodexDynamicToolCallParams, "tool" | "arguments">,
   detailMode: ToolProgressDetailMode,
diff --git a/extensions/codex/src/app-server/trajectory.ts b/extensions/codex/src/app-server/trajectory.ts
index 9709b0db37fd..db450828f5f5 100644
--- a/extensions/codex/src/app-server/trajectory.ts
+++ b/extensions/codex/src/app-server/trajectory.ts
@@ -1,3 +1,7 @@
+/**
+ * Records optional Codex runtime trajectory sidecars with bounded, redacted
+ * context and completion events.
+ */
 import nodeFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -12,6 +16,7 @@ import {
 } from "openclaw/plugin-sdk/security-runtime";
 import { resolveCodexLocalRuntimeAttribution } from "./local-runtime-attribution.js";
 
+/** Runtime trajectory recorder used by Codex run attempts and event projectors. */
 export type CodexTrajectoryRecorder = {
   filePath: string;
   recordEvent: (type: string, data?: Record<string, unknown>) => void;
@@ -41,12 +46,14 @@ type CodexTrajectoryOpenFlagConstants = Pick<
 > &
   Partial<Pick<typeof nodeFs.constants, "O_NOFOLLOW">>;
 
+/** Resolves secure append flags for trajectory runtime files. */
 export function resolveCodexTrajectoryAppendFlags(
   constants: CodexTrajectoryOpenFlagConstants = nodeFs.constants,
 ): number {
   return resolveRegularFileAppendFlags(constants);
 }
 
+/** Resolves secure create/truncate flags for trajectory pointer files. */
 export function resolveCodexTrajectoryPointerFlags(
   constants: CodexTrajectoryOpenFlagConstants = nodeFs.constants,
 ): number {
@@ -140,6 +147,7 @@ function writeTrajectoryPointerBestEffort(params: {
   }
 }
 
+/** Creates a trajectory recorder when trajectory capture is enabled for the environment. */
 export function createCodexTrajectoryRecorder(
   params: CodexTrajectoryInit,
 ): CodexTrajectoryRecorder | null {
@@ -202,6 +210,7 @@ export function createCodexTrajectoryRecorder(
   };
 }
 
+/** Records compiled prompt/tool context at the start of a Codex runtime attempt. */
 export function recordCodexTrajectoryContext(
   recorder: CodexTrajectoryRecorder | null,
   params: CodexTrajectoryInit,
@@ -217,6 +226,7 @@ export function recordCodexTrajectoryContext(
   });
 }
 
+/** Records final Codex model completion metadata and assistant snapshots. */
 export function recordCodexTrajectoryCompletion(
   recorder: CodexTrajectoryRecorder | null,
   params: {
@@ -311,6 +321,8 @@ function toTrajectoryToolDefinitions(
 }
 
 function sanitizeValue(value: unknown, depth = 0, key = ""): unknown {
+  // Trajectory files may be inspected outside the live process, so redact
+  // credentials and private payloads before queueing the line for disk writes.
   if (value == null || typeof value === "boolean" || typeof value === "number") {
     return value;
   }
@@ -350,6 +362,7 @@ function redactSensitiveString(value: string): string {
     .replace(COOKIE_PAIR_RE, "$1=<redacted>");
 }
 
+/** Converts arbitrary prompt errors into trajectory-safe text. */
 export function normalizeCodexTrajectoryError(value: unknown): string | null {
   if (!value) {
     return null;