@tablestore/tablestore-agent-cli 0.1.8 → 0.2.0

package/dist/dashboard-runtime/dashboard/src/hooks/use-instances.ts

@@ -21,6 +21,16 @@ import type {
   ImportInstancePayload,
   UpdateInstancePayload,
 } from "@/types/instance";
+import {
+  RUNTIME_CONTEXT_QUERY_KEY,
+  invalidateInstanceScopedQueries,
+  queryKeys,
+  resetInstanceScopedQueries,
+} from "@/lib/query-keys";
+import {
+  markDashboardRuntimeContextChange,
+  useRuntimeContext,
+} from "@/providers/runtime-context-provider";
 
 export const INSTANCES_QUERY_KEY = ["instances"] as const;
 
@@ -28,11 +38,7 @@ export const INSTANCES_QUERY_KEY = ["instances"] as const;
  *  Used after non-switch mutations (connect / import / update / delete) where
  *  the current session can keep the existing data while a refetch lands. */
 function invalidateInstanceScopedCaches(queryClient: QueryClient) {
-  queryClient.invalidateQueries({ queryKey: INSTANCES_QUERY_KEY });
-  queryClient.invalidateQueries({ queryKey: ["knowledge-bases"] });
-  queryClient.invalidateQueries({ queryKey: ["memory-stores"] });
-  queryClient.invalidateQueries({ queryKey: ["llm-providers"] });
-  queryClient.invalidateQueries({ queryKey: ["auth-status"] });
+  invalidateInstanceScopedQueries(queryClient);
 }
 
 /** Hard-reset every cache whose data is scoped to the active instance.
@@ -42,28 +48,29 @@ function invalidateInstanceScopedCaches(queryClient: QueryClient) {
  *  Mirrors the pattern recommended by TanStack Query maintainers for
  *  logout / tenant-switch flows. */
 function resetInstanceScopedCaches(queryClient: QueryClient) {
-  queryClient.removeQueries({ queryKey: ["knowledge-bases"] });
-  queryClient.removeQueries({ queryKey: ["memory-stores"] });
-  queryClient.removeQueries({ queryKey: ["llm-providers"] });
-  queryClient.removeQueries({ queryKey: ["documents"] });
-  queryClient.removeQueries({ queryKey: ["instance"] });
-  queryClient.invalidateQueries({ queryKey: INSTANCES_QUERY_KEY });
-  queryClient.invalidateQueries({ queryKey: ["auth-status"] });
+  resetInstanceScopedQueries(queryClient);
+}
+
+function refreshRuntimeContext(queryClient: QueryClient) {
+  void queryClient.invalidateQueries({ queryKey: RUNTIME_CONTEXT_QUERY_KEY });
 }
 
 export function useInstances() {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: INSTANCES_QUERY_KEY,
+    queryKey: queryKeys.instances(context.dataScopeKey),
     queryFn: listInstances,
+    enabled: ready,
     staleTime: 30 * 1000,
   });
 }
 
 export function useInstance(name: string | null | undefined) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["instance", name],
+    queryKey: queryKeys.instance(context.dataScopeKey, name),
     queryFn: () => getInstance(name as string),
-    enabled: !!name,
+    enabled: ready && !!name,
     staleTime: 30 * 1000,
   });
 }
