plugins

package
v1.136.1 Latest Latest
Warning

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

 Go to latest Published: Jun 11, 2026 License: Apache-2.0 Imports: 44 Imported by: 0

Documentation

Overview

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* Shared argv→JSON parsing for builtin tools. * * The agent flattens a {cmd, args:{...}} tool envelope into a flag-style argv * before dispatch (see buildArgvFromJSONMap): each "--key value" pair, with * array fields emitted as repeated "--key value" pairs and booleans as a bare * "--key". Builtin plugins therefore receive, after the subcommand token, * something like: * * ["create", "--name", "deploy-x", "--triggers", "a", "--triggers", "b", ...] * * argvToInnerJSON turns that tail into the inner-args JSON object the plugins * unmarshal, so a single code path handles both the JSON envelope and the * flattened argv form. Keys listed in arrayKeys are always emitted as JSON * arrays (so a single "--triggers a" still unmarshals into []string).

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* DescribeCall implementations for the action/multimodal builtins. These give * the agent progress UI a concise, contextual one-liner (e.g. "🎨 Generating * image: a watercolor fox") instead of falling back to the long static * Description(), which rendered as an oversized box. Labels are i18n-resolved.

* Copyright (c) 2024 Edilson Freitas. License: Apache-2.0. * BuiltinAskPlugin — exposes interactive multiple-choice questions to the LLM * as the @ask / ask_user tool. The LLM emits 1-6 questions; the user picks * answers in a Bubble Tea overlay and the selections come back as the tool * result, in the SAME turn (unlike @park which suspends). * * The plugin is DECLARATIVE: it validates args and provides the schema. The * interactive rendering happens in the agent loop (which owns the TTY and the * stdin reader), mirroring the coder security gate. ExecuteWithStream is only * the FALLBACK path (invoked outside the loop): it returns the non-interactive * fallback result — the first option per question.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinImagePlugin — image generation as an @image ReAct tool. * * It generates images from a text prompt using the configured backend * (self-hosted Stable Diffusion WebUI, an OpenAI-compatible endpoint, or * OpenAI), local/keyless-first, and saves them to file(s). Self-contained — it * reads the backend from the environment via imagegen.NewFromEnv, so no adapter * wiring is required.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinKnowledgePlugin — exposes attached knowledge bases (/context attach * of a knowledge-mode context) as an @knowledge ReAct tool, so agent and * coder can interrogate a multi-megabyte corpus iteratively instead of * relying only on the per-turn auto-retrieved passages. Subcommands: * * search { query, top_k?, kb? } -> hybrid-ranked passages (keyless BM25 floor) * get { source, offset?, kb? } -> one page of a full source document * toc { prefix?, kb? } -> table of contents (document paths) * list {} -> attached knowledge bases * * Like @memory, the top-level ChatCLI owns the context manager but the * plugin is instantiated before it, so the plugin reaches it through a * package-level adapter supplied via SetKnowledgeAdapter.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinMemoryPlugin — exposes long-term memory as an @memory ReAct tool * so the agent can persist knowledge DETERMINISTICALLY, the moment the user * reveals it, instead of relying on the throttled background extractor that * silently drops facts. Subcommands: * * remember { content, category? } -> stored fact * profile { fields:{key:value,...} } -> updated profile * forget { match } -> removed matching facts * recall { query? } -> current relevant memory * * Like @scheduler, the top-level ChatCLI owns the memory store but the * plugin is instantiated before it, so the plugin reaches the store through * a package-level adapter supplied via SetMemoryAdapter.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinMoaPlugin — Mixture-of-Agents as an @moa ReAct tool. * * It fans the same prompt out to several models (across the providers the user * has configured), then has an aggregator model synthesize one best answer from * all the candidates. This turns ChatCLI's multi-provider support into a quality * lever: independent models catch each other's mistakes, and the aggregator * resolves conflicts. Inspired by hermes-agent's mixture_of_agents tool, but * implemented natively against ChatCLI's own LLM manager — keyless beyond the * providers the user already configured. * * Like @memory/@send, the cli package owns the LLM manager, so the plugin * reaches it through an adapter supplied via SetMoaAdapter.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinOsvPlugin — dependency vulnerability scanning as an @osv ReAct tool. * * It reads a project's dependency manifest (go.mod, requirements.txt, * package-lock.json, Cargo.lock) and checks every pinned dependency against the * free, keyless OSV.dev database (https://osv.dev). It can also check a single * package@version directly. Inspired by hermes-agent's osv_check, implemented * natively in Go and self-contained — no API key, no external CLI.

* BuiltinParkPlugin — exposes agent loop suspension as the @park ReAct * tool. When invoked, the plugin parses the request, validates it, and * returns it to the agent loop wrapped in park.NewParkError. The loop * (cli/agent_mode.go) detects the sentinel, snapshots state, schedules * the resume job, and returns to the user prompt. * * Subcommands (semantically the four park modes): * * delay {duration} fixed timer * until {when} wallclock RFC3339 / "in 5m" / "+5m" * for_url {url, interval, deadline, success_when?} HTTP polling * for_cmd {cmd, interval, deadline, success_when?} shell polling * * The plugin does NOT touch the scheduler directly — that is the agent * loop's responsibility, because only the loop has the live snapshot of * the chat history and tool counters at the exact suspension point.

* BuiltinSchedulerPlugin — exposes the scheduler as an @scheduler * ReAct tool. Subcommands: * * schedule { name, when, do, wait?, timeout?, poll?, …} → job_id * wait { until, every?, timeout?, async?, then? } → outcome * query { id } → job * list { filter? } → []summary * cancel { id, reason? } → ok * * Because the top-level ChatCLI owns the scheduler but the plugin is * instantiated before it, the plugin uses a package-level adapter * supplied via SetSchedulerAdapter (called from NewChatCLI after * initScheduler).

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinSendPlugin — exposes proactive outbound messaging as an @send ReAct * tool. The agent can deliver a message to any configured gateway platform * (Telegram, WhatsApp, Discord, Slack, generic webhook) — the same adapters * the gateway daemon uses for replies, now reachable from agent/coder to * INITIATE a message. This is the chatcli equivalent of hermes-agent's * send_message tool. * * Like @memory/@scheduler, the cli package owns the gateway adapters but the * plugin is instantiated before it, so the plugin reaches them through a * package-level adapter supplied via SetSendAdapter.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinSessionPlugin — search past conversations as an @session ReAct tool. * * It lets the agent recall what was discussed in earlier saved sessions * ("what did we decide about the cache last week?") by searching ChatCLI's own * saved-session store. Inspired by hermes-agent's session_search tool; * implemented natively against ChatCLI's SessionManager via an adapter.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinSkillPlugin — self-authoring skills as an @skill ReAct tool. * * It lets the agent CREATE and EVOLVE its own skills at runtime: when it learns * a reusable procedure, a project convention, or a workflow the user repeats, * it writes a SKILL.md into the user's global skills directory, where the loader * auto-discovers it on the next turn (and on every future session). This is the * "skills that get better over time" capability — inspired by hermes-agent's * skill authoring/management, implemented natively against ChatCLI's own skill * format. * * Division of labor with @memory: @memory stores FACTS ("the user prefers X"); * @skill stores reusable PROCEDURES/KNOWLEDGE with triggers ("how to deploy * this project"). The skill is activated automatically when its triggers match * a future request. * * Self-contained: it writes to ~/.chatcli/skills (the same global directory the * loader scans and builtin.Seed populates), so no adapter wiring is required.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* BuiltinSpeakPlugin — text-to-speech as an @speak ReAct tool. * * It synthesizes text into an audio file using the configured TTS backend * (local macOS `say`/espeak, a self-hosted OpenAI-compatible endpoint, or * OpenAI), local/keyless-first. The same llm/tts package also powers the * gateway's optional voice replies. Self-contained — it reads the backend from * the environment via tts.NewFromEnv, so no adapter wiring is required.

* ChatCLI - Built-in @voice plugin: per-conversation voice reply control. * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0 * * Lets gateway users control audio replies in natural language: when someone * asks "answer me in audio" or "stop sending voice messages", the model calls * this tool and the preference sticks to that conversation (persisted across * daemon restarts). Outside a gateway run there is no conversation to bind * to, so the tool refuses with a clear message instead of guessing.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0 * * JS-shell detection for @webfetch. * * SPAs ship an HTML "shell" (an empty root div plus script tags) and only * materialize content client-side. A static fetch of such a page yields a * few words of boilerplate — the model then concludes the page is empty. * The heuristics here decide when that happened so the plugin can escalate * to a headless render (webfetch_render.go), and extract framework state * embedded in the static HTML when it is available for free.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0 * * Headless-browser escalation for @webfetch. * * Static fetches of client-rendered pages (SPAs, JS-built tables) return * an empty shell. When webfetch_jsdetect.go flags that, this file drives a * real Chromium via CDP (go-rod), waits for the DOM to settle and hands the * rendered HTML back to the regular extractText pipeline. * * Browser acquisition policy (keyless / self-hosted by design): * 1. A system Chrome / Edge / Chromium found on PATH is always preferred. * 2. With CHATCLI_WEBFETCH_RENDER_AUTOPROVISION=true and no system * browser, rod downloads a pinned Chromium snapshot once (~150 MB, * under the user cache dir) — same self-provisioning pattern as the * embedded TTS assets. Without the opt-in, the plugin degrades to the * static text plus an honest limitation note. * * Production posture: * - One shared browser per process, launched lazily and reused across * renders (a cold launch costs 1-2s; agent loops fetch in bursts). * An idle timer tears it down after renderIdleShutdown so a finished * session does not keep a ~200 MB Chromium resident. * - Launch failures trip a circuit breaker: after renderFailureThreshold * consecutive failures the escalation stays off for renderCooldown, * so a broken local Chrome costs two attempts, not seconds per fetch. * - Every render runs in its own incognito browser context: cookies and * storage never leak between unrelated target sites. * * SSRF: the navigation target has already passed validateWebTarget, and * every sub-request the page makes is re-checked through a CDP hijack * before it leaves the browser — the in-browser equivalent of the * ssrfDialControl layer used for plain HTTP fetches. Verdicts for resolved * hostnames are cached briefly since SPAs fire hundreds of sub-requests.

