minimal-agent 0.10.0 → 0.12.0

package/plugins/workflow-runner/src/controlFlow/pause.ts

@@ -0,0 +1,141 @@
+/**
+ * ============================================================
+ *  controlFlow/pause.ts —— 真 HITL 审批闸门
+ * ------------------------------------------------------------
+ *  经 AskUserQuestion/askBridge 实现**真停等**：TUI 弹选择界面、用户拍板后继续；
+ *  非交互宿主（-p / gateway / 测试）askBridge 自动选推荐项（继续执行）且 stderr
+ *  注记，**绝不挂起** —— 与 `-p` 单行 JSON 契约兼容。「等用户」骑在既有
+ *  tool_call→tool_result 回路上（同 AskUserQuestion 工具），引擎零新通道。
+ *
+ *  两条踩过坑的判定规则，改动前先读：
+ *   ① **只解析【答案行】（`A1: …`）**。回执里 Q 行带着问题原文，而工作流的 pause
+ *      提示语常含「停止」字样（如 plan.yaml 的说明文字）—— 看整个 content 会把
+ *      用户选的「继续」误判成停止。**曾是真事故。**
+ *   ② **审批门上的含糊 = 不批准**。明确选「继续」才放行；选「停止」、取消提问（ESC）、
+ *      或自由输入其它内容（= 用户想先改点什么）一律不放行。只有**桥本身异常**才
+ *      兜底放行（保持可用性）并响亮警告。
+ * ============================================================
+ */
+
+import { executeTool, type LoopEvent } from '../../../../src/plugin-sdk.js';
+import { truncate } from '../agentCommon.js';
+import { interpolate } from '../expressions.js';
+import { commitStep } from '../stepPipeline.js';
+import type { StepDef, StepResult, VarStack, WorkflowEvent } from '../types.js';
+import type { ControlDeps, ControlOutcome } from './types.js';
+
+const WF_PLUGIN_ID = 'workflow-runner';
+
+export async function* execPauseStep(
+  step: StepDef,
+  vars: VarStack,
+  deps: ControlDeps,
+): AsyncGenerator<WorkflowEvent | LoopEvent, ControlOutcome, void> {
+  const { ctx, state, cp } = deps;
+  const msg = step.prompt
+    ? interpolate(step.prompt, vars)
+    : '工作流暂停点：请确认是否继续执行后续步骤。';
+  await state.appendProgress(`- ${step.id} pause: 等待用户确认`);
+  // pause 会驻留状态行很久（等用户），title 步同样不带块内序号防误读。
+  if (step.title) {
+    yield {
+      type: 'plugin_progress',
+      pluginId: WF_PLUGIN_ID,
+      message: `⏸ ${interpolate(step.title, vars)}：等待用户确认…`,
+    };
+  } else {
+    yield {
+      type: 'plugin_progress',
+      pluginId: WF_PLUGIN_ID,
+      current: deps.index + 1,
+      max: deps.total,
+      message: `⏸ 审批闸门 ${step.id}：等待用户确认…`,
+    };
+  }
+
+  const exec = ctx.executeTool ?? executeTool;
+  let approved = true;
+  let askFailed = false;
+  let freeText = '';
+  const freeTextMode = step.free_text ?? 'halt';
+  try {
+    const r = await exec(
+      'AskUserQuestion',
+      JSON.stringify({
+        questions: [
+          {
+            question: truncate(msg, 400),
+            header: '审批闸门',
+            options: [
+              { label: '继续执行 (推荐)', description: '放行后续步骤' },
+              {
+                label: '停止（保留现场）',
+                description: '中止本次运行；同任务重跑可从断点 resume',
+              },
+            ],
+          },
+        ],
+      }),
+      ctx.signal,
+    );
+    // ⚠️ 只解析【答案行】——见文件头注规则 ①。
+    const answerText = r.ok
+      ? r.content
+          .split('\n')
+          .map((l) => l.trim())
+          .filter((l) => /^A\d+[:：]/.test(l))
+          .join('\n')
+      : '';
+    if (!r.ok || answerText.includes('停止')) {
+      approved = false;
+    } else if (answerText.includes('继续')) {
+      approved = true;
+    } else {
+      // 自由输入（「其他」逃生项）：用户想先调整 → 不放行，把原话带进 halt 文案
+      freeText = answerText.replace(/^A\d+[:：]\s*/, '');
+      approved = freeTextMode === 'approve';
+    }
+  } catch {
+    askFailed = true; // 桥不可用 → 放行 + 响亮警告（保持旧"不挂起"行为）
+  }
+
+  if (askFailed) {
+    yield {
+      type: 'warning',
+      message: `⚠ pause "${step.id}" 审批闸门不可用（提问桥异常），已自动放行。提示：${msg}`,
+    };
+  }
+
+  if (!approved) {
+    const why = freeText
+      ? `用户在审批闸门 "${step.id}" 给出指示「${truncate(freeText, 120)}」——未放行（现场已保留，按指示调整后重跑同目标可从断点续跑）`
+      : `用户在审批闸门 "${step.id}" 选择停止（现场已保留，重跑同目标可从断点续跑）`;
+    await state.appendProgress(`■ ${step.id}: ${why}`);
+    if (cp) await state.recordFailure(step.id, why);
+    yield { type: 'workflow_step_end', id: step.id, ok: false, error: why };
+    yield { type: 'error', error: `Workflow halted at step "${step.id}": ${why}` };
+    return { kind: 'halted' };
+  }
+
+  // 带补充要求的放行：自由输入并入贯穿目标（后续每步都看到，不止 capture 变量）
+  if (freeText) await deps.addGoalSupplement(freeText);
+
+  const pauseResult: StepResult = {
+    raw: { result: freeText, text: freeText, approved: true, free_text: freeText },
+    preview: freeText
+      ? `审批通过：继续执行；补充要求：${truncate(freeText, 120)}`
+      : '审批通过：继续执行',
+  };
+  yield* commitStep({
+    step,
+    result: pauseResult,
+    kind: 'pause',
+    vars,
+    ctx,
+    state,
+    ...(cp ? { cp } : {}),
+    progressLine: `✓ ${step.id} (pause: 已确认继续)`,
+    addGoalSupplement: deps.addGoalSupplement,
+  });
+  return { kind: 'next' };
+}

