hitl

type ApprovalRequest struct {
	ID            string         `json:"id"`
	ThreadID      string         `json:"thread_id"`
	RunID         string         `json:"run_id"`
	TenantID      string         `json:"tenant_id,omitempty"`
	ToolName      string         `json:"tool_name"`
	Args          string         `json:"args"`
	Status        ApprovalStatus `json:"status"`
	Feedback      string         `json:"feedback,omitempty"`
	CreatedAt     time.Time      `json:"created_at"`
	ExpiresAt     *time.Time     `json:"expires_at,omitempty"`
	ResolvedAt    *time.Time     `json:"resolved_at,omitempty"`
	ResolvedBy    string         `json:"resolved_by,omitempty"`
	CreatedBy     string         `json:"created_by,omitempty"`
	SenderContext string         `json:"sender_context,omitempty"`
	Question      string         `json:"question,omitempty"`
}

type ApprovalStatus string

type ApprovalStore interface {
	// Create persists a new pending approval and returns it with a generated ID.
	Create(ctx context.Context, req CreateRequest) (ApprovalRequest, error)

	// Resolve updates the approval's status to approved or rejected.
	// It unblocks any goroutine waiting in WaitForResolution for the same ID.
	Resolve(ctx context.Context, req ResolveRequest) error

	// WaitForResolution blocks until the given approval is resolved or the
	// context is cancelled. Returns the resolved ApprovalRequest.
	WaitForResolution(ctx context.Context, approvalID string) (ApprovalRequest, error)

	// RecoverPending handles approvals left in "pending" state after a restart.
	// Approvals older than maxAge are marked as expired; recent ones get their
	// waiter channels re-registered so they can still be resolved via the API.
	RecoverPending(ctx context.Context, maxAge time.Duration) (RecoverResult, error)

	// ListPending returns all approval requests currently in "pending" state
	// whose deadline has not expired.
	// Without this, external systems (e.g. the GUILD API) would have no way
	// to discover which tool calls are waiting for human approval.
	ListPending(ctx context.Context) ([]ApprovalRequest, error)

	// Get returns the approval request by ID (pending or resolved).
	// Used by the approve endpoint to read tool name and args when adding to the approve list.
	Get(ctx context.Context, approvalID string) (ApprovalRequest, error)

	// ExpireStale marks all pending approvals past their expires_at as expired.
	// Returns the number of rows affected. Called periodically by a background
	// reaper goroutine.
	ExpireStale(ctx context.Context) (int64, error)

	// Close releases any resources held by the store.
	Close() error

	IsAllowed(toolName string) bool
}

type Config struct {
	AlwaysAllowed []string      `yaml:"always_allowed,omitempty" toml:"always_allowed,omitempty" json:"always_allowed"`
	DeniedTools   []string      `yaml:"denied_tools,omitempty" toml:"denied_tools,omitempty" json:"denied_tools"`
	ApprovalTTL   time.Duration `yaml:"approval_ttl,omitempty" toml:"approval_ttl,omitempty" json:"approval_ttl"`
	CacheTTL      time.Duration `yaml:"cache_ttl,omitempty" toml:"cache_ttl,omitempty" json:"cache_ttl"`
}

type CreateRequest struct {
	ThreadID      string
	RunID         string
	TenantID      string
	ToolName      string
	Args          string
	CreatedBy     string // principal ID of the user who initiated the tool call
	SenderContext string // originating sender (e.g. "slack:U123:C456")
	Question      string // original user question — needed for replay-on-resume
}

type RecoverResult struct {
	Expired    int                  // approvals that were too old and marked expired
	Recovered  int                  // approvals that had waiter channels re-registered
	Replayable []ReplayableApproval // recent approvals with a saved question, eligible for replay
}

type ReplayableApproval struct {
	ApprovalID    string
	Question      string
	SenderContext string
}

type ResolveRequest struct {
	ApprovalID string
	Decision   ApprovalStatus
	ResolvedBy string
	Feedback   string
}