acp

package
v0.3.0-beta.37 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 47 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 (
	// 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"
)
View Source
const (
	ProbeStatusOK       = "ok"
	ProbeStatusMissing  = "missing"
	ProbeStatusInvalid  = "invalid"
	ProbeStatusCanceled = "canceled"
	ProbeStatusTimeout  = "timeout"
)
View Source
const (
	DeliveredMentionBlockSessionReferences = "session_references"
	DeliveredMentionBlockResourceLink      = "resource_link"
)

Delivered mention block kinds.

View Source
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"
)
View Source
const (
	ProviderErrorAuthRequired = "provider_auth_required"
	ProviderErrorRateLimited  = "provider_rate_limited"
)
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 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"
)
View Source
const EventTypeCompaction = "compaction"
View Source
const EventTypePromptDelivery = "prompt_delivery"
View Source
const MaxPromptOriginInReplyToLength = 200

MaxPromptOriginInReplyToLength bounds the message id an explicit reply may reference.

View Source
const MaxSessionMessageHops = 8
View Source
const (
	// PromptJudgeRoleAgent identifies one daemon-owned agent judge prompt.
	PromptJudgeRoleAgent = "agent-judge"
)
View Source
const PromptOriginKindSession = "session"
View Source
const PromptSyntheticKindMonitor = "monitor"

PromptSyntheticKindMonitor attributes daemon wakes emitted by fired session monitors.

View Source
const PromptSyntheticKindSessionReply = "session_reply"
View Source
const TextEstimateMethod = "bytes_div_4"

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 (
	ErrIngestSaturated = errors.New("acp: prompt ingestion capacity exhausted")
	ErrIngestClosed    = errors.New("acp: prompt ingestion is closed")
)
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")
	// 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 (
	// 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")
)
View Source
var ErrACPAuthRequired = errors.New("acp: provider authentication required")

ErrACPAuthRequired reports that a disposable ACP session probe was refused with an authentication-required peer error.

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

View Source
var ErrInvalidPromptMetadata = errors.New("acp: invalid prompt metadata")

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

View Source
var ErrPermissionQueueFull = errors.New("acp: pending permission queue is full (cap 128)")
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.

View Source
var ErrSteerTurnMismatch = errors.New("acp: steer target is no longer the active turn")

Functions

func AcceptedSessionID

func AcceptedSessionID(err error) (string, bool)

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 DaemonMatchedEnv

func DaemonMatchedEnv(base []string) []string

DaemonMatchedEnv binds subprocess CLI discovery to the executable running the daemon.

func EstimateTokens

func EstimateTokens(byteLen int64) int64

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

func IsAuthRequiredError(err error) bool

IsAuthRequiredError reports whether err carries an ACP authentication-required peer refusal, including through the driver's wrapped control-request chain.

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 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 ResolveSteerCapability

func ResolveSteerCapability(
	provider string,
	announced []string,
	override config.SteerCapability,
) config.SteerCapability

func ValidateACPModePermissions

func ValidateACPModePermissions(
	options []SessionConfigOptionSelection,
	permissions compozyconfig.PermissionMode,
) error

ValidateACPModePermissions keeps unrestricted provider modes behind the effective session permission policy at both start and live runtime changes.

func ValidateModelConfigValue

func ValidateModelConfigValue(options []SessionConfigOption, modelID string) error

ValidateModelConfigValue verifies that modelID is an exact advertised ACP model value.

func ValidatePromptOriginInReplyTo

func ValidatePromptOriginInReplyTo(value string) error

ValidatePromptOriginInReplyTo accepts an empty value or one bounded message id without whitespace.

func WrapAcceptedStart

func WrapAcceptedStart(sessionID string, err error) error

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

type AcceptedStartError struct {
	SessionID string
	Cause     error
}

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) 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) 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) 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) 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) 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.

type AgentProcess

type AgentProcess struct {
	PID       int
	AgentName string
	Command   string
	Args      []string
	Cwd       string
	SessionID string
	StartedAt time.Time
	// contains filtered or unexported fields
}

