@tablestore/tablestore-agent-cli 0.2.10 → 0.3.1

package/dist/dashboard-runtime/dashboard/src/lib/memory-storage-mode.ts

@@ -1,53 +1,208 @@
-/**
- * 记忆库存储模式（storageMode）——创建时定死、不可修改。
- *   - "ots"     仅 API 记忆：只走 Tablestore，通过语义检索读写，无文件投影。
- *   - "oss+ots" 支持文件记忆：Tablestore + OSS 文件投影，记忆额外投影成 markdown
- *               文件树，可在对话中以文件形式检索、在控制台/CLI 浏览目录结构。
- */
 import type { TranslateFn } from "@/i18n/i18n-context";
+import { newId } from "@/lib/random-id";
 
-export type StorageMode = "ots" | "oss+ots";
+export type StorageMode = "ots" | "file+ots" | "filemem";
+export type MemoryInputType = "short-term" | "file";
+export type MemoryStorageStructure = "structured" | "file";
+export type MemoryDetailSegment =
+  "units" | "search" | "messages" | "tasks" | "requests" | "dream" | "settings";
+export type MemoryCardShortcut =
+  "longTerm" | "shortTerm" | "extract" | "consolidate" | "files";
+export type MemoryCardAction = "units" | "search" | "settings";
 
-/** 建库时可选的两种模式（顺序即 UI 展示顺序，默认取第一个 ots）。 */
-export const STORAGE_MODE_VALUES: StorageMode[] = ["ots", "oss+ots"];
+export interface MemoryStorageSelection {
+  inputType: MemoryInputType;
+  storageStructures: MemoryStorageStructure[];
+}
+
+export const FILEMEM_DEFAULT_RUN_ID = "__default__";
+
+function createRandomRunId(): string {
+  return newId("run");
+}
+
+export function normalizeMemoryRunId(
+  storageMode: StorageMode | undefined,
+  runId: string,
+  createRunId: () => string = createRandomRunId,
+): string {
+  if (storageMode === "filemem") return FILEMEM_DEFAULT_RUN_ID;
+  return !runId || runId === FILEMEM_DEFAULT_RUN_ID ? createRunId() : runId;
+}
+
+export const STORAGE_MODE_VALUES: StorageMode[] = [
+  "ots",
+  "file+ots",
+  "filemem",
+];
+
+const STRUCTURED_DETAIL_SEGMENTS: MemoryDetailSegment[] = [
+  "units",
+  "search",
+  "messages",
+  "tasks",
+  "requests",
+  "dream",
+  "settings",
+];
+const FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = ["units", "settings"];
+const STRUCTURED_CARD_SHORTCUTS: MemoryCardShortcut[] = [
+  "longTerm",
+  "shortTerm",
+  "extract",
+  "consolidate",
+];
+const FILE_CARD_SHORTCUTS: MemoryCardShortcut[] = ["files"];
+const STRUCTURED_CARD_ACTIONS: MemoryCardAction[] = [
+  "units",
+  "search",
+  "settings",
+];
+const FILE_CARD_ACTIONS: MemoryCardAction[] = ["units", "settings"];
 
