@dogpile/sdk 0.3.0 → 0.3.1

package/dist/types/events.d.ts

@@ -0,0 +1,495 @@
+import type { BudgetStopReason, CostSummary, JsonObject, ModelRequest, ModelResponse, NormalizedQualityScore, RunEvaluation, RuntimeToolIdentity, RuntimeToolResult, TerminationStopRecord } from "../types.js";
+/**
+ * Event emitted when a protocol assigns or records an agent role.
+ *
+ * @remarks
+ * This event normally appears near the beginning of a run and establishes the
+ * `agentId`/`role` pair that later turn and transcript records refer to. A
+ * renderer can use it to build the participant roster before model output
+ * starts streaming.
+ *
+ * Payload shape:
+ *
+ * - `type`: always `role-assignment`.
+ * - `runId`: stable id shared by every event and trace object for the run.
+ * - `at`: ISO-8601 timestamp for when the assignment was emitted.
+ * - `agentId`: stable agent id used in events, trace, and transcript entries.
+ * - `role`: model-visible role or perspective assigned to that agent.
+ */
+export interface RoleAssignmentEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "role-assignment";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Agent receiving the role assignment. */
+    readonly agentId: string;
+    /** Role assigned to the agent. */
+    readonly role: string;
+}
+/**
+ * Event emitted when Dogpile is about to ask the configured model provider for
+ * one protocol-managed response.
+ *
+ * @remarks
+ * This event is the request-side model activity counterpart to
+ * {@link ModelResponseEvent}. Protocol implementations may omit it when they
+ * only expose completed turns, but adapters and researcher harnesses can emit
+ * it to make provider calls visible in the same streaming event log as agent
+ * turns and final output.
+ */
+export interface ModelRequestEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "model-request";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Stable provider call id within the run. */
+    readonly callId: string;
+    /** Configured model provider id receiving the request. */
+    readonly providerId: string;
+    /** Agent requesting the model call. */
+    readonly agentId: string;
+    /** Agent role for the active model call. */
+    readonly role: string;
+    /** Provider-neutral request handed to the model adapter. */
+    readonly request: ModelRequest;
+}
+/**
+ * Event emitted after the configured model provider returns one response.
+ *
+ * @remarks
+ * This event records provider-level model activity without forcing callers to
+ * infer it from the higher-level {@link TurnEvent}. The response is the same
+ * provider-neutral shape captured in replay traces, so it remains portable and
+ * JSON-serializable across Node LTS, Bun, and browser ESM runtimes.
+ */
+export interface ModelResponseEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "model-response";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Stable provider call id within the run. */
+    readonly callId: string;
+    /** Configured model provider id that produced the response. */
+    readonly providerId: string;
+    /** Agent that requested the model call. */
+    readonly agentId: string;
+    /** Agent role for the completed model call. */
+    readonly role: string;
+    /** Provider-neutral response returned by the model adapter. */
+    readonly response: ModelResponse;
+}
+/**
+ * Event emitted while a model turn is still generating text.
+ *
+ * @remarks
+ * `model-output-chunk` lets streaming callers render provider output before
+ * the protocol has enough information to commit the completed `agent-turn`
+ * transcript entry. It is emitted only when the configured model provider
+ * implements {@link ConfiguredModelProvider.stream}; non-streaming providers
+ * continue to produce the existing role/turn/final event sequence.
+ *
+ * Payload shape:
+ *
+ * - `type`: always `model-output-chunk`.
+ * - `runId`: stable id shared by every event and trace object for the run.
+ * - `at`: ISO-8601 timestamp for when the chunk was observed.
+ * - `agentId` and `role`: identify the active generating agent.
+ * - `input`: prompt text visible to that agent for this turn.
+ * - `chunkIndex`: zero-based chunk index within this model turn.
+ * - `text`: text delta from the provider.
+ * - `output`: accumulated output for this turn after applying the chunk.
+ */
+export interface ModelOutputChunkEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "model-output-chunk";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Agent currently producing output. */
+    readonly agentId: string;
+    /** Agent role for the active turn. */
+    readonly role: string;
+    /** Prompt/input visible to the agent for this turn. */
+    readonly input: string;
+    /** Zero-based chunk index within the active model turn. */
+    readonly chunkIndex: number;
+    /** Text delta produced by the model provider. */
+    readonly text: string;
+    /** Accumulated output for this turn after applying this chunk. */
+    readonly output: string;
+}
+/**
+ * Event emitted when a runtime tool is invoked by protocol or model policy.
+ *
+ * @remarks
+ * Tools are caller-owned escape hatches. This request-side event keeps tool
+ * invocation observable without making Dogpile core depend on Node-only
+ * capabilities, a storage layer, or a provider-specific function-call shape.
+ */
+export interface ToolCallEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "tool-call";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Stable tool call id within the run. */
+    readonly toolCallId: string;
+    /** Tool identity selected for execution. */
+    readonly tool: RuntimeToolIdentity;
+    /** JSON-serializable tool input. */
+    readonly input: JsonObject;
+    /** Agent that requested the tool, when agent-scoped. */
+    readonly agentId?: string;
+    /** Agent role that requested the tool, when available. */
+    readonly role?: string;
+}
+/**
+ * Event emitted after a runtime tool returns a normalized result.
+ *
+ * @remarks
+ * Tool failures are data at the public boundary. The result payload uses the
+ * same discriminated union as runtime tool adapters, allowing log consumers to
+ * render successful outputs and normalized errors exhaustively.
+ */
+export interface ToolResultEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "tool-result";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Stable tool call id within the run. */
+    readonly toolCallId: string;
+    /** Tool identity that produced the result. */
+    readonly tool: RuntimeToolIdentity;
+    /** Normalized JSON-serializable tool result. */
+    readonly result: RuntimeToolResult;
+    /** Agent that requested the tool, when agent-scoped. */
+    readonly agentId?: string;
+    /** Agent role that requested the tool, when available. */
+    readonly role?: string;
+}
+/**
+ * Provider-normalized participation decision parsed from paper-style agent output.
+ *
+ * @remarks
+ * Dogpile preserves the raw model text on transcript entries and events. When
+ * a model emits the labeled fields `role_selected`, `participation`,
+ * `rationale`, and `contribution`, protocols also attach this structured
+ * metadata so reproduction harnesses can distinguish contribution from
+ * voluntary abstention without reparsing raw text.
+ */
+export interface AgentDecision {
+    /** Task-specific role selected by the agent for this turn. */
+    readonly selectedRole: string;
+    /** Whether the agent contributed or voluntarily abstained. */
+    readonly participation: AgentParticipation;
+    /** Agent-provided rationale for the selected role and participation choice. */
+    readonly rationale: string;
+    /** Agent-provided contribution text, or abstention explanation. */
+    readonly contribution: string;
+}
+/**
+ * Agent participation state for a paper-style turn decision.
+ */
+export type AgentParticipation = "contribute" | "abstain";
+/**
+ * Event emitted after one agent contributes a model turn.
+ *
+ * @remarks
+ * `agent-turn` is the primary streaming payload for sequential, coordinator,
+ * shared-state, and broadcast executions. It captures the exact prompt/input
+ * Dogpile supplied to the agent, the text returned by the model provider, and
+ * the cumulative cost after applying that response.
+ *
+ * The corresponding durable transcript record contains the same
+ * `agentId`/`role`/`input`/`output` contribution without event timing or cost
+ * fields. Use this event for live progress UIs and the transcript for replay
+ * or downstream application logic.
+ *
+ * Payload shape:
+ *
+ * - `type`: always `agent-turn`.
+ * - `runId`: stable id shared by every event and trace object for the run.
+ * - `at`: ISO-8601 timestamp for when the turn completed.
+ * - `agentId` and `role`: identify the contributing agent.
+ * - `input`: prompt text visible to that agent for this turn.
+ * - `output`: generated model text produced by the agent.
+ * - `cost`: cumulative token and spend accounting after this turn.
+ */
+export interface TurnEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "agent-turn";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Agent that produced this turn. */
+    readonly agentId: string;
+    /** Agent role for this turn. */
+    readonly role: string;
+    /** Prompt/input visible to the agent for this turn. */
+    readonly input: string;
+    /** Model output produced by the agent. */
+    readonly output: string;
+    /** Optional structured role/participation decision parsed from model output. */
+    readonly decision?: AgentDecision;
+    /** Cumulative cost after this turn. */
+    readonly cost: CostSummary;
+}
+/**
+ * One independent contribution captured by a broadcast round event.
+ *
+ * @remarks
+ * Broadcast protocols collect one contribution per participating agent before
+ * synthesis. The contribution payload is intentionally smaller than
+ * {@link TurnEvent}: it is a round-level summary of model outputs, while the
+ * complete prompt/output pair for each agent is still available as individual
+ * `agent-turn` events and {@link TranscriptEntry} records.
+ *
+ * Payload shape:
+ *
+ * - `agentId`: stable id of the contributing agent.
+ * - `role`: model-visible role or perspective used for that contribution.
+ * - `output`: generated text contributed independently for the round.
+ */
+export interface BroadcastContribution {
+    /** Agent that produced the broadcast contribution. */
+    readonly agentId: string;
+    /** Agent role for the contribution. */
+    readonly role: string;
+    /** Independent model output produced for the shared mission. */
+    readonly output: string;
+    /** Optional structured role/participation decision parsed from model output. */
+    readonly decision?: AgentDecision;
+}
+/**
+ * Event emitted after agents broadcast independent contributions for a round.
+ *
+ * @remarks
+ * A `broadcast` event marks the coordination moment where independently
+ * generated agent outputs are gathered for a shared round. It does not replace
+ * per-agent `agent-turn` events; instead, it groups their outputs by round so
+ * observers can render the broadcast barrier and replay the paper protocol's
+ * independent-contribution step.
+ *
+ * Payload shape:
+ *
+ * - `type`: always `broadcast`.
+ * - `runId`: stable id shared by every event and trace object for the run.
+ * - `at`: ISO-8601 timestamp for when the round finished.
+ * - `round`: one-based broadcast round number.
+ * - `contributions`: independent outputs collected for this round.
+ * - `cost`: cumulative token and spend accounting after the round.
+ */
+export interface BroadcastEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "broadcast";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** One-based broadcast round number. */
+    readonly round: number;
+    /** Independent contributions collected in this broadcast round. */
+    readonly contributions: readonly BroadcastContribution[];
+    /** Cumulative cost after this broadcast round. */
+    readonly cost: CostSummary;
+}
+/**
+ * Event emitted when a workflow halts because a configured budget cap fired.
+ *
+ * @remarks
+ * `budget-stop` records the normalized cap class that stopped execution before
+ * the final event closes the run. The detail object is JSON-serializable so
+ * callers can persist or replay the exact cap, observed value, and limit.
+ */
+export interface BudgetStopEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "budget-stop";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Normalized machine-readable budget stop reason. */
+    readonly reason: BudgetStopReason;
+    /** Total cost at the stop point. */
+    readonly cost: CostSummary;
+    /** Completed model-turn iterations at the stop point. */
+    readonly iteration: number;
+    /** Elapsed runtime in milliseconds at the stop point. */
+    readonly elapsedMs: number;
+    /** Serializable cap diagnostics. */
+    readonly detail: JsonObject;
+}
+/**
+ * Link from a terminal event to the completed trace transcript.
+ *
+ * @remarks
+ * Final events are emitted before callers await {@link StreamHandle.result},
+ * so this compact link tells streaming UIs exactly which transcript artifact
+ * the terminal output closes over without duplicating every transcript entry
+ * inside the event log.
+ */
+export interface TranscriptLink {
+    /** Discriminant for future transcript link variants. */
+    readonly kind: "trace-transcript";
+    /** Number of transcript entries included in the completed trace. */
+    readonly entryCount: number;
+    /** Zero-based index of the last transcript entry, or `null` for empty runs. */
+    readonly lastEntryIndex: number | null;
+}
+/**
+ * Event emitted when a workflow produces its final output.
+ *
+ * @remarks
+ * `final` is the terminal streaming event for a successful run. Its `output`
+ * value matches {@link RunResult.output}, and its `cost` value matches the
+ * final aggregate cost returned on the result. Its `transcript` link points to
+ * the completed {@link Trace.transcript} entries that produced the terminal
+ * output.
+ *
+ * Payload shape:
+ *
+ * - `type`: always `final`.
+ * - `runId`: stable id shared by every event and trace object for the run.
+ * - `at`: ISO-8601 timestamp for when final synthesis completed.
+ * - `output`: final synthesized answer returned to the caller.
+ * - `cost`: total token and spend accounting for the run.
+ * - `transcript`: compact link to the completed trace transcript.
+ */
+export interface FinalEvent {
+    /** Discriminant for event rendering and exhaustive switches. */
+    readonly type: "final";
+    /** Stable run id shared by all events in one workflow. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Final synthesized answer returned as `RunResult.output`. */
+    readonly output: string;
+    /** Total cost at completion. */
+    readonly cost: CostSummary;
+    /** Link to the completed trace transcript. */
+    readonly transcript: TranscriptLink;
+    /** Optional normalized quality score supplied by a caller-owned evaluator. */
+    readonly quality?: NormalizedQualityScore;
+    /** Optional serializable evaluation payload supplied by a caller-owned evaluator. */
+    readonly evaluation?: RunEvaluation;
+    /** Termination condition that stopped the run, when the run ended by policy. */
+    readonly termination?: TerminationStopRecord;
+}
+/**
+ * Successful coordination event emitted by Dogpile and persisted in traces.
+ *
+ * @remarks
+ * `RunEvent` is the discriminated union stored in {@link Trace.events} and
+ * used by low-level protocol emit callbacks. Switch on `type` to handle each
+ * coordination moment exhaustively:
+ *
+ * - `role-assignment`: participant/role roster was established.
+ * - `model-request`: one provider-neutral model request was started.
+ * - `model-response`: one provider-neutral model response completed.
+ * - `model-output-chunk`: one streaming model text delta arrived.
+ * - `tool-call`: one runtime tool invocation was started.
+ * - `tool-result`: one runtime tool invocation completed.
+ * - `agent-turn`: one agent completed a prompt/response turn.
+ * - `broadcast`: a broadcast round gathered independent contributions.
+ * - `budget-stop`: a configured budget cap halted further model turns.
+ * - `final`: the run completed and produced the final output.
+ *
+ * Every variant is JSON-serializable and includes `runId` plus an ISO-8601
+ * `at` timestamp so callers can persist, render, or replay the event log
+ * without SDK-owned storage.
+ *
+ * @example
+ * ```ts
+ * for await (const event of Dogpile.stream(options)) {
+ *   switch (event.type) {
+ *     case "agent-turn":
+ *       console.log(event.agentId, event.output);
+ *       break;
+ *     case "final":
+ *       console.log(event.output);
+ *       break;
+ *   }
+ * }
+ * ```
+ */
+export type RunEvent = RoleAssignmentEvent | ModelRequestEvent | ModelResponseEvent | ModelOutputChunkEvent | ToolCallEvent | ToolResultEvent | TurnEvent | BroadcastEvent | BudgetStopEvent | FinalEvent;
+/**
+ * Model activity events yielded by `stream()` and persisted in traces when a
+ * protocol exposes provider-call boundaries.
+ */
+export type ModelActivityEvent = ModelRequestEvent | ModelResponseEvent | ModelOutputChunkEvent;
+/**
+ * Tool activity events yielded by `stream()` and persisted in traces when a
+ * protocol or caller-owned adapter invokes runtime tools.
+ */
+export type ToolActivityEvent = ToolCallEvent | ToolResultEvent;
+/**
+ * Lifecycle event yielded by `stream()`.
+ *
+ * These events describe workflow coordination state rather than model text.
+ * Role assignment establishes the participant roster, while `budget-stop`
+ * records a lifecycle halt before the terminal completion event.
+ */
+export type StreamLifecycleEvent = RoleAssignmentEvent | BudgetStopEvent;
+/**
+ * Output event yielded by `stream()`.
+ *
+ * These events carry generated agent output or grouped round output while a
+ * workflow is still running.
+ */
+export type StreamOutputEvent = ModelActivityEvent | ToolActivityEvent | TurnEvent | BroadcastEvent;
+/**
+ * Error event yielded by `stream()` when execution rejects.
+ *
+ * @remarks
+ * Stream errors are emitted before {@link StreamHandle.result} rejects so UIs
+ * and log collectors can record a terminal failure without wrapping the result
+ * promise. The error payload is JSON-serializable and intentionally omits
+ * runtime-specific values such as `Error.stack`.
+ */
+export interface StreamErrorEvent {
+    /** Discriminant for stream event handling. */
+    readonly type: "error";
+    /** Stable run id when known; empty when failure happened before protocol startup. */
+    readonly runId: string;
+    /** ISO-8601 event timestamp. */
+    readonly at: string;
+    /** Error name when available. */
+    readonly name: string;
+    /** Human-readable error message. */
+    readonly message: string;
+    /** Optional serializable diagnostics supplied by the SDK. */
+    readonly detail?: JsonObject;
+}
+/**
+ * Completion event yielded by `stream()` after successful execution.
+ */
+export type StreamCompletionEvent = FinalEvent;
+/**
+ * Public streaming event union returned by `stream()`.
+ *
+ * @remarks
+ * The union is grouped into lifecycle, output, error, and completion families:
+ *
+ * - lifecycle: {@link StreamLifecycleEvent}
+ * - output: {@link StreamOutputEvent}
+ * - error: {@link StreamErrorEvent}
+ * - completion: {@link StreamCompletionEvent}
+ *
+ * Successful stream events are also persisted as {@link RunEvent} values in the
+ * completed trace. `error` is stream-only because a failed run has no completed
+ * {@link RunResult} trace to return.
+ */
+export type StreamEvent = StreamLifecycleEvent | StreamOutputEvent | StreamErrorEvent | StreamCompletionEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"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"}

