From 29e9625b18cd4c09db83d9a98acb2d2fafad43ed Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 08:37:41 -0400
Subject: [PATCH] docs: document codex sandbox exec fs http

---
 .../src/app-server/sandbox-exec-server/filesystem.ts  | 11 +++++++++++
 .../codex/src/app-server/sandbox-exec-server/http.ts  |  6 ++++++
 2 files changed, 17 insertions(+)

diff --git a/extensions/codex/src/app-server/sandbox-exec-server/filesystem.ts b/extensions/codex/src/app-server/sandbox-exec-server/filesystem.ts
index 8f2b2535ae59..e5e7f19cdc4c 100644
--- a/extensions/codex/src/app-server/sandbox-exec-server/filesystem.ts
+++ b/extensions/codex/src/app-server/sandbox-exec-server/filesystem.ts
@@ -1,3 +1,7 @@
+/**
+ * Implements filesystem JSON-RPC handlers for the Codex sandbox exec-server
+ * with OpenClaw sandbox policy checks before every bridge operation.
+ */
 import { posix as pathPosix } from "node:path";
 import type { SandboxFsStat } from "openclaw/plugin-sdk/sandbox";
 import type { JsonObject, JsonValue } from "../protocol.js";
@@ -22,6 +26,7 @@ import type { DirectoryEntry, OpenClawExecServer, ResolvedFsSandboxPolicy } from
 
 const CODEX_SANDBOX_EXEC_SERVER_MAX_READ_FILE_BYTES = 512 * 1024 * 1024;
 
+/** Reads a sandbox file as base64 after read-policy and size checks. */
 export async function readFile(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -45,6 +50,7 @@ export async function readFile(
   return { dataBase64: data.toString("base64") };
 }
 
+/** Writes base64 data to an existing sandbox directory after write-policy checks. */
 export async function writeFile(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -64,6 +70,7 @@ export async function writeFile(
   });
 }
 
+/** Creates a sandbox directory, respecting recursive and parent-directory semantics. */
 export async function createDirectory(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -84,6 +91,7 @@ export async function createDirectory(
   });
 }
 
+/** Returns normalized metadata for a sandbox path. */
 export async function getMetadata(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -101,6 +109,7 @@ export async function getMetadata(
   return metadataResponse(stat);
 }
 
+/** Lists sandbox directory entries visible under the resolved filesystem policy. */
 export async function readDirectory(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -148,6 +157,7 @@ async function listDirectoryEntries(
   });
 }
 
+/** Removes a sandbox path after rejecting writes outside policy or under read-only descendants. */
 export async function removePath(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
@@ -167,6 +177,7 @@ export async function removePath(
   });
 }
 
+/** Copies sandbox files or recursive directories while enforcing source and destination policy. */
 export async function copyPath(
   execServer: OpenClawExecServer,
   params: JsonValue | undefined,
diff --git a/extensions/codex/src/app-server/sandbox-exec-server/http.ts b/extensions/codex/src/app-server/sandbox-exec-server/http.ts
index fbd4cd0583fa..3efe643b21c5 100644
--- a/extensions/codex/src/app-server/sandbox-exec-server/http.ts
+++ b/extensions/codex/src/app-server/sandbox-exec-server/http.ts
@@ -1,3 +1,7 @@
+/**
+ * Implements sandboxed HTTP requests for Codex native tools by routing network
+ * access through the active OpenClaw sandbox backend.
+ */
 import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-runtime";
 import type { SandboxContext } from "openclaw/plugin-sdk/sandbox";
@@ -7,8 +11,10 @@ import { readHttpHeaders, requireNumber, requireObject, requireString } from "./
 import { requireBackend } from "./runtime.js";
 import type { HttpHeader, OpenClawExecServer } from "./types.js";
 
+/** Maximum JSON-line size accepted from the streaming HTTP helper process. */
 export const SANDBOX_HTTP_STREAM_LINE_MAX_CHARS = 256 * 1024;
 
+/** Handles one sandbox HTTP JSON-RPC request, optionally streaming response body deltas. */
 export async function httpRequest(
   execServer: OpenClawExecServer,
   socket: WebSocket,