@xopcai/xopc 0.0.86 → 0.0.88

package/dist/src/agent/workflow/builtins/release-check.js

@@ -0,0 +1,165 @@
+//#region src/agent/workflow/builtins/release-check.ts
+/**
+* Built-in workflow: `release_check`
+*
+* Runs a release-readiness review for a finished change. It inspects the diff,
+* validates risk areas in parallel, and produces a go/no-go checklist.
+*
+* Args:
+*   - target: release candidate, branch, commit range, or feature summary
+*   - checks: optional subset of check keys
+*/
+const RELEASE_CHECK_SCRIPT = `export const meta = {
+  name: 'release_check',
+  description: 'Assess whether a change is ready to release with parallel risk checks and a go/no-go verdict.',
+  whenToUse: 'User is near the end of implementation and wants a release-quality readiness check before shipping.',
+  examplePrompts: [
+    { field: 'target', text: 'Is this repo ready to release v1.2?' },
+    { field: 'target', text: 'Pre-release readiness check for the current branch' },
+  ],
+  i18n: {
+    zh: {
+      description: '并行检查发布风险，判断变更是否达到可发布标准。',
+      whenToUse: '用户接近开发尾声，想在发布前做发布质量/就绪检查时。',
+      examplePrompts: [
+        { field: 'target', text: '这个仓库是否准备好发布 v1.2？' },
+        { field: 'target', text: '对当前分支做发布前就绪检查' },
+      ],
+    },
+  },
+  tags: ['release', 'quality', 'validation'],
+  estimatedAgents: { min: 6, max: 7 },
+  phases: [
+    { title: 'Scope' },
+    { title: 'Checks' },
+    { title: 'Verdict' },
+  ],
+}
+
+const READ_ONLY_TOOLS = ['read_file', 'grep', 'find', 'list_dir', 'shell']
+
+const target = args && typeof args === 'object' && args.target
+  ? String(args.target)
+  : 'Current working tree or release candidate from the conversation context.'
+
+const ALL_CHECKS = [
+  { key: 'regression', focus: 'Behavior changes, compatibility breaks, edge cases, and accidental scope creep.' },
+  { key: 'tests', focus: 'Relevant automated tests, missing regression cases, flaky or weak assertions, and manual coverage gaps.' },
+  { key: 'build', focus: 'Typecheck, lint, build, packaging, lazy imports, generated assets, and dependency correctness.' },
+  { key: 'security', focus: 'Secrets, auth/authz, input validation, unsafe shell/file/network access, and data exposure.' },
+  { key: 'ops', focus: 'Logging, observability, migrations, persistence, rollback, failure modes, and supportability.' },
+]
+
+let checks = ALL_CHECKS
+if (args && typeof args === 'object' && Array.isArray(args.checks) && args.checks.length) {
+  const selected = new Set(args.checks.map((check) => String(check)))
+  checks = ALL_CHECKS.filter((check) => selected.has(check.key))
+  if (!checks.length) checks = ALL_CHECKS
+}
+
+phase('Scope')
+const scope = await agent(
+  'Identify the release candidate scope. Inspect the working tree or target if useful. Return changed areas, user-visible behavior, and likely blast radius.\\n\\n' +
+    'TARGET:\\n' + target,
+  {
+    label: 'release scope',
+    toolset: READ_ONLY_TOOLS,
+    schema: {
+      type: 'object',
+      properties: {
+        changedAreas: { type: 'array', items: { type: 'string' } },
+        userVisibleChanges: { type: 'array', items: { type: 'string' } },
+        blastRadius: { type: 'string' },
+      },
+      required: ['changedAreas', 'blastRadius'],
+    },
+  },
+)
+
+phase('Checks')
+const reports = await parallel(
+  checks.map((check) => () =>
+    agent(
+      'Run a release-readiness check through the ' + check.key + ' lens.\\n' +
+        'Focus: ' + check.focus + '\\n\\n' +
+        'TARGET:\\n' + target + '\\n\\n' +
+        'SCOPE:\\n' + JSON.stringify(scope, null, 2) + '\\n\\n' +
+        'Return blockers, warnings, evidence, and concrete fixes. Prefer specific files/commands over generic statements.',
+      {
+        label: check.key + ' check',
+        toolset: READ_ONLY_TOOLS,
+        schema: {
+          type: 'object',
+          properties: {
+            blockers: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  title: { type: 'string' },
+                  evidence: { type: 'string' },
+                  fix: { type: 'string' },
+                },
+                required: ['title', 'evidence', 'fix'],
+              },
+            },
+            warnings: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  title: { type: 'string' },
+                  evidence: { type: 'string' },
+                  fix: { type: 'string' },
+                },
+                required: ['title', 'evidence'],
+              },
+            },
+            recommendedCommands: { type: 'array', items: { type: 'string' } },
+          },
+          required: ['blockers', 'warnings'],
+        },
+      },
+    ),
+  ),
+)
+
+phase('Verdict')
+const byCheck = {}
+for (let i = 0; i < checks.length; i++) {
+  byCheck[checks[i].key] = reports[i] ?? { blockers: [], warnings: [], recommendedCommands: [] }
+}
+
+const verdict = await agent(
+  'Synthesize a release go/no-go verdict. Block if any credible blocker remains. If not blocked, distinguish ship_now from ship_after_checks. ' +
+    'Deduplicate issues and produce the shortest checklist that would make this release safe.\\n\\n' +
+    JSON.stringify({ target, scope, byCheck }, null, 2),
+  {
+    label: 'release verdict',
+    schema: {
+      type: 'object',
+      properties: {
+        recommendation: { type: 'string', enum: ['ship_now', 'ship_after_checks', 'block'] },
+        summary: { type: 'string' },
+        blockers: { type: 'array', items: { type: 'string' } },
+        finalChecklist: { type: 'array', items: { type: 'string' } },
+        commandsToRun: { type: 'array', items: { type: 'string' } },
+      },
+      required: ['recommendation', 'summary', 'blockers', 'finalChecklist'],
+    },
+  },
+)
+
+return {
+  ok: true,
+  target,
+  checks: checks.map((check) => check.key),
+  scope,
+  ...(verdict ?? { recommendation: 'ship_after_checks', summary: 'verdict failed', blockers: [], finalChecklist: [] }),
+  byCheck,
+}
+`;
+//#endregion
+export { RELEASE_CHECK_SCRIPT };
+
+//# sourceMappingURL=release-check.js.map

