@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

package/dist/dashboard-runtime/dashboard/src/hooks/use-chat-history.ts

@@ -4,10 +4,35 @@ import { useCallback, useMemo, useSyncExternalStore } from "react";
 
 import { newId } from "@/lib/random-id";
 import {
+  isKnownStorageMode,
   normalizeMemoryRunId,
   type StorageMode,
 } from "@/lib/memory-storage-mode";
-import type { ChatMessage } from "@/types/llm-chat";
+import {
+  clampWikiEvidence,
+  clampWikiRetrievalError,
+  clampWikiRetrievalGroup,
+  MAX_WIKI_ERRORS,
+  MAX_WIKI_EVIDENCE,
+  MAX_WIKI_GROUPS,
+  MAX_WIKI_SOURCES,
+  normalizeRequiredWikiMetadata,
+} from "@/lib/wiki-metadata-limits";
+import type {
+  ChatMessage,
+  MemoryFilesCacheSummary,
+  RetrievedChunk,
+  RetrievalGroup,
+  WikiEvidence,
+  WikiRetrievalError,
+  WikiRetrievalGroup,
+} from "@/types/llm-chat";
+import type {
+  MemoryScope,
+  MemorySearchHit,
+  MemoryUnit,
+  SourceTurnRef,
+} from "@/types/memory";
 
 /** Legacy global key kept for read-only migration. */
 export const CHAT_HISTORY_LEGACY_STORAGE_KEY = "tsagent.chat.sessions.v1";
@@ -95,6 +120,8 @@ export interface ChatSessionConfig {
   retrieval?: ChatRetrievalConfig;
   mounts: ChatSessionMount[];
   memory?: ChatSessionMemoryBinding;
+  /** Allowlisted scalar config for the single Wiki owned by `memory` Scope. */
+  wiki?: { enabled: true; topK: number };
 }
 
 export interface ChatSession {
@@ -143,16 +170,448 @@ function belongsToScope(
   );
 }
 
