mcpharness

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

type Binding struct {
	// Name is the binding's stable identity within the Session. It must satisfy
	// client.Name.
	Name string
	// Server is the secret-free MCP connection configuration.
	Server client.Definition
	// Scope names the connection's owner. Required.
	Scope Scope
	// Loop is the owning Loop, for ScopeLoop only. Harness has no loop.ID named
	// type — Loop identity is a bare uuid.UUID throughout (identity.Coordinates,
	// tool.Bindings.LoopID) — so this mirrors it rather than inventing an alias
	// Harness would not recognize.
	Loop uuid.UUID
	// Visibility decides which Loops may consume a ScopeSession binding. It is
	// unused for ScopeLoop, whose audience is its owner and nobody else.
	Visibility LoopSelector
	// Required states whether the owner may come up without this binding. A
	// required binding must be ready before its owner is; an optional one that
	// fails leaves its owner usable and marks only itself failed (design
	// §Required and optional servers).
	Required bool
}

type BindingFailure struct {
	// Binding names the binding that failed.
	Binding string
	// Class classifies the failure.
	Class client.FailureClass
	// Message is the failure's bounded, normalized text.
	Message string
}

type BindingIdentity struct {
	// Name is the binding's stable name within the Session.
	Name string
	// Scope names the connection's owner.
	Scope Scope
	// Loop is the owning Loop for a loop-scoped binding, zero otherwise. It is
	// the "owner identity" half of the design's "Loop selector identity (or
	// owner identity)".
	Loop uuid.UUID
	// SelectorDigest is the hex digest of a session-scoped binding's Visibility:
	// which Loops may consume it. It is empty for a loop-scoped binding, which
	// has no selector — its audience is its owner, which Loop names.
	//
	// It is a digest rather than the membership list because the list is
	// unbounded and, for a Named selector, is application vocabulary that has no
	// business in a journal. What a restore needs is whether the audience
	// changed, and equality answers that.
	SelectorDigest string
	// TransportKind names the transport, e.g. "stdio".
	TransportKind string
	// RedactedOrigin is the transport's display origin. It is redacted at the
	// source: TransportFactory.RedactedOrigin's contract is that it never
	// contains credentials, and this field is that value verbatim.
	RedactedOrigin string
	// Required reports the binding's startup posture. It is identity because it
	// is a behavior contract: the same servers with one flipped from optional to
	// required is a Session that now refuses to start.
	Required bool

	// CapabilityDigest is the hex digest of the client capabilities this binding
	// advertises to its server.
	CapabilityDigest string
	// FilterDigest is the hex digest of the binding's ToolFilter.
	FilterDigest string
	// LimitsDigest is the hex digest of the binding's declared timeouts and
	// limits.
	LimitsDigest string
	// CompatDigest is the hex digest of the binding's compatibility profile —
	// client.Profile.Digest, the checkable form of Status.CompatProfile's label.
	CompatDigest string

	// Server is what the server claimed to be at initialize. Zero before a
	// handshake. Cosmetic in the protocol's terms — it names a peer, it never
	// authorizes one — but a change to it is still a change worth reporting.
	Server client.ServerIdentity
	// ProtocolVersion is the version negotiated at initialize. Empty before the
	// handshake.
	ProtocolVersion string
	// CatalogGeneration is the ordinal of the adopted catalog, 0 before one is
	// adopted.
	//
	// It is reported but NOT digested: a generation number is an ordinal, not
	// content. Two runs that discover the same catalog after a different number
	// of refreshes have the same configuration, and digesting the ordinal would
	// report drift on every reconnect. CatalogDigest is the content.
	CatalogGeneration uint64
	// CatalogDigest is the hex digest of the adopted catalog — the server's
	// whole offering, independent of this host's filter. Empty before one is
	// adopted.
	CatalogDigest string
	// Tools are the tools this binding actually exposes: the catalog projected
	// through the ToolFilter, in the catalog's stable order.
	//
	// Filtered, where CatalogDigest is not, and the pair is the point. The
	// catalog digest says what the server offers; these say what this binding
	// made of it. A filter change moves these and not the catalog digest, which
	// is exactly the distinction a drift report wants to draw.
	Tools []ToolIdentity

	// Digest is the hex digest of every other field of this identity: the
	// binding's whole secret-free identity in one comparable value.
	Digest string
}

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

