appserver

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Jul 30, 2026 License: MIT Imports: 37 Imported by: 0

Documentation

Overview

Package appserver wires Gollem's Codex-style app-server protocol to the first runtime services. Transports should stay thin and delegate request, notification, and lifecycle semantics to this package.

Index

Constants

View Source 
const (
	InteractionRequestUserInput = "item/tool/requestUserInput"
	InteractionToolCall         = "item/tool/call"
	InteractionMCPElicitation   = "mcpServer/elicitation/request"
)

Variables

View Source 
var (
	ErrMemoryRootRequired = errors.New("appserver/memory: root is required")
	ErrMemoryRootUnsafe   = errors.New("appserver/memory: refusing unsafe root")
)
View Source 
var (
	ErrRuntimeNotConfigured       = errors.New("appserver/runtime: model factory is not configured")
	ErrRuntimeTurnActive          = errors.New("appserver/runtime: turn is already running")
	ErrRuntimeTurnNotActive       = errors.New("appserver/runtime: turn is not running")
	ErrRuntimePromptEmpty         = errors.New("appserver/runtime: prompt is required")
	ErrRuntimeShuttingDown        = errors.New("appserver/runtime: runtime is shutting down")
	ErrRuntimeRecoveryUnavailable = errors.New("appserver/runtime: store does not support restart recovery")
)
View Source 
var (
	ErrRuntimeSteerIdempotencyConflict = errors.New("appserver/runtime: steer idempotency conflict")
	ErrRuntimeSteerMessageTooLarge     = errors.New("appserver/runtime: steer message is too large")
	ErrRuntimeSteerIDTooLarge          = errors.New("appserver/runtime: steer client message ID is too large")
)
View Source 
var (
	ErrWorkspaceRevertInProgress = errors.New("appserver: workspace file-change revert is in progress")
	ErrWorkspaceTurnActive       = errors.New("appserver: workspace turn is active")
)
View Source 
var ErrApprovalRequestDenied = errors.New("appserver: approval request denied")
View Source 
var ErrInteractionRequestFailed = errors.New("appserver: interaction request failed")

Functions

func FilesystemRuntimeTools 

func FilesystemRuntimeTools(service *toolfs.Service) []core.Tool

FilesystemRuntimeTools adapts the scoped app-server filesystem service into provider-neutral model tools. Mutations retain the service's approval and audit hooks and publish bounded artifact evidence on the active run bus.

func GitRuntimeTools 

func GitRuntimeTools(service *toolgit.Service) []core.Tool

GitRuntimeTools adapts the repository-scoped Git service into provider-neutral model tools. Read operations are bounded; commit and worktree creation retain the service's approval, audit, and path guards.

func InteractionRuntimeTools 

func InteractionRuntimeTools(service *InteractionService) []core.Tool

InteractionRuntimeTools exposes the shared server-request service to active model turns. Requests carry durable runtime item correlation and are removed from the pending registry when the turn, caller, or per-request timeout ends.

func MCPRuntimeTools 

func MCPRuntimeTools(service *appmcp.Service, approvals *ApprovalService) []core.Tool

MCPRuntimeTools adapts the app-server MCP registry into bounded, provider-neutral model tools. Tool calls retain app-server approval and emit dedicated MCP item lifecycle events.

func ProcessExitedNotification 

func ProcessExitedNotification(event toolprocess.ExitEvent) (string, any)

func ProcessOutputNotification 

func ProcessOutputNotification(event toolprocess.OutputEvent) (string, any)

func ProcessRuntimeTools 

func ProcessRuntimeTools(service *toolprocess.Service) []core.Tool

ProcessRuntimeTools adapts the workspace-scoped process service into provider-neutral model tools. Command execution remains approval-backed and publishes command lifecycle events for durable runtime item tracking.

func ServeJSONLines 

func ServeJSONLines(ctx context.Context, server *Server, reader io.Reader, writer io.Writer) error

