@linxiraos/pi-agent-core 1.1.26 → 1.2.0

package/CHANGELOG.md

@@ -1,249 +1,8 @@
-# Changelog
-
 ## [Unreleased]
 
-## [1.1.26] - 2026-10-03
-
-- 版本线推进至 1.1.26；本版无独立用户可见变化。
-
-## [14.9.5] - 2026-05-12
-
-### Added
-
-- Added an `isError?: boolean` field on `AgentToolResult` so tools can flag a non-throwing failure (e.g. an aggregator that catches per-entry errors). `coerceToolResult` preserves the flag and the agent loop surfaces it as a tool error on the wire.
-
-## [14.9.3] - 2026-05-10
-
-### Added
-
-- Added `onHarmonyLeak` option on `Agent`/loop config to receive GPT-5 Harmony leak audit callbacks
-- Added harmony-leak detection and audit exports to the package index for programmatic leak detection and recovery hooks
-
-### Changed
-
-- Changed OpenAI Codex model runs to detect GPT-5 Harmony protocol leakage during streaming and automatically retry or recover tool calls instead of sending contaminated arguments downstream
-
-### Security
-
-- Hardened tool-call handling against leaked `to=functions.*` protocol tails by truncating or retrying before execution
-- Hardened failure handling so repeated GPT-5 Harmony leak mitigation is retried only up to two times before escalating to an explicit error
-
-## [14.9.0] - 2026-05-10
-
-### Added
-
-- Added `Agent#metadata` field forwarded to every API request; callers can set arbitrary provider metadata (e.g. `metadata.user_id`) once and have it applied to all subsequent stream calls without modifying per-call options
-- Added `Agent#setMetadataResolver(fn)` for installing a function that resolves request metadata at call time. The `metadata` getter dispatches through the resolver on every read (including the snapshot taken per `prompt()`), so callers reflect mutable external state (e.g. live OAuth account UUID after a token refresh) without manual re-syncs. Plain `agent.metadata = …` continues to set a static value and clears any installed resolver.
-- Added an `onSseEvent` agent option and loop config forwarding path for raw provider SSE diagnostics.
-
-## [14.7.6] - 2026-05-07
-
-### Added
-
-- Added `hideThinkingSummary` option/getter/setter on `Agent` and `AgentLoopConfig`. Forwarded to the underlying stream call so providers can omit reasoning/thinking summaries on demand.
-
-## [14.7.2] - 2026-05-06
-
-### Added
-
-- Added `loadMode` option to `AgentTool` to mark built-in tools as `essential` for initial loading or `discoverable` for search activation
-- Added optional `summary` field to `AgentTool` definitions for one-line text used in tool discovery indexes
-
-## [14.7.0] - 2026-05-04
-
-### Breaking Changes
-
-- Changed `Agent` API types so `systemPrompt` is now a list of prompt strings, requiring callers to pass and update system prompts via string arrays
-
-### Changed
-
-- Removed automatic project-context injection into each model call from loop logic
-
-### Removed
-
-- Removed the `projectPrompt` field from agent state/context and the `setProjectPrompt` mutator
-
-## [14.6.2] - 2026-05-03
-
-### Fixed
-
-- Fixed unhandled promise rejection when `getApiKey` or any other async error occurs during `streamAssistantResponse`: agent loop IIFEs now catch and route errors through `EventStream.fail()`, which terminates the `for await` loop and lets `Agent#runLoop`'s catch block create a proper error assistant message instead of crashing
-
-## [14.6.0] - 2026-05-02
-
-### Fixed
-
-- Fixed request cancellation before provider events by emitting an aborted assistant message and ending the stream with `stopReason: "aborted"`
-
-## [14.5.10] - 2026-04-30
-
-### Added
-
-- Added an `onResponse` stream option for observing provider response metadata after response headers arrive.
-
-## [14.2.0] - 2026-04-23
-
-### Changed
-
-- Changed tool dispatch to match model-returned tool calls by either internal tool name or custom wire name, enabling custom OpenAI tool names such as `apply_patch`.
-
-## [14.0.1] - 2026-04-08
-
-### Added
-
-- Added `onAssistantMessageEvent` callback option to inspect assistant streaming events before they are emitted, enabling abort decisions before buffered events continue flowing
-- Added `setAssistantMessageEventInterceptor()` method to dynamically set or update the assistant message event interceptor
-
-## [13.13.0] - 2026-03-18
-
-### Added
-
-- Added `startup.checkUpdate` setting, set to `true` by default, can be disabled to skip the update check on agent initialization
-
-## [13.12.7] - 2026-03-16
-
-### Added
-
-- Added overload for `prompt()` method accepting a string input with optional options parameter
-
-### Fixed
-
-- Fixed stale forced toolChoice being passed to provider after tools are refreshed mid-turn
-
-## [13.9.16] - 2026-03-10
-
-### Added
-
-- Added `onPayload` option to `AgentOptions` to inspect or replace provider payloads before they are sent
-
-## [13.9.3] - 2026-03-07
-
-### Added
-
-- Exported `ThinkingLevel` selector constants and types for configuring agent reasoning behavior
-- Added `inherit` thinking level option to defer reasoning configuration to higher-level selectors
-- Added `serviceTier` option to configure service tier for agent requests
-
-### Changed
-
-- Changed `thinkingLevel` from required string to optional `Effort` type, allowing undefined state
-- Updated `setThinkingLevel()` method to accept `Effort | undefined` instead of `ThinkingLevel` string
-
-## [13.4.0] - 2026-03-01
-
-### Added
-
-- Added `getToolChoice` option to dynamically override tool choice per LLM call
-
-## [13.3.8] - 2026-02-28
-
-### Changed
-
-- Changed intent field name from `agent__intent` to `_i` in tool schemas
-
-### Fixed
-
-- Fixed synthetic tool result text formatting so aborted/error tool results no longer emit `Tool execution was aborted.: Request was aborted` style punctuation.
-
-## [13.3.7] - 2026-02-27
-
-### Added
-
-- Added `lenientArgValidation` option to tools to allow graceful handling of argument validation errors by passing raw arguments to execute() instead of returning an error to the LLM
-
-## [13.3.1] - 2026-02-26
-
-### Added
-
-- Added `topP`, `topK`, `minP`, `presencePenalty`, and `repetitionPenalty` options to `AgentOptions` for fine-grained sampling control
-- Added getter and setter properties for sampling parameters on the `Agent` class to allow runtime configuration
-
-## [13.1.0] - 2026-02-23
-
-### Changed
-
-- Removed per-tool `agent__intent` field description from injected schema to reduce token usage; intent format is now documented once in the system prompt instead of repeated in every tool definition
-
-## [12.19.0] - 2026-02-22
-
-### Changed
-
-- Updated tool result messages to include error details when tool execution fails
-
-## [12.14.0] - 2026-02-19
-
-### Added
-
-- Added `intentTracing` option to enable intent goal extraction from tool calls, allowing models to specify high-level goals via a required `_intent` field that is automatically injected into tool schemas and stripped from arguments before execution
-
-## [12.11.0] - 2026-02-19
-
-### Added
-
-- Exported `AgentBusyError` exception class for handling concurrent agent operations
-
-### Changed
-
-- Agent now throws `AgentBusyError` instead of generic `Error` when attempting concurrent operations
+## [1.2.0] - 2026-10-12
 
