registry

type AgentConfig struct {
	// Prompts is the agent's prompt set. Order is not semantic — the
	// hash canonicaliser sorts before hashing.
	Prompts []string
	// Tools is the agent's tool bindings (name + schema digest). Order
	// is not semantic — sorted before hashing.
	Tools []ToolDescriptor
	// PlannerConfig is the planner's configuration key/value set.
	PlannerConfig map[string]string
	// ModelPolicy is the model-selection / model-policy key/value set.
	ModelPolicy map[string]string
}

type AgentControlPayload struct {
	events.SafeSealed
	AgentID  string
	Command  string
	Reason   string // already passed through audit.Redactor
	IssuedAt int64  // unix nanoseconds
}

type AgentDeregisteredPayload struct {
	events.SafeSealed
	AgentID         string
	RegistrationKey string
	DeregisteredAt  int64 // unix nanoseconds
}

type AgentHealthPayload struct {
	events.SafeSealed
	AgentID    string
	Health     string // string form of Health
	ReportedAt int64  // unix nanoseconds
}

type AgentRecord struct {
	// AgentID is the stable registration identity — a ULID minted once
	// at first registration, persisted, rehydrated on restart. For a
	// HostingRemote agent it is a *handle*: runtime-instance-local,
	// never assumed globally unique.
	AgentID string
	// Incarnation bumps on every process start (every Register of an
	// already-known RegistrationKey). incarnation == 1 is the first
	// registration.
	Incarnation uint64
	// VersionHash is the deterministic content hash of the agent's
	// configuration (D-068). Stable across a plain restart; bumps iff
	// configuration content changed. Empty for HostingRemote agents
	// (the configuration is owned by the remote operator).
	VersionHash string
	// RegistrationKey is the operator-stable logical-agent key. It is
	// what distinguishes restart (same key → same agent_id) from
	// recreate (Deregister + Register of the same key → fresh
	// agent_id). It is NOT an isolation principal.
	RegistrationKey string
	// Identity is the (tenant, user, session) triple the agent is
	// registered within. The registry scopes ALL storage by this
	// triple — never by AgentID.
	Identity identity.Identity
	// Hosting discriminates locally-hosted vs connect-to-remote.
	Hosting Hosting
	// AgentCardRef references the canonical A2A AgentCard for a
	// HostingRemote agent. Empty for HostingLocal agents.
	AgentCardRef string
	// DisplayName is the operator-facing cosmetic label.
	DisplayName string
	// Health is the last-reported / last-set operational health.
	Health Health
	// RegisteredAt is the wall-clock time of the FIRST registration
	// (incarnation 1). Stable across restarts.
	RegisteredAt time.Time
	// UpdatedAt is the wall-clock time of the most recent mutation
	// (re-registration, health report, control command).
	UpdatedAt time.Time
}

type AgentRegisteredPayload struct {
	events.SafeSealed
	AgentID         string
	RegistrationKey string
	Incarnation     uint64
	VersionHash     string
	Hosting         string // string form of Hosting
	RegisteredAt    int64  // unix nanoseconds
}

