catalog

package
v0.1.6 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

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

Examples

Constants

View Source
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"
)
View Source
const DefaultActivationLimit = 64

DefaultActivationLimit bounds an ActivationSet created with a non-positive limit.

View Source
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

func SearchTokens(value string) []string

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

func ValidateToolSearchName(name string) error

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

type Authorizer func(context.Context, string, Descriptor) (bool, error)

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

func Merge(catalogs ...*Catalog) (*Catalog, error)

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 New

func New(entries ...Entry) (*Catalog, error)

New validates and indexes explicitly registered tools.

func (*Catalog) Search

func (c *Catalog) Search(ctx context.Context, policy Policy, query string) ([]Descriptor, error)

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.

func (*Catalog) Snapshot

func (c *Catalog) Snapshot(ctx context.Context, policy Policy) ([]agent.Tool, error)

Snapshot returns tools authorized for this tenant in registration order.

func (*Catalog) Tools

func (c *Catalog) Tools(ctx context.Context, policy Policy, names ...string) ([]agent.Tool, error)

Tools selects exact tool names from an already policy-gated catalog. It is used by deferred tool loading after the search result has been shown.

type Descriptor

type Descriptor struct {
	Name        string
	Description string
	Source      Source
	Risk        Risk
	Tags        []string
}

Descriptor is the immutable metadata visible to a policy decision.

type Entry

type Entry struct {
	Tool   agent.Tool
	Source Source
	Risk   Risk
	Tags   []string
}

Entry is one explicitly registered tool and its policy metadata.

func Extension

func Extension(extensionID string, risk Risk, tools ...agent.Tool) []Entry

Extension wraps tools contributed by an installed extension.

func Local

func Local(id string, risk Risk, tools ...agent.Tool) []Entry

Local wraps application-owned tools with local provenance.

func MCP

func MCP(server string, risk Risk, tools ...agent.Tool) []Entry

MCP wraps a snapshot returned by agent/mcp with server provenance.

func Team

func Team(teamID string, risk Risk, tools ...agent.Tool) []Entry

Team wraps a snapshot returned by agent/team with team provenance.

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.

func AllowAll

func AllowAll(tenantID string, maxRisk Risk) Policy

AllowAll deliberately opts into every registered tool up to maxRisk. It is intended for trusted single-tenant applications; multi-tenant hosts should supply a precise allowlist and Authorize function.

type Risk

type Risk uint8

Risk classifies the highest expected impact of a tool invocation.

const (
	RiskRead Risk = iota
	RiskWrite
	RiskPrivileged
)

Tool risk levels, ordered from least to most privileged.

type Source

type Source struct {
	Kind string
	ID   string
}

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 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

func (s *ToolSearch) AgentOptions(ctx context.Context) ([]agent.Option, error)

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) ExecutableTools added in v0.1.5

func (s *ToolSearch) ExecutableTools(ctx context.Context) ([]agent.Tool, error)

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

func (s *ToolSearch) Tools(ctx context.Context) ([]agent.Tool, error)

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. 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
}

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 Claude Code-like 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.

Jump to

Keyboard shortcuts

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