suspension

type ClaimVersion struct {
	RunID        id.AgentRunID
	SuspensionID id.SuspensionID
	RunRevision  int64
}

type Continuation struct {
	ToolResults   []verification.ToolResult `json:"tool_results,omitempty"`
	SchemaVersion int                       `json:"schema_version,omitempty"`
	Prepared      []byte                    `json:"prepared,omitempty"`
	Provenance    run.ExecutionProvenance   `json:"provenance,omitempty"`
	Usage         execution.Usage           `json:"usage,omitempty"`
	Messages      []llm.Message             `json:"messages"`
	SystemPrompt  string                    `json:"system_prompt"`
	StepIndex     int                       `json:"step_index"`
	TokensUsed    int                       `json:"tokens_used"`

	// NewMessagesFrom is the index in Messages where this run's own
	// messages begin. Everything before it is conversation history the
	// run loaded at startup and must never save again.
	//
	// Without it a resume has no way to tell the two apart, and its
	// first SaveConversation writes the whole history back as new rows.
	// That is not hypothetical: it shipped in v1.8.0, and agents went
	// deaf after about six runs because the duplicated rows filled the
	// fixed read window until it held nothing recent. The engine tracks
	// this boundary as newMessagesFrom in both react loops; this field
	// is the same number, carried across the pause.
	NewMessagesFrom int `json:"new_messages_from"`

	// SessionID is the session the run was loading from and saving to. A
	// resume cannot re-derive it: resolveSession lazily creates a
	// default session under a create race, so asking it again after a
	// pause can land on a different session than the one the messages
	// above came from.
	SessionID id.SessionID `json:"session_id,omitempty"`

	// Config is the resolved configuration the run was executing under.
	// See RunConfig: a resume builds its config from this and never
	// re-merges the agent's, so the run's own overrides survive the
	// pause.
	Config RunConfig `json:"config"`
}

type Ending struct {
	Kind EndingKind `json:"kind"`
	// Reason is what the run's error says, for an expiry.
	Reason string `json:"reason,omitempty"`
}

type EndingKind string

type LeasedClaim struct {
	// Version pins the pause and the run revision read before the claim,
	// exactly as ClaimSuspensionVersion does.
	Version ClaimVersion
	// ExpiredBy, when set, claims only a pause whose deadline passed at or
	// before it: the expiry sweep's claim. Otherwise only a pause that has
	// not expired is claimed, and an expired one is ErrSuspensionExpired.
	ExpiredBy time.Time
	// Lease is the claimer's lease. An owner with no expiry, or an expiry
	// with no owner, is refused with cortex.ErrRunLeaseLost.
	Lease run.Lease
	// First, when set, is the run's first progress snapshot under the new
	// lease, written in the same transaction. Its Owner must be Lease.Owner.
	First *Progress
}

type LeasedClaimStore interface {
	// ClaimSuspensionLeased claims the pinned pause under claim.Lease and
	// returns it with ClaimedRun set. The refusals are ClaimSuspensionVersion's
	// (cortex.ErrNotSuspended, cortex.ErrRunConflict,
	// cortex.ErrSuspensionExpired), plus cortex.ErrRunLeaseLost for a half
	// lease or a First owned by someone else.
	ClaimSuspensionLeased(ctx context.Context, claim LeasedClaim) (*Suspension, error)
	// ClaimContinuationLeased is run.ContinuationStore's ClaimContinuation
	// under a lease that must be set, writing first in the same transaction.
	ClaimContinuationLeased(ctx context.Context, runID id.AgentRunID, lease run.Lease, first *Progress) (*run.Run, error)
	// AdmitResumeLeased is ResumeAdmissionStore's AdmitResume, taking the
	// run's lease and writing first in the transaction that claims the
	// pause. An admitter that dies before it starts the resume leaves a
	// lease that lapses and the reply in the snapshot. An admission recorded
	// before is returned as it is, and takes nothing.
	AdmitResumeLeased(ctx context.Context, req ResumeAdmissionRequest, lease run.Lease, first *Progress) (ResumeAdmission, error)
	// StartResumeLeased is ResumeAdmissionStore's StartResume, taking the
	// lease of the run the admission claimed, whoever held it, and writing
	// first, in the transaction that grants execution: the one worker
	// allowed to execute the resume holds the run from then on. It never
	// advances the run's revision, which the admission recorded. A start
	// recorded before is returned as it is, and takes nothing.
	StartResumeLeased(ctx context.Context, runID id.AgentRunID, key id.SuspensionID, digest string, lease run.Lease, first *Progress) (ResumeStart, error)
}

