kit

package
v0.12.2 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2026 License: MIT Imports: 23 Imported by: 0

README

KIT SDK

The KIT SDK allows you to use KIT programmatically from Go applications without spawning OS processes.

Installation

go get github.com/mark3labs/kit

Basic Usage

package main

import (
    "context"
    "fmt"
    "log"
    
    kit "github.com/mark3labs/kit/pkg/kit"
)

func main() {
    ctx := context.Background()
    
    // Create Kit instance with default configuration
    host, err := kit.New(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }
    defer host.Close()
    
    // Send a prompt
    response, err := host.Prompt(ctx, "What is 2+2?")
    if err != nil {
        log.Fatal(err)
    }
    
    fmt.Println(response)
}

Configuration

The SDK behaves identically to the CLI:

  • Loads configuration from ~/.kit.yml by default
  • Creates default configuration if none exists
  • Respects all environment variables (KIT_*)
  • Uses the same defaults as the CLI
Options

You can override specific settings:

host, err := kit.New(ctx, &kit.Options{
    Model:        "ollama/llama3",            // Override model
    SystemPrompt: "You are a helpful bot",   // Override system prompt
    ConfigFile:   "/path/to/config.yml",     // Use specific config file
    MaxSteps:     10,                        // Override max steps
    Streaming:    true,                      // Enable streaming
    Quiet:        true,                      // Suppress debug output
})

Advanced Usage

With Tool Callbacks

Monitor tool execution in real-time:

response, err := host.PromptWithCallbacks(
    ctx,
    "List files in the current directory",
    func(name, args string) {
        fmt.Printf("Calling tool: %s\n", name)
    },
    func(name, args, result string, isError bool) {
        if isError {
            fmt.Printf("Tool %s failed: %s\n", name, result)
        } else {
            fmt.Printf("Tool %s succeeded\n", name)
        }
    },
    func(chunk string) {
        fmt.Print(chunk) // Stream output
    },
)
Session Management

Maintain conversation context:

// First message
host.Prompt(ctx, "My name is Alice")

// Second message (remembers context)
response, _ := host.Prompt(ctx, "What's my name?")
// Response: "Your name is Alice"

// Save session
host.SaveSession("./session.json")

// Load session later
host.LoadSession("./session.json")

// Clear session
host.ClearSession()

API Reference

Types
  • Kit - Main SDK type
  • Options - Configuration options
  • Message - Conversation message
  • ToolCall - Tool invocation details
Methods
  • New(ctx, opts) - Create new Kit instance
  • Prompt(ctx, message) - Send message and get response
  • PromptWithCallbacks(ctx, message, ...) - Send message with progress callbacks
  • LoadSession(path) - Load session from file
  • SaveSession(path) - Save session to file
  • ClearSession() - Clear conversation history
  • GetSessionManager() - Get session manager for advanced usage
  • GetModelString() - Get current model string
  • Close() - Clean up resources

Environment Variables

All CLI environment variables work with the SDK:

  • KIT_MODEL - Override model
  • ANTHROPIC_API_KEY - Anthropic API key
  • OPENAI_API_KEY - OpenAI API key
  • GEMINI_API_KEY - Google API key
  • etc.

License

Same as KIT CLI

Documentation

Index

Constants

View Source 
const (
	ToolKindExecute  = "execute" // Shell execution (bash)
	ToolKindEdit     = "edit"    // File modification (edit, write)
	ToolKindRead     = "read"    // File reading (read, ls)
	ToolKindSearch   = "search"  // Content/file search (grep, find)
	ToolKindSubagent = "agent"   // Subagent spawning (spawn_subagent)
)

ToolKind constants classify what a tool does, enabling UIs to render appropriate visualizations (e.g. diff view for edit tools, command+output for execute tools) and file trackers to identify which results contain modifications.

View Source 
const (
	RoleUser      = message.RoleUser
	RoleAssistant = message.RoleAssistant
	RoleTool      = message.RoleTool
	RoleSystem    = message.RoleSystem
)

Variables

View Source 
var (
	// ParseModelString parses a model string in "provider/model" format.
	ParseModelString = models.ParseModelString
	// CreateProvider creates a fantasy LanguageModel based on provider config.
	CreateProvider = models.CreateProvider
	// GetGlobalRegistry returns the global models registry instance.
	GetGlobalRegistry = models.GetGlobalRegistry
	// LoadSystemPrompt loads system prompt from file or returns string directly.
	LoadSystemPrompt = config.LoadSystemPrompt
)
View Source 
var WithWorkDir = core.WithWorkDir

WithWorkDir sets the working directory for file-based tools. If empty, os.Getwd() is used at execution time.

Functions

func CheckProviderReady 

func CheckProviderReady(provider string) error

CheckProviderReady validates that a provider is properly configured by checking that it exists in the registry and has required environment variables set.

func ConvertToFantasyMessages 

func ConvertToFantasyMessages(msg *Message) []fantasy.Message

ConvertToFantasyMessages converts an SDK message to the underlying fantasy messages used by the agent for LLM interactions.

func DeleteSession 

func DeleteSession(path string) error

DeleteSession removes a session file from disk.

func FormatSkillsForPrompt 

func FormatSkillsForPrompt(s []*Skill) string

FormatSkillsForPrompt formats skills for inclusion in a system prompt. Each skill is rendered as a named section with its content.

func GetAnthropicAPIKey 

func GetAnthropicAPIKey() string

GetAnthropicAPIKey resolves the Anthropic API key using the standard resolution order: stored credentials -> ANTHROPIC_API_KEY env var. Returns an empty string if no key is found.

func GetFantasyProviders 

func GetFantasyProviders() []string

GetFantasyProviders returns provider IDs that can be used with fantasy, either through a native provider or via openaicompat auto-routing.

func GetModelsForProvider 

func GetModelsForProvider(provider string) (map[string]ModelInfo, error)

GetModelsForProvider returns all known models for a provider.

func GetSupportedProviders 

func GetSupportedProviders() []string

GetSupportedProviders returns all known provider names in the registry.

func HasAnthropicCredentials 

func HasAnthropicCredentials() bool

HasAnthropicCredentials checks if valid Anthropic credentials are stored (either OAuth token or API key).

func InitConfig 

func InitConfig(configFile string, debug bool) error

InitConfig initializes the viper configuration system. It searches for config files in standard locations and loads them with environment variable substitution.

configFile: explicit config file path (empty = search defaults). debug: if true, print warnings about missing configs to stderr.

func InitTreeSession 

func InitTreeSession(opts *Options) (*session.TreeManager, error)

InitTreeSession creates or opens a tree session based on the given options. Both kit.New() and the CLI use this function so session initialisation logic lives in one place.

Behaviour based on Options:

  • NoSession: in-memory tree session (no persistence)
  • Continue: resume most recent session for SessionDir (or cwd)
  • SessionPath: open a specific JSONL session file
  • default: create a new tree session for SessionDir (or cwd)

func LoadConfigWithEnvSubstitution 

func LoadConfigWithEnvSubstitution(configPath string) error

LoadConfigWithEnvSubstitution loads a config file with ${ENV_VAR} expansion.

func RefreshModelRegistry 

func RefreshModelRegistry()

RefreshModelRegistry reloads the global model database from the current data sources (cache -> embedded). Call after updating the cache.

func SuggestModels 

