core

type Admission interface {
	// FilterTools returns the subset of tools the identity may call. Mirrors
	// pkg/authz filterToolsByPolicy: a per-tool AuthorizeWithJWTClaims(call) using
	// the tool's annotations; a per-tool authorizer error skips that tool
	// (log-and-continue), it is not a hard failure.
	FilterTools(ctx context.Context, identity *auth.Identity, tools []vmcp.Tool) ([]vmcp.Tool, error)
	// AllowToolCall mirrors pkg/authz authorizeToolCall (MCPFeatureTool/Call),
	// sourcing the tool's annotations for when-clause evaluation.
	AllowToolCall(ctx context.Context, identity *auth.Identity, tool *vmcp.Tool, args map[string]any) (bool, error)
	// FilterResources / AllowResourceRead use MCPFeatureResource/Read.
	FilterResources(ctx context.Context, identity *auth.Identity, resources []vmcp.Resource) ([]vmcp.Resource, error)
	AllowResourceRead(ctx context.Context, identity *auth.Identity, resource *vmcp.Resource) (bool, error)
	// FilterPrompts / AllowPromptGet use MCPFeaturePrompt/Get.
	FilterPrompts(ctx context.Context, identity *auth.Identity, prompts []vmcp.Prompt) ([]vmcp.Prompt, error)
	AllowPromptGet(ctx context.Context, identity *auth.Identity, prompt *vmcp.Prompt) (bool, error)
}

type Config struct {
	// Aggregator discovers and merges backend capabilities into the advertised set.
	Aggregator aggregator.Aggregator

	// Router resolves an advertised capability to its backend target.
	Router router.Router

	// BackendRegistry enumerates the configured backends.
	BackendRegistry vmcp.BackendRegistry

	// BackendClient performs MCP protocol calls against backend servers.
	BackendClient vmcp.BackendClient

	// WorkflowDefs holds the composite-tool workflow definitions, keyed by name.
	WorkflowDefs map[string]*composer.WorkflowDefinition

	// Authz feeds the admission seam New builds. A nil Authz means authorization
	// is unconfigured (allow-all), matching today's `AuthzMiddleware != nil` guard:
	// the composition root only populates this when Cedar policies exist (mirroring
	// newCedarAuthzMiddleware's `len(Policies) > 0` check). When Authz is non-nil,
	// ServerName is REQUIRED (New fails fast with vmcp.ErrInvalidConfig otherwise).
	Authz *authz.Config

	// ServerName is the VirtualMCPServer name used as the Cedar resource entity name
	// in authorization policy evaluation — parity with the serverName threaded into
	// the HTTP authz middleware. It is REQUIRED when Authz is non-nil (New returns
	// vmcp.ErrInvalidConfig on an empty value, since Cedar resource-scoped policies
	// depend on it) and ignored when Authz is nil.
	ServerName string

	// TelemetryProvider is the cross-cutting telemetry provider (also consumed by Serve).
	TelemetryProvider *telemetry.Provider

	// AuditConfig is the cross-cutting audit configuration (also consumed by Serve).
	AuditConfig *audit.Config

	// HealthStatusProvider is the read-only backend health view built at the
	// composition root. Nil means no health filtering (all backends included).
	HealthStatusProvider health.StatusProvider

	// Elicitation sends MCP elicitation requests to the client and blocks for the
	// response. It is the domain-typed seam (vmcp anti-pattern #5: no mcp-go types)
	// consumed by the composer's elicitation handler during composite-tool
	// workflows. The composition root supplies the SDK-backed adapter; the core
	// only forwards it to the workflow engine. May be nil when no configured
	// workflow performs elicitation; New rejects a nil Elicitation when any
	// configured workflow contains an elicitation step.
	Elicitation vmcp.ElicitationRequester
}

type VMCP interface {
	// ListTools returns the tools advertised to identity. The returned
	// [vmcp.Tool] values carry their logical BackendID.
	ListTools(ctx context.Context, identity *auth.Identity) ([]vmcp.Tool, error)

	// CallTool invokes the named tool on behalf of identity.
	//
	// args contains the tool input parameters. meta carries protocol-level
	// metadata (_meta) forwarded from the client; it is retained on this method
	// (rather than dropped) so the core can forward it through
	// [vmcp.BackendClient.CallTool] to the backend MCP server. Both maps are
	// treated as read-only.
	CallTool(ctx context.Context, identity *auth.Identity, name string,
		args map[string]any, meta map[string]any) (*vmcp.ToolCallResult, error)

	// ListResources returns the resources advertised to identity.
	ListResources(ctx context.Context, identity *auth.Identity) ([]vmcp.Resource, error)

	// ReadResource reads the resource at uri on behalf of identity. The
	// returned result's Meta may be nil (see the interface contract).
	ReadResource(ctx context.Context, identity *auth.Identity, uri string) (*vmcp.ResourceReadResult, error)

	// ListPrompts returns the prompts advertised to identity.
	ListPrompts(ctx context.Context, identity *auth.Identity) ([]vmcp.Prompt, error)

	// GetPrompt retrieves the named prompt on behalf of identity.
	//
	// args contains the prompt input parameters and is treated as read-only.
	// Unlike CallTool there is no meta parameter: prompts/get carries no client
	// _meta to forward.
	GetPrompt(ctx context.Context, identity *auth.Identity, name string,
		args map[string]any) (*vmcp.PromptGetResult, error)

	// LookupTool resolves an advertised tool name to its capability (incl.
	// BackendID) WITHOUT invoking it. Returns an error for an unknown or
	// unadvertised name — the validation seam for the call path. Lookups apply
	// the same admission filter as ListTools, so they never resolve a denied
	// capability.
	LookupTool(ctx context.Context, identity *auth.Identity, name string) (*vmcp.Tool, error)

	// LookupResource resolves an advertised resource URI to its capability
	// (incl. BackendID) WITHOUT reading it. Returns an error for an unknown or
	// unadvertised URI. Applies the same admission filter as ListResources.
	LookupResource(ctx context.Context, identity *auth.Identity, uri string) (*vmcp.Resource, error)

	// LookupPrompt resolves an advertised prompt name to its capability (incl.
	// BackendID) WITHOUT retrieving it. Returns an error for an unknown or
	// unadvertised name. Applies the same admission filter as ListPrompts.
	LookupPrompt(ctx context.Context, identity *auth.Identity, name string) (*vmcp.Prompt, error)

	// Close releases core-held resources (backend connections, etc.).
	// Implementations must be idempotent: calling Close multiple times returns nil.
	Close() error
}