package extension

// Package extension hosts the ProfileExtension HTTP runtime: the Agent-visible
// Extension Catalog projection and the /runtime/ext routes (spec §6.2).
//
// The Catalog DTOs in this file are leak-proof by construction: they project
// ONLY from registry.RegisteredExtension.Definition (the common, Agent-visible
// Catalog) and never reference the server-only ExternalBinding. A dedicated
// adversarial test (dto_test.go) reflects over every DTO struct field to assert
// only Agent-visible JSON keys are serializable, so a future field addition
// that carries endpoint/binding/auth/connection/secret state fails the build.

// rootResponse is the Agent-visible root Catalog (spec §6.3): the authorized
// Extensions, each with the FULL descriptors of its authorized Actions, in one
// document. It carries no endpoint, binding, auth profile, connection,
// credential, secret, or catalog identity — the document is pure content and
// the client compares content, not identities.
type rootResponse struct {
	Extensions []extensionEntry `json:"extensions"`
}

// extensionEntry is one authorized Extension with its full Action descriptors.
type extensionEntry struct {
	ExtensionName string          `json:"extensionName"`
	DisplayName   string          `json:"displayName"`
	Actions       []actionCatalog `json:"actions"`
}

// actionCatalog is the complete Agent-visible descriptor for one action: the
// curated texts, the safety class, the input/output JSON schemas, and the
// curated example.
//
// OutputSchema intentionally omits the "omitempty" JSON option: a nil output
// schema (no output contract) and an explicit empty-object schema ({}) are
// semantically distinct and both Agent-visible, matching the registry and
// presets convention.
type actionCatalog struct {
	Name         string         `json:"name"`
	Summary      string         `json:"summary,omitempty"`
	Description  string         `json:"description,omitempty"`
	Safety       safety         `json:"safety"`
	InputSchema  map[string]any `json:"inputSchema,omitempty"`
	OutputSchema map[string]any `json:"outputSchema"`
	Example      any            `json:"example,omitempty"`
}

// safety is the closed authorization and guidance contract (spec §4.5). It is
// the Agent-visible projection of internal/extensions/spec.Safety. The class
// alone carries the contract (destructive is exactly class=destructive and
// idempotence is presentation-only, so neither boolean crosses the wire). A
// dedicated local type (rather than embedding the presets type) keeps this
// package decoupled from the presets module and gives the no-secrets test a
// single, owned shape.
type safety struct {
	Class string `json:"class"`
}