@mmmbuto/zai-codex-bridge 0.3.2 → 0.4.2

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.2] - 2026-01-16
+
+### Changed
+- Replaced the README with expanded setup, usage, and troubleshooting guidance
+- Clarified Codex provider configuration and proxy endpoint usage
+
+## [0.4.1] - 2026-01-16
+
+### Added
+- Tool calling support (MCP/function calls) when `ALLOW_TOOLS=1`
+- Bridging for `function_call_output` items to Chat `role: tool` messages
+- Streaming support for `delta.tool_calls` with proper Responses API events
+- Non-streaming support for `msg.tool_calls` in final response
+- Tool call events: `response.output_item.added` (function_call), `response.function_call_arguments.delta`, `response.function_call_arguments.done`
+- Automated tool call test in test suite
+
+### Changed
+- `translateResponsesToChat()` now handles `type: function_call_output` items
+- `streamChatToResponses()` now detects and emits tool call events
+- `translateChatToResponses()` now includes `function_call` items in output array
+
+### Fixed
+- Tool responses (from MCP/function calls) are now correctly forwarded to upstream as `role: tool` messages
+- Function call items are now properly included in `response.completed` output array
+
+## [0.4.0] - Previous
+
+### Added
+- Initial release with Responses API to Chat Completions translation
+- Streaming support with SSE
+- Health check endpoint
+- Zero-dependency implementation

package/README.md

@@ -1,6 +1,6 @@
-# Z.AI Codex Bridge
+# ZAI Codex Bridge
 
