@desplega.ai/agent-swarm 1.90.0 → 1.91.0

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,