func SuggestModels(provider, invalidModel string) []string

SuggestModels returns model names similar to an invalid model string.

func ValidateEnvironment 

func ValidateEnvironment(provider string, apiKey string) error

ValidateEnvironment checks if required API keys are set for a provider. Returns nil for providers not in the registry (unknown providers are assumed to handle auth themselves or via --provider-api-key).

Types

type AfterToolResultHook 

type AfterToolResultHook struct {
	ToolCallID string
	ToolName   string
	ToolArgs   string
	Result     string
	IsError    bool
}

AfterToolResultHook is the input for hooks that fire after a tool executes.

type AfterToolResultResult 

type AfterToolResultResult struct {
	Result  *string // non-nil overrides the result text
	IsError *bool   // non-nil overrides the error flag
}

AfterToolResultResult can modify the tool's output before it reaches the LLM.

type AfterTurnHook 

type AfterTurnHook struct {
	Response string
	Error    error
}

AfterTurnHook is the input for hooks that fire after a prompt turn completes.

type AfterTurnResult 

type AfterTurnResult struct{}

AfterTurnResult is a placeholder — after-turn hooks are observation-only.

type AgentConfig 

type AgentConfig = agent.AgentConfig

AgentConfig holds configuration options for creating a new Agent.

type AnthropicCredentials 

type AnthropicCredentials = auth.AnthropicCredentials

AnthropicCredentials holds Anthropic API credentials supporting both OAuth and API key authentication methods.

type BeforeCompactHook added in v0.3.0 

type BeforeCompactHook struct {
	// EstimatedTokens is the estimated token count of the conversation.
	EstimatedTokens int
	// ContextLimit is the model's context window size in tokens.
	ContextLimit int
	// UsagePercent is the fraction of context used (0.0–1.0).
	UsagePercent float64
	// MessageCount is the number of messages in the conversation.
	MessageCount int
	// IsAutomatic is true when compaction was triggered automatically.
	IsAutomatic bool
}

BeforeCompactHook is the input for hooks that fire before compaction runs.

type BeforeCompactResult added in v0.3.0 

type BeforeCompactResult struct {
	// Cancel, when true, prevents compaction from proceeding.
	Cancel bool
	// Reason is a human-readable explanation when Cancel is true.
	Reason string
}

BeforeCompactResult controls whether compaction proceeds.

type BeforeToolCallHook 

type BeforeToolCallHook struct {
	ToolCallID string
	ToolName   string
	ToolArgs   string
}

BeforeToolCallHook is the input for hooks that fire before a tool executes.

type BeforeToolCallResult 

type BeforeToolCallResult struct {
	Block  bool   // true prevents the tool from running
	Reason string // human-readable reason for blocking
}

BeforeToolCallResult controls whether the tool call proceeds.

type BeforeTurnHook 

type BeforeTurnHook struct {
	Prompt string
}

BeforeTurnHook is the input for hooks that fire before a prompt turn.

type BeforeTurnResult 

type BeforeTurnResult struct {
	Prompt       *string // override prompt text in the user message
	SystemPrompt *string // prepend a system message
	InjectText   *string // prepend a user context message
}

BeforeTurnResult can modify the prompt, inject system messages, or add context.

type CLIOptions added in v0.2.0 

type CLIOptions struct {
	// MCPConfig is a pre-loaded MCP config. When set, LoadAndValidateConfig
	// is skipped during Kit creation.
	MCPConfig *config.Config
	// ShowSpinner shows a loading spinner for Ollama models.
	ShowSpinner bool
	// SpinnerFunc provides the spinner implementation (nil = no spinner).
	SpinnerFunc SpinnerFunc
	// UseBufferedLogger buffers debug messages for later display.
	UseBufferedLogger bool
}

CLIOptions holds fields only relevant to the CLI binary. SDK users should not need these; they are separated to keep the main Options struct clean.

type CompactionEvent 

type CompactionEvent struct {
	Summary         string
	OriginalTokens  int
	CompactedTokens int
	MessagesRemoved int
}

CompactionEvent fires after a successful compaction.

func (CompactionEvent) EventType 

func (e CompactionEvent) EventType() EventType

EventType implements Event.

type CompactionOptions 

type CompactionOptions = compaction.CompactionOptions

CompactionOptions configures compaction behaviour.

type CompactionResult 

type CompactionResult = compaction.CompactionResult

CompactionResult contains statistics from a compaction operation.

type Config 

type Config = config.Config

Config represents the complete application configuration including MCP servers, model settings, UI preferences, and API credentials.

type ContentPart 

type ContentPart = message.ContentPart

ContentPart is the marker interface for all message content block types.

type ContextFile 

type ContextFile struct {
	Path    string // Absolute filesystem path.
	Content string // Full file content.
}

ContextFile represents a project context file (e.g. AGENTS.md) that was loaded during initialization and injected into the system prompt.

type ContextPrepareHook added in v0.3.0 

type ContextPrepareHook struct {
	// Messages is the current context as fantasy.Message objects.
	Messages []fantasy.Message
}

ContextPrepareHook is the input for hooks that fire after the context window is assembled from the session tree (including compaction) and before the messages are sent to the LLM. Hooks can filter, reorder, or inject messages.

type ContextPrepareResult added in v0.3.0 

type ContextPrepareResult struct {
	// Messages replaces the entire context window. If nil, the original
	// messages are used.
	Messages []fantasy.Message
}

ContextPrepareResult can replace the context window.

type ContextStats 

type ContextStats struct {
	EstimatedTokens int     // Estimated token count of the current conversation
	ContextLimit    int     // Model's context window size (tokens), 0 if unknown
	UsagePercent    float64 // Fraction of context used (0.0–1.0), 0 if limit unknown
	MessageCount    int     // Number of messages in the conversation
}

ContextStats contains current context usage information.

type CredentialManager 

type CredentialManager = auth.CredentialManager

CredentialManager manages API keys and OAuth credentials.

func NewCredentialManager 

func NewCredentialManager() (*CredentialManager, error)

NewCredentialManager creates a credential manager for secure storage and retrieval of authentication credentials.

type CredentialStore 

type CredentialStore = auth.CredentialStore

CredentialStore holds all stored credentials for various providers.

type DiffBlock added in v0.12.0 

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

DiffBlock represents a single old→new text replacement within a file.

type Event 

type Event interface {
	EventType() EventType
}

Event is the interface implemented by all lifecycle events. Each concrete event type returns its EventType via this method.

type EventListener 

type EventListener func(event Event)

EventListener is a callback that receives lifecycle events.

type EventType 

type EventType string

EventType identifies the kind of lifecycle event. 

