@axiom-lattice/protocols 2.1.41 → 2.1.42

package/src/WorkflowDSL.ts

@@ -0,0 +1,347 @@
+/**
+ * Workflow DSL
+ *
+ * Concise workflow definition language. A step's `id` is its node id, state
+ * output key, and template reference name. The engine auto-generates nodes,
+ * edges, and state fields.
+ *
+ * Template syntax:
+ *   {{input}}    — initial user input
+ *   {{id}}       — output of step with given id
+ *   {{item}}     — current element in map iterations
+ */
+
+// ─── Top-level ─────────────────────────────────────────────────────────────
+
+export interface WorkflowDSL {
+  name: string;
+  steps: WorkflowStep[];
+}
+
+export type WorkflowStep =
+  | AgentStep
+  | ConditionStep
+  | HumanStep
+  | MapStep
+  | ParallelStep
+  | EndStep;
+
+// ─── Steps ─────────────────────────────────────────────────────────────────
+
+/** invoke the workflow's built-in agent. type defaults to "agent". */
+export interface AgentStep {
+  id?: string;
+  type?: "agent";
+  name?: string;
+  prompt: string;
+  schema?: Record<string, unknown>;
+}
+
+/** branch on state field or expression. */
+export interface ConditionStep {
+  id?: string;
+  type: "condition";
+  if: string;
+  then?: WorkflowStep[] | WorkflowStep;
+  else?: WorkflowStep[] | WorkflowStep;
+  branches?: Record<string, WorkflowStep[] | WorkflowStep>;
+}
+
+/** pause for human input. */
+export interface HumanStep {
+  id?: string;
+  type: "human";
+  prompt: string;
+  title?: string;
+  schema?: Record<string, unknown>;
+}
+
+/** iterate over an array, optionally reducing. */
+export interface MapStep {
+  id: string;
+  type: "map";
+  source: string;      // id of the step that produces the array
+  each: AgentStep;      // applied to every element
+  reduce?: AgentStep;   // optional aggregation
+  batch?: number;       // default 50
+  concurrency?: number; // default 5
+}
+
+/** run steps in parallel, then rejoin. */
+export interface ParallelStep {
+  id?: string;
+  type: "parallel";
+  steps: WorkflowStep[];
+}
+
+/** terminal state. */
+export interface EndStep {
+  type: "end";
+  status?: "success" | "failed";  // default "success"
+}
+
+// ─── Examples ─────────────────────────────────────────────────────────────
+
+/**
+ * Example 1 — Linear: agent → agent → end
+ *
+ * When `id` is omitted, one is auto-generated. Template uses {{id}} to
+ * reference previous step outputs.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "知识问答",
+ *   "steps": [
+ *     { "id": "researcher", "prompt": "查询: {{input}}" },
+ *     { "id": "writer", "prompt": "根据 {{researcher}} 写回答" },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 2 — Structured output with schema
+ *
+ * `schema: true` tells the agent to return JSON. The model infers the shape
+ * from the prompt description. For strict validation, pass a JSON Schema object.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "订单提取",
+ *   "steps": [
+ *     {
+ *       "id": "order",
+ *       "prompt": "提取订单: {items: [{name, qty, price}], total, urgent}",
+ *       "schema": true
+ *     },
+ *     {
+ *       "type": "condition", "if": "order.urgent",
+ *       "then": { "id": "fast", "prompt": "加急: {{order}}" },
+ *       "else": { "id": "normal", "prompt": "常规: {{order}}" }
+ *     },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 3 — Custom id for semantic naming
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "翻译",
+ *   "steps": [
+ *     { "id": "原文", "prompt": "翻译: {{input}}" },
+ *     { "id": "校对", "prompt": "校对: {{原文}}" },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 4 — Condition (binary if/else)
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "客服分流",
+ *   "steps": [
+ *     { "id": "intent", "prompt": "分类: {{input}}" },
+ *     {
+ *       "type": "condition", "if": "intent",
+ *       "then": { "id": "support", "prompt": "支持: {{input}}" },
+ *       "else": { "id": "sales", "prompt": "销售: {{input}}" }
+ *     },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 4b — Switch (multi-branch condition)
+ *
+ * When the agent's output is a fixed set of categories, use `branches`
+ * instead of nested if/else. The `if` expression evaluates to the state field
+ * value, which is matched against the branch keys. `default` is a catch-all.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "客服分流",
+ *   "steps": [
+ *     { "id": "intent", "prompt": "分类意图: {{input}}" },
+ *     {
+ *       "type": "condition", "if": "intent",
+ *       "branches": {
+ *         "support": { "id": "support", "prompt": "技术支持: {{input}}" },
+ *         "sales":   { "id": "sales",   "prompt": "销售咨询: {{input}}" },
+ *         "billing": { "id": "billing", "prompt": "账单查询: {{input}}" },
+ *         "default": { "id": "fallback", "prompt": "转接人工: {{input}}" }
+ *       }
+ *     },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 5 — Condition with expression
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "评分判定",
+ *   "steps": [
+ *     { "id": "score", "prompt": "打分: {{input}}" },
+ *     {
+ *       "type": "condition", "if": "score >= 60",
+ *       "then": [
+ *         { "id": "congrats", "prompt": "恭喜通过" },
+ *         { "type": "end" }
+ *       ],
+ *       "else": { "type": "end", "status": "failed" }
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 6 — Human feedback (agent + clarify middleware)
+ *
+ * The human step invokes an agent with ask_user_to_clarify middleware.
+ * The agent decides what questions to ask based on the prompt. A schema
+ * constrains the structured output stored under the step's id.
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "审批流程",
+ *   "steps": [
+ *     { "id": "draft", "prompt": "起草: {{input}}" },
+ *     { "id": "review", "type": "human",
+ *       "title": "审批",
+ *       "prompt": "你是审批员。审核以下方案并请用户选择通过或驳回，附上意见。\\n\\n方案:\\n{{draft}}",
+ *       "schema": { "type": "object", "properties": { "approved": { "type": "boolean" }, "comments": { "type": "string" } } } },
+ *     {
+ *       "type": "condition", "if": "review.approved",
+ *       "then": { "prompt": "发布: {{draft}}" },
+ *       "else": { "prompt": "修改: {{review.comments}}" }
+ *     },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 7 — Parallel (fixed fan-out)
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "尽职调查",
+ *   "steps": [
+ *     { "id": "info", "prompt": "收集: {{input}}" },
+ *     {
+ *       "type": "parallel", "steps": [
+ *         { "id": "legal",   "prompt": "法务: {{info}}" },
+ *         { "id": "finance", "prompt": "财务: {{info}}" },
+ *         { "id": "market",  "prompt": "市场: {{info}}" }
+ *       ]
+ *     },
+ *     { "id": "report", "prompt": "汇总: {{legal}} {{finance}} {{market}}" },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 8 — Map (dynamic iteration)
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "批量审核",
+ *   "steps": [
+ *     { "id": "items", "prompt": "提取待审核项: {{input}}" },
+ *     {
+ *       "id": "results", "type": "map", "source": "items",
+ *       "each": { "id": "auditor", "prompt": "审核: {{item}}" },
+ *       "batch": 10, "concurrency": 3
+ *     },
+ *     { "id": "summary", "prompt": "总结: {{results}}" },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 9 — Map + reduce
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "舆情分析",
+ *   "steps": [
+ *     { "id": "posts", "prompt": "抓取: {{input}}" },
+ *     {
+ *       "id": "sentiments", "type": "map", "source": "posts",
+ *       "each": { "id": "sentiment", "prompt": "分析情感: {{item}}" },
+ *       "reduce": { "id": "aggregator", "prompt": "汇总: {{sentiments}}" }
+ *     },
+ *     { "id": "report", "prompt": "报告: {{aggregator}}" },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */
+
+/**
+ * Example 10 — Full pipeline (all types)
+ *
+ * @example
+ * ```json
+ * {
+ *   "name": "智能客服",
+ *   "steps": [
+ *     { "id": "intent", "prompt": "分类: {{input}}" },
+ *     {
+ *       "type": "condition", "if": "intent",
+ *       "then": [
+ *         { "id": "kb", "prompt": "查知识库: {{input}}" },
+ *         {
+ *           "type": "condition", "if": "kb.confidence > 0.8",
+ *           "then": { "id": "reply", "prompt": "直接回复: {{kb}}" },
+ *           "else": [
+ *             { "id": "pre_merge", "prompt": "准备合并" },
+ *             { "type": "parallel", "steps": [
+ *               { "id": "faq",  "prompt": "FAQ: {{input}}" },
+ *               { "id": "hist", "prompt": "历史: {{input}}" }
+ *             ]},
+ *             { "id": "merged", "prompt": "合并: FAQ={{faq}} 历史={{hist}}" },
+ *             { "id": "review", "type": "human",
+ *               "title": "转人工", "prompt": "请处理:\\n{{merged}}",
+ *               "schema": { "type": "object", "properties": { "action": { "type": "string" } } }
+ *             },
+ *             { "id": "response", "prompt": "回复: {{review}}" }
+ *           ]
+ *         }
+ *       ],
+ *       "else": { "id": "clarify", "prompt": "请用户澄清" }
+ *     },
+ *     { "type": "end" }
+ *   ]
+ * }
+ * ```
+ */

