package runner

import (
	"context"

	"github.com/tidbcloud/AgentTeam/internal/extension/registry"
)

// CredentialValidator performs one bounded live provider request with the
// submitted credentials (Connect/test flows). It returns a classified runtime
// error; ErrorProviderAuthUnavailable means the provider rejected the
// credential.
type CredentialValidator func(ctx context.Context, credentials Credentials) error

// ConnectionPreparer performs the same bounded live validation as a
// CredentialValidator and may additionally return a small non-secret,
// code-owned config selected from pre-registered runtime paths.
type ConnectionPreparer func(
	ctx context.Context,
	credentials Credentials,
) (ConnectionConfig, error)

// Implementation is the trusted execution facet of one provider Extension:
// what executes Actions, under which revision and connection policy, which
// credential contract the App connection collects, and how credentials are
// live-validated. It is server-only and never enters the registry digest.
type Implementation struct {
	// Executor is the code-registered Builtin executor (required).
	Executor registry.Executor

	// Revision is the stable implementation identity (required, non-empty);
	// the registry folds it into the runtime digest.
	Revision string

	// ConnectionPolicy selects whether the Extension requires an active App
	// connection. Token-authenticated providers use ConnectionRequired;
	// no-auth providers use ConnectionNone.
	ConnectionPolicy registry.ConnectionPolicy

	// Auth declares the credential contract. AuthNone providers leave the
	// zero AuthSpec.
	Auth AuthSpec

	// ValidateCredentials live-checks submitted credentials for Connect and
	// connection test flows (required for authenticated providers).
	ValidateCredentials CredentialValidator

	// PrepareConnection optionally replaces ValidateCredentials in the
	// connection write/test flow when validation must also persist one
	// code-owned, non-secret runtime choice. It must not return discovered
	// endpoint, tool, resource, session, profile, or secret-derived metadata.
	PrepareConnection ConnectionPreparer

	// ConnectionConfig is the startup-validated provider-specific key and
	// value allowlist for PrepareConnection output. The empty contract permits
	// only an empty config.
	ConnectionConfig ConnectionConfigContract

	// CatalogPolicy is an optional provider facet that filters the
	// scope-derived action set against live connection capability state
	// during App catalog projection. Providers whose Actions depend on
	// Connection-local capabilities (for example IMAP feature sets) must
	// register one so the catalog never advertises unsupported actions.
	CatalogPolicy registry.CatalogPolicy
}

// ActionLister is implemented by executors that can enumerate the exact set
// of Action names their dispatch table serves. Bootstrap cross-checks it
// against the Definition catalog so a Definition/executor drift fails startup
// instead of surfacing as a runtime not-found.
type ActionLister interface {
	ActionNames() []string
}