@desplega.ai/agent-swarm 1.166.0 → 1.168.0

package/src/tests/send-task-self-send.test.ts

@@ -0,0 +1,107 @@
+// send-task refuses an agent session that targets itself, but a script runs as its owner (a
+// scheduled script as the schedule's creator), so a Lead-owned script must be able to file
+// work for the Lead. Script calls reach the tool through /api/mcp-bridge as `script-sdk`.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlinkSync } from "node:fs";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
+import { handleMcpBridge } from "../http/mcp-bridge";
+import { getPathSegments } from "../http/utils";
+import { sendTaskHandler } from "../tools/send-task";
+import { ownerCtx } from "../tools/task-tool-ctx";
+import { getRequestInfo } from "../tools/utils";
+
+const TEST_DB_PATH = "./test-send-task-self-send.sqlite";
+
+let server: Server;
+let baseUrl: string;
+let leadId = "";
+
+const selfSendArgs = (agentId: string) => ({
+  task: "x mention to triage",
+  agentId,
+  routingReason: "skill" as const,
+  routingNote: "Lead triages mentions itself",
+  offerMode: false,
+  allowDuplicate: true,
+});
+
+async function tasksFor(agentId: string): Promise<number> {
+  return (await getDbClient().get<{ c: number }>(
+    "SELECT COUNT(*) AS c FROM agent_tasks WHERE agentId = ?",
+    [agentId],
+  ))!.c;
+}
+
+beforeAll(async () => {
+  initDb(TEST_DB_PATH);
+  leadId = (
+    await createAgent({ name: "self-send-lead", isLead: true, status: "idle", maxTasks: 5 })
+  ).id;
+  server = createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const ok = await handleMcpBridge(
+      req,
+      res,
+      getPathSegments(req.url || ""),
+      undefined,
+      myAgentId,
+    );
+    if (!ok) {
+      res.writeHead(404);
+      res.end("Not Found");
+    }
+  });
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const addr = server.address();
+  if (!addr || typeof addr === "string") throw new Error("no port");
+  baseUrl = `http://127.0.0.1:${addr.port}`;
+});
+
+afterAll(() => {
+  server.close();
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      unlinkSync(TEST_DB_PATH + suffix);
+    } catch {
+      // ignore
+    }
+  }
+});
+
+describe("send-task self-send guard", () => {
+  test("a script sending a task to its own agent succeeds", async () => {
+    const before = await tasksFor(leadId);
+    const res = await fetch(`${baseUrl}/api/mcp-bridge`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "x-agent-id": leadId },
+      body: JSON.stringify({ tool: "send-task", args: selfSendArgs(leadId) }),
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { success?: boolean; message?: string };
+    expect(body.message).not.toContain("Cannot send a task to yourself");
+    expect(body.success).toBe(true);
+    expect(await tasksFor(leadId)).toBe(before + 1);
+  });
+
+  test("an agent session sending a task to itself is still refused", async () => {
+    const before = await tasksFor(leadId);
+    // An MCP session's meta carries no origin mark, so getRequestInfo reports `mcp`.
+    const info = getRequestInfo({
+      sessionId: "session-1",
+      requestInfo: { headers: { "x-agent-id": leadId } },
+    } as unknown as Parameters<typeof getRequestInfo>[0]);
+    expect(info.callOrigin).toBe("mcp");
+    const result = await sendTaskHandler(ownerCtx(info), selfSendArgs(leadId));
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain("Cannot send a task to yourself");
+    expect(await tasksFor(leadId)).toBe(before);
+  });
+});

package/src/tests/telemetry-trigger.test.ts

