driver

Documentation

Overview

Package driver is the compiled engine an agent runs on: the LLM HTTP client (Host, a host.Host implementation), TTS synthesis + playback, the serial speech queue, and health/Twilio HTTP servers. An agent supplies its particulars — tiers, TTS transport, and a system-prompt provider — through Config and stands the driver up with New. It bakes in no agent identity: prompts and policy come from the caller.

The the engine driver is becoming an HTTP server (design design/aa-server-status.md §7.1, §10): aa-server-status needs a mandatory GET /healthz on :9730 to manage it as a "source" server (§6.1 — health probe is the authoritative "serving" signal). This file is intentionally minimal: just the listener + health route. The full twilio-cli/HTTP command surface is separate, deferred work (design §11) and does not belong here.

Index

• func EnvBool(k string) bool
• func EnvFloatOr(k string, def float64) float64
• func EnvOr(k, def string) string
• func FilePrompt(path, defaultText string) func() string
• func ParseStreamScheme(args []string) (string, error)
• func StartHealthServer(addr string) *http.Server
• func StartTwilioServer(addr string, s *twilio.Server) *http.Server
• type Config
• type Host
  • func New(cfg Config) *Host
  • func (h *Host) CancelQueued()
  • func (h *Host) Clear()
  • func (h *Host) Context() []byte
  • func (h *Host) Forget()
  • func (h *Host) LastAnswer() []byte
  • func (h *Host) Remember(role string, content []byte)
  • func (h *Host) Send(contextWindow []byte, tier string) ([]byte, []byte, error)
  • func (h *Host) SendStream(contextWindow []byte, tier string, onSegment func(string)) ([]byte, []byte, error)
  • func (h *Host) Speak(text []byte, voice string, speed float64) error
  • func (h *Host) SpeakSync(text []byte, voice string, speed float64) error
  • func (h *Host) SystemPrompt() string
• type TTSConfig
• type Tier
• type Turn

Functions

func EnvBool

func EnvBool(k string) bool

EnvBool reads a boolean-ish env var: "1"/"true"/"yes"/"on" (any case) is true.

func EnvFloatOr

func EnvFloatOr(k string, def float64) float64

EnvFloatOr reads a float env var, falling back to def when unset or unparseable.

func EnvOr

func EnvOr(k, def string) string

func FilePrompt

func FilePrompt(path, defaultText string) func() string

FilePrompt returns a system-prompt provider (Config.Prompt) that reads path and hot-reloads it when the file's mtime changes, falling back to defaultText (or the last good load) if the file can't be read. Agents that don't want a file can pass any func() string to Config.Prompt instead.

func ParseStreamScheme

func ParseStreamScheme(args []string) (string, error)

ParseStreamScheme parses the -stream-scheme flag, defaulting to "wss" and rejecting any value other than "ws" or "wss" (PRD D15 — the flag itself is validated so an invalid scheme never reaches twilio.Server.StreamScheme). It uses a fresh FlagSet (rather than the package-global flag.CommandLine) so it can be called repeatedly and in isolation from tests.

func StartHealthServer

func StartHealthServer(addr string) *http.Server

StartHealthServer launches the health listener in the background and returns the *http.Server handle so the caller can Shutdown it on exit. A bind failure is reported loudly to stderr but does not crash the driver — aa-server-status will simply see the health probe fail, which is itself the correct signal (design §6.5: runtime errors abort loudly, they don't take the whole program down).

func StartTwilioServer

func StartTwilioServer(addr string, s *twilio.Server) *http.Server

StartTwilioServer launches the Twilio-facing HTTP listener in the background, serving the routes built by newTwilioMux (/webhook, /streams, /sms/inbound). Bind failures are reported to stderr but do not crash the process.

Types

type Config

type Config struct {
	Tiers  map[string]Tier
	TTS    TTSConfig
	Prompt func() string
}

Config is what an agent supplies to stand up a driver: its LLM tiers, TTS transport, and a system-prompt provider. The engine holds none of this by default — a different agent (with its own prompt, tiers, policy) constructs its own Config. Prompt is called every turn; use FilePrompt for a hot-reloading file or supply any func() string (embed, remote, constant).

type Host

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

Host is the driver's concrete host.Host: it turns a (messages, tier) pair into an HTTP call against the tier's llama-server.

func New

func New(cfg Config) *Host

New builds a driver Host from cfg, wiring the serial speech queue internally.

func (*Host) CancelQueued

func (h *Host) CancelQueued()

CancelQueued implements host.Host: drops all pending clips from the speech queue without rendering them. Call alongside Forget() on stream errors so orphaned segments don't play from a rolled-back turn.

func (*Host) Clear

func (h *Host) Clear()

func (*Host) Context

func (h *Host) Context() []byte

Context assembles [current system prompt] + history into a JSON messages array ready for Send.

func (*Host) Forget

func (h *Host) Forget()

func (*Host) LastAnswer

func (h *Host) LastAnswer() []byte

func (*Host) Remember

func (h *Host) Remember(role string, content []byte)

func (*Host) Send

func (h *Host) Send(contextWindow []byte, tier string) ([]byte, []byte, error)

Send implements host.Host. contextWindow is the already serialized `messages` array; tier is "fast" | "deep". Returns content, reasoning (empty if the model/flags don't emit it), error. It's SendStream without the per-segment callback — the full assembled text is all the caller wants.

func (*Host) SendStream

func (h *Host) SendStream(contextWindow []byte, tier string, onSegment func(string)) ([]byte, []byte, error)

SendStream is like Send but streams the response, calling onSegment each time a punctuation boundary is reached with enough accumulated text. The returned slices are the fully assembled (content, reasoning). Segments are flushed when the buffer crosses ~30 chars and a delimiter (. ? ! , \n) is seen; the delimiter is kept at the end of the segment so the TTS has the punctuation it needs for natural cadence.

func (*Host) Speak

func (h *Host) Speak(text []byte, voice string, speed float64) error

Speak implements host.Host. It queues synthesis+playback on the serial speech worker and returns immediately, so the turn's text prints without waiting for audio; a failure is logged to stderr and never breaks the turn. No cgo — the ONNX runtime lives in the separate `supertonic serve` process; the driver only does an HTTP POST and shells out to afplay.

func (*Host) SpeakSync

func (h *Host) SpeakSync(text []byte, voice string, speed float64) error

SpeakSync is Speak that blocks until playback finishes, so callers can play clips in sequence (used by /voicetest).

func (*Host) SystemPrompt

func (h *Host) SystemPrompt() string

SystemPrompt implements host.Host: the current system prompt, reloaded from its file only when the file changes.

type TTSConfig

type TTSConfig struct {
	URL    string // .../v1/tts
	Lang   string // ISO code, e.g. "en"
	Format string // wav / flac / ogg — wav plays via afplay
}

TTSConfig is the driver's fixed TTS transport config for Supertonic's native /v1/tts endpoint (the OpenAI-compatible /v1/audio/speech has no speed knob). The tunable per-call settings — voice and speed — are owned by the interpreted policy and passed into Speak, so /voice and /speed change them live.

type Tier

type Tier struct {
	URL, Model string
	Reasoning  bool
	MaxTokens  int
}

Tier describes one tier's llama-server. reasoning=false asks the model to skip its thinking trace; maxTokens caps a single turn so a runaway generation can't burn the whole 300s timeout.

type Turn

type Turn struct {
	Text    string
	Speaker string
}

Turn is one unit of user input. Text is the typed line or the transcript; Speaker is who said it (empty until speaker-ID lands — SOP-2 keeps it "").