-/** 服务端把空值/历史行视为 ots；这里统一归一，未知值也回落 ots。 */
 export function normalizeStorageMode(
   value: string | undefined | null,
 ): StorageMode {
-  return value === "oss+ots" ? "oss+ots" : "ots";
+  if (value === "filemem") return "filemem";
+  if (value === "file+ots" || value === "oss+ots") return "file+ots";
+  return "ots";
+}
+
+export function memoryStorageSelectionForInput(
+  inputType: MemoryInputType,
+): MemoryStorageSelection {
+  return inputType === "file"
+    ? { inputType, storageStructures: ["file"] }
+    : { inputType, storageStructures: ["structured"] };
+}
+
+export function toggleMemoryFileStorage(
+  selection: MemoryStorageSelection,
+): MemoryStorageSelection {
+  if (selection.inputType === "file") {
+    return memoryStorageSelectionForInput("file");
+  }
+  return selection.storageStructures.includes("file")
+    ? memoryStorageSelectionForInput("short-term")
+    : {
+        inputType: "short-term",
+        storageStructures: ["structured", "file"],
+      };
+}
+
+export function storageSelectionToMode(
+  selection: MemoryStorageSelection,
+): StorageMode {
+  const structures = new Set(selection.storageStructures);
+  const hasDuplicates = structures.size !== selection.storageStructures.length;
+
+  if (
+    !hasDuplicates &&
+    selection.inputType === "file" &&
+    structures.size === 1 &&
+    structures.has("file")
+  ) {
+    return "filemem";
+  }
+  if (
+    !hasDuplicates &&
+    selection.inputType === "short-term" &&
+    structures.has("structured")
+  ) {
+    if (structures.size === 1) return "ots";
+    if (structures.size === 2 && structures.has("file")) return "file+ots";
+  }
+  throw new Error("Invalid memory input and storage structure combination");
+}
+
+export function storageModeToSelection(
+  value: string | undefined | null,
+): MemoryStorageSelection {
+  const mode = normalizeStorageMode(value);
+  if (mode === "filemem") return memoryStorageSelectionForInput("file");
+  if (mode === "file+ots") {
+    return {
+      inputType: "short-term",
+      storageStructures: ["structured", "file"],
+    };
+  }
+  return memoryStorageSelectionForInput("short-term");
+}
+
+export function storageModeCapabilities(value: string | undefined | null) {
+  const mode = normalizeStorageMode(value);
+  const structured = mode !== "filemem";
+  return {
+    mode,
+    files: mode !== "ots",
+    structured,
+    writableFiles: mode === "filemem",
+    forceLocalRetrieval: mode === "filemem",
+    structuredAutoSave: structured,
+    supportsExtraction: structured,
+    detailSegments: [
+      ...(structured ? STRUCTURED_DETAIL_SEGMENTS : FILE_DETAIL_SEGMENTS),
+    ],
+    cardShortcuts: [
+      ...(structured ? STRUCTURED_CARD_SHORTCUTS : FILE_CARD_SHORTCUTS),
+    ],
+    cardActions: [
+      ...(structured ? STRUCTURED_CARD_ACTIONS : FILE_CARD_ACTIONS),
+    ],
+  } as const;
+}
+
+export function resolveMemoryDetailSegment(
+  value: string | undefined | null,
+  requested: string,
+): MemoryDetailSegment {
+  const { detailSegments } = storageModeCapabilities(value);
+  return detailSegments.includes(requested as MemoryDetailSegment)
+    ? (requested as MemoryDetailSegment)
+    : "units";
 }
 
 export function isFileMemory(value: string | undefined | null): boolean {
-  return normalizeStorageMode(value) === "oss+ots";
+  return storageModeCapabilities(value).files;
+}
+
+export function isWritableFileMemory(
+  value: string | undefined | null,
+): boolean {
+  return storageModeCapabilities(value).writableFiles;
 }
 
 export function storageModeLabel(
   value: string | undefined | null,
   t?: TranslateFn,
 ): string {
+  const mode = normalizeStorageMode(value);
   if (t) {
     return t(
-      isFileMemory(value)
-        ? "memory.storageMode.fileLabel"
-        : "memory.storageMode.apiOnlyLabel",
+      mode === "filemem"
+        ? "memory.storageMode.writableFileLabel"
+        : mode === "file+ots"
+          ? "memory.storageMode.projectedFileLabel"
+          : "memory.storageMode.apiOnlyLabel",
     );
   }
-  // Locale-neutral fallback; all production callers pass `t` (see settings
-  // page, memory-create-form, memory-store-card).
-  return isFileMemory(value) ? "File Memory" : "API-only Memory";
+  if (mode === "filemem") return "Writable File Memory";
+  if (mode === "file+ots") return "Read-only File Projection";
+  return "API-only Memory";
 }
 
-/**
- * 计算记忆库绑定实际生效的检索模式。文件记忆（local）只对 `oss+ots` 库有意义；
- * 若绑定的库不是文件型，一律回落 search——避免非文件型库被选成文件记忆后走错
- * 分支报错。
- */
 export function resolveRetrievalMode(
   mode: "search" | "local" | undefined,
-  isFileStore: boolean,
+  storageMode: string | boolean | undefined | null,
 ): "search" | "local" {
-  if (!isFileStore) return "search";
+  const resolvedStorage =
+    typeof storageMode === "boolean"
+      ? storageMode
+        ? "file+ots"
+        : "ots"
+      : normalizeStorageMode(storageMode);
+  if (resolvedStorage === "filemem") return "local";
+  if (resolvedStorage === "ots") return "search";
   return mode === "local" ? "local" : "search";
 }
 
