@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/_scope.ts

@@ -1,5 +1,72 @@
 import type { MemoryScope } from "@tablestore/tablestore-agent-shared";
 
+export interface ExactMemoryScope {
+  appId: string;
+  tenantId: string;
+  agentId: string;
+  runId: string;
+}
+
+export interface AgentWikiScope {
+  appId: string;
+  tenantId: string;
+  agentId: string;
+}
+
+export function readAgentWikiScope(raw: unknown): AgentWikiScope | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+
+  const value = raw as Record<string, unknown>;
+  const read = (key: keyof AgentWikiScope) => {
+    const component = value[key];
+    if (typeof component !== "string") return null;
+    const normalized = component.trim();
+    return normalized && normalized !== "*" ? normalized : null;
+  };
+
+  const appId = read("appId");
+  const tenantId = read("tenantId");
+  const agentId = read("agentId");
+  if (!appId || !tenantId || !agentId) return null;
+
+  return { appId, tenantId, agentId };
+}
+
+export function toAgentWikiScope(
+  scope: AgentWikiScope | ExactMemoryScope,
+): AgentWikiScope {
+  return {
+    appId: scope.appId,
+    tenantId: scope.tenantId,
+    agentId: scope.agentId,
+  };
+}
+
+/**
+ * Read a concrete four-part Memory scope from an untrusted value.
+ *
+ * Point APIs must not widen missing components or accept wildcard segments.
+ */
+export function readExactMemoryScope(raw: unknown): ExactMemoryScope | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+
+  const value = raw as Record<string, unknown>;
+  const read = (key: keyof ExactMemoryScope) => {
+    const component = value[key];
+    if (typeof component !== "string") return null;
+    const normalized = component.trim();
+    return normalized && normalized !== "*" ? normalized : null;
+  };
+
+  const appId = read("appId");
+  const tenantId = read("tenantId");
+  const agentId = read("agentId");
+  const runId = read("runId");
+  if (!appId || !tenantId || !agentId || !runId) return null;
+
+  return { appId, tenantId, agentId, runId };
+}
+
 /**
  * Extract a {@link MemoryScope} from URL query parameters.
  *

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/file-memory/_helpers.ts

@@ -1,9 +1,7 @@
-export interface ExactFileMemoryScope {
-  appId: string;
-  tenantId: string;
-  agentId: string;
-  runId: string;
-}
+import { readExactMemoryScope, type ExactMemoryScope } from "../_scope";
+
+export { readExactMemoryScope } from "../_scope";
+export type ExactFileMemoryScope = ExactMemoryScope;
 
 /**
  * File APIs only accept a concrete four-part scope. Unlike structured-memory
@@ -12,21 +10,5 @@ export interface ExactFileMemoryScope {
 export function readExactFileMemoryScope(
   raw: unknown,
 ): ExactFileMemoryScope | null {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
-
-  const value = raw as Record<string, unknown>;
-  const read = (key: "appId" | "tenantId" | "agentId" | "runId") => {
-    const component = value[key];
-    if (typeof component !== "string") return null;
-    const normalized = component.trim();
-    return normalized && normalized !== "*" ? normalized : null;
-  };
-
-  const appId = read("appId");
-  const tenantId = read("tenantId");
-  const agentId = read("agentId");
-  const runId = read("runId");
-  if (!appId || !tenantId || !agentId || !runId) return null;
-
-  return { appId, tenantId, agentId, runId };
+  return readExactMemoryScope(raw);
 }

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/route.ts

@@ -1,10 +1,12 @@
 import { type NextRequest } from "next/server";
+import type { StandardResponse } from "@tablestore/tablestore-agent-sdk";
 
 import {
   forwardResponse,
   handleApiError,
   requireClients,
 } from "@/lib/server/api-helpers";
+import { normalizeMemoryStoreContract } from "@/lib/server/memory-store-contract";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -19,6 +21,21 @@ interface RouteContext {
   params: Promise<{ store: string }>;
 }
 
+function forwardNormalizedStoreResponse(resp: StandardResponse) {
+  if (
+    resp.code === "SUCCESS" &&
+    resp.data &&
+    typeof resp.data === "object" &&
+    !Array.isArray(resp.data)
+  ) {
+    return forwardResponse({
+      ...resp,
+      data: normalizeMemoryStoreContract(resp.data as Record<string, unknown>),
+    });
+  }
+  return forwardResponse(resp);
+}
+
 export async function GET(request: NextRequest, context: RouteContext) {
   try {
     const { store } = await context.params;
@@ -27,7 +44,7 @@ export async function GET(request: NextRequest, context: RouteContext) {
     const { memory } = auth;
 
     const resp = await memory.getMemoryStore({ memoryStoreName: store });
-    return forwardResponse(resp);
+    return forwardNormalizedStoreResponse(resp);
   } catch (error) {
     return handleApiError(error);
   }
@@ -57,7 +74,7 @@ export async function PUT(request: NextRequest, context: RouteContext) {
       ...safeBody,
       memoryStoreName: store,
     });
-    return forwardResponse(resp);
+    return forwardNormalizedStoreResponse(resp);
   } catch (error) {
     return handleApiError(error);
   }

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/scopes/route.ts

@@ -9,6 +9,7 @@ import {
   requireClients,
   successResponse,
 } from "@/lib/server/api-helpers";
+import { parseScopeDirectoryFilter } from "@/lib/server/scope-filter-validation";
 
 import { readPaginationFromQuery, readScopeFromQuery } from "../_scope";
 
@@ -23,6 +24,88 @@ interface RouteContext {
   params: Promise<{ store: string }>;
 }
 
+const SCOPE_FIELDS = ["appId", "tenantId", "agentId", "runId"] as const;
+const MAX_SCOPE_DIRECTORY_LIMIT = 100;
+
+function badRequest(message: string) {
+  return forwardResponse({ code: "BAD_REQUEST", data: null, message });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function buildScopeDirectoryRequest(
+  body: Record<string, unknown>,
+): { request: Record<string, unknown> } | { error: string } {
+  const safeBody: Record<string, unknown> = {};
+
+  if (body.scope !== undefined && body.scope !== null) {
+    if (!isRecord(body.scope)) {
+      return { error: "scope must be a JSON object" };
+    }
+    for (const field of Object.keys(body.scope)) {
+      if (!SCOPE_FIELDS.includes(field as (typeof SCOPE_FIELDS)[number])) {
+        return { error: `Unknown scope field: ${field}` };
+      }
+    }
+    const scope: Record<string, string> = {};
+    for (const field of SCOPE_FIELDS) {
+      const value = body.scope[field];
+      if (value === undefined) continue;
+      if (typeof value !== "string" || value.trim() === "") {
+        return { error: `scope.${field} must be a non-empty string` };
+      }
+      scope[field] = value;
+    }
+    if (Object.keys(scope).length > 0) safeBody.scope = scope;
+  }
+
+  if (body.filter !== undefined && body.filter !== null) {
+    const parsedFilter = parseScopeDirectoryFilter(body.filter);
+    if ("error" in parsedFilter) return { error: parsedFilter.error };
+    safeBody.filter = parsedFilter.filter;
+  }
+
+  if (body.limit !== undefined) {
+    if (
+      typeof body.limit !== "number" ||
+      !Number.isInteger(body.limit) ||
+      body.limit <= 0 ||
+      body.limit > MAX_SCOPE_DIRECTORY_LIMIT
+    ) {
+      return {
+        error: `limit must be an integer between 1 and ${MAX_SCOPE_DIRECTORY_LIMIT}`,
+      };
+    }
+    safeBody.limit = body.limit;
+  }
+
+  if (body.nextToken !== undefined) {
+    if (typeof body.nextToken !== "string") {
+      return { error: "nextToken must be a string" };
+    }
+    if (body.nextToken) safeBody.nextToken = body.nextToken;
+  }
+
+  return { request: safeBody };
+}
+
+function normalizedScopeResponse(
+  data: Record<string, unknown>,
+  store: string,
+  fallbackScope?: unknown,
+) {
+  const items = Array.isArray(data.scopes) ? data.scopes : [];
+  return successResponse({
+    items,
+    totalCount: items.length,
+    nextToken: typeof data.nextToken === "string" ? data.nextToken : undefined,
+    scope: data.scope ?? fallbackScope ?? {},
+    memoryStoreName: store,
+  });
+}
+
 export async function GET(request: NextRequest, context: RouteContext) {
   try {
     const { store } = await context.params;
@@ -49,16 +132,48 @@ export async function GET(request: NextRequest, context: RouteContext) {
     // shape so the dashboard frontend's paginated list helpers can
     // consume scopes/tasks/dream-tasks/actions through one unified
     // contract instead of branching on per-route field names.
-    const data = (response.data ?? {}) as Record<string, unknown>;
-    const items = Array.isArray(data.scopes) ? data.scopes : [];
-    return successResponse({
-      items,
-      totalCount: items.length,
-      nextToken:
-        typeof data.nextToken === "string" ? data.nextToken : undefined,
-      scope: data.scope ?? scope,
+    return normalizedScopeResponse(
+      (response.data ?? {}) as Record<string, unknown>,
+      store,
+      scope,
+    );
+  } catch (error) {
+    return handleApiError(error);
+  }
+}
+
+/**
+ * POST keeps the structured Filter AST and opaque nextToken in the request
+ * body.  The legacy GET route remains for ScopeBar compatibility.
+ */
+export async function POST(request: NextRequest, context: RouteContext) {
+  try {
+    const { store } = await context.params;
+    const auth = requireClients(request);
+    if (!("memory" in auth)) return auth;
+
+    let rawBody: unknown;
+    try {
+      rawBody = await request.json();
+    } catch {
+      return badRequest("Request body must be JSON");
+    }
+    if (!isRecord(rawBody)) {
+      return badRequest("Request body must be a JSON object");
+    }
+    const parsedBody = buildScopeDirectoryRequest(rawBody);
+    if ("error" in parsedBody) return badRequest(parsedBody.error);
+    const safeBody = parsedBody.request;
+    const response = await auth.memory.listMemoryStoreScopes({
+      ...safeBody,
       memoryStoreName: store,
     });
+    if (response.code !== "SUCCESS") return forwardResponse(response);
+    return normalizedScopeResponse(
+      (response.data ?? {}) as Record<string, unknown>,
+      store,
+      safeBody.scope,
+    );
   } catch (error) {
     return handleApiError(error);
   }

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/search/route.ts

@@ -5,6 +5,7 @@ import {
   handleApiError,
   requireClients,
 } from "@/lib/server/api-helpers";
+import { parseScopeDirectoryFilter } from "@/lib/server/scope-filter-validation";
 
 export const runtime = "nodejs";
 export const dynamic = "force-dynamic";
@@ -17,6 +18,14 @@ interface RouteContext {
   params: Promise<{ store: string }>;
 }
 
+function badRequest(message: string) {
+  return forwardResponse({ code: "BAD_REQUEST", data: null, message });
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
 export async function POST(request: NextRequest, context: RouteContext) {
   try {
     const { store } = await context.params;
@@ -24,20 +33,24 @@ export async function POST(request: NextRequest, context: RouteContext) {
     if (!("memory" in auth)) return auth;
     const { memory } = auth;
 
-    let body: Record<string, unknown>;
+    let rawBody: unknown;
     try {
-      body = (await request.json()) as Record<string, unknown>;
+      rawBody = await request.json();
     } catch {
-      return forwardResponse({
-        code: "BAD_REQUEST",
-        data: null,
-        message: "Request body must be JSON",
-      });
+      return badRequest("Request body must be JSON");
     }
+    if (!isRecord(rawBody)) return badRequest("Request body must be an object");
 
     // Strip client-supplied memoryStoreName so the URL-derived value wins (D2).
-    const { memoryStoreName: _ignored, ...safeBody } = body;
+    const { memoryStoreName: _ignored, ...safeBody } = rawBody;
     void _ignored;
+    if (safeBody.filter === null) {
+      delete safeBody.filter;
+    } else if (safeBody.filter !== undefined) {
+      const parsedFilter = parseScopeDirectoryFilter(safeBody.filter);
+      if ("error" in parsedFilter) return badRequest(parsedFilter.error);
+      safeBody.filter = parsedFilter.filter;
+    }
     const resp = await memory.searchMemories({
       ...safeBody,
       memoryStoreName: store,

package/dist/dashboard-runtime/dashboard/src/app/api/v1/memory/stores/[store]/wikis/_helpers.ts

@@ -0,0 +1,317 @@
+import type { AgentWikiScope } from "../_scope";
+import { readAgentWikiScope } from "../_scope";
+
+const MAX_NAME_BYTES = 256;
+const MAX_SUMMARY_BYTES = 4096;
+const MAX_CLIENT_TOKEN_BYTES = 256;
+const MAX_PAGE_PATH_BYTES = 1024;
+const MAX_DREAM_ACTION_REFS = 100;
+const CONTROL_CHARACTER_PATTERN = /\p{Cc}/u;
+
+export const SOURCE_EXTENSIONS = new Set([".md", ".txt"]);
+export const MAX_SOURCE_CONTENT_BYTES = 100 * 1024;
+const WIKI_SOURCE_ERROR_MESSAGE = "Wiki source operation failed";
+
+export interface PublicWikiSource {
+  path: string;
+  contentSha256: string;
+  contentSizeBytes: number;
+  latestVersionId: string;
+  createdAt: string;
+  updatedAt: string;
+  content?: string;
+}
+
+export interface WikiJsonBody extends Record<string, unknown> {
+  scope: AgentWikiScope;
+}
+
+export function sanitizeWikiSourceErrorResponse<
+  T extends { code: string; message: string },
+>(response: T): T {
+  return response.code === "SUCCESS"
+    ? response
+    : { ...response, message: WIKI_SOURCE_ERROR_MESSAGE };
+}
+
+export type OptionalValue<T> = { ok: true; value?: T } | { ok: false };
+
+export interface DreamActionRef {
+  dreamId: string;
+  actionId: string;
+}
+
+function utf8Length(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function invalidRawSource(): never {
+  throw new Error("Invalid Wiki raw source");
+}
+
+export function toWikiRawItemPath(rawRelativePath: unknown): string {
+  if (typeof rawRelativePath !== "string") invalidRawSource();
+
+  const relativePath = rawRelativePath.normalize("NFC");
+  if (
+    !relativePath ||
+    relativePath.startsWith("/") ||
+    relativePath.endsWith("/") ||
+    relativePath.includes("\\") ||
+    relativePath.includes("\0")
+  ) {
+    invalidRawSource();
+  }
+
+  const segments = relativePath.split("/");
+  if (
+    segments.some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    invalidRawSource();
+  }
+
+  const fileName = segments.at(-1)!;
+  const dot = fileName.lastIndexOf(".");
+  const extension = dot < 0 ? "" : fileName.slice(dot).toLowerCase();
+  if (!SOURCE_EXTENSIONS.has(extension)) invalidRawSource();
+
+  const physicalPath = `/.wiki/raw/${relativePath}`;
+  if (utf8Length(physicalPath) > MAX_PAGE_PATH_BYTES) invalidRawSource();
+  return physicalPath;
+}
+
+export function fromWikiRawItemPath(rawPhysicalPath: unknown): string {
+  if (typeof rawPhysicalPath !== "string") invalidRawSource();
+
+  const prefix = "/.wiki/raw/";
+  if (!rawPhysicalPath.startsWith(prefix)) invalidRawSource();
+  const relativePath = rawPhysicalPath.slice(prefix.length);
+  if (toWikiRawItemPath(relativePath) !== rawPhysicalPath) {
+    invalidRawSource();
+  }
+  return relativePath;
+}
+
+export function assertWikiSourceContent(rawContent: unknown): string {
+  if (
+    typeof rawContent !== "string" ||
+    utf8Length(rawContent) > MAX_SOURCE_CONTENT_BYTES
+  ) {
+    throw new Error("Invalid Wiki raw source content");
+  }
+  return rawContent;
+}
+
+export function toPublicWikiSource(rawItem: unknown): PublicWikiSource {
+  if (!rawItem || typeof rawItem !== "object" || Array.isArray(rawItem)) {
+    invalidRawSource();
+  }
+  const item = rawItem as Record<string, unknown>;
+  if (
+    typeof item.contentSha256 !== "string" ||
+    typeof item.contentSizeBytes !== "number" ||
+    !Number.isFinite(item.contentSizeBytes) ||
+    item.contentSizeBytes < 0 ||
+    typeof item.latestVersionId !== "string" ||
+    !item.latestVersionId ||
+    typeof item.createdAt !== "string" ||
+    typeof item.updatedAt !== "string" ||
+    (item.content !== undefined && typeof item.content !== "string")
+  ) {
+    throw new Error("Invalid Memory Item response");
+  }
+  return {
+    path: fromWikiRawItemPath(item.path),
+    contentSha256: item.contentSha256,
+    contentSizeBytes: item.contentSizeBytes,
+    latestVersionId: item.latestVersionId,
+    createdAt: item.createdAt,
+    updatedAt: item.updatedAt,
+    ...(typeof item.content === "string" ? { content: item.content } : {}),
+  };
+}
+
+export function hasCallerWikiId(
+  request: Request,
+  body?: Record<string, unknown> | null,
+): boolean {
+  return (
+    new URL(request.url).searchParams.has("wikiId") ||
+    (body !== undefined &&
+      body !== null &&
+      Object.prototype.hasOwnProperty.call(body, "wikiId"))
+  );
+}
+
+export function hasCallerBuildId(
+  request: Request,
+  body?: Record<string, unknown> | null,
+): boolean {
+  return (
+    new URL(request.url).searchParams.has("buildId") ||
+    (body !== undefined &&
+      body !== null &&
+      Object.prototype.hasOwnProperty.call(body, "buildId"))
+  );
+}
+
+export function readExactScopeFromQuery(
+  params: URLSearchParams,
+): AgentWikiScope | null {
+  return readAgentWikiScope({
+    appId: params.get("appId"),
+    tenantId: params.get("tenantId"),
+    agentId: params.get("agentId"),
+  });
+}
+
+export async function readWikiJsonBody(
+  request: Request,
+): Promise<WikiJsonBody | null> {
+  let raw: unknown;
+  try {
+    raw = await request.json();
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+
+  const body = raw as Record<string, unknown>;
+  const scope = readAgentWikiScope(body.scope);
+  return scope ? { ...body, scope } : null;
+}
+
+export function readWikiPagePath(raw: unknown): string | null {
+  if (typeof raw !== "string" || raw.includes("\\") || raw.includes("\0")) {
+    return null;
+  }
+
+  const path = raw;
+  if (
+    !path.startsWith("/wiki/") ||
+    !path.toLowerCase().endsWith(".md") ||
+    utf8Length(path) > MAX_PAGE_PATH_BYTES
+  ) {
+    return null;
+  }
+
+  const segments = path.split("/").slice(1);
+  if (
+    segments.some(
+      (segment) => segment.length === 0 || segment === "." || segment === "..",
+    )
+  ) {
+    return null;
+  }
+  return path;
+}
+
+export function readRequiredWikiName(raw: unknown): string | null {
+  if (typeof raw !== "string" || utf8Length(raw) > MAX_NAME_BYTES) return null;
+  const name = raw.trim();
+  return name || null;
+}
+
+export function readOptionalWikiName(raw: unknown): OptionalValue<string> {
+  if (raw === undefined) return { ok: true };
+  const name = readRequiredWikiName(raw);
+  return name === null ? { ok: false } : { ok: true, value: name };
+}
+
+export function readOptionalWikiSummary(raw: unknown): OptionalValue<string> {
+  if (raw === undefined) return { ok: true };
+  return typeof raw === "string" && utf8Length(raw) <= MAX_SUMMARY_BYTES
+    ? { ok: true, value: raw }
+    : { ok: false };
+}
+
+export function readOptionalClientToken(raw: unknown): OptionalValue<string> {
+  if (raw === undefined) return { ok: true };
+  if (
+    typeof raw !== "string" ||
+    !raw.trim() ||
+    utf8Length(raw) > MAX_CLIENT_TOKEN_BYTES
+  ) {
+    return { ok: false };
+  }
+  return { ok: true, value: raw };
+}
+
+export function readOptionalDreamActionRefs(
+  raw: unknown,
+): OptionalValue<DreamActionRef[]> {
+  if (raw === undefined) return { ok: true };
+  if (!Array.isArray(raw) || raw.length > MAX_DREAM_ACTION_REFS) {
+    return { ok: false };
+  }
+
+  const refs: DreamActionRef[] = [];
+  const seen = new Set<string>();
+  for (const value of raw) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return { ok: false };
+    }
+    const record = value as Record<string, unknown>;
+    if (
+      typeof record.dreamId !== "string" ||
+      typeof record.actionId !== "string"
+    ) {
+      return { ok: false };
+    }
+    const normalizedDreamId = record.dreamId.trim();
+    const normalizedActionId = record.actionId.trim();
+    if (
+      !normalizedDreamId ||
+      !normalizedActionId ||
+      utf8Length(record.dreamId) > 128 ||
+      utf8Length(record.actionId) > 128 ||
+      utf8Length(normalizedDreamId) > 128 ||
+      utf8Length(normalizedActionId) > 128 ||
+      CONTROL_CHARACTER_PATTERN.test(normalizedDreamId + normalizedActionId)
+    ) {
+      return { ok: false };
+    }
+    const key = `${normalizedDreamId}\0${normalizedActionId}`;
+    if (seen.has(key)) return { ok: false };
+    seen.add(key);
+    refs.push({
+      dreamId: normalizedDreamId,
+      actionId: normalizedActionId,
+    });
+  }
+  return { ok: true, value: refs };
+}
+
+export function readOptionalQueryLimit(
+  raw: string | null,
+): OptionalValue<number> {
+  if (raw === null) return { ok: true };
+  if (!/^\d+$/.test(raw)) return { ok: false };
+  const limit = Number(raw);
+  return Number.isInteger(limit) && limit >= 1 && limit <= 100
+    ? { ok: true, value: limit }
+    : { ok: false };
+}
+
+export function readOptionalJsonLimit(raw: unknown): OptionalValue<number> {
+  if (raw === undefined) return { ok: true };
+  return typeof raw === "number" &&
+    Number.isInteger(raw) &&
+    raw >= 1 &&
+    raw <= 100
+    ? { ok: true, value: raw }
+    : { ok: false };
+}
+
+export function readOptionalNextToken(
+  raw: string | null,
+): OptionalValue<string> {
+  if (raw === null) return { ok: true };
+  return raw.trim() ? { ok: true, value: raw } : { ok: false };
+}
+
+export function readRequiredSearchQuery(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const query = raw.trim();
+  return query || null;
+}