tools

package
v0.10.0 Latest Latest
Warning

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

 Go to latest Published: Aug 10, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Overview

Package tools declares the typed tool registry exposed to the model. The definitions (names + JSON schemas) live here; the runtime owns execution so that permission gating, event capture and post-command diff detection stay in one place. v0 registry: read_file, ripgrep, bash, git_diff, edit_file.

Index

Constants

View Source 
const (
	ReadFile         = "read_file"
	ListDir          = "list_dir"
	Glob             = "glob" // recursive file discovery by name pattern (repofiles-backed; excludes hidden/ignored)
	Ripgrep          = "ripgrep"
	CodeQuery        = "code_query" // deterministic "where does X live" — ranked evidence in one call (no model loop)
	Bash             = "bash"
	MCPCodeExec      = "mcp_code_exec" // orchestrate the connected MCP servers from a Python script ("code execution with MCP"); only the printed result returns
	GitDiff          = "git_diff"
	EditFile         = "edit_file"
	ApplyPatch       = "apply_patch"       // multi-file, all-or-nothing edits (coherent refactor lands whole or rolls back)
	MCP              = "mcp"               // the MCP meta-tool: search/schema/call over connected servers (schemas disclosed on demand, never inlined)
	MCPResource      = "mcp_resource"      // list/read MCP resources (external context: docs, schemas, runbooks)
	MCPPrompt        = "mcp_prompt"        // list/get MCP prompt templates
	GitHub           = "github"            // typed PR/issue/CI surface over gh (structured, not shell-string fiddling)
	RunTests         = "run_tests"         // run the repo's tests and return a STRUCTURED pass/fail summary (not raw log)
	Diagnostics      = "diagnostics"       // type/compile diagnostics for a file or the repo (gopls/go build, tsc) — see errors without guessing
	CodeNav          = "code_nav"          // semantic navigation via LSP: go-to-definition, find-references, hover-for-type
	RepoMap          = "repo_map"          // ranked, token-budgeted symbol map (personalized PageRank over the reference graph)
	Memcode          = "memcode"           // dispatcher into memcode's own intelligence (read-only)
	Todo             = "todo"              // dispatcher for the agent's own work-tracker checklist
	Explore          = "explore"           // spawn a read-only sub-agent to investigate one facet (map/reduce)
	AskUser          = "ask_user"          // human-in-the-loop: ask the user a clarifying question on a critical fork
	WebSearch        = "web_search"        // search the web for a query
	Fetch            = "fetch"             // fetch a specific URL and return its text
	Skill            = "skill"             // recruit an installed skill's expert guidance on demand (gated)
	Script           = "script"            // save/find/run/delete a reusable multi-step command sequence (each gated ONCE at the script level, not per inner command)
	Artifact         = "artifact"          // publish/update/list/delete a self-contained HTML page hosted at memcode.ai (publish gated)
	Knowledge        = "knowledge"         // consult memcode's baseline facts/idioms for a stack (ungated reference)
	Trace            = "trace"             // trace an artifact across pipeline stages to locate where data is lost (alias: wiretap)
	EnterPlan        = "enter_plan"        // switch into research-and-approve plan mode (offered in normal chat only)
	CancelPlan       = "cancel_plan"       // CANCEL/ABANDON plan mode on the user's behalf (plan mode only; never executes, never presents). Renamed from exit_plan: models carry a Claude Code prior where "exit plan mode" means "present the plan" — that name got plans silently abandoned.
	ExecutePlan      = "execute_plan"      // APPROVE+execute the plan when the user says so (plan mode only) → apply phase
	Dispatch         = "dispatch"          // offload a discrete block of work to a hands-off background sub-agent
	Agent            = "agent"             // first-class sub-agent: run a task on a chosen tier (fast/strong), report the result back
	RecallPlan       = "recall_plan"       // list / retrieve a previously saved plan from the user-level plans store
	Reasoning        = "reasoning"         // adaptive reasoning: inspect/adjust OWN thinking depth mid-turn, or delegate a hard sub-problem to the strong reasoning model
	PreferenceSignal = "preference_signal" // capture a durable user taste/constraint to remember (LLM-captured, reducer-promoted)

	// Browser tools — only advertised when --chrome is set (gated in toolDefs).
	BrowserNavigate   = "browser_navigate"   // load a URL in the current Chrome tab
	BrowserClick      = "browser_click"      // click an element by CSS selector
	BrowserType       = "browser_type"       // type text into an element by CSS selector
	BrowserScreenshot = "browser_screenshot" // capture the current page as an image (vision)
	BrowserEval       = "browser_eval"       // run JavaScript in the page and return the result
	BrowserText       = "browser_text"       // get the visible text content of the current page
	BrowserScroll     = "browser_scroll"     // scroll the page by x/y pixel deltas
	BrowserPressKey   = "browser_press_key"  // send a keyboard event (Enter, Escape, Tab, arrows)
	BrowserHover      = "browser_hover"      // hover over an element (trigger hover states/menus)
	BrowserSelect     = "browser_select"     // pick an option in a <select> dropdown
	BrowserBack       = "browser_back"       // navigate to the previous page in history
	BrowserForward    = "browser_forward"    // navigate to the next page in history
	BrowserConsole    = "browser_console"    // read captured console.log/error messages
	BrowserNewTab     = "browser_new_tab"    // open a new tab and switch to it
	BrowserSwitchTab  = "browser_switch_tab" // switch focus to a different tab
	BrowserCloseTab   = "browser_close_tab"  // close a tab
	BrowserListTabs   = "browser_list_tabs"  // list all open tabs
)

