Documentation
¶
Overview ¶
Package extensions is the public, extension-facing type surface of Kit.
Kit extensions are plain Go files interpreted at runtime, so they never import this package themselves — they use the "kit/ext" import path that the interpreter provides. This package exists for the Go code AROUND an extension: unit tests, build tooling, and any program that drives the test harness in github.com/mark3labs/kit/pkg/extensions/test.
Every declaration here is an alias for the corresponding Kit-internal type, so values cross the boundary with no conversion:
package main
import (
"testing"
ext "github.com/mark3labs/kit/pkg/extensions"
"github.com/mark3labs/kit/pkg/extensions/test"
)
func TestBlocksDangerousTool(t *testing.T) {
h := test.New(t)
h.LoadFile("my-ext.go")
result, err := h.Emit(ext.ToolCallEvent{
ToolName: "write",
Input: `{"path":"main.go"}`,
})
if err != nil {
t.Fatal(err)
}
test.AssertBlocked(t, result, "not allowed")
}
Index ¶
- Constants
- func NormalizeShortcutKey(key string) string
- func ValidateShortcutKey(key string) (normalized string, warning string, err error)
- type API
- type AgentEndEvent
- type AgentStartEvent
- type ArgumentPattern
- type BeforeAgentStartEvent
- type BeforeAgentStartResult
- type BeforeCompactEvent
- type BeforeCompactResult
- type BeforeForkEvent
- type BeforeForkResult
- type BeforeSessionSwitchEvent
- type BeforeSessionSwitchResult
- type CommandDef
- type CompactConfig
- type CompleteRequest
- type CompleteResponse
- type Context
- type ContextMessage
- type ContextPrepareEvent
- type ContextPrepareResult
- type ContextStats
- type EditorConfig
- type EditorKeyAction
- type EditorKeyActionType
- type ErrorEvent
- type Event
- type EventType
- type ExtensionEntry
- type FilePart
- type HandlerFunc
- type HeaderFooterConfig
- type InputEvent
- type InputResult
- type LLMUsageEvent
- type LoadedExtension
- type MessageEndEvent
- type MessageRendererConfig
- type MessageStartEvent
- type MessageUpdateEvent
- type ModelCapabilities
- type ModelChangeEvent
- type ModelConditional
- type ModelInfoEntry
- type ModelPricing
- type ModelResolutionResult
- type OptionDef
- type OverlayAnchor
- type OverlayConfig
- type OverlayResult
- type OverlayStyle
- type ParseResult
- type PrepareStepEvent
- type PrepareStepResult
- type PrintBlockOpts
- type PromptConfirmConfig
- type PromptConfirmResult
- type PromptInputConfig
- type PromptInputResult
- type PromptMultiSelectConfig
- type PromptMultiSelectResult
- type PromptSelectConfig
- type PromptSelectResult
- type PromptTemplate
- type ReasoningStartEvent
- type Result
- type RetryEvent
- type Runner
- type SessionMessage
- type SessionShutdownEvent
- type SessionStartEvent
- type SessionUsage
- type ShortcutDef
- type Skill
- type SkillLoadResult
- type SourceEvent
- type StatusBarEntry
- type StepFinishEvent
- type StepStartEvent
- type SubagentChunkEvent
- type SubagentConfig
- type SubagentEndEvent
- type SubagentEvent
- type SubagentHandle
- type SubagentResult
- type SubagentStartEvent
- type SubagentUsage
- type TerminalResizeEvent
- type ThemeColor
- type ThemeColorConfig
- type ThemeColors
- type ThinkingLevelChangeEvent
- type ToolCallEvent
- type ToolCallInputDeltaEvent
- type ToolCallInputEndEvent
- type ToolCallInputStartEvent
- type ToolCallResult
- type ToolContext
- type ToolDef
- type ToolExecutionEndEvent
- type ToolExecutionStartEvent
- type ToolInfo
- type ToolOutputEvent
- type ToolRenderConfig
- type ToolResultEvent
- type ToolResultResult
- type TreeNavigationResult
- type TreeNode
- type TurnStateChangeEvent
- type UIVisibility
- type WarningsEvent
- type WidgetConfig
- type WidgetContent
- type WidgetPlacement
- type WidgetStyle
Constants ¶
const AgentEnd = internalext.AgentEnd
AgentEnd fires when the agent finishes responding.
const AgentStart = internalext.AgentStart
AgentStart fires when the agent loop begins processing.
const BeforeAgentStart = internalext.BeforeAgentStart
BeforeAgentStart fires before the agent loop begins for a prompt.
const BeforeCompact = internalext.BeforeCompact
BeforeCompact fires before context compaction runs. Handlers can cancel compaction by returning Cancel=true.
const BeforeFork = internalext.BeforeFork
BeforeFork fires before the session tree is branched to a different entry point. Handlers can cancel the fork by returning Cancel=true.
const BeforeSessionSwitch = internalext.BeforeSessionSwitch
BeforeSessionSwitch fires before the session is switched to a new branch (e.g. /new command). Handlers can cancel by returning Cancel=true.
const ContextPrepare = internalext.ContextPrepare
ContextPrepare fires after context is built from the session tree and before the messages are sent to the LLM. Handlers can filter, reorder, or inject messages into the context window.
const EditorKeyConsumed = internalext.EditorKeyConsumed
EditorKeyConsumed means the extension handled the key. The editor should re-render but not process the key further.
const EditorKeyPassthrough = internalext.EditorKeyPassthrough
EditorKeyPassthrough lets the built-in editor handle the key normally.
const EditorKeyRemap = internalext.EditorKeyRemap
EditorKeyRemap transforms the key into a different key before passing it to the built-in editor. Use RemappedKey to specify the target (e.g., "left", "right", "up", "down", "backspace", "delete", "enter", "tab", "home", "end", or a single character like "a").
const EditorKeySubmit = internalext.EditorKeySubmit
EditorKeySubmit forces immediate text submission. The SubmitText field specifies the text to submit (empty = use editor's current text).
const Error = internalext.Error
Error fires when an agent-level error occurs during streaming.
const Input = internalext.Input
Input fires when user input is received. Handlers can transform or handle it.
const LLMUsage = internalext.LLMUsage
LLMUsage fires after each LLM provider call with the token and cost deltas for that single call. Extensions use it to attribute usage to specific calls/models and to drive budget enforcement between calls.
const MessageEnd = internalext.MessageEnd
MessageEnd fires when the assistant message is complete.
const MessageStart = internalext.MessageStart
MessageStart fires when a new assistant message begins.
const MessageUpdate = internalext.MessageUpdate
MessageUpdate fires for each streaming text chunk.
const ModelChange = internalext.ModelChange
ModelChange fires after the active model is changed via ctx.SetModel().
const OverlayBottomCenter = internalext.OverlayBottomCenter
OverlayBottomCenter positions the dialog near the bottom of the view.
const OverlayCenter = internalext.OverlayCenter
OverlayCenter positions the dialog in the vertical center.
const OverlayTopCenter = internalext.OverlayTopCenter
OverlayTopCenter positions the dialog near the top of the view.
const PrepareStep = internalext.PrepareStep
PrepareStep fires between steps within a multi-step agent turn, after steering messages are injected and before messages are sent to the LLM. Handlers can replace the context window for this step.
const ReasoningStart = internalext.ReasoningStart
ReasoningStart fires when the LLM begins reasoning/thinking.
const Retry = internalext.Retry
Retry fires when the LLM provider request is retried after a transient error.
const SessionShutdown = internalext.SessionShutdown
SessionShutdown fires when the application is closing.
const SessionStart = internalext.SessionStart
SessionStart fires when a session is loaded or created.
const Source = internalext.Source
Source fires when the LLM references a source (e.g. web search).
const StepFinish = internalext.StepFinish
StepFinish fires when a step completes, providing step number, finish reason, and token usage.
const StepStart = internalext.StepStart
StepStart fires when a new LLM call begins within a multi-step agent turn.
const SubagentChunk = internalext.SubagentChunk
SubagentChunk fires for each real-time event emitted by a running subagent: text chunks, tool calls, tool results, etc.
const SubagentEnd = internalext.SubagentEnd
SubagentEnd fires when a subagent tool call completes (success or error). Carries the final response and any error message.
const SubagentStart = internalext.SubagentStart
SubagentStart fires when a subagent tool call begins executing. Carries the tool call ID and the task description.
const TerminalResize = internalext.TerminalResize
TerminalResize fires when the terminal dimensions change, and once at startup with the initial size. Interactive TUI only.
const ThinkingLevelChange = internalext.ThinkingLevelChange
ThinkingLevelChange fires after the extended-thinking effort level is changed, whether by the user, an extension, or an automatic downgrade when switching to a model that does not support the current level.
const ToolCall = internalext.ToolCall
ToolCall fires before a tool executes. Handlers can block execution.
const ToolCallInputDelta = internalext.ToolCallInputDelta
ToolCallInputDelta fires for each streamed fragment of tool call arguments as they arrive from the LLM.
const ToolCallInputEnd = internalext.ToolCallInputEnd
ToolCallInputEnd fires when tool argument streaming is complete, before the tool call is parsed and execution begins.
const ToolCallInputStart = internalext.ToolCallInputStart
ToolCallInputStart fires when the LLM begins generating tool call arguments. The tool name is known but the full argument JSON is still being streamed.
const ToolExecutionEnd = internalext.ToolExecutionEnd
ToolExecutionEnd fires when a tool finishes executing.
const ToolExecutionStart = internalext.ToolExecutionStart
ToolExecutionStart fires when a tool begins executing.
const ToolOutput = internalext.ToolOutput
ToolOutput fires when a tool produces streaming output chunks.
const ToolResult = internalext.ToolResult
ToolResult fires after a tool executes. Handlers can modify the result.
const TurnStateChange = internalext.TurnStateChange
TurnStateChange fires when the UI moves between its idle and working states. Unlike AgentStart/AgentEnd this also covers work that never reaches the agent loop, such as shell commands. Interactive TUI only.
const Warnings = internalext.Warnings
Warnings fires when the LLM provider returns warnings.
const WidgetAbove = internalext.WidgetAbove
WidgetAbove places the widget above the input area, between the separator and queued messages.
const WidgetBelow = internalext.WidgetBelow
WidgetBelow places the widget below the input area, between the input and the status bar.
Variables ¶
This section is empty.
Functions ¶
func NormalizeShortcutKey ¶
NormalizeShortcutKey converts a shortcut binding into the canonical spelling Kit matches against. Modifier aliases are folded, modifiers are reordered into canonical order, duplicates are dropped, and known key names are normalized. Bindings containing an unrecognized modifier are returned trimmed but otherwise untouched, so an unusual-but-valid terminal key name still has a chance to match.
func ValidateShortcutKey ¶
ValidateShortcutKey normalizes a binding and reports whether Kit can deliver it. A non-nil error means the shortcut must be rejected: the handler could never fire. A non-empty warning means the shortcut will fire but shadows built-in behaviour.
Types ¶
type API ¶
type API = internalext.API
API is passed to each extension's Init function. Extensions use it to register typed event handlers, custom tools, and slash commands.
type AgentEndEvent ¶
type AgentEndEvent = internalext.AgentEndEvent
AgentEndEvent fires when the agent finishes responding. In addition to the final response and stop reason, the event carries per-turn aggregates so observer-style extensions don't have to maintain parallel bookkeeping in OnToolResult / OnStepFinish handlers.
type AgentStartEvent ¶
type AgentStartEvent = internalext.AgentStartEvent
AgentStartEvent fires when the agent loop begins.
type ArgumentPattern ¶
type ArgumentPattern = internalext.ArgumentPattern
ArgumentPattern defines how to parse command arguments.
type BeforeAgentStartEvent ¶
type BeforeAgentStartEvent = internalext.BeforeAgentStartEvent
BeforeAgentStartEvent fires before the agent loop begins.
type BeforeAgentStartResult ¶
type BeforeAgentStartResult = internalext.BeforeAgentStartResult
BeforeAgentStartResult can inject context before the agent runs.
type BeforeCompactEvent ¶
type BeforeCompactEvent = internalext.BeforeCompactEvent
BeforeCompactEvent fires before context compaction runs. Provides information about the current context state to help extensions decide whether to allow or block compaction.
type BeforeCompactResult ¶
type BeforeCompactResult = internalext.BeforeCompactResult
BeforeCompactResult controls whether compaction proceeds. Return Cancel=true with an optional Reason to block compaction, or provide a custom Summary to replace the default LLM-generated one.
type BeforeForkEvent ¶
type BeforeForkEvent = internalext.BeforeForkEvent
BeforeForkEvent fires before the session tree is branched to a different entry point (via the tree selector or /fork command).
type BeforeForkResult ¶
type BeforeForkResult = internalext.BeforeForkResult
BeforeForkResult controls whether the fork proceeds. Return Cancel=true with an optional Reason to block the fork.
type BeforeSessionSwitchEvent ¶
type BeforeSessionSwitchEvent = internalext.BeforeSessionSwitchEvent
BeforeSessionSwitchEvent fires before the session is switched to a new branch (e.g. /new or /clear commands).
type BeforeSessionSwitchResult ¶
type BeforeSessionSwitchResult = internalext.BeforeSessionSwitchResult
BeforeSessionSwitchResult controls whether the session switch proceeds. Return Cancel=true with an optional Reason to block the switch.
type CommandDef ¶
type CommandDef = internalext.CommandDef
CommandDef describes a slash command registered by an extension.
type CompactConfig ¶
type CompactConfig = internalext.CompactConfig
CompactConfig configures a programmatic context compaction request.
type CompleteRequest ¶
type CompleteRequest = internalext.CompleteRequest
CompleteRequest configures a standalone LLM completion call. Extensions use this with ctx.Complete() to make direct LLM calls without the agent tool loop.
type CompleteResponse ¶
type CompleteResponse = internalext.CompleteResponse
CompleteResponse contains the LLM response and usage metadata from a standalone completion call.
type Context ¶
type Context = internalext.Context
Context provides runtime information to handlers about the current session.
type ContextMessage ¶
type ContextMessage = internalext.ContextMessage
ContextMessage represents a single message in the LLM context window. Used by OnContextPrepare to let extensions inspect and modify the messages that will be sent to the LLM.
type ContextPrepareEvent ¶
type ContextPrepareEvent = internalext.ContextPrepareEvent
ContextPrepareEvent fires after the context window is built from the session tree and before the messages are sent to the LLM. Handlers can inspect the messages and return a modified set to filter, reorder, or inject context.
type ContextPrepareResult ¶
type ContextPrepareResult = internalext.ContextPrepareResult
ContextPrepareResult allows extensions to replace the context window. Return nil to leave the context unchanged.
type ContextStats ¶
type ContextStats = internalext.ContextStats
ContextStats contains current context-window usage information. Extensions can poll this via ctx.GetContextStats() to build usage meters, auto-compaction triggers, etc.
type EditorConfig ¶
type EditorConfig = internalext.EditorConfig
EditorConfig defines an editor interceptor/decorator that wraps the built-in input editor. Extensions can intercept key events (remap, consume, or force submit) and/or modify the rendered output (add mode indicators, apply visual effects).
Uses concrete function fields instead of interfaces for Yaegi safety.
IMPORTANT (Yaegi limitation — forward references lose their bodies): If you reference a function BY NAME from inside a function literal, and that function is declared LATER in the file, Yaegi builds the wrapper before the function is compiled. The field then holds a callable that does nothing and returns zero values — no panic, no error. This affects every Kit API taking a function, and also direct arguments such as api.OnToolCall(fn) and api.RegisterShortcut(def, fn).
// BROKEN — myHandler is declared below this closure:
api.OnAgentStart(func(e ext.AgentStartEvent, ctx ext.Context) {
ctx.SetEditor(ext.EditorConfig{HandleKey: myHandler})
})
func myHandler(k, t string) ext.EditorKeyAction { ... }
Any one of these fixes it:
- Declare helpers ABOVE the code that references them (simplest).
- Wrap in an anonymous closure: HandleKey: func(k string, t string) ext.EditorKeyAction { return myHandler(k, t) }
- Assign to a local first: f := myHandler; ...{HandleKey: f}
Verified against yaegi v0.12.0-v0.16.1; not fixed upstream.
type EditorKeyAction ¶
type EditorKeyAction = internalext.EditorKeyAction
EditorKeyAction is returned by an editor interceptor's HandleKey function to indicate how a key press should be handled.
type EditorKeyActionType ¶
type EditorKeyActionType = internalext.EditorKeyActionType
EditorKeyActionType defines the outcome of an editor key interception.
type ErrorEvent ¶
type ErrorEvent = internalext.ErrorEvent
ErrorEvent fires when an agent-level error occurs during streaming. Uses string instead of error because Yaegi cannot handle the error interface reliably across the interpreter boundary.
type Event ¶
type Event = internalext.Event
Event is the interface satisfied by all event types internally.
type EventType ¶
type EventType = internalext.EventType
EventType identifies a point in KIT's lifecycle where extensions can hook in.
func AllEventTypes ¶
func AllEventTypes() []EventType
AllEventTypes returns every supported event type.
type ExtensionEntry ¶
type ExtensionEntry = internalext.ExtensionEntry
ExtensionEntry represents persisted extension data stored in the session. Extensions use AppendEntry to save custom state and GetEntries to retrieve it on session resume.
type FilePart ¶
type FilePart = internalext.FilePart
FilePart describes a file attachment for multimodal messages. Extensions use this with SendMultimodalMessage to attach images or documents.
type HandlerFunc ¶
type HandlerFunc = internalext.HandlerFunc
HandlerFunc is the internal handler signature used by the runner.
type HeaderFooterConfig ¶
type HeaderFooterConfig = internalext.HeaderFooterConfig
HeaderFooterConfig describes a custom header or footer region that replaces or augments the default TUI chrome. Extensions use ctx.SetHeader/SetFooter to place one; only one header and one footer can be active at a time (the latest call wins). Reuses WidgetContent and WidgetStyle for consistency.
type InputEvent ¶
type InputEvent = internalext.InputEvent
InputEvent fires when user input is received.
type InputResult ¶
type InputResult = internalext.InputResult
InputResult controls what happens with user input.
Action: "continue" (default), "transform", "handled"
type LLMUsageEvent ¶
type LLMUsageEvent = internalext.LLMUsageEvent
LLMUsageEvent fires after each LLM provider call with the per-call token and cost deltas. Use this for accurate budget tracking, cost dashboards, and any logic that needs to react between LLM calls within a single agent turn (rather than only at turn boundaries).
A single agent turn typically produces multiple LLMUsageEvents (one per tool-loop iteration). The Model and Provider fields reflect the model used for that specific call, which may differ from earlier calls if the extension switched models mid-turn via ctx.SetModel().
type LoadedExtension ¶
type LoadedExtension = internalext.LoadedExtension
LoadedExtension represents a single extension that has been discovered, loaded, and initialised. It holds the registered handlers and any custom tools, commands, or tool renderers the extension provided.
type MessageEndEvent ¶
type MessageEndEvent = internalext.MessageEndEvent
MessageEndEvent fires when the assistant message is complete.
type MessageRendererConfig ¶
type MessageRendererConfig = internalext.MessageRendererConfig
MessageRendererConfig provides a named rendering function that extensions can invoke via ctx.RenderMessage(name, content). Unlike tool renderers (which hook into the automatic tool result display), message renderers are invoked explicitly by extension code for branded status updates, progress reports, or any custom visual output.
Example:
api.RegisterMessageRenderer(ext.MessageRendererConfig{
Name: "build-status",
Render: func(content string, width int) string {
border := strings.Repeat("─", width-4)
return "╭" + border + "╮\n│ " + content + "\n╰" + border + "╯"
},
})
type MessageStartEvent ¶
type MessageStartEvent = internalext.MessageStartEvent
MessageStartEvent fires when a new assistant message begins.
type MessageUpdateEvent ¶
type MessageUpdateEvent = internalext.MessageUpdateEvent
MessageUpdateEvent fires for each streaming text chunk.
type ModelCapabilities ¶
type ModelCapabilities = internalext.ModelCapabilities
ModelCapabilities describes what a model supports.
type ModelChangeEvent ¶
type ModelChangeEvent = internalext.ModelChangeEvent
ModelChangeEvent fires after the active model is changed via ctx.SetModel().
type ModelConditional ¶
type ModelConditional = internalext.ModelConditional
ModelConditional represents an <if-model> block for evaluation.
type ModelInfoEntry ¶
type ModelInfoEntry = internalext.ModelInfoEntry
ModelInfoEntry represents a known model from the registry. Used by GetAvailableModels to let extensions discover which models are available.
type ModelPricing ¶
type ModelPricing = internalext.ModelPricing
ModelPricing describes a model's token costs, expressed in US dollars per one million tokens (the unit used by the models.dev registry). Extensions use it to compute costs or savings that Kit does not report directly — for example the value of prompt-cache reads:
caps, _ := ctx.GetModelCapabilities("")
usage := ctx.GetSessionUsage()
if caps.Pricing.Known && caps.Pricing.HasCacheRead {
saved := float64(usage.TotalCacheReadTokens) *
(caps.Pricing.Input - caps.Pricing.CacheRead) / 1_000_000
}
Costs for a raw token count are therefore tokens * rate / 1_000_000.
type ModelResolutionResult ¶
type ModelResolutionResult = internalext.ModelResolutionResult
ModelResolutionResult reports model chain resolution outcome.
type OptionDef ¶
type OptionDef = internalext.OptionDef
OptionDef describes a configuration option that an extension can register. Options are resolved from env vars, config file, or default value.
type OverlayAnchor ¶
type OverlayAnchor = internalext.OverlayAnchor
OverlayAnchor determines the vertical position of an overlay dialog within the TUI view.
type OverlayConfig ¶
type OverlayConfig = internalext.OverlayConfig
OverlayConfig fully describes a modal overlay dialog. Extensions call ctx.ShowOverlay(config) to display the dialog and block until the user dismisses it or selects an action. The dialog renders as a bordered box positioned within the TUI, with optional scrollable content and action buttons.
Example:
result := ctx.ShowOverlay(ext.OverlayConfig{
Title: "Build Results",
Content: ext.WidgetContent{Text: "All 42 tests passed."},
Style: ext.OverlayStyle{BorderColor: "#a6e3a1"},
Width: 60,
Actions: []string{"Continue", "Show Details"},
})
type OverlayResult ¶
type OverlayResult = internalext.OverlayResult
OverlayResult is the response from a ShowOverlay call.
type OverlayStyle ¶
type OverlayStyle = internalext.OverlayStyle
OverlayStyle configures the visual appearance of an overlay dialog.
type ParseResult ¶
type ParseResult = internalext.ParseResult
ParseResult reports argument parsing outcome.
type PrepareStepEvent ¶
type PrepareStepEvent = internalext.PrepareStepEvent
PrepareStepEvent fires between steps within a multi-step agent turn, after steering messages are injected and before messages are sent to the LLM. Handlers can inspect and replace the context window.
type PrepareStepResult ¶
type PrepareStepResult = internalext.PrepareStepResult
PrepareStepResult allows extensions to replace the context window between steps. Return nil Messages to leave the context unchanged.
type PrintBlockOpts ¶
type PrintBlockOpts = internalext.PrintBlockOpts
PrintBlockOpts configures a custom styled block for PrintBlock.
type PromptConfirmConfig ¶
type PromptConfirmConfig = internalext.PromptConfirmConfig
PromptConfirmConfig configures a yes/no confirmation prompt.
type PromptConfirmResult ¶
type PromptConfirmResult = internalext.PromptConfirmResult
PromptConfirmResult is the response from a confirmation prompt.
type PromptInputConfig ¶
type PromptInputConfig = internalext.PromptInputConfig
PromptInputConfig configures a free-form text input prompt.
type PromptInputResult ¶
type PromptInputResult = internalext.PromptInputResult
PromptInputResult is the response from a text input prompt.
type PromptMultiSelectConfig ¶
type PromptMultiSelectConfig = internalext.PromptMultiSelectConfig
PromptMultiSelectConfig configures a multi-selection prompt that allows the user to toggle multiple options and confirm their selection.
type PromptMultiSelectResult ¶
type PromptMultiSelectResult = internalext.PromptMultiSelectResult
PromptMultiSelectResult is the response from a multi-selection prompt.
type PromptSelectConfig ¶
type PromptSelectConfig = internalext.PromptSelectConfig
PromptSelectConfig configures a selection prompt that presents the user with a list of options to choose from.
type PromptSelectResult ¶
type PromptSelectResult = internalext.PromptSelectResult
PromptSelectResult is the response from a selection prompt.
type PromptTemplate ¶
type PromptTemplate = internalext.PromptTemplate
PromptTemplate represents a parsed template with variable placeholders.
type ReasoningStartEvent ¶
type ReasoningStartEvent = internalext.ReasoningStartEvent
ReasoningStartEvent fires when the LLM begins reasoning/thinking.
type Result ¶
type Result = internalext.Result
Result is the interface satisfied by all result types internally.
type RetryEvent ¶
type RetryEvent = internalext.RetryEvent
RetryEvent fires when the LLM provider request is retried after a transient error.
type Runner ¶
type Runner = internalext.Runner
Runner manages loaded extensions and dispatches events to their handlers sequentially. Handlers execute in extension load order; for cancellable events the first blocking result wins.
Each extension has a dedicated reentrant mutex so that handlers for the same extension are serialized (preventing data races on shared package-level state), while handlers for different extensions may execute concurrently.
type SessionMessage ¶
type SessionMessage = internalext.SessionMessage
SessionMessage represents a conversation message exposed to extensions. This is a simplified, read-only view of the internal message structures.
type SessionShutdownEvent ¶
type SessionShutdownEvent = internalext.SessionShutdownEvent
SessionShutdownEvent fires when the application is closing.
type SessionStartEvent ¶
type SessionStartEvent = internalext.SessionStartEvent
SessionStartEvent fires when a session is loaded or created.
type SessionUsage ¶
type SessionUsage = internalext.SessionUsage
SessionUsage contains aggregated token usage and cost statistics for the current session. Extensions use this with GetSessionUsage() to report usage information.
type ShortcutDef ¶
type ShortcutDef = internalext.ShortcutDef
ShortcutDef describes a global keyboard shortcut registered by an extension. Shortcuts fire across all app states except modal prompts/overlays. Use modifier combinations (e.g., "ctrl+p", "alt+t", "f1") — avoid bare characters like "a" or "x" which conflict with text input.
type Skill ¶
type Skill = internalext.Skill
Skill represents a loaded skill file with parsed YAML frontmatter.
type SkillLoadResult ¶
type SkillLoadResult = internalext.SkillLoadResult
SkillLoadResult reports skills loaded from a directory.
type SourceEvent ¶
type SourceEvent = internalext.SourceEvent
SourceEvent fires when the LLM references a source (e.g. from web search).
type StatusBarEntry ¶
type StatusBarEntry = internalext.StatusBarEntry
StatusBarEntry represents a keyed entry in the TUI status bar. Extensions can set multiple independent entries that render alongside the built-in model name and token usage display.
type StepFinishEvent ¶
type StepFinishEvent = internalext.StepFinishEvent
StepFinishEvent fires when a step completes, providing step metadata and token usage. Usage fields are plain int64 (not LLMUsage) because Yaegi cannot handle fantasy types across the interpreter boundary.
type StepStartEvent ¶
type StepStartEvent = internalext.StepStartEvent
StepStartEvent fires when a new LLM call begins within a multi-step agent turn.
type SubagentChunkEvent ¶
type SubagentChunkEvent = internalext.SubagentChunkEvent
SubagentChunkEvent fires for each real-time event from a running subagent. Type field indicates the kind of event; read the relevant fields accordingly.
type SubagentConfig ¶
type SubagentConfig = internalext.SubagentConfig
--------------------------------------------------------------------------- Subagent types --------------------------------------------------------------------------- SubagentConfig configures a subagent spawn.
type SubagentEndEvent ¶
type SubagentEndEvent = internalext.SubagentEndEvent
SubagentEndEvent fires when a subagent tool call completes.
type SubagentEvent ¶
type SubagentEvent = internalext.SubagentEvent
SubagentEvent carries a real-time event from a running subagent. Extensions use the Type field to determine what happened and read the relevant fields. This is a concrete struct (not an interface) for Yaegi compatibility.
type SubagentHandle ¶
type SubagentHandle = internalext.SubagentHandle
SubagentHandle provides control over a background (non-blocking) subagent. The subagent runs in-process in a goroutine; the handle exposes cancellation and completion signalling.
type SubagentResult ¶
type SubagentResult = internalext.SubagentResult
SubagentResult contains the outcome of a subagent execution.
type SubagentStartEvent ¶
type SubagentStartEvent = internalext.SubagentStartEvent
SubagentStartEvent fires when a subagent tool call begins executing.
type SubagentUsage ¶
type SubagentUsage = internalext.SubagentUsage
SubagentUsage contains token usage from the subagent's run.
type TerminalResizeEvent ¶
type TerminalResizeEvent = internalext.TerminalResizeEvent
TerminalResizeEvent fires when the terminal is resized, and once at startup with the initial dimensions so a handler can lay out without waiting for the user to resize. Interactive TUI only.
The same values are available through Context.GetTerminalSize(); this event exists so extensions can re-render chrome immediately instead of polling.
type ThemeColor ¶
type ThemeColor = internalext.ThemeColor
ThemeColor is an adaptive color pair with light and dark hex values. Either field may be empty to inherit from the default theme.
type ThemeColorConfig ¶
type ThemeColorConfig = internalext.ThemeColorConfig
ThemeColorConfig defines a complete color theme that extensions can register programmatically via ctx.RegisterTheme(). Uses plain hex strings (not color.Color) so the type is safe to pass across the Yaegi boundary.
type ThemeColors ¶
type ThemeColors = internalext.ThemeColors
ThemeColors holds the active theme's colors as "#rrggbb" hex strings, with the light/dark variants already resolved for the terminal's appearance. Returned by ctx.GetTheme().
It is the read counterpart to ThemeColorConfig: that type describes a theme being registered (light and dark for each slot), this one reports the colors actually in effect right now.
type ThinkingLevelChangeEvent ¶
type ThinkingLevelChangeEvent = internalext.ThinkingLevelChangeEvent
ThinkingLevelChangeEvent fires after the extended-thinking effort level changes. Handlers that display the level should re-read it here rather than caching a value from session start.
type ToolCallEvent ¶
type ToolCallEvent = internalext.ToolCallEvent
ToolCallEvent fires before a tool executes.
type ToolCallInputDeltaEvent ¶
type ToolCallInputDeltaEvent = internalext.ToolCallInputDeltaEvent
ToolCallInputDeltaEvent fires for each streamed fragment of tool call arguments as they arrive from the LLM.
type ToolCallInputEndEvent ¶
type ToolCallInputEndEvent = internalext.ToolCallInputEndEvent
ToolCallInputEndEvent fires when tool argument streaming is complete, before the tool call is parsed and execution begins.
type ToolCallInputStartEvent ¶
type ToolCallInputStartEvent = internalext.ToolCallInputStartEvent
ToolCallInputStartEvent fires when the LLM begins generating tool call arguments. The tool name is known but the full argument JSON is still being streamed.
type ToolCallResult ¶
type ToolCallResult = internalext.ToolCallResult
ToolCallResult controls whether the tool call proceeds.
type ToolContext ¶
type ToolContext = internalext.ToolContext
ToolContext provides runtime context to a tool's ExecuteWithContext handler. It allows tools to check for cancellation and report progress while running.
type ToolDef ¶
type ToolDef = internalext.ToolDef
ToolDef describes a custom tool registered by an extension.
type ToolExecutionEndEvent ¶
type ToolExecutionEndEvent = internalext.ToolExecutionEndEvent
ToolExecutionEndEvent fires when a tool finishes executing.
type ToolExecutionStartEvent ¶
type ToolExecutionStartEvent = internalext.ToolExecutionStartEvent
ToolExecutionStartEvent fires when a tool begins executing.
type ToolInfo ¶
type ToolInfo = internalext.ToolInfo
ToolInfo provides read-only information about a tool available to the agent. Used by GetAllTools to let extensions inspect and filter the tool set.
type ToolOutputEvent ¶
type ToolOutputEvent = internalext.ToolOutputEvent
ToolOutputEvent fires when a tool produces streaming output chunks. This is primarily used for long-running tools like the shell tool to show output in real-time as it arrives, before the tool completes.
type ToolRenderConfig ¶
type ToolRenderConfig = internalext.ToolRenderConfig
ToolRenderConfig provides custom rendering functions for a tool's display in the TUI. Extensions register tool renderers via API.RegisterToolRenderer() during Init. Both render functions are optional — if nil or if they return an empty string, the builtin renderer (or default) is used as a fallback.
Example:
api.RegisterToolRenderer(ext.ToolRenderConfig{
ToolName: "my-tool",
RenderHeader: func(toolArgs string, width int) string {
// Parse args and return a compact summary for the header
return "my-tool: doing something"
},
RenderBody: func(toolResult string, isError bool, width int) string {
// Return custom formatted result body
if isError {
return "ERROR: " + toolResult
}
return "Result: " + toolResult
},
})
type ToolResultEvent ¶
type ToolResultEvent = internalext.ToolResultEvent
ToolResultEvent fires after tool execution with the output.
type ToolResultResult ¶
type ToolResultResult = internalext.ToolResultResult
ToolResultResult can modify the tool's output before it reaches the LLM.
type TreeNavigationResult ¶
type TreeNavigationResult = internalext.TreeNavigationResult
TreeNavigationResult reports success or failure of tree operations.
type TreeNode ¶
type TreeNode = internalext.TreeNode
TreeNode represents a node in the session tree for navigation. Extensions use this to traverse conversation history and implement features like "fresh context" loops and branch summarization.
type TurnStateChangeEvent ¶
type TurnStateChangeEvent = internalext.TurnStateChangeEvent
TurnStateChangeEvent fires when the UI enters or leaves its working state.
This is a superset of AgentStart/AgentEnd: it also covers work that never reaches the agent loop (shell commands run with "!"), and it fires on every path back to idle, including cancellation and error. Use it for UI that must track whether Kit is busy — a spinner or a turn timer — and use AgentStart/AgentEnd when you specifically care about agent turns and their token usage.
Interactive TUI only.
type UIVisibility ¶
type UIVisibility = internalext.UIVisibility
UIVisibility controls which built-in TUI chrome elements are visible. The zero value shows everything (backward compatible). Extensions call ctx.SetUIVisibility to customise the layout — for example, a "minimal" theme can hide the startup banner, status bar, and input hint and replace them with a single custom footer.
type WarningsEvent ¶
type WarningsEvent = internalext.WarningsEvent
WarningsEvent fires when the LLM provider returns warnings about the request.
type WidgetConfig ¶
type WidgetConfig = internalext.WidgetConfig
WidgetConfig fully describes a widget for placement in the TUI. Extensions identify widgets by ID; calling SetWidget with the same ID replaces the previous widget. IDs should be descriptive to avoid collisions across extensions (e.g. "myext:token-counter").
type WidgetContent ¶
type WidgetContent = internalext.WidgetContent
WidgetContent describes what to render in a widget slot.
Content is resolved in priority order: Render (if non-nil), then Text. Render gives the extension the terminal width and takes whatever string it returns verbatim, so it can emit arbitrary ANSI, box drawing, sparklines, or per-frame animation. Text is the simple declarative form.
type WidgetPlacement ¶
type WidgetPlacement = internalext.WidgetPlacement
WidgetPlacement determines where a widget appears in the TUI layout relative to the input area.
type WidgetStyle ¶
type WidgetStyle = internalext.WidgetStyle
WidgetStyle configures the visual appearance of a widget.