const (
	// EventTurnStart fires before the agent begins processing a prompt.
	EventTurnStart EventType = "turn_start"
	// EventTurnEnd fires after the agent finishes processing (success or error).
	EventTurnEnd EventType = "turn_end"
	// EventMessageStart fires when a new assistant message begins.
	EventMessageStart EventType = "message_start"
	// EventMessageUpdate fires for each streaming text chunk.
	EventMessageUpdate EventType = "message_update"
	// EventMessageEnd fires when the assistant message is complete.
	EventMessageEnd EventType = "message_end"
	// EventToolCall fires when a tool call has been parsed and is about to execute.
	EventToolCall EventType = "tool_call"
	// EventToolExecutionStart fires when a tool begins executing.
	EventToolExecutionStart EventType = "tool_execution_start"
	// EventToolExecutionEnd fires when a tool finishes executing.
	EventToolExecutionEnd EventType = "tool_execution_end"
	// EventToolResult fires after a tool execution completes with its result.
	EventToolResult EventType = "tool_result"
	// EventToolCallContent fires when a step includes text alongside tool calls.
	EventToolCallContent EventType = "tool_call_content"
	// EventResponse fires when the LLM produces a final response.
	EventResponse EventType = "response"
	// EventCompaction fires after a successful compaction.
	EventCompaction EventType = "compaction"
	// EventReasoningDelta fires for each streaming reasoning/thinking chunk.
	EventReasoningDelta EventType = "reasoning_delta"
)

type FantasyMessage 

type FantasyMessage = fantasy.Message

FantasyMessage is the underlying message type used by the fantasy agent library. Re-exported so SDK users can work with fantasy types without a direct import of charm.land/fantasy.

type FantasyResponse 

type FantasyResponse = fantasy.Response

FantasyResponse is the response type returned by the fantasy agent library.

type FantasyUsage 

type FantasyUsage = fantasy.Usage

FantasyUsage contains token usage information from an LLM response.

type FileDiffInfo added in v0.12.0 

type FileDiffInfo struct {
	Path       string      `json:"path"`             // Absolute file path
	Additions  int         `json:"additions"`        // Lines added
	Deletions  int         `json:"deletions"`        // Lines removed
	IsNew      bool        `json:"is_new,omitempty"` // True if file was created (write only)
	DiffBlocks []DiffBlock `json:"diff_blocks,omitempty"`
}

FileDiffInfo describes a file modification from an edit or write tool.

type Finish 

type Finish = message.Finish

Finish marks the end of an assistant turn, carrying the stop reason.

type GenerateResult 

type GenerateResult = agent.GenerateWithLoopResult

GenerateResult contains the result and conversation history from an agent interaction.

type HookPriority 

type HookPriority int

HookPriority controls execution order of hooks. Lower values run first. 

const (
	// HookPriorityHigh runs before normal hooks.
	HookPriorityHigh HookPriority = 0
	// HookPriorityNormal is the default priority.
	HookPriorityNormal HookPriority = 50
	// HookPriorityLow runs after normal hooks.
	HookPriorityLow HookPriority = 100
)

type Kit 

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

Kit provides programmatic access to kit functionality, allowing integration of MCP tools and LLM interactions into Go applications. It manages agents, sessions, and model configurations.

func New 

func New(ctx context.Context, opts *Options) (*Kit, error)

func (*Kit) AppendExtensionEntry added in v0.3.0 

func (m *Kit) AppendExtensionEntry(extType, data string) (string, error)

AppendExtensionEntry persists custom extension data in the session tree.

func (*Kit) Branch 

func (m *Kit) Branch(entryID string) error

Branch moves the tree session's leaf pointer to the given entry ID, creating a branch point. Subsequent Prompt() calls will extend from the new position.

func (*Kit) ClearSession 

func (m *Kit) ClearSession()

ClearSession resets the tree session's leaf pointer to the root, starting a fresh conversation branch.

func (*Kit) Close 

func (m *Kit) Close() error

Close cleans up resources including MCP server connections, model resources, and the tree session file handle. Should be called when the Kit instance is no longer needed. Returns an error if cleanup fails.

func (*Kit) Compact 

func (m *Kit) Compact(ctx context.Context, opts *CompactionOptions, customInstructions string) (*CompactionResult, error)

Compact summarises older messages to reduce context usage. If opts is nil, the instance's CompactionOptions (or sensible defaults) are used. The model's context window is automatically populated from the model registry when opts.ContextWindow is 0.

customInstructions is optional text appended to the summary prompt (e.g. "Focus on the API design decisions"). Pass "" for the default prompt.

After compaction, the tree session is cleared and replaced with the compacted messages (summary + preserved recent messages).

func (*Kit) EmitBeforeFork added in v0.3.0 

func (m *Kit) EmitBeforeFork(targetID string, isUserMsg bool, userText string) (cancelled bool, reason string)

EmitBeforeFork emits a BeforeFork event to extensions and returns whether the fork was cancelled and the reason. No-op if extensions are disabled (returns false, "").

func (*Kit) EmitBeforeSessionSwitch added in v0.3.0 

func (m *Kit) EmitBeforeSessionSwitch(switchReason string) (cancelled bool, reason string)

EmitBeforeSessionSwitch emits a BeforeSessionSwitch event to extensions and returns whether the switch was cancelled and the reason. No-op if extensions are disabled (returns false, "").

func (*Kit) EmitExtensionCustomEvent added in v0.3.0 

func (m *Kit) EmitExtensionCustomEvent(name, data string)

EmitExtensionCustomEvent dispatches a named event to all extension handlers. No-op if extensions are disabled.

func (*Kit) EmitModelChange added in v0.3.0 

func (m *Kit) EmitModelChange(newModel, previousModel, source string)

EmitModelChange fires the ModelChange event for extensions. No-op if extensions are disabled or no handlers are registered.

func (*Kit) EmitSessionStart added in v0.2.0 

func (m *Kit) EmitSessionStart()

EmitSessionStart fires the SessionStart event for extensions. No-op if extensions are disabled or no handlers are registered.

func (*Kit) EstimateContextTokens 

func (m *Kit) EstimateContextTokens() int

EstimateContextTokens returns the estimated token count of the current conversation based on tree session messages.

func (*Kit) ExecuteCompletion added in v0.3.0 

func (m *Kit) ExecuteCompletion(ctx context.Context, req extensions.CompleteRequest) (extensions.CompleteResponse, error)

ExecuteCompletion makes a standalone LLM completion call for extensions. When req.Model is empty the current agent model is reused (no provider creation overhead). When req.Model is set a temporary provider is created, used, and closed.

func (*Kit) ExtensionCommands added in v0.2.0 

func (m *Kit) ExtensionCommands() []extensions.CommandDef

ExtensionCommands returns the slash commands registered by extensions. Returns nil if extensions are disabled or no commands are registered.

func (*Kit) FollowUp 

func (m *Kit) FollowUp(ctx context.Context, text string) (string, error)

FollowUp continues the conversation without explicit new user input. If text is empty, "Continue." is used as the prompt. Use FollowUp when the agent's previous response was truncated or you want the agent to elaborate.

Returns an error if there are no previous messages in the session.

func (*Kit) GetAgent deprecated 

func (m *Kit) GetAgent() *agent.Agent

GetAgent returns the underlying agent.

Deprecated: Use GetToolNames, GetLoadingMessage, GetLoadedServerNames, GetMCPToolCount, GetExtensionToolCount instead.

func (*Kit) GetAvailableModels added in v0.3.0 

func (m *Kit) GetAvailableModels() []extensions.ModelInfoEntry

GetAvailableModels returns a list of known models from the registry. Each entry includes provider, model ID, context limit, and whether the model supports reasoning. This is an advisory list — models not in the registry can still be used by specifying their provider/model string.

func (*Kit) GetBufferedDebugMessages added in v0.2.0 

func (m *Kit) GetBufferedDebugMessages() []string

GetBufferedDebugMessages returns any debug messages that were buffered during initialization, then clears the buffer. Returns nil if no messages were buffered or if buffered logging was not configured.

