tools

package
v0.3.0-beta.6 Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2026 License: MIT Imports: 30 Imported by: 0

Documentation

Overview

Package tools defines canonical Tool Registry contracts.

Index

Constants

View Source
const (
	// ToolArtifactURIPrefix identifies retained oversized tool results.
	ToolArtifactURIPrefix = "compozy://tool-artifacts/"
	// ToolArtifactMIMEType identifies the canonical retained ToolResult JSON envelope.
	ToolArtifactMIMEType = "application/vnd.compozy.tool-result+json"
	// ToolArtifactName is the stable display name for retained result envelopes.
	ToolArtifactName = "tool-result.json"
	// DefaultToolArtifactPageBytes is the default artifact read size.
	DefaultToolArtifactPageBytes int64 = 64 << 10
	// MaxToolArtifactPageBytes is the largest public artifact read size.
	MaxToolArtifactPageBytes int64 = 64 << 10
)
View Source
const (
	// ToolSourceBuiltin marks daemon-defined tools.
	ToolSourceBuiltin = SourceBuiltin
	// ToolSourceMCP marks tools discovered from MCP servers.
	ToolSourceMCP = SourceMCP
	// ToolSourceExtension marks tools provided by extensions.
	ToolSourceExtension = SourceExtension
	// ToolSourceDynamic marks future runtime-assembled tools.
	ToolSourceDynamic = SourceDynamic
)
View Source
const (
	// BuiltinSourceOwner is the source owner for daemon-compiled Compozy tools.
	BuiltinSourceOwner = "daemon"
)
View Source
const (
	// MaxClarifyChoices bounds model-authored choices before a question reaches a user.
	MaxClarifyChoices = 4
)
View Source
const ToolArtifactSweepInterval = time.Hour

ToolArtifactSweepInterval is the daemon-owned periodic retention cadence.

View Source
const (
	// ToolResourceKind is the canonical desired-state resource kind for tool records.
	ToolResourceKind resources.ResourceKind = "tool"
)

Variables

View Source
var (
	// ErrApprovalGrantInvalid reports an invalid durable native-tool approval grant.
	ErrApprovalGrantInvalid = errors.New("tools: invalid approval grant")
	// ErrApprovalGrantNotFound reports a missing grant without exposing another workspace's rows.
	ErrApprovalGrantNotFound = errors.New("tools: approval grant not found")
)
View Source
var (
	// ErrToolArtifactNotFound hides missing, expired, and foreign-workspace artifacts behind one error.
	ErrToolArtifactNotFound = errors.New("tools: tool artifact not found")
	// ErrToolArtifactInvalidRange reports an offset or limit outside the retained content bounds.
	ErrToolArtifactInvalidRange = errors.New("tools: invalid tool artifact range")
	// ErrToolArtifactCorrupt reports retained bytes that do not match their content identity.
	ErrToolArtifactCorrupt = errors.New("tools: tool artifact is corrupt")
	// ErrToolArtifactPersistence reports a durable write or retention failure.
	ErrToolArtifactPersistence = errors.New("tools: tool artifact persistence failed")
)
View Source
var (
	// ErrClarifyInvalid reports an invalid question or answer supplied at a public boundary.
	ErrClarifyInvalid = errors.New("tools: invalid clarification")
	// ErrClarifyPending reports that a session already owns an unresolved question.
	ErrClarifyPending = errors.New("tools: clarification already pending")
	// ErrClarifyNotFound reports that no live request matched the session and request ID.
	ErrClarifyNotFound = errors.New("tools: clarification not found")
	// ErrClarifyCanceled reports session-stop, caller-cancel, or daemon-shutdown cancellation.
	ErrClarifyCanceled = errors.New("tools: clarification canceled")
	// ErrClarifyClosed reports an ask attempted after broker shutdown began.
	ErrClarifyClosed = errors.New("tools: clarification broker closed")
)
View Source
var (
	// ErrToolNotFound reports an unknown tool id.
	ErrToolNotFound = errors.New("tools: tool not found")
	// ErrToolConflict reports a canonical id or sanitized-name conflict.
	ErrToolConflict = errors.New("tools: tool conflict")
	// ErrToolUnavailable reports an unavailable tool.
	ErrToolUnavailable = errors.New("tools: tool unavailable")
	// ErrToolDenied reports policy denial.
	ErrToolDenied = errors.New("tools: tool denied")
	// ErrToolApprovalRequired reports required approval.
	ErrToolApprovalRequired = errors.New("tools: tool approval required")
	// ErrToolInvalidInput reports invalid tool input.
	ErrToolInvalidInput = errors.New("tools: invalid tool input")
	// ErrToolResultTooLarge reports result budget overflow.
	ErrToolResultTooLarge = errors.New("tools: tool result too large")
	// ErrToolResultPersistence reports oversized result offload failure.
	ErrToolResultPersistence = errors.New("tools: tool result persistence failed")
	// ErrToolBackendFailed reports a backend adapter failure.
	ErrToolBackendFailed = errors.New("tools: backend failed")
	// ErrToolCanceled reports call cancellation.
	ErrToolCanceled = errors.New("tools: tool call canceled")
	// ErrToolTimedOut reports call deadline expiration.
	ErrToolTimedOut = errors.New("tools: tool call timed out")
)

Functions

func ApprovalInputDigest

func ApprovalInputDigest(input json.RawMessage, suppliedDigest string) (string, error)

ApprovalInputDigest returns the stable digest binding used for local approvals.

func CanonicalIDSegment

func CanonicalIDSegment(raw string) (string, error)

CanonicalIDSegment normalizes one external name into a provider-safe segment.

func CanonicalJSON

func CanonicalJSON(raw json.RawMessage) ([]byte, error)

CanonicalJSON returns RFC 8785/JCS-compatible canonical JSON bytes.

func CommandFlagTypeValues

func CommandFlagTypeValues() []string

CommandFlagTypeValues returns the complete generated-contract enum domain.

func MCPDiscoveryFailureClass

func MCPDiscoveryFailureClass(err error) deadentity.FailureClass

MCPDiscoveryFailureClass maps structured MCP errors into reliability signals.

func NewResourceCodec

func NewResourceCodec() (resources.KindCodec[Tool], error)

NewResourceCodec builds the canonical tool resource codec.

func ParseToolArtifactURI

func ParseToolArtifactURI(uri string) (string, error)

ParseToolArtifactURI validates an opaque artifact URI and returns its path-safe identity.

func SchemaDigest

func SchemaDigest(raw json.RawMessage) (string, error)

SchemaDigest returns the lowercase SHA-256 digest of a canonical JSON Schema subtree.

func ValidateHandle

func ValidateHandle(handle Handle) error

ValidateHandle rejects nil or malformed handles before dispatch.

func ValidateJSONObject

func ValidateJSONObject(field string, raw json.RawMessage, required bool) error

ValidateJSONObject validates a JSON Schema object payload.

func ValidateProvider

func ValidateProvider(provider Provider) error

ValidateProvider rejects nil or malformed providers before registry use.

Types

type AgentToolPolicy

type AgentToolPolicy struct {
	Tools     []ToolPattern `json:"-"`
	Toolsets  []ToolsetID   `json:"toolsets,omitempty"`
	DenyTools []ToolPattern `json:"-"`
}

AgentToolPolicy captures agent-local allow and deny grammar.

type ApprovalBridge

type ApprovalBridge interface {
	RequestToolApproval(ctx context.Context, scope Scope, call CallRequest, view *ToolView) error
}

ApprovalBridge mediates approval-required calls before provider execution.

type ApprovalGrant

type ApprovalGrant struct {
	ID string `json:"id"`
	ApprovalGrantKey
	Decision   ApprovalGrantDecision `json:"decision"`
	CreatedAt  time.Time             `json:"created_at"`
	LastUsedAt time.Time             `json:"last_used_at"`
}

ApprovalGrant is one durable native-tool approval decision.

func (ApprovalGrant) Normalize

func (g ApprovalGrant) Normalize() ApprovalGrant

Normalize returns a canonical durable grant.

func (ApprovalGrant) Validate

func (g ApprovalGrant) Validate() error

Validate checks a fully materialized grant.

func (ApprovalGrant) ValidateForPut

func (g ApprovalGrant) ValidateForPut() error

ValidateForPut checks a grant before the repository assigns identity and timestamps.

type ApprovalGrantDecision

type ApprovalGrantDecision string

ApprovalGrantDecision is the remembered decision for one native-tool approval key.

const (
	ApprovalGrantAllow  ApprovalGrantDecision = "allow"
	ApprovalGrantReject ApprovalGrantDecision = "reject"
)

type ApprovalGrantKey

type ApprovalGrantKey struct {
	WorkspaceID string `json:"workspace_id"`
	AgentName   string `json:"agent_name,omitempty"`
	ToolID      ToolID `json:"tool_id"`
	InputDigest string `json:"input_digest,omitempty"`
}

ApprovalGrantKey identifies one durable native-tool approval decision.

func (ApprovalGrantKey) Normalize

func (k ApprovalGrantKey) Normalize() ApprovalGrantKey

Normalize returns a canonical approval grant key.

func (ApprovalGrantKey) Validate

func (k ApprovalGrantKey) Validate() error

Validate checks the fields required by every durable approval lookup.

type ApprovalGrantManagementScope

type ApprovalGrantManagementScope string

ApprovalGrantManagementScope is an explicit wider-grant boundary.

const (
	// ApprovalGrantScopeAgent remembers one tool decision for every input from one agent.
	ApprovalGrantScopeAgent ApprovalGrantManagementScope = "agent"
	// ApprovalGrantScopeTool remembers one tool decision for every agent and input.
	ApprovalGrantScopeTool ApprovalGrantManagementScope = "tool"
)

type ApprovalGrantSetRequest

type ApprovalGrantSetRequest struct {
	ToolID    ToolID                       `json:"tool_id"`
	Decision  ApprovalGrantDecision        `json:"decision"`
	Scope     ApprovalGrantManagementScope `json:"scope"`
	AgentName string                       `json:"agent_name,omitempty"`
}

ApprovalGrantSetRequest creates or replaces one explicit wider approval decision. Exact input grants remain exclusive to prompt-origin allow_always/reject_always answers.

func (ApprovalGrantSetRequest) BuildGrant

func (r ApprovalGrantSetRequest) BuildGrant(workspaceID string) (ApprovalGrant, error)

BuildGrant validates the explicit management boundary and returns its durable wider key.

func (ApprovalGrantSetRequest) Normalize

Normalize returns a canonical wider-grant request.

type ApprovalGrantStore

type ApprovalGrantStore interface {
	LookupApprovalGrant(ctx context.Context, key ApprovalGrantKey) (ApprovalGrant, bool, error)
	PutApprovalGrant(ctx context.Context, grant ApprovalGrant) (ApprovalGrant, error)
	ListApprovalGrants(ctx context.Context, workspaceID string) ([]ApprovalGrant, error)
	RevokeApprovalGrant(ctx context.Context, workspaceID, id string) error
}

ApprovalGrantStore persists remembered native-tool approval decisions.

type ApprovalRequest

type ApprovalRequest struct {
	ToolID      ToolID          `json:"tool_id"`
	SessionID   string          `json:"session_id"`
	WorkspaceID string          `json:"workspace_id,omitempty"`
	AgentName   string          `json:"agent_name,omitempty"`
	Input       json.RawMessage `json:"input,omitempty"`
	InputDigest string          `json:"input_digest,omitempty"`
}

ApprovalRequest describes one concrete local approval-token issuance request.

type ApprovalTokenConsumer

type ApprovalTokenConsumer interface {
	ConsumeToolApproval(ctx context.Context, scope Scope, call CallRequest) error
}

ApprovalTokenConsumer validates and consumes local approval references.

type ApprovalTokenGrant

type ApprovalTokenGrant struct {
	ApprovalToken string    `json:"approval_token"`
	ExpiresAt     time.Time `json:"expires_at"`
	ToolID        ToolID    `json:"tool_id"`
	InputDigest   string    `json:"input_digest"`
}

ApprovalTokenGrant is the raw single-use approval token returned only to authenticated local callers.

type ApprovalTokenIssuer

type ApprovalTokenIssuer interface {
	CreateToolApproval(ctx context.Context, scope Scope, req ApprovalRequest) (ApprovalTokenGrant, error)
}

ApprovalTokenIssuer mints local single-use approval references.

type ApprovalTokenStore

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

ApprovalTokenStore keeps local approval references in daemon memory only.

func NewApprovalTokenStore

func NewApprovalTokenStore(ttl time.Duration, opts ...ApprovalTokenStoreOption) *ApprovalTokenStore

NewApprovalTokenStore builds a daemon-memory approval token store.

func (*ApprovalTokenStore) ConsumeToolApproval

func (s *ApprovalTokenStore) ConsumeToolApproval(ctx context.Context, scope Scope, call CallRequest) error

ConsumeToolApproval validates and consumes a single-use approval token.

func (*ApprovalTokenStore) CreateToolApproval

func (s *ApprovalTokenStore) CreateToolApproval(
	ctx context.Context,
	scope Scope,
	req ApprovalRequest,
) (ApprovalTokenGrant, error)

CreateToolApproval mints a single-use approval token bound to one invocation.

type ApprovalTokenStoreOption

type ApprovalTokenStoreOption func(*ApprovalTokenStore)

ApprovalTokenStoreOption customizes an in-memory approval token store.

func WithApprovalTokenClock

func WithApprovalTokenClock(now func() time.Time) ApprovalTokenStoreOption

WithApprovalTokenClock overrides the approval-token clock for tests.

func WithApprovalTokenRandom

func WithApprovalTokenRandom(random io.Reader) ApprovalTokenStoreOption

WithApprovalTokenRandom overrides the random source for tests.

type ArtifactRef

type ArtifactRef struct {
	URI      string `json:"uri"`
	Name     string `json:"name,omitempty"`
	MIMEType string `json:"mime_type,omitempty"`
	Bytes    int64  `json:"bytes,omitempty"`
	SHA256   string `json:"sha256,omitempty"`
}

ArtifactRef points to a durable tool output artifact.

type Availability

type Availability struct {
	Registered  bool         `json:"registered"`
	Enabled     bool         `json:"enabled"`
	Available   bool         `json:"available"`
	Authorized  bool         `json:"authorized"`
	Executable  bool         `json:"executable"`
	Conflicted  bool         `json:"conflicted"`
	ReasonCodes []ReasonCode `json:"reason_codes,omitempty"`
}

Availability records composable tool availability state.

func Available

func Available() Availability

Available returns the default executable availability for healthy native tools.

func Unavailable

func Unavailable(reason ReasonCode) Availability

Unavailable returns a deterministic unavailable state for missing native dependencies.

func (Availability) Validate

func (a Availability) Validate() error

Validate checks availability state consistency.

type BackendKind

type BackendKind string

BackendKind identifies the executable backend class.

const (
	// BackendNativeGo executes a daemon-compiled Go handler.
	BackendNativeGo BackendKind = "native_go"
	// BackendExtensionHost executes through the extension host subprocess runtime.
	BackendExtensionHost BackendKind = "extension_host"
	// BackendMCP executes through daemon-owned MCP client adapters.
	BackendMCP BackendKind = "mcp"
	// BackendBridge is reserved for a later bridge adapter TechSpec.
	BackendBridge BackendKind = "bridge"
)

