tools

type CatalogFilter ¶

type CatalogFilter struct {
	TenantID, UserID, SessionID string
	GrantedScopes               []string
	LoadingModes                []LoadingMode
	NameRegex                   *regexp.Regexp
}

CatalogFilter is the server-enforced subscription predicate on ToolCatalog.List. Keys on the (tenant, user, session) triple plus GrantedScopes — every component participates in visibility:

• TenantID / UserID / SessionID: typically mandatory at the dispatch boundary, but List is tolerant of empty fields so callers can build admin-view filters (an empty triple matches every tool — see HasFullTriple). Production wiring (later phases Protocol surface) MUST gate the empty-triple case behind an elevated scope.

• GrantedScopes: a Tool is visible only if every entry in its AuthScopes is contained in GrantedScopes. Tools with no AuthScopes (the in-process default) are always visible.

• LoadingModes: defaults to LoadingAlways when empty (the prompt-time view); pass [LoadingAlways, LoadingDeferred] for a full-discovery view.

• NameRegex: optional final filter for operator queries; nil matches every tool.

func (f CatalogFilter) HasFullTriple() bool

type CatalogOption ¶

type CatalogOption func(*catalogConfig)

CatalogOption configures a catalog at construction.

func WithCatalogBus(bus events.EventBus) CatalogOption

func WithSearchCache(sc ToolSearchCache) CatalogOption

type CatalogReplacer ¶

type CatalogReplacer interface {
	// Replace atomically swaps each named descriptor in `wrapped`
	// with its wrapped version. Returns ErrToolNotFound (wrapped)
	// when any name does not resolve.
	Replace(wrapped []ToolDescriptor) error
}

CatalogReplacer is the optional surface a ToolCatalog exposes when it supports atomic per-tool descriptor replacement at boot. The catalog wiring (internal/tools/catalog.Builder) uses this to install wrapped descriptors over previously-registered names without a Deregister+Register round trip (which would race concurrent Resolve calls).

Replacement semantics:

• Each descriptor in `wrapped` MUST name an already-registered Tool (the builder enforces this via Resolve BEFORE calling Replace). Otherwise Replace returns ErrToolNotFound naming the offending tool.
• Replacement is atomic from the catalog's external view: a concurrent Resolve sees EITHER every old descriptor OR every new descriptor, never a half-applied mix.
• Descriptors NOT named in `wrapped` are untouched.

A catalog implementation that does not support replacement skips this interface. Callers branch on the type assertion; the absence is the signal.

type CatalogSourceDeregisterer ¶ added in v1.11.0

type CatalogSourceDeregisterer interface {
	// DeregisterSource removes every tool whose Source == source and returns
	// the number removed.
	DeregisterSource(source ToolSourceID) int
}

CatalogSourceDeregisterer is the optional surface a ToolCatalog exposes when it supports removing every tool registered under one source id. The detach-on-reconcile run-start step (agent_config.remove_mcp_connection and rollback-past-add) uses it to prune a no-longer-declared MCP server's tools from the catalog so the next run's projected catalog excludes them — the physical inverse of the boot-time per-source Register loop.

Removal semantics:

• DeregisterSource removes every descriptor whose Tool.Source equals source and returns the count removed.
• Removal is atomic from the catalog's external view: a concurrent Resolve / List sees either the full set or the pruned set.
• A source with no registered tools removes nothing (returns 0) and is a no-op — idempotent across repeated deregisters of the same source.

A catalog implementation that does not support source deregistration skips this interface; callers branch on the type assertion (the absence is the signal), matching CatalogReplacer.

type DescriptorOption ¶

type DescriptorOption func(*descriptorConfig)

DescriptorOption configures a ToolDescriptor at registration. Drivers (in-process, HTTP / MCP / A2A) accept `opts ...DescriptorOption` so the same option surface is reused across transports.

func WithAuthScopes(scopes ...string) DescriptorOption

func WithCostHint(s string) DescriptorOption

func WithDescription(s string) DescriptorOption

func WithExamples(examples ...ToolExample) DescriptorOption

func WithLatencyHint(d time.Duration) DescriptorOption

func WithLoading(m LoadingMode) DescriptorOption

