@linxiraos/pi-agent-core 1.0.9 → 1.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+Copyright (c) 2025-2026 Can Bölük
+Copyright (c) 2026 Stencil Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,79 +1,78 @@
 {
-	"type": "module",
-	"name": "@linxiraos/pi-agent-core",
-	"version": "1.0.9",
-	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
-	"homepage": "https://linxira-os.github.io",
-	"author": "Can Boluk",
-	"contributors": [
-		"Mario Zechner"
-	],
-	"license": "MIT",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
-		"directory": "packages/agent"
-	},
-	"bugs": {
-		"url": "https://github.com/can1357/oh-my-pi/issues"
-	},
-	"keywords": [
-		"ai",
-		"agent",
-		"llm",
-		"transport",
-		"state-management"
-	],
-	"main": "./src/index.ts",
-	"types": "./dist/types/index.d.ts",
-	"scripts": {
-		"check": "biome check . && bun run check:types",
-		"check:types": "tsgo -p tsconfig.json --noEmit",
-		"lint": "biome lint .",
-		"test": "bun test --parallel",
-		"fix": "biome check --write --unsafe .",
-		"fmt": "biome format --write ."
-	},
-	"dependencies": {
-		"@linxiraos/pi-ai": "1.0.9",
-		"@linxiraos/pi-catalog": "1.0.9",
-		"@linxiraos/pi-natives": "1.0.9",
-		"@linxiraos/pi-utils": "1.0.9",
-		"@linxiraos/pi-wire": "1.0.9",
-		"@opentelemetry/api": "^1.9.1",
-		"@linxiraos/pi-snapcompact": "1.0.9"
-	},
-	"devDependencies": {
-		"@linxiraos/pi-omptype": "1.0.9",
-		"@opentelemetry/context-async-hooks": "^2.9.0",
-		"@opentelemetry/sdk-trace-base": "^2.9.0",
-		"@types/bun": "^1.3.14"
-	},
-	"engines": {
-		"bun": ">=1.3.14"
-	},
-	"files": [
-		"src",
-		"README.md",
-		"CHANGELOG.md",
-		"dist/types"
-	],
-	"exports": {
-		".": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./src/index.ts"
-		},
-		"./compaction": {
-			"types": "./dist/types/compaction.d.ts",
-			"import": "./src/compaction.ts"
-		},
-		"./compaction/*": {
-			"types": "./dist/types/compaction/*.d.ts",
-			"import": "./src/compaction/*.ts"
-		},
-		"./*": {
-			"types": "./dist/types/*.d.ts",
-			"import": "./src/*.ts"
-		}
-	}
-}
+  "type": "module",
+  "name": "@linxiraos/pi-agent-core",
+  "version": "1.1.0",
+  "description": "General-purpose agent with transport abstraction, state management, and attachment support",
+  "homepage": "https://linxira-os.github.io/zeta/",
+  "author": "Can Boluk",
+  "contributors": [
+    "Mario Zechner"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Linxira-OS/linxira-zeta.git",
+    "directory": "packages/agent"
+  },
+  "bugs": {
+    "url": "https://github.com/Linxira-OS/linxira-zeta/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "llm",
+    "transport",
+    "state-management"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "check": "biome check . && bun run check:types",
+    "check:types": "tsgo -p tsconfig.json --noEmit",
+    "lint": "biome lint .",
+    "test": "bun test --parallel",
+    "fix": "biome check --write --unsafe .",
+    "fmt": "biome format --write ."
+  },
+  "dependencies": {
+    "@linxiraos/pi-ai": "catalog:",
+    "@linxiraos/pi-catalog": "catalog:",
+    "@linxiraos/pi-natives": "catalog:",
+    "@linxiraos/pi-utils": "catalog:",
+    "@linxiraos/pi-wire": "catalog:",
+    "@linxiraos/pi-snapcompact": "catalog:",
+    "@opentelemetry/api": "catalog:"
+  },
+  "devDependencies": {
+    "@linxiraos/pi-omptype": "catalog:",
+    "@opentelemetry/context-async-hooks": "catalog:",
+    "@opentelemetry/sdk-trace-base": "catalog:",
+    "@types/bun": "catalog:"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./compaction": {
+      "types": "./src/compaction.ts",
+      "import": "./src/compaction.ts"
+    },
+    "./compaction/*": {
+      "types": "./src/compaction/*.ts",
+      "import": "./src/compaction/*.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    }
+  }
+}

