@oh-my-pi/pi-coding-agent 3.15.0 → 3.20.0

package/src/core/extensions/types.ts

@@ -0,0 +1,712 @@
+/**
+ * Extension system types.
+ *
+ * Extensions are TypeScript modules that can:
+ * - Subscribe to agent lifecycle events
+ * - Register LLM-callable tools
+ * - Register commands, keyboard shortcuts, and CLI flags
+ * - Interact with the user via UI primitives
+ */
+
+import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { ImageContent, Model, TextContent, ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { Component, KeyId, TUI } from "@oh-my-pi/pi-tui";
+import type { Static, TSchema } from "@sinclair/typebox";
+import type { Theme } from "../../modes/interactive/theme/theme";
+import type { CompactionPreparation, CompactionResult } from "../compaction";
+import type { EventBus } from "../event-bus";
+import type { ExecOptions, ExecResult } from "../exec";
+import type { CustomMessage } from "../messages";
+import type { ModelRegistry } from "../model-registry";
+import type {
+	BranchSummaryEntry,
+	CompactionEntry,
+	ReadonlySessionManager,
+	SessionEntry,
+	SessionManager,
+} from "../session-manager";
+import type { BashToolDetails, FindToolDetails, GrepToolDetails, LsToolDetails, ReadToolDetails } from "../tools";
+import type { EditToolDetails } from "../tools/edit";
+
+export type { ExecOptions, ExecResult } from "../exec";
+export type { AgentToolResult, AgentToolUpdateCallback };
+
+// ============================================================================
+// UI Context
+// ============================================================================
+
+/**
+ * UI context for extensions to request interactive UI.
+ * Each mode (interactive, RPC, print) provides its own implementation.
+ */
+export interface ExtensionUIContext {
+	/** Show a selector and return the user's choice. */
+	select(title: string, options: string[]): Promise<string | undefined>;
+
+	/** Show a confirmation dialog. */
+	confirm(title: string, message: string): Promise<boolean>;
+
+	/** Show a text input dialog. */
+	input(title: string, placeholder?: string): Promise<string | undefined>;
+
+	/** Show a notification to the user. */
+	notify(message: string, type?: "info" | "warning" | "error"): void;
+
+	/** Set status text in the footer/status bar. Pass undefined to clear. */
+	setStatus(key: string, text: string | undefined): void;
+
+	/** Set a widget to display above the editor. Accepts string array or component factory. */
+	setWidget(key: string, content: string[] | undefined): void;
+	setWidget(key: string, content: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined): void;
+
+	/** Set the terminal window/tab title. */
+	setTitle(title: string): void;
+
+	/** Show a custom component with keyboard focus. */
+	custom<T>(
+		factory: (
+			tui: TUI,
+			theme: Theme,
+			done: (result: T) => void,
+		) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
+	): Promise<T>;
+
+	/** Set the text in the core input editor. */
+	setEditorText(text: string): void;
+
+	/** Get the current text from the core input editor. */
+	getEditorText(): string;
+
+	/** Show a multi-line editor for text editing. */
+	editor(title: string, prefill?: string): Promise<string | undefined>;
+
+	/** Get the current theme for styling. */
+	readonly theme: Theme;
+}
+
+// ============================================================================
+// Extension Context
+// ============================================================================
+
+/**
+ * Context passed to extension event handlers.
+ */
+export interface ExtensionContext {
+	/** UI methods for user interaction */
+	ui: ExtensionUIContext;
+	/** Whether UI is available (false in print/RPC mode) */
+	hasUI: boolean;
+	/** Current working directory */
+	cwd: string;
+	/** Session manager (read-only) */
+	sessionManager: ReadonlySessionManager;
+	/** Model registry for API key resolution */
+	modelRegistry: ModelRegistry;
+	/** Current model (may be undefined) */
+	model: Model<any> | undefined;
+	/** Whether the agent is idle (not streaming) */
+	isIdle(): boolean;
+	/** Abort the current agent operation */
+	abort(): void;
+	/** Whether there are queued messages waiting */
+	hasPendingMessages(): boolean;
+	/** @deprecated Use hasPendingMessages() instead */
+	hasQueuedMessages(): boolean;
+}
+
+/**
+ * Extended context for command handlers.
+ * Includes session control methods only safe in user-initiated commands.
+ */
+export interface ExtensionCommandContext extends ExtensionContext {
+	/** Wait for the agent to finish streaming */
+	waitForIdle(): Promise<void>;
+
+	/** Start a new session, optionally with initialization. */
+	newSession(options?: {
+		parentSession?: string;
+		setup?: (sessionManager: SessionManager) => Promise<void>;
+	}): Promise<{ cancelled: boolean }>;
+
+	/** Branch from a specific entry, creating a new session file. */
+	branch(entryId: string): Promise<{ cancelled: boolean }>;
+
+	/** Navigate to a different point in the session tree. */
+	navigateTree(targetId: string, options?: { summarize?: boolean }): Promise<{ cancelled: boolean }>;
+}
+
+// ============================================================================
+// Tool Types
+// ============================================================================
+
+/** Rendering options for tool results */
+export interface ToolRenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+	/** Current spinner frame index for animated elements (optional) */
+	spinnerFrame?: number;
+}
+
+/** Session event for tool onSession lifecycle */
+export interface ToolSessionEvent {
+	/** Reason for the session event */
+	reason: "start" | "switch" | "branch" | "tree" | "shutdown";
+	/** Previous session file path, or undefined for "start" and "shutdown" */
+	previousSessionFile: string | undefined;
+}
+
+/**
+ * Tool definition for registerTool().
+ */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown> {
+	/** Tool name (used in LLM tool calls) */
+	name: string;
+	/** Human-readable label for UI */
+	label: string;
+	/** Description for LLM */
+	description: string;
+	/** Parameter schema (TypeBox) */
+	parameters: TParams;
+	/** If true, tool is excluded unless explicitly listed in --tools or agent's tools field */
+	hidden?: boolean;
+
+	/** Execute the tool. */
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<TDetails>>;
+
+	/** Called on session lifecycle events - use to reconstruct state or cleanup resources */
+	onSession?: (event: ToolSessionEvent, ctx: ExtensionContext) => void | Promise<void>;
+
+	/** Custom rendering for tool call display */
+	renderCall?: (args: Static<TParams>, theme: Theme) => Component;
+
+	/** Custom rendering for tool result display */
+	renderResult?: (result: AgentToolResult<TDetails>, options: ToolRenderResultOptions, theme: Theme) => Component;
+}
+
+// ============================================================================
+// Session Events
+// ============================================================================
+
+/** Fired on initial session load */
+export interface SessionStartEvent {
+	type: "session_start";
+}
+
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+	type: "session_before_switch";
+	reason: "new" | "resume";
+	targetSessionFile?: string;
+}
+
+/** Fired after switching to another session */
+export interface SessionSwitchEvent {
+	type: "session_switch";
+	reason: "new" | "resume";
+	previousSessionFile: string | undefined;
+}
+
+/** Fired before branching a session (can be cancelled) */
+export interface SessionBeforeBranchEvent {
+	type: "session_before_branch";
+	entryId: string;
+}
+
+/** Fired after branching a session */
+export interface SessionBranchEvent {
+	type: "session_branch";
+	previousSessionFile: string | undefined;
+}
+
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+	type: "session_before_compact";
+	preparation: CompactionPreparation;
+	branchEntries: SessionEntry[];
+	customInstructions?: string;
+	signal: AbortSignal;
+}
+
+/** Fired after context compaction */
+export interface SessionCompactEvent {
+	type: "session_compact";
+	compactionEntry: CompactionEntry;
+	fromExtension: boolean;
+}
+
+/** Fired on process exit */
+export interface SessionShutdownEvent {
+	type: "session_shutdown";
+}
+
+/** Preparation data for tree navigation */
+export interface TreePreparation {
+	targetId: string;
+	oldLeafId: string | null;
+	commonAncestorId: string | null;
+	entriesToSummarize: SessionEntry[];
+	userWantsSummary: boolean;
+}
+
+/** Fired before navigating in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+	type: "session_before_tree";
+	preparation: TreePreparation;
+	signal: AbortSignal;
+}
+
+/** Fired after navigating in the session tree */
+export interface SessionTreeEvent {
+	type: "session_tree";
+	newLeafId: string | null;
+	oldLeafId: string | null;
+	summaryEntry?: BranchSummaryEntry;
+	fromExtension?: boolean;
+}
+
+export type SessionEvent =
+	| SessionStartEvent
+	| SessionBeforeSwitchEvent
+	| SessionSwitchEvent
+	| SessionBeforeBranchEvent
+	| SessionBranchEvent
+	| SessionBeforeCompactEvent
+	| SessionCompactEvent
+	| SessionShutdownEvent
+	| SessionBeforeTreeEvent
+	| SessionTreeEvent;
+
+// ============================================================================
+// Agent Events
+// ============================================================================
+
+/** Fired before each LLM call. Can modify messages. */
+export interface ContextEvent {
+	type: "context";
+	messages: AgentMessage[];
+}
+
+/** Fired after user submits prompt but before agent loop. */
+export interface BeforeAgentStartEvent {
+	type: "before_agent_start";
+	prompt: string;
+	images?: ImageContent[];
+}
+
+/** Fired when an agent loop starts */
+export interface AgentStartEvent {
+	type: "agent_start";
+}
+
+/** Fired when an agent loop ends */
+export interface AgentEndEvent {
+	type: "agent_end";
+	messages: AgentMessage[];
+}
+
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+	type: "turn_start";
+	turnIndex: number;
+	timestamp: number;
+}
+
+/** Fired at the end of each turn */
+export interface TurnEndEvent {
+	type: "turn_end";
+	turnIndex: number;
+	message: AgentMessage;
+	toolResults: ToolResultMessage[];
+}
+
+// ============================================================================
+// Tool Events
+// ============================================================================
+
+/** Fired before a tool executes. Can block. */
+export interface ToolCallEvent {
+	type: "tool_call";
+	toolName: string;
+	toolCallId: string;
+	input: Record<string, unknown>;
+}
+
+interface ToolResultEventBase {
+	type: "tool_result";
+	toolCallId: string;
+	input: Record<string, unknown>;
+	content: (TextContent | ImageContent)[];
+	isError: boolean;
+}
+
+export interface BashToolResultEvent extends ToolResultEventBase {
+	toolName: "bash";
+	details: BashToolDetails | undefined;
+}
+
+export interface ReadToolResultEvent extends ToolResultEventBase {
+	toolName: "read";
+	details: ReadToolDetails | undefined;
+}
+
+export interface EditToolResultEvent extends ToolResultEventBase {
+	toolName: "edit";
+	details: EditToolDetails | undefined;
+}
+
+export interface WriteToolResultEvent extends ToolResultEventBase {
+	toolName: "write";
+	details: undefined;
+}
+
+export interface GrepToolResultEvent extends ToolResultEventBase {
+	toolName: "grep";
+	details: GrepToolDetails | undefined;
+}
+
+export interface FindToolResultEvent extends ToolResultEventBase {
+	toolName: "find";
+	details: FindToolDetails | undefined;
+}
+
+export interface LsToolResultEvent extends ToolResultEventBase {
+	toolName: "ls";
+	details: LsToolDetails | undefined;
+}
+
+export interface CustomToolResultEvent extends ToolResultEventBase {
+	toolName: string;
+	details: unknown;
+}
+
+/** Fired after a tool executes. Can modify result. */
+export type ToolResultEvent =
+	| BashToolResultEvent
+	| ReadToolResultEvent
+	| EditToolResultEvent
+	| WriteToolResultEvent
+	| GrepToolResultEvent
+	| FindToolResultEvent
+	| LsToolResultEvent
+	| CustomToolResultEvent;
+
+// Type guards
+export function isBashToolResult(e: ToolResultEvent): e is BashToolResultEvent {
+	return e.toolName === "bash";
+}
+export function isReadToolResult(e: ToolResultEvent): e is ReadToolResultEvent {
+	return e.toolName === "read";
+}
+export function isEditToolResult(e: ToolResultEvent): e is EditToolResultEvent {
+	return e.toolName === "edit";
+}
+export function isWriteToolResult(e: ToolResultEvent): e is WriteToolResultEvent {
+	return e.toolName === "write";
+}
+export function isGrepToolResult(e: ToolResultEvent): e is GrepToolResultEvent {
+	return e.toolName === "grep";
+}
+export function isFindToolResult(e: ToolResultEvent): e is FindToolResultEvent {
+	return e.toolName === "find";
+}
+export function isLsToolResult(e: ToolResultEvent): e is LsToolResultEvent {
+	return e.toolName === "ls";
+}
+
+/** Union of all event types */
+export type ExtensionEvent =
+	| SessionEvent
+	| ContextEvent
+	| BeforeAgentStartEvent
+	| AgentStartEvent
+	| AgentEndEvent
+	| TurnStartEvent
+	| TurnEndEvent
+	| ToolCallEvent
+	| ToolResultEvent;
+
+// ============================================================================
+// Event Results
+// ============================================================================
+
+export interface ContextEventResult {
+	messages?: AgentMessage[];
+}
+
+export interface ToolCallEventResult {
+	block?: boolean;
+	reason?: string;
+}
+
+export interface ToolResultEventResult {
+	content?: (TextContent | ImageContent)[];
+	details?: unknown;
+	isError?: boolean;
+}
+
+export interface BeforeAgentStartEventResult {
+	message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
+	systemPromptAppend?: string;
+}
+
+export interface SessionBeforeSwitchResult {
+	cancel?: boolean;
+}
+
+export interface SessionBeforeBranchResult {
+	cancel?: boolean;
+	skipConversationRestore?: boolean;
+}
+
+export interface SessionBeforeCompactResult {
+	cancel?: boolean;
+	compaction?: CompactionResult;
+}
+
+export interface SessionBeforeTreeResult {
+	cancel?: boolean;
+	summary?: {
+		summary: string;
+		details?: unknown;
+	};
+}
+
+// ============================================================================
+// Message Rendering
+// ============================================================================
+
+export interface MessageRenderOptions {
+	expanded: boolean;
+}
+
+export type MessageRenderer<T = unknown> = (
+	message: CustomMessage<T>,
+	options: MessageRenderOptions,
+	theme: Theme,
+) => Component | undefined;
+
+// ============================================================================
+// Command Registration
+// ============================================================================
+
+export interface RegisteredCommand {
+	name: string;
+	description?: string;
+	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+
+// ============================================================================
+// Extension API
+// ============================================================================
+
+/** Handler function type for events */
+// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements
+export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
+
+/**
+ * ExtensionAPI passed to extension factory functions.
+ */
+export interface ExtensionAPI {
+	// =========================================================================
+	// Module Access
+	// =========================================================================
+
+	/** File logger for error/warning/debug messages */
+	logger: typeof import("../logger").logger;
+
+	/** Injected @sinclair/typebox module for defining tool parameters */
+	typebox: typeof import("@sinclair/typebox");
+
+	/** Injected pi-coding-agent exports for accessing SDK utilities */
+	pi: typeof import("../../index.js");
+
+	// =========================================================================
+	// Event Subscription
+	// =========================================================================
+
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(
+		event: "session_before_switch",
+		handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>,
+	): void;
+	on(event: "session_switch", handler: ExtensionHandler<SessionSwitchEvent>): void;
+	on(
+		event: "session_before_branch",
+		handler: ExtensionHandler<SessionBeforeBranchEvent, SessionBeforeBranchResult>,
+	): void;
+	on(event: "session_branch", handler: ExtensionHandler<SessionBranchEvent>): void;
+	on(
+		event: "session_before_compact",
+		handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>,
+	): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
+	on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
+	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
+	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
+	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
+
+	// =========================================================================
+	// Tool Registration
+	// =========================================================================
+
+	/** Register a tool that the LLM can call. */
+	registerTool<TParams extends TSchema = TSchema, TDetails = unknown>(tool: ToolDefinition<TParams, TDetails>): void;
+
+	// =========================================================================
+	// Command, Shortcut, Flag Registration
+	// =========================================================================
+
+	/** Register a custom command. */
+	registerCommand(name: string, options: { description?: string; handler: RegisteredCommand["handler"] }): void;
+
+	/** Register a keyboard shortcut. */
+	registerShortcut(
+		shortcut: KeyId,
+		options: {
+			description?: string;
+			handler: (ctx: ExtensionContext) => Promise<void> | void;
+		},
+	): void;
+
+	/** Register a CLI flag. */
+	registerFlag(
+		name: string,
+		options: {
+			description?: string;
+			type: "boolean" | "string";
+			default?: boolean | string;
+		},
+	): void;
+
+	/** Get the value of a registered CLI flag. */
+	getFlag(name: string): boolean | string | undefined;
+
+	// =========================================================================
+	// Message Rendering
+	// =========================================================================
+
+	/** Register a custom renderer for CustomMessageEntry. */
+	registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
+
+	// =========================================================================
+	// Actions
+	// =========================================================================
+
+	/** Send a custom message to the session. */
+	sendMessage<T = unknown>(
+		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): void;
+
+	/** Append a custom entry to the session for state persistence (not sent to LLM). */
+	appendEntry<T = unknown>(customType: string, data?: T): void;
+
+	/** Execute a shell command. */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+
+	/** Get the list of currently active tool names. */
+	getActiveTools(): string[];
+
+	/** Get all configured tools (built-in + extension tools). */
+	getAllTools(): string[];
+
+	/** Set the active tools by name. */
+	setActiveTools(toolNames: string[]): void;
+
+	/** Shared event bus for extension communication. */
+	events: EventBus;
+}
+
+/** Extension factory function type. */
+export type ExtensionFactory = (pi: ExtensionAPI) => void;
+
+// ============================================================================
+// Loaded Extension Types
+// ============================================================================
+
+export interface RegisteredTool {
+	definition: ToolDefinition;
+	extensionPath: string;
+}
+
+export interface ExtensionFlag {
+	name: string;
+	description?: string;
+	type: "boolean" | "string";
+	default?: boolean | string;
+	extensionPath: string;
+}
+
+export interface ExtensionShortcut {
+	shortcut: KeyId;
+	description?: string;
+	handler: (ctx: ExtensionContext) => Promise<void> | void;
+	extensionPath: string;
+}
+
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+
+export type SendMessageHandler = <T = unknown>(
+	message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+) => void;
+
+export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
+
+export type GetActiveToolsHandler = () => string[];
+
+export type GetAllToolsHandler = () => string[];
+
+export type SetActiveToolsHandler = (toolNames: string[]) => void;
+
+/** Loaded extension with all registered items. */
+export interface LoadedExtension {
+	path: string;
+	resolvedPath: string;
+	handlers: Map<string, HandlerFn[]>;
+	tools: Map<string, RegisteredTool>;
+	messageRenderers: Map<string, MessageRenderer>;
+	commands: Map<string, RegisteredCommand>;
+	flags: Map<string, ExtensionFlag>;
+	flagValues: Map<string, boolean | string>;
+	shortcuts: Map<KeyId, ExtensionShortcut>;
+	setSendMessageHandler: (handler: SendMessageHandler) => void;
+	setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+	setGetActiveToolsHandler: (handler: GetActiveToolsHandler) => void;
+	setGetAllToolsHandler: (handler: GetAllToolsHandler) => void;
+	setSetActiveToolsHandler: (handler: SetActiveToolsHandler) => void;
+	setFlagValue: (name: string, value: boolean | string) => void;
+}
+
+/** Result of loading extensions. */
+export interface LoadExtensionsResult {
+	extensions: LoadedExtension[];
+	errors: Array<{ path: string; error: string }>;
+	setUIContext(uiContext: ExtensionUIContext, hasUI: boolean): void;
+}
+
+// ============================================================================
+// Extension Error
+// ============================================================================
+
+export interface ExtensionError {
+	extensionPath: string;
+	event: string;
+	error: string;
+	stack?: string;
+}