@desplega.ai/agent-swarm 1.87.0 → 1.88.0

package/src/commands/onboard/dashboard-url.ts

@@ -0,0 +1,29 @@
+/**
+ * Build the swarm-dashboard deep-link the SPA reads after a local onboard.
+ *
+ * IMPORTANT: the dashboard SPA reads **camelCase** `apiUrl` / `apiKey` query
+ * params (see ui/src/hooks/use-config.ts → extractUrlParams) and silently
+ * ignores snake_case. An earlier version of these builders emitted snake_case
+ * `api_url` / `api_key`, so the auto-connect deep-link never worked. Keep these
+ * camelCase.
+ */
+
+const DEFAULT_DASHBOARD_BASE = "https://app.agent-swarm.dev";
+
+export type DashboardUrlParts = {
+  apiUrl: string;
+  apiKey?: string;
+  /** Optional connection name shown in the dashboard (camelCase `name`). */
+  name?: string;
+  /** Override the dashboard base (defaults to the production app). */
+  base?: string;
+};
+
+export function buildOnboardDashboardUrl(parts: DashboardUrlParts): string {
+  const params = new URLSearchParams();
+  params.set("apiUrl", parts.apiUrl);
+  if (parts.apiKey) params.set("apiKey", parts.apiKey);
+  if (parts.name) params.set("name", parts.name);
+  const base = (parts.base ?? DEFAULT_DASHBOARD_BASE).replace(/\/+$/, "");
+  return `${base}?${params.toString()}`;
+}

package/src/commands/onboard/steps/post-dashboard.tsx

@@ -1,10 +1,12 @@
 import { Select } from "@inkjs/ui";
 import { Box, Text } from "ink";
