extension

package
v0.0.0-...-33893c2 Latest Latest
Warning

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

 Go to latest Published: Jun 19, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package extension loads and executes user workflow extensions.

Index

Constants

View Source 
const (
	// UIDrawKindBox draws a border around a window.
	UIDrawKindBox = "box"
	// UIDrawKindClear clears a window-relative rectangular region.
	UIDrawKindClear = "clear"
	// UIDrawKindSpans draws multiple styled inline text spans.
	UIDrawKindSpans = "spans"
	// UIDrawKindText draws one styled text segment.
	UIDrawKindText = "text"
)
View Source 
const (
	// LockFileName is the filename used for extension version locks.
	LockFileName = "extensions-lock.yaml"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ActionCall 

type ActionCall struct {
	Name string `json:"name"`
}

ActionCall requests a host-side runtime action.

type BufferBlock 

type BufferBlock struct {
	Metadata  map[string]any `json:"metadata"`
	CreatedAt string         `json:"created_at"`
	ID        string         `json:"id"`
	Kind      string         `json:"kind"`
	Role      string         `json:"role"`
	Text      string         `json:"text"`
	Index     int            `json:"index"`
	Streaming bool           `json:"streaming"`
}

BufferBlock describes one generic structured item inside a runtime buffer.

type BufferState 

type BufferState struct {
	Metadata map[string]any `json:"metadata"`
	Blocks   []BufferBlock  `json:"blocks"`
	Name     string         `json:"name"`
	Text     string         `json:"text"`
	Label    string         `json:"label"`
	Chars    []string       `json:"chars"`
	Cursor   int            `json:"cursor"`
}

BufferState describes an extension-visible mutable runtime buffer.

type Command 

type Command struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	Extension   string `json:"extension"`
}

Command describes a Lua slash command.

type CommandRunner 

type CommandRunner interface {
	ExecuteCommand(ctx context.Context, name, args string) (string, error)
}

CommandRunner executes a named extension command.

type CompactionMutation 

type CompactionMutation struct {
	Summary          *string        `json:"summary,omitempty"`
	FirstKeptEntryID *string        `json:"first_kept_entry_id,omitempty"`
	Details          map[string]any `json:"details,omitempty"`
	Cancel           bool           `json:"cancel,omitempty"`
}

CompactionMutation contains conservative compaction changes returned by lifecycle handlers.

type ComposerKeyEvent 

type ComposerKeyEvent struct {
	Key   string `json:"key"`
	Text  string `json:"text"`
	Ctrl  bool   `json:"ctrl"`
	Alt   bool   `json:"alt"`
	Shift bool   `json:"shift"`
}

ComposerKeyEvent describes a terminal key event passed to a composer extension.

type ConfiguredSource 

type ConfiguredSource struct {
	Source  string `json:"source" mapstructure:"source" yaml:"source"`
	Version string `json:"version" mapstructure:"version" yaml:"version"`
}

ConfiguredSource is one extension source entry from user configuration.

type EventEmitter 

type EventEmitter interface {
	Emit(ctx context.Context, eventName string, payload map[string]any) error
}

EventEmitter emits extension lifecycle events.

type FocusState 

type FocusState struct {
	Kind      string `json:"kind"`
	Window    string `json:"window"`
	Buffer    string `json:"buffer"`
	Role      string `json:"role"`
	PanelKind string `json:"panel_kind"`
	Exclusive bool   `json:"exclusive"`
}

FocusState describes the currently focused input target for extension key routing.

type LayoutState 

type LayoutState struct {
	Windows map[string]WindowState `json:"windows"`
	Width   int                    `json:"width"`
	Height  int                    `json:"height"`
}

LayoutState describes the extension-visible terminal layout.

type LifecycleDispatchResult 

type LifecycleDispatchResult struct {
	Payload         map[string]any          `json:"payload"`
	ProviderRequest ProviderRequestMutation `json:"provider_request"`
	ToolCall        ToolCallMutation        `json:"tool_call"`
	ToolResult      ToolResultMutation      `json:"tool_result"`
	Compaction      CompactionMutation      `json:"compaction"`
	Name            string                  `json:"name"`
	Errors          []string                `json:"errors"`
	Duration        time.Duration           `json:"duration"`
	HandlerCount    int                     `json:"handler_count"`
	Consumed        bool                    `json:"consumed"`
	Stopped         bool                    `json:"stopped"`
}

LifecycleDispatchResult describes the outcome of lifecycle handler dispatch.

type LifecycleDispatcher 

