zidane 1.6.17 → 1.8.0

package/README.md

@@ -10,15 +10,18 @@ Minimal TypeScript agent loop built with [Bun](https://bun.sh). Hook into every
 
 ```bash
 bun install
-bun run auth                                    # Anthropic OAuth
+bun run auth                                    # Anthropic + OpenAI Codex OAuth
 bun start --prompt "create a hello world app"
 ```
 
+`auth` runs both OAuth flows by default. Pass `--openai` or `--anthropic` to authenticate only one provider; the npm script form works too, e.g. `npm run auth --openai`.
+
 ## Agent Setup
 
 ```ts
-import { createAgent, anthropic } from 'zidane'
-import { basic } from 'zidane'
+import { createAgent } from 'zidane'
+import { basic } from 'zidane/harnesses'
+import { anthropic } from 'zidane/providers'
 
 const agent = createAgent({
   provider: anthropic({ apiKey: 'sk-ant-...' }),
@@ -77,7 +80,7 @@ Precedence: `run.behavior` > `agent.behavior` > `harness.behavior` > hardcoded d
 bun start \
   --prompt "your task"    \   # required
   --model claude-opus-4-6 \   # model id
-  --provider anthropic    \   # anthropic | openrouter | cerebras
+  --provider anthropic    \   # anthropic | openai | openrouter | cerebras
   --harness basic         \   # tool set
   --system "be concise"   \   # system prompt
   --thinking off          \   # off | minimal | low | medium | high
@@ -92,10 +95,11 @@ All providers accept runtime credentials via a params object. Env vars are fallb
 ### Anthropic
 
 ```ts
-import { anthropic } from 'zidane'
+import { anthropic } from 'zidane/providers'
 
 anthropic({ apiKey: 'sk-ant-...' })
 anthropic({ access: 'sk-ant-oat-...' })                      // OAuth
+anthropic({ access: 'sk-ant-oat-...', refresh: '...', expires: Date.now() + 3600_000 }) // auto-refresh
 anthropic({ apiKey: '...', defaultModel: 'claude-sonnet-4-6' })
 ```
 
@@ -104,17 +108,31 @@ Fallback: `params.apiKey` > `params.access` > `ANTHROPIC_API_KEY` env > `.creden
 ### OpenRouter
 
 ```ts
-import { openrouter } from 'zidane'
+import { openrouter } from 'zidane/providers'
 
 openrouter({ apiKey: 'sk-or-...', defaultModel: 'google/gemini-pro' })
 ```
 
 Fallback: `params.apiKey` > `OPENROUTER_API_KEY` env
 
+### OpenAI
+
+```ts
+import { openai } from 'zidane/providers'
+
+openai()                                                // OpenAI Codex OAuth
+openai({ access: 'eyJ...', defaultModel: 'gpt-5.4' })
+openai({ access: 'eyJ...', refresh: '...', expires: Date.now() + 3600_000, accountId: 'acct_123' })
+```
+
+Fallback: `params.apiKey` > `params.access` > `OPENAI_CODEX_API_KEY` env > `.credentials.json`
+
+Pass the full OAuth credential fields (`access`, `refresh`, `expires`, plus provider extras like `accountId`) to let the provider auto-refresh tokens without reading `.credentials.json`.
+
 ### Cerebras
 
 ```ts
-import { cerebras } from 'zidane'
+import { cerebras } from 'zidane/providers'
 
 cerebras({ apiKey: 'csk-...', defaultModel: 'zai-glm-4.7' })
 ```
@@ -136,7 +154,7 @@ Tools are grouped into **harnesses**. The `basic` harness includes:
 Define a custom harness:
 
 ```ts
-import { defineHarness, basicTools } from 'zidane'
+import { defineHarness, basicTools } from 'zidane/harnesses'
 
 const harness = defineHarness({
   name: 'researcher',
@@ -221,6 +239,12 @@ agent.hooks.hook('stream:thinking', (ctx) => {
   // ctx.delta, ctx.thinking (accumulated), ctx.turnId
   // Fires when the model streams reasoning traces (Anthropic, OpenRouter)
 })
+
+agent.hooks.hook('oauth:refresh', (ctx) => {
+  // ctx.provider, ctx.providerId, ctx.source
+  // ctx.previousCredentials, ctx.credentials
+  // Fires when an OAuth token is refreshed from passed credentials or .credentials.json
+})
 ```
 
 ### Tool execution
@@ -290,7 +314,8 @@ agent.followUp('now write tests for what you built')
 The `spawn` tool delegates tasks to child agents that run independently.
 
 ```ts
-import { createSpawnTool, defineHarness, basicTools } from 'zidane'
+import { createSpawnTool } from 'zidane/tools'
+import { defineHarness, basicTools } from 'zidane/harnesses'
 
 const harness = defineHarness({
   name: 'orchestrator',
@@ -312,7 +337,8 @@ Children inherit the parent's harness and can spawn their own children.
 Let the agent pause and request structured input from the outside world. Not included in any harness by default.
 
 ```ts
-import { createInteractionTool, defineHarness, basicTools } from 'zidane'
+import { createInteractionTool } from 'zidane/tools'
+import { defineHarness, basicTools } from 'zidane/harnesses'
 
 const askUser = createInteractionTool({
   name: 'ask_user',