Add Durable Streams fetch caching to agents runner (#4478)

## Summary
- install an Undici cache interceptor for the built-in agents local Node
runner
- use a 100 MiB in-memory HTTP cache for Durable Streams fetches
- add undici as an agents package dependency

## Testing
- pnpm --filter @electric-ax/agents typecheck
- pnpm --filter @electric-ax/agents stylecheck

Author: KyleAMathews

.changeset/quiet-streams-cache.md

@@ -0,0 +1,6 @@
+---
+'@electric-ax/agents': patch
+'@electric-ax/agents-desktop': patch
+---
+
+Install an Undici HTTP cache dispatcher for the built-in agents local Node runner so Durable Streams catch-up reads can use server cache headers. Electric Agents Desktop uses an on-disk SQLite cache so runtime restarts can reuse cached catch-up responses.

packages/agents-desktop/src/runtime/lifecycle.ts

@@ -1,3 +1,4 @@
+import path from 'node:path'
 import { app, powerSaveBlocker } from 'electron'
 import { AGENT_SKILLS_DIR } from '../shared/paths'
 import {
@@ -290,6 +291,14 @@ export async function startRuntime(
   const nextRuntime = new BuiltinAgentsServer({
     agentServerUrl: activeServer.url,
     workingDirectory: deps.settings.workingDirectory ?? app.getPath(`home`),
+    durableStreamsFetchCache: {
+      store: `sqlite`,
+      sqliteLocation: path.join(
+        app.getPath(`userData`),
+        `durable-streams-fetch-cache.sqlite`
+      ),
+      maxCount: 10_000,
+    },
     extraMcpServers: deps.settings.mcp?.servers,
     enabledModelValues: resolveEnabledModelValues(
       deps.settings.enabledModelValues

packages/agents/package.json

@@ -62,6 +62,7 @@
     "pino": "^10.3.1",
     "pino-pretty": "^13.0.0",
     "sqlite-vec": "^0.1.9",
+    "undici": "^7.24.7",
     "zod": "^4.3.6"
   },
   "devDependencies": {

packages/agents/src/durable-streams-cache.ts

@@ -0,0 +1,35 @@
+import { Agent, cacheStores, interceptors, setGlobalDispatcher } from 'undici'
+
+const MEMORY_CACHE_SIZE_BYTES = 100 * 1024 * 1024
+
+export type DurableStreamsFetchCacheOptions =
+  | false
+  | {
+      store?: `memory` | `sqlite`
+      sqliteLocation?: string
+      maxCount?: number
+    }
+
+export function installDurableStreamsFetchCache(
+  options: DurableStreamsFetchCacheOptions = {}
+): void {
+  if (options === false) return
+
+  const store =
+    options.store === `sqlite` || options.sqliteLocation
+      ? new cacheStores.SqliteCacheStore({
+          location: options.sqliteLocation,
+          maxCount: options.maxCount,
+        })
+      : new cacheStores.MemoryCacheStore({
+          maxSize: MEMORY_CACHE_SIZE_BYTES,
+        })
+
+  setGlobalDispatcher(
+    new Agent().compose(
+      interceptors.cache({
+        store,
+      })
+    )
+  )
+}

packages/agents/src/server.ts

@@ -1,4 +1,5 @@
 import path from 'node:path'
+import { installDurableStreamsFetchCache } from './durable-streams-cache.js'
 import { serverLog } from './log.js'
 import {
   createBuiltinAgentHandler,
@@ -29,12 +30,19 @@ import type {
   PullWakeRunner,
   PullWakeRunnerConfig,
 } from '@electric-ax/agents-runtime'
+import type { DurableStreamsFetchCacheOptions } from './durable-streams-cache.js'
 import type { StreamFn } from '@mariozechner/pi-agent-core'
 
 export interface BuiltinAgentsServerOptions {
   agentServerUrl: string
   workingDirectory?: string
   mockStreamFn?: StreamFn
+  /**
+   * Configure the process-wide HTTP cache used by Undici-backed fetch calls.
+   * Defaults to a 100 MiB in-memory cache. Pass `false` to leave the global
+   * dispatcher unchanged.
+   */
+  durableStreamsFetchCache?: DurableStreamsFetchCacheOptions
   /** Pull-wake runner configuration for built-in agents. */
   pullWake: {
     runnerId: string
@@ -177,6 +185,8 @@ export class BuiltinAgentsServer {
       throw new Error(`Builtin agents runtime already started`)
     }
 
+    installDurableStreamsFetchCache(this.options.durableStreamsFetchCache)
+
     const pullWake = this.options.pullWake
     if (!pullWake?.runnerId) {
       throw new Error(`Builtin agents require a pull-wake runner id`)