func (BackendKind) Validate

func (k BackendKind) Validate(field string) error

Validate ensures the backend kind is documented.

type BackendRef

type BackendRef struct {
	Kind                 BackendKind `json:"kind"`
	ExtensionID          string      `json:"extension_id,omitempty"`
	Handler              string      `json:"handler,omitempty"`
	MCPServer            string      `json:"mcp_server,omitempty"`
	MCPTool              string      `json:"mcp_tool,omitempty"`
	NativeName           string      `json:"native_name,omitempty"`
	RequiresCapabilities []string    `json:"requires_capabilities,omitempty"`
}

BackendRef binds a descriptor to its executable backend.

func (BackendRef) Validate

func (b BackendRef) Validate(field string) error

Validate ensures the backend reference has the fields required for its kind.

type CallInputAuthorizer

type CallInputAuthorizer interface {
	AuthorizeCallInput(
		ctx context.Context,
		scope Scope,
		descriptor Descriptor,
		call CallRequest,
	) error
}

CallInputAuthorizer authorizes the final bound input after hooks and schema validation.

type CallInputBinder

type CallInputBinder interface {
	BindCallInput(
		ctx context.Context,
		scope Scope,
		descriptor Descriptor,
		input json.RawMessage,
	) (json.RawMessage, error)
}

CallInputBinder rewrites trusted scope into tool input before schema validation.

type CallRequest

type CallRequest struct {
	ToolID               ToolID          `json:"tool_id"`
	ToolCallID           string          `json:"tool_call_id,omitempty"`
	TurnID               string          `json:"turn_id,omitempty"`
	SessionID            string          `json:"session_id,omitempty"`
	WorkspaceID          string          `json:"workspace_id,omitempty"`
	AgentName            string          `json:"agent_name,omitempty"`
	ActorKind            string          `json:"actor_kind,omitempty"`
	CorrelationID        string          `json:"correlation_id,omitempty"`
	Input                json.RawMessage `json:"input"`
	SensitiveInputFields []string        `json:"sensitive_input_fields,omitempty"`
	ApprovalToken        string          `json:"approval_token,omitempty"`
	TrustedWorkspaceRoot string          `json:"-"`
}

CallRequest is the canonical dispatch request.

type ClarifyAnswer

type ClarifyAnswer struct {
	Choice   *int   `json:"choice"`
	Text     string `json:"text"`
	Fallback bool   `json:"fallback"`
}

ClarifyAnswer is the frozen answer returned to native and extension callers.

type ClarifyAnswerRequest

type ClarifyAnswerRequest struct {
	ChoiceIndex *int   `json:"choice_index,omitempty"`
	Text        string `json:"text,omitempty"`
}

ClarifyAnswerRequest is the public answer mutation payload.

func (ClarifyAnswerRequest) Normalize

func (r ClarifyAnswerRequest) Normalize(question ClarifyQuestion) (ClarifyAnswer, error)

Normalize validates an answer against the original question.

type ClarifyBroker

ClarifyBroker owns the boot-scoped live clarification projection.

type ClarifyEvent

type ClarifyEvent struct {
	Status  ClarifyStatus  `json:"status"`
	Request ClarifyPending `json:"request"`
	Answer  *ClarifyAnswer `json:"answer,omitempty"`
	At      time.Time      `json:"at"`
}

ClarifyEvent is the durable session/SSE lifecycle payload.

func (ClarifyEvent) Validate

func (e ClarifyEvent) Validate() error

Validate ensures lifecycle evidence cannot represent an impossible transition.

type ClarifyPending

type ClarifyPending struct {
	RequestID   string    `json:"request_id"`
	WorkspaceID string    `json:"workspace_id"`
	SessionID   string    `json:"session_id"`
	AgentName   string    `json:"agent_name"`
	Question    string    `json:"question"`
	Choices     []string  `json:"choices,omitempty"`
	AskedAt     time.Time `json:"asked_at"`
	Deadline    time.Time `json:"deadline"`
}

ClarifyPending is the complete live projection for one unresolved question.

func (ClarifyPending) Clone

func (p ClarifyPending) Clone() ClarifyPending

Clone returns an isolated pending projection.

type ClarifyQuestion

type ClarifyQuestion struct {
	Question string   `json:"question"`
	Choices  []string `json:"choices,omitempty"`
}

ClarifyQuestion is the model-authored request accepted by the broker.

func (ClarifyQuestion) Normalize

func (q ClarifyQuestion) Normalize() (ClarifyQuestion, error)

Normalize validates and isolates one clarification question.

type ClarifyStatus

type ClarifyStatus string

ClarifyStatus identifies one durable clarification lifecycle transition.

const (
	ClarifyStatusPending  ClarifyStatus = "pending"
	ClarifyStatusResolved ClarifyStatus = "resolved"
	ClarifyStatusTimedOut ClarifyStatus = "timed_out"
	ClarifyStatusCanceled ClarifyStatus = "canceled"
)

type CommandFlag

type CommandFlag struct {
	Name       string          `json:"name"`
	Field      string          `json:"field"`
	Type       CommandFlagType `json:"type"`
	Repeatable bool            `json:"repeatable"`
	Required   bool            `json:"required"`
	Nullable   bool            `json:"nullable"`
	Enum       []string        `json:"enum,omitempty"`
	Default    json.RawMessage `json:"default,omitempty"`
	Minimum    *float64        `json:"minimum,omitempty"`
	Maximum    *float64        `json:"maximum,omitempty"`
}

CommandFlag is the schema-derived CLI projection for one top-level input field.

type CommandFlagType

type CommandFlagType string

CommandFlagType is the closed scalar type accepted by projected command flags.

const (
	// CommandFlagString projects a JSON string.
	CommandFlagString CommandFlagType = "string"
	// CommandFlagBoolean projects a JSON boolean.
	CommandFlagBoolean CommandFlagType = "boolean"
	// CommandFlagInteger projects a JSON integer.
	CommandFlagInteger CommandFlagType = "integer"
	// CommandFlagNumber projects a JSON number.
	CommandFlagNumber CommandFlagType = "number"
)

type DefaultResultProcessor

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

DefaultResultProcessor applies secret redaction and descriptor/default byte caps.

func NewResultProcessor

func NewResultProcessor(
	defaultMaxBytes int64,
	artifacts ToolArtifactStore,
	sensitiveFields ...string,
) *DefaultResultProcessor

NewResultProcessor builds the default registry result processor.

func (*DefaultResultProcessor) Finalize

func (l *DefaultResultProcessor) Finalize(
	ctx context.Context,
	scope Scope,
	d Descriptor,
	result ToolResult,
) (ToolResult, error)

Finalize reapplies redaction after hooks, then offloads one oversized canonical result.

func (*DefaultResultProcessor) Sanitize

Sanitize redacts sensitive fields before a result reaches post-call hooks.

type DeferredDiscoveryProvider

type DeferredDiscoveryProvider interface {
	Provider
	DeferInitialDiscovery() bool
}

DeferredDiscoveryProvider marks providers whose discovery may require external I/O.

type Descriptor

type Descriptor struct {
	ID           ToolID     `json:"id"`
	Backend      BackendRef `json:"backend"`
	DisplayTitle string     `json:"display_title,omitempty"`
	*ToolPresentation
	Description         string          `json:"description"`
	InputSchema         json.RawMessage `json:"input_schema"`
	OutputSchema        json.RawMessage `json:"output_schema,omitempty"`
	InputSchemaDigest   string          `json:"input_schema_digest"`
	OutputSchemaDigest  string          `json:"output_schema_digest,omitempty"`
	Source              SourceRef       `json:"source"`
	Visibility          Visibility      `json:"visibility"`
	Risk                RiskClass       `json:"risk"`
	ReadOnly            bool            `json:"read_only"`
	Destructive         bool            `json:"destructive"`
	OpenWorld           bool            `json:"open_world"`
	RequiresInteraction bool            `json:"requires_interaction"`
	ConcurrencySafe     bool            `json:"concurrency_safe"`
	MaxResultBytes      int64           `json:"max_result_bytes,omitempty"`
	Toolsets            []ToolsetID     `json:"toolsets,omitempty"`
	Tags                []string        `json:"tags,omitempty"`
	SearchHints         []string        `json:"search_hints,omitempty"`
}

Descriptor is the normalized runtime metadata used for indexing and dispatch.

func DescriptorWithSchemaDigests

func DescriptorWithSchemaDigests(descriptor Descriptor) (Descriptor, error)

DescriptorWithSchemaDigests returns a descriptor with canonical schema digests populated.

func (Descriptor) Presentation

func (d Descriptor) Presentation() ToolPresentation

Presentation returns a nil-safe copy of the runtime descriptor presentation metadata.

func (Descriptor) Tool

func (d Descriptor) Tool() Tool

Tool returns the cold resource shape for a runtime descriptor.

func (Descriptor) Validate

func (d Descriptor) Validate() error

Validate ensures the descriptor is dispatchable metadata.

type EffectivePolicyEvaluator

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

EffectivePolicyEvaluator computes policy below the ACP permission ceiling.

func NewEffectivePolicyEvaluator

func NewEffectivePolicyEvaluator(
	inputs PolicyInputs,
	toolsets ToolsetCatalog,
	universe []ToolID,
) (*EffectivePolicyEvaluator, error)

NewEffectivePolicyEvaluator validates and prepares a policy evaluator.

func (*EffectivePolicyEvaluator) Evaluate

Evaluate computes the effective decision for one descriptor.

type EffectiveToolDecision

type EffectiveToolDecision struct {
	VisibleToOperator    bool         `json:"visible_to_operator"`
	VisibleToSession     bool         `json:"visible_to_session"`
	Callable             bool         `json:"callable"`
	ApprovalRequired     bool         `json:"approval_required"`
	SystemPermissionMode string       `json:"system_permission_mode,omitempty"`
	SessionPolicyResult  string       `json:"session_policy_result,omitempty"`
	AgentPolicyResult    string       `json:"agent_policy_result,omitempty"`
	RegistryPolicyResult string       `json:"registry_policy_result,omitempty"`
	SourcePolicyResult   string       `json:"source_policy_result,omitempty"`
	AvailabilityResult   string       `json:"availability_result,omitempty"`
	HookResult           string       `json:"hook_result,omitempty"`
	ReasonCodes          []ReasonCode `json:"reason_codes,omitempty"`
}

EffectiveToolDecision records the combined policy and availability decision.

type ErrorCode

type ErrorCode string

ErrorCode is the stable public tool error code.

const (
	// ErrorCodeNotFound maps to ErrToolNotFound.
	ErrorCodeNotFound ErrorCode = "tool_not_found"
	// ErrorCodeConflict maps to ErrToolConflict.
	ErrorCodeConflict ErrorCode = "tool_conflict"
	// ErrorCodeUnavailable maps to ErrToolUnavailable.
	ErrorCodeUnavailable ErrorCode = "tool_unavailable"
	// ErrorCodeDenied maps to ErrToolDenied.
	ErrorCodeDenied ErrorCode = "tool_denied"
	// ErrorCodeApprovalRequired maps to ErrToolApprovalRequired.
	ErrorCodeApprovalRequired ErrorCode = "tool_approval_required"
	// ErrorCodeInvalidInput maps to ErrToolInvalidInput.
	ErrorCodeInvalidInput ErrorCode = "tool_invalid_input"
	// ErrorCodeResultTooLarge maps to ErrToolResultTooLarge.
	ErrorCodeResultTooLarge ErrorCode = "tool_result_too_large"
	// ErrorCodeResultPersistenceFailed maps to ErrToolResultPersistence.
	ErrorCodeResultPersistenceFailed ErrorCode = "tool_result_persistence_failed"
	// ErrorCodeBackendFailed maps to ErrToolBackendFailed.
	ErrorCodeBackendFailed ErrorCode = "tool_backend_failed"
	// ErrorCodeCanceled maps to ErrToolCanceled.
	ErrorCodeCanceled ErrorCode = "tool_canceled"
	// ErrorCodeTimedOut maps to ErrToolTimedOut.
	ErrorCodeTimedOut ErrorCode = "tool_timed_out"
	// ErrorCodeModelNotFound reports an unknown provider-model curation target.
	ErrorCodeModelNotFound ErrorCode = "model_not_found"
	// ErrorCodeReasoningEffortUnsupported reports an unavailable model effort.
	ErrorCodeReasoningEffortUnsupported ErrorCode = "reasoning_effort_unsupported"
	// ErrorCodeAgentNameReserved reports an authored agent identity reserved for daemon roles.
	ErrorCodeAgentNameReserved ErrorCode = "agent_name_reserved"
)

type ExtensionCommandSpec

type ExtensionCommandSpec struct {
	Verb    string            `json:"verb"`
	Summary string            `json:"summary"`
	Example string            `json:"example,omitempty"`
	Flags   map[string]string `json:"flags,omitempty"`
}

ExtensionCommandSpec presents an extension tool as an operator-facing command. Execution still flows through the canonical tool runtime.

type ExtensionProvideToolsResponse

type ExtensionProvideToolsResponse struct {
	Tools []ExtensionToolRuntimeDescriptor `json:"tools"`
}

ExtensionProvideToolsResponse is the extension host runtime descriptor response.

type ExtensionToolCallRequest

type ExtensionToolCallRequest struct {
	ToolID           ToolID                       `json:"tool_id"`
	Handler          string                       `json:"handler"`
	SessionID        string                       `json:"session_id,omitempty"`
	InvocationID     string                       `json:"invocation_id,omitempty"`
	TrustedWorkspace *ExtensionToolWorkspaceScope `json:"trusted_workspace,omitempty"`
	Input            json.RawMessage              `json:"input"`
}

ExtensionToolCallRequest is the extension host call request.

type ExtensionToolCallResponse

type ExtensionToolCallResponse struct {
	Result ToolResult `json:"result"`
}

ExtensionToolCallResponse is the extension host call response.

type ExtensionToolInvoker

type ExtensionToolInvoker interface {
	ProvideTools(ctx context.Context, extensionID string) ([]ExtensionToolRuntimeDescriptor, error)
	CallTool(ctx context.Context, extensionID string, req ExtensionToolCallRequest) (ToolResult, error)
}

ExtensionToolInvoker invokes out-of-process extension tool providers.

type ExtensionToolRuntimeDescriptor

type ExtensionToolRuntimeDescriptor struct {
	ID                  ToolID                `json:"id"`
	Handler             string                `json:"handler"`
	Description         string                `json:"description,omitempty"`
	FriendlyVerb        string                `json:"friendly_verb,omitempty"`
	Preview             string                `json:"preview,omitempty"`
	InputSchema         json.RawMessage       `json:"input_schema,omitempty"`
	OutputSchema        json.RawMessage       `json:"output_schema,omitempty"`
	InputSchemaDigest   string                `json:"input_schema_digest"`
	OutputSchemaDigest  string                `json:"output_schema_digest,omitempty"`
	ReadOnly            bool                  `json:"read_only"`
	Risk                RiskClass             `json:"risk"`
	RequiresInteraction bool                  `json:"requires_interaction"`
	Capabilities        []string              `json:"capabilities,omitempty"`
	Command             *ExtensionCommandSpec `json:"command,omitempty"`
}

ExtensionToolRuntimeDescriptor is the runtime reconciliation proof for an extension tool.

func (ExtensionToolRuntimeDescriptor) Validate

