tools

package
v0.9.3 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 31 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrToolNotFound is returned when a tool is not registered
	ErrToolNotFound = errors.New("tool not found")

	// ErrToolAlreadyRegistered is returned when trying to register a duplicate tool name.
	ErrToolAlreadyRegistered = errors.New("tool already registered")
)

Standard errors

Functions

func DeployToolNames added in v0.8.8 

func DeployToolNames() []string

DeployToolNames lists the app-hosting tools. Meta-agents (orchestrator, builder) are denied these alongside the shell/build tools — a router dispatches build+deploy work to specialists, it doesn't host apps itself.

func RegisterBuiltinServer added in v0.6.0 

func RegisterBuiltinServer(name string, server *BuiltinMCPServer) error

RegisterBuiltinServer adds an in-process MCP server to the global registry under the given name. After this returns nil, agents can connect via Tools.ConnectBuiltinServer(ctx, name) and tools will be registered as <name>__<toolname>.

Returns an error if the name is already taken — re-registration is not supported (use a different name or restart the process).

func RegisterEmailTool 

func RegisterEmailTool(t *Tools)

RegisterEmailTool registers the send_email built-in tool. SMTP configuration is read from environment variables at call time:

  • SMTP_HOST (required)
  • SMTP_PORT (default 587)
  • SMTP_USER (required)
  • SMTP_PASS (required)
  • SMTP_FROM (defaults to SMTP_USER)

func ShellExecToolNames added in v0.8.7 

func ShellExecToolNames() []string

ShellExecToolNames lists the shell/execution + background-service tools. Meta-agents (orchestrator, builder) are denied these: a router that can shell out builds and hosts deliverables itself instead of dispatching to a specialist (the TonyVega exec meltdown). The DSL layer strips these from any IsMeta agent's surface.

func ToolNameFromContext added in v0.9.0 

func ToolNameFromContext(ctx context.Context) string

ToolNameFromContext returns the name of the tool currently executing, or "" outside a tool execution.

func WikiMemoryToolNames added in v0.7.13 

func WikiMemoryToolNames() []string

WikiMemoryToolNames is the canonical list of wiki memory tools every agent gets in its tool surface. The DSL layer pulls this into the always-available bucket so a per-agent Tools allow-list never gates memory access: every agent sees the shared user wiki and can write durable facts back to it. Refs govega#71.

The actual implementations live in serve/memory_wiki_tools.go because they need a Store. Co-locating the names here lets the DSL layer reference them without pulling in the storage dependency.

Types

type AppDeployment added in v0.8.8 

type AppDeployment struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	URL      string `json:"url"`
	Provider string `json:"provider"`
}

AppDeployment is a hosted app.

type AppHost added in v0.8.8 

type AppHost interface {
	// Deploy makes an app reachable and returns its URL + a teardown handle.
	Deploy(ctx context.Context, spec AppSpec) (AppDeployment, error)
	// Destroy tears down a deployment by id.
	Destroy(ctx context.Context, id string) error
	// List returns the currently-hosted deployments.
	List(ctx context.Context) ([]AppDeployment, error)
}

AppHost hosts an agent-built app and returns a reachable URL. Implementations range from an in-process subprocess+reverse-proxy (the vendor-neutral default, serve.LocalAppHost) to an isolated cloud machine (a FlyAppHost provider). The agent that calls deploy_app never learns which — that keeps the agent surface free of vendor lock-in. Providers are wired by the host via SetAppHost.

See docs/app-hosting-design.md.

type AppSpec added in v0.8.8 

type AppSpec struct {
	Name       string     `json:"name"`
	Source     string     `json:"source"`  // workspace-relative directory
	Command    []string   `json:"command"` // empty ⇒ static file serving
	Port       int        `json:"port"`    // internal port for dynamic apps
	Visibility Visibility `json:"visibility"`
	DataAccess DataAccess `json:"data_access"`
}

AppSpec describes an app to host.

type BuiltinMCPServer added in v0.6.0 

type BuiltinMCPServer struct {
	// contains filtered or unexported fields
}

BuiltinMCPServer is an in-process Go-native MCP server. Embedding applications register additional servers via RegisterBuiltinServer.