-> Local proxy that translates OpenAI Responses API format to Z.AI Chat Completions format
+> Local proxy that translates OpenAI **Responses API** ↔ Z.AI **Chat Completions** for Codex CLI
 
 [![npm](https://img.shields.io/npm/v/@mmmbuto/zai-codex-bridge?style=flat-square&logo=npm)](https://www.npmjs.org/package/@mmmbuto/zai-codex-bridge)
 [![node](https://img.shields.io/node/v/@mmmbuto/zai-codex-bridge?style=flat-square&logo=node.js)](https://github.com/DioNanos/zai-codex-bridge)
@@ -10,36 +10,39 @@
 
 ## What It Solves
 
-Codex uses the OpenAI **Responses API** format (with `instructions` and `input` fields), but Z.AI only supports the legacy **Chat Completions** format (with `messages` array).
+Newer **Codex CLI** versions speak the OpenAI **Responses API** (e.g. `/v1/responses`, with `instructions` + `input` + event-stream semantics).
+Some gateways/providers (including Z.AI endpoints) only expose legacy **Chat Completions** (`messages[]`).
 
 This proxy:
-1. Accepts Codex requests in **Responses format**
-2. Translates them to **Chat format**
+1. Accepts Codex requests in **Responses** format
+2. Translates them to **Chat Completions**
 3. Forwards to Z.AI
-4. Translates the response back to **Responses format**
+4. Translates back to **Responses** format (stream + non-stream)
 5. Returns to Codex
 
-**Without this proxy**, Codex fails with error from Z.AI:
+**Without this proxy**, Codex may fail (example from upstream error payloads):
 ```json
 {"error":{"code":"1214","message":"Incorrect role information"}}
 ```
 
+> If you’re using **codex-termux** and a gateway that doesn’t fully match the Responses API, this proxy is the recommended compatibility layer.
+
 ---
 
 ## Features
 
-- Transparent translation between Responses and Chat formats
+- Responses API ↔ Chat Completions translation (request + response)
 - Streaming support with SSE (Server-Sent Events)
-- Zero dependencies - uses Node.js built-ins only
-- Health checks at `/health` endpoint
-- Configurable via CLI flags and environment variables
+- Health check endpoint (`/health`)
+- Works on Linux/macOS/Windows (WSL) + Termux (ARM64)
+- **Optional tool/MCP bridging** (see “Tools / MCP” below)
+- Zero/low dependencies (Node built-ins only, unless noted by package.json)
 
 ---
 
 ## Requirements
 
-- **Node.js**: 18.0.0 or higher (for native `fetch`)
-- **Platform**: Linux, macOS, Windows (WSL), Termux (ARM64)
+- **Node.js**: 18+ (native `fetch`)
 - **Port**: 31415 (default, configurable)
 
 ---
@@ -54,28 +57,34 @@ npm install -g @mmmbuto/zai-codex-bridge
 
 ## Quick Start
 
-### 1. Start the Proxy
+### 1) Start the Proxy
 
 ```bash
 zai-codex-bridge
 ```
 
-The proxy will listen on `http://127.0.0.1:31415`
+Default listen address:
+
+- `http://127.0.0.1:31415`
 
-### 2. Configure Codex
+### 2) Configure Codex
 
-Add to `~/.codex/config.toml`:
+Add this provider to `~/.codex/config.toml`:
 
 ```toml
 [model_providers.zai_proxy]
 name = "ZAI via local proxy"
-base_url = "http://127.0.0.1:31415/v1"
+base_url = "http://127.0.0.1:31415"
 env_key = "OPENAI_API_KEY"
 wire_api = "responses"
 stream_idle_timeout_ms = 3000000
 ```
 
-### 3. Use with Codex
+> Notes:
+> - `base_url` is the server root. Codex will call `/v1/responses`; this proxy supports that path.
+> - We keep `env_key = "OPENAI_API_KEY"` because Codex expects that key name. You can store your Z.AI key there.
+
+### 3) Run Codex via the Proxy
 
 ```bash
 export OPENAI_API_KEY="your-zai-api-key"
@@ -84,6 +93,29 @@ codex -m "GLM-4.7" -c model_provider="zai_proxy"
 
 ---
 
+## Tools / MCP (optional)
+
+Codex tool-calling / MCP memory requires an additional compatibility layer:
+- Codex uses **Responses API tool events** (function call items + arguments delta/done, plus function_call_output inputs)
+- Some upstream models/providers may not emit tool calls (or may emit them in a different shape)
+
+This proxy can **attempt** to bridge tools when enabled:
+
+```bash
+export ALLOW_TOOLS=1
+```
+
+Important:
+- Tool support is **provider/model dependent**. If upstream never emits tool calls, the proxy can’t invent them.
+- If tools are enabled, the proxy must translate:
+  - Responses `tools` + `tool_choice` → Chat `tools` + `tool_choice`
+  - Chat `tool_calls` (stream/non-stream) → Responses function-call events
+  - Responses `function_call_output` → Chat `role=tool` messages
+
+(See repo changelog and docs for the exact implemented behavior.)
+
+---
+
 ## CLI Usage
 
 ```bash
@@ -97,7 +129,7 @@ zai-codex-bridge --port 8080
 zai-codex-bridge --log-level debug
 
 # Custom Z.AI endpoint
-zai-codex-bridge --zai-base-url https://custom.z.ai/v1
+zai-codex-bridge --zai-base-url https://api.z.ai/api/coding/paas/v4
 
 # Show help
 zai-codex-bridge --help
@@ -106,17 +138,20 @@ zai-codex-bridge --help
 ### Environment Variables
 
 ```bash
-export PORT=31415
 export HOST=127.0.0.1
+export PORT=31415
 export ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4
 export LOG_LEVEL=info
+
+# Optional
+export ALLOW_TOOLS=1
 ```
 
 ---
 
-## Auto-Starting Proxy with Codex
+## Auto-start the Proxy with Codex (recommended)
 
-You can create a shell function that starts the proxy automatically when needed:
+Use a shell function that starts the proxy only if needed:
 
 ```bash
 codex-with-zai() {
@@ -125,114 +160,107 @@ codex-with-zai() {
   local HEALTH="http://${HOST}:${PORT}/health"
   local PROXY_PID=""
 
-  # Start proxy only if not responding
   if ! curl -fsS "$HEALTH" >/dev/null 2>&1; then
     zai-codex-bridge --host "$HOST" --port "$PORT" >/dev/null 2>&1 &
     PROXY_PID=$!
     trap 'kill $PROXY_PID 2>/dev/null' EXIT INT TERM
-    sleep 2
+    sleep 1
   fi
 
-  # Run codex
-  codex -m "GLM-4.7" -c model_provider="zai_proxy" "$@"
+  codex -c model_provider="zai_proxy" "$@"
 }
 ```
 
 Usage:
+
 ```bash
-codex-with-zai
-# Proxy auto-starts, Codex runs
-# Ctrl+D exits both
+export OPENAI_API_KEY="your-zai-api-key"
+codex-with-zai -m "GLM-4.7"
 ```
 
 ---
 
 ## API Endpoints
 
-### `POST /responses`
-Accepts OpenAI Responses API format, translates to Chat, returns Responses format.
-
-### `POST /v1/responses`
-Same as `/responses` (for compatibility with Codex's path structure).
-
-### `GET /health`
-Health check endpoint.
+- `POST /responses` — accepts Responses API requests
+- `POST /v1/responses` — same as above (Codex default path)
+- `GET /health` — health check
 
 ---
 
-## Translation Details
+## Translation Overview
 
 ### Request: Responses → Chat
 
-```javascript
-// Input (Responses format)
+```js
+// Input (Responses)
 {
-  model: "GLM-4.7",
-  instructions: "Be helpful",
-  input: [
-    { role: "user", content: "Hello" }
-  ],
-  max_output_tokens: 1000
+  "model": "GLM-4.7",
+  "instructions": "Be helpful",
+  "input": [{ "role": "user", "content": "Hello" }],
+  "max_output_tokens": 1000
 }
 
-// Output (Chat format)
+// Output (Chat)
 {
-  model: "GLM-4.7",
-  messages: [
-    { role: "system", content: "Be helpful" },
-    { role: "user", content: "Hello" }
+  "model": "GLM-4.7",
+  "messages": [
+    { "role": "system", "content": "Be helpful" },
+    { "role": "user", "content": "Hello" }
   ],
-  max_tokens: 1000
+  "max_tokens": 1000
 }
 ```
 
-### Response: Chat → Responses
+### Response: Chat → Responses (simplified)
 
-```javascript
-// Input (Chat format)
+```js
+// Input (Chat)
 {
-  choices: [{
-    message: { content: "Hi there!" }
-  }],
-  usage: {
-    prompt_tokens: 10,
-    completion_tokens: 5
-  }
+  "choices": [{ "message": { "content": "Hi there!" } }],
+  "usage": { "prompt_tokens": 10, "completion_tokens": 5 }
 }
 
-// Output (Responses format)
+// Output (Responses - simplified)
 {
-  output: [{ value: "Hi there!", content_type: "text" }],
-  status: "completed",
-  usage: {
-    input_tokens: 10,
-    output_tokens: 5
-  }
+  "status": "completed",
+  "output": [{ "type": "message", "content": [{ "type": "output_text", "text": "Hi there!" }] }],
+  "usage": { "input_tokens": 10, "output_tokens": 5 }
 }
 ```
 
 ---
 
-## Testing
+## Troubleshooting
 
-```bash
-# Set your Z.AI API key
-export ZAI_API_KEY="sk-your-key"
+### 401 / “token expired or incorrect”
+- Verify the key is exported as `OPENAI_API_KEY` (or matches `env_key` in config.toml).
+- Make sure the proxy is not overwriting Authorization headers.
 
-# Run test suite
-npm run test:curl
-```
+### 404 on `/v1/responses`
+- Ensure `base_url` points to the proxy root (example: `http://127.0.0.1:31415`).
+- Confirm the proxy is running and `/health` returns `ok`.
+
+### 502 Bad Gateway
+- Proxy reached upstream but upstream failed. Enable debug:
+  ```bash
+  LOG_LEVEL=debug zai-codex-bridge
+  ```
 
 ---
 
-## Documentation
+## Versioning Policy
 
-Complete usage guide: [docs/guide.md](docs/guide.md)
+This repo follows **small, safe patch increments** while stabilizing provider compatibility:
+
+- Keep patch bumps only: `0.4.0 → 0.4.1 → 0.4.2 → ...`
+- No big jumps unless strictly necessary.
+
+(See `CHANGELOG.md` for details once present.)
 
 ---
 
 ## License
 
-MIT License - Copyright (c) 2026 Davide A. Guglielmi
-
+MIT License — Copyright (c) 2026 Davide A. Guglielmi  
 See [LICENSE](LICENSE) for details.

package/RELEASING.md

@@ -0,0 +1,80 @@
+# Releasing
+
+This document describes the release process for zai-codex-bridge.
+
+## Version Policy
+
+- **Patch releases only** (0.4.0 → 0.4.1 → 0.4.2, etc.)
+- No minor or major bumps without explicit discussion
+- Always increment by +0.0.1 from current version
+
+## Release Steps
+
+### 1. Run Tests
+
+```bash
+# Set your API key
+export ZAI_API_KEY="sk-your-key"
+
+# Run test suite
+npm run test:curl
+# or
+npm test
+```
+
+### 2. Bump Version
+
+```bash
+# Use the release script (recommended)
+npm run release:patch
+
+# Or manually edit package.json and change:
+# "version": "0.4.0" -> "version": "0.4.1"
+```
+
+### 3. Update CHANGELOG.md
+
+Add an entry for the new version following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) format.
+
+### 4. Commit
+
+```bash
+git add package.json CHANGELOG.md
+git commit -m "chore: release v0.4.1"
+```
+
+### 5. Tag
+
+```bash
+git tag v0.4.1
+```
+
+### 6. Push (Optional)
+
+```bash
+git push
+git push --tags
+```
+
+### 7. Publish to npm
+
+```bash
+npm publish
+```
+
+## release:patch Script
+
+The `npm run release:patch` script:
+
+1. Verifies current version is 0.4.x
+2. Bumps patch version by +0.0.1
+3. Refuses to bump minor/major versions
+4. Updates package.json in-place
+
+Example:
+```bash
+$ npm run release:patch
+Current version: 0.4.0
+Bumping to: 0.4.1
+Updated package.json
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/zai-codex-bridge",
-  "version": "0.3.2",
+  "version": "0.4.2",
   "description": "Local proxy that translates OpenAI Responses API format to Z.AI Chat Completions format for Codex",
   "main": "src/server.js",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "scripts": {
     "start": "node src/server.js",
-    "test:curl": "node scripts/test-curl.js"
+    "test": "node scripts/test-curl.js",
+    "test:curl": "node scripts/test-curl.js",
+    "release:patch": "node scripts/release-patch.js"
   },
   "keywords": [
     "codex",

package/scripts/release-patch.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * Safe patch version bumper
+ * Only allows patch releases (0.4.0 -> 0.4.1)
+ * Refuses minor/major bumps
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_PATH = path.join(__dirname, '..', 'package.json');
+
+function bumpPatch(version) {
+  const parts = version.split('.').map(Number);
+
+  if (parts.length !== 3) {
+    throw new Error(`Invalid version format: ${version}`);
+  }
+
+  const [major, minor, patch] = parts;
+
+  // Only allow 0.4.x versions
+  if (major !== 0 || minor !== 4) {
+    console.error(`ERROR: Current version is ${version}`);
+    console.error('This script only supports patch releases for 0.4.x versions.');
+    console.error('For other version changes, edit package.json manually.');
+    process.exit(1);
+  }
+
+  const newVersion = `0.4.${patch + 1}`;
+  return newVersion;
+}
+
+function main() {
+  // Read package.json
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_PATH, 'utf8'));
+  const currentVersion = pkg.version;
+
+  console.log(`Current version: ${currentVersion}`);
+
+  // Bump patch
+  const newVersion = bumpPatch(currentVersion);
+  console.log(`Bumping to: ${newVersion}`);
+
+  // Update package.json
+  pkg.version = newVersion;
+
+  // Write back
+  fs.writeFileSync(PACKAGE_PATH, JSON.stringify(pkg, null, 2) + '\n');
+
+  console.log('Updated package.json');
+  console.log('\nNext steps:');
+  console.log('  1. Update CHANGELOG.md');
+  console.log('  2. Commit: git add package.json CHANGELOG.md && git commit -m "chore: release v' + newVersion + '"');
+  console.log('  3. Tag: git tag v' + newVersion);
+  console.log('  4. Publish: npm publish');
+}
+
+main();