Documentation
¶
Index ¶
- Variables
- func ActivateOverlay(entries []OverlayEntry) (func(), error)
- func BuildShellCommandString(ide string, modelName string, addDirs []string, reasoningEffort string, ...) string
- func DefaultModel(ide string) string
- func DisplayName(ide string) string
- func EnsureAvailable(ctx context.Context, cfg *model.RuntimeConfig) error
- func IsAuthenticationRequired(err error) bool
- func IsPromptCancelled(err error) bool
- func NewPromptMessageID() (string, error)
- func ResolveRuntimeModel(ide string, modelName string) (string, error)
- func RuntimeCommandName(ide string) string
- func SetupAgentName(ide string) (string, error)
- func ValidateAddDirSupport(fieldName string, ide string, addDirs []string) error
- func ValidateRuntimeConfig(cfg *model.RuntimeConfig) error
- type AuthenticationRequiredError
- type AvailabilityError
- type Client
- type ClientConfig
- type DriverCatalogEntry
- type DriverCatalogLauncher
- type Launcher
- type OverlayBootstrap
- type OverlayEntry
- type PromptCancelledError
- type PromptSessionRequest
- type Registry
- type ResumeSessionRequest
- type RuntimeRegistry
- type Session
- type SessionError
- type SessionIdentity
- type SessionOutcome
- type SessionRequest
- type SessionSetupError
- type SessionSetupStage
- type Spec
Constants ¶
This section is empty.
Variables ¶
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 DefaultModel ¶ added in v0.2.11
DefaultModel returns the default model identifier for an agent runtime.
func DisplayName ¶
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 IsAuthenticationRequired ¶ added in v0.2.8
IsAuthenticationRequired reports whether err is an ACP authentication failure.
func IsPromptCancelled ¶ added in v0.2.10
IsPromptCancelled reports whether err is a prompt-turn cancellation, not process shutdown.
func NewPromptMessageID ¶ added in v0.2.10
NewPromptMessageID returns an ACP-compatible UUIDv4 message id.
func ResolveRuntimeModel ¶ added in v0.1.9
ResolveRuntimeModel returns the effective model after applying the IDE default when needed.
func RuntimeCommandName ¶ added in v0.2.8
RuntimeCommandName returns the primary executable name for an agent runtime.
func SetupAgentName ¶ added in v0.1.11
SetupAgentName returns the setup/install agent identifier for one ACP runtime.
func ValidateAddDirSupport ¶ added in v0.1.9
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 AuthenticationRequiredError ¶ added in v0.2.8
type AuthenticationRequiredError struct {
Err error
}
AuthenticationRequiredError marks ACP protocol authentication failures.
func (*AuthenticationRequiredError) Error ¶ added in v0.2.8
func (e *AuthenticationRequiredError) Error() string
Error implements the error interface.
func (*AuthenticationRequiredError) Unwrap ¶ added in v0.2.8
func (e *AuthenticationRequiredError) Unwrap() error
Unwrap returns the underlying ACP session error.
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)
// CancelSession requests cancellation of the active prompt turn for a session.
CancelSession(ctx context.Context, sessionID string) error
// PromptSession sends a new prompt turn into an already active ACP session.
PromptSession(ctx context.Context, req PromptSessionRequest) (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.
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
// TerminalCommandTimeout is the absolute wall-clock cap applied to each
// terminal command as a last-resort backstop. Zero falls back to the
// resolved stall-policy default.
TerminalCommandTimeout 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
DriverCatalogLauncher describes one fallback launcher for a supported ACP 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 PromptCancelledError ¶ added in v0.2.10
type PromptCancelledError struct {
SessionID string
}
PromptCancelledError marks an ACP prompt turn canceled while the session stays reusable.
func (*PromptCancelledError) Error ¶ added in v0.2.10
func (e *PromptCancelledError) Error() string
type PromptSessionRequest ¶ added in v0.2.10
type PromptSessionRequest struct {
SessionID string `json:"session_id,omitempty"`
Prompt []byte `json:"prompt,omitempty"`
MessageID string `json:"message_id,omitempty"`
}
PromptSessionRequest contains the parameters for a follow-up prompt in an active ACP session.
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
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:"-"`
SetupContext 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:"-"`
SetupContext 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" // SessionSetupStageSetReasoning indicates that ACP session reasoning configuration failed. SessionSetupStageSetReasoning SessionSetupStage = "set_reasoning" // 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
// ModelEnvVar names the environment variable that carries an explicitly
// requested model to the agent process at launch, for runtimes that read
// their model from the environment instead of supporting session/set_model.
ModelEnvVar string
EnvVars map[string]string
DocsURL string
InstallHint string
FullAccessModeID string
BootstrapArgs func(modelName, reasoningEffort string, addDirs []string, accessMode string) []string
// LegacyBootstrapArgs configures an older launcher only when its installed
// package identity is positively detected. Current ACP adapters are configured
// through session options instead of process flags.
LegacyBootstrapArgs func(modelName, reasoningEffort string, addDirs []string, accessMode string) []string
}
Spec defines how to bootstrap an ACP-compatible agent process.