@galaxy-yearn/codex-deepseek-gateway 0.1.2 → 0.1.4

package/README.md

@@ -1,12 +1,14 @@
 # Codex DeepSeek Gateway
 
-A small local gateway for using DeepSeek V4 models from Codex.
+A small local gateway for using DeepSeek 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 if you want Codex to keep its normal Responses API client path while the actual model is DeepSeek, including DeepSeek thinking output and optional web search emulation through Tavily and Firecrawl.
+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
 
@@ -22,82 +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.
-
-### Web Search
-
-Web search is off by default. To let Codex's native `web_search` tool work while the active model is DeepSeek, configure Tavily in `gateway.local.json`:
+Put your DeepSeek API key in `gateway.local.json`:
 
 ```json
-"tavilyApiKey": "tvly-REPLACE_ME",
-"tavilyWebSearchEnabled": true
+"upstreamApiKey": "sk-..."
 ```
 
-To add opened-page reading after search, also configure Firecrawl:
-
-```json
-"firecrawlApiKey": "fc-REPLACE_ME",
-"firecrawlWebFetchEnabled": true,
-"firecrawlAutoScrapeTopResults": 3
-```
+`model-aliases.json` controls the gateway-facing model IDs exposed on `GET /v1/models` and used by the `new` and `sessions` pickers. Edit it only if you want to add or rename model aliases.
 
-Codex does not need MCP, a different tool name, or prompt changes. It can keep sending the normal Responses `web_search` or `web_search_preview` tool. The gateway converts that request to internal Chat Completions tools for DeepSeek:
-
-- `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 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
-- optional Firecrawl opened-page title, summary, relevant matches, cleaned markdown excerpt, and page links
-
-Codex receives Responses-compatible `web_search_call` items, final assistant messages, and URL citation annotations when the final text cites a matching source marker. If Codex replays prior `web_search_call` items as conversation state, the gateway preserves them as search records instead of sending broken Chat tool calls upstream.
-
-The gateway does not pass Tavily's raw response object, images, screenshots, or provider-only fields to DeepSeek. Tavily is called with `include_raw_content: false`. Firecrawl returns cleaned page text, defaults to main content, removes base64 images, rejects local/private URLs, and truncates page text before it reaches the model.
-
-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"
@@ -114,23 +70,21 @@ 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`
+Restart Codex after changing `config.toml`.
 
-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`.
+## Start And Verify
 
-`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 a display-safe `summary_text` value for Codex.
+Start, stop, and inspect the local background process:
 
-When DeepSeek thinking is enabled, the gateway buffers visible assistant text and tool-call output until the upstream response completes. It then emits reasoning before the answer or tool calls. The tradeoff is higher first-token latency while thinking is on.
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway start
+npx @galaxy-yearn/codex-deepseek-gateway stop
+npx @galaxy-yearn/codex-deepseek-gateway status
+```
 
-Restart Codex after changing `config.toml`.
+`status` should show `"reachable": true`.
 
-## Verify
-
-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
@@ -139,30 +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
-- `firecrawlWebFetchReady` should be `true` if you want Tavily search results to include opened-page excerpts
+- `reasoningDisplayMode` shows whether reasoning is shown as `summary`, `hidden`, or `disabled`
+- `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`, `new`, and `sessions` remain the reliable ways to choose a model.
+
+## Reasoning
+
+Codex reasoning effort maps to DeepSeek V4 thinking mode:
 
 | Codex `model_reasoning_effort` | DeepSeek request |
 | --- | --- |
@@ -171,11 +138,113 @@ 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 `reasoning_content` value is converted into Responses reasoning output:
+`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.
 
-- `reasoning_summary_text.delta` for Codex's native summary-style thinking UI
+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.
 
