docs: experimental codex tool document

docs/src/content/docs/guides/tools.mdx

@@ -11,15 +11,17 @@ import nonStrictSchemaTools from '../../../../../examples/docs/tools/nonStrictSc
 import agentsAsToolsExample from '../../../../../examples/docs/tools/agentsAsTools.ts?raw';
 import agentsAsToolsStreamingExample from '../../../../../examples/docs/tools/agentsAsToolsStreaming.ts?raw';
 import mcpLocalServer from '../../../../../examples/docs/tools/mcpLocalServer.ts?raw';
+import codexToolExample from '../../../../../examples/docs/tools/codexTool.ts?raw';
 
 Tools let an Agent **take actions** – fetch data, call external APIs, execute code, or even use a
-computer. The JavaScript/TypeScript SDK supports five categories:
+computer. The JavaScript/TypeScript SDK supports six categories:
 
 1. **Hosted OpenAI tools** – run alongside the model on OpenAI servers. _(web search, file search, code interpreter, image generation)_
 2. **Local built-in tools** – run in your environment. _(computer use, shell, apply_patch)_
 3. **Function tools** – wrap any local function with a JSON schema so the LLM can call it.
 4. **Agents as tools** – expose an entire Agent as a callable tool.
 5. **MCP servers** – attach a Model Context Protocol server (local or remote).
+6. **Experimental: Codex tool** – wrap the Codex SDK as a function tool to run workspace-aware tasks.
 
 ---
 
@@ -145,6 +147,30 @@ See [`filesystem-example.ts`](https://github.com/openai/openai-agents-js/tree/ma
 
 ---
 
+## 6. Experimental: Codex tool
+
+`@openai/agents-extensions/experimental/codex` provides `codexTool()`, a function tool that routes model tool calls to the Codex SDK so the agent can run workspace-scoped tasks (shell, file edits, MCP tools) autonomously. This surface is experimental and may change.
+
+Quick start:
+
+<Code
+  lang="typescript"
+  code={codexToolExample}
+  title="Experimental Codex tool"
+/>
+
+What to know:
+
+- Auth: supply `CODEX_API_KEY` (preferred) or `OPENAI_API_KEY`, or pass `codexOptions.apiKey`.
+- Inputs: strict schema—`inputs` must contain at least one `{ type: 'text', text }` or `{ type: 'local_image', path }`.
+- Safety: pair `sandboxMode` with `workingDirectory`; set `skipGitRepoCheck` if the directory is not a Git repo.
+- Behavior: `persistSession: true` reuses a single Codex thread and returns its `threadId`; you can surface it for resumable work.
+- Streaming: `onStream` mirrors Codex events (reasoning, command execution, MCP tool calls, file changes, web search) so you can log or trace progress.
+- Outputs: tool result includes `response`, `usage`, and `threadId`, and Codex token usage is recorded in `RunContext`.
+- Structure: `outputSchema` enforces structured Codex responses per turn when you need typed outputs.
+
+---
+
 ## Tool use behavior
 
 Refer to the [Agents guide](/openai-agents-js/guides/agents#forcing-tool-use) for controlling when and how a model

examples/docs/sessions/customSession.ts

@@ -1,29 +1,29 @@
 import { Agent, run } from '@openai/agents';
 import { randomUUID } from '@openai/agents-core/_shims';
-import { logger, Logger } from '@openai/agents-core/dist/logger';
+import { getLogger } from '@openai/agents-core';
 import type { AgentInputItem, Session } from '@openai/agents-core';
 
 /**
  * Minimal example of a Session implementation; swap this class for any storage-backed version.
  */
 export class CustomMemorySession implements Session {
   private readonly sessionId: string;
-  private readonly logger: Logger;
+  private readonly logger: ReturnType<typeof getLogger>;
 
   private items: AgentInputItem[];
 
   constructor(
     options: {
       sessionId?: string;
       initialItems?: AgentInputItem[];
-      logger?: Logger;
+      logger?: ReturnType<typeof getLogger>;
     } = {},
   ) {
     this.sessionId = options.sessionId ?? randomUUID();
     this.items = options.initialItems
       ? options.initialItems.map(cloneAgentItem)
       : [];
-    this.logger = options.logger ?? logger;
+    this.logger = options.logger ?? getLogger('openai-agents:memory-session');
   }
 
   async getSessionId(): Promise<string> {

examples/docs/tools/codexTool.ts

@@ -0,0 +1,20 @@
+import { Agent } from '@openai/agents';
+import { codexTool } from '@openai/agents-extensions/experimental/codex';
+
+export const codexAgent = new Agent({
+  name: 'Codex Agent',
+  instructions:
+    'Use the codex tool to inspect the workspace and answer the question. When skill names, which usually start with `$`, are mentioned, you must rely on the codex tool to use the skill and answer the question.',
+  tools: [
+    codexTool({
+      sandboxMode: 'workspace-write',
+      workingDirectory: '/path/to/repo',
+      defaultThreadOptions: {
+        model: 'gpt-5.2-codex',
+        networkAccessEnabled: true,
+        webSearchEnabled: false,
+      },
+      persistSession: true,
+    }),
+  ],
+});

examples/docs/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "extends": "../../tsconfig.examples.json",
   "compilerOptions": {
+    "moduleResolution": "bundler",
     "noUnusedLocals": false,
     "skipLibCheck": true
   }