@gr8ful/spf 0.10.2 → 0.11.0

package/README.md

@@ -194,6 +194,38 @@ That's the whole config change. `ollama` is a keyless provider — `spf doctor`
 
 Two things worth knowing before pointing a full roster at local models: tool-calling — the injected `sf_report` contract every agent's structured output rides on — worked reliably in testing down to a 3B-parameter model, which isn't a "only frontier models get tools" situation. And context-window occupancy reporting is disabled for `ollama/*` models specifically, which turns off threshold-based compaction rather than reporting a number Ollama's OpenAI-compatible API doesn't actually provide per model.
 
+### flue + Cloudflare Workers AI
+
+Point the default `flue` backend at a [Cloudflare Workers AI](https://developers.cloudflare.com/ai/) model the same way you'd pick any other Flue provider — the model string's own prefix, `cloudflare/<model-id>`, where `<model-id>` is the full `@cf/...` catalog id (the slash inside the id is fine; spf splits on the first slash only):
+
+```yaml
+defaults:
+  coding_agent: flue
+  model: cloudflare/@cf/zai-org/glm-5.3-flash
+```
+
+```bash
+export CLOUDFLARE_ACCOUNT_ID=your-account-id        # derives https://api.cloudflare.com/client/v4/accounts/$ID/ai/v1
+export CLOUDFLARE_API_TOKEN=your-token               # Workers AI > Read permission
+spf build "your prompt"
+```
+
+That's the whole config change. `cloudflare` is a keyed provider (a real Bearer token, unlike keyless `ollama` — Cloudflare's API 401s on an empty Authorization header). `spf init` asks for the token plus either `CLOUDFLARE_ACCOUNT_ID` (the standard endpoint) or an explicit `CLOUDFLARE_AI_BASE_URL` (a custom domain or an AI Gateway endpoint), and overrides the three packaged-roster agents that a Workers AI account can't serve. `spf doctor` probes the resolved endpoint (informational, never a hard failure). A ready-to-run starting point ships at [`assets/templates/ts-flue-cloudflare.spf.config.yaml`](assets/templates/ts-flue-cloudflare.spf.config.yaml) (`spf init --template ts-flue-cloudflare`).
+
+Two things worth knowing, both inherited from the `ollama/*` convention for self-served OpenAI-compatible endpoints: context-window occupancy reporting is disabled for `cloudflare/*` models (`contextWindow: 0`, turning off threshold-based compaction rather than fabricating a number Workers AI's API doesn't provide per model), and `reasoning: false` — the model's own `reasoning_effort` parameter is not wired through, so an agent's `thinking:` level is moot for `cloudflare/*` models today.
+
+### claude_code + Cloudflare AI Gateway
+
+To route the `claude_code` backend through a [Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/) (so the gateway holds the Anthropic credentials via Unified Billing or BYOK, and you authenticate to the gateway), pick **Cloudflare AI Gateway** at the `Authentication` step in `spf init`. spf writes the three env vars the gateway needs:
+
+```bash
+ANTHROPIC_BASE_URL=https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/anthropic
+ANTHROPIC_API_KEY=<CF_AIG_TOKEN>                                   # any value — the gateway ignores it; Claude Code requires it set
+ANTHROPIC_CUSTOM_HEADERS=cf-aig-authorization: Bearer <CF_AIG_TOKEN>
+```
+
+`spf doctor` probes the gateway's `/v1/messages` with the `cf-aig-authorization` header (informational, never a hard failure). This is the `claude_code` backend — it speaks the Anthropic API, so it's independent of the Workers AI `flue` provider above; you can run some agents on Workers AI (`flue`) and others through the gateway (`claude_code`) in the same roster.
+
 ---
 
 ## Isolation: post-hoc, not a sandbox

package/assets/templates/ts-flue-cloudflare.spf.config.yaml

