@linxiraos/pi-agent-core 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,8 +1,42 @@
 ## [Unreleased]
 
-## [1.2.0] - 2026-10-12
+## [1.3.0] - 2026-10-18
 
-- 版本线推进至 1.2.0；本版无独立用户可见变化。
+### Breaking Changes
+
+- Removed `estimateImageContentTokens()` from `@linxiraos/pi-agent-core/image-tokens`; use `Tokenizer.imageTokens(size, detail)`, which prices with the reading model's catalog image rule ([#15446](https://github.com/can1357/oh-my-pi/pull/15446) by [@will-bogusz](https://github.com/will-bogusz))
+- `applyShakeRegion()` and `applyShakeRegions()` take the replacement's token count (`replacementTokens`); a block rewrite of an assistant turn adds the tokens it removes to `elidedOutputTokens`, so a replayed Claude turn's count stays lowered after a reload ([#15446](https://github.com/can1357/oh-my-pi/pull/15446) by [@will-bogusz](https://github.com/will-bogusz))
+- Removed `ApprovalDetailsOptions`; `formatApprovalDetails` takes only `args` again, since the compact approval prompt no longer shows tool details ([#15642](https://github.com/can1357/oh-my-pi/pull/15642) by [@H4vC](https://github.com/H4vC))
+
+### Added
+
+- Added `AgentLoopConfig.onDetachedToolUpdate`: a tool's `onUpdate` frames that arrive after its run's event stream ended (a returned call whose background job keeps reporting) reach it instead of being dropped; `Agent` forwards them to its subscribers as `tool_execution_update` events
+- `AgentTool.formatApprovalDetails` receives `ApprovalDetailsOptions`; `compact: true` asks for untruncated bodies so a compact approval prompt can count their lines ([#15550](https://github.com/can1357/oh-my-pi/pull/15550) by [@H4vC](https://github.com/H4vC))
+- `Tokenizer.countLatestTurn`: counts a message as the transcript's latest assistant turn, which an Anthropic Messages replay keeps byte-for-byte ([#15791](https://github.com/can1357/oh-my-pi/pull/15791) by [@will-bogusz](https://github.com/will-bogusz))
+- `Agent.prioritizeSteering`: moves given pending steering messages ahead of older ones so one-at-a-time delivery takes them first ([#15642](https://github.com/can1357/oh-my-pi/pull/15642))
+- `AgentTool.delegationGuidance`: instructions a same-name extension replacement inherits in its description when it delegates to the native tool ([#15477](https://github.com/can1357/oh-my-pi/pull/15477) by [@iliaal](https://github.com/iliaal))
+- `CompactionPreparation.lastSummarizedEntryId` and `CompactionResult.providerReplayThroughEntryId`: a remote compaction that could only fit the history before the kept tail reports the last entry its native history covers; later entries replay normally ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+- `agent_start` carries `resumedToolCallIds` when a continued run first executes the calls of an unpaired assistant tail
+- `prepareQueuedMessages` receives which queue (`steering` or `followUp`) a batch came from ([#16026](https://github.com/can1357/oh-my-pi/pull/16026))
+
+### Changed
+
+- Before-model-call hooks now receive the loop context as a second argument, and `buildProviderContext` receives the summarizer model ([#15436](https://github.com/can1357/oh-my-pi/pull/15436) by [@will-bogusz](https://github.com/will-bogusz))
+
+### Fixed
+
+- Fixed Claude context counts reading Opus 5.5 requests about 55% over their billed input: a replayed thinking turn now counts at the output size Claude billed for it, not its signature's bytes ([#15446](https://github.com/can1357/oh-my-pi/pull/15446) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed screenshots and other non-frame images being counted at the OpenAI rate for every model instead of the reading model's own; Claude billed them about 16% higher ([#15446](https://github.com/can1357/oh-my-pi/pull/15446) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed OpenAI Responses and Codex context estimates leaving out replayed reasoning: each turn whose encrypted reasoning actually replays now counts its reported reasoning tokens (its ciphertext when the backend reports none), and none while a cold session rebuilds it out of the request, so compaction and snapcompact sizing match billing; branch summaries no longer budget for encrypted reasoning they never send ([#15447](https://github.com/can1357/oh-my-pi/pull/15447) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed a Claude compaction or branch summarizer receiving assistant reasoning from a snapcompact archive rendered under another model, which Claude refuses (`reasoning_extraction`) ([#15436](https://github.com/can1357/oh-my-pi/pull/15436) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed a Cursor tool call re-sent by the server persisting two results under one id; the re-run's result replaces the first ([#15749](https://github.com/can1357/oh-my-pi/issues/15749))
+- Fixed compaction keeping more recent history than `keepRecentTokens` when the latest Claude turn on the Anthropic Messages API ended its tool calls on `stop` or `length`: the replay keeps that turn's signed reasoning, but the cut point counted only its visible blocks ([#15791](https://github.com/can1357/oh-my-pi/pull/15791) by [@will-bogusz](https://github.com/will-bogusz))
+- Fixed native (OpenAI/Codex) remote compaction refusing or truncating sessions that fit the window: its preflight counted the JSON-escaped request, inflating quote-, backslash- and newline-heavy tool output such as disassembly by ~10–20%; it now counts text as the model reads it ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+- Fixed OpenAI V1/V2 remote compaction failing outright when the history, kept tail included, exceeds the context window (a large final response or tool output after the last check); it retries on the history before the kept tail ([#15712](https://github.com/can1357/oh-my-pi/pull/15712) by [@H4vC](https://github.com/H4vC))
+- Fixed fitted output caps overflowing the context window on strict hosts (llama.cpp-family) after turns with many parallel tool results; chat-template framing is now charged per locally counted message ([#15699](https://github.com/can1357/oh-my-pi/issues/15699))
+- Fixed leaked DeepSeek DSML markup reaching saved history from reasoning blocks and from turns that also made a valid tool call ([#15485](https://github.com/can1357/oh-my-pi/issues/15485))
+- Cancelling an `ask` after a background job finishes now reports the user cancellation instead of telling the model to retry a skipped tool ([#15985](https://github.com/can1357/oh-my-pi/issues/15985))
+- Fixed Cursor turns failing with `PROVIDER_ERROR` when a follow-up (a finished background job, a late diagnostic, a reminder) arrived while the previous turn was still streaming ([#15821](https://github.com/can1357/oh-my-pi/pull/15821) by [@robfeldmann](https://github.com/robfeldmann))
 
 ## [9.2.2] - 2026-01-31
 
@@ -134,6 +168,10 @@
 
 Initial release under @oh-my-pi scope. See previous releases at [badlogic/pi-mono](https://github.com/badlogic/pi-mono).
 
+## [1.2.0] - 2026-10-12
+
+- 版本线推进至 1.2.0；本版无独立用户可见变化。
+
 ## [1.1.27] - 2026-10-07
 
 - 版本线推进至 1.1.27；本版无独立用户可见变化。

package/THIRD-PARTY-NOTICES.txt

@@ -8,8 +8,8 @@ no rights in third-party code, fonts, data, or marks identified below.
 PYTHON DEPENDENCY DISTRIBUTION ROLE
 ===================================
 
-omp-rpc has no third-party runtime dependencies. robomp declares FastAPI,
-Uvicorn, HTTPX, Pydantic, pydantic-settings, python-dotenv, Click, and omp-rpc
+zeta-rpc has no third-party runtime dependencies. robomp declares FastAPI,
+Uvicorn, HTTPX, Pydantic, pydantic-settings, python-dotenv, Click, and zeta-rpc
 as ordinary installer-resolved dependencies. The Python wheels do not vendor
 those projects; each dependency remains a separately installed distribution
 carrying its own license metadata and files. Container/system assemblers must
@@ -79,9 +79,9 @@ uutils coreutils (https://github.com/uutils/coreutils), MIT
 --------------------------------------------------------------------------------
 Covers: base32, base64, basename, cat, cksum (shared checksum machinery),
 b2sum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, comm, cp,
-cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nproc, paste,
-printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee, touch, tr,
-truncate, uname, uniq, wc, whoami, yes.
+cut, date, dirname, head, hostname, ln, ls, mkdir, mktemp, mv, nl, nproc,
+paste, printenv, readlink, realpath, rm, seq, sort, stat, tac, tail, tee,
+touch, tr, truncate, uname, uniq, wc, whoami, yes.
 
   Copyright (c) uutils developers
 
@@ -824,6 +824,56 @@ public licenses.
 
 Creative Commons may be contacted at creativecommons.org.
 
+-------------------------------------------------------------------------------
+scripts/brand/fonts/ANSI Shadow.flf, scripts/brand/fonts/mini.flf
+
+Two FIGlet font files from the standard FIGlet font distribution — the
+figlet.org font set shipped by figlet.js
+(https://github.com/patorjk/figlet.js/tree/master/fonts), fetched from
+figlet.js 1.8.0 — vendored so the welcome/splash brand art
+(`packages/tui/src/prompt/welcome.ts`) is generated reproducibly and offline
+by `bun scripts/brand/generate-logo-art.ts`. Both files are unmodified and
+retain their original FIGlet headers. They are build-time inputs only: no font
+file or font data is compiled into, or shipped with, a Zeta release artifact.
+The fonts' own headers carry their terms:
+
+- `ANSI Shadow.flf` — "ANSI Shadow". Author unknown ("Font Author: ?" in the
+  header); a TheDraw-archive font converted with the FIGlet font editor
+  (http://patorjk.com/figfont-editor). Distributed under the FIGlet font
+  license as carried by the standard FIGlet font set: free to use and
+  redistribute with the header intact.
+- `mini.flf` — "mini" by Glenn Chappell (4/93), from figlet release 2.1
+  (12 Aug 1994), "Includes ISO Latin-1"; modified by Paul Burton
+  <solution@earthlink.net> 12/96. Header grant: "Permission is hereby given to
+  modify this font, as long as the modifier's name is placed on a comment
+  line."
+
+FIGlet renderer — `figlet` 1.8.0 (https://github.com/patorjk/figlet.js), a
+root devDependency used only to generate the art at build time; it is not
+imported by any runtime bundle or shipped artifact.
+
+  MIT License
+
+  Copyright (C) 2014-present Patrick Gillespie and other contributors
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+
 BUN / NPM DEPENDENCY INVENTORY
 ==============================
 This inventory is traversed from bun.lock, not from the host node_modules tree.

package/dist/types/agent.d.ts

@@ -3,7 +3,7 @@ import type { Dialect } from "@linxiraos/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@linxiraos/pi-ai/utils/harmony-leak";
 import type { AppendOnlyContextManager } from "./append-only-context.js";
 import { Tokenizer } from "./tokenizer.js";
-import type { AgentBeforeModelCall, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, PrepareQueuedMessages, SpeculativeToolExecutionConfig, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
+import type { AgentBeforeModelCall, AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, AgentTurnEndContext, AsideMessage, PrepareQueuedMessages, SpeculativeToolExecutionConfig, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
 }
@@ -395,8 +395,10 @@ export declare class Agent {
     get state(): AgentState;
     /**
      * Tokenizer for the active model. The instance is replaced whenever the
-     * active model's encoding or snapcompact frame pricing changes (see
-     * {@link setModel}), so callers must not cache it across model switches.
+     * active model's encoding, image or thinking-replay pricing, or
+     * replayed-reasoning reader changes (see {@link setModel}), or its Responses
+     * session turns cold or warm, so callers must not cache it across model
+     * switches or requests.
      */
     get tokenizer(): Tokenizer;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
@@ -425,8 +427,9 @@ export declare class Agent {
     onQueueChange(listener: () => void): () => void;
     /** Register an independently removable hook that runs before queued messages are consumed. */
     addBeforeQueuedMessageDequeueHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
-    /** Register an independently removable hook that runs immediately before each model call. */
-    addBeforeModelCallHook(hook: (signal?: AbortSignal) => Promise<void> | void): () => void;
+    /** Register an independently removable hook that runs immediately before each model call, with the
+     *  loop's live context (mutating `context.messages` changes what this and later calls send). */
+    addBeforeModelCallHook(hook: (signal: AbortSignal | undefined, context: AgentContext) => Promise<void> | void): () => void;
     /**
      * 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
@@ -511,6 +514,13 @@ export declare class Agent {
      * Delivered after current tool execution, skips remaining tools.
      */
     steer(m: AgentMessage): void;
+    /**
+     * Move the given pending steering messages (by identity) ahead of the rest,
+     * keeping both groups' relative order, so one-at-a-time delivery takes them
+     * first. Messages no longer pending, including a claimed batch already
+     * being delivered, are ignored.
+     */
+    prioritizeSteering(messages: readonly 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.

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

@@ -28,6 +28,12 @@ export interface CompactionResult<T = unknown> {
     details?: T;
     /** Hook-provided data to persist alongside compaction entry. */
     preserveData?: Record<string, unknown>;
+    /**
+     * Last entry the provider-native replay history covers. Set when a remote
+     * compaction could only fit the history before the kept tail; later entries
+     * replay normally after the native history.
+     */
+    providerReplayThroughEntryId?: string;
 }
 export interface CompactionSettings {
     enabled: boolean;
@@ -131,6 +137,14 @@ export declare function shouldCompact(contextTokens: number, contextWindow: numb
  * takes the floor.)
  */
 export declare function compactionContextTokens(providerContextTokens: number, storedConversationEstimate: number): number;
+/**
+ * The prompt budget below `contextWindow`: the window less
+ * {@link resolveBudgetReserveTokens}, capped at `contextWindow - 1` so it never
+ * reaches the whole window even when the reserve resolves to 0. Independent of
+ * any configured trigger; the default {@link resolveThresholdTokens} and
+ * length-stop recovery's "did the window run out" check both use it.
+ */
+export declare function promptBudgetTokens(contextWindow: number, settings: CompactionSettings): number;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings): number;
 /**
  * True for entries that begin a conversational turn (a user request, a
@@ -187,11 +201,11 @@ export interface SummaryOptions {
     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`.
+     * `summarized`, as read by the summarizer `model`. 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>;
+    buildProviderContext?: (summarized: AgentMessage[], retained: AgentMessage[], signal: AbortSignal | undefined, model: Model) => 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
@@ -321,6 +335,8 @@ export interface CompactionPreparation {
     recentMessages: AgentMessage[];
     /** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
     recentEntryIds?: string[];
+    /** Last entry before the kept tail; a remote compaction that cannot fit the tail covers history through it. */
+    lastSummarizedEntryId?: string;
     /** Whether this is a split turn (cut point in middle of turn) */
     isSplitTurn: boolean;
     tokensBefore: number;

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

@@ -31,7 +31,7 @@ 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.
+ * opaque compaction state included, counts as decoded text.
  */
 export declare function countResponsesHistoryTokens(items: unknown[], tokenizer: Tokenizer): number;
 export interface TrimRemoteCompactionInputResult {
@@ -46,6 +46,15 @@ export interface TrimRemoteCompactionInputResult {
      */
     fits: boolean;
 }
+/** Options for {@link trimRemoteCompactionInputToContextWindow}. */
+export interface TrimRemoteCompactionOptions {
+    /**
+     * Whether oversized trailing tool outputs may be rewritten (default true).
+     * False when a caller can compact a shorter prefix instead, so a kept tool
+     * result replays intact rather than being replaced.
+     */
+    rewriteOutputs?: boolean;
+}
 /**
  * Preserve the full native transcript unless trailing tool outputs alone push a
  * remote compaction request beyond the model window. Replacing only those
@@ -54,7 +63,7 @@ export interface TrimRemoteCompactionInputResult {
  * 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;
+export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, tokenizer: Tokenizer, contextWindow: number | null | undefined, instructions: string, tools?: unknown[], options?: TrimRemoteCompactionOptions): TrimRemoteCompactionInputResult;
 /**
  * Refuse a native compaction request whose prepared input cannot fit the model
  * window, before any network I/O. Re-expanded history behind an unreadable
@@ -117,6 +126,8 @@ export declare function requestOpenAiRemoteCompaction(model: Model, apiKey: stri
     sessionId?: string;
     providerSessionState?: Map<string, ProviderSessionState>;
     codexCompaction?: CodexCompactionContext;
+    /** Forwarded to {@link trimRemoteCompactionInputToContextWindow}. */
+    rewriteOutputs?: boolean;
 }): Promise<OpenAiRemoteCompactionResponse>;
 /**
  * Generic remote-compaction POST. Two wire shapes are auto-selected by

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

@@ -87,12 +87,13 @@ export declare function collectShakeRegions(entries: SessionEntry[], tokenizer:
  *
  * Tool-result: replaces its first non-empty text block with the placeholder,
  * removes its other text blocks, preserves every non-text block, and stamps
- * `prunedAt`. Block: splices `replacement` over `[start, end)` of the
- * target text block. When several block regions share one text block they MUST
- * be applied highest-start-first so earlier offsets stay valid — use
- * {@link applyShakeRegions}, which orders them correctly.
+ * `prunedAt`. Block: splices `replacement` (`replacementTokens` long) over
+ * `[start, end)` of the target text block, and on an assistant turn adds the
+ * tokens removed to `elidedOutputTokens`. When several block regions share one
+ * text block they MUST be applied highest-start-first so earlier offsets stay
+ * valid — use {@link applyShakeRegions}, which orders them correctly.
  */
-export declare function applyShakeRegion(region: ShakeRegion, replacement: string): void;
+export declare function applyShakeRegion(region: ShakeRegion, replacement: string, replacementTokens: number): void;
 /**
  * Apply many regions at once. Block regions are applied highest-start-first so
  * that splicing one region never shifts the offsets of another in the same text
@@ -101,4 +102,5 @@ export declare function applyShakeRegion(region: ShakeRegion, replacement: strin
 export declare function applyShakeRegions(items: Array<{
     region: ShakeRegion;
     replacement: string;
+    replacementTokens: number;
 }>): void;

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

@@ -58,11 +58,16 @@ export declare function truncateToolResultForSummary(text: string): string;
 export declare function escapeSummaryBoundaryTags(text: string): string;
 /**
  * Serialize LLM messages as plain summary input without provider control tokens.
+ * `dropThinking` is the summarizer's resolved `classifier-cot-extraction` policy.
  */
-export declare function serializeConversationForSummary(messages: Message[], dialect?: Dialect): string;
+export declare function serializeConversationForSummary(messages: Message[], dialect?: Dialect, dropThinking?: boolean): string;
 /**
  * Serialize LLM messages to transcript text.
  * Call convertToLlm() first to handle custom message types.
+ * `dropThinking` omits assistant reasoning from dialect transcripts: set it from
+ * the reader's resolved `classifier-cot-extraction` catalog policy (Claude's
+ * classifier refuses inputs that reproduce the model's own reasoning as text,
+ * "reasoning_extraction"). Reasoning is ephemeral and low-signal for a summary.
  */
-export declare function serializeConversation(messages: Message[], dialect?: Dialect): string;
+export declare function serializeConversation(messages: Message[], dialect?: Dialect, dropThinking?: boolean): string;
 export declare const SUMMARIZATION_SYSTEM_PROMPT: string;

package/dist/types/image-tokens.d.ts

@@ -1,29 +1,26 @@
 import type { ImageContent } from "@linxiraos/pi-ai";
-import { type ImageSize } from "@linxiraos/pi-catalog/compat/image-tokenization";
+import { type ImageSize, type ImageTokenization } from "@linxiraos/pi-catalog/compat/image-tokenization";
 /**
  * Dimension-based image token estimates shared by the local context counter
  * ({@link Tokenizer.countMessage}) and the native remote-compaction fit probe.
  * Both sides must price the same image the same way: when they disagreed
  * (1.2k flat locally vs a 12k flat worst case remotely) an image-heavy session
  * stayed under the local compaction trigger yet was refused as over-window by
- * the remote probe.
- *
- * Follows the catalog's image rule for the OpenAI Responses wire (GPT-5.5's
- * 32px patches, a per-detail pixel limit and patch budget, x1.2 multiplier),
- * which is also a close upper estimate for other providers once omp has
- * downscaled the image (≤1568px by default).
+ * the remote probe. Both price with the reading model's catalog image rule
+ * ({@link Tokenizer.imageTokens}); a reader without one falls back to the
+ * OpenAI Responses wire's rule (GPT-5.5's 32px patches, a per-detail pixel
+ * limit and patch budget, x1.2 multiplier).
  */
 /** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
 export type ImageDetail = ImageContent["detail"];
 export type { ImageSize };
 /**
- * Estimated input tokens for one image. Unknown dimensions (undecodable data,
- * remote URLs, provider file ids) charge the detail level's full patch budget.
+ * Estimated input tokens for one image under `rule`, the OpenAI Responses
+ * wire's by default. Unknown dimensions (undecodable data, remote URLs,
+ * provider file ids) charge the rule's most expensive size.
  */
-export declare function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number;
+export declare function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail, rule?: ImageTokenization): number;
 /** Pixel size read from the header of base64-encoded image data, or null. */
 export declare function base64ImageSize(base64: string): ImageSize | null;
 /** Pixel size of a `data:<mime>;base64,` URL, or null for any other URL. */
 export declare function dataUrlImageSize(url: string): ImageSize | null;
-/** {@link estimateImageTokens} for an in-memory image block. */
-export declare function estimateImageContentTokens(image: Pick<ImageContent, "data" | "detail">): number;

package/dist/types/output-budget.d.ts

@@ -2,14 +2,22 @@ import type { Context, Model } from "@linxiraos/pi-ai";
 import type { Tokenizer } from "./tokenizer.js";
 /** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
 export declare const MIN_FITTED_OUTPUT_TOKENS = 1024;
+/**
+ * Chat-template framing charged per locally counted message. `Tokenizer.countMessage`
+ * counts content only, but every template wraps each message in role markers and
+ * separators, and tool results in response wrappers: about 5 tokens per merged
+ * Qwen3 `<tool_response>` or Llama 3 turn, 10–15 for harmony or Mistral tool results.
+ * The proportional margin scales with content, so many short messages (a turn's
+ * parallel tool results) leave this uncovered. Provider-anchored messages need no
+ * charge: the host's own report already includes their framing.
+ */
+export declare const MESSAGE_FRAMING_TOKENS = 16;
 /**
  * Absolute headway subtracted from the remaining room (unconditionally, on anchored and
- * fully-local counts alike). Proportional padding covers
- * tokenizer drift that scales with the prompt, but a host can still count a few tokens more
- * than any local estimate can see (chat-template framing, reasoning wrappers). Measured
- * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were rejected
- * with 400s. 64 tokens covers the observed drift with margin to spare; the
- * {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
+ * fully-local counts alike). Covers per-request framing no message count sees: the
+ * generation prompt, the anchoring turn's end marker, reasoning wrappers. Measured
+ * against a 262,144-token host: fitted caps landed +11 to +42 tokens over and were
+ * rejected with 400s. The {@link MIN_FITTED_OUTPUT_TOKENS} floor still applies.
  */
 export declare const OUTPUT_FIT_HEADWAY_TOKENS = 64;
 /**
@@ -27,7 +35,9 @@ export declare const OUTPUT_FIT_HEADWAY_TOKENS = 64;
  * The prompt size is the provider's own report from the newest trustworthy
  * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
  * only the messages appended after it; the whole context is counted locally
- * only when no turn can anchor (fresh or freshly rewritten context).
+ * only when no turn can anchor (fresh or freshly rewritten context). Local
+ * counts carry a proportional tokenizer margin plus
+ * {@link MESSAGE_FRAMING_TOKENS} per message.
  *
  * Returns `maxTokens` unchanged when the requested cap already fits, the
  * model declares no window, the host ends generation at the window itself

package/dist/types/tokenizer.d.ts

@@ -1,9 +1,27 @@
 import type { Model } from "@linxiraos/pi-ai";
+import { type ThinkingReplayTokens } from "@linxiraos/pi-catalog/compat/thinking-replay";
 import * as natives from "@linxiraos/pi-natives";
 import * as snapcompact from "@linxiraos/pi-snapcompact";
+import { type ImageDetail, type ImageSize } from "./image-tokens.js";
 import type { AgentMessage } from "./types.js";
 /** Maps the catalog-resolved tokenizer family to its native implementation. */
 export declare function tokenizerEncodingForModel(model: Pick<Model, "tokenizer"> | null | undefined): natives.Encoding | null;
+type TokenizerModel = Pick<Model, "tokenizer"> & snapcompact.ShapeTarget & {
+    compat?: Model["compat"];
+    thinking?: Model["thinking"];
+};
+/** Identity of the reader whose replayed reasoning a {@link Tokenizer} counts; equal keys count it alike. */
+export declare function reasoningReplayKey(model: TokenizerModel | null | undefined): string;
+/** Request state a {@link Tokenizer} counts for, beyond its model. */
+export interface TokenizerOptions {
+    /**
+     * Whether the request replays native Responses history (pi-ai's
+     * `openAIResponsesReplaysNativeHistory`). A cold session rebuilds a turn
+     * holding encrypted reasoning from its text and tool calls, without the
+     * reasoning or its signature. Default: true.
+     */
+    nativeHistoryReplay?: boolean;
+}
 /**
  * `strict` always tries an exact native count (the catalog-resolved tokenizer
  * when known, o200k_base otherwise), falling back to the byte upper bound when
@@ -19,11 +37,15 @@ export interface MessageCountOptions {
     /**
      * Drop opaque provider reasoning payloads (`thinkingSignature`,
      * `redactedThinking`, native server-tool blocks) 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.
+     * are billed by the provider on replay, so the default counts them (a reader
+     * billing replayed thinking at `output` size: the reasoning, at its turn's
+     * output size) — 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.
+     * Native Responses reasoning that actually replays is not an opaque byte
+     * guess: it is charged at the turn's provider-reported reasoning tokens in
+     * both arms.
      */
     excludeEncryptedReasoning?: boolean;
 }
@@ -43,15 +65,28 @@ export interface TokenBudgetCheck {
  * Model-aware local token counter. Immutable: the catalog-resolved encoding
  * is fixed at construction, so a cached count can never straddle two
  * encodings. An `Agent` owns one for its active model (swapping the instance
- * when the model's encoding or snapcompact frame pricing changes); one-shot
- * flows construct their own for the model that will be billed. Known
- * tokenizer families use exact native counts; unknown models keep the fast
- * byte estimate (or o200k when `PI_TOKENIZER_ACCURATE=1`).
+ * when the model's encoding, image or thinking-replay pricing, replay
+ * identity or native-history replay state changes); one-shot flows construct
+ * their own for the model that will be billed. Known tokenizer families use
+ * exact native counts; unknown models keep the fast byte estimate (or o200k
+ * when `PI_TOKENIZER_ACCURATE=1`).
  */
 export declare class Tokenizer {
     #private;
     readonly frameBillingKey: string;
-    constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null);
+    readonly reasoningReplayKey: string;
+    /** How the reader bills replayed signed thinking (catalog `thinking-replay-tokens`). */
+    readonly thinkingReplayTokens: ThinkingReplayTokens;
+    /** Whether the counted request replays native Responses history; see {@link TokenizerOptions}. */
+    readonly nativeHistoryReplay: boolean;
+    /**
+     * Counts what `streamSimple` sends `model`. Its catalog compat decides
+     * whether Responses reasoning history is filtered: `streamOpenAIResponses`'
+     * per-request `filterReasoningHistory` override is a debugging hook
+     * `streamSimple` never forwards, so a caller using it passes `model` with
+     * that compat set.
+     */
+    constructor(model?: TokenizerModel | null, options?: TokenizerOptions);
     get encoding(): natives.Encoding | null;
     countTokens(text: string | string[], mode?: TokenCountMode): number;
     /**
@@ -72,10 +107,35 @@ export declare class Tokenizer {
      * Settled historical messages are counted once and reused until an owner
      * (prune/shake/strip-images) calls `invalidateMessageCache`; streaming
      * assistants bypass the memo entirely (see the message-cache settle-gate
-     * invariant). Image blocks charge {@link estimateImageContentTokens}, the
-     * same dimension-based estimate the native remote-compaction probe applies.
+     * invariant). Image blocks charge {@link imageTokens}, the same estimate
+     * the native remote-compaction probe applies.
      */
     countMessage(message: AgentMessage, options?: MessageCountOptions): number;
+    /**
+     * {@link countMessage} for the transcript's latest surviving assistant turn
+     * (`isSurvivingAssistant`), which an Anthropic Messages replay keeps
+     * byte-for-byte (`transformMessages`): a turn whose tool calls ended without
+     * a tool-use stop keeps its signatures then, so its reasoning is charged. A
+     * count of one message cannot see its position; a caller walking back from
+     * the end of the transcript counts that turn here. Not memoized: it differs
+     * from {@link countMessage} only for that one turn.
+     */
+    countLatestTurn(message: AgentMessage, options?: MessageCountOptions): number;
     /** Sum of {@link countMessage} over `messages`. */
     countMessages(messages: readonly AgentMessage[], options?: MessageCountOptions): number;
+    /**
+     * Input tokens for one image (not a snapcompact frame) under the reader's
+     * catalog image rule, or the generic estimate when it has none.
+     */
+    imageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number;
+    /**
+     * The replayed native Responses reasoning {@link countMessage} charges
+     * across `messages`: the part of a count that changes with the reading
+     * model. A replay whose backend reported no reasoning tokens counts at the
+     * signature price `countMessage` gives it.
+     */
+    replayedReasoningTokens(messages: readonly AgentMessage[]): number;
+    /** Whether a Tokenizer built for `model` with `options` would count every message as this one does. */
+    countsAlike(model: TokenizerModel | null | undefined, options?: TokenizerOptions): boolean;
 }
+export {};

package/dist/types/types.d.ts

@@ -12,8 +12,10 @@ export interface QueuedMessagePreparation {
     /** Append context after the originals; undefined stops this attempt, retaining originals unless explicitly removed. */
     commit(): readonly AgentMessage[] | undefined;
 }
+/** Which agent queue a batch came from: steering amends the running task, follow-ups start the next one. */
+export type QueuedMessageQueue = "steering" | "followUp";
 /** Prepare an exclusively claimed batch. Undefined delivers unchanged; the signal also aborts when the claim is cancelled. */
-export type PrepareQueuedMessages = (messages: readonly AgentMessage[], signal: AbortSignal) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
+export type PrepareQueuedMessages = (messages: readonly AgentMessage[], signal: AbortSignal, queue: QueuedMessageQueue) => QueuedMessagePreparation | undefined | Promise<QueuedMessagePreparation | undefined>;
 /** Called once an aside has been inserted into the agent's live context. */
 export declare const ASIDE_MESSAGE_COMMIT: unique symbol;
 /** Symbol-keyed handoff for one finalized, tool-owned stream speculation session. */
@@ -279,6 +281,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * tools finish first.
      */
     hasQueuedAsides?: () => boolean | Promise<boolean>;
+    /**
+     * Receives a tool's `onUpdate` frames that arrive after this run's event
+     * stream ended: a call that returned while its background job keeps
+     * reporting (`details.async`), whose run yielded before the job settled.
+     * Without it those frames are dropped.
+     */
+    onDetachedToolUpdate?: (event: Extract<AgentEvent, {
+        type: "tool_execution_update";
+    }>) => void;
     /**
      * Returns follow-up messages to process after the agent would otherwise stop.
      *
@@ -1000,6 +1011,11 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     loadMode?: ToolLoadMode;
     /** Short one-line summary used for tool discovery indexes. */
     summary?: string;
+    /**
+     * Instructions a same-name extension replacement inherits in its description, because results it
+     * obtains by delegating to this native tool through `ctx.invokeTool` follow this tool's contract.
+     */
+    readonly delegationGuidance?: string;
     /**
      * On-demand documentation topics (`topic → markdown`), readable as
      * `xd://<tool>/<topic>`. Lets a tool keep large sub-surfaces out of its
@@ -1092,6 +1108,11 @@ export interface AgentContext {
  */
 export type AgentEvent = {
     type: "agent_start";
+    /**
+     * Calls of the unpaired assistant tail a continued run executes before its
+     * first model request. They run without a new assistant `message_end`.
+     */
+    resumedToolCallIds?: string[];
 } | {
     type: "agent_end";
     messages: AgentMessage[];

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@linxiraos/pi-agent-core",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://linxira-os.github.io/zeta/",
 	"author": "Linxira-OS",
@@ -28,23 +28,23 @@
 	"types": "./dist/types/index.d.ts",
 	"scripts": {
 		"check": "oxlint . && oxfmt --check --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts' && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
+		"check:types": "tsc -p tsconfig.json --noEmit",
 		"lint": "oxlint .",
 		"test": "bun test --parallel",
 		"fix": "oxlint --fix --fix-suggestions . && bun run fmt",
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-ai": "1.2.1",
-		"@linxiraos/pi-catalog": "1.2.1",
-		"@linxiraos/pi-natives": "1.2.1",
-		"@linxiraos/pi-utils": "1.2.1",
-		"@linxiraos/pi-wire": "1.2.1",
-		"@linxiraos/pi-snapcompact": "1.2.1",
+		"@linxiraos/pi-ai": "1.3.0",
+		"@linxiraos/pi-catalog": "1.3.0",
+		"@linxiraos/pi-natives": "1.3.0",
+		"@linxiraos/pi-utils": "1.3.0",
+		"@linxiraos/pi-wire": "1.3.0",
+		"@linxiraos/pi-snapcompact": "1.3.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@linxiraos/pi-omptype": "1.2.1",
+		"@linxiraos/pi-omptype": "1.3.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "1.4.3"