server

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Sep 11, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	AgentHandlerTUI = "tui"
	AgentHandlerCLI = "cli"
	AgentHandlerACP = "acp"
)

Well-known handler names are intentionally transport-oriented. They are selected inside an agent family, so a future ACP implementation can sit next to the existing TUI handler without creating a second agent kind.

Variables

View Source 
var ErrAgentNotReady = errors.New("agent is not ready")

ErrAgentNotReady means that a provider is known, but its binding or transport has not become observable yet. It is deliberately distinct from an unknown provider or a provider failure: the lifecycle reconciler keeps a placeholder for this case and retries on its next pass.

View Source 
var ErrAgentProviderNotFound = errors.New("agent provider is not registered")

ErrAgentProviderNotFound is returned when no provider has been registered for a Session kind.

Functions

func NewAgentProviderWithHandlers added in v0.12.0 

func NewAgentProviderWithHandlers(kind string, handlers ...AgentHandler) *handlerAgentProvider

func WarrenColorQuery 

func WarrenColorQuery(kind ghostline.ColorQueryKind) (string, bool)

WarrenColorQuery supplies Warren's Ember terminal colors to ghostline.

Types

type ACPAgentProvider added in v0.12.0 

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

ACPAgentProvider is a stub for the standardized bidirectional Agent Client Protocol (ACP). It implements AgentProvider and AgentProviderCapabilities for the "acp" handler kind.

func NewACPAgentProvider added in v0.12.0 

func NewACPAgentProvider(kind string, service *Service) *ACPAgentProvider

func (*ACPAgentProvider) Capabilities added in v0.12.0 

func (provider *ACPAgentProvider) Capabilities() CapabilitySet

Capabilities advertises Track 2 native bidirectional capabilities.

func (*ACPAgentProvider) Ensure added in v0.12.0 

func (provider *ACPAgentProvider) Ensure(ctx context.Context, value AgentSessionContext) (AgentHandle, error)

func (*ACPAgentProvider) HandlerKind added in v0.12.0 

func (provider *ACPAgentProvider) HandlerKind() string

func (*ACPAgentProvider) Kind added in v0.12.0 

func (provider *ACPAgentProvider) Kind() string

type AgentEventSink added in v0.12.0 

type AgentEventSink interface{}

AgentEventSink is intentionally permissive at the package boundary. The service accepts both method-based sinks (OnEvents/OnStatus/OnTurns or their shorter Events/Status/Turns spellings) and AgentEventSinkFuncs. Keeping the type open lets an ACP provider evolve callback details without another public interface migration.

type AgentEventSinkFuncs added in v0.12.0 

type AgentEventSinkFuncs struct {
	OnEvents func([]api.AgentEvent, api.AgentStatus)
	OnStatus func(api.AgentStatus)
	OnTurns  func([]api.AgentTurn, bool)
}

AgentEventSinkFuncs is the convenience implementation for providers and tests. Nil callbacks are allowed.

func (AgentEventSinkFuncs) Events added in v0.12.0 

func (sink AgentEventSinkFuncs) Events(events []api.AgentEvent, status api.AgentStatus)

func (AgentEventSinkFuncs) Status added in v0.12.0 

func (sink AgentEventSinkFuncs) Status(status api.AgentStatus)

func (AgentEventSinkFuncs) Turns added in v0.12.0 

func (sink AgentEventSinkFuncs) Turns(turns []api.AgentTurn, replay bool)

type AgentHandle added in v0.12.0 

type AgentHandle interface {
	Start(context.Context, AgentEventSink) error
	Capabilities() CapabilitySet

	SendMessage(context.Context, api.AgentMessageSendRequest) error
	Interrupt(context.Context, api.AgentTurnInterruptRequest) error
	RespondInteraction(context.Context, api.AgentInteractionResponse) error

	BindingKey() string
	Close() error
}

AgentHandle is the lifecycle boundary between Service and a concrete PTY or ACP implementation. Start and Close must be safe to call more than once.

type AgentHandler added in v0.12.0 

type AgentHandler interface {
	HandlerKind() string
	Ensure(context.Context, AgentSessionContext) (AgentHandle, error)
}

AgentHandler is the optional finer-grained provider contract. A provider family can expose several handlers (for example codex/tui and codex/acp) while the lifecycle service continues to depend only on AgentProvider.

type AgentProvider added in v0.12.0 

type AgentProvider interface {
	Kind() string
	Ensure(context.Context, AgentSessionContext) (AgentHandle, error)
}

AgentProvider creates a handle bound to one Warren Session. Providers own discovery and provider-specific parsing; the Service owns reconciliation.

type AgentProviderCapabilities added in v0.12.0 

type AgentProviderCapabilities interface {
	Capabilities() CapabilitySet
}

AgentProviderCapabilities is optional to keep the original two-method provider contract source-compatible. When present, Service intersects it with the selected handle's runtime capabilities before publishing a Session-level capability set.

type AgentProviderRegistry added in v0.12.0 

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

AgentProviderRegistry is concurrency-safe so a daemon can register a future provider while tests or embedders are reconciling existing sessions.

func NewAgentProviderRegistry added in v0.12.0 

func NewAgentProviderRegistry(providers ...AgentProvider) *AgentProviderRegistry

func NewAgentRegistry added in v0.12.0 

func NewAgentRegistry(providers ...AgentProvider) *AgentProviderRegistry