* ChatCLI - Command Line Interface for LLM interaction * Copyright (c) 2024 Edilson Freitas * License: Apache-2.0 * * Additional keyless @websearch backends: Brave Search and Mojeek. * * Both follow the same posture as the DuckDuckGo provider — public HTML * results page, browser-like request, proper DOM parsing, zero API keys — * and exist to give the fallback chain independent indexes: Brave and * Mojeek run their own crawlers, so a DDG outage or bot-block does not * take @websearch down with it. Either backend failing (403 interstitial, * layout drift, network block) simply falls through to the next link in * the chain. * * Parsing strategy favors semantic, hash-free hooks: Brave's SERP is a * Svelte app with content-hashed class names, but every organic result * carries data-type="web"; Mojeek's classic markup nests results under * <ul class="results-standard">. Class tokens like "title" and "s" are * matched as whole tokens via hasClass, never as hashed substrings.

Index

Constants

View Source 
const (
	TruncationPreviewSize = 5000
	TruncationSuffixSize  = 1000
)

TruncationPreviewSize is the byte budget for the prefix portion of a truncated payload. The shape is "<prefix>\n\n... [TRUNCATED] ...\n\n<suffix>" where prefix is up to 5/6 of the budget and suffix is 1/6. The distribution is empirical: heads of large outputs usually contain the most useful information for the LLM (function signatures, schema, file listing) while the tail catches stack traces or summary lines.

View Source 
const DefaultMaxResultChars = 30_000

DefaultMaxResultChars is the soft cap applied to every plugin that does not implement TruncationAware. Matches the historical hard-coded 30 000 in agent_mode.go.

Variables

View Source 
var (
	// ErrNoSignature indicates the plugin has no .sig file.
	ErrNoSignature = errors.New("plugin signature file not found")
	// ErrInvalidSignature indicates the signature verification failed.
	ErrInvalidSignature = errors.New("plugin signature verification failed")
	// ErrNoTrustedKeys indicates no trusted public keys were found.
	ErrNoTrustedKeys = errors.New("no trusted public keys found")
)
View Source 
var ErrInvalidArgs = errors.New("invalid arguments")

ErrInvalidArgs is the sentinel returned when args fail schema validation. Callers (the agent loop) translate this into a ToolResult with IsError=true, ErrorCode=InvalidArgs so the LLM sees a clean failure surface and can retry with corrected input.

View Source 
var KnownSearchProviders = []SearchProvider{
	ProviderDuckDuckGo, ProviderSearXNG, ProviderBrave, ProviderMojeek,
}

KnownSearchProviders is the canonical list for the /websearch CLI command. Default order: DuckDuckGo first (zero config, always available), SearxNG as secondary (used when the user has an instance configured), then the independent-index scrapers Brave and Mojeek as deep fallbacks.

Functions

func DescribeCall added in v1.118.0 

func DescribeCall(p Plugin, args []string) string

DescribeCall returns the contextual one-liner for the plugin's current invocation, or the static Description() as a fallback. The caller never needs to do the type assertion itself.

func EffectiveMaxResultChars added in v1.118.0 

func EffectiveMaxResultChars(plugin Plugin) int

EffectiveMaxResultChars resolves the active cap for one tool call. Plugins that implement TruncationAware with a positive value win; otherwise the global default applies.

func IsConcurrencySafe added in v1.118.0 

func IsConcurrencySafe(p Plugin, args []string) bool

IsConcurrencySafe returns whether the plugin can run in parallel with other concurrency-safe invocations for the given args. Fail-closed.

func IsReadOnly added in v1.118.0 

func IsReadOnly(p Plugin, args []string) bool

IsReadOnly returns the plugin's read-only status for the given args. Returns false (fail-closed) for plugins that don't implement ReadOnlyAware. This is the single point of truth for the orchestrator; never call the interface method directly so the default stays correct.

func PromptFor added in v1.118.0 

func PromptFor(p Plugin, opts PromptOpts) (string, error)

PromptFor extracts a system-prompt slice from a Prompter plugin, if any. Returns empty string and no error when the plugin doesn't implement Prompter.

func PushStreamingInput added in v1.118.0 

func PushStreamingInput(p Plugin, field, value string)

PushStreamingInput delivers a partial-argument update to a plugin that implements StreamingInputAware. No-op otherwise.

func ResetValidatorCache added in v1.118.0 

func ResetValidatorCache()

ResetValidatorCache clears the compiled schema cache. Used by tests to ensure a plugin's schema is re-compiled across cases that mutate it via fixtures. Production code never calls this.

func SelectSearchChain added in v1.105.0 

func SelectSearchChain() []providerEntry

SelectSearchChain returns the ordered list of providers to try. An unset override → auto mode (DDG first → SearxNG if configured). An explicit override moves the named provider to the front and keeps the rest as fallbacks — so even a forced choice degrades gracefully.

func SetKnowledgeAdapter added in v1.136.0 

func SetKnowledgeAdapter(a KnowledgeAdapter)

SetKnowledgeAdapter wires the live adapter. Called from the top-level cli package once the context manager exists. Pass nil to clear it.

func SetMemoryAdapter added in v1.123.0 

func SetMemoryAdapter(a MemoryAdapter)

SetMemoryAdapter wires the live adapter. Called from the top-level cli package after the memory store is initialized. Pass nil to clear it.

func SetMoaAdapter added in v1.130.0 

func SetMoaAdapter(a MoaAdapter)

SetMoaAdapter wires the live adapter; pass nil to clear it.

func SetSchedulerAdapter added in v1.109.0 

func SetSchedulerAdapter(a SchedulerAdapter)

SetSchedulerAdapter wires the live adapter. Called from the top-level cli package after initScheduler.

func SetSendAdapter added in v1.130.0 

func SetSendAdapter(a SendAdapter)

SetSendAdapter wires the live adapter. Called from the top-level cli package once the gateway platform registry is available. Pass nil to clear it.

func SetSessionAdapter added in v1.130.0 

func SetSessionAdapter(a SessionAdapter)

SetSessionAdapter wires the live adapter; pass nil to clear.

func SetTodoAdapter added in v1.118.0 

func SetTodoAdapter(a TodoAdapter)

SetTodoAdapter wires the live adapter. Called from cli.NewChatCLI after the AgentMode is constructed; subsequent calls replace the adapter under the package mutex. Passing nil explicitly unwires — useful in tests and at process shutdown.

func TruncateForLLM added in v1.118.0 

func TruncateForLLM(s string, maxChars int) string

TruncateForLLM trims output to fit within the supplied cap. Returns the original string when it fits; otherwise a head/tail concatenation with an explicit "[TRUNCATED]" marker that names the dropped char count so the model knows it's looking at a redacted view.

The trim is intentionally not provider-agnostic for token math — chatcli's LLM clients each have their own token budget logic. This helper is for byte-level safety only.

func ValidateArgs added in v1.118.0 

func ValidateArgs(plugin Plugin, rawJSON string) error

ValidateArgs runs the plugin's JSON Schema against the raw args payload. Returns:

  • nil when the plugin does not implement JSONSchemaAware (legacy plugins keep working unchanged).
  • nil when the schema validates successfully.
  • wrapped ErrInvalidArgs with a descriptive message naming the offending JSON path when validation fails.
  • a non-InvalidArgs error when the schema itself fails to compile (programmer bug; should never reach production).

rawJSON is the LLM-emitted argument blob. We do not attempt to JSON-validate the chatcli @coder envelope shape (`{"cmd":...,"args":{...}}`) here because plugins choose their own input shape via the schema.

Types

type BuiltinAskPlugin added in v1.128.0 

type BuiltinAskPlugin struct{}

BuiltinAskPlugin is the @ask tool.

func NewBuiltinAskPlugin added in v1.128.0 

func NewBuiltinAskPlugin() *BuiltinAskPlugin

NewBuiltinAskPlugin returns a registerable instance.

func (*BuiltinAskPlugin) DescribeCall added in v1.128.0 

func (p *BuiltinAskPlugin) DescribeCall(args []string) string

DescribeCall reports how many questions are being asked, for the spinner label.

func (*BuiltinAskPlugin) Description added in v1.128.0 

func (*BuiltinAskPlugin) Description() string

Description surfaces the tool in /plugin list and the agent prompt.

func (*BuiltinAskPlugin) Execute added in v1.128.0 

