Documentation
¶
Overview ¶
Package tools defines canonical Tool Registry contracts.
Index ¶
- Constants
- Variables
- func ApprovalInputDigest(input json.RawMessage, suppliedDigest string) (string, error)
- func CanonicalIDSegment(raw string) (string, error)
- func CanonicalJSON(raw json.RawMessage) ([]byte, error)
- func CommandFlagTypeValues() []string
- func MCPDiscoveryFailureClass(err error) deadentity.FailureClass
- func NewResourceCodec() (resources.KindCodec[Tool], error)
- func ParseToolArtifactURI(uri string) (string, error)
- func SchemaDigest(raw json.RawMessage) (string, error)
- func ValidateHandle(handle Handle) error
- func ValidateJSONObject(field string, raw json.RawMessage, required bool) error
- func ValidateProvider(provider Provider) error
- type AgentToolPolicy
- type ApprovalBridge
- type ApprovalGrant
- type ApprovalGrantDecision
- type ApprovalGrantKey
- type ApprovalGrantManagementScope
- type ApprovalGrantSetRequest
- type ApprovalGrantStore
- type ApprovalRequest
- type ApprovalTokenConsumer
- type ApprovalTokenGrant
- type ApprovalTokenIssuer
- type ApprovalTokenStore
- type ApprovalTokenStoreOption
- type ArtifactRef
- type Availability
- type BackendKind
- type BackendRef
- type CallInputAuthorizer
- type CallInputBinder
- type CallRequest
- type ClarifyAnswer
- type ClarifyAnswerRequest
- type ClarifyBroker
- type ClarifyEvent
- type ClarifyPending
- type ClarifyQuestion
- type ClarifyStatus
- type CommandFlag
- type CommandFlagType
- type DefaultResultProcessor
- type DeferredDiscoveryProvider
- type Descriptor
- type EffectivePolicyEvaluator
- type EffectiveToolDecision
- type ErrorCode
- type ExtensionCommandSpec
- type ExtensionProvideToolsResponse
- type ExtensionToolCallRequest
- type ExtensionToolCallResponse
- type ExtensionToolInvoker
- type ExtensionToolRuntimeDescriptor
- type ExtensionToolWorkspaceScope
- type ExternalDefault
- type FilesystemToolArtifactStore
- func (s *FilesystemToolArtifactStore) Put(ctx context.Context, workspaceID string, content []byte) (ArtifactRef, error)
- func (s *FilesystemToolArtifactStore) ReadPage(ctx context.Context, workspaceID string, uri string, offset int64, limit int64) (ToolArtifactPage, error)
- func (s *FilesystemToolArtifactStore) Sweep(ctx context.Context) error
- type Handle
- type HookRunner
- type MCPAuthStatus
- type MCPAuthStatusProvider
- type MCPCallExecutor
- type MCPDeadEntityService
- type MCPProvider
- func (*MCPProvider) DeferInitialDiscovery() bool
- func (p *MCPProvider) ForgetMCPServer(workspaceID string, serverName string)
- func (p *MCPProvider) ForgetWorkspace(workspaceID string)
- func (p *MCPProvider) ID() SourceRef
- func (p *MCPProvider) List(ctx context.Context, scope Scope) ([]Descriptor, error)
- func (p *MCPProvider) Resolve(ctx context.Context, scope Scope, id ToolID) (Handle, bool, error)
- type MCPProviderOption
- type MCPSourceLister
- type MCPSourceListerFunc
- type MCPToolCallRequest
- type MCPToolCallResponse
- type MCPToolDescriptor
- type NativeAvailabilityFunc
- type NativeProvider
- type NativeTool
- type NativeToolFunc
- type OperatorFailure
- type PermissionMode
- type PolicyEvaluator
- type PolicyInputResolver
- type PolicyInputs
- type Provider
- type ReasonCode
- type Redaction
- type Registry
- type RegistryOption
- func WithApprovalBridge(bridge ApprovalBridge) RegistryOption
- func WithCallInputAuthorizer(authorizer CallInputAuthorizer) RegistryOption
- func WithCallInputBinder(binder CallInputBinder) RegistryOption
- func WithDefaultMaxResultBytes(maxBytes int64) RegistryOption
- func WithHookRunner(hooks HookRunner) RegistryOption
- func WithPolicyEvaluator(evaluator PolicyEvaluator) RegistryOption
- func WithPolicyInputResolver(resolver PolicyInputResolver, toolsets ToolsetCatalog) RegistryOption
- func WithPolicyInputs(inputs PolicyInputs, toolsets ToolsetCatalog) RegistryOption
- func WithProviders(providers ...Provider) RegistryOption
- func WithResultProcessor(processor ResultProcessor) RegistryOption
- func WithSensitiveResultFields(fields ...string) RegistryOption
- func WithToolEventSink(events ToolEventSink) RegistryOption
- func WithWorkspaceAccessPolicy(policy workspaceaccess.Policy) RegistryOption
- func WithWorkspaceIDResolver(resolver WorkspaceIDResolver) RegistryOption
- type ResultProcessor
- type RiskClass
- type RuntimeRegistry
- func (r *RuntimeRegistry) BootstrapSessionCall(ctx context.Context, scope Scope, req CallRequest) (ToolResult, error)
- func (r *RuntimeRegistry) BootstrapSessionProjection(ctx context.Context, scope Scope) ([]ToolView, error)
- func (r *RuntimeRegistry) Call(ctx context.Context, scope Scope, req CallRequest) (ToolResult, error)
- func (r *RuntimeRegistry) DiagnosticGet(ctx context.Context, scope Scope, id ToolID) (ToolView, error)
- func (r *RuntimeRegistry) DiagnosticProjection(ctx context.Context, scope Scope) ([]ToolView, error)
- func (r *RuntimeRegistry) DiagnosticSearch(ctx context.Context, scope Scope, q SearchQuery) ([]ToolView, error)
- func (r *RuntimeRegistry) Get(ctx context.Context, scope Scope, id ToolID) (ToolView, error)
- func (r *RuntimeRegistry) GetToolset(ctx context.Context, scope Scope, id ToolsetID) (ToolsetView, error)
- func (r *RuntimeRegistry) List(ctx context.Context, scope Scope) ([]ToolView, error)
- func (r *RuntimeRegistry) ListToolsets(ctx context.Context, scope Scope) ([]ToolsetView, error)
- func (r *RuntimeRegistry) LookupToolMetadata(workspaceID string, toolID string) (toolmeta.DescriptorMetadata, bool)
- func (r *RuntimeRegistry) OperatorProjection(ctx context.Context, scope Scope) ([]ToolView, error)
- func (r *RuntimeRegistry) Search(ctx context.Context, scope Scope, q SearchQuery) ([]ToolView, error)
- func (r *RuntimeRegistry) SessionProjection(ctx context.Context, scope Scope) ([]ToolView, error)
- type Scope
- type SearchQuery
- type SessionToolPolicy
- type SourceGrant
- type SourceKind
- type SourceRef
- type Tool
- type ToolArtifactPage
- type ToolArtifactRetention
- type ToolArtifactStore
- type ToolArtifactSweeper
- type ToolCallEvent
- type ToolCallEventKind
- type ToolContent
- type ToolError
- type ToolEventData
- type ToolEventSink
- type ToolID
- type ToolPattern
- type ToolPresentation
- type ToolResult
- type ToolSource
- type ToolView
- type Toolset
- type ToolsetCatalog
- func (c ToolsetCatalog) Contains(id ToolID, toolsetIDs []ToolsetID) (bool, error)
- func (c ToolsetCatalog) Expand(id ToolsetID, universe []ToolID) ([]ToolID, error)
- func (c ToolsetCatalog) ExpandPatterns(patterns []ToolPattern, toolsetIDs []ToolsetID, universe []ToolID) ([]ToolID, error)
- func (c ToolsetCatalog) Get(id ToolsetID) (Toolset, bool)
- func (c ToolsetCatalog) IDs() []ToolsetID
- func (c ToolsetCatalog) List() []Toolset
- type ToolsetID
- type ToolsetView
- type ValidationError
- type Visibility
- type WorkspaceIDResolver
Constants ¶
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 )
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 )
const (
// BuiltinSourceOwner is the source owner for daemon-compiled Compozy tools.
BuiltinSourceOwner = "daemon"
)
const (
// MaxClarifyChoices bounds model-authored choices before a question reaches a user.
MaxClarifyChoices = 4
)
const ToolArtifactSweepInterval = time.Hour
ToolArtifactSweepInterval is the daemon-owned periodic retention cadence.
const ( // ToolResourceKind is the canonical desired-state resource kind for tool records. ToolResourceKind resources.ResourceKind = "tool" )
Variables ¶
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") )
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") )
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") )
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 = 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 ¶
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 ¶
NewResourceCodec builds the canonical tool resource codec.
func ParseToolArtifactURI ¶
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 ¶
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 ¶
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 ¶
func (r ApprovalGrantSetRequest) Normalize() ApprovalGrantSetRequest
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 ¶
type ClarifyBroker interface {
Ask(context.Context, Scope, ClarifyQuestion) (ClarifyAnswer, error)
Pending(context.Context, Scope) ([]ClarifyPending, error)
Answer(context.Context, Scope, string, ClarifyAnswerRequest) (ClarifyAnswer, error)
}
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 ¶
func (l *DefaultResultProcessor) Sanitize(ctx context.Context, d Descriptor, result ToolResult) (ToolResult, error)
Sanitize redacts sensitive fields before a result reaches post-call hooks.
type DeferredDiscoveryProvider ¶
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 ¶
func (e *EffectivePolicyEvaluator) Evaluate(_ context.Context, _ Scope, d Descriptor) (EffectiveToolDecision, error)
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 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 ¶
func (d ExtensionToolRuntimeDescriptor) Validate() error
Validate checks runtime reconciliation metadata for an extension tool.
type ExtensionToolWorkspaceScope ¶
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.
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.
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 ¶
MCPSourceLister returns configured MCP server sources for dynamic discovery.
type MCPSourceListerFunc ¶
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.
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 ¶
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 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" )
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) 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 ¶
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 ¶
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 ¶
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 ¶
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.
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.
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 ¶
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.
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) 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 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 ¶
CanonicalToolID builds a ToolID from raw namespace segments.
func Canonicalize ¶
Canonicalize normalizes one raw MCP server/tool pair into the canonical registry ToolID.
func (ToolID) MarshalText ¶
MarshalText encodes the validated id.
func (*ToolID) UnmarshalText ¶
UnmarshalText decodes and validates an id.
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.
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 ¶
MarshalText encodes the validated id.
func (*ToolsetID) UnmarshalText ¶
UnmarshalText decodes and validates an id.
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.
Source Files
¶
- approval_grants.go
- approval_token.go
- artifact.go
- artifact_store.go
- artifact_sweeper.go
- availability.go
- builtin_extension_ids.go
- builtin_ids.go
- builtin_ids_window_manager.go
- clarify.go
- descriptor.go
- descriptor_lookup.go
- dispatch.go
- dispatch_authorization.go
- dispatch_errors.go
- dispatch_events.go
- dispatch_hooks.go
- dispatch_input_binding.go
- dispatch_result.go
- dispatch_workspace_access.go
- errors.go
- extension_command.go
- id.go
- mcp.go
- mcp_discovery.go
- mcp_reliability.go
- native.go
- operator_failure.go
- pattern.go
- policy.go
- policy_resolver.go
- presentation.go
- provider_descriptor.go
- reason.go
- registry.go
- registry_index.go
- registry_session_projection.go
- resource.go
- result.go
- result_limit.go
- result_offload.go
- schema.go
- schema_composition.go
- schema_digest.go
- tool.go
- toolset.go