@desplega.ai/agent-swarm 1.123.1 → 1.124.0

package/src/tests/sdk-allowlist.test.ts

@@ -9,7 +9,7 @@ import {
   mcpToolNameForSdkMethod,
   SDK_ALLOWLIST,
 } from "../scripts-runtime/sdk-allowlist";
-import type { SwarmConfig } from "../scripts-runtime/swarm-config";
+import { SwarmConfig } from "../scripts-runtime/swarm-config";
 import { createSwarmSdk } from "../scripts-runtime/swarm-sdk";
 import { createServer } from "../server";
 
@@ -65,6 +65,39 @@ describe("script SDK allowlist", () => {
     );
   });
 
+  test("workflow_listRuns sends bounded pagination defaults and rejects an excessive limit", async () => {
+    let requestUrl: URL | undefined;
+    const httpServer = Bun.serve({
+      port: 0,
+      fetch(req) {
+        requestUrl = new URL(req.url);
+        return Response.json({ runs: [], page: { limit: 20, offset: 0, total: 0 } });
+      },
+    });
+    const config = new SwarmConfig({
+      system: {
+        apiKey: { value: "sdk-test-key", isSecret: true },
+        agentId: { value: "sdk-test-agent", isSecret: false },
+        mcpBaseUrl: { value: `http://127.0.0.1:${httpServer.port}`, isSecret: false },
+      },
+      user: {},
+    });
+    const sdk = createSwarmSdk(config);
+
+    try {
+      await sdk.workflow_listRuns({ workflowId: "workflow-1" });
+      expect(requestUrl?.pathname).toBe("/api/workflows/workflow-1/runs");
+      expect(requestUrl?.searchParams.get("limit")).toBe("20");
+      expect(requestUrl?.searchParams.get("offset")).toBe("0");
+
+      await expect(sdk.workflow_listRuns({ workflowId: "workflow-1", limit: 101 })).rejects.toThrow(
+        "between 1 and 100",
+      );
+    } finally {
+      httpServer.stop(true);
+    }
+  });
+
   test("bundled swarm-sdk.d.ts exposes only allowlisted methods", async () => {
     const types = await Bun.file("src/scripts-runtime/types/swarm-sdk.d.ts").text();
     for (const name of SDK_ALLOWLIST) {

package/src/tests/seed-scripts.test.ts

@@ -14,6 +14,7 @@ import compoundInsights from "../be/seed-scripts/catalog/compound-insights";
 import opsCatalogAudit, {
   renderPage as renderOpsCatalogAuditPage,
 } from "../be/seed-scripts/catalog/ops-catalog-audit";
+import taskContextGathering from "../be/seed-scripts/catalog/task-context-gathering";
 import { extractScriptSignature } from "../scripts-runtime/extract-signature";
 import { validateScriptImports } from "../scripts-runtime/import-allowlist";
 
@@ -97,6 +98,48 @@ describe("seed-scripts catalog", () => {
     }
   });
 
+  test("task-context-gathering unwraps the direct REST task response", async () => {
+    const taskId = "task-context-test";
+    const result = await taskContextGathering(
+      { taskId, queries: ["task context"] },
+      {
+        swarm: {
+          async task_get(args: { taskId: string }) {
+            expect(args.taskId).toBe(taskId);
+            return {
+              success: true,
+              status: 200,
+              data: {
+                id: taskId,
+                status: "in_progress",
+                task: "Restore the flattened task response consumer",
+                dependsOn: ["parent-task"],
+                agentId: "agent-test",
+              },
+            };
+          },
+          async memory_search() {
+            return { success: true, status: 200, data: { results: [] } };
+          },
+        },
+      },
+    );
+
+    expect(result.task).toEqual({
+      id: taskId,
+      status: "in_progress",
+      description: "Restore the flattened task response consumer",
+      dependsOn: ["parent-task"],
+      slackChannelId: undefined,
+      slackThreadTs: undefined,
+      createdAt: undefined,
+      finishedAt: undefined,
+      agentId: "agent-test",
+      output: undefined,
+      failureReason: undefined,
+    });
+  });
+
   test("scriptsSeeder declares the script kind and one item per catalog entry", async () => {
     expect(scriptsSeeder.kind).toBe("script");
     const items = await scriptsSeeder.items();

package/src/tests/swarm-tool-result-gate.test.ts

@@ -214,6 +214,41 @@ describe("finalizeSwarmToolResult", () => {
     expect(text).toContain("[truncated");
   });
 
+  test("explicit details are normalized and capped identically in both channels", () => {
+    const blob = "x".repeat(50_000);
+    const result = finalizeSwarmToolResult("some-tool", {
+      ok: true,
+      message: "Big rendered payload.",
+      details: `  ${blob}  `,
+      data: { blob },
+    });
+    const text = (result.content?.[0] as { text: string }).text;
+    const structured = result.structuredContent as {
+      details?: string;
+      blob?: string;
+    };
+
+    expect(structured.details).toContain("[truncated");
+    expect(structured.details!.length).toBeLessThan(10_000);
+    expect(text).toBe(`Big rendered payload.\n\n${structured.details}`);
+    // Only the rendered details are bounded; callers using structured data
+    // still receive the complete payload.
+    expect(structured.blob).toBe(blob);
+  });
+
+  test("whitespace-only details fall back to a rendered data preview", () => {
+    const result = finalizeSwarmToolResult("some-tool", {
+      ok: true,
+      message: "Saved.",
+      details: " \n\t ",
+      data: { taskId: "t-whitespace" },
+    });
+    const text = (result.content?.[0] as { text: string }).text;
+
+    expect(text).toContain('"taskId": "t-whitespace"');
+    expect((result.structuredContent as { details?: string }).details).toBeUndefined();
+  });
+
   test("an explicit tool-provided nudge wins over the central map", () => {
     const result = finalizeSwarmToolResult("script-run", {
       ok: false,

package/src/tests/task-tools-ctx.test.ts

@@ -74,6 +74,35 @@ describe("task tool ctx", () => {
     expect(data.tasks.every((task) => task.task?.startsWith("owned task"))).toBe(true);
   });
 
+  test("getTasksHandler renders compact escaped markdown without changing structured tasks", async () => {
+    const user = createUser({ name: "Markdown List User" });
+    const taskText = "triage | path\\one\nsecond line";
+    const task = createTaskExtended(taskText, { requestedByUserId: user.id });
+
+    const result = await getTasksHandler(userCtx(user), {
+      includeFull: true,
+      includeHeartbeat: true,
+      limit: 50,
+    });
+
+    expect(result.details).toContain("| ID | Status | Priority | Agent | Task |");
+    expect(result.details).toContain("triage \\| path\\\\one<br>second line");
+    expect(result.details).not.toContain('"tasks":');
+    const data = result.data as { tasks: Array<{ id: string; task?: string }> };
+    expect(data.tasks.find((row) => row.id === task.id)?.task).toBe(taskText);
+  });
+
+  test("getTasksHandler uses a human empty-state instead of a raw data fallback", async () => {
+    const user = createUser({ name: "Empty List User" });
+    const result = await getTasksHandler(userCtx(user), {
+      includeHeartbeat: true,
+      limit: 50,
+    });
+
+    expect(result.details).toBe("No tasks matched the current filters.");
+    expect((result.data as { tasks: unknown[] }).tasks).toEqual([]);
+  });
+
   test("assertOwnsTask gates user tasks and allows owned or owner ctx", () => {
     const owner = createUser({ name: "Task Owner" });
     const foreignUser = createUser({ name: "Foreign User" });

package/src/tests/telemetry-init.test.ts

@@ -122,44 +122,25 @@ describe("initTelemetry", () => {
       expect(_getInstalledAtForTests()).toBeNull();
     });
 
-    test("backfill: telemetry_installed_at write fails → existing installationId is preserved, installedAt stays null", async () => {
-      const existing = "install_backfillfailure";
+    test("existing installationId, no stored anchor → installedAt omitted, no backfill write attempted (even with generateIfMissing)", async () => {
+      const existing = "install_noanchor";
       const writes: Array<{ key: string; value: string }> = [];
       await initTelemetry(
         "api-server",
         async (key) => (key === "telemetry_installation_id" ? existing : undefined),
         async (key, value) => {
-          if (key === "telemetry_installed_at") {
-            throw new Error("config write failed");
-          }
           writes.push({ key, value });
         },
         { generateIfMissing: true },
       );
-      // The pre-existing installation ID must survive the unrelated
-      // installed_at write failure — not get discarded for an ephemeral one.
+      // A pre-existing installation ID with no stored anchor must NOT mint
+      // now() as a stand-in install date — that back-fills a wrong date
+      // instead of an honestly-absent one. No write, no fabricated anchor.
       expect(_getInstallationIdForTests()).toBe(existing);
       expect(writes).toEqual([]);
       expect(_getInstalledAtForTests()).toBeNull();
     });
 
-    test("backfill: telemetry_installed_at write succeeds → mints and persists exactly once", async () => {
-      const existing = "install_backfillsuccess";
-      const writes: Array<{ key: string; value: string }> = [];
-      await initTelemetry(
-        "api-server",
-        async (key) => (key === "telemetry_installation_id" ? existing : undefined),
-        async (key, value) => {
-          writes.push({ key, value });
-        },
-        { generateIfMissing: true },
-      );
-      expect(_getInstallationIdForTests()).toBe(existing);
-      const installedAt = _getInstalledAtForTests();
-      expect(installedAt).not.toBeNull();
-      expect(writes).toEqual([{ key: "telemetry_installed_at", value: installedAt as string }]);
-    });
-
     test("already-exists: both installation_id and installed_at present → no writes, reuses existing anchor", async () => {
       const existing = "install_alreadyexists";
       const existingInstalledAt = "2026-01-01T00:00:00.000Z";
@@ -847,6 +828,22 @@ describe("initTelemetry", () => {
       expect(typeof metadata.install_created_at).toBe("string");
     });
 
+    test("pre-existing installationId with no stored anchor → install_created_at is absent from the payload, not back-filled with now()", async () => {
+      await initTelemetry(
+        "api-server",
+        async (key) =>
+          key === "telemetry_installation_id" ? "install_existingnoanchor" : undefined,
+        async () => {},
+        { generateIfMissing: true },
+      );
+
+      track({ event: "server.started", properties: {} });
+      await new Promise((r) => setTimeout(r, 0));
+
+      const metadata = (captured as { metadata: Record<string, unknown> }).metadata;
+      expect(metadata.install_created_at).toBeUndefined();
+    });
+
     test("wizard install: INSTALL_METHOD + INSTALL_PRESET flow through to properties/metadata", async () => {
       process.env.INSTALL_METHOD = "onboard_noninteractive";
       process.env.INSTALL_PRESET = "solo";

package/src/tests/workflow-http-v2.test.ts

@@ -11,12 +11,17 @@ import {
   closeDb,
   createWorkflowRun,
   createWorkflowRunStep,
+  getDb,
   getWorkflowVersions,
   initDb,
   updateWorkflowRun,
 } from "../be/db";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { handleWorkflows } from "../http/workflows";
+import {
+  listWorkflowRunsHandler,
+  listWorkflowRunsInputSchema,
+} from "../tools/workflows/list-workflow-runs";
 import type {
   Workflow,
   WorkflowDefinition,
@@ -549,6 +554,117 @@ describe("Workflow HTTP API v2", () => {
         expect(run.status).toBe("waiting");
       }
     });
+
+    test("supports deterministic limit/offset pages while preserving the omitted legacy shape", async () => {
+      const workflow = await createTestWorkflow();
+      const runIds = Array.from({ length: 5 }, () => crypto.randomUUID());
+      const statuses = ["running", "failed", "running", "failed", "running"] as const;
+
+      for (const [index, id] of runIds.entries()) {
+        createWorkflowRun({ id, workflowId: workflow.id });
+        getDb().run("UPDATE workflow_runs SET status = ?, startedAt = ? WHERE id = ?", [
+          statuses[index]!,
+          new Date(Date.UTC(2026, 0, index + 1)).toISOString(),
+          id,
+        ]);
+      }
+
+      const legacyRes = await fetch(`${baseUrl}/api/workflows/${workflow.id}/runs`, { headers });
+      expect(legacyRes.status).toBe(200);
+      const legacyBody = (await legacyRes.json()) as WorkflowRun[];
+      expect(Array.isArray(legacyBody)).toBe(true);
+      expect(legacyBody.map((run) => run.id)).toEqual([...runIds].reverse());
+
+      const pageRes = await fetch(`${baseUrl}/api/workflows/${workflow.id}/runs?limit=2&offset=1`, {
+        headers,
+      });
+      expect(pageRes.status).toBe(200);
+      const pageBody = (await pageRes.json()) as {
+        runs: WorkflowRun[];
+        page: {
+          limit: number;
+          offset: number;
+          total: number;
+          hasMore: boolean;
+          nextOffset?: number;
+        };
+      };
+      expect(pageBody.runs.map((run) => run.id)).toEqual([runIds[3], runIds[2]]);
+      expect(pageBody.page).toEqual({
+        limit: 2,
+        offset: 1,
+        total: 5,
+        hasMore: true,
+        nextOffset: 3,
+      });
+
+      const filteredRes = await fetch(
+        `${baseUrl}/api/workflows/${workflow.id}/runs?status=failed&limit=1`,
+        { headers },
+      );
+      expect(filteredRes.status).toBe(200);
+      const filteredBody = (await filteredRes.json()) as {
+        runs: WorkflowRun[];
+        page: { total: number };
+      };
+      expect(filteredBody.runs.map((run) => run.id)).toEqual([runIds[3]]);
+      expect(filteredBody.page.total).toBe(2);
+
+      const invalidRes = await fetch(`${baseUrl}/api/workflows/${workflow.id}/runs?limit=101`, {
+        headers,
+      });
+      expect(invalidRes.status).toBe(400);
+    });
+
+    test("MCP run listing defaults to bounded slim rows and preserves an explicit full-row opt-in", async () => {
+      const workflow = await createTestWorkflow();
+      const largeValue = "x".repeat(100_000);
+      const run = createWorkflowRun({
+        id: crypto.randomUUID(),
+        workflowId: workflow.id,
+        triggerData: { largeValue },
+      });
+      updateWorkflowRun(run.id, { context: { nodeOutput: largeValue } });
+      const parsed = listWorkflowRunsInputSchema.parse({ workflowId: workflow.id });
+      expect(parsed.limit).toBe(20);
+      expect(parsed.offset).toBe(0);
+      expect(parsed.includeContext).toBe(false);
+      expect(() =>
+        listWorkflowRunsInputSchema.parse({ workflowId: workflow.id, limit: 101 }),
+      ).toThrow();
+
+      const result = listWorkflowRunsHandler(parsed);
+      expect(result.ok).toBe(true);
+      const data = result.data as {
+        runs: Array<{
+          id: string;
+          context?: unknown;
+          triggerData?: unknown;
+          triggerDataSummary?: string;
+        }>;
+        page: { limit: number; offset: number; total: number; hasMore: boolean };
+      };
+      expect(data.runs.map((row) => row.id)).toEqual([run.id]);
+      expect(data.runs[0]!.context).toBeUndefined();
+      expect(data.runs[0]!.triggerData).toBeUndefined();
+      expect(data.runs[0]!.triggerDataSummary).toEndWith("…");
+      expect(data.runs[0]!.triggerDataSummary!.length).toBe(401);
+      expect(data.page).toEqual({
+        limit: 20,
+        offset: 0,
+        total: 1,
+        hasMore: false,
+      });
+      expect(JSON.stringify(result).length).toBeLessThan(20_000);
+
+      const fullResult = listWorkflowRunsHandler({
+        ...parsed,
+        includeContext: true,
+      });
+      const fullData = fullResult.data as { runs: WorkflowRun[] };
+      expect(fullData.runs[0]!.context).toEqual({ nodeOutput: largeValue });
+      expect(fullData.runs[0]!.triggerData).toEqual({ largeValue });
+    });
   });
 
   // ─── GET RUN DETAIL ────────────────────────────────────────

package/src/tools/get-tasks.ts

@@ -79,6 +79,45 @@ export const getTasksOutputSchema = swarmToolOutputSchema({
 
 type GetTasksArgs = z.infer<typeof getTasksInputSchema>;
 
+const TASK_DETAILS_CELL_CAP = 180;
+
+function escapeMarkdownCell(value: unknown): string {
+  const text = String(value ?? "—");
+  const compact =
+    text.length > TASK_DETAILS_CELL_CAP ? `${text.slice(0, TASK_DETAILS_CELL_CAP - 1)}…` : text;
+  return compact
+    .replaceAll("\\", "\\\\")
+    .replaceAll("|", "\\|")
+    .replace(/\r\n|\r|\n/g, "<br>");
+}
+
+function renderTaskSummaries(
+  tasks: Array<{
+    id?: string;
+    agentId?: string | null;
+    task?: string;
+    taskPreview?: string;
+    status?: string;
+    priority?: number;
+  }>,
+): string {
+  if (tasks.length === 0) return "No tasks matched the current filters.";
+
+  const header = "| ID | Status | Priority | Agent | Task |";
+  const separator = "| --- | --- | ---: | --- | --- |";
+  const rows = tasks.map((task) => {
+    const cells = [
+      task.id,
+      task.status,
+      task.priority,
+      task.agentId,
+      task.taskPreview ?? task.task,
+    ].map(escapeMarkdownCell);
+    return `| ${cells.join(" | ")} |`;
+  });
+  return [header, separator, ...rows].join("\n");
+}
+
 export async function getTasksHandler(
   ctx: ToolCtx,
   {
@@ -163,7 +202,7 @@ export async function getTasksHandler(
   };
 
   return toolOk(`Found ${taskSummaries.length} task(s)${filterMsg}.`, {
-    details: JSON.stringify(data),
+    details: renderTaskSummaries(taskSummaries),
     data,
   });
 }

package/src/tools/script-run.ts

@@ -10,7 +10,7 @@ import {
 } from "./script-common";
 
 export const SCRIPT_RUN_DESCRIPTION =
-  "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.";
+  "Run a named swarm-shared script (callable across agents and from workflow `swarm-script` nodes), OR inline source (auto-saved as scratch to the catalog). Inline source executes without the `script-upsert` compile-time typecheck. Use for swarm-visible, durable scripts. For local-only throwaway TS, use code-mode `run`.";
 
 function renderRunOutput(data: unknown): string | undefined {
   if (typeof data !== "object" || data === null) return undefined;
@@ -58,7 +58,7 @@ export const registerScriptRunTool = (server: McpServer) => {
           .min(1)
           .optional()
           .describe(
-            "Inline TypeScript source to run. Must `export default async function (args, ctx)` — args FIRST, ctx second.",
+            'Inline TypeScript source to run without a compile-time typecheck. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" for promotion-safe typing.',
           ),
         args: z.unknown().optional().describe("JSON-serializable script arguments."),
         intent: z.string().default("").describe("Why this script is being run."),

package/src/tools/script-upsert.ts

@@ -10,7 +10,7 @@ import {
 } from "./script-common";
 
 export const SCRIPT_UPSERT_DESCRIPTION =
-  "Persist a TypeScript script to the swarm catalog under your agent scope (or global if you're a lead). Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.";
+  'Typecheck and persist a TypeScript script to the swarm catalog under your agent scope (or global if you\'re a lead). Import `ScriptContext` from "swarm-sdk" for a real context type. Other agents and workflow nodes will be able to find and run it. For local-only scripts, use code-mode `save`.';
 
 export const registerScriptUpsertTool = (server: McpServer) => {
   createToolRegistrar(server)(
@@ -25,7 +25,7 @@ export const registerScriptUpsertTool = (server: McpServer) => {
           .string()
           .min(1)
           .describe(
-            "TypeScript source. Must `export default async function (args, ctx)` — args FIRST, ctx second.",
+            'TypeScript source, typechecked before saving. Must `export default async function (args, ctx)` — args FIRST, ctx second. Import `ScriptContext` from "swarm-sdk" to type `ctx`.',
           ),
         description: z.string().default("").describe("Human-readable script description."),
         intent: z.string().default("").describe("Why this script exists."),

package/src/tools/utils.ts

@@ -189,13 +189,14 @@ export const NUDGES: Record<string, (result: SwarmToolResult) => string | undefi
   },
 };
 
-// Cap for the auto-rendered data fallback in the text channel — Codex's
-// ~10KB middle-out truncation is the tightest harness budget.
-const DATA_FALLBACK_CAP = 8_000;
+// Cap for any rendered details string — Codex's ~10KB middle-out truncation is
+// the tightest harness budget. Structured data remains intact; only the
+// human/model-facing rendering is bounded.
+const DETAILS_CAP = 8_000;
 
 function truncateForText(text: string): string {
-  if (text.length <= DATA_FALLBACK_CAP) return text;
-  return `${text.slice(0, DATA_FALLBACK_CAP)}\n… [truncated ${text.length - DATA_FALLBACK_CAP} chars]`;
+  if (text.length <= DETAILS_CAP) return text;
+  return `${text.slice(0, DETAILS_CAP)}\n… [truncated ${text.length - DETAILS_CAP} chars]`;
 }
 
 type FinalizeContext = { toolName: string };
@@ -235,17 +236,22 @@ export function finalizeSwarmToolResult(toolName: string, result: SwarmToolResul
   }
   for (const middleware of FINALIZE_PIPELINE) r = middleware(r, { toolName });
 
+  // Normalize and cap explicit details only after the scrub middleware has
+  // removed secrets. The same bounded value feeds both wire channels.
+  // Whitespace-only details count as absent so data fallback remains visible.
+  const explicitDetails = r.details?.trim() ? truncateForText(r.details.trim()) : undefined;
+
   // Text-channel completeness guarantee: when a tool sets data but no details,
   // render the data as JSON into the text channel. Most harnesses only ever
   // show the model content.text — without this fallback, a data-only payload
   // would be invisible there. Not copied into structuredContent.details (the
   // structured channel already carries data verbatim).
   const dataFallback =
-    !r.details?.trim() && r.data && Object.keys(r.data).length > 0
+    !explicitDetails && r.data && Object.keys(r.data).length > 0
       ? truncateForText(JSON.stringify(r.data, null, 2))
       : undefined;
 
-  const text = [r.message, r.details ?? dataFallback, r.nudge]
+  const text = [r.message, explicitDetails ?? dataFallback, r.nudge]
     .filter((part): part is string => Boolean(part?.trim()))
     .join("\n\n");
   const structuredContent: Record<string, unknown> = {
@@ -253,7 +259,7 @@ export function finalizeSwarmToolResult(toolName: string, result: SwarmToolResul
     success: r.ok,
     message: r.message,
   };
-  if (r.details) structuredContent.details = r.details;
+  if (explicitDetails) structuredContent.details = explicitDetails;
   if (r.nudge) structuredContent.nudge = r.nudge;
 
   return {