extensions

package
v0.5.11-beta Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Overview

Package extensions implements Kodelet's long-running extension runtime.

Index

Constants

View Source 
const (
	// CommandActionPass means the command declined handling and routing should continue.
	CommandActionPass = "pass"
	// CommandActionRespond means the command handled the prompt with a direct UI response.
	CommandActionRespond = "respond"
	// CommandActionRunAgent means the command produced a replacement prompt for the agent.
	CommandActionRunAgent = "runAgent"
)
View Source 
const (
	// EventSessionStart is dispatched when the extension runtime starts.
	EventSessionStart = "session.start"
	// EventResourcesDiscover is dispatched before extension resources are finalized.
	EventResourcesDiscover = "resources.discover"
	// EventUserMessage is dispatched after a user prompt is received and before it is added to the conversation.
	EventUserMessage = "user.message"
	// EventAgentInit is dispatched after a system prompt is built and before a model request.
	EventAgentInit = "agent.init"
	// EventAgentStart is dispatched when an agent loop starts.
	EventAgentStart = "agent.start"
	// EventTurnStart is dispatched before each model turn.
	EventTurnStart = "turn.start"
	// EventToolCall is dispatched before a tool executes.
	EventToolCall = "tool.call"
	// EventToolUpdate is dispatched for transient tool result snapshots while a tool runs.
	EventToolUpdate = "tool.update"
	// EventToolResult is dispatched after a tool executes and before it is rendered/stored.
	EventToolResult = "tool.result"
	// EventTurnEnd is dispatched after one assistant turn completes.
	EventTurnEnd = "turn.end"
	// EventAgentEnd is dispatched when an agent loop has completed.
	EventAgentEnd = "agent.end"
	// EventSessionEnd is dispatched when the extension runtime shuts down.
	EventSessionEnd = "session.end"
)
View Source 
const (
	UIWidgetPlacementAboveComposer = "aboveComposer"
	UIWidgetPlacementBelowComposer = "belowComposer"

	UISurfaceAnchorTopLeft     = "topLeft"
	UISurfaceAnchorTop         = "top"
	UISurfaceAnchorTopRight    = "topRight"
	UISurfaceAnchorLeft        = "left"
	UISurfaceAnchorCenter      = "center"
	UISurfaceAnchorRight       = "right"
	UISurfaceAnchorBottomLeft  = "bottomLeft"
	UISurfaceAnchorBottom      = "bottom"
	UISurfaceAnchorBottomRight = "bottomRight"

	UISurfaceInputKey   = "key"
	UISurfaceInputMouse = "mouse"
	UISurfaceInputFocus = "focus"
	UISurfaceInputBlur  = "blur"

	UIWidgetSetMethod        = "kodelet.ui.widget.set"
	UIWidgetFrameMethod      = "kodelet.ui.widget.frame"
	UIWidgetRemoveMethod     = "kodelet.ui.widget.remove"
	UITranscriptAppendMethod = "kodelet.ui.transcript.append"
	UISurfaceOpenMethod      = "kodelet.ui.surface.open"
	UISurfaceFrameMethod     = "kodelet.ui.surface.frame"
	UISurfaceCloseMethod     = "kodelet.ui.surface.close"
	UISurfaceInputMethod     = "extension.ui.surface.input"
	UISurfaceResizeMethod    = "extension.ui.surface.resize"
)
View Source 
const (
	UIInputStatusSubmitted   = "submitted"
	UIInputStatusDismissed   = "dismissed"
	UIInputStatusTimeout     = "timeout"
	UIInputStatusUnavailable = "unavailable"
)

Variables

This section is empty.

Functions

func ContextWithDiagnosticSink 

func ContextWithDiagnosticSink(ctx context.Context, sink DiagnosticSink) context.Context

ContextWithDiagnosticSink attaches a diagnostic sink to an extension runtime context.

func ContextWithExtensionUIHost 

func ContextWithExtensionUIHost(ctx context.Context, host ExtensionUIHost) context.Context

ContextWithExtensionUIHost attaches persistent widget/surface support to an extension runtime initialization context.

func ContextWithUIInputBroker 

func ContextWithUIInputBroker(ctx context.Context, broker UIInputBroker) context.Context

ContextWithUIInputBroker attaches a UI input broker to the active run context.

func NewUIInputRequestID 

func NewUIInputRequestID() string

NewUIInputRequestID returns a unique request ID for UI input prompts.

func NormalizeSurfaceAnchor 

func NormalizeSurfaceAnchor(anchor string) (string, error)

NormalizeSurfaceAnchor applies the default overlay anchor.

func NormalizeWidgetPlacement 

func NormalizeWidgetPlacement(placement string) (string, error)

NormalizeWidgetPlacement applies the default passive-widget placement.

func NotifyUISurfaceEvent 

func NotifyUISurfaceEvent(ctx context.Context, source UIExtensionSource, lifecycle uint64, method string, params any) error