AgentProcess represents one running ACP-backed agent subprocess.

func (*AgentProcess) CapsSnapshot

func (p *AgentProcess) CapsSnapshot() Caps

CapsSnapshot returns the latest ACP capability/config snapshot.

func (*AgentProcess) Done

func (p *AgentProcess) Done() <-chan struct{}

Done returns a channel that closes when the subprocess exits.

func (*AgentProcess) ExitStatus

func (p *AgentProcess) ExitStatus() (subprocess.ExitStatus, bool)

ExitStatus returns the OS exit facts exposed by the underlying process handle.

func (*AgentProcess) ForkSession

func (p *AgentProcess) ForkSession(
	ctx context.Context,
	cwd string,
	mcpServers []acpsdk.McpServer,
) (ForkSessionResult, error)

ForkSession calls unstable session/fork on this (bound) process for the caller's cwd. While the call is open, and afterwards, notifications and callbacks whose sessionId is the returned clone id are delivered to the fork sink (captured in Updates) or quarantined; they are never emitted on the bound session's prompt stream and p.SessionID never changes.

func (*AgentProcess) HasPendingPermission

func (p *AgentProcess) HasPendingPermission() bool

HasPendingPermission reports whether this process is waiting for an interactive permission decision.

func (*AgentProcess) HealthState

func (p *AgentProcess) HealthState() subprocess.HealthState

HealthState returns the latest managed subprocess health snapshot.

func (*AgentProcess) IngestStats

func (p *AgentProcess) IngestStats() IngestStats

IngestStats exposes the active transport backlog to session supervision.

func (*AgentProcess) RequestPermission

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 {
	MethodID string
	Reason   AuthMethodUnavailableReason
}

AuthMethodUnavailableError reports that the exact configured ACP method is not available as an agent method. No authenticate request was sent.

func (*AuthMethodUnavailableError) Error

type AuthMethodUnavailableReason

type AuthMethodUnavailableReason string

AuthMethodUnavailableReason identifies why a configured ACP method cannot be used for explicit login.

const (
	// AuthMethodUnavailableAbsent means initialization advertised no entry with
	// the configured method ID.
	AuthMethodUnavailableAbsent AuthMethodUnavailableReason = "absent"
	// AuthMethodUnavailableTerminal means the configured ID is advertised as a
	// terminal method, which disposable login never executes.
	AuthMethodUnavailableTerminal AuthMethodUnavailableReason = "terminal"
	// AuthMethodUnavailableUnknown means the configured ID is advertised with a
	// 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

Values returns an isolated slice representation of the replacement set.

type BroadcastStats

type BroadcastStats struct {
	Subscribers int    `json:"subscribers"`
	Depth       int    `json:"depth"`
	Shed        uint64 `json:"shed"`
}

BroadcastStats measures only post-append delivery, never ingest admission.

type Caps

type Caps struct {
	SteerCapability       compozyconfig.SteerCapability
	SupportsLoadSession   bool
	SupportsCloseSession  bool
	SupportsForkSession   bool
	SupportsResumeSession bool
	PromptImage           bool
	PromptAudio           bool
	PromptEmbeddedContext bool
	SupportedModes        []string
	ConfigOptions         []SessionConfigOption
	SpeedResolution       *speedpkg.Resolution
}

Caps captures the usable capabilities exposed by an ACP agent.

func CloneCaps

func CloneCaps(caps Caps) Caps

CloneCaps returns a deep copy of ACP caps.

type CommandResult

type CommandResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
	Duration time.Duration
}

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

type CommandSpec struct {
	Executable string
	Args       []string
	Cwd        string
	Env        []string
}

CommandSpec identifies one already-resolved command in a runtime.

type CompactionObservation

type CompactionObservation struct {
	CompactionID string
	Status       string
	Summary      string
	Error        string
	Terminal     bool
}

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

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

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) 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) VerifyExit

func (d *Driver) VerifyExit(proc *AgentProcess) (bool, error)

VerifyExit distinguishes confirmed process exit from a failed status lookup.

type EventAttachment

