tools

package
v0.1.93 Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package tools defines tool registries and integrations (MCP, HTTP, native).

Registry resolves tool.<name>.<operation> uses strings and dispatches MVP native, mock, MCP stdio, and HTTP tools. ApplyMCPSafetyDiscovery merges MCP meta.mcp_flags into Tool safety during config resolution (issue #125). Responses use ToolCallResponse with output + meta per §13.2.

Index

Constants

View Source 
const MCPDiscoveryPerToolTimeout = 45 * time.Second

MCPDiscoveryPerToolTimeout bounds tools/list for one MCP Tool resource during config resolution. Windows CI under -race/-cover can take well over 10s to spawn a stdio subprocess (AV scan, scheduler delay); keep this high enough that a healthy mock handshake still succeeds.

Variables

This section is empty.

Functions

func FormatMCPDiscoveryWarning 

func FormatMCPDiscoveryWarning(w MCPDiscoveryWarning) string

FormatMCPDiscoveryWarning renders a warning for validate/plan output.

func GraphManifestDigest added in v0.1.93 

func GraphManifestDigest(g *spec.ProjectGraph) string

GraphManifestDigest returns a stable digest over every Tool's capability manifest in g. It is a single manifest-identity value for the closed callable universe of a resolved graph, for direct comparison across graphs. It is not the plan/apply pin (see CapabilityManifest.Digest): operation drift already changes each Tool's normalized spec hash.

func IsMCPDiscoveryTimeout 

func IsMCPDiscoveryTimeout(err error) bool

IsMCPDiscoveryTimeout reports whether err is a per-tool discovery timeout.

func ParseUses 

func ParseUses(uses string) (toolName string, operation string, err error)

ParseUses splits tool.github.pull_request.get into tool name "github" and operation "pull_request.get".

Types

type CapabilityManifest added in v0.1.93 

type CapabilityManifest struct {
	// Tool is the Tool resource name (the <name> in tool.<name>.<operation>).
	Tool string `json:"tool" yaml:"tool"`
	// Closed is the presence bit for the closed callable world: true when the Tool declares an
	// `operations` manifest at all (including an empty `operations: {}`). It is NOT len(Operations)
	// > 0 — an empty declared manifest is a *closed* world that denies every operation, while an
	// omitted manifest is an *open* world (backward compatible). Deriving closedness from the
	// operation count would invert the relation: shrinking a manifest to empty would widen it to
	// the universe.
	Closed bool `json:"closed" yaml:"closed"`
	// Operations are the allowed operations, sorted by name.
	Operations []ManifestOperation `json:"operations,omitempty" yaml:"operations,omitempty"`
}

CapabilityManifest is the closed set of operations a Tool may expose (issue #204, ADR 002).

It is the allowed-operation manifest referenced by the soundness section of ADR 002: the set of operations that may become agent-callable, each with its declared effects. The manifest is derived from the Tool's declared spec.operations — never from a live tools/list. Discovery may populate a desired manifest during authoring, but the deployed manifest (reconstructed from the applied Tool spec) is authoritative at run time.

A manifest is authored the same way for every transport (mcp, http, native): ToolHTTP carries the same exposure as MCP, so the closed-world mechanism is transport-agnostic.

func DeriveManifest added in v0.1.93 

func DeriveManifest(name string, ts *spec.ToolSpec) CapabilityManifest

DeriveManifest builds the capability manifest for one Tool from its declared operations. The result is order-stable: operations sorted by name, each effect set sorted and unique.

func ManifestFor added in v0.1.93 

func ManifestFor(g *spec.ProjectGraph, name string) CapabilityManifest

ManifestFor derives the capability manifest for tool name in g, or an open manifest when the tool is absent. Runtime enforcement uses this to deny operations outside a closed manifest.

func (CapabilityManifest) Allows added in v0.1.93 

func (m CapabilityManifest) Allows(op string) bool

Allows reports whether op is a member of a closed manifest. An open manifest (no declared operations) allows everything; a closed manifest allows only its declared operations.

func (CapabilityManifest) Digest added in v0.1.93 

func (m CapabilityManifest) Digest() string

Digest returns a stable SHA-256 hex digest of the manifest identity (tool, closed bit, operations, and each operation's effects).

This is a manifest-identity primitive, not a second pinning mechanism. Manifest drift — an operation appearing, disappearing, or changing its declared effects — is already reported by plan because spec.operations lives in the Tool's normalized spec, so it changes the resource spec hash that plan/apply already diff (issue #204 coordinates with the #112 resolved-config digest rather than adding a parallel pin). The digest exists for direct manifest comparison and for the forthcoming run-pinned deployment snapshot (#207). Note: an input schema per operation is not yet modeled on ToolOperation, so schema drift is out of scope until it is.

func (CapabilityManifest) IsClosed added in v0.1.93 

func (m CapabilityManifest) IsClosed() bool

IsClosed reports whether the Tool declares a manifest at all (the presence bit, not the operation count). A tool that declares no `operations` key has an open callable set: closed-world enforcement is opt-in, so existing MCP/HTTP examples without an operation manifest keep dispatching every operation. A declared-but-empty `operations: {}` is closed and denies all.

type MCPDiscoveryWarning 

type MCPDiscoveryWarning struct {
	Tool    string `json:"tool"`
	Message string `json:"message"`
}

MCPDiscoveryWarning reports a non-fatal MCP tools/list failure during safety discovery.

func ApplyMCPSafetyDiscovery 

func ApplyMCPSafetyDiscovery(ctx context.Context, g *spec.ProjectGraph) []MCPDiscoveryWarning

ApplyMCPSafetyDiscovery lists MCP tools for each Tool with type mcp, merges meta.mcp_flags into spec.safety (author-set fields win), and mutates g in place. Discovery failures for individual tools are reported as warnings; fail-closed defaults apply.

Discovery is never an authority source for the callable set (issue #204, ADR 002): it merges only spec.safety and never adds entries to the capability manifest (spec.operations). The closed world is the declared/deployed manifest, so a server advertising an extra operation via tools/list cannot widen what is agent-callable — see DeriveManifest and the runtime deny in internal/policy (ReasonOperationNotInManifest).

type ManifestOperation added in v0.1.93 

type ManifestOperation struct {
	// Name is the operation segment (the <operation> in tool.<name>.<operation>).
	Name string `json:"name" yaml:"name"`
	// Effects are the operation's declared effects, sorted and unique. Empty when the
	// operation declares no effects (still a closed-world member — it is callable).
	Effects []string `json:"effects,omitempty" yaml:"effects,omitempty"`
}

ManifestOperation is one allowed operation and the effects it may produce.

type MockExecutor 

type MockExecutor struct {
	Resp ToolCallResponse
	Err  error
	Fn   func(ctx context.Context, req ToolCallRequest) (ToolCallResponse, error)
}

MockExecutor returns a fixed response (or Fn) for tests.

func (*MockExecutor) Call 

func (m *MockExecutor) Call(ctx context.Context, req ToolCallRequest) (ToolCallResponse, error)

Call implements ToolExecutor.

type Registry 

type Registry struct {

	// Mock is optional; when set, ToolSpec type "mock" delegates here. Otherwise a canned JSON body is returned.
	Mock ToolExecutor
	// contains filtered or unexported fields
}

Registry resolves workflow uses strings against declared tools and dispatches by transport (MVP: native, mock, mcp stdio, http).

func NewRegistry 

func NewRegistry(g *spec.ProjectGraph) *Registry

NewRegistry builds a registry from the merged project graph.

func (*Registry) Call 

func (r *Registry) Call(ctx context.Context, req ToolCallRequest) (ToolCallResponse, error)

Call implements ToolExecutor by resolving Uses against the project graph.

type ToolCallMeta 

type ToolCallMeta struct {
	DurationMs int64
	CostUSD    float64
}

ToolCallMeta holds placeholder timing and cost (§13.2).

type ToolCallRequest 

type ToolCallRequest struct {
	Uses string
	With map[string]any
}

ToolCallRequest is a resolved workflow tool step (uses + with).

type ToolCallResponse 

type ToolCallResponse struct {
	Output map[string]any
	Meta   ToolCallMeta
}

ToolCallResponse matches the MVP step result envelope (§13.2): output + meta.

type ToolExecutor 

type ToolExecutor interface {
	Call(ctx context.Context, req ToolCallRequest) (ToolCallResponse, error)
}

ToolExecutor runs one tool operation (design doc §12.2 G).

type UnknownOperationError 

type UnknownOperationError struct {
	Tool      string
	Operation string
}

UnknownOperationError is returned when a native (or registered) tool does not implement the operation.

func (*UnknownOperationError) Error 

func (e *UnknownOperationError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package httptool runs Tool specs with type http (design doc §7.3, issue #20).
 Package httptool runs Tool specs with type http (design doc §7.3, issue #20).
Package mcp implements MCP tool transport per design doc §7.3.
 Package mcp implements MCP tool transport per design doc §7.3.
Package native implements built-in native tool operations (echo, identity, offline GitHub demo ops, and optional live GitHub REST operations when GITHUB_TOKEN is set).
 Package native implements built-in native tool operations (echo, identity, offline GitHub demo ops, and optional live GitHub REST operations when GITHUB_TOKEN is set).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.