@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/workflows/engine.ts

@@ -20,6 +20,7 @@ import {
   updateWorkflowRun,
   updateWorkflowRunStep,
 } from "../be/db";
+import { WorkflowReplayStateError } from "../be/workflow-replay";
 import { telemetry } from "../telemetry";
 import type { Workflow, WorkflowDefinition, WorkflowNode, WorkflowRunStep } from "../types";
 import { checkpointStep, checkpointStepFailure, checkpointStepWaiting } from "./checkpoint";
@@ -226,6 +227,32 @@ const activeWalks = new Map<string, number>();
 // left behind is not mistaken for a live execution.
 const executingSteps = new Set<string>();
 
+/**
+ * Fail closed when a run's sealed replay state cannot be opened. Resuming from
+ * the scrubbed copy would feed redaction markers to downstream nodes, so the
+ * run (and `stepId`, when one was claimed) fails with the error instead.
+ * Returns false, writing nothing, for any other error.
+ */
+export async function failRunOnUnreadableReplay(
+  runId: string,
+  err: unknown,
+  stepId?: string,
+): Promise<boolean> {
+  if (!(err instanceof WorkflowReplayStateError)) return false;
+  const finishedAt = new Date().toISOString();
+  console.error(`[workflow] ${err.message}`);
+  if (stepId) {
+    await updateWorkflowRunStep(stepId, {
+      status: "failed",
+      error: err.message,
+      finishedAt,
+      nextRetryAt: null,
+    });
+  }
+  await updateWorkflowRun(runId, { status: "failed", error: err.message, finishedAt });
+  return true;
+}
+
 export function isWorkflowRunActive(runId: string): boolean {
   return activeWalks.has(runId);
 }
@@ -267,6 +294,8 @@ export async function walkGraph(
   const release = holdWorkflowRun(runId);
   try {
     await walkGraphOwned(def, runId, ctx, startNodes, registry, workflowId, secretKeys, options);
+  } catch (err) {
+    if (!(await failRunOnUnreadableReplay(runId, err))) throw err;
   } finally {
     release();
   }
@@ -374,10 +403,11 @@ async function walkGraphOwned(
     const results = await Promise.all(
       pendingNodes.map((node) =>
         executeStep(def, runId, ctx, node, registry, workflowId, secretKeys, options).catch(
-          (_err): StepResult => ({
-            outcome: "failed",
-            successors: [],
-          }),
+          async (err): Promise<StepResult> => {
+            // The run-status check below then stops the walk.
+            await failRunOnUnreadableReplay(runId, err);
+            return { outcome: "failed", successors: [] };
+          },
         ),
       ),
     );
@@ -742,6 +772,11 @@ async function executeStep(
       workflowId,
       options,
     );
+  } catch (err) {
+    if (await failRunOnUnreadableReplay(runId, err, dedup.stepId)) {
+      return { outcome: "failed", successors: [] };
+    }
+    throw err;
   } finally {
     executingSteps.delete(dedup.stepId);
   }

package/src/workflows/executors/notify.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
+import { scrubSecrets } from "../../utils/secret-scrubber";
 import { BaseExecutor, type ExecutorResult } from "./base";
 
 // ─── Schemas ────────────────────────────────────────────────
@@ -32,7 +33,11 @@ export class NotifyExecutor extends BaseExecutor<
     context: Readonly<Record<string, unknown>>,
     _meta: ExecutorMeta,
   ): Promise<ExecutorResult<z.infer<typeof NotifyOutputSchema>>> {
-    const message = this.deps.interpolate(config.template, context as Record<string, unknown>);
+    // Scrub once: the message reaches Slack, the swarm channel, a log line and
+    // the step output.
+    const message = scrubSecrets(
+      this.deps.interpolate(config.template, context as Record<string, unknown>),
+    );
 
     switch (config.channel) {
       case "swarm": {

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

@@ -24,8 +24,11 @@ import {
   type SystemOneProvider,
   type SystemOneProviderId,
   systemOneKeyRejectedMessage,
+  systemOneModelProblem,
   systemOneProviderOf,
+  systemOneQuestionLimitProblem,
 } from "./system-one-providers";
+import { cloudflareErrorCode, SYSTEM_ONE_WIRE, SystemOneWireError } from "./system-one-wire";
 
 // ─── Constants ──────────────────────────────────────────────
 
@@ -226,6 +229,15 @@ 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.
+    const modelProblem = systemOneModelProblem(
+      config.provider,
+      config.model ?? (SYSTEM_ONE_PROVIDERS[config.provider] as SystemOneProvider).defaultModel,
+    );
+    if (modelProblem) ctx.addIssue({ code: "custom", path: ["model"], message: modelProblem });
+    const limitProblem = systemOneQuestionLimitProblem(config.provider, questionIds.length);
+    if (limitProblem) ctx.addIssue({ code: "custom", path: ["questions"], message: limitProblem });
   });
 
 export type SystemOneDecisionConfig = z.infer<typeof SystemOneDecisionConfigSchema>;
@@ -805,7 +817,8 @@ const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
 const ERROR_CODE_RE = /^[A-Za-z0-9._:-]{1,64}$/;
 
 function readRequestId(headers: Headers): string | undefined {
-  const value = headers.get("x-request-id") ?? headers.get("request-id");
+  // Cloudflare marks every response with `cf-ray` and sends no request id.
+  const value = headers.get("x-request-id") ?? headers.get("request-id") ?? headers.get("cf-ray");
   return value && REQUEST_ID_RE.test(value) ? value : undefined;
 }
 
@@ -839,7 +852,8 @@ function readErrorCode(text: string): string | undefined {
   ]) {
     if (typeof candidate === "string" && ERROR_CODE_RE.test(candidate)) return candidate;
   }
