apex-code 0.4.0 → 0.5.1

package/dist/core/extensions/types.d.ts

@@ -7,12 +7,13 @@
  * - Register commands, keyboard shortcuts, and CLI flags
  * - Interact with the user via UI primitives
  */
-import type { Api, AssistantMessageEvent, AssistantMessageEventStream, ConstrainedSamplingConfig, Context, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderHeaders, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, Usage } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessageEvent, AssistantMessageEventStream, ConstrainedSamplingConfig, ImageContent, Message, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderHeaders, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, TranscriptContext, Usage } from "@earendil-works/pi-ai";
 import type { AutocompleteItem, AutocompleteProvider, Component, EditorComponent, EditorTheme, KeyId, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "apex-code-agent-core";
 import type { Static, TSchema } from "typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.ts";
 import type { BashResult } from "../bash-executor.ts";
+import type { CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult } from "../cache-warmer.ts";
 import type { CompactionPreparation, CompactionResult } from "../compaction/index.ts";
 import type { EventBus } from "../event-bus.ts";
 import type { ExecOptions, ExecResult } from "../exec.ts";
@@ -22,16 +23,16 @@ import type { CustomMessage } from "../messages.ts";
 import type { ModelRegistry } from "../model-registry.ts";
 import type { ScopedModel } from "../model-resolver.ts";
 import type { PermissionPreview } from "../permissions/responder.ts";
-import type { BranchSummaryEntry, CompactionEntry, CustomEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.ts";
+import type { BranchSummaryEntry, CompactionEntry, ContextEditEntry, CustomEntry, ProjectedSessionEntry, ReadonlySessionManager, SessionEntry, SessionManager } from "../session-manager.ts";
 import type { SlashCommandInfo } from "../slash-commands.ts";
 import type { SourceInfo } from "../source-info.ts";
-import type { BuildSystemPromptOptions } from "../system-prompt.ts";
+import type { BuildSystemPromptOptions, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
 import type { BashOperations } from "../tools/bash.ts";
 import type { EditToolDetails } from "../tools/edit.ts";
 import type { BashToolDetails, BashToolInput, EditToolInput, FindToolDetails, FindToolInput, GrepToolDetails, GrepToolInput, LsToolDetails, LsToolInput, PowerShellToolDetails, PowerShellToolInput, ReadToolDetails, ReadToolInput, WriteToolInput } from "../tools/index.ts";
 export type { ExecOptions, ExecResult } from "../exec.ts";
 export type { AppKeybinding, KeybindingsManager } from "../keybindings.ts";
-export type { BuildSystemPromptOptions } from "../system-prompt.ts";
+export type { BuildSystemPromptOptions, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
 export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
 /** Options for extension UI dialogs. */
 export interface ExtensionUIDialogOptions {
@@ -520,11 +521,26 @@ export interface SessionTreeEvent {
     fromExtension?: boolean;
 }
 export type SessionEvent = SessionStartEvent | SessionInfoChangedEvent | SessionBeforeSwitchEvent | SessionBeforeForkEvent | SessionBeforeCompactEvent | SessionCompactEvent | SessionCompactFailedEvent | SessionShutdownEvent | SessionBeforeTreeEvent | SessionTreeEvent;
-/** Fired before each LLM call. Can modify messages. */
+/**
+ * Fired before each LLM call. Can modify messages.
+ *
+ * `messages` holds the conversation without system messages. The prompt and tool state
+ * belong to Pi: it restores them after the handler returns, so a handler cannot drop
+ * them and does not need to preserve them.
+ */
 export interface ContextEvent {
     type: "context";
     messages: AgentMessage[];
 }
+/**
+ * Fired before each LLM call, after every `context` handler has run and Pi has restored
+ * the prompt and tool state. `messages` is the full transcript including system messages,
+ * and the result is sent as returned: the handler owns the prompt and tool declarations.
+ */
+export interface ContextWithSystemEvent {
+    type: "context_with_system";
+    messages: AgentMessage[];
+}
 /** Fired before a provider request is sent. Can replace the payload. */
 export interface BeforeProviderRequestEvent {
     type: "before_provider_request";
@@ -552,10 +568,10 @@ export interface BeforeAgentStartEvent {
     prompt: string;
     /** Images attached to the user prompt, if any. */
     images?: ImageContent[];
-    /** The fully assembled system prompt string. */
-    systemPrompt: string;
-    /** Structured options used to build the system prompt. Extensions can inspect this to understand what Pi loaded without re-discovering resources. */
-    systemPromptOptions: BuildSystemPromptOptions;
+    /** The current system prompt, rendered from systemPromptOptions and earlier handler changes. */
+    readonly systemPrompt: string;
+    /** Mutable prompt sections. Later handlers observe mutations made by earlier handlers. */
+    systemPromptOptions: NormalizedBuildSystemPromptOptions;
 }
 /** Fired when an agent loop starts */
 export interface AgentStartEvent {
@@ -566,6 +582,54 @@ export interface AgentEndEvent {
     type: "agent_end";
     messages: AgentMessage[];
 }
+export type AgentActivityOutcome = "completed" | "aborted" | "error";
+export interface CustomEntryDraft {
+    type: "custom";
+    customType: string;
+    data?: unknown;
+}
+export interface CustomMessageEntryDraft {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: unknown;
+}
+export interface ContextEditEntryDraft {
+    type: "context_edit";
+    targetId: string;
+    replacement: ContextEditEntry["replacement"];
+}
+export interface CompactionEntryDraft {
+    type: "compaction";
+    summary: string;
+    /** Null creates a self-retaining compaction that keeps no preceding entries. */
+    firstKeptEntryId: string | null;
+    details?: unknown;
+    usage?: Usage;
+}
+export type SessionBoundaryDraft = CustomEntryDraft | CustomMessageEntryDraft | ContextEditEntryDraft | CompactionEntryDraft;
+export interface BoundaryContextPreview {
+    contextEntries: ProjectedSessionEntry[];
+    contextMessages: AgentMessage[];
+    llmMessages: Message[];
+    pendingMessages: AgentMessage[];
+    canContinue: boolean;
+}
+export interface BoundaryState {
+    entries: SessionBoundaryDraft[];
+    continue: boolean;
+    context: BoundaryContextPreview;
+    outcome: AgentActivityOutcome;
+}
+export interface BoundaryResult {
+    entries?: SessionBoundaryDraft[];
+    continue?: boolean;
+}
+/** Fired before final settlement. May append entries and ensure one next provider request. */
+export interface AgentBeforeSettleEvent extends BoundaryState {
+    type: "agent_before_settle";
+}
 /** Fired after an agent run has fully settled and no automatic retry, compaction, or queued continuation will run. */
 export interface AgentSettledEvent {
     type: "agent_settled";
@@ -592,11 +656,13 @@ export interface TurnStartEvent {
     timestamp: number;
 }
 /** Fired at the end of each turn */
-export interface TurnEndEvent {
+export interface TurnEndEvent extends BoundaryState {
     type: "turn_end";
     turnIndex: number;
     message: AgentMessage;
     toolResults: ToolResultMessage[];
+    messageEntryId: string;
+    toolResultEntryIds: string[];
 }
 /** Fired when a message starts (user, assistant, or toolResult) */
 export interface MessageStartEvent {
@@ -820,11 +886,14 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentSettledEvent | UIPromptStartEvent | UIPromptEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
+export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | ContextWithSystemEvent | CacheWarmingDecisionEvent | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentBeforeSettleEvent | AgentSettledEvent | UIPromptStartEvent | UIPromptEndEvent | TurnStartEvent | TurnEndEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent | ToolExecutionEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | UserBashEvent | InputEvent | ToolCallEvent | ToolResultEvent;
 export interface ContextEventResult {
     messages?: AgentMessage[];
 }
+export type TurnEndEventResult = BoundaryResult;
+export type AgentBeforeSettleEventResult = BoundaryResult;
 export type BeforeProviderRequestEventResult = unknown;
+export type { CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult } from "../cache-warmer.ts";
 export interface ToolCallEventResult {
     /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
     block?: boolean;
@@ -836,12 +905,15 @@ export interface ToolCallEventResult {
     terminate?: boolean;
 }
 /** Result from user_bash event handler */
-export interface UserBashEventResult {
+export type UserBashEventResult = {
     /** Custom operations to use for execution */
-    operations?: BashOperations;
+    operations: BashOperations;
+    result?: never;
+} | {
+    operations?: never;
     /** Full replacement: extension handled execution, use this result */
-    result?: BashResult;
-}
+    result: BashResult;
+};
 export interface ToolResultEventResult {
     content?: (TextContent | ImageContent)[];
     details?: unknown;
@@ -854,7 +926,7 @@ export interface MessageEndEventResult {
 }
 export interface BeforeAgentStartEventResult {
     message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
-    /** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
+    /** Replace the complete system prompt for this turn. Later handlers observe this exact override. */
     systemPrompt?: string;
 }
 export interface SessionBeforeSwitchResult {
@@ -914,42 +986,45 @@ export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContex
  * ExtensionAPI passed to extension factory functions.
  */
 export interface ExtensionAPI {
-    on(event: "project_trust", handler: ProjectTrustHandler): void;
-    on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
-    on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
-    on(event: "session_info_changed", handler: ExtensionHandler<SessionInfoChangedEvent>): void;
-    on(event: "session_before_switch", handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>): void;
-    on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
-    on(event: "session_before_compact", handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>): void;
-    on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
-    on(event: "session_compact_failed", handler: ExtensionHandler<SessionCompactFailedEvent>): 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_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>): void;
-    on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>): void;
-    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): 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: "agent_settled", handler: ExtensionHandler<AgentSettledEvent>): void;
-    on(event: "ui_prompt_start", handler: ExtensionHandler<UIPromptStartEvent>): void;
-    on(event: "ui_prompt_end", handler: ExtensionHandler<UIPromptEndEvent>): void;
-    on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
-    on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
-    on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
-    on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;
-    on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): void;
-    on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
-    on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
-    on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
-    on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
-    on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): void;
-    on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
-    on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
-    on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
-    on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
+    on(event: "project_trust", handler: ProjectTrustHandler): () => void;
+    on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): () => void;
+    on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): () => void;
+    on(event: "session_info_changed", handler: ExtensionHandler<SessionInfoChangedEvent>): () => void;
+    on(event: "session_before_switch", handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>): () => void;
+    on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): () => void;
+    on(event: "session_before_compact", handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>): () => void;
+    on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): () => void;
+    on(event: "session_compact_failed", handler: ExtensionHandler<SessionCompactFailedEvent>): () => 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: "context_with_system", handler: ExtensionHandler<ContextWithSystemEvent, ContextEventResult>): () => void;
+    on(event: "cache_warming_decision", handler: ExtensionHandler<CacheWarmingDecisionEvent, CacheWarmingDecisionEventResult>): () => void;
+    on(event: "before_provider_request", handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>): () => void;
+    on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>): () => void;
+    on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): () => 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: "agent_before_settle", handler: ExtensionHandler<AgentBeforeSettleEvent, AgentBeforeSettleEventResult>): () => void;
+    on(event: "agent_settled", handler: ExtensionHandler<AgentSettledEvent>): () => void;
+    on(event: "ui_prompt_start", handler: ExtensionHandler<UIPromptStartEvent>): () => void;
+    on(event: "ui_prompt_end", handler: ExtensionHandler<UIPromptEndEvent>): () => void;
+    on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): () => void;
+    on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent, TurnEndEventResult>): () => void;
+    on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): () => void;
+    on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): () => void;
+    on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): () => void;
+    on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): () => void;
+    on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): () => void;
+    on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): () => void;
+    on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): () => void;
+    on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): () => void;
+    on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): () => void;
+    on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): () => void;
+    on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): () => void;
+    on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): () => void;
     /** Register a tool that the LLM can call. */
     registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(tool: ToolDefinition<TParams, TDetails, TState>): void;
     /** Register a custom command. */