func (*Kit) GetBufferedLogger deprecated 

func (m *Kit) GetBufferedLogger() *tools.BufferedDebugLogger

GetBufferedLogger returns the buffered debug logger (nil if not configured).

Deprecated: Use GetBufferedDebugMessages instead.

func (*Kit) GetContextFiles 

func (m *Kit) GetContextFiles() []*ContextFile

GetContextFiles returns the context files (e.g. AGENTS.md) loaded during initialisation. Returns nil if no context files were found.

func (*Kit) GetContextStats 

func (m *Kit) GetContextStats() ContextStats

GetContextStats returns current context usage statistics including estimated token count, context limit, usage percentage, and message count.

When API-reported token counts are available (after at least one turn), EstimatedTokens uses the real input token count from the most recent API response. This is significantly more accurate than the text-based heuristic because it includes system prompts, tool definitions, and other overhead that the heuristic cannot account for.

func (*Kit) GetExtRunner deprecated 

func (m *Kit) GetExtRunner() *extensions.Runner

GetExtRunner returns the extension runner (nil if extensions are disabled).

Deprecated: Use SetExtensionContext and EmitSessionStart instead. GetExtRunner leaks the internal extensions.Runner type across the SDK boundary.

func (*Kit) GetExtensionContext added in v0.2.0 

func (m *Kit) GetExtensionContext() extensions.Context

GetExtensionContext returns the current extension runtime context. Returns a zero Context if extensions are disabled.

func (*Kit) GetExtensionEditor added in v0.2.0 

func (m *Kit) GetExtensionEditor() *extensions.EditorConfig

GetExtensionEditor returns the current editor interceptor, or nil if none is set. Returns nil if extensions are disabled.

func (*Kit) GetExtensionEntries added in v0.3.0 

func (m *Kit) GetExtensionEntries(extType string) []extensions.ExtensionEntry

GetExtensionEntries retrieves persisted extension data entries for a type.

func (*Kit) GetExtensionFooter added in v0.2.0 

func (m *Kit) GetExtensionFooter() *extensions.HeaderFooterConfig

GetExtensionFooter returns the current custom footer, or nil if none is set. Returns nil if extensions are disabled.

func (*Kit) GetExtensionHeader added in v0.2.0 

func (m *Kit) GetExtensionHeader() *extensions.HeaderFooterConfig

GetExtensionHeader returns the current custom header, or nil if none is set. Returns nil if extensions are disabled.

func (*Kit) GetExtensionMessageRenderer added in v0.3.0 

func (m *Kit) GetExtensionMessageRenderer(name string) *extensions.MessageRendererConfig

GetExtensionMessageRenderer returns the named message renderer, or nil if no extension registered a renderer with that name.

func (*Kit) GetExtensionOption added in v0.3.0 

func (m *Kit) GetExtensionOption(name string) string

GetExtensionOption resolves a named extension option value.

func (*Kit) GetExtensionShortcuts added in v0.3.0 

func (m *Kit) GetExtensionShortcuts() map[string]func()

GetExtensionShortcuts returns a map of key bindings to handler functions from all loaded extensions. Returns nil if no shortcuts are registered or extensions are disabled. Handlers are closures that capture the runner's current context, so they can call Print/SetStatus/etc.

func (*Kit) GetExtensionStatusEntries added in v0.3.0 

func (m *Kit) GetExtensionStatusEntries() []extensions.StatusBarEntry

GetExtensionStatusEntries returns all extension status bar entries sorted by priority.

func (*Kit) GetExtensionToolCount added in v0.2.0 

func (m *Kit) GetExtensionToolCount() int

GetExtensionToolCount returns the number of tools registered by extensions.

func (*Kit) GetExtensionToolInfos added in v0.3.0 

func (m *Kit) GetExtensionToolInfos() []extensions.ToolInfo

GetExtensionToolInfos returns information about all tools available to the agent, including enabled/disabled status from SetActiveTools. Each tool is categorized by source: "core", "mcp", or "extension".

func (*Kit) GetExtensionToolRenderer added in v0.2.0 

func (m *Kit) GetExtensionToolRenderer(toolName string) *extensions.ToolRenderConfig

GetExtensionToolRenderer returns the custom renderer for the named tool, or nil if no extension registered a renderer for it. Returns nil if extensions are disabled.

func (*Kit) GetExtensionUIVisibility added in v0.3.0 

func (m *Kit) GetExtensionUIVisibility() *extensions.UIVisibility

GetExtensionUIVisibility returns extension-provided UI visibility overrides, or nil if none have been set. Returns nil if extensions are disabled.

func (*Kit) GetExtensionWidgets added in v0.2.0 

func (m *Kit) GetExtensionWidgets(placement extensions.WidgetPlacement) []extensions.WidgetConfig

GetExtensionWidgets returns extension widgets matching the given placement. Returns nil if extensions are disabled or no widgets match.

func (*Kit) GetLoadedServerNames added in v0.2.0 

func (m *Kit) GetLoadedServerNames() []string

GetLoadedServerNames returns the names of successfully loaded MCP servers.

func (*Kit) GetLoadingMessage added in v0.2.0 

func (m *Kit) GetLoadingMessage() string

GetLoadingMessage returns the agent's startup info message (e.g. GPU fallback info), or empty string if none.

func (*Kit) GetMCPToolCount added in v0.2.0 

func (m *Kit) GetMCPToolCount() int

GetMCPToolCount returns the number of tools loaded from external MCP servers.

func (*Kit) GetModelInfo 

func (m *Kit) GetModelInfo() *ModelInfo

GetModelInfo returns detailed information about the current model (capabilities, pricing, limits). Returns nil if the model is not in the registry — this is expected for new models or custom fine-tunes.

func (*Kit) GetModelString 

func (m *Kit) GetModelString() string

GetModelString returns the current model string identifier (e.g., "anthropic/claude-sonnet-4-5-20250929" or "openai/gpt-4") being used by the agent.

func (*Kit) GetSessionFilePath added in v0.3.0 

func (m *Kit) GetSessionFilePath() string

GetSessionFilePath returns the JSONL file path of the current session.

func (*Kit) GetSessionID 

func (m *Kit) GetSessionID() string

GetSessionID returns the UUID of the active tree session, or empty when no tree session is configured.

func (*Kit) GetSessionMessages added in v0.3.0 

func (m *Kit) GetSessionMessages() []extensions.SessionMessage

GetSessionMessages returns the conversation messages on the current branch as extension-facing SessionMessage structs, ordered root to leaf.

func (*Kit) GetSessionPath 

func (m *Kit) GetSessionPath() string

GetSessionPath returns the file path of the active tree session, or empty for in-memory sessions or when no tree session is configured.

func (*Kit) GetSkills 

func (m *Kit) GetSkills() []*Skill

GetSkills returns the skills loaded during initialisation.

func (*Kit) GetStructuredMessages added in v0.12.0 

func (m *Kit) GetStructuredMessages() []StructuredMessage

GetStructuredMessages returns the conversation messages on the current branch with full typed content parts. Unlike GetSessionMessages() which flattens all content to a single text string, this preserves tool calls, tool results, reasoning blocks, and finish markers as distinct typed parts.

func (*Kit) GetThinkingLevel added in v0.7.0 

