server

package
v1.81.0 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrModelSwitchingNotSupported = errors.New("model switching not supported by this runtime")

ErrModelSwitchingNotSupported is returned when the runtime backing a session does not support runtime model switching (e.g. when the agent was created without a ModelSwitcherConfig).

View Source 
var ErrSessionBusy = errors.New("session is already processing a request")

ErrSessionBusy is returned when a session is already processing a request.

View Source 
var ErrSessionNotRunning = errors.New("session not found or not running")

ErrSessionNotRunning is returned by methods that require an active runtime for the session (i.e. RunSession must have been called or AttachRuntime invoked) when none is found. HTTP handlers map this to 404 to distinguish from other runtime errors.

Functions

func BearerTokenMiddleware added in v1.59.0 

func BearerTokenMiddleware(expectedToken string) echo.MiddlewareFunc

BearerTokenMiddleware validates bearer token authentication

func Listen 

func Listen(ctx context.Context, addr string) (net.Listener, error)

func NewSourceLoader 

func NewSourceLoader(ctx context.Context, inner config.Source, refreshInterval time.Duration) *sourceLoader

NewSourceLoader creates a new source loader that caches and periodically refreshes a config source.

Types

type EventSource added in v1.58.0 

type EventSource func(ctx context.Context, send func(any))

EventSource pushes session events to send for the lifetime of ctx. The callback is invoked from request goroutines (e.g. an SSE handler), so it must be safe to call concurrently across requests.

type FollowUpInjector added in v1.80.0 

type FollowUpInjector func(ctx context.Context, content string)

FollowUpInjector delivers a follow-up message to the session's owner (the TUI App) as if a user had submitted it, starting a real turn. Registered by the attached control plane via SessionManager.RegisterFollowUpInjector.

type Server 

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

func New 

func New(ctx context.Context, sessionStore session.Store, runConfig *config.RuntimeConfig, refreshInterval time.Duration, agentSources config.Sources, authToken string) (*Server, error)

func NewWithManager added in v1.58.0 

func NewWithManager(sm *SessionManager, authToken string) *Server

NewWithManager builds a Server around an already-constructed SessionManager. Useful when the runtime is owned by another component (e.g. the TUI) and only needs to be exposed over HTTP.

func (*Server) Serve 

func (s *Server) Serve(ctx context.Context, ln net.Listener) error

type SessionManager 

type SessionManager struct {
	Sources config.Sources
	// contains filtered or unexported fields
}

SessionManager manages sessions for HTTP and Connect-RPC servers.

func NewSessionManager 

func NewSessionManager(ctx context.Context, sources config.Sources, sessionStore session.Store, refreshInterval time.Duration, runConfig *config.RuntimeConfig) *SessionManager

NewSessionManager creates a new session manager.

func (*SessionManager) AddMessage added in v1.59.0 

func (sm *SessionManager) AddMessage(ctx context.Context, sessionID string, msg *session.Message) error

AddMessage adds a message to a session.

func (*SessionManager) AddSummary added in v1.59.0 

func (sm *SessionManager) AddSummary(ctx context.Context, sessionID, summary string, tokens int) error

AddSummary adds a summary to a session.

func (*SessionManager) AttachRuntime added in v1.58.0 

func (sm *SessionManager) AttachRuntime(sessionID string, rt runtime.Runtime, sess *session.Session)

AttachRuntime registers a pre-built runtime + session under sessionID so that subsequent calls (RunSession, Steer, Resume...) reuse it instead of building one from agentFilename. This is what lets a single in-process runtime be shared between the TUI and an HTTP control plane.

The internal cancellation signal is fired by SessionManager.DeleteSession; SSE streams and other lifetime-bound consumers use it (via SessionManager.StreamEvents) to terminate when the session is detached.

func (*SessionManager) AvailableSessionModels added in v1.60.0 

func (sm *SessionManager) AvailableSessionModels(ctx context.Context, sessionID string) (string, string, []runtime.ModelChoice, error)

AvailableSessionModels returns the list of models available for the session's current agent. The agent's name and the active model override (if any) are returned alongside the choices so callers don't have to peek into the runtime registry. A session-scoped runtime is required, so the session must have been started at least once (RunSession called) or be attached out-of-band via AttachRuntime.

Each returned ModelChoice has IsCurrent set so the picker can highlight the active selection without a second round-trip. When no override is active, the agent's configured default carries IsCurrent=true; if the override points at an inline provider/model not present in the agent config, a synthetic choice is appended (mirrors App.AvailableModels via the shared runtime.DecorateModelChoices helper).

func (*SessionManager) BatchDeleteSessions added in v1.59.0 

func (sm *SessionManager) BatchDeleteSessions(ctx context.Context, sessionIDs []string) (int, []string)

BatchDeleteSessions deletes multiple sessions in a single operation.

func (*SessionManager) BatchExportSessions added in v1.59.0 

func (sm *SessionManager) BatchExportSessions(ctx context.Context, sessionIDs []string) (map[string]any, error)