type Notice struct {
	SuspensionID id.SuspensionID
	Reason       SuspendReason
	Pending      []PendingCall
	// ExpiresAt is the suspension's deadline, nil when it has none.
	ExpiresAt *time.Time
	// CheckpointID is the checkpoint a person decides. It is zero unless
	// Reason is ReasonApproval.
	CheckpointID id.CheckpointID
	Scope        cortex.Scope
}

type PendingCall struct {
	// ReplyWith binds an agent reply to the question created by this pause.
	// A tool-call ID alone may be reused by a later model response.
	ReplyWith string `json:"reply_with,omitempty"`
	ID        string `json:"id"`
	Name      string `json:"name"`
	// Arguments is the JSON-encoded argument object, verbatim from the
	// model's tool call.
	Arguments string `json:"arguments"`
	// Note is the authorizer's reason for asking for approval, taken from
	// cortex.ApprovalRequired. It is empty for every other pending call,
	// and for an approval asked for with the bare sentinel.
	Note string `json:"note,omitempty"`
}

type Progress struct {
	RunID id.AgentRunID `json:"run_id"`
	// Scope is the scope the snapshot is stored under. SaveProgress sets it
	// from the context.
	Scope cortex.Scope `json:"scope"`
	// Owner is the lease owner that wrote the snapshot.
	Owner string `json:"owner"`
	// Cont is the run's state at the last durable boundary. Stores encode
	// it the way they encode a suspension's continuation, so Cont.Prepared
	// comes back byte for byte.
	Cont Continuation `json:"continuation"`
	// Started lists the calls that are not safe to retry and were handed
	// to their handler since Cont.
	Started []PendingCall `json:"started,omitempty"`
	// Done lists the calls of the current step that finished.
	Done []ProgressResult `json:"done,omitempty"`
	// Ending, when set, is the end a claim was made to write (a cancel or
	// an expiry) and did not get to. A worker that reclaims the run
	// finishes that end instead of continuing the run.
	Ending *Ending `json:"ending,omitempty"`
	// UpdatedAt is when the snapshot was saved. SaveProgress sets it.
	UpdatedAt time.Time `json:"updated_at"`
}

type ProgressResult struct {
	CallID  string `json:"call_id"`
	Content string `json:"content"`
	Error   string `json:"error,omitempty"`
	// Outcome is "completed", "failed" or "denied".
	Outcome string `json:"outcome"`
}

type ProgressStore interface {
	// SaveProgress upserts the run's snapshot at the exact scope, only while the run is running
	// under p.Owner's lease; ErrRunLeaseLost otherwise and nothing is written. An empty Owner
	// never matches, not even a run that holds no lease. On success it sets p.Scope and
	// p.UpdatedAt to what it stored.
	SaveProgress(ctx context.Context, p *Progress) error
	// GetProgress reads the run's snapshot. ErrProgressNotFound when there is none at the exact
	// scope.
	GetProgress(ctx context.Context, runID id.AgentRunID) (*Progress, error)
	// DeleteProgress removes the run's snapshot at the exact scope. It returns nil when there is
	// none.
	DeleteProgress(ctx context.Context, runID id.AgentRunID) error
}

type ReplyDiscoveryStore interface {
	ListAgentReplyRuns(context.Context, id.AgentRunID, int) ([]id.AgentRunID, error)
}

type ResumeAdmission struct {
	SchemaVersion    int                    `json:"schema_version"`
	Request          ResumeAdmissionRequest `json:"request"`
	RequestDigest    string                 `json:"request_digest"`
	SuspensionDigest string                 `json:"suspension_digest"`
	ClaimedRevision  int64                  `json:"claimed_revision"`
	AdmittedAt       time.Time              `json:"admitted_at"`
	Fresh            bool                   `json:"-"`
}

type ResumeAdmissionPage struct {
	Admissions []ResumeAdmission
	Next       string
}

type ResumeAdmissionRequest struct {
	Scope   cortex.Scope `json:"scope"`
	Version ClaimVersion `json:"version"`
	Input   []byte       `json:"input"`
}

type ResumeAdmissionStore interface {
	AdmitResume(context.Context, ResumeAdmissionRequest) (ResumeAdmission, error)
	GetResumeAdmission(context.Context, id.AgentRunID, id.SuspensionID) (ResumeAdmission, error)
	ListResumeAdmissions(context.Context, string, int) (ResumeAdmissionPage, error)
	StartResume(context.Context, id.AgentRunID, id.SuspensionID, string) (ResumeStart, error)
	GetResumeStart(context.Context, id.AgentRunID, id.SuspensionID) (ResumeStart, error)
}

