Documentation
¶
Overview ¶
Package toolcat is the tool catalog + MCP broker. Two layers of "tool": the capabilities the agent SEES (typed, schema'd, role-scoped entries here) and the binaries that BACK them (in-image CLIs, sidecar services, external MCP servers). The catalog is the declarative source of truth for "what exists"; the broker (broker.go) is the single gated endpoint the agent talks to — list/describe for runtime discovery, route + output-cap + role-scope on invoke. Every entry is PINNED (content-addressed) so the provisioned set is reproducible and a replay re-provisions byte-identically (evidence log).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CatalogHash ¶
CatalogHash is a single digest over the pinned set — a compact replay key.
Types ¶
type AgentTool ¶
type AgentTool struct {
// contains filtered or unexported fields
}
func (AgentTool) Description ¶
func (AgentTool) Schema ¶
func (a AgentTool) Schema() json.RawMessage
type Broker ¶
type Broker struct {
Tools []Tool // already role-scoped
Exec Execer // for in-image CLIs
MCP MCPCaller
DefaultTimeout time.Duration // default 60s
DefaultCap int // default 64 KiB
// contains filtered or unexported fields
}
Broker is the single gated endpoint the agent talks to. It surfaces the role-scoped catalog (list/describe), routes each call to its backend, and enforces per-tool timeouts + output caps. It is deliberately synchronous request/response to match the agent's tool-call loop; the async execution_id job model (for long tools like fuzzers) layers on top later.
func (*Broker) AgentTools ¶
AgentTools returns broker tools adapted to the agent Tool shape.
type Catalog ¶
type Catalog struct {
Tools []Tool `yaml:"tools"`
}
Catalog is the loaded set of recipes.
type Execer ¶
type Execer interface {
Exec(ctx context.Context, cmd string, args []string, stdin string, timeout time.Duration) (stdout, stderr string, exit int, err error)
}
Execer runs an in-image CLI. The agent's Workspace satisfies it (adapted in the loop), so an in-image tool inherits the SAME execution boundary as the agent's exec — inside the container sandbox when one is configured (item 4).
type MCPCaller ¶
type MCPCaller interface {
CallTool(ctx context.Context, command []string, tool string, args json.RawMessage, timeout time.Duration) (string, error)
}
MCPCaller invokes a named tool on an external MCP backend (stdio server argv + tool name + JSON args → text result). internal/mcp satisfies it. Optional: a nil caller means external-mcp/sidecar tools are advertised-but-unavailable.
type Tool ¶
type Tool struct {
ID string `yaml:"id"`
Kind Kind `yaml:"kind"`
Description string `yaml:"description"`
Schema string `yaml:"schema"` // MCP input JSON-Schema (raw JSON string)
Cmd string `yaml:"cmd"` // in-image: program to run
FixedArgs []string `yaml:"fixed_args"` // in-image: args prepended before the agent's args
Command []string `yaml:"command"` // external-mcp: server launch argv (stdio transport)
MCPTool string `yaml:"mcp_tool"` // external-mcp/sidecar: the server-side tool name (default = ID)
Roles []string `yaml:"roles"` // role scope; empty ⇒ available to all roles
Pin string `yaml:"pin"` // REQUIRED content/digest pin (…@sha256:… / sha256:… / cas:…)
TimeoutS int `yaml:"timeout_s"` // per-call timeout (0 → broker default)
OutputCap int `yaml:"output_cap"` // max bytes of captured output (0 → broker default)
}
Tool is one declarative catalog recipe.
Source Files