convo

package
v0.37.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 15 Imported by: 0

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

View Source
const DefaultQueueCap = 32

DefaultQueueCap is the soft cap NewQueue uses when given cap <= 0.

Variables

View Source
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.

View Source
var ErrUnknownModel = errors.New("unknown model")

ErrUnknownModel is wrapped by ValidateModel's error.

Functions

func ValidateModel

func ValidateModel(models []client.ModelInfo, id string) error

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 NewActive

func NewActive() *Active

NewActive returns an empty registry.

func (*Active) Begin

func (a *Active) Begin(conv string, cancel context.CancelFunc, value any) *Turn

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

func (a *Active) CancelAll(ctx context.Context) []string

CancelAll stops every registered turn and returns their conversations, sorted. WaitCancelled then waits for them to unwind.

func (*Active) CancelToken

func (a *Active) CancelToken(ctx context.Context, conv string, token uint64) (bool, error)

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

func (a *Active) End(t *Turn)

End marks t unwound: closes Ended and, if t is still conv's registered turn, removes it. Idempotent.

func (*Active) Get

func (a *Active) Get(conv string) (*Turn, bool)

Get returns conv's registered turn.

func (*Active) Len

func (a *Active) Len() int

Len returns the number of registered turns.

func (*Active) Running

func (a *Active) Running(conv string) bool

Running reports whether conv has a registered turn.

func (*Active) Stop

func (a *Active) Stop(ctx context.Context, conv string) bool

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

func (a *Active) WaitCancelled(ctx context.Context) error

WaitCancelled blocks until every turn CancelAll stopped has unwound, then until nothing is registered, or ctx is done.

func (*Active) WaitIdle

func (a *Active) WaitIdle(ctx context.Context) error

WaitIdle blocks until no turn 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`).

func (Command) Filter

func (c Command) Filter() Filter

Filter returns the command as a Before filter.

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

type Failer interface {
	Fail(ctx context.Context, in *In, err error) error
}

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.

func (*FileStore) Load

func (f *FileStore) Load() (map[string]string, error)

Load reads the file. A missing file is an empty store.

func (*FileStore) Save

func (f *FileStore) Save(conv, id string) error

Save rewrites the file atomically with conv updated.

type Filter

type Filter func(ctx context.Context, in *In) Verdict

Filter is an ingress rule. It may rewrite in.Text.

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 Informer

type Informer interface{ AgentInfo() client.AgentInfo }

Informer reports the agent's identity (`!status`).

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

type Liveness interface {
	Arm(ctx context.Context) (Clock, context.Context, context.CancelFunc)
}

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 New

func New(cfg Config) (*Manager, error)

New builds a Manager and wires its Controller into the broker.

func (*Manager) Active

func (m *Manager) Active() *Active

Active returns the in-flight turn registry.

func (*Manager) ApplyModel

func (m *Manager) ApplyModel(ctx context.Context, conv string, sid acp.SessionId)

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) Arm

Arm arms the configured Liveness policy for one turn.

func (*Manager) Broker

func (m *Manager) Broker() *command.Broker

Broker returns the command broker (nil with NoCommands).

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

func (m *Manager) Dispatch(ctx context.Context, in In) Result

Dispatch routes one inbound message: Before filters, relay commands, the broker, the passthrough rewrite, After filters, then the prompt.

func (*Manager) EffectiveModel

func (m *Manager) EffectiveModel(conv string) string

EffectiveModel is conv's override, else the model conv's live session reports (see ModelReporter), else the agent's current model.

func (*Manager) Overrides

func (m *Manager) Overrides() *Overrides

Overrides returns the model-override table.

func (*Manager) Pending

func (m *Manager) Pending(conv string) int

Pending returns how many turns are queued (not yet running) for conv.

func (*Manager) Start

func (m *Manager) Start(ctx context.Context, job Job)

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.

func (*Manager) WaitIdle

func (m *Manager) WaitIdle(ctx context.Context) error

WaitIdle blocks until no turn is running or queued, or ctx is done.

type Mode

type Mode int

Mode is the turn runner's policy for a message arriving while a turn runs in the same conversation.

const (
	// Serial queues it behind the running turn (FIFO).
	Serial Mode = iota
	// Supersede cancels the running turn and starts the new one.
	Supersede
)

type ModelReporter added in v0.27.0

type ModelReporter interface {
	CurrentModel(sid acp.SessionId) (string, bool)
}

ModelReporter reports the model one session is running. *client.AgentProc satisfies it. Without it, a conversation with no override reports Models' current, which is process-wide: the model of whichever session was opened last.

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

func NewOverrides(store Store) (*Overrides, error)

NewOverrides returns an Overrides backed by store (nil = memory only), preloaded with whatever store holds.

func (*Overrides) Carry

func (o *Overrides) Carry(from, to string) error

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) Get

func (o *Overrides) Get(conv string) (string, bool)

Get returns conv's override, if any.

func (*Overrides) Len

func (o *Overrides) Len() int

Len returns the number of conversations with an override.

func (*Overrides) MarkApplied

func (o *Overrides) MarkApplied(conv, id string, sid acp.SessionId)

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.

func (*Overrides) Pending

func (o *Overrides) Pending(conv string, sid acp.SessionId) (string, bool)

Pending reports conv's override when it has not yet been applied to session sid.

func (*Overrides) Set

func (o *Overrides) Set(conv, id string) error

Set records id as conv's override (clearing any applied marker) and persists it. An empty id clears the override.

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

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

func NewQueue[T any](cap int, sheddable func(T) bool, onShed func(T)) *Queue[T]

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]) Idle

func (q *Queue[T]) Idle() bool

Idle reports whether nothing is queued or in flight.

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]) Len

func (q *Queue[T]) Len() int

Len returns the number of queued (not in-flight) items.

func (*Queue[T]) PopOrWait

func (q *Queue[T]) PopOrWait(stop <-chan struct{}) (item T, ok bool)

PopOrWait blocks until an item is available (marking it in flight) or stop fires (ok=false).

func (*Queue[T]) Push

func (q *Queue[T]) Push(item T) bool

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

func (q *Queue[T]) Stop() (pending []T, inFlight bool)

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

func (q *Queue[T]) StopIfIdle() bool

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.

func (*Queue[T]) WaitIdle

func (q *Queue[T]) WaitIdle(d time.Duration) bool

WaitIdle blocks until Idle or d elapses, reporting Idle.

type Resetter

type Resetter interface{ Reset(conv string) error }

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

type RunFunc func(ctx context.Context, t *Turn, in *In, prompt string) error

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 Sink

type Sink interface {
	Reply(ctx context.Context, in *In, text string) error
}

Sink delivers a command's reply to the conversation.

type SinkFunc

type SinkFunc func(ctx context.Context, in *In, text string) error

SinkFunc adapts a function to Sink.

func (SinkFunc) Reply

func (f SinkFunc) Reply(ctx context.Context, in *In, text string) error

Reply implements Sink.

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).

func (*Turn) Ended

func (t *Turn) Ended() <-chan struct{}

Ended is closed when the turn has fully unwound (Active.End).

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).

func (Unbounded) Arm

Arm implements Liveness.

type Verdict

type Verdict int

Verdict is a Filter's decision.

const (
	// Pass continues dispatch with the (possibly rewritten) text.
	Pass Verdict = iota
	// Handled means the filter consumed the message.
	Handled
	// Forward skips every remaining classification and sends the text
	// to the agent as a prompt.
	Forward
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL