Documentation
¶
Overview ¶
Package extension defines the contract every pig extension speaks. It mirrors upstream pi's ExtensionAPI surface 1:1 so a TS extension can be ported to Go almost line-for-line, and so each upstream version bump is an additive diff rather than a structural one.
Source of truth:
.upstream/current/packages/coding-agent/src/core/extensions/types.ts
This package contains only the public API contract: types, the fat API interface, and the Extension author-facing interface. Hosts (the inproc dispatch runner and subprocess transport adapter) live under coding/extension/host/ and depend on this package, never the reverse.
Faithfulness rules ¶
- Method order on the API interface matches upstream ExtensionAPI declaration order. Section dividers mirror upstream comments.
- Every field on every event struct carries a json:"camelCaseName" tag matching upstream's TS field name. The parity gates in test/upstream-parity/ enforce this on every CI run.
- Field names use idiomatic Go casing with terminal initialism uplift (Id→ID, Url→URL, Api→API, Json→JSON). For example, upstream `toolCallId` becomes Go `ToolCallID`. The parity reflection check uses [parity.CamelToGoField] which knows the closed initialism set; extending it requires a coordinated update to that helper plus a docs/parity/DIVERGENCES.md U1 sync-ritual entry.
- Observable differences use a numbered source marker and ledger record.
Opaque compatibility types ¶
Upstream references many domain types (AgentMessage, Model, CompactionEntry, AbortSignal, Component, etc.) that don't yet have concrete Go equivalents in PiG. Types that cross the current dynamic JSON or renderer boundaries are explicit opaque aliases in opaque_types.go. Concrete events and SDK methods use typed Go values where the contract is stable.
Shell command execution for extensions.
Mirrors upstream core/exec.ts. Provides the implementation backing extension.API.Exec: a simple process spawn with timeout and abort support.
upstream: coding-agent/src/core/exec.ts (107 LOC)
Index ¶
- Constants
- Variables
- func BeforeAgentStartSelectedTools(ctx context.Context) json.RawMessage
- func CallInitiated(ctx context.Context)
- func ErrorStack(err error) string
- func MarshalInputEventResult(r InputEventResult) ([]byte, error)
- func MarshalToolCallEvent(e ToolCallEvent) ([]byte, error)
- func MarshalToolResultEvent(e ToolResultEvent) ([]byte, error)
- func ModelInfo(model *ai.Model) map[string]any
- func NodeTimerDelay(ms float64) time.Duration
- func ProviderStreamSimpleSelected(ctx context.Context) bool
- func ResolveBeforeAgentStartSelectedTools(ctx context.Context, before []string) ([]string, bool, error)
- func SetBeforeAgentStartSelectedTools(ctx context.Context, raw json.RawMessage)
- func ToolResultDetailsFor(details any) any
- func WithBeforeAgentStartOptions(ctx context.Context, options *BuildSystemPromptOptions) context.Context
- func WithCallInitiation(ctx context.Context, mark func()) context.Context
- func WithCommandContext(ctx context.Context, cc *CommandContext) context.Context
- func WithContext(parent context.Context, c *Context) context.Context
- func WithModelStreamRequest(ctx context.Context, request ModelStreamRequest) context.Context
- func WithProviderStreamSimple(ctx context.Context, simple bool) context.Context
- type AIContext
- type API
- type AbortSignaldeprecated
- type AfterProviderResponseEvent
- type AgentActivityOutcome
- type AgentBeforeSettleEvent
- type AgentBeforeSettleEventResult
- type AgentEndEvent
- type AgentMessage
- type AgentSettledEvent
- type AgentStartEvent
- type AgentToolResult
- type AgentToolUpdateCallback
- type ArgumentCompletionsFunc
- type AssistantMessageEvent
- type AssistantMessageEventStream
- type AttributedResourcePath
- type AutocompleteCompletion
- type AutocompleteItem
- type AutocompleteProvider
- type AutocompleteProviderFactory
- type AutocompleteSuggestions
- type BashOperations
- type BashOperationsExecOptions
- type BashOperationsResult
- type BashResult
- type BashToolCallEvent
- type BashToolDetails
- type BashToolInput
- type BashToolResultEvent
- type BeforeAgentStartCombinedResult
- type BeforeAgentStartEvent
- type BeforeAgentStartEventResult
- type BeforeProviderHeadersEvent
- type BeforeProviderRequestEvent
- type BeforeProviderRequestEventResult
- type BoundaryBaseEvent
- type BoundaryContextPreview
- type BoundaryResult
- type BoundaryState
- type BranchSummaryEntry
- type BuildSystemPromptOptions
- type CacheWarmingAction
- type CacheWarmingDecisionEvent
- type CacheWarmingDecisionEventResult
- type CancelledResult
- type Capability
- type CommandActions
- type CommandContext
- func (c *CommandContext) Fork(entryID string, opts *ForkOptions) (CancelledResult, error)
- func (c *CommandContext) GetSystemPromptOptions() (*BuildSystemPromptOptions, error)
- func (c *CommandContext) NavigateTree(targetID string, opts *NavigateTreeOptions) (CancelledResult, error)
- func (c *CommandContext) NewSession(opts *NewSessionOptions) (CancelledResult, error)
- func (c *CommandContext) Reload() error
- func (c *CommandContext) SwitchSession(sessionPath string, opts *SwitchSessionOptions) (CancelledResult, error)
- func (c *CommandContext) WaitForIdle() error
- type CommandHandler
- type CommandOptions
- type CompactOptions
- type CompactionEntry
- type CompactionPreparation
- type CompactionResult
- type Component
- type Context
- func (c *Context) Abort() error
- func (c *Context) CWD() (string, error)
- func (c *Context) Compact(opts *CompactOptions) error
- func (c *Context) GetActiveTools() []string
- func (c *Context) GetAllTools() []ToolInfo
- func (c *Context) GetContextUsage() (*ContextUsage, error)
- func (c *Context) GetFlagValue(name string) any
- func (c *Context) GetSystemPrompt() (string, error)
- func (c *Context) HasPendingMessages() (bool, error)
- func (c *Context) HasUI() (bool, error)
- func (c *Context) IsIdle() (bool, error)
- func (c *Context) IsProjectTrusted() (bool, error)
- func (c *Context) Mode() (ExtensionMode, error)
- func (c *Context) Model() (Model, error)
- func (c *Context) ModelRegistry() (ModelRegistry, error)
- func (c *Context) ScopedModels() ([]ScopedModel, error)
- func (c *Context) SendUserMessage(content any, opts *SendUserMessageOptions) error
- func (c *Context) SessionManager() (SessionManager, error)
- func (c *Context) SetActiveTools(names []string)
- func (c *Context) Shutdown() error
- func (c *Context) UI() (UIContext, error)
- type ContextActions
- type ContextEvent
- type ContextEventResult
- type ContextUsage
- type ContextWithSystemEvent
- type CustomEntry
- type CustomMessage
- type CustomMessageRef
- type CustomToolCallEvent
- type CustomToolResultEvent
- type DeliverAs
- type DialogInitiationReporter
- type EditToolCallEvent
- type EditToolDetails
- type EditToolInput
- type EditToolResultEvent
- type EditorComponent
- type EditorTheme
- type EntryRenderOptions
- type EntryRenderer
- type ErrorListener
- type EventBus
- type ExecOptions
- type ExecResult
- type Extension
- func (e *Extension) AddEventHandler(event string, id int, handler HandlerFn)
- func (e *Extension) EventHandlers(event string) []HandlerFn
- func (e *Extension) InitializeEventHandlers()
- func (e *Extension) InitializeToolRegistry()
- func (e *Extension) RegisteredTool(name string) (RegisteredTool, bool)
- func (e *Extension) RegisteredTools() []RegisteredTool
- func (e *Extension) RemoveEventHandler(event string, id int)
- func (e *Extension) ReplaceEventHandlers(source *Extension)
- func (e *Extension) ReplaceRegisteredTools(source *Extension)
- func (e *Extension) SetRegisteredTool(tool RegisteredTool)
- type ExtensionActions
- type ExtensionError
- type ExtensionFlag
- type ExtensionMode
- type ExtensionRuntime
- func (r *ExtensionRuntime) BindProviderActions(actions ProviderActions, report func(*ExtensionError))
- func (r *ExtensionRuntime) PendingProviderRegistrations() []PendingProviderRegistration
- func (r *ExtensionRuntime) RegisterProvider(name string, config ProviderConfig, extensionPath ...string) error
- func (r *ExtensionRuntime) UnregisterProvider(name string)
- type ExtensionShortcut
- type ExtensionUIDialogOptions
- type ExtensionWidgetOptions
- type FindToolCallEvent
- type FindToolDetails
- type FindToolInput
- type FindToolResultEvent
- type FlagOptions
- type FlagType
- type ForkOptions
- type GrepToolCallEvent
- type GrepToolDetails
- type GrepToolInput
- type GrepToolResultEvent
- type HandlerFn
- type ImageContent
- type InputEvent
- type InputEventResult
- type InputEventResultContinue
- type InputEventResultHandled
- type InputEventResultTransform
- type InputSource
- type KeyID
- type KeybindingsManager
- type LoginDefinition
- type LoginDefinitionError
- type LsToolCallEvent
- type LsToolDetails
- type LsToolInput
- type LsToolResultEvent
- type MarkdownMessageType
- type MarkdownTransformContext
- type MarkdownTransformer
- type MessageEndEvent
- type MessageEndEventResult
- type MessageRenderOptions
- type MessageRenderer
- type MessageStartEvent
- type MessageUpdateEvent
- type Model
- type ModelRegistry
- type ModelSelectEvent
- type ModelSelectSource
- type ModelStreamRequest
- type NativeProvider
- type NativeProviderPublication
- type NavigateTreeOptions
- type NewSessionOptions
- type OAuthCredentials
- type OAuthLoginCallbacks
- type OverlayHandle
- type OverlayLayout
- type OverlayMarginValue
- type OverlayOptions
- type OverlaySizeValue
- type PendingProviderRegistration
- type PowerShellToolCallEvent
- type PowerShellToolDetails
- type PowerShellToolInput
- type PowerShellToolResultEvent
- type ProjectTrustEvent
- type ProjectTrustEventDecision
- type ProjectTrustEventResult
- type ProjectedSessionEntry
- type ProviderActions
- type ProviderConfig
- type ProviderHeaders
- type ProviderModelConfig
- type ProviderModelCost
- type ProviderOAuth
- type ProviderStreamSimple
- type ReadToolCallEvent
- type ReadToolDetails
- type ReadToolInput
- type ReadToolResultEvent
- type ReadonlyFooterDataProvider
- type ReadonlySessionManager
- type RegisteredCommand
- type RegisteredTool
- type RemoteEditor
- type RemoteEditorAction
- type RemoteEditorConfig
- type RemoteEditorHost
- type RemoteEditorMouseEvent
- type RemoteOverlayBounds
- type RemoteOverlayFocusTarget
- type RemoteOverlayHandle
- type RemoteOverlayHost
- type RemoteOverlayOptions
- type RemoteOverlayState
- type RemoteTerminalInputHandler
- type ReplacedSessionContext
- type ReplacedSessionSendUserMessageOptions
- type ResolvedCommand
- type ResourceCollision
- type ResourceDiagnostic
- type ResourcesDiscoverAggregateResult
- type ResourcesDiscoverEvent
- type ResourcesDiscoverResult
- type ScopedModel
- type SendMessageOptions
- type SendMessagePayload
- type SendUserMessageHandler
- type SendUserMessageOptions
- type SessionBeforeCompactEvent
- type SessionBeforeCompactResult
- type SessionBeforeForkEvent
- type SessionBeforeForkResult
- type SessionBeforeSwitchEvent
- type SessionBeforeSwitchResult
- type SessionBeforeTreeEvent
- type SessionBeforeTreeResult
- type SessionBeforeTreeResultSummary
- type SessionBoundaryDraft
- type SessionCompactEvent
- type SessionCompactFailedEvent
- type SessionEntry
- type SessionInfoChangedEvent
- type SessionManager
- type SessionShutdownEvent
- type SessionStartEvent
- type SessionTreeEvent
- type SetThemeResult
- type ShortcutHandler
- type ShortcutOptions
- type SimpleStreamOptions
- type SlashCommandInfo
- type SourceInfo
- type StackError
- type SwitchSessionOptions
- type SystemPromptContextFile
- type SystemPromptSkill
- type TUI
- type TerminalInputHandler
- type TerminalInputResult
- type TextContent
- type Theme
- type ThemeMeta
- type ThinkingLevel
- type ThinkingLevelSelectEvent
- type ToolCallEvent
- type ToolCallEventBase
- type ToolCallEventResult
- type ToolDefinition
- type ToolDetailsConverter
- type ToolExecuteFunc
- type ToolExecutionEndEvent
- type ToolExecutionMode
- type ToolExecutionStartEvent
- type ToolExecutionUpdateEvent
- type ToolInfo
- type ToolPrepareArgumentsFunc
- type ToolRenderCallFunc
- type ToolRenderContext
- type ToolRenderResultFunc
- type ToolRenderResultOptions
- type ToolRenderShell
- type ToolResultEvent
- type ToolResultEventBase
- type ToolResultEventResult
- type ToolResultMessage
- type ToolTruncation
- type TreePreparation
- type TurnEndEvent
- type TurnStartEvent
- type UIContext
- type UIPromptEndEvent
- type UIPromptKind
- type UIPromptStartEvent
- type UserBashEvent
- type UserBashEventResult
- type ValidatedLoginDefinition
- func (d ValidatedLoginDefinition) Brand() []string
- func (d ValidatedLoginDefinition) Color(symbol byte) (color.RGBA, bool)
- func (d ValidatedLoginDefinition) Description() string
- func (d ValidatedLoginDefinition) Hero() []string
- func (d ValidatedLoginDefinition) Mascot() []string
- func (d ValidatedLoginDefinition) Name() string
- func (d ValidatedLoginDefinition) Tagline() string
- type WidthLines
- type WorkingIndicatorOptions
- type WriteToolCallEvent
- type WriteToolInput
- type WriteToolResultEvent
Constants ¶
const ( DiagnosticWarning = "warning" DiagnosticError = "error" DiagnosticCollision = "collision" )
Diagnostic type constants matching upstream's literal union.
const ( LoginBrandWidth = 41 LoginBrandHeight = 5 LoginHeroWidth = 32 LoginHeroHeight = 14 LoginMascotWidth = 16 LoginMascotHeight = 14 LoginPaletteLimit = 32 LoginNameWidthLimit = 24 LoginDescriptionWidthLimit = 48 LoginTaglineWidthLimit = 76 LoginMetadataWidthLimit = 80 )
pig additive (D60): Pig validates a typed login definition because subprocess extensions cannot pass Pi's live TUI component factories.
Variables ¶
var ( // ErrStaleContext is returned by API calls made through an // ExtensionContext whose runner has been replaced (typically after // /reload or a session swap). Mirrors upstream's invalidate() sentinel // in core/extensions/runner.ts. ErrStaleContext = errors.New("extension: context is stale (runner replaced)") // ErrBusy is returned when an action is rejected because the agent is // streaming or compacting. Mirrors upstream's reload guard in // modes/interactive/interactive-mode.ts handleReloadCommand. ErrBusy = errors.New("extension: agent is busy (streaming or compacting)") // ErrCapabilityNotDeclared is returned when an extension calls an API // surface it didn't declare in its manifest capabilities list. ErrCapabilityNotDeclared = errors.New("extension: capability not declared in manifest") // ErrUnknownEvent is returned when a host attempts to dispatch an event // name that no registered handler understands. Hosts may treat this as // an info-level no-op; it exists for tests and diagnostics. ErrUnknownEvent = errors.New("extension: unknown event") )
Sentinel errors surfaced by extension hosts (the inproc dispatch runner and subprocess transport adapter) to extensions. Authors compare with errors.Is.
var ErrHandlerStopped = errors.New("extension handler stopped by the host")
ErrHandlerStopped marks a handler call the host itself cut short: it stopped the extension (shutdown, a termination signal, /reload) or cancelled the dispatch. The handler did not fail, so runners do not report it as an ExtensionError. Upstream never interrupts a running handler; its signal path disposes the runtime and exits without reporting the interrupted work.
ErrUIUnavailable reports that a UI-only operation cannot run in the current mode.
Functions ¶
func BeforeAgentStartSelectedTools ¶
func BeforeAgentStartSelectedTools(ctx context.Context) json.RawMessage
BeforeAgentStartSelectedTools returns the current wire value, retaining untyped edits until prompt admission. A native collection replacement supersedes the preceding wire value.
func CallInitiated ¶
CallInitiated reports that the call carried by ctx has applied its synchronous part. It is a no-op without a mark and safe to call repeatedly when the mark is idempotent.
func ErrorStack ¶
ErrorStack returns the stack carried by err or an error it wraps, or "". Runners use it for ExtensionError.Stack: upstream reports the handler's `err.stack`, never the host's own dispatch stack.
func MarshalInputEventResult ¶
func MarshalInputEventResult(r InputEventResult) ([]byte, error)
MarshalInputEventResult serialises a sealed-interface variant to upstream wire shape with the `action` discriminator.
Why a free function not a method on the interface: defining a marshal method on the interface would force every variant to implement it (verbose); using a free function keeps marker structs trivial. Hosts dispatching events call this; authors returning a value from OnInput have their value passed through this helper by the runtime.
func MarshalToolCallEvent ¶
func MarshalToolCallEvent(e ToolCallEvent) ([]byte, error)
MarshalToolCallEvent serialises any of the nine ToolCallEvent variants. Each variant struct already declares upstream-faithful JSON tags; this helper only narrows the interface to a concrete value before marshalling.
func MarshalToolResultEvent ¶
func MarshalToolResultEvent(e ToolResultEvent) ([]byte, error)
MarshalToolResultEvent serialises any of the nine ToolResultEvent variants. Symmetric with MarshalToolCallEvent.
func ModelInfo ¶
ModelInfo projects one composed model into the complete extension-facing Pi Model shape.
func NodeTimerDelay ¶
NodeTimerDelay is the delay Node gives setTimeout(fn, ms): it truncates a fractional value and runs a delay outside [1, 2^31-1], or NaN, after one millisecond.
func ResolveBeforeAgentStartSelectedTools ¶
func ResolveBeforeAgentStartSelectedTools(ctx context.Context, before []string) ([]string, bool, error)
ResolveBeforeAgentStartSelectedTools compares the final selection before filtering non-string registry misses, as AgentSession.prompt does. Invalid lists reject prompt admission after every handler has had a chance to repair them.
func SetBeforeAgentStartSelectedTools ¶
func SetBeforeAgentStartSelectedTools(ctx context.Context, raw json.RawMessage)
SetBeforeAgentStartSelectedTools retains the complete foreign value for later handlers. Only string entries can name registered Go tools; malformed selections are rejected after the handler chain, not swallowed as handler failures.
func ToolResultDetailsFor ¶
ToolResultDetailsFor converts a tool result's Details to its SDK wire shape when the value implements ToolDetailsConverter; other details (custom-tool JSON, the already-SDK-shaped edit details, or nil) pass through unchanged.
func WithBeforeAgentStartOptions ¶
func WithBeforeAgentStartOptions(ctx context.Context, options *BuildSystemPromptOptions) context.Context
WithBeforeAgentStartOptions attaches the shared per-run options to a handler dispatch. Hosts use this without changing the value-typed BeforeAgentStartEvent.SystemPromptOptions API.
func WithCallInitiation ¶
WithCallInitiation returns ctx carrying mark, which the handler of a Promise-shaped call runs once its synchronous part has been applied.
func WithCommandContext ¶
func WithCommandContext(ctx context.Context, cc *CommandContext) context.Context
WithCommandContext attaches a CommandContext to a context.Context.
func WithContext ¶
WithContext attaches a per-extension Context to a context.Context. Hosts call this once at event-dispatch time; the resulting context.Context is then threaded through to extension handlers.
Authors do not call WithContext directly.
func WithModelStreamRequest ¶
func WithModelStreamRequest(ctx context.Context, request ModelStreamRequest) context.Context
WithModelStreamRequest binds transport callbacks to one model operation.
Types ¶
type AIContext ¶
type AIContext = any
AIContext mirrors @earendil-works/pi-ai Context (the per-call provider context, distinct from pig's ExtensionContext).
type API ¶
type API interface {
// OnProjectTrust registers a handler for "project_trust".
// upstream: types.ts:1125 (on("project_trust", ...))
OnProjectTrust(handler func(ctx context.Context, evt ProjectTrustEvent) (ProjectTrustEventResult, error))
// OnResourcesDiscover registers a handler for "resources_discover".
// upstream: types.ts:1071
OnResourcesDiscover(handler func(ctx context.Context, evt ResourcesDiscoverEvent) (ResourcesDiscoverResult, error))
// OnSessionStart registers a handler for "session_start".
// upstream: types.ts:1143
OnSessionStart(handler func(ctx context.Context, evt SessionStartEvent) error)
// OnSessionInfoChanged registers a handler for "session_info_changed"
// (upstream types.ts SessionInfoChangedEvent; adopted upstream in 0.80.3).
OnSessionInfoChanged(handler func(ctx context.Context, evt SessionInfoChangedEvent) error)
// OnSessionBeforeSwitch registers a handler for "session_before_switch".
// upstream: types.ts:1145
OnSessionBeforeSwitch(handler func(ctx context.Context, evt SessionBeforeSwitchEvent) (SessionBeforeSwitchResult, error))
// OnSessionBeforeFork registers a handler for "session_before_fork".
// upstream: types.ts:1077
OnSessionBeforeFork(handler func(ctx context.Context, evt SessionBeforeForkEvent) (SessionBeforeForkResult, error))
// OnSessionBeforeCompact registers a handler for "session_before_compact".
// upstream: types.ts:1078
OnSessionBeforeCompact(handler func(ctx context.Context, evt SessionBeforeCompactEvent) (SessionBeforeCompactResult, error))
// OnSessionCompact registers a handler for "session_compact".
// upstream: types.ts:1082
OnSessionCompact(handler func(ctx context.Context, evt SessionCompactEvent) error)
// OnSessionCompactFailed registers a handler for "session_compact_failed",
// fired after manual or automatic compaction fails or is aborted.
// upstream: types.ts:1374
OnSessionCompactFailed(handler func(ctx context.Context, evt SessionCompactFailedEvent) error)
// OnSessionShutdown registers a handler for "session_shutdown".
// upstream: types.ts:1083
OnSessionShutdown(handler func(ctx context.Context, evt SessionShutdownEvent) error)
// OnSessionBeforeTree registers a handler for "session_before_tree".
// upstream: types.ts:1084
OnSessionBeforeTree(handler func(ctx context.Context, evt SessionBeforeTreeEvent) (SessionBeforeTreeResult, error))
// OnSessionTree registers a handler for "session_tree".
// upstream: types.ts:1085
OnSessionTree(handler func(ctx context.Context, evt SessionTreeEvent) error)
// OnContext registers a handler for "context".
// upstream: types.ts:1086
OnContext(handler func(ctx context.Context, evt ContextEvent) (ContextEventResult, error))
// OnContextWithSystem registers a handler for "context_with_system".
// upstream: types.ts ExtensionAPI.on("context_with_system")
OnContextWithSystem(handler func(ctx context.Context, evt ContextWithSystemEvent) (ContextEventResult, error))
// OnBeforeProviderRequest registers a handler for "before_provider_request".
// upstream: types.ts:1087
OnBeforeProviderRequest(handler func(ctx context.Context, evt BeforeProviderRequestEvent) (BeforeProviderRequestEventResult, error))
// OnAfterProviderResponse registers a handler for "after_provider_response".
// upstream: types.ts:1091
OnAfterProviderResponse(handler func(ctx context.Context, evt AfterProviderResponseEvent) error)
// OnBeforeProviderHeaders registers a handler for "before_provider_headers".
// Handlers mutate evt.Headers in place before the request is sent.
// upstream: types.ts:1199
OnBeforeProviderHeaders(handler func(ctx context.Context, evt BeforeProviderHeadersEvent) error)
// OnBeforeAgentStart registers a handler for "before_agent_start".
// upstream: types.ts:1092
OnBeforeAgentStart(handler func(ctx context.Context, evt BeforeAgentStartEvent) (BeforeAgentStartEventResult, error))
// OnAgentStart registers a handler for "agent_start".
// upstream: types.ts:1093
OnAgentStart(handler func(ctx context.Context, evt AgentStartEvent) error)
// OnAgentEnd registers a handler for "agent_end".
// upstream: types.ts:1399
OnAgentEnd(handler func(ctx context.Context, evt AgentEndEvent) error)
// OnAgentBeforeSettle registers an awaited final-settlement boundary handler.
// Handlers may propose durable entries and request one runnable continuation.
// upstream: types.ts:1401
OnAgentBeforeSettle(handler func(ctx context.Context, evt *AgentBeforeSettleEvent) (AgentBeforeSettleEventResult, error))
// OnAgentSettled registers a handler for "agent_settled", fired after an
// agent run has fully settled (no retry, compaction, or queued continuation).
// upstream: types.ts:1204
OnAgentSettled(handler func(ctx context.Context, evt AgentSettledEvent) error)
// OnUiPromptStart registers a handler for "ui_prompt_start", fired
// without awaiting handlers when the outermost blocking ctx.ui prompt
// (select, confirm, input, editor, custom) begins.
// upstream: types.ts:1404
OnUiPromptStart(handler func(ctx context.Context, evt UIPromptStartEvent) error)
// OnUiPromptEnd registers a handler for "ui_prompt_end", fired without
// awaiting handlers when the outermost blocking ctx.ui prompt settles.
// upstream: types.ts:1405
OnUiPromptEnd(handler func(ctx context.Context, evt UIPromptEndEvent) error)
// OnTurnStart registers a handler for "turn_start".
// upstream: types.ts:1095
OnTurnStart(handler func(ctx context.Context, evt TurnStartEvent) error)
// OnTurnEnd registers a handler for "turn_end".
// upstream: types.ts:1096
OnTurnEnd(handler func(ctx context.Context, evt TurnEndEvent) error)
// OnMessageStart registers a handler for "message_start".
// upstream: types.ts:1097
OnMessageStart(handler func(ctx context.Context, evt MessageStartEvent) error)
// OnMessageUpdate registers a handler for "message_update".
// upstream: types.ts:1098
OnMessageUpdate(handler func(ctx context.Context, evt MessageUpdateEvent) error)
// OnMessageEnd registers a handler for "message_end".
// upstream: types.ts:1099
OnMessageEnd(handler func(ctx context.Context, evt MessageEndEvent) (MessageEndEventResult, error))
// OnToolExecutionStart registers a handler for "tool_execution_start".
// upstream: types.ts:1100
OnToolExecutionStart(handler func(ctx context.Context, evt ToolExecutionStartEvent) error)
// OnToolExecutionUpdate registers a handler for "tool_execution_update".
// upstream: types.ts:1101
OnToolExecutionUpdate(handler func(ctx context.Context, evt ToolExecutionUpdateEvent) error)
// OnToolExecutionEnd registers a handler for "tool_execution_end".
// upstream: types.ts:1102
OnToolExecutionEnd(handler func(ctx context.Context, evt ToolExecutionEndEvent) error)
// OnModelSelect registers a handler for "model_select".
// upstream: types.ts:1103
OnModelSelect(handler func(ctx context.Context, evt ModelSelectEvent) error)
// OnThinkingLevelSelect registers a handler for "thinking_level_select".
// upstream: types.ts:1122 (added in v0.71.0).
OnThinkingLevelSelect(handler func(ctx context.Context, evt ThinkingLevelSelectEvent) error)
// OnToolCall registers a handler for "tool_call". The event is the union
// [ToolCallEvent]. Type-switch on its concrete variant.
// upstream: types.ts:1104
OnToolCall(handler func(ctx context.Context, evt ToolCallEvent) (ToolCallEventResult, error))
// OnToolResult registers a handler for "tool_result". The event is the
// union [ToolResultEvent].
// upstream: types.ts:1105
OnToolResult(handler func(ctx context.Context, evt ToolResultEvent) (ToolResultEventResult, error))
// OnUserBash registers a handler for "user_bash".
// upstream: types.ts:1106
OnUserBash(handler func(ctx context.Context, evt UserBashEvent) (UserBashEventResult, error))
// OnInput registers a handler for "input".
// upstream: types.ts:1107
OnInput(handler func(ctx context.Context, evt InputEvent) (InputEventResult, error))
// RegisterTool registers a tool that the LLM can call.
// upstream: types.ts:1114 (registerTool)
RegisterTool(tool ToolDefinition)
// RegisterCommand registers a custom command. Mirrors upstream's
// `registerCommand(name, options: Omit<RegisteredCommand, "name" | "sourceInfo">)`.
// upstream: types.ts:1123
RegisterCommand(name string, options CommandOptions)
// RegisterShortcut registers a keyboard shortcut.
// upstream: types.ts:1126
RegisterShortcut(shortcut KeyID, options ShortcutOptions)
// RegisterFlag registers a CLI flag.
// upstream: types.ts:1135
RegisterFlag(name string, options FlagOptions)
// GetFlag returns the value of a registered CLI flag. Upstream returns
// `boolean | string | undefined`; Go returns `any` (nil when unset).
// upstream: types.ts:1145
GetFlag(name string) any
// RegisterMessageRenderer registers a custom renderer for a CustomMessageEntry.
// upstream: types.ts:1152
RegisterMessageRenderer(customType string, renderer MessageRenderer)
// RegisterEntryRenderer registers a custom renderer for a CustomEntry. Custom
// entries do not participate in LLM context.
// upstream: types.ts:1266
RegisterEntryRenderer(customType string, renderer EntryRenderer)
// RegisterMarkdownTransformer registers a display-only Markdown transform.
// upstream: types.ts:1287
RegisterMarkdownTransformer(transformer MarkdownTransformer)
// SendMessage sends a custom message to the session. Pass nil options for defaults.
// upstream: types.ts:1159
SendMessage(message SendMessagePayload, options *SendMessageOptions)
// SendUserMessage sends a user message to the agent. Always triggers a turn.
// content is `string` or `[]any` carrying TextContent / ImageContent values
// (matches upstream's `string | (TextContent | ImageContent)[]`).
// upstream: types.ts:1168
SendUserMessage(content any, options *SendUserMessageOptions)
// AppendEntry appends a custom entry to the session for state persistence
// (not sent to LLM).
// upstream: types.ts:1174
AppendEntry(customType string, data any)
// SetSessionName sets the session display name (shown in session selector).
// upstream: types.ts:1181
SetSessionName(name string)
// GetSessionName returns the current session name. Upstream returns
// `string | undefined`; Go returns the empty string when unset.
// upstream: types.ts:1184
GetSessionName() string
// SetLabel sets or clears a label on an entry. Pass empty string to clear.
// upstream: types.ts:1187
SetLabel(entryID string, label string)
// Exec executes a shell command. Pass nil options for defaults. Upstream
// returns `Promise<ExecResult>`; Go returns `(ExecResult, error)`.
// Cancellation flows through `options.Signal` (which is a context.Context
// after the D3 migration; see docs/parity/DIVERGENCES.md).
// upstream: types.ts:1190
Exec(command string, args []string, options *ExecOptions) (ExecResult, error)
// GetActiveTools returns the list of currently active tool names.
// upstream: types.ts:1193
GetActiveTools() []string
// GetAllTools returns all configured tools with parameter schema and source metadata.
// upstream: types.ts:1196
GetAllTools() []ToolInfo
// SetActiveTools sets the active tools by name.
// upstream: types.ts:1199
SetActiveTools(toolNames []string)
// GetCommands returns the available slash commands in the current session.
// upstream: types.ts:1202
GetCommands() []SlashCommandInfo
// SetModel sets the current model. Upstream returns
// `Promise<boolean>` (false when no API key available); Go returns
// `(bool, error)`: error is non-nil only on host-side failures.
// upstream: types.ts:1209
SetModel(model Model) (bool, error)
// GetThinkingLevel returns the current thinking level.
// upstream: types.ts:1212
GetThinkingLevel() ThinkingLevel
// SetThinkingLevel sets the thinking level (clamped to model capabilities).
// upstream: types.ts:1215
SetThinkingLevel(level ThinkingLevel)
// RegisterProvider registers or overrides a model provider. See [ProviderConfig]
// for the field-level semantics (upstream JSDoc preserved).
// upstream: types.ts:1264
RegisterProvider(name string, config ProviderConfig)
// UnregisterProvider unregisters a previously registered provider. Has
// no effect if the provider is not currently registered.
// upstream: types.ts:1280
UnregisterProvider(name string)
// Events returns the shared event bus for extension communication.
//
// pig translation rule (interface property → method): upstream exposes
// this as the property `events: EventBus`. Go interfaces cannot have
// fields, so the API surfaces a method that returns the host's single
// shared instance. See docs/parity/DIVERGENCES.md "TS→Go translation rituals".
// upstream: types.ts:1283
Events() EventBus
}
API is the surface passed to extension factory functions. It mirrors upstream's `ExtensionAPI` interface 1:1: every event registrable via upstream's `pi.on(event, handler)` overload has a typed `On<Event>` method here, every other method on `ExtensionAPI` has a Go counterpart (camelCase → PascalCase), and the upstream `events: EventBus` property surfaces as the API.Events method.
Method order matches upstream declaration order so a side-by-side review against types.ts is mechanical. Every method's doc comment cites its upstream line in `types.ts`.
Go mapping:
- Events is a method because Go interfaces cannot contain fields.
- Handlers receive context.Context and return errors.
upstream: types.ts:1066–1296
type AbortSignal
deprecated
AbortSignal was the upstream cancellation primitive (DOM AbortSignal). Pig uses context.Context for cancellation (see docs/parity/DIVERGENCES.md D3). This deprecated alias preserves source compatibility while giving callers the real cancellation contract instead of an untyped value.
Deprecated: use context.Context.
type AfterProviderResponseEvent ¶
type AfterProviderResponseEvent struct {
Type string `json:"type"`
Status int `json:"status"`
Headers map[string]string `json:"headers"`
}
AfterProviderResponseEvent: upstream types.ts AfterProviderResponseEvent.
type AgentActivityOutcome ¶
type AgentActivityOutcome string
AgentActivityOutcome mirrors upstream's completed/aborted/error boundary state.
const ( AgentActivityCompleted AgentActivityOutcome = "completed" AgentActivityAborted AgentActivityOutcome = "aborted" AgentActivityError AgentActivityOutcome = "error" )
type AgentBeforeSettleEvent ¶
type AgentBeforeSettleEvent struct {
Type string `json:"type"`
BoundaryState
}
AgentBeforeSettleEvent: upstream types.ts AgentBeforeSettleEvent. It is awaited after retry, recovery, compaction, and queued continuations stop.
type AgentBeforeSettleEventResult ¶
type AgentBeforeSettleEventResult = BoundaryResult
AgentBeforeSettleEventResult mirrors upstream's BoundaryResult alias.
type AgentEndEvent ¶
type AgentEndEvent struct {
Type string `json:"type"`
Messages []AgentMessage `json:"messages"`
}
AgentEndEvent: upstream types.ts AgentEndEvent.
type AgentMessage ¶
type AgentMessage = any
AgentMessage mirrors @earendil-works/pi-agent-core AgentMessage.
type AgentSettledEvent ¶
type AgentSettledEvent struct {
Type string `json:"type"`
}
AgentSettledEvent: upstream types.ts AgentSettledEvent. Fired after an agent run has fully settled and no automatic retry, compaction, or queued continuation will run.
type AgentStartEvent ¶
type AgentStartEvent struct {
Type string `json:"type"`
}
AgentStartEvent: upstream types.ts AgentStartEvent.
type AgentToolResult ¶
type AgentToolResult = any
AgentToolResult mirrors @earendil-works/pi-agent-core AgentToolResult<TDetails>.
type AgentToolUpdateCallback ¶
type AgentToolUpdateCallback = any
AgentToolUpdateCallback mirrors AgentToolUpdateCallback<TDetails>.
type ArgumentCompletionsFunc ¶
type ArgumentCompletionsFunc = func(argumentPrefix string) ([]AutocompleteItem, error)
ArgumentCompletionsFunc mirrors upstream's getArgumentCompletions callback on RegisteredCommand. Returns a list of completion items, or nil to fall through to the default provider.
pig translation rule (Promise<T[] | null> → ([]T, error)): upstream returns `AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>`. The Go signature returns the slice + error directly; if the host needs cancellation it wraps the call in a goroutine + ctx.Done() select: same shape upstream takes (the function has no signal/ctx parameter upstream either).
type AssistantMessageEvent ¶
type AssistantMessageEvent = any
AssistantMessageEvent mirrors @earendil-works/pi-ai AssistantMessageEvent.
type AssistantMessageEventStream ¶
type AssistantMessageEventStream = any
AssistantMessageEventStream mirrors AssistantMessageEventStream.
type AttributedResourcePath ¶
type AttributedResourcePath struct {
Path string `json:"path"`
ExtensionPath string `json:"extensionPath"`
}
AttributedResourcePath pairs a resource path with the extension that declared it. Used by EmitResourcesDiscover to surface where each skill/prompt/theme path came from.
upstream: anonymous type at runner.ts:944-947
skillPaths: Array<{ path: string; extensionPath: string }>;
pig names this type because Go's anonymous-type composition is less ergonomic than TS's; same wire shape.
type AutocompleteCompletion ¶
type AutocompleteCompletion struct {
Lines []string `json:"lines"`
CursorLine int `json:"cursorLine"`
CursorCol int `json:"cursorCol"`
}
AutocompleteCompletion carries the complete replacement and UTF-16 cursor position returned by a provider.
type AutocompleteItem ¶
type AutocompleteItem struct {
Value string `json:"value"`
Label string `json:"label,omitempty"`
Description string `json:"description,omitempty"`
}
AutocompleteItem mirrors @earendil-works/pi-tui AutocompleteItem.
Concrete shape so subprocess autocomplete responses can deserialise into a typed value the host can pass to the TUI editor without an extra translation step.
type AutocompleteProvider ¶
type AutocompleteProvider struct {
TriggerCharacters []string
GetSuggestions func(context.Context, []string, int, int, bool) (*AutocompleteSuggestions, error)
ApplyCompletion func(context.Context, []string, int, int, AutocompleteItem, string) (AutocompleteCompletion, error)
ShouldTriggerFileCompletion func(context.Context, []string, int, int) (bool, error)
}
AutocompleteProvider mirrors @earendil-works/pi-tui AutocompleteProvider.
func SetupAutocompleteProvider ¶
func SetupAutocompleteProvider(ctx context.Context, base *AutocompleteProvider, factories []AutocompleteProviderFactory) (*AutocompleteProvider, error)
SetupAutocompleteProvider folds retained factories over a fresh base and merges their trigger characters in first-seen order.
type AutocompleteProviderFactory ¶
type AutocompleteProviderFactory func(context.Context, *AutocompleteProvider) (*AutocompleteProvider, error)
AutocompleteProviderFactory mirrors upstream AutocompleteProviderFactory.
type AutocompleteSuggestions ¶
type AutocompleteSuggestions struct {
Items []AutocompleteItem `json:"items"`
Prefix string `json:"prefix"`
}
AutocompleteSuggestions mirrors @earendil-works/pi-tui AutocompleteSuggestions.
type BashOperations ¶
type BashOperations interface {
Exec(ctx context.Context, command, cwd string, options BashOperationsExecOptions) (BashOperationsResult, error)
}
BashOperations mirrors upstream BashOperations (core/tools/bash.ts): pluggable command execution, local by default and remote (for example SSH) when an extension supplies it, such as from a user_bash handler's { operations } result. Exec returns an error whose message is "aborted" when ctx was cancelled and "timeout:<seconds>" when the timeout fired, as upstream's callers match on those messages.
type BashOperationsExecOptions ¶
type BashOperationsExecOptions struct {
// OnData receives raw output bytes (stdout and stderr) as they arrive,
// from one goroutine at a time. The callee may keep the slice.
OnData func(data []byte)
// Timeout is the requested timeout in seconds; nil means none.
Timeout *float64
// Env replaces the inherited environment when non-nil.
Env []string
}
BashOperationsExecOptions mirrors the options upstream BashOperations.exec receives (core/tools/bash.ts). Cancellation is the context.
type BashOperationsResult ¶
type BashOperationsResult struct {
ExitCode *int
}
BashOperationsResult mirrors upstream { exitCode: number | null }: a signal termination reports 128 + the signal number, and nil is a failed command.
type BashResult ¶
type BashResult = any
BashResult mirrors core/bash-executor.BashResult. A native result must contain exitCode; its nil value represents undefined, not JSON null. A nil optional fullOutputPath is also undefined. Pre-encoded JSON retains its own null values.
type BashToolCallEvent ¶
type BashToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "bash"
Input BashToolInput `json:"input"`
}
BashToolCallEvent: upstream types.ts BashToolCallEvent.
type BashToolDetails ¶
type BashToolDetails struct {
Truncation *ToolTruncation `json:"truncation,omitempty"`
FullOutputPath string `json:"fullOutputPath,omitempty"`
}
BashToolDetails mirrors upstream bash.ts:31. Attached only when output was truncated.
type BashToolInput ¶
type BashToolInput = any
type BashToolResultEvent ¶
type BashToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "bash"
Details *BashToolDetails `json:"details,omitempty"`
}
BashToolResultEvent: upstream types.ts BashToolResultEvent.
type BeforeAgentStartCombinedResult ¶
type BeforeAgentStartCombinedResult struct {
// Messages is the slice of custom messages collected from every
// handler that returned `result.message`. Empty when no handler
// pushed a message.
Messages []CustomMessageRef `json:"messages,omitempty"`
// SystemPrompt is the final mutated system prompt, non-nil only if at
// least one handler set `result.systemPrompt` (an empty prompt included).
SystemPrompt *string `json:"systemPrompt,omitempty"`
// SystemPromptOptions is the per-run options object the handlers shared. It is set when the incoming options or a handler supplied sections, or a handler edited selectedTools. It does not alias the caller's base options.
SystemPromptOptions *BuildSystemPromptOptions `json:"systemPromptOptions,omitempty"`
// SelectedToolsEdited retains an explicit edit even when filtering non-string registry misses produces the original list.
SelectedToolsEdited bool `json:"-"`
}
BeforeAgentStartCombinedResult is the aggregated result from all before_agent_start handlers. Returned by the runner's EmitBeforeAgentStart.
upstream: runner.ts:103-107 (interface BeforeAgentStartCombinedResult)
interface BeforeAgentStartCombinedResult {
messages?: NonNullable<BeforeAgentStartEventResult["message"]>[];
systemPrompt?: string;
}
Upstream declares this type as `interface` private to runner.ts; pig exports it because Go callers need to type-assert on it after EmitBeforeAgentStart returns. Field semantics match upstream verbatim.
type BeforeAgentStartEvent ¶
type BeforeAgentStartEvent struct {
Type string `json:"type"`
Prompt string `json:"prompt"`
Images []ImageContent `json:"images,omitempty"`
SystemPrompt string `json:"systemPrompt"`
// SystemPromptOptions is the per-handler value view of the run's options. Use BeforeAgentStartOptions with the dispatch context to replace collections on the shared per-run object.
SystemPromptOptions BuildSystemPromptOptions `json:"systemPromptOptions"`
}
BeforeAgentStartEvent: upstream types.ts BeforeAgentStartEvent.
type BeforeAgentStartEventResult ¶
type BeforeAgentStartEventResult struct {
Message *CustomMessageRef `json:"message,omitempty"`
// SystemPrompt replaces the run's system prompt when set, including when
// it is empty; nil leaves it unchanged (upstream `systemPrompt?: string`).
SystemPrompt *string `json:"systemPrompt,omitempty"`
}
BeforeAgentStartEventResult: upstream types.ts BeforeAgentStartEventResult.
type BeforeProviderHeadersEvent ¶
type BeforeProviderHeadersEvent struct {
Type string `json:"type"`
Headers ProviderHeaders `json:"headers"`
}
BeforeProviderHeadersEvent: upstream types.ts BeforeProviderHeadersEvent. Handlers mutate Headers in place before the request is sent.
type BeforeProviderRequestEvent ¶
BeforeProviderRequestEvent: upstream types.ts BeforeProviderRequestEvent.
type BeforeProviderRequestEventResult ¶
type BeforeProviderRequestEventResult = any
BeforeProviderRequestEventResult: upstream type alias for `unknown`.
type BoundaryBaseEvent ¶
type BoundaryBaseEvent interface {
// contains filtered or unexported methods
}
BoundaryBaseEvent is the closed input union of actionable turn_end and agent_before_settle events. The runner supplies each handler's proposal and preview.
type BoundaryContextPreview ¶
type BoundaryContextPreview struct {
ContextEntries []ProjectedSessionEntry `json:"contextEntries"`
ContextMessages []AgentMessage `json:"contextMessages"`
LLMMessages []any `json:"llmMessages"`
PendingMessages []AgentMessage `json:"pendingMessages"`
CanContinue bool `json:"canContinue"`
}
BoundaryContextPreview is the recomputed session/model context after the currently proposed entries.
type BoundaryResult ¶
type BoundaryResult struct {
Entries *[]SessionBoundaryDraft `json:"entries,omitempty"`
Continue *bool `json:"continue,omitempty"`
}
BoundaryResult chains proposed entries and explicit continuation. Pointer fields preserve omitted versus explicit empty/false results.
type BoundaryState ¶
type BoundaryState struct {
Entries []SessionBoundaryDraft `json:"entries"`
Continue bool `json:"continue"`
Context BoundaryContextPreview `json:"context"`
Outcome AgentActivityOutcome `json:"outcome"`
}
BoundaryState is shared by turn_end and agent_before_settle upstream.
type BranchSummaryEntry ¶
type BranchSummaryEntry = any
BranchSummaryEntry mirrors core/session-manager BranchSummaryEntry.
type BuildSystemPromptOptions ¶
type BuildSystemPromptOptions struct {
// CustomPrompt is the user-supplied prompt that replaces the default
// (from --system-prompt, SYSTEM.md, or custom templates).
CustomPrompt string `json:"customPrompt,omitempty"`
// CustomPromptSet preserves a present empty customPrompt without changing the existing string field. A nonempty CustomPrompt is always present.
CustomPromptSet bool `json:"-"`
// ForceSystemPrompt is the exact full prompt a before_agent_start handler returned as systemPrompt; later handlers observe it (runner.ts:1346-1348). Nil is Pi's undefined; an empty string is a forced empty prompt.
ForceSystemPrompt *string `json:"forceSystemPrompt,omitempty"`
// SelectedTools is the list of tool names included in the prompt.
// Defaults upstream to [read, bash, edit, write].
SelectedTools []string `json:"selectedTools,omitzero"`
// ToolSnippets maps tool name → one-line description used in the
// "Available tools" section.
ToolSnippets map[string]string `json:"toolSnippets,omitzero"`
// ToolGuidelines contributes rules only while its tool is active.
ToolGuidelines map[string][]string `json:"toolGuidelines,omitzero"`
// PromptGuidelines holds bullet lines appended to the default
// guidelines section.
PromptGuidelines []string `json:"promptGuidelines,omitzero"`
// AppendSystemPrompt is the joined text appended after the main
// prompt body (from --append-system-prompt flags / settings).
AppendSystemPrompt string `json:"appendSystemPrompt"`
// Sections holds additional XML-wrapped sections in authored order. Event handlers mutate the per-run collection, not the Session's base options.
Sections *ai.OrderedSections `json:"sections,omitempty"`
// Cwd is the working directory shown to the LLM.
Cwd string `json:"cwd"`
// ContextFiles are pre-loaded AGENTS.md / CLAUDE.md files in the
// order they appear in the prompt.
ContextFiles []SystemPromptContextFile `json:"contextFiles,omitzero"`
// Skills lists skills surfaced in the prompt's skills section.
Skills []SystemPromptSkill `json:"skills,omitzero"`
}
BuildSystemPromptOptions mirrors upstream `core/system-prompt.ts::BuildSystemPromptOptions`.
Extensions receive this struct on every `before_agent_start` event via `event.systemPromptOptions` so they can inspect what pi has already assembled (custom prompt, tools, append text, context files, skills) without re-discovering resources.
Extensions receive upstream's NormalizedBuildSystemPromptOptions (system-prompt.ts:37-46): every collection is present, so an empty selectedTools is `[]`, not an omitted key. MarshalJSON writes that shape; the struct tags describe only decoding.
upstream: packages/coding-agent/src/core/system-prompt.ts:9-69
func BeforeAgentStartOptions ¶
func BeforeAgentStartOptions(ctx context.Context) *BuildSystemPromptOptions
BeforeAgentStartOptions returns the shared per-run options during before_agent_start, or nil outside that dispatch. Assign collection replacements through this pointer; edits remain visible to later handlers even when the handler returns an error. The pointer never aliases the Session's base options.
func NormalizeBuildSystemPromptOptions ¶
func NormalizeBuildSystemPromptOptions(input BuildSystemPromptOptions) BuildSystemPromptOptions
NormalizeBuildSystemPromptOptions supplies the collection-complete shape exposed to extensions while copying the per-run mutable collections.
Ports packages/coding-agent/src/core/system-prompt.ts
func (BuildSystemPromptOptions) MarshalJSON ¶
func (o BuildSystemPromptOptions) MarshalJSON() ([]byte, error)
MarshalJSON writes the collection-complete shape that upstream's normalizeBuildSystemPromptOptions (system-prompt.ts:48-64) exposes to extensions: empty collections stay present, while customPrompt is omitted when it is undefined.
func (*BuildSystemPromptOptions) UnmarshalJSON ¶
func (o *BuildSystemPromptOptions) UnmarshalJSON(data []byte) error
UnmarshalJSON retains customPrompt presence for command and event option round trips.
type CacheWarmingAction ¶
type CacheWarmingAction string
CacheWarmingAction selects whether the scheduled prompt-cache refresh runs.
const ( CacheWarmingActionWarm CacheWarmingAction = "warm" CacheWarmingActionStop CacheWarmingAction = "stop" )
type CacheWarmingDecisionEvent ¶
type CacheWarmingDecisionEvent struct {
Type string `json:"type"`
WarmCost float64 `json:"warmCost"`
MissCost float64 `json:"missCost"`
ContinuationProbability float64 `json:"continuationProbability"`
Action CacheWarmingAction `json:"action"`
}
CacheWarmingDecisionEvent carries the economics and default action before a cache refresh.
type CacheWarmingDecisionEventResult ¶
type CacheWarmingDecisionEventResult struct {
Action *CacheWarmingAction `json:"action,omitempty"`
}
CacheWarmingDecisionEventResult overrides the decision when Action is present.
type CancelledResult ¶
type CancelledResult struct {
Cancelled bool `json:"cancelled"`
}
CancelledResult is the return type for session-mutation commands (newSession, fork, navigateTree, switchSession). Upstream returns `{ cancelled: boolean }`: Go uses a named struct for clarity.
upstream: types.ts (inline `Promise<{ cancelled: boolean }>` on each method)
type Capability ¶
type Capability = string
Capability is a typed string for well-known extension capability names. Authors may use unknown strings; hosts only enforce the well-known set.
const ( CapOnEvent Capability = "onEvent" // umbrella for all on*() subscribers CapRegisterTool Capability = "registerTool" CapRegisterCommand Capability = "registerCommand" CapRegisterShortcut Capability = "registerShortcut" CapRegisterFlag Capability = "registerFlag" CapRegisterRenderer Capability = "registerMessageRenderer" CapRegisterProvider Capability = "registerProvider" CapSendMessage Capability = "sendMessage" CapSendUserMessage Capability = "sendUserMessage" CapAppendEntry Capability = "appendEntry" CapSessionMetadata Capability = "sessionMetadata" CapExec Capability = "exec" CapToolIntrospection Capability = "toolIntrospection" CapModelControl Capability = "modelControl" CapThinkingLevel Capability = "thinkingLevel" CapEvents Capability = "events" // EventBus pub/sub )
Well-known capability names. These mirror the extension API surface groups.
type CommandActions ¶
type CommandActions struct {
// WaitForIdle blocks until the agent finishes streaming.
WaitForIdle func() error
WaitForIdleContext func(context.Context) error
// NewSession starts a new session.
NewSession func(opts *NewSessionOptions) (CancelledResult, error)
NewSessionContext func(context.Context, *NewSessionOptions) (CancelledResult, error)
// Fork creates a new branch from entryId.
Fork func(entryID string, opts *ForkOptions) (CancelledResult, error)
ForkContext func(context.Context, string, *ForkOptions) (CancelledResult, error)
// NavigateTree moves to a different point in the session tree.
// SwitchSession switches to a different session file.
SwitchSession func(sessionPath string, opts *SwitchSessionOptions) (CancelledResult, error)
SwitchSessionContext func(context.Context, string, *SwitchSessionOptions) (CancelledResult, error)
// Reload reloads extensions, skills, prompts, themes.
Reload func() error
ReloadContext func(context.Context) error
}
CommandActions is the host-side injection of command-specific callbacks. These are the extra surfaces available only in command handlers (via CommandContext), not in event handlers.
Mirrors upstream ExtensionCommandContextActions (types.ts:1484-1506). All fields are optional; nil functions produce safe no-ops.
upstream: types.ts:1484-1506
type CommandContext ¶
type CommandContext struct {
*Context
// contains filtered or unexported fields
}
CommandContext extends Context with command-specific actions available only inside slash-command handlers. Mirrors upstream ExtensionCommandContext (types.ts:328-363).
Retrieve from a context.Context via CommandContextFromContext.
upstream: runner.ts:736-772 (createCommandContext)
func CommandContextFromContext ¶
func CommandContextFromContext(ctx context.Context) *CommandContext
CommandContextFromContext retrieves the CommandContext attached by WithCommandContext. Returns nil if none is set.
func NewCommandContext ¶
func NewCommandContext(base *Context, cmdActions CommandActions) *CommandContext
NewCommandContext constructs a CommandContext from the base context and command-specific actions. Called by the runner when dispatching a slash command registered by an extension. SendUserMessage is inherited from the base Context, which carries it for every dispatch.
upstream: runner.ts:736-772
func (*CommandContext) Fork ¶
func (c *CommandContext) Fork(entryID string, opts *ForkOptions) (CancelledResult, error)
Fork creates a new branch from entryID.
func (*CommandContext) GetSystemPromptOptions ¶
func (c *CommandContext) GetSystemPromptOptions() (*BuildSystemPromptOptions, error)
GetSystemPromptOptions returns the base inputs pi currently uses to build the system prompt (custom prompt, active tools, tool snippets, prompt guidelines, appended text, cwd, loaded context files, and skills). It reports the current base inputs only; it does not include per-turn before_agent_start chained changes, later context-event message mutations, or before_provider_request rewrites.
When no data source is wired, returns zero-value options carrying the runner cwd, matching upstream's `getSystemPromptOptions ?? (() => ({ cwd: this.cwd }))` default.
upstream: runner.ts:653-656 (createCommandContext getSystemPromptOptions), types.ts:339
func (*CommandContext) NavigateTree ¶
func (c *CommandContext) NavigateTree(targetID string, opts *NavigateTreeOptions) (CancelledResult, error)
NavigateTree moves to a different point in the session tree.
func (*CommandContext) NewSession ¶
func (c *CommandContext) NewSession(opts *NewSessionOptions) (CancelledResult, error)
NewSession starts a new session.
func (*CommandContext) Reload ¶
func (c *CommandContext) Reload() error
Reload reloads extensions, skills, prompts, themes.
func (*CommandContext) SwitchSession ¶
func (c *CommandContext) SwitchSession(sessionPath string, opts *SwitchSessionOptions) (CancelledResult, error)
SwitchSession switches to a different session file.
func (*CommandContext) WaitForIdle ¶
func (c *CommandContext) WaitForIdle() error
WaitForIdle blocks until the agent finishes streaming.
type CommandHandler ¶
CommandHandler is invoked when an extension command is run. Mirrors upstream's RegisteredCommand.handler signature.
CommandHandler receives cancellation and per-extension values through the Go context. Use FromContext to access the extension context.
type CommandOptions ¶
type CommandOptions struct {
Description string `json:"description,omitempty"`
GetArgumentCompletions ArgumentCompletionsFunc `json:"-"`
Handler CommandHandler `json:"-"`
}
CommandOptions is the registration payload for API.RegisterCommand : upstream's `Omit<RegisteredCommand, "name" | "sourceInfo">`.
type CompactOptions ¶
type CompactOptions struct {
CustomInstructions string `json:"customInstructions,omitempty"`
OnComplete func(result CompactionResult) `json:"-"`
OnError func(err error) `json:"-"`
}
CompactOptions mirrors upstream `CompactOptions` (types.ts:284-288). Configures a compaction operation triggered via Context.Compact.
- CustomInstructions: optional user-provided guidance for the summarization model.
- OnComplete: callback invoked with the CompactionResult once the async compaction finishes. Nil disables the callback (fire-and- forget).
- OnError: callback invoked when compaction fails. Nil routes the error to the runner's error listeners.
upstream: types.ts:284-288
type CompactionEntry ¶
type CompactionEntry = any
CompactionEntry mirrors core/session-manager CompactionEntry.
type CompactionPreparation ¶
type CompactionPreparation = any
CompactionPreparation mirrors core/compaction CompactionPreparation.
type CompactionResult ¶
type CompactionResult = any
CompactionResult mirrors core/compaction CompactionResult.
type Component ¶
type Component = any
Component mirrors @earendil-works/pi-tui Component. PiG transports rendered component state across the subprocess boundary, so the in-process value is opaque here.
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context is the per-extension runtime context. Mirrors upstream's ExtensionContext (types.ts:ExtensionContext).
Authors retrieve the Context from a context.Context via FromContext. The host attaches it at event-dispatch time using WithContext.
Go carries cancellation and per-extension values through one context.Context. Authors retrieve the extension Context with FromContext.
Context exposes the runtime, UI, session, model, and cancellation surfaces backed by ContextActions. Optional actions use their documented zero-value behavior when the host does not bind them.
func FromContext ¶
FromContext retrieves the per-extension Context that the host attached via WithContext. Returns nil if none was attached (e.g. a unit test that constructs handlers without a host).
Typical usage in an extension handler:
api.OnToolCall(func(ctx context.Context, event extension.ToolCallEvent) extension.ToolCallEventResult {
extCtx := extension.FromContext(ctx)
if extCtx != nil {
cwd, _ := extCtx.CWD()
// ... use cwd
}
return extension.ToolCallEventResult{}
})
func NewContext ¶
func NewContext(cwd string, uiContext UIContext, assertActive func() error, actions ContextActions) *Context
NewContext constructs a Context with the given parameters. This is the constructor that hosts (Runner) use; extension authors never call this directly.
uiContext is the per-mode UI binding (matches upstream's `runner.uiContext` field at runner.ts:225). Pass NoopUIContext when no UI is available; nil is normalized to NoopUIContext so callers of Context.UI always receive a non-nil dispatchable.
assertActive is the runner's staleness guard; every getter/method on Context calls it first.
actions carries the optional injection callbacks that back Model/IsIdle/Shutdown/etc. Pass a zero-value `ContextActions{}` for the no-op defaults (matches upstream's bindCore-pre-bind state).
upstream: runner.ts:566-630 (createContext factory)
func (*Context) Abort ¶
Abort cancels the current agent operation. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: no-op (matches upstream's `() => {}` default at runner.ts:240).
upstream: runner.ts:602-605 (`abort: () => { ... }`)
func (*Context) CWD ¶
CWD returns the working directory captured at Runner construction. Returns an error if the runner has been invalidated.
upstream: runner.ts:581 (`get cwd()`)
func (*Context) Compact ¶
func (c *Context) Compact(opts *CompactOptions) error
Compact triggers compaction without awaiting completion. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: no-op (matches upstream's `() => {}` default at runner.ts:234).
upstream: runner.ts:618-621 (`compact: (options) => { ... }`)
func (*Context) GetActiveTools ¶
GetActiveTools returns the names of currently active tools. Returns nil if no tool-scoping actions are wired.
func (*Context) GetAllTools ¶
pig additive (D23): these methods support Piglet tool scoping. GetAllTools returns metadata about all registered tools. Returns nil if no tool-scoping actions are wired.
func (*Context) GetContextUsage ¶
func (c *Context) GetContextUsage() (*ContextUsage, error)
GetContextUsage returns the current context-window usage for the active model, or nil if unknown. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: returns nil (matches upstream's `() => undefined` default at runner.ts:233).
upstream: runner.ts:614-617 (`getContextUsage: () => { ... }`)
func (*Context) GetFlagValue ¶
GetFlagValue returns the value of an extension-registered flag. Returns nil if no flag-value actions are wired.
func (*Context) GetSystemPrompt ¶
GetSystemPrompt returns the current system prompt text. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: returns the empty string (matches upstream's `() => ""` default).
upstream: runner.ts:622-625 (`getSystemPrompt: () => { ... }`)
func (*Context) HasPendingMessages ¶
HasPendingMessages reports whether queued messages are awaiting processing. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: returns false (matches upstream's `() => false` default at runner.ts:232).
upstream: runner.ts:606-609 (`hasPendingMessages: () => { ... }`)
func (*Context) HasUI ¶
HasUI reports whether the runner has a real (non-noop) UI context attached. Mirrors upstream's pointer-identity check (runner.ts:361: `this.uiContext !== noOpUIContext`).
Returns an error if the runner has been invalidated.
upstream: runner.ts:359-362
func (*Context) IsIdle ¶
IsIdle reports whether the agent is currently idle (not streaming). Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: returns true (matches upstream's `() => true` default at runner.ts:228).
upstream: runner.ts:594-597 (`isIdle: () => { ... return runner.isIdleFn(); }`)
func (*Context) IsProjectTrusted ¶
IsProjectTrusted reports whether the current project is trusted, so an extension can refuse to read project-scoped configuration or run project code before the user has trusted it. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: returns true (matches upstream's `() => true` default at runner.ts:280).
upstream: runner.ts:718-721 (`isProjectTrusted: () => { ... }`)
func (*Context) Mode ¶
func (c *Context) Mode() (ExtensionMode, error)
Mode returns the current run mode (tui/rpc/json/print), including changes made after this context was created. An unbound getter returns print. Stale contexts return an error. upstream: packages/coding-agent/src/core/extensions/runner.ts:createContext
func (*Context) Model ¶
Model returns the currently selected model, or nil if none is set. Returns an error if the runner has been invalidated.
Model is opaque at the extension boundary so providers retain their concrete model representation.
upstream: runner.ts:590 (`get model()`)
func (*Context) ModelRegistry ¶
func (c *Context) ModelRegistry() (ModelRegistry, error)
ModelRegistry returns the per-runtime ModelRegistry. Returns an error if the runner has been invalidated.
upstream: runner.ts:586 (`get modelRegistry()`)
func (*Context) ScopedModels ¶
func (c *Context) ScopedModels() ([]ScopedModel, error)
ScopedModels returns the current read-only scope through the callback captured when this context was created. An unbound callback returns an empty list. Do not mutate the returned slice or models. upstream: packages/coding-agent/src/core/extensions/runner.ts:createContext
func (*Context) SendUserMessage ¶
func (c *Context) SendUserMessage(content any, opts *SendUserMessageOptions) error
SendUserMessage injects a user message into the agent loop and triggers a turn when the agent is idle.
Upstream exposes this method on ExtensionAPI. Go handlers receive Context directly, so the method is available here.
func (*Context) SessionManager ¶
func (c *Context) SessionManager() (SessionManager, error)
SessionManager returns the per-runtime SessionManager. Returns an error if the runner has been invalidated.
SessionManager is opaque at the extension boundary; the host owns its concrete implementation.
upstream: runner.ts:582 (`get sessionManager()`)
func (*Context) SetActiveTools ¶
SetActiveTools sets the active tool list by name. No-op if no tool-scoping actions are wired.
func (*Context) Shutdown ¶
Shutdown triggers graceful agent shutdown. Returns an error if the runner has been invalidated.
Default semantics when no actions injector is bound: no-op (matches upstream's `() => {}` default at runner.ts:241).
upstream: runner.ts:610-613 (`shutdown: () => { ... }`)
func (*Context) UI ¶
UI returns the per-mode UIContext. Returns the package-level NoopUIContext singleton when no UI was bound (matches upstream's pre-bind state at runner.ts:255).
Returns an error if the runner has been invalidated.
upstream: runner.ts:572-575 (`get ui()` returns `runner.uiContext`)
type ContextActions ¶
type ContextActions struct {
// SessionManager backs Context.SessionManager().
// upstream: types.ts:301 (read-only)
SessionManager SessionManager
// ModelRegistry backs Context.ModelRegistry().
// upstream: types.ts:303
ModelRegistry ModelRegistry
// GetModel backs Context.Model(). Returns nil if no model is
// currently selected.
// upstream: types.ts:305 (Model<any> | undefined)
GetModel func() Model
// GetScopedModels returns the current read-only model scope. Context creation captures this callback, not its result.
// upstream: packages/coding-agent/src/core/extensions/runner.ts:createContext
GetScopedModels func() []ScopedModel
// IsIdle backs Context.IsIdle().
// upstream: types.ts:307
IsIdle func() bool
// IsProjectTrusted backs Context.IsProjectTrusted().
// upstream: types.ts:332
IsProjectTrusted func() bool
// HasPendingMessages backs Context.HasPendingMessages().
// upstream: types.ts:313
HasPendingMessages func() bool
// SendUserMessage backs Context.SendUserMessage(). Injects a user
// message into the agent loop. Populated by the runner from
// ExtensionActions, which is where a host supplies it.
// upstream: types.ts:1306 (ExtensionAPI.sendUserMessage)
SendUserMessage SendUserMessageHandler
// Abort backs Context.Abort(). Cancels the current agent action.
// upstream: types.ts:311
Abort func()
// Shutdown backs Context.Shutdown(). Triggers graceful agent
// shutdown.
// upstream: types.ts:315
Shutdown func()
// GetContextUsage backs Context.GetContextUsage().
// upstream: types.ts:317
GetContextUsage func() *ContextUsage
// Compact backs Context.Compact(opts).
// upstream: types.ts:319
Compact func(opts *CompactOptions)
// GetSystemPrompt backs Context.GetSystemPrompt(). The host callback
// returns the latest prompt, including changes made by earlier
// before_agent_start handlers.
// upstream: types.ts:321
GetSystemPrompt func() string
// GetSystemPromptOptions backs CommandContext.GetSystemPromptOptions().
// Returns the base inputs pi currently uses to build the system
// prompt (custom prompt, tools, snippets, guidelines, append text,
// cwd, context files, skills). nil → method returns zero-value
// options, matching upstream's
// `getSystemPromptOptions ?? (() => ({ cwd: this.cwd }))` default.
// upstream: types.ts:1512, runner.ts:303,653
GetSystemPromptOptions func() *BuildSystemPromptOptions
// GetMode reads the current runner mode. Nil means print.
// upstream: runner.ts:createContext
GetMode func() ExtensionMode
// GetUIContext reads the current runner UI binding. Nil uses the constructor's UI binding.
// upstream: runner.ts:createContext
GetUIContext func() UIContext
// GetAllTools returns metadata about all registered tools.
// Used by piglet scoping to enumerate available tools.
GetAllTools func() []ToolInfo
// GetActiveTools returns the names of currently active tools.
GetActiveTools func() []string
// SetActiveTools sets the active tool list by name.
// Tools not in the list are hidden from the agent.
SetActiveTools func(names []string)
// GetFlagValue returns the value of an extension-registered flag.
GetFlagValue func(name string) any
}
ContextActions is the host-side injection of per-runtime callbacks that back Context's surfaces. Mirrors upstream's `ExtensionContextActions` (types.ts:1467-1481): the single struct passed to `bindCore` to wire dynamic context surfaces (model selection, idle state, abort handling, etc.) without making the Context constructor signature unwieldy.
All fields are optional. Nil function fields produce upstream- equivalent default behavior:
GetModel nil → Model() returns nil (upstream: () => undefined)
IsIdle nil → IsIdle() returns true (upstream: () => true)
HasPendingMessages nil → HasPendingMessages() returns false (upstream: () => false)
Shutdown nil → Shutdown() is no-op (upstream: () => {})
GetContextUsage nil → GetContextUsage() returns nil (upstream: () => undefined)
Compact nil → Compact() is no-op (upstream: () => {})
GetSystemPrompt nil → GetSystemPrompt() returns "" (upstream: () => "")
SessionManager and ModelRegistry are direct value injections (not closures) because upstream stores them as Runner fields, not callbacks; nil values are honored.
pig additive (D23): ContextActions supplies Piglet tool-scoping operations.
type ContextEvent ¶
type ContextEvent struct {
Type string `json:"type"`
Messages []AgentMessage `json:"messages"`
}
ContextEvent: upstream types.ts ContextEvent.
type ContextEventResult ¶
type ContextEventResult struct {
Messages []AgentMessage `json:"messages,omitempty"`
}
ContextEventResult: upstream types.ts ContextEventResult.
type ContextUsage ¶
type ContextUsage struct {
Tokens *int `json:"tokens"`
ContextWindow int `json:"contextWindow"`
Percent *float64 `json:"percent"`
}
ContextUsage mirrors upstream `ContextUsage` (types.ts:276-283). Reports the agent's current context-window utilization for the active model.
Field semantics (from upstream JSDoc):
- Tokens: estimated context tokens, or nil if unknown (e.g. right after compaction, before the next LLM response).
- ContextWindow: model's maximum context size in tokens.
- Percent: usage as percentage of context window, or nil if Tokens is unknown.
Pointer-typed nullable fields distinguish unknown from zero; percentages retain JavaScript number precision.
upstream: types.ts:276-283
type ContextWithSystemEvent ¶
type ContextWithSystemEvent struct {
Type string `json:"type"`
Messages []AgentMessage `json:"messages"`
}
ContextWithSystemEvent: upstream types.ts ContextWithSystemEvent. Handlers see the full transcript, system messages included, after the context handlers; their returned messages are used as returned.
type CustomEntry ¶
type CustomEntry = any
CustomEntry mirrors core CustomEntry<T>: a session entry appended via AppendEntry that does not participate in LLM context. Like CustomMessage, the generic payload is carried untyped (the wire boundary is JSON) and renderers type-assert as needed.
type CustomMessageRef ¶
type CustomMessageRef struct {
CustomType string `json:"customType"`
Content any `json:"content"`
Display any `json:"display,omitempty"`
Details any `json:"details,omitempty"`
}
CustomMessageRef mirrors upstream's `Pick<CustomMessage, "customType" | "content" | "display" | "details">`.
type CustomToolCallEvent ¶
type CustomToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"`
Input map[string]any `json:"input"`
}
CustomToolCallEvent: upstream types.ts CustomToolCallEvent.
type CustomToolResultEvent ¶
type CustomToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"`
Details any `json:"details,omitempty"`
}
CustomToolResultEvent: upstream types.ts CustomToolResultEvent.
type DeliverAs ¶
type DeliverAs string
DeliverAs is the queueing discriminator for API.SendMessage / API.SendUserMessage. Upstream literal-string union.
upstream: types.ts:1161, 1170
type DialogInitiationReporter ¶
type DialogInitiationReporter interface {
ReportsDialogInitiation() bool
}
DialogInitiationReporter is implemented by a UIContext whose Select, Confirm, Input, and Editor call CallInitiated once the dialog is installed. Other UIContexts are treated as initiated when the host dispatches the call.
type EditToolCallEvent ¶
type EditToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "edit"
Input EditToolInput `json:"input"`
}
EditToolCallEvent: upstream types.ts EditToolCallEvent.
type EditToolDetails ¶
type EditToolDetails struct {
Diff string `json:"diff"`
Patch string `json:"patch"`
FirstChangedLine int `json:"firstChangedLine,omitempty"`
}
EditToolDetails is the upstream SDK contract for built-in edit-tool result details (edit.ts:61). Extensions and PostToolUse hooks receive this shape on tool_result events for the `edit` tool: a display diff, a standard unified patch, and the first changed line for navigation.
type EditToolInput ¶
type EditToolInput = any
type EditToolResultEvent ¶
type EditToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "edit"
Details *EditToolDetails `json:"details,omitempty"`
}
EditToolResultEvent: upstream types.ts EditToolResultEvent.
type EditorComponent ¶
type EditorComponent = any
EditorComponent mirrors @earendil-works/pi-tui EditorComponent.
type EntryRenderOptions ¶
type EntryRenderOptions struct {
Expanded bool `json:"expanded"`
}
EntryRenderOptions is passed to an EntryRenderer. Mirrors upstream EntryRenderOptions.
type EntryRenderer ¶
type EntryRenderer = func( entry CustomEntry, options EntryRenderOptions, theme Theme, ) Component
EntryRenderer mirrors upstream EntryRenderer<T>. Renders a custom session entry (appended via AppendEntry; not sent to the LLM) into a TUI Component, or returns nil to fall back to the default renderer.
As with MessageRenderer, the Go signature drops the TS generic parameter T: the entry's data is carried on CustomEntry (currently `any`) and the renderer type-asserts as needed.
type ErrorListener ¶
type ErrorListener = func(*ExtensionError)
ErrorListener is the callback signature registered via Runner.AddErrorListener. Listeners run synchronously in the dispatch goroutine; long-running work should be moved to a dedicated goroutine by the listener itself.
upstream: runner.ts:469 (private errorListeners: Set<ErrorListener>)
type EventBus ¶
type EventBus interface {
// Publish broadcasts payload under the given topic to every current
// subscriber. Synchronous: handlers run before Publish returns. Panics
// in handlers are recovered and logged by the host.
Publish(topic string, payload any)
// Subscribe registers handler for topic and returns a cancel func that
// unsubscribes. Handlers are dispatched in registration order.
Subscribe(topic string, handler func(payload any)) (cancel func())
}
EventBus is the extension-to-extension pub/sub bus. Mirrors upstream's core/event-bus.EventBus, exposed on ExtensionAPI as the property `events: EventBus`.
Go exposes upstream's `events` property through API.Events.
type ExecOptions ¶
type ExecOptions struct {
// Timeout in milliseconds. Pi's timeout is a JavaScript number: a positive value starts a timer and anything else starts none.
Timeout float64 `json:"timeout,omitempty"`
// CWD overrides the working directory. Empty uses the extension's CWD.
CWD string `json:"cwd,omitempty"`
}
ExecOptions configures a shell command execution.
upstream: core/exec.ts ExecOptions
type ExecResult ¶
type ExecResult struct {
Stdout string `json:"stdout"`
Stderr string `json:"stderr"`
Code int `json:"code"`
Killed bool `json:"killed"`
}
ExecResult is the outcome of a shell command execution.
upstream: core/exec.ts ExecResult
func ExecCommand ¶
func ExecCommand(ctx context.Context, cwd, command string, args []string, opts *ExecOptions) (ExecResult, error)
ExecCommand runs a shell command synchronously and returns the result. This is the default implementation backing API.Exec when the host doesn't provide an override.
The command is spawned directly (no shell wrapping). Use args to pass arguments. If opts.CWD is empty, cwd is used as the working directory. Like upstream, a program that cannot start does not fail the call: the result has code 1 and empty output. Arguments that Node's spawn rejects, an empty command or a NUL in the command, an argument, or the working directory, fail the call with Node's ERR_INVALID_ARG_VALUE message, which upstream's spawn throws. On Windows the program is looked up as Node's spawn looks it up (nodespawn.LookPath), so a name that matches only through PATHEXT, such as npm for npm.cmd, cannot start. A batch file name fails the call with Node's "spawn EINVAL" error, which upstream's spawn throws.
Timeout and context cancellation both trigger SIGTERM followed by SIGKILL after 5 seconds.
upstream: core/exec.ts execCommand
type Extension ¶
type Extension struct {
// Name is the human-readable name of the extension, typically derived
// from the manifest or directory name. Used for display in the UI.
Name string
// Path is the original (unresolved) path the extension was loaded from.
// This is typically the path the user passed via --extension or that the
// loader discovered. May be relative.
Path string
// ResolvedPath is the absolute, canonical path used for diagnostics,
// telemetry, and "Using <path>" UI strings.
ResolvedPath string
// SourceInfo describes the extension's origin and ownership metadata. The
// current public contract carries this value opaquely.
SourceInfo SourceInfo
// Handlers is the legacy construction shape. NewRunner imports it into the
// concurrency-safe handler registry before dispatch.
Handlers map[string][]HandlerFn
// Tools is the startup construction shape, keyed by name. Runtime readers use RegisteredTools or RegisteredTool to include synchronized late registrations.
Tools map[string]RegisteredTool
// ToolOrder records tool registration order. Go maps do not retain
// insertion order; loaders populate this alongside Tools so tool lists
// keep upstream's registration order (a Map in extension.tools).
ToolOrder []string
// MessageRenderers is keyed by the custom message type the renderer handles.
MessageRenderers map[string]MessageRenderer
// EntryRenderers is keyed by the custom entry type the renderer handles.
// Custom entries (appended via AppendEntry) do not participate in LLM context.
EntryRenderers map[string]EntryRenderer
// MarkdownTransformer is the extension's display-only Markdown transform,
// if it registered one; a later registration replaces an earlier one.
// upstream: types.ts Extension.markdownTransformer
MarkdownTransformer MarkdownTransformer
// Commands is keyed by the command name (without leading slash).
Commands map[string]RegisteredCommand
// CommandOrder records command registration order. Go maps do not retain
// insertion order; loaders populate this alongside Commands so resolved
// invocation names match upstream extension and registration order.
CommandOrder []string
// Flags is keyed by the flag name.
Flags map[string]ExtensionFlag
// FlagOrder records the first registration of each flag name. Loaders populate it alongside Flags, so --help lists flags in upstream registration order.
FlagOrder []string
// Shortcuts is keyed by the canonical KeyID (e.g. "ctrl+shift+r").
Shortcuts map[KeyID]ExtensionShortcut
// contains filtered or unexported fields
}
Extension is the state container populated by an extension's factory during loading. It is the cross-tier contract between the host and the extension implementation: factories write registrations into the API, the API writes them into this struct, and the Runner reads from it during dispatch.
A pre-populated `[]Extension` is what gets handed to a Runner. Loaders produce these; runners consume them. The runner does not mutate them.
Field-level translation rule: Go's idiomatic field naming and JSON tag preservation are applied; see docs/parity/DIVERGENCES.md "TS→Go translation rituals" section. The maps, sets, and overall shape mirror upstream verbatim.
upstream: types.ts:1513-1523 (export interface Extension)
func (*Extension) AddEventHandler ¶
AddEventHandler appends one identity-bearing handler in registration order.
func (*Extension) EventHandlers ¶
EventHandlers returns a stable dispatch snapshot. Registration changes made while it is being iterated apply only to the next dispatch.
func (*Extension) InitializeEventHandlers ¶
func (e *Extension) InitializeEventHandlers()
InitializeEventHandlers imports legacy Handlers once. Call before sharing an Extension between host and runner copies.
func (*Extension) InitializeToolRegistry ¶
func (e *Extension) InitializeToolRegistry()
InitializeToolRegistry enables synchronized runtime registration before an Extension is shared with runners.
func (*Extension) RegisteredTool ¶
func (e *Extension) RegisteredTool(name string) (RegisteredTool, bool)
RegisteredTool looks up the current definition without copying the registry.
func (*Extension) RegisteredTools ¶
func (e *Extension) RegisteredTools() []RegisteredTool
RegisteredTools returns an ordered snapshot, including tools registered after load.
func (*Extension) RemoveEventHandler ¶
RemoveEventHandler removes the exact registered identity. It is idempotent.
func (*Extension) ReplaceEventHandlers ¶
ReplaceEventHandlers makes e's handlers exactly source's, in place, so every copy of e that shares its registry dispatches to the new set from the next dispatch on. A restarted subprocess registers afresh; its runner keeps the copy it was built with.
func (*Extension) ReplaceRegisteredTools ¶
ReplaceRegisteredTools replaces the shared registry when the owning runtime restarts.
func (*Extension) SetRegisteredTool ¶
func (e *Extension) SetRegisteredTool(tool RegisteredTool)
SetRegisteredTool replaces a definition in place or appends a new name in registration order.
type ExtensionActions ¶
type ExtensionActions struct {
// upstream: types.ts:1590: SendMessageHandler
SendMessage any
// upstream: types.ts:1591: SendUserMessageHandler
SendUserMessage SendUserMessageHandler
// upstream: types.ts:1591: AppendEntryHandler
AppendEntry any
// upstream: types.ts:1592: SetSessionNameHandler
SetSessionName any
// upstream: types.ts:1593: GetSessionNameHandler
GetSessionName any
// upstream: types.ts:1594: SetLabelHandler
SetLabel any
// upstream: types.ts:1595: GetActiveToolsHandler
GetActiveTools any
// upstream: types.ts:1596: GetAllToolsHandler
GetAllTools any
// upstream: types.ts:1597: SetActiveToolsHandler
SetActiveTools any
// upstream: types.ts:1598: RefreshToolsHandler
RefreshTools any
// upstream: types.ts:1599: GetCommandsHandler
GetCommands any
// upstream: types.ts:1600: SetModelHandler
SetModel any
// upstream: types.ts:1601: GetThinkingLevelHandler
GetThinkingLevel any
// upstream: types.ts:1602: SetThinkingLevelHandler
SetThinkingLevel any
}
ExtensionActions is the host-side injection of agent-loop callbacks available to extensions via `ctx.actions.*` (the runtime side; this struct is consumed by [host.Runner.BindCore]). Mirrors upstream `ExtensionActions` (types.ts:1588-1603).
Most fields are opaque-typed (`any`) at this boundary because their concrete handler types live in upstream files not yet ported (session-manager, agent-runtime, tool-registry). Field names and upstream line cites are fixed here so a concrete handler type can replace `any` without renaming.
upstream: types.ts:1589-1603
type ExtensionError ¶
type ExtensionError struct {
// ExtensionPath is the resolved filesystem path of the extension
// whose handler failed. Mirrors upstream `extensionPath`.
ExtensionPath string `json:"extensionPath"`
// Event is the event-type string the handler was registered for
// (e.g. "tool_call", "session_start"). Mirrors upstream `event`.
Event string `json:"event"`
// Error is the human-readable message. In Go this is `err.Error()`;
// upstream is `err.message`. Mirrors upstream `error`.
Error string `json:"error"`
// Stack is the optional stack of the failure itself, as upstream's
// `err.stack`: the thrown error's stack for a subprocess extension, or
// the panicking goroutine's stack for an in-process handler. It is empty
// for a plain returned error, which carries no stack. See [ErrorStack].
Stack string `json:"stack,omitempty"`
}
ExtensionError is the structured error surfaced when a registered handler throws (TS) / returns a non-nil error (Go) during event dispatch. Hosts collect these without aborting the dispatch chain and surface them through `Runner.AddErrorListener`.
upstream: types.ts:1537-1542
export interface ExtensionError {
extensionPath: string;
event: string;
error: string;
stack?: string;
}
Wire format note. JSON tags match upstream camelCase exactly so the type round-trips cleanly through current and future extension transports.
type ExtensionFlag ¶
type ExtensionFlag struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Type FlagType `json:"type"`
Default any `json:"default,omitempty"`
ExtensionPath string `json:"extensionPath"`
}
ExtensionFlag mirrors upstream's ExtensionFlag: the loader's view of a registered flag, including its source extension. Hosts hand this to the CLI parser.
type ExtensionMode ¶
type ExtensionMode string
ExtensionMode is the run mode pi is operating in, exposed to extensions via Context.Mode(). Extensions guard terminal-only UI (custom components, dialogs) on mode == ModeTUI.
upstream: packages/coding-agent/src/core/extensions/types.ts:298 (`export type ExtensionMode = "tui" | "rpc" | "json" | "print"`)
const ( // ModeTUI is the interactive terminal UI. Set by interactive mode // (interactive-mode.ts:1511 `mode: "tui"`). ModeTUI ExtensionMode = "tui" // ModeRPC is the headless JSONL command/event loop. Set by rpc mode // (rpc-mode.ts:320 `mode: "rpc"`). ModeRPC ExtensionMode = "rpc" // ModeJSON is print mode emitting all events as JSON. Set by print // mode when its output mode is "json" (print-mode.ts:74). ModeJSON ExtensionMode = "json" // ModePrint is print mode emitting only the final text response. // The upstream Runner default (runner.ts:229). ModePrint ExtensionMode = "print" )
type ExtensionRuntime ¶
type ExtensionRuntime struct {
// contains filtered or unexported fields
}
ExtensionRuntime shares pending and bound provider actions between extension loading and the Runner. It stores no model catalog and does not execute factories.
func CreateExtensionRuntime ¶
func CreateExtensionRuntime() *ExtensionRuntime
CreateExtensionRuntime creates the pre-bind provider registration state.
func (*ExtensionRuntime) BindProviderActions ¶
func (r *ExtensionRuntime) BindProviderActions(actions ProviderActions, report func(*ExtensionError))
BindProviderActions drains the loading queue in order, reports each failure before continuing, and installs immediate actions. The owner serializes binding with other binds. Callbacks run outside state locks and may register or unregister providers.
func (*ExtensionRuntime) PendingProviderRegistrations ¶
func (r *ExtensionRuntime) PendingProviderRegistrations() []PendingProviderRegistration
PendingProviderRegistrations returns the current queue in registration order. Repeated provider names remain separate entries.
func (*ExtensionRuntime) RegisterProvider ¶
func (r *ExtensionRuntime) RegisterProvider(name string, config ProviderConfig, extensionPath ...string) error
RegisterProvider queues during loading and invokes the bound registry synchronously afterward. Configuration callbacks are retained, not serialized.
func (*ExtensionRuntime) UnregisterProvider ¶
func (r *ExtensionRuntime) UnregisterProvider(name string)
UnregisterProvider removes every queued registration of name before binding, and invokes the registry immediately afterward.
type ExtensionShortcut ¶
type ExtensionShortcut struct {
Shortcut KeyID `json:"shortcut"`
Description string `json:"description,omitempty"`
Handler ShortcutHandler `json:"-"`
ExtensionPath string `json:"extensionPath"`
}
ExtensionShortcut mirrors upstream's ExtensionShortcut: the loader's view of a registered shortcut, including its source extension.
type ExtensionUIDialogOptions ¶
type ExtensionUIDialogOptions = any
ExtensionUIDialogOptions mirrors upstream ExtensionUIDialogOptions.
type ExtensionWidgetOptions ¶
type ExtensionWidgetOptions = any
ExtensionWidgetOptions mirrors upstream ExtensionWidgetOptions.
type FindToolCallEvent ¶
type FindToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "find"
Input FindToolInput `json:"input"`
}
FindToolCallEvent: upstream types.ts FindToolCallEvent.
type FindToolDetails ¶
type FindToolDetails struct {
Truncation *ToolTruncation `json:"truncation,omitempty"`
ResultLimitReached *float64 `json:"resultLimitReached,omitempty"`
}
FindToolDetails mirrors upstream find.ts:32.
type FindToolInput ¶
type FindToolInput = any
type FindToolResultEvent ¶
type FindToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "find"
Details *FindToolDetails `json:"details,omitempty"`
}
FindToolResultEvent: upstream types.ts FindToolResultEvent.
type FlagOptions ¶
type FlagOptions struct {
Description string `json:"description,omitempty"`
Type FlagType `json:"type"`
// Default is bool when Type == FlagBoolean and string when
// Type == FlagString. Nil when no default.
Default any `json:"default,omitempty"`
}
FlagOptions is the registration payload for API.RegisterFlag. Mirrors the inline option object on upstream ExtensionAPI.registerFlag.
type FlagType ¶
type FlagType string
FlagType is the value type of a CLI flag registered by an extension. Mirrors upstream's "boolean" | "string" union.
type ForkOptions ¶
type ForkOptions struct {
Position string `json:"position,omitempty"` // "before" | "at"
WithSession func(*ReplacedSessionContext) error `json:"-"`
}
ForkOptions mirrors upstream's fork options.
upstream: types.ts:342-343
type GrepToolCallEvent ¶
type GrepToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "grep"
Input GrepToolInput `json:"input"`
}
GrepToolCallEvent: upstream types.ts GrepToolCallEvent.
type GrepToolDetails ¶
type GrepToolDetails struct {
Truncation *ToolTruncation `json:"truncation,omitempty"`
MatchLimitReached float64 `json:"matchLimitReached,omitempty"`
LinesTruncated bool `json:"linesTruncated,omitempty"`
}
GrepToolDetails mirrors upstream grep.ts:41. Sparse fields retain the requested numeric limit without rounding.
type GrepToolInput ¶
type GrepToolInput = any
type GrepToolResultEvent ¶
type GrepToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "grep"
Details *GrepToolDetails `json:"details,omitempty"`
}
GrepToolResultEvent: upstream types.ts GrepToolResultEvent.
type HandlerFn ¶
HandlerFn is the type-erased storage shape for event handlers.
The typed API methods (`OnToolCall`, `OnSessionStart`, ...) accept strongly-typed handler functions and wrap them into HandlerFn for storage in `Extension.Handlers`. The Runner reverses the wrap when dispatching: for each event firing, it looks up handlers by event name, calls each with the typed payload boxed as `any`, and casts the returned `any` back to the typed *EventResult shape.
This is the implementation detail of D1, which uses type erasure where Go cannot express upstream's generic event-handler map. Typed API methods and SDK helpers keep HandlerFn out of normal extension authoring.
upstream: types.ts:1380 (type HandlerFn = (...args: unknown[]) => Promise<unknown>)
type ImageContent ¶
type ImageContent = any
ImageContent mirrors @earendil-works/pi-ai ImageContent.
type InputEvent ¶
type InputEvent struct {
Type string `json:"type"`
Text string `json:"text"`
Images []ImageContent `json:"images,omitempty"`
Source InputSource `json:"source"`
// StreamingBehavior indicates context when input arrives during streaming.
// "steer" = mid-stream steer, "followUp" = queued follow-up.
// Empty when the agent is idle. Mirrors upstream v0.77.0.
StreamingBehavior string `json:"streamingBehavior,omitempty"`
}
InputEvent: upstream types.ts InputEvent.
type InputEventResult ¶
type InputEventResult interface {
// contains filtered or unexported methods
}
InputEventResult is the sealed union of handler responses for the "input" extension event. Mirrors upstream `types.ts InputEventResult`:
export type InputEventResult =
| { action: "continue" }
| { action: "transform"; text: string; images?: ImageContent[] }
| { action: "handled" };
The interface is package-sealed via the unexported `isInputEventResult` marker method: only the three variants in this package can satisfy it. Custom MarshalJSON/UnmarshalJSON in marshalling.go preserves upstream's `{"action": "..."}` discriminator wire shape.
Authors return one of:
- InputEventResultContinue (let the agent process the input as-is)
- InputEventResultTransform (replace input text/images before send)
- InputEventResultHandled (extension fully handled; skip agent)
upstream: types.ts:750
func UnmarshalInputEventResult ¶
func UnmarshalInputEventResult(data []byte) (InputEventResult, error)
UnmarshalInputEventResult parses upstream wire shape into the matching sealed-interface variant. Returns an error on unknown action discriminators so silent drift cannot enter the system.
type InputEventResultContinue ¶
type InputEventResultContinue struct{}
InputEventResultContinue: upstream `{ action: "continue" }`.
type InputEventResultHandled ¶
type InputEventResultHandled struct{}
InputEventResultHandled: upstream `{ action: "handled" }`. Tells the host the extension fully handled the input; the agent does NOT run for this turn.
type InputEventResultTransform ¶
type InputEventResultTransform struct {
Text string `json:"text"`
Images []ImageContent `json:"images,omitempty"`
}
InputEventResultTransform: upstream `{ action: "transform"; text: string; images?: ImageContent[] }`. Replaces the user input before it reaches the agent.
type InputSource ¶
type InputSource = string
InputSource mirrors upstream "interactive" | "rpc" | "extension".
const ( InputSourceUser InputSource = "interactive" InputSourceRPC InputSource = "rpc" InputSourceExtension InputSource = "extension" )
type KeyID ¶
type KeyID = string
KeyID identifies a keyboard shortcut. Mirrors @mariozechner/pi-tui KeyId, which is a string (e.g. "ctrl+shift+l", "alt+enter").
type KeybindingsManager ¶
type KeybindingsManager = any
KeybindingsManager mirrors core/keybindings.KeybindingsManager.
type LoginDefinition ¶
type LoginDefinition struct {
Brand []string `json:"brand"`
Hero []string `json:"hero"`
Mascot []string `json:"mascot"`
Palette map[string]string `json:"palette"`
Name string `json:"name"`
Description string `json:"description"`
Tagline string `json:"tagline"`
}
LoginDefinition describes one login using Pig's fixed native template. Grid cells are printable ASCII palette symbols; '.' is transparent.
type LoginDefinitionError ¶
LoginDefinitionError identifies the invalid field in a login definition.
func (*LoginDefinitionError) Error ¶
func (e *LoginDefinitionError) Error() string
type LsToolCallEvent ¶
type LsToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "ls"
Input LsToolInput `json:"input"`
}
LsToolCallEvent: upstream types.ts LsToolCallEvent.
type LsToolDetails ¶
type LsToolDetails struct {
Truncation *ToolTruncation `json:"truncation,omitempty"`
EntryLimitReached float64 `json:"entryLimitReached,omitempty"`
}
LsToolDetails mirrors upstream ls.ts:23, including fractional requested limits.
type LsToolInput ¶
type LsToolInput = any
type LsToolResultEvent ¶
type LsToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "ls"
Details *LsToolDetails `json:"details,omitempty"`
}
LsToolResultEvent: upstream types.ts LsToolResultEvent.
type MarkdownMessageType ¶
type MarkdownMessageType string
MarkdownMessageType identifies the transcript message being transformed for display. Transformers never change model context or persisted message data.
const ( MarkdownMessageUser MarkdownMessageType = "user" MarkdownMessageAssistant MarkdownMessageType = "assistant" // MarkdownMessageAssistantThinking marks the reasoning/thinking trace of an // assistant turn. Mirrors upstream MarkdownTransformContext.messageType // "assistant-thinking"; the built-in Mermaid transformer skips it. MarkdownMessageAssistantThinking MarkdownMessageType = "assistant-thinking" )
type MarkdownTransformContext ¶
type MarkdownTransformContext struct {
// Context owns the off-loop host generation; it is not part of Pi's wire context.
Context context.Context `json:"-"`
MessageType MarkdownMessageType `json:"messageType"`
IsStreaming bool `json:"isStreaming"`
AvailableWidth int `json:"availableWidth"`
}
MarkdownTransformContext mirrors upstream MarkdownTransformContext.
type MarkdownTransformer ¶
type MarkdownTransformer func(markdown string, context MarkdownTransformContext) string
MarkdownTransformer performs a synchronous display-only Markdown rewrite.
type MessageEndEvent ¶
type MessageEndEvent struct {
Type string `json:"type"`
Message AgentMessage `json:"message"`
}
MessageEndEvent: upstream types.ts MessageEndEvent.
type MessageEndEventResult ¶
type MessageEndEventResult struct {
// Message replaces the finalized message. Replacement must preserve role.
Message *AgentMessage `json:"message,omitempty"`
}
MessageEndEventResult mirrors upstream message_end handler result.
type MessageRenderOptions ¶
type MessageRenderOptions struct {
Expanded bool `json:"expanded"`
// OutputPad is the horizontal padding configured by the outputPad setting.
OutputPad int `json:"outputPad"`
}
MessageRenderOptions is passed to a MessageRenderer.
type MessageRenderer ¶
type MessageRenderer = func( message CustomMessage, options MessageRenderOptions, theme Theme, ) Component
MessageRenderer mirrors upstream MessageRenderer<T>. Renders a custom session message into a TUI Component, or returns nil to fall back to the default renderer.
The Go signature drops the TS generic parameter T: the message's data is carried on CustomMessage (currently `any`) and the renderer type-asserts as needed. This avoids the compilation explosion of N generic instantiations across the host package and matches how subprocess extensions see this surface (untyped JSON over the wire).
type MessageStartEvent ¶
type MessageStartEvent struct {
Type string `json:"type"`
Message AgentMessage `json:"message"`
}
MessageStartEvent: upstream types.ts MessageStartEvent.
type MessageUpdateEvent ¶
type MessageUpdateEvent struct {
Type string `json:"type"`
Message AgentMessage `json:"message"`
AssistantMessageEvent AssistantMessageEvent `json:"assistantMessageEvent"`
}
MessageUpdateEvent: upstream types.ts MessageUpdateEvent.
type ModelRegistry ¶
type ModelRegistry = any
ModelRegistry mirrors core/model-registry.ModelRegistry.
type ModelSelectEvent ¶
type ModelSelectEvent struct {
Type string `json:"type"`
Model Model `json:"model"`
PreviousModel Model `json:"previousModel,omitempty"`
Source ModelSelectSource `json:"source"`
}
ModelSelectEvent: upstream types.ts ModelSelectEvent.
type ModelSelectSource ¶
type ModelSelectSource = string
ModelSelectSource mirrors upstream "set" | "cycle" | "restore".
const ( ModelSelectSourceUser ModelSelectSource = "set" ModelSelectSourceCycle ModelSelectSource = "cycle" ModelSelectSourceRestore ModelSelectSource = "restore" )
type ModelStreamRequest ¶
type ModelStreamRequest struct {
API bool
Fetch *http.Client
OnPayload func(any, *ai.Model) (any, error)
OnResponse func(context.Context, ai.ProviderResponse, *ai.Model) error
TransformHeaders func(context.Context, ai.ProviderHeaders) (ai.ProviderHeaders, error)
}
ModelStreamRequest carries a resolved API-leaf request and connection-owned callbacks. API leaves use the caller's model/auth, not the parent catalog.
func ModelStreamRequestFromContext ¶
func ModelStreamRequestFromContext(ctx context.Context) ModelStreamRequest
ModelStreamRequestFromContext returns the transport contract for this operation.
type NativeProvider ¶
type NativeProvider struct {
// IsCurrent guards publication when host registrations overlap across connections.
IsCurrent func() bool
ID string
Name string
BaseURL string
Models []ProviderModelConfig
CheckAuth func(context.Context, *ai.Credential) (*ai.AuthCheck, error)
FilterModels func(context.Context, []ProviderModelConfig, *ai.Credential) ([]ProviderModelConfig, error)
ResolveAuth func(context.Context, *ai.Credential, ai.AuthResolutionOverrides) (*ai.AuthResult, *ai.Credential, error)
ResolveRefreshCredential func(context.Context, *ai.Credential) (*ai.Credential, *ai.Credential, error)
RefreshModels func(context.Context, *ai.Credential, *ai.ModelsStoreEntry, bool, *bool, func(NativeProviderPublication) error) ([]ProviderModelConfig, error)
Stream func(context.Context, *ai.Model, ai.TranscriptContext, ai.StreamOptions, bool) (*ai.AssistantMessageEventStream, error)
}
NativeProvider is a session-owned carrier for Pi's native Provider callbacks. Metadata is immutable; refresh publishes replacement model snapshots. The host owns credentials and persistence, and every callback receives its operation context.
type NativeProviderPublication ¶
type NativeProviderPublication struct {
Persist json.RawMessage `json:"persist,omitempty"`
Models *[]ProviderModelConfig `json:"models,omitempty"`
}
type NavigateTreeOptions ¶
type NavigateTreeOptions struct {
}
NavigateTreeOptions mirrors upstream's navigateTree options.
upstream: types.ts:347-351
type NewSessionOptions ¶
type NewSessionOptions struct {
ParentSession string `json:"parentSession,omitempty"`
Setup func(SessionManager) error `json:"-"`
WithSession func(*ReplacedSessionContext) error `json:"-"`
}
NewSessionOptions mirrors upstream's newSession parameter object.
upstream: types.ts:334-338 (ExtensionCommandContext.newSession options)
type OAuthCredentials ¶
type OAuthCredentials = any
OAuthCredentials mirrors @earendil-works/pi-ai OAuthCredentials.
type OAuthLoginCallbacks ¶
type OAuthLoginCallbacks = any
OAuthLoginCallbacks mirrors @earendil-works/pi-ai OAuthLoginCallbacks.
type OverlayHandle ¶
type OverlayHandle = any
OverlayHandle mirrors @earendil-works/pi-tui OverlayHandle.
type OverlayLayout ¶
type OverlayLayout struct {
Width *OverlaySizeValue `json:"width,omitempty"`
MinWidth *int `json:"minWidth,omitempty"`
MaxHeight *OverlaySizeValue `json:"maxHeight,omitempty"`
Anchor string `json:"anchor,omitempty"`
OffsetX int `json:"offsetX,omitempty"`
OffsetY int `json:"offsetY,omitempty"`
Row *OverlaySizeValue `json:"row,omitempty"`
Col *OverlaySizeValue `json:"col,omitempty"`
Margin *OverlayMarginValue `json:"margin,omitempty"`
NonCapturing bool `json:"nonCapturing,omitempty"`
}
OverlayLayout is the serialisable subset of upstream pi-tui OverlayOptions: every field except the visible callback.
type OverlayMarginValue ¶
OverlayMarginValue is upstream `OverlayMargin | number`.
func (OverlayMarginValue) MarshalJSON ¶
func (m OverlayMarginValue) MarshalJSON() ([]byte, error)
func (*OverlayMarginValue) UnmarshalJSON ¶
func (m *OverlayMarginValue) UnmarshalJSON(data []byte) error
type OverlayOptions ¶
type OverlayOptions = any
OverlayOptions mirrors @earendil-works/pi-tui OverlayOptions.
type OverlaySizeValue ¶
OverlaySizeValue is upstream SizeValue: a cell count or an "N%" string. A string that is not a percentage is kept with Invalid set, matching upstream parseSizeValue returning undefined.
func (OverlaySizeValue) MarshalJSON ¶
func (v OverlaySizeValue) MarshalJSON() ([]byte, error)
func (*OverlaySizeValue) UnmarshalJSON ¶
func (v *OverlaySizeValue) UnmarshalJSON(data []byte) error
type PendingProviderRegistration ¶
type PendingProviderRegistration struct {
Name string
Config ProviderConfig
ExtensionPath string
}
PendingProviderRegistration retains the configuration and its owning extension until the registry is bound.
type PowerShellToolCallEvent ¶
type PowerShellToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "powershell"
Input PowerShellToolInput `json:"input"`
}
PowerShellToolCallEvent: upstream types.ts PowerShellToolCallEvent.
type PowerShellToolDetails ¶
type PowerShellToolDetails = BashToolDetails
PowerShellToolDetails is the bash details shape (upstream powershell.ts).
type PowerShellToolInput ¶
type PowerShellToolInput = BashToolInput
PowerShellToolInput is the bash input shape (upstream powershell.ts).
type PowerShellToolResultEvent ¶
type PowerShellToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "powershell"
Details *PowerShellToolDetails `json:"details,omitempty"`
}
PowerShellToolResultEvent: upstream types.ts PowerShellToolResultEvent.
type ProjectTrustEvent ¶
type ProjectTrustEvent struct {
Type string `json:"type"` // "project_trust"
Cwd string `json:"cwd"`
}
ProjectTrustEvent: upstream types.ts ProjectTrustEvent. Fired before project-local inputs load so a global/CLI extension can decide trust.
type ProjectTrustEventDecision ¶
type ProjectTrustEventDecision string
ProjectTrustEventDecision is an extension's trust verdict for a project. Values: "yes" | "no" | "undecided". Mirrors upstream ProjectTrustEventDecision.
const ( ProjectTrustYes ProjectTrustEventDecision = "yes" ProjectTrustNo ProjectTrustEventDecision = "no" ProjectTrustUndecided ProjectTrustEventDecision = "undecided" )
type ProjectTrustEventResult ¶
type ProjectTrustEventResult struct {
Trusted ProjectTrustEventDecision `json:"trusted"`
Remember *bool `json:"remember,omitempty"`
}
ProjectTrustEventResult: upstream types.ts ProjectTrustEventResult. The first handler returning yes/no wins; undecided falls through.
type ProjectedSessionEntry ¶
type ProjectedSessionEntry struct {
SourceEntry any `json:"sourceEntry"`
Messages []AgentMessage `json:"messages"`
}
ProjectedSessionEntry is one boundary preview entry and its model-visible messages.
type ProviderActions ¶
type ProviderActions struct {
RegisterProvider func(name string, config ProviderConfig) error
UnregisterProvider func(name string)
}
ProviderActions supplies synchronous provider registration callbacks. Registration errors are reported per queued entry during binding and returned directly for post-bind calls. upstream: packages/coding-agent/src/core/extensions/runner.ts:bindCore
type ProviderConfig ¶
type ProviderConfig struct {
Name string `json:"name,omitempty"`
BaseURL string `json:"baseUrl,omitempty"`
APIKey string `json:"apiKey,omitempty"`
API ai.API `json:"api,omitempty"`
StreamSimple ProviderStreamSimple `json:"-"`
Headers map[string]string `json:"headers,omitempty"`
AuthHeader bool `json:"authHeader,omitempty"`
Models []ProviderModelConfig `json:"models,omitempty"`
OAuth *ProviderOAuth `json:"oauth,omitempty"`
// Insecure skips TLS certificate verification for this provider's
// endpoint. Opt-in only, for self-signed/internal-CA on-prem gateways.
// pig additive (D36): additive optional field; no upstream per-provider TLS-skip.
Insecure bool `json:"insecure,omitempty"`
// contains filtered or unexported fields
}
ProviderConfig is the registration payload for API.RegisterProvider. Mirrors upstream's ProviderConfig 1:1.
Field semantics (from upstream JSDoc):
- If Models is provided: replaces all existing models for this provider.
- If only BaseURL is provided: overrides the URL for existing models.
- If OAuth is provided: registers OAuth provider for /login support.
- If StreamSimple is provided: registers a custom API stream handler.
func (ProviderConfig) MarshalJSON ¶
func (config ProviderConfig) MarshalJSON() ([]byte, error)
func (*ProviderConfig) UnmarshalJSON ¶
func (config *ProviderConfig) UnmarshalJSON(data []byte) error
type ProviderHeaders ¶
ProviderHeaders mirrors upstream pi-ai ProviderHeaders (`Record<string, string | null>`): a nil value signals "delete this header".
type ProviderModelConfig ¶
type ProviderModelConfig struct {
ID string `json:"id"`
Name string `json:"name"`
API ai.API `json:"api,omitempty"`
BaseURL string `json:"baseUrl,omitempty"`
Reasoning bool `json:"reasoning"`
ThinkingLevelMap ai.ThinkingLevelMap `json:"thinkingLevelMap,omitempty"`
Input []string `json:"input"`
// InputLimits is upstream's provider input limits and cache-safe image
// preprocessing metadata.
InputLimits *ai.ModelInputLimits `json:"inputLimits,omitempty"`
Cost ProviderModelCost `json:"cost"`
// PromptCache is upstream's best-effort prompt cache lifetime in seconds
// per retention tier.
PromptCache ai.ModelPromptCache `json:"promptCache,omitempty"`
SamplingParams map[string]any `json:"samplingParams,omitempty"`
ContextWindow int `json:"contextWindow"`
MaxTokens int `json:"maxTokens"`
Headers map[string]string `json:"headers,omitempty"`
Compat any `json:"compat,omitempty"`
// contains filtered or unexported fields
}
ProviderModelConfig mirrors upstream ProviderModelConfig 1:1.
func (ProviderModelConfig) MarshalJSON ¶
func (config ProviderModelConfig) MarshalJSON() ([]byte, error)
func (*ProviderModelConfig) UnmarshalJSON ¶
func (config *ProviderModelConfig) UnmarshalJSON(data []byte) error
type ProviderModelCost ¶
type ProviderModelCost struct {
Input float64 `json:"input"`
Output float64 `json:"output"`
CacheRead float64 `json:"cacheRead"`
CacheWrite float64 `json:"cacheWrite"`
Tiers []ai.CostTier `json:"tiers,omitzero"`
}
ProviderModelCost mirrors upstream ProviderModelConfig.cost.
type ProviderOAuth ¶
type ProviderOAuth struct {
Name string `json:"name"`
// IsSubscription marks access through this OAuth method as subscription-backed.
IsSubscription bool `json:"isSubscription,omitempty"`
Login func(callbacks OAuthLoginCallbacks) (OAuthCredentials, error) `json:"-"`
RefreshToken func(creds OAuthCredentials) (OAuthCredentials, error) `json:"-"`
GetAPIKey func(creds OAuthCredentials) string `json:"-"`
ModifyModels func(models []Model, creds OAuthCredentials) []Model `json:"-"`
}
ProviderOAuth mirrors upstream ProviderConfig.oauth.
type ProviderStreamSimple ¶
type ProviderStreamSimple = func(model Model, ctx AIContext, opts SimpleStreamOptions) AssistantMessageEventStream
ProviderStreamSimple mirrors upstream's optional streamSimple callback. The callback's model, request context, options, and event stream remain opaque at this dynamic extension boundary.
type ReadToolCallEvent ¶
type ReadToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "read"
Input ReadToolInput `json:"input"`
}
ReadToolCallEvent: upstream types.ts ReadToolCallEvent.
type ReadToolDetails ¶
type ReadToolDetails struct {
Truncation *ToolTruncation `json:"truncation,omitempty"`
}
ReadToolDetails mirrors upstream read.ts:28. Attached only when output was truncated (or the first line exceeded the byte limit).
type ReadToolInput ¶
type ReadToolInput = any
type ReadToolResultEvent ¶
type ReadToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "read"
Details *ReadToolDetails `json:"details,omitempty"`
}
ReadToolResultEvent: upstream types.ts ReadToolResultEvent.
type ReadonlyFooterDataProvider ¶
type ReadonlyFooterDataProvider = any
ReadonlyFooterDataProvider mirrors core/footer-data-provider.
type ReadonlySessionManager ¶
type ReadonlySessionManager = any
ReadonlySessionManager mirrors core/session-manager ReadonlySessionManager.
type RegisteredCommand ¶
type RegisteredCommand struct {
Name string `json:"name"`
SourceInfo SourceInfo `json:"sourceInfo"`
Description string `json:"description,omitempty"`
GetArgumentCompletions ArgumentCompletionsFunc `json:"-"`
Handler CommandHandler `json:"-"`
}
RegisteredCommand mirrors upstream RegisteredCommand. The host's view of a command after registration.
type RegisteredTool ¶
type RegisteredTool struct {
Definition ToolDefinition `json:"definition"`
SourceInfo SourceInfo `json:"sourceInfo"`
}
RegisteredTool mirrors upstream RegisteredTool: the host's bookkeeping after a tool is registered.
type RemoteEditor ¶
type RemoteEditor interface {
// Input delivers one keystroke to the editor's handleInput.
Input(data string)
// SetText, InsertTextAtCursor and AddToHistory call the editor's
// methods of the same name, as Pi's host calls them on this.editor.
SetText(text string)
InsertTextAtCursor(text string)
AddToHistory(text string)
// Mouse delivers a left click on the editor rows to the editor's
// handleMouse, as Pi's fullscreen renderer does.
Mouse(event RemoteEditorMouseEvent)
// Configure applies host editor state to the editor: Pi copies the
// default editor's text, padding and autocomplete size when it installs
// the editor, and the TUI sets its focus.
Configure(config RemoteEditorConfig)
// Bind attaches the host that receives the editor's frames and
// callbacks. Events that arrive before Bind are delivered on binding.
Bind(host RemoteEditorHost)
// Close detaches the editor from the host.
Close()
}
RemoteEditor is an editor an extension installed with ctx.ui.setEditorComponent, running in the extension's process. Pi puts the factory's editor (typically a CustomEditor subclass) in place of its own: every keystroke goes to that editor's handleInput, its render output is the editor on screen, and Pi wires the editor's callbacks to its own handlers. The host does the same across the process boundary: it hands the editor every keystroke and every text change it makes, shows the editor's frames, and receives the editor's callbacks through the bound RemoteEditorHost.
UIContext.SetEditorComponent receives a RemoteEditor; nil restores the host's own editor.
type RemoteEditorAction ¶
type RemoteEditorAction struct {
Action string `json:"action"`
Text string `json:"text"`
Expanded string `json:"expanded"`
Local bool `json:"local"`
}
RemoteEditorAction snapshots the editor at the app-action boundary. Local means the component already applied the synchronous editor mutations; the host must not replay them into that component.
type RemoteEditorConfig ¶
type RemoteEditorConfig struct {
PaddingX int `json:"paddingX"`
AutocompleteMaxVisible int `json:"autocompleteMaxVisible"`
Focused bool `json:"focused"`
// ThinkingLevel is the session's thinking level, whose border color Pi
// gives the editor outside bash mode.
ThinkingLevel string `json:"thinkingLevel"`
// ShowHardwareCursor is the TUI's hardware-cursor setting, which the
// editor's tui.getShowHardwareCursor() reports.
ShowHardwareCursor bool `json:"showHardwareCursor"`
// Shortcuts are the key ids of the extension shortcuts Pi's
// onExtensionShortcut runs from inside the editor.
Shortcuts []string `json:"shortcuts"`
Streaming bool `json:"streaming"`
Compacting bool `json:"compacting"`
BashRunning bool `json:"bashRunning"`
InterruptHandled bool `json:"interruptHandled"`
}
RemoteEditorConfig is the host editor state an RemoteEditor mirrors.
type RemoteEditorHost ¶
type RemoteEditorHost interface {
// EditorFrame is the editor's render(width) output for the terminal
// width. WantsKeyRelease is the editor's wantsKeyRelease flag.
EditorFrame(lines []string, width int, wantsKeyRelease bool)
// EditorChanged is the editor's onChange: its text and, for the host's
// getEditorText, the text with paste markers expanded.
EditorChanged(text, expanded string)
// EditorSubmit is the editor's onSubmit. done runs once the host has
// handled the submission, which settles the promise onSubmit returns.
EditorSubmit(text string, done func())
// EditorAction runs Pi's handler for an app action the editor
// dispatched: app.interrupt (onEscape), app.exit (onCtrlD),
// app.clipboard.pasteImage (onPasteImage), or an actionHandlers entry.
EditorAction(action RemoteEditorAction)
// EditorInputDone releases input backpressure after the key's callbacks have reached the host.
EditorInputDone()
// EditorShortcut runs the extension shortcut the editor's
// onExtensionShortcut matched for data.
EditorShortcut(data string)
// TerminalWrite writes raw output to the terminal (tui.terminal.write).
TerminalWrite(data string)
// SetShowHardwareCursor is tui.setShowHardwareCursor.
SetShowHardwareCursor(enabled bool)
// EditorClosed reports that the extension's editor is gone (its process
// ended); the host restores its own editor.
EditorClosed()
}
RemoteEditorHost receives an RemoteEditor's output. The bridge calls it off the host's UI loop, in the order the extension produced the events.
type RemoteEditorMouseEvent ¶
type RemoteEditorMouseEvent struct {
Type string `json:"type"`
Button string `json:"button"`
X int `json:"x"`
Y int `json:"y"`
ScreenX int `json:"screenX"`
ScreenY int `json:"screenY"`
Width int `json:"width"`
Height int `json:"height"`
Shift bool `json:"shift"`
Alt bool `json:"alt"`
Ctrl bool `json:"ctrl"`
ClickCount int `json:"clickCount,omitempty"`
}
RemoteEditorMouseEvent is pi-tui's TuiMouseEvent, with the row relative to the editor's first row.
type RemoteOverlayBounds ¶
type RemoteOverlayBounds struct {
Row int `json:"row"`
Col int `json:"col"`
Width int `json:"width"`
Height int `json:"height"`
}
RemoteOverlayBounds is the last rendered terminal-relative rectangle.
type RemoteOverlayFocusTarget ¶
RemoteOverlayFocusTarget is an explicit OverlayHandle.unfocus target resolved by the host. The zero value is Pi's null target. Overlay is another mounted overlay of the same extension, as the host registered it; Editor selects the main editor component.
type RemoteOverlayHandle ¶
type RemoteOverlayHandle interface {
// UpdateLines replaces the overlay's cached lines and triggers
// a TUI render. Safe to call from any goroutine.
UpdateLines(lines []string)
// Close signals that the overlay is finished and unblocks the
// originating [UIContext.RunRemoteOverlay] call with the given
// result value. Safe to call from any goroutine.
Close(result any)
}
RemoteOverlayHandle is returned to the caller of UIContext.RunRemoteOverlay so it can push rendered lines into the overlay and close it when the remote producer signals completion.
pig-specific: no upstream equivalent.
type RemoteOverlayHost ¶
type RemoteOverlayHost interface {
// OnInput is invoked for every input chunk (a single key event
// after [tui.ReadInput] segmentation) while the overlay is
// open. Called from the input-reading goroutine.
OnInput(data string)
}
RemoteOverlayHost is the callback surface the bridge provides so the overlay can forward user input back to the remote producer.
pig-specific: no upstream equivalent.
type RemoteOverlayOptions ¶
type RemoteOverlayOptions struct {
// Title is the overlay's titlebar text. Empty hides the bar.
Title string `json:"title,omitempty"`
// WidthFraction is the fraction of terminal width the overlay
// should occupy. Zero falls back to the overlay default.
WidthFraction float64 `json:"widthFraction,omitempty"`
// HeightFraction is the fraction of terminal height the
// overlay should occupy. Zero falls back to the overlay default.
HeightFraction float64 `json:"heightFraction,omitempty"`
// Overlay opens a floating viewport overlay over the whole screen
// instead of replacing the inline editor slot. Mirrors upstream
// ui.custom()'s `overlay: true`. When false the component replaces
// the editor slot.
Overlay bool `json:"overlay,omitempty"`
// Layout carries upstream ui.custom()'s overlayOptions (the pi-tui
// OverlayOptions fields that can cross a process boundary). When set, or
// when no legacy Title/fractions are given, an overlay is mounted
// component-framed with exactly upstream's showOverlay geometry.
Layout *OverlayLayout `json:"overlayOptions,omitempty"`
}
RemoteOverlayOptions controls how a remote (subprocess-backed) overlay is positioned and sized when the host opens it.
Upstream's `ui.custom()` takes an `overlay` boolean plus an `OverlayOptions` value. The OverlayOptions reference TUI primitives that cannot cross a process boundary, so the subprocess bridge ports the overlay flag and the size/position fields into this serialisable struct.
type RemoteOverlayState ¶
type RemoteOverlayState struct {
Hidden bool `json:"hidden"`
Focused bool `json:"focused"`
Visible bool `json:"visible"`
Bounds *RemoteOverlayBounds `json:"bounds,omitempty"`
}
RemoteOverlayState is the host's mounted-overlay state at a control/input boundary.
type RemoteTerminalInputHandler ¶
type RemoteTerminalInputHandler = func(ctx context.Context, data string) TerminalInputResult
RemoteTerminalInputHandler asks a terminal-input listener that runs in another process for its verdict on one chunk. It blocks until the verdict arrives, the connection fails, or ctx ends. A failure returns the zero result, which leaves the input unchanged.
pig additive (D19): upstream's TerminalInputHandler answers synchronously in process. A subprocess listener's answer crosses a socket, so the host calls this off its input loop.
type ReplacedSessionContext ¶
type ReplacedSessionContext struct {
*CommandContext
// contains filtered or unexported fields
}
ReplacedSessionContext is the fresh command-capable context supplied after Session replacement and host rebinding. Its message methods await the Session operation rather than launching extension-owned background work.
func NewReplacedSessionContext ¶
func NewReplacedSessionContext(command *CommandContext, sendMessage func(CustomMessageRef, *SendMessageOptions) error, sendUserMessage func(any, *ReplacedSessionSendUserMessageOptions) error) *ReplacedSessionContext
NewReplacedSessionContext binds the replacement Session's direct, awaited message operations to its command context.
func (*ReplacedSessionContext) SendMessage ¶
func (c *ReplacedSessionContext) SendMessage(message CustomMessageRef, options *SendMessageOptions) error
SendMessage awaits custom-message persistence and any triggered turn.
func (*ReplacedSessionContext) SendUserMessage ¶
func (c *ReplacedSessionContext) SendUserMessage(content any, options *ReplacedSessionSendUserMessageOptions) error
SendUserMessage awaits input handling and the selected prompt or queue operation.
type ReplacedSessionSendUserMessageOptions ¶
type ReplacedSessionSendUserMessageOptions = SendUserMessageOptions
ReplacedSessionSendUserMessageOptions controls the awaited user-message operation on a replacement context. Template and command expansion default to false.
type ResolvedCommand ¶
type ResolvedCommand struct {
RegisteredCommand
InvocationName string `json:"invocationName"`
}
ResolvedCommand mirrors upstream ResolvedCommand: RegisteredCommand plus the name under which it was actually invoked (which can differ from Name when the command exposes aliases).
type ResourceCollision ¶
type ResourceCollision struct {
ResourceType string `json:"resourceType"`
Name string `json:"name"`
WinnerPath string `json:"winnerPath"`
LoserPath string `json:"loserPath"`
WinnerSource string `json:"winnerSource,omitempty"`
LoserSource string `json:"loserSource,omitempty"`
}
ResourceDiagnostic is the resolution-time warning/error/collision payload surfaced by the runner when extension resources (commands, shortcuts, flags, future: skills/prompts/themes) collide or fail to resolve cleanly.
upstream: core/diagnostics.ts:10-16 (export interface ResourceDiagnostic)
Final-home note. Upstream lives in `core/diagnostics.ts` because the type is shared between the extension runner and the resource loader (skills/prompts/themes). Until pig ports `core/resource-loader.ts` the type lives here in `coding/extension` to keep the dependency graph minimal. When that port lands, the canonical declaration moves to `coding/diagnostics/` and this declaration becomes a type alias for backward compatibility.
type ResourceDiagnostic ¶
type ResourceDiagnostic struct {
// Type is one of "warning", "error", "collision". Mirrors the
// upstream literal union. Not enforced by the Go type system -
// callers are expected to use the constants below.
Type string `json:"type"`
// Message is the human-readable diagnostic text. Format matches
// upstream verbatim where the diagnostic is user-visible (e.g.
// shortcut/command collision strings) so no fidelity drift in
// diagnostic UIs.
Message string `json:"message"`
// Path is the extension's resolvedPath for attribution. Optional;
// upstream uses `path?: string`.
Path string `json:"path,omitempty"`
// Collision carries structured details when Type == "collision".
// upstream: ResourceCollision in core/diagnostics.ts.
Collision *ResourceCollision `json:"collision,omitempty"`
}
type ResourcesDiscoverAggregateResult ¶
type ResourcesDiscoverAggregateResult struct {
SkillPaths []AttributedResourcePath `json:"skillPaths"`
PromptPaths []AttributedResourcePath `json:"promptPaths"`
ThemePaths []AttributedResourcePath `json:"themePaths"`
}
ResourcesDiscoverAggregateResult is the combined output of all resources_discover handlers, with each path attributed to its source extension.
upstream: anonymous return type at runner.ts:944-948
type ResourcesDiscoverEvent ¶
type ResourcesDiscoverEvent struct {
Type string `json:"type"`
Cwd string `json:"cwd"`
Reason string `json:"reason"` // "startup" | "reload"
}
ResourcesDiscoverEvent: upstream types.ts ResourcesDiscoverEvent. Fired after session_start to allow extensions to provide additional resource paths.
type ResourcesDiscoverResult ¶
type ResourcesDiscoverResult struct {
SkillPaths []string `json:"skillPaths,omitempty"`
PromptPaths []string `json:"promptPaths,omitempty"`
ThemePaths []string `json:"themePaths,omitempty"`
}
ResourcesDiscoverResult: upstream types.ts ResourcesDiscoverResult.
type ScopedModel ¶
type ScopedModel struct {
Model *ai.Model
ThinkingLevel ai.ThinkingLevel
}
Ports packages/coding-agent/src/core/model-resolver.ts. ScopedModel is a resolved member of the session's model scope. An absent thinking level supplies no per-scope override when cycling.
type SendMessageOptions ¶
type SendMessageOptions struct {
TriggerTurn *bool `json:"triggerTurn,omitempty"`
DeliverAs DeliverAs `json:"deliverAs,omitempty"`
}
SendMessageOptions mirrors the inline options object on sendMessage.
upstream: types.ts:1161–1162
type SendMessagePayload ¶
type SendMessagePayload struct {
CustomType string `json:"customType"`
// Content preserves upstream CustomMessage content across the dynamic
// extension boundary.
Content any `json:"content,omitempty"`
Display any `json:"display,omitempty"`
Details any `json:"details,omitempty"`
}
SendMessagePayload mirrors the inline `Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">` parameter on upstream's sendMessage.
upstream: types.ts:1159–1163
type SendUserMessageHandler ¶
type SendUserMessageHandler func(content any, options *SendUserMessageOptions) error
SendUserMessageHandler injects a user message into the agent loop. content is upstream's `string | (TextContent | ImageContent)[]` union; current in-process callers use strings, while unsupported content shapes should fail at the host boundary.
upstream: types.ts:1525-1528 Go returns error so hosts can surface invalid content/delivery modes loudly instead of dropping extension calls on the floor.
type SendUserMessageOptions ¶
type SendUserMessageOptions struct {
DeliverAs DeliverAs `json:"deliverAs,omitempty"`
ExpandPromptTemplates *bool `json:"expandPromptTemplates,omitempty"`
}
SendUserMessageOptions mirrors the inline options object on sendUserMessage. Note upstream restricts DeliverAs to {steer, followUp}; the type is shared, but DeliverAsNextTurn is invalid here and the host rejects it at runtime.
upstream: types.ts:1170–1171
type SessionBeforeCompactEvent ¶
type SessionBeforeCompactEvent struct {
Type string `json:"type"`
Preparation CompactionPreparation `json:"preparation"`
BranchEntries []SessionEntry `json:"branchEntries"`
CustomInstructions string `json:"customInstructions,omitempty"`
// reason/willRetry adopted upstream in 0.80.3.
Reason string `json:"reason"`
WillRetry bool `json:"willRetry"`
Signal context.Context `json:"-"`
}
SessionBeforeCompactEvent: upstream types.ts SessionBeforeCompactEvent.
Signal carries the upstream AbortSignal through Go's context.Context.
type SessionBeforeCompactResult ¶
type SessionBeforeCompactResult struct {
Cancel bool `json:"cancel,omitempty"`
Compaction CompactionResult `json:"compaction,omitempty"`
}
SessionBeforeCompactResult: upstream types.ts SessionBeforeCompactResult.
type SessionBeforeForkEvent ¶
type SessionBeforeForkEvent struct {
Type string `json:"type"`
EntryID string `json:"entryId"`
Position string `json:"position"` // "before" | "at"
}
SessionBeforeForkEvent: upstream types.ts SessionBeforeForkEvent.
type SessionBeforeForkResult ¶
type SessionBeforeForkResult struct {
Cancel bool `json:"cancel,omitempty"`
SkipConversationRestore bool `json:"skipConversationRestore,omitempty"`
}
SessionBeforeForkResult: upstream types.ts SessionBeforeForkResult.
type SessionBeforeSwitchEvent ¶
type SessionBeforeSwitchEvent struct {
Type string `json:"type"`
Reason string `json:"reason"` // "new" | "resume"
TargetSessionFile string `json:"targetSessionFile,omitempty"`
}
SessionBeforeSwitchEvent: upstream types.ts SessionBeforeSwitchEvent.
type SessionBeforeSwitchResult ¶
type SessionBeforeSwitchResult struct {
Cancel bool `json:"cancel,omitempty"`
}
SessionBeforeSwitchResult: upstream types.ts SessionBeforeSwitchResult.
type SessionBeforeTreeEvent ¶
type SessionBeforeTreeEvent struct {
Type string `json:"type"`
Preparation TreePreparation `json:"preparation"`
Signal context.Context `json:"-"`
}
SessionBeforeTreeEvent: upstream types.ts SessionBeforeTreeEvent.
Signal carries the upstream AbortSignal through Go's context.Context.
type SessionBeforeTreeResult ¶
type SessionBeforeTreeResult struct {
Cancel bool `json:"cancel,omitempty"`
Summary *SessionBeforeTreeResultSummary `json:"summary,omitempty"`
CustomInstructions string `json:"customInstructions,omitempty"`
ReplaceInstructions bool `json:"replaceInstructions,omitempty"`
Label string `json:"label,omitempty"`
}
SessionBeforeTreeResult: upstream types.ts SessionBeforeTreeResult.
type SessionBeforeTreeResultSummary ¶
type SessionBeforeTreeResultSummary struct {
Summary string `json:"summary"`
Details any `json:"details,omitempty"`
// Usage is the pi-ai Usage of the extension's summarization call.
Usage any `json:"usage,omitempty"`
}
SessionBeforeTreeResultSummary mirrors the inline `summary` object on upstream's SessionBeforeTreeResult.
type SessionBoundaryDraft ¶
type SessionBoundaryDraft struct {
Type string `json:"type"`
CustomType string `json:"customType,omitempty"`
Data any `json:"data,omitempty"`
Content any `json:"content,omitempty"`
Display bool `json:"display,omitempty"`
Details any `json:"details,omitempty"`
TargetID string `json:"targetId,omitempty"`
Replacement json.RawMessage `json:"replacement,omitempty"`
Summary string `json:"summary,omitempty"`
FirstKeptEntryID *string `json:"firstKeptEntryId,omitempty"`
Usage *ai.Usage `json:"usage,omitempty"`
}
SessionBoundaryDraft is the wire representation of upstream's closed SessionBoundaryDraft union. Fields apply according to Type.
func (SessionBoundaryDraft) MarshalJSON ¶
func (d SessionBoundaryDraft) MarshalJSON() ([]byte, error)
MarshalJSON preserves each upstream union member's required fields, including null firstKeptEntryId and replacement values.
type SessionCompactEvent ¶
type SessionCompactEvent struct {
Type string `json:"type"`
CompactionEntry CompactionEntry `json:"compactionEntry"`
FromExtension bool `json:"fromExtension"`
// reason/willRetry adopted upstream in 0.80.3.
Reason string `json:"reason"`
WillRetry bool `json:"willRetry"`
}
SessionCompactEvent: upstream types.ts SessionCompactEvent.
type SessionCompactFailedEvent ¶
type SessionCompactFailedEvent struct {
Type string `json:"type"`
// Reason is what triggered the compaction: "manual" (/compact),
// "threshold" (the context threshold), or "overflow" (context overflow
// recovery).
Reason string `json:"reason"`
// ErrorMessage is the error text when compaction failed for a
// non-abort reason.
ErrorMessage string `json:"errorMessage,omitempty"`
// Aborted is true when compaction was cancelled or aborted.
Aborted bool `json:"aborted"`
// WillRetry is true when the aborted turn would have been retried after
// this compaction (overflow recovery).
WillRetry bool `json:"willRetry"`
// FromExtension is true when the failing compaction content came from a
// session_before_compact handler.
FromExtension bool `json:"fromExtension"`
}
SessionCompactFailedEvent: upstream types.ts SessionCompactFailedEvent. Fired after context compaction fails or is aborted.
type SessionInfoChangedEvent ¶
type SessionInfoChangedEvent struct {
Type string `json:"type"`
Name string `json:"name,omitempty"`
}
SessionInfoChangedEvent: upstream types.ts SessionInfoChangedEvent (adopted upstream in 0.80.3).
type SessionManager ¶
type SessionManager = any
SessionManager mirrors core/session-manager SessionManager.
type SessionShutdownEvent ¶
type SessionShutdownEvent struct {
Type string `json:"type"`
Reason string `json:"reason"` // "quit" | "reload" | "new" | "resume" | "fork"
TargetSessionFile string `json:"targetSessionFile,omitempty"`
}
SessionShutdownEvent: upstream types.ts SessionShutdownEvent.
type SessionStartEvent ¶
type SessionStartEvent struct {
Type string `json:"type"`
Reason string `json:"reason"` // "startup" | "reload" | "new" | "resume" | "fork"
PreviousSessionFile string `json:"previousSessionFile,omitempty"`
}
SessionStartEvent: upstream types.ts SessionStartEvent.
type SessionTreeEvent ¶
type SessionTreeEvent struct {
Type string `json:"type"`
NewLeafID *string `json:"newLeafId"`
OldLeafID *string `json:"oldLeafId"`
SummaryEntry BranchSummaryEntry `json:"summaryEntry,omitempty"`
FromExtension bool `json:"fromExtension,omitempty"`
}
SessionTreeEvent: upstream types.ts SessionTreeEvent.
NewLeafID and OldLeafID are upstream `string | null` (NOT optional). The difference between "null" and "absent" matters for wire-format round-trip through session JSONL: upstream always emits the keys, with `null` when no leaf. We use *string so json.Marshal emits null on nil and so the distinction survives a marshal/unmarshal cycle.
type SetThemeResult ¶
SetThemeResult mirrors the inline return type of `ExtensionUIContext.setTheme` (types.ts:262: `{ success, error? }`). Promoted to a named type because the inline TS object literal needs a Go-level identifier; field shape matches verbatim.
type ShortcutHandler ¶
ShortcutHandler is invoked when a registered shortcut fires. Mirrors upstream `ExtensionAPI.registerShortcut.handler` signature.
ShortcutHandler receives cancellation and per-extension values through the Go context. Use FromContext to access the extension context.
type ShortcutOptions ¶
type ShortcutOptions struct {
Description string `json:"description,omitempty"`
Handler ShortcutHandler `json:"-"`
}
ShortcutOptions is the registration payload for API.RegisterShortcut.
type SimpleStreamOptions ¶
type SimpleStreamOptions = any
SimpleStreamOptions mirrors @earendil-works/pi-ai SimpleStreamOptions.
type SlashCommandInfo ¶
type SlashCommandInfo = any
SlashCommandInfo mirrors core/slash-commands.SlashCommandInfo.
type StackError ¶
StackError is an error that carries the stack of the failure it reports, such as a JavaScript error's `stack` or a recovered Go panic's stack.
type SwitchSessionOptions ¶
type SwitchSessionOptions struct {
WithSession func(*ReplacedSessionContext) error `json:"-"`
}
SwitchSessionOptions mirrors upstream's switchSession options.
upstream: types.ts:354-356
type SystemPromptContextFile ¶
SystemPromptContextFile mirrors the upstream anonymous `{ path: string; content: string }` element of contextFiles.
upstream: packages/coding-agent/src/core/system-prompt.ts:22
type SystemPromptSkill ¶
type SystemPromptSkill struct {
Name string `json:"name"`
Description string `json:"description"`
FilePath string `json:"filePath"`
BaseDir string `json:"baseDir"`
SourceInfo SourceInfo `json:"sourceInfo,omitempty"`
DisableModelInvocation bool `json:"disableModelInvocation"`
}
SystemPromptSkill mirrors the upstream `Skill` interface fields that extensions can rely on. Extensions inspect skill metadata; the physical SkillFrontmatter is not exposed.
upstream: packages/coding-agent/src/core/skills.ts:74-82 Skill
type TerminalInputHandler ¶
type TerminalInputHandler = func(data string) TerminalInputResult
TerminalInputHandler mirrors upstream `TerminalInputHandler` (types.ts:120): raw terminal byte handler for interactive mode. Returns a result indicating whether to consume the input.
type TerminalInputResult ¶
type TerminalInputResult struct {
Consume bool // true → swallow the keystroke, don't process further
Data *string // replacement data (nil = no replacement)
}
TerminalInputResult is the return value from a TerminalInputHandler. Mirrors upstream `{ consume?: boolean; data?: string }`. A nil Data leaves the input unchanged; a non-nil Data replaces it for later listeners and for normal handling, and an empty replacement drops it.
type ThemeMeta ¶
ThemeMeta mirrors the inline return-element type of `ExtensionUIContext.getAllThemes` (types.ts:257 - `{ name, path | undefined }[]`). Named for the same reason as SetThemeResult.
type ThinkingLevel ¶
type ThinkingLevel = any
ThinkingLevel mirrors @earendil-works/pi-agent-core ThinkingLevel.
type ThinkingLevelSelectEvent ¶
type ThinkingLevelSelectEvent struct {
Type string `json:"type"`
Level string `json:"level"`
PreviousLevel string `json:"previousLevel"`
}
ThinkingLevelSelectEvent: upstream types.ts ThinkingLevelSelectEvent.
type ToolCallEvent ¶
type ToolCallEvent interface {
// contains filtered or unexported methods
}
ToolCallEvent is the sealed union of per-tool ToolCallEvent variants. Mirrors upstream's `export type ToolCallEvent = | BashToolCallEvent | PowerShellToolCallEvent | ReadToolCallEvent | EditToolCallEvent | WriteToolCallEvent | GrepToolCallEvent | FindToolCallEvent | LsToolCallEvent | CustomToolCallEvent` (types.ts:810).
Package-sealed via the unexported `isToolCallEvent` marker method: only the nine variant structs declared in this package can satisfy it. Authors handle the union via a type switch on the concrete variant. Custom UnmarshalJSON in marshalling.go probes the `toolName` field to dispatch to the correct variant when reading session JSONL.
upstream: types.ts:810
func UnmarshalToolCallEvent ¶
func UnmarshalToolCallEvent(data []byte) (ToolCallEvent, error)
UnmarshalToolCallEvent dispatches by `toolName`. Tool names that don't match a known builtin variant fall through to CustomToolCallEvent \u2014 this matches upstream behaviour (custom tools share the wire shape with builtins; only `toolName` distinguishes them) and keeps third-party tools round-trippable through pig without code changes.
type ToolCallEventBase ¶
ToolCallEventBase mirrors upstream's internal ToolCallEventBase. Embedded in each per-tool variant so all variants share the discriminator and toolCallId fields.
Go embeds the common fields so reflection sees the same promoted shape.
type ToolCallEventResult ¶
type ToolCallEventResult struct {
Block bool `json:"block,omitempty"`
Reason string `json:"reason,omitempty"`
// Terminate hints that the agent should stop after the current tool batch
// when this call is blocked. Early termination only happens when every
// finalized tool result in the batch sets it.
Terminate bool `json:"terminate,omitempty"`
}
ToolCallEventResult: upstream types.ts ToolCallEventResult.
type ToolDefinition ¶
type ToolDefinition struct {
Name string `json:"name"`
Label string `json:"label"`
Description string `json:"description"`
PromptSnippet string `json:"promptSnippet,omitempty"`
PromptGuidelines []string `json:"promptGuidelines,omitempty"`
Parameters json.RawMessage `json:"parameters"`
ConstrainedSampling json.RawMessage `json:"constrainedSampling,omitempty"`
RenderShell ToolRenderShell `json:"renderShell,omitempty"`
PrepareArguments ToolPrepareArgumentsFunc `json:"-"`
ExecutionMode ToolExecutionMode `json:"executionMode,omitempty"`
Execute ToolExecuteFunc `json:"-"`
RenderCall ToolRenderCallFunc `json:"-"`
RenderResult ToolRenderResultFunc `json:"-"`
// BuiltInRenderers names the built-in tool whose renderers draw the card
// halves this definition does not render itself. A subprocess extension
// sets it for a tool built from Pi's create<Tool>ToolDefinition, whose
// renderers are that built-in tool's (D73).
BuiltInRenderers string `json:"-"`
// ValidationParameters is the host-only representation of non-enumerable TypeBox metadata.
ValidationParameters json.RawMessage `json:"-"`
}
ToolDefinition mirrors upstream ToolDefinition<TParams, TDetails, TState>.
pig Go mechanic (not a divergence): upstream is generic over TParams (TypeBox TSchema), TDetails, and TState. Go uses json.RawMessage for parameters and any for details/state because Go interface methods cannot have type parameters and the host registry is heterogeneous. The SDK ergonomics layer in `extensions/sdk/go/` provides typed wrappers without changing the wire format.
type ToolDetailsConverter ¶
type ToolDetailsConverter interface {
ToolResultDetails() any
}
ToolDetailsConverter is implemented by a built-in tool's internal result details to produce the upstream SDK wire shape for the `details` field of a tool_result event. pig keeps richer internal detail structs for the TUI renderer; this contract lets the extension emission boundary convert them to the lean upstream shapes without the generic runtime depending on the concrete tool package.
type ToolExecuteFunc ¶
type ToolExecuteFunc = func( ctx context.Context, toolCallID string, params json.RawMessage, onUpdate AgentToolUpdateCallback, ) (AgentToolResult, error)
ToolExecuteFunc mirrors upstream ToolDefinition.execute.
Go carries the upstream abort signal and extension values through one context.Context. Use FromContext to access the extension context.
type ToolExecutionEndEvent ¶
type ToolExecutionEndEvent struct {
Type string `json:"type"`
ToolCallID string `json:"toolCallId"`
ToolName string `json:"toolName"`
Result any `json:"result"`
IsError bool `json:"isError"`
}
ToolExecutionEndEvent: upstream types.ts ToolExecutionEndEvent.
type ToolExecutionMode ¶
type ToolExecutionMode = string
ToolExecutionMode mirrors ToolExecutionMode ("sequential" | "parallel").
type ToolExecutionStartEvent ¶
type ToolExecutionStartEvent struct {
Type string `json:"type"`
ToolCallID string `json:"toolCallId"`
ToolName string `json:"toolName"`
Args any `json:"args"`
}
ToolExecutionStartEvent: upstream types.ts ToolExecutionStartEvent.
type ToolExecutionUpdateEvent ¶
type ToolExecutionUpdateEvent struct {
Type string `json:"type"`
ToolCallID string `json:"toolCallId"`
ToolName string `json:"toolName"`
Args any `json:"args"`
PartialResult any `json:"partialResult"`
}
ToolExecutionUpdateEvent: upstream types.ts ToolExecutionUpdateEvent.
type ToolInfo ¶
type ToolInfo struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters json.RawMessage `json:"parameters"`
PromptGuidelines []string `json:"promptGuidelines,omitempty"`
SourceInfo SourceInfo `json:"sourceInfo"`
}
ToolInfo mirrors upstream ToolInfo: the read-only view returned by API.GetAllTools.
type ToolPrepareArgumentsFunc ¶
type ToolPrepareArgumentsFunc = func(args json.RawMessage) (json.RawMessage, error)
ToolPrepareArgumentsFunc mirrors upstream ToolDefinition.prepareArguments.
type ToolRenderCallFunc ¶
type ToolRenderCallFunc = func( args json.RawMessage, theme Theme, context ToolRenderContext, ) Component
ToolRenderCallFunc mirrors upstream ToolDefinition.renderCall.
type ToolRenderContext ¶
type ToolRenderContext struct {
Args any `json:"args"`
ToolCallID string `json:"toolCallId"`
Invalidate func() `json:"-"`
LastComponent Component `json:"-"`
State any `json:"-"`
Cwd string `json:"cwd"`
ExecutionStarted bool `json:"executionStarted"`
ArgsComplete bool `json:"argsComplete"`
IsPartial bool `json:"isPartial"`
Expanded bool `json:"expanded"`
ShowImages bool `json:"showImages"`
IsError bool `json:"isError"`
// Card identifies the tool card being rendered. Go mechanic (not a
// divergence): a renderer that runs in an extension process keeps State
// and its last component there, so the host names the card they belong
// to; upstream passes the card's objects themselves.
Card string `json:"-"`
}
ToolRenderContext mirrors upstream ToolRenderContext<TState, TArgs>.
Go mechanic (not a divergence): upstream is generic over TState and TArgs; the Go version uses any for both because Go function-type struct fields cannot have type parameters. SDK helpers in `extensions/sdk/go/` provide typed wrappers without changing the wire format.
type ToolRenderResultFunc ¶
type ToolRenderResultFunc = func( result AgentToolResult, options ToolRenderResultOptions, theme Theme, context ToolRenderContext, ) Component
ToolRenderResultFunc mirrors upstream ToolDefinition.renderResult.
type ToolRenderResultOptions ¶
type ToolRenderResultOptions struct {
Expanded bool `json:"expanded"`
IsPartial bool `json:"isPartial"`
}
ToolRenderResultOptions mirrors upstream ToolRenderResultOptions.
type ToolRenderShell ¶
type ToolRenderShell string
ToolRenderShell controls whether the standard tool-execution chrome wraps the tool's renderers, or the tool draws its own framing. Mirrors upstream "default" | "self".
const ( ToolRenderShellDefault ToolRenderShell = "default" ToolRenderShellSelf ToolRenderShell = "self" )
type ToolResultEvent ¶
type ToolResultEvent interface {
// contains filtered or unexported methods
}
ToolResultEvent is the sealed union of per-tool ToolResultEvent variants. Mirrors upstream's `export type ToolResultEvent = | BashToolResultEvent | PowerShellToolResultEvent | ... | CustomToolResultEvent` (types.ts:869).
Package-sealed via the unexported `isToolResultEvent` marker method. Custom UnmarshalJSON in marshalling.go dispatches by `toolName`.
upstream: types.ts:869
func UnmarshalToolResultEvent ¶
func UnmarshalToolResultEvent(data []byte) (ToolResultEvent, error)
UnmarshalToolResultEvent dispatches by `toolName`. See UnmarshalToolCallEvent for the custom-tool fallback rationale.
type ToolResultEventBase ¶
type ToolResultEventBase struct {
Type string `json:"type"`
ToolCallID string `json:"toolCallId"`
Input map[string]any `json:"input"`
Content []any `json:"content"` // (TextContent | ImageContent)[]
IsError bool `json:"isError"`
// Usage is the usage of the tool execution itself, if available
// (upstream `usage?: Usage`).
Usage any `json:"usage,omitempty"`
}
ToolResultEventBase mirrors upstream's internal ToolResultEventBase.
type ToolResultEventResult ¶
type ToolResultEventResult struct {
Content []any `json:"content,omitempty"` // (TextContent | ImageContent)[]
Details any `json:"details,omitempty"`
// IsError is nil when the handler leaves the error flag unchanged, as
// upstream's optional `isError?: boolean` is undefined.
IsError *bool `json:"isError,omitempty"`
// Usage mirrors upstream ToolResultEventResult.usage (pi-ai Usage). Carried
// untyped over the extension wire boundary, consistent with Details above and
// the AgentMessage alias; folded into session usage totals by the
// deferred-tools accounting path.
Usage any `json:"usage,omitempty"`
}
ToolResultEventResult: upstream types.ts ToolResultEventResult.
type ToolResultMessage ¶
type ToolResultMessage = any
ToolResultMessage mirrors @earendil-works/pi-ai ToolResultMessage.
type ToolTruncation ¶
type ToolTruncation struct {
Content string `json:"content"`
Truncated bool `json:"truncated"`
TruncatedBy string `json:"truncatedBy"` // "lines" | "bytes"
TotalLines int `json:"totalLines"`
TotalBytes int `json:"totalBytes"`
OutputLines int `json:"outputLines"`
OutputBytes int `json:"outputBytes"`
LastLinePartial bool `json:"lastLinePartial"`
FirstLineExceedsLimit bool `json:"firstLineExceedsLimit"`
MaxLines int `json:"maxLines"`
MaxBytes int `json:"maxBytes"`
}
ToolTruncation is the upstream TruncationResult wire shape (truncate.ts:15). It is attached as the `truncation` field of read/bash/grep/find/ls tool result details when output was truncated. All fields are present in a real truncation object (it is only attached when truncation occurred).
type TreePreparation ¶
type TreePreparation = any
TreePreparation mirrors the upstream TreePreparation interface.
type TurnEndEvent ¶
type TurnEndEvent struct {
*BoundaryState
Type string `json:"type"`
TurnIndex int `json:"turnIndex"`
Message AgentMessage `json:"message"`
ToolResults []ToolResultMessage `json:"toolResults"`
MessageEntryID string `json:"messageEntryId"`
ToolResultEntryIds []string `json:"toolResultEntryIds"`
}
TurnEndEvent carries the completed turn and the actionable boundary proposal and preview (upstream types.ts TurnEndEvent).
type TurnStartEvent ¶
type TurnStartEvent struct {
Type string `json:"type"`
TurnIndex int `json:"turnIndex"`
Timestamp int64 `json:"timestamp"`
}
TurnStartEvent: upstream types.ts TurnStartEvent.
type UIContext ¶
type UIContext interface {
// Show a selector and return the user's choice.
// upstream: types.ts:124
Select(ctx context.Context, title string, options []string, opts ExtensionUIDialogOptions) (string, error)
// Show a confirmation dialog.
// upstream: types.ts:127
Confirm(ctx context.Context, title, message string, opts ExtensionUIDialogOptions) (bool, error)
// Show a text input dialog.
// upstream: types.ts:130
Input(ctx context.Context, title, placeholder string, opts ExtensionUIDialogOptions) (string, error)
// Show a notification to the user. Type is one of
// "info" | "warning" | "error".
// upstream: types.ts:133
Notify(message, kind string)
// OnTerminalInput registers a raw-terminal-input handler
// (interactive mode only). Returns an unsubscribe function.
// upstream: types.ts:136
OnTerminalInput(handler TerminalInputHandler) (unsubscribe func())
// SetStatus sets status text in the footer/status bar. Empty
// text clears the entry.
// upstream: types.ts:139
SetStatus(key, text string)
// SetWorkingMessage sets the working/loading message shown
// during streaming. Empty message restores the default.
// upstream: types.ts:142
SetWorkingMessage(message string)
// SetWorkingVisible toggles whether the working/loading indicator is shown.
// upstream: interactive-mode.ts oauth/rpc extension contexts
SetWorkingVisible(visible bool)
// SetWorkingIndicator configures the interactive working
// indicator. Nil opts restores the default animated spinner.
// upstream: types.ts:153
SetWorkingIndicator(opts WorkingIndicatorOptions)
// SetHiddenThinkingLabel sets the label shown for hidden
// thinking blocks. Empty label restores the default.
// upstream: types.ts:156
SetHiddenThinkingLabel(label string)
// SetWidget sets a widget to display above or below the editor.
// content may be []string or a function-typed factory; opts
// describes placement/lifecycle.
//
// upstream: types.ts:159 + types.ts:163 (overloaded). Go merges
// to one signature using `any` for content because Go has no
// method overloading.
SetWidget(key string, content any, opts ExtensionWidgetOptions)
// built-in footer.
// upstream: types.ts:172
SetFooter(factory any)
// SetHeader installs a custom header factory. Nil restores the
// built-in header.
// upstream: types.ts:181
SetHeader(factory any)
// pig additive (D60): SetLogin validates and installs Pig's native login
// definition in the shared header slot. Upstream Pi exposes only
// SetHeader because its in-process extensions can supply component factories.
SetLogin(definition LoginDefinition) error
// SetTitle sets the terminal window/tab title.
// upstream: types.ts:184
SetTitle(title string)
// Custom shows a custom component with keyboard focus and
// returns the user's result via the `done` callback.
//
// upstream: types.ts:187: the generic `<T>` is erased to `any` because Go
// interface methods cannot be generic (an ordinary TS→Go mechanic, not a
// divergence). Authors typed-assert at the call site or use the SDK helpers.
Custom(ctx context.Context, factory any, opts any) (any, error)
// PasteToEditor pastes text into the editor, triggering paste
// handling (collapse for large content).
// upstream: types.ts:204
PasteToEditor(text string)
// SetEditorText sets the text in the core input editor.
// upstream: types.ts:207
SetEditorText(text string)
// GetEditorText returns the current text from the core input
// editor.
// upstream: types.ts:210
GetEditorText() string
// Editor shows a multi-line editor for text editing. Returns
// the entered text or empty + context.Canceled when cancelled.
// upstream: types.ts:213
Editor(ctx context.Context, title, prefill string) (string, error)
// AddAutocompleteProvider stacks additional autocomplete
// behavior on top of the built-in provider.
// upstream: types.ts:216
AddAutocompleteProvider(factory AutocompleteProviderFactory) error
// SetEditorComponent installs a custom editor component
// factory. Nil restores the default editor.
// upstream: types.ts:249
SetEditorComponent(factory any)
// GetEditorComponent returns the currently installed custom editor component.
// Nil when the default editor is active.
GetEditorComponent() any
// Theme returns the current theme for styling.
//
// upstream: types.ts:254 (`readonly theme: Theme`). Mapped to a
// getter method because Go interfaces cannot expose readonly
// fields.
Theme() Theme
// GetAllThemes returns metadata for all available themes.
// upstream: types.ts:257
GetAllThemes() []ThemeMeta
// GetTheme loads a theme by name without switching to it.
// Returns nil + error if not found.
// upstream: types.ts:260
GetTheme(name string) (Theme, error)
// SetTheme switches the current theme. theme is either a name
// (string) or a Theme value; the result reports success +
// optional error message.
// upstream: types.ts:262
SetTheme(theme any) SetThemeResult
// GetToolsExpanded returns the current tool-output expansion
// state.
// upstream: types.ts:265
GetToolsExpanded() bool
// SetToolsExpanded sets the tool-output expansion state.
// upstream: types.ts:268
SetToolsExpanded(expanded bool)
// RunRemoteOverlay opens an interactive overlay whose contents
// are produced by a remote (subprocess) extension. The overlay
// renders the cached lines pushed via the returned handle and
// forwards user input chunks back to host.OnInput. Blocks until
// the handle's Close is called and returns the result value the
// remote producer supplied. Returns (nil, false) when the
// overlay cannot be opened (e.g. no TUI bound, like in print or
// RPC modes).
//
// pig-specific: no upstream equivalent. Upstream's Custom()
// can't cross a subprocess boundary because its factory captures
// in-process TUI references; this is the deserialised companion.
RunRemoteOverlay(opts RemoteOverlayOptions, host RemoteOverlayHost, onHandle func(RemoteOverlayHandle)) (any, bool)
// OnRemoteTerminalInput registers the raw-terminal-input listener of
// the subprocess extension named extensionName. It takes its place in
// registration order as OnTerminalInput does, but the host never calls
// handler on its input loop: it asks off the loop and applies the
// verdict in input order. Returns an unsubscribe function.
//
// pig additive (D19): upstream listeners run in process and answer
// synchronously; a subprocess listener's verdict crosses a socket.
OnRemoteTerminalInput(extensionName string, handler RemoteTerminalInputHandler) (unsubscribe func())
}
UIContext is the per-mode UI surface for extensions.
**Upstream alias:** mirrors `ExtensionUIContext` (types.ts:120-269). Each mode (interactive, RPC, print) provides its own implementation; extensions interact with whichever the host bound at runtime.
**Default:** when the host binds nothing, `Context.UI()` returns the package-level NoopUIContext (a value, not a constructor - matches upstream's module-level `noOpUIContext` constant at runner.ts:188).
**Method shape conventions (pig):**
- Methods that upstream returns `Promise<T | undefined>` from map to `(T, error)` in Go. The error half carries cancellation and routes upstream "undefined" through the typed zero value (empty string, false). Callers distinguish "user cancelled" from "ok with default value" by inspecting `errors.Is(err, context.Canceled)`.
- Methods that upstream returns `Promise<void>` from map to `error`-returning Go methods so cancellation propagates.
- Methods that upstream returns synchronously stay synchronous in Go (Notify, SetStatus, etc.).
- Method names are upstream camelCase → Go PascalCase. The `setX` family becomes `SetX`. The readonly property `theme` becomes a `Theme()` getter (Go has no readonly fields on interfaces).
**Sync-compat:** every divergence from a 1:1 method shape is a silent sync-debt risk. Method order in this interface mirrors upstream types.ts order verbatim so `git diff` against the next upstream sync is mechanical.
upstream: types.ts:120-269 (ExtensionUIContext)
var NoopUIContext UIContext = &noopUIContext{}
NoopUIContext is the package-level no-op singleton. Hosts that have no UI (print and JSON modes) wire `ContextActions.UI = NoopUIContext`; equivalently, leaving `ContextActions.UI` nil produces the same behavior because Context.UI falls back to this value.
**Identity contract:** the value is intentionally a singleton (one shared `*noopUIContext`) so `Context.HasUI()` can implement upstream's identity check (runner.ts:361: `this.uiContext !== noOpUIContext`) by pointer comparison.
upstream: runner.ts:188 (`const noOpUIContext: ExtensionUIContext = ...`)
type UIPromptEndEvent ¶
type UIPromptEndEvent struct {
Type string `json:"type"` // "ui_prompt_end"
Reason string `json:"reason"` // "ui_prompt"
Kind UIPromptKind `json:"kind"`
Title string `json:"title,omitempty"`
}
UIPromptEndEvent: upstream types.ts UIPromptEndEvent. Fired when Pi is no longer waiting on a blocking user-facing extension UI prompt. Kind and Title repeat the outermost prompt's start event.
type UIPromptKind ¶
type UIPromptKind string
UIPromptKind mirrors upstream types.ts UIPromptKind: "select" | "confirm" | "input" | "editor" | "custom".
const ( UIPromptKindSelect UIPromptKind = "select" UIPromptKindConfirm UIPromptKind = "confirm" UIPromptKindInput UIPromptKind = "input" UIPromptKindEditor UIPromptKind = "editor" UIPromptKindCustom UIPromptKind = "custom" )
type UIPromptStartEvent ¶
type UIPromptStartEvent struct {
Type string `json:"type"` // "ui_prompt_start"
Reason string `json:"reason"` // "ui_prompt"
Kind UIPromptKind `json:"kind"`
Title string `json:"title,omitempty"`
}
UIPromptStartEvent: upstream types.ts UIPromptStartEvent. Fired when Pi starts waiting on a blocking user-facing extension UI prompt. Title is omitted when the prompt has none (upstream `...(title ? { title } : {})`).
type UserBashEvent ¶
type UserBashEvent struct {
Type string `json:"type"`
Command string `json:"command"`
ExcludeFromContext bool `json:"excludeFromContext"`
Cwd string `json:"cwd"`
}
UserBashEvent: upstream types.ts UserBashEvent.
type UserBashEventResult ¶
type UserBashEventResult struct {
Operations BashOperations `json:"operations,omitempty"`
Result BashResult `json:"result,omitempty"`
}
UserBashEventResult: upstream types.ts UserBashEventResult.
type ValidatedLoginDefinition ¶
type ValidatedLoginDefinition struct {
// contains filtered or unexported fields
}
ValidatedLoginDefinition is an immutable, renderer-ready login definition.
func DecodeLoginDefinitionJSON ¶
func DecodeLoginDefinitionJSON(data []byte) (ValidatedLoginDefinition, error)
DecodeLoginDefinitionJSON strictly decodes and validates the current login wire shape. Duplicate and unknown object fields are rejected.
func ValidateLoginDefinition ¶
func ValidateLoginDefinition(definition LoginDefinition) (ValidatedLoginDefinition, error)
ValidateLoginDefinition validates and defensively copies a login definition.
func (ValidatedLoginDefinition) Brand ¶
func (d ValidatedLoginDefinition) Brand() []string
func (ValidatedLoginDefinition) Color ¶
func (d ValidatedLoginDefinition) Color(symbol byte) (color.RGBA, bool)
func (ValidatedLoginDefinition) Description ¶
func (d ValidatedLoginDefinition) Description() string
func (ValidatedLoginDefinition) Hero ¶
func (d ValidatedLoginDefinition) Hero() []string
func (ValidatedLoginDefinition) Mascot ¶
func (d ValidatedLoginDefinition) Mascot() []string
func (ValidatedLoginDefinition) Name ¶
func (d ValidatedLoginDefinition) Name() string
func (ValidatedLoginDefinition) Tagline ¶
func (d ValidatedLoginDefinition) Tagline() string
type WidthLines ¶
WidthLines is a component frame rendered outside the host (by a subprocess extension) together with the terminal width it was rendered at, so the host never paints a frame rendered for another width. Width 0 means unknown.
type WorkingIndicatorOptions ¶
type WorkingIndicatorOptions = any
WorkingIndicatorOptions mirrors upstream WorkingIndicatorOptions.
type WriteToolCallEvent ¶
type WriteToolCallEvent struct {
ToolCallEventBase
ToolName string `json:"toolName"` // "write"
Input WriteToolInput `json:"input"`
}
WriteToolCallEvent: upstream types.ts WriteToolCallEvent.
type WriteToolInput ¶
type WriteToolInput = any
type WriteToolResultEvent ¶
type WriteToolResultEvent struct {
ToolResultEventBase
ToolName string `json:"toolName"` // "write"
Details any `json:"details,omitempty"`
}
WriteToolResultEvent: upstream types.ts WriteToolResultEvent.
Source Files
¶
- aggregated_results.go
- api.go
- autocomplete.go
- bash_operations.go
- before_agent_start_options.go
- cache_warming.go
- call_initiation.go
- capabilities.go
- command.go
- context.go
- context_actions.go
- diagnostics.go
- doc.go
- errors.go
- eventbus.go
- events.go
- exec.go
- exec_unix.go
- extension.go
- extension_error.go
- flag.go
- host_actions.go
- login.go
- marshalling.go
- mode.go
- model_info.go
- model_stream.go
- native_provider.go
- opaque_types.go
- provider.go
- provider_runtime.go
- remote_editor.go
- remote_overlay.go
- renderer.go
- replaced_session_context.go
- scoped_models.go
- shortcut.go
- system_prompt_options.go
- tool.go
- tool_registry.go
- ui.go
Directories
¶
| Path | Synopsis |
|---|---|
|
Package extensiontest provides test doubles for the extension.API surface.
|
Package extensiontest provides test doubles for the extension.API surface. |
|
host
|
|
|
cellpack
Package cellpack is the Piglet-Binary-side counterpart to the host's prebuilt-cell seam (runtimecell.PrebuiltResolver).
|
Package cellpack is the Piglet-Binary-side counterpart to the host's prebuilt-cell seam (runtimecell.PrebuiltResolver). |
|
fusepack
Package fusepack holds Go extensions fused into a Piglet Binary.
|
Package fusepack holds Go extensions fused into a Piglet Binary. |
|
inproc
Package inproc implements the in-process Go dispatch runner for extensions.
|
Package inproc implements the in-process Go dispatch runner for extensions. |
|
runtimecell
Package runtimecell builds and resolves packed extension runtime cells.
|
Package runtimecell builds and resolves packed extension runtime cells. |
|
subprocess
Package subprocess implements pig's out-of-process extension transport: extensions communicate over a local stream socket with length-prefixed JSON framing.
|
Package subprocess implements pig's out-of-process extension transport: extensions communicate over a local stream socket with length-prefixed JSON framing. |
|
subprocess/internal/noderuntimegen
command
Command noderuntimegen packages the Node runtime and its content identity reproducibly.
|
Command noderuntimegen packages the Node runtime and its content identity reproducibly. |
|
Package installresolver is Pig's product-neutral seam for contributed package-source behavior.
|
Package installresolver is Pig's product-neutral seam for contributed package-source behavior. |
|
Package pigsdk stages Pig's extension SDKs (Go, Python, and Rust) into the config root so out-of-tree extension builds and packed runtime cells can use the API that matches the running binary.
|
Package pigsdk stages Pig's extension SDKs (Go, Python, and Rust) into the config root so out-of-tree extension builds and packed runtime cells can use the API that matches the running binary. |
|
Package source resolves an authorized extension path into one conventional factory or exact isolated standalone definition.
|
Package source resolves an authorized extension path into one conventional factory or exact isolated standalone definition. |