@christiandoxa/prodex 0.231.0 → 0.233.0

package/README.md

@@ -94,7 +94,9 @@ curl http://127.0.0.1:4000/v1/responses \
 <details>
 <summary>Gateway capabilities (advanced)</summary>
 
-The gateway serves `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/batches`, `/v1/rerank`, `/v1/a2a`, `/v1/messages`, and `/v1/models` where the selected upstream supports them. It adds `x-prodex-call-id` to responses, writes local request detail plus `gateway_spend` events for both `request` and `response` phases to runtime logs, can export those events to JSONL or HTTP using generic, OTel, Datadog, or Langfuse-shaped payloads, supports catalog-backed policy routing strategies (`fallback`, `round-robin`, `least-busy`, `lowest-cost`, `lowest-latency`, `rpm`, `tpm`, `first`) for model aliases/fallback chains, can enforce static virtual keys with persisted request/spend usage plus model/budget/RPM/TPM limits, supports file, SQLite, Postgres, or Redis-backed gateway admin/usage/ledger/SCIM state, and can apply keyword/model, local PII redaction, Presidio, and external webhook guardrails before calls and on outputs. Admin-token, trusted-proxy SSO, or OIDC/JWT bearer requests can list usage, create generated-token keys, rotate/disable/update/delete admin-managed keys, provision SSO users through SCIM-compatible `/v1/prodex/gateway/scim/v2/Users`, inspect usage at `/v1/prodex/gateway/keys` and `/v1/prodex/gateway/usage`, read recent billing ledger records with response-status/output-token reconciliation at `/v1/prodex/gateway/ledger`, read aggregated billing totals at `/v1/prodex/gateway/ledger/summary`, export billing CSV from `/v1/prodex/gateway/ledger.csv` and `/v1/prodex/gateway/ledger/summary.csv`, scrape Prometheus text metrics at `/v1/prodex/gateway/metrics`, inspect provider adapter contracts at `/v1/prodex/gateway/providers`, inspect active observability and guardrail configuration at `/v1/prodex/gateway/observability` and `/v1/prodex/gateway/guardrails`, fetch the machine-readable gateway contract at `/v1/prodex/gateway/openapi.json`, and open the built-in gateway admin dashboard at `/v1/prodex/gateway/admin`; policy/env-backed keys remain read-only, SCIM users can carry tenant/team/project/user/budget scopes for SSO/OIDC fallback, admin-managed key and SCIM user mutations are recorded in `prodex audit`, and additional admin-plane tokens can be `admin` or read-only `viewer` with optional virtual-key prefix plus tenant/team/project/user/budget scopes. Configure defaults under `[gateway]` in `policy.toml`; validate provider catalog edits with `npm run catalog:providers`.
+The gateway serves `/v1/responses`, `/v1/chat/completions`, `/v1/embeddings`, `/v1/images/*`, `/v1/audio/*`, `/v1/batches`, `/v1/rerank`, `/v1/a2a`, `/v1/messages`, and `/v1/models` where the selected upstream supports them. It adds `x-prodex-call-id` to responses, writes local request detail plus `gateway_spend` events for both `request` and `response` phases to runtime logs, can export those events to JSONL or HTTP using generic, OTel, Datadog, or Langfuse-shaped payloads, supports catalog-backed policy routing strategies (`fallback`, `round-robin`, `least-busy`, `lowest-cost`, `lowest-latency`, `rpm`, `tpm`, `first`) for model aliases/fallback chains, can enforce static virtual keys with persisted request/spend usage plus model/budget/RPM/TPM limits, supports file, SQLite, Postgres, or Redis-backed gateway admin/usage/ledger/SCIM state, and can apply keyword/model, local PII redaction, Presidio, and external webhook guardrails before calls and on outputs. Admin-token, trusted-proxy SSO, or OIDC/JWT bearer requests can list usage, create generated-token keys, rotate/disable/update/delete admin-managed keys, provision SSO users through SCIM-compatible `/v1/prodex/gateway/scim/v2/Users`, inspect usage at `/v1/prodex/gateway/keys` and `/v1/prodex/gateway/usage`, read recent billing ledger records with response-status/output-token reconciliation at `/v1/prodex/gateway/ledger`, read aggregated billing totals at `/v1/prodex/gateway/ledger/summary`, export billing CSV from `/v1/prodex/gateway/ledger.csv` and `/v1/prodex/gateway/ledger/summary.csv`, scrape Prometheus text metrics at `/v1/prodex/gateway/metrics`, inspect provider adapter contracts at `/v1/prodex/gateway/providers` or offline with `prodex gateway providers --json`, inspect active observability and guardrail configuration at `/v1/prodex/gateway/observability` and `/v1/prodex/gateway/guardrails`, fetch the machine-readable gateway contract at `/v1/prodex/gateway/openapi.json`, and open the built-in gateway admin dashboard at `/v1/prodex/gateway/admin`; policy/env-backed keys remain read-only, SCIM users can carry tenant/team/project/user/budget scopes for SSO/OIDC fallback, admin-managed key and SCIM user mutations are recorded in `prodex audit`, and additional admin-plane tokens can be `admin` or read-only `viewer` with optional virtual-key prefix plus tenant/team/project/user/budget scopes. Configure defaults under `[gateway]` in `policy.toml`; validate provider catalog edits with `npm run catalog:providers`. The generated provider matrix lives in [docs/provider-capabilities.md](./docs/provider-capabilities.md).
+
+`[gateway.adaptive_routing]` is a shadow-mode foundation for owner-attributed quality feedback and route recommendations. Live gateway routing remains deterministic unless a future explicit adaptive policy is enabled, and continuation affinity still wins over any recommendation.
 
 JavaScript clients can use `@christiandoxa/prodex-gateway-sdk` for `/v1/responses` plus gateway key, usage, billing ledger, metrics, and OpenAPI admin calls.
 
