mslxdff 0.1.200 → 0.1.203

package/src/providers/zcode/chat.js

@@ -1,179 +1,179 @@
-// zcode 模型转发：OpenAI 请求 → Anthropic messages（网关出站恒流式；非流式本地聚合回 OpenAI JSON）。
-// 失败响应带 x-mslxdff-zcode-kind 标记，供 provider 工厂决定冷却策略。
-import { timeoutSignal } from "../../compat.js";
-import { effortLevelFromBody } from "../../thinking-effort.js";
-import { ZCODE_MESSAGES_URL, canonicalZcodeModel, zcodeErrorKind } from "./const.js";
-import { shapeZcodeWireRequest } from "./context-shape.js";
-import { buildZcodeModelHeaders } from "./headers.js";
-import { aggregateAnthropicToOpenAi, anthropicToOpenAiStream } from "./sse.js";
-
-const DEFAULT_MAX_TOKENS = 4096;
-
-function textOf(content) {
-  if (typeof content === "string") return content;
-  if (Array.isArray(content)) return content.filter((p) => p?.type === "text").map((p) => p.text || "").join("");
-  return "";
-}
-
-function mapToolChoice(tc) {
-  if (!tc) return undefined;
-  if (tc === "auto") return { type: "auto" };
-  if (tc === "required") return { type: "any" };
-  if (tc === "none") return { type: "none" };
-  const name = tc?.function?.name;
-  return name ? { type: "tool", name: String(name) } : undefined;
-}
-
-export function toAnthropicRequest(body = {}) {
-  const messages = [];
-  let system = "";
-  for (const m of Array.isArray(body.messages) ? body.messages : []) {
-    const role = String(m?.role || "");
-    if (role === "system") {
-      const part = textOf(m.content);
-      if (part) system += (system ? "\n\n" : "") + part;
-      continue;
-    }
-    if (role === "tool") {
-      messages.push({
-        role: "user",
-        content: [{ type: "tool_result", tool_use_id: String(m.tool_call_id || ""), content: typeof m.content === "string" ? m.content : textOf(m.content) }],
-      });
-      continue;
-    }
-    if (role === "assistant") {
-      const blocks = [];
-      const text = textOf(m.content);
-      if (text) blocks.push({ type: "text", text });
-      for (const tc of Array.isArray(m.tool_calls) ? m.tool_calls : []) {
-        let input = {};
-        try {
-          input = JSON.parse(tc?.function?.arguments || "{}");
-        } catch {}
-        blocks.push({ type: "tool_use", id: String(tc?.id || ""), name: String(tc?.function?.name || ""), input });
-      }
-      if (blocks.length) messages.push({ role: "assistant", content: blocks });
-      continue;
-    }
-    messages.push({ role: "user", content: textOf(m.content) });
-  }
-
-  const req = {
-    model: canonicalZcodeModel(body.model),
-    max_tokens: Number(body.max_tokens ?? body.max_completion_tokens) || DEFAULT_MAX_TOKENS,
-    messages,
-    stream: true, // 上游恒流式；非流式在本地聚合
-  };
-  if (system) req.system = system;
-  if (Number.isFinite(Number(body.temperature))) req.temperature = Number(body.temperature);
-  if (Array.isArray(body.tools) && body.tools.length) {
-    req.tools = body.tools
-      .map((t) => ({
-        name: String(t?.function?.name || t?.name || ""),
-        description: String(t?.function?.description || t?.description || ""),
-        input_schema: t?.function?.parameters || t?.parameters || { type: "object", properties: {} },
-      }))
-      .filter((t) => t.name);
-  }
-  // tool_choice 独立映射（不依赖 tools 是否在场，客户端显式给定即按 Anthropic 形状透出）
-  const choice = mapToolChoice(body.tool_choice);
-  if (choice) req.tool_choice = choice;
-  if (body.stop !== undefined && body.stop !== null) {
-    req.stop_sequences = Array.isArray(body.stop) ? body.stop : [String(body.stop)];
-  }
-  // 思考档位透传（change fix-thinking-effort-passthrough）：Anthropic 形状的 thinking 对象原样带上；
-  // effort 有则原样、无则由 reasoning_effort 回退。上游不认就如实透出 400，不替上游静默吞掉。
-  if (body.thinking && typeof body.thinking === "object") req.thinking = body.thinking;
-  // 档位载体统一走共享词表（只取真档位，不含 thinking.type 开关）：reasoning_effort ＞ reasoningEffort ＞ effort。
-  const effort = effortLevelFromBody(body);
-  if (effort) req.effort = effort;
-  return req;
-}
-
-export function classifyZcodeFailure(status, payload) {
-  const code = Number(payload?.code) || 0;
-  let kind = zcodeErrorKind(code);
-  if (kind === "unknown") {
-    if (status === 401) kind = "auth";
-    else if (status === 429) kind = "rate_limit";
-    else if (status >= 500) kind = "server";
-  }
-  return { kind, code, status, message: String(payload?.msg || payload?.message || "").trim() };
-}
-
-const ERROR_MAP = {
-  auth: { status: 401, type: "auth_error", text: (f) => `zcode: 登录已失效（code ${f.code || 1006}）。请运行 mslxdff -provider zcode login 重新登录` },
-  quota: { status: 429, type: "quota_exhausted", text: () => "zcode: 免费额度已用完（按日重置），请明日再试或添加账号" },
-  rate_limit: { status: 429, type: "all_cooling", text: () => "zcode: 上游限流（账号冷却中），请稍后重试" },
-  security: { status: 403, type: "security_reject", text: (f) => `zcode: 安全校验拒绝（code ${f.code || 3007}）${f.message ? `：${f.message}` : ""} · v3.14.4 起模型请求已免验证码（仅 claim 通道仍需要），偶发请重试，见 docs/adr/0038` },
-  param: { status: 400, type: "invalid_request", text: (f) => `zcode: 请求参数被上游拒绝（code ${f.code}）${f.message ? `：${f.message}` : ""}` },
-  server: { status: 502, type: "upstream_error", text: (f) => `zcode: 上游服务异常${f.code ? `（code ${f.code}）` : ""}${f.message ? `：${f.message}` : ""}` },
-  network: { status: 502, type: "upstream_error", text: (f) => `zcode: 网络错误 ${f.message || ""}`.trim() },
-  unknown: { status: 502, type: "upstream_error", text: (f) => `zcode: 上游错误（HTTP ${f.status || "?"}${f.code ? ` code ${f.code}` : ""}）${f.message ? `：${f.message}` : ""}` },
-};
-
-export function zcodeErrorResponse(fail = {}) {
-  const kind = ERROR_MAP[fail.kind] ? fail.kind : "unknown";
-  const entry = ERROR_MAP[kind];
-  const headers = { "Content-Type": "application/json" };
-  if (fail.kind) headers["x-mslxdff-zcode-kind"] = fail.kind;
-  return new Response(JSON.stringify({ error: { message: entry.text(fail), type: entry.type, code: fail.code || 0 } }), {
-    status: entry.status,
-    headers,
-  });
-}
-
-export async function forwardZcodeChat({ body, token, deviceMid, fetchImpl, version, timeoutMs = 120_000, provider = "zai" } = {}) {
-  const anthropicBody = toAnthropicRequest(body);
-  const modelId = anthropicBody.model; // 响应回显用 canonical id；出站另行归一
-  // 官方线形：小写模型 + system 身份块 + currentDate 前缀（缺任一 → 上游 3012）。
-  // deviceMid 入参保留签名兼容，但模型请求出站不带（官方 CLI 模型请求不带该头，实测）。
-  const wireBody = shapeZcodeWireRequest(anthropicBody, { provider });
-  const headers = { "content-type": "application/json", ...buildZcodeModelHeaders({ token, version }) };
-  void deviceMid;
-
-  let res;
-  try {
-    res = await fetchImpl(ZCODE_MESSAGES_URL, {
-      method: "POST",
-      headers,
-      body: JSON.stringify(wireBody),
-      signal: timeoutSignal(timeoutMs),
-    });
-  } catch (e) {
-    return zcodeErrorResponse({ kind: "network", message: String(e?.message || e).slice(0, 160) });
-  }
-
-  if (!res.ok) {
-    const payload = await res.json().catch(() => null);
-    return zcodeErrorResponse({ ...classifyZcodeFailure(res.status, payload), model: modelId });
-  }
-
-  // 上游业务错误惯例：HTTP 200 + JSON body（code 非 0/200）→ 同样按错误分类
-  if (!String(res.headers.get("content-type") || "").includes("text/event-stream")) {
-    const payload = await res.json().catch(() => null);
-    const code = Number(payload?.code);
-    const bizOk = payload?.success !== false && (!Number.isFinite(code) || code === 0 || code === 200);
-    if (payload && !bizOk) {
-      return zcodeErrorResponse({ ...classifyZcodeFailure(res.status, payload), model: modelId });
-    }
-    if (payload && body?.stream === false) {
-      return new Response(JSON.stringify(payload), { status: 200, headers: { "Content-Type": "application/json" } });
-    }
-  }
-
-  if (body?.stream !== false) {
-    const stream = anthropicToOpenAiStream(res.body, { model: modelId });
-    return new Response(stream, {
-      status: 200,
-      headers: { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache" },
-    });
-  }
-
-  const text = await res.text();
-  const out = await aggregateAnthropicToOpenAi(text, { model: modelId });
-  if (out.error) {
-    return zcodeErrorResponse({ kind: out.error.kind || "server", code: out.error.code || 0, status: 200, message: out.error.message });
-  }
-  return new Response(JSON.stringify(out.openAi), { status: 200, headers: { "Content-Type": "application/json" } });
-}
+// zcode 模型转发：OpenAI 请求 → Anthropic messages（网关出站恒流式；非流式本地聚合回 OpenAI JSON）。
+// 失败响应带 x-mslxdff-zcode-kind 标记，供 provider 工厂决定冷却策略。
+import { timeoutSignal } from "../../compat.js";
+import { effortLevelFromBody } from "../../thinking-effort.js";
+import { ZCODE_MESSAGES_URL, canonicalZcodeModel, zcodeErrorKind } from "./const.js";
+import { shapeZcodeWireRequest } from "./context-shape.js";
+import { buildZcodeModelHeaders } from "./headers.js";
+import { aggregateAnthropicToOpenAi, anthropicToOpenAiStream } from "./sse.js";
+
+const DEFAULT_MAX_TOKENS = 4096;
+
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) return content.filter((p) => p?.type === "text").map((p) => p.text || "").join("");
+  return "";
+}
+
+function mapToolChoice(tc) {
+  if (!tc) return undefined;
+  if (tc === "auto") return { type: "auto" };
+  if (tc === "required") return { type: "any" };
+  if (tc === "none") return { type: "none" };
+  const name = tc?.function?.name;
+  return name ? { type: "tool", name: String(name) } : undefined;
+}
+
+export function toAnthropicRequest(body = {}) {
+  const messages = [];
+  let system = "";
+  for (const m of Array.isArray(body.messages) ? body.messages : []) {
+    const role = String(m?.role || "");
+    if (role === "system") {
+      const part = textOf(m.content);
+      if (part) system += (system ? "\n\n" : "") + part;
+      continue;
+    }
+    if (role === "tool") {
+      messages.push({
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: String(m.tool_call_id || ""), content: typeof m.content === "string" ? m.content : textOf(m.content) }],
+      });
+      continue;
+    }
+    if (role === "assistant") {
+      const blocks = [];
+      const text = textOf(m.content);
+      if (text) blocks.push({ type: "text", text });
+      for (const tc of Array.isArray(m.tool_calls) ? m.tool_calls : []) {
+        let input = {};
+        try {
+          input = JSON.parse(tc?.function?.arguments || "{}");
+        } catch {}
+        blocks.push({ type: "tool_use", id: String(tc?.id || ""), name: String(tc?.function?.name || ""), input });
+      }
+      if (blocks.length) messages.push({ role: "assistant", content: blocks });
+      continue;
+    }
+    messages.push({ role: "user", content: textOf(m.content) });
+  }
+
+  const req = {
+    model: canonicalZcodeModel(body.model),
+    max_tokens: Number(body.max_tokens ?? body.max_completion_tokens) || DEFAULT_MAX_TOKENS,
+    messages,
+    stream: true, // 上游恒流式；非流式在本地聚合
+  };
+  if (system) req.system = system;
+  if (Number.isFinite(Number(body.temperature))) req.temperature = Number(body.temperature);
+  if (Array.isArray(body.tools) && body.tools.length) {
+    req.tools = body.tools
+      .map((t) => ({
+        name: String(t?.function?.name || t?.name || ""),
+        description: String(t?.function?.description || t?.description || ""),
+        input_schema: t?.function?.parameters || t?.parameters || { type: "object", properties: {} },
+      }))
+      .filter((t) => t.name);
+  }
+  // tool_choice 独立映射（不依赖 tools 是否在场，客户端显式给定即按 Anthropic 形状透出）
+  const choice = mapToolChoice(body.tool_choice);
+  if (choice) req.tool_choice = choice;
+  if (body.stop !== undefined && body.stop !== null) {
+    req.stop_sequences = Array.isArray(body.stop) ? body.stop : [String(body.stop)];
+  }
+  // 思考档位透传（change fix-thinking-effort-passthrough）：Anthropic 形状的 thinking 对象原样带上；
+  // effort 有则原样、无则由 reasoning_effort 回退。上游不认就如实透出 400，不替上游静默吞掉。
+  if (body.thinking && typeof body.thinking === "object") req.thinking = body.thinking;
+  // 档位载体统一走共享词表（只取真档位，不含 thinking.type 开关）：reasoning_effort ＞ reasoningEffort ＞ effort。
+  const effort = effortLevelFromBody(body);
+  if (effort) req.effort = effort;
+  return req;
+}
+
+export function classifyZcodeFailure(status, payload) {
+  const code = Number(payload?.code) || 0;
+  let kind = zcodeErrorKind(code);
+  if (kind === "unknown") {
+    if (status === 401) kind = "auth";
+    else if (status === 429) kind = "rate_limit";
+    else if (status >= 500) kind = "server";
+  }
+  return { kind, code, status, message: String(payload?.msg || payload?.message || "").trim() };
+}
+
+const ERROR_MAP = {
+  auth: { status: 401, type: "auth_error", text: (f) => `zcode: 登录已失效（code ${f.code || 1006}）。请运行 mslxdff -provider zcode login 重新登录` },
+  quota: { status: 429, type: "quota_exhausted", text: () => "zcode: 免费额度已用完（按日重置），请明日再试或添加账号" },
+  rate_limit: { status: 429, type: "all_cooling", text: () => "zcode: 上游限流（账号冷却中），请稍后重试" },
+  security: { status: 403, type: "security_reject", text: (f) => `zcode: 安全校验拒绝（code ${f.code || 3007}）${f.message ? `：${f.message}` : ""} · v3.14.4 起模型请求已免验证码（仅 claim 通道仍需要），偶发请重试，见 docs/adr/0038` },
+  param: { status: 400, type: "invalid_request", text: (f) => `zcode: 请求参数被上游拒绝（code ${f.code}）${f.message ? `：${f.message}` : ""}` },
+  server: { status: 502, type: "upstream_error", text: (f) => `zcode: 上游服务异常${f.code ? `（code ${f.code}）` : ""}${f.message ? `：${f.message}` : ""}` },
+  network: { status: 502, type: "upstream_error", text: (f) => `zcode: 网络错误 ${f.message || ""}`.trim() },
+  unknown: { status: 502, type: "upstream_error", text: (f) => `zcode: 上游错误（HTTP ${f.status || "?"}${f.code ? ` code ${f.code}` : ""}）${f.message ? `：${f.message}` : ""}` },
+};
+
+export function zcodeErrorResponse(fail = {}) {
+  const kind = ERROR_MAP[fail.kind] ? fail.kind : "unknown";
+  const entry = ERROR_MAP[kind];
+  const headers = { "Content-Type": "application/json" };
+  if (fail.kind) headers["x-mslxdff-zcode-kind"] = fail.kind;
+  return new Response(JSON.stringify({ error: { message: entry.text(fail), type: entry.type, code: fail.code || 0 } }), {
+    status: entry.status,
+    headers,
+  });
+}
+
+export async function forwardZcodeChat({ body, token, deviceMid, fetchImpl, version, timeoutMs = 120_000, provider = "zai" } = {}) {
+  const anthropicBody = toAnthropicRequest(body);
+  const modelId = anthropicBody.model; // 响应回显用 canonical id；出站另行归一
+  // 官方线形：小写模型 + system 身份块 + currentDate 前缀（缺任一 → 上游 3012）。
+  // deviceMid 入参保留签名兼容，但模型请求出站不带（官方 CLI 模型请求不带该头，实测）。
+  const wireBody = shapeZcodeWireRequest(anthropicBody, { provider });
+  const headers = { "content-type": "application/json", ...buildZcodeModelHeaders({ token, version }) };
+  void deviceMid;
+
+  let res;
+  try {
+    res = await fetchImpl(ZCODE_MESSAGES_URL, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(wireBody),
+      signal: timeoutSignal(timeoutMs),
+    });
+  } catch (e) {
+    return zcodeErrorResponse({ kind: "network", message: String(e?.message || e).slice(0, 160) });
+  }
+
+  if (!res.ok) {
+    const payload = await res.json().catch(() => null);
+    return zcodeErrorResponse({ ...classifyZcodeFailure(res.status, payload), model: modelId });
+  }
+
+  // 上游业务错误惯例：HTTP 200 + JSON body（code 非 0/200）→ 同样按错误分类
+  if (!String(res.headers.get("content-type") || "").includes("text/event-stream")) {
+    const payload = await res.json().catch(() => null);
+    const code = Number(payload?.code);
+    const bizOk = payload?.success !== false && (!Number.isFinite(code) || code === 0 || code === 200);
+    if (payload && !bizOk) {
+      return zcodeErrorResponse({ ...classifyZcodeFailure(res.status, payload), model: modelId });
+    }
+    if (payload && body?.stream === false) {
+      return new Response(JSON.stringify(payload), { status: 200, headers: { "Content-Type": "application/json" } });
+    }
+  }
+
+  if (body?.stream !== false) {
+    const stream = anthropicToOpenAiStream(res.body, { model: modelId });
+    return new Response(stream, {
+      status: 200,
+      headers: { "Content-Type": "text/event-stream; charset=utf-8", "Cache-Control": "no-cache" },
+    });
+  }
+
+  const text = await res.text();
+  const out = await aggregateAnthropicToOpenAi(text, { model: modelId });
+  if (out.error) {
+    return zcodeErrorResponse({ kind: out.error.kind || "server", code: out.error.code || 0, status: 200, message: out.error.message });
+  }
+  return new Response(JSON.stringify(out.openAi), { status: 200, headers: { "Content-Type": "application/json" } });
+}

