ai-sdk-provider-codex-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,22 @@
 # AI SDK Provider for Codex CLI
 
-A community provider for Vercel AI SDK v5 that uses OpenAI’s Codex CLI (non‑interactive `codex exec`) to talk to GPT‑5 class models with your ChatGPT Plus/Pro subscription. The provider spawns the Codex CLI process, parses its JSONL output, and adapts it to the AI SDK LanguageModelV2 interface.
-
-- Works with `generateText`, `streamText`, and `generateObject` (JSON schemas via prompt engineering)
+[![npm version](https://img.shields.io/npm/v/ai-sdk-provider-codex-cli.svg)](https://www.npmjs.com/package/ai-sdk-provider-codex-cli)
+[![npm downloads](https://img.shields.io/npm/dm/ai-sdk-provider-codex-cli.svg)](https://www.npmjs.com/package/ai-sdk-provider-codex-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Node >= 18](https://img.shields.io/badge/node-%3E%3D18-43853d?logo=node.js&logoColor=white)
+![AI SDK v5](https://img.shields.io/badge/AI%20SDK-v5-000?logo=vercel&logoColor=white)
+![Modules: ESM + CJS](https://img.shields.io/badge/modules-ESM%20%2B%20CJS-3178c6)
+![TypeScript](https://img.shields.io/badge/TypeScript-blue)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/issues)
+[![Latest Release](https://img.shields.io/github/v/release/ben-vargas/ai-sdk-provider-codex-cli?display_name=tag)](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/releases/latest)
+
+A community provider for Vercel AI SDK v5 that uses OpenAI’s Codex CLI (non‑interactive `codex exec`) to talk to GPT‑5 class models (`gpt-5` and the Codex-specific `gpt-5-codex` slug) with your ChatGPT Plus/Pro subscription. The provider spawns the Codex CLI process, parses its JSONL output, and adapts it to the AI SDK LanguageModelV2 interface.
+
+- Works with `generateText`, `streamText`, and `generateObject` (native JSON Schema support via `--output-schema`)
 - Uses ChatGPT OAuth from `codex login` (tokens in `~/.codex/auth.json`) or `OPENAI_API_KEY`
 - Node-only (spawns a local process); supports CI and local dev
+- **v0.3.0**: Adds comprehensive tool streaming support for monitoring autonomous tool execution
+- **v0.2.0 Breaking Changes**: Switched to `--experimental-json` and native schema enforcement (see [CHANGELOG](CHANGELOG.md))
 
 ## Installation
 
@@ -15,6 +27,12 @@ npm i -g @openai/codex
 codex login   # or set OPENAI_API_KEY
 ```
 
+> **⚠️ Version Requirement**: Requires Codex CLI **>= 0.42.0** for `--experimental-json` and `--output-schema` support. **>= 0.44.0 recommended** for full usage tracking and tool streaming support. Check your version with `codex --version` and upgrade if needed:
+>
+> ```bash
+> npm i -g @openai/codex@latest
+> ```
+
 2. Install provider and AI SDK
 
 ```bash
@@ -29,7 +47,7 @@ Text generation
 import { generateText } from 'ai';
 import { codexCli } from 'ai-sdk-provider-codex-cli';
 
-const model = codexCli('gpt-5', {
+const model = codexCli('gpt-5-codex', {
   allowNpx: true,
   skipGitRepoCheck: true,
   approvalMode: 'on-failure',
@@ -49,8 +67,10 @@ Streaming
 import { streamText } from 'ai';
 import { codexCli } from 'ai-sdk-provider-codex-cli';
 
+// The provider works with both `gpt-5` and `gpt-5-codex`; use the latter for
+// the Codex CLI specific slug.
 const { textStream } = await streamText({
-  model: codexCli('gpt-5', { allowNpx: true, skipGitRepoCheck: true }),
+  model: codexCli('gpt-5-codex', { allowNpx: true, skipGitRepoCheck: true }),
   prompt: 'Write two short lines of encouragement.',
 });
 for await (const chunk of textStream) process.stdout.write(chunk);
@@ -65,7 +85,7 @@ import { codexCli } from 'ai-sdk-provider-codex-cli';
 
 const schema = z.object({ name: z.string(), age: z.number().int() });
 const { object } = await generateObject({
-  model: codexCli('gpt-5', { allowNpx: true, skipGitRepoCheck: true }),
+  model: codexCli('gpt-5-codex', { allowNpx: true, skipGitRepoCheck: true }),
   schema,
   prompt: 'Generate a small user profile.',
 });
@@ -76,18 +96,60 @@ console.log(object);
 
 - AI SDK v5 compatible (LanguageModelV2)
 - Streaming and non‑streaming
-- JSON object generation with Zod schemas (prompt‑engineered)
+- **Tool streaming support** (v0.3.0+) - Monitor autonomous tool execution in real-time
+- **Native JSON Schema support** via `--output-schema` (API-enforced with `strict: true`)
+- JSON object generation with Zod schemas (100-200 fewer tokens per request vs prompt engineering)
 - Safe defaults for non‑interactive automation (`on-failure`, `workspace-write`, `--skip-git-repo-check`)
 - Fallback to `npx @openai/codex` when not on PATH (`allowNpx`)
+- Usage tracking from experimental JSON event format
+
+### Tool Streaming (v0.3.0+)
+
+The provider supports comprehensive tool streaming, enabling real-time monitoring of Codex CLI's autonomous tool execution:
+
+```js
+import { streamText } from 'ai';
+import { codexCli } from 'ai-sdk-provider-codex-cli';
+
+const result = await streamText({
+  model: codexCli('gpt-5-codex', { allowNpx: true, skipGitRepoCheck: true }),
+  prompt: 'List files and count lines in the largest one',
+});
+
+for await (const part of result.fullStream) {
+  if (part.type === 'tool-call') {
+    console.log('🔧 Tool:', part.toolName);
+  }
+  if (part.type === 'tool-result') {
+    console.log('✅ Result:', part.result);
+  }
+}
+```
+
+**What you get:**
+
+- Tool invocation events when Codex starts executing tools (exec, patch, web_search, mcp_tool_call)
+- Tool input tracking with full parameter visibility
+- Tool result events with complete output payloads
+- `providerExecuted: true` on all tool calls (Codex executes autonomously, app doesn't need to)
+
+**Limitation:** Real-time output streaming (`output-delta` events) not yet available. Tool outputs delivered in final `tool-result` event. See `examples/streaming-tool-calls.mjs` and `examples/streaming-multiple-tools.mjs` for usage patterns.
+
+### Text Streaming behavior
+
+**Status:** Incremental streaming not currently supported with `--experimental-json` format (expected in future Codex CLI releases)
 
-### Streaming behavior
+The `--experimental-json` output format (introduced Sept 25, 2025) currently only emits `item.completed` events with full text content. Incremental streaming via `item.updated` or delta events is not yet implemented by OpenAI.
 
-When using `codex exec --json`, the Codex CLI intentionally suppresses token/assistant deltas in its JSON event stream. Instead, it writes the final assistant message to the file you pass via `--output-last-message` and then signals completion. This provider:
+**What this means:**
 
-- emits `response-metadata` early (as soon as the session is configured), and
-- returns the final text as a single `text-delta` right before `finish`.
+- `streamText()` works functionally but delivers the entire response in a single chunk after generation completes
+- No incremental text deltas—you wait for the full response, then receive it all at once
+- The AI SDK's streaming interface is supported, but actual incremental streaming is not available
 
-This is expected behavior for JSON mode in Codex exec, so streaming typically “feels” like a final chunk rather than a gradual trickle.
+**Future support:** The Codex CLI commit (344d4a1d) introducing experimental JSON explicitly notes: "or other item types like `item.output_delta` when we need streaming" and states "more event types and item types to come."
+
+When OpenAI adds streaming support, this provider will be updated to handle those events and enable true incremental streaming.
 
 ## Documentation
 
@@ -125,9 +187,19 @@ See [docs/ai-sdk-v5/configuration.md](docs/ai-sdk-v5/configuration.md) for the f
 ## Limitations
 
 - Node ≥ 18, local process only (no Edge)
-- Codex JSON mode (`codex exec --json`) suppresses mid‑response deltas; streaming typically yields a final chunk. The CLI writes the final assistant text via `--output-last-message`, which this provider reads and emits at the end.
+- Codex `--experimental-json` mode emits events rather than streaming deltas; streaming typically yields a final chunk. The CLI provides the final assistant text in the `item.completed` event, which this provider reads and emits at the end.
 - Some AI SDK parameters are unsupported by Codex CLI (e.g., temperature/topP/penalties); the provider surfaces warnings and ignores them
 
+### JSON Schema Limitations (v0.2.0+)
+
+**⚠️ Important:** OpenAI strict mode has limitations:
+
+- **Optional fields NOT supported**: All fields must be required (no `.optional()`)
+- **Format validators stripped**: `.email()`, `.url()`, `.uuid()` are removed (use descriptions instead)
+- **Pattern validators stripped**: `.regex()` is removed (use descriptions instead)
+
+See [LIMITATIONS.md](LIMITATIONS.md) for comprehensive details and migration guidance.
+
 ## Disclaimer
 
 This is a community provider and not an official OpenAI or Vercel product. You are responsible for complying with all applicable terms and ensuring safe usage.