dsh-gateway-provider 1.0.2 → 1.0.3

package/README.md

@@ -51,7 +51,7 @@ re-deploy.
 
    ```bash
    dsh plugin --profile web add dsh-gateway-provider          # latest
-   dsh plugin --profile web add dsh-gateway-provider@1.0.2    # pinned
+   dsh plugin --profile web add dsh-gateway-provider@<version>  # pinned
    ```
 
    `dsh plugin add` forwards to `pnpm add` in the profile directory.
@@ -125,6 +125,21 @@ The **Gateway Models** page exposes the same operations with a UI: search,
 hidden/custom filters with counts, a per-model override editor (placeholders
 show discovered values), connection test, and save/cancel semantics.
 
+> ⚠️ **Hand-editing YAML?** `settings.yaml` is parsed with YAML 1.2 core
+> semantics: an unquoted `true` / `false` (any casing) becomes a boolean and
+> an unquoted digit run becomes a number. Every plain string field of the
+> section (`id`, `name`, `label`, `baseURL`, `apiKeyEnv`, `modelsUrl`,
+> `userId`, `reasoningLevels` / `excludePatterns` / `endpointPriority`
+> entries, …) tolerates the coerced form, but the cleanest habit is quoting
+> intent-significant tokens — write `reasoningLevels: ["off", "low",
+> "high"]`, not `reasoningLevels: [off, low, high]` — and never `false`
+> where a level name is meant (it survives as the junk level `"false"` and
+> is silently dropped from the picker). A structurally invalid section
+> (objects where strings belong, etc.) is refused at registration: the
+> namespace stays unregistered and every settings write from the web UI
+> then answers `settings-rejected: settings namespace "llm-newapi" is not
+> registered`.
+
 ## Configuration reference
 
 Section `llm-newapi:` of `$DSH_HOME/settings.yaml`. The flat fields
@@ -151,6 +166,7 @@ the `gateways` array support most of the same fields per gateway
 | `excludePatterns` | image/speech/embed/… | Regex patterns excluding models from the picker |
 | `endpointPriority` | `["openai-response","anthropic","openai","gemini"]` | Wire-format preference order (first match wins per model) |
 | `userId` | `1` | `New-Api-User` header for the management API |
+| `headers` | – | Extra HTTP headers (name → value) sent with every provider request; attribution headers (`user-agent`) are filtered out |
 | `maxTokens` | `32768` | Output cap fallback when models.dev lacks data |
 | `defaultContextWindow` | `128000` | Context window fallback when models.dev lacks data |
 | `streamIdleTimeoutMs` | `300000` | Stream idle watchdog |

package/docs/README.zh.md

@@ -45,7 +45,7 @@ provider。如果你的模型都在网关后面，就得手工维护一份静态
 
    ```bash
    dsh plugin --profile web add dsh-gateway-provider          # 最新版
-   dsh plugin --profile web add dsh-gateway-provider@1.0.2    # 钉住版本
+   dsh plugin --profile web add dsh-gateway-provider@<version>  # 钉住版本
    ```
 
    `dsh plugin add` 会在 profile 目录里转发执行 `pnpm add`。bundle 补丁
@@ -113,6 +113,18 @@ llm-newapi:
 **网关模型**设置页提供同样的操作：搜索、带计数的已隐藏/自定义筛选、逐模型覆写
 编辑器（placeholder 显示发现值）、连接测试、保存/取消语义。
 
+> ⚠️ **手工编辑 YAML？** `settings.yaml` 按 YAML 1.2 core 语义解析：不带引号的
+> `true` / `false`（任意大小写）会变成布尔值，不带引号的数字串会变成数值。本节
+> 所有纯字符串字段（`id`、`name`、`label`、`baseURL`、`apiKeyEnv`、`modelsUrl`、
+> `userId`，以及 `reasoningLevels` / `excludePatterns` / `endpointPriority` 的
+> 条目……）都可容忍这些被强转的形式，但最稳妥的习惯是给有含义的 token 加引号
+> ——写 `reasoningLevels: ["off", "low", "high"]`，而不是
+> `reasoningLevels: [off, low, high]`——更不要在该写级别名的地方写 `false`（它会
+> 以垃圾级别 `"false"` 存活，并被静默排除出选择器）。结构上非法的分节（比如字符
+> 串位置出现对象）会在注册时被拒绝：namespace 保持未注册状态，Web 设置页的每次
+> 写入都会得到
+> `settings-rejected: settings namespace "llm-newapi" is not registered`。
+
 ## 配置参考
 
 `$DSH_HOME/settings.yaml` 的 `llm-newapi:` 节。扁平字段（`baseURL` /
@@ -139,6 +151,7 @@ llm-newapi:
 | `excludePatterns` | image/speech/embed/… | 选择器剔除的正则列表 |
 | `endpointPriority` | `["openai-response","anthropic","openai","gemini"]` | wire 格式优先级（每模型取首个匹配） |
 | `userId` | `1` | 管理 API 的 `New-Api-User` 头 |