NotifyUISurfaceEvent delivers an event within a specific surface lifecycle. Sources without lifecycle-aware routing retain the base UIExtensionSource behavior.

func PrepareUISurfaceEventLifecycle 

func PrepareUISurfaceEventLifecycle(source UIExtensionSource, id string, lifecycle uint64)

PrepareUISurfaceEventLifecycle resets ordered event delivery after a surface lifecycle request has been accepted and before the host publishes its UI changes.

func SlashCommands 

func SlashCommands(commands []Command) []slashcommands.Command

SlashCommands converts extension command registrations to slash commands.

func ValidateUIObjectID 

func ValidateUIObjectID(id string) error

ValidateUIObjectID validates an extension-scoped widget or surface ID.

func ValidateUISequence 

func ValidateUISequence(sequence uint64) error

ValidateUISequence validates a monotonically increasing presentation sequence.

Types

type AgentInitDecision 

type AgentInitDecision struct {
	SystemPrompt  string
	AllowedTools  []string
	ToolsModified bool
}

AgentInitDecision is the result of dispatching agent.init handlers.

type Command 

type Command struct {
	ExtensionID  string
	Process      *Process
	Registration CommandRegistration
}

Command is an extension command registration bound to its process.

type CommandInvocation 

type CommandInvocation struct {
	Raw         string         `json:"raw"`
	CommandName string         `json:"commandName"`
	Args        []string       `json:"args"`
	Flags       map[string]any `json:"flags"`
}

CommandInvocation describes the user prompt that invoked an extension command.

type CommandRegistration 

type CommandRegistration struct {
	Name         string         `json:"name"`
	Aliases      []string       `json:"aliases,omitempty"`
	Description  string         `json:"description"`
	InputSchema  map[string]any `json:"inputSchema,omitempty"`
	Kind         string         `json:"kind,omitempty"`
	TimeoutInSec *float64       `json:"timeoutInSec,omitempty"`
}

CommandRegistration is returned by an extension during initialization.

type CommandResult 

type CommandResult struct {
	Action     string `json:"action"`
	Response   string `json:"response,omitempty"`
	Prompt     string `json:"prompt,omitempty"`
	RecipeName string `json:"recipeName,omitempty"`
}

CommandResult is returned by extension.command.execute.

type Config 

type Config struct {
	Enabled       bool                  `mapstructure:"enabled" json:"enabled" yaml:"enabled"`
	GlobalDir     string                `mapstructure:"global_dir" json:"global_dir" yaml:"global_dir"`
	LocalDir      string                `mapstructure:"local_dir" json:"local_dir" yaml:"local_dir"`
	MaxOutputSize int                   `mapstructure:"max_output_size" json:"max_output_size" yaml:"max_output_size"`
	Allow         []string              `mapstructure:"allow" json:"allow" yaml:"allow"`
	Deny          []string              `mapstructure:"deny" json:"deny" yaml:"deny"`
	Tools         map[string]ToolConfig `mapstructure:"tools" json:"tools" yaml:"tools"`
}

Config contains extension runtime configuration.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns the default extension runtime configuration.

func LoadConfigFromViper 

func LoadConfigFromViper() Config

LoadConfigFromViper loads extension configuration from viper.

type Diagnostic 

type Diagnostic struct {
	Level     DiagnosticLevel
	Extension string
	Message   string
	Fields    map[string]any
}

Diagnostic is a structured warning or error emitted by an extension.

type DiagnosticLevel 

type DiagnosticLevel string

DiagnosticLevel is the severity of an extension diagnostic that may be surfaced by an interactive host. 

const (
	DiagnosticLevelWarning DiagnosticLevel = "warning"
	DiagnosticLevelError   DiagnosticLevel = "error"
)

type DiagnosticSink 

type DiagnosticSink interface {
	ReportDiagnostic(ctx context.Context, diagnostic Diagnostic)
}

DiagnosticSink receives structured extension diagnostics. Implementations should return promptly so extension stderr processing cannot be blocked by UI rendering.

func DiagnosticSinkFromContext 

func DiagnosticSinkFromContext(ctx context.Context) (DiagnosticSink, bool)

DiagnosticSinkFromContext returns the run-scoped diagnostic sink, if one is available.

type Discovery 

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

Discovery handles extension discovery.

func NewDiscovery 

func NewDiscovery(opts ...DiscoveryOption) (*Discovery, error)

NewDiscovery creates an extension discovery instance.

func (*Discovery) Discover 

func (d *Discovery) Discover() ([]Extension, error)

Discover finds extension executables in configured roots.

type DiscoveryOption 

type DiscoveryOption func(*Discovery) error

DiscoveryOption configures extension discovery.

func WithConfig 

func WithConfig(config Config) DiscoveryOption

WithConfig sets discovery config.

func WithRoots 

