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 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"`
}

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)
}