@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

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

@@ -1,11 +1,24 @@
 import type { TranslateFn } from "@/i18n/i18n-context";
 import { newId } from "@/lib/random-id";
 
-export type StorageMode = "ots" | "file+ots" | "filemem";
+/**
+ * `managed-file` is a console capability label for the current
+ * messages -> [file] contract.  It is never sent as the legacy storageMode
+ * wire field.
+ */
+export type StorageMode = "ots" | "managed-file" | "file+ots" | "filemem";
 export type MemoryInputType = "short-term" | "file";
 export type MemoryStorageStructure = "structured" | "file";
 export type MemoryDetailSegment =
-  "units" | "search" | "messages" | "tasks" | "requests" | "dream" | "settings";
+  | "scope"
+  | "units"
+  | "search"
+  | "messages"
+  | "tasks"
+  | "requests"
+  | "dream"
+  | "wiki"
+  | "settings";
 export type MemoryCardShortcut =
   "longTerm" | "shortTerm" | "extract" | "consolidate" | "files";
 export type MemoryCardAction = "units" | "search" | "settings";
@@ -15,6 +28,17 @@ export interface MemoryStorageSelection {
   storageStructures: MemoryStorageStructure[];
 }
 
+export interface MemoryStoreTypeContract {
+  inputType: "messages" | "file";
+  outputTypes: MemoryStorageStructure[];
+}
+
+export interface MemoryStoreTypeSource {
+  inputType?: "messages" | "file";
+  outputTypes?: MemoryStorageStructure[];
+  storageMode?: string | null;
+}
+
 export const FILEMEM_DEFAULT_RUN_ID = "__default__";
 
 function createRandomRunId(): string {
@@ -30,22 +54,47 @@ export function normalizeMemoryRunId(
   return !runId || runId === FILEMEM_DEFAULT_RUN_ID ? createRunId() : runId;
 }
 
-export const STORAGE_MODE_VALUES: StorageMode[] = [
+export const STORAGE_MODE_VALUES = [
   "ots",
+  "managed-file",
   "file+ots",
   "filemem",
-];
+] as const satisfies readonly StorageMode[];
+
+export function isKnownStorageMode(value: unknown): value is StorageMode {
+  return (
+    typeof value === "string" &&
+    (STORAGE_MODE_VALUES as readonly string[]).includes(value)
+  );
+}
 
 const STRUCTURED_DETAIL_SEGMENTS: MemoryDetailSegment[] = [
+  "scope",
   "units",
   "search",
   "messages",
   "tasks",
   "requests",
   "dream",
+  "wiki",
+  "settings",
+];
+const FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = [
+  "scope",
+  "units",
+  "wiki",
+  "settings",
+];
+const MANAGED_FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = [
+  "scope",
+  "units",
+  "search",
+  "messages",
+  "tasks",
+  "requests",
+  "wiki",
   "settings",
 ];
-const FILE_DETAIL_SEGMENTS: MemoryDetailSegment[] = ["units", "settings"];
 const STRUCTURED_CARD_SHORTCUTS: MemoryCardShortcut[] = [
   "longTerm",
   "shortTerm",
@@ -53,7 +102,7 @@ const STRUCTURED_CARD_SHORTCUTS: MemoryCardShortcut[] = [
   "consolidate",
 ];
 const FILE_CARD_SHORTCUTS: MemoryCardShortcut[] = ["files"];
-const STRUCTURED_CARD_ACTIONS: MemoryCardAction[] = [
+const SEARCHABLE_CARD_ACTIONS: MemoryCardAction[] = [
   "units",
   "search",
   "settings",
@@ -63,9 +112,17 @@ const FILE_CARD_ACTIONS: MemoryCardAction[] = ["units", "settings"];
 export function normalizeStorageMode(
   value: string | undefined | null,
 ): StorageMode {
-  if (value === "filemem") return "filemem";
+  return parseKnownStorageMode(value) ?? "ots";
+}
+
+export function parseKnownStorageMode(
+  value: string | undefined | null,
+): StorageMode | null {
+  if (value === "ots") return "ots";
+  if (value === "managed-file") return "managed-file";
   if (value === "file+ots" || value === "oss+ots") return "file+ots";
-  return "ots";
+  if (value === "filemem") return "filemem";
+  return null;
 }
 
 export function memoryStorageSelectionForInput(
@@ -90,6 +147,23 @@ export function toggleMemoryFileStorage(
       };
 }
 
+export function toggleMemoryStructuredStorage(
+  selection: MemoryStorageSelection,
+): MemoryStorageSelection {
+  if (selection.inputType === "file") {
+    return memoryStorageSelectionForInput("file");
+  }
+  if (selection.storageStructures.includes("structured")) {
+    return selection.storageStructures.includes("file")
+      ? { inputType: "short-term", storageStructures: ["file"] }
+      : selection;
+  }
+  return {
+    inputType: "short-term",
+    storageStructures: ["structured", "file"],
+  };
+}
+
 export function storageSelectionToMode(
   selection: MemoryStorageSelection,
 ): StorageMode {
@@ -107,19 +181,39 @@ export function storageSelectionToMode(
   if (
     !hasDuplicates &&
     selection.inputType === "short-term" &&
-    structures.has("structured")
+    structures.size > 0
   ) {
-    if (structures.size === 1) return "ots";
+    if (structures.size === 1 && structures.has("structured")) return "ots";
+    if (structures.size === 1 && structures.has("file")) return "managed-file";
     if (structures.size === 2 && structures.has("file")) return "file+ots";
   }
   throw new Error("Invalid memory input and storage structure combination");
 }
 
+/**
+ * Convert the console selection to the current server contract.  New stores
+ * must use inputType/outputTypes instead of the legacy storageMode alias so a
+ * messages -> file-only store is not collapsed into one of the old modes.
+ */
+export function storageSelectionToStoreType(
+  selection: MemoryStorageSelection,
+): MemoryStoreTypeContract {
+  // Reuse the strict combination validation above before translating labels.
+  storageSelectionToMode(selection);
+  return {
+    inputType: selection.inputType === "short-term" ? "messages" : "file",
+    outputTypes: [...selection.storageStructures],
+  };
+}
+
 export function storageModeToSelection(
   value: string | undefined | null,
 ): MemoryStorageSelection {
   const mode = normalizeStorageMode(value);
   if (mode === "filemem") return memoryStorageSelectionForInput("file");
+  if (mode === "managed-file") {
+    return { inputType: "short-term", storageStructures: ["file"] };
+  }
   if (mode === "file+ots") {
     return {
       inputType: "short-term",
@@ -129,25 +223,47 @@ export function storageModeToSelection(
   return memoryStorageSelectionForInput("short-term");
 }
 
+export function resolveMemoryStoreTypeContract(
+  store: MemoryStoreTypeSource,
+): MemoryStoreTypeContract {
+  const fallback = storageSelectionToStoreType(
+    storageModeToSelection(store.storageMode),
+  );
+  return {
+    inputType: store.inputType ?? fallback.inputType,
+    outputTypes:
+      store.outputTypes && store.outputTypes.length > 0
+        ? [...store.outputTypes]
+        : fallback.outputTypes,
+  };
+}
+
 export function storageModeCapabilities(value: string | undefined | null) {
   const mode = normalizeStorageMode(value);
-  const structured = mode !== "filemem";
+  const structured = mode === "ots" || mode === "file+ots";
+  const acceptsMessages = mode !== "filemem";
+  let detailSegments = FILE_DETAIL_SEGMENTS;
+  if (mode === "managed-file") {
+    detailSegments = MANAGED_FILE_DETAIL_SEGMENTS;
+  } else if (structured) {
+    detailSegments = STRUCTURED_DETAIL_SEGMENTS;
+  }
   return {
     mode,
-    files: mode !== "ots",
+    files: mode === "managed-file" || mode === "file+ots" || mode === "filemem",
     structured,
     writableFiles: mode === "filemem",
     forceLocalRetrieval: mode === "filemem",
     structuredAutoSave: structured,
     supportsExtraction: structured,
-    detailSegments: [
-      ...(structured ? STRUCTURED_DETAIL_SEGMENTS : FILE_DETAIL_SEGMENTS),
-    ],
+    acceptsMessages,
+    discoverableScopes: acceptsMessages,
+    detailSegments: [...detailSegments],
     cardShortcuts: [
       ...(structured ? STRUCTURED_CARD_SHORTCUTS : FILE_CARD_SHORTCUTS),
     ],
     cardActions: [
-      ...(structured ? STRUCTURED_CARD_ACTIONS : FILE_CARD_ACTIONS),
+      ...(mode === "filemem" ? FILE_CARD_ACTIONS : SEARCHABLE_CARD_ACTIONS),
     ],
   } as const;
 }
@@ -178,15 +294,19 @@ export function storageModeLabel(
 ): string {
   const mode = normalizeStorageMode(value);
   if (t) {
-    return t(
-      mode === "filemem"
-        ? "memory.storageMode.writableFileLabel"
-        : mode === "file+ots"
-          ? "memory.storageMode.projectedFileLabel"
-          : "memory.storageMode.apiOnlyLabel",
-    );
+    if (mode === "filemem") {
+      return t("memory.storageMode.writableFileLabel");
+    }
+    if (mode === "managed-file") {
+      return t("memory.storageMode.managedFileLabel");
+    }
+    if (mode === "file+ots") {
+      return t("memory.storageMode.projectedFileLabel");
+    }
+    return t("memory.storageMode.apiOnlyLabel");
   }
   if (mode === "filemem") return "Writable File Memory";
+  if (mode === "managed-file") return "Managed File Memory";
   if (mode === "file+ots") return "Read-only File Projection";
   return "API-only Memory";
 }
@@ -195,14 +315,16 @@ export function resolveRetrievalMode(
   mode: "search" | "local" | undefined,
   storageMode: string | boolean | undefined | null,
 ): "search" | "local" {
-  const resolvedStorage =
-    typeof storageMode === "boolean"
-      ? storageMode
-        ? "file+ots"
-        : "ots"
-      : normalizeStorageMode(storageMode);
+  let resolvedStorage: StorageMode;
+  if (typeof storageMode === "boolean") {
+    resolvedStorage = storageMode ? "file+ots" : "ots";
+  } else {
+    resolvedStorage = normalizeStorageMode(storageMode);
+  }
   if (resolvedStorage === "filemem") return "local";
-  if (resolvedStorage === "ots") return "search";
+  if (resolvedStorage === "ots" || resolvedStorage === "managed-file") {
+    return "search";
+  }
   return mode === "local" ? "local" : "search";
 }
 
@@ -212,17 +334,23 @@ export function storageModeDescription(
 ): string {
   const mode = normalizeStorageMode(value);
   if (t) {
-    return t(
-      mode === "filemem"
-        ? "memory.storageMode.writableFileDescription"
-        : mode === "file+ots"
-          ? "memory.storageMode.projectedFileDescription"
-          : "memory.storageMode.apiOnlyDescription",
-    );
+    if (mode === "filemem") {
+      return t("memory.storageMode.writableFileDescription");
+    }
+    if (mode === "managed-file") {
+      return t("memory.storageMode.managedFileDescription");
+    }
+    if (mode === "file+ots") {
+      return t("memory.storageMode.projectedFileDescription");
+    }
+    return t("memory.storageMode.apiOnlyDescription");
   }
   if (mode === "filemem") {
     return "Writable file memory with JSON API CRUD, version history, and local lexical retrieval.";
   }
+  if (mode === "managed-file") {
+    return "Short-term messages are consolidated into a managed, read-only file tree.";
+  }
   if (mode === "file+ots") {
     return "Read-only file projection browsed through the JSON file API.";
   }

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

@@ -0,0 +1,9 @@
+export type MemoryUnitsViewMode = "units" | "files";
+
+/** Adding a message only invalidates the structured list while that list is
+ * active. The files view disables its units query and must not refetch it. */
+export function shouldRefreshUnitsAfterAdd(
+  viewMode: MemoryUnitsViewMode,
+): boolean {
+  return viewMode === "units";
+}

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

@@ -27,14 +27,9 @@ export function hasPreciseScope(scope: MemoryScope): boolean {
   );
 }
 
-/** appId and tenantId are present and not `*` (minimum for search). */
+/** The current SearchMemories contract only requires an exact appId. */
 export function hasSearchableScope(scope: MemoryScope): boolean {
-  return (
-    !!scope.appId &&
-    scope.appId !== "*" &&
-    !!scope.tenantId &&
-    scope.tenantId !== "*"
-  );
+  return !!scope.appId && scope.appId !== "*";
 }
 
 export function scopeToSearchParams(scope: MemoryScope): URLSearchParams {

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

@@ -1,5 +1,6 @@
 import type { QueryClient, QueryKey } from "@tanstack/react-query";
 import type { FileMemoryScope } from "@/types/file-memory";
+import type { WikiScope } from "@/types/wiki";
 
 export const RUNTIME_CONTEXT_QUERY_KEY = ["runtime-context"] as const;
 export const PENDING_DATA_SCOPE_KEY = "pending";
@@ -64,6 +65,97 @@ export const fileMemoryQueryKeys = {
     ] as const,
 };
 
+export const wikiQueryKeys = {
+  root: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope | undefined,
+  ) =>
+    [
+      "wiki",
+      dataScopeKey,
+      memoryStoreName,
+      scope?.appId ?? "",
+      scope?.tenantId ?? "",
+      scope?.agentId ?? "",
+    ] as const,
+  detail: (dataScopeKey: string, memoryStoreName: string, scope: WikiScope) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "detail",
+    ] as const,
+  sources: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    limit?: number,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "sources",
+      limit ?? null,
+    ] as const,
+  artifacts: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    kind: "skill" | "profile",
+    limit?: number,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "artifacts",
+      kind,
+      limit ?? null,
+    ] as const,
+  source: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    path: string,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "source",
+      path,
+    ] as const,
+  pages: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    limit?: number,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "pages",
+      limit ?? null,
+    ] as const,
+  page: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    path: string,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "page",
+      path,
+    ] as const,
+  search: (
+    dataScopeKey: string,
+    memoryStoreName: string,
+    scope: WikiScope,
+    query: string,
+    limit?: number,
+  ) =>
+    [
+      ...wikiQueryKeys.root(dataScopeKey, memoryStoreName, scope),
+      "search",
+      query,
+      limit ?? null,
+    ] as const,
+};
+
 export const queryKeys = {
   runtimeContext: RUNTIME_CONTEXT_QUERY_KEY,
   instances: (scope: string) => ["instances", scope] as const,
@@ -202,6 +294,19 @@ export const queryKeys = {
       nextToken,
       limit,
     ] as const,
+  memoryScopeDirectory: (
+    scopeKey: string,
+    memoryStoreName: string,
+    requestKey: string,
+  ) =>
+    [
+      "memory",
+      scopeKey,
+      "stores",
+      memoryStoreName,
+      "scope-directory",
+      requestKey,
+    ] as const,
   memoryTasks: (
     scopeKey: string,
     memoryStoreName: string,
@@ -314,6 +419,7 @@ const INSTANCE_SCOPED_QUERY_ROOTS = new Set([
   "knowledge-bases",
   "chunks",
   "memory",
+  "wiki",
   "llm-providers",
   "llm-provider-models",
   "api-keys",

package/dist/dashboard-runtime/dashboard/src/lib/retrieval-security.ts

@@ -0,0 +1,54 @@
+export type RetrievalSecurityCode = "UNAUTHORIZED" | "FORBIDDEN";
+export type RetrievalSecuritySource = "memory" | "wiki";
+
+function publicMessage(
+  source: RetrievalSecuritySource,
+  code: RetrievalSecurityCode,
+): string {
+  const label = source === "memory" ? "Memory" : "Wiki";
+  return code === "UNAUTHORIZED"
+    ? `${label} authentication failed`
+    : `${label} access is forbidden`;
+}
+
+export class FatalRetrievalSecurityError extends Error {
+  readonly source: RetrievalSecuritySource;
+  readonly code: RetrievalSecurityCode;
+
+  constructor(source: RetrievalSecuritySource, code: RetrievalSecurityCode) {
+    super(publicMessage(source, code));
+    this.name = "FatalRetrievalSecurityError";
+    this.source = source;
+    this.code = code;
+  }
+}
+
+function errorRecord(value: unknown): Record<string, unknown> {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function codeFromStatus(status: unknown): RetrievalSecurityCode | undefined {
+  if (status === 401) return "UNAUTHORIZED";
+  if (status === 403) return "FORBIDDEN";
+  return undefined;
+}
+
+export function retrievalSecurityCode(
+  value: unknown,
+): RetrievalSecurityCode | undefined {
+  if (value instanceof FatalRetrievalSecurityError) return value.code;
+
+  const record = errorRecord(value);
+  if (record.code === "UNAUTHORIZED" || record.code === "FORBIDDEN") {
+    return record.code;
+  }
+  const details = errorRecord(record.details);
+  return (
+    codeFromStatus(details.upstreamStatus) ??
+    codeFromStatus(record.upstreamStatus) ??
+    codeFromStatus(record.httpStatus) ??
+    codeFromStatus(record.status)
+  );
+}

package/dist/dashboard-runtime/dashboard/src/lib/scope-directory.ts

@@ -0,0 +1,97 @@
+import type {
+  MemoryScopeDirectoryEntry,
+  ScopeDirectoryFilter,
+} from "@/types/memory";
+import { buildScopeWorkspaceHref } from "@/lib/scope-workspace";
+
+export type ScopeDirectoryTypeFilter = "all" | "conversation" | "wiki";
+export type ScopeDirectoryMatchOp = "eq" | "prefix" | "wildcard";
+
+export interface ScopeDirectoryFilterInput {
+  scopeType: ScopeDirectoryTypeFilter;
+  field?: string;
+  op?: ScopeDirectoryMatchOp;
+  value?: string;
+}
+
+/** React state boundary for opaque pagination tokens. Tokens must never
+ * survive a Store or runtime data-scope transition. */
+export function buildScopeDirectoryStateKey(
+  dataScopeKey: string,
+  memoryStoreName: string,
+): string {
+  return JSON.stringify([dataScopeKey, memoryStoreName]);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+/** Only an exact four-part conversation Scope can open the point-lookup
+ * workspace. Directory entries with omitted dimensions remain browseable but
+ * must not be turned into a different Scope by filling synthetic sentinels. */
+export function buildScopeDirectoryWorkspaceHref(
+  memoryStoreName: string,
+  entry: MemoryScopeDirectoryEntry,
+): string | null {
+  if (
+    entry.scopeType !== "conversation" ||
+    !isNonEmptyString(entry.appId) ||
+    !isNonEmptyString(entry.tenantId) ||
+    !isNonEmptyString(entry.agentId) ||
+    !isNonEmptyString(entry.runId)
+  ) {
+    return null;
+  }
+  return buildScopeWorkspaceHref(memoryStoreName, {
+    appId: entry.appId,
+    tenantId: entry.tenantId,
+    agentId: entry.agentId,
+    runId: entry.runId,
+  });
+}
+
+/** Build the small visual filter form into the server's full Filter AST. */
+export function buildScopeDirectoryFilter(
+  input: ScopeDirectoryFilterInput,
+): ScopeDirectoryFilter {
+  const conditions: ScopeDirectoryFilter[] = [];
+  if (input.scopeType !== "all") {
+    conditions.push({
+      op: "eq",
+      field: "scopeType",
+      value: input.scopeType,
+    });
+  }
+  const field = input.field?.trim();
+  const value = input.value?.trim();
+  if (field && value) {
+    conditions.push({
+      op: input.op ?? "eq",
+      field,
+      value,
+    });
+  }
+  // A filter-only query is how callers request the whole heterogeneous
+  // directory. Omitting both scope and filter would mean the legacy default
+  // conversation scope instead.
+  if (conditions.length === 0) {
+    return { op: "exists", field: "scopeType" };
+  }
+  return conditions.length === 1 ? conditions[0] : { op: "and", conditions };
+}
+
+/** Legacy stores may reject a Filter AST with a generic 400. Scope-only
+ * requests must never be classified this way because they sent no Filter. */
+export function isScopeDirectoryUnsupported(
+  error: unknown,
+  usedFilter: boolean,
+): boolean {
+  if (!usedFilter || !(error instanceof Error)) return false;
+  const code =
+    "code" in error && typeof error.code === "string" ? error.code : "";
+  return (
+    code === "INVALID_PARAMETER" ||
+    error.message.toLowerCase().includes("invalid parameter")
+  );
+}