bridges

package
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 26, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Overview

Package bridges defines the daemon-owned bridge domain models shared by persistence, runtime, and transport layers.

Index

Constants

View Source 
const (
	// DeliveryEventTypeStart starts one progressive outbound delivery for a prompt turn.
	DeliveryEventTypeStart = "start"
	// DeliveryEventTypeDelta updates one progressive outbound delivery with newer full text.
	DeliveryEventTypeDelta = "delta"
	// DeliveryEventTypeFinal reports the terminal successful state for one delivery.
	DeliveryEventTypeFinal = "final"
	// DeliveryEventTypeError reports the terminal failed state for one delivery.
	DeliveryEventTypeError = "error"
	// DeliveryEventTypeResume rehydrates the latest delivery snapshot after adapter recovery.
	DeliveryEventTypeResume = "resume"
	// DeliveryEventTypeDelete removes one previously delivered message.
	DeliveryEventTypeDelete = "delete"
)
View Source 
const (
	// BridgeTaskSubscriptionConsumerPrefix namespaces bridge task-delivery cursors.
	BridgeTaskSubscriptionConsumerPrefix = "bridge_task_subscription:"
	// BridgeTaskNotificationStream is the durable task event stream consumed by subscriptions.
	BridgeTaskNotificationStream = "task_events"
)
View Source 
const (
	// BridgeInstanceResourceKind is the canonical desired-state kind for bridge instances.
	BridgeInstanceResourceKind resources.ResourceKind = "bridge.instance"
)

Variables

View Source 
var (
	// ErrDeliveryNotFound reports that no active or retained delivery matched the lookup.
	ErrDeliveryNotFound = errors.New("bridges: delivery not found")
	// ErrDeliveryQueueSaturated reports that a bounded delivery queue could not accept more work.
	ErrDeliveryQueueSaturated = errors.New("bridges: delivery queue saturated")
	// ErrDeliveryIDConflict reports that a caller-supplied delivery id is already active.
	ErrDeliveryIDConflict = errors.New("bridges: delivery id conflict")
	// ErrDeliveryTransportUnavailable reports that the broker has no usable extension delivery transport.
	ErrDeliveryTransportUnavailable = errors.New("bridges: delivery transport unavailable")
)
View Source 
var (
	// ErrBridgeTaskSubscriptionNotFound reports that no bridge task subscription matched the lookup.
	ErrBridgeTaskSubscriptionNotFound = errors.New("bridges: bridge task subscription not found")
	// ErrInvalidBridgeTaskSubscription reports malformed bridge task subscription data.
	ErrInvalidBridgeTaskSubscription = errors.New("bridges: invalid bridge task subscription")
)
View Source 
var (
	// ErrBridgeInstanceNotFound reports that no persisted bridge instance matched the lookup.
	ErrBridgeInstanceNotFound = errors.New("bridges: bridge instance not found")
	// ErrBridgeTargetDirectoryUnavailable reports that the daemon has no target-directory persistence surface.
	ErrBridgeTargetDirectoryUnavailable = errors.New("bridges: bridge target directory unavailable")
	// ErrBridgeTargetUnknown reports that no persisted bridge target matched the lookup.
	ErrBridgeTargetUnknown = errors.New("bridges: bridge target unknown")
	// ErrBridgeTargetAmbiguous reports that a friendly bridge target lookup matched multiple candidates.
	ErrBridgeTargetAmbiguous = errors.New("bridges: bridge target ambiguous")
	// ErrInvalidBridgeTarget reports malformed target-directory input.
	ErrInvalidBridgeTarget = errors.New("bridges: invalid bridge target")
	// ErrBridgeInstanceUnavailable reports that the instance exists but cannot currently accept routing work.
	ErrBridgeInstanceUnavailable = errors.New("bridges: bridge instance unavailable")
	// ErrInvalidBridgeSecretBinding reports that a bridge secret binding payload
	// is malformed or unsupported by the active daemon secret backend.
	ErrInvalidBridgeSecretBinding = errors.New("bridges: invalid bridge secret binding")
	// ErrBridgeSecretBindingNotFound reports that no persisted secret binding matched the lookup.
	ErrBridgeSecretBindingNotFound = errors.New("bridges: bridge secret binding not found")
	// ErrBridgeRouteNotFound reports that no persisted route matched the lookup.
	ErrBridgeRouteNotFound = errors.New("bridges: bridge route not found")
	// ErrIngestDedupRecordNotFound reports that no active ingest dedup record matched the lookup.
	ErrIngestDedupRecordNotFound = errors.New("bridges: ingest dedup record not found")
	// ErrInvalidBridgeStateTransition reports that the requested instance lifecycle transition is not allowed.
	ErrInvalidBridgeStateTransition = errors.New("bridges: invalid bridge state transition")
	// ErrBridgeInstanceReadOnly reports that a managed bridge instance does not
	// allow direct spec mutation through the generic CRUD surface.
	ErrBridgeInstanceReadOnly = errors.New("bridges: bridge instance is managed and read-only")
	// ErrBridgeNotificationSuppressed reports an intentional per-instance
	// notification drop that should still advance notification cursors.
	ErrBridgeNotificationSuppressed = errors.New("bridges: bridge notification suppressed")
)
View Source 
var ErrTerminalTaskNotificationMismatch = errors.New("bridges: terminal task notification state mismatch")

ErrTerminalTaskNotificationMismatch reports a replayed terminal task event that claims finality but no longer agrees with the durable task/run state.

Functions

func ApplyResourceState 

func ApplyResourceState(ctx context.Context, store ResourceProjectionStore, plan resources.ProjectionPlan) error

ApplyResourceState atomically swaps the daemon-visible bridge desired runtime state.

func NewBridgeInstanceResourceCodec 

func NewBridgeInstanceResourceCodec(
	providerLookup BridgeProviderLookup,
) (resources.KindCodec[BridgeInstanceSpec], error)

NewBridgeInstanceResourceCodec builds the typed codec for bridge.instance records.

func NormalizeBridgeTargetName 

func NormalizeBridgeTargetName(value string) string

NormalizeBridgeTargetName canonicalizes display-name hints for lookup.

func NormalizeBridgeTargetQualifier 

func NormalizeBridgeTargetQualifier(value string) string

NormalizeBridgeTargetQualifier canonicalizes workspace/guild qualifiers for lookup.

func NormalizeDeliveryDefaultsJSON 

func NormalizeDeliveryDefaultsJSON(raw json.RawMessage) (json.RawMessage, error)

NormalizeDeliveryDefaultsJSON validates and canonicalizes bridge delivery default JSON.

func ResourceScopeForBridge 

func ResourceScopeForBridge(scope Scope, workspaceID string) resources.ResourceScope

ResourceScopeForBridge converts bridge scope fields into the shared resource scope.

func ValidateInstanceStateTransition 

func ValidateInstanceStateTransition(current BridgeInstance, nextEnabled bool, nextStatus BridgeStatus) error

ValidateInstanceStateTransition reports whether the next enabled/status pair is a valid lifecycle transition from the current instance state.

func ValidateScopeWorkspaceID 

func ValidateScopeWorkspaceID(scope Scope, workspaceID string) error

ValidateScopeWorkspaceID enforces the canonical scope and workspace invariant.

Types

type BridgeDMPolicy 

type BridgeDMPolicy string

BridgeDMPolicy controls how direct messages from unpaired senders are handled. 

const (
	// BridgeDMPolicyOpen accepts direct messages from any sender.
	BridgeDMPolicyOpen BridgeDMPolicy = "open"
	// BridgeDMPolicyAllowlist accepts direct messages only from approved senders.
	BridgeDMPolicyAllowlist BridgeDMPolicy = "allowlist"
	// BridgeDMPolicyPairing requires an explicit pairing flow before accepting direct messages.
	BridgeDMPolicyPairing BridgeDMPolicy = "pairing"
)

func (BridgeDMPolicy) Normalize 

func (p BridgeDMPolicy) Normalize() BridgeDMPolicy

Normalize returns the normalized representation of the DM policy.

func (BridgeDMPolicy) Validate 

func (p BridgeDMPolicy) Validate() error

Validate reports whether the DM policy belongs to the supported bridge v1 set.

type BridgeDegradation 

type BridgeDegradation struct {
	Reason  BridgeDegradationReason `toml:"reason"            json:"reason"`
	Message string                  `toml:"message,omitempty" json:"message,omitempty"`
}

BridgeDegradation captures the structured degradation metadata persisted for a bridge instance.

func (BridgeDegradation) IsZero 

func (d BridgeDegradation) IsZero() bool

IsZero reports whether the degradation payload carries any values.

func (BridgeDegradation) Validate 

func (d BridgeDegradation) Validate() error

Validate reports whether the degradation payload is internally consistent.

type BridgeDegradationReason 

type BridgeDegradationReason string

BridgeDegradationReason reports the structured operational cause for a degraded bridge instance. 