package/dist/src/agent/workflow/builtins/release-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-check.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/release-check.ts"],"sourcesContent":["/**\n * Built-in workflow: `release_check`\n *\n * Runs a release-readiness review for a finished change. It inspects the diff,\n * validates risk areas in parallel, and produces a go/no-go checklist.\n *\n * Args:\n *   - target: release candidate, branch, commit range, or feature summary\n *   - checks: optional subset of check keys\n */\n\nexport const RELEASE_CHECK_SCRIPT = `export const meta = {\n  name: 'release_check',\n  description: 'Assess whether a change is ready to release with parallel risk checks and a go/no-go verdict.',\n  whenToUse: 'User is near the end of implementation and wants a release-quality readiness check before shipping.',\n  examplePrompts: [\n    { field: 'target', text: 'Is this repo ready to release v1.2?' },\n    { field: 'target', text: 'Pre-release readiness check for the current branch' },\n  ],\n  i18n: {\n    zh: {\n      description: '并行检查发布风险，判断变更是否达到可发布标准。',\n      whenToUse: '用户接近开发尾声，想在发布前做发布质量/就绪检查时。',\n      examplePrompts: [\n        { field: 'target', text: '这个仓库是否准备好发布 v1.2？' },\n        { field: 'target', text: '对当前分支做发布前就绪检查' },\n      ],\n    },\n  },\n  tags: ['release', 'quality', 'validation'],\n  estimatedAgents: { min: 6, max: 7 },\n  phases: [\n    { title: 'Scope' },\n    { title: 'Checks' },\n    { title: 'Verdict' },\n  ],\n}\n\nconst READ_ONLY_TOOLS = ['read_file', 'grep', 'find', 'list_dir', 'shell']\n\nconst target = args && typeof args === 'object' && args.target\n  ? String(args.target)\n  : 'Current working tree or release candidate from the conversation context.'\n\nconst ALL_CHECKS = [\n  { key: 'regression', focus: 'Behavior changes, compatibility breaks, edge cases, and accidental scope creep.' },\n  { key: 'tests', focus: 'Relevant automated tests, missing regression cases, flaky or weak assertions, and manual coverage gaps.' },\n  { key: 'build', focus: 'Typecheck, lint, build, packaging, lazy imports, generated assets, and dependency correctness.' },\n  { key: 'security', focus: 'Secrets, auth/authz, input validation, unsafe shell/file/network access, and data exposure.' },\n  { key: 'ops', focus: 'Logging, observability, migrations, persistence, rollback, failure modes, and supportability.' },\n]\n\nlet checks = ALL_CHECKS\nif (args && typeof args === 'object' && Array.isArray(args.checks) && args.checks.length) {\n  const selected = new Set(args.checks.map((check) => String(check)))\n  checks = ALL_CHECKS.filter((check) => selected.has(check.key))\n  if (!checks.length) checks = ALL_CHECKS\n}\n\nphase('Scope')\nconst scope = await agent(\n  'Identify the release candidate scope. Inspect the working tree or target if useful. Return changed areas, user-visible behavior, and likely blast radius.\\\\n\\\\n' +\n    'TARGET:\\\\n' + target,\n  {\n    label: 'release scope',\n    toolset: READ_ONLY_TOOLS,\n    schema: {\n      type: 'object',\n      properties: {\n        changedAreas: { type: 'array', items: { type: 'string' } },\n        userVisibleChanges: { type: 'array', items: { type: 'string' } },\n        blastRadius: { type: 'string' },\n      },\n      required: ['changedAreas', 'blastRadius'],\n    },\n  },\n)\n\nphase('Checks')\nconst reports = await parallel(\n  checks.map((check) => () =>\n    agent(\n      'Run a release-readiness check through the ' + check.key + ' lens.\\\\n' +\n        'Focus: ' + check.focus + '\\\\n\\\\n' +\n        'TARGET:\\\\n' + target + '\\\\n\\\\n' +\n        'SCOPE:\\\\n' + JSON.stringify(scope, null, 2) + '\\\\n\\\\n' +\n        'Return blockers, warnings, evidence, and concrete fixes. Prefer specific files/commands over generic statements.',\n      {\n        label: check.key + ' check',\n        toolset: READ_ONLY_TOOLS,\n        schema: {\n          type: 'object',\n          properties: {\n            blockers: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  title: { type: 'string' },\n                  evidence: { type: 'string' },\n                  fix: { type: 'string' },\n                },\n                required: ['title', 'evidence', 'fix'],\n              },\n            },\n            warnings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  title: { type: 'string' },\n                  evidence: { type: 'string' },\n                  fix: { type: 'string' },\n                },\n                required: ['title', 'evidence'],\n              },\n            },\n            recommendedCommands: { type: 'array', items: { type: 'string' } },\n          },\n          required: ['blockers', 'warnings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Verdict')\nconst byCheck = {}\nfor (let i = 0; i < checks.length; i++) {\n  byCheck[checks[i].key] = reports[i] ?? { blockers: [], warnings: [], recommendedCommands: [] }\n}\n\nconst verdict = await agent(\n  'Synthesize a release go/no-go verdict. Block if any credible blocker remains. If not blocked, distinguish ship_now from ship_after_checks. ' +\n    'Deduplicate issues and produce the shortest checklist that would make this release safe.\\\\n\\\\n' +\n    JSON.stringify({ target, scope, byCheck }, null, 2),\n  {\n    label: 'release verdict',\n    schema: {\n      type: 'object',\n      properties: {\n        recommendation: { type: 'string', enum: ['ship_now', 'ship_after_checks', 'block'] },\n        summary: { type: 'string' },\n        blockers: { type: 'array', items: { type: 'string' } },\n        finalChecklist: { type: 'array', items: { type: 'string' } },\n        commandsToRun: { type: 'array', items: { type: 'string' } },\n      },\n      required: ['recommendation', 'summary', 'blockers', 'finalChecklist'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  target,\n  checks: checks.map((check) => check.key),\n  scope,\n  ...(verdict ?? { recommendation: 'ship_after_checks', summary: 'verdict failed', blockers: [], finalChecklist: [] }),\n  byCheck,\n}\n`\n"],"mappings":";;;;;;;;;;;AAWA,MAAa,uBAAuB"}

package/dist/src/agent/workflow/builtins/research.d.ts

@@ -10,4 +10,4 @@
  *   - question: research question
  *   - depth: 'quick' (2 angles) | 'standard' (4) | 'deep' (6)
  */
