@oh-my-pi/pi-coding-agent 15.1.1 → 15.1.3

package/dist/types/extensibility/extensions/wrapper.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool wrappers for extensions.
+ */
+import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Static, TSchema } from "@oh-my-pi/pi-ai";
+import type { ExtensionRunner } from "./runner";
+import type { RegisteredTool } from "./types";
+/**
+ * Adapts a RegisteredTool into an AgentTool.
+ */
+export declare class RegisteredToolAdapter implements AgentTool<any, any, any> {
+    private registeredTool;
+    private runner;
+    name: string;
+    description: string;
+    parameters: any;
+    label: string;
+    strict: boolean;
+    renderCall?: (args: any, options: any, theme: any) => any;
+    renderResult?: (result: any, options: any, theme: any, args?: any) => any;
+    constructor(registeredTool: RegisteredTool, runner: ExtensionRunner);
+    execute(toolCallId: string, params: any, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<any>, _context?: AgentToolContext): Promise<import("@oh-my-pi/pi-agent-core").AgentToolResult<unknown, unknown>>;
+}
+/**
+ * Backward-compatible factory function wrapper.
+ */
+export declare function wrapRegisteredTool(registeredTool: RegisteredTool, runner: ExtensionRunner): AgentTool;
+/**
+ * Wrap all registered tools into AgentTools.
+ */
+export declare function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[];
+/**
+ * Wraps a tool with extension callbacks for interception.
+ * - Emits tool_call event before execution (can block)
+ * - Emits tool_result event after execution (can modify result)
+ */
+export declare class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetails = unknown> implements AgentTool<TParameters, TDetails> {
+    private tool;
+    private runner;
+    name: string;
+    description: string;
+    parameters: TParameters;
+    label: string;
+    strict: boolean;
+    constructor(tool: AgentTool<TParameters, TDetails>, runner: ExtensionRunner);
+    /**
+     * Forward browser mode changes when available.
+     */
+    restartForModeChange(): Promise<void>;
+    execute(toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>, context?: AgentToolContext): Promise<{
+        content: any;
+        details?: TDetails;
+    }>;
+}

package/dist/types/extensibility/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export type { ReadonlySessionManager, UsageStatistics } from "../../session/session-manager";
+export * from "./loader";
+export * from "./runner";
+export * from "./tool-wrapper";
+export * from "./types";

package/dist/types/extensibility/hooks/loader.d.ts

@@ -0,0 +1,89 @@
+import type { HookMessage } from "../../session/messages";
+import type { SessionManager } from "../../session/session-manager";
+import type { HookMessageRenderer, RegisteredCommand } from "./types";
+/**
+ * Generic handler function type.
+ */
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+/**
+ * Send message handler type for pi.sendMessage().
+ */
+export type SendMessageHandler = <T = unknown>(message: Pick<HookMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {
+    triggerTurn?: boolean;
+    deliverAs?: "steer" | "followUp";
+}) => void;
+/**
+ * Append entry handler type for pi.appendEntry().
+ */
+export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
+/**
+ * New session handler type for ctx.newSession() in HookCommandContext.
+ */
+export type NewSessionHandler = (options?: {
+    parentSession?: string;
+    setup?: (sessionManager: SessionManager) => Promise<void>;
+}) => Promise<{
+    cancelled: boolean;
+}>;
+/**
+ * Branch handler type for ctx.branch() in HookCommandContext.
+ */
+export type BranchHandler = (entryId: string) => Promise<{
+    cancelled: boolean;
+}>;
+/**
+ * Navigate tree handler type for ctx.navigateTree() in HookCommandContext.
+ */
+export type NavigateTreeHandler = (targetId: string, options?: {
+    summarize?: boolean;
+}) => Promise<{
+    cancelled: boolean;
+}>;
+/**
+ * Registered handlers for a loaded hook.
+ */
+export interface LoadedHook {
+    /** Original path from config */
+    path: string;
+    /** Resolved absolute path */
+    resolvedPath: string;
+    /** Map of event type to handler functions */
+    handlers: Map<string, HandlerFn[]>;
+    /** Map of customType to hook message renderer */
+    messageRenderers: Map<string, HookMessageRenderer>;
+    /** Map of command name to registered command */
+    commands: Map<string, RegisteredCommand>;
+    /** Set the send message handler for this hook's pi.sendMessage() */
+    setSendMessageHandler: (handler: SendMessageHandler) => void;
+    /** Set the append entry handler for this hook's pi.appendEntry() */
+    setAppendEntryHandler: (handler: AppendEntryHandler) => void;
+}
+/**
+ * Result of loading hooks.
+ */
+export interface LoadHooksResult {
+    /** Successfully loaded hooks */
+    hooks: LoadedHook[];
+    /** Errors encountered during loading */
+    errors: Array<{
+        path: string;
+        error: string;
+    }>;
+}
+/**
+ * Load all hooks from configuration.
+ * @param paths - Array of hook file paths
+ * @param cwd - Current working directory for resolving relative paths
+ */
+export declare function loadHooks(paths: string[], cwd: string): Promise<LoadHooksResult>;
+/**
+ * Discover and load hooks from all registered providers.
+ * Uses the capability API to discover hook paths from:
+ * 1. OMP native configs (.omp/.pi hooks/)
+ * 2. Installed plugins
+ * 3. Other editor/IDE configurations
+ *
+ * Plus any explicitly configured paths from settings.
+ */
+export declare function discoverAndLoadHooks(configuredPaths: string[], cwd: string): Promise<LoadHooksResult>;
+export {};

