server

Documentation

Overview

Package server provides the HTTP server for octo's REST API and Web UI.

It is the M8 milestone implementation: a stateless HTTP layer over the existing agent/session/tool infrastructure. Each request carries its own context; sessions are loaded from / saved to disk on every turn.

Index

• Constants
• Variables
• type Config
• type Server
  • func New(cfg Config) (*Server, error)
  • func (s *Server) AccessKey() string
  • func (s *Server) CreateSession(task scheduler.Task) (string, error)
  • func (s *Server) ListenAndServe() error
  • func (s *Server) Restart(reason string)
  • func (s *Server) RunTask(ctx context.Context, task scheduler.Task) (string, error)
  • func (s *Server) SetSubscribed(conn *wsConn, sessionID string)
  • func (s *Server) Shutdown(ctx context.Context) error

Constants

const ExitRestart = 42

ExitRestart is the process exit code the serve worker uses to ask its supervisor for a respawn. The supervisor (cmd/octo serve, or an external one via e.g. systemd RestartForceExitStatus) re-spawns the worker from the on-disk binary path, so a replaced binary takes effect on restart.

Variables

var ErrRestartRequested = errors.New("server restart requested")

ErrRestartRequested is returned by ListenAndServe when the server stopped because a restart was requested (API or restart_server tool), as opposed to a plain shutdown. Callers map it to ExitRestart.

Types

type Config

type Config struct {
	// Bind address (e.g. ":8088", "127.0.0.1:8088").
	Addr string

	// Provider and model override; zero values fall back to env/config.
	Provider string
	Model    string
	System   string

	// MaxTokens forwarded to the agent per turn.
	MaxTokens int

	// Tools enables the agentic tool loop.
	Tools bool

	// CORSOrigins lists allowed origins for CORS. Empty disables CORS.
	CORSOrigins []string

	// NoChannel disables IM channel (DingTalk, Feishu, etc.) startup.
	// When false (default), channels are started from ~/.octo/channels.yml
	// alongside the HTTP server.
	NoChannel bool

	// AccessKey is the shared secret used to authenticate Web UI and API
	// requests. When empty, the server looks for OCTO_ACCESS_KEY env var.
	// If still empty, a random key is generated and printed on startup.
	AccessKey string

	// NoMemory disables cross-session memory injection.
	NoMemory bool

	// UpdateCheck enables the outbound latest-release lookup behind
	// GET /api/version. Only `octo serve` sets it; every other Server
	// constructor (tests included) stays network-silent and the endpoint
	// degrades to "current is latest".
	UpdateCheck bool

	// WorkspaceDir overrides the default working directory new web sessions
	// are created with (see config.Config.WorkspaceDir / tools.ResolveWorkspaceDir).
	// Empty (default) falls back to ~/.octo/config.yml's workspace_dir, then
	// to no override at all — unchanged from today's curCwd() behavior. No
	// `octo serve` flag sets this; it exists mainly so tests can inject a
	// literal path without touching the real config file.
	WorkspaceDir string
}

Config holds server-level settings.

type Server

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

Server is the HTTP server skeleton. It owns the mux, the agent factory, and the in-memory turn lock (one turn per session at a time).

func New

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

New builds a Server. It resolves provider/model, discovers skills, and resolves the access key that gates non-loopback requests.

func (*Server) AccessKey

func (s *Server) AccessKey() string

AccessKey returns the shared secret that authenticates Web UI and API requests from non-loopback clients.

func (*Server) CreateSession

func (s *Server) CreateSession(task scheduler.Task) (string, error)

CreateSession implements scheduler.Runner. It creates or reuses the session for a task and persists it immediately so the web UI can open the session before the (potentially long) agent turn starts.

func (*Server) ListenAndServe

func (s *Server) ListenAndServe() error

ListenAndServe starts the HTTP server. The cron scheduler is armed before serving so persisted tasks fire from server start, not from the first hit on a task endpoint.

func (*Server) Restart

func (s *Server) Restart(reason string)

Restart requests a graceful restart. It is idempotent — only the first call wins — and returns immediately; the drain and shutdown run in the background so the caller (an HTTP handler or a tool executing inside a turn, whose own turn the drain waits for) is not blocked. reason is logged for the operator.

func (*Server) RunTask

func (s *Server) RunTask(ctx context.Context, task scheduler.Task) (string, error)

RunTask implements scheduler.Runner. It executes a scheduled task by creating (or reusing) a session and running a single streamed turn, so any subscribed web UI tab sees the same live progress, tool cards, and completion events as a normal chat turn.

func (*Server) SetSubscribed

func (s *Server) SetSubscribed(conn *wsConn, sessionID string)

SetSubscribed records the active session subscription for a connection.

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the server, releasing the process-global sub-agent + task registrations installed by enableSubAgentTools.

It is single-flight: Restart's background shutdown and the Ctrl-C signal path can race here, and the body mutates process-global registries that must not be torn down twice concurrently. The first caller runs the shutdown; later callers wait for it to finish (or their ctx to expire) and return the same error.