@@ -0,0 +1,61 @@
+# .spf/spf.config.yaml — Flue backend (the default), routed at Cloudflare
+# Workers AI instead of a hosted provider. `spf init --template
+# ts-flue-cloudflare` writes this file as-is.
+#
+# model: is ALWAYS provider/model-id for Flue — "cloudflare/<id>", where
+# <id> is the full @cf/... catalog id from developers.cloudflare.com/ai/models
+# (agent_flue.ts registers each distinct "cloudflare/<id>" it sees with
+# Flue's own provider registry the first time it's dispatched — no separate
+# model catalog to keep in sync here). The slash INSIDE @cf/... is fine: spf
+# splits on the first slash only, so "cloudflare/@cf/zai-org/glm-5.3-flash"
+# is provider "cloudflare", model id "@cf/zai-org/glm-5.3-flash". agents.
+# validate() only checks the STRING SHAPE (provider/id) — never that the id
+# actually exists in your account. A wrong or unavailable id only surfaces at
+# the first real dispatch, as an error from Workers AI itself, not at
+# validate() time.
+#
+# cloudflare is a KEYED provider (providers.ts's PROVIDER_ENV_KEYS.cloudflare
+# is ["CLOUDFLARE_API_TOKEN"]) — a real Bearer token, unlike keyless ollama
+# (Cloudflare's API 401s on an empty Authorization header). What's required:
+#   export CLOUDFLARE_API_TOKEN=...      # Workers AI > Read permission
+#   export CLOUDFLARE_ACCOUNT_ID=...     # derives https://api.cloudflare.com/client/v4/accounts/$ID/ai/v1
+# (or set CLOUDFLARE_AI_BASE_URL to override the endpoint — a custom domain or
+# a Cloudflare AI Gateway URL.) `spf doctor` probes the resolved endpoint
+# (informational, never a hard failure) so a misconfigured account id shows up
+# before your first real run does, not during it.
+#
+# Context-window occupancy reporting is disabled for every cloudflare/*
+# model (contextWindow: 0, the same convention as ollama/*), which turns off
+# threshold-based compaction rather than reporting a fabricated number
+# Workers AI's OpenAI-compatible API doesn't provide per-model. reasoning is
+# also false: the model's own reasoning_effort is not wired through Workers
+# AI's OpenAI-compatible surface, so an agent's thinking: level is moot.
+quality:
+  checks:
+    - { name: typecheck, operation: typecheck, argv: ["npm", "run", "typecheck"], timeout_seconds: 60 }
+    - { name: lint, operation: lint, argv: ["npm", "run", "lint"], timeout_seconds: 60 }
+    - { name: build, operation: build, argv: ["npm", "run", "build"], timeout_seconds: 300 }
+    - { name: test, operation: build, argv: ["npm", "test"], timeout_seconds: 300 }
+  suites:
+    test: [test]
+    all: [typecheck, lint, build, test]
+
+defaults:
+  coding_agent: flue
+  # EXAMPLE — replace with a heavier reasoning model from your own account's
+  # available list (developers.cloudflare.com/ai/models).
+  model: cloudflare/@cf/zai-org/glm-5.3-flash
+
+# Overridden here (same rationale as the ollama template): the packaged
+# roster's planner/reviewer/documenter pin their own fireworks/openai
+# model ids, which a Workers AI account CANNOT serve — left alone, those
+# three would route at providers whose keys this template never asks for.
+# Overridden so every agent actually demonstrates Workers AI routing.
+agents:
+  - name: planner
+    model: cloudflare/@cf/zai-org/glm-5.3-flash
+  - name: reviewer
+    model: cloudflare/@cf/zai-org/glm-5.3-flash
+  - name: documenter
+    # EXAMPLE — replace with a lighter/faster model from your account.
+    model: cloudflare/@cf/meta/llama-3.1-8b-instruct

package/dist/cli/commands/doctor.js

@@ -17,6 +17,7 @@ import { DEFAULT_NOTIFY_ENV_KEY } from "../../core/notify/notifier.js";
 import { endpointLabel, redact, resolveTracesUrl } from "../../core/otel.js";
 import { isKnownToolName as isKnownFlueToolName, resolveModel } from "../../core/agent_flue.js";
 import { ollamaBaseUrl } from "../../core/ollama_provider.js";
+import { cloudflareAiBaseUrl } from "../../core/cloudflare_provider.js";
 import { binaryOnPath, parseCli } from "../../core/utils.js";
 import { PROVIDER_ENV_KEYS } from "../../core/providers.js";
 import { probeServedOllamaTags, resolveTiering } from "../../core/tiering.js";
@@ -95,11 +96,11 @@ function repoChainLabel(source) {
 }
 const PROBE_TIMEOUT_MS = 3_000;
 /** A GET that never throws — a down/unreachable server is a finding to report, never a crash of `spf doctor` itself. */
