cx-viewer 1.0.3 → 1.0.4

package/README.md

@@ -7,8 +7,6 @@ Check out the fun part — here's what you can see on mobile:
 
 <img width="1700" height="790" alt="image" src="https://github.com/user-attachments/assets/da3e519f-ff66-4cd2-81d1-f4e131215f6c" />
 
-English | [简体中文](./docs/README.zh.md) | [繁體中文](./docs/README.zh-TW.md) | [한국어](./docs/README.ko.md) | [日本語](./docs/README.ja.md) | [Deutsch](./docs/README.de.md) | [Español](./docs/README.es.md) | [Français](./docs/README.fr.md) | [Italiano](./docs/README.it.md) | [Dansk](./docs/README.da.md) | [Polski](./docs/README.pl.md) | [Русский](./docs/README.ru.md) | [العربية](./docs/README.ar.md) | [Norsk](./docs/README.no.md) | [Português (Brasil)](./docs/README.pt-BR.md) | [ไทย](./docs/README.th.md) | [Türkçe](./docs/README.tr.md) | [Українська](./docs/README.uk.md)
-
 ## Usage
 
 ### Installation
@@ -22,7 +20,7 @@ npm install -g cx-viewer --registry=https://registry.npmjs.org
 `cxv` launches the Web Viewer and then forwards the real Codex CLI surface through unchanged. CXV only adds a few wrapper features of its own:
 
 - `cxv continue` is a convenience alias for `codex resume --last`
-- `cxv --d` is a convenience alias for `codex --dangerously-bypass-approvals-and-sandbox`
+- `cxv -d` / `cxv --d` are convenience aliases for `codex --dangerously-bypass-approvals-and-sandbox`
 - `cxv --ad` is a legacy compatibility flag kept only for CXV-side bypass toggles
 
 Everything else should be treated as standard Codex CLI syntax.
@@ -35,7 +33,8 @@ cxv -c 'model="gpt-5.5"'                    # == codex -c 'model="gpt-5.5"'
 cxv exec "summarize this repo"              # == codex exec "summarize this repo"
 cxv review                                  # == codex review
 cxv --search --model gpt-5.5                # == codex --search --model gpt-5.5
