registry

type Config struct {
	// Redis is the Redis client for Pulse operations. Required.
	Redis *redis.Client
	// Name is the registry name used to derive Pulse resource names.
	// Multiple nodes with the same Name and Redis connection form a cluster,
	// sharing state and coordinating health checks automatically.
	//
	// The pool, health map, and registry map names are derived as:
	//   - Pool: "<name>"
	//   - Health map: "<name>:health"
	//   - Registry map: "<name>:toolsets"
	//
	// Defaults to "registry" if not provided.
	Name string
	// Logger receives health tracker logs (pings, transitions, failures).
	// When nil, health tracking logs are suppressed.
	Logger telemetry.Logger
	// PingInterval is the interval between health check pings.
	// Defaults to 10 seconds if not provided.
	PingInterval time.Duration
	// MissedPingThreshold is the number of consecutive missed pings
	// before marking a toolset as unhealthy.
	// Defaults to 3 if not provided.
	MissedPingThreshold int
	// ResultStreamMappingTTL is the TTL for tool_use_id to stream_id mappings.
	// ResultStreamTTL is the TTL for per-call result streams in Redis.
	// Defaults to 15 minutes if not provided.
	ResultStreamTTL time.Duration
	// PoolNodeOptions are additional options for the Pulse pool node.
	PoolNodeOptions []pool.NodeOption
}

type HealthTracker interface {
	// Health returns the current health state for a toolset.
	//
	// Contract:
	//   - Health is derived from the last recorded Pong timestamp and the
	//     configured staleness threshold.
	//   - If the toolset has never ponged (or no entry exists), Health reports
	//     Healthy=false with LastPong unset.
	Health(toolset string) (ToolsetHealth, error)

	// RecordPong records a pong response for a toolset when the pong matches
	// the current catalog registration epoch.
	RecordPong(ctx context.Context, toolset string, pingID string) error

	// IsHealthy returns whether a toolset has healthy providers.
	// A toolset is healthy if a pong was received within the staleness threshold.
	IsHealthy(toolset string) bool

	// StartPingLoop ensures this node participates in health tracking for a
	// catalog-registered toolset. Cross-node participation is derived from the
	// shared catalog, not from a second membership index.
	StartPingLoop(ctx context.Context, toolset string) error

	// StopPingLoop stops local health tracking participation for an
	// unregistered toolset and clears its shared health state. Other nodes stop
	// via catalog change propagation.
	StopPingLoop(ctx context.Context, toolset string)

	// Close stops all ping loops and releases resources.
	Close() error
}

type HealthTrackerOption func(*healthTrackerOptions)

type Registry struct {
	// contains filtered or unexported fields
}

type Service struct {
	// contains filtered or unexported fields
}

type StreamManager interface {
	// GetOrCreateStream returns the stream for a toolset, creating it if needed.
	// The stream ID is deterministic based on the toolset name.
	GetOrCreateStream(ctx context.Context, toolset string) (clientspulse.Stream, string, error)

	// GetStream returns the stream for a toolset if it exists.
	// Returns nil if the toolset has no associated stream.
	GetStream(toolset string) clientspulse.Stream

	// RemoveStream removes the stream tracking for a toolset.
	// This does not destroy the underlying Pulse stream.
	RemoveStream(toolset string)

	// PublishToolCall publishes a tool call message to the toolset's stream.
	PublishToolCall(ctx context.Context, toolset string, msg toolregistry.ToolCallMessage) error
}

type ToolsetHealth struct {
	// Healthy reports whether a provider pong was received within the configured threshold.
	Healthy bool
	// LastPong is the timestamp of the last recorded pong when available.
	LastPong time.Time
	// Age is the duration since LastPong when available.
	Age time.Duration
	// StalenessThreshold is the configured maximum acceptable pong age.
	StalenessThreshold time.Duration
}