-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. This also applies to Tavily/Firecrawl-backed `web_search` turns.
+## Web Search
+
+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.
+
+## New Conversations
+
+Start a new Codex conversation with a temporary gateway model override:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway new
+```
+
+The command first lets you choose a model from `~/.codex/deepseek-gateway/config/model-aliases.json`, then choose Codex reasoning effort, then runs:
+
+```sh
+codex -c model_provider=deepseek-gateway -c model=<model> -c model_reasoning_effort=<effort>
+```
+
+This does not edit `~/.codex/config.toml`; the `model_providers.deepseek-gateway` provider entry still needs to exist there.
+
+You can skip the picker:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway new --model deepseek-v4-flash --reasoning-effort low
+```
+
+Print the generated launch command instead of running Codex:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway new --print
+```
+
+## 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 `[New conversation]` or the session to resume
+- use `↑/↓` to select, `Enter` to confirm, `←` 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
+```
+
+Resume a matching session directly by row number or unique session id prefix:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway sessions --exec <id-or-row>
+```
+
+Limit how many session rows are shown or offered in the picker:
+
+```sh
+npx @galaxy-yearn/codex-deepseek-gateway sessions --limit 50
+```
+
+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
 
@@ -185,6 +254,8 @@ 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 new
+npx @galaxy-yearn/codex-deepseek-gateway sessions
 npx @galaxy-yearn/codex-deepseek-gateway uninstall
 ```
 
@@ -199,48 +270,24 @@ 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
-- Firecrawl-backed opened-page reading for `web_search` when `firecrawlWebFetchEnabled` is true and `firecrawlApiKey` is configured, including automatic top-result scraping plus explicit `open_page` and `find_in_page` internal tool calls
-- 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
+- new-conversation launcher with per-run Codex config overrides
+- 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 and Firecrawl web emulation is intentionally text-focused. It covers search, opened-page excerpts, page links, and find-in-page style matching; it does not expose raw HTML, screenshots, browser actions, crawl/map jobs, cookies, private network access, or provider-specific payloads 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
+- 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`, `new`, and `sessions` remain the reliable ways to choose a model.
 
-From this repository:
+## License
 
-```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,8 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadConfig } from '../src/config.js';
+import { newConversation } from '../src/codex-launch.js';
+import { sessions } from '../src/codex-sessions.js';
 import { toProviderChatCompletionsRequest } from '../src/protocol.js';
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -32,16 +34,27 @@ Usage:
   codex-deepseek-gateway stop
   codex-deepseek-gateway status
   codex-deepseek-gateway doctor
+  codex-deepseek-gateway new
+  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 new/sessions, target model_provider override
+  --model <id>     With new/sessions, target model override
+  --reasoning-effort <level>
+                  With new/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 new, print the launch command. 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 +65,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);
     }