package/plugins/workflow-runner/src/controlFlow/signal.js

@@ -0,0 +1,21 @@
+/**
+ * controlFlow/signal.ts —— break / continue
+ *
+ * `target:<loopId>` 让信号**穿透中间层循环**直达指定 loop ——
+ * 审批反馈是方向性变化时，从审批小循环打回外层规划循环靠的就是它。
+ *
+ * ⚠️ 这里**不再重复评估 `step.when`**。重构前这个块里有一份自己的 when 求值，
+ * 而 `runSteps` 的通用 when 守卫在它之前就跑过了：when=false 时早已
+ * `workflow_step_skipped` 并跳过本步，根本到不了这里。也就是说那份求值
+ * `shouldFire` 恒为真、它的 catch 分支永不可达 —— 纯死代码，随本次重构删掉。
+ */
+export async function* execSignalStep(step, deps) {
+    const signal = step.type === 'continue' ? 'continue' : 'break';
+    const label = `${signal}${step.target ? ` → ${step.target}` : ''}`;
+    await deps.state.appendProgress(`↵ ${step.id}: ${label}`);
+    yield { type: 'workflow_step_end', id: step.id, ok: true, output: label };
+    return {
+        kind: 'flow',
+        signal: { signal, ...(step.target ? { target: step.target } : {}) },
+    };
+}

package/plugins/workflow-runner/src/controlFlow/signal.ts

@@ -0,0 +1,29 @@
+/**
+ * controlFlow/signal.ts —— break / continue
+ *
+ * `target:<loopId>` 让信号**穿透中间层循环**直达指定 loop ——
+ * 审批反馈是方向性变化时，从审批小循环打回外层规划循环靠的就是它。
+ *
+ * ⚠️ 这里**不再重复评估 `step.when`**。重构前这个块里有一份自己的 when 求值，
+ * 而 `runSteps` 的通用 when 守卫在它之前就跑过了：when=false 时早已
+ * `workflow_step_skipped` 并跳过本步，根本到不了这里。也就是说那份求值
+ * `shouldFire` 恒为真、它的 catch 分支永不可达 —— 纯死代码，随本次重构删掉。
+ */
+
+import type { LoopEvent } from '../../../../src/plugin-sdk.js';
+import type { StepDef, WorkflowEvent } from '../types.js';
+import type { ControlDeps, ControlOutcome } from './types.js';
+
+export async function* execSignalStep(
+  step: StepDef,
+  deps: ControlDeps,
+): AsyncGenerator<WorkflowEvent | LoopEvent, ControlOutcome, void> {
+  const signal = step.type === 'continue' ? 'continue' : 'break';
+  const label = `${signal}${step.target ? ` → ${step.target}` : ''}`;
+  await deps.state.appendProgress(`↵ ${step.id}: ${label}`);
+  yield { type: 'workflow_step_end', id: step.id, ok: true, output: label };
+  return {
+    kind: 'flow',
+    signal: { signal, ...(step.target ? { target: step.target } : {}) },
+  };
+}

