import { ChatMessage, LanguageModel, ContentPart, ToolCallPart, FinishReason, TokenUsage, BudgetExceededError, BudgetUsage, SerializableBudgetSpec, PendingApproval, ApprovalDecision, BudgetSpec, Approver, ZiroError, ModelGenerateResult } from '@ziro-agent/core'; import { ToolExecutionResult, RepairToolCall, Tool } from '@ziro-agent/tools'; import { AgentMemoryConfig } from '@ziro-agent/memory'; /** * Context for {@link PrepareStep} — invoked before each `generateText` in the * agent loop (RFC 0004 / Vercel `prepareStep` pattern). */ interface PrepareStepContext { /** 1-based step index (matches `step-start` / `AgentStep.index`). */ stepIndex: number; /** * Messages passed to the model this iteration (after memory transforms). * Treat as read-only; the hook receives a fresh structured clone. */ messages: ChatMessage[]; } /** * Optional return value from {@link PrepareStep}. All fields are independent: * omit a field to leave the agent default for that axis. */ interface PrepareStepResult { /** Use this model for the current `generateText` call only. */ model?: LanguageModel; /** * Replace the first `role: 'system'` message for this call only, or * prepend one if the list has no system message. */ system?: string; /** * Restrict which tools are sent to the model this step. **Empty array** * removes all tools for this step. **Omit** to keep the full agent tool map. */ activeTools?: string[]; } /** * Per-step hook on `createAgent` / `agent.run` / `agent.resume`. */ type PrepareStep = (ctx: PrepareStepContext) => PrepareStepResult | undefined | Promise; interface AgentStep { /** 1-indexed step number. */ index: number; /** Assistant text emitted in this step (may be empty if the model only made tool calls). */ text: string; /** Structured assistant content (text + tool-call parts). */ content: ContentPart[]; /** Tool calls the model requested in this step. */ toolCalls: ToolCallPart[]; /** Resolved tool results, in the same order as `toolCalls`. */ toolResults: ToolExecutionResult[]; finishReason: FinishReason; usage: TokenUsage; } /** * Why the agent loop terminated. Added in v0.1.5: * - `'budgetExceeded'` — only emitted when `BudgetSpec.onExceed` is `'truncate'`; * with the default `'throw'` semantics the agent re-raises `BudgetExceededError` * instead of returning. */ type AgentFinishReason = 'completed' | 'stopWhen' | 'maxSteps' | 'aborted' | 'budgetExceeded'; /** * Surfaced on `AgentRunResult.budgetExceeded` whenever the loop terminated via * `onExceed: 'truncate'`. Mirrors `BudgetExceededError`'s shape so callers can * branch on `kind` without importing the error class. */ interface AgentBudgetExceededInfo { kind: BudgetExceededError['kind']; limit: number; observed: number; scopeId: string; partialUsage: BudgetUsage; /** * Where the budget tripped: `preflight` for the agent loop's pre-LLM check, * `postcall` after a completed model call, `tool` for a budget thrown * inside `executeToolCalls` (whose error becomes a tool result, then the * loop converts it back into a budget halt). */ origin: 'preflight' | 'postcall' | 'tool'; } type StepEvent = { type: 'step-start'; index: number; } | { type: 'llm-finish'; index: number; text: string; toolCalls: ToolCallPart[]; } | { type: 'tool-result'; index: number; result: ToolExecutionResult; } | { type: 'step-finish'; step: AgentStep; } | { type: 'budget-exceeded'; info: AgentBudgetExceededInfo; } | { type: 'agent-finish'; reason: AgentFinishReason; }; type StepEventListener = (event: StepEvent) => void | Promise; interface StopWhenContext { steps: AgentStep[]; totalUsage: TokenUsage; } /** Predicate evaluated after every step; return true to stop the agent. */ type StopWhen = (ctx: StopWhenContext) => boolean | Promise; /** * Current snapshot shape version. Bumped any time the shape changes in a * non-additive way; the SDK accepts older versions transparently via * {@link migrateSnapshot}. * * - **v1** (v0.1.0 → v0.1.8): original shape per RFC 0002. * - **v2** (v0.1.9+): `resolvedSiblings[]` items now carry `parsedArgs` * so resume can faithfully reconstruct the original `ToolCallPart.args` * when synthesising the suspended step. Closes the gap reported in * RFC 0004 §v0.1.9 trust-recovery / RFC 0002 amend. */ declare const CURRENT_SNAPSHOT_VERSION = 2; type SnapshotVersion = 1 | 2; /** * JSON-serializable snapshot of an agent run that suspended waiting for * human approval. See RFC 0002. Persist this with whatever store fits * (Redis, Postgres, S3, in-memory) and feed it back into `agent.resume`. * * Backwards compatibility: the SDK accepts both v1 and v2 snapshots on * `resume()` and runs them through {@link migrateSnapshot} transparently. * v1 snapshots persisted before v0.1.9 will keep resuming for the * documented 12-month support window (see `apps/docs/content/docs/migration.mdx`). */ interface AgentSnapshot { /** * Shape version. New snapshots emit `2`; v1 snapshots are migrated * on-load. Branches on this when persistence layers need to know * which schema to apply (rare — most callers should let * `migrateSnapshot()` normalise). */ readonly version: SnapshotVersion; /** True for any object created by `AgentSuspendedError` — cross-realm safe. */ readonly __ziro_snapshot__: true; /** Caller-supplied stable id (echoed back through `resume`). */ agentId?: string; createdAt: string; /** Budget scope id at the moment of suspension, if a budget was active. */ scopeId?: string; /** 1-indexed step where the suspension happened. */ step: number; /** Conversation up to (but not including) the pending tool result. */ messages: ChatMessage[]; /** Steps already completed before suspension. */ steps: AgentStep[]; totalUsage: TokenUsage; /** * Budget usage accumulated before suspension. Carried into the resumed * scope via `withBudget`'s `presetUsage` so a multi-day pause cannot * silently bypass `maxUsd`. */ budgetUsage?: BudgetUsage; /** * Snapshot of the user's `BudgetSpec` minus non-serializable fields * (function-form `onExceed`). The caller may re-supply a fresh * `BudgetSpec` to `resume` — the spec on the snapshot is a fallback. */ budgetSpec?: SerializableBudgetSpec; /** All tool calls in the suspended batch awaiting approval. */ pendingApprovals: PendingApproval[]; /** * Tool calls in the same batch that already executed (approval not * required, or approver returned `approve`) before suspension was * triggered for a sibling. Their `tool.execute()` side-effects are * already applied; on resume their results are combined with the * post-approval results to form the single tool message appended to * the conversation. * * v2: each entry carries `parsedArgs` so the synthesised * `ToolCallPart` on resume includes the validated input the tool * actually received. v1 entries lack this field; resume falls back to * `undefined` for those siblings (matching pre-v0.1.9 behaviour). * * Empty when the entire batch was pending. */ resolvedSiblings: ToolExecutionResult[]; } /** * Forward-migrate a snapshot of any supported version to the current * shape ({@link CURRENT_SNAPSHOT_VERSION}). Idempotent — passing a v2 * snapshot returns an equivalent v2 snapshot. * * Today the only migration is v1 → v2: it bumps `version` and leaves * `resolvedSiblings[].parsedArgs` undefined (the field is optional, so * v2 callers handle the absence by falling back to the v1 behaviour). * * Any other version triggers a thrown error so unknown future versions * cannot silently corrupt a resume. */ declare function migrateSnapshot(snapshot: AgentSnapshot): AgentSnapshot; /** * Thrown from `agent.run` when a tool call's `requiresApproval` gate * fires and either no `approver` was supplied or the approver returned * `{ decision: 'suspend' }`. * * The caller persists `error.snapshot` (it is JSON-serializable) and * later calls `agent.resume(snapshot, { decisions })` to continue. */ declare class AgentSuspendedError extends ZiroError { readonly name = "AgentSuspendedError"; readonly snapshot: AgentSnapshot; /** Cross-realm-safe brand — survives `JSON.parse(JSON.stringify(err))` when re-thrown. */ readonly __ziro_suspended__: true; constructor(args: { snapshot: AgentSnapshot; message?: string; }); } /** Type-guard usable across realms (does not depend on `instanceof`). */ declare function isAgentSuspendedError(value: unknown): value is AgentSuspendedError; interface AgentResumeOptions { /** * Decision for every tool call in `snapshot.pendingApprovals`. Missing * entries default to `{ decision: 'suspend' }` — the loop will re-emit * an `AgentSuspendedError` carrying an updated snapshot. */ decisions: Record; /** * Re-supply (or replace) the budget. When omitted the resume reuses the * snapshot's `budgetSpec`. Original `budgetUsage` carries forward via * `withBudget(presetUsage)` regardless of which spec is used. */ budget?: BudgetSpec; /** Default budget for tool calls during the resumed run. */ toolBudget?: BudgetSpec; /** Approver for any FURTHER approvals that come up after resume. */ approver?: Approver; abortSignal?: AbortSignal; onEvent?: StepEventListener; /** Step-cap override (otherwise inherited from `CreateAgentOptions`). */ maxSteps?: number; /** stopWhen override (otherwise inherited). */ stopWhen?: StopWhen; /** * Free-form metadata propagated to the approver and tool-execute ctx * during the resumed run. */ metadata?: Record; /** Per-resume override of {@link CreateAgentOptions.repairToolCall}. */ repairToolCall?: RepairToolCall; /** Per-resume override of {@link CreateAgentOptions.prepareStep}. */ prepareStep?: PrepareStep; } /** * Attribute-only summary of how a resume turned out — useful for * tracing / OTel observers and for callers who want a one-line status. */ interface ResumeSummary { decisionCounts: { approve: number; reject: number; suspend: number; }; finishReason: AgentFinishReason; stepsAdded: number; } /** * Opaque, time-sortable checkpoint identifier. Implementations SHOULD use * UUID v7 so `list()` results are naturally chronological without an * extra `ORDER BY createdAt`. Callers MUST treat this as opaque. * * Stable since v0.1.9 / RFC 0006 §types. */ type CheckpointId = string; /** * Lightweight metadata returned by {@link Checkpointer.list} — enough to * page a UI / pick a target without fully deserializing the snapshot. * * `sizeBytes` is best-effort; adapters that cannot cheaply measure * (Redis MGET, etc.) MAY report 0 and document the gap. */ interface CheckpointMeta { id: CheckpointId; threadId: string; createdAt: Date; /** Echoes `snapshot.version` at write time so consumers can plan migrations. */ agentSnapshotVersion: number; sizeBytes: number; } /** * Persistence boundary for {@link AgentSnapshot}s — the durable side of * an agent run that pauses for HITL, hits a budget cap with `truncate`, * is intentionally suspended, or simply needs to survive a process * restart. * * **Contract** (RFC 0006 §interface): * - `put` MUST be atomic per `(threadId, returned id)`. The returned * `CheckpointId` is the only handle the caller will quote later. * - `get(threadId)` returns the *latest* checkpoint for the thread, or * `null` if none exist. `get(threadId, id)` returns the exact one or * `null` if it has been deleted / expired / never written. * - `list` is ordered newest → oldest. `limit` defaults to * implementation-specific (memory adapter: 100). * - `delete(threadId)` removes ALL checkpoints for the thread. * `delete(threadId, id)` removes only that checkpoint. * - All methods MUST be safe to call concurrently from the same * process; cross-process atomicity is the storage adapter's * responsibility (Postgres: row-level lock; Redis: single-key set). * * Implementations live in dedicated adapter packages * (`@ziro-agent/checkpoint-memory`, `@ziro-agent/checkpoint-postgres`, * `@ziro-agent/checkpoint-redis`) so the agent core stays free of * driver dependencies. See RFC 0006 for the design rationale. * * `agent.resumeFromCheckpoint` / `agent.listCheckpoints` integrate with * concrete adapters as of `@ziro-agent/agent` v0.2. For resumable * `streamText` + `resumeKey`, when `continueUpstream` throws * `ContinueUpstreamMidToolCallError` from `@ziro-agent/core`, recover via the * agent loop (`agent.resume` / `resumeFromCheckpoint`) — see RFC 0018 and * `@ziro-agent/agent` exports `isContinueUpstreamMidToolCallError`, * `MID_TOOL_CALL_CONTINUE_UPSTREAM_HINT`. */ interface Checkpointer { /** * Persist `snapshot` under `threadId` and return its newly assigned id. * The id is opaque; callers should pass it back through `get` / * `delete` rather than parsing it. */ put(threadId: string, snapshot: AgentSnapshot): Promise; /** * Read a checkpoint. With no `checkpointId`, returns the most recent * one for `threadId`. Returns `null` for unknown thread or unknown id * — the caller should treat that as "nothing to resume from". */ get(threadId: string, checkpointId?: CheckpointId): Promise; /** * List checkpoints for a thread, newest first. `limit` caps the * result; adapters MAY enforce a lower hard ceiling for memory * pressure reasons. */ list(threadId: string, opts?: { limit?: number; }): Promise; /** * Delete checkpoints. Without `checkpointId`, removes every * checkpoint for the thread (use this on conversation deletion). * No-ops silently when nothing matches. */ delete(threadId: string, checkpointId?: CheckpointId): Promise; } /** * Multi-agent handoffs (RFC 0007). * * Allows an agent to delegate the conversation to another, specialised * agent by exposing each handoff as an LLM-callable tool named * `transfer_to_`. The LLM picks the next agent the same way * it picks any other tool, so the routing decision is auditable in the * standard step trace. * * Per-handoff `inputFilter(messages)` controls how much of the parent's * message history is forwarded to the target agent — the documented * mitigation for context-pollution failure modes. * * Explicitly out of scope here: LLM-as-router (rejected in RFC 0007 * §"Explicitly NOT shipping") and a graph engine (deferred to * `@ziro-agent/workflow`). */ /** * Either an `Agent` (default `inputFilter` = passthrough) or an * explicit `HandoffSpec` for fine-grained control. */ type Handoff = Agent | HandoffSpec; interface HandoffSpec { /** Target sub-agent. Required. */ agent: Agent; /** * Transform the parent's message history before the sub-agent sees * it. Default: passthrough. Common patterns: * * `(msgs) => msgs.slice(-10)` // last 10 messages only * `(msgs) => msgs.filter(m => m.role !== 'system')` // strip parent's system prompt * * Documented production failure mode this mitigates: context * pollution (sub-agent's reasoning derailed by irrelevant earlier * turns). */ inputFilter?: (messages: ChatMessage[]) => ChatMessage[]; /** * Override the auto-derived tool description shown to the LLM. * Default: `"Transfer the conversation to the agent. Use * when the user's request requires its specialised capabilities."` */ description?: string; } /** * Thrown when a chain of handoffs exceeds `maxHandoffDepth`. Helps * catch the "triage agent calls itself" recursive misconfiguration * before it costs real money. */ declare class HandoffLoopError extends ZiroError { readonly name = "HandoffLoopError"; readonly depth: number; readonly maxDepth: number; readonly chain: readonly string[]; constructor(args: { depth: number; maxDepth: number; chain: readonly string[]; }); } /** * Sanitise an agent name into a valid OpenAI function name fragment * (lower-case, `[a-z0-9_]` only). Empty input falls back to `agent`. */ declare function handoffToolName(agentName: string): string; interface CreateAgentOptions { model: LanguageModel; tools?: Record; /** * Stable, human-readable agent name. Used for: * - Auto-generating handoff tool names (`transfer_to_`). * - Tracing / log correlation (`ziro.agent.name` attribute). * * Recommended convention: short, snake_case-ish (e.g. `triage`, * `billing`, `tech_support`). Defaults to `agent` when omitted; this * is fine for single-agent setups but causes tool-name collisions * when used in `handoffs[]` — supply a unique name in that case. */ name?: string; /** * Specialised sub-agents the LLM may delegate the conversation to * via auto-generated `transfer_to_` tools. Pass either a bare * `Agent` (full message-history passthrough) or a {@link HandoffSpec} * for `inputFilter` / custom description. See RFC 0007. * * Available since v0.2.0. */ handoffs?: Handoff[]; /** * Hard cap on the depth of nested handoffs in a single run. Throws * `HandoffLoopError` if exceeded. Default `5`. */ maxHandoffDepth?: number; /** System message passed to the model on every step. */ system?: string; /** Hard cap on iterations. Default 10. */ maxSteps?: number; /** * Predicate evaluated after every step; return true to stop early. * Combine with `stepCountIs`, `totalTokensExceeds`, etc. */ stopWhen?: StopWhen; /** * Invoked before each LLM step. Return a partial result to swap `model`, * replace the first system message for that call, or restrict which tool * names are exposed (RFC 0004 `prepareStep` adoption matrix). */ prepareStep?: PrepareStep; /** Default temperature for every step. */ temperature?: number; /** Per-step LLM call timeout. Set 0 / undefined to disable. */ timeoutMs?: number; /** * Optional persistence boundary. When supplied, every * `AgentSuspendedError` thrown by `run()` / `resume()` automatically * `put`s its snapshot under `runOptions.threadId` (or the agent-level * `defaultThreadId`) before re-throwing — so the caller can recover * with `agent.resumeFromCheckpoint(threadId)` after a process restart * without writing any persistence glue. * * Future strategies (`'message'` / `'invocation'` per RFC 0006 * §strategies) auto-checkpoint inside the loop too; they ship in v0.2 * once `AgentSnapshot` captures non-suspended mid-run state. * * Available since v0.1.9. */ checkpointer?: Checkpointer; /** * Default thread id used by `checkpointer` when neither `run` nor * `resume` overrides it. Useful when an agent instance is dedicated * to a single conversation; otherwise pass `threadId` per-call. */ defaultThreadId?: string; /** * Optional three-tier memory (RFC 0011). Working memory is merged into the * first `system` message each LLM step; memory processors and conversation * transforms run on a copy — full history stays in `AgentRunResult.messages` * and checkpoints. */ memory?: AgentMemoryConfig; /** * When `true`, every tool (including auto-generated handoff tools) is wrapped * with `instrumentTools` from `@ziro-agent/tracing`. Until `setTracer(...)` is * installed, spans are no-ops. Default `false` so callers who already pass * `instrumentTools(...)` maps do not double-wrap. */ traceTools?: boolean; /** * Default {@link RepairToolCall} for every `run()` / `resume()` unless * overridden per-call on {@link AgentRunOptions} / {@link AgentResumeOptions}. */ repairToolCall?: RepairToolCall; } interface AgentRunOptions { /** Either a single user prompt or a full message list. */ prompt?: string; messages?: ChatMessage[]; abortSignal?: AbortSignal; /** Subscribe to fine-grained step events while the agent runs. */ onEvent?: StepEventListener; /** * Per-run override of {@link CreateAgentOptions.prepareStep}. When both are * set, this wins. */ prepareStep?: PrepareStep; /** * Budget enforced across the entire run: every nested `generateText` and * `executeToolCalls` invocation participates in the same scope via * `AsyncLocalStorage`. See RFC 0001. * * `BudgetSpec.maxSteps` is honored here (it is intentionally ignored at * the `generateText` layer). If both `maxSteps` on `CreateAgentOptions` * and on `budget` are set, the tighter wins. */ budget?: BudgetSpec; /** * Per-tool-call default budget. Composed (intersected) with each tool's * declared `defineTool({ budget })` and with the outer agent budget. * Most useful as a "safety net" against a single rogue tool burning the * whole agent budget. */ toolBudget?: BudgetSpec; /** * Resolves `tool.requiresApproval` gates inline. When unset and any * tool needs approval, the agent suspends with `AgentSuspendedError` * (carrying a serializable `AgentSnapshot`). See RFC 0002. */ approver?: Approver; /** * Stable id stamped onto any `AgentSnapshot` produced during this run * (for the caller's storage layer). Optional. */ agentId?: string; /** * Per-call thread id for `checkpointer` auto-persist. Falls back to * `CreateAgentOptions.defaultThreadId`. When neither is set, an * agent-level `checkpointer` is a no-op (the snapshot still arrives * via `AgentSuspendedError` so callers may persist manually). */ threadId?: string; /** * Free-form metadata propagated to the approver and tool-execute ctx. */ metadata?: Record; /** Per-run override of {@link CreateAgentOptions.repairToolCall}. */ repairToolCall?: RepairToolCall; } interface AgentRunResult { /** Final assistant text — concatenated from the last step. */ text: string; /** Every step the agent took, in order. */ steps: AgentStep[]; /** Sum of token usage across every LLM call. */ totalUsage: TokenUsage; /** Why the loop terminated. */ finishReason: AgentFinishReason; /** Final conversation, including system, user, assistant, and tool messages. */ messages: ChatMessage[]; /** * Populated when the loop terminated via `onExceed: 'truncate'`. With the * default `'throw'` semantics, the run rejects with `BudgetExceededError` * instead and this field is never reached. */ budgetExceeded?: AgentBudgetExceededInfo; } interface ResumeFromCheckpointOptions extends AgentResumeOptions { /** * When omitted, loads the latest checkpoint for the thread. Pass an * id to resume from a specific point (useful for retry experiments). */ checkpointId?: CheckpointId; } interface Agent { /** * Stable, human-readable agent name (default `'agent'`). Drives * handoff tool naming and tracing attributes. */ readonly name: string; readonly tools: Record; /** * The {@link Checkpointer} the agent was created with, or `undefined` * when none was supplied. Re-exposed so callers can manually `list` * / `delete` checkpoints without holding a separate reference. */ readonly checkpointer?: Checkpointer; /** * Same object passed to `createAgent({ memory })`. `longTerm` is for app * tools and RAG; working and conversation tiers are applied inside the loop. */ readonly memory?: AgentMemoryConfig; run(options: AgentRunOptions): Promise; /** * Continue an agent run that was suspended via `AgentSuspendedError`. * `decisions` must contain a decision for every tool call in * `snapshot.pendingApprovals`; missing entries default to * `{ decision: 'suspend' }` and the loop will re-emit a fresh * suspension error. See RFC 0002. */ resume(snapshot: AgentSnapshot, options: AgentResumeOptions): Promise; /** * Convenience wrapper around `checkpointer.get(threadId, ?id)` + * `resume(snapshot, options)`. Throws `Error("No checkpoint found ...")` * when no snapshot exists for the thread — callers should treat that * as "nothing to resume from" and fall back to a fresh `run()`. * * Requires the agent to have been created with a `checkpointer`. * * Available since v0.1.9. */ resumeFromCheckpoint(threadId: string, options: ResumeFromCheckpointOptions): Promise; /** * Lists checkpoint metadata for a thread (newest first). Delegates to * {@link Checkpointer.list}; use this when you only hold the `Agent` * reference. * * Requires `createAgent({ checkpointer })`. */ listCheckpoints(threadId: string, opts?: { limit?: number; }): Promise; } /** * Create a tool-using agent. Internally runs a `generateText → executeToolCalls` * loop, threading messages back to the model until either: * - the model returns no tool calls (natural completion) * - `stopWhen` returns true * - `maxSteps` is reached * - `abortSignal` fires * - a tool call requires human approval (`AgentSuspendedError` thrown — RFC 0002) */ declare function createAgent(options: CreateAgentOptions): Agent; declare const AGENT_RECORDING_VERSION: 1; type SerializedToolResult = Pick & { parsedArgs?: unknown; budgetExceeded?: ToolExecutionResult['budgetExceeded']; }; /** * One JSON line emitted by {@link runWithAgentRecording} per finished agent * step (after tools ran for that step). */ interface AgentRecordingStepLine { v: typeof AGENT_RECORDING_VERSION; kind: 'step'; step: { index: number; text: string; content: ModelGenerateResult['content']; toolCalls: ModelGenerateResult['toolCalls']; toolResults: SerializedToolResult[]; finishReason: ModelGenerateResult['finishReason']; usage: ModelGenerateResult['usage']; }; } /** Thrown when replayed tool calls diverge from the recorded trace. */ declare class ReplayMismatchError extends ZiroError { readonly name = "ReplayMismatchError"; constructor(message: string); } /** * Run an agent while appending one JSON line per completed step (RFC 0015). * Skips HITL suspension paths — only steps that fully finish are recorded. */ declare function runWithAgentRecording(agent: Agent, options: AgentRunOptions & { recording: { writeLine: (line: string) => void | Promise; }; }): Promise; /** RFC 0015 name — same as {@link runWithAgentRecording}. */ declare const recordAgentRun: typeof runWithAgentRecording; /** * Parse JSONL produced by {@link runWithAgentRecording}. */ declare function parseAgentRecordingJsonl(text: string): AgentRecordingStepLine[]; /** * Build a {@link LanguageModel} that reproduces recorded LLM steps in order. */ declare function createReplayModelFromAgentRecording(lines: readonly AgentRecordingStepLine[], options?: { modelId?: string; }): LanguageModel; /** * Build deterministic tool stubs keyed by tool name so {@link createAgent} * can replay a trace without calling real side effects. */ declare function createReplayToolsFromAgentRecording(lines: readonly AgentRecordingStepLine[]): Record; /** Options for {@link replayAgentFromRecording} — `model` / `tools` default to replay stubs. */ type ReplayAgentFromRecordingAgentOptions = Omit & Partial>; /** {@link createReplayRunBundleFromRecording} return shape (RFC 0015). */ interface ReplayRunBundle { readonly agent: Agent; run(runOptions: AgentRunOptions): Promise; } /** * One-call replay: {@link createReplayModelFromAgentRecording} + * {@link createReplayToolsFromAgentRecording} + {@link createAgent} + {@link Agent.run}. */ declare function replayAgentFromRecording(lines: readonly AgentRecordingStepLine[], agentOptions: ReplayAgentFromRecordingAgentOptions, runOptions: AgentRunOptions): Promise; /** Parse JSONL then {@link replayAgentFromRecording}. */ declare function replayAgentFromRecordingJsonl(jsonl: string, agentOptions: ReplayAgentFromRecordingAgentOptions, runOptions: AgentRunOptions): Promise; /** * Build a replay {@link Agent} without running — pair with {@link Agent.run} / * {@link Agent.resumeFromCheckpoint} as needed (RFC 0015 convenience). */ declare function createReplayAgentFromRecording(lines: readonly AgentRecordingStepLine[], agentOptions: ReplayAgentFromRecordingAgentOptions): Agent; /** * Returns `{ agent, run }` where `run` delegates to {@link Agent.run} on the * replay-configured agent (RFC 0015 `replayRun`-style bundle). */ declare function createReplayRunBundleFromRecording(lines: readonly AgentRecordingStepLine[], agentOptions: ReplayAgentFromRecordingAgentOptions): ReplayRunBundle; export { type Agent as A, createReplayAgentFromRecording as B, CURRENT_SNAPSHOT_VERSION as C, createReplayModelFromAgentRecording as D, createReplayRunBundleFromRecording as E, createReplayToolsFromAgentRecording as F, handoffToolName as G, type Handoff as H, isAgentSuspendedError as I, migrateSnapshot as J, parseAgentRecordingJsonl as K, recordAgentRun as L, replayAgentFromRecording as M, replayAgentFromRecordingJsonl as N, runWithAgentRecording as O, type PrepareStep as P, type ReplayAgentFromRecordingAgentOptions as R, type SnapshotVersion as S, type AgentRunResult as a, type AgentRunOptions as b, AGENT_RECORDING_VERSION as c, type AgentBudgetExceededInfo as d, type AgentFinishReason as e, type AgentRecordingStepLine as f, type AgentResumeOptions as g, type AgentSnapshot as h, type AgentStep as i, AgentSuspendedError as j, type CheckpointId as k, type CheckpointMeta as l, type Checkpointer as m, type CreateAgentOptions as n, HandoffLoopError as o, type HandoffSpec as p, type PrepareStepContext as q, type PrepareStepResult as r, ReplayMismatchError as s, type ReplayRunBundle as t, type ResumeFromCheckpointOptions as u, type ResumeSummary as v, type StepEvent as w, type StopWhen as x, type StopWhenContext as y, createAgent as z };