@desplega.ai/agent-swarm 1.150.0 → 1.152.0

package/src/tests/slack-task-output.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { slackTaskOutput } from "../slack/task-output";
+
+const task = {
+  status: "completed" as const,
+  tags: ["deferred"],
+  output:
+    "Deferred until tomorrow 17:30 UTC ([12345678](https://example.com/schedules/12345678)) -> check the build",
+};
+
+describe("Slack deferral output", () => {
+  test("keeps the pending work without the ETA or schedule link", () => {
+    expect(slackTaskOutput(task)).toBe("Pending: check the build");
+    expect(task.output).toContain("tomorrow 17:30 UTC");
+  });
+
+  test("removes an ETA-only line and preserves punctuation in the pending description", () => {
+    expect(slackTaskOutput({ ...task, output: task.output.replace("check the build", "") })).toBe(
+      "",
+    );
+    expect(slackTaskOutput({ ...task, output: `${task.output} (CI) -> deploy` })).toBe(
+      "Pending: check the build (CI) -> deploy",
+    );
+  });
+
+  test("preserves final continuation results even with inherited deferred tags", () => {
+    expect(slackTaskOutput({ ...task, output: "Build passed." })).toBe("Build passed.");
+  });
+
+  test("preserves schema output and non-deferral output verbatim", () => {
+    expect(slackTaskOutput({ ...task, outputSchema: { type: "string" } })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, tags: [] })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, status: "in_progress" })).toBe(task.output);
+    expect(slackTaskOutput({ ...task, output: undefined })).toBeUndefined();
+  });
+});

package/src/tests/status.test.ts

@@ -31,6 +31,7 @@ import {
   updateAgentCredStatus,
 } from "../be/db";
 import { storeOAuthTokens, upsertOAuthApp } from "../be/db-queries/oauth";
+import { resetEmbeddingProvider } from "../be/memory";
 import { validateProviderCredentials } from "../commands/provider-credentials";
 import {
   _resetTestConnectionCache,
@@ -123,6 +124,11 @@ function clearEnv() {
   for (const k of ENV_KEYS_TO_RESET) {
     delete process.env[k];
   }
+  // The embedding provider memoizes its API key at construction (see
+  // OpenAIEmbeddingProvider); reset the singleton so embeddingsMilestone()
+  // (which now reads the live provider, not process.env directly) reflects
+  // whatever this test just set/cleared instead of a stale prior test's key.
+  resetEmbeddingProvider();
 }
 
 function restoreEnv() {
@@ -245,14 +251,20 @@ describe("setup milestones", () => {
       hint: "Memory search is off. Set OPENAI_API_KEY (or EMBEDDING_API_KEY) on the API server to enable it; it is cheap.",
     });
 
+    // The provider memoizes its API key at construction; in production a
+    // config reload resets it (see resetEmbeddingProvider in src/http/core.ts).
+    // Mirror that here after each direct env mutation.
     process.env.OPENAI_API_KEY = "example-openai-embedding-key";
+    resetEmbeddingProvider();
     expect(getMilestone(await buildStatusPayload(), "embeddings").state).toBe("configured");
 
     process.env.EMBEDDING_API_KEY = "";
+    resetEmbeddingProvider();
     expect(getMilestone(await buildStatusPayload(), "embeddings").state).toBe("unverified");
 
     process.env.EMBEDDING_API_KEY = "example-dedicated-embedding-key";
     delete process.env.OPENAI_API_KEY;
+    resetEmbeddingProvider();
     expect(getMilestone(await buildStatusPayload(), "embeddings").state).toBe("configured");
   });
 

package/src/tests/steering-enabled.test.ts