func WithPolicy(p ToolPolicy) DescriptorOption

func WithSafetyNotes(s string) DescriptorOption

func WithSideEffect(s SideEffect) DescriptorOption

func WithSource(id ToolSourceID) DescriptorOption

func WithTags(tags ...string) DescriptorOption

type ErrInsufficientScope ¶ added in v1.16.0

type ErrInsufficientScope struct {
	// Source is the tool source (MCP connection) that answered the challenge.
	Source ToolSourceID
	// ToolName is the server-side tool name the call targeted.
	ToolName string
	// DownstreamResource is the origin/host the challenge came from.
	DownstreamResource string
	// RequiredScopes is the parsed `scope` challenge parameter — the scopes
	// the downstream demands.
	RequiredScopes []string
	// GrantedScopes is the binding's most-recently-granted scope set (from
	// the resolved token). Empty when unknown.
	GrantedScopes []string
	// WWWAuthenticate is the verbatim challenge header value.
	WWWAuthenticate string
	// Origin is the scheme://host[:port] the challenge was observed on.
	Origin string
}

ErrInsufficientScope is the typed, structured signal for a downstream step-up scope shortfall: a `403` answered with a `WWW-Authenticate` challenge carrying `error="insufficient_scope"` (RFC 6750 §3.1). It is constructed ONLY when the challenge is explicitly marked insufficient_scope — an unmarked 403 stays an opaque transport error, so no false-positive structured signal is raised on a server that just returns bare 403s.

Report-not-act: constructing this value never escalates, re-consents, or widens a binding. It is inert data for the coordinator to act on via the existing operator-driven discovery-allowance path — the runtime never auto-follows a shortfall. Classification treats it as permanent (ClassifyError), so the reliability shell stops retrying a shortfall retrying can never fix.

func (e *ErrInsufficientScope) Error() string

func (e *ErrInsufficientScope) ShortfallDetail() ScopeShortfallDetail

type ErrorClass ¶

type ErrorClass string

ErrorClass categorises a tool invocation failure. The policy's RetryOn allowlist references these classes; the shell's classifier maps Go errors to a class on each failed attempt.

const (
	// ErrClassTransient covers retryable infrastructure issues —
	// network blips, "connection reset", "EOF", etc. The shell's
	// classifier maps common error strings here.
	ErrClassTransient ErrorClass = "transient"
	// ErrClassTimeout — the per-attempt context.DeadlineExceeded
	// or the tool's own timeout signal.
	ErrClassTimeout ErrorClass = "timeout"
	// ErrClass5xx — HTTP / RPC server-side 5xx (transient-side
	// failures distinct from network errors).
	ErrClass5xx ErrorClass = "5xx"
	// ErrClassPermanent — non-retryable. A tool that returns a
	// 4xx, ErrToolInvalidArgs, or a context.Canceled gets this
	// class; the shell stops retrying immediately.
	ErrClassPermanent ErrorClass = "permanent"
)

func ClassifyError(err error, perAttemptTimeout bool) ErrorClass

type ExclusionView ¶ added in v1.5.0

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

ExclusionView wraps a PlannerCatalogView, hiding any tool whose Source is a paused MCP server or whose Name is individually disabled — the run-start projection of the agent-config tool-exposure desired state.

Exclusion is projection-time only and applies NEXT-turn: the live MCP transport stays WARM while a server is paused (resume is a flag flip, not a re-dial). A tool hidden here is absent from BOTH List (the `<available_tools>` prompt section) and Resolve (so the planner cannot re-invoke a remembered name), making the exclusion the planner's view of the run's snapshot.

