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 ¶
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") // ErrInvalidOptions reports an unusable bus configuration. ErrInvalidOptions = errors.New("invalid event bus options") )
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 ¶
IsReserved reports a type in one of Peen's own namespaces.
func ValidateExternalType ¶
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 ¶
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 ¶
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 (*Bus) Drain ¶
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 ¶
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 ¶
Pending reports how many events are waiting for one session without consuming them.
func (*Bus) Publish ¶
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.
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 ¶
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 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" )