@oh-my-pi/pi-agent-core 18.2.4 → 18.2.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [18.2.5] - 2026-09-17
+
+### Fixed
+
+- Improved agent performance by reducing redundant tool-schema processing during repeated model calls and optimizing streamed tool-call argument parsing.
+
 ## [18.2.1] - 2026-09-15
 
 ### Added

package/dist/types/append-only-context.d.ts

@@ -41,10 +41,6 @@ export declare class StablePrefix {
     get fingerprint(): string;
     get version(): number;
     get built(): boolean;
-    /**
-     * Build or rebuild from live context.
-     * Returns `true` if the prefix actually changed (cache miss imminent).
-     */
     build(context: AgentContext, options: BuildOptions): boolean;
     /** Force rebuild on the next `build()` call. */
     invalidate(): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-agent-core",
-	"version": "18.2.4",
+	"version": "18.2.5",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://omp.sh",
 	"author": "Stencil Labs, Inc.",
@@ -35,16 +35,16 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "18.2.4",
-		"@oh-my-pi/pi-catalog": "18.2.4",
-		"@oh-my-pi/pi-natives": "18.2.4",
-		"@oh-my-pi/pi-utils": "18.2.4",
-		"@oh-my-pi/pi-wire": "18.2.4",
-		"@oh-my-pi/snapcompact": "18.2.4",
+		"@oh-my-pi/pi-ai": "18.2.5",
+		"@oh-my-pi/pi-catalog": "18.2.5",
+		"@oh-my-pi/pi-natives": "18.2.5",
+		"@oh-my-pi/pi-utils": "18.2.5",
+		"@oh-my-pi/pi-wire": "18.2.5",
+		"@oh-my-pi/snapcompact": "18.2.5",
 		"@opentelemetry/api": "^1.9.1"
 	},
 	"devDependencies": {
-		"@oh-my-pi/omptype": "18.2.4",
+		"@oh-my-pi/omptype": "18.2.5",
 		"@opentelemetry/context-async-hooks": "^2.9.0",
 		"@opentelemetry/sdk-trace-base": "^2.9.0",
 		"@types/bun": "^1.3.14"

package/src/agent-loop.ts

@@ -37,6 +37,7 @@ import {
 	getStreamingPartialJson,
 	kCursorExecResolved,
 } from "@oh-my-pi/pi-ai/utils/block-symbols";
+import { stamp } from "@oh-my-pi/pi-ai/utils/schema/stamps";
 import {
 	createHarmonyAuditEvent,
 	detectHarmonyLeakInAssistantMessage,
@@ -886,6 +887,29 @@ export function normalizeMessagesForProvider(
 const INTENT_FIELD_DESCRIPTION = "concise intent";
 const INTENT_SCHEMA_UNION_KEYS = ["anyOf", "oneOf"] as const;
 
+// Memoize injection per input schema identity: normalizeTools runs on every
+// model call and injectIntentIntoSchema mints a fresh root object each time,
+// which defeats the stamp-keyed schema memos downstream (toolWireSchema,
+// stripSchemaDescriptions, tryEnforceStrictSchema each deep-clone + re-walk
+// the whole catalog per request). The injected object is shared across
+// requests — the same profile as the intent-off path, where parameters IS the
+// shared memoized wire schema (see schema-immutability.test.ts). One stamp
+// key per (mode, describeIntent) variant; index 0 = bare, 1 = described.
+const INTENT_STAMPS = {
+	require: [Symbol("intent:require"), Symbol("intent:require:described")],
+	optional: [Symbol("intent:optional"), Symbol("intent:optional:described")],
+} as const;
+
+function memoizedInjectIntentIntoSchema(
+	schema: Record<string, unknown>,
+	mode: "require" | "optional",
+	describeIntent: boolean,
+): unknown {
+	return stamp(schema, INTENT_STAMPS[mode][describeIntent ? 1 : 0], host =>
+		injectIntentIntoSchema(host, mode, describeIntent),
+	);
+}
+
 function injectIntentIntoSchema(
 	schema: unknown,
 	mode: "require" | "optional" = "require",
@@ -965,12 +989,14 @@ export function normalizeTools(tools: AgentContext["tools"], options: NormalizeT
 		// re-inject `i` (without its hint, which `describeIntent: false` omits) so
 		// intent tracing keeps the field while no descriptions ride the wire.
 		if (pruneDescriptions) {
-			let parameters = stripSchemaDescriptions(toolWireSchema(t)) as TSchema;
-			if (doInjectIntent) parameters = injectIntentIntoSchema(parameters, intentMode, false) as TSchema;
+			const stripped = stripSchemaDescriptions(toolWireSchema(t));
+			const parameters = (
+				doInjectIntent ? memoizedInjectIntentIntoSchema(stripped, intentMode, false) : stripped
+			) as TSchema;
 			return { ...t, parameters, description: "" };
 		}
-		let parameters = toolWireSchema(t) as TSchema;
-		if (doInjectIntent) parameters = injectIntentIntoSchema(parameters, intentMode) as TSchema;
+		const wire = toolWireSchema(t);
+		const parameters = (doInjectIntent ? memoizedInjectIntentIntoSchema(wire, intentMode, true) : wire) as TSchema;
 		const description = t.description ?? "";
 		const examplesBlock = renderToolExamples({ ...t, parameters }, doInjectIntent ? INTENT_FIELD : undefined);
 		const finalDescription = examplesBlock ? `${description}\n\n${examplesBlock}` : description;

package/src/append-only-context.ts

@@ -14,7 +14,9 @@
  *    message delta is a cache miss each turn.
  */
 
+import type { AgentTool } from "./types";
 import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
+import { toolWireSchema } from "@oh-my-pi/pi-ai";
 import { normalizeTools } from "./agent-loop";
 import { messageEstimateVersion } from "./compaction/message-cache";
 import type { AgentContext, AgentMessage } from "./types";
@@ -23,6 +25,52 @@ import type { AgentContext, AgentMessage } from "./types";
 // StablePrefix (formerly ImmutablePrefix)
 // ---------------------------------------------------------------------------
 
+/**
+ * Cheap per-tool wire-identity key: every field normalizeTools and
+ * computeFingerprint read. The resolved parameters contribute by object
+ * identity — the wire-schema memo is stamp-keyed on the parameters object,
+ * so identity equals normalized bytes (modulo intent injection, a pure
+ * function of the mode flags compared separately). `customFormat` and
+ * `examples` contribute by reference: both are treated as immutable config
+ * (a registry swap replaces the object), matching how the snapshot consumes
+ * them. `intent` functions are compared by reference — same closure means
+ * same mode resolution.
+ */
+function toolKeyForPrefix(tool: AgentTool): string {
+	const params = toolWireSchema(tool);
+	const customFormat = tool.customFormat;
+	const examples = (tool as { examples?: unknown }).examples;
+	// Identity strings for objects (Map-assigned ids, no string-build cost
+	// on the hot path beyond the first sighting per object).
+	return [
+		tool.name ?? "",
+		tool.description ?? "",
+		String(tool.strict ?? ""),
+		tool.customWireName ?? "",
+		typeof tool.intent === "function" ? `fn:${objectId(tool.intent)}` : `mode:${tool.intent ?? "require"}`,
+		objectId(params),
+		objectId(customFormat),
+		objectId(examples),
+	].join("\u0000");
+}
+
+const objectIds = new WeakMap<object, number>();
+let nextObjectId = 1;
+
+function objectId(obj: unknown): number {
+	if (obj === null || obj === undefined || (typeof obj !== "object" && typeof obj !== "function")) {
+		// Primitives contribute by value below via String(); the id path is
+		// only for reference-identity comparison of config objects.
+		return 0;
+	}
+	let id = objectIds.get(obj);
+	if (id === undefined) {
+		id = nextObjectId++;
+		objectIds.set(obj, id);
+	}
+	return id;
+}
+
 /** Frozen system prompt + tool spec snapshot. */
 export interface StablePrefixSnapshot {
 	systemPrompt: string[];
@@ -63,10 +111,42 @@ export class StablePrefix {
 	/**
 	 * Build or rebuild from live context.
 	 * Returns `true` if the prefix actually changed (cache miss imminent).
+	 *
+	 * Steady-state fast path: when the live prompt reference is unchanged
+	 * AND every tool resolves to the same normalized parameters identity as
+	 * last build, the fingerprint cannot have changed, so the full snapshot
+	 * + stringify is skipped. Comparing resolved parameters (not the tool
+	 * container) is load-bearing: tools like ReadTool expose `parameters` as
+	 * a getter over live settings (`skillful`, `memory.backend`), so the
+	 * schema can swap under stable tool references when a setting toggles.
+	 * Any other in-place mutation must go through `invalidate()`.
 	 */
+	#lastPrompt: readonly string[] | undefined;
+	// Joined prompt bytes snapshot: the prompt array is caller-owned and
+	// mutable in place (Agent.setSystemPrompt stores the caller's array;
+	// anyone holding it can push/splice), so reference equality alone cannot
+	// prove the bytes are unchanged. Compared by value on the fast path.
+	#lastPromptText: string | undefined;
+	// Per-tool wire-identity snapshot: every field normalizeTools and
+	// computeFingerprint read (name, description, resolved parameters,
+	// strict, customFormat, customWireName, intent mode, examples
+	// reference). A registry swap that keeps name/description/parameters
+	// but changes any of these must miss the fast path.
+	#lastToolKey: readonly string[] | undefined;
+	#lastIntentTracing: boolean | undefined;
+	#lastPruneToolDescriptions: boolean | undefined;
+
 	build(context: AgentContext, options: BuildOptions): boolean {
+		const prev = this.#snapshot;
+		if (prev !== null && this.#fastPathHit(context, options)) {
+			return false;
+		}
 		const snapshot = takeSnapshot(context, options);
-		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+		this.#recordFastPathKey(context, options, snapshot.tools);
+		if (prev && prev.fingerprint === snapshot.fingerprint) {
+			// Identity changed but bytes did not (e.g. equivalent rebuild):
+			// keep serving the cached snapshot so downstream memo identity
+			// (stamp-keyed schema caches) stays stable.
 			return false;
 		}
 		this.#snapshot = snapshot;
@@ -74,9 +154,50 @@ export class StablePrefix {
 		return true;
 	}
 
+	/** True when the cheap key matches: prompt + per-tool resolved identity. */
+	#fastPathHit(context: AgentContext, options: BuildOptions): boolean {
+		if (
+			this.#lastIntentTracing !== options.intentTracing ||
+			this.#lastPruneToolDescriptions !== options.pruneToolDescriptions
+		) {
+			return false;
+		}
+		// Prompt by reference first (steady state), then by joined bytes so
+		// an in-place push/splice of the same array still misses.
+		if (this.#lastPrompt !== context.systemPrompt) return false;
+		if (this.#lastPromptText !== undefined) {
+			const text = context.systemPrompt.join("\u0000");
+			if (text !== this.#lastPromptText) return false;
+		}
+		const tools = context.tools ?? [];
+		if (this.#lastToolKey === undefined || this.#lastToolKey.length !== tools.length) {
+			return false;
+		}
+		for (let i = 0; i < tools.length; i++) {
+			if (this.#lastToolKey[i] !== toolKeyForPrefix(tools[i]!)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	#recordFastPathKey(context: AgentContext, options: BuildOptions, normalized: Tool[]): void {
+		this.#lastPrompt = context.systemPrompt;
+		this.#lastPromptText = context.systemPrompt.join("\u0000");
+		this.#lastIntentTracing = options.intentTracing;
+		this.#lastPruneToolDescriptions = options.pruneToolDescriptions;
+		this.#lastToolKey = (context.tools ?? []).map(tool => toolKeyForPrefix(tool));
+		void normalized;
+	}
+
 	/** Force rebuild on the next `build()` call. */
 	invalidate(): void {
 		this.#snapshot = null;
+		this.#lastPrompt = undefined;
+		this.#lastPromptText = undefined;
+		this.#lastToolKey = undefined;
+		this.#lastIntentTracing = undefined;
+		this.#lastPruneToolDescriptions = undefined;
 	}
 
 	/**

package/src/proxy.ts

@@ -20,7 +20,7 @@ import {
 	type StreamingPartialJsonCarrier,
 	setStreamingPartialJson,
 } from "@oh-my-pi/pi-ai/utils/block-symbols";
-import { parseStreamingJson, readSseJson } from "@oh-my-pi/pi-utils";
+import { parseStreamingJson, parseStreamingJsonThrottled, readSseJson } from "@oh-my-pi/pi-utils";
 
 // Event stream adapter for proxy SSE events
 export class ProxyMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
@@ -117,6 +117,10 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 		};
 
 		let response: Response | null = null;
+		// Declared outside try so the disconnect path (catch) can finalize
+		// still-buffered tool-call arguments before emitting the error event.
+		const partialJsonByIndex = new Map<number, string>();
+		const parsedLenByIndex = new Map<number, number>();
 		const abortHandler = () => {
 			const body = response?.body;
 			if (body) {
@@ -165,12 +169,11 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 			}
 
 			let sawTerminalEvent = false;
-			const partialJsonByIndex = new Map<number, string>();
 			for await (const event of readSseJson<ProxyAssistantMessageEvent>(
 				response.body as ReadableStream<Uint8Array>,
 				options.signal,
 			)) {
-				const parsedEvent = processProxyEvent(event, partial, partialJsonByIndex);
+				const parsedEvent = processProxyEvent(event, partial, partialJsonByIndex, parsedLenByIndex);
 				if (parsedEvent) {
 					if (parsedEvent.type === "done" || parsedEvent.type === "error") {
 						sawTerminalEvent = true;
@@ -193,6 +196,10 @@ export function streamProxy(model: Model, context: Context, options: ProxyStream
 			const reason = options.signal?.aborted ? "aborted" : "error";
 			partial.stopReason = reason;
 			partial.errorMessage = errorMessage;
+			// Disconnect/abort path: no terminal event ran, so trailing
+			// throttled deltas never reached content.arguments. Finalize
+			// them here so the persisted/retried transcript is complete.
+			finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
 			stream.push({
 				type: "error",
@@ -235,6 +242,7 @@ function processProxyEvent(
 	proxyEvent: ProxyAssistantMessageEvent,
 	partial: AssistantMessage,
 	partialJsonByIndex: Map<number, string>,
+	parsedLenByIndex: Map<number, number>,
 ): AssistantMessageEvent | undefined {
 	switch (proxyEvent.type) {
 		case "start":
@@ -335,13 +343,22 @@ function processProxyEvent(
 				[kStreamingPartialJson]: "",
 			} as ToolCall & StreamingPartialJsonCarrier;
 			partialJsonByIndex.set(proxyEvent.contentIndex, "");
+			parsedLenByIndex.set(proxyEvent.contentIndex, 0);
 			return { type: "toolcall_start", contentIndex: proxyEvent.contentIndex, partial };
 		case "toolcall_delta": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
 				const acc = (partialJsonByIndex.get(proxyEvent.contentIndex) ?? "") + proxyEvent.delta;
 				partialJsonByIndex.set(proxyEvent.contentIndex, acc);
-				content.arguments = parseStreamingJson(acc) || {};
+				// Geometric throttle (same contract as native providers): the
+				// authoritative parse lands at toolcall_end; mid-stream
+				// previews refresh at most ~3% late on large buffers.
+				const lastLen = parsedLenByIndex.get(proxyEvent.contentIndex) ?? 0;
+				const parsed = parseStreamingJsonThrottled(acc, lastLen);
+				if (parsed !== null) {
+					content.arguments = parsed.value || {};
+					parsedLenByIndex.set(proxyEvent.contentIndex, parsed.parsedLen);
+				}
 				setStreamingPartialJson(content, acc);
 				partial.content[proxyEvent.contentIndex] = { ...content }; // Trigger reactivity
 				return {
@@ -357,7 +374,13 @@ function processProxyEvent(
 		case "toolcall_end": {
 			const content = partial.content[proxyEvent.contentIndex];
 			if (content?.type === "toolCall") {
+				// Authoritative final parse (mirrors native providers): the
+				// throttle may have skipped trailing deltas, so the last
+				// parsed arguments can lag the accumulated buffer.
+				const acc = partialJsonByIndex.get(proxyEvent.contentIndex);
+				if (acc !== undefined && acc.length > 0) content.arguments = parseStreamingJson(acc) || {};
 				partialJsonByIndex.delete(proxyEvent.contentIndex);
+				parsedLenByIndex.delete(proxyEvent.contentIndex);
 				clearStreamingPartialJson(content);
 				return {
 					type: "toolcall_end",
@@ -373,7 +396,10 @@ function processProxyEvent(
 			partial.stopReason = proxyEvent.reason;
 			partial.usage = proxyEvent.usage;
 			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
+			else finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
+			partialJsonByIndex.clear();
+			parsedLenByIndex.clear();
 			return { type: "done", reason: proxyEvent.reason, message: partial };
 
 		case "error":
@@ -381,7 +407,26 @@ function processProxyEvent(
 			partial.errorMessage = proxyEvent.errorMessage;
 			partial.usage = proxyEvent.usage;
 			if (proxyEvent.content !== undefined) partial.content = proxyEvent.content;
+			else finalizeBufferedArguments(partial, partialJsonByIndex);
 			scrubPartialJson(partial);
+			partialJsonByIndex.clear();
+			parsedLenByIndex.clear();
 			return { type: "error", reason: proxyEvent.reason, error: partial };
 	}
 }
+
+/**
+ * Authoritatively parse every still-buffered tool-call argument accumulator
+ * into its content block. Terminal `done`/`error` events without a preceding
+ * `toolcall_end` (and with `content` omitted) finalize the partial message as
+ *-is; without this, trailing deltas below the throttle gate never reach
+ * `content.arguments` and the finalized call carries stale arguments.
+ */
+function finalizeBufferedArguments(partial: AssistantMessage, partialJsonByIndex: Map<number, string>): void {
+	if (partialJsonByIndex.size === 0) return;
+	for (const [index, acc] of partialJsonByIndex) {
+		if (acc.length === 0) continue;
+		const content = partial.content[index];
+		if (content?.type === "toolCall") content.arguments = parseStreamingJson(acc) || {};
+	}
+}