type ResumeCloser interface {
	Close(context.Context, ResumeClosureRequest) (ResumeClosure, error)
}

type ResumeClosure struct {
	Request       ResumeClosureRequest `json:"request"`
	RequestDigest string               `json:"request_digest"`
	EventID       id.ID                `json:"event_id"`
	RunRevision   int64                `json:"run_revision"`
	ClosedAt      time.Time            `json:"closed_at"`
	Fresh         bool                 `json:"-"`
}

type ResumeClosureAuthorizer interface {
	AuthorizeResumeClosure(context.Context, ResumeClosureRequest) error
}

type ResumeClosureFence interface {
	WithResumeClosure(context.Context, ResumeClosureRequest, func(ResumeClosureRequest) error) error
}

type ResumeClosureRequest struct {
	SchemaVersion   int          `json:"schema_version"`
	Scope           cortex.Scope `json:"scope"`
	Version         ClaimVersion `json:"version"`
	AdmissionDigest string       `json:"admission_digest"`
	StartDigest     string       `json:"start_digest"`
	RunRevision     int64        `json:"run_revision"`
	Actor           string       `json:"actor"`
	Issuer          string       `json:"issuer"`
	IssuerRevision  string       `json:"issuer_revision"`
	ProofRef        string       `json:"proof_ref"`
	ProofDigest     string       `json:"proof_digest"`
	ObservedAt      time.Time    `json:"observed_at"`
	ExpiresAt       time.Time    `json:"expires_at"`
}

type ResumeClosureStore interface {
	CloseResume(context.Context, ResumeClosureRequest) (ResumeClosure, error)
	GetResumeClosure(context.Context, id.AgentRunID, id.SuspensionID) (ResumeClosure, error)
}

type ResumeExpiry struct {
	SchemaVersion int          `json:"schema_version"`
	Version       ClaimVersion `json:"version"`
	Scope         cortex.Scope `json:"scope"`
	RequestDigest string       `json:"request_digest"`
	EventID       id.ID        `json:"event_id"`
	RunRevision   int64        `json:"run_revision"`
	ExpiredAt     time.Time    `json:"expired_at"`
	Fresh         bool         `json:"-"`
}

type ResumeRecoveryStore interface {
	LatestResumeAdmission(context.Context, id.AgentRunID) (ResumeAdmission, error)
	ExpireResumeAdmission(context.Context, id.AgentRunID, id.SuspensionID, string) (ResumeExpiry, error)
	GetResumeExpiry(context.Context, id.AgentRunID, id.SuspensionID) (ResumeExpiry, error)
}

type ResumeStart struct {
	SchemaVersion int          `json:"schema_version"`
	Version       ClaimVersion `json:"version"`
	Scope         cortex.Scope `json:"scope"`
	RequestDigest string       `json:"request_digest"`
	StartedAt     time.Time    `json:"started_at"`
	Fresh         bool         `json:"-"`
	Suspension    *Suspension  `json:"-"`
}

type RunConfig struct {
	Context            *cognitive.ContextPolicy `json:"context,omitempty"`
	Publication        safety.Policy            `json:"publication"`
	Budget             execution.Budget         `json:"budget,omitempty"`
	AllToolsRestricted bool                     `json:"all_tools_restricted,omitempty"`
	Model              string                   `json:"model,omitempty"`
	Temperature        *float64                 `json:"temperature,omitempty"`
	MaxSteps           int                      `json:"max_steps,omitempty"`
	MaxTokens          int                      `json:"max_tokens,omitempty"`
	ReasoningLoop      string                   `json:"reasoning_loop,omitempty"`
	Tools              []string                 `json:"tools,omitempty"`
	PersonaRef         string                   `json:"persona_ref,omitempty"`

	// ToolsRestricted says Tools is an explicit allowlist even when it
	// is empty, which is what an overlay that withdrew the agent's last
	// tool produces. It travels with the continuation because a resumed
	// run rebuilds its config from here and from nowhere else: without
	// it, an empty list would read as "every registered tool" and the
	// resume would hand back exactly what the overlay took away.
	//
	// It is absent from rows written before this field existed, and
	// decodes there as false, which is the behavior those runs had.
	// The flag can therefore be LOST across an upgrade, but it can
	// never be spuriously SET. That is the safe direction here: losing
	// it resumes an old run under the tool rules it was suspended
	// under, where inventing it would strip tools from a run nobody
	// restricted.
	ToolsRestricted bool `json:"tools_restricted,omitempty"`
}

