@desplega.ai/agent-swarm 1.20.0 → 1.51.2

package/src/workflows/executors/script.ts

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import type { ExecutorMeta } from "../../types";
+import { BaseExecutor, type ExecutorResult } from "./base";
+
+// ─── Schemas ────────────────────────────────────────────────
+
+export const ScriptConfigSchema = z.object({
+  runtime: z.enum(["bash", "ts", "python"]),
+  script: z.string(),
+  args: z.array(z.string()).optional(),
+  timeout: z.number().int().min(1000).default(30_000),
+  cwd: z.string().optional(),
+});
+
+export const ScriptOutputSchema = z.object({
+  exitCode: z.number(),
+  stdout: z.string(),
+  stderr: z.string(),
+});
+
+// ─── Executor ───────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT = 30_000;
+
+export class ScriptExecutor extends BaseExecutor<
+  typeof ScriptConfigSchema,
+  typeof ScriptOutputSchema
+> {
+  readonly type = "script";
+  readonly mode = "instant" as const;
+  readonly configSchema = ScriptConfigSchema;
+  readonly outputSchema = ScriptOutputSchema;
+
+  protected async execute(
+    config: z.infer<typeof ScriptConfigSchema>,
+    _context: Readonly<Record<string, unknown>>,
+    _meta: ExecutorMeta,
+  ): Promise<ExecutorResult<z.infer<typeof ScriptOutputSchema>>> {
+    const timeoutMs = config.timeout ?? DEFAULT_TIMEOUT;
+
+    try {
+      const result = await Promise.race([this.runScript(config), this.timeoutPromise(timeoutMs)]);
+
+      return {
+        status: "success",
+        output: result,
+        nextPort: result.exitCode === 0 ? "success" : "failure",
+      };
+    } catch (err) {
+      return {
+        status: "failed",
+        error: `Script execution error: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  }
+
+  private async runScript(config: z.infer<typeof ScriptConfigSchema>): Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+  }> {
+    const { runtime, script, args = [], cwd } = config;
+    let cmd: string[];
+
+    switch (runtime) {
+      case "bash":
+        cmd = ["bash", "-c", script, ...args];
+        break;
+      case "ts":
+        cmd = ["bun", "-e", script, ...args];
+        break;
+      case "python":
+        cmd = ["python3", "-c", script, ...args];
+        break;
+    }
+
+    const proc = Bun.spawn(cmd, {
+      stdout: "pipe",
+      stderr: "pipe",
+      cwd: cwd ?? undefined,
+    });
+
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+      proc.exited,
+    ]);
+
+    return { exitCode, stdout: stdout.trimEnd(), stderr: stderr.trimEnd() };
+  }
+
+  private timeoutPromise(ms: number): Promise<never> {
+    return new Promise((_resolve, reject) => {
+      const id = globalThis.setTimeout(() => {
+        reject(new Error(`Script timed out after ${ms}ms`));
+      }, ms);
+      // Ensure the timer doesn't keep the process alive
+      if (typeof id === "object" && "unref" in id) {
+        (id as NodeJS.Timeout).unref();
+      }
+    });
+  }
+}

package/src/workflows/executors/validate.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+import type { ExecutorMeta } from "../../types";
+import { BaseExecutor, type ExecutorResult } from "./base";
+
+// ─── Schemas ────────────────────────────────────────────────
+
+export const ValidateConfigSchema = z.object({
+  targetNodeId: z.string(),
+  prompt: z.string().optional(),
+  schema: z.record(z.string(), z.unknown()).optional(),
+});
+
+export const ValidateOutputSchema = z.object({
+  pass: z.boolean(),
+  reasoning: z.string(),
+  confidence: z.number().min(0).max(1),
+});
+
+// ─── Executor ───────────────────────────────────────────────
+
+export class ValidateExecutor extends BaseExecutor<
+  typeof ValidateConfigSchema,
+  typeof ValidateOutputSchema
+> {
+  readonly type = "validate";
+  readonly mode = "instant" as const;
+  readonly configSchema = ValidateConfigSchema;
+  readonly outputSchema = ValidateOutputSchema;
+
+  protected async execute(
+    config: z.infer<typeof ValidateConfigSchema>,
+    context: Readonly<Record<string, unknown>>,
+    _meta: ExecutorMeta,
+  ): Promise<ExecutorResult<z.infer<typeof ValidateOutputSchema>>> {
+    const targetOutput = context[config.targetNodeId];
+    if (targetOutput === undefined) {
+      return {
+        status: "success",
+        output: {
+          pass: false,
+          reasoning: `Target node "${config.targetNodeId}" has no output in context`,
+          confidence: 1,
+        },
+        nextPort: "fail",
+      };
+    }
+
+    // Schema-based validation (no LLM call needed)
+    if (config.schema) {
+      return this.validateWithSchema(targetOutput, config.schema);
+    }
+
+    // Prompt-based validation (uses LLM)
+    if (config.prompt) {
+      return this.validateWithLlm(targetOutput, config.prompt, context);
+    }
+
+    // Neither schema nor prompt — just check that output exists
+    return {
+      status: "success",
+      output: { pass: true, reasoning: "Target node output exists", confidence: 1 },
+      nextPort: "pass",
+    };
+  }
+
+  private validateWithSchema(
+    targetOutput: unknown,
+    schema: Record<string, unknown>,
+  ): ExecutorResult<z.infer<typeof ValidateOutputSchema>> {
+    try {
+      // Use JSON Schema validation via Zod's loose parsing:
+      // Convert the JSON Schema to a basic check. For full JSON Schema support
+      // we'd need ajv, but for now we do structural matching.
+      const errors = validateJsonSchemaBasic(targetOutput, schema);
+      if (errors.length === 0) {
+        return {
+          status: "success",
+          output: { pass: true, reasoning: "Output matches schema", confidence: 1 },
+          nextPort: "pass",
+        };
+      }
+      return {
+        status: "success",
+        output: {
+          pass: false,
+          reasoning: `Schema validation failed: ${errors.join("; ")}`,
+          confidence: 1,
+        },
+        nextPort: "fail",
+      };
+    } catch (err) {
+      return {
+        status: "success",
+        output: {
+          pass: false,
+          reasoning: `Schema validation error: ${err instanceof Error ? err.message : String(err)}`,
+          confidence: 0.5,
+        },
+        nextPort: "fail",
+      };
+    }
+  }
+
+  private async validateWithLlm(
+    targetOutput: unknown,
+    prompt: string,
+    context: Readonly<Record<string, unknown>>,
+  ): Promise<ExecutorResult<z.infer<typeof ValidateOutputSchema>>> {
+    const interpolatedPrompt = this.deps.interpolate(prompt, context as Record<string, unknown>);
+    const outputStr =
+      typeof targetOutput === "string" ? targetOutput : JSON.stringify(targetOutput);
+
+    try {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      const { generateObject, jsonSchema } = await import("ai");
+
+      const openrouter = createOpenAI({
+        baseURL: "https://openrouter.ai/api/v1",
+        apiKey: process.env.OPENROUTER_API_KEY,
+      });
+
+      const { object } = await generateObject({
+        model: openrouter("google/gemini-2.0-flash-001"),
+        schema: jsonSchema({
+          type: "object",
+          properties: {
+            pass: { type: "boolean" },
+            reasoning: { type: "string" },
+            confidence: { type: "number", minimum: 0, maximum: 1 },
+          },
+          required: ["pass", "reasoning", "confidence"],
+        }),
+        prompt: `Evaluate the following output against the validation criteria.
+
+Criteria: ${interpolatedPrompt}
+
+Output to validate:
+${outputStr}
+
+Respond with pass (boolean), reasoning (string), and confidence (0-1).`,
+      });
+
+      const result = object as { pass: boolean; reasoning: string; confidence: number };
+      return {
+        status: "success",
+        output: result,
+        nextPort: result.pass ? "pass" : "fail",
+      };
+    } catch (err) {
+      return {
+        status: "success",
+        output: {
+          pass: false,
+          reasoning: `LLM validation failed: ${err instanceof Error ? err.message : String(err)}`,
+          confidence: 0,
+        },
+        nextPort: "fail",
+      };
+    }
+  }
+}
+
+// ─── Basic JSON Schema Validator ────────────────────────────
+
+function validateJsonSchemaBasic(value: unknown, schema: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+
+  if (schema.type) {
+    const expectedType = schema.type as string;
+    if (expectedType === "object") {
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        errors.push(`Expected object, got ${Array.isArray(value) ? "array" : typeof value}`);
+        return errors;
+      }
+      // Check properties with const/enum constraints
+      if (schema.properties && typeof schema.properties === "object") {
+        const props = schema.properties as Record<string, Record<string, unknown>>;
+        const obj = value as Record<string, unknown>;
+        for (const [key, propSchema] of Object.entries(props)) {
+          if ("const" in propSchema && obj[key] !== propSchema.const) {
+            errors.push(
+              `Property "${key}": expected const ${JSON.stringify(propSchema.const)}, got ${JSON.stringify(obj[key])}`,
+            );
+          }
+          if ("enum" in propSchema && Array.isArray(propSchema.enum)) {
+            if (!propSchema.enum.includes(obj[key])) {
+              errors.push(
+                `Property "${key}": expected one of ${JSON.stringify(propSchema.enum)}, got ${JSON.stringify(obj[key])}`,
+              );
+            }
+          }
+        }
+      }
+      // Check required fields
+      if (Array.isArray(schema.required)) {
+        const obj = value as Record<string, unknown>;
+        for (const key of schema.required as string[]) {
+          if (!(key in obj)) {
+            errors.push(`Missing required property "${key}"`);
+          }
+        }
+      }
+    } else if (expectedType === "string" && typeof value !== "string") {
+      errors.push(`Expected string, got ${typeof value}`);
+    } else if (expectedType === "number" && typeof value !== "number") {
+      errors.push(`Expected number, got ${typeof value}`);
+    } else if (expectedType === "boolean" && typeof value !== "boolean") {
+      errors.push(`Expected boolean, got ${typeof value}`);
+    } else if (expectedType === "array" && !Array.isArray(value)) {
+      errors.push(`Expected array, got ${typeof value}`);
+    }
+  }
+
+  return errors;
+}

package/src/workflows/executors/vcs.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import type { ExecutorMeta } from "../../types";
+import { BaseExecutor, type ExecutorResult } from "./base";
+
+// ─── Schemas ────────────────────────────────────────────────
+
+export const VcsConfigSchema = z.object({
+  action: z.enum(["create-issue", "create-pr", "comment"]),
+  provider: z.enum(["github", "gitlab"]),
+  repo: z.string(),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  branch: z.string().optional(),
+  baseBranch: z.string().optional(),
+  issueNumber: z.number().optional(),
+  prNumber: z.number().optional(),
+});
+
+export const VcsOutputSchema = z.object({
+  url: z.string(),
+  id: z.union([z.string(), z.number()]),
+});
+
+// ─── Executor ───────────────────────────────────────────────
+
+export class VcsExecutor extends BaseExecutor<typeof VcsConfigSchema, typeof VcsOutputSchema> {
+  readonly type = "vcs";
+  readonly mode = "instant" as const;
+  readonly configSchema = VcsConfigSchema;
+  readonly outputSchema = VcsOutputSchema;
+
+  protected async execute(
+    config: z.infer<typeof VcsConfigSchema>,
+    context: Readonly<Record<string, unknown>>,
+    _meta: ExecutorMeta,
+  ): Promise<ExecutorResult<z.infer<typeof VcsOutputSchema>>> {
+    // Stub implementation — validate config and return mock output.
+    // Real GitHub/GitLab integration will be added in a follow-up.
+    const title = config.title
+      ? this.deps.interpolate(config.title, context as Record<string, unknown>)
+      : "";
+    const body = config.body
+      ? this.deps.interpolate(config.body, context as Record<string, unknown>)
+      : "";
+
+    console.log(
+      `[vcs] Stub — ${config.action} on ${config.provider}/${config.repo}: title="${title}" body="${body.slice(0, 80)}"`,
+    );
+
+    const mockId = `stub-${Date.now()}`;
+    const mockUrl = `https://${config.provider}.com/${config.repo}/${config.action}/${mockId}`;
+
+    return {
+      status: "success",
+      output: { url: mockUrl, id: mockId },
+    };
+  }
+}

package/src/workflows/index.ts

@@ -0,0 +1,61 @@
+export { findEntryNodes, getSuccessors } from "./definition";
+export { startWorkflowExecution } from "./engine";
+export { workflowEventBus } from "./event-bus";
+export { recoverIncompleteRuns } from "./recovery";
+export { retryFailedRun, setupWorkflowResumeListener } from "./resume";
+export { startRetryPoller, stopRetryPoller } from "./retry-poller";
+export { interpolate } from "./template";
+export { instantiateTemplate, validateTemplateVariables } from "./templates";
+export { handleScheduleTrigger, handleWebhookTrigger } from "./triggers";
+export { snapshotWorkflow } from "./version";
+
+import * as db from "../be/db";
+import { workflowEventBus } from "./event-bus";
+import type { ExecutorRegistry } from "./executors/registry";
+import { createExecutorRegistry } from "./executors/registry";
+import { recoverIncompleteRuns } from "./recovery";
+import { setupWorkflowResumeListener } from "./resume";
+import { startRetryPoller } from "./retry-poller";
+import { interpolate } from "./template";
+
+// ─── Module-level singleton ────────────────────────────────
+
+let _registry: ExecutorRegistry | null = null;
+
+/**
+ * Get the executor registry singleton.
+ * Throws if called before `initWorkflows()`.
+ */
+export function getExecutorRegistry(): ExecutorRegistry {
+  if (!_registry) {
+    throw new Error("Workflow engine not initialized — call initWorkflows() first");
+  }
+  return _registry;
+}
+
+/**
+ * Initialize the workflow engine:
+ * 1. Create executor registry with all built-in executors
+ * 2. Wire up event bus listeners for task lifecycle resume
+ * 3. Recover incomplete runs from previous server lifecycle
+ * 4. Start the retry poller for failed steps with pending retries
+ */
+export function initWorkflows(): void {
+  // 1. Create the executor registry singleton
+  _registry = createExecutorRegistry({
+    db,
+    eventBus: workflowEventBus,
+    interpolate: (template, ctx) => interpolate(template, ctx).result,
+  });
+
+  // 2. Wire up resume listener (task.completed / task.failed / task.cancelled)
+  setupWorkflowResumeListener(workflowEventBus, _registry);
+
+  // 3. Recover incomplete runs (running + waiting) from previous lifecycle
+  recoverIncompleteRuns(_registry).catch((err) => {
+    console.error("[workflows] Failed to recover incomplete runs on startup:", err);
+  });
+
+  // 4. Start retry poller for failed steps with nextRetryAt
+  startRetryPoller(_registry);
+}

package/src/workflows/input.ts

@@ -0,0 +1,46 @@
+import { getSwarmConfigs } from "../be/db";
+
+/**
+ * Resolve workflow input values.
+ *
+ * Patterns:
+ *   - `${ENV_VAR}` -> process.env[ENV_VAR]
+ *   - `secret.NAME` -> look up in DB config store (global scope, isSecret=true)
+ *   - literal string -> pass through
+ */
+export function resolveInputs(input: Record<string, string>): Record<string, string> {
+  const resolved: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(input)) {
+    resolved[key] = resolveValue(value);
+  }
+
+  return resolved;
+}
+
+function resolveValue(value: string): string {
+  // Env var reference: ${MY_VAR}
+  const envMatch = /^\$\{(.+)\}$/.exec(value);
+  if (envMatch?.[1]) {
+    const envName = envMatch[1];
+    const envValue = process.env[envName];
+    if (envValue === undefined) {
+      throw new Error(`Environment variable "${envName}" is not set`);
+    }
+    return envValue;
+  }
+
+  // Secret reference: secret.NAME
+  if (value.startsWith("secret.")) {
+    const secretName = value.slice("secret.".length);
+    const configs = getSwarmConfigs({ scope: "global", key: secretName });
+    const secretConfig = configs.find((c) => c.isSecret);
+    if (!secretConfig) {
+      throw new Error(`Secret "${secretName}" not found in config store`);
+    }
+    return secretConfig.value;
+  }
+
+  // Literal
+  return value;
+}

package/src/workflows/json-schema-validator.ts

@@ -0,0 +1,118 @@
+/**
+ * Minimal hand-rolled JSON Schema validator.
+ *
+ * Supports the subset needed for workflow I/O schemas:
+ * - `type`: "object", "string", "number", "boolean", "array"
+ * - `required`: array of required property names
+ * - `properties`: map of property name → schema (recursive)
+ *
+ * Returns an array of validation error strings (empty = valid).
+ */
+export function validateJsonSchema(schema: Record<string, unknown>, data: unknown): string[] {
+  const errors: string[] = [];
+  validate(schema, data, "", errors);
+  return errors;
+}
+
+function validate(
+  schema: Record<string, unknown>,
+  data: unknown,
+  path: string,
+  errors: string[],
+): void {
+  const prefix = path || "root";
+
+  // Type check
+  if (schema.type !== undefined) {
+    const expected = schema.type as string;
+    if (!matchesType(expected, data)) {
+      errors.push(`${prefix}: expected type "${expected}", got ${typeOf(data)}`);
+      return; // No point checking properties of wrong type
+    }
+  }
+
+  // Required fields (only for objects)
+  if (Array.isArray(schema.required) && typeof data === "object" && data !== null) {
+    const obj = data as Record<string, unknown>;
+    for (const key of schema.required as string[]) {
+      if (!(key in obj)) {
+        errors.push(`${prefix}: missing required property "${key}"`);
+      }
+    }
+  }
+
+  // Enum check
+  if (Array.isArray(schema.enum)) {
+    const allowed = schema.enum as unknown[];
+    if (!allowed.some((v) => JSON.stringify(v) === JSON.stringify(data))) {
+      errors.push(
+        `${prefix}: value ${JSON.stringify(data)} not in enum [${allowed.map((v) => JSON.stringify(v)).join(", ")}]`,
+      );
+      return;
+    }
+  }
+
+  // Const check
+  if ("const" in schema) {
+    if (JSON.stringify(data) !== JSON.stringify(schema.const)) {
+      errors.push(
+        `${prefix}: value ${JSON.stringify(data)} does not match const ${JSON.stringify(schema.const)}`,
+      );
+      return;
+    }
+  }
+
+  // Recursive property validation (only for objects)
+  if (
+    schema.properties !== undefined &&
+    typeof schema.properties === "object" &&
+    schema.properties !== null &&
+    typeof data === "object" &&
+    data !== null
+  ) {
+    const props = schema.properties as Record<string, Record<string, unknown>>;
+    const obj = data as Record<string, unknown>;
+    for (const [key, subSchema] of Object.entries(props)) {
+      if (key in obj) {
+        validate(subSchema, obj[key], path ? `${path}.${key}` : key, errors);
+      }
+    }
+  }
+
+  // Items validation (for arrays)
+  if (
+    schema.items !== undefined &&
+    typeof schema.items === "object" &&
+    schema.items !== null &&
+    Array.isArray(data)
+  ) {
+    const itemSchema = schema.items as Record<string, unknown>;
+    for (let i = 0; i < data.length; i++) {
+      validate(itemSchema, data[i], `${prefix}[${i}]`, errors);
+    }
+  }
+}
+
+function matchesType(expected: string, data: unknown): boolean {
+  switch (expected) {
+    case "string":
+      return typeof data === "string";
+    case "number":
+      return typeof data === "number";
+    case "boolean":
+      return typeof data === "boolean";
+    case "array":
+      return Array.isArray(data);
+    case "object":
+      return typeof data === "object" && data !== null && !Array.isArray(data);
+    default:
+      return true; // Unknown type — don't block
+  }
+}
+
+function typeOf(data: unknown): string {
+  if (data === null) return "null";
+  if (data === undefined) return "undefined";
+  if (Array.isArray(data)) return "array";
+  return typeof data;
+}