agent

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: May 1, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrRuntimeConfigNil = errors.New("runtime config is nil")

Functions

func ActivateOverlay added in v0.1.11

func ActivateOverlay(entries []OverlayEntry) (func(), error)

ActivateOverlay installs one command-scoped ACP runtime overlay built from extension-declared IDE providers and returns a restore function.

func BuildShellCommandString

func BuildShellCommandString(
	ide string,
	modelName string,
	addDirs []string,
	reasoningEffort string,
	accessMode string,
) string

BuildShellCommandString renders a shell preview for the configured ACP agent bootstrap command.

func DisplayName

func DisplayName(ide string) string

DisplayName returns the human-readable display name for an agent runtime.

func EnsureAvailable

func EnsureAvailable(ctx context.Context, cfg *model.RuntimeConfig) error

EnsureAvailable verifies that the configured ACP agent binary is installed and executable.

func ResolveRuntimeModel added in v0.1.9

func ResolveRuntimeModel(ide string, modelName string) (string, error)

ResolveRuntimeModel returns the effective model after applying the IDE default when needed.

func SetupAgentName added in v0.1.11

func SetupAgentName(ide string) (string, error)

SetupAgentName returns the setup/install agent identifier for one ACP runtime.

func ValidateAddDirSupport added in v0.1.9

func ValidateAddDirSupport(fieldName string, ide string, addDirs []string) error

ValidateAddDirSupport verifies that the selected runtime supports extra writable roots.

func ValidateRuntimeConfig

func ValidateRuntimeConfig(cfg *model.RuntimeConfig) error

ValidateRuntimeConfig verifies that the runtime config references a supported agent runtime.

Types

type AvailabilityError added in v0.1.3

type AvailabilityError struct {
	IDE         string
	DisplayName string
	Command     []string
	DocsURL     string
	InstallHint string
	Output      string
	Cause       error
}

AvailabilityError reports an ACP runtime that is missing or incorrectly installed.

func (*AvailabilityError) Error added in v0.1.3

func (e *AvailabilityError) Error() string

func (*AvailabilityError) Unwrap added in v0.1.3

func (e *AvailabilityError) Unwrap() error

type Client added in v0.1.3

type Client interface {
	// CreateSession starts a new ACP session with the given prompt.
	CreateSession(ctx context.Context, req SessionRequest) (Session, error)
	// ResumeSession attaches to an existing ACP session and sends a new prompt into it.
	ResumeSession(ctx context.Context, req ResumeSessionRequest) (Session, error)
	// SupportsLoadSession reports whether the connected ACP agent advertised session/load support.
	SupportsLoadSession() bool
	// Close terminates the agent subprocess.
	Close() error
	// Kill force-terminates the agent subprocess immediately.
	Kill() error
}

Client manages an ACP agent subprocess and creates sessions.

func NewClient added in v0.1.3

func NewClient(_ context.Context, cfg ClientConfig) (Client, error)

NewClient constructs a Compozy ACP client wrapper for the configured agent runtime.

type ClientConfig added in v0.1.3

type ClientConfig struct {
	IDE             string
	Model           string
	AddDirs         []string
	ReasoningEffort string
	AccessMode      string
	Logger          *slog.Logger
	ShutdownTimeout time.Duration
}

ClientConfig describes how to bootstrap an ACP agent process.

type DriverCatalogEntry added in v0.1.3

type DriverCatalogEntry struct {
	IDE                string
	DisplayName        string
	CanonicalCommand   []string
	CanonicalProbe     []string
	FallbackLaunchers  []DriverCatalogLauncher
	SupportsAddDirs    bool
	UsesBootstrapModel bool
	DocsURL            string
	InstallHint        string
}

DriverCatalogEntry exposes the stable command catalog for one supported ACP runtime.

func DriverCatalog added in v0.1.3

func DriverCatalog() []DriverCatalogEntry

DriverCatalog returns the stable ACP driver catalog in the supported IDE order.

func DriverCatalogEntryForIDE added in v0.1.3

func DriverCatalogEntryForIDE(ide string) (DriverCatalogEntry, error)

