core

package
v0.108.2 Latest Latest
Warning

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

Go to latest
Published: Sep 18, 2026 License: MIT Imports: 23 Imported by: 0

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

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

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

func NormalizeCoreToolName(name string) string

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

func ShellCommandArgs(shell []string, command string) (args []string, shellPath string, err error)

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 Edit added in v0.26.0

type Edit struct {
	OldText string `json:"old_text"`
	NewText string `json:"new_text"`
}

Edit represents a single replacement in a multi-edit operation.

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

type PasswordPromptCallback func(prompt string) (password string, cancelled bool)

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
}

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
}

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

type ToolOutputCallback func(toolCallID, toolName, chunk string, isStderr bool)

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.

Jump to

Keyboard shortcuts

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