@desplega.ai/agent-swarm 1.89.0 → 1.91.0

package/src/tests/profile-sync.test.ts

@@ -0,0 +1,282 @@
+import { describe, expect, spyOn, test } from "bun:test";
+import {
+  buildIdentityPayload,
+  CLAUDE_MD_PATH,
+  collectProfilePayloads,
+  extractSetupScriptContent,
+  type FileReader,
+  IDENTITY_MD_PATH,
+  postProfileUpdate,
+  resolveClaudeMdPath,
+  SETUP_SCRIPT_PATH,
+  SOUL_MD_PATH,
+  syncProfileFilesToServer,
+  TOOLS_MD_PATH,
+  WORKSPACE_CLAUDE_MD_PATH,
+} from "../commands/profile-sync";
+
+const MARKER_START = "# === Agent-managed setup (from DB) ===";
+const MARKER_END = "# === End agent-managed setup ===";
+
+// A SOUL/IDENTITY body long enough to clear the 500-char min-length guard.
+const LONG = "x".repeat(600);
+
+describe("extractSetupScriptContent (marker extraction)", () => {
+  test("extracts ONLY the content between the agent-managed markers", () => {
+    const raw = [
+      "#!/bin/bash",
+      "echo operator-prelude",
+      MARKER_START,
+      "export FOO=bar",
+      'echo "agent line"',
+      MARKER_END,
+      "echo operator-postlude",
+    ].join("\n");
+
+    expect(extractSetupScriptContent(raw)).toBe('export FOO=bar\necho "agent line"');
+  });
+
+  test("strips a leading shebang when no markers are present", () => {
+    const raw = '#!/bin/bash\necho "whole file is agent-managed"';
+    expect(extractSetupScriptContent(raw)).toBe('echo "whole file is agent-managed"');
+  });
+
+  test("returns null for an empty / whitespace-only file", () => {
+    expect(extractSetupScriptContent("")).toBeNull();
+    expect(extractSetupScriptContent("   \n\t ")).toBeNull();
+  });
+
+  test("returns null when the marker section is empty", () => {
+    const raw = `prelude\n${MARKER_START}\n   \n${MARKER_END}\npostlude`;
+    expect(extractSetupScriptContent(raw)).toBeNull();
+  });
+
+  test("returns null when content exceeds the max length", () => {
+    const raw = `${MARKER_START}\n${"a".repeat(65537)}\n${MARKER_END}`;
+    expect(extractSetupScriptContent(raw)).toBeNull();
+  });
+});
+
+describe("buildIdentityPayload (min-length guard)", () => {
+  test("includes SOUL/IDENTITY only when they clear the 500-char minimum", () => {
+    const errSpy = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const ok = buildIdentityPayload({ soulMd: LONG, identityMd: LONG });
+      expect(ok.soulMd).toBe(LONG);
+      expect(ok.identityMd).toBe(LONG);
+
+      const short = buildIdentityPayload({ soulMd: "too short", identityMd: "also short" });
+      expect(short.soulMd).toBeUndefined();
+      expect(short.identityMd).toBeUndefined();
+      // The guard must be VISIBLE — it logs why it skipped.
+      expect(errSpy).toHaveBeenCalled();
+    } finally {
+      errSpy.mockRestore();
+    }
+  });
+
+  test("TOOLS.md has no min-length guard (any non-empty content syncs)", () => {
+    const payload = buildIdentityPayload({ toolsMd: "short tools" });
+    expect(payload.toolsMd).toBe("short tools");
+  });
+
+  test("HEARTBEAT.md syncs even when empty (no trim/min-length guard)", () => {
+    const payload = buildIdentityPayload({ heartbeatMd: "" });
+    expect(payload.heartbeatMd).toBe("");
+  });
+
+  test("skips files that exceed the max length", () => {
+    const huge = "z".repeat(65537);
+    const payload = buildIdentityPayload({ soulMd: huge, toolsMd: huge });
+    expect(payload.soulMd).toBeUndefined();
+    expect(payload.toolsMd).toBeUndefined();
+  });
+
+  test("absent files (undefined) produce no keys", () => {
+    expect(buildIdentityPayload({})).toEqual({});
+  });
+});
+
+describe("collectProfilePayloads (field gate)", () => {
+  const reader = (files: Record<string, string>): FileReader => {
+    return async (path: string) => files[path];
+  };
+
+  test("only the selected field group is collected", async () => {
+    const files = reader({
+      [SOUL_MD_PATH]: LONG,
+      [IDENTITY_MD_PATH]: LONG,
+      [TOOLS_MD_PATH]: "tools",
+      [CLAUDE_MD_PATH]: "claude md content",
+      [SETUP_SCRIPT_PATH]: `${MARKER_START}\nexport X=1\n${MARKER_END}`,
+    });
+
+    const setupOnly = await collectProfilePayloads(["setup"], "session_sync", files);
+    expect(setupOnly.map((p) => p.label)).toEqual(["setup"]);
+    expect(setupOnly[0]?.body).toEqual({ setupScript: "export X=1", changeSource: "session_sync" });
+
+    const claudeOnly = await collectProfilePayloads(["claude"], "session_sync", files);
+    expect(claudeOnly.map((p) => p.label)).toEqual(["claude"]);
+
+    const all = await collectProfilePayloads(
+      ["identity", "claude", "setup"],
+      "session_sync",
+      files,
+    );
+    expect(all.map((p) => p.label).sort()).toEqual(["claude", "identity", "setup"]);
+  });
+
+  test("a missing file yields no payload for that group (no empty POST)", async () => {
+    const files = reader({}); // nothing on disk
+    const payloads = await collectProfilePayloads(
+      ["identity", "claude", "setup"],
+      "session_sync",
+      files,
+    );
+    expect(payloads).toEqual([]);
+  });
+
+  test("propagates the changeSource into every body", async () => {
+    const files = reader({ [TOOLS_MD_PATH]: "tools" });
+    const payloads = await collectProfilePayloads(["identity"], "self_edit", files);
+    expect(payloads[0]?.body.changeSource).toBe("self_edit");
+  });
+
+  test("non-Claude providers sync /workspace/CLAUDE.md, not the personal file", async () => {
+    // A codex/pi/opencode session edits the runner-materialized workspace file;
+    // the Claude personal file (~/.claude/CLAUDE.md) is absent for them.
+    const files = reader({ [WORKSPACE_CLAUDE_MD_PATH]: "workspace claude md edit" });
+
+    const payloads = await collectProfilePayloads(
+      ["claude"],
+      "session_sync",
+      files,
+      WORKSPACE_CLAUDE_MD_PATH,
+    );
+    expect(payloads.map((p) => p.label)).toEqual(["claude"]);
+    expect(payloads[0]?.body).toEqual({
+      claudeMd: "workspace claude md edit",
+      changeSource: "session_sync",
+    });
+  });
+
+  test("Claude's default path never reads the workspace materialization", async () => {
+    // Guard against reverting a real Claude personal-file edit: with the default
+    // (personal-file) path, content sitting only at /workspace/CLAUDE.md — the
+    // stale boot materialization — must NOT be picked up as a claude payload.
+    const files = reader({ [WORKSPACE_CLAUDE_MD_PATH]: "stale workspace materialization" });
+
+    const payloads = await collectProfilePayloads(["claude"], "session_sync", files);
+    expect(payloads).toEqual([]);
+  });
+});
+
+describe("resolveClaudeMdPath (per-batch provider routing)", () => {
+  test("an all-Claude batch uses the personal-file path (Stop-hook backstop)", () => {
+    expect(resolveClaudeMdPath(["claude"])).toBe(CLAUDE_MD_PATH);
+    expect(resolveClaudeMdPath(["claude", "claude"])).toBe(CLAUDE_MD_PATH);
+  });
+
+  test("any non-Claude local session routes to the workspace file", () => {
+    expect(resolveClaudeMdPath(["codex"])).toBe(WORKSPACE_CLAUDE_MD_PATH);
+    expect(resolveClaudeMdPath(["pi"])).toBe(WORKSPACE_CLAUDE_MD_PATH);
+    expect(resolveClaudeMdPath(["opencode"])).toBe(WORKSPACE_CLAUDE_MD_PATH);
+    // Mixed batch: a non-Claude edit means the workspace file is authoritative.
+    expect(resolveClaudeMdPath(["claude", "codex"])).toBe(WORKSPACE_CLAUDE_MD_PATH);
+  });
+});
+
+describe("postProfileUpdate (non-2xx is surfaced, not swallowed)", () => {
+  const opts = {
+    agentId: "agent-1",
+    apiUrl: "https://api.example.test",
+    apiKey: "secret-key",
+  };
+  const payload = {
+    label: "setup",
+    body: { setupScript: "export X=1", changeSource: "session_sync" },
+  };
+
+  test("a successful 2xx response logs no warning", async () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const fetchImpl = (async () => new Response("{}", { status: 200 })) as typeof fetch;
+    try {
+      await postProfileUpdate({ ...opts, fetchImpl }, payload);
+      expect(warnSpy).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("a non-2xx response surfaces a warning but does NOT throw", async () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const fetchImpl = (async () =>
+      new Response("boom", { status: 500, statusText: "Server Error" })) as typeof fetch;
+    try {
+      // Must resolve (non-fatal), not reject.
+      await expect(postProfileUpdate({ ...opts, fetchImpl }, payload)).resolves.toBeUndefined();
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const msg = String(warnSpy.mock.calls[0]?.[0]);
+      expect(msg).toContain("setup sync failed");
+      expect(msg).toContain("500");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("a thrown fetch error surfaces a warning but does NOT throw", async () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const fetchImpl = (async () => {
+      throw new Error("network down");
+    }) as typeof fetch;
+    try {
+      await expect(postProfileUpdate({ ...opts, fetchImpl }, payload)).resolves.toBeUndefined();
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(String(warnSpy.mock.calls[0]?.[0])).toContain("setup sync errored");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  test("sends a PUT to the profile route with auth + agent headers", async () => {
+    let capturedUrl = "";
+    let capturedInit: RequestInit | undefined;
+    const fetchImpl = (async (url: string | URL | Request, init?: RequestInit) => {
+      capturedUrl = String(url);
+      capturedInit = init;
+      return new Response("{}", { status: 200 });
+    }) as typeof fetch;
+
+    await postProfileUpdate({ ...opts, fetchImpl }, payload);
+
+    expect(capturedUrl).toBe("https://api.example.test/api/agents/agent-1/profile");
+    expect(capturedInit?.method).toBe("PUT");
+    const headers = capturedInit?.headers as Record<string, string>;
+    expect(headers.Authorization).toBe("Bearer secret-key");
+    expect(headers["X-Agent-ID"]).toBe("agent-1");
+    expect(JSON.parse(String(capturedInit?.body))).toEqual(payload.body);
+  });
+});
+
+describe("syncProfileFilesToServer (orchestration is non-fatal)", () => {
+  test("resolves without throwing even when every POST fails", async () => {
+    const warnSpy = spyOn(console, "warn").mockImplementation(() => {});
+    const errSpy = spyOn(console, "error").mockImplementation(() => {});
+    const fetchImpl = (async () => new Response("nope", { status: 503 })) as typeof fetch;
+    try {
+      await expect(
+        syncProfileFilesToServer({
+          agentId: "agent-1",
+          apiUrl: "https://api.example.test",
+          apiKey: "secret-key",
+          changeSource: "session_sync",
+          // No files on a CI box → typically no payloads; still must never throw.
+          fetchImpl,
+        }),
+      ).resolves.toBeUndefined();
+    } finally {
+      warnSpy.mockRestore();
+      errSpy.mockRestore();
+    }
+  });
+});

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

@@ -288,6 +288,39 @@ describe("runScript", () => {
     }
   });
 
+  test("zod import works in compiled binary mode (SCRIPT_RUNTIME_DIR)", async () => {
+    const tmpdir = `${process.env.TMPDIR ?? "/tmp"}/script-runtime-test-${crypto.randomUUID()}`;
+    await Bun.$`mkdir -p ${tmpdir}`;
+    try {
+      const runtimeSrc = new URL("../scripts-runtime", import.meta.url).pathname;
+      await Bun.$`bun build ${runtimeSrc}/eval-harness.ts --target bun --no-splitting --outfile ${tmpdir}/eval-harness.bundle.js`.quiet();
+      await Bun.$`bun build ${runtimeSrc}/stdlib/index.ts --target bun --no-splitting --outfile ${tmpdir}/stdlib.bundle.js`.quiet();
+      await Bun.$`bun build ${runtimeSrc}/swarm-sdk.ts --target bun --no-splitting --outfile ${tmpdir}/swarm-sdk.bundle.js`.quiet();
+      const zodEntry = Bun.resolveSync("zod", import.meta.dir);
+      await Bun.$`bun build ${zodEntry} --target bun --no-splitting --outfile ${tmpdir}/zod.bundle.js`.quiet();
+
+      process.env.SCRIPT_RUNTIME_DIR = tmpdir;
+
+      const output = await runScript({
+        agentId: "agent-1",
+        args: { name: "test" },
+        resources,
+        source: `
+          import { z } from "zod";
+          export const argsSchema = z.object({ name: z.string() });
+          export default async (args: z.infer<typeof argsSchema>) => ({ greeting: "hello " + args.name });
+        `,
+      });
+
+      expect(output.error).toBeUndefined();
+      expect(output.result).toEqual({ greeting: "hello test" });
+      expect(output.exitCode).toBe(0);
+    } finally {
+      delete process.env.SCRIPT_RUNTIME_DIR;
+      await Bun.$`rm -rf ${tmpdir}`;
+    }
+  });
+
   test("argsSchema rejects invalid args with a formatted Zod error", async () => {
     const output = await runScript({
       agentId: "agent-1",

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

@@ -48,8 +48,8 @@ afterAll(async () => {
 });
 
 describe("seed-scripts catalog", () => {
-  test("manifest holds 10 unique, well-described scripts", () => {
-    expect(SEED_SCRIPTS.length).toBe(10);
+  test("manifest holds 14 unique, well-described scripts", () => {
+    expect(SEED_SCRIPTS.length).toBe(14);
     const names = SEED_SCRIPTS.map((s) => s.name);
     expect(new Set(names).size).toBe(names.length);
     for (const s of SEED_SCRIPTS) {

package/src/tools/create-metric.ts

@@ -5,6 +5,7 @@ import { assertSelectOnlyQuery } from "@/http/db-query";
 import { snapshotMetric } from "@/metrics/version";
 import { createToolRegistrar } from "@/tools/utils";
 import { MetricDefinitionSchema } from "@/types";
+import { getAppUrl } from "@/utils/constants";
 
 function slugify(input: string): string {
   const slug = input
@@ -16,9 +17,7 @@ function slugify(input: string): string {
 }
 
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl();
 }
 
 function metricEditCounter(metricId: string): number {

package/src/tools/create-page.ts

@@ -23,6 +23,7 @@ import { createPage, getPage, getPageBySlug, getPageVersions, updatePage } from
 import { snapshotPage } from "@/pages/version";
 import { createToolRegistrar } from "@/tools/utils";
 import { PageAuthModeSchema, PageContentTypeSchema } from "@/types";
+import { getAppUrl, getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Same slugifier used by the HTTP createPage handler. */
 function slugify(input: string): string {
@@ -35,15 +36,11 @@ function slugify(input: string): string {
 }
 
 function getApiBaseUrl(): string {
-  const env = process.env.MCP_BASE_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return `http://localhost:${process.env.PORT || "3013"}`;
+  return getPublicMcpBaseUrl();
 }
 
 function getAppBaseUrl(): string {
-  const env = process.env.APP_URL?.trim();
-  if (env) return env.replace(/\/+$/, "");
-  return "http://localhost:5274";
+  return getAppUrl();
 }
 
 /**

package/src/tools/memory-rate.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { REFERENCES_SOURCE_MAX_LENGTH, sanitizeReferencesSource } from "@/be/memory/raters/types";
 import { createToolRegistrar } from "@/tools/utils";
 import { getApiKey } from "@/utils/api-key";
+import { getMcpBaseUrl } from "@/utils/constants";
 
 /**
  * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-5.md §1
@@ -92,7 +93,7 @@ export const registerMemoryRateTool = (server: McpServer) => {
         cleanedReferencesSource = cleaned;
       }
 
-      const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
+      const apiUrl = getMcpBaseUrl();
       const apiKey = getApiKey();
 
       const event = {

package/src/tools/memory-search.ts

@@ -125,6 +125,7 @@ export const registerMemorySearchTool = (server: McpServer) => {
         scope: scope as "agent" | "swarm" | "all",
         limit,
         isLead,
+        source,
       });
 
       const mapped = recent.map((r) => ({

package/src/tools/register-kapso-number.ts

@@ -10,13 +10,11 @@ import {
   putKapsoNumberMapping,
 } from "@/integrations/kapso/config";
 import { createToolRegistrar } from "@/tools/utils";
+import { getPublicMcpBaseUrl } from "@/utils/constants";
 
 /** Build the native inbound webhook URL the swarm exposes for Kapso deliveries. */
 function nativeWebhookUrl(): string {
-  const base = (
-    process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`
-  ).replace(/\/+$/, "");
-  return `${base}/api/integrations/kapso/webhook`;
+  return `${getPublicMcpBaseUrl()}/api/integrations/kapso/webhook`;
 }
 
 export const registerRegisterKapsoNumberTool = (server: McpServer) => {

package/src/tools/request-human-input.ts

@@ -2,6 +2,7 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { createApprovalRequest, getAgentCurrentTask } from "@/be/db";
 import { createToolRegistrar } from "@/tools/utils";
+import { getAppUrl } from "@/utils/constants";
 
 const QuestionSchema = z.object({
   id: z.string().describe("Unique ID for the question (used as key in responses)"),
@@ -94,7 +95,7 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
         timeoutSeconds,
       });
 
-      const appUrl = process.env.APP_URL || "http://localhost:5274";
+      const appUrl = getAppUrl();
       const url = `${appUrl}/approval-requests/${request.id}`;
 
       return {

package/src/tools/script-common.ts

@@ -1,6 +1,7 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import * as z from "zod";
 import { getApiKey } from "@/utils/api-key";
+import { getMcpBaseUrl } from "@/utils/constants";
 import type { RequestInfo } from "./utils";
 
 export const SCRIPT_TRANSPORT_ERROR =
@@ -20,10 +21,7 @@ export const scriptToolOutputSchema = z.object({
 export type ScriptToolStructuredContent = z.infer<typeof scriptToolOutputSchema>;
 
 function apiBaseUrl(): string {
-  return (process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`).replace(
-    /\/+$/,
-    "",
-  );
+  return getMcpBaseUrl();
 }
 
 function toolError(message: string, status = 400): CallToolResult {

package/src/tools/script-run.ts

@@ -28,6 +28,13 @@ export const registerScriptRunTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        idempotencyKey: z
+          .string()
+          .max(200)
+          .optional()
+          .describe(
+            "When set, output is auto-persisted to kv under script:executions/{key}. Re-running with the same key overwrites. Queryable via kv-get.",
+          ),
       }),
       outputSchema: scriptToolOutputSchema,
     },

package/src/utils/constants.ts

@@ -3,19 +3,69 @@
  */
 
 /**
- * Default dashboard URL used when `APP_URL` is unset. Points at the public
- * production dashboard so links (Slack messages, approval URLs, etc.) are
- * always renderable. Self-hosted operators should set `APP_URL` to override.
+ * Default dashboard URL used when neither `APP_URL` nor the deprecated
+ * `DASHBOARD_URL` is set. Points at the public production dashboard so links
+ * (Slack messages, approval URLs, page share links, post-OAuth redirects)
+ * stay renderable even when an operator forgets to configure it. Local dev
+ * should set `APP_URL` (e.g. in `.env`) to point at the local dashboard.
  */
 export const DEFAULT_APP_URL = "https://app.agent-swarm.dev";
 
 /**
- * Resolve the effective app/dashboard URL from `APP_URL` (with trailing
- * slashes stripped), falling back to {@link DEFAULT_APP_URL}.
+ * Resolve every explicitly configured app/dashboard URL. Each env var may be
+ * a comma-separated origin list; entries are returned in precedence order with
+ * trailing slashes stripped.
+ *
+ * Precedence: `APP_URL` entries → `DASHBOARD_URL` entries (deprecated alias,
+ * kept for back-compat).
+ */
+export function getConfiguredAppUrls(): string[] {
+  return [process.env.APP_URL, process.env.DASHBOARD_URL]
+    .flatMap((value) => (value ?? "").split(","))
+    .map((value) => value.trim().replace(/\/+$/, ""))
+    .filter(Boolean);
+}
+
+/**
+ * Resolve the effective app/dashboard URL — the public origin the user's
+ * browser is sent to (post-login redirects, Slack/approval links, page
+ * `app_url` share links). Trailing slashes are stripped.
+ *
+ * Precedence: first configured `APP_URL` entry → first configured
+ * `DASHBOARD_URL` entry (deprecated alias, kept for back-compat) → fallback.
+ * This is the single source of truth; call sites must not re-read
+ * `APP_URL`/`DASHBOARD_URL` directly.
+ */
+export function getAppUrl(fallback = DEFAULT_APP_URL): string {
+  return (getConfiguredAppUrls()[0] || fallback).replace(/\/+$/, "");
+}
+
+/**
+ * Internal API/MCP base URL — how workers/agents and in-process callers reach
+ * the API server. May be a private/cluster address (e.g. the Helm ClusterIP
+ * `http://<release>-api:3013`). Do NOT use for browser-facing or
+ * externally-registered URLs (OAuth redirect URIs, webhook URLs): those must
+ * resolve to a host the browser / third party can reach — use
+ * {@link getPublicMcpBaseUrl} (no request context) or `deriveApiBaseUrl(req)`
+ * (request-scoped) instead. Trailing slashes are stripped.
+ */
+export function getMcpBaseUrl(): string {
+  const raw = process.env.MCP_BASE_URL?.trim();
+  return (raw || `http://localhost:${process.env.PORT || "3013"}`).replace(/\/+$/, "");
+}
+
+/**
+ * Public, browser-/externally-reachable origin of the API server — where
+ * `/api/mcp-oauth/callback`, OAuth redirect URIs, and registered webhook URLs
+ * resolve. Falls back to {@link getMcpBaseUrl} when the public and internal
+ * hosts are the same (local dev, single-box, or an ngrok/tunnel set as
+ * `MCP_BASE_URL`). In split deployments (Helm), set `PUBLIC_MCP_BASE_URL` to
+ * the public ingress URL while `MCP_BASE_URL` stays the internal service
+ * address. Trailing slashes are stripped.
  */
-export function getAppUrl(): string {
-  const raw = process.env.APP_URL?.trim();
-  return (raw || DEFAULT_APP_URL).replace(/\/+$/, "");
+export function getPublicMcpBaseUrl(): string {
+  const raw = process.env.PUBLIC_MCP_BASE_URL?.trim();
+  return raw ? raw.replace(/\/+$/, "") : getMcpBaseUrl();
 }
 
 /**

package/templates/skills/swarm-scripts/content.md

@@ -32,16 +32,18 @@ Use `script-query-types` before non-trivial work so the script matches the live
 Use `script-run` with inline source for one-off work:
 
 ```typescript
-export default async function main(args: { status: string; limit: number }, ctx) {
+export default async function main(args: any, ctx: any) {
   const { swarm, logger } = ctx;
-  const result = await swarm.task_list({ status: args.status, limit: args.limit });
-  logger.info(`Fetched ${result.tasks.length} tasks`);
+  // All SDK methods return Promise<unknown> — unwrap defensively.
+  const res: any = await swarm.task_list({ status: args?.status, limit: args?.limit ?? 50 });
+  const tasks: any[] = res?.data?.tasks ?? res?.tasks ?? [];
+  logger.info(`Fetched ${tasks.length} tasks`);
   return {
-    total: result.tasks.length,
-    tasks: result.tasks.map((task) => ({
+    total: tasks.length,
+    tasks: tasks.map((task: any) => ({
       id: task.id,
       status: task.status,
-      title: task.task.slice(0, 120),
+      title: task.task?.slice(0, 120),
     })),
   };
 }
@@ -60,8 +62,45 @@ Good named scripts:
 - Fan out over many swarm tasks, memories, repos, or schedules.
 - Convert noisy JSON or HTML into a compact summary.
 
+## Using `db_query` For Aggregation
+
+For scripts that aggregate over tasks, sessions, or memory, `ctx.swarm.db_query` with direct SQL is far more efficient than fetching lists client-side.
+
+**The parameter is `sql`, not `query`:**
+
+```typescript
+// CORRECT
+const res = await ctx.swarm.db_query({ sql: "SELECT status, count(*) as cnt FROM agent_tasks GROUP BY status" });
+
+// WRONG — silently returns no data
+const res = await ctx.swarm.db_query({ query: "SELECT ..." });
+```
+
+**`db_query` returns positional rows, not objects.** The response shape is `{ rows: unknown[][], columns: string[] }`. Zip them into objects:
+
+```typescript
+function rowsToObjects(res: any): any[] {
+  const p = res?.data ?? res;
+  const cols: string[] = p?.columns ?? [];
+  return (p?.rows ?? []).map((r: any) =>
+    Array.isArray(r) ? Object.fromEntries(cols.map((c, i) => [c, r[i]])) : r,
+  );
+}
+
+const rows = rowsToObjects(await ctx.swarm.db_query({
+  sql: `SELECT status, count(*) as cnt FROM agent_tasks WHERE createdAt > datetime('now','-3 days') GROUP BY status`,
+}));
+// rows = [{ status: "completed", cnt: 42 }, ...]
+```
+
+**Common tables:** `agent_tasks` (tasks), `session_logs` (tool call logs), `agent_memory` (memories), `scheduled_tasks` (schedules), `agents` (agent registry).
+
+**`session_logs` has no `tool_name` column.** Tool names are embedded in the `content` JSON column. Extract them SQL-side with `instr`/`substr` or parse JSON in JS after fetching.
+
 ## SDK And Context Gotchas
 
+- **`args` can be undefined.** When a script is called without arguments, `args` is `undefined`. Always guard: `argsSchema.safeParse(args || {})` or use optional chaining (`args?.field`).
+- **All SDK methods return `Promise<unknown>`.** Never assume a specific return shape without defensive unwrapping (`res?.data?.tasks ?? res?.tasks ?? []`). Run `script-query-types` to see live type signatures — return types are `unknown` and actual shapes vary by endpoint.
 - `agentId` is propagated to scripts via the `X-Agent-ID` header, so SDK calls run as the invoking agent.
 - `taskId` is not ambient. If a script needs to call `ctx.swarm.task_storeProgress`, pass `taskId` explicitly in `args`.
 - Scripts invoked from a workflow script node may run with a workflow identity rather than a human or worker agent identity.
@@ -73,7 +112,7 @@ Good named scripts:
 Thread task identity explicitly:
 
 ```typescript
-export default async function main(args: { taskId: string; items: string[] }, ctx) {
+export default async function main(args: { taskId: string; items: string[] }, ctx: any) {
   const { swarm } = ctx;
   await swarm.task_storeProgress({
     taskId: args.taskId,