@djangocfg/ui-tools 2.1.409 → 2.1.412

package/src/tools/Chat/settings/README.md

@@ -0,0 +1,87 @@
+# Chat settings — `tools/Chat/settings/`
+
+The single, centralized home for every **chat-owned persisted setting**.
+
+## Why this exists
+
+Chat features used to each call `useLocalStorage` (or zustand `persist`)
+with their own ad-hoc storage key. That made it impossible to reason
+about, export, or reset "the chat's settings" as one thing, and
+scattered the SSR / migration / coalescing concerns across the codebase.
+
+This module gives chat **one typed object, one storage key, one hook**:
+
+- `ChatSettings` — the typed shape of all chat-owned settings.
+- `useChatSettings()` — the only hook a chat feature should use to read or
+  write a persisted preference. Built on the improved `useLocalStorage`
+  from `@djangocfg/ui-core`, which gives us:
+  - **Coalesced writes** — several features patching different slices in
+    the same render commit collapse into one `localStorage` write.
+  - **Cross-instance / cross-tab sync** — two `useChatSettings()`
+    consumers stay in lockstep, same tab and across tabs.
+  - **Safe partial updates** — a slice updater that changes nothing is a
+    no-op (no write, no re-render).
+
+## API
+
+```ts
+const {
+  settings,            // full typed ChatSettings object
+  patch,               // grouped patch over whole slices
+  updateDock,          // updateDock({ side: 'left' })
+  updateAudio,
+  updateSpeech,
+  updatePageContext,
+  setAudioMuted,       // shortcut
+  setPageContextLinked,// shortcut
+  reset,
+} = useChatSettings();
+```
+
+Storage key: `djc.chat.settings`.
+
+## Migration status
+
+### Migrated
+
+- **Page-context opt-in** — `lib/page-snapshot/react/provider.tsx` now
+  reads/writes `ChatSettings.pageContext.linked` via `useChatSettings`
+  instead of its own `useLocalStorage('djc.page-snapshot.linked')`.
+  Note: this changes the storage key, so an existing user's prior opt-in
+  is not carried over — they start from the default (`linked: false`).
+  That is acceptable: page-context is opt-in and a fresh default is safe.
+
+### To migrate (safe follow-up — deferred to keep this pass low-risk)
+
+These are mature, working call sites. They each persist correctly today;
+moving them into `ChatSettings` is a clear next step but was deliberately
+deferred so a single PR does not churn the whole chat. Each migration
+also changes a storage key (acceptable — fresh defaults).
+
+- **Dock / layout prefs**
+  - `tools/Chat/hooks/useChatDockPrefs.ts` — key `chat.dock.prefs`,
+    shape `{ mode, side, sideWidth }` → `ChatSettings.dock`.
+  - `tools/Chat/hooks/useChatLayout.ts` — keys `djc-chat-mode`
+    (`STORAGE_KEYS.mode`) and `djc-chat-sidebar-width`
+    (`STORAGE_KEYS.sidebarWidth`) → `ChatSettings.dock.mode` /
+    `ChatSettings.dock.width`. Note `useChatLayout` stores `mode` and
+    width as two separate keys; consolidate into the `dock` slice.
+  - Constants live in `tools/Chat/constants.ts` (`STORAGE_KEYS`).
+
+- **Audio prefs**
+  - `tools/Chat/hooks/useChatAudio.ts` delegates to ui-core's
+    `useNotificationSounds`, which persists under
+    `djangocfg-chat-audio:prefs`. Migrating means either teaching
+    `useNotificationSounds` to accept an external value/setter, or
+    syncing `ChatSettings.audio` ⇆ that hook. Non-trivial — leave as is.
+
+- **Speech / language prefs**
+  - `tools/SpeechRecognition/store/prefsStore.ts` — a zustand `persist`
+    store under `djangocfg-stt:prefs`, shape `{ language, deviceId,
+    engineId, earcons }` → `ChatSettings.speech`. This is a different
+    persistence mechanism (zustand, not `useLocalStorage`); migrating it
+    means reconciling the store with `useChatSettings` and is the
+    highest-effort of the three. Leave as is.
+
+When migrating any of the above: update the consuming components, delete
+the old key from `STORAGE_KEYS` where applicable, and update this file.

