@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/http/script-runs.ts

@@ -13,10 +13,12 @@ import {
   getLatestScriptRunStepTaskByContextKey,
   getScriptRun,
   getScriptRunByIdempotencyKey,
+  getScriptRunFollowUpGuard,
   getScriptRunJournalStep,
   getTaskById,
   listScriptRunJournalSteps,
   listScriptRuns,
+  setScriptRunFollowUpGuard,
   updateScriptRun,
   updateScriptRunIfNotTerminal,
   updateScriptRunIfRunning,
@@ -24,6 +26,7 @@ import {
 } from "../be/db";
 import { explicitModelErrorForAgent } from "../be/model-validation";
 import { refuseSourceWithSecrets } from "../be/scripts/source-secrets";
+import { can } from "../rbac";
 import { lintWorkflowLabels } from "../script-workflows/label-lint";
 import { scriptRunMaxAgentTasks, scriptRunMaxSteps } from "../script-workflows/limits";
 import {
@@ -32,6 +35,12 @@ import {
   terminateScriptRunProcess,
 } from "../script-workflows/supervisor";
 import {
+  evaluateFollowUpRedelegation,
+  type FollowUpRedelegationBlock,
+  followUpThreadForSourceTask,
+} from "../tasks/follow-up-redelegation-guard";
+import {
+  type AgentTask,
   AgentTaskStatusSchema,
   RoutingReasonSchema,
   ScriptRunJournalEntrySchema,
@@ -111,6 +120,8 @@ const agentTaskBodySchema = z.object({
   parentTaskId: z.string().uuid().optional(),
   requestedByUserId: z.string().optional(),
   outputSchema: z.record(z.string(), z.unknown()).optional(),
+  /** Dispatch even when the follow-up re-delegation guard blocks it (same flag as send-task). */
+  allowRedelegation: z.boolean().optional(),
 });
 
 const scriptRunCreatedSchema = z.object({
@@ -298,10 +309,70 @@ const agentTaskRoute = route({
       description: "Agent task created or still running",
       schema: z.object({ taskId: z.string(), status: AgentTaskStatusSchema }),
     },
+    403: {
+      description:
+        "Script run belongs to another agent, or the run's agent may not create a child task under parentTaskId",
+    },
     404: { description: "Script run not found" },
+    409: { description: "Agent task failed, was cancelled, or was superseded" },
+    422: { description: "Blocked by the follow-up re-delegation guard" },
   },
 });
 
+/**
+ * Send-task's task.parent.attach decision for a `ctx.step.agentTask` step: a
+ * step inherits its parent's contextKey (its Slack or chat thread) and
+ * requester, so the run's agent needs the right to hold a child under it.
+ * Returns the 403 message, or null when allowed. A parent id with no task row
+ * passes: a step under it inherits nothing, as on send-task.
+ */
+async function stepParentRefusal(runAgentId: string, parentTaskId: string): Promise<string | null> {
+  const parentTask = await getTaskById(parentTaskId);
+  if (!parentTask) return null;
+  const runAgent = await getAgentById(runAgentId);
+  const decision = can({
+    principal: { kind: "agent", agentId: runAgentId, isLead: runAgent?.isLead ?? false },
+    verb: "task.parent.attach",
+    resource: {
+      kind: "task",
+      taskId: parentTask.id,
+      requestedByUserId: parentTask.requestedByUserId,
+      creatorAgentId: parentTask.creatorAgentId,
+      agentId: parentTask.agentId,
+    },
+    source: "http",
+  });
+  return decision.allow
+    ? null
+    : `You don't have context for parent task ${parentTaskId}. Only its assignee, its creator, or a lead can create a child task under it.`;
+}
+
+/**
+ * The launching session's task (X-Source-Task-Id), kept only when it belongs
+ * to the launching agent so a run cannot borrow another agent's session.
+ */
+async function resolveRunSourceTaskId(
+  req: IncomingMessage,
+  agentId: string,
+): Promise<string | undefined> {
+  const raw = req.headers["x-source-task-id"];
+  const sourceTaskId = Array.isArray(raw) ? raw[0] : raw;
+  if (!sourceTaskId) return undefined;
+  const task = await getTaskById(sourceTaskId);
+  return task?.agentId === agentId ? task.id : undefined;
+}
+
+/** One `ctx.step.agentTask` dispatch: the step task, or the guard rule that blocked it. */
+type StepDispatch =
+  | {
+      task: AgentTask;
+      /** True when this call inserted the step, false on a replay. */
+      created?: boolean;
+      blocked?: undefined;
+      override?: FollowUpRedelegationBlock["rule"];
+    }
+  | { task?: undefined; blocked: FollowUpRedelegationBlock; override?: undefined };
+
 async function requireAgent(res: ServerResponse, agentId: string | undefined) {
   if (!agentId) {
     jsonError(res, "X-Agent-ID required for script runs API", 400);
@@ -408,6 +479,7 @@ export async function handleScriptRuns(
     // Cap check and insert commit together: N concurrent POSTs otherwise all
     // read cap-1 active runs and all insert, exceeding the cap.
     const cap = scriptRunConcurrencyCap();
+    const sourceTaskId = await resolveRunSourceTaskId(req, agent.id);
     const creation = await getDbClient().transaction(async () => {
       if ((await countActiveScriptRuns()) >= cap) return null;
       return await createScriptRun({
@@ -418,6 +490,7 @@ export async function handleScriptRuns(
         scriptName: parsed.body.scriptName,
         idempotencyKey: parsed.body.idempotencyKey,
         requestedByUserId: parsed.body.requestedByUserId,
+        sourceTaskId,
         createdBy: parsed.body.requestedByUserId,
       });
     });
@@ -629,9 +702,29 @@ export async function handleScriptRuns(
       return true;
     }
 
+    // Only the run's own harness dispatches its steps (it sends the run's
+    // agent id). Step tasks carry that agent as creator, so another agent
+    // must not create them.
+    if (agentId !== run.agentId) {
+      jsonError(res, "Script run belongs to another agent", 403);
+      return true;
+    }
+
+    // The requested parent, checked before any lookup or insert so a refused
+    // call creates nothing.
+    if (parsed.body.parentTaskId) {
+      const refusal = await stepParentRefusal(run.agentId, parsed.body.parentTaskId);
+      if (refusal) {
+        jsonError(res, refusal, 403);
+        return true;
+      }
+    }
+
     const contextKey = `script-run:${run.id}:${parsed.body.stepKey}`;
     let task = await getLatestScriptRunStepTaskByContextKey(contextKey);
+    let dispatchedHere = false;
     if (!task) {
+      const taskDescription = parsed.body.template ?? parsed.body.task ?? parsed.body.stepKey;
       const modelError = await explicitModelErrorForAgent({
         model: parsed.body.model,
         allowCustomModel: parsed.body.allowCustomModel,
@@ -641,10 +734,47 @@ export async function handleScriptRuns(
         jsonError(res, modelError, 400);
         return true;
       }
+      const followUpThread = await followUpThreadForSourceTask(run.sourceTaskId);
+      // The replay lookup, the guard decision and the insert share one write
+      // transaction. It serializes this step against the run's other steps,
+      // other runs and send-task dispatches into the same thread.
+      let dispatched: StepDispatch;
       try {
-        task = await createTaskExtended(
-          parsed.body.template ?? parsed.body.task ?? parsed.body.stepKey,
-          {
+        dispatched = await getDbClient().transaction(async (): Promise<StepDispatch> => {
+          const replayed = await getLatestScriptRunStepTaskByContextKey(contextKey);
+          if (replayed) return { task: replayed };
+
+          // Follow-up re-delegation guard, as in send-task. A run is one
+          // dispatch: its first new step decides for the whole run, and every
+          // later step follows that decision. Later steps never compare against
+          // the run's own completed steps, a long run cannot use up the thread's
+          // loop cap, and parallel steps are dispatched all or none.
+          let override: FollowUpRedelegationBlock["rule"] | undefined;
+          if (followUpThread) {
+            const decision = await getScriptRunFollowUpGuard(run.id);
+            if (decision !== "passed") {
+              const blocked: FollowUpRedelegationBlock | null =
+                decision === null
+                  ? await evaluateFollowUpRedelegation({
+                      ...followUpThread,
+                      creatorAgentId: run.agentId,
+                      taskDescription,
+                      targetAgentId: parsed.body.agentId,
+                    })
+                  : {
+                      rule: decision,
+                      message: `Blocked by the follow-up re-delegation guard (${decision} rule): an earlier step of this script run was blocked, and a run counts as one dispatch. If it must run, pass allowRedelegation: true.`,
+                    };
+              if (blocked && !parsed.body.allowRedelegation) {
+                if (decision === null) await setScriptRunFollowUpGuard(run.id, blocked.rule);
+                return { blocked };
+              }
+              override = blocked?.rule;
+              await setScriptRunFollowUpGuard(run.id, "passed");
+            }
+          }
+
+          const created = await createTaskExtended(taskDescription, {
             agentId: parsed.body.agentId,
             routingReason:
               parsed.body.routingReason ?? (parsed.body.agentId ? "human_pinned" : undefined),
@@ -660,6 +790,20 @@ export async function handleScriptRuns(
             offeredTo: parsed.body.offerMode ? parsed.body.agentId : undefined,
             taskType: "script-run-step",
             source: "mcp",
+            // Counts the run toward the launcher's follow-up loop cap.
+            creatorAgentId: run.agentId,
+            // With no parent, the step inherits the launching session's Slack
+            // thread, as a send-task from that session does.
+            sourceTaskId: run.sourceTaskId,
+            // A guarded run's steps are its dispatches into the follow-up's
+            // thread, whatever their parent, so the guard sees them there.
+            ...(followUpThread
+              ? {
+                  slackChannelId: followUpThread.channelId,
+                  slackThreadTs: followUpThread.threadTs,
+                  slackUserId: followUpThread.userId,
+                }
+              : {}),
             dir: parsed.body.dir,
             vcsRepo: parsed.body.vcsRepo,
             model: parsed.body.model,
@@ -667,8 +811,9 @@ export async function handleScriptRuns(
             requestedByUserId: parsed.body.requestedByUserId ?? run.requestedByUserId,
             outputSchema: parsed.body.outputSchema,
             contextKey,
-          },
-        );
+          });
+          return { task: created, created: true, override };
+        });
       } catch (error) {
         if (error instanceof ExtensionAgentAssignmentError) {
           jsonError(res, error.message, 400);
@@ -676,6 +821,30 @@ export async function handleScriptRuns(
         }
         throw error;
       }
+      if (dispatched.override) {
+        console.log(
+          `[script-runs] follow-up re-delegation override: rule=${dispatched.override} runId=${run.id} creatorAgentId=${run.agentId} sourceTaskId=${run.sourceTaskId} thread=${followUpThread?.channelId}/${followUpThread?.threadTs}`,
+        );
+      }
+      if (!dispatched.task) {
+        json(res, { error: dispatched.blocked.message, rule: dispatched.blocked.rule }, 422);
+        return true;
+      }
+      task = dispatched.task;
+      dispatchedHere = dispatched.created === true;
+    }
+
+    // A replay answers from the selected step, whatever parent this call sent
+    // (or omitted), so authorize the parent the step actually holds. Every
+    // replay lookup above lands here before any output is returned. A step this
+    // call just dispatched was authorized above; refusing it now would leave
+    // the work running behind a 403.
+    if (!dispatchedHere && task.parentTaskId) {
+      const refusal = await stepParentRefusal(run.agentId, task.parentTaskId);
+      if (refusal) {
+        jsonError(res, refusal, 403);
+        return true;
+      }
     }
 
     const deadline = Date.now() + 30_000;

package/src/http/status.ts

@@ -45,6 +45,7 @@ import { getSlackConnectionState } from "../slack/connection-state";
 import { isTelemetryEnabled } from "../telemetry";
 import { type AgentCredStatus, AutomationIntegrationIdSchema, ProviderNameSchema } from "../types";
 import { isRuntimePoolsEnabled } from "../utils/runtime-pools-flag";
+import { resolveAppUrl } from "./config-values";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -116,6 +117,12 @@ export const StatusIdentitySchema = z.object({
    * cloud installs can be sliced server-side.
    */
   org_id: z.string().nullable(),
+  /**
+   * The swarm's public dashboard URL (`APP_URL`, then `DASHBOARD_URL`, with
+   * swarm_config precedence). Null when neither is set. The dashboard reads
+   * links to it in agent output as its own. Absent on older APIs.
+   */
+  dashboard_url: z.string().nullable().optional(),
 });
 export type StatusIdentity = z.infer<typeof StatusIdentitySchema>;
 
@@ -334,7 +341,7 @@ export async function rollupCredStatusForProvider(provider: string): Promise<Cre
 
 // ─── Identity ────────────────────────────────────────────────────────────────
 
-function buildIdentity(): StatusIdentity {
+function buildIdentity(dashboardUrl: string | null): StatusIdentity {
   const cloudRaw = process.env.SWARM_CLOUD;
   const hideRaw = process.env.SWARM_HIDE_CLOUD_PROMO;
   return {
@@ -345,6 +352,7 @@ function buildIdentity(): StatusIdentity {
     marketing_url: process.env.SWARM_MARKETING_URL?.trim() || null,
     hide_cloud_promo: hideRaw === "true" || hideRaw === "1",
     org_id: process.env.SWARM_ORG_ID?.trim() || null,
+    dashboard_url: dashboardUrl,
   };
 }
 
@@ -759,7 +767,7 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
   const instance = await getInstanceFeedbackSignals();
   return {
     runtime_pools: { enabled: isRuntimePoolsEnabled(), supervisor: runtimeSupervisorStatus() },
-    identity: buildIdentity(),
+    identity: buildIdentity(await resolveAppUrl()),
     setup,
     activity: { ...activity, leads_ready: readyLeads },
     agent_fs: {

package/src/http/tasks.ts

@@ -84,7 +84,7 @@ import {
 import { ensure } from "../utils/business-use";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
-import { createListTotalCache } from "./list-total-cache";
+import { createListTotalCache, LIST_TOTAL_TTL_MS } from "./list-total-cache";
 import {
   agentFirstPrincipal,
   authUserId,
@@ -224,7 +224,9 @@ const SupersedeTaskResponseSchema = z.object({
 
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
-const taskTotals = createListTotalCache();
+// The task list total scans every visible task, and only the pager shows it,
+// so page 1 polls reuse a total younger than 15 s.
+const taskTotals = createListTotalCache(LIST_TOTAL_TTL_MS, 15_000);
 
 const listTasks = route({
   method: "get",

package/src/pages/browser-sdk.ts

@@ -377,11 +377,23 @@ export const SWARM_UI_JS = `
     closeCursorRoomIfUnused(record);
   }
 
+  // Colors and fonts read the page theme tokens (designVersion 2). Each
+  // fallback is the original literal, so a designVersion 1 page, which has no
+  // tokens, renders exactly as before.
   var SEV_COLOR = {
-    error: '#ef4444',
-    warn:  '#f59e0b',
-    info:  '#3b82f6',
+    error: 'var(--color-status-error-strong, #ef4444)',
+    warn:  'var(--color-status-warning-strong, #f59e0b)',
+    info:  'var(--color-status-info-strong, #3b82f6)',
   };
+  var MUTED = 'var(--color-muted-foreground, #7c8aa6)';
+  var MONO = "var(--font-mono, 'Space Mono', ui-monospace, monospace)";
+
+  // A color at a lower alpha. Mixing with transparent keeps the color and
+  // scales its alpha, so tint('#ef4444', '13.33%') equals #ef444422 and
+  // tint('rgb(34,197,94)', '10%') equals rgba(34,197,94,0.10).
+  function tint(color, percent) {
+    return 'color-mix(in srgb, ' + color + ' ' + percent + ', transparent)';
+  }
 
   function esc(s) {
     return String(s == null ? '' : s)
@@ -416,7 +428,7 @@ export const SWARM_UI_JS = `
       '<span class="swarm-diff-annot no-print" '
       + 'style="display:inline-block;margin-left:8px;padding:1px 6px;'
       + 'border-radius:4px;font-size:11px;font-weight:600;'
-      + 'background:' + color + '22;color:' + color + ';border:1px solid ' + color + '55;">'
+      + 'background:' + tint(color, '13.33%') + ';color:' + color + ';border:1px solid ' + tint(color, '33.33%') + ';">'
       + esc((ann && ann.severity ? ann.severity.toUpperCase() : 'INFO')) + ' · ' + esc(ann && ann.text || '')
       + '</span>'
     );
@@ -448,12 +460,12 @@ export const SWARM_UI_JS = `
       var text = line.text == null ? '' : line.text;
       var bg, oldCell, newCell, sign;
       if (type === 'add') {
-        bg = 'rgba(34,197,94,0.10)';
+        bg = tint('var(--color-status-success, rgb(34,197,94))', '10%');
         oldCell = '';
         newCell = String(newN++);
         sign = '+';
       } else if (type === 'del') {
-        bg = 'rgba(239,68,68,0.10)';
+        bg = tint('var(--color-status-error, rgb(239,68,68))', '10%');
         oldCell = String(oldN++);
         newCell = '';
         sign = '-';
@@ -465,15 +477,17 @@ export const SWARM_UI_JS = `
       }
 
       var annHtml = '';
-      var anns = annByLine[Number(newCell)] || annByLine[Number(oldCell)] || [];
+      // Annotations name new-side lines. A deleted row has no new-side
+      // number, so only a deleted row matches on its old-side number.
+      var anns = annByLine[Number(type === 'del' ? oldCell : newCell)] || [];
       for (var k = 0; k < anns.length; k++) annHtml += renderAnnotation(anns[k]);
 
       rowsHtml += (
         '<tr style="background:' + bg + ';">'
-        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:#7c8aa6;font-size:12px;width:48px;">' + esc(oldCell) + '</td>'
-        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:#7c8aa6;font-size:12px;width:48px;">' + esc(newCell) + '</td>'
-        + '<td class="swarm-diff-sign" style="user-select:none;text-align:center;padding:0 4px;color:#7c8aa6;font-size:12px;width:18px;">' + esc(sign) + '</td>'
-        + '<td class="swarm-diff-code" style="padding:0 8px;white-space:pre-wrap;word-break:break-word;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:12px;">' + esc(text) + annHtml + '</td>'
+        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:' + MUTED + ';font-size:12px;width:48px;">' + esc(oldCell) + '</td>'
+        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:' + MUTED + ';font-size:12px;width:48px;">' + esc(newCell) + '</td>'
+        + '<td class="swarm-diff-sign" style="user-select:none;text-align:center;padding:0 4px;color:' + MUTED + ';font-size:12px;width:18px;">' + esc(sign) + '</td>'
+        + '<td class="swarm-diff-code" style="padding:0 8px;white-space:pre-wrap;word-break:break-word;font-family:' + MONO + ';font-size:12px;">' + esc(text) + annHtml + '</td>'
         + '</tr>'
       );
     }
@@ -485,8 +499,8 @@ export const SWARM_UI_JS = `
     );
 
     return (
-      '<a id="' + esc(anchorId) + '" class="swarm-diff-anchor" data-hunk="' + esc(anchorSlug) + '"></a>'
-      + '<div class="swarm-diff-hunk-header" style="padding:6px 12px;background:rgba(124,138,166,0.10);color:#7c8aa6;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:11px;border-top:1px solid var(--swarm-border,#22304a);">'
+      '<a id="' + esc(anchorId) + '" class="swarm-diff-anchor" data-hunk="' + esc(anchorSlug) + '" data-new-start="' + esc(newStart) + '"></a>'
+      + '<div class="swarm-diff-hunk-header" style="padding:6px 12px;background:' + tint('var(--color-muted-foreground, rgb(124,138,166))', '10%') + ';color:' + MUTED + ';font-family:' + MONO + ';font-size:11px;border-top:1px solid var(--swarm-border,#22304a);">'
       + esc(header)
       + '</div>'
       + '<table class="swarm-diff-table" style="width:100%;border-collapse:collapse;table-layout:fixed;">'
@@ -503,7 +517,7 @@ export const SWARM_UI_JS = `
 
     var shaLine = '';
     if (baseSha || headSha) {
-      shaLine = '<span class="swarm-diff-sha" style="font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:11px;color:#7c8aa6;">'
+      shaLine = '<span class="swarm-diff-sha" style="font-family:' + MONO + ';font-size:11px;color:' + MUTED + ';">'
         + esc(baseSha) + ' → ' + esc(headSha)
         + '</span>';
     }
@@ -515,8 +529,8 @@ export const SWARM_UI_JS = `
 
     rootEl.innerHTML = (
       '<div class="swarm-diff-root" style="border:1px solid var(--swarm-border,#22304a);border-radius:8px;background:var(--swarm-card,#121826);overflow:hidden;margin:12px 0;break-inside:avoid;">'
-      + '<div class="swarm-diff-header" style="display:flex;align-items:center;justify-content:space-between;padding:10px 12px;background:rgba(59,130,246,0.10);border-bottom:1px solid var(--swarm-border,#22304a);">'
-      + '<span class="swarm-diff-file" style="font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:13px;font-weight:700;color:var(--swarm-text,#e6eaf2);">' + esc(file || '(untitled)') + '</span>'
+      + '<div class="swarm-diff-header" style="display:flex;align-items:center;justify-content:space-between;padding:10px 12px;background:var(--color-surface, rgba(59,130,246,0.10));border-bottom:1px solid var(--swarm-border,#22304a);">'
+      + '<span class="swarm-diff-file" style="font-family:' + MONO + ';font-size:13px;font-weight:700;color:var(--swarm-text,#e6eaf2);">' + esc(file || '(untitled)') + '</span>'
       + shaLine
       + '</div>'
       + hunksHtml
@@ -580,21 +594,34 @@ export const SWARM_UI_JS = `
       var renderJumps = function() {
         var anchors = document.querySelectorAll('.swarm-diff-anchor[data-hunk]');
         if (!anchors.length) {
-          self.innerHTML = '<span class="no-print" style="color:#7c8aa6;font-size:12px;">No hunks yet.</span>';
+          self.innerHTML = '<span class="no-print" style="color:' + MUTED + ';font-size:12px;">No hunks yet.</span>';
           return;
         }
-        var items = '';
+        var labels = [];
+        var fileCounts = new Map();
         for (var i = 0; i < anchors.length; i++) {
           var a = anchors[i];
           var slug = a.getAttribute('data-hunk') || ('hunk-' + i);
           // Hunk title = nearest preceding diff's file attribute if available.
           var diff = a.closest && a.closest('swarm-diff');
           var file = (diff && diff.getAttribute('file')) || slug;
-          items += '<li style="margin:0;padding:2px 0;"><a href="#' + esc(a.id) + '" style="color:#3b82f6;text-decoration:none;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:12px;">' + esc(file) + '</a></li>';
+          labels.push(file);
+          fileCounts.set(file, (fileCounts.get(file) || 0) + 1);
+        }
+        var items = '';
+        for (var n = 0; n < anchors.length; n++) {
+          // A file with more than one hunk gets each hunk's new-side start
+          // line (src/x.ts:58), so its links differ.
+          var label = labels[n];
+          var newStart = anchors[n].getAttribute('data-new-start');
+          if (fileCounts.get(label) > 1 && newStart) label += ':' + newStart;
+          // target=_self: the page head sets <base target="_blank">, which would
+          // open these in-page anchors in a new tab.
+          items += '<li style="margin:0;padding:2px 0;"><a href="#' + esc(anchors[n].id) + '" target="_self" style="color:var(--color-primary, #3b82f6);text-decoration:none;font-family:' + MONO + ';font-size:12px;">' + esc(label) + '</a></li>';
         }
         self.innerHTML = (
-          '<nav class="swarm-diff-jumps no-print" style="padding:8px 12px;border:1px dashed var(--swarm-border,#22304a);border-radius:8px;background:rgba(124,138,166,0.05);">'
-          + '<div style="font-size:10px;text-transform:uppercase;letter-spacing:0.08em;color:#7c8aa6;margin-bottom:4px;">Jump to</div>'
+          '<nav class="swarm-diff-jumps no-print" style="padding:8px 12px;border:1px dashed var(--swarm-border,#22304a);border-radius:8px;background:' + tint('var(--color-muted-foreground, rgb(124,138,166))', '5%') + ';">'
+          + '<div style="font-size:10px;text-transform:uppercase;letter-spacing:0.08em;color:' + MUTED + ';margin-bottom:4px;">Jump to</div>'
           + '<ul style="list-style:none;padding:0;margin:0;">' + items + '</ul>'
           + '</nav>'
         );

package/src/pages/color-literals.ts

@@ -0,0 +1,115 @@
+/**
+ * Hardcoded colors in an HTML page body. A design version 2 page should take
+ * every color from a theme token. A body with `COLOR_LITERAL_THRESHOLD` or more
+ * hardcoded colors gets two things: `create_page` steers its author toward
+ * tokens (`NUDGES.create_page`), and `/p/:id` serves it light also when the
+ * viewer asks for dark mode, because its hardcoded light surfaces would put
+ * dark-mode text on them.
+ */
+
+/** From this many hardcoded colors on, a page counts as hardcoded. */
+export const COLOR_LITERAL_THRESHOLD = 8;
+
+/**
+ * A `<style>` block (an unclosed one runs to the end of the body), a `style="..."`
+ * attribute, or a `class="..."` attribute. The tag's own attributes are capped at
+ * 200 characters: an unbounded `[^>]*` makes a body of many unterminated `<style`
+ * tags cost quadratic time.
+ */
+const STYLE_BLOCK = /<style\b[^>]{0,200}>([\s\S]*?)(?:<\/style\s*>|$)/gi;
+const STYLE_ATTRIBUTE = /\sstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+const CLASS_ATTRIBUTE = /\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+/**
+ * In style regions: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, and the rgb, rgba,
+ * hsl, hsla and oklch functions.
+ */
+const COLOR_LITERAL = /#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{3,4})\b|\b(?:rgba?|hsla?|oklch)\(/gi;
+/**
+ * In style regions: the `white` and `black` keywords as values, not inside a name
+ * such as `white-space`, `.white` or `--black`. Lowercase only, so a font name such
+ * as "Archivo Black" does not count.
+ */
+const NAMED_COLOR = /(?<![\w.#-])(?:white|black)(?![\w-])/g;
+const PALETTE_UTILITIES = [
+  "bg",
+  "text",
+  "border",
+  "ring",
+  "outline",
+  "divide",
+  "fill",
+  "stroke",
+  "from",
+  "via",
+  "to",
+  "decoration",
+  "accent",
+  "caret",
+  "placeholder",
+  "shadow",
+];
+const TAILWIND_PALETTE = [
+  "slate",
+  "gray",
+  "zinc",
+  "neutral",
+  "stone",
+  "red",
+  "orange",
+  "amber",
+  "yellow",
+  "lime",
+  "green",
+  "emerald",
+  "teal",
+  "cyan",
+  "sky",
+  "blue",
+  "indigo",
+  "violet",
+  "purple",
+  "fuchsia",
+  "pink",
+  "rose",
+];
+/**
+ * In class attributes: Tailwind palette classes (`bg-blue-500`, `hover:text-gray-600/80`),
+ * `bg-white`, `bg-black`, `text-white`, `text-black`, and arbitrary color values
+ * (`bg-[#fff]`, `text-[rgb(0_0_0)]`, `-[hsl`, `-[oklch`).
+ */
+const COLOR_CLASS = new RegExp(
+  `(?<![\\w-])(?:(?:${PALETTE_UTILITIES.join("|")})-(?:${TAILWIND_PALETTE.join("|")})-\\d+|(?:bg|text)-(?:white|black))(?![\\w-])|-\\[(?:#|rgb|hsl|oklch)`,
+  "g",
+);
+
+function attributeValues(html: string, attribute: RegExp): string[] {
+  return Array.from(html.matchAll(attribute), (match) => match[1] ?? match[2] ?? "");
+}
+
+/** The values of every `class="..."` attribute in an HTML body. */
+export function classAttributeValues(html: string): string[] {
+  return attributeValues(html, CLASS_ATTRIBUTE);
+}
+
+function countMatches(regions: string[], pattern: RegExp): number {
+  return regions.reduce((total, region) => total + (region.match(pattern)?.length ?? 0), 0);
+}
+
+/**
+ * Counts the hardcoded colors of an HTML page body: color literals and the
+ * `white` / `black` keywords in its `<style>` blocks and `style="..."`
+ * attributes, and color classes in its `class="..."` attributes. A page on the
+ * design system should use theme tokens instead, so a high count means a theme
+ * switch will not restyle it.
+ */
+export function countColorLiterals(html: string): number {
+  const styles = [
+    ...Array.from(html.matchAll(STYLE_BLOCK), (match) => match[1] ?? ""),
+    ...attributeValues(html, STYLE_ATTRIBUTE),
+  ];
+  return (
+    countMatches(styles, COLOR_LITERAL) +
+    countMatches(styles, NAMED_COLOR) +
+    countMatches(classAttributeValues(html), COLOR_CLASS)
+  );
+}