DriverCatalogEntryForIDE returns the stable driver catalog entry for one supported IDE.

type DriverCatalogLauncher added in v0.1.3

type DriverCatalogLauncher struct {
	Command []string
	Probe   []string
}

DriverCatalogLauncher describes one fallback launcher for a supported ACP runtime.

type Launcher added in v0.1.3

type Launcher struct {
	Command   string
	FixedArgs []string
	ProbeArgs []string
}

Launcher defines one ACP-compatible command shape for a runtime.

type OverlayBootstrap added in v0.1.11

type OverlayBootstrap struct {
	ModelFlag             string
	ReasoningEffortFlag   string
	AddDirFlag            string
	DefaultAccessModeArgs []string
	FullAccessModeArgs    []string
}

OverlayBootstrap declares typed ACP bootstrap flags for declarative IDE overlays.

type OverlayEntry added in v0.1.11

type OverlayEntry struct {
	Name               string
	DisplayName        string
	Command            string
	SetupAgentName     string
	DefaultModel       string
	SupportsAddDirs    *bool
	UsesBootstrapModel *bool
	DocsURL            string
	InstallHint        string
	FullAccessModeID   string
	FixedArgs          []string
	ProbeArgs          []string
	EnvVars            map[string]string
	Fallbacks          []Launcher
	Bootstrap          OverlayBootstrap
	Metadata           map[string]string
}

OverlayEntry captures one declarative ACP runtime overlay entry assembled during command bootstrap.

type Registry added in v0.1.10

type Registry struct{}

Registry exposes the supported ACP runtime catalog through a value that can be passed around as a dependency.

func (Registry) EnsureAvailable added in v0.1.10

func (Registry) EnsureAvailable(ctx context.Context, cfg *model.RuntimeConfig) error

EnsureAvailable verifies that the configured ACP agent binary is installed and executable.

func (Registry) ValidateRuntimeConfig added in v0.1.10

func (Registry) ValidateRuntimeConfig(cfg *model.RuntimeConfig) error

ValidateRuntimeConfig verifies that the runtime config references a supported agent runtime.

type ResumeSessionRequest added in v0.1.9

type ResumeSessionRequest struct {
	SessionID  string               `json:"session_id,omitempty"`
	Prompt     []byte               `json:"prompt,omitempty"`
	WorkingDir string               `json:"working_dir,omitempty"`
	Model      string               `json:"model,omitempty"`
	MCPServers []model.MCPServer    `json:"mcp_servers,omitempty"`
	ExtraEnv   map[string]string    `json:"extra_env,omitempty"`
	Context    context.Context      `json:"-"`
	RunID      string               `json:"-"`
	JobID      string               `json:"-"`
	RuntimeMgr model.RuntimeManager `json:"-"`
}

ResumeSessionRequest contains the parameters for loading and continuing an existing ACP session.

func (ResumeSessionRequest) MarshalJSON added in v0.1.11

func (r ResumeSessionRequest) MarshalJSON() ([]byte, error)

func (*ResumeSessionRequest) UnmarshalJSON added in v0.1.11

func (r *ResumeSessionRequest) UnmarshalJSON(data []byte) error

type RuntimeRegistry added in v0.1.10

type RuntimeRegistry interface {
	ValidateRuntimeConfig(cfg *model.RuntimeConfig) error
	EnsureAvailable(ctx context.Context, cfg *model.RuntimeConfig) error
}

RuntimeRegistry captures the ACP runtime validation surface needed by execution and kernel code.

func DefaultRegistry added in v0.1.10

func DefaultRegistry() RuntimeRegistry

DefaultRegistry returns the default ACP runtime registry handle.

type Session added in v0.1.3

type Session interface {
	// ID returns the ACP session identifier.
	ID() string
	// Identity returns the canonical session identifiers known for this session.
	Identity() SessionIdentity
	// Updates returns the streamed session updates in arrival order.
	Updates() <-chan model.SessionUpdate
	// Done closes when the session has fully completed.
	Done() <-chan struct{}
	// Err returns the terminal session error, if any.
	Err() error
	// SlowPublishes returns the number of publishes that waited for backpressure to clear.
	SlowPublishes() uint64
	// DroppedUpdates returns the number of updates dropped after backpressure timed out.
	DroppedUpdates() uint64
}

