@weiping/magpie-cf-jev 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# magpie-cf-jev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cloudflare Workers AI 的 Jev / Clef 作为 **magpie 决策模型供应商**（provider id `cf-jev`）的一个插件。
+
+它存在的唯一理由：**绕过 magpie 上游的一个信封 bug**。
+
+## 问题
+
+Workers AI 跑 `typesafe/jev` 时，回答套了两层信封：
+
+```json
+{"result": {"state":"Completed", "result": {"model":"jev-1.13.0","answers":{…},"usage":{…}}}, "success": true, …}
+```
+
+magpie 的 `provider.DecideAnswer`（`internal/provider/decide_wire.go`）只拆**一层** `result`，于是交给调用方的是 `{"state":"Completed","result":{…}}` —— 顶层没有 `answers`。后果：
+
+- magpie 自己的分类器（`readJev`）读不到答案，`not a System One answer`；
+- `/v1/systemone` 的客户端（例如 mbridge 的分类器）读不到 `answers`，落回默认档。
+
+Clef 只有一层信封，所以只测 Clef 时看不出来。
+
+## 这插件怎么修的
+
+magpie 的插件可以声明自己是决策供应商：`config` 钩子里 `decide: true`，模型的 `decides: true`，于是 magpie 把该 provider 的 `Decide` 指向 `plugin://cf-jev/v1`，所有 System One 请求都过插件的 `fetch`。
+
+插件在这个 `fetch` 里调 Cloudflare，**把两层信封拆干净**，只把 `{"model":…,"answers":…,"usage":…}` 交回 magpie。magpie 对 System One 路径不再拆信封（`DecideAnswer` 原样返回），所以答案带着顶层 `answers` 到达 magpie 自己和它的所有客户端。
+
+实测（本机，2026-10-25）：
+
+| 模型 | 插件直连 | 经 magpie `/v1/systemone` |
+| --- | --- | --- |
+| `cf-jev/typesafe/jev` | 200 · 1.0s | 200 · 1.2s · `keys=[model,answers,usage]` |
+| `cf-jev/@cf/cloudflare/clef` | 200 · 0.5s | 200 · 0.5s |
+| `cf-jev/@cf/cloudflare/clef-flash` | 200 · 0.4s | 200 · 0.5s |
+
+## 用法
+
+```sh
+# 1. 装插件（本地目录，不走 npm）
+magpie plugin add ~/workspace/dev/cf-jev-plugin
+
+# 2. 登录，粘贴 Cloudflare API token
+#    只做 Workers AI 的 token 可能列不出账号，那就按 "<account id>:<token>" 粘
+magpie plugin login cf-jev
+
+# 3. 确认三个决策模型都在，且 decide 探针通过
+magpie provider models cf-jev
+magpie provider test cf-jev        # ✓ decide … typesafe/jev
+
+# 4. 把分类组指到插件（order：快的在前）
+magpie group set mb-classifier \
+  models=cf-jev/typesafe/jev,cf-jev/@cf/cloudflare/clef,cf-jev/@cf/cloudflare/clef-flash,typesafe/jev-latest \
+  routing=order
+```
+
+> `magpie group mb-classifier` 对决策组总是显示 `not served now, skipped` / `no member ready` —— 那是 magpie CLI 的显示假象（它拿「给 agent 的模型目录」查成员，而决策模型本来就不在里面），不代表插件不能用。真要看可用性：`magpie provider test cf-jev` 或直接发一个 `/v1/systemone`。
+
+## 回滚
+
+```sh
+magpie group set mb-classifier \
+  models=cloudflare-jev/typesafe/jev,cloudflare-jev/@cf/cloudflare/clef,cloudflare-jev/@cf/cloudflare/clef-flash,typesafe/jev-latest \
+  routing=order
+magpie plugin rm cf-jev          # 或 magpie plugin off cf-jev
+```
+
+## 什么时候不再需要它
+
+上游 `yetone/magpie` 把 `DecideAnswer` 改成「还剩一层 `result` 就继续拆」之后：
+
+- magpie 自带的 `cloudflare-jev` 供应商会直接可用，这个插件就可以删掉；
+- 补丁已经写好并验证过（`TestCloudflareAnswerPeelsTheEnvelopes` 在旧代码上红、新代码上绿），
+  只是还没有 PR 权限能推上去。
+
+## 文件
+
+| 文件 | 作用 |
+| --- | --- |
+| `index.mjs` | 插件本体：`config` 声明决策供应商，`auth.loader` 返回自带 `fetch` 的实现，`peel()` 拆信封 |
+| `smoke.mjs` | 不经 magpie、直接按 host 的方式调 `fetch` 的自检（token 从 magpie 的 `providers.json` 读，不落盘） |
+| `peel.test.mjs` | `peel()` 的单元测试：两层信封、一层信封、错误体、已经扁平的答案 |
+
+```sh
+node --test peel.test.mjs     # 单元测试
+node smoke.mjs                # 打真实 Cloudflare
+```

