Merge branch 'main' into proj/curate-dag-cutover (re-merge after PR #601)

Brings in main's PR #601 (Proj/curation enhancement, db6560e) which
restructured the post-curate flow:

- ENG-2485: Phase 4 propagation deferred to dream — curate now ENQUEUES
  stale-summary paths via DreamStateService.enqueueStaleSummaryPaths and
  rebuilds the manifest inline; the LLM-driven propagateStaleness walk
  no longer runs on the curate hot path.
- ENG-2530: pre-pipelined recon for the agent-loop path (a deterministic
  helper invocation that skips one full LLM iteration).
- ENG-2518: batched abstract generation across queued files.

Conflicts resolved (2 files):

- src/server/infra/executor/curate-executor.ts (2 hunks)
  * Imports: kept HEAD's typed-slot DAG runner imports
    (TopologicalCurationRunner, NodeContext, buildCurationDAG,
    loadExistingMemory, buildLiveServices). Dropped main's
    `recon as reconHelper` import — our DAG already has a recon-node
    that runs deterministically as the first slot, so PR #601's
    pre-pipelined reconHelper for the agent-loop path is redundant.
  * Body: kept HEAD's typed-slot DAG runner (PR #578) inside the
    runAgentBody/finalize split. Adopted main's `propagateAndRebuild`
    helper (auto-merged from main) for the finalize thunk —
    enqueueStaleSummaryPaths + buildManifest, no inline propagateStaleness.

- test/unit/infra/executor/curate-executor.test.ts
  * Response assertions updated to match the typed-slot DAG output
    (`/Curate completed via typed-slot DAG/`) instead of `'curated'`.
  * Phase-4 lifecycle assertions adopted from main (enqueueStub +
    buildManifestStub + propagateStalenessStub.called === false) —
    confirming ENG-2485 invariant.
  * Dropped the obsolete "pre-pipelined recon (ENG-2530)" describe
    block — the typed-slot DAG runs recon as a node, not via sandbox-
    variable injection. DAG-recon coverage lives in
    test/unit/agent/curate-flow/dag-builder.test.ts.
  * Dropped the "dream-lock coordination in Phase 4" describe block —
    propagation moved to dream itself (ENG-2485), so the lock dance
    no longer happens on the curate path.

Verification post-merge
- typecheck: 0 errors.
- 212/212 curate-related tests passing across:
  * test/unit/infra/executor/curate-executor.test.ts (all split + leak + scoping tests)
  * test/integration/curate/services-adapter-live-write.test.ts (Phase A+B prefix-cluster + batching)
  * test/unit/agent/curate-flow/*.test.ts
  * test/integration/curate/*.test.ts
  * test/unit/agent/tools/curate-tool*.test.ts
  * test/unit/infra/process/curate-log-handler.test.ts
- lint: 0 errors on changed files.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ngduyanhece

src/agent/infra/agent/service-initializer.ts

@@ -193,12 +193,18 @@ export async function createCipherAgentServices(
     basePath: promptsBasePath,
     validateConfig: true,
   })
-  // Register default contributors
+  // Register default contributors.
+  //
+  // Note: dateTime is intentionally NOT in the system prompt. Anthropic
+  // prompt caching does token-level prefix matching, so a per-iteration
+  // refreshed timestamp here would invalidate the cache for everything
+  // past it. dateTime is instead injected into the first user message
+  // by AgentLLMService, where it lives after the cache breakpoints and
+  // does not poison the cached prefix.
   systemPromptManager.registerContributors([
     {enabled: true, filepath: 'system-prompt.yml', id: 'base', priority: 0, type: 'file'},
     {enabled: true, id: 'env', priority: 10, type: 'environment'},
     {enabled: true, id: 'memories', priority: 20, type: 'memory'},
-    {enabled: true, id: 'datetime', priority: 30, type: 'dateTime'},
   ])
 
   // Register context tree structure contributor for query/curate commands

src/agent/infra/llm/agent-llm-service.ts

@@ -60,6 +60,18 @@ import {type ProcessedOutput, ToolOutputProcessor, type TruncationConfig} from '
 /** Target utilization ratio for message tokens (leaves headroom for response) */
 const TARGET_MESSAGE_TOKEN_UTILIZATION = 0.7
 
+/**
+ * Build a `<dateTime>...</dateTime>\n\n` prefix for a user-message body.
+ *
+ * Per-call timestamps must NOT enter the system prompt (they would poison
+ * the prefix cache). They are injected into the user message instead, at
+ * the boundaries where the model legitimately needs fresh time context:
+ * the iter-0 input, and after a rolling-checkpoint history clear.
+ */
+export function buildDateTimePrefix(now: Date = new Date()): string {
+  return `<dateTime>Current date and time: ${now.toISOString()}</dateTime>\n\n`
+}
+
 /**
  * Result of parallel tool execution (before adding to context).
  * Contains all information needed to add the result to context in order.
@@ -902,8 +914,11 @@ export class AgentLLMService implements ILLMService {
       this.cachedBasePrompt = basePrompt
       this.memoryDirtyFlag = false
     } else {
-      // Cache hit: reuse base prompt, only refresh the DateTime section
-      basePrompt = this.refreshDateTime(this.cachedBasePrompt!)
+      // Cache hit: reuse base prompt verbatim. The cached prompt has no
+      // dateTime section to refresh — dateTime is injected into the
+      // first user message instead so the system prefix stays byte-stable
+      // across iterations and prompt caching can engage cleanly.
+      basePrompt = this.cachedBasePrompt!
     }
 
     let systemPrompt = basePrompt
@@ -944,9 +959,13 @@ export class AgentLLMService implements ILLMService {
 
     // Add user message and compress context within mutex lock
     return this.mutex.withLock(async () => {
-      // Add user message to context only on the first iteration
+      // Add user message to context only on the first iteration. The
+      // dateTime block is prefixed here (not in the system prompt) so
+      // the cached system prefix stays byte-stable across iterations
+      // and Anthropic/OpenAI/Google prefix caches can engage cleanly.
       if (iterationCount === 0) {
-        await this.contextManager.addUserMessage(textInput, imageData, fileData)
+        const inputWithDateTime = `${buildDateTimePrefix()}${textInput}`
+        await this.contextManager.addUserMessage(inputWithDateTime, imageData, fileData)
       }
 
       // Rolling checkpoint: periodically save progress and clear history for RLM commands.
@@ -1540,8 +1559,12 @@ export class AgentLLMService implements ILLMService {
     // Clear conversation history
     await this.contextManager.clearHistory()
 
-    // Re-inject continuation prompt with variable reference
-    const continuationPrompt = [
+    // Re-inject continuation prompt with variable reference.
+    // Prepend the dateTime block: clearHistory wiped the iter-0 user
+    // message that originally carried it, and the iter-0 guard upstream
+    // prevents re-injection. Without this, every iteration after the
+    // first checkpoint loses time context for the rest of the run.
+    const continuationPrompt = buildDateTimePrefix() + [
       `Continue task. Iteration checkpoint at turn ${iterationCount}.`,
       `Previous progress stored in variable: ${checkpointVar}`,
       `Original task: ${textInput.slice(0, 200)}${textInput.length > 200 ? '...' : ''}`,
@@ -1555,19 +1578,6 @@ export class AgentLLMService implements ILLMService {
     })
   }
 
-  /**
-   * Replace the DateTime section in a cached system prompt with a fresh timestamp.
-   * DateTimeContributor wraps its output in <dateTime>...</dateTime> XML tags,
-   * enabling reliable regex replacement without rebuilding the entire prompt.
-   *
-   * @param cachedPrompt - Previously cached system prompt
-   * @returns Updated prompt with fresh DateTime
-   */
-  private refreshDateTime(cachedPrompt: string): string {
-    const freshDateTime = `<dateTime>Current date and time: ${new Date().toISOString()}</dateTime>`
-    return cachedPrompt.replace(/<dateTime>[\S\s]*?<\/dateTime>/, freshDateTime)
-  }
-
   /**
    * Check if a rolling checkpoint should trigger.
    * Triggers every N iterations for curate/query commands, or when token utilization is high.

src/agent/infra/llm/generators/ai-sdk-content-generator.ts

@@ -5,7 +5,7 @@
  * Replaces per-provider content generators with one unified implementation.
  */
 
-import type {LanguageModel} from 'ai'
+import type {LanguageModel, ModelMessage} from 'ai'
 
 import {generateText, streamText} from 'ai'
 
@@ -22,6 +22,28 @@ import {toAiSdkTools, toModelMessages} from './ai-sdk-message-converter.js'
 
 const DEFAULT_CHARS_PER_TOKEN = 4
 
+/**
+ * Prepend the system prompt as a system-role message carrying
+ * `providerOptions.anthropic.cacheControl: ephemeral`. AI SDK's top-level
+ * `system: string` parameter does not propagate providerOptions, so the
+ * only way to attach Anthropic cache_control to the system block is to
+ * pass it through the messages array. Non-Anthropic providers ignore the
+ * `anthropic` namespace.
+ */
+export function prependCachedSystemMessage(systemPrompt: string | undefined, messages: ModelMessage[]): ModelMessage[] {
+  if (!systemPrompt) {
+    return messages
+  }
+
+  const systemMessage: ModelMessage = {
+    content: systemPrompt,
+    providerOptions: {anthropic: {cacheControl: {type: 'ephemeral'}}},
+    role: 'system',
+  }
+
+  return [systemMessage, ...messages]
+}
+
 /**
  * Configuration for AiSdkContentGenerator.
  */
@@ -54,7 +76,7 @@ export class AiSdkContentGenerator implements IContentGenerator {
   }
 
   public async generateContent(request: GenerateContentRequest): Promise<GenerateContentResponse> {
-    const messages = toModelMessages(request.contents)
+    const messages = prependCachedSystemMessage(request.systemPrompt, toModelMessages(request.contents))
     const tools = toAiSdkTools(request.tools)
 
     const result = await generateText({
@@ -63,7 +85,6 @@ export class AiSdkContentGenerator implements IContentGenerator {
       messages,
       model: this.model,
       temperature: request.config.temperature,
-      ...(request.systemPrompt && {system: request.systemPrompt}),
       ...(tools && {tools}),
       ...(request.config.topK !== undefined && {topK: request.config.topK}),
       ...(request.config.topP !== undefined && {topP: request.config.topP}),
@@ -100,7 +121,7 @@ export class AiSdkContentGenerator implements IContentGenerator {
   }
 
   public async *generateContentStream(request: GenerateContentRequest): AsyncGenerator<GenerateContentChunk> {
-    const messages = toModelMessages(request.contents)
+    const messages = prependCachedSystemMessage(request.systemPrompt, toModelMessages(request.contents))
     const tools = toAiSdkTools(request.tools)
 
     const result = streamText({
@@ -109,7 +130,6 @@ export class AiSdkContentGenerator implements IContentGenerator {
       messages,
       model: this.model,
       temperature: request.config.temperature,
-      ...(request.systemPrompt && {system: request.systemPrompt}),
       ...(tools && {tools}),
       ...(request.config.topK !== undefined && {topK: request.config.topK}),
       ...(request.config.topP !== undefined && {topP: request.config.topP}),

src/agent/infra/llm/generators/ai-sdk-message-converter.ts

@@ -63,18 +63,25 @@ export function toModelMessages(messages: InternalMessage[]): ModelMessage[] {
 /**
  * Convert our ToolSet to AI SDK tool definitions.
  * Tools are declared without `execute` — our agentic loop handles execution.
+ *
+ * The last tool gets `providerOptions.anthropic.cacheControl: ephemeral`,
+ * which makes Anthropic cache the entire tool block (and the system prompt
+ * before it). Non-Anthropic providers ignore the `anthropic` namespace.
  */
 export function toAiSdkTools(tools?: InternalToolSet): Record<string, ReturnType<typeof aiSdkTool>> | undefined {
   if (!tools || Object.keys(tools).length === 0) {
     return undefined
   }
 
+  const entries = Object.entries(tools)
   const result: Record<string, ReturnType<typeof aiSdkTool>> = {}
 
-  for (const [name, def] of Object.entries(tools)) {
+  for (const [index, [name, def]] of entries.entries()) {
+    const isLast = index === entries.length - 1
     result[name] = aiSdkTool({
       description: def.description ?? '',
       inputSchema: jsonSchema(def.parameters as Record<string, unknown>),
+      ...(isLast && {providerOptions: {anthropic: {cacheControl: {type: 'ephemeral'}}}}),
     })
   }