@oh-my-pi/pi-agent-core 16.1.7 → 16.1.8

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [16.1.8] - 2026-06-20
+
+### Breaking Changes
+
+- Changed `transformProviderContext` and `buildSideRequestContext` to return a Promise
+
+### Added
+
+- Added `buildSideRequestContext` to the `Agent` class to build prompt-cache-friendly provider Contexts for side-channels or ephemeral requests.
+- Added `compactionContextTokens(providerContextTokens, storedConversationEstimate)`: floors the provider-reported context tokens by a local estimate of the stored conversation for the compaction decision, so a `before_provider_request` payload transform (a compression extension, obfuscator, or inline snapcompact) that shrinks the request can no longer deflate provider usage below the true history size and suppress auto-compaction.
+
+### Changed
+
+- Exported helper functions `normalizeMessagesForProvider` and `resolveOwnedDialectFromEnv` from `packages/agent/src/agent-loop.ts`.
+
 ## [16.1.5] - 2026-06-19
 
 ### Fixed

package/dist/types/agent-loop.d.ts

@@ -8,6 +8,7 @@ import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
 /** Stop-details marker for a provider error after assistant content/tool args already streamed. */
 export declare const STREAM_INTERRUPTED_AFTER_CONTENT_STOP_DETAIL = "stream_interrupted_after_content";
+export declare function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined;
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
@@ -54,6 +55,7 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly stream: EventStream<AgentEvent, AgentMessage[]>;
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
+export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
 export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean, exampleDialect?: Dialect, pruneDescriptions?: boolean): Context["tools"];
 /** Resolve the human-readable reason an abort carried. A caller that aborts via
  *  `AbortController.abort(reason)` with a string or a non-`AbortError` `Error`

package/dist/types/agent.d.ts

@@ -22,7 +22,7 @@ export interface AgentOptions {
      * Optional transform applied after provider context assembly and before
      * telemetry capture/provider send.
      */
-    transformProviderContext?: (context: Context, model: Model) => Context;
+    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
     /**
      * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
      */