govega ships only generic, agent-runtime-essential builtins (e.g. fetch). Vendor-specific integrations live in the consuming product and call RegisterBuiltinServer at startup.

func NewBuiltinMCPServer added in v0.6.0 

func NewBuiltinMCPServer(tools map[string]ToolDef) *BuiltinMCPServer

NewBuiltinMCPServer constructs a server with the given tool defs. The caller still has to call RegisterBuiltinServer to make it discoverable by name from agents.

type DataAccess added in v0.8.8 

type DataAccess string

DataAccess controls whether the app can reach the tenant's data. 

const (
	// DataAccessNone (default) — the app is fully isolated from tenant data.
	DataAccessNone DataAccess = "none"
	// DataAccessTenantAPI — the app may call the tenant API with injected
	// identity (the App Contract). No shared filesystem.
	DataAccessTenantAPI DataAccess = "tenant_api"
)

type DynamicParamDef 

type DynamicParamDef struct {
	Name        string   `yaml:"name"`
	Type        string   `yaml:"type"`
	Description string   `yaml:"description"`
	Required    bool     `yaml:"required"`
	Default     any      `yaml:"default"`
	Enum        []string `yaml:"enum"`
}

DynamicParamDef is a YAML parameter definition.

type DynamicToolDef 

type DynamicToolDef struct {
	Name           string            `yaml:"name"`
	Description    string            `yaml:"description"`
	Params         []DynamicParamDef `yaml:"params"`
	Implementation DynamicToolImpl   `yaml:"implementation"`
}

DynamicToolDef is a YAML tool definition.

type DynamicToolImpl 

type DynamicToolImpl struct {
	Type    string            `yaml:"type"` // http, exec, file_read, file_write, builtin
	Method  string            `yaml:"method"`
	URL     string            `yaml:"url"`
	Headers map[string]string `yaml:"headers"`
	Query   map[string]string `yaml:"query"`
	Body    any               `yaml:"body"`
	Command string            `yaml:"command"`
	Path    string            `yaml:"path"`
	Timeout string            `yaml:"timeout"`
}

DynamicToolImpl is a YAML implementation definition.

type MCPServerOption 

type MCPServerOption func(*mcpServerOptions)

MCPServerOption configures MCP server behavior.

func WithMCPAutoConnect 

func WithMCPAutoConnect(enabled bool) MCPServerOption

WithMCPAutoConnect enables automatic connection on first tool call.

func WithMCPTimeout 

func WithMCPTimeout(d time.Duration) MCPServerOption

WithMCPTimeout sets the timeout for MCP operations.

type MCPServerStatus 

type MCPServerStatus struct {
	Name      string   `json:"name"`
	Connected bool     `json:"connected"`
	Transport string   `json:"transport,omitempty"`
	URL       string   `json:"url,omitempty"`
	Command   string   `json:"command,omitempty"`
	Tools     []string `json:"tools"`
}

MCPServerStatus describes the status of a connected MCP server.

type ParamDef 

type ParamDef struct {
	Type        string   `json:"type" yaml:"type"`
	Description string   `json:"description" yaml:"description"`
	Required    bool     `json:"required" yaml:"required"`
	Default     any      `json:"default,omitempty" yaml:"default,omitempty"`
	Enum        []string `json:"enum,omitempty" yaml:"enum,omitempty"`
}

ParamDef defines a tool parameter.

type SkillsRef 

type SkillsRef interface {
	GetMatchedSkills() []skills.SkillMatch
}

SkillsRef is a narrow interface for skill-based tool augmentation. *vega.SkillsPrompt satisfies this interface.

type ToolDef 

type ToolDef struct {
	Description string
	Fn          any
	Params      map[string]ParamDef
}

ToolDef allows explicit tool definition with schema.

type ToolError 

type ToolError struct {
	ToolName string
	Err      error
}

ToolError wraps errors with tool context.

func (*ToolError) Error 

func (e *ToolError) Error() string

func (*ToolError) Unwrap 

func (e *ToolError) Unwrap() error

type ToolFunc 

type ToolFunc func(ctx context.Context, params map[string]any) (string, error)

ToolFunc is the signature for tool execution.

type ToolMiddleware 

type ToolMiddleware func(ToolFunc) ToolFunc