type LifecycleDispatcher interface {
	DispatchLifecycle(ctx context.Context, event LifecycleEvent) (LifecycleDispatchResult, error)
}

LifecycleDispatcher emits runtime-neutral lifecycle events.

type LifecycleEvent 

type LifecycleEvent struct {
	Payload map[string]any     `json:"payload"`
	Name    LifecycleEventName `json:"name"`
}

LifecycleEvent is the runtime-neutral payload passed through lifecycle handlers.

type LifecycleEventName 

type LifecycleEventName string

LifecycleEventName identifies one agent/runtime lifecycle event. 

const (
	// LifecycleSessionStart fires when a new session is created.
	LifecycleSessionStart LifecycleEventName = "session_start"
	// LifecycleSessionLoad fires when an existing session is loaded.
	LifecycleSessionLoad LifecycleEventName = "session_load"
	// LifecycleSessionSave fires after durable session state is written.
	LifecycleSessionSave LifecycleEventName = "session_save"
	// LifecycleSessionShutdown fires before a session/runtime shuts down.
	LifecycleSessionShutdown LifecycleEventName = "session_shutdown"
	// LifecycleResourcesDiscover fires while project resources are discovered.
	LifecycleResourcesDiscover LifecycleEventName = "resources_discover"
	// LifecycleInput fires when raw user input enters the assistant runtime.
	LifecycleInput LifecycleEventName = "input"
	// LifecyclePromptPrepare fires before a prompt becomes a model turn.
	LifecyclePromptPrepare LifecycleEventName = "prompt_prepare"
	// LifecycleBeforeAgentStart fires before assistant turn execution starts.
	LifecycleBeforeAgentStart LifecycleEventName = "before_agent_start"
	// LifecycleAgentStart fires when assistant turn execution starts.
	LifecycleAgentStart LifecycleEventName = "agent_start"
	// LifecycleTurnStart fires when a model-facing turn starts.
	LifecycleTurnStart LifecycleEventName = "turn_start"
	// LifecycleContextBuild fires while model context is assembled.
	LifecycleContextBuild LifecycleEventName = "context_build"
	// LifecycleBeforeProviderRequest fires before a provider request is sent.
	LifecycleBeforeProviderRequest LifecycleEventName = "before_provider_request"
	// LifecycleAfterProviderResponse fires after a provider response is received.
	LifecycleAfterProviderResponse LifecycleEventName = "after_provider_response"
	// LifecycleProviderError fires when a provider request fails.
	LifecycleProviderError LifecycleEventName = "provider_error"
	// LifecycleToolCall fires before a tool call executes.
	LifecycleToolCall LifecycleEventName = "tool_call"
	// LifecycleToolResult fires after a tool call returns.
	LifecycleToolResult LifecycleEventName = "tool_result"
	// LifecycleToolError fires when a tool call fails.
	LifecycleToolError LifecycleEventName = "tool_error"
	// LifecycleMessageAppend fires after a durable message is appended.
	LifecycleMessageAppend LifecycleEventName = "message_append"
	// LifecycleTurnEnd fires when a model-facing turn ends.
	LifecycleTurnEnd LifecycleEventName = "turn_end"
	// LifecycleSessionBeforeCompact fires before compacted context is summarized and saved.
	LifecycleSessionBeforeCompact LifecycleEventName = "session_before_compact"
	// LifecycleSessionCompact fires after a compaction entry is saved.
	LifecycleSessionCompact LifecycleEventName = "session_compact"
	// LifecycleAgentEnd fires when assistant turn execution ends.
	LifecycleAgentEnd LifecycleEventName = "agent_end"
	// LifecycleShutdown fires before the runtime exits.
	LifecycleShutdown LifecycleEventName = "shutdown"
)

type LoadedExtension 

type LoadedExtension struct {
	Name          string        `json:"name"`
	Path          string        `json:"path"`
	Commands      []string      `json:"commands"`
	Tools         []string      `json:"tools"`
	Keymaps       []string      `json:"keymaps"`
	Handlers      []string      `json:"handlers"`
	Timers        int           `json:"timers"`
	TotalDuration time.Duration `json:"total_duration"`
}

LoadedExtension contains metadata for a loaded extension.

type LockFile 

type LockFile struct {
	Extensions map[string]LockedExtension `json:"extensions" yaml:"extensions"`
}

LockFile pins resolved extension versions.

func ReadLockFile 

func ReadLockFile(path string) (LockFile, error)

ReadLockFile loads an extension lockfile. Missing files return an empty lock.

type LockedExtension 