Tool names (stable identifiers shared by the model and the runtime).

Variables

View Source 
var MemcodeCommands = []string{
	"overview", "map", "context", "why", "recall", "next", "recap", "memories", "claims", "sources", "session", "acceptance", "doctor", "jobs", "preferences",
}

MemcodeCommands are the introspection subcommands the `memcode` tool dispatches to. One tool, one schema — cheap context, structured calls (no shell strings).

View Source 
var PreferenceAxes = []string{"workflow", "gating", "verbosity", "style", "tooling"}

PreferenceAxes is the vocabulary for preference_signal's `axis` field. The axis drives clustering in the reducer — same-axis signals are candidates to merge.

View Source 
var TodoActions = []string{"create", "add", "start", "done", "block", "skip", "update", "show"}

TodoActions are the actions the `todo` tool dispatches to.

Functions

func BrowserDefs 

func BrowserDefs() []wire.ToolDef

BrowserDefs returns the browser tool schemas, advertised only when --chrome is set. They drive a real Chrome instance (via CDP) so the agent can fully interact with web pages as a user would: navigate, click, type, scroll, hover, keyboard, dropdowns, history, tabs, screenshots, console logs, and JS. Screenshots come back as image blocks (vision) through the tool_result content union. Actions that change page state (navigate/click/type/scroll/hover/press/ select/back/forward/new_tab/close_tab) are Medium (they act on the world); screenshot/eval/text/console/list_tabs are Safe (read-only).

func Defs 

func Defs() []wire.ToolDef

Defs returns the tool schemas advertised to the model.

Types

type AgentInput 

type AgentInput struct {
	Task       string `json:"task"`                 // the self-contained instruction for the sub-agent
	Context    string `json:"context,omitempty"`    // optional background the sub-agent needs (it starts fresh)
	Tier       string `json:"tier,omitempty"`       // "fast" (cheap, default) | "strong" (Anthropic — non-code/hard/quality work)
	ReadOnly   bool   `json:"readonly,omitempty"`   // true = investigate/generate only (no edits); false = a full mutating agent
	Background bool   `json:"background,omitempty"` // true = run detached and report the result back when done (don't block this turn)
}

AgentInput drives the first-class agent tool: run a self-contained task on a chosen tier, read-only or mutating, and get the result back.

type ApplyPatchInput 

