Documentation
¶
Overview ¶
Package acp provides the Compozy ACP client implementation.
Index ¶
- Constants
- Variables
- func AcceptedSessionID(err error) (string, bool)
- func CloneRawMessage(value json.RawMessage) json.RawMessage
- func CollectPromptSections(ctx context.Context) (context.Context, func() []PromptSection)
- func DaemonMatchedEnv(base []string) []string
- func EstimateTokens(byteLen int64) int64
- func FailureFromError(err error, fallback store.FailureKind) (*store.SessionFailure, bool)
- func IsLoadSessionResourceMissing(err error) bool
- func RegisterPromptSection(ctx context.Context, section PromptSection)
- func ReplaceProviderFailureDiagnostic(summary string, d ProviderFailureDiagnostic) string
- func ResolveSteerCapability(provider string, announced []string, override config.SteerCapability) config.SteerCapability
- func ValidateACPModePermissions(options []SessionConfigOptionSelection, ...) error
- func ValidateModelConfigValue(options []SessionConfigOption, modelID string) error
- func WrapAcceptedStart(sessionID string, err error) error
- func WrapFailure(kind store.FailureKind, summary string, err error) error
- type AcceptedStartError
- type AgentEvent
- func (e AgentEvent) Attachments() []EventAttachment
- func (e AgentEvent) AvailableCommandSet() *AvailableCommandSet
- func (e AgentEvent) DeliveryManifest() *DeliveryManifest
- func (e *AgentEvent) EventIDValue() string
- func (e AgentEvent) HasToolPayload() bool
- func (e *AgentEvent) MessageIDValue() string
- func (e AgentEvent) PromptRuntimeSnapshot() *PromptRuntime
- func (e AgentEvent) RequestIDValue() string
- func (e AgentEvent) ResolvedByValue() string
- func (e AgentEvent) SkillInvocations() []commandpkg.Invocation
- func (e AgentEvent) ToolError() bool
- func (e AgentEvent) ToolErrorDetail() string
- func (e AgentEvent) ToolInput() json.RawMessage
- func (e AgentEvent) ToolKind() string
- func (e AgentEvent) ToolName() string
- func (e AgentEvent) ToolPrechecked() bool
- func (e AgentEvent) WithAttachments(attachments []EventAttachment) AgentEvent
- func (e AgentEvent) WithAvailableCommands(commands []store.SessionAdvertisedCommand) AgentEvent
- func (e AgentEvent) WithDelivery(manifest *DeliveryManifest) AgentEvent
- func (e AgentEvent) WithEventID(eventID string) AgentEvent
- func (e AgentEvent) WithMessageID(messageID string) AgentEvent
- func (e AgentEvent) WithPromptRuntime(runtime *PromptRuntime) AgentEvent
- func (e AgentEvent) WithRequestID(requestID string) AgentEvent
- func (e AgentEvent) WithResolvedBy(resolvedBy string) AgentEvent
- func (e AgentEvent) WithSkillInvocations(invocations []commandpkg.Invocation) AgentEvent
- func (e AgentEvent) WithTool(name string, input json.RawMessage, failed bool) AgentEvent
- func (e AgentEvent) WithToolDetail(name string, input json.RawMessage, failed bool, errorDetail string) AgentEvent
- func (e AgentEvent) WithToolKind(kind string) AgentEvent
- func (e AgentEvent) WithToolPrechecked() AgentEvent
- type AgentProcess
- func (p *AgentProcess) CapsSnapshot() Caps
- func (p *AgentProcess) Done() <-chan struct{}
- func (p *AgentProcess) ExitStatus() (subprocess.ExitStatus, bool)
- func (p *AgentProcess) ForkSession(ctx context.Context, cwd string, mcpServers []acpsdk.McpServer) (ForkSessionResult, error)
- func (p *AgentProcess) HasPendingPermission() bool
- func (p *AgentProcess) HealthState() subprocess.HealthState
- func (p *AgentProcess) IngestStats() IngestStats
- func (p *AgentProcess) RequestPermission(ctx context.Context, req RequestPermissionRequest) (RequestPermissionResponse, error)
- func (p *AgentProcess) ResolvePermission(req ApproveRequest) error
- func (p *AgentProcess) Stderr() string
- func (p *AgentProcess) ToolHost() ToolHost
- func (p *AgentProcess) Wait() error
- type ApproveRequest
- type AvailableCommandSet
- type BroadcastStats
- type Caps
- type CommandResult
- type CommandRuntime
- type CommandSpec
- type DeliveredSpan
- type DeliveryManifest
- type Driver
- func (d *Driver) ApprovePermission(ctx context.Context, proc *AgentProcess, req ApproveRequest) error
- func (d *Driver) Cancel(ctx context.Context, proc *AgentProcess) error
- func (d *Driver) CancelCooperatively(ctx context.Context, proc *AgentProcess) error
- func (d *Driver) ConfigureRuntime(ctx context.Context, process *AgentProcess, config RuntimeConfig) error
- func (d *Driver) Interrupt(ctx context.Context, scope toolruntime.InterruptScope) (toolruntime.InterruptReport, error)
- func (d *Driver) Kill(ctx context.Context, proc *AgentProcess) error
- func (d *Driver) NotifyExtension(ctx context.Context, proc *AgentProcess, method string, params any) error
- func (d *Driver) Prompt(ctx context.Context, proc *AgentProcess, req PromptRequest) (<-chan AgentEvent, error)
- func (d *Driver) Start(ctx context.Context, opts StartOpts) (process *AgentProcess, startErr error)
- func (d *Driver) Steer(ctx context.Context, proc *AgentProcess, turnID, text string) (SteerResult, error)
- func (d *Driver) Stop(ctx context.Context, proc *AgentProcess) error
- func (d *Driver) VerifyExit(proc *AgentProcess) (bool, error)
- type EventAttachment
- type FailureError
- type ForkSessionResult
- type GoalPromptMeta
- type Handle
- type IngestGate
- type IngestStats
- type LaunchPreparer
- type LaunchSpec
- type Launcher
- type LiveBroadcast
- type LocalRuntimeOption
- type LocalTerminalScope
- type NegotiationError
- type Option
- func WithControlTimeout(timeout time.Duration) Option
- func WithLauncher(launcher Launcher) Option
- func WithLogger(logger *slog.Logger) Option
- func WithPermissionTimeout(timeout time.Duration) Option
- func WithProcessRecordTimeout(timeout time.Duration) Option
- func WithProcessRegistry(registry *toolruntime.Registry) Option
- func WithPromptBufferSize(size int) Option
- func WithPromptDrainWait(wait time.Duration) Option
- func WithProviderPreStarter(starter ProviderPreStarter) Option
- func WithStartAttempts(attempts int) Option
- func WithStopTimeout(timeout time.Duration) Option
- func WithTerminalManager(manager TerminalHost) Option
- func WithToolHost(toolHost ToolHost) Option
- type PermissionDecision
- type PermissionOperation
- type ProbeLookup
- type ProbeOptions
- type ProbeResult
- type ProbeTarget
- type ProcessSignal
- type PromptActivityReport
- type PromptActivityReporter
- type PromptAttachment
- type PromptJudgeMeta
- type PromptMeta
- type PromptRequest
- type PromptRuntime
- type PromptSection
- type PromptStopReason
- type PromptSyntheticMeta
- type PromptSystemMeta
- type ProviderErrorDiagnostic
- type ProviderFailureAction
- type ProviderFailureDiagnostic
- type ProviderFailureKind
- type ProviderPreStarter
- type RequestPermissionRequest
- type RequestPermissionResponse
- type RuntimeActivity
- type RuntimeApplicationStrategy
- type RuntimeConfig
- type SessionConfigOption
- func CloneSessionConfigOptions(options []SessionConfigOption) []SessionConfigOption
- func InspectSessionConfigOptions(ctx context.Context, req SessionInspectionRequest) ([]SessionConfigOption, error)
- func ModelConfigOption(options []SessionConfigOption) (SessionConfigOption, bool)
- func ReasoningConfigOption(options []SessionConfigOption) (SessionConfigOption, bool)
- type SessionConfigOptionKind
- type SessionConfigOptionSelection
- type SessionConfigOptionValue
- type SessionInspectionRequest
- type SessionModelInspection
- type StartOpts
- type StartupManifest
- type SteerAttempt
- type SteerResult
- type SystemPromptDeliveryMode
- type TerminalHost
- type TokenUsage
- type ToolExecutionGateway
- type ToolExecutionRequest
- type ToolHost
Constants ¶
const ( GoalPromptKindWork = "goal-work" GoalPromptKindContinuation = "goal-continuation" GoalPromptKindCompaction = "goal-compaction" )
const ( NegotiationCodeReasoningOptionMissing = diagnosticcontract.CodeReasoningOptionMissing NegotiationCodeReasoningEffortUnsupported = diagnosticcontract.CodeReasoningEffortUnsupported NegotiationCodeSpeedRejected = diagnosticcontract.CodeSpeedRejected )
const ( // PermissionRequestIDMetaKey pins the externally addressable permission request ID in ACP metadata. PermissionRequestIDMetaKey = "request_id" // PermissionToolIDMetaKey preserves the canonical Compozy tool identity for attention projections. PermissionToolIDMetaKey = "compozy_tool_id" )
const ( ProbeStatusOK = "ok" ProbeStatusMissing = "missing" ProbeStatusInvalid = "invalid" ProbeStatusCanceled = "canceled" ProbeStatusTimeout = "timeout" )
const ( // PromptTurnSourceUser identifies a daemon prompt that originated from the // user-facing prompt surfaces. PromptTurnSourceUser = "user" // PromptTurnSourceSynthetic identifies a daemon-owned prompt turn injected by // internal runtime code. PromptTurnSourceSynthetic = "synthetic" )
const ( ProviderErrorAuthRequired = "provider_auth_required" ProviderErrorRateLimited = "provider_rate_limited" )
const ( // EventTypeUserMessage is emitted when the agent echoes a user message chunk. EventTypeUserMessage = "user_message" // EventTypeSyntheticReentry is emitted for daemon-originated synthetic prompt input. EventTypeSyntheticReentry = "synthetic_reentry" // EventTypeAgentMessage is emitted for assistant message chunks. EventTypeAgentMessage = "agent_message" // EventTypeThought is emitted for assistant thought chunks. EventTypeThought = "thought" // EventTypeToolCall is emitted when a tool call starts or is updated in-flight. EventTypeToolCall = "tool_call" // EventTypeToolResult is emitted when a tool call finishes. EventTypeToolResult = "tool_result" // EventTypePlan is emitted for plan updates. EventTypePlan = "plan" // EventTypePermission is emitted when the daemon applies a permission decision. EventTypePermission = "permission" // EventTypeClarify is emitted for daemon-owned clarification lifecycle transitions. EventTypeClarify = "clarify" // EventTypeUsage is emitted when unstable usage metadata is reported. EventTypeUsage = "usage" // EventTypeSystem is emitted for system-level ACP updates. EventTypeSystem = "system" // EventTypeRuntimeProgress is emitted by Compozy while a prompt remains active. EventTypeRuntimeProgress = "runtime_progress" // EventTypeRuntimeWarning reports stale prompt activity or auxiliary runtime cleanup failures. EventTypeRuntimeWarning = "runtime_warning" // EventTypeRuntimeRecoveryStarted is emitted before an automatic runtime recovery attempt. EventTypeRuntimeRecoveryStarted = "runtime_recovery_started" // EventTypeRuntimeRecoverySucceeded is emitted after an automatic runtime recovery resumes the turn. EventTypeRuntimeRecoverySucceeded = "runtime_recovery_succeeded" // EventTypeRuntimeRecoveryExhausted is emitted after all automatic runtime recovery attempts fail. EventTypeRuntimeRecoveryExhausted = "runtime_recovery_exhausted" // EventTypeDone is emitted when a prompt turn finishes. EventTypeDone = "done" // EventTypeError is emitted when prompt processing fails. EventTypeError = "error" // SystemEventTitleAvailableCommandsUpdate replaces the provider-advertised command set. SystemEventTitleAvailableCommandsUpdate = "available_commands_update" )
const EventTypePromptDelivery = "prompt_delivery"
const (
// PromptJudgeRoleAgent identifies one daemon-owned agent judge prompt.
PromptJudgeRoleAgent = "agent-judge"
)
const TextEstimateMethod = "bytes_div_4"
Variables ¶
var ( // ErrAgentDoesNotSupportSession reports that resume was requested for an ACP agent without session/load support. ErrAgentDoesNotSupportSession = errors.New("acp: agent does not support session/load") // ErrLoadSessionFailed reports that ACP session/load failed during resume. ErrLoadSessionFailed = errors.New("acp: load session failed") )
var ( ErrIngestSaturated = errors.New("acp: prompt ingestion capacity exhausted") ErrIngestClosed = errors.New("acp: prompt ingestion is closed") )
var ( // ErrPermissionDenied reports that the configured static policy rejected an operation. ErrPermissionDenied = errors.New("acp: permission denied") // ErrInvalidPath reports malformed tool paths rejected before filesystem access. ErrInvalidPath = errors.New("acp: invalid path") // ErrPathOutsideWorkspace reports that a requested path escapes the session root. ErrPathOutsideWorkspace = errors.New("acp: path outside session workspace") // ErrPendingPermissionNotFound reports that no waiting permission request matched the approval request. ErrPendingPermissionNotFound = errors.New("acp: pending permission not found") // ErrPendingPermissionConflict reports that a fallback lookup by turn ID matched multiple pending requests. ErrPendingPermissionConflict = errors.New("acp: pending permission lookup is ambiguous") // ErrPermissionDecisionUnsupported reports a persisted decision that the provider did not offer. ErrPermissionDecisionUnsupported = errors.New("acp: permission decision unsupported") )
var ( // ErrPromptImagesUnsupported reports that image blocks exceed the negotiated prompt capabilities. ErrPromptImagesUnsupported = errors.New("acp: prompt images unsupported") // ErrPromptFilesUnsupported reports that embedded file blocks exceed the negotiated prompt capabilities. ErrPromptFilesUnsupported = errors.New("acp: prompt files unsupported") // ErrPromptAttachmentDataRequired reports an attachment without content bytes. ErrPromptAttachmentDataRequired = errors.New("acp: prompt attachment data is required") // ErrPromptAttachmentMIMEUnsupported reports an attachment MIME type outside the prompt contract. ErrPromptAttachmentMIMEUnsupported = errors.New("acp: prompt attachment mime type unsupported") )
var ErrForkSessionUnbound = errors.New("acp: session/fork requires a bound ACP session")
ErrForkSessionUnbound reports a session/fork attempt on a process without a bound ACP session.
var ErrInvalidPromptMetadata = errors.New("acp: invalid prompt metadata")
ErrInvalidPromptMetadata identifies metadata that cannot be sent to an ACP agent.
var ErrPermissionQueueFull = errors.New("acp: pending permission queue is full (cap 128)")
var ErrPromptStreamIncomplete = errors.New("acp prompt stream ended before a terminal event")
ErrPromptStreamIncomplete identifies an ACP prompt stream that closed without a Done or Error event.
var ErrSteerTurnMismatch = errors.New("acp: steer target is no longer the active turn")
Functions ¶
func AcceptedSessionID ¶
AcceptedSessionID reports the accepted ACP session id carried anywhere in err's chain, including through fmt.Errorf("%w") and errors.Join wrappers.
func CloneRawMessage ¶
func CloneRawMessage(value json.RawMessage) json.RawMessage
CloneRawMessage returns an independent copy of one raw JSON payload.
func CollectPromptSections ¶
func CollectPromptSections(ctx context.Context) (context.Context, func() []PromptSection)
CollectPromptSections collects daemon-owned context for one dispatch attempt.
func DaemonMatchedEnv ¶
DaemonMatchedEnv binds subprocess CLI discovery to the executable running the daemon.
func EstimateTokens ¶
EstimateTokens estimates only known text bytes, without consulting a tokenizer.
func FailureFromError ¶
func FailureFromError(err error, fallback store.FailureKind) (*store.SessionFailure, bool)
FailureFromError extracts a redacted session failure from a typed or classifiable error.
func IsLoadSessionResourceMissing ¶
IsLoadSessionResourceMissing reports whether a resume failed because the upstream ACP implementation no longer knows the referenced session id.
func RegisterPromptSection ¶
func RegisterPromptSection(ctx context.Context, section PromptSection)
RegisterPromptSection keeps compaction metadata out of provider-visible prompt metadata.
func ReplaceProviderFailureDiagnostic ¶
func ReplaceProviderFailureDiagnostic(summary string, d ProviderFailureDiagnostic) string
ReplaceProviderFailureDiagnostic rewrites the recovery metadata of summary with d, keeping the human-readable prefix unchanged.
func ResolveSteerCapability ¶
func ResolveSteerCapability( provider string, announced []string, override config.SteerCapability, ) config.SteerCapability
func ValidateACPModePermissions ¶
func ValidateACPModePermissions( options []SessionConfigOptionSelection, permissions compozyconfig.PermissionMode, ) error
ValidateACPModePermissions keeps unrestricted provider modes behind the effective session permission policy at both start and live runtime changes.
func ValidateModelConfigValue ¶
func ValidateModelConfigValue(options []SessionConfigOption, modelID string) error
ValidateModelConfigValue verifies that modelID is an exact advertised ACP model value.
func WrapAcceptedStart ¶
WrapAcceptedStart marks err as a failure raised after ACP accepted sessionID. The driver and the layers above it (session persistence, activation) use it so every chain owner derives acceptance from one fact. An error that already carries the acceptance fact is returned unchanged.
func WrapFailure ¶
func WrapFailure(kind store.FailureKind, summary string, err error) error
WrapFailure annotates err with a typed ACP/session failure classification.
Types ¶
type AcceptedStartError ¶
AcceptedStartError reports a failure that happened after ACP accepted the session: session/new or session/load returned a session id. Fallback-chain owners must stop on it; the accepted route is final for that binding even though the start failed.
func (*AcceptedStartError) Error ¶
func (e *AcceptedStartError) Error() string
Error implements error.
func (*AcceptedStartError) Unwrap ¶
func (e *AcceptedStartError) Unwrap() error
Unwrap exposes the post-acceptance cause so failure classification keeps working.
type AgentEvent ¶
type AgentEvent struct {
Type string
SessionID string
TurnID string
store.EventCorrelation
Timestamp time.Time
Text string
Title string
ToolCallID string
StopReason string
PromptStopReason PromptStopReason
Action string
Resource string
Decision string
Error string
Failure *store.SessionFailure
ProviderError *ProviderErrorDiagnostic
Synthetic *PromptSyntheticMeta
Goal *GoalPromptMeta
Usage *TokenUsage
Runtime *RuntimeActivity
Raw json.RawMessage
// contains filtered or unexported fields
}
AgentEvent is the stream item exposed to session/.
func PromptStreamIncompleteEvent ¶
func PromptStreamIncompleteEvent() AgentEvent
PromptStreamIncompleteEvent returns the canonical terminal failure for an upstream stream that closes without declaring completion or failure.
func (AgentEvent) Attachments ¶
func (e AgentEvent) Attachments() []EventAttachment
Attachments returns an isolated copy of attachment metadata.
func (AgentEvent) AvailableCommandSet ¶
func (e AgentEvent) AvailableCommandSet() *AvailableCommandSet
AvailableCommandSet returns the optional replacement command set.
func (AgentEvent) DeliveryManifest ¶
func (e AgentEvent) DeliveryManifest() *DeliveryManifest
DeliveryManifest returns an isolated receipt, when present.
func (*AgentEvent) EventIDValue ¶
func (e *AgentEvent) EventIDValue() string
EventIDValue returns the stable durable identity reserved for the event.
func (AgentEvent) HasToolPayload ¶
func (e AgentEvent) HasToolPayload() bool
HasToolPayload reports whether typed tool metadata is present on the event.
func (*AgentEvent) MessageIDValue ¶
func (e *AgentEvent) MessageIDValue() string
MessageIDValue returns the normalized identity for an authored user message.
func (AgentEvent) PromptRuntimeSnapshot ¶
func (e AgentEvent) PromptRuntimeSnapshot() *PromptRuntime
PromptRuntimeSnapshot returns an isolated effective runtime snapshot.
func (AgentEvent) RequestIDValue ¶
func (e AgentEvent) RequestIDValue() string
RequestIDValue returns the externally addressable request identity.
func (AgentEvent) ResolvedByValue ¶
func (e AgentEvent) ResolvedByValue() string
ResolvedByValue returns the normalized actor that resolved an interaction.
func (AgentEvent) SkillInvocations ¶
func (e AgentEvent) SkillInvocations() []commandpkg.Invocation
SkillInvocations returns an isolated copy of admitted slash metadata.
func (AgentEvent) ToolError ¶
func (e AgentEvent) ToolError() bool
ToolError reports whether the optional tool result failed.
func (AgentEvent) ToolErrorDetail ¶
func (e AgentEvent) ToolErrorDetail() string
ToolErrorDetail returns the optional tool-result failure detail.
func (AgentEvent) ToolInput ¶
func (e AgentEvent) ToolInput() json.RawMessage
ToolInput returns an isolated copy of the optional tool input.
func (AgentEvent) ToolKind ¶
func (e AgentEvent) ToolKind() string
ToolKind returns the optional normalized tool kind.
func (AgentEvent) ToolName ¶
func (e AgentEvent) ToolName() string
ToolName returns the optional tool name.
func (AgentEvent) ToolPrechecked ¶
func (e AgentEvent) ToolPrechecked() bool
ToolPrechecked reports whether tool admission was already enforced.
func (AgentEvent) WithAttachments ¶
func (e AgentEvent) WithAttachments(attachments []EventAttachment) AgentEvent
WithAttachments returns an event carrying isolated attachment metadata.
func (AgentEvent) WithAvailableCommands ¶
func (e AgentEvent) WithAvailableCommands(commands []store.SessionAdvertisedCommand) AgentEvent
WithAvailableCommands returns an event carrying an isolated replacement command set.
func (AgentEvent) WithDelivery ¶
func (e AgentEvent) WithDelivery(manifest *DeliveryManifest) AgentEvent
WithDelivery returns an event carrying an isolated confirmed delivery receipt.
func (AgentEvent) WithEventID ¶
func (e AgentEvent) WithEventID(eventID string) AgentEvent
WithEventID returns an event carrying its stable durable event identity.
func (AgentEvent) WithMessageID ¶
func (e AgentEvent) WithMessageID(messageID string) AgentEvent
WithMessageID returns an event carrying the normalized authored-message identity.
func (AgentEvent) WithPromptRuntime ¶
func (e AgentEvent) WithPromptRuntime(runtime *PromptRuntime) AgentEvent
WithPromptRuntime returns an event carrying an isolated effective runtime snapshot.
func (AgentEvent) WithRequestID ¶
func (e AgentEvent) WithRequestID(requestID string) AgentEvent
WithRequestID returns an event carrying its externally addressable request identity.
func (AgentEvent) WithResolvedBy ¶
func (e AgentEvent) WithResolvedBy(resolvedBy string) AgentEvent
WithResolvedBy returns an event carrying the normalized interaction actor.
func (AgentEvent) WithSkillInvocations ¶
func (e AgentEvent) WithSkillInvocations(invocations []commandpkg.Invocation) AgentEvent
WithSkillInvocations returns an event carrying isolated admitted slash metadata.
func (AgentEvent) WithTool ¶
func (e AgentEvent) WithTool(name string, input json.RawMessage, failed bool) AgentEvent
WithTool returns an event carrying an isolated optional tool payload.
func (AgentEvent) WithToolDetail ¶
func (e AgentEvent) WithToolDetail( name string, input json.RawMessage, failed bool, errorDetail string, ) AgentEvent
WithToolDetail returns an event carrying isolated tool metadata and an optional result error.
func (AgentEvent) WithToolKind ¶
func (e AgentEvent) WithToolKind(kind string) AgentEvent
WithToolKind returns an event carrying the normalized tool kind.
func (AgentEvent) WithToolPrechecked ¶
func (e AgentEvent) WithToolPrechecked() AgentEvent
WithToolPrechecked marks tool admission as already enforced at the ACP boundary.
type AgentProcess ¶
type AgentProcess struct {
PID int
AgentName string
Command string
Args []string
Cwd string
SessionID string
StartedAt time.Time
// contains filtered or unexported fields
}
AgentProcess represents one running ACP-backed agent subprocess.
func (*AgentProcess) CapsSnapshot ¶
func (p *AgentProcess) CapsSnapshot() Caps
CapsSnapshot returns the latest ACP capability/config snapshot.
func (*AgentProcess) Done ¶
func (p *AgentProcess) Done() <-chan struct{}
Done returns a channel that closes when the subprocess exits.
func (*AgentProcess) ExitStatus ¶
func (p *AgentProcess) ExitStatus() (subprocess.ExitStatus, bool)
ExitStatus returns the OS exit facts exposed by the underlying process handle.
func (*AgentProcess) ForkSession ¶
func (p *AgentProcess) ForkSession( ctx context.Context, cwd string, mcpServers []acpsdk.McpServer, ) (ForkSessionResult, error)
ForkSession calls unstable session/fork on this (bound) process for the caller's cwd. While the call is open, and afterwards, notifications and callbacks whose sessionId is the returned clone id are delivered to the fork sink (captured in Updates) or quarantined; they are never emitted on the bound session's prompt stream and p.SessionID never changes.
func (*AgentProcess) HasPendingPermission ¶
func (p *AgentProcess) HasPendingPermission() bool
HasPendingPermission reports whether this process is waiting for an interactive permission decision.
func (*AgentProcess) HealthState ¶
func (p *AgentProcess) HealthState() subprocess.HealthState
HealthState returns the latest managed subprocess health snapshot.
func (*AgentProcess) IngestStats ¶
func (p *AgentProcess) IngestStats() IngestStats
IngestStats exposes the active transport backlog to session supervision.
func (*AgentProcess) RequestPermission ¶
func (p *AgentProcess) RequestPermission( ctx context.Context, req RequestPermissionRequest, ) (RequestPermissionResponse, error)
RequestPermission reuses the ACP client-side permission path for daemon-originated tool approvals. The daemon already routed the request to this process by its Compozy session id, which is not the ACP session id, so the inbound bound-session guard that quarantines agent callbacks from clone or foreign ids does not apply here.
func (*AgentProcess) ResolvePermission ¶
func (p *AgentProcess) ResolvePermission(req ApproveRequest) error
ResolvePermission delivers a user decision to a waiting permission request.
func (*AgentProcess) Stderr ¶
func (p *AgentProcess) Stderr() string
Stderr returns the currently captured stderr output for the subprocess.
func (*AgentProcess) ToolHost ¶
func (p *AgentProcess) ToolHost() ToolHost
ToolHost returns the local tool host used by this process.
func (*AgentProcess) Wait ¶
func (p *AgentProcess) Wait() error
Wait blocks until the subprocess exits and returns its final error state.
type ApproveRequest ¶
type ApproveRequest struct {
RequestID string `json:"request_id,omitempty"`
TurnID string `json:"turn_id,omitempty"`
Decision string `json:"decision"`
ResolvedBy string `json:"-"`
}
ApproveRequest resolves one pending permission request.
func (ApproveRequest) Validate ¶
func (r ApproveRequest) Validate() error
Validate ensures the approval request can be matched to a pending permission.
type AvailableCommandSet ¶
type AvailableCommandSet []store.SessionAdvertisedCommand
AvailableCommandSet is the optional replacement payload carried only by available-commands events.
func NewAvailableCommandSet ¶
func NewAvailableCommandSet(commands []store.SessionAdvertisedCommand) *AvailableCommandSet
NewAvailableCommandSet returns an isolated, explicitly present replacement set. An empty input remains distinguishable from an absent event payload.
func (*AvailableCommandSet) Values ¶
func (s *AvailableCommandSet) Values() []store.SessionAdvertisedCommand
Values returns an isolated slice representation of the replacement set.
type BroadcastStats ¶
type BroadcastStats struct {
Subscribers int `json:"subscribers"`
Depth int `json:"depth"`
Shed uint64 `json:"shed"`
}
BroadcastStats measures only post-append delivery, never ingest admission.
type Caps ¶
type Caps struct {
SteerCapability compozyconfig.SteerCapability
SupportsLoadSession bool
SupportsCloseSession bool
SupportsForkSession bool
SupportsResumeSession bool
PromptImage bool
PromptAudio bool
PromptEmbeddedContext bool
SupportedModes []string
ConfigOptions []SessionConfigOption
SpeedResolution *speedpkg.Resolution
}
Caps captures the usable capabilities exposed by an ACP agent.
type CommandResult ¶
CommandResult reports one completed command without interpreting its output.
type CommandRuntime ¶
type CommandRuntime interface {
Resolve(ctx context.Context, command string, env []string, cwd string) (string, error)
Run(ctx context.Context, spec CommandSpec) (CommandResult, error)
}
CommandRuntime resolves and runs diagnostic commands in one runtime.
type CommandSpec ¶
CommandSpec identifies one already-resolved command in a runtime.
type DeliveredSpan ¶
type DeliveredSpan struct {
Key string `json:"key"`
Kind string `json:"kind"`
Bytes int64 `json:"bytes"`
Tokens *int64 `json:"tokens,omitempty"`
Unchanged bool `json:"unchanged"`
StartupDedup bool `json:"startup_dedup,omitzero"`
Delivery string `json:"delivery,omitempty"`
HookModified bool `json:"hook_modified,omitzero"`
Name string `json:"name,omitempty"`
}
func TextSpan ¶
func TextSpan(key, text string) DeliveredSpan
TextSpan measures the exact text selected for delivery.
type DeliveryManifest ¶
type DeliveryManifest struct {
TurnID string `json:"turn_id"`
SentAt time.Time `json:"sent_at"`
Estimate string `json:"estimate"`
Spans []DeliveredSpan `json:"spans"`
}
type Driver ¶
type Driver struct {
// contains filtered or unexported fields
}
Driver launches ACP agent subprocesses and brokers JSON-RPC traffic.
func (*Driver) ApprovePermission ¶
func (d *Driver) ApprovePermission(ctx context.Context, proc *AgentProcess, req ApproveRequest) error
ApprovePermission resolves a pending interactive permission request for the process.
func (*Driver) Cancel ¶
func (d *Driver) Cancel(ctx context.Context, proc *AgentProcess) error
Cancel cancels only the active prompt and is an idempotent no-op once it settles.
func (*Driver) CancelCooperatively ¶
func (d *Driver) CancelCooperatively(ctx context.Context, proc *AgentProcess) error
CancelCooperatively requests peer cancellation without ending the local prompt. The prompt response or process exit remains the evidence that work has stopped.
func (*Driver) ConfigureRuntime ¶
func (d *Driver) ConfigureRuntime(ctx context.Context, process *AgentProcess, config RuntimeConfig) error
ConfigureRuntime applies model, refreshed capabilities, reasoning, and speed in order.
func (*Driver) Interrupt ¶
func (d *Driver) Interrupt( ctx context.Context, scope toolruntime.InterruptScope, ) (toolruntime.InterruptReport, error)
Interrupt signals processes matching a scoped toolruntime selector.
func (*Driver) Kill ¶
func (d *Driver) Kill(ctx context.Context, proc *AgentProcess) error
Kill attempts the final process-tree termination phase independently of a canceled request.
func (*Driver) NotifyExtension ¶
func (d *Driver) NotifyExtension( ctx context.Context, proc *AgentProcess, method string, params any, ) error
NotifyExtension sends one fire-and-forget `_`-prefixed notification over the live agent connection.
func (*Driver) Prompt ¶
func (d *Driver) Prompt(ctx context.Context, proc *AgentProcess, req PromptRequest) (<-chan AgentEvent, error)
Prompt starts one prompt turn and returns the streamed event channel.
func (*Driver) Start ¶
Start launches a subprocess, completes ACP initialization, and creates or resumes a session.
func (*Driver) Steer ¶
func (d *Driver) Steer(ctx context.Context, proc *AgentProcess, turnID, text string) (SteerResult, error)
func (*Driver) Stop ¶
func (d *Driver) Stop(ctx context.Context, proc *AgentProcess) error
Stop terminates the subprocess and waits for it to exit.
func (*Driver) VerifyExit ¶
func (d *Driver) VerifyExit(proc *AgentProcess) (bool, error)
VerifyExit distinguishes confirmed process exit from a failed status lookup.
type EventAttachment ¶
type EventAttachment struct {
ID string `json:"id"`
Name string `json:"name"`
MIMEType string `json:"mime_type"`
Bytes int64 `json:"bytes"`
SHA256 string `json:"sha256"`
Kind string `json:"kind"`
Width int `json:"width,omitempty"`
Height int `json:"height,omitempty"`
}
EventAttachment is durable attachment metadata carried by an agent event.
type FailureError ¶
type FailureError struct {
Kind store.FailureKind
Summary string
Err error
}
FailureError carries a typed lifecycle classification beside the wrapped ACP error so session orchestration can persist the failure without parsing text.
func (*FailureError) Error ¶
func (e *FailureError) Error() string
func (*FailureError) Unwrap ¶
func (e *FailureError) Unwrap() error
type ForkSessionResult ¶
type ForkSessionResult struct {
// SessionID is the clone's ACP session id returned by the agent.
SessionID acpsdk.SessionId
// Updates are the notifications the agent sent for the clone id before the
// response returned (command lists, history replay). Diagnostics only.
Updates []acpsdk.SessionNotification
}
ForkSessionResult is the outcome of one unstable session/fork call.
type GoalPromptMeta ¶
type GoalPromptMeta struct {
Kind string `json:"kind"`
RunID string `json:"run_id"`
NodeID string `json:"node_id"`
Generation int64 `json:"generation"`
ItemIndex int `json:"item_index"`
Turn *int `json:"turn"`
PromptAttempt int `json:"prompt_attempt"`
PromptID string `json:"prompt_id"`
}
GoalPromptMeta classifies one engine-owned Goal prompt without importing Loop.
func CloneGoalPromptMeta ¶
func CloneGoalPromptMeta(meta *GoalPromptMeta) *GoalPromptMeta
CloneGoalPromptMeta returns an isolated normalized pointer.
func (GoalPromptMeta) IsZero ¶
func (m GoalPromptMeta) IsZero() bool
IsZero reports whether the metadata carries no Goal identity.
func (GoalPromptMeta) Normalize ¶
func (m GoalPromptMeta) Normalize() GoalPromptMeta
Normalize returns a trimmed, isolated copy.
func (GoalPromptMeta) Validate ¶
func (m GoalPromptMeta) Validate() error
Validate enforces the closed public Goal prompt metadata contract.
type Handle ¶
type Handle interface {
PID() int
Cwd() string
Stdin() io.WriteCloser
Stdout() io.ReadCloser
Stderr() string
Done() <-chan struct{}
Wait() error
Stop(ctx context.Context) error
}
Handle represents a running agent process.
type IngestGate ¶
type IngestGate struct {
// contains filtered or unexported fields
}
IngestGate accepts bounded, lossless work without waiting for its consumer. Close retains accepted events for Next, then returns the closing error.
func NewIngestGate ¶
func NewIngestGate(capacity, maxBytes int) *IngestGate
func (*IngestGate) Admit ¶
func (g *IngestGate) Admit(event AgentEvent) error
func (*IngestGate) Close ¶
func (g *IngestGate) Close(reason error)
func (*IngestGate) Next ¶
func (g *IngestGate) Next(ctx context.Context) (AgentEvent, error)
Next drains accepted work in order. Its wait is exclusively consumer-owned.
func (*IngestGate) Stats ¶
func (g *IngestGate) Stats() IngestStats
type IngestStats ¶
type IngestStats struct {
Depth int `json:"depth"`
Bytes int `json:"bytes"`
Coalesced uint64 `json:"coalesced"`
}
IngestStats describes accepted pre-append work, including coalesced chunks.
type LaunchPreparer ¶
type LaunchPreparer interface {
PrepareLaunch(ctx context.Context, spec LaunchSpec) (LaunchSpec, error)
}
LaunchPreparer resolves one final launch specification inside the launcher's runtime.
type LaunchSpec ¶
type LaunchSpec struct {
Command string
// ResolvedExecutable and Args carry a launcher's prepared terminal identity.
// A launcher that prepares them must execute this absolute identity without
// resolving Command again.
ResolvedExecutable string
Args []string
Cwd string
AdditionalDirs []string
Env []string
}
LaunchSpec describes the ACP-capable command to start locally.
type Launcher ¶
type Launcher interface {
Launch(ctx context.Context, spec LaunchSpec) (Handle, error)
}
Launcher starts an ACP-capable agent process locally.
type LiveBroadcast ¶
type LiveBroadcast struct {
// contains filtered or unexported fields
}
LiveBroadcast distributes persisted events. A shed subscriber receives one replay marker and closes; its owner queries durable history after its cursor.
func NewLiveBroadcast ¶
func NewLiveBroadcast(capacity int) *LiveBroadcast
func (*LiveBroadcast) Publish ¶
func (b *LiveBroadcast) Publish(sequence uint64, event store.SessionEvent) bool
Publish must be called after event's durable append. Sequence is its store cursor; the broadcast neither allocates cursors nor acknowledges ingestion.
func (*LiveBroadcast) Stats ¶
func (b *LiveBroadcast) Stats() BroadcastStats
func (*LiveBroadcast) Subscribe ¶
func (b *LiveBroadcast) Subscribe(after uint64, wakeOnly bool) (<-chan store.SessionEvent, func())
type LocalRuntimeOption ¶
type LocalRuntimeOption func(*localRuntimeConfig)
LocalRuntimeOption customizes local ACP runtime helpers.
func WithLocalAdditionalRoots ¶
func WithLocalAdditionalRoots(roots ...string) LocalRuntimeOption
WithLocalAdditionalRoots authorizes local tool-host paths outside the primary root.
func WithLocalTerminalManager ¶
func WithLocalTerminalManager(manager TerminalHost, scope LocalTerminalScope) LocalRuntimeOption
type LocalTerminalScope ¶
type NegotiationError ¶
type NegotiationError struct {
Code string
Stage string
Requested string
ConfigOptionID string
ValidChoices []string
Cause error
}
NegotiationError reports one model or reasoning request rejected before the first prompt.
func (*NegotiationError) Error ¶
func (e *NegotiationError) Error() string
func (*NegotiationError) Unwrap ¶
func (e *NegotiationError) Unwrap() error
type Option ¶
type Option func(*Driver)
Option customizes the ACP driver.
func WithControlTimeout ¶
WithControlTimeout bounds each non-prompt ACP request; nonpositive values use the default.
func WithLauncher ¶
WithLauncher overrides the process launcher used by default for new ACP sessions.
func WithLogger ¶
WithLogger directs driver diagnostics to the provided logger.
func WithPermissionTimeout ¶
WithPermissionTimeout overrides how long an interactive permission request waits for approval.
func WithProcessRecordTimeout ¶
WithProcessRecordTimeout bounds process registry writes during ACP interruption and exit. Initial registration uses the startup context, like the rest of process initialization.
func WithProcessRegistry ¶
func WithProcessRegistry(registry *toolruntime.Registry) Option
WithProcessRegistry injects shared tool process tracking and scoped interrupts.
func WithPromptBufferSize ¶
WithPromptBufferSize overrides the per-prompt event buffer size.
func WithPromptDrainWait ¶
WithPromptDrainWait overrides how long Prompt waits for trailing asynchronous updates.
func WithProviderPreStarter ¶
func WithProviderPreStarter(starter ProviderPreStarter) Option
WithProviderPreStarter injects the daemon-owned provider auth probe boundary.
func WithStartAttempts ¶
WithStartAttempts sets the fresh-process ceiling for timed-out session/new; nonpositive values use two.
func WithStopTimeout ¶
WithStopTimeout overrides how long Stop waits before escalating to SIGKILL.
func WithTerminalManager ¶
func WithTerminalManager(manager TerminalHost) Option
WithTerminalManager injects the daemon-owned terminal core for local ACP commands.
func WithToolHost ¶
WithToolHost overrides the local tool host used by default for new ACP sessions.
type PermissionDecision ¶
type PermissionDecision string
PermissionDecision is a daemon policy decision for an ACP permission request.
const ( // PermissionDecisionPending asks an operator or client to decide. PermissionDecisionPending PermissionDecision = "pending" // PermissionDecisionCanceled closes a request without an operator decision. PermissionDecisionCanceled PermissionDecision = "canceled" // PermissionDecisionAllowOnce permits one operation. PermissionDecisionAllowOnce PermissionDecision = "allow-once" // PermissionDecisionAllowAlways permits this class of operation persistently. PermissionDecisionAllowAlways PermissionDecision = "allow-always" // PermissionDecisionRejectOnce rejects one operation. PermissionDecisionRejectOnce PermissionDecision = "reject-once" // PermissionDecisionRejectAlways rejects this class of operation persistently. PermissionDecisionRejectAlways PermissionDecision = "reject-always" )
type PermissionOperation ¶
type PermissionOperation string
PermissionOperation identifies a ToolHost operation subject to policy.
const ( // PermissionOperationReadTextFile authorizes ACP text file reads. PermissionOperationReadTextFile PermissionOperation = "fs/read_text_file" // PermissionOperationWriteTextFile authorizes ACP text file writes. PermissionOperationWriteTextFile PermissionOperation = "fs/write_text_file" // PermissionOperationCreateTerminal authorizes terminal creation. PermissionOperationCreateTerminal PermissionOperation = "terminal/create" // PermissionOperationCloseTerminal authorizes closing a live terminal. PermissionOperationCloseTerminal PermissionOperation = "terminal/close" // PermissionOperationRequestToolGrant authorizes interactive permission requests. PermissionOperationRequestToolGrant PermissionOperation = "session/request_permission" )
type ProbeLookup ¶
ProbeLookup resolves an executable name. Tests can inject a blocking lookup to validate timeout/cancellation without sleeping in production code.
type ProbeOptions ¶
type ProbeOptions struct {
Timeout time.Duration
Now func() time.Time
Lookup ProbeLookup
}
ProbeOptions configures command probing.
type ProbeResult ¶
type ProbeResult struct {
AgentName string `json:"agent_name,omitempty"`
Provider string `json:"provider,omitempty"`
Command string `json:"command,omitempty"`
Executable string `json:"executable,omitempty"`
Status string `json:"status"`
Error string `json:"error,omitempty"`
CheckedAt time.Time `json:"checked_at"`
DurationMS int64 `json:"duration_ms"`
}
ProbeResult is the structured health output for one downstream agent command.
func ProbeTargetCommand ¶
func ProbeTargetCommand(ctx context.Context, target ProbeTarget, opts ProbeOptions) (result ProbeResult)
ProbeTargetCommand checks one target command by resolving its executable.
func ProbeTargets ¶
func ProbeTargets(ctx context.Context, targets []ProbeTarget, opts ProbeOptions) []ProbeResult
ProbeTargets checks every target with bounded timeout/cancellation behavior.
type ProbeTarget ¶
ProbeTarget identifies one configured ACP-compatible agent/provider command that should be checked before operators need to start a session.
type ProcessSignal ¶
type ProcessSignal string
ProcessSignal identifies one action in the session owner's termination ladder.
const ( ProcessSignalCloseInput ProcessSignal = "close-input" ProcessSignalTerminate ProcessSignal = "terminate" ProcessSignalKill ProcessSignal = "kill" )
type PromptActivityReport ¶
PromptActivityReport is a low-frequency runtime heartbeat emitted by the driver.
type PromptActivityReporter ¶
type PromptActivityReporter func(PromptActivityReport)
PromptActivityReporter receives runtime activity observed while a prompt is in flight.
type PromptAttachment ¶
PromptAttachment carries resolved attachment bytes into the ACP boundary.
type PromptJudgeMeta ¶
type PromptJudgeMeta struct {
Role string `json:"role"`
Attempt int `json:"attempt"`
CorrelationID string `json:"correlation_id"`
GateID string `json:"gate_id"`
CriterionID string `json:"criterion_id"`
}
PromptJudgeMeta carries stable routing identity for one daemon-owned judge prompt.
func (PromptJudgeMeta) IsZero ¶
func (m PromptJudgeMeta) IsZero() bool
IsZero reports whether the metadata carries no judge identity.
func (PromptJudgeMeta) Normalize ¶
func (m PromptJudgeMeta) Normalize() PromptJudgeMeta
Normalize returns a trimmed copy.
func (PromptJudgeMeta) Validate ¶
func (m PromptJudgeMeta) Validate() error
Validate enforces the closed judge prompt metadata contract.
type PromptMeta ¶
type PromptMeta struct {
TurnSource string `json:"turn_source,omitempty"`
Synthetic *PromptSyntheticMeta `json:"synthetic,omitempty"`
Judge *PromptJudgeMeta `json:"judge,omitempty"`
System *PromptSystemMeta `json:"system,omitempty"`
}
PromptMeta carries structured, transport-stable metadata for one ACP prompt.
func (PromptMeta) IsZero ¶
func (m PromptMeta) IsZero() bool
IsZero reports whether the prompt metadata carries any fields.
func (PromptMeta) Normalize ¶
func (m PromptMeta) Normalize() PromptMeta
Normalize returns a trimmed copy of the prompt metadata.
func (PromptMeta) ToMap ¶
func (m PromptMeta) ToMap() (map[string]any, error)
ToMap converts normalized prompt metadata to the ACP SDK extensibility map.
func (PromptMeta) Validate ¶
func (m PromptMeta) Validate() error
Validate ensures the metadata shape is internally consistent.
type PromptRequest ¶
type PromptRequest struct {
TurnID string
RunID string
Generation int64
Message string
Sections []PromptSection
Attachments []PromptAttachment
Meta PromptMeta
ActivityReporter PromptActivityReporter
ActivityHeartbeatInterval time.Duration
}
PromptRequest describes one prompt turn sent to an active ACP session.
func (PromptRequest) Validate ¶
func (r PromptRequest) Validate() error
Validate ensures the prompt request can be sent to the agent.
type PromptRuntime ¶
type PromptRuntime struct {
Provider string `json:"provider"`
Model string `json:"model,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
Speed speedpkg.Speed `json:"speed,omitempty"`
ACPOptions []SessionConfigOptionSelection `json:"acp_options,omitempty"`
}
PromptRuntime is the immutable effective runtime attached to every event in one prompt turn.
func ClonePromptRuntime ¶
func ClonePromptRuntime(runtime *PromptRuntime) *PromptRuntime
ClonePromptRuntime returns an isolated prompt-runtime snapshot.
type PromptSection ¶
type PromptSection struct {
Key string
Content string
StartupContent string
UnchangedContent string
}
PromptSection retains full context until the transport confirms its delivery.
type PromptStopReason ¶
type PromptStopReason string
PromptStopReason is the closed ACP turn-completion reason vocabulary.
const ( PromptStopReasonEndTurn PromptStopReason = "end_turn" PromptStopReasonMaxTokens PromptStopReason = "max_tokens" PromptStopReasonMaxTurnRequests PromptStopReason = "max_turn_requests" PromptStopReasonRefusal PromptStopReason = "refusal" // ACP spells the cancellation wire value with a doubled l. PromptStopReasonCancelled PromptStopReason = "cancel" + "led" // EventTypeAvailableCommands replaces the current typed command set for a session. EventTypeAvailableCommands = "available_commands_update" )
func (PromptStopReason) Valid ¶
func (r PromptStopReason) Valid() bool
Valid reports whether the value is one of the five ACP stop reasons.
type PromptSyntheticMeta ¶
type PromptSyntheticMeta struct {
TaskID string `json:"task_id,omitempty"`
TaskRunID string `json:"task_run_id,omitempty"`
WorkflowID string `json:"workflow_id,omitempty"`
ClaimTokenHash string `json:"claim_token_hash,omitempty"`
CoordinatorSessionID string `json:"coordinator_session_id,omitempty"`
ChildSessionID string `json:"child_session_id,omitempty"`
ChildAgentName string `json:"child_agent_name,omitempty"`
Badge string `json:"badge,omitempty"`
Reason string `json:"reason,omitempty"`
Summary string `json:"summary,omitempty"`
WakeEventID string `json:"wake_event_id,omitempty"`
PolicySnapshotID string `json:"policy_snapshot_id,omitempty"`
PolicyDigest string `json:"policy_digest,omitempty"`
ConfigDigest string `json:"config_digest,omitempty"`
Goal *GoalPromptMeta `json:"goal,omitempty"`
}
PromptSyntheticMeta captures stable daemon-owned metadata for one synthetic prompt turn.
func (PromptSyntheticMeta) IsZero ¶
func (m PromptSyntheticMeta) IsZero() bool
IsZero reports whether the synthetic metadata carries any fields.
func (PromptSyntheticMeta) Normalize ¶
func (m PromptSyntheticMeta) Normalize() PromptSyntheticMeta
Normalize returns a trimmed copy of the synthetic metadata.
func (PromptSyntheticMeta) Validate ¶
func (m PromptSyntheticMeta) Validate() error
Validate ensures the synthetic metadata carries the minimum wake-up identity.
type PromptSystemMeta ¶
type PromptSystemMeta struct {
PromptDelivery string `json:"prompt_delivery,omitempty"`
}
PromptSystemMeta captures daemon-owned prompt delivery metadata.
func (PromptSystemMeta) IsZero ¶
func (m PromptSystemMeta) IsZero() bool
IsZero reports whether the system metadata carries any fields.
func (PromptSystemMeta) Normalize ¶
func (m PromptSystemMeta) Normalize() PromptSystemMeta
Normalize returns a trimmed copy of the system metadata.
func (PromptSystemMeta) Validate ¶
func (m PromptSystemMeta) Validate() error
Validate ensures the system metadata shape is internally consistent.
type ProviderErrorDiagnostic ¶
type ProviderErrorDiagnostic struct {
Code string `json:"code"`
Provider string `json:"provider"`
NextAction ProviderFailureAction `json:"next_action"`
Guidance string `json:"guidance"`
OccurrenceCount uint64 `json:"occurrence_count"`
FirstSeenAt time.Time `json:"first_seen_at"`
LastSeenAt time.Time `json:"last_seen_at"`
}
ProviderErrorDiagnostic describes a recoverable provider failure within one process lifetime.
func CloneProviderErrorDiagnostic ¶
func CloneProviderErrorDiagnostic(diagnostic *ProviderErrorDiagnostic) *ProviderErrorDiagnostic
CloneProviderErrorDiagnostic isolates diagnostics attached to emitted events.
type ProviderFailureAction ¶
type ProviderFailureAction string
ProviderFailureAction is the stable next action paired with a provider failure classification.
const ( ProviderFailureActionInstallCLI ProviderFailureAction = "install_cli" ProviderFailureActionLogin ProviderFailureAction = "login" ProviderFailureActionBindSecret ProviderFailureAction = "bind_secret" ProviderFailureActionInspect ProviderFailureAction = "inspect" ProviderFailureActionChangeModel ProviderFailureAction = "change_model" ProviderFailureActionRequestPermission ProviderFailureAction = "request_permission" ProviderFailureActionWait ProviderFailureAction = "wait" ProviderFailureActionRetry ProviderFailureAction = "retry" ProviderFailureActionNoRetry ProviderFailureAction = "no_retry" // ProviderFailureActionUseFallback marks a refused pre-acceptance attempt after which // the session layer advances to the next configured route (never set by the classifier). ProviderFailureActionUseFallback ProviderFailureAction = "use_fallback" // ProviderFailureActionHandoff prescribes continuing a user session with another agent // or route after a post-acceptance prompt failure; decorated by the session owner // (never set by the classifier, which has no session type). ProviderFailureActionHandoff ProviderFailureAction = "handoff" )
type ProviderFailureDiagnostic ¶
type ProviderFailureDiagnostic struct {
Kind ProviderFailureKind
Action ProviderFailureAction
Guidance string
}
ProviderFailureDiagnostic is the typed provider-specific recovery metadata embedded into redacted session failure summaries.
func ProviderFailureDiagnosticFromError ¶
func ProviderFailureDiagnosticFromError(err error) (ProviderFailureDiagnostic, bool)
ProviderFailureDiagnosticFromError returns stable provider recovery metadata for known ACP/native-provider failure signals.
func ProviderFailureDiagnosticFromSummary ¶
func ProviderFailureDiagnosticFromSummary(summary string) (ProviderFailureDiagnostic, bool)
ProviderFailureDiagnosticFromSummary recovers the recovery metadata that ProviderFailureDiagnostic.Summary appended to a redacted failure summary.
func (ProviderFailureDiagnostic) Summary ¶
func (d ProviderFailureDiagnostic) Summary(summary string) string
Summary attaches stable recovery metadata to the redacted failure text.
type ProviderFailureKind ¶
type ProviderFailureKind string
ProviderFailureKind classifies provider-facing failures into the recovery branches operators and agents need at the CLI/API boundary.
const ( ProviderFailureMissingCLI ProviderFailureKind = "missing_cli" ProviderFailureUnauthenticated ProviderFailureKind = "not_authenticated" ProviderFailureInvalidModel ProviderFailureKind = "invalid_model" ProviderFailurePermissionDenied ProviderFailureKind = "permission_denied" ProviderFailureRateLimited ProviderFailureKind = "rate_limited" ProviderFailureTransient ProviderFailureKind = "transient" )
type ProviderPreStarter ¶
type ProviderPreStarter interface {
PreStart(context.Context, compozyconfig.ProviderConfig, *authproviders.ProbeEnv) authproviders.PreStartReport
}
ProviderPreStarter classifies provider readiness before ACP process launch. The daemon owns the concrete cache instance and injects it at composition.
type RequestPermissionRequest ¶
type RequestPermissionRequest = acpsdk.RequestPermissionRequest
RequestPermissionRequest asks the session permission bridge for a tool-call decision.
type RequestPermissionResponse ¶
type RequestPermissionResponse = acpsdk.RequestPermissionResponse
RequestPermissionResponse reports the selected or canceled permission outcome.
type RuntimeActivity ¶
type RuntimeActivity struct {
TurnID string `json:"turn_id,omitempty"`
TurnSource string `json:"turn_source,omitempty"`
TurnStartedAt *time.Time `json:"turn_started_at,omitempty"`
DeadlineAt *time.Time `json:"deadline_at,omitempty"`
LastActivityAt *time.Time `json:"last_activity_at,omitempty"`
LastActivityKind string `json:"last_activity_kind,omitempty"`
LastActivityDetail string `json:"last_activity_detail,omitempty"`
CurrentTool string `json:"current_tool,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
LastProgressAt *time.Time `json:"last_progress_at,omitempty"`
IterationCurrent int `json:"iteration_current,omitempty"`
IterationMax int `json:"iteration_max,omitempty"`
IdleSeconds int64 `json:"idle_seconds,omitempty"`
ElapsedSeconds int64 `json:"elapsed_seconds,omitempty"`
ElapsedMS int64 `json:"elapsed_ms,omitempty"`
}
RuntimeActivity is the structured activity payload attached to Compozy runtime progress and warning events.
type RuntimeApplicationStrategy ¶
type RuntimeApplicationStrategy string
RuntimeApplicationStrategy identifies where provider runtime options must be applied.
const ( // RuntimeApplicationSessionConfig applies options through ACP session config methods. RuntimeApplicationSessionConfig RuntimeApplicationStrategy = "session_config" // RuntimeApplicationLaunchArg compiles options into the subprocess launch command. RuntimeApplicationLaunchArg RuntimeApplicationStrategy = "launch_arg" // RuntimeApplicationProviderManaged leaves runtime selection to the provider-owned bridge. RuntimeApplicationProviderManaged RuntimeApplicationStrategy = "provider_managed" )
type RuntimeConfig ¶
type RuntimeConfig struct {
Model string
ReasoningEffort string
Speed speedpkg.Speed
ACPOptions []SessionConfigOptionSelection
}
RuntimeConfig identifies mutable ACP settings requested for one prompt boundary.
type SessionConfigOption ¶
type SessionConfigOption struct {
ID string
Label string
Description string
Category string
Kind SessionConfigOptionKind
// ReadOnly marks discovery-only options that do not have a matching ACP
// mutation method. They remain visible for validation and inspection.
ReadOnly bool
CurrentValueID string
CurrentBool *bool
Values []SessionConfigOptionValue
}
SessionConfigOption captures one active ACP session config option.
func CloneSessionConfigOptions ¶
func CloneSessionConfigOptions(options []SessionConfigOption) []SessionConfigOption
CloneSessionConfigOptions returns a deep copy of session config options.
func InspectSessionConfigOptions ¶
func InspectSessionConfigOptions( ctx context.Context, req SessionInspectionRequest, ) ([]SessionConfigOption, error)
InspectSessionConfigOptions creates a short-lived ACP session and returns its advertised config options.
func ModelConfigOption ¶
func ModelConfigOption(options []SessionConfigOption) (SessionConfigOption, bool)
ModelConfigOption returns the ACP select option that controls the session model.
func ReasoningConfigOption ¶
func ReasoningConfigOption(options []SessionConfigOption) (SessionConfigOption, bool)
ReasoningConfigOption returns the provider's model-specific thought-level selector.
type SessionConfigOptionKind ¶
type SessionConfigOptionKind string
SessionConfigOptionKind identifies the ACP config option shape Compozy exposes.
const ( // SessionConfigOptionKindSelect is a single-value ACP config selector. SessionConfigOptionKindSelect SessionConfigOptionKind = "select" // SessionConfigOptionKindBoolean is an ACP boolean config toggle. SessionConfigOptionKindBoolean SessionConfigOptionKind = "boolean" )
type SessionConfigOptionSelection ¶
SessionConfigOptionSelection identifies one typed ACP config option update.
func CloneSessionConfigOptionSelections ¶
func CloneSessionConfigOptionSelections( selections []SessionConfigOptionSelection, ) []SessionConfigOptionSelection
CloneSessionConfigOptionSelections returns an ownership-safe copy of ACP selections.
func NormalizeSessionConfigOptionSelections ¶
func NormalizeSessionConfigOptionSelections( selections []SessionConfigOptionSelection, ) ([]SessionConfigOptionSelection, error)
NormalizeSessionConfigOptionSelections validates and canonicalizes typed ACP selections.
type SessionConfigOptionValue ¶
type SessionConfigOptionValue struct {
Value string
Label string
Description string
GroupID string
GroupLabel string
}
SessionConfigOptionValue captures one selectable value for an ACP config option.
type SessionInspectionRequest ¶
SessionInspectionRequest describes a short-lived ACP session used only to read advertised options.
type SessionModelInspection ¶
type SessionModelInspection struct {
Options []SessionConfigOption
// Models holds options only for models whose selection the agent acknowledged.
Models map[string][]SessionConfigOption
// ModelErrors records each model whose options could not be observed, whether the
// selection failed or the budget ran out first; Options stays authoritative.
ModelErrors map[string]error
}
SessionModelInspection retains options for each independently selected transport model.
func InspectSessionModels ¶
func InspectSessionModels(ctx context.Context, req SessionInspectionRequest) (SessionModelInspection, error)
InspectSessionModels reads model-specific options without submitting a prompt. The advertised model list is the discovery result; per-model option probes only enrich it, so a rejected model or an exhausted budget never discards the list.
type StartOpts ¶
type StartOpts struct {
AgentName string
CompozySessionID string
WorkspaceID string
ProfileID string
RuntimeGeneration int64
Command string
Cwd string
AdditionalDirs []string
Env []string
MCPServers []compozyconfig.MCPServer
Permissions compozyconfig.PermissionMode
SystemPrompt string
StartupManifest StartupManifest
SystemPromptDelivery SystemPromptDeliveryMode
PreferredModel string
ReasoningEffort string
Speed speedpkg.Speed
ACPOptions []SessionConfigOptionSelection
RuntimeStrategy RuntimeApplicationStrategy
LaunchModelID string
ResumeSessionID string
Launcher Launcher
ToolHost ToolHost
ToolGateway ToolExecutionGateway
ProviderName string
ProviderConfig *compozyconfig.ProviderConfig
ProviderAuthEnv *authproviders.ProbeEnv
ActivateMCPServers func(context.Context) error
Inspection bool
// contains filtered or unexported fields
}
StartOpts defines how to launch and initialize an ACP agent process.
type StartupManifest ¶
type StartupManifest struct {
Spans []DeliveredSpan
HookModified bool
}
StartupManifest describes disjoint sections of the bound startup prompt.
func CloneStartupManifest ¶
func CloneStartupManifest(manifest StartupManifest) StartupManifest
CloneStartupManifest returns an independent startup measurement snapshot.
func OpaqueStartupManifest ¶
func OpaqueStartupManifest(prompt string, hookModified bool) StartupManifest
OpaqueStartupManifest retains the final prompt when section boundaries are unknown.
type SteerAttempt ¶
type SteerAttempt string
const ( SteerAttemptInjected SteerAttempt = "injected" SteerAttemptPendingInjection SteerAttempt = "pending_injection" SteerAttemptUnsupported SteerAttempt = "unsupported" )
type SteerResult ¶
type SteerResult struct {
Attempt SteerAttempt
Completion <-chan error
}
type SystemPromptDeliveryMode ¶
type SystemPromptDeliveryMode string
SystemPromptDeliveryMode records how Compozy delivered startup system guidance to the provider harness.
const ( // SystemPromptDeliveryFirstTurnPrefix means Compozy embedded startup system // guidance in the first ACP prompt because generic ACP has no system role. SystemPromptDeliveryFirstTurnPrefix SystemPromptDeliveryMode = "first_turn_prefix" // SystemPromptDeliveryNative means the provider received startup system // guidance through a provider-native system-prompt channel. SystemPromptDeliveryNative SystemPromptDeliveryMode = "native" )
type TerminalHost ¶
type TerminalHost interface {
OpenPipe(context.Context, terminalpkg.PipeRequest) (terminalpkg.Handle, error)
Handle(context.Context, string, string, terminalpkg.ID) (terminalpkg.Handle, error)
Release(context.Context, string, string, terminalpkg.ID, terminalpkg.Actor) error
}
TerminalHost is the narrow terminal core consumed by ACP's three terminal methods.
type TokenUsage ¶
type TokenUsage struct {
Meta map[string]any
Sequence int64
TurnID string
InputTokens *int64
OutputTokens *int64
TotalTokens *int64
ThoughtTokens *int64
CacheReadTokens *int64
CacheWriteTokens *int64
ContextUsed *int64
ContextSize *int64
CostAmount *float64
CostCurrency *string
Timestamp time.Time
}
TokenUsage captures per-turn usage reported by the agent.
func (TokenUsage) IsZero ¶
func (u TokenUsage) IsZero() bool
IsZero reports whether the usage payload carries any reported values.
func (TokenUsage) Merge ¶
func (u TokenUsage) Merge(other TokenUsage) TokenUsage
Merge overlays non-nil usage fields from other into the receiver.
type ToolExecutionGateway ¶
type ToolExecutionGateway interface {
Intercept(context.Context, ToolExecutionRequest) (ToolExecutionRequest, error)
}
ToolExecutionGateway authoritatively intercepts provider-native tool calls at the execution boundary.
type ToolExecutionRequest ¶
type ToolExecutionRequest struct {
ToolID string
ReadOnly bool
Input json.RawMessage
}
ToolExecutionRequest captures one provider-native tool call before any real side effect happens.
type ToolHost ¶
type ToolHost interface {
ReadTextFile(ctx context.Context, path string) (string, error)
WriteTextFile(ctx context.Context, path string, content string) error
ResolvePath(path string) (string, error)
Authorize(op PermissionOperation) error
PermissionDecision(req acpsdk.RequestPermissionRequest) (PermissionDecision, bool)
CreateTerminal(ctx context.Context, req acpsdk.CreateTerminalRequest) (acpsdk.CreateTerminalResponse, error)
KillTerminal(id string) error
TerminalOutput(id string) (string, error)
WaitForTerminalExit(ctx context.Context, id string) (int, error)
ReleaseTerminal(id string) error
}
ToolHost abstracts ACP file, permission, and terminal operations for a runtime.
func NewLocalToolHost ¶
func NewLocalToolHost( ctx context.Context, root string, mode compozyconfig.PermissionMode, logger *slog.Logger, opts ...LocalRuntimeOption, ) (ToolHost, error)
NewLocalToolHost returns the local daemon-host file, permission, and terminal host.
Source Files
¶
- agent_event.go
- agent_event_resolution.go
- agent_event_tool.go
- agent_process.go
- agent_process_fork.go
- agent_process_ingest.go
- agent_process_prompt.go
- client.go
- client_control.go
- client_notify.go
- client_process.go
- client_prompt.go
- client_protocol.go
- client_steer.go
- client_steer_concurrent.go
- config_option_selection.go
- config_options.go
- control_request.go
- event_broadcast.go
- event_ingest.go
- event_ingest_text.go
- failure.go
- generic_config_negotiation.go
- goal_prompt_meta.go
- handlers.go
- handlers_helpers.go
- handlers_interceptors.go
- handlers_session_state.go
- handlers_session_update.go
- launch_identity.go
- launcher.go
- locked_buffer.go
- negotiation_error.go
- permission.go
- permission_event.go
- permission_helpers.go
- permission_pending.go
- probe.go
- process_child_tasks.go
- process_config_state.go
- process_exit_verification.go
- process_tree.go
- prompt_attachments.go
- prompt_cache.go
- prompt_delivery.go
- prompt_judge_meta.go
- prompt_manifest.go
- prompt_meta.go
- prompt_metadata_error.go
- prompt_runtime.go
- prompt_sections.go
- prompt_stream_terminal.go
- prompt_synthetic_meta.go
- protocol_observations.go
- provider_error_event.go
- provider_failure.go
- provider_failure_summary.go
- rawjson.go
- runtime_configuration.go
- runtime_types.go
- session_config_negotiation.go
- session_inspection.go
- session_model_state.go
- session_routing.go
- speed_config.go
- start.go
- start_accepted.go
- start_process.go
- start_session.go
- steer_capability.go
- terminal.go
- terminal_access.go
- terminal_create.go
- terminal_process.go
- tool_gateway.go
- tool_host.go
- types.go
- usage_validation.go