server

package
v0.20.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package server exposes Peen's client-facing Serbewr HTTP API.

Index

Constants

View Source
const (
	// ErrorCodeInvalidSessionID reports a malformed X-Session-ID header.
	ErrorCodeInvalidSessionID aichteeteapee.ErrorCode = "INVALID_SESSION_ID"
	// ErrorCodeSessionNotFound reports a well-formed but unknown session ID.
	ErrorCodeSessionNotFound aichteeteapee.ErrorCode = "SESSION_NOT_FOUND"
	// ErrorCodeSessionBusy reports a session with an already active turn.
	ErrorCodeSessionBusy aichteeteapee.ErrorCode = "SESSION_BUSY"
	// ErrorCodeTurnCancelled reports a turn that ended because its session
	// was explicitly cancelled.
	ErrorCodeTurnCancelled aichteeteapee.ErrorCode = "TURN_CANCELLED"
	// ErrorCodeUserMessageQueueFull reports an active turn that cannot accept
	// another queued user message.
	ErrorCodeUserMessageQueueFull = aichteeteapee.ErrorCode(
		"USER_MESSAGE_QUEUE_FULL",
	)
	// ErrorCodeAgentSpaceNotAllowed reports a named agent space the
	// deployment does not offer. It is a refusal rather than a not-found,
	// because the allowed set is operator policy and the response never names
	// which agent spaces exist.
	ErrorCodeAgentSpaceNotAllowed = aichteeteapee.ErrorCode(
		"AGENT_SPACE_NOT_ALLOWED",
	)
	// ErrorCodeWorkspaceNotAllowed reports a requested workspace that falls
	// outside every configured workspace root. It is distinct from a
	// validation failure because the path is well formed and the deployment
	// simply does not expose it.
	ErrorCodeWorkspaceNotAllowed = aichteeteapee.ErrorCode(
		"WORKSPACE_NOT_ALLOWED",
	)
	// ErrorCodeWorkspaceNotFound reports an admitted workspace path whose
	// directory no longer exists.
	ErrorCodeWorkspaceNotFound = aichteeteapee.ErrorCode(
		"WORKSPACE_NOT_FOUND",
	)
	// ErrorCodeHarnessConfigurationInvalid reports a harness safety bound that
	// prevents a turn from starting. Malformed optional definitions emit a
	// harness.warning event instead.
	ErrorCodeHarnessConfigurationInvalid = aichteeteapee.ErrorCode(
		"HARNESS_CONFIGURATION_INVALID",
	)
)

Peen's documented contract distinguishes four session-scoped failures that aichteeteapee's generic codes would otherwise collapse into NOT_FOUND, CONFLICT, and BAD_REQUEST. aichteeteapee.ErrorCode is a plain string alias, so Peen defines its own values on it rather than rolling a separate error envelope.

Variables

View Source
var ErrMissingDependency = errors.New("HTTP server dependency is required")

ErrMissingDependency reports an incomplete HTTP server constructor input.

Functions

This section is empty.

Types

type Dependencies

type Dependencies struct {
	Runtime agent.API

	// Sessions opens and lists workspace sessions. It is the control surface's
	// registry rather than the runtime, because opening a workspace is a
	// control operation bounded by deployment policy, not part of running a
	// turn.
	Sessions SessionRegistry

	// Turns dispatches an accepted client message to the session's worker. The
	// control plane routes work; it does not run the model loop.
	Turns TurnRouter

	APIToken       string
	ListenAddress  string
	Metrics        *metrics.Metrics
	ServiceContext func() context.Context
}

Dependencies are the transport-neutral operations required by the API.

type Server

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

Server owns Peen's Serbewr listener and its generated OpenAPI handler.

func New

func New(deps Dependencies) (*Server, error)

New constructs a fully-wired HTTP server without opening a listener.

func (*Server) BroadcastDurableSessionEvents added in v0.8.0

func (s *Server) BroadcastDurableSessionEvents(
	sessionID uuid.UUID,
	events []session.EventInput,
)

BroadcastDurableSessionEvents fans out events the controller has already written.

It is the live half of the worker event path: a worker's durable write lands in SQLite first, and only then does the controller hand the same records here for delivery. A client therefore never sees an event the database does not already hold.

func (*Server) CancelSession

CancelSession asks an active agent turn to stop without deleting its session.

func (*Server) CancelSessionAgentRun

CancelSessionAgentRun stops one child agent without ending its parent turn.

func (*Server) GetSession

GetSession returns durable metadata and active-turn state for one session.

func (*Server) GetSessionAgentRun added in v0.4.0

GetSessionAgentRun returns all persisted data for one child-agent run.

func (*Server) GetSessionAgentRunCompaction added in v0.11.0

GetSessionAgentRunCompaction reads one immutable child compaction.

func (*Server) GetSessionCompaction added in v0.4.0

GetSessionCompaction returns one immutable compaction record for one session.

func (*Server) GetSessionContextSnapshot added in v0.4.0

GetSessionContextSnapshot returns one session-referenced context snapshot.

func (*Server) GetSessionPromptSnapshot added in v0.4.0

GetSessionPromptSnapshot returns one session-referenced prompt snapshot.

func (*Server) ListAgentSpaces added in v0.19.0

ListAgentSpaces reports the agent spaces a client may name when it opens a workspace. It takes no session header because a client reads it before it has a session.

func (*Server) ListMessages

ListMessages returns one stable bounded durable transcript page.

func (*Server) ListModels added in v0.12.0

ListModels returns the model references the controller discovered at startup. It does not contact an upstream or expose connection credentials.

func (*Server) ListSessionAgentRunCompactions added in v0.11.0

