zidane 2.2.3 → 3.0.1

package/README.md

@@ -14,7 +14,11 @@ Built to be embedded.
 
 - 🧠 **Multi-provider** — Anthropic, OpenAI Codex, OpenRouter, Cerebras, plus a generic `openaiCompat` factory (Baseten, Fireworks, Groq, local servers). OAuth + API-key auth, auto-refreshing tokens.
 - 🔁 **Streaming turn loop** — stream text + thinking deltas, tool calls, and tool results with hookable events at every step.
-- 🛠 **Tools first-class** — shell, file IO, glob, spawn, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel execution, per-call gates, typed hooks.
+- 🛠 **Tools first-class** — `shell`, `read_file`, `write_file`, `edit`, `multi_edit`, `glob`, `grep`, `spawn`, human-in-the-loop, plus any [MCP](https://modelcontextprotocol.io) server. Sequential or parallel execution, per-call gates, typed hooks. Built-in tools ship with sensible truncation and idempotency defaults so consumers don't have to polyfill them.
+- ✂️ **Token-aware tool ergonomics** — `read_file` line-paginates with a footer that documents how to read the rest, `shell` tail-truncates combined output at 8 KB, `write_file` returns `No change needed` on idempotent writes. `outputBytes` surfaced on every tool/mcp hook.
+- 🧰 **Self-healing tool args** — `validateToolArgs` auto-coerces small/OSS-model mistakes (`"true"` → `true`, `"42"` → `42`, JSON-encoded arrays) before reaching `execute`. `validation:reject` fires only on irrecoverable mismatches.
+- 🪤 **Hallucinated tool names** handled — `tool:unknown` fires before the default error so consumers can substitute a friendly response.
+- 📉 **Per-turn output budget** — `behavior.toolOutputBudget` injects a "summarize before continuing" message when a turn's tool outputs exceed the cap. Off by default.
 - 🧩 **[Agent Skills](https://agentskills.io/specification) spec-aligned** — discover, activate, and run skills with `allowed-tools` enforcement and session-resume rehydration.
 - 💾 **Pluggable sessions** — in-memory, SQLite, remote HTTP, or a file-map adapter. Turns persist incrementally — a crash leaves valid partial history.
 - 🖼 **Multimodal** — images + documents via `PromptPart[]`; tools can return image blocks (screenshots, diagrams) routed natively on vision providers and via companion messages elsewhere.
@@ -25,8 +29,10 @@ Built to be embedded.
 - 🧵 **Sub-agent spawning** — delegate to child agents with inherited or overridden preset; child stream/tool events bubble to the parent.
 - 🧭 **Typed errors** — `AgentContextExceededError` / `AgentProviderError` / `AgentAbortedError` instead of sniffing error strings.
 - 🔌 **Execution contexts** — run tools in-process, in Docker, or in a remote sandbox (E2B / Rivet / any `SandboxProvider`).
-- 🪝 **Hookable everything** — ~40 typed hook events covering turn, stream, tool, MCP, session, skills, spawn, OAuth refresh, and bootstrap timing.
-- 🧪 **915+ tests, zero API keys** — mock providers + mock execution contexts; suite runs in under 2 seconds.
+- 🪝 **Hookable everything** — typed hook events covering turn, stream, tool, MCP, session, skills, spawn, OAuth refresh, bootstrap timing, validation rejection / coercion, and budget overflow.
+- 🧪 **1000+ tests, zero API keys** — mock providers + mock execution contexts; suite runs in under 2 seconds.
+
+> Upgrading from 2.x? See [`docs/migrate-from-v2.md`](./docs/migrate-from-v2.md) for the full list of behavior changes.
 
 ## Quickstart
 
@@ -70,6 +76,7 @@ createAgent({
     maxTokens: 16384,                // max tokens per LLM response
     thinkingBudget: 10240,           // exact thinking token budget
     cache: true,                     // prompt-cache breakpoints on supported providers (default: true)
+    toolOutputBudget: 32768,         // soft per-turn cap on tool-output bytes (off by default)
   },
   execution: createProcessContext(), // where tools run
   mcpServers: [],                    // MCP tool servers
@@ -213,13 +220,23 @@ The `basic` preset bundles:
 
 | Tool | Description |
 |---|---|
-| `shell` | Execute shell commands |
-| `readFile` | Read file contents |
-| `writeFile` | Write/create files |
+| `shell` | Execute shell commands. Combined stdout+stderr tail-truncated at 8 KB by default; `maxOutputBytes: 0` disables |
+| `readFile` | Read a file by line range. Default: lines 1..2000, byte cap 64 KB. Truncation footer documents how to page; binary files return a marker instead of mojibake |
+| `writeFile` | Write a file. Returns `Created` / `Updated` / `No change needed: …` so the model can detect no-ops without a separate read |
+| `edit` | Surgical replace of `old_string` → `new_string`. Fails clearly on non-unique matches (unless `replace_all`) and on not-found (with a nearest-match preview) |
+| `multiEdit` | Atomic list of edits to one file. All-or-nothing: any failed edit prevents the write |
 | `listFiles` | List directory contents |
 | `spawn` | Spawn a sub-agent |
 
-Extra tools live alongside: `glob` (pattern-based file matching), `createInteractionTool` (human-in-the-loop factory), and the three `skills_use` / `skills_read` / `skills_run_script` tools that auto-inject when the skills catalog is non-empty.
+Opt-in tools available via `import { glob, grep, createInteractionTool } from 'zidane'`:
+
+| Tool | Description |
+|---|---|
+| `glob` | Bun.Glob-backed pattern matching (in-process); shells out in docker/sandbox |
+| `grep` | ripgrep-backed regex search (with a Bun.Glob fallback). `output_mode`, `-i / -n / -A / -B / -C`, `multiline`, `head_limit`, `offset` — Claude Code Grep semantics |
+| `createInteractionTool` | Human-in-the-loop factory |
+
+The three `skills_use` / `skills_read` / `skills_run_script` tools auto-inject when the skills catalog is non-empty.
 
 Define a custom preset:
 
@@ -333,26 +350,51 @@ agent.hooks.hook('tool:gate', (ctx) => {
   }
 })
 
-agent.hooks.hook('tool:before', (ctx) => { /* ctx.turnId, ctx.callId, ctx.name, ctx.input */ })
-agent.hooks.hook('tool:after', (ctx) => { /* + ctx.result */ })
+agent.hooks.hook('tool:before', (ctx) => { /* ctx.turnId, ctx.callId, ctx.name, ctx.input, ctx.coercions? */ })
+agent.hooks.hook('tool:after', (ctx) => { /* + ctx.result, ctx.outputBytes, ctx.coercions? */ })
 agent.hooks.hook('tool:error', (ctx) => { /* + ctx.error */ })
 agent.hooks.hook('tool:transform', (ctx) => {
-  // + ctx.result, ctx.isError — mutate to modify output
-  if (ctx.result.length > 5000)
-    ctx.result = ctx.result.slice(0, 5000) + '\n... (truncated)'
+  // + ctx.result, ctx.isError, ctx.outputBytes (pre-mutation), ctx.coercions? — mutate result/isError to modify.
+  // Built-in tools already truncate; use this hook for consumer concerns the framework can't infer,
+  // e.g. redacting secrets in tool output before they reach the model.
+  if (typeof ctx.result === 'string')
+    ctx.result = ctx.result.replace(/\b(API_KEY|TOKEN|PASSWORD)\s*=\s*\S+/gi, '$1=<redacted>')
+})
+agent.hooks.hook('tool:unknown', (ctx) => {
+  // Fires when the model invents a tool name (or calls one no longer registered).
+  // Mutate ctx.result to substitute a friendly response, set ctx.suppressError = true
+  // to skip the companion `tool:error`.
+  if (ctx.name === 'EnterPlanMode') {
+    ctx.result = 'EnterPlanMode is not available — use shell to draft a plan as comments.'
+    ctx.suppressError = true
+  }
+})
+agent.hooks.hook('validation:reject', (ctx) => {
+  // Fires when arg validation rejects the input even after auto-coercion attempts.
+  // Observational — the model still receives `Validation error: …` for the retry.
+  // ctx.reason, ctx.schema
+})
+agent.hooks.hook('validation:coerce', (ctx) => {
+  // Fires when validation auto-healed at least one field. Never fires on
+  // perfectly-typed inputs. ctx.coercions lists the field names that were changed.
+  // Symmetric counterpart to `validation:reject` — useful for "model wrongness rate".
 })
 ```
 
+`ctx.coercions` (when present) is the same `readonly string[]` exposed via `validation:coerce`. The field is **omitted** from `tool:before` / `tool:after` / `tool:transform` ctx when no coercion happened, so it never noises up the happy path. Listeners can `if (ctx.coercions)` guard.
+
 MCP tool hooks mirror the same pattern with `server` and `tool` fields. Typed via `McpToolHookContext`.
 
 ```ts
 agent.hooks.hook('mcp:tool:gate', (ctx) => { /* ctx.turnId, ctx.callId, ctx.server, ctx.tool, ctx.input, ctx.block, ctx.reason */ })
 agent.hooks.hook('mcp:tool:before', (ctx) => { /* ctx.turnId, ctx.callId, ctx.server, ctx.tool, ctx.input */ })
-agent.hooks.hook('mcp:tool:after', (ctx) => { /* + ctx.result */ })
-agent.hooks.hook('mcp:tool:transform', (ctx) => { /* + ctx.result — mutate to modify */ })
+agent.hooks.hook('mcp:tool:after', (ctx) => { /* + ctx.result, ctx.outputBytes */ })
+agent.hooks.hook('mcp:tool:transform', (ctx) => { /* + ctx.result, ctx.outputBytes — mutate to modify */ })
 agent.hooks.hook('mcp:tool:error', (ctx) => { /* + ctx.error */ })
 ```
 
+`outputBytes` measures the wire size of the tool's result. On `*:transform` it's the **pre-mutation** size (a truncation handler can size-budget); on `*:after` it's the **post-mutation** size that goes to the model. `toolOutputByteLength(content)` exported from `zidane` reproduces the formula.
+
 ### Context transform
 
 Prune messages before each LLM call:
@@ -364,6 +406,58 @@ agent.hooks.hook('context:transform', (ctx) => {
 })
 ```
 
+### Hook recipes
+
+Three patterns that don't have a built-in default. Copy-paste and tune.
+
+```ts
+// 1. Truncate MCP tool results.
+//    Built-in tools (shell, read_file) already tail-truncate; MCP server outputs
+//    don't, since their sizes vary wildly and zidane can't pick a sane default
+//    on their behalf. Apply the same shape to mcp:tool:transform.
+agent.hooks.hook('mcp:tool:transform', (ctx) => {
+  if (ctx.outputBytes <= 8192 || typeof ctx.result !== 'string')
+    return
+  const tail = ctx.result.slice(-4096)
+  ctx.result = `…(${ctx.outputBytes - tail.length} bytes truncated from head)…\n${tail}`
+})
+
+// 2. Substitute a friendly response when the model invents a tool name.
+agent.hooks.hook('tool:unknown', (ctx) => {
+  if (ctx.name === 'EnterPlanMode') {
+    ctx.result = 'EnterPlanMode is not available — use shell to draft a plan as comments.'
+    ctx.suppressError = true
+  }
+})
+
+// 3. Drop old turns once the conversation grows past a soft cap.
+agent.hooks.hook('context:transform', (ctx) => {
+  const KEEP_RECENT = 30
+  if (ctx.messages.length > KEEP_RECENT) {
+    const trimmed = [ctx.messages[0], ...ctx.messages.slice(-KEEP_RECENT + 1)]
+    ctx.messages.splice(0, ctx.messages.length, ...trimmed)
+  }
+})
+```
+
+`mcp:tool:transform`, `tool:unknown`, and `context:transform` are the highest-leverage entries on the surface for the cases v3 doesn't auto-handle. Most production agents end up with one of each.
+
+### Per-turn output budget
+
+When working with OSS models that return large tool outputs, set `behavior.toolOutputBudget` to inject a "summarize before continuing" message after any turn whose combined post-`tool:transform` tool-output bytes exceed the cap. Off by default.
+
+```ts
+const agent = createAgent({
+  ...basic,
+  provider,
+  behavior: { toolOutputBudget: 32768 },
+})
+
+agent.hooks.hook('budget:exceeded', (ctx) => {
+  console.warn(`turn ${ctx.turn}: ${ctx.bytes} > ${ctx.budget} bytes`)
+})
+```
+
 ## Steering and Follow-up
 
 ### Steering
@@ -751,19 +845,29 @@ stats.timeTillFirstTokenMs      // ms from run() start to the first stream/tool
 All types are available from `zidane/types`:
 
 ```ts
-import type { Agent, SessionTurn, TurnUsage, Provider, ToolDef } from 'zidane/types'
+import type { Agent, SessionTurn, TurnUsage, Provider, ToolDef, ValidationResult } from 'zidane/types'
 
 // Hook context types for typed event handlers
 import type { ToolHookContext, McpToolHookContext, SessionHookContext, StreamHookContext } from 'zidane/types'
 ```
 
+Helpers (re-exported from the main entry):
+
+```ts
+import { toolResultToText, toolOutputByteLength, validateToolArgs } from 'zidane'
+```
+
+- `toolResultToText(content)` — flatten `string | ToolResultContent[]` to a string for logging.
+- `toolOutputByteLength(content)` — same formula the loop uses for `outputBytes`.
+- `validateToolArgs(input, schema)` — the validator the loop runs between `tool:gate` and `tool:before`. Useful for unit tests of consumer tool definitions.
+
 ## Testing
 
 ```bash
 bun test
 ```
 
-915+ tests with mock provider and execution context. No API keys or Docker needed; the suite runs in under 2 seconds.
+1000+ tests with mock provider and execution context. No API keys or Docker needed; the suite runs in under 2 seconds.
 
 ## Benchmarks
 

package/dist/{agent-CEO3IeZj.d.ts → agent-4zeSbdXy.d.ts}

@@ -121,7 +121,18 @@ declare function toTypedError(classification: ClassifiedError, provider: string,
  * Shared types for the agent system.
  */
 
-type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high';
+/**
+ * Thinking / extended-reasoning configuration.
+ *
+ * - `'off'` — no thinking.
+ * - `'minimal' | 'low' | 'medium' | 'high'` — explicit token budget. Maps to
+ *   provider-specific reasoning controls (Anthropic `thinking.type='enabled'`
+ *   with a budget; OpenAI `reasoning_effort`).
+ * - `'adaptive'` — let the model decide per-turn whether and how much to think.
+ *   Anthropic-only (`thinking.type='adaptive'`). Other providers fall back to
+ *   no reasoning when this value is supplied.
+ */
+type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'adaptive';
 interface McpServerConfig {
     /** Display name (used for tool namespacing) */
     name: string;
@@ -194,6 +205,17 @@ interface AgentBehavior {
      * Default: `true`.
      */
     cache?: boolean;
+    /**
+     * Soft per-turn cap on total tool-output bytes. When the sum of `outputBytes`
+     * across a turn's tool results exceeds this value, the loop injects a
+     * synthetic user message instructing the model to summarize before calling
+     * more tools, and fires the `budget:exceeded` hook.
+     *
+     * Measured **post-`tool:transform`** so consumer truncation counts toward the
+     * budget. Off by default (undefined / `0` disables the check). A reasonable
+     * starting value for OSS-model integrations is `32768`.
+     */
+    toolOutputBudget?: number;
 }
 interface ImageContent {
     type: 'image';
@@ -270,6 +292,19 @@ interface ToolResultImageContent {
  * structured content should route the array through without flattening.
  */
 declare function toolResultToText(content: string | ToolResultContent[]): string;
+/**
+ * Approximate byte length of a tool output as it goes back to the model.
+ *
+ * - Plain text: UTF-8 byte length.
+ * - Structured content: text blocks contribute their UTF-8 byte length; image
+ *   blocks contribute their **base64 character length**, since that is what
+ *   the model tokenizes (the wire-encoded payload, not the decoded image).
+ *
+ * Used by the agent loop to populate `outputBytes` on `tool:after`,
+ * `tool:transform`, `mcp:tool:after`, and `mcp:tool:transform` hooks so
+ * consumers can size-budget tool output without re-counting bytes themselves.
+ */
+declare function toolOutputByteLength(content: string | ToolResultContent[]): number;
 type SessionContentBlock = {
     type: 'text';
     text: string;
@@ -1423,9 +1458,13 @@ interface AgentHooks {
         block: boolean;
         reason: string;
     }) => void;
-    'tool:before': (ctx: ToolHookContext) => void;
+    'tool:before': (ctx: ToolHookContext & {
+        coercions?: readonly string[];
+    }) => void;
     'tool:after': (ctx: ToolHookContext & {
         result: string | ToolResultContent[];
+        outputBytes: number;
+        coercions?: readonly string[];
     }) => void;
     'tool:error': (ctx: ToolHookContext & {
         error: Error;
@@ -1433,6 +1472,45 @@ interface AgentHooks {
     'tool:transform': (ctx: ToolHookContext & {
         result: string | ToolResultContent[];
         isError: boolean;
+        outputBytes: number;
+        coercions?: readonly string[];
+    }) => void;
+    /**
+     * Fires before the generic "Unknown tool" error when the model invokes a tool
+     * that isn't registered (hallucinated names, dropped MCP servers, dangling
+     * aliases). Mutate `result` to substitute a friendly response or set
+     * `suppressError: true` to skip the companion `tool:error` emission.
+     *
+     * Fires for any unknown tool name — including hallucinated MCP-style names
+     * (`mcp_supabase_xxx`); branch on `name.startsWith('mcp_')` to differentiate.
+     */
+    'tool:unknown': (ctx: ToolHookContext & {
+        result?: string | ToolResultContent[];
+        suppressError: boolean;
+    }) => void;
+    /**
+     * Fires when `validateToolArgs` rejects an input that could not be auto-coerced
+     * to satisfy the tool's `inputSchema`. Observational — the tool call still
+     * surfaces a `Validation error: …` string back to the model. Useful for
+     * counting validation failures separately from runtime tool errors.
+     */
+    'validation:reject': (ctx: ToolHookContext & {
+        reason: string;
+        schema: Record<string, unknown>;
+    }) => void;
+    /**
+     * Fires when `validateToolArgs` successfully auto-coerced one or more input
+     * fields to satisfy the tool's `inputSchema`. **Only fires when at least one
+     * coercion happened** — never on perfectly-shaped inputs. Useful for counting
+     * model "wrongness rate" without re-running validation downstream.
+     *
+     * `coercions` lists the field names that were coerced. The values landed in
+     * the input that the tool actually received; consumers wanting before/after
+     * comparison can re-run `validateToolArgs(ctx.input, ctx.schema)`.
+     */
+    'validation:coerce': (ctx: ToolHookContext & {
+        coercions: readonly string[];
+        schema: Record<string, unknown>;
     }) => void;
     'context:transform': (ctx: {
         messages: SessionMessage[];
@@ -1463,11 +1541,14 @@ interface AgentHooks {
         depth: number;
     }) => void;
     'child:tool:before': (ctx: ToolHookContext & {
+        coercions?: readonly string[];
         childId: string;
         depth: number;
     }) => void;
     'child:tool:after': (ctx: ToolHookContext & {
         result: string | ToolResultContent[];
+        outputBytes: number;
+        coercions?: readonly string[];
         childId: string;
         depth: number;
     }) => void;
@@ -1527,9 +1608,11 @@ interface AgentHooks {
     'mcp:tool:before': (ctx: McpToolHookContext) => void;
     'mcp:tool:after': (ctx: McpToolHookContext & {
         result: string | ToolResultContent[];
+        outputBytes: number;
     }) => void;
     'mcp:tool:transform': (ctx: McpToolHookContext & {
         result: string | ToolResultContent[];
+        outputBytes: number;
     }) => void;
     'mcp:tool:error': (ctx: McpToolHookContext & {
         error: Error;
@@ -1560,6 +1643,17 @@ interface AgentHooks {
         output: Record<string, unknown>;
         schema: Record<string, unknown>;
     }) => void;
+    /**
+     * Fires when a turn's total tool-output bytes exceed `behavior.toolOutputBudget`.
+     * Measured post-`tool:transform`. Loop injects a synthetic user message after
+     * the tool-results turn instructing the model to summarize.
+     */
+    'budget:exceeded': (ctx: {
+        turn: number;
+        turnId: string;
+        bytes: number;
+        budget: number;
+    }) => void;
     'agent:abort': (ctx: object) => void;
     'agent:done': (ctx: AgentStats) => void;
     'session:start': (ctx: SessionHookContext & {
@@ -1675,4 +1769,4 @@ interface Agent {
 }
 declare function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, mcpConnector, eager }: AgentOptions): Agent;
 
-export { type ToolHookContext as $, type Agent as A, type SessionData as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionEndStatus as D, type SessionHookContext as E, type SessionMessage as F, type SessionRun as G, type SessionStore as H, type ImageContent as I, type SessionTurn as J, type SkillConfig as K, type SkillResource as L, type McpConnection as M, type SkillsConfig as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type SpawnHookContext as Q, type RemoteStoreOptions as R, type Session as S, type StreamCallbacks as T, type StreamHookContext as U, type StreamOptions as V, type ThinkingLevel as W, type ToolCall as X, type ToolContext as Y, type ToolDef as Z, type ToolExecutionMode as _, AgentAbortedError as a, type ToolMap as a0, type ToolResult as a1, type ToolResultContent as a2, type ToolResultImageContent as a3, type ToolResultTextContent as a4, type ToolSpec as a5, type TurnFinishReason as a6, type TurnResult as a7, type TurnUsage as a8, matchesContextExceeded as a9, loadSession as aA, mapOAIFinishReason as aB, normalizeMcpBlocks as aC, normalizeMcpServers as aD, openai as aE, openaiCompat as aF, openrouter as aG, resultToString as aH, toAnthropic as aI, toOpenAI as aJ, toTypedError as aK, toolResultToText as aa, type ActivationVia as ab, type ActiveSkill as ac, type DeactivationReason as ad, type FileMapAdapter as ae, type FileMapStoreOptions as af, type OpenAICompatAuthHeader as ag, OpenAICompatHttpError as ah, type OpenAICompatParams as ai, type SkillActivationState as aj, type SkillActivationStateOptions as ak, type SkillDiagnostic as al, type SkillSource as am, anthropic as an, autoDetectAndConvert as ao, cerebras as ap, classifyOpenAICompatError as aq, connectMcpServers as ar, createAgent as as, createFileMapStore as at, createMemoryStore as au, createRemoteStore as av, createSession as aw, createSkillActivationState as ax, fromAnthropic as ay, fromOpenAI as az, type AgentBehavior as b, AgentContextExceededError as c, type AgentHooks as d, type AgentOptions as e, AgentProviderError as f, type AgentRunOptions as g, type AgentStats as h, AgentToolNotAllowedError as i, type AnthropicParams as j, type CerebrasParams as k, type ChildRunStats as l, type ClassifiedError as m, type ClassifiedErrorKind as n, type CreateSessionOptions as o, type McpServerConfig as p, type McpToolHookContext as q, type OpenAIParams as r, type OpenRouterParams as s, type PromptImagePart as t, type PromptPart as u, type PromptTextPart as v, type Provider as w, type ProviderCapabilities as x, type RunHookMap as y, type SessionContentBlock as z };
+export { type ToolHookContext as $, type Agent as A, type SessionData as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionEndStatus as D, type SessionHookContext as E, type SessionMessage as F, type SessionRun as G, type SessionStore as H, type ImageContent as I, type SessionTurn as J, type SkillConfig as K, type SkillResource as L, type McpConnection as M, type SkillsConfig as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type SpawnHookContext as Q, type RemoteStoreOptions as R, type Session as S, type StreamCallbacks as T, type StreamHookContext as U, type StreamOptions as V, type ThinkingLevel as W, type ToolCall as X, type ToolContext as Y, type ToolDef as Z, type ToolExecutionMode as _, AgentAbortedError as a, type ToolMap as a0, type ToolResult as a1, type ToolResultContent as a2, type ToolResultImageContent as a3, type ToolResultTextContent as a4, type ToolSpec as a5, type TurnFinishReason as a6, type TurnResult as a7, type TurnUsage as a8, matchesContextExceeded as a9, fromOpenAI as aA, loadSession as aB, mapOAIFinishReason as aC, normalizeMcpBlocks as aD, normalizeMcpServers as aE, openai as aF, openaiCompat as aG, openrouter as aH, resultToString as aI, toAnthropic as aJ, toOpenAI as aK, toTypedError as aL, toolOutputByteLength as aa, toolResultToText as ab, type ActivationVia as ac, type ActiveSkill as ad, type DeactivationReason as ae, type FileMapAdapter as af, type FileMapStoreOptions as ag, type OpenAICompatAuthHeader as ah, OpenAICompatHttpError as ai, type OpenAICompatParams as aj, type SkillActivationState as ak, type SkillActivationStateOptions as al, type SkillDiagnostic as am, type SkillSource as an, anthropic as ao, autoDetectAndConvert as ap, cerebras as aq, classifyOpenAICompatError as ar, connectMcpServers as as, createAgent as at, createFileMapStore as au, createMemoryStore as av, createRemoteStore as aw, createSession as ax, createSkillActivationState as ay, fromAnthropic as az, type AgentBehavior as b, AgentContextExceededError as c, type AgentHooks as d, type AgentOptions as e, AgentProviderError as f, type AgentRunOptions as g, type AgentStats as h, AgentToolNotAllowedError as i, type AnthropicParams as j, type CerebrasParams as k, type ChildRunStats as l, type ClassifiedError as m, type ClassifiedErrorKind as n, type CreateSessionOptions as o, type McpServerConfig as p, type McpToolHookContext as q, type OpenAIParams as r, type OpenRouterParams as s, type PromptImagePart as t, type PromptPart as u, type PromptTextPart as v, type Provider as w, type ProviderCapabilities as x, type RunHookMap as y, type SessionContentBlock as z };

package/dist/{chunk-MDVZX6GM.js → chunk-2VM47IBI.js}

@@ -1,16 +1,18 @@
 import {
+  edit,
   listFiles,
+  multiEdit,
   readFile,
   shell,
   spawn,
   writeFile
-} from "./chunk-O2XZLJMG.js";
+} from "./chunk-QFHGWKK3.js";
 
 // src/presets/basic.ts
-var basicTools = { shell, readFile, writeFile, listFiles };
+var basicTools = { shell, readFile, writeFile, listFiles, edit, multiEdit };
 var basic_default = definePreset({
   name: "basic",
-  system: "You are a helpful assistant with access to shell, file reading, file writing, directory listing, and sub-agent spawning tools. Use them to accomplish tasks in the project directory.",
+  system: "You are a helpful assistant with access to shell, file reading, file writing, surgical and multi-edit tools, directory listing, and sub-agent spawning. Prefer `edit` / `multi_edit` for in-place changes and `write_file` for full file overwrites. Use them to accomplish tasks in the project directory.",
   tools: { ...basicTools, spawn }
 });
 

package/dist/{chunk-ZSEMKVHP.js → chunk-HQD5ICI6.js}

@@ -161,12 +161,22 @@ function createClient(SDK, apiKey, isOAuth, baseURL) {
     } : { apiKey, ...base }
   );
 }
-var THINKING_BUDGETS = {
-  minimal: 1024,
-  low: 4096,
-  medium: 10240,
-  high: 32768
+var EFFORT_FOR_LEVEL = {
+  minimal: "low",
+  low: "low",
+  medium: "medium",
+  high: "high"
 };
+function planAnthropicThinking(level, customBudget) {
+  if (level === "off")
+    return null;
+  if (level === "adaptive")
+    return { kind: "adaptive" };
+  if (customBudget !== void 0) {
+    return { kind: "enabled", budgetTokens: customBudget, maxTokensBump: customBudget };
+  }
+  return { kind: "adaptive", effort: EFFORT_FOR_LEVEL[level] };
+}
 function mapStopReason(stopReason) {
   if (!stopReason)
     return void 0;
@@ -393,13 +403,16 @@ function anthropic(anthropicParams) {
       };
       if (options.cache !== false)
         applyAnthropicCacheBreakpoints(params);
-      if (thinking !== "off") {
-        const budgetTokens = options.thinkingBudget ?? THINKING_BUDGETS[thinking];
-        params.thinking = {
-          type: "enabled",
-          budget_tokens: budgetTokens
-        };
-        params.max_tokens = budgetTokens + params.max_tokens;
+      const plan = planAnthropicThinking(thinking, options.thinkingBudget);
+      if (plan) {
+        if (plan.kind === "enabled") {
+          params.thinking = { type: "enabled", budget_tokens: plan.budgetTokens };
+          params.max_tokens = plan.maxTokensBump + params.max_tokens;
+        } else {
+          params.thinking = { type: "adaptive" };
+          if (plan.effort)
+            params.output_config = { effort: plan.effort };
+        }
         params.temperature = 1;
       }
       if (options.toolChoice) {
@@ -679,13 +692,14 @@ function openai(params) {
         messages: toPiMessages(options.messages, modelId),
         tools: options.tools
       };
+      const reasoningLevel = options.thinking && options.thinking !== "off" && options.thinking !== "adaptive" ? options.thinking : void 0;
       const stream = streamOpenAICodexResponses(model, context, {
         apiKey,
         maxTokens: options.maxTokens,
         signal: options.signal,
         transport: params?.transport,
-        reasoningEffort: options.thinking && options.thinking !== "off" ? options.thinking : void 0,
-        reasoningSummary: options.thinking && options.thinking !== "off" ? "auto" : void 0,
+        reasoningEffort: reasoningLevel,
+        reasoningSummary: reasoningLevel ? "auto" : void 0,
         onPayload: (payload) => applyPayloadOverrides(payload, options)
       });
       let finalMessage;

package/dist/chunk-JH6IAAFA.js

@@ -0,0 +1,28 @@
+// src/types.ts
+import { Buffer } from "buffer";
+function toolResultToText(content) {
+  if (typeof content === "string")
+    return content;
+  return content.map((block) => {
+    if (block.type === "text")
+      return block.text;
+    return `[image: ${block.mediaType} \u2014 ${block.data.length} b64 bytes]`;
+  }).join("\n");
+}
+function toolOutputByteLength(content) {
+  if (typeof content === "string")
+    return Buffer.byteLength(content);
+  let total = 0;
+  for (const block of content) {
+    if (block.type === "text")
+      total += Buffer.byteLength(block.text);
+    else
+      total += block.data.length;
+  }
+  return total;
+}
+
+export {
+  toolResultToText,
+  toolOutputByteLength
+};