@qwen-code/qwen-code 0.23.2 → 0.23.3

package/chunks/workflow-UHPFALVZ.js

@@ -0,0 +1,1224 @@
+// Force strict mode and setup for ESM
+"use strict";
+import {
+  DEFAULT_MAX_AGENTS_PER_RUN,
+  DEFAULT_STALL_MS,
+  DEFAULT_WORKFLOW_SUBAGENT_MAX_TIME_MINUTES,
+  DEFAULT_WORKFLOW_SUBAGENT_MAX_TURNS,
+  MAX_STALL_ATTEMPTS,
+  MAX_TOKENS_PER_WORKFLOW_ENV,
+  MAX_WORKFLOW_AGENTS_ENV,
+  MAX_WORKFLOW_CONCURRENCY_ENV,
+  MAX_WORKFLOW_STALL_MS_ENV,
+  WORKFLOW_SUBAGENT_MAX_MINUTES_ENV,
+  WORKFLOW_SUBAGENT_MAX_TURNS_ENV,
+  WorkflowBudgetImpl,
+  WorkflowDispatchScheduler,
+  WorkflowExecutionError,
+  WorkflowJournal,
+  WorkflowOrchestrator,
+  compileWorkflowScript,
+  createProductionDispatch,
+  deleteInlineWorkflowScript,
+  describeWorkflowCompileError,
+  extractAndStripMeta,
+  isSymlinkedRoot,
+  persistInlineWorkflowScript,
+  resolveConcurrencyLimit,
+  resolveMaxTokensPerWorkflow,
+  resolveReviewWorkflowLimits,
+  resolveSavedWorkflowScript,
+  writeWorkflowSnapshot
+} from "./chunk-UKZ45TJL.js";
+import {
+  RESUME_ARGS_TOO_LARGE_NOTE,
+  buildFailureLines,
+  buildResumeCall,
+  getRuleDisplayName,
+  getWorkflowTaskMutationKey,
+  hasUninlinableResumeArgs,
+  isTerminalWorkflowStatus,
+  markWorkflowRunPersistenceActive,
+  resolveToolName,
+  tryWithWorkflowTaskMutation
+} from "./chunk-N7VWZDWW.js";
+import "./chunk-GOFAQQZA.js";
+import "./chunk-TWPJO254.js";
+import "./chunk-CQ35AJ4Z.js";
+import "./chunk-65I7S4Z3.js";
+import "./chunk-6HUXPLB5.js";
+import "./chunk-7CLLH5TI.js";
+import "./chunk-XKBFYTCD.js";
+import "./chunk-ZTTC7T4X.js";
+import "./chunk-E4UEO3XM.js";
+import "./chunk-IAEXTMED.js";
+import "./chunk-IRH27ZC2.js";
+import "./chunk-QHWCP53L.js";
+import "./chunk-F53KKZUD.js";
+import "./chunk-O6GEWCJA.js";
+import "./chunk-36HCNKDS.js";
+import "./chunk-6PVPNMXU.js";
+import "./chunk-2SZH22YO.js";
+import "./chunk-DTNV6UZY.js";
+import "./chunk-QJNDUTOL.js";
+import "./chunk-JXNIF2O5.js";
+import "./chunk-NFYEQRLG.js";
+import "./chunk-ELRMZTPF.js";
+import "./chunk-CHEIIBT3.js";
+import "./chunk-PLLIWEM3.js";
+import "./chunk-5GLDOLNQ.js";
+import "./chunk-CH2YDT6X.js";
+import "./chunk-JX6XHPTX.js";
+import "./chunk-ZSTCM3MX.js";
+import "./chunk-MLXTMF7H.js";
+import "./chunk-LILGKQ4B.js";
+import "./chunk-3CZ2BQV6.js";
+import "./chunk-SAH4BD2J.js";
+import "./chunk-CXTPVBFA.js";
+import "./chunk-U7O65WKL.js";
+import "./chunk-S6LOFUVP.js";
+import "./chunk-FN3JNDRU.js";
+import "./chunk-EUURTIV6.js";
+import "./chunk-G6UUOCUT.js";
+import "./chunk-IZ2U57NY.js";
+import "./chunk-NUQ4GK5I.js";
+import "./chunk-K2OJUPOE.js";
+import "./chunk-NAVJD2PQ.js";
+import "./chunk-YBUMTY7B.js";
+import "./chunk-HNLMYDQE.js";
+import "./chunk-QHMLYMMS.js";
+import "./chunk-CFKIH3D3.js";
+import "./chunk-JL6APGBX.js";
+import {
+  createAbortController,
+  createChildAbortController
+} from "./chunk-DJ2GSRLV.js";
+import "./chunk-4ALNJDHL.js";
+import "./chunk-NOO4QFXM.js";
+import "./chunk-KFFCDLKV.js";
+import "./chunk-ZW2EUO2A.js";
+import {
+  WorkflowRunEvent,
+  logWorkflowRun
+} from "./chunk-HBU7EKY4.js";
+import "./chunk-5ETULJLP.js";
+import "./chunk-ZHKTKHMO.js";
+import "./chunk-VGC4I5JJ.js";
+import "./chunk-EDIDYZBT.js";
+import "./chunk-HD7O6WLV.js";
+import {
+  isWithinRoot
+} from "./chunk-J6MB5ZHZ.js";
+import "./chunk-WZAD4ZNJ.js";
+import "./chunk-3FPYT6QC.js";
+import "./chunk-FPGTNKCP.js";
+import "./chunk-TIGXX4PA.js";
+import "./chunk-3UXUOFO6.js";
+import "./chunk-XFFRI3WM.js";
+import "./chunk-ERU3SDXT.js";
+import "./chunk-EWJTAP3Y.js";
+import "./chunk-HHJLM3WQ.js";
+import {
+  stripAnsiAndControl
+} from "./chunk-W5ZQMAEM.js";
+import "./chunk-74TONY4F.js";
+import "./chunk-HUXPEUFL.js";
+import {
+  BaseDeclarativeTool,
+  BaseToolInvocation,
+  ToolDisplayNames,
+  ToolNames
+} from "./chunk-TP6FYVQT.js";
+import "./chunk-ZAFYHRVY.js";
+import "./chunk-TBWQLLFO.js";
+import "./chunk-UKMWZ5NS.js";
+import "./chunk-75DOP5OR.js";
+import "./chunk-DMTGGOSA.js";
+import "./chunk-YQ3U5MUC.js";
+import "./chunk-MATEIJZF.js";
+import {
+  init_esbuild_shims
+} from "./chunk-5O2XNYP6.js";
+import {
+  __name
+} from "./chunk-J2S4EL5Y.js";
+
+// packages/core/src/tools/workflow/workflow.ts
+init_esbuild_shims();
+
+// packages/core/src/agents/runtime/workflow-runner.ts
+init_esbuild_shims();
+import { randomBytes } from "node:crypto";
+var WorkflowRunHandle = class {
+  constructor(runId, budget, registry, controller, scheduler, start, locations = {}) {
+    this.runId = runId;
+    this.budget = budget;
+    this.registry = registry;
+    this.controller = controller;
+    this.scheduler = scheduler;
+    this.scriptPath = locations.scriptPath;
+    this.journalPath = locations.journalPath;
+    this.completion = Promise.resolve().then(start);
+  }
+  static {
+    __name(this, "WorkflowRunHandle");
+  }
+  completion;
+  /**
+   * Where this run's script lives on disk: the file a `{scriptPath}` launch
+   * loaded, or the persisted copy of an inline `{script}`. `undefined` when
+   * an inline script could not be persisted (no `storage`, symlinked root,
+   * write failure) — callers report the run without it rather than naming a
+   * path that does not exist.
+   */
+  scriptPath;
+  /** This run's resume journal, when the config has a `storage` to hold one. */
+  journalPath;
+  abort() {
+    this.controller.abort();
+  }
+  pause() {
+    return this.scheduler.pause();
+  }
+  resume() {
+    return this.scheduler.resume();
+  }
+};
+var WorkflowScriptNotLaunchedError = class extends Error {
+  constructor(detail) {
+    super(
+      `Workflow script is invalid and was not launched:
+${detail}
+
+Workflow scripts must be plain JavaScript \u2014 the usual causes are TypeScript syntax (type annotations, interfaces, generics) and broken string quoting or escaping. Metadata must use literal values.`
+    );
+    this.detail = detail;
+    this.name = "WorkflowScriptNotLaunchedError";
+  }
+  static {
+    __name(this, "WorkflowScriptNotLaunchedError");
+  }
+};
+var WorkflowStartCancelledError = class extends Error {
+  static {
+    __name(this, "WorkflowStartCancelledError");
+  }
+  constructor() {
+    super("Workflow start was cancelled.");
+    this.name = "WorkflowStartCancelledError";
+  }
+};
+var WorkflowRunner = class {
+  static {
+    __name(this, "WorkflowRunner");
+  }
+  static async start(options) {
+    if (options.resumeFromRunId) {
+      const attempt = await tryWithWorkflowTaskMutation(
+        getWorkflowTaskMutationKey(options.config, options.resumeFromRunId),
+        () => this.startClaimed(options)
+      );
+      if (!attempt.acquired) {
+        throw new Error(
+          `Workflow run ${options.resumeFromRunId} is already being modified.`
+        );
+      }
+      return attempt.value;
+    }
+    return this.startClaimed(options);
+  }
+  static async startClaimed(options) {
+    const config = options.config;
+    const runInBackground = options.runInBackground === true;
+    const budget = WorkflowBudgetImpl.fromEnv();
+    const runId = options.resumeFromRunId ?? `wf_${randomBytes(8).toString("hex")}`;
+    const registry = config.getWorkflowRunRegistry?.();
+    let entry;
+    const isCurrentEntry = /* @__PURE__ */ __name(() => registry === void 0 || entry !== void 0 && registry.get(runId) === entry, "isCurrentEntry");
+    const createController = /* @__PURE__ */ __name(() => runInBackground ? createAbortController() : createChildAbortController(options.signal), "createController");
+    const controller = registry ? registry.reserveStart(runId, createController) : createController();
+    const releasePersistenceActivity = markWorkflowRunPersistenceActive(
+      config,
+      runId
+    );
+    const assertStartNotCancelled = /* @__PURE__ */ __name(() => {
+      if (controller.signal.aborted && !options.signal.aborted) {
+        throw new WorkflowStartCancelledError();
+      }
+      if (runInBackground && options.signal.aborted) {
+        throw new WorkflowStartCancelledError();
+      }
+    }, "assertStartNotCancelled");
+    const storage = config.storage;
+    const previousEntry = registry?.get(runId);
+    let journalPath = storage ? storage.getWorkflowRunJournalPath(runId) : void 0;
+    const journal = journalPath ? new WorkflowJournal(journalPath, storage.getWorkflowRunsDir()) : void 0;
+    let script;
+    let scriptPath;
+    let resumeReplay;
+    let persistedInlineScript = false;
+    let callerWasAbortedBeforeStart;
+    let orchestrator;
+    let reviewLimits;
+    try {
+      const loaded = options.scriptPath && options.script === void 0 ? await resolveSavedWorkflowScript(
+        { scriptPath: options.scriptPath },
+        config
+      ) : void 0;
+      script = loaded?.script ?? options.script ?? "";
+      scriptPath = loaded?.scriptPath ?? options.scriptPath;
+      if (loaded && scriptPath && storage) {
+        reviewLimits = await resolveReviewWorkflowLimits(
+          scriptPath,
+          storage.getGeneratedWorkflowsDir(),
+          script
+        );
+      }
+      const workflowName = options.workflowName ?? loaded?.savedWorkflowName ?? registry?.get(runId)?.workflowName;
+      try {
+        compileWorkflowScript(script);
+      } catch (error) {
+        throw new WorkflowScriptNotLaunchedError(
+          describeWorkflowCompileError(
+            error,
+            script.split(/\r\n|[\n\r\u2028\u2029]/).length
+          )
+        );
+      }
+      resumeReplay = options.resumeFromRunId ? await journal?.load() : void 0;
+      assertStartNotCancelled();
+      callerWasAbortedBeforeStart = options.signal.aborted;
+      if (options.script !== void 0 && scriptPath === void 0) {
+        const persisted = await persistInlineWorkflowScript(
+          config,
+          runId,
+          script
+        );
+        scriptPath = persisted ?? void 0;
+        persistedInlineScript = persisted !== null;
+      }
+      if (journal && !await journal.ensureExists()) {
+        journalPath = void 0;
+      }
+      assertStartNotCancelled();
+      const dispatch = options.dispatch ?? createProductionDispatch(
+        config,
+        controller.signal,
+        (outputTokens) => budget.recordSpent(outputTokens),
+        registry ? (emitter2, dispatchId) => isCurrentEntry() ? registry.bridgeApprovalEvents(
+          runId,
+          emitter2,
+          dispatchId,
+          entry
+        ) : () => void 0 : void 0,
+        reviewLimits?.subagent
+      );
+      orchestrator = new WorkflowOrchestrator(dispatch);
+      entry = registry?.register(
+        {
+          runId,
+          toolUseId: options.toolUseId,
+          ...workflowName ? { workflowName } : {},
+          meta: null,
+          status: "running",
+          startTime: Date.now(),
+          outputFile: "",
+          abortController: controller,
+          tokenBudgetTotal: budget.total,
+          script,
+          scriptPath,
+          ...journalPath ? { journalPath } : {},
+          args: options.args,
+          ...options.resumeFromRunId ? {
+            sourceRunId: options.resumeFromRunId,
+            startMode: "retry"
+          } : {},
+          isBackgrounded: runInBackground,
+          resumeInBackground: runInBackground && config.isInteractive?.() === true && config.getExperimentalZedIntegration?.() !== true
+        },
+        controller
+      );
+    } catch (error) {
+      registry?.releaseStart(runId, controller);
+      controller.abort();
+      if (persistedInlineScript && options.resumeFromRunId === void 0) {
+        await deleteInlineWorkflowScript(config, runId);
+      }
+      if (persistedInlineScript && options.resumeFromRunId && previousEntry) {
+        await persistInlineWorkflowScript(config, runId, previousEntry.script);
+      }
+      if (options.resumeFromRunId === void 0) {
+        await journal?.remove();
+      }
+      releasePersistenceActivity();
+      throw error;
+    }
+    const emitUpdate = /* @__PURE__ */ __name(() => {
+      if (!entry || !options.onUpdate || !isCurrentEntry()) return;
+      try {
+        options.onUpdate(entry);
+      } catch {
+      }
+    }, "emitUpdate");
+    const emitter = {
+      phaseStarted: /* @__PURE__ */ __name((title) => {
+        if (!isCurrentEntry()) return;
+        registry?.onPhaseStarted(runId, title);
+        emitUpdate();
+      }, "phaseStarted"),
+      agentDispatched: /* @__PURE__ */ __name(() => {
+        if (!isCurrentEntry()) return;
+        registry?.onAgentDispatched(runId);
+        emitUpdate();
+      }, "agentDispatched"),
+      agentCompleted: /* @__PURE__ */ __name(() => {
+        if (!isCurrentEntry()) return;
+        registry?.onAgentCompleted(runId);
+      }, "agentCompleted"),
+      dispatchQueued: /* @__PURE__ */ __name((event) => {
+        if (!isCurrentEntry()) return;
+        registry?.onDispatchQueued(runId, event);
+        emitUpdate();
+      }, "dispatchQueued"),
+      dispatchStarted: /* @__PURE__ */ __name((dispatchId, startedAt) => {
+        if (!isCurrentEntry()) return;
+        registry?.onDispatchStarted(runId, dispatchId, startedAt);
+        emitUpdate();
+      }, "dispatchStarted"),
+      dispatchSettled: /* @__PURE__ */ __name((dispatchId, error, endedAt) => {
+        if (!isCurrentEntry()) return;
+        registry?.onDispatchSettled(
+          runId,
+          dispatchId,
+          error,
+          endedAt,
+          !runInBackground && options.signal.aborted
+        );
+        emitUpdate();
+      }, "dispatchSettled"),
+      // The registry records this without firing a status update, avoiding a
+      // TUI redraw per line while retaining the real replay timestamp.
+      logAppended: /* @__PURE__ */ __name((line) => {
+        if (!isCurrentEntry()) return;
+        registry?.onLogAppended(runId, line);
+      }, "logAppended"),
+      budgetUpdated: /* @__PURE__ */ __name((spent, total) => {
+        if (!isCurrentEntry()) return;
+        registry?.onBudgetUpdated(runId, spent, total);
+        emitUpdate();
+      }, "budgetUpdated"),
+      resumeRespawn: /* @__PURE__ */ __name((line) => {
+        if (!isCurrentEntry()) return;
+        registry?.onResumeRespawn(runId, line);
+        emitUpdate();
+      }, "resumeRespawn")
+    };
+    const scheduler = new WorkflowDispatchScheduler(
+      reviewLimits?.concurrency ?? resolveConcurrencyLimit(),
+      controller.signal,
+      ({ state }) => {
+        if (!isCurrentEntry()) return;
+        registry?.onDispatchStateChange(runId, state);
+      }
+    );
+    const handle = new WorkflowRunHandle(
+      runId,
+      budget,
+      registry,
+      controller,
+      scheduler,
+      async () => {
+        try {
+          const outcome = await orchestrator.run({
+            script,
+            args: options.args,
+            maxWallClockMs: reviewLimits?.maxWallClockMs,
+            abortOnTimeout: controller,
+            runId,
+            emitter,
+            budget,
+            resolveSavedWorkflow: /* @__PURE__ */ __name((ref) => resolveSavedWorkflowScript(ref, config), "resolveSavedWorkflow"),
+            journal,
+            resumeReplay,
+            scheduler
+          });
+          if (entry) {
+            entry.meta = outcome.meta;
+            if (outcome.meta?.name && entry.description === runId) {
+              entry.description = outcome.meta.name;
+            }
+          }
+          registry?.setRecentLogs(runId, outcome.logs);
+          if (entry && isTerminalWorkflowStatus(entry.status)) {
+            return {
+              ok: false,
+              message: entry.status === "cancelled" ? "Workflow run cancelled." : entry.error ?? "Workflow run failed."
+            };
+          }
+          registry?.complete(runId, outcome.result, Date.now());
+          return { ok: true, outcome };
+        } catch (error) {
+          const details = error instanceof WorkflowExecutionError ? error : void 0;
+          const message = extractErrorMessage(error);
+          if (entry && details?.meta && !entry.meta) entry.meta = details.meta;
+          if (details?.logs) registry?.setRecentLogs(runId, details.logs);
+          if (entry && isTerminalWorkflowStatus(entry.status)) {
+            return {
+              ok: false,
+              message: entry.status === "cancelled" ? "Workflow run cancelled." : entry.error ?? message,
+              details
+            };
+          }
+          if (callerWasAbortedBeforeStart || !runInBackground && options.signal.aborted) {
+            registry?.cancel(runId, Date.now());
+          } else {
+            registry?.fail(runId, message, Date.now());
+          }
+          return { ok: false, message, details };
+        } finally {
+          controller.abort();
+          if (entry && isTerminalWorkflowStatus(entry.status)) {
+            const telemetryEvent = new WorkflowRunEvent({
+              status: entry.status,
+              agents_dispatched: entry.agentsDispatched,
+              agents_completed: entry.agentsCompleted,
+              // Read off the dispatch traces rather than the counters: a
+              // dispatch that failed or replayed from cache still counts as
+              // completed, so without these three a run that lost half its
+              // fan-out and one that lost none report identically.
+              agents_failed: entry.dispatches.reduce(
+                (n, dispatch) => dispatch.status === "failed" ? n + 1 : n,
+                0
+              ),
+              agents_cached: entry.dispatches.reduce(
+                (n, dispatch) => dispatch.status === "cached" ? n + 1 : n,
+                0
+              ),
+              agents_respawned: entry.agentsRespawned ?? 0,
+              phase_count: entry.phases.length,
+              tokens_spent: entry.tokensSpent,
+              duration_ms: (entry.endTime ?? entry.startTime) - entry.startTime
+            });
+            const snapshotPersisted = await writeWorkflowSnapshot(
+              config,
+              entry
+            );
+            if (snapshotPersisted) {
+              registry?.notifySnapshotPersisted(entry.runId);
+            }
+            await journal?.drain();
+            try {
+              logWorkflowRun(config, telemetryEvent);
+            } catch {
+            }
+          }
+          releasePersistenceActivity();
+          registry?.releaseHandle(runId, handle);
+        }
+      },
+      {
+        ...scriptPath ? { scriptPath } : {},
+        ...journalPath ? { journalPath } : {}
+      }
+    );
+    registry?.attachHandle(handle);
+    return handle;
+  }
+};
+function extractErrorMessage(error) {
+  if (error && typeof error === "object" && "message" in error) {
+    const message = error.message;
+    if (typeof message === "string") return message;
+    return String(message);
+  }
+  return String(error);
+}
+__name(extractErrorMessage, "extractErrorMessage");
+
+// packages/core/src/tools/workflow/workflow.ts
+import { promises as fs } from "node:fs";
+import * as path from "node:path";
+var WORKFLOW_PARAM_SCHEMA = {
+  type: "object",
+  properties: {
+    script: {
+      type: "string",
+      description: `JavaScript source of the workflow. Wrapped as an async IIFE. May call the injected globals \`phase(title)\`, \`log(msg)\`, \`agent(prompt, opts?)\`, and read \`args\`. agent() opts: \`{ label?, phase?, schema?, model?, agentType?, isolation?, workingDir?, stallMs? }\`. \`schema\` (JSON Schema object): the subagent must deliver its result by calling \`structured_output\` with arguments matching the schema; agent() resolves to the validated object. After two in-conversation nudges without a valid result, it resolves to null and the failure is recorded as "subagent completed without calling StructuredOutput (after 2 in-conversation nudges)"; check for null. \`agentType\` (string): resolves against the declarative-agents registry (\`.qwen/agents/<name>.md\`, project then user then built-in). Unresolved names make the admitted agent() resolve to null and record "agent({agentType}): agent type 'X' not found"; check for null. \`model\` (string): per-call model override; routes provider correctly via the subagent runtime view. \`isolation\`: \`'worktree'\` provisions a fresh git worktree under \`<projectRoot>/.qwen/worktrees/agent-<7hex>\`; the worktree is auto-removed if no changes, otherwise the path and branch are returned alongside the result. \`'remote'\` makes the admitted agent() resolve to null and records "agent({isolation:'remote'}) is not available in this build" (parity with upstream). isolation=worktree also resolves to null and records a refusal when the parent working tree has uncommitted changes (the subagent would see a stale HEAD). \`workingDir\` (string): pin the subagent to an EXISTING git worktree of this repository that the caller owns \u2014 nothing is created and nothing is removed. Use it when the directory the agent must work in already exists and its uncommitted state is the point (a review worktree, a checkout a previous step provisioned) \u2014 exactly the case isolation cannot serve. Mutually exclusive with \`isolation\`. The path must be a linked worktree of this repository registered via \`git worktree add\` (it may live anywhere on disk) \u2014 the main checkout is not eligible. \`stallMs\` (number, ms): a no-progress watchdog, not a wall-clock cap. The dispatch is aborted and retried (up to ${MAX_STALL_ATTEMPTS} attempts total) after this many milliseconds with no observable subagent progress \u2014 including before the first response arrives; the timer is suspended while a tool is in flight, so a legitimately slow tool is not a stall. Default ${DEFAULT_STALL_MS} (override via \`${MAX_WORKFLOW_STALL_MS_ENV}\`, whole seconds); \`0\` disables the watchdog. Wall time per attempt is bounded separately. Workflow subagents always have SendMessage / Monitor / EnterPlanMode / ExitPlanMode in their disallowed-tool floor regardless of agentType. Concurrency: \`parallel([() => agent(...), ...])\` runs thunks through a shared per-run window (default \`max(2, min(16, cpus-2))\` agents in flight; override via \`${MAX_WORKFLOW_CONCURRENCY_ENV}\`) and resolves to a position-aligned array \u2014 a thunk that throws, or resolves to a non-JSON-serializable value, becomes \`null\` at its index (errors-as-data); parallel() itself rejects on invalid arguments, abort, or a run-level token/agent-cap refusal. \`pipeline(items, ...stages)\` runs each item through the stages (staggered, no inter-stage barrier); an ordinary stage error, \`null\`, or non-JSON-serializable value drops that item to \`null\`, while a run-level refusal rejects the batch. A bare sequential \`await agent()\` follows the same rule: an agent that fails on its own terms resolves to \`null\` there too, so the fan-out and the sequential form never disagree about what a broken agent means. Pass THUNKS to parallel, not eager calls: \`parallel([() => agent(...)])\`, not \`parallel([agent(...)])\`. At most ${DEFAULT_MAX_AGENTS_PER_RUN} agent() calls per run (override via \`${MAX_WORKFLOW_AGENTS_ENV}\`). \`Date.now()\` and \`Math.random()\` both throw \u2014 workflow scripts must be deterministic for resume. \`export const meta = {...}\` declarations are stripped before execution.`
+    },
+    scriptPath: {
+      type: "string",
+      description: "Optional. Absolute path to a workflow `.js` file to load and run instead of inline `script`. Primarily set by the `/<name>` saved-workflow slash command; a tool that generated a script for this run hands you its path the same way. The file must resolve inside a saved-workflow directory (`.qwen/workflows`, `~/.qwen/workflows`) or the generated-scripts root (`$QWEN_CODE_PROJECT_DIR/workflows/generated` \u2014 the per-project runtime dir, not the project tree) \u2014 any other path is refused. Provide exactly ONE of `script` or `scriptPath`. The file is read at execution time, so edits to a saved workflow take effect on the next run. An inline `script` is persisted to `<generated root>/inline/<runId>.js` and that path comes back in the result, so a resume passes the path instead of the source."
+    },
+    args: {
+      description: "Optional structured value bound to the `args` global. Pass actual JSON, not a stringified value."
+    },
+    resumeFromRunId: {
+      type: "string",
+      description: "Optional. Resume a prior workflow run by id (e.g. wf_abc123\u2026). Re-runs the supplied script or returned script path; agent() calls whose rolling prefix-hash (prompt + opts, chained in call order) matches a journaled result are served from cache for the longest unchanged prefix, and the first changed/missing call onward runs live. Pass the `scriptPath` the original run returned and the same `args`. Editing a saved workflow changes future runs too, so copy it for run-specific edits. Replay requires a journal; without one, every agent() call runs live. The journal keys hash each agent() call's prompt and opts, not the script text, so post-processing can change without losing the cache."
+    },
+    run_in_background: {
+      type: "boolean",
+      default: false,
+      description: "Optional. When true, start the workflow under the interactive session and return a run handle immediately. The Background Tasks view can observe, cooperatively pause/resume, or stop it, and completion is delivered to the conversation when the run settles. Interactive TUI only. Defaults to false."
+    }
+  }
+  // `script` is required UNLESS `scriptPath` is supplied; this XOR can't be
+  // expressed as a plain `required` list, so it's enforced in
+  // `validateToolParamValues`. Inline authoring (the LLM path) should always
+  // pass `script`; the `scriptPath` property description states the XOR.
+};
+var WorkflowToolInvocation = class extends BaseToolInvocation {
+  constructor(config, toolOptions, params, workflowName) {
+    super(params);
+    this.config = config;
+    this.toolOptions = toolOptions;
+    this.workflowName = workflowName;
+  }
+  static {
+    __name(this, "WorkflowToolInvocation");
+  }
+  callId;
+  setCallId(callId) {
+    this.callId = callId;
+  }
+  /**
+   * Cache so the transcript header and the approval dialog cannot disagree,
+   * and so an oversized script is scanned once per invocation rather than
+   * once per surface that asks.
+   */
+  metaCache;
+  resolveMeta() {
+    if (this.metaCache === void 0) {
+      this.metaCache = this.params.script ? readMetaForConfirmation(this.params.script) : null;
+    }
+    return this.metaCache;
+  }
+  getDescription() {
+    const meta = this.resolveMeta();
+    if (meta) {
+      return `Run workflow: ${sanitizeLine(meta.name)}`;
+    }
+    if (this.params.scriptPath && this.params.script === void 0) {
+      const kind = isGeneratedWorkflowScriptPath(
+        this.config,
+        this.params.scriptPath
+      ) ? "generated workflow script" : "saved workflow";
+      return `Run ${kind} (${path.basename(this.params.scriptPath)})`;
+    }
+    return `Run a workflow script (${this.params.script?.length ?? 0} chars)`;
+  }
+  toolLocations() {
+    return [];
+  }
+  getDefaultPermission() {
+    return Promise.resolve("ask");
+  }
+  /**
+   * Show what is about to run, and scope the grant that approves it.
+   *
+   * Without this override the base class renders `Confirm WorkflowTool` over
+   * `Run a workflow script (4127 chars)` — a character count standing in for
+   * arbitrary model-authored JavaScript that may fan out to
+   * `DEFAULT_MAX_AGENTS_PER_RUN` subagents, provision git worktrees and spend
+   * an uncapped token budget. The asymmetry is visible within one run: the
+   * subagent approvals this workflow bubbles up each get a full dialog.
+   *
+   * Two properties of the grant matter as much as the disclosure:
+   *
+   *   - An inline `script` can never be pre-approved. It is fresh
+   *     model-authored source every time, so a blanket "always allow" would
+   *     transfer consent from the script the user read to every script the
+   *     model writes afterwards. `hideAlwaysAllow` removes the option and the
+   *     empty `permissionRules` stops `injectPermissionRulesIfMissing` from
+   *     supplying the bare-tool-name rule, which `buildPermissionRules`
+   *     documents as matching *all* invocations.
+   *   - A `scriptPath` names a file on disk that the user chose, so it can be
+   *     pre-approved — but scoped to that path. The rule is built with the
+   *     same helpers the matcher uses so a tool rename moves both sides.
+   */
+  async getConfirmationDetails(_abortSignal) {
+    const meta = this.resolveMeta();
+    const isGeneratedScriptPath = this.params.scriptPath !== void 0 && await isGeneratedWorkflowScriptPathCanonical(
+      this.config,
+      this.params.scriptPath
+    );
+    const isGeneratedInlineScriptPath = this.params.scriptPath !== void 0 && await isWorkflowScriptPathWithinCanonicalRoot(
+      this.params.scriptPath,
+      path.dirname(this.config.storage.getInlineWorkflowScriptPath("wf_0"))
+    );
+    const body = buildConfirmationPrompt(
+      this.params,
+      meta,
+      isGeneratedScriptPath
+    );
+    const banner = resolveUsageBanner(
+      this.config,
+      this.config.getWorkflowRunRegistry?.(),
+      resolveMaxTokensPerWorkflow()
+    );
+    const isInlineScript = this.params.script !== void 0 || isGeneratedInlineScriptPath;
+    const details = {
+      type: "info",
+      title: "Run a dynamic workflow?",
+      prompt: banner ? `${banner}${body}` : body,
+      // The body is a script excerpt and a phase list: rendering it as
+      // Markdown would swallow the very characters the reader needs to see.
+      renderPromptAsPlainText: true,
+      hideAlwaysAllow: isInlineScript,
+      permissionRules: isInlineScript ? [] : [
+        `${getRuleDisplayName(resolveToolName(ToolNames.WORKFLOW))}(scriptPath:${this.params.scriptPath})`
+      ],
+      onConfirm: /* @__PURE__ */ __name(async (_outcome, _payload) => {
+      }, "onConfirm")
+    };
+    return details;
+  }
+  async execute(signal, updateOutput, _shellExecutionConfig) {
+    const runInBackground = this.params.run_in_background === true;
+    if (runInBackground && signal.aborted) {
+      return startCancelledResult();
+    }
+    let handle;
+    try {
+      handle = await WorkflowRunner.start({
+        config: this.config,
+        signal,
+        toolUseId: this.callId,
+        ...this.workflowName ? { workflowName: this.workflowName } : {},
+        script: this.params.script,
+        scriptPath: this.params.scriptPath,
+        args: this.params.args,
+        resumeFromRunId: this.params.resumeFromRunId,
+        dispatch: this.toolOptions.dispatch,
+        runInBackground,
+        onUpdate: !runInBackground && updateOutput ? (entry) => safeEmitUpdate(updateOutput, entry) : void 0
+      });
+    } catch (error) {
+      if (error instanceof WorkflowStartCancelledError || runInBackground && signal.aborted) {
+        return startCancelledResult();
+      }
+      if (error instanceof WorkflowScriptNotLaunchedError) {
+        return {
+          llmContent: [{ text: error.message }],
+          returnDisplay: error.message,
+          error: {
+            message: error.message,
+            type: "invalid_tool_params" /* INVALID_TOOL_PARAMS */
+          }
+        };
+      }
+      throw error;
+    }
+    if (runInBackground) {
+      const status = handle.registry?.get(handle.runId)?.status ?? "running";
+      const usageBanner = resolveUsageBanner(
+        this.config,
+        handle.registry,
+        handle.budget.total
+      );
+      return {
+        workflowRunId: handle.runId,
+        ...handle.scriptPath ? { scriptPath: handle.scriptPath } : {},
+        ...handle.journalPath ? { journalPath: handle.journalPath } : {},
+        llmContent: [
+          {
+            text: buildBackgroundStartText(handle, status)
+          }
+        ],
+        returnDisplay: usageBanner + `Workflow ${handle.runId} started in the background (status: ${status}). Use Background Tasks to observe, cooperatively pause/resume, or stop it.`
+      };
+    }
+    const settlement = await handle.completion;
+    if (settlement.ok) {
+      const { outcome } = settlement;
+      const usageBanner = resolveUsageBanner(
+        this.config,
+        handle.registry,
+        handle.budget.total
+      );
+      const llmText = safeStringifyResult(outcome.result);
+      const displayJson = safeStringifyDisplayPayload({
+        runId: outcome.runId,
+        ...outcome.meta ? { meta: outcome.meta } : {},
+        phases: outcome.phases,
+        logs: outcome.logs,
+        result: outcome.result,
+        // P5: surface the per-run token total in the terminal display so
+        // the user sees actual usage even without opening the dialog.
+        // P5 R1 (#11): align with `buildLivePhaseTreeDisplay` — include
+        // tokens whenever ANY usage is reported OR a cap is set, not
+        // only when spend > 0. A capped-but-zero-spend run still wants
+        // the cap visible so the user sees the gate engaged.
+        ...handle.budget.spent() > 0 || handle.budget.total !== null ? {
+          tokens: {
+            spent: handle.budget.spent(),
+            total: handle.budget.total
+          }
+        } : {}
+      });
+      return {
+        ...handle.scriptPath ? { scriptPath: handle.scriptPath } : {},
+        ...handle.journalPath ? { journalPath: handle.journalPath } : {},
+        // Two parts: the script's return value is left exactly as it was,
+        // and the run handle follows as a separate part. Note what this does
+        // NOT mean — `convertToFunctionResponse` joins the text parts with a
+        // newline, so the model reads `<return value>\n--- workflow run ---…`
+        // as one string. Keeping them apart is still what makes the return
+        // value untouched at the tool boundary, keeps `returnDisplay` clean,
+        // and gives the per-tool head/tail truncator a distinct trailer part.
+        // The scheduler-wide persistence gate may still fold both parts into
+        // one head-only preview when their combined text crosses its limit.
+        llmContent: [
+          { text: llmText },
+          { text: buildRunTrailer(this.config, handle, this.params.args) }
+        ],
+        returnDisplay: usageBanner + "```json\n" + displayJson + "\n```"
+      };
+    } else {
+      const { message, details } = settlement;
+      const { phases, logs, meta } = details ?? {};
+      const cancelled = handle.registry?.get(handle.runId)?.status === "cancelled";
+      const failureText = cancelled ? "Workflow cancelled." : `Workflow failed: ${clampForDisplay(
+        sanitizeBlock(message),
+        TRAILER_ERROR_CHARS
+      )}`;
+      const trailer = buildRunTrailer(
+        this.config,
+        handle,
+        this.params.args,
+        logs,
+        !cancelled
+      );
+      const display = `${cancelled ? "Workflow cancelled." : `Workflow failed: ${message}`}
+
+${safeStringifyDisplayPayload(
+        {
+          runId: handle.runId,
+          ...meta ? { meta } : {},
+          phases: phases ?? [],
+          logs: logs ?? []
+        }
+      )}`;
+      return {
+        ...handle.scriptPath ? { scriptPath: handle.scriptPath } : {},
+        ...handle.journalPath ? { journalPath: handle.journalPath } : {},
+        // The failure message alone names what threw but not where to look:
+        // the logs the runtime already mirrored (`dispatch failed (result not
+        // consumed)` and friends) only reached `returnDisplay`, which the
+        // scheduler overwrites with `error.message` — so the model never saw
+        // them. Mirror the two content parts into the error message because
+        // that is the only text the non-timeout scheduler branch delivers.
+        llmContent: [{ text: failureText }, { text: trailer }],
+        returnDisplay: display,
+        // FIX-10 (REUSE-I1): use the standard ToolErrorType.EXECUTION_FAILED
+        // code so error routing / dashboards can classify workflow failures
+        // the same way as other execution-time tool errors.
+        error: {
+          message: `${failureText}
+${trailer}`,
+          type: "execution_failed" /* EXECUTION_FAILED */
+        }
+      };
+    }
+  }
+};
+var TRAILER_LOG_LINES = 20;
+var TRAILER_LOG_LINE_CHARS = 400;
+var TRAILER_ERROR_CHARS = 4e3;
+function buildRunTrailer(config, handle, args, logs, includeResume = true) {
+  const lines = [
+    "--- workflow run ---",
+    `runId: ${sanitizeLine(handle.runId)}`
+  ];
+  if (handle.scriptPath) {
+    lines.push(`script: ${sanitizeLine(handle.scriptPath)}`);
+  }
+  if (handle.journalPath) {
+    lines.push(`journal: ${sanitizeLine(handle.journalPath)}`);
+  }
+  const entry = handle.registry?.get(handle.runId);
+  let failedCount = 0;
+  if (entry) {
+    const countByStatus = /* @__PURE__ */ __name((status) => entry.dispatches.reduce(
+      (n, dispatch) => dispatch.status === status ? n + 1 : n,
+      0
+    ), "countByStatus");
+    const respawned = entry.agentsRespawned ?? 0;
+    failedCount = countByStatus("failed");
+    lines.push(
+      `agents: ${entry.dispatches.length} dispatched` + (respawned > 0 ? ` (${respawned} re-ran from a prior run)` : "") + ` \xB7 ${countByStatus("completed")} completed \xB7 ${countByStatus("cached")} cached \xB7 ${failedCount} failed \xB7 ${countByStatus("cancelled")} cancelled`
+    );
+  }
+  const spent = handle.budget.spent();
+  lines.push(
+    handle.budget.total === null ? `tokens: ${spent} spent (no cap)` : `tokens: ${spent} / ${handle.budget.total} spent`
+  );
+  const failures = entry ? buildFailureLines(entry) : [];
+  if (failures.length > 0 && entry) {
+    lines.push(
+      `failures (${failedCount}):`,
+      ...failures.map(
+        (line) => clampForDisplay(sanitizeLine(line), TRAILER_LOG_LINE_CHARS)
+      )
+    );
+  }
+  const resume = buildResumeCall({
+    runId: handle.runId,
+    scriptPath: handle.scriptPath,
+    args
+  });
+  if (resume && includeResume) {
+    const pathAdvice = entry?.workflowName || !isGeneratedWorkflowScriptPath(config, handle.scriptPath) ? "this reads the saved workflow; copy it before making a run-specific change" : "edit that generated copy first if the script needs to change";
+    const journalAdvice = handle.journalPath ? "the journal replays the longest unchanged prefix of agent() calls, and the first changed call onward runs live" : "no journal was written for this run, so every agent() call runs live";
+    lines.push(`resume: ${resume} \u2014 ${pathAdvice}; ${journalAdvice}.`);
+    if (hasUninlinableResumeArgs({ runId: handle.runId, args })) {
+      lines.push(RESUME_ARGS_TOO_LARGE_NOTE);
+    }
+  }
+  const tail = (logs ?? []).slice(-TRAILER_LOG_LINES);
+  if (tail.length > 0) {
+    lines.push(
+      `logs (last ${tail.length}):`,
+      ...tail.map(
+        (line) => clampForDisplay(sanitizeLine(line), TRAILER_LOG_LINE_CHARS)
+      )
+    );
+  }
+  return lines.join("\n");
+}
+__name(buildRunTrailer, "buildRunTrailer");
+function buildBackgroundStartText(handle, status) {
+  const lines = [
+    "Workflow started in background.",
+    `Run ID: ${sanitizeLine(handle.runId)}`,
+    `Status: ${sanitizeLine(status)}`
+  ];
+  if (handle.scriptPath) {
+    lines.push(`Script file: ${sanitizeLine(handle.scriptPath)}`);
+  }
+  if (handle.journalPath) {
+    lines.push(`Journal: ${sanitizeLine(handle.journalPath)}`);
+  }
+  lines.push(
+    `You will be notified when it settles. Use /workflows ${sanitizeLine(handle.runId)} for the live phase tree.`
+  );
+  return lines.join("\n");
+}
+__name(buildBackgroundStartText, "buildBackgroundStartText");
+function startCancelledResult() {
+  return {
+    llmContent: "Workflow was cancelled before it could start.",
+    returnDisplay: "Workflow cancelled."
+  };
+}
+__name(startCancelledResult, "startCancelledResult");
+function buildLivePhaseTreeDisplay(entry) {
+  const payload = {
+    runId: entry.runId,
+    ...entry.meta ? { meta: entry.meta } : {},
+    status: entry.status,
+    currentPhase: entry.currentPhase,
+    phases: entry.phases,
+    agentsDispatched: entry.agentsDispatched,
+    agentsCompleted: entry.agentsCompleted
+  };
+  if (entry.tokensSpent > 0 || entry.tokenBudgetTotal !== null) {
+    payload["tokens"] = {
+      spent: entry.tokensSpent,
+      total: entry.tokenBudgetTotal
+    };
+  }
+  try {
+    return "```json\n" + JSON.stringify(payload, null, 2) + "\n```";
+  } catch {
+    return `Workflow ${entry.runId} \u2014 ${entry.status} \u2014 ${entry.phases.length} phase(s)`;
+  }
+}
+__name(buildLivePhaseTreeDisplay, "buildLivePhaseTreeDisplay");
+function resolveUsageBanner(config, registry, budgetTotal) {
+  if (!registry) return "";
+  if (config.getSkipWorkflowUsageWarning?.()) return "";
+  if (!registry.shouldShowUsageWarning()) return "";
+  return buildUsageBanner(budgetTotal);
+}
+__name(resolveUsageBanner, "resolveUsageBanner");
+var CONFIRM_SCRIPT_EXCERPT_CHARS = 1200;
+var CONFIRM_ARGS_CHARS = 300;
+var CONFIRM_MAX_PHASES = 12;
+function sanitizeLine(text) {
+  return stripAnsiAndControl(text);
+}
+__name(sanitizeLine, "sanitizeLine");
+function sanitizeBlock(text) {
+  return text.replace(/\t/g, "  ").split("\n").map((line) => stripAnsiAndControl(line)).join("\n");
+}
+__name(sanitizeBlock, "sanitizeBlock");
+function clampForDisplay(text, max) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}
+\u2026 (${text.length - max} more characters)`;
+}
+__name(clampForDisplay, "clampForDisplay");
+function readMetaForConfirmation(script) {
+  try {
+    return extractAndStripMeta(script).meta;
+  } catch {
+    return null;
+  }
+}
+__name(readMetaForConfirmation, "readMetaForConfirmation");
+function isGeneratedWorkflowScriptPath(config, scriptPath) {
+  return isWithinRoot(scriptPath, config.storage.getGeneratedWorkflowsDir());
+}
+__name(isGeneratedWorkflowScriptPath, "isGeneratedWorkflowScriptPath");
+async function isGeneratedWorkflowScriptPathCanonical(config, scriptPath) {
+  return isWorkflowScriptPathWithinCanonicalRoot(
+    scriptPath,
+    config.storage.getGeneratedWorkflowsDir()
+  );
+}
+__name(isGeneratedWorkflowScriptPathCanonical, "isGeneratedWorkflowScriptPathCanonical");
+async function isWorkflowScriptPathWithinCanonicalRoot(scriptPath, root) {
+  if (await isSymlinkedRoot(root)) return false;
+  let realScriptPath;
+  try {
+    realScriptPath = await fs.realpath(scriptPath);
+  } catch {
+    return isWithinRoot(scriptPath, root);
+  }
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(root);
+  } catch {
+    realRoot = path.resolve(root);
+  }
+  return isWithinRoot(realScriptPath, realRoot);
+}
+__name(isWorkflowScriptPathWithinCanonicalRoot, "isWorkflowScriptPathWithinCanonicalRoot");
+function buildConfirmationPrompt(params, meta, isGeneratedScriptPath) {
+  const lines = [];
+  if (meta) {
+    lines.push(`Workflow: ${sanitizeLine(meta.name)}`);
+    lines.push(sanitizeLine(meta.description));
+  } else if (params.scriptPath) {
+    const label = isGeneratedScriptPath ? "Generated workflow script" : "Saved workflow";
+    lines.push(`${label}: ${sanitizeLine(params.scriptPath)}`);
+  } else {
+    lines.push("Workflow: (the script declares no meta block)");
+  }
+  if (meta?.phases?.length) {
+    const shown = meta.phases.slice(0, CONFIRM_MAX_PHASES);
+    lines.push("", `Phases (${meta.phases.length}):`);
+    shown.forEach((phase, i) => {
+      const detail = phase.detail ? ` \u2014 ${sanitizeLine(phase.detail)}` : "";
+      lines.push(`  ${i + 1}. ${sanitizeLine(phase.title)}${detail}`);
+    });
+    if (meta.phases.length > shown.length) {
+      lines.push(`  \u2026 and ${meta.phases.length - shown.length} more`);
+    }
+  }
+  if (params.scriptPath && meta) {
+    lines.push("", `Loaded from: ${sanitizeLine(params.scriptPath)}`);
+  }
+  if (params.resumeFromRunId) {
+    lines.push("", `Resuming run: ${sanitizeLine(params.resumeFromRunId)}`);
+  }
+  if (params.args !== void 0) {
+    let rendered;
+    try {
+      rendered = JSON.stringify(params.args) ?? String(params.args);
+    } catch {
+      rendered = "(args are not JSON-serializable)";
+    }
+    lines.push(
+      "",
+      `Args: ${clampForDisplay(sanitizeLine(rendered), CONFIRM_ARGS_CHARS)}`
+    );
+  }
+  if (params.script) {
+    lines.push(
+      "",
+      "Script:",
+      clampForDisplay(
+        sanitizeBlock(params.script),
+        CONFIRM_SCRIPT_EXCERPT_CHARS
+      )
+    );
+  }
+  return lines.join("\n");
+}
+__name(buildConfirmationPrompt, "buildConfirmationPrompt");
+function buildUsageBanner(total) {
+  if (total === null) {
+    return `> Workflows have no per-run token cap. Set \`${MAX_TOKENS_PER_WORKFLOW_ENV}=<n>\` (env) for a soft cap. Suppress this notice with \`skipWorkflowUsageWarning: true\` in settings.
+
+`;
+  }
+  return `> Workflow token cap is ${total} (per \`${MAX_TOKENS_PER_WORKFLOW_ENV}\`). Suppress this notice with \`skipWorkflowUsageWarning: true\` in settings.
+
+`;
+}
+__name(buildUsageBanner, "buildUsageBanner");
+function safeEmitUpdate(updateOutput, entry) {
+  if (!updateOutput || !entry) return;
+  try {
+    updateOutput(buildLivePhaseTreeDisplay(entry));
+  } catch {
+  }
+}
+__name(safeEmitUpdate, "safeEmitUpdate");
+function safeStringifyResult(result) {
+  if (result === void 0) return "(workflow returned no value)";
+  if (typeof result === "string") return result;
+  try {
+    return JSON.stringify(result, null, 2);
+  } catch {
+    return `(workflow returned a non-JSON-serializable value of type ${typeof result})`;
+  }
+}
+__name(safeStringifyResult, "safeStringifyResult");
+function safeStringifyDisplayPayload(payload) {
+  try {
+    return JSON.stringify(payload, null, 2);
+  } catch {
+    if (payload && typeof payload === "object") {
+      const sanitized = {};
+      for (const [key, value] of Object.entries(payload)) {
+        try {
+          JSON.stringify(value);
+          sanitized[key] = value;
+        } catch {
+          sanitized[key] = `(non-JSON-serializable value of type ${typeof value})`;
+        }
+      }
+      try {
+        return JSON.stringify(sanitized, null, 2);
+      } catch {
+      }
+    }
+    return "(display payload not JSON-serializable)";
+  }
+}
+__name(safeStringifyDisplayPayload, "safeStringifyDisplayPayload");
+var WORKFLOW_TOOL_DESCRIPTION = `Execute a workflow script that orchestrates subagents deterministically.
+
+**Only on an explicit request**
+
+Do not call this tool unless the user has asked for multi-agent orchestration. A run can dispatch up to ${DEFAULT_MAX_AGENTS_PER_RUN} subagents and spend tokens accordingly, so that scale has to be requested rather than inferred. It counts as requested when any of these holds:
+
+- The user's message contains the word \`workflow\`; a system reminder confirms it when it does.
+- The user asked for orchestration in their own words \u2014 run a workflow, fan out agents, orchestrate this with subagents.
+- A skill or slash command the user invoked instructs you to use this tool.
+- The user named a saved workflow to run, reached through \`workflow('<name>')\` or \`scriptPath\`.
+- The user asked to resume or continue an earlier run, which is \`resumeFromRunId\`.
+
+Otherwise do not call it, however well the task would parallelize. Do the work in the main loop, or spawn a single subagent for one self-contained piece. When a workflow would genuinely be the better tool, say in one sentence what it would fan out over and roughly how many agents that is, then let the user decide \u2014 and mention that including the word \`workflow\` next time skips the ask.
+
+**What a workflow is for**
+
+Reach for one to be comprehensive (decompose the work and cover every part in parallel), to be confident (independent perspectives and adversarial checks before an answer is committed to), or to take on scale a single context cannot hold \u2014 migrations, audits, broad sweeps. The script is where that structure is encoded: what fans out, what verifies, what synthesizes. Parallelism on its own is not a reason; work that is already one short sequence of edits belongs in the main loop.
+
+**Runtime** \u2014 see the \`script\` parameter for the detailed authoring contract.
+
+\`phase(title)\`, \`log(msg)\`, \`agent(prompt, opts?)\`, \`parallel(thunks)\`, \`pipeline(items, ...stages)\`, \`workflow(nameOrRef, args?)\`, plus the \`args\` and \`budget\` globals. \`workflow()\` runs a saved workflow inline under this run's caps and nests one level only \u2014 a workflow reached through \`workflow()\` cannot call \`workflow()\` itself, and doing so throws. Saved workflows are \`<name>.js\` files under \`<projectRoot>/.qwen/workflows\` (project scope, also surfaced as \`/<name>\` slash commands) or \`~/.qwen/workflows\` (user scope, lower precedence when both define the same name); \`workflow('<name>')\` resolves against those two directories, while \`scriptPath\` takes an absolute path to a script inside either of them or inside the generated-scripts root (\`$QWEN_CODE_PROJECT_DIR/workflows/generated\` \u2014 the per-project runtime dir, not the project tree \u2014 where a tool emitting a one-run script writes it; never a slash command, never resolvable by name); a path outside those roots is refused. Default \`max(2, min(16, cpus-2))\` agents in flight per run (\`${MAX_WORKFLOW_CONCURRENCY_ENV}\`), up to ${DEFAULT_MAX_AGENTS_PER_RUN} agents total (\`${MAX_WORKFLOW_AGENTS_ENV}\`), under a 30-minute wall-clock cap per run (\`QWEN_CODE_MAX_WORKFLOW_SECONDS\`) \u2014 a fan-out near the agent cap will not fit inside the default cap. Each subagent attempt is separately capped at ${DEFAULT_WORKFLOW_SUBAGENT_MAX_TURNS} turns (\`${WORKFLOW_SUBAGENT_MAX_TURNS_ENV}\`) and ${DEFAULT_WORKFLOW_SUBAGENT_MAX_TIME_MINUTES} minutes (\`${WORKFLOW_SUBAGENT_MAX_MINUTES_ENV}\`) \u2014 raise them for legitimately long work. \`agent()\` resolves to \`null\` when that admitted agent fails on its own \u2014 including turn/time caps, model or setup errors, missing structured output, and exhausted stall retries \u2014 and it does so for a bare \`await agent()\` exactly as it does inside \`parallel()\`/\`pipeline()\`, so check for \`null\` wherever you read a result. Call-shape validation failures \u2014 such as an empty prompt, an unsupported option combination, or an invalid option value \u2014 reject a bare call; inside \`parallel()\`/\`pipeline()\`, the surrounding ordinary thunk or stage rejection becomes a position-aligned \`null\`. Run-level rejections no later call could survive \u2014 the token budget, the ${DEFAULT_MAX_AGENTS_PER_RUN}-agent cap, and cancellation \u2014 throw and end a \`parallel()\`/\`pipeline()\` batch. An admitted agent that fails and settles to \`null\` still counts as dispatched and is named, with its error, in the run's failures list; a \`null\` returned by an ordinary thunk or stage is not an agent dispatch. A per-run output-token cap may also be in effect: read \`budget.total\` (\`null\` = uncapped) before committing to a large fan-out, because once the cap is reached every further \`agent()\` call is refused. Per-call \`agent({ schema, agentType, model, isolation: 'worktree', workingDir, stallMs })\` covers structured-output contracts, declarative-agent selection, model override, git-worktree-isolated subagents, pinning an agent to a caller-owned worktree, and the no-progress stall watchdog (\`stallMs: 0\` disables it). \`resumeFromRunId\` resumes a prior run \u2014 agent() calls whose rolling prefix-hash matches the journal are served from cache for the longest unchanged prefix. Every run hands back its runId, the script's path on disk (an inline script is persisted, so a resume edits that file rather than re-sending the source) and its journal path; the journal holds one result line per completed agent, so read it before diagnosing an empty or surprising result. Runs appear in the background-tasks view and the \`/workflows\` dialog (live phase tree, token usage, cooperative pause/resume, cancel); \`run_in_background: true\` returns a run handle immediately in the interactive TUI and delivers completion through the conversation. Scripts run in a node:vm sandbox with no filesystem or shell access \u2014 all I/O happens through the spawned agents.
+
+**Scout first, then orchestrate**
+
+The strongest pattern is hybrid: discover the work list in the main loop (list the files, scope the diff, read the failing test), then hand that list to a workflow. You do not need to know the shape of the work before the task \u2014 only before the orchestration step. When the work has distinct phases, run several small workflows across turns and read each result before choosing the next, rather than authoring one large script that runs unattended.
+
+Common single-phase shapes: understand (parallel readers over subsystems, merged into one map), design (independent approaches, judged, then synthesized), review (dimensions, find, verify each finding), research (broad sweep, deep read, synthesis), migrate (discover sites, transform each under \`isolation: 'worktree'\`, verify).
+
+**Default to \`pipeline()\`**
+
+\`pipeline()\` runs each item through every stage independently \u2014 item A can be in stage 3 while item B is still in stage 1 \u2014 so wall-clock is the slowest single chain. \`parallel()\` is a barrier: it waits for every thunk before anything moves on, so it costs the slowest item of every stage.
+
+A barrier is right only when a stage genuinely needs cross-item context: deduplicating or merging across the full result set before expensive downstream work, exiting early when the total count is zero, or a prompt that compares one finding against all the others. It is not justified by needing to flatten, map, or filter between stages (do that inside a pipeline stage), by two stages being conceptually separate, or by the code reading more tidily. Smell test: \`parallel()\` \u2192 a pure transform \u2192 \`parallel()\` is a pipeline someone wrote with an unnecessary barrier. When in doubt, \`pipeline()\`.
+
+**Verify before believing**
+
+A subagent's answer is a claim, not a result. For findings that matter, spawn independent verifiers prompted to *refute*, and drop what a majority refutes. When a claim can be wrong in several different ways, give each verifier a distinct lens (correctness, security, performance, does it actually reproduce) \u2014 diversity catches what repetition cannot. For a wide solution space, generate several independent attempts, judge them in parallel, and synthesize from the winner while grafting the best ideas from the rest.
+
+**Converge deliberately**
+
+For discovery of unknown size, keep running finders until some number of consecutive rounds turn up nothing new; a fixed round count stops partway into the tail. Deduplicate each round against everything already seen, never against only what survived judging \u2014 otherwise rejected findings reappear every round and the loop never terminates. A closing pass that asks what is still missing (a search angle never run, a claim never verified, a file never read) usually produces the next round of real work.
+
+**Report honestly**
+
+Scale the fleet to what was actually asked: a quick check gets a few agents and one verification pass; an explicit request to be thorough or exhaustive earns a larger pool and a multi-vote adversarial round. Whenever a run bounds its own coverage \u2014 top-N, sampling, no retry \u2014 \`log()\` what was dropped. Silent truncation reads as full coverage, which is worse than a smaller honest result.
+
+These shapes are a starting point, not a menu; compose the harness the task actually needs.`;
+var WorkflowTool = class extends BaseDeclarativeTool {
+  constructor(config, toolOptions = {}) {
+    super(
+      ToolNames.WORKFLOW,
+      ToolDisplayNames.WORKFLOW,
+      WORKFLOW_TOOL_DESCRIPTION,
+      "other" /* Other */,
+      WORKFLOW_PARAM_SCHEMA,
+      /* isOutputMarkdown */
+      true,
+      /* canUpdateOutput */
+      true
+    );
+    this.config = config;
+    this.toolOptions = toolOptions;
+  }
+  static {
+    __name(this, "WorkflowTool");
+  }
+  buildSessionOwnedBackground(params, workflowName) {
+    const validationError = this.validateToolParams(params);
+    if (validationError) {
+      throw new Error(validationError);
+    }
+    if (!this.config.getWorkflowRunRegistry().hasCompletionCallback()) {
+      throw new Error(
+        "WorkflowTool: session-owned background runs require an active workflow completion channel."
+      );
+    }
+    return new WorkflowToolInvocation(
+      this.config,
+      this.toolOptions,
+      { ...params, run_in_background: true },
+      workflowName
+    );
+  }
+  validateToolParamValues(params) {
+    const hasScript = typeof params.script === "string" && params.script.length > 0;
+    const hasPath = typeof params.scriptPath === "string" && params.scriptPath.length > 0;
+    if (!hasScript && !hasPath) {
+      return "WorkflowTool: provide `script` (inline source) or `scriptPath` (a workflow script file).";
+    }
+    if (hasScript && hasPath) {
+      return "WorkflowTool: provide exactly one of `script` or `scriptPath`, not both.";
+    }
+    if (params.resumeFromRunId !== void 0 && !/^wf_[0-9a-f]+$/.test(params.resumeFromRunId)) {
+      return "WorkflowTool: `resumeFromRunId` must match the generated id format `wf_<hex>`.";
+    }
+    if (params.run_in_background === true) {
+      if (!this.config.isInteractive() || this.config.getExperimentalZedIntegration?.() === true) {
+        return "WorkflowTool: `run_in_background` is available only in the interactive TUI.";
+      }
+      if (!this.config.getWorkflowRunRegistry().hasCompletionCallback()) {
+        return "WorkflowTool: `run_in_background` requires an active workflow completion channel.";
+      }
+    }
+    return null;
+  }
+  createInvocation(params) {
+    return new WorkflowToolInvocation(this.config, this.toolOptions, params);
+  }
+};
+export {
+  WorkflowTool
+};
+/**
+ * @license
+ * Copyright 2026 Qwen Team
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * @license
+ * Copyright 2025 Qwen
+ * SPDX-License-Identifier: Apache-2.0
+ */