-export declare const RESEARCH_SCRIPT = "export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  tags: ['research', 'investigation'],\n  estimatedAgents: { min: 4, max: 8 },\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst RESEARCH_TOOLS = ['web_search', 'web_fetch', 'read_file', 'grep', 'find', 'list_dir']\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nconst depth = args && typeof args === 'object' && args.depth\n  ? String(args.depth)\n  : 'standard'\nconst maxAngles = depth === 'quick' ? 2 : depth === 'deep' ? 6 : 4\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return exactly ' + maxAngles + ' distinct angles worth investigating, ' +\n    'each with the single most decisive sub-question. Be concrete.\\n\\nQUESTION:\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question, depth }\n}\n\nconst angles = frame.angles.slice(0, maxAngles)\n\nphase('Sweep')\nconst angleReports = await parallel(\n  angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\n\\n' +\n        'ANGLE: ' + a.title + '\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\n\\n' +\n        'Return: 3\u20136 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        toolset: RESEARCH_TOOLS,\n        maxIterations: depth === 'deep' ? 40 : 30,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Explicitly list contradictions where angles disagree. Return: an executive summary (max 5 sentences), top findings with inline source URLs, open questions, and contradictions.\\n\\n' +\n    'QUESTION:\\n' + question + '\\n\\n' +\n    JSON.stringify({ angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n        contradictions: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              topic: { type: 'string' },\n              sides: { type: 'array', items: { type: 'string' } },\n            },\n            required: ['topic', 'sides'],\n          },\n        },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  depth,\n  angleCount: angles.length,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [], contradictions: [] }),\n}\n";
+export declare const RESEARCH_SCRIPT = "export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  examplePrompts: [\n    { field: 'question', text: 'Compare Bun vs Node startup performance' },\n    { field: 'question', text: 'What are the trade-offs of SQLite vs Postgres for this app?' },\n  ],\n  i18n: {\n    zh: {\n      description: '\u591A\u89D2\u5EA6\u5E76\u884C\u8C03\u7814\u4E00\u4E2A\u95EE\u9898\uFF0C\u5E76\u4EA7\u51FA\u5E26\u5F15\u7528\u7684\u7EFC\u5408\u62A5\u544A\u3002',\n      whenToUse: '\u7528\u6237\u63D0\u51FA\u9700\u8981\u591A\u89D2\u5EA6\u68C0\u7D22\u3001\u9605\u8BFB\u6765\u6E90\u7684\u975E\u5E73\u51E1\u8C03\u7814\u95EE\u9898\u65F6\u3002',\n      examplePrompts: [\n        { field: 'question', text: '\u6BD4\u8F83 Bun \u4E0E Node \u7684\u542F\u52A8\u6027\u80FD' },\n        { field: 'question', text: '\u8FD9\u4E2A\u5E94\u7528\u7528 SQLite \u8FD8\u662F Postgres \u5404\u6709\u4EC0\u4E48\u6743\u8861\uFF1F' },\n      ],\n    },\n  },\n  tags: ['research', 'investigation'],\n  estimatedAgents: { min: 4, max: 8 },\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst RESEARCH_TOOLS = ['web_search', 'web_fetch', 'read_file', 'grep', 'find', 'list_dir']\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nconst depth = args && typeof args === 'object' && args.depth\n  ? String(args.depth)\n  : 'standard'\nconst maxAngles = depth === 'quick' ? 2 : depth === 'deep' ? 6 : 4\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return exactly ' + maxAngles + ' distinct angles worth investigating, ' +\n    'each with the single most decisive sub-question. Be concrete.\\n\\nQUESTION:\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question, depth }\n}\n\nconst angles = frame.angles.slice(0, maxAngles)\n\nphase('Sweep')\nconst angleReports = await parallel(\n  angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\n\\n' +\n        'ANGLE: ' + a.title + '\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\n\\n' +\n        'Return: 3\u20136 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        toolset: RESEARCH_TOOLS,\n        maxIterations: depth === 'deep' ? 40 : 30,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Explicitly list contradictions where angles disagree. Return: an executive summary (max 5 sentences), top findings with inline source URLs, open questions, and contradictions.\\n\\n' +\n    'QUESTION:\\n' + question + '\\n\\n' +\n    JSON.stringify({ angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n        contradictions: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              topic: { type: 'string' },\n              sides: { type: 'array', items: { type: 'string' } },\n            },\n            required: ['topic', 'sides'],\n          },\n        },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  depth,\n  angleCount: angles.length,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [], contradictions: [] }),\n}\n";

package/dist/src/agent/workflow/builtins/research.js

