From 7a2aa689605ebca9e1f95dc788bb73bdb44bc62e Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Thu, 4 Jun 2026 08:32:30 -0400 Subject: [PATCH] docs: document codex app-server helpers --- .../codex/src/app-server/image-payload-sanitizer.ts | 7 +++++++ .../codex/src/app-server/local-runtime-attribution.ts | 6 ++++++ extensions/codex/src/app-server/models.ts | 10 ++++++++++ .../codex/src/app-server/native-execution-policy.ts | 7 +++++++ 4 files changed, 30 insertions(+) diff --git a/extensions/codex/src/app-server/image-payload-sanitizer.ts b/extensions/codex/src/app-server/image-payload-sanitizer.ts index 04733889f5d..e7b00c62ec6 100644 --- a/extensions/codex/src/app-server/image-payload-sanitizer.ts +++ b/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(value: T, label: string): T { if (Array.isArray(value)) { return value.map((entry) => sanitizeCodexHistoryImagePayloads(entry, label)) as T; diff --git a/extensions/codex/src/app-server/local-runtime-attribution.ts b/extensions/codex/src/app-server/local-runtime-attribution.ts index 6b9c5d89392..75540aced10 100644 --- a/extensions/codex/src/app-server/local-runtime-attribution.ts +++ b/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 { diff --git a/extensions/codex/src/app-server/models.ts b/extensions/codex/src/app-server/models.ts index 2836b4c740c..47ec8109c60 100644 --- a/extensions/codex/src/app-server/models.ts +++ b/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 { @@ -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 { @@ -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) { diff --git a/extensions/codex/src/app-server/native-execution-policy.ts b/extensions/codex/src/app-server/native-execution-policy.ts index 577bfaeed17..af9b909313d 100644 --- a/extensions/codex/src/app-server/native-execution-policy.ts +++ b/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;