type AgentRegistry interface {
	// Register mints (or rehydrates) a locally-hosted agent's
	// registration identity.
	//
	//   - First registration of `key`: mints a fresh agent_id (ULID),
	//     incarnation = 1, version_hash = hash(cfg), emits
	//     agent.registered.
	//   - Re-registration of a known `key` (restart): keeps the
	//     agent_id, bumps incarnation, recomputes version_hash (stable
	//     iff cfg content unchanged), emits agent.restarted.
	//
	// Returns a copy of the resulting AgentRecord.
	Register(ctx context.Context, key string, cfg AgentConfig, opts RegisterOptions) (*AgentRecord, error)

	// RegisterRemote registers a connect-to-remote agent (D-060). The
	// local agent_id is a *handle*; cardRef references the canonical
	// A2A AgentCard owned by the remote operator. Semantics mirror
	// Register (first vs re-registration of `key`), but no version_hash
	// is computed — the configuration is owned remotely.
	RegisterRemote(ctx context.Context, key string, cardRef string, opts RegisterOptions) (*AgentRecord, error)

	// Get returns the AgentRecord for agentID, scoped to the ctx
	// identity. Returns a wrapped ErrAgentNotFound when no record
	// exists for that (identity, agentID). Fleet observation — ordinary
	// identity scope.
	Get(ctx context.Context, agentID string) (*AgentRecord, error)

	// List returns every AgentRecord registered under the ctx
	// identity, in agent_id order. One identity's view never includes
	// another identity's agents. Fleet observation — ordinary identity
	// scope.
	List(ctx context.Context) ([]AgentRecord, error)

	// Inspect returns the read-side AgentSnapshot for agentID. Fleet
	// observation — ordinary identity scope.
	Inspect(ctx context.Context, agentID string) (*AgentSnapshot, error)

	// ReportHealth updates the agent's Health and emits agent.health.
	// Fleet observation tier — health is reported BY the agent, not a
	// privileged control command.
	ReportHealth(ctx context.Context, agentID string, h Health) error

	// Deregister removes the agent's record and emits
	// agent.deregistered. A subsequent Register of the same
	// RegistrationKey mints a FRESH agent_id (recreate != restart).
	Deregister(ctx context.Context, agentID string) error

	// Pause requests the agent pause. FLEET CONTROL — requires the
	// elevated control-scope claim (ErrControlScopeRequired otherwise);
	// audit-redacted and emitted.
	Pause(ctx context.Context, agentID string, reason string) error

	// Drain requests the agent drain in-flight work and accept no new
	// work; sets Health = HealthDraining. FLEET CONTROL — requires the
	// elevated control-scope claim; audit-redacted and emitted as
	// agent.drained.
	Drain(ctx context.Context, agentID string, reason string) error

	// Restart requests the agent restart. FLEET CONTROL — requires the
	// elevated control-scope claim; audit-redacted and emitted.
	Restart(ctx context.Context, agentID string, reason string) error

	// ForceStop force-stops the agent; sets Health = HealthStopped.
	// FLEET CONTROL — requires the elevated control-scope claim;
	// audit-redacted and emitted.
	ForceStop(ctx context.Context, agentID string, reason string) error

	// Close releases the registry. Idempotent. Subsequent operations
	// return ErrRegistryClosed. The V1 registry owns no long-lived
	// goroutine; Close exists for interface symmetry and future-
	// proofing.
	Close(ctx context.Context) error
}

type AgentRestartedPayload struct {
	events.SafeSealed
	AgentID            string
	RegistrationKey    string
	Incarnation        uint64
	VersionHash        string
	VersionHashChanged bool
	RestartedAt        int64 // unix nanoseconds
}

type AgentSnapshot struct {
	AgentRecord
	// Local is true iff Hosting == HostingLocal. Convenience for the
	// Console lens so it does not string-compare Hosting.
	Local bool
}

type Clock interface {
	Now() time.Time
}

type Deps struct {
	// Store is the per-runtime-instance StateStore. Driver pluralism
	// (in-mem / SQLite / Postgres) lives here, not at the registry
	// layer (D-027 / D-060).
	Store state.StateStore
	// Bus is the typed event bus the registry emits agent.* events on.
	Bus events.EventBus
	// Redactor redacts the operator-supplied Reason string on every
	// fleet-control command before it is emitted (D-020 / D-066).
	Redactor audit.Redactor
}

type Health string

type Hosting string

type Option func(*Registry)

type RegisterOptions struct {
	// DisplayName is an operator-facing label. Not load-bearing for
	// identity; purely cosmetic for the Console Agents page.
	DisplayName string
}

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

type ToolDescriptor struct {
	Name         string
	SchemaDigest string
}