zidane 1.8.1 → 2.1.1

package/dist/{agent-8QBOx4_0.d.ts → agent-DFkSTVKm.d.ts}

@@ -1,7 +1,6 @@
 import { Hookable } from 'hookable';
 import { b as ExecutionContext, c as ExecutionHandle } from './types-BpvTmawk.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { b as SkillsConfig, S as SkillConfig } from './types-CDI8Kmve.js';
 
 /**
  * Typed error classes for agent runs.
@@ -22,6 +21,13 @@ interface ClassifiedError {
     providerCode?: string;
     /** Optional human-readable message override. Falls back to the underlying error's message. */
     message?: string;
+    /**
+     * Hint that the error is transient and a retry with backoff is reasonable
+     * (e.g. 429, 5xx, truncated stream). Omitted when the provider can't decide;
+     * callers should default to "do not retry" when absent to avoid hammering
+     * terminal failures (auth, invalid request).
+     */
+    retryable?: boolean;
 }
 interface TypedErrorOptions {
     /** Provider name, always set (e.g. `anthropic`, `openrouter`) */
@@ -30,6 +36,8 @@ interface TypedErrorOptions {
     providerCode?: string;
     /** Original error from the provider SDK/HTTP layer */
     cause?: unknown;
+    /** See {@link ClassifiedError.retryable}. */
+    retryable?: boolean;
 }
 /**
  * Thrown when the model or provider signals that the context window was exceeded.
@@ -49,6 +57,12 @@ declare class AgentProviderError extends Error {
     readonly code: "provider_error";
     readonly provider: string;
     readonly providerCode?: string;
+    /**
+     * Whether a retry with backoff is likely to succeed. See
+     * {@link ClassifiedError.retryable}. Absent when the provider did not
+     * classify the error — callers should treat absent as "don't retry".
+     */
+    readonly retryable?: boolean;
     constructor(message: string, options: TypedErrorOptions);
 }
 /**
@@ -60,6 +74,32 @@ declare class AgentAbortedError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Thrown (well — constructed; attach via the `tool:gate` block signal) when the
+ * union of `allowed-tools` across active skills does not permit a tool call.
+ *
+ * Produced by the allowed-tools middleware registered on `tool:gate` /
+ * `mcp:tool:gate`. The gate's `block = true` + `reason` carry the same message
+ * so consumers that don't look at this typed error still get a useful string.
+ */
+declare class AgentToolNotAllowedError extends Error {
+    readonly code: "tool_not_allowed";
+    /** Canonical tool name the agent tried to call. */
+    readonly toolName: string;
+    /** Aliased / wire name the LLM saw. */
+    readonly displayName: string;
+    /** Flattened union of `allowedTools` patterns across active skills. */
+    readonly allowedUnion: readonly string[];
+    /** Names of the skills currently active when the block fired. */
+    readonly activeSkills: readonly string[];
+    constructor(options: {
+        toolName: string;
+        displayName: string;
+        allowedUnion: readonly string[];
+        activeSkills: readonly string[];
+        cause?: unknown;
+    });
+}
 /**
  * Regex patterns matching common "context window exceeded" messages across providers.
  *
@@ -91,8 +131,24 @@ interface McpServerConfig {
     command?: string;
     /** For stdio: command arguments */
     args?: string[];
-    /** For stdio: environment variables */
+    /**
+     * For stdio: environment variables to pass to the server process.
+     *
+     * Merged on top of the MCP SDK's default inherited environment — a safety
+     * whitelist (`PATH`, `HOME`, `LANG`, `SHELL`, `USER` on POSIX; `APPDATA`,
+     * `PATH`, ... on Win32). Setting this to `{}` no longer strips `PATH` from
+     * the child process. Set {@link McpServerConfig.strictEnv} to `true` to
+     * pass `env` verbatim with no inherited defaults.
+     */
     env?: Record<string, string>;
+    /**
+     * When true, {@link McpServerConfig.env} is passed verbatim to the spawned
+     * process — the MCP SDK's default inherited environment (`PATH`, `HOME`, ...)
+     * is NOT merged in. Most consumers should leave this off; the default merge
+     * prevents `spawn ENOENT` when a stdio server declares an `env` without
+     * restating `PATH`.
+     */
+    strictEnv?: boolean;
     /** For sse/streamable-http: server URL */
     url?: string;
     /** Optional headers for HTTP transports */
@@ -156,6 +212,38 @@ interface PromptDocumentPart {
     /** Optional display name used in attachment headers */
     name?: string;
 }
