feat(agent-core-v2): report fork request prefix parity in the prompt cache probe (#4179)

* feat(agent-core-v2): report fork request prefix parity in the prompt cache probe

The fork prompt cache probe only reported the child's cache usage, so a low
hit rate could not be told apart between a client-side prefix divergence and
a server-side miss, and the hit rate itself was diluted by the new tail that
can never be cached.

The requester now keeps a snapshot of each agent's last completed turn
request (the tools and system prompt hashes it already records in
llm.request, input tokens and timing). A forked agent captures its parent's
snapshot when it is created and reports tools_match, system_prompt_match,
parent_input_tokens and parent_request_gap_ms with its first request.

* fix(agent-core-v2): clear the parent request snapshot when the context is rewritten

Undo and compaction rewrite the parent context without touching the
non-persisted snapshot, so a /btw fork made before the next turn request
compared against a request whose input the child no longer inherits.

* fix(agent-core-v2): drop stale parent baselines from the fork cache probe

The probe compared the child's first request against the parent snapshot
captured at scope creation, but a parent undo or compaction landing
before the context copy left that snapshot describing a request the
child no longer inherits, and a model switch between the parent's last
turn and the fork compared across cache namespaces that can never share
a prompt cache.

The probe now watches the parent's ContextSpliced/ContextUndone events
and drops the captured snapshot once the parent context is rewritten,
and the snapshot carries the model alias so the comparison fields and
the parent input token baseline are only reported when both sides ran
the same model.

* fix(agent-core-v2): keep the turn request snapshot across conversation undo

Undo only truncates the tail of the parent context, so the request a
/btw fork inherits is still a strict prefix of the request the parent
last cached: the server cache keeps hitting and the snapshot's hashes
stay accurate. Clearing the snapshot on undo threw away a baseline
that was still valid, and made the requester depend on the undo
domain for no benefit. Only compaction rewrites the prefix, so it
remains the sole event that clears the snapshot.

* refactor(agent-core-v2): validate the fork cache probe baseline by context prefix revision

The requester subscribed to ContextSpliced solely to keep a telemetry
snapshot fresh, which made the module understand context rewrites and
grow an event bus dependency for the probe's sake. The probe's own
subscription could not cover forks created after a compaction either,
which is the only reason the requester had to listen at all.

Context memory now exposes a prefix revision that increments on every
deleting splice, the turn request snapshot records the revision it was
taken at, and the probe compares it with the parent's current revision
at probe time. Read-time validation covers both the compact-then-fork
and the fork-then-compact windows with no subscriptions, and the
requester is back to only recording facts about its own requests.

* fix(agent-core-v2): stamp the turn request snapshot with the build-time context revision

The public SDK clearContext path has no busy check and can empty the
parent context while a turn request is in flight. Reading the revision
at completion stamped the snapshot with the post-clear value, so a
later fork saw matching revisions and hashes and silently attributed
the client-side prefix divergence to the server. The request input is
fixed by recordRequest time, so capture the revision in the same
synchronous block; a mid-flight clear then leaves the snapshot on the
pre-clear revision and the probe drops the baseline on comparison.

* fix(agent-core-v2): capture the snapshot context revision where the request messages are copied

The build-time capture still ran after the awaited media resolution,
so a clearContext or compaction landing in that window stamped the
snapshot with the post-rewrite revision for a request whose messages
were copied earlier. resolveRequest is synchronous and copies the
context messages there, so the revision captured alongside the copy
always describes the same context the request was built from.

* fix(agent-core-v2): omit the parent token baseline when the parent request reported no usage

A provider that completes without a usage event left the snapshot with
inputTokens: 0, so a later same-model fork emitted parent_input_tokens: 0
and the input_cache_read / parent_input_tokens analysis divided by zero
or treated an unknown baseline as real. The field is now optional and
absent for that snapshot, which the optional telemetry property already
allows.

Author: 7Sageer

packages/agent-core-v2/docs/state-manifest.d.ts

@@ -27,7 +27,7 @@
 // references become '(circular)', and class instances collapse to a '(ClassName)'
 // marker — the wire shape of an entry is the JSON projection of the type here.
 //
-// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 72 keys)
+// Index (App: 0 keys · Workspace: 6 keys · Session: 9 keys · Agent: 73 keys)
 //   App
 //   Workspace
 //     workspaceDirs.ephemeralDirs          src/workspace/workspaceDirs/workspaceDirsService.ts
@@ -66,6 +66,7 @@
 //     llm.requestTrace                                src/agent/llmRequester/llmRequestOps.ts
 //     llmRequester.emittedThinkingEffortWarnings      src/agent/llmRequester/llmRequesterService.ts
 //     llmRequester.lastConfigLogSignature             src/agent/llmRequester/llmRequesterService.ts
+//     llmRequester.lastTurnRequest                    src/agent/llmRequester/llmRequesterService.ts
 //     llmRequester.mediaDegradedTurns                 src/agent/llmRequester/llmRequesterService.ts
 //     llmRequester.mediaStrippedTurns                 src/agent/llmRequester/llmRequesterService.ts
 //     llmRequester.turnConfigs                        src/agent/llmRequester/llmRequesterService.ts
@@ -972,6 +973,15 @@ export interface AgentStateSnapshot {
   // src/agent/llmRequester/llmRequesterService.ts
   'llmRequester.emittedThinkingEffortWarnings': Set<string>;
   'llmRequester.lastConfigLogSignature': string | undefined;
+  'llmRequester.lastTurnRequest': /* AgentLLMTurnRequestSnapshot — packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts */ {
+    readonly modelAlias: string;
+    readonly contextRevision: number;
+    readonly toolsHash: string;
+    readonly systemPromptHash: string;
+    readonly inputTokens?: number;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+  } | undefined;
   'llmRequester.mediaDegradedTurns': Set<number>;
   'llmRequester.mediaStrippedTurns': Map<number, /* MediaStripSnapshot — packages/agent-core-v2/src/agent/contextProjector/contextProjector.ts */ {
     readonly "__@mediaStripSnapshotBrand": undefined;

packages/agent-core-v2/src/agent/contextMemory/contextMemory.ts

@@ -34,6 +34,8 @@ export interface IAgentContextMemoryService {
 
   get(): readonly ContextMessage[];
 
+  prefixRevision(): number;
+
   append(...messages: readonly ContextMessage[]): void;
 
   appendLoopEvent(event: LoopRecordedEvent): void;

packages/agent-core-v2/src/agent/contextMemory/contextMemoryService.ts

@@ -27,6 +27,8 @@ import type { ContextMessage } from './types';
 export class AgentContextMemoryService extends Disposable implements IAgentContextMemoryService {
   declare readonly _serviceBrand: undefined;
 
+  private revision = 0;
+
   constructor(
     @IEventDispatcher private readonly dispatcher: IEventDispatcher,
     @IAgentScopeContext private readonly scopeContext: IAgentScopeContext,
@@ -49,6 +51,10 @@ export class AgentContextMemoryService extends Disposable implements IAgentConte
     return this.agentState.get(contextMemoryKey) as readonly ContextMessage[];
   }
 
+  prefixRevision(): number {
+    return this.revision;
+  }
+
   append(...messages: readonly ContextMessage[]): void {
     if (messages.length === 0) return;
     const start = this.get().length;
@@ -128,6 +134,7 @@ export class AgentContextMemoryService extends Disposable implements IAgentConte
   }
 
   private publishSplice(input: Omit<ContextSplicedPayload, 'agentId'>): void {
+    if (input.deleteCount > 0) this.revision += 1;
     void this.dispatcher.dispatch(
       new ContextSpliced({ agentId: this.scopeContext.agentId, ...input }),
     );

packages/agent-core-v2/src/agent/llmRequester/llmRequester.ts

@@ -56,6 +56,16 @@ export interface PreparedTurnRequestConfig {
   readonly thinkingEffort: ThinkingEffort;
 }
 
+export interface AgentLLMTurnRequestSnapshot {
+  readonly modelAlias: string;
+  readonly contextRevision: number;
+  readonly toolsHash: string;
+  readonly systemPromptHash: string;
+  readonly inputTokens?: number;
+  readonly startedAt: number;
+  readonly finishedAt: number;
+}
+
 export interface IAgentLLMRequesterService {
   readonly _serviceBrand: undefined;
 
@@ -65,6 +75,8 @@ export interface IAgentLLMRequesterService {
 
   credentialProviderForTurn(turnId: number): LlmCredentialProvider | undefined;
 
+  lastTurnRequest(): AgentLLMTurnRequestSnapshot | undefined;
+
   request(
     overrides?: AgentLLMRequestOverrides,
     onPart?: AgentLLMRequestPartHandler,

packages/agent-core-v2/src/agent/llmRequester/llmRequesterService.ts

@@ -62,6 +62,7 @@ import {
   type AgentLLMRequestPartHandler,
   type AgentLLMRequestSource,
   type AgentLLMRequestTask,
+  type AgentLLMTurnRequestSnapshot,
   type PreparedTurnRequestConfig,
 } from './llmRequester';
 import type { LLMRequestTrace } from '#/llm-adapter/contract/request-trace';
@@ -105,6 +106,7 @@ interface ResolvedLLMRequest {
   readonly systemPrompt: string;
   readonly tools: readonly Tool[];
   readonly messages: Message[];
+  readonly contextRevision: number;
   readonly source: AgentLLMRequestSource | undefined;
   readonly logFields: AgentLLMRequestLogFields;
 }
@@ -148,6 +150,10 @@ export const llmRequesterEmittedThinkingEffortWarningsKey = defineState<Set<stri
   'llmRequester.emittedThinkingEffortWarnings',
   () => new Set(),
 );
+export const llmRequesterLastTurnRequestKey = defineState<AgentLLMTurnRequestSnapshot | undefined>(
+  'llmRequester.lastTurnRequest',
+  () => undefined as AgentLLMTurnRequestSnapshot | undefined,
+);
 
 export class AgentLLMRequesterService implements IAgentLLMRequesterService {
   declare readonly _serviceBrand: undefined;
@@ -179,6 +185,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     this.states.contributeState(llmRequesterMediaDegradedTurnsKey);
     this.states.contributeState(llmRequesterMediaStrippedTurnsKey);
     this.states.contributeState(llmRequesterEmittedThinkingEffortWarningsKey);
+    this.states.contributeState(llmRequesterLastTurnRequestKey);
   }
 
   private get lastConfigLogSignature(): string | undefined {
@@ -222,6 +229,10 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     return this.modelCatalog.get(resolved.modelAlias).credentialProvider;
   }
 
+  lastTurnRequest(): AgentLLMTurnRequestSnapshot | undefined {
+    return this.states.get(llmRequesterLastTurnRequestKey);
+  }
+
   async request(
     overrides: AgentLLMRequestOverrides = {},
     onPart: AgentLLMRequestPartHandler = noopOnPart,
@@ -413,7 +424,8 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
         fields,
       };
       this.logRequest(logInput);
-      this.recordRequest(logInput);
+      const recorded = this.recordRequest(logInput);
+      const startedAt = Date.now();
 
       let message: Message | undefined;
       let usage: TokenUsage | undefined;
@@ -474,6 +486,17 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
         throw error;
       }
 
+      if (request.source?.type === 'turn') {
+        this.states.set(llmRequesterLastTurnRequestKey, {
+          modelAlias: request.modelAlias,
+          contextRevision: request.contextRevision,
+          toolsHash: recorded.toolsHash,
+          systemPromptHash: recorded.systemPromptHash,
+          inputTokens: usage === undefined ? undefined : inputTotal(usage),
+          startedAt,
+          finishedAt: Date.now(),
+        });
+      }
       void this.usage.record(
         this.scopeContext.agentContext,
         request.modelAlias,
@@ -723,6 +746,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
       systemPrompt: overrides.systemPrompt ?? turnConfig?.systemPrompt ?? this.profile.getSystemPrompt(),
       tools: [...(overrides.tools ?? this.defaultTools())],
       messages: [...messages],
+      contextRevision: this.context.prefixRevision(),
       source: overrides.source,
       logFields: logFieldsForSource(overrides.source),
     };
@@ -776,7 +800,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
     this.log.info('llm request', requestFields);
   }
 
-  private recordRequest(input: LLMRequestLogInput): void {
+  private recordRequest(input: LLMRequestLogInput): LlmRequestPayload {
     const fields = input.fields ?? {};
     const wireTools = providerVisibleTools(input.tools);
     const tools = toolSignature(wireTools);
@@ -822,6 +846,7 @@ export class AgentLLMRequesterService implements IAgentLLMRequesterService {
       droppedCount: numberField(fields, 'droppedCount'),
     };
     void this.dispatcher.dispatch(new LlmRequest(payload));
+    return payload;
   }
 
   private logResponse(

packages/agent-core-v2/src/agent/usage/cacheProbeService.ts

@@ -1,10 +1,17 @@
+import { IInstantiationService } from '#/_base/di/instantiation';
 import { Service } from '#/_base/di/service';
 import { ScopeActivation, registerScopedService } from '#/_base/di/scope';
 import { LifecycleScope } from '#/app/scopes';
+import { IAgentContextMemoryService } from '#/agent/contextMemory/contextMemory';
+import {
+  IAgentLLMRequesterService,
+  type AgentLLMTurnRequestSnapshot,
+} from '#/agent/llmRequester/llmRequester';
 import { IAgentScopeContext } from '#/agent/scopeContext/scopeContext';
 import { ITelemetryService } from '#/app/telemetry/telemetry';
 import { inputTotal } from '#human/llm/usage';
 import { IModelCatalog } from '#/llm-adapter/model/catalog';
+import { IAgentLifecycleService } from '#/session/agentLifecycle/agentLifecycle';
 import { ISessionUsageService } from '#/session/usage/sessionUsage';
 
 import { IAgentCacheProbeService } from './cacheProbe';
@@ -13,14 +20,25 @@ import { type UsageRecordedContext } from './usage';
 export class AgentCacheProbeService extends Service implements IAgentCacheProbeService {
   declare readonly _serviceBrand: undefined;
 
+  private parentId: string | undefined;
+
+  private parentRequest: AgentLLMTurnRequestSnapshot | undefined;
+
   constructor(
     @ISessionUsageService usage: ISessionUsageService,
     @IAgentScopeContext scopeContext: IAgentScopeContext,
     @ITelemetryService private readonly telemetry: ITelemetryService,
     @IModelCatalog private readonly models: IModelCatalog,
+    @IInstantiationService private readonly instantiation: IInstantiationService,
+    @IAgentLifecycleService private readonly agentLifecycle: IAgentLifecycleService,
   ) {
     super();
     if (scopeContext.forkedFrom === undefined) return;
+    this.parentId = scopeContext.forkedFrom;
+    this.parentRequest = agentLifecycle
+      .handleOf(this.parentId)
+      ?.accessor.get(IAgentLLMRequesterService)
+      .lastTurnRequest();
     this._register(
       usage.onDidRecord((e) => {
         if (e.agent.agentId === scopeContext.agentId) this.probe(e);
@@ -30,13 +48,29 @@ export class AgentCacheProbeService extends Service implements IAgentCacheProbeS
 
   private probe(e: UsageRecordedContext): void {
     if (!e.firstRecord || e.source?.type !== 'turn') return;
+    const parentRevision =
+      this.parentId === undefined
+        ? undefined
+        : this.agentLifecycle
+            .handleOf(this.parentId)
+            ?.accessor.get(IAgentContextMemoryService)
+            .prefixRevision();
+    const parent =
+      this.parentRequest !== undefined && this.parentRequest.contextRevision === parentRevision
+        ? this.parentRequest
+        : undefined;
     let providerType: string | undefined;
     let protocol: string | undefined;
     try {
       const model = this.models.get(e.model);
       providerType = model.providerType ?? model.protocol;
       protocol = model.protocol;
     } catch { }
+    const own = this.instantiation
+      .invokeFunction((accessor) => accessor.get(IAgentLLMRequesterService))
+      .lastTurnRequest();
+    const sameModel = parent !== undefined && parent.modelAlias === e.model;
+    const compared = sameModel && own !== undefined;
     this.telemetry.track2('prompt_cache_probe', {
       source: 'fork',
       turn_id: e.source.turnId,
@@ -46,6 +80,10 @@ export class AgentCacheProbeService extends Service implements IAgentCacheProbeS
       input_cache_read: e.usage.inputCacheRead,
       input_cache_creation: e.usage.inputCacheCreation,
       output_tokens: e.usage.output,
+      tools_match: compared ? own.toolsHash === parent.toolsHash : undefined,
+      system_prompt_match: compared ? own.systemPromptHash === parent.systemPromptHash : undefined,
+      parent_input_tokens: sameModel ? parent?.inputTokens : undefined,
+      parent_request_gap_ms: compared ? own.startedAt - parent.finishedAt : undefined,
     });
   }
 }

packages/agent-core-v2/src/app/telemetry/events.ts

@@ -96,6 +96,10 @@ export interface PromptCacheProbeEvent {
   input_cache_read: number;
   input_cache_creation: number;
   output_tokens: number;
+  tools_match?: boolean;
+  system_prompt_match?: boolean;
+  parent_input_tokens?: number;
+  parent_request_gap_ms?: number;
 }
 
 export type ToolCallOutcome = 'success' | 'error' | 'cancelled';
@@ -672,7 +676,7 @@ export const telemetryEventDefinitions = {
   prompt_cache_probe: defineAgentTelemetryEvent<PromptCacheProbeEvent>({
     owner: 'kimi-code',
     comment:
-      'An agent whose first request is expected to hit the prompt cache reports that request\'s cache usage.',
+      'An agent whose first request is expected to hit the prompt cache reports that request\'s cache usage and how its prefix compares with the last turn request the parent agent completed before the fork.',
     properties: {
       source: 'Why a cache hit was expected for this request',
       turn_id: 'Per-agent turn index of the probed request',
@@ -682,6 +686,14 @@ export const telemetryEventDefinitions = {
       input_cache_read: 'Cache-read input tokens of the probed request',
       input_cache_creation: 'Cache-creation input tokens of the probed request',
       output_tokens: 'Output tokens of the probed request',
+      tools_match:
+        "Whether the provider-visible tool table hash equals the parent's; absent when the parent completed no turn request before the fork, or its context was rewritten (undo, compaction) after the last one",
+      system_prompt_match:
+        "Whether the system prompt hash equals the parent's; absent when the parent completed no turn request before the fork, or its context was rewritten (undo, compaction) after the last one",
+      parent_input_tokens:
+        "Total input tokens of the parent's last completed turn request before the fork, i.e. the prefix this request could read from the cache; absent when there is none, or the parent's context was rewritten (undo, compaction) after it",
+      parent_request_gap_ms:
+        "Milliseconds from the parent's last completed turn request finishing to the probed request starting; absent when the parent completed no turn request before the fork, or its context was rewritten (undo, compaction) after the last one",
     },
   }),
   tool_call: defineAgentTelemetryEvent<ToolCallEvent>({

packages/agent-core-v2/test/agent/contextMemory/stubs.ts

@@ -43,12 +43,14 @@ function publishSplice(
 
 export function stubContextMemory(eventBus?: IEventBus): StubContextMemory {
   const messages: ContextMessage[] = [];
+  let revision = 0;
   return {
     _serviceBrand: undefined,
     get messages() {
       return messages;
     },
     get: () => [...messages],
+    prefixRevision: () => revision,
     append: (...inserted) => {
       const start = messages.length;
       messages.push(...inserted);
@@ -60,13 +62,15 @@ export function stubContextMemory(eventBus?: IEventBus): StubContextMemory {
       const deleteCount = messages.length;
       if (deleteCount === 0) return;
       messages.splice(0, deleteCount);
+      revision += 1;
       publishSplice(eventBus, { start: 0, deleteCount, messages: [] });
     },
     undo: (count) => {
       const cut = computeUndoCut(messages, count);
       if (cut.cutIndex >= 0 && cut.removedCount >= count) {
         const deleteCount = messages.length - cut.cutIndex;
         messages.splice(cut.cutIndex, deleteCount);
+        revision += 1;
         publishSplice(eventBus, { start: cut.cutIndex, deleteCount, messages: [] });
       }
       return cut;
@@ -75,6 +79,7 @@ export function stubContextMemory(eventBus?: IEventBus): StubContextMemory {
       const shape = buildContextCompactionShape(messages, input);
       const previousLength = messages.length;
       messages.splice(0, previousLength, ...shape.messages);
+      if (previousLength > 0) revision += 1;
       publishSplice(eventBus, {
         start: 0,
         deleteCount: previousLength,
@@ -115,6 +120,9 @@ class StubContextMemoryService implements IAgentContextMemoryService {
   applyCompaction(input: ContextCompactionInput): ContextCompactionResult {
     return this.impl.applyCompaction(input);
   }
+  prefixRevision(): number {
+    return this.impl.prefixRevision();
+  }
 }
 
 export function registerContextMemoryServices(reg: ServiceRegistration): void {