zidane 2.0.1 → 2.2.0

package/dist/{agent-D-ZFMbSd.d.ts → agent-vPBFXnu-.d.ts}

@@ -6,7 +6,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
  * Typed error classes for agent runs.
  *
  * Providers classify native errors into one of these so downstream consumers
- * (e.g. harness adapters) can react without string-sniffing messages.
+ * can react without string-sniffing messages.
  *
  * Provider authors: implement `Provider.classifyError` to map native errors
  * (SDK exceptions, HTTP responses) to a `ClassifiedError`. The loop wraps
@@ -21,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`) */
@@ -29,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.
@@ -48,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);
 }
 /**
@@ -295,9 +310,9 @@ interface AgentRunOptions {
     images?: ImageContent[];
     /** Abort signal — when triggered, the agent stops after the current turn */
     signal?: AbortSignal;
-    /** Behavior overrides for this run (overrides agent and harness defaults) */
+    /** Behavior overrides for this run (overrides agent defaults) */
     behavior?: AgentBehavior;
-    /** Tool overrides for this run. Pass {} for no tools. Omit to use harness tools. */
+    /** Tool overrides for this run. Pass {} for no tools. Omit to use agent tools. */
     tools?: Record<string, ToolDef>;
     /**
      * Per-run hook registrations. Each hook is attached before the run starts and
@@ -306,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';
@@ -356,15 +383,33 @@ 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.
  *
- * `name` is the canonical tool identity — the spec name defined in the harness (or the
+ * `name` is the canonical tool identity — the spec name registered on the agent (or the
  * `mcp_{server}_{tool}` name for MCP tools). Hooks should policy-match against `name`.
  *
  * `displayName` is the outward-facing name — the alias surfaced to the LLM when
- * `HarnessConfig.toolAliases` maps the canonical name; otherwise equal to `name`.
+ * `AgentOptions.toolAliases` maps the canonical name; otherwise equal to `name`.
  * UI/telemetry adapters should emit `displayName`.
  *
  * Canonical vs. alias matters on session resume: `session.turns` persists canonical
@@ -373,7 +418,7 @@ interface ChildRunStats {
 interface ToolHookContext {
     turnId: string;
     callId: string;
-    /** Canonical tool name (harness spec name). Stable across alias-map changes. */
+    /** Canonical tool name (spec name). Stable across alias-map changes. */
     name: string;
     /** Aliased (wire) name — equal to `name` when no alias is defined. */
     displayName: string;
@@ -385,8 +430,8 @@ interface ToolHookContext {
  * `tool` is the native tool name on the MCP server. `server` is the configured server
  * name. The canonical zidane-namespaced identity is `mcp_{server}_{tool}`.
  *
- * `displayName` equals the canonical namespaced name unless the harness has aliased
- * this MCP tool via `HarnessConfig.toolAliases`; in which case `displayName` is the
+ * `displayName` equals the canonical namespaced name unless the agent has aliased
+ * this MCP tool via `AgentOptions.toolAliases`; in which case `displayName` is the
  * alias that the LLM sees.
  */
 interface McpToolHookContext {
@@ -406,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 {
@@ -711,263 +762,6 @@ interface Provider {
     classifyError?: (err: unknown) => ClassifiedError | 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;
-}
-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>;
-
 /**
  * File-map session store.
  *
@@ -1108,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;
@@ -1164,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;
@@ -1216,6 +1028,250 @@ 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;
+}
+
+/**
+ * Runtime context passed to every tool execution.
+ * Provides access to the agent's provider, abort signal, execution environment, and hooks.
+ *
+ * The preset-y fields (`name`, `system`, `tools`, `toolAliases`, `mcpServers`, `skills`,
+ * `behavior`) mirror the agent's own options so child-spawning tools can inherit them.
+ */
+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>;
+    /** Agent display name (preset or user-supplied) */
+    name?: string;
+    /** Agent default system prompt */
+    system?: string;
+    /** Source tool map the agent was created with (pre-MCP-merge, pre-skills-injection) */
+    tools: Record<string, ToolDef>;
+    /**
+     * 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.
+     */
+    toolAliases?: Record<string, string>;
+    /** MCP servers configured on the agent (for child inheritance) */
+    mcpServers?: McpServerConfig[];
+    /** Skills configuration (for child inheritance) */
+    skills?: SkillsConfig;
+    /** Behavior defaults (for child inheritance) */
+    behavior?: AgentBehavior;
+    /** 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>;
+
+/**
+ * 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 agent 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.
  *
@@ -1341,6 +1397,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;
@@ -1415,9 +1510,21 @@ interface AgentHooks {
     'session:save': (ctx: SessionHookContext) => void;
 }
 interface AgentOptions {
-    /** Harness (tools + system prompt). Defaults to a no-tools harness if omitted. */
-    harness?: HarnessConfig;
     provider: Provider;
+    /** Display name for the agent (used in traces/logs). */
+    name?: string;
+    /** Default system prompt injected when no system is provided at run time. */
+    system?: string;
+    /** Tool definitions available to the agent. Defaults to no tools. */
+    tools?: Record<string, ToolDef>;
+    /**
+     * Map canonical tool names to LLM-facing (aliased) names.
+     *
+     * Aliasing is **LLM-boundary-only**: the alias is what the provider's tool spec
+     * carries and what the model calls the tool; the canonical name is what lives in
+     * `session.turns` and what the agent uses to look up the tool implementation.
+     */
+    toolAliases?: Record<string, string>;
     /** Agent-level behavior defaults (overridden by run-level behavior) */
     behavior?: AgentBehavior;
     /** Execution context: where tools run. Defaults to in-process. */
@@ -1426,7 +1533,7 @@ interface AgentOptions {
     mcpServers?: McpServerConfig[];
     /** Session for identity, turn persistence, and run tracking */
     session?: Session;
-    /** Skills configuration (merged with harness-level skills, agent takes precedence) */
+    /** Skills configuration */
     skills?: SkillsConfig;
     /** @internal */
     _mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
@@ -1438,8 +1545,16 @@ 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
@@ -1462,6 +1577,6 @@ interface Agent {
     readonly activeSkills: readonly ActiveSkill[];
     meta: Record<string, unknown>;
 }
-declare function createAgent({ harness: harnessOption, provider, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
+declare function createAgent({ provider, name: agentName, system: agentSystem, tools: agentTools, toolAliases, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
 
-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 };
+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 };