+/**
+ * A single block of structured tool-result content.
+ *
+ * MCP servers can return a mix of text, image, resource, and audio blocks. Tools
+ * return `string` for the common text-only case or `ToolResultContent[]` when they
+ * need to preserve non-text content (e.g. screenshots from a browser MCP).
+ *
+ * Providers that support native multi-part tool results (Anthropic, OpenAI Codex via
+ * pi-ai) route image blocks into their wire format verbatim; OpenAI-compat providers
+ * route them via a companion-user-message fallback when the underlying model/endpoint
+ * does not accept images inside tool-role messages.
+ */
+type ToolResultContent = ToolResultTextContent | ToolResultImageContent;
+interface ToolResultTextContent {
+    type: 'text';
+    text: string;
+}
+interface ToolResultImageContent {
+    type: 'image';
+    /** IANA media type (e.g. `image/png`, `image/jpeg`) */
+    mediaType: string;
+    /** Base64-encoded payload */
+    data: string;
+}
+/**
+ * Lossy flattener — converts `ToolResultContent[]` (or a plain string) to a single
+ * string. Image blocks are replaced with `[image: <media> — <n> b64 bytes]` markers.
+ *
+ * Use at UI boundaries where a string is required; providers that understand
+ * structured content should route the array through without flattening.
+ */
+declare function toolResultToText(content: string | ToolResultContent[]): string;
 type SessionContentBlock = {
     type: 'text';
     text: string;
@@ -171,7 +259,11 @@ type SessionContentBlock = {
 } | {
     type: 'tool_result';
     callId: string;
-    output: string;
+    /**
+     * Tool output — either a plain string (text-only, the common case) or a structured
+     * array of content blocks (text + image for multimodal tools such as screenshots).
+     */
+    output: string | ToolResultContent[];
     isError?: boolean;
 } | {
     type: 'thinking';
@@ -229,6 +321,18 @@ interface AgentRunOptions {
      * Accepts either a single handler or an array (all handlers register).
      */
     hooks?: RunHookMap;
+    /**
+     * Parent run id. Populated automatically by the `spawn` tool when the child
+     * shares the parent's session; recorded on the resulting `SessionRun` so the
+     * parent↔child run tree can be reconstructed from a persisted session.
+     */
+    parentRunId?: string;
+    /**
+     * Zero-based subagent depth. 0 = top-level `agent.run()`, 1 = first-level
+     * child spawned by a parent agent, and so on. Used by the spawn tool to
+     * enforce `maxDepth` and to stamp `child:*` forwarded hook payloads.
+     */
+    depth?: number;
 }
 /** Reason the provider gave for stopping the turn */
 type TurnFinishReason = 'stop' | 'tool-calls' | 'length' | 'content-filter' | 'error' | 'other';
@@ -279,6 +383,24 @@ interface ChildRunStats {
     id: string;
     task: string;
     stats: AgentStats;
+    /**
+     * Subagent depth when this child ran. 1 = direct child of the top-level
+     * agent, 2 = grandchild, etc. Useful for telemetry that wants to group
+     * runs by depth.
+     */
+    depth?: number;
+    /**
+     * Terminal state of the child run. `'completed'` is the default. Exposed so
+     * a parent reading `stats.children` can distinguish aborted/timed-out
+     * children without re-parsing the returned string.
+     */
+    status?: 'completed' | 'aborted' | 'timeout' | 'error';
+    /**
+     * Final structured output when the child was run with `behavior.schema`.
+     * Mirrors `AgentStats.output` but is surfaced here so the parent can read
+     * it without peeking at the nested `stats` bag.
+     */
+    output?: Record<string, unknown>;
 }
 /**
  * Base context for tool execution hooks.
@@ -329,6 +451,12 @@ interface SessionHookContext {
 interface SpawnHookContext {
     id: string;
     task: string;
+    /**
+     * Subagent depth for the spawn. 1 = direct child of the top-level agent.
+     * Present on spawn:before/complete/error. Absent for grandchild spawns that
+     * bubble through `child:*` events (which carry their own `depth`).
+     */
+    depth?: number;
 }
 /** Context for stream hooks */
 interface StreamHookContext {
@@ -370,6 +498,12 @@ declare function anthropic(anthropicParams?: AnthropicParams): Provider;
 interface CerebrasParams {
     apiKey?: string;
     defaultModel?: string;
+    /**
+     * Provider capability flags. Cerebras currently serves text-only OSS models
+     * (GLM, Llama-family, Qwen-family) — default: `{ vision: false, imageInToolResult: false }`.
+     * Override when routing to a vision-capable deployment.
+     */
+    capabilities?: ProviderCapabilities;
 }
 /**
  * Cerebras provider.
@@ -455,6 +589,17 @@ interface OpenAICompatParams {
     authHeader?: OpenAICompatAuthHeader;
     /** Extra headers sent with every request (e.g. referer, user-agent). */
     extraHeaders?: Record<string, string>;
+    /**
+     * Provider-level capability flags. Routed into the message shaper and the
+     * agent loop so images in tool results + user messages are handled correctly
+     * for the underlying model.
+     *
+     * Defaults when omitted: `vision: false`, `imageInToolResult: false` — a
+     * conservative assumption matching most OSS text-only OpenAI-compat
+     * endpoints. Override when routing to a known vision-capable endpoint
+     * (e.g. OpenRouter vision models, Baseten image-capable deployments).
+     */
+    capabilities?: ProviderCapabilities;
 }
 /**
  * Factory for any OpenAI-compatible HTTP endpoint.
@@ -477,6 +622,16 @@ declare function openaiCompat(params: OpenAICompatParams): Provider;
 interface OpenRouterParams {
     apiKey?: string;
     defaultModel?: string;
+    /**
+     * Provider capability flags. OpenRouter itself is a router — whether vision or
+     * native image-in-tool-result are supported depends on the downstream model.
+     * Default: `{ vision: true, imageInToolResult: false }` — matches the default
+     * `anthropic/claude-sonnet-4-6` model (vision-capable via companion user-message
+     * fallback since OpenRouter exposes Claude over the Chat Completions dialect).
+     *
+     * Override when routing to a known-text-only model (e.g. `meta-llama/llama-3-8b-instruct`).
+     */
+    capabilities?: ProviderCapabilities;
 }
 /**
  * OpenRouter provider.
@@ -498,7 +653,44 @@ interface ToolCall {
 }
 interface ToolResult {
     id: string;
-    content: string;
+    /**
+     * Tool output — plain string for text-only tools (the common case) or a structured
+     * array of content blocks for tools that return images or mixed content (e.g. an
+     * MCP browser server returning a screenshot).
+     *
+     * Use `toolResultToText(content)` when a downstream consumer only handles strings.
+     */
+    content: string | ToolResultContent[];
+}
+/**
+ * Provider-level capability flags used by the agent loop to route tool results
+ * and user messages appropriately.
+ *
+ * When a flag is `undefined` (omitted), the loop applies the conservative
+ * text-only default — images are stripped and replaced with a text marker so
+ * non-vision models do not confabulate about content they cannot see.
+ */
+interface ProviderCapabilities {
+    /**
+     * Model accepts image input anywhere (user messages and tool results).
+     *
+     * When `false`, the loop replaces image blocks with
+     * `"[image omitted — model does not support vision]"` before they reach the provider.
+     * Gives the model an honest marker instead of letting JSON-stringified base64 slip
+     * through and get confabulated over.
+     */
+    vision?: boolean;
+    /**
+     * Provider wire format embeds images inside tool-role messages natively
+     * (Anthropic `tool_result.content` arrays, OpenAI Codex pi-ai `toolResult` blocks).
+     *
+     * When `false`, a vision-capable provider still gets images — but via a
+     * companion `user` message emitted immediately after the flattened
+     * `tool`/`tool_result` marker. This is the Claude Desktop / Cline pattern
+     * and works on any OpenAI Chat Completions endpoint that accepts image
+     * URLs in user messages.
+     */
+    imageInToolResult?: boolean;
 }
 interface StreamCallbacks {
     onText: (delta: string) => void;
@@ -538,6 +730,8 @@ interface Provider {
     readonly name: string;
     readonly meta: {
         defaultModel: string;
+        /** Provider-level capability flags. See {@link ProviderCapabilities}. */
+        capabilities?: ProviderCapabilities;
     } & Record<string, unknown>;
     /** Format tool specs for this provider */
     formatTools: (tools: ToolSpec[]) => unknown[];
@@ -568,133 +762,6 @@ interface Provider {
     classifyError?: (err: unknown) => ClassifiedError | null;
 }
 
-/** Core tools available in every basic harness (without spawn) */
-declare const basicTools: {
-    shell: ToolDef;
-    readFile: ToolDef;
-    writeFile: ToolDef;
-    listFiles: ToolDef;
-};
-declare const _default: HarnessConfig;
-
-/**
- * Runtime context passed to every tool execution.
- * Provides access to the agent's provider, abort signal, execution environment, and hooks.
- */
-interface ToolContext {
-    /** The LLM provider for this agent run */
-    provider: Provider;
-    /** Abort signal — tools should check this for early termination */
-    signal: AbortSignal;
-    /** The execution context (shell, filesystem, etc.) */
-    execution: ExecutionContext;
-    /** The active execution handle for the current agent run */
-    handle: ExecutionHandle;
-    /** Agent hooks for emitting events (e.g. spawn:complete) */
-    hooks: Hookable<AgentHooks>;
-    /** The harness config for this agent (tools available to the agent) */
-    harness: HarnessConfig;
-    /** Turn ID that requested this tool call */
-    turnId: string;
-    /** Tool call ID from the model */
-    callId: string;
-}
-interface ToolDef {
-    spec: ToolSpec;
-    execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
-}
-type ToolMap = Map<string, ToolDef>;
-interface HarnessConfig {
-    /** Display name for this harness */
-    name: string;
-    /** Default system prompt injected when no system is provided at run time */
-    system?: string;
-    /** Tool definitions available to the agent */
-    tools: Record<string, ToolDef>;
-    /** MCP servers to connect and expose as tools */
-    mcpServers?: McpServerConfig[];
-    /** Skills configuration at the harness level */
-    skills?: SkillsConfig;
-    /** Default behavior for agents using this harness */
-    behavior?: AgentBehavior;
-    /**
-     * Map canonical tool names to LLM-facing (aliased) names.
-     *
-     * Aliasing is **LLM-boundary-only**:
-     * - The alias is what the provider's tool spec carries, what the model calls it, and
-     *   what appears in `ToolHookContext.displayName` / `McpToolHookContext.displayName`.
-     * - The canonical name is what lives in `session.turns`, `ToolHookContext.name`, and
-     *   what the agent uses to look up the tool implementation. Alias changes never
-     *   desync persisted history.
-     *
-     * Keys are canonical names from `tools` (or `mcp_{server}_{tool}` for MCP tools).
-     * Collisions between aliases are rejected by the loop.
-     *
-     * @example
-     * ```ts
-     * defineHarness({
-     *   tools: { ...basicTools },
-     *   toolAliases: { shell: 'Bash', read_file: 'Read', write_file: 'Write' },
-     * })
-     * ```
-     *
-     * @remarks Alias a tool only when the aliased name is semantically equivalent.
-     * `list_files` → `Glob` is NOT a valid alias because Glob is pattern-based.
-     */
-    toolAliases?: Record<string, string>;
-}
-/**
- * Define a harness with a name, optional system prompt, and tools.
- */
-declare function defineHarness(config: HarnessConfig): HarnessConfig;
-type Harness = HarnessConfig;
-/**
- * A harness with no tools — for pure chat mode.
- * Pass `tools: {}` in agent.run() or use this harness directly.
- */
-declare const noTools: HarnessConfig;
-
-/**
- * MCP (Model Context Protocol) server support.
- *
- * Connects to one or more MCP servers, discovers their tools,
- * and wraps them as zidane ToolDefs for use in agent loops.
- */
-
-interface McpConnection {
-    tools: Record<string, ToolDef>;
-    close: () => Promise<void>;
-}
-/**
- * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
- *
- * Accepts:
- * - `McpServerConfig[]` — zidane native (pass-through).
- * - `McpServerConfig` — a single config object (wrapped to a 1-element array).
- * - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
- * - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
- *
- * Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
- * cannot be inferred from a given entry, or when the input shape is unsupported.
- */
-declare function normalizeMcpServers(input: unknown): McpServerConfig[];
-/**
- * Convert MCP tool result content blocks to a single string.
- * Text blocks are extracted; non-text blocks are JSON-stringified.
- */
-declare function resultToString(content: unknown[]): string;
-/**
- * Connect to MCP servers and discover their tools.
- *
- * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
- * collisions with harness tools or tools from other servers.
- *
- * @param configs - Array of MCP server configurations
- * @param _clientFactory - Internal: override client construction for testing
- * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
- */
-declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
-
 /**
  * File-map session store.
  *
@@ -835,6 +902,17 @@ interface SessionRun {
     totalUsage?: TurnUsage;
     /** Estimated cost in USD */
     cost?: number;
+    /**
+     * The run that spawned this one, when the agent is a subagent sharing its
+     * parent's session. Undefined on top-level `agent.run()`. Consumers can walk
+     * `runs` by `parentRunId` to reconstruct the subagent tree.
+     */
+    parentRunId?: string;
+    /**
+     * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
+     * Recorded here so hosts can query/filter by level without walking the tree.
+     */
+    depth?: number;
 }
 interface SessionData {
     id: string;
@@ -891,8 +969,15 @@ interface Session {
     readonly runs: SessionRun[];
     /** Arbitrary metadata */
     readonly metadata: Record<string, unknown>;
-    /** Start tracking a new run */
-    startRun: (runId: string, prompt?: string) => void;
+    /**
+     * Start tracking a new run. `extras.parentRunId` + `extras.depth` are
+     * populated by the spawn tool when a child agent shares its parent's
+     * session; regular top-level `agent.run()` calls omit them.
+     */
+    startRun: (runId: string, prompt?: string, extras?: {
+        parentRunId?: string;
+        depth?: number;
+    }) => void;
     /** Mark a run as completed */
     completeRun: (runId: string, stats: {
         turns: number;
@@ -943,6 +1028,352 @@ declare function createSession(options?: CreateSessionOptions): Promise<Session>
  */
 declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
 
+/**
+ * Types for the Agent Skills system.
+ *
+ * Follows the Agent Skills open standard (agentskills.io/specification).
+ * Zidane-specific metadata conventionally uses the `zidane.` key prefix
+ * (e.g. `metadata['zidane.paths']`) to stay spec-compliant.
+ */
+interface SkillResource {
+    /** Relative path from skill directory */
+    path: string;
+    /** Resource type inferred from directory */
+    type: 'script' | 'reference' | 'asset' | 'other';
+}
+/**
+ * Where the skill came from. Used for collision precedence (project beats user)
+ * and for host SDKs to gate project-level skills on a trust check.
+ */
+type SkillSource = 'project' | 'user' | 'inline' | 'builtin';
+/** Severity + code for lenient-load warnings surfaced to host UIs. */
+interface SkillDiagnostic {
+    severity: 'warning' | 'error';
+    /** Stable machine-readable code (e.g. `name-mismatch-directory`). */
+    code: string;
+    /** Human-readable description. */
+    message: string;
+    /** Optional frontmatter field name the diagnostic relates to. */
+    field?: string;
+}
+interface SkillConfig {
+    /** Skill name: 1-64 chars, lowercase alphanumeric + hyphens */
+    name: string;
+    /** What the skill does and when to use it (1-1024 chars) */
+    description: string;
+    /** The SKILL.md body content (after YAML frontmatter) */
+    instructions: string;
+    /**
+     * Where this skill was loaded from. Drives collision precedence and the
+     * `trustProjectSkills` gate. Optional — `parseSkillFile` stamps it; raw
+     * fixtures that omit it are treated as `'project'` by downstream readers.
+     */
+    source?: SkillSource;
+    /** Absolute path to SKILL.md (undefined for inline skills) */
+    location?: string;
+    /** Skill directory path for resolving relative references */
+    baseDir?: string;
+    /** License identifier or reference */
+    license?: string;
+    /** Environment requirements */
+    compatibility?: string;
+    /**
+     * Flat key-value metadata bag per the spec. For Zidane-specific hints,
+     * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
+     */
+    metadata?: Record<string, string>;
+    /** Pre-approved tool names (experimental per spec) */
+    allowedTools?: string[];
+    /** Bundled resource files discovered in the skill directory */
+    resources?: SkillResource[];
+    /**
+     * Lenient-load warnings recorded during parsing. Host SDKs can surface these
+     * as inline UI hints. Absent when no issues were found.
+     */
+    diagnostics?: SkillDiagnostic[];
+}
+interface SkillsConfig {
+    /**
+     * Control which skills are active.
+     * - `true` (default): all discovered skills are enabled
+     * - `false` or `[]`: fully disable the skills system (no resolution, no catalog, no hooks)
+     * - `string[]`: allowlist — only skills with matching names are enabled
+     */
+    enabled?: boolean | string[];
+    /** Directories to scan for SKILL.md files */
+    scan?: string[];
+    /** Dynamic skills written to disk at agent start, then loaded normally */
+    write?: SkillConfig[];
+    /** Skill names to exclude from the catalog */
+    exclude?: string[];
+    /** Skip default scan paths (~/.agents/skills, .zidane/skills, etc.) */
+    skipDefaultPaths?: boolean;
+    /**
+     * Auto-inject `skills_use` / `skills_read` / `skills_run_script` tools
+     * when the catalog is non-empty. Default `true`. Set `false` to opt out
+     * (the system prompt will then instruct the model to use its file-read
+     * tool instead).
+     */
+    tool?: boolean;
+    /**
+     * Cap on concurrently active skills per run. Default `undefined` (unlimited).
+     * Attempts to activate past the cap throw from `skills_use`.
+     */
+    maxActive?: number;
+    /** Script timeout for `skills_run_script`, in milliseconds. Default `60000`. */
+    scriptTimeoutMs?: number;
+    /**
+     * When `false`, skills with `source: 'project'` are skipped during
+     * resolution with a diagnostic. Default `true` (preserves existing behavior).
+     * Useful for host SDKs handling untrusted repositories.
+     */
+    trustProjectSkills?: boolean;
+}
+
+/** Core tools available in every basic harness (without spawn) */
+declare const basicTools: {
+    shell: ToolDef;
+    readFile: ToolDef;
+    writeFile: ToolDef;
+    listFiles: ToolDef;
+};
+declare const _default: HarnessConfig;
+
+/**
+ * Runtime context passed to every tool execution.
+ * Provides access to the agent's provider, abort signal, execution environment, and hooks.
+ */
+interface ToolContext {
+    /** The LLM provider for this agent run */
+    provider: Provider;
+    /** Abort signal — tools should check this for early termination */
+    signal: AbortSignal;
+    /** The execution context (shell, filesystem, etc.) */
+    execution: ExecutionContext;
+    /** The active execution handle for the current agent run */
+    handle: ExecutionHandle;
+    /** Agent hooks for emitting events (e.g. spawn:complete) */
+    hooks: Hookable<AgentHooks>;
+    /** The harness config for this agent (tools available to the agent) */
+    harness: HarnessConfig;
+    /** Turn ID that requested this tool call */
+    turnId: string;
+    /** Tool call ID from the model */
+    callId: string;
+    /**
+     * The run id this tool call is part of. Populated by the agent loop when
+     * invoking tools. Optional on the type so host code constructing contexts
+     * by hand (tests, direct tool invocations) doesn't have to synthesize one.
+     *
+     * Spawn-style tools rely on this to tag child runs with `parentRunId` so
+     * the subagent tree can be reconstructed from a persisted session.
+     */
+    runId?: string;
+    /**
+     * The agent's session, when one was provided to `createAgent`. Tools that
+     * want to persist their own state (or, in the case of `spawn`, inherit the
+     * parent's session for child persistence) can read from here.
+     */
+    session?: Session;
+    /**
+     * Subagent depth for the agent owning this tool call. 0 = top-level,
+     * 1 = first-level child, … Used by spawn to enforce a `maxDepth` cap.
+     * Undefined is treated as 0 by spawn.
+     */
+    depth?: number;
+}
+interface ToolDef {
+    spec: ToolSpec;
+    /**
+     * Execute the tool and return its output.
+     *
+     * Return a plain string for text-only tools (the common case). Return a
+     * `ToolResultContent[]` when the tool produces non-text content (images, mixed
+     * text+image) that the provider can route through natively (Anthropic
+     * `tool_result.content` arrays, OpenAI Codex pi-ai) or through the
+     * companion-user-message fallback (OpenAI Chat Completions).
+     */
+    execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string | ToolResultContent[]>;
+}
+type ToolMap = Map<string, ToolDef>;
+interface HarnessConfig {
+    /** Display name for this harness */
+    name: string;
+    /** Default system prompt injected when no system is provided at run time */
+    system?: string;
+    /** Tool definitions available to the agent */
+    tools: Record<string, ToolDef>;
+    /** MCP servers to connect and expose as tools */
+    mcpServers?: McpServerConfig[];
+    /** Skills configuration at the harness level */
+    skills?: SkillsConfig;
+    /** Default behavior for agents using this harness */
+    behavior?: AgentBehavior;
+    /**
+     * Map canonical tool names to LLM-facing (aliased) names.
+     *
+     * Aliasing is **LLM-boundary-only**:
+     * - The alias is what the provider's tool spec carries, what the model calls it, and
+     *   what appears in `ToolHookContext.displayName` / `McpToolHookContext.displayName`.
+     * - The canonical name is what lives in `session.turns`, `ToolHookContext.name`, and
+     *   what the agent uses to look up the tool implementation. Alias changes never
+     *   desync persisted history.
+     *
+     * Keys are canonical names from `tools` (or `mcp_{server}_{tool}` for MCP tools).
+     * Collisions between aliases are rejected by the loop.
+     *
+     * @example
+     * ```ts
+     * defineHarness({
+     *   tools: { ...basicTools },
+     *   toolAliases: { shell: 'Bash', read_file: 'Read', write_file: 'Write' },
+     * })
+     * ```
+     *
+     * @remarks Alias a tool only when the aliased name is semantically equivalent.
+     * `list_files` → `Glob` is NOT a valid alias because Glob is pattern-based.
+     */
+    toolAliases?: Record<string, string>;
+}
+/**
+ * Define a harness with a name, optional system prompt, and tools.
+ */
+declare function defineHarness(config: HarnessConfig): HarnessConfig;
+type Harness = HarnessConfig;
+/**
+ * A harness with no tools — for pure chat mode.
+ * Pass `tools: {}` in agent.run() or use this harness directly.
+ */
+declare const noTools: HarnessConfig;
+
+/**
+ * MCP (Model Context Protocol) server support.
+ *
+ * Connects to one or more MCP servers, discovers their tools,
+ * and wraps them as zidane ToolDefs for use in agent loops.
+ */
+
+interface McpConnection {
+    tools: Record<string, ToolDef>;
+    close: () => Promise<void>;
+}
+/**
+ * Normalize MCP server configs from any common shape to `McpServerConfig[]`.
+ *
+ * Accepts:
+ * - `McpServerConfig[]` — zidane native (pass-through).
+ * - `McpServerConfig` — a single config object (wrapped to a 1-element array).
+ * - `Record<string, RawShape>` — name-keyed map (common in host-SDK configs), where the key is the server name.
+ * - Mixed shapes with `type` vs `transport`, `httpUrl`/`sseUrl` vs `url`.
+ *
+ * Returns `[]` when `input` is nullish. Throws a descriptive error when the transport
+ * cannot be inferred from a given entry, or when the input shape is unsupported.
+ */
+declare function normalizeMcpServers(input: unknown): McpServerConfig[];
+/**
+ * Lossy flattener — converts MCP `CallToolResult.content` blocks to a single string.
+ * Text blocks are extracted; non-text blocks are JSON-stringified.
+ *
+ * Prefer {@link normalizeMcpBlocks} for new code — it preserves image blocks so the
+ * provider can route them through to the model natively (Anthropic tool_result blocks,
+ * OpenAI companion-user-message). This function is kept for back-compat and is useful
+ * as a logging/display helper where a single string is required.
+ */
+declare function resultToString(content: unknown[]): string;
+/**
+ * Normalize MCP `CallToolResult.content` to zidane's {@link ToolResultContent[]} shape.
+ *
+ * Handles the four MCP content block types:
+ * - `text` → preserved as `{type:'text', text}`
+ * - `image` → preserved as `{type:'image', mediaType, data}` (MCP uses `mimeType`)
+ * - `resource` with embedded text → flattened to a text block
+ * - `resource` with embedded blob whose `mimeType` is `image/*` → flattened to an image block
+ * - Any unrecognized block → JSON-stringified fallback text block (lossy but safe)
+ *
+ * Returns `null` when the input is not an array — callers should fall back to an empty
+ * result in that case.
+ */
+declare function normalizeMcpBlocks(content: unknown): ToolResultContent[] | null;
+/**
+ * Connect to MCP servers and discover their tools.
+ *
+ * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
+ * collisions with harness tools or tools from other servers.
+ *
+ * @param configs - Array of MCP server configurations
+ * @param _clientFactory - Internal: override client construction for testing
+ * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
+ */
+declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
+
+/**
+ * Per-agent skill activation state machine.
+ *
+ * Tracks which skills are active across a run. The three skills tools
+ * (`skills_use` / `skills_read` / `skills_run_script`) read from this state
+ * for gating + listing. Allowed-tools enforcement reads from it too.
+ *
+ * Lifecycle:
+ * - Storage lives on the agent instance (created once in `createAgent`), but
+ *   every `run()` ends with an implicit deactivate-all pass (reason `'run-end'`)
+ *   so activation does **not** persist across run boundaries. To keep a skill
+ *   active across successive runs, call `agent.activateSkill(name)` before each
+ *   run — the explicit-activation path is idempotent.
+ * - `agent.reset()` clears the state with reason `'reset'`.
+ * - On session-resume, carried-forward `skills_use` tool_call blocks (in prior
+ *   assistant turns) are replayed at run-start to rehydrate state with
+ *   `via: 'resume'`.
+ *
+ * The caps (`maxActive` from SkillsConfig) is enforced here — returning `false`
+ * from `activate()` when the cap is hit lets the caller surface an actionable
+ * "max skills active" error to the model.
+ */
+
+/** How a skill was activated. Surfaced in `skills:activate` hook ctx. */
+type ActivationVia = 'model' | 'explicit' | 'resume';
+/** Reason a skill was deactivated. Surfaced in `skills:deactivate` hook ctx. */
+type DeactivationReason = 'run-end' | 'explicit' | 'reset';
+/** A skill currently active in the state machine. */
+interface ActiveSkill {
+    skill: SkillConfig;
+    activatedAt: number;
+    activatedVia: ActivationVia;
+}
+/**
+ * Per-agent skill activation state. Public read-surface is the `active()` list
+ * and `isActive(name)` predicate; writes go through `activate()` / `deactivate()`.
+ */
+interface SkillActivationState {
+    /** List of currently active skills in activation order. Returns a snapshot. */
+    active: () => readonly ActiveSkill[];
+    /** Is the skill with this canonical name currently active? */
+    isActive: (name: string) => boolean;
+    /** Retrieve the `ActiveSkill` record by name, or `undefined`. */
+    get: (name: string) => ActiveSkill | undefined;
+    /**
+     * Mark a skill as active.
+     * - Returns `'ok'` on a fresh activation (caller should fire `skills:activate`).
+     * - Returns `'already-active'` if the skill was already in the set (idempotent).
+     * - Returns `'cap-reached'` if the `maxActive` cap would be exceeded. State is unchanged.
+     */
+    activate: (skill: SkillConfig, via: ActivationVia) => 'ok' | 'already-active' | 'cap-reached';
+    /**
+     * Mark a skill as inactive. Returns the removed `ActiveSkill` record or `undefined`
+     * if it wasn't active. Callers fire `skills:deactivate` on removal.
+     */
+    deactivate: (name: string) => ActiveSkill | undefined;
+    /** Remove every active skill. Returns the list of removed records. */
+    clear: () => readonly ActiveSkill[];
+}
+interface SkillActivationStateOptions {
+    /**
+     * Cap on concurrent activations. `undefined` (the default) disables the cap.
+     * When set, `activate()` returns `'cap-reached'` once the set is at size `maxActive`.
+     */
+    maxActive?: number;
+}
+declare function createSkillActivationState(options?: SkillActivationStateOptions): SkillActivationState;
+
 /**
  * Agent creation and state management.
  */
@@ -980,13 +1411,13 @@ interface AgentHooks {
     }) => void;
     'tool:before': (ctx: ToolHookContext) => void;
     'tool:after': (ctx: ToolHookContext & {
-        result: string;
+        result: string | ToolResultContent[];
     }) => void;
     'tool:error': (ctx: ToolHookContext & {
         error: Error;
     }) => void;
     'tool:transform': (ctx: ToolHookContext & {
-        result: string;
+        result: string | ToolResultContent[];
         isError: boolean;
     }) => void;
     'context:transform': (ctx: {
@@ -1000,6 +1431,45 @@ interface AgentHooks {
     'spawn:error': (ctx: SpawnHookContext & {
         error: Error;
     }) => void;
+    'child:stream:text': (ctx: StreamHookContext & {
+        delta: string;
+        text: string;
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:stream:thinking': (ctx: StreamHookContext & {
+        delta: string;
+        thinking: string;
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:stream:end': (ctx: StreamHookContext & {
+        text: string;
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:tool:before': (ctx: ToolHookContext & {
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:tool:after': (ctx: ToolHookContext & {
+        result: string | ToolResultContent[];
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:tool:error': (ctx: ToolHookContext & {
+        error: Error;
+        childId: string;
+        depth: number;
+    }) => void;
+    'child:turn:after': (ctx: {
+        turn: number;
+        turnId: string;
+        usage: TurnUsage;
+        message: SessionTurn;
+        childId: string;
+        depth: number;
+    }) => void;
     'mcp:connect': (ctx: {
         name: string;
         transport: string;
@@ -1018,10 +1488,10 @@ interface AgentHooks {
     }) => void;
     'mcp:tool:before': (ctx: McpToolHookContext) => void;
     'mcp:tool:after': (ctx: McpToolHookContext & {
-        result: string;
+        result: string | ToolResultContent[];
     }) => void;
     'mcp:tool:transform': (ctx: McpToolHookContext & {
-        result: string;
+        result: string | ToolResultContent[];
     }) => void;
     'mcp:tool:error': (ctx: McpToolHookContext & {
         error: Error;
@@ -1035,6 +1505,11 @@ interface AgentHooks {
     }) => void;
     'skills:activate': (ctx: {
         skill: SkillConfig;
+        via: ActivationVia;
+    }) => void;
+    'skills:deactivate': (ctx: {
+        skill: SkillConfig;
+        reason: DeactivationReason;
     }) => void;
     'usage': (ctx: {
         turn: number;
@@ -1092,16 +1567,38 @@ interface Agent {
     steer: (message: string) => void;
     followUp: (message: string) => void;
     waitForIdle: () => Promise<void>;
-    reset: () => void;
-    /** Destroy the execution context and clean up resources */
+    /**
+     * Clear the agent's in-memory state (turns, queues, skill activations).
+     * Fires `skills:deactivate` with `reason: 'reset'` for each previously active
+     * skill. Awaiting lets host apps observe listener rejections.
+     */
+    reset: () => Promise<void>;
+    /**
+     * Destroy the execution context and clean up resources.
+     * Idempotent — safe to call from both a `finally` block and a signal handler.
+     */
     destroy: () => Promise<void>;
+    /**
+     * Explicitly activate a skill by name. Fires `skills:activate` with
+     * `via: 'explicit'`. Throws if the skill isn't in the resolved catalog or
+     * if the `maxActive` cap is reached. Idempotent — activating an already-active
+     * skill is a no-op.
+     */
+    activateSkill: (name: string) => Promise<void>;
+    /**
+     * Deactivate a skill by name. Fires `skills:deactivate` with `reason: 'explicit'`.
+     * No-op when the skill wasn't active.
+     */
+    deactivateSkill: (name: string) => Promise<void>;
     readonly isRunning: boolean;
     readonly turns: SessionTurn[];
     readonly execution: ExecutionContext;
     readonly handle: ExecutionHandle | null;
     readonly session: Session | null;
+    /** Snapshot of currently active skills. */
+    readonly activeSkills: readonly ActiveSkill[];
     meta: Record<string, unknown>;
 }
 declare function createAgent({ harness: harnessOption, provider, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
 
-export { type ToolSpec as $, type Agent as A, type SessionEndStatus as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionHookContext as D, type SessionMessage as E, type SessionRun as F, type SessionStore as G, type Harness as H, type ImageContent as I, type SessionTurn as J, type SpawnHookContext as K, type StreamCallbacks as L, type McpConnection as M, type StreamHookContext as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type StreamOptions as Q, type RemoteStoreOptions as R, type Session as S, type ThinkingLevel as T, type ToolCall as U, type ToolContext as V, type ToolDef as W, type ToolExecutionMode as X, type ToolHookContext as Y, type ToolMap as Z, type ToolResult as _, AgentAbortedError as a, type TurnFinishReason as a0, type TurnResult as a1, type TurnUsage as a2, matchesContextExceeded as a3, type FileMapAdapter as a4, type FileMapStoreOptions as a5, type OpenAICompatAuthHeader as a6, OpenAICompatHttpError as a7, type OpenAICompatParams as a8, anthropic as a9, autoDetectAndConvert as aa, cerebras as ab, classifyOpenAICompatError as ac, connectMcpServers as ad, createAgent as ae, createFileMapStore as af, createMemoryStore as ag, createRemoteStore as ah, createSession as ai, defineHarness as aj, fromAnthropic as ak, fromOpenAI as al, loadSession as am, mapOAIFinishReason as an, noTools as ao, normalizeMcpServers as ap, openai as aq, openaiCompat as ar, openrouter as as, toAnthropic as at, toOpenAI as au, toTypedError as av, _default as aw, basicTools as ax, resultToString as ay, 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, type AnthropicParams as i, type CerebrasParams as j, type ChildRunStats as k, type ClassifiedError as l, type ClassifiedErrorKind as m, type CreateSessionOptions as n, type HarnessConfig 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 RunHookMap as x, type SessionContentBlock as y, type SessionData as z };
+export { type ToolDef as $, type Agent as A, type SessionContentBlock as B, CONTEXT_EXCEEDED_MESSAGE_PATTERNS as C, type SessionData as D, type SessionEndStatus as E, type SessionHookContext as F, type SessionMessage as G, type Harness as H, type ImageContent as I, type SessionRun as J, type SessionStore as K, type SessionTurn as L, type McpConnection as M, type SkillConfig as N, type OAuthRefreshHookContext as O, type PromptDocumentPart as P, type SkillResource as Q, type RemoteStoreOptions as R, type Session as S, type SkillsConfig as T, type SpawnHookContext as U, type StreamCallbacks as V, type StreamHookContext as W, type StreamOptions as X, type ThinkingLevel as Y, type ToolCall as Z, type ToolContext as _, AgentAbortedError as a, type ToolExecutionMode as a0, type ToolHookContext as a1, type ToolMap as a2, type ToolResult as a3, type ToolResultContent as a4, type ToolResultImageContent as a5, type ToolResultTextContent as a6, type ToolSpec as a7, type TurnFinishReason as a8, type TurnResult as a9, defineHarness as aA, fromAnthropic as aB, fromOpenAI as aC, loadSession as aD, mapOAIFinishReason as aE, noTools as aF, normalizeMcpBlocks as aG, normalizeMcpServers as aH, openai as aI, openaiCompat as aJ, openrouter as aK, resultToString as aL, toAnthropic as aM, toOpenAI as aN, toTypedError as aO, _default as aP, basicTools as aQ, type TurnUsage as aa, matchesContextExceeded as ab, toolResultToText as ac, type ActivationVia as ad, type ActiveSkill as ae, type DeactivationReason as af, type FileMapAdapter as ag, type FileMapStoreOptions as ah, type OpenAICompatAuthHeader as ai, OpenAICompatHttpError as aj, type OpenAICompatParams as ak, type SkillActivationState as al, type SkillActivationStateOptions as am, type SkillDiagnostic as an, type SkillSource as ao, anthropic as ap, autoDetectAndConvert as aq, cerebras as ar, classifyOpenAICompatError as as, connectMcpServers as at, createAgent as au, createFileMapStore as av, createMemoryStore as aw, createRemoteStore as ax, createSession as ay, createSkillActivationState 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 HarnessConfig as p, type McpServerConfig as q, type McpToolHookContext as r, type OpenAIParams as s, type OpenRouterParams as t, type PromptImagePart as u, type PromptPart as v, type PromptTextPart as w, type Provider as x, type ProviderCapabilities as y, type RunHookMap as z };