func (m *Kit) GetThinkingLevel() string

GetThinkingLevel returns the current thinking level.

func (*Kit) GetToolNames added in v0.2.0 

func (m *Kit) GetToolNames() []string

GetToolNames returns the names of all tools available to the agent.

func (*Kit) GetTools 

func (m *Kit) GetTools() []Tool

GetTools returns all tools available to the agent (core + MCP + extensions).

func (*Kit) GetTreeSession 

func (m *Kit) GetTreeSession() *TreeManager

GetTreeSession returns the tree session manager, or nil if not configured.

func (*Kit) HasExtensions added in v0.2.0 

func (m *Kit) HasExtensions() bool

HasExtensions returns true if the extension runner is configured and active.

func (*Kit) IsReasoningModel added in v0.7.0 

func (m *Kit) IsReasoningModel() bool

IsReasoningModel returns true if the current model supports extended thinking / reasoning.

func (*Kit) OnAfterToolResult 

func (m *Kit) OnAfterToolResult(p HookPriority, h func(AfterToolResultHook) *AfterToolResultResult) func()

OnAfterToolResult registers a hook that fires after each tool execution. Return a non-nil AfterToolResultResult to modify the tool's output before it reaches the LLM. Hooks execute in priority order; the first non-nil result wins. Returns an unregister function.

func (*Kit) OnAfterTurn 

func (m *Kit) OnAfterTurn(p HookPriority, h func(AfterTurnHook)) func()

OnAfterTurn registers a hook that fires after each prompt turn completes. This is observation-only — the handler cannot modify the response. Hooks execute in priority order. Returns an unregister function.

func (*Kit) OnBeforeCompact added in v0.3.0 

func (m *Kit) OnBeforeCompact(p HookPriority, h func(BeforeCompactHook) *BeforeCompactResult) func()

OnBeforeCompact registers a hook that fires before context compaction runs. Return a non-nil BeforeCompactResult with Cancel=true to prevent compaction. Hooks execute in priority order; the first non-nil result wins. Returns an unregister function.

func (*Kit) OnBeforeToolCall 

func (m *Kit) OnBeforeToolCall(p HookPriority, h func(BeforeToolCallHook) *BeforeToolCallResult) func()

OnBeforeToolCall registers a hook that fires before each tool execution. Return a non-nil BeforeToolCallResult with Block=true to prevent the tool from running. Hooks execute in priority order; the first non-nil result wins. Returns an unregister function.

func (*Kit) OnBeforeTurn 

func (m *Kit) OnBeforeTurn(p HookPriority, h func(BeforeTurnHook) *BeforeTurnResult) func()

OnBeforeTurn registers a hook that fires before each prompt turn. Return a non-nil BeforeTurnResult to modify the prompt, inject a system message, or prepend context. Hooks execute in priority order; the first non-nil result wins. Returns an unregister function.

func (*Kit) OnContextPrepare added in v0.3.0 

func (m *Kit) OnContextPrepare(p HookPriority, h func(ContextPrepareHook) *ContextPrepareResult) func()

OnContextPrepare registers a hook that fires after the context window is built from the session tree and before messages are sent to the LLM. Return a non-nil ContextPrepareResult with Messages to replace the entire context. Hooks execute in priority order; the first non-nil result wins. Returns an unregister function.

func (*Kit) OnResponse 

func (m *Kit) OnResponse(handler func(ResponseEvent)) func()

OnResponse registers a handler that fires only for ResponseEvent. Returns an unsubscribe function.

func (*Kit) OnStreaming 

func (m *Kit) OnStreaming(handler func(MessageUpdateEvent)) func()

OnStreaming registers a handler that fires only for MessageUpdateEvent (streaming text chunks). Returns an unsubscribe function.

func (*Kit) OnToolCall 

func (m *Kit) OnToolCall(handler func(ToolCallEvent)) func()

OnToolCall registers a handler that fires only for ToolCallEvent. Returns an unsubscribe function.

func (*Kit) OnToolResult 

func (m *Kit) OnToolResult(handler func(ToolResultEvent)) func()

OnToolResult registers a handler that fires only for ToolResultEvent. Returns an unsubscribe function.

func (*Kit) OnTurnEnd 

func (m *Kit) OnTurnEnd(handler func(TurnEndEvent)) func()

OnTurnEnd registers a handler that fires only for TurnEndEvent. Returns an unsubscribe function.

func (*Kit) OnTurnStart 

func (m *Kit) OnTurnStart(handler func(TurnStartEvent)) func()

OnTurnStart registers a handler that fires only for TurnStartEvent. Returns an unsubscribe function.

func (*Kit) Prompt 

func (m *Kit) Prompt(ctx context.Context, message string) (string, error)

Prompt sends a message to the agent and returns the response. The agent may use tools as needed to generate the response. The conversation history is automatically maintained in the tree session. Lifecycle events are emitted to all registered subscribers. Returns an error if generation fails.

func (*Kit) PromptResult 

func (m *Kit) PromptResult(ctx context.Context, message string) (*TurnResult, error)

PromptResult sends a message and returns the full turn result including usage statistics and conversation messages. Use this instead of Prompt() when you need more than just the response text.

func (*Kit) PromptResultWithFiles added in v0.7.0 

func (m *Kit) PromptResultWithFiles(ctx context.Context, message string, files []fantasy.FilePart) (*TurnResult, error)

PromptResultWithFiles sends a multimodal message (text + images) and returns the full turn result. The files parameter carries binary file data (e.g. clipboard images) that are included alongside the text in the user message.

func (*Kit) PromptWithCallbacks deprecated 

func (m *Kit) PromptWithCallbacks(
	ctx context.Context,
	message string,
	onToolCall func(name, args string),
	onToolResult func(name, args, result string, isError bool),
	onStreaming func(chunk string),
) (string, error)

PromptWithCallbacks sends a message with callbacks for monitoring tool execution and streaming responses. Lifecycle events are also emitted to all registered subscribers (via Subscribe).

Deprecated: Use Subscribe/OnToolCall/OnToolResult/OnStreaming instead of inline callbacks. PromptWithCallbacks is retained for backward compatibility.

func (*Kit) PromptWithOptions 

func (m *Kit) PromptWithOptions(ctx context.Context, msg string, opts PromptOptions) (string, error)

PromptWithOptions sends a message with per-call configuration. It behaves like Prompt but allows injecting an additional system message before the user prompt. Both messages are persisted to the session.

func (*Kit) ReloadExtensions added in v0.3.0 

func (m *Kit) ReloadExtensions() error

ReloadExtensions hot-reloads all extensions from disk. Event handlers, commands, renderers, and shortcuts update immediately. Extension-defined tools are NOT updated (they are baked into the agent at creation time).

func (*Kit) RemoveExtensionFooter added in v0.2.0 

func (m *Kit) RemoveExtensionFooter()

RemoveExtensionFooter removes the custom extension footer. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) RemoveExtensionHeader added in v0.2.0 

func (m *Kit) RemoveExtensionHeader()

RemoveExtensionHeader removes the custom extension header. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) RemoveExtensionStatus added in v0.3.0 

func (m *Kit) RemoveExtensionStatus(key string)

RemoveExtensionStatus removes a keyed status bar entry.

func (*Kit) RemoveExtensionWidget added in v0.2.0 

func (m *Kit) RemoveExtensionWidget(id string)

