@axiom-lattice/protocols 2.1.48 → 2.1.50

package/src/CollectionStoreProtocol.ts

@@ -0,0 +1,131 @@
+/**
+ * CollectionStoreProtocol
+ *
+ * Collection store protocol definitions for the Axiom Lattice framework.
+ * Provides standardized interfaces for collection management across all implementations.
+ */
+
+/**
+ * Collection field type definition
+ */
+export type CollectionFieldType = 'string' | 'number' | 'enum';
+
+/**
+ * Collection field definition
+ */
+export interface CollectionField {
+  /** Field key name, written to metadata[key] */
+  key: string;
+  /** Field data type */
+  type: CollectionFieldType;
+  /** Valid values for enum type */
+  enumValues?: string[];
+  /** Whether the field is required on entry creation */
+  required?: boolean;
+}
+
+/**
+ * Collection schema definition
+ */
+export interface CollectionSchema {
+  /** Custom field definitions */
+  fields: CollectionField[];
+}
+
+/**
+ * Collection type definition
+ */
+export interface Collection {
+  /** Collection unique identifier */
+  id: string;
+  /** Collection name (unique per tenant, corresponds to vector table name) */
+  name: string;
+  /** Tenant identifier */
+  tenantId: string;
+  /** Human-readable display name */
+  label: string;
+  /** Embedding model key (registered in EmbeddingsLatticeManager) */
+  embeddingKey: string;
+  /** Custom field schema */
+  schema: CollectionSchema;
+  /** Creation timestamp */
+  createdAt: Date;
+  /** Last update timestamp */
+  updatedAt: Date;
+}
+
+/**
+ * Create collection request type
+ */
+export interface CreateCollectionRequest {
+  /** Collection name (required) */
+  name: string;
+  /** Human-readable display name (required) */
+  label: string;
+  /** Embedding model key (required) */
+  embeddingKey: string;
+  /** Custom field schema (optional) */
+  schema?: CollectionSchema;
+}
+
+/**
+ * Update collection request type
+ */
+export interface UpdateCollectionRequest {
+  /** Human-readable display name */
+  label?: string;
+  /** Embedding model key */
+  embeddingKey?: string;
+  /** Custom field schema */
+  schema?: CollectionSchema;
+}
+
+/**
+ * CollectionStore interface
+ * Provides CRUD operations for collection metadata
+ */
+export interface CollectionStore {
+  /**
+   * Get all collections for a tenant
+   * @param tenantId Tenant identifier
+   * @returns Array of all collections for the tenant
+   */
+  getAllCollections(tenantId: string): Promise<Collection[]>;
+
+  /**
+   * Get collection by name
+   * @param tenantId Tenant identifier
+   * @param name Collection name
+   * @returns Collection if found, null otherwise
+   */
+  getCollectionByName(tenantId: string, name: string): Promise<Collection | null>;
+
+  /**
+   * Create a new collection
+   * @param tenantId Tenant identifier
+   * @param data Collection creation data
+   * @returns Created collection
+   */
+  createCollection(tenantId: string, data: CreateCollectionRequest): Promise<Collection>;
+
+  /**
+   * Update an existing collection
+   * @param tenantId Tenant identifier
+   * @param name Collection name
+   * @param updates Partial updates
+   * @returns Updated collection if found, null otherwise
+   */
+  updateCollection(
+    tenantId: string,
+    name: string,
+    updates: UpdateCollectionRequest
+  ): Promise<Collection | null>;
+
+  /**
+   * Delete a collection by name
+   * @param tenantId Tenant identifier
+   * @param name Collection name
+   * @returns true if deleted, false otherwise
+   */
+  deleteCollection(tenantId: string, name: string): Promise<boolean>;
+}

package/src/ConnectionStoreProtocol.ts

