codemode

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 28 Imported by: 0

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

View Source
const (
	StatusRunning   = "running"
	StatusOK        = "ok"
	StatusError     = "error"
	StatusCancelled = "cancelled"
)

The nested call statuses.

View Source
const (
	ModeOn   = "on"
	ModeOnly = "only"
)

Mode is how the tool presents tools that are both declared and callable from scripts.

View Source
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

View Source
const StoreEntryType = "codemode-store"

StoreEntryType is the custom entry type holding one script's `store()` writes: StoreEntryData.

View Source
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), the shared MCP types when listed tools need them, 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 MCP servers connect or change their tools. 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL