@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

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

@@ -0,0 +1,167 @@
+import type { MemoryScope } from "@/types/memory";
+
+export const SCOPE_LEVELS = ["app", "tenant", "agent", "run"] as const;
+
+export type ScopeLevel = (typeof SCOPE_LEVELS)[number];
+export type ScopeGranularity = "all" | ScopeLevel;
+
+export interface ScopeChild {
+  level: ScopeLevel;
+  value: string;
+}
+
+export interface ScopeBreadcrumbItem extends ScopeChild {
+  concrete: boolean;
+}
+
+export const SCOPE_FIELD_BY_LEVEL = {
+  app: "appId",
+  tenant: "tenantId",
+  agent: "agentId",
+  run: "runId",
+} as const satisfies Record<ScopeLevel, keyof MemoryScope>;
+
+const ALL_SCOPE: MemoryScope = {
+  appId: "*",
+  tenantId: "*",
+  agentId: "*",
+  runId: "*",
+};
+
+const LEVEL_BY_FIELD: Record<keyof MemoryScope, ScopeLevel> = {
+  appId: "app",
+  tenantId: "tenant",
+  agentId: "agent",
+  runId: "run",
+};
+
+export function normalizeHierarchicalScope(
+  scope: MemoryScope,
+): MemoryScope | null {
+  const appId = scope.appId?.trim();
+  if (!appId) return null;
+
+  const values = [
+    appId,
+    scope.tenantId?.trim() || "*",
+    scope.agentId?.trim() || "*",
+    scope.runId?.trim() || "*",
+  ];
+  let wildcardSeen = false;
+  const canonical = values.map((value) => {
+    if (wildcardSeen || value === "*") {
+      wildcardSeen = true;
+      return "*";
+    }
+    return value;
+  });
+
+  return {
+    appId: canonical[0],
+    tenantId: canonical[1],
+    agentId: canonical[2],
+    runId: canonical[3],
+  };
+}
+
+export function scopeGranularity(scope: MemoryScope): ScopeGranularity {
+  const canonical = normalizeHierarchicalScope(scope) ?? ALL_SCOPE;
+  if (canonical.appId === "*") return "all";
+  if (canonical.tenantId === "*") return "app";
+  if (canonical.agentId === "*") return "tenant";
+  if (canonical.runId === "*") return "agent";
+  return "run";
+}
+
+export function scopeAtLevel(
+  scope: MemoryScope,
+  level: ScopeGranularity,
+): MemoryScope {
+  if (level === "all") return { ...ALL_SCOPE };
+
+  const canonical = normalizeHierarchicalScope(scope) ?? ALL_SCOPE;
+  const selectedIndex = SCOPE_LEVELS.indexOf(level);
+  const result = { ...ALL_SCOPE };
+  for (let index = 0; index <= selectedIndex; index += 1) {
+    const field = SCOPE_FIELD_BY_LEVEL[SCOPE_LEVELS[index]];
+    const value = canonical[field];
+    if (!value || value === "*") break;
+    result[field] = value;
+  }
+  return result;
+}
+
+export function scopeWithSelection(
+  scope: MemoryScope,
+  field: keyof MemoryScope,
+  value: string,
+): MemoryScope {
+  const canonical = normalizeHierarchicalScope(scope) ?? { ...ALL_SCOPE };
+  const level = LEVEL_BY_FIELD[field];
+  const levelIndex = SCOPE_LEVELS.indexOf(level);
+  canonical[field] = value.trim() || "*";
+  for (let index = levelIndex + 1; index < SCOPE_LEVELS.length; index += 1) {
+    canonical[SCOPE_FIELD_BY_LEVEL[SCOPE_LEVELS[index]]] = "*";
+  }
+  return normalizeHierarchicalScope(canonical) ?? { ...ALL_SCOPE };
+}
+
+export function scopeChildren(
+  scopes: readonly MemoryScope[],
+  parent: MemoryScope,
+): ScopeChild[] {
+  const canonicalParent = normalizeHierarchicalScope(parent) ?? ALL_SCOPE;
+  const parentGranularity = scopeGranularity(canonicalParent);
+  const nextIndex =
+    parentGranularity === "all"
+      ? 0
+      : SCOPE_LEVELS.indexOf(parentGranularity) + 1;
+  if (nextIndex >= SCOPE_LEVELS.length) return [];
+
+  const nextLevel = SCOPE_LEVELS[nextIndex];
+  const nextField = SCOPE_FIELD_BY_LEVEL[nextLevel];
+  const values = new Set<string>();
+
+  for (const scope of scopes) {
+    const candidate = normalizeHierarchicalScope(scope);
+    if (!candidate) continue;
+
+    const matchesParent = SCOPE_LEVELS.slice(0, nextIndex).every((level) => {
+      const field = SCOPE_FIELD_BY_LEVEL[level];
+      return candidate[field] === canonicalParent[field];
+    });
+    const value = candidate[nextField];
+    if (matchesParent && value && value !== "*") values.add(value);
+  }
+
+  return [...values]
+    .sort((left, right) => left.localeCompare(right))
+    .map((value) => ({ level: nextLevel, value }));
+}
+
+export function scopeBreadcrumb(scope: MemoryScope): ScopeBreadcrumbItem[] {
+  const canonical = normalizeHierarchicalScope(scope) ?? ALL_SCOPE;
+  return SCOPE_LEVELS.map((level) => {
+    const value = canonical[SCOPE_FIELD_BY_LEVEL[level]] ?? "*";
+    return { level, value, concrete: value !== "*" };
+  });
+}
+
+export function filterScopeTuples(
+  scopes: readonly MemoryScope[],
+  query: string,
+): MemoryScope[] {
+  const terms = query.toLocaleLowerCase().split(/\s+/).filter(Boolean);
+  if (terms.length === 0) return [...scopes];
+
+  return scopes.filter((scope) => {
+    const canonical = normalizeHierarchicalScope(scope);
+    if (!canonical) return false;
+    const text = SCOPE_LEVELS.map(
+      (level) => canonical[SCOPE_FIELD_BY_LEVEL[level]],
+    )
+      .join(" ")
+      .toLocaleLowerCase();
+    return terms.every((term) => text.includes(term));
+  });
+}

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

@@ -0,0 +1,123 @@
+import type { MemoryScope } from "@/types/memory";
+import type { FileMemoryScope } from "@/types/file-memory";
+import type { Wiki, WikiBuildStatus } from "@/types/wiki";
+import type {
+  ChatScopeStorageMode,
+  ChatScopeWikiPolicy,
+} from "@/lib/chat-scope-entry";
+
+export type ScopeFeatureSegment =
+  "scope" | "units" | "search" | "dream" | "wiki";
+export type ScopeWorkspaceStatus =
+  | "loading"
+  | "draft"
+  | "building"
+  | "ready"
+  | "stale"
+  | "failed_with_fallback"
+  | "blocked";
+
+const NON_TERMINAL = new Set<WikiBuildStatus>([
+  "pending",
+  "processing",
+  "accepting_output",
+  "sealing",
+  "validating",
+  "indexing",
+  "publishing",
+]);
+
+export function parseExactScope(
+  params: URLSearchParams,
+): FileMemoryScope | null {
+  const values = ["appId", "tenantId", "agentId", "runId"].map(
+    (key) => params.get(key)?.trim() ?? "",
+  );
+  if (values.some((value) => !value || value === "*")) return null;
+  const [appId, tenantId, agentId, runId] = values;
+  return { appId, tenantId, agentId, runId };
+}
+
+export function toExactScope(scope: MemoryScope): FileMemoryScope | null {
+  return parseExactScope(
+    new URLSearchParams({
+      appId: scope.appId ?? "",
+      tenantId: scope.tenantId ?? "",
+      agentId: scope.agentId ?? "",
+      runId: scope.runId ?? "",
+    }),
+  );
+}
+
+function scopeParams(
+  scope: FileMemoryScope,
+  extra: Record<string, string> = {},
+) {
+  const params = new URLSearchParams({
+    appId: scope.appId,
+    tenantId: scope.tenantId,
+    agentId: scope.agentId,
+    runId: scope.runId,
+  });
+  for (const [key, value] of Object.entries(extra)) {
+    if (!["appId", "tenantId", "agentId", "runId"].includes(key)) {
+      params.set(key, value);
+    }
+  }
+  return params;
+}
+
+export function buildScopeFeatureHref(
+  store: string,
+  segment: ScopeFeatureSegment,
+  scope: FileMemoryScope,
+  extra: Record<string, string> = {},
+): string {
+  return `/memory/${encodeURIComponent(store)}/${segment}?${scopeParams(scope, extra)}`;
+}
+
+export function buildScopeWorkspaceHref(store: string, scope: FileMemoryScope) {
+  return buildScopeFeatureHref(store, "scope", scope);
+}
+
+export function buildScopeChatHref(
+  memoryStoreName: string,
+  storageMode: ChatScopeStorageMode,
+  scope: FileMemoryScope,
+  wiki: ChatScopeWikiPolicy,
+): string {
+  if (storageMode !== "ots" && storageMode !== "file+ots") {
+    throw new Error("Unsupported Chat Scope storage mode");
+  }
+  const params = new URLSearchParams({
+    memoryStoreName,
+    storageMode,
+    appId: scope.appId,
+    tenantId: scope.tenantId,
+    agentId: scope.agentId,
+    runId: scope.runId,
+    wiki,
+  });
+  return `/chat?${params}`;
+}
+
+export function deriveScopeWorkspaceStatus(input: {
+  loading?: boolean;
+  error?: unknown;
+  wiki?: Pick<Wiki, "status" | "hasPendingChanges"> & {
+    latestBuild?: { status: WikiBuildStatus };
+  };
+}): ScopeWorkspaceStatus {
+  if (input.loading) return "loading";
+  if (input.error || !input.wiki) return "blocked";
+  const latestStatus = input.wiki.latestBuild?.status;
+  if (latestStatus && NON_TERMINAL.has(latestStatus)) return "building";
+  if (latestStatus === "failed" || latestStatus === "conflict") {
+    return input.wiki.status === "ready" ? "failed_with_fallback" : "blocked";
+  }
+  if (input.wiki.status !== "ready") return "draft";
+  if (input.wiki.hasPendingChanges) {
+    return "stale";
+  }
+  return "ready";
+}

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

@@ -140,8 +140,15 @@ export interface ForwardableEnvelope {
   data: unknown;
   message: string;
   requestId?: string;
+  details?: ForwardableUpstreamErrorDetails;
 }
 
+type ForwardableUpstreamErrorDetails = {
+  upstreamCode?: string;
+  upstreamStatus?: number;
+  upstreamRequestId?: string;
+};
+
 /**
  * Forward a {@link StandardResponse} (or an ad-hoc envelope) produced by a
  * route handler as an HTTP response. Success envelopes become 200 with `data`
@@ -162,15 +169,24 @@ export function forwardResponse(
     message: resp.message,
   };
   if (resp.requestId) body.requestId = resp.requestId;
-
-  const status = resp.code === "SUCCESS" ? 200 : httpStatusFor(resp.code);
+  const details = normalizeUpstreamErrorDetails(resp.details);
+  if (details) body.details = details;
+
+  const upstreamStatus = details?.upstreamStatus;
+  const status =
+    resp.code === "SUCCESS"
+      ? 200
+      : isForwardableHttpStatus(upstreamStatus)
+        ? upstreamStatus
+        : httpStatusFor(resp.code);
   logApiResponse(
     resp.code === "SUCCESS" ? "api.response" : "api.service_error",
-    resp.message,
+    resp.code === "SUCCESS" ? "succeed" : "upstream service error",
     resp.code,
     status,
     resp.requestId,
     resp.code === "SUCCESS" ? undefined : "service",
+    details,
   );
   const response = NextResponse.json(body, { status });
   attachNoStoreHeader(response);
@@ -178,6 +194,33 @@ export function forwardResponse(
   return response;
 }
 
+function isForwardableHttpStatus(status: number | undefined): status is number {
+  return (
+    status !== undefined &&
+    Number.isInteger(status) &&
+    status >= 400 &&
+    status <= 599
+  );
+}
+
+function normalizeUpstreamErrorDetails(
+  details: unknown,
+): ForwardableUpstreamErrorDetails | undefined {
+  if (details === null || typeof details !== "object") return undefined;
+  const record = details as Record<string, unknown>;
+  const normalized: ForwardableUpstreamErrorDetails = {};
+  if (typeof record.upstreamCode === "string") {
+    normalized.upstreamCode = record.upstreamCode;
+  }
+  if (typeof record.upstreamStatus === "number") {
+    normalized.upstreamStatus = record.upstreamStatus;
+  }
+  if (typeof record.upstreamRequestId === "string") {
+    normalized.upstreamRequestId = record.upstreamRequestId;
+  }
+  return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Error handling
 // ---------------------------------------------------------------------------

package/dist/dashboard-runtime/dashboard/src/lib/server/memory-store-contract.ts

@@ -0,0 +1,41 @@
+import {
+  parseKnownStorageMode,
+  type StorageMode,
+} from "@/lib/memory-storage-mode";
+
+type MemoryStoreWire = Record<string, unknown> & {
+  storageMode?: unknown;
+  inputType?: unknown;
+  outputTypes?: unknown;
+};
+
+/**
+ * The current service omits storageMode for stores created with the new
+ * inputType/outputTypes contract.  Keep one derived legacy label at the BFF
+ * boundary so the existing capability matrix remains correct while the UI
+ * also exposes the authoritative fields.
+ */
+export function normalizeMemoryStoreContract<T extends MemoryStoreWire>(
+  store: T,
+): T & { storageMode: StorageMode } {
+  const knownStorageMode =
+    typeof store.storageMode === "string"
+      ? parseKnownStorageMode(store.storageMode)
+      : null;
+  if (knownStorageMode) {
+    return { ...store, storageMode: knownStorageMode };
+  }
+
+  const outputs = new Set(
+    Array.isArray(store.outputTypes) ? store.outputTypes : [],
+  );
+  let storageMode: StorageMode = "ots";
+  if (store.inputType === "file") {
+    storageMode = "filemem";
+  } else if (outputs.has("file") && outputs.has("structured")) {
+    storageMode = "file+ots";
+  } else if (outputs.has("file")) {
+    storageMode = "managed-file";
+  }
+  return { ...store, storageMode };
+}

package/dist/dashboard-runtime/dashboard/src/lib/server/scope-filter-validation.ts

@@ -0,0 +1,186 @@
+import type { ScopeDirectoryFilter } from "@/types/memory";
+
+const FILTER_FIELD_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}$/;
+const MAX_FILTER_DEPTH = 8;
+const MAX_FILTER_LEAVES = 64;
+
+type FilterParseResult = { filter: ScopeDirectoryFilter } | { error: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyKeys(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
+
+function parseField(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const field = value.trim();
+  return FILTER_FIELD_PATTERN.test(field) ? field : null;
+}
+
+function parseFilterNode(
+  value: unknown,
+  depth: number,
+  counter: { leaves: number },
+): FilterParseResult {
+  if (depth >= MAX_FILTER_DEPTH) {
+    return { error: `filter exceeds maximum depth ${MAX_FILTER_DEPTH}` };
+  }
+  if (!isRecord(value) || typeof value.op !== "string") {
+    return { error: "filter nodes must be objects with a string op" };
+  }
+
+  const op = value.op.trim().toLowerCase();
+  const field = parseField(value.field);
+  if (["eq", "prefix", "wildcard"].includes(op)) {
+    if (!hasOnlyKeys(value, ["op", "field", "value"])) {
+      return { error: `filter ${op} contains unknown fields` };
+    }
+    if (!field || typeof value.value !== "string") {
+      return { error: `filter ${op} requires a valid field and string value` };
+    }
+    // Keep operand constraints aligned with scopedirectory.Filter.Validate in
+    // the service. It intentionally caps wildcard patterns only; imposing
+    // invented limits on eq/prefix/range/in here would reject valid requests.
+    if (op === "wildcard" && [...value.value].length > 32) {
+      return { error: "filter wildcard value exceeds 32 characters" };
+    }
+    counter.leaves += 1;
+    if (counter.leaves > MAX_FILTER_LEAVES) {
+      return {
+        error: `filter exceeds maximum leaf count ${MAX_FILTER_LEAVES}`,
+      };
+    }
+    return {
+      filter: {
+        op: op as "eq" | "prefix" | "wildcard",
+        field,
+        value: value.value,
+      },
+    };
+  }
+
+  if (op === "in") {
+    if (!hasOnlyKeys(value, ["op", "field", "values"])) {
+      return { error: "filter in contains unknown fields" };
+    }
+    if (
+      !field ||
+      !Array.isArray(value.values) ||
+      value.values.length === 0 ||
+      value.values.some((item) => typeof item !== "string")
+    ) {
+      return { error: "filter in requires a valid field and string values" };
+    }
+    counter.leaves += 1;
+    if (counter.leaves > MAX_FILTER_LEAVES) {
+      return {
+        error: `filter exceeds maximum leaf count ${MAX_FILTER_LEAVES}`,
+      };
+    }
+    return { filter: { op: "in", field, values: value.values as string[] } };
+  }
+
+  if (op === "range") {
+    if (!hasOnlyKeys(value, ["op", "field", "gt", "gte", "lt", "lte"])) {
+      return { error: "filter range contains unknown fields" };
+    }
+    const bounds = ["gt", "gte", "lt", "lte"] as const;
+    const presentBounds = bounds.filter((key) => value[key] !== undefined);
+    if (
+      !field ||
+      presentBounds.length === 0 ||
+      presentBounds.some((key) => typeof value[key] !== "string")
+    ) {
+      return {
+        error:
+          "filter range requires a valid field and at least one string bound",
+      };
+    }
+    if (
+      (value.gt !== undefined && value.gte !== undefined) ||
+      (value.lt !== undefined && value.lte !== undefined)
+    ) {
+      return { error: "filter range cannot combine gt/gte or lt/lte" };
+    }
+    counter.leaves += 1;
+    if (counter.leaves > MAX_FILTER_LEAVES) {
+      return {
+        error: `filter exceeds maximum leaf count ${MAX_FILTER_LEAVES}`,
+      };
+    }
+    return {
+      filter: {
+        op: "range",
+        field,
+        ...(typeof value.gt === "string" ? { gt: value.gt } : {}),
+        ...(typeof value.gte === "string" ? { gte: value.gte } : {}),
+        ...(typeof value.lt === "string" ? { lt: value.lt } : {}),
+        ...(typeof value.lte === "string" ? { lte: value.lte } : {}),
+      },
+    };
+  }
+
+  if (op === "exists") {
+    if (!hasOnlyKeys(value, ["op", "field"]) || !field) {
+      return { error: "filter exists requires exactly one known field" };
+    }
+    counter.leaves += 1;
+    if (counter.leaves > MAX_FILTER_LEAVES) {
+      return {
+        error: `filter exceeds maximum leaf count ${MAX_FILTER_LEAVES}`,
+      };
+    }
+    return { filter: { op: "exists", field } };
+  }
+
+  if (op === "and" || op === "or") {
+    if (!hasOnlyKeys(value, ["op", "conditions"])) {
+      return { error: `filter ${op} contains unknown fields` };
+    }
+    if (!Array.isArray(value.conditions) || value.conditions.length === 0) {
+      return { error: `filter ${op} requires non-empty conditions` };
+    }
+    const conditions: ScopeDirectoryFilter[] = [];
+    for (const condition of value.conditions) {
+      const parsed = parseFilterNode(condition, depth + 1, counter);
+      if ("error" in parsed) return parsed;
+      conditions.push(parsed.filter);
+    }
+    return { filter: { op, conditions } };
+  }
+
+  if (op === "not") {
+    if (!hasOnlyKeys(value, ["op", "condition", "conditions"])) {
+      return { error: "filter not contains unknown fields" };
+    }
+    const legacyConditions = Array.isArray(value.conditions)
+      ? value.conditions
+      : [];
+    if (
+      (value.condition !== undefined && legacyConditions.length !== 0) ||
+      (value.condition === undefined && legacyConditions.length !== 1)
+    ) {
+      return { error: "filter not requires exactly one condition" };
+    }
+    const parsed = parseFilterNode(
+      value.condition ?? legacyConditions[0],
+      depth + 1,
+      counter,
+    );
+    return "error" in parsed
+      ? parsed
+      : { filter: { op: "not", condition: parsed.filter } };
+  }
+
+  return { error: `unsupported filter op: ${op}` };
+}
+
+export function parseScopeDirectoryFilter(value: unknown): FilterParseResult {
+  return parseFilterNode(value, 0, { leaves: 0 });
+}

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

@@ -18,6 +18,7 @@ import {
 import {
   KnowledgeBaseClient,
   MemoryClient,
+  WikiClient,
   inferRegionFromOtsEndpoint,
 } from "@tablestore/tablestore-agent-sdk";
 
@@ -139,6 +140,7 @@ export type CredentialSource = "cookie" | "instance" | "env";
 export interface ResolvedClients {
   kb: KnowledgeBaseClient;
   memory: MemoryClient;
+  wiki: WikiClient;
   config: AppConfig;
   source: CredentialSource;
   /** Trusted active project name for named-instance requests, else null. */
@@ -578,6 +580,7 @@ export function resolveClients(request: NextRequest): ResolvedClients {
   const resolved: ResolvedClients = {
     kb: new KnowledgeBaseClient(appConfig),
     memory: new MemoryClient(appConfig),
+    wiki: new WikiClient(appConfig),
     config: appConfig,
     source,
     instanceName,