zidane 5.9.12 → 5.9.13

package/README.md

@@ -18,7 +18,7 @@ Small, hookable core with sensible defaults. Three principles guide the design:
 
 Everything below is in service of those:
 
-- 🧠 **Providers** — Anthropic, OpenAI Codex, OpenRouter, Cerebras, plus `openaiCompat` (Baseten, Fireworks, Groq, local). OAuth + API key with auto-refresh.
+- 🧠 **Providers** — Anthropic, OpenAI Codex, OpenRouter, Cerebras, Arcee, local LLMs, plus `openaiCompat` (Baseten, Fireworks, Groq). OAuth + API key with auto-refresh.
 - 🪝 **Hookable turn loop** — every text/thinking delta, tool call, MCP, session, skill, spawn, OAuth, validation, and budget event is observable and (mostly) mutable.
 - 🛠️ **First-class tools** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Per-call gates, arg auto-coerce, hallucinated-tool fallback, error rewriting. Lazy MCP disclosure via `tool_search`. Optional `todowrite` / `todoread` for persistent task checkpointing across prompts.
 - 🧮 **Per-tool concurrency** — every `ToolDef` carries `isConcurrencySafe` (default `false`); the dispatcher fans safe siblings out in parallel and barriers unsafe ones. Order is preserved at yield time. Cap via `behavior.maxConcurrentTools`.
@@ -121,7 +121,9 @@ Precedence: `run.behavior` > `agent.behavior` > defaults.
 bun start \
   --prompt "your task"    \   # required
   --model claude-opus-4-7 \   # model id
-  --provider anthropic    \   # anthropic | openai | openrouter | cerebras
+  --provider anthropic    \   # anthropic | openai | openrouter | cerebras | arcee | local | openai-compat
+  --base-url http://localhost:8000/v1 \ # local/openai-compat endpoint
+  --header "X-Route: dev" \ # extra header for local/openai-compat
   --preset basic          \   # preset name
   --system "be concise"   \   # system prompt
   --thinking off          \   # off | minimal | low | medium | high
@@ -129,6 +131,8 @@ bun start \
   --mcp '{"name":"fs","transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}'
 ```
 
+For `local` / `openai-compat`, `--base-url`, `--api-key-env`, `--headers-env`, `--header`, `--vision`, `--image-in-tool-result`, `--temperature`, and `--seed` apply; hosted providers ignore them.
+
 `bun start --restate` runs the same start flow through a local Restate endpoint for durable-execution demos and fixture testing. It starts the service, probes readiness, registers the deployment, invokes `zidane-start-agent`, and exposes `run` / `status` / `history` handlers. See [docs/RESTATE.md](./docs/RESTATE.md) for production wiring and the advanced ReState flags.
 
 ## Providers
@@ -164,20 +168,22 @@ anthropic({
 
 Fallback: `params.apiKey` > `params.access` > `ANTHROPIC_API_KEY` env > `.credentials.json`. `extraBetas` merge with OAuth defaults and de-dupe. `contextManagement` is sent as `context_management`; pair with the matching beta. Non-Anthropic equivalent: `behavior.compactStrategy: 'tail'`. Declares `capabilities.nativeWebSearch`: when the `web_search` tool is registered, the provider swaps in Anthropic's server-side `web_search_20250305` and streams results via `onServerToolUse` / `onServerToolResult`.
 
-`extraBodyParams` passes un-typed Messages API fields through (factory options win on collision). Use when Anthropic ships a beta before zidane has a knob. `openaiCompat` accepts the same field (e.g. `reasoning_effort`, `metadata`, OpenRouter `provider` routing).
+`extraHeaders` merges request headers for proxies/gateways; reserved Anthropic headers still win on collision. `extraBodyParams` passes un-typed Messages API fields through (factory options win on collision). Use when Anthropic ships a beta before zidane has a knob. `openaiCompat` accepts the same field (e.g. `reasoning_effort`, `metadata`, OpenRouter `provider` routing).
 
-### OpenRouter / OpenAI / Cerebras
+### OpenRouter / OpenAI / Cerebras / Arcee / Local
 
 ```ts
-import { openrouter, openai, cerebras } from 'zidane/providers'
+import { openrouter, openai, cerebras, arcee, local } from 'zidane/providers'
 
 openrouter({ apiKey: 'sk-or-...', defaultModel: 'google/gemini-pro' })
 openai()                                                                  // OpenAI Codex OAuth
 openai({ access: 'eyJ...', refresh: '...', expires: Date.now() + 3600_000, accountId: 'acct_123' })
 cerebras({ apiKey: 'csk-...', defaultModel: 'zai-glm-4.7' })
