zidane 5.6.11 → 5.6.13

package/README.md

@@ -220,7 +220,7 @@ openaiCompat({
 | `listFiles` | Directory listing. |
 | `spawn` | Sub-agent. |
 
-Opt-in (via `import from 'zidane'`): `glob` (Bun.Glob; shells out in docker/sandbox), `grep` (ripgrep + Bun.Glob fallback; full Claude Code Grep semantics), `createInteractionTool` (HITL factory).
+Opt-in (via `import from 'zidane'`): `glob` (`node:fs/promises` glob; shells out in docker/sandbox), `grep` (ripgrep + `node:fs/promises` glob fallback; full Claude Code Grep semantics), `createInteractionTool` (HITL factory).
 
 `skills_use` / `skills_read` / `skills_run_script` auto-inject when the skills catalog is non-empty.
 
@@ -504,6 +504,8 @@ Storage backends — `createMemoryStore()` (in-memory), `createSqliteStore({ pat
 
 Restore via `await loadSession(store, id)`. Session hooks: `session:start`, `session:turns`, `session:end` (always fires, carries `turnRange`).
 
+**Building provider requests outside `agent.run()`** — use `session.toMessages({ provider })` instead of `session.turns`. Raw turns can carry orphan `tool_use` / `tool_result` blocks from interrupted runs, partial-result writes, or compaction boundaries — feeding them to a provider hits `tool_result must be preceded by a tool_call with the same toolCallId`. `toMessages()` projects through the same defensive pairing repair the loop runs at wire-send time and (with `provider`) enforces the user-tail invariant for prefill-rejecting models. Pure, idempotent, never mutates `session.turns`; do not write the result back via `setTurns` / `appendTurns` (synthetic placeholders would contaminate history). Standalone variant `toWireMessages(turns, opts?)` for callers holding raw `SessionTurn[]` from `store.getTurns()`.
+
 ## MCP Servers
 
 Connect any MCP server. Tools are namespaced `mcp_{server}_{tool}`. Connections are lazy (first `run()`) and reused; all servers bootstrap in parallel.
@@ -693,7 +695,7 @@ type ToolResultContent =
 
 Image-producing tools (MCP browsers, screenshots) return `ToolResultContent[]` — routed natively on providers with `imageInToolResult: true`, via companion user message elsewhere. Flatten with `toolResultToText(output)`.
 
-External interop converters: `fromAnthropic`, `toAnthropic`, `fromOpenAI`, `toOpenAI`, `autoDetectAndConvert` (re-exported from `zidane`).
+External interop converters: `fromAnthropic`, `toAnthropic`, `fromOpenAI`, `toOpenAI`, `autoDetectAndConvert` (re-exported from `zidane`). Wire-safety helpers: `toWireMessages(turns, opts?)`, `ensureToolResultPairing(messages, opts?)`, `ensureEndsWithUserMessage(messages, provider)` — apply when sending outside `agent.run()` to avoid orphan `tool_use` 400s; see [Sessions](#sessions).
 
 ## Typed Errors
 
@@ -719,6 +721,21 @@ catch (err) {
 
 Set `behavior.maxCostUsd` and/or `behavior.maxTotalTokens` to trip the budget circuit breaker (post-turn check, soft cap). See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) → run-level budget.
 
+### Retry-with-backoff (new default)
+
+Transient provider failures (429, 5xx, Anthropic `overloaded_error` mid-stream, OpenAI-compat stream truncation, pi-ai rate-limit / unavailable messages) now retry with exponential backoff + jitter **by default**. Default policy: **3 attempts, 1s → 2s → 4s with full jitter, capped at 30s per delay**, `retry-after` / `retry-after-ms` headers honored. Worst-case run latency on terminal failure: ~2× `maxDelayMs` (so ~60s) before the error surfaces.
+
+```ts
+await agent.run({
+  prompt: '...',
+  behavior: {
+    retry: { maxAttempts: 3, initialDelayMs: 1000, maxDelayMs: 30_000 },
+  },
+})
+```
+
+Set `behavior.retry.maxAttempts: 1` to restore the pre-v5.7 fail-fast behavior. Retry skips when any output has already streamed this turn (replaying over partial text would corrupt the transcript). Observe via the `stream:retry` hook (`{ attempt, nextAttempt, delayMs, err, statusCode?, requestId? }`); `stream:error` only fires on the terminal failure.
+
 ## Structured Output
 
 Force the final response to a JSON Schema via provider-level tool forcing. Lands on `stats.output` and fires the `output` hook (`ctx.output`, `ctx.schema`).