docs: document codex app-server helpers

extensions/codex/src/app-server/image-payload-sanitizer.ts

@@ -1,3 +1,7 @@
+/**
+ * Sanitizes inline image payloads mirrored through Codex history so invalid
+ * base64 data becomes readable text instead of poisoning replayed transcripts.
+ */
 import {
   INLINE_IMAGE_DATA_URL_PREFIX,
   sanitizeInlineImageDataUrl as sanitizeSharedInlineImageDataUrl,
@@ -6,10 +10,12 @@ import { isRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 
 const IMAGE_OMITTED_TEXT = "omitted image payload: invalid inline image data";
 
+/** Validates and normalizes an inline image data URL for Codex history payloads. */
 export function sanitizeInlineImageDataUrl(imageUrl: string): string | undefined {
   return sanitizeSharedInlineImageDataUrl(imageUrl);
 }
 
+/** Builds the replacement text inserted when an inline image payload is invalid. */
 export function invalidInlineImageText(label: string): string {
   return `[${label}] ${IMAGE_OMITTED_TEXT}`;
 }
@@ -47,6 +53,7 @@ function sanitizeImageContentRecord(
   return undefined;
 }
 
+/** Recursively sanitizes all Codex history image shapes while preserving unknown structure. */
 export function sanitizeCodexHistoryImagePayloads<T>(value: T, label: string): T {
   if (Array.isArray(value)) {
     return value.map((entry) => sanitizeCodexHistoryImagePayloads(entry, label)) as T;

extensions/codex/src/app-server/local-runtime-attribution.ts

@@ -1,9 +1,14 @@
+/**
+ * Resolves the provider/api attribution used when a local Codex runtime is
+ * backed by OpenAI auth but should still report Codex Responses semantics.
+ */
 import type { EmbeddedRunAttemptParams } from "openclaw/plugin-sdk/agent-harness-runtime";
 
 const OPENAI_PROVIDER_ID = "openai";
 const OPENAI_RESPONSES_API = "openai-responses";
 const OPENAI_CODEX_RESPONSES_API = "openai-chatgpt-responses";
 
+/** Provider identity that downstream telemetry should attribute to the local Codex turn. */
 export type CodexLocalRuntimeAttribution = {
   provider: string;
   api?: string;
@@ -13,6 +18,7 @@ function normalizeRuntimeId(value: string | undefined): string {
   return value?.trim().toLowerCase() ?? "";
 }
 
+/** Maps local Codex runtime plans onto the provider/api pair exposed to event projection. */
 export function resolveCodexLocalRuntimeAttribution(
   params: EmbeddedRunAttemptParams,
 ): CodexLocalRuntimeAttribution {

extensions/codex/src/app-server/models.ts

@@ -1,3 +1,7 @@
+/**
+ * Lists and normalizes models exposed by the Codex app-server `model/list`
+ * endpoint, including pagination and shared-client lease handling.
+ */
 import { uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
 import type { resolveCodexAppServerAuthProfileIdForAgent } from "./auth-bridge.js";
 import type { CodexAppServerClient } from "./client.js";
@@ -5,6 +9,7 @@ import type { CodexAppServerStartOptions } from "./config.js";
 import { readCodexModelListResponse } from "./protocol-validators.js";
 import type { CodexModel, CodexReasoningEffortOption } from "./protocol.js";
 
+/** Normalized model metadata returned by the Codex app-server model listing helper. */
 export type CodexAppServerModel = {
   id: string;
   model: string;
@@ -17,12 +22,14 @@ export type CodexAppServerModel = {
   defaultReasoningEffort?: string;
 };
 
+/** One page of Codex app-server model metadata plus optional pagination state. */
 export type CodexAppServerModelListResult = {
   models: CodexAppServerModel[];
   nextCursor?: string;
   truncated?: boolean;
 };
 
+/** Options for querying Codex app-server models through a shared or isolated client. */
 export type CodexAppServerListModelsOptions = {
   limit?: number;
   cursor?: string;
@@ -35,6 +42,7 @@ export type CodexAppServerListModelsOptions = {
   sharedClient?: boolean;
 };
 
+/** Lists one Codex app-server model page using the configured auth/client options. */
 export async function listCodexAppServerModels(
   options: CodexAppServerListModelsOptions = {},
 ): Promise<CodexAppServerModelListResult> {
@@ -43,6 +51,7 @@ export async function listCodexAppServerModels(
   );
 }
 
+/** Walks Codex app-server model pages until exhaustion or the max-page guard. */
 export async function listAllCodexAppServerModels(
   options: CodexAppServerListModelsOptions & { maxPages?: number } = {},
 ): Promise<CodexAppServerModelListResult> {
@@ -121,6 +130,7 @@ async function requestModelListPage(
   return readModelListResult(response);
 }
 
+/** Parses a raw Codex app-server model/list response into OpenClaw's normalized shape. */
 export function readModelListResult(value: unknown): CodexAppServerModelListResult {
   const response = readCodexModelListResponse(value);
   if (!response) {

extensions/codex/src/app-server/native-execution-policy.ts

@@ -1,3 +1,7 @@
+/**
+ * Resolves whether Codex app-server native execution can own shell/file work,
+ * or whether OpenClaw must keep exec/process on a configured node host.
+ */
 import type { OpenClawConfig } from "openclaw/plugin-sdk/config-contracts";
 import { resolveSandboxRuntimeStatus } from "openclaw/plugin-sdk/sandbox";
 import { getSessionEntry, type SessionEntry } from "openclaw/plugin-sdk/session-store-runtime";
@@ -18,6 +22,7 @@ const INVALID_AGENT_ID_CHARS_PATTERN = /[^a-z0-9_-]+/g;
 const LEADING_DASH_PATTERN = /^-+/;
 const TRAILING_DASH_PATTERN = /-+$/;
 
+/** Effective execution-host policy for the Codex app-server native tool surface. */
 export type CodexNativeExecutionPolicy = {
   nativeToolSurfaceAllowed: boolean;
   requestedExecHost: ExecTarget;
@@ -26,6 +31,7 @@ export type CodexNativeExecutionPolicy = {
   blockReason?: string;
 };
 
+/** Resolves node/gateway/sandbox execution ownership from overrides, session, agent, and config. */
 export function resolveCodexNativeExecutionPolicy(params: {
   config?: OpenClawConfig;
   sessionEntry?: SessionEntry;
@@ -84,6 +90,7 @@ export function resolveCodexNativeExecutionPolicy(params: {
   };
 }
 
+/** Formats the user-facing explanation shown when native tools are blocked by exec host=node. */
 export function formatCodexNativeNodeExecBlock(params: {
   surface: string;
   reason?: string;