Validate checks runtime reconciliation metadata for an extension tool.

type ExtensionToolWorkspaceScope

type ExtensionToolWorkspaceScope struct {
	ID   string `json:"id"`
	Root string `json:"root"`
}

ExtensionToolWorkspaceScope is daemon-authenticated invocation context, separate from tool input.

type ExternalDefault

type ExternalDefault string

ExternalDefault controls default policy for external executable sources.

const (
	// ExternalDefaultDisabled denies external sources unless explicitly granted.
	ExternalDefaultDisabled ExternalDefault = "disabled"
	// ExternalDefaultAsk allows external sources but requires approval.
	ExternalDefaultAsk ExternalDefault = "ask"
	// ExternalDefaultEnabled allows external sources subject to the ACP ceiling.
	ExternalDefaultEnabled ExternalDefault = "enabled"
)

type FilesystemToolArtifactStore

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

FilesystemToolArtifactStore retains immutable content-addressed result envelopes.

func OpenFilesystemToolArtifactStore

func OpenFilesystemToolArtifactStore(
	ctx context.Context,
	root string,
	retention ToolArtifactRetention,
	opts ...func(*artifactStoreOptions),
) (*FilesystemToolArtifactStore, error)

OpenFilesystemToolArtifactStore opens the canonical store and applies retention before use.

func (*FilesystemToolArtifactStore) Put

func (s *FilesystemToolArtifactStore) Put(
	ctx context.Context,
	workspaceID string,
	content []byte,
) (ArtifactRef, error)

Put publishes canonical bytes once and returns their opaque reference.

func (*FilesystemToolArtifactStore) ReadPage

func (s *FilesystemToolArtifactStore) ReadPage(
	ctx context.Context,
	workspaceID string,
	uri string,
	offset int64,
	limit int64,
) (ToolArtifactPage, error)

ReadPage returns one exact bounded byte range after enforcing workspace scope and retention.

func (*FilesystemToolArtifactStore) Sweep

Sweep removes expired and over-budget artifacts in deterministic creation order.

type Handle

type Handle interface {
	Descriptor() Descriptor
	Availability(ctx context.Context, scope Scope) Availability
	Call(ctx context.Context, req CallRequest) (ToolResult, error)
}

Handle is the executable runtime contract for one tool.

type HookRunner

type HookRunner interface {
	PreCall(ctx context.Context, call CallRequest) (CallRequest, EffectiveToolDecision, error)
	PostCall(ctx context.Context, call CallRequest, result ToolResult) (ToolResult, error)
	PostError(ctx context.Context, call CallRequest, err error) error
}

HookRunner runs typed registry hooks around dispatch.

type MCPAuthStatus

type MCPAuthStatus struct {
	ServerName   string     `json:"server_name"`
	Status       string     `json:"status"`
	AuthType     string     `json:"auth_type,omitempty"`
	ClientID     string     `json:"client_id,omitempty"`
	Scopes       []string   `json:"scopes,omitempty"`
	ExpiresAt    *time.Time `json:"expires_at,omitempty"`
	Refreshable  bool       `json:"refreshable"`
	TokenPresent bool       `json:"token_present"`
	Diagnostic   string     `json:"diagnostic,omitempty"`
}

MCPAuthStatus is a redacted auth diagnostic for external MCP sources.

type MCPAuthStatusProvider

type MCPAuthStatusProvider interface {
	Status(ctx context.Context, source SourceRef) (MCPAuthStatus, error)
}

MCPAuthStatusProvider returns redacted MCP auth status for diagnostics.

type MCPCallExecutor

type MCPCallExecutor interface {
	ListTools(ctx context.Context, source SourceRef) ([]MCPToolDescriptor, error)
	CallTool(ctx context.Context, source SourceRef, req MCPToolCallRequest) (ToolResult, error)
}

MCPCallExecutor lists and calls MCP tools without exposing credential material.

type MCPDeadEntityService

type MCPDeadEntityService interface {
	BeforeProbe(ctx context.Context, key store.DeadEntityKey) (deadentity.ProbeDecision, error)
	Status(ctx context.Context, key store.DeadEntityKey) (deadentity.Status, error)
	RecordFailure(
		ctx context.Context,
		key store.DeadEntityKey,
		class deadentity.FailureClass,
		reason string,
	) error
	RecordSuccess(ctx context.Context, key store.DeadEntityKey) error
	ForgetEntity(key store.DeadEntityKey)
}

MCPDeadEntityService is the reliability seam required by the MCP registry adapter.

type MCPProvider

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

MCPProvider adapts daemon-owned MCP discovery and calls into registry descriptors.

func NewMCPProvider

func NewMCPProvider(
	sources MCPSourceLister,
	exec MCPCallExecutor,
	auth MCPAuthStatusProvider,
	opts ...MCPProviderOption,
) (*MCPProvider, error)

NewMCPProvider creates a registry provider for daemon-owned MCP call-through.

func (*MCPProvider) DeferInitialDiscovery

func (*MCPProvider) DeferInitialDiscovery() bool

DeferInitialDiscovery keeps vendor MCP startup out of the hosted session handshake.

func (*MCPProvider) ForgetMCPServer

func (p *MCPProvider) ForgetMCPServer(workspaceID string, serverName string)

ForgetMCPServer retires one workspace MCP server's volatile reliability state.

func (*MCPProvider) ForgetWorkspace

func (p *MCPProvider) ForgetWorkspace(workspaceID string)

ForgetWorkspace retires cached MCP descriptors owned by one workspace.

func (*MCPProvider) ID

func (p *MCPProvider) ID() SourceRef

ID returns aggregate provider provenance.

func (*MCPProvider) List

func (p *MCPProvider) List(ctx context.Context, scope Scope) ([]Descriptor, error)

List discovers configured MCP tools and normalizes them into registry descriptors.

func (*MCPProvider) Resolve

func (p *MCPProvider) Resolve(ctx context.Context, scope Scope, id ToolID) (Handle, bool, error)

Resolve returns a handle for one discovered MCP tool.

type MCPProviderOption

type MCPProviderOption func(*MCPProvider)

MCPProviderOption configures MCP discovery behavior.

func WithMCPDeadEntityService

func WithMCPDeadEntityService(service MCPDeadEntityService) MCPProviderOption

WithMCPDeadEntityService enables workspace-scoped durable MCP recovery.

type MCPSourceLister

type MCPSourceLister interface {
	ListMCPSources(ctx context.Context) ([]SourceRef, error)
}

MCPSourceLister returns configured MCP server sources for dynamic discovery.

type MCPSourceListerFunc

type MCPSourceListerFunc func(context.Context) ([]SourceRef, error)

MCPSourceListerFunc adapts a function into an MCP source lister.

func (MCPSourceListerFunc) ListMCPSources

func (f MCPSourceListerFunc) ListMCPSources(ctx context.Context) ([]SourceRef, error)

ListMCPSources returns configured MCP server sources.

type MCPToolCallRequest

type MCPToolCallRequest struct {
	ToolID      ToolID          `json:"tool_id"`
	RawToolName string          `json:"raw_tool_name"`
	Input       json.RawMessage `json:"input"`
}

MCPToolCallRequest is the daemon-owned MCP adapter call request.

type MCPToolCallResponse

type MCPToolCallResponse struct {
	Result ToolResult `json:"result"`
}

MCPToolCallResponse is the daemon-owned MCP adapter call response.

type MCPToolDescriptor

type MCPToolDescriptor struct {
	ID           ToolID          `json:"id"`
	RawName      string          `json:"raw_name"`
	Title        string          `json:"title,omitempty"`
	FriendlyVerb string          `json:"friendly_verb,omitempty"`
	Preview      string          `json:"preview,omitempty"`
	Description  string          `json:"description,omitempty"`
	InputSchema  json.RawMessage `json:"input_schema"`
	OutputSchema json.RawMessage `json:"output_schema,omitempty"`
	Source       SourceRef       `json:"source"`
	ReadOnly     bool            `json:"read_only"`
}

MCPToolDescriptor describes one externally discovered MCP tool.

type NativeAvailabilityFunc

type NativeAvailabilityFunc func(ctx context.Context, scope Scope) Availability

NativeAvailabilityFunc computes runtime availability for one daemon-compiled tool.

type NativeProvider

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

NativeProvider serves daemon-compiled native_go tools.

func NewNativeProvider

func NewNativeProvider(source SourceRef, nativeTools ...NativeTool) (*NativeProvider, error)

NewNativeProvider validates and indexes native tools for one source.

func (*NativeProvider) ID

func (p *NativeProvider) ID() SourceRef

ID returns the provider provenance.

func (*NativeProvider) List

func (p *NativeProvider) List(_ context.Context, _ Scope) ([]Descriptor, error)

List returns deterministic native descriptors.

func (*NativeProvider) Resolve

func (p *NativeProvider) Resolve(_ context.Context, scope Scope, id ToolID) (Handle, bool, error)

Resolve returns the executable handle for one native tool.

type NativeTool

type NativeTool struct {
	Descriptor   Descriptor
	Call         NativeToolFunc
	Availability NativeAvailabilityFunc
}

NativeTool binds one descriptor to an in-process daemon handler.

type NativeToolFunc

type NativeToolFunc func(ctx context.Context, scope Scope, req CallRequest) (ToolResult, error)

NativeToolFunc is the daemon-compiled function signature for native tools.

type OperatorFailure

type OperatorFailure struct {
	Cause    string `json:"cause"`
	Recovery string `json:"recovery"`
}

OperatorFailure carries error detail explicitly authored for operator display.

type PermissionMode

type PermissionMode string

PermissionMode mirrors ACP's static approval modes without importing config.

const (
	// PermissionModeDenyAll requires explicit approval for every tool call.
	PermissionModeDenyAll PermissionMode = "deny-all"
	// PermissionModeApproveReads auto-approves read-only tools.
	PermissionModeApproveReads PermissionMode = "approve-reads"
	// PermissionModeApproveAll auto-approves otherwise allowed tools.
	PermissionModeApproveAll PermissionMode = "approve-all"
)

type PolicyEvaluator

type PolicyEvaluator interface {
	Evaluate(ctx context.Context, scope Scope, d Descriptor) (EffectiveToolDecision, error)
}

PolicyEvaluator computes the effective policy decision for a descriptor.

type PolicyInputResolver

type PolicyInputResolver interface {
	Resolve(ctx context.Context, scope Scope) (PolicyInputs, error)
}

PolicyInputResolver resolves effective policy inputs for the current caller scope.

func NewStaticPolicyInputResolver

func NewStaticPolicyInputResolver(inputs PolicyInputs) PolicyInputResolver

NewStaticPolicyInputResolver returns a resolver for callers with fixed policy inputs.

type PolicyInputs

type PolicyInputs struct {
	ToolsDisabled        bool
	SystemPermissionMode PermissionMode
	ExternalDefault      ExternalDefault
	ApprovalAvailable    bool
	TrustedSources       []SourceGrant
	AllowSources         []SourceGrant
	AllowTools           []ToolPattern
	AllowToolsets        []ToolsetID
	DenyTools            []ToolPattern
	Agent                AgentToolPolicy
	Session              SessionToolPolicy
}

PolicyInputs contains the config-neutral inputs for effective policy.

func DefaultPolicyInputs

func DefaultPolicyInputs() PolicyInputs

DefaultPolicyInputs returns conservative registry defaults.

type Provider

type Provider interface {
	ID() SourceRef
	List(ctx context.Context, scope Scope) ([]Descriptor, error)
	Resolve(ctx context.Context, scope Scope, id ToolID) (Handle, bool, error)
}

Provider contributes descriptors and executable handles from one source.

type ReasonCode

type ReasonCode string

ReasonCode is a deterministic machine-readable reason.

