@galaxy-yearn/codex-deepseek-gateway 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Galaxy-Yearn
+
+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

@@ -2,10 +2,14 @@
 
 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.
+Codex keeps sending OpenAI `Responses API` requests to a local endpoint. The gateway converts those requests to DeepSeek-compatible `Chat Completions`, calls DeepSeek, then converts the result back to Responses JSON or streaming `response.*` events.
+
+NPM package: [@galaxy-yearn/codex-deepseek-gateway](https://www.npmjs.com/package/@galaxy-yearn/codex-deepseek-gateway)
 
 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.
 
+Use this when you want Codex to stay on its normal Responses API path while the actual model is DeepSeek, including DeepSeek thinking output, function calls, local session resume help, and optional web search emulation through Tavily and Firecrawl.
+
 ## Requirements
 
 - Node.js 20 or newer
@@ -20,81 +24,36 @@ Run:
 npx @galaxy-yearn/codex-deepseek-gateway install
 ```
 
-This copies the gateway to:
+This copies the runtime to:
 
 ```text
 ~/.codex/deepseek-gateway
 ```
 
-It also creates:
+It creates two local config files:
 
 ```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.
-
-### Tavily Web Search
-
-Tavily search is off by default. To let Codex's native `web_search` tool work while the active model is DeepSeek, set these fields in `gateway.local.json`:
+Put your DeepSeek API key in `gateway.local.json`:
 
 ```json
-"tavilyApiKey": "tvly-REPLACE_ME",
-"tavilyWebSearchEnabled": true
+"upstreamApiKey": "sk-..."
 ```
 
-Codex does not need MCP, a different tool name, or any prompt changes. It can keep sending the normal Responses `web_search` or `web_search_preview` tool. The gateway converts that request to an internal `tavily_search` function for DeepSeek, calls Tavily, then maps the result back to Responses-style output.
+`model-aliases.json` controls the gateway-facing model IDs exposed on `GET /v1/models` and used by the `sessions` picker. Edit it only if you want to add or rename model aliases.
 
-The compatibility is two-sided:
-
-- Codex sees `web_search_call` items and final assistant messages in the Responses format.
-- DeepSeek sees a normal Chat Completions function tool named `tavily_search`.
-- If Codex replays prior `web_search_call` items as conversation state, the gateway keeps them as Responses search records instead of sending broken, unpaired Chat tool calls upstream.
-
-Codex receives:
-
-- `web_search_call` output items
-- final assistant `message` items
-- streaming `response.output_text.annotation.added` events for URL citations when the final text contains a matching source marker
-- final `url_citation` annotations on matching cited source markers
-- `web_search_call.action.sources` only when the request includes `include: ["web_search_call.action.sources"]`
-
-DeepSeek receives a compact text summary it can read directly:
-
-- the search query
-- an optional Tavily answer summary
-- numbered sources
-- each source's title, URL, optional date, relevance score, and snippet
-
-The gateway does not pass Tavily's raw response object, raw page content, images, or extra Tavily-only fields to DeepSeek. Tavily is called with `include_raw_content: false`. The model is also told not to write Markdown links or raw URLs in the final answer; URL data is carried through Responses citation annotations when the client supports rendering them.
-
-If the key is already configured, `install` also starts the gateway. If this is your first install, run `start` after adding the key:
+If the key is already configured, `install` also starts the gateway. If this is your first install, add the key and then run:
 
 ```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:
+Edit `~/.codex/config.toml`:
 
 ```toml
 model_provider = "deepseek-gateway"
@@ -104,35 +63,28 @@ model_supports_reasoning_summaries = true
 model_reasoning_summary = "auto"
 
 [model_providers.deepseek-gateway]
-name = "DeepSeekGateway"
+name = "DeepSeek"
 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"`
+Restart Codex after changing `config.toml`.
 
-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.
+## Start And Verify
 
-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.
+Start, stop, and inspect the local background process:
 
-Restart Codex after changing `config.toml`.
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway start
+npx @galaxy-yearn/codex-deepseek-gateway stop
+npx @galaxy-yearn/codex-deepseek-gateway status
+```
 
-## Verify
+`status` should show `"reachable": true`.
 
-Run:
+Run `doctor` to check the active Codex config and the DeepSeek request shape the gateway will send:
 
 ```sh
 npx @galaxy-yearn/codex-deepseek-gateway doctor
@@ -141,29 +93,43 @@ npx @galaxy-yearn/codex-deepseek-gateway doctor
 Important fields:
 
 - `codexConfigUsingGateway` should be `true`
-- `codexModel` should be your DeepSeek model, for example `deepseek-v4-pro`
+- `codexModel` should be your gateway 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
-- `tavilyWebSearchReady` should be `true` if you want Codex `web_search` to route through Tavily
+- `tavilyWebSearchReady` and `firecrawlWebFetchReady` show whether optional web search backends are usable
 
-For example, with:
+Avoid running Codex through a proxy while using the local gateway. Some proxy clients intercept `http://127.0.0.1:3000` and can break local gateway requests.
 
-```toml
-model_reasoning_effort = "xhigh"
+## Models
+
+The installed `config/model-aliases.json` starts with:
+
+```json
+{
+  "deepseek-v4-flash": {
+    "model": "deepseek-v4-flash",
+    "thinking": "auto"
+  },
+  "deepseek-v4-pro": {
+    "model": "deepseek-v4-pro",
+    "thinking": "auto"
+  }
+}
 ```
 
-`doctor` should show:
+The gateway serves these aliases directly on `GET /v1/models`. If you also want to merge DeepSeek's upstream `/models` list, set this in `gateway.local.json`:
 
 ```json
-"deepseekThinking": { "type": "enabled" },
-"deepseekReasoningEffort": "max"
+"fetchUpstreamModels": true
 ```
 
-## Reasoning Mapping
+Whether Codex TUI `/model` shows custom provider models depends on the Codex client build. `config.toml` and the `sessions` command remain the reliable ways to choose a model.
+
+## Reasoning
+
+Codex reasoning effort maps to DeepSeek V4 thinking mode:
 
 | Codex `model_reasoning_effort` | DeepSeek request |
 | --- | --- |
@@ -172,11 +138,73 @@ model_reasoning_effort = "xhigh"
 | `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:
+`model_supports_reasoning_summaries = true` and `model_reasoning_summary = "auto"` tell Codex to use its normal thinking UI path. When DeepSeek returns `reasoning_content`, the gateway keeps the raw text as `reasoning_text` and mirrors it into `summary_text` with a `Reasoning` heading for Codex TUI compatibility.
+
+When thinking is enabled, the gateway intentionally buffers visible assistant text and tool-call output until the upstream response completes, then emits reasoning first. This improves thinking order in Codex at the cost of higher first-token latency.
 
-- `reasoning_summary_text.delta` for Codex's native summary-style thinking UI
+## Web Search
 
-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.
+Web search is off by default. To let Codex's native `web_search` or `web_search_preview` tool work while DeepSeek is active, configure the optional backends in `gateway.local.json`.
+
+Tavily provides search results:
+
+```json
+"tavilyApiKey": "tvly-...",
+"tavilyWebSearchEnabled": true
+```
+
+Firecrawl provides opened-page reading and focused page lookup:
+
+```json
+"firecrawlApiKey": "fc-...",
+"firecrawlWebFetchEnabled": true,
+"firecrawlAutoScrapeTopResults": 3
+```
+
+Codex does not need MCP, a different tool name, or prompt changes. The gateway converts Codex web search requests into internal Chat Completions tools:
+
+- `tavily_search` searches the web and returns citation-ready snippets.
+- `firecrawl_open_page` reads a specific public page.
+- `firecrawl_find_in_page` reads a page with a focused query.
+
+DeepSeek receives compact text context containing the search query, sources, snippets, and optional opened-page excerpts. Codex receives Responses-compatible `web_search_call` items, final assistant messages, and URL citation annotations when the final text cites a matching source marker.
+
+The web payload is intentionally text-focused. Tavily is called with `include_raw_content: false`; Firecrawl defaults to main content, removes base64 images, rejects local/private URLs, and truncates page text before it reaches the model.
+
+## Sessions
+
+Open a cross-provider session picker from a project:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway sessions
+```
+
+The picker is read-only. It scans Codex local transcript files, lists sessions for the current project across providers, then runs:
+
+```sh
+codex resume <session-id> -c model_provider=deepseek-gateway -c model=<model> -c model_reasoning_effort=<effort>
+```
+
+Flow:
+
+- choose a model from `~/.codex/deepseek-gateway/config/model-aliases.json`
+- choose Codex reasoning effort
+- choose the session to resume
+- use `Up/Down` to select, `Enter` to confirm, `Left` to go back, and `Esc` to quit
+
+Print copyable resume commands instead of opening the picker:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway sessions --print
+```
+
+Include sessions outside the current project:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway sessions --all
+```
+
+The command does not edit session files, change provider ownership, or change Codex's native resume picker filters. It only helps you find the hidden session id and resume it with explicit config overrides.
 
 ## Commands
 
@@ -186,6 +214,7 @@ 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 sessions
 npx @galaxy-yearn/codex-deepseek-gateway uninstall
 ```
 
@@ -200,47 +229,23 @@ If `start` returns without visible output on your terminal, run `status`; `"reac
 - 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
-- Codex `web_search` emulation through Tavily when `tavilyWebSearchEnabled` is true and `tavilyApiKey` is configured, with Responses-style `web_search_call` output and compact source snippets for DeepSeek
-- Responses-style URL citation metadata for Tavily-backed answers when the final text contains matching source markers
 - 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
+- `GET /v1/models` with local model aliases and optional upstream discovery
+- optional Tavily/Firecrawl-backed `web_search` emulation
+- read-only cross-provider session picker
 
 ## Limits
 
 Chat Completions is not a full Responses API replacement. Some Responses features have no equivalent upstream field.
 
-- Hosted tools such as file search, computer use, image generation, and code interpreter are represented as function-tool shims unless Codex executes matching tools locally. Web search is the only hosted tool the gateway can emulate directly, and only when Tavily is configured.
-- Tavily search emulation is intentionally narrow. It uses Tavily Search results for text web lookup; it does not expose Tavily extract/crawl/map, raw page content, images, or other Tavily-specific capabilities through Codex `web_search`.
+- Hosted tools such as file search, computer use, image generation, and code interpreter are represented as function-tool shims unless Codex executes matching tools locally. Web search is the only hosted tool the gateway can emulate directly.
+- Tavily and Firecrawl web emulation is text-focused. It does not expose raw HTML, screenshots, browser actions, crawl/map jobs, cookies, private network access, or provider-specific payloads through Codex `web_search`.
 - URL citations are returned in the Responses metadata path. Whether they appear as clickable links in the terminal depends on the Codex client build and how it renders custom-provider citation annotations.
 - 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
+## License
 
-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
-```
+MIT. See [LICENSE](LICENSE).

package/bin/codex-deepseek-gateway.js

@@ -13,6 +13,7 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig } from '../src/config.js';
+import { sessions } from '../src/codex-sessions.js';
 import { toProviderChatCompletionsRequest } from '../src/protocol.js';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -32,16 +33,25 @@ Usage:
   codex-deepseek-gateway stop
   codex-deepseek-gateway status
   codex-deepseek-gateway doctor
