@tablestore/tablestore-agent-cli 0.1.7 → 0.1.9

package/dist/dashboard-runtime/dashboard/src/lib/dev-flags.ts

@@ -0,0 +1,24 @@
+/**
+ * Tiny dev-only feature toggle reader. Backed by localStorage so a developer
+ * can flip a flag from the browser devtools console without rebuilding:
+ *
+ *   localStorage.setItem("tsagent.dev.logChatRequest", "1")
+ *
+ * Production builds keep behaviour off by default — these flags are debug
+ * aids, not user-facing settings. Returns false during SSR so server code
+ * paths never accidentally enable verbose logging.
+ */
+export type DevFlagName = "logChatRequest";
+
+const KEY_PREFIX = "tsagent.dev.";
+
+export function devFlag(name: DevFlagName): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    return window.localStorage.getItem(KEY_PREFIX + name) === "1";
+  } catch {
+    // Safari private mode and similar can throw on localStorage access; treat
+    // as flag off rather than crashing the caller.
+    return false;
+  }
+}

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[];
+}

package/dist/dashboard-runtime/dashboard/src/lib/normalize-oss-endpoint.ts

@@ -0,0 +1,28 @@
+/**
+ * Strip a bucket-name prefix from an OSS endpoint URL.
+ *
+ * Users sometimes paste the bucket-specific URL
+ * (e.g. `https://my-bucket.oss-cn-hangzhou.aliyuncs.com`) instead of the
+ * bare regional endpoint. The upstream SDK prepends the bucket name itself
+ * when constructing request URLs, so leaving the prefix in place produces a
+ * doubled hostname like `https://my-bucket.my-bucket.oss-cn-hangzhou.…`.
+ *
+ * Returns the cleaned endpoint, or the original string when no stripping
+ * is needed (including malformed URLs — those are left for schema
+ * validation to reject).
+ */
+export function stripBucketPrefix(
+  ossEndpoint: string,
+  ossBucketName: string,
+): string {
+  try {
+    const url = new URL(ossEndpoint);
+    if (url.hostname.startsWith(`${ossBucketName}.`)) {
+      url.hostname = url.hostname.slice(ossBucketName.length + 1);
+      return url.toString().replace(/\/$/, "");
+    }
+  } catch {
+    // invalid URL — return as-is
+  }
+  return ossEndpoint;
+}

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