package/index.mjs

@@ -0,0 +1,188 @@
+// cf-jev: Cloudflare Workers AI as a magpie decision provider.
+//
+// magpie can serve a plugin's decision API (its config hook's `decide`, a
+// model's `decides`), asked at the provider's own base /systemone through
+// the plugin's fetch. That fetch is where this plugin belongs: Workers AI
+// answers a Jev in two envelopes — Cloudflare's own {"result": …} and the
+// Jev's {"state": …,"result": …} — and magpie unwraps one of them
+// (provider.DecideAnswer), so a Jev asked directly comes back with no
+// answers at the top and every System One client refuses it (magpie's own
+// classifier included). Here the envelopes are peeled before the answer
+// leaves the plugin, so magpie and its clients see the System One answer
+// as TypeSafe's own API and a Clef give it: `answers` at the top.
+//
+// The upstream fix (peel while another envelope is there) has been sent
+// to yetone/magpie; until it ships, this plugin is the way to route a
+// group's classifier through Workers AI.
+
+const PROVIDER = "cf-jev";
+const API = "https://api.cloudflare.com/client/v4";
+
+// MODELS are the decision models Workers AI serves, and how each is asked:
+// a Jev is a run of typesafe/jev whose question is the run's input, while
+// a Clef is asked as it is, at its own path, naming itself.
+const MODELS = [
+  { id: "typesafe/jev", name: "Jev (Workers AI)", clef: "" },
+  { id: "@cf/cloudflare/clef", name: "Clef", clef: "clef" },
+  { id: "@cf/cloudflare/clef-flash", name: "Clef Flash", clef: "clef-flash" },
+];
+
+// modelOf is the model a System One question names. A probe asks with no
+// model, or with the Jev's own name (jev-latest, jev-preview, as
+// TypeSafe's API calls it): that is the Jev Workers AI runs.
+const modelOf = (id) => {
+  const said = String(id ?? "").trim();
+  const hit = MODELS.find((m) => m.id === said);
+  if (hit) return hit;
+  return /^(|(typesafe\/)?jev(-latest|-preview)?)$/.test(said) ? MODELS[0] : undefined;
+};
+
+// peel is an answer out of whatever envelopes it came in: Cloudflare's own
+// {"result": …}, the Jev's {"state": …,"result": …}, or neither. It stops
+// as soon as the body has answers of its own, so a failure's errors and an
+// already-flat answer are left as they came.
+export function peel(body) {
+  let cur = body;
+  for (let i = 0; i < 4; i++) {
+    if (!cur || typeof cur !== "object") return cur;
+    if (cur.answers) return cur;
+    if (!cur.result || typeof cur.result !== "object") return cur;
+    cur = cur.result;
+  }
+  return cur;
+}
+
+// account is the Cloudflare account the token works in: the one the key
+// names (a key pasted as "<account id>:<token>" says so), else the first
+// the token can list, as magpie's built-in provider looks it up.
+const accounts = new Map();
+async function account(token, named) {
+  if (named) return named;
+  if (accounts.has(token)) return accounts.get(token);
+  const res = await fetch(`${API}/accounts`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok || !Array.isArray(body?.result) || !body.result[0]?.id) {
+    const why = body?.errors?.[0]?.message ?? `${res.status} ${res.statusText}`;
+    throw new Error(
+      `Cloudflare listed no account for this token: ${why}. ` +
+        `A token made for Workers AI alone may not list accounts — sign in with "<account id>:<token>" then.`,
+    );
+  }
+  accounts.set(token, body.result[0].id);
+  return body.result[0].id;
+}
+
+// ask posts a System One question to Workers AI the way it takes it, and
+// gives back the answer as System One gives it: answers at the top.
+export async function ask({ token, named, model, question, signal }) {
+  // magpie probes a decision API while it lists the provider, before anyone
+  // has signed in: told so plainly rather than as a failed account lookup
+  if (!token) return { status: 401, body: "cf-jev is not signed in: magpie plugin login cf-jev" };
+  const m = modelOf(model);
+  if (!m) throw new Error(`${PROVIDER} does not serve ${model}`);  const acct = await account(token, named);
+  const url = m.clef
+    ? `${API}/accounts/${acct}/ai/run/${m.id}`
+    : `${API}/accounts/${acct}/ai/run`;
+  const body = m.clef
+    ? { model: m.clef, state: question.state, questions: question.questions }
+    : { model: m.id, input: { state: question.state, questions: question.questions } };
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal,
+  });
+  const raw = await res.text();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { status: 502, body: raw || `${res.status} ${res.statusText}` };
+  }
+  if (!res.ok || parsed.success === false) {
+    const why =
+      parsed?.errors?.map?.((e) => e?.message).filter(Boolean).join("; ") ||
+      `${res.status} ${res.statusText}`;
+    return { status: res.ok ? 502 : res.status, body: why };
+  }
+  return { status: 200, body: JSON.stringify(peel(parsed)) };
+}
+
+export async function CfJevPlugin() {
+  return {
+    config: async (cfg) => {
+      cfg.provider ??= {};
+      const was = cfg.provider[PROVIDER] ?? {};
+      cfg.provider[PROVIDER] = {
+        name: "Cloudflare Workers AI · Jev (cf-jev)",
+        ...was,
+        // magpie's own field: this provider serves a decision API
+        // (System One), asked at its base /systemone through this fetch
+        decide: true,
+        models: {
+          ...Object.fromEntries(MODELS.map((m) => [m.id, { name: m.name, decides: true }])),
+          ...(was.models ?? {}),
+        },
+      };
+    },
+    auth: {
+      provider: PROVIDER,
+      methods: [
+        {
+          type: "api",
+          label: "Cloudflare API token (Workers AI)",
+          placeholder: "token, or <account id>:<token>",
+        },
+      ],
+      async loader(getAuth) {
+        const auth = (await getAuth()) ?? {};
+        const raw = String(auth.key ?? auth.apiKey ?? "").trim();
+        // a key pasted as "<account id>:<token>" names the account itself,
+        // which a token made for Workers AI alone can't be asked for
+        const cut = raw.indexOf(":");
+        const named = cut > 0 ? raw.slice(0, cut).trim() : "";
+        const token = cut > 0 ? raw.slice(cut + 1).trim() : raw;
+        return {
+          apiKey: token,
+          // where magpie thinks the provider's requests go: this fetch is
+          // what answers them, so it is told a Cloudflare-shaped base and
+          // never asked to reach it
+          baseURL: API,
+          async fetch(input, init) {
+            const url = typeof input === "string" ? input : (input?.url ?? String(input));
+            const path = (() => {
+              try {
+                return new URL(url).pathname;
+              } catch {
+                return url;
+              }
+            })();
+            if (!path.endsWith("/systemone")) {
+              return new Response(`cf-jev serves System One only: ${path}`, { status: 404 });
+            }
+            let question;
+            try {
+              question = JSON.parse(String(init?.body ?? "{}"));
+            } catch {
+              return new Response("cf-jev got no System One question", { status: 400 });
+            }
+            const out = await ask({
+              token,
+              named,
+              model: question.model,
+              question,
+              signal: init?.signal,
+            });
+            if (out.status !== 200) return new Response(out.body, { status: out.status });
+            return new Response(out.body, {
+              status: 200,
+              headers: { "Content-Type": "application/json" },
+            });
+          },
+        };
+      },
+    },
+  };
+}

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@weiping/magpie-cf-jev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Cloudflare Workers AI (Jev and Clef) as a magpie decision provider, with the answers read out of Cloudflare's envelope",
+  "type": "module",
+  "main": "./index.mjs",
+  "exports": "./index.mjs",
+  "files": ["index.mjs", "README.md"],
+  "keywords": [
+    "magpie",
+    "magpie-plugin",
+    "opencode",
+    "opencode-plugin",
+    "cloudflare",
+    "workers-ai",
+    "jev",
+    "clef",
+    "system-one"
+  ],
+  "author": "weiping",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test peel.test.mjs"
+  }
+}