jeopi-agent-core 16.2.13

package/dist/types/compaction/compaction-v2-streaming.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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 { FetchImpl, Model } from "jeopi-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>;
+}): 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,283 @@
+/**
+ * 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 Context, type FetchImpl, type MessageAttribution, type Model, type SimpleStreamOptions, type Tool, type Usage } from "jeopi-ai";
+import { type AgentTelemetry } from "../telemetry";
+import { ThinkingLevel } from "../thinking";
+import type { AgentMessage } 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" | "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;
+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
+ * (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;
+    /** 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>;
+}
+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:
+ * `toolChoice: "none"`, clamped reasoning effort, 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, compactionModels?: readonly 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>;

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

@@ -0,0 +1,110 @@
+import type { ImageContent, MessageAttribution, ServiceTierByFamily, TextContent } from "jeopi-ai";
+import type { AgentMessage } from "../types";
+export interface SessionEntryBase {
+    type: string;
+    id: string;
+    parentId: string | null;
+    timestamp: string;
+}
+export interface SessionMessageEntry extends SessionEntryBase {
+    type: "message";
+    message: AgentMessage;
+}
+export interface ThinkingLevelChangeEntry extends SessionEntryBase {
+    type: "thinking_level_change";
+    thinkingLevel?: string | null;
+}
+export interface ModelChangeEntry extends SessionEntryBase {
+    type: "model_change";
+    /** Model in "provider/modelId" format */
+    model: string;
+    /** Role: "default", "smol", "slow", etc. Undefined treated as "default" */
+    role?: string;
+}
+export interface ServiceTierChangeEntry extends SessionEntryBase {
+    type: "service_tier_change";
+    serviceTier: ServiceTierByFamily | null;
+}
+export interface CompactionEntry<T = unknown> extends SessionEntryBase {
+    type: "compaction";
+    summary: string;
+    shortSummary?: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+    /** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+    details?: T;
+    /** Hook-provided data to persist across compaction */
+    preserveData?: Record<string, unknown>;
+    /** True if generated by an extension, undefined/false if pi-generated (backward compatible) */
+    fromExtension?: boolean;
+}
+export interface BranchSummaryEntry<T = unknown> extends SessionEntryBase {
+    type: "branch_summary";
+    fromId: string;
+    summary: string;
+    /** Extension-specific data (not sent to LLM) */
+    details?: T;
+    /** True if generated by an extension, false if pi-generated */
+    fromExtension?: boolean;
+}
+export interface CustomMessageEntry<T = unknown> extends SessionEntryBase {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    details?: T;
+    display: boolean;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+}
+export interface CustomEntry<T = unknown> extends SessionEntryBase {
+    type: "custom";
+    customType: string;
+    data?: T;
+}
+export interface LabelEntry extends SessionEntryBase {
+    type: "label";
+    targetId: string;
+    label: string | undefined;
+}
+export interface TitleChangeEntry extends SessionEntryBase {
+    type: "title_change";
+    title: string;
+    previousTitle?: string;
+    source: "auto" | "user";
+    trigger?: string;
+}
+export interface TtsrInjectionEntry extends SessionEntryBase {
+    type: "ttsr_injection";
+    /** Names of rules that were injected */
+    injectedRules: string[];
+}
+export interface MCPToolSelectionEntry extends SessionEntryBase {
+    type: "mcp_tool_selection";
+    /** MCP tool names selected for visibility in discovery mode. */
+    selectedToolNames: string[];
+}
+export interface SessionInitEntry extends SessionEntryBase {
+    type: "session_init";
+    /** Full system prompt sent to the model */
+    systemPrompt: string;
+    /** Initial task/user message */
+    task: string;
+    /** Tools available to the agent */
+    tools: string[];
+    /** Output schema if structured output was requested */
+    outputSchema?: unknown;
+}
+export interface ModeChangeEntry extends SessionEntryBase {
+    type: "mode_change";
+    /** Current mode name, or "none" when exiting a mode */
+    mode: string;
+    /** Optional mode-specific data (e.g. plan file path) */
+    data?: Record<string, unknown>;
+}
+export interface CustomCompactionSessionEntries {
+}
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TitleChangeEntry | TtsrInjectionEntry | MCPToolSelectionEntry | SessionInitEntry | ModeChangeEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
+export interface ReadonlySessionManager {
+    getBranch(leafId?: string | null): SessionEntry[];
+    getEntry(id: string): SessionEntry | undefined;
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Compaction error types.
+ *
+ * `CompactionCancelledError` is the canonical signal raised when a compaction
+ * is explicitly aborted — operator Esc, extension hook returning `cancel`,
+ * programmatic `session.abortCompaction()` call, or any other deliberate
+ * abort source. Downstream callers (e.g. `executeCompaction`) discriminate
+ * cancellation from other failures via `instanceof CompactionCancelledError`
+ * rather than introspecting error messages or `name` fields — the typed
+ * sentinel makes classification source-agnostic and refactor-stable.
+ */
+export declare class CompactionCancelledError extends Error {
+    readonly name: "CompactionCancelledError";
+    constructor(message?: string);
+}
+/**
+ * Outcome of a compaction attempt, surfaced by `CommandController.executeCompaction`
+ * so callers (e.g. the plan-mode approval flow) can distinguish a deliberate abort
+ * from an unrelated failure.
+ *
+ *   "ok"        — compaction completed; transcript was summarized.
+ *   "cancelled" — `CompactionCancelledError` was raised. Operator Esc, extension
+ *                 hook, programmatic abort — all source-agnostic.
+ *   "failed"    — any other rejection from `session.compact()`.
+ */
+export type CompactionOutcome = "ok" | "cancelled" | "failed";

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

@@ -0,0 +1,12 @@
+/**
+ * Compaction and summarization utilities.
+ */
+export * from "./branch-summarization";
+export * from "./compaction";
+export * from "./entries";
+export * from "./errors";
+export * from "./messages";
+export * from "./openai";
+export * from "./pruning";
+export * from "./shake";
+export * from "./utils";

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

@@ -0,0 +1,77 @@
+import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "jeopi-ai";
+import type { AgentMessage } from "../types";
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/** Legacy hook message type (pre-extensions). Kept for session migration. */
+export interface HookMessage<T = unknown> {
+    role: "hookMessage";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+export interface BranchSummaryMessage {
+    role: "branchSummary";
+    summary: string;
+    fromId: string;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    shortSummary?: string;
+    tokensBefore: number;
+    providerPayload?: ProviderPayload;
+    /** Runtime-only ordered archive blocks for snapcompact: old text region,
+     *  imaged middle, then new text region. When present, `summary` is already
+     *  the final lead-in text (no legacy wrapper applied). */
+    blocks?: (TextContent | ImageContent)[];
+    /** Snapcompact image blocks, kept for display counts / legacy consumers. */
+    images?: ImageContent[];
+    timestamp: number;
+}
+export type CoreCompactionMessage = CustomMessage | HookMessage | BranchSummaryMessage | CompactionSummaryMessage;
+declare module "../types" {
+    interface CustomAgentMessages {
+        custom: CustomMessage;
+        hookMessage: HookMessage;
+        branchSummary: BranchSummaryMessage;
+        compactionSummary: CompactionSummaryMessage;
+    }
+}
+export type ConvertToLlm = (messages: AgentMessage[]) => Message[];
+export declare function renderBranchSummaryContext(summary: string): string;
+export declare function renderCompactionSummaryContext(summary: string): string;
+export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, shortSummary?: string, providerPayload?: ProviderPayload, images?: ImageContent[], blocks?: (TextContent | ImageContent)[]): CompactionSummaryMessage;
+export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string, attribution?: MessageAttribution): CustomMessage;
+/**
+ * Transform a single core-domain agent message to its LLM form; `undefined`
+ * drops it from the provider request.
+ *
+ * Single source of truth for the core roles (user/developer/assistant/
+ * toolResult) and the compaction messages owned by this package. Embedders
+ * with their own app messages (e.g. the coding agent) handle their custom
+ * roles and delegate every core role here — duplicating these cases is how
+ * snapcompact frames once silently fell off the provider request.
+ */
+export declare function convertMessageToLlm(message: AgentMessage): Message | undefined;
+/**
+ * Default compaction-domain transformer.
+ *
+ * Embedders with their own app messages should pass a richer transformer through
+ * `SummaryOptions.convertToLlm`; this default intentionally preserves only the
+ * core LLM roles and the compaction messages owned by this package.
+ */
+export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];

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