@@ -0,0 +1,147 @@
+import type { QueryClient, QueryKey } from "@tanstack/react-query";
+
+export const RUNTIME_CONTEXT_QUERY_KEY = ["runtime-context"] as const;
+export const PENDING_DATA_SCOPE_KEY = "pending";
+
+export const queryKeys = {
+  runtimeContext: RUNTIME_CONTEXT_QUERY_KEY,
+  instances: (scope: string) => ["instances", scope] as const,
+  instance: (scope: string, name: string | null | undefined) =>
+    ["instance", scope, name] as const,
+  knowledgeBases: (scope: string) => ["knowledge-bases", scope] as const,
+  knowledgeBase: (scope: string, name: string | null | undefined) =>
+    ["knowledge-bases", scope, name] as const,
+  documents: (
+    scope: string,
+    knowledgeBaseName: string,
+    nextToken?: string,
+    maxResults?: number,
+    subspace?: string,
+  ) =>
+    [
+      "knowledge-bases",
+      scope,
+      knowledgeBaseName,
+      "documents",
+      nextToken,
+      maxResults,
+      subspace,
+    ] as const,
+  chunks: (
+    scope: string,
+    knowledgeBaseName: string,
+    docId: string | null,
+    subspace?: string,
+  ) => ["chunks", scope, knowledgeBaseName, docId, subspace] as const,
+  memoryStores: (scope: string) => ["memory", scope, "stores"] as const,
+  memoryStore: (scope: string, memoryStoreName: string | undefined) =>
+    ["memory", scope, "stores", memoryStoreName] as const,
+  memoryUnits: (
+    scopeKey: string,
+    memoryStoreName: string,
+    scope: unknown,
+    nextToken?: string,
+    limit?: number,
+  ) =>
+    ["memory", scopeKey, "stores", memoryStoreName, "units", scope, nextToken, limit] as const,
+  memoryUnit: (
+    scopeKey: string,
+    memoryStoreName: string,
+    memoryId: string | undefined,
+    scope: unknown,
+  ) =>
+    ["memory", scopeKey, "stores", memoryStoreName, "units", "detail", memoryId, scope] as const,
+  memoryRequests: (
+    scopeKey: string,
+    memoryStoreName: string,
+    scope: unknown,
+    nextToken?: string,
+    limit?: number,
+    operation?: string,
+  ) =>
+    [
+      "memory",
+      scopeKey,
+      "stores",
+      memoryStoreName,
+      "requests",
+      scope,
+      nextToken,
+      limit,
+      operation,
+    ] as const,
+  memoryMessages: (
+    scopeKey: string,
+    memoryStoreName: string,
+    scope: unknown,
+    nextToken?: string,
+    limit?: number,
+    filters?: { minTimestamp?: string; maxTimestamp?: string },
+  ) =>
+    [
+      "memory",
+      scopeKey,
+      "stores",
+      memoryStoreName,
+      "messages",
+      scope,
+      nextToken,
+      limit,
+      filters?.minTimestamp,
+      filters?.maxTimestamp,
+    ] as const,
+  llmProviders: (scope: string) => ["llm-providers", scope] as const,
+  llmProvider: (scope: string, id: string | undefined) =>
+    ["llm-providers", scope, id] as const,
+  llmProviderModels: (scope: string, id: string | undefined) =>
+    ["llm-provider-models", scope, id] as const,
+};
+
+const INSTANCE_SCOPED_QUERY_ROOTS = new Set([
+  "instances",
+  "instance",
+  "knowledge-bases",
+  "chunks",
+  "memory",
+  "llm-providers",
+  "llm-provider-models",
+  "auth-status",
+]);
+
+export function isInstanceScopedQueryKey(queryKey: QueryKey): boolean {
+  const root = queryKey[0];
+  return typeof root === "string" && INSTANCE_SCOPED_QUERY_ROOTS.has(root);
+}
+
+function belongsToDataScope(queryKey: QueryKey, dataScopeKey: string): boolean {
+  return queryKey[1] === dataScopeKey;
+}
+
+export function resetInstanceScopedQueries(
+  queryClient: QueryClient,
+  dataScopeKey?: string,
+): void {
+  queryClient.removeQueries({
+    predicate: (query) =>
+      isInstanceScopedQueryKey(query.queryKey) &&
+      (!dataScopeKey || belongsToDataScope(query.queryKey, dataScopeKey)),
+  });
+}
+
+export function invalidateInstanceScopedQueries(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({
+    predicate: (query) => isInstanceScopedQueryKey(query.queryKey),
+  });
+}
+
+export function invalidateKnowledgeBaseQueries(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: ["knowledge-bases"] });
+}
+
+export function invalidateMemoryQueries(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: ["memory"] });
+}
+
+export function invalidateLLMProviderQueries(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: ["llm-providers"] });
+}

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

@@ -1,10 +1,31 @@
 import { type NextRequest, NextResponse } from "next/server";
+import { AsyncLocalStorage } from "node:async_hooks";
 
-import { CLIError, EXIT_CODE_MAP } from "@tablestore/tablestore-agent-shared";
+import {
+  CLIError,
+  EXIT_CODE_MAP,
+  classifyErrorSource,
+  createLogger,
+  enterLogContext,
+  generateTraceId,
+  runWithLogContext,
+} from "@tablestore/tablestore-agent-shared";
 import type { StandardResponse } from "@tablestore/tablestore-agent-sdk";
 
 import { resolveClients, type ResolvedClients } from "./sdk-client";
 
+interface ApiLogContext {
+  traceId: string;
+  dashboardSessionId?: string;
+  method?: string;
+  path?: string;
+  startTime: number;
+}
+
+const apiContext = new AsyncLocalStorage<ApiLogContext>();
+const apiLogger = createLogger("dashboard.api");
+const QUIET_SUCCESS_PATHS = new Set(["/api/v1/runtime/context"]);
+
 // ---------------------------------------------------------------------------
 // HTTP status mapping
 // ---------------------------------------------------------------------------