@@ -127,7 +127,18 @@ describe("trigger_surface on task telemetry", () => {
   // so each one is run for real and judged on the row it persists and the
   // task.created event it emits.
   const heartbeatCreators: Array<{ taskType: string; create: () => Promise<void> }> = [
-    { taskType: "boot-triage", create: createBootTriageTask },
+    {
+      taskType: "boot-triage",
+      create: async () => {
+        // A clean boot creates no task; force one to judge its source.
+        process.env.HEARTBEAT_BOOT_TRIAGE_ALWAYS = "true";
+        try {
+          await createBootTriageTask();
+        } finally {
+          delete process.env.HEARTBEAT_BOOT_TRIAGE_ALWAYS;
+        }
+      },
+    },
     {
       taskType: "heartbeat-checklist",
       create: async () => {

package/src/tests/workflow-llm.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_MODEL } from "../utils/internal-ai/models";
+import { OPENROUTER_APP_ATTRIBUTION_HEADERS } from "../utils/openrouter-base-url";
 import { resolveWorkflowLlmConfig } from "../workflows/executors/workflow-llm";
 
 describe("resolveWorkflowLlmConfig", () => {
@@ -12,10 +13,22 @@ describe("resolveWorkflowLlmConfig", () => {
     expect(config).toEqual({
       apiKey: "sk-or-test",
       baseURL: "https://gateway.example.test/v1",
+      headers: {},
       model: "deepseek/deepseek-v4.1-flash",
     });
   });
 
+  test("attributes direct openrouter.ai calls unless OPENROUTER_APP_ATTRIBUTION is off", async () => {
+    const direct = await resolveWorkflowLlmConfig(undefined, { OPENROUTER_API_KEY: "sk-or-test" });
+    expect(direct.headers).toEqual(OPENROUTER_APP_ATTRIBUTION_HEADERS);
+
+    const optedOut = await resolveWorkflowLlmConfig(undefined, {
+      OPENROUTER_API_KEY: "sk-or-test",
+      OPENROUTER_APP_ATTRIBUTION: "false",
+    });
+    expect(optedOut.headers).toEqual({});
+  });
+
   test("routes OpenAI credentials to the SDK default endpoint", async () => {
     const config = await resolveWorkflowLlmConfig(undefined, {
       OPENAI_API_KEY: "example-sk-openai-test",
@@ -24,6 +37,7 @@ describe("resolveWorkflowLlmConfig", () => {
     expect(config).toEqual({
       apiKey: "example-sk-openai-test",
       baseURL: undefined,
+      headers: {},
       model: "gpt-6-luna",
     });
   });

package/src/tests/workflow-system-one-decision-providers.test.ts

@@ -734,4 +734,37 @@ describe("system-one-decision SystemOne wire is unchanged", () => {
       expect(calls[0]?.raw).toBe(expected);
     }
   });
+
+  test("only the openrouter.ai provider carries OpenRouter app attribution", async () => {
+    const referer = async (provider: string, env: Record<string, string>) => {
+      const { executor, calls } = makeExecutor(
+        [
+          jsonResponse({
+            model: "jev",
+            answers: systemOneAnswers,
+            usage: { input_tokens: 1, output_tokens: 0 },
+          }),
+        ],
+        {
+          getApiKey: async () => OPENAI_KEY,
+          getServerUrl: async () => "https://laya.example.test",
+          env: { OPENROUTER_API_KEY: OPENAI_KEY, ...env },
+        },
+      );
+      await run(executor, { ...config({ model: "jev-1.13.0" }), provider });
+      const headers = new Headers(calls[0]?.init.headers);
+      return [headers.get("http-referer"), headers.get("x-openrouter-categories")];
+    };
+    expect(await referer("openrouter", {})).toEqual([
+      "https://agent-swarm.dev",
+      "personal-agent,cloud-agent",
+    ]);
+    expect(await referer("openrouter", { OPENROUTER_APP_ATTRIBUTION: "false" })).toEqual([
+      null,
+      null,
+    ]);
+    for (const provider of ["typesafe", "laya"]) {
+      expect(await referer(provider, {})).toEqual([null, null]);
+    }
+  });
 });

package/src/tools/request-human-input.ts

@@ -12,7 +12,10 @@ const QuestionSchema = z.object({
     .describe("Question type"),
   label: z.string().describe("The question text displayed to the user"),
   required: z.boolean().optional().describe("Whether this question is required (default: true)"),
-  description: z.string().optional().describe("Optional help text"),
+  description: z
+    .string()
+    .optional()
+    .describe("Optional help text, rendered as markdown (code fences, images)"),
   placeholder: z.string().optional().describe("Placeholder text (for text type)"),
   multiline: z.boolean().optional().describe("Use textarea instead of input (for text type)"),
   options: z
@@ -39,7 +42,9 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
       description:
         "Create an approval request and return at once with the request id and URL. The answer arrives later as a hitl-follow-up task. " +
         "Supports multiple question types: approval (yes/no), text, single-select, " +
-        "multi-select, and boolean. Returns the request ID and URL for the human to respond.",
+        "multi-select, and boolean. Returns the request ID and URL for the human to respond. " +
+        "The dashboard renders each label and description as markdown: put long content in description, fence code with a language, and put an image URL alone on its own line to show it. " +
+        "No Slack message is sent; share the URL yourself.",
       inputSchema: z.object({
         title: z.string().min(1).describe("Title of the approval request"),
         questions: z.array(QuestionSchema).min(1).describe("Questions to ask the human"),

package/src/tools/script-connections/tool.ts

@@ -4,6 +4,7 @@ import { getAgentById } from "@/be/db";
 import {
   ConnectionAuthInputSchema,
   connectionAuthInputFromFlat,
+  deleteScriptConnection,
   getScriptConnectionById,
   listScriptConnections,
   refreshScriptConnection,
@@ -16,13 +17,23 @@ import { resolveScopedResourceId, scopedResourceScopeIdSchema } from "@/utils/sc
 
 const scriptConnectionsInputSchema = z.object({
   action: z
-    .enum(["list", "upsert-openapi", "upsert-mcp", "upsert-graphql", "refresh", "disable"])
-    .describe("List, create/update, refresh, or disable a script connection."),
+    .enum([
+      "list",
+      "upsert-openapi",
+      "upsert-mcp",
+      "upsert-graphql",
+      "refresh",
+      "disable",
+      "delete",
+    ])
+    .describe(
+      "List, create/update, refresh, disable, or delete a script connection. delete is permanent: it removes the connection, its managed credential binding, and any inline secret it owns.",
+    ),
   id: z
     .string()
     .uuid()
     .optional()
-    .describe("Existing connection ID for update, refresh, or disable."),
+    .describe("Existing connection ID for update, refresh, disable, or delete."),
   slug: z
     .string()
     .min(1)
@@ -193,6 +204,27 @@ export const registerScriptConnectionsTool = (server: McpServer) => {
         });
       }
 
+      if (args.action === "delete") {
+        if (!args.id) {
+          return toolErr("id is required for delete.", {
+            data: {
+              yourAgentId: requestInfo.agentId,
+              connections: listScriptConnections({ includeDisabled: true, allScopes: true }),
+            },
+          });
+        }
+        const deleted = await deleteScriptConnection(args.id);
+        const connections = listScriptConnections({ includeDisabled: true, allScopes: true });
+        if (!deleted) {
+          return toolErr(`Script connection ${args.id} not found.`, {
+            data: { yourAgentId: requestInfo.agentId, connections },
+          });
+        }
+        return toolOk(`Script connection ${deleted.slug} deleted.`, {
+          data: { yourAgentId: requestInfo.agentId, connections },
+        });
+      }
+
       if (args.action === "refresh") {
         if (!args.id) {
           return toolErr("id is required for refresh.", {

package/src/tools/send-task.ts

@@ -355,7 +355,15 @@ export async function sendTaskHandler(
     });
   }
 
-  if (ctx.kind === "owner" && requestedAgentId === ctx.agentId) {
+  // The guard stops an agent session from handing work back to itself. A script runs as its
+  // owner (a scheduled script as the schedule's creator), so a Lead-owned poller that files
+  // work for the Lead is legitimate. The bridge marks script calls `script-sdk`; a caller that
+  // spoofs it can only send itself a task, which grants nothing it could not already do.
+  if (
+    ctx.kind === "owner" &&
+    requestedAgentId === ctx.agentId &&
+    ctx.requestInfo?.callOrigin !== "script-sdk"
+  ) {
     return toolErr("Cannot send a task to yourself, are you drunk?", {
       data: { yourAgentId: ctx.agentId },
     });

package/src/utils/enabled-tools.ts

@@ -0,0 +1,27 @@
+/**
+ * Parse the `SWARM_ENABLED_TOOLS` MCP tool allowlist.
+ *
+ * Accepts a comma-separated list (`get-tasks, store-progress`) or a JSON array
+ * of strings. Returns `undefined` when the value is unset, blank, or holds no
+ * entries, so callers keep the capability-driven surface. Throws on a JSON
+ * array that does not parse to strings.
+ */
+export function parseEnabledTools(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  let entries: string[];
+  if (trimmed.startsWith("[")) {
+    const parsed: unknown = JSON.parse(trimmed);
+    if (!Array.isArray(parsed) || !parsed.every((entry) => typeof entry === "string")) {
+      throw new Error("Expected a JSON array of tool names");
+    }
+    entries = parsed;
+  } else {
+    entries = trimmed.split(",");
+  }
+
+  const tools = [...new Set(entries.map((entry) => entry.trim()).filter(Boolean))];
+  return tools.length > 0 ? tools : undefined;
+}

package/src/utils/internal-ai/complete-structured.ts

@@ -20,7 +20,11 @@ import { complete } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModel as getModel } from "@earendil-works/pi-ai/providers/all";
 import type { TSchema } from "typebox";
 import { z } from "zod";
-import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../openrouter-base-url.js";
+import {
+  DEFAULT_OPENROUTER_BASE_URL,
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../openrouter-base-url.js";
 import { scrubSecrets } from "../secret-scrubber.js";
 import { type ResolvedCredential, resolveCredential } from "./credentials.js";
 import { parseModelStr } from "./models.js";
@@ -319,10 +323,14 @@ export async function completeStructuredWithModel<TZod extends z.ZodTypeAny>(
   // through a gateway (pi-ai's stream path uses `model.baseUrl` verbatim).
   // Resolved from the caller's session env when provided — swarm_config
   // overlays don't reach `process.env`.
-  const openRouterBaseUrl = getOpenRouterBaseUrl((opts.env ?? process.env) as NodeJS.ProcessEnv);
+  const env = opts.env ?? process.env;
+  const openRouterBaseUrl = getOpenRouterBaseUrl(env as NodeJS.ProcessEnv);
   if (provider === "openrouter" && openRouterBaseUrl !== DEFAULT_OPENROUTER_BASE_URL) {
     model = { ...model, baseUrl: openRouterBaseUrl };
   }
+  // pi-ai merges `options.headers` over the provider defaults.
+  const headers =
+    provider === "openrouter" ? getOpenRouterAttributionHeaders(model.baseUrl, env) : {};
 
   const completeFn = opts._complete ?? complete;
   const toolChoice =
@@ -348,7 +356,7 @@ export async function completeStructuredWithModel<TZod extends z.ZodTypeAny>(
         },
         // pi-ai's ProviderStreamOptions type only allows known providers;
         // we pass the validated apiKey through verbatim.
-        { apiKey: cred.apiKey, signal: opts.signal, toolChoice } as Parameters<
+        { apiKey: cred.apiKey, signal: opts.signal, toolChoice, headers } as Parameters<
           typeof completeFn
         >[2],
       );

package/src/utils/openrouter-base-url.ts

@@ -26,3 +26,26 @@ export function getOpenRouterBaseUrl(env: NodeJS.ProcessEnv = process.env): stri
   }
   return DEFAULT_OPENROUTER_BASE_URL;
 }
+
+export const OPENROUTER_APP_ATTRIBUTION_HEADERS = {
+  "HTTP-Referer": "https://agent-swarm.dev",
+  "X-OpenRouter-Title": "Agent Swarm",
+  "X-OpenRouter-Categories": "personal-agent,cloud-agent",
+} as const;
+
+/** Attribute direct OpenRouter requests unless the task opts out. */
+export function getOpenRouterAttributionHeaders(
+  url: string,
+  env: Record<string, string | undefined> = process.env,
+): Record<string, string> {
+  const enabled = env.OPENROUTER_APP_ATTRIBUTION?.toLowerCase();
+  if (enabled === "false" || enabled === "0") return {};
+  try {
+    const host = new URL(url).hostname;
+    return host === "openrouter.ai" || host.endsWith(".openrouter.ai")
+      ? { ...OPENROUTER_APP_ATTRIBUTION_HEADERS }
+      : {};
+  } catch {
+    return {};
+  }
+}

package/src/workflows/executors/raw-llm.ts

@@ -32,6 +32,7 @@ export async function executeRawLlm(
     const provider = createOpenAI({
       baseURL: llmConfig.baseURL,
       apiKey: llmConfig.apiKey,
+      headers: llmConfig.headers,
     });
     const model = provider(llmConfig.model);
 

package/src/workflows/executors/system-one-decision.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
+import { getOpenRouterAttributionHeaders } from "../../utils/openrouter-base-url";
 import { scrubSecrets } from "../../utils/secret-scrubber";
 import {
   type ApprovalOutcome,
@@ -1170,6 +1171,7 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
       res = await doFetch(endpoint, {
         method: "POST",
         headers: {
+          ...getOpenRouterAttributionHeaders(endpoint, this.providerContext().env),
           "content-type": "application/json",
           accept: "application/json",
           authorization: `Bearer ${apiKey}`,

package/src/workflows/executors/validate.ts

@@ -119,6 +119,7 @@ export class ValidateExecutor extends BaseExecutor<
       const provider = createOpenAI({
         baseURL: llmConfig.baseURL,
         apiKey: llmConfig.apiKey,
+        headers: llmConfig.headers,
       });
 
       const { object } = await generateObject({

package/src/workflows/executors/workflow-llm.ts

@@ -1,9 +1,14 @@
 import { DEFAULT_MODEL, resolveCredential } from "../../utils/internal-ai/credentials";
-import { getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
+import {
+  getOpenRouterAttributionHeaders,
+  getOpenRouterBaseUrl,
+} from "../../utils/openrouter-base-url";
 
 export interface WorkflowLlmConfig {
   apiKey: string;
   baseURL?: string;
+  /** OpenRouter app attribution; empty for OpenAI and for gateway base URLs. */
+  headers: Record<string, string>;
   model: string;
 }
 
@@ -39,9 +44,11 @@ export async function resolveWorkflowLlmConfig(
   // Workflow defaults are provider-owned; MEMORY_RATER_MODEL only configures memory work.
   const model = requestedModel ?? DEFAULT_MODEL[credential.kind];
 
+  const baseURL = credential.kind === "openrouter" ? getOpenRouterBaseUrl(env) : undefined;
   return {
     apiKey: credential.apiKey,
-    baseURL: credential.kind === "openrouter" ? getOpenRouterBaseUrl(env) : undefined,
+    baseURL,
+    headers: baseURL ? getOpenRouterAttributionHeaders(baseURL, env) : {},
     model: model.startsWith(providerPrefix) ? model.slice(providerPrefix.length) : model,
   };
 }

package/templates/extensions/README.md

@@ -13,6 +13,7 @@ Each folder holds exactly one `manifest.yaml`, `manifest.yml`, or `manifest.json
 | `require-ticket-ref` | `pre.task.create` | Blocks REST, MCP, and Slack tasks that do not name a ticket |
 | `notify-on-complete` | `post.task.completed`, `post.task.failed` | Posts a summary to a Slack channel |
 | `deploy-awareness` | `pre.task.create` | Appends a one-line note to new tasks while a Dokploy deploy is in progress |
+| `slack-reply-gate` | `pre.task.create` | Asks Jev (TypeSafe or OpenRouter) whether Lead should answer a Slack thread follow-up; in `enforce` drops the wake-up and marks the message :mute: |
 | `require-verification-note` | `pre.tool.call` | Refuses completion without a `Verified:` line in the output |
 | `task-digest` | `post.task.completed`, `post.task.failed` | Ships the `task-digest-collect` script, the `task-digest-daily` schedule (09:00 UTC), the `task-digest-report` workflow, and the `task-digest-guide` skill |
 

package/templates/extensions/slack-reply-gate/README.md

@@ -0,0 +1,98 @@
+# slack-reply-gate
+
+Lead is woken by every human message in a Slack thread the swarm takes part in, including "lol", an emoji, or two people chatting with each other. This extension asks Jev, [TypeSafe](https://typesafe.ai)'s decision model, whether Lead should answer a new thread message, and drops the wake-up when it should not.
+
+Install config:
+
+```json
+{ "mode": "shadow" }
+```
+
+Start in `shadow`, read the decisions in KV for a few days, then switch to `enforce`.
+
+## Modes
+
+| `mode` | Effect |
+|---|---|
+| `off` | Never evaluates. |
+| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |
+| `enforce` | Asks Jev, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |
+
+## What it gates
+
+Hook: `pre.task.create`, for tasks with origin `slack` whose description carries the thread buffer's header `[Thread follow-up — N message(s) buffered]`. Those are the non-mention thread replies that `src/slack/thread-buffer.ts` batches into a Lead task. A direct @mention of the bot creates a task without that header and is never gated.
+
+The header counts only at the start of the description or right after the closing `</thread_context>`. Thread context quotes old messages verbatim, and an older Lead reply can quote the header itself, so a header inside the context is ignored. Only the text after the real header is treated as new.
+
+## Decision
+
+1. A follow-up with downloaded files (status `draft`) passes without a Jev call.
+2. **@mention pass-through.** A new message that @mentions Lead passes without a Jev call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.
+3. Otherwise one Jev call (one `choice` question, see [Jev transport](#jev-transport)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.
+4. The answer is no only when the top label is `reaction_only`, `banter_between_others`, or `not_addressed_to_lead`, and the summed probability of those three labels is at least `minConfidence`. A split between two skip labels is still a skip. An unsure verdict replies.
+
+Several buffered messages are judged together. One mention in any of them passes the batch.
+
+## Jev transport
+
+Jev is reachable two ways. Both take the same request and return the same answer, so the decision is identical whichever one runs.
+
+| `provider` | Endpoint | Key | Model |
+|---|---|---|---|
+| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |
+| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |
+| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |
+
+Under `auto`, `TYPESAFE_API_KEY` wins when both keys are set. With neither key, every message fails open and the KV row names both secrets. Each decision row records the `provider` that answered.
+
+## Fail open
+
+Every error lets the task through: a missing key, a TypeSafe HTTP error, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.
+
+## :mute: on drop (enforce)
+
+No swarm tool or extension `ctx` method adds a Slack reaction, so the hook calls the Slack Web API with the bot token. It needs the `reactions:write` scope, which the Slack app already uses for its acceptance reactions.
+
+1. `reactions.remove` for each acceptance reaction the engine may have put on the triggering message: `eyes`, `heavy_plus_sign`, `zap`, `speech_balloon`, or their `SLACK_REACTION_ACCEPTED`, `SLACK_REACTION_BUFFERED`, `SLACK_REACTION_NOW`, and `SLACK_REACTION_STEERED` overrides. Slack only removes the bot's own reaction, so a human's :eyes: stays.
+2. `reactions.add` with `muteReaction` (default `mute`). `already_reacted` counts as success. Skipped when `muteReaction` is `""`.
+
+The block returns first and the Slack calls run after it. A slow or failing Slack call never delays the drop or turns it back into a task. Set `muteReaction` to `""` for a true no-op: step 1 still clears the bot's acceptance reaction(s), and nothing is added.
+
+## Config
+
+| Key | Default | Notes |
+|---|---|---|
+| `mode` | `shadow` | `off`, `shadow`, or `enforce` |
+| `timeoutMs` | `3000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
+| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |
+| `model` | `jev-latest` | Jev model on TypeSafe |
+| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |
+| `minConfidence` | `0.55` | Minimum summed skip probability to skip |
+| `contextMessages` | `6` | Thread messages sent to Jev, 0 to 20 |
+| `leadAliases` | `["lead"]` | A literal `@alias` in a new message counts as a mention |
+| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for Jev |
+| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |
+| `muteReaction` | `mute` | Reaction for a dropped message; `""` only removes the acceptance reaction(s) |
+| `slackTimeoutMs` | `5000` | Timeout per Slack call |
+
+## Required secrets
+
+All are read from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.
+
+- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every message fails open.
+- `SLACK_BOT_TOKEN`: the Slack app's bot token. A swarm with Slack connected already has it. Without it, `enforce` still drops the message but cannot touch its reactions, and logs a `mute-error`.
+
+No key is written to config, KV, logs, or a description.
+
+## KV namespace `ext:slack-reply-gate`
+
+- `d:<epochMs>:<channel>_<threadTs>`: one row per decision, with `action` (`pass`, `shadow-skip`, `skipped`, `fail-open`), `provider`, `reason`, `confidence`, `skipP`, `latencyMs`, `sender`, and a 300-character `preview`.
+- `m:<epochMs>:<channel>_<threadTs>`: one row per mute attempt, with `action` (`muted`, `unreacted` when `muteReaction` is `""`, `mute-error`), `removed`, `added`, and `errors`.
+- `last`: the latest decision. Mute rows never overwrite it.
+- Counters: `total`, `mention`, `files`, `reply`, `shadow-skip`, `skipped`, `error`, `muted`, `unreacted`, `mute-error`, and `reason:<label>`.
+
+## Known limits
+
+- When Lead already has an active task in the thread, the buffer steers that task instead of creating one, so `pre.task.create` does not fire and the gate does not run.
+- A blocked flush makes the thread buffer log a `TaskCreationBlockedError`. Nothing is lost: the next follow-up's `<thread_context>` carries the earlier messages.
+- A flush of several messages mutes only the triggering (last) message. The others keep their acceptance reaction.