@@ -55,14 +210,21 @@ export function storageModeDescription(
   value: string | undefined | null,
   t?: TranslateFn,
 ): string {
+  const mode = normalizeStorageMode(value);
   if (t) {
     return t(
-      isFileMemory(value)
-        ? "memory.storageMode.fileDescription"
-        : "memory.storageMode.apiOnlyDescription",
+      mode === "filemem"
+        ? "memory.storageMode.writableFileDescription"
+        : mode === "file+ots"
+          ? "memory.storageMode.projectedFileDescription"
+          : "memory.storageMode.apiOnlyDescription",
     );
   }
-  return isFileMemory(value)
-    ? "Tablestore + OSS file projection: memory is additionally projected into a markdown file tree, retrievable as files in conversations and browsable in the console and CLI."
-    : "Tablestore only: read and write memory via API semantic retrieval, no file projection.";
+  if (mode === "filemem") {
+    return "Writable file memory with JSON API CRUD, version history, and local lexical retrieval.";
+  }
+  if (mode === "file+ots") {
+    return "Read-only file projection browsed through the JSON file API.";
+  }
+  return "Tablestore semantic memory without a file workspace.";
 }

package/dist/dashboard-runtime/dashboard/src/lib/memory.ts

@@ -53,6 +53,19 @@ export function formatScope(scope?: MemoryScope): string {
     .join(" / ");
 }
 
