@desplega.ai/agent-swarm 2.7.5 → 2.7.7

package/src/utils/internal-ai/task-title.ts

@@ -0,0 +1,282 @@
+/**
+ * Task title generation: a short display title for a task prompt.
+ *
+ * Consumer of `completeStructuredWithModel`. Walks `TASK_TITLE_MODEL_CANDIDATES`
+ * (provider order, then model order) and returns the first title a configured
+ * credential produces. Every candidate is a cheap, fast model: one title costs
+ * well under a tenth of a cent, so thousands of weekly tasks stay in cents.
+ *
+ * Worker-safe: no bun:sqlite import. The API server wires it to task creation
+ * in `src/be/task-auto-title-listener.ts`.
+ */
+
+import { Type } from "typebox";
+import { z } from "zod";
+import { scrubSecrets } from "../secret-scrubber.js";
+import { completeStructuredWithModel } from "./complete-structured.js";
+import { type CredentialKind, type ResolvedCredential, resolveCredentials } from "./credentials.js";
+import { kindForModelString } from "./models.js";
+
+/** Longest generated title. The PATCH /api/tasks/{id}/title route allows 120. */
+export const TASK_TITLE_MAX_CHARS = 100;
+/** Prompts shorter than this keep the prompt itself as the display title. */
+export const TASK_TITLE_MIN_TASK_CHARS = 48;
+/** Prompt text sent to the model is cut here. Keeps every call small. */
+export const TASK_TITLE_MAX_TASK_CHARS = 2000;
+/** Whole generation, across every candidate. */
+export const TASK_TITLE_TIMEOUT_MS = 20_000;
+
+/** Env var that pins one model (`provider/model-id`, or a `claude -p` alias). */
+export const TASK_TITLE_MODEL_ENV = "TASK_AUTO_TITLE_MODEL";
+
+export interface TaskTitleCandidateGroup {
+  kind: CredentialKind;
+  /** Full model strings for this credential kind, best first. */
+  models: readonly string[];
+}
+
+/**
+ * Provider order, then model order within a provider. Cheapest and fastest
+ * first: pay-per-token API keys before subscription OAuth, and the `claude -p`
+ * shellout last (it spawns a full CLI process per call).
+ *
+ * Model prices (input / output, USD per million tokens, models.dev snapshot):
+ *   deepseek-v4.1-flash 0.034 / 0.137 · claude-haiku-5.5 0.10 / 0.50 ·
+ *   gpt-6-luna 0.10 / 0.50 · gpt-5-nano 0.05 / 0.40
+ */
+export const TASK_TITLE_MODEL_CANDIDATES: readonly TaskTitleCandidateGroup[] = [
+  {
+    kind: "openrouter",
+    models: [
+      "openrouter/deepseek/deepseek-v4.1-flash",
+      "openrouter/anthropic/claude-haiku-5.5",
+      "openrouter/openai/gpt-6-luna",
+    ],
+  },
+  { kind: "anthropic", models: ["anthropic/claude-haiku-5-5"] },
+  { kind: "openai", models: ["openai/gpt-6-luna", "openai/gpt-5-nano"] },
+  { kind: "openai-codex", models: ["openai-codex/gpt-6-luna"] },
+  { kind: "claude-cli", models: ["haiku"] },
+];
+
+export { kindForModelString };
+
+/**
+ * The candidate list for one environment. `TASK_AUTO_TITLE_MODEL` moves its
+ * provider to the front and puts the pinned model first inside it; the rest of
+ * the list stays as fallback. An unknown provider is ignored with a warning.
+ */
+export function buildTaskTitlePlan(
+  env: Record<string, string | undefined> = process.env,
+): readonly TaskTitleCandidateGroup[] {
+  const pinned = env[TASK_TITLE_MODEL_ENV]?.trim();
+  if (!pinned) return TASK_TITLE_MODEL_CANDIDATES;
+  const kind = kindForModelString(pinned);
+  if (!kind) {
+    console.warn(
+      `[task-title] ${TASK_TITLE_MODEL_ENV}=${pinned} names an unsupported provider; ignored`,
+    );
+    return TASK_TITLE_MODEL_CANDIDATES;
+  }
+  const own = TASK_TITLE_MODEL_CANDIDATES.find((group) => group.kind === kind);
+  const rest = TASK_TITLE_MODEL_CANDIDATES.filter((group) => group.kind !== kind);
+  const models = [pinned, ...(own?.models ?? []).filter((model) => model !== pinned)];
+  return [{ kind, models }, ...rest];
+}
+
+const SIBLING_OPEN = "<sibling_tasks_in_progress>";
+const SIBLING_CLOSE = "</sibling_tasks_in_progress>";
+
+/**
+ * Task text as the model should see it: without the sibling-awareness block
+ * the API prepends to child tasks, with runs of blank lines collapsed, and cut
+ * to `TASK_TITLE_MAX_TASK_CHARS`.
+ */
+export function prepareTaskTextForTitle(task: string): string {
+  let text = task;
+  if (text.startsWith(SIBLING_OPEN)) {
+    const close = text.indexOf(SIBLING_CLOSE);
+    if (close !== -1) text = text.slice(close + SIBLING_CLOSE.length);
+  }
+  text = text
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+  if (text.length > TASK_TITLE_MAX_TASK_CHARS) {
+    text = `${text.slice(0, TASK_TITLE_MAX_TASK_CHARS).trimEnd()} …`;
+  }
+  return text;
+}
+
+const WRAPPING_QUOTES: ReadonlyArray<[string, string]> = [
+  ['"', '"'],
+  ["'", "'"],
+  ["“", "”"],
+  ["‘", "’"],
+  ["`", "`"],
+  ["«", "»"],
+];
+
+/**
+ * Clean a model-produced title: one line, no wrapping quotes or `Title:`
+ * prefix, no markdown emphasis, no trailing sentence punctuation, at most
+ * `TASK_TITLE_MAX_CHARS` (cut at a word boundary). Empty string when nothing
+ * usable remains.
+ */
+export function normalizeTaskTitle(raw: string): string {
+  let title = raw.replace(/\s+/g, " ").trim();
+  title = title.replace(/^title\s*:\s*/i, "");
+  title = title.replace(/\*\*|__|^#+\s*/g, "");
+  const stripTrailingPunctuation = () => {
+    title = title.replace(/[.!…]+$/u, "").trim();
+  };
+  // Quotes can sit inside or outside the trailing punctuation: `"Title".` and `"Title…"`.
+  stripTrailingPunctuation();
+  for (const [open, close] of WRAPPING_QUOTES) {
+    if (title.length >= 2 && title.startsWith(open) && title.endsWith(close)) {
+      title = title.slice(open.length, title.length - close.length).trim();
+    }
+  }
+  stripTrailingPunctuation();
+  if (title.length > TASK_TITLE_MAX_CHARS) {
+    const cut = title.slice(0, TASK_TITLE_MAX_CHARS);
+    const lastSpace = cut.lastIndexOf(" ");
+    title = (lastSpace >= TASK_TITLE_MAX_CHARS / 2 ? cut.slice(0, lastSpace) : cut).trimEnd();
+    title = title.replace(/[,;:\-–—]+$/u, "").trimEnd();
+  }
+  return title;
+}
+
+export const TASK_TITLE_SYSTEM_PROMPT = [
+  "You write titles for tasks on a software team's dashboard.",
+  "Rules:",
+  "- 3 to 8 words, at most 80 characters.",
+  "- Sentence case. No trailing period. No quotes, markdown, emoji, or task ids.",
+  "- Name the concrete subject (feature, bug, repo, file, system, person), not a generic verb alone.",
+  "- Keep the language of the request.",
+  "- Ignore pasted logs, code, and context blocks; title the request itself.",
+  "Call the set_title tool with the title.",
+].join("\n");
+
+export const TASK_TITLE_TOOL_NAME = "set_title";
+
+const TaskTitleZodSchema = z.object({ title: z.string().trim().min(1).max(200) });
+const TaskTitleToolSchema = Type.Object({
+  title: Type.String({ minLength: 1, maxLength: 200, description: "The task title." }),
+});
+
+export interface GenerateTaskTitleOptions {
+  /** Full task prompt as stored on the task. */
+  task: string;
+  /** Credential lookup env. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** Optional loopback context for the codex OAuth probe (see `resolveCredentials`). */
+  apiUrl?: string;
+  apiKey?: string;
+  signal?: AbortSignal;
+  /** Diagnostic tag forwarded to `completeStructured` logs. */
+  callerTag?: string;
+  // Test injection points:
+  _resolveCredentials?: typeof resolveCredentials;
+  _completeStructured?: typeof completeStructuredWithModel;
+}
+
+export type GenerateTaskTitleResult =
+  | { ok: true; title: string; model: string; kind: CredentialKind }
+  | { ok: false; reason: "short-task" | "no-credentials" | "all-models-failed" };
+
+/**
+ * Generate a title for `task`. Never throws: a provider error moves on to the
+ * next candidate, and exhausting the list returns `{ ok: false }`.
+ */
+export async function generateTaskTitle(
+  opts: GenerateTaskTitleOptions,
+): Promise<GenerateTaskTitleResult> {
+  const text = prepareTaskTextForTitle(opts.task);
+  if (text.length < TASK_TITLE_MIN_TASK_CHARS) return { ok: false, reason: "short-task" };
+
+  const env = opts.env ?? process.env;
+  const resolve = opts._resolveCredentials ?? resolveCredentials;
+  const complete = opts._completeStructured ?? completeStructuredWithModel;
+  const callerTag = opts.callerTag ?? "task-title";
+  const plan = buildTaskTitlePlan(env);
+
+  // One lookup per kind, on demand, so the codex OAuth probe (an HTTP call
+  // that can rotate a refresh token) runs only when its turn comes.
+  const credentialCache = new Map<CredentialKind, ResolvedCredential | null>();
+  const credentialFor = async (kind: CredentialKind): Promise<ResolvedCredential | null> => {
+    const cached = credentialCache.get(kind);
+    if (cached !== undefined) return cached;
+    const [cred] = await resolve({
+      env,
+      apiUrl: opts.apiUrl,
+      apiKey: opts.apiKey,
+      callerTag,
+      kinds: [kind],
+      limit: 1,
+    });
+    credentialCache.set(kind, cred ?? null);
+    return cred ?? null;
+  };
+
+  let sawCredential = false;
+  for (const group of plan) {
+    if (opts.signal?.aborted) break;
+    const cred = await credentialFor(group.kind);
+    if (!cred) continue;
+    sawCredential = true;
+    for (const model of group.models) {
+      if (opts.signal?.aborted) break;
+      const title = await attemptTitle(complete, {
+        cred,
+        model,
+        text,
+        env,
+        callerTag,
+        signal: opts.signal,
+      });
+      if (title) return { ok: true, title, model, kind: cred.kind };
+    }
+  }
+  return { ok: false, reason: sawCredential ? "all-models-failed" : "no-credentials" };
+}
+
+interface TitleAttempt {
+  cred: ResolvedCredential;
+  model: string;
+  text: string;
+  env: Record<string, string | undefined>;
+  callerTag: string;
+  signal?: AbortSignal;
+}
+
+/** One model call. `completeStructuredWithModel` swallows provider errors; a throw here is still just a miss. */
+async function attemptTitle(
+  complete: typeof completeStructuredWithModel,
+  attempt: TitleAttempt,
+): Promise<string> {
+  try {
+    const result = await complete({
+      zodSchema: TaskTitleZodSchema,
+      toolSchema: TaskTitleToolSchema,
+      toolName: TASK_TITLE_TOOL_NAME,
+      toolDescription: "Record the title for this task.",
+      systemPrompt: TASK_TITLE_SYSTEM_PROMPT,
+      userPrompt: `Task request:\n\n${attempt.text}`,
+      env: attempt.env,
+      retries: 1,
+      signal: attempt.signal,
+      callerTag: `${attempt.callerTag}:${attempt.model}`,
+      _credentialOverride: { ...attempt.cred, modelDefault: attempt.model },
+    });
+    return result ? normalizeTaskTitle(result.data.title) : "";
+  } catch (error) {
+    // Provider errors can echo request fragments; scrub before logging.
+    console.error(
+      scrubSecrets(
+        `[task-title] ${attempt.model} threw: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+    );
+    return "";
+  }
+}

package/src/utils/page-session.ts

@@ -27,7 +27,9 @@
  */
 import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import type { IncomingHttpHeaders } from "node:http";
 import path from "node:path";
+import { isDevOrTestNodeEnv } from "./node-env";
 
 const ENV_SECRET = "PAGE_SESSION_SECRET";
 const ENV_SECRET_FILE = "PAGE_SESSION_SECRET_FILE";
@@ -336,6 +338,41 @@ export async function extractAndVerifyCookie(
  */
 const PAGE_SESSION_TTL_SECONDS = 3600;
 
+const LOCAL_DEV_HOSTNAMES = new Set(["localhost", "127.0.0.1"]);
+
+/** True only for a parsed `http:` URL whose hostname is exactly a loopback dev name. */
+function isLocalHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" && LOCAL_DEV_HOSTNAMES.has(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Decide the `dev` flag for `issuePageSessionCookie`. Shared by the launch
+ * endpoint (`src/http/pages.ts`) and the password flow on `/p/:id`
+ * (`src/http/pages-public.ts`) so both issue the same cookie.
+ *
+ * Fails closed: only an explicit development or test NODE_ENV can soften the
+ * cookie. Deployed images leave NODE_ENV unset and get `SameSite=None; Secure`.
+ * In dev, the request must come from `http://localhost` or `http://127.0.0.1`
+ * (parsed, so `http://localhost.evil.example` does not match). Without an
+ * Origin, the Host header decides; a missing Host counts as local.
+ * Anything else, including portless `https://*.localhost`, keeps
+ * `SameSite=None; Secure` so the cookie travels on cross-site fetches.
+ * Chrome treats localhost as a secure context, so Secure also works over http.
+ */
+export function isLocalDevPageRequest(req: { headers: IncomingHttpHeaders }): boolean {
+  if (!isDevOrTestNodeEnv()) return false;
+  const origin = req.headers.origin ?? "";
+  if (origin !== "") return isLocalHttpUrl(origin);
+  const host = req.headers.host;
+  if (!host) return true;
+  return isLocalHttpUrl(`http://${host}`);
+}
+
 /**
  * Mint a signed page-session token + build the `Set-Cookie` header value for
  * `pageId`. Shared by the bearer-authed launch endpoint (`src/http/pages.ts`)

package/templates/schedules/daily-status-report/content.md

@@ -27,7 +27,93 @@ You are Lead. Produce one digest covering workflows, schedule runs, agents, task
 Call `GET $MCP_BASE_URL/status` and read `status.automations`. List every automation whose state is `needs_setup`, its missing parameters/integrations, and its `fixUrl`. This is the first digest section and the first failure classification; it is setup work, not an automation failure.
 
 ### 1B. Workflows and schedules
-Run the same six-query set as `daily-workflow-health-audit` Phase 1 (hard-failed workflow runs, hard-failed schedule-spawned tasks, halted >24h runs, silent-empty-output completions, cron-didn't-fire, schedules with ≥3 consecutive errors — all against `workflow_runs` / `agent_tasks` / `scheduled_tasks` via `db-query`), plus:
+Run these six failure-mode queries with `db-query`:
+
+**1.** Hard-failed workflow runs (last 24h)
+
+```sql
+SELECT wr.id, w.name AS workflowName, wr.status,
+       wr.finishedAt, wr.lastUpdatedAt,
+       SUBSTR(COALESCE(wr.error, ''), 1, 220) AS errSnippet
+FROM workflow_runs wr
+JOIN workflows w ON w.id = wr.workflowId
+WHERE wr.status = 'failed'
+  AND datetime(COALESCE(wr.finishedAt, wr.lastUpdatedAt, wr.startedAt)) > datetime('now', '-24 hours')
+ORDER BY wr.lastUpdatedAt DESC;
+```
+
+**2.** Hard-failed schedule-spawned tasks (last 24h)
+
+```sql
+SELECT t.id, s.name AS scheduleName, t.status,
+       SUBSTR(COALESCE(t.failureReason, ''), 1, 220) AS reasonSnippet,
+       SUBSTR(COALESCE(t.output, ''), 1, 220) AS outSnippet,
+       t.lastUpdatedAt
+FROM agent_tasks t
+LEFT JOIN scheduled_tasks s ON s.id = t.scheduleId
+WHERE t.status = 'failed'
+  AND t.scheduleId IS NOT NULL
+  AND datetime(t.lastUpdatedAt) > datetime('now', '-24 hours')
+ORDER BY t.lastUpdatedAt DESC;
+```
+
+**3.** Halted >24h workflow runs (silent stuck)
+
+```sql
+SELECT wr.id, w.name AS workflowName, wr.status, wr.lastUpdatedAt
+FROM workflow_runs wr
+JOIN workflows w ON w.id = wr.workflowId
+WHERE wr.status IN ('running', 'waiting')
+  AND datetime(wr.lastUpdatedAt) < datetime('now', '-24 hours')
+ORDER BY wr.lastUpdatedAt ASC;
+```
+
+**4.** Silent: schedule-spawned task completed with empty/sentinel output
+
+```sql
+SELECT t.id, s.name AS scheduleName, t.status,
+       SUBSTR(COALESCE(t.output, ''), 1, 220) AS outSnippet,
+       LENGTH(TRIM(COALESCE(t.output, ''))) AS outLen,
+       t.lastUpdatedAt
+FROM agent_tasks t
+LEFT JOIN scheduled_tasks s ON s.id = t.scheduleId
+WHERE t.status = 'completed'
+  AND t.scheduleId IS NOT NULL
+  AND datetime(t.lastUpdatedAt) > datetime('now', '-24 hours')
+  AND (
+    t.output IS NULL
+    OR TRIM(t.output) = ''
+    OR TRIM(t.output) = '⚡ Running shell command'
+    OR LENGTH(TRIM(t.output)) < 10
+  )
+ORDER BY t.lastUpdatedAt DESC;
+```
+
+**5.** Cron didn't fire (nextRunAt in the past)
+
+```sql
+SELECT s.id, s.name, s.cronExpression, s.lastRunAt, s.nextRunAt, s.consecutiveErrors,
+       SUBSTR(COALESCE(s.lastErrorMessage, ''), 1, 220) AS lastErrSnippet
+FROM scheduled_tasks s
+WHERE s.enabled = 1
+  AND s.scheduleType = 'recurring'
+  AND s.nextRunAt IS NOT NULL
+  AND datetime(s.nextRunAt) < datetime('now', '-1 hour')
+ORDER BY s.nextRunAt ASC;
+```
+
+**6.** Schedules with consecutive errors (defensive)
+
+```sql
+SELECT s.id, s.name, s.cronExpression, s.consecutiveErrors, s.lastErrorAt,
+       SUBSTR(COALESCE(s.lastErrorMessage, ''), 1, 220) AS lastErrSnippet
+FROM scheduled_tasks s
+WHERE s.enabled = 1
+  AND s.consecutiveErrors >= 3
+ORDER BY s.consecutiveErrors DESC;
+```
+
+Plus:
 - Enabled/disabled counts: `SELECT enabled, COUNT(*) FROM scheduled_tasks GROUP BY enabled` and the workflow equivalent.
 - 7-day rollup, not just 24h: repeat the hard-failure and cron-didn't-fire queries with a `-7 days` window for a weekly trend line.
 
@@ -87,7 +173,7 @@ More than 3 qualify ⇒ post the 3 that matter and put the rest in the task outp
 `store-progress` with `status: "completed"`. **This is where the detail goes** — every count from Phase 1, the per-class failure breakdown, and the Slack message ts. The Slack post is the headline; the task output is the record. Cutting the post does not mean cutting the work.
 
 ## Anti-patterns
-- ❌ Modifying anything — this schedule reports, it doesn't fix (that's `daily-workflow-health-audit` for plumbing and `daily-compounding-reflection` for agent/skill/memory evolution).
+- ❌ Modifying anything — this schedule reports, it doesn't fix (that's `daily-compounding-reflection` for agent/skill/memory evolution).
 - ❌ Folding the unclassified-failure bucket into "real defect" to make the number look more actionable than it is.
 - ❌ Narrating a zero. The all-clear line already covers `needs_setup` and integrations; only a non-verified integration or a real `needs_setup` automation earns its own line.
 - ❌ Exceeding 600 characters, or posting more than one message.

package/templates/schedules/daily-swarm-update-check/content.md

@@ -2,48 +2,24 @@
 
 Zero-config auto-update watchdog: compares the swarm's own running version against the latest published GitHub release of `desplega-ai/agent-swarm`, and flags the operator when an upgrade is available. No placeholders and no integration required — every install gets this by default.
 
-## Schedule
-
-```json
-{"cron":"0 9 * * *","timezone":"UTC","agentRole":"lead","enabled":true}
-```
-
-## Scheduled Task
-
-This schedule runs by default. It needs no repository clone and no integration — it only reads its own task metadata and calls the public GitHub API.
-
-Task Type: Daily Agent-Swarm Update Check
-
-You are Lead. Determine whether a newer `desplega-ai/agent-swarm` release is published than the version currently running on this install, and tell the operator if so.
-
-## Phase 1 — Determine the running version
+This is a script schedule: each fire runs the global `swarm-update-check` script directly, with no agent task in between. The script:
 
-Call `get-task-details` for THIS task's own id and read `task.swarmVersion` — the API server stamps every task with the `package.json` version it was running at task-creation time, so this is the version currently deployed on this install.
+1. Reads the running version from the API server's own `/health` route.
+2. Fetches `https://api.github.com/repos/desplega-ai/agent-swarm/releases/latest` once and reads `tag_name` and `html_url`.
+3. Compares the two as numeric `major.minor.patch`, never as strings (`"1.9.0" < "1.10.0"` is false as strings).
+4. Only when the latest release is newer, sends the lead one task to post the notice to its configured admin delivery channel (the in-app fallback if none is configured).
 
-If `swarmVersion` is missing or empty (an older install, or the field predates this schedule), complete with `output`: `"Unable to determine running version — swarmVersion not set on this task."` and stop. Do not guess a version.
+Up to date, a missing running version (reported as `unknown`, never as up to date) and an unreachable GitHub API all end the run without any agent task. A failed GitHub call is reported once and never retried in a loop. The check never attempts the upgrade; `weekly-harness-upgrade-check` is the separate routine that bumps pinned harness versions inside the repo.
 
-## Phase 2 — Fetch the latest published release
+## Schedule
 
-```bash
-curl -fsSL https://api.github.com/repos/desplega-ai/agent-swarm/releases/latest
+```json
+{
+  "cron": "0 9 * * *",
+  "timezone": "UTC",
+  "enabled": true,
+  "targetType": "script",
+  "scriptName": "swarm-update-check",
+  "scriptArgs": {}
+}
 ```
-
-Read `.tag_name` (strip a leading `v` if present) and `.html_url`. If the request fails (network, rate limit, non-200), complete with `output`: `"Could not reach GitHub releases API: <error>"` and stop — do not retry in a loop.
-
-## Phase 3 — Compare and act
-
-Compare the two versions as dotted numeric triples (major.minor.patch) — never as plain strings (`"1.9.0" < "1.10.0"` is false as strings).
-
-- **Latest <= running:** complete with `output`: `"Up to date: running <running>, latest published <latest>."` No further action.
-- **Latest > running:** raise it for the operator:
-  1. Post a short message to your configured admin delivery channel (or the in-app fallback if none is configured) naming the running version, the new version, and the release URL.
-  2. Complete `store-progress` with `status: "completed"` and `output`: `"Update available: running <running>, latest <latest> — <releaseUrl>"`.
-
-Do not attempt the upgrade yourself — this schedule only detects and reports. `weekly-harness-upgrade-check` is the separate routine that bumps pinned harness versions inside the repo; this schedule is about the agent-swarm release itself.
-
-## Anti-patterns
-
-- ❌ Cloning the repo or reading `package.json` from disk — this schedule must work on any install, including ones where the API pod has no repo checkout.
-- ❌ String-comparing versions.
-- ❌ Treating a missing `swarmVersion` as "no update available" — it's "unknown", say so explicitly.
-- ❌ Retrying a failed GitHub API call in a loop.

package/templates/skills/apps/SKILL.md

@@ -133,7 +133,7 @@ Use `{ "$state": "/user/<field>" }` on a page for the read-only current-user bin
 
 ### Theming
 
-An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas — a lowercase slug validated by shape only. The preset catalog ships with the dashboard (`apps/ui/src/lib/themes.ts` + `theme-classics.ts` — update this list and the `app-upsert` tool description when it changes); current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette — hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
+An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas: a lowercase slug validated by shape only. The preset catalog ships with the dashboard and lives in `src/themes/presets.ts` and `src/themes/classics.ts`. Update this list and the `app-upsert` tool description when it changes. Current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, `paper` (the warm editorial paper look), and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette: hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
 
 Viewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.
 

package/templates/skills/apps/content.md

@@ -128,7 +128,7 @@ Use `{ "$state": "/user/<field>" }` on a page for the read-only current-user bin
 
 ### Theming
 
-An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas — a lowercase slug validated by shape only. The preset catalog ships with the dashboard (`apps/ui/src/lib/themes.ts` + `theme-classics.ts` — update this list and the `app-upsert` tool description when it changes); current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette — hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
+An optional top-level `"theme"` sets the preset the dashboard applies to the app's rendered canvas: a lowercase slug validated by shape only. The preset catalog ships with the dashboard and lives in `src/themes/presets.ts` and `src/themes/classics.ts`. Update this list and the `app-upsert` tool description when it changes. Current ids: `hive` (the stock look), the accent/field presets `meadow`, `iris`, `rose`, `cobalt`, `ember`, `carbon`, `paper` (the warm editorial paper look), and the classic editor/platform presets `github`, `vscode`, `material`, `solarized`, `tokyo`, `monokai`, `gruvbox`, `catppuccin`. Action and destructive tones are never themed; status tones are themed ONLY by the classic presets (their identity includes a status palette: hue semantics stay fixed, success reads green and error reads red everywhere). An id the viewer's dashboard build does not know degrades to the dashboard's own theme, so unknown slugs are safe but pointless. Omit `theme` to inherit whatever theme the viewer runs; `"hive"` is an explicit reset to the stock look even inside a themed dashboard.
 
 Viewers can override the preset per app from the app's settings drawer; the override rides the reserved `$theme` key of the user-config values (accepted on every app, even without a declared `userConfig` schema, and never visible at `/user/...`). A present override always beats the definition's `theme` — even an unrecognized one, which degrades to the dashboard theme — so treat `theme` as the app's default styling, not a guarantee.
 

package/templates/skills/composio-google-docs/content.md

@@ -80,6 +80,16 @@ Google Drive export, then preserve or reconstruct the structure explicitly.
 There is no `GET_DOCUMENT_MARKDOWN` tool; markdown exists on create/update, not
 on read.
 
+## Comments
+
+Doc comments are a Drive feature, not a Docs one: there is no `GOOGLEDOCS_*`
+comment slug. List them with `GOOGLEDRIVE_LIST_COMMENTS` (replies:
+`GOOGLEDRIVE_LIST_REPLIES`) from the `googledrive` toolkit, so resolve the
+user's `googledrive` connected account instead of their `googledocs` one.
+Listing only works when the Drive read scopes are authorized on that account.
+`GOOGLEDRIVE_CREATE_COMMENT` and the update/delete tools are write actions,
+only on explicit request.
+
 ## Gotchas
 
 - Search returns Drive metadata, not document content — do a second

package/templates/skills/heartbeat-runbook/content.md

@@ -35,7 +35,7 @@ Two kinds of sections:
 
 0. Quiet check. Take the fast path when three things hold: every failed, stalled or reboot-interrupted task in the system status was already named in the previous heartbeat-checklist task's output (newest completed one via `get-tasks`); no mention has gone unanswered since the last heartbeat; and no tracked item in the task's runbook snapshot is at or past its date. On the fast path, run the two step 3 scripts. If they report nothing the previous heartbeat had not already triaged, complete with exactly one line, `Quiet. Same as <previousTaskId>: <N> failures (triaged), schedule-health <M>/<total>, controls ok.`, and skip steps 1, 2 and 4-7. A longer quiet output is a defect: no failure-set recap, no per-script bullets. Anything new means continue at step 1.
 1. Read the latest runbook. The snapshot in the task may be stale.
-2. Prune first. Check every tracked item against its lift trigger. Remove resolved, stale, and past-date items. A trigger tied to a pull request ("lift when #N merges") fires silently: read the state of every PR a trigger names. Merged means the lift fired, so act on it now. Closed without merge means the item is dead, so drop it.
+2. Prune first. Check every tracked item against its lift trigger. Remove resolved, stale, and past-date items. A trigger tied to a pull request ("lift when #N merges") fires silently: read the state of every PR a trigger names. Merged means the lift fired, so act on it now. Closed without merge means the item is dead, so drop it. A PR's `mergeable` field reads `null` while the host is still computing it: `null` is unknown, never clean, so re-read until a value comes back and never treat it as a cleared blocker or as ready to merge.
 3. Run the seeded scripts: `script-run` with name `schedule-health`, then `task-failure-audit`, both with `args: { days: 1, publishPage: false }`. They report failing schedules and failure clusters. Check any other standing order in the runbook yourself.
 4. Read the system status and the script results for stalled tasks, idle workers next to open work, and anomalies.
 5. Reboot-interrupted failures: the failure reason "Auto-failed by reboot sweep: worker session not found after server restart" means a restart cut the task off. For each one: `get-task-details` on the task, confirm a retry task tagged `reboot-retry` exists and moves, recreate the task when no retry exists and the work is still needed. Heartbeat and triage tasks get no retry. A worker crash outside a restart ("worker session not found" or "worker session heartbeat is stale" from the stall sweep) normally leaves a `superseded` task with a `resume` child instead; check that the child moves. None of these are "expected cleanup".

package/templates/skills/pages/config.json

@@ -4,7 +4,7 @@
   "displayName": "Pages",
   "slug": "pages",
   "title": "Pages",
-  "description": "Publish human-readable task outputs as DB-backed shareable pages (HTML or JSON) via `create_page` — no server, no tunnel. Covers auth modes, share URLs, versioning, the injected browser SDK, the `<swarm-diff>` primitive, print/PDF export, limits, and the minimalist taste baseline plus report-density layer every page should follow.",
+  "description": "Publish human-readable task outputs as DB-backed shareable pages (HTML or JSON) via `create_page`, with no server and no tunnel. Covers auth modes, share URLs, versioning, the injected browser SDK, the `<swarm-diff>` web component, print/PDF export, and limits. Also covers the swarm design system every page should use: theme tokens, `swarm-*` primitives, Tailwind v4 utilities, theme presets, dark mode, and the minimalist taste and report-density rules.",
   "version": "2.0.0",
   "category": "skills",
   "placeholders": [],