ToolMiddleware wraps tool execution. The executing tool's name is available via ToolNameFromContext, so one middleware can gate or observe specific tools (approval prompts, auditing, rate limits).

type Tools 

type Tools struct {

	// OnFileWrite is called after a successful write_file or append_file operation.
	// Parameters: ctx, relative path, operation ("write"/"append"), description.
	OnFileWrite func(ctx context.Context, path, operation, description string)
	// contains filtered or unexported fields
}

Tools is a collection of callable tools.

func NewTools 

func NewTools(opts ...ToolsOption) *Tools

NewTools creates a new Tools collection.

func (*Tools) ActiveProject added in v0.2.0 

func (t *Tools) ActiveProject() string

ActiveProject returns the current active project name, or "" if none.

func (*Tools) BaseURL added in v0.4.2 

func (t *Tools) BaseURL() string

BaseURL returns the configured server base URL.

func (*Tools) BuiltinServerConnected added in v0.2.0 

func (t *Tools) BuiltinServerConnected(name string) bool

BuiltinServerConnected reports whether a built-in server's tools are already registered.

func (*Tools) ConnectBuiltinServer added in v0.2.0 

func (t *Tools) ConnectBuiltinServer(ctx context.Context, name string) (int, error)

ConnectBuiltinServer registers all tools from a built-in Go MCP server implementation. Tools are registered with the standard "servername__toolname" prefix. Returns the number of tools registered.

func (*Tools) ConnectMCP 

func (t *Tools) ConnectMCP(ctx context.Context) error

ConnectMCP connects all MCP servers and discovers their tools.

func (*Tools) ConnectMCPServer added in v0.2.0 

func (t *Tools) ConnectMCPServer(ctx context.Context, config mcp.ServerConfig) (int, error)

ConnectMCPServer connects a single MCP server by config at runtime, discovers its tools, and registers them. Returns the number of tools found.

func (*Tools) ContainerAvailable 

func (t *Tools) ContainerAvailable() bool

ContainerAvailable returns whether container execution is available.

func (*Tools) DisconnectBuiltinServer added in v0.3.0 

func (t *Tools) DisconnectBuiltinServer(name string) error

DisconnectBuiltinServer unregisters all tools from a built-in Go MCP server.

func (*Tools) DisconnectMCP 

func (t *Tools) DisconnectMCP() error

DisconnectMCP disconnects all MCP servers.

func (*Tools) DisconnectMCPServer added in v0.2.1 

func (t *Tools) DisconnectMCPServer(name string) error

DisconnectMCPServer disconnects a single MCP server by name, removes it from the client list, and unregisters all its tools.

func (*Tools) Execute 

func (t *Tools) Execute(ctx context.Context, name string, params map[string]any) (string, error)

Execute calls a tool by name.

func (*Tools) Filter 

func (t *Tools) Filter(names ...string) *Tools

Filter returns a new Tools with only the specified tools.

func (*Tools) FilterMCP 

func (t *Tools) FilterMCP(patterns ...string) *Tools

FilterMCP returns a new Tools with only tools from specified MCP servers. Supports patterns like "server__*" to include all tools from a server.

func (*Tools) GetSettings added in v0.2.0 

func (t *Tools) GetSettings() map[string]string

GetSettings returns a copy of the current settings map.

func (*Tools) HasBuiltinServer added in v0.2.0 

func (t *Tools) HasBuiltinServer(name string) bool

HasBuiltinServer reports whether a Go-native implementation exists for the named MCP server.

func (*Tools) LoadDirectory 

func (t *Tools) LoadDirectory(path string) error

LoadDirectory loads tool definitions from YAML files.

func (*Tools) LoadFile 

func (t *Tools) LoadFile(path string) error

LoadFile loads a single tool definition from YAML.

func (*Tools) MCPServerConnected added in v0.2.0 

func (t *Tools) MCPServerConnected(name string) bool

MCPServerConnected reports whether a server with the given name is already connected.

func (*Tools) MCPServerStatuses 

func (t *Tools) MCPServerStatuses() []MCPServerStatus

MCPServerStatuses returns the status of all configured MCP servers.

func (*Tools) ReadMCPResource 

func (t *Tools) ReadMCPResource(ctx context.Context, serverName, uri string) (string, error)

