@oh-my-pi/pi-agent-core 17.3.7 → 17.4.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [17.4.0] - 2026-08-20
+
+### Breaking Changes
+
+- Replaced global token counting functions (`countTokens`, `countTokensConservatively`, `setTokenizerModel`, and `estimateTokens`) with model-scoped, immutable `Tokenizer` instances (`agent.tokenizer`). Use `tokenizer.countTokens(text, mode?)`, `tokenizer.countMessage(message)`, or `tokenizer.countMessages(messages)`.
+- Updated context management functions (`findCutPoint`, `prepareBranchEntries`, `collectShakeRegions`, `pruneToolOutputs`, `pruneSupersededToolResults`, and `trimRemoteCompactionInputToContextWindow`) to require an explicit `Tokenizer` instance.
+
+### Added
+
+- Added `Tokenizer.checkTokenBudget(text, budget)` to efficiently verify if text fits within a token limit using fast byte-bound checks before falling back to full tokenization.
+- Added provider-anchored transcript token estimation (`findTranscriptUsageAnchor`, `isTranscriptUsageAnchor`, `estimateTranscriptTokens`) to calculate transcript token counts incrementally from the latest reported assistant turn usage.
+- Added `remotePreserveReusable()` to check whether a previous remote compaction payload remains reusable with the active model.
+
+### Changed
+
+- Expanded native tokenizer support across catalog models, adding exact embedded token counting for Claude, Qwen 3.5+, DeepSeek V3/V4/R1, Kimi K2/K3, and GLM-5+ models. `Tokenizer` now constructs from a resolved catalog `Model`.
+- `createCompactionSummaryMessage` takes an options object after `(summary, tokensBefore, timestamp)`; `CompactionSummaryMessage` gained optional `method` and `tokensAfter` display metadata.
+
+## [17.3.8] - 2026-08-19
+
+### Fixed
+
+- Fixed `/compact` (and automatic compaction) resurrecting pre-`/clear` conversation turns: `prepareCompaction` now honors the latest `reset_boundary`, so a compaction after an in-place `/clear` only summarizes messages created after the reset ([#8718](https://github.com/can1357/oh-my-pi/issues/8718)).
+- Hardened compaction summarization against prompt injection: conversation history and previous summaries are now treated as untrusted, and embedded `<conversation>`/`<previous-summary>` boundary tags are neutralized before prompt assembly ([#8727](https://github.com/can1357/oh-my-pi/pull/8727) by [@koopmannleon19977-cmyk](https://github.com/koopmannleon19977-cmyk)).
+- Compaction summarization input is now bounded to the summary model's context (windowed fold for oversized spans) and deterministic context-overflow 400s are no longer retried up to the full retry budget; artifact ids containing `503` no longer misclassify hard 400s as transient.
+- Fixed remote compaction mirroring the #8789 Responses shape: `buildOpenAiNativeHistory` now hoists an assistant `message` wedged between a tool-call batch and its outputs ahead of the batch, so compaction requests to strict opencode-go gateways match the canonical `message(s) → calls → outputs` order ([#8789](https://github.com/can1357/oh-my-pi/issues/8789)).
+
 ## [17.3.5] - 2026-08-16
 
 ### Added

package/dist/types/agent.d.ts

@@ -2,6 +2,7 @@ import { type ApiKey, type AssistantMessage, type AssistantMessageEvent, type Co
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/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, StreamFn, ToolCallContext, ToolChoiceDirective } from "./types.js";
 export declare class AgentBusyError extends Error {
     constructor(message?: string);
@@ -354,6 +355,12 @@ export declare class Agent {
      */
     set maxRetryDelayMs(value: number | undefined);
     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.
+     */
+    get tokenizer(): Tokenizer;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
     setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
     /**
@@ -401,7 +408,7 @@ export declare class Agent {
     setAsideMessageProvider(fn: (() => AsideMessage[] | Promise<AsideMessage[]>) | undefined): void;
     emitExternalEvent(event: AgentEvent): void;
     setSystemPrompt(v: string[] | string): void;
-    setModel(m: Model): void;
+    setModel(model: Model): void;
     setThinkingLevel(l: Effort | undefined): void;
     setDisableReasoning(disabled: boolean): void;
     setSteeringMode(mode: "all" | "one-at-a-time"): void;

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

@@ -6,6 +6,7 @@
  */
 import type { Api, ApiKey, AssistantMessage, Context, Model, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry.js";
+import { Tokenizer } from "../tokenizer.js";
 import type { AgentMessage } from "../types.js";
 import type { ReadonlySessionManager, SessionEntry } from "./entries.js";
 import { type ConvertToLlm } from "./messages.js";
@@ -91,7 +92,7 @@ export declare function collectEntriesForBranchSummary(session: ReadonlySessionM
  * @param entries - Entries in chronological order
  * @param tokenBudget - Maximum tokens to include (0 = no limit)
  */
-export declare function prepareBranchEntries(entries: SessionEntry[], tokenBudget?: number): BranchPreparation;
+export declare function prepareBranchEntries(entries: SessionEntry[], tokenizer: Tokenizer, tokenBudget?: number): BranchPreparation;
 /**
  * Generate a summary of abandoned branch entries.
  *

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

@@ -7,6 +7,7 @@
 import { type Api, type ApiKey, type AssistantMessage, type CodexCompactionContext, type Context, type FetchImpl, type MessageAttribution, type Model, type OneshotRetryOptions, type ProviderSessionState, type SimpleStreamOptions, type Tool, type Usage } from "@oh-my-pi/pi-ai";
 import { type AgentTelemetry } from "../telemetry.js";
 import { ThinkingLevel } from "../thinking.js";
+import { Tokenizer } from "../tokenizer.js";
 import type { AgentMessage } from "../types.js";
 import type { SessionEntry } from "./entries.js";
 import { type ConvertToLlm } from "./messages.js";
@@ -119,21 +120,6 @@ export declare function shouldCompact(contextTokens: number, contextWindow: numb
  */
 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.
@@ -164,7 +150,7 @@ export interface CutPointResult {
  *
  * Only considers entries between `startIndex` and `endIndex` (exclusive).
  */
-export declare function findCutPoint(entries: SessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
+export declare function findCutPoint(entries: SessionEntry[], tokenizer: Tokenizer, startIndex: number, endIndex: number, keepRecentTokens: number): CutPointResult;
 export declare const AUTO_HANDOFF_THRESHOLD_FOCUS: string;
 /**
  * Generate a summary of the conversation using the LLM.
@@ -310,7 +296,41 @@ export interface CompactionPreparation {
     /** Compaction settions from settings.jsonl	*/
     settings: CompactionSettings;
 }
-export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, activeModel?: Model): CompactionPreparation | undefined;
+/**
+ * Whether a prior remote compaction's provider-native replay can still be read
+ * by the active model — the model that assembles the request context on every
+ * turn. A local compaction (no remote preserve) always can: it holds a real
+ * textual summary. A remote compaction (V2 or V1) only can when the active model
+ * shares the blob's provider AND remote replay is still enabled; otherwise the
+ * active model's encoder drops the payload (see `getOpenAIResponsesHistoryPayload`)
+ * and only the opaque placeholder summary survives, so the caller must re-expand
+ * the originals into a portable local summary rather than strand that history.
+ *
+ * Judged against the ACTIVE model, not the compaction candidate set: a role
+ * model (e.g. `modelRoles.smol`) that still maps to the blob's provider does not
+ * let the active model replay it, so keying reuse on "any candidate shares the
+ * provider" left a provider-switched session permanently context-less (#6343).
+ */
+export declare function remotePreserveReusable(preserveData: Record<string, unknown> | undefined, activeModel: Model, settings: CompactionSettings): boolean;
+/**
+ * Index of the newest compaction entry the active model can actually read, or
+ * `-1` when none can.
+ *
+ * A provider-native remote compaction (V2 or V1) stores an opaque replay payload
+ * and only a placeholder summary, so for any OTHER provider that entry
+ * summarizes nothing and the history behind it is still live context. Callers
+ * must therefore treat it as absent: `prepareCompaction` re-expands past it and
+ * summarizes those messages locally, and the maintenance ops that use the
+ * compaction boundary to skip "already summarized away" entries must not skip
+ * entries that no summary covers.
+ */
+export declare function findReadableCompactionIndex(pathEntries: SessionEntry[], settings: CompactionSettings, activeModel?: Model): number;
+/**
+ * Pass the caller's warm `tokenizer` (the Agent's for the active model) so the
+ * full-branch estimate walk hits its memo; the cold default is for one-shot
+ * callers that have no live agent.
+ */
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, activeModel?: Model, tokenizer?: Tokenizer): CompactionPreparation | undefined;
 /**
  * Generate summaries for compaction using prepared data.
  * Returns CompactionResult - SessionManager adds id/parentId when saving.

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

@@ -102,9 +102,18 @@ export interface ModeChangeEntry extends SessionEntryBase {
     /** Optional mode-specific data (e.g. plan file path) */
     data?: Record<string, unknown>;
 }
+/**
+ * Durable context-reset marker recorded by an in-place `/clear`. It carries no
+ * payload — its presence on the branch means every entry before it was dropped
+ * from the model context, so context assembly and compaction start after the
+ * latest one. The full pre-reset history stays on disk for transcript export.
+ */
+export interface ResetBoundaryEntry extends SessionEntryBase {
+    type: "reset_boundary";
+}
 export interface CustomCompactionSessionEntries {
 }
-export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TitleChangeEntry | TtsrInjectionEntry | SessionInitEntry | ModeChangeEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
+export type SessionEntry = SessionMessageEntry | ThinkingLevelChangeEntry | ModelChangeEntry | ServiceTierChangeEntry | CompactionEntry | BranchSummaryEntry | CustomEntry | CustomMessageEntry | LabelEntry | TitleChangeEntry | TtsrInjectionEntry | SessionInitEntry | ModeChangeEntry | ResetBoundaryEntry | CustomCompactionSessionEntries[keyof CustomCompactionSessionEntries];
 export interface ReadonlySessionManager {
     getBranch(leafId?: string | null): SessionEntry[];
     getEntry(id: string): SessionEntry | undefined;

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

@@ -10,4 +10,5 @@ export * from "./messages.js";
 export * from "./openai.js";
 export * from "./pruning.js";
 export * from "./shake.js";
+export * from "./transcript-tokens.js";
 export * from "./utils.js";

package/dist/types/compaction/message-cache.d.ts

@@ -5,16 +5,18 @@ import type { AgentMessage } from "../types.js";
  * unregister function. The coding-agent `convertToLlm` memo registers here.
  */
 export declare function registerMessageCacheInvalidator(invalidate: (message: AgentMessage) => void): () => void;
+/**
+ * Current estimate version of `message` (0 until first invalidation). A
+ * `Tokenizer` memo entry stamped with an older version is stale and must be
+ * recounted.
+ */
+export declare function messageEstimateVersion(message: AgentMessage): number;
 /**
  * True when this message's estimate is safe to cache by identity. Non-assistants
  * are immutable once appended; assistants are cached only once settled (see the
  * settle-gate invariant above).
  */
 export declare function isEstimateCacheable(message: AgentMessage): boolean;
-/** Read a cached estimate for the given option split, or `undefined` on miss. */
-export declare function readEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean): number | undefined;
-/** Store an estimate for the given option split. */
-export declare function writeEstimateCache(message: AgentMessage, excludeEncryptedReasoning: boolean, value: number): void;
 /**
  * Drop every cached derivation of `message` after an in-place rewrite. Owners of
  * mutation (prune, shake, strip-images) call this at the mutation seam so the

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

@@ -32,6 +32,10 @@ export interface CompactionSummaryMessage {
     summary: string;
     shortSummary?: string;
     tokensBefore: number;
+    /** Estimated context tokens after the rewrite (display metadata). */
+    tokensAfter?: number;
+    /** Harness compaction method that produced this summary (display metadata). */
+    method?: string;
     providerPayload?: ProviderPayload;
     /** Runtime-only ordered archive blocks for snapcompact: old text region,
      *  imaged middle, then new text region. When present, `summary` is already
@@ -56,7 +60,19 @@ 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)[], warning?: string): CompactionSummaryMessage;
+/** Optional metadata for {@link createCompactionSummaryMessage}. */
+export interface CompactionSummaryMessageOptions {
+    shortSummary?: string;
+    providerPayload?: ProviderPayload;
+    images?: ImageContent[];
+    blocks?: (TextContent | ImageContent)[];
+    warning?: string;
+    /** Harness compaction method that produced this summary (e.g. "remote", "soft", "handoff"). */
+    method?: string;
+    /** Estimated context tokens after the rewrite, for display alongside `tokensBefore`. */
+    tokensAfter?: number;
+}
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string, options?: CompactionSummaryMessageOptions): 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`

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

@@ -15,6 +15,7 @@
  *   with `{ summary, shortSummary? }`.
  */
 import type { CodexCompactionContext, FetchImpl, Message, Model, ProviderSessionState } from "@oh-my-pi/pi-ai/types";
+import { Tokenizer } from "../tokenizer.js";
 export * from "./compaction-v2-streaming.js";
 export declare const OPENAI_REMOTE_COMPACTION_PRESERVE_KEY = "openaiRemoteCompaction";
 /**
@@ -39,7 +40,7 @@ export interface TrimRemoteCompactionInputResult {
  * outputs keeps call/result pairing and all earlier assistant/reasoning history,
  * matching Codex's recovery path for oversized tool turns.
  */
-export declare function trimRemoteCompactionInputToContextWindow(input: Array<Record<string, unknown>>, 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[]): TrimRemoteCompactionInputResult;
 export type OpenAiRemoteCompactionItem = {
     type: "compaction" | "compaction_summary";
     encrypted_content?: string;

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

@@ -1,6 +1,7 @@
 /**
  * Tool output pruning utilities for compaction.
  */
+import type { Tokenizer } from "../tokenizer.js";
 import type { SessionEntry } from "./entries.js";
 import { type ProtectedToolMatcher } from "./tool-protection.js";
 export interface PruneConfig {
@@ -90,8 +91,8 @@ export interface SupersedePruneConfig {
  * the provider cache is cold anyway (then all still-sent candidates flush).
  * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
  */
-export declare function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult;
-export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;
+export declare function pruneSupersededToolResults(entries: SessionEntry[], tokenizer: Tokenizer, config: SupersedePruneConfig): PruneResult;
+export declare function pruneToolOutputs(entries: SessionEntry[], tokenizer: Tokenizer, config?: PruneConfig): PruneResult;
 /**
  * Supersede key for the `read` tool: the file path with the trailing line/raw
  * selector stripped (the read tool's own splitter grammar via

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

@@ -9,6 +9,7 @@
  *
  * Layering mirrors `pruning.ts`: no I/O here.
  */
+import type { Tokenizer } from "../tokenizer.js";
 import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries.js";
 import { type ProtectedToolMatcher } from "./tool-protection.js";
 export interface ShakeConfig {
@@ -77,7 +78,7 @@ export type ShakeRegion = ToolResultShakeRegion | BlockShakeRegion;
  * and regions never span a message boundary. When the combined estimated
  * savings is below `minSavings`, returns `[]` (no-op).
  */
-export declare function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[];
+export declare function collectShakeRegions(entries: SessionEntry[], tokenizer: Tokenizer, config: ShakeConfig): ShakeRegion[];
 /**
  * Pure mutation: replace a single region's content in place.
  *

package/dist/types/compaction/transcript-tokens.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Provider-anchored transcript token accounting.
+ *
+ * Local tokenization is the expensive way to answer "how big is this
+ * conversation?" — and usually the wrong one, because the provider already
+ * answered it. Every settled assistant turn carries `usage` covering the exact
+ * prompt it was sent: the system prompt, the tool schemas, and every message up
+ * to and including itself. The only genuinely unaccounted-for text is the tail
+ * appended *after* that turn.
+ *
+ * These helpers locate the newest trustworthy usage report and tokenize only
+ * that tail, so a long session pays counting proportional to one turn instead
+ * of to the whole transcript, every turn.
+ *
+ * Trust rules for an anchor (mirroring the provider contract):
+ * - Assistant role only — nothing else carries `usage`.
+ * - Not `aborted` / `error`: those turns report partial or zero usage.
+ * - `hasContextTokenUsage(usage)`: the report must carry usable context numbers.
+ */
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { Tokenizer } from "../tokenizer.js";
+import type { AgentMessage } from "../types.js";
+/** A provider usage report that accounts for a prefix of the transcript. */
+export interface TranscriptUsageAnchor {
+    /** Index in the scanned array; messages at or before it are provider-accounted. */
+    index: number;
+    /** The anchoring assistant turn. */
+    message: AssistantMessage;
+    /** Conversation tokens the provider reported for that prompt. */
+    tokens: number;
+}
+/**
+ * Whether this message's provider usage may anchor transcript accounting.
+ *
+ * The single home for the trust rules — every anchor scan MUST route through
+ * it so a stale-usage rule can never drift between the transcript walkers and
+ * the session-entry walkers.
+ */
+export declare function isTranscriptUsageAnchor(message: AgentMessage): message is AssistantMessage;
+/**
+ * Newest assistant turn in `messages[fromIndex..]` whose usage can anchor the
+ * transcript, or `undefined` when none qualifies (fresh context, or every
+ * recent turn aborted/errored).
+ *
+ * `fromIndex` excludes turns whose usage is stale — anything a compaction
+ * summarized away describes a prompt that is no longer sent.
+ */
+export declare function findTranscriptUsageAnchor(messages: readonly AgentMessage[], fromIndex?: number): TranscriptUsageAnchor | undefined;
+/** Options for {@link estimateTranscriptTokens}. */
+export interface TranscriptTokenOptions {
+    /**
+     * Gates the anchor search only: usage at or before this index is stale (a
+     * compaction rewrote the prompt it describes) and must not anchor. Content
+     * accounting is governed separately by {@link countFromIndex}.
+     */
+    anchorFromIndex?: number;
+    /**
+     * First message whose content is counted locally when no anchor is found.
+     * Defaults to 0 (count the whole transcript), which is what a floor
+     * estimate wants; pass the compaction boundary to skip summarized-away
+     * messages entirely.
+     */
+    countFromIndex?: number;
+    /** Forwarded to {@link Tokenizer.countMessage} for every locally counted message. */
+    excludeEncryptedReasoning?: boolean;
+}
+/**
+ * Conversation tokens for `messages`: the provider's own report for everything
+ * it already covers, plus a local count of only the unaccounted-for tail.
+ *
+ * An anchored result already includes the non-message prefix (system prompt +
+ * tool schemas) because the provider charged it; an unanchored result is a
+ * message-only sum. Callers that add non-message tokens on top MUST branch on
+ * {@link findTranscriptUsageAnchor} rather than assuming one shape.
+ */
+export declare function estimateTranscriptTokens(messages: readonly AgentMessage[], tokenizer: Tokenizer, options?: TranscriptTokenOptions): number;

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

@@ -49,6 +49,8 @@ export declare function upsertFileOperations(summary: string, readFiles: string[
  * Truncate tool results to the same representation used in summarization prompts.
  */
 export declare function truncateToolResultForSummary(text: string): string;
+/** Keep untrusted summary input from closing or impersonating harness-owned boundaries. */
+export declare function escapeSummaryBoundaryTags(text: string): string;
 /**
  * Serialize LLM messages as plain summary input without provider control tokens.
  */

package/dist/types/tokenizer.d.ts

@@ -1,2 +1,78 @@
-export declare function countTokens(text: string | string[]): number;
-export declare function countTokensConservatively(text: string | string[]): number;
+import type { Model } from "@oh-my-pi/pi-ai";
+import { Encoding } from "@oh-my-pi/pi-natives";
+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): Encoding | null;
+/**
+ * `strict` always pays for an exact native count (the catalog-resolved
+ * tokenizer when known, o200k_base otherwise). `approximate` and
+ * `upperbound` prefer the same exact count for known tokenizer families or
+ * when `PI_TOKENIZER_ACCURATE=1` is set; otherwise they use a cheap heuristic:
+ * `approximate` a bytes/4 guess, `upperbound` the raw byte length (never
+ * undercounts).
+ */
+export type TokenCountMode = "strict" | "approximate" | "upperbound";
+/** Options for {@link Tokenizer.countMessage} / {@link Tokenizer.countMessages}. */
+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.
+     */
+    excludeEncryptedReasoning?: boolean;
+}
+/** Verdict from {@link Tokenizer.checkTokenBudget}. */
+export interface TokenBudgetCheck {
+    /** Whether the text fits the budget. */
+    fits: boolean;
+    /**
+     * Token count behind the verdict: the exact native count when `exact` is
+     * set, otherwise the cheap byte upper bound (which already fit, so it is
+     * only an over-estimate of a count known to be under budget).
+     */
+    tokens: number;
+    /** Whether the exact tokenizer had to run because the cheap bound busted. */
+    exact: boolean;
+}
+/**
+ * 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 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;
+    constructor(model?: Pick<Model, "tokenizer"> | null);
+    get encoding(): Encoding | null;
+    countTokens(text: string | string[], mode?: TokenCountMode): number;
+    /**
+     * Cheap-first budget probe — the way to ask "does this fit in `budget`
+     * tokens?" without tokenizing the world.
+     *
+     * Byte length is a hard upper bound on token count (every token consumes at
+     * least one input byte), so text whose raw bytes already fit the budget
+     * cannot possibly exceed it — that verdict is returned without tokenizing at
+     * all. Only text that busts the bound is ambiguous, and only that case pays
+     * for the exact count. Since the bound overshoots ~4x on ordinary prose, the
+     * common "comfortably under budget" answer is free.
+     */
+    checkTokenBudget(text: string | string[], budget: number): TokenBudgetCheck;
+    /**
+     * Token estimate for one message under this tokenizer's encoding.
+     *
+     * 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 a fixed per-image estimate.
+     */
+    countMessage(message: AgentMessage, options?: MessageCountOptions): number;
+    /** Sum of {@link countMessage} over `messages`. */
+    countMessages(messages: readonly AgentMessage[], options?: MessageCountOptions): number;
+}

package/dist/types/types.d.ts

@@ -162,7 +162,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * @example
      * ```typescript
      * transformContext: async (messages) => {
-     *   if (estimateTokens(messages) > MAX_TOKENS) {
+     *   if (agent.tokenizer.countMessages(messages) > MAX_TOKENS) {
      *     return pruneOldMessages(messages);
      *   }
      *   return messages;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "17.3.7",
+	"version": "17.4.0",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,16 +35,16 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.3.7",
-		"@oh-my-pi/pi-catalog": "17.3.7",
-		"@oh-my-pi/pi-natives": "17.3.7",
-		"@oh-my-pi/pi-utils": "17.3.7",
-		"@oh-my-pi/pi-wire": "17.3.7",
-		"@oh-my-pi/snapcompact": "17.3.7",
+		"@oh-my-pi/pi-ai": "17.4.0",
+		"@oh-my-pi/pi-catalog": "17.4.0",
+		"@oh-my-pi/pi-natives": "17.4.0",
+		"@oh-my-pi/pi-utils": "17.4.0",
+		"@oh-my-pi/pi-wire": "17.4.0",
+		"@oh-my-pi/snapcompact": "17.4.0",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "17.3.7",
+		"@oh-my-pi/omptype": "17.4.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent.ts

@@ -37,6 +37,7 @@ import {
 } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import { isProviderRefusalMessage } from "./replay-policy";
+import { Tokenizer, tokenizerEncodingForModel } from "./tokenizer";
 import type {
 	AgentBeforeModelCall,
 	AgentContext,
@@ -363,7 +364,7 @@ export class Agent {
 		pendingToolCalls: new Set<string>(),
 		error: undefined,
 	};
-
+	#tokenizer = new Tokenizer(this.#state.model);
 	#listeners = new Set<(e: AgentEvent) => void>();
 	#abortController?: AbortController;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
@@ -459,6 +460,7 @@ export class Agent {
 		if (opts.initialState?.messages) this.#state.messages = opts.initialState.messages.slice();
 		if (opts.initialState?.pendingToolCalls)
 			this.#state.pendingToolCalls = new Set(opts.initialState.pendingToolCalls);
+		this.#syncTokenizer(this.#state.model);
 		this.#convertToLlm = opts.convertToLlm || defaultConvertToLlm;
 		this.#transformContext = opts.transformContext;
 		this.#steeringMode = opts.steeringMode || "one-at-a-time";
@@ -720,11 +722,29 @@ export class Agent {
 	set maxRetryDelayMs(value: number | undefined) {
 		this.#maxRetryDelayMs = value;
 	}
-
 	get state(): AgentState {
 		return this.#state;
 	}
 
+	/**
+	 * 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.
+	 */
+	get tokenizer(): Tokenizer {
+		return this.#tokenizer;
+	}
+
+	/**
+	 * Swap the tokenizer only when the encoding actually changes, so the warm
+	 * per-message memo survives same-encoding model switches.
+	 */
+	#syncTokenizer(model: Model | null | undefined): void {
+		if (tokenizerEncodingForModel(model) !== this.#tokenizer.encoding) {
+			this.#tokenizer = new Tokenizer(model);
+		}
+	}
+
 	get appendOnlyContext(): AppendOnlyContextManager | undefined {
 		return this.#appendOnlyContext;
 	}
@@ -902,8 +922,9 @@ export class Agent {
 		this.#state.systemPrompt = typeof v === "string" ? [v] : v;
 	}
 
-	setModel(m: Model) {
-		this.#state.model = m;
+	setModel(model: Model) {
+		this.#state.model = model;
+		this.#syncTokenizer(model);
 	}
 
 	setThinkingLevel(l: Effort | undefined) {