notification

package
v0.19.9 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package notification owns the canonical local notification projection, personal project registry, independent delivery leases, and trusted route ledger. Native adapters only render this protocol.

Index

Constants

View Source 
const SchemaVersion = 1

SchemaVersion is the notification adapter protocol version.

Variables

View Source 
var (
	// ErrInvalidConsumer rejects unsafe or unbounded adapter identities.
	ErrInvalidConsumer = errors.New("invalid notification consumer")
	// ErrInvalidLimit rejects unbounded adapter claims.
	ErrInvalidLimit = errors.New("notification claim limit must be between 1 and 50")
	// ErrDeliveryStateMismatch rejects state owned by another consumer/channel.
	ErrDeliveryStateMismatch = errors.New("notification delivery state identity mismatch")
	// ErrLeaseNotFound rejects unknown or expired lease identities.
	ErrLeaseNotFound = errors.New("notification lease not found")
	// ErrEntryNotLeased rejects acknowledgement outside the leased batch.
	ErrEntryNotLeased = errors.New("notification entry was not leased")
)
View Source 
var (
	// ErrComponentsUnavailable means no platform component manager was wired.
	ErrComponentsUnavailable = errors.New("notification components unavailable")
	// ErrInvalidAck rejects incomplete acknowledgement requests.
	ErrInvalidAck = errors.New("notification ack requires lease and entries")
	// ErrUninstallAffectsProjects requires confirmation for global impact.
	ErrUninstallAffectsProjects = errors.New("notification uninstall affects other projects")
)
View Source 
var (
	// ErrProjectNotFound means the requested registration does not exist.
	ErrProjectNotFound = errors.New("notification project not found")
	// ErrInvalidChannel rejects an unknown presentation channel.
	ErrInvalidChannel = errors.New("invalid notification channel")
	// ErrInvalidPreference rejects ambiguous setup-offer transitions.
	ErrInvalidPreference = errors.New("invalid notification preference")
)
View Source 
var ErrChannelNotEnrolled = fmt.Errorf("notification channel not enrolled")

ErrChannelNotEnrolled rejects claims for a project-disabled channel.

View Source 
var ErrRouteNotFound = errors.New("notification route not found")

ErrRouteNotFound rejects unknown or malformed trusted-route tokens.

Functions

func ValidChannel 

func ValidChannel(channel Channel) bool

ValidChannel reports whether channel is implemented by P49.

Types

type AckRequest 

type AckRequest struct {
	LeaseToken string
	EntryIDs   []string
}

AckRequest acknowledges accepted entries under one lease.

type AckResult 

type AckResult struct {
	Acked        []string `json:"acked"`
	AlreadyAcked []string `json:"already_acked"`
}

AckResult distinguishes newly and previously accepted entries.

type Channel 

type Channel string

Channel identifies a native presentation surface. 

const (
	// ChannelMacOS is the signed native macOS application.
	ChannelMacOS Channel = "macos"
	// ChannelVSCode is the local VS Code UI extension.
	ChannelVSCode Channel = "vscode"
)

type ChannelResult 

type ChannelResult struct {
	Channel Channel `json:"channel"`
	Status  string  `json:"status"`
	Reason  string  `json:"reason,omitempty"`
}

ChannelResult reports one component lifecycle outcome.

type ClaimRequest 

type ClaimRequest struct {
	Channel   Channel
	Consumer  string
	ProjectID string
	Limit     int
}

ClaimRequest is the adapter-only transition delivery request.

type ClaimResult 

type ClaimResult struct {
	Lease   *Lease  `json:"lease"`
	Entries []Entry `json:"entries"`
}

ClaimResult contains an optional lease and its bounded entries.

type ComponentHealth 

type ComponentHealth struct {
	Channel    Channel `json:"channel"`
	Available  bool    `json:"available"`
	Installed  bool    `json:"installed"`
	Version    string  `json:"version,omitempty"`
	Protocol   int     `json:"protocol,omitempty"`
	Profile    string  `json:"profile,omitempty"`
	CodePath   string  `json:"code_path,omitempty"`
	Permission string  `json:"permission,omitempty"`
	LoginItem  string  `json:"login_item,omitempty"`
	Handshake  string  `json:"handshake,omitempty"`
	Enabled    *bool   `json:"enabled,omitempty"`
	Detail     string  `json:"detail,omitempty"`
}