@@ -324,7 +366,6 @@ async function doctor(options) {
     : thinkingEnabled
     ? 'summary'
     : 'disabled';
-  const codexSummaryConfigured = supportsReasoningSummaries && summaryMode && summaryMode !== 'none';
   print(JSON.stringify({
     packageVersion: packageJson.version,
     installDir: options.dir,
@@ -341,17 +382,12 @@ async function doctor(options) {
     deepseekThinking: upstreamRequest.thinking || null,
     deepseekReasoningEffort: upstreamRequest.reasoning_effort || null,
     reasoningDisplayMode,
-    gatewayEmitsReasoningSummary: reasoningDisplayMode === 'summary',
-    codexSummaryConfigured,
     tavilyWebSearchEnabled: Boolean(config.tavilyWebSearchEnabled),
     tavilyWebSearchReady: Boolean(config.tavilyWebSearchEnabled && config.tavilyApiKey),
     firecrawlWebFetchEnabled: Boolean(config.firecrawlWebFetchEnabled),
     firecrawlWebFetchReady: Boolean(config.firecrawlWebFetchEnabled && config.firecrawlApiKey),
     firecrawlAutoScrapeTopResults: config.firecrawlAutoScrapeTopResults,
-    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.',
-    firecrawlWebFetchHint: 'Set firecrawlApiKey and firecrawlWebFetchEnabled in gateway.local.json to add opened-page excerpts to Tavily-backed Codex web_search.',
-    modelDiscoveryHint: 'The gateway exposes model aliases on /v1/models. Whether Codex TUI /model shows them depends on the Codex build.',
+    hint: 'The gateway exposes model aliases on /v1/models. Whether Codex TUI /model shows them depends on the Codex build.',
   }, null, 2));
   print('\n');
 }
@@ -368,7 +404,7 @@ async function main() {
     usage();
     return;
   }
-  const commands = { install, start, stop, status, doctor, uninstall };
+  const commands = { install, start, stop, status, doctor, new: newConversation, sessions, uninstall };
   const handler = commands[command];
   if (!handler) {
     throw new Error(`Unknown command: ${command}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@galaxy-yearn/codex-deepseek-gateway",
-  "version": "0.1.2",
-  "description": "Local Codex Responses API to DeepSeek Chat Completions gateway.",
+  "version": "0.1.4",
+  "description": "Local OpenAI Codex Responses API gateway for DeepSeek Chat Completions.",
   "type": "module",
   "main": "src/server.js",
   "bin": {
@@ -27,7 +27,18 @@
     "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": {

package/src/codex-launch.js

@@ -0,0 +1,233 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { clearScreenDown, cursorTo } from 'node:readline';
+import { readCodexConfig } from './codex-config.js';
+
+export const DEFAULT_PROVIDER = 'deepseek-gateway';
+export const REASONING_EFFORTS = ['low', 'medium', 'high', 'xhigh'];
+const SELECTED_ROW = '\x1b[38;5;81m';
+const RESET_STYLE = '\x1b[0m';
+
+function print(message = '') {
+  process.stdout.write(message);
+}
+
+export function defaultCodexHome() {
+  return process.env.CODEX_HOME || join(process.env.USERPROFILE || process.env.HOME || process.cwd(), '.codex');
+}
+
+export function findProjectRoot(start) {
+  let current = resolve(start);
+  while (true) {
+    if (existsSync(join(current, '.git'))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(start);
+    current = parent;
+  }
+}
+
+function readJsonObject(file) {
+  if (!existsSync(file)) return {};
+  const value = JSON.parse(readFileSync(file, 'utf8'));
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+export function gatewayModels(installDir) {
+  return Object.keys(readJsonObject(join(installDir, 'config', 'model-aliases.json'))).sort();
+}
+
+export function createLaunchContext(options) {
+  const codexHome = defaultCodexHome();
+  const models = gatewayModels(options.dir);
+  const codexConfig = readCodexConfig();
+  const configModel = codexConfig.modelProvider === DEFAULT_PROVIDER && models.includes(codexConfig.model) ? codexConfig.model : '';
+  return {
+    all: options.all,
+    codexHome,
+    installDir: options.dir,
+    models,
+    projectRoot: findProjectRoot(process.cwd()),
+    provider: options.provider || DEFAULT_PROVIDER,
+    model: options.model || configModel || models[0] || '',
+    reasoningEffort: options.reasoningEffort || codexConfig.modelReasoningEffort || 'low',
+  };
+}
+
+export function missingModelMessage(context) {
+  return `No gateway models found in ${join(context.installDir, 'config', 'model-aliases.json')}\n`;
+}
+
+function configOverrideArgs(context) {
+  return [
+    '-c',
+    `model_provider=${JSON.stringify(context.provider)}`,
+    '-c',
+    `model=${JSON.stringify(context.model)}`,
+    '-c',
+    `model_reasoning_effort=${JSON.stringify(context.reasoningEffort)}`,
+  ];
+}
+
+function configOverrideCommandParts(context) {
+  return [
+    '-c',
+    `model_provider=${context.provider}`,
+    '-c',
+    `model=${context.model}`,
+    '-c',
+    `model_reasoning_effort=${context.reasoningEffort}`,
+  ];
+}
+
+export function codexNewArgs(context) {
+  return configOverrideArgs(context);
+}
+
+export function codexResumeArgs(sessionId, context) {
+  return ['resume', sessionId, ...configOverrideArgs(context)];
+}
+
+export function codexNewCommand(context) {
+  return ['codex', ...configOverrideCommandParts(context)].join(' ');
+}
+
+export function codexResumeCommand(sessionId, context) {
+  return ['codex', 'resume', sessionId, ...configOverrideCommandParts(context)].join(' ');
+}
+
+export async function runCodex(args) {
+  const child = spawn('codex', args, {
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  });
+  process.exitCode = await new Promise((resolveChild) => {
+    child.on('exit', (exitCode) => resolveChild(exitCode ?? 0));
+  });
+}
+
+function rowOffset(header) {
+  return header ? 4 : 2;
+}
+
+function renderRow(state, index) {
+  cursorTo(process.stdout, 0, rowOffset(state.header) + index);
+  const row = `${index === state.selected ? '>' : ' '} ${state.rows[index]}`;
+  const styled = index === state.selected ? `${SELECTED_ROW}${row}${RESET_STYLE}` : row;
+  print(`\x1b[2K${styled}`);
+}
+
+function renderPicker(state) {
+  const { title, rows, selected, header } = state;
+  cursorTo(process.stdout, 0, 0);
+  clearScreenDown(process.stdout);
+  let output = `${title}\n\n`;
+  if (header) output += `  ${header}\n  ${'-'.repeat(header.length)}\n`;
+  for (const [index] of rows.entries()) {
+    const row = `${index === selected ? '>' : ' '} ${rows[index]}`;
+    output += `${index === selected ? `${SELECTED_ROW}${row}${RESET_STYLE}` : row}\n`;
+  }
+  output += '\n↑/↓ select  Enter confirm  ← back  Esc quit\n';
+  print(output);
+}
+
+function openPickerScreen() {
+  process.stdout.write('\x1b[?1049h\x1b[?25l');
+}
+
+function closePickerScreen() {
+  process.stdout.write('\x1b[?25h\x1b[?1049l');
+}
+
+export async function pick(title, rows, header = '') {
+  if (!rows.length) return { action: 'back' };
+  let selected = 0;
+  const stdin = process.stdin;
+  const state = { title, rows, selected, header };
+  renderPicker(state);
+
+  return await new Promise((resolvePick) => {
+    const done = (result) => {
+      stdin.off('data', onData);
+      resolvePick(result);
+    };
+    const onData = (chunk) => {
+      const key = chunk.toString('utf8');
+      if (key === '\u0003' || key === '\u001b') return done({ action: 'cancel' });
+      if (key === '\u001b[D') return done({ action: 'back' });
+      if (key === '\r' || key === '\n') return done({ action: 'select', index: selected });
+      const previous = selected;
+      if (key === '\u001b[A') selected = Math.max(0, selected - 1);
+      else if (key === '\u001b[B') selected = Math.min(rows.length - 1, selected + 1);
+      else return;
+      if (selected === previous) return;
+      state.selected = selected;
+      renderRow(state, previous);
+      renderRow(state, selected);
+    };
+    stdin.on('data', onData);
+  });
+}
+
+export async function withPickerScreen(callback) {
+  const stdin = process.stdin;
+  stdin.resume();
+  stdin.setRawMode(true);
+  openPickerScreen();
+  try {
+    return await callback();
+  } finally {
+    stdin.setRawMode(false);
+    stdin.pause();
+    closePickerScreen();
+  }
+}
+
+export async function pickModel(context) {
+  const result = await pick('Choose gateway model', context.models);
+  if (result.action === 'select') context.model = context.models[result.index];
+  return result.action;
+}
+
+export async function pickReasoning(context) {
+  const result = await pick(`Choose Codex reasoning effort for ${context.model}`, REASONING_EFFORTS);
+  if (result.action === 'select') context.reasoningEffort = REASONING_EFFORTS[result.index];
+  return result.action;
+}
+
+export async function chooseLaunchContext(context) {
+  return await withPickerScreen(async () => {
+    let step = 'model';
+    while (true) {
+      if (step === 'model') {
+        const action = await pickModel(context);
+        if (action !== 'select') return false;
+        step = 'reasoning';
+      } else {
+        const action = await pickReasoning(context);
+        if (action === 'cancel') return false;
+        if (action === 'back') step = 'model';
+        else return true;
+      }
+    }
+  });
+}
+
+export async function newConversation(options) {
+  const context = createLaunchContext(options);
+  if (!context.model) {
+    print(missingModelMessage(context));
+    return;
+  }
+  const canPick = process.stdin.isTTY && process.stdout.isTTY;
+  const hasLaunchOverrides = options.provider || options.model || options.reasoningEffort;
+  if (!hasLaunchOverrides && !options.print && canPick) {
+    const selected = await chooseLaunchContext(context);
+    if (!selected) return;
+  }
+  if (options.print || (!hasLaunchOverrides && !canPick)) {
+    print(`${codexNewCommand(context)}\n`);
+    return;
+  }
+  await runCodex(codexNewArgs(context));
+}

package/src/codex-sessions.js

@@ -0,0 +1,235 @@
+import {
+  closeSync,
+  existsSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  readSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  codexNewArgs,
+  codexResumeArgs,
+  codexResumeCommand,
+  createLaunchContext,
+  missingModelMessage,
+  pick,
+  pickModel,
+  pickReasoning,
+  runCodex,
+  withPickerScreen,
+} from './codex-launch.js';
+
+const TIME_WIDTH = 10;
+const PROVIDER_WIDTH = 17;
+const ID_WIDTH = 36;
+const TITLE_WIDTH = 16;
+const TABLE_INDENT = '    ';
+const COLUMN_GAP = '  ';
+const NEW_SESSION_ROW = '[New conversation]';
+
+function print(message = '') {
+  process.stdout.write(message);
+}
+
+function readStart(file, bytes = 256 * 1024) {
+  const handle = openSync(file, 'r');
+  try {
+    const buffer = Buffer.alloc(bytes);
+    return buffer.subarray(0, readSync(handle, buffer, 0, bytes, 0)).toString('utf8');
+  } finally {
+    closeSync(handle);
+  }
+}
+
+function walkJsonl(dir, result = []) {
+  if (!existsSync(dir)) return result;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) walkJsonl(path, result);
+    else if (entry.isFile() && entry.name.endsWith('.jsonl')) result.push(path);
+  }
+  return result;
+}
+
+function parseJsonLine(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function readSessionIndex(codexHome) {
+  const file = join(codexHome, 'session_index.jsonl');
+  const byId = new Map();
+  if (!existsSync(file)) return byId;
+  for (const line of readFileSync(file, 'utf8').split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const row = parseJsonLine(line);
+    if (!row?.id) continue;
+    const prior = byId.get(row.id);
+    if (!prior || String(row.updated_at || '') > String(prior.updated_at || '')) byId.set(row.id, row);
+  }
+  return byId;
+}
+
+function textFromContent(content) {
+  if (!Array.isArray(content)) return '';
+  return content
+    .map((part) => part?.text || '')
+    .filter(Boolean)
+    .join(' ');
+}
+
+function firstUserPreview(lines) {
+  for (const line of lines.slice(1, 180)) {
+    const payload = parseJsonLine(line)?.payload;
+    if (payload?.type !== 'message' || payload.role !== 'user') continue;
+    const text = textFromContent(payload.content).trim().replace(/\s+/g, ' ');
+    if (!text || text.startsWith('<environment_context>') || text.startsWith('# AGENTS.md instructions')) continue;
+    return truncate(text, TITLE_WIDTH);
+  }
+  return '';
+}
+
+function truncate(text, max) {
+  return text.length > max ? `${text.slice(0, max - 1)}...` : text;
+}
+
+function pad(text, width) {
+  return truncate(String(text || ''), width).padEnd(width, ' ');
+}
+
+function formatTime(value) {
+  if (!value) return '';
+  return String(value).slice(0, 10);
+}
+
+function normalizePath(path) {
+  const resolved = resolve(path || '');
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function isInsideProject(cwd, projectRoot) {
+  if (!cwd) return false;
+  const sessionCwd = normalizePath(cwd);
+  const root = normalizePath(projectRoot);
+  return sessionCwd === root || sessionCwd.startsWith(`${root}${process.platform === 'win32' ? '\\' : '/'}`);
+}
+
+function readSession(file, indexById) {
+  const lines = readStart(file).split(/\r?\n/).filter(Boolean);
+  const meta = parseJsonLine(lines[0])?.payload;
+  if (!meta?.id) return null;
+  const index = indexById.get(meta.id) || {};
+  return {
+    id: meta.id,
+    provider: meta.model_provider || '',
+    cwd: meta.cwd || '',
+    updatedAt: index.updated_at || meta.timestamp || '',
+    title: index.thread_name || firstUserPreview(lines) || '(untitled)',
+  };
+}
+
+function resolveSessionSelection(selection, sessionsList) {
+  if (/^\d+$/.test(selection)) {
+    const byIndex = sessionsList[Number(selection) - 1];
+    if (byIndex) return byIndex;
+  }
+  const matches = sessionsList.filter((session) => session.id.startsWith(selection));
+  return matches.length === 1 ? matches[0] : null;
+}
+
+function printSessions(sessionsList, options, context) {
+  const listed = sessionsList.slice(0, options.limit || 20);
+  print(`Codex sessions ${options.all ? `under ${context.codexHome}` : `for project ${context.projectRoot}`}\n`);
+  print(`Target: ${context.provider} / ${context.model} / ${context.reasoningEffort}\n\n`);
+  if (!listed.length) {
+    print('No matching sessions found.\n');
+    return;
+  }
+  print(`${TABLE_INDENT}${sessionHeader()}\n`);
+  print(`${TABLE_INDENT}${'-'.repeat(sessionHeader().length)}\n`);
+  listed.forEach((session, index) => {
+    print(`${String(index + 1).padStart(2, ' ')}  ${sessionRow(session)}\n`);
+    if (options.all) print(`    cwd: ${session.cwd || '(unknown cwd)'}\n`);
+    print(`    resume: ${codexResumeCommand(session.id, context)}\n\n`);
+  });
+  if (sessionsList.length > listed.length) print(`Showing ${listed.length} of ${sessionsList.length}. Use --limit ${sessionsList.length} or --all as needed.\n`);
+}
+
+function sessionHeader() {
+  return `${pad('Date', TIME_WIDTH)}${COLUMN_GAP}${pad('Provider', PROVIDER_WIDTH)}${COLUMN_GAP}${pad('Session ID', ID_WIDTH)}${COLUMN_GAP}Title`;
+}
+
+function sessionRow(session) {
+  return `${pad(formatTime(session.updatedAt), TIME_WIDTH)}${COLUMN_GAP}${pad(session.provider || '(unknown)', PROVIDER_WIDTH)}${COLUMN_GAP}${session.id}${COLUMN_GAP}${truncate(session.title, TITLE_WIDTH)}`;
+}
+
+function sessionRows(sessionsList) {
+  return sessionsList.map((session) => sessionRow(session));
+}
+
+async function chooseSessionFlow(allSessions, context, limit) {
+  if (!context.models.length) {
+    print(missingModelMessage(context));
+    return null;
+  }
+
+  const listed = allSessions.slice(0, limit);
+  const header = sessionHeader();
+  return await withPickerScreen(async () => {
+    let step = 'model';
+    while (true) {
+      if (step === 'model') {
+        const action = await pickModel(context);
+        if (action !== 'select') return null;
+        step = 'reasoning';
+      } else if (step === 'reasoning') {
+        const action = await pickReasoning(context);
+        if (action === 'cancel') return null;
+        if (action === 'back') step = 'model';
+        else step = 'session';
+      } else {
+        const rows = [NEW_SESSION_ROW, ...sessionRows(listed)];
+        const result = await pick(`Choose Codex session for ${context.provider} / ${context.model} / ${context.reasoningEffort}`, rows, header);
+        if (result.action === 'cancel') return null;
+        if (result.action === 'back') step = 'reasoning';
+        else if (result.index === 0) return { newConversation: true };
+        else return listed[result.index - 1];
+      }
+    }
+  });
+}
+
+export async function sessions(options) {
+  const context = createLaunchContext(options);
+  const sessionsDir = join(context.codexHome, 'sessions');
+  const indexById = readSessionIndex(context.codexHome);
+  const seen = new Map();
+
+  for (const file of walkJsonl(sessionsDir)) {
+    const session = readSession(file, indexById);
+    if (!session || (!options.all && !isInsideProject(session.cwd, context.projectRoot))) continue;
+    const prior = seen.get(session.id);
+    if (!prior || session.updatedAt > prior.updatedAt) seen.set(session.id, session);
+  }
+
+  const allSessions = [...seen.values()].sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  if (options.exec) {
+    const session = resolveSessionSelection(options.exec, allSessions);
+    if (!session) throw new Error(`Session not found or ambiguous: ${options.exec}`);
+    await runCodex(codexResumeArgs(session.id, context));
+    return;
+  }
+
+  if (options.print || !process.stdin.isTTY || !process.stdout.isTTY) {
+    printSessions(allSessions, options, context);
+    return;
+  }
+
+  const selected = await chooseSessionFlow(allSessions, context, options.limit || 20);
+  if (selected?.newConversation) await runCodex(codexNewArgs(context));
+  else if (selected) await runCodex(codexResumeArgs(selected.id, context));
+}