@desplega.ai/agent-swarm 2.4.4 → 2.5.0

package/src/vcs/types.ts

@@ -1,5 +1,5 @@
 /**
- * VCS Provider types — shared across GitHub/GitLab/Azure DevOps integration.
+ * VCS Provider types — shared across GitHub/GitLab/Azure DevOps/Bitbucket integration.
  */
 
-export type VcsProvider = "github" | "gitlab" | "azure-devops";
+export type VcsProvider = "github" | "gitlab" | "azure-devops" | "bitbucket";

package/src/workflows/approval-resolution.ts

@@ -1,6 +1,7 @@
 import type { WorkflowDefinition } from "../types";
 import type { ApprovalOutcome, ResolvedApproval } from "./executors/base";
 import type { ExecutorRegistry } from "./executors/registry";
+import { resolveStepNode } from "./foreach-body";
 
 /**
  * Step output and output port for a step whose approval request resolved.
@@ -18,7 +19,9 @@ export function shapeApprovalResolution(
   parkedOutput: unknown,
   approval: ResolvedApproval,
 ): ApprovalOutcome {
-  const node = definition.nodes.find((candidate) => candidate.id === nodeId);
+  // A foreach child resolves to its body node, so a system-one-decision body
+  // keeps its own shaping.
+  const node = resolveStepNode(definition, nodeId);
   if (node && registry.has(node.type)) {
     const shaped = registry.get(node.type).resolveApproval(parkedOutput, approval);
     if (shaped) return shaped;

package/src/workflows/checkpoint.ts

@@ -83,11 +83,16 @@ export async function checkpointStepFailure(
 
 /**
  * Checkpoint a step entering waiting state (async executor).
+ *
+ * `keepRunStatus` parks the step and persists the context but leaves the run
+ * `running`: a foreach parent parks before its driver starts the children, and
+ * the run must not read as `waiting` until they are dispatched.
  */
 export async function checkpointStepWaiting(
   runId: string,
   stepId: string,
   ctx: Record<string, unknown>,
+  options: { keepRunStatus?: boolean } = {},
 ): Promise<boolean> {
   return getDbClient().transaction(async () => {
     const step = await getDbClient().get<{ id: string }>(
@@ -103,7 +108,10 @@ export async function checkpointStepWaiting(
     );
     if (!step) return false;
 
-    await updateWorkflowRun(runId, { status: "waiting", context: ctx });
+    await updateWorkflowRun(
+      runId,
+      options.keepRunStatus ? { context: ctx } : { status: "waiting", context: ctx },
+    );
     return true;
   });
 }

package/src/workflows/constants.ts

@@ -1 +1,4 @@
 export const FAILED_TASK_OUTPUT_PREFIX = "[FAILED:";
+
+/** `waitFor` of a foreach parent that materialized its children; the driver starts them. */
+export const FOREACH_ITEMS_WAIT_FOR = "foreach.items";

package/src/workflows/definition.ts

@@ -11,6 +11,12 @@ import {
   systemOneStaticShapeViolations,
 } from "./executors/system-one-decision";
 import { systemOneExtractionStaticShapeViolations } from "./executors/system-one-extraction";
+import {
+  FOREACH_FAILURE_POLICIES,
+  type ForeachFailurePolicy,
+  foreachBodyTypeError,
+  isForeachBodyType,
+} from "./foreach-body";
 
 /** Extract all target node IDs from a node's `next` field */
 export function getNextTargets(next: string | string[] | Record<string, string>): string[] {
@@ -220,7 +226,7 @@ export function validateDefinition(
       ...systemOneRetryViolations(node),
     );
     if (node.type === "foreach") {
-      validateForeachNode(node, errors);
+      validateForeachNode(node, errors, registry);
       // A legacy `#` id may stay editable as a NORMAL node, but never as a foreach
       // parent: its children would be `a#b#item`, and parseSyntheticNodeId splits on
       // the FIRST `#`, so the join would resolve them to parent "a" and never close.
@@ -312,20 +318,25 @@ export function validateDefinition(
 
       reportStaticConfigIssues(node, registry.get(node.type).configSchema, node.config, errors);
 
-      // A foreach body is executed by the agent-task executor per item — hold its
-      // static config to the same schema a top-level agent-task node gets, so an
-      // invalid field (priority: 101, tags: "x") fails at authoring instead of
+      // A foreach body is executed by its own executor per item — hold its
+      // static config to the same schema a top-level node of that type gets, so
+      // an invalid field (priority: 101, tags: "x") fails at authoring instead of
       // after the fan-out materialized. Interpolated fields defer as usual.
-      if (node.type === "foreach" && registry.has("agent-task")) {
-        const body = node.config.body;
-        const bodyConfig =
-          typeof body === "object" && body !== null && !Array.isArray(body)
-            ? (body as Record<string, unknown>).config
-            : undefined;
+      const body = node.type === "foreach" ? node.config.body : undefined;
+      const bodyRecord =
+        typeof body === "object" && body !== null && !Array.isArray(body)
+          ? (body as Record<string, unknown>)
+          : undefined;
+      if (
+        bodyRecord &&
+        typeof bodyRecord.type === "string" &&
+        isForeachBodyType(bodyRecord.type, registry)
+      ) {
+        const bodyConfig = bodyRecord.config;
         if (typeof bodyConfig === "object" && bodyConfig !== null && !Array.isArray(bodyConfig)) {
           reportStaticConfigIssues(
             node,
-            registry.get("agent-task").configSchema,
+            registry.get(bodyRecord.type).configSchema,
             bodyConfig,
             errors,
             "config.body.config",
@@ -401,10 +412,27 @@ function reportStaticConfigIssues(
   }
 }
 
-function validateForeachNode(node: WorkflowNode, errors: string[]): void {
+function validateForeachNode(
+  node: WorkflowNode,
+  errors: string[],
+  registry?: ExecutorRegistry,
+): void {
   const config = node.config;
-  if (Object.hasOwn(config, "concurrency")) {
-    errors.push(`Node "${node.id}" foreach concurrency is not supported in v1`);
+  if (
+    config.concurrency !== undefined &&
+    !(Number.isInteger(config.concurrency) && (config.concurrency as number) >= 1)
+  ) {
+    errors.push(
+      `Node "${node.id}" foreach config.concurrency must be an integer of 1 or more, got ${JSON.stringify(config.concurrency)}`,
+    );
+  }
+  if (
+    config.failurePolicy !== undefined &&
+    !FOREACH_FAILURE_POLICIES.includes(config.failurePolicy as ForeachFailurePolicy)
+  ) {
+    errors.push(
+      `Node "${node.id}" foreach config.failurePolicy must be one of ${FOREACH_FAILURE_POLICIES.map((p) => `"${p}"`).join(", ")}, got ${JSON.stringify(config.failurePolicy)}`,
+    );
   }
 
   // The asynchronous join (joinForeach) checkpoints the aggregate and routes
@@ -436,8 +464,11 @@ function validateForeachNode(node: WorkflowNode, errors: string[]): void {
     return;
   }
   const bodyRecord = body as Record<string, unknown>;
-  if (bodyRecord.type !== "agent-task") {
-    errors.push(`Node "${node.id}" foreach config.body.type must be "agent-task" in v1`);
+  if (typeof bodyRecord.type !== "string" || bodyRecord.type.length === 0) {
+    errors.push(`Node "${node.id}" foreach config.body.type must be a non-empty string`);
+  } else {
+    const typeError = foreachBodyTypeError(node.id, bodyRecord.type, registry);
+    if (typeError) errors.push(typeError);
   }
   if (
     typeof bodyRecord.config !== "object" ||
@@ -448,7 +479,7 @@ function validateForeachNode(node: WorkflowNode, errors: string[]): void {
     return;
   }
   const bodyConfig = bodyRecord.config as Record<string, unknown>;
-  if (typeof bodyConfig.template !== "string") {
+  if (bodyRecord.type === "agent-task" && typeof bodyConfig.template !== "string") {
     errors.push(`Node "${node.id}" foreach agent-task body.config.template must be a string`);
   }
 }

package/src/workflows/engine.ts

@@ -25,6 +25,7 @@ import { telemetry } from "../telemetry";
 import type { Workflow, WorkflowDefinition, WorkflowNode, WorkflowRunStep } from "../types";
 import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./checkpoint";
 import { loadCompletedStepRouting } from "./completed-step-routing";
+import { FOREACH_ITEMS_WAIT_FOR } from "./constants";
 import { shouldSkipCooldown } from "./cooldown";
 import { findEntryNodes, getNextTargets, getSuccessors, resolveValidationPort } from "./definition";
 import type { AsyncExecutorResult } from "./executors/base";
@@ -34,15 +35,16 @@ import {
   systemOneRetryViolations,
   systemOneUnresolvedError,
 } from "./executors/system-one-decision";
+import { parkAndDriveForeach } from "./foreach-driver";
 import { FOREACH_TERMINAL_STEP_STATUSES, resolveForeachParent } from "./foreach-join";
 import { getSecretInputKeys, redactSecretsForStorage, resolveInputs } from "./input";
 import { validateJsonSchema } from "./json-schema-validator";
 import { getMaxWorkflowStepsPerRun } from "./limits";
+import { resolveNodeTimeoutMs } from "./node-timeout";
 import { findWorkflowReadinessProblems, formatReadinessRunError } from "./readiness";
 import { deepInterpolate } from "./template";
 import { runStepValidation, type ValidationRunResult } from "./validation";
 
-const DEFAULT_TIMEOUT_MS = 30_000;
 // Read dynamically, NOT captured at module load: `src/http/index.ts` imports
 // this module before `loadGlobalConfigsIntoEnv()` hydrates `swarm_config` into
 // `process.env`, so a module-level const would permanently ignore DB-saved
@@ -510,14 +512,19 @@ async function walkGraphOwned(
     const hasPendingRetries = finalSteps.some(
       (s) => s.status === "failed" && s.nextRetryAt != null,
     );
-    const failedSteps = finalSteps.filter((s) => s.status === "failed" && s.nextRetryAt == null);
+    // A foreach child's outcome is in its parent's aggregate; the parent step
+    // is authoritative for the run outcome.
+    const isForeachChild = (s: WorkflowRunStep) => resolveForeachParent(def, s.nodeId) !== null;
+    const failedSteps = finalSteps.filter(
+      (s) => s.status === "failed" && s.nextRetryAt == null && !isForeachChild(s),
+    );
     // Exclude entry/trigger nodes when checking for completed steps — a trigger
     // completing doesn't mean a meaningful branch succeeded. Without this filter,
     // a linear workflow (trigger → mustPass validator → action) would be marked
     // as partial-failure instead of failed when the validator fails.
     const entryNodeIds = new Set(findEntryNodes(def).map((n) => n.id));
     const hasCompletedSteps = finalSteps.some(
-      (s) => s.status === "completed" && !entryNodeIds.has(s.nodeId),
+      (s) => s.status === "completed" && !entryNodeIds.has(s.nodeId) && !isForeachChild(s),
     );
 
     if (hasWaitingSteps) {
@@ -880,18 +887,7 @@ async function runClaimedStep(
     inputCtx: interpolationCtx,
   };
 
-  // Inline script nodes historically expose their wall-clock budget as
-  // `config.timeout`, while the workflow watchdog reads `config.timeoutMs` for
-  // every other executor. Keep the outer watchdog aligned with the script
-  // executor so a script configured for (for example) 90s is not killed by the
-  // engine's 30s default first.
-  const configuredTimeoutMs =
-    typeof node.config?.timeoutMs === "number"
-      ? node.config.timeoutMs
-      : node.type === "script" && typeof node.config?.timeout === "number"
-        ? node.config.timeout
-        : undefined;
-  const timeoutMs = configuredTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const timeoutMs = resolveNodeTimeoutMs(node);
 
   let result: Awaited<ReturnType<typeof executor.run>>;
   try {
@@ -949,6 +945,20 @@ async function runClaimedStep(
 
   // Check for async result
   if ("async" in result && (result as AsyncExecutorResult).async) {
+    if ((result as AsyncExecutorResult).waitFor === FOREACH_ITEMS_WAIT_FOR) {
+      // The foreach executor materialized its children; park the parent and
+      // start them. Instant bodies run here, each against its own budget, and
+      // can close the join before the drive returns.
+      const drive = await parkAndDriveForeach({
+        runId,
+        stepId,
+        parentNodeId: node.id,
+        ctx,
+        registry,
+      });
+      if (drive.joined) return { outcome: "completed", successors: drive.successors };
+      return { outcome: drive.parked ? "waiting" : "completed", successors: [] };
+    }
     const waiting = await checkpointStepWaiting(runId, stepId, ctx);
     // A child run that finished before the step parked had its event dropped.
     if (waiting && (result as AsyncExecutorResult).waitFor === "workflow.child.finished") {

package/src/workflows/executors/foreach.ts

@@ -1,19 +1,22 @@
 import { z } from "zod";
+import { createForeachChildSteps } from "../../be/db/workflow-runs";
 import type { ExecutorMeta } from "../../types";
-import { deepInterpolate } from "../../utils/template";
+import { FOREACH_ITEMS_WAIT_FOR } from "../constants";
 import { getSuccessors } from "../definition";
+import { foreachBodyTypeError } from "../foreach-body";
 import {
   buildForeachAggregate,
   FOREACH_TERMINAL_STEP_STATUSES,
   parseSyntheticNodeId,
 } from "../foreach-join";
 import { getMaxWorkflowStepsPerRun } from "../limits";
-import { AgentTaskExecutor } from "./agent-task";
 import type { AsyncExecutorResult, ExecutorResult } from "./base";
 import { BaseExecutor } from "./base";
 
+// Any registered executor except `foreach` (see foreach-body.ts); the guard in
+// execute() and definition validation enforce the policy.
 const ForeachBodySchema = z.object({
-  type: z.literal("agent-task"),
+  type: z.string().min(1),
   config: z.record(z.string(), z.unknown()),
 });
 
@@ -21,7 +24,12 @@ export const ForeachConfigSchema = z.object({
   over: z.array(z.record(z.string(), z.unknown())),
   itemKey: z.string().min(1),
   body: ForeachBodySchema,
-  concurrency: z.never().optional(),
+  /** Items in flight at once (`running` or `waiting` children). Unbounded when absent. */
+  concurrency: z.number().int().min(1).optional(),
+  /** Defaults from the workflow `onNodeFailure` (see effectiveFailurePolicy). */
+  // Literal, not FOREACH_FAILURE_POLICIES: foreach-body.ts sits in an import
+  // cycle with this module and would be read before it initializes.
+  failurePolicy: z.enum(["fail-fast", "collect-outcomes"]).optional(),
 });
 
 const ForeachResultSchema = z.object({
@@ -34,6 +42,8 @@ export const ForeachOutputSchema = z.object({
   results: z.array(ForeachResultSchema),
   okCount: z.number().int().nonnegative(),
   failedCount: z.number().int().nonnegative(),
+  /** Items cancelled before they finished (fail-fast queued items, cancelled bodies). Counted in failedCount too. */
+  cancelledCount: z.number().int().nonnegative().optional(),
 });
 
 export type ForeachOutput = z.infer<typeof ForeachOutputSchema>;
@@ -49,7 +59,7 @@ export class ForeachExecutor extends BaseExecutor<
 
   protected async execute(
     config: z.infer<typeof ForeachConfigSchema>,
-    context: Readonly<Record<string, unknown>>,
+    _context: Readonly<Record<string, unknown>>,
     meta: ExecutorMeta,
   ): Promise<ExecutorResult<ForeachOutput>> {
     if (config.over.length === 0) {
@@ -77,16 +87,19 @@ export class ForeachExecutor extends BaseExecutor<
       seenItemKeys.add(itemKey);
     }
 
-    const agentTaskExecutor = new AgentTaskExecutor(this.deps);
+    const bodyTypeError = foreachBodyTypeError(meta.nodeId, config.body.type);
+    if (bodyTypeError) return { status: "failed", error: bodyTypeError };
+
     const runSteps = await this.deps.db.getWorkflowRunStepsByRunId(meta.runId);
-    const childStepsByNodeId = new Map(
+    const existingChildNodeIds = new Set(
       runSteps
         .filter((step) => parseSyntheticNodeId(step.nodeId)?.parentNodeId === meta.nodeId)
-        .map((step) => [step.nodeId, step]),
+        .map((step) => step.nodeId),
+    );
+    const missingItems = items.filter(
+      ({ itemKey }) => !existingChildNodeIds.has(`${meta.nodeId}#${itemKey}`),
     );
-    const childCountToCreate = items.filter(
-      ({ itemKey }) => !childStepsByNodeId.has(`${meta.nodeId}#${itemKey}`),
-    ).length;
+    const childCountToCreate = missingItems.length;
     const maxSteps = getMaxWorkflowStepsPerRun();
     // walkGraph's circuit breaker rejects any post-join walk once allSteps.length
     // >= maxSteps, so a fan-out with a successor that lands exactly on the cap would
@@ -107,79 +120,26 @@ export class ForeachExecutor extends BaseExecutor<
       };
     }
 
-    // Materialize EVERY child step row before dispatching ANY child task. A task
-    // dispatched for an early child can complete (and trigger joinForeach) while
-    // later children are still being set up — the join must always see the full
-    // child set, with not-yet-dispatched children in a non-terminal state.
-    for (const { index, itemKey } of items) {
-      const childNodeId = `${meta.nodeId}#${itemKey}`;
-      if (childStepsByNodeId.has(childNodeId)) continue;
-      const childStepId = crypto.randomUUID();
-      const childStep = await this.deps.db.createWorkflowRunStep({
-        id: childStepId,
-        runId: meta.runId,
-        nodeId: childNodeId,
-        nodeType: "agent-task",
-        input: { itemKey, index },
-      });
-      await this.deps.db.updateWorkflowRunStep(childStepId, {
-        idempotencyKey: `${meta.runId}:${childNodeId}:0`,
-      });
-      childStepsByNodeId.set(childNodeId, childStep);
-    }
-
-    for (const { item, index, itemKey } of items) {
-      const childNodeId = `${meta.nodeId}#${itemKey}`;
-      const childStep = childStepsByNodeId.get(childNodeId)!;
-
-      // Re-walks must not regress terminal children or disturb their aggregate
-      // inputs. Retry resets only the failed child to pending before arriving here.
-      if (FOREACH_TERMINAL_STEP_STATUSES.has(childStep.status)) continue;
-
-      // The deferred per-item pass interpolates against the node's declared-inputs
-      // context (meta.inputCtx) plus item/index — NOT the full run context — so
-      // body.config obeys the same explicit-dataflow boundary as normal node
-      // config instead of silently reading undeclared upstream outputs.
-      const bodyCtx = { ...(meta.inputCtx ?? context), item, index };
-      const childInterpolation = deepInterpolate(config.body.config, bodyCtx);
-      if (childInterpolation.unresolved.length > 0) {
-        console.warn(
-          `[workflow] Step ${childNodeId}: unresolved interpolation tokens: ${childInterpolation.unresolved.join(", ")}`,
-        );
-        await this.deps.db.updateWorkflowRunStep(childStep.id, {
-          diagnostics: JSON.stringify({ unresolvedTokens: childInterpolation.unresolved }),
-        });
-      }
-
-      const linkedTask = await this.deps.db.getTaskByWorkflowRunStepId(childStep.id);
-      if (linkedTask?.status === "failed" || linkedTask?.status === "cancelled") {
-        // A retry needs a fresh task. Detaching the stale terminal task keeps the
-        // executor's one-task-per-step de-duplication deterministic and scoped.
-        await this.deps.db.detachTaskFromWorkflowRunStep(linkedTask.id);
-      }
-
-      const childResult = await agentTaskExecutor.run({
-        config: childInterpolation.value as Record<string, unknown>,
-        context,
-        meta: {
-          ...meta,
-          stepId: childStep.id,
+    // Materialize EVERY child row, queued (`pending`), in one transaction and
+    // before any child starts. An early child can complete (and trigger the
+    // join) while later children are still being set up, so the join must
+    // always see the full child set. The item value is not persisted: the
+    // driver looks it up by key in the re-interpolated `over`, which keeps
+    // resolved secrets out of step rows.
+    await createForeachChildSteps(
+      meta.runId,
+      meta.nodeId,
+      missingItems.map(({ index, itemKey }) => {
+        const childNodeId = `${meta.nodeId}#${itemKey}`;
+        return {
+          id: crypto.randomUUID(),
           nodeId: childNodeId,
-        },
-      });
-      if (childResult.status !== "success") {
-        throw new Error(childResult.error ?? `foreach child "${itemKey}" failed to start`);
-      }
-      if ("async" in childResult) {
-        await this.deps.db.updateWorkflowRunStep(childStep.id, { status: "waiting" });
-      } else {
-        await this.deps.db.updateWorkflowRunStep(childStep.id, {
-          status: "completed",
-          output: normalizeExistingTaskOutput(childResult.output),
-          finishedAt: new Date().toISOString(),
-        });
-      }
-    }
+          nodeType: config.body.type,
+          input: { itemKey, index, attempt: 0 },
+          idempotencyKey: `${meta.runId}:${childNodeId}:0`,
+        };
+      }),
+    );
 
     const childSteps = (await this.deps.db.getWorkflowRunStepsByRunId(meta.runId)).filter(
       (step) => parseSyntheticNodeId(step.nodeId)?.parentNodeId === meta.nodeId,
@@ -188,26 +148,12 @@ export class ForeachExecutor extends BaseExecutor<
       return { status: "success", output: buildForeachAggregate(childSteps) };
     }
 
+    // The engine parks the parent and the foreach driver starts the children.
     return {
       status: "success",
       async: true,
-      waitFor: "task.completed",
+      waitFor: FOREACH_ITEMS_WAIT_FOR,
       correlationId: meta.stepId,
     } as AsyncExecutorResult<ForeachOutput>;
   }
 }
-
-function normalizeExistingTaskOutput(output: unknown): unknown {
-  if (typeof output !== "object" || output === null) return output;
-  const record = output as Record<string, unknown>;
-  if (typeof record.taskOutput !== "string") return output;
-  try {
-    const parsed = JSON.parse(record.taskOutput);
-    if (typeof parsed === "object" && parsed !== null) {
-      return { ...record, taskOutput: parsed };
-    }
-  } catch {
-    // Non-structured task output remains a string.
-  }
-  return output;
-}

package/src/workflows/executors/system-one-decision.ts

@@ -18,8 +18,8 @@ import {
 } from "./human-in-the-loop";
 import { SYSTEM_ONE_EXTRACTION_NODE_TYPE } from "./system-one-extraction";
 import {
+  resolveSystemOneDefaultProvider,
   resolveSystemOneTarget,
-  SYSTEM_ONE_DEFAULT_PROVIDER,
   SYSTEM_ONE_PROVIDER_IDS,
   SYSTEM_ONE_PROVIDERS,
   type SystemOneProvider,
@@ -164,7 +164,11 @@ export type SystemOneHumanReview = z.infer<typeof HumanReviewSchema>;
 
 export const SystemOneDecisionConfigSchema = z
   .strictObject({
-    provider: z.enum(SYSTEM_ONE_PROVIDER_IDS).default(SYSTEM_ONE_DEFAULT_PROVIDER),
+    /**
+     * Decision host. Unset means the `SYSTEM_ONE_DEFAULT_PROVIDER` global config
+     * value, read at run time (`typesafe` when that is unset too).
+     */
+    provider: z.enum(SYSTEM_ONE_PROVIDER_IDS).optional(),
     /** Provider-specific model id. Unset means the provider's default. */
     model: z.string().min(1).optional(),
     state: SystemOneStateSchema,
@@ -235,7 +239,9 @@ export const SystemOneDecisionConfigSchema = z
       }
     }
     // Provider limits. A {{token}} model is skipped at save and checked again at run,
-    // where the interpolated config is parsed by this same schema.
+    // where the interpolated config is parsed by this same schema. With no provider
+    // the default is read at run time, so `decide` checks the limits there.
+    if (config.provider === undefined) return;
     const modelProblem = systemOneModelProblem(
       config.provider,
       config.model ?? (SYSTEM_ONE_PROVIDERS[config.provider] as SystemOneProvider).defaultModel,
@@ -847,6 +853,11 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     return { db: this.deps.db, env: this.options.env ?? process.env };
   }
 
+  /** The provider a config without `provider` uses, read now so a settings change applies at once. */
+  private defaultProvider(): Promise<SystemOneProviderId> {
+    return resolveSystemOneDefaultProvider(this.providerContext());
+  }
+
   private resolveTarget(id: SystemOneProviderId, model?: string) {
     return resolveSystemOneTarget(id, this.providerContext(), {
       apiKey: this.options.getApiKey,
@@ -863,9 +874,10 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     nodes: readonly ExecutorReadinessNode[],
   ): Promise<ExecutorReadinessProblem[]> {
     const nodeIdsByProvider = new Map<SystemOneProviderId, string[]>();
+    const defaultId = await this.defaultProvider();
     for (const node of nodes) {
       // An unknown provider is a config error the schema reports; it names no credential.
-      const id = systemOneProviderOf(node.config);
+      const id = systemOneProviderOf(node.config, defaultId);
       if (id) nodeIdsByProvider.set(id, [...(nodeIdsByProvider.get(id) ?? []), node.id]);
     }
     const problems: ExecutorReadinessProblem[] = [];
@@ -903,16 +915,25 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
    */
   async decide(
     config: SystemOneDecisionConfig,
-  ): Promise<{ ok: true; output: SystemOneDecisionOutput } | { ok: false; error: string }> {
-    const providerId = config.provider;
+  ): Promise<
+    | { ok: true; output: SystemOneDecisionOutput }
+    | { ok: false; error: string; deploymentRefused?: true }
+  > {
+    const providerId = config.provider ?? (await this.defaultProvider());
     const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[providerId];
 
     // A provider with no default sends no `model` when the node sets none.
     const model = config.model ?? provider.defaultModel;
     const modelProblem = systemOneModelProblem(providerId, model);
     if (modelProblem) return { ok: false, error: modelProblem };
+    // Checked at save only for a named provider; a defaulted one is checked here.
+    const limitProblem = systemOneQuestionLimitProblem(
+      providerId,
+      Object.keys(config.questions).length,
+    );
+    if (limitProblem) return { ok: false, error: limitProblem };
     const target = await this.resolveTarget(providerId, model);
-    if (!target.ok) return { ok: false, error: target.error };
+    if (!target.ok) return target;
     const { apiKey, endpoint, keyName } = target;
 
     const wire = provider.wire ?? SYSTEM_ONE_WIRE;

package/src/workflows/executors/system-one-providers.ts

@@ -288,15 +288,41 @@ export const SYSTEM_ONE_PROVIDERS = Object.fromEntries(
 export const SYSTEM_ONE_PROVIDER_IDS = hostsServing("decide");
 export const SYSTEM_ONE_EXTRACT_PROVIDER_IDS = hostsServing("extract");
 
+/** The decision provider when neither the call nor `SYSTEM_ONE_DEFAULT_PROVIDER` names one. */
 export const SYSTEM_ONE_DEFAULT_PROVIDER: SystemOneProviderId = "typesafe";
 export const SYSTEM_ONE_EXTRACT_DEFAULT_PROVIDER: SystemOneExtractProviderId = "cloudflare";
 
+/** Global config key naming the decision provider a node or call without `provider` uses. */
+export const SYSTEM_ONE_DEFAULT_PROVIDER_CONFIG_KEY = "SYSTEM_ONE_DEFAULT_PROVIDER";
+
 export function isSystemOneProviderId(value: unknown): value is SystemOneProviderId {
   return (
     typeof value === "string" && (SYSTEM_ONE_PROVIDER_IDS as readonly string[]).includes(value)
   );
 }
 
+/**
+ * The decision provider for a node or call that names none: the global
+ * `SYSTEM_ONE_DEFAULT_PROVIDER` row, then the same key in the environment, then
+ * `typesafe`. Read at run time, so changing the setting needs no workflow edit.
+ * A value that is not a decide host is skipped; the config guard refuses it on save.
+ */
+export async function resolveSystemOneDefaultProvider(
+  ctx: SystemOneProviderContext,
+): Promise<SystemOneProviderId> {
+  let stored: string | undefined;
+  try {
+    stored = await readGlobalConfig(ctx.db, SYSTEM_ONE_DEFAULT_PROVIDER_CONFIG_KEY);
+  } catch {
+    // An unreadable row falls back like an unset one: the default stays usable.
+  }
+  for (const raw of [stored, ctx.env[SYSTEM_ONE_DEFAULT_PROVIDER_CONFIG_KEY]]) {
+    const id = raw?.trim().toLowerCase();
+    if (isSystemOneProviderId(id)) return id;
+  }
+  return SYSTEM_ONE_DEFAULT_PROVIDER;
+}
+
 export function isSystemOneExtractProviderId(value: unknown): value is SystemOneExtractProviderId {
   return (
     typeof value === "string" &&
@@ -304,11 +330,15 @@ export function isSystemOneExtractProviderId(value: unknown): value is SystemOne
   );
 }
 
-/** Provider a raw node config selects. Undefined when the field is present but not a known id. */
+/**
+ * Provider a raw node config selects, `defaultId` when it names none. Undefined
+ * when the field is present but not a known id.
+ */
 export function systemOneProviderOf(
   config: Record<string, unknown>,
+  defaultId: SystemOneProviderId = SYSTEM_ONE_DEFAULT_PROVIDER,
 ): SystemOneProviderId | undefined {
-  if (config.provider === undefined) return SYSTEM_ONE_DEFAULT_PROVIDER;
+  if (config.provider === undefined) return defaultId;
   return isSystemOneProviderId(config.provider) ? config.provider : undefined;
 }
 
@@ -489,7 +519,12 @@ export type SystemOneTarget =
       /** The secret name the key was read under, for a rejection message. */
       keyName: string;
     }
-  | { ok: false; error: string };
+  | {
+      ok: false;
+      error: string;
+      /** This deployment refuses the host whatever its credential (`deploymentProblem`). */
+      deploymentRefused?: true;
+    };
 
 export interface SystemOneTargetOverrides {
   /** Replaces the credential lookup. */
@@ -517,7 +552,7 @@ export async function resolveSystemOneTarget(
   const capability = overrides.capability ?? "decide";
   const service = serviceOf(id, capability);
   const deploymentProblem = host.deploymentProblem?.(ctx.env);
-  if (deploymentProblem) return { ok: false, error: deploymentProblem };
+  if (deploymentProblem) return { ok: false, error: deploymentProblem, deploymentRefused: true };
 
   const errors: string[] = [];