@oh-my-pi/pi-agent-core 15.2.4 → 15.3.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [15.3.0] - 2026-05-25
+### Fixed
+
+- Fixed `transformContext` receiving the loop config object as the `signal` argument instead of the actual `AbortSignal`, so hooks that check `signal.aborted` or call `signal.addEventListener` now work correctly under abort/timeout conditions
+- Fixed `appendOnlyContext` not being re-evaluated after `setModel()` — the mode was decided once at session construction based on the initial model's provider, so switching from/to DeepSeek (or changing `provider.appendOnlyContext`) mid-session produced incorrect mode behavior
+
 ## [15.2.3] - 2026-05-22
 ### Added
 

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

@@ -2,7 +2,7 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { EventStream } from "@oh-my-pi/pi-ai";
+import { type Context, EventStream } from "@oh-my-pi/pi-ai";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
 /**
@@ -52,3 +52,4 @@ export declare function agentLoopContinueDetailed(context: AgentContext, config:
     readonly detailed: () => Promise<AgentLoopDetailedResult>;
 };
 export declare const INTENT_FIELD = "_i";
+export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"];

package/dist/types/agent.d.ts

@@ -2,6 +2,7 @@
  * No transport abstraction - calls streamSimple via the loop.
  */
 import { type AssistantMessage, type AssistantMessageEvent, type CursorExecHandlers, type CursorToolResultHandler, type Effort, type ImageContent, type Message, type Model, type ProviderSessionState, type ServiceTier, type SimpleStreamOptions, type ThinkingBudgets, type ToolChoice } from "@oh-my-pi/pi-ai";
