1package pubsub
 2
 3import (
 4	"context"
 5	"encoding/json"
 6)
 7
 8const (
 9	CreatedEvent EventType = "created"
10	UpdatedEvent EventType = "updated"
11	DeletedEvent EventType = "deleted"
12)
13
14// PayloadType identifies the type of event payload for discriminated
15// deserialization over JSON.
16type PayloadType = string
17
18const (
19	PayloadTypeLSPEvent               PayloadType = "lsp_event"
20	PayloadTypeMCPEvent               PayloadType = "mcp_event"
21	PayloadTypePermissionRequest      PayloadType = "permission_request"
22	PayloadTypePermissionNotification PayloadType = "permission_notification"
23	PayloadTypeMessage                PayloadType = "message"
24	PayloadTypeSession                PayloadType = "session"
25	PayloadTypeFile                   PayloadType = "file"
26	PayloadTypeAgentEvent             PayloadType = "agent_event"
27	PayloadTypeConfigChanged          PayloadType = "config_changed"
28	PayloadTypeSkillsEvent            PayloadType = "skills_event"
29	PayloadTypeRunComplete            PayloadType = "run_complete"
30)
31
32// Payload wraps a discriminated JSON payload with a type tag.
33type Payload struct {
34	Type    PayloadType     `json:"type"`
35	Payload json.RawMessage `json:"payload"`
36}
37
38// Subscriber can subscribe to events of type T.
39type Subscriber[T any] interface {
40	Subscribe(context.Context) <-chan Event[T]
41}
42
43type (
44	// EventType identifies the type of event.
45	EventType string
46
47	// Event represents an event in the lifecycle of a resource.
48	Event[T any] struct {
49		Type    EventType `json:"type"`
50		Payload T         `json:"payload"`
51	}
52
53	// Publisher can publish events of type T.
54	//
55	// Publish is best-effort and lossy under back-pressure;
56	// PublishMustDeliver applies the bounded-blocking semantics used
57	// for terminal events that must reach subscribers (finish, tool
58	// result, error, cancel, RunComplete). See [Broker.Publish] and
59	// [Broker.PublishMustDeliver].
60	Publisher[T any] interface {
61		Publish(EventType, T)
62		PublishMustDeliver(context.Context, EventType, T)
63	}
64)