builtins

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Sep 25, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package builtins provides ready-to-use tool implementations.

Index

Constants

View Source 
const (
	FSWriteToolName  = "fs_write"
	FSReadToolName   = "fs_read"
	FSListToolName   = "fs_ls"
	FSDeleteToolName = "fs_delete"
)

VFS tool names.

View Source 
const MaxArtifactBytes = 5 << 20 // 5 MiB

MaxArtifactBytes caps the size of a single artifact written through fs_write. The VFS exists to offload large artifacts, but an unbounded write would let a misbehaving agent bloat the backing table (and later load the whole blob back into memory), so writes above this generous text-artifact limit are rejected.

View Source 
const PlanToolName = "update_plan"

PlanToolName is the name the model uses to update its plan.

Variables

View Source 
var ErrNoSession = errors.New("harness: no active session in context (use storage.WithSession)")

ErrNoSession is returned by any session-scoped harness primitive (the planning tool's PlanStore, the virtual filesystem's VFS) when the context carries no session id. These primitives are inherently per-session, so a sessionless call is a programming error, not an empty result — use storage.WithSession, ChatWithSession, or a graph run. The message is deliberately generic so it reads correctly from whichever primitive surfaced it.

Functions

func NewAutoShellTool 

func NewAutoShellTool(allowedCommands []string, timeout time.Duration) *tool.Definition

NewAutoShellTool creates a host shell tool.

SECURITY: this tool executes commands directly on the host with no isolation, so it defaults to tool.PermRequireApproval and never auto-runs on the host — regardless of its historical name. For unsupervised autonomous agents, use NewSandboxShellTool with a hardened sandbox.Sandbox: that is the only shell tool that may be auto-approved, because execution is confined to the sandbox boundary.

allowedCommands restricts which commands can run; an empty list means all are allowed. timeout controls max execution time (0 = 30s default).

func NewAutoShellToolAt added in v0.15.0 

func NewAutoShellToolAt(basePath string, allowedCommands []string, timeout time.Duration) *tool.Definition

NewAutoShellToolAt creates an approval-gated host shell rooted at basePath.

func NewCalculatorTool 

func NewCalculatorTool() *tool.Definition

NewCalculatorTool creates a tool that evaluates mathematical expressions.

func NewFSDeleteTool added in v0.10.0 

func NewFSDeleteTool(vfs VFS) *tool.Definition

NewFSDeleteTool returns a tool that deletes a stored artifact.

func NewFSListTool added in v0.10.0 

func NewFSListTool(vfs VFS) *tool.Definition

NewFSListTool returns a tool that lists stored artifacts (metadata only, no content) so the model can discover what it has offloaded.

func NewFSReadTool added in v0.10.0 

func NewFSReadTool(vfs VFS) *tool.Definition

NewFSReadTool returns a tool that pages an artifact back into context by path.

func NewFSWriteTool added in v0.10.0 

func NewFSWriteTool(vfs VFS) *tool.Definition

NewFSWriteTool returns a tool that saves an artifact to the virtual filesystem instead of the context window. It returns only the path and byte count — never the content — so writing a large artifact costs almost nothing in tokens.

func NewFileGlobTool 

func NewFileGlobTool(basePath string) *tool.Definition

NewFileGlobTool creates a tool that matches files using glob patterns.

func NewFileGrepTool 

func NewFileGrepTool(basePath string) *tool.Definition

NewFileGrepTool creates a tool that searches file contents for a pattern.

func NewFileListTool 

func NewFileListTool(basePath string) *tool.Definition

NewFileListTool creates a tool that lists files in a directory.

func NewFileReadTool 

func NewFileReadTool(basePath string) *tool.Definition

NewFileReadTool creates a tool that reads file contents.

func NewFileToolkit 

func NewFileToolkit(basePath string) *tool.Toolkit

NewFileToolkit creates a toolkit with all file tools.

func NewFileWriteTool 

func NewFileWriteTool(basePath string) *tool.Definition