+  codex-deepseek-gateway sessions
   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
+  --all            With sessions, include sessions outside the current project
+  --provider <id>  With sessions, target model_provider override
+  --model <id>     With sessions, target model override
+  --reasoning-effort <level>
+                  With sessions, target Codex reasoning effort
+  --exec <id>      With sessions, run the generated codex resume command
+  --limit <n>      With sessions, max rows to print, defaults to 20
+  --print          With sessions, print copyable resume commands instead of picker
 `);
 }
 
 function parseArgs(argv) {
-  const options = { dir: defaultInstallDir(), noEdit: false };
+  const options = { dir: defaultInstallDir(), noEdit: false, all: false };
   const rest = [];
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
@@ -52,6 +62,35 @@ function parseArgs(argv) {
       index += 1;
     } else if (arg === '--no-edit' || arg === '-NoEdit') {
       options.noEdit = true;
+    } else if (arg === '--all') {
+      options.all = true;
+    } else if (arg === '--provider') {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${arg} requires a provider id`);
+      options.provider = value;
+      index += 1;
+    } else if (arg === '--model' || arg === '-m') {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${arg} requires a model id`);
+      options.model = value;
+      index += 1;
+    } else if (arg === '--reasoning-effort') {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${arg} requires a reasoning effort`);
+      options.reasoningEffort = value;
+      index += 1;
+    } else if (arg === '--exec') {
+      const value = argv[index + 1];
+      if (!value) throw new Error(`${arg} requires a session id`);
+      options.exec = value;
+      index += 1;
+    } else if (arg === '--limit') {
+      const value = Number(argv[index + 1]);
+      if (!Number.isInteger(value) || value < 1) throw new Error(`${arg} requires a positive integer`);
+      options.limit = value;
+      index += 1;
+    } else if (arg === '--print') {
+      options.print = true;
     } else {
       rest.push(arg);
     }