type BindingStatus struct {
	// Name is the binding name.
	Name string
	// Scope names the connection's owner.
	Scope Scope
	// Loop is the owning Loop for a loop-scoped binding, zero otherwise.
	Loop uuid.UUID
	// Required reports the binding's startup posture.
	Required bool
	// Enabled is false for a binding an operator disabled.
	Enabled bool
	// Retiring reports that the binding is out of future generations and is
	// serving only the turns that still hold it.
	Retiring bool
	// Client is the connection's status, already redacted and bounded. It is
	// the zero value with State StateConfigured before a connection exists.
	Client client.Status
}

type Clock interface {
	Now() time.Time
}

type Deps struct {
	// SessionID identifies the Session these bindings belong to. It is the
	// coordinate every event.IntegrationStatus is stamped with, and an event
	// carrying the wrong Session's ID — or none — is one that either reaches the
	// wrong subscribers or is refused as invalid. The Manager cannot derive it:
	// it is deliberately given a GateOpener and an EventPublisher rather than a
	// Session (see this file's header), so nothing it holds knows the answer.
	//
	// It is OPTIONAL, and the zero value is a supported way to build a Manager
	// rather than a mistake: an application that contributes its MCP identity to
	// the Session's config fingerprint must discover its servers BEFORE the
	// Session exists, so there is no ID to give yet. Such an application leaves
	// this zero and calls BindSession once rig.NewSession has minted one. See
	// attach.go, which owns that ordering and is the only reason this field is
	// optional.
	//
	// Supplying it here is still the right thing for an application that does not
	// contribute a fingerprint: the Manager is attached from birth and never has
	// a window in which a status has nowhere to go.
	SessionID uuid.UUID
	// Gates routes elicitation to a human. Required: a binding that advertises
	// the elicitation capability with nowhere to ask would be a lie told to a
	// server.
	Gates GateOpener
	// Events receives integration events. Required: a binding whose failures
	// nobody can observe is one an operator cannot fix.
	Events EventPublisher
	// Sampling services servers' requests for LLM completions, under the
	// application's own policy. Optional, and its absence is the default: this
	// module never spends a host's model budget because it was composed, only
	// because it was asked to.
	//
	// # Nil means the capability is not advertised, and that is not a downgrade
	//
	// A nil here yields a nil client.Handlers.Sampling for every binding (see
	// Manager.samplingHandler). That is the whole of the fail-closed rule, and it
	// is deliberately NOT a rule this file enforces a second time:
	// client.Handlers.advertised already owns it, and owns it for elicitation and
	// roots identically — a capability the Definition requests with no handler to
	// serve it is a FailureInvalidConfig, never a silent downgrade. So a Binding
	// whose Server.Capabilities.Sampling is true with no policy installed fails to
	// connect, before its transport is ever dialed, with the same classified error
	// an application would get from pkg/client directly. A required binding takes
	// its owner's startup down with it; an optional one fails as a whole, serving
	// nothing — never a binding that quietly comes up with its tools and without
	// the capability it advertised.
	//
	// Re-deriving that check here would be a second opinion on a decision one
	// package already makes: two places to keep in step, and the wrong one wins
	// whenever they disagree.
	//
	// # Why this is not a field on Binding
	//
	// Sampling authority IS per-binding, and it already lands there: a binding
	// advertises the capability only if its own Server.Capabilities.Sampling says
	// so, and SampleRequest.Binding names the asker, so one policy decides per
	// server. What a Binding must not hold is the policy VALUE. A Binding is
	// immutable configuration that gets digested into the Session's configuration
	// identity (see identity.go), and an interface has no stable encoding to
	// digest — it would either be excluded, making the digest lie about what a
	// binding may spend, or included, making a restore report drift because the
	// host allocated a new policy. Deps is where host capabilities live, for
	// exactly this reason: Gates is not a Binding field either.
	Sampling SamplingPolicy
	// Reporter receives the adapter's own notices — the facts the sealed
	// Harness event set cannot express. Optional; nil drops them.
	Reporter Reporter
	// Clock is the time source. Nil selects the system clock.
	Clock Clock
}

type DuplicateModelNameError struct {
	// ModelName is the contested model-facing name.
	ModelName string
	// Binding is the binding whose tool was rejected.
	Binding string
	// OtherBinding is the binding that already holds the name. It equals
	// Binding when one binding offered the name twice, which a catalog should
	// have prevented; the table still refuses it.
	OtherBinding string
}