const (
	// ReasonIDEmpty reports an empty id.
	ReasonIDEmpty ReasonCode = "id_empty"
	// ReasonIDEmptySegment reports a missing namespace segment.
	ReasonIDEmptySegment ReasonCode = "id_empty_segment"
	// ReasonIDInvalidFormat reports a grammar violation.
	ReasonIDInvalidFormat ReasonCode = "id_invalid_format"
	// ReasonIDReservedConflict reports ambiguous reserved separator usage.
	ReasonIDReservedConflict ReasonCode = "reserved_conflict"
	// ReasonReservedNamespace reports an extension or external source claiming a reserved namespace.
	ReasonReservedNamespace ReasonCode = "reserved_namespace"
	// ReasonIDTooLong reports an id over the provider-safe limit.
	ReasonIDTooLong ReasonCode = "id_too_long"
	// ReasonDependencyMissing reports a missing dependency.
	ReasonDependencyMissing ReasonCode = "dependency_missing"
	// ReasonBackendUnhealthy reports an unhealthy backend.
	ReasonBackendUnhealthy ReasonCode = "backend_unhealthy"
	// ReasonBackendDead reports a durably suppressed backend awaiting recovery.
	ReasonBackendDead ReasonCode = "backend_dead"
	// ReasonBackendNotExecutable reports a descriptor without an executable backend.
	ReasonBackendNotExecutable ReasonCode = "backend_not_executable"
	// ReasonExtensionInactive reports an inactive extension.
	ReasonExtensionInactive ReasonCode = "extension_inactive"
	// ReasonExtensionRuntimeMismatch reports a manifest/runtime mismatch.
	ReasonExtensionRuntimeMismatch ReasonCode = "extension_runtime_mismatch"
	// ReasonExtensionCapabilityMissing reports a missing extension capability.
	ReasonExtensionCapabilityMissing ReasonCode = "extension_capability_missing"
	// ReasonExtensionSourceForbidden reports a denied or unconfigured extension source.
	ReasonExtensionSourceForbidden ReasonCode = "extension_source_forbidden"
	// ReasonExtensionNotInstalled reports a missing installed extension.
	ReasonExtensionNotInstalled ReasonCode = "extension_not_installed"
	// ReasonExtensionValidationFailed reports extension lifecycle validation failure.
	ReasonExtensionValidationFailed ReasonCode = "extension_validation_failed"
	// ReasonExtensionGitUnavailable reports that Git cannot be resolved by the daemon.
	ReasonExtensionGitUnavailable ReasonCode = "extension_git_unavailable"
	// ReasonExtensionGitVersionUnsupported reports that the resolved Git version is too old.
	ReasonExtensionGitVersionUnsupported ReasonCode = "extension_git_version_unsupported"
	// ReasonRuntimeDescriptorMissing reports a missing runtime descriptor.
	ReasonRuntimeDescriptorMissing ReasonCode = "runtime_descriptor_missing"
	// ReasonRuntimeDescriptorMismatch reports a runtime descriptor mismatch.
	ReasonRuntimeDescriptorMismatch ReasonCode = "runtime_descriptor_mismatch"
	// ReasonHandlerMissing reports a missing extension handler.
	ReasonHandlerMissing ReasonCode = "handler_missing"
	// ReasonMCPUnreachable reports an unreachable MCP server.
	ReasonMCPUnreachable ReasonCode = "mcp_unreachable"
	// ReasonMCPAuthUnconfigured reports missing MCP auth configuration.
	ReasonMCPAuthUnconfigured ReasonCode = "mcp_auth_unconfigured"
	// ReasonMCPAuthRequired reports that MCP login is required.
	ReasonMCPAuthRequired ReasonCode = "mcp_auth_required"
	// ReasonMCPAuthExpired reports expired MCP auth.
	ReasonMCPAuthExpired ReasonCode = "mcp_auth_expired"
	// ReasonMCPAuthInvalid reports invalid MCP auth.
	ReasonMCPAuthInvalid ReasonCode = "mcp_auth_invalid"
	// ReasonMCPAuthRefreshFailed reports failed MCP auth refresh.
	ReasonMCPAuthRefreshFailed ReasonCode = "mcp_auth_refresh_failed"
	// ReasonNetworkRawTokenRejected reports raw claim-token fields in network payloads.
	ReasonNetworkRawTokenRejected ReasonCode = "network_raw_token_rejected"
	// ReasonNetworkNotParticipating reports a Local session attempting a Network operation.
	ReasonNetworkNotParticipating ReasonCode = "not_participating"
	// ReasonSourceDisabled reports a disabled source.
	ReasonSourceDisabled ReasonCode = "source_disabled"
	// ReasonPolicyDenied reports a policy denial.
	ReasonPolicyDenied ReasonCode = "policy_denied"
	// ReasonVisibilityDenied reports a descriptor hidden from a scoped projection.
	ReasonVisibilityDenied ReasonCode = "visibility_denied"
	// ReasonApprovalRequired reports required approval.
	ReasonApprovalRequired ReasonCode = "approval_required"
	// ReasonApprovalUnreachable reports no available approval channel.
	ReasonApprovalUnreachable ReasonCode = "approval_unreachable"
	// ReasonApprovalTimedOut reports approval timeout.
	ReasonApprovalTimedOut ReasonCode = "approval_timed_out"
	// ReasonApprovalCanceled reports approval cancellation.
	ReasonApprovalCanceled ReasonCode = "approval_canceled"
	// ReasonApprovalTokenMissing reports a missing local approval token.
	ReasonApprovalTokenMissing ReasonCode = "approval_token_missing"
	// ReasonApprovalTokenExpired reports an expired local approval token.
	ReasonApprovalTokenExpired ReasonCode = "approval_token_expired"
	// ReasonApprovalTokenMismatch reports a local approval token binding mismatch.
	ReasonApprovalTokenMismatch ReasonCode = "approval_token_mismatch"
	// ReasonApprovalTokenReplayed reports a replayed local approval token.
	ReasonApprovalTokenReplayed ReasonCode = "approval_token_replayed"
	// ReasonApprovalSelfDenied reports an attempted self-approval of a human gate.
	ReasonApprovalSelfDenied ReasonCode = "approval_self_denied"
	// ReasonSessionDenied reports session lineage denial.
	ReasonSessionDenied ReasonCode = "session_denied"
	// ReasonGoalNotActive reports that no visible or reportable Goal exists for the caller session.
	ReasonGoalNotActive ReasonCode = "goal_not_active"
	// ReasonGoalReportConflict reports a report retry whose status or evidence differs.
	ReasonGoalReportConflict ReasonCode = "goal_report_conflict"
	// ReasonGoalEvidenceTooLarge reports inline Goal evidence above the public byte limit.
	ReasonGoalEvidenceTooLarge ReasonCode = "goal_evidence_too_large"
	// ReasonLoopVersionConflict reports a stale Loop definition compare-and-swap.
	ReasonLoopVersionConflict ReasonCode = "loop_version_conflict"
	// ReasonLoopSourceImmutable reports a mutation attempt against a read-only Loop source.
	ReasonLoopSourceImmutable ReasonCode = "loop_source_immutable"
	// ReasonLoopInvalidStatusTransition reports a Loop control requested from an unsupported run status.
	ReasonLoopInvalidStatusTransition ReasonCode = "invalid_status_transition"
	// ReasonLoopTerminalRun reports a Loop control requested after the run reached a terminal status.
	ReasonLoopTerminalRun ReasonCode = "terminal_loop_run"
	// ReasonLoopRunTerminal reports a node lifecycle verb rejected by terminal run truth.
	ReasonLoopRunTerminal ReasonCode = "run_terminal"
	// ReasonLoopNodeNotPaused reports a resume request against a node that is not paused.
	ReasonLoopNodeNotPaused ReasonCode = "node_not_paused"
	// ReasonLoopNodeNotQuarantined reports a requeue request against a node outside quarantine.
	ReasonLoopNodeNotQuarantined ReasonCode = "node_not_quarantined"
	// ReasonLoopAlreadyDecided reports a lifecycle mutation that lost to a durable winner.
	ReasonLoopAlreadyDecided ReasonCode = "already_decided"
	// ReasonScopeMismatch reports caller-supplied scope conflicting with trusted scope.
	ReasonScopeMismatch ReasonCode = "scope_mismatch"
	// ReasonWorkspaceAccessDenied reports a workspace-axis policy denial.
	ReasonWorkspaceAccessDenied ReasonCode = "workspace_access_denied"
	// ReasonMemorySubagentWriteDenied reports a sub-agent direct memory write denial.
	ReasonMemorySubagentWriteDenied ReasonCode = "memory_subagent_write_denied"
	// ReasonHookDenied reports hook denial.
	ReasonHookDenied ReasonCode = "hook_denied"
	// ReasonSchemaInvalid reports invalid JSON schema.
	ReasonSchemaInvalid ReasonCode = "schema_invalid"
	// ReasonConflictedID reports a canonical id conflict.
	ReasonConflictedID ReasonCode = "conflicted_id"
	// ReasonConflictedSanitizedName reports an external-name sanitization conflict.
	ReasonConflictedSanitizedName ReasonCode = "conflicted_sanitized_name"
	// ReasonResultBudgetExceeded reports a result budget violation.
	ReasonResultBudgetExceeded ReasonCode = "result_budget_exceeded"
	// ReasonResultPersistenceFailed reports inability to retain an oversized result.
	ReasonResultPersistenceFailed ReasonCode = "result_persistence_failed"
	// ReasonToolArtifactNotFound reports a missing, expired, or foreign-workspace artifact.
	ReasonToolArtifactNotFound ReasonCode = "tool_artifact_not_found"
	// ReasonToolArtifactCorrupt reports retained bytes that fail integrity verification.
	ReasonToolArtifactCorrupt ReasonCode = "tool_artifact_corrupt"
	// ReasonCallCanceled reports dispatch cancellation.
	ReasonCallCanceled ReasonCode = "call_canceled"
	// ReasonCallTimedOut reports dispatch deadline expiration.
	ReasonCallTimedOut ReasonCode = "call_timed_out"
	// ReasonSecretMetadata reports sensitive metadata in a public envelope.
	ReasonSecretMetadata ReasonCode = "secret_metadata"
	// ReasonToolsetUnknown reports a policy reference to an unknown toolset.
	ReasonToolsetUnknown ReasonCode = "toolset_unknown"
	// ReasonToolsetCycle reports recursive toolset membership.
	ReasonToolsetCycle ReasonCode = "toolset_cycle"
	// ReasonToolUnknown reports a policy reference to an unknown tool.
	ReasonToolUnknown ReasonCode = "tool_unknown"
	// ReasonConfigPathForbidden reports an agent-immutable config path.
	ReasonConfigPathForbidden ReasonCode = "config_path_forbidden"
	// ReasonConfigSecretPathForbidden reports a secret-bearing config path.
	ReasonConfigSecretPathForbidden ReasonCode = "config_secret_path_forbidden" // #nosec G101 -- reason code.
	// ReasonConfigTrustRootForbidden reports a trust-root config path.
	ReasonConfigTrustRootForbidden ReasonCode = "config_trust_root_forbidden"
	// ReasonConfigScopeNotAllowed reports an unsupported config write scope.
	ReasonConfigScopeNotAllowed ReasonCode = "config_scope_not_allowed"
	// ReasonConfigValidationFailed reports a validated config writer rejection.
	ReasonConfigValidationFailed ReasonCode = "config_validation_failed"
	// ReasonHookSourceImmutable reports a non-config hook source mutation attempt.
	ReasonHookSourceImmutable ReasonCode = "hook_source_immutable"
	// ReasonHookSecretInputForbidden reports a secret-bearing hook executor input.
	ReasonHookSecretInputForbidden ReasonCode = "hook_secret_input_forbidden"
	// ReasonHookValidationFailed reports a hook normalization or validation rejection.
	ReasonHookValidationFailed ReasonCode = "hook_validation_failed"
	// ReasonAutomationScopeForbidden reports an automation scope or source mutation denial.
	ReasonAutomationScopeForbidden ReasonCode = "automation_scope_forbidden"
	// ReasonAutomationSecretInputForbidden reports forbidden raw automation secret material.
	ReasonAutomationSecretInputForbidden ReasonCode = "automation_secret_input_forbidden" // #nosec G101 -- reason code.
	// ReasonAutomationValidationFailed reports automation manager or model validation rejection.
	ReasonAutomationValidationFailed ReasonCode = "automation_validation_failed"
	// ReasonAutonomySessionRequired reports a session-bound autonomy call without a caller session.
	ReasonAutonomySessionRequired ReasonCode = "autonomy_session_required"
	// ReasonAutonomyNoActiveLease reports no active run lease for the caller session.
	ReasonAutonomyNoActiveLease ReasonCode = "autonomy_no_active_lease"
	// ReasonAutonomyForeignRun reports a run id outside the caller session's active lease.
	ReasonAutonomyForeignRun ReasonCode = "autonomy_foreign_run"
	// ReasonAutonomyLeaseExpired reports an expired or non-active caller lease.
	ReasonAutonomyLeaseExpired ReasonCode = "autonomy_lease_expired"
	// ReasonAutonomyLeaseAlreadyHeld reports multiple active leases for one session.
	ReasonAutonomyLeaseAlreadyHeld ReasonCode = "autonomy_lease_already_held"
	// ReasonAutonomyWorkspaceCapacity reports a workspace whose active-run capacity is full.
	ReasonAutonomyWorkspaceCapacity ReasonCode = "autonomy_workspace_capacity"
)

func MCPAuthStatusReason

func MCPAuthStatusReason(status MCPAuthStatus) (ReasonCode, bool)

MCPAuthStatusReason maps redacted MCP auth status to registry reason codes.

func ReasonOf

func ReasonOf(err error) (ReasonCode, bool)

ReasonOf extracts the primary deterministic reason from an error.

func (ReasonCode) Validate

func (r ReasonCode) Validate(field string) error

Validate ensures the reason code is documented.

type Redaction

type Redaction struct {
	Path   string     `json:"path"`
	Reason ReasonCode `json:"reason"`
	Bytes  int64      `json:"bytes,omitempty"`
}

Redaction records a redaction applied before a result crosses surfaces.

type Registry

type Registry interface {
	List(ctx context.Context, scope Scope) ([]ToolView, error)
	Search(ctx context.Context, scope Scope, q SearchQuery) ([]ToolView, error)
	Get(ctx context.Context, scope Scope, id ToolID) (ToolView, error)
	Call(ctx context.Context, scope Scope, req CallRequest) (ToolResult, error)
}

Registry owns tool discovery and dispatch for all surfaces.

type RegistryOption

type RegistryOption func(*RuntimeRegistry)

RegistryOption configures a runtime registry.

func WithApprovalBridge

func WithApprovalBridge(bridge ApprovalBridge) RegistryOption

WithApprovalBridge wires approval-required calls into a session permission path.

func WithCallInputAuthorizer

func WithCallInputAuthorizer(authorizer CallInputAuthorizer) RegistryOption

WithCallInputAuthorizer wires authorization of the final bound call input.

func WithCallInputBinder

func WithCallInputBinder(binder CallInputBinder) RegistryOption

WithCallInputBinder wires trusted scope binding into every dispatched call.

func WithDefaultMaxResultBytes

func WithDefaultMaxResultBytes(maxBytes int64) RegistryOption

WithDefaultMaxResultBytes sets the fallback result budget for silent descriptors.

func WithHookRunner

func WithHookRunner(hooks HookRunner) RegistryOption

WithHookRunner wires registry-owned call hooks into dispatch.

func WithPolicyEvaluator

func WithPolicyEvaluator(evaluator PolicyEvaluator) RegistryOption

WithPolicyEvaluator injects a custom evaluator for tests or composition roots.

func WithPolicyInputResolver

func WithPolicyInputResolver(resolver PolicyInputResolver, toolsets ToolsetCatalog) RegistryOption

WithPolicyInputResolver configures a scope-aware effective policy evaluator.

func WithPolicyInputs

func WithPolicyInputs(inputs PolicyInputs, toolsets ToolsetCatalog) RegistryOption

WithPolicyInputs configures the default effective policy evaluator.

func WithProviders

func WithProviders(providers ...Provider) RegistryOption

WithProviders registers provider sources for indexing.

func WithResultProcessor

func WithResultProcessor(processor ResultProcessor) RegistryOption

WithResultProcessor wires result redaction, offload, and budget enforcement.

func WithSensitiveResultFields

func WithSensitiveResultFields(fields ...string) RegistryOption

WithSensitiveResultFields configures extra field names redacted from results.

func WithToolEventSink

func WithToolEventSink(events ToolEventSink) RegistryOption

WithToolEventSink wires structured dispatch events into observability.

func WithWorkspaceAccessPolicy

func WithWorkspaceAccessPolicy(policy workspaceaccess.Policy) RegistryOption

WithWorkspaceAccessPolicy wires workspace-envelope authorization into dispatch.

func WithWorkspaceIDResolver

func WithWorkspaceIDResolver(resolver WorkspaceIDResolver) RegistryOption

WithWorkspaceIDResolver wires workspace-reference canonicalization into dispatch.

type ResultProcessor

type ResultProcessor interface {
	Sanitize(ctx context.Context, d Descriptor, result ToolResult) (ToolResult, error)
	Finalize(ctx context.Context, scope Scope, d Descriptor, result ToolResult) (ToolResult, error)
}

ResultProcessor sanitizes provider output before hooks and finalizes the public result once afterward.

type RiskClass

type RiskClass string

RiskClass classifies the safety posture of a tool.

const (
	// RiskRead marks read-only local inspection.
	RiskRead RiskClass = "read"
	// RiskMutating marks state-changing behavior.
	RiskMutating RiskClass = "mutating"
	// RiskOpenWorld marks access to arbitrary external state.
	RiskOpenWorld RiskClass = "open_world"
	// RiskDestructive marks destructive or irreversible behavior.
	RiskDestructive RiskClass = "destructive"
)

func (RiskClass) Validate

func (r RiskClass) Validate(field string) error

Validate ensures the risk class is documented.

type RuntimeRegistry

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

RuntimeRegistry indexes providers and produces scoped projections.

func NewRegistry

func NewRegistry(opts ...RegistryOption) (*RuntimeRegistry, error)

NewRegistry validates providers and returns a deterministic registry.

func (*RuntimeRegistry) BootstrapSessionCall

func (r *RuntimeRegistry) BootstrapSessionCall(
	ctx context.Context,
	scope Scope,
	req CallRequest,
) (ToolResult, error)

BootstrapSessionCall dispatches through the complete registry to enforce policy and conflict checks.

func (*RuntimeRegistry) BootstrapSessionProjection

func (r *RuntimeRegistry) BootstrapSessionProjection(ctx context.Context, scope Scope) ([]ToolView, error)

BootstrapSessionProjection returns all callable tools from providers that do not defer discovery.

func (*RuntimeRegistry) Call