ReadMCPResource reads a resource from a specific MCP server by name.

func (*Tools) Register 

func (t *Tools) Register(name string, fn any) error

Register adds a tool to the collection. The function can be: - func(params) string - func(params) (string, error) - func(ctx, params) (string, error) - ToolDef with explicit schema

func (*Tools) RegisterBuiltins 

func (t *Tools) RegisterBuiltins()

RegisterBuiltins adds the built-in tools.

func (*Tools) RegisterDynamicTool 

func (t *Tools) RegisterDynamicTool(def DynamicToolDef) error

RegisterDynamicTool registers a tool from a DynamicToolDef.

func (*Tools) Sandbox added in v0.2.0 

func (t *Tools) Sandbox() string

Sandbox returns the base sandbox path (without project subdirectory).

func (*Tools) Schema 

func (t *Tools) Schema() []llm.ToolSchema

Schema returns the schemas for all tools. If a skillsRef is set, tools declared by matched skills are also included.

func (*Tools) SetActiveProject added in v0.2.0 

func (t *Tools) SetActiveProject(name string)

SetActiveProject sets the active project name for workspace subdirectories. All file and exec operations will target sandbox/<project>/ when set. Pass an empty string to clear the active project.

func (*Tools) SetAppHost added in v0.8.8 

func (t *Tools) SetAppHost(h AppHost)

SetAppHost wires the app-hosting provider. Called by the host (serve wires LocalAppHost by default; v39a wires a FlyAppHost). nil ⇒ deploy_app reports that hosting isn't configured.

func (*Tools) SetBaseURL added in v0.4.2 

func (t *Tools) SetBaseURL(url string)

SetBaseURL sets the server base URL after construction.

func (*Tools) SetProject 

func (t *Tools) SetProject(name string)

SetProject sets the active project for container routing.

func (*Tools) SetSetting added in v0.3.0 

func (t *Tools) SetSetting(key, value string)

SetSetting sets a single setting key-value pair, merging into existing settings.

func (*Tools) SetSettings added in v0.2.0 

func (t *Tools) SetSettings(m map[string]string)

SetSettings replaces the tool settings map used for dynamic tool interpolation.

func (*Tools) SetURLSigner added in v0.8.8 

func (t *Tools) SetURLSigner(f func(urlPath string) string)

SetURLSigner injects the capability-token signer used to sign deliverable URLs. Returns "" for a path when gating is off (open mode).

func (*Tools) Use 

func (t *Tools) Use(mw ToolMiddleware)

Use adds middleware to the tool chain.

func (*Tools) WithSkillsRef 

func (t *Tools) WithSkillsRef(sp SkillsRef) *Tools

WithSkillsRef returns a shallow copy with a skills prompt reference set. When Schema() is called, tools declared by matched skills are included.

type ToolsOption 

type ToolsOption func(*Tools)

ToolsOption configures Tools.

func WithBaseURL added in v0.4.2 

func WithBaseURL(url string) ToolsOption

WithBaseURL sets the server base URL for constructing deliverable URLs in tool responses (e.g. write_file returns the accessible URL).

func WithContainer 

func WithContainer(cm *container.Manager) ToolsOption

WithContainer enables container-based tool execution.

func WithContainerRouting 

func WithContainerRouting(toolNames ...string) ToolsOption

WithContainerRouting specifies which tools should be routed to containers.

func WithMCPServer 

func WithMCPServer(config mcp.ServerConfig) ToolsOption

WithMCPServer adds an MCP server to the tools collection. Tools from the server will be prefixed with "server_name__tool_name".

func WithSandbox 

func WithSandbox(path string) ToolsOption

WithSandbox restricts file operations to a directory.

type Visibility added in v0.8.8 

type Visibility string

Visibility controls who can reach a deployment's URL. 

const (
	// VisibilityPortalGated (default) requires a portal session or a
	// capability token scoped to the app — the safe default for a
	// multi-tenant host.
	VisibilityPortalGated Visibility = "portal_gated"
	// VisibilityPublic is reachable by anyone with the link.
	VisibilityPublic Visibility = "public"
	// VisibilityPrivate requires an authenticated portal session.
	VisibilityPrivate Visibility = "private"
)

Source Files

View all Source files

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.