@earendil-works/pi-coding-agent 0.86.1 → 0.87.0

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

@@ -8,7 +8,7 @@
  * - Interact with the user via UI primitives
  */
 import type { AgentMessage, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode } from "@earendil-works/pi-agent-core";
-import type { Api, AssistantMessageEvent, AssistantMessageEventStream, ConstrainedSamplingConfig, ImageContent, Model, OAuthCredentials, OAuthLoginCallbacks, Provider, ProviderHeaders, RefreshModelsContext, SimpleStreamOptions, TextContent, ToolResultMessage, TranscriptContext, 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 { Static, TSchema } from "typebox";
 import type { Theme } from "../../modes/interactive/theme/theme.ts";
@@ -22,7 +22,7 @@ import type { KeybindingsManager } from "../keybindings.ts";
 import type { CustomMessage } from "../messages.ts";
 import type { ModelRegistry } from "../model-registry.ts";
 import type { ScopedModel } from "../model-resolver.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, NormalizedBuildSystemPromptOptions } from "../system-prompt.ts";
@@ -511,11 +511,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";
@@ -557,6 +572,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";
@@ -583,11 +646,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 {
@@ -811,10 +876,12 @@ export declare function isToolCallEventType<TName extends string, TInput extends
     input: TInput;
 };
 /** Union of all event types */
-export type ExtensionEvent = ProjectTrustEvent | ResourcesDiscoverEvent | SessionEvent | ContextEvent | CacheWarmingDecisionEvent | 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 {
@@ -922,6 +989,7 @@ export interface ExtensionAPI {
     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;
@@ -929,11 +997,12 @@ export interface ExtensionAPI {
     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>): () => 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;
@@ -1152,6 +1221,8 @@ 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. */