@@ -73,7 +80,8 @@ export function useConnectInstance() {
   return useMutation({
     mutationFn: (payload: ConnectInstancePayload) => connectInstance(payload),
     onSuccess: () => {
-      invalidateInstanceScopedCaches(queryClient);
+      resetInstanceScopedCaches(queryClient);
+      refreshRuntimeContext(queryClient);
       toast.success("项目已创建");
     },
     onError: (error) => {
@@ -87,7 +95,8 @@ export function useImportInstance() {
   return useMutation({
     mutationFn: (payload: ImportInstancePayload) => importInstance(payload),
     onSuccess: () => {
-      invalidateInstanceScopedCaches(queryClient);
+      resetInstanceScopedCaches(queryClient);
+      refreshRuntimeContext(queryClient);
       toast.success("Token 已导入");
     },
     onError: (error) => {
@@ -102,7 +111,8 @@ export function useUpdateInstance(name: string) {
     mutationFn: (patch: UpdateInstancePayload) => updateInstance(name, patch),
     onSuccess: () => {
       invalidateInstanceScopedCaches(queryClient);
-      queryClient.invalidateQueries({ queryKey: ["instance", name] });
+      queryClient.invalidateQueries({ queryKey: ["instance"] });
+      refreshRuntimeContext(queryClient);
       toast.success("项目已更新");
     },
     onError: (error) => {
@@ -117,6 +127,7 @@ export function useDeleteInstance() {
     mutationFn: (name: string) => deleteInstance(name),
     onSuccess: () => {
       invalidateInstanceScopedCaches(queryClient);
+      refreshRuntimeContext(queryClient);
       toast.success("项目已删除");
     },
     onError: (error) => {
@@ -127,14 +138,22 @@ export function useDeleteInstance() {
 
 export function useSwitchInstance() {
   const queryClient = useQueryClient();
+  const { context } = useRuntimeContext();
   return useMutation({
     mutationFn: (name: string) => switchInstance(name),
-    onSuccess: () => {
+    onSuccess: ({ activeInstance }) => {
+      if (typeof window !== "undefined") {
+        markDashboardRuntimeContextChange(window.sessionStorage, {
+          previousDataScopeKey: context.dataScopeKey,
+          targetActiveInstance: activeInstance,
+        });
+      }
       // Switching the active instance is conceptually a tenant change:
       // every instance-scoped cache must be evicted (not just invalidated)
       // so the new instance never inherits the old one's KB / memory /
       // provider rows for even a single render.
       resetInstanceScopedCaches(queryClient);
+      refreshRuntimeContext(queryClient);
       toast.success("已切换当前项目");
     },
     onError: (error) => {

package/dist/dashboard-runtime/dashboard/src/hooks/use-knowledge-base.ts

@@ -1,11 +1,14 @@
 import { useQuery } from "@tanstack/react-query";
 import { describeKnowledgeBase } from "@/services/knowledge-base";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export function useKnowledgeBase(name: string) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["knowledge-bases", name],
+    queryKey: queryKeys.knowledgeBase(context.dataScopeKey, name),
     queryFn: () => describeKnowledgeBase(name),
-    enabled: !!name,
+    enabled: ready && !!name,
     staleTime: 30 * 1000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-knowledge-bases.ts

@@ -1,10 +1,14 @@
 import { useQuery } from "@tanstack/react-query";
 import { listKnowledgeBases } from "@/services/knowledge-base";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export function useKnowledgeBases() {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["knowledge-bases"],
+    queryKey: queryKeys.knowledgeBases(context.dataScopeKey),
     queryFn: listKnowledgeBases,
+    enabled: ready,
     staleTime: 30 * 1000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-llm-provider-models.ts

@@ -1,6 +1,8 @@
 import { useQuery } from "@tanstack/react-query";
 
 import { fetchProviderModels } from "@/services/llm-providers";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 /**
  * Pull the upstream model list for a provider. Disabled by default until the
@@ -11,10 +13,11 @@ export function useLLMProviderModels(
   id: string | undefined,
   options: { enabled?: boolean } = {},
 ) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["llm-provider-models", id],
+    queryKey: queryKeys.llmProviderModels(context.dataScopeKey, id),
     queryFn: () => fetchProviderModels(id!),
-    enabled: Boolean(id) && (options.enabled ?? true),
+    enabled: ready && Boolean(id) && (options.enabled ?? true),
     staleTime: 5 * 60 * 1000,
     retry: false,
   });

package/dist/dashboard-runtime/dashboard/src/hooks/use-llm-provider.ts

@@ -1,12 +1,15 @@
 import { useQuery } from "@tanstack/react-query";
 
 import { getProvider } from "@/services/llm-providers";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export function useLLMProvider(id: string | undefined) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["llm-providers", id],
+    queryKey: queryKeys.llmProvider(context.dataScopeKey, id),
     queryFn: () => getProvider(id!),
-    enabled: Boolean(id),
+    enabled: ready && Boolean(id),
     staleTime: 30 * 1000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-llm-providers.ts

@@ -1,13 +1,17 @@
 import { useQuery } from "@tanstack/react-query";
 
 import { listProviders } from "@/services/llm-providers";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export const LLM_PROVIDERS_QUERY_KEY = ["llm-providers"] as const;
 
 export function useLLMProviders() {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: LLM_PROVIDERS_QUERY_KEY,
+    queryKey: queryKeys.llmProviders(context.dataScopeKey),
     queryFn: listProviders,
+    enabled: ready,
     staleTime: 30 * 1000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-messages.ts

@@ -1,5 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { listMemoryMessages } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 import type { MemoryScope } from "@/types/memory";
 
 export function useMemoryMessages(
@@ -10,12 +12,16 @@ export function useMemoryMessages(
   enabled = true,
   filters?: { minTimestamp?: string; maxTimestamp?: string },
 ) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: [
-      "memory", "stores", memoryStoreName, "messages",
-      scope, nextToken, limit,
-      filters?.minTimestamp, filters?.maxTimestamp,
-    ],
+    queryKey: queryKeys.memoryMessages(
+      context.dataScopeKey,
+      memoryStoreName,
+      scope,
+      nextToken,
+      limit,
+      filters,
+    ),
     queryFn: () =>
       listMemoryMessages(memoryStoreName, scope!, {
         nextToken,
@@ -23,7 +29,7 @@ export function useMemoryMessages(
         minTimestamp: filters?.minTimestamp,
         maxTimestamp: filters?.maxTimestamp,
       }),
-    enabled: enabled && !!memoryStoreName && !!scope?.appId,
+    enabled: ready && enabled && !!memoryStoreName && !!scope?.appId,
     staleTime: 30_000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-requests.ts

@@ -1,5 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { listMemoryRequests } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 import type { MemoryScope } from "@/types/memory";
 
 export function useMemoryRequests(
@@ -9,9 +11,17 @@ export function useMemoryRequests(
   limit = 20,
   operation?: string
 ) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["memory", "stores", memoryStoreName, "requests", scope, nextToken, limit, operation],
+    queryKey: queryKeys.memoryRequests(
+      context.dataScopeKey,
+      memoryStoreName,
+      scope,
+      nextToken,
+      limit,
+      operation,
+    ),
     queryFn: () => listMemoryRequests(memoryStoreName, scope!, { nextToken, limit, operation }),
-    enabled: !!memoryStoreName && !!scope?.appId,
+    enabled: ready && !!memoryStoreName && !!scope?.appId,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-store.ts

@@ -1,10 +1,13 @@
 import { useQuery } from "@tanstack/react-query";
 import { describeMemoryStore } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export function useMemoryStore(memoryStoreName: string) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["memory", "stores", memoryStoreName],
+    queryKey: queryKeys.memoryStore(context.dataScopeKey, memoryStoreName),
     queryFn: () => describeMemoryStore(memoryStoreName),
-    enabled: !!memoryStoreName,
+    enabled: ready && !!memoryStoreName,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-stores.ts

@@ -1,10 +1,14 @@
 import { useQuery } from "@tanstack/react-query";
 import { listMemoryStores } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 
 export function useMemoryStores() {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["memory", "stores"],
+    queryKey: queryKeys.memoryStores(context.dataScopeKey),
     queryFn: listMemoryStores,
+    enabled: ready,
     staleTime: 30 * 1000,
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-unit.ts

@@ -1,5 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { getMemoryUnit } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 import type { MemoryScope } from "@/types/memory";
 
 export function useMemoryUnit(
@@ -8,9 +10,21 @@ export function useMemoryUnit(
   scope: MemoryScope | null,
   enabled = true
 ) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["memory", "stores", memoryStoreName, "units", "detail", memoryId, scope],
+    queryKey: queryKeys.memoryUnit(
+      context.dataScopeKey,
+      memoryStoreName,
+      memoryId,
+      scope,
+    ),
     queryFn: () => getMemoryUnit({ memoryStoreName, memoryId: memoryId!, scope: scope! }),
-    enabled: enabled && !!memoryStoreName && !!scope?.appId && !!memoryId && memoryId !== "-",
+    enabled:
+      ready &&
+      enabled &&
+      !!memoryStoreName &&
+      !!scope?.appId &&
+      !!memoryId &&
+      memoryId !== "-",
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-memory-units.ts

@@ -1,5 +1,7 @@
 import { useQuery } from "@tanstack/react-query";
 import { listMemoryUnits } from "@/services/memory";
+import { queryKeys } from "@/lib/query-keys";
+import { useRuntimeContext } from "@/providers/runtime-context-provider";
 import type { MemoryScope } from "@/types/memory";
 
 export function useMemoryUnits(
@@ -8,10 +10,17 @@ export function useMemoryUnits(
   nextToken?: string,
   limit = 20
 ) {
+  const { context, ready } = useRuntimeContext();
   return useQuery({
-    queryKey: ["memory", "stores", memoryStoreName, "units", scope, nextToken, limit],
+    queryKey: queryKeys.memoryUnits(
+      context.dataScopeKey,
+      memoryStoreName,
+      scope,
+      nextToken,
+      limit,
+    ),
     queryFn: () => listMemoryUnits(memoryStoreName, scope!, { nextToken, limit }),
-    enabled: !!memoryStoreName && !!scope?.appId,
+    enabled: ready && !!memoryStoreName && !!scope?.appId,
     staleTime: 30_000,
   });
 }

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

@@ -23,6 +23,7 @@ import type { ChatMessage, ChatRequestBody, ChatRole } from "@/types/llm-chat";
 type StreamPatch = { content?: string; reasoning?: string };
 
 export interface UseQaChatOptions {
+  activeInstance: string | null;
   providerId: string;
   model: string;
   systemPrompt: string;
@@ -203,6 +204,7 @@ export function useQaChat(options: UseQaChatOptions): UseQaChatResult {
 
       try {
         const body: ChatRequestBody = {
+          activeInstance: opts.activeInstance,
           providerId: opts.providerId,
           model: opts.model,
           messages: historyToSend,

package/dist/dashboard-runtime/dashboard/src/hooks/use-update-kb.ts

@@ -1,17 +1,15 @@
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { updateKnowledgeBase } from "@/services/knowledge-base";
 import type { UpdateKBRequest } from "@/types/knowledge-base";
+import { invalidateKnowledgeBaseQueries } from "@/lib/query-keys";
 
 export function useUpdateKB() {
   const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: (request: UpdateKBRequest) => updateKnowledgeBase(request),
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({ queryKey: ["knowledge-bases"] });
-      queryClient.invalidateQueries({
-        queryKey: ["knowledge-bases", variables.knowledgeBaseName],
-      });
+    onSuccess: () => {
+      invalidateKnowledgeBaseQueries(queryClient);
     },
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-update-llm-provider.ts

@@ -2,16 +2,14 @@ import { useMutation, useQueryClient } from "@tanstack/react-query";
 
 import { updateProvider } from "@/services/llm-providers";
 import type { UpdateLLMProviderInput } from "@/types/llm-provider";
-
-import { LLM_PROVIDERS_QUERY_KEY } from "./use-llm-providers";
+import { invalidateLLMProviderQueries } from "@/lib/query-keys";
 
 export function useUpdateLLMProvider(id: string) {
   const queryClient = useQueryClient();
   return useMutation({
     mutationFn: (patch: UpdateLLMProviderInput) => updateProvider(id, patch),
     onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: LLM_PROVIDERS_QUERY_KEY });
-      queryClient.invalidateQueries({ queryKey: ["llm-providers", id] });
+      invalidateLLMProviderQueries(queryClient);
     },
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-update-memory-store.ts

@@ -1,17 +1,15 @@
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { updateMemoryStore } from "@/services/memory";
 import type { UpdateMemoryStoreRequest } from "@/types/memory";
+import { invalidateMemoryQueries } from "@/lib/query-keys";
 
 export function useUpdateMemoryStore() {
   const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: (request: UpdateMemoryStoreRequest) => updateMemoryStore(request),
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({ queryKey: ["memory", "stores"] });
-      queryClient.invalidateQueries({
-        queryKey: ["memory", "stores", variables.memoryStoreName],
-      });
+    onSuccess: () => {
+      invalidateMemoryQueries(queryClient);
     },
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-update-memory-unit.ts

@@ -1,14 +1,15 @@
 import { useMutation, useQueryClient } from "@tanstack/react-query";
 import { updateMemoryUnit } from "@/services/memory";
 import type { UpdateMemoryUnitRequest } from "@/types/memory";
+import { invalidateMemoryQueries } from "@/lib/query-keys";
 
 export function useUpdateMemoryUnit() {
   const queryClient = useQueryClient();
 
   return useMutation({
     mutationFn: (request: UpdateMemoryUnitRequest) => updateMemoryUnit(request),
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({ queryKey: ["memory", "stores", variables.memoryStoreName, "units"] });
+    onSuccess: () => {
+      invalidateMemoryQueries(queryClient);
     },
   });
 }

package/dist/dashboard-runtime/dashboard/src/hooks/use-upload-documents.ts

@@ -1,5 +1,10 @@
+import { useCallback, useRef, useState } from "react";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
-import { uploadDocuments } from "@/services/documents";
+import {
+  uploadDocumentsBatched,
+  type BatchUploadProgress,
+} from "@/services/documents";
+import { invalidateKnowledgeBaseQueries } from "@/lib/query-keys";
 
 interface UploadDocumentsVariables {
   knowledgeBaseName: string;
@@ -10,14 +15,28 @@ interface UploadDocumentsVariables {
 
 export function useUploadDocuments() {
   const queryClient = useQueryClient();
+  const [progress, setProgress] = useState<BatchUploadProgress | null>(null);
+  const progressRef = useRef(progress);
+  progressRef.current = progress;
 
-  return useMutation({
+  const resetProgress = useCallback(() => setProgress(null), []);
+
+  const mutation = useMutation({
     mutationFn: ({ knowledgeBaseName, files, subspace, metadata }: UploadDocumentsVariables) =>
-      uploadDocuments(knowledgeBaseName, files, { subspace, metadata }),
-    onSuccess: (_data, variables) => {
-      queryClient.invalidateQueries({
-        queryKey: ["knowledge-bases", variables.knowledgeBaseName, "documents"],
-      });
+      uploadDocumentsBatched(knowledgeBaseName, files, {
+        subspace,
+        metadata,
+        onProgress: setProgress,
+      }),
+    onSuccess: () => {
+      invalidateKnowledgeBaseQueries(queryClient);
+    },
+    onSettled: () => {
+      // Keep progress visible briefly so the user can read the final state,
+      // then clear it for the next upload.
+      setTimeout(resetProgress, 300);
     },
   });
+
+  return { ...mutation, progress };
 }

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

@@ -0,0 +1,22 @@
+export const DEFAULT_PAGE_SIZE = 20;
+
+export const KB_NAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_-]{1,62}[a-zA-Z0-9]$/;
+
+export const ERROR_CODE_MAP = {
+  INVALID_PARAMETER: "参数错误",
+  NOT_FOUND: "资源不存在",
+  ALREADY_EXISTS: "资源已存在",
+  INTERNAL_ERROR: "服务内部错误",
+  UNAUTHORIZED: "未授权",
+  RATE_LIMITED: "请求过于频繁",
+} as const satisfies Record<string, string>;
+
+export const METADATA_TYPES = [
+  "keyword",
+  "text",
+  "long",
+  "double",
+  "boolean",
+] as const;
+
+export type MetadataType = (typeof METADATA_TYPES)[number];

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

@@ -0,0 +1,9 @@
+/**
+ * The dashboard must build in offline / intranet environments, including the
+ * CLI's standalone packaging flow. `next/font/google` hard-fails the build
+ * when fonts.googleapis.com is unreachable, so we expose no-op descriptors
+ * here and rely on CSS fallback stacks declared in `globals.css`.
+ */
+export const plusJakarta = { variable: "" } as const;
+export const inter = { variable: "" } as const;
+export const jetbrainsMono = { variable: "" } as const;

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

@@ -0,0 +1,69 @@
+import type { MemoryScope } from "@/types/memory";
+
+export function buildMemoryScope(searchParams: URLSearchParams): MemoryScope {
+  return {
+    appId: searchParams.get("appId") ?? "",
+    tenantId: searchParams.get("tenantId") || undefined,
+    agentId: searchParams.get("agentId") || undefined,
+    runId: searchParams.get("runId") || undefined,
+  };
+}
+
+export function hasWildcardScope(scope: MemoryScope): boolean {
+  return Object.values(scope).some((value) => value === "*");
+}
+
+/** All four scope fields are present and none is `*`. */
+export function hasPreciseScope(scope: MemoryScope): boolean {
+  return (
+    !!scope.appId && scope.appId !== "*" &&
+    !!scope.tenantId && scope.tenantId !== "*" &&
+    !!scope.agentId && scope.agentId !== "*" &&
+    !!scope.runId && scope.runId !== "*"
+  );
+}
+
+/** appId and tenantId are present and not `*` (minimum for search). */
+export function hasSearchableScope(scope: MemoryScope): boolean {
+  return (
+    !!scope.appId && scope.appId !== "*" &&
+    !!scope.tenantId && scope.tenantId !== "*"
+  );
+}
+
+export function scopeToSearchParams(scope: MemoryScope): URLSearchParams {
+  const params = new URLSearchParams();
+  params.set("appId", scope.appId);
+  if (scope.tenantId) params.set("tenantId", scope.tenantId);
+  if (scope.agentId) params.set("agentId", scope.agentId);
+  if (scope.runId) params.set("runId", scope.runId);
+  return params;
+}
+
+export function formatScope(scope?: MemoryScope): string {
+  if (!scope) return "-";
+  return [
+    scope.appId,
+    scope.tenantId,
+    scope.agentId,
+    scope.runId,
+  ].filter(Boolean).join(" / ");
+}
+
+export function parseJsonObject(value: string): Record<string, string> | undefined {
+  if (!value.trim()) return undefined;
+  const parsed = JSON.parse(value) as unknown;
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("JSON must be an object");
+  }
+  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;
+  if (!Array.isArray(parsed)) {
+    throw new Error("JSON must be an array");
+  }
+  return parsed as T[];
+}