+/**
+ * Positional four-tuple label for the scope pickers. Unlike
+ * {@link formatScope}, an empty dimension keeps its slot as `—`, so rows line
+ * up column-wise in a dropdown and "no tenant" reads differently from "no
+ * agent". Shared by both pickers (ScopeCombobox and the ScopeBar) so their
+ * labels can't drift apart.
+ */
+export function scopeLabel(scope: MemoryScope): string {
+  return [scope.appId, scope.tenantId, scope.agentId, scope.runId]
+    .map((v) => v || "—")
+    .join(" / ");
+}
+
 /**
  * A set of dream tasks that share the same input scope.
  *
@@ -154,18 +167,30 @@ export function parseJsonObject(
   value: string,
 ): Record<string, string> | undefined {
   if (!value.trim()) return undefined;
-  const parsed = JSON.parse(value) as unknown;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value) as unknown;
+  } catch {
+    throw new Error(
+      '元数据 JSON 格式不正确，请检查引号与括号，例如 {"source":"chat"}',
+    );
+  }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new Error("JSON must be an object");
+    throw new Error('元数据需为 JSON 对象，例如 {"source":"chat"}');
   }
   return parsed as Record<string, string>;
 }
 
 export function parseJsonArray<T>(value: string): T[] | undefined {
   if (!value.trim()) return undefined;
-  const parsed = JSON.parse(value) as unknown;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value) as unknown;
+  } catch {
+    throw new Error("JSON 格式不正确，请检查引号与括号后重试");
+  }
   if (!Array.isArray(parsed)) {
-    throw new Error("JSON must be an array");
+    throw new Error('需要 JSON 数组，例如 [{"key":"value"}]');
   }
   return parsed as T[];
 }

package/dist/dashboard-runtime/dashboard/src/lib/query-keys.ts

@@ -1,11 +1,74 @@
 import type { QueryClient, QueryKey } from "@tanstack/react-query";
+import type { FileMemoryScope } from "@/types/file-memory";
 
 export const RUNTIME_CONTEXT_QUERY_KEY = ["runtime-context"] as const;
 export const PENDING_DATA_SCOPE_KEY = "pending";
 
+export const fileMemoryQueryKeys = {
+  root: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: FileMemoryScope,
+  ) =>
+    [
+      "memory",
+      dataScopeKey,
+      "stores",
+      memoryStoreName,
+      "file-memory",
+      scope,
+    ] as const,
+  list: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: FileMemoryScope,
+    pathPrefix?: string,
+  ) =>
+    [
+      ...fileMemoryQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "list",
+      pathPrefix,
+    ] as const,
+  item: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: FileMemoryScope,
+    address: string,
+  ) =>
+    [
+      ...fileMemoryQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "item",
+      address,
+    ] as const,
+  versions: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: FileMemoryScope,
+    itemId: string,
+  ) =>
+    [
+      ...fileMemoryQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "versions",
+      itemId,
+    ] as const,
+  version: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: FileMemoryScope,
+    versionId: string,
+  ) =>
+    [
+      ...fileMemoryQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "version",
+      versionId,
+    ] as const,
+};
+
 export const queryKeys = {
   runtimeContext: RUNTIME_CONTEXT_QUERY_KEY,
   instances: (scope: string) => ["instances", scope] as const,
+  instanceConnectivity: (scope: string) =>
+    ["instance-connectivity", scope] as const,
   instance: (scope: string, name: string | null | undefined) =>
     ["instance", scope, name] as const,
   knowledgeBases: (scope: string) => ["knowledge-bases", scope] as const,

package/dist/dashboard-runtime/dashboard/src/lib/server/api-helpers.ts

@@ -44,6 +44,11 @@ const CODE_TO_HTTP_STATUS: Record<string, number> = {
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   CONFLICT: 409,
+  PATH_EXISTS: 409,
+  LOCK_CONFLICT: 409,
+  QUOTA_EXCEEDED: 409,
+  READ_ONLY_STORE: 409,
+  PAYLOAD_TOO_LARGE: 413,
   QUOTA_EXHAUSTED: 429,
   FLOW_CONTROL: 429,
   INTERNAL_SERVER_ERROR: 500,

package/dist/dashboard-runtime/dashboard/src/lib/server/instance-connectivity.ts

@@ -0,0 +1,136 @@
+import type {
+  InstanceConnectivity,
+  InstanceConnectivityReason,
+} from "@/types/instance";
+
+const DEFAULT_TIMEOUT_MS = 3_000;
+const MAX_MESSAGE_LENGTH = 240;
+
+const DNS_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "EAI_FAIL"]);
+const CONNECTION_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+]);
+const TLS_CODES = new Set([
+  "CERT_HAS_EXPIRED",
+  "CERT_NOT_YET_VALID",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+]);
+
+interface ProbeOptions {
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+  now?: () => number;
+}
+
+interface ErrorDetails {
+  reason: InstanceConnectivityReason;
+  message: string;
+}
+
+function safeMessage(value: unknown): string {
+  const message =
+    value instanceof Error && value.message.trim()
+      ? value.message
+      : "Network request failed";
+  return message.replace(/\s+/g, " ").slice(0, MAX_MESSAGE_LENGTH);
+}
+
+function errorDetails(error: unknown): ErrorDetails {
+  let current: unknown = error;
+  let deepestMessage = safeMessage(error);
+  const seen = new Set<unknown>();
+
+  while (current && typeof current === "object" && !seen.has(current)) {
+    seen.add(current);
+    const record = current as {
+      cause?: unknown;
+      code?: unknown;
+      message?: unknown;
+      name?: unknown;
+    };
+    if (typeof record.message === "string" && record.message.trim()) {
+      deepestMessage = record.message.replace(/\s+/g, " ");
+    }
+    if (record.name === "TimeoutError" || record.name === "AbortError") {
+      return { reason: "timeout", message: safeMessage(current) };
+    }
+    const code = typeof record.code === "string" ? record.code : "";
+    if (DNS_CODES.has(code)) {
+      return { reason: "dns", message: safeMessage(current) };
+    }
+    if (CONNECTION_CODES.has(code)) {
+      return { reason: "connection", message: safeMessage(current) };
+    }
+    if (TLS_CODES.has(code) || code.startsWith("ERR_TLS_")) {
+      return { reason: "tls", message: safeMessage(current) };
+    }
+    current = record.cause;
+  }
+
+  return {
+    reason: "network",
+    message: deepestMessage.replace(/\s+/g, " ").slice(0, MAX_MESSAGE_LENGTH),
+  };
+}
+
+export async function probeInstanceEndpoint(
+  endpoint: string,
+  options: ProbeOptions = {},
+): Promise<InstanceConnectivity> {
+  const now = options.now ?? Date.now;
+  const startedAt = now();
+  const checkedAt = () => new Date(now()).toISOString();
+
+  if (!endpoint.trim()) {
+    return { configured: false, reachable: null, checkedAt: checkedAt() };
+  }
+
+  let url: string;
+  try {
+    const parsed = new URL(endpoint);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+      throw new TypeError("unsupported protocol");
+    }
+    url = parsed.toString();
+  } catch {
+    return {
+      configured: true,
+      reachable: false,
+      checkedAt: checkedAt(),
+      latencyMs: Math.max(0, now() - startedAt),
+      reason: "network",
+      message: "Invalid endpoint URL",
+    };
+  }
+
+  try {
+    const response = await (options.fetchImpl ?? fetch)(url, {
+      method: "HEAD",
+      signal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_TIMEOUT_MS),
+      redirect: "manual",
+      cache: "no-store",
+    });
+    return {
+      configured: true,
+      reachable: true,
+      checkedAt: checkedAt(),
+      latencyMs: Math.max(0, now() - startedAt),
+      httpStatus: response.status,
+    };
+  } catch (error) {
+    return {
+      configured: true,
+      reachable: false,
+      checkedAt: checkedAt(),
+      latencyMs: Math.max(0, now() - startedAt),
+      ...errorDetails(error),
+    };
+  }
+}

package/dist/dashboard-runtime/dashboard/src/lib/server/sdk-client.ts

@@ -57,6 +57,7 @@ export const TOKEN_SOURCE_COOKIE_NAME = "tablestore_token_source";
 const COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30; // 30 days
 const RAW_TOKEN_SOURCE = "raw";
 const INSTANCE_TOKEN_SOURCE = "instance";
+const FORCE_ENV_VALUE = "1";
 
 const COOKIE_OPTIONS = {
   httpOnly: true,
@@ -272,6 +273,10 @@ function configFromEnv(): Record<string, string> | null {
   };
 }
 
+function shouldForceEnvCredentials(): boolean {
+  return process.env.TABLESTORE_DASHBOARD_FORCE_ENV === FORCE_ENV_VALUE;
+}
+
 function configFromToken(token: string): Record<string, string> {
   // decodeToken throws on malformed input; callers translate to 401.
   return decodeToken(token);
@@ -521,12 +526,13 @@ function cacheSet(key: string, value: ResolvedClients): void {
  */
 export function resolveClients(request: NextRequest): ResolvedClients {
   const token = request.cookies.get(SESSION_COOKIE_NAME)?.value;
+  const forceEnv = shouldForceEnvCredentials();
 
-  let fields: Record<string, string> | null = null;
+  let fields: Record<string, string> | null = forceEnv ? configFromEnv() : null;
   let source: CredentialSource = "env";
   let instanceName: string | null = null;
 
-  if (token) {
+  if (!forceEnv && token) {
     try {
       const tokenFields = configFromToken(token);
       if (shouldUseCookieCredentials(request, tokenFields)) {
@@ -542,7 +548,7 @@ export function resolveClients(request: NextRequest): ResolvedClients {
     }
   }
 
-  if (!fields) {
+  if (!forceEnv && !fields) {
     const fromInstance = configFromActiveInstance();
     if (fromInstance) {
       fields = fromInstance.fields;
@@ -591,6 +597,22 @@ export function inspectCredentials(request: NextRequest): {
   activeInstance: string | null;
   credentialFingerprint: string;
 } | null {
+  if (shouldForceEnvCredentials()) {
+    const fields = configFromEnv();
+    if (!fields) return null;
+    const region =
+      fields.region ||
+      inferRegionFromOtsEndpoint(fields.ots_endpoint) ||
+      DEFAULT_REGION;
+    return {
+      instanceName: fields.ots_instance_name,
+      region,
+      source: "env",
+      activeInstance: null,
+      credentialFingerprint: computeCredentialFingerprint(fields),
+    };
+  }
+
   const token = request.cookies.get(SESSION_COOKIE_NAME)?.value;
   if (token) {
     try {