@botconnector/bccli 0.4.17 → 0.5.0

package/package.json

@@ -1,29 +1,14 @@
 {
   "name": "@botconnector/bccli",
-  "version": "0.4.17",
-  "description": "BCCLI — BotConnector AI coding agent for the terminal",
+  "version": "0.5.0",
+  "description": "BCCLI | BotConnector multi-provider coding agent with stable CLI/SDK compatibility",
   "type": "module",
   "bin": {
-    "bccli": "dist/cli.js"
+    "bccli": "./cli.mjs"
   },
-  "files": [
-    "dist"
-  ],
   "engines": {
     "node": ">=22"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/farijarifriyanto-debug/bccli.git"
-  },
-  "license": "MIT",
-  "scripts": {
-    "build": "tsup && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome lint --error-on-warnings src test",
-    "test": "vitest run",
-    "coverage": "vitest run --coverage"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
     "diff": "^9.0.0",
@@ -33,45 +18,56 @@
     "undici": "^8.12.1",
     "ws": "^8.22.0",
     "yaml": "^2.9.1",
-    "zod": "^4.6.5"
+    "zod": "^4.6.5",
+    "@qwen-code/qwen-code": "0.26.3"
   },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.14",
-    "@types/node": "^26.6.3",
-    "@types/react": "^19.3.0",
-    "@types/ws": "^8.18.2",
-    "@vitest/coverage-v8": "^5.0.5",
-    "ink-testing-library": "^4.0.0",
-    "tsup": "^9.0.0",
-    "typescript": "^7.0.2",
-    "vitest": "^5.0.2"
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "test:security": "node --test test/security-e2e.test.mjs test/proxy-mcp-e2e.test.mjs test/trusted-mcp.test.mjs test/proxy.test.mjs",
+    "test:integration": "node --test test-integration/*.test.mjs",
+    "build": "node --check cli.mjs && node --check core.mjs && node --check proxy.mjs && node --check gateway.mjs && node --check branding.mjs && node --check credentials.mjs && node --check model-command.mjs && node --check providers.mjs && node --check provider-cli.mjs && node --check startup-menu.mjs",
+    "rebuild": "npm run build && npm test && npm pack --ignore-scripts"
   },
+  "license": "Apache-2.0",
   "overrides": {
-    "esbuild": "0.28.2"
-  },
-  "main": "dist/sdk.js",
-  "types": "dist/sdk.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/sdk.d.ts",
-      "default": "./dist/sdk.js"
-    }
+    "esbuild": "0.28.2",
+    "sharp": "0.35.5"
   },
-  "keywords": [
-    "bccli",
-    "ai",
-    "coding-agent",
-    "agent",
-    "cli",
-    "tui",
-    "terminal",
-    "mcp",
-    "openai",
-    "indonesia"
+  "files": [
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "cli.mjs",
+    "core.mjs",
+    "proxy.mjs",
+    "gateway.mjs",
+    "branding.mjs",
+    "credentials.mjs",
+    "model-command.mjs",
+    "providers.mjs",
+    "provider-cli.mjs",
+    "startup-menu.mjs",
+    "legacy-compat.mjs",
+    "legacy"
   ],
-  "author": "BotConnector (https://botconnector.id)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/farijarifriyanto-debug/bccli-runtime.git"
+  },
+  "homepage": "https://github.com/farijarifriyanto-debug/bccli#readme",
   "bugs": {
     "url": "https://github.com/farijarifriyanto-debug/bccli/issues"
   },