package/src/WorkflowTrackingStoreProtocol.ts

@@ -11,7 +11,7 @@ export interface TopologyEdge {
   purpose: string;
 }
 
-export type WorkflowRunStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+export type WorkflowRunStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
 
 export interface WorkflowRun {
   id: string;
@@ -25,12 +25,12 @@ export interface WorkflowRun {
   errorMessage?: string;
   metadata?: Record<string, any>;
   startedAt: Date;
-  completedAt?: Date;
+  completedAt?: Date | null;
   createdAt: Date;
   updatedAt: Date;
 }
 
-export type StepType = 'task_delegation' | 'tool_call' | 'human_in_loop' | 'topology_transition';
+export type StepType = 'task_delegation' | 'tool_call' | 'human_in_loop' | 'topology_transition' | 'agent' | 'human_feedback' | 'map' | 'input' | 'terminal';
 export type StepStatus = 'running' | 'completed' | 'failed' | 'interrupted';
 
 export interface RunStep {
@@ -47,7 +47,7 @@ export interface RunStep {
   status: StepStatus;
   errorMessage?: string;
   startedAt: Date;
-  completedAt?: Date;
+  completedAt?: Date | null;
   durationMs?: number;
   createdAt: Date;
   updatedAt: Date;
@@ -65,7 +65,7 @@ export interface UpdateWorkflowRunRequest {
   status?: WorkflowRunStatus;
   completedEdges?: number;
   errorMessage?: string;
-  completedAt?: Date;
+  completedAt?: Date | null;
   metadata?: Record<string, any>;
 }
 
@@ -84,7 +84,7 @@ export interface UpdateRunStepRequest {
   status?: StepStatus;
   output?: Record<string, any>;
   errorMessage?: string;
-  completedAt?: Date;
+  completedAt?: Date | null;
   durationMs?: number;
 }
 
@@ -100,6 +100,8 @@ export interface WorkflowTrackingStore {
 
   // RunStep CRUD
   createRunStep(request: CreateRunStepRequest): Promise<RunStep>;
+  /** Idempotent create — uses (runId, stepType, stepName) as unique key. Returns existing step if one already exists. */
+  upsertRunStep(request: CreateRunStepRequest): Promise<RunStep>;
   updateRunStep(runId: string, stepId: string, updates: UpdateRunStepRequest): Promise<RunStep | null>;
   getRunSteps(runId: string): Promise<RunStep[]>;
   getRunStepsByType(runId: string, stepType: StepType): Promise<RunStep[]>;

package/src/index.ts

@@ -37,5 +37,11 @@ export * from "./ChannelAdapterProtocol";
 export * from "./A2AProtocol";
 export * from "./A2AApiKeyStoreProtocol";
 
+// Workflow DSL (concise, public API)
+export * from "./WorkflowDSL";
+
+// Internal DSL (expanded IR, internal use)
+export * from "./InternalDSL";
+
 // 导出通用类型
 export * from "./types";