@@ -15,6 +15,20 @@ const RESEARCH_SCRIPT = `export const meta = {
   name: 'research',
   description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',
   whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',
+  examplePrompts: [
+    { field: 'question', text: 'Compare Bun vs Node startup performance' },
+    { field: 'question', text: 'What are the trade-offs of SQLite vs Postgres for this app?' },
+  ],
+  i18n: {
+    zh: {
+      description: '多角度并行调研一个问题，并产出带引用的综合报告。',
+      whenToUse: '用户提出需要多角度检索、阅读来源的非平凡调研问题时。',
+      examplePrompts: [
+        { field: 'question', text: '比较 Bun 与 Node 的启动性能' },
+        { field: 'question', text: '这个应用用 SQLite 还是 Postgres 各有什么权衡？' },
+      ],
+    },
+  },
   tags: ['research', 'investigation'],
   estimatedAgents: { min: 4, max: 8 },
   phases: [

package/dist/src/agent/workflow/builtins/research.js.map

@@ -1 +1 @@
-{"version":3,"file":"research.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/research.ts"],"sourcesContent":["/**\n * Built-in workflow: `research`\n *\n * Multi-modal research sweep on a question (args.question). Fans out search /\n * exploration / source-reading angles in parallel, then synthesises a cited\n * report. Each angle is its own subagent so source reading does not pollute the\n * parent context.\n *\n * Args:\n *   - question: research question\n *   - depth: 'quick' (2 angles) | 'standard' (4) | 'deep' (6)\n */\n\nexport const RESEARCH_SCRIPT = `export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  tags: ['research', 'investigation'],\n  estimatedAgents: { min: 4, max: 8 },\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst RESEARCH_TOOLS = ['web_search', 'web_fetch', 'read_file', 'grep', 'find', 'list_dir']\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nconst depth = args && typeof args === 'object' && args.depth\n  ? String(args.depth)\n  : 'standard'\nconst maxAngles = depth === 'quick' ? 2 : depth === 'deep' ? 6 : 4\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return exactly ' + maxAngles + ' distinct angles worth investigating, ' +\n    'each with the single most decisive sub-question. Be concrete.\\\\n\\\\nQUESTION:\\\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question, depth }\n}\n\nconst angles = frame.angles.slice(0, maxAngles)\n\nphase('Sweep')\nconst angleReports = await parallel(\n  angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\\\n\\\\n' +\n        'ANGLE: ' + a.title + '\\\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\\\n\\\\n' +\n        'Return: 3–6 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        toolset: RESEARCH_TOOLS,\n        maxIterations: depth === 'deep' ? 40 : 30,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Explicitly list contradictions where angles disagree. Return: an executive summary (max 5 sentences), top findings with inline source URLs, open questions, and contradictions.\\\\n\\\\n' +\n    'QUESTION:\\\\n' + question + '\\\\n\\\\n' +\n    JSON.stringify({ angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n        contradictions: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              topic: { type: 'string' },\n              sides: { type: 'array', items: { type: 'string' } },\n            },\n            required: ['topic', 'sides'],\n          },\n        },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  depth,\n  angleCount: angles.length,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [], contradictions: [] }),\n}\n`\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAa,kBAAkB"}
+{"version":3,"file":"research.js","names":[],"sources":["../../../../../src/agent/workflow/builtins/research.ts"],"sourcesContent":["/**\n * Built-in workflow: `research`\n *\n * Multi-modal research sweep on a question (args.question). Fans out search /\n * exploration / source-reading angles in parallel, then synthesises a cited\n * report. Each angle is its own subagent so source reading does not pollute the\n * parent context.\n *\n * Args:\n *   - question: research question\n *   - depth: 'quick' (2 angles) | 'standard' (4) | 'deep' (6)\n */\n\nexport const RESEARCH_SCRIPT = `export const meta = {\n  name: 'research',\n  description: 'Multi-angle research on a question with parallel exploration and a cited synthesis.',\n  whenToUse: 'User asks a non-trivial research question that benefits from multiple search angles or source reads.',\n  examplePrompts: [\n    { field: 'question', text: 'Compare Bun vs Node startup performance' },\n    { field: 'question', text: 'What are the trade-offs of SQLite vs Postgres for this app?' },\n  ],\n  i18n: {\n    zh: {\n      description: '多角度并行调研一个问题，并产出带引用的综合报告。',\n      whenToUse: '用户提出需要多角度检索、阅读来源的非平凡调研问题时。',\n      examplePrompts: [\n        { field: 'question', text: '比较 Bun 与 Node 的启动性能' },\n        { field: 'question', text: '这个应用用 SQLite 还是 Postgres 各有什么权衡？' },\n      ],\n    },\n  },\n  tags: ['research', 'investigation'],\n  estimatedAgents: { min: 4, max: 8 },\n  phases: [\n    { title: 'Frame' },\n    { title: 'Sweep' },\n    { title: 'Synthesize' },\n  ],\n}\n\nconst RESEARCH_TOOLS = ['web_search', 'web_fetch', 'read_file', 'grep', 'find', 'list_dir']\n\nconst question = args && typeof args === 'object' && args.question\n  ? String(args.question)\n  : 'No explicit question supplied; infer from the most recent user turn.'\n\nconst depth = args && typeof args === 'object' && args.depth\n  ? String(args.depth)\n  : 'standard'\nconst maxAngles = depth === 'quick' ? 2 : depth === 'deep' ? 6 : 4\n\nphase('Frame')\nconst frame = await agent(\n  'Frame this research question. Return exactly ' + maxAngles + ' distinct angles worth investigating, ' +\n    'each with the single most decisive sub-question. Be concrete.\\\\n\\\\nQUESTION:\\\\n' +\n    question,\n  {\n    label: 'framing',\n    schema: {\n      type: 'object',\n      properties: {\n        angles: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              title: { type: 'string' },\n              key_question: { type: 'string' },\n            },\n            required: ['title', 'key_question'],\n          },\n        },\n      },\n      required: ['angles'],\n    },\n  },\n)\n\nif (!frame || !frame.angles?.length) {\n  return { ok: false, reason: 'framing failed', question, depth }\n}\n\nconst angles = frame.angles.slice(0, maxAngles)\n\nphase('Sweep')\nconst angleReports = await parallel(\n  angles.map((a) => () =>\n    agent(\n      'Investigate this angle. Use search and source-read tools liberally. Distinguish what you can confirm from what is conjecture.\\\\n\\\\n' +\n        'ANGLE: ' + a.title + '\\\\n' +\n        'KEY QUESTION: ' + a.key_question + '\\\\n\\\\n' +\n        'Return: 3–6 grounded findings (each with a 1-line claim and a source URL or file path), plus the strongest counter-evidence.',\n      {\n        label: a.title,\n        toolset: RESEARCH_TOOLS,\n        maxIterations: depth === 'deep' ? 40 : 30,\n        schema: {\n          type: 'object',\n          properties: {\n            findings: {\n              type: 'array',\n              items: {\n                type: 'object',\n                properties: {\n                  claim: { type: 'string' },\n                  source: { type: 'string' },\n                  confidence: { type: 'string', enum: ['low', 'med', 'high'] },\n                },\n                required: ['claim', 'source', 'confidence'],\n              },\n            },\n            counterEvidence: { type: 'string' },\n          },\n          required: ['findings'],\n        },\n      },\n    ),\n  ),\n)\n\nphase('Synthesize')\nconst live = angleReports.filter(Boolean)\nconst synthesis = await agent(\n  'Synthesize a cited research report from these angle-level findings. Drop unsupported or duplicate claims. Use the highest-confidence source per claim. ' +\n    'Explicitly list contradictions where angles disagree. Return: an executive summary (max 5 sentences), top findings with inline source URLs, open questions, and contradictions.\\\\n\\\\n' +\n    'QUESTION:\\\\n' + question + '\\\\n\\\\n' +\n    JSON.stringify({ angles, reports: live }, null, 2),\n  {\n    label: 'synthesis',\n    schema: {\n      type: 'object',\n      properties: {\n        executiveSummary: { type: 'string' },\n        topFindings: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              claim: { type: 'string' },\n              source: { type: 'string' },\n            },\n            required: ['claim', 'source'],\n          },\n        },\n        openQuestions: { type: 'array', items: { type: 'string' } },\n        contradictions: {\n          type: 'array',\n          items: {\n            type: 'object',\n            properties: {\n              topic: { type: 'string' },\n              sides: { type: 'array', items: { type: 'string' } },\n            },\n            required: ['topic', 'sides'],\n          },\n        },\n      },\n      required: ['executiveSummary', 'topFindings'],\n    },\n  },\n)\n\nreturn {\n  ok: true,\n  question,\n  depth,\n  angleCount: angles.length,\n  ...(synthesis ?? { executiveSummary: 'synthesis failed', topFindings: [], contradictions: [] }),\n}\n`\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAa,kBAAkB"}

package/dist/src/agent/workflow/catalog.js

@@ -1,8 +1,8 @@
 import { init_paths_state, resolveStateDir } from "../../config/paths-state.js";
 import { BUILTIN_WORKFLOWS } from "./builtins/index.js";
 import { parseWorkflowScript } from "./parser.js";
-import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 //#region src/agent/workflow/catalog.ts
 /**
 * Catalog for named workflows.

package/dist/src/agent/workflow/channel-capability.d.ts

@@ -42,9 +42,9 @@ export interface WorkflowProgressPostInput {
      * prefixes mid-run `append` messages with "▾ progress" so the user can tell
      * them apart from the final summary).
      *
-     * Optional for backwards compatibility with hand-rolled callers and unit
-     * tests; the broker always provides it. Capabilities that consume the field
-     * should default to `'edit'` when missing.
+     * Optional only to keep hand-rolled callers and unit-test stubs lean — the
+     * broker always provides it. Capabilities that consume the field should
+     * default to `'edit'` when missing.
      */
     mode?: WorkflowProgressMode;
 }

package/dist/src/agent/workflow/index.d.ts

@@ -1,3 +1,4 @@
+export { applySubagentProgress } from './agent-progress.js';
 export { BUILTIN_WORKFLOWS, type BuiltinWorkflow } from './builtins/index.js';
 export { createWorkflowCatalog, defaultUserDir, type CatalogEntry, type LoadedWorkflow, type WorkflowCatalog, type WorkflowSource, } from './catalog.js';
 export { getLastWorkflowMemory, _resetLastWorkflowMemoryForTests, type LastWorkflowEntry, type LastWorkflowMemory, } from './last-run-memory.js';
@@ -8,4 +9,4 @@ export { emptySnapshotFor, runWorkflow, type RunWorkflowDeps, } from './runtime.
 export { createWorkflowSnapshot, previewValue, recomputeCounts, renderWorkflowText, type RenderOptions, } from './snapshot.js';
 export { createStructuredOutputTool, STRUCTURED_OUTPUT_TOOL_NAME, type CreateStructuredOutputToolOptions, type StructuredOutputCapture, } from './structured-output-tool.js';
 export { DelegateSubagentRunner, type DelegateSubagentRunnerDeps, } from './subagent-runner.js';
-export type { AgentScriptOptions, JsonSchema, SubagentRunner, SubagentRunOptions, WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowMeta, WorkflowMetaEstimatedAgents, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, WorkflowSnapshot, } from './types.js';
+export type { AgentScriptOptions, JsonSchema, SubagentRunner, SubagentRunOptions, SubagentProgressEvent, WorkflowAgentSnapshot, WorkflowAgentStatus, WorkflowAgentStep, WorkflowMeta, WorkflowMetaEstimatedAgents, WorkflowMetaPhase, WorkflowRunOptions, WorkflowRunResult, WorkflowSnapshot, } from './types.js';

package/dist/src/agent/workflow/index.js

@@ -1,10 +1,11 @@
+import { applySubagentProgress } from "./agent-progress.js";
 import { BUILTIN_WORKFLOWS } from "./builtins/index.js";
 import { parseWorkflowScript } from "./parser.js";
 import { createWorkflowCatalog, defaultUserDir } from "./catalog.js";
 import { _resetLastWorkflowMemoryForTests, getLastWorkflowMemory } from "./last-run-memory.js";
+import { emptySnapshotFor, runWorkflow } from "./runtime.js";
 import { createWorkflowSnapshot, previewValue, recomputeCounts, renderWorkflowText } from "./snapshot.js";
 import { WorkflowProgressBroker, _resetWorkflowProgressBrokerForTests, getWorkflowProgressBroker } from "./progress-broker.js";
-import { emptySnapshotFor, runWorkflow } from "./runtime.js";
 import { STRUCTURED_OUTPUT_TOOL_NAME, createStructuredOutputTool } from "./structured-output-tool.js";
 import { DelegateSubagentRunner } from "./subagent-runner.js";
-export { BUILTIN_WORKFLOWS, DelegateSubagentRunner, STRUCTURED_OUTPUT_TOOL_NAME, WorkflowProgressBroker, _resetLastWorkflowMemoryForTests, _resetWorkflowProgressBrokerForTests, createStructuredOutputTool, createWorkflowCatalog, createWorkflowSnapshot, defaultUserDir, emptySnapshotFor, getLastWorkflowMemory, getWorkflowProgressBroker, parseWorkflowScript, previewValue, recomputeCounts, renderWorkflowText, runWorkflow };
+export { BUILTIN_WORKFLOWS, DelegateSubagentRunner, STRUCTURED_OUTPUT_TOOL_NAME, WorkflowProgressBroker, _resetLastWorkflowMemoryForTests, _resetWorkflowProgressBrokerForTests, applySubagentProgress, createStructuredOutputTool, createWorkflowCatalog, createWorkflowSnapshot, defaultUserDir, emptySnapshotFor, getLastWorkflowMemory, getWorkflowProgressBroker, parseWorkflowScript, previewValue, recomputeCounts, renderWorkflowText, runWorkflow };

package/dist/src/agent/workflow/lint.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Static lint for workflow scripts.
+ *
+ * Catches the single most common AI-authoring bug: calling `agent()`,
+ * `parallel()`, or `pipeline()` without `await` and then using the returned
+ * Promise as if it were a value. The runtime would throw a cryptic TypeError
+ * like `results.map is not a function`; this lint converts it into an
+ * actionable error before the script ever runs.
+ *
+ * Rules (per matching CallExpression):
+ *   Allowed parents
+ *     - AwaitExpression argument                  `await parallel(...)`
+ *     - ReturnStatement argument                  `return agent(...)` (auto-unwraps)
+ *     - ExpressionStatement                       fire-and-forget; pending agents drain
+ *     - ArrowFunctionExpression expression body   `() => agent(...)` (thunk for parallel/pipeline)
+ *   Anything else (VariableDeclarator init, MemberExpression object, template
+ *   interpolation, binary/logical operand, call argument, property/array
+ *   element, ...) is rejected with a teaching message.
+ *
+ * Out of scope (handled by the runtime):
+ *   - `parallel([agent(...), agent(...)])` (promises instead of thunks) — caught
+ *     by the runtime's TypeError ("expects an array of functions, not promises").
+ *   - Promise-as-value bugs that survive lint (dynamic indirection, late await).
+ */
+import type { Node } from 'acorn';
+type AnyNode = Node & {
+    [key: string]: any;
+    start: number;
+    end: number;
+    loc?: {
+        start: {
+            line: number;
+            column: number;
+        };
+    };
+};
+export declare function lintAwaits(ast: AnyNode): void;
+export {};

package/dist/src/agent/workflow/lint.js

@@ -0,0 +1,74 @@
+//#region src/agent/workflow/lint.ts
+const LINT_TARGETS = new Set([
+	"agent",
+	"parallel",
+	"pipeline"
+]);
+function lintAwaits(ast) {
+	walk(ast, null, (node, parent) => {
+		if (!isLintTarget(node)) return;
+		if (isAcceptableParent(parent, node)) return;
+		const calleeName = node.callee.name;
+		const line = node.loc?.start.line ?? "?";
+		throw new Error(formatError(calleeName, line, parent));
+	});
+}
+function isLintTarget(node) {
+	if (node.type !== "CallExpression") return false;
+	const callee = node.callee;
+	if (!callee || callee.type !== "Identifier") return false;
+	return LINT_TARGETS.has(callee.name);
+}
+function isAcceptableParent(parent, call) {
+	if (!parent) return false;
+	switch (parent.type) {
+		case "AwaitExpression": return parent.argument === call;
+		case "ReturnStatement": return parent.argument === call;
+		case "ExpressionStatement": return parent.expression === call;
+		case "ArrowFunctionExpression": return parent.expression === true && parent.body === call;
+		default: return false;
+	}
+}
+function formatError(name, line, parent) {
+	const ctx = parentContextHint(parent);
+	return [
+		`workflow lint error at line ${line}: \`${name}(...)\` returns a Promise but is used without 'await'${ctx ? ` (${ctx})` : ""}.`,
+		`  ❌ const x = ${name}(...); x.map(...)`,
+		`  ✅ const x = await ${name}(...); x.map(...)`,
+		`Workflow scripts run in an async IIFE — 'await' parallel()/pipeline()/agent() before using their results, or 'return' them directly.`
+	].join("\n");
+}
+function parentContextHint(parent) {
+	if (!parent) return "";
+	switch (parent.type) {
+		case "VariableDeclarator": return "assigned to variable";
+		case "AssignmentExpression": return "assigned via =";
+		case "MemberExpression": return "method/property access on Promise";
+		case "TemplateLiteral": return "interpolated in template string";
+		case "BinaryExpression":
+		case "LogicalExpression": return "used in expression";
+		case "ConditionalExpression": return "used as ternary operand";
+		case "CallExpression": return "passed as argument";
+		case "Property": return "used as object property value";
+		case "ArrayExpression": return "placed in array (use a thunk: () => call)";
+		case "SpreadElement": return "spread";
+		case "IfStatement":
+		case "WhileStatement":
+		case "DoWhileStatement":
+		case "ForStatement": return "used as condition";
+		default: return parent.type;
+	}
+}
+function walk(node, parent, visit) {
+	visit(node, parent);
+	for (const value of Object.values(node)) if (Array.isArray(value)) {
+		for (const v of value) if (isAstNode(v)) walk(v, node, visit);
+	} else if (isAstNode(value)) walk(value, node, visit);
+}
+function isAstNode(value) {
+	return !!value && typeof value === "object" && typeof value.type === "string";
+}
+//#endregion
+export { lintAwaits };
+
+//# sourceMappingURL=lint.js.map

package/dist/src/agent/workflow/lint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.js","names":[],"sources":["../../../../src/agent/workflow/lint.ts"],"sourcesContent":["/**\n * Static lint for workflow scripts.\n *\n * Catches the single most common AI-authoring bug: calling `agent()`,\n * `parallel()`, or `pipeline()` without `await` and then using the returned\n * Promise as if it were a value. The runtime would throw a cryptic TypeError\n * like `results.map is not a function`; this lint converts it into an\n * actionable error before the script ever runs.\n *\n * Rules (per matching CallExpression):\n *   Allowed parents\n *     - AwaitExpression argument                  `await parallel(...)`\n *     - ReturnStatement argument                  `return agent(...)` (auto-unwraps)\n *     - ExpressionStatement                       fire-and-forget; pending agents drain\n *     - ArrowFunctionExpression expression body   `() => agent(...)` (thunk for parallel/pipeline)\n *   Anything else (VariableDeclarator init, MemberExpression object, template\n *   interpolation, binary/logical operand, call argument, property/array\n *   element, ...) is rejected with a teaching message.\n *\n * Out of scope (handled by the runtime):\n *   - `parallel([agent(...), agent(...)])` (promises instead of thunks) — caught\n *     by the runtime's TypeError (\"expects an array of functions, not promises\").\n *   - Promise-as-value bugs that survive lint (dynamic indirection, late await).\n */\n\nimport type { Node } from 'acorn';\n\ntype AnyNode = Node & {\n  [key: string]: any;\n  start: number;\n  end: number;\n  loc?: { start: { line: number; column: number } };\n};\n\nconst LINT_TARGETS = new Set(['agent', 'parallel', 'pipeline']);\n\nexport function lintAwaits(ast: AnyNode): void {\n  walk(ast, null, (node, parent) => {\n    if (!isLintTarget(node)) return;\n    if (isAcceptableParent(parent, node)) return;\n    const calleeName = (node.callee as AnyNode).name as string;\n    const line = node.loc?.start.line ?? '?';\n    throw new Error(formatError(calleeName, line, parent));\n  });\n}\n\nfunction isLintTarget(node: AnyNode): boolean {\n  if (node.type !== 'CallExpression') return false;\n  const callee = node.callee as AnyNode | undefined;\n  if (!callee || callee.type !== 'Identifier') return false;\n  return LINT_TARGETS.has(callee.name);\n}\n\nfunction isAcceptableParent(parent: AnyNode | null, call: AnyNode): boolean {\n  if (!parent) return false;\n  switch (parent.type) {\n    case 'AwaitExpression':\n      return parent.argument === call;\n    case 'ReturnStatement':\n      return parent.argument === call;\n    case 'ExpressionStatement':\n      return parent.expression === call;\n    case 'ArrowFunctionExpression':\n      // `() => agent(...)` — thunk-style body that the runtime invokes/awaits.\n      return parent.expression === true && parent.body === call;\n    default:\n      return false;\n  }\n}\n\nfunction formatError(name: string, line: number | string, parent: AnyNode | null): string {\n  const ctx = parentContextHint(parent);\n  return [\n    `workflow lint error at line ${line}: \\`${name}(...)\\` returns a Promise but is used without 'await'${ctx ? ` (${ctx})` : ''}.`,\n    `  ❌ const x = ${name}(...); x.map(...)`,\n    `  ✅ const x = await ${name}(...); x.map(...)`,\n    `Workflow scripts run in an async IIFE — 'await' parallel()/pipeline()/agent() before using their results, or 'return' them directly.`,\n  ].join('\\n');\n}\n\nfunction parentContextHint(parent: AnyNode | null): string {\n  if (!parent) return '';\n  switch (parent.type) {\n    case 'VariableDeclarator':\n      return 'assigned to variable';\n    case 'AssignmentExpression':\n      return 'assigned via =';\n    case 'MemberExpression':\n      return 'method/property access on Promise';\n    case 'TemplateLiteral':\n      return 'interpolated in template string';\n    case 'BinaryExpression':\n    case 'LogicalExpression':\n      return 'used in expression';\n    case 'ConditionalExpression':\n      return 'used as ternary operand';\n    case 'CallExpression':\n      return 'passed as argument';\n    case 'Property':\n      return 'used as object property value';\n    case 'ArrayExpression':\n      return 'placed in array (use a thunk: () => ' + 'call)';\n    case 'SpreadElement':\n      return 'spread';\n    case 'IfStatement':\n    case 'WhileStatement':\n    case 'DoWhileStatement':\n    case 'ForStatement':\n      return 'used as condition';\n    default:\n      return parent.type;\n  }\n}\n\nfunction walk(\n  node: AnyNode,\n  parent: AnyNode | null,\n  visit: (n: AnyNode, p: AnyNode | null) => void,\n): void {\n  visit(node, parent);\n  for (const value of Object.values(node)) {\n    if (Array.isArray(value)) {\n      for (const v of value) {\n        if (isAstNode(v)) walk(v, node, visit);\n      }\n    } else if (isAstNode(value)) {\n      walk(value, node, visit);\n    }\n  }\n}\n\nfunction isAstNode(value: unknown): value is AnyNode {\n  return !!value && typeof value === 'object' && typeof (value as AnyNode).type === 'string';\n}\n"],"mappings":";AAkCA,MAAM,eAAe,IAAI,IAAI;CAAC;CAAS;CAAY;CAAW,CAAC;AAE/D,SAAgB,WAAW,KAAoB;AAC7C,MAAK,KAAK,OAAO,MAAM,WAAW;AAChC,MAAI,CAAC,aAAa,KAAK,CAAE;AACzB,MAAI,mBAAmB,QAAQ,KAAK,CAAE;EACtC,MAAM,aAAc,KAAK,OAAmB;EAC5C,MAAM,OAAO,KAAK,KAAK,MAAM,QAAQ;AACrC,QAAM,IAAI,MAAM,YAAY,YAAY,MAAM,OAAO,CAAC;GACtD;;AAGJ,SAAS,aAAa,MAAwB;AAC5C,KAAI,KAAK,SAAS,iBAAkB,QAAO;CAC3C,MAAM,SAAS,KAAK;AACpB,KAAI,CAAC,UAAU,OAAO,SAAS,aAAc,QAAO;AACpD,QAAO,aAAa,IAAI,OAAO,KAAK;;AAGtC,SAAS,mBAAmB,QAAwB,MAAwB;AAC1E,KAAI,CAAC,OAAQ,QAAO;AACpB,SAAQ,OAAO,MAAf;EACE,KAAK,kBACH,QAAO,OAAO,aAAa;EAC7B,KAAK,kBACH,QAAO,OAAO,aAAa;EAC7B,KAAK,sBACH,QAAO,OAAO,eAAe;EAC/B,KAAK,0BAEH,QAAO,OAAO,eAAe,QAAQ,OAAO,SAAS;EACvD,QACE,QAAO;;;AAIb,SAAS,YAAY,MAAc,MAAuB,QAAgC;CACxF,MAAM,MAAM,kBAAkB,OAAO;AACrC,QAAO;EACL,+BAA+B,KAAK,MAAM,KAAK,uDAAuD,MAAM,KAAK,IAAI,KAAK,GAAG;EAC7H,iBAAiB,KAAK;EACtB,uBAAuB,KAAK;EAC5B;EACD,CAAC,KAAK,KAAK;;AAGd,SAAS,kBAAkB,QAAgC;AACzD,KAAI,CAAC,OAAQ,QAAO;AACpB,SAAQ,OAAO,MAAf;EACE,KAAK,qBACH,QAAO;EACT,KAAK,uBACH,QAAO;EACT,KAAK,mBACH,QAAO;EACT,KAAK,kBACH,QAAO;EACT,KAAK;EACL,KAAK,oBACH,QAAO;EACT,KAAK,wBACH,QAAO;EACT,KAAK,iBACH,QAAO;EACT,KAAK,WACH,QAAO;EACT,KAAK,kBACH,QAAO;EACT,KAAK,gBACH,QAAO;EACT,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK,eACH,QAAO;EACT,QACE,QAAO,OAAO;;;AAIpB,SAAS,KACP,MACA,QACA,OACM;AACN,OAAM,MAAM,OAAO;AACnB,MAAK,MAAM,SAAS,OAAO,OAAO,KAAK,CACrC,KAAI,MAAM,QAAQ,MAAM;OACjB,MAAM,KAAK,MACd,KAAI,UAAU,EAAE,CAAE,MAAK,GAAG,MAAM,MAAM;YAE/B,UAAU,MAAM,CACzB,MAAK,OAAO,MAAM,MAAM;;AAK9B,SAAS,UAAU,OAAkC;AACnD,QAAO,CAAC,CAAC,SAAS,OAAO,UAAU,YAAY,OAAQ,MAAkB,SAAS"}

package/dist/src/agent/workflow/meta-locale.d.ts

@@ -0,0 +1,12 @@
+import type { WorkflowMeta, WorkflowMetaExamplePrompt, WorkflowMetaLocale } from './types.js';
+export type WorkflowLocaleCode = 'en' | 'zh';
+export declare function normalizeWorkflowLocale(language: string | undefined): WorkflowLocaleCode;
+export interface WorkflowLocalizedCopy {
+    description: string;
+    whenToUse?: string;
+    examplePrompts: WorkflowMetaExamplePrompt[];
+}
+export declare function resolveWorkflowLocalizedCopy(meta: Pick<WorkflowMeta, 'description' | 'whenToUse' | 'examplePrompts' | 'i18n'>, locale: WorkflowLocaleCode): WorkflowLocalizedCopy;
+export declare function validateExamplePrompts(value: unknown, path: string): WorkflowMetaExamplePrompt[] | undefined;
+export declare function validateMetaLocale(value: unknown, path: string): WorkflowMetaLocale;
+export declare function validateMetaI18n(value: unknown): Record<string, WorkflowMetaLocale> | undefined;

package/dist/src/agent/workflow/meta-locale.js

@@ -0,0 +1,62 @@
+//#region src/agent/workflow/meta-locale.ts
+function normalizeWorkflowLocale(language) {
+	return language === "zh" ? "zh" : "en";
+}
+function resolveWorkflowLocalizedCopy(meta, locale) {
+	const bundle = locale !== "en" ? meta.i18n?.[locale] : void 0;
+	const examplePrompts = bundle?.examplePrompts && bundle.examplePrompts.length > 0 ? bundle.examplePrompts : meta.examplePrompts ?? [];
+	return {
+		description: pickNonEmpty(bundle?.description, meta.description),
+		whenToUse: pickOptional(bundle?.whenToUse, meta.whenToUse),
+		examplePrompts
+	};
+}
+function pickNonEmpty(localized, fallback) {
+	const trimmed = localized?.trim();
+	return trimmed ? trimmed : fallback;
+}
+function pickOptional(localized, fallback) {
+	const trimmed = localized?.trim();
+	if (trimmed) return trimmed;
+	return fallback?.trim() || void 0;
+}
+function validateExamplePrompts(value, path) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value)) throw new Error(`${path} must be an array`);
+	const prompts = [];
+	for (let index = 0; index < value.length; index++) {
+		const item = value[index];
+		if (!item || typeof item !== "object") throw new Error(`${path}[${index}] must be an object`);
+		const field = item.field;
+		const text = item.text;
+		if (typeof field !== "string" || !field.trim()) throw new Error(`${path}[${index}].field must be a non-empty string`);
+		if (typeof text !== "string" || !text.trim()) throw new Error(`${path}[${index}].text must be a non-empty string`);
+		prompts.push({
+			field: field.trim(),
+			text: text.trim()
+		});
+	}
+	return prompts;
+}
+function validateMetaLocale(value, path) {
+	if (!value || typeof value !== "object") throw new Error(`${path} must be an object`);
+	const record = value;
+	if (record.description !== void 0 && (typeof record.description !== "string" || !record.description.trim())) throw new Error(`${path}.description must be a non-empty string`);
+	if (record.whenToUse !== void 0 && typeof record.whenToUse !== "string") throw new Error(`${path}.whenToUse must be a string`);
+	validateExamplePrompts(record.examplePrompts, `${path}.examplePrompts`);
+	return record;
+}
+function validateMetaI18n(value) {
+	if (value === void 0) return void 0;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("meta.i18n must be an object");
+	const locales = {};
+	for (const [locale, bundle] of Object.entries(value)) {
+		if (!/^[a-z]{2}(-[A-Za-z]{2})?$/.test(locale)) throw new Error(`meta.i18n key "${locale}" must be a language tag like "zh" or "en"`);
+		locales[locale] = validateMetaLocale(bundle, `meta.i18n.${locale}`);
+	}
+	return locales;
+}
+//#endregion
+export { normalizeWorkflowLocale, resolveWorkflowLocalizedCopy, validateExamplePrompts, validateMetaI18n, validateMetaLocale };
+
+//# sourceMappingURL=meta-locale.js.map