-  "homepage": "https://github.com/farijarifriyanto-debug/bccli#readme"
+  "author": "BICO Inovasi Digital / BotConnector",
+  "main": "./legacy/dist/sdk.js",
+  "types": "./legacy/dist/sdk.d.ts",
+  "exports": {
+    ".": {
+      "types": "./legacy/dist/sdk.d.ts",
+      "default": "./legacy/dist/sdk.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
 }

package/provider-cli.mjs

@@ -0,0 +1,76 @@
+// Provider management is an explicitly invoked CLI operation, not a model prompt.
+import { PROVIDERS, isConfigured, providerDefinition, removeProvider, saveProviderKey, selectedProvider, useProvider } from './providers.mjs'
+
+export async function hiddenApiKey({ input = process.stdin, output = process.stdout } = {}) {
+  if (!input.isTTY || typeof input.setRawMode !== 'function') throw Error('Provider add requires an interactive terminal to enter a hidden API key.')
+  output.write('Paste API key (hidden; Enter to save, Ctrl+C to cancel): ')
+  return new Promise((resolve, reject) => {
+    let value = ''
+    const finish = (error) => {
+      input.off('data', onData)
+      input.off('end', onEnd)
+      input.setRawMode(false)
+      input.pause()
+      output.write('\n')
+      error ? reject(error) : resolve(value)
+    }
+    const onEnd = () => finish(Error('API key input ended before confirmation.'))
+    const onData = buffer => {
+      for (const ch of buffer.toString('utf8')) {
+        if (ch === '\u0003') return finish(Error('Cancelled.'))
+        if (ch === '\r' || ch === '\n') return finish(value ? null : Error('Empty API key; nothing saved.'))
+        if (ch === '\u007f' || ch === '\b') { value = value.slice(0, -1); continue }
+        if (ch.charCodeAt(0) < 32) continue
+        value += ch
+        if (value.length > 8192) return finish(Error('API key is too long; nothing saved.'))
+      }
+    }
+    input.on('data', onData)
+    input.on('end', onEnd)
+    input.setRawMode(true)
+    input.resume()
+  })
+}
+
+export async function runProviderCommand(words, {
+  env = process.env,
+  getKey = hiddenApiKey,
+  out = text => console.log(text),
+  save = saveProviderKey,
+  select = useProvider,
+  remove = removeProvider,
+  configured = isConfigured,
+  active = selectedProvider,
+} = {}) {
+  const [action = 'list', id, ...extra] = words
+  if (!['list', 'add', 'use', 'remove'].includes(action) || (action === 'list' ? words.length > 1 : !id || extra.length)) {
+    throw Error('Use: provider list | add PROVIDER | use PROVIDER | remove PROVIDER.')
+  }
+  if (action === 'list') {
+    const current = active({env})
+    for (const [name, info] of Object.entries(PROVIDERS)) {
+      out(name + ' - ' + info.name + ' [' + (configured(name,{env}) ? 'configured' : 'no key') + ']' + (name === current ? ' [ACTIVE]' : ''))
+    }
+    out('Add: bccli provider add openrouter; select: bccli provider use openrouter')
+    out('Provider keys are stored encrypted for your Windows user. Other systems: use the provider environment variable.')
+    return 0
+  }
+  providerDefinition(id)
+  if (action === 'add') {
+    out('Provider: ' + PROVIDERS[id].name + ' (API use may incur charges; entering a key does not send an AI prompt).')
+    const key = await getKey()
+    save(id, key)
+    select(id,{env})
+    out('API key securely saved and provider selected: ' + id + '. Key was not printed. No AI request sent.')
+    out('Run: bccli models, then bccli chat --model MODEL_ID')
+    return 0
+  }
+  if (action === 'use') {
+    select(id,{env})
+    out('Active provider: ' + id + '. New sessions only; existing chats are unchanged.')
+    return 0
+  }
+  remove(id,{env})
+  out('Saved provider key removed for ' + id + '. Environment variables, if set, are not changed.')
+  return 0
+}

package/providers.mjs

@@ -0,0 +1,179 @@
+// BCCLI Preview provider keys: explicit OpenAI-compatible presets only.
+// Windows stores provider API keys as per-user DPAPI encrypted blobs. The
+// upstream Qwen process receives only an ephemeral loopback proxy token.
+import { randomBytes } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { existsSync, lstatSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join } from 'node:path'
+import { botConnectorCredentialStatus, botConnectorKey } from './credentials.mjs'
+import { GATEWAY } from './gateway.mjs'
+
+export const PROVIDERS = Object.freeze({
+  botconnector: Object.freeze({ name: 'BotConnector Cloud', endpoint: GATEWAY }),
+  openai: Object.freeze({ name: 'OpenAI API', endpoint: 'https://api.openai.com/v1', env: 'OPENAI_API_KEY' }),
+  openrouter: Object.freeze({ name: 'OpenRouter', endpoint: 'https://openrouter.ai/api/v1', env: 'OPENROUTER_API_KEY' }),
+  deepseek: Object.freeze({ name: 'DeepSeek', endpoint: 'https://api.deepseek.com/v1', env: 'DEEPSEEK_API_KEY' }),
+  groq: Object.freeze({ name: 'Groq', endpoint: 'https://api.groq.com/openai/v1', env: 'GROQ_API_KEY' }),
+  xai: Object.freeze({ name: 'xAI', endpoint: 'https://api.x.ai/v1', env: 'XAI_API_KEY' }),
+})
+export const ALLOWED_PROVIDER_ENDPOINTS = Object.freeze(Object.values(PROVIDERS).map(p => p.endpoint))
+const ID = /^[a-z][a-z0-9-]{0,31}$/
+const MAX_BLOB_BYTES = 64 * 1024
+const ENC_SCRIPT = '$ErrorActionPreference="Stop"; $plain=[Console]::In.ReadToEnd().Trim(); if(-not $plain){exit 1}; $sec=ConvertTo-SecureString -String $plain -AsPlainText -Force; [Console]::Out.Write((ConvertFrom-SecureString -SecureString $sec))'
+const DEC_SCRIPT = '$ErrorActionPreference="Stop"; $encoded=[Console]::In.ReadToEnd().Trim(); $sec=ConvertTo-SecureString -String $encoded; $ptr=[Runtime.InteropServices.Marshal]::SecureStringToBSTR($sec); try{[Console]::Out.Write([Runtime.InteropServices.Marshal]::PtrToStringBSTR($ptr))}finally{[Runtime.InteropServices.Marshal]::ZeroFreeBSTR($ptr)}'
+
+export function providerRoot({ home = homedir(), env = process.env } = {}) {
+  const path = env.BCCLI_PREVIEW_HOME || join(home, '.bccli-preview')
+  if (!isAbsolute(path)) throw Error('BCCLI_PREVIEW_HOME must be absolute.')
+  return path
+}
+export function providerDefinition(id) {
+  if (!Object.hasOwn(PROVIDERS, id)) throw Error('Unknown provider. Choose from: ' + Object.keys(PROVIDERS).join(', '))
+  return PROVIDERS[id]
+}
+function ownerDirectory(root, { create = false } = {}) {
+  if (create) mkdirSync(root, { recursive: true, mode: 0o700 })
+  if (!existsSync(root)) return false
+  const info = lstatSync(root)
+  if (!info.isDirectory() || info.isSymbolicLink()) throw Error('Preview credential directory is not a safe regular directory.')
+  return true
+}
+function keyPath(root, id) {
+  if (!ID.test(id)) throw Error('Provider key storage requires a supported provider.')
+  return join(root, 'provider-' + id + '.dpapi')
+}
+function dpapi(script, input, { platform = process.platform, runner = spawnSync } = {}) {
+  if (platform !== 'win32') throw Error('Persisting provider API keys currently requires Windows DPAPI. Use the provider environment variable on other systems.')
+  const result = runner('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+    input, encoding: 'utf8', timeout: 15000, maxBuffer: MAX_BLOB_BYTES, windowsHide: true,
+    env: { ...process.env, PSModulePath: process.env.PSModulePath },
+  })
+  if (result.error || result.status !== 0 || !result.stdout?.trim()) throw Error('Windows protected credential operation failed; no key was printed.')
+  return result.stdout.trim()
+}
+export function saveProviderKey(id, key, { root = providerRoot(), platform = process.platform, runner = spawnSync } = {}) {
+  providerDefinition(id)
+  if (typeof key !== 'string' || !key.trim() || key.length > 8192 || /[\r\n]/.test(key)) throw Error('API key cannot be empty, multiline, or oversized.')
+  if (platform !== 'win32') throw Error('On non-Windows systems, use the provider API key environment variable.')
+  ownerDirectory(root, { create: true })
+  const ciphertext = dpapi(ENC_SCRIPT, key.trim(), { platform, runner })
+  if (ciphertext.length > MAX_BLOB_BYTES || !/^[0-9a-f]+$/i.test(ciphertext)) throw Error('Windows credential encryption returned an invalid format.')
+  const path = keyPath(root, id)
+  if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())) throw Error('Unsafe provider credentials path.')
+  const temporary = path + '.' + randomBytes(8).toString('hex') + '.tmp'
+  try {
+    writeFileSync(temporary, ciphertext + '\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 })
+    renameSync(temporary, path)
+  } finally { rmSync(temporary, { force: true }) }
+}
+export function storedProviderKey(id, { root = providerRoot(), platform = process.platform, runner = spawnSync } = {}) {
+  providerDefinition(id)
+  if (!ownerDirectory(root)) throw Error('Provider not configured. Run provider add.')
+  const path = keyPath(root, id)
+  let info
+  try { info = lstatSync(path) }
+  catch { throw Error('Provider not configured. Run provider add.') }
+  if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_BLOB_BYTES) throw Error('Unsafe provider credentials file.')
+  const cipher = readFileSync(path, 'utf8')
+  if (!/^[0-9a-f]+\s*$/i.test(cipher)) throw Error('Provider credentials are invalid.')
+  return dpapi(DEC_SCRIPT, cipher, { platform, runner })
+}
+export function isConfigured(id, { env = process.env, root = providerRoot({env}) } = {}) {
+  providerDefinition(id)
+  if (id === 'botconnector') {
+    if (env.BOTCONNECTOR_API_KEY?.trim()) return true
+    try {
+      if (ownerDirectory(root)) {
+        const info = lstatSync(keyPath(root, id))
+        if (info.isFile() && !info.isSymbolicLink() && info.size <= MAX_BLOB_BYTES) return true
+      }
+    } catch {}
+    return botConnectorCredentialStatus({ env }).configured
+  }
+  if (env[PROVIDERS[id].env]?.trim()) return true
+  try { return ownerDirectory(root) && lstatSync(keyPath(root, id)).isFile() && !lstatSync(keyPath(root, id)).isSymbolicLink() }
+  catch { return false }
+}
+export function selectedProvider({ env = process.env, root = providerRoot({env}) } = {}) {
+  if (!ownerDirectory(root)) return 'botconnector'
+  const path = join(root, 'active-provider')
+  if (!existsSync(path)) return 'botconnector'
+  const info = lstatSync(path)
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 128) throw Error('Unsafe provider selection file.')
+  const id = readFileSync(path, 'utf8').trim()
+  providerDefinition(id)
+  return id
+}
+// Model IDs are public selections, never credentials. Keep one per provider
+// so a returning user goes directly to chat without repeating the model picker.
+const MODEL_ID = /^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,255}$/
+export function selectedModel(id, { env = process.env, root = providerRoot({ env }) } = {}) {
+  providerDefinition(id)
+  if (!ownerDirectory(root)) return undefined
+  const path = join(root, 'active-model-' + id)
+  if (!existsSync(path)) return undefined
+  const info = lstatSync(path)
+  if (!info.isFile() || info.isSymbolicLink() || info.size > 300) throw Error('Unsafe model selection file.')
+  const value = readFileSync(path, 'utf8').trim()
+  if (!MODEL_ID.test(value)) throw Error('Invalid saved model selection.')
+  return value
+}
+
+export function saveSelectedModel(id, model, { env = process.env, root = providerRoot({ env }) } = {}) {
+  providerDefinition(id)
+  if (!MODEL_ID.test(model)) throw Error('Invalid model ID.')
+  ownerDirectory(root, { create: true })
+  const path = join(root, 'active-model-' + id)
+  if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())) {
+    throw Error('Unsafe model selection path.')
+  }
+  const tmp = path + '.' + randomBytes(8).toString('hex') + '.tmp'
+  try { writeFileSync(tmp, model + '\n', { flag: 'wx', encoding: 'utf8', mode: 0o600 }); renameSync(tmp, path) }
+  finally { rmSync(tmp, { force: true }) }
+}
+
+export function useProvider(id, { env = process.env, root = providerRoot({env}) } = {}) {
+  providerDefinition(id)
+  if (!isConfigured(id, { env, root })) throw Error('Provider is not configured. Use: provider add ' + id + ' (or its API key environment variable).')
+  ownerDirectory(root, { create: true })
+  const path = join(root, 'active-provider')
+  if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink())) throw Error('Unsafe provider selection path.')
+  const tmp = path + '.' + randomBytes(8).toString('hex') + '.tmp'
+  try { writeFileSync(tmp, id + '\n', { flag: 'wx', encoding: 'utf8', mode: 0o600 }); renameSync(tmp, path) }
+  finally { rmSync(tmp, { force: true }) }
+}
+export function removeProvider(id, { env = process.env, root = providerRoot({env}) } = {}) {
+  providerDefinition(id)
+  if (!ownerDirectory(root)) return
+  const path = keyPath(root, id)
+  if (existsSync(path)) {
+    if (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()) throw Error('Unsafe provider credential path.')
+    rmSync(path)
+  }
+  if (selectedProvider({env,root}) === id) {
+    const active = join(root, 'active-provider')
+    rmSync(active, {force:true})
+  }
+}
+export function resolveProvider(id, { env = process.env, root = providerRoot({env}) } = {}) {
+  const info = providerDefinition(id)
+  if (id === 'botconnector') {
+    // Saved keys take precedence; legacy credentials are read only as fallback.
+    try { return { id, ...info, key: storedProviderKey(id, { root }) } }
+    catch (error) {
+      if (error?.message !== 'Provider not configured. Run provider add.') throw error
+      return { id, ...info, key: botConnectorKey({ env }) }
+    }
+  }
+  // An explicit key saved through "provider add" must win over stale environment
+  // variables. Never silently fall back if the encrypted file is corrupted.
+  let key
+  try { key = storedProviderKey(id, {root}) }
+  catch (error) {
+    if (error?.message !== 'Provider not configured. Run provider add.') throw error
+    key = env[info.env]?.trim()
+  }
+  if (!key) throw Error('Provider not configured. Run provider add ' + id + ' or set ' + info.env + '.')
+  return { id, ...info, key }
+}

