@desplega.ai/agent-swarm 1.87.0 → 1.89.0

package/src/http/webhooks.ts

@@ -41,7 +41,14 @@ import {
   isGitLabEnabled,
   verifyGitLabWebhook,
 } from "../gitlab";
+import {
+  type KapsoMessageActionResult,
+  markKapsoMessageRead,
+  sendKapsoReaction,
+} from "../integrations/kapso/client";
+import type { KapsoConfig } from "../integrations/kapso/config";
 import { getKapsoConfig } from "../integrations/kapso/config";
+import type { KapsoWebhookPayload } from "../integrations/kapso/inbound";
 import { routeKapsoInbound } from "../integrations/kapso/inbound";
 import { getExecutorRegistry } from "../workflows";
 import { workflowEventBus } from "../workflows/event-bus";
@@ -108,6 +115,72 @@ const kapsoWebhook = route({
 
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
+function logKapsoAckResult(action: string, result: KapsoMessageActionResult): void {
+  if (result.ok) return;
+  console.warn(
+    `[Kapso] Inbound acknowledgement ${action} failed: ${
+      result.errorMessage ?? `status ${result.status}`
+    }`,
+  );
+}
+
+async function acknowledgeKapsoInboundMessage(
+  payload: KapsoWebhookPayload,
+  config: KapsoConfig,
+): Promise<void> {
+  const message = payload.message;
+  const phoneNumberId = payload.phone_number_id;
+  const messageId = message?.id;
+  const to = message?.from ?? payload.conversation?.phone_number;
+
+  if (payload.test || message?.kapso?.direction !== "inbound" || !phoneNumberId || !messageId) {
+    return;
+  }
+
+  if (!config.apiKey) {
+    console.warn("[Kapso] Cannot acknowledge inbound message: KAPSO_API_KEY is not configured");
+    return;
+  }
+
+  const markRead = markKapsoMessageRead({
+    apiBaseUrl: config.apiBaseUrl,
+    apiKey: config.apiKey,
+    phoneNumberId,
+    messageId,
+    typingIndicatorType: "text",
+  });
+  const react =
+    to && to.length > 0
+      ? sendKapsoReaction({
+          apiBaseUrl: config.apiBaseUrl,
+          apiKey: config.apiKey,
+          phoneNumberId,
+          to,
+          messageId,
+          emoji: "👀",
+        })
+      : Promise.resolve<KapsoMessageActionResult>({
+          ok: false,
+          status: 0,
+          raw: null,
+          errorMessage: "missing sender phone",
+        });
+
+  const [readResult, reactionResult] = await Promise.allSettled([markRead, react]);
+  if (readResult.status === "fulfilled") {
+    logKapsoAckResult("mark-as-read/typing", readResult.value);
+  } else {
+    console.warn(
+      `[Kapso] Inbound acknowledgement mark-as-read/typing failed: ${readResult.reason}`,
+    );
+  }
+  if (reactionResult.status === "fulfilled") {
+    logKapsoAckResult("reaction", reactionResult.value);
+  } else {
+    console.warn(`[Kapso] Inbound acknowledgement reaction failed: ${reactionResult.reason}`);
+  }
+}
+
 export async function handleWebhooks(
   req: IncomingMessage,
   res: ServerResponse,
@@ -494,6 +567,8 @@ export async function handleWebhooks(
       return true;
     }
 
+    void acknowledgeKapsoInboundMessage(payload, config);
+
     try {
       const routing = routeKapsoInbound(payload);
       switch (routing.kind) {

package/src/http/workflows.ts

@@ -21,6 +21,7 @@ import {
   WorkflowPatchSchema,
   WorkflowRunStatusSchema,
 } from "../types";
+import { getRequestAuth } from "../utils/request-auth-context";
 import { getExecutorRegistry, startWorkflowExecution } from "../workflows";
 import { applyDefinitionPatch, generateEdges, validateDefinition } from "../workflows/definition";
 import { TriggerSchemaError } from "../workflows/engine";
@@ -645,10 +646,13 @@ export async function handleWorkflows(
       return true;
     }
     const body = await parseBody<Record<string, unknown>>(req);
+    const auth = getRequestAuth(req);
 
     let runId: string;
     try {
-      runId = await startWorkflowExecution(workflow, body, getExecutorRegistry());
+      runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
+        requestedByUserId: auth?.kind === "user" ? auth.userId : undefined,
+      });
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
         triggerSchemaErrorResponse(res, err.message, err.validationErrors);

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/metrics/version.ts

@@ -0,0 +1,26 @@
+import { createMetricVersion, getMetric, getMetricVersions } from "../be/db";
+import type { MetricSnapshot, MetricVersion } from "../types";
+
+export function snapshotMetric(metricId: string, changedByAgentId?: string): MetricVersion {
+  const metric = getMetric(metricId);
+  if (!metric) {
+    throw new Error(`Metric ${metricId} not found — cannot create snapshot`);
+  }
+
+  const existingVersions = getMetricVersions(metricId);
+  const maxVersion = existingVersions.length > 0 ? existingVersions[0]!.version : 0;
+  const nextVersion = maxVersion + 1;
+
+  const snapshot: MetricSnapshot = {
+    title: metric.title,
+    description: metric.description,
+    definition: metric.definition,
+  };
+
+  return createMetricVersion({
+    metricId,
+    version: nextVersion,
+    snapshot,
+    changedByAgentId,
+  });
+}

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;
@@ -65,6 +72,7 @@ export type BasePromptArgs = {
     claudeMd?: string | null;
     clonePath: string;
     warning?: string | null;
+    autoStashes?: { ref: string; message: string }[];
     guidelines?: {
       prChecks: string[];
       mergeChecks: string[];
@@ -91,8 +99,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;
@@ -182,6 +198,13 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
       } else if (!args.repoContext.warning) {
         prompt += `Repository is cloned at \`${args.repoContext.clonePath}\` but has no CLAUDE.md file.\n`;
       }
+
+      if (args.repoContext.autoStashes && args.repoContext.autoStashes.length > 0) {
+        const stashes = args.repoContext.autoStashes
+          .map((stash) => `- ${stash.ref}: ${stash.message}`)
+          .join("\n");
+        prompt += `\nPending auto-stashed work exists in this repo:\n${stashes}\nRestore if relevant with \`git stash apply <ref>\` or \`git stash pop <ref>\`.\n`;
+      }
     }
 
     // Inject repo guidelines

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",
@@ -540,6 +565,29 @@ When working in a repository, your system prompt may include a **Repository Guid
   category: "system",
 });
 
+// ============================================================================
+// Per-task prompt templates (category: "task_lifecycle")
+// ============================================================================
+
+registerTemplate({
+  eventType: "task.requester.profile",
+  header: "",
+  defaultBody: `
+## Requester Profile
+This task was requested by {{requester_name}}{{requester_role_suffix}}.{{requester_notes_section}}
+Honor this requester profile in tone, depth, and format where it doesn't conflict with correctness or your operating rules.
+`,
+  variables: [
+    { name: "requester_name", description: "The requesting user's display name" },
+    { name: "requester_role_suffix", description: "Formatted role suffix, including parentheses" },
+    {
+      name: "requester_notes_section",
+      description: "Formatted notes section sourced from users.notes, or empty string",
+    },
+  ],
+  category: "task_lifecycle",
+});
+
 // ============================================================================
 // Composite session templates (category: "session")
 // ============================================================================
@@ -586,6 +634,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";