-async function probeGet(url) {
+async function probeGet(url, headers) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
     try {
-        const res = await fetch(url, { signal: controller.signal });
+        const res = await fetch(url, { signal: controller.signal, headers });
         return { ok: true, status: res.status };
     }
     catch (error) {
@@ -167,12 +168,26 @@ async function probeAnthropicMessages(base, model) {
         // though the probe itself never authenticated. Harmless for Ollama,
         // which ignores the header entirely (see the module doc above).
         const apiKey = process.env["ANTHROPIC_AUTH_TOKEN"] || process.env["ANTHROPIC_API_KEY"];
+        // ANTHROPIC_CUSTOM_HEADERS (Claude Code's own escape hatch) carries the
+        // Cloudflare AI Gateway's `cf-aig-authorization: Bearer <token>` — without
+        // it, a gateway probe 401s even though the gateway is up. Parsed the
+        // same loose way Claude Code parses it: one `Name: value` per line, so a
+        // single header (the common case) needs no newline. Empty/comment-only
+        // lines are skipped, never crash the probe.
+        const customHeaders = {};
+        for (const line of (process.env["ANTHROPIC_CUSTOM_HEADERS"] ?? "").split(/\r?\n/)) {
+            const colon = line.indexOf(":");
+            if (colon <= 0)
+                continue;
+            customHeaders[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+        }
         const res = await fetch(`${base}/v1/messages`, {
             method: "POST",
             headers: {
                 "content-type": "application/json",
                 "anthropic-version": "2023-06-01",
                 ...(apiKey ? { "x-api-key": apiKey } : {}),
+                ...customHeaders,
             },
             body: JSON.stringify({ model, max_tokens: 1, messages: [{ role: "user", content: "ping" }] }),
             signal: controller.signal,
@@ -381,6 +396,36 @@ export async function doctorCommand(argv) {
         check(report, "OLLAMA_BASE_URL reachability", true, // informational/warning only — see the ANTHROPIC_BASE_URL check above for why
         result.ok ? `reachable: GET ${ollamaBase}/models -> HTTP ${result.status}` : `unreachable: GET ${ollamaBase}/models -> ${result.error}`, result.ok ? "info" : "warn");
     }
+    // Cloudflare Workers AI — the same reachability check the Ollama block
+    // above runs, for the same reason: a keyed provider whose endpoint
+    // (derived from CLOUDFLARE_ACCOUNT_ID, or overridden by
+    // CLOUDFLARE_AI_BASE_URL) might simply be misconfigured. Unlike Ollama,
+    // Workers AI needs the Bearer token to answer at all (a 401 without it),
+    // so the probe sends `Authorization: Bearer $CLOUDFLARE_API_TOKEN` when
+    // set. `/models` is the OpenAI-compatible list endpoint (same shape the
+    // Ollama probe hits); a 404 here still means "host up, path differs",
+    // which is the useful signal, and the check is informational only — same
+    // never-a-hard-failure contract as the Ollama and ANTHROPIC_BASE_URL
+    // probes. Gated on tiering.enabled for ladder rungs, identically to
+    // usesOllamaFlue above.
+    const usesCloudflareFlue = cfg.agents.some((a) => a.coding_agent !== "claude_code" && a.model.startsWith("cloudflare/")) ||
+        (cfg.tiering.enabled && cfg.tiering.tiers.some((t) => t.coding_agent !== "claude_code" && t.model.startsWith("cloudflare/")));
+    if (usesCloudflareFlue && !flags["no-probe"]) {
+        const cfBase = cloudflareAiBaseUrl();
+        if (!cfBase) {
+            check(report, "Cloudflare Workers AI endpoint", true, "CLOUDFLARE_ACCOUNT_ID (or CLOUDFLARE_AI_BASE_URL) is not set — Workers AI base URL can't be resolved", "warn");
+        }
+        else {
+            const cfBaseTrimmed = cfBase.replace(/\/+$/, "");
+            const token = process.env["CLOUDFLARE_API_TOKEN"];
+            const headers = token ? { authorization: `Bearer ${token}` } : {};
+            const result = await withProbeStatus("Cloudflare Workers AI reachability", () => probeGet(`${cfBaseTrimmed}/models`, headers));
+            check(report, "Cloudflare Workers AI reachability", true, // informational/warning only — same contract as the Ollama check above
+            result.ok
+                ? `reachable: GET ${cfBaseTrimmed}/models -> HTTP ${result.status}${token ? "" : " (no CLOUDFLARE_API_TOKEN — sent unauthenticated)"}`
+                : `unreachable: GET ${cfBaseTrimmed}/models -> ${result.error}`, result.ok ? "info" : "warn");
+        }
+    }
     for (const agent of cfg.agents) {
         const label = `agent "${agent.name}"`;
         if (agent.coding_agent === "claude_code") {

package/dist/cli/interview.js

@@ -141,6 +141,7 @@ export async function runInterview(asker, ctx) {
         const auth = await asker.select("Authentication", [
             { value: "login", label: "already logged in via `claude login`", hint: "writes nothing" },
             { value: "key", label: "ANTHROPIC_API_KEY" },
+            { value: "aig", label: "Cloudflare AI Gateway (Anthropic endpoint)" },
             { value: "endpoint", label: "custom endpoint (Ollama / Ollama Cloud / a proxy)" },
         ], "login");
         if (auth === "key") {
@@ -158,6 +159,32 @@ export async function runInterview(asker, ctx) {
             envExampleKeys.push("ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN");
             asker.note("spf doctor now probes ANTHROPIC_BASE_URL with a minimal POST /v1/messages (informational only, never a hard failure) and flags a base URL that already ends in \"/v1\" as a likely double-path mistake — the default above (without a trailing /v1) is exactly what that check is guarding against. It still cannot validate ANTHROPIC_AUTH_TOKEN itself.");
         }
+        else if (auth === "aig") {
+            // Cloudflare AI Gateway's Anthropic endpoint — routes Claude Code's
+            // traffic through a gateway that holds the real Anthropic credentials
+            // (Unified Billing or BYOK), so the operator authenticates to the
+            // GATEWAY, not to Anthropic. The exact env shape comes straight from
+            // developers.cloudflare.com/ai-gateway/integrations/coding-agents/claude-code:
+            //   ANTHROPIC_BASE_URL = https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/anthropic
+            //   ANTHROPIC_API_KEY  = <CF_AIG_TOKEN>   (any value — Claude Code requires it set; the gateway ignores it)
+            //   ANTHROPIC_CUSTOM_HEADERS = cf-aig-authorization: Bearer <CF_AIG_TOKEN>
+            // The gateway token must have Run permission on the gateway.
+            asker.note("Create the gateway in the Cloudflare dashboard (AI Gateway), then use its token with Run permission. The gateway holds the Anthropic credentials (Unified Billing / BYOK); this token authenticates YOU to the gateway.");
+            const baseUrl = await asker.text("ANTHROPIC_BASE_URL", {
+                default: "https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/anthropic",
+                validate: (v) => (v.trim() && !v.includes("<") && v.endsWith("/anthropic") ? null : "must be the gateway's /anthropic endpoint — https://gateway.ai.cloudflare.com/v1/<ACCOUNT_ID>/<GATEWAY_ID>/anthropic"),
+            });
+            env["ANTHROPIC_BASE_URL"] = baseUrl;
+            const token = await asker.secret("CF_AIG_TOKEN (gateway token)", { current: ctx.existingEnv.get("ANTHROPIC_API_KEY") });
+            const tok = token || "replace-me";
+            // Claude Code requires ANTHROPIC_API_KEY to be set even when the
+            // gateway ignores it — the CF doc reuses the gateway token as the
+            // placeholder. The real auth rides on the custom header below.
+            env["ANTHROPIC_API_KEY"] = tok;
+            env["ANTHROPIC_CUSTOM_HEADERS"] = `cf-aig-authorization: Bearer ${tok}`;
+            envExampleKeys.push("ANTHROPIC_BASE_URL", "ANTHROPIC_API_KEY", "ANTHROPIC_CUSTOM_HEADERS");
+            asker.note("spf doctor probes this gateway's /v1/messages with the cf-aig-authorization header (informational, never a hard failure).");
+        }
         // The packaged roster pins planner/reviewer/documenter to their own
         // Flue-style provider/model-id strings, which always win over
         // defaults.model (agents.ts's back-fill only applies when an agent
@@ -223,6 +250,46 @@ export async function runInterview(asker, ctx) {
                 notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to the ollama model chosen above, or spf doctor would report missing FIREWORKS_API_KEY/GEMINI_API_KEY/OPENAI_API_KEY for providers this flow never asked about.");
             }
         }
+        // Cloudflare Workers AI — a keyed provider, so the API token was
+        // collected by the envKeys block above. It ALSO needs an endpoint
+        // address (like ollama needs OLLAMA_BASE_URL): an account id to derive
+        // the standard https://api.cloudflare.com/client/v4/accounts/{id}/ai/v1
+        // URL, or an explicit CLOUDFLARE_AI_BASE_URL override (a custom domain,
+        // or a Cloudflare AI Gateway endpoint). See cloudflare_provider.ts's
+        // cloudflareAiBaseUrl() for the resolution order doctor and dispatch
+        // both share — asking here keeps the interview's answers and the
+        // runtime's resolution from drifting apart.
+        if (provider === "cloudflare") {
+            asker.note("Workers AI model ids start with @cf/ — e.g. @cf/zai-org/glm-5.3-flash. See developers.cloudflare.com/ai/models for the catalog.");
+            const useExplicit = await asker.confirm("Use an explicit base URL instead of an account id (custom domain / AI Gateway)?", false);
+            if (useExplicit) {
+                const baseUrl = await asker.text("CLOUDFLARE_AI_BASE_URL", {
+                    default: "https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/v1",
+                    validate: (v) => (v.trim() && !v.includes("<") ? null : "set the full OpenAI-compatible base URL (no placeholders)"),
+                });
+                env["CLOUDFLARE_AI_BASE_URL"] = baseUrl;
+                envExampleKeys.push("CLOUDFLARE_AI_BASE_URL");
+            }
+            else {
+                const accountId = await asker.text("CLOUDFLARE_ACCOUNT_ID", {
+                    validate: (v) => (v.trim() ? null : "required — find it in the Cloudflare dashboard (right sidebar)"),
+                });
+                env["CLOUDFLARE_ACCOUNT_ID"] = accountId;
+                envExampleKeys.push("CLOUDFLARE_ACCOUNT_ID");
+            }
+            asker.note("spf doctor probes the resolved Workers AI endpoint (informational, never a hard failure).");
+            // Same pinned-roster fix as the ollama branch above: cloudflare is a
+            // single self-served endpoint, not a multi-model aggregator like
+            // openrouter — the packaged roster's planner (fireworks/...),
+            // reviewer, and documenter (openai/...) are NOT reachable through a
+            // Workers AI account, so leaving them pinned would route three agents
+            // at providers whose keys this interview never asked for. Overriding
+            // all three to the chosen cloudflare model is the exact same fix.
+            for (const name of ["planner", "reviewer", "documenter"]) {
+                agentOverrides.push({ name, model: defaults.model });
+            }
+            notes.push("planner/reviewer/documenter pin their own model in the packaged roster and always win over defaults.model — overriding all three to the cloudflare model chosen above, or spf doctor would report missing FIREWORKS_API_KEY/OPENAI_API_KEY for providers a Workers AI account can't serve.");
+        }
     }
     // Declined (the default): today's behavior exactly — on claude_code, the
     // three-agent auto-pin above stands unchanged; on flue, no agents: block

package/dist/core/agent_flue.js

@@ -26,6 +26,7 @@ import { AgentRunError, createBashTool, createEditTool, createGlobTool, createGr
 import { local, sqlite, start } from "@flue/runtime/node";
 import { UsageBreakdown, makeAgentResult } from "./data_types.js";
 import { registerOllamaModel } from "./ollama_provider.js";
+import { registerCloudflareModel } from "./cloudflare_provider.js";
 import * as sandbox from "./sandbox.js";
 import { nowIso, operatorEnv } from "./utils.js";
 const RESULT_SNIPPET_CHARS = 20_000; // tool output rides along whole; clip only guards pathological cases
@@ -296,6 +297,13 @@ export async function run(request, onEvent, onSpawn, onExit) {
     const [provider, modelId] = resolveModel(request.model);
     if (provider === "ollama")
         await registerOllamaModel(modelId);
+    // Cloudflare Workers AI is the same self-registration shape as Ollama
+    // (no pi-ai/Flue built-in "cloudflare" provider on Node) — see
+    // cloudflare_provider.ts's header comment for the Workers AI OpenAI-
+    // compatible endpoint, the slashed `@cf/...` model-id handling, and the
+    // real-Bearer-token (not dummy-key) auth.
+    if (provider === "cloudflare")
+        await registerCloudflareModel(modelId);
     await ensureRuntime(request.flue_db_path);
     REGISTRY.set(request.session_id, {
         model: request.model,

package/dist/core/cloudflare_provider.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Cloudflare Workers AI registration for the Flue backend (agent_flue.ts).
+ *
+ * A sibling of ollama_provider.ts — read that file first; only the deltas are
+ * documented here. Neither pi-ai nor Flue ships a built-in "cloudflare"
+ * provider on Node (the `cloudflare` provider id exists ONLY inside a
+ * Cloudflare Worker's own runtime, where a generated Workers AI binding
+ * registers it — see `@flue/runtime`'s providers module: "On Cloudflare,
+ * registering a `cloudflare` provider in `app.ts` takes precedence over the
+ * generated Workers AI binding default"). In a plain Node process (spf is a
+ * Node CLI), there is no such binding, so we register our own against the
+ * same OpenAI-compatible surface Ollama uses.
+ *
+ * Workers AI's OpenAI-compatible endpoint is served under
+ *   https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1
+ * (the `/v1/chat/completions` the OpenAI SDK appends to `baseURL` is exactly
+ * what Workers AI speaks — verified against developers.cloudflare.com/ai).
+ * Auth is a real Bearer token (`CLOUDFLARE_API_TOKEN`), NOT a dummy: unlike
+ * a local keyless Ollama server, Cloudflare's API rejects an empty/wrong
+ * Authorization header with HTTP 401, so the placeholder-key trick
+ * ollama_provider.ts uses would surface as a 401 at the first dispatch
+ * instead of a clear "set CLOUDFLARE_API_TOKEN" message.
+ *
+ * pi-ai's `openai-completions` api constructs the HTTP client with the
+ * official `OpenAI` SDK (`new OpenAI({ apiKey, baseURL })`), which sends
+ * `Authorization: Bearer <apiKey>` and `params.model = model.id` in the
+ * body — both exactly what Workers AI expects. Its `detectCompat` ALSO has
+ * first-class Workers AI handling keyed off the base URL
+ * (`isCloudflareWorkersAI = ... || baseUrl.includes("api.cloudflare.com")`),
+ * so registering under provider id `"cloudflare"` (not pi-ai's internal
+ * `"cloudflare-workers-ai"`) still activates the right transport compat
+ * (no `store`, `max_completion_tokens`, no long cache retention) via the
+ * URL match. Using `"cloudflare"` matches the provider id Flue's own docs
+ * reserve for the Workers AI override, and keeps the model string short
+ * (`cloudflare/@cf/...`).
+ *
+ * SLASHED MODEL IDS — Workers AI model ids contain slashes
+ * (`@cf/zai-org/glm-5.3-flash`), which is unusual for Flue's
+ * `provider/model-id` format. Verified against `@flue/runtime`'s own
+ * `resolveModel`: it splits on the FIRST slash only (`providerId =
+ * slice(0, slash)`, `modelId = slice(slash+1)`), then does an exact
+ * `models.getModel(providerId, modelId)` lookup — so
+ * `cloudflare/@cf/zai-org/glm-5.3-flash` resolves provider `cloudflare`,
+ * model id `@cf/zai-org/glm-5.3-flash`, and matches a model registered
+ * with exactly that `id`. No special-casing needed; the hermetic test in
+ * cloudflare_provider.test.ts pins this so a future Flue rewrite that
+ * changed the split would fail loudly here, not at a user's first run.
+ *
+ * REASONING / CONTEXT WINDOW — `reasoning: false` and `contextWindow: 0`
+ * mirror ollama_provider.ts's stance for a self-served, arbitrary-model
+ * endpoint: Workers AI's catalog has no single reliable per-model context
+ * window, and the zai/glm thinking-format params pi-ai would emit for a
+ * `reasoning: true` model (`thinking: {type: ...}`, `reasoning_effort`)
+ * are the zai *direct* API's params, not guaranteed to be honored through
+ * Workers AI's OpenAI-compatible surface. Disabled keeps spf's behavior
+ * identical to the ollama case (the agent's `thinking:` level is moot) and
+ * avoids fabricating metadata Workers AI's API doesn't actually provide.
+ */
+import type { Provider } from "@earendil-works/pi-ai";
+/**
+ * The Workers AI OpenAI-compatible base URL. Resolution order, matching
+ * ollama_provider.ts's `ollamaBaseUrl()` "fresh per registration" read:
+ *
+ *   1. `CLOUDFLARE_AI_BASE_URL` — an explicit full URL (gateway, a custom
+ *      domain, an AI Gateway endpoint). Takes precedence so a power user
+ *      can redirect without touching the account id.
+ *   2. `https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1`
+ *      — the standard shape, constructed from the account id.
+ *
+ * Returns `undefined` when NEITHER is set: unlike Ollama, a hosted
+ * Cloudflare endpoint has no sensible localhost default to fall back to —
+ * silently synthesizing one would misroute real dispatches. Callers
+ * (registerCloudflareModel, doctor's probe) treat `undefined` as
+ * "unconfigured, report it" rather than guessing.
+ */
+export declare function cloudflareAiBaseUrl(): string | undefined;
+/**
+ * Registers `modelId` (the part after `cloudflare/` in an agent's `model`
+ * config — e.g. `@cf/zai-org/glm-5.3-flash`) with Flue's provider registry,
+ * alongside every other `cloudflare/*` id ever registered this process.
+ * Idempotent and concurrency-safe in exactly the ways
+ * ollama_provider.ts's `registerOllamaModel` is — see that function's doc;
+ * the `registeredIds`-after-`setProvider` ordering, the `inflight` join,
+ * and the dynamic-import boundary are all identical and kept identical on
+ * purpose (one OpenAI-compatible self-registration pattern across both).
+ *
+ * Throws BEFORE touching Flue's registry if the base URL or API token is
+ * unconfigured — a clearer failure than letting `setProvider()` succeed
+ * and surfacing a 401 / "No API key for provider: cloudflare" at the first
+ * real dispatch.
+ */
+export declare function registerCloudflareModel(modelId: string): Promise<void>;
+/** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
+export declare function providerForTest(): Provider<"openai-completions"> | undefined;
+/** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */
+export declare function resetCloudflareRegistrationForTest(): void;

package/dist/core/cloudflare_provider.js

@@ -0,0 +1,232 @@
+/**
+ * Cloudflare Workers AI registration for the Flue backend (agent_flue.ts).
+ *
+ * A sibling of ollama_provider.ts — read that file first; only the deltas are
+ * documented here. Neither pi-ai nor Flue ships a built-in "cloudflare"
+ * provider on Node (the `cloudflare` provider id exists ONLY inside a
+ * Cloudflare Worker's own runtime, where a generated Workers AI binding
+ * registers it — see `@flue/runtime`'s providers module: "On Cloudflare,
+ * registering a `cloudflare` provider in `app.ts` takes precedence over the
+ * generated Workers AI binding default"). In a plain Node process (spf is a
+ * Node CLI), there is no such binding, so we register our own against the
+ * same OpenAI-compatible surface Ollama uses.
+ *
+ * Workers AI's OpenAI-compatible endpoint is served under
+ *   https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/v1
+ * (the `/v1/chat/completions` the OpenAI SDK appends to `baseURL` is exactly
+ * what Workers AI speaks — verified against developers.cloudflare.com/ai).
+ * Auth is a real Bearer token (`CLOUDFLARE_API_TOKEN`), NOT a dummy: unlike
+ * a local keyless Ollama server, Cloudflare's API rejects an empty/wrong
+ * Authorization header with HTTP 401, so the placeholder-key trick
+ * ollama_provider.ts uses would surface as a 401 at the first dispatch
+ * instead of a clear "set CLOUDFLARE_API_TOKEN" message.
+ *
+ * pi-ai's `openai-completions` api constructs the HTTP client with the
+ * official `OpenAI` SDK (`new OpenAI({ apiKey, baseURL })`), which sends
+ * `Authorization: Bearer <apiKey>` and `params.model = model.id` in the
+ * body — both exactly what Workers AI expects. Its `detectCompat` ALSO has
+ * first-class Workers AI handling keyed off the base URL
+ * (`isCloudflareWorkersAI = ... || baseUrl.includes("api.cloudflare.com")`),
+ * so registering under provider id `"cloudflare"` (not pi-ai's internal
+ * `"cloudflare-workers-ai"`) still activates the right transport compat
+ * (no `store`, `max_completion_tokens`, no long cache retention) via the
+ * URL match. Using `"cloudflare"` matches the provider id Flue's own docs
+ * reserve for the Workers AI override, and keeps the model string short
+ * (`cloudflare/@cf/...`).
+ *
+ * SLASHED MODEL IDS — Workers AI model ids contain slashes
+ * (`@cf/zai-org/glm-5.3-flash`), which is unusual for Flue's
+ * `provider/model-id` format. Verified against `@flue/runtime`'s own
+ * `resolveModel`: it splits on the FIRST slash only (`providerId =
+ * slice(0, slash)`, `modelId = slice(slash+1)`), then does an exact
+ * `models.getModel(providerId, modelId)` lookup — so
+ * `cloudflare/@cf/zai-org/glm-5.3-flash` resolves provider `cloudflare`,
+ * model id `@cf/zai-org/glm-5.3-flash`, and matches a model registered
+ * with exactly that `id`. No special-casing needed; the hermetic test in
+ * cloudflare_provider.test.ts pins this so a future Flue rewrite that
+ * changed the split would fail loudly here, not at a user's first run.
+ *
+ * REASONING / CONTEXT WINDOW — `reasoning: false` and `contextWindow: 0`
+ * mirror ollama_provider.ts's stance for a self-served, arbitrary-model
+ * endpoint: Workers AI's catalog has no single reliable per-model context
+ * window, and the zai/glm thinking-format params pi-ai would emit for a
+ * `reasoning: true` model (`thinking: {type: ...}`, `reasoning_effort`)
+ * are the zai *direct* API's params, not guaranteed to be honored through
+ * Workers AI's OpenAI-compatible surface. Disabled keeps spf's behavior
+ * identical to the ollama case (the agent's `thinking:` level is moot) and
+ * avoids fabricating metadata Workers AI's API doesn't actually provide.
+ */
+/**
+ * The Workers AI OpenAI-compatible base URL. Resolution order, matching
+ * ollama_provider.ts's `ollamaBaseUrl()` "fresh per registration" read:
+ *
+ *   1. `CLOUDFLARE_AI_BASE_URL` — an explicit full URL (gateway, a custom
+ *      domain, an AI Gateway endpoint). Takes precedence so a power user
+ *      can redirect without touching the account id.
+ *   2. `https://api.cloudflare.com/client/v4/accounts/{CLOUDFLARE_ACCOUNT_ID}/ai/v1`
+ *      — the standard shape, constructed from the account id.
+ *
+ * Returns `undefined` when NEITHER is set: unlike Ollama, a hosted
+ * Cloudflare endpoint has no sensible localhost default to fall back to —
+ * silently synthesizing one would misroute real dispatches. Callers
+ * (registerCloudflareModel, doctor's probe) treat `undefined` as
+ * "unconfigured, report it" rather than guessing.
+ */
+export function cloudflareAiBaseUrl() {
+    const explicit = (process.env.CLOUDFLARE_AI_BASE_URL ?? "").trim();
+    if (explicit)
+        return explicit.replace(/\/+$/, "");
+    const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID ?? "").trim();
+    if (accountId)
+        return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
+    return undefined;
+}
+/**
+ * The Bearer token Workers AI expects. `CLOUDFLARE_API_TOKEN` is the env
+ * var name spf already uses for its Cloudflare *sandbox* backend
+ * (data_types.ts's SandboxCloudflareSchema.api_token_env) — reusing it here
+ * means one token serves both a Workers AI model provider AND a Cloudflare
+ * sandbox in the same repo, and a user who already set it for the sandbox
+ * gets the model provider for free. Read fresh per request (the resolver
+ * runs at dispatch time), matching ollama_provider.ts's per-call base URL
+ * read.
+ */
+function cloudflareApiToken() {
+    const token = (process.env.CLOUDFLARE_API_TOKEN ?? "").trim();
+    if (!token)
+        throw new Error("CLOUDFLARE_API_TOKEN is not set — required to authenticate Cloudflare Workers AI (get one at https://dash.cloudflare.com/profile/api-tokens, with the Workers AI > Read permission)");
+    return token;
+}
+// Advisory only — same role as ollama_provider.ts's DEFAULT_MAX_TOKENS:
+// feeds Flue's compaction-reserve sizing, moot since `contextWindow: 0`
+// below disables threshold compaction. Workers AI's OpenAI-compatible
+// surface accepts `max_completion_tokens` (the field pi-ai picks for this
+// provider — detectCompat's `useMaxTokens` does NOT include Workers AI, so
+// `max_completion_tokens`, not `max_tokens`), and the per-model hard cap
+// varies; kept generous.
+const DEFAULT_MAX_TOKENS = 8192;
+/**
+ * Every `cloudflare/<id>` model id a `registerCloudflareModel` call has
+ * ever SUCCEEDED in registering, in call order. `setProvider()` REPLACES
+ * the named provider's entire model list on every call (not additive), so
+ * this Set is what lets each call re-register the FULL union instead of
+ * just the newest id — the same invariant ollama_provider.ts's
+ * `registeredIds` exists to preserve. Without it: register
+ * `@cf/zai-org/glm-5.3-flash`, then `@cf/meta/llama-3.1-8b-instruct`, and
+ * the first becomes an "Unknown model ID" at its next dispatch.
+ */
+const registeredIds = new Set();
+// Registrations currently in flight, keyed by model id — same join semantics
+// as ollama_provider.ts's `inflight`: a second caller for the SAME id that
+// arrives before the first `await` resolves joins that in-progress
+// registration instead of returning with nothing registered yet.
+const inflight = new Map();
+// The most recently constructed provider object — test-only, same reason
+// as ollama_provider.ts's `lastProvider` (Flue exports no `getProvider`).
+let lastProvider;
+function modelFor(id, baseUrl) {
+    return {
+        id,
+        name: id,
+        api: "openai-completions",
+        provider: "cloudflare",
+        baseUrl,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        // Disables Flue's threshold-based compaction — same convention as
+        // ollama_provider.ts: no reliable per-model context window across
+        // Workers AI's catalog, and agent_flue.ts already treats 0 as
+        // "unknown, don't compact".
+        contextWindow: 0,
+        maxTokens: DEFAULT_MAX_TOKENS,
+    };
+}
+/**
+ * Registers `modelId` (the part after `cloudflare/` in an agent's `model`
+ * config — e.g. `@cf/zai-org/glm-5.3-flash`) with Flue's provider registry,
+ * alongside every other `cloudflare/*` id ever registered this process.
+ * Idempotent and concurrency-safe in exactly the ways
+ * ollama_provider.ts's `registerOllamaModel` is — see that function's doc;
+ * the `registeredIds`-after-`setProvider` ordering, the `inflight` join,
+ * and the dynamic-import boundary are all identical and kept identical on
+ * purpose (one OpenAI-compatible self-registration pattern across both).
+ *
+ * Throws BEFORE touching Flue's registry if the base URL or API token is
+ * unconfigured — a clearer failure than letting `setProvider()` succeed
+ * and surfacing a 401 / "No API key for provider: cloudflare" at the first
+ * real dispatch.
+ */
+export async function registerCloudflareModel(modelId) {
+    if (registeredIds.has(modelId))
+        return;
+    const existing = inflight.get(modelId);
+    if (existing)
+        return existing;
+    const baseUrl = cloudflareAiBaseUrl();
+    if (!baseUrl) {
+        throw new Error("Cloudflare Workers AI base URL is not configured — set CLOUDFLARE_ACCOUNT_ID (for the standard https://api.cloudflare.com/client/v4/accounts/{id}/ai/v1 endpoint) or CLOUDFLARE_AI_BASE_URL (for a custom/AI Gateway endpoint)");
+    }
+    // Eagerly resolve the token too: a missing token throws here, before
+    // setProvider(), so the error names the env var rather than arriving as
+    // pi-ai's generic "No API key for provider: cloudflare" at dispatch.
+    cloudflareApiToken();
+    const promise = (async () => {
+        // Same lazy-import rationale as ollama_provider.ts: keeps this module's
+        // cloudflare-only symbols (especially the deep `openai-completions.lazy`
+        // subpath) off the module graph of anything that imports agent_flue.ts
+        // for `resolveModel()` alone (doctor.ts, interview.ts) without ever
+        // dispatching a cloudflare call.
+        const [{ createProvider }, { openAICompletionsApi }, { setProvider }] = await Promise.all([
+            import("@earendil-works/pi-ai"),
+            import("@earendil-works/pi-ai/api/openai-completions.lazy"),
+            import("@flue/runtime/internal"),
+        ]);
+        const ids = new Set(registeredIds);
+        ids.add(modelId);
+        const models = [...ids].map((id) => modelFor(id, baseUrl));
+        const options = {
+            id: "cloudflare",
+            name: "Cloudflare Workers AI",
+            baseUrl,
+            auth: {
+                apiKey: {
+                    name: "CLOUDFLARE_API_TOKEN",
+                    // Read fresh per dispatch (per pi-ai's resolve() contract), so a
+                    // token set AFTER the first registration still works for the next
+                    // dispatch without re-registering. Throws a clear message if
+                    // unset — see cloudflareApiToken()'s doc.
+                    resolve: async () => ({ auth: { apiKey: cloudflareApiToken() } }),
+                },
+            },
+            models,
+            api: openAICompletionsApi(),
+        };
+        // setProvider() upserts this one provider id and leaves every other
+        // registered provider untouched — same additive primitive
+        // ollama_provider.ts uses (NOT `start({ providers: [...] })`, which
+        // would REPLACE the whole default set and drop anthropic/openai/etc.).
+        const provider = createProvider(options);
+        setProvider(provider);
+        lastProvider = provider;
+        for (const id of ids)
+            registeredIds.add(id);
+    })();
+    inflight.set(modelId, promise);
+    try {
+        await promise;
+    }
+    finally {
+        inflight.delete(modelId);
+    }
+}
+/** Test-only: the most recently constructed provider object (see `lastProvider`'s doc). */
+export function providerForTest() {
+    return lastProvider;
+}
+/** Test-only: forgets accumulated ids so test files don't leak into each other. Does not touch Flue's own registry — pair with `resetModelsForTests()` from `@flue/runtime/internal`. */
+export function resetCloudflareRegistrationForTest() {
+    registeredIds.clear();
+    inflight.clear();
+    lastProvider = undefined;
+}

package/dist/core/providers.js

@@ -25,4 +25,14 @@ export const PROVIDER_ENV_KEYS = {
     // prompt for. An empty array here means "known provider, needs no key",
     // never "unknown provider" (that's a missing table entry, not `[]`).
     ollama: [],
+    // Cloudflare Workers AI — a real Bearer token (NOT keyless like ollama;
+    // Cloudflare's API 401s on an empty Authorization header). The base URL
+    // is derived from CLOUDFLARE_ACCOUNT_ID (or overridden by
+    // CLOUDFLARE_AI_BASE_URL) — that's collected separately in the `spf init`
+    // interview's cloudflare branch, the same way the ollama branch collects
+    // OLLAMA_BASE_URL, since PROVIDER_ENV_KEYS only carries the KEY a provider
+    // needs, not a base address. Same env var name spf's Cloudflare *sandbox*
+    // backend already uses (data_types.ts's SandboxCloudflareSchema), so one
+    // token serves both.
+    cloudflare: ["CLOUDFLARE_API_TOKEN"],
 };

package/dist/core/watch.js

@@ -57,6 +57,7 @@
 import path from "node:path";
 import { attemptAdwId, attemptBranch, attemptWorktreePath, runBestOf } from "./fanout.js";
 import { PRIORITY_RANK } from "./data_types.js";
+import { redact } from "./otel.js";
 import { parseRefineMarker } from "./refine.js";
 import { newId } from "./utils.js";
 const MAX_ORPHAN_ATTEMPTS = 2;
@@ -1255,7 +1256,18 @@ export async function claimSpecs(deps, state, from = "spec-ready") {
 }
 function tickErrorHandler(deps, stage) {
     return (error) => {
-        const message = error.message;
+        // undici (and the tracker/code-host clients built on `fetch`) collapse
+        // every connection-level failure to the bare string "fetch failed" and
+        // put the actual reason (DNS, ECONNREFUSED, a TLS error — each with a
+        // different fix) on `error.cause` — same fold-in `doctor.ts`'s
+        // `probeOtel` already does, otherwise this alert has no diagnostic value.
+        const err = error;
+        const cause = err.cause;
+        const detail = cause ? ` (${cause.code ?? cause.message ?? String(cause)})` : "";
+        // redact(): a fetch failure routinely embeds the URL it attempted, which
+        // may carry credentials (e.g. a tracker API token) — never let that reach
+        // a log line or an outbound Slack/Teams/webhook notification.
+        const message = redact(`${err.message}${detail}`, []);
         deps.log(`watch: ${stage} error: ${message}`);
         deps.notify({ kind: "watch_error", level: "error", title: `watch: ${stage} error`, detail: message, fields: [] });
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",