@desplega.ai/agent-swarm 1.131.1 → 1.134.0

package/src/jira/outbound.ts

@@ -1,4 +1,5 @@
 import { getTrackerSync, updateTrackerSync } from "../be/db-queries/tracker";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { workflowEventBus } from "../workflows/event-bus";
 import { jiraFetch } from "./client";
 
@@ -28,14 +29,44 @@ const OUTPUT_TRUNCATE_CHARS = 4000;
  * as a known v1 limitation; a per-issue debounce / bounded outbound queue
  * could be added in v2 if it becomes a real problem.
  */
+/**
+ * `EventEmitter.emit()` calls listeners synchronously and discards whatever
+ * they return, so a rejected async handler is never seen by the emitting side
+ * — it escapes to the process-level `unhandledRejection` handler with no
+ * subsystem context. These wrappers observe the *complete* handler body,
+ * including work that runs before any internal `try` (e.g. `getTrackerSync`).
+ *
+ * Each wrapper is created once at module scope so `off()` is passed the exact
+ * reference `on()` registered; building them inside `init` would leave the
+ * listeners attached after teardown.
+ */
+function observed(
+  eventName: string,
+  handler: (data: unknown) => Promise<void>,
+): (data: unknown) => void {
+  return (data: unknown): void => {
+    handler(data).catch((error) => {
+      console.error(
+        `[Jira Outbound] ${eventName} handler failed:`,
+        scrubSecrets(error instanceof Error ? error.message : String(error)),
+      );
+    });
+  };
+}
+
+const onTaskCreated = observed("task.created", handleTaskCreated);
+const onTaskCompleted = observed("task.completed", handleTaskCompleted);
+const onTaskFailed = observed("task.failed", handleTaskFailed);
+const onTaskCancelled = observed("task.cancelled", handleTaskCancelled);
+
 export function initJiraOutboundSync(): void {
   if (subscribed) return;
   subscribed = true;
 
-  workflowEventBus.on("task.created", handleTaskCreated);
-  workflowEventBus.on("task.completed", handleTaskCompleted);
-  workflowEventBus.on("task.failed", handleTaskFailed);
-  workflowEventBus.on("task.cancelled", handleTaskCancelled);
+  workflowEventBus.on("task.created", onTaskCreated);
+  workflowEventBus.on("task.completed", onTaskCompleted);
+  workflowEventBus.on("task.failed", onTaskFailed);
+  workflowEventBus.on("task.cancelled", onTaskCancelled);
   console.log("[Jira] Outbound sync subscribed to event bus");
 }
 
@@ -43,10 +74,10 @@ export function teardownJiraOutboundSync(): void {
   if (!subscribed) return;
   subscribed = false;
 
-  workflowEventBus.off("task.created", handleTaskCreated);
-  workflowEventBus.off("task.completed", handleTaskCompleted);
-  workflowEventBus.off("task.failed", handleTaskFailed);
-  workflowEventBus.off("task.cancelled", handleTaskCancelled);
+  workflowEventBus.off("task.created", onTaskCreated);
+  workflowEventBus.off("task.completed", onTaskCompleted);
+  workflowEventBus.off("task.failed", onTaskFailed);
+  workflowEventBus.off("task.cancelled", onTaskCancelled);
   console.log("[Jira] Outbound sync unsubscribed from event bus");
 }
 

package/src/jira/webhook-lifecycle.ts

@@ -1,4 +1,5 @@
 import { getPublicMcpBaseUrl } from "../utils/constants";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { jiraFetch } from "./client";
 import { getJiraMetadata, updateJiraMetadata } from "./metadata";
 
