@desplega.ai/agent-swarm 1.87.0 → 1.88.0

package/src/integrations/kapso/client.ts

@@ -20,6 +20,14 @@ export interface KapsoSendResult {
   errorMessage?: string;
 }
 
+/** Result of a lightweight message action through the Meta proxy. */
+export interface KapsoMessageActionResult {
+  ok: boolean;
+  status: number;
+  raw: unknown;
+  errorMessage?: string;
+}
+
 /** Meta error codes that mean "outside the 24h customer-service window". */
 const SESSION_WINDOW_ERROR_CODES = new Set([131047, 131051, 470]);
 
@@ -98,6 +106,80 @@ export async function sendKapsoText(params: {
   return { ok: true, status: res.status, messageId, raw, sessionWindowExpired: false };
 }
 
+/** Mark an inbound WhatsApp message as read, optionally showing the typing indicator. */
+export async function markKapsoMessageRead(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  messageId: string;
+  typingIndicatorType?: "text";
+}): Promise<KapsoMessageActionResult> {
+  const url = `${params.apiBaseUrl}/meta/whatsapp/v24.0/${params.phoneNumberId}/messages`;
+  const payload: Record<string, unknown> = {
+    messaging_product: "whatsapp",
+    status: "read",
+    message_id: params.messageId,
+  };
+  if (params.typingIndicatorType) {
+    payload.typing_indicator = { type: params.typingIndicatorType };
+  }
+
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      errorMessage: message ?? `Kapso mark-as-read failed with status ${res.status}`,
+    };
+  }
+
+  return { ok: true, status: res.status, raw };
+}
+
+/** React to an inbound WhatsApp message with an emoji. Pass an empty emoji to clear. */
+export async function sendKapsoReaction(params: {
+  apiBaseUrl: string;
+  apiKey: string;
+  phoneNumberId: string;
+  to: string;
+  messageId: string;
+  emoji: string;
+}): Promise<KapsoMessageActionResult> {
+  const url = `${params.apiBaseUrl}/meta/whatsapp/v24.0/${params.phoneNumberId}/messages`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": params.apiKey, "Content-Type": "application/json" },
+    body: JSON.stringify({
+      messaging_product: "whatsapp",
+      recipient_type: "individual",
+      to: params.to,
+      type: "reaction",
+      reaction: { message_id: params.messageId, emoji: params.emoji },
+    }),
+  });
+  const raw = await parseJsonSafe(res);
+
+  if (!res.ok) {
+    const { message } = extractMetaError(raw);
+    return {
+      ok: false,
+      status: res.status,
+      raw,
+      errorMessage: message ?? `Kapso reaction failed with status ${res.status}`,
+    };
+  }
+
+  return { ok: true, status: res.status, raw };
+}
+
 /** Result of configuring a webhook on a phone number. */
 export interface KapsoWebhookResult {
   ok: boolean;

package/src/memory/automatic-task-gate.ts

@@ -0,0 +1,47 @@
+const SCHEDULE_TAG_PREFIX = "schedule:";
+const AUTOMATIC_TASK_TYPES = new Set([
+  "boot-triage",
+  "heartbeat",
+  "heartbeat-checklist",
+  "health-check",
+  "health-probe",
+  "monitor",
+  "monitoring",
+]);
+
+export interface MemoryGateTask {
+  source?: string | null;
+  taskType?: string | null;
+  tags?: string[] | null;
+}
+
+export function isScheduledTaskCompletion(task: { tags?: string[] | null }): boolean {
+  return task.tags?.some((tag) => tag.startsWith(SCHEDULE_TAG_PREFIX)) ?? false;
+}
+
+export function isAutomaticOrRecurringTaskCompletion(task: MemoryGateTask): boolean {
+  const tags = task.tags ?? [];
+  const taskType = task.taskType?.toLowerCase();
+
+  return (
+    task.source === "schedule" ||
+    task.source === "system" ||
+    tags.includes("scheduled") ||
+    tags.includes("auto-generated") ||
+    tags.some((tag) => tag.startsWith(SCHEDULE_TAG_PREFIX)) ||
+    (taskType !== undefined &&
+      (AUTOMATIC_TASK_TYPES.has(taskType) ||
+        taskType.endsWith("-monitor") ||
+        taskType.endsWith("-digest")))
+  );
+}
+
+export function shouldPersistAutomaticTaskMemory(
+  task: MemoryGateTask,
+  persistMemory?: boolean,
+): boolean {
+  if (persistMemory) return true;
+  return !isAutomaticOrRecurringTaskCompletion(task);
+}
+
+export const shouldPersistTaskCompletionMemory = shouldPersistAutomaticTaskMemory;

package/src/prompts/base-prompt.ts

@@ -8,6 +8,7 @@
  */
 
 import type { ProviderTraits } from "../providers/types";
+import type { ProviderName } from "../types";
 import { resolveTemplateAsync } from "./resolver";
 
 // Side-effect import: register all system + session templates
@@ -55,6 +56,12 @@ export type BasePromptArgs = {
   swarmUrl: string;
   capabilities?: string[];
   traits?: ProviderTraits;
+  /**
+   * Harness provider for this session. Gates provider-specific prompt blocks
+   * (e.g. the context-mode block is excluded for `pi`, which has no
+   * context-mode MCP wiring yet — deferred to DES-514).
+   */
+  provider?: ProviderName;
   name?: string;
   description?: string;
   soulMd?: string;
@@ -91,8 +98,16 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
   if (!hasMcp) {
     // If no MCP, role cannot be lead
     compositeEventType = "system.session.worker.remote";
+  } else if (role === "lead") {
+    compositeEventType = "system.session.lead";
+  } else if (args.provider === "pi") {
+    // Pi has no context-mode MCP wiring yet (deferred to DES-514), so it uses a
+    // worker composite that omits the context_mode block to avoid advertising
+    // phantom `ctx_*` tools. All other local providers (claude, codex, opencode)
+    // keep the block via the standard worker composite.
+    compositeEventType = "system.session.worker.pi";
   } else {
-    compositeEventType = role === "lead" ? "system.session.lead" : "system.session.worker";
+    compositeEventType = "system.session.worker";
   }
   const compositeResult = await resolveTemplateAsync(compositeEventType, vars);
   let prompt = compositeResult.text;

package/src/prompts/session-templates.ts

@@ -377,6 +377,31 @@ registerTemplate({
 ### Context Window Management
 
 You have access to the \`context-mode\` MCP tools (\`batch_execute\`, \`execute\`, \`execute_file\`, \`search\`, \`fetch_and_index\`, \`index\`) which compress tool output to save context window space. For data-heavy operations (web fetches, large file reads, CLI output processing), prefer these over raw Bash/WebFetch to avoid flooding your context window with raw output.
+
+When a tool returns more than a few dozen lines — JSON payloads, log tails, search results, API responses — route it through \`ctx_execute\` or \`ctx_batch_execute\` so only the derived answer enters your conversation. This is especially important for tasks that make many Bash/Read/MCP calls in sequence; each raw response compounds context pressure.
+
+### Agent Scripts — for bulk, repetitive, or data-heavy work
+
+Use **scripts** (\`script-upsert\` + \`script-run\`) when a task involves repetitive SDK calls, large data processing, or deterministic multi-step pipelines. Scripts run out-of-process and return only their final result — none of the intermediate output floods your context window.
+
+**Decision rubric — when to use scripts vs. other approaches:**
+
+| Situation | Preferred approach |
+|---|---|
+| 1–10 SDK calls, result fits in context | Direct tool call |
+| 10+ items, bulk/fan-out SDK ops | **Script** (\`script-run\` with inline source or named) |
+| Heavy data (fetch + parse + transform) | **Script** or \`ctx_*\` (context-mode) |
+| Single expensive web fetch | \`ctx_fetch_and_index\` (context-mode) |
+| Multi-agent fan-out, parallel work, deterministic pipeline | **Workflow** |
+| One-off bash/TS with no reuse needed | \`code-mode run\` (Bash) |
+| Same logic needed across sessions/agents | **Named script** (\`script-upsert\` + reuse) |
+
+The 5 script tools (\`script-search\`, \`script-run\`, \`script-upsert\`, \`script-delete\`, \`script-query-types\`) are deferred tools. Call ToolSearch to load \`script-upsert\`, \`script-run\`, and \`script-query-types\` before using them.
+
+**Key gotchas:**
+- \`agentId\` IS propagated to scripts via the \`X-Agent-ID\` header.
+- \`taskId\` is NOT propagated to scripts — there is no ambient task context. Pass \`taskId\` explicitly via \`args\` if the script needs to call \`ctx.swarm.task_storeProgress\`.
+- Use \`script-query-types\` to inspect the live \`swarm-sdk.d.ts\` before authoring a complex script.
 `,
   variables: [],
   category: "system",
@@ -586,6 +611,32 @@ registerTemplate({
   category: "session",
 });
 
+// Pi-specific worker composite. Identical to `system.session.worker` except it
+// OMITS the `system.agent.context_mode` block — pi has no context-mode MCP
+// wiring yet (deferred to DES-514), so advertising the `ctx_*` tools to pi
+// workers would point at phantom tools. `getBasePrompt` selects this composite
+// when `provider === 'pi'`; all other local providers (claude, codex, opencode)
+// keep the context_mode block via `system.session.worker`.
+registerTemplate({
+  eventType: "system.session.worker.pi",
+  header: "",
+  defaultBody: `{{@template[system.agent.role]}}
+
+{{@template[system.agent.register]}}
+{{@template[system.agent.worker]}}
+{{@template[system.agent.filesystem]}}
+{{@template[system.agent.self_awareness]}}
+
+{{@template[system.agent.system]}}
+{{@template[system.agent.share_urls]}}
+{{@template[system.agent.code_quality]}}`,
+  variables: [
+    { name: "role", description: "The agent's role" },
+    { name: "agentId", description: "The agent's unique identifier" },
+  ],
+  category: "session",
+});
+
 // ============================================================================
 // Remote provider templates (no MCP, no Docker container)
 // ============================================================================

package/src/providers/claude-adapter.ts

@@ -16,6 +16,7 @@ import {
 } from "../utils/error-tracker";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
 import { buildOtelTraceparentEnv, isHarnessOtelEnabled } from "./otel-env";
 import type {
   CostData,
@@ -256,6 +257,23 @@ export async function createSessionMcpConfig(
 
   if (Object.keys(mergedServers).length === 0 && !installedServers) return null;
 
+  // Inject the context-mode stdio MCP server so its `ctx_*` tools survive
+  // `--strict-mcp-config` (which restricts Claude to this file and structurally
+  // excludes plugin-provided MCP servers). The plugin's hooks still fire via the
+  // installed Claude plugin — strict-mcp-config only suppresses MCP servers, not
+  // hooks. Placed BEFORE mergeMcpConfig so an API-installed server can still
+  // override it (unlikely, but safe). Gated by CONTEXT_MODE_DISABLED so builds
+  // and deploys without context-mode don't break.
+  //
+  // Server key uses the plugin naming convention (`plugin_context-mode_context-mode`)
+  // so that the resulting tool names (`mcp__plugin_context-mode_context-mode__ctx_*`)
+  // match the names the plugin's hooks reference in guidance text. With the bare
+  // key `context-mode`, the tools would be `mcp__context-mode__ctx_*` — callable,
+  // but invisible to the hook nudges that point agents at the plugin-prefixed name.
+  if (process.env.CONTEXT_MODE_DISABLED !== "true") {
+    mergedServers["plugin_context-mode_context-mode"] = { command: "context-mode" };
+  }
+
   try {
     const config = mergeMcpConfig({ mcpServers: mergedServers }, installedServers ?? null, taskId);
     const sessionConfigPath = `/tmp/mcp-${taskId}.json`;
@@ -399,6 +417,7 @@ class ClaudeSession implements ProviderSession {
         ...(sourceEnv.CLAUDE_CODE_OAUTH_TOKEN
           ? { AGENT_SWARM_CLAUDE_OAUTH_TOKEN: sourceEnv.CLAUDE_CODE_OAUTH_TOKEN }
           : {}),
+        CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY: CTX_MODE_NUDGE_EVERY,
       } as Record<string, string>,
       stdout: "pipe",
       stderr: "pipe",

package/src/providers/codex-adapter.ts

@@ -82,6 +82,7 @@ import { credentialsToAuthJson } from "./codex-oauth/auth-json.js";
 import { getValidCodexOAuth } from "./codex-oauth/storage.js";
 import { resolveCodexPrompt } from "./codex-skill-resolver";
 import { createCodexSwarmEventHandler } from "./codex-swarm-events";
+import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
 import { buildOtelTraceparentEnv } from "./otel-env";
 import type {
   CostData,
@@ -351,15 +352,34 @@ export async function buildCodexConfig(
     }
   }
 
+  // (4) context-mode — pre-installed stdio MCP server providing the `ctx_*`
+  // context-compression tools. Gated by `CONTEXT_MODE_DISABLED` so builds /
+  // deploys without the `context-mode` binary on PATH don't break the session.
+  // Same entry shape as the swarm + installed-server stdio entries above.
+  if (process.env.CONTEXT_MODE_DISABLED !== "true") {
+    mcpServers["context-mode"] = {
+      command: "context-mode",
+      enabled: true,
+      startup_timeout_sec: 30,
+      tool_timeout_sec: 120,
+    };
+  }
+
   // (1) Baseline overrides. Keep these aligned with the Dockerfile baseline
   // at `~/.codex/config.toml` (Phase 6). Repeating them here makes local dev
   // (no baseline file) behave identically to the Docker worker.
+  //
+  // `features.hooks` / `features.plugin_hooks` enable Codex's hook system and
+  // the hooks contributed by installed Codex plugins (context-mode's plugin:
+  // routing injection, PreToolUse safety blocks, output capture). The SDK
+  // flattens these to `--config features.hooks=true` / `features.plugin_hooks=true`.
   return {
     model,
     approval_policy: "never",
     sandbox_mode: "danger-full-access",
     skip_git_repo_check: true,
     show_raw_agent_reasoning: false,
+    features: { hooks: true, plugin_hooks: true },
     mcp_servers: mcpServers as CodexConfig,
   };
 }
@@ -1246,6 +1266,7 @@ export async function createInProcessCodexSession(
       ...(process.env.NODE_EXTRA_CA_CERTS
         ? { NODE_EXTRA_CA_CERTS: process.env.NODE_EXTRA_CA_CERTS }
         : {}),
+      CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY: CTX_MODE_NUDGE_EVERY,
       ...(config.env ?? {}),
       // Gated cross-service OTel linking: when SWARM_ENABLE_HARNESS_OTEL (or
       // the deprecated SWARM_ENABLE_CLAUDE_CODE_OTEL alias) is on, inject
@@ -1420,6 +1441,7 @@ class CodexSubprocessSession implements ProviderSession {
           ? { CODEX_PATH_OVERRIDE: process.env.CODEX_PATH_OVERRIDE }
           : {}),
         ...(process.env.CODEX_SKILLS_DIR ? { CODEX_SKILLS_DIR: process.env.CODEX_SKILLS_DIR } : {}),
+        CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY: CTX_MODE_NUDGE_EVERY,
         ...(process.env.SKIP_SESSION_SUMMARY
           ? { SKIP_SESSION_SUMMARY: process.env.SKIP_SESSION_SUMMARY }
           : {}),

package/src/providers/ctx-mode-env.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared context-mode plugin env config for harness subprocesses.
+ *
+ * The `context-mode` MCP plugin reads `CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY`
+ * to decide how often to surface its external-MCP guidance nudge (default 10).
+ * We lower it to 3 to increase adoption. All three adapters (claude, codex,
+ * opencode) inject this into the subprocess env.
+ */
+
+export const CTX_MODE_NUDGE_EVERY = process.env.CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY ?? "3";

package/src/providers/opencode-adapter.ts

@@ -20,6 +20,7 @@ import {
 import { validateOpencodeCredentials } from "../utils/credentials";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { scrubSecrets } from "../utils/secret-scrubber";
+import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
 import type {
   CostData,
   CredCheckOptions,
@@ -176,6 +177,32 @@ function resolvePluginPath(): string {
   return join(import.meta.dir, "../../plugin/opencode-plugins/agent-swarm.ts");
 }
 
+// context-mode is installed globally via `npm install -g` (Dockerfile.worker),
+// which places it under the npm global modules dir. opencode resolves bare
+// plugin names with `import(await Bun.resolve(name, ...))`, which does NOT walk
+// the npm global dir — a bare "context-mode" entry only resolves if Bun
+// auto-installs from the registry at runtime, which fails on network-sandboxed
+// workers. So we hand opencode the ABSOLUTE path to the package's built
+// opencode-plugin entry, which imports cleanly with no network.
+const CONTEXT_MODE_GLOBAL_ROOTS = ["/usr/lib/node_modules", "/usr/local/lib/node_modules"];
+const CONTEXT_MODE_PLUGIN_SUBPATH = "context-mode/build/adapters/opencode/plugin.js";
+
+/**
+ * Resolve the absolute path to context-mode's opencode plugin entry, or `null`
+ * if it can't be found on disk. `CONTEXT_MODE_OPENCODE_PLUGIN_PATH` overrides
+ * the lookup (and must itself exist). Returning `null` lets the caller skip the
+ * plugin gracefully instead of handing opencode an unresolvable entry.
+ */
+export function resolveContextModePluginPath(): string | null {
+  const override = process.env.CONTEXT_MODE_OPENCODE_PLUGIN_PATH;
+  if (override) return existsSync(override) ? override : null;
+  for (const root of CONTEXT_MODE_GLOBAL_ROOTS) {
+    const candidate = join(root, CONTEXT_MODE_PLUGIN_SUBPATH);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
 export class OpencodeSession implements ProviderSession {
   private _sessionId: string;
   private listeners: Array<(event: ProviderEvent) => void> = [];
@@ -588,6 +615,27 @@ export class OpencodeAdapter implements ProviderAdapter {
     // an accident, not a contract.
     const pluginPath = resolvePluginPath();
 
+    // context-mode ships as an in-process opencode plugin (NOT an MCP server).
+    // Its built plugin entry registers both the native ctx_* tools and the 5
+    // hook surrogates. It must NOT also appear in the `mcp` block — dual
+    // registration yields zero tools. We push the ABSOLUTE path to the globally
+    // installed package's opencode plugin entry, not the bare name (see
+    // resolveContextModePluginPath for why a bare name fails to resolve offline).
+    // Gated by CONTEXT_MODE_DISABLED so builds/deploys without it opt out.
+    const plugins = [pluginPath];
+    if (process.env.CONTEXT_MODE_DISABLED !== "true") {
+      const contextModePluginPath = resolveContextModePluginPath();
+      if (contextModePluginPath) {
+        plugins.push(contextModePluginPath);
+      } else {
+        console.warn(
+          "[opencode] context-mode is enabled but its opencode plugin entry was not found on disk; " +
+            "skipping it for this session. Set CONTEXT_MODE_OPENCODE_PLUGIN_PATH to override, or " +
+            "CONTEXT_MODE_DISABLED=true to silence.",
+        );
+      }
+    }
+
     // Build per-task opencode config (plugin field carries the swarm plugin)
     const opencodeConfig: Config & { plugin?: string[] } = {
       $schema: "https://opencode.ai/config.json",
@@ -600,7 +648,7 @@ export class OpencodeAdapter implements ProviderAdapter {
         doom_loop: "allow",
         external_directory: "allow",
       },
-      plugin: [pluginPath],
+      plugin: plugins,
     };
 
     // Write per-task config file
@@ -626,6 +674,7 @@ export class OpencodeAdapter implements ProviderAdapter {
     process.env.SWARM_AGENT_ID = config.agentId;
     process.env.SWARM_TASK_ID = config.taskId;
     process.env.SWARM_IS_LEAD = config.role === "lead" ? "true" : "false";
+    process.env.CONTEXT_MODE_EXTERNAL_MCP_NUDGE_EVERY = CTX_MODE_NUDGE_EVERY;
 
     // Set OPENCODE_CONFIG scoped to the spawn call (save + restore)
     const prevOpencodeConfig = process.env.OPENCODE_CONFIG;

package/src/slack/blocks.ts

@@ -5,7 +5,7 @@
  * across responses.ts, handlers.ts, thread-buffer.ts).
  */
 
-import type { TaskAttachment } from "../types";
+import type { AgentTaskStatus, TaskAttachment } from "../types";
 import { buildAgentFsLiveUrl, getAppUrl } from "../utils/constants";
 
 // Slack limits section text to 3000 chars; we use 2900 for safety
@@ -205,7 +205,7 @@ export function formatDuration(start: Date, end: Date): string {
 export interface TreeNode {
   taskId: string;
   agentName: string;
-  status: "pending" | "in_progress" | "completed" | "failed" | "cancelled";
+  status: AgentTaskStatus;
   progress?: string;
   duration?: string;
   slackReplySent?: boolean;
@@ -342,12 +342,20 @@ export function buildBufferFlushBlocks(opts: {
 
 // --- Tree rendering ---
 
-const STATUS_ICON: Record<TreeNode["status"], string> = {
+type TreeStatusIcon = TreeNode["status"] | "superseded";
+
+const STATUS_ICON: Record<TreeStatusIcon, string> = {
+  backlog: "🗂️",
+  unassigned: "📭",
+  offered: "📨",
+  reviewing: "👀",
   pending: "📡",
   in_progress: "⏳",
+  paused: "⏸️",
   completed: "✅",
   failed: "❌",
   cancelled: "🚫",
+  superseded: "↪️",
 };
 
 const MAX_VISIBLE_CHILDREN = 8;
@@ -368,7 +376,7 @@ function truncateOutput(text: string): string {
  * Render a single node line: icon + bold name + task link + optional duration.
  */
 function renderNodeLine(node: TreeNode): string {
-  const icon = STATUS_ICON[node.status];
+  const icon = STATUS_ICON[node.status] ?? "•";
   const taskLink = getTaskLink(node.taskId);
   let line = `${icon} *${node.agentName}* (${taskLink})`;
   if (node.duration) line += ` · ${node.duration}`;

package/src/slack/watcher.ts

@@ -144,7 +144,7 @@ export function buildTreeNodes(tree: TreeMessageState): TreeNode[] {
         childNodes.push({
           taskId: child.id,
           agentName: childAgentName,
-          status: child.status as TreeNode["status"],
+          status: child.status,
           progress: child.progress ?? undefined,
           duration: childDuration,
           slackReplySent: child.slackReplySent,
@@ -164,7 +164,7 @@ export function buildTreeNodes(tree: TreeMessageState): TreeNode[] {
     nodes.push({
       taskId: task.id,
       agentName,
-      status: task.status as TreeNode["status"],
+      status: task.status,
       progress: task.progress ?? undefined,
       duration,
       slackReplySent: task.slackReplySent,
@@ -382,7 +382,7 @@ async function postInitialDMTreeMessage(task: AgentTask): Promise<string | undef
   const initialNode: TreeNode = {
     taskId: task.id,
     agentName: agent.name,
-    status: task.status as TreeNode["status"],
+    status: task.status,
     progress: task.progress ?? undefined,
     children: [],
   };

package/src/telemetry.ts

@@ -15,6 +15,7 @@ const TIMEOUT_MS = 5_000;
 let installationId: string | null = null;
 let source = "unknown";
 let cachedIsCloud = false;
+let cachedIsE2b = false;
 
 function isEnabled(): boolean {
   return process.env.ANONYMIZED_TELEMETRY !== "false";
@@ -41,6 +42,15 @@ function isCloudHostname(hostname: string): boolean {
   return CLOUD_HOST_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
 }
 
+/**
+ * Detect whether the current process is running inside an E2B sandbox.
+ * E2B automatically exposes `E2B_SANDBOX_ID` inside every sandbox.
+ * Exported for tests; not part of the public API.
+ */
+export function _isE2bSandbox(): boolean {
+  return typeof process.env.E2B_SANDBOX_ID === "string" && process.env.E2B_SANDBOX_ID.length > 0;
+}
+
 /**
  * Parse `MCP_BASE_URL` (or any candidate URL) into the cloud flag we ship on
  * every telemetry event. URL parsing — not substring match — so we never
@@ -100,7 +110,8 @@ export async function initTelemetry(
 
   const resolved = _resolveCloudMode(process.env.MCP_BASE_URL);
   cachedIsCloud = resolved.isCloud;
-  console.log(`telemetry: cloud=${cachedIsCloud}`);
+  cachedIsE2b = _isE2bSandbox();
+  console.log(`telemetry: cloud=${cachedIsCloud} e2b=${cachedIsE2b}`);
 
   try {
     const existing = await getConfig("telemetry_installation_id");
@@ -183,6 +194,7 @@ export function track(options: TrackOptions): void {
         // The hostname is intentionally NOT included — telemetry must stay
         // anonymous, and the boolean is sufficient to split cloud vs self-host.
         is_cloud: cachedIsCloud,
+        is_e2b: cachedIsE2b,
       },
       metadata: {
         transport: "https",
@@ -212,6 +224,7 @@ export function _resetTelemetryStateForTests(): void {
   installationId = null;
   source = "unknown";
   cachedIsCloud = false;
+  cachedIsE2b = false;
 }
 
 /** Test-only: read the resolved install ID. */

package/src/templates.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/tests/base-prompt.test.ts

@@ -605,6 +605,47 @@ describe("getBasePrompt — local providers unaffected", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Context-mode block — provider gating
+//
+// The context_mode block advertises the `ctx_*` MCP tools. It is included for
+// local providers that have context-mode wired into their per-session config
+// (claude, codex, opencode) and excluded for `pi`, which has no context-mode
+// wiring yet (deferred to DES-514). Remote-provider exclusion is covered by the
+// "remote provider excluded sections" suite above.
+// ---------------------------------------------------------------------------
+const localTraits: ProviderTraits = { hasMcp: true, hasLocalEnvironment: true };
+
+describe("getBasePrompt — context-mode provider gating", () => {
+  test("excludes context-mode block for pi provider", async () => {
+    const result = await getBasePrompt({
+      ...minimalArgs,
+      traits: localTraits,
+      provider: "pi",
+    });
+    expect(result).not.toContain("Context Window Management");
+    expect(result).not.toContain("context-mode");
+  });
+
+  for (const provider of ["claude", "codex", "opencode"] as const) {
+    test(`includes context-mode block for ${provider} provider`, async () => {
+      const result = await getBasePrompt({
+        ...minimalArgs,
+        traits: localTraits,
+        provider,
+      });
+      expect(result).toContain("Context Window Management");
+      expect(result).toContain("context-mode");
+    });
+  }
+
+  test("includes context-mode block when provider is unspecified (local default)", async () => {
+    const result = await getBasePrompt({ ...minimalArgs, traits: localTraits });
+    expect(result).toContain("Context Window Management");
+    expect(result).toContain("context-mode");
+  });
+});
+
 describe("getBasePrompt — conditional Slack templates", () => {
   test("omits Slack tool templates when Slack is disabled", async () => {
     disableSlackPromptTools();