func WithRoots(roots ...Root) DiscoveryOption

WithRoots replaces discovery roots. Intended for tests.

func WithWorkingDir 

func WithWorkingDir(workingDir string) DiscoveryOption

WithWorkingDir sets the working directory for relative path normalization.

type EventBlock 

type EventBlock struct {
	Reason string `json:"reason"`
}

EventBlock asks Kodelet to block a mutable/blocking event.

type EventResult 

type EventResult struct {
	Input            json.RawMessage    `json:"input,omitempty"`
	Block            *EventBlock        `json:"block,omitempty"`
	Output           json.RawMessage    `json:"output,omitempty"`
	Message          *string            `json:"message,omitempty"`
	SystemPrompt     *SystemPromptPatch `json:"systemPrompt,omitempty"`
	Tools            *ToolListPatch     `json:"tools,omitempty"`
	FollowUpMessages []string           `json:"followUpMessages,omitempty"`
}

EventResult is returned by extension.event.handle.

type Extension 

type Extension struct {
	ID           string
	Name         string
	ExecPath     string
	Dir          string
	RootDir      string
	Kind         SourceKind
	PluginPrefix string
	PluginRef    string
}

Extension describes a discovered extension executable.

type ExtensionCallContext 

type ExtensionCallContext struct {
	SessionID      string `json:"sessionId,omitempty"`
	ConversationID string `json:"conversationId,omitempty"`
	CWD            string `json:"cwd,omitempty"`
	Provider       string `json:"provider,omitempty"`
	Model          string `json:"model,omitempty"`
	Profile        string `json:"profile,omitempty"`
	RecipeName     string `json:"recipeName,omitempty"`
	InvokedBy      string `json:"invokedBy,omitempty"`
}

ExtensionCallContext is passed to extension tool/event/command calls.

type ExtensionUIHost 

type ExtensionUIHost interface {
	SetWidget(ctx context.Context, source UIExtensionSource, request UIWidgetSetRequest) (UIFrameResponse, error)
	UpdateWidget(ctx context.Context, source UIExtensionSource, request UIWidgetFrameRequest) (UIFrameResponse, error)
	RemoveWidget(ctx context.Context, source UIExtensionSource, request UIWidgetRemoveRequest) (UIFrameResponse, error)
	OpenSurface(ctx context.Context, source UIExtensionSource, request UISurfaceOpenRequest) (UIFrameResponse, error)
	UpdateSurface(ctx context.Context, source UIExtensionSource, request UISurfaceFrameRequest) (UIFrameResponse, error)
	CloseSurface(ctx context.Context, source UIExtensionSource, request UISurfaceCloseRequest) (UIFrameResponse, error)
	CleanupExtensionUI(owner UIExtensionOwner)
}

ExtensionUIHost owns extension widgets and interactive surfaces for an interactive frontend.

func ExtensionUIHostFromContext 

func ExtensionUIHostFromContext(ctx context.Context) (ExtensionUIHost, bool)

ExtensionUIHostFromContext returns the interactive extension UI host, if any.

type ExtensionUITranscriptHost 

type ExtensionUITranscriptHost interface {
	AppendTranscript(ctx context.Context, source UIExtensionSource, request UITranscriptAppendRequest) (UITranscriptAppendResponse, error)
}

ExtensionUITranscriptHost optionally accepts persistent informational transcript entries.

type InitializeResult 

type InitializeResult struct {
	Name          string                `json:"name"`
	Version       string                `json:"version,omitempty"`
	Tools         []ToolRegistration    `json:"tools,omitempty"`
	Commands      []CommandRegistration `json:"commands,omitempty"`
	Subscriptions []Subscription        `json:"subscriptions,omitempty"`
}

InitializeResult is returned by extension.initialize.

type Process 

type Process struct {
	Extension Extension
	// contains filtered or unexported fields
}

Process is a running extension subprocess.

func StartProcess 

func StartProcess(ctx context.Context, ext Extension, config Config, workspaceCWD string) (*Process, error)

StartProcess starts an extension subprocess and initializes its JSON-RPC client.

func (*Process) Close 

func (p *Process) Close() error

Close terminates the extension process.

func (*Process) ExecuteCommand 

func (p *Process) ExecuteCommand(ctx context.Context, name string, input map[string]any, invocation CommandInvocation, callContext ExtensionCallContext) (*CommandResult, error)

ExecuteCommand invokes an extension-provided command over JSON-RPC.

func (*Process) ExecuteTool 

func (p *Process) ExecuteTool(ctx context.Context, name string, input json.RawMessage, callContext ExtensionCallContext) (*ToolExecutionResult, error)

ExecuteTool invokes an extension-provided tool.

func (*Process) ExecuteToolStreaming 

func (p *Process) ExecuteToolStreaming(ctx context.Context, name string, input json.RawMessage, callContext ExtensionCallContext, onUpdate func(ToolExecutionResult)) (*ToolExecutionResult, error)

