@worca/ui 0.21.0 → 0.23.0

package/server/integrations/commands/fleet.js

@@ -0,0 +1,266 @@
+/**
+ * Fleet-scoped chat commands.
+ *
+ *   /fleets                      list active fleets (running + paused)
+ *   /fleet [id|last]             show one fleet's status
+ *   /fleet-children <id|last>    per-child status table
+ *   /fleet-halt <id>             graceful halt (in-flight finish naturally)
+ *   /fleet-stop <id> [--force]   hard stop (SIGTERM + control file), with confirmation
+ *   /fleet-pause <id>            pause every in-flight child
+ *   /fleet-resume <id>           resume paused/interrupted children, re-dispatch failed
+ *
+ * Authz: every handler runs *after* the inbound allowlist gate in
+ * index.js — same gate that already guards /pause, /resume, /stop.
+ *
+ * Destructive actions (/fleet-stop) require a confirmation token written
+ * into chat_context with a 60s expiry. The token mechanism is local to
+ * this module so we don't bloat chat_context.js's public API for what is
+ * really a per-command UX concern.
+ *
+ * @module commands/fleet
+ */
+
+import { statusEmoji } from './global.js';
+
+const CONFIRM_TTL_MS = 60_000;
+
+/** Pick the most recent fleet from a list (created_at desc). */
+function pickLatest(fleets) {
+  if (!fleets || fleets.length === 0) return null;
+  return [...fleets].sort((a, b) => {
+    const at = a.created_at || '';
+    const bt = b.created_at || '';
+    return bt.localeCompare(at);
+  })[0];
+}
+
+async function fetchFleets(restClient) {
+  const resp = await restClient.get('/api/fleet-runs');
+  const data = resp.data;
+  if (!data || data.ok === false) return [];
+  return Array.isArray(data.fleets) ? data.fleets : [];
+}
+
+async function fetchFleetById(restClient, id) {
+  const resp = await restClient.get(
+    `/api/fleet-runs/${encodeURIComponent(id)}`,
+  );
+  const data = resp.data;
+  if (!data || data.ok === false) return null;
+  return data.fleet ?? null;
+}
+
+/**
+ * Resolve "last" / short-suffix / full-id into a fleet manifest object.
+ * Returns { fleet, disambig } — exactly one of them populated.
+ */
+async function resolveFleet(restClient, idArg, command) {
+  if (!idArg || idArg === 'last') {
+    const all = await fetchFleets(restClient);
+    const latest = pickLatest(all);
+    if (!latest) return { disambig: 'No fleets found.' };
+    return { fleet: latest };
+  }
+  if (idArg.startsWith('f_')) {
+    const fleet = await fetchFleetById(restClient, idArg);
+    if (!fleet) return { disambig: `Fleet \`${idArg}\` not found.` };
+    return { fleet };
+  }
+  // Short suffix match — `4318dbf9` matches `f_..._4318dbf9`.
+  const all = await fetchFleets(restClient);
+  const matches = all.filter((f) => f.fleet_id?.endsWith(idArg));
+  if (matches.length === 0) {
+    return { disambig: `No fleet matches \`${idArg}\`.` };
+  }
+  if (matches.length > 1) {
+    const lines = matches.map((f) => `   • \`${f.fleet_id}\` — ${f.status}`);
+    return {
+      disambig:
+        `Multiple fleets match \`${idArg}\`:\n${lines.join('\n')}\n\n` +
+        `Usage: /${command} <fleet_id>`,
+    };
+  }
+  return { fleet: matches[0] };
+}
+
+function fmtFleetSummary(fleet) {
+  const id = fleet.fleet_id;
+  const title = fleet.work_request?.title || '(no title)';
+  const status = fleet.status || 'unknown';
+  const reason = fleet.halt_reason ? ` (${fleet.halt_reason})` : '';
+  const childCount = fleet.children_count ?? fleet.children?.length ?? 0;
+  const completed = (fleet.children || []).filter(
+    (c) => c.status === 'completed',
+  ).length;
+  const failed = (fleet.children || []).filter(
+    (c) => c.status === 'failed' || c.status === 'setup_failed',
+  ).length;
+  const parts = [`${statusEmoji(status)} **Fleet:** \`${id}\``];
+  parts.push(`   **Title:** ${title}`);
+  parts.push(`   **Status:** ${status}${reason}`);
+  parts.push(
+    `   **Children:** ${completed}/${childCount} completed${failed ? `, ${failed} failed` : ''}`,
+  );
+  if (fleet.cost_usd != null) {
+    parts.push(`   **Cost:** $${Number(fleet.cost_usd).toFixed(2)}`);
+  }
+  return parts.join('\n');
+}
+
+function fmtChildrenTable(fleet) {
+  const children = fleet.children || [];
+  if (children.length === 0) return '   (no children dispatched yet)';
+  return children
+    .map((c) => {
+      const project =
+        (c.project_path || '').split('/').filter(Boolean).pop() || '(?)';
+      const st = c.status || 'unknown';
+      const rid = c.run_id ? ` \`${c.run_id}\`` : '';
+      return `   ${statusEmoji(st)} **${project}** — ${st}${rid}`;
+    })
+    .join('\n');
+}
+
+/**
+ * Creates handlers for the /fleet… commands.
+ *
+ * The chatContext is used for /fleet-stop confirmation tokens — we store
+ * a `pending_fleet_stop = { fleet_id, expires_at }` shape on the chat key
+ * and clear it after the confirming message comes in.
+ *
+ * @param {{ chatContext, restClient }} deps
+ */
+export function createFleetHandlers({ chatContext, restClient }) {
+  async function fleets() {
+    const all = await fetchFleets(restClient);
+    const active = all.filter((f) => {
+      const s = f.status;
+      return s === 'running' || s === 'paused' || s === 'resuming';
+    });
+    if (active.length === 0) return 'No active fleets.';
+    const lines = active.map((f) => {
+      const childCount = f.children_count ?? f.children?.length ?? 0;
+      const title = f.work_request?.title || '(no title)';
+      const reason = f.halt_reason ? ` (${f.halt_reason})` : '';
+      return [
+        `${statusEmoji(f.status)} **Fleet:** \`${f.fleet_id}\``,
+        `   **Title:** ${title}`,
+        `   **Status:** ${f.status}${reason} | **Children:** ${childCount}`,
+      ].join('\n');
+    });
+    return `Active fleets:\n\n${lines.join('\n')}`;
+  }
+
+  async function fleet(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet');
+    if (resolved.disambig) return resolved.disambig;
+    return fmtFleetSummary(resolved.fleet);
+  }
+
+  async function fleetChildren(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-children');
+    if (resolved.disambig) return resolved.disambig;
+    const f = resolved.fleet;
+    return `Children of \`${f.fleet_id}\`:\n\n` + fmtChildrenTable(f);
+  }
+
+  async function fleetHalt(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-halt');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.delete(
+      `/api/fleet-runs/${encodeURIComponent(id)}`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to halt fleet \`${id}\` (${resp.status}).`;
+    }
+    return `\u{1F7E1} Halted fleet \`${id}\`.\nIn-flight children will finish naturally.`;
+  }
+
+  async function fleetStop(chatKey, args) {
+    const isForce = args.includes('--force') || args.includes('YES');
+    const cleanArgs = args.filter((a) => a !== '--force' && a !== 'YES');
+    const resolved = await resolveFleet(restClient, cleanArgs[0], 'fleet-stop');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+
+    const ctx = chatContext.get(chatKey) || {};
+    const pending = ctx.pending_fleet_stop;
+
+    if (!isForce) {
+      // Issue / refresh a confirmation token.
+      chatContext.set(chatKey, {
+        pending_fleet_stop: {
+          fleet_id: id,
+          expires_at: new Date(Date.now() + CONFIRM_TTL_MS).toISOString(),
+        },
+      });
+      const child_count =
+        resolved.fleet.children_count ?? (resolved.fleet.children || []).length;
+      return (
+        `⚠ \`/fleet-stop\` will SIGTERM every in-flight child of fleet \`${id}\` (${child_count} children).\n` +
+        `Confirm with \`/fleet-stop ${id} YES\` within 60s, or pass \`--force\`.`
+      );
+    }
+
+    // --force or YES path. Either matches a fresh confirmation token, or
+    // the caller is bypassing the gate entirely with --force.
+    if (
+      args.includes('YES') &&
+      (!pending ||
+        pending.fleet_id !== id ||
+        new Date(pending.expires_at).getTime() < Date.now())
+    ) {
+      return `Confirmation expired or never issued for fleet \`${id}\`. Re-run \`/fleet-stop ${id}\` to get a fresh token.`;
+    }
+
+    chatContext.set(chatKey, { pending_fleet_stop: null });
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/stop`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to stop fleet \`${id}\` (${resp.status}).`;
+    }
+    const count = resp.data.stopped_count ?? '?';
+    return `\u{1F534} Stopped fleet \`${id}\`. SIGTERM sent to ${count} child(ren).`;
+  }
+
+  async function fleetPause(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-pause');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/pause`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to pause fleet \`${id}\` (${resp.status}).`;
+    }
+    const count = resp.data.paused_count ?? '?';
+    return `\u{1F7E1} Paused fleet \`${id}\`. ${count} child(ren) will pause at their next iteration boundary.`;
+  }
+
+  async function fleetResume(_chatKey, args) {
+    const resolved = await resolveFleet(restClient, args[0], 'fleet-resume');
+    if (resolved.disambig) return resolved.disambig;
+    const id = resolved.fleet.fleet_id;
+    const resp = await restClient.post(
+      `/api/fleet-runs/${encodeURIComponent(id)}/resume`,
+    );
+    if (!resp.data || resp.data.ok === false) {
+      return `Failed to resume fleet \`${id}\` (${resp.status}).`;
+    }
+    const continued = resp.data.continued_count ?? 0;
+    const redispatched = resp.data.redispatched_count ?? 0;
+    return `\u{1F7E2} Resumed fleet \`${id}\`. ${continued} continued in-place, ${redispatched} re-dispatched.`;
+  }
+
+  return {
+    fleets,
+    fleet,
+    'fleet-children': fleetChildren,
+    'fleet-halt': fleetHalt,
+    'fleet-stop': fleetStop,
+    'fleet-pause': fleetPause,
+    'fleet-resume': fleetResume,
+  };
+}