func NewDefaultAgentProviderRegistry added in v0.12.0 

func NewDefaultAgentProviderRegistry(service *Service) *AgentProviderRegistry

func NewTUIAgentProviderRegistry added in v0.12.0 

func NewTUIAgentProviderRegistry(service *Service) *AgentProviderRegistry

NewTUIAgentProviderRegistry registers every provider currently understood by the Host. A future ACP provider can be registered beside these adapters without changing Service reconciliation.

func (*AgentProviderRegistry) Ensure added in v0.12.0 

func (registry *AgentProviderRegistry) Ensure(ctx context.Context, session AgentSessionContext) (AgentHandle, error)

func (*AgentProviderRegistry) Get added in v0.12.0 

func (registry *AgentProviderRegistry) Get(kind string) AgentProvider

func (*AgentProviderRegistry) HandlerKinds added in v0.12.0 

func (registry *AgentProviderRegistry) HandlerKinds(kind string) []string

func (*AgentProviderRegistry) Kinds added in v0.12.0 

func (registry *AgentProviderRegistry) Kinds() []string

func (*AgentProviderRegistry) Provider added in v0.12.0 

func (registry *AgentProviderRegistry) Provider(kind string) (AgentProvider, bool)

func (*AgentProviderRegistry) ProviderFor added in v0.12.0 

func (registry *AgentProviderRegistry) ProviderFor(kind, handler string) (AgentProvider, bool)

ProviderFor resolves an agent family and its selected handler. Empty handler falls back to the family default provider.

func (*AgentProviderRegistry) Register added in v0.12.0 

func (registry *AgentProviderRegistry) Register(provider AgentProvider) error

func (*AgentProviderRegistry) RegisterAgentHandler added in v0.12.0 

func (registry *AgentProviderRegistry) RegisterAgentHandler(agentKind, handler string, provider AgentProvider) error

func (*AgentProviderRegistry) RegisterHandler added in v0.12.0 

func (registry *AgentProviderRegistry) RegisterHandler(provider AgentProvider, handler string) error

RegisterHandler adds a transport-specific implementation under an agent family. The provider's Kind remains the family key; HandlerKind is the second-level key and is deliberately not exposed on the wire.

func (*AgentProviderRegistry) RegisterOrReplace added in v0.12.0 

func (registry *AgentProviderRegistry) RegisterOrReplace(provider AgentProvider) error

func (*AgentProviderRegistry) RegisterWithHandler added in v0.12.0 

func (registry *AgentProviderRegistry) RegisterWithHandler(agentKind, handler string, provider AgentProvider) error

RegisterWithHandler is the explicit form useful when a provider's concrete type does not expose HandlerKind.

func (*AgentProviderRegistry) Unregister added in v0.12.0 

func (registry *AgentProviderRegistry) Unregister(kind string)

type AgentRegistry added in v0.12.0 

type AgentRegistry = AgentProviderRegistry

AgentRegistry is a shorter compatibility name for callers that do not need to spell out the Provider suffix.

type AgentSessionContext added in v0.12.0 

type AgentSessionContext struct {
	Session   api.Session
	SessionID string
	// Kind identifies the agent family (codex, claude, opencode, pi, qoder).
	Kind string
	// Handler selects the transport/runtime implementation inside that agent
	// family (normally tui, acp, or cli). Transport is an alias retained for
	// callers that use protocol terminology.
	Handler        string
	Transport      string
	WorkspacePath  string
	AgentSessionID string
	TranscriptPath string
	Runtime        string
	RuntimeKind    string
	Binding        string
}

AgentSessionContext is the provider-facing view of one Warren Session. The full API Session is retained for forward compatibility; the duplicated fields make fake providers and future ACP implementations independent from persistence details.

type AgentViewAtomicController added in v0.12.0 

type AgentViewAtomicController interface {
	InterruptAndSend(context.Context, api.AgentTurnInterruptRequest) error
}

AgentViewAtomicController is an optional stronger bridge for Hosts that can perform a provider-native interrupt and replacement in one transaction. AgentViewController remains deliberately small so existing embedders do not need to implement the new method; the built-in PTY bridge preserves ordering under a per-session action lock as a compatibility fallback.

type AgentViewController added in v0.12.0 

type AgentViewController interface {
	RespondInteraction(context.Context, api.AgentInteractionResponse) error
	InterruptTurn(context.Context, api.AgentTurnInterruptRequest) error
	SendMessage(context.Context, api.AgentMessageSendRequest) error
}

AgentViewController is an optional provider-native bridge. Hosts that have a provider API can install one; known TUI providers may use the bounded PTY fallback below for interaction and interrupt semantics.

type AgentViewGoalController added in v0.12.0 

type AgentViewGoalController interface {
	SetGoal(context.Context, api.AgentGoalSetRequest) error
	ClearGoal(context.Context, api.AgentGoalClearRequest) error
}

AgentViewGoalController is an optional provider-native bridge for Codex thread goals. It is separate from AgentViewController so existing Hosts can adopt the goal command without breaking their interaction implementation.

type AgentViewGoalHandle added in v0.12.0 

type AgentViewGoalHandle interface {
	SetGoal(context.Context, api.AgentGoalSetRequest) error
	ClearGoal(context.Context, api.AgentGoalClearRequest) error
}

AgentViewGoalHandle is the per-provider equivalent used by lifecycle handles. A handle may implement this without changing the AgentHandle contract consumed by existing providers.