type ApplyPatchInput struct {
	Edits []EditFileInput `json:"edits"`
}

ApplyPatchInput is a set of edits applied ATOMICALLY: validate all, apply all, or roll back all. For a coherent multi-file change (rename + all call sites) that must not half-land. Each edit is the same shape as edit_file.

type ArtifactInput 

type ArtifactInput struct {
	Action string `json:"action"`          // publish | update | list | delete
	Path   string `json:"path,omitempty"`  // repo-relative path to the HTML file (publish/update)
	Title  string `json:"title,omitempty"` // display title (publish; optional on update)
	ID     string `json:"id,omitempty"`    // artifact id from a prior publish (update/delete)
}

ArtifactInput drives the artifact tool: publish a LOCAL self-contained HTML file as a shareable page at memcode.ai/code/artifact/<id>.

type AskOption 

type AskOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
}

AskOption is one candidate answer: a concise Label (the choice the user picks) and an optional Description (a muted clarifying line shown beneath it, à la a Claude-Code selector). It decodes tolerantly from EITHER a plain JSON string (→ Label, no description) or an object {label, description}, because models are inconsistent about which they emit — see UnmarshalJSON.

func (*AskOption) UnmarshalJSON 

func (o *AskOption) UnmarshalJSON(b []byte) error

UnmarshalJSON accepts an ask option as EITHER a plain string (a bare label) or an object {label, description}. Models are inconsistent about which they emit, so we tolerate both rather than dropping options that arrived as strings.

type AskUserInput 

type AskUserInput struct {
	Question string      `json:"question"`
	Options  []AskOption `json:"options,omitempty"` // 2-4 choices; the user may also type their own
}

AskUserInput poses a clarifying question to the user (human-in-the-loop).

type BashInput 

type BashInput struct {
	Command    string `json:"command"`
	Cwd        string `json:"cwd,omitempty"`
	Background bool   `json:"background,omitempty"` // long-running (dev server/watcher): run detached, don't block
}

Input payloads, one per tool.

type BrowserClickInput 

type BrowserClickInput struct {
	Selector string `json:"selector"`
}

BrowserClickInput clicks an element by CSS selector.

type BrowserCloseTabInput 

type BrowserCloseTabInput struct {
	Index int `json:"index"` // 1-based tab number
}

BrowserCloseTabInput closes a tab by 1-based index.

type BrowserConsoleInput 

type BrowserConsoleInput struct {
	Level string `json:"level,omitempty"` // filter by level: log, error, warn, info, debug, exception
}

BrowserConsoleInput reads captured console messages.

type BrowserEvalInput 

type BrowserEvalInput struct {
	Script string `json:"script"`
}

BrowserEvalInput runs a JavaScript expression in the page and returns the result.

type BrowserHoverInput 

type BrowserHoverInput struct {
	Selector string `json:"selector"`
}

BrowserHoverInput hovers over an element by CSS selector.

type BrowserNavigateInput 

type BrowserNavigateInput struct {
	URL string `json:"url"`
}

BrowserNavigateInput loads a URL in the Chrome tab.

type BrowserPressKeyInput 

type BrowserPressKeyInput struct {
	Key string `json:"key"` // "Enter", "Escape", "Tab", "Backspace", "Space", "ArrowUp/Down/Left/Right", or a single char
}

BrowserPressKeyInput sends a keyboard event to the page.

type BrowserScreenshotInput 

type BrowserScreenshotInput struct {
	FullPage bool `json:"full_page,omitempty"`
}

BrowserScreenshotInput captures the current page as a PNG image (vision). Default is the viewport; full_page captures the entire scrollable page (larger — more tokens).

type BrowserScrollInput 

type BrowserScrollInput struct {
	DX int `json:"dx,omitempty"` // horizontal pixels (positive = right)
	DY int `json:"dy,omitempty"` // vertical pixels (positive = down)
}

BrowserScrollInput scrolls the page by pixel deltas.

type BrowserSelectInput 

