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

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';
@@ -671,7 +675,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',
@@ -681,6 +685,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 {