type AtomicStateRuntime added in v0.10.0 

type AtomicStateRuntime interface {
	CursorOutputRuntime
	AtomicState(context.Context, string) (ghostline.AtomicState, error)
}

AtomicStateRuntime is the optional native-state recovery capability. The payload remains owned and versioned by Ghostline; Warren only pairs it with the browser-facing recovery anchor and transports it as an opaque frame.

type Capability added in v0.12.0 

type Capability string

Capability is the typed form used inside Headless. String values are only emitted at the protocol boundary. 

const (
	CapabilityTimeline     Capability = api.CapabilityAgentTimeline
	CapabilityInteractions Capability = api.CapabilityAgentInteractions
	CapabilityInterrupt    Capability = api.CapabilityAgentInterrupt
	CapabilityAttachments  Capability = api.CapabilityAgentAttachments
	CapabilityGoals        Capability = api.CapabilityAgentGoals
)

type CapabilitySet added in v0.12.0 

type CapabilitySet map[Capability]struct{}

CapabilitySet is an immutable-by-convention set of provider/transport capabilities. Constructors and set operations always return fresh maps so a provider cannot mutate a handle's advertised values through a shared map.

func CapabilitySetFromStrings added in v0.12.0 

func CapabilitySetFromStrings(values []string) CapabilitySet

CapabilitySetFromStrings is used only when crossing the existing string capability boundary (for example a client handshake or a test fixture).

func IntersectCapabilitySets added in v0.12.0 

func IntersectCapabilitySets(sets ...CapabilitySet) CapabilitySet

func NewCapabilitySet added in v0.12.0 

func NewCapabilitySet(values ...Capability) CapabilitySet

func (CapabilitySet) Clone added in v0.12.0 

func (set CapabilitySet) Clone() CapabilitySet

func (CapabilitySet) Contains added in v0.12.0 

func (set CapabilitySet) Contains(value Capability) bool

Contains is an alias that reads naturally at action call sites.

func (CapabilitySet) Has added in v0.12.0 

func (set CapabilitySet) Has(value Capability) bool

func (CapabilitySet) Strings added in v0.12.0 

func (set CapabilitySet) Strings() []string

type CursorOutputReader added in v0.10.0 

type CursorOutputReader interface {
	io.Reader
	io.Closer
	Cursor() ghostline.Cursor
}

CursorOutputReader is the small portion of Ghostline's reader contract that Warren needs. Keeping the service boundary interface-shaped lets tests and embedders provide deterministic readers without depending on Ghostline's concrete reader constructor; GhostlineRuntime still returns the native *ghostline.OutputReader behind this interface.

type CursorOutputRuntime added in v0.9.0 

type CursorOutputRuntime interface {
	Runtime
	Checkpoint(context.Context, string) (ghostline.Checkpoint, error)
	OpenOutput(context.Context, string, ghostline.Cursor) (CursorOutputReader, error)
}

CursorOutputRuntime is implemented by Ghostline v1. The service owns one reader per session and treats Cursor as an opaque durable token; the browser-facing output protocol deliberately continues to use its own lightweight sequence anchors.

type GhostlineRuntime 

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

GhostlineRuntime adapts ghostline's session-handle API to the name-based Runtime surface used by Service. Handles are cached by name and re-adopted from the server on demand, so a daemon restart keeps managing sessions owned by a detached ghostline serve process.

func NewGhostlineRuntime 

func NewGhostlineRuntime(client *ghostline.Client) *GhostlineRuntime

func (*GhostlineRuntime) AtomicState added in v0.10.0 

func (r *GhostlineRuntime) AtomicState(ctx context.Context, name string) (ghostline.AtomicState, error)

AtomicState captures Ghostty's native terminal state together with the first output cursor not represented by it. Warren treats the payload as an opaque runtime artifact and forwards its advertised format unchanged.

func (*GhostlineRuntime) Capture 

func (r *GhostlineRuntime) Capture(ctx context.Context, name string) ([]byte, error)

func (*GhostlineRuntime) Check 

func (r *GhostlineRuntime) Check(ctx context.Context) error

func (*GhostlineRuntime) Checkpoint added in v0.9.0 

func (r *GhostlineRuntime) Checkpoint(ctx context.Context, name string) (ghostline.Checkpoint, error)

Checkpoint captures a v1 replay together with an opaque output cursor. The Service owns the reader lifecycle so it never exposes or interprets v1 output storage paths.

func (*GhostlineRuntime) Create 

func (r *GhostlineRuntime) Create(ctx context.Context, name, directory, command string, env []string) error

func (*GhostlineRuntime) Exists 

func (r *GhostlineRuntime) Exists(ctx context.Context, name string) bool

func (*GhostlineRuntime) Input 

func (r *GhostlineRuntime) Input(ctx context.Context, name string, data []byte) error

func (*GhostlineRuntime) Kill 

func (r *GhostlineRuntime) Kill(ctx context.Context, name string) error

func (*GhostlineRuntime) List 

func (r *GhostlineRuntime) List(ctx context.Context) (map[string]bool, error)

func (*GhostlineRuntime) ListCreated 

func (r *GhostlineRuntime) ListCreated(ctx context.Context) (map[string]time.Time, error)

func (*GhostlineRuntime) Metadata 