RemoveExtensionWidget removes a previously placed extension widget by ID. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) ResetExtensionEditor added in v0.2.0 

func (m *Kit) ResetExtensionEditor()

ResetExtensionEditor removes the active editor interceptor from extensions. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) SetExtensionActiveTools added in v0.3.0 

func (m *Kit) SetExtensionActiveTools(names []string)

SetExtensionActiveTools restricts the tool set to the named tools. All other tools are blocked from execution. Pass nil to re-enable all tools. No-op if extensions are disabled.

func (*Kit) SetExtensionContext added in v0.2.0 

func (m *Kit) SetExtensionContext(ctx extensions.Context)

SetExtensionContext configures the extension runner with the given context functions. No-op if extensions are disabled.

func (*Kit) SetExtensionEditor added in v0.2.0 

func (m *Kit) SetExtensionEditor(config extensions.EditorConfig)

SetExtensionEditor installs an editor interceptor from extensions. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) SetExtensionFooter added in v0.2.0 

func (m *Kit) SetExtensionFooter(config extensions.HeaderFooterConfig)

SetExtensionFooter places or replaces the custom footer from extensions. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) SetExtensionHeader added in v0.2.0 

func (m *Kit) SetExtensionHeader(config extensions.HeaderFooterConfig)

SetExtensionHeader places or replaces the custom header from extensions. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) SetExtensionOption added in v0.3.0 

func (m *Kit) SetExtensionOption(name, value string)

SetExtensionOption stores a runtime override for a named extension option.

func (*Kit) SetExtensionStatus added in v0.3.0 

func (m *Kit) SetExtensionStatus(entry extensions.StatusBarEntry)

SetExtensionStatus places or updates a keyed status bar entry.

func (*Kit) SetExtensionUIVisibility added in v0.3.0 

func (m *Kit) SetExtensionUIVisibility(v extensions.UIVisibility)

SetExtensionUIVisibility stores extension-provided UI visibility overrides. No-op if extensions are disabled.

func (*Kit) SetExtensionWidget added in v0.2.0 

func (m *Kit) SetExtensionWidget(config extensions.WidgetConfig)

SetExtensionWidget places or updates a persistent extension widget. Delegates to the extension runner. No-op if extensions are disabled.

func (*Kit) SetModel added in v0.3.0 

func (m *Kit) SetModel(ctx context.Context, modelString string) error

SetModel changes the active model at runtime. The existing tools, system prompt, and session are preserved. The model string should be in "provider/model" format (e.g. "anthropic/claude-sonnet-4-5-20250929"). Returns an error if the model string is invalid or the provider cannot be created.

func (*Kit) SetSessionName 

func (m *Kit) SetSessionName(name string) error

SetSessionName sets a user-defined display name for the active tree session.

func (*Kit) SetThinkingLevel added in v0.7.0 

func (m *Kit) SetThinkingLevel(ctx context.Context, level string) error

SetThinkingLevel changes the thinking level and recreates the agent with the new thinking budget. Returns an error if provider recreation fails.

func (*Kit) SetTreeSession 

func (m *Kit) SetTreeSession(ts *TreeManager)

SetTreeSession replaces the tree session on a Kit instance. This is used by the CLI when it handles session creation externally (e.g. --resume with a TUI picker) and needs to inject the result into a Kit-like workflow.

func (*Kit) ShouldCompact 

func (m *Kit) ShouldCompact() bool

ShouldCompact reports whether the conversation is near the model's context limit and should be compacted. Formula: contextTokens > contextWindow − reserveTokens. Returns false if the model's context limit is unknown.

func (*Kit) Steer 

func (m *Kit) Steer(ctx context.Context, instruction string) (string, error)

Steer injects a system-level instruction and triggers a new agent turn. Use Steer to dynamically adjust agent behavior mid-conversation without a visible user message — for example, changing tone, focus, or constraints.

Under the hood, Steer appends a system message (the instruction) followed by a synthetic user message so the agent acknowledges and follows the directive. Both messages are persisted to the session.

func (*Kit) Subagent added in v0.12.0 

func (m *Kit) Subagent(ctx context.Context, cfg SubagentConfig) (*SubagentResult, error)

Subagent spawns an in-process child Kit instance to perform a task. The child gets its own session, event bus, and agent loop but shares the parent's config (API keys, provider settings) and defaults to the parent's model when SubagentConfig.Model is empty.

This is the recommended way to run subagents in the SDK — no subprocess, no kit binary dependency, native Go types for results.

func (*Kit) Subscribe 

func (m *Kit) Subscribe(listener EventListener) func()

Subscribe registers an EventListener that will be called for every lifecycle event emitted during Prompt() and PromptWithCallbacks(). Returns an unsubscribe function that removes the listener.

func (*Kit) UpdateExtensionContextModel added in v0.3.0 

func (m *Kit) UpdateExtensionContextModel(model string)

UpdateExtensionContextModel updates the Model field on the extension context so subsequent event handlers see the new model. This is a targeted update that avoids replacing the entire Context struct.

type MCPServerConfig 

type MCPServerConfig = config.MCPServerConfig

MCPServerConfig represents configuration for an MCP server, supporting both local (stdio) and remote (StreamableHTTP/SSE) server types.

type Message 

type Message = message.Message

Message is a single conversation message containing heterogeneous content parts (text, reasoning, tool calls, tool results, finish markers).

func ConvertFromFantasyMessage 

func ConvertFromFantasyMessage(msg fantasy.Message) Message

ConvertFromFantasyMessage converts a fantasy message from the agent to an SDK message format for use in the SDK API.

type MessageEndEvent 

type MessageEndEvent struct {
	Content string
}

MessageEndEvent fires when the assistant message is complete.

func (MessageEndEvent) EventType 

func (e MessageEndEvent) EventType() EventType

EventType implements Event.

type MessageEntry 

type MessageEntry = session.MessageEntry

MessageEntry stores a conversation message as a tree entry in JSONL sessions.

type MessageRole 

type MessageRole = message.MessageRole

MessageRole identifies the sender of a message (user, assistant, tool, system).

type MessageStartEvent 

type MessageStartEvent struct{}

MessageStartEvent fires when a new assistant message begins.

func (MessageStartEvent) EventType 

func (e MessageStartEvent) EventType() EventType

EventType implements Event.

type MessageUpdateEvent 

type MessageUpdateEvent struct {
	Chunk string
}

MessageUpdateEvent fires for each streaming text chunk.

func (MessageUpdateEvent) EventType 

func (e MessageUpdateEvent) EventType() EventType

EventType implements Event.

type ModelCost 

type ModelCost = models.Cost

ModelCost represents the pricing information for a model.

type ModelInfo 

type ModelInfo = models.ModelInfo

ModelInfo represents information about a specific model (capabilities, pricing, limits).

func LookupModel 

func LookupModel(provider, modelID string) *ModelInfo

LookupModel returns information about a model, or nil if unknown.

type ModelLimit 

type ModelLimit = models.Limit

ModelLimit represents the context and output limits for a model.

type ModelsRegistry 

type ModelsRegistry = models.ModelsRegistry

ModelsRegistry provides validation and information about models, maintaining a registry of all supported LLM providers and their models.

type Options 