type EventPublisher interface {
	PublishEvent(ctx context.Context, ev event.Event) error
}

type EventSource interface {
	SubscribeEvents(event.EventFilter) (event.Subscription, error)
}

type GateOpener interface {
	OpenGate(ctx context.Context, req GateRequest) (GateResponse, error)
}

type GateRequest struct {
	// Kind is the gate scenario: gate.KindForm or gate.KindOpenURL.
	Kind gate.Kind
	// Payload is the authoritative request. It is a sealed gate.Payload, so a
	// host cannot be handed a shape the gate codec would reject.
	Payload gate.Payload
	// Prompt is the presentation projection an opener renders.
	Prompt gate.Prompt
	// Restorable states whether the gate may survive a restore boundary. An
	// open-url gate must never be restorable — its action target is
	// deliberately not journaled, so a restored gate could only ever be a
	// broken one, and gate.ValidateGate rejects it (see gate.OpenURLPayload).
	Restorable bool
	// Binding names the MCP binding that asked, for attribution.
	Binding string
	// LoopID is the Loop the request is on behalf of, or zero for a
	// Session-scoped binding's own startup — an elicitation raised during
	// initialization belongs to no Loop yet.
	LoopID uuid.UUID
}

type GateResponse struct {
	Action string
	Values map[string]string
}

type LoopControllers interface {
	LoopController(uuid.UUID) (loop.Controller, bool)
}

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

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

type Notice struct {
	// Kind classifies the notice.
	Kind NoticeKind
	// Binding names the binding concerned.
	Binding string
	// LoopID is the Loop concerned, or zero when the notice is not about one.
	LoopID uuid.UUID
	// Generation is the catalog generation concerned, or 0.
	Generation uint64
	// Message is bounded, redacted explanatory text.
	Message string
}

type NoticeKind uint8

type Reporter interface {
	Report(Notice)
}

type SampleMessage struct {
	// Role is who the server says authored this message. It is always a
	// declared role.
	Role SampleRole
	// Text is the message body, bounded by the binding's Limits.
	Text string
}

type SampleRequest struct {
	// Binding names the server that asked. It is the whole of "which authority
	// is this": a policy that trusts one server to spend and not another
	// switches on this.
	Binding string
	// LoopID is the Loop the request is on behalf of, or zero for a
	// Session-scoped binding.
	//
	// The zero is not a gap, for the reason GateRequest.LoopID gives: a
	// Session's server is shared, and a sampling request it raises belongs to the
	// Session rather than to whichever Loop happened to be calling. A policy that
	// budgets per Loop must therefore treat the zero as "the Session's own
	// budget" rather than as an unattributed request to be waved through.
	LoopID uuid.UUID
	// SystemPrompt is the system prompt the server asked for, bounded. It is a
	// request, not a fact: a policy is free to replace or ignore it.
	SystemPrompt string
	// Messages is the conversation the server wants completed. Never empty:
	// pkg/client refuses a sampling request with no messages before it reaches
	// here.
	Messages []SampleMessage
	// MaxTokens is the completion budget, already capped against the binding's
	// Limits.MaxSamplingTokens. A server may lower this ceiling and never raise
	// it, so it is an upper bound the policy may spend within — not a number to
	// honor.
	MaxTokens int
}

type SampleResult struct {
	// Model names the model the policy actually ran, which need not be one the
	// server asked for. It is required: pkg/client refuses a result without one,
	// because a completion nobody can attribute to a model is not auditable.
	Model string
	// Text is the completion.
	Text string
	// StopReason is why generation stopped.
	StopReason string
}

type SampleRole uint8

type SamplingPolicy interface {
	Sample(ctx context.Context, req SampleRequest) (SampleResult, error)
}

type Scope uint8

type StartupError struct {
	Failures []BindingFailure
}

type ToolIdentity struct {
	// RawName is the server's own name for the tool.
	RawName string
	// ModelName is the sanitized, binding-qualified name a model sees. It is
	// separate identity from RawName because the mapping is this host's, not the
	// server's: two hosts can see the same raw tool under different model names,
	// and a model name changing under a stable raw name is a change to what the
	// model was shown.
	ModelName string
	// InputSchemaDigest is the hex digest of the tool's input schema.
	InputSchemaDigest string
	// OutputSchemaDigest is the hex digest of the tool's output schema, empty
	// when the tool has none.
	OutputSchemaDigest string
}