@desplega.ai/agent-swarm 1.102.0 → 1.103.0

package/src/types.ts

@@ -1,5 +1,152 @@
 import * as z from "zod";
-import { ModelTierSchema } from "./model-tiers";
+
+// ─── Model Tiers ─────────────────────────────────────────────────────────────
+// Merged from the former `src/model-tiers.ts` to dissolve the benign
+// `types` ↔ `model-tiers` import cycle (cycle-break #1; prep for the
+// `@swarm/types` monorepo package). `ModelTierSchema` is a runtime VALUE that is
+// referenced later in this file (e.g. the task/schedule schemas), so this
+// section must stay above its first use. `ProviderName` is referenced only as a
+// TYPE below; it is declared further down this same module and type references
+// are hoisted, so the forward reference is safe.
+
+export const ModelTierSchema = z.enum(["smol", "regular", "smart", "ultra"]);
+export type ModelTier = z.infer<typeof ModelTierSchema>;
+
+export const MODEL_TIERS = ModelTierSchema.options;
+
+export const LEGACY_MODEL_TO_TIER: Record<string, ModelTier> = {
+  haiku: "smol",
+  sonnet: "regular",
+  opus: "smart",
+  fable: "ultra",
+};
+
+export const MODEL_TIER_LABELS: Record<ModelTier, string> = {
+  smol: "Smol",
+  regular: "Regular",
+  smart: "Smart",
+  ultra: "Ultra",
+};
+
+export const DEFAULT_MODEL_TIER_MAP: Record<ProviderName, Record<ModelTier, string>> = {
+  claude: {
+    smol: "haiku",
+    regular: "sonnet",
+    smart: "opus",
+    ultra: "fable",
+  },
+  "claude-managed": {
+    smol: "claude-haiku-4-5",
+    regular: "claude-sonnet-4-6",
+    smart: "claude-opus-4-8",
+    ultra: "claude-fable-5",
+  },
+  codex: {
+    smol: "gpt-5.4-mini",
+    regular: "gpt-5.4",
+    smart: "gpt-5.5",
+    ultra: "gpt-5.5",
+  },
+  pi: {
+    smol: "openrouter/deepseek/deepseek-v4-flash",
+    regular: "openrouter/deepseek/deepseek-v4-flash",
+    smart: "openrouter/deepseek/deepseek-v4-pro",
+    ultra: "openrouter/anthropic/claude-opus-4.8",
+  },
+  opencode: {
+    smol: "openrouter/deepseek/deepseek-v4-flash",
+    regular: "openrouter/deepseek/deepseek-v4-flash",
+    smart: "openrouter/deepseek/deepseek-v4-pro",
+    ultra: "openrouter/anthropic/claude-opus-4.8",
+  },
+  devin: {
+    smol: "devin",
+    regular: "devin",
+    smart: "devin",
+    ultra: "devin",
+  },
+};
+
+export function parseModelTier(value: string | null | undefined): ModelTier | undefined {
+  if (!value) return undefined;
+  const normalized = value.trim().toLowerCase();
+  return ModelTierSchema.safeParse(normalized).success
+    ? (normalized as ModelTier)
+    : LEGACY_MODEL_TO_TIER[normalized];
+}
+
+export function splitLegacyModelAlias(input: {
+  model?: string | null;
+  modelTier?: string | null;
+}): { model?: string; modelTier?: ModelTier } {
+  const explicitTier = parseModelTier(input.modelTier);
+  const model = input.model?.trim();
+  if (!model) return { modelTier: explicitTier };
+
+  const legacyTier = parseModelTier(model);
+  if (legacyTier && !explicitTier) {
+    return { modelTier: legacyTier };
+  }
+
+  return {
+    model,
+    modelTier: explicitTier,
+  };
+}
+
+function parseTierMapJson(value: string | undefined): Partial<Record<ModelTier, string>> {
+  if (!value) return {};
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    const result: Partial<Record<ModelTier, string>> = {};
+    for (const tier of MODEL_TIERS) {
+      const model = (parsed as Record<string, unknown>)[tier];
+      if (typeof model === "string" && model.trim()) result[tier] = model.trim();
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+
+export function resolveModelTier(opts: {
+  tier?: string | null;
+  harnessProvider: ProviderName;
+  env?: Record<string, string | undefined>;
+}): string | undefined {
+  const tier = parseModelTier(opts.tier);
+  if (!tier) return undefined;
+
+  const env = opts.env ?? {};
+  const jsonOverrides = parseTierMapJson(env.MODEL_TIER_MAP);
+  const envKey = `MODEL_TIER_${tier.toUpperCase()}`;
+  const directOverride = env[envKey]?.trim();
+  if (directOverride) return directOverride;
+  if (jsonOverrides[tier]) return jsonOverrides[tier];
+
+  return DEFAULT_MODEL_TIER_MAP[opts.harnessProvider]?.[tier];
+}
+
+export function resolveTaskModelSelection(opts: {
+  model?: string | null;
+  modelTier?: string | null;
+  harnessProvider: ProviderName;
+  env?: Record<string, string | undefined>;
+}): { model?: string; source: "model" | "modelTier" | "none" } {
+  const model = opts.model?.trim();
+  if (model) return { model, source: "model" };
+
+  const tierModel = resolveModelTier({
+    tier: opts.modelTier,
+    harnessProvider: opts.harnessProvider,
+    env: opts.env,
+  });
+  if (tierModel) return { model: tierModel, source: "modelTier" };
+
+  return { source: "none" };
+}
+// ─── End Model Tiers ─────────────────────────────────────────────────────────
 
 // Task status - includes new unassigned and offered states
 export const AgentTaskStatusSchema = z.enum([
@@ -962,6 +1109,12 @@ export const RepoGuidelinesSchema = z.object({
 
 export type RepoGuidelines = z.infer<typeof RepoGuidelinesSchema>;
 
+export const RepoHooksSchema = z.object({
+  enabled: z.boolean().default(false),
+});
+
+export type RepoHooks = z.infer<typeof RepoHooksSchema>;
+
 export const SwarmRepoSchema = z.object({
   id: z.string().uuid(),
   url: z.string().min(1),
@@ -969,6 +1122,7 @@ export const SwarmRepoSchema = z.object({
   clonePath: z.string().min(1),
   defaultBranch: z.string().default("main"),
   autoClone: z.boolean().default(true),
+  hooks: RepoHooksSchema.optional().default({ enabled: false }),
   guidelines: RepoGuidelinesSchema.nullable().optional(),
   createdAt: z.string(),
   lastUpdatedAt: z.string(),

package/src/utils/template.ts

@@ -0,0 +1,127 @@
+/**
+ * Replace {{path.to.value}} tokens in a template string
+ * with values from the context object.
+ *
+ * Returns the interpolated result and a list of any unresolved token paths.
+ *
+ * Lives in `utils/` (not `workflows/`) so any domain — prompts, worker
+ * commands, HTTP handlers, MCP tools — can interpolate template strings
+ * without taking a dependency on the workflow engine module. The workflow
+ * engine re-exports these from `@/workflows/template` for its own use.
+ */
+
+export interface InterpolateResult {
+  result: string;
+  unresolved: string[];
+}
+
+export interface DeepInterpolateOptions {
+  preserveRawTokens?: boolean;
+}
+
+export function interpolate(template: string, ctx: Record<string, unknown>): InterpolateResult {
+  const unresolved: string[] = [];
+  const result = template.replace(/\{\{([^}]+)\}\}/g, (_match, path: string) => {
+    const keys = path.trim().split(".");
+    let value: unknown = ctx;
+    for (const key of keys) {
+      if (value == null || typeof value !== "object") {
+        unresolved.push(path.trim());
+        return "";
+      }
+      value = (value as Record<string, unknown>)[key];
+    }
+    if (value == null) {
+      unresolved.push(path.trim());
+      return "";
+    }
+    return typeof value === "object" ? safeStringify(value) : String(value);
+  });
+  return { result, unresolved };
+}
+
+/**
+ * Circular-reference-safe JSON.stringify for interpolation.
+ * Returns "[Circular]" instead of throwing on circular structures.
+ */
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return "[Circular]";
+  }
+}
+
+/** Matches a string that is EXACTLY one {{path}} token with no surrounding text. */
+const EXACT_TOKEN_RE = /^\{\{([^}]+)\}\}$/;
+
+/**
+ * Resolve a dot-separated path against a context object.
+ * Returns `{ found: true, value }` on success, `{ found: false }` when any
+ * segment is missing or the traversal hits a non-object.
+ */
+function resolvePath(
+  path: string,
+  ctx: Record<string, unknown>,
+): { found: true; value: unknown } | { found: false } {
+  const keys = path.trim().split(".");
+  let value: unknown = ctx;
+  for (const key of keys) {
+    if (value == null || typeof value !== "object") return { found: false };
+    value = (value as Record<string, unknown>)[key];
+  }
+  if (value === undefined) return { found: false };
+  return { found: true, value };
+}
+
+/**
+ * Deep-interpolate an arbitrary value tree (objects, arrays, strings).
+ *
+ * When `preserveRawTokens` is true and a string value is **exactly** one
+ * `{{path}}` token with no surrounding text, the resolved value is returned
+ * as-is (preserving object / array / number / boolean types). This is the
+ * "raw injection" path used by `swarm-script` node `config.args`.
+ *
+ * When a string contains multiple tokens or surrounding text (e.g.
+ * `"prefix-{{x}}"`) the existing string-interpolation path is used so the
+ * result remains a string.
+ *
+ * Non-string leaves are passed through unchanged.
+ */
+export function deepInterpolate(
+  value: unknown,
+  ctx: Record<string, unknown>,
+  options: DeepInterpolateOptions = {},
+): { value: unknown; unresolved: string[] } {
+  const allUnresolved: string[] = [];
+
+  function walk(v: unknown): unknown {
+    if (typeof v === "string") {
+      const exactMatch = options.preserveRawTokens ? EXACT_TOKEN_RE.exec(v) : null;
+      if (exactMatch?.[1]) {
+        const path = exactMatch[1].trim();
+        const resolved = resolvePath(path, ctx);
+        if (!resolved.found) {
+          allUnresolved.push(path);
+          return "";
+        }
+        return resolved.value;
+      }
+      // Multi-token or mixed string - fall back to string interpolation.
+      const { result, unresolved } = interpolate(v, ctx);
+      allUnresolved.push(...unresolved);
+      return result;
+    }
+    if (Array.isArray(v)) return v.map(walk);
+    if (v != null && typeof v === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(v)) {
+        out[k] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  }
+
+  return { value: walk(value), unresolved: allUnresolved };
+}

package/src/workflows/engine.ts

@@ -10,6 +10,7 @@ import {
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
+import { telemetry } from "../telemetry";
 import type { Workflow, WorkflowDefinition, WorkflowNode } from "../types";
 import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./checkpoint";
 import { shouldSkipCooldown } from "./cooldown";
@@ -27,6 +28,7 @@ const MAX_STEPS_PER_RUN = Number(process.env.WORKFLOW_MAX_STEPS_PER_RUN) || 500;
 
 export interface WorkflowExecutionOptions {
   requestedByUserId?: string;
+  triggerType?: "schedule" | "manual" | "event" | "api";
 }
 
 /**
@@ -78,6 +80,11 @@ export async function startWorkflowExecution(
 
   const runId = crypto.randomUUID();
   createWorkflowRun({ id: runId, workflowId: workflow.id, triggerData });
+  telemetry.workflow("started", {
+    workflowId: workflow.id,
+    nodeCount: workflow.definition.nodes.length,
+    triggerType: options.triggerType ?? "manual",
+  });
 
   // Resolve inputs and merge into initial context
   const ctx: Record<string, unknown> = { trigger: triggerData };

package/src/workflows/executors/agent-task.ts

@@ -1,9 +1,8 @@
 import { z } from "zod";
-import { ModelTierSchema, splitLegacyModelAlias } from "../../model-tiers";
 import { workflowContextKey } from "../../tasks/context-key";
 import { withSiblingAwareness } from "../../tasks/sibling-awareness";
 import type { ExecutorMeta } from "../../types";
-import { FollowUpConfigSchema } from "../../types";
+import { FollowUpConfigSchema, ModelTierSchema, splitLegacyModelAlias } from "../../types";
 import type { ExecutorResult } from "./base";
 import { BaseExecutor } from "./base";
 

package/src/workflows/template.ts

@@ -1,122 +1,13 @@
 /**
- * Replace {{path.to.value}} tokens in a template string
- * with values from the context object.
- *
- * Returns the interpolated result and a list of any unresolved token paths.
- */
-
-export interface InterpolateResult {
-  result: string;
-  unresolved: string[];
-}
-
-export interface DeepInterpolateOptions {
-  preserveRawTokens?: boolean;
-}
-
-export function interpolate(template: string, ctx: Record<string, unknown>): InterpolateResult {
-  const unresolved: string[] = [];
-  const result = template.replace(/\{\{([^}]+)\}\}/g, (_match, path: string) => {
-    const keys = path.trim().split(".");
-    let value: unknown = ctx;
-    for (const key of keys) {
-      if (value == null || typeof value !== "object") {
-        unresolved.push(path.trim());
-        return "";
-      }
-      value = (value as Record<string, unknown>)[key];
-    }
-    if (value == null) {
-      unresolved.push(path.trim());
-      return "";
-    }
-    return typeof value === "object" ? safeStringify(value) : String(value);
-  });
-  return { result, unresolved };
-}
-
-/**
- * Circular-reference-safe JSON.stringify for interpolation.
- * Returns "[Circular]" instead of throwing on circular structures.
- */
-function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return "[Circular]";
-  }
-}
-
-/** Matches a string that is EXACTLY one {{path}} token with no surrounding text. */
-const EXACT_TOKEN_RE = /^\{\{([^}]+)\}\}$/;
-
-/**
- * Resolve a dot-separated path against a context object.
- * Returns `{ found: true, value }` on success, `{ found: false }` when any
- * segment is missing or the traversal hits a non-object.
- */
-function resolvePath(
-  path: string,
-  ctx: Record<string, unknown>,
-): { found: true; value: unknown } | { found: false } {
-  const keys = path.trim().split(".");
-  let value: unknown = ctx;
-  for (const key of keys) {
-    if (value == null || typeof value !== "object") return { found: false };
-    value = (value as Record<string, unknown>)[key];
-  }
-  if (value === undefined) return { found: false };
-  return { found: true, value };
-}
-
-/**
- * Deep-interpolate an arbitrary value tree (objects, arrays, strings).
- *
- * When `preserveRawTokens` is true and a string value is **exactly** one
- * `{{path}}` token with no surrounding text, the resolved value is returned
- * as-is (preserving object / array / number / boolean types). This is the
- * "raw injection" path used by `swarm-script` node `config.args`.
- *
- * When a string contains multiple tokens or surrounding text (e.g.
- * `"prefix-{{x}}"`) the existing string-interpolation path is used so the
- * result remains a string.
- *
- * Non-string leaves are passed through unchanged.
- */
-export function deepInterpolate(
-  value: unknown,
-  ctx: Record<string, unknown>,
-  options: DeepInterpolateOptions = {},
-): { value: unknown; unresolved: string[] } {
-  const allUnresolved: string[] = [];
-
-  function walk(v: unknown): unknown {
-    if (typeof v === "string") {
-      const exactMatch = options.preserveRawTokens ? EXACT_TOKEN_RE.exec(v) : null;
-      if (exactMatch?.[1]) {
-        const path = exactMatch[1].trim();
-        const resolved = resolvePath(path, ctx);
-        if (!resolved.found) {
-          allUnresolved.push(path);
-          return "";
-        }
-        return resolved.value;
-      }
-      // Multi-token or mixed string - fall back to string interpolation.
-      const { result, unresolved } = interpolate(v, ctx);
-      allUnresolved.push(...unresolved);
-      return result;
-    }
-    if (Array.isArray(v)) return v.map(walk);
-    if (v != null && typeof v === "object") {
-      const out: Record<string, unknown> = {};
-      for (const [k, val] of Object.entries(v)) {
-        out[k] = walk(val);
-      }
-      return out;
-    }
-    return v;
-  }
-
-  return { value: walk(value), unresolved: allUnresolved };
-}
+ * The `{{token}}` interpolation helpers moved to `@/utils/template` so that
+ * non-workflow domains (prompts, worker commands, HTTP handlers, MCP tools)
+ * can use them without depending on the workflow engine module.
+ *
+ * This module re-exports them for the workflow engine and existing tests.
+ */
+export {
+  type DeepInterpolateOptions,
+  deepInterpolate,
+  type InterpolateResult,
+  interpolate,
+} from "@/utils/template";

package/src/workflows/triggers.ts

@@ -113,7 +113,9 @@ export async function handleWebhookTrigger(
   // string so non-JSON webhooks don't break.
   const triggerData = parseTriggerPayload(payload);
 
-  const runId = await startWorkflowExecution(workflow, triggerData, registry);
+  const runId = await startWorkflowExecution(workflow, triggerData, registry, {
+    triggerType: "event",
+  });
   return { runId };
 }
 
@@ -152,7 +154,9 @@ export async function handleScheduleTrigger(
       scheduleName: schedule.name,
       firedAt: new Date().toISOString(),
     };
-    const runId = await startWorkflowExecution(workflow, triggerData, registry);
+    const runId = await startWorkflowExecution(workflow, triggerData, registry, {
+      triggerType: "schedule",
+    });
     runIds.push(runId);
     console.log(
       `[Triggers] Schedule "${schedule.name}" triggered workflow "${workflow.name}" (run: ${runId})`,