ExecuteToolStreaming invokes an extension-provided tool and forwards transient updates.

func (*Process) HandleEvent 

func (p *Process) HandleEvent(ctx context.Context, eventID string, eventName string, payload any, callContext ExtensionCallContext) (*EventResult, error)

HandleEvent invokes an extension event handler.

func (*Process) HandleRPCRequest 

func (p *Process) HandleRPCRequest(ctx context.Context, method string, params json.RawMessage) (any, *rpcError)

func (*Process) Initialize 

func (p *Process) Initialize(ctx context.Context, cwd string) (*InitializeResult, error)

Initialize initializes the extension process and returns its registrations.

type Root 

type Root struct {
	Dir          string
	Kind         SourceKind
	PluginPrefix string
}

Root describes a directory that should be scanned for extension executables.

type RoutedCommandResult 

type RoutedCommandResult struct {
	Matched      bool
	CommandName  string
	ExtensionID  string
	Action       string
	Response     string
	Prompt       string
	RecipeName   string
	Display      string
	Registration CommandRegistration
}

RoutedCommandResult is returned by TryCommand.

type Runtime 

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

Runtime manages discovered extension processes and registrations.

func EmptyRuntime 

func EmptyRuntime() *Runtime

EmptyRuntime creates an extension runtime with no processes or registrations. It is useful for callers that want to attach a non-nil runtime before discovery has found any extensions.

func NewRuntime 

func NewRuntime(ctx context.Context, opts ...DiscoveryOption) (*Runtime, error)

NewRuntime creates and initializes an extension runtime.

func NewRuntimeFromViper 

func NewRuntimeFromViper(ctx context.Context, workingDir string) (*Runtime, error)

NewRuntimeFromViper creates a runtime from viper config.

func (*Runtime) CanStreamToolUpdates 

func (r *Runtime) CanStreamToolUpdates() bool

CanStreamToolUpdates reports whether every extension that mutates final tool results also subscribes to tool.update. This prevents partial output from bypassing an existing result sanitization policy.

func (*Runtime) Close 

func (r *Runtime) Close() error

Close terminates all extension processes.

func (*Runtime) Commands 

func (r *Runtime) Commands() []Command

Commands returns registered extension commands.

func (*Runtime) DispatchAgentEnd 

func (r *Runtime) DispatchAgentEnd(ctx context.Context, callContext ExtensionCallContext, messages []llmtypes.Message) []string

DispatchAgentEnd runs agent.end subscriptions and returns accumulated follow-up messages.

func (*Runtime) DispatchAgentInit 

func (r *Runtime) DispatchAgentInit(ctx context.Context, callContext ExtensionCallContext, systemPrompt string) string

DispatchAgentInit runs agent.init subscriptions and applies system prompt patches.

func (*Runtime) DispatchAgentInitDecision 

func (r *Runtime) DispatchAgentInitDecision(ctx context.Context, callContext ExtensionCallContext, systemPrompt string, allowedTools []string) AgentInitDecision

DispatchAgentInitDecision runs agent.init subscriptions and applies system prompt and tool-list patches.

func (*Runtime) DispatchAgentStart 

func (r *Runtime) DispatchAgentStart(ctx context.Context, callContext ExtensionCallContext)

DispatchAgentStart runs agent.start subscriptions.

func (*Runtime) DispatchResourcesDiscover 

func (r *Runtime) DispatchResourcesDiscover(ctx context.Context, callContext ExtensionCallContext)

DispatchResourcesDiscover runs resources.discover subscriptions.

func (*Runtime) DispatchSessionEnd 

func (r *Runtime) DispatchSessionEnd(ctx context.Context, callContext ExtensionCallContext)

DispatchSessionEnd runs session.end subscriptions.

func (*Runtime) DispatchSessionStart 

func (r *Runtime) DispatchSessionStart(ctx context.Context, callContext ExtensionCallContext)

DispatchSessionStart runs session.start subscriptions.

func (*Runtime) DispatchToolCall 

func (r *Runtime) DispatchToolCall(ctx context.Context, callContext ExtensionCallContext, toolName, toolInput, toolCallID string) ToolCallDecision

DispatchToolCall runs tool.call subscriptions sequentially.

func (*Runtime) DispatchToolResult 

func (r *Runtime) DispatchToolResult(ctx context.Context, callContext ExtensionCallContext, toolName, toolInput, toolCallID string, output tooltypes.StructuredToolResult) (tooltypes.StructuredToolResult, bool)

DispatchToolResult runs tool.result subscriptions sequentially.

func (*Runtime) DispatchToolUpdate 

func (r *Runtime) DispatchToolUpdate(ctx context.Context, callContext ExtensionCallContext, toolName, toolInput, toolCallID string, output tooltypes.StructuredToolResult) (tooltypes.StructuredToolResult, bool, bool)