@@ -1009,11 +1084,17 @@ export interface ExtensionAPI {
     setActiveTools(toolNames: string[]): void;
     /** Get available slash commands in the current session. */
     getCommands(): SlashCommandInfo[];
-    /** Set the current model. Returns false if no API key available. */
+    /**
+     * Set the model for the current session without changing the configured default for new sessions.
+     * Returns false if authentication is not configured for the model's provider.
+     */
     setModel(model: Model<any>): Promise<boolean>;
     /** Get current thinking level. */
     getThinkingLevel(): ThinkingLevel;
-    /** Set thinking level (clamped to model capabilities). */
+    /**
+     * Set the thinking level (clamped to model capabilities) for the current session without changing the configured default
+     * for new sessions.
+     */
     setThinkingLevel(level: ThinkingLevel): void;
     /**
      * Register or override a model provider.
@@ -1098,11 +1179,13 @@ export interface ProviderConfig {
     api?: Api;
     /**
      * Optional streamSimple handler for custom APIs.
+     * The context is a normalized transcript: read the prompt and tools from its system messages
+     * (`getCurrentSystemPrompt(context.messages)`, `getCurrentTools(context.messages)`).
      * Implementations must invoke `options.onPayload` before sending the provider request and use any
      * returned replacement payload. They must invoke `options.onResponse` after receiving the response
      * and before consuming its body, matching built-in providers.
      */
-    streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+    streamSimple?: (model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions) => AssistantMessageEventStream;
     /** Custom headers to include in requests. */
     headers?: Record<string, string>;
     /** If true, adds Authorization: Bearer header with the resolved API key. */
@@ -1148,8 +1231,12 @@ export interface ProviderModelConfig {
     thinkingLevelMap?: Model<Api>["thinkingLevelMap"];
     /** Supported input types. */
     input: ("text" | "image")[];
+    /** Provider input limits and cache-safe image preprocessing metadata. */
+    inputLimits?: Model<Api>["inputLimits"];
     /** Per-million-token cost rates and optional request-wide input pricing tiers. */
     cost: Model<Api>["cost"];
+    /** Best-effort prompt cache lifetime in seconds per retention tier. Unset disables cache warming. */
+    promptCache?: Model<Api>["promptCache"];
     /** Maximum context window size in tokens. */
     contextWindow: number;
     /** Maximum output tokens. */