tools

package
v0.2.16 Latest Latest
Warning

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

 Go to latest Published: Oct 18, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateSkeleton 

func GenerateSkeleton(path string, src []byte) (string, int, error)

GenerateSkeleton returns a formatted skeleton string and total line count for a file.

func WithFileState 

func WithFileState(ctx context.Context, t *FileStateTracker) context.Context

WithFileState attaches a session's read-state tracker to the tool context.

func WithSessionBridge 

func WithSessionBridge(ctx context.Context, bridge SessionBridge) context.Context

WithSessionBridge attaches a session bridge to the context.

Types

type AskQuestion 

type AskQuestion struct {
	ID          string   `json:"id"`
	Question    string   `json:"question"`
	Header      string   `json:"header,omitempty"`
	Options     []string `json:"options"`
	Multi       bool     `json:"multi,omitempty"`
	Recommended int      `json:"recommended,omitempty"`
}

AskQuestion is a structured question the `ask` tool can pause the agent for.

type BackgroundTask 

type BackgroundTask struct {
	ID        string     `json:"id"`
	SessionID string     `json:"session_id"`
	Command   string     `json:"command"`
	Cwd       string     `json:"cwd,omitempty"`
	Status    TaskStatus `json:"status"`
	ExitCode  int        `json:"exit_code,omitempty"`
	StartedAt time.Time  `json:"started_at"`
	Finished  *time.Time `json:"finished_at,omitempty"`

	// OutputFile persists the full stdout+stderr stream so output survives
	// beyond the in-memory ring buffer (ZCode's artifact spill).
	OutputFile string `json:"output_file,omitempty"`
	OutputTail string `json:"output_tail,omitempty"`
	OutputSize int64  `json:"output_size"`
	// contains filtered or unexported fields
}

BackgroundTask is one detached shell command.

func (*BackgroundTask) TaskSnapshot 

func (t *BackgroundTask) TaskSnapshot() map[string]any

TaskSnapshot returns the JSON-friendly map representation of the task.

type CreatePluginPayload 

type CreatePluginPayload struct {
	ID           string            `json:"id"`
	Name         string            `json:"name"`
	Description  string            `json:"description"`
	Version      string            `json:"version,omitempty"`
	Author       string            `json:"author,omitempty"`
	Scope        string            `json:"scope,omitempty"`
	SystemPrompt string            `json:"system_prompt,omitempty"`
	Tools        []map[string]any  `json:"tools,omitempty"`
	Skills       []map[string]any  `json:"skills,omitempty"`
	Files        map[string]string `json:"files,omitempty"`
}

CreatePluginPayload defines parameters for creating a plugin via tool.

type FileStateTracker 

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

FileStateTracker mirrors the harness readFileState concept: it records which files the session has Read (mtime + size at read time) so edit/write can enforce read-before-edit and staleness checks. One tracker lives per agent session (in memory); tools only see it through the context, so standalone callers (tests, side chat) are never gated.

func FileStateFrom 

func FileStateFrom(ctx context.Context) *FileStateTracker

FileStateFrom returns the tracker attached to the context, if any.

func NewFileStateTracker 

func NewFileStateTracker() *FileStateTracker

func (*FileStateTracker) CheckFresh 

func (t *FileStateTracker) CheckFresh(path string) error

CheckFresh returns an error when the file has changed on disk since the last Read (by another process, a linter, the user…).

func (*FileStateTracker) MarkEdited 

func (t *FileStateTracker) MarkEdited(path string)

MarkEdited refreshes the snapshot after a successful edit/write so the model does not need to re-Read the file it just changed.

func (*FileStateTracker) MarkRead 

func (t *FileStateTracker) MarkRead(path string)

MarkRead records the file's current mtime/size as the read snapshot.

type MCPCaller 

type MCPCaller interface {
	CallTool(ctx context.Context, fullName string, args map[string]any) (string, error)
}

MCPCaller abstracts the MCP manager so the registry can dispatch MCP tool calls without importing the mcp package (avoiding an import cycle).

type Registry 

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

