capability

type Authority struct {
	Reads                  []AuthorityRead `json:"reads,omitempty"`
	MaxTaskDurationSeconds *int            `json:"maxTaskDurationSeconds,omitempty"`
}

type AuthorityRead struct {
	GVK GVKRef `json:"gvk"`
}

type CallerIdentity struct {
	// BearerToken is the raw token from the authenticated request. Empty means
	// there is no identity to forward (any non-HTTP entry point).
	BearerToken string
}

type CapabilityDocument struct {
	APIVersion string         `json:"apiVersion,omitempty"`
	Kind       string         `json:"kind,omitempty"`
	Metadata   *Metadata      `json:"metadata,omitempty"`
	Spec       CapabilitySpec `json:"spec"`
	Status     *Status        `json:"status,omitempty"`
}

type CapabilitySpec struct {
	ServiceRef           Ref        `json:"serviceRef"`
	ServiceName          string     `json:"serviceName"`
	ServiceAgentRef      Ref        `json:"serviceAgentRef"`
	ConfigurationVersion string     `json:"configurationVersion"`
	Knowledge            *Knowledge `json:"knowledge,omitempty"`
	Tools                *Tools     `json:"tools,omitempty"`
	Skills               []Skill    `json:"skills,omitempty"`
	Authority            *Authority `json:"authority,omitempty"`
	// ReportingProject is the Milo project where this service's own team
	// reviews capability-gap reports (see internal/gapreport) — resolved by
	// the service catalog from its own service registration, distinct from
	// Metadata.Namespace (the consumer project this document was entitled
	// to). Optional: when a document declares Tools but no
	// ReportingProject, capability-gap reporting is simply unavailable for
	// that service (no tool is registered) rather than an error.
	ReportingProject string `json:"reportingProject,omitempty"`
}

type ComposeOptions struct {
	// HTTPClient fetches knowledge sources. Nil uses http.DefaultClient.
	HTTPClient *http.Client
	// KnowledgeTimeout, KnowledgeMaxBytesPerSource, KnowledgeMaxSourcesPerService
	// override the Tier-1 defaults when > 0.
	KnowledgeTimeout              time.Duration
	KnowledgeMaxBytesPerSource    int
	KnowledgeMaxSourcesPerService int
	// MCPConnectTimeout overrides [DefaultMCPConnectTimeout] when > 0.
	MCPConnectTimeout time.Duration
	// SkillTimeout and SkillMaxBytes override the skill-body fetch defaults
	// when > 0 (see DefaultSkillTimeout / DefaultSkillMaxBytes).
	SkillTimeout  time.Duration
	SkillMaxBytes int

	// OnToolInvocation, if set, fires once at the start of every provider-tool
	// execution (wired to usage metering by the caller).
	OnToolInvocation func(ProviderToolInvocation)
	// Logger receives composition warnings. Nil discards them.
	Logger *slog.Logger
	// AllowPrivateNetworks disables the SSRF IP guard's private/loopback/
	// link-local block for the knowledge, skill, and MCP fetches. It is the
	// dev/cluster escape hatch: local overlays address services over loopback
	// and in-cluster (private) IPs, which the guard blocks by default. It MUST
	// stay false in production. Default false = guard on (safe).
	AllowPrivateNetworks bool
	// AllowedHosts and AllowedCIDRs, when either is non-empty, switch the SSRF
	// guard from its default "block private" IP-policy into an allow-list posture
	// for UNTRUSTED providers: a capability-document URL (knowledge source, skill
	// source, MCP endpoint) is permitted only if its host matches an AllowedHosts
	// entry or resolves into an AllowedCIDRs range. AllowedHosts entries match a
	// host exactly and as a domain suffix ("example.com" permits "example.com"
	// and "api.example.com"); AllowedCIDRs is the reviewed gateway range(s).
	//
	// The always-blocked set (link-local/IMDS, unspecified, multicast) still
	// holds in allow-list mode — an allow-listed host that resolves to metadata
	// is refused. When both are empty the guard keeps its IP-policy behavior
	// (backward compatible). The integrator populates these from config.
	AllowedHosts []string
	AllowedCIDRs []string
	// Caller is the calling user's own credential, forwarded (with
	// ExpectedProject) only to endpoints in IdentityForwardHosts so a provider
	// can read as the caller instead of holding standing access of its own.
	Caller CallerIdentity
	// IdentityForwardHosts is the OPERATOR-sanctioned set of MCP endpoint hosts
	// that may receive Caller — matched exactly and as a domain suffix. Kept
	// separate from the SSRF allow-list on purpose: that one answers "may we
	// connect at all", this the far narrower "may we hand this endpoint the
	// user's credential". Empty (the default) forwards to nobody. See identity.go.
	IdentityForwardHosts []string
	// ExpectedProject, when set, is the namespace/project of the calling request.
	// It is a defense-in-depth tenant-isolation check on the capability Source:
	// the Source is responsible for returning only the calling project's
	// documents, but any document whose Metadata.Namespace disagrees with
	// ExpectedProject is dropped and logged rather than trusted. Documents that
	// carry no namespace are passed through — for those the Source remains the
	// scoping authority (the CRD projection has no spec-level project field to
	// cross-check; if one is added later, extend ScopeDocuments to verify it).
	ExpectedProject string
	// Memory, when non-nil, enables the memory_remember / memory_forget
	// built-in tools (see internal/capability/memory.go) scoped to
	// ExpectedProject, plus a "Project memory:" addendum section listing the
	// project's current facts. Nil disables the feature entirely — no tools,
	// no addendum section. Also requires ExpectedProject to be set, since the
	// tools need a project to scope reads/writes to.
	Memory memory.Store
	// ContextID, when set, is the conversation this composition is running
	// for. It is threaded into gap reports as provenance only (see
	// GapReports) — it plays no role in tool scoping or tenant isolation.
	ContextID string
	// GapReports, when non-nil, enables one report_capability_gap__<service>
	// tool per composed document that declares spec.reportingProject (see
	// internal/capability/gapreport.go): the model can flag that a provider
	// service is missing a tool or lookup a user needed, and the report is
	// written to that PROVIDER's own project — never ExpectedProject, the
	// consumer's project — so the team that owns the missing capability sees
	// it without the user having to report it themselves. A document with
	// tools but no reportingProject simply gets no gap-report tool. Nil
	// disables the feature entirely.
	GapReports gapreport.Store
	// PlatformAPI, when non-nil, adds the base platform tools (see
	// internal/basetools) to every project's composition: read this project's
	// resources of any kind, describe a kind, list where a service is offered,
	// report what the allowance has left. They are not one provider's
	// contribution, so they are not namespaced under a service and are not
	// allow-listed by a capability document — they are what every project has.
	//
	// They run as the CALLER and only as the caller: the client is bound to
	// Caller.BearerToken and ExpectedProject here, once, and the tools receive
	// a view that carries no other identity. With either missing there is
	// nobody to act as, so nothing is composed. Nil disables the feature.
	PlatformAPI *projectapi.Client
	// PlanTokenKey binds plans for the base tools' change path
	// (resources_validate, resources_plan, resources_apply). Empty leaves the
	// change path out: a service that cannot check a token must not issue one.
	// Ignored when PlatformAPI is nil. See internal/plantoken.
	PlanTokenKey []byte
	// Metrics, when non-nil, records assistant_gap_report_total for every
	// report_capability_gap tool call this composition creates (see
	// internal/metrics). Nil disables recording only — GapReports still
	// governs whether the tool is composed at all.
	Metrics *appmetrics.Metrics
	// contains filtered or unexported fields
}

