@linxiraos/pi-agent-core 1.0.4 → 1.0.6

package/dist/types/append-only-context.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+import type { Context, Message, Tool } from "@linxiraos/pi-ai";
+import type { AgentContext } from "./types.js";
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+    systemPrompt: string[];
+    tools: Tool[];
+    fingerprint: string;
+}
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+    /** Inject the `i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+    intentTracing: boolean;
+    /** Strip tool descriptions from the provider-bound specs (must match normalizeTools). */
+    pruneToolDescriptions?: boolean;
+}
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export declare class StablePrefix {
+    #private;
+    get fingerprint(): string;
+    get version(): number;
+    get built(): boolean;
+    /**
+     * Build or rebuild from live context.
+     * Returns `true` if the prefix actually changed (cache miss imminent).
+     */
+    build(context: AgentContext, options: BuildOptions): boolean;
+    /** Force rebuild on the next `build()` call. */
+    invalidate(): void;
+    /**
+     * Returns the cached prefix.
+     * @throws if `build()` was never called.
+     */
+    toContext(): {
+        systemPrompt: string[];
+        tools: Tool[];
+    };
+}
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export declare class AppendOnlyLog {
+    #private;
+    get length(): number;
+    append(message: any): void;
+    extend(messages: any[]): void;
+    /** Replace the last entry — only legal for compaction. */
+    replaceTail(replacement: any): void;
+    /** Returns a shallow copy of all entries. */
+    toMessages(): Message[];
+    /** Direct readonly access for in-place inspection. */
+    entries(): readonly Message[];
+    /** Drop entries past index `count`, keeping the first `count` byte-stable.
+     * Used by {@link AppendOnlyContextManager.syncMessages} to preserve the
+     * already-on-the-wire prefix when a later message diverges. */
+    truncate(count: number): void;
+    clear(): void;
+}
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export declare class AppendOnlyContextManager {
+    #private;
+    readonly prefix: StablePrefix;
+    readonly log: AppendOnlyLog;
+    build(context: AgentContext, options: BuildOptions): Context;
+    /**
+     * Sync normalized (provider-level) messages into the append-only log.
+     *
+     * Three cases:
+     *
+     * 1. **Append**: same prefix, new tail → push the new entries.
+     * 2. **Compaction**: shorter array → clear the log and replay.
+     * 3. **In-place rewrite** (per-turn pruning, transformContext re-render,
+     *    image strip, etc.): find the longest byte-stable prefix between
+     *    the previously-synced messages and the new ones, drop the log
+     *    down to that prefix, then append the diverged tail. Earlier
+     *    revisions cleared the whole log on any digest change, which on
+     *    llama.cpp / local backends forced a full ~40k-token re-prefill
+     *    every turn that an extension, prune pass, or steering re-wrap
+     *    rewrote a single message (#3406). Preserving the stable prefix
+     *    lets the provider's KV cache stay warm up to the divergence
+     *    point — the model only re-prefills from the changed message on.
+     */
+    syncMessages(normalizedMessages: any[]): void;
+    /** Reset prefix + log for a model/provider switch while mode stays active. */
+    invalidateForModelChange(): void;
+    /** Reset the sync cursor AND clear the log. */
+    resetSyncCursor(): void;
+    appendMessage(message: any): void;
+    replaceTailMessage(message: any): void;
+    invalidate(): void;
+    reset(context: AgentContext, options: BuildOptions): void;
+}

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