type Options struct {
	Model        string // Override model (e.g., "anthropic/claude-sonnet-4-5-20250929")
	SystemPrompt string // Override system prompt
	ConfigFile   string // Override config file path
	MaxSteps     int    // Override max steps (0 = use default)
	Streaming    bool   // Enable streaming (default from config)
	Quiet        bool   // Suppress debug output
	Tools        []Tool // Custom tool set. If empty, AllTools() is used.
	ExtraTools   []Tool // Additional tools added alongside core/MCP/extension tools.

	// Session configuration
	SessionDir  string // Base directory for session discovery (default: cwd)
	SessionPath string // Open a specific session file by path
	Continue    bool   // Continue the most recent session for SessionDir
	NoSession   bool   // Ephemeral mode — in-memory session, no persistence

	// Skills
	Skills    []string // Explicit skill files/dirs to load (empty = auto-discover)
	SkillsDir string   // Override default project-local skills directory

	// Compaction
	AutoCompact       bool               // Auto-compact when near context limit
	CompactionOptions *CompactionOptions // Config for auto-compaction (nil = defaults)

	// Debug enables debug logging for the SDK.
	Debug bool

	// CLI is optional CLI-specific configuration. SDK users leave this nil.
	CLI *CLIOptions
}

Options configures Kit creation with optional overrides for model, prompts, configuration, and behavior settings. All fields are optional and will use CLI defaults if not specified.

type PromptBuilder 

type PromptBuilder = skills.PromptBuilder

PromptBuilder composes a system prompt from a base prompt, skills, and arbitrary named sections.

func NewPromptBuilder 

func NewPromptBuilder(basePrompt string) *PromptBuilder

NewPromptBuilder creates a PromptBuilder with the given base system prompt. The base prompt is always emitted first.

type PromptOptions 

type PromptOptions struct {
	// SystemMessage is prepended as a system message before the user prompt.
	// Use it to inject per-call instructions or context without permanently
	// modifying the agent's system prompt.
	SystemMessage string
}

PromptOptions configures a single PromptWithOptions call.

type PromptTemplate 

type PromptTemplate = skills.PromptTemplate

PromptTemplate is a named text template with {{variable}} placeholders.

func LoadPromptTemplate 

func LoadPromptTemplate(path string) (*PromptTemplate, error)

LoadPromptTemplate reads a template from a file. The template name is derived from the filename (without extension).

func NewPromptTemplate 

func NewPromptTemplate(name, content string) *PromptTemplate

NewPromptTemplate creates a PromptTemplate, automatically extracting variable names from {{...}} placeholders in content.

type ProviderConfig 

type ProviderConfig = models.ProviderConfig

ProviderConfig holds configuration for creating LLM providers.

type ProviderInfo 

type ProviderInfo = models.ProviderInfo

ProviderInfo represents information about a model provider from the models.dev database.

func GetProviderInfo 

func GetProviderInfo(provider string) *ProviderInfo

GetProviderInfo returns information about a provider (env vars, API URL, etc.). Returns nil if the provider is not in the registry.

type ProviderResult 

type ProviderResult = models.ProviderResult

ProviderResult contains the result of provider creation (model + optional feedback message + closer).

type ReasoningContent 

type ReasoningContent = message.ReasoningContent

ReasoningContent holds extended thinking / reasoning output from the LLM.

type ReasoningDeltaEvent added in v0.7.0 

type ReasoningDeltaEvent struct {
	Delta string
}

ReasoningDeltaEvent fires for each streaming reasoning/thinking chunk.

func (ReasoningDeltaEvent) EventType added in v0.7.0 

func (e ReasoningDeltaEvent) EventType() EventType

EventType implements Event.

type ResponseEvent 

type ResponseEvent struct {
	Content string
}

ResponseEvent fires when the LLM produces a final response.

func (ResponseEvent) EventType 

func (e ResponseEvent) EventType() EventType

EventType implements Event.

type ResponseHandler 

type ResponseHandler = agent.ResponseHandler

ResponseHandler is a function type for handling LLM responses.

type SessionHeader 

type SessionHeader = session.SessionHeader

SessionHeader is the first line in a JSONL session file, carrying metadata.

type SessionInfo 

type SessionInfo = session.SessionInfo

SessionInfo contains metadata about a discovered session, used for listing and session picker display.

func ListAllSessions 

func ListAllSessions() ([]SessionInfo, error)

ListAllSessions finds all sessions across all working directories, sorted by modification time (newest first).

func ListSessions 

func ListSessions(dir string) ([]SessionInfo, error)

ListSessions finds all sessions for the given working directory, sorted by modification time (newest first). If dir is empty, the current working directory is used.

type Skill 

type Skill = skills.Skill

Skill represents a markdown-based instruction file with optional YAML frontmatter that provides domain-specific context and workflows.

func LoadSkill 

func LoadSkill(path string) (*Skill, error)

LoadSkill reads a single skill file (markdown with optional YAML frontmatter). If no frontmatter is present the skill name is derived from the filename.

func LoadSkills 

func LoadSkills(cwd string) ([]*Skill, error)

LoadSkills auto-discovers skills from standard directories:

  • Global: $XDG_CONFIG_HOME/kit/skills/ (default ~/.config/kit/skills/)
  • Project-local: <cwd>/.kit/skills/

cwd is the working directory for project-local discovery; if empty the current working directory is used.

func LoadSkillsFromDir 

func LoadSkillsFromDir(dir string) ([]*Skill, error)

LoadSkillsFromDir loads all skills from a single directory. It finds *.md and *.txt files directly in the directory, and SKILL.md files in immediate subdirectories.

type SpinnerFunc 

type SpinnerFunc = agent.SpinnerFunc

SpinnerFunc wraps a function in a loading spinner animation. Used for Ollama model loading. Signature: func(fn func() error) error.

type StreamingResponseHandler 

type StreamingResponseHandler = agent.StreamingResponseHandler

StreamingResponseHandler is a function type for handling streaming LLM responses.

type StructuredMessage added in v0.12.0 

type StructuredMessage struct {
	ID        string
	ParentID  string
	Role      MessageRole
	Parts     []ContentPart
	Model     string
	Provider  string
	Timestamp string // RFC3339 format
}

StructuredMessage represents a conversation message with typed content parts (tool calls, reasoning, finish markers, etc.) instead of flattened text.

type SubagentConfig added in v0.12.0 

type SubagentConfig struct {
	// Prompt is the task/instruction for the subagent (required).
	Prompt string

	// Model overrides the parent's model (e.g. "anthropic/claude-haiku-3-5-20241022").
	// Empty string uses the parent's current model.
	Model string

	// SystemPrompt provides domain-specific instructions for the subagent.
	// Empty string uses a minimal default prompt.
	SystemPrompt string

	// Tools overrides the tool set. If nil, SubagentTools() is used (all
	// core tools except spawn_subagent, preventing infinite recursion).
	Tools []Tool

	// NoSession, when true, uses an in-memory ephemeral session. When false
	// (default), the subagent's session is persisted and can be loaded for
	// replay/inspection.
	NoSession bool

	// Timeout limits execution time. Zero means 5 minute default.
	Timeout time.Duration

	// OnEvent, when set, receives all events from the subagent's event bus.
	// This enables the parent to stream subagent tool calls, text chunks,
	// etc. in real time.
	OnEvent func(Event)
}

SubagentConfig configures an in-process subagent spawned via Kit.Subagent().