type Composed struct {
	// SystemPromptAddendum is "" when no document contributed knowledge.
	SystemPromptAddendum string
	// Tools holds the allow-listed provider tools, keyed and named
	// "<server>__<tool>", together with the platform's own built-ins.
	Tools agentcore.ToolSet
	// Mutating names the composed tools on a change path: those a capability
	// document flagged in mcpServers[].mutating, plus the base tools' change
	// path. It answers what this project's assistant can change. Sorted, so
	// two compositions of the same project read alike.
	Mutating []string
	// contains filtered or unexported fields
}

type Condition struct {
	Type    string `json:"type"`
	Status  string `json:"status"`
	Reason  string `json:"reason,omitempty"`
	Message string `json:"message,omitempty"`
}

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

type GVKRef struct {
	Group string `json:"group"`
	Kind  string `json:"kind"`
}

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

type Knowledge struct {
	Sources  []KnowledgeSource  `json:"sources,omitempty"`
	Concepts []KnowledgeConcept `json:"concepts,omitempty"`
}

type KnowledgeConcept struct {
	GVK     GVKRef `json:"gvk"`
	Summary string `json:"summary"`
}

type KnowledgeSource struct {
	Type  KnowledgeSourceType `json:"type"`
	Title string              `json:"title,omitempty"`
	URL   string              `json:"url"`
}

type KnowledgeSourceType string

type MCPServer struct {
	Name         string       `json:"name"`
	Endpoint     string       `json:"endpoint"`
	ToolSelector ToolSelector `json:"toolSelector"`
	Mutating     []string     `json:"mutating,omitempty"`
}

type Metadata struct {
	Name      string `json:"name,omitempty"`
	Namespace string `json:"namespace,omitempty"`
}

type ProviderToolInvocation struct {
	// ServiceName is the reverse-DNS provider service name from the document.
	ServiceName string
	// ServerName is the mcpServers[].name shortname the tool is namespaced under.
	ServerName string
	// ToolName is the original (un-namespaced) provider tool name.
	ToolName string
	// NamespacedToolName is the name the model sees, "<server>__<tool>".
	NamespacedToolName string
}

type Ref struct {
	Name string `json:"name"`
}

type ServiceEntitlement struct {
	// ID is the sanitized serviceRef: the stable identifier a card advertises,
	// run through [SanitizeName] so a provider-supplied name cannot put an
	// arbitrary string in a field consumers treat as an ID.
	ID                string
	ServiceRef        string   // spec.serviceRef.name, verbatim — "streamco"
	ServiceName       string   // spec.serviceName — "streaming.streamco.example"
	ToolNames         []string // namespaced "<server>__<tool>", from ToolSelector.Include ONLY
	MCPEndpoints      []string // spec.tools.mcpServers[].endpoint
	SkillNames        []string // namespaced "<serviceRef>__<skill>"
	SkillDescriptions []string
	KnowledgeTitles   []string // knowledge source titles (or URLs when untitled)
}

type Skill struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Source is the HTTP(S) URL of the skill body (markdown/plain text).
	Source string `json:"source"`
}

type Source interface {
	// Documents returns the capability documents entitling projectName.
	Documents(ctx context.Context, projectName string) ([]CapabilityDocument, error)
}

type Status struct {
	Conditions []Condition `json:"conditions,omitempty"`
}

type ToolSelector struct {
	Include []string `json:"include,omitempty"`
}

type Tools struct {
	MCPServers []MCPServer `json:"mcpServers,omitempty"`
}