@oh-my-pi/pi-agent-core 15.1.0 → 15.1.2

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [15.1.2] - 2026-05-15
+### Added
+
+- Added `responseHeaders` to `ChatUsageEvent` and `ManualChatTelemetryOptions` so telemetry hooks receive captured lowercase upstream response headers for each chat span
+- Added automatic gateway/proxy detection from response headers (`litellm`, `helicone`, `portkey`, `openrouter`) and stamped `pi.gen_ai.gateway.*` span attributes for detected routing metadata
+- Added exported `detectGatewayFromHeaders` API for header-based gateway detection
+
 ## [15.1.0] - 2026-05-15
 ### Breaking Changes
 

package/dist/types/agent-loop.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import { EventStream } from "@oh-my-pi/pi-ai";
+import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
+ * run-level telemetry/coverage rollup to the existing `AgentMessage[]`
+ * payload without changing the resolved type of `stream.result()`.
+ */
+export interface AgentLoopDetailedResult {
+    readonly messages: AgentMessage[];
+    readonly telemetry: AgentRunSummary | undefined;
+    readonly coverage: AgentRunCoverage | undefined;
+}
+/**
+ * Convenience wrapper over {@link agentLoop} that exposes the run-level
+ * summary + coverage alongside the messages. The returned `stream` is the
+ * same `EventStream` callers already consume; `detailed()` awaits the
+ * stream's `agent_end` event and returns the additive fields.
+ *
+ * Existing `stream.result()` semantics are preserved — it still resolves to
+ * `AgentMessage[]`. Use {@link agentLoopDetailed} when you need the rollup;
+ * use {@link agentLoop} when you do not.
+ */
+export declare function agentLoopDetailed(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+/**
+ * Like {@link agentLoopDetailed} but built on top of
+ * {@link agentLoopContinue}.
+ */
+export declare function agentLoopContinueDetailed(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+export declare const INTENT_FIELD = "_i";

package/dist/types/agent.d.ts

@@ -0,0 +1,318 @@
+/** Agent class that uses the agent-loop directly.
+ * No transport abstraction - calls streamSimple via the loop.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@oh-my-pi/pi-ai";
+import type { HarmonyAuditEvent } from "./harmony-leak";
+import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, StreamFn, ToolCallContext } from "./types";
+export declare class AgentBusyError extends Error {
+    constructor(message?: string);
+}
+export interface AgentOptions {
+    initialState?: Partial<AgentState>;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     * Default filters to user/assistant/toolResult and converts attachments.
+     */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to context before convertToLlm.
+     * Use for context pruning, injecting external context, etc.
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
+     */
+    steeringMode?: "all" | "one-at-a-time";
+    /**
+     * Follow-up mode: "all" = send all follow-up messages at once, "one-at-a-time" = one per turn
+     */
+    followUpMode?: "all" | "one-at-a-time";
+    /**
+     * When to interrupt tool execution for steering messages.
+     * - "immediate": check after each tool call (default)
+     * - "wait": defer steering until the current turn completes
+     */
+    interruptMode?: "immediate" | "wait";
+    /**
+     * API format for Kimi Code provider: "openai" or "anthropic" (default: "anthropic")
+     */
+    kimiApiFormat?: "openai" | "anthropic";
+    /** Hint that websocket transport should be preferred when supported by the provider implementation. */
+    preferWebsockets?: boolean;
+    /**
+     * Custom stream function (for proxy backends, etc.). Default uses streamSimple.
+     */
+    streamFn?: StreamFn;
+    /**
+     * Optional session identifier forwarded to LLM providers.
+     * Used by providers that support session-based caching (e.g., OpenAI Codex).
+     */
+    sessionId?: string;
+    /**
+     * Shared provider state map for session-scoped transport/session caches.
+     */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     * Useful for expiring tokens (e.g., GitHub Copilot OAuth).
+     */
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Inspect or replace provider payloads before they are sent.
+     */
+    onPayload?: SimpleStreamOptions["onPayload"];
+    /**
+     * Inspect provider response metadata after headers arrive and before streaming body consumption.
+     */
+    onResponse?: SimpleStreamOptions["onResponse"];
+    /**
+     * Inspect raw Server-Sent Events from HTTP streaming providers.
+     */
+    onSseEvent?: SimpleStreamOptions["onSseEvent"];
+    /**
+     * Inspect assistant streaming events before they are emitted to subscribers.
+     * Use this when abort decisions must happen before buffered events continue flowing.
+     */
+    onAssistantMessageEvent?: (message: AssistantMessage, event: AssistantMessageEvent) => void;
+    /**
+     * Called when GPT-5 Harmony protocol leakage is detected and mitigated.
+     */
+    onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
+    /**
+     * Custom token budgets for thinking levels (token-based providers only).
+     */
+    thinkingBudgets?: ThinkingBudgets;
+    /**
+     * Sampling temperature for LLM calls. `undefined` uses provider default.
+     */
+    temperature?: number;
+    /** Additional sampling controls for providers that support them. */
+    topP?: number;
+    topK?: number;
+    minP?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+    serviceTier?: ServiceTier;
+    /**
+     * If true, request that the underlying provider omit reasoning/thinking summaries
+     * from the response. The model still reasons internally; only the human-readable
+     * summary stream is suppressed. Useful when the UI hides thinking blocks anyway.
+     */
+    hideThinkingSummary?: boolean;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately,
+     * allowing higher-level retry logic to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Provides tool execution context, resolved per tool call.
+     * Use for late-bound UI or session state access.
+     */
+    getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
+    /**
+     * Optional transform applied to tool call arguments before execution.
+     * Use for deobfuscating secrets or rewriting arguments.
+     */
+    transformToolCallArguments?: (args: Record<string, unknown>, toolName: string) => Record<string, unknown>;
+    /** Enable intent tracing schema injection/stripping in the harness. */
+    intentTracing?: boolean;
+    /** Dynamic tool choice override, resolved per LLM call. */
+    getToolChoice?: () => ToolChoice | undefined;
+    /**
+     * Cursor exec handlers for local tool execution.
+     */
+    cursorExecHandlers?: CursorExecHandlers;
+    /**
+     * Cursor tool result callback for exec tool responses.
+     */
+    cursorOnToolResult?: CursorToolResultHandler;
+    /**
+     * Called after a tool call has been validated and is about to execute.
+     * See {@link AgentLoopConfig.beforeToolCall} for full semantics.
+     */
+    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
+    /**
+     * Called after a tool finishes executing, before `tool_execution_end` and the tool-result
+     * message are emitted. See {@link AgentLoopConfig.afterToolCall} for full semantics.
+     */
+    afterToolCall?: AgentLoopConfig["afterToolCall"];
+    /**
+     * Opt-in OpenTelemetry instrumentation. Passing `{}` enables the loop's
+     * GenAI-semantic-convention spans using the global tracer provider. See
+     * {@link AgentLoopConfig.telemetry} for the full surface.
+     */
+    telemetry?: AgentLoopConfig["telemetry"];
+}
+export interface AgentPromptOptions {
+    toolChoice?: ToolChoice;
+}
+export declare class Agent {
+    #private;
+    streamFn: StreamFn;
+    getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Hook invoked after tool arguments are validated and before execution.
+     * Reassign at any time to swap the implementation (e.g. on extension reload).
+     */
+    beforeToolCall?: AgentLoopConfig["beforeToolCall"];
+    /**
+     * Hook invoked after tool execution and before `tool_execution_end` / tool-result
+     * message emission. Reassign at any time to swap the implementation.
+     */
+    afterToolCall?: AgentLoopConfig["afterToolCall"];
+    constructor(opts?: AgentOptions);
+    /**
+     * Get the current session ID used for provider caching.
+     */
+    get sessionId(): string | undefined;
+    /**
+     * Set the session ID for provider caching.
+     * Call this when switching sessions (new session, branch, resume).
+     */
+    set sessionId(value: string | undefined);
+    /**
+     * Static metadata forwarded to every API request when no resolver is installed
+     * (e.g. `metadata.user_id` for Anthropic session attribution). Setting this
+     * clears any installed resolver.
+     *
+     * For live/provider-aware metadata (e.g. Anthropic OAuth `account_uuid` that
+     * must reflect the credential selected per-request), use
+     * {@link setMetadataResolver} and read via {@link metadataForProvider}.
+     */
+    get metadata(): Record<string, unknown> | undefined;
+    set metadata(value: Record<string, unknown> | undefined);
+    /**
+     * Resolve request metadata for the given provider at call time. When a
+     * resolver is installed via {@link setMetadataResolver}, it is invoked with
+     * the provider string so the result can be scoped (e.g. `account_uuid` is
+     * only included for `"anthropic"` requests). Falls back to the static
+     * {@link metadata} value when no resolver is set.
+     */
+    metadataForProvider(provider: string): Record<string, unknown> | undefined;
+    /**
+     * Install a function that resolves request metadata at call time. The
+     * resolver receives the target provider string and can gate provider-specific
+     * fields (e.g. `account_uuid` only for `"anthropic"`). Invoked per LLM
+     * request by `agent-loop` after `getApiKey` selects the session-sticky
+     * credential. Pass `undefined` to clear and revert to the static
+     * {@link metadata} value.
+     */
+    setMetadataResolver(resolver: ((provider: string) => Record<string, unknown> | undefined) | undefined): void;
+    /**
+     * Read the active OpenTelemetry configuration. Returns `undefined` when
+     * instrumentation is disabled. Callers spawning child runs (e.g. subagent
+     * dispatch) forward this to the child's loop so its spans appear under the
+     * parent's active context with the subagent's own identity stamped.
+     */
+    get telemetry(): AgentLoopConfig["telemetry"] | undefined;
+    /**
+     * Replace the active OpenTelemetry configuration. Pass `undefined` to
+     * disable instrumentation. Applies to the *next* `agentLoop` invocation —
+     * in-flight loops keep the configuration they started with.
+     */
+    setTelemetry(telemetry: AgentLoopConfig["telemetry"] | undefined): void;
+    /**
+     * Get provider-scoped mutable session state store.
+     */
+    get providerSessionState(): Map<string, ProviderSessionState> | undefined;
+    /**
+     * Set provider-scoped mutable session state store.
+     */
+    set providerSessionState(value: Map<string, ProviderSessionState> | undefined);
+    /**
+     * Get the current thinking budgets.
+     */
+    get thinkingBudgets(): ThinkingBudgets | undefined;
+    /**
+     * Set custom thinking budgets for token-based providers.
+     */
+    set thinkingBudgets(value: ThinkingBudgets | undefined);
+    /**
+     * Get the current sampling temperature.
+     */
+    get temperature(): number | undefined;
+    /**
+     * Set sampling temperature for LLM calls. `undefined` uses provider default.
+     */
+    set temperature(value: number | undefined);
+    get topP(): number | undefined;
+    set topP(value: number | undefined);
+    get topK(): number | undefined;
+    set topK(value: number | undefined);
+    get minP(): number | undefined;
+    set minP(value: number | undefined);
+    get presencePenalty(): number | undefined;
+    set presencePenalty(value: number | undefined);
+    get repetitionPenalty(): number | undefined;
+    set repetitionPenalty(value: number | undefined);
+    get serviceTier(): ServiceTier | undefined;
+    set serviceTier(value: ServiceTier | undefined);
+    get hideThinkingSummary(): boolean | undefined;
+    set hideThinkingSummary(value: boolean | undefined);
+    /**
+     * Get the current max retry delay in milliseconds.
+     */
+    get maxRetryDelayMs(): number | undefined;
+    /**
+     * Set the maximum delay to wait for server-requested retries.
+     * Set to 0 to disable the cap.
+     */
+    set maxRetryDelayMs(value: number | undefined);
+    get state(): AgentState;
+    subscribe(fn: (e: AgentEvent) => void): () => void;
+    setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
+    setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;
+    setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
+    emitExternalEvent(event: AgentEvent): void;
+    setSystemPrompt(v: string[]): void;
+    setModel(m: Model): void;
+    setThinkingLevel(l: Effort | undefined): void;
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    getSteeringMode(): "all" | "one-at-a-time";
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    getFollowUpMode(): "all" | "one-at-a-time";
+    setInterruptMode(mode: "immediate" | "wait"): void;
+    getInterruptMode(): "immediate" | "wait";
+    setTools(t: AgentTool<any>[]): void;
+    replaceMessages(ms: AgentMessage[]): void;
+    appendMessage(m: AgentMessage): void;
+    popMessage(): AgentMessage | undefined;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     * Delivered after current tool execution, skips remaining tools.
+     */
+    steer(m: AgentMessage): void;
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     * Delivered only when agent has no more tool calls or steering messages.
+     */
+    followUp(m: AgentMessage): void;
+    clearSteeringQueue(): void;
+    clearFollowUpQueue(): void;
+    clearAllQueues(): void;
+    hasQueuedMessages(): boolean;
+    /**
+     * Remove and return the last steering message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastSteer(): AgentMessage | undefined;
+    /**
+     * Remove and return the last follow-up message from the queue (LIFO).
+     * Used by dequeue keybinding.
+     */
+    popLastFollowUp(): AgentMessage | undefined;
+    clearMessages(): void;
+    abort(): void;
+    waitForIdle(): Promise<void>;
+    reset(): void;
+    /** Send a prompt with an AgentMessage */
+    prompt(message: AgentMessage | AgentMessage[], options?: AgentPromptOptions): Promise<void>;
+    prompt(input: string, options?: AgentPromptOptions): Promise<void>;
+    prompt(input: string, images?: ImageContent[], options?: AgentPromptOptions): Promise<void>;
+    /**
+     * Continue from current context (used for retries and resuming queued messages).
+     */
+    continue(): Promise<void>;
+}

package/dist/types/compaction/branch-summarization.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Branch summarization for tree navigation.
+ *
+ * When navigating to a different point in the session tree, this generates
+ * a summary of the branch being left so context isn't lost.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { AgentMessage } from "../types";
+import type { ReadonlySessionManager, SessionEntry } from "./entries";
+import { type ConvertToLlm } from "./messages";
+import { type FileOperations } from "./utils";
+export interface BranchSummaryResult {
+    summary?: string;
+    readFiles?: string[];
+    modifiedFiles?: string[];
+    aborted?: boolean;
+    error?: string;
+}
+/** Details stored in BranchSummaryEntry.details for file tracking */
+export interface BranchSummaryDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export type { FileOperations } from "./utils";
+export interface BranchPreparation {
+    /** Messages extracted for summarization, in chronological order */
+    messages: AgentMessage[];
+    /** File operations extracted from tool calls */
+    fileOps: FileOperations;
+    /** Total estimated tokens in messages */
+    totalTokens: number;
+}
+export interface CollectEntriesResult {
+    /** Entries to summarize, in chronological order */
+    entries: SessionEntry[];
+    /** Common ancestor between old and new position, if any */
+    commonAncestorId: string | null;
+}
+export interface GenerateBranchSummaryOptions {
+    /** Model to use for summarization */
+    model: Model;
+    /** API key for the model */
+    apiKey: string;
+    /** Abort signal for cancellation */
+    signal: AbortSignal;
+    /** Optional custom instructions for summarization */
+    customInstructions?: string;
+    /** Tokens reserved for prompt + LLM response (default 16384) */
+    reserveTokens?: number;
+    /** Optional metadata forwarded to the underlying API request (e.g. user_id for session attribution). */
+    metadata?: Record<string, unknown>;
+    /** Convert app-specific messages before serializing the branch summary prompt. */
+    convertToLlm?: ConvertToLlm;
+}
+/**
+ * Collect entries that should be summarized when navigating from one position to another.
+ *
+ * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
+ * along the way. Does NOT stop at compaction boundaries - those are included and their
+ * summaries become context.
+ *
+ * @param session - Session manager (read-only access)
+ * @param oldLeafId - Current position (where we're navigating from)
+ * @param targetId - Target position (where we're navigating to)
+ * @returns Entries to summarize and the common ancestor
+ */
+export declare function collectEntriesForBranchSummary(session: ReadonlySessionManager, oldLeafId: string | null, targetId: string): CollectEntriesResult;
+/**
+ * Prepare entries for summarization with token budget.
+ *
+ * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
+ * This ensures we keep the most recent context when the branch is too long.
+ *
+ * Also collects file operations from:
+ * - Tool calls in assistant messages
+ * - Existing branch_summary entries' details (for cumulative tracking)
+ *
+ * @param entries - Entries in chronological order
+ * @param tokenBudget - Maximum tokens to include (0 = no limit)
+ */
+export declare function prepareBranchEntries(entries: SessionEntry[], tokenBudget?: number): BranchPreparation;
+/**
+ * Generate a summary of abandoned branch entries.
+ *
+ * @param entries - Session entries to summarize (chronological order)
+ * @param options - Generation options
+ */
+export declare function generateBranchSummary(entries: SessionEntry[], options: GenerateBranchSummaryOptions): Promise<BranchSummaryResult>;

package/dist/types/compaction/compaction.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+import { type MessageAttribution, type Model, type Usage } from "@oh-my-pi/pi-ai";
+import type { AgentMessage, AgentTool } from "../types";
+import type { SessionEntry } from "./entries";
+import { type ConvertToLlm } from "./messages";
+import { type FileOperations } from "./utils";
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+    summary: string;
+    /** Short PR-style summary for display purposes. */
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Hook-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** Hook-provided data to persist alongside compaction entry. */
+    preserveData?: Record<string, unknown>;
+}
+export interface CompactionSettings {
+    enabled: boolean;
+    strategy?: "context-full" | "handoff" | "off";
+    thresholdPercent?: number;
+    thresholdTokens?: number;
+    reserveTokens: number;
+    keepRecentTokens: number;
+    autoContinue?: boolean;
+    remoteEnabled?: boolean;
+    remoteEndpoint?: string;
+}
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/**
+ * Calculate total context tokens from usage.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export declare function calculateContextTokens(usage: Usage): number;
+export declare function calculatePromptTokens(usage: Usage): number;
+/**
+ * Find the last non-aborted assistant message usage from session entries.
+ */
+export declare function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined;
+/**
+ * Effective reserve: at least 15% of context window or the configured floor, whichever is larger.
+ */
+export declare function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Estimate token count for a message using cl100k_base via the native
+ * tokenizer. This is not Claude's first-party tokenizer (Anthropic doesn't
+ * publish one) but is within ~5–10% across English/code text.
+ */
+export declare function estimateTokens(message: AgentMessage): number;
+/**
+ * Find the user message (or bashExecution) that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ * BashExecutionMessage is treated like a user message for turn boundaries.
+ */
+export declare function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number;
+export interface CutPointResult {
+    /** Index of first entry to keep */
+    firstKeptEntryIndex: number;
+    /** Index of user message that starts the turn being split, or -1 if not splitting */
+    turnStartIndex: number;
+    /** Whether this cut splits a turn (cut point is not a user message) */
+    isSplitTurn: boolean;
+}
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+export declare const AUTO_HANDOFF_THRESHOLD_FOCUS: string;
+/**
+ * Generate a summary of the conversation using the LLM.
+ * If previousSummary is provided, uses the update prompt to merge.
+ */
+export interface SummaryOptions {
+    promptOverride?: string;
+    extraContext?: string[];
+    remoteEndpoint?: string;
+    remoteInstructions?: string;
+    initiatorOverride?: MessageAttribution;
+    metadata?: Record<string, unknown>;
+    convertToLlm?: ConvertToLlm;
+}
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: string, signal?: AbortSignal, customInstructions?: string, previousSummary?: string, options?: SummaryOptions): Promise<string>;
+export interface HandoffOptions {
+    /** Live agent system prompt — passed verbatim so providers hit the cached prefix. */
+    systemPrompt: string[];
+    /** Live agent tool list — same purpose. Forced to `toolChoice: "none"`. */
+    tools?: AgentTool<any>[];
+    customInstructions?: string;
+    convertToLlm?: ConvertToLlm;
+    initiatorOverride?: MessageAttribution;
+    metadata?: Record<string, unknown>;
+}
+export declare function renderHandoffPrompt(customInstructions?: string): string;
+export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: string, options: HandoffOptions, signal?: AbortSignal): Promise<string>;
+export interface CompactionPreparation {
+    /** UUID of first entry to keep */
+    firstKeptEntryId: string;
+    /** Messages that will be summarized and discarded */
+    messagesToSummarize: AgentMessage[];
+    /** Messages that will be turned into turn prefix summary (if splitting) */
+    turnPrefixMessages: AgentMessage[];
+    /** Messages kept in full after compaction (recent history) */
+    recentMessages: AgentMessage[];
+    /** Whether this is a split turn (cut point in middle of turn) */
+    isSplitTurn: boolean;
+    tokensBefore: number;
+    /** Summary from previous compaction, for iterative update */
+    previousSummary?: string;
+    /** Preserved opaque compaction payload from the previous compaction, if any. */
+    previousPreserveData?: Record<string, unknown>;
+    /** File operations extracted from messagesToSummarize */
+    fileOps: FileOperations;
+    /** Compaction settions from settings.jsonl	*/
+    settings: CompactionSettings;
+}
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds id/parentId when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ */
+export declare function compact(preparation: CompactionPreparation, model: Model, apiKey: string, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;