NewFileWriteTool creates a tool that writes content to a file.

func NewHTTPTool 

func NewHTTPTool(timeout time.Duration, maxBodySize int64) *tool.Definition

NewHTTPTool creates a tool that makes HTTP requests. timeout controls max request time (0 = 30s default). maxBodySize limits response body read size (0 = 1MB default).

func NewPlanTool added in v0.10.0 

func NewPlanTool(store PlanStore, broker *stream.Broker) *tool.Definition

NewPlanTool returns the planning ("todo") tool bound to store. The model calls it with the full task list, which replaces the stored plan; the tool persists the plan for the session in context and, when broker is non-nil, publishes a stream.EventPlanUpdate so UIs can render progress. broker may be nil.

func NewPlanToolkit added in v0.10.0 

func NewPlanToolkit(store PlanStore, broker *stream.Broker) *tool.Toolkit

NewPlanToolkit wraps NewPlanTool in a toolkit so it can be added to an agent with agent.New(...).AddToolkit(builtins.NewPlanToolkit(store, broker)).

func NewSQLTool 

func NewSQLTool(db *sql.DB, allowedOperations []string) *tool.Definition

NewSQLTool creates a tool that executes SQL queries against a database. db is a *sql.DB connection. allowedOperations restricts which SQL operations are permitted (e.g., "SELECT", "INSERT"). An empty list allows only SELECT.

func NewSandboxShellTool 

func NewSandboxShellTool(sb sandbox.Sandbox, timeout time.Duration) *tool.Definition

NewSandboxShellTool creates a shell tool that executes commands inside a Sandbox. Commands run in isolation — the agent cannot escape the sandbox boundary.

func NewShellTool 

func NewShellTool(allowedCommands []string, timeout time.Duration) *tool.Definition

NewShellTool creates a tool that executes shell commands. allowedCommands restricts which commands can run; an empty list means all are allowed. timeout controls max execution time (0 = 30s default).

func NewShellToolAt added in v0.15.0 

func NewShellToolAt(basePath string, allowedCommands []string, timeout time.Duration) *tool.Definition

NewShellToolAt creates a host shell rooted at basePath unless a request context supplies a workspace override.

func NewSleepTool 

func NewSleepTool(maxDuration time.Duration) *tool.Definition

NewSleepTool creates a tool that pauses execution for a specified duration. maxDuration limits the maximum sleep time (0 means unlimited).

func NewVFSToolkit added in v0.10.0 

func NewVFSToolkit(vfs VFS) *tool.Toolkit

NewVFSToolkit bundles the virtual-filesystem tools (fs_write, fs_read, fs_ls, fs_delete) so an agent gains context-offloading scratch space with agent.New(...).AddToolkit(builtins.NewVFSToolkit(vfs)).

func NewWebSearchTool 

func NewWebSearchTool(timeout time.Duration, maxResults int) *tool.Definition

NewWebSearchTool creates a tool that searches the web using DuckDuckGo's instant answer API. timeout controls max request time (0 = 30s default). maxResults limits the number of results returned (0 = 5 default).

func NewWebSearchToolWithEngine 

func NewWebSearchToolWithEngine(engineURL string, timeout time.Duration) *tool.Definition

NewWebSearchToolWithEngine creates a web search tool that accepts a custom search URL template. The template must contain %s for the query placeholder.

func WithWorkspaceRoot added in v0.15.0 

func WithWorkspaceRoot(ctx context.Context, root string) context.Context

WithWorkspaceRoot returns a child context whose built-in filesystem and host shell tools resolve paths against root. The override is request-scoped and never mutates process state or a shared tool definition.

func WorkspaceRoot added in v0.15.0 

func WorkspaceRoot(ctx context.Context, configured string) string

WorkspaceRoot returns the request root when present, otherwise configured.

func WorkspaceRootFromContext added in v0.15.0 

func WorkspaceRootFromContext(ctx context.Context) (string, bool)

WorkspaceRootFromContext returns the request-scoped workspace root, if set.

Types