const (
	BridgeDegradationReasonAuthFailed          BridgeDegradationReason = "auth_failed"
	BridgeDegradationReasonRateLimited         BridgeDegradationReason = "rate_limited"
	BridgeDegradationReasonWebhookInvalid      BridgeDegradationReason = "webhook_invalid"
	BridgeDegradationReasonProviderTimeout     BridgeDegradationReason = "provider_timeout"
	BridgeDegradationReasonTenantConfigInvalid BridgeDegradationReason = "tenant_config_invalid"
)

func (BridgeDegradationReason) Normalize 

func (r BridgeDegradationReason) Normalize() BridgeDegradationReason

Normalize returns the normalized representation of the degradation reason.

func (BridgeDegradationReason) Validate 

func (r BridgeDegradationReason) Validate() error

Validate reports whether the degradation reason belongs to the supported bridge v1 set.

type BridgeDeliveryMetrics 

type BridgeDeliveryMetrics struct {
	BridgeInstanceID        string         `json:"bridge_instance_id"`
	DeliveryBacklog         int            `json:"delivery_backlog"`
	DeliveryDroppedTotal    int            `json:"delivery_dropped_total"`
	DeliveryDroppedByReason map[string]int `json:"delivery_dropped_by_reason,omitempty"`
	DeliveryFailuresTotal   int            `json:"delivery_failures_total"`
	LastError               string         `json:"last_error,omitempty"`
	LastErrorAt             time.Time      `json:"last_error_at"`
	LastSuccessAt           time.Time      `json:"last_success_at"`
}

BridgeDeliveryMetrics captures the per-instance delivery telemetry exposed by the broker for observability surfaces.

type BridgeDiagnostic 

type BridgeDiagnostic struct {
	Kind              BridgeDiagnosticKind     `json:"kind"`
	Severity          BridgeDiagnosticSeverity `json:"severity"`
	Source            string                   `json:"source"`
	Message           string                   `json:"message"`
	NextAction        string                   `json:"next_action,omitempty"`
	BridgeInstanceID  string                   `json:"bridge_instance_id,omitempty"`
	SecretSlot        string                   `json:"secret_slot,omitempty"`
	Status            BridgeStatus             `json:"status,omitempty"`
	DegradationReason BridgeDegradationReason  `json:"degradation_reason,omitempty"`
}

BridgeDiagnostic exposes a bridge management diagnostic derived from canonical bridge route, provider, secret, status, degradation, and delivery telemetry.

func BuildBridgeDiagnostics 

func BuildBridgeDiagnostics(input BridgeDiagnosticsInput) []BridgeDiagnostic

BuildBridgeDiagnostics derives actionable bridge diagnostics from existing canonical bridge facts.

type BridgeDiagnosticKind 

type BridgeDiagnosticKind string

BridgeDiagnosticKind identifies one operator-actionable bridge diagnostic. 

const (
	// BridgeDiagnosticKindUnknownDestination reports that no route/default target
	// can identify where outbound delivery should go.
	BridgeDiagnosticKindUnknownDestination BridgeDiagnosticKind = "unknown_destination"
	// BridgeDiagnosticKindMissingToken reports a required provider secret slot that
	// has no persisted binding.
	BridgeDiagnosticKindMissingToken BridgeDiagnosticKind = "missing_token"
	// BridgeDiagnosticKindPermissionDenied reports auth/permission evidence from
	// bridge status, degradation, or observed delivery auth failures.
	BridgeDiagnosticKindPermissionDenied BridgeDiagnosticKind = "permission_denied"
	// BridgeDiagnosticKindUnsupportedCapability reports a provider/capability shape
	// that cannot support this bridge instance.
	BridgeDiagnosticKindUnsupportedCapability BridgeDiagnosticKind = "unsupported_capability"
	// BridgeDiagnosticKindTransientDeliveryFailure reports delivery failure evidence
	// that should be treated as retryable/transient by operators.
	BridgeDiagnosticKindTransientDeliveryFailure BridgeDiagnosticKind = "transient_delivery_failure"
)

type BridgeDiagnosticSeverity 

type BridgeDiagnosticSeverity string

BridgeDiagnosticSeverity identifies how strongly an operator should react to a bridge diagnostic. 

const (
	// BridgeDiagnosticSeverityInfo reports informational bridge state.
	BridgeDiagnosticSeverityInfo BridgeDiagnosticSeverity = "info"
	// BridgeDiagnosticSeverityWarning reports degraded but potentially recoverable bridge state.
	BridgeDiagnosticSeverityWarning BridgeDiagnosticSeverity = "warning"
	// BridgeDiagnosticSeverityError reports a bridge state that blocks reliable delivery.
	BridgeDiagnosticSeverityError BridgeDiagnosticSeverity = "error"
)

type BridgeDiagnosticsInput 

type BridgeDiagnosticsInput struct {
	Instance                 BridgeInstance
	Provider                 *BridgeProvider
	ProviderCatalogAvailable bool
	SecretBindings           []BridgeSecretBinding
	RouteCount               int
	DeliveryBacklog          int
	DeliveryFailuresTotal    int
	AuthFailuresTotal        int
	LastError                string
}

BridgeDiagnosticsInput carries the existing bridge facts used to derive diagnostics without probing or inventing runtime health.

type BridgeInstance 

type BridgeInstance struct {
	ID                   string               `json:"id"`
	Scope                Scope                `json:"scope"`
	WorkspaceID          string               `json:"workspace_id,omitempty"`
	Platform             string               `json:"platform"`
	ExtensionName        string               `json:"extension_name"`
	DisplayName          string               `json:"display_name"`
	Source               BridgeInstanceSource `json:"source,omitempty"`
	Enabled              bool                 `json:"enabled"`
	Status               BridgeStatus         `json:"status"`
	DMPolicy             BridgeDMPolicy       `json:"dm_policy,omitempty"`
	RoutingPolicy        RoutingPolicy        `json:"routing_policy"`
	ProviderConfig       json.RawMessage      `json:"provider_config,omitempty"`
	DeliveryDefaults     json.RawMessage      `json:"delivery_defaults,omitempty"`
	NotificationSuppress bool                 `json:"notification_suppress"`
	Degradation          *BridgeDegradation   `json:"degradation,omitempty"`
	CreatedAt            time.Time            `json:"created_at"`
	UpdatedAt            time.Time            `json:"updated_at"`
}

BridgeInstance is the authoritative persisted configuration for one bridge adapter instance.

func (BridgeInstance) Normalized 

func (i BridgeInstance) Normalized() BridgeInstance

Normalized returns the canonical representation of the bridge instance.

func (BridgeInstance) Validate 

func (i BridgeInstance) Validate() error

Validate reports whether the persisted bridge instance shape is complete and valid.

type BridgeInstanceReader 

type BridgeInstanceReader interface {
	GetBridgeInstance(ctx context.Context, id string) (BridgeInstance, error)
}

BridgeInstanceReader loads bridge instances for direct adapter delivery.

type BridgeInstanceSource 

type BridgeInstanceSource string

BridgeInstanceSource identifies where a persisted bridge instance originated. 

const (
	// BridgeInstanceSourceDynamic identifies a regular operator-created bridge instance.
	BridgeInstanceSourceDynamic BridgeInstanceSource = "dynamic"
	// BridgeInstanceSourcePackage identifies an extension bundle-managed bridge instance.
	BridgeInstanceSourcePackage BridgeInstanceSource = "package"
)

func (BridgeInstanceSource) Normalize 

func (s BridgeInstanceSource) Normalize() BridgeInstanceSource

Normalize returns the normalized representation of the source.

func (BridgeInstanceSource) Validate 

func (s BridgeInstanceSource) Validate() error

Validate reports whether the bridge-instance source is supported.

type BridgeInstanceSpec 

type BridgeInstanceSpec struct {
	Scope                Scope                       `json:"scope,omitempty"`
	WorkspaceID          string                      `json:"workspace_id,omitempty"`
	Platform             string                      `json:"platform"`
	ExtensionName        string                      `json:"extension_name"`
	DisplayName          string                      `json:"display_name"`
	Source               BridgeInstanceSource        `json:"source,omitempty"`
	Enabled              bool                        `json:"enabled"`
	DMPolicy             BridgeDMPolicy              `json:"dm_policy,omitempty"`
	RoutingPolicy        RoutingPolicy               `json:"routing_policy"`
	ProviderConfig       json.RawMessage             `json:"provider_config,omitempty"`
	DeliveryDefaults     json.RawMessage             `json:"delivery_defaults,omitempty"`
	NotificationSuppress bool                        `json:"notification_suppress"`
	SecretSlots          []BridgeSecretSlot          `json:"secret_slots,omitempty"`
	ConfigSchema         *BridgeProviderConfigSchema `json:"config_schema,omitempty"`
}

BridgeInstanceSpec is the canonical desired-state payload for bridge.instance records.

