host

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Aug 28, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package host owns the gateway-managed ACP process lifecycle, pooled instances, sessions, permissions, transcripts, and native turn execution. It implements ACP-specific execution facilities below the unified Agent contracts in pkg/agent/runtime.

Index

Constants

This section is empty.

Variables

View Source 
var ErrCapacityExceeded = errors.New("acp instance capacity exceeded")
View Source 
var ErrInvalidRequest = errors.New("invalid acp request")

ErrInvalidRequest marks a client-correctable problem with a session or transcript request (a disabled service, a cwd outside allowed_roots, or a missing session id). Callers map it to HTTP 400; service-not-found maps to 404 and unwrapped agent/transport failures map to 502.

View Source 
var ErrPermissionNotFound = fmt.Errorf("acp permission request not found")

ErrPermissionNotFound reports a decision for a permission request that is unknown, already answered, or expired (the in-agent wait timed out and failed closed).

View Source 
var ErrRunNotFound = errors.New("acp run not found")
View Source 
var ErrRunNotReady = errors.New("acp run cancellation is not ready")
View Source 
var ErrRuntimeConfigRetired = errors.New("acp runtime config is retired")
View Source 
var ErrTurnCancelled = errors.New("acp turn cancelled")

Functions

func ScopeOwnerID 

func ScopeOwnerID(scope string) string

ScopeOwnerID extracts the Agent owner id encoded as the first segment of a pooled-instance scope, or "" if the scope is malformed. It lets callers map a PooledInstanceInfo / InFlightTurn back to its owning Agent without exposing the scope-encoding format.

Types

type ActiveRunInfo 

type ActiveRunInfo struct {
	OwnerID   string    `json:"owner_id"`
	RunID     string    `json:"run_id"`
	SessionID string    `json:"session_id,omitempty"`
	StartedAt time.Time `json:"started_at"`
}

ActiveRunInfo is the exact logical-run view used by the common Agent control plane. It deliberately does not expose the native cancel handle.

type ActivityTracker 

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

func NewActivityTracker 

func NewActivityTracker() *ActivityTracker

func (*ActivityTracker) Begin 

func (t *ActivityTracker) Begin(scope string) (func(), error)

func (*ActivityTracker) IsActive 

func (t *ActivityTracker) IsActive(scope string) bool

func (*ActivityTracker) List 

func (t *ActivityTracker) List() []InFlightTurn

type EventSink 

type EventSink func(TurnEvent) error

type InFlightTurn 

type InFlightTurn struct {
	Scope string `json:"scope"`
}

type ListSessionsRequest 

type ListSessionsRequest struct {
	CWD    string `json:"cwd,omitempty"`
	Cursor string `json:"cursor,omitempty"`
}

type ListSessionsResponse 

type ListSessionsResponse struct {
	Sessions   []SessionInfo `json:"sessions"`
	NextCursor string        `json:"next_cursor,omitempty"`
}

type Manager 

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

func NewManager 

func NewManager() *Manager

func (*Manager) CancelRun 

func (m *Manager) CancelRun(ownerID, runID string) error

CancelRun sends native session/cancel to exactly one active logical run and cancels that run's context. It never closes a scope, thread, or pool entry.

func (*Manager) Close 

func (m *Manager) Close()

Close stops the janitor and tears down every pooled instance, killing the underlying agent subprocesses. It is safe to call more than once.

func (*Manager) CloseOwner 

func (m *Manager) CloseOwner(ownerID string) int

CloseOwner tears down every pooled instance for an Agent owner and returns the count closed.

func (*Manager) CloseScope 

func (m *Manager) CloseScope(scope string) bool

CloseScope tears down the pooled instance for an exact scope, returning whether one was closed. An in-flight turn on that scope will fail on its next request.

func (*Manager) CloseThread 

func (m *Manager) CloseThread(ownerID, threadID string) int

CloseThread tears down every pooled instance for a service+thread and returns the count closed. Intended as an operator escape hatch for a wedged thread.

func (*Manager) ListActiveRuns 

func (m *Manager) ListActiveRuns(ownerID string) []ActiveRunInfo

func (*Manager) ListConfiguredSessions 

func (m *Manager) ListConfiguredSessions(ctx context.Context, ownerID string, runtimeCfg hostconfig.Config, req ListSessionsRequest) (ListSessionsResponse, error)

func (*Manager) ListInFlight 

func (m *Manager) ListInFlight() []InFlightTurn

func (*Manager) ListInstances 

func (m *Manager) ListInstances() []PooledInstanceInfo

ListInstances returns an operator-facing snapshot of the pooled instances, including each instance's cached session metadata, sorted by scope.

func (*Manager) ListOwnerInstances 

func (m *Manager) ListOwnerInstances(ownerID string) []PooledInstanceInfo

ListOwnerInstances keeps pool-scope encoding inside the ACP runtime while exposing the instances owned by one Agent to adapters.

func (*Manager) ListPendingPermissions 

func (m *Manager) ListPendingPermissions() []PendingPermissionInfo

ListPendingPermissions returns the in-flight interactive permission requests awaiting a decision.

func (*Manager) LoadConfiguredTranscript 

func (m *Manager) LoadConfiguredTranscript(ctx context.Context, ownerID string, runtimeCfg hostconfig.Config, req TranscriptRequest) (TranscriptResponse, error)

func (*Manager) RequestCancelRun 

func (m *Manager) RequestCancelRun(ownerID, runID string) error

RequestCancelRun records fail-closed lifecycle cancellation. Unlike the exact CancelRun operation, a pre-bind run accepts the request and is stopped by bind before its prompt starts.

