@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/src/utils/credentials.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "bun:test";
+import {
+  CREDENTIAL_POOL_VARS,
+  resolveCredentialPools,
+  selectRandomCredential,
+  validateClaudeCredentials,
+} from "./credentials.ts";
+
+describe("selectRandomCredential", () => {
+  it("returns single value as-is when no commas", () => {
+    const result = selectRandomCredential("my-single-token");
+    expect(result.selected).toBe("my-single-token");
+    expect(result.index).toBe(0);
+    expect(result.total).toBe(1);
+  });
+
+  it("returns empty string as-is", () => {
+    const result = selectRandomCredential("");
+    expect(result.selected).toBe("");
+    expect(result.index).toBe(0);
+    expect(result.total).toBe(1);
+  });
+
+  it("selects one from comma-separated values", () => {
+    const credentials = ["token1", "token2", "token3"];
+    const result = selectRandomCredential(credentials.join(","));
+    expect(credentials).toContain(result.selected);
+    expect(result.index).toBeGreaterThanOrEqual(0);
+    expect(result.index).toBeLessThan(3);
+    expect(result.total).toBe(3);
+  });
+
+  it("trims whitespace around credentials", () => {
+    const result = selectRandomCredential(" token1 , token2 ");
+    expect(["token1", "token2"]).toContain(result.selected);
+    expect(result.total).toBe(2);
+  });
+
+  it("filters out empty segments from trailing commas", () => {
+    const result = selectRandomCredential("token1,,token2,");
+    expect(["token1", "token2"]).toContain(result.selected);
+    expect(result.total).toBe(2);
+  });
+
+  it("treats single value with trailing comma as single credential", () => {
+    const result = selectRandomCredential("token1,");
+    expect(result.selected).toBe("token1,");
+    expect(result.total).toBe(1);
+  });
+
+  it("distributes selections across all credentials over many calls", () => {
+    const seen = new Set<string>();
+    for (let i = 0; i < 100; i++) {
+      const result = selectRandomCredential("a,b,c");
+      seen.add(result.selected);
+    }
+    // With 100 iterations and 3 options, we should see all 3
+    expect(seen.size).toBe(3);
+  });
+});
+
+describe("resolveCredentialPools", () => {
+  it("resolves comma-separated CLAUDE_CODE_OAUTH_TOKEN", () => {
+    const env: Record<string, string | undefined> = {
+      CLAUDE_CODE_OAUTH_TOKEN: "token1,token2",
+      OTHER_VAR: "unchanged",
+    };
+    resolveCredentialPools(env);
+    expect(["token1", "token2"]).toContain(env.CLAUDE_CODE_OAUTH_TOKEN!);
+    expect(env.OTHER_VAR).toBe("unchanged");
+  });
+
+  it("resolves comma-separated ANTHROPIC_API_KEY", () => {
+    const env: Record<string, string | undefined> = {
+      ANTHROPIC_API_KEY: "key1,key2,key3",
+    };
+    resolveCredentialPools(env);
+    expect(["key1", "key2", "key3"]).toContain(env.ANTHROPIC_API_KEY!);
+  });
+
+  it("leaves single values unchanged", () => {
+    const env: Record<string, string | undefined> = {
+      CLAUDE_CODE_OAUTH_TOKEN: "single-token",
+      ANTHROPIC_API_KEY: "single-key",
+    };
+    resolveCredentialPools(env);
+    expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBe("single-token");
+    expect(env.ANTHROPIC_API_KEY).toBe("single-key");
+  });
+
+  it("handles undefined credential vars", () => {
+    const env: Record<string, string | undefined> = {
+      SOME_OTHER_VAR: "value",
+    };
+    resolveCredentialPools(env);
+    expect(env.CLAUDE_CODE_OAUTH_TOKEN).toBeUndefined();
+    expect(env.ANTHROPIC_API_KEY).toBeUndefined();
+    expect(env.SOME_OTHER_VAR).toBe("value");
+  });
+
+  it("resolves both credential vars independently", () => {
+    const env: Record<string, string | undefined> = {
+      CLAUDE_CODE_OAUTH_TOKEN: "oauth1,oauth2",
+      ANTHROPIC_API_KEY: "apikey1,apikey2",
+    };
+    resolveCredentialPools(env);
+    expect(["oauth1", "oauth2"]).toContain(env.CLAUDE_CODE_OAUTH_TOKEN!);
+    expect(["apikey1", "apikey2"]).toContain(env.ANTHROPIC_API_KEY!);
+  });
+});
+
+describe("validateClaudeCredentials", () => {
+  it("returns 'oauth' when CLAUDE_CODE_OAUTH_TOKEN is set", () => {
+    const env = { CLAUDE_CODE_OAUTH_TOKEN: "some-oauth-token" };
+    expect(validateClaudeCredentials(env)).toBe("oauth");
+  });
+
+  it("returns 'api_key' when only ANTHROPIC_API_KEY is set", () => {
+    const env = { ANTHROPIC_API_KEY: "sk-ant-123" };
+    expect(validateClaudeCredentials(env)).toBe("api_key");
+  });
+
+  it("returns 'oauth' when both are set (oauth takes priority)", () => {
+    const env = {
+      CLAUDE_CODE_OAUTH_TOKEN: "some-oauth-token",
+      ANTHROPIC_API_KEY: "sk-ant-123",
+    };
+    expect(validateClaudeCredentials(env)).toBe("oauth");
+  });
+
+  it("throws when neither credential is set", () => {
+    expect(() => validateClaudeCredentials({})).toThrow(
+      "No Claude credentials found. Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.",
+    );
+  });
+
+  it("treats empty string as missing", () => {
+    const env = { CLAUDE_CODE_OAUTH_TOKEN: "", ANTHROPIC_API_KEY: "" };
+    expect(() => validateClaudeCredentials(env)).toThrow("No Claude credentials found");
+  });
+
+  it("treats undefined values as missing", () => {
+    const env: Record<string, string | undefined> = {
+      CLAUDE_CODE_OAUTH_TOKEN: undefined,
+      ANTHROPIC_API_KEY: undefined,
+    };
+    expect(() => validateClaudeCredentials(env)).toThrow("No Claude credentials found");
+  });
+});
+
+describe("CREDENTIAL_POOL_VARS", () => {
+  it("contains expected env var names", () => {
+    expect(CREDENTIAL_POOL_VARS).toContain("CLAUDE_CODE_OAUTH_TOKEN");
+    expect(CREDENTIAL_POOL_VARS).toContain("ANTHROPIC_API_KEY");
+  });
+});