@@ -34,6 +55,14 @@ function httpStatusFor(code: string, fallback = 500): number {
   return CODE_TO_HTTP_STATUS[code] ?? fallback;
 }
 
+function attachNoStoreHeader(response: NextResponse): void {
+  response.headers.set("Cache-Control", "no-store, max-age=0");
+}
+
+function shouldLogApiSuccess(path: string | undefined): boolean {
+  return !path || !QUIET_SUCCESS_PATHS.has(path);
+}
+
 // ---------------------------------------------------------------------------
 // Response builders
 // ---------------------------------------------------------------------------
@@ -45,10 +74,14 @@ function httpStatusFor(code: string, fallback = 500): number {
  * emits on stdout, so the Dashboard frontend uses the same response parser.
  */
 export function successResponse<T>(data: T, status = 200): NextResponse {
-  return NextResponse.json(
+  logApiResponse("api.response", "succeed", "SUCCESS", status);
+  const response = NextResponse.json(
     { code: "SUCCESS", message: "succeed", data },
     { status },
   );
+  attachNoStoreHeader(response);
+  attachTraceHeader(response);
+  return response;
 }
 
 /**
@@ -58,11 +91,26 @@ export function errorResponse(
   code: string,
   message: string,
   status?: number,
+  options: { log?: boolean; errorSource?: "local" | "network" | "service" | "browser" } = {},
 ): NextResponse {
-  return NextResponse.json(
+  const responseStatus = status ?? httpStatusFor(code);
+  if (options.log !== false) {
+    logApiResponse(
+      "api.error_response",
+      message,
+      code,
+      responseStatus,
+      undefined,
+      options.errorSource ?? "local",
+    );
+  }
+  const response = NextResponse.json(
     { code, message, data: null },
-    { status: status ?? httpStatusFor(code) },
+    { status: responseStatus },
   );
+  attachNoStoreHeader(response);
+  attachTraceHeader(response);
+  return response;
 }
 
 /**
@@ -99,7 +147,18 @@ export function forwardResponse(
   if (resp.requestId) body.requestId = resp.requestId;
 
   const status = resp.code === "SUCCESS" ? 200 : httpStatusFor(resp.code);
-  return NextResponse.json(body, { status });
+  logApiResponse(
+    resp.code === "SUCCESS" ? "api.response" : "api.service_error",
+    resp.message,
+    resp.code,
+    status,
+    resp.requestId,
+    resp.code === "SUCCESS" ? undefined : "service",
+  );
+  const response = NextResponse.json(body, { status });
+  attachNoStoreHeader(response);
+  attachTraceHeader(response);
+  return response;
 }
 
 // ---------------------------------------------------------------------------
@@ -119,7 +178,10 @@ export function forwardResponse(
  */
 export function handleApiError(error: unknown): NextResponse {
   if (error instanceof CLIError) {
-    return errorResponse(error.code, error.message, httpStatusFor(error.code));
+    logApiException(error, error.code, httpStatusFor(error.code));
+    return errorResponse(error.code, error.message, httpStatusFor(error.code), {
+      log: false,
+    });
   }
 
   if (error instanceof Error) {
@@ -133,7 +195,8 @@ export function handleApiError(error: unknown): NextResponse {
       lowerMessage.includes("token decode") ||
       lowerMessage.includes("unsupported token version")
     ) {
-      return errorResponse("UNAUTHORIZED", message, 401);
+      logApiException(error, "UNAUTHORIZED", 401);
+      return errorResponse("UNAUTHORIZED", message, 401, { log: false });
     }
 
     if (
@@ -143,16 +206,20 @@ export function handleApiError(error: unknown): NextResponse {
       lowerMessage.includes("enotfound") ||
       lowerMessage.includes("network")
     ) {
-      return errorResponse("NETWORK_ERROR", message, 503);
+      logApiException(error, "NETWORK_ERROR", 503);
+      return errorResponse("NETWORK_ERROR", message, 503, { log: false });
     }
 
-    return errorResponse("INTERNAL_SERVER_ERROR", message, 500);
+    logApiException(error, "INTERNAL_SERVER_ERROR", 500);
+    return errorResponse("INTERNAL_SERVER_ERROR", message, 500, { log: false });
   }
 
+  logApiException(error, "INTERNAL_SERVER_ERROR", 500);
   return errorResponse(
     "INTERNAL_SERVER_ERROR",
     typeof error === "string" ? error : JSON.stringify(error),
     500,
+    { log: false },
   );
 }
 
@@ -176,6 +243,7 @@ export function handleApiError(error: unknown): NextResponse {
 export function requireClients(
   request: NextRequest,
 ): ResolvedClients | NextResponse {
+  ensureApiLogContext(request);
   try {
     return resolveClients(request);
   } catch (err) {
@@ -183,5 +251,121 @@ export function requireClients(
   }
 }
 
+export function ensureApiLogContext(request: NextRequest): ApiLogContext {
+  const current = apiContext.getStore();
+  if (current) return current;
+
+  const traceId =
+    request.headers.get("x-trace-id") ||
+    request.headers.get("x-request-id") ||
+    generateTraceId();
+  const path = request.nextUrl?.pathname ?? safePathname(request.url);
+  const context: ApiLogContext = {
+    traceId,
+    dashboardSessionId: process.env.TABLESTORE_DASHBOARD_SESSION_ID,
+    method: request.method,
+    path,
+    startTime: Date.now(),
+  };
+  apiContext.enterWith(context);
+  enterLogContext(context);
+  if (shouldLogApiSuccess(path)) {
+    apiLogger.info({
+      event: "api.request",
+      message: `${request.method} ${path}`,
+      dashboardSessionId: context.dashboardSessionId,
+      traceId,
+      details: {
+        method: request.method,
+        path,
+        userAgent: request.headers.get("user-agent") ?? undefined,
+      },
+    });
+  }
+  return context;
+}
+
+export function getApiLogContext(): ApiLogContext | undefined {
+  return apiContext.getStore();
+}
+
+export async function withApiLogging<T>(
+  request: NextRequest,
+  handler: () => Promise<T> | T,
+): Promise<T> {
+  const context = ensureApiLogContext(request);
+  return apiContext.run(context, async () =>
+    runWithLogContext(context, async () => handler()),
+  );
+}
+
 // Re-export so routes can `import { CODE_TO_HTTP_STATUS } from` if ever needed.
 export { CODE_TO_HTTP_STATUS, EXIT_CODE_MAP };
+
+function logApiResponse(
+  event: string,
+  message: string,
+  code: string,
+  status: number,
+  requestId?: string,
+  errorSource?: "local" | "network" | "service" | "browser",
+): void {
+  const context = apiContext.getStore();
+  if (status < 400 && !shouldLogApiSuccess(context?.path)) return;
+  const durationMs = context ? Date.now() - context.startTime : undefined;
+  const level = status >= 500 ? "error" : status >= 400 ? "warn" : "info";
+  apiLogger.log({
+    level,
+    event,
+    message,
+    dashboardSessionId: context?.dashboardSessionId,
+    traceId: context?.traceId,
+    requestId,
+    durationMs,
+    errorSource,
+    details: {
+      method: context?.method,
+      path: context?.path,
+      status,
+      code,
+      errorSource,
+    },
+  });
+}
+
+function logApiException(error: unknown, code: string, status: number): void {
+  const context = apiContext.getStore();
+  const durationMs = context ? Date.now() - context.startTime : undefined;
+  const source = classifyErrorSource(error);
+  apiLogger.error({
+    event: "api.exception",
+    message: error instanceof Error ? error.message : String(error),
+    dashboardSessionId: context?.dashboardSessionId,
+    traceId: context?.traceId,
+    durationMs,
+    error,
+    errorSource: source,
+    details: {
+      method: context?.method,
+      path: context?.path,
+      status,
+      code,
+      errorSource: source,
+    },
+  });
+}
+
+function attachTraceHeader(response: NextResponse): void {
+  const context = apiContext.getStore();
+  if (context?.traceId) {
+    response.headers.set("x-trace-id", context.traceId);
+  }
+}
+
+function safePathname(url: string): string {
+  try {
+    return new URL(url).pathname;
+  } catch {
+    return "";
+  }
+}

package/dist/dashboard-runtime/dashboard/src/lib/server/chat-project-context.ts

@@ -0,0 +1,17 @@
+import { type NextRequest } from "next/server";
+
+import { getActiveInstanceContext } from "./sdk-client";
+
+export function validateChatProjectContext(
+  request: NextRequest,
+  requestedActiveInstance: string | null | undefined,
+): { ok: true } | { ok: false; message: string } {
+  if (requestedActiveInstance === undefined) return { ok: true };
+  const current = getActiveInstanceContext(request).instanceName ?? null;
+  if (current === requestedActiveInstance) return { ok: true };
+  return {
+    ok: false,
+    message:
+      "Project context changed. Refresh the dashboard and start the chat again.",
+  };
+}

package/dist/dashboard-runtime/dashboard/src/lib/server/runtime-context.ts

@@ -0,0 +1,108 @@
+import { type NextRequest } from "next/server";
+import { createHash } from "node:crypto";
+
+import {
+  getConfigRevision,
+  listInstances,
+} from "@tablestore/tablestore-agent-shared";
+
+import { inspectCredentials } from "./sdk-client";
+import type { RuntimeContext } from "@/types/runtime-context";
+
+function hasAnyNamedInstance(): boolean {
+  try {
+    return listInstances().some((r) => !r.is_default_fallback);
+  } catch {
+    return false;
+  }
+}
+
+function fallbackScopeHash(input: {
+  instanceName?: string;
+  region?: string;
+  configRevision: string;
+}): string {
+  return createHash("sha256")
+    .update([
+      input.instanceName ?? "",
+      input.region ?? "",
+      input.configRevision,
+    ].join("|"))
+    .digest("hex")
+    .slice(0, 12);
+}
+
+export function buildDataScopeKey(input: {
+  configured: boolean;
+  credentialSource: RuntimeContext["credentialSource"];
+  activeInstance: string | null;
+  instanceName?: string;
+  region?: string;
+  configRevision: string;
+  credentialFingerprint?: string;
+}): string {
+  if (!input.configured) return `unconfigured:${input.configRevision}`;
+  if (input.credentialSource === "cookie" && !input.activeInstance) {
+    // getRuntimeContext always supplies credentialFingerprint for raw-token
+    // cookies. The fallback only protects direct callers/tests from collapsing
+    // unrelated raw-token scopes back into one cache namespace.
+    return [
+      "cookie",
+      "raw",
+      input.credentialFingerprint ?? fallbackScopeHash(input),
+    ].join(":");
+  }
+  if (input.credentialSource === "env") {
+    return [
+      "env",
+      input.instanceName ?? "",
+      input.region ?? "",
+    ].join(":");
+  }
+  if (input.activeInstance) {
+    return [
+      "project",
+      encodeURIComponent(input.activeInstance),
+      input.configRevision,
+    ].join(":");
+  }
+  return `${input.credentialSource ?? "unknown"}:${input.configRevision}`;
+}
+
+export function getRuntimeContext(request: NextRequest): RuntimeContext {
+  const configRevision = getConfigRevision();
+  const creds = inspectCredentials(request);
+  const hasAnyInstance = hasAnyNamedInstance();
+
+  if (!creds) {
+    const base = {
+      configured: false,
+      credentialSource: null,
+      activeInstance: null,
+      configRevision,
+      hasAnyInstance,
+    } satisfies Omit<RuntimeContext, "dataScopeKey">;
+    return {
+      ...base,
+      dataScopeKey: buildDataScopeKey(base),
+    };
+  }
+
+  const base = {
+    configured: true,
+    credentialSource: creds.source,
+    activeInstance: creds.activeInstance,
+    instanceName: creds.instanceName,
+    region: creds.region,
+    configRevision,
+    hasAnyInstance,
+  } satisfies Omit<RuntimeContext, "dataScopeKey">;
+
+  return {
+    ...base,
+    dataScopeKey: buildDataScopeKey({
+      ...base,
+      credentialFingerprint: creds.credentialFingerprint,
+    }),
+  };
+}