type InMemoryPlanStore added in v0.10.0 

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

InMemoryPlanStore is a process-local PlanStore keyed by (tenant, session). It is intended for tests and ephemeral use; it does not survive a process restart. Use StoragePlanStore for durable, resume-safe persistence.

func NewInMemoryPlanStore added in v0.10.0 

func NewInMemoryPlanStore() *InMemoryPlanStore

NewInMemoryPlanStore creates an empty in-memory plan store.

func (*InMemoryPlanStore) Load added in v0.10.0 

func (s *InMemoryPlanStore) Load(ctx context.Context) (*Plan, error)

Load returns a clone of the stored plan for the context's session, or an empty plan when none exists.

func (*InMemoryPlanStore) Save added in v0.10.0 

func (s *InMemoryPlanStore) Save(ctx context.Context, p *Plan) error

Save stores a clone of p for the context's session.

type InMemoryVFS added in v0.10.0 

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

InMemoryVFS is a process-local VFS keyed by (tenant, session, path). It is intended for tests and ephemeral use and does not survive a restart; use StorageVFS for durable, resume-safe artifacts.

func NewInMemoryVFS added in v0.10.0 

func NewInMemoryVFS() *InMemoryVFS

NewInMemoryVFS creates an empty in-memory virtual filesystem.

func (*InMemoryVFS) Delete added in v0.10.0 

func (v *InMemoryVFS) Delete(ctx context.Context, path string) error

Delete removes the artifact at path.

func (*InMemoryVFS) List added in v0.10.0 

func (v *InMemoryVFS) List(ctx context.Context, prefix string) ([]storage.FileInfo, error)

List returns metadata for artifacts with the given prefix, ordered by path.

func (*InMemoryVFS) Read added in v0.10.0 

func (v *InMemoryVFS) Read(ctx context.Context, path string) ([]byte, error)

Read returns a copy of the artifact at path.

func (*InMemoryVFS) Write added in v0.10.0 

func (v *InMemoryVFS) Write(ctx context.Context, path string, content []byte) error

Write stores a copy of content at path for the context's session.

type Plan added in v0.10.0 

type Plan struct {
	Tasks     []PlanTask `json:"tasks"`
	UpdatedAt time.Time  `json:"updated_at"`
}

Plan is a structured, revisable task list the agent maintains across turns so it does not lose track of subgoals on long, multi-step tasks. It is persisted per session (see PlanStore) so it survives checkpoints and resume.

func (*Plan) Clone added in v0.10.0 

func (p *Plan) Clone() *Plan

Clone returns a deep copy so callers never share the store's backing slice.

func (*Plan) Complete added in v0.10.0 

func (p *Plan) Complete() bool

Complete reports whether every task in the plan is completed. An empty plan is not considered complete.

func (*Plan) Summary added in v0.10.0 

func (p *Plan) Summary() string

Summary renders the plan as a human- and model-readable checklist, e.g. 

[x] 1. gather sources
[~] 2. draft report
[ ] 3. review

type PlanStore added in v0.10.0 

type PlanStore interface {
	Load(ctx context.Context) (*Plan, error)
	Save(ctx context.Context, p *Plan) error
}

PlanStore persists a single agent's plan, scoped to the session and tenant carried by the context (see storage.WithSession / storage.WithTenant). Load returns a non-nil empty plan when nothing has been saved yet, so callers never need a nil check. Both Load and Save require an active session (ErrNoSession otherwise); the two implementations are behaviorally substitutable.

ErrNoSession and the sessionScope gate are shared with the other session-scoped harness primitives (see session_scope.go).

type PlanTask added in v0.10.0 

type PlanTask struct {
	Content string     `json:"content"`
	Status  TaskStatus `json:"status"`
}

PlanTask is one entry in an agent's task list. Tasks are identified by their position in the plan: the model rewrites the whole list on every update, so a stable id would only go stale.

type StoragePlanStore added in v0.10.0 

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

