@desplega.ai/agent-swarm 1.84.0 → 1.84.1

package/README.md

@@ -2,12 +2,10 @@
   <a href="https://github.com/desplega-ai/agent-swarm/stargazers"><img src="https://img.shields.io/github/stars/desplega-ai/agent-swarm?style=flat-square&color=yellow" alt="GitHub Stars"></a>
   <a href="https://github.com/desplega-ai/agent-swarm/blob/main/LICENSE"><img src="https://img.shields.io/github/license/desplega-ai/agent-swarm?style=flat-square" alt="MIT License"></a>
   <a href="https://github.com/desplega-ai/agent-swarm/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome"></a>
-  <a href="https://discord.gg/KZgfyyDVZa"><img src="https://img.shields.io/badge/Discord-Join%20us-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
-  <a href="https://docs.agent-swarm.dev"><img src="https://img.shields.io/badge/docs-agent--swarm.dev-blue?style=flat-square" alt="Docs"></a>
 </p>
 
 <p align="center">
-  <b>Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants.</b><br/>
+  <b>An engine to make your company AI Native</b><br/>
   <sub>Built by <a href="https://desplega.sh">desplega.sh</a> — by builders, for builders.</sub>
 </p>
 
@@ -39,11 +37,19 @@
   </a>
 </p>
 
-> **What if your AI agents remembered everything, learned from every mistake, and got better with every task?**
+> **Agent Swarm is your Company's Compounding Intelligence Layer. A system of AI agents that remember, reason, act and get better with every task.**
+
+> AI-Native · Compounds · Presence · Harness & LLM-Agnostic · Your Infra · Your Memory · 
 
 ## What it does
 
