@linxiraos/pi-agent-core 1.1.26 → 1.1.27

package/src/compaction/pruning.ts

@@ -14,7 +14,7 @@ import {
 	isSkillReadToolResult,
 	type ProtectedToolMatcher,
 } from "./tool-protection";
-import { splitReadSelector } from "./utils";
+import { isAlternateFormReadSelector, splitReadSelector } from "./utils";
 
 export interface PruneConfig {
 	/** Keep the most recent tool output tokens intact. */
@@ -30,6 +30,8 @@ export interface PruneConfig {
 	 * unchanged.
 	 */
 	supersedeKey?: SupersedeKeyFn;
+	/** Whether a keyed result shows its whole target (see {@link SupersedePruneConfig.supersedeComplete}). */
+	supersedeComplete?: SupersedeCompleteFn;
 	/** Useless-flagged results bypass the protect window (see {@link USELESS_NOTICE}). Default true. */
 	pruneUseless?: boolean;
 	/**
@@ -100,16 +102,37 @@ export const USELESS_NOTICE = "[Uneventful result elided]";
 
 /**
  * Maps a tool call to a supersede key. Results sharing a key form a group in
- * which every result except the newest is a supersede candidate. A key `K`
- * additionally supersedes keys with prefix `K + "\u0000"` (selector-free read
- * supersedes selector-carrying reads of the same base path). Return
- * `undefined` to exempt a call from supersede grouping.
+ * which a newer successful result supersedes every older one. A key `K` also
+ * covers keys with prefix `K + "\u0000"`: they are superseded only when the
+ * newest successful result for `K` is complete (see
+ * {@link SupersedeCompleteFn}). Return `undefined` to exempt a call from
+ * supersede grouping.
  */
 export type SupersedeKeyFn = (toolName: string, args: Record<string, unknown>) => string | undefined;
 
+/**
+ * Whether a successful keyed result shows its whole target, so a result for a
+ * parent key (e.g. a selector-free read) may supersede child-key results (e.g.
+ * range reads). A summary, truncated page, or notice is not complete.
+ */
+export type SupersedeCompleteFn = (message: ToolResultMessage) => boolean;
+
 export interface SupersedePruneConfig {
-	/** Supersede key function; results sharing a key supersede older ones. */
+	/** Supersede key function; a newer successful result with the same key supersedes older ones (see {@link SupersedeKeyFn}). */
 	supersedeKey?: SupersedeKeyFn;
+	/**
+	 * Whether a successful keyed result is complete. Absent, every successful
+	 * result is complete. Child-key results are superseded only when the parent
+	 * key's newest successful result is complete; same-key results follow
+	 * newest-wins, since a same-key re-read that shows a different view means
+	 * the target changed. A failed result supersedes only older failed results.
+	 *
+	 * Trade-off, by design: after `read foo.ts:50-200` → edit → a bare
+	 * `read foo.ts` that returns a summary, the pre-edit range stays in context
+	 * until a complete bare read or a same-range re-read. Keeping possibly stale
+	 * detail is preferred over losing detail the summary does not show.
+	 */
+	supersedeComplete?: SupersedeCompleteFn;
 	/** Also prune results flagged useless by their tool. Default false. */
 	pruneUseless?: boolean;
 	/** Prune a candidate now when all messages after it total at most this many estimated tokens. Default 8 000. */
@@ -196,21 +219,35 @@ interface SupersedeCandidate {
 	notice: string;
 }
 
+/**
+ * Newer results of one key. An entry exists once any newer result (even a
+ * failed one) was seen. `complete` describes the newest successful result
+ * only: older successes of the key are superseded, so they cannot vouch for
+ * child keys.
+ */
+interface NewerResults {
+	success: boolean;
+	complete: boolean;
+}
+
 /**
  * Collect superseded tool results: for every unpruned, unprotected tool result
- * whose paired call resolves a supersede key, a LATER result with the same key
- * — or with a key that is the `"\u0000"`-prefix parent of this one — marks it
- * superseded. Returned in message order.
+ * whose paired call resolves a supersede key, a LATER successful result of the
+ * same key supersedes it, as does its `"\u0000"`-prefix parent key when that
+ * key's newest successful result is complete. A failed result supersedes only
+ * older failed results; an older failed result is superseded by any later
+ * result of its key or a later successful result of its parent key.
  */
 function collectSupersededResults(
 	entries: readonly SessionEntry[],
 	tokenizer: Tokenizer,
 	toolCallsById: ReadonlyMap<string, AgentToolCall>,
 	supersedeKey: SupersedeKeyFn,
+	supersedeComplete: SupersedeCompleteFn | undefined,
 	protectedTools: readonly ProtectedToolMatcher[],
 ): SupersedeCandidate[] {
 	const candidates: SupersedeCandidate[] = [];
-	const seenKeys = new Set<string>();
+	const newerByKey = new Map<string, NewerResults>();
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
@@ -221,8 +258,17 @@ function collectSupersededResults(
 		const key = supersedeKey(toolCall.name, toolCall.arguments as Record<string, unknown>);
 		if (key === undefined) continue;
 		const separator = key.indexOf("\u0000");
-		const superseded = seenKeys.has(key) || (separator >= 0 && seenKeys.has(key.slice(0, separator)));
-		seenKeys.add(key);
+		const sameKey = newerByKey.get(key);
+		const parent = separator >= 0 ? newerByKey.get(key.slice(0, separator)) : undefined;
+		const superseded = message.isError
+			? sameKey !== undefined || parent?.success === true
+			: sameKey?.success === true || parent?.complete === true;
+		const newer = sameKey ?? { success: false, complete: false };
+		if (!message.isError && !newer.success) {
+			newer.success = true;
+			newer.complete = supersedeComplete?.(message) ?? true;
+		}
+		newerByKey.set(key, newer);
 		if (!superseded) continue;
 		candidates.push({
 			entry: entry as SessionMessageEntry,
@@ -278,7 +324,14 @@ export function pruneSupersededToolResults(
 ): PruneResult {
 	const toolCallsById = collectToolCallsById(entries);
 	const candidates = config.supersedeKey
-		? collectSupersededResults(entries, tokenizer, toolCallsById, config.supersedeKey, config.protectedTools)
+		? collectSupersededResults(
+				entries,
+				tokenizer,
+				toolCallsById,
+				config.supersedeKey,
+				config.supersedeComplete,
+				config.protectedTools,
+			)
 		: [];
 	if (config.pruneUseless) {
 		const exclude = new Set(candidates.map(candidate => candidate.message));
@@ -341,9 +394,14 @@ export function pruneToolOutputs(
 	const toolCallsById = collectToolCallsById(entries);
 	const supersededMessages = config.supersedeKey
 		? new Set(
-				collectSupersededResults(entries, tokenizer, toolCallsById, config.supersedeKey, config.protectedTools).map(
-					candidate => candidate.message,
-				),
+				collectSupersededResults(
+					entries,
+					tokenizer,
+					toolCallsById,
+					config.supersedeKey,
+					config.supersedeComplete,
+					config.protectedTools,
+				).map(candidate => candidate.message),
 			)
 		: undefined;
 	const uselessMessages =
@@ -440,10 +498,11 @@ export function pruneToolOutputs(
  * selector stripped (the read tool's own splitter grammar via
  * {@link splitReadSelector}, e.g. `src/foo.ts:50-200`, `:2-4:raw`).
  * Internal/URL-scheme paths (`skill://…`, `https://…`) are exempt.
- * Selector-free reads key on the bare path; selector-carrying reads key on
- * `path + "\u0000" + selector`, so two reads collide only when the newer is
- * selector-free or the selectors are identical (the pass's prefix rule lets a
- * bare-path read supersede selector-carrying reads of the same file).
+ * Selector-free reads key on the bare path; line-range reads key on
+ * `path + "\u0000" + selector`, so a complete bare-path read can supersede them.
+ * `raw` and `conflicts` reads show a different form than a plain read (e.g. raw
+ * notebook JSON vs converted notebook text), so they key on
+ * `path + "\u0001" + selector` and are superseded only by the same selector.
  */
 export function readToolSupersedeKey(toolName: string, args: Record<string, unknown>): string | undefined {
 	if (toolName !== "read") return undefined;
@@ -451,5 +510,6 @@ export function readToolSupersedeKey(toolName: string, args: Record<string, unkn
 	if (typeof path !== "string" || path.length === 0) return undefined;
 	if (path.includes("://")) return undefined;
 	const { path: base, sel } = splitReadSelector(path);
-	return sel === undefined ? base : `${base}\u0000${sel}`;
+	if (sel === undefined) return base;
+	return `${base}${isAlternateFormReadSelector(sel) ? "\u0001" : "\u0000"}${sel}`;
 }

package/src/compaction/utils.ts

@@ -38,6 +38,7 @@ const RANGE_LIST_SRC = `${RANGE_CHUNK_SRC}(?:,${RANGE_CHUNK_SRC})*`;
 const READ_SELECTOR_RE = new RegExp(`^(?:${RANGE_LIST_SRC}|raw|conflicts)$`, "i");
 const READ_RANGE_ONLY_RE = new RegExp(`^${RANGE_LIST_SRC}$`, "i");
 const READ_RAW_ONLY_RE = /^raw$/i;
+const READ_ALTERNATE_FORM_RE = /^(?:raw|conflicts)$/i;
 
 /**
  * Split a read-tool path into its base path and trailing selector, mirroring the
@@ -77,6 +78,14 @@ export function stripReadSelector(path: string): string {
 	return splitReadSelector(path).path;
 }
 
+/**
+ * Whether a selector from {@link splitReadSelector} shows the file in a form other
+ * than its plain lines: verbatim `raw` bytes or the merge `conflicts` view.
+ */
+export function isAlternateFormReadSelector(sel: string): boolean {
+	return sel.split(":").some(part => READ_ALTERNATE_FORM_RE.test(part));
+}
+
 /**
  * A real filesystem path never contains a `scheme://` URL. Tool-call paths that
  * do — `conflict://1`, `artifact://3`, `local://ctx.md`, `history://…`,

package/src/image-tokens.ts

@@ -0,0 +1,77 @@
+import type { ImageContent } from "@linxiraos/pi-ai";
+import {
+	type ImageSize,
+	type ImageTokenization,
+	imageTokens,
+	resolveImageTokenization,
+} from "@linxiraos/pi-catalog/compat/image-tokenization";
+import { parseImageMetadata } from "@linxiraos/pi-utils";
+
+/**
+ * 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).
+ */
+
+/** OpenAI image `detail` values; `undefined` means the provider default (`auto`). */
+export type ImageDetail = ImageContent["detail"];
+
+export type { ImageSize };
+
+// Larger than every detail level's pixel limit, so an unknown size charges
+// the level's full patch budget.
+const UNKNOWN_SIZE: ImageSize = { width: 65_535, height: 65_535 };
+
+let wireRule: ImageTokenization | undefined;
+
+/** The OpenAI Responses wire's image rule, resolved from the catalog once. */
+function openAiWireRule(): ImageTokenization {
+	if (wireRule) return wireRule;
+	const rule = resolveImageTokenization({ api: "openai-responses" });
+	if (!rule) throw new Error("The catalog has no image-tokenization rule for the openai-responses wire");
+	wireRule = rule;
+	return rule;
+}
+
+/**
+ * Estimated input tokens for one image. Unknown dimensions (undecodable data,
+ * remote URLs, provider file ids) charge the detail level's full patch budget.
+ */
+export function estimateImageTokens(size: ImageSize | null | undefined, detail?: ImageDetail): number {
+	return imageTokens(openAiWireRule(), size && size.width > 0 && size.height > 0 ? size : UNKNOWN_SIZE, detail);
+}
+
+// Enough decoded bytes to reach a JPEG SOF marker behind typical EXIF/ICC
+// segments; PNG/GIF/WebP need only the first 30 bytes. Multiple of 4 so the
+// base64 slice decodes cleanly.
+const HEADER_BASE64_CHARS = 4 * Math.ceil((64 * 1024) / 3);
+
+/** Pixel size read from the header of base64-encoded image data, or null. */
+export function base64ImageSize(base64: string): ImageSize | null {
+	if (base64.length === 0) return null;
+	const header = Buffer.from(base64.slice(0, HEADER_BASE64_CHARS), "base64");
+	const metadata = parseImageMetadata(header);
+	if (!metadata?.width || !metadata.height) return null;
+	return { width: metadata.width, height: metadata.height };
+}
+
+/** Pixel size of a `data:<mime>;base64,` URL, or null for any other URL. */
+export function dataUrlImageSize(url: string): ImageSize | null {
+	if (!url.startsWith("data:")) return null;
+	const comma = url.indexOf(",");
+	if (comma < 0 || !url.slice(0, comma).endsWith(";base64")) return null;
+	return base64ImageSize(url.slice(comma + 1));
+}
+
+/** {@link estimateImageTokens} for an in-memory image block. */
+export function estimateImageContentTokens(image: Pick<ImageContent, "data" | "detail">): number {
+	return estimateImageTokens(base64ImageSize(image.data), image.detail);
+}

package/src/prompts/dsml-tool-call-leak.md

@@ -0,0 +1,19 @@
+Tool call failed: your previous response tried to invoke a tool, but the DSML markup was malformed, so it arrived as plain text, no tool was executed, and the broken markup was removed from your response. Usually the opening `<｜DSML｜tool_calls>` and/or `<｜DSML｜invoke name="…">` tags are missing, or the tool name was written as a plain line.
+
+A tool call must be one complete envelope:
+
+```
+<｜DSML｜tool_calls>
+<｜DSML｜invoke name="TOOL_NAME">
+<｜DSML｜parameter name="ARG_NAME" string="true">text value</｜DSML｜parameter>
+<｜DSML｜parameter name="OTHER_ARG" string="false">{"json": "value"}</｜DSML｜parameter>
+</｜DSML｜invoke>
+</｜DSML｜tool_calls>
+```
+
+- `<｜DSML｜tool_calls>` wraps every call; put one `<｜DSML｜invoke>` per call inside it.
+- The tool name goes in the `name` attribute of `<｜DSML｜invoke>`, never on its own line.
+- Use `string="true"` for raw text values and `string="false"` for numbers, booleans, arrays, and objects (JSON).
+- Close every tag.
+
+Re-issue the intended call now in this shape, or reply in plain prose if no tool is needed.

package/src/telemetry.ts

@@ -204,10 +204,18 @@ export interface ChatUsageSnapshot {
 
 /** Context passed to the cost estimator. */
 export interface CostEstimatorContext {
+	/** OTel provider label (`gen_ai.provider.name`). */
 	readonly provider: string;
+	/** Provider id before OTel normalization (e.g. `openai-codex` for the `openai` label). */
+	readonly providerId: string | undefined;
+	/** Model id reported on the response; a provider may report a served model instead of the requested one. */
 	readonly model: string;
+	/** Requested model id, when the caller knows it. */
+	readonly modelId: string | undefined;
 	readonly serviceTier: ServiceTier | undefined;
 	readonly usage: ChatUsageSnapshot;
+	/** Cost the provider already computed for this request; the value persisted with the message. */
+	readonly usageCost: Usage["cost"];
 }
 
 /**
@@ -1138,6 +1146,8 @@ export async function finishChatSpan(
 	message: AssistantMessage,
 	options: {
 		readonly stepNumber: number;
+		/** Requested model id; `message.model` may name a served fallback model instead. */
+		readonly modelId?: string;
 		readonly serviceTier?: ServiceTier;
 		readonly responseHeaders?: Readonly<Record<string, string>>;
 		readonly baseUrl?: string;
@@ -1147,7 +1157,7 @@ export async function finishChatSpan(
 	applyChatResponseAttributes(span, message);
 	applyUsageAttributes(span, message.usage);
 	applyGatewayAttributes(span, options.responseHeaders, options.baseUrl);
-	const cost = applyCostEstimate(telemetry, span, message, options.serviceTier, options.stepNumber);
+	const cost = applyCostEstimate(telemetry, span, message, options.serviceTier, options.stepNumber, options.modelId);
 	if (telemetry) {
 		await emitChatUsage(telemetry, span, {
 			operation: GenAIOperation.Chat,
@@ -1367,10 +1377,12 @@ function applyCostEstimate(
 	message: AssistantMessage,
 	serviceTier: ServiceTier | undefined,
 	stepNumber: number | undefined,
+	modelId: string | undefined,
 ): AppliedCostEstimate {
 	if (!telemetry) return EMPTY_COST;
 	return applyCostEstimateForUsage(telemetry, span, {
 		model: message.model,
+		modelId,
 		provider: message.provider,
 		serviceTier,
 		stepNumber,
@@ -1383,6 +1395,7 @@ function applyCostEstimateForUsage(
 	span: Span,
 	input: {
 		readonly model: string;
+		readonly modelId: string | undefined;
 		readonly provider: string | undefined;
 		readonly serviceTier: ServiceTier | undefined;
 		readonly stepNumber: number | undefined;
@@ -1398,9 +1411,12 @@ function applyCostEstimateForUsage(
 	try {
 		result = estimator({
 			provider,
+			providerId: input.provider,
 			model: input.model,
+			modelId: input.modelId,
 			serviceTier: input.serviceTier,
 			usage,
+			usageCost: input.usage.cost,
 		});
 	} catch (err) {
 		emitTelemetryWarning(telemetry, {
@@ -1620,6 +1636,7 @@ export async function recordManualChatTelemetry(
 	if (telemetry) {
 		const applied = applyCostEstimateForUsage(telemetry, span, {
 			model: options.responseModel ?? options.model.id,
+			modelId: options.model.id,
 			provider: options.model.provider,
 			serviceTier: options.serviceTier,
 			stepNumber: options.stepNumber,
@@ -1889,6 +1906,7 @@ export async function instrumentedCompleteSimple<TApi extends Api>(
 				: await runOnce();
 			await finishChatSpan(telemetry, chatSpan, message, {
 				stepNumber,
+				modelId: model.id,
 				serviceTier: options.serviceTier,
 				responseHeaders: capturedHeaders,
 				baseUrl: model.baseUrl,

package/src/tokenizer.ts

@@ -5,6 +5,7 @@ import { materializeString, stringifyJson } from "@linxiraos/pi-utils";
 import { LRUCache } from "@linxiraos/pi-utils/lru";
 import * as snapcompact from "@linxiraos/pi-snapcompact";
 import { isEstimateCacheable, messageEstimateVersion } from "./compaction/message-cache";
+import { base64ImageSize, estimateImageContentTokens } from "./image-tokens";
 import type { AgentMessage } from "./types";
 
 const testEnv = Bun.env.NODE_ENV === "test";
@@ -131,12 +132,6 @@ export interface TokenBudgetCheck {
 	exact: boolean;
 }
 
-/**
- * Image content has no tokenizer representation; charge a fixed estimate
- * matching what providers typically bill for inline images.
- */
-const IMAGE_TOKEN_ESTIMATE = 1200;
-
 /**
  * Memoized estimates for one message under this tokenizer's encoding, split by
  * the {@link MessageCountOptions.excludeEncryptedReasoning} option so the two
@@ -154,13 +149,15 @@ interface MessageEstimate {
  * 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`).
+ * 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`).
  */
 export class Tokenizer {
 	readonly #encoding: natives.Encoding | null;
+	readonly #frameBilling: snapcompact.FrameBilling;
+	readonly frameBillingKey: string;
 
 	/** Exact counts only; byte fallbacks remain mode-dependent and uncached. */
 	readonly #nativeCounts = new LRUCache<string, number>({
@@ -179,8 +176,10 @@ export class Tokenizer {
 	 */
 	#estimates = new WeakMap<AgentMessage, MessageEstimate>();
 
-	constructor(model?: Pick<Model, "tokenizer"> | null) {
+	constructor(model?: (Pick<Model, "tokenizer"> & snapcompact.ShapeTarget) | null) {
 		this.#encoding = tokenizerEncodingForModel(model);
+		this.#frameBilling = snapcompact.frameBilling(model ?? undefined);
+		this.frameBillingKey = snapcompact.frameBillingKey(this.#frameBilling);
 	}
 
 	get encoding(): natives.Encoding | null {
@@ -219,7 +218,8 @@ export 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 a fixed per-image estimate.
+	 * invariant). Image blocks charge {@link estimateImageContentTokens}, the
+	 * same dimension-based estimate the native remote-compaction probe applies.
 	 */
 	countMessage(message: AgentMessage, options?: MessageCountOptions): number {
 		const floored = options?.excludeEncryptedReasoning === true;
@@ -273,7 +273,7 @@ export class Tokenizer {
 						if (block.type === "text" && block.text) {
 							fragments.push(block.text);
 						} else if (block.type === "image") {
-							extra += IMAGE_TOKEN_ESTIMATE;
+							extra += estimateImageContentTokens(block);
 						}
 					}
 				}
@@ -323,7 +323,7 @@ export class Tokenizer {
 						if (block.type === "text" && block.text) {
 							fragments.push(block.text);
 						} else if (block.type === "image") {
-							extra += IMAGE_TOKEN_ESTIMATE;
+							extra += estimateImageContentTokens(block);
 						}
 					}
 				}
@@ -336,11 +336,12 @@ export class Tokenizer {
 					if (message.blocks) {
 						for (const block of message.blocks) {
 							if (block.type === "text") fragments.push(block.text);
-							else extra += snapcompact.FRAME_TOKEN_ESTIMATE;
+							else extra += this.#frameTokens(block.data);
 						}
 					} else if (message.images) {
-						// Snapcompact frames render at ≥1568px; providers bill the downscaled cap.
-						extra += message.images.length * snapcompact.FRAME_TOKEN_ESTIMATE;
+						for (const image of message.images) {
+							extra += this.#frameTokens(image.data);
+						}
 					}
 				}
 				break;
@@ -352,4 +353,10 @@ export class Tokenizer {
 		if (fragments.length === 0) return extra;
 		return extra + this.countTokens(fragments);
 	}
+
+	/** One snapcompact frame at the active model's price for its pixel size; unreadable frames cost the ceiling. */
+	#frameTokens(data: string): number {
+		const size = base64ImageSize(data);
+		return size ? snapcompact.frameTokens(this.#frameBilling, size) : snapcompact.FRAME_TOKEN_ESTIMATE;
+	}
 }