+import { buildOnboardDashboardUrl } from "../dashboard-url.ts";
 import type { StepProps } from "../types.ts";
 
 export function PostDashboardStep({ state, addLog, goToNext }: StepProps) {
   const apiUrl = `http://localhost:${state.apiPort || 3013}`;
-  const dashboardUrl = `https://app.agent-swarm.dev?api_url=${apiUrl}&api_key=${state.apiKey}`;
+  // camelCase params — the SPA ignores snake_case (see dashboard-url.ts).
+  const dashboardUrl = buildOnboardDashboardUrl({ apiUrl, apiKey: state.apiKey });
 
   return (
     <Box flexDirection="column" padding={1}>

package/src/commands/onboard.tsx

@@ -4,6 +4,7 @@ import { Box, Text, useApp, useInput } from "ink";
 import { useCallback, useEffect, useRef, useState } from "react";
 import pkg from "../../package.json";
 import { getApiKey } from "../utils/api-key.ts";
+import { buildOnboardDashboardUrl } from "./onboard/dashboard-url.ts";
 import { getAgentSummary, getPresetById, PRESETS } from "./onboard/presets.ts";
 import { CoreCredentialsStep } from "./onboard/steps/core-credentials.tsx";
 import { CustomTemplatesStep } from "./onboard/steps/custom-templates.tsx";
@@ -244,7 +245,8 @@ export function Onboard({ dryRun = false, yes = false, preset }: OnboardProps) {
 
   if (state.step === "done") {
     const apiUrl = `http://localhost:${state.apiPort || 3013}`;
-    const dashUrl = `https://app.agent-swarm.dev?api_url=${apiUrl}&api_key=${state.apiKey}`;
+    // camelCase params — the SPA ignores snake_case (see dashboard-url.ts).
+    const dashUrl = buildOnboardDashboardUrl({ apiUrl, apiKey: state.apiKey });
     const agentCount = state.services.reduce((sum, s) => sum + s.count, 0);
 
     return (

package/src/commands/runner.ts

@@ -3295,6 +3295,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       swarmUrl,
       capabilities,
       traits,
+      provider: adapter.name as ProviderName,
       name: agentProfileName,
       description: agentDescription,
       ...(traits.hasLocalEnvironment && {

package/src/e2b/dispatch.ts

@@ -14,6 +14,26 @@ export type E2BSandboxInfo = {
   startedAt?: string;
   endAt?: string;
   metadata?: Record<string, string>;
+  // Client-side fallback for the sandbox expiry. The raw `POST /sandboxes`
+  // create response uses E2B's `Sandbox` schema, which (unlike `ListedSandbox`
+  // / `SandboxDetail`) does NOT include `endAt`. We populate this from
+  // `now + timeoutSec*1000` at create time so `ttlRemaining` can report expiry
+  // immediately after a launch without an extra round-trip. `endAt` (when
+  // present, e.g. from `listSandboxes`) is always authoritative over this.
+  expiresAt?: string;
+};
+
+export type TtlRemaining = {
+  expiresAt?: string;
+  secondsLeft?: number;
+};
+
+export type SetSandboxTimeoutOptions = {
+  sandboxId: string;
+  apiKey: string;
+  apiBase?: string;
+  e2bEnv?: EnvMap;
+  timeoutMs: number;
 };
 
 export type E2BCommandResult = {
@@ -80,6 +100,25 @@ export type StartDetachedOptions = {
   cwd?: string;
 };
 
+export type StreamSandboxLogOptions = {
+  sandboxId: string;
+  role: E2BRole;
+  apiKey: string;
+  apiBase?: string;
+  e2bEnv?: EnvMap;
+  /** Number of trailing history lines to emit before following (default 200). */
+  tailLines?: number;
+  /** When true, keep streaming new output (`tail -f`) until the caller aborts. */
+  follow?: boolean;
+  /**
+   * Egress sink for each chunk. The caller MUST scrub here — log output is
+   * untrusted entrypoint stdout and can embed tokens/secrets.
+   */
+  onChunk: (chunk: string) => void;
+  /** Abort signal to stop a `--follow` stream (e.g. on SIGINT). */
+  signal?: AbortSignal;
+};
+
 type E2BSdkConnectionOptions = {
   apiKey: string;
   apiUrl?: string;
@@ -98,15 +137,24 @@ function e2bHeaders(apiKey: string): Record<string, string> {
   };
 }
 
-export function buildDetachedShell(command: string, logPath: string, pidPath: string): string {
-  return [
-    "set -e",
-    `nohup ${command} >${logPath} 2>&1 </dev/null & pid=$!`,
-    "sleep 2",
-    `if ! kill -0 "$pid" 2>/dev/null; then cat ${logPath} >&2; exit 1; fi`,
-    `echo "$pid" > ${pidPath}`,
-    'echo "$pid"',
-  ].join("; ");
+/**
+ * Build the shell payload for the envd-tracked entrypoint launch. Phase 5: the
+ * entrypoint is no longer detached via `nohup … >file &` (a grandchild envd
+ * never sees). Instead it runs as the SDK background command itself (envd owns
+ * and streams it; it survives client disconnect). We still `tee` to a
+ * deterministic file so `swarms logs` can retrieve FULL history later: the SDK's
+ * `commands.connect(pid)` only streams output going forward from the connect
+ * instant — it does NOT replay stdout produced while disconnected (verified
+ * against the e2b SDK types + docs) — so the file copy is the only reliable
+ * full-history source.
+ *
+ * `set -o pipefail` makes the pipeline's exit code reflect the ENTRYPOINT rather
+ * than `tee` (tee exits 0 on EOF even if the entrypoint crashed), so the early
+ * `exitCode` poll in {@link startDetachedProcess} can detect a launch failure.
+ * Invoked via `bash -lc` (both the api + worker images ship bash) for pipefail.
+ */
+export function buildTrackedShell(command: string, logPath: string): string {
+  return `set -o pipefail; ${command} 2>&1 | tee ${logPath}`;
 }
 
 export function e2bSdkConnectionOptions(
@@ -184,7 +232,10 @@ export async function e2bFetchJson<T>(
 }
 
 export async function createSandbox(opts: CreateSandboxOptions): Promise<E2BSandboxInfo> {
-  return e2bFetchJson<E2BSandboxInfo>(
+  // Capture the wall-clock create instant BEFORE the request so the client-side
+  // expiry fallback reflects when the TTL countdown begins.
+  const createdAt = Date.now();
+  const sandbox = await e2bFetchJson<E2BSandboxInfo>(
     "/sandboxes",
     opts.apiKey,
     {
@@ -200,6 +251,61 @@ export async function createSandbox(opts: CreateSandboxOptions): Promise<E2BSand
     },
     opts.apiBase,
   );
+  // Pre-flight check (resolved against node_modules/e2b types): the create
+  // response is E2B's `Sandbox` schema, which omits `endAt`. Compute a
+  // client-side expiry fallback so `ttlRemaining` works right after launch.
+  if (!sandbox.endAt && !sandbox.expiresAt) {
+    sandbox.expiresAt = new Date(createdAt + opts.timeoutSec * 1000).toISOString();
+  }
+  return sandbox;
+}
+
+/**
+ * Compute the remaining time-to-live for a sandbox. Prefers the authoritative
+ * `endAt` (present on listed/detail responses); falls back to the client-side
+ * `expiresAt` stamped by `createSandbox`. Returns an empty object when neither
+ * is available (e.g. a dry-run fake sandbox). `secondsLeft` is clamped at 0 so
+ * an already-expired sandbox never reports negative time.
+ */
+export function ttlRemaining(sandbox: E2BSandboxInfo): TtlRemaining {
+  const expiresAt = sandbox.endAt ?? sandbox.expiresAt;
+  if (!expiresAt) return {};
+  const expiryMs = Date.parse(expiresAt);
+  if (Number.isNaN(expiryMs)) return {};
+  const secondsLeft = Math.max(0, Math.round((expiryMs - Date.now()) / 1000));
+  return { expiresAt, secondsLeft };
+}
+
+/**
+ * Extend (or reduce) a live sandbox's TTL via the SDK and read back the actual
+ * `endAt` E2B applied (the server clamps to the tier max, so the requested
+ * timeout is not always honored verbatim). Connecting to a dead/expired sandbox
+ * throws; we translate that into a redacted "not found / already expired"
+ * error so a stale sandbox ID never leaks the controller key into logs.
+ */
+export async function setSandboxTimeout(opts: SetSandboxTimeoutOptions): Promise<TtlRemaining> {
+  const { Sandbox } = await import("e2b");
+  let sandbox: Awaited<ReturnType<typeof Sandbox.connect>>;
+  try {
+    sandbox = await Sandbox.connect(
+      opts.sandboxId,
+      e2bSdkConnectionOptions(opts.apiKey, opts.e2bEnv ?? {}, opts.apiBase),
+    );
+  } catch {
+    // Do not surface the underlying error verbatim — it can embed the
+    // controller API key / connection URL. Emit a fixed redacted message.
+    throw new Error(`sandbox ${opts.sandboxId} not found / already expired`);
+  }
+
+  await sandbox.setTimeout(opts.timeoutMs);
+  // `setTimeout` returns void; re-read the info to learn the clamped expiry.
+  const info = await sandbox.getInfo();
+  const expiresAt = info.endAt instanceof Date ? info.endAt.toISOString() : String(info.endAt);
+  return ttlRemaining({
+    sandboxID: opts.sandboxId,
+    templateID: info.templateId,
+    endAt: expiresAt,
+  });
 }
 
 export async function killSandbox(
@@ -222,27 +328,137 @@ export async function listSandboxes(
   return e2bFetchJson<E2BSandboxInfo[]>("/sandboxes", apiKey, {}, apiBase);
 }
 
+/**
+ * The deterministic per-role log path the entrypoint tees to. `swarms logs`
+ * recomputes it from the role alone (no PID bookkeeping needed) to `tail`/`cat`
+ * full history or `tail -f` for `--follow`.
+ */
+export function sandboxLogPath(role: E2BRole): string {
+  return `/tmp/agent-swarm-e2b-${role}.log`;
+}
+
+/**
+ * Launch the entrypoint as an envd-tracked BACKGROUND command (Phase 5). Returns
+ * the PID immediately. Replaces the old `nohup … >file & sleep 2; kill -0` hack:
+ * the SDK's background handle exposes `exitCode` (undefined while running), so we
+ * poll it once after a short grace period — a non-zero exit by then means the
+ * entrypoint died at launch, which we surface as a launch failure (reading the
+ * tee'd log for context). The `tee` preserves a file copy for full-history
+ * retrieval regardless of envd stdout-replay semantics.
+ */
 export async function startDetachedProcess(opts: StartDetachedOptions): Promise<string> {
-  const logPath = `/tmp/agent-swarm-e2b-${opts.role}.log`;
-  const pidPath = `/tmp/agent-swarm-e2b-${opts.role}.pid`;
-  const shell = buildDetachedShell(opts.command, logPath, pidPath);
+  const logPath = sandboxLogPath(opts.role);
+  const shell = buildTrackedShell(opts.command, logPath);
 
   const { Sandbox } = await import("e2b");
   const sandbox = await Sandbox.connect(
     opts.sandbox.sandboxID,
     e2bSdkConnectionOptions(opts.apiKey, opts.e2bEnv ?? {}, opts.apiBase),
   );
-  const result = await sandbox.commands.run(shell, {
+  // `bash -lc` (not `sh`) so `set -o pipefail` is honored on both images.
+  const handle = await sandbox.commands.run(`bash -lc ${shellQuote(shell)}`, {
     user: opts.user ?? "root",
     cwd: opts.cwd ?? "/",
     envs: opts.env,
-    timeoutMs: 30_000,
+    background: true,
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(`E2B start command failed: ${redactWithEnv(result.stderr, opts.env)}`);
+  // Early liveness poll: give the entrypoint a moment to fault, then check the
+  // handle's exit code. `undefined` = still running (the expected happy path).
+  await Bun.sleep(2_000);
+  if (typeof handle.exitCode === "number" && handle.exitCode !== 0) {
+    // The pipeline already exited non-zero — surface stderr/stdout (redacted, as
+    // entrypoint output can embed tokens) as a launch failure.
+    const detail = redactWithEnv(`${handle.stdout}\n${handle.stderr}`.trim(), opts.env);
+    throw new Error(`E2B start command exited ${handle.exitCode} at launch: ${detail}`);
+  }
+
+  return String(handle.pid);
+}
+
+/** Single-quote a string for safe embedding in a `bash -lc '<...>'` invocation. */
+function shellQuote(value: string): string {
+  return `'${value.split("'").join(`'\\''`)}'`;
+}
+
+/**
+ * Stream a sandbox's tee'd entrypoint log to the caller's `onChunk` sink.
+ *
+ * Design (Phase 5): we read from the deterministic per-role {@link sandboxLogPath}
+ * the entrypoint tees to — NOT from a tracked PID — so no PID bookkeeping is
+ * needed and history survives reconnect / a fresh CLI process. The SDK's
+ * `commands.connect(pid)` only streams forward from connect (no historical
+ * replay, verified against the SDK), so the file is the source of truth for
+ * full history.
+ *
+ * - History (no `--follow`): `tail -n <N> <logPath>` once (a CommandResult).
+ * - Follow: `tail -n <N> -F <logPath>` as a BACKGROUND command, piping each
+ *   `onStdout`/`onStderr` chunk to `onChunk` until the abort signal fires
+ *   (`-F` keeps following across truncation/rotation; tolerates a not-yet-created
+ *   file). The caller scrubs inside `onChunk`.
+ *
+ * Output is emitted RAW here; the caller is responsible for scrubbing in
+ * `onChunk` (it sees both this function's stdout and stderr).
+ */
+export async function streamSandboxLog(opts: StreamSandboxLogOptions): Promise<void> {
+  const logPath = sandboxLogPath(opts.role);
+  const tailLines = opts.tailLines ?? 200;
+
+  const { Sandbox } = await import("e2b");
+  const sandbox = await Sandbox.connect(
+    opts.sandboxId,
+    e2bSdkConnectionOptions(opts.apiKey, opts.e2bEnv ?? {}, opts.apiBase),
+  );
+
+  if (!opts.follow) {
+    // History only: a single `tail`. If the file does not exist yet (entrypoint
+    // hasn't written), `tail` exits non-zero with a message on stderr — we emit
+    // that to the sink rather than throwing, so a freshly-launched swarm reads as
+    // "no logs yet" instead of a hard error.
+    const result = await sandbox.commands.run(
+      `bash -lc ${shellQuote(`tail -n ${tailLines} ${logPath} 2>&1 || true`)}`,
+      { user: "root", timeoutMs: 30_000 },
+    );
+    if (result.stdout) opts.onChunk(result.stdout);
+    if (result.stderr) opts.onChunk(result.stderr);
+    return;
+  }
+
+  // Follow: background `tail -F` streaming forward. `-F` (vs `-f`) re-opens the
+  // file if it is rotated/recreated and waits for a not-yet-existing file.
+  const handle = await sandbox.commands.run(
+    `bash -lc ${shellQuote(`tail -n ${tailLines} -F ${logPath}`)}`,
+    {
+      user: "root",
+      background: true,
+      onStdout: (data) => opts.onChunk(data),
+      onStderr: (data) => opts.onChunk(data),
+    },
+  );
+
+  const stop = async () => {
+    try {
+      await handle.kill();
+    } catch {
+      // The command may already be gone (sandbox killed/expired); ignore.
+    }
+  };
+  if (opts.signal) {
+    if (opts.signal.aborted) {
+      await stop();
+      return;
+    }
+    opts.signal.addEventListener("abort", stop, { once: true });
+  }
+
+  try {
+    // `wait()` resolves when the stream ends (sandbox death) or the handle is
+    // killed by the abort listener above. `tail -F` otherwise runs indefinitely.
+    await handle.wait();
+  } catch {
+    // A kill / disconnect surfaces as a rejected wait — that is the expected exit
+    // path for `--follow`, not an error to propagate.
   }
-  return result.stdout.trim();
 }
 
 export async function waitForAgentRegistration(

package/src/http/memory.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { chunkContent } from "../be/chunking";
+import { getTaskById } from "../be/db";
 import { getEmbeddingProvider, getMemoryStore } from "../be/memory";
 import { CANDIDATE_SET_MULTIPLIER } from "../be/memory/constants";
 import { listEdgesForAgent } from "../be/memory/edges-store";
@@ -13,6 +14,7 @@ import {
 } from "../be/memory/raters/types";
 import { rerank } from "../be/memory/reranker";
 import { getRetrievalsForAgent, hasRetrievalForTask } from "../be/memory/retrieval-store";
+import { shouldPersistAutomaticTaskMemory } from "../memory/automatic-task-gate";
 import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "../types";
 import { route } from "./route-def";
 import { json, jsonError, parseQueryParams } from "./utils";
@@ -34,6 +36,7 @@ const indexMemory = route({
     sourceTaskId: z.string().uuid().optional(),
     sourcePath: z.string().optional(),
     tags: z.array(z.string()).optional(),
+    persistMemory: z.boolean().optional(),
   }),
   responses: {
     202: { description: "Content queued for embedding" },
@@ -249,7 +252,16 @@ export async function handleMemory(
     const parsed = await indexMemory.parse(req, res, pathSegments, new URLSearchParams());
     if (!parsed) return true;
 
-    const { agentId, content, name, scope, source, sourceTaskId, sourcePath, tags } = parsed.body;
+    const { agentId, content, name, scope, source, sourceTaskId, sourcePath, tags, persistMemory } =
+      parsed.body;
+
+    if (source === "session_summary" && sourceTaskId) {
+      const sourceTask = getTaskById(sourceTaskId);
+      if (sourceTask && !shouldPersistAutomaticTaskMemory(sourceTask, persistMemory)) {
+        json(res, { queued: false, memoryIds: [], skipped: "automatic_task_memory_disabled" }, 202);
+        return true;
+      }
+    }
 
     // Chunk content and create memories
     const contentChunks = chunkContent(content);

package/src/http/skills.ts

@@ -16,6 +16,9 @@ import { computeAgentSkillsSignature, syncSkillsToFilesystem } from "../be/skill
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
+const SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE =
+  "This skill is system-managed and cannot be edited from the UI; it is re-seeded on each start. Fork it under a new name to customize.";
+
 // ─── Route Definitions ───────────────────────────────────────────────────────
 
 const listSkillsRoute = route({
@@ -67,6 +70,7 @@ const createSkillRoute = route({
     type: z.string().optional(),
     scope: z.string().optional(),
     ownerAgentId: z.string().optional(),
+    systemDefault: z.boolean().optional(),
   }),
   responses: {
     201: { description: "Skill created" },
@@ -85,6 +89,7 @@ const updateSkillRoute = route({
   body: z.record(z.string(), z.unknown()),
   responses: {
     200: { description: "Skill updated" },
+    403: { description: "System-managed skills cannot be edited" },
     404: { description: "Skill not found" },
   },
 });
@@ -99,6 +104,7 @@ const deleteSkillRoute = route({
   params: z.object({ id: z.string() }),
   responses: {
     200: { description: "Skill deleted" },
+    403: { description: "System-managed skills cannot be deleted" },
     404: { description: "Skill not found" },
   },
 });
@@ -452,6 +458,7 @@ export async function handleSkills(
         agent: pm.agent,
         disableModelInvocation: pm.disableModelInvocation,
         userInvocable: pm.userInvocable,
+        systemDefault: parsed.body.systemDefault,
       });
       json(res, { skill }, 201);
     } catch (err) {
@@ -465,6 +472,42 @@ export async function handleSkills(
     const parsed = await updateSkillRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
+    const existing = getSkillById(parsed.params.id);
+    if (!existing) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+
+    const protectedSystemDefaultFields = [
+      "content",
+      "name",
+      "description",
+      "type",
+      "scope",
+      "ownerAgentId",
+      "sourceUrl",
+      "sourceRepo",
+      "sourcePath",
+      "sourceBranch",
+      "sourceHash",
+      "isComplex",
+      "allowedTools",
+      "model",
+      "effort",
+      "context",
+      "agent",
+      "disableModelInvocation",
+      "userInvocable",
+      "systemDefault",
+    ];
+    if (
+      existing.systemDefault &&
+      protectedSystemDefaultFields.some((field) => Object.hasOwn(parsed.body, field))
+    ) {
+      jsonError(res, SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, 403);
+      return true;
+    }
+
     const updates: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(parsed.body)) {
       updates[key] = value;
@@ -498,6 +541,16 @@ export async function handleSkills(
     const parsed = await deleteSkillRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
+    const existing = getSkillById(parsed.params.id);
+    if (!existing) {
+      jsonError(res, "Skill not found", 404);
+      return true;
+    }
+    if (existing.systemDefault) {
+      jsonError(res, SYSTEM_DEFAULT_SKILL_LOCKED_MESSAGE, 403);
+      return true;
+    }
+
     const deleted = deleteSkill(parsed.params.id);
     if (!deleted) {
       jsonError(res, "Skill not found", 404);

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) {