+import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentEvent, AgentLoopConfig, AgentMessage, AgentState, AgentTool, AgentToolContext, StreamFn, ToolCallContext } from "./types";
 export declare class AgentBusyError extends Error {
@@ -144,6 +145,11 @@ export interface AgentOptions {
      * {@link AgentLoopConfig.telemetry} for the full surface.
      */
     telemetry?: AgentLoopConfig["telemetry"];
+    /**
+     * Immutable context mode — stabilizes system prompt + tool spec bytes
+     * across turns so DeepSeek/Anthropic prefix caches hit at maximum rate.
+     */
+    appendOnlyContext?: AppendOnlyContextManager;
 }
 export interface AgentPromptOptions {
     toolChoice?: ToolChoice;
@@ -261,6 +267,8 @@ export declare class Agent {
      */
     set maxRetryDelayMs(value: number | undefined);
     get state(): AgentState;
+    get appendOnlyContext(): AppendOnlyContextManager | undefined;
+    setAppendOnlyContext(manager?: AppendOnlyContextManager): void;
     subscribe(fn: (e: AgentEvent) => void): () => void;
     setProviderResponseInterceptor(fn: SimpleStreamOptions["onResponse"] | undefined): void;
     setRawSseEventInterceptor(fn: SimpleStreamOptions["onSseEvent"] | undefined): void;

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

@@ -0,0 +1,113 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
+import type { AgentContext } from "./types";
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+    systemPrompt: string[];
+    tools: Tool[];
+    fingerprint: string;
+}
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+    /** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+    intentTracing: boolean;
+}
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export declare class StablePrefix {
+    #private;
+    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;
+    /**
+     * Returns the cached prefix.
+     * @throws if `build()` was never called.
+     */
+    toContext(): {
+        systemPrompt: string[];
+        tools: Tool[];
+    };
+}
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export declare class AppendOnlyLog {
+    #private;
+    get length(): number;
+    append(message: any): void;
+    extend(messages: any[]): void;
+    /** Replace the last entry — only legal for compaction. */
+    replaceTail(replacement: any): void;
+    /** Returns a shallow copy of all entries. */
+    toMessages(): Message[];
+    /** Direct readonly access for in-place inspection. */
+    entries(): readonly Message[];
+    clear(): void;
+}
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export declare class AppendOnlyContextManager {
+    #private;
+    readonly prefix: StablePrefix;
+    readonly log: AppendOnlyLog;
+    build(context: AgentContext, options: BuildOptions): Context;
+    /**
+     * Sync normalized (provider-level) messages into the append-only log.
+     *
+     * Detects both compaction (shorter array) and in-place rewrites
+     * (same length, changed content via a rolling digest).
+     */
+    syncMessages(normalizedMessages: any[]): void;
+    /** Reset prefix + log for a model/provider switch while mode stays active. */
+    invalidateForModelChange(): void;
+    /** Reset the sync cursor AND clear the log. */
+    resetSyncCursor(): void;
+    appendMessage(message: any): void;
+    replaceTailMessage(message: any): void;
+    invalidate(): void;
+    reset(context: AgentContext, options: BuildOptions): void;
+}

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./agent";
 export * from "./agent-loop";
+export * from "./append-only-context";
 export * from "./compaction";
 export * from "./harmony-leak";
 export * from "./proxy";

package/dist/types/types.d.ts

@@ -1,4 +1,5 @@
 import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@oh-my-pi/pi-ai";
+import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
@@ -122,6 +123,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * then strips from arguments before executing tools.
      */
     intentTracing?: boolean;
+    /**
+     * Append-only context mode — stabilizes system prompt + tool spec bytes
+     * across turns so provider prefix caches hit at maximum rate.
+     *
+     * When set, the loop reads messages from the append-only log (stable
+     * byte prefix) and caches system prompt + tools. Tools exclude per-turn
+     * `_i` intent fields.
+     */
+    appendOnlyContext?: AppendOnlyContextManager;
     /**
      * Inspect assistant streaming events before they are published to the outer agent event stream.
      * Callers may abort synchronously to stop consuming buffered provider events.

package/package.json

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

package/src/agent-loop.ts

@@ -363,7 +363,7 @@ function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" =
 	};
 }
 
-function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"] {
+export function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"] {
 	injectIntent = injectIntent && Bun.env.PI_NO_INTENT !== "1";
 	return tools?.map(t => {
 		const intentMode = resolveIntentMode(t.intent);
@@ -647,12 +647,19 @@ async function streamAssistantResponse(
 	const llmMessages = await config.convertToLlm(messages);
 	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
 
-	// Build LLM context
-	const llmContext: Context = {
-		systemPrompt: context.systemPrompt,
-		messages: normalizedMessages,
-		tools: normalizeTools(context.tools, !!config.intentTracing),
-	};
+	// Build LLM context — append-only mode caches system prompt + tools
+	// AND keeps an append-only message log so prior-turn bytes are stable.
+	let llmContext: Context;
+	if (config.appendOnlyContext) {
+		config.appendOnlyContext.syncMessages(normalizedMessages);
+		llmContext = config.appendOnlyContext.build(context, { intentTracing: !!config.intentTracing });
+	} else {
+		llmContext = {
+			systemPrompt: context.systemPrompt,
+			messages: normalizedMessages,
+			tools: normalizeTools(context.tools, !!config.intentTracing),
+		};
+	}
 
 	const streamFunction = streamFn || streamSimple;
 

package/src/agent.ts

@@ -21,6 +21,7 @@ import {
 	type ToolResultMessage,
 } from "@oh-my-pi/pi-ai";
 import { agentLoop, agentLoopContinue } from "./agent-loop";
+import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type {
 	AgentContext,
@@ -227,6 +228,11 @@ export interface AgentOptions {
 	 * {@link AgentLoopConfig.telemetry} for the full surface.
 	 */
 	telemetry?: AgentLoopConfig["telemetry"];
+	/**
+	 * Immutable context mode — stabilizes system prompt + tool spec bytes
+	 * across turns so DeepSeek/Anthropic prefix caches hit at maximum rate.
+	 */
+	appendOnlyContext?: AppendOnlyContextManager;
 }
 
 export interface AgentPromptOptions {
@@ -292,6 +298,7 @@ export class Agent {
 	#onHarmonyLeak?: (event: HarmonyAuditEvent) => void | Promise<void>;
 	#onBeforeYield?: () => Promise<void> | void;
 	#telemetry?: AgentLoopConfig["telemetry"];
+	#appendOnlyContext?: AppendOnlyContextManager;
 
 	/** Buffered Cursor tool results with text length at time of call (for correct ordering) */
 	#cursorToolResultBuffer: CursorToolResultEntry[] = [];
@@ -346,6 +353,7 @@ export class Agent {
 		this.beforeToolCall = opts.beforeToolCall;
 		this.afterToolCall = opts.afterToolCall;
 		this.#telemetry = opts.telemetry;
+		this.#appendOnlyContext = opts.appendOnlyContext;
 	}
 
 	/**
@@ -541,6 +549,14 @@ export class Agent {
 		return this.#state;
 	}
 
+	get appendOnlyContext(): AppendOnlyContextManager | undefined {
+		return this.#appendOnlyContext;
+	}
+
+	setAppendOnlyContext(manager?: AppendOnlyContextManager): void {
+		this.#appendOnlyContext = manager;
+	}
+
 	subscribe(fn: (e: AgentEvent) => void): () => void {
 		this.#listeners.add(fn);
 		return () => this.#listeners.delete(fn);
@@ -925,6 +941,7 @@ export class Agent {
 			cursorOnToolResult,
 			transformToolCallArguments: this.#transformToolCallArguments,
 			intentTracing: this.#intentTracing,
+			appendOnlyContext: this.#appendOnlyContext,
 			beforeToolCall: this.beforeToolCall ? (ctx, signal) => this.beforeToolCall?.(ctx, signal) : undefined,
 			afterToolCall: this.afterToolCall ? (ctx, signal) => this.afterToolCall?.(ctx, signal) : undefined,
 			onAssistantMessageEvent: this.#onAssistantMessageEvent,

package/src/append-only-context.ts

@@ -0,0 +1,297 @@
+/**
+ * Append-only context mode — stabilizes the byte prefix sent to the LLM
+ * across turns so provider prefix caches (DeepSeek, Anthropic, etc.)
+ * hit at the maximum possible rate.
+ *
+ * Two mechanisms:
+ *
+ * 1. **StablePrefix** — system prompt + tool specs are computed once
+ *    and frozen. Subsequent turns reuse the exact same byte sequence
+ *    unless `invalidate()` is called (e.g. after MCP reconnect).
+ *
+ * 2. **AppendOnlyLog** — messages only grow; prior turns are never
+ *    re-serialized. Combined with a stable prefix, only the user's new
+ *    message delta is a cache miss each turn.
+ */
+
+import type { Context, Message, Tool } from "@oh-my-pi/pi-ai";
+import { normalizeTools } from "./agent-loop";
+import type { AgentContext } from "./types";
+
+// ---------------------------------------------------------------------------
+// StablePrefix (formerly ImmutablePrefix)
+// ---------------------------------------------------------------------------
+
+/** Frozen system prompt + tool spec snapshot. */
+export interface StablePrefixSnapshot {
+	systemPrompt: string[];
+	tools: Tool[];
+	fingerprint: string;
+}
+
+/** Options threaded through `build()` so the snapshot reflects loop-time settings. */
+export interface BuildOptions {
+	/** Inject the `_i` intent field into tool schemas (must match agent-loop's normalizeTools). */
+	intentTracing: boolean;
+}
+
+/**
+ * A frozen prefix (system prompt + tools) that produces stable byte
+ * sequences across `build()` calls.
+ *
+ * The first `build()` snapshots the live state. Subsequent calls reuse
+ * the cached copy until `invalidate()` is called or the live state's
+ * fingerprint changes.
+ */
+export class StablePrefix {
+	#snapshot: StablePrefixSnapshot | null = null;
+	#version = 0;
+
+	get fingerprint(): string {
+		return this.#snapshot?.fingerprint ?? "<unbuilt>";
+	}
+	get version(): number {
+		return this.#version;
+	}
+	get built(): boolean {
+		return this.#snapshot !== null;
+	}
+
+	/**
+	 * Build or rebuild from live context.
+	 * Returns `true` if the prefix actually changed (cache miss imminent).
+	 */
+	build(context: AgentContext, options: BuildOptions): boolean {
+		const snapshot = takeSnapshot(context, options);
+		if (this.#snapshot && this.#snapshot.fingerprint === snapshot.fingerprint) {
+			return false;
+		}
+		this.#snapshot = snapshot;
+		this.#version++;
+		return true;
+	}
+
+	/** Force rebuild on the next `build()` call. */
+	invalidate(): void {
+		this.#snapshot = null;
+	}
+
+	/**
+	 * Returns the cached prefix.
+	 * @throws if `build()` was never called.
+	 */
+	toContext(): { systemPrompt: string[]; tools: Tool[] } {
+		const s = this.#snapshot;
+		if (!s) throw new Error("StablePrefix.toContext() called before build()");
+		return { systemPrompt: s.systemPrompt, tools: s.tools };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// AppendOnlyLog
+// ---------------------------------------------------------------------------
+
+/**
+ * Append-only message log at the `Message[]` (provider-level) layer.
+ *
+ * The only mutation path is `replaceTail()`, reserved for compaction.
+ * Every other operation is append-only.
+ */
+export class AppendOnlyLog {
+	#entries: Message[] = [];
+
+	get length(): number {
+		return this.#entries.length;
+	}
+
+	append(message: any): void {
+		this.#entries.push(message);
+	}
+
+	extend(messages: any[]): void {
+		for (const m of messages) this.#entries.push(m);
+	}
+
+	/** Replace the last entry — only legal for compaction. */
+	replaceTail(replacement: any): void {
+		const idx = this.#entries.length - 1;
+		if (idx >= 0) this.#entries[idx] = replacement;
+	}
+
+	/** Returns a shallow copy of all entries. */
+	toMessages(): Message[] {
+		return this.#entries.slice();
+	}
+
+	/** Direct readonly access for in-place inspection. */
+	entries(): readonly Message[] {
+		return this.#entries;
+	}
+
+	clear(): void {
+		this.#entries = [];
+	}
+}
+
+// ---------------------------------------------------------------------------
+// AppendOnlyContextManager
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages a stable prefix + append-only log for the agent loop.
+ *
+ * Call `build(context)` each turn to get a `Context` with stable
+ * `systemPrompt` and `tools` and append-only messages. Call
+ * `syncMessages(normalizedMessages)` after `convertToLlm` each
+ * turn to keep the log in sync.
+ *
+ * Example:
+ * ```
+ * const mgr = new AppendOnlyContextManager();
+ * const ctx = mgr.build(context);  // first call snapshots prefix
+ * mgr.syncMessages(normalized);    // grow the log
+ * ctx = mgr.build(context);        // subsequent calls use cache
+ * ```
+ */
+export class AppendOnlyContextManager {
+	readonly prefix = new StablePrefix();
+	readonly log = new AppendOnlyLog();
+	/** How many normalized messages were synced into the log as of the last sync. */
+	#lastSyncCount = 0;
+	/** Rolling digest of synced message content — detects in-place rewrites. */
+	#syncedDigest = 0;
+
+	build(context: AgentContext, options: BuildOptions): Context {
+		this.prefix.build(context, options);
+		const { systemPrompt, tools } = this.prefix.toContext();
+		return { systemPrompt, messages: this.log.toMessages(), tools };
+	}
+
+	/**
+	 * Sync normalized (provider-level) messages into the append-only log.
+	 *
+	 * Detects both compaction (shorter array) and in-place rewrites
+	 * (same length, changed content via a rolling digest).
+	 */
+	syncMessages(normalizedMessages: any[]): void {
+		// Detect in-place rewrites of already-synced messages.
+		if (
+			this.#lastSyncCount > 0 &&
+			this.#lastSyncCount <= normalizedMessages.length &&
+			this.#computeDigest(normalizedMessages.slice(0, this.#lastSyncCount)) !== this.#syncedDigest
+		) {
+			this.log.clear();
+			this.#lastSyncCount = 0;
+		}
+
+		// Compaction — array shrunk.
+		if (normalizedMessages.length < this.#lastSyncCount) {
+			this.log.clear();
+			this.#lastSyncCount = 0;
+		}
+
+		const newMsgs = normalizedMessages.slice(this.#lastSyncCount);
+		for (const msg of newMsgs) {
+			this.log.append(msg);
+		}
+
+		this.#lastSyncCount = normalizedMessages.length;
+		this.#syncedDigest = this.#computeDigest(normalizedMessages);
+	}
+
+	/** Reset prefix + log for a model/provider switch while mode stays active. */
+	invalidateForModelChange(): void {
+		this.prefix.invalidate();
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedDigest = 0;
+	}
+
+	/** Reset the sync cursor AND clear the log. */
+	resetSyncCursor(): void {
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedDigest = 0;
+	}
+
+	appendMessage(message: any): void {
+		this.log.append(message);
+	}
+
+	replaceTailMessage(message: any): void {
+		this.log.replaceTail(message);
+	}
+
+	invalidate(): void {
+		this.prefix.invalidate();
+	}
+
+	reset(context: AgentContext, options: BuildOptions): void {
+		this.prefix.invalidate();
+		this.log.clear();
+		this.#lastSyncCount = 0;
+		this.#syncedDigest = 0;
+		this.prefix.build(context, options);
+	}
+
+	/**
+	 * Deterministic digest over every field the provider may serialize — role,
+	 * content, tool calls (both `toolCalls` and OpenAI-wire `tool_calls`),
+	 * `tool_call_id`, `name`, `id`. Hashed with the same FNV-style rolling
+	 * accumulator so in-place rewrites of *any* of these fields are visible.
+	 */
+	#computeDigest(messages: readonly unknown[]): number {
+		let hash = 0;
+		for (let i = 0; i < messages.length; i++) {
+			const msg = messages[i];
+			if (!msg || typeof msg !== "object") continue;
+			const m = msg as Record<string, unknown>;
+			const payload = JSON.stringify({
+				r: m.role ?? null,
+				c: m.content ?? null,
+				tc: m.toolCalls ?? m.tool_calls ?? null,
+				tcid: m.tool_call_id ?? null,
+				n: m.name ?? null,
+				id: m.id ?? null,
+			});
+			for (let j = 0; j < payload.length; j++) {
+				hash = ((hash << 5) - hash + payload.charCodeAt(j)) | 0;
+			}
+		}
+		return hash >>> 0;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot helpers
+// ---------------------------------------------------------------------------
+
+function takeSnapshot(context: AgentContext, options: BuildOptions): StablePrefixSnapshot {
+	const systemPrompt = [...context.systemPrompt];
+	const tools = normalizeTools(context.tools, options.intentTracing) ?? [];
+	return {
+		systemPrompt,
+		tools,
+		fingerprint: computeFingerprint(systemPrompt, tools, options),
+	};
+}
+
+function computeFingerprint(systemPrompt: string[], tools: Tool[], options: BuildOptions): string {
+	const payload = JSON.stringify({
+		s: systemPrompt,
+		t: tools.map(t => ({
+			n: t.name,
+			d: t.description,
+			p: t.parameters,
+			s: t.strict,
+			cf: t.customFormat,
+			cw: t.customWireName,
+		})),
+		i: options.intentTracing,
+	});
+	let hash = 0;
+	for (let i = 0; i < payload.length; i++) {
+		hash = ((hash << 5) - hash + payload.charCodeAt(i)) | 0;
+	}
+	return (hash >>> 0).toString(36);
+}

package/src/index.ts

@@ -2,6 +2,8 @@
 export * from "./agent";
 // Loop functions
 export * from "./agent-loop";
+// Append-only context mode
+export * from "./append-only-context";
 // Compaction
 export * from "./compaction";
 export * from "./harmony-leak";

package/src/types.ts

@@ -15,6 +15,7 @@ import type {
 	ToolResultMessage,
 	TSchema,
 } from "@oh-my-pi/pi-ai";
+import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
 import type { AgentTelemetryConfig } from "./telemetry";
@@ -154,6 +155,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
 	 * then strips from arguments before executing tools.
 	 */
 	intentTracing?: boolean;
+	/**
+	 * Append-only context mode — stabilizes system prompt + tool spec bytes
+	 * across turns so provider prefix caches hit at maximum rate.
+	 *
+	 * When set, the loop reads messages from the append-only log (stable
+	 * byte prefix) and caches system prompt + tools. Tools exclude per-turn
+	 * `_i` intent fields.
+	 */
+	appendOnlyContext?: AppendOnlyContextManager;
 
 	/**
 	 * Inspect assistant streaming events before they are published to the outer agent event stream.