type BrowserSelectInput struct {
	Selector string `json:"selector"`
	Value    string `json:"value"`
}

BrowserSelectInput picks an option in a <select> by value.

type BrowserSwitchTabInput 

type BrowserSwitchTabInput struct {
	Index int `json:"index"` // 1-based tab number
}

BrowserSwitchTabInput switches to a tab by 1-based index.

type BrowserTypeInput 

type BrowserTypeInput struct {
	Selector string `json:"selector"`
	Text     string `json:"text"`
}

BrowserTypeInput types text into an element by CSS selector.

type CodeNavInput 

type CodeNavInput struct {
	Action string `json:"action"`
	Path   string `json:"path"`
	Line   int    `json:"line"`
	Col    int    `json:"col"`
	Depth  int    `json:"depth,omitempty"`
}

CodeNavInput drives the code_nav tool: a semantic query at a 1-based line/col in a file. action = definition | references | hover | impact. depth applies to impact.

type CodeQueryInput 

type CodeQueryInput struct {
	Query string `json:"query"`
	Scope string `json:"scope,omitempty"` // optional path prefix to focus on
}

CodeQueryInput locates code by a natural-language question, deterministically.

type DiagnosticsInput 

type DiagnosticsInput struct {
	Path string `json:"path,omitempty"`
}

DiagnosticsInput drives the diagnostics tool: optional path (a file or dir) to scope the check. Empty = the whole repo.

type DispatchInput 

type DispatchInput struct {
	Task string `json:"task"`
	Mode string `json:"mode,omitempty"` // "auto" (default) | "allow-all"
}

DispatchInput offloads a discrete block of work to a hands-off background sub-agent. The sub-agent runs the full mutating agent loop (edits, bash, tests) with NO prompts or clarifying questions — 100% autonomous. It reports back a summary when done.

type EditFileInput 

type EditFileInput struct {
	Path       string `json:"path"`
	OldString  string `json:"old_string,omitempty"`
	NewString  string `json:"new_string"`
	ReplaceAll bool   `json:"replace_all,omitempty"`
}

Input payloads, one per tool.

type EnterPlanInput 

type EnterPlanInput struct {
	Yolo bool `json:"yolo,omitempty"`
}

EnterPlanInput optionally requests yolo planning (auto-resolve questions + auto-execute on approval). cancel_plan takes no input — it's cancel-only.

type ExploreInput 

type ExploreInput struct {
	Question string `json:"question"`
	Scope    string `json:"scope,omitempty"` // optional subsystem/path to focus on
	Focus    string `json:"focus,omitempty"` // optional angle (e.g. "entrypoints, schema, tests")
}

ExploreInput dispatches a read-only sub-agent investigation of one facet.

type FetchInput 

type FetchInput struct {
	URL string `json:"url"`
}

FetchInput fetches a specific URL and returns its (text) content.

type GitDiffInput 

type GitDiffInput struct {
	Path string `json:"path,omitempty"`
}

Input payloads, one per tool.

type GitHubInput 

type GitHubInput struct {
	Action string `json:"action"`           // pr_view | pr_list | issue_view | issue_list | checks | pr_create | comment
	Number int    `json:"number,omitempty"` // PR/issue number (pr_view/issue_view/comment; checks uses current branch if 0)
	Title  string `json:"title,omitempty"`  // pr_create
	Body   string `json:"body,omitempty"`   // pr_create / comment
	Base   string `json:"base,omitempty"`   // pr_create base branch (default the repo default)
}

GitHubInput drives the github tool — a typed surface over `gh`. Read actions (pr_view/pr_list/issue_view/issue_list/checks) run directly; write actions (pr_create/comment) go through the permission gate.

type GlobInput 

type GlobInput struct {
	Pattern       string `json:"pattern"`
	IncludeHidden bool   `json:"include_hidden,omitempty"`
	MaxResults    int    `json:"max_results,omitempty"`
}

Input payloads, one per tool.

type KnowledgeInput 