type LockedExtension struct {
	Resolved string `json:"resolved,omitempty" yaml:"resolved,omitempty"`
	Version  string `json:"version,omitempty" yaml:"version,omitempty"`
}

LockedExtension pins one configured extension source.

type Manager 

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

Manager is the built-in Lua runtime adapter for the extension host.

func NewManager 

func NewManager(logger *slog.Logger) *Manager

NewManager creates an empty Lua runtime adapter.

func (*Manager) Commands 

func (manager *Manager) Commands() []Command

Commands returns registered extension commands sorted by name.

func (*Manager) DispatchLifecycle 

func (manager *Manager) DispatchLifecycle(ctx context.Context, event LifecycleEvent) (LifecycleDispatchResult, error)

DispatchLifecycle runs registered handlers for a lifecycle event.

func (*Manager) Emit 

func (manager *Manager) Emit(ctx context.Context, eventName string, payload map[string]any) error

Emit sends an event to registered extension handlers.

func (*Manager) ExecuteCommand 

func (manager *Manager) ExecuteCommand(ctx context.Context, name, args string) (string, error)

ExecuteCommand runs a registered extension slash command.

func (*Manager) ExecuteTool 

func (manager *Manager) ExecuteTool(ctx context.Context, name string, args map[string]any) (ToolResult, error)

ExecuteTool runs a registered extension tool.

func (*Manager) Extensions 

func (manager *Manager) Extensions() []LoadedExtension

Extensions returns loaded extension metadata.

func (*Manager) HandleTerminalEvent 

func (manager *Manager) HandleTerminalEvent(ctx context.Context, event *TerminalEvent) (TerminalEventResult, error)

HandleTerminalEvent runs registered low-level terminal runtime handlers.

func (*Manager) HasTerminalEventHandlers 

func (manager *Manager) HasTerminalEventHandlers(eventName string) bool

HasTerminalEventHandlers reports whether any extension handler is registered for eventName.

func (*Manager) LoadFile 

func (manager *Manager) LoadFile(ctx context.Context, extensionPath string) error

LoadFile loads one Lua extension source file.

func (*Manager) LoadManifest 

func (manager *Manager) LoadManifest(ctx context.Context, manifestPath string) error

LoadManifest loads one directory-based Lua extension manifest.

func (*Manager) LoadPaths 

func (manager *Manager) LoadPaths(ctx context.Context, paths []string) error

LoadPaths discovers and loads Lua extension sources from files or directories.

func (*Manager) NextTimerDelay 

func (manager *Manager) NextTimerDelay(now time.Time) (time.Duration, bool)

NextTimerDelay reports the duration until the next scheduled timer is due.

func (*Manager) ReadManifest 

func (manager *Manager) ReadManifest(manifestPath string) (Manifest, error)

ReadManifest reads a directory-based Lua manifest without executing extension entry code.

func (*Manager) Shutdown 

func (manager *Manager) Shutdown()

Shutdown closes all loaded Lua states and clears registrations.

func (*Manager) Tools 

func (manager *Manager) Tools() []Tool

Tools returns registered extension tools sorted by name.

type ManagerState 

type ManagerState struct {
	Configured []ResolvedSource
	Loaded     []LoadedExtension
}

ManagerState describes configured, resolved, and loaded extension state.

type Manifest 

type Manifest struct {
	Name        string
	Version     string
	APIVersion  string
	Description string
	Entry       string
}

Manifest describes a directory-based extension manifest returned from init.lua.

type ProviderRequestMutation 

type ProviderRequestMutation struct {
	Headers map[string]string `json:"headers"`
}

ProviderRequestMutation contains conservative provider request changes returned by lifecycle handlers.

type ResolvedSource 

type ResolvedSource struct {
	Configured ConfiguredSource
	Ref        SourceRef
	Lock       LockedExtension
	LoadPath   string
	Name       string
	Status     string
}

ResolvedSource describes a configured extension after applying aliases and locks.

func ResolveConfiguredSources 

func ResolveConfiguredSources(
	configuredSources []ConfiguredSource,
	lockFile LockFile,
	installRoot string,
) ([]ResolvedSource, error)

ResolveConfiguredSources resolves configured extension entries using a lockfile.

type SourceRef 

type SourceRef struct {
	Scheme  string
	Value   string
	Version string
}

SourceRef describes one configured extension source.

func ParseSourceRef 

func ParseSourceRef(source, version string) (SourceRef, error)

ParseSourceRef parses extension source strings like official:vim-mode or github:user/repo.

func (SourceRef) Key 

func (source SourceRef) Key() string

