@hncode/hncode 0.2.0 → 0.3.0

package/src/tasks-browser.js

@@ -0,0 +1,279 @@
+// TasksBrowser - the full-screen background-task panel (/tasks), mirroring
+// kimi-code's TasksBrowserApp.
+//
+// Layout:
+//   TASK BROWSER  filter=ALL  2 running  3 total
+//   +-- Tasks [all] --+  +-- Detail ----------+
+//   | > bash-x  run   |  | Task ID:  ...      |
+//   |   agent-y compl  |  +-- Preview Output -+
+//   |                  |  | <live tail>       |
+//   +------------------+  +-------------------+
+//   Up/Down select  Enter/O output  S stop  R refresh  Tab filter  Q/Esc close
+//
+// This module is pure rendering + key handling. It returns ACTION STRINGS to the
+// caller instead of touching the task store, so all state stays in one place.
+import { C } from './colors.js';
+import { visualWidth } from './term.js';
+import { STATUS_LABEL } from './agent-task.js';
+
+const ELLIPSIS = '\u2026';
+const ESC = '\x1b';
+// visWidth() counts ANSI bytes, so strip escapes before measuring: every
+// string here carries colour codes and would otherwise measure far too wide.
+function visWidth(s) { return visualWidth(String(s).replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')); }
+const MIN_WIDTH = 48;
+const MIN_HEIGHT = 10;
+const LIST_COL_MIN = 28;
+const LIST_COL_MAX = 44;
+const LIST_COL_RATIO = 0.32;
+
+export function statusColorToken(status) {
+  if (status === 'running') return C.green;
+  if (status === 'completed') return C.gray;
+  return C.red;
+}
+
+function truncateToWidth(s, width) {
+  const str = String(s);
+  let out = '';
+  let n = 0;
+  let i = 0;
+  while (i < str.length) {
+    if (str[i] === ESC) {
+      const m = /^\x1b\[[0-9;?]*[a-zA-Z]/.exec(str.slice(i));
+      if (m) { out += m[0]; i += m[0].length; continue; }
+    }
+    const cp = str.codePointAt(i);
+    const ch = String.fromCodePoint(cp);
+    const cw = visWidth(ch);
+    if (n + cw > width - 1) {
+      // Pad after the ellipsis so the row is EXACTLY `width` columns: a short
+      // row breaks the frame's right border alignment.
+      const used = n + 1;
+      return out + ELLIPSIS + ' '.repeat(Math.max(0, width - used));
+    }
+    n += cw;
+    out += ch;
+    i += cp > 0xffff ? 2 : 1;
+  }
+  return out;
+}
+
+function padToWidth(s, width) {
+  const w = visWidth(s);
+  if (w === width) return s;
+  if (w > width) return truncateToWidth(s, width);
+  return s + ' '.repeat(width - w);
+}
+
+function fitExactly(line, width) {
+  let s = String(line);
+  if (visWidth(s) > width) s = truncateToWidth(s, width);
+  return padToWidth(s, width) + C.reset;
+}
+
+function singleLine(t) { return String(t == null ? '' : t).replace(/\s+/g, ' ').trim(); }
+
+function relativeTime(ts) {
+  if (!ts || !Number.isFinite(ts) || ts <= 0) return '';
+  const d = Math.floor(Math.max(0, Date.now() - ts) / 1000);
+  if (d < 60) return 'just now';
+  const m = Math.floor(d / 60);
+  if (m < 60) return m + 'm ago';
+  const h = Math.floor(m / 60);
+  if (h < 24) return h + 'h ago';
+  return Math.floor(h / 24) + 'd ago';
+}
+
+export function visibleTasks(tasks, filter) {
+  if (filter === 'active') return tasks.filter((t) => t.status === 'running');
+  return tasks.slice();
+}
+
+function countByStatus(tasks) {
+  const c = { running: 0, completed: 0, failed: 0 };
+  for (const t of tasks) {
+    if (t.status === 'running') c.running++;
+    else if (t.status === 'completed') c.completed++;
+    else c.failed++;
+  }
+  return c;
+}
+
+// A framed box: top/bottom rules + side walls, exactly width x height cells.
+function renderFrame(title, content, width, height) {
+  if (height < 2 || width < 4) return Array.from({ length: height }, () => ' '.repeat(width));
+  const innerW = width - 2;
+  const innerH = height - 2;
+  const t = String(title || '');
+  const topMid = t
+    ? C.border + '\u2500 ' + C.cyan + C.bold + t + C.reset + C.border + ' '
+      + '\u2500'.repeat(Math.max(0, innerW - visWidth(t) - 3)) + C.reset
+    : C.border + '\u2500'.repeat(innerW) + C.reset;
+  const lines = [C.border + '\u250c' + topMid + C.border + '\u2510' + C.reset];
+  for (let i = 0; i < innerH; i++) {
+    lines.push(C.border + '\u2502' + C.reset + fitExactly(content[i] ?? '', innerW) + C.border + '\u2502' + C.reset);
+  }
+  lines.push(C.border + '\u2514' + '\u2500'.repeat(innerW) + '\u2518' + C.reset);
+  return lines;
+}
+
+export function renderTasksBrowser(state, cols, rows) {
+  if (cols < MIN_WIDTH || rows < MIN_HEIGHT) {
+    const lines = [fitExactly(C.red + 'Terminal too small (need >= ' + MIN_WIDTH + ' x ' + MIN_HEIGHT + ')' + C.reset, cols)];
+    for (let i = 1; i < rows; i++) lines.push(' '.repeat(cols));
+    return lines;
+  }
+  const visible = visibleTasks(state.tasks, state.filter);
+  const counts = countByStatus(visible);
+
+  const segs = [C.cyan + C.bold + ' TASK BROWSER ' + C.reset, C.gray + ' filter=' + (state.filter === 'all' ? 'ALL' : 'ACTIVE') + ' ' + C.reset];
+  if (counts.running) segs.push(C.green + ' ' + counts.running + ' running ' + C.reset);
+  if (counts.completed) segs.push(C.gray + ' ' + counts.completed + ' completed ' + C.reset);
+  if (counts.failed) segs.push(C.red + ' ' + counts.failed + ' interrupted ' + C.reset);
+  segs.push(C.gray + ' ' + visible.length + ' total ' + C.reset);
+  const header = fitExactly(segs.join(''), cols);
+
+  const key = (s) => C.cyan + C.bold + s + C.reset;
+  const dim = (s) => C.gray + s + C.reset;
+  let footer;
+  if (state.pendingStop) {
+    footer = fitExactly(' ' + C.orange + C.bold + 'Stop' + C.reset + ' ' + C.white + state.pendingStop + C.reset + '? '
+      + key('Y') + ' ' + dim('confirm') + '  ' + key('N') + dim('/') + key('esc') + ' ' + dim('cancel') + ' ', cols);
+  } else {
+    const parts = [
+      ' ' + key('\u2191\u2193') + ' ' + dim('select'),
+      key('Enter/O') + ' ' + dim('output'),
+      key('S') + ' ' + dim('stop'),
+      key('R') + ' ' + dim('refresh'),
+      key('Tab') + ' ' + dim('filter'),
+      key('Q/Esc') + ' ' + dim('close') + ' ',
+    ];
+    const left = parts.join('  ');
+    const flash = state.flash ? C.orange + ' ' + state.flash + ' ' + C.reset : '';
+    const total = visWidth(left) + visWidth(flash);
+    footer = total <= cols ? left + ' '.repeat(cols - total) + flash : fitExactly(left, cols);
+  }
+
+  const bodyH = rows - 2;
+  const listW = Math.max(LIST_COL_MIN, Math.min(LIST_COL_MAX, Math.floor(cols * LIST_COL_RATIO)));
+  const rightW = cols - listW;
+
+  // left: task list
+  const listInnerH = Math.max(0, bodyH - 2);
+  const listInnerW = listW - 2;
+  let listLines;
+  if (!visible.length) {
+    listLines = [C.gray + (state.filter === 'active' ? 'No active tasks. Tab = show all.' : 'No background tasks in this session.') + C.reset];
+  } else {
+    listLines = visible.map((t, i) => {
+      const selected = i === state.selectedIndex;
+      const ptr = selected ? C.cyan + '\u276f ' + C.reset : '  ';
+      const idCol = t.kind === 'agent' ? C.green : t.kind === 'question' ? C.orange : C.blue;
+      const idText = selected ? idCol + C.bold + t.taskId + C.reset : idCol + t.taskId + C.reset;
+      const pad = ' '.repeat(Math.max(0, 20 - visWidth(t.taskId)));
+      const badge = statusColorToken(t.status) + (STATUS_LABEL[t.status] || t.status) + C.reset;
+      const prefix = ptr + idText + pad + ' ' + badge;
+      const budget = Math.max(0, listInnerW - visWidth(prefix) - 1);
+      if (budget < 4) return fitExactly(prefix, listInnerW);
+      const desc = singleLine(t.description) || singleLine(t.command) || '(no description)';
+      return fitExactly(prefix + ' ' + C.white + truncateToWidth(desc, budget) + C.reset, listInnerW);
+    });
+  }
+  while (listLines.length < listInnerH) listLines.push('');
+  const listFrame = renderFrame('Tasks [' + state.filter + ']', listLines.slice(0, listInnerH), listW, bodyH);
+
+  // right: detail + preview
+  const detailH = Math.min(Math.max(10, Math.min(Math.floor(bodyH * 0.4), bodyH - 5)), Math.max(3, bodyH - 3));
+  const previewH = bodyH - detailH;
+  const rightInnerW = rightW - 2;
+  const task = visible[state.selectedIndex];
+
+  const detailLines = [];
+  if (!task) {
+    detailLines.push(C.gray + 'Select a task from the list.' + C.reset);
+  } else {
+    const label = (s) => C.gray + s.padEnd(14) + C.reset;
+    const val = (s) => C.white + String(s) + C.reset;
+    detailLines.push(label('Task ID:') + val(task.taskId));
+    detailLines.push(label('Kind:') + val(task.kind));
+    detailLines.push(label('Status:') + statusColorToken(task.status) + (STATUS_LABEL[task.status] || task.status) + C.reset);
+    detailLines.push(label('Description:') + val(singleLine(task.description) || '-'));
+    if (task.kind === 'process') {
+      if (task.command && task.command !== task.description) detailLines.push(label('Command:') + val(singleLine(task.command)));
+      if (task.pid) detailLines.push(label('Pid:') + C.gray + task.pid + C.reset);
+      if (task.exitCode != null) detailLines.push(label('Exit code:') + C.gray + task.exitCode + C.reset);
+    }
+    if (task.kind === 'agent') {
+      if (task.agentId) detailLines.push(label('Agent ID:') + val(task.agentId));
+      if (task.subagentType) detailLines.push(label('Agent type:') + val(task.subagentType));
+      if (task.model) detailLines.push(label('Model:') + val(task.model));
+      if (task.thinkingEffort) detailLines.push(label('Effort:') + val(task.thinkingEffort));
+    }
+    if (task.kind === 'question') {
+      detailLines.push(label('Questions:') + C.gray + task.questionCount + C.reset);
+      if (task.toolCallId) detailLines.push(label('Tool call:') + C.gray + task.toolCallId + C.reset);
+    }
+    const timing = task.status === 'running'
+      ? 'running ' + relativeTime(task.startedAt)
+      : (task.endedAt ? 'finished ' + relativeTime(task.endedAt) : '');
+    if (timing) detailLines.push(label('Time:') + C.gray + timing + C.reset);
+    if (task.stopReason) detailLines.push(label('Reason:') + C.gray + singleLine(task.stopReason) + C.reset);
+  }
+  while (detailLines.length < Math.max(0, detailH - 2)) detailLines.push('');
+  const detailFrame = renderFrame('Detail', detailLines, rightW, detailH);
+
+  const previewInnerH = Math.max(0, previewH - 2);
+  let previewLines;
+  const tail = task ? String(task.output || '') : '';
+  if (!task) previewLines = [C.gray + 'No task selected.' + C.reset];
+  else if (!tail.length) previewLines = [C.gray + '[no output captured]' + C.reset];
+  else previewLines = tail.replace(/\r\n/g, '\n').split('\n').slice(-previewInnerH).map((l) => C.gray + truncateToWidth(l, rightInnerW) + C.reset);
+  while (previewLines.length < previewInnerH) previewLines.push('');
+  const previewFrame = renderFrame('Preview Output', previewLines, rightW, previewH);
+
+  const out = [header];
+  for (let i = 0; i < bodyH; i++) {
+    const right = i < detailH ? (detailFrame[i] ?? ' '.repeat(rightW)) : (previewFrame[i - detailH] ?? ' '.repeat(rightW));
+    out.push((listFrame[i] ?? ' '.repeat(listW)) + right);
+  }
+  out.push(footer);
+  return out;
+}
+
+// Handle one key. Returns an ACTION STRING for the caller (all state stays in
+// the caller): 'close' | 'refresh' | 'toggleFilter' | 'openOutput' |
+// 'requestStop' | 'confirmStop' | 'cancelStop' | 'select' | null
+export function handleTasksBrowserKey(state, t) {
+  const visible = visibleTasks(state.tasks, state.filter);
+  const ch = t.ch;
+  if (state.pendingStop) {
+    if (ch === 'y' || ch === 'Y') { state.pendingStop = null; return 'confirmStop'; }
+    state.pendingStop = null;
+    return 'cancelStop';
+  }
+  if (t.key === 'escape' || ch === 'q' || ch === 'Q') return 'close';
+  if (t.key === 'up' || ch === 'k') {
+    if (!visible.length) return null;
+    state.selectedIndex = Math.max(0, state.selectedIndex - 1);
+    return 'select';
+  }
+  if (t.key === 'down' || ch === 'j') {
+    if (!visible.length) return null;
+    state.selectedIndex = Math.min(visible.length - 1, state.selectedIndex + 1);
+    return 'select';
+  }
+  if (t.key === 'home') { state.selectedIndex = 0; return 'select'; }
+  if (t.key === 'end') { state.selectedIndex = Math.max(0, visible.length - 1); return 'select'; }
+  if (t.key === 'tab') return 'toggleFilter';
+  if (ch === 'r' || ch === 'R') return 'refresh';
+  if (ch === 's' || ch === 'S') {
+    const task = visible[state.selectedIndex];
+    if (!task) return null;
+    if (task.status !== 'running') return 'stopIgnored';
+    state.pendingStop = task.taskId;
+    return 'requestStop';
+  }
+  if (ch === 'o' || ch === 'O' || t.key === 'enter') return 'openOutput';
+  return null;
+}

package/src/tools/agent-swarm.js

@@ -0,0 +1,203 @@
+// AgentSwarm tool — launch many subagents from ONE prompt template, mirroring
+// kimi-code's AgentSwarm.
+//
+//   prompt_template: 'Review {{item}} for regressions.'
+//   items: ['src/a.ts', 'src/b.ts']        -> two subagents
+//
+// Enforced rules (same as kimi):
+//   * at least 2 items unless resume_agent_ids is given
+//   * whenever items are present, prompt_template is required and must contain
+//     the {{item}} placeholder
+//   * the filled-in prompts must be distinct
+//   * at most 128 items
+//   * swarm runs are queued, so a large swarm does not spawn 128 processes at once
+
+import { spec as agentSpec } from './agent.js';
+import { SUBAGENT_TYPES, DEFAULT_SUBAGENT_TYPE } from '../subagent-types.js';
+import { createTask, appendTaskOutput, settleTask } from '../agent-task.js';
+
+export const PROMPT_TEMPLATE_PLACEHOLDER = '{{item}}';
+export const MAX_AGENT_SWARM_SUBAGENTS = 128;
+// How many subagents run at once. kimi queues launches automatically; we use a
+// small fixed window so a 128-item swarm cannot stampede the machine.
+const SWARM_CONCURRENCY = 4;
+
+// Validate and expand the swarm request. Returns { prompts } or { error }.
+export function planSwarm(args) {
+  const items = Array.isArray(args.items) ? args.items.map((s) => String(s).trim()).filter(Boolean) : [];
+  const template = args.prompt_template == null ? '' : String(args.prompt_template);
+  const resumeMap = (args.resume_agent_ids && typeof args.resume_agent_ids === 'object')
+    ? Object.entries(args.resume_agent_ids).map(([id, p]) => [String(id).trim(), String(p).trim()])
+    : [];
+
+  if (items.length === 0 && resumeMap.length === 0) {
+    return { error: 'Error: provide at least 2 items, or a resume_agent_ids map.' };
+  }
+  if (items.length === 1 && resumeMap.length === 0) {
+    return { error: 'Error: at least 2 items are required (a single task should use the Agent tool instead).' };
+  }
+  if (items.length > MAX_AGENT_SWARM_SUBAGENTS) {
+    return { error: `Error: at most ${MAX_AGENT_SWARM_SUBAGENTS} subagents per swarm (got ${items.length}).` };
+  }
+  if (items.length > 0 && !template.trim()) {
+    return { error: 'Error: `prompt_template` is required whenever `items` are present.' };
+  }
+  if (items.length > 0 && !template.includes(PROMPT_TEMPLATE_PLACEHOLDER)) {
+    return { error: `Error: \`prompt_template\` must contain the ${PROMPT_TEMPLATE_PLACEHOLDER} placeholder.` };
+  }
+  const prompts = items.map((it) => template.split(PROMPT_TEMPLATE_PLACEHOLDER).join(it));
+  const uniq = new Set(prompts);
+  if (uniq.size !== prompts.length) {
+    return { error: 'Error: two items expand to the same prompt — make each item distinct.' };
+  }
+  return { prompts, resumeMap };
+}
+
+export const spec = {
+  name: 'AgentSwarm',
+  description: `Launch multiple subagents from one prompt template, existing agent resumes, or both.
+
+Use AgentSwarm when many subagents should run the same kind of task over different inputs. The placeholder is exactly \`${PROMPT_TEMPLATE_PLACEHOLDER}\`. For example, with \`prompt_template\` set to \`Review ${PROMPT_TEMPLATE_PLACEHOLDER} for likely regressions.\` and \`items\` set to \`["src/a.ts", "src/b.ts"]\`, AgentSwarm launches two new subagents with those two concrete prompts. For a few differently-shaped tasks, make separate \`Agent\` calls in one message instead.
+
+Use \`resume_agent_ids\` to continue subagents that already exist from earlier work, such as ones that failed or timed out: map each agent id to the prompt for that resumed subagent (usually \`continue\` if no extra information is needed). You may combine \`resume_agent_ids\` with \`items\` in the same call. Do not duplicate resumed work in \`items\`.
+
+Each of these is enforced — a violation is rejected before any subagent starts: provide at least 2 \`items\` unless you pass \`resume_agent_ids\`; whenever \`items\` are present, \`prompt_template\` is required and must contain \`${PROMPT_TEMPLATE_PLACEHOLDER}\`; and the filled-in prompts must be distinct.
+
+Use enough subagents to keep the work focused and parallel. AgentSwarm supports up to ${MAX_AGENT_SWARM_SUBAGENTS} subagents, and launches are queued automatically, so it is safe to split large tasks into many clear, independent items.
+
+When NOT to use AgentSwarm:
+- Never call this on your own initiative. It requires the same explicit permission as \`Agent\`: the user, or the applicable AGENTS.md / project instructions, must have asked for sub-agents, delegation, or parallel agent work. Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do NOT count as permission.
+- Do not use it for two or three differently-shaped tasks: use separate \`Agent\` calls instead, which can run in parallel in one message.
+- Do not use it to fan out work you could finish yourself in a few steps.
+
+If \`AgentSwarm\` is called, that call must be the only tool call in the response.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      description: { type: 'string', description: 'Short description for the whole swarm.' },
+      subagent_type: { type: 'string', description: `Subagent type used for every new subagent spawned from items; defaults to ${DEFAULT_SUBAGENT_TYPE}.` },
+      prompt_template: { type: 'string', description: `Prompt template for each subagent. The ${PROMPT_TEMPLATE_PLACEHOLDER} placeholder is replaced with each item value.` },
+      items: {
+        type: 'array',
+        items: { type: 'string' },
+        maxItems: MAX_AGENT_SWARM_SUBAGENTS,
+        description: `Values used to fill ${PROMPT_TEMPLATE_PLACEHOLDER}. Each item launches one new subagent.`,
+      },
+      fork: { type: 'boolean', default: false, description: "Fork the current context for every item-spawned subagent: each starts with a snapshot of this agent's completed conversation history." },
+      resume_agent_ids: { type: 'object', description: 'Map of existing subagent agent_id to the prompt used to resume that subagent. Resumed subagents are launched before new item-based subagents.' },
+      model: { type: 'string', description: 'Which model to run the item-spawned subagents on, or "primary" for the current model.' },
+    },
+    required: ['description'],
+  },
+
+  async execute(args, ctx) {
+    const description = String(args.description || '').trim();
+    if (!description) return 'Error: `description` is required.';
+
+    const plan = planSwarm(args);
+    if (plan.error) return plan.error;
+
+    const type = SUBAGENT_TYPES[args.subagent_type] ? args.subagent_type : DEFAULT_SUBAGENT_TYPE;
+
+    // Build the work list: resumes first (kimi launches them before new items).
+    const jobs = [
+      ...plan.resumeMap.map(([agentId, prompt]) => ({ kind: 'resume', agentId, prompt })),
+      ...plan.prompts.map((prompt) => ({ kind: 'new', prompt })),
+    ];
+
+    // The swarm runs in the FOREGROUND by default, like Bash and Agent: this call
+    // does not return until every subagent has finished, so the turn waits for the
+    // result. The task record exists from the start so Ctrl+B can hand the run to
+    // the background mid-flight (the TUI's ctrl+b calls `ctx._foreground.detach`).
+    const task = createTask(ctx, 'agent', {
+      description: `${description} (${jobs.length} subagents)`,
+      subagentType: type,
+      model: args.model || '',
+      detached: false,
+    });
+
+    // Run with a bounded window. Each job appends its verdict to the task output
+    // as it finishes, so TaskOutput shows partial progress.
+    const results = new Array(jobs.length).fill(null);
+    let next = 0;
+    const worker = async () => {
+      for (;;) {
+        const i = next++;
+        if (i >= jobs.length) return;
+        const job = jobs[i];
+        try {
+          const subArgs = {
+            prompt: job.prompt,
+            description: `${description} #${i + 1}`,
+            ...(job.kind === 'resume' ? { resume: job.agentId } : { subagent_type: type }),
+            ...(args.model ? { model: args.model } : {}),
+            ...(args.fork === true && job.kind === 'new' ? { fork: true } : {}),
+          };
+          const out = await agentSpec.execute(subArgs, { ...ctx, _progressTag: `#${i + 1}` });
+          // `agentSpec.execute` returns `agent_id: <id>\n\n<handoff>`. The swarm's
+          // caller wants the handoff, and the id is only useful for a later
+          // `resume`; keep it on one labelled line rather than letting it lead the
+          // block, so the reported text is what each subagent actually produced.
+          const raw = String(out);
+          const m = /^agent_id:\s*(\S+)\s*\n+([\s\S]*)$/.exec(raw);
+          const body = (m ? m[2] : raw).trim();
+          const head = `--- #${i + 1}${job.kind === 'resume' ? ` (resumed ${job.agentId})` : ''}${m ? ` [${m[1]}]` : ''} ---`;
+          results[i] = `${head}\n${body}`;
+        } catch (e) {
+          results[i] = `--- #${i + 1} ---\n[error: ${e.message}]`;
+        }
+        // Stream progress into the task output so a long swarm is inspectable.
+        const done = results.filter((r) => r !== null).length;
+        appendTaskOutput(task, `[${done}/${jobs.length}] finished\n`);
+      }
+    };
+    const runAll = Promise.all(Array.from({ length: Math.min(SWARM_CONCURRENCY, jobs.length) }, worker));
+
+    // Ctrl+B hands the still-running swarm to the background. The task already
+    // exists, so detaching only flips who waits on `runAll`: the turn stops
+    // blocking and keeps the normal progress lines flowing into the task output.
+    let detached = false;
+    if (ctx) {
+      ctx._foreground = {
+        kind: 'AgentSwarm',
+        description: `${description} (${jobs.length} subagents)`,
+        detach: () => {
+          if (detached) return task.taskId;
+          detached = true;
+          task.detached = true;
+          if (ctx._foreground && ctx._foreground.detach) ctx._foreground = null;
+          void (async () => {
+            try {
+              await runAll;
+              settleTask(task, 'completed');
+              appendTaskOutput(task, results.join('\n\n'));
+            } catch (e) {
+              settleTask(task, 'failed', { stopReason: e.message });
+            }
+            if (typeof ctx._onBackgroundTaskDone === 'function') ctx._onBackgroundTaskDone(task);
+          })();
+          return task.taskId;
+        },
+      };
+    }
+
+    try {
+      await runAll;
+    } catch (e) {
+      if (ctx && ctx._foreground && ctx._foreground.detach) ctx._foreground = null;
+      // Detached: the background continuation owns the outcome now.
+      if (detached) return `Moved to background as task #${task.taskId}. It keeps running; inspect with TaskList / TaskOutput {task_id: "${task.taskId}"}.`;
+      settleTask(task, 'failed', { stopReason: e.message });
+      return `Error: swarm failed: ${e.message}`;
+    }
+    if (ctx && ctx._foreground && ctx._foreground.detach) ctx._foreground = null;
+    if (detached) {
+      return `Moved to background as task #${task.taskId}. It keeps running; inspect with TaskList / TaskOutput {task_id: "${task.taskId}"}.`;
+    }
+    settleTask(task, 'completed');
+    appendTaskOutput(task, results.join('\n\n'));
+    if (typeof ctx._onBackgroundTaskDone === 'function') ctx._onBackgroundTaskDone(task);
+
+    return `Swarm finished: ${jobs.length} subagent(s).\n\n${results.join('\n\n')}`;
+  },
+};