@dadado/agent-kit-cli 4.8.9 → 5.1.0

package/dashboard/lib/open-browser.mjs

@@ -0,0 +1,298 @@
+/**
+ * Shared Mission Control browser open helper.
+ *
+ * Preference resolution (highest wins):
+ *   1. env MISSION_CONTROL_PREFERRED_BROWSER
+ *   2. config missionControl.preferredBrowser (passed in by caller)
+ *   3. OS default handler (null preferred)
+ *
+ * Skips open when MISSION_CONTROL_NO_OPEN=1.
+ * Never opens more than one process per call (preferred may fall back once).
+ *
+ * Trust boundary: preferredBrowser is an app/binary *name*, not a path or
+ * shell expression. Values with path separators or shell metacharacters are
+ * rejected and treated as OS default.
+ *
+ * ADR: .cursor/memory/decisions/2026-08-11_mission-control-preferred-browser.md
+ */
+
+import { spawn, spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { platform as osPlatform } from "node:os";
+
+/** Sentinel values that mean "use OS default" (and slash-only Ask). */
+export const OS_DEFAULT_TOKENS = new Set(["", "default", "os", "ask"]);
+
+/**
+ * Reject path separators, absolute/relative path forms, and shell metacharacters.
+ * Allowed examples: "Google Chrome", "firefox", "msedge", "Brave Browser".
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isSafePreferredBrowser(value) {
+  if (typeof value !== "string") return false;
+  const s = value.trim();
+  if (!s) return false;
+  if (/[/\\]/.test(s)) return false;
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional reject of C0/DEL in browser names
+  if (/[\0-\x1f\x7f]/.test(s)) return false;
+  if (/[$`;&|<>(){}[\]!*?#~"'%^=,+]/.test(s)) return false;
+  if (s.includes(":")) return false;
+  if (/^-/.test(s)) return false;
+  return true;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean}
+ */
+export function shouldSkipOpen(env = process.env) {
+  return env.MISSION_CONTROL_NO_OPEN === "1";
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null} trimmed app/binary name, or null for OS default
+ */
+export function normalizePreferredBrowser(value) {
+  if (value == null) return null;
+  const s = String(value).trim();
+  if (!s || OS_DEFAULT_TOKENS.has(s.toLowerCase())) return null;
+  if (!isSafePreferredBrowser(s)) return null;
+  return s;
+}
+
+/**
+ * @param {{ env?: NodeJS.ProcessEnv, configValue?: unknown }} [opts]
+ * @returns {string | null}
+ */
+export function resolvePreferredBrowser(opts = {}) {
+  const env = opts.env ?? process.env;
+  const fromEnv = env.MISSION_CONTROL_PREFERRED_BROWSER;
+  if (fromEnv != null && String(fromEnv).trim() !== "") {
+    return normalizePreferredBrowser(fromEnv);
+  }
+  return normalizePreferredBrowser(opts.configValue);
+}
+
+/**
+ * Read missionControl.preferredBrowser from a context config.json path.
+ * Missing/invalid file → null (OS default). Does not create the file.
+ *
+ * @param {string} configPath
+ * @param {{ readFileSync?: typeof readFileSync }} [fsHooks]
+ * @returns {unknown}
+ */
+export function readPreferredBrowserFromConfig(configPath, fsHooks = {}) {
+  const read = fsHooks.readFileSync ?? readFileSync;
+  try {
+    const raw = read(configPath, "utf8");
+    const data = JSON.parse(raw);
+    if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+    const mc = data.missionControl;
+    if (!mc || typeof mc !== "object" || Array.isArray(mc)) return null;
+    return mc.preferredBrowser ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build an argv for a single open attempt (hermetic: no spawn).
+ *
+ * @param {{
+ *   url: string,
+ *   preferred?: string | null,
+ *   platform?: NodeJS.Platform,
+ * }} opts
+ * @returns {{ command: string, args: string[] } | null}
+ */
+export function buildOpenBrowserCommand(opts) {
+  const url = opts.url;
+  if (typeof url !== "string" || !url.trim()) return null;
+  const preferred = normalizePreferredBrowser(opts.preferred ?? null);
+  const os = opts.platform ?? osPlatform();
+
+  if (os === "darwin") {
+    if (preferred) {
+      return { command: "open", args: ["-a", preferred, url] };
+    }
+    return { command: "open", args: [url] };
+  }
+
+  if (os === "win32") {
+    if (preferred) {
+      // `start` treats the first quoted arg as window title; pass empty title.
+      return { command: "cmd", args: ["/c", "start", "", preferred, url] };
+    }
+    return { command: "cmd", args: ["/c", "start", "", url] };
+  }
+
+  // Linux / other: preferred is a binary or command name; else xdg-open.
+  if (preferred) {
+    return { command: preferred, args: [url] };
+  }
+  return { command: "xdg-open", args: [url] };
+}
+
+/**
+ * @param {import("node:child_process").ChildProcess | { on?: Function, unref?: Function } | null | undefined} child
+ */
+function attachErrorSwallow(child) {
+  if (child && typeof child.on === "function") {
+    child.on("error", () => {
+      /* prevent unhandled 'error' (ENOENT) from killing the launcher */
+    });
+  }
+  if (child && typeof child.unref === "function") {
+    child.unref();
+  }
+}
+
+/**
+ * Open one browser for the URL. Returns whether a process was spawned.
+ * When a preferred open fails, falls back once to the OS default opener.
+ *
+ * @param {string} url
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   preferred?: string | null,
+ *   configValue?: unknown,
+ *   platform?: NodeJS.Platform,
+ *   spawnFn?: typeof spawn,
+ *   spawnSyncFn?: typeof spawnSync,
+ * }} [options]
+ * @returns {{ opened: boolean, reason?: string, command?: string, args?: string[] }}
+ */
+export function openBrowser(url, options = {}) {
+  const env = options.env ?? process.env;
+  if (shouldSkipOpen(env)) {
+    return { opened: false, reason: "no-open" };
+  }
+
+  const preferred =
+    options.preferred !== undefined
+      ? normalizePreferredBrowser(options.preferred)
+      : resolvePreferredBrowser({ env, configValue: options.configValue });
+
+  const platform = options.platform ?? osPlatform();
+  const spawnFn = options.spawnFn ?? spawn;
+  const spawnSyncFn = options.spawnSyncFn;
+
+  /**
+   * @param {{ command: string, args: string[] }} built
+   * @returns {{ opened: boolean, reason?: string, command: string, args: string[] }}
+   */
+  function runDetached(built) {
+    try {
+      const child = spawnFn(built.command, built.args, { detached: true, stdio: "ignore" });
+      attachErrorSwallow(child);
+      return { opened: true, command: built.command, args: built.args };
+    } catch {
+      return {
+        opened: false,
+        reason: "spawn-failed",
+        command: built.command,
+        args: built.args,
+      };
+    }
+  }
+
+  /**
+   * Preferred open: detect failure before claiming success, then caller may fall back.
+   * Hermetic tests that only inject spawnFn use the detached path (throw = fail).
+   *
+   * @param {{ command: string, args: string[] }} built
+   * @returns {{ opened: boolean, reason?: string, command: string, args: string[] }}
+   */
+  function runPreferred(built) {
+    if (options.spawnFn && !spawnSyncFn) {
+      return runDetached(built);
+    }
+
+    const sync = spawnSyncFn ?? spawnSync;
+
+    if (platform !== "darwin" && platform !== "win32") {
+      // Long-lived browser binaries: probe PATH, then detach (do not spawnSync the app).
+      const probe = sync("which", [built.command], { encoding: "utf8" });
+      if (probe.error || (typeof probe.status === "number" && probe.status !== 0)) {
+        return {
+          opened: false,
+          reason: "spawn-failed",
+          command: built.command,
+          args: built.args,
+        };
+      }
+      return runDetached(built);
+    }
+
+    // darwin `open` / win32 `cmd /c start` exit quickly.
+    try {
+      const result = sync(built.command, built.args, {
+        encoding: "utf8",
+        windowsHide: true,
+      });
+      if (result.error || (typeof result.status === "number" && result.status !== 0)) {
+        return {
+          opened: false,
+          reason: "spawn-failed",
+          command: built.command,
+          args: built.args,
+        };
+      }
+      return { opened: true, command: built.command, args: built.args };
+    } catch {
+      return {
+        opened: false,
+        reason: "spawn-failed",
+        command: built.command,
+        args: built.args,
+      };
+    }
+  }
+
+  const built = buildOpenBrowserCommand({
+    url,
+    preferred,
+    platform,
+  });
+  if (!built) {
+    return { opened: false, reason: "invalid-url" };
+  }
+
+  if (!preferred) {
+    // Same failure detection as preferred opens (probe / spawnSync) so OS-default
+    // missing handlers are not reported as opened:true.
+    return runPreferred(built);
+  }
+
+  const prefResult = runPreferred(built);
+  if (prefResult.opened) {
+    return prefResult;
+  }
+
+  const fallback = buildOpenBrowserCommand({
+    url,
+    preferred: null,
+    platform,
+  });
+  if (!fallback) {
+    return { opened: false, reason: "invalid-url" };
+  }
+  const fb = runPreferred(fallback);
+  if (fb.opened) {
+    return {
+      opened: true,
+      command: fb.command,
+      args: fb.args,
+      reason: "preferred-fallback",
+    };
+  }
+  return {
+    opened: false,
+    reason: "spawn-failed",
+    command: built.command,
+    args: built.args,
+  };
+}

package/dashboard/lib/semantic-model.mjs

@@ -24,10 +24,16 @@ export const MONITOR_FEED_CAP = 20;
 /** Cap agent_step rows emitted per active plan for the denser Crew feed. */
 export const MONITOR_AGENT_STEP_EMIT_CAP = 12;
 
+/** Cap subagent-run rows emitted per snapshot (fs scan bounds live in dashboard-data.mjs). */
+export const MONITOR_SUBAGENT_EMIT_CAP = 8;
+/** Cap plan_review pointer rows emitted per snapshot. */
+export const MONITOR_PLAN_REVIEW_EMIT_CAP = 4;
+
 /**
  * Monitor hero curated subset over the semantic activity stream.
  * Live agent steps: run_plan / handoff / delivery plus agent_step (Task/orchestrator
- * to-do steps). plan_progress milestones stay on Activity / Checklist.
+ * to-do steps), subagent (Task worker lifecycle) and plan_review (background
+ * mid-batch review pointers). plan_progress milestones stay on Activity / Checklist.
  * Activity (Phase 2) is the superset; inventory kinds are excluded here.
  */
 export const MONITOR_ACTIVITY_KINDS = Object.freeze([
@@ -35,6 +41,8 @@ export const MONITOR_ACTIVITY_KINDS = Object.freeze([
   "handoff",
   "delivery",
   "agent_step",
+  "subagent",
+  "plan_review",
 ]);
 
 /**
@@ -2152,9 +2160,12 @@ export function formatDeliveryActivity(logLines, { plans = [], limit = MAX_GIT_A
     const kitAgent = normalizeKitAgentId(agent);
     const actor = briefActivityActor(kitAgent, { kind: "delivery", plan: planName });
     const prBit = `PR #${entry.pr}`;
+    // Verb `merged` (not `shipped`, retired 2026-08-05): the row is derived from
+    // a merge/squash entry, and `shipped` implied a prod promote /git-staging
+    // never performed.
     const label = brief
-      ? `${actor} \u00b7 shipped \u00b7 ${brief} \u00b7 ${prBit} \u00b7 ${entry.sha}`
-      : `${actor} \u00b7 shipped \u00b7 ${prBit} \u00b7 ${entry.sha}`;
+      ? `${actor} \u00b7 merged \u00b7 ${brief} \u00b7 ${prBit} \u00b7 ${entry.sha}`
+      : `${actor} \u00b7 merged \u00b7 ${prBit} \u00b7 ${entry.sha}`;
     const commitType = parseDeliveryCommitType(brief, { hasPr: entry.pr != null });
     events.push({
       id: activityId("delivery", ["merge", String(entry.pr)]),
@@ -2173,18 +2184,23 @@ export function formatDeliveryActivity(logLines, { plans = [], limit = MAX_GIT_A
 
 /**
  * Actor segment for Monitor return-brief labels.
- * Kit agent id, else Engineering Manager for delivery, else Squad when a plan
- * is present (never the full plan filename), else Platform Engineer.
- * Default software lexicon display masks (resolution kinds unchanged).
+ * Kit agent id, else `Eng` for delivery, else `SQ` when a plan is present
+ * (never the full plan filename), else `Eng`.
+ *
+ * Short display masks from the operator lexicon (2026-08-05): Engineering
+ * Manager -> Eng, Squad -> SQ, Platform Engineer -> Eng. `Eng` is a documented
+ * collision between the delivery and system fallbacks; the resolution keys
+ * (`orchestrator` / `crew` / `system`) and the row's kind glyph stay distinct.
+ * ADR: decisions/2026-07-27_crew-monitor-vs-plan-monitor-glossary.md.
  * @param {string|null|undefined} agent
  * @param {{ kind?: string, plan?: string|null }} [opts]
  */
 export function briefActivityActor(agent, { kind, plan } = {}) {
   const kit = normalizeKitAgentId(agent);
   if (kit) return kit;
-  if (kind === "delivery") return "Engineering Manager";
-  if (plan) return "Squad";
-  return "Platform Engineer";
+  if (kind === "delivery") return "Eng";
+  if (plan) return "SQ";
+  return "Eng";
 }
 
 /**
@@ -2316,6 +2332,191 @@ export function formatPlanHandoffActivity({ now, handoff, plans }) {
   return events;
 }
 
+/**
+ * Task subagent transcripts are `<uuid>.jsonl` inside a parent chat's
+ * `subagents/` directory.
+ */
+export const SUBAGENT_TRANSCRIPT_FILE_RE = /^([0-9a-fA-F][0-9a-fA-F-]{7,})\.jsonl$/;
+
+/**
+ * Worker-prompt fields the kit's own dispatch template declares (see
+ * `.cursor/commands/run-plan.md`). Both forms occur in real dispatches: the
+ * bare `To-do id: x` of the plain template and the `- **worker_type:** x` of a
+ * bulleted orchestrator prompt, so the leading list marker and the markdown
+ * emphasis on either side of the colon are optional. The captured value
+ * excludes `*` and a backtick so `**explore**` and `` `explore` `` yield
+ * `explore` rather than the decoration.
+ */
+const SUBAGENT_TODO_ID_RE =
+  /^[ \t]*(?:[-*][ \t]*)?\**To-?do id\**[ \t]*[:=][ \t]*\**[ \t]*([^\s*`]+)/im;
+const SUBAGENT_WORKER_TYPE_RE =
+  /^[ \t]*(?:[-*][ \t]*)?\**(?:worker_type(?:[ \t]*\/[ \t]*subagent_type)?|subagent_type)\**[ \t]*[:=][ \t]*\**[ \t]*([^\s*`]+)/im;
+
+/** Plain-text content of a transcript entry (user prompt or assistant reply). */
+function subagentEntryText(entry) {
+  const content = entry?.message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = [];
+  for (const c of content) {
+    if (c && c.type === "text" && typeof c.text === "string") parts.push(c.text);
+  }
+  return parts.join("\n");
+}
+
+/**
+ * Lifecycle of one Task subagent run, from the two records that carry it: the
+ * dispatch prompt (first entry) and the terminal record (last entry).
+ *
+ * Phase contract: a transcript whose last record is not `turn_ended` is still
+ * `running`; `turn_ended` with `status: "success"` is `done`; any other status
+ * (including `error`) is `failed`. A transcript that is empty or entirely
+ * unparsable yields `null` rather than a phantom running row.
+ *
+ * The fs half (directory layout, recency window, file/byte caps) lives in
+ * `dashboard-data.mjs` next to the agent-prompt scan contract. Transcript paths
+ * live under `$HOME`, never in the repo, so no `sourcePath` is emitted.
+ *
+ * @param {{ id?: string, parentId?: string|null, firstLine?: string, lastLine?: string, modifiedAt?: string|null }} input
+ * @returns {{ id: string, parentId: string|null, phase: 'running'|'done'|'failed', todoId: string|null, workerType: string|null, modifiedAt: string|null }|null}
+ */
+export function parseSubagentRun({
+  id,
+  parentId = null,
+  firstLine = "",
+  lastLine = "",
+  modifiedAt = null,
+} = {}) {
+  const runId = String(id || "").trim();
+  if (!runId) return null;
+
+  let first = null;
+  let last = null;
+  try {
+    first = firstLine ? JSON.parse(firstLine) : null;
+  } catch {
+    first = null;
+  }
+  try {
+    last = lastLine ? JSON.parse(lastLine) : null;
+  } catch {
+    last = null;
+  }
+  if (!first && !last) return null;
+
+  let phase = "running";
+  if (last && last.type === "turn_ended") {
+    phase = last.status === "success" ? "done" : "failed";
+  }
+
+  const promptText = first && first.role === "user" ? subagentEntryText(first) : "";
+  const todoMatch = promptText ? SUBAGENT_TODO_ID_RE.exec(promptText) : null;
+  const typeMatch = promptText ? SUBAGENT_WORKER_TYPE_RE.exec(promptText) : null;
+  const rawTodo = todoMatch ? todoMatch[1] : null;
+  const rawType = typeMatch ? typeMatch[1] : null;
+  // The template writes literal placeholders when a field is unset; those are
+  // not identities and must not reach a row.
+  const placeholder = /^(?:<.*>|none|n\/a|-{1,2})$/i;
+  return {
+    id: runId,
+    parentId: parentId ? String(parentId) : null,
+    phase,
+    todoId: rawTodo && !placeholder.test(rawTodo) ? rawTodo : null,
+    workerType: rawType && !placeholder.test(rawType) ? rawType : null,
+    modifiedAt: modifiedAt || null,
+  };
+}
+
+/**
+ * Live Crew Monitor rows for Task subagent runs (start / still running /
+ * complete / failed). Newest first; the caller passes an already-bounded list.
+ *
+ * Deliberately a distinct kind from `agent_step`: `agent_step` is derived from
+ * plan to-do status, so a subagent that runs without flipping a to-do would be
+ * invisible there and a to-do flipped by hand would be misattributed to a
+ * worker. ADR: decisions/2026-07-27_crew-monitor-vs-plan-monitor-glossary.md.
+ *
+ * @param {object[]} runs - `parseSubagentRun` output
+ * @param {{ limit?: number }} [opts]
+ */
+export function formatSubagentActivity(runs, { limit = MONITOR_SUBAGENT_EMIT_CAP } = {}) {
+  const events = [];
+  for (const run of runs || []) {
+    if (events.length >= limit) break;
+    if (!run || !run.id) continue;
+    const kitAgent = normalizeKitAgentId(run.workerType);
+    // Display actor is the dispatched worker type whenever the prompt declared
+    // one: a built-in type such as `explore` is a real worker identity even
+    // though it is not a `.cursor/agents/` id. `agent` stays kit-id-only so
+    // downstream attribution is unchanged. `Dev` is the operator-lexicon mask
+    // for Developer / Full-Stack Developer, used when no type was declared.
+    const actor = run.workerType ? truncateStr(String(run.workerType), 24) : "Dev";
+    const shortId = String(run.id).slice(0, 8);
+    const subject = run.todoId || "task";
+    const visible = `${actor} · ${run.phase} · ${subject} · ${shortId}`;
+    events.push({
+      id: activityId("subagent", [run.id, run.phase]),
+      kind: "subagent",
+      at: run.modifiedAt || null,
+      agent: kitAgent,
+      label: truncateStr(visible, MAX_SEMANTIC_LABEL),
+      labelFull: visible,
+      // Transcripts live outside the repo (under $HOME); no repo path to copy.
+      sourcePath: null,
+      refs: { subagent: run.id, parent: run.parentId || null, phase: run.phase, todo: run.todoId },
+    });
+  }
+  return events;
+}
+
+/**
+ * Crew Monitor pointer rows for background mid-batch plan reviews.
+ *
+ * The operator cannot otherwise see that a review ran: `plan-monitor-*.md` lands
+ * silently in `.cursor/memory/` and only surfaces once Flight Log / attention
+ * picks it up. These rows say a review exists and whether it is still owed
+ * triage. They are pointers only — Flight Log and the attention inbox keep sole
+ * ownership of triage state and actions, and a row never marks anything
+ * reviewed. Boundary amend recorded in the glossary ADR (2026-08-05).
+ *
+ * @param {object[]} reports - `parseExternalReport` output
+ * @param {object[]} plans - plan records from the snapshot
+ * @param {{ limit?: number }} [opts]
+ */
+export function formatPlanReviewActivity(
+  reports,
+  plans,
+  { limit = MONITOR_PLAN_REVIEW_EMIT_CAP } = {},
+) {
+  const sorted = (reports || [])
+    .filter((r) => r?.file)
+    .slice()
+    .sort((a, b) => String(b.modifiedAt || "").localeCompare(String(a.modifiedAt || "")));
+
+  const events = [];
+  for (const report of sorted) {
+    if (events.length >= limit) break;
+    const triaged = isReportTriaged(report, plans);
+    // `awaiting` reuses the existing gate verb: the review itself has landed,
+    // what is outstanding is the operator's triage.
+    const verb = triaged ? "done" : "awaiting";
+    // `QA` is the operator-lexicon mask for QA Engineer.
+    const planRef = report.reviewedPlanFile || `${report.slug}.plan.md`;
+    const visible = `QA · ${verb} · review · ${planRef}`;
+    events.push({
+      id: activityId("plan_review", [report.file, triaged ? "triaged" : "open"]),
+      kind: "plan_review",
+      at: report.modifiedAt || null,
+      agent: null,
+      label: truncateStr(visible, MAX_SEMANTIC_LABEL),
+      labelFull: visible,
+      sourcePath: report.path || null,
+      refs: { plan: report.reviewedPlanFile || null, report: report.file, triaged },
+    });
+  }
+  return events;
+}
+
 /**
  * Explicit run-plan loop lines in terminal output. Shared detection for the
  * Crew feed (formatTerminalRunEvidence) and the busy-outside-plan derivation
@@ -3562,6 +3763,7 @@ export function buildMissionControlView({
   deferredCheckIds = [],
   agentPrompts = [],
   externalReports = [],
+  subagentRuns = [],
   dismissedIds = [],
   archivedPlanFiles = [],
   agents = [],
@@ -3615,7 +3817,11 @@ export function buildMissionControlView({
   const activity = mergeActivity([
     planEvents.filter((e) => e.kind === "run_plan" || e.kind === "handoff"),
     planEvents.filter((e) => e.kind === "agent_step"),
+    // Live Task-worker lifecycle before delivery: a running subagent is the
+    // freshest thing on the board and must not be starved by MAX_ACTIVITY.
+    formatSubagentActivity(subagentRuns),
     deliveryEvents,
+    formatPlanReviewActivity(externalReports, plans),
     planEvents.filter((e) => e.kind === "plan_progress"),
     formatGitActivity(gitLogLines, { excludeShas: supersededShas }),
     formatTerminalRunEvidence(terminals),