-Agent Swarm runs a team of AI coding agents that coordinate autonomously. A **lead agent** receives tasks — from Slack, GitHub, GitLab, email, or the API — breaks them down, and delegates to **worker agents** running in Docker containers. Workers execute tasks, ship code, and write their learnings back to a shared memory so the whole swarm gets smarter every session.
+Agent Swarm runs a team of AI agents that coordinate autonomously. A **lead agent** receives tasks ( from Slack, GitHub, GitLab, Linear, Jira, email, or the API) breaks them down, and delegates to **worker agents** running in isolated environments (Docker). Workers execute tasks, ship solutions, and write their learnings back to a shared memory so the whole swarm gets smarter every session.
+
+You can run agents for Marketing, Product, UX, Engineering, Support, Operations, HR, Finance, or any role you can think of. A centralized Lead coordinates them, and they share the learnings horizontally. That's the true difference between [*AI First*](https://www.pleasedontdeploy.com/i/197193364/ai-first) and [*AI Native*](https://www.pleasedontdeploy.com/i/197193364/third-the-ai-native-metamorphosis).
+
+Agent Swarm is the shared cloud brain and muscle that makes your whole company better every day.
+
+Sometimes humans are the blocker. We can help you. Contact us [contact@desplega.sh](mailto:contact@desplega.sh).
 
 Learn more in the [architecture overview](https://docs.agent-swarm.dev/docs/architecture/overview).
 
@@ -85,14 +91,39 @@ flowchart LR
     WORKERS --> OUT
 ```
 
+## Known Use Cases
+
+Use cases that are used daily by ourselves and others.
+Each playbook contains: the agents, the tools & skills, and workflows & schedules behind it. **[Browse all playbooks →](https://docs.agent-swarm.dev/docs/playbooks)**
+
+- **[Feature Development](https://docs.agent-swarm.dev/docs/playbooks/feature-development)** — Integrated with Linear and GitHub to take feature requests from Slack and turn them into pull requests.
+- **[Lead Prospecting](https://docs.agent-swarm.dev/docs/playbooks/lead-prospecting)** — Integrate your prospecting tools with the swarm and let agents handle outreach, scheduling, and follow-up.
+- **[Content Generation](https://docs.agent-swarm.dev/docs/playbooks/content-generation)** — Generate engagement tools, blog posts, manage social media presence, update your website, and more.
+- **[UX Command Center](https://docs.agent-swarm.dev/docs/playbooks/ux-command-center)** — Agents that keep your product usable: record agentic sessions, enforce your design system, and mine user logs to detect and propose UX improvements.
+- **[Proactive Customer Support](https://docs.agent-swarm.dev/docs/playbooks/proactive-customer-support)** — Agents that oversee your top accounts, prepare scheduled reports, and leverage everything they know about your platform to keep those accounts up to date.
+- **[Code Health & Alert Management](https://docs.agent-swarm.dev/docs/playbooks/code-health-alert-management)** — Datadog, New Relic, Sentry, or any alerting tool can kick off fixes or new proposals. Monitor code health and propose improvements weekly, daily, or hourly.
+- **[Reports from Multiple Sources](https://docs.agent-swarm.dev/docs/playbooks/reports-multiple-sources)** — Integrate your data warehouse to generate tailored reports and answer the key questions your team has, with fresh data. Your BI tool may be a thing of the past.
+- **[Self-Documenting & Release Reports](https://docs.agent-swarm.dev/docs/playbooks/self-documenting-release-reports)** — Update your docs and use frameworks like [Remotion](https://www.remotion.dev/), [qa-use](https://github.com/qa-use/qa-use), and [browser-use](https://github.com/browser-use/browser-use) to generate release videos and rich documentation in seconds, at the cadence you need.
+- Do you have a cool playbook to share? Send us a PR!
+
+> **The patterns that compound.** Five recipes show up in nearly every playbook — they're how the swarm stays reliable as it scales:
+> **[Litmus Tests](https://docs.agent-swarm.dev/docs/playbooks/patterns/litmus-tests)** (LLM-as-judge quality gates) ·
+> **[Drain Loops](https://docs.agent-swarm.dev/docs/playbooks/patterns/drain-loops)** (one ticket → a chain of reviewable PRs) ·
+> **[HITL Gates](https://docs.agent-swarm.dev/docs/playbooks/patterns/hitl-gates)** (pause for human approval on irreversible steps) ·
+> **[Per-Customer Working Directories](https://docs.agent-swarm.dev/docs/playbooks/patterns/per-customer-working-directories)** (context that compounds per account) ·
+> **[No-op Workflows](https://docs.agent-swarm.dev/docs/playbooks/patterns/no-op-workflows)** (skip silently when nothing changed).
+> **[See all patterns →](https://docs.agent-swarm.dev/docs/playbooks/patterns)**
+
+Check [our templates](https://templates.agent-swarm.dev) for a quick start.
+
 ## Highlights
 
 - **Lead/worker orchestration in Docker** — isolated dev environments, priority queues, pause/resume across deploys. [Architecture →](https://docs.agent-swarm.dev/docs/architecture/overview)
 - **Compounding memory & persistent identity** — agents remember past sessions and evolve their own persona, expertise, and notes. [Memory →](https://docs.agent-swarm.dev/docs/architecture/memory) · [Agents →](https://docs.agent-swarm.dev/docs/architecture/agents)
-- **Multi-channel inputs** — Slack, GitHub, GitLab, email, Linear, Jira, and the HTTP API all create tasks. [Integrations](#integrations)
+- **Multi-channel inputs** — Slack, GitHub, GitLab, email, WhatsApp, Linear, Jira, and the HTTP API all create tasks. [Integrations](#integrations)
 - **Workflow engine with Human-in-the-Loop** — DAG-based automation with approval gates, retries, and structured I/O. [Workflows →](https://docs.agent-swarm.dev/docs/concepts/workflows)
 - **Scheduled & recurring tasks** — cron-based automation for standing work. [Scheduling →](https://docs.agent-swarm.dev/docs/concepts/scheduling)
-- **Multi-provider** — run with Claude Code, OpenAI Codex, pi-mono, Devin, Claude Managed Agents, or opencode. [Harness config →](https://docs.agent-swarm.dev/docs/guides/harness-configuration) · [Add a new provider →](https://docs.agent-swarm.dev/docs/guides/harness-providers)
+- **Harness & LLM agnostic** — run with Claude Code, OpenAI Codex, pi-mono, Devin, Claude Managed Agents, raw LLMs, or opencode. [Harness config →](https://docs.agent-swarm.dev/docs/guides/harness-configuration) · [Add a new provider →](https://docs.agent-swarm.dev/docs/guides/harness-providers)
 - **Skills & MCP servers** — reusable procedural knowledge and per-agent MCP servers with scope cascade. [MCP tools →](https://docs.agent-swarm.dev/docs/reference/mcp-tools)
 - **DB-backed pages** — agents publish HTML or JSON pages (reports, dashboards, action specs) via the `create_page` MCP tool with public / authed / password modes, version history, view counters, diff helpers, and PDF export. [MCP tools → Pages](https://docs.agent-swarm.dev/docs/reference/mcp-tools#pages-tools)
 - **KV store** — Redis-like namespaced key/value store with auto-scoped context (Slack thread / PR / Linear issue / page). [MCP tools → KV](https://docs.agent-swarm.dev/docs/reference/mcp-tools#kv-tools)
@@ -100,6 +131,8 @@ flowchart LR
 
 ## Quick Start
 
+Need help? Contact us at [contact@desplega.sh](mailto:contact@desplega.sh).
+
 **Prerequisites:** [Docker](https://docker.com) and a [Claude Code](https://docs.anthropic.com/en/docs/claude-code) OAuth token (`claude setup-token`).
 
 The fastest way is the onboarding wizard — it collects credentials, picks presets, and generates a working `docker-compose.yml`:
@@ -144,22 +177,26 @@ Worker  Worker  Worker
 2. The lead plans and delegates subtasks to workers.
 3. Workers execute in isolated Docker containers (git, Node.js, Python, etc.).
 4. Progress streams to the dashboard, Slack threads, or the API.
-5. Results ship back out as PRs, issue replies, or Slack messages.
+5. Results ship back out as PRs, custom pages, issue replies, or Slack messages.
 6. Session learnings are extracted and become memory for future tasks.
 
 More detail in the [task lifecycle docs](https://docs.agent-swarm.dev/docs/concepts/task-lifecycle).
 
 ## Integrations
 
+Missing one? Ask the swarm to build it.
+
 | Integration | What it does | Setup |
 |---|---|---|
 | **Slack** | DM or @mention the bot to create tasks; workers reply in threads | [Guide](https://docs.agent-swarm.dev/docs/guides/slack-integration) |
 | **GitHub App** | @mention or assign the bot on issues/PRs; CI failures create follow-up tasks | [Guide](https://docs.agent-swarm.dev/docs/guides/github-integration) |
 | **GitLab** | Same model as GitHub — webhooks on issues/MRs, `glab` preinstalled in workers | [Guide](https://docs.agent-swarm.dev/docs/guides/gitlab-integration) |
 | **AgentMail** | Give each agent an inbox; emails become tasks or lead messages | [Guide](https://docs.agent-swarm.dev/docs/guides/agentmail-integration) |
+| **Kapso (WhatsApp)** | Native inbound WhatsApp webhook routing; agents reply over WhatsApp with MCP tools or the `kapso-whatsapp` skill | [Guide](https://docs.agent-swarm.dev/docs/integrations/kapso) |
 | **Linear** | Bidirectional ticket sync via OAuth + webhooks | [Guide](https://docs.agent-swarm.dev/docs/guides/linear-integration) |
 | **Jira Cloud** | OAuth 3LO ticket sync — assignee/comment events create tasks; lifecycle posts comments back | [Guide](https://docs.agent-swarm.dev/docs/guides/jira-integration) |
 | **Sentry** | Workers can triage Sentry issues with the `/investigate-sentry-issue` command | [Guide](https://docs.agent-swarm.dev/docs/guides/sentry-integration) |
+| **Devin** | Devin can be a node in your swarm — keep your existing configuration | [Guide](https://docs.agent-swarm.dev/docs/guides/harness-configuration#supported-providers) |
 
 ## Dashboard
 
@@ -196,6 +233,7 @@ Everything lives at **[docs.agent-swarm.dev](https://docs.agent-swarm.dev)**. Go
 
 - [Getting Started](https://docs.agent-swarm.dev/docs/getting-started) — install, configure, and run your first task
 - [Architecture overview](https://docs.agent-swarm.dev/docs/architecture/overview) — how the swarm is wired together
+- [Playbooks](https://docs.agent-swarm.dev/docs/playbooks) — eight production flows we use to run Desplega, plus the patterns behind them
 - [CLI reference](https://docs.agent-swarm.dev/docs/reference/cli) and [Environment variables](https://docs.agent-swarm.dev/docs/reference/environment-variables)
 - [API reference](https://docs.agent-swarm.dev/docs/api-reference) — every HTTP endpoint
 
@@ -212,6 +250,8 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) to get started. The quickest way to con
 
 Join our [Discord](https://discord.gg/KZgfyyDVZa) if you have questions or want to discuss ideas.
 
+> Are you an agent? Go to [agent-swarm.dev/skill.md](https://www.agent-swarm.dev/skill.md).
+
 ## Star History
 
 <a href="https://star-history.com/#desplega-ai/agent-swarm&Date">

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.84.0",
+    "version": "1.84.1",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -10839,11 +10839,13 @@
                       "email": {
                         "type": "string",
                         "format": "email"
+                      },
+                      "notes": {
+                        "type": "string"
                       }
                     },
                     "required": [
-                      "name",
-                      "email"
+                      "name"
                     ]
                   }
                 ]

package/package.json

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

package/src/be/migrations/076_kapso_sender_user_backfill.sql

@@ -0,0 +1,43 @@
+-- Backfill Kapso/WhatsApp sender identities into the canonical user registry.
+--
+-- Native Kapso inbound messages resolve their sender through user_external_ids
+-- using kind='kapso' and the normalized WhatsApp phone number from
+-- message.from/conversation.phone_number. Existing user profiles can already
+-- carry WhatsApp numbers in notes in the documented form:
+--
+--   WhatsApp: +34 ... (E.164: 346...)
+--
+-- Link those existing, human-curated profile rows instead of leaving inbound
+-- Kapso sender rows unmapped. This is idempotent and preserves any existing
+-- mapping for a phone number.
+
+INSERT OR IGNORE INTO user_external_ids (kind, externalId, userId)
+WITH raw_notes AS (
+  SELECT
+    id AS userId,
+    substr(notes, instr(notes, 'E.164:') + length('E.164:')) AS e164_suffix
+  FROM users
+  WHERE notes LIKE '%WhatsApp:%'
+    AND notes LIKE '%E.164:%'
+),
+parsed AS (
+  SELECT
+    userId,
+    trim(
+      CASE
+        WHEN instr(e164_suffix, ')') > 0 THEN substr(e164_suffix, 1, instr(e164_suffix, ')') - 1)
+        ELSE e164_suffix
+      END
+    ) AS e164_value
+  FROM raw_notes
+),
+normalized AS (
+  SELECT
+    userId,
+    replace(replace(replace(replace(e164_value, '+', ''), ' ', ''), '-', ''), '.', '') AS externalId
+  FROM parsed
+)
+SELECT 'kapso', externalId, userId
+FROM normalized
+WHERE externalId <> ''
+  AND externalId NOT GLOB '*[^0-9]*';

package/src/commands/context-preamble.ts

@@ -0,0 +1,178 @@
+/**
+ * Universal context preamble for follow-up task continuity.
+ *
+ * Builds a bounded text summary of prior task context (parent → ancestor chain)
+ * and prepends it to the child task's prompt. This makes follow-up continuity
+ * uniform across ALL harness providers — not just those that support native
+ * session resume (claude/codex).
+ *
+ * Token budget (CONTEXT_PREAMBLE_MAX_TOKENS, default 2000) prevents the
+ * SIGTERM-143 context-saturation failure mode seen with unbounded session
+ * resumes (see swarm memory sigterm-143-resumed-session-context-saturation-2026-05-13).
+ */
+
+export const CONTEXT_PREAMBLE_MAX_TOKENS = Number(
+  process.env.CONTEXT_PREAMBLE_MAX_TOKENS || "2000",
+);
+// ~4 chars per token (conservative approximation for mixed code/prose)
+export const CONTEXT_PREAMBLE_MAX_CHARS = CONTEXT_PREAMBLE_MAX_TOKENS * 4;
+export const CONTEXT_PREAMBLE_MAX_ANCESTORS = 5;
+
+export interface TaskContextForPreamble {
+  id: string;
+  task: string;
+  output?: string;
+  progress?: string;
+  status?: string;
+  parentTaskId?: string;
+  attachments?: Array<{
+    kind: string;
+    name: string;
+    url?: string;
+    path?: string;
+    pageId?: string;
+    orgId?: string;
+    driveId?: string;
+    description?: string;
+    intent?: string;
+    isPrimary?: boolean;
+  }>;
+}
+
+/** Fetch minimal task context for preamble generation (worker-side, via HTTP). */
+export async function fetchTaskContextForPreamble(
+  apiUrl: string,
+  apiKey: string,
+  taskId: string,
+): Promise<TaskContextForPreamble | null> {
+  const headers: Record<string, string> = {};
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  try {
+    const response = await fetch(`${apiUrl}/api/tasks/${taskId}`, { headers });
+    if (!response.ok) return null;
+    const data = (await response.json()) as TaskContextForPreamble;
+    return {
+      id: data.id,
+      task: data.task,
+      output: data.output,
+      progress: data.progress,
+      status: data.status,
+      parentTaskId: data.parentTaskId,
+      attachments: data.attachments,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function formatAttachmentPointer(
+  att: NonNullable<TaskContextForPreamble["attachments"]>[number],
+): string {
+  if (att.kind === "agent-fs" && att.path) {
+    const liveHost = process.env.AGENT_FS_LIVE_URL ?? "https://live.agent-fs.dev";
+    if (att.orgId && att.driveId) {
+      return `${liveHost}/file/~/${att.orgId}/${att.driveId}/${att.path}`;
+    }
+    return att.path;
+  }
+  if (att.kind === "url" && att.url) return att.url;
+  if (att.kind === "page" && att.pageId) return `(page:${att.pageId})`;
+  if (att.kind === "shared-fs" && att.path) return att.path;
+  return "(no pointer)";
+}
+
+/**
+ * Build a bounded context preamble for a follow-up task.
+ *
+ * Walks the ancestor chain (up to CONTEXT_PREAMBLE_MAX_ANCESTORS) via the API
+ * and returns a formatted markdown block that is prepended to the child prompt.
+ *
+ * - Immediate parent: inline detail (subject + output + attachments)
+ * - Older ancestors: pointer-only (taskId + one-line subject)
+ *
+ * Hard-capped at CONTEXT_PREAMBLE_MAX_CHARS (~CONTEXT_PREAMBLE_MAX_TOKENS
+ * tokens) to prevent context saturation.
+ */
+export async function buildContextPreamble(
+  apiUrl: string,
+  apiKey: string,
+  parentTaskId: string,
+): Promise<string | null> {
+  const ancestors: TaskContextForPreamble[] = [];
+  let currentId: string | undefined = parentTaskId;
+  while (currentId && ancestors.length < CONTEXT_PREAMBLE_MAX_ANCESTORS) {
+    const ctx = await fetchTaskContextForPreamble(apiUrl, apiKey, currentId);
+    if (!ctx) break;
+    ancestors.push(ctx);
+    currentId = ctx.parentTaskId;
+  }
+  if (ancestors.length === 0) return null;
+  // ancestors[0] is guaranteed by the length check above; TypeScript needs the guard.
+  const parent = ancestors[0];
+  if (!parent) return null;
+
+  const lines: string[] = [
+    "\n---",
+    "## Prior Conversation Context",
+    "",
+    "This task is a follow-up in an ongoing thread. Here is a summary of prior work to maintain continuity.",
+    "",
+  ];
+
+  const subjectPreview = parent.task.slice(0, 600).replace(/\n/g, " ");
+  lines.push(`### Immediate Prior Task (ID: \`${parent.id}\`)`);
+  lines.push(`**Task:** ${subjectPreview}`);
+  lines.push("");
+
+  const rawResult = parent.output || parent.progress;
+  if (rawResult) {
+    // Reserve ~55% of budget for the output content; rest for structure + older ancestors
+    const outputBudget = Math.floor(CONTEXT_PREAMBLE_MAX_CHARS * 0.55);
+    const truncated =
+      rawResult.length > outputBudget
+        ? `${rawResult.slice(0, outputBudget)}\n\n[output truncated — full history via \`get-task-details\` with taskId \`${parent.id}\`]`
+        : rawResult;
+    lines.push("**Outcome:**");
+    lines.push(truncated);
+    lines.push("");
+  } else {
+    lines.push("**Outcome:** (no output recorded yet — task may still be in progress)");
+    lines.push("");
+  }
+
+  const atts = parent.attachments?.filter((a) => a.name && (a.url || a.path || a.pageId));
+  if (atts && atts.length > 0) {
+    lines.push("**Artifacts from prior task:**");
+    for (const att of atts.slice(0, 10)) {
+      const pointer = formatAttachmentPointer(att);
+      const note = att.description || att.intent || "";
+      lines.push(`  - **${att.name}**: \`${pointer}\`${note ? ` — ${note}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    `To review the full prior conversation call \`get-task-details\` with taskId \`${parent.id}\`.`,
+  );
+
+  if (ancestors.length > 1) {
+    lines.push("");
+    lines.push(
+      "### Older Ancestor Tasks (pointers only — call `get-task-details` for full details)",
+    );
+    for (const ancestor of ancestors.slice(1)) {
+      const brief = ancestor.task.slice(0, 200).replace(/\n/g, " ");
+      lines.push(`- \`${ancestor.id}\` — ${brief}`);
+    }
+  }
+
+  lines.push("", "---", "");
+
+  let preamble = lines.join("\n");
+
+  if (preamble.length > CONTEXT_PREAMBLE_MAX_CHARS) {
+    preamble = `${preamble.slice(0, CONTEXT_PREAMBLE_MAX_CHARS)}\n\n[context preamble truncated to ${CONTEXT_PREAMBLE_MAX_TOKENS}-token budget]\n\n---\n`;
+  }
+
+  return preamble;
+}

package/src/commands/runner.ts

@@ -49,6 +49,7 @@ import { scrubSecrets } from "../utils/secret-scrubber.ts";
 import { refreshSkillsIfChanged } from "../utils/skills-refresh.ts";
 import { detectVcsProvider } from "../vcs/index.ts";
 import { interpolate } from "../workflows/template.ts";
+import { buildContextPreamble } from "./context-preamble.ts";
 import { awaitCredentials, BootMaxWaitExceededError, EX_CONFIG } from "./credential-wait.ts";
 import {
   buildCredStatusReport,
@@ -3752,6 +3753,19 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           console.log(`[${role}] Injected relevant memories into resumed task prompt`);
         }
 
+        // Universal context preamble: inject for all providers when task is a follow-up.
+        // Gives non-resumable providers (opencode/pi/devin) prior-task context; also
+        // acts as a bounded safety net for resumable ones (claude/codex).
+        if (task.parentTaskId && apiUrl) {
+          const contextPreamble = await buildContextPreamble(apiUrl, apiKey, task.parentTaskId);
+          if (contextPreamble) {
+            resumePrompt = contextPreamble + resumePrompt;
+            console.log(
+              `[${role}] Injected context preamble into resumed follow-up task prompt (parent: ${task.parentTaskId.slice(0, 8)})`,
+            );
+          }
+        }
+
         // Resolve provider-aware resume: prefer own session, then parent.
         const resumeCandidates: ResumeSessionCandidate[] = [
           {
@@ -4107,9 +4121,22 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
           }
         }
 
+        // Universal context preamble: inject for all providers when task is a follow-up.
+        // Gives non-resumable providers (opencode/pi/devin) prior-task context; also
+        // acts as a bounded safety net for resumable ones (claude/codex).
+        const taskObj = trigger.task as { parentTaskId?: string } | undefined;
+        if (taskObj?.parentTaskId && apiUrl) {
+          const contextPreamble = await buildContextPreamble(apiUrl, apiKey, taskObj.parentTaskId);
+          if (contextPreamble) {
+            triggerPrompt = contextPreamble + triggerPrompt;
+            console.log(
+              `[${role}] Injected context preamble for follow-up task (parent: ${taskObj.parentTaskId.slice(0, 8)})`,
+            );
+          }
+        }
+
         // Resolve provider-aware resume for child tasks with parentTaskId.
         let resumeSessionId: string | undefined;
-        const taskObj = trigger.task as { parentTaskId?: string } | undefined;
         if (taskObj?.parentTaskId) {
           const parentSession = await fetchProviderSessionInfo(
             apiUrl,

package/src/http/users.ts

@@ -151,7 +151,11 @@ const resolveUnmapped = route({
   params: z.object({ kind: z.string(), externalId: z.string() }),
   body: z.union([
     z.object({ userId: z.string().min(1) }),
-    z.object({ name: z.string().min(1), email: z.string().email() }),
+    z.object({
+      name: z.string().min(1),
+      email: z.string().email().optional(),
+      notes: z.string().optional(),
+    }),
   ]),
   responses: {
     200: { description: "Identity linked + kv entries cleared" },
@@ -322,7 +326,7 @@ const deleteIdentityRoute = route({
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-const UNMAPPED_KINDS = ["slack", "github", "gitlab", "linear"] as const;
+const UNMAPPED_KINDS = ["slack", "github", "gitlab", "linear", "kapso"] as const;
 
 /**
  * Group the two-key-per-identity kv entries (`<externalId>:meta` json +
@@ -477,7 +481,11 @@ export async function handleUsers(
         }
         targetUserId = existing.id;
       } else {
-        const created = createUser({ name: parsed.body.name, email: parsed.body.email });
+        const created = createUser({
+          name: parsed.body.name,
+          email: parsed.body.email,
+          notes: parsed.body.notes,
+        });
         targetUserId = created.id;
       }
       linkIdentity(targetUserId, kind, externalId, actor);

package/src/integrations/kapso/inbound.ts

@@ -2,8 +2,13 @@ import { resolveTemplate } from "@/prompts/resolver";
 import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import { workflowEventBus } from "@/workflows/event-bus";
 import "@/tools/templates";
+import { recordUnmappedIdentity } from "@/be/unmapped-identities";
+import { findUserByExternalId } from "@/be/users";
 import { getKapsoNumberMapping, markKapsoMessageSeen } from "./config";
 
+const KAPSO_IDENTITY_KIND = "kapso";
+const WHATSAPP_IDENTITY_KIND = "whatsapp";
+
 /** Minimal shape of the Kapso v2 inbound webhook payload (see the kapso-whatsapp skill). */
 export interface KapsoWebhookPayload {
   message?: {
@@ -50,6 +55,36 @@ function buildTaskDescription(payload: KapsoWebhookPayload): string {
   }).text;
 }
 
+function normalizeKapsoSender(payload: KapsoWebhookPayload): string | null {
+  const raw = payload.message?.from ?? payload.conversation?.phone_number ?? "";
+  const digits = raw.replace(/\D/g, "");
+  return digits || null;
+}
+
+function resolveKapsoRequestedByUserId(payload: KapsoWebhookPayload): string | undefined {
+  const externalId = normalizeKapsoSender(payload);
+  if (!externalId) return undefined;
+
+  const mapped =
+    findUserByExternalId(KAPSO_IDENTITY_KIND, externalId) ??
+    findUserByExternalId(WHATSAPP_IDENTITY_KIND, externalId);
+  if (mapped) return mapped.id;
+
+  recordUnmappedIdentity(KAPSO_IDENTITY_KIND, externalId, {
+    sampleEventType: "kapso.message.received",
+    sampleContext: [
+      payload.conversation?.contact_name ? `contact=${payload.conversation.contact_name}` : null,
+      payload.conversation?.id ? `conversation=${payload.conversation.id}` : null,
+      payload.message?.id ? `message=${payload.message.id}` : null,
+      payload.phone_number_id ? `phone_number_id=${payload.phone_number_id}` : null,
+    ]
+      .filter(Boolean)
+      .join(" "),
+  });
+
+  return undefined;
+}
+
 /**
  * Route one inbound Kapso webhook delivery. Pure of HTTP concerns — the caller
  * handles HMAC verification and the workflow-trigger dispatch (which needs the
@@ -104,6 +139,7 @@ export function routeKapsoInbound(payload: KapsoWebhookPayload): KapsoRouting {
     taskType: "kapso-inbound",
     tags: ["kapso-whatsapp", "inbound"],
     priority: 70,
+    requestedByUserId: resolveKapsoRequestedByUserId(payload),
     contextKey: `kapso:conversation:${payload.conversation?.id ?? messageId}`,
   });
 

package/src/prompts/base-prompt.ts

@@ -23,6 +23,13 @@ const BOOTSTRAP_TOTAL_MAX_CHARS = 150_000;
 const truncationNotice = (file: string) =>
   `\n\n[...truncated, see /workspace/${file} for full content]\n`;
 
+export function areSlackPromptToolsEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const slackDisable = env.SLACK_DISABLE;
+  if (slackDisable === "true" || slackDisable === "1") return false;
+
+  return Boolean(env.SLACK_BOT_TOKEN && env.SLACK_APP_TOKEN);
+}
+
 export type BasePromptArgs = {
   role: string;
   agentId: string;
@@ -71,9 +78,15 @@ export const getBasePrompt = async (args: BasePromptArgs): Promise<string> => {
   const compositeResult = await resolveTemplateAsync(compositeEventType, vars);
   let prompt = compositeResult.text;
 
+  const slackPromptToolsEnabled = areSlackPromptToolsEnabled();
+
+  if (hasMcp && slackPromptToolsEnabled) {
+    const slackResult = await resolveTemplateAsync("system.agent.slack", {});
+    prompt += slackResult.text;
+  }
+
   // Conditionally inject Slack instructions for workers with Slack-originated tasks
-  // Skip for providers without MCP — they can't call Slack tools (slack-reply, etc.)
-  if (role !== "lead" && args.slackContext && hasMcp) {
+  if (role !== "lead" && args.slackContext && hasMcp && slackPromptToolsEnabled) {
     const slackResult = await resolveTemplateAsync("system.agent.worker.slack", {
       slackChannelId: args.slackContext.channelId,
       slackThreadTs: args.slackContext.threadTs ?? "",

package/src/prompts/session-templates.ts

@@ -59,16 +59,11 @@ As the lead agent, you coordinate all worker agents in the swarm.
 - \`send-task\`: Assign a task to a specific worker or to the general pool. Slack/AgentMail metadata auto-inherits from parent task.
 - \`store-progress\`: Track coordination notes or update task status
 
-**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
-
-**Slack:**
-- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
-- \`slack-read\`: Read thread/channel history (use taskId or channelId)
-- \`slack-list-channels\`: Discover available Slack channels
+**User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`), use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the task metadata attached to the task.
 
 **Identity:**
 - \`update-profile\`: Update your own or other agents' profile fields (name, role, capabilities, soulMd, identityMd, heartbeatMd, claudeMd, toolsMd, setupScript)
-- \`manage-user\`: Register or update human users (resolve from Slack/GitHub/GitLab identity)
+- \`manage-user\`: Register or update human users (resolve from GitHub/GitLab identity or other source metadata)
 
 #### Task Routing
 
@@ -85,16 +80,14 @@ When composing task descriptions: include the repo URL (if applicable), specific
 For follow-up tasks that should continue from previous work, pass \`parentTaskId\` with the previous task's ID:
 - Worker resumes the parent's Claude session (full conversation context preserved)
 - Child task is auto-routed to the same worker (session data is local)
-- Slack metadata (channelId, threadTs, userId) auto-inherits
 
 If you explicitly assign to a different worker, session resume gracefully falls back to a fresh session.
 
-#### Follow-Up Tasks & Slack
+#### Follow-Up Tasks
 
 When a worker completes or fails a task, you receive an automatic follow-up task. Handle it by:
 1. Review the output/failure reason
-2. If the task has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread
-3. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
+2. Complete this task. Do NOT re-delegate or create new worker tasks from a follow-up \u2014 the worker's result IS the answer. Only escalate to the stakeholder if the worker explicitly failed and the failure needs human attention.
 
 #### Heartbeat Checklist
 
@@ -106,7 +99,6 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
 
 **Example standing orders:**
 \`\`\`markdown
-- Check Slack for unaddressed requests older than 1 hour
 - Review active tasks for any that seem stuck or need follow-up
 - If idle workers exist and unassigned tasks are available, investigate why
 \`\`\`
@@ -122,6 +114,28 @@ The system reads your \`/workspace/HEARTBEAT.md\` every 30 minutes. If it has co
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.slack",
+  header: "",
+  defaultBody: `
+#### Slack Tools
+
+- \`slack-reply\`: Reply to user in the Slack thread (use taskId for context)
+- \`slack-read\`: Read thread/channel history (use taskId or channelId)
+- \`slack-list-channels\`: Discover available Slack channels
+
+**Slack User Registration:** When a task arrives from an unknown user (no \`requestedByUserId\`) with Slack metadata, use the \`manage-user\` tool to register them before proceeding. Resolve their identity from the Slack metadata (user ID, display name) attached to the task.
+
+**Slack context inheritance:** For follow-up tasks using \`parentTaskId\`, Slack metadata (channelId, threadTs, userId) auto-inherits.
+
+**Slack follow-up tasks:** When a worker completes or fails a task that has Slack metadata, use \`slack-reply\` with the task's ID to post the result back to the originating thread before completing the follow-up task.
+
+**Slack standing orders:** If you maintain heartbeat standing orders, check Slack for unaddressed requests older than 1 hour when appropriate.
+`,
+  variables: [],
+  category: "system",
+});
+
 registerTemplate({
   eventType: "system.agent.worker",
   header: "",