@desplega.ai/agent-swarm 1.167.0 → 1.168.0

package/src/tests/schedule-target-type.test.ts

@@ -33,6 +33,7 @@ import {
   preflightAutomation,
   renderAutomationTokens,
 } from "../be/automation-preflight";
+import * as dbModule from "../be/db";
 import {
   closeDb,
   createAgent,
@@ -58,6 +59,7 @@ import {
   startScheduler,
   stopScheduler,
 } from "../scheduler/scheduler";
+import * as scriptLoader from "../scripts-runtime/loader";
 import type { Workflow, WorkflowDefinition } from "../types";
 import { InProcessEventBus } from "../workflows/event-bus";
 import { BaseExecutor, type ExecutorResult } from "../workflows/executors/base";
@@ -148,6 +150,38 @@ async function saveGlobalScript(name: string, source: string) {
   });
 }
 
+type ScheduleScriptRunRow = {
+  agentId: string;
+  scriptName: string;
+  source: string;
+  kind: string;
+  status: string;
+  output: string | null;
+  error: string | null;
+  finishedAt: string | null;
+};
+
+async function scriptRunsFor(scriptName: string): Promise<ScheduleScriptRunRow[]> {
+  return getDbClient().query<ScheduleScriptRunRow>(
+    "SELECT agentId, scriptName, source, kind, status, output, error, finishedAt FROM script_runs WHERE scriptName = ?",
+    [scriptName],
+  );
+}
+
+type RunScriptOutput = Awaited<ReturnType<typeof scriptLoader.runScript>>;
+
+function fakeRunOutput(overrides: Partial<RunScriptOutput>): RunScriptOutput {
+  return {
+    result: undefined,
+    stdout: "",
+    stderr: "",
+    exitCode: 0,
+    durationMs: 1,
+    truncated: { stdout: false, stderr: false },
+    ...overrides,
+  } as RunScriptOutput;
+}
+
 beforeAll(async () => {
   savedEnv = { ...process.env };
   await removeDbFiles();
@@ -718,6 +752,11 @@ describe("dispatchScheduleTarget — script target", () => {
     const result = await dispatchScheduleTarget(schedule);
     expect(result.triggeredWorkflows).toBe(false);
     expect(result.task).toBeUndefined();
+
+    const runs = await scriptRunsFor("schedule-target-type-echo");
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.status).toBe("completed");
+    expect(JSON.parse(runs[0]?.output ?? "null")).toEqual({ received: { hello: "world" } });
   }, 15_000);
 
   skip("scheduled script runs receive ctx.api and ctx.mcp connections", async () => {
@@ -794,9 +833,106 @@ describe("dispatchScheduleTarget — script target", () => {
     });
 
     await expect(dispatchScheduleTarget(schedule)).rejects.toThrow();
+
+    const runs = await scriptRunsFor("schedule-target-type-throws");
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.status).toBe("failed");
+    expect(runs[0]?.error).toContain("boom");
   }, 15_000);
 });
 
