opencode-fetch-writer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tonydeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# opencode-fetch-writer
+
+[![CI](https://github.com/tonydeng/opencode-fetch-writer/actions/workflows/ci.yml/badge.svg)](https://github.com/tonydeng/opencode-fetch-writer/actions/workflows/ci.yml)
+
+OpenCode plugin that rewrites the **User-Agent** and adds/removes **HTTP headers** on outgoing provider requests — for any provider, configured purely through plugin options.
+
+**中文文档：[README.zh-CN.md](./README.zh-CN.md)**
+
+## Why
+
+Two common failure modes when pointing OpenCode at a custom or enterprise model gateway:
+
+1. **Your configured `User-Agent` is silently ignored.** Some SDKs merge their own default UA *after* your `provider.options.headers`, so the gateway never sees the UA you configured.
+2. **The gateway rejects the request** because of the default client fingerprint (UA or headers added by intermediate layers).
+
+This plugin solves both by wrapping the provider's `options.fetch` through the official `config` hook. `options.fetch` is the final outbound choke point — headers set there cannot be overridden by SDK defaults.
+
+## Install
+
+### OpenCode v1 (1.x, tuple syntax)
+
+```jsonc
+// opencode.jsonc
+{
+  "plugin": [
+    ["opencode-fetch-writer@0.1.0", {
+      "providerId": "my-provider",
+      "uaTarget": "my-app/1.0.0",
+      "headersToStrip": ["x-unwanted-header"],
+      "headersToInject": {
+        "X-Client-Name": "my-app"
+      }
+    }]
+  ]
+}
+```
+
+### OpenCode v2 (object syntax)
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-fetch-writer@0.1.0",
+      "options": {
+        "providerId": "my-provider",
+        "uaTarget": "my-app/1.0.0",
+        "headersToStrip": ["x-unwanted-header"],
+        "headersToInject": {
+          "X-Client-Name": "my-app"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Local development
+
+```jsonc
+{
+  "plugin": ["file://./src/index.ts"]
+}
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `providerId` | `string` | — | Provider ID (key in your `provider` map). **Required** — the plugin stays inactive without it. |
+| `uaTarget` | `string` | — | Target User-Agent. Omit to leave the UA unchanged. |
+| `headersToStrip` | `string[]` | `[]` | Header names to delete from outgoing requests. |
+| `headersToInject` | `Record<string, string>` | `{}` | Headers to inject when missing. **Never overwrites** existing values. |
+| `debug` | `boolean` | `false` | Enable debug logging to stderr. |
+
+## Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `FETCH_WRITER_UA` | Overrides the `uaTarget` option | — |
+| `FETCH_WRITER_DEBUG` | Set to `1` to enable debug logging | `0` |
+
+## Behavior notes
+
+- **Marker guard**: the plugin marks the wrapped fetch and refuses to wrap twice. If the plugin gets loaded through both auto-discovery and an explicit config entry, your requests are still wrapped exactly once.
+- **Activation log**: on startup, the plugin always prints `[fetch-writer] patched options.fetch for provider "…"` to stderr so you can confirm it took effect.
+- **Both fetch call shapes** supported: `fetch(url, init)` and `fetch(new Request(...))`.
+
+## Troubleshooting
+
+- **Plugin not taking effect** — check that `providerId` matches the key in your `provider` map exactly (case-sensitive).
+- **UA still overridden** — make sure no other plugin or provider option also sets a custom `fetch` after this one.
+- **Double patching** — the marker guard handles it; if you see the activation line twice, you have two *different* fetch wrappers active, not this plugin twice.
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun run build
+bun test
+```
+
+## License
+
+[MIT](./LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,106 @@
+# opencode-fetch-writer
+
+[![CI](https://github.com/tonydeng/opencode-fetch-writer/actions/workflows/ci.yml/badge.svg)](https://github.com/tonydeng/opencode-fetch-writer/actions/workflows/ci.yml)
+
+OpenCode 插件：改写 provider 出站请求的 **User-Agent** 并增删 **HTTP headers**——适用于任意 provider，完全通过插件 options 配置。
+
+**English: [README.md](./README.md)**
+
+## 为什么需要
+
+把 OpenCode 指向自定义或企业级模型网关时，常见两类故障：
+
+1. **你配置的 `User-Agent` 被静默忽略。** 部分 SDK 在合并 `provider.options.headers` *之后*再叠加自己的默认 UA，网关根本看不到你配置的 UA。
+2. **网关直接拒绝请求**，因为默认客户端指纹不合规（UA 或中间层附加的 headers）。
+
+本插件通过官方 `config` hook 包装 provider 的 `options.fetch` 解决以上两个问题。`options.fetch` 是请求的最终出口——在这里设置的 headers 不会被 SDK 默认值覆盖。
+
+## 安装
+
+### OpenCode v1（1.x，元组语法）
+
+```jsonc
+// opencode.jsonc
+{
+  "plugin": [
+    ["opencode-fetch-writer@0.1.0", {
+      "providerId": "my-provider",
+      "uaTarget": "my-app/1.0.0",
+      "headersToStrip": ["x-unwanted-header"],
+      "headersToInject": {
+        "X-Client-Name": "my-app"
+      }
+    }]
+  ]
+}
+```
+
+### OpenCode v2（对象语法）
+
+```jsonc
+{
+  "plugins": [
+    {
+      "package": "opencode-fetch-writer@0.1.0",
+      "options": {
+        "providerId": "my-provider",
+        "uaTarget": "my-app/1.0.0",
+        "headersToStrip": ["x-unwanted-header"],
+        "headersToInject": {
+          "X-Client-Name": "my-app"
+        }
+      }
+    }
+  ]
+}
+```
+
+### 本地开发
+
+```jsonc
+{
+  "plugin": ["file://./src/index.ts"]
+}
+```
+
+## Options
+
+| 选项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `providerId` | `string` | — | Provider ID（`provider` 映射中的键）。**必填**——缺省时插件不激活。 |
+| `uaTarget` | `string` | — | 目标 User-Agent。缺省则不改写 UA。 |
+| `headersToStrip` | `string[]` | `[]` | 需要从出站请求中删除的 header 名。 |
+| `headersToInject` | `Record<string, string>` | `{}` | 缺失时注入的 headers。**从不覆盖**已有值。 |
+| `debug` | `boolean` | `false` | 向 stderr 输出调试日志。 |
+
+## 环境变量
+
+| 变量 | 说明 | 默认值 |
+|---|---|---|
+| `FETCH_WRITER_UA` | 覆盖 `uaTarget` 选项 | — |
+| `FETCH_WRITER_DEBUG` | 设为 `1` 启用调试日志 | `0` |
+
+## 行为说明
+
+- **MARKER 守卫**：插件在包装后的 fetch 上打标记，拒绝二次包装。即使同时被 plugins/ 目录自动加载和配置文件显式引用，请求也只会被包装一次。
+- **激活日志**：启动时插件总会向 stderr 输出一行 `[fetch-writer] patched options.fetch for provider "…"`，便于确认生效。
+- **兼容两种 fetch 调用形态**：`fetch(url, init)` 与 `fetch(new Request(...))`。
+
+## 问题排查
+
+- **插件不生效**——检查 `providerId` 是否与 `provider` 映射中的键完全一致（区分大小写）。
+- **UA 仍被覆盖**——确认没有其他插件或 provider option 在本插件之后再次设置自定义 `fetch`。
+- **双重注入**——MARKER 守卫已处理；若激活日志出现两次，说明有两个*不同*的 fetch 包装器在生效，而非本插件重复加载。
+
+## 开发
+
+```bash
+bun install
+bun run typecheck
+bun run build
+bun test
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * opencode-fetch-writer
+ *
+ * Generic OpenCode plugin that rewrites outgoing HTTP headers (including
+ * User-Agent) for a configured provider, by wrapping its `options.fetch`
+ * through the official `config` hook.
+ *
+ * Why `options.fetch`? It is the final outbound choke point: headers set
+ * here cannot be overridden by SDK defaults. This is not true for
+ * `provider.options.headers` — some SDKs merge their own User-Agent after
+ * yours, silently discarding the configured value.
+ *
+ * Features:
+ *  - Rewrite the User-Agent to any target string
+ *  - Strip unwanted headers (e.g. ones injected by intermediate layers)
+ *  - Idempotently inject fallback headers (never overwrites existing values)
+ *  - Marker guard against double-wrapping when the plugin gets loaded twice
+ *    (auto-discovery in a plugins/ dir + an explicit entry in the config)
+ *
+ * Environment variables (all optional):
+ *   FETCH_WRITER_UA      - overrides the `uaTarget` option
+ *   FETCH_WRITER_DEBUG   - set to "1" to enable debug logging (stderr)
+ */
+import type { Plugin } from "@opencode-ai/plugin";
+export interface FetchWriterOptions {
+    /** Provider ID (key in the `provider` map) whose fetch will be wrapped. Required to activate the plugin. */
+    providerId?: string;
+    /** Target User-Agent string. Omit to leave the UA unchanged. */
+    uaTarget?: string;
+    /** Header names to delete from outgoing requests. Default: [] */
+    headersToStrip?: string[];
+    /** Headers to inject when missing. Never overwrites existing values. Default: {} */
+    headersToInject?: Record<string, string>;
+    /** Enable debug logging to stderr. Default: false */
+    debug?: boolean;
+}
+/** Marker guard: prevents double-wrapping when the plugin is loaded twice */
+export declare const MARKER = "__fetchWriterPatched";
+export declare const fetchWriter: Plugin;
+export default fetchWriter;

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * opencode-fetch-writer
+ *
+ * Generic OpenCode plugin that rewrites outgoing HTTP headers (including
+ * User-Agent) for a configured provider, by wrapping its `options.fetch`
+ * through the official `config` hook.
+ *
+ * Why `options.fetch`? It is the final outbound choke point: headers set
+ * here cannot be overridden by SDK defaults. This is not true for
+ * `provider.options.headers` — some SDKs merge their own User-Agent after
+ * yours, silently discarding the configured value.
+ *
+ * Features:
+ *  - Rewrite the User-Agent to any target string
+ *  - Strip unwanted headers (e.g. ones injected by intermediate layers)
+ *  - Idempotently inject fallback headers (never overwrites existing values)
+ *  - Marker guard against double-wrapping when the plugin gets loaded twice
+ *    (auto-discovery in a plugins/ dir + an explicit entry in the config)
+ *
+ * Environment variables (all optional):
+ *   FETCH_WRITER_UA      - overrides the `uaTarget` option
+ *   FETCH_WRITER_DEBUG   - set to "1" to enable debug logging (stderr)
+ */
+/** Marker guard: prevents double-wrapping when the plugin is loaded twice */
+export const MARKER = "__fetchWriterPatched";
+export const fetchWriter = async (_input, options) => {
+    const providerId = options?.providerId;
+    const uaTarget = options?.uaTarget ?? process.env.FETCH_WRITER_UA;
+    const headersToStrip = options?.headersToStrip ?? [];
+    const headersToInject = options?.headersToInject ?? {};
+    const debug = options?.debug === true || process.env.FETCH_WRITER_DEBUG === "1";
+    const log = (msg) => {
+        if (debug)
+            console.error(`[fetch-writer] ${msg}`);
+    };
+    return {
+        config: async (config) => {
+            if (!providerId) {
+                console.error("[fetch-writer] no providerId configured, plugin inactive");
+                return;
+            }
+            const provider = config.provider?.[providerId];
+            if (!provider) {
+                log(`provider "${providerId}" not found in config, skipping`);
+                return;
+            }
+            const opts = (provider.options ??= {});
+            const existingFetch = opts.fetch;
+            if (typeof existingFetch?.[MARKER] === "boolean") {
+                log("options.fetch already patched, skipping (marker guard)");
+                return;
+            }
+            const realFetch = existingFetch ?? globalThis.fetch.bind(globalThis);
+            const wrapped = (async (req, init) => {
+                try {
+                    // Support both fetch(url, init) and fetch(Request) call shapes
+                    const headers = new Headers(init?.headers ?? undefined);
+                    if (init?.headers === undefined && typeof Request !== "undefined" && req instanceof Request) {
+                        req.headers.forEach((v, k) => {
+                            if (!headers.has(k))
+                                headers.set(k, v);
+                        });
+                    }
+                    if (uaTarget) {
+                        log(`user-agent: ${headers.get("user-agent")} -> ${uaTarget}`);
+                        headers.set("user-agent", uaTarget);
+                    }
+                    for (const name of headersToStrip)
+                        headers.delete(name);
+                    for (const [name, value] of Object.entries(headersToInject)) {
+                        if (!headers.has(name))
+                            headers.set(name, value);
+                    }
+                    return realFetch(req, init ? { ...init, headers } : { headers });
+                }
+                catch (err) {
+                    log(`wrap failed, falling back to raw fetch: ${err}`);
+                    return realFetch(req, init);
+                }
+            });
+            wrapped[MARKER] = true;
+            opts.fetch = wrapped;
+            // Always emit one activation line so users can confirm the patch at startup
+            console.error(`[fetch-writer] patched options.fetch for provider "${providerId}"`);
+        },
+    };
+};
+export default fetchWriter;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "opencode-fetch-writer",
+  "version": "0.1.0",
+  "description": "OpenCode plugin: rewrite User-Agent and add/remove headers on provider requests",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "fetch",
+    "user-agent",
+    "headers",
+    "rewrite",
+    "http"
+  ],
+  "author": "tonydeng",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonydeng/opencode-fetch-writer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonydeng/opencode-fetch-writer/issues"
+  },
+  "homepage": "https://github.com/tonydeng/opencode-fetch-writer#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.17.0",
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ]
+}