@tablestore/tablestore-agent-cli 0.2.0 → 0.2.1

package/dist/dashboard-runtime/dashboard/src/lib/glob-filter.ts

@@ -0,0 +1,76 @@
+/**
+ * Translate user-friendly extension / prefix tokens into the glob patterns
+ * the KB server expects on `inclusionFilters` / `exclusionFilters`.
+ *
+ * The server only accepts one of two pattern shapes:
+ *   - prefix:  `value*` (wildcard at the END, anchors the start)
+ *   - suffix:  `*value` (wildcard at the START, anchors the end)
+ *
+ * The dashboard masks these details — users type plain text in the UI
+ * (e.g. ".md, .pdf" for suffix include; "archive/2026/, drafts/" for prefix
+ * include) and these helpers wrap them. Already-globbed input is detected
+ * and left alone, so a user who pastes "*.md" or "drafts/*" gets the same
+ * result as one who types ".md" or "drafts/".
+ */
+
+/**
+ * Lowercase, trim, and split a comma-separated input list. Empty tokens are
+ * dropped. Used by both prefix and suffix parsers below.
+ */
+function tokenize(raw: string): string[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Wrap each token as a suffix glob: ".md, .pdf" → ["*.md", "*.pdf"].
+ *
+ * Idempotent — a token that already starts with `*` is kept verbatim, so
+ * users who type the canonical glob form don't get a double-star.
+ */
+export function parseSuffixGlobs(raw: string): string[] {
+  return tokenize(raw).map((token) => (token.startsWith("*") ? token : `*${token}`));
+}
+
+/**
+ * Wrap each token as a prefix glob: "drafts/, archive/2026/" →
+ * ["drafts/*", "archive/2026/*"].
+ *
+ * Idempotent on tokens already ending in `*`.
+ */
+export function parsePrefixGlobs(raw: string): string[] {
+  return tokenize(raw).map((token) => (token.endsWith("*") ? token : `${token}*`));
+}
+
+/**
+ * Combine prefix and suffix inclusion / exclusion inputs into the flat
+ * `inclusionFilters` / `exclusionFilters` arrays the server consumes.
+ * Returns `undefined` for empty buckets so callers can spread without
+ * leaking empty arrays into the request body.
+ */
+export interface FolderGlobInputs {
+  prefixIncludeInput: string;
+  prefixExcludeInput: string;
+  suffixIncludeInput: string;
+  suffixExcludeInput: string;
+}
+
+export function buildFolderGlobs(inputs: FolderGlobInputs): {
+  inclusionFilters?: string[];
+  exclusionFilters?: string[];
+} {
+  const inclusionFilters = [
+    ...parsePrefixGlobs(inputs.prefixIncludeInput),
+    ...parseSuffixGlobs(inputs.suffixIncludeInput),
+  ];
+  const exclusionFilters = [
+    ...parsePrefixGlobs(inputs.prefixExcludeInput),
+    ...parseSuffixGlobs(inputs.suffixExcludeInput),
+  ];
+  return {
+    inclusionFilters: inclusionFilters.length > 0 ? inclusionFilters : undefined,
+    exclusionFilters: exclusionFilters.length > 0 ? exclusionFilters : undefined,
+  };
+}

package/dist/dashboard-runtime/dashboard/src/lib/oss-selection.ts

@@ -0,0 +1,58 @@
+/**
+ * Discriminated selection algebra used by the OSS browser. Splitting the
+ * shape into a tagged union (instead of two parallel sets) keeps the
+ * "checked file" vs. "checked folder" distinction visible at every call
+ * site without bug-prone implicit-conversion paths.
+ */
+export type OssSelectedItem =
+  | { type: "file"; ossKey: string; size: number }
+  | { type: "folder"; prefix: string };
+
+export type OssSelection = OssSelectedItem[];
+
+export function isFileSelected(sel: OssSelection, ossKey: string): boolean {
+  return sel.some((s) => s.type === "file" && s.ossKey === ossKey);
+}
+
+export function isFolderSelected(sel: OssSelection, prefix: string): boolean {
+  return sel.some((s) => s.type === "folder" && s.prefix === prefix);
+}
+
+export function toggleFile(
+  sel: OssSelection,
+  file: { ossKey: string; size: number },
+): OssSelection {
+  if (isFileSelected(sel, file.ossKey)) {
+    return sel.filter((s) => !(s.type === "file" && s.ossKey === file.ossKey));
+  }
+  return [...sel, { type: "file", ossKey: file.ossKey, size: file.size }];
+}
+
+export function toggleFolder(
+  sel: OssSelection,
+  folder: { prefix: string },
+): OssSelection {
+  if (isFolderSelected(sel, folder.prefix)) {
+    return sel.filter((s) => !(s.type === "folder" && s.prefix === folder.prefix));
+  }
+  return [...sel, { type: "folder", prefix: folder.prefix }];
+}
+
+/**
+ * Split a selection into the two payloads consumers need at submission time:
+ * an explicit ossKey list (files), and the prefixes that need to go through
+ * `expandPrefixes()`. Order within each list is preserved so the UI can
+ * render a stable preview.
+ */
+export function partitionSelection(sel: OssSelection): {
+  fileKeys: string[];
+  folderPrefixes: string[];
+} {
+  const fileKeys: string[] = [];
+  const folderPrefixes: string[] = [];
+  for (const item of sel) {
+    if (item.type === "file") fileKeys.push(item.ossKey);
+    else folderPrefixes.push(item.prefix);
+  }
+  return { fileKeys, folderPrefixes };
+}

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

@@ -0,0 +1,65 @@
+import OSS from "ali-oss";
+
+import type { AppConfig } from "@tablestore/tablestore-agent-shared";
+
+/**
+ * Build an `ali-oss` client from a resolved AppConfig, or `null` if no OSS
+ * target has been configured for this instance. Callers should treat `null`
+ * as the `OSS_NOT_CONFIGURED` case — the upstream error envelope.
+ *
+ * Construction mirrors the upstream agent-storage SDK's OSSUploader (which is
+ * the path that successfully uploads files for the local-upload tab):
+ * v1 signing (no `authorizationV4`), raw region, explicit endpoint. We do
+ * NOT mirror `packages/sdk/src/managed-oss.ts` here — that file is the
+ * bucket-creation path, which talks to a different OSS surface that requires
+ * v4. Forcing v4 on object-operation calls produces "SignatureDoesNotMatch"
+ * because the canonical string is computed against a region that the
+ * legacy bucket signing flow doesn't agree with.
+ */
+export function getOssClient(config: AppConfig): OSS | null {
+  const endpoint = (config.oss_endpoint ?? "").trim();
+  const bucket = (config.oss_bucket_name ?? "").trim();
+  const region = (config.region ?? "").trim();
+  if (!endpoint || !bucket || !region) return null;
+
+  return new OSS({
+    accessKeyId: config.access_key_id ?? "",
+    accessKeySecret: config.access_key_secret ?? "",
+    bucket,
+    region,
+    endpoint,
+    secure: true,
+  });
+}
+
+/**
+ * Translate an error from ali-oss (or anywhere else in the OSS path) into
+ * the dashboard's canonical `{ code, httpStatus, message }` triple. The
+ * route handlers feed this directly into `forwardResponse`.
+ */
+export function mapOssError(error: unknown): {
+  code: string;
+  httpStatus: number;
+  message: string;
+} {
+  // ali-oss attaches a string `code` on every operational error; lean on it.
+  const ossCode =
+    error && typeof error === "object" && "code" in error
+      ? String((error as { code: unknown }).code ?? "")
+      : "";
+  const message =
+    error instanceof Error ? error.message : String(error ?? "Unknown OSS error");
+
+  switch (ossCode) {
+    case "AccessDenied":
+    case "InvalidAccessKeyId":
+    case "SignatureDoesNotMatch":
+      return { code: "OSS_FORBIDDEN", httpStatus: 403, message };
+    case "NoSuchBucket":
+      return { code: "OSS_BUCKET_NOT_FOUND", httpStatus: 404, message };
+    case "InvalidArgument":
+      return { code: "BAD_REQUEST", httpStatus: 400, message };
+    default:
+      return { code: "OSS_UPSTREAM_ERROR", httpStatus: 502, message };
+  }
+}

package/dist/dashboard-runtime/dashboard/src/schemas/knowledge-base.ts

@@ -29,7 +29,7 @@ const embeddingConfigSchema = z.object({
 
 const rerankingConfigSchema = z.object({
   type: z.enum(["RRF", "WEIGHT", "MODEL"]),
-  numberOfResults: z.number().int().positive().optional(),
+  numberOfResults: z.number().int().min(0).max(200).optional(),
   rrfConfiguration: z
     .object({
       denseVectorSearchWeight: z.number().min(0),
@@ -57,10 +57,10 @@ const retrievalConfigSchema = z.object({
     .min(1)
     .optional(),
   denseVectorSearchConfiguration: z
-    .object({ numberOfResults: z.number().int().positive() })
+    .object({ numberOfResults: z.number().int().min(0).max(100) })
     .optional(),
   fullTextSearchConfiguration: z
-    .object({ numberOfResults: z.number().int().positive() })
+    .object({ numberOfResults: z.number().int().min(0).max(100) })
     .optional(),
   rerankingConfiguration: rerankingConfigSchema.optional(),
 });

package/dist/dashboard-runtime/dashboard/src/schemas/llm-chat.ts

@@ -11,7 +11,7 @@ export const chatRagKbSchema = z.object({
   knowledgeBaseName: z.string().min(1),
   subspace: z.array(z.string()).optional(),
   retrievalConfiguration: z.record(z.unknown()).optional(),
-  topK: z.number().int().min(1).max(200).optional(),
+  topK: z.number().int().min(0).max(100).optional(),
 });
 
 export const chatRagSchema = z.object({

package/dist/dashboard-runtime/dashboard/src/schemas/retrieval.ts

@@ -7,7 +7,10 @@ export const retrievalSchema = z.object({
     .min(1, "Query must be at least 1 character")
     .max(128, "Query must be at most 128 characters"),
   subspace: z.array(z.string()).optional(),
-  topK: z.number().int().min(1).max(100).default(20).optional(),
+  topK: z.number().int().min(0).max(100).default(20).optional(),
+  denseTopK: z.number().int().min(0).max(100).default(20).optional(),
+  fullTextTopK: z.number().int().min(0).max(100).default(20).optional(),
+  rerankTopK: z.number().int().min(0).max(200).default(20).optional(),
   searchType: z
     .array(z.enum(["DENSE_VECTOR", "FULL_TEXT"]))
     .optional(),

package/dist/dashboard-runtime/dashboard/src/services/api-client.ts

@@ -133,14 +133,19 @@ export async function apiGet<T>(
 
 export async function apiPost<T>(
   path: string,
-  body?: unknown
+  body?: unknown,
+  timeoutMs?: number
 ): Promise<T> {
   const response = await requestWithClientLogging(path, () =>
-    fetchWithTimeout(buildUrl(path), {
-      method: "POST",
-      headers: buildHeaders("application/json"),
-      body: body !== undefined ? JSON.stringify(body) : undefined,
-    })
+    fetchWithTimeout(
+      buildUrl(path),
+      {
+        method: "POST",
+        headers: buildHeaders("application/json"),
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      },
+      timeoutMs,
+    )
   );
   return handleResponse<T>(response);
 }

package/dist/dashboard-runtime/dashboard/src/services/documents.ts

@@ -28,13 +28,23 @@ export async function getDocument(
   );
 }
 
+export interface AddDocumentItem {
+  ossKey: string;
+  metadata?: Record<string, unknown>;
+  /**
+   * Glob patterns the server uses to filter members of a folder ossKey
+   * during recursive ingestion. Ignored when `ossKey` points at a single
+   * file. Only one wildcard is allowed per pattern: `prefix*` (anchored at
+   * the start) or `*suffix` (anchored at the end).
+   */
+  inclusionFilters?: string[];
+  exclusionFilters?: string[];
+}
+
 export interface AddDocumentsRequest {
   knowledgeBaseName: string;
   subspace?: string;
-  documents: Array<{
-    ossKey: string;
-    metadata?: Record<string, unknown>;
-  }>;
+  documents: AddDocumentItem[];
 }
 
 export interface DocumentOperationResult {
@@ -45,19 +55,28 @@ export interface DocumentOperationResult {
 }
 
 export async function addDocuments(
-  request: AddDocumentsRequest
+  request: AddDocumentsRequest,
+  options?: { timeoutMs?: number },
 ): Promise<{ documentDetails: DocumentOperationResult[] }> {
   const { knowledgeBaseName, documents, ...rest } = request;
   const url = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents`;
 
   if (documents.length <= BATCH_SIZE) {
-    return apiPost<{ documentDetails: DocumentOperationResult[] }>(url, { documents, ...rest });
+    return apiPost<{ documentDetails: DocumentOperationResult[] }>(
+      url,
+      { documents, ...rest },
+      options?.timeoutMs,
+    );
   }
 
   const allResults: DocumentOperationResult[] = [];
   for (let i = 0; i < documents.length; i += BATCH_SIZE) {
     const batch = documents.slice(i, i + BATCH_SIZE);
-    const resp = await apiPost<{ documentDetails: DocumentOperationResult[] }>(url, { documents: batch, ...rest });
+    const resp = await apiPost<{ documentDetails: DocumentOperationResult[] }>(
+      url,
+      { documents: batch, ...rest },
+      options?.timeoutMs,
+    );
     allResults.push(...resp.documentDetails);
   }
   return { documentDetails: allResults };
@@ -94,7 +113,7 @@ export async function uploadDocuments(
 
 // Server-side limit for documents per request across all batch endpoints.
 const BATCH_SIZE = 10;
-const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per batch
+export const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per batch
 
 export interface BatchUploadProgress {
   completedBatches: number;

package/dist/dashboard-runtime/dashboard/src/services/oss.ts

@@ -0,0 +1,36 @@
+import { apiGet } from "./api-client";
+
+export interface OssListFolder {
+  name: string;     // basename ending with "/", e.g. "january/"
+  prefix: string;   // full prefix, e.g. "docs/2026/january/"
+}
+
+export interface OssListFile {
+  name: string;       // basename without prefix, e.g. "spec.pdf"
+  ossKey: string;     // full key, e.g. "docs/2026/spec.pdf"
+  size: number;
+  lastModified: string; // ISO 8601
+}
+
+export interface OssListPage {
+  prefix: string;
+  folders: OssListFolder[];
+  files: OssListFile[];
+  nextContinuationToken: string | null;
+  totalEstimate: number;
+}
+
+export async function listOssObjects(params: {
+  prefix?: string;
+  continuationToken?: string;
+  maxResults?: number;
+  search?: string;
+}): Promise<OssListPage> {
+  const q = new URLSearchParams();
+  if (params.prefix) q.set("prefix", params.prefix);
+  if (params.continuationToken) q.set("continuationToken", params.continuationToken);
+  if (params.maxResults) q.set("maxResults", String(params.maxResults));
+  if (params.search) q.set("search", params.search);
+  return apiGet<OssListPage>(`/api/v1/oss/list?${q.toString()}`);
+}
+

package/dist/dashboard-runtime/dashboard/src/types/knowledge-base.ts

@@ -44,7 +44,7 @@ export type SearchType = "DENSE_VECTOR" | "FULL_TEXT";
 
 export interface RerankingConfiguration {
   type: RerankType;
-  numberOfResults: number;
+  numberOfResults?: number;
   rrfConfiguration?: RrfConfiguration;
   weightConfiguration?: WeightConfiguration;
   modelConfiguration?: ModelConfiguration;

package/dist/dashboard-runtime/dashboard/vitest.config.mjs

@@ -1,6 +1,12 @@
+import { resolve } from "node:path";
 import { defineConfig } from "vitest/config";
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      "@": resolve(__dirname, "src"),
+    },
+  },
   test: {
     environment: "node",
     include: ["src/**/__tests__/**/*.test.ts"],