type Store interface {
	// CreateSuspension writes a new suspension row for a run that just
	// paused.
	CreateSuspension(ctx context.Context, s *Suspension) error

	// GetSuspension reads the suspension for a run without changing
	// anything. Callers that intend to resume the run must use
	// ClaimSuspension instead: a Get followed by a separate write is the
	// race ClaimSuspension exists to close.
	GetSuspension(ctx context.Context, runID id.AgentRunID) (*Suspension, error)

	// ClaimSuspension is the concurrency primitive for resume.
	// Implementations must perform the run's paused-to-running
	// transition and the suspension read as ONE atomic operation, not a
	// read followed by a separate write: that gap is exactly the race
	// this method exists to close, since two concurrent resume calls
	// must not both observe a paused run and proceed. The caller that
	// loses the race gets cortex.ErrNotSuspended, not the suspension it
	// lost the race for.
	ClaimSuspension(ctx context.Context, runID id.AgentRunID) (*Suspension, error)

	// DeleteSuspension removes a suspension row. Callers use this once a
	// resume has fully completed, or as part of the expiry sweep once an
	// expired suspension has been handled.
	DeleteSuspension(ctx context.Context, runID id.AgentRunID) error

	// ListExpired returns suspensions whose ExpiresAt is at or before
	// now, bounded to at most limit rows, within the caller's scope.
	ListExpired(ctx context.Context, now time.Time, limit int) ([]*Suspension, error)

	// ListExpiredAcrossScopes is ListExpired with the scope filter
	// DELIBERATELY BYPASSED: it returns expired suspensions from every
	// scope in the database, and it is the one read in this interface
	// that does.
	//
	// It exists for the engine's expiry sweeper and nothing else. A
	// sweeper is process infrastructure started by Engine.Start, so
	// there is no request scope on its context and no way to enumerate
	// the scopes that have rows; ListExpired would sweep whichever scope
	// the sweeper's context happened to carry, which in practice is
	// none. Hence a second method rather than a flag or a sentinel
	// scope: a cross-scope read has to be visible as one at the call
	// site, and no handler can reach this by passing a zero value.
	//
	// Crossing scopes to FIND the work does not license doing the work
	// unscoped. Callers must rebind their context to each returned
	// suspension's own Scope before touching that run, exactly as Resume
	// does.
	ListExpiredAcrossScopes(ctx context.Context, now time.Time, limit int) ([]*Suspension, error)

	// ClaimExpiredSuspension is ClaimSuspension's mirror for the expiry
	// sweeper: the same atomic paused-to-running transition, conditioned
	// on the suspension being PAST its deadline rather than short of it.
	//
	// The two predicates partition the same row, which is what makes a
	// resume and a sweep exclusive rather than merely unlikely to
	// collide. A resume that beats the deadline claims the run and the
	// sweeper can no longer take it; a sweep that finds the deadline
	// passed takes the run and no resume can claim it afterwards. Both
	// answer against the same stored ExpiresAt, so there is no window
	// where the two agree the row is theirs.
	//
	// Zero rows matched means somebody else got there first, and it
	// returns cortex.ErrNotSuspended. The sweeper skips such a run
	// rather than failing it: it is either gone, already resumed, or no
	// longer paused.
	ClaimExpiredSuspension(ctx context.Context, runID id.AgentRunID, now time.Time) (*Suspension, error)
}

type SuspendReason string

type Suspension struct {
	// ClaimedRun is the snapshot returned by an atomic claim, including its
	// new revision. It is transient and is never saved as suspension content.
	ClaimedRun *run.Run `json:"-"`
	cortex.Entity
	ID    id.SuspensionID `json:"id"`
	RunID id.AgentRunID   `json:"run_id"`

	// Scope is stored so Resume re-derives authorization from the scope
	// the run STARTED under, rather than trusting the scope of whoever
	// happens to call Resume. A resume arriving with different authority
	// must not quietly continue with it.
	Scope cortex.Scope `json:"scope"`

	Reason    SuspendReason `json:"reason"`
	Pending   []PendingCall `json:"pending,omitempty"`
	Cont      Continuation  `json:"continuation"`
	ExpiresAt *time.Time    `json:"expires_at,omitempty"`
}

type VersionedStore interface {
	ClaimSuspensionVersion(context.Context, ClaimVersion) (*Suspension, error)
}