package/src/utils/credentials.ts

@@ -0,0 +1,50 @@
+/** Env vars that may contain comma-separated credential pools */
+export const CREDENTIAL_POOL_VARS = ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"] as const;
+
+/**
+ * If a value contains commas, split and randomly select one credential.
+ * Single values (no commas) are returned as-is for backward compatibility.
+ */
+export function selectRandomCredential(value: string): {
+  selected: string;
+  index: number;
+  total: number;
+} {
+  const credentials = value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (credentials.length <= 1) {
+    return { selected: value, index: 0, total: 1 };
+  }
+  const index = Math.floor(Math.random() * credentials.length);
+  return { selected: credentials[index]!, index, total: credentials.length };
+}
+
+/**
+ * Validate that at least one Claude credential is available.
+ * Priority: CLAUDE_CODE_OAUTH_TOKEN > ANTHROPIC_API_KEY.
+ * Returns the credential type found, or throws if neither is set.
+ */
+export function validateClaudeCredentials(
+  env: Record<string, string | undefined>,
+): "oauth" | "api_key" {
+  if (env.CLAUDE_CODE_OAUTH_TOKEN) return "oauth";
+  if (env.ANTHROPIC_API_KEY) return "api_key";
+  throw new Error("No Claude credentials found. Set CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY.");
+}
+
+/**
+ * For credential env vars that contain comma-separated values,
+ * randomly select one to distribute load across subscriptions.
+ */
+export function resolveCredentialPools(env: Record<string, string | undefined>): void {
+  for (const envVar of CREDENTIAL_POOL_VARS) {
+    const val = env[envVar];
+    if (val?.includes(",")) {
+      const { selected, index, total } = selectRandomCredential(val);
+      env[envVar] = selected;
+      console.log(`[credentials] Selected ${envVar} credential ${index + 1}/${total}`);
+    }
+  }
+}