-  return undefined;
+  // Cloudflare's envelope: `{ success: false, errors: [{ code: 10000, message }] }`.
+  return cloudflareErrorCode(parsed);
 }
 
 function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
@@ -878,10 +892,11 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     return { db: this.deps.db, env: this.options.env ?? process.env };
   }
 
-  private resolveTarget(id: SystemOneProviderId) {
+  private resolveTarget(id: SystemOneProviderId, model?: string) {
     return resolveSystemOneTarget(id, this.providerContext(), {
       apiKey: this.options.getApiKey,
       serverUrl: this.options.getServerUrl,
+      model,
     });
   }
 
@@ -922,17 +937,17 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
 
     const providerId = config.provider;
     const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[providerId];
-    const target = await this.resolveTarget(providerId);
-    if (!target.ok) return { status: "failed", error: target.error };
-    const { apiKey, endpoint } = target;
 
     // A provider with no default sends no `model` when the node sets none.
     const model = config.model ?? provider.defaultModel;
-    const body = JSON.stringify({
-      state: config.state,
-      ...(model === undefined ? {} : { model }),
-      questions: config.questions,
-    });
+    const modelProblem = systemOneModelProblem(providerId, model);
+    if (modelProblem) return { status: "failed", error: modelProblem };
+    const target = await this.resolveTarget(providerId, model);
+    if (!target.ok) return { status: "failed", error: target.error };
+    const { apiKey, endpoint } = target;
+
+    const wire = provider.wire ?? SYSTEM_ONE_WIRE;
+    const body = JSON.stringify(wire.buildRequest(config, model));
 
     const scrub = (message: string) => message.split(apiKey).join("[REDACTED]");
     const sent = await this.send(
@@ -955,11 +970,15 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     try {
       decision = validateSystemOneResponse(
         config.questions,
-        parsed,
+        wire.toSystemOne(parsed, { questions: config.questions, model }),
         sent.requestId,
         provider.confidenceField,
       );
     } catch (err) {
+      if (err instanceof SystemOneWireError) {
+        const withId = sent.requestId ? `${err.message} [request ${sent.requestId}]` : err.message;
+        return { status: "failed", error: scrub(withId) };
+      }
       if (err instanceof SystemOneContractError) {
         return {
           status: "failed",

package/src/workflows/executors/system-one-openai-wire.ts

@@ -0,0 +1,168 @@
+import type { SystemOneQuestion } from "./system-one-decision";
+import {
+  isRecord,
+  type SystemOneWire,
+  SystemOneWireError,
+  wireContractError,
+} from "./system-one-wire";
+
+/**
+ * The OpenAI Decisions API (`POST /v1/decisions`, public beta) as a SystemOne host.
+ *
+ * Request: `{ model, input, questions: [...] }`. Questions are an array named by
+ * the node's question ids: `noul` becomes `predicate`, `choice` lists `choices`,
+ * `score` lists `levels`. Response: `answers` is an array in question order, each
+ * echoing `name`; choice and score probabilities are arrays of `{ value, probability }`.
+ * Both directions are translated here so the rest of the node sees SystemOne.
+ */
+
+type Entry = string | null | unknown[] | Record<string, unknown>;
+
+/** A criterion as text: a string as is, structure as JSON, null as nothing. */
+function entryText(entry: Entry | undefined): string | undefined {
+  if (entry === undefined || entry === null) return undefined;
+  return typeof entry === "string" ? entry : JSON.stringify(entry);
+}
+
+function openaiInput(state: unknown): unknown {
+  if (typeof state === "string") return state;
+  if (Array.isArray(state)) {
+    return [
+      {
+        role: "user",
+        content: state.map((text) => ({ type: "input_text", text: String(text) })),
+      },
+    ];
+  }
+  // The API reads text and images only, so structured state is sent as JSON text.
+  return JSON.stringify(state);
+}
+
+function openaiQuestion(name: string, question: SystemOneQuestion): Record<string, unknown> {
+  const instructions = entryText(question.instructions) ?? "";
+  switch (question.type) {
+    case "noul": {
+      // A predicate has no true/false descriptions; they become part of the instructions.
+      const whenTrue = entryText(question.criteria?.true);
+      const whenFalse = entryText(question.criteria?.false);
+      const parts = [instructions];
+      if (whenTrue) parts.push(`True when: ${whenTrue}`);
+      if (whenFalse) parts.push(`False when: ${whenFalse}`);
+      return { type: "predicate", name, instructions: parts.join("\n\n") };
+    }
+    case "choice":
+      return {
+        type: "choice",
+        name,
+        instructions,
+        choices: Object.entries(question.criteria).map(([value, entry]) => {
+          const description = entryText(entry);
+          return description === undefined ? { value } : { value, description };
+        }),
+      };
+    case "score":
+      return {
+        type: "score",
+        name,
+        instructions,
+        // `label` is required, so a level with no description is named by its index.
+        levels: question.criteria.map((entry, index) => ({
+          label: entryText(entry) ?? String(index),
+        })),
+      };
+  }
+}
+
+/** `[{ value, probability }]` as `{ [value]: probability }`. Anything else is left for the validator. */
+function probabilityMap(value: unknown, at: string): unknown {
+  if (!Array.isArray(value)) return value;
+  const out: Record<string, unknown> = {};
+  for (const item of value) {
+    if (!isRecord(item) || (typeof item.value !== "string" && typeof item.value !== "number")) {
+      wireContractError(`${at} entries must carry a string or number value`);
+    }
+    const key = String(item.value);
+    if (Object.hasOwn(out, key)) wireContractError(`${at} lists an option twice`);
+    out[key] = item.probability;
+  }
+  return out;
+}
+
+function toSystemOneAnswer(id: string, question: SystemOneQuestion, raw: Record<string, unknown>) {
+  const at = `answer "${id}".probabilities`;
+  switch (raw.type) {
+    case "predicate":
+      return { type: "noul", noul: raw.probability };
+    case "choice":
+      return {
+        type: "choice",
+        choice: raw.choice,
+        probabilities: probabilityMap(raw.probabilities, at),
+        confidence: raw.confidence,
+      };
+    case "score":
+      return {
+        type: "score",
+        score: raw.score,
+        probabilities: probabilityMap(raw.probabilities, at),
+        // OpenAI does not echo the levels; the legend is the node's own criteria.
+        legend:
+          question.type === "score"
+            ? Object.fromEntries(question.criteria.map((entry, index) => [String(index), entry]))
+            : undefined,
+        confidence: raw.confidence,
+      };
+    default:
+      // The validator reports the type mismatch against the declared question.
+      return raw;
+  }
+}
+
+export const OPENAI_DECISIONS_WIRE: SystemOneWire = {
+  buildRequest: (config, model) => ({
+    ...(model === undefined ? {} : { model }),
+    input: openaiInput(config.state),
+    questions: Object.entries(config.questions).map(([name, question]) =>
+      openaiQuestion(name, question),
+    ),
+  }),
+
+  toSystemOne(body, { questions }) {
+    if (!isRecord(body)) wireContractError("response body must be a JSON object");
+    if (!Array.isArray(body.answers)) wireContractError("response is missing the answers array");
+
+    const byName = new Map<string, Record<string, unknown>>();
+    for (const answer of body.answers) {
+      if (!isRecord(answer) || typeof answer.name !== "string") {
+        wireContractError("every answer must be an object naming its question");
+      }
+      if (!Object.hasOwn(questions, answer.name)) {
+        wireContractError("response contains an answer for an undeclared question");
+      }
+      if (byName.has(answer.name)) {
+        wireContractError(`response answers question "${answer.name}" twice`);
+      }
+      byName.set(answer.name, answer);
+    }
+
+    // A refusal is not an answer of the declared type, so no decision is made.
+    const refused = [...byName.values()]
+      .filter((answer) => answer.type === "refusal")
+      .map((answer) => `"${answer.name}"`);
+    if (refused.length > 0) {
+      throw new SystemOneWireError(
+        `OpenAI refused question${refused.length > 1 ? "s" : ""} ${refused.join(", ")}; no decision was made`,
+      );
+    }
+
+    const answers: Record<string, unknown> = {};
+    for (const [id, answer] of byName) {
+      const question = questions[id];
+      if (question) answers[id] = toSystemOneAnswer(id, question, answer);
+    }
+    const usage = isRecord(body.usage)
+      ? { input_tokens: body.usage.input_tokens, output_tokens: body.usage.output_tokens }
+      : body.usage;
+    return { model: body.model, answers, usage };
+  },
+};

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

@@ -1,13 +1,17 @@
 import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
 import type { ExecutorDependencies } from "./base";
+import { OPENAI_DECISIONS_WIRE } from "./system-one-openai-wire";
+import { CLOUDFLARE_WIRE, type SystemOneWire } from "./system-one-wire";
 import { resolveWorkflowLlmConfig } from "./workflow-llm";
 
 /**
- * Hosts that serve typed decisions (Jev, laya). A `system-one-decision` node names one by id
- * (`config.provider`); the endpoint, header shape, and key name live here, never
- * in a workflow definition. Every host takes the same `{ state, model, questions }`
- * request and returns the same `{ model, answers, usage }` body, so the answer
- * contract in `system-one-decision.ts` is shared. Adding a host is one entry in `SYSTEM_ONE_PROVIDERS`.
+ * Hosts that serve typed decisions (Jev, laya, OpenAI Decisions, Cloudflare Clef). A
+ * `system-one-decision` node names one by id (`config.provider`); the endpoint, header
+ * shape, and key name live here, never in a workflow definition. Most hosts take the
+ * SystemOne `{ state, model, questions }` request and return its `{ model, answers, usage }`
+ * body; a host that does not supplies a `wire` that translates both ways, so the
+ * answer contract in `system-one-decision.ts` is shared. Adding a host is one entry
+ * in `SYSTEM_ONE_PROVIDERS`.
  *
  * Do not add a chat-completions route. OpenRouter's `typesafe/jev-router` is a
  * router that forwards a chat request to another model, and `~typesafe/jev-latest`
@@ -31,18 +35,37 @@ export interface SystemOneConfiguredEndpoint {
   readonly path: string;
 }
 
+/**
+ * A host whose URL is built from a global config value and the model, e.g. an
+ * account id in the path. The value is checked before it reaches the URL.
+ */
+export interface SystemOneBuiltEndpoint {
+  /** Global config key holding the value, e.g. `CLOUDFLARE_ACCOUNT_ID`. */
+  readonly configKey: string;
+  /** What the value is, for messages: "the account id of a Cloudflare account". */
+  readonly describe: string;
+  /** Request URL, or null when the value is not usable. `model` is already allowlisted. */
+  readonly build: (value: string, model: string) => string | null;
+}
+
 export interface SystemOneProvider {
   /** Name used in messages, e.g. "TypeSafe". */
   readonly label: string;
   /** The single credential this host needs: a global secret name. */
   readonly keyName: string;
-  /** A fixed URL, or the global config key that names the server. */
-  readonly endpoint: string | SystemOneConfiguredEndpoint;
+  /** A fixed URL, the global config key that names the server, or a URL built from config and model. */
+  readonly endpoint: string | SystemOneConfiguredEndpoint | SystemOneBuiltEndpoint;
   /**
    * Model used when the node sets none. Absent means no `model` is sent and the
    * host picks, for a host that ignores a model id it does not know.
    */
   readonly defaultModel?: string;
+  /** When set, the only model ids the node may use (checked at save and at run). */
+  readonly allowedModels?: readonly string[];
+  /** Host limits stricter than the node's own. */
+  readonly limits?: { readonly maxQuestions?: number };
+  /** Request and response translation. Absent means the SystemOne wire as is. */
+  readonly wire?: SystemOneWire;
   /**
    * The field of a `choice` or `score` answer that is the answer's confidence: what
    * the output reports and what a `humanReview` band is tested against.
@@ -58,6 +81,10 @@ const TYPESAFE_KEY = "TYPESAFE_API_KEY";
 const OPENROUTER_KEY = "OPENROUTER_API_KEY";
 const LAYA_KEY = "LAYA_API_KEY";
 const LAYA_URL_KEY = "LAYA_URL";
+const OPENAI_DECISIONS_KEY = "OPENAI_DECISIONS_API_KEY";
+const CLOUDFLARE_TOKEN_KEY = "CLOUDFLARE_API_TOKEN";
+const CLOUDFLARE_ACCOUNT_KEY = "CLOUDFLARE_ACCOUNT_ID";
+const CLOUDFLARE_ACCOUNT_RE = /^[0-9a-f]{32}$/;
 
 /** Filter by key and scope in SQL so no other config row is read or decrypted. */
 async function readGlobalConfig(
@@ -113,6 +140,39 @@ export const SYSTEM_ONE_PROVIDERS = {
     confidenceField: "answer_confidence",
     readKey: ({ db }) => readGlobalConfig(db, LAYA_KEY),
   },
+  openai: {
+    label: "OpenAI",
+    // Not OPENAI_API_KEY: a global row of that name reaches every worker's env and
+    // can change harness auth. This key serves this node only, and needs Decisions access.
+    keyName: OPENAI_DECISIONS_KEY,
+    endpoint: "https://api.openai.com/v1/decisions",
+    defaultModel: "gpt-6-luna",
+    // OpenAI's own field; it is not the top probability.
+    confidenceField: "confidence",
+    wire: OPENAI_DECISIONS_WIRE,
+    readKey: ({ db }) => readGlobalConfig(db, OPENAI_DECISIONS_KEY),
+  },
+  cloudflare: {
+    label: "Cloudflare Workers AI",
+    keyName: CLOUDFLARE_TOKEN_KEY,
+    endpoint: {
+      configKey: CLOUDFLARE_ACCOUNT_KEY,
+      describe: "the 32-character id of a Cloudflare account",
+      build: (accountId, model) => {
+        const id = accountId.trim();
+        return CLOUDFLARE_ACCOUNT_RE.test(id)
+          ? `https://api.cloudflare.com/client/v4/accounts/${id}/ai/run/@cf/cloudflare/${model}`
+          : null;
+      },
+    },
+    defaultModel: "clef",
+    // The model is part of the URL, so only these ids are accepted.
+    allowedModels: ["clef", "clef-flash"],
+    limits: { maxQuestions: 64 },
+    confidenceField: "confidence",
+    wire: CLOUDFLARE_WIRE,
+    readKey: ({ db }) => readGlobalConfig(db, CLOUDFLARE_TOKEN_KEY),
+  },
 } as const satisfies Record<string, SystemOneProvider>;
 
 export type SystemOneProviderId = keyof typeof SYSTEM_ONE_PROVIDERS;
@@ -180,10 +240,23 @@ function urlKeyOf(provider: SystemOneProvider): string | null {
   return typeof provider.endpoint === "string" ? null : provider.endpoint.configKey;
 }
 
+function isBuiltEndpoint(
+  endpoint: SystemOneProvider["endpoint"],
+): endpoint is SystemOneBuiltEndpoint {
+  return typeof endpoint !== "string" && "build" in endpoint;
+}
+
+/** What a provider's config value names, for messages. */
+function urlDescriptionOf(provider: SystemOneProvider): string {
+  return isBuiltEndpoint(provider.endpoint)
+    ? provider.endpoint.describe
+    : `the URL of a ${provider.label} server`;
+}
+
 export function systemOneUrlMissingMessage(id: SystemOneProviderId): string {
   const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
   const configKey = urlKeyOf(provider) ?? "";
-  return `${configKey} is not configured. SystemOne provider "${id}" needs the URL of a ${provider.label} server. ${SET_URL(configKey)}`;
+  return `${configKey} is not configured. SystemOne provider "${id}" needs ${urlDescriptionOf(provider)}. ${SET_URL(configKey)}`;
 }
 
 export function systemOneUrlUnreadableMessage(id: SystemOneProviderId): string {
@@ -194,9 +267,33 @@ export function systemOneUrlInvalidMessage(id: SystemOneProviderId): string {
   const provider: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
   const configKey = urlKeyOf(provider) ?? "";
   // The value is not echoed: a URL can carry a credential.
+  if (isBuiltEndpoint(provider.endpoint)) {
+    return `${configKey} is not ${provider.endpoint.describe}. ${SET_URL(configKey)}`;
+  }
   return `${configKey} is not a usable ${provider.label} server URL. It must be an https URL (http only for localhost) with no credentials, query, or fragment. ${SET_URL(configKey)}`;
 }
 
+/** Why a provider cannot use this model, or null. The value is not echoed: it may come from run input. */
+export function systemOneModelProblem(
+  id: SystemOneProviderId,
+  model: string | undefined,
+): string | null {
+  const { allowedModels }: SystemOneProvider = SYSTEM_ONE_PROVIDERS[id];
+  if (!allowedModels || (model !== undefined && allowedModels.includes(model))) return null;
+  return `SystemOne provider "${id}" serves only the models ${allowedModels.join(", ")}; set model to one of them or leave it unset.`;
+}
+
+/** Why a provider cannot take this many questions, or null. */
+export function systemOneQuestionLimitProblem(
+  id: SystemOneProviderId,
+  count: number,
+): string | null {
+  const max = (SYSTEM_ONE_PROVIDERS[id] as SystemOneProvider).limits?.maxQuestions;
+  return max !== undefined && count > max
+    ? `SystemOne provider "${id}" takes at most ${max} questions per node; this node has ${count}.`
+    : null;
+}
+
 // ─── Credential and endpoint ────────────────────────────────
 
 /** A bearer token is one visible token; anything else would break or split the header. */
@@ -236,8 +333,10 @@ export type SystemOneTarget =
 export interface SystemOneTargetOverrides {
   /** Replaces the credential lookup. */
   apiKey?: (id: SystemOneProviderId) => Promise<string | null | undefined>;
-  /** Replaces the lookup of a configured server's base URL. */
+  /** Replaces the lookup of a configured server's base URL (or account id). */
   serverUrl?: (id: SystemOneProviderId) => Promise<string | null | undefined>;
+  /** The model the call uses, for a host whose URL names it. Defaults to the provider's default. */
+  model?: string;
 }
 
 /**
@@ -261,7 +360,7 @@ export async function resolveSystemOneTarget(
   if (typeof provider.endpoint === "string") {
     endpoint = provider.endpoint;
   } else {
-    const { configKey, path } = provider.endpoint;
+    const { configKey } = provider.endpoint;
     let base: string | null | undefined;
     let readable = true;
     try {
@@ -276,7 +375,9 @@ export async function resolveSystemOneTarget(
       if (!base || base.trim() === "") {
         errors.push(systemOneUrlMissingMessage(id));
       } else {
-        const resolved = systemOneEndpointFromBase(base, path);
+        const resolved = isBuiltEndpoint(provider.endpoint)
+          ? provider.endpoint.build(base, overrides.model ?? provider.defaultModel ?? "")
+          : systemOneEndpointFromBase(base, provider.endpoint.path);
         if (resolved) endpoint = resolved;
         else errors.push(systemOneUrlInvalidMessage(id));
       }

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

@@ -0,0 +1,79 @@
+import type { SystemOneDecisionConfig, SystemOneQuestion } from "./system-one-decision";
+
+/**
+ * How one provider's request and response map onto the SystemOne contract. Most
+ * hosts speak it natively (`SYSTEM_ONE_WIRE`). A host with another shape supplies
+ * a wire that builds its body and turns its success body back into the SystemOne
+ * shape, which `validateSystemOneResponse` then checks like any other.
+ */
+export interface SystemOneWire {
+  /** Request body for one call. */
+  buildRequest(config: SystemOneDecisionConfig, model: string | undefined): unknown;
+  /**
+   * Turn a parsed success body into the SystemOne `{ model, answers, usage }` shape,
+   * or throw a `SystemOneWireError`. The result is still validated afterwards.
+   */
+  toSystemOne(body: unknown, call: SystemOneWireCall): unknown;
+}
+
+export interface SystemOneWireCall {
+  questions: Record<string, SystemOneQuestion>;
+  /** The model the request named, when one was sent. */
+  model: string | undefined;
+}
+
+/**
+ * A success body the wire cannot turn into a decision. `message` is the whole step
+ * error: a shape problem carries the validation prefix, a refusal does not.
+ */
+export class SystemOneWireError extends Error {}
+
+export const VALIDATION_PREFIX = "SystemOne response failed validation: ";
+
+export function wireContractError(message: string): never {
+  throw new SystemOneWireError(`${VALIDATION_PREFIX}${message}`);
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The SystemOne request as is. The response needs no translation. */
+export const SYSTEM_ONE_WIRE: SystemOneWire = {
+  buildRequest: (config, model) => ({
+    state: config.state,
+    ...(model === undefined ? {} : { model }),
+    questions: config.questions,
+  }),
+  toSystemOne: (body) => body,
+};
+
+/**
+ * Cloudflare Workers AI. The request is the SystemOne request (Clef is SystemOne
+ * compatible); the response is wrapped in Cloudflare's `{ result, success, errors }`
+ * envelope.
+ */
+export const CLOUDFLARE_WIRE: SystemOneWire = {
+  buildRequest: SYSTEM_ONE_WIRE.buildRequest,
+  toSystemOne(body) {
+    if (!isRecord(body)) wireContractError("response body must be a JSON object");
+    if (body.success !== true) {
+      const code = cloudflareErrorCode(body);
+      throw new SystemOneWireError(
+        `Cloudflare Workers AI reported a failed run${code ? ` (${code})` : ""}. No decision was made.`,
+      );
+    }
+    if (!isRecord(body.result)) wireContractError("Cloudflare response is missing its result");
+    return body.result;
+  },
+};
+
+const ERROR_CODE_RE = /^[A-Za-z0-9._:-]{1,64}$/;
+
+/** `errors[0].code` of a Cloudflare envelope, a number or a short string, as text. */
+export function cloudflareErrorCode(body: Record<string, unknown>): string | undefined {
+  const first = Array.isArray(body.errors) ? body.errors[0] : undefined;
+  const code = isRecord(first) ? first.code : undefined;
+  if (typeof code === "number" && Number.isSafeInteger(code)) return String(code);
+  return typeof code === "string" && ERROR_CODE_RE.test(code) ? code : undefined;
+}