agent

Documentation

Overview

Package agent implements the turn loop: one live turn per session, mid-turn steering for overflow messages, bounded worker concurrency, and a system prompt assembled from identity, workspace bootstrap files, drop-in instructions, the skills catalog, and smrti memory recall.

Index

• type Activity
• type ChatProvider
• type ContextBuilder
  • func NewContextBuilder(cfg *config.Config, loader *skills.Loader, ambient *memory.Ambient) *ContextBuilder
  • func (cb *ContextBuilder) SystemPrompt(ctx context.Context, history []provider.Message, current string) string
• type Loop
  • func NewLoop(cfg *config.Config, b *bus.MessageBus, chat ChatProvider, ...) *Loop
  • func (l *Loop) LastChannel() (channel, chatID string, ok bool)
  • func (l *Loop) OnActivity(fn func(Activity))
  • func (l *Loop) ProcessDirect(ctx context.Context, content, sessionKey string) (string, error)
  • func (l *Loop) ProcessEphemeral(ctx context.Context, content string) (string, error)
  • func (l *Loop) Run(ctx context.Context)
  • func (l *Loop) WaitBackground(timeout time.Duration)
• type Phase

Types

type Activity

type Activity struct {
	SessionKey string
	Phase      Phase
	Detail     string
}

Activity is one phase change on one session.

type ChatProvider

type ChatProvider interface {
	Chat(ctx context.Context, req *provider.Request) (*provider.Response, error)
}

ChatProvider is what the loop needs from the provider layer (satisfied by *provider.Chain; tests use scripted fakes).

type ContextBuilder

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

ContextBuilder assembles the system prompt. The static portion (identity, bootstrap files, instructions, skill catalog) is cached and invalidated by file mtimes; the memory portion is recalled fresh every turn.

func NewContextBuilder

func NewContextBuilder(cfg *config.Config, loader *skills.Loader, ambient *memory.Ambient) *ContextBuilder

func (*ContextBuilder) SystemPrompt

func (cb *ContextBuilder) SystemPrompt(ctx context.Context, history []provider.Message, current string) string

SystemPrompt builds the full prompt for one turn.

type Loop

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

func NewLoop

func NewLoop(cfg *config.Config, b *bus.MessageBus, chat ChatProvider, registry *tools.Registry,
	sessions *session.Store, builder *ContextBuilder, ambient *memory.Ambient) *Loop

func (*Loop) LastChannel

func (l *Loop) LastChannel() (channel, chatID string, ok bool)

LastChannel returns the most recent external channel/chat, for heartbeat and cron delivery. ok is false before any external message arrived.

func (*Loop) OnActivity

func (l *Loop) OnActivity(fn func(Activity))

OnActivity installs the activity watcher, replacing any previous one and clearing it when fn is nil. It is called from turn goroutines, so it must not block and must not call back into the loop.

func (*Loop) ProcessDirect

func (l *Loop) ProcessDirect(ctx context.Context, content, sessionKey string) (string, error)

ProcessDirect runs a synchronous turn outside the bus (CLI one-shot, cron, delegated jobs). It honors the one-live-turn-per-session invariant: if the session is busy (e.g. an overlapping cron firing), it waits for the claim instead of interleaving histories.

func (*Loop) ProcessEphemeral

func (l *Loop) ProcessEphemeral(ctx context.Context, content string) (string, error)

ProcessEphemeral runs a history-less, memory-less turn (heartbeat).

func (*Loop) Run

func (l *Loop) Run(ctx context.Context)

Run drains the inbound bus until ctx is cancelled. One live turn per session key; overflow becomes steering.

func (*Loop) WaitBackground

func (l *Loop) WaitBackground(timeout time.Duration)

WaitBackground blocks until async work (memory stores, compaction) drains, or the timeout passes. One-shot mode calls this so memory writes are not lost to process exit.

type Phase

type Phase string

Phase is what a turn is busy with at a given moment. Front-ends map these onto whatever they draw while the user waits.

const (
	PhaseContext    Phase = "context"    // assembling the prompt: skills, memory recall
	PhaseThinking   Phase = "thinking"   // waiting on the provider
	PhaseTool       Phase = "tool"       // running a tool call (Detail is its name)
	PhaseCompacting Phase = "compacting" // summarizing history after a context overflow
	PhaseSteering   Phase = "steering"   // folding in a message that arrived mid-turn
	PhaseDone       Phase = "done"       // the turn ended, with a reply or an error
)