StoragePlanStore persists the plan durably as a single mutable value in the session's Session.Metadata, via the storage.Storage backend. Because the plan is part of the session record, it survives process restarts and is restored when a worker resumes the session — without touching the runner's append-only event ledger or its sequence space. The session must already exist (created by the agent/runner run or ChatWithSession); reads and writes are tenant-scoped by the underlying adapter.

Save is serialized by an internal mutex so a read-modify-write of the session record cannot lose a concurrent update (e.g. two team agents sharing a session). Distributed single-writer-per-session is additionally guaranteed by the durable queue's leased dequeue.

func NewStoragePlanStore added in v0.10.0 

func NewStoragePlanStore(s storage.Storage) *StoragePlanStore

NewStoragePlanStore creates a durable, session-metadata-backed plan store.

func (*StoragePlanStore) Load added in v0.10.0 

func (s *StoragePlanStore) Load(ctx context.Context) (*Plan, error)

Load reads the current plan from the session's metadata, returning an empty plan when the session has no plan yet.

func (*StoragePlanStore) Save added in v0.10.0 

func (s *StoragePlanStore) Save(ctx context.Context, p *Plan) error

Save writes p into the session's metadata, preserving the rest of the session record. It is atomic with respect to concurrent Saves (see the type doc).

type StorageVFS added in v0.10.0 

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

StorageVFS is a durable VFS backed by a storage.SessionFileStore. Artifacts persist across process restarts and resume with the session.

func NewStorageVFS added in v0.10.0 

func NewStorageVFS(store storage.Storage) (*StorageVFS, error)

NewStorageVFS returns a durable VFS over store. It fails at construction (not at first use) when the backend does not implement storage.SessionFileStore, so misconfiguration surfaces immediately.

func (*StorageVFS) Delete added in v0.10.0 

func (v *StorageVFS) Delete(ctx context.Context, path string) error

Delete removes the artifact at path.

func (*StorageVFS) List added in v0.10.0 

func (v *StorageVFS) List(ctx context.Context, prefix string) ([]storage.FileInfo, error)

List returns metadata for artifacts with the given prefix.

func (*StorageVFS) Read added in v0.10.0 

func (v *StorageVFS) Read(ctx context.Context, path string) ([]byte, error)

Read returns the artifact at path.

func (*StorageVFS) Write added in v0.10.0 

func (v *StorageVFS) Write(ctx context.Context, path string, content []byte) error

Write persists content at path for the context's session.

type TaskStatus added in v0.10.0 

type TaskStatus string

TaskStatus is the lifecycle state of a single planned task. 

const (
	TaskPending    TaskStatus = "pending"     // not started
	TaskInProgress TaskStatus = "in_progress" // actively being worked on
	TaskCompleted  TaskStatus = "completed"   // finished
)

func (TaskStatus) Valid added in v0.10.0 

func (s TaskStatus) Valid() bool

Valid reports whether s is one of the recognized task statuses.

type VFS added in v0.10.0 

type VFS interface {
	// Write creates or overwrites the artifact at path.
	Write(ctx context.Context, path string, content []byte) error
	// Read returns the artifact at path, or an error (storage.ErrFileNotFound)
	// if it does not exist.
	Read(ctx context.Context, path string) ([]byte, error)
	// List returns metadata for every artifact whose path has the given prefix
	// (empty prefix lists all), ordered by path.
	List(ctx context.Context, prefix string) ([]storage.FileInfo, error)
	// Delete removes the artifact at path; deleting a missing path is a no-op.
	Delete(ctx context.Context, path string) error
}

VFS is a per-session, per-tenant virtual filesystem the agent uses as scratch space: it offloads large intermediate artifacts (research notes, drafts, tool output) out of the prompt and pages them back in by path on demand, keeping the context window small on long tasks. Paths are opaque keys within the session's namespace, not host filesystem paths, so there is no host access and no path-traversal surface.

Every method resolves the session from ctx (storage.WithSession); a sessionless call returns ErrNoSession, identical to PlanStore, so the two harness primitives behave consistently.

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.