func NewRegistry 

func NewRegistry(searchMgr *search.SearchManager) *Registry

func (*Registry) Definitions 

func (r *Registry) Definitions() []llm.ToolDefinition

func (*Registry) DrainTaskNotifications 

func (r *Registry) DrainTaskNotifications(sessionID string) []TaskNotification

DrainTaskNotifications returns notifications for this session's tasks that reached a terminal state since the last drain, marking them consumed. The agent calls this at the start of every model step so the model learns a background command's outcome without polling.

func (*Registry) Execute 

func (r *Registry) Execute(ctx context.Context, name string, rawArgs string) (interface{}, error)

func (*Registry) GetTask 

func (r *Registry) GetTask(taskID string) (*BackgroundTask, bool)

GetTask returns a snapshot copy of a task.

func (*Registry) ListTasks 

func (r *Registry) ListTasks(sessionID string) []*BackgroundTask

ListTasks returns tasks for a session (all sessions when sessionID is empty), newest first.

func (*Registry) Lookup 

func (r *Registry) Lookup(name string) (ToolSpec, bool)

func (*Registry) Register 

func (r *Registry) Register(spec ToolSpec)

func (*Registry) RegisterMCPToolWithCaller 

func (r *Registry) RegisterMCPToolWithCaller(t llm.MCPTool, caller MCPCaller)

RegisterMCPToolWithCaller registers a single MCP tool and wires its handler RegisterMCPToolWithCaller registers a single MCP tool and wires its handler to the given caller.

func (*Registry) RegisterMCPTools 

func (r *Registry) RegisterMCPTools(tools []llm.MCPTool)

RegisterMCPTools registers tools discovered from MCP servers. Each tool's name is the full "server/tool" form so routing back to the right server is unambiguous. The handler delegates to the MCP manager's CallTool.

func (*Registry) SetMCPCaller 

func (r *Registry) SetMCPCaller(caller MCPCaller)

SetMCPCaller installs the MCP caller used by registered MCP tools.

func (*Registry) SetSessionFolderResolver 

func (r *Registry) SetSessionFolderResolver(fn func(sessionID string) string)

SetSessionFolderResolver registers the callback resolving a workspace folder for an agent session ID.

func (*Registry) SetTaskUpdateHandler 

func (r *Registry) SetTaskUpdateHandler(fn func(task *BackgroundTask))

SetTaskUpdateHandler installs the lifecycle callback invoked on every task transition (called once from the agent manager at construction).

func (*Registry) StartBackgroundCommand 

func (r *Registry) StartBackgroundCommand(sessionID, command, cwd string) (*BackgroundTask, error)

StartBackgroundCommand spawns a detached shell command and registers it as a background task owned by the given agent session. The process is detached from the caller's context on purpose: it must survive turn cancellation.

func (*Registry) StopTask 

func (r *Registry) StopTask(taskID string) bool

StopTask kills a running task's whole process group. Returns false when the task is unknown or already terminal.

func (*Registry) Unregister 

func (r *Registry) Unregister(name string)

func (*Registry) UnregisterMCPTools 

func (r *Registry) UnregisterMCPTools(serverName string)

UnregisterMCPTools removes previously registered MCP tools (used when MCP servers are reconnected or removed).

func (*Registry) WaitTask 

func (r *Registry) WaitTask(ctx context.Context, taskID string, timeout time.Duration) (*BackgroundTask, bool)

WaitTask blocks until the task reaches a terminal state or the timeout elapses. timeout <= 0 waits indefinitely (bounded by ctx).

type SearchResultItem 

type SearchResultItem struct {
	Title   string `json:"title"`
	URL     string `json:"url"`
	Snippet string `json:"snippet"`
}

type SessionBridge 