package/src/providers/zcode/const.js

@@ -1,54 +1,54 @@
-// zcode 供应商常量单一源：网关地址、客户端版本、业务码表、Start/Coding Plan 模型目录。
-// 端点契约调研自 zai-org/ZCode 源码（official-coding-plan-gateway.ts / zcodeEndpoint.ts）与 zcode-switch 实测。
-export const ZCODE_ORIGIN = "https://zcode.z.ai";
-export const ZCODE_CLI_INIT_URL = `${ZCODE_ORIGIN}/api/v1/oauth/cli/init`;
-export const zcodeCliPollUrl = (flowId) =>
-  `${ZCODE_ORIGIN}/api/v1/oauth/cli/poll/${encodeURIComponent(String(flowId || ""))}`;
-export const ZCODE_MESSAGES_URL = `${ZCODE_ORIGIN}/api/v1/zcode-plan/anthropic/v1/messages`;
-export const zcodeBalanceUrl = (appVersion) =>
-  `${ZCODE_ORIGIN}/api/v1/zcode-plan/billing/balance?app_version=${encodeURIComponent(String(appVersion || ""))}`;
-
-export const ZCODE_DEFAULT_APP_VERSION = "3.14.4";
-export const ZCODE_RELEASE_CHANNEL = "stable";
-
-export function zcodeAppVersion(env = process.env) {
-  const v = typeof env?.MSLXDFF_ZCODE_APP_VERSION === "string" ? env.MSLXDFF_ZCODE_APP_VERSION.trim() : "";
-  return v || ZCODE_DEFAULT_APP_VERSION;
-}
-
-// 业务码表（zcode-switch quota.rs classify + ZCode 客户端 model-execution.ts 实测）：
-// 401/1006 鉴权失效，1005 额度耗尽（data/plan/ends_at 为下次时间），限流组，3007 安全校验拒绝。
-export const ZCODE_ERROR_KINDS = {
-  401: "auth",
-  1006: "auth",
-  1005: "quota",
-  3002: "rate_limit",
-  3008: "rate_limit",
-  3009: "rate_limit",
-  3010: "rate_limit",
-  3007: "security",
-  2007: "server",
-  3001: "param",
-  3006: "param",
-  3102: "param",
-};
-
-export function zcodeErrorKind(code) {
-  const n = Number(code);
-  return ZCODE_ERROR_KINDS[n] || "unknown";
-}
-
-// 官方 canonical id（quota.rs BUILTIN_*_MODELS）；入站大小写不敏感，出站规范化为该表内的写法。
-export const ZCODE_CODING_PLAN_MODELS = ["GLM-5.3", "GLM-5.3-Flash"];
-export const ZCODE_START_PLAN_MODELS = ["GLM-5.3-Flash", "GLM-5.2", "GLM-5-Turbo"];
-export const ZCODE_MODEL_CATALOG = [...new Set([...ZCODE_CODING_PLAN_MODELS, ...ZCODE_START_PLAN_MODELS])];
-
-export function canonicalZcodeModel(id) {
-  let raw = String(id || "").trim();
-  if (raw.startsWith("zcode/")) raw = raw.slice(6);
-  const low = raw.toLowerCase();
-  for (const m of ZCODE_MODEL_CATALOG) {
-    if (m.toLowerCase() === low) return m;
-  }
-  return raw;
-}
+// zcode 供应商常量单一源：网关地址、客户端版本、业务码表、Start/Coding Plan 模型目录。
+// 端点契约调研自 zai-org/ZCode 源码（official-coding-plan-gateway.ts / zcodeEndpoint.ts）与 zcode-switch 实测。
+export const ZCODE_ORIGIN = "https://zcode.z.ai";
+export const ZCODE_CLI_INIT_URL = `${ZCODE_ORIGIN}/api/v1/oauth/cli/init`;
+export const zcodeCliPollUrl = (flowId) =>
+  `${ZCODE_ORIGIN}/api/v1/oauth/cli/poll/${encodeURIComponent(String(flowId || ""))}`;
+export const ZCODE_MESSAGES_URL = `${ZCODE_ORIGIN}/api/v1/zcode-plan/anthropic/v1/messages`;
+export const zcodeBalanceUrl = (appVersion) =>
+  `${ZCODE_ORIGIN}/api/v1/zcode-plan/billing/balance?app_version=${encodeURIComponent(String(appVersion || ""))}`;
+
+export const ZCODE_DEFAULT_APP_VERSION = "3.14.4";
+export const ZCODE_RELEASE_CHANNEL = "stable";
+
+export function zcodeAppVersion(env = process.env) {
+  const v = typeof env?.MSLXDFF_ZCODE_APP_VERSION === "string" ? env.MSLXDFF_ZCODE_APP_VERSION.trim() : "";
+  return v || ZCODE_DEFAULT_APP_VERSION;
+}
+
+// 业务码表（zcode-switch quota.rs classify + ZCode 客户端 model-execution.ts 实测）：
+// 401/1006 鉴权失效，1005 额度耗尽（data/plan/ends_at 为下次时间），限流组，3007 安全校验拒绝。
+export const ZCODE_ERROR_KINDS = {
+  401: "auth",
+  1006: "auth",
+  1005: "quota",
+  3002: "rate_limit",
+  3008: "rate_limit",
+  3009: "rate_limit",
+  3010: "rate_limit",
+  3007: "security",
+  2007: "server",
+  3001: "param",
+  3006: "param",
+  3102: "param",
+};
+
+export function zcodeErrorKind(code) {
+  const n = Number(code);
+  return ZCODE_ERROR_KINDS[n] || "unknown";
+}
+
+// 官方 canonical id（quota.rs BUILTIN_*_MODELS）；入站大小写不敏感，出站规范化为该表内的写法。
+export const ZCODE_CODING_PLAN_MODELS = ["GLM-5.3", "GLM-5.3-Flash"];
+export const ZCODE_START_PLAN_MODELS = ["GLM-5.3-Flash", "GLM-5.2", "GLM-5-Turbo"];
+export const ZCODE_MODEL_CATALOG = [...new Set([...ZCODE_CODING_PLAN_MODELS, ...ZCODE_START_PLAN_MODELS])];
+
+export function canonicalZcodeModel(id) {
+  let raw = String(id || "").trim();
+  if (raw.startsWith("zcode/")) raw = raw.slice(6);
+  const low = raw.toLowerCase();
+  for (const m of ZCODE_MODEL_CATALOG) {
+    if (m.toLowerCase() === low) return m;
+  }
+  return raw;
+}