package/src/tools/Chat/settings/__tests__/useChatSettings.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { CHAT_SETTINGS_STORAGE_KEY } from '../types';
+import { useChatSettings, type UseChatSettingsReturn } from '../useChatSettings';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+let api: UseChatSettingsReturn | null = null;
+
+function Probe() {
+  api = useChatSettings();
+  return null;
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  window.localStorage.clear();
+  api = null;
+});
+
+async function flush() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe('useChatSettings', () => {
+  it('exposes the default settings before anything is stored', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    expect(api!.settings.pageContext.linked).toBe(false);
+    expect(api!.settings.audio.muted).toBe(false);
+    expect(api!.settings.dock.side).toBe('right');
+  });
+
+  it('updates only the targeted slice, leaving siblings untouched', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    const audioBefore = api!.settings.audio;
+
+    await act(async () => api!.updateDock({ side: 'left' }));
+
+    expect(api!.settings.dock.side).toBe('left');
+    // Audio slice identity is unchanged — a feature never touches another's.
+    expect(api!.settings.audio).toBe(audioBefore);
+  });
+
+  it('setPageContextLinked persists the opt-in under the central key', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    await act(async () => api!.setPageContextLinked(true));
+    await flush();
+
+    expect(api!.settings.pageContext.linked).toBe(true);
+    const stored = JSON.parse(
+      window.localStorage.getItem(CHAT_SETTINGS_STORAGE_KEY)!,
+    );
+    expect(stored.pageContext.linked).toBe(true);
+  });
+
+  it('reset restores every slice to defaults', async () => {
+    await act(async () => root.render(createElement(Probe)));
+    await act(async () => {
+      api!.setAudioMuted(true);
+      api!.updateDock({ side: 'left' });
+    });
+    await flush();
+    expect(api!.settings.audio.muted).toBe(true);
+
+    await act(async () => api!.reset());
+    expect(api!.settings.audio.muted).toBe(false);
+    expect(api!.settings.dock.side).toBe('right');
+  });
+});

package/src/tools/Chat/settings/__tests__/useLocalStorage.test.tsx