package/src/utils/error-tracker.ts

@@ -0,0 +1,190 @@
+/**
+ * Tracks error signals from Claude CLI stream-json output to produce
+ * meaningful failure reasons instead of generic "exited with code N".
+ */
+
+export interface ErrorSignal {
+  type: "api_error" | "result_error" | "stderr_error";
+  errorCategory?: string;
+  message: string;
+  timestamp: string;
+}
+
+export class SessionErrorTracker {
+  private errors: ErrorSignal[] = [];
+
+  /** Record an error from an assistant message with message.error field */
+  addApiError(errorCategory: string, message: string): void {
+    this.errors.push({
+      type: "api_error",
+      errorCategory,
+      message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /** Record an error from a result event with is_error: true */
+  addResultError(subtype: string, errors: string[]): void {
+    for (const msg of errors) {
+      this.errors.push({
+        type: "result_error",
+        errorCategory: subtype,
+        message: msg,
+        timestamp: new Date().toISOString(),
+      });
+    }
+  }
+
+  /** Record an error from an explicit type: "error" event */
+  addErrorEvent(message: string): void {
+    this.errors.push({
+      type: "api_error",
+      message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  /** Record an error pattern found in stderr */
+  addStderrError(message: string): void {
+    this.errors.push({
+      type: "stderr_error",
+      message,
+      timestamp: new Date().toISOString(),
+    });
+  }
+
+  hasErrors(): boolean {
+    return this.errors.length > 0;
+  }
+
+  /**
+   * Build a meaningful failure reason string from accumulated errors.
+   * Falls back to the generic exit code message if no errors were captured.
+   */
+  buildFailureReason(exitCode: number): string {
+    if (this.errors.length === 0) {
+      return `Claude process exited with code ${exitCode}`;
+    }
+
+    const uniqueMessages = [...new Set(this.errors.map((e) => e.message))];
+    const apiErrors = this.errors.filter((e) => e.type === "api_error" && e.errorCategory);
+    const primaryCategory = apiErrors.length > 0 ? (apiErrors[0]!.errorCategory ?? null) : null;
+
+    const parts: string[] = [];
+
+    switch (primaryCategory) {
+      case "rate_limit":
+        parts.push("Rate limit hit");
+        break;
+      case "authentication_failed":
+        parts.push("Authentication failed");
+        break;
+      case "billing_error":
+        parts.push("Billing error");
+        break;
+      case "server_error":
+        parts.push("Server error (API overloaded)");
+        break;
+      default: {
+        const resultErrors = this.errors.filter((e) => e.type === "result_error");
+        if (resultErrors.length > 0) {
+          const subtype = resultErrors[0]!.errorCategory;
+          switch (subtype) {
+            case "error_max_turns":
+              parts.push("Max turns exceeded");
+              break;
+            case "error_max_budget_usd":
+              parts.push("Budget limit exceeded");
+              break;
+            case "error_during_execution":
+              parts.push("Error during execution");
+              break;
+            default:
+              parts.push(`Session error (exit code ${exitCode})`);
+          }
+        } else {
+          parts.push(`Session error (exit code ${exitCode})`);
+        }
+      }
+    }
+
+    if (uniqueMessages.length > 0) {
+      parts.push(`: ${uniqueMessages[0]}`);
+    }
+
+    if (uniqueMessages.length > 1) {
+      parts.push(` (+${uniqueMessages.length - 1} more error(s))`);
+    }
+
+    return parts.join("");
+  }
+
+  /** Check if the failure was due to a missing/stale session ID */
+  isSessionNotFound(): boolean {
+    return this.errors.some((e) => e.message.includes("No conversation found with session ID"));
+  }
+
+  getErrors(): ReadonlyArray<ErrorSignal> {
+    return this.errors;
+  }
+}
+
+/**
+ * Extract error signals from a parsed JSON line of Claude CLI stream-json output.
+ * Call this for each parsed JSON object from stdout.
+ */
+export function trackErrorFromJson(
+  json: Record<string, unknown>,
+  tracker: SessionErrorTracker,
+): void {
+  // 1. Assistant messages with API errors (rate_limit, auth, billing, etc.)
+  if (json.type === "assistant") {
+    const message = json.message as Record<string, unknown> | undefined;
+    if (message?.error) {
+      const content = message.content as Array<Record<string, unknown>> | undefined;
+      const errorText =
+        (content?.[0]?.text as string) || String(message.error) || "Unknown API error";
+      tracker.addApiError(String(message.error), errorText);
+    }
+  }
+
+  // 2. Explicit error events
+  if (json.type === "error") {
+    const errorText = (json.error as string) || (json.message as string) || JSON.stringify(json);
+    tracker.addErrorEvent(errorText);
+  }
+
+  // 3. Result events with errors
+  if (json.type === "result" && json.is_error) {
+    const errors = Array.isArray(json.errors) ? (json.errors as string[]) : [];
+    const subtype = (json.subtype as string) || "error_during_execution";
+    tracker.addResultError(
+      subtype,
+      errors.length > 0 ? errors : [(json.result as string) || "Unknown error"],
+    );
+  }
+}
+
+/**
+ * Parse stderr text for known error patterns and add them to the tracker.
+ */
+export function parseStderrForErrors(stderr: string, tracker: SessionErrorTracker): void {
+  if (!stderr.trim()) return;
+
+  const lower = stderr.toLowerCase();
+  const firstLine = stderr.trim().split("\n")[0] ?? stderr.trim();
+
+  if (lower.includes("rate limit") || lower.includes("rate_limit") || lower.includes("429")) {
+    tracker.addStderrError(firstLine);
+  } else if (
+    lower.includes("authentication") ||
+    lower.includes("unauthorized") ||
+    lower.includes("401")
+  ) {
+    tracker.addStderrError(`Authentication error: ${firstLine}`);
+  } else if (lower.includes("billing") || lower.includes("payment")) {
+    tracker.addStderrError(`Billing error: ${firstLine}`);
+  } else if (lower.includes("error") || lower.includes("fatal") || lower.includes("panic")) {
+    tracker.addStderrError(firstLine);
+  }
+}

package/src/vcs/index.ts

@@ -0,0 +1,15 @@
+/**
+ * VCS Provider utilities.
+ */
+
+export type { VcsProvider } from "./types";
+
+/**
+ * Detect the VCS provider for a repo URL string.
+ * Returns null for unrecognised URLs.
+ */
+export function detectVcsProvider(url: string): "github" | "gitlab" | null {
+  if (url.includes("gitlab.com") || url.includes("gitlab.")) return "gitlab";
+  if (url.includes("github.com") || /^[\w.-]+\/[\w.-]+$/.test(url)) return "github";
+  return null;
+}

package/src/vcs/types.ts

@@ -0,0 +1,5 @@
+/**
+ * VCS Provider types — shared across GitHub/GitLab integration.
+ */
+
+export type VcsProvider = "github" | "gitlab";

package/src/workflows/checkpoint.ts

@@ -0,0 +1,121 @@
+import { getDb, updateWorkflowRun, updateWorkflowRunStep } from "../be/db";
+import type { RetryPolicy } from "../types";
+
+/**
+ * Checkpoint a successful step — atomic DB write of step result + run context.
+ */
+export function checkpointStep(
+  runId: string,
+  stepId: string,
+  nodeId: string,
+  result: { output?: unknown; nextPort?: string },
+  ctx: Record<string, unknown>,
+): void {
+  const txn = getDb().transaction(() => {
+    updateWorkflowRunStep(stepId, {
+      status: "completed",
+      output: result.output,
+      nextPort: result.nextPort || undefined,
+      finishedAt: new Date().toISOString(),
+    });
+
+    // Merge step output into run context
+    ctx[nodeId] = result.output;
+    updateWorkflowRun(runId, {
+      context: ctx,
+    });
+  });
+  txn();
+}
+
+/**
+ * Checkpoint a step failure — marks step failed, calculates retry if applicable.
+ */
+export function checkpointStepFailure(
+  runId: string,
+  stepId: string,
+  error: string,
+  retryCount: number,
+  retryPolicy?: RetryPolicy,
+): { shouldRetry: boolean } {
+  const now = new Date().toISOString();
+
+  if (retryPolicy && retryCount < retryPolicy.maxRetries) {
+    const delay = calculateBackoff(retryPolicy, retryCount);
+    const nextRetryAt = new Date(Date.now() + delay).toISOString();
+
+    updateWorkflowRunStep(stepId, {
+      status: "failed",
+      error,
+      retryCount: retryCount + 1,
+      maxRetries: retryPolicy.maxRetries,
+      nextRetryAt,
+    });
+
+    return { shouldRetry: true };
+  }
+
+  // No retries left — mark step and run failed
+  // Clear nextRetryAt so the poller stops picking this step up
+  updateWorkflowRunStep(stepId, {
+    status: "failed",
+    error,
+    finishedAt: now,
+    nextRetryAt: null,
+  });
+
+  updateWorkflowRun(runId, {
+    status: "failed",
+    error: `Step failed: ${error}`,
+    finishedAt: now,
+  });
+
+  return { shouldRetry: false };
+}
+
+/**
+ * Checkpoint a step entering waiting state (async executor).
+ */
+export function checkpointStepWaiting(
+  runId: string,
+  stepId: string,
+  ctx: Record<string, unknown>,
+): void {
+  const txn = getDb().transaction(() => {
+    updateWorkflowRunStep(stepId, {
+      status: "waiting",
+    });
+
+    updateWorkflowRun(runId, {
+      status: "waiting",
+      context: ctx,
+    });
+  });
+  txn();
+}
+
+/**
+ * Calculate backoff delay based on retry policy and current attempt.
+ */
+function calculateBackoff(policy: RetryPolicy, attempt: number): number {
+  let delay: number;
+
+  switch (policy.strategy) {
+    case "exponential": {
+      // Exponential with full jitter
+      const base = policy.baseDelayMs * 2 ** attempt;
+      delay = Math.random() * Math.min(base, policy.maxDelayMs);
+      break;
+    }
+    case "linear":
+      delay = policy.baseDelayMs * (attempt + 1);
+      break;
+    case "static":
+      delay = policy.baseDelayMs;
+      break;
+    default:
+      delay = policy.baseDelayMs;
+  }
+
+  return Math.min(delay, policy.maxDelayMs);
+}

package/src/workflows/cooldown.ts

@@ -0,0 +1,28 @@
+import { getLastSuccessfulRun } from "../be/db";
+import type { CooldownConfig } from "../types";
+
+/**
+ * Convert a CooldownConfig to total milliseconds.
+ */
+function cooldownToMs(cooldown: CooldownConfig): number {
+  let ms = 0;
+  if (cooldown.hours) ms += cooldown.hours * 60 * 60 * 1000;
+  if (cooldown.minutes) ms += cooldown.minutes * 60 * 1000;
+  if (cooldown.seconds) ms += cooldown.seconds * 1000;
+  return ms;
+}
+
+/**
+ * Check if a workflow should be skipped due to cooldown.
+ * Returns true if the last successful run completed within the cooldown window.
+ */
+export function shouldSkipCooldown(workflowId: string, cooldown: CooldownConfig): boolean {
+  const lastRun = getLastSuccessfulRun(workflowId);
+  if (!lastRun?.finishedAt) return false;
+
+  const cooldownMs = cooldownToMs(cooldown);
+  const lastFinished = new Date(lastRun.finishedAt).getTime();
+  const now = Date.now();
+
+  return now - lastFinished < cooldownMs;
+}