Concurrent reuse: ExclusionView is a value type with read-only fields (the wrapped view + two immutable lookup sets). Each run constructs its own via NewExclusionView; DO NOT cache across runs (the exclusion sets derive from the run's resolved active revision).

func NewExclusionView(inner PlannerCatalogView, pausedSources, disabledNames []string) ExclusionView

func (v ExclusionView) List() []Tool

func (v ExclusionView) Resolve(name string) (Tool, bool)

type InvokeHooks ¶

type InvokeHooks struct {
	// OnAttempt fires after each invoke attempt with the attempt
	// index (0-based: 0 is the initial call, 1 is the first
	// retry) and the attempt's error (nil on success).
	OnAttempt func(attempt int, err error)
}

InvokeHooks lets drivers observe per-attempt outcomes (e.g. to emit per-attempt audit events) without coupling the policy shell to the events package.

type LoadingMode ¶

type LoadingMode string

LoadingMode controls when a Tool appears in the planner's prompt- time catalog. Always-loaded tools live in every planner step; Deferred tools are loaded on demand (lazy resolution).

const (
	LoadingAlways   LoadingMode = "always"
	LoadingDeferred LoadingMode = "deferred"
)

type LoadingOverrideView ¶ added in v1.10.0

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

LoadingOverrideView wraps a PlannerCatalogView, rewriting each tool's LoadingMode from a per-run resolved effective-mode map and re-applying the prompt-time loading predicate against that EFFECTIVE mode — the run-start projection of the agent-config loading-mode override. Sibling of ExclusionView: the two compose independently — LoadingOverrideView changes prompt PRESENCE only, ExclusionView removes CAPABILITY.

List() keeps only tools whose effective mode is in the constructor's visibleModes set (defaulting to LoadingAlways, mirroring CatalogFilter's default), and rewrites Tool.Loading on every returned tool. Resolve() NEVER filters on loading — matching PlannerView.Resolve — so a tool overridden to LoadingDeferred stays reachable through the two-turn tool_search discovery cycle; it still rewrites the returned Tool's Loading to the effective mode.

Concurrent reuse: LoadingOverrideView is a value type with read-only fields (the wrapped view + two immutable lookup maps built at construction). Each run constructs its own via NewLoadingOverrideView; DO NOT cache across runs — the effective map derives from the run's resolved active config revision (the concurrent-reuse contract).

func NewLoadingOverrideView(inner PlannerCatalogView, effective map[string]LoadingMode, visibleModes []LoadingMode) LoadingOverrideView

func (v LoadingOverrideView) List() []Tool

func (v LoadingOverrideView) Resolve(name string) (Tool, bool)

type PlannerCatalogView ¶ added in v1.5.0

type PlannerCatalogView interface {
	// Resolve returns the schema-only Tool by name and a presence bool.
	Resolve(name string) (Tool, bool)
	// List returns every Tool visible to the run.
	List() []Tool
}

PlannerCatalogView is the planner-facing, schema-only catalog view contract (Resolve + List over Tool). Both PlannerView and ExclusionView satisfy it; the run-loop driver assigns the value it builds to the planner's structurally-identical `ToolCatalogView`. The interface lives here (not in `internal/planner`) so the agent-config run-start projection can compose views without importing `planner`.

type PlannerView ¶ added in v1.3.0

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

PlannerView is the planner-facing, schema-only projection of a ToolCatalog under one run's identity scope ( originally as a `cmd/harbor` adapter).