-## [12.8.0] - 2026-02-16
-
-### Added
-
-- Added `transformToolCallArguments` option to `AgentOptions` and `AgentLoopConfig` for transforming tool call arguments before execution (e.g. secret deobfuscation)
-
-## [12.2.0] - 2026-02-13
-
-### Added
-
-- Added `providerSessionState` option to share provider state map for session-scoped transport and session caches
-- Added `preferWebsockets` option to hint that websocket transport should be preferred when supported by the provider implementation
-
-## [11.10.0] - 2026-02-10
-
-### Added
-
-- Added `temperature` option to `AgentOptions` to control LLM sampling temperature
-- Added `temperature` getter and setter to `Agent` class for runtime configuration
-
-## [11.6.0] - 2026-02-07
-
-### Added
-
-- Added `hasQueuedMessages()` method to check for pending steering/follow-up messages
-- Resume queued steering and follow-up messages from `continue()` after auto-compaction
-
-### Changed
-
-- Extracted `dequeueSteeringMessages()` and `dequeueFollowUpMessages()` from inline config callbacks
-- Added `skipInitialSteeringPoll` option to `_runLoop()` for correct queue resume ordering
-
-## [11.3.0] - 2026-02-06
-
-### Added
-
-- Added `maxRetryDelayMs` option to AgentOptions to cap server-requested retry delays, allowing higher-level retry logic to handle long waits with user visibility
-
-### Changed
-
-- Updated ThinkingLevel documentation to include support for gpt-5.3 and gpt-5.3-codex models with 'xhigh' thinking level
-
-## [11.2.0] - 2026-02-05
-
-### Fixed
-
-- Fixed handling of aborted requests to properly throw abort errors when stream terminates without a terminal event
-
-## [10.5.0] - 2026-02-04
-
-### Added
-
-- Added `concurrency` option to `AgentTool` to control tool scheduling: "shared" (default, runs in parallel) or "exclusive" (runs alone)
-- Implemented parallel execution of shared tools within a single agent turn for improved performance
-
-### Changed
-
-- Refactored tool execution to support concurrent scheduling with proper interrupt handling and steering message checks
+- 版本线推进至 1.2.0；本版无独立用户可见变化。
 
 ## [9.2.2] - 2026-01-31
 
