Documentation
¶
Overview ¶
Package codemode is the built-in `codemode` extension: the tool that lets the model write JavaScript that calls other tools. The script runs in the sandbox of package codemode (docs/specs/builtin-codemode-tool-search.md).
Scripts use `tools`, `ALL_TOOLS`, `text()`, `image()`, `exit()`, `store()`/`load()`, `console.*`, and `return <value>`, may start with a `// @options:` line, and reach the model catalog, classifiers, and image models through `models.*`. Results start with a "Script completed" or "Script failed" header.
Scripts can call the agent loop's nested tools: active `direct` tools and every `codemode` or `deferred` tool. Nested calls run through the agent loop's tool pipeline (`ToolContext.ExecuteTool`), so validation, `tool_call` and `tool_result` hooks, and permission checks apply exactly as for direct calls. Only the script's output reaches the model; nested results do not.
Ports packages/coding-agent/src/extensions/codemode/{tool,execute,renderer,index}.ts.
Index ¶
- Constants
- func CreateCodemodeExtension(options Options) extension.ExtensionFactory
- func CreateDescription(tools []extension.AgentTool, options DescriptionOptions) (string, error)
- func Definition(options Options) extension.ToolDefinition
- func DocsPath() string
- func Execute(ctx context.Context, toolCallID string, params json.RawMessage, ...) (agent.AgentToolResult, error)
- type DescriptionOptions
- type NestedCall
- type Options
- type StoreEntryData
- type ToolDetails
Constants ¶
const ( StatusRunning = "running" StatusOK = "ok" StatusError = "error" StatusCancelled = "cancelled" )
The nested call statuses.
const ( ModeOn = "on" ModeOnly = "only" )
Mode is how the tool presents tools that are both declared and callable from scripts.
const DefaultInlineBudget = 3000
DefaultInlineBudget is the default token budget for tool declarations in the description, in estimated tokens. upstream: packages/coding-agent/src/core/settings-defaults.ts:SETTINGS_DEFAULTS
const StoreEntryType = "codemode-store"
StoreEntryType is the custom entry type holding one script's `store()` writes: StoreEntryData.
const ToolName = "codemode"
ToolName is the name of the tool.
Variables ¶
This section is empty.
Functions ¶
func CreateCodemodeExtension ¶
func CreateCodemodeExtension(options Options) extension.ExtensionFactory
CreateCodemodeExtension is the factory of the `builtin:codemode` extension: it registers the tool inactive. Activate it with `--tools`, the `defaultTools` setting or `setActiveTools()`. The tool reads `codemode.mode` and `codemode.inlineBudget` through the API's GetSettings on every use, unless the options override them (upstream's readMode and readInlineBudget).
Ports packages/coding-agent/src/extensions/codemode/index.ts (createCodemodeExtension).
func CreateDescription ¶
func CreateDescription(tools []extension.AgentTool, options DescriptionOptions) (string, error)
CreateDescription is the model-facing description: the intro, one line per script global (with `models` when options.Models is set), and one section per listed tool, grouped by namespace. Deferred tools are never listed and do not affect the description at all, so it stays the same while tools are registered late (for example by MCP servers that connect). Tool sections are limited to the inline budget.
func Definition ¶
func Definition(options Options) extension.ToolDefinition
Definition is the tool definition of `codemode`, without the registration flag: Extension registers it inactive.
Ports packages/coding-agent/src/extensions/codemode/tool.ts (createCodemodeToolDefinition).
func DocsPath ¶
func DocsPath() string
DocsPath is the reference for scripts: globals, tool results, `store()`, the `models` API, and limits. It is the codemode page of the documentation bundle PiG materializes under its config root, the directory the system prompt's docs section names.
Ports packages/coding-agent/src/extensions/codemode/tool.ts (CODEMODE_DOCS_PATH).
func Execute ¶
func Execute(ctx context.Context, toolCallID string, params json.RawMessage, onUpdate agent.ToolUpdateCallback, options Options) (agent.AgentToolResult, error)
Execute runs one script. Without a session context (a plain Agent or a direct call) scripts cannot call tools, `store()` starts empty, and writes are dropped.
Ports packages/coding-agent/src/extensions/codemode/execute.ts (executeCodemode).
Types ¶
type DescriptionOptions ¶
type DescriptionOptions struct {
// Models names the `models` global; only for tools created with model access.
Models bool
// Namespaces holds the namespace of each tool, by tool name. Tools of one namespace are listed under one heading.
Namespaces map[string]extension.ToolNamespace
// Deferred names the tools that are callable but never listed. They do not affect the description at all, so it
// stays the same while MCP servers connect or change their tools.
Deferred map[string]bool
// Guidelines holds the prompt guidelines of each tool, by tool name, listed after its description.
Guidelines map[string][]string
// InlineBudget is the estimated tokens (characters / 4) the tool sections may use; tools that do not fit are
// left out like deferred tools. Nil lists every tool that is not deferred.
InlineBudget *int
}
DescriptionOptions configures CreateDescription.
type NestedCall ¶
type NestedCall struct {
// ID is the tool call id of the nested call, `<codemode call id>/<n>`.
ID string `json:"id"`
Name string `json:"name"`
// Args is compact JSON of the arguments, truncated for display.
Args string `json:"args"`
Status string `json:"status"`
// DurationMs is nil until the call ends.
DurationMs *float64 `json:"durationMs,omitempty"`
// Error is the error text, truncated for display.
Error string `json:"error,omitempty"`
// Cost in USD of a `models.*` call that reported usage.
Cost *float64 `json:"cost,omitempty"`
}
NestedCall is one nested tool call as the tool result reports it.
type Options ¶
type Options struct {
// GetSettings returns the effective settings, read on every use: `codemode.mode` and `codemode.inlineBudget`.
// Nil means the defaults (mode `on`, the default budget).
GetSettings func() extension.Settings
// Mode overrides the `codemode.mode` setting: [ModeOn] or [ModeOnly]. Empty reads the setting.
//
// Ports packages/coding-agent/src/extensions/codemode/index.ts (CodemodeExtensionOptions.mode).
Mode string
// InlineBudget overrides the `codemode.inlineBudget` setting. Nil reads the setting.
//
// Ports packages/coding-agent/src/extensions/codemode/index.ts (CodemodeExtensionOptions.inlineBudget).
InlineBudget *int
// CacheDir holds wazero's on-disk compilation cache for the sandbox module; empty compiles in memory.
CacheDir string
// Models declares and serves the `models` namespace of the tool [Definition] (createCodemodeToolDefinition's
// `models`, false by default). The [Extension] sets it unless DisableModels is set.
Models bool
// DisableModels leaves `models` out of the tool [Extension] registers. Upstream's createCodemodeExtension serves it
// unless its `models` option is false (index.ts `options.models ?? true`).
DisableModels bool
}
Options configures the extension.
type StoreEntryData ¶
type StoreEntryData struct {
Set map[string]json.RawMessage `json:"set"`
Delete []string `json:"delete"`
// Keys is the order MarshalJSON writes Set's keys in (StoreWrites.SetKeys); keys it lacks follow in JavaScript enumeration order.
Keys []string `json:"-"`
}
StoreEntryData is the data of a codemode-store entry.
func (StoreEntryData) MarshalJSON ¶
func (d StoreEntryData) MarshalJSON() ([]byte, error)
MarshalJSON writes the keys with their UTF-16 units, so an unpaired surrogate in a key reaches the entry as its \u escape rather than as U+FFFD.
type ToolDetails ¶
type ToolDetails struct {
Calls []NestedCall `json:"calls"`
// FullOutputPath is the temp file with the full text output, when the output was truncated.
FullOutputPath string `json:"fullOutputPath,omitempty"`
}
ToolDetails are the details of a codemode tool result.