@@ -345,9 +384,10 @@ async function doctor(options) {
     codexSummaryConfigured,
     tavilyWebSearchEnabled: Boolean(config.tavilyWebSearchEnabled),
     tavilyWebSearchReady: Boolean(config.tavilyWebSearchEnabled && config.tavilyApiKey),
-    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.',
-    tavilyWebSearchHint: 'Set tavilyApiKey in gateway.local.json to route Codex web_search tools through Tavily while using DeepSeek.',
-    modelDiscoveryHint: 'The gateway exposes model aliases on /v1/models. Whether Codex TUI /model shows them depends on the Codex build.',
+    firecrawlWebFetchEnabled: Boolean(config.firecrawlWebFetchEnabled),
+    firecrawlWebFetchReady: Boolean(config.firecrawlWebFetchEnabled && config.firecrawlApiKey),
+    firecrawlAutoScrapeTopResults: config.firecrawlAutoScrapeTopResults,
+    hint: 'The gateway exposes model aliases on /v1/models. Whether Codex TUI /model shows them depends on the Codex build.',
   }, null, 2));
   print('\n');
 }
@@ -364,7 +404,7 @@ async function main() {
     usage();
     return;
   }
-  const commands = { install, start, stop, status, doctor, uninstall };
+  const commands = { install, start, stop, status, doctor, sessions, uninstall };
   const handler = commands[command];
   if (!handler) {
     throw new Error(`Unknown command: ${command}`);

package/config/gateway.example.json

@@ -11,6 +11,11 @@
   "tavilyMaxResults": 5,
   "tavilyMaxSearchRounds": 2,
   "tavilyTimeoutMs": 15000,
+  "firecrawlApiKey": "",
+  "firecrawlWebFetchEnabled": false,
+  "firecrawlAutoScrapeTopResults": 3,
+  "firecrawlPageMaxChars": 5000,
+  "firecrawlTimeoutMs": 30000,
   "fetchUpstreamModels": false,
   "modelsTimeoutMs": 5000,
   "modelsCacheMs": 60000,

package/package.json

@@ -1,17 +1,19 @@
 {
   "name": "@galaxy-yearn/codex-deepseek-gateway",
-  "version": "0.1.1",
-  "description": "Local Codex Responses API to DeepSeek Chat Completions gateway.",
+  "version": "0.1.3",
+  "description": "Local OpenAI Codex Responses API gateway for DeepSeek Chat Completions.",
   "type": "module",
   "main": "src/server.js",
   "bin": {
     "codex-deepseek-gateway": "bin/codex-deepseek-gateway.js"
   },
   "files": [
-    "bin",
-    "config",
+    "bin/codex-deepseek-gateway.js",
+    "config/gateway.example.json",
+    "config/model-aliases.example.json",
     "src",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node --test"
@@ -25,9 +27,28 @@
     "openai",
     "responses-api",
     "chat-completions",
-    "gateway"
+    "gateway",
+    "proxy",
+    "codex-cli",
+    "openai-responses",
+    "deepseek-v4",
+    "deepseek-v4-flash",
+    "deepseek-v4-pro",
+    "function-calling",
+    "tool-calls",
+    "web-search",
+    "tavily",
+    "firecrawl"
   ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Galaxy-Yearn/codex-deepseek-gateway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Galaxy-Yearn/codex-deepseek-gateway/issues"
+  },
+  "homepage": "https://github.com/Galaxy-Yearn/codex-deepseek-gateway#readme",
   "publishConfig": {
     "access": "public"
   }