ComponentHealth is additive detail behind the stable installed-channel summary. Platform probes may leave fields empty when a bounded status read cannot determine them without launching UI or prompting.

type ComponentManager 

type ComponentManager interface {
	ComponentProbe
	Install(context.Context, Channel, ComponentOptions) (ChannelResult, error)
	Test(context.Context, Channel, Project) (ChannelResult, error)
	Uninstall(context.Context, Channel, ComponentOptions, bool) (ChannelResult, error)
}

ComponentManager owns platform application state. It never owns project semantics or delivery cursors.

type ComponentOptions 

type ComponentOptions struct {
	Profile  string
	CodePath string
}

ComponentOptions identifies an exact VS Code installation/profile.

type ComponentProbe 

type ComponentProbe interface {
	Available(context.Context) ([]Channel, error)
	Installed(context.Context) ([]Channel, error)
}

ComponentProbe reports basic platform availability and installation state.

type Controller 

type Controller struct {
	Service    *Service
	Components ComponentManager
	OpenRoute  RouteOpener
}

Controller is the application service behind the thin CLI family.

func (*Controller) Ack 

func (c *Controller) Ack(ctx context.Context, request AckRequest) (AckResult, error)

Ack accepts only entries covered by a live or completed lease.

func (*Controller) Claim 

func (c *Controller) Claim(ctx context.Context, request ClaimRequest) (ClaimResult, error)

Claim leases one adapter consumer's bounded transition batch.

func (*Controller) Install 

func (c *Controller) Install(ctx context.Context, request InstallRequest) (OperationResult, error)

Install prepares adapter config, repairs components, then enrolls only channels whose component mutation succeeded. A failed install therefore cannot leave registry truth claiming that a channel is enabled.

func (*Controller) Open 

func (c *Controller) Open(ctx context.Context, request OpenRequest) (OpenResult, error)

Open resolves a core-minted route and invokes the local HTML opener.

func (*Controller) Preference 

func (c *Controller) Preference(ctx context.Context, request PreferenceRequest) (PreferenceResult, error)

Preference applies one validated setup-offer transition.

func (*Controller) Status 

func (c *Controller) Status(ctx context.Context, request StatusRequest) (Status, error)

Status returns project signals and bounded platform component health.

func (*Controller) Test 

func (c *Controller) Test(ctx context.Context, request TestRequest) (OperationResult, error)

Test sends a synthetic readiness request without advancing delivery state.

func (*Controller) Uninstall 

func (c *Controller) Uninstall(ctx context.Context, request UninstallRequest) (OperationResult, error)

Uninstall removes components and optionally purges selected machine state.

type DeliveryStore 

type DeliveryStore struct {
	Root     string
	Now      func() time.Time
	LeaseTTL time.Duration
	Mint     func() (string, error)
}

DeliveryStore persists channel/consumer-specific at-least-once state.

func NewDeliveryStore 

func NewDeliveryStore(root string, now func() time.Time) *DeliveryStore

NewDeliveryStore constructs a delivery store rooted in disposable cache.

func (*DeliveryStore) Ack 

func (s *DeliveryStore) Ack(ctx context.Context, token string, entryIDs []string) (AckResult, error)

Ack idempotently accepts only entries owned by the supplied lease.

func (*DeliveryStore) Claim 

func (s *DeliveryStore) Claim(ctx context.Context, channel Channel, consumer, projectID string, current []Entry, limit int) (ClaimResult, error)

Claim leases a bounded batch after establishing a no-history baseline.

func (*DeliveryStore) PurgeChannels 

func (s *DeliveryStore) PurgeChannels(channels []Channel) error

PurgeChannels removes only disposable delivery state for explicitly selected channels. The fixed channel directory is derived after validation; project truth and the human inbox cursor are outside this root and cannot be touched.

type DetailedComponentProbe 

type DetailedComponentProbe interface {
	Health(context.Context) ([]ComponentHealth, error)
}

DetailedComponentProbe reports bounded platform-specific health.

type Entry 

