@desplega.ai/agent-swarm 2.4.3 → 2.4.5

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

@@ -0,0 +1,264 @@
+import { getOpenRouterAttributionHeaders } from "../../utils/openrouter-base-url";
+import {
+  type SystemOneCapability,
+  type SystemOneHostId,
+  systemOneKeyRejectedMessage,
+} from "./system-one-providers";
+import { cloudflareErrorCode, isRecord } from "./system-one-wire";
+
+/**
+ * One POST to a System One host, shared by every capability (`system-one-decision`,
+ * `system-one-extraction`): one time budget, transient retries with backoff,
+ * `Retry-After`, redirect refusal, a response size cap, and the same error
+ * sentences. The credential goes only into the `authorization` header.
+ */
+
+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;
+
+/** 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;
+const MAX_RESPONSE_CHARS = 1_048_576;
+const MAX_ERROR_BODY_CHARS = 65_536;
+
+export interface SystemOneTransportOptions {
+  /** Transport. Tests inject a fake; production uses the global `fetch`. */
+  fetch?: typeof fetch;
+  sleep?: (ms: number, signal: AbortSignal) => Promise<void>;
+  now?: () => number;
+  random?: () => number;
+}
+
+export interface SystemOneRequest {
+  providerId: SystemOneHostId;
+  capability: SystemOneCapability;
+  endpoint: string;
+  apiKey: string;
+  /** The secret name the key was read under, named when the host rejects it. */
+  keyName: string;
+  body: string;
+  timeoutMs: number;
+  maxRetries: number;
+  env: NodeJS.ProcessEnv;
+}
+
+export type SystemOneSendResult =
+  | { ok: true; text: string; requestId?: string }
+  | { ok: false; error: string };
+
+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 });
+  });
+}
+
+/**
+ * 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).
+ */
+export async function sendSystemOneRequest(
+  request: SystemOneRequest,
+  options: SystemOneTransportOptions = {},
+): Promise<SystemOneSendResult> {
+  const { timeoutMs, maxRetries } = request;
+  const doFetch = options.fetch ?? fetch;
+  const sleep = options.sleep ?? defaultSleep;
+  const now = options.now ?? Date.now;
+  const random = 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 attemptOnce(doFetch, request, 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);
+  }
+}
+
+async function attemptOnce(
+  doFetch: typeof fetch,
+  request: SystemOneRequest,
+  signal: AbortSignal,
+  now: () => number,
+): Promise<Attempt> {
+  const { endpoint, apiKey, body } = request;
+  let res: Response;
+  try {
+    res = await doFetch(endpoint, {
+      method: "POST",
+      headers: {
+        ...getOpenRouterAttributionHeaders(endpoint, request.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(request.providerId, res.status, code, {
+          keyName: request.keyName,
+          capability: request.capability,
+        }),
+      ),
+      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/templates/extensions/slack-reply-gate/README.md

@@ -1,6 +1,6 @@
 # slack-reply-gate
 
-Lead is woken by every human message in a Slack thread the swarm takes part in, including "lol", an emoji, or two people chatting with each other. This extension asks Jev, [TypeSafe](https://typesafe.ai)'s decision model, whether Lead should answer a new thread message, and drops the wake-up when it should not.
+Lead is woken by every human message in a Slack thread the swarm takes part in, including "lol", an emoji, or two people chatting with each other. This extension asks a SystemOne decision model, Jev ([TypeSafe](https://typesafe.ai)) or Clef (Cloudflare Workers AI), whether Lead should answer a new thread message, and drops the wake-up when it should not.
 
 Install config:
 
@@ -15,8 +15,8 @@ Start in `shadow`, read the decisions in KV for a few days, then switch to `enfo
 | `mode` | Effect |
 |---|---|
 | `off` | Never evaluates. |
-| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |
-| `enforce` | Asks Jev, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |
+| `shadow` (default) | Asks the model and records the verdict. Never blocks. |
+| `enforce` | Asks the model, records the verdict, and blocks the Lead task when the answer is no. The message gets :mute: instead: no Lead task, no reply, no outcome card. |
 
 ## What it gates
 
@@ -26,28 +26,30 @@ The header counts only at the start of the description or right after the closin
 
 ## Decision
 
-1. A follow-up with downloaded files (status `draft`) passes without a Jev call.
-2. **@mention pass-through.** A new message that @mentions Lead passes without a Jev call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.
-3. Otherwise one Jev call (one `choice` question, see [Jev transport](#jev-transport)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.
+1. A follow-up with downloaded files (status `draft`) passes without a decision call.
+2. **@mention pass-through.** A new message that @mentions Lead passes without a decision call. A mention is the bot mention the engine rewrites to `<@U…> (that's you)`, a resolved `<@U…|lead>`, or a literal `@lead` (any name in `leadAliases`). Only the new messages are scanned, never the thread context, so an old mention earlier in the thread does not pass later banter.
+3. Otherwise one decision call (one `choice` question, see [Provider](#provider)) with the new message(s), the sender kind, and the last `contextMessages` thread messages. Labels: `direct_ask`, `followup_to_lead`, `instruction_to_lead`, `reaction_only`, `banter_between_others`, `not_addressed_to_lead`, `other`.
 4. The answer is no only when the top label is `reaction_only`, `banter_between_others`, or `not_addressed_to_lead`, and the summed probability of those three labels is at least `minConfidence`. A split between two skip labels is still a skip. An unsure verdict replies.
 
 Several buffered messages are judged together. One mention in any of them passes the batch.
 
-## Jev transport
+## Provider
 
-Jev is reachable two ways. Both take the same request and return the same answer, so the decision is identical whichever one runs.
+The decision is made on the API server by the `system-one-decide` tool (`ctx.swarm.systemOne_decide`), the same path a `system-one-decision` workflow node takes. The server reads the provider's credential, sends the request, and validates the answer, so every SystemOne host works and no key enters the hook.
 
-| `provider` | Endpoint | Key | Model |
-|---|---|---|---|
-| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |
-| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |
-| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |
+| `provider` | Model | Credential |
+|---|---|---|
+| `typesafe` | Jev, `model` (default `jev-latest`) | `TYPESAFE_API_KEY` |
+| `openrouter` | Jev, `openrouterModel` (default `typesafe/jev-1.13`) | `OPENROUTER_API_KEY` |
+| `cloudflare` | Clef, `cloudflareModel` (default `clef`, or `clef-flash`) | `CLOUDFLARE_API_TOKEN` (or `CLOUDFLARE_API_KEY`) and `CLOUDFLARE_ACCOUNT_ID` |
+| `laya`, `openai` | The host's default model | See the workflows guide |
+| `auto` (default) | The first of typesafe, openrouter, cloudflare whose credential is set. A provider the server refuses for a deployment setting (openrouter when `OPENROUTER_BASE_URL` points at a gateway) is skipped for the next one | |
 
-Under `auto`, `TYPESAFE_API_KEY` wins when both keys are set. With neither key, every message fails open and the KV row names both secrets. Each decision row records the `provider` that answered.
+With no credential for `auto`, every message fails open and the KV row names the secrets. Each decision row records the `provider` that answered. `minConfidence` was tuned on Jev; check Clef's verdicts in `shadow` before you enforce on it.
 
 ## Fail open
 
-Every error lets the task through: a missing key, a TypeSafe HTTP error, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.
+Every error lets the task through: a missing key, a provider error relayed by the server, a network error, a timeout, a malformed answer, or an unknown label. The handler never throws, so an outage cannot auto-disable the extension. Each failure is recorded as `fail-open` in KV and logged as a warning.
 
 ## :mute: on drop (enforce)
 
@@ -63,23 +65,23 @@ The block returns first and the Slack calls run after it. A slow or failing Slac
 | Key | Default | Notes |
 |---|---|---|
 | `mode` | `shadow` | `off`, `shadow`, or `enforce` |
-| `timeoutMs` | `3000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
-| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |
+| `timeoutMs` | `3000` | Decision call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |
+| `provider` | `auto` | `auto`, `typesafe`, `openrouter`, `cloudflare`, `laya`, or `openai`. See [Provider](#provider) |
 | `model` | `jev-latest` | Jev model on TypeSafe |
 | `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |
+| `cloudflareModel` | `clef` | Clef model on Cloudflare Workers AI |
 | `minConfidence` | `0.55` | Minimum summed skip probability to skip |
-| `contextMessages` | `6` | Thread messages sent to Jev, 0 to 20 |
+| `contextMessages` | `6` | Thread messages sent to the model, 0 to 20 |
 | `leadAliases` | `["lead"]` | A literal `@alias` in a new message counts as a mention |
-| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for Jev |
-| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |
+| `botSlackUserIds` | `[]` | Slack user ids labelled `bot` as the sender for the model |
 | `muteReaction` | `mute` | Reaction for a dropped message; `""` only removes the acceptance reaction(s) |
 | `slackTimeoutMs` | `5000` | Timeout per Slack call |
 
 ## Required secrets
 
-All are read from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.
+Set them as global `swarm_config` values. The server reads the provider credential from the global row when it makes the decision. `auto` and the Slack token read the API process environment, which loads global rows at boot and on config reload.
 
-- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every message fails open.
+- One provider credential from the [Provider](#provider) table is required for any evaluation. Without one, every message fails open. The `apiKey` config field of earlier versions is gone: the hook never holds a key, so store it as the global `TYPESAFE_API_KEY` secret.
 - `SLACK_BOT_TOKEN`: the Slack app's bot token. A swarm with Slack connected already has it. Without it, `enforce` still drops the message but cannot touch its reactions, and logs a `mute-error`.
 
 No key is written to config, KV, logs, or a description.