DispatchToolUpdate runs tool.update subscriptions sequentially. The accepted result is false when a subscribed sanitizer fails, so callers can drop the transient snapshot instead of exposing unsanitized output.

func (*Runtime) DispatchTurnEnd 

func (r *Runtime) DispatchTurnEnd(ctx context.Context, callContext ExtensionCallContext, response string, turnNumber int)

DispatchTurnEnd runs turn.end subscriptions.

func (*Runtime) DispatchTurnStart 

func (r *Runtime) DispatchTurnStart(ctx context.Context, callContext ExtensionCallContext, turnNumber int)

DispatchTurnStart runs turn.start subscriptions.

func (*Runtime) DispatchUserMessage 

func (r *Runtime) DispatchUserMessage(ctx context.Context, callContext ExtensionCallContext, message string) UserMessageDecision

DispatchUserMessage runs user.message subscriptions sequentially.

func (*Runtime) SlashCommands 

func (r *Runtime) SlashCommands() []slashcommands.Command

SlashCommands returns extension command registrations in the shared slash command shape used by CLI/ACP/web command discovery surfaces.

func (*Runtime) Subscriptions 

func (r *Runtime) Subscriptions() []Subscription

Subscriptions returns registered extension event subscriptions.

func (*Runtime) Tools 

func (r *Runtime) Tools() []tooltypes.Tool

Tools returns registered extension tools sorted by name.

func (*Runtime) TryCommand 

func (r *Runtime) TryCommand(ctx context.Context, rawPrompt, commandName, args string, callContext ExtensionCallContext) (*RoutedCommandResult, error)

TryCommand routes a parsed slash command through extension command registrations.

type RuntimeManager 

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

RuntimeManager reuses extension runtimes for the lifetime of an interactive host. Runtimes are scoped by canonical working directory and closed together with the host.

func NewRuntimeManager 

func NewRuntimeManager() *RuntimeManager

NewRuntimeManager creates a persistent extension runtime manager.

func (*RuntimeManager) Close 

func (m *RuntimeManager) Close() error

Close terminates every managed extension runtime. It is safe to call more than once.

func (*RuntimeManager) Runtime 

func (m *RuntimeManager) Runtime(ctx context.Context, cwd string) (*Runtime, error)

Runtime returns the runtime associated with cwd, creating it on first use.

func (*RuntimeManager) RuntimeForCommandDiscovery 

func (m *RuntimeManager) RuntimeForCommandDiscovery(ctx context.Context, cwd string) (*Runtime, error)

RuntimeForCommandDiscovery returns a cached runtime without starting session lifecycle events.

type SourceKind 

type SourceKind string

SourceKind identifies where an extension was discovered. 

const (
	SourceKindLocalStandalone  SourceKind = "local_standalone"
	SourceKindLocalPlugin      SourceKind = "local_plugin"
	SourceKindGlobalStandalone SourceKind = "global_standalone"
	SourceKindGlobalPlugin     SourceKind = "global_plugin"
)

type Subscription 

type Subscription struct {
	Event        string   `json:"event"`
	Priority     int      `json:"priority,omitempty"`
	TimeoutInSec *float64 `json:"timeoutInSec,omitempty"`
}

Subscription declares an event handler registered by an extension.

type SystemPromptPatch 

type SystemPromptPatch struct {
	Prepend *string `json:"prepend,omitempty"`
	Append  *string `json:"append,omitempty"`
	Replace *string `json:"replace,omitempty"`
}

SystemPromptPatch describes an agent.init system prompt mutation.

type TerminalUIInputBroker 

type TerminalUIInputBroker struct {
	In          io.Reader
	Out         io.Writer
	Interactive bool
	// contains filtered or unexported fields
}

TerminalUIInputBroker prompts for extension-requested input in an interactive terminal.

func NewTerminalUIInputBroker 

func NewTerminalUIInputBroker(in io.Reader, out io.Writer) *TerminalUIInputBroker

NewTerminalUIInputBroker creates a terminal-backed UI input broker.

func (*TerminalUIInputBroker) Confirm 

func (b *TerminalUIInputBroker) Confirm(ctx context.Context, request UIConfirmRequest) (UIInputResponse, error)

Confirm asks the user for a yes/no decision.

func (*TerminalUIInputBroker) Input 

func (b *TerminalUIInputBroker) Input(ctx context.Context, request UIInputRequest) (UIInputResponse, error)

Input asks the user for a single line of input.

func (*TerminalUIInputBroker) Notify 

func (b *TerminalUIInputBroker) Notify(ctx context.Context, request UINotifyRequest) (UIInputResponse, error)

Notify displays a one-way notification.

func (*TerminalUIInputBroker) Select 

func (b *TerminalUIInputBroker) Select(ctx context.Context, request UISelectRequest) (UIInputResponse, error)

Select asks the user to choose one option.