package/dist/src/agent/workflow/meta-locale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-locale.js","names":[],"sources":["../../../../src/agent/workflow/meta-locale.ts"],"sourcesContent":["import type { WorkflowMeta, WorkflowMetaExamplePrompt, WorkflowMetaLocale } from './types.js';\n\nexport type WorkflowLocaleCode = 'en' | 'zh';\n\nexport function normalizeWorkflowLocale(language: string | undefined): WorkflowLocaleCode {\n  return language === 'zh' ? 'zh' : 'en';\n}\n\nexport interface WorkflowLocalizedCopy {\n  description: string;\n  whenToUse?: string;\n  examplePrompts: WorkflowMetaExamplePrompt[];\n}\n\nexport function resolveWorkflowLocalizedCopy(\n  meta: Pick<WorkflowMeta, 'description' | 'whenToUse' | 'examplePrompts' | 'i18n'>,\n  locale: WorkflowLocaleCode,\n): WorkflowLocalizedCopy {\n  const bundle = locale !== 'en' ? meta.i18n?.[locale] : undefined;\n  const examplePrompts =\n    bundle?.examplePrompts && bundle.examplePrompts.length > 0\n      ? bundle.examplePrompts\n      : (meta.examplePrompts ?? []);\n  return {\n    description: pickNonEmpty(bundle?.description, meta.description),\n    whenToUse: pickOptional(bundle?.whenToUse, meta.whenToUse),\n    examplePrompts,\n  };\n}\n\nfunction pickNonEmpty(localized: string | undefined, fallback: string): string {\n  const trimmed = localized?.trim();\n  return trimmed ? trimmed : fallback;\n}\n\nfunction pickOptional(localized: string | undefined, fallback: string | undefined): string | undefined {\n  const trimmed = localized?.trim();\n  if (trimmed) return trimmed;\n  const fb = fallback?.trim();\n  return fb || undefined;\n}\n\nexport function validateExamplePrompts(value: unknown, path: string): WorkflowMetaExamplePrompt[] | undefined {\n  if (value === undefined) return undefined;\n  if (!Array.isArray(value)) {\n    throw new Error(`${path} must be an array`);\n  }\n  const prompts: WorkflowMetaExamplePrompt[] = [];\n  for (let index = 0; index < value.length; index++) {\n    const item = value[index];\n    if (!item || typeof item !== 'object') {\n      throw new Error(`${path}[${index}] must be an object`);\n    }\n    const field = (item as WorkflowMetaExamplePrompt).field;\n    const text = (item as WorkflowMetaExamplePrompt).text;\n    if (typeof field !== 'string' || !field.trim()) {\n      throw new Error(`${path}[${index}].field must be a non-empty string`);\n    }\n    if (typeof text !== 'string' || !text.trim()) {\n      throw new Error(`${path}[${index}].text must be a non-empty string`);\n    }\n    prompts.push({ field: field.trim(), text: text.trim() });\n  }\n  return prompts;\n}\n\nexport function validateMetaLocale(value: unknown, path: string): WorkflowMetaLocale {\n  if (!value || typeof value !== 'object') {\n    throw new Error(`${path} must be an object`);\n  }\n  const record = value as WorkflowMetaLocale;\n  if (record.description !== undefined && (typeof record.description !== 'string' || !record.description.trim())) {\n    throw new Error(`${path}.description must be a non-empty string`);\n  }\n  if (record.whenToUse !== undefined && typeof record.whenToUse !== 'string') {\n    throw new Error(`${path}.whenToUse must be a string`);\n  }\n  validateExamplePrompts(record.examplePrompts, `${path}.examplePrompts`);\n  return record;\n}\n\nexport function validateMetaI18n(value: unknown): Record<string, WorkflowMetaLocale> | undefined {\n  if (value === undefined) return undefined;\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    throw new Error('meta.i18n must be an object');\n  }\n  const locales: Record<string, WorkflowMetaLocale> = {};\n  for (const [locale, bundle] of Object.entries(value as Record<string, unknown>)) {\n    if (!/^[a-z]{2}(-[A-Za-z]{2})?$/.test(locale)) {\n      throw new Error(`meta.i18n key \"${locale}\" must be a language tag like \"zh\" or \"en\"`);\n    }\n    locales[locale] = validateMetaLocale(bundle, `meta.i18n.${locale}`);\n  }\n  return locales;\n}\n"],"mappings":";AAIA,SAAgB,wBAAwB,UAAkD;AACxF,QAAO,aAAa,OAAO,OAAO;;AASpC,SAAgB,6BACd,MACA,QACuB;CACvB,MAAM,SAAS,WAAW,OAAO,KAAK,OAAO,UAAU,KAAA;CACvD,MAAM,iBACJ,QAAQ,kBAAkB,OAAO,eAAe,SAAS,IACrD,OAAO,iBACN,KAAK,kBAAkB,EAAE;AAChC,QAAO;EACL,aAAa,aAAa,QAAQ,aAAa,KAAK,YAAY;EAChE,WAAW,aAAa,QAAQ,WAAW,KAAK,UAAU;EAC1D;EACD;;AAGH,SAAS,aAAa,WAA+B,UAA0B;CAC7E,MAAM,UAAU,WAAW,MAAM;AACjC,QAAO,UAAU,UAAU;;AAG7B,SAAS,aAAa,WAA+B,UAAkD;CACrG,MAAM,UAAU,WAAW,MAAM;AACjC,KAAI,QAAS,QAAO;AAEpB,QADW,UAAU,MAAM,IACd,KAAA;;AAGf,SAAgB,uBAAuB,OAAgB,MAAuD;AAC5G,KAAI,UAAU,KAAA,EAAW,QAAO,KAAA;AAChC,KAAI,CAAC,MAAM,QAAQ,MAAM,CACvB,OAAM,IAAI,MAAM,GAAG,KAAK,mBAAmB;CAE7C,MAAM,UAAuC,EAAE;AAC/C,MAAK,IAAI,QAAQ,GAAG,QAAQ,MAAM,QAAQ,SAAS;EACjD,MAAM,OAAO,MAAM;AACnB,MAAI,CAAC,QAAQ,OAAO,SAAS,SAC3B,OAAM,IAAI,MAAM,GAAG,KAAK,GAAG,MAAM,qBAAqB;EAExD,MAAM,QAAS,KAAmC;EAClD,MAAM,OAAQ,KAAmC;AACjD,MAAI,OAAO,UAAU,YAAY,CAAC,MAAM,MAAM,CAC5C,OAAM,IAAI,MAAM,GAAG,KAAK,GAAG,MAAM,oCAAoC;AAEvE,MAAI,OAAO,SAAS,YAAY,CAAC,KAAK,MAAM,CAC1C,OAAM,IAAI,MAAM,GAAG,KAAK,GAAG,MAAM,mCAAmC;AAEtE,UAAQ,KAAK;GAAE,OAAO,MAAM,MAAM;GAAE,MAAM,KAAK,MAAM;GAAE,CAAC;;AAE1D,QAAO;;AAGT,SAAgB,mBAAmB,OAAgB,MAAkC;AACnF,KAAI,CAAC,SAAS,OAAO,UAAU,SAC7B,OAAM,IAAI,MAAM,GAAG,KAAK,oBAAoB;CAE9C,MAAM,SAAS;AACf,KAAI,OAAO,gBAAgB,KAAA,MAAc,OAAO,OAAO,gBAAgB,YAAY,CAAC,OAAO,YAAY,MAAM,EAC3G,OAAM,IAAI,MAAM,GAAG,KAAK,yCAAyC;AAEnE,KAAI,OAAO,cAAc,KAAA,KAAa,OAAO,OAAO,cAAc,SAChE,OAAM,IAAI,MAAM,GAAG,KAAK,6BAA6B;AAEvD,wBAAuB,OAAO,gBAAgB,GAAG,KAAK,iBAAiB;AACvE,QAAO;;AAGT,SAAgB,iBAAiB,OAAgE;AAC/F,KAAI,UAAU,KAAA,EAAW,QAAO,KAAA;AAChC,KAAI,CAAC,SAAS,OAAO,UAAU,YAAY,MAAM,QAAQ,MAAM,CAC7D,OAAM,IAAI,MAAM,8BAA8B;CAEhD,MAAM,UAA8C,EAAE;AACtD,MAAK,MAAM,CAAC,QAAQ,WAAW,OAAO,QAAQ,MAAiC,EAAE;AAC/E,MAAI,CAAC,4BAA4B,KAAK,OAAO,CAC3C,OAAM,IAAI,MAAM,kBAAkB,OAAO,4CAA4C;AAEvF,UAAQ,UAAU,mBAAmB,QAAQ,aAAa,SAAS;;AAErE,QAAO"}