@@ -972,6 +974,10 @@ prodex run --respect-system-proxy
 
 Codex `multiAgentMode` is an app-server/thread setting, not a normal TUI `config.toml` launch override. Prodex therefore does not invent a competing CLI config flag. Launch `prodex app-server` or `prodex run app-server` and pass upstream `multiAgentMode` values (`none`, `explicitRequestOnly`, or `proactive`) through the Codex app-server API.
 
+`prodex mcp-server`, `prodex app-server`, and `prodex exec-server` are direct Codex command-server passthroughs by default. Prodex selects the profile `CODEX_HOME` and preserves upstream protocol arguments, but it does not wrap stdio, inject the runtime proxy, rotate accounts inside the protocol, or apply gateway guardrails to those command-server streams. A future broker mode may add JSON-RPC-aware routing behind explicit opt-in; default passthrough remains the compatibility path.
+
+`prodex app-server-broker --json` exposes the current broker-ready contract skeleton. It recognizes JSON-RPC lifecycle methods such as `initialize`, `thread/start`, `thread/resume`, `thread/fork`, `turn/start`, and `turn/cancel`, but stdio brokering is still disabled; `--experimental-stdio` fails loudly instead of corrupting protocol traffic.
+
 Codex plugin catalog commands are managed passthrough by default:
 
 ```bash
@@ -1082,6 +1088,38 @@ prodex s deepseek --model deepseek-v4-pro --api-key "$DEEPSEEK_API_KEY"
 
 If `--api-key` is omitted, Prodex reads `DEEPSEEK_API_KEY`; `DEEPSEEK_API_KEYS` may contain multiple comma-, semicolon-, or newline-separated keys for round-robin request rotation and pre-commit retry on auth/quota/rate/temporary failures. This path injects a temporary `prodex-deepseek` Codex provider, exposes a local `/v1/responses` adapter to Codex, forwards to DeepSeek's OpenAI-format chat API, and keeps quota preflight disabled. Prodex also injects a one-model Codex catalog for the selected DeepSeek model, so `/model` stays on that model and offers the DeepSeek-compatible `high`/`xhigh` effort choices. `prodex quota --all --provider deepseek` reads the same `DEEPSEEK_API_KEY(S)` environment and fetches DeepSeek `/user/balance`. Available Super optimizer tools remain local Prodex overlay additions around Codex. Remote compact is not implemented for this adapter yet, so the default DeepSeek context window is large and `--auto-compact-token-limit` defaults high.
 
+The DeepSeek catalog includes `deepseek-v4-pro` and `deepseek-v4-flash`; `deepseek-chat` and `deepseek-reasoner` remain compatibility aliases for existing configs.
+
+DeepSeek compatibility is translated, not native Responses. Prodex maps Codex text turns, function/MCP/local shell/apply-patch style tools, `tool_choice`, reasoning effort, JSON object mode, stop sequences, token limits (`max_output_tokens`, `max_tokens`, and `max_completion_tokens`), sampling, logprobs, streaming usage, and DeepSeek cache hit/miss usage into compatible shapes. Request `metadata`, `client_metadata`, `prompt_cache_key`, and `prompt_cache_retention` are preserved in local response metadata instead of being forwarded upstream. JSON schema requests are degraded to DeepSeek `json_object` mode and marked in response metadata because DeepSeek's OpenAI Chat route does not provide native JSON Schema enforcement. Web search is explicit and configurable: the DeepSeek catalog does not advertise native Codex web search, `[deepseek] web_search_mode = "auto"` fails clearly because DeepSeek's OpenAI Chat docs do not document native web-search request fields, `"off"` rejects web-search tools, and `"openai_chat"` explicitly chooses best-effort `web_search_options` forwarding with retry fallback. Gateway/profileless launches can use `PRODEX_DEEPSEEK_WEB_SEARCH_MODE`. The reserved `anthropic` and `function_proxy` modes fail clearly until the DeepSeek Anthropic adapter or a local search backend is implemented. DeepSeek function tools are bounded by the upstream 128-tool limit; Prodex must fail rather than silently truncate if that ceiling is reached, translated duplicate tool names are rejected instead of being dropped, and named `tool_choice` must target a translated function tool. Tool declarations must also be translatable: function/custom tools require names, namespace tools require a named namespace with named function entries, MCP toolsets that declare inventories require a server name plus allowed/enabled tools, and DeepSeek function names must use only letters, numbers, underscores, or dashes within the upstream 64-character limit. When DeepSeek thinking is enabled, Prodex omits explicit `tool_choice` for upstream compatibility and records the omitted value in DeepSeek response metadata. Reasoning content, refusal text, annotations, logprobs, and finish reasons are preserved in DeepSeek response metadata. Reasoning summaries are not advertised for DeepSeek, and `reasoning.summary` fails clearly. Image, document, audio, and video message content is rejected because this adapter targets DeepSeek's text/tool OpenAI Chat surface. Deprecated `frequency_penalty` and `presence_penalty` are not mapped because current DeepSeek docs mark them unsupported/ignored. `parallel_tool_calls=true` is compatible with DeepSeek's one-or-more tool-call behavior, but `parallel_tool_calls=false` is rejected because the OpenAI Chat route has no equivalent control to enforce it. Responses-only controls that DeepSeek cannot honor, including non-empty `include`, `store=false`, background responses, `truncation=auto`, per-message `cache_control`, `text.verbosity`, legacy `functions`/`function_call`, `logit_bias`, and `max_tool_calls`, fail clearly instead of being dropped.
+
+DeepSeek troubleshooting: if JSON mode appears to stream whitespace or stalls, make sure the prompt explicitly asks for JSON; Prodex adds a minimal adapter instruction when JSON mode is requested, but model-facing task instructions still matter. A DeepSeek 400 around web search usually means the selected `openai_chat` web-search forwarding shape is not accepted by upstream; use `web_search_mode = "off"` or remove web-search tools unless you are deliberately testing that best-effort path. Strict tool failures usually mean a schema keyword outside DeepSeek's beta strict subset, a missing `required` property, or an object schema that cannot be made `additionalProperties = false`.
+
+DeepSeek compatibility matrix:
+
+| Capability | Status |
+| --- | --- |
+| Text chat, streaming text, usage | Translated through DeepSeek OpenAI Chat. |
+| Reasoning effort and `reasoning_content` | Translated/preserved through DeepSeek thinking fields and response metadata. |
+| JSON object output | Native DeepSeek `response_format = json_object`. |
+| JSON Schema structured output | Degraded to `json_object` with DeepSeek degradation metadata. |
+| Function tools, MCP tools, local shell, apply patch, `tool_search` | Translated to DeepSeek function tools and mapped back to Codex-compatible output items. |
+| `tool_choice` with thinking | Omitted for upstream compatibility and recorded in DeepSeek response metadata. |
+| Strict function tools | Beta only, opt in with `deepseek.strict_tools = true`. |
+| Web search | Not advertised as native; `auto`/`off` fail clearly, `openai_chat` is explicit best-effort forwarding, `anthropic`/`function_proxy` are reserved until implemented. |
+| Images, documents, audio, video, vision detail | Unsupported on this text/tool adapter; requests fail clearly. |
+| Chat prefix completion, FIM `/completions` | DeepSeek beta features, not enabled on the current `/responses` adapter; completion-shaped requests fail fast. |
+| Remote compact | Unsupported for DeepSeek today; use the large default context/auto-compact limit. |
+
+Strict DeepSeek function calling is opt-in because DeepSeek documents it on the beta endpoint. Add this to the selected Codex profile config:
+
+```toml
+[deepseek]
+strict_tools = true
+beta_base_url = "https://api.deepseek.com/beta"
+```
+
+Gateway/profileless launches can use `PRODEX_DEEPSEEK_STRICT_TOOLS=1` and optional `PRODEX_DEEPSEEK_BETA_BASE_URL`. When enabled, Prodex routes rewritten DeepSeek `/responses` traffic through the beta base URL, sets every translated function tool to `strict: true`, forces strict object schemas to require all properties with `additionalProperties = false`, and rejects unsupported strict schema keywords or types clearly. DeepSeek beta chat prefix completion and FIM `/completions` are not enabled by this adapter yet; `prefix`, `prompt`, and `suffix` completion-style requests fail fast instead of being rewritten as chat.
+
 Use `--provider gemini` when you want the Codex/Super front end with Gemini upstream:
 
 ```bash
