@desplega.ai/agent-swarm 1.84.0 → 1.85.0

package/src/tools/get-tasks.ts

@@ -140,6 +140,10 @@ export async function getTasksHandler(
   if (scheduleId) filters.push(`scheduleId='${scheduleId}'`);
 
   const filterMsg = filters.length > 0 ? ` (${filters.join(", ")})` : "";
+  const structuredContent = {
+    yourAgentId: agentId,
+    tasks: taskSummaries,
+  };
 
   return {
     content: [
@@ -147,11 +151,12 @@ export async function getTasksHandler(
         type: "text",
         text: `Found ${taskSummaries.length} task(s)${filterMsg}.`,
       },
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent),
+      },
     ],
-    structuredContent: {
-      yourAgentId: agentId,
-      tasks: taskSummaries,
-    },
+    structuredContent,
   };
 }
 

package/src/tools/oauth-access-token.ts

@@ -0,0 +1,118 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getOAuthTokens } from "@/be/db-queries/oauth";
+import { ensureTokenOrThrow } from "@/oauth/ensure-token";
+import { createToolRegistrar } from "@/tools/utils";
+import { registerVolatileSecret } from "@/utils/secret-scrubber";
+
+type OAuthProvider = string;
+
+export interface OAuthAccessTokenResult {
+  provider: OAuthProvider;
+  accessToken: string;
+  expiresAt: string;
+  tokenType: "Bearer";
+}
+
+function assertTokenUsable(
+  provider: OAuthProvider,
+  expiresAt: string,
+  minValidityMs: number,
+): void {
+  const expiresAtMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expiresAtMs)) {
+    throw new Error(`${provider} OAuth token has an invalid expiry`);
+  }
+  if (expiresAtMs - Date.now() < minValidityMs) {
+    throw new Error(
+      `${provider} OAuth token is expired or expiring soon and could not be refreshed`,
+    );
+  }
+}
+
+export async function resolveOAuthAccessToken(
+  provider: OAuthProvider,
+  minValiditySeconds = 300,
+): Promise<OAuthAccessTokenResult> {
+  const minValidityMs = minValiditySeconds * 1000;
+  await ensureTokenOrThrow(provider, minValidityMs);
+
+  const tokens = getOAuthTokens(provider);
+  if (!tokens) {
+    throw new Error(`${provider} OAuth tokens are not connected`);
+  }
+
+  assertTokenUsable(provider, tokens.expiresAt, minValidityMs);
+  registerVolatileSecret(tokens.accessToken, `${provider.toUpperCase()}_OAUTH_ACCESS_TOKEN`);
+
+  return {
+    provider,
+    accessToken: tokens.accessToken,
+    expiresAt: tokens.expiresAt,
+    tokenType: "Bearer",
+  };
+}
+
+export const registerGetOauthAccessTokenTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "get-oauth-access-token",
+    {
+      title: "Get OAuth access token",
+      description:
+        "Return a valid plaintext OAuth access token for an integrated tracker. The token is refreshed first when it is near expiry. Returns access_token only; never returns refresh_token.",
+      annotations: { destructiveHint: false, openWorldHint: true },
+      inputSchema: z.object({
+        provider: z
+          .string()
+          .min(1)
+          .max(64)
+          .regex(/^[A-Za-z0-9][A-Za-z0-9_-]*$/, "provider must be a slug")
+          .describe("OAuth provider slug to read from oauth_tokens (for example: linear, jira)."),
+        minValiditySeconds: z
+          .number()
+          .int()
+          .min(0)
+          .max(3600)
+          .optional()
+          .default(300)
+          .describe("Minimum remaining token lifetime required before returning it."),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+        provider: z.string().optional(),
+        accessToken: z.string().optional(),
+        expiresAt: z.string().optional(),
+        tokenType: z.literal("Bearer").optional(),
+      }),
+    },
+    async ({ provider, minValiditySeconds }, _requestInfo, _meta) => {
+      try {
+        const token = await resolveOAuthAccessToken(provider, minValiditySeconds);
+        const message = `${provider} OAuth access token resolved; expires at ${token.expiresAt}.`;
+        return {
+          content: [
+            {
+              type: "text",
+              text: `${message}\n\n${token.accessToken}`,
+            },
+          ],
+          structuredContent: {
+            success: true,
+            message,
+            ...token,
+          },
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{ type: "text", text: `Failed to resolve OAuth access token: ${message}` }],
+          structuredContent: {
+            success: false,
+            message,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/send-task.ts

@@ -326,13 +326,17 @@ export async function sendTaskHandler(
   });
 
   const result = txn();
+  const structuredContent = {
+    yourAgentId: creatorAgentId,
+    ...result,
+  };
 
   return {
-    content: [{ type: "text", text: result.message }],
-    structuredContent: {
-      yourAgentId: creatorAgentId,
-      ...result,
-    },
+    content: [
+      { type: "text", text: result.message },
+      { type: "text", text: JSON.stringify(result) },
+    ],
+    structuredContent,
   };
 }
 

package/src/tools/store-progress.ts

@@ -3,14 +3,11 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import {
   completeTask,
-  createTaskExtended,
   failTask,
   getAgentById,
   getDb,
-  getLeadAgent,
   getResolvedConfig,
   getSessionLogsByTaskId,
-  getTaskAttachments,
   getTaskById,
   insertTaskAttachment,
   updateAgentStatusFromCapacity,
@@ -19,11 +16,9 @@ import {
 import { getEmbeddingProvider, getMemoryStore } from "@/be/memory";
 import { getRetrievalsForTask } from "@/be/memory/raters/retrieval";
 import { runServerRaters } from "@/be/memory/raters/run-server-raters";
-import { resolveTemplate } from "@/prompts/resolver";
+import { createWorkerTaskFollowUp } from "@/tasks/worker-follow-up";
 import { createToolRegistrar } from "@/tools/utils";
-import { AgentTaskSchema, AttachmentInputSchema, type TaskAttachment } from "@/types";
-// Side-effect import: registers task lifecycle templates in the in-memory registry
-import "./templates";
+import { AgentTaskSchema, AttachmentInputSchema } from "@/types";
 import { validateJsonSchema } from "@/workflows/json-schema-validator";
 
 // Phase 11: the `cost` / `costData` field was removed from this tool's input
@@ -33,29 +28,6 @@ import { validateJsonSchema } from "@/workflows/json-schema-validator";
 // echoed the schema example, producing noise rows keyed `mcp-<taskId>-<ts>`
 // that double-counted alongside the harness's authoritative entry.
 
-function attachmentPointer(a: TaskAttachment): string {
-  switch (a.kind) {
-    case "url":
-      return a.url ?? "";
-    case "page":
-      return `page:${a.pageId ?? ""}`;
-    case "agent-fs":
-      return `agent-fs:${a.path ?? ""}`;
-    case "shared-fs":
-      return `shared-fs:${a.path ?? ""}`;
-  }
-}
-
-function formatAttachmentsBlock(attachments: TaskAttachment[]): string {
-  if (attachments.length === 0) return "";
-  const lines = attachments.map((a) => {
-    const tag = a.isPrimary ? "[primary] " : "";
-    const intent = a.intent ? ` (intent: ${a.intent})` : "";
-    return `- ${tag}${a.name} — ${attachmentPointer(a)}${intent}`;
-  });
-  return `\n\nAttachments (${attachments.length}):\n${lines.join("\n")}`;
-}
-
 export const registerStoreProgressTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "store-progress",
@@ -460,53 +432,16 @@ export const registerStoreProgressTool = (server: McpServer) => {
         !("wasNoOp" in result && result.wasNoOp)
       ) {
         try {
-          const taskAgent = getAgentById(result.task.agentId ?? "");
-          // Only create follow-ups for worker tasks (not lead's own tasks)
-          if (taskAgent && !taskAgent.isLead) {
-            const leadAgent = getLeadAgent();
-            if (leadAgent) {
-              const agentName = taskAgent.name || result.task.agentId?.slice(0, 8) || "Unknown";
-              const taskDesc = result.task.task.slice(0, 200);
-
-              let followUpDescription: string;
-              if (status === "completed") {
-                const attachmentsBlock = formatAttachmentsBlock(getTaskAttachments(taskId));
-                const outputSummary = output
-                  ? `${output.slice(0, 500)}${output.length > 500 ? "..." : ""}${attachmentsBlock}`
-                  : `(no output)${attachmentsBlock}`;
-                const completedResult = resolveTemplate("task.worker.completed", {
-                  agent_name: agentName,
-                  task_desc: taskDesc,
-                  output_summary: outputSummary,
-                  task_id: taskId,
-                });
-                followUpDescription = completedResult.text;
-              } else {
-                const reason = failureReason || "(no reason given)";
-                const failedResult = resolveTemplate("task.worker.failed", {
-                  agent_name: agentName,
-                  task_desc: taskDesc,
-                  failure_reason: reason,
-                  task_id: taskId,
-                });
-                followUpDescription = failedResult.text;
-              }
-
-              // If the original task came from Slack, forward context so lead can reply
-              createTaskExtended(followUpDescription, {
-                agentId: leadAgent.id,
-                source: "system",
-                taskType: "follow-up",
-                parentTaskId: taskId,
-                slackChannelId: result.task.slackChannelId,
-                slackThreadTs: result.task.slackThreadTs,
-                slackUserId: result.task.slackUserId,
-              });
-
-              console.log(
-                `[store-progress] Created follow-up task for lead (${leadAgent.name}) — ${status} task ${taskId.slice(0, 8)} by ${agentName}`,
-              );
-            }
+          const followUp = createWorkerTaskFollowUp({
+            task: result.task,
+            status,
+            output,
+            failureReason,
+          });
+          if (followUp) {
+            console.log(
+              `[store-progress] Created follow-up task ${followUp.id.slice(0, 8)} for ${status} task ${taskId.slice(0, 8)}`,
+            );
           }
         } catch (err) {
           // Non-blocking — follow-up task creation failure should not affect the store-progress response

package/src/tools/task-action.ts

@@ -108,24 +108,34 @@ type TaskActionResult = {
 
 function agentOnlyActionResult(): CallToolResult {
   const message = "This action is only available to worker agents.";
+  const structuredContent = {
+    success: false,
+    message,
+  };
+
   return {
     isError: true,
-    content: [{ type: "text", text: message }],
-    structuredContent: {
-      success: false,
-      message,
-    },
+    content: [
+      { type: "text", text: message },
+      { type: "text", text: JSON.stringify(structuredContent) },
+    ],
+    structuredContent,
   };
 }
 
 function taskActionCallResult(result: TaskActionResult, agentId?: string): CallToolResult {
   const { refusalSideEffects: _omit, ...publicResult } = result;
+  const structuredContent = {
+    yourAgentId: agentId,
+    ...publicResult,
+  };
+
   return {
-    content: [{ type: "text", text: result.message }],
-    structuredContent: {
-      yourAgentId: agentId,
-      ...publicResult,
-    },
+    content: [
+      { type: "text", text: result.message },
+      { type: "text", text: JSON.stringify(structuredContent) },
+    ],
+    structuredContent,
   };
 }
 

package/src/tools/tool-config.ts

@@ -104,8 +104,9 @@ export const DEFERRED_TOOLS = new Set([
   "send-whatsapp-message",
   "reply-whatsapp-message",
 
-  // Tracker (6)
+  // Tracker (7)
   "tracker-status",
+  "get-oauth-access-token",
   "tracker-link-task",
   "tracker-unlink",
   "tracker-sync-status",

package/src/types.ts

@@ -212,6 +212,10 @@ export const AgentTaskSchema = z.object({
   // Provider tracking — which harness provider ran this task
   provider: ProviderNameSchema.optional(),
   providerMeta: z.record(z.string(), z.unknown()).optional(),
+
+  // Aggregated session cost for task list/read models. Undefined means no
+  // session cost rows have been recorded for this task.
+  totalCostUsd: z.number().min(0).optional(),
 });
 
 // ============================================================================
@@ -1328,6 +1332,7 @@ export type AgentTaskSummary = Pick<
   | "lastUpdatedAt"
   | "finishedAt"
   | "peakContextPercent"
+  | "totalCostUsd"
 >;
 
 export const PageVersionSchema = z.object({

package/src/utils/secret-scrubber.ts

@@ -142,6 +142,7 @@ interface ScrubCache {
 }
 
 let cache: ScrubCache | null = null;
+const volatileSecrets = new Map<string, string>();
 
 /** Fingerprint current env so we can invalidate cache cheaply when it changes. */
 function snapshotEnv(): string {
@@ -225,6 +226,12 @@ export function scrubSecrets(text: string | null | undefined): string {
     }
   }
 
+  for (const [value, name] of volatileSecrets) {
+    if (out.includes(value)) {
+      out = out.split(value).join(`[REDACTED:${name}]`);
+    }
+  }
+
   // Pass 2: structural patterns (catches secrets we never saw in env, e.g.
   // a token pasted into a tool_result by the operator or fetched from a
   // third-party API during a task).
@@ -265,3 +272,19 @@ export function scrubObject<T>(value: T, seen = new WeakSet<object>()): T {
 export function refreshSecretScrubberCache(): void {
   cache = null;
 }
+
+/**
+ * Register a runtime-fetched secret that is not present in process.env.
+ *
+ * Use this before returning short-lived tokens through an API/tool result so
+ * follow-on logs, telemetry previews, and session-log egress can redact the
+ * concrete value even though the caller still receives it.
+ */
+export function registerVolatileSecret(value: string, name: string): void {
+  if (value.length < MIN_VALUE_LENGTH) return;
+  volatileSecrets.set(value, name);
+}
+
+export function clearVolatileSecretsForTesting(): void {
+  volatileSecrets.clear();
+}

package/templates/skills/agentmail-sending/SKILL.md

@@ -1,49 +1,169 @@
 ---
 name: agentmail-sending
-description: CRITICAL rules for sending emails via AgentMail API. Covers the HTML bug workaround, BCC policy, and best practices. ALL agents MUST follow these rules when using send_message or reply_to_message.
+description: Canonical AgentMail send-message API reference for swarm agents. Pins the base URL, required field names, text-only rendering workaround, BCC policy, and ready-to-copy curl / swarm-script examples so agents do not rediscover the API surface at runtime.
 user-invocable: false
 ---
 
-# AgentMail Sending Rules
+# AgentMail Sending
 
-These rules are MANDATORY for all agents sending email via AgentMail. Violating them will result in blank emails reaching real people.
+## Canonical Base URL
 
-## Rule 1: TEXT ONLY — Never Pass `html` Parameter
+Use this base URL exactly:
 
-**AgentMail has a critical bug (as of 2026-03-25):** When both `text` and `html` parameters are passed to `send_message` or `reply_to_message`, the HTML body content is silently dropped. The resulting email has an empty `<div dir="ltr"></div>`. Email clients (Gmail, etc.) prefer the HTML version over plain text, so recipients see a completely blank email.
+```text
+https://api.agentmail.to/v0/
+```
+
+DO NOT use `api.agentmail.ai`. That host is a hallucination and will not send mail through AgentMail's current API.
+
+## Canonical Send-Message Fields
+
+For `POST /inboxes/{inbox}/messages/send`, the JSON body fields are exactly:
+
+```text
+to
+bcc
+subject
+text
+```
+
+Use `text`, NOT `text_body`, `body`, or `content`.
+
+Do NOT pass `html`. AgentMail has a known rendering bug: when `html` is passed with `text`, the HTML body can be empty and email clients may show a blank email. AgentMail renders `text` correctly on its own.
+
+## Rule 0: One-Shots Stay One-Shots
+
+For a one-off send, such as a kickoff email or a single notification, do not create a reusable swarm-script. Use raw `curl` from Bash, or inline `script_run` if you need swarm-visible execution.
+
+Only use `script_upsert` when the send will be reused by a workflow that fires repeatedly.
+
+## Default Example: Raw curl
+
+Use this direct API call first. It does not assume any SDK is installed.
+
+Endpoint:
+
+```text
+https://api.agentmail.to/v0/inboxes/{inbox}/messages/send
+```
+
+```bash
+INBOX="<agentmail-inbox-id>"
+
+curl -sS -X POST "https://api.agentmail.to/v0/inboxes/${INBOX}/messages/send" \
+  -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
+  -H "Content-Type: application/json" \
+  --data-binary @- <<'JSON'
+{
+  "to": ["recipient@example.com"],
+  "bcc": ["oversight@example.com"],
+  "subject": "Subject line",
+  "text": "Plain-text email body."
+}
+JSON
+```
+
+Notes:
+
+- `AGENTMAIL_API_KEY` must be configured in swarm config or exported into the shell before running curl.
+- Keep `bcc` for external recipients so a human oversight inbox sees outbound email.
+- Do not add `html`; `text` is the canonical content field.
+
+## Reusable Workflow Example: script_upsert
+
+Use this only when the send is part of a reusable workflow. The script resolves the API key from swarm config at runtime and calls the same raw HTTP endpoint with `fetch`.
 
-**What to do:**
-- ONLY pass the `text` parameter
-- NEVER pass the `html` parameter
-- This applies to BOTH `send_message` and `reply_to_message`
+```ts
+await script_upsert({
+  name: "send-agentmail-text-email",
+  description: "Send a text-only AgentMail message from a reusable workflow.",
+  intent: "Reusable workflow email send via AgentMail raw API",
+  scope: "agent",
+  source: `
+import type { ScriptContext } from "swarm-sdk";
 
-**Why this matters:** This bug causes outbound emails to arrive completely blank, burning contacts permanently. It is not a cosmetic issue — it is a data loss / reputation issue.
+type Args = {
+  inbox: string;
+  to: string[];
+  bcc: string[];
+  subject: string;
+  text: string;
+};
 
-## Rule 2: BCC a Human Oversight Address on Outbound Emails
+export default async (args: Args, ctx: ScriptContext) => {
+  const redactedKey = ctx.swarm.config.get('AGENTMAIL_API_KEY');
+  if (!redactedKey) {
+    throw new Error("AGENTMAIL_API_KEY is not configured in swarm config");
+  }
 
-All outbound emails to external recipients MUST include a human oversight email address as BCC. This gives your team visibility into what the swarm is sending on your behalf.
+  const apiKey = ctx.stdlib.Redacted.value(redactedKey);
+  const response = await ctx.stdlib.fetch(
+    \`https://api.agentmail.to/v0/inboxes/\${encodeURIComponent(args.inbox)}/messages/send\`,
+    {
+      method: "POST",
+      headers: {
+        Authorization: \`Bearer \${apiKey}\`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        to: args.to,
+        bcc: args.bcc,
+        subject: args.subject,
+        text: args.text,
+      }),
+    },
+  );
 
-**Configure a BCC oversight address for your swarm** (e.g. a founder address, ops inbox, or shared team address):
+  const responseText = await response.text();
+  if (!response.ok) {
+    throw new Error(\`AgentMail send failed: \${response.status} \${responseText}\`);
+  }
 
+  return responseText ? JSON.parse(responseText) : { ok: true };
+};
+`,
+});
 ```
-send_message({
-  inboxId: "<your-agentmail-inbox-id>",
-  to: ["recipient@example.com"],
-  bcc: ["oversight@yourcompany.com"],
-  subject: "...",
-  text: "..."
-})
+
+Run it from a workflow with args shaped like:
+
+```json
+{
+  "inbox": "<agentmail-inbox-id>",
+  "to": ["recipient@example.com"],
+  "bcc": ["oversight@example.com"],
+  "subject": "Subject line",
+  "text": "Plain-text email body."
+}
 ```
 
-**Exception:** Internal emails between your swarm's own agent inboxes do NOT need BCC.
+## BCC Policy
+
+All outbound emails to external recipients MUST include a human oversight email address in `bcc`. This gives the operator visibility into what the swarm sends.
+
+Exception: internal emails between the swarm's own agent inboxes do not need BCC.
+
+## Human Approval
+
+Never send outreach or cold emails to external recipients without explicit human approval. Draft the email, present it for review, and send only after receiving approval.
+
+## Checklist
 
-## Rule 3: Human Approval Before Sending to External Recipients
+Before every AgentMail send:
 
-Never send outreach or cold emails to external recipients without explicit human approval. Draft the emails, present them for review, and only send after receiving "approved" or equivalent confirmation.
+- Use `https://api.agentmail.to/v0/`.
+- Use only `to`, `bcc`, `subject`, and `text` in the send-message JSON body.
+- Use `text`, not `text_body`, `body`, or `content`.
+- Do not pass `html`.
+- BCC a human oversight address for external recipients.
+- Get human approval for outreach or cold email.
+- Use raw `curl` or inline `script_run` for one-offs; reserve `script_upsert` for reusable workflow sends.
 
-## Summary Checklist
+## Common Errors
 
-Before every `send_message` or `reply_to_message` call:
-- [ ] Only `text` param, NO `html` param
-- [ ] BCC your oversight address if recipient is external
-- [ ] Human-approved if it is outreach/cold email
+| Symptom | Cause / fix |
+|---|---|
+| 404 on `/v0/inboxes/.../send` | Check the base URL. Use `api.agentmail.to`, not `api.agentmail.ai`. |
+| 422 `{"detail":"text Field required"}` | The request used `text_body` or `body` instead of `text`. |
+| 401 | `AGENTMAIL_API_KEY` is not configured in swarm config. In scripts, use `swarm.config.get('AGENTMAIL_API_KEY')`. |
+| HTML rendering bug | Do not pass `html` at all. AgentMail renders `text` correctly. |