type Tool 

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

Tool is a tool registered by an extension.

func (*Tool) Description 

func (t *Tool) Description() string

Description returns the extension tool description.

func (*Tool) Execute 

func (t *Tool) Execute(ctx context.Context, _ tooltypes.State, parameters string) tooltypes.ToolResult

Execute invokes the extension tool over JSON-RPC.

func (*Tool) ExecuteStreaming 

func (t *Tool) ExecuteStreaming(ctx context.Context, _ tooltypes.State, parameters string, onUpdate tooltypes.ToolUpdateCallback) tooltypes.ToolResult

ExecuteStreaming invokes the extension tool and forwards accumulated snapshots.

func (*Tool) GenerateSchema 

func (t *Tool) GenerateSchema() *jsonschema.Schema

GenerateSchema returns a typed compatibility view of the extension schema.

func (*Tool) Name 

func (t *Tool) Name() string

Name returns the extension tool name.

func (*Tool) RawInputSchema 

func (t *Tool) RawInputSchema() map[string]any

RawInputSchema returns the extension-provided schema without narrowing it.

func (*Tool) TracingKVs 

func (t *Tool) TracingKVs(_ string) ([]attribute.KeyValue, error)

TracingKVs returns tracing attributes for the tool.

func (*Tool) ValidateInput 

func (t *Tool) ValidateInput(_ tooltypes.State, parameters string) error

ValidateInput validates JSON syntax. Schema validation is delegated to the extension SDK/runtime.

type ToolCallDecision 

type ToolCallDecision struct {
	Blocked bool
	Reason  string
	Input   string
}

ToolCallDecision is the result of dispatching a tool.call event.

type ToolConfig 

type ToolConfig struct {
	Enabled *bool `mapstructure:"enabled" json:"enabled" yaml:"enabled"`
}

ToolConfig controls runtime behavior for a specific extension-provided tool.

type ToolExecutionResult 

type ToolExecutionResult struct {
	Content string         `json:"content"`
	Data    map[string]any `json:"data,omitempty"`
	Error   string         `json:"error,omitempty"`
}

ToolExecutionResult is returned by extension.tool.execute.

type ToolListPatch 

type ToolListPatch struct {
	Disable []string `json:"disable,omitempty"`
	Enable  []string `json:"enable,omitempty"`
}

ToolListPatch describes an agent.init mutation to the tool allowlist.

type ToolRegistration 

type ToolRegistration struct {
	Name         string         `json:"name"`
	Description  string         `json:"description"`
	InputSchema  map[string]any `json:"inputSchema"`
	TimeoutInSec *float64       `json:"timeoutInSec,omitempty"`
}

ToolRegistration is returned by an extension during initialization.

type ToolResult 

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

ToolResult is the result of an extension tool execution.

func (*ToolResult) AssistantFacing 

func (r *ToolResult) AssistantFacing() string

AssistantFacing returns the result for the assistant.

func (*ToolResult) GetError 

func (r *ToolResult) GetError() string

GetError returns the error string.

func (*ToolResult) GetResult 

func (r *ToolResult) GetResult() string

GetResult returns the result string.

func (*ToolResult) IsError 

func (r *ToolResult) IsError() bool

IsError returns true when execution failed.

func (*ToolResult) String 

func (r *ToolResult) String() string

func (*ToolResult) StructuredData 

func (r *ToolResult) StructuredData() tooltypes.StructuredToolResult

StructuredData returns structured metadata.

type UIConfirmBroker 

type UIConfirmBroker interface {
	Confirm(ctx context.Context, request UIConfirmRequest) (UIInputResponse, error)
}

UIConfirmBroker routes extension confirmation requests to the active user interface.

func UIConfirmBrokerFromContext 

func UIConfirmBrokerFromContext(ctx context.Context) (UIConfirmBroker, bool)

UIConfirmBrokerFromContext returns the run-scoped confirmation broker, if one exists.

type UIConfirmRequest 

type UIConfirmRequest struct {
	ID                string `json:"id,omitempty"`
	Title             string `json:"title"`
	Message           string `json:"message,omitempty"`
	ConfirmButtonText string `json:"confirmButtonText,omitempty"`
	CancelButtonText  string `json:"cancelButtonText,omitempty"`
}

UIConfirmRequest describes a yes/no prompt requested by an extension.

type UIExtensionOwner 

type UIExtensionOwner struct {
	ExtensionID string
	Generation  uint64
}

UIExtensionOwner identifies one running generation of an extension process. The generation keeps frames from a failed process separate from a restarted process whose sequence numbers begin at one again.

type UIExtensionSource 

type UIExtensionSource interface {
	ExtensionUIOwner() UIExtensionOwner
	NotifyExtensionUI(ctx context.Context, method string, params any) error
}

UIExtensionSource is a running process capable of receiving host UI events.

type UIFrame 