@@ -1295,6 +1333,10 @@ In practice, profile `history.jsonl`, `sessions`, `archived_sessions`, `config.t
 
 Codex 0.140.0 defaults CLI auth credentials to the file store, so managed Prodex profiles continue to keep `auth.json` isolated per profile, including OpenAI, API-key, and Bedrock API-key auth JSON. MCP OAuth defaults to Codex `auto`; when it falls back to the file store, `.credentials.json` is shared with direct Codex. OS keyring-backed MCP OAuth credentials remain Codex/OS-owned and are not part of Prodex profile export bundles.
 
+Prodex's own `prodex-secret-store` keyring backend is currently unavailable. If `PRODEX_SECRET_BACKEND=keyring` or `[secrets].backend = "keyring"` is selected, `prodex doctor` and `prodex info` report an invalid backend instead of silently pretending that OS keyring storage is active. Use `backend = "file"` until a real OS keyring implementation is enabled.
+
+Prodex strips dynamic-loader injection variables such as `LD_PRELOAD`, `LD_AUDIT`, `LD_LIBRARY_PATH`, and `DYLD_*` from Codex child processes by default. Set `PRODEX_ALLOW_UNSAFE_CHILD_ENV=1` only when intentionally debugging a custom local runtime environment.
+
 Codex cloud-managed config bundle caches are identity/account scoped and remain profile-local. System-level Codex requirements and managed config files remain owned by upstream Codex and the operating system.
 
 Prodex does not synthesize legacy Codex `[profiles.*]` behavior. File-based Codex profile config selected by `--profile` stays in shared Codex state, while Prodex-owned account selection remains in Prodex profile metadata.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christiandoxa/prodex",
-  "version": "0.231.0",
+  "version": "0.233.0",
   "description": "Multi-provider Codex wrapper with OpenAI quota-aware routing and Claude Code support",
   "license": "Apache-2.0",
   "bin": {
@@ -16,12 +16,12 @@
     "@openai/codex": "latest"
   },
   "optionalDependencies": {
-    "@christiandoxa/prodex-linux-x64": "0.231.0",
-    "@christiandoxa/prodex-linux-arm64": "0.231.0",
-    "@christiandoxa/prodex-darwin-x64": "0.231.0",
-    "@christiandoxa/prodex-darwin-arm64": "0.231.0",
-    "@christiandoxa/prodex-win32-x64": "0.231.0",
-    "@christiandoxa/prodex-win32-arm64": "0.231.0",
+    "@christiandoxa/prodex-linux-x64": "0.233.0",
+    "@christiandoxa/prodex-linux-arm64": "0.233.0",
+    "@christiandoxa/prodex-darwin-x64": "0.233.0",
+    "@christiandoxa/prodex-darwin-arm64": "0.233.0",
+    "@christiandoxa/prodex-win32-x64": "0.233.0",
+    "@christiandoxa/prodex-win32-arm64": "0.233.0",
     "@openai/codex-linux-x64": "npm:@openai/codex@linux-x64",
     "@openai/codex-linux-arm64": "npm:@openai/codex@linux-arm64",
     "@openai/codex-darwin-x64": "npm:@openai/codex@darwin-x64",