func (*Manager) ResolvePermission 

func (m *Manager) ResolvePermission(decision PermissionDecision) error

ResolvePermission answers one pending interactive permission request. The outcome must be the ACP discriminator "selected" (with the chosen option id exactly as offered by the agent) or "cancelled".

func (*Manager) RetireOwner 

func (m *Manager) RetireOwner(ownerID, keepFingerprint string) int

RetireOwner retires every pooled instance owned by ownerID whose config fingerprint differs from keepFingerprint (an empty keep retires all). Idle instances close immediately; an instance with an active turn is marked retired so the in-flight turn drains, accepts no further reuse, and is reaped by the janitor once idle. It returns the number of instances closed or marked.

func (*Manager) RetireOwnerDeferred 

func (m *Manager) RetireOwnerDeferred(ownerID, keepFingerprint string) (int, func())

RetireOwnerDeferred performs the bounded, in-memory part of RetireOwner and returns cleanup that closes idle victims outside a caller's coordination lock. The state transition takes effect before this method returns.

func (*Manager) ServeConfiguredTurn 

func (m *Manager) ServeConfiguredTurn(ctx context.Context, ownerID string, runtimeCfg hostconfig.Config, req TurnRequest, emit EventSink) error

ServeConfiguredTurn executes an Agent-owned ACP runtime from an identity-free snapshot. It performs no service-store lookup; ownerID is the pool/permission ownership key and is never exposed through the common SPI.

type PendingPermissionInfo 

type PendingPermissionInfo struct {
	RequestID string          `json:"request_id"`
	OwnerID   string          `json:"owner_id"`
	SessionID string          `json:"session_id,omitempty"`
	CreatedAt time.Time       `json:"created_at"`
	Data      json.RawMessage `json:"data,omitempty"`
}

PendingPermissionInfo describes one in-flight interactive permission request. Data carries the raw ACP session/request_permission params (tool call context plus the agent's permission options and their exact ids).

type PermissionDecision 

type PermissionDecision struct {
	RequestID string `json:"request_id"`
	Outcome   string `json:"outcome"`
	OptionID  string `json:"option_id,omitempty"`
}

PermissionDecision is the north-side answer to a pending interactive permission request. Outcome follows the ACP RequestPermissionOutcome discriminators: "selected" (with the chosen option id) or "cancelled".

type PooledInstanceInfo 

type PooledInstanceInfo struct {
	Scope     string          `json:"scope"`
	SessionID string          `json:"session_id,omitempty"`
	Alive     bool            `json:"alive"`
	Active    bool            `json:"active"`
	LastUsed  time.Time       `json:"last_used"`
	IdleTTL   time.Duration   `json:"idle_ttl,omitempty"`
	Metadata  SessionMetadata `json:"metadata"`
}

PooledInstanceInfo is the operator-facing view of one pooled agent instance.

type SessionInfo 

type SessionInfo struct {
	SessionID string          `json:"session_id"`
	CWD       string          `json:"cwd"`
	Title     string          `json:"title,omitempty"`
	UpdatedAt *time.Time      `json:"updated_at,omitempty"`
	Meta      json.RawMessage `json:"_meta,omitempty"`
}

type SessionMetadata 

type SessionMetadata struct {
	ConfigOptions     json.RawMessage `json:"config_options,omitempty"`
	AvailableCommands json.RawMessage `json:"available_commands,omitempty"`
	SessionInfo       json.RawMessage `json:"session_info,omitempty"`
	Mode              json.RawMessage `json:"mode,omitempty"`
	Usage             json.RawMessage `json:"usage,omitempty"`
}

SessionMetadata is the cached structured state of one pooled session. Every field carries the raw ACP update object of its kind (config_option_update, available_commands_update, session_info_update, current_mode_update, usage_update).

type TranscriptMessage 

type TranscriptMessage struct {
	Role string `json:"role"`
	Text string `json:"text"`
}

TranscriptMessage is one coalesced replayed message. Role is one of user, assistant, or reasoning.

type TranscriptRequest 

type TranscriptRequest struct {
	SessionID string `json:"session_id"`
	CWD       string `json:"cwd,omitempty"`
}

type TranscriptResponse 

type TranscriptResponse struct {
	SessionID string              `json:"session_id"`
	Messages  []TranscriptMessage `json:"messages"`
}

type TurnEvent 

type TurnEvent struct {
	Event               string          `json:"-"`
	SessionID           string          `json:"session_id,omitempty"`
	RequestID           string          `json:"request_id,omitempty"`
	PermissionExpiresAt time.Time       `json:"-"`
	Text                string          `json:"text,omitempty"`
	StopReason          string          `json:"stop_reason,omitempty"`
	Message             string          `json:"message,omitempty"`
	Data                json.RawMessage `json:"data,omitempty"`
}

type TurnRequest 

type TurnRequest struct {
	RunID           string            `json:"run_id,omitempty"`
	ThreadID        string            `json:"thread_id"`
	SessionID       string            `json:"session_id,omitempty"`
	Input           string            `json:"input"`
	CWD             string            `json:"cwd,omitempty"`
	Model           string            `json:"model,omitempty"`
	FreshSession    bool              `json:"fresh_session,omitempty"`
	ConfigOverrides map[string]string `json:"config_overrides,omitempty"`
}

Source Files

View all Source files

Directories

Path Synopsis
Package acpupdate parses ACP session/update notifications into a small set of neutral events the runtime driver forwards to the gateway north side.
 Package acpupdate parses ACP session/update notifications into a small set of neutral events the runtime driver forwards to the gateway north side.

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.