func (r *RuntimeRegistry) Call(ctx context.Context, scope Scope, req CallRequest) (ToolResult, error)

Call runs the central provider-agnostic registry dispatch pipeline.

func (*RuntimeRegistry) DiagnosticGet

func (r *RuntimeRegistry) DiagnosticGet(ctx context.Context, scope Scope, id ToolID) (ToolView, error)

DiagnosticGet returns one diagnostic projection row even when the tool is not callable.

func (*RuntimeRegistry) DiagnosticProjection

func (r *RuntimeRegistry) DiagnosticProjection(ctx context.Context, scope Scope) ([]ToolView, error)

DiagnosticProjection returns all indexed tools with effective diagnostics for the supplied scope.

func (*RuntimeRegistry) DiagnosticSearch

func (r *RuntimeRegistry) DiagnosticSearch(ctx context.Context, scope Scope, q SearchQuery) ([]ToolView, error)

DiagnosticSearch filters the diagnostic projection without hiding denied tools.

func (*RuntimeRegistry) Get

func (r *RuntimeRegistry) Get(ctx context.Context, scope Scope, id ToolID) (ToolView, error)

Get returns one tool from the scoped projection.

func (*RuntimeRegistry) GetToolset

func (r *RuntimeRegistry) GetToolset(ctx context.Context, scope Scope, id ToolsetID) (ToolsetView, error)

GetToolset returns one named toolset with expansion diagnostics for the supplied scope.

func (*RuntimeRegistry) List

func (r *RuntimeRegistry) List(ctx context.Context, scope Scope) ([]ToolView, error)

List returns an operator or session projection based on Scope.Operator.

func (*RuntimeRegistry) ListToolsets

func (r *RuntimeRegistry) ListToolsets(ctx context.Context, scope Scope) ([]ToolsetView, error)

ListToolsets returns named toolsets with expansion diagnostics for the supplied scope.

func (*RuntimeRegistry) LookupToolMetadata

func (r *RuntimeRegistry) LookupToolMetadata(
	workspaceID string,
	toolID string,
) (toolmeta.DescriptorMetadata, bool)

LookupToolMetadata returns presentation metadata discovered by the runtime registry.

func (*RuntimeRegistry) OperatorProjection

func (r *RuntimeRegistry) OperatorProjection(ctx context.Context, scope Scope) ([]ToolView, error)

OperatorProjection returns all registered tools with diagnostics.

func (*RuntimeRegistry) Search

func (r *RuntimeRegistry) Search(ctx context.Context, scope Scope, q SearchQuery) ([]ToolView, error)

Search filters the scoped projection by descriptor text and provenance.

func (*RuntimeRegistry) SessionProjection

func (r *RuntimeRegistry) SessionProjection(ctx context.Context, scope Scope) ([]ToolView, error)

SessionProjection returns only callable tools for the effective session.

type Scope

type Scope struct {
	WorkspaceID string `json:"workspace_id,omitempty"`
	SessionID   string `json:"session_id,omitempty"`
	AgentName   string `json:"agent_name,omitempty"`
	ActorKind   string `json:"actor_kind,omitempty"`
	Operator    bool   `json:"operator,omitempty"`
}

Scope identifies the caller context used for projections and dispatch.

type SearchQuery

type SearchQuery struct {
	Query string `json:"query"`
	Limit int    `json:"limit,omitempty"`
}

SearchQuery describes a registry search request.

type SessionToolPolicy

type SessionToolPolicy struct {
	Enforced bool     `json:"enforced"`
	Tools    []ToolID `json:"tools,omitempty"`
}

SessionToolPolicy captures concrete resolved lineage atoms.

type SourceGrant

type SourceGrant struct {
	Kind  SourceKind `json:"kind"`
	Owner string     `json:"owner"`
}

SourceGrant grants policy to one descriptor source owner.

func ParseSourceGrant

func ParseSourceGrant(raw string) (SourceGrant, error)

ParseSourceGrant parses kind:owner source policy entries.

func (SourceGrant) Match

func (g SourceGrant) Match(source SourceRef) bool

Match reports whether the grant covers the descriptor source.

func (SourceGrant) Validate

func (g SourceGrant) Validate(field string) error

Validate ensures the grant can match a source deterministically.

type SourceKind

type SourceKind string

SourceKind identifies the provenance class for a descriptor.

const (
	// SourceBuiltin marks daemon-defined tools.
	SourceBuiltin SourceKind = "builtin"
	// SourceMCP marks tools discovered from MCP servers.
	SourceMCP SourceKind = "mcp"
	// SourceExtension marks tools provided by extensions.
	SourceExtension SourceKind = "extension"
	// SourceDynamic marks future runtime-assembled tools.
	SourceDynamic SourceKind = "dynamic"
)

func (SourceKind) String

func (k SourceKind) String() string

String returns the stable source kind text.

func (SourceKind) Validate

func (k SourceKind) Validate(field string) error

Validate ensures the source kind is documented.

type SourceRef

type SourceRef struct {
	Kind            SourceKind `json:"kind"`
	Owner           string     `json:"owner"`
	RawServerName   string     `json:"raw_server_name,omitempty"`
	RawToolName     string     `json:"raw_tool_name,omitempty"`
	ResourceID      string     `json:"resource_id,omitempty"`
	ResourceVersion string     `json:"resource_version,omitempty"`
	WorkspaceID     string     `json:"workspace_id,omitempty"`
	Scope           string     `json:"scope,omitempty"`
}

SourceRef preserves provenance without creating alternate tool identities.

func BuiltinSource

func BuiltinSource() SourceRef

BuiltinSource returns the provenance shared by daemon-compiled Compozy tools.

func (SourceRef) Validate

func (s SourceRef) Validate(field string) error

Validate ensures source provenance can support deterministic diagnostics.

type Tool

type Tool struct {
	ID           ToolID     `json:"id"`
	Backend      BackendRef `json:"backend"`
	DisplayTitle string     `json:"display_title,omitempty"`
	*ToolPresentation
	Description         string          `json:"description"`
	InputSchema         json.RawMessage `json:"input_schema"`
	OutputSchema        json.RawMessage `json:"output_schema,omitempty"`
	InputSchemaDigest   string          `json:"input_schema_digest"`
	OutputSchemaDigest  string          `json:"output_schema_digest,omitempty"`
	Source              SourceRef       `json:"source"`
	Visibility          Visibility      `json:"visibility"`
	Risk                RiskClass       `json:"risk"`
	ReadOnly            bool            `json:"read_only"`
	Destructive         bool            `json:"destructive"`
	OpenWorld           bool            `json:"open_world"`
	RequiresInteraction bool            `json:"requires_interaction"`
	ConcurrencySafe     bool            `json:"concurrency_safe"`
	MaxResultBytes      int64           `json:"max_result_bytes,omitempty"`
	Toolsets            []ToolsetID     `json:"toolsets,omitempty"`
	Tags                []string        `json:"tags,omitempty"`
	SearchHints         []string        `json:"search_hints,omitempty"`
}

Tool is the cold desired-state resource spec for a registry tool.

func (Tool) Descriptor

func (t Tool) Descriptor() Descriptor

Descriptor converts a cold resource into the runtime descriptor shape.

func (Tool) Presentation

func (t Tool) Presentation() ToolPresentation

Presentation returns a nil-safe copy of the cold tool presentation metadata.

func (Tool) Validate

func (t Tool) Validate() error

Validate ensures the cold resource can normalize into a descriptor.

type ToolArtifactPage

type ToolArtifactPage struct {
	Artifact   ArtifactRef `json:"artifact"`
	Offset     int64       `json:"offset"`
	Bytes      int64       `json:"bytes"`
	TotalBytes int64       `json:"total_bytes"`
	DataBase64 string      `json:"data_base64"`
	NextOffset int64       `json:"next_offset"`
	EOF        bool        `json:"eof"`
}

ToolArtifactPage is one exact byte range from a retained result envelope.

type ToolArtifactRetention

type ToolArtifactRetention struct {
	MaxCount int
	MaxBytes int64
	MaxAge   time.Duration
}

ToolArtifactRetention defines global disk bounds for workspace-scoped artifacts.

func (ToolArtifactRetention) Validate

func (r ToolArtifactRetention) Validate() error

Validate ensures retention always establishes finite positive bounds.

type ToolArtifactStore

type ToolArtifactStore interface {
	Put(ctx context.Context, workspaceID string, content []byte) (ArtifactRef, error)
	ReadPage(
		ctx context.Context,
		workspaceID string,
		uri string,
		offset int64,
		limit int64,
	) (ToolArtifactPage, error)
	Sweep(ctx context.Context) error
}

ToolArtifactStore persists and pages workspace-scoped result envelopes.

type ToolArtifactSweeper

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

ToolArtifactSweeper applies age retention even when no artifact calls occur.

func NewToolArtifactSweeper

func NewToolArtifactSweeper(
	store ToolArtifactStore,
	interval time.Duration,
	onError func(error),
) *ToolArtifactSweeper

NewToolArtifactSweeper builds a joined periodic retention worker.

func (*ToolArtifactSweeper) Shutdown

func (w *ToolArtifactSweeper) Shutdown(ctx context.Context) error

Shutdown cancels and joins the periodic sweep worker.

func (*ToolArtifactSweeper) Start

func (w *ToolArtifactSweeper) Start(ctx context.Context) error

Start begins periodic sweeps until shutdown or parent cancellation.

type ToolCallEvent

type ToolCallEvent struct {
	Kind                 ToolCallEventKind `json:"kind"`
	ToolID               ToolID            `json:"tool_id"`
	DisplayTitle         string            `json:"display_title,omitempty"`
	SourceKind           SourceKind        `json:"source_kind,omitempty"`
	SourceOwner          string            `json:"source_owner,omitempty"`
	WorkspaceID          string            `json:"workspace_id,omitempty"`
	SessionID            string            `json:"session_id,omitempty"`
	AgentName            string            `json:"agent_name,omitempty"`
	Risk                 RiskClass         `json:"risk,omitempty"`
	ReadOnly             bool              `json:"read_only"`
	Destructive          bool              `json:"destructive"`
	OpenWorld            bool              `json:"open_world"`
	ApprovalMode         string            `json:"approval_mode,omitempty"`
	Decision             string            `json:"decision,omitempty"`
	ReasonCodes          []ReasonCode      `json:"reason_codes,omitempty"`
	DurationMS           int64             `json:"duration_ms,omitempty"`
	ResultBytes          int64             `json:"result_bytes,omitempty"`
	Truncated            bool              `json:"truncated"`
	CorrelationID        string            `json:"correlation_id,omitempty"`
	ErrorCode            ErrorCode         `json:"error_code,omitempty"`
	InputDigest          string            `json:"input_digest,omitempty"`
	RedactedInputFields  []string          `json:"redacted_input_fields,omitempty"`
	ResultDigest         string            `json:"result_digest,omitempty"`
	ResultRedactionPaths []string          `json:"result_redaction_paths,omitempty"`
}

ToolCallEvent is the redacted dispatch event envelope emitted by Registry.Call.

type ToolCallEventKind

type ToolCallEventKind string

ToolCallEventKind identifies one structured dispatch observability event.

const (
	// ToolCallStarted reports that dispatch passed identity resolution and began.
	ToolCallStarted ToolCallEventKind = "tool.call_started"
	// ToolCallCompleted reports successful provider execution and result limiting.
	ToolCallCompleted ToolCallEventKind = "tool.call_completed"
	// ToolCallFailed reports schema, hook, backend, cancellation, or timeout failures.
	ToolCallFailed ToolCallEventKind = "tool.call_failed"
	// ToolCallDenied reports policy, availability, approval, conflict, or hook denial.
	ToolCallDenied ToolCallEventKind = "tool.call_denied"
	// ToolResultTruncated reports deterministic result truncation.
	ToolResultTruncated ToolCallEventKind = "tool.result_truncated"
)

type ToolContent

type ToolContent struct {
	Type     string                     `json:"type"`
	Text     string                     `json:"text,omitempty"`
	Data     json.RawMessage            `json:"data,omitempty"`
	MIMEType string                     `json:"mime_type,omitempty"`
	Metadata map[string]json.RawMessage `json:"metadata,omitempty"`
}

ToolContent is one typed content block returned by a tool.

type ToolError

type ToolError struct {
	Code          ErrorCode        `json:"code"`
	ToolID        ToolID           `json:"tool_id,omitempty"`
	Message       string           `json:"message"`
	ReasonCodes   []ReasonCode     `json:"reason_codes,omitempty"`
	Operator      *OperatorFailure `json:"operator,omitempty"`
	PartialResult *ToolResult      `json:"partial_result,omitempty"`
	Err           error            `json:"-"`
}

ToolError carries stable reason codes with a wrapped cause.

func NewOperatorToolError

func NewOperatorToolError(
	code ErrorCode,
	id ToolID,
	message string,
	err error,
	cause string,
	recovery string,
	reasons ...ReasonCode,
) *ToolError

NewOperatorToolError builds a tool error with operator-safe cause and recovery text.

func NewToolError

func NewToolError(code ErrorCode, id ToolID, message string, err error, reasons ...ReasonCode) *ToolError

NewToolError builds a stable tool error envelope.

func (*ToolError) Error

func (e *ToolError) Error() string

Error returns the public error message.

func (*ToolError) Unwrap

func (e *ToolError) Unwrap() error

Unwrap returns the wrapped cause.

func (*ToolError) WithPartialResult

func (e *ToolError) WithPartialResult(result ToolResult) *ToolError

WithPartialResult returns a cloned error carrying a redacted bounded result preview.

type ToolEventData

type ToolEventData struct {
	StartedAt time.Time
	Input     json.RawMessage
	Result    ToolResult
	Err       error
}

ToolEventData carries per-outcome event details.

type ToolEventSink

type ToolEventSink interface {
	EmitToolEvent(ctx context.Context, event ToolCallEvent) error
}

ToolEventSink receives redacted dispatch events from the registry.

type ToolID

type ToolID string

ToolID is the canonical public tool identity.