package/dist/types/events.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":""}

package/dist/types/replay.d.ts

@@ -0,0 +1,169 @@
+import type { AgentSpec, Budget, BudgetStopReason, CostSummary, ModelRequest, ModelResponse, Protocol, ProtocolConfig, RunEvent, RuntimeToolIdentity, TerminationCondition, Tier, TranscriptLink } from "../types.js";
+/**
+ * Version tag for the replay trace artifact schema.
+ */
+export type ReplayTraceSchemaVersion = "1.0";
+/**
+ * Serializable seed metadata recorded with replay traces.
+ *
+ * @remarks
+ * Most providers do not expose deterministic seed control. Dogpile still
+ * records an explicit empty seed artifact so replay consumers can distinguish
+ * "no seed supplied" from a missing trace field.
+ */
+export interface ReplayTraceSeed {
+    /** Seed artifact discriminant. */
+    readonly kind: "replay-trace-seed";
+    /** Seed source visible to replay tooling. */
+    readonly source: "caller" | "none";
+    /** Caller-supplied seed value, or `null` when no seed was supplied. */
+    readonly value: string | number | null;
+}
+/**
+ * Normalized run inputs persisted inside the replay trace artifact.
+ */
+export interface ReplayTraceRunInputs {
+    /** Run input artifact discriminant. */
+    readonly kind: "replay-trace-run-inputs";
+    /** Mission or intent supplied by the caller. */
+    readonly intent: string;
+    /** Exact normalized protocol config used for execution. */
+    readonly protocol: ProtocolConfig;
+    /** Selected cost/quality tier. */
+    readonly tier: Tier;
+    /** Configured model provider id. */
+    readonly modelProviderId: string;
+    /** Concrete agent roster visible to the protocol. */
+    readonly agents: readonly AgentSpec[];
+    /** Temperature supplied to provider requests. */
+    readonly temperature: number;
+}
+/**
+ * Budget and stop-policy artifact persisted inside replay traces.
+ */
+export interface ReplayTraceBudget {
+    /** Budget artifact discriminant. */
+    readonly kind: "replay-trace-budget";
+    /** Selected cost/quality tier. */
+    readonly tier: Tier;
+    /** Optional hard caps supplied by the caller. */
+    readonly caps?: Omit<Budget, "tier">;
+    /** Optional composable termination policy used by the protocol. */
+    readonly termination?: TerminationCondition;
+}
+/**
+ * Budget state snapshot derived from a cost-bearing trace event.
+ *
+ * @remarks
+ * Replay consumers can inspect this artifact without walking the full event
+ * log. Entries are emitted for model-turn accounting changes, coordination
+ * barriers that expose cumulative cost, budget stops, and final completion.
+ */
+export interface ReplayTraceBudgetStateChange {
+    /** Budget state artifact discriminant. */
+    readonly kind: "replay-trace-budget-state-change";
+    /** Zero-based event index that exposed this budget state. */
+    readonly eventIndex: number;
+    /** Source event type for the budget state. */
+    readonly eventType: "agent-turn" | "broadcast" | "budget-stop" | "final";
+    /** ISO-8601 timestamp from the source event. */
+    readonly at: string;
+    /** Cumulative cost visible at this point in the run. */
+    readonly cost: CostSummary;
+    /** Completed model-turn iteration count when known. */
+    readonly iteration?: number;
+    /** Elapsed runtime in milliseconds when known. */
+    readonly elapsedMs?: number;
+    /** Budget stop reason when this state records a halt. */
+    readonly budgetReason?: BudgetStopReason;
+}
+/**
+ * Provider-neutral protocol decision kinds recorded for replay.
+ */
+export type ReplayTraceProtocolDecisionType = "assign-role" | "select-agent-turn" | "start-model-call" | "complete-model-call" | "observe-model-output" | "start-tool-call" | "complete-tool-call" | "collect-broadcast-round" | "stop-for-budget" | "finalize-output";
+/**
+ * Protocol-level decision appended during execution.
+ */
+export interface ReplayTraceProtocolDecision {
+    /** Decision artifact discriminant. */
+    readonly kind: "replay-trace-protocol-decision";
+    /** Zero-based event index that produced this decision. */
+    readonly eventIndex: number;
+    /** Event type that records the decision. */
+    readonly eventType: RunEvent["type"];
+    /** Coordination protocol that made the decision. */
+    readonly protocol: Protocol;
+    /** Provider-neutral decision kind for replay tooling. */
+    readonly decision: ReplayTraceProtocolDecisionType;
+    /** ISO-8601 timestamp from the source event. */
+    readonly at: string;
+    /** Agent involved in the decision, when agent-scoped. */
+    readonly agentId?: string;
+    /** Role involved in the decision, when agent-scoped. */
+    readonly role?: string;
+    /** Provider call involved in the decision, when model-scoped. */
+    readonly callId?: string;
+    /** Provider involved in the decision, when model-scoped. */
+    readonly providerId?: string;
+    /** Tool call involved in the decision, when tool-scoped. */
+    readonly toolCallId?: string;
+    /** Tool identity involved in the decision, when tool-scoped. */
+    readonly tool?: RuntimeToolIdentity;
+    /** One-based protocol turn for turn-scoped decisions. */
+    readonly turn?: number;
+    /** Coordinator phase for coordinator protocol turn decisions. */
+    readonly phase?: "plan" | "worker" | "final-synthesis";
+    /** One-based broadcast round for grouped broadcast decisions. */
+    readonly round?: number;
+    /** Number of transcript entries visible after this decision. */
+    readonly transcriptEntryCount?: number;
+    /** Number of contributions collected at a broadcast barrier. */
+    readonly contributionCount?: number;
+    /** Prompt/input associated with turn decisions. */
+    readonly input?: string;
+    /** Output associated with turn or final decisions. */
+    readonly output?: string;
+    /** Cumulative cost visible at this decision point. */
+    readonly cost?: CostSummary;
+    /** Normalized budget stop reason for budget-stop decisions. */
+    readonly budgetReason?: BudgetStopReason;
+}
+/**
+ * Provider call metadata and response captured for replay inspection.
+ */
+export interface ReplayTraceProviderCall {
+    /** Provider call artifact discriminant. */
+    readonly kind: "replay-trace-provider-call";
+    /** Stable call id within the run. */
+    readonly callId: string;
+    /** Configured model provider id. */
+    readonly providerId: string;
+    /** ISO-8601 timestamp before the provider call started. */
+    readonly startedAt: string;
+    /** ISO-8601 timestamp after the provider call completed. */
+    readonly completedAt: string;
+    /** Agent that requested this provider call. */
+    readonly agentId: string;
+    /** Role that requested this provider call. */
+    readonly role: string;
+    /** Request handed to the configured model provider. */
+    readonly request: ModelRequest;
+    /** Response returned by the configured model provider. */
+    readonly response: ModelResponse;
+}
+/**
+ * Final output artifact persisted inside replay traces.
+ */
+export interface ReplayTraceFinalOutput {
+    /** Final output artifact discriminant. */
+    readonly kind: "replay-trace-final-output";
+    /** Final synthesized output returned by the run. */
+    readonly output: string;
+    /** Total cost at completion. */
+    readonly cost: CostSummary;
+    /** ISO-8601 completion timestamp from the terminal event. */
+    readonly completedAt: string;
+    /** Link to the completed transcript artifact. */
+    readonly transcript: TranscriptLink;
+}
+//# sourceMappingURL=replay.d.ts.map