state

type Config struct {
	// Backend selects the storage backend: "redis" (default).
	// Future backends: "postgres", "s3", "gcs", "azureblob".
	Backend string `json:"backend"`

	// RedisURL is the Redis connection URL.
	// Example: "redis://redis.infra.svc.cluster.local:6379"
	RedisURL string `json:"redisUrl,omitempty"`

	// RedisPasswordFile, when set, is a file holding the Redis password. It
	// overrides any password in RedisURL. The operator mounts it from a Secret
	// so the password never appears in the model-router ConfigMap.
	RedisPasswordFile string `json:"redisPasswordFile,omitempty"`

	// TTLSeconds is the Redis key TTL beyond the run timeout.
	// Keys auto-expire, so no manual cleanup is needed.
	TTLSeconds int `json:"ttlSeconds,omitempty"`

	// CheckpointKey is the Redis key prefix for this run.
	// Format: "agentorca/runs/<run-id>/state"
	CheckpointKey string `json:"checkpointKey,omitempty"`

	// MaxTokenStreamLen is the Redis XADD MAXLEN (APPROX) applied to each run's token
	// and trace-event stream ("tokens:<ns>:<run>"). The stream holds one entry per
	// streamed token delta + trace event, so long-running/Reasoning-heavy runs can
	// exceed the historical 10k cap and silently lose the OLDEST tokens on replay.
	// 0 (default) = 100000 (~10x the old floor), enough headroom for very long runs
	// while still bounding per-run memory. Tools/agents reading the stream via
	// TailTokens keep the newest entries; set higher per-deployment if you run
	// extremely long sessions. Not related to output truncation mid-stream.
	MaxTokenStreamLen int `json:"maxTokenStreamLen,omitempty"`
}

type Store interface {
	// SaveMessages persists the full conversation history.
	// The implementation may write incrementally (delta) or as a full snapshot.
	SaveMessages(ctx context.Context, key string, messages []json.RawMessage, ttl time.Duration) error

	// LoadMessages retrieves the full conversation history from a checkpoint key.
	LoadMessages(ctx context.Context, key string) ([]json.RawMessage, error)

	// SaveSpend persists the cumulative USD spend for a run.
	// Called after every LLM response so the value survives pod crashes.
	SaveSpend(ctx context.Context, key string, usd float64, ttl time.Duration) error

	// LoadSpend retrieves the cumulative USD spend for a run.
	// Returns 0 if no spend has been recorded.
	LoadSpend(ctx context.Context, key string) (float64, error)

	// SaveToken appends a streaming token to a Redis Stream for real-time UI
	// streaming. Completion is signalled by a terminal trace event (see
	// IsTerminalTraceEventJSON and TailTokens), not by an empty token, so every
	// value saved here is real streaming content under the "t" field.
	SaveToken(ctx context.Context, key string, token string) error

	// SaveTraceEvent appends a structured trace event (JSON) to the Redis Stream.
	// These are interleaved with tokens so the UI can display tool calls in order.
	SaveTraceEvent(ctx context.Context, key string, eventJSON string) error

	// TailTokens returns a channel that yields tokens and trace events in order.
	// Regular tokens are plain strings. Trace events are prefixed with "\x00" followed
	// by JSON. Replays all prior entries first (handles page refresh), then blocks for
	// new ones. The channel closes when ctx is cancelled, when a terminal trace event
	// (done/fail/finalOutput) is received, or after a 10-minute absolute deadline.
	TailTokens(ctx context.Context, key string) (<-chan string, error)

	// ReadTraceEvents returns all trace entries from the token-stream Redis key,
	// ordered by stream entry ID. Tokens are converted to
	// {"type":"token","content":"..."} events; structured trace events (ev field)
	// are returned with their original JSON payload. Each entry receives a
	// sequential id and an ISO timestamp parsed from the Redis stream ID.
	// Returns nil if the stream does not exist or is empty. Used at archival
	// time to snapshot a run's full execution trace into PostgreSQL.
	ReadTraceEvents(ctx context.Context, key string) ([]TraceEntry, error)

	// SaveAnswer stores a human's clarification answer for a run.
	SaveAnswer(ctx context.Context, key string, answer string, ttl time.Duration) error

	// LoadAnswer retrieves a pending clarification answer. Returns "" if none is set.
	LoadAnswer(ctx context.Context, key string) (string, error)

	// SaveHTTPOutput stores the output captured from an http-mode agent run.
	SaveHTTPOutput(ctx context.Context, runName string, output string) error

	// LoadHTTPOutput retrieves http-mode agent run output. Returns "" if not set.
	LoadHTTPOutput(ctx context.Context, runName string) (string, error)

	// DeleteKey removes a key from the store.
	DeleteKey(ctx context.Context, key string) error

	// SaveKV stores an arbitrary key-value pair within a scoped prefix.
	// Values are zstd-compressed. Maximum value size is 1MB (enforced by callers).
	SaveKV(ctx context.Context, scope, key string, value []byte, ttl time.Duration) error

	// LoadKV retrieves a value by scope and key. Returns nil, nil if not found.
	LoadKV(ctx context.Context, scope, key string) ([]byte, error)

	// DeleteKV removes a key within a scope.
	DeleteKV(ctx context.Context, scope, key string) error

	// ListKV returns all keys within a scope.
	ListKV(ctx context.Context, scope string) ([]string, error)

	// ListMessageKeys returns conversation-checkpoint keys matching a glob pattern.
	// The pattern uses Redis SCAN MATCH semantics: '*' matches any run of
	// characters including '/'. Implementations without a native scan should
	// return (nil, nil). Used to enumerate prior-run checkpoints for the
	// warm-pool local cache + history retrieval.
	ListMessageKeys(ctx context.Context, pattern string) ([]string, error)

	// SignalCancel sets a cancellation flag for a run in Redis.
	// The flag has a short TTL (5 minutes) and auto-expires.
	// External systems can also write this key directly: SET cancel:<ns>:<run> 1 EX 300
	SignalCancel(ctx context.Context, ns, runName string) error

	// IsCancelled checks whether the cancel flag is set for a run.
	IsCancelled(ctx context.Context, ns, runName string) (bool, error)

	// Ping verifies connectivity to the backing store (e.g. Redis).
	// Used by /readyz. Implementations must return nil if reachable.
	Ping(ctx context.Context) error

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

type TraceEntry struct {
	// ID is a sequential counter assigned during archival for React key stability.
	ID int `json:"id"`
	// Event is the discriminated trace event JSON (e.g. {"type":"toolCall",...}).
	Event json.RawMessage `json:"event"`
	// TS is an RFC3339 timestamp derived from the Redis stream entry ID.
	TS string `json:"ts"`
	// ChildRunName is set when this entry originated from a child run's stream.
	ChildRunName string `json:"childRunName,omitempty"`
}