@axiom-lattice/protocols 2.1.42 → 2.1.43

package/src/WorkflowDSL.ts

@@ -1,347 +1,72 @@
 /**
- * Workflow DSL
+ * YAML Workflow DSL — linear model with parallel blocks
  *
- * 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.
+ * Steps execute top-to-bottom. `parallel:` blocks declare concurrency.
+ * `if` on any step skips it. `map` iterates over arrays.
+ * No `needs` — execution order = reading order.
  *
  * Template syntax:
- *   {{input}}    — initial user input
- *   {{id}}       — output of step with given id
- *   {{item}}     — current element in map iterations
+ *   {{input}}        — initial user input
+ *   {{label}}        — output of step with given label
+ *   {{label.field}}  — nested field access on structured output
+ *   {{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";
+export interface YamlWorkflow {
+  /** Optional workflow name — defaults to "workflow" if omitted. */
   name?: string;
-  prompt: string;
-  schema?: Record<string, unknown>;
+  steps: YamlTopLevelStep[];
 }
 
-/** 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>;
-}
+export type YamlTopLevelStep = YamlAgentStep | YamlParallelBlock | YamlMapStep;
 
-/** pause for human input. */
-export interface HumanStep {
-  id?: string;
-  type: "human";
+// ─── Agent step ────────────────────────────────────────────────────────────
+
+export interface YamlAgentStep {
+  /** Unique label serving as state key and template reference. */
+  label: string;
+  /** JS expression evaluated as boolean. Step skipped when falsy. */
+  if?: string;
+  /** Agent instruction with {{template}} references. */
   prompt: string;
-  title?: string;
-  schema?: Record<string, unknown>;
+  /** Shorthand output schema: { field: "string" | "number" | "boolean" } */
+  output?: Record<string, unknown>;
+  /** When true, inject ask_user_to_clarify middleware. */
+  ask?: boolean;
 }
 
-/** 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
-}
+// ─── Parallel block ────────────────────────────────────────────────────────
 
-/** run steps in parallel, then rejoin. */
-export interface ParallelStep {
-  id?: string;
-  type: "parallel";
-  steps: WorkflowStep[];
+export interface YamlParallelBlock {
+  parallel: YamlAgentStep[];
+  /** JS expression evaluated as boolean. Entire block skipped when falsy. */
+  if?: string;
+  /** Shorthand output schema for aggregated results. */
+  output?: Record<string, unknown>;
 }
 
-/** terminal state. */
-export interface EndStep {
-  type: "end";
-  status?: "success" | "failed";  // default "success"
+// ─── Map step ──────────────────────────────────────────────────────────────
+
+export interface YamlMapStep {
+  map: {
+    /** Path to source array (e.g. "extract.items"). */
+    source: string;
+    /** Step label for referencing in templates (e.g. {{label}}). */
+    label: string;
+    /** JS expression evaluated as boolean. Entire map skipped when falsy. */
+    if?: string;
+    /** Agent applied to each element. Use {{item}} for current element. */
+    each: {
+      prompt: string;
+      output?: Record<string, unknown>;
+    };
+    /** Shorthand output schema for the aggregated results. */
+    output?: Record<string, unknown>;
+    /** Items per batch (default 50). */
+    batch?: number;
+    /** Max parallel items (default 5). */
+    concurrency?: number;
+  };
 }
-
-// ─── 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

@@ -31,7 +31,7 @@ export interface WorkflowRun {
 }
 
 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 type StepStatus = 'running' | 'completed' | 'failed' | 'interrupted' | 'skipped';
 
 export interface RunStep {
   id: string;
@@ -39,6 +39,8 @@ export interface RunStep {
   tenantId: string;
   stepType: StepType;
   stepName: string;
+  /** Sub-agent thread_id for agent/map steps. null for input/terminal. */
+  threadId?: string | null;
   edgeFrom?: string;
   edgeTo?: string;
   edgePurpose?: string;
@@ -74,6 +76,7 @@ export interface CreateRunStepRequest {
   tenantId: string;
   stepType: StepType;
   stepName: string;
+  threadId?: string | null;
   edgeFrom?: string;
   edgeTo?: string;
   edgePurpose?: string;

package/src/index.ts

@@ -31,7 +31,9 @@ export * from "./UserStoreProtocol";
 export * from "./UserTenantLinkProtocol";
 export * from "./WorkflowTrackingStoreProtocol";
 export * from "./BindingProtocol";
+export * from "./MenuProtocol";
 export * from "./EvalStoreProtocol";
+export * from "./TaskStoreProtocol";
 
 export * from "./ChannelAdapterProtocol";
 export * from "./A2AProtocol";