channel

type AgentFunc ¶

type AgentFunc func() (*agent.Agent, error)

AgentFunc returns a ready base agent, minus its gate. It runs once per message so the system prompt reflects the current memory index.

type Attachment ¶

type Attachment struct {
	Name    string // suggested filename, like "chart.png"
	Mime    string // media type, like "image/png"
	Data    []byte // the file bytes
	Caption string // optional note to show alongside it
}

Attachment is a file the agent made for the user: an image, a chart, a screenshot, a document. It rides the send_file tool back out.

type Caps ¶

type Caps struct {
	Media   bool // can carry images in and out
	Buttons bool // can render tap-to-approve controls
	Stream  bool // can update a message as text streams
}

Caps declares what a channel can do, so the router can degrade gracefully: no Buttons means approvals fall back to a yes/no text reply, no Stream means the reply is sent once at the end instead of incrementally.

type Channel ¶

type Channel interface {
	Name() string
	Caps() Caps
	Run(ctx context.Context, h Handler) error
}

Channel receives messages until its context is cancelled.

func Open(name string, s Settings) (Channel, error)

type Clip ¶

type Clip struct {
	Data []byte // the raw audio
	Ext  string // container extension, like ".ogg" or ".m4a"
}

Clip is a speech attachment waiting to be transcribed. The router turns it into text before the turn runs; channels only have to carry the bytes and the container extension.

func DecodeAudioDataURL(s string) (Clip, error)

func FetchAudio(ctx context.Context, client *http.Client, url string, header http.Header) (Clip, error)

func ReadAudioFile(path string) (Clip, error)

type Driver ¶ added in v0.2.1

type Driver interface {
	Open(Settings) (Channel, error)
}

Driver opens a channel from its settings. A driver package registers itself under a name in init(), so the core reaches a channel by name and never imports the channel's package. This mirrors how a database driver owns its own connection string: the standard library dispatches by name and stays ignorant of any one driver's dialect.

Open returns (nil, nil) to mean "configured but off", which lets a driver treat an empty or disabled block as a no-op rather than an error.

type Exchange ¶

type Exchange struct {
	Channel  string
	In       Inbound
	Reply    Reply
	Approver policy.Approver
}

Exchange bundles one inbound message with the channel-side handles the router needs to answer it.

type FileReply ¶

type FileReply interface {
	File(a Attachment)
}

FileReply is an optional capability a Reply may implement: it can deliver a file the agent produced. A channel that cannot carry files leaves it unimplemented, and the send_file tool tells the agent where the file is instead.

type Handler ¶

type Handler func(ctx context.Context, x Exchange)

Handler processes one exchange to completion.

type Inbound ¶

type Inbound struct {
	Chat   string           // conversation key within the channel
	User   string           // sender id, for allowlisting
	Text   string           // message text
	Images []provider.Block // any image blocks that came with it
	Audio  []Clip           // any voice notes that came with it, pre-transcription
}

Inbound is one message arriving from a channel.

func (in Inbound) Message() provider.Message

type Reply ¶

type Reply interface {
	Chunk(text string)
	Notice(text string)
	Done()
}

Reply is how the router talks back during one turn. Chunk carries streamed assistant text, Notice carries out-of-band status (tool activity, errors), and Done finalizes the turn.

type Router ¶

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

Router turns an inbound message into a persisted, policy-gated agent turn and streams the reply back. It is channel-agnostic: HandlerFor binds it to a named channel and returns the Handler that channel drives. A Workforce decides which worker handles each message and builds that worker's agent.

func NewRouter(st *store.Store, work Workforce, auditor policy.Auditor, transcriber voice.Transcriber, synth voice.Synthesizer) *Router

func (r *Router) Background(ctx context.Context, ch, chat, prompt string) (string, error)

func (r *Router) HandlerFor(name string) Handler

func (r *Router) WaitIdle()

type Settings ¶ added in v0.2.1

type Settings map[string]any

Settings is one channel's configuration, decoded from the YAML block under channels.<name>. The core is deliberately blind to what any single key means: a Telegram token, a Discord allow-list, an iMessage database path are all just entries here, and only the channel's own driver knows how to read them. That is the whole point of the split. A new channel is a new package that registers a driver; the core never grows a field for it.

The accessors coerce the loose types a YAML decode produces (a number may arrive as int, int64, or float64; a list as []any) into the shapes a driver asks for, so a driver states what it wants and does not repeat the coercion.

func (s Settings) Bool(key string) bool

func (s Settings) Int64s(key string) []int64

func (s Settings) String(key string) string

func (s Settings) Strings(key string) []string

type VoiceReply ¶

type VoiceReply interface {
	Voice(clip Clip)
}

VoiceReply is an optional capability a Reply may also implement: it can send a synthesized audio clip back. The router calls it when it has spoken a reply and the channel can carry audio out. A channel that cannot just leaves it unimplemented and the reply stays text only.

type Workforce ¶

type Workforce interface {
	// Route picks the worker for a message. An explicit @name prefix wins, then
	// a channel:chat binding, otherwise the default worker. It returns the
	// worker name and the text with any @name prefix stripped.
	Route(channel, chat, text string) (worker, cleaned string)
	// Agent builds a fresh agent for one worker, so its system prompt reflects
	// the worker's current memory.
	Agent(worker string) (*agent.Agent, error)
	// Engine returns the policy engine for one worker.
	Engine(worker string) *policy.Engine
	// Curator returns the reflection pass for one worker, or nil if none runs.
	Curator(worker string) *curator.Curator
	// Names lists every known worker, the default included.
	Names() []string
}

Workforce resolves an inbound message to the worker that should handle it and builds that worker's agent, policy, and curator. A worker is a named specialist with its own persona, memory, and gate; the default worker is tomo. The router owns none of this itself, so how workers are configured stays out of pkg/channel.

func Solo(newAgent AgentFunc, engine *policy.Engine, cur *curator.Curator) Workforce