const (
	// ToolIDExtensionsList lists installed extensions through the extension registry.
	ToolIDExtensionsList ToolID = "compozy__extensions_list"
	// ToolIDExtensionsInfo reads one installed extension status.
	ToolIDExtensionsInfo ToolID = "compozy__extensions_info"
	// ToolIDExtensionsInventory reads shipped and live extension resources.
	ToolIDExtensionsInventory ToolID = "compozy__extensions_inventory"
	// ToolIDExtensionsPreview previews an extension enable without changing state.
	ToolIDExtensionsPreview ToolID = "compozy__extensions_preview"
	// ToolIDExtensionsInstall installs one extension through a managed local or marketplace source.
	ToolIDExtensionsInstall ToolID = "compozy__extensions_install"
	// ToolIDExtensionsUpdate updates one or more marketplace-installed extensions.
	ToolIDExtensionsUpdate ToolID = "compozy__extensions_update"
	// ToolIDExtensionsRemove removes one managed installed extension.
	ToolIDExtensionsRemove ToolID = "compozy__extensions_remove"
	// ToolIDExtensionsEnable enables one installed extension.
	ToolIDExtensionsEnable ToolID = "compozy__extensions_enable"
	// ToolIDExtensionsDisable disables one installed extension.
	ToolIDExtensionsDisable ToolID = "compozy__extensions_disable"
	// ToolIDExtensionsInit scaffolds one extension project from an embedded template.
	ToolIDExtensionsInit ToolID = "compozy__extensions_init"
	// ToolIDExtensionsBuild builds one immutable extension generation.
	ToolIDExtensionsBuild ToolID = "compozy__extensions_build"
	// ToolIDExtensionsValidate validates one extension bundle without executing it.
	ToolIDExtensionsValidate ToolID = "compozy__extensions_validate"
	// ToolIDExtensionsDev links one immutable generation to the trusted workspace.
	ToolIDExtensionsDev ToolID = "compozy__extensions_dev"
	// ToolIDExtensionsReload reloads one trusted workspace extension generation.
	ToolIDExtensionsReload ToolID = "compozy__extensions_reload"
	// ToolIDExtensionsLogs reads redacted logs for the trusted extension instance.
	ToolIDExtensionsLogs ToolID = "compozy__extensions_logs"
	// ToolIDExtensionsSearch discovers extensions across curated and GitHub sources.
	ToolIDExtensionsSearch ToolID = "compozy__extensions_search"
	// ToolIDExtensionsProvenance reads persisted install provenance.
	ToolIDExtensionsProvenance ToolID = "compozy__extensions_provenance"
	// ToolIDExtensionsPublish publishes an immutable generation to GitHub Releases.
	ToolIDExtensionsPublish ToolID = "compozy__extensions_publish"
)
const (
	// ToolIDToolList lists tools in the caller's effective registry projection.
	ToolIDToolList ToolID = "compozy__tool_list"
	// ToolIDToolSearch searches tools in the caller's effective registry projection.
	ToolIDToolSearch ToolID = "compozy__tool_search"
	// ToolIDToolInfo reads one tool descriptor and diagnostics view.
	ToolIDToolInfo ToolID = "compozy__tool_info"
	// ToolIDToolApprovalsSet sets one explicit wider native-tool approval decision.
	ToolIDToolApprovalsSet ToolID = "compozy__tool_approvals_set"
	// ToolIDToolApprovalsList lists durable native-tool approval decisions in one workspace.
	ToolIDToolApprovalsList ToolID = "compozy__tool_approvals_list"
	// ToolIDToolApprovalsRevoke revokes one durable native-tool approval decision.
	ToolIDToolApprovalsRevoke ToolID = "compozy__tool_approvals_revoke"
	// ToolIDClarify asks the user one bounded session-scoped question.
	ToolIDClarify ToolID = "compozy__clarify"
	// ToolIDSkillList lists skills through the existing skill registry.
	ToolIDSkillList ToolID = "compozy__skill_list"
	// ToolIDSkillSearch searches skills through the existing skill registry.
	ToolIDSkillSearch ToolID = "compozy__skill_search"
	// ToolIDSkillView reads one skill and its verified body.
	ToolIDSkillView ToolID = "compozy__skill_view"
	// ToolIDCommandList lists the unified command catalog for one session.
	ToolIDCommandList ToolID = "compozy__command_list"
	// ToolIDNetworkPeers lists visible network peers.
	ToolIDNetworkPeers ToolID = "compozy__network_peers"
	// ToolIDNetworkStatus reads daemon-owned network runtime status.
	ToolIDNetworkStatus ToolID = "compozy__network_status"
	// ToolIDNetworkUsage reads bounded workspace-scoped network wake usage.
	ToolIDNetworkUsage ToolID = "compozy__network_usage"
	// ToolIDNetworkChannels lists active Compozy network channels.
	ToolIDNetworkChannels ToolID = "compozy__network_channels"
	// ToolIDNetworkInbox reads queued inbound network messages for one local session.
	ToolIDNetworkInbox ToolID = "compozy__network_inbox"
	// ToolIDNetworkSend sends one network message through the existing network manager.
	ToolIDNetworkSend ToolID = "compozy__network_send"
	// ToolIDNetworkChannelCreate registers one Compozy network channel with a stated purpose.
	ToolIDNetworkChannelCreate ToolID = "compozy__network_channel_create"
	// ToolIDNetworkChannelUpdate updates one Compozy network channel delivery policy.
	ToolIDNetworkChannelUpdate ToolID = "compozy__network_channel_update"
	// ToolIDNetworkSubscriptions lists Compozy network delivery preferences.
	ToolIDNetworkSubscriptions ToolID = "compozy__network_subscriptions"
	// ToolIDNetworkSubscribe sets one Compozy network delivery preference to full delivery.
	ToolIDNetworkSubscribe ToolID = "compozy__network_subscribe"
	// ToolIDNetworkMute mutes one Compozy network delivery preference.
	ToolIDNetworkMute ToolID = "compozy__network_mute"
	// ToolIDNetworkUnmute removes one Compozy network delivery preference.
	ToolIDNetworkUnmute ToolID = "compozy__network_unmute"
	// ToolIDNetworkThreads lists public network thread summaries.
	ToolIDNetworkThreads ToolID = "compozy__network_threads"
	// ToolIDNetworkThreadMessages reads messages in one public network thread.
	ToolIDNetworkThreadMessages ToolID = "compozy__network_thread_messages"
	// ToolIDNetworkDirects lists direct-room summaries.
	ToolIDNetworkDirects ToolID = "compozy__network_directs"
	// ToolIDNetworkDirectResolve creates or returns one deterministic direct room.
	ToolIDNetworkDirectResolve ToolID = "compozy__network_direct_resolve"
	// ToolIDNetworkDirectMessages reads messages in one direct room.
	ToolIDNetworkDirectMessages ToolID = "compozy__network_direct_messages"
	// ToolIDNetworkWork reads one network work lifecycle row.
	ToolIDNetworkWork ToolID = "compozy__network_work"
	// ToolIDSessionList lists runtime sessions.
	ToolIDSessionList ToolID = "compozy__session_list"
	// ToolIDSessionArchive archives one stopped runtime session.
	ToolIDSessionArchive ToolID = "compozy__session_archive"
	// ToolIDSessionUnarchive restores one archived runtime session.
	ToolIDSessionUnarchive ToolID = "compozy__session_unarchive"
	// ToolIDSessionCreate accepts one unbound logical user session.
	ToolIDSessionCreate ToolID = "compozy__session_create"
	// ToolIDSessionPrompt submits one prompt with an optional runtime snapshot.
	ToolIDSessionPrompt ToolID = "compozy__session_prompt"
	// ToolIDSessionRewind archives a conversation suffix and restarts the session context.
	ToolIDSessionRewind ToolID = "compozy__session_rewind"
	// ToolIDSessionRuntimeSet selects the default runtime for future prompts.
	ToolIDSessionRuntimeSet ToolID = "compozy__session_runtime_set"
	// ToolIDSessionRuntimeClear clears the default runtime for future prompts.
	ToolIDSessionRuntimeClear ToolID = "compozy__session_runtime_clear"
	// ToolIDSessionInputsList lists durable pending session input in dispatch order.
	ToolIDSessionInputsList ToolID = "compozy__session_inputs_list"
	// ToolIDSessionInputReplace atomically replaces one queued session input.
	ToolIDSessionInputReplace ToolID = "compozy__session_input_replace"
	// ToolIDSessionInputCancel cancels one queued session input.
	ToolIDSessionInputCancel ToolID = "compozy__session_input_cancel"
	// ToolIDSessionInputPromote atomically promotes queued input to steering.
	ToolIDSessionInputPromote ToolID = "compozy__session_input_promote"
	// ToolIDSessionStatus reads one runtime session snapshot.
	ToolIDSessionStatus ToolID = "compozy__session_status"
	// ToolIDSessionHistory reads grouped turn history for one session.
	ToolIDSessionHistory ToolID = "compozy__session_history"
	// ToolIDSessionEvents reads persisted events for one session.
	ToolIDSessionEvents ToolID = "compozy__session_events"
	// ToolIDSessionDescribe reads a composite read-only session description.
	ToolIDSessionDescribe ToolID = "compozy__session_describe"
	// ToolIDSessionHealth reads metadata-only session health and wake eligibility.
	ToolIDSessionHealth ToolID = "compozy__session_health"
	// ToolIDAgentHeartbeatStatus reads resolved Heartbeat policy, wake state, health, and wake audit.
	ToolIDAgentHeartbeatStatus ToolID = "compozy__agent_heartbeat_status"
	// ToolIDAgentHeartbeatWake requests one managed advisory Heartbeat wake decision.
	ToolIDAgentHeartbeatWake ToolID = "compozy__agent_heartbeat_wake"
	// ToolIDWorkspaceList lists registered workspaces.
	ToolIDWorkspaceList ToolID = "compozy__workspace_list"
	// ToolIDWorkspaceInfo reads one registered workspace record.
	ToolIDWorkspaceInfo ToolID = "compozy__workspace_info"
	// ToolIDWorkspaceDescribe reads one resolved workspace detail projection.
	ToolIDWorkspaceDescribe ToolID = "compozy__workspace_describe"
	// ToolIDAgentCreate authors one AGENT.md definition at global or workspace scope.
	ToolIDAgentCreate ToolID = "compozy__agent_create"
	// ToolIDProviderModelsList lists the daemon provider model catalog.
	ToolIDProviderModelsList ToolID = "compozy__provider_models_list"
	// ToolIDProviderModelsRefresh refreshes one or more provider model catalog sources.
	ToolIDProviderModelsRefresh ToolID = "compozy__provider_models_refresh"
	// ToolIDProviderModelsStatus reads provider model catalog source status.
	ToolIDProviderModelsStatus ToolID = "compozy__provider_models_status"
	// ToolIDProviderModelsCurate mutates one provider model's global curation metadata.
	ToolIDProviderModelsCurate ToolID = "compozy__provider_models_curate"
	// ToolIDMemoryList lists memory headers visible for a scope.
	ToolIDMemoryList ToolID = "compozy__memory_list"
	// ToolIDMemoryShow reads one memory document through the current memory store.
	ToolIDMemoryShow ToolID = "compozy__memory_show"
	// ToolIDMemorySearch recalls memory documents through the active memory provider.
	ToolIDMemorySearch ToolID = "compozy__memory_search"
	// ToolIDMemoryPropose submits a controller-backed memory proposal.
	ToolIDMemoryPropose ToolID = "compozy__memory_propose"
	// ToolIDMemoryNote records a controller-backed ad-hoc memory note.
	ToolIDMemoryNote ToolID = "compozy__memory_note"
	// ToolIDMemoryHealth reads Memory v2 health and derived catalog state.
	ToolIDMemoryHealth ToolID = "compozy__memory_health"
	// ToolIDMemoryScopeShow reports effective Memory v2 scope resolution.
	ToolIDMemoryScopeShow ToolID = "compozy__memory_scope_show"
	// ToolIDMemoryAdminHistory lists Memory v2 operation history without reusing the removed legacy ID.
	ToolIDMemoryAdminHistory ToolID = "compozy__memory_admin_history"
	// ToolIDMemoryReindex rebuilds Memory v2 derived indexes.
	ToolIDMemoryReindex ToolID = "compozy__memory_reindex"
	// ToolIDMemoryPromote promotes one Memory v2 entry across scopes.
	ToolIDMemoryPromote ToolID = "compozy__memory_promote"
	// ToolIDMemoryReset resets derived Memory v2 state.
	ToolIDMemoryReset ToolID = "compozy__memory_reset"
	// ToolIDMemoryReload invalidates future Memory v2 snapshots.
	ToolIDMemoryReload ToolID = "compozy__memory_reload"
	// ToolIDMemoryDecisionsList lists Memory v2 controller decisions.
	ToolIDMemoryDecisionsList ToolID = "compozy__memory_decisions_list"
	// ToolIDMemoryDecisionsShow reads one Memory v2 controller decision.
	ToolIDMemoryDecisionsShow ToolID = "compozy__memory_decisions_show"
	// ToolIDMemoryDecisionsRevert reverts one applied Memory v2 controller decision.
	ToolIDMemoryDecisionsRevert ToolID = "compozy__memory_decisions_revert"
	// ToolIDMemoryRecallTrace reads one materialized Memory v2 recall trace.
	ToolIDMemoryRecallTrace ToolID = "compozy__memory_recall_trace"
	// ToolIDMemoryDreamStatus reads live Memory v2 dreaming status.
	ToolIDMemoryDreamStatus ToolID = "compozy__memory_dream_status"
	// ToolIDMemoryDreamList lists Memory v2 dreaming run records.
	ToolIDMemoryDreamList ToolID = "compozy__memory_dream_list"
	// ToolIDMemoryDreamShow reads one Memory v2 dreaming run record.
	ToolIDMemoryDreamShow ToolID = "compozy__memory_dream_show"
	// ToolIDMemoryDreamTrigger triggers Memory v2 dream consolidation.
	ToolIDMemoryDreamTrigger ToolID = "compozy__memory_dream_trigger"
	// ToolIDMemoryDreamRetry retries Memory v2 dream consolidation.
	ToolIDMemoryDreamRetry ToolID = "compozy__memory_dream_retry"
	// ToolIDMemoryDailyList lists Memory v2 daily operation logs.
	ToolIDMemoryDailyList ToolID = "compozy__memory_daily_list"
	// ToolIDMemoryExtractorStatus reads Memory v2 extractor queue status.
	ToolIDMemoryExtractorStatus ToolID = "compozy__memory_extractor_status"
	// ToolIDMemoryExtractorFailures lists Memory v2 extractor failures.
	ToolIDMemoryExtractorFailures ToolID = "compozy__memory_extractor_failures"
	// ToolIDMemoryExtractorRetry retries Memory v2 extractor failures.
	ToolIDMemoryExtractorRetry ToolID = "compozy__memory_extractor_retry"
	// ToolIDMemoryExtractorDrain drains the Memory v2 extractor queue.
	ToolIDMemoryExtractorDrain ToolID = "compozy__memory_extractor_drain"
	// ToolIDMemoryProviderList lists Memory v2 providers.
	ToolIDMemoryProviderList ToolID = "compozy__memory_provider_list"
	// ToolIDMemoryProviderGet reads one Memory v2 provider.
	ToolIDMemoryProviderGet ToolID = "compozy__memory_provider_get"
	// ToolIDMemoryProviderSelect selects the active Memory v2 provider.
	ToolIDMemoryProviderSelect ToolID = "compozy__memory_provider_select"
	// ToolIDMemoryProviderEnable enables one Memory v2 provider.
	ToolIDMemoryProviderEnable ToolID = "compozy__memory_provider_enable"
	// ToolIDMemoryProviderDisable disables one Memory v2 provider.
	ToolIDMemoryProviderDisable ToolID = "compozy__memory_provider_disable"
	// ToolIDMemorySessionLedger reads one materialized Memory v2 session ledger.
	ToolIDMemorySessionLedger ToolID = "compozy__memory_session_ledger"
	// ToolIDMemorySessionReplay replays one materialized Memory v2 session ledger.
	ToolIDMemorySessionReplay ToolID = "compozy__memory_session_replay"
	// ToolIDMemorySessionsPrune prunes Memory v2 session ledgers.
	ToolIDMemorySessionsPrune ToolID = "compozy__memory_sessions_prune"
	// ToolIDMemorySessionsRepair repairs Memory v2 session ledgers.
	ToolIDMemorySessionsRepair ToolID = "compozy__memory_sessions_repair"
	// ToolIDListLogs reads redacted runtime logs.
	ToolIDListLogs ToolID = "compozy__logs"
	// ToolIDToolArtifactRead pages one retained oversized tool result.
	ToolIDToolArtifactRead ToolID = "compozy__tool_artifact_read"
	// ToolIDObserveMetrics reads daemon observability health and metrics.
	ToolIDObserveMetrics ToolID = "compozy__observe_metrics"
	// ToolIDObserveSearch searches redacted observability events.
	ToolIDObserveSearch ToolID = "compozy__observe_search"
	// ToolIDBridgesList lists bridge instances without secret bindings.
	ToolIDBridgesList ToolID = "compozy__bridges_list"
	// ToolIDBridgesStatus reads bridge status and health without credentials.
	ToolIDBridgesStatus ToolID = "compozy__bridges_status"
	// ToolIDTaskList lists task summaries through the task service.
	ToolIDTaskList ToolID = "compozy__task_list"
	// ToolIDTaskRead reads one task view through the task service.
	ToolIDTaskRead ToolID = "compozy__task_read"
	// ToolIDTaskCreate creates one root task through the task service.
	ToolIDTaskCreate ToolID = "compozy__task_create"
	// ToolIDTaskChildCreate creates one child task through the task service.
	ToolIDTaskChildCreate ToolID = "compozy__task_child_create"
	// ToolIDTaskUpdate updates one task through the task service.
	ToolIDTaskUpdate ToolID = "compozy__task_update"
	// ToolIDTaskCancel cancels one task through the task service.
	ToolIDTaskCancel ToolID = "compozy__task_cancel"
	// ToolIDTaskBlock creates one runtime-declared task block.
	ToolIDTaskBlock ToolID = "compozy__task_block"
	// ToolIDTaskUnblock clears one runtime-declared task block.
	ToolIDTaskUnblock ToolID = "compozy__task_unblock"
	// ToolIDTaskBlocks lists runtime-declared task blocks.
	ToolIDTaskBlocks ToolID = "compozy__task_blocks"
	// ToolIDTaskRecover clears task-level needs_attention state.
	ToolIDTaskRecover ToolID = "compozy__task_recover"
	// ToolIDTaskRunList lists task runs through the task service.
	ToolIDTaskRunList ToolID = "compozy__task_run_list"
	// ToolIDTaskRunReviewRequest requests a review for one terminal task run.
	ToolIDTaskRunReviewRequest ToolID = "compozy__task_run_review_request"
	// ToolIDTaskRunReviewList lists task-run reviews through the task service.
	ToolIDTaskRunReviewList ToolID = "compozy__task_run_review_list"
	// ToolIDTaskRunReviewShow reads one task-run review through the task service.
	ToolIDTaskRunReviewShow ToolID = "compozy__task_run_review_show"
	// ToolIDTaskExecutionProfileGet reads one task execution profile.
	ToolIDTaskExecutionProfileGet ToolID = "compozy__task_execution_profile_get"
	// ToolIDTaskExecutionProfileSet updates one task execution profile.
	ToolIDTaskExecutionProfileSet ToolID = "compozy__task_execution_profile_set"
	// ToolIDTaskExecutionProfileDelete removes one task execution profile.
	ToolIDTaskExecutionProfileDelete ToolID = "compozy__task_execution_profile_delete"
	// ToolIDTaskNotificationSubscribe creates one bridge notification subscription for a task.
	ToolIDTaskNotificationSubscribe ToolID = "compozy__task_notification_subscribe"
	// ToolIDTaskNotificationList lists bridge notification subscriptions for a task.
	ToolIDTaskNotificationList ToolID = "compozy__task_notification_list"
	// ToolIDTaskNotificationShow reads one bridge notification subscription for a task.
	ToolIDTaskNotificationShow ToolID = "compozy__task_notification_show"
	// ToolIDTaskNotificationDelete deletes one bridge notification subscription for a task.
	ToolIDTaskNotificationDelete ToolID = "compozy__task_notification_delete"
	// ToolIDTaskPromoteFromThread promotes one network thread message into a durable task.
	ToolIDTaskPromoteFromThread ToolID = "compozy__task_promote_from_thread"
	// ToolIDTaskFanOutRuns creates designated sibling task runs.
	ToolIDTaskFanOutRuns ToolID = "compozy__task_fanout_runs"
	// ToolIDTaskRunClaimNext claims the next run for the caller session.
	ToolIDTaskRunClaimNext ToolID = "compozy__task_run_claim_next"
	// ToolIDTaskRunHeartbeat extends the caller session's active run lease.
	ToolIDTaskRunHeartbeat ToolID = "compozy__task_run_heartbeat"
	// ToolIDTaskRunComplete completes the caller session's active run lease.
	ToolIDTaskRunComplete ToolID = "compozy__task_run_complete"
	// ToolIDTaskRunFail fails the caller session's active run lease.
	ToolIDTaskRunFail ToolID = "compozy__task_run_fail"
	// ToolIDTaskRunRelease releases the caller session's active run lease.
	ToolIDTaskRunRelease ToolID = "compozy__task_run_release"
	// ToolIDTaskRunReviewSubmit submits the caller session's bound task-run review verdict.
	ToolIDTaskRunReviewSubmit ToolID = "compozy__task_run_review_submit"
	// ToolIDConfigShow shows the redacted effective config.
	ToolIDConfigShow ToolID = "compozy__config_show"
	// ToolIDConfigList lists redacted effective config entries.
	ToolIDConfigList ToolID = "compozy__config_list"
	// ToolIDConfigGet reads one redacted effective config entry.
	ToolIDConfigGet ToolID = "compozy__config_get"
	// ToolIDConfigSet mutates one validated config overlay value.
	ToolIDConfigSet ToolID = "compozy__config_set"
	// ToolIDConfigUnset removes one validated config overlay value.
	ToolIDConfigUnset ToolID = "compozy__config_unset"
	// ToolIDConfigDiff compares defaults/global config against the effective view.
	ToolIDConfigDiff ToolID = "compozy__config_diff"
	// ToolIDConfigPath reports resolved config paths.
	ToolIDConfigPath ToolID = "compozy__config_path"
	// ToolIDHooksList lists resolved hooks.
	ToolIDHooksList ToolID = "compozy__hooks_list"
	// ToolIDHooksInfo reads one resolved hook.
	ToolIDHooksInfo ToolID = "compozy__hooks_info"
	// ToolIDHooksEvents lists supported hook events.
	ToolIDHooksEvents ToolID = "compozy__hooks_events"
	// ToolIDHooksRuns lists hook run audit records.
	ToolIDHooksRuns ToolID = "compozy__hooks_runs"
	// ToolIDHooksCreate creates one config-backed hook declaration.
	ToolIDHooksCreate ToolID = "compozy__hooks_create"
	// ToolIDHooksUpdate updates one config-backed hook declaration.
	ToolIDHooksUpdate ToolID = "compozy__hooks_update"
	// ToolIDHooksDelete deletes one config-backed hook declaration.
	ToolIDHooksDelete ToolID = "compozy__hooks_delete"
	// ToolIDHooksEnable enables one config-backed hook declaration.
	ToolIDHooksEnable ToolID = "compozy__hooks_enable"
	// ToolIDHooksDisable disables one config-backed hook declaration.
	ToolIDHooksDisable ToolID = "compozy__hooks_disable"
	// ToolIDGoalGet reads the visible Goal projection for the caller session.
	ToolIDGoalGet ToolID = "compozy__goal_get"
	// ToolIDGoalReport records one prompt-bound Goal completion or blocker intent.
	ToolIDGoalReport ToolID = "compozy__goal_report"
	// ToolIDLoopList lists Loop definitions available in a workspace.
	ToolIDLoopList ToolID = "compozy__loop_list"
	// ToolIDLoopInspect reads one Loop definition and authoring contract.
	ToolIDLoopInspect ToolID = "compozy__loop_inspect"
	// ToolIDLoopValidate lints and compiles one Loop definition without saving it.
	ToolIDLoopValidate ToolID = "compozy__loop_validate"
	// ToolIDLoopCreate creates or forks one Loop definition.
	ToolIDLoopCreate ToolID = "compozy__loop_create"
	// ToolIDLoopRun starts or dry-runs one Loop.
	ToolIDLoopRun ToolID = "compozy__loop_run"
	// ToolIDLoopStatus reads one Loop run status.
	ToolIDLoopStatus ToolID = "compozy__loop_status"
	// ToolIDLoopRuns lists workspace-scoped Loop runs.
	ToolIDLoopRuns ToolID = "compozy__loop_runs"
	// ToolIDLoopTurns lists one Loop run's total-order Goal turn audit.
	ToolIDLoopTurns ToolID = "compozy__loop_turns"
	// ToolIDLoopCancel requests cooperative cancellation for one Loop run.
	ToolIDLoopCancel ToolID = "compozy__loop_cancel"
	// ToolIDLoopKill immediately terminalizes one Loop run.
	ToolIDLoopKill ToolID = "compozy__loop_kill"
	// ToolIDLoopNodes lists workspace-scoped Loop node state.
	ToolIDLoopNodes ToolID = "compozy__loop_nodes"
	// ToolIDLoopNodePause parks one authored Loop node.
	ToolIDLoopNodePause ToolID = "compozy__loop_node_pause"
	// ToolIDLoopNodeResume releases one authored Loop node or manual wait.
	ToolIDLoopNodeResume ToolID = "compozy__loop_node_resume"
	// ToolIDLoopNodeCancel requests cooperative node cancellation.
	ToolIDLoopNodeCancel ToolID = "compozy__loop_node_cancel"
	// ToolIDLoopNodeKill immediately fences one Loop node.
	ToolIDLoopNodeKill ToolID = "compozy__loop_node_kill"
	// ToolIDLoopNodeRequeue clears one Loop node quarantine.
	ToolIDLoopNodeRequeue ToolID = "compozy__loop_node_requeue"
	// ToolIDLoopPause pauses one running Loop at a generation boundary.
	ToolIDLoopPause ToolID = "compozy__loop_pause"
	// ToolIDLoopResume resumes one paused Loop run.
	ToolIDLoopResume ToolID = "compozy__loop_resume"
	// ToolIDLoopConfigure writes per-loop runtime config overrides.
	ToolIDLoopConfigure ToolID = "compozy__loop_configure"
	// ToolIDLoopApprove applies one human-gate decision.
	ToolIDLoopApprove ToolID = "compozy__loop_approve"
	// ToolIDLoopDelete deletes one user-authored Loop definition.
	ToolIDLoopDelete ToolID = "compozy__loop_delete"
	// ToolIDAutomationJobsList lists automation jobs through the automation manager.
	ToolIDAutomationJobsList ToolID = "compozy__automation_jobs_list"
	// ToolIDAutomationJobsGet reads one automation job through the automation manager.
	ToolIDAutomationJobsGet ToolID = "compozy__automation_jobs_get"
	// ToolIDAutomationJobsCreate creates one dynamic automation job through the automation manager.
	ToolIDAutomationJobsCreate ToolID = "compozy__automation_jobs_create"
	// ToolIDAutomationJobsUpdate updates one automation job through the automation manager.
	ToolIDAutomationJobsUpdate ToolID = "compozy__automation_jobs_update"
	// ToolIDAutomationJobsDelete deletes one dynamic automation job through the automation manager.
	ToolIDAutomationJobsDelete ToolID = "compozy__automation_jobs_delete"
	// ToolIDAutomationJobsEnable enables one automation job through the automation manager.
	ToolIDAutomationJobsEnable ToolID = "compozy__automation_jobs_enable"
	// ToolIDAutomationJobsDisable disables one automation job through the automation manager.
	ToolIDAutomationJobsDisable ToolID = "compozy__automation_jobs_disable"
	// ToolIDAutomationJobsTrigger manually triggers one automation job through the automation manager.
	ToolIDAutomationJobsTrigger ToolID = "compozy__automation_jobs_trigger"
	// ToolIDAutomationJobsHistory lists run history for one automation job.
	ToolIDAutomationJobsHistory ToolID = "compozy__automation_jobs_history"
	// ToolIDAutomationTriggersList lists automation triggers through the automation manager.
	ToolIDAutomationTriggersList ToolID = "compozy__automation_triggers_list"
	// ToolIDAutomationTriggersGet reads one automation trigger through the automation manager.
	ToolIDAutomationTriggersGet ToolID = "compozy__automation_triggers_get"
	// ToolIDAutomationTriggersCreate creates one dynamic automation trigger through the automation manager.
	ToolIDAutomationTriggersCreate ToolID = "compozy__automation_triggers_create"
	// ToolIDAutomationTriggersUpdate updates one automation trigger through the automation manager.
	ToolIDAutomationTriggersUpdate ToolID = "compozy__automation_triggers_update"
	// ToolIDAutomationTriggersDelete deletes one dynamic automation trigger through the automation manager.
	ToolIDAutomationTriggersDelete ToolID = "compozy__automation_triggers_delete"
	// ToolIDAutomationTriggersEnable enables one automation trigger through the automation manager.
	ToolIDAutomationTriggersEnable ToolID = "compozy__automation_triggers_enable"
	// ToolIDAutomationTriggersDisable disables one automation trigger through the automation manager.
	ToolIDAutomationTriggersDisable ToolID = "compozy__automation_triggers_disable"
	// ToolIDAutomationTriggersHistory lists run history for one automation trigger.
	ToolIDAutomationTriggersHistory ToolID = "compozy__automation_triggers_history"
	// ToolIDAutomationRunsList lists automation run records through the automation manager.
	ToolIDAutomationRunsList ToolID = "compozy__automation_runs_list"
	// ToolIDAutomationRunsGet reads one automation run record through the automation manager.
	ToolIDAutomationRunsGet ToolID = "compozy__automation_runs_get"
	// ToolIDAutomationSuggestionsList lists workspace-scoped automation suggestions.
	ToolIDAutomationSuggestionsList ToolID = "compozy__automation_suggestions_list"
	// ToolIDAutomationSuggestionsAccept accepts one suggestion and creates its Job.
	ToolIDAutomationSuggestionsAccept ToolID = "compozy__automation_suggestions_accept"
	// ToolIDAutomationSuggestionsDismiss durably dismisses one suggestion.
	ToolIDAutomationSuggestionsDismiss ToolID = "compozy__automation_suggestions_dismiss"
	// ToolIDMarketplaceSearch searches the shared marketplace discovery plane.
	ToolIDMarketplaceSearch ToolID = "compozy__marketplace_search"
	// ToolIDResourcesList lists desired-state resource records.
	ToolIDResourcesList ToolID = "compozy__resources_list"
	// ToolIDResourcesInfo reads one desired-state resource record.
	ToolIDResourcesInfo ToolID = "compozy__resources_info"
	// ToolIDResourcesSnapshot reads a filtered desired-state resource snapshot.
	ToolIDResourcesSnapshot ToolID = "compozy__resources_snapshot"
	// ToolIDMCPStatus probes one configured MCP server without exposing login/logout as tools.
	ToolIDMCPStatus ToolID = "compozy__mcp_status"
	// ToolIDMCPAuthStatus reads redacted MCP auth diagnostics for one configured server.
	ToolIDMCPAuthStatus ToolID = "compozy__mcp_auth_status"
)
const (
	// ToolIDDesktopList lists persistent desktops.
	ToolIDDesktopList ToolID = "compozy__desktop_list"
	// ToolIDDesktopCreate creates a persistent desktop.
	ToolIDDesktopCreate ToolID = "compozy__desktop_create"
	// ToolIDDesktopUpdate renames a persistent desktop.
	ToolIDDesktopUpdate ToolID = "compozy__desktop_update"
	// ToolIDDesktopReorder changes persistent desktop order.
	ToolIDDesktopReorder ToolID = "compozy__desktop_reorder"
	// ToolIDDesktopSwitch changes one explicit client's active desktop.
	ToolIDDesktopSwitch ToolID = "compozy__desktop_switch"
	// ToolIDDesktopDelete deletes a persistent desktop.
	ToolIDDesktopDelete ToolID = "compozy__desktop_delete"
	// ToolIDDesktopClients lists connected window-manager clients.
	ToolIDDesktopClients ToolID = "compozy__desktop_clients"
	// ToolIDWindowList lists managed windows.
	ToolIDWindowList ToolID = "compozy__window_list"
	// ToolIDWindowOpen opens or restores a managed window.
	ToolIDWindowOpen ToolID = "compozy__window_open"
	// ToolIDWindowNavigate persists one managed window's internal route.
	ToolIDWindowNavigate ToolID = "compozy__window_navigate"
	// ToolIDWindowClose closes or minimizes a managed window.
	ToolIDWindowClose ToolID = "compozy__window_close"
	// ToolIDWindowGroup groups windows into one ordered stack.
	ToolIDWindowGroup ToolID = "compozy__window_group"
	// ToolIDWindowReorder reorders one member within its stack.
	ToolIDWindowReorder ToolID = "compozy__window_reorder"
	// ToolIDWindowActivate durably activates one stacked window.
	ToolIDWindowActivate ToolID = "compozy__window_activate"
	// ToolIDWindowPin changes one window's pinned state.
	ToolIDWindowPin ToolID = "compozy__window_pin"
	// ToolIDWindowReopen restores the newest closed entry.
	ToolIDWindowReopen ToolID = "compozy__window_reopen"
	// ToolIDWindowFocus focuses a managed window for one explicit client.
	ToolIDWindowFocus ToolID = "compozy__window_focus"
	// ToolIDWindowMove moves a managed window.
	ToolIDWindowMove ToolID = "compozy__window_move"
	// ToolIDWindowResize resizes a window frame, detaching split members into islands.
	ToolIDWindowResize ToolID = "compozy__window_resize"
	// ToolIDWindowSwap swaps two managed windows.
	ToolIDWindowSwap ToolID = "compozy__window_swap"
	// ToolIDWindowFloat toggles one managed window's floating state.
	ToolIDWindowFloat ToolID = "compozy__window_float"
	// ToolIDWindowZoom toggles one managed window's focus desktop.
	ToolIDWindowZoom ToolID = "compozy__window_zoom"
	// ToolIDLayoutGet reads the authoritative topology snapshot.
	ToolIDLayoutGet ToolID = "compozy__layout_get"
	// ToolIDLayoutPreview previews one semantic layout command.
	ToolIDLayoutPreview ToolID = "compozy__layout_preview"
	// ToolIDLayoutArrange arranges windows into a tiled group.
	ToolIDLayoutArrange ToolID = "compozy__layout_arrange"
	// ToolIDLayoutResize resizes a split boundary.
	ToolIDLayoutResize ToolID = "compozy__layout_resize"
	// ToolIDLayoutFrameResize atomically rewrites adjacent island frames.
	ToolIDLayoutFrameResize ToolID = "compozy__layout_frame_resize"
	// ToolIDLayoutBalance balances a group or split.
	ToolIDLayoutBalance ToolID = "compozy__layout_balance"
	// ToolIDLayoutUndo reverts the latest durable topology command.
	ToolIDLayoutUndo ToolID = "compozy__layout_undo"
	// ToolIDLayoutRedo reapplies the latest reverted topology command.
	ToolIDLayoutRedo ToolID = "compozy__layout_redo"
	// ToolIDLayoutExport exports a history-free layout document.
	ToolIDLayoutExport ToolID = "compozy__layout_export"
	// ToolIDLayoutValidate validates a raw layout document.
	ToolIDLayoutValidate ToolID = "compozy__layout_validate"
	// ToolIDLayoutApply atomically applies a validated layout document.
	ToolIDLayoutApply ToolID = "compozy__layout_apply"
)

