fix(ai): declare append-only history for session-cached backends

Trailing volatile placement only pays off for backends that cache by
request prefix. Meridian's proxy matches the incoming message array
against the history it already holds, and its lineage boundary tolerates
a last-message append only for new tool_result blocks, so a payload-only
volatile text block classified as modified-history and forced a full
replay every turn.

Model.appendOnlyHistory now declares that constraint. When set, the API
registry routes volatileContext into the system prompt and adds no
payload-only message block, so the request history stays byte-identical
to the persisted conversation. Default placement is unchanged. The flag
is settable from registerProvider model entries, models.json model
definitions, and modelOverrides.

refs #26

Author: rynfar

.pylon/features.yaml

@@ -331,7 +331,7 @@ decisions:
       - https://github.com/PrimeIntellect-ai/prime-agent/commit/f81acc6679ab214f1c40821588d9e5e97c47bdb1
       - https://github.com/PrimeIntellect-ai/prime-agent/tree/c382f09856d4a8c8d2b765179657047d58691f25
     fork_change: stable-prompt-cache-prefix-v1
-    upstream_support: Prime through c382f09856d4 reduced the system-prompt date to a day stamp for cache stability, but it still serializes mutable continual-harness state and that date into the cached system prompt, has no provider-neutral volatile-content channel, and does not pin active tool order behind the `cache_control` marker on the last tool definition.
+    upstream_support: Prime through c382f09856d4 reduced the system-prompt date to a day stamp for cache stability, but it still serializes mutable continual-harness state and that date into the cached system prompt, has no provider-neutral volatile-content channel, no per-model placement contract for session-cached proxy backends, and does not pin active tool order behind the `cache_control` marker on the last tool definition.
     revisit_when:
-      - Prime upstream provides an equivalent provider-neutral channel that keeps mutable state and clock-derived content out of the cached tools/system/history prefix.
-      - Pylon can drop the fork behavior without regressing measured cache-hit rates through a Claude-Max proxy.
+      - Prime upstream provides an equivalent provider-neutral channel that keeps mutable state and clock-derived content out of the cached tools/system/history prefix, including a declared constraint for append-only-history backends.
+      - Pylon can drop the fork behavior without regressing measured cache-hit rates through a Claude-Max proxy or Meridian lineage continuation rates.

.pylon/upstream-review.md

@@ -157,6 +157,8 @@ This ledger records Prime upstream evidence and the decision taken for each over
 - Design: `Context.volatileContext` carries continual-harness state and the current date. The Anthropic provider appends it as the final content block after the `cache_control` breakpoint on the last history block, so the cached tools -> system -> history prefix is unchanged by a harness write or a date flip. The OpenAI-completions provider appends it after its Anthropic-style markers and after the automatically cached prefix of providers without markers. The API registry folds the content into the end of the message list for every other provider, so no provider can silently drop it. `AgentSession` pins each tool to the slot it first occupied, so a registry refresh or an extension reload serializes an unchanged tool set to identical bytes.
 - Behavior preservation: the harness-state section and the `Current date` line are byte-identical to what the system prompt previously inlined, including the empty-state rendering and the custom-prompt-only scope of the date. Only their position changed. The subagent guidance still precedes the harness-state roster in the assembled request.
 - Compatibility classification: **backward-compatible and additive**. `Context.volatileContext`, `AgentState.volatileContext`, `AgentLoopConfig.getVolatileContext`, and `ApiProvider.handlesVolatileContext` are all optional; a caller that sets none behaves exactly as before. No daemon command, event, protocol version, or schema revision changes.
