@desplega.ai/agent-swarm 1.113.0 → 1.115.0

package/src/scripts-runtime/api-client.ts

@@ -1,10 +1,33 @@
 import type {
   ScriptApiConnectionDescriptor,
+  ScriptApiCredentialDescriptor,
   ScriptApiOperationDescriptor,
   ScriptApiRegistryClient,
 } from "./api-types";
 
-function applyTemplate(template: string, _placeholder: string): [string, string] | null {
+type FetchResponse = Awaited<ReturnType<typeof fetch>>;
+type TextResponse = {
+  headers: { get(name: string): string | null };
+  text(): Promise<string>;
+};
+
+type ScriptApiRawResult = {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  url: string;
+  response: FetchResponse;
+};
+
+type ScriptApiError = Error & {
+  status?: number;
+  statusText?: string;
+  body?: unknown;
+  response?: FetchResponse;
+};
+
+function applyTemplate(template: string): [string, string] | null {
   const idx = template.indexOf("=");
   if (idx >= 0) return [template.slice(0, idx), template.slice(idx + 1)];
   const colon = template.indexOf(":");
@@ -12,6 +35,22 @@ function applyTemplate(template: string, _placeholder: string): [string, string]
   return null;
 }
 
+function applyCredential(
+  credential: ScriptApiCredentialDescriptor | null,
+  url: URL,
+  headers: Headers,
+) {
+  if (!credential) return;
+  if (credential.headerTemplate) {
+    const parsed = applyTemplate(credential.headerTemplate);
+    if (parsed) headers.set(parsed[0], parsed[1]);
+  }
+  if (credential.queryTemplate) {
+    const parsed = applyTemplate(credential.queryTemplate);
+    if (parsed) url.searchParams.set(parsed[0], parsed[1]);
+  }
+}
+
 function operationUrl(
   baseUrl: string,
   operation: ScriptApiOperationDescriptor,
@@ -28,7 +67,9 @@ function operationUrl(
       throw new Error(`Missing path parameter ${param.name}`);
     path = path.replace(`{${param.name}}`, encodeURIComponent(String(value ?? "")));
   }
-  const url = new URL(path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+  // Spec paths are absolute ("/store/inventory"); resolve them relative to the
+  // base URL so a base path prefix like "/api/v3" is preserved.
+  const url = new URL(path.replace(/^\/+/, ""), baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
   const queryArgs = (args.query && typeof args.query === "object" ? args.query : {}) as Record<
     string,
     unknown
@@ -44,14 +85,113 @@ function operationUrl(
   return url;
 }
 
+function graphqlErrorMessage(errors: unknown): string {
+  if (!Array.isArray(errors)) return JSON.stringify(errors);
+  return errors
+    .map((error) => {
+      if (error && typeof error === "object" && "message" in error) {
+        return String((error as { message: unknown }).message);
+      }
+      return JSON.stringify(error);
+    })
+    .join("; ");
+}
+
+function isRawOptions(value: unknown): value is { raw: true } {
+  return Boolean(value && typeof value === "object" && (value as { raw?: unknown }).raw === true);
+}
+
+function headersRecord(headers: Headers): Record<string, string> {
+  return Object.fromEntries(headers.entries());
+}
+
+function rawResult(response: FetchResponse): ScriptApiRawResult {
+  return {
+    ok: response.ok,
+    status: response.status,
+    statusText: response.statusText,
+    headers: headersRecord(response.headers),
+    url: response.url,
+    response,
+  };
+}
+
+async function parseResponseBody(response: TextResponse): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return "";
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  return text;
+}
+
+async function throwApiResponseError(
+  slug: string,
+  operationName: string,
+  response: FetchResponse,
+): Promise<never> {
+  const error = new Error(
+    `ctx.api.${slug}.${operationName} failed with ${response.status}`,
+  ) as ScriptApiError;
+  error.status = response.status;
+  error.statusText = response.statusText;
+  error.response = response;
+  try {
+    error.body = await parseResponseBody(response.clone());
+  } catch {
+    error.body = undefined;
+  }
+  throw error;
+}
+
 export function createApiRegistryClient(
   descriptors: ScriptApiConnectionDescriptor[] = [],
+  options: { fetch?: typeof fetch } = {},
 ): ScriptApiRegistryClient {
+  const fetchImpl = options.fetch ?? fetch;
   const registry: ScriptApiRegistryClient = {};
   for (const descriptor of descriptors) {
     const client: ScriptApiRegistryClient[string] = {};
+    if (descriptor.kind === "graphql") {
+      client.graphql = async (query, variables) => {
+        if (typeof query !== "string") {
+          throw new Error(`ctx.api.${descriptor.slug}.graphql query must be a string`);
+        }
+        const url = new URL(descriptor.baseUrl);
+        const headers = new Headers({ "content-type": "application/json" });
+        applyCredential(descriptor.credential, url, headers);
+        const response = await fetchImpl(url, {
+          method: "POST",
+          headers,
+          body: JSON.stringify({ query, variables }),
+        });
+        if (!response.ok) {
+          throw new Error(`ctx.api.${descriptor.slug}.graphql failed with ${response.status}`);
+        }
+        const body = (await response.json()) as unknown;
+        if (body && typeof body === "object") {
+          const record = body as { data?: unknown; errors?: unknown };
+          if (Array.isArray(record.errors) && !("data" in record)) {
+            throw new Error(
+              `ctx.api.${descriptor.slug}.graphql failed: ${graphqlErrorMessage(record.errors)}`,
+            );
+          }
+          if ("data" in record) return record.data;
+        }
+        return body;
+      };
+      registry[descriptor.slug] = client;
+      continue;
+    }
+
     for (const operation of descriptor.operations) {
-      client[operation.name] = async (rawArgs = {}) => {
+      client[operation.name] = async (rawArgs = {}, options?: unknown) => {
+        const raw = isRawOptions(options);
         const args = rawArgs as Record<string, unknown>;
         const url = operationUrl(descriptor.baseUrl, operation, args);
         const headers = new Headers();
@@ -67,28 +207,20 @@ export function createApiRegistryClient(
           headers.set(param.name, String(value));
         }
 
-        const placeholder = descriptor.credential
-          ? `[REDACTED:${descriptor.credential.configKey}]`
-          : null;
-        if (placeholder && descriptor.credential?.headerTemplate) {
-          const parsed = applyTemplate(descriptor.credential.headerTemplate, placeholder);
-          if (parsed) headers.set(parsed[0], parsed[1]);
-        }
-        if (placeholder && descriptor.credential?.queryTemplate) {
-          const parsed = applyTemplate(descriptor.credential.queryTemplate, placeholder);
-          if (parsed) url.searchParams.set(parsed[0], parsed[1]);
-        }
+        applyCredential(descriptor.credential, url, headers);
 
         const init: RequestInit = { method: operation.method, headers };
-        if (operation.hasBody) {
+        // Guard against stored runtimes generated before hasBody excluded
+        // GET/HEAD — fetch() throws on GET/HEAD requests with a body.
+        const methodAllowsBody = !["GET", "HEAD"].includes(operation.method.toUpperCase());
+        if (operation.hasBody && methodAllowsBody) {
           headers.set("content-type", headers.get("content-type") ?? "application/json");
           init.body = JSON.stringify(args.body ?? null);
         }
-        const response = await fetch(url, init);
+        const response = await fetchImpl(url, init);
+        if (raw) return rawResult(response);
         if (!response.ok) {
-          throw new Error(
-            `ctx.api.${descriptor.slug}.${operation.name} failed with ${response.status}`,
-          );
+          await throwApiResponseError(descriptor.slug, operation.name, response);
         }
         const contentType = response.headers.get("content-type") ?? "";
         return contentType.includes("application/json") ? response.json() : response.text();

package/src/scripts-runtime/api-types.ts

@@ -28,18 +28,50 @@ export type ScriptApiOperationDescriptor = {
   responseType: string;
 };
 
-export type ScriptApiConnectionDescriptor = {
+export type ScriptApiCredentialDescriptor = {
+  configKey: string;
+  headerTemplate?: string;
+  queryTemplate?: string;
+};
+
+export type ScriptOpenApiConnectionDescriptor = {
   slug: string;
+  kind?: "openapi";
   baseUrl: string;
-  credential: {
-    configKey: string;
-    headerTemplate?: string;
-    queryTemplate?: string;
-  } | null;
+  credential: ScriptApiCredentialDescriptor | null;
   operations: ScriptApiOperationDescriptor[];
 };
 
+export type ScriptGraphqlConnectionDescriptor = {
+  slug: string;
+  kind: "graphql";
+  baseUrl: string;
+  credential: ScriptApiCredentialDescriptor | null;
+};
+
+export type ScriptApiConnectionDescriptor =
+  | ScriptOpenApiConnectionDescriptor
+  | ScriptGraphqlConnectionDescriptor;
+
+export type ScriptMcpToolDescriptor = {
+  name: string;
+  description?: string;
+  inputSchema: ScriptApiJsonSchema;
+};
+
+export type ScriptMcpConnectionDescriptor = {
+  slug: string;
+  kind: "mcp";
+  connectionId: string;
+  tools: ScriptMcpToolDescriptor[];
+};
+
 export type ScriptApiRegistryClient = Record<
+  string,
+  Record<string, (...args: unknown[]) => Promise<unknown>>
+>;
+
+export type ScriptMcpRegistryClient = Record<
   string,
   Record<string, (args?: Record<string, unknown>) => Promise<unknown>>
 >;

package/src/scripts-runtime/credential-broker/default-bindings.ts

@@ -15,5 +15,6 @@ export const DEFAULT_CREDENTIAL_BINDINGS: CredentialBinding[] = [
     scope: "global",
     scopeId: null,
     active: true,
+    authKind: "config",
   },
 ];

package/src/scripts-runtime/credential-broker/types.ts

@@ -5,6 +5,7 @@ export const CREDENTIAL_BINDINGS_CONFIG_KEY = "SCRIPT_CREDENTIAL_BINDINGS";
 export const REDACTED_PLACEHOLDER_PREFIX = "[REDACTED:";
 
 export const CredentialBindingScopeSchema = z.enum(["global", "agent", "repo"]);
+export const CredentialBindingAuthKindSchema = z.enum(["config", "oauth"]);
 
 export const CredentialBindingSchema = z
   .object({
@@ -15,9 +16,15 @@ export const CredentialBindingSchema = z
     scope: CredentialBindingScopeSchema.default("global"),
     scopeId: z.string().nullable().optional(),
     active: z.boolean().default(true),
+    authKind: CredentialBindingAuthKindSchema.default("config"),
+    oauthProvider: z.string().min(1).max(255).optional(),
   })
   .refine((binding) => binding.headerTemplate || binding.queryTemplate, {
     message: "At least one of headerTemplate or queryTemplate is required.",
+  })
+  .refine((binding) => binding.authKind !== "oauth" || !!binding.oauthProvider, {
+    message: "oauthProvider is required when authKind is oauth.",
+    path: ["oauthProvider"],
   });
 
 export const CredentialBindingsDocumentSchema = z.union([
@@ -26,6 +33,7 @@ export const CredentialBindingsDocumentSchema = z.union([
 ]);
 
 export type CredentialBindingScope = z.infer<typeof CredentialBindingScopeSchema>;
+export type CredentialBindingAuthKind = z.infer<typeof CredentialBindingAuthKindSchema>;
 export type CredentialBinding = z.infer<typeof CredentialBindingSchema>;
 
 export type ResolvedCredentialBinding = CredentialBinding & {

package/src/scripts-runtime/ctx.ts

@@ -1,5 +1,11 @@
 import { createApiRegistryClient } from "./api-client";
-import type { ScriptApiConnectionDescriptor, ScriptApiRegistryClient } from "./api-types";
+import type {
+  ScriptApiConnectionDescriptor,
+  ScriptApiRegistryClient,
+  ScriptMcpConnectionDescriptor,
+  ScriptMcpRegistryClient,
+} from "./api-types";
+import { createMcpRegistryClient } from "./mcp-client";
 import { stdlib } from "./stdlib";
 import type { SwarmConfig } from "./swarm-config";
 import { createSwarmSdk } from "./swarm-sdk";
@@ -7,6 +13,7 @@ import { createSwarmSdk } from "./swarm-sdk";
 export type RuntimeCtx = {
   swarm: Record<string, unknown> & { config: SwarmConfig };
   api: ScriptApiRegistryClient;
+  mcp: ScriptMcpRegistryClient;
   stdlib: typeof stdlib;
   logger: {
     log: (...args: unknown[]) => void;
@@ -18,15 +25,18 @@ export type RuntimeCtx = {
 export function buildCtx({
   swarmConfig,
   apiConnections,
+  mcpConnections,
 }: {
   swarmConfig: SwarmConfig;
   apiConnections?: ScriptApiConnectionDescriptor[];
+  mcpConnections?: ScriptMcpConnectionDescriptor[];
 }): RuntimeCtx {
   const swarm = createSwarmSdk(swarmConfig) as Record<string, unknown> & { config: SwarmConfig };
   swarm.config = swarmConfig;
   return {
     swarm,
     api: createApiRegistryClient(apiConnections),
+    mcp: createMcpRegistryClient(mcpConnections, swarmConfig),
     stdlib,
     logger: console,
   };

package/src/scripts-runtime/eval-harness.ts

@@ -92,7 +92,11 @@ try {
   const rawArgs = JSON.parse(await Bun.file(requiredEnv("SWARM_SCRIPT_ARGS_FILE")).text());
   // Accept both shapes: callers may pass an already-serialized JSON string.
   const parsedArgs = typeof rawArgs === "string" ? JSON.parse(rawArgs) : rawArgs;
-  const ctx = buildCtx({ swarmConfig, apiConnections: payload.apiConnections });
+  const ctx = buildCtx({
+    swarmConfig,
+    apiConnections: payload.apiConnections,
+    mcpConnections: payload.mcpConnections,
+  });
 
   const sourceText = await Bun.file(requiredEnv("SWARM_SCRIPT_SOURCE_FILE")).text();
   await Bun.write(userModulePath, sourceText);

package/src/scripts-runtime/executors/types.ts

@@ -1,4 +1,4 @@
-import type { ScriptApiConnectionDescriptor } from "../api-types";
+import type { ScriptApiConnectionDescriptor, ScriptMcpConnectionDescriptor } from "../api-types";
 import type { ResolvedCredentialBinding } from "../credential-broker";
 
 export type ScriptFsMode = "none" | "workspace-rw";
@@ -14,6 +14,7 @@ export type SwarmConfigPayload = {
   user: Record<string, { value: string; isSecret: boolean }>;
   egressSecrets?: EgressSecretEntry[];
   apiConnections?: ScriptApiConnectionDescriptor[];
+  mcpConnections?: ScriptMcpConnectionDescriptor[];
 };
 
 export type ScriptResourcePolicy = {

package/src/scripts-runtime/loader.ts

@@ -1,6 +1,6 @@
 import { getApiKey } from "../utils/api-key";
 import { scrubObject, scrubSecrets } from "../utils/secret-scrubber";
-import type { ScriptApiConnectionDescriptor } from "./api-types";
+import type { ScriptApiConnectionDescriptor, ScriptMcpConnectionDescriptor } from "./api-types";
 import { buildEgressSecrets } from "./egress-secrets";
 import { getScriptExecutor } from "./executors/registry";
 import {
@@ -25,6 +25,7 @@ export type RunScriptInput = {
   userConfig?: Record<string, { value: string; isSecret: boolean }>;
   egressSecrets?: EgressSecretEntry[];
   apiConnections?: ScriptApiConnectionDescriptor[];
+  mcpConnections?: ScriptMcpConnectionDescriptor[];
 };
 
 export type RunScriptOutput = Omit<ExecutorOutput, "result" | "stdout" | "stderr"> & {
@@ -51,6 +52,7 @@ function buildConfigPayload(input: RunScriptInput): SwarmConfigPayload {
     user: input.userConfig ?? {},
     egressSecrets: input.egressSecrets ?? buildEgressSecrets(),
     apiConnections: input.apiConnections ?? [],
+    mcpConnections: input.mcpConnections ?? [],
   };
 }
 

package/src/scripts-runtime/mcp-client.ts

@@ -0,0 +1,87 @@
+import type { ScriptMcpConnectionDescriptor, ScriptMcpRegistryClient } from "./api-types";
+import { Redacted } from "./redacted";
+import type { SwarmConfig } from "./swarm-config";
+
+function methodName(name: string): string {
+  const cleaned = name
+    .trim()
+    .replace(/[^A-Za-z0-9]+(.)/g, (_m, chr: string) => chr.toUpperCase())
+    .replace(/^[^A-Za-z_]+/, "")
+    .replace(/[^A-Za-z0-9_]/g, "");
+  if (!cleaned) throw new Error("MCP tool name must contain at least one letter");
+  return `${cleaned[0]?.toLowerCase()}${cleaned.slice(1)}`;
+}
+
+function methodNames(
+  tools: Array<{ name: string }>,
+): Array<{ tool: { name: string }; methodName: string }> {
+  const used = new Set<string>();
+  const baseCounts = new Map<string, number>();
+  return tools.map((tool) => {
+    const base = methodName(tool.name);
+    const count = baseCounts.get(base) ?? 0;
+    baseCounts.set(base, count + 1);
+    let toolMethod = count === 0 ? base : `${base}${count + 1}`;
+    let suffix = count + 2;
+    while (used.has(toolMethod)) {
+      toolMethod = `${base}${suffix}`;
+      suffix += 1;
+    }
+    used.add(toolMethod);
+    return { tool, methodName: toolMethod };
+  });
+}
+
+function headers(config: SwarmConfig): Record<string, string> {
+  return {
+    Authorization: `Bearer ${Redacted.value(config.apiKey)}`,
+    "X-Agent-ID": Redacted.value(config.agentId),
+    "Content-Type": "application/json",
+  };
+}
+
+function errorMessage(data: unknown): string {
+  if (data && typeof data === "object") {
+    if ("error" in data) return JSON.stringify((data as { error: unknown }).error);
+    if ("message" in data) return String((data as { message: unknown }).message);
+  }
+  return "unknown MCP proxy error";
+}
+
+export function createMcpRegistryClient(
+  descriptors: ScriptMcpConnectionDescriptor[] = [],
+  config: SwarmConfig,
+): ScriptMcpRegistryClient {
+  const registry: ScriptMcpRegistryClient = {};
+  const baseUrl = Redacted.value(config.mcpBaseUrl).replace(/\/$/, "");
+
+  for (const descriptor of descriptors) {
+    const client: ScriptMcpRegistryClient[string] = {};
+    for (const { tool, methodName: toolMethod } of methodNames(descriptor.tools)) {
+      client[toolMethod] = async (rawArgs = {}) => {
+        const response = await fetch(
+          `${baseUrl}/api/script-connections/${encodeURIComponent(descriptor.connectionId)}/mcp-call`,
+          {
+            method: "POST",
+            headers: headers(config),
+            body: JSON.stringify({ tool: tool.name, arguments: rawArgs ?? {} }),
+          },
+        );
+        const text = await response.text();
+        const data = text ? JSON.parse(text) : {};
+        if (!response.ok) {
+          throw new Error(
+            `ctx.mcp.${descriptor.slug}.${toolMethod} failed with ${response.status}: ${errorMessage(data)}`,
+          );
+        }
+        if (!data || typeof data !== "object" || (data as { ok?: unknown }).ok !== true) {
+          throw new Error(`ctx.mcp.${descriptor.slug}.${toolMethod} failed: ${errorMessage(data)}`);
+        }
+        return (data as { result: unknown }).result;
+      };
+    }
+    registry[descriptor.slug] = client;
+  }
+
+  return registry;
+}

package/src/scripts-runtime/sdk-allowlist.ts

@@ -139,6 +139,7 @@ export const SDK_TOOL_NAME_MAP = {
 
   // ── pages & metrics ──
   page_create: "create_page",
+  page_delete: "delete-page", // destructive
   metric_create: "create_metric",
 
   // ── human input ──

package/src/scripts-runtime/types/stdlib.d.ts

@@ -108,6 +108,7 @@ declare module "swarm-sdk" {
       externalId?: string;
       email?: string;
       userId?: string;
+      name?: string;
     }): Promise<unknown>;
     db_query(args: { sql: string; params?: unknown[] }): Promise<unknown>;
     // --- config ---
@@ -242,6 +243,8 @@ declare module "swarm-sdk" {
     slack_startThread(args: { channelId: string; message: string }): Promise<unknown>;
     slack_uploadFile(args: Record<string, unknown>): Promise<unknown>;
     slack_downloadFile(args: { url: string }): Promise<unknown>;
+    slack_delete(args: { channelId: string; messageTs: string }): Promise<unknown>;
+    slack_update(args: { channelId: string; messageTs: string; message: string }): Promise<unknown>;
 
     // --- write: messaging (internal) ---
     message_post(args: { channel?: string; content: string; to?: string }): Promise<unknown>;
@@ -346,6 +349,7 @@ declare module "swarm-sdk" {
 
     // --- pages & metrics ---
     page_create(args: Record<string, unknown>): Promise<unknown>;
+    page_delete(args: { pageId?: string; slug?: string }): Promise<unknown>;
     metric_create(args: Record<string, unknown>): Promise<unknown>;
 
     // --- human input ---
@@ -411,6 +415,8 @@ declare module "swarm-sdk" {
     run?: ScriptRunContext;
     step?: ScriptWorkflowSteps;
     swarm: SwarmSdk & { config: SwarmConfig };
+    api: ScriptApiRegistry;
+    mcp: ScriptMcpRegistry;
     stdlib: ScriptStdlib;
     logger: ScriptLogger;
   }

package/src/scripts-runtime/types/swarm-sdk.d.ts

@@ -8,6 +8,17 @@ declare module "swarm-sdk" {
     | { [key: string]: JsonValue };
   export type ScriptScope = "agent" | "global";
   export type ScriptFsMode = "none" | "workspace-rw";
+  export type ScriptApiRawOptions = { raw: true };
+  export type ScriptApiDefaultOptions = { raw?: false };
+
+  export interface ScriptApiRawResult {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    url: string;
+    response: Response;
+  }
 
   export interface Redacted<T> {
     readonly __redactedBrand?: T;
@@ -90,6 +101,7 @@ declare module "swarm-sdk" {
       externalId?: string;
       email?: string;
       userId?: string;
+      name?: string;
     }): Promise<unknown>;
     db_query(args: { sql: string; params?: unknown[] }): Promise<unknown>;
     // --- config ---
@@ -330,6 +342,7 @@ declare module "swarm-sdk" {
 
     // --- pages & metrics ---
     page_create(args: Record<string, unknown>): Promise<unknown>;
+    page_delete(args: { pageId?: string; slug?: string }): Promise<unknown>;
     metric_create(args: Record<string, unknown>): Promise<unknown>;
 
     // --- human input ---
@@ -395,10 +408,16 @@ declare module "swarm-sdk" {
     run?: ScriptRunContext;
     step?: ScriptWorkflowSteps;
     swarm: SwarmSdk & { config: SwarmConfig };
+    api: ScriptApiRegistry;
+    mcp: ScriptMcpRegistry;
     stdlib: ScriptStdlib;
     logger: ScriptLogger;
   }
 
   // biome-ignore lint/suspicious/noExplicitAny: scripts may narrow their args type at the entrypoint.
   export type ScriptMain = (args: any, ctx: ScriptContext) => unknown | Promise<unknown>;
+
+  export interface ScriptApiRegistry {}
+
+  export interface ScriptMcpRegistry {}
 }