Runtime status, degradation, routes, delivery state, and assigned-instance reporting stay in the bridge runtime store. This spec carries only desired configuration plus provider manifest metadata that must be validated with the provider before persistence.

func BridgeInstanceSpecFromCreateRequest 

func BridgeInstanceSpecFromCreateRequest(
	req CreateInstanceRequest,
	now func() time.Time,
) (string, BridgeInstanceSpec, error)

BridgeInstanceSpecFromCreateRequest converts a transport/domain create request into desired resource state.

func BridgeInstanceSpecFromInstance 

func BridgeInstanceSpecFromInstance(instance BridgeInstance) BridgeInstanceSpec

BridgeInstanceSpecFromInstance strips bridge-owned operational fields from a bridge instance.

type BridgeProvider 

type BridgeProvider struct {
	Platform      string                      `json:"platform"`
	ExtensionName string                      `json:"extension_name"`
	DisplayName   string                      `json:"display_name"`
	Description   string                      `json:"description,omitempty"`
	SecretSlots   []BridgeSecretSlot          `json:"secret_slots,omitempty"`
	ConfigSchema  *BridgeProviderConfigSchema `json:"config_schema,omitempty"`
	Enabled       bool                        `json:"enabled"`
	State         string                      `json:"state"`
	Health        string                      `json:"health"`
	HealthMessage string                      `json:"health_message,omitempty"`
}

BridgeProvider describes one installed bridge-capable extension that can be selected when creating a bridge instance.

type BridgeProviderConfigSchema 

type BridgeProviderConfigSchema struct {
	Schema  string `toml:"schema,omitempty"  json:"schema,omitempty"`
	Version string `toml:"version,omitempty" json:"version,omitempty"`
}

BridgeProviderConfigSchema captures static provider config schema hints from provider manifests.

func (BridgeProviderConfigSchema) IsZero 

func (h BridgeProviderConfigSchema) IsZero() bool

IsZero reports whether the schema hint carries any values.

func (BridgeProviderConfigSchema) Normalize 

func (h BridgeProviderConfigSchema) Normalize() BridgeProviderConfigSchema

Normalize returns the normalized representation of the config schema hint.

func (BridgeProviderConfigSchema) Validate 

func (h BridgeProviderConfigSchema) Validate() error

Validate reports whether the config schema hint is internally consistent.

type BridgeProviderLookup 

type BridgeProviderLookup func(context.Context, string) (BridgeProvider, bool, error)

BridgeProviderLookup resolves provider-authored bridge manifest metadata for resource validation.

type BridgeRoute 

