@desplega.ai/agent-swarm 2.4.2 → 2.4.4

package/src/types.ts

@@ -2287,7 +2287,7 @@ export const WorkflowNodeSchema = z
     type: z
       .string()
       .describe(
-        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'system-one-decision', 'validate', 'property-match'",
+        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'system-one-decision', 'system-one-extraction', 'validate', 'property-match'",
       ),
     label: z.string().optional().describe("Human-readable label for UI display"),
     config: z
@@ -2297,6 +2297,7 @@ export const WorkflowNodeSchema = z
           "For script: { runtime, script, args?, timeout? }. " +
           "For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode?, timeoutMs? (1000-300000) }. " +
           "For system-one-decision (typed decisions, Jev by default): { provider? ('typesafe' default | 'openrouter' | 'laya'; a literal, never a {{token}}), state, questions: { <id>: { type: 'noul'|'choice'|'score', instructions, criteria? } }, returns: { <id>: { type } }, model? (provider-specific; unset = the provider's default, and laya has none so it sends no model and picks its own checkpoint), timeoutMs?, maxRetries? (0-3), humanReview? { band: { min, max } (0-1, inclusive), approvers: { users?, roles?, policy }, title?, timeout?, notifications? } }; each provider needs its own global secret (TYPESAFE_API_KEY, OPENROUTER_API_KEY, or LAYA_API_KEY; laya also needs the global config LAYA_URL), and a save warns and a run fails before any node executes when one is missing; system-one-decision nodes must not set retry or validation.retry. With humanReview, an answer whose confidence is inside the band waits for a person (human-in-the-loop approval), and next must map ports { approved, rejected?, timeout? }. " +
+          "For system-one-extraction (typed extraction, Cloudflare Clairic by default): { provider? ('cloudflare'; a literal), state (text to read; may be empty when images are sent), fields: { <id>: { type: 'text'|'number'|'date'|'time'|'datetime'|'duration'|'list'|'estimate'|'forecast', instructions?, ...type options (number: unit?, integer?, decimals?; duration: unit? (seconds..years), integer?, decimals?; list: items ('text'|'number'|'date'); estimate: min, max, step?, scale?, unit?; forecast: min, max, horizon?, interval?, scale?, unit?; text/number/date/time/datetime/duration: null_threshold?) } }, images? (max 4 base64 data: URLs or { content_type, base64 }), referenceDate? (YYYY-MM-DD), model?, timeoutMs?, maxRetries? (0-3) }; output answers.<id> carries value (null when the input does not say), guess, p_null, confidence, span/spans, and for estimate/forecast median/p10/p90. Needs the global secret CLOUDFLARE_API_TOKEN (or CLOUDFLARE_API_KEY) and the global config CLOUDFLARE_ACCOUNT_ID; must not set retry or validation.retry. " +
           "Agent-task templates and ordinary config values support {{interpolation}} from the node's inputs context, including trigger and declared upstream aliases. " +
           "SECURITY: executable source for script/swarm-script nodes does not interpolate trigger.* or upstream node outputs; only input/workflow/swarm/run values are allowed in inline script source, and named swarm-script source is not workflow-interpolated. " +
           'Pass dynamic values through config.args instead (inline script receives them as argv, with runtime: "bash" running bash -c <script> ...args so args[0] is $0 and args[1] is $1; swarm-script receives its args object). ' +

package/src/utils/env-flag.ts

@@ -53,3 +53,12 @@ export function isEnvFlagEnabled(
 ): boolean {
   return parseEnvFlag(env[key], defaultValue);
 }
+
+/**
+ * Whether the session-end summary is turned off via `SKIP_SESSION_SUMMARY`.
+ * Every harness (claude Stop hook, pi, opencode, codex) gates on this, so
+ * `1`/`true` skip and unset/empty/`0`/`false` keep the summary everywhere.
+ */
+export function isSessionSummarySkipped(env: NodeJS.ProcessEnv = process.env): boolean {
+  return isEnvFlagEnabled("SKIP_SESSION_SUMMARY", false, env);
+}

package/src/utils/request-auth-context.ts

