Documentation
¶
Overview ¶
Package acp provides the Compozy ACP client implementation.
Index ¶
- Constants
- Variables
- func CloneRawMessage(value json.RawMessage) json.RawMessage
- func FailureFromError(err error, fallback store.FailureKind) (*store.SessionFailure, bool)
- func IsLoadSessionResourceMissing(err error) bool
- func NewLocalLauncher(logger *slog.Logger, stopTimeout time.Duration) sandbox.Launcher
- func NewLocalToolHost(ctx context.Context, root string, mode compozyconfig.PermissionMode, ...) (sandbox.ToolHost, error)
- func WrapFailure(kind store.FailureKind, summary string, err error) error
- type AgentEvent
- func (e *AgentEvent) EventIDValue() string
- func (e AgentEvent) HasToolPayload() bool
- func (e *AgentEvent) MessageIDValue() string
- func (e AgentEvent) PromptRuntimeSnapshot() *PromptRuntime
- 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) WithEventID(eventID string) AgentEvent
- func (e AgentEvent) WithMessageID(messageID string) AgentEvent
- func (e AgentEvent) WithPromptRuntime(runtime *PromptRuntime) 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
- type AgentProcess
- func (p *AgentProcess) CapsSnapshot() Caps
- func (p *AgentProcess) Done() <-chan struct{}
- func (p *AgentProcess) ExitStatus() (subprocess.ExitStatus, bool)
- func (p *AgentProcess) HasPendingPermission() bool
- func (p *AgentProcess) HealthState() subprocess.HealthState
- func (p *AgentProcess) RequestPermission(ctx context.Context, req RequestPermissionRequest) (RequestPermissionResponse, error)
- func (p *AgentProcess) ResolvePermission(req ApproveRequest) error
- func (p *AgentProcess) SetTurnSourceProvider(provider func() string)
- func (p *AgentProcess) Stderr() string
- func (p *AgentProcess) ToolHost() sandbox.ToolHost
- func (p *AgentProcess) Wait() error
- type ApproveRequest
- type AvailableCommandSet
- type Caps
- 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) 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) 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) Stop(ctx context.Context, proc *AgentProcess) error
- type FailureError
- type GoalPromptMeta
- type Handle
- type LaunchSpec
- type Launcher
- type LocalRuntimeOption
- type NegotiationError
- type Option
- func WithLauncher(launcher sandbox.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 WithStopTimeout(timeout time.Duration) Option
- func WithToolHost(toolHost sandbox.ToolHost) Option
- type ProbeLookup
- type ProbeOptions
- type ProbeResult
- type ProbeTarget
- type PromptActivityReport
- type PromptActivityReporter
- type PromptJudgeMeta
- type PromptMeta
- type PromptNetworkMeta
- type PromptRequest
- type PromptRuntime
- type PromptStopReason
- type PromptSyntheticMeta
- type PromptSystemMeta
- type ProviderFailureAction
- type ProviderFailureDiagnostic
- type ProviderFailureKind
- type ProviderPreStarter
- type RequestPermissionRequest
- type RequestPermissionResponse
- type RuntimeActivity
- type RuntimeConfig
- type SessionConfigOption
- type SessionConfigOptionKind
- type SessionConfigOptionValue
- type StartOpts
- type SystemPromptDeliveryMode
- 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 ( 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" // PromptTurnSourceNetwork identifies a daemon prompt that originated from an // Compozy network envelope delivery. PromptTurnSourceNetwork = "network" // PromptTurnSourceSynthetic identifies a daemon-owned prompt turn injected by // internal runtime code. PromptTurnSourceSynthetic = "synthetic" )
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 is emitted by Compozy when active prompt activity is stale. EventTypeRuntimeWarning = "runtime_warning" // 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 PermissionRequestIDMetaKey = "request_id"
PermissionRequestIDMetaKey pins the externally addressable permission request ID in ACP metadata.
const (
// PromptJudgeRoleAgent identifies one daemon-owned agent judge prompt.
PromptJudgeRoleAgent = "agent-judge"
)
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 ( // 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") // ErrToolBlockedForNetworkTurn reports that daemon-side network turn policy rejected a tool operation. ErrToolBlockedForNetworkTurn = errors.New("acp: tool blocked for network-originated turn") // 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 ErrInvalidPromptMetadata = errors.New("acp: invalid prompt metadata")
ErrInvalidPromptMetadata identifies metadata that cannot be sent to an ACP agent.
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.
Functions ¶
func CloneRawMessage ¶
func CloneRawMessage(value json.RawMessage) json.RawMessage
CloneRawMessage returns an independent copy of one raw JSON payload.
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 NewLocalLauncher ¶
NewLocalLauncher returns the local daemon-host subprocess launcher.
func NewLocalToolHost ¶
func NewLocalToolHost( ctx context.Context, root string, mode compozyconfig.PermissionMode, logger *slog.Logger, opts ...LocalRuntimeOption, ) (sandbox.ToolHost, error)
NewLocalToolHost returns the local daemon-host file, permission, and terminal host.
func WrapFailure ¶
func WrapFailure(kind store.FailureKind, summary string, err error) error
WrapFailure annotates err with a typed ACP/session failure classification.
Types ¶
type AgentEvent ¶
type AgentEvent struct {
Type string
SessionID string
TurnID string
RequestID 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
Synthetic *PromptSyntheticMeta
Goal *GoalPromptMeta
AvailableCommands *AvailableCommandSet
Usage *TokenUsage
Runtime *RuntimeActivity
Raw json.RawMessage
ToolPrechecked bool
// 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) 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) 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) 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) 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.
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) 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) 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.
func (*AgentProcess) ResolvePermission ¶
func (p *AgentProcess) ResolvePermission(req ApproveRequest) error
ResolvePermission delivers a user decision to a waiting permission request.
func (*AgentProcess) SetTurnSourceProvider ¶
func (p *AgentProcess) SetTurnSourceProvider(provider func() string)
SetTurnSourceProvider configures a daemon-local callback that reports the current turn provenance.
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() sandbox.ToolHost
ToolHost returns the sandbox-owned 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"`
}
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 Caps ¶
type Caps struct {
SupportsLoadSession bool
SupportedModes []string
ConfigOptions []SessionConfigOption
SpeedResolution *speedpkg.Resolution
}
Caps captures the usable capabilities exposed by an ACP agent.
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 the local active prompt or falls back to ACP cooperative cancellation.
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) 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.
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 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 LaunchSpec ¶
type LaunchSpec = sandbox.LaunchSpec
LaunchSpec describes the ACP-capable command to start inside a sandbox.
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 WithLocalProcessRegistry ¶
func WithLocalProcessRegistry(registry *toolruntime.Registry) LocalRuntimeOption
WithLocalProcessRegistry injects the shared tool process registry.
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 WithLauncher ¶
WithLauncher overrides the sandbox 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 for ACP subprocesses.
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 WithStopTimeout ¶
WithStopTimeout overrides how long Stop waits before escalating to SIGKILL.
func WithToolHost ¶
WithToolHost overrides the sandbox tool host used by default for new ACP sessions.
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 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 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"`
Network *PromptNetworkMeta `json:"network,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 PromptNetworkMeta ¶
type PromptNetworkMeta struct {
MessageID string `json:"message_id,omitempty"`
Kind string `json:"kind,omitempty"`
Channel string `json:"channel,omitempty"`
Surface string `json:"surface,omitempty"`
ThreadID string `json:"thread_id,omitempty"`
DirectID string `json:"direct_id,omitempty"`
From string `json:"from,omitempty"`
To string `json:"to,omitempty"`
Mentions []string `json:"mentions,omitempty"`
WorkID string `json:"work_id,omitempty"`
ReplyTo string `json:"reply_to,omitempty"`
TraceID string `json:"trace_id,omitempty"`
CausationID string `json:"causation_id,omitempty"`
Trust string `json:"trust,omitempty"`
DeliveryMode string `json:"delivery_mode,omitempty"`
PromptSizeBytes int64 `json:"prompt_size_bytes,omitempty"`
EstimatedPromptTokens int64 `json:"estimated_prompt_tokens,omitempty"`
}
PromptNetworkMeta captures stable Compozy network envelope correlation fields.
func (PromptNetworkMeta) IsZero ¶
func (m PromptNetworkMeta) IsZero() bool
IsZero reports whether the network metadata carries any fields.
func (PromptNetworkMeta) Normalize ¶
func (m PromptNetworkMeta) Normalize() PromptNetworkMeta
Normalize returns a trimmed copy of the network metadata.
type PromptRequest ¶
type PromptRequest struct {
TurnID string
Message string
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"`
}
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 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"`
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 ProviderFailureAction ¶
type ProviderFailureAction string
ProviderFailureAction is the stable next action paired with a provider failure classification.
const ( ProviderFailureActionInstallCLI ProviderFailureAction = "install_cli" ProviderFailureActionLogin ProviderFailureAction = "login" ProviderFailureActionChangeModel ProviderFailureAction = "change_model" ProviderFailureActionRequestPermission ProviderFailureAction = "request_permission" ProviderFailureActionWait ProviderFailureAction = "wait" ProviderFailureActionRetry ProviderFailureAction = "retry" ProviderFailureActionNoRetry ProviderFailureAction = "no_retry" )
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 (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 RuntimeConfig ¶
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
Current string
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.
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 SessionConfigOptionValue ¶
SessionConfigOptionValue captures one selectable value for an ACP config option.
type StartOpts ¶
type StartOpts struct {
AgentName string
Command string
Cwd string
AdditionalDirs []string
Env []string
MCPServers []compozyconfig.MCPServer
Permissions compozyconfig.PermissionMode
SystemPrompt string
SystemPromptDelivery SystemPromptDeliveryMode
PreferredModel string
ReasoningEffort string
Speed speedpkg.Speed
ResumeSessionID string
Launcher sandbox.Launcher
ToolHost sandbox.ToolHost
ToolGateway ToolExecutionGateway
ProviderName string
ProviderConfig *compozyconfig.ProviderConfig
ProviderAuthEnv *authproviders.ProbeEnv
ActivateMCPServers func(context.Context) error
// contains filtered or unexported fields
}
StartOpts defines how to launch and initialize an ACP agent process.
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 TokenUsage ¶
type TokenUsage struct {
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.
Source Files
¶
- agent_event.go
- agent_event_tool.go
- agent_process.go
- agent_process_prompt.go
- client.go
- client_control.go
- client_process.go
- client_prompt.go
- client_protocol.go
- config_options.go
- failure.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_tree.go
- prompt_cache.go
- prompt_judge_meta.go
- prompt_meta.go
- prompt_metadata_error.go
- prompt_runtime.go
- prompt_stream_terminal.go
- prompt_synthetic_meta.go
- protocol_observations.go
- provider_failure.go
- rawjson.go
- runtime_configuration.go
- session_config_negotiation.go
- speed_config.go
- start.go
- start_process.go
- start_session.go
- terminal.go
- terminal_access.go
- terminal_create.go
- terminal_process.go
- tool_gateway.go
- tool_host.go
- types.go