@@ -0,0 +1,77 @@
+/**
+ * Remote compaction utilities.
+ *
+ * Provider-side conversation summarization endpoints. Three flavors:
+ *
+ * - **OpenAI remote compaction V2** (Responses streaming): appends a
+ *   `compaction_trigger` input item to the normal stream and stores the returned
+ *   `compaction` item with retained real user messages in `preserveData`.
+ * - **OpenAI remote compaction V1** (`/responses/compact`): preserves encrypted
+ *   reasoning across compactions by submitting the full responses-API native
+ *   history and storing the returned `compaction` / `compaction_summary`
+ *   item in `preserveData` so future turns can replay the encrypted state.
+ * - **Generic remote compaction**: a thin POST helper for self-hosted
+ *   summarization endpoints that accept `{ systemPrompt, prompt }` and reply
+ *   with `{ summary, shortSummary? }`.
+ */
+import type { FetchImpl, Message, Model } from "jeopi-ai/types";
+export * from "./compaction-v2-streaming";
+export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
+/**
+ * Hard ceiling on remote compaction HTTP requests. Unlike every provider
+ * stream (guarded by first-event/idle watchdogs in pi-ai), these are raw
+ * fetches awaiting one non-streamed JSON body — a connection silently dropped
+ * by a middlebox would otherwise hang the whole compaction pipeline forever
+ * (frozen "Auto context-full maintenance…" spinner, manual /compact queueing
+ * behind it). On timeout the caller falls back to local summarization.
+ */
+export declare const REMOTE_COMPACTION_TIMEOUT_MS = 180000;
+export type OpenAiRemoteCompactionItem = {
+    type: "compaction" | "compaction_summary";
+    encrypted_content?: string;
+    summary?: string;
+};
+export interface OpenAiRemoteCompactionPreserveData {
+    provider?: string;
+    replacementHistory: Array<Record<string, unknown>>;
+    compactionItem: OpenAiRemoteCompactionItem;
+}
+export interface OpenAiRemoteCompactionRequest {
+    model: string;
+    input: Array<Record<string, unknown>>;
+    instructions: string;
+}
+export interface OpenAiRemoteCompactionResponse extends OpenAiRemoteCompactionPreserveData {
+}
+export interface RemoteCompactionRequest {
+    systemPrompt: string;
+    prompt: string;
+}
+export interface RemoteCompactionResponse {
+    summary: string;
+    shortSummary?: string;
+}
+export declare function shouldUseOpenAiRemoteCompaction(model: Model): boolean;
+export declare function getPreservedOpenAiRemoteCompactionData(preserveData: Record<string, unknown> | undefined): OpenAiRemoteCompactionPreserveData | undefined;
+export declare function withOpenAiRemoteCompactionPreserveData(preserveData: Record<string, unknown> | undefined, remoteCompaction: OpenAiRemoteCompactionPreserveData | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the OpenAI Responses-API native history array from LLM messages.
+ *
+ * Caller is responsible for converting any custom message types to
+ * `Message[]` first (e.g. via the agent's `convertToLlm`); this function
+ * operates purely on the LLM-domain shape.
+ *
+ * @param messages - LLM messages to encode.
+ * @param model - Target model (used for provider gating + tool-call id rules).
+ * @param previousReplacementHistory - History from a prior compaction whose
+ *   encrypted reasoning we want to preserve.
+ */
+export declare function buildOpenAiNativeHistory(messages: Message[], model: Model, previousReplacementHistory?: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: string, compactInput: Array<Record<string, unknown>>, instructions: string, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+}): Promise<OpenAiRemoteCompactionResponse>;
+export declare function requestRemoteCompaction(endpoint: string, request: RemoteCompactionRequest, signal?: AbortSignal, opts?: {
+    fetch?: FetchImpl;
+    timeoutMs?: number;
+}): Promise<RemoteCompactionResponse>;