zidane 2.0.1 → 2.2.0

package/README.md

@@ -20,12 +20,12 @@ bun start --prompt "create a hello world app"
 
 ```ts
 import { createAgent } from 'zidane'
-import { basic } from 'zidane/harnesses'
+import { basic } from 'zidane/presets'
 import { anthropic } from 'zidane/providers'
 
 const agent = createAgent({
+  ...basic,
   provider: anthropic({ apiKey: 'sk-ant-...' }),
-  harness: basic,
 })
 
 const stats = await agent.run({ prompt: 'build a REST API' })
@@ -37,8 +37,11 @@ All options on `createAgent`:
 ```ts
 createAgent({
   provider,                          // required: LLM provider
+  name: 'basic',                     // optional display name (shown in traces/logs)
+  system: 'You are a helpful...',    // default system prompt
+  tools: { shell, readFile },        // tool set (default: no tools)
+  toolAliases: { shell: 'Bash' },    // map canonical names to LLM-facing names
   session,                           // session for persistence
-  harness: basic,                    // tool set (default: noTools)
   behavior: {                        // agent-level defaults
     toolExecution: 'parallel',       // or 'sequential' (default: parallel)
     maxTurns: 50,                    // max loop iterations
@@ -51,6 +54,12 @@ createAgent({
 })
 ```
 
+Presets are just `Partial<AgentOptions>` — spread them in, override any field:
+
+```ts
+createAgent({ ...basic, provider, system: 'be concise' })
+```
+
 All options on `agent.run()`:
 
 ```ts
@@ -72,7 +81,7 @@ await agent.run({
 
 `prompt` is optional when a session with existing turns is provided — the agent resumes from the last turn. This supports apps where the user message is persisted to the session before the agent runs (e.g. WebSocket → session → queue → agent).
 
-Precedence: `run.behavior` > `agent.behavior` > `harness.behavior` > hardcoded defaults.
+Precedence: `run.behavior` > `agent.behavior` > hardcoded defaults.
 
 ## CLI
 
@@ -81,7 +90,7 @@ bun start \
   --prompt "your task"    \   # required
   --model claude-opus-4-6 \   # model id
   --provider anthropic    \   # anthropic | openai | openrouter | cerebras
-  --harness basic         \   # tool set
+  --preset basic          \   # preset name
   --system "be concise"   \   # system prompt
   --thinking off          \   # off | minimal | low | medium | high
   --context process       \   # process | docker
@@ -139,9 +148,11 @@ cerebras({ apiKey: 'csk-...', defaultModel: 'zai-glm-4.7' })
 
 Fallback: `params.apiKey` > `CEREBRAS_API_KEY` env
 
-## Harnesses
+## Presets
+
+Reusable slices of `AgentOptions` — spread them into `createAgent()`.
 
-Tools are grouped into **harnesses**. The `basic` harness includes:
+The `basic` preset bundles:
 
 | Tool | Description |
 |---|---|
@@ -151,22 +162,25 @@ Tools are grouped into **harnesses**. The `basic` harness includes:
 | `list_files` | List directory contents |
 | `spawn` | Spawn a sub-agent |
 
-Define a custom harness:
+Define a custom preset:
 
 ```ts
-import { defineHarness, basicTools } from 'zidane/harnesses'
+import { basicTools, definePreset } from 'zidane/presets'
 
-const harness = defineHarness({
+const researcher = definePreset({
   name: 'researcher',
   system: 'You are a research assistant.',
   tools: { ...basicTools },
 })
+
+createAgent({ ...researcher, provider })
 ```
 
-For pure chat with no tools, pass `tools: {}` on a specific run or use the `noTools` harness:
+For pure chat with no tools, omit `tools` or pass `{}` at run time:
 
 ```ts
-await agent.run({ prompt: 'just chat', tools: {} })
+createAgent({ provider })                                 // no tools
+await agent.run({ prompt: 'just chat', tools: {} })       // override for one run
 ```
 
 ## Thinking
@@ -189,7 +203,7 @@ await agent.run({ prompt: 'solve this', thinking: 'high' })
 await agent.run({ prompt: 'solve this', thinking: 'high', behavior: { thinkingBudget: 50000 } })
 
 // Agent-level default
-const agent = createAgent({ provider, harness, behavior: { thinkingBudget: 16384 } })
+const agent = createAgent({ ...basic, provider, behavior: { thinkingBudget: 16384 } })
 ```
 
 Thinking traces are stored in session turns as `{ type: 'thinking', text }` content blocks and streamed live via the `stream:thinking` hook. Supported by Anthropic (native) and OpenRouter/Cerebras (`reasoning_content`/`reasoning` SSE fields).
@@ -314,10 +328,10 @@ agent.followUp('now write tests for what you built')
 The `spawn` tool delegates tasks to child agents that run independently.
 
 ```ts
+import { basicTools, definePreset } from 'zidane/presets'
 import { createSpawnTool } from 'zidane/tools'
-import { defineHarness, basicTools } from 'zidane/harnesses'
 
-const harness = defineHarness({
+const orchestrator = definePreset({
   name: 'orchestrator',
   tools: {
     ...basicTools,
@@ -330,15 +344,15 @@ const harness = defineHarness({
 })
 ```
 
-Children inherit the parent's harness and can spawn their own children.
+Children inherit the parent's preset (tools, system prompt, aliases, MCP servers, skills, behavior) and can spawn their own children. Pass `preset` on `createSpawnTool()` to override the inherited slice per child.
 
 ## Interaction Tool
 
-Let the agent pause and request structured input from the outside world. Not included in any harness by default.
+Let the agent pause and request structured input from the outside world. Not included in any preset by default.
 
 ```ts
+import { basicTools, definePreset } from 'zidane/presets'
 import { createInteractionTool } from 'zidane/tools'
-import { defineHarness, basicTools } from 'zidane/harnesses'
 
 const askUser = createInteractionTool({
   name: 'ask_user',
@@ -353,7 +367,7 @@ const askUser = createInteractionTool({
   },
 })
 
-const harness = defineHarness({
+const interactive = definePreset({
   name: 'interactive',
   tools: { ...basicTools, ask_user: askUser },
 })
@@ -371,7 +385,7 @@ import { createAgent, createSession, createSqliteStore } from 'zidane'
 const store = createSqliteStore({ path: './sessions.db' })
 const session = await createSession({ store })
 
-const agent = createAgent({ harness, provider, session })
+const agent = createAgent({ ...basic, provider, session })
 await agent.run({ prompt: 'hello' })
 await session.save()
 ```
@@ -395,7 +409,7 @@ import { loadSession } from 'zidane/session'
 
 const session = await loadSession(store, 'my-session')
 if (session) {
-  const agent = createAgent({ harness, provider, session })
+  const agent = createAgent({ ...basic, provider, session })
   await agent.run({ prompt: 'continue' })
 }
 ```
@@ -414,7 +428,7 @@ Connect any MCP-compatible tool server. Tools are namespaced as `mcp_{server}_{t
 
 ```ts
 const agent = createAgent({
-  harness,
+  ...basic,
   provider,
   mcpServers: [
     { name: 'fs', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
@@ -423,7 +437,7 @@ const agent = createAgent({
 })
 ```
 
-MCP servers can also be declared on the harness. Connections are lazy (first `run()`) and reused.
+MCP servers can live on a preset too (they're just `AgentOptions` fields). Connections are lazy (first `run()`) and reused.
 
 ## Skills
 
@@ -467,7 +481,7 @@ Scan paths in priority order (first found wins):
 import { createAgent, defineSkill } from 'zidane'
 
 const agent = createAgent({
-  harness,
+  ...basic,
   provider,
   skills: {
     scan: ['./custom-skills'],
@@ -496,7 +510,7 @@ An execution context defines **where** tools run. Defaults to in-process.
 import { createAgent, createDockerContext } from 'zidane'
 
 const agent = createAgent({
-  harness,
+  ...basic,
   provider,
   execution: createDockerContext({
     image: 'node:22',
@@ -514,7 +528,7 @@ Implement `SandboxProvider` for your provider (E2B, Rivet, etc.):
 import { createAgent, createSandboxContext } from 'zidane'
 
 const agent = createAgent({
-  harness,
+  ...basic,
   provider,
   execution: createSandboxContext(myProvider),
 })