acp

package
v0.3.0-beta.8 Latest Latest
Warning

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

Go to latest
Published: Aug 10, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package acp provides the Compozy ACP client implementation.

Index

Constants

View Source
const (
	GoalPromptKindWork         = "goal-work"
	GoalPromptKindContinuation = "goal-continuation"
	GoalPromptKindCompaction   = "goal-compaction"
)
View Source
const (
	NegotiationCodeModelUnavailable           = diagnosticcontract.CodeModelUnavailable
	NegotiationCodeReasoningOptionMissing     = diagnosticcontract.CodeReasoningOptionMissing
	NegotiationCodeReasoningEffortUnsupported = diagnosticcontract.CodeReasoningEffortUnsupported
	NegotiationCodeSpeedRejected              = diagnosticcontract.CodeSpeedRejected
)
View Source
const (
	ProbeStatusOK       = "ok"
	ProbeStatusMissing  = "missing"
	ProbeStatusInvalid  = "invalid"
	ProbeStatusCanceled = "canceled"
	ProbeStatusTimeout  = "timeout"
)
View Source
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"
)
View Source
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"
)
View Source
const PermissionRequestIDMetaKey = "request_id"

PermissionRequestIDMetaKey pins the externally addressable permission request ID in ACP metadata.

View Source
const (
	// PromptJudgeRoleAgent identifies one daemon-owned agent judge prompt.
	PromptJudgeRoleAgent = "agent-judge"
)

Variables

View Source
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")
)
View Source
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")
)
View Source
var ErrInvalidPromptMetadata = errors.New("acp: invalid prompt metadata")

ErrInvalidPromptMetadata identifies metadata that cannot be sent to an ACP agent.

View Source
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

func IsLoadSessionResourceMissing(err error) bool

IsLoadSessionResourceMissing reports whether a resume failed because the upstream ACP implementation no longer knows the referenced session id.

func NewLocalLauncher

func NewLocalLauncher(logger *slog.Logger, stopTimeout time.Duration) sandbox.Launcher

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

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

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.

func CloneCaps

func CloneCaps(caps Caps) Caps

CloneCaps returns a deep copy of ACP caps.

type Driver

type Driver struct {
	// contains filtered or unexported fields
}

Driver launches ACP agent subprocesses and brokers JSON-RPC traffic.

func New

func New(opts ...Option) *Driver

New constructs an ACP driver with sensible defaults.

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

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.

func (*Driver) Start

func (d *Driver) Start(ctx context.Context, opts StartOpts) (process *AgentProcess, startErr error)

Start launches a subprocess, completes ACP initialization, and creates or resumes a session.

func (*Driver) Stop

func (d *Driver) Stop(ctx context.Context, proc *AgentProcess) error

Stop terminates the subprocess and waits for it to exit.

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 Handle

type Handle = sandbox.Handle

Handle represents a running agent process.

type LaunchSpec

type LaunchSpec = sandbox.LaunchSpec

LaunchSpec describes the ACP-capable command to start inside a sandbox.

type Launcher

type Launcher = sandbox.Launcher

Launcher starts an ACP-capable agent process 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

func WithLauncher(launcher sandbox.Launcher) Option

WithLauncher overrides the sandbox launcher used by default for new ACP sessions.

func WithLogger

func WithLogger(logger *slog.Logger) Option

WithLogger directs driver diagnostics to the provided logger.

func WithPermissionTimeout

func WithPermissionTimeout(timeout time.Duration) Option

WithPermissionTimeout overrides how long an interactive permission request waits for approval.

func WithProcessRecordTimeout

func WithProcessRecordTimeout(timeout time.Duration) Option

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

func WithPromptBufferSize(size int) Option

WithPromptBufferSize overrides the per-prompt event buffer size.

func WithPromptDrainWait

func WithPromptDrainWait(wait time.Duration) Option

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

func WithStopTimeout(timeout time.Duration) Option

WithStopTimeout overrides how long Stop waits before escalating to SIGKILL.

func WithToolHost

func WithToolHost(toolHost sandbox.ToolHost) Option

WithToolHost overrides the sandbox tool host used by default for new ACP sessions.

type ProbeLookup

type ProbeLookup func(context.Context, string) (string, error)

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

type ProbeTarget struct {
	AgentName string
	Provider  string
	Command   string
}

ProbeTarget identifies one configured ACP-compatible agent/provider command that should be checked before operators need to start a session.

type PromptActivityReport

type PromptActivityReport struct {
	Timestamp time.Time
	Kind      string
	Detail    string
}

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

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"
	ProviderFailureModelUnavailable ProviderFailureKind = "model_unavailable"
	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

type RuntimeConfig struct {
	Model           string
	ReasoningEffort string
	Speed           speedpkg.Speed
}

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

type SessionConfigOptionValue struct {
	Value       string
	Label       string
	Description string
}

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.

func (StartOpts) Validate

func (o StartOpts) Validate() error

Validate ensures the start options are minimally usable.

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.

type ToolHost

type ToolHost = sandbox.ToolHost

ToolHost abstracts ACP file, permission, and terminal operations for a runtime.

Jump to

Keyboard shortcuts

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