Window-manager native tool IDs: desktops, windows, and layout surfaces.

func CanonicalToolID

func CanonicalToolID(namespace string, segments ...string) (ToolID, error)

CanonicalToolID builds a ToolID from raw namespace segments.

func Canonicalize

func Canonicalize(rawServer, rawTool string) (ToolID, error)

Canonicalize normalizes one raw MCP server/tool pair into the canonical registry ToolID.

func (ToolID) MarshalText

func (id ToolID) MarshalText() ([]byte, error)

MarshalText encodes the validated id.

func (ToolID) Namespace

func (id ToolID) Namespace() (string, error)

Namespace returns the leading namespace segment.

func (ToolID) Segments

func (id ToolID) Segments() ([]string, error)

Segments returns a copy of the namespace segments.

func (ToolID) String

func (id ToolID) String() string

String returns the canonical string value.

func (*ToolID) UnmarshalText

func (id *ToolID) UnmarshalText(text []byte) error

UnmarshalText decodes and validates an id.

func (ToolID) Validate

func (id ToolID) Validate() error

Validate ensures the tool id follows the canonical grammar.

type ToolPattern

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

ToolPattern matches exact ToolIDs or namespace-prefix wildcards.

func ParseToolPattern

func ParseToolPattern(raw string) (ToolPattern, error)