package/server/integrations/commands/global.js

@@ -115,6 +115,15 @@ const HELP_TEXT = `/start \u2014 show your chat ID
 /resume [run_id] \u2014 resume paused run
 /stop [run_id] \u2014 stop run
 
+Fleet commands (cross-project):
+/fleets \u2014 list active fleets
+/fleet [id|last] \u2014 fleet status
+/fleet-children <id|last> \u2014 per-child status
+/fleet-halt <id> \u2014 graceful halt (in-flight finish naturally)
+/fleet-stop <id> [--force] \u2014 SIGTERM every in-flight child (confirms first)
+/fleet-pause <id> \u2014 pause every in-flight child
+/fleet-resume <id> \u2014 resume paused/interrupted, re-dispatch failed
+
 Commands with [run_id] auto-resolve to the active run if omitted.
 Use \`*suffix\` to match by ending, e.g. /status \`*2db5\`
 Project commands require /use first.`;

package/server/integrations/commands/parser.js

@@ -1,6 +1,9 @@
 const MENTION_RE = /^@\S+$/i;
 
-const COMMAND_RE = /^\/([a-z_]+)(?:@\S+)?$/i;
+// Allow `-` so namespaced commands like /fleet-halt and /fleet-resume parse.
+// Hyphens must appear inside the name, not lead or trail. Backwards-compatible
+// — every existing underscore-only command still matches.
+const COMMAND_RE = /^\/([a-z_][a-z0-9_-]*)(?:@\S+)?$/i;
 
 /**
  * Parses a chat message into a command name and argument list.

package/server/integrations/index.js

@@ -12,6 +12,7 @@ import { createWebhookOutAdapter } from './adapters/webhook_out.js';
 import { createAllowlistGuard } from './allowlist.js';
 import { createChatContext } from './chat_context.js';
 import { createControlHandlers } from './commands/control.js';
+import { createFleetHandlers } from './commands/fleet.js';
 import { createGlobalHandlers } from './commands/global.js';
 import { parseCommand } from './commands/parser.js';
 import { createProjectHandlers } from './commands/project.js';
@@ -65,10 +66,12 @@ export function createIntegrations({
   });
   const projectHandlers = createProjectHandlers({ chatContext, restClient });
   const controlHandlers = createControlHandlers({ chatContext, restClient });
+  const fleetHandlers = createFleetHandlers({ chatContext, restClient });
   const allHandlers = {
     ...globalHandlers,
     ...projectHandlers,
     ...controlHandlers,
+    ...fleetHandlers,
   };
 
   // Mutable adapter registry — keyed by adapter name

package/server/integrations/renderers.js

@@ -154,6 +154,90 @@ function renderCostBudgetWarning(envelope) {
   return mdMsg(parts.join('\n'), 'warning');
 }
 
+// ---------------------------------------------------------------------------
+// Fleet event renderers
+// ---------------------------------------------------------------------------
+// Mirror the run-event renderers' shape: short title line + indented meta
+// rows. fleet_id replaces run_id as the primary key; envelopes are
+// fleet-shaped (top-level fleet_id, no `pipeline` wrapper). See
+// src/worca/events/fleet_emitter.py for the envelope schema.
+
+function fleetId(envelope) {
+  return envelope.fleet_id ?? 'fleet';
+}
+
+function projectBasename(p) {
+  if (!p) return '';
+  const parts = p.split('/').filter(Boolean);
+  return parts[parts.length - 1] || p;
+}
+
+function renderFleetLaunched(envelope) {
+  const p = envelope.payload ?? {};
+  const projects = Array.isArray(p.projects) ? p.projects : [];
+  const projectsLabel = projects.length
+    ? projects.slice(0, 5).map(projectBasename).join(', ') +
+      (projects.length > 5 ? `, +${projects.length - 5} more` : '')
+    : '(none)';
+  const parts = [`\u{1F680} **Fleet launched:** \`${fleetId(envelope)}\``];
+  parts.push(`   **Projects:** ${projects.length} — ${projectsLabel}`);
+  if (p.plan_mode && p.plan_mode !== 'none') {
+    parts.push(`   **Plan mode:** ${p.plan_mode}`);
+  }
+  if (p.guide_attached) parts.push('   **Guide:** attached');
+  if (p.base_branch) parts.push(`   **Base:** ${p.base_branch}`);
+  return mdMsg(parts.join('\n'), 'info');
+}
+
+function renderFleetHalted(envelope) {
+  const p = envelope.payload ?? {};
+  const reason = p.halt_reason || 'unknown';
+  // Severity matches the reason: circuit_breaker is an error, user/stopped is
+  // a warning. Keeps Slack/Discord colour coding consistent with the per-run
+  // pipeline.run.interrupted vs pipeline.circuit_breaker.tripped split.
+  const sev = reason === 'circuit_breaker' ? 'error' : 'warning';
+  const parts = [`\u{1F6D1} **Fleet halted:** \`${fleetId(envelope)}\``];
+  parts.push(`   **Reason:** ${reason}`);
+  if (p.in_flight_count != null) {
+    parts.push(`   **In-flight at halt:** ${p.in_flight_count}`);
+  }
+  if (p.pending_count != null && p.pending_count > 0) {
+    parts.push(`   **Pending (not dispatched):** ${p.pending_count}`);
+  }
+  return mdMsg(parts.join('\n'), sev);
+}
+
+function renderFleetCompleted(envelope) {
+  const p = envelope.payload ?? {};
+  const parts = [`✅ **Fleet completed:** \`${fleetId(envelope)}\``];
+  if (p.child_count != null) {
+    parts.push(
+      `   **Children:** ${p.completed_count ?? p.child_count}/${p.child_count} completed`,
+    );
+  }
+  if (p.duration_ms != null) {
+    parts.push(`   **Duration:** ${fmtMs(p.duration_ms)}`);
+  }
+  return mdMsg(parts.join('\n'), 'success');
+}
+
+function renderFleetFailed(envelope) {
+  const p = envelope.payload ?? {};
+  const parts = [`❌ **Fleet failed:** \`${fleetId(envelope)}\``];
+  if (p.child_count != null) {
+    const failed = p.failed_count ?? 0;
+    const interrupted = p.interrupted_count ?? 0;
+    const completed = p.completed_count ?? 0;
+    parts.push(
+      `   **Children:** ${completed}/${p.child_count} completed, ${failed} failed, ${interrupted} interrupted`,
+    );
+  }
+  if (p.duration_ms != null) {
+    parts.push(`   **Duration:** ${fmtMs(p.duration_ms)}`);
+  }
+  return mdMsg(parts.join('\n'), 'error');
+}
+
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -173,6 +257,20 @@ const EVENT_RENDERERS = {
   'pipeline.git.pr_merged': renderGitPrMerged,
   'pipeline.circuit_breaker.tripped': renderCbTripped,
   'pipeline.cost.budget_warning': renderCostBudgetWarning,
+  // fleet.launched is intentionally NOT in this map by default — projects
+  // that launch many fleets per day would find it noisy. Opt-in callers
+  // can register it themselves via renderEvent's renderer override (or
+  // by extending TIER1_EVENTS in a future per-project config).
+  'fleet.halted': renderFleetHalted,
+  'fleet.completed': renderFleetCompleted,
+  'fleet.failed': renderFleetFailed,
+};
+
+// fleet.launched ships as an opt-in renderer rather than a Tier-1 default —
+// see comment above. Callers that want it can pull it from this export and
+// register it in their own pipeline.
+export const OPT_IN_RENDERERS = {
+  'fleet.launched': renderFleetLaunched,
 };
 
 export const TIER1_EVENTS = Object.keys(EVENT_RENDERERS);

package/server/integrations/rest_client.js

@@ -13,5 +13,12 @@ export function createRestClient({ host, port }) {
       });
       return { status: r.status, data: r.ok ? await r.json() : null };
     },
+    // DELETE used by /fleet-halt (DELETE /api/fleet-runs/:id) — added when
+    // chat fleet commands landed. Mirrors the get/post pair: no body, returns
+    // parsed JSON on 2xx, null on error status.
+    async delete(path) {
+      const r = await fetch(`${base}${path}`, { method: 'DELETE' });
+      return { status: r.status, data: r.ok ? await r.json() : null };
+    },
   };
 }