-cxv --d                                     # == codex --dangerously-bypass-approvals-and-sandbox
+cxv -d                                      # == codex --dangerously-bypass-approvals-and-sandbox
+cxv --d                                     # same as cxv -d
 ```
 
 The author's most-used command is:
@@ -110,7 +109,7 @@ The most useful inherited Codex commands in CXV are:
 
 ### Configuration Override
 
-If you need to use a custom API endpoint (e.g., a corporate proxy), simply configure it in `~/.codex/settings.json` or set the `OPENAI_BASE_URL` environment variable. `cxv` will automatically detect and correctly forward requests.
+If you need to use a custom API endpoint (e.g., a corporate proxy), configure `openai_base_url` in `~/.codex/config.toml` or set the `OPENAI_BASE_URL` environment variable. `cxv` will automatically detect and correctly forward requests.
 
 ### Silent Mode
 
@@ -149,9 +148,9 @@ Fulfill your imagination of mobile programming. There's also a plugin mechanism
 
 
 - Captures all API requests from Codex in real time, ensuring raw text — not redacted logs (this is important!!!)
-- Automatically identifies and labels Main Agent and Sub Agent requests (subtypes: Plan, Search, Bash)
+- Automatically identifies and labels Main Agent and Sub Agent requests (subtypes: Plan, Search, Shell)
 - MainAgent requests support Body Diff JSON, showing collapsed differences from the previous MainAgent request (only changed/new fields)
-- Each request displays inline Token usage statistics (input/output tokens, cache creation/read, hit rate)
+- Each request displays inline token usage statistics (input/output tokens)
 - Compatible with Codex Router (CCR) and other proxy scenarios — falls back to API path pattern matching
 
 ### Conversation Mode
@@ -164,7 +163,7 @@ Click the "Conversation Mode" button in the top-right corner to parse the Main A
 - Agent Team display is not yet supported
 - User messages are right-aligned (blue bubbles), Main Agent replies are left-aligned (dark bubbles)
 - `thinking` blocks are collapsed by default, rendered as Markdown — click to expand and view the thinking process; one-click translation is supported (feature is still unstable)
-- User selection messages (AskUserQuestion) are displayed in Q&A format
+- User selection messages (`request_user_input`) are displayed in Q&A format
 - Bidirectional mode sync: switching to conversation mode auto-scrolls to the conversation corresponding to the selected request; switching back to raw mode auto-scrolls to the selected request
 - Settings panel: toggle default collapse state for tool results and thinking blocks
 - Mobile conversation browsing: in mobile CLI mode, tap the "Conversation Browse" button in the top bar to slide out a read-only conversation view for browsing the complete conversation history on mobile
@@ -175,12 +174,11 @@ The "Data Statistics" floating panel in the header area:
 
 <img width="1500" height="765" alt="image" src="https://github.com/user-attachments/assets/a3d2db47-eac3-463a-9b44-3fa64994bf3b" />
 
-- Displays cache creation/read counts and cache hit rate
-- Cache rebuild statistics: grouped by reason (TTL, system/tools/model changes, message truncation/modification, key changes) showing counts and cache_creation tokens
+- Displays input/output token usage by model
 - Tool usage statistics: displays call frequency for each tool sorted by number of calls
 - Skill usage statistics: displays call frequency for each skill sorted by number of calls
 - Supports teammate statistics
-- Concept help (?) icon: click to view built-in documentation for MainAgent, CacheRebuild, and each tool
+- Concept help (?) icon: click to view built-in documentation for MainAgent and each tool
 
 ### Log Management
 
@@ -188,7 +186,7 @@ Via the CX-Viewer dropdown menu in the top-left corner:
 <img width="1500" height="760" alt="image" src="https://github.com/user-attachments/assets/33295e2b-f2e0-4968-a6f1-6f3d1404454e" />
 
 **Log Compression**
-Regarding logs, the author wants to clarify that the official Anthropic definitions have not been modified, ensuring log integrity. However, since individual log entries from the 1M Opus model can become extremely large in later stages, thanks to certain log optimizations for MainAgent, at least 66% size reduction is achieved without gzip. The parsing method for these compressed logs can be extracted from the current repository.
+Log compression does not change the captured Codex/OpenAI payload semantics. It only optimizes repeated MainAgent context stored by CX-Viewer, which can substantially reduce log size for long sessions without requiring gzip. The parser for these compressed entries is included in this repository.
 
 ### More Useful Features
 
@@ -198,15 +196,9 @@ You can quickly locate your prompts using the sidebar tools.
 
 --- 
 
-<img width="1500" height="765" alt="image" src="https://github.com/user-attachments/assets/82b8eb67-82f5-41b1-89d6-341c95a047ed" />
-
-The interesting KV-Cache-Text feature lets you see exactly what Claude sees.
-
----
-
 <img width="1500" height="765" alt="image" src="https://github.com/user-attachments/assets/54cdfa4e-677c-4aed-a5bb-5fd946600c46" />
 
-You can upload images and describe your needs — Claude's image understanding is incredibly powerful. And as you know, you can paste images directly with Ctrl+V, and your complete content will be displayed in the conversation.
+You can upload images and describe your needs. You can also paste images directly with Ctrl+V, and the complete content will be displayed in the conversation.
 
 ---
 
@@ -226,7 +218,7 @@ More features waiting to be discovered... For example: the system supports Agent
 
 CX-Viewer automatically checks for updates on startup (at most once every 4 hours). Within the same major version (e.g., 1.x.x -> 1.y.z), updates are applied automatically and take effect on the next restart. Cross-major-version updates only show a notification.
 
-Auto-update follows Codex's global configuration in `~/.codex/settings.json`. If Codex has auto-updates disabled (`autoUpdates: false`), CX-Viewer will also skip auto-updates.
+Auto-update follows Codex's global configuration in `~/.codex/config.toml`. Set `auto_update = false` there, or set `CODEX_DISABLE_NONESSENTIAL_TRAFFIC=1`, to skip CX-Viewer update checks.
 
 ### Multi-language Support
 
@@ -234,6 +226,43 @@ CX-Viewer supports 18 languages, automatically switching based on system locale:
 
 简体中文 | English | 繁體中文 | 한국어 | Deutsch | Español | Français | Italiano | Dansk | 日本語 | Polski | Русский | العربية | Norsk | Português (Brasil) | ไทย | Türkçe | Українська
 
+## NPM Release Preparation
+
+The npm package name is `cx-viewer`. The project is configured to publish to the public npm registry through `publishConfig.registry`.
+
+Before publishing, verify the registry state and local account:
+
+```bash
+npm view cx-viewer version --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+```
+
+Run the local release checks before changing the version:
+
+```bash
+npm run release:check
+```
+
+This command runs tests, builds the frontend, and previews the package contents with `npm pack --dry-run`. It does not publish anything. The dry-run wrapper uses a temporary npm cache so the check is not blocked by stale root-owned files in `~/.npm`. Review the dry-run file list before release; `prepublishOnly` also runs `npm run build` during the real publish step, and the `files` whitelist in `package.json` controls what gets included.
+
+For an actual release, bump the package version first, commit the release, push to GitHub, then publish manually:
+
+```bash
+# Choose patch, minor, or major based on the release scope.
+npm version patch --no-git-tag-version
+
+git status --short
+git add package.json README.md scripts/npm-pack-dry-run.mjs
+git commit -m "chore: prepare cx-viewer release"
+VERSION=$(node -p "require('./package.json').version")
+git tag "v${VERSION}"
+git push origin main --tags
+
+npm publish --registry=https://registry.npmjs.org
+```
+
+Do not publish without a version bump; npm will reject republishing an existing version such as `1.0.3`.
+
 ## License
 
 MIT

package/build.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 执行 vite build，输出到 dist/
+console.log('🔨 正在执行 Vite 构建...');
+execSync('npx vite build', { cwd: __dirname, stdio: 'inherit' });
+
+console.log('✅ Build 完成，输出目录: dist/');
+console.log('   - dist/index.html');
+console.log('   - dist/assets/');

package/cli.js

@@ -264,7 +264,7 @@ async function runCliMode(extraCodexArgs = [], cwd) {
   const { registerWorkspace } = await import('./workspace-registry.js');
   registerWorkspace(workingDir);
 
-  // 确保 AskUserQuestion hook 已注册到 ~/.codex/settings.json
+  // 确保 request_user_input hook 已注册到 Codex hooks.json
   ensureHooks();
 
   // 2. 设置 CLI 模式标记
@@ -320,10 +320,57 @@ async function runCliMode(extraCodexArgs = [], cwd) {
     console.error('[CX Viewer] Failed to inject OTel config:', err.message);
   }
 
+  // Start HTTP capture proxy for all auth modes (API-key and ChatGPT/OAuth).
+  // proxy.js detects OAuth via the chatgpt-account-id request header and routes
+  // to chatgpt.com/backend-api/codex; API-key traffic routes to api.openai.com.
+  let _proxyPort = null;
+  let configArgs = [];
+  {
+    const { readFileSync, existsSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const { homedir } = await import('node:os');
+    const { startProxy, stopProxy } = await import('./proxy.js');
+    const { readOriginalOpenAiBaseUrl } = await import('./lib/codex-config.js');
+
+    let authMode = 'chatgpt';
+    try {
+      const authPath = join(homedir(), '.codex', 'auth.json');
+      if (existsSync(authPath)) {
+        const auth = JSON.parse(readFileSync(authPath, 'utf-8'));
+        authMode = auth.auth_mode || 'chatgpt';
+      }
+    } catch { }
+
+    {
+      const loopback = '127.0.0.1,localhost,::1';
+      const existing = process.env.NO_PROXY || process.env.no_proxy || '';
+      const merged = existing ? `${existing},${loopback}` : loopback;
+      process.env.NO_PROXY = merged;
+      process.env.no_proxy = merged;
+    }
+    try {
+      _proxyPort = await startProxy();
+      if (authMode === 'chatgpt') {
+        process.env.CXV_ORIGINAL_BASE_URL = 'https://chatgpt.com/backend-api/codex';
+      } else {
+        process.env.CXV_ORIGINAL_BASE_URL = readOriginalOpenAiBaseUrl() || 'https://api.openai.com/v1';
+      }
+      if (!process.env.CXV_ORIGINAL_CHATGPT_BASE_URL) {
+        process.env.CXV_ORIGINAL_CHATGPT_BASE_URL = 'https://chatgpt.com/backend-api/codex';
+      }
+      configArgs = ['-c', `openai_base_url="http://127.0.0.1:${_proxyPort}/v1"`];
+      console.log(`[CX Viewer] HTTP capture proxy started on 127.0.0.1:${_proxyPort} (${authMode} mode)`);
+    } catch (err) {
+      console.warn('[CX Viewer] HTTP capture proxy failed to start:', err.message);
+    }
+  }
+
   // 启动 App-Server Bridge（WebSocket 中间代理，获取完整执行日志）
-  const { LOG_FILE: currentLogFile } = await import('./interceptor.js');
+  const interceptorMod = await import('./interceptor.js');
+  const currentLogFile = interceptorMod.LOG_FILE;
   let _bridge = null;
-  let bridgeArgs = [];
+  // configArgs 让 codex 通过 -c 覆盖重定向到抓包代理；bridge 失败回退直连时 TUI 也需要它
+  let bridgeArgs = [...configArgs];
   try {
     const { startAppServerBridge } = await import('./lib/appserver-bridge.js');
     _bridge = await startAppServerBridge({
@@ -331,9 +378,13 @@ async function runCliMode(extraCodexArgs = [], cwd) {
       codexPath,
       logFile: currentLogFile,
       env: process.env,
+      extraConfigArgs: configArgs,
+      onApprovalsReviewerActive: (reviewer) => serverMod.setActiveCodexApprovalsReviewer(reviewer, true),
+      writeLogEntry: interceptorMod.appendLogEntry,
     });
+    serverMod.setCodexApprovalsReviewerUpdater(_bridge.setApprovalsReviewer);
     // 让 codex TUI 通过 --remote 连接到代理
-    bridgeArgs = ['--remote', `ws://127.0.0.1:${_bridge.proxyPort}`];
+    bridgeArgs = [...configArgs, '--remote', `ws://127.0.0.1:${_bridge.proxyPort}`];
     console.log(`[CX Viewer] App-Server bridge started (proxy:${_bridge.proxyPort} → server:${_bridge.appServerPort})`);
   } catch (err) {
     console.warn('[CX Viewer] App-Server bridge failed, falling back to direct mode:', err.message);
@@ -341,8 +392,15 @@ async function runCliMode(extraCodexArgs = [], cwd) {
 
   // 启动 PTY 中的 codex TUI
   const { spawnCodex, killPty } = await import('./pty-manager.js');
+  const savedApprovalsReviewer = serverMod.getApprovalsReviewerPreference();
+  const reviewerArgs = savedApprovalsReviewer
+    ? ['-c', `approvals_reviewer="${savedApprovalsReviewer}"`]
+    : [];
+  if (!_bridge && savedApprovalsReviewer) {
+    serverMod.setActiveCodexApprovalsReviewer(savedApprovalsReviewer, true);
+  }
   try {
-    await spawnCodex(null, workingDir, [...bridgeArgs, ...extraCodexArgs], codexPath, isNpmVersion, port);
+    await spawnCodex(null, workingDir, [...bridgeArgs, ...reviewerArgs, ...extraCodexArgs], codexPath, isNpmVersion, port);
   } catch (err) {
     console.error('[CX Viewer] Failed to spawn Codex:', err.message);
     if (_bridge) _bridge.stop();
@@ -378,7 +436,10 @@ async function runCliMode(extraCodexArgs = [], cwd) {
   };
   const cleanup = () => {
     killPty();
+    serverMod.setCodexApprovalsReviewerUpdater(null);
+    serverMod.setActiveCodexApprovalsReviewer(null, false);
     if (_bridge) _bridge.stop();
+    try { stopProxy(); } catch {}
     cleanupOtelConfig();
     serverMod.stopViewer().finally(() => process.exit());
   };
@@ -387,13 +448,23 @@ async function runCliMode(extraCodexArgs = [], cwd) {
 }
 
 async function runSdkMode(extraCodexArgs = [], cwd) {
+  let codexPath = resolveNpmCodexPath();
+  if (!codexPath) {
+    codexPath = resolveNativePath();
+  }
+
+  if (!codexPath) {
+    console.error(t('cli.cMode.notFound'));
+    process.exit(1);
+  }
+
   // 检查 SDK 是否可用
   let sdkManager;
   try {
     sdkManager = await import('./lib/sdk-manager.js');
     if (!sdkManager.isSdkAvailable()) throw new Error('query not available');
-  } catch {
-    console.warn('[CX Viewer] Agent SDK not available, falling back to PTY mode (-C)');
+  } catch (err) {
+    console.warn(`[CX Viewer] Codex SDK not available (${err.message}), falling back to PTY mode`);
     return runCliMode(extraCodexArgs, cwd);
   }
 
@@ -403,7 +474,7 @@ async function runSdkMode(extraCodexArgs = [], cwd) {
   const { registerWorkspace } = await import('./workspace-registry.js');
   registerWorkspace(workingDir);
 
-  // 不需要 ensureHooks — SDK canUseTool 处理 AskUserQuestion + 权限
+  // 不需要 ensureHooks — SDK canUseTool 处理 request_user_input + 权限
   // 不需要 proxy — SDK 直接管理 API 通信
 
   // 设置环境标记（必须在 import server.js 之前）
@@ -411,8 +482,15 @@ async function runSdkMode(extraCodexArgs = [], cwd) {
   process.env.CXV_SDK_MODE = '1';
   process.env.CXV_PROJECT_DIR = workingDir;
 
+  // 初始化日志文件（CXV_WORKSPACE_MODE=1 下 interceptor 跳过了自动初始化）
+  const { initForWorkspace } = await import('./interceptor.js');
+  initForWorkspace(workingDir);
+
   // 启动 HTTP 服务器
   const serverMod = await import('./server.js');
+  await serverMod.startViewer();
+  serverMod.setWorkspaceLaunched(true);
+  serverMod.initPostLaunch();
 
   await new Promise(resolve => {
     const check = () => {
@@ -431,18 +509,26 @@ async function runSdkMode(extraCodexArgs = [], cwd) {
   if (hasBypassPermissions(extraCodexArgs)) {
     permissionMode = 'bypassPermissions';
   }
+  const savedApprovalsReviewer = serverMod.getApprovalsReviewerPreference();
+  const sdkCodexArgs = savedApprovalsReviewer
+    ? [...extraCodexArgs, '-c', `approvals_reviewer="${savedApprovalsReviewer}"`]
+    : extraCodexArgs;
 
   // 初始化 SDK 会话
   sdkManager.initSdkSession(workingDir, basename(workingDir), {
     onEntry: (entry) => serverMod.pushSdkEntry(entry),
     onStreamingStatus: (data) => serverMod.setSdkStreamingState(data),
+    onStreamProgress: (data) => serverMod.sendSdkStreamProgress(data),
     broadcastWs: (msg) => serverMod.broadcastWsMessage(msg),
     permissionMode,
+    codexPath,
+    codexArgs: sdkCodexArgs,
   });
 
   // 注册 SDK 回调到 server.js（WS 消息路由用）
   serverMod.setSdkResolveApproval(sdkManager.resolveApproval);
   serverMod.setSdkSendUserMessage(sdkManager.sendUserMessage);
+  serverMod.setSdkInterruptTurn(sdkManager.interruptTurn);
 
   // 自动打开浏览器
   const protocol = serverMod.getProtocol();
@@ -461,6 +547,13 @@ async function runSdkMode(extraCodexArgs = [], cwd) {
     console.log(`  ➜ Network: ${protocol}://${_ip}:${port}?token=${_token}`);
   }
 
+  const initialPrompt = sdkManager.getInitialPrompt();
+  if (initialPrompt) {
+    sdkManager.sendUserMessage(initialPrompt).catch(err => {
+      console.error('[SDK] initial prompt error:', err.message);
+    });
+  }
+
   // 注册退出处理
   const cleanup = () => {
     sdkManager.stopSession();
@@ -572,17 +665,8 @@ if (isUninstall) {
     console.log(t('cli.uninstall.hookFail', { error: shellResult.error }));
   }
 
-  // 清理 statusLine 配置和脚本（兼容历史版本遗留）
+  // 清理 statusLine 脚本（兼容历史版本遗留）
   try {
-    const settingsPath = resolve(homedir(), '.codex', 'settings.json');
-    if (existsSync(settingsPath)) {
-      const settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-      if (settings.statusLine?.command?.includes('cxv-statusline')) {
-        delete settings.statusLine;
-        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-        console.log('Cleaned statusLine config from settings.json');
-      }
-    }
     const cxvScript = resolve(homedir(), '.codex', 'cxv-statusline.sh');
     if (existsSync(cxvScript)) {
       unlinkSync(cxvScript);

package/concepts/ar/BodyDiffJSON.md

@@ -2,7 +2,7 @@
 
 ## الخلفية
 
-يعتمد MainAgent في Claude Code آلية إرسال السياق الكامل — حيث يحمل كل طلب سجل المحادثة الكامل وsystem prompt وتعريفات الأدوات وغيرها. هذا يعني أنه مع تقدم المحادثة يصبح جسم الطلب أكبر فأكبر، ومن الصعب تحديد "ما الجديد في هذه الجولة" عند عرض Body الخام مباشرة.
+يعتمد MainAgent في Codex آلية إرسال السياق الكامل — حيث يحمل كل طلب سجل المحادثة الكامل وsystem prompt وتعريفات الأدوات وغيرها. هذا يعني أنه مع تقدم المحادثة يصبح جسم الطلب أكبر فأكبر، ومن الصعب تحديد "ما الجديد في هذه الجولة" عند عرض Body الخام مباشرة.
 
 Body Diff JSON صُمم لحل هذه المشكلة: يقارن تلقائياً بين طلبي MainAgent متتاليين ويستخلص الجزء التزايدي، مما يتيح لك رؤية المحتوى الجديد الفعلي في هذا الطلب بنظرة واحدة.
 

package/concepts/ar/BodyFields.md

@@ -1,42 +1,39 @@
-# شرح حقول Request Body
+# Request Body Fields
 
-شرح الحقول العليا لجسم طلب `/v1/messages` في Claude API.
+Field descriptions for CX-Viewer's normalized Codex request body. The original source may be OpenAI Responses API traffic, Codex app-server notifications, or Codex SDK events; CX-Viewer maps them into one stable viewer shape.
 
-## قائمة الحقول
+## Field List
 
-| الحقل | النوع | الشرح |
-|------|------|------|
-| **model** | string | اسم النموذج المستخدم، مثل `claude-opus-4-6`، `claude-sonnet-4-6` |
-| **messages** | array | سجل رسائل المحادثة. تحتوي كل رسالة على `role` (user/assistant) و`content` (مصفوفة من الكتل مثل النصوص والصور وtool_use وtool_result) |
-| **system** | array | System prompt. يتضمن التعليمات الأساسية لـ Codex وتعليمات استخدام الأدوات ومعلومات البيئة ومحتوى CLAUDE.md وغيرها. الكتل التي تحمل `cache_control` يتم تخزينها مؤقتًا عبر prompt caching |
-| **tools** | array | قائمة تعريفات الأدوات المتاحة. تحتوي كل أداة على `name` و`description` و`input_schema` (JSON Schema). عادةً يمتلك MainAgent أكثر من 20 أداة، بينما يمتلك SubAgent عددًا قليلًا فقط |
-| **metadata** | object | البيانات الوصفية للطلب، تتضمن عادةً `user_id` لتحديد هوية المستخدم |
-| **max_tokens** | number | الحد الأقصى لعدد الرموز (tokens) في رد النموذج الواحد، مثل `16000`، `64000` |
-| **thinking** | object | تكوين التفكير الموسع. `type: "enabled"` يُفعّل وضع التفكير، و`budget_tokens` يتحكم في الحد الأقصى لرموز التفكير |
-| **context_management** | object | تكوين إدارة السياق. `truncation: "auto"` يسمح لـ Codex باقتطاع سجل الرسائل الطويل تلقائيًا |
-| **output_config** | object | تكوين المخرجات، مثل إعداد `format` |
-| **stream** | boolean | ما إذا كان يتم تفعيل الاستجابة المتدفقة. يستخدم Codex دائمًا `true` |
+| Field | Type | Description |
+|-------|------|-------------|
+| **model** | string | The model name selected by Codex, e.g. a `gpt-*` model |
+| **input** | string/array | OpenAI Responses API input. Codex usually uses the array form for user input, assistant history, tool results, and other context items |
+| **instructions** | string/array | OpenAI Responses API instructions. This can include Codex core directives, tool usage guidelines, environment information, and `AGENTS.md` project instructions |
+| **tools** | array | Available tool definitions or compact tool descriptors. MainAgent usually has a broader tool set than SubAgent |
+| **metadata** | object | Request metadata such as `thread_id`, `turn_id`, `cwd`, SDK/app-server source, and subAgent parent-thread information |
+| **max_tokens** | number | Maximum number of tokens for a single model response, e.g. `16000`, `64000` |
+| **reasoning_effort** | string | Reasoning effort when reported by Codex |
+| **reasoning_summary** | string | Reasoning summary mode when reported by Codex |
+| **approval_policy** | string | Codex approval policy for the turn |
+| **sandbox_policy** | object/string | Sandbox policy for the turn when available |
+| **stream** | boolean | Whether the OpenAI Responses API request used streaming; app-server/SDK entries are normalized as streamed turns |
 
-## بنية messages
+## input Structure
 
-حقل `content` لكل رسالة هو مصفوفة من الكتل، والأنواع الشائعة هي:
+When `input` is an array, each input item usually contains `role` and `content`. `content` can be an array of blocks. Common types include:
 
-- **text**: محتوى نصي عادي
-- **tool_use**: استدعاء النموذج لأداة (يحتوي على `name`، `input`)
-- **tool_result**: نتيجة تنفيذ الأداة (يحتوي على `tool_use_id`، `content`)
-- **image**: محتوى صورة (base64 أو URL)
-- **thinking**: عملية تفكير النموذج (وضع التفكير الموسع)
+- **text**: Plain text content
+- **tool_use**: Model tool invocation (contains `name`, `input`)
+- **tool_result**: Tool execution result (contains `tool_use_id`, `content`)
+- **image/input_image/local_image**: Image content or an attached local image reference
+- **thinking**: Model's thinking process (extended thinking mode)
 
-## بنية system
+## instructions Structure
 
-تتضمن مصفوفة system prompt عادةً:
+`instructions` typically contains:
 
-1. **تعليمات الوكيل الأساسية** ("You are Codex...")
-2. **مواصفات استخدام الأدوات**
-3. **محتوى CLAUDE.md** (تعليمات على مستوى المشروع)
-4. **تذكيرات المهارات** (skills reminder)
-5. **معلومات البيئة** (نظام التشغيل، الصدفة، حالة git، إلخ) — في الواقع يعتمد Codex بشكل كبير على git. إذا كان المشروع يحتوي على مستودع git، يمكن لـ Codex إظهار فهم أفضل للمشروع، بما في ذلك القدرة على جلب التغييرات البعيدة وسجلات الالتزام للمساعدة في التحليل
-
-الكتل المعلّمة بـ `cache_control: { type: "ephemeral" }` يتم تخزينها مؤقتًا بواسطة Anthropic API لمدة 5 دقائق. عند إصابة الذاكرة المؤقتة يتم المحاسبة كـ `cache_read_input_tokens` (أقل بكثير من `input_tokens`).
-
-> **ملاحظة**: بالنسبة للعملاء الخاصين مثل Codex، لا يعتمد خادم Anthropic فعليًا بشكل كامل على خاصية `cache_control` في الطلب لتحديد سلوك التخزين المؤقت. يقوم الخادم بتنفيذ سياسة التخزين المؤقت تلقائيًا لحقول معينة (مثل system prompt وتعريفات الأدوات)، حتى لو لم يحمل الطلب علامة `cache_control` بشكل صريح. لذلك، عندما لا ترى هذه الخاصية في جسم الطلب، لا تحتاج إلى الاستغراب — فالخادم قد أنجز عملية التخزين المؤقت في الكواليس، لكنه لم يكشف هذه المعلومات للعميل. هذا تفاهم ضمني بين Codex وAnthropic API.
+1. **Core agent instructions** ("You are Codex...")
+2. **Tool usage guidelines**
+3. **AGENTS.md contents** (project-level instructions)
+4. **Skills reminders** (skills reminder)
+5. **Environment information** (OS, shell, git status, etc.) — In fact, Codex relies heavily on git. If a project has a git repository, Codex demonstrates a better understanding of the project, including the ability to pull remote changes and commit history to assist with analysis