package/plugins/workflow-runner/src/controlFlow/types.js

@@ -0,0 +1,18 @@
+/**
+ * ============================================================
+ *  controlFlow/types.ts —— 控制流模块的统一契约
+ * ------------------------------------------------------------
+ *  控制流 step（branch / loop / break / continue / pause）与动作 step 的区别是
+ *  **它们影响的是迭代本身**，不是产出一个 StepResult。所以它们不能塞进
+ *  `stepExecutors/` 那套 `(step, vars, ctx) → StepResult` 的形状里 ——
+ *  硬塞的结果是「执行器返回值里带一个谁都看不懂的控制信号」。
+ *
+ *  这里给它们一个自己的出口形状，让 `runSteps` 只需要一个 switch。
+ *
+ *  ⚠️ **循环依赖的解法**：loop / branch 需要递归执行子块，而子块执行在
+ *  `runner.ts::runSteps` 里。**不要互相 import** —— 把它作为依赖注入进来
+ *  （`ControlDeps.runBlock`）。这同时让控制流模块能脱离 runner 单测：
+ *  喂一个假的 runBlock 就能验 break 的 target 穿透。
+ * ============================================================
+ */
+export {};

package/plugins/workflow-runner/src/controlFlow/types.ts

@@ -0,0 +1,63 @@
+/**
+ * ============================================================
+ *  controlFlow/types.ts —— 控制流模块的统一契约
+ * ------------------------------------------------------------
+ *  控制流 step（branch / loop / break / continue / pause）与动作 step 的区别是
+ *  **它们影响的是迭代本身**，不是产出一个 StepResult。所以它们不能塞进
+ *  `stepExecutors/` 那套 `(step, vars, ctx) → StepResult` 的形状里 ——
+ *  硬塞的结果是「执行器返回值里带一个谁都看不懂的控制信号」。
+ *
+ *  这里给它们一个自己的出口形状，让 `runSteps` 只需要一个 switch。
+ *
+ *  ⚠️ **循环依赖的解法**：loop / branch 需要递归执行子块，而子块执行在
+ *  `runner.ts::runSteps` 里。**不要互相 import** —— 把它作为依赖注入进来
+ *  （`ControlDeps.runBlock`）。这同时让控制流模块能脱离 runner 单测：
+ *  喂一个假的 runBlock 就能验 break 的 target 穿透。
+ * ============================================================
+ */
+
+import type { LoopEvent } from '../../../../src/plugin-sdk.js';
+import type { CpScope } from '../stepPipeline.js';
+import type {
+  RunContext,
+  StepDef,
+  VarStack,
+  WorkflowEvent,
+} from '../types.js';
+import type { LoopResumeInfo, WorkflowState } from '../workflowState.js';
+
+/** break / continue 向上传播的信号（含 `target:` 标签，用于穿透中间层循环）。 */
+export interface FlowSignal {
+  signal: 'break' | 'continue';
+  target?: string;
+}
+
+/** 一段 steps 的执行结局。 */
+export type StepFlow = 'completed' | 'halted' | FlowSignal;
+
+/** 控制流处理器的出口。 */
+export type ControlOutcome =
+  | { kind: 'next' }                     // 本步处理完，继续下一步
+  | { kind: 'flow'; signal: FlowSignal }  // 向上传播给最近的循环 / 顶层
+  | { kind: 'halted' };
+
+/** 递归执行子块的能力，由 runner 注入（见文件头注：避免循环依赖）。 */
+export type RunBlock = (
+  steps: StepDef[],
+  vars: VarStack,
+  cp?: CpScope,
+  startFrom?: number,
+  loopResume?: LoopResumeInfo,
+) => AsyncGenerator<WorkflowEvent | LoopEvent, StepFlow, void>;
+
+export interface ControlDeps {
+  ctx: RunContext;
+  state: WorkflowState;
+  cp?: CpScope;
+  runBlock: RunBlock;
+  /** 本步在当前 block 中的位置，仅用于 plugin_progress 的 current/max。 */
+  index: number;
+  total: number;
+  /** 累加用户补充要求（pause 的自由输入走它）。由 runner 注入，避免反向依赖。 */
+  addGoalSupplement: (text: string) => Promise<void>;
+}

package/plugins/workflow-runner/src/dslManifest.ts