package/proxy.mjs

@@ -0,0 +1,242 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { createServer } from 'node:http'
+import { GATEWAY } from './gateway.mjs'
+import { ALLOWED_PROVIDER_ENDPOINTS } from './providers.mjs'
+
+// This proxy lives only for one Qwen Code session. Real provider keys remain in
+// the launcher process; MCP and bash subprocesses can see only a short-lived
+// local bearer token. The proxy cannot be redirected to arbitrary hosts.
+const ALLOWED_PATHS = new Set(['/v1/models', '/v1/chat/completions', '/v1/responses'])
+const MAX_REQUEST_BYTES = 16 * 1024 * 1024
+
+// Qwen 0.26.3 produces get_goal without parameters and read_file with
+// optional JSON-schema type unions such as ["integer", "null"]. Strict
+// OpenAI-compatible providers reject both formats while parsing tools.
+// Normalize only the incompatible pieces, preserving all coding tools.
+function normalizeOptionalNullableSchema(schema) {
+  if (!schema || typeof schema !== 'object' || Array.isArray(schema)) return schema
+  let out = schema
+  if (schema.properties && typeof schema.properties === 'object' && !Array.isArray(schema.properties)) {
+    const required = new Set(Array.isArray(schema.required) ? schema.required : [])
+    let properties = schema.properties
+    for (const [name, field] of Object.entries(schema.properties)) {
+      if (!field || typeof field !== 'object' || Array.isArray(field)) continue
+      let candidate = field
+      // The optional absence of a field already represents null; dropping
+      // "null" from this one optional JSON-Schema union is safe. Do not rewrite
+      // required nullable fields or multi-type unions (fail closed upstream).
+      if (!required.has(name) && Array.isArray(field.type) && field.type.length === 2
+        && field.type.includes('null')) {
+        const primitive = field.type.find((type) => type !== 'null')
+        if (['string', 'number', 'integer', 'boolean', 'object', 'array'].includes(primitive)) {
+          candidate = { ...field, type: primitive }
+        }
+      }
+      candidate = normalizeOptionalNullableSchema(candidate)
+      if (candidate !== field) {
+        if (properties === schema.properties) properties = { ...properties }
+        properties[name] = candidate
+      }
+    }
+    if (properties !== schema.properties) out = { ...out, properties }
+  }
+  if (schema.items && typeof schema.items === 'object' && !Array.isArray(schema.items)) {
+    const items = normalizeOptionalNullableSchema(schema.items)
+    if (items !== schema.items) out = { ...out, items }
+  }
+  return out
+}
+
+export function normalizeZeroArgFunctionTools(requestBody) {
+  if (!requestBody || typeof requestBody !== 'object' || !Array.isArray(requestBody.tools)) return requestBody
+  let changed = false
+  const tools = requestBody.tools.map((tool) => {
+    const fn = tool?.type === 'function' ? tool.function : null
+    if (!fn || typeof fn.name !== 'string') return tool
+    const parameters = fn.parameters == null
+      ? { type: 'object', properties: {} }
+      : normalizeOptionalNullableSchema(fn.parameters)
+    if (parameters === fn.parameters) return tool
+    changed = true
+    return { ...tool, function: { ...fn, parameters } }
+  })
+  return changed ? { ...requestBody, tools } : requestBody
+}
+
+// The model can be switched with /model without restarting the coding agent.
+// Annotate each request with the ACTUAL model chosen by Qwen Config, rather
+// than retaining a stale --append-system-prompt model from CLI startup.
+export function attachRuntimeModelContext(payload) {
+  if (!payload || typeof payload !== 'object' || !Array.isArray(payload.messages)) return payload
+  const model = payload.model
+  if (typeof model !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._:/+-]{0,255}$/.test(model)) return payload
+  const index = payload.messages.findIndex(item => item?.role === 'system' && typeof item.content === 'string')
+  if (index === -1) return payload
+  const runtime = '\n\nRuntime metadata (not model instructions): active_model_id=' + model + '; client_app=BCCLI; transport=local-proxy.'
+  const messages = [...payload.messages]
+  messages[index] = { ...messages[index], content: messages[index].content + runtime }
+  return { ...payload, messages }
+}
+
+// Qwen 0.26.3 sends max_tokens=64000 for many model IDs. Several Gateway
+// upstream routes reject that value (e.g. GLM Flash). Bound the requested
+// output conservatively for coding-agent interoperability; never increase it.
+// This does not change the context window or input-token budget.
+const DEFAULT_OUTPUT_TOKEN_CEILING = 4096
+export function boundChatOutputTokens(payload) {
+  if (!payload || typeof payload !== 'object') return payload
+  const legacy = payload.max_tokens
+  const modern = payload.max_completion_tokens
+  const valid = (value) => Number.isInteger(value) && value > 0
+
+  // Real Gateway's exact Kimi route rejects legacy max_tokens. Keep parity
+  // with PAYG validation for positive decimal numeric strings, without
+  // changing the output-ceiling policy for any other model.
+  if (payload.model === 'kimi-k2.7-code') {
+    const parsed = (value) => {
+      if (typeof value !== 'number' && !(typeof value === 'string' && /^[0-9]+$/.test(value))) return null
+      const n = Number(value)
+      return Number.isSafeInteger(n) && n > 0 ? n : null
+    }
+    const legacyValue = parsed(legacy)
+    const modernValue = parsed(modern)
+    if (legacyValue != null) {
+      const requested = modernValue != null ? Math.min(legacyValue, modernValue) : legacyValue
+      const { max_tokens: _ignored, ...rest } = payload
+      return { ...rest, max_completion_tokens: Math.min(requested, DEFAULT_OUTPUT_TOKEN_CEILING) }
+    }
+    if (modernValue != null && (typeof modern !== 'number' || modernValue > DEFAULT_OUTPUT_TOKEN_CEILING)) {
+      return { ...payload, max_completion_tokens: Math.min(modernValue, DEFAULT_OUTPUT_TOKEN_CEILING) }
+    }
+  }
+  if (valid(legacy) && legacy > DEFAULT_OUTPUT_TOKEN_CEILING) {
+    return { ...payload, max_tokens: DEFAULT_OUTPUT_TOKEN_CEILING }
+  }
+  if (valid(modern) && modern > DEFAULT_OUTPUT_TOKEN_CEILING) {
+    return { ...payload, max_completion_tokens: DEFAULT_OUTPUT_TOKEN_CEILING }
+  }
+  return payload
+}
+
+function waitForDrainOrClose(res) {
+  if (res.destroyed) return Promise.resolve()
+  return new Promise((resolve) => {
+    const done = () => {
+      res.off('drain', done)
+      res.off('close', done)
+      resolve()
+    }
+    res.once('drain', done)
+    res.once('close', done)
+  })
+}
+
+function matchesToken(auth, token) {
+  if (typeof auth !== 'string') return false
+  const actual = Buffer.from(auth)
+  const expected = Buffer.from('Bearer ' + token)
+  return actual.length === expected.length && timingSafeEqual(actual, expected)
+}
+
+export async function startGatewayProxy({ key, endpoint = GATEWAY, token = randomBytes(32).toString('hex'), fetchImpl = fetch } = {}) {
+  if (!ALLOWED_PROVIDER_ENDPOINTS.includes(endpoint)) throw Error('Unapproved provider endpoint; local proxy refused to start.')
+  if (typeof key !== 'string' || !key.trim()) throw Error('Gateway key is required for local proxy.')
+  if (typeof token !== 'string' || token.length < 6 || token === key) throw Error('Invalid or non-isolated proxy token.')
+
+  const server = createServer(async (req, res) => {
+    const fail = (status, body) => {
+      if (res.headersSent || res.destroyed) return
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' })
+      res.end(JSON.stringify({ error: body }))
+    }
+
+    if (!matchesToken(req.headers.authorization, token)) {
+      fail(401, 'Local session token is required.')
+      return
+    }
+    if (!ALLOWED_PATHS.has(req.url ?? '')) {
+      fail(404, 'Unsupported local gateway route.')
+      return
+    }
+    const method = req.url === '/v1/models' ? 'GET' : 'POST'
+    if (req.method !== method) {
+      fail(405, 'Unsupported request method.')
+      return
+    }
+    if (req.headers['content-length'] && Number(req.headers['content-length']) > MAX_REQUEST_BYTES) {
+      fail(413, 'Request too large.')
+      return
+    }
+
+    const abort = new AbortController()
+    const onClose = () => { if (!res.writableEnded) abort.abort() }
+    res.once('close', onClose)
+    try {
+      let body
+      if (method === 'POST') {
+        const buffers = []
+        let bytes = 0
+        for await (const chunk of req) {
+          bytes += chunk.length
+          if (bytes > MAX_REQUEST_BYTES) {
+            fail(413, 'Request too large.')
+            return
+          }
+          buffers.push(chunk)
+        }
+        body = Buffer.concat(buffers)
+        if (req.url === '/v1/chat/completions') {
+          let parsed
+          try { parsed = JSON.parse(body.toString('utf8')) }
+          catch { fail(400, 'Invalid JSON request.'); return }
+          const normalized = boundChatOutputTokens(attachRuntimeModelContext(normalizeZeroArgFunctionTools(parsed)))
+          if (normalized !== parsed) body = Buffer.from(JSON.stringify(normalized))
+        }
+      }
+      const upstream = await fetchImpl(endpoint + req.url.slice(3), {
+        method,
+        headers: {
+          authorization: 'Bearer ' + key,
+          accept: 'application/json, text/event-stream',
+          ...(method === 'POST' ? { 'content-type': 'application/json' } : {}),
+        },
+        body,
+        redirect: 'error',
+        signal: abort.signal,
+      })
+      res.writeHead(upstream.status, {
+        'content-type': upstream.headers.get('content-type') ?? 'application/json',
+        'cache-control': 'no-store',
+      })
+      if (upstream.body) {
+        for await (const chunk of upstream.body) {
+          if (res.destroyed) break
+          if (!res.write(chunk)) await waitForDrainOrClose(res)
+        }
+      }
+      res.end()
+    } catch {
+      if (res.headersSent) res.destroy()
+      else fail(502, 'Provider connection failed.')
+    } finally {
+      res.off('close', onClose)
+    }
+  })
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => { server.off('listening', onListening); reject(error) }
+    const onListening = () => { server.off('error', onError); resolve() }
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(0, '127.0.0.1')
+  })
+  const port = server.address()?.port
+  return {
+    token,
+    baseUrl: 'http://127.0.0.1:' + port + '/v1',
+    async close() {
+      server.closeAllConnections()
+      await new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()))
+    },
+  }
+}