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. AgentOptions installs the direct snapshot and prepare hook. Raw files under a Skill's scripts/ folder are never discovered as tools.
Index ¶
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" )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 whose name, description, source or tags contain every query term. It 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 ToolSearch ¶
type ToolSearch struct {
// contains filtered or unexported fields
}
ToolSearch provides Claude-style 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.
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) 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) 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.
type ToolSearchOptions ¶
type ToolSearchOptions struct {
Enabled bool
DeferredSources []string
Initial []agent.Tool
Limit int
MaxRuns int
}
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 tool_search; all other sources stay visible. An empty DeferredSources uses the Claude Code-like default: MCP and extension tools are deferred, while local and Team tools are direct.
Source Files