func (r *GhostlineRuntime) Metadata(ctx context.Context, name string) (runtime.RuntimeMetadata, error)

Metadata reports the foreground process snapshot from ghostline when the server was started with ProbeForeground enabled. Older servers without the capability return empty metadata without failing the roster.

func (*GhostlineRuntime) OpenOutput added in v0.9.0 

func (r *GhostlineRuntime) OpenOutput(ctx context.Context, name string, cursor ghostline.Cursor) (CursorOutputReader, error)

OpenOutput creates one caller-owned v1 reader from an opaque cursor.

func (*GhostlineRuntime) Probe added in v0.12.0 

func (r *GhostlineRuntime) Probe(ctx context.Context, name string) RuntimeProbeResult

Probe preserves the distinction between an authoritative not-found/dead answer and an unavailable Ghostline server. Lifecycle reconciliation must never turn the latter into a durable Session end.

func (*GhostlineRuntime) Resize 

func (r *GhostlineRuntime) Resize(ctx context.Context, name string, columns, rows int) error

type HTTPServer 

type HTTPServer struct {
	Service *Service
	Token   string
	// AccessScopeID is the stable, non-secret visibility scope for direct
	// authenticated clients. Relay clients receive a derived scope from their
	// stable client ID so local replicas cannot collide across sharing scopes.
	AccessScopeID string
	Logger        *slog.Logger
	// RelayStart and RelayStop are installed by the daemon entrypoint. Keeping
	// lifecycle hooks on the HTTP server lets settings.put toggle the supervised
	// connector without touching Session or PTY ownership; tests and embedded
	// callers may leave them nil.
	RelayStart func() error
	RelayStop  func()
	// RelayEnroll performs a Host-initiated Relay claim. The callback owns the
	// daemon's Host credential and persists only non-secret Relay metadata.
	RelayEnroll func(context.Context, string, string, string) error
	// RelayReset removes the local Relay identity in addition to clearing the
	// persisted Relay metadata.
	RelayReset func() error
	// RelayRouteClient creates an authenticated client for the Relay route API.
	// Route lifecycle uses the same Host Secret as the BRLY/2 connector.
	RelayRouteClient func() (*relay.RouteClient, error)
	// RelayPairing creates a safe client-facing invite. The callback owns the
	// Host Secret and returns only an opaque URL plus its expiry metadata.
	RelayPairing func(context.Context) (relay.PairingResult, error)
	// RelayState is queried by /healthz to surface the supervised connector's
	// current state. Optional: a nil callback reports an unconfigured relay.
	RelayState    func() api.RelayHealth
	BuildVersion  string
	BuildRevision string
	BuildDirty    bool
	// GhostlineRPCVersion is the protocol version reported by the running
	// Ghostline server.
	GhostlineRPCVersion string
	// GhostlineTagVersion is the Ghostline Go module version compiled into
	// Warren.
	GhostlineTagVersion string
	CACertPath          string
	// contains filtered or unexported fields
}

func NewHTTPServer 

func NewHTTPServer(service *Service, token string, logger *slog.Logger) *HTTPServer

func (*HTTPServer) HandleRelayControl added in v0.12.0 

func (s *HTTPServer) HandleRelayControl(
	ctx context.Context,
	open relay.StreamOpen,
	value relay.Frame,
	send func(relay.Frame) error,
) error

HandleRelayControl adapts one BRLY/2 control stream to the daemon's normal wsPeer protocol. The Relay has already authenticated the client capability; the Host still validates the stream metadata and never forwards its Host Secret back across the transport. send is Connector.Send for the owning stream and is kept as a callback to avoid coupling this package to relay's connection state.

func (*HTTPServer) Handler 

func (s *HTTPServer) Handler() http.Handler

func (*HTTPServer) PairingOpen added in v0.13.0 

func (s *HTTPServer) PairingOpen() bool

PairingOpen reports whether the explicit Host-side pairing window is armed. Discovery uses this callback to update the non-secret `pair` TXT flag.

type LiveActivityPublisher added in v0.12.0 

type LiveActivityPublisher func(context.Context, LiveActivitySnapshot) error

LiveActivityPublisher is installed by the daemon entrypoint when an owned Relay is configured. A nil publisher leaves the Host fully functional while disabling optional mobile push delivery.

type LiveActivitySession added in v0.12.0 

type LiveActivitySession struct {
	ID         string `json:"id"`
	Title      string `json:"title,omitempty"`
	Connection string `json:"connection"`
	Activity   string `json:"activity,omitempty"`
	Attention  bool   `json:"attention,omitempty"`
}

LiveActivitySession is the bounded Host projection sent to Relay. It is deliberately independent from the full roster so push payloads never carry transcript text, paths, command lines, or credentials.

type LiveActivitySnapshot added in v0.12.0 

type LiveActivitySnapshot struct {
	Connection            string                `json:"connection"`
	ActiveSessionCount    int                   `json:"activeSessionCount"`
	WorkingSessionCount   int                   `json:"workingSessionCount"`
	AttentionSessionCount int                   `json:"attentionSessionCount"`
	Sessions              []LiveActivitySession `json:"sessions"`
	UpdatedAt             time.Time             `json:"updatedAt"`
}

LiveActivitySnapshot is a complete snapshot for one Host. Relay owns the registered ActivityKit tokens and fans this projection out per Session.

type PublicAccessService added in v0.12.0 

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

