Documentation
¶
Overview ¶
Package server exposes Peen's client-facing Serbewr HTTP API.
Index ¶
- Constants
- Variables
- type Dependencies
- type Server
- func (s *Server) BroadcastDurableSessionEvents(sessionID uuid.UUID, events []session.EventInput)
- func (s *Server) CancelSession(ctx context.Context, request api.CancelSessionRequestObject) (api.CancelSessionResponseObject, error)
- func (s *Server) CancelSessionAgentRun(ctx context.Context, request api.CancelSessionAgentRunRequestObject) (api.CancelSessionAgentRunResponseObject, error)
- func (s *Server) GetSession(ctx context.Context, request api.GetSessionRequestObject) (api.GetSessionResponseObject, error)
- func (s *Server) GetSessionAgentRun(ctx context.Context, request api.GetSessionAgentRunRequestObject) (api.GetSessionAgentRunResponseObject, error)
- func (s *Server) GetSessionAgentRunCompaction(ctx context.Context, request api.GetSessionAgentRunCompactionRequestObject) (api.GetSessionAgentRunCompactionResponseObject, error)
- func (s *Server) GetSessionCompaction(ctx context.Context, request api.GetSessionCompactionRequestObject) (api.GetSessionCompactionResponseObject, error)
- func (s *Server) GetSessionContextSnapshot(ctx context.Context, request api.GetSessionContextSnapshotRequestObject) (api.GetSessionContextSnapshotResponseObject, error)
- func (s *Server) GetSessionPromptSnapshot(ctx context.Context, request api.GetSessionPromptSnapshotRequestObject) (api.GetSessionPromptSnapshotResponseObject, error)
- func (s *Server) ListAgentSpaces(ctx context.Context, _ api.ListAgentSpacesRequestObject) (api.ListAgentSpacesResponseObject, error)
- func (s *Server) ListMessages(ctx context.Context, request api.ListMessagesRequestObject) (api.ListMessagesResponseObject, error)
- func (s *Server) ListModels(ctx context.Context, _ api.ListModelsRequestObject) (api.ListModelsResponseObject, error)
- func (s *Server) ListSessionAgentRunCompactions(ctx context.Context, request api.ListSessionAgentRunCompactionsRequestObject) (api.ListSessionAgentRunCompactionsResponseObject, error)
- func (s *Server) ListSessionAgentRunEvents(ctx context.Context, request api.ListSessionAgentRunEventsRequestObject) (api.ListSessionAgentRunEventsResponseObject, error)
- func (s *Server) ListSessionAgentRunMessages(ctx context.Context, request api.ListSessionAgentRunMessagesRequestObject) (api.ListSessionAgentRunMessagesResponseObject, error)
- func (s *Server) ListSessionAgentRuns(ctx context.Context, request api.ListSessionAgentRunsRequestObject) (api.ListSessionAgentRunsResponseObject, error)
- func (s *Server) ListSessionAgentSpaceDecisions(ctx context.Context, request api.ListSessionAgentSpaceDecisionsRequestObject) (api.ListSessionAgentSpaceDecisionsResponseObject, error)
- func (s *Server) ListSessionCompactions(ctx context.Context, request api.ListSessionCompactionsRequestObject) (api.ListSessionCompactionsResponseObject, error)
- func (s *Server) ListSessionEvents(ctx context.Context, request api.ListSessionEventsRequestObject) (api.ListSessionEventsResponseObject, error)
- func (s *Server) ListSessionJobSignalRequests(ctx context.Context, request api.ListSessionJobSignalRequestsRequestObject) (api.ListSessionJobSignalRequestsResponseObject, error)
- func (s *Server) ListSessionJobs(ctx context.Context, request api.ListSessionJobsRequestObject) (api.ListSessionJobsResponseObject, error)
- func (s *Server) ListSessionModelRunCalls(ctx context.Context, request api.ListSessionModelRunCallsRequestObject) (api.ListSessionModelRunCallsResponseObject, error)
- func (s *Server) ListSessionModelRuns(ctx context.Context, request api.ListSessionModelRunsRequestObject) (api.ListSessionModelRunsResponseObject, error)
- func (s *Server) ListSessionNotices(ctx context.Context, request api.ListSessionNoticesRequestObject) (api.ListSessionNoticesResponseObject, error)
- func (s *Server) ListSessionTurns(ctx context.Context, request api.ListSessionTurnsRequestObject) (api.ListSessionTurnsResponseObject, error)
- func (s *Server) ListSessionWorkers(ctx context.Context, request api.ListSessionWorkersRequestObject) (api.ListSessionWorkersResponseObject, error)
- func (s *Server) ListSessions(ctx context.Context, request api.ListSessionsRequestObject) (api.ListSessionsResponseObject, error)
- func (s *Server) ListWorkspaceRoots(ctx context.Context, _ api.ListWorkspaceRootsRequestObject) (api.ListWorkspaceRootsResponseObject, error)
- func (s *Server) OpenSession(ctx context.Context, request api.OpenSessionRequestObject) (api.OpenSessionResponseObject, error)
- func (s *Server) PublishSessionNotice(ctx context.Context, request api.PublishSessionNoticeRequestObject) (api.PublishSessionNoticeResponseObject, error)
- func (s *Server) ReadSessionJobOutput(ctx context.Context, request api.ReadSessionJobOutputRequestObject) (api.ReadSessionJobOutputResponseObject, error)
- func (s *Server) ReconfigureSession(ctx context.Context, request api.ReconfigureSessionRequestObject) (api.ReconfigureSessionResponseObject, error)
- func (s *Server) Serve(ctx context.Context) error
- func (s *Server) SignalSessionJob(ctx context.Context, request api.SignalSessionJobRequestObject) (api.SignalSessionJobResponseObject, error)
- func (s *Server) Stop(ctx context.Context) error
- type SessionRegistry
- type TurnRouter
Constants ¶
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 ¶
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 ¶
func (s *Server) CancelSession( ctx context.Context, request api.CancelSessionRequestObject, ) (api.CancelSessionResponseObject, error)
CancelSession asks an active agent turn to stop without deleting its session.
func (*Server) CancelSessionAgentRun ¶
func (s *Server) CancelSessionAgentRun( ctx context.Context, request api.CancelSessionAgentRunRequestObject, ) (api.CancelSessionAgentRunResponseObject, error)
CancelSessionAgentRun stops one child agent without ending its parent turn.
func (*Server) GetSession ¶
func (s *Server) GetSession( ctx context.Context, request api.GetSessionRequestObject, ) (api.GetSessionResponseObject, error)
GetSession returns durable metadata and active-turn state for one session.
func (*Server) GetSessionAgentRun ¶ added in v0.4.0
func (s *Server) GetSessionAgentRun( ctx context.Context, request api.GetSessionAgentRunRequestObject, ) (api.GetSessionAgentRunResponseObject, error)
GetSessionAgentRun returns all persisted data for one child-agent run.
func (*Server) GetSessionAgentRunCompaction ¶ added in v0.11.0
func (s *Server) GetSessionAgentRunCompaction( ctx context.Context, request api.GetSessionAgentRunCompactionRequestObject, ) (api.GetSessionAgentRunCompactionResponseObject, error)
GetSessionAgentRunCompaction reads one immutable child compaction.
func (*Server) GetSessionCompaction ¶ added in v0.4.0
func (s *Server) GetSessionCompaction( ctx context.Context, request api.GetSessionCompactionRequestObject, ) (api.GetSessionCompactionResponseObject, error)
GetSessionCompaction returns one immutable compaction record for one session.
func (*Server) GetSessionContextSnapshot ¶ added in v0.4.0
func (s *Server) GetSessionContextSnapshot( ctx context.Context, request api.GetSessionContextSnapshotRequestObject, ) (api.GetSessionContextSnapshotResponseObject, error)
GetSessionContextSnapshot returns one session-referenced context snapshot.
func (*Server) GetSessionPromptSnapshot ¶ added in v0.4.0
func (s *Server) GetSessionPromptSnapshot( ctx context.Context, request api.GetSessionPromptSnapshotRequestObject, ) (api.GetSessionPromptSnapshotResponseObject, error)
GetSessionPromptSnapshot returns one session-referenced prompt snapshot.
func (*Server) ListAgentSpaces ¶ added in v0.19.0
func (s *Server) ListAgentSpaces( ctx context.Context, _ api.ListAgentSpacesRequestObject, ) (api.ListAgentSpacesResponseObject, error)
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 ¶
func (s *Server) ListMessages( ctx context.Context, request api.ListMessagesRequestObject, ) (api.ListMessagesResponseObject, error)
ListMessages returns one stable bounded durable transcript page.
func (*Server) ListModels ¶ added in v0.12.0
func (s *Server) ListModels( ctx context.Context, _ api.ListModelsRequestObject, ) (api.ListModelsResponseObject, error)
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
func (s *Server) ListSessionAgentRunCompactions( ctx context.Context, request api.ListSessionAgentRunCompactionsRequestObject, ) (api.ListSessionAgentRunCompactionsResponseObject, error)
ListSessionAgentRunCompactions returns one child's compaction lineage.
func (*Server) ListSessionAgentRunEvents ¶
func (s *Server) ListSessionAgentRunEvents( ctx context.Context, request api.ListSessionAgentRunEventsRequestObject, ) (api.ListSessionAgentRunEventsResponseObject, error)
ListSessionAgentRunEvents follows what one child agent is doing.
func (*Server) ListSessionAgentRunMessages ¶ added in v0.11.0
func (s *Server) ListSessionAgentRunMessages( ctx context.Context, request api.ListSessionAgentRunMessagesRequestObject, ) (api.ListSessionAgentRunMessagesResponseObject, error)
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 ¶
func (s *Server) ListSessionAgentRuns( ctx context.Context, request api.ListSessionAgentRunsRequestObject, ) (api.ListSessionAgentRunsResponseObject, error)
ListSessionAgentRuns reports the child agents this session has launched.
func (*Server) ListSessionAgentSpaceDecisions ¶ added in v0.19.0
func (s *Server) ListSessionAgentSpaceDecisions( ctx context.Context, request api.ListSessionAgentSpaceDecisionsRequestObject, ) (api.ListSessionAgentSpaceDecisionsResponseObject, error)
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
func (s *Server) ListSessionCompactions( ctx context.Context, request api.ListSessionCompactionsRequestObject, ) (api.ListSessionCompactionsResponseObject, error)
ListSessionCompactions returns every durable summary record for one session.
func (*Server) ListSessionEvents ¶
func (s *Server) ListSessionEvents( ctx context.Context, request api.ListSessionEventsRequestObject, ) (api.ListSessionEventsResponseObject, error)
ListSessionEvents returns durable protocol history without consuming it.
func (*Server) ListSessionJobSignalRequests ¶ added in v0.4.0
func (s *Server) ListSessionJobSignalRequests( ctx context.Context, request api.ListSessionJobSignalRequestsRequestObject, ) (api.ListSessionJobSignalRequestsResponseObject, error)
ListSessionJobSignalRequests returns the durable signal-request history for one process job.
func (*Server) ListSessionJobs ¶
func (s *Server) ListSessionJobs( ctx context.Context, request api.ListSessionJobsRequestObject, ) (api.ListSessionJobsResponseObject, error)
ListSessionJobs reports the commands this session has started.
func (*Server) ListSessionModelRunCalls ¶ added in v0.4.0
func (s *Server) ListSessionModelRunCalls( ctx context.Context, request api.ListSessionModelRunCallsRequestObject, ) (api.ListSessionModelRunCallsResponseObject, error)
ListSessionModelRunCalls returns every provider round for one model run.
func (*Server) ListSessionModelRuns ¶ added in v0.4.0
func (s *Server) ListSessionModelRuns( ctx context.Context, request api.ListSessionModelRunsRequestObject, ) (api.ListSessionModelRunsResponseObject, error)
ListSessionModelRuns returns durable logical model invocations.
func (*Server) ListSessionNotices ¶ added in v0.4.0
func (s *Server) ListSessionNotices( ctx context.Context, request api.ListSessionNoticesRequestObject, ) (api.ListSessionNoticesResponseObject, error)
ListSessionNotices returns durable notice history without consuming it.
func (*Server) ListSessionTurns ¶ added in v0.4.0
func (s *Server) ListSessionTurns( ctx context.Context, request api.ListSessionTurnsRequestObject, ) (api.ListSessionTurnsResponseObject, error)
ListSessionTurns returns the durable turn lifecycle for one session.
func (*Server) ListSessionWorkers ¶ added in v0.8.0
func (s *Server) ListSessionWorkers( ctx context.Context, request api.ListSessionWorkersRequestObject, ) (api.ListSessionWorkersResponseObject, error)
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
func (s *Server) ListSessions( ctx context.Context, request api.ListSessionsRequestObject, ) (api.ListSessionsResponseObject, error)
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
func (s *Server) ListWorkspaceRoots( ctx context.Context, _ api.ListWorkspaceRootsRequestObject, ) (api.ListWorkspaceRootsResponseObject, error)
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
func (s *Server) OpenSession( ctx context.Context, request api.OpenSessionRequestObject, ) (api.OpenSessionResponseObject, error)
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
func (s *Server) PublishSessionNotice( ctx context.Context, request api.PublishSessionNoticeRequestObject, ) (api.PublishSessionNoticeResponseObject, error)
PublishSessionNotice records an outside report against a session.
func (*Server) ReadSessionJobOutput ¶
func (s *Server) ReadSessionJobOutput( ctx context.Context, request api.ReadSessionJobOutputRequestObject, ) (api.ReadSessionJobOutputResponseObject, error)
ReadSessionJobOutput returns a bounded window of one job's output.
func (*Server) ReconfigureSession ¶ added in v0.8.0
func (s *Server) ReconfigureSession( ctx context.Context, request api.ReconfigureSessionRequestObject, ) (api.ReconfigureSessionResponseObject, error)
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) SignalSessionJob ¶
func (s *Server) SignalSessionJob( ctx context.Context, request api.SignalSessionJobRequestObject, ) (api.SignalSessionJobResponseObject, error)
SignalSessionJob stops one running job.
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.