@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/src/utils/credentials.ts

@@ -1,4 +1,10 @@
 import { existsSync } from "node:fs";
+import {
+  openAICompatibleProviders,
+  providerForKeyVar,
+  providerForModel,
+  providerKeyVars,
+} from "@desplega/model-catalog";
 import { deriveDefaultRoute, routeCredentialStatus } from "@desplega/model-routing";
 import { type ModelFamily, modelFamilyOf, windowForModelFamily } from "./model-rate-limit-windows";
 
@@ -14,8 +20,27 @@ export const CREDENTIAL_POOL_VARS = [
   "AMP_API_KEY",
   "CURSOR_API_KEY",
   "XAI_API_KEY",
+  // The canonical key var of every OpenAI-compatible registry provider
+  // (`@desplega/model-catalog`). Aliases are normalized into these by the
+  // runner (`normalizeProviderKeyAliases`), so they never pool.
+  ...openAICompatibleProviders().map((p) => p.envVar),
 ] as const;
 
+/**
+ * Copy the first set alias of each registry provider into its canonical key
+ * var when the canonical var is empty (`HELMCODE_API_NAN` → `NAN_API_KEY`).
+ * The runner runs this once per task, so pooling, credential checks, pi's
+ * runtime key and the opencode key splice only read the canonical name. An
+ * explicit canonical value wins. Mutates `env`.
+ */
+export function normalizeProviderKeyAliases(env: Record<string, string | undefined>): void {
+  for (const provider of openAICompatibleProviders()) {
+    if (env[provider.envVar]?.trim()) continue;
+    const alias = provider.aliasEnvVars.find((name) => env[name]?.trim());
+    if (alias) env[provider.envVar] = env[alias];
+  }
+}
+
 /**
  * Which credential env vars are relevant for each harness provider. The
  * runner uses this map to filter `CREDENTIAL_POOL_VARS` so a codex worker
@@ -76,6 +101,10 @@ export function getModelAwareCredentialVars(provider: string, model?: string): r
     return model.startsWith("openrouter/") ? ["OPENROUTER_API_KEY"] : ["XAI_API_KEY"];
   }
   if (!SLASH_MODEL_PROVIDERS.has(provider) || !model) return base;
+  // OpenAI-compatible registry providers own their key: `nan/<id>` and
+  // `helmcode/<id>` never pool an OpenRouter or Anthropic key.
+  const direct = providerForModel(model);
+  if (direct) return [direct.envVar];
   if (model.includes("/")) {
     return base.filter((v) => v !== "OPENAI_API_KEY");
   }
@@ -91,6 +120,8 @@ export function getModelAwareCredentialVars(provider: string, model?: string): r
  * usage with the active worker's HARNESS_PROVIDER.
  */
 export function deriveProviderFromKeyType(keyType: string): string {
+  // OpenAI-compatible registry keys (canonical or alias) default to pi.
+  if (providerForKeyVar(keyType)) return "pi";
   switch (keyType) {
     case "CLAUDE_CODE_OAUTH_TOKEN":
     case "ANTHROPIC_API_KEY":
@@ -210,7 +241,7 @@ function isJsonObject(value: string): boolean {
  * Falls back to random selection from all credentials if no available indices match.
  * A JSON object value (the CODEX_OAUTH blob) is always one credential.
  */
-function splitCredentialPool(value: string): string[] {
+export function splitCredentialPool(value: string): string[] {
   return isJsonObject(value)
     ? [value.trim()]
     : value
@@ -311,21 +342,38 @@ export function validateClaudeCredentials(env: Record<string, string | undefined
   return CLAUDE_CREDENTIAL_TYPE_BY_PROVIDER[route.provider] ?? route.provider;
 }
 
+/**
+ * One label per OpenAI-compatible registry provider for hints and errors:
+ * `NAN_API_KEY (or HELMCODE_API_NAN)`, `HELMCODE_API_KEY`.
+ */
+export function openAICompatibleKeyLabels(): string[] {
+  return openAICompatibleProviders().map((p) =>
+    p.aliasEnvVars.length > 0 ? `${p.envVar} (or ${p.aliasEnvVars.join(" or ")})` : p.envVar,
+  );
+}
+
 /**
  * Validate that at least one opencode credential is available.
- * Priority: OPENROUTER_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY → ~/.local/share/opencode/auth.json.
+ * Priority: OPENROUTER_API_KEY → ANTHROPIC_API_KEY → OPENAI_API_KEY → each
+ * OpenAI-compatible registry provider's key (canonical or alias, e.g.
+ * NAN_API_KEY or HELMCODE_API_NAN → `nan_api_key`) →
+ * ~/.local/share/opencode/auth.json.
  * Returns the credential type found, or throws if none are available.
  */
 export function validateOpencodeCredentials(
   env: Record<string, string | undefined>,
-): "openrouter_api_key" | "anthropic_api_key" | "openai_api_key" | "auth_file" {
+): "openrouter_api_key" | "anthropic_api_key" | "openai_api_key" | Lowercase<string> | "auth_file" {
   if (env.OPENROUTER_API_KEY) return "openrouter_api_key";
   if (env.ANTHROPIC_API_KEY) return "anthropic_api_key";
   if (env.OPENAI_API_KEY) return "openai_api_key";
+  const direct = openAICompatibleProviders().find((p) => providerKeyVars(p).some((n) => env[n]));
+  if (direct) return direct.envVar.toLowerCase() as Lowercase<string>;
   const authFile = `${process.env.HOME ?? "/root"}/.local/share/opencode/auth.json`;
   if (existsSync(authFile)) return "auth_file";
   throw new Error(
-    "No opencode credentials found. Set OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, or provide ~/.local/share/opencode/auth.json.",
+    `No opencode credentials found. Set OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, ${openAICompatibleKeyLabels()
+      .map((label) => `${label}, `)
+      .join("")}or provide ~/.local/share/opencode/auth.json.`,
   );
 }
 

package/src/utils/harness-provider.ts

@@ -1,3 +1,4 @@
+import { openAICompatibleKeyVars } from "@desplega/model-catalog";
 import { type ProviderName, ProviderNameSchema } from "../types";
 
 const SUPPORTED_PROVIDERS = ProviderNameSchema.options;
@@ -10,23 +11,31 @@ function hasEnvValue(
   return !!(resolvedEnv[key]?.trim() || fallbackEnv[key]?.trim());
 }
 
+/**
+ * LLM keys that make "pi" the default harness when no Claude credential is
+ * set: OpenRouter plus every OpenAI-compatible registry key (canonical or alias).
+ */
+const PI_DEFAULT_KEY_VARS = ["OPENROUTER_API_KEY", ...openAICompatibleKeyVars()];
+
 /**
  * Credential-aware default for when HARNESS_PROVIDER is unset or invalid.
  * Unconditionally defaulting to "claude" leaves an OpenRouter-only swarm —
  * e.g. every auto-deployed swarm, which is provisioned with
  * OPENROUTER_API_KEY and NEVER an Anthropic credential — unable to
- * authenticate at all. Prefer "pi" when an OpenRouter key is present and no
- * Claude credential is; otherwise keep the original "claude" default.
+ * authenticate at all. Prefer "pi" when an OpenRouter key or an
+ * OpenAI-compatible registry key (NaN, Helmcode; canonical or alias) is
+ * present and no Claude credential is; otherwise keep the original "claude"
+ * default.
  */
 function credentialAwareDefault(
   resolvedEnv: Record<string, string | undefined>,
   fallbackEnv: Record<string, string | undefined>,
 ): ProviderName {
-  const hasOpenRouterKey = hasEnvValue("OPENROUTER_API_KEY", resolvedEnv, fallbackEnv);
+  const hasPiKey = PI_DEFAULT_KEY_VARS.some((key) => hasEnvValue(key, resolvedEnv, fallbackEnv));
   const hasClaudeCredential =
     hasEnvValue("ANTHROPIC_API_KEY", resolvedEnv, fallbackEnv) ||
     hasEnvValue("CLAUDE_CODE_OAUTH_TOKEN", resolvedEnv, fallbackEnv);
-  return hasOpenRouterKey && !hasClaudeCredential ? "pi" : "claude";
+  return hasPiKey && !hasClaudeCredential ? "pi" : "claude";
 }
 
 /**
@@ -36,8 +45,8 @@ function credentialAwareDefault(
  *   1. `resolvedEnv.HARNESS_PROVIDER` — value coming from `swarm_config`
  *      (overlay produced by `fetchResolvedEnv`, scoped repo > agent > global).
  *   2. `fallbackEnv.HARNESS_PROVIDER` — raw `process.env`.
- *   3. Credential-aware default — "pi" when an OpenRouter key is present and
- *      no Anthropic credential is (see `credentialAwareDefault`), else
+ *   3. Credential-aware default — "pi" when an OpenRouter or registry
+ *      provider key is present and no Anthropic credential is (see `credentialAwareDefault`), else
  *      `"claude"`.
  *
  * Invalid values (anything outside `ProviderNameSchema`) log a warning and

package/src/utils/runtime-model-catalog.ts

@@ -17,6 +17,7 @@
  * NO database imports (worker-safe). Every lookup is synchronous; the HTTP
  * refresh is TTL-cached and never throws, so hot paths stay cheap.
  */
+import { type CatalogChatRow, withRegistryCatalogSections } from "@desplega/model-catalog";
 import modelsDevSnapshot from "../be/modelsdev-cache.json";
 
 export interface RuntimeCatalogModel {
@@ -38,7 +39,16 @@ export interface RuntimeCatalogProvider {
 
 export type RuntimeCatalog = Record<string, RuntimeCatalogProvider | undefined>;
 
-const SNAPSHOT = modelsDevSnapshot as RuntimeCatalog;
+// Plus the registry-synthesized sections models.dev does not list (`helmcode`).
+const SNAPSHOT = withRegistryCatalogSections(modelsDevSnapshot as RuntimeCatalog);
+
+/**
+ * One section's full snapshot rows (output limit, modalities, tool calling),
+ * which the slim live catalog drops. Harness config blocks read these.
+ */
+export function snapshotCatalogRows(provider: string): Record<string, CatalogChatRow> {
+  return (SNAPSHOT[provider]?.models ?? {}) as Record<string, CatalogChatRow>;
+}
 
 /** Default freshness window for the worker-side HTTP pull. */
 export const RUNTIME_CATALOG_TTL_MS = 10 * 60_000;

package/src/utils/secret-scrubber.ts

@@ -21,6 +21,7 @@
  * API↔worker DB boundary (scripts/check-db-boundary.sh).
  */
 
+import { openAICompatibleKeyVars } from "@desplega/model-catalog";
 import { GITLEAKS_RULES } from "./secret-rules.generated";
 
 /**
@@ -35,9 +36,13 @@ import { GITLEAKS_RULES } from "./secret-rules.generated";
  * 5, the vendored gitleaks rule set, plus hand-written Resend, Google OAuth,
  * Discord webhook, xAI and bare Telegram shapes in pass 2; v6 = pass 5 resumes
  * after the secret, not the match, so adjacent secrets that share a delimiter
- * both redact, and sourcegraph-access-token drops its bare 40-hex branch.
+ * both redact, and sourcegraph-access-token drops its bare 40-hex branch;
+ * v7 = the OpenAI-compatible registry key vars (`NAN_API_KEY`,
+ * `HELMCODE_API_KEY`, and the `HELMCODE_API_NAN` alias no suffix matches).
+ * A new registry entry adds key vars, so it is a rule change too
+ * (`secret-scrubber.test.ts` pins the list to this number).
  */
-export const SCRUBBER_RULES_VERSION = 6;
+export const SCRUBBER_RULES_VERSION = 8;
 
 /** Env-var names that are always considered secrets, even without suffix hints. */
 const SENSITIVE_KEY_EXACT = new Set<string>([
@@ -52,6 +57,9 @@ const SENSITIVE_KEY_EXACT = new Set<string>([
   "ANTHROPIC_API_KEY",
   "OPENAI_API_KEY",
   "OPENROUTER_API_KEY",
+  // OpenAI-compatible registry key vars, canonical and alias. An alias such
+  // as `HELMCODE_API_NAN` matches no SENSITIVE_KEY_SUFFIXES entry.
+  ...openAICompatibleKeyVars(),
   "SLACK_BOT_TOKEN",
   "SLACK_SIGNING_SECRET",
   "SLACK_CLIENT_SECRET",
@@ -1005,6 +1013,52 @@ export function scrubObject<T>(value: T, seen = new WeakSet<object>()): T {
   return out as T;
 }
 
+export type ValueScrubber = {
+  text(text: string): string;
+  object<T>(value: T): T;
+};
+
+/**
+ * Redact exact occurrences of the given values, at any length, in one output
+ * boundary that knows which secrets it handed out (a script run's secret
+ * config). The global passes above keep their MIN_VALUE_LENGTH floor; this
+ * one never registers anything swarm-wide. All forms match in a single regex
+ * pass, longest first, so one value's marker is never rewritten by another
+ * value's pass. Object keys are redacted too.
+ */
+export function createValueScrubber(
+  entries: Array<{ value: string; name: string }>,
+): ValueScrubber {
+  const names = new Map<string, string>();
+  for (const { value, name } of entries) {
+    if (!value) continue;
+    for (const form of escapedForms(value)) if (!names.has(form)) names.set(form, name);
+  }
+  if (names.size === 0) return { text: (text) => text, object: (value) => value };
+
+  const pattern = [...names.keys()]
+    .sort((a, b) => b.length - a.length)
+    .map(escapeRegExp)
+    .join("|");
+  const re = new RegExp(pattern, "g");
+  const text = (input: string) =>
+    input.replace(re, (match) => `[REDACTED:${names.get(match) ?? "secret"}]`);
+  const object = <T>(value: T, seen = new WeakSet<object>()): T => {
+    if (typeof value === "string") return text(value) as T;
+    if (value === null || typeof value !== "object") return value;
+    if (seen.has(value)) return "[Circular]" as T;
+    seen.add(value);
+    if (Array.isArray(value)) return value.map((item) => object(item, seen)) as T;
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
+        text(key),
+        object(child, seen),
+      ]),
+    ) as T;
+  };
+  return { text, object: (value) => object(value) };
+}
+
 /**
  * Force the env-value cache to rebuild on the next scrub call. Callers should
  * invoke this whenever the swarm_config is reloaded (`/internal/reload-config`
@@ -1031,6 +1085,21 @@ export function registerVolatileSecret(value: string, name: string): void {
   }
 }
 
+/**
+ * Register the sensitive values of an env map that is not `process.env`
+ * (a runner's per-task env, an adapter's session env). A key picked from a
+ * credential pool, or a row admitted after boot, lives only there, so the
+ * env pass never sees it. Comma-separated pools register each member too.
+ */
+export function registerEnvSecrets(env: Record<string, string | undefined>): void {
+  for (const [key, value] of Object.entries(env)) {
+    if (!value || !isSensitiveKey(key)) continue;
+    registerVolatileSecret(value, key);
+    if (!value.includes(",")) continue;
+    for (const member of value.split(",")) registerVolatileSecret(member.trim(), key);
+  }
+}
+
 /** Remove a short-lived secret and its encoded forms after credential revocation. */
 export function unregisterVolatileSecret(name: string): void {
   for (const [value, registeredName] of volatileSecrets) {

package/src/utils/task-tool-manifest.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { chatThreadOfContextKey } from "../tasks/context-key";
 import { ALL_TOOLS } from "../tools/tool-config";
 
 const toolNames = z
@@ -15,9 +16,22 @@ export function parseTaskToolManifest(value: string) {
   return taskToolManifestSchema.parse(JSON.parse(value));
 }
 
+/** Tools that act on the chat thread of the calling task; useless on any other task. */
+export const CHAT_TASK_ONLY_TOOLS: readonly string[] = ["chat-reply"];
+
+/** True when the task came from a Chat SDK thread (contextKey family `chat-sdk`). */
+export function isChatSdkTask(task: { contextKey?: string | null }): boolean {
+  return chatThreadOfContextKey(task.contextKey) !== null;
+}
+
 export function selectTaskTools(
   manifest: z.infer<typeof taskToolManifestSchema>,
-  task: { taskType?: string; scheduleId?: string; slackChannelId?: string },
+  task: {
+    taskType?: string;
+    scheduleId?: string;
+    slackChannelId?: string;
+    contextKey?: string | null;
+  },
 ): string[] {
   const fromSchedule =
     task.scheduleId && Object.hasOwn(manifest.schedules ?? {}, task.scheduleId)
@@ -27,7 +41,10 @@ export function selectTaskTools(
     task.taskType && Object.hasOwn(manifest.taskTypes ?? {}, task.taskType)
       ? manifest.taskTypes?.[task.taskType]
       : undefined;
+  const chatTask = isChatSdkTask(task);
   return [...new Set(fromSchedule ?? fromType ?? [])].filter(
-    (name) => !name.startsWith("slack-") || Boolean(task.slackChannelId),
+    (name) =>
+      (!name.startsWith("slack-") || Boolean(task.slackChannelId)) &&
+      (chatTask || !CHAT_TASK_ONLY_TOOLS.includes(name)),
   );
 }

package/src/workflows/executors/swarm-script.ts

@@ -127,6 +127,7 @@ export class SwarmScriptExecutor extends BaseExecutor<
       mcpBaseUrl: getMcpBaseUrl(),
       egressSecrets: credentials.egressSecrets,
       failedBindings: credentials.failedBindings,
+      userConfig: credentials.userConfig,
       apiConnections: getScriptApiConnectionDescriptors({ agentId: agentId ?? undefined }),
       mcpConnections: getScriptMcpConnectionDescriptors({ agentId: agentId ?? undefined }),
       timeoutMs: config.timeoutMs,

package/templates/skills/agent-browser/SKILL.md

@@ -84,7 +84,7 @@ agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --js
 - In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
-The `artifacts` skill holds the full agent-fs recipe and the naming conventions.
+The `agent-fs` skill holds the full agent-fs recipe.
 
 ## Gotchas
 

package/templates/skills/agent-browser/content.md

@@ -79,7 +79,7 @@ agent-fs share-create thoughts/<agent-id>/qa/<topic>-screenshots/<name>.png --js
 - In `store-progress`, list the upload in the `attachments` field with `kind: "agent-fs"` and the path, and paste the `share-create` link for people who need to open the file.
 - If `agent-fs auth whoami` fails, report the local path, say the upload was skipped, and continue.
 
-The `artifacts` skill holds the full agent-fs recipe and the naming conventions.
+The `agent-fs` skill holds the full agent-fs recipe.
 
 ## Gotchas
 

package/templates/skills/apps/SKILL.md

@@ -5,7 +5,7 @@ description: Build and iterate on schema-backed Swarm Apps with live models, nam
 
 # Swarm Apps
 
-Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot and `artifacts` for custom server logic or a UI outside this catalog.
+Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot.
 
 > **Capability gate**: app tools are available when the server's `CAPABILITIES` includes `pages` (for example `CAPABILITIES=core,task-pool,pages`). There is no separate `apps` capability. If these tools are absent from your MCP list, this is why.
 
@@ -740,3 +740,10 @@ Create this with `app-upsert`:
 ```
 
 The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the live UI, then continue with the read-patch-validate loop above.
+
+## View and screenshot a live app
+
+- An app renders at `<dashboard>/apps/<id>`. Two view modes are set by query string: `?mode=full` (full-viewport overlay with a slim header) and `?mode=chromeless` (only the rendered page, the embed surface). `app.navigate` keeps only `?mode`.
+- Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
+- Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
+- App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.

package/templates/skills/apps/content.md

@@ -1,6 +1,6 @@
 # Swarm Apps
 
-Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot and `artifacts` for custom server logic or a UI outside this catalog.
+Swarm Apps are persistent, agent-authored internal applications: a schema-backed row store, named queries, custom script/task actions, and a validated json-render interface served at `/apps/<id>`. Use an app when people need to view and change live records; use `create_page` for a static snapshot.
 
 > **Capability gate**: app tools are available when the server's `CAPABILITIES` includes `pages` (for example `CAPABILITIES=core,task-pool,pages`). There is no separate `apps` capability. If these tools are absent from your MCP list, this is why.
 
@@ -735,3 +735,10 @@ Create this with `app-upsert`:
 ```
 
 The tool returns `{ appId, url: "/apps/<id>" }`. Open that URL to verify the live UI, then continue with the read-patch-validate loop above.
+
+## View and screenshot a live app
+
+- An app renders at `<dashboard>/apps/<id>`. Two view modes are set by query string: `?mode=full` (full-viewport overlay with a slim header) and `?mode=chromeless` (only the rendered page, the embed surface). `app.navigate` keeps only `?mode`.
+- Logged-in browser: a fresh dashboard has no connection and redirects to /setup. Seed the localStorage key `agent-swarm-connections` with `{connections:[{id,name,apiUrl,apiKey}],activeId}`. Build the value from an env var and pipe it to `agent-browser eval --stdin`, so the key never reaches a command line. Reload, then pick a user in the "Who are you?" dialog.
+- Apps scroll inside an inner canvas, so a full-page screenshot captures only the viewport. Scroll the canvas or raise the viewport height. For mobile, set a 375px-wide viewport before the screenshot.
+- App definitions: `GET /api/apps` and `GET /api/apps/<id>` with the API key as Bearer.

package/templates/skills/chat-sdk/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "chat-sdk",
+  "displayName": "Chat SDK",
+  "slug": "chat-sdk",
+  "title": "Chat SDK",
+  "description": "Chat threads from Telegram, Slack (Chat SDK), Discord, and Teams. Use when a task carries a task:chat-sdk contextKey or a user asked through Telegram, Slack, Discord, or Teams. Covers what the swarm posts for you, `chat-reply`, markdown and length per platform, attachments, `chat-read-thread` limits, and channel routes with `register-chat-channel`.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": false,
+  "tags": ["chat", "telegram", "discord", "teams", "slack", "communication"]
+}

package/templates/skills/chat-sdk/content.md

@@ -0,0 +1,84 @@
+# Chat SDK
+
+The swarm receives messages from Telegram, Slack, Discord, and Microsoft Teams through the Chat SDK channel. A person mentions the bot or sends it a direct message, and the swarm creates a task for it. This skill tells you how to work on such a task.
+
+## How you know you are on a chat task
+
+- The task has `source: "chat"`, or it is a lead follow-up of one.
+- The task `contextKey` starts with `task:chat-sdk:`. The full form is `task:chat-sdk:<adapter>:<encoded thread id>`, for example `task:chat-sdk:telegram:555001`.
+- The task text holds the user's message. Later replies in the same thread arrive as follow-up tasks with the same `contextKey`, or as steering messages on your running task.
+- The user has four slash commands that never reach you as a task: `/help`, `/status`, `/cancel` and `/reset`. `/cancel` ends the thread's active tasks, yours included, with status `cancelled`. After `/reset` the next task has no parent task and no earlier thread context, so treat it as a new conversation.
+
+Use `get-task-details` to read the `contextKey` when you are not sure.
+
+## Reply with `chat-reply`
+
+`chat-reply { text }` posts to the thread your current task came from. It finds the thread from your task, so you do not pass ids.
+
+- Use it to ask the user a question you cannot answer yourself. Ask once, with all your questions together.
+- Use it for one short progress note when work takes more than a few minutes, such as "Started. This takes about 10 minutes."
+- Do not use it for receipts ("Got it", "On it"), and do not send many progress notes.
+- It works only on a task with a `task:chat-sdk:` contextKey. A session bound to a non-chat task does not see `chat-reply` at all, because the tool is left out of its tool list.
+
+## The final summary is posted automatically
+
+When your task ends, the swarm posts the task output to the thread:
+
+- Completed: your `store-progress` output.
+- Failed: a "Task failed." line, then the failure reason.
+- Cancelled: a "Task cancelled." line, then the reason when there is one.
+
+Do not post your final answer with `chat-reply` as well. The user would get it twice. Put the answer in the `store-progress` output and stop.
+
+The post is durable. If the platform is down, the swarm retries with backoff for up to 24 hours.
+
+## Markdown per platform
+
+Write plain, short markdown: bold, italic, inline code, code blocks, bullet lists, and links. Avoid tables, nested lists, and HTML.
+
+| Platform | What renders | Limit per message |
+|---|---|---|
+| Telegram | Bold, italic, code, code blocks, links, lists. No tables. | 4096 characters |
+| Discord | Bold, italic, code, code blocks, lists, headings, links. No tables. | 2000 characters |
+| Slack | Converted to Slack mrkdwn: bold, italic, code, lists, links. Tables do not render well. | 4000 characters |
+| Teams | Basic markdown: bold, italic, code, lists, links. | 20000 characters |
+
+The swarm splits longer text into several messages at line breaks. Long answers are hard to read in chat, so keep the answer short and put long material in an artifact or page, then post the link.
+
+## Attachments arrive as task attachments
+
+Files and images the user sends in the thread are stored as attachments of the task. The task text names them. Download them with the `download-task-attachment` skill. You cannot send files back to the thread in this version. Share a link instead.
+
+## `chat-read-thread` limits per platform
+
+`chat-read-thread { threadId, limit? }` returns the most recent messages of a thread, oldest first. The thread id is the adapter name plus the URI-decoded remainder of the contextKey. Telegram ids have no escaping, so `telegram:555001` stays as it is. Slack, Discord, and Teams ids contain `%3A` in the contextKey, so do not build the id by hand. `chat-reply` resolves the thread itself. For `chat-read-thread`, use the thread id returned by `chat-reply`, `chat-post`, or `chat-open-dm`. You can read the thread of your current task. Any other thread needs lead privileges.
+
+- Telegram has no history API. The SDK keeps the Telegram thread history it saw in the swarm database, capped at 100 messages and 7 days.
+- Teams needs the `Chat.Read.*` Graph permission on the bot. Without it, the call fails.
+- Slack and Discord return the platform history.
+
+The task text already holds the earlier swarm messages of the thread, so read the thread only when you need more.
+
+## Other tools
+
+- `chat-post { adapter, threadId | channelId, text }` posts outside your task's thread. Lead only. Use it only when the task asks you to message another thread or channel.
+- `chat-open-dm { adapter, userId }` returns the direct-message thread id for a user. Lead only. Then post to it with `chat-post`.
+
+## Leads: `register-chat-channel`
+
+By default every message addressed to the swarm goes to the lead. A lead can route one channel to a fixed agent or workflow:
+
+```
+register-chat-channel { adapter: "telegram", channelId: "telegram:-100123", agentId: "<agent id>" }
+register-chat-channel { adapter: "slack", channelId: "slack:C123", workflowId: "<workflow id>" }
+unregister-chat-channel { adapter: "telegram", channelId: "telegram:-100123" }
+```
+
+Give exactly one of `agentId` or `workflowId`. A `swarm#<agentId>` token in a message still wins over the route. A workflow mapping fires only for a bot mention or a DM; a plain reply in the subscribed thread does not start another run. Only the lead can call these tools.
+
+## Etiquette
+
+- Keep messages short. Chat is read on phones.
+- Never post secrets, tokens, internal URLs with credentials, or private data from other users. The swarm scrubs known secrets, but do not depend on it.
+- When you ask a question in a group, start with the user's name so they see it.
+- One question message is better than several.

package/templates/skills/composio-gmail/content.md

@@ -62,6 +62,13 @@ agent-swarm x composio POST /tools/execute/GMAIL_SEND_EMAIL \
 - `recipient_email` is the primary; add more via `extra_recipients` / `cc` / `bcc`.
 - **Sending is a write action** — only do it when the task explicitly asks.
 
+## Sender (From) and footer
+
+- A draft defaults to the connected account's primary address. Before you create drafts, list the account's verified send-as aliases and set From to the alias the requester prefers (requester profile or brief). Take the footer and signature domain from the same source.
+- Never set From to an alias that is not verified. Gmail rewrites it to the primary address.
+- After you create the drafts, check From as well as To and Subject on each one.
+- To fix existing drafts, update each draft in place with the alias. Draft ids stay the same, so there is no need to delete and recreate.
+
 ## Reply in a thread
 
 ```bash

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

@@ -67,7 +67,7 @@ agent-swarm x composio POST /tools/execute/GOOGLEDOCS_CREATE_DOCUMENT_MARKDOWN \
 2. Write the converted content to your own agent-fs namespace with a short
    provenance header naming the source document and import method.
 3. Resolve the destination org and drive from the environment or
-   `agent-fs stat <path> --json`; the `artifacts` skill documents the canonical
+   `agent-fs stat <path> --json`; the `agent-fs` skill documents the canonical
    storage and share-link workflow. Never copy org or drive IDs from an example.
 4. Read the stored file back and assert several markers: the title, a middle
    phrase, and the final sentence. A successful byte-count response alone does

package/templates/skills/email-domain-health/config.json

@@ -0,0 +1,14 @@
+{
+  "kind": "skill",
+  "name": "email-domain-health",
+  "displayName": "Email Domain Health",
+  "slug": "email-domain-health",
+  "title": "Email Domain Health",
+  "description": "Build a scheduled email domain health monitor: ask the user for domains, providers, test inbox, schedule and alert rules, then build a checks script (SPF, DKIM, DMARC, MX, provider records, blocklists with positive controls), a daily test send with score capture, bounce rate, run history in a Swarm App, and alerts only on a new red or a score drop. Orchestrates the swarm-scripts, apps, scheduling and composio-gmail skills.",
+  "version": "1.0.0",
+  "category": "skills",
+  "placeholders": [],
+  "runAllSeedersCandidate": true,
+  "systemDefault": true,
+  "tags": ["email", "deliverability", "dns", "monitoring", "apps"]
+}