Key returns the stable source key used in diagnostics and lockfiles.

type TerminalEvent 

type TerminalEvent struct {
	Buffers map[string]BufferState `json:"buffers"`
	Windows map[string]WindowState `json:"windows"`
	Context map[string]any         `json:"context"`
	Data    map[string]any         `json:"data"`
	Name    string                 `json:"name"`
	Key     ComposerKeyEvent       `json:"key"`
	Layout  LayoutState            `json:"layout"`
	Focus   FocusState             `json:"focus"`
}

TerminalEvent describes a low-level terminal runtime event exposed to extensions.

type TerminalEventInspector 

type TerminalEventInspector interface {
	HasTerminalEventHandlers(eventName string) bool
}

TerminalEventInspector reports whether an extension manager has handlers for a terminal event.

type TerminalEventResult 

type TerminalEventResult struct {
	Buffers        map[string]BufferState `json:"buffers"`
	Windows        map[string]WindowState `json:"windows"`
	Layout         *LayoutState           `json:"layout,omitempty"`
	UICursor       *UICursor              `json:"ui_cursor,omitempty"`
	Actions        []ActionCall           `json:"actions"`
	UIDrawOps      []UIDrawOp             `json:"ui_draw_ops"`
	ResetUIWindows []string               `json:"reset_ui_windows"`
	DeletedBuffers []string               `json:"deleted_buffers"`
	DeletedWindows []string               `json:"deleted_windows"`
	Consumed       bool                   `json:"consumed"`
}

TerminalEventResult describes mutations produced by low-level extension handlers.

type TerminalEventRunner 

type TerminalEventRunner interface {
	HandleTerminalEvent(ctx context.Context, event *TerminalEvent) (TerminalEventResult, error)
}

TerminalEventRunner executes low-level terminal runtime event handlers.

type TimerScheduler 

type TimerScheduler interface {
	NextTimerDelay(now time.Time) (time.Duration, bool)
}

TimerScheduler reports when extension timers should wake the host loop.

type Tool 

type Tool struct {
	InputSchema map[string]any `json:"input_schema"`
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Extension   string         `json:"extension"`
}

Tool describes an extension-provided tool callable by the runtime.

type ToolCallMutation 

type ToolCallMutation struct {
	Arguments map[string]any `json:"arguments"`
}

ToolCallMutation contains tool call argument changes returned by lifecycle handlers.

type ToolResult 

type ToolResult struct {
	Details map[string]any `json:"details"`
	Content string         `json:"content"`
}

ToolResult is returned from Lua tool handlers.

type ToolResultMutation 

type ToolResultMutation struct {
	Result      *string `json:"result,omitempty"`
	DetailsJSON *string `json:"details_json,omitempty"`
	Error       *string `json:"error,omitempty"`
}

ToolResultMutation contains tool result changes returned by lifecycle handlers.

type UICursor 

type UICursor struct {
	Window string `json:"window"`
	Row    int    `json:"row"`
	Col    int    `json:"col"`
}

UICursor requests a cursor position relative to a window.

type UIDrawOp 

type UIDrawOp struct {
	Window string   `json:"window"`
	Kind   string   `json:"kind"`
	Text   string   `json:"text"`
	Style  UIStyle  `json:"style"`
	Spans  []UISpan `json:"spans"`
	Row    int      `json:"row"`
	Col    int      `json:"col"`
	Width  int      `json:"width"`
	Height int      `json:"height"`
	Clear  bool     `json:"clear"`
}

UIDrawOp describes one low-level window-relative drawing operation.

type UISpan 

type UISpan struct {
	Text  string  `json:"text"`
	Style UIStyle `json:"style"`
}

UISpan describes one styled inline segment for extension-driven draw operations.

type UIStyle 

type UIStyle struct {
	FG     string `json:"fg"`
	BG     string `json:"bg"`
	Bold   bool   `json:"bold"`
	Italic bool   `json:"italic"`
}

UIStyle describes minimal low-level styling for extension-driven draw operations.

type WindowState 

type WindowState struct {
	Metadata  map[string]any `json:"metadata"`
	Name      string         `json:"name"`
	Role      string         `json:"role"`
	Buffer    string         `json:"buffer"`
	Renderer  string         `json:"renderer"`
	X         int            `json:"x"`
	Y         int            `json:"y"`
	Width     int            `json:"width"`
	Height    int            `json:"height"`
	CursorRow int            `json:"cursor_row"`
	CursorCol int            `json:"cursor_col"`
	Visible   bool           `json:"visible"`
}

WindowState describes an extension-visible window or viewport.

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.