type Entry struct {
	SchemaVersion  int       `json:"schema_version"`
	EntryID        string    `json:"entry_id"`
	ProjectID      string    `json:"project_id"`
	SpaceID        string    `json:"space_id,omitempty"`
	ArtifactID     string    `json:"artifact_id,omitempty"`
	EventID        string    `json:"event_id,omitempty"`
	Kind           string    `json:"kind"`
	Severity       string    `json:"severity"`
	Title          string    `json:"title"`
	Summary        string    `json:"summary"`
	OccurredAt     time.Time `json:"occurred_at"`
	SourceRevision string    `json:"source_revision,omitempty"`
	CoalesceKey    string    `json:"coalesce_key"`
	RouteToken     string    `json:"route_token"`
}

Entry is one sanitized, qualified, lease-delivered transition signal.

type InstallRequest 

type InstallRequest struct {
	Root     string
	Channels []Channel
	All      bool
	Profile  string
	CodePath string
}

InstallRequest enrolls a project and installs selected components.

type Lease 

type Lease struct {
	Token      string    `json:"token"`
	ConsumerID string    `json:"consumer_id"`
	Channel    Channel   `json:"channel"`
	ProjectID  string    `json:"project_id"`
	ExpiresAt  time.Time `json:"expires_at"`
}

Lease grants one consumer temporary ownership of a project batch.

type Level 

type Level struct {
	Line       string `json:"line"`
	New        int    `json:"new"`
	Urgent     int    `json:"urgent"`
	Stale      int    `json:"stale"`
	Update     string `json:"update"`
	Severity   string `json:"severity"`
	Quiet      bool   `json:"quiet"`
	RouteToken string `json:"route_token,omitempty"`
}

Level is the persistent aggregate status rendered by every channel.

type Offer 

type Offer struct {
	State       string     `json:"state"`
	Scope       string     `json:"scope"`
	RemindAfter *time.Time `json:"remind_after"`
}

Offer is the effective notification setup prompt state.

type OpenRequest 

type OpenRequest struct {
	RouteToken string
}

OpenRequest carries a core-minted trusted route token.

type OpenResult 

type OpenResult struct {
	ProjectID  string `json:"project_id"`
	Root       string `json:"root"`
	SpaceID    string `json:"space_id,omitempty"`
	ArtifactID string `json:"artifact_id,omitempty"`
	Kind       string `json:"kind"`
}

OpenResult reports the project-local destination opened for a route.

type OperationResult 

type OperationResult struct {
	Project *Project        `json:"project"`
	Results []ChannelResult `json:"results"`
	Failed  bool            `json:"failed"`
}

OperationResult aggregates deterministic per-channel lifecycle outcomes.

type PreferenceRequest 

type PreferenceRequest struct {
	Root         string
	RemindInDays int
	Never        bool
	Reset        bool
	Global       bool
}

PreferenceRequest changes project or global setup-offer policy.

type PreferenceResult 

type PreferenceResult struct {
	Project *Project `json:"project"`
	Offer   Offer    `json:"offer"`
}

PreferenceResult returns the effective setup-offer state.

type Project 

type Project struct {
	ID       string    `json:"id"`
	Root     string    `json:"root"`
	Channels []Channel `json:"channels"`
	LastSeen time.Time `json:"last_seen"`
}

Project is one stable machine-local notification registration.

type ProjectConfigurator 

type ProjectConfigurator interface {
	Configure(context.Context, []Project) error
}

ProjectConfigurator refreshes adapter-owned project configuration.

type ProjectSource 

type ProjectSource interface {
	NotificationSnapshot(context.Context) (cache.NotificationSnapshot, error)
}

ProjectSource is the consumer-side interface implemented by cache.Store.

type Projection 

type Projection struct {
	Level   Level
	Entries []Entry
	Routes  []Route
}

Projection is the canonical level, transition-entry, and route snapshot.

func BuildProjection 

func BuildProjection(ctx context.Context, project Project, source ProjectSource, now time.Time) (Projection, error)

BuildProjection derives sanitized notification state from cursor-neutral cache truth.

type Registry 

type Registry struct {
	Path    string
	Now     func() time.Time
	Entropy func() (string, error)
}

Registry owns machine-local project enrollment and setup preferences.

func NewRegistry 

func NewRegistry(path string, now func() time.Time) *Registry

NewRegistry constructs a registry backed by typed machine config.

func (*Registry) Enroll 