@@ -0,0 +1,101 @@
+/**
+ * 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 { Api, ApiKey, AssistantMessage, Context, Model, SimpleStreamOptions } from "@linxiraos/pi-ai";
+import { type AgentTelemetry } from "../telemetry.js";
+import type { AgentMessage } from "../types.js";
+import type { ReadonlySessionManager, SessionEntry } from "./entries.js";
+import { type ConvertToLlm } from "./messages.js";
+import { type FileOperations } from "./utils.js";
+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.js";
+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: ApiKey;
+    /** 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;
+    /**
+     * Optional telemetry handle. When provided, the branch summary LLM call is
+     * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "branch_summary"`.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Optional completion transport override (same contract as
+     * {@link SummaryOptions.completeImpl}). Lets the host route the branch
+     * summary HTTP request through its provider-concurrency limiter instead
+     * of the default `completeSimple` transport.
+     */
+    completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+}
+/**
+ * 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-v2-streaming.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Remote Compaction V2: streaming Responses compaction.
+ *
+ * Mirrors Codex `core/src/compact_remote_v2.rs`: append a `compaction_trigger`
+ * input item to the normal Responses stream, require exactly one streamed
+ * compaction output item, then install retained real user messages plus that
+ * compaction item as replacement history.
+ */
+import type { CodexCompactionContext, FetchImpl, Model, ProviderSessionState } from "@linxiraos/pi-ai";
+/** Retained-message budget Codex uses after streamed V2 compaction. */
+export declare const V2_RETAINED_MESSAGE_TOKEN_BUDGET = 64000;
+/** Max retries for V2 streaming compaction on transient stream errors. */
+export declare const V2_COMPACTION_MAX_RETRIES = 2;
+/** Timeout for V2 streaming compaction (3 minutes, same as V1). */
+export declare const V2_COMPACTION_TIMEOUT_MS = 180000;
+/** Token usage reported by the streamed V2 Responses completion. */
+export interface CompactionV2Usage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cachedInputTokens?: number;
+    reasoningOutputTokens?: number;
+}
+/** Request body fields needed for Responses-stream V2 compaction. */
+export interface CompactionV2Request {
+    model: string;
+    input: unknown[];
+    instructions: string;
+    retainedMessageBudget: number;
+    tools?: unknown[];
+    /** Responses reasoning param (effort + summary), matching a normal turn; omitted for non-reasoning models. */
+    reasoning?: {
+        effort: string;
+        summary: string;
+    };
+    sessionId?: string;
+    promptCacheKey?: string;
+}
+/** Response collected from the V2 stream and converted into replacement history. */
+export interface CompactionV2Response {
+    compactionItem: Record<string, unknown>;
+    replacementHistory: Array<Record<string, unknown>>;
+    usedTokens: number;
+    usage?: CompactionV2Usage;
+    retainedImageCount: number;
+}
+/** Resolve the streaming Responses endpoint for a V2-capable model. */
+export declare function getCompactionV2Endpoint(model: Model): string | undefined;
+/** Check whether a model can use streaming V2 compaction. */
+export declare function shouldUseCompactionV2Streaming(model: Model): model is Model<"openai-responses" | "azure-openai-responses" | "openai-codex-responses">;
+/** Clamp the retained-message budget to Codex's known-safe 64K ceiling. */
+export declare function resolveCompactionV2RetainedMessageBudget(value: number | undefined): number;
+/** Build a V2 streaming compaction request from Responses-native history. */
+export declare function buildCompactionV2Request(model: Model, input: unknown[], instructions: string, options?: {
+    tools?: unknown[];
+    reasoning?: {
+        effort: string;
+        summary: string;
+    };
+    sessionId?: string;
+    promptCacheKey?: string;
+    retainedMessageBudget?: number;
+}): CompactionV2Request;
+/** Request V2 compaction over the normal OpenAI Responses streaming endpoint. */
+export declare function requestCompactionV2Streaming(model: Model, apiKey: string, request: CompactionV2Request, signal?: AbortSignal, options?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+    retryWait?: (delayMs: number, signal?: AbortSignal) => Promise<void>;
+    providerSessionState?: Map<string, ProviderSessionState>;
+    codexCompaction?: CodexCompactionContext;
+    preferWebsockets?: boolean;
+}): Promise<CompactionV2Response>;
+/** Build Codex-style V2 replacement history from prompt input plus compaction output. */
+export declare function buildCompactionV2ReplacementHistory(input: unknown[], compactionItem: Record<string, unknown>, retainedMessageBudget?: number): {
+    replacementHistory: Array<Record<string, unknown>>;
+    retainedImageCount: number;
+};
+/** Store V2 replacement history in the OpenAI remote-compaction preserve slot. */
+export declare function storeCompactionV2PreserveData(response: CompactionV2Response, model: Model): Record<string, unknown>;
+/** Retrieve preserved OpenAI replacement history that V2 can extend. */
+export declare function getCompactionV2PreserveData(preserveData: Record<string, unknown> | undefined): {
+    provider: string;
+    replacementHistory: Array<Record<string, unknown>>;
+    usedTokens: number;
+} | undefined;

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