@@ -0,0 +1,127 @@
+import { ACTION_KINDS, CONTROL_FLOW_TYPES, ON_ERROR_VALUES, VALID_STEP_TYPES } from './loader.js';
+
+export type DslFieldUi =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'boolean'
+  | 'select'
+  | 'json'
+  | 'string[]'
+  | 'object[]';
+
+export interface WorkflowDslField {
+  name: string;
+  type:
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'enum'
+    | 'object'
+    | 'array'
+    | 'string[]'
+    | 'object[]';
+  ui: DslFieldUi;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  default?: unknown;
+  enum?: string[];
+  appliesTo?: string[];
+  disallowedOn?: string[];
+}
+
+export interface WorkflowDslStepKind {
+  kind: string;
+  group: 'action' | 'control' | 'quality';
+  label: string;
+  description: string;
+  primaryFields: string[];
+  childCollections?: string[];
+}
+
+export interface WorkflowDslManifest {
+  version: string;
+  actionKinds: string[];
+  controlFlowTypes: string[];
+  validStepTypes: string[];
+  onErrorValues: string[];
+  exclusiveActionFields: string[];
+  stepKinds: WorkflowDslStepKind[];
+  commonStepFields: WorkflowDslField[];
+  stepFields: WorkflowDslField[];
+  workflowFields: WorkflowDslField[];
+}
+
+const llmAgentOnly = ['llm', 'agent'];
+const llmAgentSkillOnly = ['llm', 'agent', 'skill'];
+
+export const WORKFLOW_DSL_MANIFEST: WorkflowDslManifest = {
+  version: '1.0.0',
+  actionKinds: [...ACTION_KINDS],
+  controlFlowTypes: [...CONTROL_FLOW_TYPES],
+  validStepTypes: [...VALID_STEP_TYPES],
+  onErrorValues: [...ON_ERROR_VALUES],
+  exclusiveActionFields: [...ACTION_KINDS, 'type'],
+  stepKinds: [
+    { kind: 'tool', group: 'action', label: 'Tool', description: 'Call one deterministic tool.', primaryFields: ['tool', 'args'] },
+    { kind: 'llm', group: 'action', label: 'LLM', description: 'Single LLM step.', primaryFields: ['llm', 'output_schema', 'context_files', 'allowed_tools'] },
+    { kind: 'skill', group: 'action', label: 'Skill', description: 'Run one SKILL.md workflow agent.', primaryFields: ['skill', 'input', 'maxTurns'] },
+    { kind: 'agent', group: 'action', label: 'Agent', description: 'Run an inline bounded TAOR agent.', primaryFields: ['agent', 'maxTurns', 'done_when', 'output_schema', 'context_files', 'allowed_tools'] },
+    { kind: 'assert', group: 'quality', label: 'Assert', description: 'Halt when a condition is false.', primaryFields: ['condition', 'onFail'] },
+    { kind: 'verify', group: 'quality', label: 'Verify', description: 'Run deterministic checks before continuing.', primaryFields: ['checks', 'onFail'] },
+    { kind: 'set', group: 'control', label: 'Set', description: 'Set workflow variables deterministically.', primaryFields: ['set'] },
+    { kind: 'branch', group: 'control', label: 'Branch', description: 'Route into then/else child steps.', primaryFields: ['condition'], childCollections: ['then', 'else'] },
+    { kind: 'loop', group: 'control', label: 'Loop', description: 'For-each or bounded while loop.', primaryFields: ['over', 'as', 'max_iterations', 'fresh_context'], childCollections: ['do'] },
+    { kind: 'break', group: 'control', label: 'Break', description: 'Exit the nearest (or target) loop.', primaryFields: ['when', 'target'] },
+    { kind: 'continue', group: 'control', label: 'Continue', description: 'Skip to the next iteration of the nearest (or target) loop.', primaryFields: ['when', 'target'] },
+    { kind: 'echo', group: 'control', label: 'Echo', description: 'Deterministically print an interpolated message (no LLM).', primaryFields: ['message'] },
+    { kind: 'pause', group: 'control', label: 'Pause', description: 'Human approval gate.', primaryFields: ['prompt', 'free_text'] },
+  ],
+  commonStepFields: [
+    { name: 'id', type: 'string', ui: 'text', required: true, label: 'id' },
+    { name: 'title', type: 'string', ui: 'text', label: 'title', description: 'Human-readable progress label (supports ${} interpolation); when set, the status line shows it instead of block-relative step numbers.' },
+    { name: 'when', type: 'string', ui: 'text', label: 'when', description: 'Optional execution condition.' },
+    { name: 'onError', type: 'enum', ui: 'select', enum: [...ON_ERROR_VALUES], label: 'onError' },
+    { name: 'recover_hint', type: 'string', ui: 'text', label: 'recover_hint', description: 'Hint for onError=recover.' },
+  ],
+  stepFields: [
+    { name: 'tool', type: 'string', ui: 'text', appliesTo: ['tool'] },
+    { name: 'args', type: 'object', ui: 'json', appliesTo: ['tool'] },
+    { name: 'llm', type: 'string', ui: 'textarea', appliesTo: ['llm'] },
+    { name: 'skill', type: 'string', ui: 'text', appliesTo: ['skill'] },
+    { name: 'agent', type: 'string', ui: 'textarea', appliesTo: ['agent'] },
+    { name: 'input', type: 'string', ui: 'textarea', appliesTo: ['skill'] },
+    { name: 'capture', type: 'object', ui: 'json' },
+    { name: 'maxTurns', type: 'number', ui: 'number', appliesTo: ['llm', 'skill', 'agent'] },
+    { name: 'max_retries', type: 'number', ui: 'number' },
+    { name: 'artifacts', type: 'string[]', ui: 'string[]' },
+    { name: 'condition', type: 'string', ui: 'text', appliesTo: ['assert', 'branch'] },
+    { name: 'onFail', type: 'string', ui: 'textarea', appliesTo: ['assert', 'verify'] },
+    { name: 'set', type: 'object', ui: 'json', required: true, appliesTo: ['set'] },
+    { name: 'checks', type: 'string[]', ui: 'string[]', required: true, appliesTo: ['verify'] },
+    { name: 'over', type: 'string', ui: 'text', appliesTo: ['loop'] },
+    { name: 'as', type: 'string', ui: 'text', appliesTo: ['loop'] },
+    { name: 'max_iterations', type: 'number', ui: 'number', appliesTo: ['loop'] },
+    { name: 'fresh_context', type: 'boolean', ui: 'boolean', appliesTo: ['loop'] },
+    { name: 'prompt', type: 'string', ui: 'textarea', appliesTo: ['pause'] },
+    { name: 'free_text', type: 'enum', ui: 'select', enum: ['halt', 'approve'], appliesTo: ['pause'] },
+    { name: 'target', type: 'string', ui: 'text', appliesTo: ['break', 'continue'], description: 'Target loop id (label semantics; default = nearest loop).' },
+    { name: 'message', type: 'string', ui: 'textarea', required: true, appliesTo: ['echo'] },
+    { name: 'goal_supplement', type: 'boolean', ui: 'boolean', appliesTo: ['tool', 'skill', 'agent', 'llm', 'pause'], description: 'Append this step output to the goal anchor as a user supplement.' },
+    { name: 'done_when', type: 'string', ui: 'text', appliesTo: ['agent'], description: 'Deterministic completion condition (whitelist expression, e.g. fileExists(...)); engine nudges the agent to keep working until it holds.' },
+    { name: 'output_schema', type: 'object', ui: 'json', appliesTo: llmAgentOnly },
+    { name: 'context_files', type: 'object[]', ui: 'object[]', appliesTo: llmAgentOnly },
+    { name: 'allowed_tools', type: 'string[]', ui: 'string[]', appliesTo: llmAgentOnly },
+    { name: 'history_mode', type: 'enum', ui: 'select', enum: ['shared', 'isolated'], appliesTo: llmAgentSkillOnly, description: 'Use shared workflow history or run this llm/agent/skill step in an isolated history (system prompt + current step only).' },
+    // 多模态（视觉）：仅 llm/agent 生效。images 喂图给模型识图/打分（如 illustrate 配图工作流）。
+    { name: 'images', type: 'array', ui: 'json', appliesTo: llmAgentOnly, description: 'Multimodal image inputs (paths/URLs, supports ${} interpolation). Array of strings or { source, detail, max_long_side_pixel }.' },
+    { name: 'image_detail', type: 'enum', ui: 'select', enum: ['low', 'high', 'auto'], appliesTo: llmAgentOnly, description: 'Default vision detail for this step (per-image override allowed inside images[]).' },
+    { name: 'image_max_long_side_pixel', type: 'number', ui: 'number', appliesTo: llmAgentOnly, description: 'Default max long-side pixels for downscaling images before sending.' },
+    { name: 'parse_inline_images', type: 'boolean', ui: 'boolean', appliesTo: llmAgentOnly, description: 'Parse @./img.png or image URLs found in the prompt text.' },
+  ],
+  workflowFields: [
+    { name: 'artifacts', type: 'string[]', ui: 'string[]', label: 'workflow artifacts' },
+    { name: 'self_heal', type: 'object', ui: 'json', label: 'self_heal' },
+  ],
+};