+function isRecord(raw: unknown): raw is Record<string, unknown> {
+  return !!raw && typeof raw === "object" && !Array.isArray(raw);
+}
+
+function isFiniteNumber(raw: unknown): raw is number {
+  return typeof raw === "number" && Number.isFinite(raw);
+}
+
+function sanitizeRetrievedChunk(raw: unknown): RetrievedChunk | null {
+  if (!isRecord(raw)) return null;
+  if (
+    typeof raw.docId !== "string" ||
+    !isFiniteNumber(raw.chunkId) ||
+    typeof raw.ossKey !== "string" ||
+    !isFiniteNumber(raw.score) ||
+    typeof raw.content !== "string" ||
+    typeof raw.chunkType !== "string"
+  ) {
+    return null;
+  }
+
+  const chunk: RetrievedChunk = {
+    docId: raw.docId,
+    chunkId: raw.chunkId,
+    ossKey: raw.ossKey,
+    score: raw.score,
+    content: raw.content,
+    chunkType: raw.chunkType,
+  };
+  if (typeof raw.imageBase64 === "string") chunk.imageBase64 = raw.imageBase64;
+  if (typeof raw.subspace === "string") chunk.subspace = raw.subspace;
+  if (typeof raw.knowledgeBaseName === "string") {
+    chunk.knowledgeBaseName = raw.knowledgeBaseName;
+  }
+  return chunk;
+}
+
+function sanitizeRetrievalGroup(raw: unknown): RetrievalGroup | null {
+  if (
+    !isRecord(raw) ||
+    typeof raw.knowledgeBaseName !== "string" ||
+    !Array.isArray(raw.chunks)
+  ) {
+    return null;
+  }
+  const group: RetrievalGroup = {
+    knowledgeBaseName: raw.knowledgeBaseName,
+    chunks: raw.chunks
+      .map(sanitizeRetrievedChunk)
+      .filter((chunk): chunk is RetrievedChunk => chunk !== null),
+  };
+  if (typeof raw.error === "string") group.error = raw.error;
+  return group;
+}
+
+function sanitizeMemoryScope(raw: unknown): MemoryScope | undefined {
+  if (!isRecord(raw) || typeof raw.appId !== "string") return undefined;
+  const scope: MemoryScope = { appId: raw.appId };
+  if (typeof raw.tenantId === "string") scope.tenantId = raw.tenantId;
+  if (typeof raw.agentId === "string") scope.agentId = raw.agentId;
+  if (typeof raw.runId === "string") scope.runId = raw.runId;
+  return scope;
+}
+
+function sanitizeSourceTurnRef(raw: unknown): SourceTurnRef | null {
+  if (
+    !isRecord(raw) ||
+    typeof raw.messageId !== "string" ||
+    !isFiniteNumber(raw.timestampMs)
+  ) {
+    return null;
+  }
+  return { messageId: raw.messageId, timestampMs: raw.timestampMs };
+}
+
+function sanitizeMemoryUnit(raw: unknown): MemoryUnit | null {
+  if (!isRecord(raw) || typeof raw.text !== "string") return null;
+  const unit: MemoryUnit = { text: raw.text };
+  if (typeof raw.id === "string") unit.id = raw.id;
+  if (typeof raw.memoryId === "string") unit.memoryId = raw.memoryId;
+  if (typeof raw.conversation_key === "string") {
+    unit.conversation_key = raw.conversation_key;
+  }
+  const scope = sanitizeMemoryScope(raw.scope);
+  if (scope) unit.scope = scope;
+  if (typeof raw.memcell_id === "string") unit.memcell_id = raw.memcell_id;
+  if (typeof raw.unit_type === "string") unit.unit_type = raw.unit_type;
+  if (Array.isArray(raw.source_turn_ids)) {
+    unit.source_turn_ids = raw.source_turn_ids.filter(
+      (item): item is string => typeof item === "string",
+    );
+  }
+  if (Array.isArray(raw.source_turn_refs)) {
+    unit.source_turn_refs = raw.source_turn_refs
+      .map(sanitizeSourceTurnRef)
+      .filter((item): item is SourceTurnRef => item !== null);
+  }
+  if (typeof raw.search_text === "string") unit.search_text = raw.search_text;
+  if (isFiniteNumber(raw.salience)) unit.salience = raw.salience;
+  if (isFiniteNumber(raw.version)) unit.version = raw.version;
+  if (typeof raw.deleted === "boolean") unit.deleted = raw.deleted;
+  if (typeof raw.created_at === "string") unit.created_at = raw.created_at;
+  if (typeof raw.updated_at === "string") unit.updated_at = raw.updated_at;
+  if (isFiniteNumber(raw.score)) unit.score = raw.score;
+  if (typeof raw.createdAt === "string" || isFiniteNumber(raw.createdAt)) {
+    unit.createdAt = raw.createdAt;
+  }
+  if (typeof raw.updatedAt === "string" || isFiniteNumber(raw.updatedAt)) {
+    unit.updatedAt = raw.updatedAt;
+  }
+  return unit;
+}
+
+function sanitizeMemorySearchHit(raw: unknown): MemorySearchHit | null {
+  if (!isRecord(raw)) return null;
+  const unit = sanitizeMemoryUnit(raw.unit);
+  if (!unit) return null;
+  const hit: MemorySearchHit = { unit };
+  if (isFiniteNumber(raw.score)) hit.score = raw.score;
+  if (isFiniteNumber(raw.similarity)) hit.similarity = raw.similarity;
+  if (typeof raw.source === "string") hit.source = raw.source;
+  return hit;
+}
+
+function sanitizeMemoryFiles(raw: unknown): ChatMessage["memoryFiles"] {
+  if (!Array.isArray(raw)) return undefined;
+  return raw.flatMap((item) => {
+    if (
+      !isRecord(item) ||
+      typeof item.rel !== "string" ||
+      !isFiniteNumber(item.size)
+    ) {
+      return [];
+    }
+    return [
+      {
+        rel: item.rel,
+        size: item.size,
+        ...(typeof item.sha256 === "string" ? { sha256: item.sha256 } : {}),
+      },
+    ];
+  });
+}
+
+function sanitizeMemoryFilesCache(
+  raw: unknown,
+): MemoryFilesCacheSummary | undefined {
+  if (
+    !isRecord(raw) ||
+    typeof raw.ok !== "boolean" ||
+    !isFiniteNumber(raw.listed) ||
+    !isFiniteNumber(raw.loaded) ||
+    !isFiniteNumber(raw.reused) ||
+    !isFiniteNumber(raw.totalBytes) ||
+    typeof raw.truncated !== "boolean"
+  ) {
+    return undefined;
+  }
+  const cache: MemoryFilesCacheSummary = {
+    ok: raw.ok,
+    listed: raw.listed,
+    loaded: raw.loaded,
+    reused: raw.reused,
+    totalBytes: raw.totalBytes,
+    truncated: raw.truncated,
+  };
+  if (typeof raw.error === "string") cache.error = raw.error;
+  return cache;
+}
+
+function sanitizeSessionWikiConfig(
+  raw: unknown,
+  hasValidMemoryBinding: boolean,
+): ChatSessionConfig["wiki"] | undefined {
+  if (!hasValidMemoryBinding || !isRecord(raw)) return undefined;
+  if (
+    raw.enabled !== true ||
+    !Number.isInteger(raw.topK) ||
+    (raw.topK as number) < 1 ||
+    (raw.topK as number) > 10
+  ) {
+    return undefined;
+  }
+  return { enabled: true, topK: raw.topK as number };
+}
+
+function sanitizeWikiEvidence(raw: unknown): WikiEvidence | null {
+  if (!raw || typeof raw !== "object") return null;
+  const value = raw as Record<string, unknown>;
+  const wikiName = normalizeRequiredWikiMetadata(value.wikiName);
+  const path = normalizeRequiredWikiMetadata(value.path);
+  if (
+    typeof value.reference !== "string" ||
+    !/^W[1-6]$/.test(value.reference) ||
+    !wikiName ||
+    !path ||
+    typeof value.truncated !== "boolean" ||
+    !Number.isInteger(value.injectedChars) ||
+    (value.injectedChars as number) < 0 ||
+    (value.injectedChars as number) > 8_000
+  ) {
+    return null;
+  }
+
+  return clampWikiEvidence({
+    reference: value.reference as `W${number}`,
+    wikiName,
+    path,
+    ...(typeof value.title === "string" ? { title: value.title } : {}),
+    ...(typeof value.type === "string" ? { type: value.type } : {}),
+    ...(typeof value.description === "string"
+      ? { description: value.description }
+      : {}),
+    ...(typeof value.score === "number" ? { score: value.score } : {}),
+    ...(Array.isArray(value.sources)
+      ? {
+          sources: value.sources
+            .slice(0, MAX_WIKI_SOURCES)
+            .filter((item): item is string => typeof item === "string"),
+        }
+      : {}),
+    truncated: value.truncated,
+    injectedChars: value.injectedChars as number,
+  });
+}
+
+function sanitizeWikiRetrievalError(raw: unknown): WikiRetrievalError | null {
+  if (!raw || typeof raw !== "object") return null;
+  const value = raw as Record<string, unknown>;
+  const code = normalizeRequiredWikiMetadata(value.code);
+  const message = normalizeRequiredWikiMetadata(value.message);
+  if (
+    !code ||
+    !message ||
+    (value.stage !== "validate" &&
+      value.stage !== "search" &&
+      value.stage !== "read" &&
+      value.stage !== "budget")
+  ) {
+    return null;
+  }
+
+  return clampWikiRetrievalError({
+    code,
+    message,
+    ...(typeof value.requestId === "string"
+      ? { requestId: value.requestId }
+      : {}),
+    ...(typeof value.httpStatus === "number"
+      ? { httpStatus: value.httpStatus }
+      : {}),
+    stage: value.stage,
+    ...(typeof value.path === "string" ? { path: value.path } : {}),
+  });
+}
+
+function sanitizeWikiRetrievalGroup(raw: unknown): WikiRetrievalGroup | null {
+  if (!raw || typeof raw !== "object") return null;
+  const value = raw as Record<string, unknown>;
+  const wikiName = normalizeRequiredWikiMetadata(value.wikiName);
+  if (!wikiName || !Array.isArray(value.pages)) {
+    return null;
+  }
+
+  return clampWikiRetrievalGroup({
+    wikiName,
+    pages: value.pages
+      .slice(0, MAX_WIKI_EVIDENCE)
+      .map(sanitizeWikiEvidence)
+      .filter((page): page is WikiEvidence => page !== null),
+    ...(Array.isArray(value.errors)
+      ? {
+          errors: value.errors
+            .slice(0, MAX_WIKI_ERRORS)
+            .map(sanitizeWikiRetrievalError)
+            .filter((error): error is WikiRetrievalError => error !== null),
+        }
+      : {}),
+  });
+}
+
+function sanitizeWikiScope(raw: unknown): ChatMessage["wikiScope"] | null {
+  if (!raw || typeof raw !== "object") return null;
+  const value = raw as Record<string, unknown>;
+  if (
+    typeof value.appId !== "string" ||
+    typeof value.tenantId !== "string" ||
+    typeof value.agentId !== "string" ||
+    typeof value.runId !== "string"
+  ) {
+    return null;
+  }
+  return {
+    appId: value.appId,
+    tenantId: value.tenantId,
+    agentId: value.agentId,
+    runId: value.runId,
+  };
+}
+
 function sanitizeSessionMessages(messages: unknown[]): ChatMessage[] {
   return messages.flatMap((message) => {
-    if (!message || typeof message !== "object") return [];
-    const candidate = message as ChatMessage;
-    if (candidate.memorySaveStatus !== "saving") return [candidate];
-    const sanitized = { ...candidate };
-    delete sanitized.memorySaveStatus;
-    delete sanitized.memorySavePath;
-    delete sanitized.memorySaveCount;
-    delete sanitized.memorySaveError;
+    if (!isRecord(message)) return [];
+    const { id, role, content, createdAt } = message;
+    if (
+      typeof id !== "string" ||
+      (role !== "user" && role !== "assistant" && role !== "system") ||
+      typeof content !== "string" ||
+      !isFiniteNumber(createdAt)
+    ) {
+      return [];
+    }
+    const value = message;
+    const sanitized: ChatMessage = {
+      id,
+      role,
+      content,
+      createdAt,
+    };
+
+    if (typeof value.reasoning === "string")
+      sanitized.reasoning = value.reasoning;
+    if (isFiniteNumber(value.reasoningStartedAt)) {
+      sanitized.reasoningStartedAt = value.reasoningStartedAt;
+    }
+    if (isFiniteNumber(value.reasoningCompletedAt)) {
+      sanitized.reasoningCompletedAt = value.reasoningCompletedAt;
+    }
+    if (typeof value.usingRag === "boolean")
+      sanitized.usingRag = value.usingRag;
+    if (typeof value.queryRewriteFailed === "boolean") {
+      sanitized.queryRewriteFailed = value.queryRewriteFailed;
+    }
+    if (typeof value.queryRewriteError === "string") {
+      sanitized.queryRewriteError = value.queryRewriteError;
+    }
+    if (typeof value.retrievalQuery === "string") {
+      sanitized.retrievalQuery = value.retrievalQuery;
+    }
+    if (typeof value.retrievalQueryRewritten === "boolean") {
+      sanitized.retrievalQueryRewritten = value.retrievalQueryRewritten;
+    }
+    if (Array.isArray(value.retrievedChunks)) {
+      sanitized.retrievedChunks = value.retrievedChunks
+        .map(sanitizeRetrievedChunk)
+        .filter((chunk): chunk is RetrievedChunk => chunk !== null);
+    }
+    if (Array.isArray(value.retrievalGroups)) {
+      sanitized.retrievalGroups = value.retrievalGroups
+        .map(sanitizeRetrievalGroup)
+        .filter((group): group is RetrievalGroup => group !== null);
+    }
+    if (Array.isArray(value.memoryHits)) {
+      sanitized.memoryHits = value.memoryHits
+        .map(sanitizeMemorySearchHit)
+        .filter((hit): hit is MemorySearchHit => hit !== null);
+    }
+    if (typeof value.memoryQuery === "string") {
+      sanitized.memoryQuery = value.memoryQuery;
+    }
+
+    if (typeof value.wikiQuery === "string") {
+      sanitized.wikiQuery = value.wikiQuery;
+    }
+    if (Number.isInteger(value.wikiCount) && (value.wikiCount as number) >= 0) {
+      sanitized.wikiCount = value.wikiCount as number;
+    }
+    if (typeof value.wikiRetrievalDone === "boolean") {
+      sanitized.wikiRetrievalDone = value.wikiRetrievalDone;
+    }
+    if (Array.isArray(value.wikiEvidence)) {
+      sanitized.wikiEvidence = value.wikiEvidence
+        .slice(0, MAX_WIKI_EVIDENCE)
+        .map(sanitizeWikiEvidence)
+        .filter((page): page is WikiEvidence => page !== null);
+    }
+    if (Array.isArray(value.wikiRetrievalGroups)) {
+      sanitized.wikiRetrievalGroups = value.wikiRetrievalGroups
+        .slice(0, MAX_WIKI_GROUPS)
+        .map(sanitizeWikiRetrievalGroup)
+        .filter((group): group is WikiRetrievalGroup => group !== null);
+    }
+    if (
+      Number.isInteger(value.wikiTotalContextChars) &&
+      (value.wikiTotalContextChars as number) >= 0
+    ) {
+      sanitized.wikiTotalContextChars = value.wikiTotalContextChars as number;
+    }
+    if (typeof value.wikiMemoryStoreName === "string") {
+      sanitized.wikiMemoryStoreName = value.wikiMemoryStoreName;
+    }
+    const wikiScope = sanitizeWikiScope(value.wikiScope);
+    if (wikiScope) sanitized.wikiScope = wikiScope;
+
+    const memoryFiles = sanitizeMemoryFiles(value.memoryFiles);
+    if (memoryFiles) sanitized.memoryFiles = memoryFiles;
+    const memoryFilesCache = sanitizeMemoryFilesCache(value.memoryFilesCache);
+    if (memoryFilesCache) sanitized.memoryFilesCache = memoryFilesCache;
+    if (typeof value.memoryFilesStoreName === "string") {
+      sanitized.memoryFilesStoreName = value.memoryFilesStoreName;
+    }
+    if (typeof value.memoryFilesWritable === "boolean") {
+      sanitized.memoryFilesWritable = value.memoryFilesWritable;
+    }
+    const memoryFilesScope = sanitizeWikiScope(value.memoryFilesScope);
+    if (memoryFilesScope) sanitized.memoryFilesScope = memoryFilesScope;
+
+    if (
+      value.memorySaveStatus === "saving" ||
+      value.memorySaveStatus === "saved" ||
+      value.memorySaveStatus === "unchanged" ||
+      value.memorySaveStatus === "error"
+    ) {
+      sanitized.memorySaveStatus = value.memorySaveStatus;
+    }
+    if (typeof value.memorySavePath === "string") {
+      sanitized.memorySavePath = value.memorySavePath;
+    }
+    if (isFiniteNumber(value.memorySaveCount)) {
+      sanitized.memorySaveCount = value.memorySaveCount;
+    }
+    if (typeof value.memorySaveError === "string") {
+      sanitized.memorySaveError = value.memorySaveError;
+    }
+    if (typeof value.turnId === "string") sanitized.turnId = value.turnId;
+    if (
+      value.status === "streaming" ||
+      value.status === "done" ||
+      value.status === "error"
+    ) {
+      sanitized.status = value.status;
+    }
+    if (typeof value.errorMessage === "string") {
+      sanitized.errorMessage = value.errorMessage;
+    }
+
+    if (sanitized.memorySaveStatus === "saving") {
+      delete sanitized.memorySaveStatus;
+      delete sanitized.memorySavePath;
+      delete sanitized.memorySaveCount;
+      delete sanitized.memorySaveError;
+    }
     return [sanitized];
   });
 }
