@tanstack/ai-client 0.22.1 → 0.23.1

package/src/devtools-noop.ts

@@ -86,6 +86,7 @@ export class NoOpChatDevtoolsBridge {
     return ''
   }
   observeChunk(_chunk: StreamChunk): void {}
+  recordMemoryState(_value: unknown): void {}
   beginRun(_runId: string, _threadId: string): void {}
   getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
     return undefined
@@ -190,12 +191,12 @@ void _bridgeParity
 export const createNoOpChatDevtoolsBridge: ChatDevtoolsBridgeFactory = (
   options,
 ) =>
-  // eslint-disable-next-line no-restricted-syntax -- see comment above
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
   new NoOpChatDevtoolsBridge(options) as unknown as ChatDevtoolsBridge
 
 export const createNoOpGenerationDevtoolsBridge: GenerationDevtoolsBridgeFactory =
   <TOutput>(options: GenerationDevtoolsBridgeOptions<TOutput>) =>
-    // eslint-disable-next-line no-restricted-syntax -- see comment above
+    // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
     new NoOpGenerationDevtoolsBridge<TOutput>(
       options,
     ) as unknown as GenerationDevtoolsBridge<TOutput>
@@ -205,7 +206,7 @@ export const createNoOpVideoDevtoolsBridge: VideoDevtoolsBridgeFactory = <
 >(
   options: VideoDevtoolsBridgeOptions<TOutput>,
 ) =>
-  // eslint-disable-next-line no-restricted-syntax -- see comment above
+  // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
   new NoOpVideoDevtoolsBridge<TOutput>(
     options,
   ) as unknown as VideoDevtoolsBridge<TOutput>

package/src/devtools.ts