@@ -0,0 +1,28 @@
+/**
+ * ConnectionStore Protocol
+ *
+ * Generic store for external service connections (databases, APIs, etc.).
+ * Provides tenant-scoped CRUD operations keyed by a unique business key.
+ * The key is scoped to (tenant_id, type) — same tenant, same plugin type
+ * can't use duplicate keys, but different types can share keys (ERP "prod" != CRM "prod").
+ */
+
+export interface ConnectionEntry {
+  id: string;
+  tenantId: string;
+  type: string;
+  key: string;
+  name: string;
+  description?: string;
+  config: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ConnectionStore {
+  listByType(tenantId: string, type: string): Promise<ConnectionEntry[]>;
+  getByKey(tenantId: string, type: string, key: string): Promise<ConnectionEntry | null>;
+  create(entry: Omit<ConnectionEntry, "id" | "createdAt" | "updatedAt">): Promise<ConnectionEntry>;
+  update(tenantId: string, type: string, key: string, updates: Partial<ConnectionEntry>): Promise<ConnectionEntry | null>;
+  delete(tenantId: string, type: string, key: string): Promise<boolean>;
+}

package/src/PluginProtocol.ts

@@ -0,0 +1,145 @@
+/**
+ * Plugin Connection 字段 schema（驱动前端表单渲染）
+ */
+export interface PluginConnectionFieldSchema {
+  /** 字段 key */
+  key: string;
+  /** 字段类型 */
+  type: "string" | "number" | "boolean" | "password";
+  /** UI 标签 */
+  title: string;
+  /** 前端 widget 类型 */
+  widget?: "input" | "password" | "select" | "numberInput";
+  /** 是否必填 */
+  required?: boolean;
+  /** 默认值 */
+  default?: unknown;
+  /** 如果是 select widget，可选值列表 */
+  enumValues?: string[];
+  /** 帮助文本 */
+  helpText?: string;
+}
+
+/**
+ * 连接测试结果
+ */
+export interface PluginConnectionTestResult {
+  ok: boolean;
+  message: string;
+  /** 可选的附加诊断信息 */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * 资源发现条目
+ */
+export interface PluginDiscoveredResource {
+  id: string;
+  name: string;
+  /** 可选的归组 */
+  group?: string;
+  /** 可选描述 */
+  description?: string;
+}
+
+/**
+ * 插件连接定义（全部可选，存在即生效）
+ *
+ * - fields: 前端渲染表单字段
+ * - test: 连通测试 → API 推导 hasTest
+ * - discover: 资源发现 → API 推导 hasDiscover
+ * - resourceLabel: 资源面板标题
+ */
+export interface PluginConnection {
+  /** 连接表单字段 */
+  fields: PluginConnectionFieldSchema[];
+  /** 连通测试回调（存在即声明 hasTest: true） */
+  test?: (config: Record<string, unknown>) => Promise<PluginConnectionTestResult>;
+  /** 资源发现回调（存在即声明 hasDiscover: true） */
+  discover?: (config: Record<string, unknown>) => Promise<PluginDiscoveredResource[]>;
+  /** 资源发现面板标题 */
+  resourceLabel?: string;
+}
+
+/**
+ * 工具元信息（用于前端 allowedTools 筛选）
+ */
+export interface PluginToolMeta {
+  name: string;
+  description: string;
+}
+
+/**
+ * 插件元数据（开发者声明）
+ *
+ * connectionSchema 不在此类型中——由 serializePluginMeta 自动推导后注入 PluginMetaOutput。
+ */
+export interface PluginMeta {
+  /** 插件唯一标识，如 "erp" */
+  type: string;
+  /** 显示名称 */
+  name: string;
+  /** 描述 */
+  description: string;
+  /** 版本号，为包管理预留 */
+  version?: string;
+  /** 安装来源，如 "npm:my-plugin@1.2.0" */
+  source?: string;
+  /** 图标名称（可选，前端渲染用） */
+  icon?: string;
+  /** 工具清单（可选，middleware 能自动提取时不需要写） */
+  tools?: PluginToolMeta[];
+  /** 中间件配置 schema（用于 agent 配置面板） */
+  configSchema?: Record<string, unknown>;
+  /** 默认配置 */
+  defaultConfig?: Record<string, unknown>;
+}
+
+/**
+ * 插件元数据输出（API 返回格式）
+ *
+ * 在 PluginMeta 基础上增加了由 serializePluginMeta 自动推导的 connectionSchema。
+ */
+export interface PluginMetaOutput extends PluginMeta {
+  /** 连接 schema（由 API 端点从 connection 方法存在性自动注入） */
+  connectionSchema?: {
+    fields: PluginConnectionFieldSchema[];
+    hasTest: boolean;
+    hasDiscover: boolean;
+    resourceLabel?: string;
+  };
+}
+
+/**
+ * 中间件工厂（泛型，不依赖 langchain）
+ */
+export type PluginMiddlewareFactory<T = unknown> = (
+  config: Record<string, unknown>,
+) => T | Promise<T>;
+
+/**
+ * Plugin 基类接口
+ *
+ * 一个对象 = 一个完整的插件定义。
+ * meta + connection + middleware 全在一个类里内聚。
+ *
+ * @example
+ * ```ts
+ * const erpPlugin: Plugin = {
+ *   meta: { type: "erp", name: "ERP", description: "SAP B1" },
+ *   connection: {
+ *     fields: [{ key: "baseUrl", type: "string", title: "SAP URL" }],
+ *     test: async (config) => ({ ok: true, message: "ok" }),
+ *   },
+ *   middleware: (config) => createMiddleware({ ... }),
+ * };
+ * ```
+ */
+export interface Plugin {
+  /** 插件元数据 */
+  meta: PluginMeta;
+  /** 连接能力（可选，没有则不暴露连接管理） */
+  connection?: PluginConnection;
+  /** 中间件工厂（可选，没有则不注册任何工具） */
+  middleware?: PluginMiddlewareFactory;
+}

package/src/SandboxResourceProtocol.ts

@@ -18,7 +18,7 @@ export interface ResourceResolver {
 }
 
 /** Visibility level for resource shares. */
-export type ShareVisibility = "public" | "password";
+export type ShareVisibility = "public" | "password" | "internal";
 
 /** Persisted record of a resource share within a project. */
 export interface ShareRecord {

package/src/VectorStoreProviderProtocol.ts

@@ -0,0 +1,59 @@
+/**
+ * VectorStoreProviderProtocol
+ *
+ * Provides a pluggable factory for creating VectorStore instances.
+ * Each provider key maps to a backend (memory, pgvector, chroma, etc.).
+ * Follows the same singleton registry pattern as EmbeddingsLatticeManager.
+ */
+
+import { VectorStore } from "@langchain/core/vectorstores";
+import type { DocumentInterface } from "@langchain/core/documents";
+
+/**
+ * Parameters for creating a VectorStore instance.
+ */
+export interface VectorStoreCreateParams {
+  /** Table/collection name for the vector store */
+  tableName: string;
+  /** Embedding model key to use for embedding operations */
+  embeddingKey: string;
+  /** Provider-specific configuration */
+  config?: Record<string, unknown>;
+}
+
+/**
+ * VectorStoreProvider interface.
+ * Implementations create VectorStore instances for a specific backend.
+ */
+export interface VectorStoreProvider {
+  /**
+   * Create a new VectorStore instance.
+   * @param params Creation parameters including table name and embedding key
+   * @returns A LangChain VectorStore instance
+   */
+  create(params: VectorStoreCreateParams): Promise<VectorStore>;
+
+  /**
+   * Dispose a VectorStore instance (optional cleanup).
+   * @param name The table/collection name
+   */
+  dispose?(name: string): Promise<void>;
+
+  /**
+   * Get the number of entries in a vector store (optional).
+   * @param tableName The table/collection name
+   */
+  getEntryCount?(tableName: string): Promise<number>;
+
+  /**
+   * List all entries in a vector store (optional).
+   * @param tableName The table/collection name
+   */
+  listEntries?(tableName: string): Promise<DocumentInterface[]>;
+
+  /**
+   * Drop/delete the underlying storage for a vector store (optional).
+   * @param tableName The table/collection name
+   */
+  dropTable?(tableName: string): Promise<void>;
+}

package/src/index.ts

@@ -24,6 +24,7 @@ export * from "./McpLatticeProtocol";
 export * from "./WorkspaceStoreProtocol";
 export * from "./TenantStoreProtocol";
 export * from "./DatabaseConfigStoreProtocol";
+export * from "./ConnectionStoreProtocol";
 export * from "./ChannelInstallationStoreProtocol";
 export * from "./MetricsServerConfigStoreProtocol";
 export * from "./McpServerConfigStoreProtocol";
@@ -31,6 +32,8 @@ export * from "./UserStoreProtocol";
 export * from "./UserTenantLinkProtocol";
 export * from "./WorkflowTrackingStoreProtocol";
 export * from "./BindingProtocol";
+export * from "./CollectionStoreProtocol";
+export * from "./VectorStoreProviderProtocol";
 export * from "./MenuProtocol";
 export * from "./EvalStoreProtocol";
 export * from "./TaskStoreProtocol";
@@ -47,5 +50,18 @@ export * from "./InternalDSL";
 
 export * from "./SandboxResourceProtocol";
 
+// Plugin system
+export type {
+  Plugin,
+  PluginMeta,
+  PluginMetaOutput,
+  PluginConnection,
+  PluginConnectionFieldSchema,
+  PluginConnectionTestResult,
+  PluginDiscoveredResource,
+  PluginToolMeta,
+  PluginMiddlewareFactory,
+} from "./PluginProtocol";
+
 // 导出通用类型
 export * from "./types";