@desplega.ai/agent-swarm 2.4.3 → 2.4.5

package/src/be/seed-scripts/catalog/heartbeat-jev-gate.ts

@@ -13,11 +13,15 @@ export const argsSchema = z.object({
     .min(0)
     .max(1)
     .optional()
-    .describe("Quiet when Jev's p(needs action) is below this (default 0.5)"),
+    .describe(
+      "Quiet when the model's p(needs action) is below this (default: the provider's measured threshold, 0.5 for Jev, 0.2 for Clef)",
+    ),
   provider: z
-    .enum(["auto", "typesafe", "openrouter"])
+    .enum(["auto", "typesafe", "openrouter", "cloudflare"])
     .optional()
-    .describe("Jev host; auto prefers TypeSafe (default auto)"),
+    .describe(
+      "Decision host: typesafe or openrouter (Jev), cloudflare (Clef). auto tries them in that order (default auto)",
+    ),
   timeZone: z
     .string()
     .optional()
@@ -28,25 +32,56 @@ export const argsSchema = z.object({
     .min(1_000)
     .max(45_000)
     .optional()
-    .describe("Abandon the Jev call after this many ms (default 25000); the gate deadline is 60 s"),
+    .describe(
+      "Abandon the decision call after this many ms (default 25000); the gate deadline is 60 s",
+    ),
 });
 
 const KV_NAMESPACE = "heartbeat-jev-gate";
 const KV_KEY = "setup";
-// Measured per decision in the 2026-10-15 heartbeat replay (229 states).
-const COST_PER_DECISION = "$0.00004";
+// Jev's cost, measured per decision in the 2026-10-15 heartbeat replay (229 states).
+const JEV_COST_PER_DECISION = "$0.00004";
+// Clef replayed on the same 229 states and labels (2026-10-20): 0.2 is the highest
+// threshold that misses none of the 9 ticks where the Lead acted (57 quiet ticks;
+// Jev at 0.5 has 100). Above 0.21 Clef starts missing real asks.
+const CLEF_THRESHOLD = 0.2;
 
-// Jev is called through `ctx.swarm.systemOne_decide`: the API server reads the
-// key and sends the request, so no key ever enters this script's realm. The
+// The model is called through `ctx.swarm.systemOne_decide`: the API server reads
+// the key and sends the request, so no key ever enters this script's realm. The
 // server also refuses OpenRouter when the effective OPENROUTER_BASE_URL (stored
-// config or deployment env) points at a gateway.
+// config or deployment env) points at a gateway; `auto` then tries the next
+// usable provider, since this script cannot read the deployment env.
+//
+// `credentials` lists what must be set: every group needs one of its keys.
+// `threshold` is the default the provider's own replay measured (see `CLEF_THRESHOLD`).
 const PROVIDERS = {
-  typesafe: { keyName: "TYPESAFE_API_KEY", model: "jev-latest" },
-  openrouter: { keyName: "OPENROUTER_API_KEY", model: "~typesafe/jev-latest" },
+  typesafe: {
+    model: "jev-latest",
+    family: "jev",
+    threshold: 0.5,
+    credentials: [["TYPESAFE_API_KEY"]],
+    setup: "`TYPESAFE_API_KEY` (Jev on TypeSafe)",
+  },
+  openrouter: {
+    model: "~typesafe/jev-latest",
+    family: "jev",
+    threshold: 0.5,
+    credentials: [["OPENROUTER_API_KEY"]],
+    setup: "`OPENROUTER_API_KEY` (Jev on OpenRouter)",
+  },
+  cloudflare: {
+    model: "clef",
+    family: "clef",
+    threshold: CLEF_THRESHOLD,
+    credentials: [["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_API_KEY"], ["CLOUDFLARE_ACCOUNT_ID"]],
+    setup:
+      "`CLOUDFLARE_API_TOKEN` (or `CLOUDFLARE_API_KEY`) as a secret plus the `CLOUDFLARE_ACCOUNT_ID` config value (Clef on Cloudflare Workers AI)",
+  },
 } as const;
 type ProviderId = keyof typeof PROVIDERS;
+const AUTO_ORDER: ProviderId[] = ["typesafe", "openrouter", "cloudflare"];
 
-// Worded exactly as in the replay that set the 0.5 threshold; changing it voids that result.
+// Worded exactly as in the replays that set the thresholds; changing it voids those results.
 const QUESTIONS = {
   act: {
     type: "noul",
@@ -189,11 +224,20 @@ async function buildState(ctx: any, leadId: string, nowMs: number, timeZone: str
   const mmdd = new Date(nowMs).toISOString().slice(5, 10);
   const mmddLocal = stamp.slice(5, 10);
   const due: string[] = [];
+  // An MM-DD counts only as a bare token: "release on 10-20" is due, while a
+  // re-verification stamp ("2026-10-20 ~10:45Z", a UUID piece) and a suffixed
+  // token ("10-20s") are not.
+  const mentionsMmdd = (s: string, tok: string) =>
+    new RegExp(`(?<![\\w-])${tok}(?![\\w-])`).test(s);
   for (const line of String(lead[0]?.heartbeatMd ?? "").split("\n")) {
     const l = line.trim();
     if (!l) continue;
     const del = /DELETE <?(\d\d-\d\d)>?/.exec(l);
-    if (l.includes(mmdd) || l.includes(mmddLocal) || (del?.[1] && del[1] <= mmddLocal)) {
+    if (
+      mentionsMmdd(l, mmdd) ||
+      mentionsMmdd(l, mmddLocal) ||
+      (del?.[1] && del[1] <= mmddLocal)
+    ) {
       due.push(oneLine(l).slice(0, 200));
     }
     if (due.length >= 6) break;
@@ -220,21 +264,25 @@ async function buildState(ctx: any, leadId: string, nowMs: number, timeZone: str
   };
 }
 
-function setupPrompt(keys: string[]) {
+function setupPrompt(candidates: ProviderId[]) {
+  const options = candidates.map((id) => `- ${PROVIDERS[id].setup}`);
   return {
-    title: "Heartbeat Jev gate: add a Jev credential or decline",
+    title: "Heartbeat gate: add a decision model credential or decline",
     detached: true,
     questions: [
       {
         id: "enable",
         type: "approval",
-        label: "Enable the Jev heartbeat gate?",
+        label: "Enable the heartbeat checklist gate?",
         description: [
-          "Before each recurring heartbeat checklist, the `heartbeat-jev-gate` script sends a short summary of swarm state (about 1,500 characters: new failures, due tracked items, task and agent counts) to Jev, a small decision model by TypeSafe, and asks whether the Lead needs to act. With `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`, quiet ticks skip the Lead's checklist task.",
+          "Before each recurring heartbeat checklist, the `heartbeat-jev-gate` script sends a short summary of swarm state (about 1,500 characters: new failures, due tracked items, task and agent counts) to a small SystemOne decision model (Jev by TypeSafe, or Clef on Cloudflare Workers AI) and asks whether the Lead needs to act. With `HEARTBEAT_CHECKLIST_GATE_MODE=enforce`, quiet ticks skip the Lead's checklist task.",
           "",
-          `Cost: about ${COST_PER_DECISION} per decision, one decision per checklist tick.`,
+          `Cost: one decision per checklist tick, about ${JEV_COST_PER_DECISION} each with Jev.`,
           "",
-          `No Jev credential is configured. To enable, approve and add one of ${keys.map((k) => `\`${k}\``).join(" or ")} as a global secret on the Secrets page (Settings > Secrets). Do not paste the key here. The next tick picks it up.`,
+          "No credential for the gate is configured. To enable, approve and add one of these as a global value on the Secrets page (Settings > Secrets):",
+          ...options,
+          "",
+          "Do not paste a key here. The next tick picks it up.",
           "",
           "Reject to decline. The gate then stays inactive, with no further prompts, until a key is added.",
         ].join("\n"),
@@ -244,9 +292,10 @@ function setupPrompt(keys: string[]) {
 }
 
 /**
- * Heartbeat checklist gate backed by Jev: asks Jev whether a recurring checklist
- * tick needs the Lead and returns { quiet, reason, summary }. With no Jev
- * credential it asks a human once, then stays a no-op until a key is added.
+ * Heartbeat checklist gate backed by a SystemOne decision model (Jev or Clef):
+ * asks whether a recurring checklist tick needs the Lead and returns
+ * { quiet, reason, summary }. With no credential it asks a human once, then
+ * stays a no-op until a key is added.
  */
 export default async function heartbeatJevGate(args: any, ctx: any) {
   const parsed = argsSchema.safeParse(args ?? {});
@@ -267,25 +316,21 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
   };
 
   const cfgThreshold = Number.parseFloat(cfg("HEARTBEAT_JEV_GATE_THRESHOLD"));
-  const threshold =
-    a.threshold ?? (cfgThreshold >= 0 && cfgThreshold <= 1 ? cfgThreshold : 0.5);
   const providerPref = a.provider ?? (cfg("HEARTBEAT_JEV_GATE_PROVIDER").toLowerCase() || "auto");
   const timeZone = a.timeZone ?? (cfg("HEARTBEAT_JEV_GATE_TIMEZONE") || "UTC");
 
-  const usable: Record<ProviderId, boolean> = {
-    typesafe: cfg(PROVIDERS.typesafe.keyName) !== "",
-    openrouter: cfg(PROVIDERS.openrouter.keyName) !== "",
-  };
+  const usable = (id: ProviderId) =>
+    PROVIDERS[id].credentials.every((group) => group.some((key) => cfg(key) !== ""));
   const candidates: ProviderId[] =
-    providerPref === "typesafe"
-      ? ["typesafe"]
-      : providerPref === "openrouter"
-        ? ["openrouter"]
-        : ["typesafe", "openrouter"];
-  const provider = candidates.find((id) => usable[id]);
+    Object.hasOwn(PROVIDERS, providerPref) ? [providerPref as ProviderId] : AUTO_ORDER;
+  const usableCandidates = candidates.filter(usable);
 
-  if (!provider) {
-    const keys = candidates.map((id) => PROVIDERS[id].keyName);
+  if (usableCandidates.length === 0) {
+    const keys = candidates.map((id) =>
+      PROVIDERS[id].credentials
+        .map((group) => (group.length > 1 ? `(${group.join(" or ")})` : group[0]))
+        .join(" + "),
+    );
     const inactive = (state: string, extra: Record<string, unknown> = {}) => ({
       quiet: false,
       reason: `jev-gate inactive: ${state}`.slice(0, 300),
@@ -296,7 +341,7 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
     let setup: SetupState | null = typeof stored === "string" ? JSON.parse(stored) : (stored ?? null);
 
     if (!setup) {
-      const prompt = setupPrompt(keys);
+      const prompt = setupPrompt(candidates);
       if (dryRun) {
         const state = await buildState(ctx, leadId, Date.now(), timeZone);
         return inactive("no credential, would ask a human", { prompt, state });
@@ -340,35 +385,51 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
     return inactive(why, { setup });
   }
 
-  const target = PROVIDERS[provider];
   const state = await buildState(ctx, leadId, Date.now(), timeZone);
 
-  // The server enforces the time budget. No retries, as in the replay.
-  const res: any = await ctx.swarm.systemOne_decide({
-    provider,
-    model: target.model,
-    state,
-    questions: QUESTIONS,
-    timeoutMs: a.jevTimeoutMs ?? 25_000,
-    maxRetries: 0,
-  });
-  const body: any = res?.data ?? res;
-  if (res?.success === false || body?.success === false) {
-    throw new Error(`jev ${provider}: ${String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 250)}`);
+  // The server enforces the time budget. No retries, as in the replay. A provider
+  // this deployment refuses (OpenRouter behind a gateway) sends nothing, so the
+  // next usable one is tried; only an explicit choice or the last one throws.
+  let provider = usableCandidates[0] as ProviderId;
+  let body: any;
+  const skipped: string[] = [];
+  for (const [i, id] of usableCandidates.entries()) {
+    provider = id;
+    const res: any = await ctx.swarm.systemOne_decide({
+      provider: id,
+      model: PROVIDERS[id].model,
+      state,
+      questions: QUESTIONS,
+      timeoutMs: a.jevTimeoutMs ?? 25_000,
+      maxRetries: 0,
+    });
+    body = res?.data ?? res;
+    if (res?.success !== false && body?.success !== false) break;
+    const why = String(body?.message ?? body?.error ?? `HTTP ${res?.status}`).slice(0, 250);
+    if (body?.providerUnavailable === true && i < usableCandidates.length - 1) {
+      skipped.push(`${id}: ${why}`);
+      continue;
+    }
+    throw new Error(`${PROVIDERS[id].family} ${id}: ${why}`);
   }
+  const target = PROVIDERS[provider];
+  // A configured threshold applies to every provider; unset, each uses its measured one.
+  const threshold =
+    a.threshold ?? (cfgThreshold >= 0 && cfgThreshold <= 1 ? cfgThreshold : target.threshold);
   const p = body?.answers?.act?.noul;
   if (typeof p !== "number" || !Number.isFinite(p)) {
-    throw new Error(`jev ${provider}: response has no numeric answers.act.noul`);
+    throw new Error(`${target.family} ${provider}: response has no numeric answers.act.noul`);
   }
 
   const pText = p.toFixed(3);
   const quiet = p < threshold;
   const verdict: Record<string, unknown> = {
     quiet,
-    reason: `jev p(needs action)=${pText} ${quiet ? "<" : ">="} ${threshold} via ${provider}`,
+    reason: `${target.family} p(needs action)=${pText} ${quiet ? "<" : ">="} ${threshold} via ${provider}`,
   };
   if (!quiet) {
-    const lines = [`Jev p(needs action) = ${pText} (threshold ${threshold}, ${provider}).`];
+    const model = target.family === "jev" ? "Jev" : "Clef";
+    const lines = [`${model} p(needs action) = ${pText} (threshold ${threshold}, ${provider}).`];
     const failures = state.new_failures_since_previous_heartbeat;
     const tracked = state.tracked_items_mentioning_today_or_past_delete_date;
     if (Array.isArray(failures)) {
@@ -378,9 +439,9 @@ export default async function heartbeatJevGate(args: any, ctx: any) {
       lines.push("", "Tracked items due today or past their DELETE date:", ...tracked.map((t) => `- ${t.replace(/^[-*] /, "")}`));
     }
     if (!Array.isArray(failures) && !Array.isArray(tracked)) {
-      lines.push("", "No new failures or due tracked items; Jev flagged the overall state.");
+      lines.push("", `No new failures or due tracked items; ${model} flagged the overall state.`);
     }
     verdict.summary = lines.join("\n").slice(0, 4000);
   }
-  return dryRun ? { ...verdict, dryRun: true, provider, p, threshold, state } : verdict;
+  return dryRun ? { ...verdict, dryRun: true, provider, skipped, p, threshold, state } : verdict;
 }

package/src/be/seed-scripts/index.ts

@@ -116,9 +116,9 @@ export const SEED_SCRIPTS: SeedScript[] = [
   {
     name: "heartbeat-jev-gate",
     description:
-      "Heartbeat checklist gate backed by Jev (TypeSafe or OpenRouter decisions API): scores a compact swarm state and returns {quiet, reason, summary} for HEARTBEAT_CHECKLIST_GATE_SCRIPT.",
+      "Heartbeat checklist gate backed by a SystemOne decision model (Jev on TypeSafe or OpenRouter, Clef on Cloudflare Workers AI): scores a compact swarm state and returns {quiet, reason, summary} for HEARTBEAT_CHECKLIST_GATE_SCRIPT.",
     intent:
-      "Skip quiet Lead heartbeat checklist ticks with a cheap Jev decision; with no Jev credential it asks a human once, then stays a no-op until a key is added.",
+      "Skip quiet Lead heartbeat checklist ticks with a cheap Jev or Clef decision; with no credential it asks a human once, then stays a no-op until a key is added.",
     source: asText(heartbeatJevGateSrc),
   },
   {

package/src/be/swarm-config-guard.ts

@@ -68,7 +68,11 @@ const RESERVED_KEYS = new Set([
 // the agent-fs bootstrap admin key would let a compromised worker administer the
 // shared org. The API materializes these into its own process.env at boot via
 // getInjectableGlobalConfigs, so no HTTP consumer legitimately needs them.
-const API_ONLY_CONFIG_KEYS = new Set(["API_AGENT_FS_API_KEY", "SLACK_SIGNING_SECRET"]);
+const API_ONLY_CONFIG_KEYS = new Set([
+  "API_AGENT_FS_API_KEY",
+  "SLACK_SIGNING_SECRET",
+  "TRANSCRIPTION_API_KEY",
+]);
 
 export function isApiOnlyConfigKey(key: string): boolean {
   return API_ONLY_CONFIG_KEYS.has(key);
@@ -149,6 +153,31 @@ export const DB_RETENTION_TUNING_BOUNDS = {
  */
 export const APPS_JSON_COLUMN_MAX_BYTES_BOUNDS = { min: 1_024, max: 16_777_216 } as const;
 
+/**
+ * Bounds for the Codex OAuth keep-warm age threshold
+ * (`CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS`).
+ *
+ * `src/http/codex-oauth-keep-warm.ts` reads the knob against exactly these at
+ * call time and falls back to its default outside them. The 216 h (9 day)
+ * ceiling stays under the 9.5 day point where task-time near-expiry refresh
+ * takes over, so every accepted value still changes when a slot refreshes.
+ */
+export const CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS = { min: 1, max: 216 } as const;
+
+/**
+ * Decision hosts `SYSTEM_ONE_DEFAULT_PROVIDER` may name: `SYSTEM_ONE_PROVIDER_IDS`
+ * in `src/workflows/executors/system-one-providers.ts`, listed here because that
+ * module's credential readers would pull the LLM stack into every `db.ts` import.
+ * A test keeps the two lists equal.
+ */
+export const SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS = [
+  "typesafe",
+  "openrouter",
+  "laya",
+  "openai",
+  "cloudflare",
+] as const;
+
 /** Build `{ KEY: validator }` entries accepting only boolean literals. */
 function booleanValidators(keys: string[]): Record<string, ConfigValidator> {
   const message = (key: string) =>
@@ -388,6 +417,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   },
   ...enumValidator("CLAUDE_TRANSPORT", ["cli", "sdk"]),
   ...enumValidator("SCRIPT_EXECUTOR", ["native", "quickjs"]),
+  ...enumValidator("TRANSCRIPTION_PROVIDER", ["openai", "elevenlabs", "groq"]),
   SCRIPT_QUICKJS_POOL_SIZE: validateQuickJSPoolSize,
   ...booleanValidators(["SCRIPT_EGRESS_ALLOW_PRIVATE"]),
   SCRIPT_EGRESS_ALLOWLIST: (value) =>
@@ -396,6 +426,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // model's weekly window (Fable/Opus/Sonnet). fallback: legacy random pick.
   ...enumValidator("MODEL_WINDOW_EXHAUSTED_POLICY", ["fail", "fallback"]),
   ...enumValidator("HEARTBEAT_CHECKLIST_GATE_MODE", ["shadow", "enforce"]),
+  ...enumValidator("SYSTEM_ONE_DEFAULT_PROVIDER", [...SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS]),
   // Codex credits-exhausted cooldown (ms). Permissive on range here (positive
   // integer) — the worker clamps to [5m, 7d] via resolveCodexCreditsExhaustedCooldownMs.
   CODEX_CREDITS_EXHAUSTED_COOLDOWN_MS: (value) => {
@@ -542,6 +573,11 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
     APPS_JSON_COLUMN_MAX_BYTES_BOUNDS.min,
     APPS_JSON_COLUMN_MAX_BYTES_BOUNDS.max,
   ),
+  ...boundedIntegerValidators(
+    ["CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS"],
+    CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS.min,
+    CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS.max,
+  ),
   ...boundedIntegerValidators(
     [
       "SESSION_LOG_RETENTION_DAYS",
@@ -566,6 +602,9 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
   // default in thread-buffer.ts; above 10 minutes a
   // reply waits longer than any operator expects.
   ...boundedIntegerValidators(["CHAT_SDK_BUFFER_MS"], 1, 600_000),
+  // Minutes a Chat SDK thread keeps its owner after the owner's task ends.
+  // 0 keeps it only while the task is open; a day is the longest useful window.
+  ...boundedIntegerValidators(["CHAT_SDK_OWNER_WINDOW_MIN"], 0, 1440),
   // Below ~100 tokens the preamble can't fit a useful summary; above 20000
   // (~80k chars) it risks the SIGTERM-143 context-saturation failure mode
   // the cap exists to prevent (see context-preamble.ts).

package/src/be/task-attachment-store.ts

@@ -68,3 +68,33 @@ export async function recordTaskAttachmentUpload(
     throw error;
   }
 }
+
+// Resolve against the row's ACTUAL stored key + its own org/drive, rather than
+// reconstructing `tasks/<taskId>/<name>`. Attachments written to agent-fs via the
+// CLI live at arbitrary paths (`misc/…`, `smoke/…`); reconstruction mis-resolves
+// them, which previously caused downloads to 404 and deletes to orphan the real
+// file. New uploads have no stored key yet at scope-build time and keep the
+// forward-looking layout.
+export function scopeFromAttachment(attachment: TaskAttachment): FileScope {
+  const storedKey = attachment.providerKey ?? attachment.path ?? "";
+  return {
+    taskId: attachment.taskId,
+    name: attachment.name,
+    key: storedKey.trim() ? storedKey : undefined,
+    orgId: attachment.orgId,
+    driveId: attachment.driveId,
+  };
+}
+
+// Which file-storage provider (if any) actually holds this attachment's bytes.
+// Only agent-fs objects and local-fs uploads are provider-backed; `shared-fs`
+// worker-volume pointers, `url`, and `page` attachments have no provider object,
+// so they must never be fetched or deleted through a provider (doing so would
+// mis-resolve and, on delete, orphan the real target). Note local-fs uploads are
+// recorded with kind "shared-fs" but an explicit local-fs providerId, so key off
+// both signals rather than kind alone.
+export function backingProviderId(attachment: TaskAttachment): string | null {
+  if (attachment.kind === "agent-fs") return attachment.providerId ?? "agent-fs";
+  if (attachment.providerId === "local-fs") return "local-fs";
+  return null;
+}