@@ -104,6 +104,13 @@ export interface AgentOptions {
     presencePenalty?: number;
     repetitionPenalty?: number;
     serviceTier?: ServiceTier;
+    /**
+     * Per-call effective service-tier resolver. When set, it authoritatively
+     * supplies the request's tier (replacing the static `serviceTier` and its
+     * telemetry) per model — used to scope a provider/model into a priority
+     * serving path without mutating the shared session `serviceTier`.
+     */
+    serviceTierResolver?: (model: Model) => ServiceTier | undefined;
     /**
      * If true, request that the underlying provider omit reasoning/thinking summaries
      * from the response. The model still reasons internally; only the human-readable
@@ -299,6 +306,8 @@ export declare class Agent {
     set repetitionPenalty(value: number | undefined);
     get serviceTier(): ServiceTier | undefined;
     set serviceTier(value: ServiceTier | undefined);
+    get serviceTierResolver(): ((model: Model) => ServiceTier | undefined) | undefined;
+    set serviceTierResolver(value: ((model: Model) => ServiceTier | undefined) | undefined);
     get hideThinkingSummary(): boolean | undefined;
     set hideThinkingSummary(value: boolean | undefined);
     /**
@@ -313,6 +322,15 @@ export declare class Agent {
     get state(): AgentState;
     get appendOnlyContext(): AppendOnlyContextManager | undefined;
     setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
+    /**
+     * Assemble the provider Context for a side-channel (no-loop) request, mirroring
+     * the main loop's prefix (system + normalized tools) so it shares the prompt
+     * cache. Never touches the append-only log or the tool-choice queue. Owned/
+     * in-band dialect sessions stay tools-less (matching their no-native-tools wire
+     * shape and avoiding tool-markup leakage). `llmMessages` is already converted
+     * (and, in production, obfuscated) by the caller.
+     */
+    buildSideRequestContext(llmMessages: Message[]): Promise<Context>;
     subscribe(fn: (e: AgentEvent) => void): () => void;
     setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;

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

@@ -58,13 +58,38 @@ export declare function effectiveReserveTokens(contextWindow: number, settings:
  * Check if compaction should trigger based on context usage.
  */
 export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean;
+/**
+ * Context tokens to feed the compaction decision, floored by a local estimate of
+ * the stored conversation.
+ *
+ * The provider-reported usage is normally ground truth, but a
+ * `before_provider_request` payload transform — a compression extension (e.g.
+ * Headroom), an obfuscator, or inline snapcompact — can shrink the request below
+ * the real stored conversation. The provider then reports deflated prompt
+ * tokens, so anchoring compaction purely on that usage lets the real history
+ * grow unbounded until it overflows and native compaction can no longer run.
+ * Flooring by the agent's own estimate of the stored conversation keeps the
+ * compaction trigger honest regardless of on-wire compression. (Display/cost
+ * accounting still uses the exact provider usage; only the compaction decision
+ * takes the floor.)
+ */
+export declare function compactionContextTokens(providerContextTokens: number, storedConversationEstimate: number): number;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings): number;
 /**
  * Estimate token count for a message using cl100k_base via the native
  * tokenizer. This is not Claude's first-party tokenizer (Anthropic doesn't
  * publish one) but is within ~5–10% across English/code text.
+ *
+ * `excludeEncryptedReasoning` drops opaque provider reasoning payloads
+ * (`thinkingSignature`, `redactedThinking`) from the estimate. Those are billed
+ * by the provider on replay, so the default counts them — but their *local*
+ * byte size can diverge wildly from what the provider charges, so the
+ * compaction floor (which only needs the reliably-countable, on-wire-compressible
+ * content) excludes them to avoid false triggers on thinking-heavy turns.
  */
-export declare function estimateTokens(message: AgentMessage): number;
+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.

package/dist/types/types.d.ts

@@ -1,4 +1,4 @@
-import type { ApiKey, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@oh-my-pi/pi-ai";
+import type { ApiKey, AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Context, Effort, ImageContent, Message, Model, ServiceTier, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@oh-my-pi/pi-ai";
 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";
@@ -119,7 +119,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * normalization, and append-only context handling, but before telemetry capture
      * and provider send.
      */
-    transformProviderContext?: (context: Context, model: Model) => Context;
+    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
     /**
      * Resolves the API key or resolver for the current model before each LLM call.
      *
@@ -266,6 +266,16 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * to the next provider call.
      */
     getDisableReasoning?: () => boolean | undefined;
+    /**
+     * Per-call effective service-tier resolver. Unlike {@link getReasoning},
+     * this is *authoritative*: when set, its return value (including
+     * `undefined`) fully replaces the static `serviceTier` for the request and
+     * its telemetry. The resolver receives the model being requested so the
+     * caller can scope the tier per provider/model without mutating the shared
+     * session `serviceTier` (e.g. opting a Fireworks model into the Priority
+     * serving path while leaving the OpenAI/Anthropic tier untouched).
+     */
+    getServiceTier?: (model: Model) => ServiceTier | undefined;
     /**
      * Called after a tool call has been validated and is about to execute.
      *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "16.1.7",
+	"version": "16.1.8",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -35,12 +35,12 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "16.1.7",
-		"@oh-my-pi/pi-catalog": "16.1.7",
-		"@oh-my-pi/pi-natives": "16.1.7",
-		"@oh-my-pi/pi-utils": "16.1.7",
-		"@oh-my-pi/pi-wire": "16.1.7",
-		"@oh-my-pi/snapcompact": "16.1.7",
+		"@oh-my-pi/pi-ai": "16.1.8",
+		"@oh-my-pi/pi-catalog": "16.1.8",
+		"@oh-my-pi/pi-natives": "16.1.8",
+		"@oh-my-pi/pi-utils": "16.1.8",
+		"@oh-my-pi/pi-wire": "16.1.8",
+		"@oh-my-pi/snapcompact": "16.1.8",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -121,7 +121,7 @@ class HarmonyLeakInterruption extends Error {
 		this.name = "HarmonyLeakInterruption";
 	}
 }
-function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined {
+export function resolveOwnedDialectFromEnv(value: string | undefined): Dialect | undefined {
 	switch (value) {
 		case "1":
 		case "true":
@@ -502,7 +502,7 @@ function createDetailedCapture(config: AgentLoopConfig): {
 	};
 }
 
-function normalizeMessagesForProvider(
+export function normalizeMessagesForProvider(
 	messages: Context["messages"],
 	model: AgentLoopConfig["model"],
 ): Context["messages"] {
@@ -1161,7 +1161,7 @@ async function streamAssistantResponse(
 		};
 	}
 	if (config.transformProviderContext) {
-		llmContext = config.transformProviderContext(llmContext, config.model);
+		llmContext = await config.transformProviderContext(llmContext, config.model);
 	}
 
 	// Owned tool calling: take tool calls away from the provider and run them
@@ -1182,6 +1182,10 @@ async function streamAssistantResponse(
 
 	const dynamicReasoning = config.getReasoning?.();
 	const dynamicDisableReasoning = config.getDisableReasoning?.();
+	// `getServiceTier` is authoritative when present (replaces the static tier
+	// for both the wire request and telemetry), so callers can scope priority
+	// per model without touching the shared session `serviceTier`.
+	const effectiveServiceTier = config.getServiceTier ? config.getServiceTier(config.model) : config.serviceTier;
 	const harmonyMitigationEnabled = isHarmonyLeakMitigationTarget(config.model);
 	const harmonyAbortController = harmonyMitigationEnabled ? new AbortController() : undefined;
 	const requestSignal = harmonyAbortController
@@ -1229,7 +1233,7 @@ async function streamAssistantResponse(
 			topP: config.topP,
 			topK: config.topK,
 			presencePenalty: config.presencePenalty,
-			serviceTier: config.serviceTier,
+			serviceTier: effectiveServiceTier,
 			reasoningEffort: typeof effectiveReasoning === "string" ? effectiveReasoning : undefined,
 			toolChoice: effectiveToolChoice,
 			tools: llmContext.tools,
@@ -1251,7 +1255,7 @@ async function streamAssistantResponse(
 	const finishChat = async (message: AssistantMessage): Promise<void> => {
 		await finishChatSpan(telemetry, chatSpan, message, {
 			stepNumber: chatStepNumber,
-			serviceTier: config.serviceTier,
+			serviceTier: effectiveServiceTier,
 			responseHeaders: capturedHeaders,
 			baseUrl: config.model.baseUrl,
 		});
@@ -1267,6 +1271,7 @@ async function streamAssistantResponse(
 				reasoning: effectiveReasoning,
 				disableReasoning: effectiveDisableReasoning,
 				temperature: effectiveTemperature,
+				serviceTier: effectiveServiceTier,
 				signal: finalRequestSignal,
 				onResponse: captureOnResponse,
 			});

package/src/agent.ts

@@ -24,9 +24,17 @@ import {
 } from "@oh-my-pi/pi-ai";
 import type { Dialect } from "@oh-my-pi/pi-ai/dialect";
 import type { HarmonyAuditEvent } from "@oh-my-pi/pi-ai/utils/harmony-leak";
+import { preferredDialect } from "@oh-my-pi/pi-catalog/identity";
 import { getBundledModel } from "@oh-my-pi/pi-catalog/models";
 import { logger } from "@oh-my-pi/pi-utils";
-import { abortReasonText, agentLoop, agentLoopContinue } from "./agent-loop";
+import {
+	abortReasonText,
+	agentLoop,
+	agentLoopContinue,
+	normalizeMessagesForProvider,
+	normalizeTools,
+	resolveOwnedDialectFromEnv,
+} from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type {
 	AgentContext,
@@ -102,7 +110,7 @@ export interface AgentOptions {
 	 * Optional transform applied after provider context assembly and before
 	 * telemetry capture/provider send.
 	 */
-	transformProviderContext?: (context: Context, model: Model) => Context;
+	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 
 	/**
 	 * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
@@ -196,6 +204,13 @@ export interface AgentOptions {
 	presencePenalty?: number;
 	repetitionPenalty?: number;
 	serviceTier?: ServiceTier;
+	/**
+	 * Per-call effective service-tier resolver. When set, it authoritatively
+	 * supplies the request's tier (replacing the static `serviceTier` and its
+	 * telemetry) per model — used to scope a provider/model into a priority
+	 * serving path without mutating the shared session `serviceTier`.
+	 */
+	serviceTierResolver?: (model: Model) => ServiceTier | undefined;
 	/**
 	 * If true, request that the underlying provider omit reasoning/thinking summaries
 	 * from the response. The model still reasons internally; only the human-readable
@@ -313,7 +328,7 @@ export class Agent {
 	#abortController?: AbortController;
 	#convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
-	#transformProviderContext?: (context: Context, model: Model) => Context;
+	#transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
 	#steeringMode: "all" | "one-at-a-time";
@@ -333,6 +348,7 @@ export class Agent {
 	#presencePenalty?: number;
 	#repetitionPenalty?: number;
 	#serviceTier?: ServiceTier;
+	#serviceTierResolver?: (model: Model) => ServiceTier | undefined;
 	#hideThinkingSummary?: boolean;
 	#maxRetryDelayMs?: number;
 	#getToolContext?: (toolCall?: ToolCallContext) => AgentToolContext | undefined;
@@ -403,6 +419,7 @@ export class Agent {
 		this.#presencePenalty = opts.presencePenalty;
 		this.#repetitionPenalty = opts.repetitionPenalty;
 		this.#serviceTier = opts.serviceTier;
+		this.#serviceTierResolver = opts.serviceTierResolver;
 		this.#hideThinkingSummary = opts.hideThinkingSummary;
 		this.#maxRetryDelayMs = opts.maxRetryDelayMs;
 		this.getApiKey = opts.getApiKey;
@@ -610,6 +627,14 @@ export class Agent {
 		this.#serviceTier = value;
 	}
 
+	get serviceTierResolver(): ((model: Model) => ServiceTier | undefined) | undefined {
+		return this.#serviceTierResolver;
+	}
+
+	set serviceTierResolver(value: ((model: Model) => ServiceTier | undefined) | undefined) {
+		this.#serviceTierResolver = value;
+	}
+
 	get hideThinkingSummary(): boolean | undefined {
 		return this.#hideThinkingSummary;
 	}
@@ -645,6 +670,32 @@ export class Agent {
 		this.#appendOnlyContext = manager;
 	}
 
+	/**
+	 * Assemble the provider Context for a side-channel (no-loop) request, mirroring
+	 * the main loop's prefix (system + normalized tools) so it shares the prompt
+	 * cache. Never touches the append-only log or the tool-choice queue. Owned/
+	 * in-band dialect sessions stay tools-less (matching their no-native-tools wire
+	 * shape and avoiding tool-markup leakage). `llmMessages` is already converted
+	 * (and, in production, obfuscated) by the caller.
+	 */
+	async buildSideRequestContext(llmMessages: Message[]): Promise<Context> {
+		const model = this.#state.model;
+		if (!model) throw new Error("No active model on agent");
+		const ownedDialect = this.#dialect ?? resolveOwnedDialectFromEnv(Bun.env.PI_DIALECT);
+		const messages = normalizeMessagesForProvider(llmMessages, model);
+		const tools = ownedDialect
+			? []
+			: (normalizeTools(
+					this.#state.tools,
+					this.#intentTracing,
+					preferredDialect(model.id),
+					this.#pruneToolDescriptions,
+				) ?? []);
+		let context: Context = { systemPrompt: this.#state.systemPrompt, messages, tools };
+		if (this.#transformProviderContext) context = await this.#transformProviderContext(context, model);
+		return context;
+	}
+
 	subscribe(fn: (e: AgentEvent) => void): () => void {
 		this.#listeners.add(fn);
 		return () => this.#listeners.delete(fn);
@@ -1087,6 +1138,7 @@ export class Agent {
 			getToolChoice,
 			getReasoning: () => this.#state.thinkingLevel,
 			getDisableReasoning: () => this.#state.disableReasoning,
+			getServiceTier: this.#serviceTierResolver,
 			getSteeringMessages: async () => {
 				if (skipInitialSteeringPoll) {
 					skipInitialSteeringPoll = false;

package/src/compaction/compaction.ts

@@ -228,6 +228,25 @@ export function shouldCompact(contextTokens: number, contextWindow: number, sett
 	return contextTokens > thresholdTokens;
 }
 
+/**
+ * Context tokens to feed the compaction decision, floored by a local estimate of
+ * the stored conversation.
+ *
+ * The provider-reported usage is normally ground truth, but a
+ * `before_provider_request` payload transform — a compression extension (e.g.
+ * Headroom), an obfuscator, or inline snapcompact — can shrink the request below
+ * the real stored conversation. The provider then reports deflated prompt
+ * tokens, so anchoring compaction purely on that usage lets the real history
+ * grow unbounded until it overflows and native compaction can no longer run.
+ * Flooring by the agent's own estimate of the stored conversation keeps the
+ * compaction trigger honest regardless of on-wire compression. (Display/cost
+ * accounting still uses the exact provider usage; only the compaction decision
+ * takes the floor.)
+ */
+export function compactionContextTokens(providerContextTokens: number, storedConversationEstimate: number): number {
+	return Math.max(Math.max(0, providerContextTokens), Math.max(0, storedConversationEstimate));
+}
+
 export function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings): number {
 	// Fixed token limit takes priority over percentage
 	const thresholdTokens = settings.thresholdTokens;
@@ -259,8 +278,15 @@ const IMAGE_TOKEN_ESTIMATE = 1200;
  * 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 function estimateTokens(message: AgentMessage): number {
+export function estimateTokens(message: AgentMessage, options?: { excludeEncryptedReasoning?: boolean }): number {
 	const fragments: string[] = [];
 	let extra = 0;
 	if ((message as { role?: string }).role === "bashExecution") {
@@ -296,14 +322,18 @@ export function estimateTokens(message: AgentMessage): number {
 					// reasoning items, Anthropic signed thinking blocks, etc.). Without
 					// counting it, this estimator can read ~half of the provider-reported
 					// usage on thinking-heavy turns — see #2275 for the resulting
-					// compaction-trigger / post-check metric divergence.
-					if (block.thinkingSignature) fragments.push(block.thinkingSignature);
+					// compaction-trigger / post-check metric divergence. The compaction
+					// floor excludes it (its local byte size diverges from provider billing).
+					if (block.thinkingSignature && !options?.excludeEncryptedReasoning) {
+						fragments.push(block.thinkingSignature);
+					}
 				} else if (block.type === "toolCall") {
 					fragments.push(block.name);
 					fragments.push(JSON.stringify(block.arguments));
 				} else if (block.type === "redactedThinking") {
-					// Encrypted reasoning blob the provider still bills for on replay.
-					fragments.push(block.data);
+					// Encrypted reasoning blob the provider still bills for on replay;
+					// excluded from the compaction floor for the same reason as above.
+					if (!options?.excludeEncryptedReasoning) fragments.push(block.data);
 				}
 			}
 			break;

package/src/types.ts

@@ -8,6 +8,7 @@ import type {
 	ImageContent,
 	Message,
 	Model,
+	ServiceTier,
 	SimpleStreamOptions,
 	Static,
 	streamSimple,
@@ -154,7 +155,7 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * normalization, and append-only context handling, but before telemetry capture
 	 * and provider send.
 	 */
-	transformProviderContext?: (context: Context, model: Model) => Context;
+	transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
 
 	/**
 	 * Resolves the API key or resolver for the current model before each LLM call.
@@ -315,6 +316,17 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 */
 	getDisableReasoning?: () => boolean | undefined;
 
+	/**
+	 * Per-call effective service-tier resolver. Unlike {@link getReasoning},
+	 * this is *authoritative*: when set, its return value (including
+	 * `undefined`) fully replaces the static `serviceTier` for the request and
+	 * its telemetry. The resolver receives the model being requested so the
+	 * caller can scope the tier per provider/model without mutating the shared
+	 * session `serviceTier` (e.g. opting a Fireworks model into the Priority
+	 * serving path while leaving the OpenAI/Anthropic tier untouched).
+	 */
+	getServiceTier?: (model: Model) => ServiceTier | undefined;
+
 	/**
 	 * Called after a tool call has been validated and is about to execute.
 	 *