brain

Documentation

Overview

Package brain is the orchestration loop (the plan's component 3): a stateless harness that claims model_turn work, replays the session's event log into a provider request, streams the model's turn back into Anthropic-native events, and drives the session state machine at turn end. It never runs tools in-process — a tool call is an emitted intent event, and the turn resumes when the matching result event lands (a fresh model_turn item enqueued by the control plane). Any brain can pick up any turn: all durable state is the event log.

Index

• Constants
• type Brain
  • func New(pool *pgxpool.Pool, registry *provider.Registry, blobs blob.Store, cfg Config) *Brain
  • func (b *Brain) Run(ctx context.Context) error
  • func (b *Brain) RunOnce(ctx context.Context) (found bool, err error)
• type Config

Constants

const MetricFileResolveMisses = "files.resolve.misses"

MetricFileResolveMisses counts mounted-file references the brain could not resolve to filename/size at injection time — a dangling mount (its file row gone, plan decision 2) or a transient store error. The mounted-files twin of MetricSkillResolveMisses; exported so the telemetry test can assert the name.

const MetricSkillResolveMisses = "skills.resolve.misses"

MetricSkillResolveMisses counts skill references the brain could not resolve to name/description at Level-1 injection time — a dangling id or version (surfaced late-bound, plan design decision 7) or a transient store error. Exported so the telemetry contract test can assert the exact name.

const MetricTimeToFirstToken = "model.time_to_first_token"

MetricTimeToFirstToken is the time-to-first-token histogram: the clock starts when the brain claims the model turn — replay and request assembly are latency the user feels — and stops at the first content the model streams. It is the brain's own metric, not a gen_ai.* one, because the interval it measures spans more than the provider call. Exported so the telemetry contract test can assert this exact name reaches an OTLP collector.

Types

type Brain

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

Brain runs model turns. All instances are interchangeable ("cattle"): a crashed brain's lease expires and any other replays the session.

func New

func New(pool *pgxpool.Pool, registry *provider.Registry, blobs blob.Store, cfg Config) *Brain

func (*Brain) Run

func (b *Brain) Run(ctx context.Context) error

Run claims and executes turns until the context ends. Infra errors are logged and retried — the turn's lease expires and is reclaimed.

func (*Brain) RunOnce

func (b *Brain) RunOnce(ctx context.Context) (found bool, err error)

RunOnce claims at most one model_turn and runs it to completion, reporting whether there was work.

The claimed turn runs under a model_turn consumer span — the brain's counterpart of the executor's tool_exec span and the BYOC worker's, the same two work-queue claimants. It opens on the claimed item and closes on its fate because the nested model_request span can carry neither half of a turn fault. Half the faults happen before that span exists at all — claimLiveSession, the reclaim-recovery append, replay, request assembly, provider resolution, which reach failTurn with a nil span. For the rest, runTurn hands back an error and nothing else: sctx never leaves it, and Finish has closed the span before the error arrives here. Unlike a tool_exec item there is no enqueuing trace to continue — queue.Enqueue deliberately stores none on a model_turn — so this span roots the turn's trace, and the tool_exec items the turn enqueues carry its model_request onward as their parent.

type Config

type Config struct {
	// LeaseTTL is the work-item lease; the lease keeper re-extends it at
	// TTL/3 for as long as the turn is streaming.
	LeaseTTL time.Duration
	// PollInterval is the idle wait between empty queue checks.
	PollInterval time.Duration
}

Config sizes the loop.