suspend

type Answer struct {
	// QuestionID is the nonce of the Question this answers.
	QuestionID string `json:"question_id"`
	// Text is the raw friend answer. It flows raw all the way to the executor's
	// Resume, which owns framing (checkpoint.FramedAnswers) before the answer
	// reaches a provider payload — no layer in between frames or caps it.
	Text string `json:"text"`
	// AnsweredAt is when the friend replied.
	AnsweredAt time.Time `json:"answered_at"`
}

type Coordinator struct {
	// Store is the durable home for suspended envelopes.
	Store checkpoint.Store
	// Questions is the friend transport for the pending question/answer.
	Questions QuestionStore
	// WakeInterval is the base requeue delay between wake probes. Must be > 0.
	WakeInterval time.Duration

	// Jitter, when > 0, spreads wake requeues across [WakeInterval,
	// WakeInterval+Jitter) so keys that suspended together don't stampede back
	// at once. Optional; zero means no jitter.
	Jitter time.Duration

	// DefaultParkDeadline bounds how long a park may wait for an answer when the
	// suspension's envelope carries no Deadline of its own: Suspend stamps
	// Envelope.Deadline = now + DefaultParkDeadline before persisting, so
	// Wake's dead-checkpoint sweep retires every park once its answer SLA
	// lapses — a suspension can never wait forever. An explicit caller-set
	// Deadline is preserved untouched. Optional; zero means the 14-day default
	// (aligned with the answer SLA and checkpoint-bucket TTL); negative values
	// are rejected by Suspend.
	DefaultParkDeadline time.Duration

	// WithBackup, if set, is invoked after the envelope is durably Saved but
	// before the question is posted, giving callers a hook to mirror the
	// checkpoint elsewhere (e.g. a secondary store or an audit log). A non-nil
	// error aborts the suspension.
	WithBackup func(ctx context.Context, key string, env *checkpoint.Envelope) error

	// ValidateEnvelope, if set, is consulted on Wake against a parked envelope.
	// Returning an error that Is(err, checkpoint.ErrConfigDrift) causes Wake to
	// treat the checkpoint as unusable: it is deleted and WakeFresh is returned.
	ValidateEnvelope func(ctx context.Context, env *checkpoint.Envelope) error
	// contains filtered or unexported fields
}

type Question struct {
	// ID is the pause nonce. Fresh per Suspend; never reused.
	ID string `json:"id"`
	// Key is the reconciler/workqueue key the paused run belongs to.
	Key string `json:"key"`
	// RunID disambiguates successive runs of the same key (copied from the
	// suspended envelope, diagnostics only).
	RunID string `json:"run_id,omitempty"`
	// Prompt is the human-readable question text.
	Prompt string `json:"prompt"`
	// AskedAt is when the question was posted.
	AskedAt time.Time `json:"asked_at"`
}

type QuestionStore interface {
	// Ask posts q as the pending question for key, replacing any previous
	// pending question (and its answer) for that key. q.ID is the fresh nonce.
	Ask(ctx context.Context, key string, q Question) error

	// Pending returns the currently pending Question for key; the bool is
	// false (with a zero Question and nil error) when none is pending. Wake
	// reads it before sweeping a dead checkpoint so the orphaned question can
	// be consumed by its nonce.
	Pending(ctx context.Context, key string) (Question, bool, error)

	// Answer returns the friend reply for key's pending question. The bool is
	// false (with a zero Answer and nil error) when the question is unanswered
	// or when the only available answer is bound to a stale question ID.
	Answer(ctx context.Context, key string) (Answer, bool, error)

	// Consume marks the question identified by questionID as fully handled for
	// key, so a later Answer for the same key returns false until a new Ask.
	// It is a no-op if questionID does not match the pending question (the
	// answer belonged to a superseded pause).
	Consume(ctx context.Context, key, questionID string) error
}

type WakeDecision int

type WakeResult struct {
	// Envelope is the claimed checkpoint envelope to rebuild the request from.
	Envelope *checkpoint.Envelope
	// Answer is the friend reply, passed raw to the executor's Resume — which
	// owns framing — and paired back to the suspending tool call.
	Answer Answer
	// Token is the CAS handle that was used to claim (delete) the envelope,
	// retained for telemetry and idempotency assertions.
	Token checkpoint.Token
}