events

package
v0.14.2 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package events carries typed notices about things that happened which the agent did not directly ask about: a process job ended, a child agent finished, or something outside Peen reported a change.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidType reports a type that is not lowercase dotted segments.
	ErrInvalidType = errors.New("invalid event type")
	// ErrReservedType reports an outside caller using a Peen-owned prefix.
	ErrReservedType = errors.New("event type prefix is reserved")
	// ErrInvalidDelivery reports a delivery mode Peen does not implement.
	ErrInvalidDelivery = errors.New("invalid event delivery mode")
	// ErrInvalidData reports event data that cannot round-trip through Peen's
	// object-shaped durable and HTTP contracts.
	ErrInvalidData = errors.New("invalid event data")
	// ErrInvalidOptions reports an unusable bus configuration.
	ErrInvalidOptions = errors.New("invalid event bus options")
)
View Source
var ReservedPrefixes = []string{"job.", "agent."}

ReservedPrefixes are the type namespaces only Peen's own producers may publish. An outside caller posting one is rejected so it cannot forge a job or agent event.

Functions

func IsReserved

func IsReserved(eventType Type) bool

IsReserved reports a type in one of Peen's own namespaces.

func ValidateData added in v0.11.0

func ValidateData(data json.RawMessage) error

ValidateData accepts an absent payload or one JSON object. Session notices are exposed through an object-shaped HTTP field, so accepting an array, scalar, or null here would allow a record that durable reads cannot replay.

func ValidateExternalType

func ValidateExternalType(eventType Type) error

ValidateExternalType applies the outside-caller rules: a valid type that is not in a reserved namespace, so a webhook cannot forge a job or agent event.

func ValidateType

func ValidateType(eventType Type) error

ValidateType checks the shape every event type must have: one to eight lowercase dotted segments of letters and digits, starting with a letter. Validation is done by hand rather than with a regular expression so the package needs no compiled package-level state.

Types

type Batch

type Batch struct {
	Notices []Notice
	Dropped int
}

Batch is what one drain returns: the events still pending plus how many were dropped before them, so a reader can tell that its view has a hole.

type Bus

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

Bus is the one path from "something happened" to "the agent knows". It is session-scoped and bounded: publishing never blocks the publisher, because a finishing process must not stall on a session nobody is draining.

func NewBus

func NewBus(options Options) *Bus

NewBus builds a bus with bounded per-session queues.

func (*Bus) Drain

func (b *Bus) Drain(sessionID uuid.UUID) Batch

Drain removes and returns everything pending for one session, plus how many were dropped since the previous drain. This is what a turn calls at a tool boundary to build one coalesced message.

func (*Bus) Peek

func (b *Bus) Peek(sessionID uuid.UUID) Batch

Peek returns what is waiting for one session WITHOUT consuming it, so an operator reading the queue over HTTP does not steal events the agent has not been told about yet. Only Drain consumes.

func (*Bus) Pending

func (b *Bus) Pending(sessionID uuid.UUID) int

Pending reports how many events are waiting for one session without consuming them.

func (*Bus) Prepare added in v0.4.0

func (b *Bus) Prepare(notice Notice) (Notice, error)

Prepare validates and normalizes a notice without making it visible. Callers that need persistence-before-publication use it before their durable write.

func (*Bus) Publish

func (b *Bus) Publish(notice Notice) (Notice, error)

Publish records one event for a session and hands it to any live subscribers. It validates the type but does not apply the reserved-prefix rule, because Peen's own producers publish reserved types through here. The HTTP boundary applies ValidateExternalType before calling this.

A full queue drops its oldest event and counts the drop. A subscriber that is not reading is skipped rather than waited on.

func (*Bus) PublishContext added in v0.4.0

func (b *Bus) PublishContext(_ context.Context, notice Notice) (Notice, error)

PublishContext lets a Bus satisfy Publisher. A Bus has no durable state, so callers that need replay use Runtime's publisher instead.

func (*Bus) Subscribe

func (b *Bus) Subscribe(sessionID uuid.UUID) (<-chan Notice, func())

Subscribe returns a channel of live events for one session and the function that stops the subscription. The returned function is safe to call more than once and closes the channel exactly once.

type Delivery

type Delivery = string

Delivery selects whether an event waits for the next turn or starts one.

const (
	// DeliveryQueue waits for the next tool boundary or turn. The default.
	DeliveryQueue Delivery = "queue"
	// DeliveryWake starts a turn when the session is idle and a handler
	// matches. It degrades to DeliveryQueue when a turn is already running or
	// no handler matches.
	DeliveryWake Delivery = "wake"
)

func ValidateDelivery

func ValidateDelivery(delivery Delivery) (Delivery, error)

ValidateDelivery checks the delivery mode, treating empty as the default.

type Notice

type Notice struct {
	ID        uuid.UUID       `json:"id"`
	SessionID uuid.UUID       `json:"sessionId"`
	Type      Type            `json:"type"`
	Source    string          `json:"source"`
	Summary   string          `json:"summary"`
	Data      json.RawMessage `json:"data,omitempty"`
	Delivery  Delivery        `json:"delivery"`
	CreatedAt time.Time       `json:"createdAt"`
}

Notice is one thing that happened which the session should learn about.

Summary and Data are caller-supplied for externally published events, so both are treated as untrusted input everywhere downstream. They are quoted as data when they reach a model and never merged into a system prompt.

type Options

type Options struct {
	// MaxPendingPerSession bounds undelivered events per session. Over the
	// bound the oldest are dropped and counted.
	MaxPendingPerSession int
	// MaxSummaryBytes bounds the one-line summary a model reads.
	MaxSummaryBytes int
	// MaxDataBytes bounds the structured payload.
	MaxDataBytes int
	// SubscriberBuffer sizes each live subscriber's channel.
	SubscriberBuffer int
	// Metrics records bounded event-drop telemetry. Nil disables observation.
	Metrics *metrics.Metrics
}

Options bounds the bus. Zero fields take the package defaults.

type Publisher added in v0.4.0

type Publisher interface {
	PublishContext(context.Context, Notice) (Notice, error)
}

Publisher publishes one notice with the context that produced it. The runtime implementation persists before it fans out to live subscribers.

type Type

type Type = string

Type names one kind of session event. It is a dotted, lowercase, namespaced name. Peen reserves the job. and agent. prefixes for its own producers; every other prefix belongs to the deployment, so an application is free to publish app.error or ci.failed and have those be first-class.

It is an alias because it carries no behavior and crosses the HTTP and JSON boundaries as a plain string.

const (
	// TypeJobExited reports a process job that ended on its own.
	TypeJobExited Type = "job.exited"
	// TypeJobSignalled reports a process job terminated by a signal.
	TypeJobSignalled Type = "job.signalled"
	// TypeJobFailed reports a process job that could not run.
	TypeJobFailed Type = "job.failed"
	// TypeAgentFinished reports a child agent run that completed.
	TypeAgentFinished Type = "agent.finished"
	// TypeAgentFailed reports a child agent run that failed.
	TypeAgentFailed Type = "agent.failed"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL