@tablestore/tablestore-agent-cli 0.3.1 → 0.4.0

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

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

@@ -0,0 +1,194 @@
+import type { NextRequest } from "next/server";
+
+import {
+  errorResponse,
+  forwardResponse,
+  handleApiError,
+  requireClients,
+} from "@/lib/server/api-helpers";
+
+import { readExactScopeFromQuery } from "../_helpers";
+import { readExactMemoryScope, type AgentWikiScope } from "../../_scope";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+type ArtifactKind = "skill" | "profile";
+
+interface RouteContext {
+  params: Promise<{ store: string }>;
+}
+
+interface PublicArtifact {
+  dreamId: string;
+  actionId: string;
+  kind: ArtifactKind;
+  name: string;
+  description: string;
+  targetScope: {
+    appId: string;
+    tenantId: string;
+    agentId: string;
+    runId: string;
+  };
+  appliedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+function scopeKey(scope: AgentWikiScope): string {
+  return [scope.appId, scope.tenantId, scope.agentId].join("\0");
+}
+
+const ACTION_TYPE: Record<ArtifactKind, "EMIT_SKILL" | "EMIT_PROFILE"> = {
+  skill: "EMIT_SKILL",
+  profile: "EMIT_PROFILE",
+};
+
+function readKind(raw: string | null): ArtifactKind | null {
+  return raw === "skill" || raw === "profile" ? raw : null;
+}
+
+function readLimit(raw: string | null): number | null {
+  if (raw === null) return 100;
+  const value = Number(raw);
+  return Number.isInteger(value) && value >= 1 && value <= 100 ? value : null;
+}
+
+function readRequiredString(
+  value: Record<string, unknown>,
+  key: string,
+): string | null {
+  const raw = value[key];
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
+
+function normalizeArtifact(
+  raw: unknown,
+  kind: ArtifactKind,
+  expectedScope: AgentWikiScope,
+): PublicArtifact | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const action = raw as Record<string, unknown>;
+  if (action.action !== ACTION_TYPE[kind] || action.status !== "applied") {
+    return null;
+  }
+  if (
+    !action.newExtract ||
+    typeof action.newExtract !== "object" ||
+    Array.isArray(action.newExtract) ||
+    !action.targetScope ||
+    typeof action.targetScope !== "object" ||
+    Array.isArray(action.targetScope)
+  ) {
+    return null;
+  }
+  const extract = action.newExtract as Record<string, unknown>;
+  const targetScope = readExactMemoryScope(action.targetScope);
+  const dreamId = readRequiredString(action, "dreamId");
+  const actionId = readRequiredString(action, "actionId");
+  const name = readRequiredString(extract, "name");
+  const description = readRequiredString(extract, "description");
+  const createdAt = readRequiredString(action, "createdAt");
+  const updatedAt = readRequiredString(action, "updatedAt");
+  if (
+    extract.kind !== kind ||
+    !dreamId ||
+    !actionId ||
+    !name ||
+    !description ||
+    !targetScope ||
+    scopeKey(targetScope) !== scopeKey(expectedScope) ||
+    !createdAt ||
+    !updatedAt
+  ) {
+    return null;
+  }
+
+  const appliedAt = readRequiredString(action, "appliedAt");
+  return {
+    dreamId,
+    actionId,
+    kind,
+    name,
+    description,
+    targetScope,
+    ...(appliedAt ? { appliedAt } : {}),
+    createdAt,
+    updatedAt,
+  };
+}
+
+function normalizeArtifacts(
+  raw: unknown,
+  kind: ArtifactKind,
+  expectedScope: AgentWikiScope,
+): PublicArtifact[] {
+  if (!Array.isArray(raw)) return [];
+  const artifacts: PublicArtifact[] = [];
+  const seen = new Set<string>();
+  for (const row of raw) {
+    const artifact = normalizeArtifact(row, kind, expectedScope);
+    if (!artifact) continue;
+    const key = `${artifact.dreamId}\0${artifact.actionId}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    artifacts.push(artifact);
+  }
+  return artifacts;
+}
+
+export async function GET(request: NextRequest, context: RouteContext) {
+  try {
+    const { store } = await context.params;
+    const auth = requireClients(request);
+    if (!("memory" in auth)) return auth;
+
+    const params = new URL(request.url).searchParams;
+    const kind = readKind(params.get("kind"));
+    const scope = readExactScopeFromQuery(params);
+    const limit = readLimit(params.get("limit"));
+    if (!kind || !scope || limit === null) {
+      return errorResponse(
+        "BAD_REQUEST",
+        "kind, exact scope, and a limit between 1 and 100 are required",
+        400,
+      );
+    }
+
+    const nextToken = params.get("nextToken") || undefined;
+    const response = await auth.memory.listMemoryDreamActions(
+      {
+        memoryStoreName: store,
+        scope: { ...scope, runId: "*" },
+        actionType: ACTION_TYPE[kind],
+        status: "applied",
+        limit,
+        ...(nextToken ? { nextToken } : {}),
+      },
+      request.signal,
+    );
+    if (response.code !== "SUCCESS") return forwardResponse(response);
+
+    const data =
+      response.data &&
+      typeof response.data === "object" &&
+      !Array.isArray(response.data)
+        ? (response.data as Record<string, unknown>)
+        : {};
+    const upstreamNextToken =
+      typeof data.nextToken === "string" ? data.nextToken : undefined;
+    return forwardResponse({
+      ...response,
+      data: {
+        memoryStoreName: store,
+        artifacts: normalizeArtifacts(data.actions, kind, scope),
+        ...(upstreamNextToken !== undefined
+          ? { nextToken: upstreamNextToken }
+          : {}),
+      },
+    });
+  } catch (error) {
+    return handleApiError(error);
+  }
+}

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

@@ -0,0 +1,60 @@
+import type { NextRequest } from "next/server";
+
+import {
+  errorResponse,
+  forwardResponse,
+  handleApiError,
+  requireClients,
+} from "@/lib/server/api-helpers";
+
+import {
+  hasCallerWikiId,
+  readOptionalClientToken,
+  readOptionalDreamActionRefs,
+  readWikiJsonBody,
+} from "../_helpers";
+import { toAgentWikiScope } from "../../_scope";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+interface RouteContext {
+  params: Promise<{ store: string }>;
+}
+
+export async function POST(request: NextRequest, context: RouteContext) {
+  try {
+    const { store } = await context.params;
+    const auth = requireClients(request);
+    if (!("wiki" in auth)) return auth;
+
+    const body = await readWikiJsonBody(request);
+    const clientToken = readOptionalClientToken(body?.clientToken);
+    const dreamActionRefs = readOptionalDreamActionRefs(body?.dreamActionRefs);
+    if (
+      !body ||
+      hasCallerWikiId(request, body) ||
+      !clientToken.ok ||
+      !dreamActionRefs.ok
+    ) {
+      return errorResponse("BAD_REQUEST", "Invalid ingest Wiki request", 400);
+    }
+
+    const response = await auth.wiki.ingestWiki(
+      {
+        memoryStoreName: store,
+        scope: toAgentWikiScope(body.scope),
+        ...(clientToken.value !== undefined
+          ? { clientToken: clientToken.value }
+          : {}),
+        ...(dreamActionRefs.value !== undefined
+          ? { dreamActionRefs: dreamActionRefs.value }
+          : {}),
+      },
+      request.signal,
+    );
+    return forwardResponse(response);
+  } catch (error) {
+    return handleApiError(error);
+  }
+}