zidane 2.0.1 → 2.1.1

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

@@ -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);
 }
 /**
@@ -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,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.
@@ -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 {
@@ -712,79 +763,345 @@ interface Provider {
 }
 
 /**
- * Types for the Agent Skills system.
+ * File-map session store.
  *
- * 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.
+ * Wraps a narrow 3-method adapter (`get` / `save` / `delete`) that exchanges a flat
+ * map of filename → string content. Useful for embedding zidane sessions inside
+ * host-provided session backends that only speak in file maps (not zidane's native
+ * `SessionStore` shape).
+ *
+ * Serialization format:
+ * - `turns.jsonl` — one `SessionTurn` per line.
+ * - `meta.json` — session metadata (id, agentId, status, runs, metadata, timestamps).
+ *
+ * JSONL for turns keeps history inspectable with tools like `jq` and resilient to
+ * partial corruption — parse up to the first bad line and you still have a valid
+ * prefix. Metadata lives in its own file so large turn logs don't bloat the
+ * metadata path.
+ *
+ * Scope: each `createFileMapStore` handles a **single session** — the adapter's
+ * file map holds at most one zidane session at a time. This matches how host SDKs
+ * scope their session stores per conversation.
+ *
+ * Divergences from the built-in memory / sqlite stores:
+ * - `appendTurns` / `updateStatus` / `updateRun` auto-create a minimal `SessionData`
+ *   record on first write, instead of silently no-oping when the session hasn't been
+ *   explicitly `save()`-ed. This matches the host-SDK integration path where
+ *   `createSession(...)` → `agent.run(...)` directly without an explicit `save()` call.
+ * - `updateRun` inserts the run if not found in the cached record (rather than
+ *   silently dropping). Run records therefore always reach the adapter.
  */