package/src/agent-loop.ts

@@ -623,6 +623,15 @@ function buildAgentEndEvent(
  * Push a `turn_end` event and run the awaited per-turn hook when the run is
  * still healthy. The hook is skipped for externally aborted or errored turns so
  * a user interrupt does not hang on a background backlog wait.
+ *
+ * A {@link TERMINAL_TOOL_RESULT_ABORT_REASON} abort is the exception: it is a
+ * graceful yield (e.g. a subagent's final `yield` tool), not a user interrupt.
+ * The completed tool batch is persisted and the turn must still reach
+ * `onTurnEnd` so per-turn bookkeeping — notably advisor review of the yield
+ * delta (#9505) — runs exactly as it does for a plain end-of-turn message. The
+ * hook receives no signal in that case so downstream waits (advisor catch-up)
+ * behave identically to a normal final turn instead of short-circuiting on the
+ * spent abort.
  */
 async function emitTurnEnd(
 	stream: EventStream<AgentEvent, AgentMessage[]>,
@@ -635,10 +644,16 @@ async function emitTurnEnd(
 	runHookOnAbortedMessage = false,
 ): Promise<void> {
 	stream.push({ type: "turn_end", message, toolResults });
+	const terminalYield = signal?.reason === TERMINAL_TOOL_RESULT_ABORT_REASON;
 	const isAbortedOrError =
 		message.role === "assistant" && (message.stopReason === "aborted" || message.stopReason === "error");
-	if (signal?.aborted || (isAbortedOrError && !runHookOnAbortedMessage)) return;
-	await config.onTurnEnd?.(currentContext.messages, signal, { message, toolResults, willContinue: false, ...context });
+	if ((signal?.aborted && !terminalYield) || (isAbortedOrError && !runHookOnAbortedMessage)) return;
+	await config.onTurnEnd?.(currentContext.messages, terminalYield ? undefined : signal, {
+		message,
+		toolResults,
+		willContinue: false,
+		...context,
+	});
 }
 
 function createGateStopMessage(model: Model, reason: string | undefined): AssistantMessage {

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) {

package/src/append-only-context.ts

@@ -16,7 +16,8 @@
 
 import type { Context, Message, Tool } from "@linxiraos/pi-ai";
 import { normalizeTools } from "./agent-loop";
-import type { AgentContext } from "./types";
+import { messageEstimateVersion } from "./compaction/message-cache";
+import type { AgentContext, AgentMessage } from "./types";
 
 // ---------------------------------------------------------------------------
 // StablePrefix (formerly ImmutablePrefix)
@@ -177,6 +178,26 @@ export class AppendOnlyContextManager {
 	 * point on every subsequent turn.
 	 */
 	#messageDigests: number[] = [];
+	/**
+	 * Digests memoized by message object identity, validated by the message's
+	 * estimate version ({@link messageEstimateVersion}). Synced message objects
+	 * are stable between calls: converted fragments are cached per session
+	 * message identity and handed back unchanged on every call, so an unchanged
+	 * history re-hits this memo instead of re-serializing every previously-
+	 * synced message on each LLM call.
+	 *
+	 * Owner-side rewrites (prune/shake/strip-images) mutate messages IN PLACE
+	 * under stable identity — for assistant pass-through fragments the log
+	 * aliases the very object being mutated — so a bare identity memo would
+	 * serve pre-mutation bytes forever. Those owners MUST call
+	 * `invalidateMessageCache`, which bumps the symbol-keyed version tag
+	 * this memo validates before every hit; a version mismatch recomputes from
+	 * actual bytes and the sync diverges exactly as if a fresh object had
+	 * arrived. Mutating a synced message without that bump violates the
+	 * cache-coherence contract shared with the tokenizer and convert caches
+	 * (see `compaction/message-cache.ts`) and is unsupported.
+	 */
+	#digestMemo = new WeakMap<object, { version: number; digest: number }>();
 
 	build(context: AgentContext, options: BuildOptions): Context {
 		this.prefix.build(context, options);
@@ -290,6 +311,9 @@ export class AppendOnlyContextManager {
 	#messageDigest(msg: unknown): number {
 		if (!msg || typeof msg !== "object") return 0;
 		const m = msg as Record<string, unknown>;
+		const version = messageEstimateVersion(msg as AgentMessage);
+		const cached = this.#digestMemo.get(m);
+		if (cached !== undefined && cached.version === version) return cached.digest;
 		const payload = JSON.stringify({
 			r: m.role ?? null,
 			c: m.content ?? null,
@@ -304,7 +328,9 @@ export class AppendOnlyContextManager {
 		for (let j = 0; j < payload.length; j++) {
 			hash = ((hash << 5) - hash + payload.charCodeAt(j)) | 0;
 		}
-		return hash >>> 0;
+		const hash32 = hash >>> 0;
+		this.#digestMemo.set(m, { version, digest: hash32 });
+		return hash32;
 	}
 }
 

package/src/compaction/branch-summarization.ts

@@ -9,8 +9,8 @@ import type { Api, ApiKey, AssistantMessage, Context, Model, SimpleStreamOptions
 import { preferredDialect } from "@linxiraos/pi-catalog/identity";
 import { prompt } from "@linxiraos/pi-utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
+import { Tokenizer } from "../tokenizer";
 import type { AgentMessage } from "../types";
-import { estimateTokens } from "./compaction";
 import type { ReadonlySessionManager, SessionEntry } from "./entries";
 import {
 	type ConvertToLlm,
@@ -191,7 +191,9 @@ function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
 
 		case "compaction":
-			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp, entry.shortSummary);
+			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp, {
+				shortSummary: entry.shortSummary,
+			});
 
 		// These don't contribute to conversation content
 		case "thinking_level_change":
@@ -206,14 +208,14 @@ function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
 	}
 }
 
-function estimateBranchSummaryTokens(message: AgentMessage): number {
-	if (message.role !== "toolResult") return estimateTokens(message);
+function estimateBranchSummaryTokens(message: AgentMessage, tokenizer: Tokenizer): number {
+	if (message.role !== "toolResult") return tokenizer.countMessage(message);
 	const text = message.content
 		.filter((c): c is { type: "text"; text: string } => c.type === "text")
 		.map(c => c.text)
 		.join("");
 	if (!text) return 0;
-	return estimateTokens({
+	return tokenizer.countMessage({
 		...message,
 		content: [{ type: "text", text: truncateToolResultForSummary(text) }],
 	});
@@ -232,7 +234,11 @@ function estimateBranchSummaryTokens(message: AgentMessage): number {
  * @param entries - Entries in chronological order
  * @param tokenBudget - Maximum tokens to include (0 = no limit)
  */
-export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: number = 0): BranchPreparation {
+export function prepareBranchEntries(
+	entries: SessionEntry[],
+	tokenizer: Tokenizer,
+	tokenBudget: number = 0,
+): BranchPreparation {
 	const messages: AgentMessage[] = [];
 	const fileOps = createFileOps();
 	let totalTokens = 0;
@@ -264,7 +270,7 @@ export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: numbe
 		// Extract file ops from assistant messages (tool calls)
 		extractFileOpsFromMessage(message, fileOps);
 
-		const tokens = estimateBranchSummaryTokens(message);
+		const tokens = estimateBranchSummaryTokens(message, tokenizer);
 
 		// Check budget before adding
 		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
@@ -309,8 +315,9 @@ export async function generateBranchSummary(
 	// Token budget = context window minus reserved space for prompt + response
 	const contextWindow = model.contextWindow || 128000;
 	const tokenBudget = contextWindow - reserveTokens;
+	const tokenizer = new Tokenizer(model);
 
-	const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);
+	const { messages, fileOps } = prepareBranchEntries(entries, tokenizer, tokenBudget);
 
 	if (messages.length === 0) {
 		return { summary: "No content to summarize" };

package/src/compaction/compaction-v2-streaming.ts

@@ -25,6 +25,7 @@ import {
 } from "@linxiraos/pi-ai/providers/openai-shared";
 import { captureOpenAIHttpError } from "@linxiraos/pi-ai/utils/openai-http";
 import {
+	applyCodexResidencyHeader,
 	CODEX_BASE_URL,
 	getCodexAccountId,
 	OPENAI_HEADER_VALUES,
@@ -416,6 +417,7 @@ function buildCompactionV2Headers(
 		if (accountId) {
 			headers[OPENAI_HEADERS.ACCOUNT_ID] = accountId;
 		}
+		applyCodexResidencyHeader(headers, apiKey);
 		if (routingSessionId) {
 			headers[OPENAI_HEADERS.CONVERSATION_ID] = routingSessionId;
 			headers[OPENAI_HEADERS.SESSION_ID] = routingSessionId;