@@ -169,6 +628,116 @@ function createLegacyRunId(seed: string): string {
   return `run_legacy_${hash.toString(16).padStart(16, "0")}`;
 }
 
+function sanitizeRetrievalConfig(
+  raw: unknown,
+): ChatRetrievalConfig | undefined {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const value = raw as Record<string, unknown>;
+  const retrieval: ChatRetrievalConfig = {};
+  if (Array.isArray(value.searchType)) {
+    retrieval.searchType = value.searchType.filter(
+      (item): item is "DENSE_VECTOR" | "FULL_TEXT" =>
+        item === "DENSE_VECTOR" || item === "FULL_TEXT",
+    );
+  }
+  if (
+    value.rerankType === "RRF" ||
+    value.rerankType === "WEIGHT" ||
+    value.rerankType === "MODEL"
+  ) {
+    retrieval.rerankType = value.rerankType;
+  }
+  if (isFiniteNumber(value.rrfK)) retrieval.rrfK = value.rrfK;
+  if (isFiniteNumber(value.rrfDenseWeight)) {
+    retrieval.rrfDenseWeight = value.rrfDenseWeight;
+  }
+  if (isFiniteNumber(value.rrfFullTextWeight)) {
+    retrieval.rrfFullTextWeight = value.rrfFullTextWeight;
+  }
+  if (isFiniteNumber(value.weightDense)) {
+    retrieval.weightDense = value.weightDense;
+  }
+  if (isFiniteNumber(value.weightFullText)) {
+    retrieval.weightFullText = value.weightFullText;
+  }
+  if (typeof value.modelName === "string") {
+    retrieval.modelName = value.modelName;
+  }
+  if (typeof value.modelProvider === "string") {
+    retrieval.modelProvider = value.modelProvider;
+  }
+  return retrieval;
+}
+
+function sanitizeSessionMounts(raw: unknown): ChatSessionMount[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.flatMap((item) => {
+    if (!item || typeof item !== "object") return [];
+    const value = item as Record<string, unknown>;
+    if (
+      typeof value.id !== "string" ||
+      typeof value.knowledgeBaseName !== "string"
+    ) {
+      return [];
+    }
+
+    const mount: ChatSessionMount = {
+      id: value.id,
+      knowledgeBaseName: value.knowledgeBaseName,
+    };
+    if (
+      Array.isArray(value.subspace) &&
+      value.subspace.length > 0 &&
+      value.subspace.every((entry) => typeof entry === "string")
+    ) {
+      mount.subspace = value.subspace as string[];
+    }
+    const retrieval = sanitizeRetrievalConfig(value.retrieval);
+    if (retrieval) mount.retrieval = retrieval;
+    if (isFiniteNumber(value.topK)) mount.topK = value.topK;
+    return [mount];
+  });
+}
+
+function sanitizeSessionConfig(
+  raw: unknown,
+  sessionId: string,
+  normalizeRunId: boolean,
+): ChatSessionConfig {
+  const value =
+    raw && typeof raw === "object" && !Array.isArray(raw)
+      ? (raw as Record<string, unknown>)
+      : {};
+  const memory = sanitizeMemoryBinding(value.memory, sessionId, normalizeRunId);
+  const config: ChatSessionConfig = {
+    mounts: sanitizeSessionMounts(value.mounts),
+  };
+  if (typeof value.providerId === "string")
+    config.providerId = value.providerId;
+  if (typeof value.model === "string") config.model = value.model;
+  if (typeof value.systemPrompt === "string") {
+    config.systemPrompt = value.systemPrompt;
+  }
+  if (isFiniteNumber(value.temperature)) {
+    config.temperature = value.temperature;
+  }
+  if (isFiniteNumber(value.aggregateTopK)) {
+    config.aggregateTopK = value.aggregateTopK;
+  }
+  if (isFiniteNumber(value.perKbTopK)) {
+    config.perKbTopK = value.perKbTopK;
+  }
+  const retrieval = sanitizeRetrievalConfig(value.retrieval);
+  if (retrieval) config.retrieval = retrieval;
+  if (memory) config.memory = memory;
+  const wiki = sanitizeSessionWikiConfig(
+    value.wiki,
+    memory?.storageMode !== undefined,
+  );
+  if (wiki) config.wiki = wiki;
+  return config;
+}
+
 function sanitizeSessions(parsed: unknown): ChatSession[] {
   if (!Array.isArray(parsed)) return [];
   const sessions = parsed.filter(
@@ -176,29 +745,26 @@ function sanitizeSessions(parsed: unknown): ChatSession[] {
       !!s &&
       typeof s === "object" &&
       typeof (s as ChatSession).id === "string" &&
+      typeof (s as ChatSession).title === "string" &&
+      isFiniteNumber((s as ChatSession).updatedAt) &&
       Array.isArray((s as ChatSession).messages),
   );
-  return sessions.map((s) => ({
-    ...s,
-    activeInstance: normalizeActiveInstance(s.activeInstance),
-    messages: sanitizeSessionMessages(s.messages),
-    config: {
-      ...s.config,
-      mounts: (s.config?.mounts ?? []).map((m) => ({
-        id: m.id,
-        knowledgeBaseName: m.knowledgeBaseName,
-        ...(m.subspace && m.subspace.length ? { subspace: m.subspace } : {}),
-        ...(m.retrieval ? { retrieval: m.retrieval } : {}),
-        ...(typeof m.topK === "number" ? { topK: m.topK } : {}),
-      })),
-      memory: sanitizeMemoryBinding(s.config?.memory, s.id),
-    },
-  }));
+  return sessions.map((s) => {
+    return {
+      id: s.id,
+      title: s.title,
+      updatedAt: s.updatedAt,
+      activeInstance: normalizeActiveInstance(s.activeInstance),
+      config: sanitizeSessionConfig(s.config, s.id, true),
+      messages: sanitizeSessionMessages(s.messages),
+    };
+  });
 }
 
 function sanitizeMemoryBinding(
   raw: unknown,
   sessionId: string,
+  normalizeRunId = true,
 ): ChatSessionMemoryBinding | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const r = raw as Partial<ChatSessionMemoryBinding>;
@@ -217,25 +783,25 @@ function sanitizeMemoryBinding(
   ) {
     return undefined;
   }
-  const runId = normalizeMemoryRunId(r.storageMode, s.runId, () =>
-    createLegacyRunId(
-      JSON.stringify([
-        sessionId,
-        r.memoryStoreName,
-        s.appId,
-        s.tenantId,
-        s.agentId,
-      ]),
-    ),
-  );
+  const runId = normalizeRunId
+    ? normalizeMemoryRunId(r.storageMode, s.runId, () =>
+        createLegacyRunId(
+          JSON.stringify([
+            sessionId,
+            r.memoryStoreName,
+            s.appId,
+            s.tenantId,
+            s.agentId,
+          ]),
+        ),
+      )
+    : s.runId;
   return {
     // 缺失 binding id 只可能来自老快照或手动损坏的数据；写 scope 的 runId
     // 则在上方用会话与 scope seed 做确定性修复，不依赖这个临时 UI key。
     id: typeof r.id === "string" && r.id ? r.id : newId("memory"),
     memoryStoreName: r.memoryStoreName,
-    ...(r.storageMode === "ots" ||
-    r.storageMode === "file+ots" ||
-    r.storageMode === "filemem"
+    ...(isKnownStorageMode(r.storageMode)
       ? { storageMode: r.storageMode }
       : {}),
     scope: {
@@ -398,18 +964,32 @@ export function upsertSession(
   session: ChatSession,
   activeInstance: string | null | undefined,
 ): void {
+  if (
+    typeof session.id !== "string" ||
+    typeof session.title !== "string" ||
+    !isFiniteNumber(session.updatedAt) ||
+    !Array.isArray(session.messages)
+  ) {
+    return;
+  }
   const scope = normalizeActiveInstance(activeInstance);
   const all = readAll(scope);
   // Truncate the session's message list to the tail so a single runaway
   // conversation cannot consume the whole localStorage budget.
-  const scopedSession = { ...session, activeInstance: scope };
-  const capped: ChatSession =
-    scopedSession.messages.length > MAX_MESSAGES_PER_SESSION
-      ? {
-          ...scopedSession,
-          messages: scopedSession.messages.slice(-MAX_MESSAGES_PER_SESSION),
-        }
-      : scopedSession;
+  const scopedSession: ChatSession = {
+    id: session.id,
+    title: session.title,
+    updatedAt: session.updatedAt,
+    activeInstance: scope,
+    config: sanitizeSessionConfig(session.config, session.id, false),
+    messages: sanitizeSessionMessages(session.messages),
+  };
+  if (scopedSession.messages.length > MAX_MESSAGES_PER_SESSION) {
+    scopedSession.messages = scopedSession.messages.slice(
+      -MAX_MESSAGES_PER_SESSION,
+    );
+  }
+  const capped = scopedSession;
   const idx = all.findIndex((s) => s.id === capped.id);
   if (idx >= 0) {
     all[idx] = capped;