@linxiraos/pi-agent-core 1.0.10 → 1.1.0

package/src/compaction/prompts/handoff-document.md

@@ -10,6 +10,8 @@ Capture exact technical state, not abstractions.
 - Test results, observed failures
 - Decisions made
 - Partial work affecting the next step
+Register: address the successor directly in the imperative ("Fix X", "Run Y") — never first person ("I need to…", "my attempt…").
+The handoff mechanism is invisible to the document: NEVER list writing, generating, or delivering a handoff/summary/context document as progress or a next step. Progress and Next Steps cover the user's task only.
 </instruction>
 
 <output>

package/src/compaction/prompts/handoff-summary-context.md

@@ -0,0 +1,9 @@
+Context replaced. The <handoff> below is a handoff document a prior instance of you wrote from the full conversation. It is your own working memory, not user input.
+- First person inside it refers to you (the prior instance).
+- "Next Steps" is your own resumed plan; re-check it against the latest user message before acting.
+- The handoff already exists and is complete: NEVER write another handoff document unless the user explicitly asks.
+MUST build on prior work; NEVER duplicate prior work.
+
+<handoff>
+{{summary}}
+</handoff>

package/src/compaction/pruning.ts

@@ -3,8 +3,8 @@
  */
 
 import type { ToolResultMessage } from "@linxiraos/pi-ai";
+import type { Tokenizer } from "../tokenizer";
 import type { AgentMessage, AgentToolCall } from "../types";