PublicAccessService is the single Host-owned use-case implementation for both the local REST adapter and the relayed Warren RPC adapter.

func (*PublicAccessService) Disable added in v0.12.0 

func (s *PublicAccessService) Disable(ctx context.Context) (api.PublicAccessStatus, error)

func (*PublicAccessService) Enable added in v0.12.0 

func (s *PublicAccessService) Enable(ctx context.Context, request api.PublicAccessEnableRequest) (api.PublicAccessStatus, error)

func (*PublicAccessService) Reset added in v0.12.0 

func (s *PublicAccessService) Reset(ctx context.Context) (api.PublicAccessStatus, error)

func (*PublicAccessService) Restart added in v0.12.0 

func (s *PublicAccessService) Restart(ctx context.Context) (api.PublicAccessStatus, error)

func (*PublicAccessService) Status added in v0.12.0 

func (s *PublicAccessService) Status(ctx context.Context) api.PublicAccessStatus

func (*PublicAccessService) Test added in v0.12.0 

func (s *PublicAccessService) Test(ctx context.Context, request api.PublicAccessTestRequest) (api.PublicAccessStatus, error)

type RemoveWorkspaceOptions 

type RemoveWorkspaceOptions struct {
	Force bool
	// RemoveWorktree controls whether a Git worktree directory is removed
	// together with its Warren workspace. It only applies to worktree-backed
	// workspaces; main checkouts are never deleted from disk.
	RemoveWorktree bool
}

type Runtime 

type Runtime interface {
	Create(context.Context, string, string, string, []string) error
	Exists(context.Context, string) bool
	Capture(context.Context, string) ([]byte, error)
	Input(context.Context, string, []byte) error
	Resize(context.Context, string, int, int) error
	Kill(context.Context, string) error
}

type RuntimeCreatedLister 

type RuntimeCreatedLister interface {
	ListCreated(context.Context) (map[string]time.Time, error)
}

type RuntimeLister 

type RuntimeLister interface {
	List(context.Context) (map[string]bool, error)
}

type RuntimeProbeResult added in v0.12.0 

type RuntimeProbeResult struct {
	State    RuntimeProbeState
	Evidence string
	Err      error
}

RuntimeProbeResult is the typed lifecycle result returned by adapters that can distinguish an authoritative negative answer from an unavailable authority. Err is diagnostic only; callers must branch on State.

type RuntimeProbeState added in v0.12.0 

type RuntimeProbeState uint8

RuntimeProbeState describes what Warren actually learned from a runtime authority. Unknown is deliberately distinct from Dead: a timeout, transport outage, malformed response, or unavailable runtime must never end a durable Session or authorize an orphan reap. 

const (
	RuntimeProbeUnknown RuntimeProbeState = iota
	RuntimeProbeAlive
	RuntimeProbeDead
)

type RuntimeProber added in v0.12.0 

type RuntimeProber interface {
	Probe(context.Context, string) RuntimeProbeResult
}

RuntimeProber is an additive capability so existing embedders that only implement Runtime keep compiling while production adapters can expose safe lifecycle semantics. New lifecycle decisions always prefer this interface.

type Service 

type Service struct {
	Store          *store.Store
	AgentStore     *store.AgentEventStore
	AgentStorePath string
	// HostName is the Warren Host/system name advertised to the owned Relay.
	// It is injected by the daemon from --name/WARREN_HOST_NAME.
	HostName string
	// Runtime is the adapter for DefaultRuntime, kept for compatibility with
	// existing construction sites and tests.
	Runtime Runtime
	// Runtimes maps runtime kind to its adapter. Ghostline is the only runtime.
	Runtimes map[string]Runtime
	// DefaultRuntime is the engine used for sessions created without an
	// explicit kind.
	DefaultRuntime string
	// Settings holds the persisted headless settings (default runtime and
	// runtime environment overrides) and is returned by the settings API.
	Settings settings.Settings
	// SettingsPath persists settings changes made over the API.
	SettingsPath string

	// Logger receives lifecycle warnings and performance diagnostics. A nil
	// logger falls back to slog's process-wide default for warnings; optional
	// informational diagnostics stay disabled for tests and embedders.
	Logger *slog.Logger
	// ColorQuery supplies terminal foreground and background colors for
	// capability queries answered while no client is attached.
	ColorQuery   ghostline.ColorQueryCallback
	WorktreeRoot string

	// AgentFinder locates Codex/Claude transcript files. When nil, agent
	// projection is disabled and sessions behave exactly as before.
	AgentFinder agent.Finder
	// AgentHooks installs the Warren-managed Codex hook that reports the
	// CLI session ID and transcript path. Nil disables installation; the
	// finder then remains the best-effort fallback.
	AgentHooks func() error
	// AgentProviders is the optional provider registry used by the lifecycle
	// supervisor. Nil retains the legacy built-in transcript path for
	// embedders that have not opted into provider handles yet.
	AgentProviders *AgentProviderRegistry
	// ProviderRegistry and AgentRegistry are compatibility aliases for
	// embedders that used the shorter names while this abstraction was being
	// introduced. When more than one is set, AgentProviders wins.
	ProviderRegistry *AgentProviderRegistry
	AgentRegistry    *AgentProviderRegistry
	// AgentController is an optional provider-native bridge for structured
	// Agent View actions. When absent, ordinary text keeps its legacy PTY path,
	// while interaction and interrupt requests fail explicitly.
	AgentController AgentViewController
	RingCapacity    int
	RingMaxBytes    int
	// CommandTimeout bounds runtime operations during attach and adoption. A
	// stuck runtime must fail the attach and release the session broadcast
	// lock instead of wedging the session until the
	// daemon restarts.
	CommandTimeout time.Duration
	// ProbeForeground enables live foreground process metadata from runtime
	// adapters that support it. Disabled by default so roster snapshots stay
	// cheap; clients fall back to launch command and workspace path.
	ProbeForeground bool
	// ClientsActive reports whether any client can observe roster snapshots.
	// The merge projection only refreshes while clients are connected; nil
	// means "always active" for tests and embedders.
	ClientsActive func() bool
	// contains filtered or unexported fields
}