BatchExportSessions exports multiple sessions as JSON

func (*SessionManager) CreateSession 

func (sm *SessionManager) CreateSession(ctx context.Context, sessionTemplate *session.Session) (*session.Session, error)

CreateSession creates a new session from a template.

func (*SessionManager) DeleteSession 

func (sm *SessionManager) DeleteSession(ctx context.Context, sessionID string) error

DeleteSession deletes a session by ID. It cancels the runtime context and removes the session from all registries. Callers that need to wait for the stream to fully stop should call WaitStopped afterwards.

func (*SessionManager) ExportSessionForRecovery added in v1.59.0 

func (sm *SessionManager) ExportSessionForRecovery(ctx context.Context, sessionID string) (map[string]any, error)

ExportSessionForRecovery exports a single session as JSON for recovery

func (*SessionManager) FollowUpSession added in v1.44.0 

func (sm *SessionManager) FollowUpSession(ctx context.Context, sessionID string, messages []api.Message, idempotencyKey string) (streaming, duplicate bool, err error)

FollowUpSession enqueues user messages for end-of-turn processing in a running session. Each message is popped one at a time after the current turn finishes, giving each follow-up a full undivided agent turn.

idempotencyKey, when non-empty, makes the call safe to retry: if a request with the same key already landed for this session, this one is a no-op and returns duplicate=true. The reservation is rolled back if delivery fails, so a genuine failure stays retryable.

When a follow-up injector is registered for the session (the --listen control plane attaches one for the TUI App), messages are delivered through it: the App submits them as normal user input, which starts a turn even when the agent is idle and streams events to the TUI and every SSE subscriber. The returned streaming flag is true in this case because a turn is (or is about to be) running.

Without an injector (headless server-owned sessions) the messages go to the runtime follow-up queue. If no stream is currently running the messages are still enqueued but are not consumed until the next RunSession starts a stream; the returned boolean indicates whether a stream is active.

func (*SessionManager) GetAgentToolCount 

func (sm *SessionManager) GetAgentToolCount(ctx context.Context, agentFilename, agentName string) (int, error)

GetAgentToolCount loads the agent's team and returns the number of tools available to the given agent. When agentName is empty, it resolves to the team's default agent.

func (*SessionManager) GetSession 

func (sm *SessionManager) GetSession(ctx context.Context, id string) (*session.Session, error)

GetSession retrieves a session by ID.

func (*SessionManager) GetSessionSnapshot added in v1.80.0 

func (sm *SessionManager) GetSessionSnapshot(ctx context.Context, id string) (*api.SessionSnapshotResponse, error)

GetSessionSnapshot returns the full, self-contained state of a session: its stored fields plus, when an active runtime is attached, its live runtime state (streaming, current agent) and the sequence number of the most recent event on its /events stream. It is the resync primitive for the control plane: a client reads the snapshot, then tails /events?since=<LastEventSeq> to continue without a gap.

func (*SessionManager) GetSessionStatus added in v1.59.0 

func (sm *SessionManager) GetSessionStatus(_ context.Context, id string) (*api.SessionStatusResponse, error)

GetSessionStatus returns a lightweight snapshot of the session's current runtime state. Designed for late-joining SSE consumers that need to know the session's state without waiting for the next event transition.

func (*SessionManager) GetSessions 

func (sm *SessionManager) GetSessions(ctx context.Context) ([]*session.Session, error)

GetSessions retrieves all sessions.

func (*SessionManager) HasEventSource added in v1.80.0 

func (sm *SessionManager) HasEventSource(sessionID string) bool

HasEventSource reports whether an event log is registered for sessionID.

func (*SessionManager) LastEventSeq added in v1.80.0 

func (sm *SessionManager) LastEventSeq(sessionID string) (uint64, bool)

LastEventSeq returns the most recent event sequence number for sessionID, so a snapshot can advertise the exact point from which a client should tail. Returns 0 and false when no event log exists.

func (*SessionManager) RegisterEventSource added in v1.58.0 

func (sm *SessionManager) RegisterEventSource(sessionID string, src EventSource)

RegisterEventSource attaches an event source for sessionID and immediately starts pumping its events into a per-session [eventLog]. It is used by callers that own a runtime out-of-band (e.g. the TUI) so that HTTP clients can subscribe to events — with sequence numbers and replay — via GET /api/sessions/:id/events.

The pump runs for the session's lifetime (until DeleteSession or the source returns), buffering events even when no client is connected, so a client that connects or reconnects later can replay what it missed.

func (*SessionManager) RegisterFollowUpInjector added in v1.80.0 

func (sm *SessionManager) RegisterFollowUpInjector(sessionID string, fn FollowUpInjector)

RegisterFollowUpInjector registers fn as the follow-up delivery path for an attached sessionID. When set, SessionManager.FollowUpSession routes messages through fn (which feeds them to the TUI App so a real turn starts) instead of the runtime follow-up queue. Used by the --listen control plane.

func (*SessionManager) ResumeElicitation 

