Documentation
¶
Overview ¶
Package acp provides the Compozy ACP client implementation.
Index ¶
- Constants
- Variables
- func AcceptedSessionID(err error) (string, bool)
- func Authenticate(ctx context.Context, req AuthenticationRequest) error
- func ClassifyProbeError(providerName string, err error) authproviders.Classification
- func CloneRawMessage(value json.RawMessage) json.RawMessage
- func CollectPromptSections(ctx context.Context) (context.Context, func() []PromptSection)
- func CurrentSpeed(options []SessionConfigOption) speedpkg.Speed
- func DaemonMatchedEnv(base []string) []string
- func EstimateTokens(byteLen int64) int64
- func FailureFromError(err error, fallback store.FailureKind) (*store.SessionFailure, bool)
- func IsAuthRequiredError(err error) bool
- func IsConfigurationRejection(err error) bool
- func IsLoadSessionProviderMismatch(err error) bool
- func IsLoadSessionResourceMissing(err error) bool
- func LoadSessionRequiresFreshThread(err error) bool
- func NPXStartupDiagnostic(failure *store.SessionFailure) (contract.DiagnosticItem, bool)
- func ProbeAuthentication(ctx context.Context, req SessionInspectionRequest) error
- func RegisterPromptSection(ctx context.Context, section PromptSection)
- func ReplaceProviderFailureDiagnostic(summary string, d ProviderFailureDiagnostic) string
- func ResolveCurrentSpeed(requested speedpkg.Speed, options []SessionConfigOption) *speedpkg.Resolution
- func ResolveSteerCapability(provider string, announced []string, override config.SteerCapability) config.SteerCapability
- func SupportsSpeed(requested speedpkg.Speed, options []SessionConfigOption) bool
- func TracedMethods() []string
- func ValidateACPModePermissions(provider string, options []SessionConfigOptionSelection, ...) error
- func ValidateModelConfigValue(options []SessionConfigOption, modelID string) error
- func ValidatePromptOriginInReplyTo(value 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) ExpiresAtValue() *time.Time
- func (e AgentEvent) GoalPromptMeta() *GoalPromptMeta
- func (e AgentEvent) HasToolPayload() bool
- func (e AgentEvent) Mentions() []mention.Mention
- func (e *AgentEvent) MessageIDValue() string
- func (e AgentEvent) NativeTask() *NativeTaskObservation
- func (e AgentEvent) ParentToolCallID() string
- func (e AgentEvent) PromptOrigin() *PromptOriginMeta
- func (e AgentEvent) PromptRuntimeSnapshot() *PromptRuntime
- func (e AgentEvent) ProviderToolAsync() bool
- func (e AgentEvent) ProviderToolName() string
- func (e AgentEvent) RequestIDValue() string
- func (e AgentEvent) ResolvedByValue() string
- func (e AgentEvent) SessionMessageCard() json.RawMessage
- func (e AgentEvent) SkillInvocations() []commandpkg.Invocation
- func (e AgentEvent) SubagentCard() json.RawMessage
- 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) ToolResultUpdate() bool
- func (e AgentEvent) ToolStatus() string
- 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) WithExpiresAt(expiresAt time.Time) AgentEvent
- func (e AgentEvent) WithGoalPromptMeta(goal *GoalPromptMeta) AgentEvent
- func (e AgentEvent) WithMentions(mentions []mention.Mention) AgentEvent
- func (e AgentEvent) WithMessageID(messageID string) AgentEvent
- func (e AgentEvent) WithNativeTask(observation *NativeTaskObservation) AgentEvent
- func (e AgentEvent) WithPromptOrigin(origin *PromptOriginMeta) AgentEvent
- func (e AgentEvent) WithPromptRuntime(runtime *PromptRuntime) AgentEvent
- func (e AgentEvent) WithProviderToolAsync() AgentEvent
- func (e AgentEvent) WithProviderToolMetadata(parentToolCallID, providerToolName, status string) AgentEvent
- func (e AgentEvent) WithRequestID(requestID string) AgentEvent
- func (e AgentEvent) WithResolvedBy(resolvedBy string) AgentEvent
- func (e AgentEvent) WithSessionMessageCard(card json.RawMessage) AgentEvent
- func (e AgentEvent) WithSkillInvocations(invocations []commandpkg.Invocation) AgentEvent
- func (e AgentEvent) WithSubagentCard(card json.RawMessage) 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
- func (e AgentEvent) WithToolResultUpdate() 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) ReplacePendingStartupPrompt(prompt string, manifest StartupManifest) bool
- 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 AuthMethodUnavailableError
- type AuthMethodUnavailableReason
- type AuthenticationRequest
- type AvailableCommandSet
- type BroadcastStats
- type Caps
- type CommandResult
- type CommandRuntime
- type CommandSpec
- type CompactionObservation
- type DeliveredMentionBlock
- type DeliveredMentions
- 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) StopBudget() time.Duration
- func (d *Driver) VerifyExit(proc *AgentProcess) (bool, error)
- type ElicitationAsker
- 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 NativeTaskKind
- type NativeTaskObservation
- type NativeTaskUsage
- type NegotiationError
- type Option
- func WithAgentNiceness(niceness int) 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 WithPermissionWaitResolver(resolver PermissionWaitResolver) 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 PermissionDenials
- type PermissionOperation
- type PermissionWaitResolver
- type ProbeLookup
- type ProbeOptions
- type ProbeResult
- type ProbeTarget
- type ProcessSignal
- type PromptActivityReport
- type PromptActivityReporter
- type PromptAttachment
- type PromptJudgeMeta
- type PromptMentionDelivery
- type PromptMeta
- type PromptOriginMeta
- type PromptRequest
- type PromptResourceLink
- 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 RuntimeLiveApplication
- 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
- func CloneSessionConfigOptionSelections(selections []SessionConfigOptionSelection) []SessionConfigOptionSelection
- func ConfirmedSessionConfigOptionSelections(selections []SessionConfigOptionSelection, options []SessionConfigOption) []SessionConfigOptionSelection
- func NormalizeSessionConfigOptionSelections(selections []SessionConfigOptionSelection) ([]SessionConfigOptionSelection, error)
- type SessionConfigOptionValue
- type SessionInspectionRequest
- type SessionModelInspection
- type StartOpts
- type StartPermissionPolicy
- 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 ( NativeTaskStatusPending = "pending" NativeTaskStatusRunning = "running" NativeTaskStatusPaused = "paused" NativeTaskStatusCompleted = "completed" NativeTaskStatusFailed = "failed" NativeTaskStatusKilled = "killed" NativeTaskStatusStopped = "stopped" )
Provider task statuses carried by NativeTaskObservation.Status. SDK patches report killed; settled-task notifications report stopped.
const ( NativeTaskSummaryMaxBytes = 1 << 20 NativeTaskTextMaxBytes = 64 << 10 NativeTaskNameMaxBytes = 256 )
Field bounds applied to provider task payloads before admission. The summary bound is a byte safety cap above the default subagent result allowance; the configured result limit decides the delivered result, and a cut here is recorded as SummaryTruncated so result_truncated stays truthful.
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 ( DeliveredMentionBlockSessionReferences = "session_references" DeliveredMentionBlockResourceLink = "resource_link" )
Delivered mention block kinds.
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 EventTypeCompaction = "compaction"
const EventTypeNativeTask = "native_task"
EventTypeNativeTask is one provider-native task lifecycle observation for a Claude Agent/Task subagent. It never creates a subagent row or a tool result: session ingest joins it to the native row of its originating Agent/Task call.
const EventTypePromptDelivery = "prompt_delivery"
const ExecutionPolicyTriage = "triage"
const MaxPromptOriginInReplyToLength = 200
MaxPromptOriginInReplyToLength bounds the message id an explicit reply may reference.
const MaxSessionMessageHops = 8
const NativeTaskSourceClaudeSDK = "claude_sdk"
NativeTaskSourceClaudeSDK marks observations decoded from claude-agent-acp's filtered raw SDK task messages (`_claude/sdkMessage`).
const (
// PromptJudgeRoleAgent identifies one daemon-owned agent judge prompt.
PromptJudgeRoleAgent = "agent-judge"
)
const PromptOriginKindSession = "session"
const PromptSyntheticKindMonitor = "monitor"
PromptSyntheticKindMonitor attributes daemon wakes emitted by fired session monitors.
const PromptSyntheticKindSessionReply = "session_reply"
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 ( // elicitation for this session, so the agent receives an explicit decline. ErrElicitationUnavailable = errors.New("acp: operator elicitation is unavailable") // ErrElicitationUnsupported reports a form this client cannot render. ErrElicitationUnsupported = errors.New("acp: elicitation form is not representable") )
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") ErrPendingPermissionExpired = fmt.Errorf("%w: permission request expired", ErrPendingPermissionNotFound) // 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 ErrACPAuthRequired = errors.New("acp: provider authentication required")
ErrACPAuthRequired reports that a disposable ACP session probe was refused with an authentication-required peer error.
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 ErrPermissionExpired = errors.New("acp: approval expired; ask the operator to prompt the session before retrying")
ErrPermissionExpired distinguishes an unanswered approval from an operator rejection.
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")
var ErrTriageUnsupported = errors.New("triage_unsupported")
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 Authenticate ¶
func Authenticate(ctx context.Context, req AuthenticationRequest) error
Authenticate performs one disposable explicit login: it probes readiness with a promptless session/new, authenticates the exact configured advertised agent method only when that probe reports auth-required, then verifies readiness once. A refused post-login session stays a classified failure.
func ClassifyProbeError ¶
func ClassifyProbeError(providerName string, err error) authproviders.Classification
ClassifyProbeError maps one ProbeAuthentication failure onto the canonical provider-auth taxonomy shared with native-command probes. A nil error is an authenticated readiness proof; it never reports account identity.
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 CurrentSpeed ¶
func CurrentSpeed(options []SessionConfigOption) speedpkg.Speed
CurrentSpeed returns the speed confirmed by the latest unambiguous ACP option.
func DaemonMatchedEnv ¶
DaemonMatchedEnv binds subprocess CLI discovery to the executable running the daemon. Internal handoff variables never reach the subprocess, whatever layer assembled base.
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 IsAuthRequiredError ¶
IsAuthRequiredError reports whether err carries an ACP authentication-required peer refusal, including through the driver's wrapped control-request chain.
func IsConfigurationRejection ¶
IsConfigurationRejection reports whether err is a provider rejection of a requested model, reasoning effort, or speed: an unadvertised value, a missing or read-only option, a provider invalid-params refusal, or a response that did not apply the value. Deadlines, cancellation, and transport failures wrapped in a NegotiationError are not configuration rejections.
func IsLoadSessionProviderMismatch ¶
IsLoadSessionProviderMismatch reports whether session/load was refused because the stored provider thread belongs to a different provider account or backend than the one the agent process runs under now. codex-acp answers this way after `model_provider` changes: "This chat uses openai, but your current provider is <name>. Switch to openai to continue." The refusal is permanent for the current configuration: the same thread never loads again, so a retry only repeats the failure.
func IsLoadSessionResourceMissing ¶
IsLoadSessionResourceMissing reports whether a resume failed because the upstream ACP implementation no longer knows the referenced session id.
func LoadSessionRequiresFreshThread ¶
LoadSessionRequiresFreshThread reports the classified session/load failures after which the stored provider session id can never be loaded again: the agent has no session/load, the provider no longer knows the id, or the id belongs to another provider account or backend. Only these failures may clear the stored id and fall back to a fresh provider thread with replayed context; every other load failure keeps the id and stays retryable.
func NPXStartupDiagnostic ¶
func NPXStartupDiagnostic(failure *store.SessionFailure) (contract.DiagnosticItem, bool)
NPXStartupDiagnostic recovers preparation guidance from the persisted failure boundary.
func ProbeAuthentication ¶
func ProbeAuthentication(ctx context.Context, req SessionInspectionRequest) error
ProbeAuthentication verifies readiness with one promptless disposable session/new. It never sends authenticate, prompts, or tools; MCP servers stay an empty list so strict agents accept the probe.
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 ResolveCurrentSpeed ¶
func ResolveCurrentSpeed(requested speedpkg.Speed, options []SessionConfigOption) *speedpkg.Resolution
ResolveCurrentSpeed compares a normalized request with the latest provider observation.
func ResolveSteerCapability ¶
func ResolveSteerCapability( provider string, announced []string, override config.SteerCapability, ) config.SteerCapability
func SupportsSpeed ¶
func SupportsSpeed(requested speedpkg.Speed, options []SessionConfigOption) bool
SupportsSpeed reports whether an unambiguous advertised option accepts the requested speed.
func TracedMethods ¶
func TracedMethods() []string
TracedMethods are the ACP methods the driver traces as "acp <method>" client spans; the daemon registers them with the telemetry sanitizer.
func ValidateACPModePermissions ¶
func ValidateACPModePermissions( provider string, 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 ValidatePromptOriginInReplyTo ¶
ValidatePromptOriginInReplyTo accepts an empty value or one bounded message id without whitespace.
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
Usage *TokenUsage
Compaction *CompactionObservation
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) ExpiresAtValue ¶
func (e AgentEvent) ExpiresAtValue() *time.Time
ExpiresAtValue returns an isolated interaction expiry.
func (AgentEvent) GoalPromptMeta ¶
func (e AgentEvent) GoalPromptMeta() *GoalPromptMeta
func (AgentEvent) HasToolPayload ¶
func (e AgentEvent) HasToolPayload() bool
HasToolPayload reports whether typed tool metadata is present on the event.
func (AgentEvent) Mentions ¶
func (e AgentEvent) Mentions() []mention.Mention
Mentions returns an isolated copy of verified mention metadata.
func (*AgentEvent) MessageIDValue ¶
func (e *AgentEvent) MessageIDValue() string
MessageIDValue returns the normalized identity for an authored user message.
func (AgentEvent) NativeTask ¶
func (e AgentEvent) NativeTask() *NativeTaskObservation
NativeTask returns an isolated copy of the event's native task observation.
func (AgentEvent) ParentToolCallID ¶
func (e AgentEvent) ParentToolCallID() string
ParentToolCallID identifies the provider tool whose subagent produced this event.
func (AgentEvent) PromptOrigin ¶
func (e AgentEvent) PromptOrigin() *PromptOriginMeta
func (AgentEvent) PromptRuntimeSnapshot ¶
func (e AgentEvent) PromptRuntimeSnapshot() *PromptRuntime
PromptRuntimeSnapshot returns an isolated effective runtime snapshot.
func (AgentEvent) ProviderToolAsync ¶
func (e AgentEvent) ProviderToolAsync() bool
ProviderToolAsync reports whether the provider launched the tool's work in the background.
func (AgentEvent) ProviderToolName ¶
func (e AgentEvent) ProviderToolName() string
ProviderToolName returns the provider's tool identity, independent of its title.
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) SessionMessageCard ¶
func (e AgentEvent) SessionMessageCard() json.RawMessage
func (AgentEvent) SkillInvocations ¶
func (e AgentEvent) SkillInvocations() []commandpkg.Invocation
SkillInvocations returns an isolated copy of admitted slash metadata.
func (AgentEvent) SubagentCard ¶
func (e AgentEvent) SubagentCard() json.RawMessage
SubagentCard returns the projected subagent card, when the event has one.
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) ToolResultUpdate ¶
func (e AgentEvent) ToolResultUpdate() bool
ToolResultUpdate reports whether this event only enriches an earlier completion.
func (AgentEvent) ToolStatus ¶
func (e AgentEvent) ToolStatus() string
ToolStatus returns the provider's observed tool lifecycle status.
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) WithExpiresAt ¶
func (e AgentEvent) WithExpiresAt(expiresAt time.Time) AgentEvent
WithExpiresAt returns an event carrying an interaction expiry.
func (AgentEvent) WithGoalPromptMeta ¶
func (e AgentEvent) WithGoalPromptMeta(goal *GoalPromptMeta) AgentEvent
func (AgentEvent) WithMentions ¶
func (e AgentEvent) WithMentions(mentions []mention.Mention) AgentEvent
WithMentions returns an event carrying isolated verified mention metadata.
func (AgentEvent) WithMessageID ¶
func (e AgentEvent) WithMessageID(messageID string) AgentEvent
WithMessageID returns an event carrying the normalized authored-message identity.
func (AgentEvent) WithNativeTask ¶
func (e AgentEvent) WithNativeTask(observation *NativeTaskObservation) AgentEvent
WithNativeTask returns an event carrying an isolated native task observation.
func (AgentEvent) WithPromptOrigin ¶
func (e AgentEvent) WithPromptOrigin(origin *PromptOriginMeta) AgentEvent
func (AgentEvent) WithPromptRuntime ¶
func (e AgentEvent) WithPromptRuntime(runtime *PromptRuntime) AgentEvent
WithPromptRuntime returns an event carrying an isolated effective runtime snapshot.
func (AgentEvent) WithProviderToolAsync ¶
func (e AgentEvent) WithProviderToolAsync() AgentEvent
WithProviderToolAsync marks a tool result as the provider's receipt for work it launched in the background, not that work's outcome.
func (AgentEvent) WithProviderToolMetadata ¶
func (e AgentEvent) WithProviderToolMetadata(parentToolCallID, providerToolName, status string) AgentEvent
WithProviderToolMetadata preserves provider attribution independently of tool display names.
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) WithSessionMessageCard ¶
func (e AgentEvent) WithSessionMessageCard(card json.RawMessage) AgentEvent
func (AgentEvent) WithSkillInvocations ¶
func (e AgentEvent) WithSkillInvocations(invocations []commandpkg.Invocation) AgentEvent
WithSkillInvocations returns an event carrying isolated admitted slash metadata.
func (AgentEvent) WithSubagentCard ¶
func (e AgentEvent) WithSubagentCard(card json.RawMessage) AgentEvent
WithSubagentCard carries the subagent card (`data-compozy-subagent` payload) the transcript projection derives from this event's persisted form, for live surfaces that only see the decoded event (the prompt stream).
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.
func (AgentEvent) WithToolResultUpdate ¶
func (e AgentEvent) WithToolResultUpdate() AgentEvent
WithToolResultUpdate marks additional output after completion was already observed.
type AgentProcess ¶
type AgentProcess struct {
PID int
AgentName string
Command string
Args []string
Cwd string
SessionID string
StartedAt time.Time
KernelToken string
// 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) ReplacePendingStartupPrompt ¶
func (p *AgentProcess) ReplacePendingStartupPrompt(prompt string, manifest StartupManifest) bool
ReplacePendingStartupPrompt swaps startup guidance that has not reached the provider: it applies only to first-turn-prefix delivery before the first prompt is sent.
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 AuthMethodUnavailableError ¶
type AuthMethodUnavailableError struct {
}
AuthMethodUnavailableError reports that the exact configured ACP method is not available as an agent method. No authenticate request was sent.
func (*AuthMethodUnavailableError) Error ¶
func (e *AuthMethodUnavailableError) Error() string
type AuthMethodUnavailableReason ¶
type AuthMethodUnavailableReason string
AuthMethodUnavailableReason identifies why a configured ACP method cannot be used for explicit login.
const ( // the configured method ID. AuthMethodUnavailableAbsent AuthMethodUnavailableReason = "absent" // terminal method, which disposable login never executes. AuthMethodUnavailableTerminal AuthMethodUnavailableReason = "terminal" // type disposable login does not speak. Unknown types fail closed instead of // becoming agent methods. AuthMethodUnavailableUnknown AuthMethodUnavailableReason = "unknown" )
type AuthenticationRequest ¶
type AuthenticationRequest struct {
SessionInspectionRequest
MethodID string
InteractiveOutput io.Writer // local login only; never a persisted logger
}
AuthenticationRequest describes one disposable explicit-login attempt. The command, environment, and home arrive exactly as the caller resolved them; InteractiveOutput is the only sink for live login progress.
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 {
PermissionModeDegraded bool
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 CompactionObservation ¶
type DeliveredMentionBlock ¶
type DeliveredMentionBlock struct {
Kind string `json:"kind"`
Name string `json:"name,omitempty"`
Form string `json:"form,omitempty"`
SessionIDs []string `json:"session_ids,omitempty"`
Bytes int64 `json:"bytes,omitzero"`
}
DeliveredMentionBlock is one delivered mention block, in prompt order. It never carries an absolute path: links record only their working-directory-relative name, and the references block records its form, session ids, and size.
type DeliveredMentions ¶
type DeliveredMentions struct {
Links int `json:"links"`
Sessions int `json:"sessions"`
ReferencesForm string `json:"references_form,omitempty"`
DroppedOverCap int `json:"dropped_over_cap"`
DroppedAtDispatch int `json:"dropped_at_dispatch"`
Blocks []DeliveredMentionBlock `json:"blocks,omitempty"`
}
DeliveredMentions records the mention blocks sent with one prompt.
type DeliveredSpan ¶
type DeliveredSpan struct {
Key string `json:"key"`
Kind string `json:"kind"`
Bytes int64 `json:"bytes"`
Tokens *int64 `json:"tokens,omitzero"`
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"`
// Mentions records the mention blocks of this prompt; nil when it carried none.
Mentions *DeliveredMentions `json:"mentions,omitzero"`
}
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, attachments []PromptAttachment, ) (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) StopBudget ¶
StopBudget is how long Stop runs its stop and drain protocol before forcing the exit.
func (*Driver) VerifyExit ¶
func (d *Driver) VerifyExit(proc *AgentProcess) (bool, error)
VerifyExit distinguishes confirmed process exit from a failed status lookup.
type ElicitationAsker ¶
type ElicitationAsker func(ctx context.Context, question toolspkg.ClarifyQuestion) (toolspkg.ClarifyAnswer, error)
ElicitationAsker delivers one provider question to the operator. It blocks until the operator answers, the context ends, or the session cannot answer.
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,omitzero"`
Height int `json:"height,omitzero"`
}
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 inherits when nil; explicit empty excludes parent entries except OS-required variables.
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 NativeTaskKind ¶
type NativeTaskKind string
NativeTaskKind is what one observation reports about a provider task.
const ( // NativeTaskKindSpawn reports a started task run. NativeTaskKindSpawn NativeTaskKind = "spawn" // NativeTaskKindProgress reports a progress line or usage for a running task. NativeTaskKindProgress NativeTaskKind = "progress" // NativeTaskKindState reports a status patch or a settled-task notification. NativeTaskKindState NativeTaskKind = "state" )
type NativeTaskObservation ¶
type NativeTaskObservation struct {
Source string
Kind NativeTaskKind
TaskID string
RunID string
ToolCallID string
// Status is the provider status, empty when the observation carries none.
Status string
// Summary is nil when absent, distinguishing it from an explicit empty summary.
Summary *string
// SummaryTruncated records that Summary was cut before storage.
SummaryTruncated bool
Error string
Description string
LastToolName string
Usage *NativeTaskUsage
// Background is nil when the observation says nothing about backgrounding.
Background *bool
EventUUID string
}
NativeTaskObservation is the typed, immutable payload of EventTypeNativeTask. The owning AgentEvent carries the session and turn; ToolCallID is the Agent/Task tool call that launched the task, never a Compozy subagent id.
func (*NativeTaskObservation) Clone ¶
func (o *NativeTaskObservation) Clone() *NativeTaskObservation
Clone returns an isolated copy of the observation.
func (*NativeTaskObservation) Terminal ¶
func (o *NativeTaskObservation) Terminal() bool
Terminal reports whether the observation settles its task run.
type NativeTaskUsage ¶
NativeTaskUsage is the provider's running usage for one task. It is informational: the parent's billed usage already includes it.
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 WithAgentNiceness ¶
WithAgentNiceness lowers the CPU priority of locally launched agent process groups; zero keeps the daemon's priority. It applies to the default local launcher.
func WithControlTimeout ¶
WithControlTimeout bounds each non-prompt ACP request; nonpositive values use method-specific defaults.
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 WithPermissionWaitResolver ¶
func WithPermissionWaitResolver(resolver PermissionWaitResolver) Option
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" )
func (PermissionDecision) TelemetryOutcome ¶
func (d PermissionDecision) TelemetryOutcome() string
TelemetryOutcome maps a decision to its telemetry outcome: allow is approved, reject is denied, and anything else, such as a cancellation or an unknown value, is OutcomeCancelled.
type PermissionDenials ¶
type PermissionDenials struct {
// contains filtered or unexported fields
}
PermissionDenials outlives an ACP process and is cleared by the next human prompt.
func (*PermissionDenials) Clear ¶
func (d *PermissionDenials) Clear()
func (*PermissionDenials) Contains ¶
func (d *PermissionDenials) Contains(key string) bool
func (*PermissionDenials) Epoch ¶
func (d *PermissionDenials) Epoch() uint64
func (*PermissionDenials) Record ¶
func (d *PermissionDenials) Record(key string, epoch uint64)
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 PermissionWaitResolver ¶
PermissionWaitResolver resolves the current wait using the daemon session identity.
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 PromptMentionDelivery ¶
type PromptMentionDelivery struct {
Sessions int // referenced sessions rendered in the references block
SessionIDs []string // ids of the rendered sessions, in block order
ReferencesForm string // reference | inline | unavailable; empty without sessions
DroppedOverCap int // tokens left as text because a per-prompt cap was reached
DroppedAtDispatch int // admitted mentions dropped by the dispatch re-check
}
PromptMentionDelivery carries the session-layer mention counts recorded in the delivery manifest. Link counts are derived from PromptRequest.MentionLinks.
type PromptMeta ¶
type PromptMeta struct {
Origin *PromptOriginMeta `json:"origin,omitempty"`
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 PromptOriginMeta ¶
type PromptOriginMeta struct {
Kind string `json:"kind"`
SessionID string `json:"session_id"`
WorkspaceID string `json:"workspace_id"`
AgentName string `json:"agent_name,omitempty"`
TitleAtSend string `json:"title_at_send,omitempty"`
Hop int `json:"hop"`
NotifyOnComplete bool `json:"notify_on_complete,omitempty"`
ReplyWatchID string `json:"reply_watch_id,omitempty"`
// InReplyTo is the message id this send answers; it threads the reply for the receiver.
InReplyTo string `json:"in_reply_to,omitempty"`
}
func ClonePromptOriginMeta ¶
func ClonePromptOriginMeta(m *PromptOriginMeta) *PromptOriginMeta
func (PromptOriginMeta) IsZero ¶
func (m PromptOriginMeta) IsZero() bool
func (PromptOriginMeta) Normalize ¶
func (m PromptOriginMeta) Normalize() PromptOriginMeta
func (PromptOriginMeta) Validate ¶
func (m PromptOriginMeta) Validate() error
type PromptRequest ¶
type PromptRequest struct {
TurnID string
RunID string
Generation int64
Model string // session model; labels compozy.session.ttft only
Message string
Maintenance bool
AgentCommand bool
Sections []PromptSection
Attachments []PromptAttachment
SessionReferences string // rendered session-references block; empty when none
MentionLinks []PromptResourceLink // distinct file/folder targets, first-mention order
MentionDelivery PromptMentionDelivery
Meta PromptMeta
ActivityReporter PromptActivityReporter
ActivityHeartbeatInterval time.Duration
}
PromptRequest describes one prompt turn sent to an active ACP session.
func (PromptRequest) BypassesContext ¶
func (r PromptRequest) BypassesContext() bool
BypassesContext preserves native commands without advancing ordinary prompt context delivery.
func (PromptRequest) Validate ¶
func (r PromptRequest) Validate() error
Validate ensures the prompt request can be sent to the agent.
type PromptResourceLink ¶
type PromptResourceLink struct {
Name string // path relative to the session working directory; folders end in "/"
URI string // file:// + percent-encoded absolute path; folders end in "/"
}
PromptResourceLink is one verified file or folder mention delivered as an ACP resource_link block. No content is read or embedded.
func NewPromptResourceLink ¶
func NewPromptResourceLink(relPath, absPath string, folder bool) PromptResourceLink
NewPromptResourceLink builds the resource link for a verified path mention. relPath is relative to the working directory and absPath is its absolute location; folder links end both fields in "/".
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
// OperatorAuthored keeps a leading section outside the attribution header of a
// message sent by another agent, so operator text is never presented as the sender's.
OperatorAuthored bool
}
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 {
Hop int `json:"hop,omitzero"`
ChildWorkspaceID string `json:"child_workspace_id,omitempty"`
ReplyTruncated bool `json:"reply_truncated,omitzero"`
Kind string `json:"kind,omitempty"`
SubagentIDs []string `json:"subagent_ids,omitempty"`
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,omitzero"`
IterationMax int `json:"iteration_max,omitzero"`
IdleSeconds int64 `json:"idle_seconds,omitzero"`
ElapsedSeconds int64 `json:"elapsed_seconds,omitzero"`
ElapsedMS int64 `json:"elapsed_ms,omitzero"`
}
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 RuntimeLiveApplication ¶
type RuntimeLiveApplication string
RuntimeLiveApplication identifies when a provider honors a session_config change sent while its process is live.
const ( // RuntimeLiveApplyNextStep means the running turn uses the change from the agent's next model step. RuntimeLiveApplyNextStep RuntimeLiveApplication = "next_step" // RuntimeLiveApplyNextTurn means the provider stores the change and honors it from its next turn. RuntimeLiveApplyNextTurn RuntimeLiveApplication = "next_turn" )
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 ConfirmedSessionConfigOptionSelections ¶
func ConfirmedSessionConfigOptionSelections( selections []SessionConfigOptionSelection, options []SessionConfigOption, ) []SessionConfigOptionSelection
ConfirmedSessionConfigOptionSelections returns only selections confirmed by unique provider options.
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 ¶
type SessionInspectionRequest struct {
AgentName string
Command string
Cwd string
Env []string
// TelemetryProvider labels the inspection's acp.process.spawn span without setting a provider name, which would
// also run the provider pre-start.
TelemetryProvider string
}
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 {
PermissionPolicy *StartPermissionPolicy
AgentName string
CompozySessionID string
WorkspaceID string
ProfileID string
RuntimeGeneration int64
Command string
Cwd string
AdditionalDirs []string
// Env inherits when nil; explicit empty excludes parent entries except OS-required variables.
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
PermissionEventHandler func(AgentEvent, bool)
ActivateMCPServers func(context.Context) error
FinalizeStartup func(context.Context) (string, StartupManifest, error)
CheckInTools bool
Inspection bool
// InputOnly marks a daemon-owned child that only transforms its prompt. The
// Claude Agent Bridge then skips built-in tools, user MCP servers, plugins,
// skills, hooks, and instruction files; other providers ignore it. Tool and
// hosted-MCP denial come from the verdict-only runtime mode, not this flag.
InputOnly bool
// LeanEnvironment excludes unrelated Claude MCP servers, connectors and auto-memory.
LeanEnvironment bool
// IsolateProviderMCP excludes the operator's own Claude MCP servers and claude.ai
// connectors, so the session sees only the servers CompozyOS passes and governs.
// It keeps auto-memory, which LeanEnvironment also turns off.
IsolateProviderMCP bool
// ShellWaitGuard marks a session that can call compozy__terminal_exec and
// compozy__monitor_create, so a provider hook may refuse a foreground shell
// wait and redirect it. It stays false when policy withholds either tool.
ShellWaitGuard bool
// ForwardTraceParent hands the provider the acp.process.spawn span's TRACEPARENT; the caller sets it when
// observability.otel.forward_to_providers forwards OTLP export variables to this provider.
ForwardTraceParent bool
// contains filtered or unexported fields
}
StartOpts defines how to launch and initialize an ACP agent process.
func (StartOpts) ExecutionPolicyValue ¶
func (StartOpts) PermissionRulesValue ¶
func (o StartOpts) PermissionRulesValue() []compozyconfig.PermissionRule
func (*StartOpts) SetExecutionPolicy ¶
type StartPermissionPolicy ¶
type StartPermissionPolicy struct {
ExecutionPolicy string
Rules []compozyconfig.PermissionRule
Denials *PermissionDenials
// ElicitationAsker renders provider questions to the same session operator
// that answers this policy's approvals. Nil declines provider questions.
ElicitationAsker ElicitationAsker
}
StartPermissionPolicy binds the session-owned approval policy to a process launch.
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. An empty span list stays an empty list so a delivery with no sections (a literal maintenance command) still serializes "spans" as [].
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
// ReportedCostAmount retains the adapter counter after CostAmount is normalized per turn.
ReportedCostAmount *float64 `json:",omitzero"`
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
// Execute marks a permission request for a shell command, whose title
// differs per provider and may never read Bash.
Execute bool
}
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_provider.go
- agent_event_resolution.go
- agent_event_tool.go
- agent_process.go
- agent_process_fork.go
- agent_process_ingest.go
- agent_process_prompt.go
- authentication.go
- classify.go
- claude_session_meta.go
- claude_task_updates.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
- compaction.go
- config_option_selection.go
- config_options.go
- control_request.go
- elicitation.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_discriminator.go
- handlers_session_state.go
- handlers_session_update.go
- launch_identity.go
- launcher.go
- locked_buffer.go
- native_task.go
- negotiation_error.go
- npx_prepare.go
- permission.go
- permission_denials.go
- permission_event.go
- permission_helpers.go
- permission_hosted.go
- permission_pending.go
- permission_rules.go
- permission_wait.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_mentions.go
- prompt_meta.go
- prompt_metadata_error.go
- prompt_origin_meta.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_mcp.go
- session_model_state.go
- session_routing.go
- speed_config.go
- start.go
- start_accepted.go
- start_permission_policy.go
- start_process.go
- start_session.go
- steer_capability.go
- telemetry.go
- terminal.go
- terminal_access.go
- terminal_create.go
- terminal_process.go
- tool_gateway.go
- tool_host.go
- triage.go
- types.go
- usage_validation.go