@@ -359,11 +360,21 @@ export function startJiraWebhookKeepalive(): void {
   // Immediate-on-boot check (after a short delay so server finishes startup
   // and OAuth tokens are loaded). Mirrors src/oauth/keepalive.ts pattern.
   setTimeout(() => {
-    runKeepalive();
+    runKeepalive().catch((err) =>
+      console.error(
+        "[Jira webhook keepalive] run failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   }, 10_000);
 
   keepaliveInterval = setInterval(() => {
-    runKeepalive();
+    runKeepalive().catch((err) =>
+      console.error(
+        "[Jira webhook keepalive] run failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   }, TWELVE_HOURS_MS);
 }
 

package/src/linear/outbound.ts

@@ -1,5 +1,6 @@
 import { getTrackerSync, updateTrackerSync } from "../be/db-queries/tracker";
 import { ensureToken } from "../oauth/ensure-token";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { workflowEventBus } from "../workflows/event-bus";
 import { getLinearClient, resetLinearClient } from "./client";
 import { endAgentSession, postAgentSessionAction, taskSessionMap } from "./sync";
@@ -8,15 +9,47 @@ let subscribed = false;
 
 const LOOP_PREVENTION_WINDOW_MS = 5_000;
 
+/**
+ * `EventEmitter.emit()` calls listeners synchronously and discards whatever
+ * they return, so a rejected async handler is never seen by the emitting side
+ * — it escapes to the process-level `unhandledRejection` handler with no
+ * subsystem context. These wrappers observe the *complete* handler body,
+ * including work that runs before any internal `try` (e.g. `getTrackerSync`)
+ * and the `updateTrackerSync` write that runs after it.
+ *
+ * Each wrapper is created once at module scope so `off()` is passed the exact
+ * reference `on()` registered; building them inside `init` would leave the
+ * listeners attached after teardown.
+ */
+function observed(
+  eventName: string,
+  handler: (data: unknown) => Promise<void>,
+): (data: unknown) => void {
+  return (data: unknown): void => {
+    handler(data).catch((error) => {
+      console.error(
+        `[Linear Outbound] ${eventName} handler failed:`,
+        scrubSecrets(error instanceof Error ? error.message : String(error)),
+      );
+    });
+  };
+}
+
+const onTaskCreated = observed("task.created", handleTaskCreated);
+const onTaskCompleted = observed("task.completed", handleTaskCompleted);
+const onTaskFailed = observed("task.failed", handleTaskFailed);
+const onTaskCancelled = observed("task.cancelled", handleTaskCancelled);
+const onTaskProgress = observed("task.progress", handleTaskProgress);
+
 export function initLinearOutboundSync(): void {
   if (subscribed) return;
   subscribed = true;
 
-  workflowEventBus.on("task.created", handleTaskCreated);
-  workflowEventBus.on("task.completed", handleTaskCompleted);
-  workflowEventBus.on("task.failed", handleTaskFailed);
-  workflowEventBus.on("task.cancelled", handleTaskCancelled);
-  workflowEventBus.on("task.progress", handleTaskProgress);
+  workflowEventBus.on("task.created", onTaskCreated);
+  workflowEventBus.on("task.completed", onTaskCompleted);
+  workflowEventBus.on("task.failed", onTaskFailed);
+  workflowEventBus.on("task.cancelled", onTaskCancelled);
+  workflowEventBus.on("task.progress", onTaskProgress);
   console.log("[Linear] Outbound sync subscribed to event bus");
 }
 
@@ -24,11 +57,11 @@ export function teardownLinearOutboundSync(): void {
   if (!subscribed) return;
   subscribed = false;
 
-  workflowEventBus.off("task.created", handleTaskCreated);
-  workflowEventBus.off("task.completed", handleTaskCompleted);
-  workflowEventBus.off("task.failed", handleTaskFailed);
-  workflowEventBus.off("task.cancelled", handleTaskCancelled);
-  workflowEventBus.off("task.progress", handleTaskProgress);
+  workflowEventBus.off("task.created", onTaskCreated);
+  workflowEventBus.off("task.completed", onTaskCompleted);
+  workflowEventBus.off("task.failed", onTaskFailed);
+  workflowEventBus.off("task.cancelled", onTaskCancelled);
+  workflowEventBus.off("task.progress", onTaskProgress);
   console.log("[Linear] Outbound sync unsubscribed from event bus");
 }
 

package/src/oauth/keepalive.ts

@@ -1,4 +1,5 @@
 import { listKeepAliveAuthorizations } from "../be/db-queries/oauth";
+import { scrubSecrets } from "../utils/secret-scrubber";
 import { ensureAuthorizationTokenOrThrow } from "./ensure-token";
 
 // Keep refresh tokens warm without constantly rotating strict-rotation
@@ -115,11 +116,21 @@ export function startOAuthKeepalive(): void {
   // Run once after a short delay (let server finish startup).
   startupKeepaliveTimeout = setTimeout(() => {
     startupKeepaliveTimeout = null;
-    scheduleKeepaliveRun("startup");
+    scheduleKeepaliveRun("startup").catch((err) =>
+      console.error(
+        "[OAuth Keepalive] startup run failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   }, STARTUP_KEEPALIVE_DELAY_MS);
 
   keepaliveInterval = setInterval(() => {
-    scheduleKeepaliveRun("interval");
+    scheduleKeepaliveRun("interval").catch((err) =>
+      console.error(
+        "[OAuth Keepalive] interval run failed:",
+        scrubSecrets(err instanceof Error ? err.message : String(err)),
+      ),
+    );
   }, KEEPALIVE_INTERVAL_MS);
 }
 

package/src/prompts/base-prompt.ts

@@ -16,7 +16,7 @@ import { resolveTemplateAsync } from "./resolver";
 import "./session-templates";
 
 /** Max characters per individual injected section before truncation */
-const BOOTSTRAP_MAX_CHARS = 20_000;
+export const BOOTSTRAP_MAX_CHARS = 20_000;
 
 /**
  * Max total characters across all injected sections combined.

package/src/prompts/default-drift.ts

@@ -0,0 +1,21 @@
+export interface PromptTemplateDefaultDrift {
+  defaultDrifted: boolean;
+  customizedBytes: number;
+  defaultBytes: number;
+  byteDelta: number;
+}
+
+export function getPromptTemplateDefaultDrift(
+  template: { body: string; isDefault: boolean },
+  defaultBody: string,
+): PromptTemplateDefaultDrift {
+  const customizedBytes = Buffer.byteLength(template.body, "utf8");
+  const defaultBytes = Buffer.byteLength(defaultBody, "utf8");
+
+  return {
+    defaultDrifted: !template.isDefault && template.body !== defaultBody,
+    customizedBytes,
+    defaultBytes,
+    byteDelta: defaultBytes - customizedBytes,
+  };
+}

package/src/prompts/session-templates.ts

@@ -63,7 +63,7 @@ As the lead agent, you coordinate all worker agents in the swarm.
 
 **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 GitHub/GitLab identity or other source metadata)
+- \`manage-user\`: Register or update human users (resolve from GitHub/GitLab identity or other source metadata). When you learn a requester's stable communication preferences (tone, language, verbosity), persist them with its \`comms\` field so future sessions adapt.
 
 #### Task Routing
 
@@ -145,6 +145,17 @@ As a worker agent of the swarm, you are responsible for executing tasks assigned
 - Each worker focuses on specific tasks or objectives, contributing to the overall goals of the swarm.
 - Workers MUST report their progress back to the lead and collaborate with other workers as needed.
 
+#### Skills (CHECK BEFORE STARTING WORK)
+
+You have installed skills with tested procedures for common tasks. Before doing manual research or implementation, check the installed skill catalog and invoke a matching skill first.
+
+Examples:
+- Researching a codebase → use \`researching\`
+- Planning an implementation → use \`planning\`
+- Reviewing code changes → use \`code-reviewing\`
+
+**Rule: If a skill exists for your task type, USE IT. Do not research what the skill already documents.**
+
 #### Useful tools for workers
 
 - \`store-progress\`: Save your work progress on tasks (critical!)
@@ -803,6 +814,32 @@ When working in a repository, your system prompt may include a **Repository Guid
   category: "system",
 });
 
+registerTemplate({
+  eventType: "system.agent.communication_style",
+  header: "",
+  defaultBody: `
+### Communication Style
+
+Your persona lives in your SOUL.md (see Your Identity, when present). It defines who you are. The rules below define how you write, whoever you are.
+
+They govern everything a human reads from you: Slack, PR and issue comments, tickets, email, pages, and task summaries.
+
+- Write like a person, not a press release. Plain words, direct statements.
+- Lead with the outcome or the answer. Context comes after.
+- Keep sentences short (25 words or fewer). One idea per sentence.
+- Use active voice. Say who did what.
+- Never use em dashes. Use a period, a comma, a colon, or parentheses.
+- No marketing adjectives (seamless, robust, powerful). State the fact that earns the claim instead.
+- No hedge stacks ("might possibly perhaps"). Keep a hedge only when you are genuinely unsure, and keep it: "may have failed" never becomes "failed".
+- No filler ("I hope this helps", "Great question!") and no formal sign-offs.
+- If something is broken, blocked, or a bad idea, say so plainly and say why.
+- Mirror the requester: reply in the language they wrote in, match their register, and answer at the depth they asked. A one-line question gets the answer first, detail after.
+- If a Requester Profile section is present, it wins on tone, depth, and format. Correctness always wins over style.
+`,
+  variables: [],
+  category: "system",
+});
+
 // ============================================================================
 // Per-task prompt templates (category: "task_lifecycle")
 // ============================================================================
@@ -812,12 +849,18 @@ registerTemplate({
   header: "",
   defaultBody: `
 ## Requester Profile
-This task was requested by {{requester_name}}{{requester_role_suffix}}.{{requester_notes_section}}
+This task was requested by {{requester_name}}{{requester_role_suffix}}.{{requester_comms_section}}{{requester_notes_section}}
 Honor this requester profile in tone, depth, and format where it doesn't conflict with correctness or your operating rules.
+If this task reveals new stable communication preferences for this requester, persist them: the lead updates \`comms\` (tone, language, verbosity) via \`manage-user\`.
 `,
   variables: [
     { name: "requester_name", description: "The requesting user's display name" },
     { name: "requester_role_suffix", description: "Formatted role suffix, including parentheses" },
+    {
+      name: "requester_comms_section",
+      description:
+        "Formatted communication preferences (tone/language/verbosity) sourced from users.metadata.comms, or empty string",
+    },
     {
       name: "requester_notes_section",
       description: "Formatted notes section sourced from users.notes, or empty string",
@@ -859,7 +902,8 @@ registerTemplate({
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
-{{@template[system.agent.code_quality]}}`,
+{{@template[system.agent.code_quality]}}
+{{@template[system.agent.communication_style]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
     { name: "agentId", description: "The agent's unique identifier" },
@@ -881,7 +925,8 @@ registerTemplate({
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
-{{@template[system.agent.code_quality]}}`,
+{{@template[system.agent.code_quality]}}
+{{@template[system.agent.communication_style]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
     { name: "agentId", description: "The agent's unique identifier" },
@@ -910,7 +955,8 @@ registerTemplate({
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
-{{@template[system.agent.code_quality]}}`,
+{{@template[system.agent.code_quality]}}
+{{@template[system.agent.communication_style]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
     { name: "agentId", description: "The agent's unique identifier" },
@@ -939,7 +985,8 @@ registerTemplate({
 
 {{@template[system.agent.system]}}
 {{@template[system.agent.share_urls]}}
-{{@template[system.agent.code_quality]}}`,
+{{@template[system.agent.code_quality]}}
+{{@template[system.agent.communication_style]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
     { name: "agentId", description: "The agent's unique identifier" },
@@ -982,7 +1029,9 @@ registerTemplate({
   header: "",
   defaultBody: `{{@template[system.agent.role]}}
 
-{{@template[system.agent.worker.remote]}}`,
+{{@template[system.agent.worker.remote]}}
+
+{{@template[system.agent.communication_style]}}`,
   variables: [
     { name: "role", description: "The agent's role" },
     { name: "agentId", description: "The agent's unique identifier" },

package/src/providers/claude-adapter.ts

@@ -19,6 +19,7 @@ import {
   trackErrorFromJson,
 } from "../utils/error-tracker";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
+import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { CTX_MODE_NUDGE_EVERY } from "./ctx-mode-env";
 import { buildOtelTraceparentEnv, isHarnessOtelEnabled } from "./otel-env";
@@ -332,6 +333,7 @@ export function mergeMcpConfig(
   installedServers: Record<string, Record<string, unknown>> | null,
   taskId: string,
   contextKey?: string,
+  runtimeInstanceId?: string,
 ): { mcpServers: Record<string, unknown> } {
   const config: { mcpServers: Record<string, unknown> } = {
     mcpServers: { ...(baseConfig?.mcpServers ?? {}) },
@@ -360,6 +362,9 @@ export function mergeMcpConfig(
     if (contextKey) {
       (server.headers as Record<string, string>)["X-Context-Key"] = contextKey;
     }
+    if (runtimeInstanceId) {
+      (server.headers as Record<string, string>)["X-Runtime-Instance-ID"] = runtimeInstanceId;
+    }
   }
 
   return config;
@@ -434,6 +439,7 @@ export async function createSessionMcpConfig(
       installedServers ?? null,
       taskId,
       contextKey,
+      swarmRuntimeInstanceId(),
     );
     const sessionConfigPath = `/tmp/mcp-${taskId}.json`;
     await writeFile(sessionConfigPath, JSON.stringify(config, null, 2));

package/src/providers/codex-adapter.ts

@@ -77,6 +77,7 @@ import {
 } from "../utils/context-window";
 import { SessionErrorTracker } from "../utils/error-tracker";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
+import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { type CodexAgentsMdHandle, writeCodexAgentsMd } from "./codex-agents-md";
 import { computeCodexCostUsd, getCodexContextWindow, resolveCodexModel } from "./codex-models";
@@ -365,12 +366,17 @@ export async function buildCodexConfig(
   // (2) Swarm MCP server — Streamable HTTP transport.
   // Field names verified against https://developers.openai.com/codex/mcp:
   // `url`, `http_headers`, `enabled`, `startup_timeout_sec`, `tool_timeout_sec`.
+  // Same per-boot runtime identity the runner registers with — dispatch tools
+  // require it in multi-runtime mode, and it travels as request context, not
+  // as a tool argument.
+  const runtimeInstanceId = swarmRuntimeInstanceId();
   mcpServers["agent-swarm"] = {
     url: `${config.apiUrl}/mcp`,
     http_headers: {
       Authorization: `Bearer ${config.apiKey}`,
       "X-Agent-ID": config.agentId,
       "X-Source-Task-Id": config.taskId ?? "",
+      ...(runtimeInstanceId ? { "X-Runtime-Instance-ID": runtimeInstanceId } : {}),
     },
     enabled: true,
     startup_timeout_sec: 30,

package/src/providers/opencode-adapter.ts

@@ -19,6 +19,7 @@ import {
 } from "../utils/context-window";
 import { validateOpencodeCredentials } from "../utils/credentials";
 import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
+import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
 import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { resolveSlashSkillPrompt } from "./codex-skill-resolver";
@@ -726,6 +727,10 @@ export class OpencodeAdapter implements ProviderAdapter {
     const installedMcp =
       (await fetchInstalledMcpServers(config.apiUrl, config.apiKey, config.agentId, "opencode")) ??
       {};
+    // Same per-boot runtime identity the runner registers with — dispatch
+    // tools require it in multi-runtime mode, and it travels as request
+    // context, not as a tool argument.
+    const runtimeInstanceId = swarmRuntimeInstanceId();
     const mcpConfig: Config["mcp"] = {
       swarm: {
         type: "remote",
@@ -733,6 +738,7 @@ export class OpencodeAdapter implements ProviderAdapter {
         headers: {
           Authorization: `Bearer ${config.apiKey}`,
           "X-Agent-ID": config.agentId,
+          ...(runtimeInstanceId ? { "X-Runtime-Instance-ID": runtimeInstanceId } : {}),
         },
       },
       ...installedMcp,

package/src/providers/pi-mono-adapter.ts

@@ -28,6 +28,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type TSchema, Type } from "typebox";
 import { classifyAwsSdkError } from "../utils/aws-error-classifier";
+import { swarmRuntimeInstanceId } from "../utils/multi-runtime";
 import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { readPkgVersion } from "./harness-version";
@@ -1089,6 +1090,13 @@ export class PiMonoAdapter implements ProviderAdapter {
           config.agentId,
           config.taskId,
         );
+        // Same per-boot runtime identity the runner registers with — dispatch
+        // tools require it in multi-runtime mode, and it travels as request
+        // context, not as a tool argument.
+        const runtimeInstanceId = swarmRuntimeInstanceId();
+        if (runtimeInstanceId) {
+          mcpClient.customHeaders["X-Runtime-Instance-ID"] = runtimeInstanceId;
+        }
         await mcpClient.initialize();
         const tools = await mcpClient.listTools();
         customTools = mcpToolsToDefinitions(mcpClient, tools);

package/src/providers/pricing-sources.md

@@ -84,6 +84,30 @@ Unlike token rates — where a missing rate marks the whole row
 That asymmetry is deliberate (a small request fee shouldn't unprice an entire
 session) and is documented in the cost-and-context-computation guide.
 
+## Attribution reporting contract
+
+Usage reporting keeps total spend separate from the cost population that can
+truthfully carry a human requester:
+
+- `attributableCostUsd` is total cost minus structurally human-free work;
+  coverage is `attributedCostUsd / attributableCostUsd`.
+- `excludedCostUsd` and `excludedTaskCount` retain visibility into the removed
+  population. A stale requester id on structurally human-free work does not put
+  that cost back into either side of the coverage ratio.
+- Human-free seeds are the `heartbeat`, `heartbeat-checklist`, and
+  `boot-triage` task types; legacy JSON tag rows matched by the `heartbeat`
+  tags `LIKE` check; creatorless schedules (including their workflow roots);
+  and requester-less system follow-ups of requester-less parents.
+- The classification propagates through requester-less descendants. An
+  explicitly attributed child is a human handoff and stops propagation down
+  that branch.
+
+The per-person report uses the same requester data model without grouping the
+cost denominator or turning it into a leaderboard. Human-requested root tasks
+determine Problems Initiated and Problems Shipped; their full task trees
+determine Agents, Repos, and Surfaces Reached. Requester-less autonomous roots
+and heartbeat-classified roots are omitted, and the metrics remain separate.
+
 ## Provider pricing caveats
 
 - **Claude Sonnet 5 introductory rate:** Anthropic's pricing page lists