Documentation
¶
Overview ¶
Package core provides the built-in core tools for KIT's coding agent. These tools are direct fantasy.AgentTool implementations — no MCP layer, no JSON-RPC, no serialization overhead. Core tool set: shell, read, write, edit, grep, find, ls.
Index ¶
- Constants
- func AllTools(opts ...ToolOption) []fantasy.AgentTool
- func CodingTools(opts ...ToolOption) []fantasy.AgentTool
- func ContextWithPasswordPrompt(ctx context.Context, callback PasswordPromptCallback) context.Context
- func ContextWithToolOutputCallback(ctx context.Context, callback ToolOutputCallback) context.Context
- func ListAllCoreToolNames() []string
- func ListedTools(toolList []string, opts ...ToolOption) []fantasy.AgentTool
- func NewEditTool(opts ...ToolOption) fantasy.AgentTool
- func NewFindTool(opts ...ToolOption) fantasy.AgentTool
- func NewGrepTool(opts ...ToolOption) fantasy.AgentTool
- func NewLsTool(opts ...ToolOption) fantasy.AgentTool
- func NewReadTool(opts ...ToolOption) fantasy.AgentTool
- func NewShellTool(opts ...ToolOption) fantasy.AgentTool
- func NewSubagentTool(opts ...ToolOption) fantasy.AgentTool
- func NewWriteTool(opts ...ToolOption) fantasy.AgentTool
- func NormalizeCoreToolName(name string) string
- func ReadOnlyTools(opts ...ToolOption) []fantasy.AgentTool
- func ShellCommandArgs(shell []string, command string) (args []string, shellPath string, err error)
- func SubagentTools(opts ...ToolOption) []fantasy.AgentTool
- func WithSubagentSpawner(ctx context.Context, fn SubagentSpawnFunc) context.Context
- type Edit
- type NamedAgentSpec
- type PasswordPromptCallback
- type SubagentSpawnFunc
- type SubagentSpawnRequest
- type SubagentSpawnResult
- type ToolConfig
- type ToolOption
- type ToolOutputCallback
- type TruncationResult
Constants ¶
const ( ShellToolName = "shell" LegacyShellToolName = "bash" )
The command-execution tool is a shell tool, and ShellToolName is its name: in the registry, in the tool definition sent to the model, and in a session transcript. It does not vary with the configured shell.
LegacyShellToolName is the name the tool had before the shell became configurable. It appears in existing user configuration and in existing sessions, so it is accepted wherever a user names the tool; see NormalizeCoreToolName.
const ( // DefaultMaxLines is the exported default line limit for truncation. DefaultMaxLines = defaultMaxLines // DefaultMaxBytes is the exported default byte limit for truncation. DefaultMaxBytes = defaultMaxBytes )
Variables ¶
This section is empty.
Functions ¶
func AllTools ¶
func AllTools(opts ...ToolOption) []fantasy.AgentTool
AllTools returns all available core tools.
func CodingTools ¶
func CodingTools(opts ...ToolOption) []fantasy.AgentTool
CodingTools returns the default set of core tools for a coding agent: shell, read, write, edit.
func ContextWithPasswordPrompt ¶ added in v0.53.0
func ContextWithPasswordPrompt(ctx context.Context, callback PasswordPromptCallback) context.Context
ContextWithPasswordPrompt returns a new context with the password prompt callback set. This allows the TUI to show a modal password prompt when sudo needs a password.
func ContextWithToolOutputCallback ¶ added in v0.20.0
func ContextWithToolOutputCallback(ctx context.Context, callback ToolOutputCallback) context.Context
ContextWithToolOutputCallback returns a new context with the tool output callback set.
func ListAllCoreToolNames ¶ added in v0.81.0
func ListAllCoreToolNames() []string
ListAllCoreToolNames always returns the full list of available core tools. It can be used to validate a user provided tool list.
func ListedTools ¶ added in v0.81.0
func ListedTools(toolList []string, opts ...ToolOption) []fantasy.AgentTool
ListedTools builds the named core tools. Names are normalized first, so a list carrying the shell tool's earlier name still selects it, and a name that matches no core tool is skipped rather than dereferenced.
func NewEditTool ¶
func NewEditTool(opts ...ToolOption) fantasy.AgentTool
NewEditTool creates the edit core tool.
func NewFindTool ¶
func NewFindTool(opts ...ToolOption) fantasy.AgentTool
NewFindTool creates the find core tool.
func NewGrepTool ¶
func NewGrepTool(opts ...ToolOption) fantasy.AgentTool
NewGrepTool creates the grep core tool.
func NewLsTool ¶
func NewLsTool(opts ...ToolOption) fantasy.AgentTool
NewLsTool creates the ls core tool.
func NewReadTool ¶
func NewReadTool(opts ...ToolOption) fantasy.AgentTool
NewReadTool creates the read core tool.
func NewShellTool ¶ added in v0.103.0
func NewShellTool(opts ...ToolOption) fantasy.AgentTool
NewShellTool creates the shell core tool. It runs one command string through the configured shell, which defaults to bash.
func NewSubagentTool ¶ added in v0.9.0
func NewSubagentTool(opts ...ToolOption) fantasy.AgentTool
NewSubagentTool creates the subagent core tool. When named agents are configured via WithNamedAgents, they are advertised in the tool description so the LLM can delegate to the right specialist.
func NewWriteTool ¶
func NewWriteTool(opts ...ToolOption) fantasy.AgentTool
NewWriteTool creates the write core tool.
func NormalizeCoreToolName ¶ added in v0.103.0
NormalizeCoreToolName maps a user-supplied core tool name onto its registry key, so that the earlier name for the shell tool keeps selecting it. An unrecognised name in include-core-tools or exclude-core-tools produces a warning and no effect, which is what this avoids.
func ReadOnlyTools ¶
func ReadOnlyTools(opts ...ToolOption) []fantasy.AgentTool
ReadOnlyTools returns tools for read-only exploration: read, grep, find, ls.
func ShellCommandArgs ¶ added in v0.103.0
ShellCommandArgs returns the process argument vector that runs one command string through the configured shell, and the SHELL value to advertise to child processes, empty when SHELL should stay inherited. It is the same construction the shell tool uses, exported so that the TUI's ! and !! commands execute through the same shell.
func SubagentTools ¶ added in v0.12.0
func SubagentTools(opts ...ToolOption) []fantasy.AgentTool
SubagentTools returns all core tools except subagent. This prevents infinite recursion when a subagent is itself a Kit instance.
func WithSubagentSpawner ¶ added in v0.12.0
func WithSubagentSpawner(ctx context.Context, fn SubagentSpawnFunc) context.Context
WithSubagentSpawner stores a spawn function in the context so that the subagent core tool can create in-process subagents.
Types ¶
type NamedAgentSpec ¶ added in v0.85.0
type NamedAgentSpec struct {
// Name is the value the LLM passes in the "agent" parameter.
Name string
// Description summarises what the agent does.
Description string
// Tools lists the tool names the agent may use. Empty means the full
// default subagent tool set.
Tools []string
}
NamedAgentSpec summarises a named agent definition for advertisement in the subagent tool description. It is intentionally minimal so the core package does not depend on the agent discovery machinery.
type PasswordPromptCallback ¶ added in v0.53.0
PasswordPromptCallback is the signature for password prompts. It receives a prompt message and returns the password and whether it was cancelled.
type SubagentSpawnFunc ¶ added in v0.12.0
type SubagentSpawnFunc func(ctx context.Context, req SubagentSpawnRequest) (*SubagentSpawnResult, error)
SubagentSpawnFunc is a callback that spawns an in-process subagent. The parent Kit instance injects this into the context so the core tool can call back without importing pkg/kit (which would create a cycle).
type SubagentSpawnRequest ¶ added in v0.85.0
type SubagentSpawnRequest struct {
// ToolCallID is the LLM-assigned ID of the subagent tool call,
// enabling the parent to correlate subagent events.
ToolCallID string
// Prompt is the task for the subagent (required).
Prompt string
// Agent optionally names a discovered agent definition whose presets
// (model, system prompt, tools, timeout) apply as defaults.
Agent string
// Model optionally overrides the model.
Model string
// SystemPrompt optionally overrides the system prompt.
SystemPrompt string
// Timeout bounds execution. Zero means "unset": the spawner applies
// the named agent's timeout (if any) or the default.
Timeout time.Duration
// SessionID optionally resumes an existing subagent session (the
// subagent_session_id returned by a previous run) instead of starting
// fresh, so follow-up tasks reuse the subagent's accumulated context.
SessionID string
}
SubagentSpawnRequest carries the parameters of an in-process subagent spawn from the subagent core tool to the parent Kit instance.
type SubagentSpawnResult ¶ added in v0.12.0
type SubagentSpawnResult struct {
Response string
Error error
SessionID string
InputTokens int64
OutputTokens int64
Elapsed time.Duration
// Killed is true when the user stopped the run (for example with
// /kill-subagent) before it completed.
Killed bool
}
SubagentSpawnResult carries the outcome of an in-process subagent spawn.
type ToolConfig ¶
type ToolConfig struct {
WorkDir string
// NamedAgents lists discovered named agent definitions advertised in
// the subagent tool description. Only the subagent tool consumes this.
NamedAgents []NamedAgentSpec
// ShellTimeout overrides the default per-call timeout for the shell tool.
// Zero uses the built-in default (120s). Only the shell tool consumes this.
ShellTimeout time.Duration
// ShellMaxTimeout overrides the ceiling a shell tool call may request via
// its timeout argument. Zero uses the built-in default (600s). Only the
// shell tool consumes this.
ShellMaxTimeout time.Duration
// Shell is the shell the shell tool runs a command string through, plus
// its own leading arguments, e.g. ["bash"] or ["busybox", "ash"]. Nil or
// empty uses the built-in default ["bash"]. This exists so KIT can run
// on images that do not ship bash (Alpine, distroless and similar). Only
// the shell tool consumes this.
Shell []string
// ImageLimits bounds the pixel size and encoded byte size of an image
// the read tool attaches to a message. The zero value applies the
// built-in defaults. Only the read tool consumes this.
ImageLimits media.Limits
}
ToolConfig holds configuration for tool construction.
func ApplyOptions ¶
func ApplyOptions(opts []ToolOption) ToolConfig
ApplyOptions applies the given ToolOptions to a ToolConfig and returns it.
type ToolOption ¶
type ToolOption func(*ToolConfig)
ToolOption configures tool behavior.
func WithImageLimits ¶ added in v0.114.0
func WithImageLimits(limits media.Limits) ToolOption
WithImageLimits bounds the images the read tool attaches to a message. A zero field inside limits keeps the built-in default for that field.
func WithNamedAgents ¶ added in v0.85.0
func WithNamedAgents(agents ...NamedAgentSpec) ToolOption
WithNamedAgents advertises named agent definitions in the subagent tool description so the LLM can delegate tasks to them by name.
func WithShell ¶ added in v0.103.0
func WithShell(argv []string) ToolOption
WithShell sets the shell the shell tool runs command strings through: the shell plus its own leading arguments, e.g. ["bash"] or ["busybox", "ash"]. A nil or empty vector leaves the built-in default ["bash"] in place, so an installation that sets nothing executes exactly what it did before.
func WithShellMaxTimeout ¶ added in v0.103.0
func WithShellMaxTimeout(d time.Duration) ToolOption
WithShellMaxTimeout sets the maximum timeout a shell tool call may request. A non-positive duration leaves the built-in default (600s) in place.
func WithShellTimeout ¶ added in v0.103.0
func WithShellTimeout(d time.Duration) ToolOption
WithShellTimeout sets the default per-call timeout for the shell tool. A non-positive duration leaves the built-in default (120s) in place.
func WithWorkDir ¶
func WithWorkDir(dir string) ToolOption
WithWorkDir sets the working directory for file-based tools. If empty, os.Getwd() is used at execution time.
type ToolOutputCallback ¶ added in v0.20.0
ToolOutputCallback is the signature for streaming tool output. It receives tool call ID, tool name, output chunk, and whether it's stderr.
type TruncationResult ¶
type TruncationResult struct {
Content string
Truncated bool
TruncBy string // "lines", "bytes", or ""
Total int // total lines before truncation
Kept int // lines kept after truncation
}
TruncationResult describes how output was truncated.
func TruncateTail ¶ added in v0.5.1
func TruncateTail(content string, maxLines, maxBytes int) TruncationResult
TruncateTail keeps the last maxLines lines and at most maxBytes bytes. Individual lines longer than defaultMaxLineLen are truncated to prevent extremely long single lines from blowing up the TUI when wrapped. Used for bash output where the tail is most relevant.