type BridgeRoute struct {
	RoutingKeyHash   string    `json:"routing_key_hash"`
	Scope            Scope     `json:"scope"`
	WorkspaceID      string    `json:"workspace_id,omitempty"`
	BridgeInstanceID string    `json:"bridge_instance_id"`
	PeerID           string    `json:"peer_id,omitempty"`
	ThreadID         string    `json:"thread_id,omitempty"`
	GroupID          string    `json:"group_id,omitempty"`
	SessionID        string    `json:"session_id"`
	AgentName        string    `json:"agent_name"`
	LastActivityAt   time.Time `json:"last_activity_at"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

BridgeRoute persists the canonical routing-key to ACP-session mapping.

func CanonicalizeRoute 

func CanonicalizeRoute(instance BridgeInstance, route BridgeRoute) (BridgeRoute, error)

CanonicalizeRoute rebuilds the supplied route identity under the instance's routing policy and computes the expected routing-key hash.

func (BridgeRoute) Canonicalize 

func (r BridgeRoute) Canonicalize() (BridgeRoute, error)

Canonicalize normalizes the route and fills the routing-key hash when missing.

func (BridgeRoute) RoutingKey 

func (r BridgeRoute) RoutingKey() RoutingKey

RoutingKey returns the canonical routing key represented by the route.

func (BridgeRoute) Validate 

func (r BridgeRoute) Validate() error

Validate reports whether the persisted route is complete and internally consistent.

type BridgeSecretBinding 

type BridgeSecretBinding struct {
	BridgeInstanceID string    `json:"bridge_instance_id"`
	BindingName      string    `json:"binding_name"`
	SecretRef        string    `json:"secret_ref"`
	Kind             string    `json:"kind"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

BridgeSecretBinding binds one named bridge secret slot to a daemon-managed secret reference.

func (BridgeSecretBinding) Validate 

func (b BridgeSecretBinding) Validate() error

Validate reports whether the persisted secret binding is complete and valid.

type BridgeSecretSlot 

type BridgeSecretSlot struct {
	Name        string `toml:"name"                  json:"name"`
	Description string `toml:"description,omitempty" json:"description,omitempty"`
	Required    bool   `toml:"required,omitempty"    json:"required,omitempty"`
}

BridgeSecretSlot describes one provider-declared secret requirement.

func (BridgeSecretSlot) Normalize 

func (s BridgeSecretSlot) Normalize() BridgeSecretSlot

Normalize returns the normalized representation of the secret slot.

func (BridgeSecretSlot) Validate 

func (s BridgeSecretSlot) Validate() error

Validate reports whether the secret slot metadata is complete.

type BridgeStatus 

type BridgeStatus string

BridgeStatus reports the operator-visible lifecycle state of a bridge instance. 

const (
	// BridgeStatusDisabled reports an instance that is intentionally disabled.
	BridgeStatusDisabled BridgeStatus = "disabled"
	// BridgeStatusStarting reports an instance that is launching or reconnecting.
	BridgeStatusStarting BridgeStatus = "starting"
	// BridgeStatusReady reports an instance that is healthy and ready to ingest/deliver.
	BridgeStatusReady BridgeStatus = "ready"
	// BridgeStatusDegraded reports an instance that is partially working with known issues.
	BridgeStatusDegraded BridgeStatus = "degraded"
	// BridgeStatusAuthRequired reports an instance that cannot operate until authentication is refreshed.
	BridgeStatusAuthRequired BridgeStatus = "auth_required"
	// BridgeStatusError reports an instance that is unhealthy due to a terminal or repeated fault.
	BridgeStatusError BridgeStatus = "error"
)

func (BridgeStatus) Normalize 

func (s BridgeStatus) Normalize() BridgeStatus

Normalize returns the normalized representation of the status.

func (BridgeStatus) Validate 

func (s BridgeStatus) Validate() error

Validate reports whether the status belongs to the closed bridge status set.

type BridgeTarget 

type BridgeTarget struct {
	BridgeID       string           `json:"bridge_id"`
	CanonicalRoute string           `json:"canonical_route"`
	DisplayName    string           `json:"display_name"`
	Normalized     string           `json:"normalized"`
	TargetType     BridgeTargetType `json:"target_type"`
	Qualifier      string           `json:"qualifier,omitempty"`
	Capabilities   []string         `json:"capabilities"`
	UpdatedAt      time.Time        `json:"updated_at"`
	LastSeenAt     time.Time        `json:"last_seen_at,omitzero"`
}

BridgeTarget is the daemon-normalized persisted directory row.

func (BridgeTarget) Validate 

func (t BridgeTarget) Validate() error

Validate reports whether the target row is ready for persistence.

type BridgeTargetPage 

type BridgeTargetPage struct {
	Items                   []BridgeTarget `json:"items"`
	Total                   int            `json:"total"`
	LastSuccessfulRefreshAt time.Time      `json:"last_successful_refresh_at,omitzero"`
}

BridgeTargetPage is the persistence-layer page for target directory reads.

type BridgeTargetQuery 

type BridgeTargetQuery struct {
	BridgeID        string        `json:"bridge_id"`
	Query           string        `json:"query,omitempty"`
	Limit           int           `json:"limit,omitempty"`
	FreshnessWindow time.Duration `json:"-"`
	GeneratedAt     time.Time     `json:"-"`
}

BridgeTargetQuery filters the persisted target directory for one bridge instance.

type BridgeTargetSnapshot 

type BridgeTargetSnapshot struct {
	CanonicalRoute string           `json:"canonical_route"`
	DisplayName    string           `json:"display_name"`
	TargetType     BridgeTargetType `json:"target_type"`
	Qualifier      string           `json:"qualifier,omitempty"`
	Capabilities   []string         `json:"capabilities,omitempty"`
	LastSeenAt     time.Time        `json:"last_seen_at,omitzero"`
}

BridgeTargetSnapshot is adapter-provided target data before daemon-owned normalization.

func (BridgeTargetSnapshot) Validate 

func (s BridgeTargetSnapshot) Validate() error

Validate reports whether the adapter snapshot has a stable provider identity.

type BridgeTargetSnapshotRequest 

type BridgeTargetSnapshotRequest struct {
	BridgeInstanceID string `json:"bridge_instance_id"`
}

BridgeTargetSnapshotRequest asks a bridge-capable extension to enumerate targets for one instance.

func (BridgeTargetSnapshotRequest) Validate 

func (r BridgeTargetSnapshotRequest) Validate() error

Validate reports whether the snapshot request identifies a bridge instance.

type BridgeTargetSnapshotResponse 

type BridgeTargetSnapshotResponse struct {
	Targets []BridgeTargetSnapshot `json:"targets"`
}

BridgeTargetSnapshotResponse carries adapter-enumerated targets back to the daemon.

type BridgeTargetType 

type BridgeTargetType string

BridgeTargetType identifies the provider target family used by a bridge adapter. 

const (
	BridgeTargetTypeChannel BridgeTargetType = "channel"
	BridgeTargetTypeUser    BridgeTargetType = "user"
	BridgeTargetTypeRoom    BridgeTargetType = "room"
	BridgeTargetTypeThread  BridgeTargetType = "thread"
	BridgeTargetTypeGroup   BridgeTargetType = "group"
)

func (BridgeTargetType) Normalize 

func (t BridgeTargetType) Normalize() BridgeTargetType

Normalize returns the canonical target type representation.

func (BridgeTargetType) Validate 

func (t BridgeTargetType) Validate() error

Validate reports whether the target type belongs to the supported set.

type BridgeTargetsResult 

type BridgeTargetsResult struct {
	BridgeID                string         `json:"bridge_id"`
	Items                   []BridgeTarget `json:"items"`
	Total                   int            `json:"total"`
	CacheStale              bool           `json:"cache_stale"`
	GeneratedAt             time.Time      `json:"generated_at"`
	LastSuccessfulRefreshAt time.Time      `json:"last_successful_refresh_at,omitzero"`
}

BridgeTargetsResult is the service-level target directory response.

type BridgeTaskSubscription 

type BridgeTaskSubscription struct {
	SubscriptionID   string                `json:"subscription_id"`
	TaskID           string                `json:"task_id"`
	BridgeInstanceID string                `json:"bridge_instance_id"`
	Scope            Scope                 `json:"scope"`
	WorkspaceID      string                `json:"workspace_id,omitempty"`
	PeerID           string                `json:"peer_id,omitempty"`
	ThreadID         string                `json:"thread_id,omitempty"`
	GroupID          string                `json:"group_id,omitempty"`
	DeliveryMode     DeliveryMode          `json:"delivery_mode"`
	CreatedBy        taskpkg.ActorIdentity `json:"created_by"`
	CreatedAt        time.Time             `json:"created_at"`
	UpdatedAt        time.Time             `json:"updated_at"`
}

BridgeTaskSubscription stores one bridge terminal-notification target for one task.

func (BridgeTaskSubscription) CursorKey 

func (s BridgeTaskSubscription) CursorKey() notifications.CursorKey

CursorKey returns the fixed cursor identity for this subscription.

func (BridgeTaskSubscription) DeliveryTarget 

func (s BridgeTaskSubscription) DeliveryTarget() DeliveryTarget

DeliveryTarget returns the outbound bridge delivery target for the subscription.

func (BridgeTaskSubscription) Normalize 

func (s BridgeTaskSubscription) Normalize() BridgeTaskSubscription

Normalize returns the canonical subscription representation.

func (BridgeTaskSubscription) RoutingKey 

func (s BridgeTaskSubscription) RoutingKey() RoutingKey

RoutingKey returns the subscription's bridge routing identity.

func (BridgeTaskSubscription) Validate 

func (s BridgeTaskSubscription) Validate() error

Validate reports whether a subscription contains a valid task delivery target.

type BridgeTaskSubscriptionQuery 

type BridgeTaskSubscriptionQuery struct {
	TaskID           string `json:"task_id,omitempty"`
	BridgeInstanceID string `json:"bridge_instance_id,omitempty"`
	Scope            Scope  `json:"scope,omitempty"`
	WorkspaceID      string `json:"workspace_id,omitempty"`
	Limit            int    `json:"limit,omitempty"`
}

BridgeTaskSubscriptionQuery filters persisted bridge task subscriptions.

func (BridgeTaskSubscriptionQuery) Normalize 

func (q BridgeTaskSubscriptionQuery) Normalize() BridgeTaskSubscriptionQuery

Normalize trims subscription query filters.

type BridgeTaskSubscriptionStore 

type BridgeTaskSubscriptionStore interface {
	PutBridgeTaskSubscription(ctx context.Context, subscription BridgeTaskSubscription) error
	GetBridgeTaskSubscription(ctx context.Context, subscriptionID string) (BridgeTaskSubscription, error)
	ListBridgeTaskSubscriptions(
		ctx context.Context,
		query BridgeTaskSubscriptionQuery,
	) ([]BridgeTaskSubscription, error)
	DeleteBridgeTaskSubscription(ctx context.Context, subscriptionID string) error
}

BridgeTaskSubscriptionStore persists bridge task subscription targets.

type Broker 

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

Broker projects session output into ordered delivery requests for one bridge-capable extension runtime.

func NewBroker 

func NewBroker(transport DeliveryTransport, opts ...DeliveryBrokerOption) *Broker

NewBroker constructs a delivery broker with bounded per-route queues and background workers for negotiated extension delivery.

func (*Broker) Close 

func (b *Broker) Close()

Close stops every background route worker.

func (*Broker) Deliver 

func (b *Broker) Deliver(ctx context.Context, evt DeliveryEvent) error

Deliver enqueues one already-projected delivery event for ordered extension delivery.

func (*Broker) DeliveryMetrics 

func (b *Broker) DeliveryMetrics() map[string]BridgeDeliveryMetrics

DeliveryMetrics returns a point-in-time snapshot of per-instance broker telemetry used by health and observability surfaces.

func (*Broker) FailSession 

func (b *Broker) FailSession(ctx context.Context, sessionID string, reason string) error

FailSession marks every unfinished delivery for the stopped session as a terminal error so adapters do not silently orphan bridge responses.

func (*Broker) ProjectEvent 

func (b *Broker) ProjectEvent(ctx context.Context, sessionID string, event DeliveryProjectionEvent) error

ProjectEvent converts one live or persisted session output event into the delivery-oriented stream for the registered prompt turn.

func (*Broker) RegisterPromptDelivery 

func (b *Broker) RegisterPromptDelivery(
	ctx context.Context,
	reg PromptDeliveryRegistration,
) (*DeliverySnapshot, error)

RegisterPromptDelivery binds one prompted session turn to a live delivery projection and optionally seeds the broker from already-persisted turn events.

func (*Broker) SetTransport 

func (b *Broker) SetTransport(transport DeliveryTransport)

SetTransport swaps the negotiated extension-delivery transport used by the broker.

func (*Broker) Snapshot 

func (b *Broker) Snapshot(ctx context.Context, deliveryID string) (*DeliverySnapshot, error)

Snapshot returns the current resumable state for one active delivery.

type CreateInstanceRequest 

type CreateInstanceRequest struct {
	ID                   string               `json:"id,omitempty"`
	Scope                Scope                `json:"scope"`
	WorkspaceID          string               `json:"workspace_id,omitempty"`
	Platform             string               `json:"platform"`
	ExtensionName        string               `json:"extension_name"`
	DisplayName          string               `json:"display_name"`
	Source               BridgeInstanceSource `json:"source,omitempty"`
	Enabled              bool                 `json:"enabled"`
	Status               BridgeStatus         `json:"status"`
	DMPolicy             BridgeDMPolicy       `json:"dm_policy,omitempty"`
	RoutingPolicy        RoutingPolicy        `json:"routing_policy"`
	ProviderConfig       json.RawMessage      `json:"provider_config,omitempty"`
	DeliveryDefaults     json.RawMessage      `json:"delivery_defaults,omitempty"`
	NotificationSuppress bool                 `json:"notification_suppress"`
	Degradation          *BridgeDegradation   `json:"degradation,omitempty"`
	CreatedAt            time.Time            `json:"created_at"`
	UpdatedAt            time.Time            `json:"updated_at"`
}

CreateInstanceRequest captures the persisted configuration for a new bridge instance.

func (CreateInstanceRequest) Validate 

func (r CreateInstanceRequest) Validate() error

Validate reports whether the creation request contains a valid instance definition.

type DeliveryAck 

type DeliveryAck struct {
	DeliveryID             string `json:"delivery_id,omitempty"`
	Seq                    int64  `json:"seq,omitempty"`
	RemoteMessageID        string `json:"remote_message_id,omitempty"`
	ReplaceRemoteMessageID string `json:"replace_remote_message_id,omitempty"`
}

DeliveryAck is the negotiated extension->daemon acknowledgement payload for one `bridges/deliver` request.

func (DeliveryAck) ValidateFor 

func (a DeliveryAck) ValidateFor(event DeliveryEvent) error

ValidateFor reports whether the acknowledgement still belongs to the request that triggered it.

type DeliveryBrokerOption 

type DeliveryBrokerOption func(*Broker)

DeliveryBrokerOption customizes delivery-broker construction.

func WithDeliveryBrokerLifecycleContext 

func WithDeliveryBrokerLifecycleContext(ctx context.Context) DeliveryBrokerOption

WithDeliveryBrokerLifecycleContext injects the broker-owned lifecycle context used by background route workers.

func WithDeliveryBrokerNow 

func WithDeliveryBrokerNow(now func() time.Time) DeliveryBrokerOption

WithDeliveryBrokerNow overrides the broker clock, mainly for tests.

func WithDeliveryBrokerQueueCapacity 

func WithDeliveryBrokerQueueCapacity(capacity int) DeliveryBrokerOption

WithDeliveryBrokerQueueCapacity overrides the bounded queue length per routed delivery worker. Values below 2 are raised to 2 so `start` and one terminal event can coexist under pressure.

func WithDeliveryBrokerRequestTimeout 

func WithDeliveryBrokerRequestTimeout(timeout time.Duration) DeliveryBrokerOption

WithDeliveryBrokerRequestTimeout overrides the timeout applied to one negotiated `bridges/deliver` call.

func WithDeliveryBrokerRetryDelay 

func WithDeliveryBrokerRetryDelay(delay time.Duration) DeliveryBrokerOption

WithDeliveryBrokerRetryDelay overrides the backoff between retry attempts after a delivery-transport failure.

type DeliveryErrorDetail 

type DeliveryErrorDetail struct {
	Message string `json:"message"`
}

DeliveryErrorDetail captures one typed delivery failure payload.

func (DeliveryErrorDetail) Validate 

func (d DeliveryErrorDetail) Validate() error

Validate reports whether the error detail carries a message.

type DeliveryEvent 

type DeliveryEvent struct {
	DeliveryID       string                    `json:"delivery_id"`
	BridgeInstanceID string                    `json:"bridge_instance_id"`
	RoutingKey       RoutingKey                `json:"routing_key"`
	DeliveryTarget   DeliveryTarget            `json:"delivery_target"`
	Seq              int64                     `json:"seq"`
	EventType        string                    `json:"event_type"`
	Content          MessageContent            `json:"content"`
	Final            bool                      `json:"final"`
	Operation        DeliveryOperation         `json:"operation,omitempty"`
	Reference        *DeliveryMessageReference `json:"reference,omitempty"`
	Error            *DeliveryErrorDetail      `json:"error,omitempty"`
	Resume           *DeliveryResumeState      `json:"resume,omitempty"`
	ProviderMetadata json.RawMessage           `json:"provider_metadata,omitempty"`
}

DeliveryEvent is the daemon-owned outbound projection sent to a bridge adapter.

func (DeliveryEvent) Validate 

func (e DeliveryEvent) Validate() error

Validate reports whether the delivery event contains the required identifiers.

type DeliveryMessageReference 

type DeliveryMessageReference struct {
	DeliveryID      string `json:"delivery_id,omitempty"`
	RemoteMessageID string `json:"remote_message_id,omitempty"`
}

DeliveryMessageReference identifies one previously delivered message.

func (DeliveryMessageReference) Validate 

func (r DeliveryMessageReference) Validate() error

Validate reports whether the reference identifies at least one prior message handle.

type DeliveryMode 

type DeliveryMode string

DeliveryMode identifies the daemon-owned outbound delivery behavior requested for one canonical bridge target. 

const (
	// DeliveryModeDirectSend sends a fresh outbound message into the target conversation.
	DeliveryModeDirectSend DeliveryMode = "direct-send"
	// DeliveryModeReply sends an outbound reply within the resolved conversation context.
	DeliveryModeReply DeliveryMode = "reply"
)

func (DeliveryMode) Normalize 

func (m DeliveryMode) Normalize() DeliveryMode

Normalize returns the canonical delivery mode representation.

func (DeliveryMode) Validate 

func (m DeliveryMode) Validate() error

Validate reports whether the delivery mode belongs to the supported mode set.

type DeliveryOperation 

type DeliveryOperation string

DeliveryOperation identifies whether the outbound delivery is posting new text, editing an existing remote message, or deleting one. 

const (
	// DeliveryOperationPost creates or continues a new daemon-owned delivery.
	DeliveryOperationPost DeliveryOperation = "post"
	// DeliveryOperationEdit updates a previously delivered message in-place.
	DeliveryOperationEdit DeliveryOperation = "edit"
	// DeliveryOperationDelete removes a previously delivered message.
	DeliveryOperationDelete DeliveryOperation = "delete"
)

func (DeliveryOperation) Normalize 

func (o DeliveryOperation) Normalize() DeliveryOperation

Normalize returns the canonical delivery-operation representation.

func (DeliveryOperation) Validate 

func (o DeliveryOperation) Validate() error

Validate reports whether the delivery operation belongs to the supported set.

type DeliveryProjectionEvent 

type DeliveryProjectionEvent struct {
	Type        string    `json:"type"`
	TurnID      string    `json:"turn_id"`
	Timestamp   time.Time `json:"timestamp"`
	Text        string    `json:"text,omitempty"`
	Error       string    `json:"error,omitempty"`
	Fingerprint string    `json:"fingerprint,omitempty"`
}

DeliveryProjectionEvent is the reduced session-event shape the broker needs to project prompt output into delivery-oriented bridge events. It remains ACP-agnostic so `internal/bridges` does not depend on runtime transport packages.

type DeliveryRequest 

type DeliveryRequest struct {
	Event    DeliveryEvent     `json:"event"`
	Snapshot *DeliverySnapshot `json:"snapshot,omitempty"`
}

DeliveryRequest is the negotiated daemon->extension request payload for `bridges/deliver`. Regular streaming requests carry only Event. Recovery requests also carry Snapshot and use EventTypeResume.

func (DeliveryRequest) Validate 

func (r DeliveryRequest) Validate() error

Validate reports whether the negotiated request is internally consistent.

type DeliveryResumeState 

type DeliveryResumeState struct {
	LatestEventType string `json:"latest_event_type"`
}

DeliveryResumeState captures the typed resumable delivery phase.

func (DeliveryResumeState) Validate 

func (s DeliveryResumeState) Validate() error

Validate reports whether the resume state references a supported prior event type.

type DeliverySnapshot 

type DeliverySnapshot struct {
	DeliveryID             string                    `json:"delivery_id"`
	SessionID              string                    `json:"session_id"`
	TurnID                 string                    `json:"turn_id"`
	BridgeInstanceID       string                    `json:"bridge_instance_id"`
	RoutingKey             RoutingKey                `json:"routing_key"`
	DeliveryTarget         DeliveryTarget            `json:"delivery_target"`
	LatestSeq              int64                     `json:"latest_seq"`
	LatestEventType        string                    `json:"latest_event_type"`
	CurrentContent         MessageContent            `json:"current_content"`
	Operation              DeliveryOperation         `json:"operation,omitempty"`
	Reference              *DeliveryMessageReference `json:"reference,omitempty"`
	ProviderMetadata       json.RawMessage           `json:"provider_metadata,omitempty"`
	LastSentSeq            int64                     `json:"last_sent_seq,omitempty"`
	LastAckedSeq           int64                     `json:"last_acked_seq,omitempty"`
	RemoteMessageID        string                    `json:"remote_message_id,omitempty"`
	ReplaceRemoteMessageID string                    `json:"replace_remote_message_id,omitempty"`
	Final                  bool                      `json:"final"`
	Error                  string                    `json:"error,omitempty"`
	UpdatedAt              time.Time                 `json:"updated_at"`
}

DeliverySnapshot captures the current progressive state for one active delivery so the broker can resume it after adapter recovery.

func (DeliverySnapshot) Validate 

func (s DeliverySnapshot) Validate() error

Validate reports whether the snapshot contains the state needed to resume a negotiated bridge delivery.

type DeliveryTarget 

type DeliveryTarget struct {
	BridgeInstanceID string       `json:"bridge_instance_id"`
	PeerID           string       `json:"peer_id,omitempty"`
	ThreadID         string       `json:"thread_id,omitempty"`
	GroupID          string       `json:"group_id,omitempty"`
	Mode             DeliveryMode `json:"mode,omitempty"`
}

DeliveryTarget identifies an outbound delivery destination within one bridge instance.

func BuildDeliveryTarget 

func BuildDeliveryTarget(instance BridgeInstance, req ResolveDeliveryTargetRequest) (DeliveryTarget, error)

BuildDeliveryTarget merges bridge-instance delivery defaults with explicit request overrides and returns one canonical outbound target.

func (DeliveryTarget) IsZero 

func (t DeliveryTarget) IsZero() bool

IsZero reports whether the target carries any values.

func (DeliveryTarget) Validate 

func (t DeliveryTarget) Validate() error

Validate reports whether the delivery target contains a supported mode and the identity fields required by that mode.

type DeliveryTransport 

type DeliveryTransport interface {
	DeliverBridge(ctx context.Context, extensionName string, req DeliveryRequest) (DeliveryAck, error)
}

DeliveryTransport delivers negotiated daemon->extension bridge requests. The extension name remains explicit because the broker owns routing semantics, while the extension manager owns the subprocess runtime.

type InboundAction 

type InboundAction struct {
	ActionID  string `json:"action_id"`
	MessageID string `json:"message_id,omitempty"`
	Value     string `json:"value,omitempty"`
	TriggerID string `json:"trigger_id,omitempty"`
}

InboundAction captures a typed button/action inbound interaction.

func (InboundAction) Validate 

func (a InboundAction) Validate() error

Validate reports whether the action payload contains the required identity.

type InboundCommand 

type InboundCommand struct {
	Command   string `json:"command"`
	Text      string `json:"text,omitempty"`
	TriggerID string `json:"trigger_id,omitempty"`
}

InboundCommand captures a typed slash-command style inbound interaction.

func (InboundCommand) Validate 

func (c InboundCommand) Validate() error

Validate reports whether the command payload contains the required identity.

type InboundEventFamily 

type InboundEventFamily string

InboundEventFamily identifies the typed inbound bridge event family. 

const (
	// InboundEventFamilyMessage identifies a text-and-attachment message event.
	InboundEventFamilyMessage InboundEventFamily = "message"
	// InboundEventFamilyCommand identifies a typed slash-command style event.
	InboundEventFamilyCommand InboundEventFamily = "command"
	// InboundEventFamilyAction identifies a typed button/action event.
	InboundEventFamilyAction InboundEventFamily = "action"
	// InboundEventFamilyReaction identifies a typed reaction add/remove event.
	InboundEventFamilyReaction InboundEventFamily = "reaction"
)

func (InboundEventFamily) Normalize 

func (f InboundEventFamily) Normalize() InboundEventFamily

Normalize returns the canonical inbound event-family representation.

func (InboundEventFamily) Validate 

func (f InboundEventFamily) Validate() error

Validate reports whether the inbound event family belongs to the supported set.

type InboundMessageEnvelope 

type InboundMessageEnvelope struct {
	BridgeInstanceID  string                  `json:"bridge_instance_id"`
	Scope             Scope                   `json:"scope"`
	WorkspaceID       string                  `json:"workspace_id,omitempty"`
	PeerID            string                  `json:"peer_id,omitempty"`
	ThreadID          string                  `json:"thread_id,omitempty"`
	GroupID           string                  `json:"group_id,omitempty"`
	PlatformMessageID string                  `json:"platform_message_id"`
	ReceivedAt        time.Time               `json:"received_at"`
	Sender            MessageSender           `json:"sender"`
	Content           MessageContent          `json:"content"`
	Attachments       []MessageAttachment     `json:"attachments,omitempty"`
	EventFamily       InboundEventFamily      `json:"event_family"`
	Command           *InboundCommand         `json:"command,omitempty"`
	Action            *InboundAction          `json:"action,omitempty"`
	Reaction          *InboundReaction        `json:"reaction,omitempty"`
	Conversation      *NetworkConversationRef `json:"conversation,omitempty"`
	ProviderMetadata  json.RawMessage         `json:"provider_metadata,omitempty"`
	IdempotencyKey    string                  `json:"idempotency_key"`
}

InboundMessageEnvelope is the normalized bridge ingest payload delivered by adapters.

func (InboundMessageEnvelope) NetworkConversationRef 

func (e InboundMessageEnvelope) NetworkConversationRef() (NetworkConversationRef, bool, error)

NetworkConversationRef returns only the explicit AGH conversation mapping.

func (InboundMessageEnvelope) Validate 

func (e InboundMessageEnvelope) Validate() error

Validate reports whether the inbound envelope contains the required identifying fields.

type InboundReaction 

type InboundReaction struct {
	MessageID string `json:"message_id"`
	Emoji     string `json:"emoji"`
	RawEmoji  string `json:"raw_emoji,omitempty"`
	Added     bool   `json:"added"`
}

InboundReaction captures a typed reaction add/remove inbound interaction.

func (InboundReaction) Validate 

func (r InboundReaction) Validate() error

Validate reports whether the reaction payload contains the required identity.

type IngestDedupRecord 

type IngestDedupRecord struct {
	IdempotencyKey   string    `json:"idempotency_key"`
	BridgeInstanceID string    `json:"bridge_instance_id"`
	ReceivedAt       time.Time `json:"received_at"`
	ExpiresAt        time.Time `json:"expires_at"`
}

IngestDedupRecord tracks inbound idempotency keys with an explicit TTL.

func (IngestDedupRecord) Validate 

func (r IngestDedupRecord) Validate() error

Validate reports whether the dedup record is complete and time-consistent.

type MessageAttachment 

type MessageAttachment struct {
	ID       string `json:"id,omitempty"`
	Name     string `json:"name,omitempty"`
	MIMEType string `json:"mime_type,omitempty"`
	URL      string `json:"url,omitempty"`
}

MessageAttachment captures normalized attachment metadata shared by ingest and delivery flows.

type MessageContent 

type MessageContent struct {
	Text string `json:"text,omitempty"`
}

MessageContent carries normalized text content shared by inbound and outbound bridge models.

type MessageSender 

type MessageSender struct {
	ID          string `json:"id,omitempty"`
	Username    string `json:"username,omitempty"`
	DisplayName string `json:"display_name,omitempty"`
}

MessageSender identifies the upstream actor that produced an inbound message.

type NetworkConversationRef 

type NetworkConversationRef struct {
	Channel     string                     `json:"channel"`
	Surface     NetworkConversationSurface `json:"surface"`
	ThreadID    string                     `json:"thread_id,omitempty"`
	DirectID    string                     `json:"direct_id,omitempty"`
	WorkID      string                     `json:"work_id,omitempty"`
	ReplyTo     string                     `json:"reply_to,omitempty"`
	TraceID     string                     `json:"trace_id,omitempty"`
	CausationID string                     `json:"causation_id,omitempty"`
}

NetworkConversationRef carries an explicit bridge-to-AGH conversation mapping.

func (NetworkConversationRef) Validate 

func (r NetworkConversationRef) Validate() error

Validate reports whether the explicit bridge mapping selects one AGH conversation container.

type NetworkConversationSurface 

type NetworkConversationSurface string

NetworkConversationSurface identifies one explicit AGH network conversation container. 

const (
	// NetworkConversationSurfaceThread maps bridge ingress into a public AGH thread.
	NetworkConversationSurfaceThread NetworkConversationSurface = "thread"
	// NetworkConversationSurfaceDirect maps bridge ingress into a resolved AGH direct room.
	NetworkConversationSurfaceDirect NetworkConversationSurface = "direct"
)

func (NetworkConversationSurface) Normalize 

func (s NetworkConversationSurface) Normalize() NetworkConversationSurface

Normalize returns the canonical bridge conversation surface.

type PlatformDimensionMapping 

type PlatformDimensionMapping struct {
	Platform        string `json:"platform"`
	PeerIDConcept   string `json:"peer_id_concept,omitempty"`
	ThreadIDConcept string `json:"thread_id_concept,omitempty"`
	GroupIDConcept  string `json:"group_id_concept,omitempty"`
}

PlatformDimensionMapping documents how one adapter maps platform-native identity concepts onto AGH's canonical routing dimensions.

Semantics: - `peer_id` identifies the direct conversation peer or primary counterparty. - `thread_id` identifies a sub-conversation nested under a peer or group. - `group_id` identifies a shared container such as a room, forum, bridge, or guild.

Adapters should publish one mapping per platform so route inspection and cross-platform tooling can interpret `peer_id`, `thread_id`, and `group_id` consistently.

func (PlatformDimensionMapping) Validate 

func (m PlatformDimensionMapping) Validate() error

Validate reports whether the contract identifies a platform and at least one mapped routing dimension concept.

type PromptDeliveryRegistration 

type PromptDeliveryRegistration struct {
	SessionID      string                    `json:"session_id"`
	TurnID         string                    `json:"turn_id"`
	ExtensionName  string                    `json:"extension_name"`
	DeliveryID     string                    `json:"delivery_id,omitempty"`
	RoutingKey     RoutingKey                `json:"routing_key"`
	DeliveryTarget DeliveryTarget            `json:"delivery_target"`
	SeedEvents     []DeliveryProjectionEvent `json:"seed_events,omitempty"`
}

PromptDeliveryRegistration binds one session prompt turn to a routed bridge delivery stream before or shortly after the prompt begins emitting events.

func (PromptDeliveryRegistration) Validate 

func (r PromptDeliveryRegistration) Validate() error

Validate reports whether the registration contains enough routed context to project session output into a negotiated delivery stream.

type Registry 

type Registry interface {
	CreateInstance(ctx context.Context, req CreateInstanceRequest) (*BridgeInstance, error)
	GetInstance(ctx context.Context, id string) (*BridgeInstance, error)
	ListInstances(ctx context.Context) ([]BridgeInstance, error)
	UpdateInstance(ctx context.Context, req UpdateInstanceRequest) (*BridgeInstance, error)
	UpdateInstanceState(ctx context.Context, req UpdateInstanceStateRequest) (*BridgeInstance, error)
	BuildRoutingKey(ctx context.Context, key RoutingKey) (RoutingKey, error)
	ResolveRoute(ctx context.Context, key RoutingKey) (*BridgeRoute, error)
	ResolveOrCreateRoute(ctx context.Context, route BridgeRoute) (*BridgeRoute, bool, error)
	UpsertRoute(ctx context.Context, route BridgeRoute) (*BridgeRoute, error)
	ListRoutes(ctx context.Context, bridgeInstanceID string) ([]BridgeRoute, error)
}

Registry owns bridge instance lifecycle validation and canonical routing-key construction on top of the persistence layer.

type RegistryOption 

type RegistryOption func(*Service)

RegistryOption customizes Service construction.

func WithNow 

func WithNow(now func() time.Time) RegistryOption

WithNow overrides the clock used for default timestamps in tests.

type RegistryStore 

type RegistryStore interface {
	InsertBridgeInstance(ctx context.Context, instance BridgeInstance) error
	UpdateBridgeInstance(ctx context.Context, instance BridgeInstance) error
	GetBridgeInstance(ctx context.Context, id string) (BridgeInstance, error)
	ListBridgeInstances(ctx context.Context) ([]BridgeInstance, error)
	PutBridgeRoute(ctx context.Context, route BridgeRoute) error
	ResolveBridgeRoute(ctx context.Context, key RoutingKey) (BridgeRoute, error)
	ListBridgeRoutes(ctx context.Context, bridgeInstanceID string) ([]BridgeRoute, error)
}

RegistryStore is the persistence surface consumed by the daemon-owned bridge registry. The global DB implementation from task 01 satisfies this contract.

type ResolveBridgeTargetResult 

type ResolveBridgeTargetResult struct {
	Match      *BridgeTarget  `json:"match,omitempty"`
	Step       int            `json:"step"`
	Ambiguous  bool           `json:"ambiguous"`
	Candidates []BridgeTarget `json:"candidates,omitempty"`
}

ResolveBridgeTargetResult reports the deterministic resolver step for one friendly target lookup.

type ResolveDeliveryTargetRequest 

type ResolveDeliveryTargetRequest struct {
	BridgeInstanceID string       `json:"bridge_instance_id"`
	PeerID           string       `json:"peer_id,omitempty"`
	ThreadID         string       `json:"thread_id,omitempty"`
	GroupID          string       `json:"group_id,omitempty"`
	Mode             DeliveryMode `json:"mode,omitempty"`
}

ResolveDeliveryTargetRequest captures one outbound target request before bridge-instance defaults have been merged in.

func (ResolveDeliveryTargetRequest) Validate 

func (r ResolveDeliveryTargetRequest) Validate() error

Validate reports whether the request identifies the owning bridge instance.

type ResourceProjectionPlan 

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

ResourceProjectionPlan is the validated bridge.instance delta built from canonical resources.

func BuildResourceState 

func BuildResourceState(
	ctx context.Context,
	store ResourceProjectionStore,
	records []resources.Record[BridgeInstanceSpec],
	now func() time.Time,
) (*ResourceProjectionPlan, error)

BuildResourceState computes the next bridge runtime projection without opening live provider connections.

func (*ResourceProjectionPlan) ChangedExtensions 

func (p *ResourceProjectionPlan) ChangedExtensions() []string

ChangedExtensions returns the provider extensions impacted by this plan.

func (*ResourceProjectionPlan) Kind 

func (p *ResourceProjectionPlan) Kind() resources.ResourceKind

Kind returns the projected resource kind.

func (*ResourceProjectionPlan) NextInstances 

func (p *ResourceProjectionPlan) NextInstances() []BridgeInstance

NextInstances returns the daemon-visible bridge state after this plan applies.

func (*ResourceProjectionPlan) OperationCount 

func (p *ResourceProjectionPlan) OperationCount() int

OperationCount returns the number of runtime rows that change when this plan applies.

func (*ResourceProjectionPlan) PreviousInstances 

func (p *ResourceProjectionPlan) PreviousInstances() []BridgeInstance

PreviousInstances returns the daemon-visible bridge state before this plan applies.

func (*ResourceProjectionPlan) Revision 

func (p *ResourceProjectionPlan) Revision() int64

Revision returns the highest source resource version represented by this plan.

func (*ResourceProjectionPlan) RollbackPlan 

func (p *ResourceProjectionPlan) RollbackPlan() *ResourceProjectionPlan

RollbackPlan returns a plan that restores the prior daemon-visible bridge state.

type ResourceProjectionStore 

type ResourceProjectionStore interface {
	ListBridgeInstances(ctx context.Context) ([]BridgeInstance, error)
	ReplaceBridgeInstances(ctx context.Context, instances []BridgeInstance) error
}

ResourceProjectionStore is the bridge desired-runtime surface updated by resource projection.

type RoutingDimensions 

type RoutingDimensions struct {
	PeerID   string `json:"peer_id,omitempty"`
	ThreadID string `json:"thread_id,omitempty"`
	GroupID  string `json:"group_id,omitempty"`
}

RoutingDimensions carries the platform-normalized identity values that may participate in a routing key, depending on the instance routing policy.

type RoutingKey 

type RoutingKey struct {
	Scope            Scope  `json:"scope"`
	WorkspaceID      string `json:"workspace_id,omitempty"`
	BridgeInstanceID string `json:"bridge_instance_id"`
	PeerID           string `json:"peer_id,omitempty"`
	ThreadID         string `json:"thread_id,omitempty"`
	GroupID          string `json:"group_id,omitempty"`
}

RoutingKey is the canonical identity used to resolve bridge traffic to one ACP session.

func BuildRoutingKey 

func BuildRoutingKey(instance BridgeInstance, dims RoutingDimensions) (RoutingKey, error)

BuildRoutingKey constructs the canonical routing key for one instance using the instance's fixed base identity and policy-selected routing dimensions.

func CanonicalizeRoutingKey 

func CanonicalizeRoutingKey(instance BridgeInstance, key RoutingKey) (RoutingKey, error)

CanonicalizeRoutingKey rebuilds the supplied routing key under the instance's routing policy and validates that any supplied base identity matches.

func (RoutingKey) Hash 

func (k RoutingKey) Hash() (string, error)

Hash returns the stable SHA-256 hash for the serialized routing key.

func (RoutingKey) Serialize 

func (k RoutingKey) Serialize() (string, error)

Serialize returns the stable serialized representation used for routing-key hashing.

func (RoutingKey) Validate 

func (k RoutingKey) Validate() error

Validate reports whether the routing key carries the required base identity.

type RoutingPolicy 

type RoutingPolicy struct {
	IncludePeer   bool `json:"include_peer"`
	IncludeThread bool `json:"include_thread"`
	IncludeGroup  bool `json:"include_group"`
}

RoutingPolicy controls which platform identity dimensions participate in routing.

func (RoutingPolicy) Validate 

func (p RoutingPolicy) Validate() error

Validate reports whether the routing policy is internally consistent.

type Scope 

type Scope string

Scope identifies whether a bridge resource is daemon-global or workspace-owned. 

const (
	// ScopeGlobal identifies a daemon-global bridge resource.
	ScopeGlobal Scope = "global"
	// ScopeWorkspace identifies a workspace-owned bridge resource.
	ScopeWorkspace Scope = "workspace"
)

func (Scope) Normalize 

func (s Scope) Normalize() Scope

Normalize returns the normalized representation of the scope.

func (Scope) Validate 

func (s Scope) Validate() error

Validate reports whether the scope is supported.

type Service 

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

Service is the concrete daemon-owned registry implementation.

func NewRegistry 

func NewRegistry(store RegistryStore, opts ...RegistryOption) *Service

NewRegistry constructs the bridge registry over the supplied persistence surface.

func (*Service) BuildRoutingKey 

func (s *Service) BuildRoutingKey(ctx context.Context, key RoutingKey) (RoutingKey, error)

BuildRoutingKey canonicalizes the supplied routing identity under the owning instance policy.

func (*Service) CreateInstance 

func (s *Service) CreateInstance(ctx context.Context, req CreateInstanceRequest) (*BridgeInstance, error)

CreateInstance persists a new bridge instance after applying lifecycle validation.

func (*Service) GetInstance 

func (s *Service) GetInstance(ctx context.Context, id string) (*BridgeInstance, error)

GetInstance returns one persisted bridge instance by primary key.

func (*Service) ListBridgeTargets 

func (s *Service) ListBridgeTargets(ctx context.Context, query BridgeTargetQuery) (BridgeTargetsResult, error)

ListBridgeTargets lists persisted bridge targets and reports cache freshness.

func (*Service) ListInstances 

func (s *Service) ListInstances(ctx context.Context) ([]BridgeInstance, error)

ListInstances returns all persisted bridge instances.

func (*Service) ListRoutes 

func (s *Service) ListRoutes(ctx context.Context, bridgeInstanceID string) ([]BridgeRoute, error)

ListRoutes returns the persisted routes owned by one bridge instance.

func (*Service) RefreshBridgeTargets 

func (s *Service) RefreshBridgeTargets(
	ctx context.Context,
	bridgeID string,
	snapshots []BridgeTargetSnapshot,
) ([]BridgeTarget, error)

RefreshBridgeTargets validates adapter snapshots and persists them as one daemon-owned refresh.

func (*Service) ResolveBridgeTarget 

func (s *Service) ResolveBridgeTarget(
	ctx context.Context,
	bridgeID string,
	query string,
) (ResolveBridgeTargetResult, error)

ResolveBridgeTarget resolves a canonical bridge target using the Hermes-style 4-step algorithm.

func (*Service) ResolveDeliveryTarget 

func (s *Service) ResolveDeliveryTarget(
	ctx context.Context,
	req ResolveDeliveryTargetRequest,
) (*DeliveryTarget, error)

ResolveDeliveryTarget loads the owning bridge instance and resolves the canonical outbound target under that instance's delivery defaults.

func (*Service) ResolveOrCreateRoute 

func (s *Service) ResolveOrCreateRoute(ctx context.Context, route BridgeRoute) (*BridgeRoute, bool, error)

ResolveOrCreateRoute reuses an existing session binding for the canonical key or persists the supplied route when no binding exists yet.

func (*Service) ResolveRoute 

func (s *Service) ResolveRoute(ctx context.Context, key RoutingKey) (*BridgeRoute, error)

ResolveRoute resolves one route by canonical routing identity.

func (*Service) UpdateInstance 

func (s *Service) UpdateInstance(ctx context.Context, req UpdateInstanceRequest) (*BridgeInstance, error)

UpdateInstance updates one persisted bridge instance without changing its lifecycle state.

func (*Service) UpdateInstanceState 

func (s *Service) UpdateInstanceState(ctx context.Context, req UpdateInstanceStateRequest) (*BridgeInstance, error)

UpdateInstanceState applies one validated lifecycle transition to a persisted instance.

func (*Service) UpsertRoute 

func (s *Service) UpsertRoute(ctx context.Context, route BridgeRoute) (*BridgeRoute, error)

UpsertRoute writes a route using the canonical key derived from the owning instance policy.

type TargetDirectory 

type TargetDirectory interface {
	RefreshBridgeTargets(
		ctx context.Context,
		bridgeID string,
		snapshots []BridgeTargetSnapshot,
	) ([]BridgeTarget, error)
	ListBridgeTargets(ctx context.Context, query BridgeTargetQuery) (BridgeTargetsResult, error)
	ResolveBridgeTarget(ctx context.Context, bridgeID string, query string) (ResolveBridgeTargetResult, error)
}

TargetDirectory is the daemon-owned bridge target directory behavior.

type TargetDirectoryStore 

type TargetDirectoryStore interface {
	RefreshBridgeTargets(ctx context.Context, bridgeID string, targets []BridgeTarget, refreshedAt time.Time) error
	ListBridgeTargets(ctx context.Context, query BridgeTargetQuery) (BridgeTargetPage, error)
	GetBridgeTargetByCanonical(ctx context.Context, bridgeID string, canonicalRoute string) (BridgeTarget, error)
	FindBridgeTargetsByNormalized(ctx context.Context, bridgeID string, normalized string) ([]BridgeTarget, error)
	FindBridgeTargetsByQualifiedName(
		ctx context.Context,
		bridgeID string,
		qualifier string,
		normalized string,
	) ([]BridgeTarget, error)
	FindBridgeTargetsByPrefix(ctx context.Context, bridgeID string, normalizedPrefix string) ([]BridgeTarget, error)
}

TargetDirectoryStore is the persistence surface for daemon-owned bridge target refreshes.

type TargetResolver 

type TargetResolver interface {
	ResolveDeliveryTarget(ctx context.Context, req ResolveDeliveryTargetRequest) (*DeliveryTarget, error)
}

TargetResolver resolves one canonical outbound delivery target from bridge instance metadata plus explicit destination overrides.

type TargetSnapshotTransport 

type TargetSnapshotTransport interface {
	BridgeTargetSnapshots(
		ctx context.Context,
		extensionName string,
		req BridgeTargetSnapshotRequest,
	) ([]BridgeTargetSnapshot, error)
}

TargetSnapshotTransport calls bridge-capable extension adapters for target snapshots.

type TerminalTaskEventReader 

type TerminalTaskEventReader interface {
	GetTask(ctx context.Context, id string) (taskpkg.Task, error)
	GetTaskRun(ctx context.Context, id string) (taskpkg.Run, error)
	ListTaskEventRecords(ctx context.Context, query taskpkg.EventRecordQuery) ([]taskpkg.EventRecord, error)
}

TerminalTaskEventReader reads the durable task state used to replay terminal notifications.

type TerminalTaskNotification 

type TerminalTaskNotification struct {
	DeliveryID     string          `json:"delivery_id"`
	EventType      string          `json:"event_type"`
	Final          bool            `json:"final"`
	Seq            int64           `json:"seq"`
	TaskID         string          `json:"task_id"`
	RunID          string          `json:"run_id,omitempty"`
	Status         taskpkg.Status  `json:"status"`
	Summary        string          `json:"summary,omitempty"`
	Error          string          `json:"error,omitempty"`
	Payload        json.RawMessage `json:"payload,omitempty"`
	SubscriptionID string          `json:"subscription_id"`
}

TerminalTaskNotification is the bridge-delivered accepted-final task envelope.

type TerminalTaskNotificationSweep 

type TerminalTaskNotificationSweep struct {
	Subscriptions int `json:"subscriptions"`
	Delivered     int `json:"delivered"`
	Suppressed    int `json:"suppressed"`
	Deferred      int `json:"deferred"`
	Failed        int `json:"failed"`
}

TerminalTaskNotificationSweep summarizes one notifier replay pass.

type TerminalTaskNotifier 

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

TerminalTaskNotifier replays durable task events into subscribed bridge targets.

func NewTerminalTaskNotifier 

func NewTerminalTaskNotifier(cfg TerminalTaskNotifierConfig) *TerminalTaskNotifier

NewTerminalTaskNotifier constructs a bridge terminal notifier.

func (*TerminalTaskNotifier) DeliverDue 

func (n *TerminalTaskNotifier) DeliverDue(
	ctx context.Context,
	query BridgeTaskSubscriptionQuery,
) (TerminalTaskNotificationSweep, error)

DeliverDue replays task events for subscriptions matching the query.

type TerminalTaskNotifierConfig 

type TerminalTaskNotifierConfig struct {
	Subscriptions BridgeTaskSubscriptionStore
	TaskEvents    TerminalTaskEventReader
	Instances     BridgeInstanceReader
	Cursors       notifications.CursorStore
	Transport     DeliveryTransport
	Now           func() time.Time
	EventLimit    int
}

TerminalTaskNotifierConfig wires the bridge terminal notifier.

type UpdateInstanceRequest 

type UpdateInstanceRequest struct {
	ID                   string             `json:"id"`
	DisplayName          *string            `json:"display_name,omitempty"`
	DMPolicy             *BridgeDMPolicy    `json:"dm_policy,omitempty"`
	RoutingPolicy        *RoutingPolicy     `json:"routing_policy,omitempty"`
	ProviderConfig       *json.RawMessage   `json:"provider_config,omitempty"`
	DeliveryDefaults     *json.RawMessage   `json:"delivery_defaults,omitempty"`
	NotificationSuppress *bool              `json:"notification_suppress,omitempty"`
	Degradation          *BridgeDegradation `json:"degradation,omitempty"`
	ClearDegradation     bool               `json:"clear_degradation,omitempty"`
	UpdatedAt            time.Time          `json:"updated_at"`
}

UpdateInstanceRequest captures one mutation of bridge-instance fields that do not change the lifecycle state machine.

func (UpdateInstanceRequest) Validate 

func (r UpdateInstanceRequest) Validate() error

Validate reports whether the request contains at least one mutable field and each supplied value is internally consistent.

type UpdateInstanceStateRequest 

type UpdateInstanceStateRequest struct {
	ID               string             `json:"id"`
	Enabled          bool               `json:"enabled"`
	Status           BridgeStatus       `json:"status"`
	Degradation      *BridgeDegradation `json:"degradation,omitempty"`
	ClearDegradation bool               `json:"clear_degradation,omitempty"`
	UpdatedAt        time.Time          `json:"updated_at"`
}

UpdateInstanceStateRequest captures one daemon-owned lifecycle transition.

func (UpdateInstanceStateRequest) Validate 

func (r UpdateInstanceStateRequest) Validate() error

Validate reports whether the request contains the fields needed for a lifecycle update.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.