+describe("dispatchScheduleTarget — script target records a script_runs row", () => {
+  async function scheduleFor(scriptName: string) {
+    await saveGlobalScript(scriptName, `export default async () => ({ ok: true });`);
+    return createScheduledTask({
+      name: `record-${scriptName}`,
+      intervalMs: 60_000,
+      targetType: "script",
+      scriptName,
+      createdByAgentId: agentId,
+    });
+  }
+
+  test("a completed scheduled run writes a completed inline row that points at the script version", async () => {
+    const scriptName = `record-ok-${crypto.randomUUID()}`;
+    const schedule = await scheduleFor(scriptName);
+    const run = spyOn(scriptLoader, "runScript").mockResolvedValue(
+      fakeRunOutput({ result: { polled: 3 } }),
+    );
+    try {
+      await dispatchScheduleTarget(schedule);
+    } finally {
+      run.mockRestore();
+    }
+
+    const runs = await scriptRunsFor(scriptName);
+    expect(runs).toHaveLength(1);
+    const row = runs[0];
+    expect(row?.kind).toBe("inline");
+    expect(row?.status).toBe("completed");
+    expect(row?.agentId).toBe(agentId);
+    expect(row?.finishedAt).toBeTruthy();
+    expect(row?.error).toBeNull();
+    expect(JSON.parse(row?.output ?? "null")).toEqual({ polled: 3 });
+    expect(row?.source).toContain(`'${scriptName}' v1`);
+    expect(row?.source).toContain(`by schedule '${schedule.name}'`);
+    expect(row?.source).not.toContain("export default");
+  });
+
+  test("a failed scheduled run writes a failed row and still throws", async () => {
+    const scriptName = `record-fail-${crypto.randomUUID()}`;
+    const schedule = await scheduleFor(scriptName);
+    const run = spyOn(scriptLoader, "runScript").mockResolvedValue(
+      fakeRunOutput({ exitCode: 1, stderr: "upstream 503" }),
+    );
+    try {
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow("upstream 503");
+    } finally {
+      run.mockRestore();
+    }
+
+    const runs = await scriptRunsFor(scriptName);
+    expect(runs).toHaveLength(1);
+    expect(runs[0]?.status).toBe("failed");
+    expect(runs[0]?.error).toBe("upstream 503");
+  });
+
+  test("a runtime that throws before returning writes a failed row and rethrows", async () => {
+    const scriptName = `record-throw-${crypto.randomUUID()}`;
+    const schedule = await scheduleFor(scriptName);
+    const run = spyOn(scriptLoader, "runScript").mockRejectedValue(new Error("spawn failed"));
+    try {
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow("spawn failed");
+    } finally {
+      run.mockRestore();
+    }
+
+    const runs = await scriptRunsFor(scriptName);
+    expect(runs.map((r) => [r.status, r.error])).toEqual([["failed", "spawn failed"]]);
+  });
+
+  test("a persistence error changes neither outcome", async () => {
+    const scriptName = `record-dberr-${crypto.randomUUID()}`;
+    const schedule = await scheduleFor(scriptName);
+    const record = spyOn(dbModule, "recordInlineScriptRun").mockRejectedValue(
+      new Error("database is locked"),
+    );
+    const run = spyOn(scriptLoader, "runScript")
+      .mockResolvedValueOnce(fakeRunOutput({ result: { ok: true } }))
+      .mockResolvedValueOnce(fakeRunOutput({ exitCode: 1, stderr: "real failure" }));
+    try {
+      const result = await dispatchScheduleTarget(schedule);
+      expect(result.triggeredWorkflows).toBe(false);
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow("real failure");
+      expect(record).toHaveBeenCalledTimes(2);
+    } finally {
+      run.mockRestore();
+      record.mockRestore();
+    }
+    expect(await scriptRunsFor(scriptName)).toHaveLength(0);
+  });
+});
+
 // ─── HTTP route cross-field validation ────────────────────────────────────────
 
 function makeHttpReq(

package/src/tests/script-connections-http.test.ts

@@ -254,6 +254,51 @@ describe("/api/script-connections HTTP", () => {
     expect(await res.json()).toEqual({ error: "Only the lead can manage script connections." });
   });
 
+  test("DELETE removes a connection, its managed binding, and its inline secret", async () => {
+    const created = await dispatch("/api/script-connections", {
+      method: "POST",
+      agentId: leadAgentId,
+      body: {
+        kind: "openapi",
+        slug: "deleteHttpVendor",
+        baseUrl: "https://api.vendor.test",
+        allowedHosts: ["api.vendor.test"],
+        auth: { type: "bearer", secret: "example-http-delete-tok" },
+        openapiSpecJson: inlineOpenApiSpec(),
+      },
+    });
+    expect(created.status).toBe(200);
+    const { connection } = (await created.json()) as { connection: { id: string } };
+
+    const forbidden = await dispatch(`/api/script-connections/${connection.id}`, {
+      method: "DELETE",
+      agentId: workerAgentId,
+    });
+    expect(forbidden.status).toBe(403);
+
+    const res = await dispatch(`/api/script-connections/${connection.id}`, {
+      method: "DELETE",
+      agentId: leadAgentId,
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ deleted: true, id: connection.id });
+
+    const counts = await getDbClient().get<{ conns: number; bindings: number; secrets: number }>(
+      `SELECT
+         (SELECT COUNT(*) FROM script_connections WHERE id = ?) AS conns,
+         (SELECT COUNT(*) FROM script_credential_bindings WHERE managed_by_connection_id = ?) AS bindings,
+         (SELECT COUNT(*) FROM swarm_config WHERE key = 'connection.deleteHttpVendor.secret') AS secrets`,
+      [connection.id, connection.id],
+    );
+    expect(counts).toEqual({ conns: 0, bindings: 0, secrets: 0 });
+
+    const missing = await dispatch(`/api/script-connections/${connection.id}`, {
+      method: "DELETE",
+      agentId: leadAgentId,
+    });
+    expect(missing.status).toBe(404);
+  });
+
   test("list returns connections without secrets", async () => {
     await upsertSwarmConfig({
       scope: "global",

package/src/tests/script-connections-mcp.test.ts

@@ -907,3 +907,44 @@ describe("script MCP connections", () => {
     }
   });
 });
+
+describe("script-connections MCP delete", () => {
+  test("lead deletes a connection and its inline secret; unknown id and non-lead fail", async () => {
+    const lead = await createAgent({ name: "mcp-delete-lead", isLead: true, status: "idle" });
+    const worker = await createAgent({ name: "mcp-delete-worker", isLead: false, status: "idle" });
+    const connection = await upsertScriptConnection({
+      slug: "mcpDeleteVendor",
+      kind: "graphql",
+      baseUrl: "https://api.vendor.test/graphql",
+      allowedHosts: ["api.vendor.test"],
+      auth: { type: "bearer", secret: "example-mcp-delete-tok" },
+    });
+
+    const denied = (await scriptConnectionsTool().handler(
+      { action: "delete", id: connection.id },
+      meta(worker.id),
+    )) as ToolResult;
+    expect(denied.structuredContent.success).toBe(false);
+    expect(await getScriptConnectionById(connection.id)).not.toBeNull();
+
+    const result = (await scriptConnectionsTool().handler(
+      { action: "delete", id: connection.id },
+      meta(lead.id),
+    )) as ToolResult;
+    expect(result.structuredContent.success).toBe(true);
+    expect(result.structuredContent.connections.map((c) => c.id)).not.toContain(connection.id);
+    expect(await getScriptConnectionById(connection.id)).toBeNull();
+    const secretRow = await getDbClient().get<{ key: string }>(
+      "SELECT key FROM swarm_config WHERE key = ?",
+      ["connection.mcpDeleteVendor.secret"],
+    );
+    expect(secretRow).toBeNull();
+
+    const again = (await scriptConnectionsTool().handler(
+      { action: "delete", id: connection.id },
+      meta(lead.id),
+    )) as ToolResult;
+    expect(again.structuredContent.success).toBe(false);
+    expect(again.structuredContent.message).toContain("not found");
+  });
+});

package/src/tests/script-executor-registry.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { validateConfigValue } from "../be/swarm-config-guard";
 import { NativeScriptExecutor } from "../scripts-runtime/executors/native";
 import { QuickJSScriptExecutor } from "../scripts-runtime/executors/quickjs";
 import { getScriptExecutor } from "../scripts-runtime/executors/registry";
@@ -20,3 +21,20 @@ describe("getScriptExecutor", () => {
     expect(() => getScriptExecutor("e2b")).toThrow("Available: native, quickjs");
   });
 });
+
+describe("SCRIPT_EXECUTOR configuration", () => {
+  test("every accepted value resolves to its executor", () => {
+    for (const value of ["native", "quickjs", " native ", " quickjs "]) {
+      expect(validateConfigValue("SCRIPT_EXECUTOR", value)).toBeNull();
+      expect(getScriptExecutor(value).name).toBe(value.trim());
+    }
+  });
+
+  test("rejects unsupported names, blank values and non-string values", () => {
+    for (const value of ["e2b", "Native", "QUICKJS", "", " ", null, undefined, 1, true]) {
+      expect(validateConfigValue("SCRIPT_EXECUTOR", value)).toBe(
+        "Invalid SCRIPT_EXECUTOR value (must be one of: native, quickjs)",
+      );
+    }
+  });
+});

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/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/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.