@janole/ai-sdk-provider-codex-asp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @janole/ai-sdk-provider-codex-asp
+
+`@janole/ai-sdk-provider-codex-asp` is a [Vercel AI SDK](https://ai-sdk.dev/) v6 custom provider for the Codex App Server Protocol.
+
+Status: POC feature-complete for language model usage.
+
+- `LanguageModelV3` provider implementation
+- Streaming (`streamText`) and non-streaming (`generateText`)
+- Standard AI SDK `tool()` support via Codex dynamic tools injection
+- `stdio` and `websocket` transports
+- Persistent worker pool with thread management
+
+## Installation
+
+```bash
+npm install @janole/ai-sdk-provider-codex-asp ai
+```
+
+## Quick Start
+
+### 1. Non-streaming (`generateText`)
+
+```ts
+import { generateText } from 'ai';
+import { createCodexAppServer } from '@janole/ai-sdk-provider-codex-asp';
+
+const codex = createCodexAppServer({
+  defaultModel: 'gpt-5.3-codex',
+  clientInfo: { name: 'my-app', version: '0.1.0' },
+});
+
+const result = await generateText({
+  model: codex.languageModel('gpt-5.3-codex'),
+  prompt: 'Write a short release note title for websocket support.',
+});
+
+console.log(result.text);
+```
+
+### 2. Streaming (`streamText`)
+
+```ts
+import { streamText } from 'ai';
+import { createCodexAppServer } from '@janole/ai-sdk-provider-codex-asp';
+
+const codex = createCodexAppServer({
+  defaultModel: 'gpt-5.3-codex',
+  clientInfo: { name: 'my-app', version: '0.1.0' },
+});
+
+const result = streamText({
+  model: codex('gpt-5.3-codex'),
+  prompt: 'Explain JSON-RPC in one paragraph.',
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## Tools
+
+Use standard AI SDK `tool()` definitions — the provider automatically injects them into Codex as dynamic tools and routes results back. No Codex-specific API needed.
+
+Requires a persistent transport so tool results can be fed back within the same session:
+
+```ts
+import { stepCountIs, streamText, tool } from 'ai';
+import { z } from 'zod';
+import { createCodexAppServer } from '@janole/ai-sdk-provider-codex-asp';
+
+const codex = createCodexAppServer({
+  persistent: { scope: 'global', poolSize: 1, idleTimeoutMs: 60_000 },
+});
+
+const result = streamText({
+  model: codex('gpt-5.3-codex'),
+  prompt: 'Can you check ticket 15 and also the weather in Berlin?',
+  tools: {
+    lookup_ticket: tool({
+      description: 'Look up the current status of a support ticket by its ID.',
+      inputSchema: z.object({
+        id: z.string().describe('The ticket ID, e.g. "TICK-42".'),
+      }),
+      execute: async ({ id }) => `Ticket ${id} is open and assigned to team Alpha.`,
+    }),
+    check_weather: tool({
+      description: 'Get the current weather for a given location.',
+      inputSchema: z.object({
+        location: z.string().describe('City name or coordinates.'),
+      }),
+      execute: async ({ location }) => `Weather in ${location}: 22°C, sunny`,
+    }),
+  },
+  stopWhen: stepCountIs(5),
+});
+
+for await (const chunk of result.textStream) {
+  process.stdout.write(chunk);
+}
+
+await codex.shutdown();
+```
+
+## API Reference
+
+```ts
+const codex = createCodexAppServer({
+  defaultModel?: string,
+  clientInfo?: { name, version, title? },  // defaults to package.json
+  transport?: { type: 'stdio' | 'websocket', stdio?, websocket? },
+  persistent?: { poolSize?, idleTimeoutMs?, scope?, key? },
+  defaultThreadSettings?: { cwd?, approvalMode?, sandboxMode? },
+  approvals?: { onCommandApproval?, onFileChangeApproval? },
+  toolTimeoutMs?: number,                  // default: 30000
+});
+
+codex(modelId)                // returns a language model instance
+codex.languageModel(modelId)  // explicit alias
+codex.chat(modelId)           // explicit alias
+codex.shutdown()              // clean up persistent workers
+```
+
+See [`src/provider.ts`](src/provider.ts) for full type definitions.
+
+## Examples
+
+See the [`examples/`](examples/) directory:
+
+- [`generate-text.ts`](examples/generate-text.ts) — Non-streaming text generation
+- [`stream-text.ts`](examples/stream-text.ts) — Streaming text generation
+- [`cross-call-tools.ts`](examples/cross-call-tools.ts) — Standard AI SDK tools via Codex
+- [`dynamic-tools.ts`](examples/dynamic-tools.ts) — Provider-level dynamic tools
+- [`thread-continuation.ts`](examples/thread-continuation.ts) — Multi-turn thread resumption
+- [`approvals.ts`](examples/approvals.ts) — Command and file-change approval handling
+
+Run any example with:
+
+```bash
+npx tsx examples/stream-text.ts
+```
+
+## Troubleshooting
+
+- `No such file or command: codex`:
+  - Install Codex CLI and ensure `codex` is in `PATH`.
+- `WebSocket is not available in this runtime`:
+  - Use Node.js 18+ with global WebSocket support, or use `stdio` transport.
+- Request timeouts:
+  - Increase `toolTimeoutMs` for long-running dynamic tools.
+- Empty generated text:
+  - Verify Codex emits `item/agentMessage/delta` and `turn/completed` notifications.
+
+## Development
+
+```bash
+npm install
+npm run build        # ESM + CJS + .d.ts via tsup
+npm run qa           # lint + typecheck + test (all-in-one)
+```
+
+## License
+
+MIT