@@ -0,0 +1,321 @@
+/**
+ * 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 Api, type ApiKey, type AssistantMessage, type CodexCompactionContext, type Context, type FetchImpl, type MessageAttribution, type Model, type OneshotRetryOptions, type ProviderSessionState, type SimpleStreamOptions, type Tool, type Usage } from "@linxiraos/pi-ai";
+import { type AgentTelemetry } from "../telemetry.js";
+import { ThinkingLevel } from "../thinking.js";
+import type { AgentMessage } from "../types.js";
+import type { SessionEntry } from "./entries.js";
+import { type ConvertToLlm } from "./messages.js";
+import { type FileOperations } from "./utils.js";
+/** 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" | "shake" | "snapcompact" | "off";
+    thresholdPercent?: number;
+    thresholdTokens?: number;
+    midTurnEnabled?: boolean;
+    /**
+     * Tokens reserved below the context window for the next prompt + response.
+     *
+     * Leave unset to use {@link DEFAULT_RESERVE_TOKENS}; the unset state is the
+     * provenance signal that lets small-window recovery replace the default with
+     * a proportional reserve (see {@link resolveBudgetReserveTokens}). An
+     * explicit value — even one equal to the default — is always honored.
+     */
+    reserveTokens?: number;
+    keepRecentTokens: number;
+    autoContinue?: boolean;
+    remoteEnabled?: boolean;
+    remoteEndpoint?: string;
+    remoteStreamingV2Enabled?: boolean;
+    v2RetainedMessageBudget?: number;
+}
+/** Reserve applied when {@link CompactionSettings.reserveTokens} is unset. */
+export declare const DEFAULT_RESERVE_TOKENS = 16384;
+/**
+ * Hard ceiling on a generated compaction summary.
+ *
+ * The summary budget is `floor(0.8 * reserveTokens)`, and the effective reserve is
+ * at least 15% of the declared context window, so a 1M-token window authorizes a
+ * ~120k-token summary. At that size the model copies rather than compresses, and
+ * output is the slowest and most expensive token class. Capping absolutely keeps
+ * the compression ratio improving with window size instead of degrading. The value
+ * mirrors {@link DEFAULT_RESERVE_TOKENS} so this adds no new tuning constant.
+ */
+export declare const MAX_SUMMARY_TOKENS = 16384;
+export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+/** Whether a compaction candidate preserves provider-native transport under the effective settings. */
+export declare function shouldUseProviderNativeCompaction(model: Model, settings: Pick<CompactionSettings, "remoteEnabled" | "remoteStreamingV2Enabled">): boolean;
+/**
+ * Calculate total context tokens from usage.
+ * Prefers an explicit provider-reported context occupancy when available.
+ * Otherwise uses totalTokens and falls back to computing from billable
+ * components. Provider-side orchestration tokens are billable but never replay
+ * into the conversation prefix, so they are excluded from context sizing.
+ */
+export declare function calculateContextTokens(usage: Usage): number;
+export declare function calculatePromptTokens(usage: Usage): number;
+export declare function hasContextTokenUsage(usage: Usage): boolean;
+/**
+ * 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
+ * (defaulting to {@link DEFAULT_RESERVE_TOKENS} when unset), whichever is larger.
+ */
+export declare function effectiveReserveTokens(contextWindow: number, settings: CompactionSettings): number;
+/**
+ * Reserve used when deciding whether a prompt still fits inside the model window.
+ *
+ * The default absolute reserve predates small bundled windows and can leave no
+ * practical budget there; recover a DEFAULTED reserve that is impossible for
+ * the window with the 15% proportional reserve (clamped to >= 1 so the derived
+ * threshold stays strictly below the window even for tiny test windows).
+ * Explicit valid reserves — including one that happens to equal the default —
+ * still win, because they intentionally shrink the usable prompt budget;
+ * provenance is carried by `settings.reserveTokens` being unset, never by
+ * comparing values against the default.
+ */
+export declare function resolveBudgetReserveTokens(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;
+/**
+ * Context tokens to feed the compaction decision, floored by a local estimate of
+ * the stored conversation.
+ *
+ * The provider-reported usage is normally ground truth, but a
+ * `before_provider_request` payload transform — a compression extension (e.g.
+ * Headroom), an obfuscator, or inline snapcompact — can shrink the request below
+ * the real stored conversation. The provider then reports deflated prompt
+ * tokens, so anchoring compaction purely on that usage lets the real history
+ * grow unbounded until it overflows and native compaction can no longer run.
+ * Flooring by the agent's own estimate of the stored conversation keeps the
+ * compaction trigger honest regardless of on-wire compression. (Display/cost
+ * accounting still uses the exact provider usage; only the compaction decision
+ * takes the floor.)
+ */
+export declare function compactionContextTokens(providerContextTokens: number, storedConversationEstimate: number): number;
+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.
+ *
+ * `excludeEncryptedReasoning` drops opaque provider reasoning payloads
+ * (`thinkingSignature`, `redactedThinking`) from the estimate. Those are billed
+ * by the provider on replay, so the default counts them — but their *local*
+ * byte size can diverge wildly from what the provider charges, so the
+ * compaction floor (which only needs the reliably-countable, on-wire-compressible
+ * content) excludes them to avoid false triggers on thinking-heavy turns.
+ */
+export declare function estimateTokens(message: AgentMessage, options?: {
+    excludeEncryptedReasoning?: boolean;
+}): 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;
+    /**
+     * Optional telemetry handle. When provided, every LLM call emitted during
+     * compaction is wrapped in an OTEL chat span tagged with
+     * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
+     * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Active session thinking level. Threaded from `agent-session.ts` so
+     * compaction honors the user's `/model` thinking selection instead of
+     * silently overriding it with `Effort.High` (the historical default).
+     * `undefined` / `ThinkingLevel.Inherit` falls back to that historical
+     * default; `ThinkingLevel.Off` omits reasoning entirely. See
+     * `resolveCompactionEffort` for the conversion contract.
+     */
+    thinkingLevel?: ThinkingLevel;
+    /** Session routing key for remote compaction transports with sticky provider sessions. */
+    sessionId?: string;
+    /** Prompt-cache key for remote compaction transports that support provider prefix caching. */
+    promptCacheKey?: string;
+    /** Mutable provider state used to keep Codex compaction on the live session identity. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Whether Codex remote compaction should prefer the provider WebSocket transport. */
+    preferWebsockets?: boolean;
+    /** Classification shared by every provider request in this logical compaction. */
+    codexCompaction?: CodexCompactionContext;
+    /** Provider-visible tools for remote compaction transports that replay native tool history. */
+    tools?: Tool[];
+    /** Optional fetch implementation threaded into remote compaction calls. */
+    fetch?: FetchImpl;
+    /**
+     * Optional completion transport override for host-level request wrappers
+     * (e.g. the coding-agent provider-concurrency limiter). When provided,
+     * every local summarization oneshot (`generateSummary`,
+     * `generateTurnPrefixSummary`, `generateShortSummary`) routes through it
+     * instead of the default `completeSimple`, so cap policies enforced on
+     * the live agent turn also bracket compaction HTTP requests.
+     */
+    completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+    /**
+     * Transient-failure retry for the summarization oneshots (`generateSummary`,
+     * `generateShortSummary`, `generateTurnPrefixSummary`).
+     *
+     * Defaults to enabled, which is what a one-shot caller such as manual
+     * `/compact` needs: a single Anthropic `overloaded_error` / 429 / 529 should
+     * not abort compaction and leave the context full.
+     *
+     * Pass `false` when the CALLER already owns a retry loop around the whole
+     * compaction attempt — auto-compaction does — otherwise the two budgets
+     * multiply (10 outer attempts x 3 inner = 30 requests) and each outer wait
+     * stacks on top of the inner backoff.
+     */
+    oneshotRetry?: OneshotRetryOptions | false;
+}
+export declare function generateSummary(currentMessages: AgentMessage[], model: Model, reserveTokens: number, apiKey: ApiKey, 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?: Tool[];
+    customInstructions?: string;
+    convertToLlm?: ConvertToLlm;
+    initiatorOverride?: MessageAttribution;
+    metadata?: Record<string, unknown>;
+    /**
+     * Optional telemetry handle. When provided, the handoff LLM call is
+     * wrapped in an OTEL chat span tagged with `pi.gen_ai.oneshot.kind = "handoff"`.
+     */
+    telemetry?: AgentTelemetry;
+    /**
+     * Active session thinking level. Threaded from `agent-session.ts` so
+     * handoff generation honors the user's `/model` thinking selection
+     * instead of silently overriding it with `Effort.High`. See
+     * `resolveCompactionEffort` for the conversion contract.
+     */
+    thinkingLevel?: ThinkingLevel;
+}
+export declare function renderHandoffPrompt(customInstructions?: string): string;
+export interface HandoffFromContextOptions {
+    /**
+     * Stream options mirrored from the live agent turn: `apiKey`, `signal`, the
+     * `sessionId`/`promptCacheKey` cache-routing pair, `serviceTier`, and the
+     * session's payload/response hooks. Sending the same routing + payload shape
+     * the main loop uses is what lets the handoff oneshot READ the provider
+     * prompt cache the live turn populated instead of cold-missing the whole
+     * prefix. `reasoning` and `toolChoice` are set internally and override
+     * anything provided here.
+     */
+    streamOptions: SimpleStreamOptions;
+    /** Optional completion transport override for host-level request wrappers. */
+    completeImpl?: <TApi extends Api>(model: Model<TApi>, ctx: Context, options: SimpleStreamOptions) => Promise<AssistantMessage>;
+    /** See {@link HandoffOptions.telemetry}. */
+    telemetry?: AgentTelemetry;
+    /** See {@link HandoffOptions.thinkingLevel}. */
+    thinkingLevel?: ThinkingLevel;
+}
+/**
+ * Run the handoff oneshot against a fully-built provider {@link Context}.
+ *
+ * The caller assembles `context` exactly like a live agent turn — same system
+ * prompt, normalized tools, transformed + obfuscated message history, with the
+ * trailing handoff-prompt message already appended — and supplies
+ * `streamOptions` that mirror the live turn's cache routing. That keeps the
+ * cache-preserving context construction in the host (which owns the transform
+ * pipeline) while this function centralizes the handoff request contract:
+ * cache-first `toolChoice: "none"`, clamped reasoning effort, one retry for
+ * auto-only `tool_choice` providers, oneshot telemetry, text-only extraction,
+ * and provider-error mapping.
+ */
+export declare function generateHandoffFromContext(context: Context, model: Model, options: HandoffFromContextOptions): Promise<string>;
+export declare function generateHandoff(messages: AgentMessage[], model: Model, apiKey: ApiKey, 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, activeModel?: Model): 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: ApiKey, customInstructions?: string, signal?: AbortSignal, options?: SummaryOptions): Promise<CompactionResult>;