@@ -0,0 +1,138 @@
+// @vitest-environment jsdom
+//
+// Covers the Part-1 additions to `@djangocfg/ui-core`'s `useLocalStorage`:
+// partial-merge `patch`, no-op skip, write coalescing, and same-tab
+// cross-instance sync. ui-core ships no test runner, so the test lives
+// here (ui-tools has vitest + jsdom and resolves ui-core via workspace).
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { useLocalStorage } from '@djangocfg/ui-core/hooks';
+
+(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+
+interface Prefs {
+  a: number;
+  b: number;
+  c: string;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  window.localStorage.clear();
+});
+
+/** Flush pending microtask-coalesced writes. */
+async function flushMicrotasks() {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe('useLocalStorage — patch / coalescing / sync', () => {
+  it('patch shallow-merges a subset of keys', async () => {
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      api = useLocalStorage<Prefs>('t.patch', { a: 1, b: 2, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    await act(async () => {
+      api![3]({ b: 99 });
+    });
+    expect(api![0]).toEqual({ a: 1, b: 99, c: 'x' });
+
+    await flushMicrotasks();
+    expect(JSON.parse(window.localStorage.getItem('t.patch')!)).toEqual({
+      a: 1,
+      b: 99,
+      c: 'x',
+    });
+  });
+
+  it('patch is a no-op when nothing changes', async () => {
+    let renders = 0;
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      renders += 1;
+      api = useLocalStorage<Prefs>('t.noop', { a: 1, b: 2, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+    await flushMicrotasks();
+    const rendersAfterMount = renders;
+
+    // Patching with the same values must not trigger a write/re-render.
+    await act(async () => {
+      api![3]({ a: 1, b: 2 });
+    });
+    await flushMicrotasks();
+
+    expect(renders).toBe(rendersAfterMount);
+    // No write happened — key stays absent.
+    expect(window.localStorage.getItem('t.noop')).toBeNull();
+  });
+
+  it('coalesces several patches in one tick into a single write', async () => {
+    let api: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      api = useLocalStorage<Prefs>('t.coalesce', { a: 0, b: 0, c: '' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    // Spy on the prototype — jsdom's per-instance `setItem` is read-only.
+    let writes = 0;
+    const realSetItem = Storage.prototype.setItem;
+    Storage.prototype.setItem = function patched(this: Storage, k, v) {
+      if (k === 't.coalesce') writes += 1;
+      return realSetItem.call(this, k, v);
+    };
+
+    await act(async () => {
+      api![3]({ a: 1 });
+      api![3]({ b: 2 });
+      api![3]({ c: 'z' });
+    });
+    await flushMicrotasks();
+    Storage.prototype.setItem = realSetItem;
+
+    // State reflects all three patches...
+    expect(api![0]).toEqual({ a: 1, b: 2, c: 'z' });
+    // ...but they collapsed into exactly one localStorage write.
+    expect(writes).toBe(1);
+  });
+
+  it('two hook instances on the same key stay in sync (same tab)', async () => {
+    let a: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    let b: ReturnType<typeof useLocalStorage<Prefs>> | null = null;
+    function Probe() {
+      a = useLocalStorage<Prefs>('t.sync', { a: 1, b: 1, c: 'x' });
+      b = useLocalStorage<Prefs>('t.sync', { a: 1, b: 1, c: 'x' });
+      return null;
+    }
+    await act(async () => root.render(createElement(Probe)));
+
+    await act(async () => {
+      a![3]({ b: 42 });
+    });
+    await flushMicrotasks();
+
+    // The sibling instance saw the write without its own setter being called.
+    expect(a![0]).toEqual({ a: 1, b: 42, c: 'x' });
+    expect(b![0]).toEqual({ a: 1, b: 42, c: 'x' });
+  });
+});

package/src/tools/Chat/settings/index.ts

@@ -0,0 +1,23 @@
+'use client';
+
+/**
+ * @djangocfg/ui-tools — Chat / settings
+ *
+ * The one place every chat-owned persisted setting lives. See README.md.
+ */
+
+export {
+  CHAT_SETTINGS_STORAGE_KEY,
+  DEFAULT_CHAT_SETTINGS,
+  type ChatSettings,
+  type ChatDockSettings,
+  type ChatAudioSettings,
+  type ChatSpeechSettings,
+  type ChatPageContextSettings,
+} from './types';
+
+export {
+  useChatSettings,
+  type UseChatSettingsOptions,
+  type UseChatSettingsReturn,
+} from './useChatSettings';

package/src/tools/Chat/settings/types.ts

@@ -0,0 +1,108 @@
+'use client';
+
+import type { ChatDisplayMode } from '../types';
+
+/**
+ * Dock / layout preferences.
+ *
+ * Mirrors the fields the existing `useChatDockPrefs` / `useChatLayout`
+ * persist today. Kept as a nested slice so a feature can `updateDock({...})`
+ * without touching audio / speech / page-context state.
+ */
+export interface ChatDockSettings {
+  /** Floating popover vs. side-docked panel vs. embedded, etc. */
+  mode: ChatDisplayMode;
+  /** Which edge a side dock attaches to. */
+  side: 'left' | 'right';
+  /** Width in px when side-docked. */
+  width: number;
+}
+
+/**
+ * Audio / notification-sound preferences.
+ *
+ * `eventsMuted` is a sparse map: only events the user explicitly toggled
+ * off appear here. An absent key means "use the default for that event".
+ */
+export interface ChatAudioSettings {
+  /** Master mute — silences every chat sound. */
+  muted: boolean;
+  /** Master volume, 0..1. */
+  volume: number;
+  /** Per-event opt-outs, keyed by chat audio event name. */
+  eventsMuted: Record<string, boolean>;
+}
+
+/**
+ * Speech-recognition / language-picker preferences.
+ *
+ * `language` is a BCP-47 tag the user explicitly picked, or `null` for
+ * "no override" — callers then fall back to the app locale.
+ */
+export interface ChatSpeechSettings {
+  /** Explicit language override, or `null` to follow the app locale. */
+  language: string | null;
+  /** Preferred capture device id, or `null` for the system default. */
+  deviceId: string | null;
+  /** Preferred STT engine id, or `null` for auto-select. */
+  engineId: string | null;
+  /** Earcon (audio cue) feedback on dictation start/stop. */
+  earcons: boolean;
+}
+
+/** Page-context (screen-sharing) opt-in. */
+export interface ChatPageContextSettings {
+  /**
+   * Whether the user has opted in to sharing a snapshot of the page they
+   * are viewing with the assistant. Persisted so the choice survives
+   * reloads — the user enables it once.
+   */
+  linked: boolean;
+}
+
+/**
+ * The single, typed shape for every chat-owned persisted setting.
+ *
+ * Centralization rationale: chat features used to each call
+ * `useLocalStorage` with their own ad-hoc key. That made it impossible to
+ * reason about (or export/import) "the chat's settings" as one thing, and
+ * scattered the SSR/migration concerns. One object, one storage key, one
+ * hook — every feature reads/writes its own slice through it.
+ */
+export interface ChatSettings {
+  dock: ChatDockSettings;
+  audio: ChatAudioSettings;
+  speech: ChatSpeechSettings;
+  pageContext: ChatPageContextSettings;
+}
+
+/** Baseline defaults — used for SSR and first-run (nothing stored yet). */
+export const DEFAULT_CHAT_SETTINGS: ChatSettings = {
+  dock: {
+    mode: 'closed',
+    side: 'right',
+    width: 420,
+  },
+  audio: {
+    muted: false,
+    volume: 1,
+    eventsMuted: {},
+  },
+  speech: {
+    language: null,
+    deviceId: null,
+    engineId: null,
+    earcons: false,
+  },
+  pageContext: {
+    linked: false,
+  },
+};
+
+/**
+ * Single localStorage key for the whole chat-settings object.
+ *
+ * One key (vs. one-per-feature) so the entire chat configuration is a
+ * single read/write/coalesce unit — see {@link useChatSettings}.
+ */
+export const CHAT_SETTINGS_STORAGE_KEY = 'djc.chat.settings';

package/src/tools/Chat/settings/useChatSettings.ts

@@ -0,0 +1,168 @@
+'use client';
+
+import { useCallback, useMemo } from 'react';
+
+import { useLocalStorage } from '@djangocfg/ui-core/hooks';
+
+import {
+  CHAT_SETTINGS_STORAGE_KEY,
+  DEFAULT_CHAT_SETTINGS,
+  type ChatAudioSettings,
+  type ChatDockSettings,
+  type ChatPageContextSettings,
+  type ChatSettings,
+  type ChatSpeechSettings,
+} from './types';
+
+/** Options for {@link useChatSettings}. */
+export interface UseChatSettingsOptions {
+  /**
+   * Override the storage key (per-product scoping). Defaults to the
+   * shared {@link CHAT_SETTINGS_STORAGE_KEY}.
+   */
+  storageKey?: string;
+  /**
+   * Override baseline defaults — merged over {@link DEFAULT_CHAT_SETTINGS}
+   * at the slice level (per-product branding, host opt-ins, etc.).
+   */
+  defaults?: Partial<ChatSettings>;
+}
+
+/** Everything {@link useChatSettings} exposes. */
+export interface UseChatSettingsReturn {
+  /** The full, typed settings object (each slice always present). */
+  settings: ChatSettings;
+
+  /**
+   * Top-level grouped patch — shallow-merges whole slices. Use this for
+   * cross-slice updates; for a single slice prefer the typed helpers.
+   */
+  patch: (partial: Partial<ChatSettings>) => void;
+
+  /** Merge a subset of dock fields. */
+  updateDock: (partial: Partial<ChatDockSettings>) => void;
+  /** Merge a subset of audio fields. */
+  updateAudio: (partial: Partial<ChatAudioSettings>) => void;
+  /** Merge a subset of speech fields. */
+  updateSpeech: (partial: Partial<ChatSpeechSettings>) => void;
+  /** Merge a subset of page-context fields. */
+  updatePageContext: (partial: Partial<ChatPageContextSettings>) => void;
+
+  /** Master audio mute shortcut. */
+  setAudioMuted: (muted: boolean) => void;
+  /** Page-context opt-in shortcut. */
+  setPageContextLinked: (linked: boolean) => void;
+
+  /** Reset every slice back to defaults. */
+  reset: () => void;
+}
+
+/** Shallow-merge `defaults` slices over the baseline. */
+function resolveDefaults(defaults?: Partial<ChatSettings>): ChatSettings {
+  if (!defaults) return DEFAULT_CHAT_SETTINGS;
+  return {
+    dock: { ...DEFAULT_CHAT_SETTINGS.dock, ...defaults.dock },
+    audio: { ...DEFAULT_CHAT_SETTINGS.audio, ...defaults.audio },
+    speech: { ...DEFAULT_CHAT_SETTINGS.speech, ...defaults.speech },
+    pageContext: {
+      ...DEFAULT_CHAT_SETTINGS.pageContext,
+      ...defaults.pageContext,
+    },
+  };
+}
+
+/**
+ * The single entry point for chat-owned persisted settings.
+ *
+ * Every chat feature that wants to remember a preference goes through
+ * here instead of calling `useLocalStorage` with its own key. Why:
+ *
+ * - One typed object, one storage key — "the chat's settings" is a single
+ *   thing that can be reasoned about, exported, or reset wholesale.
+ * - Coalesced writes: `useLocalStorage` (Part 1) updates React state
+ *   synchronously but batches the actual `localStorage` write to one per
+ *   tick — so several features patching different slices in the same
+ *   render commit collapse into a single write, no thrash.
+ * - Cross-instance sync: two `useChatSettings()` consumers (e.g. the
+ *   header audio toggle and the settings panel) stay in lockstep within
+ *   the same tab and across tabs.
+ *
+ * Each helper updates only its own slice, leaving sibling slices
+ * untouched — a feature never has to know about the others.
+ *
+ * SSR-safe: returns defaults on the server, hydrates on mount.
+ */
+export function useChatSettings(
+  opts: UseChatSettingsOptions = {},
+): UseChatSettingsReturn {
+  const key = opts.storageKey ?? CHAT_SETTINGS_STORAGE_KEY;
+  // Memoized so the resolved defaults keep a stable identity — passing a
+  // fresh object to `useLocalStorage` each render is harmless but wasteful.
+  const initial = useMemo(
+    () => resolveDefaults(opts.defaults),
+    [opts.defaults],
+  );
+
+  const [settings, setSettings, , patch] = useLocalStorage<ChatSettings>(
+    key,
+    initial,
+  );
+
+  // Slice updaters: read the current slice, shallow-merge the partial,
+  // write back via the coalescing top-level `patch`. The inner
+  // `useLocalStorage` `patch` already skips no-op writes.
+  const updateDock = useCallback(
+    (partial: Partial<ChatDockSettings>) => {
+      patch({ dock: { ...settings.dock, ...partial } });
+    },
+    [patch, settings.dock],
+  );
+
+  const updateAudio = useCallback(
+    (partial: Partial<ChatAudioSettings>) => {
+      patch({ audio: { ...settings.audio, ...partial } });
+    },
+    [patch, settings.audio],
+  );
+
+  const updateSpeech = useCallback(
+    (partial: Partial<ChatSpeechSettings>) => {
+      patch({ speech: { ...settings.speech, ...partial } });
+    },
+    [patch, settings.speech],
+  );
+
+  const updatePageContext = useCallback(
+    (partial: Partial<ChatPageContextSettings>) => {
+      patch({ pageContext: { ...settings.pageContext, ...partial } });
+    },
+    [patch, settings.pageContext],
+  );
+
+  const setAudioMuted = useCallback(
+    (muted: boolean) => updateAudio({ muted }),
+    [updateAudio],
+  );
+
+  const setPageContextLinked = useCallback(
+    (linked: boolean) => updatePageContext({ linked }),
+    [updatePageContext],
+  );
+
+  const reset = useCallback(
+    () => setSettings(initial),
+    [setSettings, initial],
+  );
+
+  return {
+    settings,
+    patch,
+    updateDock,
+    updateAudio,
+    updateSpeech,
+    updatePageContext,
+    setAudioMuted,
+    setPageContextLinked,
+    reset,
+  };
+}

package/src/tools/Chat/types/events.ts

@@ -7,6 +7,32 @@
 
 import type { ChatSource } from './attachment';
 
+/**
+ * Per-run metrics block. Emitted once per assistant turn alongside the
+ * terminal `message_end` event (a separate `message_metrics` event so
+ * `message_end` keeps its lean `tokensIn`/`tokensOut`/`sources` shape).
+ *
+ * All fields optional — the backend omits anything it could not measure.
+ */
+export interface ChatMessageMetrics {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  processingTimeMs?: number;
+  firstTokenMs?: number;
+  turns?: number;
+  toolCallCount?: number;
+  toolNames?: string[];
+  /** Model the request was sent with (may be an alias). */
+  model?: string;
+  /** Concrete model the alias resolved to. */
+  resolvedModel?: string;
+  /** Short summary of the model's thinking, if available. */
+  thinkingSummary?: string;
+}
+
 export type ChatStreamEvent =
   | { type: 'message_start'; messageId: string; sessionId: string }
   | { type: 'resume_start' }
@@ -32,4 +58,28 @@ export type ChatStreamEvent =
       tokensOut?: number;
       sources?: ChatSource[];
     }
+  | {
+      /**
+       * Per-turn metrics for the assistant message currently streaming.
+       * Non-terminal — arrives near the end of the run but does not
+       * close the stream (`message_end` / `error` do that).
+       */
+      type: 'message_metrics';
+      metrics: ChatMessageMetrics;
+    }
+  | {
+      /**
+       * One-shot model-alias resolution (e.g. `@code` → `glm-5.1`).
+       * Non-terminal — lets the UI update the model chip mid-run.
+       */
+      type: 'resolved_model';
+      /** Alias the user/request originally specified. */
+      originalAlias: string;
+      /** Concrete model id the alias resolved to. */
+      resolvedModel: string;
+      /** True when routing upgraded the model (e.g. for a larger context). */
+      upgraded?: boolean;
+      /** Human-readable reason the router picked this model. */
+      routingReason?: string;
+    }
   | { type: 'error'; code: string; message: string };

package/src/tools/Chat/types/index.ts

@@ -40,7 +40,7 @@ export type { ChatMessage } from './message';
 export { DEFAULT_LABELS } from './labels';
 export type { ChatLabels } from './labels';
 export type { ChatConfig, ChatPrefs, ChatDisplayMode } from './config';
-export type { ChatStreamEvent } from './events';
+export type { ChatStreamEvent, ChatMessageMetrics } from './events';
 export type {
   CreateSessionOptions,
   SessionInfo,

package/src/tools/Chat/types/message.ts

@@ -7,6 +7,7 @@
 
 import type { ChatAttachment, ChatSource } from './attachment';
 import type { MessageBlock } from './block';
+import type { ChatMessageMetrics } from './events';
 import type { ChatPersona, ChatRole } from './persona';
 import type { ChatToolCall } from './tool-call';
 
@@ -32,4 +33,8 @@ export interface ChatMessage {
   sources?: ChatSource[];
   tokensIn?: number;
   tokensOut?: number;
+  /** Per-turn metrics (from a `message_metrics` stream event). */
+  metrics?: ChatMessageMetrics;
+  /** Concrete model the request resolved to (from a `resolved_model` event). */
+  resolvedModel?: string;
 }