ai-sdk-provider-codex-cli 0.2.0 → 0.4.0

package/README.md

@@ -15,6 +15,7 @@ A community provider for Vercel AI SDK v5 that uses OpenAI’s Codex CLI (non‑
 - 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
@@ -26,7 +27,7 @@ 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. Check your version with `codex --version` and upgrade if needed:
+> **⚠️ 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
@@ -95,19 +96,53 @@ console.log(object);
 
 - AI SDK v5 compatible (LanguageModelV2)
 - Streaming and non‑streaming
+- **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
 
-### Streaming behavior
+### 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)
 
 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.
 
 **What this means:**
+
 - `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
@@ -144,6 +179,73 @@ When OpenAI adds streaming support, this provider will be updated to handle thos
 
 See [docs/ai-sdk-v5/configuration.md](docs/ai-sdk-v5/configuration.md) for the full list and examples.
 
+## Model Parameters & Advanced Options (v0.4.0+)
+
+Control reasoning effort, verbosity, and advanced Codex features at model creation time:
+
+```ts
+import { codexCli } from 'ai-sdk-provider-codex-cli';
+
+const model = codexCli('gpt-5-codex', {
+  allowNpx: true,
+  skipGitRepoCheck: true,
+
+  // Reasoning & verbosity
+  reasoningEffort: 'medium', // minimal | low | medium | high
+  reasoningSummary: 'auto', // auto | detailed (Note: 'concise' and 'none' are rejected by API)
+  reasoningSummaryFormat: 'none', // none | experimental
+  modelVerbosity: 'high', // low | medium | high
+
+  // Advanced features
+  includePlanTool: true, // adds --include-plan-tool
+  profile: 'production', // adds --profile production
+  oss: false, // adds --oss when true
+  webSearch: true, // maps to -c tools.web_search=true
+
+  // Generic overrides (maps to -c key=value)
+  configOverrides: {
+    experimental_resume: '/tmp/session.jsonl',
+    sandbox_workspace_write: { network_access: true },
+  },
+});
+```
+
+Nested override objects are flattened to dotted keys (e.g., the example above emits
+`-c sandbox_workspace_write.network_access=true`). Arrays are serialized to JSON strings.
+
+### Per-call overrides via `providerOptions` (v0.4.0+)
+
+Override these parameters for individual AI SDK calls using the `providerOptions` map. Per-call
+values take precedence over constructor defaults while leaving other settings intact.
+
+```ts
+import { generateText } from 'ai';
+import { codexCli } from 'ai-sdk-provider-codex-cli';
+
+const model = codexCli('gpt-5-codex', {
+  allowNpx: true,
+  reasoningEffort: 'medium',
+  modelVerbosity: 'medium',
+});
+
+const response = await generateText({
+  model,
+  prompt: 'Summarize the latest release notes.',
+  providerOptions: {
+    'codex-cli': {
+      reasoningEffort: 'high',
+      reasoningSummary: 'detailed',
+      textVerbosity: 'high', // AI SDK naming; maps to model_verbosity
+      configOverrides: {
+        experimental_resume: '/tmp/resume.jsonl',
+      },
+    },
+  },
+});
+```
+
+**Precedence:** `providerOptions['codex-cli']` > constructor `CodexCliSettings` > Codex CLI defaults.
+
 ## Zod Compatibility
 
 - Peer supports `zod@^3 || ^4`