ParseToolPattern validates one exact ToolID or namespace-prefix wildcard.

func ParseToolPatterns

func ParseToolPatterns(values []string) ([]ToolPattern, error)

ParseToolPatterns validates a list of policy patterns.

func (ToolPattern) Match

func (p ToolPattern) Match(id ToolID) bool

Match reports whether the pattern covers the given canonical ToolID.

func (ToolPattern) String

func (p ToolPattern) String() string

String returns the stable policy expression.

type ToolPresentation

type ToolPresentation struct {
	FriendlyVerb string `json:"friendly_verb,omitempty"`
	Preview      string `json:"preview,omitempty"`
}

ToolPresentation carries optional, non-executable descriptor presentation hints.

func CloneToolPresentation

func CloneToolPresentation(p *ToolPresentation) *ToolPresentation

CloneToolPresentation returns an independent presentation payload.

func NewToolPresentation

func NewToolPresentation(friendlyVerb string, preview string) *ToolPresentation

NewToolPresentation returns nil when both optional presentation fields are empty.

type ToolResult

type ToolResult struct {
	Content    []ToolContent              `json:"content,omitempty"`
	Structured json.RawMessage            `json:"structured,omitempty"`
	Preview    string                     `json:"preview,omitempty"`
	Artifacts  []ArtifactRef              `json:"artifacts,omitempty"`
	Metadata   map[string]json.RawMessage `json:"metadata,omitempty"`
	Redactions []Redaction                `json:"redactions,omitempty"`
	Truncated  bool                       `json:"truncated"`
	Bytes      int64                      `json:"bytes"`
	DurationMS int64                      `json:"duration_ms"`
}

ToolResult is the canonical result envelope for all backends.

func (ToolResult) Validate

func (r ToolResult) Validate(maxBytes int64) error

Validate checks the public result envelope and metadata safety.

type ToolSource

type ToolSource = SourceKind

ToolSource preserves the public source-name type used by existing resource contracts.

type ToolView

type ToolView struct {
	Descriptor   Descriptor            `json:"descriptor"`
	Availability Availability          `json:"availability"`
	Decision     EffectiveToolDecision `json:"decision"`
}

ToolView is a descriptor plus effective diagnostics for a caller.

type Toolset

type Toolset struct {
	ID       ToolsetID   `json:"id"`
	Tools    []string    `json:"tools,omitempty"`
	Toolsets []ToolsetID `json:"toolsets,omitempty"`
}

Toolset groups exact tools, patterns, and nested toolsets.

func (Toolset) Validate

func (t Toolset) Validate() error

Validate ensures the toolset is syntactically expandable.

type ToolsetCatalog

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

ToolsetCatalog expands named toolsets into concrete ToolID atoms.

func NewToolsetCatalog

func NewToolsetCatalog(toolsets ...Toolset) (ToolsetCatalog, error)

NewToolsetCatalog validates and indexes toolsets by ID.

func (ToolsetCatalog) Contains

func (c ToolsetCatalog) Contains(id ToolID, toolsetIDs []ToolsetID) (bool, error)

Contains reports whether any selected toolset grants the concrete tool ID.

func (ToolsetCatalog) Expand

func (c ToolsetCatalog) Expand(id ToolsetID, universe []ToolID) ([]ToolID, error)

Expand resolves one toolset into concrete ToolID atoms.

func (ToolsetCatalog) ExpandPatterns

func (c ToolsetCatalog) ExpandPatterns(
	patterns []ToolPattern,
	toolsetIDs []ToolsetID,
	universe []ToolID,
) ([]ToolID, error)

ExpandPatterns resolves patterns and toolsets into concrete ToolID atoms.

func (ToolsetCatalog) Get

func (c ToolsetCatalog) Get(id ToolsetID) (Toolset, bool)

Get returns one known toolset definition.

func (ToolsetCatalog) IDs

func (c ToolsetCatalog) IDs() []ToolsetID

IDs returns the known toolset IDs in deterministic order.

func (ToolsetCatalog) List

func (c ToolsetCatalog) List() []Toolset

List returns all known toolsets in deterministic order.

type ToolsetID

type ToolsetID string

ToolsetID is the canonical public toolset identity.

const (
	// ToolsetIDBootstrap groups registry self-inspection tools.
	ToolsetIDBootstrap ToolsetID = "compozy__bootstrap"
	// ToolsetIDCatalog groups registry and skill catalog tools.
	ToolsetIDCatalog ToolsetID = "compozy__catalog"
	// ToolsetIDToolArtifacts groups retained oversized result tools.
	ToolsetIDToolArtifacts ToolsetID = "compozy__tool_artifacts"
	// ToolsetIDToolApprovals groups durable native-tool approval management tools.
	ToolsetIDToolApprovals ToolsetID = "compozy__tool_approvals"
	// ToolsetIDClarify exposes the session-scoped human clarification tool.
	ToolsetIDClarify ToolsetID = "compozy__clarify"
	// ToolsetIDCoordination groups network coordination tools.
	ToolsetIDCoordination ToolsetID = "compozy__coordination"
	// ToolsetIDTasks groups bounded task tools.
	ToolsetIDTasks ToolsetID = "compozy__tasks"
	// ToolsetIDAutonomy groups session-bound task-run autonomy tools.
	ToolsetIDAutonomy ToolsetID = "compozy__autonomy"
	// ToolsetIDSessions groups runtime session tools.
	ToolsetIDSessions ToolsetID = "compozy__sessions"
	// ToolsetIDAuthoredContext groups managed Soul/Heartbeat read and wake tools.
	ToolsetIDAuthoredContext ToolsetID = "compozy__authored_context"
	// ToolsetIDWorkspace groups workspace inspection and managed agent authoring tools.
	ToolsetIDWorkspace ToolsetID = "compozy__workspace"
	// ToolsetIDProviderModels groups provider model catalog tools.
	ToolsetIDProviderModels ToolsetID = "compozy__provider_models"
	// ToolsetIDMemory groups Memory v2 read and proposal tools.
	ToolsetIDMemory ToolsetID = "compozy__memory"
	// ToolsetIDMemoryAdmin groups Memory v2 operational tools.
	ToolsetIDMemoryAdmin ToolsetID = "compozy__memory_admin"
	// ToolsetIDObserve groups read-only observability tools.
	ToolsetIDObserve ToolsetID = "compozy__observe"
	// ToolsetIDBridges groups read-only bridge inspection tools.
	ToolsetIDBridges ToolsetID = "compozy__bridges"
	// ToolsetIDConfig groups validated config tools.
	ToolsetIDConfig ToolsetID = "compozy__config"
	// ToolsetIDHooks groups hook introspection and mutable config-backed hook tools.
	ToolsetIDHooks ToolsetID = "compozy__hooks"
	// ToolsetIDLoops groups Loop authoring, execution, and run-management tools.
	ToolsetIDLoops ToolsetID = "compozy__loops"
	// ToolsetIDAutomation groups automation lifecycle and run inspection tools.
	ToolsetIDAutomation ToolsetID = "compozy__automation"
	// ToolsetIDExtensions groups extension discovery and lifecycle tools.
	ToolsetIDExtensions ToolsetID = "compozy__extensions"
	// ToolsetIDMarketplace groups cross-kind marketplace discovery tools.
	ToolsetIDMarketplace ToolsetID = "compozy__marketplace"
	// ToolsetIDResources groups desired-state resource inspection tools.
	ToolsetIDResources ToolsetID = "compozy__resources"
	// ToolsetIDWindowManager groups persistent desktop, window, and layout tools.
	ToolsetIDWindowManager ToolsetID = "compozy__window_manager"
	// ToolsetIDMCP groups MCP probe and status diagnostics.
	ToolsetIDMCP ToolsetID = "compozy__mcp"
	// ToolsetIDMCPAuth groups redacted MCP auth diagnostics.
	ToolsetIDMCPAuth ToolsetID = "compozy__mcp_auth"
)

func (ToolsetID) MarshalText

func (id ToolsetID) MarshalText() ([]byte, error)

MarshalText encodes the validated id.

func (ToolsetID) String

func (id ToolsetID) String() string

String returns the canonical string value.

func (*ToolsetID) UnmarshalText

func (id *ToolsetID) UnmarshalText(text []byte) error

UnmarshalText decodes and validates an id.

func (ToolsetID) Validate

func (id ToolsetID) Validate() error

Validate ensures the toolset id follows the canonical grammar.

type ToolsetView

type ToolsetView struct {
	Toolset       Toolset      `json:"toolset"`
	ExpandedTools []ToolID     `json:"expanded_tools,omitempty"`
	ReasonCodes   []ReasonCode `json:"reason_codes,omitempty"`
}

ToolsetView is a named toolset plus its current expansion diagnostics.

type ValidationError

type ValidationError struct {
	Field  string
	Reason ReasonCode
	Detail string
}

ValidationError describes deterministic contract validation failures.

func NewValidationError

func NewValidationError(field string, reason ReasonCode, detail string) *ValidationError

NewValidationError builds a deterministic validation error.

func (*ValidationError) Error

func (e *ValidationError) Error() string

Error returns a stable validation message.

type Visibility

type Visibility string

Visibility identifies which surfaces may display a descriptor.

const (
	// VisibilityInternal limits a tool to daemon-internal use.
	VisibilityInternal Visibility = "internal"
	// VisibilityOperator exposes a tool to operator diagnostics.
	VisibilityOperator Visibility = "operator"
	// VisibilitySession exposes a tool to session-scoped views.
	VisibilitySession Visibility = "session"
	// VisibilityModel exposes a tool to model-visible projections.
	VisibilityModel Visibility = "model"
)

func (Visibility) Validate

func (v Visibility) Validate(field string) error

Validate ensures the visibility is documented.

type WorkspaceIDResolver

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

WorkspaceIDResolver canonicalizes workspace references before policy evaluation.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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