mcpbroker

type AttachOutcome ¶

type AttachOutcome string

AttachOutcome is the closed result vocabulary for AttachSession.

const (
	// AttachCreated means the logical broker session was created.
	AttachCreated AttachOutcome = "created"
	// AttachReattached means an attachment was opened to existing logical state.
	AttachReattached AttachOutcome = "reattached"
)

type Attachment ¶

type Attachment interface {
	// Commit publishes a newly created logical session after its host session is
	// durable. It is idempotent. On a reattached handle it is a no-op. The
	// implementation keeps any creation token private so remote brokers can provide
	// the same transaction without exposing storage generations or CAS values.
	Commit(context.Context) error
	// Abort abandons this attachment's uncommitted creation and closes the local
	// handle. It may delete logical state only while that creation is still private;
	// once another attachment has observed the session, Abort must preserve that
	// peer and degrade to local close. It is idempotent.
	Abort(context.Context) error
	// Binding is the opaque identity of this exact logical-session incarnation.
	// It is persisted by the host and must match exactly on reattachment.
	Binding() session.ExternalBinding
	// Tools returns independently owned wrappers bound to this attachment.
	Tools() []tool.Tool
	// RefreshGrantedAuthorizationCatalogue atomically replaces static protected
	// declarations with authenticated metadata after the exact bundle grant. A
	// valid non-bundle grant returns the unchanged catalogue. The returned snapshot
	// is independently owned for the host's model-visible catalog.
	RefreshGrantedAuthorizationCatalogue(context.Context, session.ExternalAuthorization) ([]tool.Tool, error)
	// PresentAuthorization returns the live presentation URL for the exact
	// authorization. The URL is deliberately an ephemeral return value: it is not
	// part of ExternalAuthorization or any broker reference intended for storage.
	PresentAuthorization(context.Context, session.ExternalAuthorization) (string, error)
	// AuthorizationStatus queries the exact authorization and remains available
	// after closing an old attachment and reattaching to the logical session.
	AuthorizationStatus(context.Context, session.ExternalAuthorization) (session.AuthorizationStatus, error)
	// CancelAuthorization precisely cancels the exact authorization reference.
	CancelAuthorization(context.Context, session.ExternalAuthorization) (CancelOutcome, error)
	// Close releases only this local attachment and is idempotent. It never
	// deletes logical broker state.
	Close(context.Context) (CloseOutcome, error)
}

Attachment is a process-local handle to one logical broker session.

Authorization operations take session.ExternalAuthorization so callers reuse the aggregate's existing value instead of a second broker DTO. Identity is the stable authorization ID plus opaque AuthorizationBinding; ExpiresAt is freshness metadata and must not participate in lookup equality. Implementations must not infer a transaction from only the session or authorization ID.

type Availability ¶ added in v0.0.34

type Availability string

Availability is the closed vocabulary for ConnectorInventory.Availability.

const (
	// AvailabilityAvailable means the broker reached the connector inventory.
	AvailabilityAvailable Availability = "available"
	// AvailabilityUnavailable means the broker could not reach the connector inventory.
	AvailabilityUnavailable Availability = "unavailable"
)

type CancelOutcome ¶

type CancelOutcome string

CancelOutcome is the closed, idempotent result vocabulary for cancellation.

const (
	// CancelCancelled means this call cancelled the pending authorization.
	CancelCancelled CancelOutcome = "cancelled"
	// CancelAlreadyCancelled means that exact authorization was already cancelled.
	CancelAlreadyCancelled CancelOutcome = "already_cancelled"
	// CancelAlreadyResolved means that exact authorization had another terminal
	// status. AuthorizationStatus reports which one.
	CancelAlreadyResolved CancelOutcome = "already_resolved"
)

type CatalogueState ¶ added in v0.0.34

type CatalogueState string

CatalogueState is the closed vocabulary for ConnectorStatus.CatalogueState. A zero ToolCount with CatalogueStateUnknown is missing information, not proof of an empty catalogue.

const (
	// CatalogueHidden means the connector's tools are not published.
	CatalogueHidden CatalogueState = "hidden"
	// CatalogueDeclared means the connector is declared but not yet discovered.
	CatalogueDeclared CatalogueState = "declared"
	// CatalogueDiscovered means the connector's tools were discovered and published.
	CatalogueDiscovered CatalogueState = "discovered"
	// CatalogueUnknown means the catalogue state could not be determined.
	CatalogueUnknown CatalogueState = "unknown"
)

type CloseOutcome ¶

type CloseOutcome string

CloseOutcome is the closed, idempotent result vocabulary for Attachment.Close.

const (
	// CloseClosed means this call released the local attachment.
	CloseClosed CloseOutcome = "closed"
	// CloseAlreadyClosed means the attachment had already been released.
	CloseAlreadyClosed CloseOutcome = "already_closed"
)

type ConnectorInspector ¶ added in v0.0.34

type ConnectorInspector interface {
	InspectConnectors(context.Context, session.SessionID, session.ExternalBinding) (ConnectorInventory, error)
}

ConnectorInspector is optional, read-only inspection of an existing exact broker incarnation. The caller must authorize the session owner first. It never attaches, enrolls, refreshes credentials, or performs discovery.

type ConnectorInventory ¶ added in v0.0.34

type ConnectorInventory struct {
	Availability    Availability
	EnrollmentState EnrollmentState
	Connectors      []ConnectorStatus
	TotalConnectors uint32
	Truncated       bool
}

ConnectorInventory describes broker-local catalogue publication, not session installation, persistence, prompt readiness, authorization validity, or health.