func (*Service) AddProject 

func (s *Service) AddProject(path, name string) (api.Project, error)

func (*Service) AddProjectWithOptions 

func (s *Service) AddProjectWithOptions(path, name string, autoImportGitWorktrees bool) (api.Project, error)

AddProjectWithOptions adds a project and optionally imports every existing Git worktree for that project. The option is persisted on the Project, not in host-wide settings, so repositories can opt in independently.

func (*Service) AgentViewCapabilities added in v0.12.0 

func (s *Service) AgentViewCapabilities() []string

AgentViewCapabilities reports the capabilities this Service can actually execute. The protocol-level list describes the implementation's vocabulary, while the per-session projection prevents an unsupported provider from receiving the Codex-specific PTY interaction controls.

func (*Service) AttachWorkspaceToTask added in v0.11.2 

func (s *Service) AttachWorkspaceToTask(taskID, workspaceID string) error

func (*Service) CreateDefaultGroupSession 

func (s *Service) CreateDefaultGroupSession(ctx context.Context, command, kind, title, runtimeKind string) (api.Session, error)

CreateDefaultGroupSession creates a standalone shell in the first ordered Group, recreating Inbox when a Host has no Groups left.

func (*Service) CreateDefaultGroupSessionWithHandler added in v0.12.0 

func (s *Service) CreateDefaultGroupSessionWithHandler(ctx context.Context, command, kind, title, runtimeKind, agentHandler string) (api.Session, error)

func (*Service) CreateGroupSession 

func (s *Service) CreateGroupSession(ctx context.Context, groupID, command, kind, title, runtimeKind string) (api.Session, error)

func (*Service) CreateGroupSessionWithHandler added in v0.12.0 

func (s *Service) CreateGroupSessionWithHandler(ctx context.Context, groupID, command, kind, title, runtimeKind, agentHandler string) (api.Session, error)

func (*Service) CreateSession 

func (s *Service) CreateSession(ctx context.Context, workspaceID, command, kind, title, runtimeKind string) (api.Session, error)

func (*Service) CreateSessionWithHandler added in v0.12.0 

func (s *Service) CreateSessionWithHandler(ctx context.Context, workspaceID, command, kind, title, runtimeKind, agentHandler string) (api.Session, error)

CreateSessionWithHandler is the handler-aware form used by protocol clients that explicitly select a transport such as codex/acp. The original CreateSession signature remains source-compatible for shell and TUI users.

func (*Service) CreateTask added in v0.11.2 

func (s *Service) CreateTask(name, source, externalID, rawURL string) (api.Task, error)

func (*Service) CreateTaskWithRequestID added in v0.11.2 

func (s *Service) CreateTaskWithRequestID(name, source, externalID, rawURL, requestID string) (api.Task, error)

func (*Service) CreateTaskWorkspace added in v0.11.2 

func (s *Service) CreateTaskWorkspace(projectID, taskID, branch, name, path string) (api.WorkspaceCreateResult, error)

func (*Service) CreateTaskWorkspaceWithRequestID added in v0.11.2 

func (s *Service) CreateTaskWorkspaceWithRequestID(projectID, taskID, branch, name, path, requestID string) (api.WorkspaceCreateResult, error)

func (*Service) CreateTaskWorkspaceWithSetup added in v0.12.0 

func (s *Service) CreateTaskWorkspaceWithSetup(
	projectID, taskID, branch, name, path, requestID string,
	runSetupScript bool, setupArgs []string,
) (api.WorkspaceCreateResult, error)

func (*Service) CreateTerminalGroup 

func (s *Service) CreateTerminalGroup(name, home string) (api.TerminalGroup, error)

func (*Service) CreateWorkspace 

func (s *Service) CreateWorkspace(projectID, branch, name, path string) (api.WorkspaceCreateResult, error)

func (*Service) DeleteSession 

func (s *Service) DeleteSession(ctx context.Context, id string) error

func (*Service) DetachWorkspaceFromTask added in v0.11.2 

func (s *Service) DetachWorkspaceFromTask(taskID, workspaceID string) error

func (*Service) GitCheckout 

func (s *Service) GitCheckout(ctx context.Context, workspaceID, branch string, create bool) (api.GitCommandResult, error)

func (*Service) GitCommit 

func (s *Service) GitCommit(ctx context.Context, workspaceID, message string) (api.GitCommandResult, error)

func (*Service) GitCreatePullRequest 

func (s *Service) GitCreatePullRequest(ctx context.Context, workspaceID, title, body string) (api.GitPullRequest, error)

GitCreatePullRequest pushes the workspace branch if needed and opens a pull request against the repository's main branch.