@@ -8,9 +8,10 @@ export type HttpRequestAuth = (
   /** Password-page viewer with no user identity. Least privilege: every gate denies it. */
   | { kind: "guest" }
   | { kind: "controller"; controllerId: string; tokenId: string; expiresAt: string }
-  /** Ephemeral token bound to an ACP task or a worker runtime (aseph_ prefix). */
+  /** Session token bound to an ACP task, a worker runtime, or only its agent (aseph_ prefix). */
   | {
       kind: "agent";
+      tokenKind: "task" | "runtime" | "agent";
       agentId: string;
       taskId: string | null;
       runtimeId: string | null;

package/src/workflows/definition.ts

@@ -10,6 +10,7 @@ import {
   systemOneRetryViolations,
   systemOneStaticShapeViolations,
 } from "./executors/system-one-decision";
+import { systemOneExtractionStaticShapeViolations } from "./executors/system-one-extraction";
 
 /** Extract all target node IDs from a node's `next` field */
 export function getNextTargets(next: string | string[] | Record<string, string>): string[] {
@@ -212,7 +213,12 @@ export function validateDefinition(
     }
     // A system-one-decision node's question ids and return types are static, and it never carries
     // an engine retry policy (it retries transient transport errors itself).
-    errors.push(...systemOneStaticShapeViolations(node), ...systemOneRetryViolations(node));
+    // A system-one-extraction node's field ids and types are static in the same way.
+    errors.push(
+      ...systemOneStaticShapeViolations(node),
+      ...systemOneExtractionStaticShapeViolations(node),
+      ...systemOneRetryViolations(node),
+    );
     if (node.type === "foreach") {
       validateForeachNode(node, errors);
       // A legacy `#` id may stay editable as a NORMAL node, but never as a foreach

package/src/workflows/engine.ts

@@ -30,7 +30,7 @@ import { findEntryNodes, getNextTargets, getSuccessors, resolveValidationPort }
 import type { AsyncExecutorResult } from "./executors/base";
 import type { ExecutorRegistry } from "./executors/registry";
 import {
-  SYSTEM_ONE_DECISION_NODE_TYPE,
+  isSystemOneNodeType,
   systemOneRetryViolations,
   systemOneUnresolvedError,
 } from "./executors/system-one-decision";
@@ -854,7 +854,7 @@ async function runClaimedStep(
     await checkpointStepFailure(
       runId,
       stepId,
-      systemOneUnresolvedError(node.id, strictUnresolved),
+      systemOneUnresolvedError(node.id, strictUnresolved, node.type),
       0,
     );
     return { outcome: "failed", successors: [] };
@@ -1150,6 +1150,9 @@ function buildScriptBodyCtx(
   return safe;
 }
 
+/** System One config fields whose whole-token references keep their JSON type. */
+const SYSTEM_ONE_DATA_FIELDS = new Set(["state", "questions", "fields", "images"]);
+
 export function interpolateNodeConfig(
   node: Pick<WorkflowNode, "type" | "config" | "inputs">,
   interpolationCtx: Record<string, unknown>,
@@ -1160,17 +1163,20 @@ export function interpolateNodeConfig(
   /** Tokens that must resolve before dispatch; the caller fails the step when non-empty. */
   strictUnresolved?: string[];
 } {
-  if (node.type === SYSTEM_ONE_DECISION_NODE_TYPE) {
-    // `state` and `questions` keep a whole-token reference's JSON type (an object
-    // stays an object; string interpolation would flatten it to JSON text). The
-    // resolved value is data, never re-interpolated, so a literal `{{` inside a
-    // lead's text is not read as another template. Every other field, and every
-    // unresolved token anywhere in the config, is strict: no blank reaches the API.
-    const { state, questions, ...rest } = node.config;
-    const restResult = deepInterpolate(rest, interpolationCtx);
+  if (isSystemOneNodeType(node.type)) {
+    // `state` and the question / field specs (and extraction `images`) keep a
+    // whole-token reference's JSON type (an object stays an object; string
+    // interpolation would flatten it to JSON text). The resolved value is data,
+    // never re-interpolated, so a literal `{{` inside a lead's text is not read as
+    // another template. Every other field, and every unresolved token anywhere in
+    // the config, is strict: no blank reaches the API.
+    const rest: Record<string, unknown> = {};
     const dynamic: Record<string, unknown> = {};
-    if (Object.hasOwn(node.config, "state")) dynamic.state = state;
-    if (Object.hasOwn(node.config, "questions")) dynamic.questions = questions;
+    for (const [key, value] of Object.entries(node.config)) {
+      if (SYSTEM_ONE_DATA_FIELDS.has(key)) dynamic[key] = value;
+      else rest[key] = value;
+    }
+    const restResult = deepInterpolate(rest, interpolationCtx);
     const dynamicResult = deepInterpolate(dynamic, interpolationCtx, { preserveRawTokens: true });
     const unresolved = [...restResult.unresolved, ...dynamicResult.unresolved];
     return {

package/src/workflows/executors/index.ts

@@ -14,6 +14,7 @@ export { createExecutorRegistry, ExecutorRegistry } from "./registry";
 export { ScriptExecutor } from "./script";
 export { SwarmScriptExecutor } from "./swarm-script";
 export { SystemOneDecisionExecutor } from "./system-one-decision";
+export { SystemOneExtractionExecutor } from "./system-one-extraction";
 export { ValidateExecutor } from "./validate";
 export { VcsExecutor } from "./vcs";
 export { WaitExecutor } from "./wait";

package/src/workflows/executors/registry.ts

@@ -11,6 +11,7 @@ import { ScriptExecutor } from "./script";
 import { SubWorkflowExecutor } from "./sub-workflow";
 import { SwarmScriptExecutor } from "./swarm-script";
 import { SystemOneDecisionExecutor } from "./system-one-decision";
+import { SystemOneExtractionExecutor } from "./system-one-extraction";
 import { ValidateExecutor } from "./validate";
 import { VcsExecutor } from "./vcs";
 import { WaitExecutor } from "./wait";
@@ -72,6 +73,7 @@ export function createExecutorRegistry(deps: ExecutorDependencies): ExecutorRegi
   registry.register(new NotifyExecutor(deps));
   registry.register(new RawLlmExecutor(deps));
   registry.register(new SystemOneDecisionExecutor(deps));
+  registry.register(new SystemOneExtractionExecutor(deps));
   registry.register(new ScriptExecutor(deps));
   registry.register(new SwarmScriptExecutor(deps));
   registry.register(new VcsExecutor(deps));

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

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
-import { getOpenRouterAttributionHeaders } from "../../utils/openrouter-base-url";
 import { scrubSecrets } from "../../utils/secret-scrubber";
 import {
   type ApprovalOutcome,
@@ -17,6 +16,7 @@ import {
   HumanInTheLoopExecutor,
   NotificationConfigSchema,
 } from "./human-in-the-loop";
+import { SYSTEM_ONE_EXTRACTION_NODE_TYPE } from "./system-one-extraction";
 import {
   resolveSystemOneTarget,
   SYSTEM_ONE_DEFAULT_PROVIDER,
@@ -24,12 +24,20 @@ import {
   SYSTEM_ONE_PROVIDERS,
   type SystemOneProvider,
   type SystemOneProviderId,
-  systemOneKeyRejectedMessage,
   systemOneModelProblem,
   systemOneProviderOf,
   systemOneQuestionLimitProblem,
 } from "./system-one-providers";
-import { cloudflareErrorCode, SYSTEM_ONE_WIRE, SystemOneWireError } from "./system-one-wire";
+import {
+  SYSTEM_ONE_DEFAULT_MAX_RETRIES,
+  SYSTEM_ONE_DEFAULT_TIMEOUT_MS,
+  SYSTEM_ONE_MAX_RETRIES_LIMIT,
+  SYSTEM_ONE_MAX_TIMEOUT_MS,
+  SYSTEM_ONE_MIN_TIMEOUT_MS,
+  type SystemOneTransportOptions,
+  sendSystemOneRequest,
+} from "./system-one-transport";
+import { SYSTEM_ONE_WIRE, SystemOneWireError } from "./system-one-wire";
 
 // ─── Constants ──────────────────────────────────────────────
 
@@ -43,11 +51,13 @@ export const SYSTEM_ONE_DECISION_NODE_TYPE = "system-one-decision";
 export const SYSTEM_ONE_ENDPOINT = SYSTEM_ONE_PROVIDERS.typesafe.endpoint;
 export const SYSTEM_ONE_API_KEY_CONFIG_KEY = SYSTEM_ONE_PROVIDERS.typesafe.keyName;
 
-export const SYSTEM_ONE_DEFAULT_TIMEOUT_MS = 30_000;
-export const SYSTEM_ONE_MIN_TIMEOUT_MS = 1_000;
-export const SYSTEM_ONE_MAX_TIMEOUT_MS = 300_000;
-export const SYSTEM_ONE_DEFAULT_MAX_RETRIES = 2;
-export const SYSTEM_ONE_MAX_RETRIES_LIMIT = 3;
+export {
+  SYSTEM_ONE_DEFAULT_MAX_RETRIES,
+  SYSTEM_ONE_DEFAULT_TIMEOUT_MS,
+  SYSTEM_ONE_MAX_RETRIES_LIMIT,
+  SYSTEM_ONE_MAX_TIMEOUT_MS,
+  SYSTEM_ONE_MIN_TIMEOUT_MS,
+};
 
 /** Choice: 2-255 options, Score: 2-10 levels (TypeSafe primitive limits; 2 is our authoring floor). */
 const CHOICE_MIN_OPTIONS = 2;
@@ -55,14 +65,8 @@ const CHOICE_MAX_OPTIONS = 255;
 const SCORE_MIN_LEVELS = 2;
 const SCORE_MAX_LEVELS = 10;
 
-/** Room left before the engine watchdog fires so the executor can report its own failure. */
-const DEADLINE_MARGIN_MS = 250;
-const BACKOFF_BASE_MS = 500;
-const BACKOFF_CAP_MS = 8_000;
 /** A returned distribution must sum to 1 within this tolerance. It is checked, never normalized. */
 const DISTRIBUTION_TOLERANCE = 0.02;
-const MAX_RESPONSE_CHARS = 1_048_576;
-const MAX_ERROR_BODY_CHARS = 65_536;
 
 /** Output ports of a node that sets `humanReview`, the same names `human-in-the-loop` uses. */
 const REVIEW_PORTS = ["approved", "rejected", "timeout"] as const;
@@ -316,8 +320,18 @@ interface RetryShape {
   maxRetries?: number;
 }
 
+/** Node types that call a System One host: paid, non-idempotent, with their own transient retries. */
+const SYSTEM_ONE_NODE_LABELS: Record<string, string> = {
+  [SYSTEM_ONE_DECISION_NODE_TYPE]: "SystemOne Decision",
+  [SYSTEM_ONE_EXTRACTION_NODE_TYPE]: "SystemOne Extraction",
+};
+
+export function isSystemOneNodeType(type: string): boolean {
+  return Object.hasOwn(SYSTEM_ONE_NODE_LABELS, type);
+}
+
 /**
- * Why a `system-one-decision` node may not carry an engine retry policy.
+ * Why a `system-one-decision` (or `system-one-extraction`) node may not carry an engine retry policy.
  *
  * The executor owns its transient retries (`config.maxRetries`). Engine retries
  * are not status-aware, so a node-level or validation retry would re-send 401 / 422
@@ -329,18 +343,18 @@ export function systemOneRetryViolations(node: {
   retry?: RetryShape | null;
   validation?: { retry?: RetryShape | null } | null;
 }): string[] {
-  if (node.type !== SYSTEM_ONE_DECISION_NODE_TYPE) return [];
+  if (!isSystemOneNodeType(node.type)) return [];
   const violations: string[] = [];
   const attempts = (retry: RetryShape | null | undefined) =>
     retry ? (retry.maxRetries ?? ENGINE_RETRY_DEFAULT) : 0;
   if (attempts(node.retry) > 0) {
     violations.push(
-      `Node "${node.id}" (system-one-decision) must not set retry.maxRetries > 0: the system-one-decision executor retries transient transport errors itself (config.maxRetries), and engine retries would re-send rejected requests`,
+      `Node "${node.id}" (${node.type}) must not set retry.maxRetries > 0: the ${node.type} executor retries transient transport errors itself (config.maxRetries), and engine retries would re-send rejected requests`,
     );
   }
   if (attempts(node.validation?.retry) > 0) {
     violations.push(
-      `Node "${node.id}" (system-one-decision) must not set validation.retry.maxRetries > 0: a validation-driven retry would send another paid request`,
+      `Node "${node.id}" (${node.type}) must not set validation.retry.maxRetries > 0: a validation-driven retry would send another paid request`,
     );
   }
   return violations;
@@ -397,11 +411,17 @@ export function systemOneStaticShapeViolations(node: {
   return violations;
 }
 
-/** The engine fails a system-one-decision step before dispatch when any config token is unresolved. */
-export function systemOneUnresolvedError(nodeId: string, tokens: string[]): string {
+/** The engine fails a System One step before dispatch when any config token is unresolved. */
+export function systemOneUnresolvedError(
+  nodeId: string,
+  tokens: string[],
+  nodeType: string = SYSTEM_ONE_DECISION_NODE_TYPE,
+): string {
   const rendered = [...new Set(tokens)].map((token) => `{{${token}}}`).join(", ");
+  const label =
+    SYSTEM_ONE_NODE_LABELS[nodeType] ?? SYSTEM_ONE_NODE_LABELS[SYSTEM_ONE_DECISION_NODE_TYPE];
   return (
-    `SystemOne Decision node "${nodeId}" has unresolved interpolation token(s): ${rendered}. ` +
+    `${label} node "${nodeId}" has unresolved interpolation token(s): ${rendered}. ` +
     "No request was sent. Declare the value in the node's inputs mapping or fix the path."
   );
 }
@@ -795,79 +815,13 @@ export function resolveReviewedDecision(
 
 // ─── Transport ──────────────────────────────────────────────
 
-export interface SystemOneDecisionExecutorOptions {
-  /** Transport. Tests inject a fake; production uses the global `fetch`. */
-  fetch?: typeof fetch;
+export interface SystemOneDecisionExecutorOptions extends SystemOneTransportOptions {
   /** Credential lookup for any provider. Defaults to each provider's own source (see `SYSTEM_ONE_PROVIDERS`). */
   getApiKey?: (provider: SystemOneProviderId) => Promise<string | null | undefined>;
   /** Base-URL lookup for a provider with no fixed host (`laya`). Defaults to its global config value. */
   getServerUrl?: (provider: SystemOneProviderId) => Promise<string | null | undefined>;
   /** Environment the OpenRouter credential is resolved from. Defaults to `process.env`. */
   env?: NodeJS.ProcessEnv;
-  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
-  now?: () => number;
-  random?: () => number;
-}
-
-type Attempt =
-  | { kind: "ok"; text: string; requestId?: string }
-  | { kind: "timeout" }
-  | { kind: "fail"; message: string; retryable: boolean; retryAfterMs?: number };
-
-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 {
-  // 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;
-}
-
-/** Retry-After as delta-seconds or an HTTP date, in ms. Undefined when absent or unparseable. */
-function parseRetryAfter(value: string | null, now: number): number | undefined {
-  if (!value) return undefined;
-  const trimmed = value.trim();
-  if (/^\d+(\.\d+)?$/.test(trimmed)) return Math.round(Number(trimmed) * 1000);
-  const at = Date.parse(trimmed);
-  return Number.isNaN(at) ? undefined : Math.max(0, at - now);
-}
-
-/** Only a short identifier from the provider's error envelope. Never its message or echoed request. */
-function readErrorCode(text: string): string | undefined {
-  if (text.length === 0 || text.length > MAX_ERROR_BODY_CHARS) return undefined;
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-  if (!isRecord(parsed)) return undefined;
-  const nested = isRecord(parsed.error) ? parsed.error : undefined;
-  const detail = isRecord(parsed.detail) ? parsed.detail : undefined;
-  for (const candidate of [
-    nested?.code,
-    nested?.type,
-    detail?.error_type,
-    parsed.code,
-    parsed.type,
-  ]) {
-    if (typeof candidate === "string" && ERROR_CODE_RE.test(candidate)) return candidate;
-  }
-  // Cloudflare's envelope: `{ success: false, errors: [{ code: 10000, message }] }`.
-  return cloudflareErrorCode(parsed);
-}
-
-function defaultSleep(ms: number, signal: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
-    if (signal.aborted) return resolve();
-    const timer = setTimeout(done, ms);
-    function done() {
-      clearTimeout(timer);
-      signal.removeEventListener("abort", done);
-      resolve();
-    }
-    signal.addEventListener("abort", done, { once: true });
-  });
 }
 
 // ─── Executor ───────────────────────────────────────────────
@@ -959,19 +913,25 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
     if (modelProblem) return { ok: false, error: modelProblem };
     const target = await this.resolveTarget(providerId, model);
     if (!target.ok) return { ok: false, error: target.error };
-    const { apiKey, endpoint } = target;
+    const { apiKey, endpoint, keyName } = 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(
-      providerId,
-      endpoint,
-      apiKey,
-      body,
-      config.timeoutMs,
-      config.maxRetries,
+    const sent = await sendSystemOneRequest(
+      {
+        providerId,
+        capability: "decide",
+        endpoint,
+        apiKey,
+        keyName,
+        body,
+        timeoutMs: config.timeoutMs,
+        maxRetries: config.maxRetries,
+        env: this.providerContext().env,
+      },
+      this.options,
     );
     if (!sent.ok) return { ok: false, error: scrub(sent.error) };
 
@@ -1101,163 +1061,4 @@ export class SystemOneDecisionExecutor extends BaseExecutor<
   ): ApprovalOutcome | null {
     return resolveReviewedDecision(parkedOutput, approval);
   }
-
-  /**
-   * POST once, retrying only transient failures inside one time budget.
-   * Retries: connection errors, HTTP 408 / 429 / 5xx (incl. 529). Never: 401, 422,
-   * other 4xx, redirects, or a bad success body (the caller validates that).
-   */
-  private async send(
-    providerId: SystemOneProviderId,
-    endpoint: string,
-    apiKey: string,
-    body: string,
-    timeoutMs: number,
-    maxRetries: number,
-  ): Promise<{ ok: true; text: string; requestId?: string } | { ok: false; error: string }> {
-    const doFetch = this.options.fetch ?? fetch;
-    const sleep = this.options.sleep ?? defaultSleep;
-    const now = this.options.now ?? Date.now;
-    const random = this.options.random ?? Math.random;
-
-    const deadlineAt = now() + timeoutMs - DEADLINE_MARGIN_MS;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), Math.max(0, deadlineAt - now()));
-    const timedOut = () =>
-      ({
-        ok: false,
-        error: `SystemOne request exceeded its ${timeoutMs}ms time budget`,
-      }) as const;
-
-    try {
-      for (let attempt = 0; ; attempt++) {
-        const result = await this.attemptOnce(
-          doFetch,
-          providerId,
-          endpoint,
-          apiKey,
-          body,
-          controller.signal,
-          now,
-        );
-        if (result.kind === "ok") {
-          return { ok: true, text: result.text, requestId: result.requestId };
-        }
-        if (result.kind === "timeout" || controller.signal.aborted) return timedOut();
-
-        const attempts = attempt + 1;
-        const suffix = attempts > 1 ? ` after ${attempts} attempts` : "";
-        if (!result.retryable || attempt >= maxRetries) {
-          return { ok: false, error: `${result.message}${suffix}` };
-        }
-
-        const backoff = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt);
-        const delay = result.retryAfterMs ?? Math.round(backoff * (0.5 + random() * 0.5));
-        if (delay >= deadlineAt - now()) {
-          return {
-            ok: false,
-            error: `${result.message}${suffix}; the ${delay}ms retry delay does not fit the ${timeoutMs}ms time budget`,
-          };
-        }
-        await sleep(delay, controller.signal);
-        if (controller.signal.aborted) return timedOut();
-      }
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  private async attemptOnce(
-    doFetch: typeof fetch,
-    providerId: SystemOneProviderId,
-    endpoint: string,
-    apiKey: string,
-    body: string,
-    signal: AbortSignal,
-    now: () => number,
-  ): Promise<Attempt> {
-    let res: Response;
-    try {
-      res = await doFetch(endpoint, {
-        method: "POST",
-        headers: {
-          ...getOpenRouterAttributionHeaders(endpoint, this.providerContext().env),
-          "content-type": "application/json",
-          accept: "application/json",
-          authorization: `Bearer ${apiKey}`,
-        },
-        body,
-        redirect: "manual",
-        signal,
-      });
-    } catch (err) {
-      if (signal.aborted) return { kind: "timeout" };
-      const code = (err as { code?: unknown })?.code;
-      const detail = typeof code === "string" && /^[A-Z0-9_]{3,40}$/.test(code) ? ` (${code})` : "";
-      return {
-        kind: "fail",
-        message: `SystemOne request failed: network error${detail}`,
-        retryable: true,
-      };
-    }
-
-    const requestId = readRequestId(res.headers);
-    const withId = (message: string) => (requestId ? `${message} [request ${requestId}]` : message);
-
-    if (res.status >= 200 && res.status < 300) {
-      let text: string;
-      try {
-        text = await res.text();
-      } catch {
-        if (signal.aborted) return { kind: "timeout" };
-        return {
-          kind: "fail",
-          message: withId("SystemOne response body could not be read"),
-          retryable: true,
-        };
-      }
-      if (text.length > MAX_RESPONSE_CHARS) {
-        return {
-          kind: "fail",
-          message: withId("SystemOne response exceeded the size limit"),
-          retryable: false,
-        };
-      }
-      return { kind: "ok", text, requestId };
-    }
-
-    if (res.status >= 300 && res.status < 400) {
-      return {
-        kind: "fail",
-        message: withId(
-          `SystemOne request was redirected (HTTP ${res.status}); redirects are refused`,
-        ),
-        retryable: false,
-      };
-    }
-
-    let errorText = "";
-    try {
-      errorText = await res.text();
-    } catch {
-      if (signal.aborted) return { kind: "timeout" };
-    }
-    const code = readErrorCode(errorText);
-    // The host answered but does not accept the key: name it, never retry.
-    if (res.status === 401 || res.status === 403) {
-      return {
-        kind: "fail",
-        message: withId(systemOneKeyRejectedMessage(providerId, res.status, code)),
-        retryable: false,
-      };
-    }
-    const detail = code ? ` (${code})` : "";
-    const retryable = res.status === 408 || res.status === 429 || res.status >= 500;
-    return {
-      kind: "fail",
-      message: withId(`SystemOne API returned HTTP ${res.status}${detail}`),
-      retryable,
-      retryAfterMs: retryable ? parseRetryAfter(res.headers.get("retry-after"), now()) : undefined,
-    };
-  }
 }

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

@@ -0,0 +1,57 @@
+import type { SystemOneExtractionConfig } from "./system-one-extraction";
+import {
+  cloudflareErrorCode,
+  isRecord,
+  SystemOneWireError,
+  wireContractError,
+} from "./system-one-wire";
+
+/**
+ * How one host's extraction request and response map onto the `system-one-extraction`
+ * contract: Clairic's `{ model, state, fields, images?, reference_date? }` request and
+ * `{ model, answers, truncated, usage }` body. A host with another shape supplies a
+ * wire that builds its body and returns that shape, which
+ * `validateSystemOneExtraction` then checks.
+ */
+export interface SystemOneExtractWire {
+  /** Request body for one call. */
+  buildRequest(config: SystemOneExtractionConfig, model: string | undefined): unknown;
+  /**
+   * Turn a parsed success body into the Clairic `{ model, answers, usage }` shape, or
+   * throw a `SystemOneWireError`. The result is still validated afterwards.
+   */
+  toExtraction(body: unknown): unknown;
+}
+
+/** Clairic reads one text; structured state is sent as JSON text, which spans then index into. */
+export function extractionStateText(state: SystemOneExtractionConfig["state"]): string {
+  return typeof state === "string" ? state : JSON.stringify(state);
+}
+
+/** The Clairic request as is: field specs already use Clairic's option names. */
+export const CLAIRIC_WIRE: SystemOneExtractWire = {
+  buildRequest: (config, model) => ({
+    ...(model === undefined ? {} : { model }),
+    state: extractionStateText(config.state),
+    fields: config.fields,
+    ...(config.images?.length ? { images: config.images } : {}),
+    ...(config.referenceDate ? { reference_date: config.referenceDate } : {}),
+  }),
+  toExtraction: (body) => body,
+};
+
+/** Cloudflare Workers AI: the Clairic request, the response wrapped in `{ result, success, errors }`. */
+export const CLOUDFLARE_EXTRACT_WIRE: SystemOneExtractWire = {
+  buildRequest: CLAIRIC_WIRE.buildRequest,
+  toExtraction(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})` : ""}. Nothing was extracted.`,
+      );
+    }
+    if (!isRecord(body.result)) wireContractError("Cloudflare response is missing its result");
+    return body.result;
+  },
+};