@@ -48,12 +48,11 @@ function restoreEnv(name: string, value: string | undefined): void {
 }
 
 /**
- * Steering is opt-in (disabled unless STEERING_ENABLED=true|1), so "disabled"
- * is simply the default: unset the flag for the duration of the callback.
+ * Exercise an explicit opt-out without depending on the deployment default.
  */
 async function withSteeringDisabled<T>(run: () => Promise<T> | T): Promise<T> {
   const previous = process.env.STEERING_ENABLED;
-  delete process.env.STEERING_ENABLED;
+  process.env.STEERING_ENABLED = "false";
   try {
     return await run();
   } finally {
@@ -116,8 +115,7 @@ async function api(
 const originalSteeringEnabled = process.env.STEERING_ENABLED;
 
 beforeAll(async () => {
-  // The "enabled" halves of these tests opt in explicitly (steering is off by
-  // default); withSteeringDisabled() drops the flag to exercise the default.
+  // Pin both branches explicitly so inherited configuration cannot affect them.
   process.env.STEERING_ENABLED = "true";
   await removeTestDb();
   process.env.DATABASE_PATH = TEST_DB_PATH;
@@ -147,9 +145,9 @@ afterAll(async () => {
   await removeTestDb();
 });
 
-describe("STEERING_ENABLED opt-in", () => {
-  test("steering is disabled by default (flag unset) and on falsy values", () => {
-    expect(isSteeringEnabled({})).toBe(false);
+describe("STEERING_ENABLED defaults and overrides", () => {
+  test("steering defaults on and accepts explicit opt-outs", () => {
+    expect(isSteeringEnabled({})).toBe(true);
     expect(isSteeringEnabled({ STEERING_ENABLED: "false" })).toBe(false);
     expect(isSteeringEnabled({ STEERING_ENABLED: "0" })).toBe(false);
     expect(isSteeringEnabled({ STEERING_ENABLED: "true" })).toBe(true);

package/src/tests/store-progress-attachments-handler.test.ts

@@ -17,7 +17,7 @@
  *      org/drive and credentials
  *   4. missing files and wrong drives both block attachment + task writes
  */
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, describe, expect, spyOn, test } from "bun:test";
 import crypto from "node:crypto";
 import { unlink } from "node:fs/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -34,6 +34,7 @@ import {
   upsertSwarmConfig,
 } from "../be/db";
 import { registerStoreProgressTool } from "../tools/store-progress";
+import malformedOutput from "./fixtures/store-progress-malformed-output.json";
 
 const TEST_DB_PATH = "./test-store-progress-attachments-handler.sqlite";
 const ORIGINAL_FETCH = globalThis.fetch;
@@ -137,6 +138,104 @@ describe("store-progress handler — attachments insert path", () => {
     };
   }
 
+  test("salvages the literal 59811b57 output and registers both URL attachments", async () => {
+    const task = await createTaskExtended("salvage leaked tool parameters", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      { taskId: task.id, status: "completed", output: malformedOutput.output },
+      buildMeta(),
+    )) as StoreProgressResult;
+
+    expect(result.structuredContent.success).toBe(true);
+    const saved = await getTaskById(task.id);
+    expect(saved?.output).toBe(malformedOutput.output.split("</output>")[0]);
+    expect(saved?.output?.endsWith("reposted clean.")).toBe(true);
+    const attachments = await getTaskAttachments(task.id);
+    expect(attachments).toHaveLength(2);
+    expect(attachments.every((a) => a.kind === "url")).toBe(true);
+    expect(attachments.map((a) => a.url).sort()).toEqual([
+      "https://api.desplega.agent-swarm.dev/p/556b11781dbb40bf9b1eb1b3315adae6",
+      "https://x.com/desplegalabs/status/2100595056939827590",
+    ]);
+    expect(attachments.find((a) => a.isPrimary)?.name).toBe("X reply in the Jev thread");
+  });
+
+  test("preserves clean output byte-for-byte", async () => {
+    const output = "The output is ready: 2 < 3.\n  Keep this whitespace.  ";
+    const task = await createTaskExtended("clean output control", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      { taskId: task.id, status: "completed", output },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(true);
+    expect((await getTaskById(task.id))?.output).toBe(output);
+    expect(await getTaskAttachments(task.id)).toHaveLength(0);
+  });
+
+  test.each([
+    ["invalid JSON", '</output>\n<parameter name="attachments">[broken'],
+    ["invalid attachment schema", '</output><parameter name="attachments">[{"kind":"url"}]'],
+    ["unknown parameter", '</output><parameter name="status">"failed"'],
+    ["alternate closing tag", '</parameter>\n<parameter name="progress">Not JSON'],
+    ["bare opener", '<parameter name="progress">Not JSON'],
+    ["non-array JSON", '</output><parameter name="attachments">null'],
+  ])("strips %s without losing the clean result", async (_name, tail) => {
+    const task = await createTaskExtended("unrecoverable tail", { agentId });
+    await startTask(task.id);
+    const warning = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const result = (await buildServer().handler(
+        { taskId: task.id, status: "completed", output: `Clean result.${tail}` },
+        buildMeta(),
+      )) as StoreProgressResult;
+      expect(result.structuredContent.success).toBe(true);
+      expect((await getTaskById(task.id))?.output).toBe("Clean result.");
+      expect((await getTaskById(task.id))?.status).toBe("completed");
+      expect(await getTaskAttachments(task.id)).toHaveLength(0);
+      expect(warning).toHaveBeenCalledTimes(1);
+      expect(warning.mock.calls[0]?.[0]).not.toContain(tail);
+    } finally {
+      warning.mockRestore();
+    }
+  });
+
+  test("appends recovered pointers to explicit attachments through the normal dedupe path", async () => {
+    const task = await createTaskExtended("mixed explicit and leaked attachments", { agentId });
+    await startTask(task.id);
+    const attachment = { kind: "url", name: "link", url: "https://example.com/link" };
+    const result = (await buildServer().handler(
+      {
+        taskId: task.id,
+        status: "completed",
+        output: `Done.<parameter name="attachments">${JSON.stringify([attachment])}</parameter>`,
+        attachments: [attachment],
+      },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(true);
+    expect((await getTaskById(task.id))?.output).toBe("Done.");
+    expect(await getTaskAttachments(task.id)).toHaveLength(1);
+  });
+
+  test("recovered agent-fs pointers still require ordinary scope verification", async () => {
+    const task = await createTaskExtended("verify recovered pointer", { agentId });
+    await startTask(task.id);
+    const result = (await buildServer().handler(
+      {
+        taskId: task.id,
+        status: "completed",
+        output:
+          'Done.</output><parameter name="attachments">[{"kind":"agent-fs","name":"missing.md","path":"/missing.md"}]',
+      },
+      buildMeta(),
+    )) as StoreProgressResult;
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("both orgId and driveId must resolve");
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+    expect(await getTaskAttachments(task.id)).toHaveLength(0);
+  });
+
   test("inserts attachment row on an in-progress task (baseline)", async () => {
     const task = await createTaskExtended("handler in-progress baseline", {
       agentId,

package/src/tests/swarm-config-reserved-keys.test.ts

@@ -134,7 +134,12 @@ describe("swarm-config reserved keys guard", () => {
     await unlink(`${TEST_DB_PATH}-shm`).catch(() => {});
   });
 
-  for (const key of ["CORS_ALLOW_ANY_ORIGIN", "cors_allow_any_origin"]) {
+  for (const key of [
+    "CORS_ALLOW_ANY_ORIGIN",
+    "cors_allow_any_origin",
+    "EXTENSION_ALLOW_LEAD_ACTIVATION",
+    "extension_allow_lead_activation",
+  ]) {
     test(`rejects deployment-only ${key} through DB, HTTP, and MCP`, async () => {
       const config = { scope: "global" as const, key, value: "true" };
       await expect(upsertSwarmConfig(config)).rejects.toThrow(EXPECTED_MESSAGE(key));

package/src/tests/task-tool-preload-mcp.test.ts

@@ -73,11 +73,14 @@ async function pins(client: Client): Promise<string[]> {
     .sort();
 }
 
-test("wire response is default-off, per-task, additive, and fixed for one MCP session", async () => {
+test("wire response is default-on, per-task, additive, and fixed for one MCP session", async () => {
   const task = await createTaskExtended("review fixture", { agentId, taskType: "review" });
   const other = await createTaskExtended("other fixture", { agentId, taskType: "other" });
   const foreign = await createTaskExtended("unowned", { taskType: "review" });
   await configure("TASK_TOOL_MANIFESTS", '{"taskTypes":{"review":["script-run","get-tasks"]}}');
+  const defaultOn = await connect(task.id);
+  expect(await pins(defaultOn)).toEqual(["get-tasks", "script-run"]);
+  await configure("TASK_TOOL_PRELOAD_ENABLED", "false");
   const off = await connect(task.id);
   const baseline = (await off.listTools()).tools;
   expect(baseline.some((tool) => tool.name === "script-run")).toBe(true);

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

@@ -378,7 +378,7 @@ describe("Tool Annotations & Classification", () => {
     // Includes 11 skill tools, 7 MCP server tools, reusable script tools, and the
     // native Kapso/WhatsApp tools (register/unregister number + send/reply message).
     expect(count).toBeGreaterThanOrEqual(45);
-    expect(count).toBeLessThanOrEqual(141);
+    expect(count).toBeLessThanOrEqual(147);
   });
 
   test("core tools are fewer than deferred tools", () => {

package/src/tests/tool-registrar-no-input.test.ts

@@ -1,7 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
-import { createToolRegistrar } from "../tools/utils";
+import {
+  createToolRegistrar,
+  finalizeSwarmToolResult,
+  markExtensionRequestOrigin,
+} from "../tools/utils";
 
 describe("createToolRegistrar with no inputSchema", () => {
   test("handler receives requestInfo from meta when no inputSchema is defined", async () => {
@@ -117,4 +121,41 @@ describe("createToolRegistrar with no inputSchema", () => {
     });
     expect(result).toBeDefined();
   });
+
+  test("server-marked extension calls carry extension origin", async () => {
+    const server = new McpServer({ name: "test-extension-origin", version: "1.0.0" });
+    let callOrigin: string | undefined;
+    createToolRegistrar(server)(
+      "test-extension-origin-tool",
+      {
+        inputSchema: z.object({}),
+        outputSchema: z.looseObject({}),
+      },
+      async (_args, requestInfo) => {
+        callOrigin = requestInfo.callOrigin;
+        return { ok: true, message: "ok" };
+      },
+    );
+    const registeredTools = (server as Record<string, unknown>)._registeredTools as Record<
+      string,
+      { handler: (args: unknown, extra: unknown) => Promise<unknown> }
+    >;
+    const extra = markExtensionRequestOrigin({
+      sessionId: "extension",
+      requestInfo: { headers: { "x-agent-id": "extension-agent" } },
+    });
+
+    await registeredTools["test-extension-origin-tool"]!.handler({}, extra);
+    expect(callOrigin).toBe("extension");
+  });
+
+  test("extension calls bypass the model context ceiling", async () => {
+    const result = await finalizeSwarmToolResult(
+      "large-extension-result",
+      { ok: true, message: "ok", data: { value: "x".repeat(1_100_000) } },
+      { agentId: "extension-agent", callOrigin: "extension" },
+    );
+    expect(result.structuredContent?.truncation).toBeUndefined();
+    expect((result.structuredContent?.value as string).length).toBe(1_100_000);
+  });
 });

package/src/tools/defer-task.ts

@@ -169,7 +169,7 @@ export const registerDeferTaskTool = (server: McpServer) => {
           })
           .optional()
           .describe(
-            "Wake early on a task event. Provide taskId or nonempty, unique taskIds. mode defaults to all (every member must match); any wakes on the first match. settled covers completed or failed. Deferred members follow their continuations. Any already-terminal member rejects the request; one delayMs/runAt ceiling is still required for the whole set.",
+            "Wake early on a task event. Provide taskId or nonempty, unique taskIds. mode defaults to all (every member must match); any wakes on the first match. settled covers completed, failed, or cancelled. Deferred and superseded members follow their continuations; a superseded member without a resume child holds to the ceiling. Any already-terminal member rejects the request; one delayMs/runAt ceiling is still required for the whole set.",
           ),
         summary: z
           .string()

package/src/tools/extension-activate-version.ts

@@ -0,0 +1,38 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionActivateVersionTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-activate-version",
+    {
+      title: "Extension Activate Version",
+      description:
+        "Activate a stored extension version, reloading it if enabled. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+          version: z.number().int().min(1).describe("Stored version number to activate."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/activate-version`,
+        body: { version: args.version },
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension activated.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-common.ts

@@ -0,0 +1,85 @@
+import * as z from "zod";
+import { proxySwarmApi } from "./script-common";
+import { type RequestInfo, type SwarmToolResult, swarmToolOutputSchema, toolErr } from "./utils";
+
+export const EXTENSION_TRANSPORT_ERROR =
+  "extension_* tools require HTTP MCP transport because agent identity is unavailable over stdio. Use MCP_BASE_URL=http://... or invoke the HTTP API directly.";
+
+const extensionListItemSchema = z.looseObject({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  version: z.number().optional(),
+  activeVersion: z.number().optional(),
+  enabled: z.boolean().optional(),
+  status: z.string().optional(),
+  priority: z.number().optional(),
+  consecutiveFailures: z.number().optional(),
+});
+
+export const extensionToolOutputSchema = swarmToolOutputSchema({
+  id: z.string().optional(),
+  name: z.string().optional(),
+  version: z.number().optional(),
+  activeVersion: z.number().optional(),
+  enabled: z.boolean().optional(),
+  status: z.string().optional(),
+  priority: z.number().optional(),
+  consecutiveFailures: z.number().optional(),
+  contentDeduped: z.boolean().optional(),
+  deleted: z.boolean().optional(),
+  extensions: z.array(extensionListItemSchema).optional(),
+});
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function coerceExtensionSummary(entry: unknown) {
+  const extension = isRecord(entry) ? entry : {};
+  return {
+    id: typeof extension.id === "string" ? extension.id : undefined,
+    name: typeof extension.name === "string" ? extension.name : undefined,
+    version: typeof extension.version === "number" ? extension.version : undefined,
+    activeVersion:
+      typeof extension.activeVersion === "number" ? extension.activeVersion : undefined,
+    enabled: typeof extension.enabled === "boolean" ? extension.enabled : undefined,
+    status: typeof extension.status === "string" ? extension.status : undefined,
+    priority: typeof extension.priority === "number" ? extension.priority : undefined,
+    consecutiveFailures:
+      typeof extension.consecutiveFailures === "number" ? extension.consecutiveFailures : undefined,
+  };
+}
+
+function errorMessage(data: unknown, status: number): string {
+  if (isRecord(data) && typeof data.error === "string" && data.error) return data.error;
+  return `Extensions API request failed with ${status}`;
+}
+
+function renderDiagnostics(data: unknown): string | undefined {
+  if (!isRecord(data) || !Array.isArray(data.diagnostics)) return undefined;
+  const diagnostics = data.diagnostics.map(String).filter(Boolean);
+  return diagnostics.length > 0 ? diagnostics.join("\n") : undefined;
+}
+
+export async function proxyExtensionsApi<T>(args: {
+  method: "GET" | "POST" | "DELETE";
+  path: string;
+  body?: unknown;
+  requestInfo: RequestInfo;
+  success: (data: unknown) => SwarmToolResult<T & Record<string, unknown>>;
+}): Promise<SwarmToolResult<T & Record<string, unknown>>> {
+  return proxySwarmApi({
+    ...args,
+    transportError: EXTENSION_TRANSPORT_ERROR,
+    respond: (data, response) => {
+      if (!response.ok) {
+        const diagnostics = renderDiagnostics(data);
+        if (response.status === 400 && diagnostics) {
+          return toolErr("Extension rejected by typecheck.", { details: diagnostics });
+        }
+        return toolErr(errorMessage(data, response.status), { details: diagnostics });
+      }
+      return args.success(data);
+    },
+  });
+}

package/src/tools/extension-delete.ts

@@ -0,0 +1,29 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import { extensionToolOutputSchema, proxyExtensionsApi } from "./extension-common";
+
+export const registerExtensionDeleteTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-delete",
+    {
+      title: "Extension Delete",
+      description:
+        "Uninstall a disabled extension and delete its stored history. Disable it first with extension-disable. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false, destructiveHint: true },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "DELETE",
+        path: `/api/extensions/${args.id}`,
+        requestInfo,
+        success: () => toolOk("Extension deleted.", { data: { id: args.id, deleted: true } }),
+      }),
+  );
+};

package/src/tools/extension-disable.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionDisableTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-disable",
+    {
+      title: "Extension Disable",
+      description:
+        "Unload and disable an installed extension. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/disable`,
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension disabled.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-enable.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const registerExtensionEnableTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-enable",
+    {
+      title: "Extension Enable",
+      description:
+        "Load and enable an installed extension. Requires a lead, operator, or dashboard user.",
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          id: z.string().uuid().describe("Installed extension ID from extension-list."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: `/api/extensions/${args.id}/enable`,
+        requestInfo,
+        success: (data) =>
+          toolOk("Extension enabled.", {
+            data: coerceExtensionSummary((data as { extension?: unknown }).extension),
+          }),
+      }),
+  );
+};

package/src/tools/extension-install.ts

@@ -0,0 +1,65 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar, toolOk } from "@/tools/utils";
+import { ExtensionManifestSchema } from "@/types";
+import {
+  coerceExtensionSummary,
+  extensionToolOutputSchema,
+  proxyExtensionsApi,
+} from "./extension-common";
+
+export const EXTENSION_INSTALL_DESCRIPTION =
+  "Validate and store a TypeScript extension bundle (manifest plus a files map with one hooks.ts). Fetch the hook contract first: GET /api/extensions/type-defs returns swarm-extension.d.ts with every event and modify shape. The extension remains disabled until a lead, operator, or dashboard user enables it with extension-enable.";
+
+function extensionInstallResult(data: unknown, fallbackName: string) {
+  const body = data as {
+    extension?: unknown;
+    contentDeduped?: unknown;
+  };
+  const extension = coerceExtensionSummary(body.extension);
+  const name = extension.name ?? fallbackName;
+  const version = typeof extension.version === "number" ? ` v${extension.version}` : "";
+  const deduped = body.contentDeduped === true ? " Content was unchanged." : "";
+  const enableInstruction =
+    "A lead, operator, or dashboard user can enable it with `extension-enable` or `POST /api/extensions/{id}/enable`.";
+
+  return toolOk(`Extension \`${name}\`${version} installed.${deduped} ${enableInstruction}`, {
+    data: {
+      ...extension,
+      name,
+      contentDeduped: body.contentDeduped === true,
+    },
+  });
+}
+
+export const registerExtensionInstallTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "extension-install",
+    {
+      title: "Extension Install",
+      description: EXTENSION_INSTALL_DESCRIPTION,
+      annotations: { openWorldHint: false },
+      inputSchema: z
+        .object({
+          manifest: ExtensionManifestSchema.describe("Extension bundle manifest."),
+          files: z.record(z.string(), z.string()).describe("Bundle files keyed by relative path."),
+          priority: z
+            .number()
+            .int()
+            .optional()
+            .describe("Handler priority. Lower values run first."),
+          config: z.record(z.string(), z.unknown()).optional().describe("Extension configuration."),
+        })
+        .strict(),
+      outputSchema: extensionToolOutputSchema,
+    },
+    async (args, requestInfo) =>
+      proxyExtensionsApi({
+        method: "POST",
+        path: "/api/extensions/install",
+        body: args,
+        requestInfo,
+        success: (data) => extensionInstallResult(data, args.manifest.name),
+      }),
+  );
+};