zidane 1.5.2 → 1.6.1

package/README.md

@@ -35,11 +35,12 @@ All options on `createAgent`:
 createAgent({
   provider,                          // required: LLM provider
   harness: basic,                    // tool set (default: noTools)
-  enableTools: true,                 // false for pure chat mode
-  toolExecution: 'sequential',       // or 'parallel'
-  maxTurns: 50,                      // max loop iterations
-  maxTokens: 16384,                  // max tokens per LLM response
-  thinkingBudget: 10240,             // exact thinking token budget
+  behavior: {                        // agent-level defaults
+    toolExecution: 'sequential',     // or 'parallel'
+    maxTurns: 50,                    // max loop iterations
+    maxTokens: 16384,               // max tokens per LLM response
+    thinkingBudget: 10240,          // exact thinking token budget
+  },
   execution: createProcessContext(), // where tools run
   mcpServers: [],                    // MCP tool servers
   session,                           // session for persistence
@@ -51,19 +52,22 @@ All options on `agent.run()`:
 
 ```ts
 await agent.run({
-  prompt: 'your task',     // required
+  prompt: 'your task',       // required
   model: 'claude-opus-4-6',
   system: 'be concise',
-  thinking: 'medium',      // off | minimal | low | medium | high
-  thinkingBudget: 8192,    // overrides level-based default
-  maxTurns: 10,            // overrides agent-level default
-  maxTokens: 4096,         // overrides agent-level default
-  images: [],              // base64 images
+  thinking: 'medium',        // off | minimal | low | medium | high
+  behavior: {                // per-run overrides
+    maxTurns: 10,
+    maxTokens: 4096,
+    thinkingBudget: 8192,
+  },
+  tools: {},                 // override tools for this run ({} = no tools)
+  images: [],                // base64 images
   signal: abortController.signal,
 })
 ```
 
-Per-run options override agent-level defaults. Agent-level defaults override hardcoded defaults.
+Precedence: `run.behavior` > `agent.behavior` > `harness.behavior` > hardcoded defaults.
 
 ## CLI
 
@@ -139,10 +143,10 @@ const harness = defineHarness({
 })
 ```
 
-For pure chat with no tools:
+For pure chat with no tools, pass `tools: {}` on a specific run or use the `noTools` harness:
 
 ```ts
-const agent = createAgent({ provider, enableTools: false })
+await agent.run({ prompt: 'just chat', tools: {} })
 ```
 
 ## Thinking
@@ -162,10 +166,10 @@ Extended reasoning with named levels or exact token budgets.
 await agent.run({ prompt: 'solve this', thinking: 'high' })
 
 // Exact budget (overrides level default)
-await agent.run({ prompt: 'solve this', thinking: 'high', thinkingBudget: 50000 })
+await agent.run({ prompt: 'solve this', thinking: 'high', behavior: { thinkingBudget: 50000 } })
 
 // Agent-level default
-const agent = createAgent({ provider, harness, thinkingBudget: 16384 })
+const agent = createAgent({ provider, harness, behavior: { thinkingBudget: 16384 } })
 ```
 
 ## Hooks
@@ -180,12 +184,19 @@ agent.hooks.hook('turn:before', (ctx) => {
 })
 
 agent.hooks.hook('turn:after', (ctx) => {
-  // ctx.turn, ctx.turnId, ctx.usage { input, output }
+  // ctx.turn, ctx.turnId, ctx.usage, ctx.message (full SessionTurn)
   // Always fires — even if the provider throws mid-stream
+  // Turn is guaranteed to be in agent.turns before this fires
+})
+
+agent.hooks.hook('usage', (ctx) => {
+  // ctx.turn, ctx.turnId, ctx.usage (per-turn)
+  // ctx.totalIn, ctx.totalOut (running totals)
 })
 
 agent.hooks.hook('agent:done', (ctx) => {
   // ctx.totalIn, ctx.totalOut, ctx.turns, ctx.elapsed, ctx.children?
+  // ctx.output — structured output (when behavior.schema is set)
   // Fires on all exit paths: completion, maxTurns, and abort
 })
 ```
@@ -329,7 +340,7 @@ if (session) {
 
 ```ts
 agent.hooks.hook('session:start', (ctx) => { /* ctx.sessionId, ctx.runId, ctx.prompt */ })
-agent.hooks.hook('session:end', (ctx) => { /* ctx.sessionId, ctx.runId, ctx.status */ })
+agent.hooks.hook('session:end', (ctx) => { /* ctx.sessionId, ctx.runId, ctx.status, ctx.turnRange */ })
 agent.hooks.hook('session:turns', (ctx) => { /* ctx.sessionId, ctx.count */ })
 ```
 
@@ -449,7 +460,7 @@ const agent = createAgent({
 
 ```ts
 agent.isRunning           // is a run in progress?
-agent.messages            // conversation history
+agent.turns               // conversation history (SessionTurn[])
 agent.abort()             // cancel the current run
 agent.reset()             // clear messages and queues
 await agent.destroy()     // clean up context + MCP connections
@@ -480,6 +491,45 @@ Converters for external interop:
 import { fromAnthropic, toAnthropic, fromOpenAI, toOpenAI, autoDetectAndConvert } from 'zidane'
 ```
 
+## Structured Output
+
+Force the agent's final response to match a JSON Schema via provider-level tool forcing.
+
+```ts
+const stats = await agent.run({
+  prompt: 'Extract the entities',
+  behavior: {
+    schema: {
+      type: 'object',
+      properties: { name: { type: 'string' }, age: { type: 'number' } },
+      required: ['name', 'age'],
+    },
+  },
+})
+
+console.log(stats.output) // { name: 'Alice', age: 30 }
+```
+
+The `output` hook fires when structured output is extracted:
+
+```ts
+agent.hooks.hook('output', (ctx) => {
+  // ctx.output — the parsed JSON matching the schema
+  // ctx.schema — the schema that was enforced
+})
+```
+
+### Zod v4 integration
+
+Use `zodToJsonSchema` to normalize `z.toJsonSchema()` output for tool schemas:
+
+```ts
+import { z } from 'zod'
+import { zodToJsonSchema } from 'zidane'
+
+const schema = zodToJsonSchema(z.toJsonSchema(z.object({ name: z.string() })))
+```
+
 ## Usage Tracking
 
 ```ts
@@ -488,13 +538,21 @@ stats.turnUsage   // TurnUsage[] — per-turn { input, output, cacheCreation?, c
 stats.cost        // total USD cost (if reported by provider)
 ```
 
+## Types
+
+All types are available from `zidane/types`:
+
+```ts
+import type { Agent, SessionTurn, TurnUsage, Provider, ToolDef } from 'zidane/types'
+```
+
 ## Testing
 
 ```bash
 bun test
 ```
 
-430+ tests with mock provider and execution context. No API keys or Docker needed.
+460+ tests with mock provider and execution context. No API keys or Docker needed.
 
 ## License