ServeJSONLines serves newline-delimited JSON-RPC messages over the supplied reader and writer. It is intended for stdio first, but tests and future transports can reuse it for any ordered byte stream.

func ServeWebSocket 

func ServeWebSocket(ctx context.Context, server *Server, conn *websocket.Conn) error

ServeWebSocket serves one app-server connection over WebSocket text frames. Each incoming text or binary message must contain one JSON-RPC object; each response, server request, or notification is written as one text message.

Types

type ApprovalService 

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

ApprovalService bridges synchronous tool approval hooks to app-server server-to-client approval requests resolved directly or by approval/respond.

func NewApprovalService 

func NewApprovalService() *ApprovalService

func (*ApprovalService) DrainRequests 

func (s *ApprovalService) DrainRequests() []protocol.Request

func (*ApprovalService) FilesystemApproval 

func (s *ApprovalService) FilesystemApproval(ctx context.Context, op toolfs.Operation) error

func (*ApprovalService) GitApproval 

func (s *ApprovalService) GitApproval(ctx context.Context, op toolgit.Operation) error

func (*ApprovalService) MCPToolApproval 

func (s *ApprovalService) MCPToolApproval(ctx context.Context, serverName, toolName string, args map[string]any) error

func (*ApprovalService) ProcessApproval 

func (s *ApprovalService) ProcessApproval(ctx context.Context, op toolprocess.Operation) error

func (*ApprovalService) RequestSignal 

func (s *ApprovalService) RequestSignal() <-chan struct{}

func (*ApprovalService) Respond 

func (s *ApprovalService) Respond(params approvalRespondParams) (approvalRespondResult, error)

func (*ApprovalService) RespondResponse 

func (s *ApprovalService) RespondResponse(resp protocol.Response) (approvalResponseResult, bool, error)

type DaemonOption 

type DaemonOption func(*DaemonService)

func WithDaemonName 

func WithDaemonName(name string) DaemonOption

func WithDaemonStorePath 

func WithDaemonStorePath(storePath string) DaemonOption

func WithDaemonTransport 

func WithDaemonTransport(transport string) DaemonOption

func WithDaemonVersion 

func WithDaemonVersion(version string) DaemonOption

func WithDaemonWorkDir 

func WithDaemonWorkDir(workDir string) DaemonOption

type DaemonService 

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

func NewDaemonService 

func NewDaemonService(opts ...DaemonOption) *DaemonService

func (*DaemonService) Restart 

func (d *DaemonService) Restart(reason string) DaemonStopResult

func (*DaemonService) ShutdownRequested 

func (d *DaemonService) ShutdownRequested() bool

func (*DaemonService) Start 

func (d *DaemonService) Start() DaemonStartResult

func (*DaemonService) Status 

func (d *DaemonService) Status() DaemonStatus

func (*DaemonService) Stop 

func (d *DaemonService) Stop(reason string) DaemonStopResult

func (*DaemonService) Version 

func (d *DaemonService) Version() DaemonVersion

type DaemonStartResult 

type DaemonStartResult = protocol.DaemonStartResult

type DaemonStatus 

type DaemonStatus = protocol.DaemonStatus

type DaemonStopResult 

type DaemonStopResult = protocol.DaemonStopResult

type DaemonVersion 

type DaemonVersion = protocol.DaemonVersion

type DynamicToolCallRequest 