-interface SkillResource {
-    /** Relative path from skill directory */
-    path: string;
-    /** Resource type inferred from directory */
-    type: 'script' | 'reference' | 'asset' | 'other';
+
+/**
+ * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
+ * payloads — the whole persistence surface the wrapper needs.
+ */
+interface FileMapAdapter {
+    /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
+    get: () => Promise<{
+        files: Record<string, string>;
+    }>;
+    /** Replace the persisted file map. Full-rewrite semantics. */
+    save: (files: Record<string, string>) => Promise<void>;
+    /** Delete all persisted state. */
+    delete: () => Promise<void>;
+}
+interface FileMapStoreOptions {
+    /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
+    turnsFile?: string;
+    /** Filename for the metadata JSON. Default: `meta.json`. */
+    metaFile?: string;
 }
 /**
- * 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.
+ * Create a single-session `SessionStore` backed by a file-map adapter.
+ *
+ * @example
+ * ```ts
+ * const session = await createSession({
+ *   store: createFileMapStore(hostSessionStore),
+ * })
+ * ```
  */
-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;
+declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
+
+/**
+ * In-memory session store.
+ * Useful for development and testing. Data is lost when the process exits.
+ */
+
+declare function createMemoryStore(): SessionStore;
+
+/**
+ * Canonical SessionMessage format with converters from/to Anthropic and OpenAI-compat formats.
+ */
+
+declare function fromAnthropic(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+declare function fromOpenAI(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+declare function toAnthropic(msg: SessionMessage): {
+    role: string;
+    content: unknown;
+};
+declare function toOpenAI(msg: SessionMessage): {
+    role: string;
+    content: unknown;
+};
+declare function autoDetectAndConvert(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+
+/**
+ * Remote session store via HTTP API.
+ *
+ * Expects a REST API with:
+ *   GET    {url}/sessions/{id}                    -> SessionData | 404
+ *   PUT    {url}/sessions/{id}                    -> save SessionData
+ *   DELETE {url}/sessions/{id}                    -> delete
+ *   GET    {url}/sessions?agentId=&limit=         -> { ids: string[] }
+ *   POST   {url}/sessions/{id}/turns              -> append turns
+ *   GET    {url}/sessions/{id}/turns?from=&limit= -> SessionTurn[]
+ *   PUT    {url}/sessions/{id}/runs/{runId}        -> update run
+ *   PATCH  {url}/sessions/{id}                    -> { status }
+ */
+
+interface RemoteStoreOptions {
+    /** Base URL of the session API */
+    url: string;
+    /** Optional headers (e.g. for authentication) */
+    headers?: Record<string, 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;
+declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
+
+/**
+ * Session management for agents.
+ *
+ * A session tracks identity, turn history, and run metadata.
+ * Plug in any storage backend by implementing the SessionStore interface,
+ * or use one of the built-in stores: memory, sqlite, remote.
+ */
+
+interface SessionRun {
+    id: string;
+    startedAt: number;
+    endedAt?: number;
+    prompt: string;
+    status: 'running' | 'completed' | 'aborted' | 'error';
+    turns?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    error?: string;
+    /** Per-turn usage breakdown */
+    turnUsage?: TurnUsage[];
+    /** Total usage across all turns */
+    totalUsage?: TurnUsage;
+    /** Estimated cost in USD */
+    cost?: number;
     /**
-     * Flat key-value metadata bag per the spec. For Zidane-specific hints,
-     * use the `zidane.` key prefix (e.g. `metadata['zidane.paths']`).
+     * 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.
      */
-    metadata?: Record<string, string>;
-    /** Pre-approved tool names (experimental per spec) */
-    allowedTools?: string[];
-    /** Bundled resource files discovered in the skill directory */
-    resources?: SkillResource[];
+    parentRunId?: string;
     /**
-     * Lenient-load warnings recorded during parsing. Host SDKs can surface these
-     * as inline UI hints. Absent when no issues were found.
+     * Zero-based subagent depth. 0 = top-level run, 1 = direct child, …
+     * Recorded here so hosts can query/filter by level without walking the tree.
      */
-    diagnostics?: SkillDiagnostic[];
+    depth?: number;
 }
-interface SkillsConfig {
+interface SessionData {
+    id: string;
+    agentId?: string;
+    turns: SessionTurn[];
+    runs: SessionRun[];
+    status: 'idle' | 'running' | 'completed' | 'error';
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionStore {
+    /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
+    generateSessionId?: () => string | Promise<string>;
+    /** Optional: generate a turn ID server-side. */
+    generateTurnId?: () => string | Promise<string>;
+    /** Load a session by ID. Returns null if not found. */
+    load: (sessionId: string) => Promise<SessionData | null>;
+    /** Save a session (create or update, full document). */
+    save: (session: SessionData) => Promise<void>;
+    /** Delete a session. */
+    delete: (sessionId: string) => Promise<void>;
+    /** List session IDs, optionally filtered. */
+    list: (filter?: {
+        agentId?: string;
+        limit?: number;
+    }) => Promise<string[]>;
+    /** Append new turns to a session (incremental, avoids full re-save). */
+    appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
+    /** Return a slice of turns for a session. */
+    getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
+    /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
+    updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
+    /** Update the top-level status of a session. */
+    updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
+}
+interface Session {
+    /** Session ID */
+    readonly id: string;
+    /** Agent ID (optional label) */
+    readonly agentId?: string;
+    /** Current turn history */
+    readonly turns: SessionTurn[];
     /**
-     * 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
+     * True when this session has no turns yet.
+     *
+     * Use this as a first-prompt signal when setting up a run — e.g. writing initial
+     * configuration only on fresh sessions. Equivalent to `turns.length === 0`.
      */
-    enabled?: boolean | string[];
-    /** Directories to scan for SKILL.md files */
-    scan?: string[];
+    readonly isEmpty: boolean;
+    /** Top-level session status */
+    readonly status: SessionData['status'];
+    /** All runs in this session */
+    readonly runs: SessionRun[];
+    /** Arbitrary metadata */
+    readonly metadata: Record<string, unknown>;
+    /**
+     * 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;
+        tokensIn: number;
+        tokensOut: number;
+        turnUsage?: TurnUsage[];
+        cost?: number;
+    }) => void;
+    /** Mark a run as aborted */
+    abortRun: (runId: string) => void;
+    /** Mark a run as errored */
+    errorRun: (runId: string, error: string) => void;
+    /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
+    appendTurns: (turns: SessionTurn[]) => Promise<void>;
+    /** Replace all turns in-memory (does not persist — use save() for that) */
+    setTurns: (turns: SessionTurn[]) => void;
+    /** Update the session status in memory AND via store.updateStatus (if store present) */
+    updateStatus: (status: SessionData['status']) => Promise<void>;
+    /** Persist an updated run record via store.updateRun (if store present) */
+    updateRun: (run: SessionRun) => Promise<void>;
+    /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
+    generateTurnId: () => string | Promise<string>;
+    /** Set metadata key */
+    setMeta: (key: string, value: unknown) => void;
+    /** Persist the full session document to the store */
+    save: () => Promise<void>;
+    /** Serialize to SessionData */
+    toJSON: () => SessionData;
+}
+interface CreateSessionOptions {
+    /** Session ID. If omitted and store provides generateSessionId, that is used. */
+    id?: string;
+    /** Agent ID label */
+    agentId?: string;
+    /** Initial metadata */
+    metadata?: Record<string, unknown>;
+    /** Storage backend (optional, enables save/load) */
+    store?: SessionStore;
+    _data?: SessionData;
+}
+/**
+ * Create a new session.
+ * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
+ */
+declare function createSession(options?: CreateSessionOptions): Promise<Session>;
+/**
+ * Load an existing session from a store.
+ */
+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 */
@@ -843,6 +1160,27 @@ interface ToolContext {
     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;
@@ -968,254 +1306,6 @@ declare function normalizeMcpBlocks(content: unknown): ToolResultContent[] | nul
  */
 declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
 
-/**
- * File-map session store.
- *
- * Wraps a narrow 3-method adapter (`get` / `save` / `delete`) that exchanges a flat
- * map of filename → string content. Useful for embedding zidane sessions inside
- * host-provided session backends that only speak in file maps (not zidane's native
- * `SessionStore` shape).
- *
- * Serialization format:
- * - `turns.jsonl` — one `SessionTurn` per line.
- * - `meta.json` — session metadata (id, agentId, status, runs, metadata, timestamps).
- *
- * JSONL for turns keeps history inspectable with tools like `jq` and resilient to
- * partial corruption — parse up to the first bad line and you still have a valid
- * prefix. Metadata lives in its own file so large turn logs don't bloat the
- * metadata path.
- *
- * Scope: each `createFileMapStore` handles a **single session** — the adapter's
- * file map holds at most one zidane session at a time. This matches how host SDKs
- * scope their session stores per conversation.
- *
- * Divergences from the built-in memory / sqlite stores:
- * - `appendTurns` / `updateStatus` / `updateRun` auto-create a minimal `SessionData`
- *   record on first write, instead of silently no-oping when the session hasn't been
- *   explicitly `save()`-ed. This matches the host-SDK integration path where
- *   `createSession(...)` → `agent.run(...)` directly without an explicit `save()` call.
- * - `updateRun` inserts the run if not found in the cached record (rather than
- *   silently dropping). Run records therefore always reach the adapter.
- */
-
-/**
- * Host-provided file-map adapter. Three methods exchanging `Record<string, string>`
- * payloads — the whole persistence surface the wrapper needs.
- */
-interface FileMapAdapter {
-    /** Load the current file map. Returns an empty `files` record when nothing is persisted. */
-    get: () => Promise<{
-        files: Record<string, string>;
-    }>;
-    /** Replace the persisted file map. Full-rewrite semantics. */
-    save: (files: Record<string, string>) => Promise<void>;
-    /** Delete all persisted state. */
-    delete: () => Promise<void>;
-}
-interface FileMapStoreOptions {
-    /** Filename for the JSONL turns log. Default: `turns.jsonl`. */
-    turnsFile?: string;
-    /** Filename for the metadata JSON. Default: `meta.json`. */
-    metaFile?: string;
-}
-/**
- * Create a single-session `SessionStore` backed by a file-map adapter.
- *
- * @example
- * ```ts
- * const session = await createSession({
- *   store: createFileMapStore(hostSessionStore),
- * })
- * ```
- */
-declare function createFileMapStore(adapter: FileMapAdapter, options?: FileMapStoreOptions): SessionStore;
-
-/**
- * In-memory session store.
- * Useful for development and testing. Data is lost when the process exits.
- */
-
-declare function createMemoryStore(): SessionStore;
-
-/**
- * Canonical SessionMessage format with converters from/to Anthropic and OpenAI-compat formats.
- */
-
-declare function fromAnthropic(msg: {
-    role: string;
-    content: unknown;
-}): SessionMessage;
-declare function fromOpenAI(msg: {
-    role: string;
-    content: unknown;
-}): SessionMessage;
-declare function toAnthropic(msg: SessionMessage): {
-    role: string;
-    content: unknown;
-};
-declare function toOpenAI(msg: SessionMessage): {
-    role: string;
-    content: unknown;
-};
-declare function autoDetectAndConvert(msg: {
-    role: string;
-    content: unknown;
-}): SessionMessage;
-
-/**
- * Remote session store via HTTP API.
- *
- * Expects a REST API with:
- *   GET    {url}/sessions/{id}                    -> SessionData | 404
- *   PUT    {url}/sessions/{id}                    -> save SessionData
- *   DELETE {url}/sessions/{id}                    -> delete
- *   GET    {url}/sessions?agentId=&limit=         -> { ids: string[] }
- *   POST   {url}/sessions/{id}/turns              -> append turns
- *   GET    {url}/sessions/{id}/turns?from=&limit= -> SessionTurn[]
- *   PUT    {url}/sessions/{id}/runs/{runId}        -> update run
- *   PATCH  {url}/sessions/{id}                    -> { status }
- */
-
-interface RemoteStoreOptions {
-    /** Base URL of the session API */
-    url: string;
-    /** Optional headers (e.g. for authentication) */
-    headers?: Record<string, string>;
-}
-declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
-
-/**
- * Session management for agents.
- *
- * A session tracks identity, turn history, and run metadata.
- * Plug in any storage backend by implementing the SessionStore interface,
- * or use one of the built-in stores: memory, sqlite, remote.
- */
-
-interface SessionRun {
-    id: string;
-    startedAt: number;
-    endedAt?: number;
-    prompt: string;
-    status: 'running' | 'completed' | 'aborted' | 'error';
-    turns?: number;
-    tokensIn?: number;
-    tokensOut?: number;
-    error?: string;
-    /** Per-turn usage breakdown */
-    turnUsage?: TurnUsage[];
-    /** Total usage across all turns */
-    totalUsage?: TurnUsage;
-    /** Estimated cost in USD */
-    cost?: number;
-}
-interface SessionData {
-    id: string;
-    agentId?: string;
-    turns: SessionTurn[];
-    runs: SessionRun[];
-    status: 'idle' | 'running' | 'completed' | 'error';
-    metadata: Record<string, unknown>;
-    createdAt: number;
-    updatedAt: number;
-}
-interface SessionStore {
-    /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
-    generateSessionId?: () => string | Promise<string>;
-    /** Optional: generate a turn ID server-side. */
-    generateTurnId?: () => string | Promise<string>;
-    /** Load a session by ID. Returns null if not found. */
-    load: (sessionId: string) => Promise<SessionData | null>;
-    /** Save a session (create or update, full document). */
-    save: (session: SessionData) => Promise<void>;
-    /** Delete a session. */
-    delete: (sessionId: string) => Promise<void>;
-    /** List session IDs, optionally filtered. */
-    list: (filter?: {
-        agentId?: string;
-        limit?: number;
-    }) => Promise<string[]>;
-    /** Append new turns to a session (incremental, avoids full re-save). */
-    appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
-    /** Return a slice of turns for a session. */
-    getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
-    /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
-    updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
-    /** Update the top-level status of a session. */
-    updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
-}
-interface Session {
-    /** Session ID */
-    readonly id: string;
-    /** Agent ID (optional label) */
-    readonly agentId?: string;
-    /** Current turn history */
-    readonly turns: SessionTurn[];
-    /**
-     * True when this session has no turns yet.
-     *
-     * Use this as a first-prompt signal when setting up a run — e.g. writing initial
-     * configuration only on fresh sessions. Equivalent to `turns.length === 0`.
-     */
-    readonly isEmpty: boolean;
-    /** Top-level session status */
-    readonly status: SessionData['status'];
-    /** All runs in this session */
-    readonly runs: SessionRun[];
-    /** Arbitrary metadata */
-    readonly metadata: Record<string, unknown>;
-    /** Start tracking a new run */
-    startRun: (runId: string, prompt?: string) => void;
-    /** Mark a run as completed */
-    completeRun: (runId: string, stats: {
-        turns: number;
-        tokensIn: number;
-        tokensOut: number;
-        turnUsage?: TurnUsage[];
-        cost?: number;
-    }) => void;
-    /** Mark a run as aborted */
-    abortRun: (runId: string) => void;
-    /** Mark a run as errored */
-    errorRun: (runId: string, error: string) => void;
-    /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
-    appendTurns: (turns: SessionTurn[]) => Promise<void>;
-    /** Replace all turns in-memory (does not persist — use save() for that) */
-    setTurns: (turns: SessionTurn[]) => void;
-    /** Update the session status in memory AND via store.updateStatus (if store present) */
-    updateStatus: (status: SessionData['status']) => Promise<void>;
-    /** Persist an updated run record via store.updateRun (if store present) */
-    updateRun: (run: SessionRun) => Promise<void>;
-    /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
-    generateTurnId: () => string | Promise<string>;
-    /** Set metadata key */
-    setMeta: (key: string, value: unknown) => void;
-    /** Persist the full session document to the store */
-    save: () => Promise<void>;
-    /** Serialize to SessionData */
-    toJSON: () => SessionData;
-}
-interface CreateSessionOptions {
-    /** Session ID. If omitted and store provides generateSessionId, that is used. */
-    id?: string;
-    /** Agent ID label */
-    agentId?: string;
-    /** Initial metadata */
-    metadata?: Record<string, unknown>;
-    /** Storage backend (optional, enables save/load) */
-    store?: SessionStore;
-    _data?: SessionData;
-}
-/**
- * Create a new session.
- * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
- */
-declare function createSession(options?: CreateSessionOptions): Promise<Session>;
-/**
- * Load an existing session from a store.
- */
-declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
-
 /**
  * Per-agent skill activation state machine.
  *
@@ -1341,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;
@@ -1438,8 +1567,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