tools

package
v0.1.98 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 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). The digest covers each operation's input-schema ref, so a changed operation schema is manifest drift; the schema's *content* is covered separately by the deployment snapshot's schema bundle (#207).

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"`
	// Schema is the operation's declared input-schema ref (the "→ schema" half of the manifest,
	// #204). Empty when the operation declares no input schema. Part of the manifest digest, so a
	// changed operation schema ref is manifest drift.
	Schema string `json:"schema,omitempty" yaml:"schema,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.