type KnowledgeInput struct {
	Find  string `json:"find,omitempty"`  // search query → matching pack names
	Topic string `json:"topic,omitempty"` // exact pack name → its full Facts + Idioms (ungated)
}

KnowledgeInput drives the knowledge tool: FIND packs by topic, or get one by name/topic.

type ListDirInput 

type ListDirInput struct {
	Path string `json:"path,omitempty"`
}

Input payloads, one per tool.

type MCPCodeExecInput 

type MCPCodeExecInput struct {
	Script               string `json:"script"`
	SaveSkill            string `json:"save_skill,omitempty"`             // slug (lowercase-hyphen) to save the script as a skill
	SaveSkillDescription string `json:"save_skill_description,omitempty"` // one-line description for the saved skill
}

MCPMCPCodeExecInput drives the mcp_code_exec tool: a Python 3 script that calls a whitelisted set of read-only memcode tools as functions and prints ONLY the distilled answer. save_skill (+ description) optionally persists the script as a reusable skill under .memcode/skills/ — only when the user asked for it.

type MCPInput 

type MCPInput struct {
	Action string          `json:"action"`          // search | schema | call
	Query  string          `json:"query,omitempty"` // search filter (empty = list all)
	Tool   string          `json:"tool,omitempty"`  // required for schema/call
	Args   json.RawMessage `json:"args,omitempty"`  // call arguments per the tool's schema
}

