toolpack

Documentation

Overview

Package toolpack turns an IR into a hot-loadable Rysh tool pack: a declarative manifest of tool definitions plus the live ToolExecutors that back them. It is the highest-leverage Forge target — the same manifest is exposed to agents either one-tool-per-operation (small specs) or via three dynamic meta-tools (large specs), per the context-budget policy (see exposure.go).

Index

• Constants
• func RegisterGRPCStreams(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, ...) []string
• func RegisterGraphQL(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.GraphQLExecutor, ...) []string
• func SanitizeName(name string) string
• type ExposureMode
• type Policy
• type ToolDef
• type ToolPack
  • func Build(api *ir.API, prefix string) *ToolPack
  • func (tp *ToolPack) JSON() ([]byte, error)
  • func (tp *ToolPack) Register(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, ...) ([]string, ExposureMode)

Constants

const DefaultDynamicThreshold = 50

DefaultDynamicThreshold mirrors Stainless's auto-switch (~50 methods).

const DefaultMaxTools = 200

DefaultMaxTools caps static registration to protect the context budget.

Functions

func RegisterGRPCStreams

func RegisterGRPCStreams(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, sm *runtime.StreamManager, pol Policy) []string

RegisterGRPCStreams installs the stream_start / stream_session pair for an API with server-streaming methods (api.Streams). No-op (nil) when the API has none. Returns the registered tool names.

func RegisterGraphQL

func RegisterGraphQL(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.GraphQLExecutor, sm *runtime.StreamManager, pol Policy) []string

RegisterGraphQL exposes a GraphQL API to agents through constant-footprint tools — <prefix>graphql_schema (discover query/mutation/subscription fields from the IR) and <prefix>graphql_query (execute a GraphQL document); when the schema has subscription fields AND sm is non-nil, it also registers <prefix>graphql_subscribe + <prefix>stream_session (streaming sessions over graphql-ws, design 015 §2.1). This mirrors the dynamic REST exposure: the agent discovers, then invokes, without flooding the context. Returns the registered tool names.

func SanitizeName

func SanitizeName(name string) string

SanitizeName coerces a name into Anthropic's tool name charset (^[a-zA-Z0-9_-]{1,64}$), folding invalid runes to '_' and truncating to 64.

Types

type ExposureMode

type ExposureMode string

ExposureMode controls how many tools a tool-pack advertises to the model — the central lever against "tool explosion" (a 400-operation API would both blow the context budget and degrade selection accuracy if registered 1:1).

const (
	ModeAuto    ExposureMode = ""        // dynamic above DynamicThreshold, else static
	ModeStatic  ExposureMode = "static"  // one tool per (filtered) operation
	ModeDynamic ExposureMode = "dynamic" // three constant meta-tools regardless of size
)

type Policy

type Policy struct {
	Mode             ExposureMode `json:"mode,omitempty"`
	DynamicThreshold int          `json:"dynamic_threshold,omitempty"`
	Tags             []string     `json:"tags,omitempty"`      // include only ops carrying one of these tags
	ReadOnly         bool         `json:"read_only,omitempty"` // include only GET/HEAD
	MaxTools         int          `json:"max_tools,omitempty"`
	ForceApproval    bool         `json:"force_approval,omitempty"` // gate ALL calls (else mutating-only)
	Prefix           string       `json:"prefix,omitempty"`
}

Policy is the per-integration exposure configuration.

type ToolDef

type ToolDef struct {
	Name        string          `json:"name"`         // sanitized, prefixed tool name
	OperationID string          `json:"operation_id"` // IR operation id (used by invoke_endpoint)
	Method      string          `json:"method"`
	Path        string          `json:"path"`
	Summary     string          `json:"summary,omitempty"`
	Tags        []string        `json:"tags,omitempty"`
	Mutating    bool            `json:"mutating"`
	InputSchema json.RawMessage `json:"input_schema"`
}

ToolDef is one operation rendered as an agent-callable tool.

type ToolPack

type ToolPack struct {
	Name        string          `json:"name"`
	Version     string          `json:"version"`
	Description string          `json:"description,omitempty"`
	BaseURL     string          `json:"base_url,omitempty"`
	Auth        []ir.AuthScheme `json:"auth,omitempty"`
	Tools       []ToolDef       `json:"tools"`
}

ToolPack is the generated, serializable manifest for an API.

func Build

func Build(api *ir.API, prefix string) *ToolPack

Build produces a ToolPack from the IR. prefix is prepended to every tool name (e.g. "stripe_") for namespacing; pass "" for none.

func (*ToolPack) JSON

func (tp *ToolPack) JSON() ([]byte, error)

JSON renders the manifest as indented JSON (the artifact form).

func (*ToolPack) Register

func (tp *ToolPack) Register(reg *sharedtools.ToolRegistry, api *ir.API, exec *runtime.HTTPExecutor, pol Policy) ([]string, ExposureMode)

Register installs the tool-pack's executors into reg according to the policy. It returns the registered tool names and the effective exposure mode. exec is the shared HTTP runtime (already carrying credentials + redaction).