-- Validation: 10 new `packages/ai` payload tests assert a byte-identical cached prefix across volatile changes for both the Anthropic and OpenAI-completions payload builders, correct marker placement, the trailing-user-message case, blank-input handling, and the registry fallback. 4 new `packages/coding-agent/test/suite/regressions/26-stable-cache-prefix.test.ts` cases assert an unchanged prefix across a mid-session harness memory write, an unchanged prefix across a mocked two-day clock advance, identical tool bytes across repeated registry refreshes, and first-activation tool-order pinning across reordering and removal. `test/system-prompt.test.ts` (25), the compaction, compact-skill, refine, runtime, queue, and prompt suites (357), `packages/agent` (60), and 13 focused `packages/ai` provider files (93 passed, 9 gated skips) are green. `npm run check` passes. `test/extensions-runner.test.ts` fails 21 cases identically on unmodified `origin/pylon`, so it is pre-existing and unrelated.
+- Validation: 15 `packages/ai` payload tests assert a byte-identical cached prefix across volatile changes for both the Anthropic and OpenAI-completions payload builders, correct marker placement, the trailing-user-message case, blank-input handling, and the registry fallback. 5 `packages/coding-agent/test/suite/regressions/26-stable-cache-prefix.test.ts` cases assert an unchanged prefix across a mid-session harness memory write, an unchanged prefix across a mocked two-day clock advance, identical tool bytes across repeated registry refreshes, first-activation tool-order pinning across reordering and removal, and — for an `appendOnlyHistory` model registered through `registerProvider` — an append-only history with the volatile content in the system prompt. `test/suite` (79 files, 960), `test/system-prompt.test.ts` (25), `test/model-registry.test.ts`, `test/agent-session-recursion.test.ts` (112), `packages/agent` (60), and 13 focused `packages/ai` provider files (93 passed, 9 gated skips) are green. `npm run check` passes. `test/extensions-runner.test.ts` fails 21 cases identically on unmodified `origin/pylon`, so it is pre-existing and unrelated.
+- Review correction — two placements, declared per model. The first candidate always used trailing placement, which regressed the Meridian proxy path from "cold cache when harness state or the date changes" to a full fresh replay every turn. Meridian's lineage matcher (`meridian/src/proxy/session/lineage.ts`) resumes an SDK session only when the incoming history matches the stored history; its boundary branch at `cached.messageCount - 1` tolerates a last-message block append only when every stored block hash is preserved and every appended block is a new `tool_result` (`hasOnlyNewToolResults`, deliberately narrow per Meridian #689/#692). A payload-only volatile text block fails that on the turn it appears, and on the next turn the stored boundary message holds more blocks than the incoming replay because the block was never persisted, so `incomingBlockHashes.length > storedBlocks.length` fails too. Classification falls through to `diverged: modified-history` and forces a full-history replay on the exact deployment #22 targets.
+- The fix is a declared per-model constraint, not a workaround. `Model.appendOnlyHistory` marks a backend that caches by session rather than by request prefix and therefore requires the request message array to stay byte-identical to the persisted history. When set, the API registry routes `volatileContext` into the system prompt and adds no payload-only message block; the backend's own session cache absorbs the system-prompt change. Default stays trailing placement, which is correct for direct prefix-cached APIs. The flag is settable from extension `registerProvider` model entries and from `models.json` model definitions and `modelOverrides`, and it is documented for extension authors in `packages/coding-agent/docs/extensions.md`.
 - Deferred: the optional debug-level prefix-drift check from issue #26 is not implemented. The regression tests assert the invariant directly, and a cross-turn byte comparison would need new mutable state inside otherwise pure prompt assembly.
 - Revisit when Prime upstream offers an equivalent provider-neutral channel that keeps mutable state and clock-derived content out of the cached prefix, and Pylon can drop the fork behavior without regressing measured cache-hit rates through a Claude-Max proxy.

packages/ai/.changes/stable-prompt-cache-prefix.md