type UIFrame struct {
	Sequence uint64        `json:"sequence"`
	Lines    []UIFrameLine `json:"lines"`
}

UIFrame is a complete, replace-in-place presentation snapshot.

type UIFrameLine 

type UIFrameLine struct {
	Spans []UIStyledSpan `json:"spans"`
}

UIFrameLine accepts either a plain JSON string or an object containing styled spans. Internally both representations use spans.

func (UIFrameLine) MarshalJSON 

func (l UIFrameLine) MarshalJSON() ([]byte, error)

MarshalJSON preserves the concise string representation for plain lines.

func (*UIFrameLine) UnmarshalJSON 

func (l *UIFrameLine) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the mixed string/styled-line wire representation.

type UIFrameResponse 

type UIFrameResponse struct {
	Accepted       bool   `json:"accepted"`
	LatestSequence uint64 `json:"latestSequence"`
	Reason         string `json:"reason,omitempty"`
}

UIFrameResponse acknowledges the latest accepted sequence for an object.

type UIInputBroker 

type UIInputBroker interface {
	Input(ctx context.Context, request UIInputRequest) (UIInputResponse, error)
}

UIInputBroker routes extension UI input requests to the active user interface.

func UIInputBrokerFromContext 

func UIInputBrokerFromContext(ctx context.Context) (UIInputBroker, bool)

UIInputBrokerFromContext returns the run-scoped UI input broker, if one exists.

type UIInputRequest 

type UIInputRequest struct {
	ID               string `json:"id,omitempty"`
	Title            string `json:"title"`
	HelpText         string `json:"helpText,omitempty"`
	Message          string `json:"message,omitempty"`
	Placeholder      string `json:"placeholder,omitempty"`
	DefaultValue     string `json:"defaultValue,omitempty"`
	SubmitButtonText string `json:"submitButtonText,omitempty"`
	CancelButtonText string `json:"cancelButtonText,omitempty"`
	Required         bool   `json:"required,omitempty"`
	Secret           bool   `json:"secret,omitempty"`
}

UIInputRequest describes a user-input prompt requested by an extension.

type UIInputResponse 

type UIInputResponse struct {
	Status    string `json:"status"`
	Value     string `json:"value,omitempty"`
	Confirmed bool   `json:"confirmed,omitempty"`
	Reason    string `json:"reason,omitempty"`
}

UIInputResponse is returned to the extension after a UI input prompt resolves.

type UIMargin 

type UIMargin struct {
	Top    int `json:"top,omitempty"`
	Right  int `json:"right,omitempty"`
	Bottom int `json:"bottom,omitempty"`
	Left   int `json:"left,omitempty"`
}

UIMargin constrains an overlay to the usable terminal rectangle.

type UINotifyBroker 

type UINotifyBroker interface {
	Notify(ctx context.Context, request UINotifyRequest) (UIInputResponse, error)
}

UINotifyBroker routes extension notifications to the active user interface.

func UINotifyBrokerFromContext 

func UINotifyBrokerFromContext(ctx context.Context) (UINotifyBroker, bool)

UINotifyBrokerFromContext returns the run-scoped notification broker, if one exists.

type UINotifyRequest 

type UINotifyRequest struct {
	Title   string `json:"title,omitempty"`
	Message string `json:"message"`
}

UINotifyRequest describes a fire-and-forget notification requested by an extension.

type UISelectBroker 

type UISelectBroker interface {
	Select(ctx context.Context, request UISelectRequest) (UIInputResponse, error)
}

UISelectBroker routes extension selection requests to the active user interface.

func UISelectBrokerFromContext 

func UISelectBrokerFromContext(ctx context.Context) (UISelectBroker, bool)

UISelectBrokerFromContext returns the run-scoped selection broker, if one exists.

type UISelectRequest 

type UISelectRequest struct {
	ID               string   `json:"id,omitempty"`
	Title            string   `json:"title"`
	Message          string   `json:"message,omitempty"`
	Options          []string `json:"options"`
	SubmitButtonText string   `json:"submitButtonText,omitempty"`
	CancelButtonText string   `json:"cancelButtonText,omitempty"`
}

UISelectRequest describes a single-choice prompt requested by an extension.

type UISizeValue 

type UISizeValue struct {
	Cells   int
	Percent float64
	Set     bool
}

UISizeValue is either a fixed terminal-cell count or a percentage.

func (UISizeValue) MarshalJSON 

func (v UISizeValue) MarshalJSON() ([]byte, error)

MarshalJSON emits the same number-or-percentage representation accepted by UnmarshalJSON.

func (*UISizeValue) UnmarshalJSON 

func (v *UISizeValue) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts positive integer cell counts and strings such as "75%".

type UIStyle 