-import { estimateTokens } from "./compaction";
 import type { SessionEntry, SessionMessageEntry } from "./entries";
 import { invalidateMessageCache } from "./message-cache";
 import {
@@ -140,13 +140,13 @@ function estimatePrunedSavings(tokens: number, notice: string): number {
  * (cacheWrite premium) if that entry is mutated in place. Used to keep prune
  * mutations inside the cheap-to-recache tail.
  */
-function computeMessageSuffixTokens(entries: readonly SessionEntry[]): number[] {
+function computeMessageSuffixTokens(entries: readonly SessionEntry[], tokenizer: Tokenizer): number[] {
 	const suffix = new Array<number>(entries.length);
 	let accumulated = 0;
 	for (let i = entries.length - 1; i >= 0; i--) {
 		suffix[i] = accumulated;
 		const entry = entries[i];
-		if (entry.type === "message") accumulated += estimateTokens(entry.message as AgentMessage);
+		if (entry.type === "message") accumulated += tokenizer.countMessage(entry.message as AgentMessage);
 	}
 	return suffix;
 }
@@ -181,6 +181,7 @@ interface SupersedeCandidate {
  */
 function collectSupersededResults(
 	entries: readonly SessionEntry[],
+	tokenizer: Tokenizer,
 	toolCallsById: ReadonlyMap<string, AgentToolCall>,
 	supersedeKey: SupersedeKeyFn,
 	protectedTools: readonly ProtectedToolMatcher[],
@@ -204,7 +205,7 @@ function collectSupersededResults(
 			entry: entry as SessionMessageEntry,
 			message,
 			index: i,
-			tokens: estimateTokens(message as AgentMessage),
+			tokens: tokenizer.countMessage(message as AgentMessage),
 			notice: SUPERSEDED_NOTICE,
 		});
 	}
@@ -219,6 +220,7 @@ function collectSupersededResults(
  */
 function collectUselessResults(
 	entries: readonly SessionEntry[],
+	tokenizer: Tokenizer,
 	toolCallsById: ReadonlyMap<string, AgentToolCall>,
 	protectedTools: readonly ProtectedToolMatcher[],
 	exclude: ReadonlySet<ToolResultMessage>,
@@ -230,7 +232,7 @@ function collectUselessResults(
 		if (message?.useless !== true || message.prunedAt !== undefined || message.isError === true) continue;
 		if (exclude.has(message)) continue;
 		if (isProtectedToolResult(message, toolCallsById.get(message.toolCallId), protectedTools)) continue;
-		const tokens = estimateTokens(message as AgentMessage);
+		const tokens = tokenizer.countMessage(message as AgentMessage);
 		if (estimatePrunedSavings(tokens, USELESS_NOTICE) <= 0) continue;
 		candidates.push({ entry: entry as SessionMessageEntry, message, index: i, tokens, notice: USELESS_NOTICE });
 	}
@@ -246,14 +248,18 @@ function collectUselessResults(
  * the provider cache is cold anyway (then all still-sent candidates flush).
  * Never mutates entries before `keepBoundaryId` (summarized away — not sent).
  */
-export function pruneSupersededToolResults(entries: SessionEntry[], config: SupersedePruneConfig): PruneResult {
+export function pruneSupersededToolResults(
+	entries: SessionEntry[],
+	tokenizer: Tokenizer,
+	config: SupersedePruneConfig,
+): PruneResult {
 	const toolCallsById = collectToolCallsById(entries);
 	const candidates = config.supersedeKey
-		? collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools)
+		? collectSupersededResults(entries, tokenizer, toolCallsById, config.supersedeKey, config.protectedTools)
 		: [];
 	if (config.pruneUseless) {
 		const exclude = new Set(candidates.map(candidate => candidate.message));
-		candidates.push(...collectUselessResults(entries, toolCallsById, config.protectedTools, exclude));
+		candidates.push(...collectUselessResults(entries, tokenizer, toolCallsById, config.protectedTools, exclude));
 		candidates.sort((a, b) => a.index - b.index);
 	}
 	if (candidates.length === 0) return { prunedCount: 0, tokensSaved: 0 };
@@ -284,7 +290,7 @@ export function pruneSupersededToolResults(entries: SessionEntry[], config: Supe
 		// Mutating a candidate re-writes its suffix in the warm cache, so prune only
 		// when that suffix is small (cheap-to-recache tail) and the candidate sits
 		// at/after the compaction boundary.
-		const suffixTokens = computeMessageSuffixTokens(entries);
+		const suffixTokens = computeMessageSuffixTokens(entries, tokenizer);
 		toPrune = candidates.filter(
 			candidate => candidate.index >= boundaryIndex && suffixTokens[candidate.index] <= suffixTokenLimit,
 		);
@@ -302,7 +308,11 @@ export function pruneSupersededToolResults(entries: SessionEntry[], config: Supe
 	return { prunedCount: toPrune.length, tokensSaved };
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+export function pruneToolOutputs(
+	entries: SessionEntry[],
+	tokenizer: Tokenizer,
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+): PruneResult {
 	let accumulatedTokens = 0;
 	let tokensSaved = 0;
 	let prunedCount = 0;
@@ -311,7 +321,7 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	const toolCallsById = collectToolCallsById(entries);
 	const supersededMessages = config.supersedeKey
 		? new Set(
-				collectSupersededResults(entries, toolCallsById, config.supersedeKey, config.protectedTools).map(
+				collectSupersededResults(entries, tokenizer, toolCallsById, config.supersedeKey, config.protectedTools).map(
 					candidate => candidate.message,
 				),
 			)
@@ -321,6 +331,7 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 			? new Set(
 					collectUselessResults(
 						entries,
+						tokenizer,
 						toolCallsById,
 						config.protectedTools,
 						supersededMessages ?? new Set(),
@@ -331,14 +342,15 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 	const boundaryIndex = resolveBoundaryIndex(entries, config.keepBoundaryId);
 	const cacheWarmSuffixTokens = config.cacheWarmSuffixTokens;
 	// All-message suffix per index, only when the cache guard is armed.
-	const messageSuffix = cacheWarmSuffixTokens === undefined ? undefined : computeMessageSuffixTokens(entries);
+	const messageSuffix =
+		cacheWarmSuffixTokens === undefined ? undefined : computeMessageSuffixTokens(entries, tokenizer);
 
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
 		const message = getToolResultMessage(entry);
 		if (!message) continue;
 
-		const tokens = estimateTokens(message as AgentMessage);
+		const tokens = tokenizer.countMessage(message as AgentMessage);
 		const isProtected = isProtectedToolResult(message, toolCallsById.get(message.toolCallId), config.protectedTools);
 
 		if (message.prunedAt !== undefined) {

package/src/compaction/shake.ts

@@ -11,9 +11,8 @@
  */
 
 import type { TextContent, ToolResultMessage } from "@linxiraos/pi-ai";
-import { countTokens } from "../tokenizer";
+import type { Tokenizer } from "../tokenizer";
 import type { AgentMessage } from "../types";
-import { estimateTokens } from "./compaction";
 import type { CustomMessageEntry, SessionEntry, SessionMessageEntry } from "./entries";
 import { invalidateMessageCache } from "./message-cache";
 import {
@@ -123,15 +122,15 @@ function toolResultText(message: ToolResultMessage): string {
 }
 
 /** Estimate the token contribution of an entry for the protect-recent window. */
-function entryTokens(entry: SessionEntry): number {
+function entryTokens(entry: SessionEntry, tokenizer: Tokenizer): number {
 	if (entry.type === "message") {
-		return estimateTokens(entry.message);
+		return tokenizer.countMessage(entry.message);
 	}
 	if (entry.type === "custom_message") {
 		const content = entry.content;
-		if (typeof content === "string") return content.length === 0 ? 0 : countTokens(content);
+		if (typeof content === "string") return content.length === 0 ? 0 : tokenizer.countTokens(content);
 		const fragments = content.filter((block): block is TextContent => block.type === "text").map(block => block.text);
-		return fragments.length === 0 ? 0 : countTokens(fragments);
+		return fragments.length === 0 ? 0 : tokenizer.countTokens(fragments);
 	}
 	return 0;
 }
@@ -222,6 +221,7 @@ function pushBlockRegions(
 	entry: SessionMessageEntry | CustomMessageEntry,
 	blockIndex: number,
 	text: string,
+	tokenizer: Tokenizer,
 	config: ShakeConfig,
 	label: string,
 	out: ShakeRegion[],
@@ -229,7 +229,7 @@ function pushBlockRegions(
 	for (const range of scanTextForBlockRanges(text)) {
 		const slice = text.slice(range.start, range.end);
 		if (slice.length === 0) continue;
-		const tokens = countTokens(slice);
+		const tokens = tokenizer.countTokens(slice);
 		if (tokens < config.fenceMinTokens) continue;
 		out.push({
 			kind: "block",
@@ -246,6 +246,7 @@ function pushBlockRegions(
 
 function collectBlockRegions(
 	entry: SessionMessageEntry | CustomMessageEntry,
+	tokenizer: Tokenizer,
 	config: ShakeConfig,
 	out: ShakeRegion[],
 ): void {
@@ -254,34 +255,35 @@ function collectBlockRegions(
 		if (message.role === "assistant") {
 			for (let bi = 0; bi < message.content.length; bi++) {
 				const block = message.content[bi];
-				if (block.type === "text") pushBlockRegions(entry, bi, block.text, config, "assistant", out);
+				if (block.type === "text") pushBlockRegions(entry, bi, block.text, tokenizer, config, "assistant", out);
 			}
 			return;
 		}
 		if (message.role === "user" || message.role === "developer") {
-			scanContentBlocks(entry, message.content, config, message.role, out);
+			scanContentBlocks(entry, message.content, tokenizer, config, message.role, out);
 		}
 		return;
 	}
 	// custom_message
-	scanContentBlocks(entry, entry.content, config, entry.customType, out);
+	scanContentBlocks(entry, entry.content, tokenizer, config, entry.customType, out);
 }
 
 function scanContentBlocks(
 	entry: SessionMessageEntry | CustomMessageEntry,
 	content: string | Array<{ type: string; text?: string }>,
+	tokenizer: Tokenizer,
 	config: ShakeConfig,
 	label: string,
 	out: ShakeRegion[],
 ): void {
 	if (typeof content === "string") {
-		pushBlockRegions(entry, -1, content, config, label, out);
+		pushBlockRegions(entry, -1, content, tokenizer, config, label, out);
 		return;
 	}
 	for (let bi = 0; bi < content.length; bi++) {
 		const block = content[bi];
 		if (block.type === "text" && typeof block.text === "string") {
-			pushBlockRegions(entry, bi, block.text, config, label, out);
+			pushBlockRegions(entry, bi, block.text, tokenizer, config, label, out);
 		}
 	}
 }
@@ -300,7 +302,7 @@ function scanContentBlocks(
  * and regions never span a message boundary. When the combined estimated
  * savings is below `minSavings`, returns `[]` (no-op).
  */
-export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig): ShakeRegion[] {
+export function collectShakeRegions(entries: SessionEntry[], tokenizer: Tokenizer, config: ShakeConfig): ShakeRegion[] {
 	const n = entries.length;
 	if (n === 0) return [];
 
@@ -309,7 +311,7 @@ export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig
 	let acc = 0;
 	for (let i = n - 1; i >= 0; i--) {
 		accumulatedAfter[i] = acc;
-		acc += entryTokens(entries[i]);
+		acc += entryTokens(entries[i], tokenizer);
 	}
 
 	const toolCallsById = collectToolCallsById(entries);
@@ -342,7 +344,7 @@ export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig
 			regions.push({
 				kind: "toolResult",
 				entry: entry as SessionMessageEntry,
-				tokens: estimateTokens(toolResult as AgentMessage),
+				tokens: tokenizer.countMessage(toolResult as AgentMessage),
 				originalText: text,
 				label: toolResult.toolName,
 			});
@@ -350,7 +352,7 @@ export function collectShakeRegions(entries: SessionEntry[], config: ShakeConfig
 		}
 
 		if (entry.type === "message" || entry.type === "custom_message") {
-			collectBlockRegions(entry as SessionMessageEntry | CustomMessageEntry, config, regions);
+			collectBlockRegions(entry as SessionMessageEntry | CustomMessageEntry, tokenizer, config, regions);
 		}
 	}
 

package/src/compaction/transcript-tokens.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 "@linxiraos/pi-ai";
+import type { MessageCountOptions, Tokenizer } from "../tokenizer";
+import type { AgentMessage } from "../types";
+import { calculateContextTokens, hasContextTokenUsage } from "./compaction";
+
+/** 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 function isTranscriptUsageAnchor(message: AgentMessage): message is AssistantMessage {
+	if (message.role !== "assistant") return false;
+	const assistant = message as AssistantMessage;
+	if (assistant.stopReason === "aborted" || assistant.stopReason === "error") return false;
+	return assistant.usage !== undefined && hasContextTokenUsage(assistant.usage);
+}
+
+/**
+ * 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 function findTranscriptUsageAnchor(
+	messages: readonly AgentMessage[],
+	fromIndex = 0,
+): TranscriptUsageAnchor | undefined {
+	for (let index = messages.length - 1; index >= fromIndex; index--) {
+		const message = messages[index];
+		if (!isTranscriptUsageAnchor(message)) continue;
+		return { index, message, tokens: calculateContextTokens(message.usage) };
+	}
+	return 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 function estimateTranscriptTokens(
+	messages: readonly AgentMessage[],
+	tokenizer: Tokenizer,
+	options?: TranscriptTokenOptions,
+): number {
+	const estimateOptions: MessageCountOptions | undefined =
+		options?.excludeEncryptedReasoning === true ? { excludeEncryptedReasoning: true } : undefined;
+	const anchor = findTranscriptUsageAnchor(messages, options?.anchorFromIndex ?? 0);
+	let total = anchor?.tokens ?? 0;
+	for (let index = anchor ? anchor.index + 1 : (options?.countFromIndex ?? 0); index < messages.length; index++) {
+		total += tokenizer.countMessage(messages[index], estimateOptions);
+	}
+	return total;
+}