Documentation
¶
Overview ¶
Package convo is the shared conversation → ACP-session manager core every relay (poe-acp, zulip-acp, slack-acp) puts between its chat surface and the agent.
A relay used to hand-write the same five things: a sticky per- conversation `!model` override, a turn runner (serial FIFO or supersede-on-follow-up), race-safe cancellation, a turn liveness bound, and a command.Controller over all of it — and one relay (slack-acp) never wrote the Controller at all, so `!model` reached a broken model as a prompt. Manager owns those; the relay injects what only it knows:
- Sink: where a command's reply goes (a Zulip message, an SSE frame, a Slack thread post).
- Filters: ingress rules that run before and after the broker — Zulip's /me /poll /todo passthrough, the `!!` escape, relay-only commands such as `!opts`, `!archive` and `!branch`.
- Liveness: the turn-bound policy (ProgressClock by default).
- Store: optional persistence for model overrides.
- Hooks: relay-shaped Controller behaviour — re-keying `!new`, token → conversation resolution, status decoration.
- Sessions: the conversation → ACP session map. acp-kit/state's Manager is the shared implementation; a relay with its own session semantics (poe-acp's per-host agents and transcript divergence) plugs its map in through the same interface.
Dispatch is the single entry point: relay filters, then the command broker (standard `!commands` are on by default), then the passthrough rewrite, then the prompt — run by the Manager's turn runner when the relay supplies Run, or handed back to the caller when it streams the turn itself.
Index ¶
- Constants
- Variables
- func ValidateModel(models []client.ModelInfo, id string) error
- type Active
- func (a *Active) Begin(conv string, cancel context.CancelFunc, value any) *Turn
- func (a *Active) CancelAll(ctx context.Context) []string
- func (a *Active) CancelToken(ctx context.Context, conv string, token uint64) (bool, error)
- func (a *Active) Claim(ctx context.Context, conv string, cancel context.CancelFunc, value any) (*Turn, error)
- func (a *Active) End(t *Turn)
- func (a *Active) Get(conv string) (*Turn, bool)
- func (a *Active) Len() int
- func (a *Active) Running(conv string) bool
- func (a *Active) Stop(ctx context.Context, conv string) bool
- func (a *Active) Supersede(ctx context.Context, conv string, cancel context.CancelFunc, value any) *Turn
- func (a *Active) WaitCancelled(ctx context.Context) error
- func (a *Active) WaitIdle(ctx context.Context) error
- type Agent
- type Clock
- type Command
- type Config
- type Failer
- type FileStore
- type Filter
- type Hooks
- type In
- type Informer
- type Job
- type Liveness
- type Manager
- func (m *Manager) Active() *Active
- func (m *Manager) ApplyModel(ctx context.Context, conv string, sid acp.SessionId)
- func (m *Manager) Arm(ctx context.Context) (Clock, context.Context, context.CancelFunc)
- func (m *Manager) Broker() *command.Broker
- func (m *Manager) Controller() command.Controller
- func (m *Manager) Dispatch(ctx context.Context, in In) Result
- func (m *Manager) EffectiveModel(conv string) string
- func (m *Manager) Overrides() *Overrides
- func (m *Manager) Pending(conv string) int
- func (m *Manager) Start(ctx context.Context, job Job)
- func (m *Manager) WaitIdle(ctx context.Context) error
- type Mode
- type ModelSetter
- type Overrides
- func (o *Overrides) Carry(from, to string) error
- func (o *Overrides) Get(conv string) (string, bool)
- func (o *Overrides) Len() int
- func (o *Overrides) MarkApplied(conv, id string, sid acp.SessionId)
- func (o *Overrides) Pending(conv string, sid acp.SessionId) (string, bool)
- func (o *Overrides) Set(conv, id string) error
- type ProgressClock
- type Queue
- func (q *Queue[T]) Finish()
- func (q *Queue[T]) Idle() bool
- func (q *Queue[T]) Items() []T
- func (q *Queue[T]) Len() int
- func (q *Queue[T]) PopOrWait(stop <-chan struct{}) (item T, ok bool)
- func (q *Queue[T]) Push(item T) bool
- func (q *Queue[T]) Stop() (pending []T, inFlight bool)
- func (q *Queue[T]) StopIfIdle() bool
- func (q *Queue[T]) WaitIdle(d time.Duration) bool
- type Resetter
- type Result
- type RunFunc
- type Sessions
- type Sink
- type SinkFunc
- type StatsReporter
- type Store
- type Turn
- type Unbounded
- type Verdict
Constants ¶
const DefaultQueueCap = 32
DefaultQueueCap is the soft cap NewQueue uses when given cap <= 0.
Variables ¶
var ErrNoConversation = errors.New("there is no conversation here yet — send a message first")
ErrNoConversation is returned by SetModelOverride for a token that resolves to no conversation.
var ErrUnknownModel = errors.New("unknown model")
ErrUnknownModel is wrapped by ValidateModel's error.
Functions ¶
func ValidateModel ¶
ValidateModel checks id against the agent's advertised models. An empty catalogue accepts anything: the relay cannot tell a bad id from a list it has not learned yet, and refusing would lock the user out of the one command that can repair a broken model.
Types ¶
type Active ¶
type Active struct {
// OnCancel, when set, is called after a turn's context is
// cancelled, to tell the agent (session/cancel). Called without the
// registry lock held. Its error is returned by CancelToken.
OnCancel func(ctx context.Context, conv string) error
// OnWait, when set, is called (under the registry lock — it must not
// call back into Active) each time Claim finds conv busy and parks.
OnWait func(conv string)
// contains filtered or unexported fields
}
Active is the registry of in-flight turns, one per conversation.
It is the race-safe half of cancellation. Stop cancels whatever is running (`!stop`, a superseding follow-up); CancelToken cancels only the turn a caller proves it owns, closing the window where turn N's owner cancels turn N+1 after N finished and N+1 started.
func (*Active) Begin ¶
Begin registers a new turn for conv and returns it. cancel (may be nil) is what Stop and CancelToken call. A turn already registered for conv is displaced from the registry but NOT cancelled — see Supersede.
func (*Active) CancelAll ¶
CancelAll stops every registered turn and returns their conversations, sorted. WaitCancelled then waits for them to unwind.
func (*Active) CancelToken ¶
CancelToken cancels conv's turn only if it is the one identified by token, reporting whether it did and OnCancel's error. A stale or zero token is a no-op. The turn stays registered until its runner calls End.
Residual window: the token is compared under the lock but the cancel is issued after releasing it (never hold a lock across a wire write), so a turn ending in those few instructions may still be followed by a cancel of its successor's session. The seconds-wide window is gone.
func (*Active) Claim ¶
func (a *Active) Claim(ctx context.Context, conv string, cancel context.CancelFunc, value any) (*Turn, error)
Claim waits until conv has no registered turn and then registers a new one, without releasing the lock in between — so a turn that must never supersede another (a scheduled prompt, a batched reaction) cannot have a message arriving in the gap displaced either. Returns ctx.Err() if it gives up first, in which case nothing is registered.
func (*Active) End ¶
End marks t unwound: closes Ended and, if t is still conv's registered turn, removes it. Idempotent.
func (*Active) Stop ¶
Stop cancels and deregisters conv's turn, reporting whether there was one. `!stop` uses the answer to tell interrupting from doing nothing.
func (*Active) Supersede ¶
func (a *Active) Supersede(ctx context.Context, conv string, cancel context.CancelFunc, value any) *Turn
Supersede registers a new turn for conv and cancels the one it displaces, if any, in one step: two follow-ups racing each other can never both be left running, as a separate Stop then Begin could.
func (*Active) WaitCancelled ¶
WaitCancelled blocks until every turn CancelAll stopped has unwound, then until nothing is registered, or ctx is done.
type Agent ¶
type Agent interface {
Models() (models []client.ModelInfo, currentID string)
AvailableCommands() []client.CommandInfo
}
Agent is the agent surface the Manager needs. *client.AgentProc satisfies it, and also the optional ModelSetter, Informer and StatsReporter the Manager uses when present.
type Clock ¶
type Clock interface {
Progress()
Wrap(down client.SessionUpdateSink) client.SessionUpdateSink
}
Clock is one armed turn bound. Progress resets it; Wrap returns a sink that resets it on every progress-bearing session update.
type Command ¶
type Command struct {
// Match reports whether text invokes the command, and its argument.
Match func(text string) (arg string, ok bool)
Run func(ctx context.Context, in *In, arg string)
// Help lines appended to the broker's `!help`.
Help []string
}
Command is a relay-only chat command (zulip-acp's `!opts`, `!archive`, `!branch`).
type Config ¶
type Config struct {
Agent Agent
Sessions Sessions // optional
// Broker is the command broker. Nil builds a standard one over Auth
// (or Agent, when it can authenticate) unless NoCommands is set.
Broker *command.Broker
Auth command.Authenticator
NoCommands bool
// Poster and Scheduler are the optional command capabilities behind
// out-of-band posting and `!schedules`, handed to the broker.
Poster command.Poster
Scheduler command.Scheduler
// Overrides holds the `!model` choices. Nil = in-memory, or
// persistent when Store is set.
Overrides *Overrides
Store Store
Mode Mode
Liveness Liveness // nil = ProgressClock{NoProgressTimeout: 2m}
// NoStop leaves `!stop` unadvertised (command.TurnStopper not
// implemented) for relays with no in-flight turn a later message can
// reach.
NoStop bool
Sink Sink
Before []Filter // before the broker
After []Filter // after the passthrough rewrite
Extra []Command // relay-only commands, run after Before
Run RunFunc // nil = Dispatch hands the prompt back
OnError func(conv string, err error)
Hooks Hooks
ModelOrder func([]client.ModelInfo) []client.ModelInfo
Version string
AgentCmd string
StartTime time.Time
Now func() time.Time
Logf func(format string, args ...any)
}
Config configures a Manager.
type Failer ¶
Failer is an optional Sink capability for a failed command. Without it the Manager replies "Command failed: <err>".
type FileStore ¶
type FileStore struct {
Path string
// contains filtered or unexported fields
}
FileStore is a Store kept in one JSON object file.
type Hooks ¶
type Hooks struct {
// Resolve maps a broker token to the conversation id. ok=false means
// the conversation does not exist yet. Default: the token itself.
Resolve func(token string) (conv string, ok bool)
// Reset replaces the default `!new` (stop the turn, drop the
// session). zulip-acp retires the conversation and re-keys it.
Reset func(ctx context.Context, token string) error
// Status and RelayInfo post-process the Manager's snapshot.
Status func(token, conv string, ok bool, st command.SessionStatus) command.SessionStatus
RelayInfo func(token, conv string, ok bool, ri command.RelayInfo) command.RelayInfo
// ModelChanged runs after a successful `!model <id>`.
ModelChanged func(token, conv, modelID string)
// Decorate post-processes a broker reply before it is sent.
Decorate func(text, reply string) string
}
Hooks are relay-shaped Controller behaviour. Every hook is optional.
type In ¶
type In struct {
// Conv is the relay's conversation id — the session key.
Conv string
// Token is the broker's opaque conversation token; "" means Conv.
// A relay that re-keys conversations (zulip-acp's `!new`) passes a
// stable token here and resolves it with Config.Resolve.
Token string
Text string
// Sink overrides Config.Sink for this message (poe-acp: the
// request's SSE stream).
Sink Sink
// Meta is relay-owned context for filters and Run (the Zulip
// message, the Slack event).
Meta any
}
In is one inbound message.
type Job ¶
type Job struct {
Conv string
Value any // becomes Turn.Value
Run func(ctx context.Context, t *Turn) error
// After runs once the turn has fully unwound and is no longer
// registered — so a deferred action the turn asked for (a reset,
// say) cannot cancel the very turn that requested it.
After func(t *Turn)
}
Job is one turn submitted to the Manager's turn runner.
type Liveness ¶
Liveness is the relay's turn-bound policy. Arm returns the armed clock, a context that is cancelled (with a cause) when the bound trips, and a stop func that disarms it. Relays arm it where their turn really starts — after any queue wait, just before prompting — so a turn is never charged for time spent behind another one.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager is the conversation core. See the package doc.
func (*Manager) ApplyModel ¶
ApplyModel pushes conv's sticky override to session sid, at most once per session. Lazy on purpose: applying at `!model` time would need a live session, and creating one from a settings command is a side effect nobody asked for. A failure is logged and the turn continues on whatever model the session already had — far better than refusing to answer over a preference.
func (*Manager) Controller ¶
func (m *Manager) Controller() command.Controller
Controller returns the Manager's command.Controller. It implements command.TurnStopper unless Config.NoStop.
func (*Manager) Dispatch ¶
Dispatch routes one inbound message: Before filters, relay commands, the broker, the passthrough rewrite, After filters, then the prompt.
func (*Manager) EffectiveModel ¶
EffectiveModel is conv's override, else the agent's current model.
func (*Manager) Start ¶
Start submits job under the configured Mode and returns at once.
The turn's context is detached from ctx's cancellation (an inbound request ending must not kill the turn it started) and is cancelled only by Active.Stop / CancelToken — `!stop`, a superseding follow-up, or a caller that owns the turn's token. In Serial mode `!stop` stops the running turn only; turns already queued behind it still run.
type Mode ¶
type Mode int
Mode is the turn runner's policy for a message arriving while a turn runs in the same conversation.
type ModelSetter ¶
type ModelSetter interface {
SetModel(ctx context.Context, sid acp.SessionId, modelID string) error
}
ModelSetter applies a model to one session (ApplyModel).
type Overrides ¶
type Overrides struct {
// contains filtered or unexported fields
}
Overrides holds the sticky per-conversation model chosen with `!model`.
Each choice also records the ACP session it was last pushed to, so a relay that applies overrides lazily (at the start of the next turn) re-applies after idle GC or a reset hands the conversation a new session: the id mismatch is the signal. See Pending and MarkApplied.
func NewOverrides ¶
NewOverrides returns an Overrides backed by store (nil = memory only), preloaded with whatever store holds.
func (*Overrides) Carry ¶
Carry moves from's override to to, dropping the applied marker so the new conversation's session gets its own push. Used when a relay re-keys a conversation (zulip-acp's `!new` allocates a fresh id): the model choice is the user's, not the conversation's.
func (*Overrides) MarkApplied ¶
MarkApplied records that id was pushed to sid for conv. A choice changed in the meantime is left untouched so it is applied next turn.
type ProgressClock ¶
type ProgressClock client.TurnLivenessConfig
ProgressClock is the default Liveness: acp-kit's progress-resetting no-progress timeout plus an optional absolute ceiling. See client.TurnLivenessConfig.
func (ProgressClock) Arm ¶
func (p ProgressClock) Arm(ctx context.Context) (Clock, context.Context, context.CancelFunc)
Arm implements Liveness.
type Queue ¶
type Queue[T any] struct { // contains filtered or unexported fields }
Queue is a per-conversation FIFO of pending turns, consumed by exactly one runner goroutine that owns every prompt for the conversation — ACP allows one outstanding prompt per session, so turns are serialised.
Items may be SHEDDABLE (out-of-band work such as a reaction event). Past the soft cap the oldest sheddable item is dropped to make room; an incoming sheddable item with nothing older to shed is refused. Non-sheddable items (real user turns) are never dropped: the queue grows past the cap rather than lose one.
func NewQueue ¶
NewQueue returns an empty queue. sheddable (nil = nothing sheds) classifies items; onShed (may be nil) is told about an item dropped on overflow — push never finalises it itself.
func (*Queue[T]) Finish ¶
func (q *Queue[T]) Finish()
Finish marks the in-flight item done. Call after every popped item, before releasing whoever waits on it.
func (*Queue[T]) Items ¶
func (q *Queue[T]) Items() []T
Items returns a copy of the queued (not in-flight) items, oldest first.
func (*Queue[T]) PopOrWait ¶
PopOrWait blocks until an item is available (marking it in flight) or stop fires (ok=false).
func (*Queue[T]) Push ¶
Push appends item, reporting whether it was accepted. It is refused when the queue is stopped, or when it is sheddable, the queue is full and no older sheddable item exists.
func (*Queue[T]) Stop ¶
Stop closes the queue and detaches pending items, returning them and whether one is still in flight. The caller finalises the returned items — deliberately not done here, so Stop is safe under a caller's lock that must never be held across a sink write.
func (*Queue[T]) StopIfIdle ¶
StopIfIdle atomically checks idleness and, only if idle, closes the queue. Checking and closing in separate steps would leave a gap where a pushed item is detached with nobody left to run it.
type Resetter ¶
Resetter is the optional Sessions capability behind the default `!new`: drop conv's session so the next turn starts fresh.
type Result ¶
type Result struct {
// Handled: the message was consumed (a command, or a filter).
Handled bool
// Prompt is the text to send to the agent when not Handled. With
// Config.Run set it has already been submitted to the turn runner;
// otherwise the caller runs it.
Prompt string
}
Result is what Dispatch did with a message.
type RunFunc ¶
RunFunc executes one prompt turn. It runs on the Manager's turn runner: ctx is cancelled by `!stop`, a superseding follow-up, or Active.CancelToken.
type Sessions ¶
type Sessions interface {
// Live reports conv's live session without creating one.
Live(conv string) (sid acp.SessionId, lastUsed time.Time, ok bool)
// Cancel sends session/cancel for conv's live session, if any.
Cancel(ctx context.Context, conv string)
// Len is the number of live sessions.
Len() int
}
Sessions is the conversation → ACP session map. *state.Manager satisfies it (and Resetter).
type StatsReporter ¶
type StatsReporter interface {
SessionStats(sid acp.SessionId) (client.SessionStats, bool)
}
StatsReporter reports per-session ACP stats (`!status`).
type Store ¶
type Store interface {
// Load returns every persisted override, keyed by conversation.
Load() (map[string]string, error)
// Save records conv's override. An empty id deletes it.
Save(conv, id string) error
}
Store persists per-conversation model overrides across restarts. It is optional: a nil Store keeps overrides in memory only, which is what a relay wants when a model choice is session-shaped and a restart drops the sessions it applied to anyway.
type Turn ¶
type Turn struct {
Conv string
Token uint64
// Value is relay-owned per-turn state (poe-acp: the live sink for
// its MCP attach tool; zulip-acp: the turn's pending topic rename).
Value any
// contains filtered or unexported fields
}
Turn is one registered in-flight turn.
Its Token identifies it for race-safe cancellation: a canceller that captured the token of the turn it owns can never, by accident, cancel the NEXT turn of the same conversation (see Active.CancelToken).
type Unbounded ¶
type Unbounded struct{}
Unbounded is a Liveness that never trips: for relays whose turns are bounded elsewhere (e.g. by the HTTP request that carries them).