ListSessionAgentRunCompactions returns one child's compaction lineage.

func (*Server) ListSessionAgentRunEvents

ListSessionAgentRunEvents follows what one child agent is doing.

func (*Server) ListSessionAgentRunMessages added in v0.11.0

ListSessionAgentRunMessages returns one child agent run's own transcript.

A child agent runs a separate model context, so these rows are the child's and never the session's.

func (*Server) ListSessionAgentRuns

ListSessionAgentRuns reports the child agents this session has launched.

func (*Server) ListSessionAgentSpaceDecisions added in v0.19.0

ListSessionAgentSpaceDecisions reports one session's agent space change history, so an operator can see who moved it and why.

func (*Server) ListSessionCompactions added in v0.4.0

ListSessionCompactions returns every durable summary record for one session.

func (*Server) ListSessionEvents

ListSessionEvents returns durable protocol history without consuming it.

func (*Server) ListSessionJobSignalRequests added in v0.4.0

ListSessionJobSignalRequests returns the durable signal-request history for one process job.

func (*Server) ListSessionJobs

ListSessionJobs reports the commands this session has started.

func (*Server) ListSessionModelRunCalls added in v0.4.0

ListSessionModelRunCalls returns every provider round for one model run.

func (*Server) ListSessionModelRuns added in v0.4.0

ListSessionModelRuns returns durable logical model invocations.

func (*Server) ListSessionNotices added in v0.4.0

ListSessionNotices returns durable notice history without consuming it.

func (*Server) ListSessionTurns added in v0.4.0

ListSessionTurns returns the durable turn lifecycle for one session.

func (*Server) ListSessionWorkers added in v0.8.0

ListSessionWorkers reports one session's durable worker generations, so an operator can see which environment ran which turns.

func (*Server) ListSessions added in v0.8.0

ListSessions reports the sessions this control surface holds, so a client can discover them without already knowing a session ID.

func (*Server) ListWorkspaceRoots added in v0.13.0

ListWorkspaceRoots reports the configured workspace roots after normal API authentication, so the control surface can offer valid choices before a session exists.

func (*Server) OpenSession added in v0.8.0

OpenSession resolves a workspace path to its durable session, creating that session the first time the directory is opened.

This is the only operation that creates a session, which is what lets the control surface start with none.

func (*Server) PublishSessionNotice added in v0.4.0

PublishSessionNotice records an outside report against a session.

func (*Server) ReadSessionJobOutput

ReadSessionJobOutput returns a bounded window of one job's output.

func (*Server) ReconfigureSession added in v0.8.0

ReconfigureSession moves one idle session to a different agent space and records why. The client names only an agent space: the operator decides what that name means.

func (*Server) Serve

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

Serve listens until the service context is cancelled or the listener fails.

func (*Server) SignalSessionJob

SignalSessionJob stops one running job.

func (*Server) Stop added in v0.2.0

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

Stop shuts down Serbewr. It is safe to call after Serve has already stopped because Serbewr's shutdown is idempotent.

type SessionRegistry added in v0.8.0

type SessionRegistry interface {
	OpenWorkspaceSession(
		ctx context.Context,
		workspace string,
		agentSpace string,
	) (api.OpenedSession, error)
	ListSessions(
		ctx context.Context,
		params api.ListSessionsParams,
	) (api.SessionPage, error)
	WorkspaceRoots() api.WorkspaceRootList
	AgentSpaces() api.AgentSpaceList
	ListWorkerGenerations(
		ctx context.Context,
		sessionID uuid.UUID,
		params api.ListSessionWorkersParams,
	) (api.WorkerGenerationPage, error)
	ReconfigureSession(
		ctx context.Context,
		sessionID uuid.UUID,
		request api.ReconfigureSessionRequest,
	) (api.SessionAgentSpaceDecision, error)
	ListAgentSpaceDecisions(
		ctx context.Context,
		sessionID uuid.UUID,
		params api.ListSessionAgentSpaceDecisionsParams,
	) (api.SessionAgentSpaceDecisionPage, error)
}

SessionRegistry is the control-surface operation set the session endpoints need. It is an interface so the HTTP layer depends on the operations rather than the registry's construction.

type TurnRouter added in v0.8.0

type TurnRouter interface {
	// ReserveSessionMessage takes a message's place in its session's
	// admission line without waiting. The WebSocket runs each message on its
	// own goroutine, so it reserves while it still holds the receive order;
	// otherwise two messages sent back to back could reach the worker in
	// either order.
	ReserveSessionMessage(sessionID uuid.UUID) *session.AdmissionTicket

	// RunReservedSessionMessage runs the message once its reservation is
	// admitted and always releases the reservation.
	RunReservedSessionMessage(
		ctx context.Context,
		reservation *session.AdmissionTicket,
		request agent.MessageRequest,
		requestID uuid.UUID,
	) (*agent.MessageRunResult, error)

	// CancelSessionTurn reaches the worker process running the turn. The
	// controller records the request durably but cannot interrupt a model loop
	// that runs in another process, so cancellation has to travel the same
	// route the turn did.
	CancelSessionTurn(
		ctx context.Context,
		sessionID uuid.UUID,
	) (bool, error)

	// SignalSessionJob reaches the worker whose process group holds the job. A
	// nil response means no live worker holds it, which the caller records
	// against the durable row instead.
	SignalSessionJob(
		ctx context.Context,
		sessionID uuid.UUID,
		jobID uuid.UUID,
		signal string,
	) (*api.JobSignalResponse, error)
}

TurnRouter sends one accepted client message to its session's worker.

It is an interface so the HTTP layer depends on dispatching a turn rather than on how a worker is found or launched.

Jump to

Keyboard shortcuts

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