@@ -1 +1,2 @@
 - Added `Context.volatileContext` for content that must stay out of every cached prompt prefix; Anthropic and OpenAI-completions place it after their cache breakpoints and other providers receive it appended to the message list ([#26](https://github.com/pylon-code/prime-agent/issues/26)).
+- Added the `Model.appendOnlyHistory` flag for session-cached backends, which routes volatile content into the system prompt so the request message array stays byte-identical to the persisted history ([#26](https://github.com/pylon-code/prime-agent/issues/26)).

packages/ai/README.md

@@ -997,6 +997,16 @@ The model still sees it, but never inside a cached region:
 - Anthropic and OpenAI-completions append it after their `cache_control` breakpoints, so the cached tools, system prompt, and conversation history are unaffected when it changes.
 - Every other provider receives it appended to the end of `Context.messages`, which is after the automatically cached prefix. Set `handlesVolatileContext: true` when registering a custom provider that positions the content itself.
 
+### Session-cached backends
+
+Trailing placement assumes the backend caches by request prefix. A proxy in front of an agent SDK does not: it matches the incoming message array against the history it already holds and resumes that session, so a payload-only trailing block reads as a modified history and forces a full replay.
+
+Set `appendOnlyHistory: true` on those models. The volatile content then goes into the system prompt and the message array stays byte-identical to the caller's history:
+
+```typescript
+const model = { ...getModel('anthropic', 'claude-opus-4-6'), baseUrl: 'https://my-sdk-proxy.example.com', appendOnlyHistory: true };
+```
+
 ## Context Serialization
 
 The `Context` object can be easily serialized and deserialized using standard JSON methods, making it simple to persist conversations, implement chat history, or transfer contexts between services:

packages/ai/src/api-registry.ts

@@ -7,7 +7,7 @@ import type {
 	StreamFunction,
 	StreamOptions,
 } from "./types.js";
-import { foldVolatileContext } from "./utils/volatile-context.js";
+import { foldVolatileContext, foldVolatileContextIntoSystemPrompt } from "./utils/volatile-context.js";
 
 export type ApiStreamFunction = (
 	model: Model<Api>,
@@ -46,6 +46,20 @@ type RegisteredApiProvider = {
 
 const apiProviderRegistry = new Map<string, RegisteredApiProvider>();
 
+/**
+ * Decide where `Context.volatileContext` goes before the provider sees it.
+ *
+ * Prefix-cached backends want it after the last cache breakpoint, which the
+ * provider places. Session-cached `appendOnlyHistory` backends need the message
+ * array untouched, so it goes into the system prompt instead.
+ */
+function resolveVolatilePlacement(model: Model<Api>, context: Context, handlesVolatileContext: boolean): Context {
+	if (model.appendOnlyHistory) {
+		return foldVolatileContextIntoSystemPrompt(context);
+	}
+	return handlesVolatileContext ? context : foldVolatileContext(context);
+}
+
 function wrapStream<TApi extends Api, TOptions extends StreamOptions>(
 	api: TApi,
 	stream: StreamFunction<TApi, TOptions>,
@@ -55,7 +69,7 @@ function wrapStream<TApi extends Api, TOptions extends StreamOptions>(
 		if (model.api !== api) {
 			throw new Error(`Mismatched api: ${model.api} expected ${api}`);
 		}
-		const resolved = handlesVolatileContext ? context : foldVolatileContext(context);
+		const resolved = resolveVolatilePlacement(model, context, handlesVolatileContext);
 		return stream(model as Model<TApi>, resolved, options as TOptions);
 	};
 }
@@ -69,7 +83,7 @@ function wrapStreamSimple<TApi extends Api>(
 		if (model.api !== api) {
 			throw new Error(`Mismatched api: ${model.api} expected ${api}`);
 		}
-		const resolved = handlesVolatileContext ? context : foldVolatileContext(context);
+		const resolved = resolveVolatilePlacement(model, context, handlesVolatileContext);
 		return streamSimple(model as Model<TApi>, resolved, options);
 	};
 }

packages/ai/src/types.ts

@@ -462,6 +462,17 @@ export interface Model<TApi extends Api> {
 	maxTokens: number;
 	/** Flagship model surfaced above non-featured models of the same provider in pickers. */
 	featured?: boolean;
+	/**
+	 * Set when the backend keeps its own session cache keyed on the request message
+	 * array, so that array must stay byte-identical to the conversation history the
+	 * client persisted — a proxy in front of an agent SDK, for example.
+	 *
+	 * `Context.volatileContext` then goes into the system prompt instead of the end
+	 * of the message list, because a payload-only message block breaks the backend's
+	 * lineage matching and forces a full-history replay on every request. The
+	 * backend's own session cache absorbs the system-prompt change instead.
+	 */
+	appendOnlyHistory?: boolean;
 	headers?: Record<string, string>;
 	/** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
 	compat?: TApi extends "openai-completions"

packages/ai/src/utils/volatile-context.ts

@@ -27,3 +27,21 @@ export function foldVolatileContext(context: Context): Context {
 	const messages: Message[] = [...context.messages, trailing];
 	return { ...context, messages, volatileContext: undefined };
 }
+
+/**
+ * Move volatile content to the end of the system prompt, leaving the message
+ * list byte-identical to the caller's history.
+ *
+ * Used for `Model.appendOnlyHistory` backends. They cache by session rather than
+ * by prefix, so a system-prompt change costs one re-send while a payload-only
+ * message block would invalidate their whole history lineage.
+ */
+export function foldVolatileContextIntoSystemPrompt(context: Context): Context {
+	const text = resolveVolatileContext(context);
+	if (!text) {
+		return context.volatileContext === undefined ? context : { ...context, volatileContext: undefined };
+	}
+
+	const systemPrompt = context.systemPrompt ? `${context.systemPrompt}\n\n${text}` : text;
+	return { ...context, systemPrompt, volatileContext: undefined };
+}

packages/ai/test/volatile-context-cache-prefix.test.ts

@@ -263,6 +263,35 @@ describe("Anthropic volatile context placement", () => {
 		const payload = await captureAnthropicPayload("   \n  ");
 		expect(flattenParts(payload.messages[payload.messages.length - 1])).toHaveLength(1);
 	});
+
+	it("sends volatile context in the system prompt for an appendOnlyHistory model", async () => {
+		const model: Model<"anthropic-messages"> = {
+			...getModel("anthropic", "claude-sonnet-4-5"),
+			baseUrl: "http://127.0.0.1:9",
+			appendOnlyHistory: true,
+		};
+		const source = baseContext("# Continual Harness State\n\nmemory: 1");
+		let captured: CapturedPayload | undefined;
+		// Routed through the registry, which owns the placement decision.
+		await streamSimple(model, source, {
+			apiKey: "fake-key",
+			maxRetries: 0,
+			onPayload: (payload) => {
+				captured = payload as CapturedPayload;
+				return payload;
+			},
+		}).result();
+
+		if (!captured) throw new Error("Expected the Anthropic payload to be captured");
+		expect(JSON.stringify(captured.system)).toContain("Continual Harness State");
+
+		// No payload-only block: the message array still matches the caller's history.
+		const parts = flattenParts(captured.messages[captured.messages.length - 1]);
+		expect(parts).toHaveLength(1);
+		expect(parts[0]?.text).toBe("second");
+		expect(parts[0]?.cache_control).toEqual({ type: "ephemeral" });
+		expect(captured.messages).toHaveLength(source.messages.length);
+	});
 });
 
 describe("OpenAI-completions volatile context placement", () => {
@@ -356,6 +385,36 @@ describe("volatile context handling at the provider registry", () => {
 		expect(contexts[0].messages).toHaveLength(baseContext().messages.length);
 	});
 
+	it("routes volatile context into the system prompt for appendOnlyHistory models", () => {
+		for (const handlesVolatileContext of [true, false]) {
+			const api = handlesVolatileContext ? "native-api" : "fallback-api";
+			const { contexts, model } = recordingProvider(api, handlesVolatileContext);
+			const source = baseContext("# Continual Harness State\n\nmemory: 1");
+
+			streamSimple({ ...model, appendOnlyHistory: true }, source);
+
+			expect(contexts).toHaveLength(1);
+			const received = contexts[0];
+			expect(received.volatileContext).toBeUndefined();
+			// A session-cached backend matches on the message array, so it must be
+			// byte-identical to the caller's persisted history.
+			expect(JSON.stringify(received.messages)).toBe(JSON.stringify(source.messages));
+			expect(received.systemPrompt).toBe(
+				"You are a general purpose agent.\n\n# Continual Harness State\n\nmemory: 1",
+			);
+			unregisterApiProviders(api);
+		}
+	});
+
+	it("uses the volatile content as the system prompt when an appendOnlyHistory model has none", () => {
+		const { contexts, model } = recordingProvider("native-api", true);
+
+		streamSimple({ ...model, appendOnlyHistory: true }, { messages: [], volatileContext: "memory: 1" });
+
+		expect(contexts[0].systemPrompt).toBe("memory: 1");
+		expect(contexts[0].messages).toHaveLength(0);
+	});
+
 	it("keeps volatile content out of the faux provider's simulated cache prefix", async () => {
 		const faux = registerFauxProvider();
 		try {

packages/coding-agent/.changes/stable-prompt-cache-prefix.md

@@ -1,2 +1,3 @@
 - Fixed prompt-cache churn by sending continual harness state and the current date outside the cached prompt prefix, so a harness refinement or a midnight date flip no longer re-caches a long-running session ([#26](https://github.com/pylon-code/prime-agent/issues/26)).
 - Pinned each tool to the slot it first occupied so a tool-registry refresh serializes an unchanged tool set to identical bytes ([#26](https://github.com/pylon-code/prime-agent/issues/26)).
+- Added the `appendOnlyHistory` model flag so proxy-backed providers registered by extensions keep an append-only request history and receive volatile prompt content in the system prompt ([#26](https://github.com/pylon-code/prime-agent/issues/26)).

packages/coding-agent/docs/extensions.md

@@ -1648,6 +1648,34 @@ pi.registerProvider("corporate-ai", {
 - `oauth` - OAuth provider config for `/login` support. When provided, the provider appears in the login menu.
 - `streamSimple` - Custom streaming implementation for non-standard APIs.
 
+**Model definitions: `appendOnlyHistory`**
+
+Set `appendOnlyHistory: true` on a model when the backend keeps its own session cache keyed on the request message array, rather than caching by request prefix. Proxies in front of an agent SDK work this way: they match the incoming history against the history they already hold and resume that session, so they only tolerate an append.
+
+The flag controls where Prime Agent puts volatile prompt content — continual harness state and the current date. By default that content is appended after the message list so a change cannot invalidate a prefix cache. A session-cached backend reads the same append as a modified history and replays the whole conversation instead, so the flag routes the content into the system prompt and leaves the message array byte-identical to the persisted conversation.
+
+```typescript
+pi.registerProvider("my-sdk-proxy", {
+  baseUrl: "https://proxy.example.com",
+  apiKey: "PROXY_API_KEY",
+  api: "anthropic-messages",
+  models: [
+    {
+      id: "claude-opus-4-6",
+      name: "Claude Opus 4.6 (via SDK proxy)",
+      reasoning: true,
+      input: ["text", "image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 32000,
+      appendOnlyHistory: true
+    }
+  ]
+});
+```
+
+Leave it unset for direct provider APIs, including Anthropic and OpenAI-compatible endpoints that cache by prefix. `models.json` accepts the same field on a model definition or a `modelOverrides` entry.
+
 See [custom-provider.md](custom-provider.md) for advanced topics: custom streaming APIs, OAuth details, model definition reference.
 
 ### pi.unregisterProvider(name)