func (p *BuiltinAskPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy entry-point; defers to ExecuteWithStream.

func (*BuiltinAskPlugin) ExecuteWithStream added in v1.128.0 

func (p *BuiltinAskPlugin) ExecuteWithStream(_ context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream is the NON-INTERACTIVE fallback (see the file header). It validates the questions and returns the first-option-per-question fallback so callers outside the interactive loop never block. The real interactive path is the agent loop's @ask interception.

func (*BuiltinAskPlugin) IsConcurrencySafe added in v1.128.0 

func (p *BuiltinAskPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe returns false: @ask takes over the terminal with a Bubble Tea overlay, so it MUST run serially — two overlays at once would fight for the TTY.

func (*BuiltinAskPlugin) IsReadOnly added in v1.128.0 

func (p *BuiltinAskPlugin) IsReadOnly(_ []string) bool

IsReadOnly returns true: @ask never touches the filesystem or external state; it only collects a decision from the user.

func (*BuiltinAskPlugin) Name added in v1.128.0 

func (*BuiltinAskPlugin) Name() string

Name is the canonical tool name visible to the LLM.

func (*BuiltinAskPlugin) Path added in v1.128.0 

func (*BuiltinAskPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinAskPlugin) Schema added in v1.128.0 

func (*BuiltinAskPlugin) Schema() string

Schema returns the structured contract for the text-mode prompt builder.

func (*BuiltinAskPlugin) Usage added in v1.128.0 

func (*BuiltinAskPlugin) Usage() string

Usage explains the canonical invocation form.

func (*BuiltinAskPlugin) Version added in v1.128.0 

func (*BuiltinAskPlugin) Version() string

Version is bumped whenever the surface changes.

type BuiltinCoderPlugin added in v1.60.0 

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

BuiltinCoderPlugin adapts the engine package to the Plugin interface, providing @coder functionality without requiring an external binary.

func NewBuiltinCoderPlugin added in v1.60.0 

func NewBuiltinCoderPlugin() *BuiltinCoderPlugin

NewBuiltinCoderPlugin creates a builtin @coder plugin backed by the engine package.

func (*BuiltinCoderPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinCoderPlugin) DescribeCall(args []string) string

DescribeCall surfaces what @coder is about to do: which subcommand, against which target. Strings are i18n-resolved at call time.

func (*BuiltinCoderPlugin) Description added in v1.60.0 

func (p *BuiltinCoderPlugin) Description() string

func (*BuiltinCoderPlugin) Execute added in v1.60.0 

func (p *BuiltinCoderPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute runs without streaming — collects all output and returns.

func (*BuiltinCoderPlugin) ExecuteWithStream added in v1.60.0 

func (p *BuiltinCoderPlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

ExecuteWithStream runs the engine and streams output line-by-line via onOutput.

func (*BuiltinCoderPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinCoderPlugin) IsConcurrencySafe(args []string) bool

IsConcurrencySafe mirrors IsReadOnly: read/search/tree on independent paths can run in parallel; mutating subcommands stay serial so an exec and a write in the same batch never race.

func (*BuiltinCoderPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinCoderPlugin) IsReadOnly(args []string) bool

IsReadOnly reports whether the @coder subcommand is read-only for the given args. Only `read`, `search`, `tree`, `list`, `stat` are pure reads — every other subcommand (`exec`, `write`, `patch`, `test`) mutates state.

func (*BuiltinCoderPlugin) Name added in v1.60.0 

func (p *BuiltinCoderPlugin) Name() string

func (*BuiltinCoderPlugin) Path added in v1.60.0 

func (p *BuiltinCoderPlugin) Path() string

func (*BuiltinCoderPlugin) Schema added in v1.60.0 

func (p *BuiltinCoderPlugin) Schema() string

func (*BuiltinCoderPlugin) Usage added in v1.60.0 

func (p *BuiltinCoderPlugin) Usage() string

func (*BuiltinCoderPlugin) Version added in v1.60.0 

func (p *BuiltinCoderPlugin) Version() string

type BuiltinImagePlugin added in v1.130.0 

type BuiltinImagePlugin struct{}

BuiltinImagePlugin is the @image tool.

func NewBuiltinImagePlugin added in v1.130.0 

func NewBuiltinImagePlugin() *BuiltinImagePlugin

NewBuiltinImagePlugin returns a ready-to-register plugin.

func (*BuiltinImagePlugin) DescribeCall added in v1.130.0 

func (*BuiltinImagePlugin) DescribeCall(args []string) string

func (*BuiltinImagePlugin) Description added in v1.130.0 

func (*BuiltinImagePlugin) Description() string

Description surfaces the tool.

func (*BuiltinImagePlugin) Execute added in v1.130.0 

func (p *BuiltinImagePlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinImagePlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinImagePlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream runs the generation. Progress feedback is the agent loop's animated spinner (this tool is blocking, not streaming).

func (*BuiltinImagePlugin) Name added in v1.130.0 

func (*BuiltinImagePlugin) Name() string

Name returns "@image".

func (*BuiltinImagePlugin) Path added in v1.130.0 

func (*BuiltinImagePlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinImagePlugin) Schema added in v1.130.0 

func (*BuiltinImagePlugin) Schema() string

Schema describes the subcommands.

func (*BuiltinImagePlugin) Usage added in v1.130.0 

func (*BuiltinImagePlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinImagePlugin) Version added in v1.130.0 

func (*BuiltinImagePlugin) Version() string

Version is semver.

type BuiltinKnowledgePlugin added in v1.136.0 

type BuiltinKnowledgePlugin struct{}

BuiltinKnowledgePlugin is the @knowledge tool.

func NewBuiltinKnowledgePlugin added in v1.136.0 

func NewBuiltinKnowledgePlugin() *BuiltinKnowledgePlugin

NewBuiltinKnowledgePlugin returns a ready-to-register plugin.

func (*BuiltinKnowledgePlugin) DescribeCall added in v1.136.1 

func (p *BuiltinKnowledgePlugin) DescribeCall(args []string) string

DescribeCall surfaces what is being looked up so the spinner reads "Searching knowledge base: \"gateway env vars\"" instead of the static (long) description or the raw JSON envelope — both of which overflow a terminal row and break the spinner's single-line repaint.

func (*BuiltinKnowledgePlugin) Description added in v1.136.0 

func (*BuiltinKnowledgePlugin) Description() string

Description surfaces the tool in /plugin list and the agent tool catalog.

func (*BuiltinKnowledgePlugin) Execute added in v1.136.0 

func (p *BuiltinKnowledgePlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses the args and dispatches to the adapter.

func (*BuiltinKnowledgePlugin) ExecuteWithStream added in v1.136.0 

func (p *BuiltinKnowledgePlugin) ExecuteWithStream(_ context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream mirrors Execute — this plugin produces no incremental output, so the stream callback is ignored.

func (*BuiltinKnowledgePlugin) IsConcurrencySafe added in v1.136.1 

func (p *BuiltinKnowledgePlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: every subcommand reads immutable, cached corpus data, so parallel searches over different topics never conflict.

func (*BuiltinKnowledgePlugin) IsReadOnly added in v1.136.1 

func (p *BuiltinKnowledgePlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true for every invocation: @knowledge only queries the attached knowledge bases — it never mutates files or state. The orchestrator uses this to skip the security prompt.

func (*BuiltinKnowledgePlugin) Name added in v1.136.0 

func (*BuiltinKnowledgePlugin) Name() string

Name returns "@knowledge".

func (*BuiltinKnowledgePlugin) Path added in v1.136.0 

func (*BuiltinKnowledgePlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinKnowledgePlugin) Schema added in v1.136.0 

func (*BuiltinKnowledgePlugin) Schema() string

Schema exposes the structured description the agent prompt builder renders into per-subcommand flag lists with examples.

func (*BuiltinKnowledgePlugin) Usage added in v1.136.0 

func (*BuiltinKnowledgePlugin) Usage() string

Usage explains the canonical invocation forms.

func (*BuiltinKnowledgePlugin) Version added in v1.136.0 

func (*BuiltinKnowledgePlugin) Version() string

Version is semver; bumped when the surface changes.

type BuiltinMemoryPlugin added in v1.123.0 

type BuiltinMemoryPlugin struct{}

BuiltinMemoryPlugin is the @memory tool.

func NewBuiltinMemoryPlugin added in v1.123.0 

func NewBuiltinMemoryPlugin() *BuiltinMemoryPlugin

NewBuiltinMemoryPlugin returns a ready-to-register plugin.

func (*BuiltinMemoryPlugin) Description added in v1.123.0 

func (*BuiltinMemoryPlugin) Description() string

Description surfaces the tool in /plugin list and the help.

func (*BuiltinMemoryPlugin) Execute added in v1.123.0 

func (p *BuiltinMemoryPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses the args and dispatches to the adapter.

func (*BuiltinMemoryPlugin) ExecuteWithStream added in v1.123.0 

func (p *BuiltinMemoryPlugin) ExecuteWithStream(_ context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream mirrors Execute — this plugin produces no incremental output, so the stream callback is ignored.

func (*BuiltinMemoryPlugin) Name added in v1.123.0 

func (*BuiltinMemoryPlugin) Name() string

Name returns "@memory".

func (*BuiltinMemoryPlugin) Path added in v1.123.0 

func (*BuiltinMemoryPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinMemoryPlugin) Schema added in v1.123.0 

func (*BuiltinMemoryPlugin) Schema() string

Schema exposes a structured description the agent prompt builder renders into per-subcommand flag lists with examples.

func (*BuiltinMemoryPlugin) Usage added in v1.123.0 

func (*BuiltinMemoryPlugin) Usage() string

Usage explains the canonical invocation forms.

func (*BuiltinMemoryPlugin) Version added in v1.123.0 

func (*BuiltinMemoryPlugin) Version() string

Version is semver; bumped when the surface changes.

type BuiltinMoaPlugin added in v1.130.0 

type BuiltinMoaPlugin struct{}

BuiltinMoaPlugin is the @moa tool.

func NewBuiltinMoaPlugin added in v1.130.0 

func NewBuiltinMoaPlugin() *BuiltinMoaPlugin

NewBuiltinMoaPlugin returns a ready-to-register plugin.

func (*BuiltinMoaPlugin) DescribeCall added in v1.130.0 

func (*BuiltinMoaPlugin) DescribeCall(args []string) string

func (*BuiltinMoaPlugin) Description added in v1.130.0 

func (*BuiltinMoaPlugin) Description() string

Description surfaces the tool in the catalog.

func (*BuiltinMoaPlugin) Execute added in v1.130.0 

func (p *BuiltinMoaPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinMoaPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinMoaPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream ignores the stream callback (no incremental output).

func (*BuiltinMoaPlugin) Name added in v1.130.0 

func (*BuiltinMoaPlugin) Name() string

Name returns "@moa".

func (*BuiltinMoaPlugin) Path added in v1.130.0 

func (*BuiltinMoaPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinMoaPlugin) Schema added in v1.130.0 

func (*BuiltinMoaPlugin) Schema() string

Schema describes the subcommands for the prompt builder.

func (*BuiltinMoaPlugin) Usage added in v1.130.0 

func (*BuiltinMoaPlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinMoaPlugin) Version added in v1.130.0 

func (*BuiltinMoaPlugin) Version() string

Version is semver.

type BuiltinOsvPlugin added in v1.130.0 

type BuiltinOsvPlugin struct{}

BuiltinOsvPlugin is the @osv tool.

func NewBuiltinOsvPlugin added in v1.130.0 

func NewBuiltinOsvPlugin() *BuiltinOsvPlugin

NewBuiltinOsvPlugin returns a ready-to-register plugin.

func (*BuiltinOsvPlugin) DescribeCall added in v1.130.0 

func (*BuiltinOsvPlugin) DescribeCall(args []string) string

func (*BuiltinOsvPlugin) Description added in v1.130.0 

func (*BuiltinOsvPlugin) Description() string

Description surfaces the tool in the catalog.

func (*BuiltinOsvPlugin) Execute added in v1.130.0 

func (p *BuiltinOsvPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinOsvPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinOsvPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream ignores the stream callback.

func (*BuiltinOsvPlugin) IsConcurrencySafe added in v1.130.0 

func (*BuiltinOsvPlugin) IsConcurrencySafe() bool

IsConcurrencySafe lets the orchestrator fan @osv out in parallel — it only reads files and queries a read-only API.

func (*BuiltinOsvPlugin) Name added in v1.130.0 

func (*BuiltinOsvPlugin) Name() string

Name returns "@osv".

func (*BuiltinOsvPlugin) Path added in v1.130.0 

func (*BuiltinOsvPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinOsvPlugin) Schema added in v1.130.0 

func (*BuiltinOsvPlugin) Schema() string

Schema describes the subcommands.

func (*BuiltinOsvPlugin) Usage added in v1.130.0 

func (*BuiltinOsvPlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinOsvPlugin) Version added in v1.130.0 

func (*BuiltinOsvPlugin) Version() string

Version is semver.

type BuiltinParkPlugin added in v1.112.0 

type BuiltinParkPlugin struct{}

BuiltinParkPlugin is the @park tool.

func NewBuiltinParkPlugin added in v1.112.0 

func NewBuiltinParkPlugin() *BuiltinParkPlugin

NewBuiltinParkPlugin returns a registerable instance.

func (*BuiltinParkPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinParkPlugin) DescribeCall(args []string) string

DescribeCall reports which park flavor is being requested. The cmd vocabulary is delay / until / for_url / for_cmd; each gets its own human-readable prefix via i18n.

func (*BuiltinParkPlugin) Description added in v1.112.0 

func (*BuiltinParkPlugin) Description() string

Description surfaces the tool in /plugin list.

func (*BuiltinParkPlugin) Execute added in v1.112.0 

func (p *BuiltinParkPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy entry-point; defers to ExecuteWithStream.

func (*BuiltinParkPlugin) ExecuteWithStream added in v1.112.0 

func (p *BuiltinParkPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream parses the invocation, validates the request, and returns the sentinel error wrapping it. The stream callback is unused — park has no incremental output by design.

func (*BuiltinParkPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinParkPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe returns false: parking is a process-wide event that suspends the agent loop. It cannot meaningfully run in parallel with another tool — it IS the way the agent surrenders the turn.

func (*BuiltinParkPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinParkPlugin) IsReadOnly(_ []string) bool

IsReadOnly returns false: @park mutates scheduler state (it parks the agent and registers an auto-resume callback). Even though the observation subcommands (for_cmd, for_url) are mostly read-only at the user level, they still create durable scheduler entries.

func (*BuiltinParkPlugin) Name added in v1.112.0 

func (*BuiltinParkPlugin) Name() string

Name is the canonical tool name visible to the LLM.

func (*BuiltinParkPlugin) Path added in v1.112.0 

func (*BuiltinParkPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinParkPlugin) Schema added in v1.112.0 

func (*BuiltinParkPlugin) Schema() string

Schema returns the structured contract used by the agent prompt builder to inject per-subcommand flag lists into the system prompt.

func (*BuiltinParkPlugin) Usage added in v1.112.0 

func (*BuiltinParkPlugin) Usage() string

Usage explains the canonical invocation forms.

func (*BuiltinParkPlugin) Version added in v1.112.0 

func (*BuiltinParkPlugin) Version() string

Version is bumped whenever the surface changes.

type BuiltinReadPlugin added in v1.118.0 

type BuiltinReadPlugin struct{}

BuiltinReadPlugin is the atomic read tool — equivalent to Claude Code's Read primitive. It exposes a dedicated, flat-schema interface to the LLM ("@read") rather than requiring the model to remember the @coder envelope (`{"cmd":"read","args":{"file":"x"}}`). The legacy @coder read subcommand stays operational for backwards compatibility; both paths funnel into the same engine.handleRead implementation.

Why split this out from @coder:

  • A narrow tool with one job and one schema gives the model a cleaner choice surface (Claude Code-style).
  • Read is unambiguously read-only and concurrency-safe, so the orchestrator's partition policy can batch multiple @read calls in parallel — which @coder couldn't claim because of its write/exec subcommands.
  • The DescribeCall spinner can show the file path directly with no envelope-unwrap heuristics.

func NewBuiltinReadPlugin added in v1.118.0 

func NewBuiltinReadPlugin() *BuiltinReadPlugin

NewBuiltinReadPlugin builds the @read singleton.

func (*BuiltinReadPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinReadPlugin) DescribeCall(args []string) string

DescribeCall surfaces the file being read so the spinner reads "Reading: main.go" instead of the static description. Falls back to Description() when the file argument is missing.

func (*BuiltinReadPlugin) Description added in v1.118.0 

func (p *BuiltinReadPlugin) Description() string

Description is the one-liner shown in the tool catalog the LLM sees in its system prompt. i18n-resolved at startup.

func (*BuiltinReadPlugin) Execute added in v1.118.0 

func (p *BuiltinReadPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy synchronous entry-point.

func (*BuiltinReadPlugin) ExecuteWithStream added in v1.118.0 

func (p *BuiltinReadPlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

ExecuteWithStream parses the flat JSON args into the engine's argv form and dispatches to engine.handleRead via a fresh Engine instance. Output is streamed line-by-line through onOutput when present.

func (*BuiltinReadPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinReadPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: each @read opens its own file descriptor and streams to its own output buffer. Two reads of the same file don't conflict; two reads of different files don't either.

func (*BuiltinReadPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinReadPlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true for every invocation: @read never mutates the file system. The orchestrator uses this to skip the security prompt and to participate in concurrent batches.

func (*BuiltinReadPlugin) JSONSchema added in v1.118.0 

func (p *BuiltinReadPlugin) JSONSchema() string

JSONSchema returns the draft-2020-12 schema for @read input. The plugin layer validates the LLM-emitted args against this before dispatch — bad payloads short-circuit with InvalidArgs instead of failing inside parseReadArgs with an unhelpful message.

func (*BuiltinReadPlugin) MaxResultChars added in v1.118.0 

func (p *BuiltinReadPlugin) MaxResultChars() int

MaxResultChars raises the per-call truncation cap for @read. File reads are the primary way the model learns code structure; truncating at 30k loses crucial context for large files (e.g. a 1500-line model definition). 80k chars (~20k tokens) is the upper bound — beyond that the caller should request a line range via the from_line/to_line flags.

func (*BuiltinReadPlugin) Name added in v1.118.0 

func (p *BuiltinReadPlugin) Name() string

Name returns the LLM-visible tool name.

func (*BuiltinReadPlugin) Path added in v1.118.0 

func (p *BuiltinReadPlugin) Path() string

Path is a sentinel matching the existing builtin convention.

func (*BuiltinReadPlugin) Schema added in v1.118.0 

func (p *BuiltinReadPlugin) Schema() string

Schema returns the JSON schema the LLM uses to format tool calls. Flat shape on purpose — no @coder envelope; the LLM passes {"file":"main.go","from_line":10,"to_line":50} directly.

func (*BuiltinReadPlugin) Usage added in v1.118.0 

func (p *BuiltinReadPlugin) Usage() string

Usage is the short shell-like example the user sees in /help.

func (*BuiltinReadPlugin) Version added in v1.118.0 

func (p *BuiltinReadPlugin) Version() string

Version follows semver for the plugin; tied to the engine's contract.

type BuiltinSchedulerPlugin added in v1.109.0 

type BuiltinSchedulerPlugin struct{}

BuiltinSchedulerPlugin is the @scheduler tool.

func NewBuiltinSchedulerPlugin added in v1.109.0 

func NewBuiltinSchedulerPlugin() *BuiltinSchedulerPlugin

NewBuiltinSchedulerPlugin returns a ready-to-register plugin.

func (*BuiltinSchedulerPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinSchedulerPlugin) DescribeCall(args []string) string

DescribeCall surfaces the subcommand and, when available, the job identifier or schedule name being acted on. All strings are i18n-resolved.

func (*BuiltinSchedulerPlugin) Description added in v1.109.0 

func (*BuiltinSchedulerPlugin) Description() string

Description surfaces the tool in /plugin list and the help.

func (*BuiltinSchedulerPlugin) Execute added in v1.109.0 

func (p *BuiltinSchedulerPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses the args and dispatches to the adapter.

func (*BuiltinSchedulerPlugin) ExecuteWithStream added in v1.109.0 

func (p *BuiltinSchedulerPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream mirrors Execute — this plugin does not produce incremental output, so stream is ignored.

The agent's tool dispatcher (cli/agent_tool_sanitizer.go, buildArgvFromJSONMap) flattens {"cmd":"schedule","args":{...}} into argv form ["schedule","--name","x","--when","+5m",...] before this plugin is invoked. Historically the plugin only json.Unmarshaled the joined argv string, so the agent's call always failed with "parse envelope: invalid character 's'". parseSchedulerInvocation now accepts JSON envelopes, flat JSON without args wrapper, and the flattened argv form, then applies field aliases (delay→when, command→do, …) so common LLM phrasings work first try.

func (*BuiltinSchedulerPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinSchedulerPlugin) IsConcurrencySafe(args []string) bool

IsConcurrencySafe matches IsReadOnly: two queries or two lists can run in parallel against the durable store without conflict (the store uses a per-job lock). Mutators stay serial to preserve causal ordering of the schedule/cancel chain.

func (*BuiltinSchedulerPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinSchedulerPlugin) IsReadOnly(args []string) bool

IsReadOnly reports true for query/list operations; schedule/wait/ cancel mutate the scheduler's persistent state. We look at the first arg (subcommand) which is the stable @scheduler schema entry point.

func (*BuiltinSchedulerPlugin) Name added in v1.109.0 

func (*BuiltinSchedulerPlugin) Name() string

Name returns "@scheduler".

func (*BuiltinSchedulerPlugin) Path added in v1.109.0 

func (*BuiltinSchedulerPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinSchedulerPlugin) Schema added in v1.109.0 

func (*BuiltinSchedulerPlugin) Schema() string

Schema exposes a structured description that the agent prompt builder in cli/agent_mode.go (getToolContextString) renders into per-subcommand flag lists with examples. Keep examples concrete and copy-pasteable — the LLM uses these to learn field names without reinvention.

func (*BuiltinSchedulerPlugin) Usage added in v1.109.0 

func (*BuiltinSchedulerPlugin) Usage() string

Usage explains how the ReAct loop invokes the tool. Shows the canonical JSON envelope first because it is the most copy-pasteable form, then summarizes the per-subcommand fields with concrete value examples so the LLM can pattern-match without guessing.

Action DSL (do=) — all forms below fire from a scheduled job: 

"/run <task>"      task delegated to the agent ReAct loop
"/agent <task>"    same as /run; explicit agent invocation
"/coder <task>"    runs the agent in coder profile (CoderSystemPrompt)
"shell: <cmd>"     raw shell command (policy-classified, captured)
"agent: <task>"    boots the agent loop with the given task (DSL form)
"@<tool> <args>"   invokes a registered tool (e.g. "@coder exec ls")
"POST <url> | b"   webhook (also GET/PUT, with optional body)
"llm: <prompt>"    single-shot LLM call, no tools
"hook:<event>"     fires a chatcli hook event by name
"noop"             do nothing (used for pure wait/dependency jobs)

func (*BuiltinSchedulerPlugin) Version added in v1.109.0 

func (*BuiltinSchedulerPlugin) Version() string

Version is semver; bumped when the surface changes.

type BuiltinSearchPlugin added in v1.118.0 

type BuiltinSearchPlugin struct{}

BuiltinSearchPlugin is the atomic regex-search tool — the chatcli analog of Claude Code's Grep primitive. Like BuiltinReadPlugin, it is a thin adapter over engine.handleSearch that gives the LLM a flat, dedicated schema instead of forcing it through the @coder envelope. The legacy `@coder search` subcommand stays working.

The tool advertises IsReadOnly + IsConcurrencySafe so multiple searches in the same turn can run in parallel batches — typical scenario: the model greps for an identifier in src/ and another in tests/ simultaneously.

func NewBuiltinSearchPlugin added in v1.118.0 

func NewBuiltinSearchPlugin() *BuiltinSearchPlugin

NewBuiltinSearchPlugin builds the @search singleton.

func (*BuiltinSearchPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinSearchPlugin) DescribeCall(args []string) string

DescribeCall surfaces the regex pattern being searched.

func (*BuiltinSearchPlugin) Description added in v1.118.0 

func (p *BuiltinSearchPlugin) Description() string

Description is shown in the model's tool catalog.

func (*BuiltinSearchPlugin) Execute added in v1.118.0 

func (p *BuiltinSearchPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy synchronous entry-point.

func (*BuiltinSearchPlugin) ExecuteWithStream added in v1.118.0 

func (p *BuiltinSearchPlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

ExecuteWithStream parses the flat JSON args, converts to engine argv form, and runs engine.handleSearch via a fresh Engine instance. Output streams line-by-line through onOutput.

func (*BuiltinSearchPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinSearchPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: multiple searches don't conflict. File system reads at the syscall layer are safe to interleave.

func (*BuiltinSearchPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinSearchPlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true: @search only reads files, never modifies them.

func (*BuiltinSearchPlugin) JSONSchema added in v1.118.0 

func (p *BuiltinSearchPlugin) JSONSchema() string

JSONSchema returns the draft-2020-12 schema for @search input.

func (*BuiltinSearchPlugin) MaxResultChars added in v1.118.0 

func (p *BuiltinSearchPlugin) MaxResultChars() int

MaxResultChars raises the per-call truncation cap for @search. grep output is structured (file:line:match) and the LLM needs breadth more than depth; cutting at the global 30k blocks many repository-wide investigations. 60k chars (~15k tokens with standard BPE) is a pragmatic upper bound for one search call.

func (*BuiltinSearchPlugin) Name added in v1.118.0 

func (p *BuiltinSearchPlugin) Name() string

Name returns the LLM-visible tool name. The "@" prefix distinguishes it from @websearch (which hits the public internet); the description further disambiguates by stating the scope is "files in the workspace".

func (*BuiltinSearchPlugin) Path added in v1.118.0 

func (p *BuiltinSearchPlugin) Path() string

Path is the builtin sentinel.

func (*BuiltinSearchPlugin) Schema added in v1.118.0 

func (p *BuiltinSearchPlugin) Schema() string

Schema returns the flat JSON schema the LLM uses to format calls. No @coder envelope — model passes {"term":"Login","dir":"./src"} directly.

func (*BuiltinSearchPlugin) Usage added in v1.118.0 

func (p *BuiltinSearchPlugin) Usage() string

Usage is a short shell-like example for /help.

func (*BuiltinSearchPlugin) Version added in v1.118.0 

func (p *BuiltinSearchPlugin) Version() string

Version follows semver tied to the engine's contract.

type BuiltinSendPlugin added in v1.130.0 

type BuiltinSendPlugin struct{}

BuiltinSendPlugin is the @send tool.

func NewBuiltinSendPlugin added in v1.130.0 

func NewBuiltinSendPlugin() *BuiltinSendPlugin

NewBuiltinSendPlugin returns a ready-to-register plugin.

func (*BuiltinSendPlugin) DescribeCall added in v1.130.0 

func (*BuiltinSendPlugin) DescribeCall(args []string) string

func (*BuiltinSendPlugin) Description added in v1.130.0 

func (*BuiltinSendPlugin) Description() string

Description surfaces the tool in /plugin list and the agent tool catalog.

func (*BuiltinSendPlugin) Execute added in v1.130.0 

func (p *BuiltinSendPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses the args and dispatches to the adapter.

func (*BuiltinSendPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinSendPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream mirrors Execute — this plugin produces no incremental output, so the stream callback is ignored.

func (*BuiltinSendPlugin) Name added in v1.130.0 

func (*BuiltinSendPlugin) Name() string

Name returns "@send".

func (*BuiltinSendPlugin) Path added in v1.130.0 

func (*BuiltinSendPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinSendPlugin) Schema added in v1.130.0 

func (*BuiltinSendPlugin) Schema() string

Schema exposes a structured description the agent prompt builder renders into per-subcommand flag lists with examples.

func (*BuiltinSendPlugin) Usage added in v1.130.0 

func (*BuiltinSendPlugin) Usage() string

Usage explains the canonical invocation forms.

func (*BuiltinSendPlugin) Version added in v1.130.0 

func (*BuiltinSendPlugin) Version() string

Version is semver; bumped when the surface changes.

type BuiltinSessionPlugin added in v1.130.0 

type BuiltinSessionPlugin struct{}

BuiltinSessionPlugin is the @session tool.

func NewBuiltinSessionPlugin added in v1.130.0 

func NewBuiltinSessionPlugin() *BuiltinSessionPlugin

NewBuiltinSessionPlugin returns a ready-to-register plugin.

func (*BuiltinSessionPlugin) DescribeCall added in v1.130.0 

func (*BuiltinSessionPlugin) DescribeCall(args []string) string

func (*BuiltinSessionPlugin) Description added in v1.130.0 

func (*BuiltinSessionPlugin) Description() string

Description surfaces the tool.

func (*BuiltinSessionPlugin) Execute added in v1.130.0 

func (p *BuiltinSessionPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinSessionPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinSessionPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream ignores the stream callback.

func (*BuiltinSessionPlugin) IsConcurrencySafe added in v1.130.0 

func (*BuiltinSessionPlugin) IsConcurrencySafe() bool

IsConcurrencySafe — read-only over the session store.

func (*BuiltinSessionPlugin) Name added in v1.130.0 

func (*BuiltinSessionPlugin) Name() string

Name returns "@session".

func (*BuiltinSessionPlugin) Path added in v1.130.0 

func (*BuiltinSessionPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinSessionPlugin) Schema added in v1.130.0 

func (*BuiltinSessionPlugin) Schema() string

Schema describes the subcommands.

func (*BuiltinSessionPlugin) Usage added in v1.130.0 

func (*BuiltinSessionPlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinSessionPlugin) Version added in v1.130.0 

func (*BuiltinSessionPlugin) Version() string

Version is semver.

type BuiltinSkillPlugin added in v1.130.0 

type BuiltinSkillPlugin struct{}

BuiltinSkillPlugin is the @skill tool.

func NewBuiltinSkillPlugin added in v1.130.0 

func NewBuiltinSkillPlugin() *BuiltinSkillPlugin

NewBuiltinSkillPlugin returns a ready-to-register plugin.

func (*BuiltinSkillPlugin) DescribeCall added in v1.130.0 

func (*BuiltinSkillPlugin) DescribeCall(args []string) string

func (*BuiltinSkillPlugin) Description added in v1.130.0 

func (*BuiltinSkillPlugin) Description() string

Description surfaces the tool.

func (*BuiltinSkillPlugin) Execute added in v1.130.0 

func (p *BuiltinSkillPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinSkillPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinSkillPlugin) ExecuteWithStream(_ context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream ignores the stream callback.

func (*BuiltinSkillPlugin) Name added in v1.130.0 

func (*BuiltinSkillPlugin) Name() string

Name returns "@skill".

func (*BuiltinSkillPlugin) Path added in v1.130.0 

func (*BuiltinSkillPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinSkillPlugin) Schema added in v1.130.0 

func (*BuiltinSkillPlugin) Schema() string

Schema describes the subcommands.

func (*BuiltinSkillPlugin) Usage added in v1.130.0 

func (*BuiltinSkillPlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinSkillPlugin) Version added in v1.130.0 

func (*BuiltinSkillPlugin) Version() string

Version is semver.

type BuiltinSpeakPlugin added in v1.130.0 

type BuiltinSpeakPlugin struct{}

BuiltinSpeakPlugin is the @speak tool.

func NewBuiltinSpeakPlugin added in v1.130.0 

func NewBuiltinSpeakPlugin() *BuiltinSpeakPlugin

NewBuiltinSpeakPlugin returns a ready-to-register plugin.

func (*BuiltinSpeakPlugin) DescribeCall added in v1.130.0 

func (*BuiltinSpeakPlugin) DescribeCall(args []string) string

func (*BuiltinSpeakPlugin) Description added in v1.130.0 

func (*BuiltinSpeakPlugin) Description() string

Description surfaces the tool.

func (*BuiltinSpeakPlugin) Execute added in v1.130.0 

func (p *BuiltinSpeakPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute parses args and dispatches.

func (*BuiltinSpeakPlugin) ExecuteWithStream added in v1.130.0 

func (p *BuiltinSpeakPlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream runs synthesis. Progress feedback is the agent loop's animated spinner (this tool is blocking, not streaming).

func (*BuiltinSpeakPlugin) Name added in v1.130.0 

func (*BuiltinSpeakPlugin) Name() string

Name returns "@speak".

func (*BuiltinSpeakPlugin) Path added in v1.130.0 

func (*BuiltinSpeakPlugin) Path() string

Path is empty for builtin plugins.

func (*BuiltinSpeakPlugin) Schema added in v1.130.0 

func (*BuiltinSpeakPlugin) Schema() string

Schema describes the subcommands.

func (*BuiltinSpeakPlugin) Usage added in v1.130.0 

func (*BuiltinSpeakPlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinSpeakPlugin) Version added in v1.130.0 

func (*BuiltinSpeakPlugin) Version() string

Version is semver.

type BuiltinTodoPlugin added in v1.118.0 

type BuiltinTodoPlugin struct{}

BuiltinTodoPlugin exposes the agent's task tracker as an LLM-callable tool (Claude Code TodoWrite parity). Letting the model own its plan reduces ReAct loop drift: every turn the model sees the same plan it wrote, and reconciles in one place rather than re-deriving from prior turns.

func NewBuiltinTodoPlugin added in v1.118.0 

func NewBuiltinTodoPlugin() *BuiltinTodoPlugin

NewBuiltinTodoPlugin returns the singleton.

func (*BuiltinTodoPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinTodoPlugin) DescribeCall(args []string) string

DescribeCall surfaces the subcommand for the spinner. write and mark also surface the relevant identifier when present.

func (*BuiltinTodoPlugin) Description added in v1.118.0 

func (p *BuiltinTodoPlugin) Description() string

Description is shown in the model's tool catalog.

func (*BuiltinTodoPlugin) Execute added in v1.118.0 

func (p *BuiltinTodoPlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy synchronous entry-point.

func (*BuiltinTodoPlugin) ExecuteWithStream added in v1.118.0 

func (p *BuiltinTodoPlugin) ExecuteWithStream(_ context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream dispatches the subcommand to the wired adapter. The stream callback is unused — todo operations are atomic and produce a single result string, not an incremental log.

func (*BuiltinTodoPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinTodoPlugin) IsConcurrencySafe(args []string) bool

IsConcurrencySafe mirrors IsReadOnly. Two parallel list calls don't interfere; two parallel writes would race on the tracker mutex and produce undefined "which write wins" semantics that we want to surface deterministically (last call wins, but the user can audit the call order in serial execution).

func (*BuiltinTodoPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinTodoPlugin) IsReadOnly(args []string) bool

IsReadOnly returns true only for the list subcommand. write and mark mutate the in-process tracker; even though the change is confined to the agent loop's own state (no disk side-effect), the orchestrator should treat them as serial-only so per-task ordering stays well-defined.

func (*BuiltinTodoPlugin) JSONSchema added in v1.118.0 

func (p *BuiltinTodoPlugin) JSONSchema() string

JSONSchema returns the draft-2020-12 schema for @todo input. Three subcommand shapes are enumerated via oneOf so the validator rejects {"cmd":"write"} without args (the LLM's most common mistake when learning the tool).

func (*BuiltinTodoPlugin) Name added in v1.118.0 

func (p *BuiltinTodoPlugin) Name() string

Name is the LLM-visible tool name.

func (*BuiltinTodoPlugin) Path added in v1.118.0 

func (p *BuiltinTodoPlugin) Path() string

Path is the builtin sentinel.

func (*BuiltinTodoPlugin) Schema added in v1.118.0 

func (p *BuiltinTodoPlugin) Schema() string

Schema returns the JSON schema. Three subcommands:

  • write: replace the entire plan with todos[].
  • list: return the current progress.
  • mark: flip a single task by id (1-indexed).

func (*BuiltinTodoPlugin) Usage added in v1.118.0 

func (p *BuiltinTodoPlugin) Usage() string

Usage is the short shell-like example for /help.

func (*BuiltinTodoPlugin) Version added in v1.118.0 

func (p *BuiltinTodoPlugin) Version() string

Version follows semver tied to the tracker contract.

type BuiltinTreePlugin added in v1.118.0 

type BuiltinTreePlugin struct{}

BuiltinTreePlugin is the atomic directory-tree tool. Equivalent in spirit to the listing operations the Claude Code agent surfaces alongside Read+Grep. Same design as @read and @search: thin adapter over engine.handleTree with a flat dedicated schema.

func NewBuiltinTreePlugin added in v1.118.0 

func NewBuiltinTreePlugin() *BuiltinTreePlugin

NewBuiltinTreePlugin builds the @tree singleton.

func (*BuiltinTreePlugin) DescribeCall added in v1.118.0 

func (p *BuiltinTreePlugin) DescribeCall(args []string) string

DescribeCall surfaces the directory being listed.

func (*BuiltinTreePlugin) Description added in v1.118.0 

func (p *BuiltinTreePlugin) Description() string

Description is shown in the model's tool catalog.

func (*BuiltinTreePlugin) Execute added in v1.118.0 

func (p *BuiltinTreePlugin) Execute(ctx context.Context, args []string) (string, error)

Execute is the legacy synchronous entry-point.

func (*BuiltinTreePlugin) ExecuteWithStream added in v1.118.0 

func (p *BuiltinTreePlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

ExecuteWithStream parses args, converts to engine argv form, runs engine.handleTree. Output streams line-by-line.

func (*BuiltinTreePlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinTreePlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: multiple tree walks don't conflict.

func (*BuiltinTreePlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinTreePlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true: directory listing never mutates the tree.

func (*BuiltinTreePlugin) JSONSchema added in v1.118.0 

func (p *BuiltinTreePlugin) JSONSchema() string

JSONSchema returns the draft-2020-12 schema for @tree input. All fields are optional — bare {} defaults to listing the current workspace.

func (*BuiltinTreePlugin) MaxResultChars added in v1.118.0 

func (p *BuiltinTreePlugin) MaxResultChars() int

MaxResultChars raises the per-call truncation cap for @tree. Directory listings for monorepos can easily exceed 30k chars; the LLM uses the tree to navigate, so cutting the tail leaves it blind to deep subtrees. 50k strikes the balance between context budget and information density.

func (*BuiltinTreePlugin) Name added in v1.118.0 

func (p *BuiltinTreePlugin) Name() string

Name is the LLM-visible identifier.

func (*BuiltinTreePlugin) Path added in v1.118.0 

func (p *BuiltinTreePlugin) Path() string

Path is the builtin sentinel.

func (*BuiltinTreePlugin) Schema added in v1.118.0 

func (p *BuiltinTreePlugin) Schema() string

Schema is the flat JSON schema. The LLM passes {"dir":".", "depth":3} directly.

func (*BuiltinTreePlugin) Usage added in v1.118.0 

func (p *BuiltinTreePlugin) Usage() string

Usage is a short shell-like example for /help.

func (*BuiltinTreePlugin) Version added in v1.118.0 

func (p *BuiltinTreePlugin) Version() string

Version follows semver tied to the engine contract.

type BuiltinVoicePlugin added in v1.132.0 

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

BuiltinVoicePlugin toggles per-conversation voice replies.

func NewBuiltinVoicePlugin added in v1.132.0 

func NewBuiltinVoicePlugin(prefs *gateway.VoicePrefs) *BuiltinVoicePlugin

NewBuiltinVoicePlugin builds the plugin over the shared preference store.

func (*BuiltinVoicePlugin) Description added in v1.132.0 

func (*BuiltinVoicePlugin) Description() string

Description surfaces the tool to the model.

func (*BuiltinVoicePlugin) Execute added in v1.132.0 

func (p *BuiltinVoicePlugin) Execute(_ context.Context, args []string) (string, error)

Execute parses the envelope and applies the per-conversation preference.

func (*BuiltinVoicePlugin) ExecuteWithStream added in v1.132.0 

func (p *BuiltinVoicePlugin) ExecuteWithStream(ctx context.Context, args []string, _ func(string)) (string, error)

ExecuteWithStream delegates to Execute — this tool is instant, nothing to stream.

func (*BuiltinVoicePlugin) Name added in v1.132.0 

func (*BuiltinVoicePlugin) Name() string

Name is the tool identifier.

func (*BuiltinVoicePlugin) Path added in v1.132.0 

func (*BuiltinVoicePlugin) Path() string

Path is empty for builtins.

func (*BuiltinVoicePlugin) Schema added in v1.132.0 

func (*BuiltinVoicePlugin) Schema() string

Schema describes the accepted envelope for the agent tool layer.

func (*BuiltinVoicePlugin) Usage added in v1.132.0 

func (*BuiltinVoicePlugin) Usage() string

Usage explains the canonical invocation.

func (*BuiltinVoicePlugin) Version added in v1.132.0 

func (*BuiltinVoicePlugin) Version() string

Version is semver.

type BuiltinWebFetchPlugin added in v1.97.0 

type BuiltinWebFetchPlugin struct{}

BuiltinWebFetchPlugin provides web page fetching functionality.

func NewBuiltinWebFetchPlugin added in v1.97.0 

func NewBuiltinWebFetchPlugin() *BuiltinWebFetchPlugin

func (*BuiltinWebFetchPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinWebFetchPlugin) DescribeCall(args []string) string

DescribeCall surfaces the URL being fetched so the spinner reports "Fetching https://x.example/..." instead of the generic description.

func (*BuiltinWebFetchPlugin) Description added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Description() string

func (*BuiltinWebFetchPlugin) Execute added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Execute(ctx context.Context, args []string) (string, error)

func (*BuiltinWebFetchPlugin) ExecuteWithStream added in v1.97.0 

func (p *BuiltinWebFetchPlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

func (*BuiltinWebFetchPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinWebFetchPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: each fetch opens an independent HTTP connection. Two parallel fetches don't conflict, and net/http handles connection pooling under the hood with goroutine-safe semantics.

func (*BuiltinWebFetchPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinWebFetchPlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true whenever the invocation is a plain fetch (HTTP GET). When the caller asks the plugin to save the body to the session scratch dir via save_to_file, that is still a side-effect- only-in-scratch operation — read-only with respect to the user's working tree.

func (*BuiltinWebFetchPlugin) Name added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Name() string

func (*BuiltinWebFetchPlugin) Path added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Path() string

func (*BuiltinWebFetchPlugin) Schema added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Schema() string

func (*BuiltinWebFetchPlugin) Usage added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Usage() string

func (*BuiltinWebFetchPlugin) Version added in v1.97.0 

func (p *BuiltinWebFetchPlugin) Version() string

type BuiltinWebSearchPlugin added in v1.97.0 

type BuiltinWebSearchPlugin struct{}

BuiltinWebSearchPlugin provides web search with a pluggable backend chain.

Default order (CHATCLI_WEBSEARCH_PROVIDER unset or "auto"):

  1. DuckDuckGo HTML — zero-config default
  2. SearxNG self-hosted (SEARXNG_URL) — used as fallback when configured
  3. Brave Search HTML — independent index, zero config
  4. Mojeek HTML — independent index, zero config

Set CHATCLI_WEBSEARCH_PROVIDER to any provider name to move it to the front of the chain. On failure or empty results the chain falls through to the next backend.

func NewBuiltinWebSearchPlugin added in v1.97.0 

func NewBuiltinWebSearchPlugin() *BuiltinWebSearchPlugin

func (*BuiltinWebSearchPlugin) DescribeCall added in v1.118.0 

func (p *BuiltinWebSearchPlugin) DescribeCall(args []string) string

DescribeCall returns a contextual one-liner showing the query the user is searching for. Falls back to the static description when the query cannot be parsed out of the args. The label is i18n-resolved so the spinner respects the active locale.

func (*BuiltinWebSearchPlugin) Description added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Description() string

func (*BuiltinWebSearchPlugin) Execute added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Execute(ctx context.Context, args []string) (string, error)

func (*BuiltinWebSearchPlugin) ExecuteWithStream added in v1.97.0 

func (p *BuiltinWebSearchPlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

func (*BuiltinWebSearchPlugin) IsConcurrencySafe added in v1.118.0 

func (p *BuiltinWebSearchPlugin) IsConcurrencySafe(_ []string) bool

IsConcurrencySafe reports true: each search opens its own HTTP connection and writes only to the returned string. Two parallel searches do not interfere — they may share connection pools but that is goroutine-safe at the net/http layer.

func (*BuiltinWebSearchPlugin) IsReadOnly added in v1.118.0 

func (p *BuiltinWebSearchPlugin) IsReadOnly(_ []string) bool

IsReadOnly reports true for every invocation: web search is a GET over HTTPS, never mutates local state. Skipping the security prompt for read-only searches is part of the UX win in Fase 2.1.

func (*BuiltinWebSearchPlugin) Name added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Name() string

func (*BuiltinWebSearchPlugin) Path added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Path() string

func (*BuiltinWebSearchPlugin) Schema added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Schema() string

func (*BuiltinWebSearchPlugin) Usage added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Usage() string

func (*BuiltinWebSearchPlugin) Version added in v1.97.0 

func (p *BuiltinWebSearchPlugin) Version() string

type ConcurrencySafeAware added in v1.118.0 

type ConcurrencySafeAware interface {
	IsConcurrencySafe(args []string) bool
}

ConcurrencySafeAware is implemented by plugins whose invocations can safely run in parallel with other concurrency-safe invocations of the same OR different plugins. A plugin that mutates global state (writes files, edits a database, mutates the agent's tool context) MUST return false to opt out.

The orchestrator partitions a turn's tool calls into batches where each batch is either all-concurrency-safe (run in parallel up to CHATCLI_MAX_TOOL_CONCURRENCY) or all-serial. Mixed batches are split to preserve the relative order of serial steps.

type DescriberWithInput added in v1.118.0 

type DescriberWithInput interface {
	DescribeCall(args []string) string
}

DescriberWithInput supplements the static Description() with a contextual one-liner for the spinner / progress UI. Example: 

Read("/etc/hosts") -> "Reading /etc/hosts"
Search("Login")    -> "Searching for 'Login'"

The returned text MUST already be i18n-resolved by the plugin (it owns the locale lookup). Callers display it verbatim.

type ExecutablePlugin 

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

func (*ExecutablePlugin) Description 

func (p *ExecutablePlugin) Description() string

func (*ExecutablePlugin) Execute 

func (p *ExecutablePlugin) Execute(ctx context.Context, args []string) (string, error)

Execute mantém compatibilidade

func (*ExecutablePlugin) ExecuteWithStream added in v1.47.8 

func (p *ExecutablePlugin) ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)

ExecuteWithStream é a implementação real com callback

func (*ExecutablePlugin) Name 

func (p *ExecutablePlugin) Name() string

func (*ExecutablePlugin) Path 

func (p *ExecutablePlugin) Path() string

func (*ExecutablePlugin) Schema added in v1.38.6 

func (p *ExecutablePlugin) Schema() string

func (*ExecutablePlugin) Usage 

func (p *ExecutablePlugin) Usage() string

func (*ExecutablePlugin) Version 

func (p *ExecutablePlugin) Version() string

type JSONSchemaAware added in v1.118.0 

type JSONSchemaAware interface {
	JSONSchema() string
}

JSONSchemaAware is implemented by plugins that ship a JSON Schema (draft-2020-12) describing their input. The schema is the LLM-facing contract: when the model emits arguments the validator rejects, the orchestrator can fail fast with a clear "InvalidArgs" code instead of letting a type assertion panic deep inside the plugin.

Plugins that do NOT implement this interface bypass validation and keep working — Item 5 is purely additive. External plugins, MCP-sourced tools, and legacy builtins that have not migrated all continue to dispatch via the existing path.

The JSON Schema returned must be a valid draft-2020-12 document. Empty string is treated as "no schema" (same as not implementing the interface).

type KnowledgeAdapter added in v1.136.0 

type KnowledgeAdapter interface {
	// Search returns hybrid-ranked passages for query across the attached
	// knowledge bases (one of them when kb is non-empty).
	Search(query, kb string, topK int) (string, error)
	// Get returns one budget-bounded page of a source document, starting at
	// the given character offset.
	Get(source, kb string, offset int) (string, error)
	// TOC lists the source documents, optionally filtered by path prefix.
	TOC(kb, prefix string) (string, error)
	// List describes the knowledge bases attached to the session.
	List() (string, error)
}

KnowledgeAdapter is the interface the BuiltinKnowledgePlugin uses to reach the live context manager, bound to the current session.

type Manager 

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

Manager descobre, carrega e gerencia o ciclo de vida dos plugins.

func NewManager 

func NewManager(logger *zap.Logger) (*Manager, error)

func (*Manager) ClearRemotePlugins added in v1.60.0 

func (m *Manager) ClearRemotePlugins()

ClearRemotePlugins removes all remote plugins (identified by Path() == "[remote]").

func (*Manager) Close 

func (m *Manager) Close()

Close encerra o watcher de arquivos de forma segura.

func (*Manager) GetPlugin 

func (m *Manager) GetPlugin(name string) (Plugin, bool)

func (*Manager) GetPlugins 

func (m *Manager) GetPlugins() []Plugin

func (*Manager) PluginsDir 

func (m *Manager) PluginsDir() string

PluginsDir retorna o diretório onde os plugins estão instalados.

func (*Manager) RegisterBuiltinPlugin added in v1.60.0 

func (m *Manager) RegisterBuiltinPlugin(plugin Plugin)

RegisterBuiltinPlugin registers a builtin plugin. It is stored in a separate map so that Reload() can re-inject it when no external override exists.

func (*Manager) RegisterRemotePlugin added in v1.60.0 

func (m *Manager) RegisterRemotePlugin(plugin Plugin)

RegisterRemotePlugin registers a remote plugin in the manager without saving to disk. This allows remote plugins to be discoverable via GetPlugin/GetPlugins.

func (*Manager) Reload 

func (m *Manager) Reload()

Reload limpa e recarrega todos os plugins do diretório de plugins.

func (*Manager) SetShadowedBuiltins added in v1.97.0 

func (m *Manager) SetShadowedBuiltins(names []string)

SetShadowedBuiltins updates the set of built-in plugin names that are hidden because MCP servers declared them as overrides. Call this whenever MCP server connectivity changes so that built-ins are restored when servers disconnect.

type MemoryAdapter added in v1.123.0 

type MemoryAdapter interface {
	// Remember stores a single fact. category may be "" to auto-classify.
	Remember(content, category string) (string, error)
	// UpdateProfile applies key/value updates to the user profile.
	UpdateProfile(updates map[string]string) (string, error)
	// Forget removes facts whose content matches the substring.
	Forget(match string) (string, error)
	// Recall returns relevant stored memory (profile + facts) for query.
	// The implementation may run HyDE/embedding round-trips to widen recall
	// semantically; it bounds those internally.
	Recall(query string) (string, error)
}

MemoryAdapter is the interface the BuiltinMemoryPlugin uses to reach the live memory store. The chatcli top-level package provides an implementation bound to the current session.

type Metadata 

type Metadata struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Usage       string `json:"usage"`
	Version     string `json:"version"`
}

type MoaAdapter added in v1.130.0 

type MoaAdapter interface {
	// Run queries each member model with prompt in parallel, then has the
	// aggregator synthesize a single answer. Empty members → a sensible default
	// set drawn from configured providers. Empty aggregator → the session's
	// current model. Each member is "provider" or "provider:model".
	Run(ctx context.Context, prompt string, members []string, aggregator string) (string, error)
	// List reports the providers/models available to participate.
	List(ctx context.Context) (string, error)
}

MoaAdapter runs a Mixture-of-Agents query through the live LLM manager.

type Plugin 

type Plugin interface {
	Name() string
	Description() string
	Usage() string
	Version() string
	Path() string
	Schema() string
	Execute(ctx context.Context, args []string) (string, error)
	ExecuteWithStream(ctx context.Context, args []string, onOutput func(string)) (string, error)
}

func NewPluginFromPath 

func NewPluginFromPath(path string) (Plugin, error)

type PluginVerifier added in v1.97.0 

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

PluginVerifier verifies Ed25519 signatures on plugin binaries.

func NewPluginVerifier added in v1.97.0 

func NewPluginVerifier() *PluginVerifier

NewPluginVerifier creates a verifier that loads trusted keys from ~/.chatcli/trusted-keys/. Set CHATCLI_ALLOW_UNSIGNED_PLUGINS=true to allow unsigned plugins (dev only).

func (*PluginVerifier) AllowsUnsigned added in v1.97.0 

func (v *PluginVerifier) AllowsUnsigned() bool

AllowsUnsigned returns whether unsigned plugins are permitted.

func (*PluginVerifier) HasTrustedKeys added in v1.97.0 

func (v *PluginVerifier) HasTrustedKeys() bool

HasTrustedKeys returns whether any trusted public keys are loaded.

func (*PluginVerifier) VerifyPlugin added in v1.97.0 

func (v *PluginVerifier) VerifyPlugin(pluginPath string) error

VerifyPlugin checks the Ed25519 signature of a plugin binary. The .sig file must be adjacent to the plugin (e.g., myplugin.sig for myplugin). .sig format: first line is base64-encoded Ed25519 signature of the plugin's SHA256 hash.

type PromptOpts added in v1.118.0 

type PromptOpts struct {
	ToolName string
}

PromptOpts carries the context an LLM-aware plugin needs to produce a system-prompt slice. Today only ToolName is used; the struct exists so future fields (model family, locale, role mode) can be added without breaking the interface signature.

type Prompter added in v1.118.0 

type Prompter interface {
	Prompt(opts PromptOpts) (string, error)
}

Prompter is implemented by plugins that want to contribute a contextual snippet to the system prompt. Useful for tools whose usage instructions vary by environment (e.g. a workspace-aware /coder hints differ between Go and TypeScript projects).

type ReadOnlyAware added in v1.118.0 

type ReadOnlyAware interface {
	IsReadOnly(args []string) bool
}

ReadOnlyAware is implemented by plugins that can report whether a specific invocation has side effects. Read-only plugins skip the security confirmation prompt by default (modulo policy rules) and participate in the concurrent batch alongside other read-only tools.

The decision is per-input — `Read("/etc/passwd")` is read-only; `Read("--mutate-cache")` (hypothetical) would not be. The validator for the actual side-effect lives inside the plugin, where the schema is known.

type SchedulerAdapter added in v1.109.0 

type SchedulerAdapter interface {
	// Owner returns the principal for this invocation (e.g. agent name,
	// session id). Agents typically call with their own owner.
	Owner() SchedulerOwner
	ScheduleJob(ctx context.Context, owner SchedulerOwner, inputJSON string) (string, error)
	WaitUntil(ctx context.Context, owner SchedulerOwner, inputJSON string) (string, error)
	QueryJob(ctx context.Context, owner SchedulerOwner, inputJSON string) (string, error)
	ListJobs(ctx context.Context, owner SchedulerOwner, inputJSON string) (string, error)
	CancelJob(ctx context.Context, owner SchedulerOwner, inputJSON string) (string, error)
}

SchedulerAdapter is the interface the BuiltinSchedulerPlugin uses to reach the live scheduler. The chatcli top-level package provides an implementation bound to the current session.

type SchedulerOwner added in v1.109.0 

type SchedulerOwner struct {
	Kind string
	ID   string
	Tag  string
}

SchedulerOwner is the package-local mirror of scheduler.Owner (the plugins package cannot import cli/scheduler without an import cycle).

type SearchProvider added in v1.105.0 

type SearchProvider string

SearchProvider identifies a backend. Only backends that don't require a third-party API key are supported — by design, to keep chatcli usable in corporate environments without credential provisioning friction. 

const (
	ProviderAuto       SearchProvider = "auto"
	ProviderSearXNG    SearchProvider = "searxng"
	ProviderDuckDuckGo SearchProvider = "duckduckgo"
	ProviderBrave      SearchProvider = "brave"
	ProviderMojeek     SearchProvider = "mojeek"
)

func SelectSearchChainNames added in v1.105.0 

func SelectSearchChainNames() []SearchProvider

SelectSearchChainNames returns just the provider names in chain order. Exposed for display layers (e.g. /websearch status) that shouldn't touch the internal provider-entry struct.

type SendAdapter added in v1.130.0 

type SendAdapter interface {
	// Send delivers message to target. target is "platform" (home channel) or
	// "platform:chat_id" (e.g. "telegram:-100123", "whatsapp:+5511999999999").
	// Returns a short human/JSON result describing the outcome.
	Send(ctx context.Context, target, message string) (string, error)
	// List returns the configured platforms and any default targets.
	List(ctx context.Context) (string, error)
}

SendAdapter is the interface the BuiltinSendPlugin uses to deliver messages through the live gateway adapters. The chatcli top-level package provides an implementation bound to the configured platforms.

type SessionAdapter added in v1.130.0 

type SessionAdapter interface {
	// Search returns a formatted list of matching sessions with snippets.
	Search(ctx context.Context, query string, limit int) (string, error)
	// List returns the saved session names.
	List(ctx context.Context) (string, error)
}

SessionAdapter exposes saved-session search to the @session tool.

type StreamingInputAware added in v1.118.0 

type StreamingInputAware interface {
	UpdateStreamingInput(field, value string)
}

StreamingInputAware is implemented by plugins that want progressive updates as the LLM streams the tool's input arguments. Anthropic streams `input_json_delta` token by token; OpenAI streams `tool_calls[].function.arguments` deltas. The orchestrator parses those into field updates and calls UpdateStreamingInput for plugins that opt in.

Typical use: @websearch displays the query as it comes in; @webfetch shows the URL the moment it's complete; coder Read shows the path. Plugins that don't care leave this unimplemented and only see the final args.

type StructuredExecutor added in v1.118.0 

type StructuredExecutor interface {
	ExecuteStructured(ctx context.Context, args []string, onOutput func(string)) (StructuredResult, error)
}

StructuredExecutor is the optional interface a plugin implements when it wants to return a structured result instead of the legacy (string, error) pair. The plain Execute / ExecuteWithStream continue to work for plugins that have not migrated — the orchestrator wraps their output via agent.WrapLegacyOutput.

Streaming callback semantics are identical to ExecuteWithStream.

type StructuredResult added in v1.118.0 

type StructuredResult struct {
	Output    string
	IsError   bool
	ErrorCode string
	MCPMeta   map[string]any
}

StructuredResult is the provider-neutral, agent-internal representation of a tool invocation outcome. It mirrors cli/agent.ToolResult but lives in the plugins package so plugins (which sit below cli/agent in the dep graph) can emit it without an import cycle. The cli/agent layer wraps it into the ToolResult type used by the orchestrator.

Fields intentionally mirror ToolResult: Output / IsError / ErrorCode / MCPMeta. The richer fields (NewMessages, ContextMutation) live exclusively on ToolResult and are filled by the agent layer if it needs them.

func RunStructured added in v1.118.0 

func RunStructured(ctx context.Context, p Plugin, args []string, onOutput func(string)) (StructuredResult, error)

RunStructured executes the plugin and always returns a StructuredResult, preferring the structured executor when available and falling back to the legacy ExecuteWithStream pair otherwise. The infrastructure error (network timeout, ctx canceled, plugin binary not found) is returned separately so the orchestrator can decide whether to abort the batch.

func (StructuredResult) GetErrorCode added in v1.118.0 

func (r StructuredResult) GetErrorCode() string

GetErrorCode mirrors the ErrorCode field for the structuredCarrier interface.

func (StructuredResult) GetIsError added in v1.118.0 

func (r StructuredResult) GetIsError() bool

GetIsError mirrors the IsError field for the structuredCarrier interface.

func (StructuredResult) GetMCPMeta added in v1.118.0 

func (r StructuredResult) GetMCPMeta() map[string]any

GetMCPMeta mirrors the MCPMeta field for the structuredCarrier interface.

func (StructuredResult) GetOutput added in v1.118.0 

func (r StructuredResult) GetOutput() string

GetOutput returns the human/model-readable output. Satisfies the agent-side structuredCarrier interface without introducing an import of cli/plugins from cli/agent.

type TodoAdapter added in v1.118.0 

type TodoAdapter interface {
	// Write replaces the entire plan with the supplied items.
	// Returns the post-write progress summary.
	Write(items []TodoItem) (string, error)

	// List returns the current plan's progress summary.
	List() (string, error)

	// Mark sets the status of one task by its 1-indexed ID. Returns
	// an error when the id is out of range.
	Mark(id int, status string, errorMsg string) (string, error)
}

TodoAdapter is the interface the @todo plugin uses to manipulate the live agent task tracker. The cli package wires an implementation bound to the current AgentMode session at run start; the plugin stays decoupled from cli/agent.* concrete types.

Design mirrors Claude Code's TodoWrite tool: the LLM submits the full list of todos on each call (Write), or asks for the current state (List), or flips a single item by id (Mark). The replacement- semantics path is the canonical one — it makes the LLM the single source of truth for the plan, eliminating "tracker drift" where the model and the tracker disagree after a few turns.

type TodoItem added in v1.118.0 

type TodoItem struct {
	Description string `json:"description"`
	Status      string `json:"status,omitempty"` // pending | in_progress | completed | failed
}

TodoItem is the flat, LLM-facing view of a single planned task. Decoupled from the agent.TaskTracker.TaskSpec type so the plugins package stays out of the cli/agent dependency graph.

type TruncationAware added in v1.118.0 

type TruncationAware interface {
	MaxResultChars() int
}

TruncationAware is implemented by plugins that want fine-grained control over how their oversize output is trimmed before going into the LLM context. The global default (30 000 chars) made sense as a blanket safety net but punishes plugins like @search and @tree that legitimately produce large structured output the model needs in full, while letting @webfetch (which IS in turn handled by its own auto-save path) still hit a different threshold.

MaxResultChars returns the soft cap. Output longer than this is truncated using TruncateForLLM. A value <= 0 means "use the global default"; the orchestrator decides what that default is at runtime.

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.