@axiom-lattice/protocols 2.1.41 → 2.1.43

package/src/AgentLatticeProtocol.ts

@@ -5,7 +5,7 @@
  */
 
 import { CompiledStateGraph } from "@langchain/langgraph";
-import z, { ZodObject, ZodSchema } from "zod";
+import { ZodObject } from "zod";
 import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
 
 /**
@@ -18,6 +18,8 @@ export enum AgentType {
   PROCESSING = "processing",
   /** Remote A2A agent — delegates to an external A2A-compatible server */
   A2A_REMOTE = "a2a_remote",
+  /** Workflow agent — compiled from YAML DSL into a LangGraph StateGraph */
+  WORKFLOW = "workflow",
 }
 
 /**
@@ -54,6 +56,21 @@ interface BaseAgentConfig {
   runConfig?: AgentRunConfig;
   skillCategories?: string[];
   middleware?: AgentMiddlewareConfig[];
+  /**
+   * Structured output response format for the agent.
+   * Supports Zod schema (z.object({...})), JSON Schema object ({ type: "object", properties: {...} }),
+   * providerStrategy(), toolStrategy(), and other formats accepted by the underlying model.
+   *
+   * @example
+   * ```ts
+   * // Zod schema
+   * responseFormat: z.object({ name: z.string(), age: z.number() })
+   *
+   * // JSON Schema
+   * responseFormat: { type: "object", properties: { name: { type: "string" } }, required: ["name"] }
+   * ```
+   */
+  responseFormat?: any;
 }
 
 export type AvailableModule = "filesystem" | "code_eval" | "browser";
@@ -89,7 +106,7 @@ export interface SchedulerMiddlewareConfig {
   defaultMaxRetries?: number;
 }
 
