event

type ActionRequestedPayload struct {
	ActionID      string          `json:"action_id"`
	ActionType    string          `json:"action_type"`
	ActionPayload json.RawMessage `json:"action_payload"`
}

type BudgetChargedPayload struct {
	// Tokens charged in this event.
	Tokens int64 `json:"tokens,omitempty"`
	// USD charged in this event.
	USD float64 `json:"usd,omitempty"`
	// WallClockMs charged in this event (milliseconds).
	WallClockMs int64 `json:"wall_clock_ms,omitempty"`
	// Iterations charged in this event.
	Iterations int `json:"iterations,omitempty"`
	// ActionType is the kind of action that generated this charge ("model" | "tool" | "iteration").
	ActionType string `json:"action_type"`
}

type CompactionAppliedPayload struct {
	Strategy string `json:"strategy"`
	// PlanJSON is the serialised ctxmgr.Plan. Replay reads this instead of re-deciding.
	PlanJSON json.RawMessage `json:"plan_json"`
	// Legacy fields kept for backward compat with SP3 stub (DroppedFrom/To/SummaryRef).
	DroppedFrom uint64 `json:"dropped_from,omitempty"`
	DroppedTo   uint64 `json:"dropped_to,omitempty"`
	SummaryRef  string `json:"summary_ref,omitempty"`
}

type ConvergenceWarningPayload struct {
	// Detector is the name of the detector that fired ("oscillation" | "zero-progress" | "depth").
	Detector string `json:"detector"`
	// Reason is a human-readable explanation.
	Reason string `json:"reason"`
	// Count is how many times the condition has been observed.
	Count int `json:"count"`
}

type Envelope struct {
	// LoopID identifies which loop this event belongs to.
	LoopID LoopID
	// Seq is 1-based and contiguous within a loop. No gaps are permitted.
	Seq uint64
	// Time is injected by the runtime Clock. Transitions must NOT read the system clock;
	// they must use ctx.Now which comes from the last event's Time field.
	Time time.Time
	// Kind identifies the event type. See Kind constants in kinds.go.
	Kind Kind
	// Payload is canonical JSON (sorted keys, no insignificant whitespace).
	// Always produced via event.Marshal.
	Payload []byte
	// Hash is SHA-256(prevHash ‖ LoopID ‖ Seq ‖ Time(RFC3339Nano) ‖ Kind ‖ Payload).
	// The zero value of prevHash is used for the first event in a loop.
	Hash [32]byte
}

type ForkedFromPayload struct {
	// SourceLoopID is the loop ID that was forked from.
	SourceLoopID LoopID `json:"source_loop_id"`
	// AtSeq is the sequence number at which the fork diverged.
	// Events 1..AtSeq are replayed from the source; events after are live.
	AtSeq uint64 `json:"at_seq"`
}

type HumanRequestedPayload struct {
	ActionID string `json:"action_id"`
	Prompt   string `json:"prompt"`
}

type HumanRespondedPayload struct {
	ActionID string `json:"action_id"`
	Response string `json:"response"`
}

type InterruptedPayload struct {
	Reason string `json:"reason"`
}

type IterationStartedPayload struct {
	Iteration int `json:"iteration"`
}

type Kind string

type LoopFinishedPayload struct {
	OutcomeKind string          `json:"outcome_kind"`
	Result      json.RawMessage `json:"result,omitempty"`
	Error       string          `json:"error,omitempty"`
	TotalSpend  json.RawMessage `json:"total_spend,omitempty"`
}

type LoopID string

type LoopStartedPayload struct {
	Name         string          `json:"name"`
	InitialState json.RawMessage `json:"initial_state"`
	Seed         int64           `json:"seed"`
	ConfigHash   string          `json:"config_hash"`
	// SP5: multi-agent fields (zero value = top-level loop)
	ParentID LoopID `json:"parent_id,omitempty"` // empty for root loops
	Depth    int    `json:"depth,omitempty"`     // 0 = root; parent+1 for children
}

type ModelCalledPayload struct {
	ActionID   string          `json:"action_id"`
	Request    json.RawMessage `json:"request"`
	Response   json.RawMessage `json:"response"`
	Usage      ModelUsage      `json:"usage"`
	Provider   string          `json:"provider"`
	Model      string          `json:"model"`
	DurationMs int64           `json:"duration_ms"`
}

type ModelUsage struct {
	In      int     `json:"in"`
	Out     int     `json:"out"`
	CostUSD float64 `json:"cost_usd"`
}

type PolicyDecidedPayload struct {
	// ActionID links back to the ActionRequested event.
	ActionID string `json:"action_id"`
	// Decision is "allow" | "deny" | "ask-human".
	Decision string `json:"decision"`
	// Capability is the capability string that was evaluated.
	Capability string `json:"capability"`
	// Tool is the tool name that triggered the check.
	Tool string `json:"tool"`
	// Reason is the human-readable explanation from the policy engine.
	Reason string `json:"reason"`
}

type ResumedPayload struct{}

type Snapshot struct {
	// LoopID identifies the loop this snapshot belongs to.
	LoopID LoopID
	// Seq is the sequence number of the last event included in this snapshot.
	Seq uint64
	// State is the canonical JSON-encoded state at this point.
	State []byte
	// StateHash is SHA-256 of the State bytes, for integrity verification.
	StateHash [32]byte
	// TakenAt is when the snapshot was recorded (wall clock of the runner).
	TakenAt time.Time
}

type SnapshotTakenPayload struct {
	Seq       uint64 `json:"seq"`
	StateHash string `json:"state_hash"` // hex-encoded SHA-256 of state
}

type StreamChunk struct {
	// Delta contains the incremental content update (e.g., a text delta or tool-use chunk).
	// See core/model.Chunk for the wire format definition.
	Delta json.RawMessage `json:"delta"`
	// Usage is set only in the final chunk; nil for intermediate chunks.
	Usage *ModelUsage `json:"usage,omitempty"`
}

type SubAgentCompletedPayload struct {
	ChildLoopID string `json:"child_loop_id"`
	Definition  string `json:"definition"`
	// OutcomeKind is "Completed" | "BudgetExceeded" | "Stuck" | "Failed" | "Interrupted" | "PolicyDenied".
	OutcomeKind string `json:"outcome_kind"`
	// RespJSON is the marshalled child result (only set when OutcomeKind == "Completed").
	RespJSON json.RawMessage `json:"resp_json,omitempty"`
	// Error is a human-readable error string for non-Completed outcomes.
	Error string `json:"error,omitempty"`
	// ChildSpend is the actual spend charged to the parent ledger for this child.
	ChildSpend json.RawMessage `json:"child_spend,omitempty"`
}

type SubAgentSpawnedPayload struct {
	ChildLoopID string          `json:"child_loop_id"`
	Definition  string          `json:"definition"`
	Request     json.RawMessage `json:"request"`
}

type ToolCalledPayload struct {
	ActionID       string          `json:"action_id"`
	Tool           string          `json:"tool"`
	Args           json.RawMessage `json:"args"`
	Result         json.RawMessage `json:"result"`
	IsError        bool            `json:"is_error"`
	DurationMs     int64           `json:"duration_ms"`
	IdempotencyKey string          `json:"idempotency_key"`
}