package/dist/types/extensibility/hooks/runner.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Hook runner - executes hooks and manages their lifecycle.
+ */
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { ModelRegistry } from "../../config/model-registry";
+import type { SessionManager } from "../../session/session-manager";
+import type { AppendEntryHandler, BranchHandler, LoadedHook, NavigateTreeHandler, NewSessionHandler, SendMessageHandler } from "./loader";
+import type { BeforeAgentStartEventResult, HookCommandContext, HookError, HookEvent, HookMessageRenderer, HookUIContext, RegisteredCommand, SessionBeforeCompactResult, SessionBeforeTreeResult, SessionCompactingResult, ToolCallEvent, ToolCallEventResult, ToolResultEventResult } from "./types";
+/**
+ * Listener for hook errors.
+ */
+export type HookErrorListener = (error: HookError) => void;
+export { execCommand } from "../../exec/exec";
+/**
+ * HookRunner executes hooks and manages event emission.
+ */
+export declare class HookRunner {
+    #private;
+    private readonly hooks;
+    private readonly cwd;
+    private readonly sessionManager;
+    private readonly modelRegistry;
+    constructor(hooks: LoadedHook[], cwd: string, sessionManager: SessionManager, modelRegistry: ModelRegistry);
+    /**
+     * Initialize HookRunner with all required context.
+     * Modes call this once the agent session is fully set up.
+     */
+    initialize(options: {
+        /** Function to get the current model */
+        getModel: () => Model | undefined;
+        /** Handler for hooks to send messages */
+        sendMessageHandler: SendMessageHandler;
+        /** Handler for hooks to append entries */
+        appendEntryHandler: AppendEntryHandler;
+        /** Handler for creating new sessions (for HookCommandContext) */
+        newSessionHandler?: NewSessionHandler;
+        /** Handler for branching sessions (for HookCommandContext) */
+        branchHandler?: BranchHandler;
+        /** Handler for navigating session tree (for HookCommandContext) */
+        navigateTreeHandler?: NavigateTreeHandler;
+        /** Function to check if agent is idle */
+        isIdle?: () => boolean;
+        /** Function to wait for agent to be idle */
+        waitForIdle?: () => Promise<void>;
+        /** Function to abort current operation (fire-and-forget) */
+        abort?: () => void;
+        /** Function to check if there are queued messages */
+        hasQueuedMessages?: () => boolean;
+        /** UI context for interactive prompts */
+        uiContext?: HookUIContext;
+        /** Whether UI is available */
+        hasUI?: boolean;
+    }): void;
+    /**
+     * Get the UI context (set by mode).
+     */
+    getUIContext(): HookUIContext | null;
+    /**
+     * Get whether UI is available.
+     */
+    getHasUI(): boolean;
+    /**
+     * Get the paths of all loaded hooks.
+     */
+    getHookPaths(): string[];
+    /**
+     * Subscribe to hook errors.
+     * @returns Unsubscribe function
+     */
+    onError(listener: HookErrorListener): () => void;
+    /**
+     * Emit an error to all listeners.
+     */
+    /**
+     * Emit an error to all error listeners.
+     */
+    emitError(error: HookError): void;
+    /**
+     * Check if any hooks have handlers for the given event type.
+     */
+    hasHandlers(eventType: string): boolean;
+    /**
+     * Get a message renderer for the given customType.
+     * Returns the first renderer found across all hooks, or undefined if none.
+     */
+    getMessageRenderer(customType: string): HookMessageRenderer | undefined;
+    /**
+     * Get all registered commands from all hooks.
+     */
+    getRegisteredCommands(): RegisteredCommand[];
+    /**
+     * Get a registered command by name.
+     * Returns the first command found across all hooks, or undefined if none.
+     */
+    getCommand(name: string): RegisteredCommand | undefined;
+    /**
+     * Create the command context for slash command handlers.
+     * Extends HookContext with session control methods that are only safe in commands.
+     */
+    createCommandContext(): HookCommandContext;
+    /**
+     * Emit an event to all hooks.
+     * Returns the result from session before_* / tool_result events (if any handler returns one).
+     */
+    emit(event: HookEvent): Promise<SessionBeforeCompactResult | SessionBeforeTreeResult | SessionCompactingResult | ToolResultEventResult | undefined>;
+    /**
+     * Emit a tool_call event to all hooks.
+     * No timeout - user prompts can take as long as needed.
+     * Errors are thrown (not swallowed) so caller can block on failure.
+     */
+    emitToolCall(event: ToolCallEvent): Promise<ToolCallEventResult | undefined>;
+    /**
+     * Emit a context event to all hooks.
+     * Handlers are chained - each gets the previous handler's output (if any).
+     * Returns the final modified messages, or the original if no modifications.
+     *
+     * Note: Messages are already deep-copied by the caller (pi-ai preprocessor).
+     */
+    emitContext(messages: AgentMessage[]): Promise<AgentMessage[]>;
+    /**
+     * Emit before_agent_start event to all hooks.
+     * Returns the first message to inject (if any handler returns one).
+     */
+    emitBeforeAgentStart(prompt: string, images?: import("@oh-my-pi/pi-ai").ImageContent[]): Promise<BeforeAgentStartEventResult | undefined>;
+}

package/dist/types/extensibility/hooks/tool-wrapper.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tool wrapper - wraps tools with hook callbacks for interception.
+ */
+import type { AgentTool, AgentToolContext, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { Static, TSchema } from "@oh-my-pi/pi-ai";
+import type { HookRunner } from "./runner";
+/**
+ * Wraps an AgentTool with hook callbacks for interception.
+ *
+ * Features:
+ * - Emits tool_call event before execution (can block)
+ * - Emits tool_result event after execution (can modify result)
+ * - Forwards onUpdate callback to wrapped tool for progress streaming
+ */
+export declare class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = unknown> implements AgentTool<TParameters, TDetails> {
+    private tool;
+    private hookRunner;
+    name: string;
+    description: string;
+    parameters: TParameters;
+    label: string;
+    strict: boolean;
+    constructor(tool: AgentTool<TParameters, TDetails>, hookRunner: HookRunner);
+    execute(toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>, context?: AgentToolContext): Promise<import("@oh-my-pi/pi-agent-core").AgentToolResult<TDetails, TParameters>>;
+}