type ConnectorStatus ¶ added in v0.0.34

type ConnectorStatus struct {
	Name           string
	CatalogueState CatalogueState
	ToolCount      uint32
}

ConnectorStatus contains only a bounded display name and published tool count.

type DeleteOutcome ¶

type DeleteOutcome string

DeleteOutcome is the closed, idempotent result vocabulary for DeleteSession.

const (
	// DeleteDeleted means logical broker state existed and was deleted.
	DeleteDeleted DeleteOutcome = "deleted"
	// DeleteNotFound means no logical broker state existed; the requested end
	// state is already satisfied.
	DeleteNotFound DeleteOutcome = "not_found"
)

type EnrollmentState ¶ added in v0.0.34

type EnrollmentState string

EnrollmentState is the closed vocabulary for ConnectorInventory.EnrollmentState.

const (
	// EnrollmentNotRequired means the connector needs no enrollment step.
	EnrollmentNotRequired EnrollmentState = "not_required"
	// EnrollmentNotStarted means enrollment is required but has not begun.
	EnrollmentNotStarted EnrollmentState = "not_started"
	// EnrollmentPending means enrollment has started but not completed.
	EnrollmentPending EnrollmentState = "pending"
	// EnrollmentCompleted means enrollment has finished successfully.
	EnrollmentCompleted EnrollmentState = "completed"
	// EnrollmentUnknown means enrollment status could not be determined.
	EnrollmentUnknown EnrollmentState = "unknown"
)

type Service ¶

type Service interface {
	AttachSession(context.Context, session.SessionID) (Attachment, AttachOutcome, error)
	// DeleteSession durably invalidates every attachment to the deleted logical
	// session incarnation. A later AttachSession with the same SessionID creates a
	// new incarnation; stale attachments must return ErrStateUnavailable. Any
	// generation or fencing mechanism used to enforce this remains implementation-private.
	DeleteSession(context.Context, session.SessionID) (DeleteOutcome, error)
}

Service attaches consumers to broker state keyed by the stable mecatl session identity. AttachSession does not transfer ownership: multiple process-local attachments may refer to the same logical state. DeleteSession, unlike Close, durably and idempotently destroys that logical state.

type WorkspaceCatalogue ¶

type WorkspaceCatalogue interface {
	Valid() bool
	Ref() WorkspaceEnrollmentRef
	Tools() []tool.Tool
	ToolNames() []string
	// contains filtered or unexported methods
}

WorkspaceCatalogue is an immutable snapshot of the complete frozen tool catalogue proven by one exact enrollment. Construct it with NewWorkspaceCatalogue; its accessors return defensive copies. The private marker seals construction to this package.

func NewWorkspaceCatalogue(ref WorkspaceEnrollmentRef, tools []tool.Tool) (WorkspaceCatalogue, error)

type WorkspaceEnrollmentAttachment ¶

type WorkspaceEnrollmentAttachment interface {
	BeginWorkspaceEnrollment(context.Context) (WorkspaceEnrollmentPresentation, error)
	ObserveWorkspaceEnrollment(context.Context, WorkspaceEnrollmentRef) (WorkspaceEnrollmentResult, error)
	CancelWorkspaceEnrollment(context.Context, WorkspaceEnrollmentRef) (WorkspaceEnrollmentResult, error)
}

WorkspaceEnrollmentAttachment is the optional enrollment capability of an Attachment. Callers may begin, observe, or cancel broker-owned state, but can never submit status, discovered definitions, authority, or success.

type WorkspaceEnrollmentPresentation ¶

type WorkspaceEnrollmentPresentation struct {
	Ref WorkspaceEnrollmentRef
	URL string
}

WorkspaceEnrollmentPresentation is the ephemeral browser presentation for an enrollment. URL deliberately exists only on this non-durable value.

func (p WorkspaceEnrollmentPresentation) Valid() bool

type WorkspaceEnrollmentRef ¶

type WorkspaceEnrollmentRef struct {
	ID               session.WorkspaceEnrollmentID
	RequiredServices uint32
	ExpiresAt        time.Time
}

WorkspaceEnrollmentRef is the durable, presentation-safe correlation for one broker-owned enrollment. It contains no URL, credential, backend selection, or discovered definition.

func (r WorkspaceEnrollmentRef) Valid() bool

type WorkspaceEnrollmentResult ¶

type WorkspaceEnrollmentResult struct {
	Ref       WorkspaceEnrollmentRef
	Status    WorkspaceEnrollmentStatus
	Catalogue WorkspaceCatalogue
}

WorkspaceEnrollmentResult is a broker-authored observation. A connected result proves one complete frozen catalogue; every other state forbids one.

func (r WorkspaceEnrollmentResult) Valid() bool

type WorkspaceEnrollmentStatus ¶

type WorkspaceEnrollmentStatus string

WorkspaceEnrollmentStatus is the closed broker-authored state of one pre-prompt workspace enrollment.

const (
	WorkspaceEnrollmentPending   WorkspaceEnrollmentStatus = "pending"
	WorkspaceEnrollmentConnected WorkspaceEnrollmentStatus = "connected"
	WorkspaceEnrollmentDenied    WorkspaceEnrollmentStatus = "denied"
	WorkspaceEnrollmentCancelled WorkspaceEnrollmentStatus = "cancelled"
	WorkspaceEnrollmentExpired   WorkspaceEnrollmentStatus = "expired"
	WorkspaceEnrollmentFailed    WorkspaceEnrollmentStatus = "failed"
)

func (s WorkspaceEnrollmentStatus) Valid() bool