@ai-setting/roy-agent-core 1.7.50 → 1.7.52

package/dist/shared/@ai-setting/{roy-agent-core-cg9f4zch.js → roy-agent-core-gdsqp6j8.js}

@@ -184,7 +184,7 @@ delegate_task(
 
 ### \uD83E\uDD49 Workflow creator：\`workflow-creator\`（用户主动构建 workflow 时使用）
 
-专用 sub-agent：与用户**多轮交互式**协作设计 workflow，根据用户的任务/日志/trace/session 信息一步步澄清需求、学习现有模式、生成 YAML 草稿、迭代 validate 直到通过、最后由用户确认后 add。
+专用 sub-agent：与用户**多轮交互式**协作设计 workflow，根据用户的任务/日志/trace/session 信息一步步澄清需求、学习现有模式、生成 YAML 草稿、**迭代 validate 直到零 error（含模板引用契约校验）**、**构建后真跑一次并附 trace 取证**，最后由用户确认后 add。
 
 使用场景：
 - 用户说"帮我建一个 workflow 做 XXX"
@@ -221,8 +221,9 @@ delegate_task(
 
 ### 为什么必须委托？
 - default agent 用 bash \`workflow add/validate/tag list\` 手写 YAML 容易出错、命名不规范、tag 容易膨胀、节点类型不熟悉
-- workflow-creator 专做这事，6 个工具白名单 + 8 次 validate 迭代 + 学会复用已有 tag
-- 它会先用 \`workflow_list\`/\`workflow_get\` 学习现有命名约定，再 \`workflow_validate\` 直到通过，最后由用户确认后 add
+- workflow-creator 专做这事，**10 个工具白名单 + 8 次 validate 迭代 + 契约校验 + 端到端冒烟 + trace 取证** + 学会复用已有 tag
+- 它会先用 \`workflow_list\`/\`workflow_get\` 学习现有命名约定，再 \`workflow_validate\` 迭代到 **零 error**（含\`{{nodes.X.<字段>}}\` **模板引用契约**校验，能抓出 \`.result\` 用在 tool 节点这类错误），再**真跑一次**并附 trace 证据，最后由用户确认后 add
+- ⚠️ 历史教训（Task #4296）：手撸/未校验的 workflow 曾出现「validate 通过但一跑就假阳性 PASS」——prompt 引用了 tool 节点不存在的 \`.result\` 字段，引擎静默解析为空串，最终 0/0/0 却报 completed
 
 ### 快速判断矩阵（在选择 agent 前先看）
 
@@ -238,7 +239,8 @@ delegate_task(
 \`\`\`bash
 delegate_task(
   description="构建定制 workflow",
-  prompt="详细说明用户想要的 workflow 需求 + 任何上下文（task/trace/log/session 摘要）。让 workflow-creator 多轮澄清、validate 直到通过、用户确认后 add。",
+  prompt="详细说明用户想要的 workflow 需求 + 任何上下文（task/trace/log/session 摘要）。
+必做 DoD（缺一不可）：① validate 迭代到 errorCount === 0（含模板引用契约校验）；② 用真实输入 workflow_run 真跑一次，拿终态 + trace 作为证据（run_id / trace_id / session_id 落盘 + 写 task_operation）；③ 引用上游节点字段前先核对输出契约（agent → .result；tool / pythonCall / skill → .output）。三步全绿才算构建完成，最后由用户确认后 add。",
   subagent_type="workflow-creator",
   similar_task_ids=[]
 )
@@ -1443,7 +1445,7 @@ outputs: []                     # 输出定义（可空）
 | \`workflow_get\` | 取指定 workflow 完整定义（学习节点结构、template 写法） |
 | \`workflow_search\` | 关键词搜索（"code-review" / "agentNode" / "parallel" 等） |
 | \`workflow_tag_list\` | **查 tag 池，避免 tag 膨胀**（已有 \`code-review\` 时不要新增 \`review-workflow\`） |
-| \`workflow_validate\` | **必须**在 \`workflow_add\` 之前调用，直到返回 valid |
+| \`workflow_validate\` | **必须**在 \`workflow_add\` 之前调用，直到返回 **零 error**。它现在做两层校验：① DAG 结构；② **模板引用契约**（\`{{nodes.X.<字段>}}\` 是否匹配 X 的输出 schema），并返回可操作的 \`warnings\` / \`infos\` |
 | \`workflow_add\` | 注册新 workflow（需要 1-3 个 tags） |
 | \`bash\` | **仅用于契约真实性校验**（见阶段 4.5）：\`ls\` 核对脚本真名、\`grep\` 核对输出标记、\`roy-agent debug trace/debug span\` 取证。**禁止**用它绕过 workflow 直接干活 |
 | \`read_file\` | 读脚本/测试文件内容，核对它真的输出你 grep 的标记 |
@@ -1505,20 +1507,71 @@ workflow-creator 是**多轮对话式**协作。每个阶段都可能需要 ask
   把「宿主机用 docker 驱动」的脚本 \`docker cp\` 进容器再跑 = **必然空跑**，禁止。
 - 校验结论写进设计报告「契约校验」小节，注明每条契约的**核实命令 + 实际结果**。
 
+### 阶段 4.6: 引用契约先行 (Reference Contracts First) \uD83D\uDD17
+
+> 背景（真实事故，Task #4296）：\`wheels-validate-v1\` v1.3.0 的 \`report-results\`(agent)
+> 节点 prompt 写了 \`{{nodes.run-validation-tests.result}}\`，但 \`run-validation-tests\`
+> 是 **tool** 节点 —— tool 节点**没有** \`result\` 字段（只有 \`output\`）。引擎把该模板静默解析成**空字符串**（只 warn 不报错），agent 拿到空上下文后自判 ERROR，
+> 最终顶层 status 却是 \`completed\`，写出一份 0/0/0 的假报告。
+>
+> **根因不是 DAG，是「引用字段名与源节点输出 schema 不匹配」。**
+
+**铁律：写 \`{{nodes.X.<字段>}}\` 之前，先确认 X 的节点类型能产出该字段。**
+
+#### 节点输出契约表（写引用时的唯一真值）
+
+| 源节点 type | 可引用的首层字段 | 说明 |
+|---|---|---|
+| \`tool\` | **\`output\`** | tool 节点的存储值就是它的结果（常常是字符串）。**没有** \`.result\` |
+| \`pythonCall\` | **\`output\`** | JSON 解析后的 stdout |
+| \`skill\` | **\`output\`** | skill 的返回值 |
+| \`condition\` | \`output\` / \`success\` / \`condition\` | 存储值为 \`{ success, condition }\` |
+| \`merge\` | \`output\` / \`strategy\` / \`results\` / \`count\` | 存储值为 \`{ strategy, results, count }\` |
+| \`agent\` | **\`result\`** / \`output\` / \`metadata\` / \`workflowHistory\` + 声明的 JSON schema 字段 | agent 自由输出；若声明了 \`output.schema.properties\`，字段名应与 schema 对齐 |
+| \`workflow\` | \`output\` / \`result\` | 子 workflow 顶层 output（形状未知） |
+
+**记忆口诀**：
+- **\`agent\` → \`.result\`**（唯一用 \`.result\` 的节点类型）
+- **数据类节点（tool / pythonCall / skill）→ \`.output\`**
+- **\`.output\` 对所有类型都安全**（引擎把它当「取出该节点的值」的通用前缀）
+
+#### 自检两步
+
+1. **先 validate**：写完 YAML 先跑 \`workflow_validate\`，它会把
+   \`{{nodes.<toolNode>.result}}\` 这类错误直接标成 **error**，并给出 \`Did you mean "{{nodes.<toolNode>.output}}"\` 的修复建议 —— **照抄建议改**。
+2. **必要时查 schema**：需要引用 agent 节点的结构化字段时，先 \`workflow_get <相似 workflow>\` 看它的 \`output.schema\` 字段名，或在自己的 \`config.output.schema\` 里**显式声明**所有下游会用到的字段，再照字段名写引用。
+
+#### 硬约束
+
+- ❌ **禁止**在 \`tool\` / \`pythonCall\` / \`skill\` 节点上用 \`.result\`
+- ❌ **禁止**在未声明 \`output.schema\` 的 agent 节点上引用「看起来应该存在」的字段（先声明再引用）
+- ❌ **禁止**对 \`tool\` 节点写深层路径（如 \`{{nodes.bash-node.output.foo}}\`）—— tool 输出常是字符串，无法再取属性
+- ✅ 存疑时一律退回 \`.output\`，或用 \`{{nodes.X.output}}\` 打印后**人肉核对**
+
 ### 阶段 5: 迭代验证 (Iterative Validate) \uD83D\uDD01
 
-调用 \`workflow_validate\`：
-- ✅ valid → 进入阶段 6
-- ❌ invalid → 仔细阅读 errors 列表（节点 ID 重复、依赖缺失、循环、空 ID）
-  - 修正 YAML → 重新 validate
-  - **最多迭代 8 次**，超过则停止并报告失败原因
-- ❌ 不要**跳过 validate** 直接 \`workflow_add\`
+调用 \`workflow_validate\`，它返回 \`{ valid, errors, warnings, infos, errorCount, warningCount }\`。
+
+**循环直到 \`valid === true\`（即 errorCount === 0）：**
+
+| 返回项 | 你必须做什么 |
+|---|---|
+| \`errors\`（阻塞） | **逐条修复**。常见两类：① **DAG 结构**：节点 ID 重复 / 依赖缺失 / 环 / 空 ID；② **模板引用契约**（错误信息以 \`[template-contract:...]\` 开头，如 \`R2-result-on-non-agent\`）：源节点类型与所引用字段不匹配 —— **直接采用错误信息里的 \`Did you mean ...\` 建议** |
+| \`warnings\`（建议） | **逐条评估**。若判断可接受（如输出恰好是对象且含该键），在最终报告里**写明理由**；否则**一并修掉** |
+| \`infos\`（提示） | 阅读即可，多为 loop 前向引用等良性场景，无需修改 |
+
+规则：
+- ✅ \`errorCount === 0\` 才算通过 → 进入阶段 5.5
+- ❌ 有 error → 修 YAML → **重新 validate**（**最多迭代 8 次**，超过则停止并报告失败原因）
+- ❌ **不要**跳过 validate 直接 \`workflow_add\`
+- ❌ **不要**在还有 error 时用「结构没问题」自我说服 —— error 是**硬阻塞**，\`workflow_add\` 也会拒绝
 
 ### 阶段 5.5: 端到端冒烟验证 (Smoke Run) \uD83D\uDEA8 完成硬门槛
 
-> ⚠️ **\`workflow_validate\` 通过 ≠ workflow 可用。** 它只校验 DAG 结构
-> （重复节点 / 缺依赖 / 环 / 空节点 ID），**不校验**脚本路径、变量拼接、输出契约、测试是否真执行。
-> 你**必须**让 workflow 真的跑一次并拿到证据，否则**不算完成**。
+> ⚠️ **\`workflow_validate\` 通过 ≠ workflow 可用。** 它校验 DAG 结构 **+ 模板引用契约**
+> （字段名是否匹配源节点输出 schema），但**仍然不校验**：脚本路径是否真实存在、
+> 变量拼接后的字符串是否正确、输出标记是否与脚本真实输出一致、测试是否真被执行。
+> 这些**只有真跑**才能证明。你**必须**让 workflow 真的跑一次并拿到证据，否则**不算完成**。
 
 **执行路径（你有 \`workflow_run\`）：**
 
@@ -1541,6 +1594,7 @@ workflow-creator 是**多轮对话式**协作。每个阶段都可能需要 ask
 | ✅ **每个节点都有 output 且非空** | 逐个检查；出现 \`command not found\` / \`Bad substitution\` / \`timeout\` 即失败 |
 | ✅ **真实执行条数 > 0** | 例：\`passed_count + failed_count + expected_count > 0\`；**严禁 0/0/0 判 PASS** |
 | ✅ 关键输入契约在运行中被**真实命中** | 例：日志出现 \`Test script: <真名>\`，而不是 fallback 警告分支 |
+| ✅ **无 unresolved template 警告** | 在 trace / app.log 里 **grep \`has unresolved templates\`**，命中即说明仍有引用被解析成空串（引用契约错误），必须回去修 |
 | ✅ trace 里能看到**完整节点链路** | \`debug trace\` 中每个预期节点都出现且有耗时（非 0ms 跳过） |
 | ✅ run 证据落盘 | \`run_id + trace_id + session_id\` 写入 \`/tmp/<task>_smoke_evidence.json\` 与 task_operation |
 
@@ -1714,6 +1768,8 @@ outputs: []                        # 输出定义（可空）
 ## 严格约束
 
 - ✅ 只用 10 个被授予的工具（白名单强制）
+- ✅ **写 \`{{nodes.X.<字段>}}\` 前先核对访问契约表**（阶段 4.6）：\`agent\` → \`.result\`；\`tool\` / \`pythonCall\` / \`skill\` → \`.output\`
+- ✅ **validate 必须迭代到 \`errorCount === 0\`**；每条 \`warning\` 要么修掉、要么在报告中写明保留理由
 - ✅ validate **必须**在 add 之前
 - ✅ **add / update 之后必须端到端冒烟跑一次**（阶段 5.5），并附 trace 证据；否则不算完成
 - ✅ tags 1-3 个，优先复用已有 tag
@@ -1725,6 +1781,9 @@ outputs: []                        # 输出定义（可空）
 - ❌ 不要用 \`workflow update\` 绕过 validate / 冒烟
 - ❌ 不要用 \`bash\` 替代 workflow 节点完成业务逻辑（走捷径 = 交付空壳）
 - ❌ 不要凭"应该能跑"声称通过；**没有 trace / run 证据就不算跑过**
+- ❌ 不要在 \`tool\` / \`pythonCall\` / \`skill\` 节点上用 \`.result\`（引擎会静默解析成空字符串）
+- ❌ 不要对 \`tool\` 节点写深层属性路径（输出常为字符串，无法再取属性）
+- ❌ 不要在有 \`errors\` 未清零的情况下声称「语法检测 OK」
 - ❌ 不要自动 merge / push / tag
 - ❌ 不要硬编码大段 text（应引用 \`{{input.x}}\` 模板）`,
   "task-organizer": `

package/dist/shared/@ai-setting/{roy-agent-core-zd077w51.js → roy-agent-core-j8e92gj8.js}

@@ -229,6 +229,29 @@ function buildTaskCard(opts) {
   const updateCount = opts.updateCount ?? 0;
   const spinner = opts.spinner ?? "";
   const elements = [];
+  const hasGroup = !!(opts.meta.perTaskChatId && opts.meta.perTaskChatId.length > 0);
+  const taskIdForButton = opts.meta.id !== undefined ? String(opts.meta.id) : "";
+  elements.push({
+    tag: "button",
+    text: {
+      tag: "plain_text",
+      content: hasGroup ? "解散该群" : "为这个任务建群"
+    },
+    type: hasGroup ? "danger" : "primary",
+    value: {
+      action: hasGroup ? "disband_group" : "create_group",
+      taskId: taskIdForButton
+    }
+  });
+  if (hasGroup) {
+    const link = buildChatAppLink(opts.meta.perTaskChatId);
+    const label = opts.meta.perTaskChatName ? `\uD83D\uDCE8 进入专属群：${sanitizeInlineText(opts.meta.perTaskChatName, 60)}` : "\uD83D\uDCE8 进入专属群";
+    elements.push({
+      tag: "markdown",
+      content: `[${label}](${link})`
+    });
+    elements.push({ tag: "hr" });
+  }
   const infoLines = renderTaskInfoLines(opts.meta);
   if (infoLines.length > 0) {
     elements.push({ tag: "markdown", content: infoLines.join(`
@@ -595,6 +618,25 @@ class LarkCardPatchNotifier {
     this.states.delete(opts.messageId);
     this.mutexes.delete(opts.messageId);
   }
+  updateMetaAndBuildCard(messageId, meta, opts = {}) {
+    const state = this.states.get(messageId);
+    if (!state)
+      return;
+    state.meta = mergeTaskMeta(state.meta, meta);
+    if (opts.clearPerTaskChat) {
+      delete state.meta.perTaskChatId;
+      delete state.meta.perTaskChatName;
+    }
+    return buildTaskCard({
+      status: "running",
+      meta: state.meta,
+      milestones: state.milestones,
+      processSteps: state.processSteps,
+      progress: state.progress,
+      updateCount: state.updateCount,
+      spinner: SPINNER_EMOJIS[state.spinnerIndex] ?? SPINNER_EMOJIS[0]
+    });
+  }
   trackedCardCount() {
     return this.states.size;
   }
@@ -1034,4 +1076,4 @@ function sanitize(text) {
   return `${trimmed.slice(0, 500)}…`;
 }
 
-export { humanizeValue, formatDurationMs, LarkCardPatchNotifier };
+export { humanizeValue, buildTaskCard, formatDurationMs, LarkCardPatchNotifier };

package/dist/shared/@ai-setting/roy-agent-core-na73mym1.js

@@ -0,0 +1,367 @@
+import {
+  DAGManager,
+  init_dag_manager
+} from "./roy-agent-core-8s9jd2qy.js";
+
+// src/env/workflow/utils/node-output-contracts.ts
+var VIRTUAL_OUTPUT_FIELD = "output";
+var NODE_OUTPUT_CONTRACTS = {
+  tool: {
+    fields: [],
+    closed: true,
+    description: "a tool node's stored value is its result (usually a string)",
+    suggestedField: VIRTUAL_OUTPUT_FIELD
+  },
+  python_call: {
+    fields: [],
+    closed: true,
+    description: "a pythonCall node's stored value is its JSON-parsed stdout",
+    suggestedField: VIRTUAL_OUTPUT_FIELD
+  },
+  pythonCall: {
+    fields: [],
+    closed: true,
+    description: "a pythonCall node's stored value is its JSON-parsed stdout",
+    suggestedField: VIRTUAL_OUTPUT_FIELD
+  },
+  skill: {
+    fields: [],
+    closed: true,
+    description: "a skill node's stored value is the skill's return value",
+    suggestedField: VIRTUAL_OUTPUT_FIELD
+  },
+  condition: {
+    fields: ["success", "condition"],
+    closed: true,
+    description: "a condition node's stored value is { success, condition }",
+    suggestedField: VIRTUAL_OUTPUT_FIELD,
+    canonicalField: "condition"
+  },
+  merge: {
+    fields: ["strategy", "results", "count"],
+    closed: true,
+    description: "a merge node's stored value is { strategy, results, count }",
+    suggestedField: VIRTUAL_OUTPUT_FIELD,
+    canonicalField: "results"
+  },
+  agent: {
+    fields: ["result", "metadata", "workflowHistory"],
+    canonicalField: "result",
+    closed: false,
+    description: "an agent node's stored value is { result, metadata, workflowHistory, ...<json output fields> }",
+    suggestedField: "result"
+  },
+  workflow: {
+    fields: ["result"],
+    closed: false,
+    description: "a workflow node's stored value is the child workflow's top-level output",
+    suggestedField: VIRTUAL_OUTPUT_FIELD
+  },
+  ask_user: {
+    fields: [],
+    closed: true,
+    description: "an askUser node never produces output (it always pauses)"
+  },
+  askUser: {
+    fields: [],
+    closed: true,
+    description: "an askUser node never produces output (it always pauses)"
+  }
+};
+function getNodeOutputContract(nodeType) {
+  return NODE_OUTPUT_CONTRACTS[nodeType] ?? {
+    fields: [],
+    closed: false,
+    description: `unknown node type "${nodeType}" (output shape unknown)`
+  };
+}
+function getSuggestionFieldForResultMisuse(nodeType) {
+  const contract = getNodeOutputContract(nodeType);
+  return contract.canonicalField ?? contract.suggestedField ?? VIRTUAL_OUTPUT_FIELD;
+}
+function hasClosedOutputContract(nodeType) {
+  return getNodeOutputContract(nodeType).closed;
+}
+var RESULT_INVALID_NODE_TYPES = new Set([
+  "tool",
+  "python_call",
+  "pythonCall",
+  "skill",
+  "condition",
+  "merge",
+  "ask_user",
+  "askUser"
+]);
+function getAgentDeclaredJsonFields(config) {
+  const output = config?.output;
+  const properties = output?.schema?.properties;
+  if (!properties || typeof properties !== "object")
+    return;
+  const keys = Object.keys(properties);
+  return keys.length > 0 ? keys : undefined;
+}
+
+// src/env/workflow/utils/template-contract-validator.ts
+var TEMPLATE_RE = /\{\{\s*([^{}]+?)\s*\}\}/g;
+var PURE_PATH_RE = /^[A-Za-z_][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+|\[-?\d+\])*$/;
+var NON_NODE_SCOPES = new Set(["input", "inputs", "config", "env", "workflow", "vars", "secrets"]);
+function isPurePath(body) {
+  return PURE_PATH_RE.test(body);
+}
+function walkStrings(value, visit) {
+  if (typeof value === "string") {
+    visit(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value)
+      walkStrings(item, visit);
+    return;
+  }
+  if (value && typeof value === "object") {
+    for (const v of Object.values(value))
+      walkStrings(v, visit);
+  }
+}
+function extractNodeRefs(config) {
+  const refs = [];
+  walkStrings(config, (s) => {
+    TEMPLATE_RE.lastIndex = 0;
+    let m;
+    while ((m = TEMPLATE_RE.exec(s)) !== null) {
+      const raw = m[0];
+      const body = m[1].split("|")[0].trim();
+      if (!body || /\s/.test(body) || !isPurePath(body))
+        continue;
+      if (body.startsWith("#") || body.startsWith("/"))
+        continue;
+      const parts = body.split(".");
+      let sourceNodeId;
+      let rest;
+      if (parts[0] === "nodes") {
+        if (parts.length < 2)
+          continue;
+        sourceNodeId = parts[1];
+        rest = parts.slice(2);
+      } else {
+        sourceNodeId = parts[0];
+        rest = parts.slice(1);
+      }
+      if (!sourceNodeId)
+        continue;
+      if (NON_NODE_SCOPES.has(sourceNodeId))
+        continue;
+      refs.push({ template: raw, sourceNodeId, rest });
+    }
+  });
+  return refs;
+}
+function baseSegment(seg) {
+  if (!seg)
+    return "";
+  return seg.replace(/\[-?\d+\]$/, "");
+}
+function buildGraph(nodes, edges) {
+  const byId = new Map;
+  const direct = new Map;
+  for (const n of nodes) {
+    if (!n || typeof n !== "object" || typeof n.id !== "string" || !n.id)
+      continue;
+    byId.set(n.id, n);
+    const deps = Array.isArray(n.depends_on) ? n.depends_on.filter((d) => typeof d === "string") : [];
+    direct.set(n.id, [...deps]);
+  }
+  for (const e of Array.isArray(edges) ? edges : []) {
+    if (!e || typeof e.from !== "string" || typeof e.to !== "string")
+      continue;
+    const to = direct.get(e.to);
+    if (!to)
+      continue;
+    if (!to.includes(e.from))
+      to.push(e.from);
+  }
+  const upstream = new Map;
+  for (const id of byId.keys()) {
+    const seen = new Set;
+    const stack = [...direct.get(id) ?? []];
+    while (stack.length > 0) {
+      const d = stack.pop();
+      if (seen.has(d))
+        continue;
+      seen.add(d);
+      for (const dd of direct.get(d) ?? [])
+        stack.push(dd);
+    }
+    upstream.set(id, seen);
+  }
+  return { byId, upstream };
+}
+function validateTemplateContracts(definition) {
+  if (!definition || typeof definition !== "object")
+    return [];
+  const def = definition;
+  if (!Array.isArray(def.nodes))
+    return [];
+  const nodes = def.nodes;
+  const { byId, upstream } = buildGraph(nodes, Array.isArray(def.edges) ? def.edges : []);
+  const findings = [];
+  for (const node of nodes) {
+    if (!node || typeof node !== "object" || typeof node.id !== "string" || !node.id)
+      continue;
+    const nodeId = node.id;
+    const refs = extractNodeRefs(node.config);
+    const upOfNode = upstream.get(nodeId) ?? new Set;
+    for (const ref of refs) {
+      const { template, sourceNodeId, rest } = ref;
+      const src = byId.get(sourceNodeId);
+      if (!src) {
+        findings.push({
+          severity: "error",
+          rule: "R1-node-not-found",
+          nodeId,
+          template,
+          sourceNodeId,
+          message: `Node "${nodeId}" references "${template}", but no node with id ` + `"${sourceNodeId}" exists in this workflow.`,
+          suggestion: `Remove the reference, or add a node with id "${sourceNodeId}".`
+        });
+        continue;
+      }
+      const srcType = src.type;
+      const contract = getNodeOutputContract(srcType);
+      const allowed = new Set([VIRTUAL_OUTPUT_FIELD, ...contract.fields]);
+      const first = baseSegment(rest[0]);
+      if (first === "result" && RESULT_INVALID_NODE_TYPES.has(srcType)) {
+        const suggestedField = getSuggestionFieldForResultMisuse(srcType);
+        const fixed = template.replace(new RegExp(`(nodes\\.${escapeRegExp(sourceNodeId)}|^\\{\\{${escapeRegExp(sourceNodeId)})\\.result`), `$1.${suggestedField}`);
+        findings.push({
+          severity: "error",
+          rule: "R2-result-on-non-agent",
+          nodeId,
+          template,
+          sourceNodeId,
+          sourceNodeType: srcType,
+          message: `Node "${nodeId}" references "${template}", but "${sourceNodeId}" is a ` + `"${srcType}" node — ${contract.description}. The ".result" field only ` + `exists on agent nodes; the value will silently resolve to an empty ` + `string at runtime. Use ".output" instead.`,
+          suggestion: fixed !== template ? fixed : undefined
+        });
+        continue;
+      }
+      if (first && contract.closed && !allowed.has(first)) {
+        findings.push({
+          severity: "warning",
+          rule: "R3-unknown-field-on-closed",
+          nodeId,
+          template,
+          sourceNodeId,
+          sourceNodeType: srcType,
+          message: `Node "${nodeId}" references "${template}"; "${sourceNodeId}" is a ` + `"${srcType}" node whose output is ${contract.description} — "${first}" ` + `is not one of [${[...allowed].join(", ")}]. It may resolve only if the ` + `node's output object happens to contain "${first}".`,
+          suggestion: contract.suggestedField ? template.replace(new RegExp(`\\.${escapeRegExp(first)}(?=\\.|\\[|\\}\\}|$)`), `.${contract.suggestedField}`) : undefined
+        });
+      }
+      if (srcType === "tool" && first === VIRTUAL_OUTPUT_FIELD && rest.length > 1) {
+        findings.push({
+          severity: "info",
+          rule: "R4-deep-path-into-tool",
+          nodeId,
+          template,
+          sourceNodeId,
+          sourceNodeType: srcType,
+          message: `Node "${nodeId}" references "${template}" — a deep path into a "tool" ` + `node. Tool outputs are frequently plain strings, in which case ` + `".${rest.slice(1).join(".")}" cannot be navigated. Verify the tool ` + `returns a structured object.`
+        });
+      }
+      if (srcType === "agent" && first) {
+        const declared = getAgentDeclaredJsonFields(src.config);
+        if (declared && first && !allowed.has(first) && !declared.includes(first)) {
+          findings.push({
+            severity: "warning",
+            rule: "R5-agent-schema-field",
+            nodeId,
+            template,
+            sourceNodeId,
+            sourceNodeType: srcType,
+            message: `Node "${nodeId}" references "${template}", but agent node ` + `"${sourceNodeId}" declares a JSON output schema with fields ` + `[${declared.join(", ")}]. "${first}" is not among them ` + `(nor the generic "result"/"output"/"metadata"/"workflowHistory").`
+          });
+        }
+      }
+      if (sourceNodeId !== nodeId && !upOfNode.has(sourceNodeId)) {
+        findings.push({
+          severity: "info",
+          rule: "R6-not-upstream",
+          nodeId,
+          template,
+          sourceNodeId,
+          sourceNodeType: srcType,
+          message: `Node "${nodeId}" references "${template}", but "${sourceNodeId}" is not ` + `in its upstream dependency closure. This is valid for loop back-edges ` + `(consuming the previous round's output) but otherwise may resolve to an ` + `empty value on the first execution.`
+        });
+      }
+    }
+  }
+  return findings;
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function getTemplateContractErrors(definition) {
+  return validateTemplateContracts(definition).filter((f) => f.severity === "error");
+}
+function getTemplateContractWarnings(definition) {
+  return validateTemplateContracts(definition).filter((f) => f.severity === "warning");
+}
+function formatTemplateContractFindings(findings) {
+  return findings.map((f) => {
+    const head = `[template-contract:${f.rule}] Node "${f.nodeId}": ${f.message}`;
+    return f.suggestion ? `${head} — Did you mean "${f.suggestion}"?` : head;
+  });
+}
+
+// src/env/workflow/utils/validate-workflow-definition.ts
+init_dag_manager();
+function validateWorkflowDefinition(definition, options = {}) {
+  if (!definition || typeof definition !== "object") {
+    return {
+      valid: false,
+      errors: ["Workflow definition must be an object"]
+    };
+  }
+  const def = definition;
+  if (!Array.isArray(def.nodes)) {
+    return {
+      valid: false,
+      errors: ["Workflow definition must have a 'nodes' array"]
+    };
+  }
+  let structural;
+  try {
+    const dag = new DAGManager(definition, { allowCycles: false });
+    structural = dag.validate();
+  } catch (error) {
+    structural = {
+      valid: false,
+      errors: [
+        `Validation error: ${error instanceof Error ? error.message : String(error)}`
+      ]
+    };
+  }
+  let findings = [];
+  if (structural.valid && !options.skipTemplateContracts) {
+    try {
+      findings = validateTemplateContracts(definition);
+    } catch {
+      findings = [];
+    }
+  }
+  const contractErrors = findings.filter((f) => f.severity === "error");
+  const contractWarnings = findings.filter((f) => f.severity === "warning");
+  const contractInfos = findings.filter((f) => f.severity === "info");
+  const errors = [...structural.errors, ...formatTemplateContractFindings(contractErrors)];
+  const warnings = formatTemplateContractFindings(contractWarnings);
+  const infos = formatTemplateContractFindings(contractInfos);
+  return {
+    valid: structural.valid && contractErrors.length === 0,
+    errors,
+    ...warnings.length > 0 ? { warnings } : {},
+    ...infos.length > 0 ? { infos } : {},
+    ...findings.length > 0 ? { findings } : {}
+  };
+}
+
+export { VIRTUAL_OUTPUT_FIELD, NODE_OUTPUT_CONTRACTS, getNodeOutputContract, hasClosedOutputContract, RESULT_INVALID_NODE_TYPES, getAgentDeclaredJsonFields, validateTemplateContracts, getTemplateContractErrors, getTemplateContractWarnings, formatTemplateContractFindings, validateWorkflowDefinition };

package/dist/shared/@ai-setting/{roy-agent-core-gpf2059p.js → roy-agent-core-p2r27era.js}

@@ -10,7 +10,7 @@ import {
 } from "./roy-agent-core-1pg0fepg.js";
 import {
   builtInPrompts
-} from "./roy-agent-core-cg9f4zch.js";
+} from "./roy-agent-core-gdsqp6j8.js";
 import {
   DEFAULT_SUBAGENT_PROMPT
 } from "./roy-agent-core-rx16h2m1.js";