type SubagentResult added in v0.12.0 

type SubagentResult struct {
	// Response is the subagent's final text response.
	Response string
	// Error is set if the subagent failed (nil on success).
	Error error
	// SessionID is the subagent's session identifier (for replay).
	SessionID string
	// StopReason is the LLM's finish reason for the subagent's final turn.
	StopReason string
	// Usage contains token usage from the subagent's run.
	Usage *FantasyUsage
	// Elapsed is the total execution time.
	Elapsed time.Duration
}

SubagentResult contains the outcome of an in-process subagent execution.

type TextContent 

type TextContent = message.TextContent

TextContent holds plain text content within a message.

type Tool 

type Tool = fantasy.AgentTool

Tool is the interface that all Kit tools implement.

func AllTools 

func AllTools(opts ...ToolOption) []Tool

AllTools returns all available core tools.

func CodingTools 

func CodingTools(opts ...ToolOption) []Tool

CodingTools returns the default set of core tools for a coding agent: bash, read, write, edit.

func NewBashTool 

func NewBashTool(opts ...ToolOption) Tool

NewBashTool creates a bash command execution tool.

func NewEditTool 

func NewEditTool(opts ...ToolOption) Tool

NewEditTool creates a surgical text-editing tool.

func NewFindTool 

func NewFindTool(opts ...ToolOption) Tool

NewFindTool creates a file search tool (uses fd when available).

func NewGrepTool 

func NewGrepTool(opts ...ToolOption) Tool

NewGrepTool creates a content search tool (uses ripgrep when available).

func NewLsTool 

func NewLsTool(opts ...ToolOption) Tool

NewLsTool creates a directory listing tool.

func NewReadTool 

func NewReadTool(opts ...ToolOption) Tool

NewReadTool creates a file-reading tool.

func NewWriteTool 

func NewWriteTool(opts ...ToolOption) Tool

NewWriteTool creates a file-writing tool.

func ReadOnlyTools 

func ReadOnlyTools(opts ...ToolOption) []Tool

ReadOnlyTools returns tools for read-only exploration: read, grep, find, ls.

func SubagentTools added in v0.12.0 

func SubagentTools(opts ...ToolOption) []Tool

SubagentTools returns all core tools except spawn_subagent. Use this when creating child Kit instances (in-process subagents) to prevent infinite recursion.

type ToolCall 

type ToolCall = message.ToolCall

ToolCall represents a tool invocation initiated by the LLM.

type ToolCallContentEvent 

type ToolCallContentEvent struct {
	Content string
}

ToolCallContentEvent fires when a step includes text alongside tool calls.

func (ToolCallContentEvent) EventType 

func (e ToolCallContentEvent) EventType() EventType

EventType implements Event.

type ToolCallContentHandler 

type ToolCallContentHandler = agent.ToolCallContentHandler

ToolCallContentHandler is a function type for handling content that accompanies tool calls.

type ToolCallEvent 

type ToolCallEvent struct {
	ToolCallID string // Stable ID for correlating tool lifecycle events
	ToolName   string
	ToolKind   string         // Tool classification: "execute", "edit", "read", "search", "agent"
	ToolArgs   string         // JSON-encoded arguments
	ParsedArgs map[string]any // Pre-parsed arguments for convenience (nil on parse failure)
}

ToolCallEvent fires when a tool call has been parsed.

func (ToolCallEvent) EventType 

func (e ToolCallEvent) EventType() EventType

EventType implements Event.

type ToolCallHandler 

type ToolCallHandler = agent.ToolCallHandler

ToolCallHandler is a function type for handling tool calls as they happen.

type ToolExecutionEndEvent 

type ToolExecutionEndEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
}

ToolExecutionEndEvent fires when a tool finishes executing.

func (ToolExecutionEndEvent) EventType 

func (e ToolExecutionEndEvent) EventType() EventType

EventType implements Event.

type ToolExecutionHandler 

type ToolExecutionHandler = agent.ToolExecutionHandler

ToolExecutionHandler is a function type for handling tool execution start/end events.

type ToolExecutionStartEvent 

type ToolExecutionStartEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
	ToolArgs   string
}

ToolExecutionStartEvent fires when a tool begins executing.

func (ToolExecutionStartEvent) EventType 

func (e ToolExecutionStartEvent) EventType() EventType

EventType implements Event.

type ToolOption 

type ToolOption = core.ToolOption

ToolOption configures tool behavior.

type ToolResult 

type ToolResult = message.ToolResult

ToolResult represents the result of executing a tool.

type ToolResultEvent 

type ToolResultEvent struct {
	ToolCallID string
	ToolName   string
	ToolKind   string
	ToolArgs   string
	ParsedArgs map[string]any // Pre-parsed arguments for convenience
	Result     string
	IsError    bool
	Metadata   *ToolResultMetadata // Optional structured metadata from tool execution
}

ToolResultEvent fires after a tool execution completes with its result.

func (ToolResultEvent) EventType 

func (e ToolResultEvent) EventType() EventType

EventType implements Event.

type ToolResultHandler 

type ToolResultHandler = agent.ToolResultHandler

ToolResultHandler is a function type for handling tool results.

type ToolResultMetadata added in v0.12.0 

type ToolResultMetadata struct {
	FileDiffs         []FileDiffInfo `json:"file_diffs,omitempty"`          // Present for edit/write tools
	SubagentSessionID string         `json:"subagent_session_id,omitempty"` // Present for spawn_subagent tool
}

ToolResultMetadata carries structured data from tool executions.

type TreeManager 

type TreeManager = session.TreeManager

TreeManager manages a tree-structured JSONL session with branching, leaf-pointer tracking, and context building.

type TurnEndEvent 

type TurnEndEvent struct {
	Response   string
	Error      error
	StopReason string // "end_turn", "max_tokens", "tool_use", "error", etc.
}

TurnEndEvent fires after the agent finishes processing.

func (TurnEndEvent) EventType 

func (e TurnEndEvent) EventType() EventType

EventType implements Event.

type TurnResult 

type TurnResult struct {
	// Response is the assistant's final text response.
	Response string

	// StopReason indicates why the turn ended. Derived from the LLM
	// provider's finish reason: "stop", "length" (max tokens), "tool-calls",
	// "content-filter", "error", "other", "unknown".
	StopReason string

	// SessionID is the UUID of the session this turn belongs to.
	SessionID string

	// TotalUsage is the aggregate token usage across all steps in the turn
	// (includes tool-calling loop iterations). Nil if the provider didn't
	// report usage.
	TotalUsage *FantasyUsage

	// FinalUsage is the token usage from the last API call only. Use this
	// for context window fill estimation (InputTokens + OutputTokens ≈
	// current context size). Nil if unavailable.
	FinalUsage *FantasyUsage

	// Messages is the full updated conversation after the turn, including
	// any tool call/result messages added during the agent loop.
	Messages []FantasyMessage
}

TurnResult contains the full result of a prompt turn, including usage statistics and the updated conversation. Use PromptResult() instead of Prompt() when you need access to this data.

type TurnStartEvent 

type TurnStartEvent struct {
	Prompt string
}

TurnStartEvent fires before the agent begins processing a prompt.

func (TurnStartEvent) EventType 

func (e TurnStartEvent) EventType() EventType

EventType implements Event.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command
scripting command

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.