@desplega.ai/agent-swarm 1.87.0 → 1.89.0

package/src/tests/kapso-inbound.test.ts

@@ -1,4 +1,4 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import crypto from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { closeDb, createAgent, createUser, getKv, getTaskById, initDb } from "../be/db";
@@ -11,6 +11,7 @@ const TEST_DB_PATH = "./test-kapso-inbound.sqlite";
 const HMAC_SECRET = "kapso-test-hmac-secret";
 
 let agentId: string;
+const originalFetch = globalThis.fetch;
 
 function makePayload(opts: {
   phoneNumberId: string;
@@ -77,13 +78,21 @@ beforeAll(() => {
   }
   initDb(TEST_DB_PATH);
   process.env.KAPSO_WEBHOOK_HMAC_SECRET = HMAC_SECRET;
+  process.env.KAPSO_API_KEY = "kapso-test-api-key";
+  process.env.KAPSO_API_BASE_URL = "https://kapso.test";
   const agent = createAgent({ name: "KapsoWorker", isLead: false, status: "idle" });
   agentId = agent.id;
 });
 
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
 afterAll(() => {
   closeDb();
   delete process.env.KAPSO_WEBHOOK_HMAC_SECRET;
+  delete process.env.KAPSO_API_KEY;
+  delete process.env.KAPSO_API_BASE_URL;
   for (const suffix of ["", "-wal", "-shm"]) {
     try {
       require("node:fs").unlinkSync(`${TEST_DB_PATH}${suffix}`);
@@ -205,12 +214,18 @@ describe("routeKapsoInbound", () => {
 });
 
 describe("handleWebhooks — Kapso HMAC gate", () => {
-  test("valid HMAC + mapping hit → 200 and task routing", async () => {
+  test("valid HMAC + mapping hit → auto-acknowledges inbound, then 200 and task routing", async () => {
     putKapsoNumberMapping({
       phoneNumberId: "pn-http",
       agentId,
       createdAt: new Date().toISOString(),
     });
+    const calls: Array<{ url: string; body: Record<string, unknown> }> = [];
+    globalThis.fetch = (async (url: string, init: RequestInit) => {
+      calls.push({ url, body: JSON.parse(init.body as string) });
+      return new Response(JSON.stringify({ success: true }), { status: 200 });
+    }) as typeof fetch;
+
     const rawBody = JSON.stringify(
       makePayload({ phoneNumberId: "pn-http", messageId: "wamid.HTTP_OK" }),
     );
@@ -221,9 +236,52 @@ describe("handleWebhooks — Kapso HMAC gate", () => {
     expect(handled).toBe(true);
     expect(captured.status).toBe(200);
     expect(JSON.parse(captured.body)).toMatchObject({ received: true, routing: "task" });
+    expect(calls).toHaveLength(2);
+    expect(
+      calls.every((call) => call.url === "https://kapso.test/meta/whatsapp/v24.0/pn-http/messages"),
+    ).toBe(true);
+    expect(calls.map((call) => call.body)).toContainEqual({
+      messaging_product: "whatsapp",
+      status: "read",
+      message_id: "wamid.HTTP_OK",
+      typing_indicator: { type: "text" },
+    });
+    expect(calls.map((call) => call.body)).toContainEqual({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to: "34679077777",
+      type: "reaction",
+      reaction: { message_id: "wamid.HTTP_OK", emoji: "👀" },
+    });
+  });
+
+  test("Kapso acknowledgement failures do not block webhook success", async () => {
+    putKapsoNumberMapping({
+      phoneNumberId: "pn-http-ack-fail",
+      agentId,
+      createdAt: new Date().toISOString(),
+    });
+    globalThis.fetch = (async () => {
+      throw new Error("kapso unavailable");
+    }) as typeof fetch;
+
+    const rawBody = JSON.stringify(
+      makePayload({ phoneNumberId: "pn-http-ack-fail", messageId: "wamid.HTTP_ACK_FAIL" }),
+    );
+    const { req, res, captured } = fakeReqRes(rawBody, {
+      "x-webhook-signature": sign(HMAC_SECRET, rawBody),
+    });
+    const handled = await handleWebhooks(req, res, KAPSO_PATH);
+
+    expect(handled).toBe(true);
+    expect(captured.status).toBe(200);
+    expect(JSON.parse(captured.body)).toMatchObject({ received: true, routing: "task" });
   });
 
   test("valid HMAC + no mapping → 200 no_mapping (fallback, does not break)", async () => {
+    globalThis.fetch = (async () =>
+      new Response(JSON.stringify({ success: true }), { status: 200 })) as typeof fetch;
+
     const rawBody = JSON.stringify(
       makePayload({ phoneNumberId: "pn-http-unmapped", messageId: "wamid.HTTP_NOMAP" }),
     );

package/src/tests/metrics-http.test.ts

@@ -0,0 +1,247 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import crypto from "node:crypto";
+import { unlink } from "node:fs/promises";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import { closeDb, getMetricVersions, initDb } from "../be/db";
+import { handleMetrics } from "../http/metrics";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import type { Metric } from "../types";
+
+const TEST_DB_PATH = "./test-metrics-http.sqlite";
+const TEST_PORT = 13083;
+const BASE = `http://localhost:${TEST_PORT}`;
+
+type MetricRunResponse = {
+  widgets: Array<{
+    widget: { id: string };
+    result: {
+      columns: string[];
+      rows: Record<string, unknown>[];
+    };
+  }>;
+  result: {
+    columns: string[];
+    rows: Record<string, unknown>[];
+  };
+};
+
+function createTestServer(): Server {
+  return createHttpServer(async (req: IncomingMessage, res: ServerResponse) => {
+    res.setHeader("Content-Type", "application/json");
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const handled = await handleMetrics(req, res, pathSegments, queryParams, myAgentId);
+    if (!handled) {
+      res.writeHead(404);
+      res.end(JSON.stringify({ error: "not found" }));
+    }
+  });
+}
+
+describe("Metrics HTTP API", () => {
+  let server: Server;
+  const agentId = crypto.randomUUID();
+  const headers = { "Content-Type": "application/json", "X-Agent-ID": agentId };
+
+  beforeAll(async () => {
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+    initDb(TEST_DB_PATH);
+    server = createTestServer();
+    await new Promise<void>((resolve) => server.listen(TEST_PORT, () => resolve()));
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    closeDb();
+    for (const suffix of ["", "-wal", "-shm"]) {
+      try {
+        await unlink(`${TEST_DB_PATH}${suffix}`);
+      } catch {}
+    }
+  });
+
+  test("fresh DB seeds starter metrics", async () => {
+    const res = await fetch(`${BASE}/api/metrics/definitions?fields=full`);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { metrics: Metric[]; total: number };
+    expect(body.total).toBeGreaterThanOrEqual(1);
+    const starter = body.metrics.find((metric) => metric.slug === "swarm-operations-overview");
+    expect(starter?.definition.widgets.map((widget) => widget.viz.type)).toContain("multi-line");
+  });
+
+  test("create, run, update snapshots prior definition", async () => {
+    const created = await fetch(`${BASE}/api/metrics/definitions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug: "test-count",
+        title: "Test Count",
+        description: "Counts agent rows",
+        definition: {
+          version: 1,
+          widgets: [
+            {
+              id: "agent-count",
+              title: "Agent count",
+              query: { sql: "SELECT COUNT(*) AS count FROM agents", maxRows: 10 },
+              viz: { type: "stat", value: "count", format: "integer" },
+            },
+          ],
+        },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string; version: number };
+
+    const run = await fetch(`${BASE}/api/metrics/definitions/${id}/run`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ variables: {} }),
+    });
+    expect(run.status).toBe(200);
+    const runBody = (await run.json()) as MetricRunResponse;
+    expect(runBody.widgets[0]?.result.columns).toEqual(["count"]);
+    expect(runBody.widgets[0]?.result.rows[0]).toHaveProperty("count");
+
+    const updated = await fetch(`${BASE}/api/metrics/definitions/${id}`, {
+      method: "PUT",
+      headers,
+      body: JSON.stringify({
+        title: "Updated Count",
+        definition: {
+          version: 1,
+          widgets: [
+            {
+              id: "task-count",
+              title: "Task count",
+              query: { sql: "SELECT COUNT(*) AS count FROM agent_tasks", maxRows: 10 },
+              viz: { type: "stat", value: "count", format: "integer" },
+            },
+          ],
+        },
+      }),
+    });
+    expect(updated.status).toBe(200);
+    expect(getMetricVersions(id)).toHaveLength(1);
+    expect(getMetricVersions(id)[0]?.snapshot.title).toBe("Test Count");
+  });
+
+  test("humans can create metrics through the UI without an agent header", async () => {
+    const created = await fetch(`${BASE}/api/metrics/definitions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        slug: "ui-owned-count",
+        title: "UI Owned Count",
+        definition: {
+          version: 1,
+          widgets: [
+            {
+              id: "task-count",
+              title: "Task count",
+              query: { sql: "SELECT COUNT(*) AS count FROM agent_tasks", maxRows: 10 },
+              viz: { type: "stat", value: "count", format: "integer" },
+            },
+          ],
+        },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string; version: number };
+
+    const run = await fetch(`${BASE}/api/metrics/definitions/${id}/run`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ variables: {} }),
+    });
+    expect(run.status).toBe(200);
+    const runBody = (await run.json()) as MetricRunResponse;
+    expect(runBody.widgets[0]?.result.rows[0]).toHaveProperty("count");
+  });
+
+  test("run binds metric variables into query params", async () => {
+    const created = await fetch(`${BASE}/api/metrics/definitions`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        slug: "variable-count",
+        title: "Variable Count",
+        definition: {
+          version: 1,
+          variables: [
+            {
+              key: "status",
+              label: "Status",
+              type: "select",
+              defaultValue: "pending",
+              options: [
+                { label: "Pending", value: "pending" },
+                { label: "Completed", value: "completed" },
+              ],
+            },
+          ],
+          widgets: [
+            {
+              id: "status-count",
+              title: "Status count",
+              query: {
+                sql: "SELECT COUNT(*) AS count FROM agent_tasks WHERE status = ?",
+                params: ["{{status}}"],
+                maxRows: 10,
+              },
+              viz: { type: "stat", value: "count", format: "integer" },
+            },
+          ],
+        },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const { id } = (await created.json()) as { id: string; version: number };
+
+    const run = await fetch(`${BASE}/api/metrics/definitions/${id}/run`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ variables: { status: "completed" } }),
+    });
+    expect(run.status).toBe(200);
+    const runBody = (await run.json()) as MetricRunResponse & {
+      variables: Record<string, string>;
+    };
+    expect(runBody.variables.status).toBe("completed");
+    expect(runBody.widgets[0]?.result.rows[0]).toHaveProperty("count");
+  });
+
+  test("saved metric SQL rejects writes and multiple statements", async () => {
+    for (const sql of ["DELETE FROM agent_tasks", "SELECT 1; SELECT 2"]) {
+      const res = await fetch(`${BASE}/api/metrics/definitions`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          title: "Bad Metric",
+          definition: {
+            version: 1,
+            widgets: [
+              {
+                id: "bad",
+                title: "Bad",
+                query: { sql },
+                viz: { type: "stat", value: "x" },
+              },
+            ],
+          },
+        }),
+      });
+      expect(res.status).toBe(400);
+    }
+  });
+});

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

@@ -7,6 +7,7 @@
  */
 
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+import { writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Event as OpencodeEvent } from "@opencode-ai/sdk";
 import type { ProviderEvent, ProviderResult, ProviderSessionConfig } from "../providers/types";
@@ -47,7 +48,7 @@ let lastCreateOpencodeConfig: unknown;
 async function driveSession(
   events: OpencodeEvent[],
   cfg: ProviderSessionConfig = testConfig(),
-): Promise<{ emitted: ProviderEvent[]; result: ProviderResult }> {
+): Promise<{ emitted: ProviderEvent[]; result: ProviderResult; serverCloseCalls: () => number }> {
   const emitted: ProviderEvent[] = [];
 
   // Build the fake client/server pair used by the mock
@@ -67,7 +68,8 @@ async function driveSession(
     },
   };
 
-  const fakeServer = { url: "http://127.0.0.1:12345", close: mock(() => {}) };
+  const closeServer = mock(() => {});
+  const fakeServer = { url: "http://127.0.0.1:12345", close: closeServer };
 
   // Install mock BEFORE importing the adapter (Bun hoists mock.module)
   mock.module("@opencode-ai/sdk", () => ({
@@ -87,7 +89,54 @@ async function driveSession(
   await new Promise((r) => setTimeout(r, 0));
 
   const result = await session.waitForCompletion();
-  return { emitted, result };
+  return { emitted, result, serverCloseCalls: () => closeServer.mock.calls.length };
+}
+
+async function inspectSessionBeforeIdle(
+  cfg: ProviderSessionConfig,
+  inspect: () => Promise<void>,
+): Promise<void> {
+  const fakeSessionId = "sess-abc-123";
+  let releaseIdle!: () => void;
+  const idleReleased = new Promise<void>((resolve) => {
+    releaseIdle = resolve;
+  });
+
+  const fakeClient = {
+    session: {
+      create: async () => ({ data: { id: fakeSessionId }, error: undefined }),
+      prompt: async (args: unknown) => {
+        lastPromptArgs = args;
+        return { data: {}, error: undefined };
+      },
+    },
+    event: {
+      subscribe: async () => ({
+        stream: (async function* (): AsyncGenerator<OpencodeEvent> {
+          await idleReleased;
+          yield { type: "session.idle", properties: { sessionID: fakeSessionId } };
+        })(),
+      }),
+    },
+  };
+
+  const fakeServer = { url: "http://127.0.0.1:12345", close: mock(() => {}) };
+
+  mock.module("@opencode-ai/sdk", () => ({
+    createOpencode: async (opts: unknown) => {
+      lastCreateOpencodeConfig = opts;
+      return { client: fakeClient, server: fakeServer };
+    },
+  }));
+
+  const { OpencodeAdapter } = await import("../providers/opencode-adapter");
+  const adapter = new OpencodeAdapter();
+  const session = await adapter.createSession(cfg);
+  session.onEvent(() => {});
+  await new Promise((r) => setTimeout(r, 0));
+  await inspect();
+  releaseIdle();
+  await session.waitForCompletion();
 }
 
 // ── tests ─────────────────────────────────────────────────────────────────────
@@ -105,7 +154,7 @@ describe("OpencodeSession — SSE→ProviderEvent mapping", () => {
         properties: { sessionID: "sess-abc-123" },
       },
     ];
-    const { emitted, result } = await driveSession(events);
+    const { emitted, result, serverCloseCalls } = await driveSession(events);
 
     const resultEvent = emitted.find((e) => e.type === "result");
     expect(resultEvent).toBeDefined();
@@ -117,6 +166,21 @@ describe("OpencodeSession — SSE→ProviderEvent mapping", () => {
     expect(result.isError).toBe(false);
     expect(result.exitCode).toBe(0);
     expect(result.sessionId).toBe("sess-abc-123");
+    expect(serverCloseCalls()).toBe(1);
+  });
+
+  test("session.idle closes the server and drops later heartbeat events", async () => {
+    const events: OpencodeEvent[] = [
+      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
+      { type: "server.heartbeat", properties: {} } as OpencodeEvent,
+    ];
+    const { emitted, serverCloseCalls } = await driveSession(events);
+
+    expect(serverCloseCalls()).toBe(1);
+    const rawLogContents = emitted
+      .filter((e): e is Extract<ProviderEvent, { type: "raw_log" }> => e.type === "raw_log")
+      .map((e) => e.content);
+    expect(rawLogContents.some((content) => content.includes("server.heartbeat"))).toBe(false);
   });
 
   test("session.error → emits error event and fails result", async () => {
@@ -129,7 +193,7 @@ describe("OpencodeSession — SSE→ProviderEvent mapping", () => {
         },
       },
     ];
-    const { emitted, result } = await driveSession(events);
+    const { emitted, result, serverCloseCalls } = await driveSession(events);
 
     const errorEvent = emitted.find((e) => e.type === "error");
     expect(errorEvent).toBeDefined();
@@ -139,6 +203,7 @@ describe("OpencodeSession — SSE→ProviderEvent mapping", () => {
     expect(result.isError).toBe(true);
     expect(result.exitCode).toBe(1);
     expect(result.failureReason).toContain("provider overloaded");
+    expect(serverCloseCalls()).toBe(1);
   });
 
   test("prompt Model not found refreshes OpenRouter cache and retries once", async () => {
@@ -599,44 +664,134 @@ describe("OpencodeAdapter — per-task isolation (DES-300)", () => {
   });
 
   test("per-task agent file is written with system prompt", async () => {
-    const events: OpencodeEvent[] = [
-      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
-    ];
     const cwd = `/tmp/opencode-test-agent-${Date.now()}`;
     await Bun.$`mkdir -p ${cwd}`.quiet();
     const cfg = testConfig({ taskId: "task-agent-file", systemPrompt: "be a coder", cwd });
-    await driveSession(events, cfg);
+    await inspectSessionBeforeIdle(cfg, async () => {
+      const agentFile = Bun.file(join(cwd, ".opencode", "agents", "swarm-task-agent-file.md"));
+      const exists = await agentFile.exists();
+      expect(exists).toBe(true);
+      if (exists) {
+        const content = await agentFile.text();
+        expect(content).toContain("be a coder");
+      }
+    });
 
-    const agentFile = Bun.file(join(cwd, ".opencode", "agents", "swarm-task-agent-file.md"));
-    const exists = await agentFile.exists();
-    expect(exists).toBe(true);
-    if (exists) {
-      const content = await agentFile.text();
-      expect(content).toContain("be a coder");
-    }
     // Cleanup
     await Bun.$`rm -rf ${cwd}`.quiet().nothrow();
   });
 
   test("per-task config file is written as valid JSON", async () => {
-    const events: OpencodeEvent[] = [
-      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
-    ];
     const cfg = testConfig({ taskId: "task-cfg-json" });
-    await driveSession(events, cfg);
+    await inspectSessionBeforeIdle(cfg, async () => {
+      const configFile = Bun.file("/tmp/opencode-task-cfg-json.json");
+      const exists = await configFile.exists();
+      expect(exists).toBe(true);
+      if (exists) {
+        const text = await configFile.text();
+        expect(() => JSON.parse(text)).not.toThrow();
+        const parsed = JSON.parse(text) as { mcp?: unknown; permission?: unknown };
+        expect(parsed.mcp).toBeDefined();
+        expect(parsed.permission).toBeDefined();
+      }
+    });
 
-    const configFile = Bun.file("/tmp/opencode-task-cfg-json.json");
-    const exists = await configFile.exists();
-    expect(exists).toBe(true);
-    if (exists) {
-      const text = await configFile.text();
-      expect(() => JSON.parse(text)).not.toThrow();
-      const parsed = JSON.parse(text) as { mcp?: unknown; permission?: unknown };
-      expect(parsed.mcp).toBeDefined();
-      expect(parsed.permission).toBeDefined();
-    }
     // Cleanup
     await Bun.$`rm -f /tmp/opencode-task-cfg-json.json`.quiet().nothrow();
     await Bun.$`rm -rf /tmp/opencode-data-task-cfg-json`.quiet().nothrow();
   });
 });
+
+// ── Phase 4: context-mode in-process plugin ────────────────────────────────────
+
+describe("OpencodeAdapter — context-mode plugin wiring (phase 4)", () => {
+  let prevContextModeDisabled: string | undefined;
+  let prevContextModePluginPath: string | undefined;
+  // The global npm install of context-mode is absent in the test env, so point
+  // the override at a real temp file to make resolution succeed deterministically.
+  const fakePluginPath = "/tmp/ctx-mode-opencode-plugin.test.js";
+
+  beforeEach(() => {
+    prevContextModeDisabled = process.env.CONTEXT_MODE_DISABLED;
+    prevContextModePluginPath = process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH;
+    lastCreateOpencodeConfig = undefined;
+    mock.restore();
+  });
+
+  afterEach(() => {
+    // Never leak the env mutations across tests.
+    if (prevContextModeDisabled === undefined) delete process.env.CONTEXT_MODE_DISABLED;
+    else process.env.CONTEXT_MODE_DISABLED = prevContextModeDisabled;
+    if (prevContextModePluginPath === undefined)
+      delete process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH;
+    else process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = prevContextModePluginPath;
+    Bun.$`rm -rf /tmp/opencode-task-1.json /tmp/opencode-data-task-1`.quiet().nothrow();
+    Bun.$`rm -rf /tmp/test/.opencode`.quiet().nothrow();
+    Bun.$`rm -f ${fakePluginPath}`.quiet().nothrow();
+  });
+
+  /** Pull the opencode config object passed to createOpencode. */
+  function getBuiltConfig(): { plugin?: string[]; mcp?: Record<string, unknown> } {
+    const opts = lastCreateOpencodeConfig as {
+      config?: { plugin?: string[]; mcp?: Record<string, unknown> };
+    };
+    expect(opts.config).toBeDefined();
+    return opts.config as { plugin?: string[]; mcp?: Record<string, unknown> };
+  }
+
+  test("resolveContextModePluginPath returns the override path when it exists", async () => {
+    writeFileSync(fakePluginPath, "// test plugin\n");
+    process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = fakePluginPath;
+    const { resolveContextModePluginPath } = await import("../providers/opencode-adapter");
+    expect(resolveContextModePluginPath()).toBe(fakePluginPath);
+  });
+
+  test("resolveContextModePluginPath returns null when the override path is missing", async () => {
+    process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = "/tmp/ctx-mode-does-not-exist.js";
+    const { resolveContextModePluginPath } = await import("../providers/opencode-adapter");
+    expect(resolveContextModePluginPath()).toBeNull();
+  });
+
+  test("plugin array includes the resolved context-mode plugin path when available", async () => {
+    delete process.env.CONTEXT_MODE_DISABLED;
+    writeFileSync(fakePluginPath, "// test plugin\n");
+    process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = fakePluginPath;
+    const events: OpencodeEvent[] = [
+      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
+    ];
+    await driveSession(events, testConfig({ taskId: "task-1" }));
+
+    const built = getBuiltConfig();
+    expect(built.plugin).toContain(fakePluginPath);
+    // The bare package name must never be used — opencode can't resolve it offline.
+    expect(built.plugin).not.toContain("context-mode");
+  });
+
+  test("plugin array excludes context-mode when CONTEXT_MODE_DISABLED=true", async () => {
+    process.env.CONTEXT_MODE_DISABLED = "true";
+    writeFileSync(fakePluginPath, "// test plugin\n");
+    process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = fakePluginPath;
+    const events: OpencodeEvent[] = [
+      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
+    ];
+    await driveSession(events, testConfig({ taskId: "task-1" }));
+
+    const built = getBuiltConfig();
+    expect(built.plugin).not.toContain(fakePluginPath);
+    expect(built.plugin).not.toContain("context-mode");
+  });
+
+  test("context-mode does NOT appear in the mcp block", async () => {
+    delete process.env.CONTEXT_MODE_DISABLED;
+    writeFileSync(fakePluginPath, "// test plugin\n");
+    process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH = fakePluginPath;
+    const events: OpencodeEvent[] = [
+      { type: "session.idle", properties: { sessionID: "sess-abc-123" } },
+    ];
+    await driveSession(events, testConfig({ taskId: "task-1" }));
+
+    const built = getBuiltConfig();
+    expect(built.mcp).toBeDefined();
+    expect(built.mcp?.["context-mode"]).toBeUndefined();
+  });
+});

package/src/tests/prompt-template-session.test.ts

@@ -90,10 +90,12 @@ describe("Session templates — registration", () => {
     }
   });
 
-  test("total of 19 session/system templates registered", () => {
+  test("total of 20 session/system templates registered", () => {
     const all = getAllTemplateDefinitions();
     const sessionSystem = all.filter((d) => d.category === "system" || d.category === "session");
-    expect(sessionSystem.length).toBe(19);
+    // 20 = the original 19 + `system.session.worker.pi` (a pi-specific worker
+    // composite that omits the context_mode block — see session-templates.ts).
+    expect(sessionSystem.length).toBe(20);
   });
 });