`planner.RunContext.Catalog` is the surface that renders into the `<available_tools>` prompt section. PlannerView wraps the production catalog + a per-run visibility filter (keyed on the run's identity triple + any GrantedScopes the operator declared). The planner sees the FILTERED set; the catalog's internal store is immutable from the planner's perspective (the planner only reads), and Resolve returns the schema-only Tool value — never the dispatch-side ToolDescriptor.

PlannerView satisfies `planner.ToolCatalogView` STRUCTURALLY (Resolve(name) (Tool, bool) + List() []Tool). This package cannot name that interface — `internal/planner` imports `internal/tools` (ToolCatalogView's methods return Tool) — so the compile-time assertion lives in `internal/planner`'s tests, where the import is legal.

Per-run construction discipline: the view is a value type with two read-only fields. Each run constructs its own view via NewPlannerView — the filter depends on the run's identity. Sharing one view across runs would cross-contaminate visibility across tenants / users / sessions — DO NOT cache.

func NewPlannerView(cat ToolCatalog, filter CatalogFilter) PlannerView

func (v PlannerView) List() []Tool

func (v PlannerView) Resolve(name string) (Tool, bool)

type ResolvedDescriptorConfig ¶

type ResolvedDescriptorConfig struct {
	Policy      ToolPolicy
	Description string
	Tags        []string
	AuthScopes  []string
	Examples    []ToolExample
	SideEffect  SideEffect
	Loading     LoadingMode
	CostHint    string
	LatencyHint time.Duration
	SafetyNotes string
	Source      ToolSourceID
}

ResolvedDescriptorConfig is the resolved option set after applying DescriptorOptions. Drivers consume this when building their ToolDescriptor — they read what the operator declared at registration time + the package-set defaults.

Exported so transports (HTTP, MCP, the A2A) can reuse the option-resolution pipeline without re-implementing it. The fields mirror the unexported descriptorConfig in this file.

func ResolveOptions(opts ...DescriptorOption) ResolvedDescriptorConfig

type ScopeShortfallDetail ¶ added in v1.16.0

type ScopeShortfallDetail struct {
	DownstreamResource string
	RequiredScopes     []string
	GrantedScopes      []string
	WWWAuthenticate    string
	Origin             string
}

ScopeShortfallDetail is the wire-safe (SafePayload) projection of ErrInsufficientScope carried on ToolFailedPayload. Every field is operator/server-supplied metadata — never a token or an arg value.

type SideEffect ¶

type SideEffect string

SideEffect is the declared side-effect class. Operators reason about which tools are safe to retry from this field; the policy's retry behaviour is orthogonal (a tool with SideEffectWrite may still have RetryOn = []ErrorClass{ErrClassTransient} if the caller knows the write is idempotent).

const (
	SideEffectPure     SideEffect = "pure"
	SideEffectRead     SideEffect = "read"
	SideEffectWrite    SideEffect = "write"
	SideEffectExternal SideEffect = "external"
	SideEffectStateful SideEffect = "stateful"
)

type Tool ¶

type Tool struct {
	// Name is the unique catalog key. Two descriptors with the same
	// Name return ErrToolDuplicateName from Register.
	Name string
	// Description is the planner-facing summary. Surfaced in the
	// prompt-time catalog so the LLM can choose between tools.
	Description string
	// ArgsSchema is the JSON-Schema (object) describing the tool's
	// argument shape. Catalogs validate against this before dispatch
	// — failures yield ErrToolInvalidArgs.
	ArgsSchema json.RawMessage
	// OutSchema is the JSON-Schema (object) describing the tool's
	// result shape. Used for output validation when policy enables it.
	OutSchema json.RawMessage
	// SideEffects classifies the tool's effect domain — operators
	// gate which classes are safe to retry / parallelize.
	SideEffects SideEffect
	// Tags allow operators to filter / categorise tools.
	Tags []string
	// AuthScopes lists the scopes a planner step's identity MUST
	// carry (via CatalogFilter.GrantedScopes) for the Tool to be
	// visible. Empty = no scope requirement.
	AuthScopes []string
	// CostHint is free-form (cheap / normal / expensive) and
	// non-authoritative — Governance owns real cost gates.
	CostHint string
	// LatencyHint is non-authoritative; surfaced for prompt ordering.
	LatencyHint time.Duration
	// SafetyNotes is free-form text the planner sees alongside
	// Description; used for "this tool writes to production" hints.
	SafetyNotes string
	// Loading mode: Always (visible in every planner step) or
	// Deferred (loaded on demand).
	Loading LoadingMode
	// Examples surface canonical argument shapes to the planner.
	Examples []ToolExample
	// Source identifies the provider (empty for in-process tools).
	Source ToolSourceID
	// Transport discriminates the tool's source. Determines which
	// driver's Invoke implementation runs.
	Transport TransportKind
	// Policy is the reliability shell wrapping every invocation.
	// Zero value → DefaultPolicy is applied at dispatch time.
	Policy ToolPolicy
	// HandlesMIME declares the MIME types this tool can consume from
	// the artifact store. Used by the runtime's
	// multimodal materializer to populate `ArtifactStub.Fetch.Tool`
	// when an operator-uploaded input artifact's MIME matches — giving
	// the planner an explicit "use this tool for this ref" hint
	// instead of forcing the LLM to discover the binding from the
	// catalog. Wildcards are supported (`image/*`, `audio/*`); empty
	// means the tool advertises no MIME affinity (the LLM still picks
	// it from the catalog by description).
	HandlesMIME []string
	// Form classifies the descriptor shape (tool / resource / prompt).
	// Additive, classification-only (never a dispatch or isolation input);
	// zero value is ToolFormTool. Stamped by the MCP driver at build time
	// for its resource/prompt wrappers; every other driver leaves it
	// zero-valued. See ToolForm.
	Form ToolForm
}

Tool is Harbor's planner-addressable unit. Same struct regardless of Transport. The planner reasons about this; the dispatcher uses the matching ToolDescriptor.

Concurrent reuse: Tool is a value type; all fields are read-only after Register. The Tool itself never carries per-invocation state.

func (t Tool) MatchesMIME(mime string) bool

type ToolCatalog ¶

type ToolCatalog interface {
	// Register adds a descriptor. Returns ErrToolDuplicateName when
	// the Tool's Name is already registered.
	Register(d ToolDescriptor) error
	// Resolve returns the descriptor for name. found=false when
	// absent; the caller compares against the boolean (no error).
	Resolve(name string) (ToolDescriptor, bool)
	// List returns Tool *views* (never ToolDescriptors) matching
	// filter. The slice is owned by the caller; mutations on it do
	// not affect the catalog.
	List(filter CatalogFilter) []Tool
	// Search runs a full-text + tag-filter scan
	// over the catalog's search index. Returns an empty slice when no
	// SearchCache is attached (honest "discovery unavailable").
	Search(ctx context.Context, query string, tags []string, limit int) []Tool
}

ToolCatalog is Harbor's planner-addressable registry. Three methods. Concrete V1 implementation is the in-memory catalog (catalog.go); future drivers (remote-catalog, persistent-catalog) plug in behind the interface.

Concurrent reuse: implementations MUST be safe for N concurrent goroutines. The in-memory catalog uses a single RWMutex; descriptors are immutable after Register.

func Catalog(ctx context.Context) (ToolCatalog, bool)

func MustCatalog(ctx context.Context) ToolCatalog

func NewCatalog(opts ...CatalogOption) ToolCatalog

type ToolCompletedPayload ¶

type ToolCompletedPayload struct {
	events.SafeSealed
	Identity   identity.Quadruple
	ToolName   string
	Transport  TransportKind
	Attempts   int
	DurationMS int64
}

ToolCompletedPayload is the typed payload for EventTypeToolCompleted. SafePayload.

type ToolDescriptor ¶

type ToolDescriptor struct {
	Tool     Tool
	Invoke   func(ctx context.Context, args json.RawMessage) (ToolResult, error)
	Validate func(args json.RawMessage) error
}

ToolDescriptor is the callable binding produced by a driver. The planner sees Tool; the dispatcher uses ToolDescriptor.

Invoke is wrapped by the ToolPolicy shell at dispatch time — the descriptor's Invoke is the inner-most function, called once per retry attempt by the shell. Drivers populate Invoke with the transport-specific code; the shell handles timeout / retry / backoff / validation uniformly.

Validate is the cached compiled JSON-Schema validator. Drivers build it once at Register; the shell calls it once before the first Invoke attempt (validation BEFORE retry — failing args don't get retried).

type ToolExample ¶

type ToolExample struct {
	Args        map[string]any
	Description string
	Tags        []string
}

ToolExample is a usage example surfaced to the planner. The `Args` map is JSON-marshalled into the prompt.

type ToolFailedPayload ¶

type ToolFailedPayload struct {
	events.SafeSealed
	Identity     identity.Quadruple
	ToolName     string
	Transport    TransportKind
	Attempts     int
	ErrorClass   ErrorClass
	ErrorMessage string
	// ScopeShortfall carries the structured downstream insufficient-scope
	// step-up when the terminal failure was an *ErrInsufficientScope. Nil for
	// every other failure. Additive: it enriches the SAME tool.failed event
	// every transport already emits, never a new event type. SafePayload —
	// server/operator-supplied challenge metadata, never a token.
	ScopeShortfall *ScopeShortfallDetail `json:",omitempty"`
}

ToolFailedPayload is the typed payload for EventTypeToolFailed. SafePayload: ErrorClass is enum-shaped; ErrorMessage is operator-controlled (or wraps a sentinel).

type ToolForm ¶ added in v1.10.0

type ToolForm string

ToolForm classifies a Tool's descriptor shape — a callable TOOL versus a driver-wrapped resource/prompt. Additive; classification only — NEVER a dispatch or isolation input. It exists so cross-cutting policy (the agent-config per-server loading-mode override) can distinguish callable tools from wrapped MCP resources/prompts without sniffing a driver's internal name conventions across the §4.4 seam.

const (
	// ToolFormTool is a callable tool descriptor (the zero value / default).
	ToolFormTool ToolForm = ""
	// ToolFormResource is a driver-wrapped resource (e.g. the MCP driver's
	// one-shot `read_resource`-style descriptor).
	ToolFormResource ToolForm = "resource"
	// ToolFormPrompt is a driver-wrapped prompt (e.g. the MCP driver's
	// one-shot `get_prompt`-style descriptor).
	ToolFormPrompt ToolForm = "prompt"
)

type ToolInvalidArgsPayload ¶

type ToolInvalidArgsPayload struct {
	events.SafeSealed
	Identity        identity.Quadruple
	ToolName        string
	Transport       TransportKind
	ValidationError string
}

ToolInvalidArgsPayload is the typed payload for EventTypeToolInvalidArgs. SafePayload: the validation error describes the schema mismatch (e.g. "expected string, got int"), not the offending arg value. Producers MUST NOT include raw arg bytes here — those go through the audit redactor.

type ToolInvokedPayload ¶

type ToolInvokedPayload struct {
	events.SafeSealed
	Identity  identity.Quadruple
	ToolName  string
	Transport TransportKind
	StartedAt time.Time
}

ToolInvokedPayload is the typed payload for EventTypeToolInvoked. SafePayload: carries no secret-shaped data (the tool name and transport are operator-supplied identifiers, not user input).

type ToolPolicy ¶

type ToolPolicy struct {
	// TimeoutMS is the per-attempt deadline in milliseconds. 0
	// means "use DefaultPolicy.TimeoutMS (30000)". When the policy
	// is overridden via WithPolicy, 0 means "no per-attempt
	// timeout" (the ctx's deadline still applies).
	TimeoutMS int
	// MaxRetries is the count of retry attempts AFTER the initial
	// invocation. Total invocations = MaxRetries + 1. 0 (zero
	// value) means "use DefaultPolicy.MaxRetries (3)".
	MaxRetries int
	// BackoffBase is the first-retry sleep before retry attempt 1.
	// Subsequent retries multiply by BackoffMult, capped at
	// BackoffMax. 0 means "use DefaultPolicy.BackoffBase (100ms)".
	BackoffBase time.Duration
	// BackoffMult is the multiplier between successive retry
	// sleeps. 0 means "use DefaultPolicy.BackoffMult (2)".
	BackoffMult float64
	// BackoffMax caps the per-retry sleep regardless of mult. 0
	// means "use DefaultPolicy.BackoffMax (30s)".
	BackoffMax time.Duration
	// RetryOn lists which ErrorClasses are retryable. Empty (zero
	// value) means "use DefaultPolicy.RetryOn ([transient, timeout,
	// 5xx])". An empty non-nil slice (explicitly set to []) means
	// "retry on nothing" (one attempt only).
	RetryOn []ErrorClass
	// Validate selects which side(s) of the invocation the shell
	// validates. Zero value means "use DefaultPolicy.Validate
	// (ValidateBoth)".
	Validate ValidateMode
}

ToolPolicy is the per-tool reliability shell. Every invocation regardless of Transport wraps in ToolPolicy (RFC §6.4). Zero value is "use defaults": DefaultPolicy fires on a fresh Tool.Policy at dispatch time.

Mirrors engine.NodePolicy (RFC §6.1): same backoff math, same validation modes. A flow registered as a tool gets BOTH layers — the outer ToolPolicy wraps the whole flow invocation; the per-node NodePolicy wraps each step inside the flow's engine. No double-wrapping at any single layer.

func DefaultPolicy() ToolPolicy

type ToolPolicyExhaustedPayload ¶

type ToolPolicyExhaustedPayload struct {
	events.SafeSealed
	Identity  identity.Quadruple
	ToolName  string
	Transport TransportKind
	Attempts  int
	LastClass ErrorClass
	LastError string
}

ToolPolicyExhaustedPayload is the typed payload for EventTypeToolPolicyExhausted. SafePayload.

type ToolProvider ¶

type ToolProvider interface {
	// Connect is called once at provider attach. Drivers establish
	// long-lived connections, authenticate, etc.
	Connect(ctx context.Context) error
	// Discover returns the current set of descriptors. May be
	// called periodically by the catalog manager.
	Discover(ctx context.Context) ([]ToolDescriptor, error)
	// Close releases provider resources. Must be idempotent.
	Close(ctx context.Context) error
	// SourceID is the stable identifier for this provider.
	SourceID() ToolSourceID
}

ToolProvider is the seam for external tool sources. later phases drivers (HTTP, MCP, A2A) implement Connect / Discover / Close to pull in remote tools as ToolDescriptors. The in-process registrar does not need a provider lifecycle (it's a thin wrapper around ToolCatalog.Register), so Harbor ships the interface shape without a default driver.

Identity-mandatory: Connect / Discover propagate identity via ctx so transports can scope their authentication.

type ToolResult ¶

type ToolResult struct {
	Value any
	Meta  map[string]any
}

ToolResult is the canonical result type returned by every ToolDescriptor.Invoke. Heavy outputs route through the ArtifactStore upstream; ToolResult.Value carries either typed Go values or ArtifactRef-shaped placeholders.

func RunWithPolicy(
	ctx context.Context,
	args json.RawMessage,
	invoke func(ctx context.Context, args json.RawMessage) (ToolResult, error),
	validateIn func(args json.RawMessage) error,
	validateOut func(result ToolResult) error,
	policy ToolPolicy,
) (ToolResult, error)

func RunWithPolicyHooked(
	ctx context.Context,
	args json.RawMessage,
	invoke func(ctx context.Context, args json.RawMessage) (ToolResult, error),
	validateIn func(args json.RawMessage) error,
	validateOut func(result ToolResult) error,
	policy ToolPolicy,
	hooks ...InvokeHooks,
) (ToolResult, error)

type ToolSearchCache ¶ added in v1.2.0

type ToolSearchCache interface {
	Search(ctx context.Context, query string, tags []string, limit int) ([]Tool, error)
	Sync(ctx context.Context, tools []Tool) error
	Close() error
}

ToolSearchCache is the tool search index surface the catalog delegates to. Defined here to avoid import cycles between internal/tools and internal/tools/drivers/searchcache.

type ToolSourceID ¶

type ToolSourceID string

ToolSourceID identifies the provider that produced a Tool. Empty for in-process tools (no provider lifecycle to track); populated for HTTP / MCP / A2A providers.

type TransportKind ¶

type TransportKind string

TransportKind discriminates a Tool's source. Same Tool struct regardless of Transport; the value lets observability + audit filter or annotate without re-shaping the Tool.

const (
	// TransportInProcess — a Go function registered via
	// drivers/inproc.RegisterFunc.
	TransportInProcess TransportKind = "inprocess"
	// TransportHTTP — (UTCP-style HTTP tool).
	TransportHTTP TransportKind = "http"
	// TransportMCP — (MCP southbound).
	TransportMCP TransportKind = "mcp"
	// TransportA2A — (A2A southbound).
	TransportA2A TransportKind = "a2a"
	// TransportFlow — (a typed DAG of Nodes registered as
	// a Tool via internal/runtime/flow.RegisterAsTool).
	TransportFlow TransportKind = "flow"
)

type ValidateMode ¶

type ValidateMode string

ValidateMode selects which side of an invocation the policy validates: input, output, both, or none. Mirrors engine.NodePolicy (RFC §6.1) so a developer who learned NodePolicy already knows ToolPolicy.

const (
	// ValidateNone disables validation. Escape hatch for hot paths.
	ValidateNone ValidateMode = ""
	// ValidateBoth runs validation on input AND output. Default for
	// production tools.
	ValidateBoth ValidateMode = "both"
	// ValidateIn runs validation on the input only.
	ValidateIn ValidateMode = "in"
	// ValidateOut runs validation on the output only.
	ValidateOut ValidateMode = "out"
)