@galaxy-yearn/codex-deepseek-gateway 0.1.0

package/README.md

@@ -0,0 +1,207 @@
+# Codex DeepSeek Gateway
+
+A small local gateway for using DeepSeek V4 models from Codex.
+
+Codex sends OpenAI `Responses API` requests to the local gateway. The gateway converts them to DeepSeek-compatible `Chat Completions`, calls DeepSeek, then converts the answer back to Responses objects or streaming `response.*` events.
+
+The runtime uses only the Node.js standard library. It installs under `~/.codex/deepseek-gateway`, runs as a detached background process, and does not edit your existing Codex config.
+
+## Requirements
+
+- Node.js 20 or newer
+- A DeepSeek API key
+- Codex configured from `~/.codex/config.toml`
+
+## Install
+
+Run:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway install
+```
+
+This copies the gateway to:
+
+```text
+~/.codex/deepseek-gateway
+```
+
+It also creates:
+
+```text
+~/.codex/deepseek-gateway/config/gateway.local.json
+```
+
+Open that file and replace `sk-REPLACE_ME` with your DeepSeek API key.
+
+The install also creates:
+
+```text
+~/.codex/deepseek-gateway/config/model-aliases.json
+```
+
+That file controls which model IDs the gateway exposes on `GET /v1/models`. You only need to edit it if you want to add or rename gateway-facing model aliases.
+
+By default, the gateway serves the local alias list directly. If you also want to merge DeepSeek's upstream `/models` list, set `"fetchUpstreamModels": true` in `gateway.local.json`. Leaving it `false` keeps `/v1/models` lighter and more predictable.
+
+If the key is already configured, `install` also starts the gateway. If this is your first install, run `start` after adding the key:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway start
+```
+
+Check that it is running:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway status
+```
+
+You should see `"reachable": true`.
+
+## Configure Codex
+
+Edit `~/.codex/config.toml` and set the active provider to the gateway:
+
+```toml
+model_provider = "deepseek-gateway"
+model = "deepseek-v4-flash"
+model_reasoning_effort = "low"
+model_supports_reasoning_summaries = true
+model_reasoning_summary = "auto"
+
+[model_providers.deepseek-gateway]
+name = "DeepSeekGateway"
+base_url = "http://127.0.0.1:3000/v1"
+wire_api = "responses"
+```
+
+Use `deepseek-v4-pro` instead of `deepseek-v4-flash` if you want the pro model.
+
+`config.toml` can change:
+
+- the active provider via `model_provider`
+- the active model ID via `model`
+- the provider label via `[model_providers.<id>].name`
+
+It does not define a separate display name for each model entry inside Codex `/model`. If your Codex build reads custom provider models from `/v1/models`, the visible model names come from the gateway's model IDs in `~/.codex/deepseek-gateway/config/model-aliases.json`.
+
+These reasoning settings do different jobs:
+
+- `model_supports_reasoning_summaries = true`
+- `model_reasoning_summary = "auto"`
+
+These tell Codex to use its normal thinking UI path. When DeepSeek returns `reasoning_content`, the gateway maps it into that path while thinking is enabled. It keeps the raw text as `reasoning_text` and sends a display-safe `summary_text` version with a small heading and common Markdown markers removed, because Codex TUI renders reasoning summaries as plain summary blocks.
+
+When DeepSeek thinking is enabled, the gateway buffers visible assistant text and tool-call output until the upstream response completes. It then flushes collected reasoning before the answer/tool calls through one summary part streamed as small deltas. The tradeoff is higher first-token latency while thinking is on.
+
+Restart Codex after changing `config.toml`.
+
+## Verify
+
+Run:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway doctor
+```
+
+Important fields:
+
+- `codexConfigUsingGateway` should be `true`
+- `codexModel` should be your DeepSeek model, for example `deepseek-v4-pro`
+- `codexReasoningEffort` should match `model_reasoning_effort`
+- `deepseekThinking` shows the DeepSeek `thinking` payload
+- `deepseekReasoningEffort` shows the DeepSeek effort sent upstream
+- `reasoningDisplayMode` shows whether the gateway will emit `summary`, `disabled`, or `hidden`
+- `gatewayEmitsReasoningSummary` should be `true` when DeepSeek thinking is enabled
+- `codexSummaryConfigured` should be `true` so Codex TUI is configured to show summaries
+
+For example, with:
+
+```toml
+model_reasoning_effort = "xhigh"
+```
+
+`doctor` should show:
+
+```json
+"deepseekThinking": { "type": "enabled" },
+"deepseekReasoningEffort": "max"
+```
+
+## Reasoning Mapping
+
+| Codex `model_reasoning_effort` | DeepSeek request |
+| --- | --- |
+| `low` | `thinking.type = disabled` |
+| `medium` | `thinking.type = enabled`, `reasoning_effort = high` |
+| `high` | `thinking.type = enabled`, `reasoning_effort = high` |
+| `xhigh` | `thinking.type = enabled`, `reasoning_effort = max` |
+
+When thinking is enabled, every non-empty DeepSeek streaming `reasoning_content` chunk is collected and converted into Responses reasoning events:
+
+- `reasoning_summary_text.delta` for Codex's native summary-style thinking UI
+
+The completed response keeps the original DeepSeek text as `reasoning_text`. The visible summary path uses a plain-text rendering of the same text with common Markdown markers removed and a `Reasoning` heading for Codex TUI compatibility. When thinking is enabled, the gateway holds back visible answer/tool output until completion so the reasoning block can land first and stay contiguous.
+
+## Commands
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway install
+npx @galaxy-yearn/codex-deepseek-gateway start
+npx @galaxy-yearn/codex-deepseek-gateway stop
+npx @galaxy-yearn/codex-deepseek-gateway status
+npx @galaxy-yearn/codex-deepseek-gateway doctor
+npx @galaxy-yearn/codex-deepseek-gateway uninstall
+```
+
+`start` launches a headless background Node.js process. `stop` stops it. `uninstall` stops the gateway and removes `~/.codex/deepseek-gateway`, but it does not edit `~/.codex/config.toml`.
+
+If `start` returns without visible output on your terminal, run `status`; `"reachable": true` is the source of truth.
+
+## What Works
+
+- Codex `POST /v1/responses`
+- streaming and non-streaming responses
+- text input and output
+- image, file, and audio content parts when DeepSeek accepts the corresponding Chat Completions shape
+- function tools and tool-call history
+- conservative schema-based repair for streamed and non-streamed tool arguments where DeepSeek returns stringified JSON values for fields that Codex declared as arrays, objects, booleans, or numbers
+- DeepSeek thinking mode and `reasoning_content`
+- lightweight local `previous_response_id` / `conversation` history while the gateway process is running
+- `GET /v1/models` with local DeepSeek V4 aliases and optional upstream discovery
+
+## Limits
+
+Chat Completions is not a full Responses API replacement. Some Responses features have no equivalent upstream field.
+
+- Hosted tools such as web search, file search, computer use, image generation, and code interpreter are represented as function-tool shims unless Codex executes matching tools locally.
+- OpenAI `file_id` values are passed through; the gateway cannot fetch private OpenAI-hosted files.
+- In-memory conversation history is lost when the gateway restarts.
+- The gateway exposes model aliases on `/v1/models`, including aliases from `config/model-aliases.json`. Whether Codex TUI `/model` actually shows custom provider models depends on the Codex build. `config.toml` remains the reliable fallback.
+
+## Local Testing Before Publish
+
+From this repository:
+
+```sh
+npm test
+npm pack
+npx --yes --package ./<generated-tarball>.tgz codex-deepseek-gateway install --no-edit
+npx --yes --package ./<generated-tarball>.tgz codex-deepseek-gateway status
+npx --yes --package ./<generated-tarball>.tgz codex-deepseek-gateway doctor
+```
+
+Replace `<generated-tarball>.tgz` with the filename printed by `npm pack`.
+
+For published usage, use the shorter package command shown in the install section.
+
+## Publish
+
+When ready:
+
+```sh
+npm login
+npm test
+npm pack --dry-run
+npm publish
+```

package/bin/codex-deepseek-gateway.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+import { execFileSync, spawn } from 'node:child_process';
+import {
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadConfig } from '../src/config.js';
+import { toProviderChatCompletionsRequest } from '../src/protocol.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+
+function print(message = '') {
+  process.stdout.write(message);
+}
+
+function usage() {
+  print(`Codex DeepSeek Gateway
+
+Usage:
+  codex-deepseek-gateway install
+  codex-deepseek-gateway start
+  codex-deepseek-gateway stop
+  codex-deepseek-gateway status
+  codex-deepseek-gateway doctor
+  codex-deepseek-gateway uninstall
+
+Options:
+  --dir <path>     Install directory, defaults to ~/.codex/deepseek-gateway
+  --no-edit        Do not open the local config file after install
+`);
+}
+
+function parseArgs(argv) {
+  const options = { dir: defaultInstallDir(), noEdit: false };
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--dir' || arg === '-d' || arg === '-InstallDir') {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${arg} requires a path`);
+      options.dir = resolve(value);
+      index += 1;
+    } else if (arg === '--no-edit' || arg === '-NoEdit') {
+      options.noEdit = true;
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { command: rest[0], options };
+}
+
+function defaultInstallDir() {
+  const home = process.env.CODEX_HOME || join(process.env.USERPROFILE || process.env.HOME || process.cwd(), '.codex');
+  return join(home, 'deepseek-gateway');
+}
+
+function configPath(installDir) {
+  return join(installDir, 'config', 'gateway.local.json');
+}
+
+function pidPath(installDir) {
+  return join(installDir, 'gateway.pid');
+}
+
+function serverPath(installDir) {
+  return join(installDir, 'src', 'server.js');
+}
+
+function loadInstalledConfig(installDir) {
+  return loadConfig({ ...process.env, GATEWAY_CONFIG_FILE: configPath(installDir) });
+}
+
+function endpoint(config, path = '') {
+  return `http://${config.host}:${config.port}${path}`;
+}
+
+function isConfigured(installDir) {
+  if (!existsSync(configPath(installDir))) return false;
+  const config = loadInstalledConfig(installDir);
+  return Boolean(config.upstreamApiKey);
+}
+
+async function health(config) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 1500);
+  try {
+    const response = await fetch(endpoint(config, '/health'), { signal: controller.signal });
+    if (!response.ok) return null;
+    return await response.json();
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function processExists(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function killProcess(pid) {
+  if (!pid || pid === process.pid) return;
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('taskkill.exe', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    } else {
+      process.kill(pid);
+    }
+  } catch {
+  }
+}
+
+function findWindowsPidOnPort(port) {
+  if (process.platform !== 'win32') return 0;
+  try {
+    const output = execFileSync('netstat.exe', ['-ano', '-p', 'tcp'], { encoding: 'utf8', windowsHide: true });
+    const escapedPort = String(port).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`(?:127\\.0\\.0\\.1|0\\.0\\.0\\.0|\\[::1\\]|\\[::\\]):${escapedPort}\\s+[^\\s]+\\s+LISTENING\\s+(\\d+)`, 'i');
+    for (const line of output.split(/\r?\n/)) {
+      const match = line.match(pattern);
+      if (match) return Number(match[1]) || 0;
+    }
+  } catch {
+  }
+  return 0;
+}
+
+function processCommandLine(pid) {
+  if (process.platform !== 'win32' || !pid) return '';
+  try {
+    const output = execFileSync(
+      'wmic.exe',
+      ['process', 'where', `ProcessId=${pid}`, 'get', 'CommandLine', '/value'],
+      { encoding: 'utf8', windowsHide: true },
+    );
+    const match = output.match(/CommandLine=(.*)/s);
+    return match ? match[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+function readPid(installDir) {
+  try {
+    return Number(readFileSync(pidPath(installDir), 'utf8').trim()) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+function copyRuntime(installDir) {
+  mkdirSync(join(installDir, 'bin'), { recursive: true });
+  mkdirSync(join(installDir, 'src'), { recursive: true });
+  mkdirSync(join(installDir, 'config'), { recursive: true });
+  copyFileSync(join(ROOT, 'package.json'), join(installDir, 'package.json'));
+  rmSync(join(installDir, 'bin'), { recursive: true, force: true });
+  rmSync(join(installDir, 'src'), { recursive: true, force: true });
+  cpSync(join(ROOT, 'bin'), join(installDir, 'bin'), { recursive: true });
+  cpSync(join(ROOT, 'src'), join(installDir, 'src'), { recursive: true });
+  const modelAliasesConfig = join(installDir, 'config', 'model-aliases.json');
+  if (!existsSync(modelAliasesConfig)) {
+    copyFileSync(join(ROOT, 'config', 'model-aliases.example.json'), modelAliasesConfig);
+  }
+  const localConfig = configPath(installDir);
+  if (!existsSync(localConfig)) {
+    copyFileSync(join(ROOT, 'config', 'gateway.example.json'), localConfig);
+  }
+}
+
+function openConfig(file) {
+  const opener =
+    process.platform === 'win32'
+      ? ['notepad.exe', [file]]
+      : process.platform === 'darwin'
+      ? ['open', [file]]
+      : ['xdg-open', [file]];
+  try {
+    const child = spawn(opener[0], opener[1], { detached: true, stdio: 'ignore' });
+    child.on('error', () => print(`Edit config: ${file}\n`));
+    child.unref();
+  } catch {
+    print(`Edit config: ${file}\n`);
+  }
+}
+
+async function install(options) {
+  copyRuntime(options.dir);
+  print(`Installed to ${options.dir}\n`);
+  if (!isConfigured(options.dir)) {
+    print(`Edit this file and put your DeepSeek API key:\n  ${configPath(options.dir)}\n`);
+    if (!options.noEdit) openConfig(configPath(options.dir));
+    return;
+  }
+  await start(options);
+}
+
+async function start(options) {
+  if (!existsSync(serverPath(options.dir))) {
+    throw new Error(`Missing runtime at ${options.dir}. Run install first.`);
+  }
+  if (!isConfigured(options.dir)) {
+    throw new Error(`Missing DeepSeek API key in ${configPath(options.dir)} or DEEPSEEK_API_KEY`);
+  }
+  const config = loadInstalledConfig(options.dir);
+  const currentHealth = await health(config);
+  if (currentHealth?.ok) {
+    const pid = readPid(options.dir);
+    const message = processExists(pid)
+      ? 'Gateway is already running.\n'
+      : `Gateway is already reachable at ${endpoint(config)}. Another install may already be running.\n`;
+    print(message);
+    return;
+  }
+
+  mkdirSync(options.dir, { recursive: true });
+  const out = 'ignore';
+  print(`Starting gateway on ${endpoint(config)} ...\n`);
+  const child = spawn(process.execPath, [serverPath(options.dir)], {
+    cwd: options.dir,
+    detached: true,
+    stdio: ['ignore', out, out],
+    windowsHide: true,
+  });
+  writeFileSync(pidPath(options.dir), String(child.pid));
+  child.unref();
+
+  for (let index = 0; index < 20; index += 1) {
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
+    const ready = await health(config);
+    if (ready?.ok) {
+      print(`Gateway started. PID ${child.pid}\n`);
+      return;
+    }
+  }
+  throw new Error(`Gateway did not become reachable on ${endpoint(config)}`);
+}
+
+async function stop(options) {
+  const config = loadInstalledConfig(options.dir);
+  const pid = readPid(options.dir);
+  const hadManagedPid = processExists(pid);
+  let killedPortProcess = false;
+  if (processExists(pid)) {
+    killProcess(pid);
+    for (let index = 0; index < 20 && processExists(pid); index += 1) {
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, 100));
+    }
+  }
+  const portPid = findWindowsPidOnPort(config.port);
+  if (portPid && portPid !== pid) {
+    const commandLine = processCommandLine(portPid);
+    if (commandLine.includes(serverPath(options.dir))) {
+      killProcess(portPid);
+      killedPortProcess = true;
+      for (let index = 0; index < 20 && processExists(portPid); index += 1) {
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, 100));
+      }
+    }
+  }
+  rmSync(pidPath(options.dir), { force: true });
+  const running = await health(config);
+  if (!running?.ok) {
+    print('Gateway stopped.\n');
+  } else if (!hadManagedPid && !killedPortProcess) {
+    print(`No gateway process is recorded for this install. ${endpoint(config)} is still reachable, likely from another install.\n`);
+  } else {
+    print(`Gateway may still be running on ${endpoint(config)}.\n`);
+  }
+}
+
+async function status(options) {
+  const config = loadInstalledConfig(options.dir);
+  const pid = readPid(options.dir);
+  const running = await health(config);
+  const versionPath = join(options.dir, 'package.json');
+  const installedVersion = existsSync(versionPath) ? JSON.parse(readFileSync(versionPath, 'utf8')).version : '';
+  print(JSON.stringify({
+    installed: existsSync(options.dir),
+    installDir: options.dir,
+    configPath: configPath(options.dir),
+    pid,
+    pidRunning: processExists(pid),
+    reachable: Boolean(running?.ok),
+    url: endpoint(config),
+    version: installedVersion || packageJson.version,
+  }, null, 2));
+  print('\n');
+}
+
+async function doctor(options) {
+  const config = loadInstalledConfig(options.dir);
+  const codexConfigUsingGateway = config.codexModelProvider === 'deepseek-gateway';
+  const model = codexConfigUsingGateway && config.codexModel ? config.codexModel : 'deepseek-v4-pro';
+  const upstreamRequest = toProviderChatCompletionsRequest(
+    {
+      model,
+      messages: [{ role: 'user', content: 'ping' }],
+      stream: true,
+    },
+    config,
+  );
+  const supportsReasoningSummaries = String(config.codexModelSupportsReasoningSummaries).toLowerCase() === 'true';
+  const summaryMode = String(config.codexReasoningSummary || '').toLowerCase();
+  const hideAgentReasoning = String(config.codexHideAgentReasoning).toLowerCase() === 'true';
+  const thinkingEnabled = upstreamRequest.thinking?.type === 'enabled';
+  const reasoningDisplayMode = hideAgentReasoning
+    ? 'hidden'
+    : thinkingEnabled
+    ? 'summary'
+    : 'disabled';
+  const codexSummaryConfigured = supportsReasoningSummaries && summaryMode && summaryMode !== 'none';
+  print(JSON.stringify({
+    packageVersion: packageJson.version,
+    installDir: options.dir,
+    localConfig: configPath(options.dir),
+    codexConfigUsingGateway,
+    codexModelProvider: config.codexModelProvider || null,
+    codexModel: config.codexModel || null,
+    codexReasoningEffort: config.codexReasoningEffort || null,
+    codexReasoningSummary: config.codexReasoningSummary || null,
+    codexModelSupportsReasoningSummaries: config.codexModelSupportsReasoningSummaries || null,
+    codexHideAgentReasoning: config.codexHideAgentReasoning || null,
+    sampleModel: model,
+    upstreamModel: upstreamRequest.model,
+    deepseekThinking: upstreamRequest.thinking || null,
+    deepseekReasoningEffort: upstreamRequest.reasoning_effort || null,
+    reasoningDisplayMode,
+    gatewayEmitsReasoningSummary: reasoningDisplayMode === 'summary',
+    codexSummaryConfigured,
+    reasoningSummaryHint: 'When DeepSeek thinking is enabled, the gateway maps every non-empty reasoning_content chunk into the Responses reasoning summary path. Keep model_supports_reasoning_summaries = true and model_reasoning_summary = "auto" so Codex TUI is configured to show summaries.',
+    modelDiscoveryHint: 'The gateway exposes model aliases on /v1/models. Whether Codex TUI /model shows them depends on the Codex build.',
+  }, null, 2));
+  print('\n');
+}
+
+async function uninstall(options) {
+  await stop(options);
+  rmSync(options.dir, { recursive: true, force: true });
+  print(`Removed ${options.dir}\n`);
+}
+
+async function main() {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (!command || command === '-h' || command === '--help' || command === 'help') {
+    usage();
+    return;
+  }
+  const commands = { install, start, stop, status, doctor, uninstall };
+  const handler = commands[command];
+  if (!handler) {
+    throw new Error(`Unknown command: ${command}`);
+  }
+  await handler(options);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message || error}\n`);
+  process.exit(1);
+});

package/config/gateway.example.json

@@ -0,0 +1,12 @@
+{
+  "port": 3000,
+  "host": "127.0.0.1",
+  "upstreamProvider": "deepseek",
+  "upstreamBaseUrl": "https://api.deepseek.com",
+  "upstreamApiKey": "sk-REPLACE_ME",
+  "upstreamTimeoutMs": 120000,
+  "fetchUpstreamModels": false,
+  "modelsTimeoutMs": 5000,
+  "modelsCacheMs": 60000,
+  "debugPayload": false
+}

package/config/model-aliases.example.json

@@ -0,0 +1,10 @@
+{
+  "deepseek-v4-flash": {
+    "model": "deepseek-v4-flash",
+    "thinking": "auto"
+  },
+  "deepseek-v4-pro": {
+    "model": "deepseek-v4-pro",
+    "thinking": "auto"
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@galaxy-yearn/codex-deepseek-gateway",
+  "version": "0.1.0",
+  "description": "Local Codex Responses API to DeepSeek Chat Completions gateway.",
+  "type": "module",
+  "main": "src/server.js",
+  "bin": {
+    "codex-deepseek-gateway": "bin/codex-deepseek-gateway.js"
+  },
+  "files": [
+    "bin",
+    "config",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "codex",
+    "deepseek",
+    "openai",
+    "responses-api",
+    "chat-completions",
+    "gateway"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}