Documentation
¶
Overview ¶
Package catalog composes explicitly registered agent tools into policy-gated snapshots. It deliberately does not discover executables from skill folders: scripts become callable only after a host wraps them as an agent.Tool or MCP tool and assigns provenance and risk.
Package catalog provides the application composition boundary for agent tools. A Catalog holds explicitly registered local, MCP, and Team snapshots with provenance and risk. A Policy then creates a tenant-scoped, deny-by- default snapshot suitable for agent.WithTools.
Merge combines several immutable Catalogs while preserving their entry order and policy metadata. Duplicate tool names remain errors rather than receiving an implicit precedence.
ToolSearch implements optional, source-aware deferred discovery. With ToolSearchOptions{Enabled: true}, local and Team tools stay direct while MCP and extension tools are deferred by default; DeferredSources customizes that policy. The discovery tool is named DefaultToolSearchName unless Name overrides it, is only advertised while at least one authorized deferred tool exists, and ranks Search results by name, parameter, and description hits. AgentOptions installs the executable snapshot and prepare hook. Raw files under a Skill's scripts/ folder are never discovered as tools.
Index ¶
- Constants
- func FormatSourceSummaries(sources []SourceSummary) string
- func SearchTokens(value string) []string
- func ValidateToolSearchName(name string) error
- type ActivationSet
- type Authorizer
- type Catalog
- type Descriptor
- type Entry
- type Policy
- type Risk
- type Source
- type SourceSummary
- type ToolSearch
- func (s *ToolSearch) AgentOptions(ctx context.Context) ([]agent.Option, error)
- func (s *ToolSearch) BeforeTool(ctx context.Context, info agent.ToolCallInfo) agent.ToolDecision
- func (s *ToolSearch) DeferredSources(ctx context.Context) ([]SourceSummary, error)
- func (s *ToolSearch) Dispatch(ctx context.Context, name string, input ai.JSON) ([]ai.Part, error)
- func (s *ToolSearch) ExecutableTools(ctx context.Context) ([]agent.Tool, error)
- func (s *ToolSearch) Forget(runID string)
- func (s *ToolSearch) Name() string
- func (s *ToolSearch) PrepareTurn(ctx context.Context, info agent.RunInfo) agent.TurnUpdate
- func (s *ToolSearch) Tools(ctx context.Context) ([]agent.Tool, error)
- type ToolSearchOptions
- type UseToolDispatch
Examples ¶
Constants ¶
const ( // SourceLocal identifies a tool implemented by the application process. SourceLocal = "local" // SourceMCP identifies a tool from an MCP server snapshot. SourceMCP = "mcp" // SourceExtension identifies a tool supplied by an installed extension. SourceExtension = "extension" // SourceTeam identifies a Team-scoped agent tool. SourceTeam = "team" )
const DefaultActivationLimit = 64
DefaultActivationLimit bounds an ActivationSet created with a non-positive limit.
const DefaultToolSearchName = "pips_tool_search"
DefaultToolSearchName is the namespaced discovery tool name used when ToolSearchOptions.Name is empty. The pips_ prefix avoids collisions with proxies and providers that reserve or rewrite the bare "tool_search" name.
Variables ¶
This section is empty.
Functions ¶
func FormatSourceSummaries ¶ added in v0.1.5
func FormatSourceSummaries(sources []SourceSummary) string
FormatSourceSummaries joins summaries for a prompt or hint sentence.
func SearchTokens ¶ added in v0.1.5
SearchTokens returns the lowercase tokens that Search matches a query term against. Values split on non-alphanumerics and camelCase boundaries, and one trailing plural "s" is removed from tokens of four or more characters so "tools" and "tool" compare equal. The same tokenizer is exposed so callers can rank tool names consistently with Search.
func ValidateToolSearchName ¶ added in v0.1.5
ValidateToolSearchName reports whether name is portable across providers: one to sixty-four ASCII letters, digits, underscores, or dashes.
Types ¶
type ActivationSet ¶ added in v0.1.5
type ActivationSet struct {
// contains filtered or unexported fields
}
ActivationSet remembers deferred tool names activated by ToolSearch across runs, for example for the lifetime of one application session. It stores names only: every snapshot re-authorizes them against the current catalog and policy, so a name that is no longer registered or authorized is silently skipped. The set is bounded; the least recently activated name is evicted first. It is safe for concurrent use.
func NewActivationSet ¶ added in v0.1.5
func NewActivationSet(limit int) *ActivationSet
NewActivationSet returns an empty set holding at most limit names.
func (*ActivationSet) Add ¶ added in v0.1.5
func (s *ActivationSet) Add(names ...string)
Add records names as the most recent activations.
func (*ActivationSet) Contains ¶ added in v0.1.5
func (s *ActivationSet) Contains(name string) bool
Contains reports whether name is currently activated.
func (*ActivationSet) Names ¶ added in v0.1.5
func (s *ActivationSet) Names() []string
Names returns the activated names, least recently activated first.
type Authorizer ¶
Authorizer can make tenant-specific decisions after static allowlist and risk checks pass. Returning false hides the tool from the snapshot.
type Catalog ¶
type Catalog struct {
// contains filtered or unexported fields
}
Catalog is immutable after construction and safe for concurrent snapshots.
func Merge ¶
Merge combines immutable catalogs in argument order. It preserves each entry's tool, provenance, risk, and tags, and returns an independent Catalog. A nil input or duplicate tool name is an error; no inputs produce an empty Catalog.
Example ¶
package main
import (
"context"
"fmt"
"github.com/rsbin1178/pips/agent"
"github.com/rsbin1178/pips/agent/catalog"
)
func main() {
read := agent.NewTool("read_doc", "Read a document", func(context.Context, struct{}) (string, error) {
return "", nil
})
lookup := agent.NewTool("remote_lookup", "Look up documentation", func(context.Context, struct{}) (string, error) {
return "", nil
})
local, _ := catalog.New(catalog.Local("app", catalog.RiskRead, read)...)
remote, _ := catalog.New(catalog.MCP("docs", catalog.RiskRead, lookup)...)
merged, _ := catalog.Merge(local, remote)
tools, _ := merged.Snapshot(context.Background(), catalog.AllowAll("example", catalog.RiskRead))
for _, tool := range tools {
fmt.Println(tool.Decl().Name)
}
}
Output: read_doc remote_lookup
func (*Catalog) Search ¶
Search returns policy-authorized descriptors. An empty query returns every authorized descriptor in registration order. A non-empty query ranks candidates by relevance: each term is matched against the tool name, top-level parameter names, and the free text formed by the description, parameter descriptions, source, and tags. Name and parameter hits outweigh text hits, and a tool is a candidate when at least one term matches. Ties break on name. Search never exposes a Tool implementation.
type Descriptor ¶
Descriptor is the immutable metadata visible to a policy decision.
type Entry ¶
Entry is one explicitly registered tool and its policy metadata.
type Policy ¶
type Policy struct {
TenantID string
Allowlist []string
MaxRisk Risk
Authorize Authorizer
}
Policy bounds a snapshot. It is deny-by-default: callers must provide an allowlist or use AllowAll deliberately. MaxRisk defaults to RiskRead.
type Source ¶
Source identifies how a tool reached the application composition root. The catalog never imports optional MCP or team packages; their callers pass the snapshots through the corresponding constructor helpers below.
type SourceSummary ¶ added in v0.1.5
type SourceSummary struct {
Kind string `json:"kind"`
ID string `json:"id"`
Tools int `json:"tools"`
}
SourceSummary counts the policy-authorized deferred tools registered under one source. It is reported to the model so a miss can be distinguished from an empty registry.
func (SourceSummary) String ¶ added in v0.1.5
func (s SourceSummary) String() string
String renders the summary as kind/id (count).
type ToolSearch ¶
type ToolSearch struct {
// contains filtered or unexported fields
}
ToolSearch provides deferred tool discovery without exposing every declaration on the first model request. Add Tools() when building the agent and use PrepareTurn as its prepare-turn hook. Search results are policy-filtered before they reach the model, then re-authorized when the snapshot is applied. An enabled surface may also offer a dispatch Tool that reaches a hidden tool by name (ToolSearchOptions.UseTool).
func NewToolSearch ¶
func NewToolSearch(catalog *Catalog, policy Policy, options ToolSearchOptions) (*ToolSearch, error)
NewToolSearch constructs a source-aware tool configuration. policy must explicitly authorize every eventual target; an empty allowlist produces an empty tool snapshot. Call Tools with the construction context, then install PrepareTurn only when Enabled is true.
func (*ToolSearch) AgentOptions ¶
AgentOptions builds the options needed to install this configuration. It keeps direct tools visible and adds the prepare hook only when search is on.
func (*ToolSearch) BeforeTool ¶ added in v0.1.5
func (s *ToolSearch) BeforeTool(ctx context.Context, info agent.ToolCallInfo) agent.ToolDecision
BeforeTool denies a call to a registered, authorized deferred tool that is not active for the calling run, telling the model to activate it through the discovery tool first. Without it, such a call fails as an unknown tool. Every other call is allowed; install it before ordinary policy gates.
func (*ToolSearch) DeferredSources ¶ added in v0.1.5
func (s *ToolSearch) DeferredSources(ctx context.Context) ([]SourceSummary, error)
DeferredSources summarizes the policy-authorized deferred tools grouped by source in registration order. It is empty when nothing can be discovered, whether because search is disabled or no deferred tool is registered.
func (*ToolSearch) Dispatch ¶ added in v0.1.9
Dispatch runs one call to a tool the current snapshot hides. name is resolved through the catalog with this surface's policy, so an unauthorized tool is refused exactly as a direct call would be and an unknown name is refused by name, which the catalog's own message carries.
A name the current snapshot already shows is refused with a correction: the wrapper carries only what the snapshot hides, so a visible tool must be called as its own tool call. That rule is load-bearing rather than cosmetic. Every operation pips gates behind an approval permit — shell and monitor — is a local tool, so it is directly visible, so this refusal stops the call before any dispatch; the stop Tool is local too, so the same refusal covers it. A dispatch that reached one would run its Exec without the permit its BeforeTool gate issues.
Every other name runs with the given arguments, and the resolved tool's own result, content or error, is returned unchanged.
func (*ToolSearch) ExecutableTools ¶ added in v0.1.5
ExecutableTools returns Tools plus, when search is enabled but nothing is deferred, a hidden copy of the discovery tool. The copy is omitted from model requests yet executes when called by name, answering with the registry hint. Pass this slice to agent.WithTools.
func (*ToolSearch) Forget ¶
func (s *ToolSearch) Forget(runID string)
Forget removes one run's deferred selection early. It is useful when a host chains its event handler and observes agent.EventRunCompleted.
func (*ToolSearch) Name ¶ added in v0.1.5
func (s *ToolSearch) Name() string
Name returns the discovery tool name the model must call.
func (*ToolSearch) PrepareTurn ¶
func (s *ToolSearch) PrepareTurn(ctx context.Context, info agent.RunInfo) agent.TurnUpdate
PrepareTurn returns the complete next-turn snapshot. It must be installed through agent.WithPrepareTurn; the agent runtime validates the replacement before showing it to the model.
func (*ToolSearch) Tools ¶
Tools returns the model-visible toolset: the application built-ins and all direct catalog tools. When deferred search is enabled and at least one authorized deferred tool exists, it additionally returns the discovery tool; when search is disabled it returns every policy-authorized catalog tool. A surface built with a dispatch Tool returns that too. Use it for prompts and visibility decisions.
type ToolSearchOptions ¶
type ToolSearchOptions struct {
Enabled bool
Name string
DeferredSources []string
Initial []agent.Tool
Limit int
MaxRuns int
Activations *ActivationSet
UseTool func(UseToolDispatch) agent.Tool
}
ToolSearchOptions controls deferred loading behavior. Initial tools are application built-ins and remain visible on every snapshot. When Enabled is false, every policy-authorized catalog tool is exposed normally. When true, only DeferredSources are discovered through the discovery tool; all other sources stay visible. An empty DeferredSources uses the conventional default: MCP and extension tools are deferred, while local and Team tools are direct. Name overrides DefaultToolSearchName; it must satisfy ValidateToolSearchName and must not collide with a catalog or Initial tool. Activations, when non-nil, keeps activated deferred tools visible beyond the activating run: every later snapshot of any ToolSearch sharing the set includes them, re-authorized by policy. When nil, an activation lasts only for the run that performed it. UseTool, when non-nil, builds the model-facing dispatch Tool from this surface's own dispatcher (see ToolSearch.Dispatch). It is called only when Enabled is true, so a disabled surface, and a surface built without it, offer no dispatch Tool.
type UseToolDispatch ¶ added in v0.1.9
UseToolDispatch runs one call to a tool the current snapshot hides. It is the one dispatcher the dispatch Tool carries: it resolves a target name with the caller's policy, refuses a name the snapshot already shows, and returns the resolved tool's own result.