type EventAttachment struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	MIMEType string `json:"mime_type"`
	Bytes    int64  `json:"bytes"`
	SHA256   string `json:"sha256"`
	Kind     string `json:"kind"`
	Width    int    `json:"width,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                []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.

func NewLocalLauncher

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

NewLocalLauncher returns the local daemon-host subprocess launcher.

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 LocalTerminalScope struct {
	WorkspaceID  string
	ProfileID    string
	SessionID    string
	Generation   int64
	ActorID      string
	AllowedRoots []string
}

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

func WithAgentNiceness(niceness int) Option

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

func WithControlTimeout(timeout time.Duration) Option

WithControlTimeout bounds each non-prompt ACP request; nonpositive values use method-specific defaults.

func WithLauncher

func WithLauncher(launcher Launcher) Option

WithLauncher overrides the process 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 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

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 WithStartAttempts

func WithStartAttempts(attempts int) Option

WithStartAttempts sets the fresh-process ceiling for timed-out session/new; nonpositive values use two.

func WithStopTimeout

func WithStopTimeout(timeout time.Duration) Option

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

func WithToolHost(toolHost ToolHost) Option

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

type PermissionDecision

type PermissionDecision string

PermissionDecision is a daemon policy decision for an ACP permission request.

const (
	// PermissionDecisionPending asks an operator or client to decide.
	PermissionDecisionPending PermissionDecision = "pending"
	// PermissionDecisionCanceled closes a request without an operator decision.
	PermissionDecisionCanceled PermissionDecision = "canceled"
	// PermissionDecisionAllowOnce permits one operation.
	PermissionDecisionAllowOnce PermissionDecision = "allow-once"
	// PermissionDecisionAllowAlways permits this class of operation persistently.
	PermissionDecisionAllowAlways PermissionDecision = "allow-always"
	// PermissionDecisionRejectOnce rejects one operation.
	PermissionDecisionRejectOnce PermissionDecision = "reject-once"
	// PermissionDecisionRejectAlways rejects this class of operation persistently.
	PermissionDecisionRejectAlways PermissionDecision = "reject-always"
)

type PermissionOperation

type PermissionOperation string

PermissionOperation identifies a ToolHost operation subject to policy.

const (
	// PermissionOperationReadTextFile authorizes ACP text file reads.
	PermissionOperationReadTextFile PermissionOperation = "fs/read_text_file"
	// PermissionOperationWriteTextFile authorizes ACP text file writes.
	PermissionOperationWriteTextFile PermissionOperation = "fs/write_text_file"
	// PermissionOperationCreateTerminal authorizes terminal creation.
	PermissionOperationCreateTerminal PermissionOperation = "terminal/create"
	// PermissionOperationCloseTerminal authorizes closing a live terminal.
	PermissionOperationCloseTerminal PermissionOperation = "terminal/close"
	// PermissionOperationRequestToolGrant authorizes interactive permission requests.
	PermissionOperationRequestToolGrant PermissionOperation = "session/request_permission"
)

type ProbeLookup

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

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 PromptAttachment

type PromptAttachment struct {
	Name     string
	MIMEType string
	Data     []byte
}

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
	Message                   string
	Maintenance               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) Validate

func (r PromptRequest) Validate() error

Validate ensures the prompt request can be sent to the agent.

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(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
}

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

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"
	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,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 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

type SessionConfigOptionSelection struct {
	ID        string
	ValueID   string
	BoolValue *bool
}

SessionConfigOptionSelection identifies one typed ACP config option update.

func CloneSessionConfigOptionSelections

func CloneSessionConfigOptionSelections(
	selections []SessionConfigOptionSelection,
) []SessionConfigOptionSelection

CloneSessionConfigOptionSelections returns an ownership-safe copy of ACP selections.

func NormalizeSessionConfigOptionSelections

func NormalizeSessionConfigOptionSelections(
	selections []SessionConfigOptionSelection,
) ([]SessionConfigOptionSelection, error)

NormalizeSessionConfigOptionSelections validates and canonicalizes typed ACP selections.

type SessionConfigOptionValue

type SessionConfigOptionValue struct {
	Value       string
	Label       string
	Description string
	GroupID     string
	GroupLabel  string
}

SessionConfigOptionValue captures one selectable value for an ACP config option.

type SessionInspectionRequest

type SessionInspectionRequest struct {
	AgentName string
	Command   string
	Cwd       string
	Env       []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 {
	AgentName            string
	CompozySessionID     string
	WorkspaceID          string
	ProfileID            string
	RuntimeGeneration    int64
	Command              string
	Cwd                  string
	AdditionalDirs       []string
	Env                  []string
	MCPServers           []compozyconfig.MCPServer
	Permissions          compozyconfig.PermissionMode
	SystemPrompt         string
	StartupManifest      StartupManifest
	SystemPromptDelivery SystemPromptDeliveryMode
	PreferredModel       string
	ReasoningEffort      string
	Speed                speedpkg.Speed
	ACPOptions           []SessionConfigOptionSelection
	RuntimeStrategy      RuntimeApplicationStrategy
	LaunchModelID        string
	ResumeSessionID      string
	Launcher             Launcher
	ToolHost             ToolHost
	ToolGateway          ToolExecutionGateway
	ProviderName         string
	ProviderConfig       *compozyconfig.ProviderConfig
	ProviderAuthEnv      *authproviders.ProbeEnv
	ActivateMCPServers   func(context.Context) error
	Inspection           bool
	// contains filtered or unexported fields
}

StartOpts defines how to launch and initialize an ACP agent process.

func (StartOpts) Validate

func (o StartOpts) Validate() error

Validate ensures the start options are minimally usable.

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

TerminalHost is the narrow terminal core consumed by ACP's three terminal methods.

type TokenUsage

type TokenUsage struct {
	Meta             map[string]any
	Sequence         int64
	TurnID           string
	InputTokens      *int64
	OutputTokens     *int64
	TotalTokens      *int64
	ThoughtTokens    *int64
	CacheReadTokens  *int64
	CacheWriteTokens *int64
	ContextUsed      *int64
	ContextSize      *int64
	CostAmount       *float64
	CostCurrency     *string
	Timestamp        time.Time
}

TokenUsage captures per-turn usage reported by the agent.

func (TokenUsage) IsZero

func (u TokenUsage) IsZero() bool

IsZero reports whether the usage payload carries any reported values.

func (TokenUsage) Merge

func (u TokenUsage) Merge(other TokenUsage) TokenUsage

Merge overlays non-nil usage fields from other into the receiver.

type ToolExecutionGateway

type ToolExecutionGateway interface {
	Intercept(context.Context, ToolExecutionRequest) (ToolExecutionRequest, error)
}

ToolExecutionGateway authoritatively intercepts provider-native tool calls at the execution boundary.

type ToolExecutionRequest

type ToolExecutionRequest struct {
	ToolID   string
	ReadOnly bool
	Input    json.RawMessage
}

ToolExecutionRequest captures one provider-native tool call before any real side effect happens.

type ToolHost

type ToolHost interface {
	ReadTextFile(ctx context.Context, path string) (string, error)
	WriteTextFile(ctx context.Context, path string, content string) error
	ResolvePath(path string) (string, error)
	Authorize(op PermissionOperation) error
	PermissionDecision(req acpsdk.RequestPermissionRequest) (PermissionDecision, bool)
	CreateTerminal(ctx context.Context, req acpsdk.CreateTerminalRequest) (acpsdk.CreateTerminalResponse, error)
	KillTerminal(id string) error
	TerminalOutput(id string) (string, error)
	WaitForTerminalExit(ctx context.Context, id string) (int, error)
	ReleaseTerminal(id string) error
}

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

func NewLocalToolHost

func NewLocalToolHost(
	ctx context.Context,
	root string,
	mode compozyconfig.PermissionMode,
	logger *slog.Logger,
	opts ...LocalRuntimeOption,
) (ToolHost, error)

NewLocalToolHost returns the local daemon-host file, permission, and terminal host.

Source Files

Jump to

Keyboard shortcuts

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