type SessionBridge interface {
	GetTodos() []TodoItem
	SetTodos(items []TodoItem)
	Ask(questions []AskQuestion) error
	// SessionID returns the owning agent session id (used to scope
	// background-task ownership and completion notifications).
	SessionID() string
	// GetWorkspaceFolder returns the workspace root the session is scoped to.
	// Tools use it as the default working directory instead of the process cwd
	// (which is "/" or the app bundle dir for a launched desktop app).
	GetWorkspaceFolder() string
	// TerminalExec runs a command in the session's persistent shell. Returns
	// output, exit code, error. If unavailable, tools should fall back to
	// spawning a one-shot shell.
	TerminalExec(command string, timeout time.Duration) (string, int, error)

	// Skills capabilities
	CreateSkill(name string, description string, body string, scope string, scripts map[string]string) (map[string]any, error)
	LoadSkill(name string) (map[string]any, error)
	ListSkills() ([]map[string]any, error)

	// Plugins capabilities
	CreatePlugin(payload CreatePluginPayload) (map[string]any, error)
	RegisterPlugin(manifest map[string]any) error
	ListPlugins() ([]map[string]any, error)
	TogglePlugin(id string, enabled bool) error

	// Memory capabilities
	LearnMemory(key string, content string, category string, scope string) error
	RecallMemory(query string) ([]map[string]any, error)
	ListMemories() ([]map[string]any, error)

	// Subagent capabilities
	SpawnSubagent(task string, role string) (string, error)
	SpawnSubagentWithModel(task string, role string, model string) (string, error)
	SelectSubagent(task string) (map[string]any, error)
	GetSubagents() []SubagentSummary
	WaitSubagent(ctx context.Context, subID string, timeout time.Duration) (map[string]any, error)

	// Scheduler / Timer capabilities
	ScheduleTimer(duration time.Duration, cronExpr string, prompt string, taskID string) (string, error)
	CancelSchedule(scheduleID string) bool
	ListSchedules() []map[string]any
}

SessionBridge is implemented by the agent manager and handed to tools via the context so tools can interact with the live session, skills, and plugins.

func SessionBridgeFrom 

func SessionBridgeFrom(ctx context.Context) SessionBridge

SessionBridgeFrom returns the session bridge from the context, if any.

type SingleEdit 

type SingleEdit struct {
	OldString  string `json:"old_string"`
	NewString  string `json:"new_string"`
	ReplaceAll bool   `json:"replace_all"`
}

SingleEdit represents one find-and-replace operation within a multiedit call.

type SubagentSummary 

type SubagentSummary struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Role     string `json:"role"`
	State    string `json:"state"`
	Folder   string `json:"folder"`
	ParentID string `json:"parent_id,omitempty"`
	Output   string `json:"output,omitempty"`
}

SubagentSummary summarizes a child agent session.

type TaskNotification 

type TaskNotification struct {
	TaskID   string
	Command  string
	Status   TaskStatus
	ExitCode int
	Tail     string
}

TaskNotification is a completed-task summary drained into the model's context (ZCode's <task-notification> pattern).

type TaskStatus 

type TaskStatus string

TaskStatus is the lifecycle state of a background task. 

const (
	TaskRunning   TaskStatus = "running"
	TaskCompleted TaskStatus = "completed" // exit code 0
	TaskFailed    TaskStatus = "failed"    // non-zero exit
	TaskStopped   TaskStatus = "stopped"   // killed via task_stop
)

type TodoItem 

type TodoItem struct {
	ID         string `json:"id"`
	Title      string `json:"title"`
	Status     string `json:"status"` // pending | in_progress | completed | blocked | abandoned
	ActiveForm string `json:"active_form,omitempty"`
	Phase      string `json:"phase,omitempty"`
	Blocker    string `json:"blocker,omitempty"`
}

TodoItem mirrors the agent session's task list in a tools-friendly shape.

type ToolHandler 

type ToolHandler func(ctx context.Context, args map[string]interface{}) (interface{}, error)

type ToolSpec 

type ToolSpec struct {
	Name        string
	Description string
	Parameters  map[string]interface{}
	// Cost is one of "cheap" (1pt), "medium" (3pt), "high" (10pt). Used for
	// the per-turn tool budget the agent sees in its system prompt.
	Cost       string
	Handler    ToolHandler
	IsMCP      bool
	ServerName string
}

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.