@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/memory-helpers.ts

@@ -1,4 +1,5 @@
 import type { MemorySearchHit } from "@/types/memory";
+import type { RetrievalFailure } from "@/types/llm-chat";
 
 export interface MemoryWriteScope {
   appId: string;
@@ -43,3 +44,52 @@ export function formatMemoryBlock(hits: MemorySearchHit[]): string {
   });
   return `\n\n相关历史记忆（共 ${hits.length} 条）：\n${lines.join("\n")}`;
 }
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function optionalNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
+}
+
+/** Preserve bounded upstream diagnostics without leaking request payloads. */
+export function memoryRetrievalFailure(
+  value: unknown,
+  fallbackCode = "MEMORY_RETRIEVAL_FAILED",
+): RetrievalFailure {
+  const record =
+    value !== null && typeof value === "object"
+      ? (value as Record<string, unknown>)
+      : {};
+  const details =
+    record.details !== null && typeof record.details === "object"
+      ? (record.details as Record<string, unknown>)
+      : {};
+  const code =
+    optionalString(details.upstreamCode) ??
+    optionalString(record.upstreamCode) ??
+    optionalString(record.code) ??
+    fallbackCode;
+  const message =
+    optionalString(record.message) ??
+    (typeof value === "string" ? value : "Memory retrieval failed");
+  const requestId =
+    optionalString(details.upstreamRequestId) ??
+    optionalString(record.upstreamRequestId) ??
+    optionalString(record.requestId);
+  const httpStatus =
+    optionalNumber(details.upstreamStatus) ??
+    optionalNumber(record.upstreamStatus) ??
+    optionalNumber(record.httpStatus) ??
+    optionalNumber(record.status);
+
+  return {
+    code,
+    message,
+    ...(requestId === undefined ? {} : { requestId }),
+    ...(httpStatus === undefined ? {} : { httpStatus }),
+  };
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/memory-retrieval.ts

@@ -0,0 +1,228 @@
+import type { MemoryClient } from "@tablestore/tablestore-agent-sdk";
+
+import type {
+  ChatRequestBody,
+  ChatStreamEvent,
+  RetrievalFailure,
+} from "@/types/llm-chat";
+import type { MemoryFileSearchHit, MemorySearchHit } from "@/types/memory";
+import { normalizeFileMemoryStoreName } from "@/lib/file-memory-core";
+import { formatFileMemoryBlock } from "./file-memory-helpers";
+import { loadServerFileMemory } from "./server-file-memory";
+import { throwIfMemorySecurity } from "./memory-security";
+import {
+  deriveReadScope,
+  formatMemoryBlock,
+  memoryRetrievalFailure,
+  type MemoryWriteScope,
+} from "./memory-helpers";
+
+export interface MemoryRetrievalResult {
+  query: string;
+  hits: MemorySearchHit[];
+  promptBlock: string;
+  filesEvent?: Extract<ChatStreamEvent, { type: "memory.files" }>;
+  error?: RetrievalFailure;
+  isFileMemory: boolean;
+}
+
+const FILE_MEMORY_CACHE_UNAVAILABLE: RetrievalFailure = {
+  code: "FILE_MEMORY_CACHE_UNAVAILABLE",
+  message: "File memory cache is unavailable",
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isMemorySearchHit(value: unknown): value is MemorySearchHit {
+  return (
+    isRecord(value) &&
+    isRecord(value.unit) &&
+    typeof value.unit.text === "string"
+  );
+}
+
+function isMemoryFileSearchHit(value: unknown): value is MemoryFileSearchHit {
+  return (
+    isRecord(value) &&
+    typeof value.itemId === "string" &&
+    value.itemId.length > 0 &&
+    typeof value.path === "string" &&
+    value.path.length > 0 &&
+    (value.summary === undefined || typeof value.summary === "string")
+  );
+}
+
+function memoryHitRank(hit: MemorySearchHit): number {
+  for (const value of [hit.rankingScore, hit.score, hit.similarity]) {
+    if (typeof value === "number" && Number.isFinite(value)) return value;
+  }
+  return Number.NEGATIVE_INFINITY;
+}
+
+/** Merge the server's per-output buckets into one bounded Chat context. */
+export function mergeMemorySearchHits(
+  structuredHits: MemorySearchHit[],
+  managedFileHits: MemorySearchHit[],
+  topK: number,
+): MemorySearchHit[] {
+  return [...structuredHits, ...managedFileHits]
+    .map((hit, index) => ({ hit, index }))
+    .sort((left, right) => {
+      const leftRank = memoryHitRank(left.hit);
+      const rightRank = memoryHitRank(right.hit);
+      if (leftRank !== rightRank) return rightRank > leftRank ? 1 : -1;
+      return left.index - right.index;
+    })
+    .slice(0, topK)
+    .map(({ hit }) => hit);
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    error !== null &&
+    typeof error === "object" &&
+    "name" in error &&
+    error.name === "AbortError"
+  );
+}
+
+async function waitWithSignal<T>(
+  promise: Promise<T>,
+  signal: AbortSignal,
+): Promise<T> {
+  let onAbort: (() => void) | undefined;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () =>
+      reject(
+        signal.reason ??
+          new DOMException("The operation was aborted", "AbortError"),
+      );
+    if (signal.aborted) onAbort();
+    else signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return await Promise.race([promise, aborted]);
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+
+export async function retrieveMemoryContext({
+  client,
+  binding,
+  query,
+  signal,
+}: {
+  client: MemoryClient;
+  binding: NonNullable<ChatRequestBody["memory"]>;
+  query: string;
+  signal: AbortSignal;
+}): Promise<MemoryRetrievalResult> {
+  signal.throwIfAborted();
+  const isFileMemory = binding.retrievalMode === "local";
+  if (isFileMemory) {
+    const memoryStoreName = normalizeFileMemoryStoreName(
+      binding.memoryStoreName,
+    );
+    const loaded = await loadServerFileMemory({
+      client,
+      binding: { ...binding, memoryStoreName },
+      query,
+      signal,
+    });
+    const hits = loaded.hits.map<MemorySearchHit>((hit) => ({
+      unit: { text: hit.text },
+      score: hit.score,
+      source: hit.source,
+    }));
+    const publicCache = loaded.cache.ok
+      ? loaded.cache
+      : { ...loaded.cache, error: FILE_MEMORY_CACHE_UNAVAILABLE.message };
+    return {
+      query,
+      hits,
+      promptBlock: formatFileMemoryBlock(loaded.hits),
+      filesEvent: {
+        type: "memory.files",
+        files: loaded.files,
+        cache: publicCache,
+        memoryStoreName,
+        writable: binding.storageMode === "filemem",
+        scope: binding.scope,
+      },
+      ...(loaded.cache.ok ? {} : { error: FILE_MEMORY_CACHE_UNAVAILABLE }),
+      isFileMemory: true,
+    };
+  }
+
+  try {
+    const topK = binding.topK ?? 5;
+    const response = await waitWithSignal(
+      Promise.resolve(
+        client.searchMemories(
+          {
+            memoryStoreName: binding.memoryStoreName,
+            scope: deriveReadScope(binding.scope as MemoryWriteScope),
+            query,
+            topK,
+          },
+          signal,
+        ),
+      ),
+      signal,
+    );
+    signal.throwIfAborted();
+    if (response.code !== "SUCCESS") {
+      throwIfMemorySecurity(response);
+      return {
+        query,
+        hits: [],
+        promptBlock: "",
+        error: memoryRetrievalFailure(response),
+        isFileMemory: false,
+      };
+    }
+
+    // The SDK wire field is `results`, not the historic dashboard-only `hits`.
+    const data = isRecord(response.data) ? response.data : {};
+    const structuredHits = Array.isArray(data.results)
+      ? data.results.filter(isMemorySearchHit)
+      : [];
+    const fileResults = Array.isArray(data.fileResults)
+      ? data.fileResults.filter(isMemoryFileSearchHit)
+      : [];
+    const managedFileHits = fileResults.map<MemorySearchHit>((hit) => ({
+      unit: {
+        memoryId: hit.itemId,
+        text: hit.summary || hit.path,
+        metadata: {
+          path: hit.path,
+          ...(hit.versionId ? { versionId: hit.versionId } : {}),
+        },
+      },
+      score: hit.score,
+      similarity: hit.similarity,
+      source: `managed-file:${hit.path}`,
+    }));
+    const hits = mergeMemorySearchHits(structuredHits, managedFileHits, topK);
+    return {
+      query,
+      hits,
+      promptBlock: formatMemoryBlock(hits),
+      isFileMemory: false,
+    };
+  } catch (error) {
+    signal.throwIfAborted();
+    if (isAbortError(error)) throw error;
+    throwIfMemorySecurity(error);
+    return {
+      query,
+      hits: [],
+      promptBlock: "",
+      error: memoryRetrievalFailure(error),
+      isFileMemory: false,
+    };
+  }
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/memory-security.ts

@@ -0,0 +1,26 @@
+import {
+  FatalRetrievalSecurityError,
+  retrievalSecurityCode,
+  type RetrievalSecurityCode,
+} from "@/lib/retrieval-security";
+
+export class MemorySecurityError extends FatalRetrievalSecurityError {
+  constructor(code: RetrievalSecurityCode) {
+    super("memory", code);
+    this.name = "MemorySecurityError";
+  }
+}
+
+export function throwIfMemorySecurity(value: unknown): void {
+  if (value instanceof MemorySecurityError) throw value;
+  if (
+    value !== null &&
+    typeof value === "object" &&
+    "name" in value &&
+    value.name === "AbortError"
+  ) {
+    return;
+  }
+  const code = retrievalSecurityCode(value);
+  if (code) throw new MemorySecurityError(code);
+}