+| `headers` | – | 随每个 provider 请求附带的额外 HTTP 头（名称 → 值）；归属头（`user-agent`）会被过滤掉 |
 | `maxTokens` | `32768` | 无 models.dev 数据时的输出上限兜底 |
 | `defaultContextWindow` | `128000` | 无 models.dev 数据时的上下文兜底 |
 | `streamIdleTimeoutMs` | `300000` | 流空闲看门狗 |

package/index.js

@@ -60,12 +60,30 @@ export const DEFAULT_MODELS_URL = "https://models.dev/models.json";
 const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 600_000;
 const DEFAULT_CATALOG_TTL_MS = 30 * 60 * 1000;
 
+/**
+ * String field tolerant of hand-edited YAML scalars. `settings.yaml` is a
+ * user-editable document parsed with YAML 1.2 core semantics: an unquoted
+ * `true` / `false` / `True` / `FALSE` round-trips as a boolean and an
+ * unquoted digit run as a number, long before the value reaches a strict
+ * `z.string()` — and because the settings seam refuses to register a
+ * namespace whose stored section fails its schema, one such scalar anywhere
+ * in the section bricks the whole namespace (the web UI then reports every
+ * write as `settings-rejected: settings namespace "llm-newapi" is not
+ * registered`). Booleans and finite numbers coerce to their string form;
+ * anything else still fails loud with schemastery's own union diagnostic.
+ */
+const coercedString = () => z.union([
+  z.string(),
+  z.transform(z.boolean(), (value) => String(value)),
+  z.transform(z.number(), (value) => String(value)),
+]);
+
 /** Schema for one model-level override on a gateway (all fields optional). */
 const ModelOverrideSchema = z.object({
   /** Model id exactly as the gateway accepts it. */
-  id: z.string(),
+  id: coercedString().required(),
   /** Display name override. */
-  name: z.string(),
+  name: coercedString(),
   /** Hide this model from the picker. */
   disabled: z.boolean(),
   /** Force the wire protocol for this model (openai/anthropic/gemini/…). */
@@ -75,7 +93,7 @@ const ModelOverrideSchema = z.object({
   /** Override the output-token cap. */
   maxTokens: z.number().step(1).min(1),
   /** Reasoning level set (e.g. ["off","low","medium","high"]). */
-  reasoningLevels: z.array(z.string()),
+  reasoningLevels: z.array(coercedString()),
 });
 
 /** Gateway-type templates the settings UI offers (informational labels). */
@@ -88,49 +106,49 @@ const FLAVORS = ["newapi", "litellm", "higress", "openai-compatible", "custom"];
  */
 const GatewaySchema = z.object({
   /** Short stable id; becomes the provider route suffix (`gateway:<id>`). */
-  id: z.string().required(),
+  id: coercedString().required(),
   /** Human-readable gateway name. */
-  label: z.string(),
+  label: coercedString(),
   /** Gateway base URL (unused when protocol URL fields are set). */
-  baseURL: z.string(),
+  baseURL: coercedString(),
   /** Full chat-completions endpoint URL (custom template). */
-  openaiURL: z.string(),
+  openaiURL: coercedString(),
   /** Full Responses endpoint URL (custom template). */
-  responsesURL: z.string(),
+  responsesURL: coercedString(),
   /** Full Anthropic messages endpoint URL (custom template). */
-  anthropicURL: z.string(),
+  anthropicURL: coercedString(),
   /** Environment-variable name (credential ref) holding the API key. */
-  apiKeyEnv: z.string().role("credential-ref"),
+  apiKeyEnv: coercedString().role("credential-ref"),
   /** Gateway type label (newapi/litellm/higress/openai-compatible/custom). */
   flavor: z.union(FLAVORS),
   /** Model-list source: `auto` (prefer /v1/models), `v1`, or `management`. */
   catalogMode: z.union(["auto", "v1", "management"]),
   /** User id sent to the management API when it is used. */
-  userId: z.string(),
+  userId: coercedString(),
   /** Per-model overrides and custom models. */
   models: z.array(ModelOverrideSchema),
   /** Wire-format preference order for this gateway. */
-  endpointPriority: z.array(z.string()),
+  endpointPriority: z.array(coercedString()),
 });
 
 export const Config = z.object({
   // ---- Legacy single-connection fields (build the default `newapi` route) ----
   /** Display name of the default gateway route (defaults to "NewAPI"). */
-  label: z.string(),
+  label: coercedString(),
   /** Environment-variable name (credential ref) holding the default gateway API key. */
-  apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+  apiKeyEnv: coercedString().role("credential-ref").default(DEFAULT_API_KEY_ENV),
   /** Default gateway base URL; resolved from NEWAPI_BASE_URL / NEWAPI_API_URL then the public cloud default. */
-  baseURL: z.string(),
+  baseURL: coercedString(),
   /** Full chat-completions endpoint URL (custom template for the default gateway). */
-  openaiURL: z.string(),
+  openaiURL: coercedString(),
   /** Full Responses endpoint URL (custom template for the default gateway). */
-  responsesURL: z.string(),
+  responsesURL: coercedString(),
   /** Full Anthropic messages endpoint URL (custom template for the default gateway). */
-  anthropicURL: z.string(),
+  anthropicURL: coercedString(),
   /** Gateway type label shown in the UI (newapi/litellm/higress/openai-compatible/custom). */
   flavor: z.union(FLAVORS).default("newapi"),
   /** models.dev catalog URL (any fetch-able URL; file: works for offline mirrors). */
-  modelsUrl: z.string().default(DEFAULT_MODELS_URL),
+  modelsUrl: coercedString().default(DEFAULT_MODELS_URL),
   /** Enrich gateway models with models.dev parameters. */
   useModelsDev: z.boolean().default(true),
   /** Widen the unknown-model reasoning fallback to the full off~max set. */
@@ -144,11 +162,17 @@ export const Config = z.object({
   /** Exclude non-chat model families from the picker. */
   includeChatOnly: z.boolean().default(true),
   /** Regex patterns excluding models from the picker. */
-  excludePatterns: z.array(z.string()).default(DEFAULT_EXCLUDE_PATTERNS),
+  excludePatterns: z.array(coercedString()).default(DEFAULT_EXCLUDE_PATTERNS),
   /** Wire-format preference order, intersected with each model's supported types. */
-  endpointPriority: z.array(z.string()).default(DEFAULT_ENDPOINT_PRIORITY),
+  endpointPriority: z.array(coercedString()).default(DEFAULT_ENDPOINT_PRIORITY),
   /** User id sent to the management API when it is used. */
-  userId: z.string().default("1"),
+  userId: coercedString().default("1"),
+  /**
+   * Extra HTTP headers sent with every provider request to the default
+   * gateway (name → value). Reserved attribution headers (user-agent) are
+   * filtered out at request time; per-request values are unaffected.
+   */
+  headers: z.dict(coercedString()),
   /** Fallback output-token cap for models without models.dev data. */
   maxTokens: z.number().step(1).min(1).default(DEFAULT_MAX_TOKENS),
   /** Fallback context window for models without models.dev data. */

package/lib/pi-bridge.js

@@ -344,10 +344,25 @@ export function toPiContext(options, attachments) {
 // Stream translation (pi-ai EventStream → harness StreamChunks)
 // ---------------------------------------------------------------------------
 
-/** Classify a pi-ai error message into a harness error code. */
+/**
+ * Classify a pi-ai error message into a harness error code.
+ * Lifted from dsh-llm-pi-ai/stream (rc.7): the coarse codes matter because
+ * the harness retry stack (dsh-llm-retry) retries exactly RATE_LIMIT /
+ * SERVER / TIMEOUT / TRANSPORT / EMPTY_RESPONSE — a generic fallback code
+ * would make gateway blips unretryable.
+ */
 function classifyPiAiError(text) {
+  if (/\b(?:401|403)\b/.test(text)) return "AUTH";
   if (isQuotaExceededError(text)) return QUOTA_EXCEEDED_CODE;
-  return "PROVIDER_ERROR";
+  if (/\b429\b|rate.?limit/i.test(text)) return "RATE_LIMIT";
+  if (/\b400\b|invalid.?request/i.test(text)) return "INVALID_REQUEST";
+  if (/\b5\d\d\b/.test(text)) return "SERVER";
+  if (/\btime(?:d)?\s*out\b|timeout/i.test(text)) return "TIMEOUT";
+  if (/stream ended (?:before|without)\b/i.test(text)) return "TRANSPORT";
+  if (/\b(?:network|connection|socket|fetch)\b|\bECONN[A-Z]+\b/i.test(text)
+    || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(text)
+    || /\bterminated\b|premature close/i.test(text)) return "TRANSPORT";
+  return "PI_AI_ERROR";
 }
 
 /** Map pi-ai usage (reasoning folded into output by pi-ai). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-gateway-provider",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Generic LLM gateway model provider plugin for DeepSeek Harness: mounts newapi / LiteLLM / Higress / any OpenAI-compatible gateway as provider routes, auto-discovers the model list, enriches every model with models.dev parameters, and dispatches each model over its native wire protocol (OpenAI / Anthropic / Gemini) via the pi-ai SDK",
   "repository": {
     "type": "git",
@@ -27,7 +27,9 @@
     "link": "bash scripts/link.sh",
     "smoke": "node test/smoke.mjs",
     "test:client": "node test/client-render.mjs",
-    "test:urls": "node test/protocol-urls.mjs"
+    "test:urls": "node test/protocol-urls.mjs",
+    "test:schema": "node test/schema-coercion.mjs",
+    "test:errors": "node test/error-codes.mjs"
   },
   "keywords": [
     "deepseek-harness",
@@ -61,12 +63,11 @@
   "dependencies": {},
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-anonymous-user-id": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-launch-environment": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.7",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@earendil-works/pi-ai": "^0.82.1"
   }