func (*Service) GitDiff 

func (s *Service) GitDiff(ctx context.Context, workspaceID, path string, staged bool, commit string) (api.GitDiff, error)

GitDiff returns the full content and unified diff of one path in a workspace, either in the working tree (staged selects the index) or for a specific commit.

func (*Service) GitPanel 

func (s *Service) GitPanel(ctx context.Context, workspaceID string, fetch, force bool) (api.GitPanel, error)

func (*Service) GitPull 

func (s *Service) GitPull(ctx context.Context, workspaceID string) (api.GitCommandResult, error)

func (*Service) GitPush 

func (s *Service) GitPush(ctx context.Context, workspaceID string) (api.GitCommandResult, error)

func (*Service) ImportProjectWorktrees 

func (s *Service) ImportProjectWorktrees(projectID string, paths []string) ([]api.Workspace, error)

ImportProjectWorktrees registers selected existing Git worktrees as workspaces. It never creates, moves, or removes a checkout on disk.

func (*Service) ListProjectWorktrees 

func (s *Service) ListProjectWorktrees(projectID string) ([]api.WorktreeCandidate, error)

ListProjectWorktrees returns existing external Git worktrees for a project. Already registered worktrees stay in the result so clients can render them disabled and explain that import is a one-time operation.

func (*Service) MoveProject 

func (s *Service) MoveProject(id, before string) error

MoveProject moves one project before another project (or to the end when before is empty) and renumbers the stored sidebar order.

func (*Service) MoveSession 

func (s *Service) MoveSession(ctx context.Context, id, workspaceID, groupID string) (api.Session, error)

MoveSession changes the Host scope of a Session between a Workspace and a Terminal Group. The compatibility wrapper keeps existing API callers working; new callers should use MoveSessionWithExpectations.

func (*Service) MoveSessionWithExpectations 

func (s *Service) MoveSessionWithExpectations(_ context.Context, id, workspaceID, groupID string, expectations SessionMoveExpectations) (api.Session, error)

MoveSessionWithExpectations performs an atomic move with optional source context guards and records a reversible operation audit entry. The runtime, working directory, output history, and Session ID are all preserved.

func (*Service) MoveTask added in v0.11.2 

func (s *Service) MoveTask(id, before string) error

func (*Service) MoveTerminalGroup 

func (s *Service) MoveTerminalGroup(id, before string) error

func (*Service) MoveWorkspace 

func (s *Service) MoveWorkspace(id, before string) error

MoveWorkspace moves one workspace before another workspace inside the same project (or to the end when before is empty) and renumbers the stored per-project sidebar order.

func (*Service) PairedClientsSnapshot added in v0.13.0 

func (s *Service) PairedClientsSnapshot() []settings.PairedClient

PairedClientsSnapshot returns detached pairing metadata. Token hashes are kept inside the Host service and are never projected to remote clients.

func (*Service) PingOutput 

func (s *Service) PingOutput(sessionID string)

func (*Service) PreflightSessionMove 

func (s *Service) PreflightSessionMove(id, workspaceID, groupID string, expectations SessionMoveExpectations) (api.SessionMovePreflight, error)

PreflightSessionMove validates a move without changing durable state. It uses the same context checks as the atomic mutation path so dry-run output is actionable rather than a best-effort local guess.

func (*Service) PublicAccessEnabled 

func (s *Service) PublicAccessEnabled() bool

PublicAccessEnabled reports the persisted public Relay route intent. This distinction lets recovery retry after a daemon restart without claiming that the route is already live.

func (*Service) PublicTunnelSettingsSnapshot added in v0.12.0 

func (s *Service) PublicTunnelSettingsSnapshot() settings.PublicTunnelSettings

func (*Service) RelaySettingsSnapshot added in v0.12.0 

func (s *Service) RelaySettingsSnapshot() settings.RelaySettings

RelaySettingsSnapshot and PublicTunnelSettingsSnapshot are the lifecycle supervisor's narrow read surface; neither returns any Host Secret.

func (*Service) RemoveProject 

func (s *Service) RemoveProject(id string, force bool) error

func (*Service) RemoveTask added in v0.11.2 

func (s *Service) RemoveTask(id string) error

func (*Service) RemoveTerminalGroup 

func (s *Service) RemoveTerminalGroup(ctx context.Context, id string, force bool) error

func (*Service) RemoveWorkspace 

func (s *Service) RemoveWorkspace(ctx context.Context, id string, options RemoveWorkspaceOptions) error

func (*Service) RenameProject 

func (s *Service) RenameProject(id, name string) error

func (*Service) RenameSession 

func (s *Service) RenameSession(id, title string) error

func (*Service) RenameTask added in v0.11.2 

func (s *Service) RenameTask(id, name string) error

func (*Service) RenameTerminalGroup 

func (s *Service) RenameTerminalGroup(id, name string) error

func (*Service) RenameWorkspace 

func (s *Service) RenameWorkspace(id, name string) error

func (*Service) Roster 

func (s *Service) Roster(ctx context.Context) api.State

func (*Service) RosterVersion 

func (s *Service) RosterVersion(_ context.Context) (api.State, uint64)

func (*Service) Session 

func (s *Service) Session(id string) (api.Session, bool)

func (*Service) SetAutoOpenShell 

func (s *Service) SetAutoOpenShell(enabled bool) error