package/dist/src/agent/workflow/parser.js

@@ -1,3 +1,5 @@
+import { lintAwaits } from "./lint.js";
+import { validateExamplePrompts, validateMetaI18n } from "./meta-locale.js";
 import { parse } from "acorn";
 //#region src/agent/workflow/parser.ts
 /**
@@ -23,7 +25,8 @@ function parseWorkflowScript(script) {
 			sourceType: "module",
 			allowAwaitOutsideFunction: true,
 			allowReturnOutsideFunction: true,
-			ranges: false
+			ranges: false,
+			locations: true
 		});
 	} catch (e) {
 		const msg = e instanceof Error ? e.message : String(e);
@@ -31,6 +34,7 @@ function parseWorkflowScript(script) {
 	}
 	assertDeterministicAst(ast);
 	assertNoDangerousImports(ast);
+	lintAwaits(ast);
 	const first = ast.body?.[0];
 	if (first?.type !== "ExportNamedDeclaration") throw new Error("`export const meta = { name, description }` must be the first statement in the script");
 	const declaration = first.declaration;
@@ -139,6 +143,8 @@ function validateMeta(meta) {
 		if (typeof est.min !== "number" || typeof est.max !== "number" || !Number.isFinite(est.min) || !Number.isFinite(est.max)) throw new Error("meta.estimatedAgents.min and .max must be finite numbers");
 		if (est.min < 1 || est.max < est.min) throw new Error("meta.estimatedAgents requires min >= 1 and max >= min");
 	}
+	validateExamplePrompts(value.examplePrompts, "meta.examplePrompts");
+	validateMetaI18n(value.i18n);
 }
 //#endregion
 export { parseWorkflowScript };