+arcee({ apiKey: 'arcee-...', defaultModel: 'trinity-large-thinking' })
+local({ baseURL: 'http://localhost:8000/v1', defaultModel: 'qwen3-coder' })
 ```
 
-Fallbacks: `params.apiKey` > `params.access` (Codex) > `<PROVIDER>_API_KEY` env > `.credentials.json` (Codex). Pass full OAuth fields on `openai()` to auto-refresh without reading `.credentials.json`.
+Fallbacks: `params.apiKey` > `params.access` (Codex) > `<PROVIDER>_API_KEY` env > `.credentials.json` (Codex). `local` uses `LOCAL_LLM_BASE_URL`, `LOCAL_LLM_API_KEY`, and `LOCAL_LLM_DEFAULT_MODEL`. Pass full OAuth fields on `openai()` to auto-refresh without reading `.credentials.json`.
 
 ### OpenAI-compatible (custom endpoints)
 
@@ -196,7 +202,7 @@ openaiCompat({
 })
 ```
 
-`openrouter` and `cerebras` are thin wrappers with vendor defaults pinned. Use `openaiCompat` directly for new backends.
+`openrouter`, `cerebras`, `arcee`, and `local` are thin wrappers with vendor/runtime defaults pinned. Use `openaiCompat` directly for new backends.
 
 ### Prompt caching
 