SetAutoOpenShell records whether opening an empty workspace creates a Shell session by default. Explicit session actions are unaffected.

func (*Service) SetAutoStartAI 

func (s *Service) SetAutoStartAI(enabled bool) error

SetAutoStartAI records whether entering an empty workspace starts the first AI preset. Explicit session actions are unaffected.

func (*Service) SetDefaultRuntime 

func (s *Service) SetDefaultRuntime(kind string) error

SetDefaultRuntime changes the engine used for newly created sessions while preserving the configured runtime environment overrides.

func (*Service) SetLiveActivityPublisher added in v0.12.0 

func (s *Service) SetLiveActivityPublisher(publisher LiveActivityPublisher)

SetLiveActivityPublisher changes the optional Host→Relay push sink. It is safe to call after Start while the relay supervisor is being assembled.

func (*Service) SetProjectAutoImportGitWorktrees 

func (s *Service) SetProjectAutoImportGitWorktrees(projectID string, enabled bool) (api.Project, error)

SetProjectAutoImportGitWorktrees changes one project's automatic import policy. Enabling it also imports currently visible external worktrees once; this is deliberately non-interactive and leaves imported checkouts on disk.

func (*Service) SetProjectPinned 

func (s *Service) SetProjectPinned(id string, pinned bool) error

func (*Service) SetProjectSetupScript added in v0.12.0 

func (s *Service) SetProjectSetupScript(projectID, script string) (api.Project, error)

SetProjectSetupScript changes the executable used for newly created managed worktrees. An empty value disables setup execution for this project.

func (*Service) SetSessionPinned 

func (s *Service) SetSessionPinned(id string, pinned bool) error

func (*Service) SetTaskPinned added in v0.11.2 

func (s *Service) SetTaskPinned(id string, pinned bool) error

func (*Service) SetTerminalGroupHome 

func (s *Service) SetTerminalGroupHome(id, home string) error

func (*Service) SetWorkspacePinned 

func (s *Service) SetWorkspacePinned(id string, pinned bool) error

func (*Service) SettingsSnapshot added in v0.12.0 

func (s *Service) SettingsSnapshot() settings.Settings

SettingsSnapshot returns a detached copy suitable for concurrent readers. Maps are copied so a caller cannot mutate the service's live configuration.

func (*Service) Shutdown 

func (s *Service) Shutdown()

func (*Service) Start 

func (s *Service) Start(parent context.Context)

Start runs the single lifecycle watcher. One goroutine probes all managed sessions; it never creates a polling task per Session.

func (*Service) TestOpenAITitle added in v0.12.0 

func (s *Service) TestOpenAITitle(ctx context.Context, baseURL, model, apiKey string) error

TestOpenAITitle makes one best-effort title request without changing settings or session state. An empty key uses the key already held by the Host so clients can test a saved credential without downloading it.

func (*Service) UndoSessionMove 

func (s *Service) UndoSessionMove(operationID string) (api.Session, error)

UndoSessionMove reverts a recorded move only while the session still has the exact post-move ownership recorded by the operation. Any intervening change fails closed and leaves both state and audit history untouched.

func (*Service) UpdatePairedClients added in v0.13.0 

func (s *Service) UpdatePairedClients(values []settings.PairedClient) error

UpdatePairedClients persists the current set of explicitly paired clients.

func (*Service) UpdatePublicTunnelSettings added in v0.12.0 

func (s *Service) UpdatePublicTunnelSettings(value settings.PublicTunnelSettings) error

func (*Service) UpdateRelaySettings added in v0.12.0 

func (s *Service) UpdateRelaySettings(value settings.RelaySettings) error

func (*Service) UpdateSettings 

func (s *Service) UpdateSettings(kind string, runtimeEnv map[string]string) error

UpdateSettings changes the engine used for newly created sessions and the runtime environment overrides, persisting them when a settings file is configured. Existing sessions keep their own runtimeKind.

type SessionMoveExpectations 

type SessionMoveExpectations struct {
	WorkspaceID    *string
	AgentSessionID *string
}

SessionMoveExpectations are optional compare-and-swap guards. A nil pointer means the caller did not observe that piece of source context and therefore does not ask the Host to guard it. A non-nil pointer, including an empty string, is an explicit expectation.

type TUIAgentProvider added in v0.12.0 

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

TUIAgentProvider adapts the existing transcript watcher and PTY runtime to the provider lifecycle boundary. It intentionally contains no provider parser logic: agent.Start still selects the established Codex, Claude, OpenCode, Pi, and Qoder normalizers.

func NewTUIAgentProvider added in v0.12.0 

func NewTUIAgentProvider(service *Service, kind string) *TUIAgentProvider

func (*TUIAgentProvider) Capabilities added in v0.12.0 

func (provider *TUIAgentProvider) Capabilities() CapabilitySet

Capabilities describes what the TUI family can execute on this Host. The concrete handle repeats this calculation so a future per-session transport can narrow it further without changing the Service contract.

func (*TUIAgentProvider) Ensure added in v0.12.0 

func (provider *TUIAgentProvider) Ensure(ctx context.Context, value AgentSessionContext) (AgentHandle, error)

func (*TUIAgentProvider) HandlerKind added in v0.12.0 

func (provider *TUIAgentProvider) HandlerKind() string

func (*TUIAgentProvider) Kind added in v0.12.0 

func (provider *TUIAgentProvider) Kind() string

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.