func (r *Registry) Enroll(root string, channels []Channel) (Project, error)

Enroll idempotently enables selected channels for a project.

func (*Registry) FindByID 

func (r *Registry) FindByID(id string) (Project, error)

FindByID resolves one registered project.

func (*Registry) FindByRoot 

func (r *Registry) FindByRoot(root string) (Project, error)

FindByRoot resolves one canonical registered project root.

func (*Registry) ForgetComponent 

func (r *Registry) ForgetComponent(channel Channel, profile, codePath string) error

ForgetComponent drops only the matching ownership marker; application uninstall and project enrollment remain separate lifecycle operations.

func (*Registry) Offer 

func (r *Registry) Offer(project Project, available []Channel) (Offer, error)

Offer computes effective prompt state using project-before-global precedence.

func (*Registry) Preference 

func (r *Registry) Preference(root string, remindInDays int, never, reset, global bool) error

Preference applies one project or global setup-offer policy change.

func (*Registry) Projects 

func (r *Registry) Projects() ([]Project, error)

Projects returns all registrations in stable ID order.

func (*Registry) PurgeChannels 

func (r *Registry) PurgeChannels(channels []Channel) error

PurgeChannels deletes the selected notification registry state after an explicitly confirmed --purge. Purging both channels resets the whole P49 config while preserving unrelated machine defaults and credentials.

func (*Registry) Register 

func (r *Registry) Register(root string) (Project, bool, error)

Register idempotently assigns a stable machine-local ID to a project root.

func (*Registry) RememberComponent 

func (r *Registry) RememberComponent(channel Channel, profile, codePath, productVersion string) error

RememberComponent records a successfully installed a2a-managed companion. The channel/profile/code-path tuple is idempotent and machine-local.

type Route 

type Route struct {
	Token      string    `json:"token"`
	ProjectID  string    `json:"project_id"`
	SpaceID    string    `json:"space_id,omitempty"`
	ArtifactID string    `json:"artifact_id,omitempty"`
	Kind       string    `json:"kind"`
	CreatedAt  time.Time `json:"created_at"`
}

Route is a core-minted local HTML destination.

type RouteOpener 

type RouteOpener func(context.Context, Route, Project) error

RouteOpener opens a previously resolved trusted local route.

type Service 

type Service struct {
	Registry *Registry
	Delivery *DeliveryStore
	Sources  SourceFactory
	Probe    ComponentProbe
}

Service composes registry, projection, delivery, routes, and component health.

func (*Service) Ack 

func (s *Service) Ack(ctx context.Context, token string, entries []string) (AckResult, error)

Ack advances only the delivery lease identified by token.

func (*Service) Claim 

func (s *Service) Claim(ctx context.Context, channel Channel, consumer, projectID string, limit int) (ClaimResult, error)

Claim projects and leases transition entries for one enrolled consumer.

func (*Service) ResolveRoute 

func (s *Service) ResolveRoute(token string) (Route, Project, error)

ResolveRoute resolves a ledger-backed token and its registered project.

func (*Service) Status 

func (s *Service) Status(ctx context.Context, root string, probe bool) (Status, error)

Status returns a non-consuming project snapshot and component health.

type SourceFactory 

type SourceFactory func(project Project) (ProjectSource, error)

SourceFactory resolves cursor-neutral cache truth for one project.

type Status 

type Status struct {
	AvailableChannels []Channel         `json:"available_channels"`
	InstalledChannels []Channel         `json:"installed_channels"`
	Project           *Project          `json:"project"`
	Level             Level             `json:"level"`
	Offer             Offer             `json:"offer"`
	Components        []ComponentHealth `json:"components"`
}

Status is the additive JSON contract shared by skill and adapters.

type StatusRequest 

type StatusRequest struct {
	Root    string
	Channel Channel
	Probe   bool
}

StatusRequest selects one project and optional channel health view.

type TestRequest 

type TestRequest struct {
	Root     string
	Channels []Channel
	All      bool
}

TestRequest asks selected adapters for a synthetic readiness proof.

type UninstallRequest 

type UninstallRequest struct {
	Root     string
	Channels []Channel
	All      bool
	Profile  string
	CodePath string
	Purge    bool
	Yes      bool
}

UninstallRequest removes selected managed components.

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.