@@ -375,6 +134,10 @@
 
 Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
 
+## [1.1.27] - 2026-10-07
+
+- 版本线推进至 1.1.27；本版无独立用户可见变化。
+
 ## [1.1.25] - 2026-10-03
 
 - 版本线推进至 1.1.25；本版无独立用户可见变化。

package/README.md

@@ -466,7 +466,7 @@ const runCoverage = aggregateAgentRunCoverage(coverages);
 
 ### Tool status reporting
 
-`execute_tool` spans carry `omp.gen_ai.tool.status` ∈
+`execute_tool` spans carry `zeta.gen_ai.tool.status` ∈
 `"ok" | "error" | "skipped" | "blocked" | "timeout" | "aborted"`.
 `beforeToolCall` blocks throw a distinguishable `ToolCallBlockedError`
 internally; the catch path reports `status: "blocked"` instead of conflating

package/dist/types/agent.d.ts

@@ -270,6 +270,11 @@ export declare class Agent {
      * are queued for the next boundary.
      */
     hasBackgroundCompletions?: AgentLoopConfig["hasBackgroundCompletions"];
+    /**
+     * Hook that peeks whether a passive aside is queued for the next boundary;
+     * ends an interruptible wait without interrupting other tools.
+     */
+    hasQueuedAsides?: AgentLoopConfig["hasQueuedAsides"];
     constructor(opts?: AgentOptions);
     /**
      * Get the current session ID used for provider caching.
@@ -390,8 +395,8 @@ export declare class Agent {
     get state(): AgentState;
     /**
      * Tokenizer for the active model. The instance is replaced whenever the
-     * active model's encoding changes (see {@link setModel}), so callers must
-     * not cache it across model switches.
+     * active model's encoding or snapcompact frame pricing changes (see
+     * {@link setModel}), so callers must not cache it across model switches.
      */
     get tokenizer(): Tokenizer;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
@@ -412,7 +417,8 @@ export declare class Agent {
     buildSideRequestContext(llmMessages: Message[], systemPrompt?: string[]): Promise<Context>;
     subscribe(fn: (e: AgentEvent) => void): () => void;
     /** Register a listener notified after any steering/follow-up queue mutator
-     *  (enqueue, dequeue-on-delivery, clear, restore) runs. Internal-only signal —
+     *  (enqueue, dequeue-on-delivery, clear, restore, live-steering adoption,
+     *  withdrawal, and landing in the transcript) runs. Internal-only signal —
      *  the queue itself has no concept of display filtering — so listeners
      *  recompute their own snapshot from `peekSteeringQueue()`/`peekFollowUpQueue()`
      *  (or a higher-level view) on notification. */
@@ -422,10 +428,15 @@ export declare class Agent {
     /** Register an independently removable hook that runs immediately before each model call. */
     addBeforeModelCallHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
     /**
-     * Take back live-steered messages ahead of an abort (Esc restores them to the editor):
-     * the aborted run then neither records nor requeues them.
+     * Take back dequeued input the transcript has not recorded yet, ahead of an abort (Esc restores
+     * it to the editor): steering live steering took for the in-flight response, then each batch
+     * dequeued for the next model call, oldest first. The aborted run then neither records it (or
+     * the context prepared for it) nor requeues it.
      */
-    withdrawLiveSteering(): AgentMessage[];
+    withdrawUndeliveredQueuedMessages(): {
+        steering: AgentMessage[];
+        followUp: AgentMessage[];
+    };
     /** Steering live steering took for the streaming response; the transcript records it once
      *  that response (or its tool batch) ends, which is when the model switches to it. */
     peekLiveSteeredMessages(): AgentMessage[];
@@ -434,6 +445,8 @@ export declare class Agent {
     setAssistantMessageEventInterceptor(fn: ((message: AssistantMessage, event: AssistantMessageEvent) => void) | undefined): void;
     setOnBeforeYield(fn: (() => Promise<void> | void) | undefined): void;
     setOnTurnEnd(fn: ((messages: AgentMessage[], signal?: AbortSignal, context?: AgentTurnEndContext) => Promise<void> | void) | undefined): void;
+    /** Called with the exact system prompt each model call is built from, after before-model-call hooks. */
+    setOnModelCallSystemPrompt(fn: ((systemPrompt: string[]) => void) | undefined): void;
     /**
      * Install or replace the host pre-model-call gate; pass `undefined` to
      * remove it. Gates are sampled when a run starts: installing the first
@@ -450,12 +463,19 @@ export declare class Agent {
     /**
      * Provide a source of non-interrupting "aside" messages (e.g. background-job
      * completions, late LSP diagnostics) drained at each step boundary. Never
-     * aborts in-flight tools. See `AgentLoopConfig.getAsideMessages`.
+     * aborts foreground tools; an interruptible `wait` may end early through the
+     * peek hooks. See `AgentLoopConfig.getAsideMessages`.
      */
     setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
     setSystemPrompt(v: string[] | string): void;
     setModel(model: Model): void;
+    /**
+     * Route every model this agent adopts through `resolver` (e.g. to fit a
+     * shared catalog row to this agent's own settings), starting with the
+     * current one; `undefined` adopts models as given from now on.
+     */
+    setModelResolver(resolver: ((model: Model) => Model) | undefined): void;
     setThinkingLevel(l: Effort | undefined): void;
     setDisableReasoning(disabled: boolean): void;
     setSteeringMode(mode: "all" | "one-at-a-time"): void;

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

@@ -1,11 +1,12 @@
 /**
  * Anthropic on-demand compaction (`compact-2026-09-04` beta).
  *
- * The request sends only the prefix to summarize, with the live conversation's
- * system prompt, tools and thinking settings. The returned signed block
- * replaces that prefix; the retained tail is replayed from session entries.
+ * The request sends only the prefix to summarize, as the live conversation
+ * sent it: same system prompt, tools, history bytes and thinking settings.
+ * The returned signed block replaces that prefix; the retained tail is
+ * replayed from session entries.
  */
-import type { AnthropicCompactionPayload, ApiKey, Effort, Message, Model, SimpleStreamOptions, Tool, Usage } from "@linxiraos/pi-ai";
+import type { AnthropicCompactionFiles, AnthropicCompactionPayload, ApiKey, Context, Effort, Model, SimpleStreamOptions, Usage } from "@linxiraos/pi-ai";
 import { type InstrumentedChatSpanOptions } from "../telemetry.js";
 import type { AgentMessage } from "../types.js";
 export declare const ANTHROPIC_COMPACTION_PRESERVE_KEY = "anthropicCompaction";
@@ -17,8 +18,12 @@ export interface AnthropicCompactionPreserveData {
     signature?: string;
     /** Legacy threshold block state; replay-only. */
     encryptedContent?: string;
-    /** Harness file metadata (`<files>` section) replayed after the native block. */
+    /** Harness file metadata (`<files>` section) replayed after the retained tail. */
     filesText?: string;
+    /** Earlier summaries' file metadata replayed inside the retained tail. */
+    retainedFiles?: AnthropicCompactionFiles[];
+    /** The retained tail replays unchanged (see `AnthropicCompactionPayload.exactTail`). */
+    exactTail?: true;
     /** Model that wrote the summary. */
     model?: string;
     /** Prompt tokens the compaction request processed, for display. */
@@ -51,10 +56,11 @@ export declare function findAnthropicCompactionCut(messages: readonly (AgentMess
 /** Instructions replace the API default; the request contains only summarized messages. */
 export declare function buildAnthropicCompactionInstructions(basePrompt: string, customInstructions: string | undefined, extraContext: string | undefined): string;
 export interface AnthropicNativeCompactionRequest {
-    systemPrompt: string[];
-    messages: Message[];
-    tools?: Tool[];
+    /** The summarized prefix as the live turn would send it. */
+    context: Context;
     instructions: string;
+    /** Replayed file metadata due before this time ends the request (see `AnthropicCompactionRequest.filesDueBefore`). */
+    filesDueBefore?: number;
     maxTokens: number;
     reasoning?: Effort;
 }

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

@@ -55,7 +55,7 @@ export interface GenerateBranchSummaryOptions {
     convertToLlm?: ConvertToLlm;
     /**
      * Optional telemetry handle. When provided, the branch summary LLM call is
-     * wrapped in an OTEL chat span tagged with `omp.gen_ai.oneshot.kind = "branch_summary"`.
+     * wrapped in an OTEL chat span tagged with `zeta.gen_ai.oneshot.kind = "branch_summary"`.
      */
     telemetry?: AgentTelemetry;
     /**

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

@@ -26,6 +26,8 @@ export interface CompactionV2Usage {
 export interface CompactionV2Request {
     body: OpenAICodexCompactionBody;
     input: unknown[];
+    /** Serialized user-written turns to keep next to the compaction item; defaults to `input`. */
+    retainedUserItems: unknown[];
     retainedMessageBudget: number;
     sessionId?: string;
     promptCacheKey?: string;
@@ -56,12 +58,14 @@ export declare function buildCompactionV2Request(model: Model, input: unknown[],
     sessionId?: string;
     promptCacheKey?: string;
     retainedMessageBudget?: number;
+    retainedUserItems?: unknown[];
 }): CompactionV2Request;
 /** Wrap a body built by the normal Codex serializer for V2 compaction transport. */
 export declare function buildCompactionV2RequestFromBody(model: Model, body: OpenAICodexCompactionBody, options?: {
     sessionId?: string;
     promptCacheKey?: string;
     retainedMessageBudget?: number;
+    retainedUserItems?: unknown[];
 }): CompactionV2Request;
 /** Request V2 compaction over the normal OpenAI Responses streaming endpoint. */
 export declare function requestCompactionV2Streaming(model: Model, apiKey: string, request: CompactionV2Request, signal?: AbortSignal, options?: {
@@ -72,7 +76,7 @@ export declare function requestCompactionV2Streaming(model: Model, apiKey: strin
     codexCompaction?: CodexCompactionContext;
     preferWebsockets?: boolean;
 }): Promise<CompactionV2Response>;
-/** Build Codex-style V2 replacement history from prompt input plus compaction output. */
+/** Build Codex-style V2 replacement history from retention candidates plus compaction output. */
 export declare function buildCompactionV2ReplacementHistory(input: unknown[], compactionItem: Record<string, unknown>, retainedMessageBudget?: number): {
     replacementHistory: Array<Record<string, unknown>>;
     retainedImageCount: number;

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

@@ -34,6 +34,14 @@ export interface CompactionSettings {
     strategy?: "context-full" | "handoff" | "shake" | "snapcompact" | "off";
     thresholdPercent?: number;
     thresholdTokens?: number;
+    /**
+     * Stands in for the context window when the percentage or reserve-based
+     * threshold is computed (when `> 0` and smaller than the window); a positive
+     * `thresholdTokens` still wins and is checked against the real window (at
+     * or past it, the window less its reserve applies). Set by per-model
+     * compaction limits; request and overflow budgets keep the real window.
+     */
+    baseWindowTokens?: number;
     midTurnEnabled?: boolean;
     /**
      * Tokens reserved below the context window for the next prompt + response.
@@ -177,10 +185,24 @@ export interface SummaryOptions {
     initiatorOverride?: MessageAttribution;
     metadata?: Record<string, unknown>;
     convertToLlm?: ConvertToLlm;
+    /**
+     * The provider context a live turn sends for `summarized` + `retained`, cut to
+     * `summarized`. Anthropic on-demand compaction sends it so retained signed
+     * thinking keeps its prefix; without it the request uses `remoteSystemPrompt`,
+     * `tools` and `convertToLlm`.
+     */
+    buildProviderContext?: (summarized: AgentMessage[], retained: AgentMessage[], signal?: AbortSignal) => Promise<Context>;
+    /**
+     * Whether a message is a turn the user wrote. Remote Compaction V2 keeps these
+     * next to the compaction item. Defaults to `role === "user"`; hosts whose
+     * user-initiated turns also arrive as custom messages (e.g. skill invocations)
+     * widen it.
+     */
+    isUserAuthored?: (message: AgentMessage) => boolean;
     /**
      * Optional telemetry handle. When provided, every LLM call emitted during
      * compaction is wrapped in an OTEL chat span tagged with
-     * `omp.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
+     * `zeta.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
      * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
      */
     telemetry?: AgentTelemetry;
@@ -243,7 +265,7 @@ export interface HandoffOptions {
     metadata?: Record<string, unknown>;
     /**
      * Optional telemetry handle. When provided, the handoff LLM call is
-     * wrapped in an OTEL chat span tagged with `omp.gen_ai.oneshot.kind = "handoff"`.
+     * wrapped in an OTEL chat span tagged with `zeta.gen_ai.oneshot.kind = "handoff"`.
      */
     telemetry?: AgentTelemetry;
     /**

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

@@ -88,8 +88,8 @@ export interface TtsrInjectionEntry extends SessionEntryBase {
 }
 export interface SessionInitEntry extends SessionEntryBase {
     type: "session_init";
-    /** Full system prompt sent to the model */
-    systemPrompt: string;
+    /** System prompt blocks exactly as sent to the model; files written before blocks were kept store one joined string. */
+    systemPrompt: string[] | string;
     /** Initial task/user message */
     task: string;
     /** Tools available to the agent */

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

@@ -1,5 +1,6 @@
 import type { ImageContent, Message, MessageAttribution, ProviderPayload, TextContent } from "@linxiraos/pi-ai";
 import type { AgentMessage } from "../types.js";
+import type { SessionEntry } from "./entries.js";
 export interface CustomMessage<T = unknown> {
     role: "custom";
     customType: string;
@@ -110,3 +111,8 @@ export declare function convertMessageToLlm(message: AgentMessage): Message | un
  * core LLM roles and the compaction messages owned by this package.
  */
 export declare function defaultConvertToLlm(messages: AgentMessage[]): Message[];
+/**
+ * The context message a session entry contributes, or `undefined` for entries
+ * that don't reach the LLM (compaction markers, labels, model changes, ...).
+ */
+export declare function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined;

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

@@ -28,19 +28,31 @@ export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompac
  */
 export declare const REMOTE_COMPACTION_TIMEOUT_MS = 300000;
 export declare const CONTEXT_WINDOW_TRUNCATED_OUTPUT_MESSAGE: string;
+/**
+ * Tokens of stored Responses replacement history. Retained `input_image` parts
+ * count at their image estimate rather than as base64 text; everything else,
+ * opaque compaction state included, counts as serialized.
+ */
+export declare function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number;
 export interface TrimRemoteCompactionInputResult {
     input: Array<Record<string, unknown>>;
     rewrittenOutputs: number;
     estimatedTokensBefore: number;
     estimatedTokensAfter: number;
-    /** Whether `input` fits the model window; false means it must not be sent. */
+    /**
+     * Whether `input` may be sent; false means it must not be. True when the
+     * full estimate fits, or when only the image estimate pushes it over (image
+     * pricing is a guess; the provider's own accounting decides).
+     */
     fits: boolean;
 }
 /**
  * Preserve the full native transcript unless trailing tool outputs alone push a
  * remote compaction request beyond the model window. Replacing only those
  * outputs keeps call/result pairing and all earlier assistant/reasoning history,
- * matching Codex's recovery path for oversized tool turns.
+ * matching Codex's recovery path for oversized tool turns. A request whose text
+ * fits but whose image estimate does not is still sendable: refusing it on an
+ * image guess would skip native compaction the provider would have accepted.
  */
 export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, tokenizer: Tokenizer, contextWindow: number | null | undefined, instructions: string, tools?: unknown[]): TrimRemoteCompactionInputResult;
 /**