@@ -6,7 +6,10 @@ import {
 import { convertSchemaToJsonSchema } from '@tanstack/ai/client'
 import { DefaultChatClientEventEmitter } from './events'
 import type { AnyClientTool, StreamChunk } from '@tanstack/ai/client'
-import type { AIDevtoolsEventVisibility } from '@tanstack/ai-event-client'
+import type {
+  AIDevtoolsEventVisibility,
+  MemoryScopeLite,
+} from '@tanstack/ai-event-client'
 import type {
   ChatClientEventContext,
   ChatClientEventEmitter,
@@ -25,6 +28,33 @@ export interface AIDevtoolsDisplayOptions {
   name?: string
 }
 
+/**
+ * Structural mirror of `MemoryStateEventValue` from `@tanstack/ai-memory` — the
+ * payload of the `memory:state` CUSTOM chunk. Kept local so `ai-client` doesn't
+ * depend on `ai-memory`; the memory middleware is the producer.
+ */
+interface MemoryStateEventValue {
+  scope: MemoryScopeLite
+  adapter: string
+  query?: string
+  recall?: {
+    fragmentCount?: number
+    hasTools?: boolean
+    systemPromptChars?: number
+    durationMs?: number
+  }
+  snapshot?: {
+    takenAt: string
+    data: unknown
+    facts?: Array<{
+      id: string
+      text: string
+      source?: string
+      createdAt?: string
+    }>
+  }
+}
+
 export interface AIDevtoolsClientMetadata extends AIDevtoolsDisplayOptions {
   framework?: string
   hookName: string
@@ -463,7 +493,7 @@ export class ClientDevtoolsBridge<TSnapshot extends object> {
       ...this.createMetadataPayload(),
       // Wire envelope uses Record<string, unknown>; widen the typed snapshot
       // here so the typed-snapshot constraint above can stay narrow.
-      // eslint-disable-next-line no-restricted-syntax -- TSnapshot extends object is structurally compatible but TS can't see the missing index signature
+      // oxlint-disable-next-line eslint-js/no-restricted-syntax -- TSnapshot extends object is structurally compatible but TS can't see the missing index signature
       state: this.options.getSnapshot() as unknown as Record<string, unknown>,
     })
   }
@@ -626,8 +656,16 @@ export class ClientDevtoolsBridge<TSnapshot extends object> {
     this.emitRegistered()
     this.emitToolsRegistered()
     this.emitSnapshot()
+    this.onReplayState()
   }
 
+  /**
+   * Extension hook for subclasses to replay any additional cached state on a
+   * `devtools:request-state` (i.e. when a panel opens). Called only after the
+   * base guards (disposed/superseded/targetHookId) pass. No-op by default.
+   */
+  protected onReplayState(): void {}
+
   private async handleToolFixtureApply(
     event: AIDevtoolsEvent<AIDevtoolsToolFixture>,
   ): Promise<void> {
@@ -644,6 +682,9 @@ export class ClientDevtoolsBridge<TSnapshot extends object> {
       return false
     }
 
+    // Fixture routing: `hookId` wins when present (latest bridge for that
+    // registry key). `threadId` is the fallback for fixtures scoped only to a
+    // conversation / generation slot without a hook id.
     if (fixture.hookId) {
       return fixture.hookId === this.options.hookId
     }
@@ -657,13 +698,16 @@ export class ClientDevtoolsBridge<TSnapshot extends object> {
     return true
   }
 
-  private createEnvelope(
+  protected createEnvelope(
     eventType:
       | 'hook:registered'
       | 'hook:updated'
       | 'hook:unregistered'
       | 'hook:state-snapshot'
       | 'tools:registered'
+      | 'memory:retrieve:started'
+      | 'memory:retrieve:completed'
+      | 'memory:snapshot'
       | AIDevtoolsRunEventType,
     visibility: AIDevtoolsEventVisibility = 'client-state',
     context: { runId?: string } = {},
@@ -740,6 +784,8 @@ export class ChatDevtoolsBridge extends ClientDevtoolsBridge<AIDevtoolsChatSnaps
   private currentStreamId: string | null = null
   private lastStreamId: string | null = null
   private lastRunEventContext: ChatClientRunEventContext | undefined
+  /** Last transported `memory:state` value, replayed when a panel opens. */
+  private lastMemoryStateValue: unknown = null
 
   constructor(options: ChatDevtoolsBridgeOptions) {
     super({
@@ -830,6 +876,78 @@ export class ChatDevtoolsBridge extends ClientDevtoolsBridge<AIDevtoolsChatSnaps
     }
   }
 
+  /**
+   * Record a transported `memory:state` value (the server memory middleware's
+   * per-turn recall metrics + store snapshot). Called from the chat client's
+   * `onCustomEvent` handler — the designated path for CUSTOM stream events —
+   * NOT from `observeChunk`. Re-emits the browser `memory:*` events the devtools
+   * store consumes, and caches the value so a panel opened later can replay it
+   * (see {@link onReplayState}). Symmetric with the generation bridge's
+   * `recordResultChange` / `recordProgressChange`.
+   */
+  recordMemoryState(rawValue: unknown): void {
+    this.lastMemoryStateValue = rawValue
+    this.emitMemoryState(rawValue)
+  }
+
+  /**
+   * Re-emit the browser-side `memory:*` events from a transported
+   * `memory:state` value. The devtools store consumes these to render the
+   * Memory tab (operations timeline + live contents). The recall pair mirrors
+   * the server middleware's own emits; the snapshot is included only when the
+   * adapter supports introspection.
+   */
+  private emitMemoryState(rawValue: unknown): void {
+    if (!rawValue || typeof rawValue !== 'object') return
+    const value = rawValue as MemoryStateEventValue
+    const scope = value.scope
+    const adapter = value.adapter
+    if (!scope || typeof adapter !== 'string') return
+    const runContext = this.currentRunId ? { runId: this.currentRunId } : {}
+
+    emitAIDevtoolsEvent('memory:retrieve:started', {
+      ...this.createEnvelope(
+        'memory:retrieve:started',
+        'client-state',
+        runContext,
+      ),
+      scope,
+      adapter,
+      query: value.query ?? '',
+    })
+    if (value.recall) {
+      emitAIDevtoolsEvent('memory:retrieve:completed', {
+        ...this.createEnvelope(
+          'memory:retrieve:completed',
+          'client-state',
+          runContext,
+        ),
+        scope,
+        adapter,
+        fragmentCount: value.recall.fragmentCount ?? 0,
+        hasTools: Boolean(value.recall.hasTools),
+        systemPromptChars: value.recall.systemPromptChars ?? 0,
+        durationMs: value.recall.durationMs ?? 0,
+      })
+    }
+    if (value.snapshot) {
+      emitAIDevtoolsEvent('memory:snapshot', {
+        ...this.createEnvelope('memory:snapshot', 'client-state', runContext),
+        scope,
+        adapter,
+        takenAt: value.snapshot.takenAt,
+        data: value.snapshot.data,
+        facts: value.snapshot.facts ?? [],
+      })
+    }
+  }
+
+  protected override onReplayState(): void {
+    if (this.lastMemoryStateValue != null) {
+      this.emitMemoryState(this.lastMemoryStateValue)
+    }
+  }
+
   getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
     if (!this.currentRunId) return undefined
     return {