dsh-opencode-free-tier 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,236 @@
+# dsh-opencode-free-tier
+
+Free OpenCode Zen models inside DeepSeek Harness (DSH) via the stock `llm-pi-ai` adapter — no API key, no extra provider plugin.
+
+## The problem
+
+Since 2026-09-16, OpenCode Zen's anonymous free lane rejects every request that doesn't look like traffic from the OpenCode CLI:
+
+```
+403: {"type":"FreeTierError","message":"Error from provider (Console): OpenCode's free tier can only be used from within OpenCode"}
+```
+
+Live-probed 2026-09-18, the gate has three parts — **all** must hold:
+
+1. `User-Agent` starts with `opencode/`
+2. `x-opencode-session` is `ses_` + 26 chars (12 lowercase hex + 14 Base62)
+3. the chat body streams (`stream: true`) with function tools named `bash` **and** `read`
+
+DSH's `llm-pi-ai` `opencode` route sends none of the three (UA `deepseek-harness/...`,
+the DSH session id, no tools on plain chats), so every free-model call fails — while
+OpenCode CLI works keyless. No login and no key are required; the anonymous lane key
+is the literal string `public`.
+
+## What this plugin does
+
+A zero-dependency Cordis plugin that fixes all three at the fetch transport layer:
+
+- **`llm/stream` waterfall observer** — carries `GenerateOptions.sessionId` in an
+  `AsyncLocalStorage` across each adapter stream, so the fetch layer knows which DSH
+  conversation a request belongs to (stable session → optimal upstream prompt-cache routing).
+- **Fetch middleware, scoped strictly to `opencode.ai`** (+ subdomains) — every other
+  host passes through byte-for-byte untouched:
+  - missing/non-CLI `User-Agent` → `opencode/<cli-version> (platform arch; node...)`
+  - missing/malformed `x-opencode-session` → canonicalized (`ses_` + 26) from the DSH
+    conversation id; an already-canonical id passes through (cache affinity preserved)
+  - fills `x-opencode-client: cli`, `x-session-affinity`, `X-Session-Id`,
+    `x-opencode-request`, `x-opencode-project` when absent
+  - chat-completions bodies missing `bash`/`read` tools get the stubs appended
+    (`tool_choice: "none"` when the caller had no tools, so the model never calls them)
+
+Already-correct requests pass through untouched (idempotent) — e.g. it coexists with
+`opencode2dsh` instead of breaking it.
+
+It supersedes `dsh-opencode-session-header`, which only stamped a **non-canonical**
+session (no UA, no tools) and actively breaks canonical sessions by overwriting them.
+Remove that plugin when installing this one.
+
+## Requirements
+
+- DSH (`DeepSeek Harness`) with a `web` profile; Node.js ≥ 20 (already present if DSH runs)
+- Outbound HTTPS to `opencode.ai`
+
+## Install
+
+### Option A — from npm (recommended)
+
+```sh
+dsh plugin --profile web add dsh-opencode-free-tier
+```
+
+then register the bundle in `package.json`:
+
+```json
+{
+  "dsh": {
+    "profile": {
+      "bundles": [
+        "@deepseek-ai/dsh-base",
+        "@deepseek-ai/dsh-web-app",
+        "dsh-opencode-free-tier",
+        "dsh-file-upload"
+      ]
+    }
+  }
+}
+```
+
+### Option B — from git
+
+```sh
+cd ~/.dsh/profiles/web
+pnpm add github:DOCUTEE/dsh-opencode-free-tier
+```
+
+then register the bundle as above.
+
+### Option C — from a local clone
+
+```sh
+git clone https://github.com/DOCUTEE/dsh-opencode-free-tier.git
+cd ~/.dsh/profiles/web
+pnpm add file:/path/to/dsh-opencode-free-tier
+```
+
+then register the bundle as above.
+
+Finally:
+
+```sh
+cd ~/.dsh/profiles/web
+pnpm install
+```
+
+Remove `dsh-opencode-session-header` from `dependencies` + `bundles` if present,
+then **restart `dsh web`** once — plugins load at boot.
+
+## Configure the free route
+
+No API key needed. The anonymous lane key is the literal string `public`, but
+`llm-pi-ai` still requires the route to *name* a credential — otherwise pi-ai
+refuses the request before it is even sent (`Provider is not configured:
+opencode`). So expose the anonymous key through `$DSH_HOME/.env`:
+
+```sh
+# ~/.dsh/.env (DSH_HOME defaults to ~/.dsh)
+OPENCODE_ANON_KEY=public
+```
+
+In `~/.dsh/settings.yaml`:
+
+```yaml
+llm-pi-ai:
+  providers:
+    opencode:
+      apiKeyEnv: OPENCODE_ANON_KEY
+      headers:
+        Authorization: Bearer public
+```
+
+**Restart `dsh web`** after editing `.env` — the environment snapshot is taken
+at launch, so a key added while DSH runs is invisible until restart.
+
+Then pick any free model from the `opencode` route (e.g. `mimo-v2.5-free`,
+`deepseek-v4-flash-free`, `ling-3.0-flash-fin-free`, `nemotron-3-ultra-free`).
+
+## Verify
+
+```sh
+curl -s -X POST https://opencode.ai/zen/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer public" \
+  -H "User-Agent: deepseek-harness/0.1.0 test" \
+  -d '{"model":"mimo-v2.5-free","messages":[{"role":"user","content":"hi"}],"stream":true,"max_completion_tokens":10}' \
+  --max-time 20 | head -c 300
+```
+
+- Without the plugin: `FreeTierError`.
+- With the plugin (restart DSH, chat with the model): normal streamed chunks.
+
+Or run the plugin's own tests:
+
+```sh
+npm test
+```
+
+## Runtime switch (no restart needed)
+
+State file: `~/.dsh/plugins/dsh-opencode-free-tier.json` (defaults to `~/.dsh`,
+or `$DSH_HOME` when set):
+
+```json
+{ "enabled": false }
+```
+
+- `false` → everything passes through untouched
+- `true` or **file missing** → fixing on
+- re-read on every matching request
+
+Plugin config in `cordis.patch.yml` also accepts `{ hosts?, enabled? }`.
+
+## How it works
+
+```
+DSH llm-pi-ai (opencode route)
+  │  pi-ai openai-completions stream
+  ▼  global fetch
+dsh-opencode-free-tier middleware (opencode.ai only)
+  │  UA → opencode/…  ·  session → ses_+26  ·  tools → +bash/+read
+  ▼
+https://opencode.ai/zen/…   Authorization: Bearer public
+```
+
+Session derivation mirrors the CLI: `SHA-256("ses\0" + DSH-session-id)` →
+`ses_` + 6 bytes hex + 10 bytes Base62. The same conversation keeps a stable
+session; different conversations separate (same scheme as `opencode2dsh`, so a
+mixed setup shares cache affinity).
+
+## Testing
+
+```sh
+node --test test/free-tier.test.mjs
+```
+
+Covers: canonical session passthrough/hashing, CLI UA shape, tool injection +
+idempotence, middleware fixing a DSH-like request while preserving an
+already-correct one and leaving foreign hosts untouched.
+
+## Compatibility & retirement
+
+- Verified against DSH `0.1.2-rc.1` and `@earendil-works/pi-ai` `0.85.x`.
+- Depends on DSH outbound LLM traffic using the process-global `fetch`. If a future
+  DSH build changes its network stack, the plugin silently stops fixing — the symptom
+  is simply the `403` returning; uninstall then.
+- If upstream DSH ever ships native CLI disguise for the free lane, retire this plugin:
+  remove it from `dependencies` + `bundles`, `pnpm install`, restart.
+
+## Troubleshooting
+
+| Symptom | Cause & fix |
+| --- | --- |
+| `Provider is not configured: opencode` | The route names no credential, so pi-ai rejects before sending. Add `OPENCODE_ANON_KEY=public` to `~/.dsh/.env` and `apiKeyEnv: OPENCODE_ANON_KEY` to the route (see Configure), then **restart** `dsh web`. |
+| `403 FreeTierError: free tier can only be used from within OpenCode` | The disguise isn't applied: plugin not installed/enabled, DSH not restarted after install, or the runtime switch disables it. Check `~/.dsh/plugins/dsh-opencode-free-tier.json` is absent or `{"enabled": true}`. |
+| `400 MissingSessionID` | An old `dsh-opencode-session-header` is overwriting the canonical session — remove that plugin. |
+| Key added to `.env` but still `MISSING_CREDENTIAL` | `.env` is snapshotted at launch — restart `dsh web`. |
+
+## License
+
+[MIT](./LICENSE)
+
+## Release process (maintainers)
+
+Publishing uses [npm trusted publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) —
+no tokens, no OTP. One-time setup on npmjs.com → package → Settings →
+Trusted Publisher: GitHub Actions, user `DOCUTEE`, repository
+`dsh-opencode-free-tier`, workflow `publish.yml`, allowed action `npm publish`.
+
+To release:
+
+```sh
+# 1. bump version in package.json (must match the tag below)
+# 2. commit, then:
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+Pushing the tag runs `.github/workflows/publish.yml`, which runs tests and
+`npm publish`es. Provenance is generated automatically.

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-opencode-session-header bundle patch: mount the session-header plugin
+# under its package name, resolved through the profile's node_modules.
+- insert:
+    - id: dsh-opencode-free-tier
+      name: dsh-opencode-free-tier

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './index.js'

package/lib/index.js

@@ -0,0 +1,414 @@
+/**
+ * dsh-opencode-free-tier — make every DSH request to OpenCode Zen look like
+ * OpenCode CLI so the anonymous free lane passes its gate.
+ *
+ * Live-probed 2026-09-18 (see README): Zen free tier returns
+ * 403 FreeTierError unless ALL three hold:
+ *   1. `User-Agent` starts with `opencode/`
+ *   2. `x-opencode-session` is `ses_` + 26 chars (12 lowercase hex + 14 Base62)
+ *   3. chat body streams with function tools named `bash` AND `read`
+ *
+ * DSH's `llm-pi-ai` opencode route sends none of the three (UA is
+ * `deepseek-harness/...`, session is the DSH id, plain chats carry no tools),
+ * so every free-model call fails. The `opencode2dsh` adapter already spoofs
+ * all three — this plugin fixes the generic `llm-pi-ai` path at the fetch
+ * transport layer, and leaves already-correct requests (opencode2dsh)
+ * byte-for-byte untouched (idempotent).
+ *
+ * Scope: `opencode.ai` (+ subdomains) only. Every other host passes through.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { createHash, randomBytes } from 'node:crypto'
+
+/** Cordis plugin name (the Loader entry). */
+export const name = 'dsh-opencode-free-tier'
+
+/** Services required before load: none — llm/stream is an optional observer. */
+export const inject = []
+
+/** Carries the DSH session id across one llm/stream call. */
+export const requestSessionContext = new AsyncLocalStorage()
+
+const HEADER_SESSION = 'x-opencode-session'
+const DEFAULT_HOSTS = ['opencode.ai']
+
+/** Canonical CLI session shape: `ses_` + 12 hex + 14 Base62 (= 26). */
+export const CANONICAL_SESSION_PATTERN = /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/
+const BASE62_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+
+function base62Fixed(value, width) {
+  const base = 62n
+  let n = value
+  const out = new Array(width)
+  for (let i = width - 1; i >= 0; i--) {
+    out[i] = BASE62_ALPHABET.charAt(Number(n % base))
+    n /= base
+  }
+  return out.join('')
+}
+
+/**
+ * Canonicalize any signal into the CLI session shape. An already-canonical
+ * id passes through unchanged (preserves upstream prompt-cache affinity);
+ * anything else (DSH session id, fallback, probe) is deterministically hashed.
+ */
+export function canonicalSessionID(signal) {
+  if (typeof signal === 'string' && CANONICAL_SESSION_PATTERN.test(signal)) return signal
+  const sum = createHash('sha256').update('ses\0' + String(signal)).digest()
+  return `ses_${sum.subarray(0, 6).toString('hex')}${base62Fixed(BigInt('0x' + sum.subarray(6, 16).toString('hex')), 14)}`
+}
+
+function randomID(prefix, size) {
+  return `${prefix}_${randomBytes(size).toString('hex')}`
+}
+
+function stableID(prefix, value) {
+  return `${prefix}_${createHash('sha256').update(prefix + '\0' + value).digest().subarray(0, 12).toString('hex')}`
+}
+
+/** Stable default project id (same derivation as opencode2dsh). */
+function defaultProjectID() {
+  return stableID('prj', 'opencode2dsh:default-project')
+}
+
+/** CLI-identical user agent. */
+export function opencodeUserAgent() {
+  return `opencode/1.18.31 (${process.platform} ${process.arch}; node${process.versions.node})`
+}
+
+// ---------------------------------------------------------------------------
+// fetch pipeline (own symbol so coexisting plugins never clobber each other)
+// ---------------------------------------------------------------------------
+
+const FETCH_PIPELINE_KEY = Symbol.for('dsh-opencode-free-tier.fetch.pipeline.v1')
+
+function ensureFetchPipeline() {
+  const g = globalThis
+  if (g[FETCH_PIPELINE_KEY]) return g[FETCH_PIPELINE_KEY]
+  let underlyingFetch = globalThis.fetch
+  const state = {
+    getUnderlyingFetch: () => underlyingFetch,
+    setUnderlyingFetch: (nextFetch) => {
+      underlyingFetch = nextFetch
+    },
+    middlewares: [],
+    installed: false,
+    patchedFetch: undefined,
+  }
+  g[FETCH_PIPELINE_KEY] = state
+  return state
+}
+
+function compose(state) {
+  const ordered = [...state.middlewares].sort((a, b) => a.priority - b.priority)
+  const callAt = (index, input, init) => {
+    if (index >= ordered.length) return state.getUnderlyingFetch()(input, init)
+    const current = ordered[index]
+    return current.middleware({
+      input,
+      init,
+      next: (nextInput, nextInit) => callAt(index + 1, nextInput, nextInit),
+    })
+  }
+  return (input, init) => callAt(0, input, init)
+}
+
+function installFetchPipeline() {
+  const state = ensureFetchPipeline()
+  if (state.installed) {
+    state.patchedFetch = compose(state)
+    return
+  }
+  const prevDesc = Object.getOwnPropertyDescriptor(globalThis, 'fetch')
+  state.patchedFetch = compose(state)
+  Object.defineProperty(globalThis, 'fetch', {
+    configurable: true,
+    enumerable: prevDesc?.enumerable ?? true,
+    get() {
+      return state.patchedFetch
+    },
+    set(newFetch) {
+      if (newFetch === state.patchedFetch) return
+      try {
+        prevDesc?.set?.call(globalThis, newFetch)
+      } catch {}
+      state.setUnderlyingFetch(newFetch)
+      state.patchedFetch = compose(state)
+    },
+  })
+  state.installed = true
+}
+
+export function registerFetchMiddleware(registration) {
+  const state = ensureFetchPipeline()
+  const existingIndex = state.middlewares.findIndex((m) => m.name === registration.name)
+  if (existingIndex >= 0) state.middlewares.splice(existingIndex, 1, registration)
+  else state.middlewares.push(registration)
+  installFetchPipeline()
+}
+
+export function unregisterFetchMiddleware(mwName) {
+  const state = ensureFetchPipeline()
+  const index = state.middlewares.findIndex((m) => m.name === mwName)
+  if (index >= 0) state.middlewares.splice(index, 1)
+  if (state.installed) state.patchedFetch = compose(state)
+}
+
+// ---------------------------------------------------------------------------
+// request helpers
+// ---------------------------------------------------------------------------
+
+function requestUrlOf(input) {
+  try {
+    if (typeof input === 'string') return new URL(input)
+    if (input && typeof input === 'object' && typeof input.url === 'string') return new URL(input.url)
+  } catch {}
+  return undefined
+}
+
+export function hostMatches(hostname, hosts) {
+  const h = String(hostname ?? '').toLowerCase()
+  return hosts.some((entry) => {
+    const target = String(entry).toLowerCase().trim()
+    if (!target) return false
+    return h === target || h.endsWith(`.${target}`)
+  })
+}
+
+// ---------------------------------------------------------------------------
+// free-lane body shape (port of opencode2dsh ensureFreeLaneShape)
+// ---------------------------------------------------------------------------
+
+const FREE_LANE_GATE_TOOL_NAMES = ['bash', 'read']
+
+function freeLaneGateTool(toolName) {
+  return {
+    type: 'function',
+    function: {
+      name: toolName,
+      description: 'Reserved for the host runtime; do not call it.',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+    },
+  }
+}
+
+/**
+ * Rewrite an outgoing chat-completions payload so it satisfies the free-lane
+ * agent-shape gate. Appends only the gate tools the payload is missing; when
+ * the context carried no tools at all, `tool_choice: 'none'` keeps the model
+ * from ever calling the injected stubs. Returns the new body object, or
+ * `undefined` when the payload already satisfies the gate or is not a
+ * chat-completions body (caller keeps the original in that case).
+ */
+export function ensureFreeLaneShape(payload) {
+  if (typeof payload !== 'object' || payload === null || Array.isArray(payload)) return undefined
+  const body = payload
+  if (!Array.isArray(body.messages)) return undefined
+  const tools = Array.isArray(body.tools) ? body.tools : []
+  const names = new Set(
+    tools.map((tool) => {
+      const fn = typeof tool === 'object' && tool !== null ? tool.function : undefined
+      return typeof fn === 'object' && fn !== null ? fn.name : undefined
+    }),
+  )
+  const missing = FREE_LANE_GATE_TOOL_NAMES.filter((toolName) => !names.has(toolName))
+  if (missing.length === 0) return undefined
+  const next = { ...body }
+  next.tools = [...tools, ...missing.map((toolName) => freeLaneGateTool(toolName))]
+  if (tools.length === 0) next.tool_choice = 'none'
+  // The gate also has a streaming half; pi-ai always streams, but enforce it
+  // for any other client that reaches this layer without it.
+  if (next.stream !== true) next.stream = true
+  return next
+}
+
+async function readBodyText(input, init) {
+  if (init && init.body !== undefined) {
+    const b = init.body
+    if (typeof b === 'string') return b
+    // URLSearchParams / FormData / Blob / ArrayBuffer etc: not JSON chat bodies.
+    return undefined
+  }
+  try {
+    if (input && typeof input === 'object' && typeof input.clone === 'function' && typeof input.text === 'function') {
+      const method = String(input.method ?? 'GET').toUpperCase()
+      if (method === 'GET' || method === 'HEAD') return undefined
+      const ct = input.headers?.get?.('content-type') ?? ''
+      if (ct && !ct.includes('json')) return undefined
+      return await input.clone().text()
+    }
+  } catch {}
+  return undefined
+}
+
+// ---------------------------------------------------------------------------
+// middleware + llm/stream listener factories (exported for tests)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the fetch middleware.
+ * Options:
+ *   - hosts: allowlist (default opencode.ai)
+ *   - isEnabled: () => boolean, consulted per matching request
+ */
+export function createFreeTierMiddleware(options) {
+  const hosts = options?.hosts?.length ? options.hosts : DEFAULT_HOSTS
+  const isEnabled = options?.isEnabled || (() => true)
+  return async function freeTierMiddleware({ input, init, next }) {
+    const url = requestUrlOf(input)
+    if (!url || !hostMatches(url.hostname, hosts)) return next(input, init)
+    if (!isEnabled()) return next(input, init)
+
+    // Merge whichever header source would actually reach the wire (fetch spec:
+    // init.headers replaces Request headers when present).
+    const source =
+      init && init.headers !== undefined
+        ? init.headers
+        : input && typeof input === 'object' && input.headers
+          ? input.headers
+          : undefined
+    const headers = new Headers(source ?? undefined)
+
+    // 1. User-Agent must start with opencode/
+    const ua = headers.get('user-agent')
+    if (!ua || !ua.toLowerCase().startsWith('opencode/')) {
+      headers.set('user-agent', opencodeUserAgent())
+    }
+
+    // 2. x-opencode-session must be canonical ses_+26; preserve a correct one
+    // (opencode2dsh already sets a canonical id — keep it for cache affinity).
+    const existing = headers.get(HEADER_SESSION)
+    let session
+    if (existing && CANONICAL_SESSION_PATTERN.test(existing)) {
+      session = existing
+    } else {
+      const store = requestSessionContext.getStore()
+      const signal =
+        typeof store === 'string' && store.length > 0 ? store : randomID('fallback', 16)
+      session = canonicalSessionID(signal)
+      headers.set(HEADER_SESSION, session)
+    }
+    if (!headers.get('x-opencode-client')) headers.set('x-opencode-client', 'cli')
+    if (!headers.get('x-session-affinity')) headers.set('x-session-affinity', session)
+    if (!headers.get('x-session-id') && !headers.get('X-Session-Id')) headers.set('X-Session-Id', session)
+    if (!headers.get('x-opencode-request')) headers.set('x-opencode-request', randomID('req', 16))
+    if (!headers.get('x-opencode-project')) headers.set('x-opencode-project', defaultProjectID())
+
+    // 3. Body must carry bash+read tools (chat-completions shape only).
+    let newBodyText
+    try {
+      const bodyText = await readBodyText(input, init)
+      if (typeof bodyText === 'string' && bodyText.length > 0) {
+        let parsed
+        try {
+          parsed = JSON.parse(bodyText)
+        } catch {
+          parsed = undefined
+        }
+        const fixed = parsed === undefined ? undefined : ensureFreeLaneShape(parsed)
+        if (fixed !== undefined) newBodyText = JSON.stringify(fixed)
+      }
+    } catch {}
+
+    if (newBodyText === undefined) {
+      return next(input, { ...init, headers })
+    }
+    // init.body wins over Request body per fetch spec, so stamping the fixed
+    // string there covers both string-URL and Request-object call shapes.
+    return next(input, { ...init, headers, body: newBodyText })
+  }
+}
+
+/**
+ * Build the `llm/stream` waterfall listener: re-emits the downstream stream
+ * with every iterator step executed inside AsyncLocalStorage carrying the
+ * call's sessionId, so fetches issued while iterating inherit the context.
+ */
+export function createLlmStreamListener(sessionContext) {
+  return function llmStreamObserver(llmOptions, next) {
+    const sessionKey = String(llmOptions?.sessionId ?? '')
+    const inner = next()
+    const iterator = inner[Symbol.asyncIterator]()
+    const doneResult = () => ({ done: true, value: undefined })
+    const runNext = () => sessionContext.run(sessionKey, () => iterator.next())
+    const runReturn = () =>
+      sessionContext.run(sessionKey, () => (iterator.return ? iterator.return() : Promise.resolve(doneResult())))
+    const runThrow = (err) =>
+      sessionContext.run(sessionKey, () => (iterator.throw ? iterator.throw(err) : Promise.resolve(doneResult())))
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          next: () => runNext(),
+          return: () => runReturn(),
+          throw: (err) => runThrow(err),
+        }
+      },
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// runtime switch (re-read per request; no restart needed)
+// ---------------------------------------------------------------------------
+
+export function switchFilePath() {
+  const envHome = process.env.DSH_HOME?.trim()
+  const home = envHome ? envHome : join(homedir(), '.dsh')
+  return join(home, 'plugins', 'dsh-opencode-free-tier.json')
+}
+
+/** Missing/unreadable file or non-boolean `enabled` → seed (default true). */
+export function readEnabledSwitch(seed = true) {
+  try {
+    const parsed = JSON.parse(readFileSync(switchFilePath(), 'utf8'))
+    if (parsed && typeof parsed.enabled === 'boolean') return parsed.enabled
+  } catch {}
+  return seed
+}
+
+// ---------------------------------------------------------------------------
+// cordis plugin surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Mount the plugin.
+ * @param ctx - host cordis context.
+ * @param config - optional deployment config: { hosts?, enabled? }.
+ */
+export function apply(ctx, config) {
+  const cfg = config ?? {}
+  const hosts = Array.isArray(cfg.hosts) && cfg.hosts.length ? cfg.hosts.map(String) : DEFAULT_HOSTS
+  const seedEnabled = typeof cfg.enabled === 'boolean' ? cfg.enabled : true
+  const isEnabled = () => readEnabledSwitch(seedEnabled)
+
+  const log = (level, message) => {
+    try {
+      ctx.logger?.[level]?.(message)
+    } catch {}
+  }
+
+  ctx.effect(() => {
+    registerFetchMiddleware({
+      name: 'dsh-opencode-free-tier-inject',
+      priority: 6,
+      middleware: createFreeTierMiddleware({ hosts, isEnabled }),
+    })
+    return () => {
+      unregisterFetchMiddleware('dsh-opencode-free-tier-inject')
+    }
+  }, 'dsh-opencode-free-tier: fetch middleware')
+
+  ctx.on('llm/stream', createLlmStreamListener(requestSessionContext))
+
+  log('info', `[dsh-opencode-free-tier] loaded: hosts=${hosts.join(', ')} ua=${opencodeUserAgent()}`)
+  log('info', `[dsh-opencode-free-tier] runtime switch: ${switchFilePath()} ({"enabled":false} disables; missing file = enabled)`)
+}
+
+export default apply

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "dsh-opencode-free-tier",
+  "version": "0.1.0",
+  "description": "Make DSH llm-pi-ai opencode routes pass Zen free-tier gate: opencode User-Agent + canonical ses_ session + bash/read tools. Scoped to opencode.ai only.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "license": "MIT",
+  "author": "DOCUTEE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DOCUTEE/dsh-opencode-free-tier.git"
+  },
+  "homepage": "https://github.com/DOCUTEE/dsh-opencode-free-tier#readme",
+  "bugs": {
+    "url": "https://github.com/DOCUTEE/dsh-opencode-free-tier/issues"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "opencode",
+    "opencode-zen",
+    "free-tier",
+    "x-opencode-session"
+  ],
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}