event

Documentation

Overview

Package event is the shared vocabulary between the core and every client.

It imports nothing outside the standard library, and a test enforces that, because a shared vocabulary with dependencies is a coupling leak.

Versioning discipline: SchemaMajor bumps only when an existing field is renamed, retyped, or removed, or when an event type changes meaning. Adding a new event type or a new optional field is not a major bump. The golden schema test pins every payload's JSON keys, so any change here is a visible, deliberate diff in review.

Index

• Constants
• type AntSpawned
• type Consequence
• type ErrorInfo
• type Event
  • func New(t Type, session, turn string, payload any) (Event, error)
  • func (e Event) Decode(dst any) error
• type Hello
• type LedgerTurn
• type Log
• type MemoryFolded
• type PermissionRequested
• type PermissionResolved
• type RouteDecided
• type SessionCreated
• type SessionForked
• type SessionUpdated
• type TextDelta
• type TextEnd
• type ThinkingDelta
• type ThinkingEnd
• type ToolEnd
• type ToolProgress
• type ToolStart
• type TurnFinished
• type TurnStarted
• type Type

Constants

const SchemaMajor = 1

SchemaMajor is the wire schema major version carried on every event.

Types

type AntSpawned

type AntSpawned struct {
	ID   string `json:"id"`
	Card string `json:"card"`
}

AntSpawned is defined for the wire schema and unused until M3.

type Consequence

type Consequence struct {
	Kind    string `json:"kind"` // diff, command, url, json
	Content string `json:"content"`
}

Consequence is the core-rendered preview of what a tool call would do. Every client shows these same bytes; no client re-derives them.

type ErrorInfo

type ErrorInfo struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable"`
	Ant       string `json:"ant,omitempty"`
	Cause     string `json:"cause,omitempty"`
}

ErrorInfo is a client-facing failure with a taxonomy code. A model-correctable mistake is a tool result, never one of these. Code is core's ErrorKind on the wire; Retryable tells a client whether a retry could help; Cause is an unwrapped underlying detail (doc 01 section 10).

type Event