func (sm *SessionManager) ResumeElicitation(ctx context.Context, sessionID, action string, content map[string]any) error

ResumeElicitation resumes an elicitation request.

func (*SessionManager) ResumeSession 

func (sm *SessionManager) ResumeSession(ctx context.Context, sessionID, confirmation, reason, toolName string) error

ResumeSession resumes a paused session with an optional rejection reason or tool name.

func (*SessionManager) RunSession 

func (sm *SessionManager) RunSession(ctx context.Context, sessionID, agentFilename, currentAgent string, messages []api.Message, modelOverride string) (<-chan runtime.Event, error)

RunSession runs a session with the given messages.

When modelOverride is non-empty, it is applied to the session's current agent before any user messages are appended (and persisted via SetSessionAgentModel) so the override is in effect for this turn and every subsequent one. Validation happens before the messages are recorded so a bad ref does not leave an orphaned user message in the history.

func (*SessionManager) SetSessionAgentModel added in v1.60.0 

func (sm *SessionManager) SetSessionAgentModel(ctx context.Context, sessionID, modelRef string) (string, string, error)

SetSessionAgentModel applies modelRef as the model override for the current agent of the session and persists it. Pass an empty modelRef to clear the override and revert to the agent's default model.

On store-write failure the in-memory session state and the runtime override are rolled back so the next call observes a consistent state.

The HTTP server no longer exposes this directly: model overrides are folded into the runAgent request body. The method is kept so in-process callers (notably the TUI's App) can switch models without going through HTTP.

func (*SessionManager) SetSessionStarred added in v1.59.0 

func (sm *SessionManager) SetSessionStarred(ctx context.Context, sessionID string, starred bool) error

SetSessionStarred sets the starred status for a session.

func (*SessionManager) SteerSession added in v1.44.0 

func (sm *SessionManager) SteerSession(_ context.Context, sessionID string, messages []api.Message) error

SteerSession enqueues user messages for mid-turn injection into a running session. The messages are picked up by the agent loop after the current tool calls finish but before the next LLM call. Returns an error if the session is not actively running or if the steer buffer is full.

func (*SessionManager) StreamEvents added in v1.58.0 

func (sm *SessionManager) StreamEvents(ctx context.Context, sessionID string, since *uint64, send func(seq uint64, event any)) bool

StreamEvents replays and tails the events buffered for sessionID, calling send for each one with its sequence number. When since is non-nil only events newer than *since are replayed before tailing (see [eventLog.stream] for the gap semantics). It blocks until ctx is cancelled, the session is detached via SessionManager.DeleteSession, or the source ends. Returns false when no event log is registered.

func (*SessionManager) ToggleToolApproval 

func (sm *SessionManager) ToggleToolApproval(ctx context.Context, sessionID string) error

ToggleToolApproval toggles the tool approval mode for a session.

func (*SessionManager) UpdateMessage added in v1.59.0 

func (sm *SessionManager) UpdateMessage(ctx context.Context, sessionID, msgID string, msg *session.Message) error

UpdateMessage updates a message in a session.

func (*SessionManager) UpdateSessionPermissions 

func (sm *SessionManager) UpdateSessionPermissions(ctx context.Context, sessionID string, perms *session.PermissionsConfig) error

UpdateSessionPermissions updates the permissions for a session.

func (*SessionManager) UpdateSessionTitle 

func (sm *SessionManager) UpdateSessionTitle(ctx context.Context, sessionID, title string) error

UpdateSessionTitle updates the title for a session. If the session is actively running, it also updates the in-memory session object to prevent subsequent runtime saves from overwriting the title.

func (*SessionManager) UpdateSessionTokens added in v1.59.0 

func (sm *SessionManager) UpdateSessionTokens(ctx context.Context, sessionID string, inputTokens, outputTokens int64, cost float64) error

UpdateSessionTokens updates the token counts for a session.

func (*SessionManager) WaitReady added in v1.59.0 

func (sm *SessionManager) WaitReady(ctx context.Context) error

WaitReady blocks until at least one session has been attached or created, or ctx is cancelled. Returns nil when ready, ctx.Err() on timeout.

func (*SessionManager) WaitSessionAttached added in v1.80.0 

func (sm *SessionManager) WaitSessionAttached(ctx context.Context, sessionID string, timeout time.Duration) bool

WaitSessionAttached blocks until a runtime is attached for sessionID (i.e. the session is ready to accept follow-ups and produce events), the timeout elapses, or ctx is cancelled. It returns true once the session is attached.

Unlike WaitReady, which fires as soon as *any* session is ready, this is session-scoped: a client that launched a specific run can wait for exactly that session instead of racing the server's startup.

func (*SessionManager) WaitStopped added in v1.59.0 

func (sm *SessionManager) WaitStopped(ctx context.Context, sessionID string, timeout time.Duration) error

WaitStopped blocks until the session's runtime stream goroutine has fully exited (streaming mutex released), the timeout fires, or ctx is cancelled (e.g. client disconnect). It should be called after DeleteSession. Returns nil when the stream has stopped.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.