MCPInput drives the mcp meta-tool: action "search" (find tools by query), "schema" (one tool's input schema on demand), or "call" (invoke — gated per call).

type MCPPromptInput 

type MCPPromptInput struct {
	Action string            `json:"action"`         // list | get
	Name   string            `json:"name,omitempty"` // required for get (namespaced)
	Args   map[string]string `json:"args,omitempty"` // template arguments for get
}

MCPPromptInput drives the mcp_prompt tool: action "list" (catalog) or "get" (render a template with args).

type MCPResourceInput 

type MCPResourceInput struct {
	Action string `json:"action"`        // list | read
	URI    string `json:"uri,omitempty"` // required for read
}

MCPResourceInput drives the mcp_resource tool: action "list" (catalog) or "read" (fetch a resource's contents by uri).

type MemcodeInput 

type MemcodeInput struct {
	Command string `json:"command"`
	Target  string `json:"target,omitempty"` // path/subsystem for context/why
	Query   string `json:"query,omitempty"`  // question for recall
	Limit   int    `json:"limit,omitempty"`
}

Input payloads, one per tool.

type PreferenceSignalInput 

type PreferenceSignalInput struct {
	Text  string `json:"text"`
	Axis  string `json:"axis"`
	Scope string `json:"scope,omitempty"`
}

PreferenceSignalInput captures a durable user taste/constraint the model wants memcode to remember. The reducer clusters these by axis + lexical similarity and promotes a cluster to a standing preference once it crosses the evidence bar (≥3 signals, ≥2 sessions, weighted score ≥ 2.0). Call this when the user states a FORCEFUL, REPEATED directive ("always X", "never Y", "stop doing Z") — NOT for one-off tasks, explorations, or ordinary preferences.

type ReadFileInput 

type ReadFileInput struct {
	Path string `json:"path"`
	// Optional 1-based inclusive line range — a re-verification read fetches
	// the region it needs instead of re-paying the whole file. 0 = unset.
	StartLine int `json:"start_line,omitempty"`
	EndLine   int `json:"end_line,omitempty"`
	// Attach (PDFs only): send the file ITSELF to the model as a native
	// document instead of locally extracted text — for layout/charts/scans.
	// Costs far more tokens (per-page image billing), so it's opt-in.
	Attach bool `json:"attach,omitempty"`
}

Input payloads, one per tool.

type ReasoningInput 

type ReasoningInput struct {
	Task    string `json:"task,omitempty"`
	Context string `json:"context,omitempty"`
	Effort  string `json:"effort,omitempty"` // off | medium | high | auto
}

ReasoningInput drives the adaptive-reasoning tool: bare effort = self-adjust (or report when everything is empty); task (+context, +effort) = delegate to the strong reasoning model.

type RecallPlanInput 

type RecallPlanInput struct {
	Slug string `json:"slug,omitempty"`
}

RecallPlanInput retrieves a saved plan. Empty slug → the most recent plan (plus a list of older ones); a slug → that specific plan's markdown.

type RepoMapInput 

type RepoMapInput struct {
	Focus        string `json:"focus,omitempty"`
	BudgetTokens int    `json:"budget_tokens,omitempty"`
}

RepoMapInput drives the repo_map tool: optional focus terms (paths or symbol names, space-separated) to center the map on, and a token budget.

type RipgrepInput 

type RipgrepInput struct {
	Query string `json:"query"`
	Path  string `json:"path,omitempty"`
}

Input payloads, one per tool.

type RunTestsInput 

type RunTestsInput struct {
	Path string `json:"path,omitempty"` // package/dir to scope the run (default: whole repo)
	Run  string `json:"run,omitempty"`  // test-name pattern to filter (go -run / pytest -k / jest -t)
}

RunTestsInput drives the run_tests tool: optional path (a package/dir to scope to) and run (a name pattern to filter). Empty = the whole repo's tests.

type ScriptInput 

type ScriptInput struct {
	Save        string `json:"save,omitempty"`        // slug (lowercase-hyphen) to save/update — pairs with description + command (gated)
	Description string `json:"description,omitempty"` // one-line description for `save`
	Command     string `json:"command,omitempty"`     // the command body for `save`
	Run         string `json:"run,omitempty"`         // exact saved slug to execute (gated once, at the script level — its contents are NOT re-classified)
	Background  bool   `json:"background,omitempty"`  // `run`: start detached instead of blocking (long-running scripts)
	List        bool   `json:"list,omitempty"`        // list every saved script (read-only)
	Find        string `json:"find,omitempty"`        // search saved scripts by topic (read-only)
	Delete      string `json:"delete,omitempty"`      // exact saved slug to remove — soft-deleted to .trash (gated)
}

ScriptInput drives the script tool: SAVE/DELETE/RUN each get exactly ONE coarse permission decision (never a deep look inside the script — its commands were already approved, per-command, the moment they first ran live); LIST/FIND are read-only.

type SkillInput 

type SkillInput struct {
	Find     string `json:"find,omitempty"`     // search INSTALLED skills (local) → matching names
	Load     string `json:"load,omitempty"`     // exact installed skill name → pull its guidance in (gated)
	Discover string `json:"discover,omitempty"` // search the skills.sh CATALOG (remote, no install) → packages
	Install  string `json:"install,omitempty"`  // install "owner/repo@skill" from the catalog (gated) → then loadable
}

SkillInput drives the skill tool: FIND/LOAD work on already-installed skills; DISCOVER/INSTALL reach the skills.sh catalog (search any agent's published skills, then install one on demand).

type TodoInput 

type TodoInput struct {
	Action  string         `json:"action"`
	Items   []TodoItemWire `json:"items,omitempty"`
	Index   int            `json:"index,omitempty"`
	Indices []int          `json:"indices,omitempty"` // done/skip several at once (one sweep → one call)
}

TodoInput drives the work-tracker. `items` carries the (re)written list for create/update; `index` (1-based) targets a single item for done/block.

type TodoItemWire 

type TodoItemWire struct {
	Title  string `json:"title"`
	Detail string `json:"detail,omitempty"`
	Status string `json:"status,omitempty"`
}

Input payloads, one per tool.

type TraceInput 

type TraceInput struct {
	Target string `json:"target"` // a URL (traces the fetch pipeline) or a file path
}

TraceInput traces an artifact across pipeline stages to locate data loss.

type WebSearchInput 

type WebSearchInput struct {
	Query string `json:"query"`
}

WebSearchInput searches the web for a query.

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.