type Event struct {
	V       int             `json:"v"`
	Seq     uint64          `json:"seq"`
	Type    Type            `json:"type"`
	Session string          `json:"session,omitempty"`
	Turn    string          `json:"turn,omitempty"`
	Time    time.Time       `json:"time"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

Event is the envelope every payload travels in. Seq is assigned by the journal's single writer and is total and gap-free within a colony run, which is what makes resume-from-cursor possible for every client.

func New

func New(t Type, session, turn string, payload any) (Event, error)

New wraps a payload in an envelope. Seq stays zero until the journal assigns it; a zero Seq means the event has not been journaled.

func (Event) Decode

func (e Event) Decode(dst any) error

Decode unmarshals the payload into dst.

type Hello

type Hello struct {
	Schema int    `json:"schema"`
	Cursor uint64 `json:"cursor"`
	Server string `json:"server"`
}

Hello is the first event on any subscription. It carries the schema version and the resume cursor so a client knows where the stream starts.

type LedgerTurn

type LedgerTurn struct {
	Turn       string  `json:"turn"`
	Model      string  `json:"model"`
	Input      int64   `json:"input"`
	Output     int64   `json:"output"`
	CacheRead  int64   `json:"cache_read"`
	CacheWrite int64   `json:"cache_write"`
	CostUSD    float64 `json:"cost_usd"`
	CacheRate  float64 `json:"cache_rate"`
}

LedgerTurn is the per-turn meter: tokens, dollars, and cache hit rate.

type Log

type Log struct {
	Level string `json:"level"`
	Text  string `json:"text"`
}

Log is a diagnostic line a client may show in a debug surface.

type MemoryFolded

type MemoryFolded struct {
	Namespace string `json:"namespace"`
	Merged    int    `json:"merged"`
	Archived  int    `json:"archived"`
}

MemoryFolded is defined for the wire schema and unused until M2.

type PermissionRequested

type PermissionRequested struct {
	ID          string      `json:"id"`
	Call        string      `json:"call"`
	Tool        string      `json:"tool"`
	Consequence Consequence `json:"consequence"`
	Suggestions []string    `json:"suggestions,omitempty"`
	Mode        string      `json:"mode,omitempty"`
	Reason      string      `json:"reason,omitempty"`
}

PermissionRequested asks a client to resolve a permission decision. Mode is the session mode in effect, so the client's full-auto indicator and the core can never disagree; Reason is the prose why, naming the offending subcommand for a compound sh call.

type PermissionResolved

type PermissionResolved struct {
	ID       string `json:"id"`
	Behavior string `json:"behavior"` // allow, deny
	Stage    string `json:"stage"`
	Rule     string `json:"rule,omitempty"`
	Kind     string `json:"kind,omitempty"`
	Reason   string `json:"reason,omitempty"`
}

PermissionResolved records how a permission decision landed and why. Kind names the machinery that decided (rule, safety, headless, ...), so a client can tell a headless auto-deny from a user's no without parsing the prose.

type RouteDecided

type RouteDecided struct {
	Task string `json:"task"`
	Ant  string `json:"ant"`
	Why  string `json:"why"`
}

RouteDecided is defined for the wire schema and unused until M3.

type SessionCreated

type SessionCreated struct {
	ID     string `json:"id"`
	Title  string `json:"title,omitempty"`
	Parent string `json:"parent,omitempty"`
	Root   string `json:"root"`
}

SessionCreated announces a new session.

type SessionForked

type SessionForked struct {
	ID     string `json:"id"`
	Parent string `json:"parent"`
	AtTurn string `json:"at_turn"`
}

SessionForked announces a child session split from a parent at a turn.

type SessionUpdated

type SessionUpdated struct {
	ID    string `json:"id"`
	Title string `json:"title,omitempty"`
}

SessionUpdated carries a changed session attribute, such as a title.

type TextDelta

type TextDelta struct {
	Part int    `json:"part"`
	Text string `json:"text"`
}

TextDelta streams assistant text for one part.

type TextEnd

type TextEnd struct {
	Part int `json:"part"`
}

TextEnd closes a streaming text part.

type ThinkingDelta

type ThinkingDelta struct {
	Part int    `json:"part"`
	Text string `json:"text"`
}

ThinkingDelta streams reasoning text for one part.

type ThinkingEnd

type ThinkingEnd struct {
	Part       int   `json:"part"`
	DurationMS int64 `json:"duration_ms"`
}

ThinkingEnd closes a reasoning part and records its wall time.

type ToolEnd

type ToolEnd struct {
	Part    int    `json:"part"`
	Call    string `json:"call"`
	Tool    string `json:"tool"`
	OK      bool   `json:"ok"`
	Display string `json:"display"`
	Spilled string `json:"spilled,omitempty"`
}

ToolEnd carries a finished tool result. Display is the human-facing render; the model-facing serialization never appears in an event.

type ToolProgress

type ToolProgress struct {
	Part int    `json:"part"`
	Call string `json:"call"`
	Text string `json:"text"`
}

ToolProgress streams incremental tool output, such as sh stdout.

type ToolStart

type ToolStart struct {
	Part  int    `json:"part"`
	Call  string `json:"call"`
	Tool  string `json:"tool"`
	Input string `json:"input"`
}

ToolStart announces a tool call the model asked for.

type TurnFinished

type TurnFinished struct {
	ID     string `json:"id"`
	Reason string `json:"reason"`
	Error  string `json:"error,omitempty"`
}

TurnFinished marks the end of a turn with its terminal reason.

type TurnStarted

type TurnStarted struct {
	ID     string `json:"id"`
	Ant    string `json:"ant"`
	Prompt string `json:"prompt"`
}

TurnStarted marks the start of a turn and names the ant running it.

type Type

type Type string

Type names an event. Types are dotted, lowercase, and stable.

const (
	TypeHello Type = "hello"

	TypeSessionCreated Type = "session.created"
	TypeSessionUpdated Type = "session.updated"
	TypeSessionForked  Type = "session.forked"

	TypeTurnStarted  Type = "turn.started"
	TypeTurnFinished Type = "turn.finished"

	TypeTextDelta     Type = "part.text.delta"
	TypeTextEnd       Type = "part.text.end"
	TypeThinkingDelta Type = "part.thinking.delta"
	TypeThinkingEnd   Type = "part.thinking.end"
	TypeToolStart     Type = "part.tool.start"
	TypeToolProgress  Type = "part.tool.progress"
	TypeToolEnd       Type = "part.tool.end"

	TypePermissionRequested Type = "permission.requested"
	TypePermissionResolved  Type = "permission.resolved"

	TypeLedgerTurn Type = "ledger.turn"
	TypeLog        Type = "log"
	TypeError      Type = "error"

	// Defined, never emitted in M0.
	TypeAntSpawned   Type = "ant.spawned"
	TypeRouteDecided Type = "route.decided"
	TypeMemoryFolded Type = "memory.folded"
)

The M0 event types. The colony and memory types at the bottom are defined but never emitted in M0; the features that produce them arrive with M2 and M3, and the seam-without-the-feature rule applies to the wire schema too.