-export type MiddlewareType = "filesystem" | "code_eval" | "browser" | "sql" | "skill" | "http" | "custom" | "metrics" | "ask_user_to_clarify" | "widget" | "claw" | "date" | "scheduler" | "topology";
+export type MiddlewareType = "filesystem" | "code_eval" | "browser" | "sql" | "skill" | "http" | "custom" | "metrics" | "ask_user_to_clarify" | "widget" | "claw" | "date" | "scheduler" | "topology" | "task";
 
 export interface AgentMiddlewareConfig {
   id: string;
@@ -235,6 +252,21 @@ export interface A2ARemoteAgentConfig extends BaseAgentConfig {
   tools?: string[];
 }
 
+/**
+ * WORKFLOW agent configuration — compiled from YAML workflow DSL into a LangGraph StateGraph.
+ *
+ * The workflow field contains the full DSL definition (nodes, edges, state).
+ * The WorkflowAgentGraphBuilder compiles this into a multi-node LangGraph
+ * where each node invokes a registered sub-agent by ref.
+ */
+export interface WorkflowAgentConfig extends BaseAgentConfig {
+  type: AgentType.WORKFLOW;
+  /** The YAML workflow DSL definition string (needs+if format) */
+  workflowYaml: string;
+  /** Optional tool keys */
+  tools?: string[];
+}
+
 /**
  * Type guard to check if config is A2ARemoteAgentConfig
  */
@@ -244,6 +276,15 @@ export function isA2ARemoteAgentConfig(
   return config.type === AgentType.A2A_REMOTE;
 }
 
+/**
+ * Type guard to check if config is WorkflowAgentConfig
+ */
+export function isWorkflowAgentConfig(
+  config: AgentConfig
+): config is WorkflowAgentConfig {
+  return config.type === AgentType.WORKFLOW;
+}
+
 /**
  * Agent configuration union type
  * Different agent types have different configuration options
@@ -254,6 +295,7 @@ export type AgentConfig =
   | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
+  | WorkflowAgentConfig
 
 /**
  * Agent configuration with tools property
@@ -264,12 +306,13 @@ export type AgentConfigWithTools =
   | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
+  | WorkflowAgentConfig
 
 /**
  * Type guard to check if config has tools property
  */
 export function hasTools(config: AgentConfig): config is AgentConfigWithTools {
-  return true
+  return true;
 }
 
 /**

package/src/AssistantStoreProtocol.ts

@@ -29,6 +29,12 @@ export interface Assistant {
    */
   description?: string;
 
+  /**
+   * Owner user ID — when set, this assistant is a personal assistant
+   * owned by the given user. NULL for shared/tenant agents.
+   */
+  ownerUserId?: string;
+
   /**
    * Graph definition for the assistant
    */
@@ -59,6 +65,11 @@ export interface CreateAssistantRequest {
    */
   description?: string;
 
+  /**
+   * Owner user ID for personal assistants
+   */
+  ownerUserId?: string;
+
   /**
    * Graph definition for the assistant
    */
@@ -122,4 +133,12 @@ export interface AssistantStore {
    * @returns true if assistant exists, false otherwise
    */
   hasAssistant(tenantId: string, id: string): Promise<boolean>;
+
+  /**
+   * Get personal assistant by owner user ID
+   * @param tenantId Tenant identifier
+   * @param userId Owner user identifier
+   * @returns Assistant if found, null otherwise
+   */
+  getByOwner(tenantId: string, userId: string): Promise<Assistant | null>;
 }

package/src/ChannelAdapterProtocol.ts

@@ -76,4 +76,24 @@ export interface ChannelAdapter<TConfig = unknown> {
     message: OutboundMessage,
     installation: ChannelInstallation,
   ): Promise<void>;
+  /**
+   * 可选：Channel 自定义 thread ID 生成策略。
+   * 如果提供，MessageRouter 会优先使用此方法决定 thread ID，
+   * 替代默认的 binding.threadMode（fixed / per_conversation）。
+   *
+   * 返回的 thread ID 会持久化到 binding 中，以便后续消息复用。
+   */
+  resolveThreadId?(
+    message: InboundMessage,
+    binding: unknown,
+  ): Promise<string> | string;
+  /**
+   * 可选：建立持久连接并开始接收事件。
+   * adapter 自己负责连接管理、事件处理、消息分发。
+   * `deps` 由调用方传入，通常包含 MessageRouter。
+   */
+  connect?(
+    installation: ChannelInstallation<TConfig>,
+    deps?: unknown,
+  ): Promise<void>;
 }

package/src/ChannelInstallationStoreProtocol.ts

@@ -48,6 +48,14 @@ export interface ChannelInstallationStore {
     channel?: ChannelInstallationType,
   ): Promise<ChannelInstallation[]>;
 
+  /**
+   * 返回所有租户下指定 channel 类型的安装（跨租户查询）。
+   * 用于 connectAllChannels 等不需要按租户过滤的场景。
+   */
+  getAllInstallations(
+    channel?: ChannelInstallationType,
+  ): Promise<ChannelInstallation[]>;
+
   createInstallation(
     tenantId: string,
     installationId: string,

package/src/InternalDSL.ts

@@ -0,0 +1,117 @@
+/**
+ * Internal DSL — expanded intermediate representation.
+ *
+ * Generated by parseYaml() from the YAML workflow DSL. Consumed by compileWorkflow.
+ * Not part of the public API.
+ */
+
+// ─── Top-level ─────────────────────────────────────────────────────────────
+
+export interface InternalDSL {
+  version: "1.0";
+  name: string;
+  description?: string;
+  state?: InternalState;
+  nodes: InternalNode[];
+  edges: InternalEdge[];
+}
+
+// ─── State ─────────────────────────────────────────────────────────────────
+
+export interface InternalState {
+  fields: Record<string, InternalStateField>;
+}
+
+export interface InternalStateField {
+  type: "string" | "number" | "boolean" | "object" | "array";
+  default?: unknown;
+  reducer?: "replace" | "append" | "merge";
+}
+
+// ─── Nodes ─────────────────────────────────────────────────────────────────
+
+export type InternalNode =
+  | InternalAgentNode
+  | InternalMapNode
+  | InternalTerminalNode
+  | InternalInputNode;
+
+export interface InternalBaseNode {
+  id: string;
+  type: "agent" | "map" | "terminal" | "input";
+  name: string;
+  description?: string;
+  config?: InternalNodeConfig;
+  input?: InternalInput;
+  output?: InternalOutput;
+}
+
+export interface InternalAgentNode extends InternalBaseNode {
+  type: "agent";
+  ref?: string;
+  /** When true, the agent loads ask_user_to_clarify middleware. */
+  ask?: boolean;
+  /** Runtime condition expression evaluated as JS. Step skipped when false. */
+  condition?: string;
+  /** Parallel group ID — children in the same group run concurrently. */
+  parallelGroup?: string;
+}
+
+export interface InternalMapNode extends InternalBaseNode {
+  type: "map";
+  source: string;
+  itemKey?: string;
+  /** Runtime condition expression evaluated as JS. Map skipped when false. */
+  condition?: string;
+  config?: InternalNodeConfig & {
+    batchSize?: number;
+    maxConcurrency?: number;
+    innerConcurrency?: number;
+  };
+  node: {
+    type: "agent";
+    ref?: string;
+    input?: InternalInput;
+    schema?: Record<string, unknown>;
+  };
+  reduce?: {
+    ref?: string;
+    input?: InternalInput;
+    schema?: Record<string, unknown>;
+  };
+}
+
+export interface InternalTerminalNode extends InternalBaseNode {
+  type: "terminal";
+  status: "success" | "failed" | "cancelled";
+}
+
+export interface InternalInputNode extends InternalBaseNode {
+  type: "input";
+  /** output key for the user message (typically "input") */
+  output: InternalOutput;
+}
+
+// ─── Input / Output ────────────────────────────────────────────────────────
+
+export type InternalInput = { template: string };
+
+export interface InternalOutput {
+  schema?: Record<string, unknown>;
+  key?: string;
+}
+
+// ─── Edges ─────────────────────────────────────────────────────────────────
+
+export interface InternalEdge {
+  from: string;
+  to?: string | string[];
+}
+
+// ─── Node Config ───────────────────────────────────────────────────────────
+
+export interface InternalNodeConfig {
+  timeout?: number;
+  maxRetries?: number;
+  retryOn?: string[];
+}

package/src/MenuProtocol.ts

@@ -0,0 +1,70 @@
+/**
+ * MenuProtocol
+ *
+ * Defines types and registry interface for per-tenant customizable menu items.
+ * Menu items are merged with built-in defaults at the React SDK layer.
+ */
+
+export type MenuTarget = 'sidebar' | 'workspace';
+
+export type MenuContentType = 'agent' | 'html' | 'custom';
+
+export interface AgentMenuConfig {
+  agentId: string;
+  workspaceId?: string;
+  projectId?: string;
+}
+
+export interface HtmlMenuConfig {
+  url: string;
+  params?: Record<string, string>;
+  title?: string;
+}
+
+export interface CustomMenuConfig {
+  componentKey: string;
+}
+
+export type MenuContentConfig = AgentMenuConfig | HtmlMenuConfig | CustomMenuConfig;
+
+export interface MenuItem {
+  id: string;
+  tenantId: string;
+  menuTarget: MenuTarget;
+  group?: string;
+  name: string;
+  icon?: string;
+  sortOrder: number;
+  contentType: MenuContentType;
+  contentConfig: MenuContentConfig;
+  enabled: boolean;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateMenuItemInput {
+  menuTarget: MenuTarget;
+  group?: string;
+  name: string;
+  icon?: string;
+  sortOrder?: number;
+  contentType: MenuContentType;
+  contentConfig: MenuContentConfig;
+}
+
+export interface UpdateMenuItemInput {
+  group?: string;
+  name?: string;
+  icon?: string;
+  sortOrder?: number;
+  contentConfig?: MenuContentConfig;
+  enabled?: boolean;
+}
+
+export interface MenuRegistry {
+  list(params: { tenantId: string; menuTarget?: MenuTarget }): Promise<MenuItem[]>;
+  getById(id: string): Promise<MenuItem | null>;
+  create(input: CreateMenuItemInput & { tenantId: string }): Promise<MenuItem>;
+  update(id: string, patch: UpdateMenuItemInput): Promise<MenuItem>;
+  delete(id: string): Promise<void>;
+}

package/src/MessageProtocol.ts

@@ -3,7 +3,7 @@
  *
  */
 
-import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
+
 
 /**
  * Base message interface

package/src/SkillStoreProtocol.ts

@@ -5,7 +5,7 @@
  * Provides standardized interfaces for skill management across all implementations
  */
 
-import { SkillConfig } from "./SkillLatticeProtocol";
+
 
 /**
  * Skill type definition

package/src/TaskStoreProtocol.ts

@@ -0,0 +1,306 @@
+/**
+ * TaskStoreProtocol
+ *
+ * Task store protocol definitions for the Axiom Lattice framework.
+ * Provides standardized interfaces for task management across all implementations.
+ */
+
+/**
+ * TaskItem — unified task model for users and agents.
+ */
+export interface TaskItem {
+  /**
+   * Task identifier
+   */
+  id: string;
+
+  /**
+   * Tenant identifier
+   */
+  tenantId: string;
+
+  /**
+   * Owner type — either a user or an agent
+   */
+  ownerType: 'user' | 'agent';
+
+  /**
+   * Owner identifier
+   */
+  ownerId: string;
+
+  /**
+   * Task title
+   */
+  title: string;
+
+  /**
+   * Task description
+   */
+  description?: string;
+
+  /**
+   * Task status
+   */
+  status: 'pending' | 'in_progress' | 'completed' | 'cancelled';
+
+  /**
+   * Task priority level
+   */
+  priority: 'low' | 'medium' | 'high';
+
+  /**
+   * Optional due date as ISO string
+   */
+  dueDate?: string;
+
+  /**
+   * Arbitrary metadata key-value pairs
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Parent task ID for hierarchical tasks
+   */
+  parentId?: string;
+
+  /**
+   * Source system identifier for external task tracking
+   */
+  sourceId?: string;
+
+  /**
+   * Additional contextual data
+   */
+  context?: Record<string, unknown>;
+
+  /**
+   * Task creation timestamp
+   */
+  createdAt: Date;
+
+  /**
+   * Task last update timestamp
+   */
+  updatedAt: Date;
+}
+
+/**
+ * Create task request type
+ */
+export interface CreateTaskRequest {
+  /**
+   * Task title
+   */
+  title: string;
+
+  /**
+   * Task description
+   */
+  description?: string;
+
+  /**
+   * Task status — defaults to 'pending' if not provided
+   */
+  status?: 'pending' | 'in_progress' | 'completed' | 'cancelled';
+
+  /**
+   * Task priority level — defaults to 'medium' if not provided
+   */
+  priority?: 'low' | 'medium' | 'high';
+
+  /**
+   * Optional due date as ISO string
+   */
+  dueDate?: string;
+
+  /**
+   * Arbitrary metadata key-value pairs
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Parent task ID for hierarchical tasks
+   */
+  parentId?: string;
+
+  /**
+   * Source system identifier for external task tracking
+   */
+  sourceId?: string;
+
+  /**
+   * Additional contextual data
+   */
+  context?: Record<string, unknown>;
+
+  /**
+   * Owner type — defaults based on context if not provided
+   */
+  ownerType?: 'user' | 'agent';
+
+  /**
+   * Owner identifier — defaults based on context if not provided
+   */
+  ownerId?: string;
+}
+
+/**
+ * Update task request type
+ */
+export interface UpdateTaskRequest {
+  /**
+   * Task title
+   */
+  title?: string;
+
+  /**
+   * Task description
+   */
+  description?: string;
+
+  /**
+   * Task status
+   */
+  status?: 'pending' | 'in_progress' | 'completed' | 'cancelled';
+
+  /**
+   * Task priority level
+   */
+  priority?: 'low' | 'medium' | 'high';
+
+  /**
+   * Optional due date as ISO string
+   */
+  dueDate?: string;
+
+  /**
+   * Arbitrary metadata key-value pairs
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Parent task ID for hierarchical tasks
+   */
+  parentId?: string;
+
+  /**
+   * Source system identifier for external task tracking
+   */
+  sourceId?: string;
+
+  /**
+   * Additional contextual data
+   */
+  context?: Record<string, unknown>;
+
+  /**
+   * Owner type
+   */
+  ownerType?: 'user' | 'agent';
+
+  /**
+   * Owner identifier
+   */
+  ownerId?: string;
+}
+
+/**
+ * Task list filter criteria
+ */
+export interface TaskListFilter {
+  /**
+   * Tenant identifier (required)
+   */
+  tenantId: string;
+
+  /**
+   * Filter by owner type
+   */
+  ownerType?: 'user' | 'agent';
+
+  /**
+   * Filter by owner ID
+   */
+  ownerId?: string;
+
+  /**
+   * Filter by task status
+   */
+  status?: string;
+
+  /**
+   * Filter by priority level
+   */
+  priority?: string;
+
+  /**
+   * Filter by parent task ID
+   */
+  parentId?: string;
+
+  /**
+   * Filter by source system ID
+   */
+  sourceId?: string;
+
+  /**
+   * Filter by metadata key-value pairs
+   */
+  metadata?: Record<string, unknown>;
+
+  /**
+   * Maximum number of results to return
+   */
+  limit?: number;
+
+  /**
+   * Number of results to skip for pagination
+   */
+  offset?: number;
+}
+
+/**
+ * TaskStore interface
+ * Provides CRUD operations for task data
+ */
+export interface TaskStore {
+  /**
+   * Create a new task
+   * @param params Task creation data including tenant, ownerType ('user' | 'agent'), and owner info
+   * @returns Created task
+   */
+  create(params: CreateTaskRequest & { tenantId: string; ownerType: string; ownerId: string }): Promise<TaskItem>;
+
+  /**
+   * Get a task by ID
+   * @param tenantId Tenant identifier
+   * @param id Task identifier
+   * @returns Task if found, null otherwise
+   */
+  getById(tenantId: string, id: string): Promise<TaskItem | null>;
+
+  /**
+   * List tasks matching the given filter
+   * @param filter Filter criteria
+   * @returns Array of matching tasks
+   */
+  list(filter: TaskListFilter): Promise<TaskItem[]>;
+
+  /**
+   * Update an existing task
+   * @param tenantId Tenant identifier
+   * @param id Task identifier
+   * @param updates Partial task data to update
+   * @returns Updated task if found, null otherwise
+   */
+  update(tenantId: string, id: string, updates: UpdateTaskRequest): Promise<TaskItem | null>;
+
+  /**
+   * Delete a task by ID
+   * @param tenantId Tenant identifier
+   * @param id Task identifier
+   * @returns true if deleted, false otherwise
+   */
+  delete(tenantId: string, id: string): Promise<boolean>;
+}