type UIStyle struct {
	Foreground    string `json:"foreground,omitempty"`
	Background    string `json:"background,omitempty"`
	Bold          bool   `json:"bold,omitempty"`
	Dim           bool   `json:"dim,omitempty"`
	Italic        bool   `json:"italic,omitempty"`
	Underline     bool   `json:"underline,omitempty"`
	Strikethrough bool   `json:"strikethrough,omitempty"`
	Reverse       bool   `json:"reverse,omitempty"`
}

UIStyle describes terminal-safe styling for one text span.

type UIStyledSpan 

type UIStyledSpan struct {
	Text  string  `json:"text"`
	Style UIStyle `json:"style,omitempty"`
}

UIStyledSpan is a styled run of text in a widget or surface line.

type UISurfaceCloseRequest 

type UISurfaceCloseRequest struct {
	ID       string `json:"id"`
	Sequence uint64 `json:"sequence"`
}

UISurfaceCloseRequest closes an interactive surface.

type UISurfaceFrameRequest 

type UISurfaceFrameRequest struct {
	ID    string  `json:"id"`
	Frame UIFrame `json:"frame"`
}

UISurfaceFrameRequest replaces a surface's current presentation frame.

type UISurfaceInputNotification 

type UISurfaceInputNotification struct {
	ID       string               `json:"id"`
	Sequence uint64               `json:"sequence"`
	Kind     string               `json:"kind"`
	Key      string               `json:"key,omitempty"`
	Text     string               `json:"text,omitempty"`
	Alt      bool                 `json:"alt,omitempty"`
	Shift    bool                 `json:"shift,omitempty"`
	Ctrl     bool                 `json:"ctrl,omitempty"`
	Mouse    *UISurfaceMouseEvent `json:"mouse,omitempty"`
}

UISurfaceInputNotification routes terminal input and focus changes to an extension.

type UISurfaceMouseEvent 

type UISurfaceMouseEvent struct {
	X      int    `json:"x"`
	Y      int    `json:"y"`
	Button string `json:"button"`
	Action string `json:"action"`
	Shift  bool   `json:"shift,omitempty"`
	Alt    bool   `json:"alt,omitempty"`
	Ctrl   bool   `json:"ctrl,omitempty"`
}

UISurfaceMouseEvent describes a mouse event relative to the surface origin.

type UISurfaceOpenRequest 

type UISurfaceOpenRequest struct {
	ID      string           `json:"id"`
	Options UISurfaceOptions `json:"options,omitempty"`
	Frame   UIFrame          `json:"frame"`
}

UISurfaceOpenRequest creates or replaces an interactive overlay surface.

type UISurfaceOptions 

type UISurfaceOptions struct {
	Width        UISizeValue `json:"width,omitempty"`
	Height       UISizeValue `json:"height,omitempty"`
	MaxWidth     UISizeValue `json:"maxWidth,omitempty"`
	MaxHeight    UISizeValue `json:"maxHeight,omitempty"`
	Anchor       string      `json:"anchor,omitempty"`
	OffsetX      int         `json:"offsetX,omitempty"`
	OffsetY      int         `json:"offsetY,omitempty"`
	Margin       UIMargin    `json:"margin,omitempty"`
	NonCapturing bool        `json:"nonCapturing,omitempty"`
}

UISurfaceOptions controls overlay allocation and focus behavior.

type UISurfaceResizeNotification 

type UISurfaceResizeNotification struct {
	ID       string `json:"id"`
	Sequence uint64 `json:"sequence"`
	Width    int    `json:"width"`
	Height   int    `json:"height"`
}

UISurfaceResizeNotification reports the current allocated overlay size.

type UITranscriptAppendRequest 

type UITranscriptAppendRequest struct {
	Title   string `json:"title,omitempty"`
	Message string `json:"message"`
}

UITranscriptAppendRequest appends a persistent informational TUI transcript entry.

type UITranscriptAppendResponse 

type UITranscriptAppendResponse struct {
	Accepted bool   `json:"accepted"`
	Reason   string `json:"reason,omitempty"`
}

UITranscriptAppendResponse reports whether an informational entry was accepted.

type UIWidgetFrameRequest 

type UIWidgetFrameRequest struct {
	ID    string  `json:"id"`
	Frame UIFrame `json:"frame"`
}

UIWidgetFrameRequest updates an existing passive widget.

type UIWidgetRemoveRequest 

type UIWidgetRemoveRequest struct {
	ID       string `json:"id"`
	Sequence uint64 `json:"sequence"`
}

UIWidgetRemoveRequest removes a passive widget.

type UIWidgetSetRequest 

type UIWidgetSetRequest struct {
	ID        string  `json:"id"`
	Placement string  `json:"placement"`
	Frame     UIFrame `json:"frame"`
}

UIWidgetSetRequest creates or replaces a passive widget frame.

type UserMessageDecision 

type UserMessageDecision struct {
	Blocked bool
	Reason  string
	Message string
}

UserMessageDecision is the result of dispatching a user.message event.

Source Files

View all Source files

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.