agentsw 0.10.0 → 0.10.2

package/README.md

@@ -17,20 +17,7 @@ without touching the settings you hand-tuned.
 
 </div>
 
-```console
-$ asw use myproxy -m glm-5.3-flash
-switching to myproxy (openai) · default model glm-5.3-flash
-
-skip claude    Claude Code does not support openai-protocol providers
-ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
-               backup: ~/.config/agentsw/backups/transaction-<unique>
-ok   omp       ~/.omp/agent/models.yml
-               select in omp with: omp --model myproxy/glm-5.3-flash
-skip pi        pi not detected (pass --apps pi to force)
-ok   opencode  ~/.config/opencode/opencode.json
-ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
-               select in dsh with the model picker, or run: dsh web
-```
+![asw use myproxy writes one provider into nine coding agents](https://raw.githubusercontent.com/tchivs/agentsw/main/docs/demo.gif)
 
 `agentsw` and the short `asw` are the same binary.
 
@@ -54,9 +41,37 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 - **Wire-aware.** `/v1/chat/completions` and `/v1/responses` are different endpoints;
   agentsw tracks which one a provider speaks and never downgrades a working one.
 
-Want a GUI, MCP/Skills sync, a usage dashboard or a local failover proxy? Use
-[cc-switch](https://github.com/farion1231/cc-switch) — it is excellent at that, and agentsw
-imports from it rather than competing with it.
+## How it compares
+
+Two projects do most of this better than agentsw does, and both are worth your time:
+
+- **[cc-switch](https://github.com/farion1231/cc-switch)** — a desktop app (Tauri) for ten tools:
+  one-click switching, 90+ provider presets, MCP/Skills/Prompts management, local routing and
+  failover with API-format conversion, a usage and cost dashboard, a session manager, and
+  WebDAV/S3 sync.
+- **[cc-switch-cli](https://github.com/SaladDay/cc-switch-cli)** — the community CLI fork of the
+  same idea: TUI plus scriptable subcommands, seven tools, MCP and skills, a daemon proxy with
+  token accounting, SQLite-backed state.
+
+Between them they cover Claude Code, Claude Desktop, Codex, Gemini CLI, OpenCode, Hermes,
+OpenClaw, Pi, Grok Build and MiniMax Code. agentsw covers a different nine — Claude Code, Codex,
+omp, pi, prime-agent, opencode, Hermes, WorkBuddy and DeepSeek Harness — **four of which neither
+other tool writes at all.**
+
+| | agentsw | cc-switch | cc-switch-cli |
+|---|---|---|---|
+| Interface | CLI, `--json` for scripts | desktop GUI | TUI + CLI |
+| Model metadata (models.dev + AI Gateway) written into each app's own fields | **yes** | no | no |
+| MCP / Skills / Prompts management | — | yes | yes |
+| Routing, API-format conversion, failover | — | yes | yes |
+| Usage and cost dashboard | — | yes | yes |
+| Presets, sessions, cloud sync, deep links | — | yes | partial |
+| Reads the other tool's provider store | yes — read-only `import` | — | — |
+
+The honest summary: **if you want a GUI, MCP management, or a failover proxy, use cc-switch.** If
+you use omp, prime-agent, WorkBuddy or DeepSeek Harness, or you want each agent to receive real
+model metadata instead of a bare id, that is what agentsw is for. It reads cc-switch's store
+rather than competing with it.
 
 ## Install
 
@@ -104,6 +119,32 @@ opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.co
 dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
+And the point of the whole thing — one command writes every detected agent (this is the run in
+the animation at the top of this page, as text):
+
+```console
+$ asw use myproxy
+switching to myproxy (openai) · default model glm-5.3-flash
+
+skip claude    Claude Code does not support openai-protocol providers
+ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
+ok   omp       ~/.omp/agent/models.yml
+               select in omp with: omp --model myproxy/glm-5.3-flash
+ok   pi        ~/.pi/agent/models.json, ~/.pi/agent/settings.json
+ok   prime     ~/.prime/agent/models.json, ~/.prime/agent/settings.json
+ok   opencode  ~/.config/opencode/opencode.json
+ok   hermes    ~/.hermes/config.yaml, ~/.hermes/.env
+ok   workbuddy ~/.workbuddy/models.json, ~/.workbuddy/settings.json
+               WorkBuddy watches models.json; models appear in the selector's custom section without restart
+ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
+               select in dsh with the model picker, or run: dsh web
+```
+
+`claude` is the only skip: Claude Code speaks the Anthropic protocol, and `myproxy` is an
+OpenAI-protocol provider. On a machine where an agent's config already exists, committing to it
+also prints a `backup: ~/.config/agentsw/backups/transaction-<unique>` line; this sandbox starts
+with empty configs, so there is nothing to back up and none appear.
+
 ## Supported apps
 
 | App | Config written | Protocols |
@@ -115,7 +156,7 @@ dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.d
 | [prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) | `~/.prime/agent/models.json` + `settings.json` | both |
 | [opencode](https://opencode.ai) | `~/.config/opencode/opencode.json`, `.jsonc` or `config.json` (the one that exists; comments preserved) | both |
 | [Hermes](https://pypi.org/project/hermes-agent/) | `~/.hermes/config.yaml` + `.env` (comments preserved) | both |
-| WorkBuddy | `~/.workbuddy/models.json` + `settings.json` | openai |
+| WorkBuddy | `~/.workbuddy/models.json` + `settings.json` (`%APPDATA%\workbuddy` on Windows) | openai |
 | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) | `~/.dsh/settings.yaml` + `.credentials.yaml` | both |
 
 An agent that is not installed is skipped, not guessed at. `--apps codex,omp` narrows a run;
@@ -242,7 +283,9 @@ Import still skips already configured accounts.
   `refresh --provider <id> --metadata-mode on` to request fresh reference prices.
 - **Auditable and optional:** `metadata.fields` records origins, value snapshots and timestamps;
   `metadata.conflicts` records disagreements with retained values. This audit stays in agentsw, never runtime agent configs.
-  Gateway has a separate 24-hour cache; failures use stale cached data or skip supplementation.
+  Gateway has a separate 24-hour cache; a failed request is retried once before falling back to stale cached data
+  (or skipping supplementation when there is none). `AGENTSW_DEBUG=1` reports why an attempt failed, and
+  `AGENTSW_GATEWAY_TIMEOUT_MS` overrides the 15-second whole-request budget.
 - **Automatic lookup is not automatic sync:** enrichment updates saved metadata during add/quick/discover/import/refresh.
   It does not add an automatic push to agents. Sync behavior is unchanged: ordinary `sync` only writes saved settings
   and fetches neither model lists nor metadata catalogs.
@@ -352,7 +395,10 @@ are unaffected.
 - A sync overwrites only the fields agentsw owns. Unmodeled provider-level keys and per-model
   extras survive; an owned field that stops applying is cleared rather than left stale, and a
   per-model `api`/`baseUrl` override that contradicts the route is dropped (it would silently
-  win over the entry) and reported.
+  win over the entry) and reported. Clearing needs the entry to say something in the first
+  place: a model the store knows nothing about — an id no catalog row matched — is written as
+  an id and its capabilities alone, and the limits already in the file are kept rather than
+  deleted.
 - YAML configs (omp, Hermes, dsh) keep their comments. `~/.codex/config.toml` does not —
   TOML round-trip drops them, which is why the backup happens first.
 - OpenAI endpoints come in two wires: `/v1/chat/completions` and `/v1/responses`. Imported

package/README.zh-CN.md

@@ -17,20 +17,7 @@
 
 </div>
 
-```console
-$ asw use myproxy -m glm-5.3-flash
-switching to myproxy (openai) · default model glm-5.3-flash
-
-skip claude    Claude Code does not support openai-protocol providers
-ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
-               backup: ~/.config/agentsw/backups/transaction-<unique>
-ok   omp       ~/.omp/agent/models.yml
-               select in omp with: omp --model myproxy/glm-5.3-flash
-skip pi        pi not detected (pass --apps pi to force)
-ok   opencode  ~/.config/opencode/opencode.json
-ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
-               select in dsh with the model picker, or run: dsh web
-```
+![asw use myproxy 把一个供应商写进九个编码智能体](https://raw.githubusercontent.com/tchivs/agentsw/main/docs/demo.gif)
 
 `agentsw` 和短名 `asw` 是同一个可执行文件。
 
@@ -53,9 +40,33 @@ ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
 - **区分接口形态。** `/v1/chat/completions` 与 `/v1/responses` 是两个不同端点；
   agentsw 记录供应商说的是哪一种，并且绝不把可用的 responses 降级。
 
-想要 GUI、MCP/Skills 同步、用量仪表盘或本地故障转移代理？用
-[cc-switch](https://github.com/farion1231/cc-switch)——那些它做得很好；agentsw 从它导入，
-而不是跟它抢。
+## 它和同类工具的关系
+
+有两件事别人做得比 agentsw 好，而且都值得你去看：
+
+- **[cc-switch](https://github.com/farion1231/cc-switch)**——桌面应用（Tauri），支持十个工具：一键切换、
+  90+ 供应商预设、MCP/Skills/Prompts 管理、本地路由与故障转移（含 API 格式转换）、用量与成本仪表盘、
+  会话管理、WebDAV/S3 同步。
+- **[cc-switch-cli](https://github.com/SaladDay/cc-switch-cli)**——同一思路的社区 CLI 分支：TUI + 可脚本化子命令、
+  七个工具、MCP 与 Skills、带 token 统计的守护进程代理、SQLite 存储。
+
+两者合起来覆盖 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、Hermes、OpenClaw、Pi、
+Grok Build、MiniMax Code。agentsw 覆盖的是另外九个——Claude Code、Codex、omp、pi、prime-agent、
+opencode、Hermes、WorkBuddy、DeepSeek Harness——**其中四个另外两个工具根本不写。**
+
+| | agentsw | cc-switch | cc-switch-cli |
+|---|---|---|---|
+| 形态 | CLI，`--json` 可脚本化 | 桌面 GUI | TUI + CLI |
+| 从 models.dev + AI Gateway 取元数据，写入各应用自己的字段 | **是** | 无 | 无 |
+| MCP / Skills / Prompts 管理 | — | 有 | 有 |
+| 路由、API 格式转换、故障转移 | — | 有 | 有 |
+| 用量与成本仪表盘 | — | 有 | 有 |
+| 预设、会话、云同步、deep link | — | 有 | 部分 |
+| 读取对方的供应商库 | 有——只读 `import` | — | — |
+
+说实话的结论：**想要 GUI、MCP 管理或故障转移代理，用 cc-switch。** 如果你在用 omp、prime-agent、
+WorkBuddy 或 DeepSeek Harness，或者你希望每个智能体拿到的是真实模型参数而不是一个裸 id，
+那才是 agentsw 的用处。它读 cc-switch 的库，而不是跟它抢。
 
 ## 安装
 
@@ -99,6 +110,31 @@ opencode  yes    openai+anthropic  myproxy/glm-5.3-flash                   ~/.co
 dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.dsh/settings.yaml
 ```
 
+而这个工具真正的用处是另一条——一条命令写进所有检测到的智能体
+（也就是本页顶部那段动画里跑的东西，文字版）：
+
+```console
+$ asw use myproxy
+switching to myproxy (openai) · default model glm-5.3-flash
+
+skip claude    Claude Code does not support openai-protocol providers
+ok   codex     ~/.codex/config.toml, ~/.codex/auth.json
+ok   omp       ~/.omp/agent/models.yml
+               select in omp with: omp --model myproxy/glm-5.3-flash
+ok   pi        ~/.pi/agent/models.json, ~/.pi/agent/settings.json
+ok   prime     ~/.prime/agent/models.json, ~/.prime/agent/settings.json
+ok   opencode  ~/.config/opencode/opencode.json
+ok   hermes    ~/.hermes/config.yaml, ~/.hermes/.env
+ok   workbuddy ~/.workbuddy/models.json, ~/.workbuddy/settings.json
+               WorkBuddy watches models.json; models appear in the selector's custom section without restart
+ok   dsh       ~/.dsh/settings.yaml, ~/.dsh/.credentials.yaml
+               select in dsh with the model picker, or run: dsh web
+```
+
+唯一被跳过的是 `claude`：Claude Code 说的是 Anthropic 协议，而 `myproxy` 是 OpenAI 协议的供应商。
+在智能体的配置已经存在的机器上，提交它时还会打印一行 `backup: ~/.config/agentsw/backups/transaction-<unique>`；
+本沙箱从空配置开始，无物可备，因此没有这行。
+
 ## 支持的应用
 
 | 应用 | 写入的配置 | 协议 |
@@ -110,7 +146,7 @@ dsh       yes    openai+anthropic  myproxy · glm-5.3-flash                 ~/.d
 | [prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) | `~/.prime/agent/models.json` + `settings.json` | 双协议 |
 | [opencode](https://opencode.ai) | `~/.config/opencode/` 下已存在的 `opencode.json`、`.jsonc` 或 `config.json`（保留注释） | 双协议 |
 | [Hermes](https://pypi.org/project/hermes-agent/) | `~/.hermes/config.yaml` + `.env`（保留注释） | 双协议 |
-| WorkBuddy | `~/.workbuddy/models.json` + `settings.json` | openai |
+| WorkBuddy | `~/.workbuddy/models.json` + `settings.json`(Windows 下为 `%APPDATA%\workbuddy`) | openai |
 | [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) | `~/.dsh/settings.yaml` + `.credentials.yaml` | 双协议 |
 
 未安装的应用会被跳过，而不是瞎猜。`--apps codex,omp` 只跑指定应用；
@@ -227,7 +263,9 @@ asw sync --provider myproxy
   自动模式不会仅为刷新参考价格而查询：可查看 `metadata.gateway.fetchedAt` 判断快照时间，
   需要重新查询参考价格时使用 `refresh --provider <id> --metadata-mode on`。
 - **可追溯、可降级：** `metadata.fields` 记录来源、原值快照和时间，`metadata.conflicts` 记录保留值与冲突。
-  审计信息仅保存在 agentsw，不写入智能体运行配置。Gateway 目录独立缓存 24 小时；请求失败可使用旧缓存，无缓存时只跳过补充。
+  审计信息仅保存在 agentsw，不写入智能体运行配置。Gateway 目录独立缓存 24 小时；请求失败会先重试一次，
+  仍失败才使用旧缓存，无缓存时只跳过补充。`AGENTSW_DEBUG=1` 会说明该次尝试失败的原因，
+  `AGENTSW_GATEWAY_TIMEOUT_MS` 可覆盖默认 15 秒的整体请求预算。
 - **自动查询不等于自动同步：** 添加、快速添加、发现、导入、刷新时补全保存的元数据，并不新增自动推送。
   同步行为不变：普通 `sync` 仅写入已保存的设置，既不获取模型列表，也不请求元数据目录。
 
@@ -330,6 +368,8 @@ JSON 载荷一律不含凭据；`--json --dry-run` 只报告将要改动的文
 - 同步只覆盖 agentsw 自己管理的字段：未建模的供应商级键与模型级扩展字段保留；
   自己管理但本次不再写出的字段会被清除而非留成陈旧值；与新路由矛盾的模型级
   `api`/`baseUrl` 覆盖会被删除（否则它会静默盖过供应商条目）并在输出中点名。
+  但"清除"要求这一条本身说了点什么：store 完全不认识的模型（没有任何目录行匹配到的 id）
+  只带 id 和能力写入，文件里已有的上下文长度等参数会保留而不是被删掉。
 - YAML 配置（omp、Hermes、dsh）保留注释；`~/.codex/config.toml` 不行——TOML 往返会丢注释，
   所以才先备份。
 - OpenAI 端点有两种接口形态：`/v1/chat/completions` 与 `/v1/responses`。导入时沿用配置里

package/dist/commands.js

@@ -483,7 +483,10 @@ function reportResults(results) {
             out(`${pc.yellow(t("common.skip"))} ${r.app.padEnd(9)} ${pc.dim(r.skipped)}`);
             continue;
         }
-        out(`${pc.green("ok  ")} ${r.app.padEnd(9)} ${r.changed.join(", ")}`);
+        // An empty change list means the app was already in sync: say so rather than
+        // printing a bare "ok" with nothing after it.
+        const detail = r.changed.length ? r.changed.join(", ") : pc.dim(t("preview.unchanged"));
+        out(`${pc.green("ok  ")} ${r.app.padEnd(9)} ${detail}`);
         for (const note of r.notes)
             out(`     ${" ".repeat(9)} ${pc.dim(note)}`);
     }

package/dist/config-transaction.js

@@ -144,26 +144,31 @@ export function commitFileChanges(changes, opts = {}) {
     return withWriteLock(() => {
         // Another writer may have committed between planning and acquiring the lock.
         validateReads();
+        // Only a file that already existed has anything to save. When every planned
+        // file is new, no transaction directory is created: an empty one (nothing but
+        // its manifest) would read as a backup that does not exist.
         let backupDir;
         let currentFile = backupsDir;
         try {
-            fs.mkdirSync(backupsDir, { recursive: true, mode: 0o700 });
-            backupDir = fs.mkdtempSync(path.join(backupsDir, "transaction-"));
-            fs.chmodSync(backupDir, 0o700);
-            for (const [index, change] of plan.entries()) {
-                currentFile = change.file;
-                if (change.before === undefined)
-                    continue;
-                const backup = path.join(backupDir, `${index}-${path.basename(change.file)}`);
-                fs.writeFileSync(backup, change.before, { flag: "wx", mode: 0o600 });
-                fs.chmodSync(backup, 0o600);
+            if (plan.some((change) => change.before !== undefined)) {
+                fs.mkdirSync(backupsDir, { recursive: true, mode: 0o700 });
+                backupDir = fs.mkdtempSync(path.join(backupsDir, "transaction-"));
+                fs.chmodSync(backupDir, 0o700);
+                for (const [index, change] of plan.entries()) {
+                    currentFile = change.file;
+                    if (change.before === undefined)
+                        continue;
+                    const backup = path.join(backupDir, `${index}-${path.basename(change.file)}`);
+                    fs.writeFileSync(backup, change.before, { flag: "wx", mode: 0o600 });
+                    fs.chmodSync(backup, 0o600);
+                }
+                fs.writeFileSync(path.join(backupDir, "manifest.json"), JSON.stringify(plan.map((change, index) => ({
+                    file: change.file,
+                    backup: change.before === undefined ? null : `${index}-${path.basename(change.file)}`,
+                    mode: change.original.mode,
+                })), null, 2) + "\n", { flag: "wx", mode: 0o600 });
+                fs.chmodSync(path.join(backupDir, "manifest.json"), 0o600);
             }
-            fs.writeFileSync(path.join(backupDir, "manifest.json"), JSON.stringify(plan.map((change, index) => ({
-                file: change.file,
-                backup: change.before === undefined ? null : `${index}-${path.basename(change.file)}`,
-                mode: change.original.mode,
-            })), null, 2) + "\n", { flag: "wx", mode: 0o600 });
-            fs.chmodSync(path.join(backupDir, "manifest.json"), 0o600);
             validateReads();
         }
         catch {
@@ -216,7 +221,7 @@ export function commitFileChanges(changes, opts = {}) {
                 }
                 catch { /* Only remove empty directories created by this transaction. */ }
             }
-            throw new Error(`${currentFile}: configuration transaction failed; ${failed.length ? `rollback incomplete for ${failed.join(", ")}` : "previous writes rolled back"}; backups: ${backupDir}`);
+            throw new Error(`${currentFile}: configuration transaction failed; ${failed.length ? `rollback incomplete for ${failed.join(", ")}` : "previous writes rolled back"}${backupDir ? `; backups: ${backupDir}` : "; no files needed backing up"}`);
         }
         return { files, backupDir };
     });

package/dist/gateway.js

@@ -7,6 +7,13 @@ const API_URL = "https://ai-gateway.vercel.sh/v1/models";
 const CACHE_FILE = path.join(configDir, "ai-gateway.json");
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_BODY_BYTES = 5 * 1024 * 1024;
+/** Whole-request budget. A cold handshake through a tunnel measures ~3s here, so this is generous. */
+const DEFAULT_TIMEOUT_MS = 15_000;
+const MAX_ATTEMPTS = 2;
+const RETRY_DELAY_MS = 300;
+/** The endpoint answered — a status, an oversize body, a missing one. A retry repeats the answer. */
+class DefinitiveFailure extends Error {
+}
 const REASONING_EFFORTS = {
     none: true, minimal: true, low: true, medium: true, high: true, xhigh: true, max: true,
 };
@@ -137,10 +144,10 @@ async function readResponseBody(response) {
     const contentLength = response.headers.get("content-length");
     if (contentLength !== null && Number(contentLength) > MAX_BODY_BYTES) {
         await response.body?.cancel().catch(() => { });
-        throw new Error("AI Gateway catalog exceeds size limit");
+        throw new DefinitiveFailure("AI Gateway catalog exceeds size limit");
     }
     if (!response.body)
-        throw new Error("Missing AI Gateway catalog body");
+        throw new DefinitiveFailure("Missing AI Gateway catalog body");
     const reader = response.body.getReader();
     const decoder = new TextDecoder();
     const chunks = [];
@@ -152,7 +159,7 @@ async function readResponseBody(response) {
                 break;
             size += value.byteLength;
             if (size > MAX_BODY_BYTES)
-                throw new Error("AI Gateway catalog exceeds size limit");
+                throw new DefinitiveFailure("AI Gateway catalog exceeds size limit");
             chunks.push(decoder.decode(value, { stream: true }));
         }
         chunks.push(decoder.decode());
@@ -166,6 +173,65 @@ async function readResponseBody(response) {
         reader.releaseLock();
     }
 }
+/** Diagnostics for a failure the user cannot otherwise see; opt in with AGENTSW_DEBUG=1. */
+function debug(message) {
+    if (process.env.AGENTSW_DEBUG !== "1")
+        return;
+    warn(message);
+}
+/** One-line reason for a failed attempt, for `AGENTSW_DEBUG` only — never part of the warning. */
+function describeFailure(error, timeoutMs) {
+    if (error instanceof Error && error.name === "TimeoutError")
+        return `no response within ${timeoutMs}ms`;
+    const cause = error instanceof Error ? error.cause : undefined;
+    const code = cause && typeof cause === "object" && "code" in cause ? ` (${String(cause.code)})` : "";
+    return `${error instanceof Error ? error.message : String(error)}${code}`;
+}
+/**
+ * Whole-request budget, overridable with `AGENTSW_GATEWAY_TIMEOUT_MS`. An unusable value is
+ * ignored rather than fatal: this is an escape hatch for a slow route, not configuration.
+ */
+function timeoutMs() {
+    const raw = process.env.AGENTSW_GATEWAY_TIMEOUT_MS;
+    if (raw === undefined)
+        return DEFAULT_TIMEOUT_MS;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : DEFAULT_TIMEOUT_MS;
+}
+async function requestOnce(budget) {
+    const response = await fetch(API_URL, {
+        signal: AbortSignal.timeout(budget),
+        credentials: "omit",
+        redirect: "error",
+    });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new DefinitiveFailure(`HTTP ${response.status}`);
+    }
+    return readResponseBody(response);
+}
+/**
+ * Read the catalog text, retrying once when the attempt failed before the endpoint could
+ * answer. The likeliest failure by far is a transient one: a cold TLS handshake over whatever
+ * route this machine has measures an order of magnitude slower than a warm one, so a stall or a
+ * reset is far more common than a bad answer. A `DefinitiveFailure` is not retried — the second
+ * request would only repeat it — and neither is a body that arrived but would not parse, which
+ * is why parsing stays outside this call.
+ */
+async function requestCatalogText() {
+    const budget = timeoutMs();
+    for (let attempt = 1;; attempt++) {
+        try {
+            return await requestOnce(budget);
+        }
+        catch (error) {
+            if (error instanceof DefinitiveFailure || attempt >= MAX_ATTEMPTS)
+                throw error;
+            debug(`AI Gateway attempt ${attempt} failed (${describeFailure(error, budget)}); retrying`);
+            await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+        }
+    }
+}
 /** Optional supplement: offline never fetches, and every failure leaves discovery usable. */
 export async function loadGatewayCatalog(opts = {}) {
     const cached = readCache();
@@ -174,16 +240,7 @@ export async function loadGatewayCatalog(opts = {}) {
     if (!opts.refresh && cached && Date.now() - Date.parse(cached.fetchedAt) < CACHE_TTL_MS)
         return cached;
     try {
-        const response = await fetch(API_URL, {
-            signal: AbortSignal.timeout(15_000),
-            credentials: "omit",
-            redirect: "error",
-        });
-        if (!response.ok) {
-            await response.body?.cancel().catch(() => { });
-            throw new Error("AI Gateway catalog request failed");
-        }
-        const body = JSON.parse(await readResponseBody(response));
+        const body = JSON.parse(await requestCatalogText());
         const catalog = parseGatewayCatalog(body, new Date().toISOString());
         try {
             writeFileAtomic(CACHE_FILE, JSON.stringify({ version: 1, fetchedAt: catalog.fetchedAt, body }) + "\n", 0o600);
@@ -193,7 +250,8 @@ export async function loadGatewayCatalog(opts = {}) {
         }
         return catalog;
     }
-    catch {
+    catch (error) {
+        debug(`AI Gateway metadata unavailable: ${describeFailure(error, timeoutMs())}`);
         warn(cached
             ? "could not refresh AI Gateway metadata; using cached metadata"
             : "could not load AI Gateway metadata");

package/dist/metadata.js

@@ -116,7 +116,10 @@ function indexCatalog(catalog) {
     for (const provider of Object.values(catalog)) {
         for (const [key, model] of Object.entries(provider.models)) {
             const modelId = model.id.includes("/") ? model.id : `${provider.id}/${model.id}`;
-            const entry = { provider: provider.id, modelId, identity: model.canonical_model_id ?? modelId, model };
+            const entry = {
+                provider: provider.id, modelId, identity: model.canonical_model_id ?? modelId,
+                claimed: model.canonical_model_id !== undefined, model,
+            };
             for (const id of new Set([key, model.id]))
                 push(exact, id, entry);
             push(canonical, modelId, entry);
@@ -125,10 +128,29 @@ function indexCatalog(catalog) {
     }
     return { exact, canonical, identities };
 }
+/**
+ * The identities a group of catalog rows stands for.
+ *
+ * Only `canonical_model_id` is evidence. Counting the fallback guess of a row
+ * that declares nothing would let one sloppy reseller row invent a second
+ * creator and block an otherwise unique match — the id then reports as
+ * ambiguous even though every row that does carry the field names one model.
+ * A group where *nothing* declares an identity is a different situation: there
+ * is no primary evidence to weigh, so the listings' own ids are all the group
+ * can be held to, which is exactly the conservative answer. An empty group
+ * stays empty — that is "no evidence at all", not "one guess".
+ */
+function claimIdentities(entries) {
+    const list = entries ?? [];
+    const claimed = new Set(list.filter((entry) => entry.claimed).map((entry) => entry.identity));
+    if (claimed.size)
+        return claimed;
+    return new Set(list.map((entry) => entry.identity));
+}
 /** Creator identity of a catalog model id, or undefined when its rows disagree. */
 function catalogIdentity(index, modelId) {
-    const identities = new Set(index?.canonical.get(modelId)?.map((entry) => entry.identity));
-    return identities?.size === 1 ? [...identities][0] : undefined;
+    const identities = claimIdentities(index?.canonical.get(modelId));
+    return identities.size === 1 ? [...identities][0] : undefined;
 }
 /**
  * The creator's own listing for an identity, when models.dev carries one.
@@ -164,7 +186,7 @@ function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
             const candidate = gatewayBareIds?.get(id);
             const evidence = index?.exact.get(id);
             const hintedEvidence = hint ? evidence?.filter((entry) => entry.provider === hint) : undefined;
-            const identities = new Set((hintedEvidence?.length ? hintedEvidence : evidence)?.map((entry) => entry.identity));
+            const identities = claimIdentities(hintedEvidence?.length ? hintedEvidence : evidence);
             // Gateway names the creator while models.dev names the listing provider, so
             // the two agree only once both are reduced to a creator identity. A gateway
             // id the catalog has no row for stands for itself.
@@ -181,7 +203,7 @@ function selectExact(index, id, hint, aliases, gateway, gatewayBareIds) {
         : (bare && hint ? index?.canonical.get(`${hint}/${id}`) : undefined)
             ?? index?.canonical.get(id) ?? index?.exact.get(id);
     const hinted = candidates?.find((entry) => entry.provider === hint);
-    const identities = new Set(candidates?.map((entry) => entry.identity));
+    const identities = claimIdentities(candidates);
     // Reseller rows for one model share an identity but disagree on limits and
     // prices, so only the creator's own row is authoritative.
     const primary = hinted ?? (identities.size === 1 ? creatorEntry(index, [...identities][0]) : undefined);
@@ -440,10 +462,13 @@ export function classifyUnresolved(catalog, ids, hint) {
         const candidates = hinted ?? index.canonical.get(id) ?? index.exact.get(id);
         if (!candidates?.length)
             unknown.push(id);
-        else if (new Set(candidates.map((entry) => entry.identity)).size > 1)
-            ambiguous.push(id);
-        else if (!creatorEntry(index, [...new Set(candidates.map((entry) => entry.identity))][0]))
-            noCreatorRow.push(id);
+        else {
+            const identities = claimIdentities(candidates);
+            if (identities.size > 1)
+                ambiguous.push(id);
+            else if (!creatorEntry(index, [...identities][0]))
+                noCreatorRow.push(id);
+        }
     }
     return { ambiguous, unknown, noCreatorRow };
 }

package/dist/targets/codex.js

@@ -82,7 +82,11 @@ export const codex = transactionalTarget({
             wire_api: "responses",
             requires_openai_auth: true,
         };
-        notes.push("codex requires an OpenAI Responses-compatible endpoint (/v1/responses); chat-completions-only endpoints will not work");
+        // Only worth saying when the endpoint has not declared itself Responses-compatible:
+        // a provider the user already marked `responses` needs no caveat.
+        if (provider.openaiApi !== "responses") {
+            notes.push("codex requires an OpenAI Responses-compatible endpoint (/v1/responses); chat-completions-only endpoints will not work");
+        }
         config.model_providers = providers;
         const configBackup = backupFile(configFile);
         if (configBackup)

package/dist/targets/dsh.js

@@ -10,7 +10,7 @@ import { apiValue, classifyApi, entryApi, mergeModels, sdkBaseUrl } from "./wire
 const CREDENTIALS_VERSION = 1;
 /** Thinking levels a `reasoningEfforts` entry may offer (llm-pi-ai THINKING_LEVEL_GATE). */
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-/** Per-model keys this adapter writes; one that stops being emitted is cleared, not inherited. */
+/** Per-model keys this adapter writes; one a metadata-bearing entry stops emitting is cleared, not inherited. */
 const OWNED_MODEL_KEYS = ["id", "name", "contextWindow", "maxTokens", "input", "reasoningEfforts"];
 /** models.dev efforts -> `{ level: wire spelling }`; an unoffered level is omitted, not nulled. */
 function reasoningEfforts(efforts) {

package/dist/targets/pistyle.js

@@ -6,7 +6,7 @@ import { editJsoncObject, isJsonObject, readJsoncObject } from "../jsonc.js";
 import { looksLikeEnvName } from "../slug.js";
 import { transactionalTarget } from "../target-transaction.js";
 import { apiValue, classifyApi, entryApi, mergeModels, sdkBaseUrl, stripConflictingOverrides } from "./wire.js";
-/** Per-model keys this adapter writes; one that stops being emitted is cleared, not inherited. */
+/** Per-model keys this adapter writes; one a metadata-bearing entry stops emitting is cleared, not inherited. */
 const OWNED_MODEL_KEYS = [
     "id",
     "name",

package/dist/targets/wire.js

@@ -69,12 +69,24 @@ export function entryApi(entry) {
 /**
  * Merge the model entries agentsw owns over the ones already in an app
  * config: per-model keys the adapter does not model (`compat`, per-model wire
- * overrides, ...) survive a re-sync, while an `owned` key the new entry no
- * longer carries is cleared instead of lingering as last sync's value — a
- * stale `thinkingLevelMap` beside `reasoning: false` is a state no fresh write
+ * overrides, ...) survive a re-sync, and an `owned` key the entry omits is
+ * cleared rather than lingering as last sync's value — a stale
+ * `thinkingLevelMap` beside `reasoning: false` is a state no fresh write
  * produces.
+ *
+ * That clearing is only meaningful for an entry that carries metadata at all.
+ * A model the store knows nothing about arrives as a bare `{ id }` — that is
+ * exactly what enrichment does with an id no catalog row matched — and every
+ * adapter still adds the derived capability in `derived`. Absence in such a
+ * stub says nothing about the model, so the config's existing values are kept:
+ * deleting them would throw away limits an earlier lookup filled in, or that a
+ * person typed by hand, every time a catalog lookup misses. Once an entry
+ * carries any owned metadata of its own, the same absence is a statement about
+ * the model and is applied as before.
  */
-export function mergeModels(previous, written, owned) {
+export function mergeModels(previous, written, owned, 
+/** Owned keys every adapter derives instead of reading them from the model. */
+derived = ["input"]) {
     const prev = new Map();
     if (Array.isArray(previous)) {
         for (const m of previous) {
@@ -82,14 +94,17 @@ export function mergeModels(previous, written, owned) {
                 prev.set(m.id, m);
         }
     }
+    const informative = owned.filter((key) => key !== "id" && !derived.includes(key));
     return written.map((m) => {
         const old = prev.get(m.id);
         if (!old)
             return m;
         const kept = { ...old };
-        for (const key of owned)
-            if (!(key in m))
-                delete kept[key];
+        const known = informative.some((key) => key in m);
+        if (known)
+            for (const key of owned)
+                if (!(key in m))
+                    delete kept[key];
         return { ...kept, ...m };
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsw",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "CLI provider switcher for coding agents: manage OpenAI/Anthropic-protocol providers in one place and sync them, with models.dev metadata, into Claude Code, Codex, omp, pi, prime-agent, opencode, Hermes, WorkBuddy and DeepSeek Harness",
   "type": "module",
   "repository": {