type DynamicToolCallRequest struct {
	ThreadID  string          `json:"threadId,omitempty"`
	TurnID    string          `json:"turnId,omitempty"`
	ItemID    string          `json:"itemId,omitempty"`
	CallID    string          `json:"callId,omitempty"`
	Namespace *string         `json:"namespace"`
	ToolName  string          `json:"toolName"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	Metadata  map[string]any  `json:"metadata,omitempty"`
}

type EventQueue 

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

EventQueue buffers server-to-client app-server notifications for transports that need ordered delivery alongside request responses.

func NewEventQueue 

func NewEventQueue() *EventQueue

func (*EventQueue) Drain 

func (q *EventQueue) Drain(filter func(string) bool) []protocol.Notification

func (*EventQueue) Publish 

func (q *EventQueue) Publish(method string, params any)

func (*EventQueue) PublishRaw 

func (q *EventQueue) PublishRaw(method string, params json.RawMessage)

func (*EventQueue) Signal 

func (q *EventQueue) Signal() <-chan struct{}

type InteractionRequest 

type InteractionRequest struct {
	Method    string         `json:"method"`
	RequestID string         `json:"requestId,omitempty"`
	ThreadID  string         `json:"threadId,omitempty"`
	TurnID    string         `json:"turnId,omitempty"`
	ItemID    string         `json:"itemId,omitempty"`
	Reason    string         `json:"reason,omitempty"`
	Params    map[string]any `json:"params,omitempty"`
}

type InteractionRequestMeta 

type InteractionRequestMeta struct {
	RequestID string `json:"requestId"`
	Method    string `json:"method"`
	ThreadID  string `json:"threadId,omitempty"`
	TurnID    string `json:"turnId,omitempty"`
	ItemID    string `json:"itemId,omitempty"`
}

type InteractionResponse 

type InteractionResponse struct {
	InteractionRequestMeta
	Result json.RawMessage `json:"result,omitempty"`
	Error  *protocol.Error `json:"error,omitempty"`
}

type InteractionService 

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

InteractionService publishes runtime server-to-client interaction requests and resolves them from JSON-RPC responses sent by the client.

func NewInteractionService 

func NewInteractionService() *InteractionService

func (*InteractionService) Request 

func (s *InteractionService) Request(ctx context.Context, req InteractionRequest) (InteractionResponse, error)

func (*InteractionService) RequestMCPElicitation 

func (s *InteractionService) RequestMCPElicitation(ctx context.Context, req MCPElicitationRequest) (InteractionResponse, error)

func (*InteractionService) RequestToolCall 

func (s *InteractionService) RequestToolCall(ctx context.Context, req DynamicToolCallRequest) (InteractionResponse, error)

func (*InteractionService) RequestUserInput 

func (s *InteractionService) RequestUserInput(ctx context.Context, req UserInputRequest) (InteractionResponse, error)

func (*InteractionService) Respond 

func (s *InteractionService) Respond(resp protocol.Response) (InteractionResponse, bool, error)

type MCPElicitationRequest 

type MCPElicitationRequest struct {
	ThreadID string         `json:"threadId,omitempty"`
	TurnID   string         `json:"turnId,omitempty"`
	ItemID   string         `json:"itemId,omitempty"`
	ServerID string         `json:"serverId,omitempty"`
	Message  string         `json:"message"`
	Schema   map[string]any `json:"schema,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type MemoryResetResponse 

type MemoryResetResponse struct{}

type MemoryService 

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

func NewMemoryService 

func NewMemoryService(root string) (*MemoryService, error)

func (*MemoryService) Reset 

func (s *MemoryService) Reset(ctx context.Context) (MemoryResetResponse, error)

func (*MemoryService) Root 

func (s *MemoryService) Root() string

type Option 

type Option func(*Server)

Option configures a Server.

func WithApprovalService 

func WithApprovalService(approvals *ApprovalService) Option

func WithCache 

func WithCache(cache *appcache.Service) Option

func WithCatalog 

func WithCatalog(catalog *catalog.Catalog) Option

func WithConfig 

func WithConfig(config *appconfig.Service) Option

func WithDaemonService 

func WithDaemonService(daemon *DaemonService) Option

func WithEventQueue 

func WithEventQueue(events *EventQueue) Option

func WithFilesystem 

func WithFilesystem(fs *toolfs.Service) Option

func WithGit 

func WithGit(git *toolgit.Service) Option

func WithImplementationInfo 

func WithImplementationInfo(info protocol.ImplementationInfo) Option

func WithInitializeHome 

func WithInitializeHome(home string) Option

WithInitializeHome sets the absolute Gollem state root exposed through the Codex-compatible initialize response field.

func WithInteractionService 

func WithInteractionService(interactions *InteractionService) Option

func WithMCP 

func WithMCP(mcp *appmcp.Service) Option

func WithMemoryService 

func WithMemoryService(memory *MemoryService) Option

func WithProcess 

func WithProcess(process *toolprocess.Service) Option

func WithRequestSchedulerLimit 

func WithRequestSchedulerLimit(limit int) Option

func WithRuntimeService 

func WithRuntimeService(runtime *RuntimeService) Option

func WithSkills 

func WithSkills(skills *appskills.Service) Option

func WithStore 

func WithStore(st store.Store) Option

func WithThreadIdleUnloadAfter 

func WithThreadIdleUnloadAfter(after time.Duration) Option

func WithWorkspaceMutationCoordinator 

func WithWorkspaceMutationCoordinator(coordinator *WorkspaceMutationCoordinator) Option

WithWorkspaceMutationCoordinator shares exact-revert reservations across every transport connection that can mutate the same workspace.

type RequestLease 

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

RequestLease represents one accepted request slot.

func (*RequestLease) Release 

func (l *RequestLease) Release()

func (*RequestLease) Run 

func (l *RequestLease) Run(ctx context.Context, fn func() error) error

type RequestQueue 

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

RequestQueue buffers server-to-client app-server requests for transports that need ordered delivery alongside request responses.

func NewRequestQueue 

func NewRequestQueue() *RequestQueue

func (*RequestQueue) Drain 

func (q *RequestQueue) Drain() []protocol.Request

func (*RequestQueue) Publish 

func (q *RequestQueue) Publish(method string, id protocol.RequestID, params any)

func (*RequestQueue) PublishRaw 

func (q *RequestQueue) PublishRaw(req protocol.Request)

func (*RequestQueue) Signal 

func (q *RequestQueue) Signal() <-chan struct{}

type RequestSchedule 

type RequestSchedule struct {
	Scope  string
	Serial bool
}

func RequestScheduleFor 

func RequestScheduleFor(method string, params json.RawMessage) RequestSchedule

type RequestScheduler 

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

RequestScheduler bounds app-server request backlog and serializes requests that share a mutation-sensitive scope. Transports should bypass it only for initialize and approval responses that unblock a pending request.

func NewRequestScheduler 

func NewRequestScheduler(limit int) *RequestScheduler

func (*RequestScheduler) TryAcquire 

func (s *RequestScheduler) TryAcquire(method string, params json.RawMessage) (*RequestLease, *protocol.Error)

type RuntimeInterruptResult 

type RuntimeInterruptResult struct {
	OK     bool        `json:"ok"`
	TurnID string      `json:"turnId"`
	Turn   *store.Turn `json:"turn,omitempty"`
}

type RuntimeModelFactory 

type RuntimeModelFactory func(context.Context, RuntimeModelSelection) (core.Model, RuntimeModelInfo, error)

type RuntimeModelInfo 

type RuntimeModelInfo struct {
	ProviderID string `json:"providerId,omitempty"`
	Provider   string `json:"provider,omitempty"`
	Model      string `json:"model,omitempty"`
}

type RuntimeModelParams 

type RuntimeModelParams = protocol.RuntimeModelParams

type RuntimeModelSelection 

type RuntimeModelSelection struct {
	ProviderID string `json:"providerId,omitempty"`
	Provider   string `json:"provider,omitempty"`
	Model      string `json:"model,omitempty"`
}

type RuntimeOption 

type RuntimeOption func(*RuntimeService)

func WithRuntimeModel 

func WithRuntimeModel(model core.Model, info RuntimeModelInfo) RuntimeOption

func WithRuntimeModelFactory 

func WithRuntimeModelFactory(factory RuntimeModelFactory) RuntimeOption

func WithRuntimeTools 

func WithRuntimeTools(tools ...core.Tool) RuntimeOption

WithRuntimeTools registers provider-neutral core tools for app-server turns. Tool handlers are shared across turns and should be safe for concurrent use.

type RuntimeRetryRequest 

type RuntimeRetryRequest struct {
	SourceTurnID   string
	IdempotencyKey string
	Prompt         string
	Input          json.RawMessage
	Metadata       map[string]any
	Selection      RuntimeModelSelection
	ModelSettings  core.ModelSettings
	History        []core.ModelMessage
}

type RuntimeRetryResult 

type RuntimeRetryResult struct {
	Turn           *store.Turn
	SourceTurnID   string
	IdempotencyKey string
	Reused         bool
}

type RuntimeService 

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

func NewRuntimeService 

func NewRuntimeService(opts ...RuntimeOption) *RuntimeService

func (*RuntimeService) Interrupt 

func (s *RuntimeService) Interrupt(ctx context.Context, st store.Store, turnID string) (*RuntimeInterruptResult, error)

func (*RuntimeService) IsActive 

func (s *RuntimeService) IsActive(turnID string) bool

func (*RuntimeService) Retry 

func (s *RuntimeService) Retry(ctx context.Context, st store.Store, notifier runtimeNotifier, req RuntimeRetryRequest) (*RuntimeRetryResult, error)

Retry starts at most one retry turn for an idempotency key. Replayed requests return the durable turn without launching the model again.

func (*RuntimeService) Shutdown 

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

func (*RuntimeService) Start 

func (s *RuntimeService) Start(ctx context.Context, st store.Store, notifier runtimeNotifier, req RuntimeStartRequest) (*RuntimeStartResult, error)

func (*RuntimeService) Steer added in v0.8.0 

func (s *RuntimeService) Steer(
	ctx context.Context,
	req RuntimeSteerRequest,
) (*RuntimeSteerResult, error)

type RuntimeStartRequest 

type RuntimeStartRequest struct {
	ThreadID      string
	Prompt        string
	Input         json.RawMessage
	Metadata      map[string]any
	Selection     RuntimeModelSelection
	ModelSettings core.ModelSettings
	History       []core.ModelMessage
	// contains filtered or unexported fields
}

type RuntimeStartResult 

type RuntimeStartResult struct {
	Turn *store.Turn `json:"turn"`
}

type RuntimeSteerRequest added in v0.8.0 

type RuntimeSteerRequest struct {
	ThreadID            string
	TurnID              string
	ClientUserMessageID string
	Message             string
}

type RuntimeSteerResult added in v0.8.0 

type RuntimeSteerResult struct {
	TurnID              string
	ClientUserMessageID string
	Item                *store.Item
	Reused              bool
}

type Server 

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

Server dispatches Codex-style app-server JSON-RPC requests to Gollem services. It is transport-neutral; stdio/socket/WebSocket layers can wrap it.

func NewServer 

func NewServer(opts ...Option) *Server

func (*Server) ClientCapabilities 

func (s *Server) ClientCapabilities() protocol.InitializeCapabilities

ClientCapabilities returns a defensive copy of the capabilities negotiated by the current connection.

func (*Server) DaemonShutdownRequested 

func (s *Server) DaemonShutdownRequested() bool

func (*Server) DrainNotifications 

func (s *Server) DrainNotifications() []protocol.Notification

func (*Server) DrainRequests 

func (s *Server) DrainRequests() []protocol.Request

func (*Server) HandleJSON 

func (s *Server) HandleJSON(ctx context.Context, data []byte) ([]byte, bool, error)

HandleJSON handles one raw JSON-RPC request or notification. Requests return a response payload and true. Notifications return false and no payload.

func (*Server) HandleNotification 

func (s *Server) HandleNotification(ctx context.Context, notification protocol.Notification) error

HandleNotification handles one client-to-server notification.

func (*Server) HandleRequest 

func (s *Server) HandleRequest(ctx context.Context, req protocol.Request) protocol.Response

HandleRequest handles one client-to-server request and always returns a JSON-RPC response.

func (*Server) HandleResponse 

func (s *Server) HandleResponse(ctx context.Context, resp protocol.Response) error

HandleResponse handles one client response to a server-to-client request.

func (*Server) NotificationEnabled 

func (s *Server) NotificationEnabled(method string) bool

NotificationEnabled reports whether the connected client opted out of a server notification method.

func (*Server) NotificationSignal 

func (s *Server) NotificationSignal() <-chan struct{}

func (*Server) PublishNotification 

func (s *Server) PublishNotification(method string, params any)

func (*Server) PublishProcessExited 

func (s *Server) PublishProcessExited(event toolprocess.ExitEvent)

func (*Server) PublishProcessOutput 

func (s *Server) PublishProcessOutput(event toolprocess.OutputEvent)

PublishProcessOutput publishes the generic process output notification and, for thread/shellCommand-owned processes, the Codex command-execution delta.

func (*Server) RequestSchedulerLimit 

func (s *Server) RequestSchedulerLimit() int

func (*Server) RequestSignal 

func (s *Server) RequestSignal() <-chan struct{}

type UserInputRequest 

type UserInputRequest struct {
	ThreadID         string         `json:"threadId,omitempty"`
	TurnID           string         `json:"turnId,omitempty"`
	ItemID           string         `json:"itemId,omitempty"`
	QuestionID       string         `json:"questionId,omitempty"`
	Header           string         `json:"header,omitempty"`
	Prompt           string         `json:"prompt"`
	Placeholder      string         `json:"placeholder,omitempty"`
	Required         bool           `json:"required,omitempty"`
	IsOther          bool           `json:"isOther,omitempty"`
	IsSecret         bool           `json:"isSecret,omitempty"`
	Options          []string       `json:"options,omitempty"`
	AutoResolutionMS *uint64        `json:"autoResolutionMs"`
	Metadata         map[string]any `json:"metadata,omitempty"`
}

type WorkspaceMutationCoordinator 

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

WorkspaceMutationCoordinator owns the daemon-wide exclusion state between exact reverts and operations that can start or rewrite workspace history.

func NewWorkspaceMutationCoordinator 

func NewWorkspaceMutationCoordinator() *WorkspaceMutationCoordinator

Source Files

View all Source files

Directories

Path Synopsis
Package cache provides app-server cache telemetry and deterministic benchmark fixtures for provider-neutral request normalization.
 Package cache provides app-server cache telemetry and deterministic benchmark fixtures for provider-neutral request normalization.
Package catalog exposes provider-neutral app-server metadata for models, providers, and built-in tools.
 Package catalog exposes provider-neutral app-server metadata for models, providers, and built-in tools.
Package config exposes Gollem app-server configuration, environment, permission, collaboration, and experimental-feature metadata.
 Package config exposes Gollem app-server configuration, environment, permission, collaboration, and experimental-feature metadata.
Package mcp exposes Gollem's MCP client manager through the app-server JSON-RPC contract.
 Package mcp exposes Gollem's MCP client manager through the app-server JSON-RPC contract.
Package protocol defines Gollem's app-server JSON-RPC contract.
 Package protocol defines Gollem's app-server JSON-RPC contract.
internal/cmd/schema command
Package skills discovers read-only Gollem skill and plugin metadata from configured filesystem roots for app-server clients.
 Package skills discovers read-only Gollem skill and plugin metadata from configured filesystem roots for app-server clients.
Package store provides durable app-server thread, turn, and item storage.
 Package store provides durable app-server thread, turn, and item storage.
tools
fs
Package fs provides workspace-scoped filesystem operations for the app-server API.
 Package fs provides workspace-scoped filesystem operations for the app-server API.
git
Package git provides repository-scoped Git and worktree operations for the app-server API.
 Package git provides repository-scoped Git and worktree operations for the app-server API.
process
Package process provides workspace-scoped process execution primitives for the app-server API.
 Package process provides workspace-scoped process execution primitives for the app-server API.

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.