ai-sdk-provider-codex-cli 1.3.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +62 -49
- package/dist/index.d.ts +156 -27
- package/dist/index.js +412 -150
- package/package.json +10 -16
- package/dist/index.cjs +0 -5858
- package/dist/index.d.cts +0 -806
package/README.md
CHANGED
|
@@ -3,14 +3,14 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/ai-sdk-provider-codex-cli)
|
|
4
4
|
[](https://www.npmjs.com/package/ai-sdk-provider-codex-cli)
|
|
5
5
|
[](LICENSE)
|
|
6
|
-
|
|
7
|
+
|
|
8
|
+
|
|
9
9
|
|
|
10
10
|
[](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/issues)
|
|
11
11
|
[](https://github.com/ben-vargas/ai-sdk-provider-codex-cli/releases/latest)
|
|
12
12
|
|
|
13
|
-
A community provider for Vercel AI SDK
|
|
13
|
+
A community provider for Vercel AI SDK v7 that integrates OpenAI's Codex CLI (for example `gpt-5.5`) using your ChatGPT Plus/Pro subscription. Available model slugs follow whatever your installed Codex CLI exposes — use `listModels()` / `provider.listModels()` to discover them.
|
|
14
14
|
|
|
15
15
|
This package ships two provider modes:
|
|
16
16
|
|
|
@@ -20,20 +20,22 @@ This package ships two provider modes:
|
|
|
20
20
|
- Works with `generateText`, `streamText`, and `generateObject`
|
|
21
21
|
- Uses ChatGPT OAuth from `codex login` (tokens in `~/.codex/auth.json`) or `OPENAI_API_KEY`
|
|
22
22
|
- Node-only (spawns a local process); supports CI and local dev
|
|
23
|
-
-
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
23
|
+
- Requires Node.js >= 22; published as an ESM-only package
|
|
24
|
+
- **v2.0.0**: AI SDK v7 migration with the native LanguageModelV4 provider spec (package line 2.x)
|
|
25
|
+
- **v1.0.0**: AI SDK v6 migration with the LanguageModelV3 interface (now on the `ai-sdk-v6` tag)
|
|
26
26
|
|
|
27
27
|
## Version Compatibility
|
|
28
28
|
|
|
29
|
-
|
|
|
30
|
-
|
|
|
31
|
-
|
|
|
32
|
-
|
|
|
29
|
+
| Package line | AI SDK | npm tag | Git branch | Status |
|
|
30
|
+
| ----------------- | ------ | --------------------- | ----------- | ---------------------------- |
|
|
31
|
+
| 2.x | v7 | `latest`, `ai-sdk-v7` | `main` | Active development |
|
|
32
|
+
| 1.x | v6 | `ai-sdk-v6` | `ai-sdk-v6` | Maintenance |
|
|
33
|
+
| 0.7.x | v5 | `ai-sdk-v5` | `ai-sdk-v5` | Maintenance / critical fixes |
|
|
34
|
+
| `0.1.0-ai-sdk-v4` | v4 | `ai-sdk-v4` | `ai-sdk-v4` | Frozen |
|
|
33
35
|
|
|
34
36
|
## Installation
|
|
35
37
|
|
|
36
|
-
### For AI SDK
|
|
38
|
+
### For AI SDK v7 (default)
|
|
37
39
|
|
|
38
40
|
1. Install and authenticate Codex CLI
|
|
39
41
|
|
|
@@ -42,19 +44,27 @@ npm i -g @openai/codex
|
|
|
42
44
|
codex login # or set OPENAI_API_KEY
|
|
43
45
|
```
|
|
44
46
|
|
|
45
|
-
2. Install provider and AI SDK
|
|
47
|
+
2. Install provider and AI SDK v7
|
|
46
48
|
|
|
47
49
|
```bash
|
|
48
50
|
npm i ai ai-sdk-provider-codex-cli
|
|
49
51
|
```
|
|
50
52
|
|
|
53
|
+
> **Requirements:** Node.js >= 22. This package is ESM-only (no CommonJS build); load it with `import` (or dynamic `import()` from CJS).
|
|
54
|
+
|
|
55
|
+
### For AI SDK v6
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npm i ai@^6 ai-sdk-provider-codex-cli@ai-sdk-v6
|
|
59
|
+
```
|
|
60
|
+
|
|
51
61
|
### For AI SDK v5
|
|
52
62
|
|
|
53
63
|
```bash
|
|
54
64
|
npm i ai@^5.0.0 ai-sdk-provider-codex-cli@ai-sdk-v5
|
|
55
65
|
```
|
|
56
66
|
|
|
57
|
-
> **⚠️ Codex CLI Version**: Requires the current stable Codex CLI **0.
|
|
67
|
+
> **⚠️ Codex CLI Version**: Requires the current stable Codex CLI **0.142.x** for full support of both provider modes (`codexExec` and `codexAppServer`). This package pins its optional `@openai/codex` dependency to `^0.142.5`, the latest non-alpha release validated for this release line. If you supply your own Codex CLI (global install or custom `codexPath`), check it with `codex --version` and upgrade if needed.
|
|
58
68
|
>
|
|
59
69
|
> ```bash
|
|
60
70
|
> npm i -g @openai/codex@latest
|
|
@@ -90,7 +100,7 @@ import { createCodexAppServer } from 'ai-sdk-provider-codex-cli';
|
|
|
90
100
|
|
|
91
101
|
const provider = createCodexAppServer({
|
|
92
102
|
defaultSettings: {
|
|
93
|
-
minCodexVersion: '0.
|
|
103
|
+
minCodexVersion: '0.142.5',
|
|
94
104
|
autoApprove: false,
|
|
95
105
|
personality: 'pragmatic',
|
|
96
106
|
},
|
|
@@ -123,7 +133,7 @@ const first = await generateText({
|
|
|
123
133
|
},
|
|
124
134
|
});
|
|
125
135
|
|
|
126
|
-
const threadId = first.providerMetadata?.['codex-app-server']?.threadId;
|
|
136
|
+
const threadId = first.finalStep.providerMetadata?.['codex-app-server']?.threadId;
|
|
127
137
|
|
|
128
138
|
const second = await generateText({
|
|
129
139
|
model: provider('gpt-5.5'),
|
|
@@ -154,20 +164,21 @@ console.log(object);
|
|
|
154
164
|
|
|
155
165
|
## Features
|
|
156
166
|
|
|
157
|
-
- AI SDK
|
|
167
|
+
- AI SDK v7 compatible (native LanguageModelV4 provider spec)
|
|
158
168
|
- Dual provider architecture:
|
|
159
169
|
- `codexExec` / `createCodexExec` for `codex exec`
|
|
160
170
|
- `codexAppServer` / `createCodexAppServer` for `codex app-server`
|
|
161
171
|
- Backward-compatible aliases: `codexCli` / `createCodexCli` map to exec mode
|
|
172
|
+
- Model discovery via `listModels()` / `provider.listModels()` — available slugs follow your installed Codex CLI
|
|
162
173
|
- Streaming and non‑streaming
|
|
163
|
-
- **Configurable logging**
|
|
164
|
-
- **Tool streaming support**
|
|
165
|
-
- **Native JSON Schema support** via `--output-schema` (
|
|
174
|
+
- **Configurable logging** - Verbose mode, custom loggers, or silent operation
|
|
175
|
+
- **Tool streaming support** - Monitor autonomous tool execution in real-time
|
|
176
|
+
- **Native JSON Schema support** via `--output-schema` (exec) / the `outputSchema` turn parameter (app-server)
|
|
166
177
|
- JSON object generation with Zod schemas (100-200 fewer tokens per request vs prompt engineering)
|
|
167
178
|
- Safe defaults for non‑interactive automation (`on-failure`, `workspace-write`, `--skip-git-repo-check`)
|
|
168
|
-
- Fallback to `npx @openai/codex` when
|
|
179
|
+
- Fallback to `npx -y @openai/codex` when the local `@openai/codex` package can't be resolved (`allowNpx`)
|
|
169
180
|
- Usage tracking from experimental JSON event format
|
|
170
|
-
- **Image support** - Local binary images in both providers
|
|
181
|
+
- **Image support** - Local binary images in both providers; remote HTTP/HTTPS image URLs work via AI SDK download
|
|
171
182
|
|
|
172
183
|
### Image Support
|
|
173
184
|
|
|
@@ -188,7 +199,7 @@ const { text } = await generateText({
|
|
|
188
199
|
role: 'user',
|
|
189
200
|
content: [
|
|
190
201
|
{ type: 'text', text: 'What do you see in this image?' },
|
|
191
|
-
{ type: '
|
|
202
|
+
{ type: 'file', data: imageBuffer, mediaType: 'image/png' },
|
|
192
203
|
],
|
|
193
204
|
},
|
|
194
205
|
],
|
|
@@ -204,14 +215,15 @@ console.log(text);
|
|
|
204
215
|
|
|
205
216
|
**Remote image URLs:**
|
|
206
217
|
|
|
207
|
-
- `
|
|
208
|
-
- `
|
|
218
|
+
- Pass remote images as `{ type: 'file', data: new URL('https://...'), mediaType: 'image/png' }` message parts in either mode
|
|
219
|
+
- Both providers declare `supportedUrls = {}`, so the AI SDK downloads the URL itself and hands the provider the bytes, which flow through the same temp-file path as local images
|
|
220
|
+
- Raw URL shapes that bypass the AI SDK's download step are warned and skipped in exec mode; app-server mode forwards them to Codex as-is, but the SDK download route above is the supported path
|
|
209
221
|
|
|
210
222
|
Local image data is written to temporary files and passed to Codex CLI via `--image` (or app-server `localImage`). Temp files are automatically cleaned up after each request.
|
|
211
223
|
|
|
212
224
|
See [examples/exec/image-support.mjs](examples/exec/image-support.mjs) and [examples/app-server/image-support.mjs](examples/app-server/image-support.mjs) for complete working examples.
|
|
213
225
|
|
|
214
|
-
### Tool Streaming
|
|
226
|
+
### Tool Streaming
|
|
215
227
|
|
|
216
228
|
The provider supports comprehensive tool streaming, enabling real-time monitoring of Codex CLI's autonomous tool execution:
|
|
217
229
|
|
|
@@ -224,12 +236,12 @@ const result = await streamText({
|
|
|
224
236
|
prompt: 'List files and count lines in the largest one',
|
|
225
237
|
});
|
|
226
238
|
|
|
227
|
-
for await (const part of result.
|
|
239
|
+
for await (const part of result.stream) {
|
|
228
240
|
if (part.type === 'tool-call') {
|
|
229
241
|
console.log('🔧 Tool:', part.toolName);
|
|
230
242
|
}
|
|
231
243
|
if (part.type === 'tool-result') {
|
|
232
|
-
console.log('✅ Result:', part.
|
|
244
|
+
console.log('✅ Result:', part.output);
|
|
233
245
|
}
|
|
234
246
|
}
|
|
235
247
|
```
|
|
@@ -244,11 +256,11 @@ for await (const part of result.fullStream) {
|
|
|
244
256
|
**Current behavior:**
|
|
245
257
|
|
|
246
258
|
- `codexExec`: tool outputs are delivered in final `tool-result` events.
|
|
247
|
-
- `codexAppServer`: when Codex emits tool output delta notifications, the provider surfaces `tool-result` parts
|
|
259
|
+
- `codexAppServer`: when Codex emits tool output delta notifications, the provider surfaces `tool-result` parts whose `output.type === 'output-delta'` during streaming.
|
|
248
260
|
|
|
249
261
|
See `examples/exec/streaming-tool-calls.mjs`, `examples/exec/streaming-multiple-tools.mjs`, and their app-server counterparts under `examples/app-server/`.
|
|
250
262
|
|
|
251
|
-
### Logging Configuration
|
|
263
|
+
### Logging Configuration
|
|
252
264
|
|
|
253
265
|
Control logging verbosity and integrate with your observability stack:
|
|
254
266
|
|
|
@@ -298,7 +310,7 @@ const silentModel = codexExec('gpt-5.5', {
|
|
|
298
310
|
|
|
299
311
|
**Default Logger:** Adds level tags `[DEBUG]`, `[INFO]`, `[WARN]`, `[ERROR]` to console output. Use a custom logger or `logger: false` if you need different formatting.
|
|
300
312
|
|
|
301
|
-
See `examples/exec/logging-*.mjs` and `examples/app-server/logging-*.mjs` for complete examples, and [docs/ai-sdk-
|
|
313
|
+
See `examples/exec/logging-*.mjs` and `examples/app-server/logging-*.mjs` for complete examples, and [docs/ai-sdk-v7/guide.md](docs/ai-sdk-v7/guide.md) for detailed configuration.
|
|
302
314
|
|
|
303
315
|
### Text Streaming behavior
|
|
304
316
|
|
|
@@ -319,11 +331,11 @@ When OpenAI adds streaming support to `codex exec --experimental-json`, this pro
|
|
|
319
331
|
## Documentation
|
|
320
332
|
|
|
321
333
|
- Getting started, configuration, and troubleshooting live in `docs/`:
|
|
322
|
-
- [docs/ai-sdk-
|
|
323
|
-
- [docs/ai-sdk-
|
|
324
|
-
- [docs/ai-sdk-
|
|
325
|
-
- [docs/ai-sdk-
|
|
326
|
-
- [docs/ai-sdk-
|
|
334
|
+
- [docs/ai-sdk-v7/guide.md](docs/ai-sdk-v7/guide.md) – full usage guide and examples
|
|
335
|
+
- [docs/ai-sdk-v7/configuration.md](docs/ai-sdk-v7/configuration.md) – all settings and how they map to CLI flags
|
|
336
|
+
- [docs/ai-sdk-v7/troubleshooting.md](docs/ai-sdk-v7/troubleshooting.md) – common issues and fixes
|
|
337
|
+
- [docs/ai-sdk-v7/limitations.md](docs/ai-sdk-v7/limitations.md) – known constraints and behavior differences
|
|
338
|
+
- [docs/ai-sdk-v7/migration-v6-to-v7.md](docs/ai-sdk-v7/migration-v6-to-v7.md) – migrating from the 1.x (AI SDK v6) package line
|
|
327
339
|
- See [examples/](examples/) for runnable scripts covering core usage, streaming, permissions/sandboxing, and object generation.
|
|
328
340
|
- Validation helpers:
|
|
329
341
|
- `npm run validate:docs` checks markdown links and example command paths
|
|
@@ -337,21 +349,21 @@ When OpenAI adds streaming support to `codex exec --experimental-json`, this pro
|
|
|
337
349
|
|
|
338
350
|
## Configuration (high level)
|
|
339
351
|
|
|
340
|
-
- `allowNpx`:
|
|
352
|
+
- `allowNpx`: The provider prefers the locally installed `@openai/codex` package; when it can't be resolved, `allowNpx: true` falls back to `npx -y @openai/codex` (otherwise a `codex` binary on PATH is used)
|
|
341
353
|
- `cwd`: Working directory for Codex
|
|
342
354
|
- `addDirs`: Extra directories Codex may read/write (repeats `--add-dir`)
|
|
343
355
|
- Autonomy/sandbox:
|
|
344
356
|
- `fullAuto` (equivalent to `--full-auto`)
|
|
345
357
|
- `dangerouslyBypassApprovalsAndSandbox` (bypass approvals and sandbox; dangerous)
|
|
346
358
|
- Otherwise the provider writes `-c approval_policy=...` and `-c sandbox_mode=...` for you; defaults to `on-failure` and `workspace-write`
|
|
347
|
-
- `skipGitRepoCheck`:
|
|
359
|
+
- `skipGitRepoCheck`: on by default (pass `false` to keep Codex's git-repo check for CI/non‑repo safety)
|
|
348
360
|
- `color`: `always` | `never` | `auto`
|
|
349
361
|
- `outputLastMessageFile`: by default the provider sets a temp path and reads it to capture final text reliably
|
|
350
|
-
- Logging
|
|
362
|
+
- Logging:
|
|
351
363
|
- `verbose`: Enable debug/info logs (default: `false` for clean output)
|
|
352
364
|
- `logger`: Custom logger object or `false` to disable all logging
|
|
353
365
|
|
|
354
|
-
See [docs/ai-sdk-
|
|
366
|
+
See [docs/ai-sdk-v7/configuration.md](docs/ai-sdk-v7/configuration.md) for the full list and examples.
|
|
355
367
|
|
|
356
368
|
### App-server settings highlights
|
|
357
369
|
|
|
@@ -361,7 +373,7 @@ See [docs/ai-sdk-v5/configuration.md](docs/ai-sdk-v5/configuration.md) for the f
|
|
|
361
373
|
- `requestTimeoutMs`: default per-request JSON-RPC timeout
|
|
362
374
|
- `idleTimeoutMs`: close idle app-server process after inactivity
|
|
363
375
|
- `minCodexVersion`: minimum supported app-server version (semver)
|
|
364
|
-
- `includeRawChunks`: emit raw JSON-RPC notifications as `raw` stream parts by default
|
|
376
|
+
- `includeRawChunks`: emit raw JSON-RPC notifications as `raw` stream parts by default (per call, prefer the standard AI SDK v7 option `include: { rawChunks: true }` on `streamText`)
|
|
365
377
|
- `serverRequests`: typed handlers for server-initiated JSON-RPC requests
|
|
366
378
|
- `autoApprove`: default approval response when no custom handler is provided (covers command execution, file changes, skills, and MCP tool call approvals via `mcpServer/elicitation/request` on Codex >= 0.139)
|
|
367
379
|
- `persistExtendedHistory`: request extended thread history persistence
|
|
@@ -369,7 +381,7 @@ See [docs/ai-sdk-v5/configuration.md](docs/ai-sdk-v5/configuration.md) for the f
|
|
|
369
381
|
- `resume`: shorthand to resume an existing thread id
|
|
370
382
|
- `onSessionCreated`: receive a session object for `injectMessage()` / `interrupt()`
|
|
371
383
|
|
|
372
|
-
Per-call app-server overrides use `providerOptions['codex-app-server']` (for example `threadId`, `threadMode`, `includeRawChunks`, `personality`, `approvalPolicy`, `sandboxPolicy`, `serverRequests`, `configOverrides`).
|
|
384
|
+
Per-call app-server overrides use `providerOptions['codex-app-server']` (for example `threadId`, `threadMode`, `includeRawChunks`, `personality`, `approvalPolicy`, `sandboxPolicy`, `serverRequests`, `configOverrides`). Raw chunk emission can also be requested per call with the standard AI SDK v7 option `include: { rawChunks: true }`.
|
|
373
385
|
|
|
374
386
|
Additional app-server helpers:
|
|
375
387
|
|
|
@@ -384,7 +396,7 @@ Local MCP security defaults:
|
|
|
384
396
|
- Without `cacheKey`, SDK MCP server/tool function identity participates in persistent keying to avoid conflating closure-dependent tool behavior.
|
|
385
397
|
- Use `createSdkMcpServer({ cacheKey })` when you intentionally recreate equivalent SDK MCP definitions per call and want stable persistent model reuse.
|
|
386
398
|
|
|
387
|
-
## Model Parameters & Advanced Options
|
|
399
|
+
## Model Parameters & Advanced Options
|
|
388
400
|
|
|
389
401
|
Control reasoning effort, verbosity, and advanced Codex features at model creation time:
|
|
390
402
|
|
|
@@ -436,7 +448,7 @@ Nested override objects are flattened to dotted keys (e.g., the example above em
|
|
|
436
448
|
`-c sandbox_workspace_write.network_access=true`). Arrays are serialized to JSON strings.
|
|
437
449
|
MCP server env/header objects flatten the same way (e.g., `mcp_servers.docs.http_headers.x-tenant=acme`).
|
|
438
450
|
|
|
439
|
-
### Per-call overrides via `providerOptions`
|
|
451
|
+
### Per-call overrides via `providerOptions`
|
|
440
452
|
|
|
441
453
|
Override these parameters for individual AI SDK calls using the `providerOptions` map. Per-call
|
|
442
454
|
values take precedence over constructor defaults while leaving other settings intact.
|
|
@@ -475,7 +487,9 @@ const response = await generateText({
|
|
|
475
487
|
});
|
|
476
488
|
```
|
|
477
489
|
|
|
478
|
-
**Precedence:** `providerOptions['codex-cli']` > constructor `CodexCliSettings` > Codex CLI defaults.
|
|
490
|
+
**Precedence:** `providerOptions['codex-cli']` > top-level `reasoning` call option > constructor `CodexCliSettings` > Codex CLI defaults.
|
|
491
|
+
|
|
492
|
+
The AI SDK v7 top-level `reasoning` option (`'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'`) maps directly to Codex reasoning effort in both provider modes; provider-specific effort options (`reasoningEffort` for exec, `effort` for app-server) win when both are set, and `'provider-default'` leaves your configured default untouched.
|
|
479
493
|
|
|
480
494
|
App-server per-call overrides use `providerOptions['codex-app-server']`:
|
|
481
495
|
|
|
@@ -499,16 +513,15 @@ const response = await generateText({
|
|
|
499
513
|
|
|
500
514
|
## Zod Compatibility
|
|
501
515
|
|
|
502
|
-
- Peer
|
|
503
|
-
- Validation logic normalizes v3/v4 error shapes
|
|
516
|
+
- Peer dependency: `zod@^4.1.8` (Zod 4 only; Zod 3 is not supported)
|
|
504
517
|
|
|
505
518
|
## Limitations
|
|
506
519
|
|
|
507
|
-
- Node ≥
|
|
520
|
+
- Node ≥ 22, ESM-only, local process only (no Edge)
|
|
508
521
|
- 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.
|
|
509
522
|
- Some AI SDK parameters are unsupported by Codex CLI (e.g., temperature/topP/penalties); the provider surfaces warnings and ignores them
|
|
510
523
|
|
|
511
|
-
### JSON Schema Limitations
|
|
524
|
+
### JSON Schema Limitations
|
|
512
525
|
|
|
513
526
|
**⚠️ Important:** OpenAI strict mode has limitations:
|
|
514
527
|
|