@desplega.ai/agent-swarm 1.69.1 → 1.70.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.69.1",
+    "version": "1.70.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -4855,6 +4855,64 @@
         }
       }
     },
+    "/api/mcp-oauth/{mcpServerId}/authorize-url": {
+      "get": {
+        "summary": "Build an OAuth authorize URL. Returns JSON so the browser can navigate without losing the Bearer auth header.",
+        "tags": [
+          "MCP OAuth"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "mcpServerId",
+            "in": "path"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "redirect",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "userId",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "scopes",
+            "in": "query"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "{ providerUrl: string }"
+          },
+          "400": {
+            "description": "MCP has no URL / does not require OAuth"
+          },
+          "404": {
+            "description": "MCP server not found"
+          }
+        }
+      }
+    },
     "/api/mcp-oauth/callback": {
       "get": {
         "summary": "OAuth redirect target. Exchanges code -> tokens and redirects back to dashboard.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.69.1",
+  "version": "1.70.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/commands/runner.ts

@@ -272,6 +272,7 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "update-profile": "🪪 Updating profile",
   // Slack
   "slack-post": "💬 Posting to Slack",
+  "slack-start-thread": "💬 Starting Slack thread",
   "slack-reply": "💬 Replying in Slack",
   "slack-read": "💬 Reading Slack",
   "slack-list-channels": "💬 Listing Slack channels",

package/src/hooks/hook.ts

@@ -355,8 +355,10 @@ export async function handleHook(): Promise<void> {
     }
   };
 
-  // Minimum length for SOUL.md and IDENTITY.md to prevent accidental corruption
-  const IDENTITY_FILE_MIN_LENGTH = 100;
+  // Minimum length for SOUL.md and IDENTITY.md to prevent accidental corruption.
+  // Raised from 100 to 500 after Picateclas profile corruption recurrences where
+  // a 234-char test sentinel payload was syncing into the real agent's DB row.
+  const IDENTITY_FILE_MIN_LENGTH = 500;
 
   /**
    * Sync SOUL.md and IDENTITY.md content back to the server

package/src/http/core.ts

@@ -16,7 +16,27 @@ import { startSlackApp, stopSlackApp } from "../slack";
 import type { AgentStatus } from "../types";
 import { refreshSecretScrubberCache } from "../utils/secret-scrubber";
 import { generateOpenApiSpec, SCALAR_HTML } from "./openapi";
-import { agentWithCapacity, parseQueryParams } from "./utils";
+import { routeRegistry } from "./route-def";
+import { agentWithCapacity, getPathSegments, matchRoute, parseQueryParams } from "./utils";
+
+/**
+ * Check whether a request targets a route declared (via the `route()` factory)
+ * with `auth: { apiKey: false }` — i.e. one that opts out of the API-key
+ * bearer check. Handler files must use the `route()` factory for this to take
+ * effect; unknown paths fail closed (auth required).
+ */
+function isPublicRoute(method: string | undefined, pathSegments: string[]): boolean {
+  for (const def of routeRegistry) {
+    if (def.auth?.apiKey === false) {
+      if (
+        matchRoute(method, pathSegments, def.method.toUpperCase(), def.pattern, def.exact ?? true)
+      ) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 /**
  * Load global swarm_config entries into process.env.
@@ -121,31 +141,21 @@ export async function handleCore(
     return true;
   }
 
-  // API key authentication (if API_KEY is configured)
-  // Skip auth for webhooks (they have their own signature verification)
-  const isGitHubWebhook = req.url?.startsWith("/api/github/webhook");
-  const isGitLabWebhook = req.url?.startsWith("/api/gitlab/webhook");
-  const isAgentMailWebhook = req.url?.startsWith("/api/agentmail/webhook");
-  const isTrackerAuth =
-    req.url?.startsWith("/api/trackers/linear/authorize") ||
-    req.url?.startsWith("/api/trackers/linear/callback") ||
-    req.url?.startsWith("/api/trackers/linear/webhook");
-  const isWorkflowWebhook = req.url?.startsWith("/api/webhooks/");
-  if (
-    apiKey &&
-    !isGitHubWebhook &&
-    !isGitLabWebhook &&
-    !isAgentMailWebhook &&
-    !isTrackerAuth &&
-    !isWorkflowWebhook
-  ) {
-    const authHeader = req.headers.authorization;
-    const providedKey = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
-
-    if (providedKey !== apiKey) {
-      res.writeHead(401, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "Unauthorized" }));
-      return true;
+  // API-key authentication (if API_KEY is configured). Routes that opt out via
+  // `route({ auth: { apiKey: false } })` — webhooks, OAuth provider callbacks,
+  // etc. — are skipped based on the central `routeRegistry`. Unknown paths
+  // fall through to the bearer check (fail-closed).
+  if (apiKey) {
+    const pathSegments = getPathSegments(req.url || "");
+    if (!isPublicRoute(req.method, pathSegments)) {
+      const authHeader = req.headers.authorization;
+      const providedKey = authHeader?.startsWith("Bearer ") ? authHeader.slice(7) : null;
+
+      if (providedKey !== apiKey) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return true;
+      }
     }
   }
 

package/src/http/mcp-oauth.ts

@@ -158,6 +158,27 @@ const authorizeRoute = route({
   },
 });
 
+const authorizeUrlRoute = route({
+  method: "get",
+  path: "/api/mcp-oauth/{mcpServerId}/authorize-url",
+  pattern: ["api", "mcp-oauth", null, "authorize-url"],
+  summary:
+    "Build an OAuth authorize URL. Returns JSON so the browser can navigate without losing the Bearer auth header.",
+  tags: ["MCP OAuth"],
+  auth: { apiKey: true },
+  params: z.object({ mcpServerId: z.string() }),
+  query: z.object({
+    redirect: z.string().optional(),
+    userId: z.string().optional(),
+    scopes: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "{ providerUrl: string }" },
+    400: { description: "MCP has no URL / does not require OAuth" },
+    404: { description: "MCP server not found" },
+  },
+});
+
 const callbackRoute = route({
   method: "get",
   path: "/api/mcp-oauth/callback",
@@ -236,6 +257,86 @@ const manualClientRoute = route({
   },
 });
 
+// ─── Shared authorize flow ───────────────────────────────────────────────────
+
+interface AuthorizeFlowQuery {
+  redirect?: string;
+  userId?: string;
+  scopes?: string;
+}
+
+/**
+ * Discover metadata, DCR-register (or fail), build the authorize URL, and
+ * persist the pending session. Returns the provider `providerUrl` the caller
+ * should redirect to / respond with. On failure, writes a JSON error response
+ * and returns null.
+ */
+async function prepareAuthorizeFlow(
+  res: ServerResponse,
+  mcpServerId: string,
+  server: NonNullable<ReturnType<typeof getMcpServerById>>,
+  q: AuthorizeFlowQuery,
+): Promise<string | null> {
+  const discovery = await discoverForMcp(server.url!);
+  if (!discovery) {
+    jsonError(res, "MCP server does not require OAuth", 400);
+    return null;
+  }
+
+  let clientId: string | null = null;
+  let clientSecret: string | null = null;
+  if (discovery.dcrSupported && discovery.registrationEndpoint) {
+    const dcr = await registerClient(discovery.registrationEndpoint, {
+      client_name: `agent-swarm (${server.name})`,
+      redirect_uris: [callbackRedirectUri()],
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "client_secret_basic",
+      application_type: "web",
+      scope: (q.scopes ?? discovery.scopes.join(" ")) || undefined,
+    });
+    clientId = dcr.client_id;
+    clientSecret = dcr.client_secret ?? null;
+  } else {
+    jsonError(
+      res,
+      "DCR not supported — paste client_id/client_secret via POST /api/mcp-oauth/:id/manual-client first.",
+      400,
+    );
+    return null;
+  }
+
+  const scopes = q.scopes ? q.scopes.split(" ").filter(Boolean) : discovery.scopes;
+
+  const built = await buildAuthorizeUrl({
+    authorizeUrl: discovery.authorizeUrl,
+    tokenUrl: discovery.tokenUrl,
+    clientId: clientId!,
+    redirectUri: callbackRedirectUri(),
+    scopes,
+    resource: discovery.resourceUrl,
+  });
+
+  insertMcpOAuthPending({
+    state: built.state,
+    mcpServerId,
+    userId: q.userId ?? null,
+    codeVerifier: built.codeVerifier,
+    resourceUrl: discovery.resourceUrl,
+    authorizationServerIssuer: discovery.authorizationServerIssuer,
+    authorizeUrl: discovery.authorizeUrl,
+    tokenUrl: discovery.tokenUrl,
+    revocationUrl: discovery.revocationUrl,
+    scopes: scopes.join(" "),
+    dcrClientId: clientId!,
+    dcrClientSecret: clientSecret,
+    redirectUri: callbackRedirectUri(),
+    finalRedirect: q.redirect ?? null,
+  });
+
+  return built.url;
+}
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleMcpOAuth(
@@ -398,69 +499,40 @@ export async function handleMcpOAuth(
     if (!server) return true;
 
     try {
-      const discovery = await discoverForMcp(server.url!);
-      if (!discovery) {
-        jsonError(res, "MCP server does not require OAuth", 400);
-        return true;
-      }
-
-      // Dynamic Client Registration if supported, otherwise expect the user to
-      // have already called /manual-client.
-      let clientId: string | null = null;
-      let clientSecret: string | null = null;
-      if (discovery.dcrSupported && discovery.registrationEndpoint) {
-        const dcr = await registerClient(discovery.registrationEndpoint, {
-          client_name: `agent-swarm (${server.name})`,
-          redirect_uris: [callbackRedirectUri()],
-          grant_types: ["authorization_code", "refresh_token"],
-          response_types: ["code"],
-          token_endpoint_auth_method: "client_secret_basic",
-          application_type: "web",
-          scope: (parsed.query.scopes ?? discovery.scopes.join(" ")) || undefined,
-        });
-        clientId = dcr.client_id;
-        clientSecret = dcr.client_secret ?? null;
-      } else {
-        jsonError(
-          res,
-          "DCR not supported — paste client_id/client_secret via POST /api/mcp-oauth/:id/manual-client first.",
-          400,
-        );
-        return true;
-      }
+      const providerUrl = await prepareAuthorizeFlow(
+        res,
+        parsed.params.mcpServerId,
+        server,
+        parsed.query,
+      );
+      if (!providerUrl) return true;
+      res.writeHead(302, { Location: providerUrl });
+      res.end();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      jsonError(res, `Authorize failed: ${message}`, 502);
+    }
+    return true;
+  }
 
-      const scopes = parsed.query.scopes
-        ? parsed.query.scopes.split(" ").filter(Boolean)
-        : discovery.scopes;
-
-      const built = await buildAuthorizeUrl({
-        authorizeUrl: discovery.authorizeUrl,
-        tokenUrl: discovery.tokenUrl,
-        clientId: clientId!,
-        redirectUri: callbackRedirectUri(),
-        scopes,
-        resource: discovery.resourceUrl,
-      });
+  // GET /api/mcp-oauth/:id/authorize-url — JSON variant of /authorize so the
+  // dashboard can fetch the provider URL with Bearer auth and then navigate.
+  if (authorizeUrlRoute.match(req.method, pathSegments)) {
+    const parsed = await authorizeUrlRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
 
-      insertMcpOAuthPending({
-        state: built.state,
-        mcpServerId: parsed.params.mcpServerId,
-        userId: parsed.query.userId ?? null,
-        codeVerifier: built.codeVerifier,
-        resourceUrl: discovery.resourceUrl,
-        authorizationServerIssuer: discovery.authorizationServerIssuer,
-        authorizeUrl: discovery.authorizeUrl,
-        tokenUrl: discovery.tokenUrl,
-        revocationUrl: discovery.revocationUrl,
-        scopes: scopes.join(" "),
-        dcrClientId: clientId!,
-        dcrClientSecret: clientSecret,
-        redirectUri: callbackRedirectUri(),
-        finalRedirect: parsed.query.redirect ?? null,
-      });
+    const server = getMcpOrError(res, parsed.params.mcpServerId);
+    if (!server) return true;
 
-      res.writeHead(302, { Location: built.url });
-      res.end();
+    try {
+      const providerUrl = await prepareAuthorizeFlow(
+        res,
+        parsed.params.mcpServerId,
+        server,
+        parsed.query,
+      );
+      if (!providerUrl) return true;
+      json(res, { providerUrl });
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       jsonError(res, `Authorize failed: ${message}`, 502);

package/src/http/mcp-servers.ts

@@ -243,7 +243,11 @@ export async function handleMcpServers(
             try {
               const token = await ensureMcpToken(server.id);
               if (token && token.status === "connected") {
-                const prefix = token.tokenType || "Bearer";
+                // Normalize the bearer scheme to capital "Bearer": some resource
+                // servers reject the lowercase "bearer" RFC 6749 returns (issue #368).
+                // Non-bearer schemes (e.g. "MAC") are preserved verbatim.
+                const rawType = token.tokenType || "Bearer";
+                const prefix = rawType.toLowerCase() === "bearer" ? "Bearer" : rawType;
                 resolvedHeaders.Authorization = `${prefix} ${token.accessToken}`;
               } else if (!token) {
                 authError = "No OAuth token for this MCP server";

package/src/providers/claude-adapter.ts

@@ -106,6 +106,52 @@ async function fetchInstalledMcpServers(
   }
 }
 
+/**
+ * Merge a base MCP config (typically read from `.mcp.json`) with freshly-resolved
+ * installed servers from the API, and inject the per-task `X-Source-Task-Id` header
+ * into the `agent-swarm` entry.
+ *
+ * Precedence: installed servers from the API WIN over entries already in `.mcp.json`.
+ * This guards against stale credentials from a `.mcp.json` that was written once at
+ * container startup and never refreshed (see issue #369). The per-session fetch
+ * carries current OAuth tokens / rotated secrets / up-to-date installs.
+ *
+ * Exported for unit testing.
+ */
+export function mergeMcpConfig(
+  baseConfig: { mcpServers?: Record<string, unknown> } | null,
+  installedServers: Record<string, Record<string, unknown>> | null,
+  taskId: string,
+): { mcpServers: Record<string, unknown> } {
+  const config: { mcpServers: Record<string, unknown> } = {
+    mcpServers: { ...(baseConfig?.mcpServers ?? {}) },
+  };
+
+  // Installed servers from the API always win — fresh credentials replace stale ones.
+  if (installedServers) {
+    for (const [name, serverConfig] of Object.entries(installedServers)) {
+      config.mcpServers[name] = serverConfig;
+    }
+  }
+
+  // Find the agent-swarm server entry (could be named "agent-swarm" or similar)
+  const serverKey = Object.keys(config.mcpServers).find(
+    (k) =>
+      k === "agent-swarm" ||
+      ((config.mcpServers[k] as Record<string, unknown>)?.headers &&
+        ((config.mcpServers[k] as Record<string, Record<string, unknown>>).headers?.[
+          "X-Agent-ID"
+        ] as unknown)),
+  );
+  if (serverKey) {
+    const server = config.mcpServers[serverKey] as Record<string, unknown>;
+    if (!server.headers) server.headers = {};
+    (server.headers as Record<string, string>)["X-Source-Task-Id"] = taskId;
+  }
+
+  return config;
+}
+
 /**
  * Create a per-session MCP config file with X-Source-Task-Id header injected
  * and installed MCP servers merged in.
@@ -138,39 +184,14 @@ async function createSessionMcpConfig(
   if (!mcpJsonPath && !installedServers) return null;
 
   try {
-    let config: { mcpServers?: Record<string, unknown> } = { mcpServers: {} };
+    let baseConfig: { mcpServers?: Record<string, unknown> } = { mcpServers: {} };
     if (mcpJsonPath) {
       const file = Bun.file(mcpJsonPath);
-      config = await file.json();
-    }
-    const servers = config?.mcpServers;
-    if (!servers && !installedServers) return null;
-
-    if (!config.mcpServers) config.mcpServers = {};
-
-    // Find the agent-swarm server entry (could be named "agent-swarm" or similar)
-    const serverKey = Object.keys(config.mcpServers).find(
-      (k) =>
-        k === "agent-swarm" ||
-        ((config.mcpServers![k] as Record<string, unknown>)?.headers &&
-          ((config.mcpServers![k] as Record<string, Record<string, unknown>>).headers?.[
-            "X-Agent-ID"
-          ] as unknown)),
-    );
-    if (serverKey) {
-      const server = config.mcpServers[serverKey] as Record<string, unknown>;
-      if (!server.headers) server.headers = {};
-      (server.headers as Record<string, string>)["X-Source-Task-Id"] = taskId;
+      baseConfig = await file.json();
     }
+    if (!baseConfig?.mcpServers && !installedServers) return null;
 
-    // Merge installed MCP servers (don't overwrite existing entries)
-    if (installedServers) {
-      for (const [name, serverConfig] of Object.entries(installedServers)) {
-        if (!config.mcpServers[name]) {
-          config.mcpServers[name] = serverConfig;
-        }
-      }
-    }
+    const config = mergeMcpConfig(baseConfig, installedServers ?? null, taskId);
 
     // Write per-session config to /tmp — no race, each session has its own file
     const sessionConfigPath = `/tmp/mcp-${taskId}.json`;

package/src/server.ts

@@ -77,6 +77,7 @@ import { registerSlackListChannelsTool } from "./tools/slack-list-channels";
 import { registerSlackPostTool } from "./tools/slack-post";
 import { registerSlackReadTool } from "./tools/slack-read";
 import { registerSlackReplyTool } from "./tools/slack-reply";
+import { registerSlackStartThreadTool } from "./tools/slack-start-thread";
 import { registerSlackUploadFileTool } from "./tools/slack-upload-file";
 import { registerStoreProgressTool } from "./tools/store-progress";
 // Swarm config tools
@@ -189,6 +190,7 @@ export function createServer() {
   registerSlackReplyTool(server);
   registerSlackReadTool(server);
   registerSlackPostTool(server);
+  registerSlackStartThreadTool(server);
   registerSlackListChannelsTool(server);
   registerSlackUploadFileTool(server);
   registerSlackDownloadFileTool(server);

package/src/tests/claude-adapter.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { ClaudeAdapter } from "../providers/claude-adapter";
+import { ClaudeAdapter, mergeMcpConfig } from "../providers/claude-adapter";
 import type { ProviderSessionConfig } from "../providers/types";
 
 /** Minimal config for testing — sessions won't actually spawn in these unit tests */
@@ -103,6 +103,148 @@ describe("Claude stream-json event parsing", () => {
   });
 });
 
+describe("mergeMcpConfig (issue #369)", () => {
+  const TASK_ID = "task-abc-123";
+
+  test("returns only installed servers when base config is null", () => {
+    const installed = {
+      "my-mcp": {
+        type: "http",
+        url: "https://example.com",
+        headers: { Authorization: "Bearer x" },
+      },
+    };
+    const merged = mergeMcpConfig(null, installed, TASK_ID);
+    expect(merged.mcpServers["my-mcp"]).toEqual(installed["my-mcp"]);
+  });
+
+  test("returns only base servers when installedServers is null", () => {
+    const base = {
+      mcpServers: {
+        "agent-swarm": {
+          type: "http",
+          url: "http://localhost:3013/mcp",
+          headers: { Authorization: "Bearer KEY", "X-Agent-ID": "a1" },
+        },
+      },
+    };
+    const merged = mergeMcpConfig(base, null, TASK_ID);
+    const agentSwarm = merged.mcpServers["agent-swarm"] as Record<string, unknown>;
+    expect(agentSwarm).toBeDefined();
+    // Agent-swarm entry is augmented with X-Source-Task-Id
+    expect((agentSwarm.headers as Record<string, string>)["X-Source-Task-Id"]).toBe(TASK_ID);
+  });
+
+  test("installed servers OVERRIDE stale .mcp.json entries (precedence fix)", () => {
+    // Simulates: /workspace/.mcp.json has an entry baked at container startup with
+    // a stale OAuth Bearer; the per-session fetch returns a freshly-resolved Bearer.
+    // The merged config MUST carry the fresh token — this is the core of issue #369.
+    const base = {
+      mcpServers: {
+        stripe: {
+          type: "http",
+          url: "https://mcp.stripe.com",
+          headers: { Authorization: "Bearer STALE_TOKEN_FROM_STARTUP" },
+        },
+      },
+    };
+    const installed = {
+      stripe: {
+        type: "http",
+        url: "https://mcp.stripe.com",
+        headers: { Authorization: "Bearer FRESH_TOKEN_FROM_API" },
+      },
+    };
+    const merged = mergeMcpConfig(base, installed, TASK_ID);
+    const stripe = merged.mcpServers.stripe as Record<string, unknown>;
+    expect((stripe.headers as Record<string, string>).Authorization).toBe(
+      "Bearer FRESH_TOKEN_FROM_API",
+    );
+  });
+
+  test("installed-server removal is honored (uninstall propagates)", () => {
+    // Previously, if .mcp.json had `stripe` baked in but the server was uninstalled
+    // from the API, the stale entry persisted. With the precedence fix + skeleton
+    // .mcp.json, a server absent from installedServers stays in the merged config
+    // ONLY if it's also in base (e.g., manually-added) — no API-layer override is
+    // issued. This test confirms we don't spontaneously delete base entries; the
+    // docker-entrypoint change (don't bake installed servers) is what prevents
+    // stale uninstalls from persisting.
+    const base = {
+      mcpServers: {
+        "manually-configured": { type: "http", url: "https://x.test" },
+      },
+    };
+    const installed = {}; // Empty — nothing installed via API
+    const merged = mergeMcpConfig(base, installed, TASK_ID);
+    expect(merged.mcpServers["manually-configured"]).toBeDefined();
+  });
+
+  test("agent-swarm server gets X-Source-Task-Id injected", () => {
+    const base = {
+      mcpServers: {
+        "agent-swarm": {
+          type: "http",
+          url: "http://localhost:3013/mcp",
+          headers: { Authorization: "Bearer KEY", "X-Agent-ID": "a1" },
+        },
+      },
+    };
+    const merged = mergeMcpConfig(base, null, TASK_ID);
+    const agentSwarm = merged.mcpServers["agent-swarm"] as Record<string, unknown>;
+    const headers = agentSwarm.headers as Record<string, string>;
+    expect(headers["X-Source-Task-Id"]).toBe(TASK_ID);
+    // Existing headers preserved
+    expect(headers.Authorization).toBe("Bearer KEY");
+    expect(headers["X-Agent-ID"]).toBe("a1");
+  });
+
+  test("X-Source-Task-Id injection works on entry discovered by X-Agent-ID header", () => {
+    // Discovery path for non-standard server names.
+    const base = {
+      mcpServers: {
+        "custom-name-swarm": {
+          type: "http",
+          url: "http://localhost:3013/mcp",
+          headers: { Authorization: "Bearer KEY", "X-Agent-ID": "a1" },
+        },
+      },
+    };
+    const merged = mergeMcpConfig(base, null, TASK_ID);
+    const entry = merged.mcpServers["custom-name-swarm"] as Record<string, unknown>;
+    expect((entry.headers as Record<string, string>)["X-Source-Task-Id"]).toBe(TASK_ID);
+  });
+
+  test("does not mutate the input baseConfig", () => {
+    const base = {
+      mcpServers: {
+        stripe: {
+          type: "http",
+          url: "https://mcp.stripe.com",
+          headers: { Authorization: "Bearer STALE" },
+        },
+      },
+    };
+    const installed = {
+      stripe: {
+        type: "http",
+        url: "https://mcp.stripe.com",
+        headers: { Authorization: "Bearer FRESH" },
+      },
+    };
+    mergeMcpConfig(base, installed, TASK_ID);
+    // Original object should be untouched
+    expect((base.mcpServers.stripe.headers as Record<string, string>).Authorization).toBe(
+      "Bearer STALE",
+    );
+  });
+
+  test("empty base + empty installed yields empty mcpServers", () => {
+    const merged = mergeMcpConfig({ mcpServers: {} }, {}, TASK_ID);
+    expect(Object.keys(merged.mcpServers)).toHaveLength(0);
+  });
+});
+
 describe("Stale session retry logic", () => {
   test("--resume args are stripped correctly", () => {
     const args = ["--max-turns", "10", "--resume", "session-abc", "--verbose"];

package/src/tests/core-auth.test.ts

@@ -0,0 +1,142 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { handleCore } from "../http/core";
+// Importing the handlers here is load-bearing: each import populates
+// `routeRegistry` as a side effect via the `route()` factory, which is what
+// the auth middleware consults.
+import "../http/webhooks";
+import "../http/mcp-oauth";
+import "../http/trackers/linear";
+import "../http/workflows";
+
+const API_KEY = "test-secret-key";
+
+function createTestServer(apiKey: string): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const handled = await handleCore(req, res, myAgentId, apiKey);
+    if (!handled) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ passed: true }));
+    }
+  });
+}
+
+async function listen(server: Server): Promise<number> {
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const addr = server.address();
+  if (!addr || typeof addr === "string") throw new Error("no port");
+  return addr.port;
+}
+
+describe("handleCore auth middleware (route() auth.apiKey=false is honored)", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    server = createTestServer(API_KEY);
+    port = await listen(server);
+  });
+
+  afterAll(() => {
+    server.close();
+  });
+
+  test("public route (auth:{apiKey:false}) passes without a Bearer", async () => {
+    const res = await fetch(`http://localhost:${port}/api/mcp-oauth/callback`);
+    // The callback route is public — without a state param it returns 400
+    // from the handler, but it must NOT be 401 from the auth middleware.
+    expect(res.status).not.toBe(401);
+  });
+
+  test("authed route (no auth flag → default authed) returns 401 without Bearer", async () => {
+    // /api/mcp-oauth/<id>/status is declared with auth:{apiKey:true}
+    const res = await fetch(`http://localhost:${port}/api/mcp-oauth/some-id/status`);
+    expect(res.status).toBe(401);
+    const body = await res.json();
+    expect(body.error).toBe("Unauthorized");
+  });
+
+  test("authed route passes with correct Bearer", async () => {
+    const res = await fetch(`http://localhost:${port}/api/mcp-oauth/some-id/status`, {
+      headers: { Authorization: `Bearer ${API_KEY}` },
+    });
+    // Middleware passes (no 401). Downstream handler decides the final status.
+    expect(res.status).not.toBe(401);
+  });
+
+  test("authed route returns 401 with wrong Bearer", async () => {
+    const res = await fetch(`http://localhost:${port}/api/mcp-oauth/some-id/status`, {
+      headers: { Authorization: "Bearer WRONG" },
+    });
+    expect(res.status).toBe(401);
+  });
+
+  test("GitHub webhook is still public (auth:{apiKey:false})", async () => {
+    const res = await fetch(`http://localhost:${port}/api/github/webhook`, { method: "POST" });
+    expect(res.status).not.toBe(401);
+  });
+
+  test("GitLab webhook is still public", async () => {
+    const res = await fetch(`http://localhost:${port}/api/gitlab/webhook`, { method: "POST" });
+    expect(res.status).not.toBe(401);
+  });
+
+  test("AgentMail webhook is still public", async () => {
+    const res = await fetch(`http://localhost:${port}/api/agentmail/webhook`, { method: "POST" });
+    expect(res.status).not.toBe(401);
+  });
+
+  test("Linear webhook/authorize/callback are still public", async () => {
+    for (const path of [
+      "/api/trackers/linear/authorize",
+      "/api/trackers/linear/callback",
+      "/api/trackers/linear/webhook",
+    ]) {
+      const method = path.endsWith("/webhook") ? "POST" : "GET";
+      const res = await fetch(`http://localhost:${port}${path}`, { method });
+      expect(res.status).not.toBe(401);
+    }
+  });
+
+  test("Workflow webhook trigger is still public", async () => {
+    const res = await fetch(`http://localhost:${port}/api/webhooks/some-workflow-id`, {
+      method: "POST",
+    });
+    expect(res.status).not.toBe(401);
+  });
+
+  test("unknown /api/* path fails closed (401 without Bearer)", async () => {
+    const res = await fetch(`http://localhost:${port}/api/does-not-exist/xyz`);
+    expect(res.status).toBe(401);
+  });
+
+  test("/health is always public", async () => {
+    const res = await fetch(`http://localhost:${port}/health`);
+    expect(res.status).toBe(200);
+  });
+});
+
+describe("handleCore auth middleware (no API_KEY configured)", () => {
+  let server: Server;
+  let port: number;
+
+  beforeAll(async () => {
+    server = createTestServer(""); // empty == auth disabled
+    port = await listen(server);
+  });
+
+  afterAll(() => {
+    server.close();
+  });
+
+  test("authed routes pass without Bearer when API_KEY is empty", async () => {
+    const res = await fetch(`http://localhost:${port}/api/mcp-oauth/some-id/status`);
+    expect(res.status).not.toBe(401);
+  });
+});

package/src/tests/mcp-oauth-resolve-secrets.test.ts

@@ -101,6 +101,85 @@ describe("resolveSecrets integration — OAuth Authorization injection", () => {
     expect(match!.authError).toBeNull();
   });
 
+  test("lowercase 'bearer' tokenType is normalized to capital 'Bearer' in Authorization header", async () => {
+    // Providers that follow RFC 6749 strictly (e.g. Amplitude's MCP) return
+    // `token_type: "bearer"`. Some resource servers then reject the lowercase
+    // prefix with 401. The fix in src/http/mcp-servers.ts normalizes the
+    // scheme to capital "Bearer". See GitHub issue #368.
+    const agent = createAgent({
+      id: crypto.randomUUID(),
+      name: "oauth-agent-lowercase",
+      status: "idle",
+      isLead: false,
+    });
+    const mcp = createMcpServer({
+      name: "mcp-oauth-lowercase-bearer",
+      transport: "http",
+      url: "https://mcp.example.com",
+      scope: "agent",
+      ownerAgentId: agent.id,
+    });
+    installMcpServer(agent.id, mcp.id);
+    setMcpServerAuthMethod(mcp.id, "oauth");
+    upsertMcpOAuthToken({
+      mcpServerId: mcp.id,
+      accessToken: "lowercase-token-xyz",
+      refreshToken: null,
+      tokenType: "bearer", // lowercase, as RFC 6749 prescribes
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      resourceUrl: "https://mcp.example.com/",
+      authorizationServerIssuer: "https://as.example.com",
+      authorizeUrl: "https://as.example.com/authorize",
+      tokenUrl: "https://as.example.com/token",
+      clientSource: "dcr",
+      status: "connected",
+    });
+
+    const result = await agentMcpServers(agent.id);
+    const match = result.servers.find((s) => s.id === mcp.id);
+    expect(match).toBeTruthy();
+    expect(match!.resolvedHeaders?.Authorization).toBe("Bearer lowercase-token-xyz");
+    expect(match!.resolvedHeaders?.Authorization?.startsWith("Bearer ")).toBe(true);
+  });
+
+  test("non-bearer tokenType (e.g. 'MAC') is preserved verbatim in Authorization header", async () => {
+    // RFC 6749 allows non-bearer token types. The normalization must only
+    // touch the bearer scheme and leave others alone.
+    const agent = createAgent({
+      id: crypto.randomUUID(),
+      name: "oauth-agent-mac",
+      status: "idle",
+      isLead: false,
+    });
+    const mcp = createMcpServer({
+      name: "mcp-oauth-mac",
+      transport: "http",
+      url: "https://mcp.example.com",
+      scope: "agent",
+      ownerAgentId: agent.id,
+    });
+    installMcpServer(agent.id, mcp.id);
+    setMcpServerAuthMethod(mcp.id, "oauth");
+    upsertMcpOAuthToken({
+      mcpServerId: mcp.id,
+      accessToken: "mac-token-xyz",
+      refreshToken: null,
+      tokenType: "MAC",
+      expiresAt: new Date(Date.now() + 3600_000).toISOString(),
+      resourceUrl: "https://mcp.example.com/",
+      authorizationServerIssuer: "https://as.example.com",
+      authorizeUrl: "https://as.example.com/authorize",
+      tokenUrl: "https://as.example.com/token",
+      clientSource: "dcr",
+      status: "connected",
+    });
+
+    const result = await agentMcpServers(agent.id);
+    const match = result.servers.find((s) => s.id === mcp.id);
+    expect(match).toBeTruthy();
+    expect(match!.resolvedHeaders?.Authorization).toBe("MAC mac-token-xyz");
+  });
+
   test("OAuth server without token row surfaces authError", async () => {
     const agent = createAgent({
       id: crypto.randomUUID(),

package/src/tests/tool-annotations.test.ts

@@ -159,6 +159,7 @@ describe("Tool Annotations & Classification", () => {
       "slack-reply",
       "slack-read",
       "slack-post",
+      "slack-start-thread",
       "slack-upload-file",
       "slack-download-file",
       "slack-list-channels",

package/src/tools/slack-post.ts

@@ -9,14 +9,20 @@ export const registerSlackPostTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "slack-post",
     {
-      title: "Post new message to Slack channel",
+      title: "Post message to Slack channel",
       description:
-        "Post a new message to a Slack channel. This creates a new message (not a thread reply). Requires lead privileges.",
+        "Post a message to a Slack channel. By default creates a new top-level message; pass `threadTs` to post as a threaded reply under an existing message (obtain the ts from `slack-start-thread`). Requires lead privileges.",
       annotations: { openWorldHint: true },
 
       inputSchema: z.object({
         channelId: z.string().min(1).describe("The Slack channel ID to post to."),
         message: z.string().min(1).max(4000).describe("The message content to post."),
+        threadTs: z
+          .string()
+          .optional()
+          .describe(
+            "Optional parent message ts to thread under. Obtain via `slack-start-thread`. When omitted, posts as a new top-level message.",
+          ),
       }),
       outputSchema: z.object({
         success: z.boolean(),
@@ -24,7 +30,7 @@ export const registerSlackPostTool = (server: McpServer) => {
         messageTs: z.string().optional(),
       }),
     },
-    async ({ channelId, message }, requestInfo, _meta) => {
+    async ({ channelId, message, threadTs }, requestInfo, _meta) => {
       if (!requestInfo.agentId) {
         return {
           content: [{ type: "text", text: "Agent ID not found." }],
@@ -67,6 +73,7 @@ export const registerSlackPostTool = (server: McpServer) => {
           text: slackMessage, // Fallback for notifications
           username: agent.name,
           icon_emoji: ":crown:",
+          ...(threadTs ? { thread_ts: threadTs } : {}),
           blocks: [
             {
               type: "section",

package/src/tools/slack-start-thread.ts

@@ -0,0 +1,123 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById } from "@/be/db";
+import { getSlackApp } from "@/slack/app";
+import { markdownToSlack } from "@/slack/responses";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerSlackStartThreadTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "slack-start-thread",
+    {
+      title: "Start a new Slack thread",
+      description:
+        "Post a new top-level message to a Slack channel and return its ts so the caller can thread replies under it. Pass the returned `ts` as `threadTs` on subsequent `slack-post` calls to keep replies in the same thread. Requires lead privileges.",
+      annotations: { openWorldHint: true },
+
+      inputSchema: z.object({
+        channelId: z.string().min(1).describe("The Slack channel ID to post to."),
+        message: z.string().min(1).max(4000).describe("The message content to post."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        channelId: z.string().optional(),
+        ts: z.string().optional(),
+      }),
+    },
+    async ({ channelId, message }, requestInfo, _meta) => {
+      if (!requestInfo.agentId) {
+        return {
+          content: [{ type: "text", text: "Agent ID not found." }],
+          structuredContent: { success: false, message: "Agent ID not found." },
+        };
+      }
+
+      const agent = getAgentById(requestInfo.agentId);
+      if (!agent) {
+        return {
+          content: [{ type: "text", text: "Agent not found." }],
+          structuredContent: { success: false, message: "Agent not found." },
+        };
+      }
+
+      if (!agent.isLead) {
+        return {
+          content: [{ type: "text", text: "Posting to Slack channels requires lead privileges." }],
+          structuredContent: {
+            success: false,
+            message: "Posting to Slack channels requires lead privileges.",
+          },
+        };
+      }
+
+      const app = getSlackApp();
+      if (!app) {
+        return {
+          content: [{ type: "text", text: "Slack not configured." }],
+          structuredContent: { success: false, message: "Slack not configured." },
+        };
+      }
+
+      try {
+        const slackMessage = markdownToSlack(message);
+
+        const result = await app.client.chat.postMessage({
+          channel: channelId,
+          text: slackMessage, // Fallback for notifications
+          username: agent.name,
+          icon_emoji: ":crown:",
+          blocks: [
+            {
+              type: "section",
+              text: {
+                type: "mrkdwn",
+                text: slackMessage,
+              },
+            },
+          ],
+        });
+
+        const ts = result.ts;
+        const resolvedChannelId = result.channel ?? channelId;
+
+        if (!ts) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: "Message posted but Slack did not return a ts — cannot thread replies.",
+              },
+            ],
+            structuredContent: {
+              success: false,
+              message: "Message posted but Slack did not return a ts — cannot thread replies.",
+              channelId: resolvedChannelId,
+            },
+          };
+        }
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Thread started. channelId=${resolvedChannelId}, ts=${ts}. Pass ts as threadTs on slack-post to reply in-thread.`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message: "Thread started successfully.",
+            channelId: resolvedChannelId,
+            ts,
+          },
+        };
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        return {
+          content: [{ type: "text", text: `Failed to start thread: ${errorMsg}` }],
+          structuredContent: { success: false, message: `Failed to start thread: ${errorMsg}` },
+        };
+      }
+    },
+  );
+};

package/src/tools/tool-config.ts

@@ -80,13 +80,14 @@ export const DEFERRED_TOOLS = new Set([
   "context-history",
   "context-diff",
 
-  // Slack (6)
+  // Slack (7)
   "slack-reply",
   "slack-read",
   "slack-upload-file",
   "slack-download-file",
   "slack-list-channels",
   "slack-post",
+  "slack-start-thread",
 
   // Channel management (2)
   "create-channel",

package/src/tools/update-profile.ts

@@ -226,9 +226,12 @@ export const registerUpdateProfileTool = (server: McpServer) => {
           },
         );
 
-        // Write updated files to workspace only when updating self
+        // Write updated files to workspace only when updating self AND the caller
+        // matches the real running agent (process.env.AGENT_ID). This guards against
+        // unit tests (with fake WORKER_IDs) accidentally overwriting the container's
+        // SOUL.md/IDENTITY.md when the test suite runs inside a real agent container.
         // (remote agent files live on their own container)
-        if (isUpdatingSelf) {
+        if (isUpdatingSelf && requestInfo.agentId === process.env.AGENT_ID) {
           if (soulMd !== undefined) {
             try {
               await Bun.write("/workspace/SOUL.md", soulMd);