Session represents an active ACP session streaming updates.

type SessionError added in v0.1.3

type SessionError struct {
	Code    int
	Message string
	Data    json.RawMessage
}

SessionError wraps JSON-RPC/ACP request errors without leaking SDK types.

func (*SessionError) Error added in v0.1.3

func (e *SessionError) Error() string

Error implements the error interface.

type SessionIdentity added in v0.1.9

type SessionIdentity struct {
	ACPSessionID   string `json:"acp_session_id"`
	AgentSessionID string `json:"agent_session_id,omitempty"`
	Resumed        bool   `json:"resumed,omitempty"`
}

SessionIdentity captures the stable ACP and provider-specific ids for a session.

type SessionOutcome added in v0.1.11

type SessionOutcome struct {
	Status model.SessionStatus `json:"status"`
	Error  string              `json:"error,omitempty"`
}

type SessionRequest added in v0.1.3

type SessionRequest struct {
	Prompt     []byte               `json:"prompt,omitempty"`
	WorkingDir string               `json:"working_dir,omitempty"`
	Model      string               `json:"model,omitempty"`
	MCPServers []model.MCPServer    `json:"mcp_servers,omitempty"`
	ExtraEnv   map[string]string    `json:"extra_env,omitempty"`
	Context    context.Context      `json:"-"`
	RunID      string               `json:"-"`
	JobID      string               `json:"-"`
	RuntimeMgr model.RuntimeManager `json:"-"`
}

SessionRequest contains the parameters for creating a new ACP session.

func (SessionRequest) MarshalJSON added in v0.1.11

func (r SessionRequest) MarshalJSON() ([]byte, error)

func (*SessionRequest) UnmarshalJSON added in v0.1.11

func (r *SessionRequest) UnmarshalJSON(data []byte) error

type SessionSetupError added in v0.1.6

type SessionSetupError struct {
	Stage SessionSetupStage
	Err   error
}

SessionSetupError wraps an ACP setup failure with its stage for retry classification.

func (*SessionSetupError) Error added in v0.1.6

func (e *SessionSetupError) Error() string

Error implements the error interface.

func (*SessionSetupError) Unwrap added in v0.1.6

func (e *SessionSetupError) Unwrap() error

Unwrap returns the underlying setup failure.

type SessionSetupStage added in v0.1.6

type SessionSetupStage string

SessionSetupStage identifies which ACP bootstrap or session-configuration step failed.

const (
	// SessionSetupStageStartProcess indicates that starting the ACP subprocess failed.
	SessionSetupStageStartProcess SessionSetupStage = "start_process"
	// SessionSetupStageInitialize indicates that ACP protocol initialization failed.
	SessionSetupStageInitialize SessionSetupStage = "initialize"
	// SessionSetupStageNewSession indicates that ACP session creation failed.
	SessionSetupStageNewSession SessionSetupStage = "new_session"
	// SessionSetupStageLoadSession indicates that ACP session loading failed.
	SessionSetupStageLoadSession SessionSetupStage = "load_session"
	// SessionSetupStageSetModel indicates that ACP session model configuration failed.
	SessionSetupStageSetModel SessionSetupStage = "set_model"
	// SessionSetupStageSetMode indicates that ACP session mode configuration failed.
	SessionSetupStageSetMode SessionSetupStage = "set_mode"
)

type Spec added in v0.1.3

type Spec struct {
	ID                 string
	DisplayName        string
	SetupAgentName     string
	DefaultModel       string
	Command            string
	FixedArgs          []string
	ProbeArgs          []string
	Fallbacks          []Launcher
	SupportsAddDirs    bool
	UsesBootstrapModel bool
	EnvVars            map[string]string
	DocsURL            string
	InstallHint        string
	FullAccessModeID   string
	BootstrapArgs      func(modelName, reasoningEffort string, addDirs []string, accessMode string) []string
}

Spec defines how to bootstrap an ACP-compatible agent process.

Jump to

Keyboard shortcuts

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