run

type AwaitSnapshot struct {
	// Kind identifies which await variant is active.
	Kind string
	// ID is the await correlation identifier.
	ID string
	// ToolName is the tool that triggered the await when applicable.
	ToolName tools.Ident
	// ToolCallID is the tool call that triggered the await when applicable.
	ToolCallID string
	// Question is the clarification question when awaiting clarification.
	Question string
	// Title is the confirmation title when awaiting confirmation.
	Title string
	// Prompt is the confirmation prompt when awaiting confirmation.
	Prompt string
	// ItemCount is the number of external tool items awaited.
	ItemCount int
}

type ChildRunLink struct {
	// ToolName is the agent-tool identifier that started the child run.
	ToolName tools.Ident
	// ToolCallID is the parent tool call identifier.
	ToolCallID string
	// ChildRunID is the workflow run identifier of the nested agent execution.
	ChildRunID string
	// ChildAgentID identifies the agent that executed the child run.
	ChildAgentID agent.Ident
}

type Context struct {
	// RunID uniquely identifies the durable workflow run (infrastructure layer).
	// This corresponds to the workflow engine's execution identifier (e.g.,
	// Temporal WorkflowID). Used for workflow operations, replay, and observability.
	RunID string

	// ParentToolCallID identifies the parent tool call when this run represents a
	// nested agent execution (agent-as-tool). Empty for top-level runs. Used to
	// correlate ToolCallUpdated events and propagate parent-child relationships.
	ParentToolCallID string

	// ParentRunID identifies the run that scheduled this nested execution. Empty for
	// top-level runs. When set, tool events emitted by this run can be attributed to
	// the parent run for streaming/UI purposes.
	ParentRunID string

	// ParentAgentID identifies the agent that invoked this nested execution. Empty
	// for top-level runs. When set alongside ParentRunID, tool events can retain the
	// parent agent identity even though execution occurs in a child agent.
	ParentAgentID agent.Ident

	// SessionID associates related runs into a conversation or interaction thread.
	// Multiple turns in a chat session share the same SessionID. Optional.
	SessionID string

	// TurnID identifies a conversational turn within a session (application layer).
	// Optional. When set, groups all events produced during this turn for UI
	// rendering and conversation tracking. Multiple runs may share the same TurnID
	// if a turn requires pause/resume or retry with a new workflow execution.
	// Format: typically "turn-1", "turn-2", etc. within a session.
	TurnID string

	// Tool identifies the fully-qualified tool name when this run is a nested
	// agent-as-tool execution. For top-level runs (not invoked via a parent tool),
	// Tool is empty. Planners may use this to select method-specific prompts.
	// Format: "<service>.<toolset>.<tool>".
	Tool tools.Ident

	// ToolArgs carries the original JSON arguments for the parent tool when this run
	// is an agent-as-tool execution. Nil for top-level runs. Nested agent planners
	// can use this structured input to render method-specific prompts without
	// reparsing free-form messages.
	ToolArgs rawjson.Message

	// Attempt counts how many times the run has been attempted/resumed.
	Attempt int

	// Labels carries caller-provided metadata (account, priority, etc.).
	Labels map[string]string

	// MaxDuration encodes the wall-clock budget remaining (string form for prompts/telemetry).
	MaxDuration string
}

type Handle struct {
	// RunID uniquely identifies the durable workflow run.
	RunID string
	// AgentID identifies the agent that owns this run.
	AgentID agent.Ident
	// ParentRunID identifies the run that scheduled this run when used for
	// nested agent-as-tool execution. Empty for top-level runs.
	ParentRunID string
	// ParentToolCallID identifies the parent tool call that created this
	// run when used for nested agent-as-tool execution. Empty for
	// top-level runs.
	ParentToolCallID string
}

type Phase string

type Snapshot struct {
	// RunID uniquely identifies the durable workflow run.
	RunID string
	// AgentID identifies the agent that owns the run.
	AgentID agent.Ident
	// SessionID groups related runs into a logical session.
	SessionID string
	// TurnID groups events for a single conversational turn.
	TurnID string

	// Status is the coarse-grained run lifecycle status derived from events.
	Status Status
	// Phase is the current execution phase derived from events.
	Phase Phase

	// StartedAt is the timestamp of the first observed run event.
	StartedAt time.Time
	// UpdatedAt is the timestamp of the last observed run event.
	UpdatedAt time.Time

	// LastAssistantMessage is the most recent assistant message emitted by the run.
	LastAssistantMessage string

	// Await describes the current await state when the run is paused awaiting input.
	Await *AwaitSnapshot

	// ToolCalls summarizes observed tool calls (scheduled, updated, completed).
	ToolCalls []*ToolCallSnapshot

	// ChildRuns links nested agent runs (agent-as-tool) started during this run.
	ChildRuns []*ChildRunLink
}

type Status string

type ToolCallSnapshot struct {
	// ToolCallID uniquely identifies the tool invocation.
	ToolCallID string
	// ParentToolCallID identifies the parent tool call when this call is nested.
	ParentToolCallID string
	// ToolName identifies the executed tool.
	ToolName tools.Ident
	// ScheduledAt is the timestamp of the tool scheduling event.
	ScheduledAt time.Time
	// CompletedAt is the timestamp of the tool result event.
	CompletedAt time.Time
	// Duration is the tool execution duration when the result is observed.
	Duration time.Duration
	// ErrorSummary is a human-readable error message when the tool failed.
	ErrorSummary string
	// ExpectedChildrenTotal tracks the expected number of child tool calls for parent tools.
	ExpectedChildrenTotal int
	// ObservedChildrenTotal tracks how many direct child tool calls were observed as scheduled.
	ObservedChildrenTotal int
}