@@ -206,7 +212,7 @@ openaiCompat({
 |---|---|
 | `anthropic` | Honored natively. |
 | `openrouter` | Forwarded; Anthropic + Gemini honor; OpenAI / DeepSeek / Grok / Groq / Moonshot cache automatically and ignore the markers. |
-| `openaiCompat` | Opt-in via `cacheBreakpoints: true`. Off by default. |
+| `arcee` / `local` / `openaiCompat` | Off by default for strict OpenAI-compatible schemas; use `openaiCompat({ cacheBreakpoints: true })` only for endpoints that honor `cache_control`. |
 | `cerebras` | Off. |
 | `openai` (Codex) | Not affected (pi-ai wire format). |
 
@@ -238,7 +244,7 @@ await agent.run({ prompt: 'just chat', tools: {} }) // no tools for one run
 
 ## Thinking
 
-Named levels or exact budgets. Traces persist as `{ type: 'thinking', text }` blocks and stream via `stream:thinking`. Supported by Anthropic (native) and OpenRouter/Cerebras (`reasoning_content`/`reasoning` SSE fields).
+Named levels or exact budgets. Traces persist as `{ type: 'thinking', text }` blocks and stream via `stream:thinking`. Supported by Anthropic (native) and OpenRouter/Arcee (`reasoning_content`/`reasoning` SSE fields).
 
 | Level | Default budget |
 |---|---|

package/docs/ARCHITECTURE.md

@@ -312,7 +312,7 @@ Provider semantics:
 |---|---|
 | `anthropic` | Breakpoints honored natively. |
 | `openrouter` | Breakpoints forwarded; Anthropic + Gemini routes honor them, others ignore. |
-| `openaiCompat` | Factory-gated via `cacheBreakpoints: boolean` (default **off**). `openrouter` flips it on; bare `openaiCompat` stays off so OpenAI-direct doesn't reject unknown fields. |
+| `arcee` / `local` / `openaiCompat` | Factory-gated via `cacheBreakpoints: boolean` (default **off**). `openrouter` flips it on; Arcee/local/bare `openaiCompat` stay off so strict OpenAI-compatible endpoints don't reject unknown fields. |
 | `cerebras` | Off (factory doesn't enable breakpoints). |
 | `openai` (Codex) | Not affected — separate wire format (pi-ai). |
 
@@ -352,7 +352,7 @@ The built-in profiles (`buildBuildSystem` / `buildPlanSystem` in `zidane/chat`)
 
 - `anthropic` — `applyAnthropicCacheBreakpoints(params, originalSystem)` splits string system prompts on the marker. The OAuth path skips the split (the canonical CC prompt occupies `params.system`; the user doctrine lives in an injected user message).
 - `openaiCompat` — `toOAIMessages` strips the marker; `applyOAICacheBreakpoints(messages, originalSystem)` splits the leading system message into static + dynamic content parts when caching is on.
-- `openai` (Codex), `cerebras`, and any cache-disabled route — marker is collapsed via `renderSystemForWire` so it never reaches the model.
+- `openai` (Codex), `cerebras`, `arcee`, `local`, and any cache-disabled route — marker is collapsed via `renderSystemForWire` so it never reaches the model.
 
 ### Cache-break diagnosis
 

package/docs/CHAT.md

@@ -151,7 +151,7 @@ The table below indexes every named export; sections further down dive into the
 | `project-root` | `findGitRoot(cwd)` — walks upward looking for `.git`, returns absolute path or `null`. Used for session scope tagging + export anchors. |
 | `prompt-segments` | `splitPromptSegments(text, refs)` → `PromptSegment[]`. GUI maps the same segments to inline-block chip pills. |
 | `project-user-paths` | `projectUserPaths({ subPath, cwd, home, prefix })` — shared search-order builder for project + user config discovery. Powers `defaultSkillScanPaths` (`'skills'`) and `defaultMcpsConfigPaths` (calls it twice, once per `mcps.json` / `mcp.json`); the same convention extends to any new discovery surface. |
-| `providers` | `ProviderDescriptor` registry + helpers — `BUILTIN_PROVIDERS` (`anthropicDescriptor`, `openaiDescriptor`, `openrouterDescriptor`, `cerebrasDescriptor`, `localDescriptor`), `modelsForDescriptor`, `getModelInfo`, `getContextWindow`, `effectiveContextWindow`, `modelSupportsReasoning`, `OUTPUT_RESERVE_TOKENS`, `credKeyOf`, `piIdOf`. `cursorDescriptor` is exported but NOT in `BUILTIN_PROVIDERS` (OAuth works, inference not wired). See **Local provider**. |
+| `providers` | `ProviderDescriptor` registry + helpers — `BUILTIN_PROVIDERS` (`anthropicDescriptor`, `openaiDescriptor`, `openrouterDescriptor`, `cerebrasDescriptor`, `arceeDescriptor`, `localDescriptor`), `modelsForDescriptor`, `getModelInfo`, `getContextWindow`, `effectiveContextWindow`, `modelSupportsReasoning`, `OUTPUT_RESERVE_TOKENS`, `credKeyOf`, `piIdOf`. `cursorDescriptor` is exported but NOT in `BUILTIN_PROVIDERS` (OAuth works, inference not wired). See **Local provider**. |
 | `safe-mode` | Per-project safelist + matchers — `IMPLICITLY_SAFE_TOOLS`, `suggestSafelistEntry`, `addToSafelist`, `getSafelist`, `isOnSafelist`, `matchesSafelistEntry`, `readProjects`, `writeProjects`, `projectsFilePath`. |
 | `safe-mode-context` | `SafeModeProvider` owns a FIFO approval queue. `useSafeModeQueue()` returns the live array; `useSafeModeActions()` returns stable `{ requestApproval, resolveHead, denyAll }`. |
 | `session-export` | `renderSession`, `resolveSessionExportTarget`, `writeSessionExport`, `SessionExportFormat`, `SessionExportAnchor`, `SessionExportTarget`. |
@@ -186,7 +186,7 @@ resolveConfig({
   projectDb: false,
   cwd: process.cwd(),               // override the project-root walk root
 
-  // Provider registry — defaults to BUILTIN_PROVIDERS (Anthropic + OpenAI + OpenRouter + Cerebras).
+  // Provider registry — defaults to BUILTIN_PROVIDERS (Anthropic + OpenAI + OpenRouter + Cerebras + Arcee + Local).
   providers: { ...BUILTIN_PROVIDERS, mine: myDescriptor },
 
   // Agent registry — defaults to BUILTIN_AGENTS (Build + Plan).

package/docs/SKILL.md

@@ -11,7 +11,7 @@ Minimal TypeScript agent loop built with Bun. Streams from an LLM, executes tool
 
 ## Core Concepts
 
-- **Provider** — LLM backend (Anthropic, OpenAI Codex, OpenRouter, Cerebras). Streaming, format conversion, tool wiring. Anthropic + Codex support OAuth.
+- **Provider** — LLM backend (Anthropic, OpenAI Codex, OpenRouter, Cerebras, Arcee, local LLMs). Streaming, format conversion, tool wiring. Anthropic + Codex support OAuth.
 - **Preset** — `Partial<AgentOptions>` (tools, system, aliases, mcpServers, skills, behavior, hooks). `basicTools` ships `shell`, `readFile`, `writeFile`, `listFiles`, `edit`, `multiEdit`; the `basic` preset adds `spawn`. Override `tools: {}` for untrusted prompts.
 - **Agent** — `createAgent()` returns one. Turn loop: prompt → LLM → tool calls → tool results → … until done or `maxTurns`.
 - **Session** — Optional persistent turn history. Written incrementally.
@@ -85,11 +85,12 @@ Precedence: `run.behavior` > `agent.behavior` > defaults. `prompt` is required u
 All providers accept runtime keys via params. Env vars are fallbacks. OAuth credentials are read from `.credentials.json` and auto-refreshed (populate via `bun run auth`).
 
 ```ts
-import { anthropic, openai, openrouter, cerebras, openaiCompat } from 'zidane'
+import { anthropic, openai, openrouter, cerebras, arcee, local, openaiCompat } from 'zidane'
 
 anthropic({ apiKey: 'sk-ant-...', defaultModel: 'claude-opus-4-8' })
 anthropic({ access: 'sk-ant-oat-...', refresh: '...', expires: 1234567890 })  // OAuth
 anthropic({ apiKey: 'sk-ant-...', baseURL: 'https://gateway.corp/anthropic' }) // full proxy
+anthropic({ apiKey: 'sk-ant-...', extraHeaders: { 'X-Route': 'claude-prod' } }) // proxy headers
 anthropic({                                                                    // first-party betas
   apiKey: 'sk-ant-...',
   extraBetas: ['context-management-2025-06-27', 'token-efficient-tools-2026-03-28'],
@@ -105,6 +106,8 @@ anthropic({                                                                    /
 openai({ apiKey: 'sk-...', defaultModel: 'gpt-5.5' })                          // OpenAI Codex (OAuth too)
 openrouter({ apiKey: 'sk-or-...', defaultModel: 'google/gemini-pro' })
 cerebras({ apiKey: 'csk-...', defaultModel: 'zai-glm-4.7' })
+arcee({ apiKey: 'arcee-...', defaultModel: 'trinity-large-thinking' })
+local({ baseURL: 'http://localhost:8000/v1', defaultModel: 'qwen3-coder' })
 
 // Public factory for any OpenAI-compatible endpoint:
 openaiCompat({
@@ -115,9 +118,9 @@ openaiCompat({
 })
 ```
 
-Provider params types: `AnthropicParams`, `OpenAIParams`, `OpenRouterParams`, `CerebrasParams`, `OpenAICompatParams` — exported from `zidane`.
+Provider params types: `AnthropicParams`, `OpenAIParams`, `OpenRouterParams`, `CerebrasParams`, `ArceeParams`, `LocalParams`, `OpenAICompatParams` — exported from `zidane`.
 
-`openrouter` and `cerebras` are thin wrappers over `openaiCompat` with vendor defaults pinned. For new OAI-compatible backends (Baseten, Fireworks, Groq, local LM servers), use `openaiCompat` directly.
+`openrouter`, `cerebras`, `arcee`, and `local` are thin wrappers over `openaiCompat` with vendor/runtime defaults pinned. For new OAI-compatible backends (Baseten, Fireworks, Groq), use `openaiCompat` directly.
 
 ### Vision + image tool results
 
@@ -152,7 +155,7 @@ Flatten via `toolResultToText(result)`. MCP image blocks are auto-normalized via
 |---|---|
 | `anthropic` | Honored natively. |
 | `openrouter` | Forwarded to Anthropic + Gemini routes; ignored by OpenAI / DeepSeek / Grok / Groq / Moonshot (those cache automatically). |
-| `openaiCompat` | Opt-in via `cacheBreakpoints: true`. Off by default so strict-schema endpoints don't reject unknown fields. |
+| `arcee` / `local` / `openaiCompat` | Off by default so strict-schema endpoints don't reject unknown fields. Use `openaiCompat({ cacheBreakpoints: true })` only for hosts that honor `cache_control`. |
 | `cerebras` | Off. |
 | `openai` (Codex) | Not affected (pi-ai wire format). |
 
@@ -857,6 +860,7 @@ createSandboxContext(myProvider)  // implement SandboxProvider (E2B, Rivet, …)
 | `FileMapAdapter` | `{ get, save, delete }` — host-SDK seam for `createFileMapStore`. |
 | `TracingHooksOptions` | `createTracingHooks` config (`startSpan`, `namespace?`). |
 | `OpenAICompatParams` | `openaiCompat()` config (apiKey, baseURL, authHeader, extraHeaders, capabilities, cacheBreakpoints). |
+| `ArceeParams` / `LocalParams` | OpenAI-compatible wrapper configs for Arcee Platform and self-hosted local endpoints. |
 | `ValidationResult` | `{ valid, error?, coercedInput?, coercions?, droppedItems? }` — `validateToolArgs` output. `droppedItems` is keyed by field name and reports the original indexes of items dropped during recursive array validation. |
 | `AgentHookMap` | `{ [event]: handler \| handler[] }` — agent-lifetime hooks on `AgentOptions.hooks`. |
 | `RunHookMap` | Same shape, per-run scope (`agent.run({ hooks })`); handlers auto-detach. |
@@ -885,7 +889,7 @@ src/
   zod.ts               zodToJsonSchema (v4)
   auth.ts              OAuth login CLI
   start.ts             CLI entrypoint
-  providers/           anthropic, openai (Codex), openrouter, cerebras, openaiCompat + oauth helpers
+  providers/           anthropic, openai (Codex), openrouter, cerebras, arcee, local, openaiCompat + oauth helpers
   presets/             basic, basicTools, definePreset, composePresets
   tools/               Built-ins + skills tools + validation (auto-coerce)
   session/             memory, sqlite, remote, file-map + converters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "5.9.12",
+  "version": "5.9.13",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,