@mmmbuto/zai-codex-bridge 0.4.0 → 0.4.3

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# 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.3] - 2026-01-16
+
+### Added
+- Auto-enable tool bridging when tool-related fields are present in the request
+- Extra logging to surface `allowTools` and `toolsPresent` per request
+- Debug tool summary logging (types and sample names)
+
+### Fixed
+- Correct output_index mapping for streaming tool call events
+- Filter non-function tools to avoid upstream schema errors
+
+### Changed
+- README guidance for MCP/tools troubleshooting and proxy startup
+
+## [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,31 @@ 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 automatically when the request carries tool definitions
+(`tools`, `tool_choice`, or tool outputs). You can also force it on:
+
+```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
+- Non-function tool types are dropped for Z.AI compatibility.
+
+(See repo changelog and docs for the exact implemented behavior.)
+
+---
+
 ## CLI Usage
 
 ```bash
@@ -97,7 +131,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 +140,21 @@ 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   # force tool bridging (otherwise auto-enabled when tools are present)
+export ALLOW_SYSTEM=1  # only if your provider supports system role
 ```
 
 ---
 
-## 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 +163,114 @@ 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 &
+    ALLOW_TOOLS=1 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`.
+
+### MCP/tools not being called
+- Check proxy logs for `allowTools: true` and `toolsPresent: true`.
+- If `toolsPresent: false`, Codex did not send tool definitions (verify your provider config).
+- If tools are present but the model prints literal `<function=...>` markup or never emits tool calls,
+  your upstream model likely doesn’t support tool calling.
+- If your provider supports `system` role, try `ALLOW_SYSTEM=1` to improve tool adherence.
+
+### 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.4.0",
+  "version": "0.4.3",
   "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();

package/scripts/test-curl.js

@@ -135,6 +135,155 @@ async function testStreamingFormat() {
   });
 }
 
+async function testToolCall() {
+  console.log('\n=== Testing POST /v1/responses (Tool Call) ===\n');
+  console.log('Note: This test requires ALLOW_TOOLS=1 and upstream model support for tools.\n');
+
+  const payload = {
+    model: 'GLM-4.7',
+    instructions: 'You are a helpful assistant.',
+    input: [
+      {
+        role: 'user',
+        content: 'What is the weather in Tokyo? Use the get_weather tool.'
+      }
+    ],
+    tools: [
+      {
+        type: 'function',
+        function: {
+          name: 'get_weather',
+          description: 'Get the current weather for a location',
+          parameters: {
+            type: 'object',
+            properties: {
+              location: {
+                type: 'string',
+                description: 'The city and state, e.g. San Francisco, CA'
+              }
+            },
+            required: ['location']
+          }
+        }
+      }
+    ],
+    tool_choice: 'auto',
+    stream: true
+  };
+
+  return new Promise((resolve, reject) => {
+    const options = {
+      hostname: PROXY_HOST,
+      port: PROXY_PORT,
+      path: '/v1/responses',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${ZAI_API_KEY}`
+      }
+    };
+
+    const req = http.request(options, (res) => {
+      console.log('Status:', res.statusCode);
+
+      if (res.statusCode !== 200) {
+        let body = '';
+        res.on('data', (chunk) => body += chunk);
+        res.on('end', () => {
+          console.log('Error response:', body);
+          resolve({ status: 'error', message: body });
+        });
+        return;
+      }
+
+      console.log('\nStreaming response:');
+      let buffer = '';
+      let foundToolCall = false;
+      let foundOutputItemAdded = false;
+      let foundFunctionCallDelta = false;
+      let foundOutputItemDone = false;
+      let foundResponseCompleted = false;
+
+      res.on('data', (chunk) => {
+        buffer += chunk.toString();
+        const events = buffer.split('\n\n');
+        buffer = events.pop() || '';
+
+        for (const evt of events) {
+          const lines = evt.split('\n');
+          for (const line of lines) {
+            if (!line.startsWith('data:')) continue;
+            const payload = line.slice(5).trim();
+            if (!payload || payload === '[DONE]') continue;
+
+            try {
+              const data = JSON.parse(payload);
+              const type = data.type;
+
+              // Look for tool call events
+              if (type === 'response.output_item.added') {
+                if (data.item?.type === 'function_call') {
+                  foundOutputItemAdded = true;
+                  console.log('[EVENT] output_item.added (function_call):', data.item?.name);
+                }
+              }
+
+              if (type === 'response.function_call_arguments.delta') {
+                foundFunctionCallDelta = true;
+                process.stdout.write('.');
+              }
+
+              if (type === 'response.output_item.done') {
+                if (data.item?.type === 'function_call') {
+                  foundOutputItemDone = true;
+                }
+              }
+
+              if (type === 'response.completed') {
+                foundResponseCompleted = true;
+              }
+            } catch (e) {
+              // Skip parse errors
+            }
+          }
+        }
+      });
+
+      res.on('end', () => {
+        console.log();
+        console.log('\n=== Tool Call Test Results ===');
+
+        if (!foundToolCall && !foundOutputItemAdded) {
+          console.log('SKIP: upstream did not return tool_calls');
+          console.log('This may mean:');
+          console.log('  - ALLOW_TOOLS is not enabled on the proxy');
+          console.log('  - The model does not support tool calls');
+          console.log('  - The prompt did not trigger a tool call');
+          resolve({ status: 'skipped', reason: 'no tool calls from upstream' });
+          return;
+        }
+
+        const passed = foundOutputItemAdded && foundFunctionCallDelta && foundOutputItemDone && foundResponseCompleted;
+        console.log('output_item.added (function_call):', foundOutputItemAdded ? 'PASS' : 'FAIL');
+        console.log('function_call_arguments.delta:', foundFunctionCallDelta ? 'PASS' : 'FAIL');
+        console.log('output_item.done (function_call):', foundOutputItemDone ? 'PASS' : 'FAIL');
+        console.log('response.completed:', foundResponseCompleted ? 'PASS' : 'FAIL');
+        console.log('\nOverall:', passed ? 'PASS' : 'FAIL');
+
+        resolve({ status: passed ? 'pass' : 'fail', results: { foundOutputItemAdded, foundFunctionCallDelta, foundOutputItemDone, foundResponseCompleted } });
+      });
+    });
+
+    req.on('error', (err) => {
+      console.error('Request error:', err.message);
+      reject(err);
+    });
+
+    req.write(JSON.stringify(payload, null, 2));
+    req.end();
+  });
+}
+
 async function main() {
   console.log('zai-codex-bridge Manual Test');
   console.log('================================');
@@ -151,7 +300,22 @@ async function main() {
     await testResponsesFormat();
     await testStreamingFormat();
 
+    // Tool call test (optional - depends on upstream support)
+    console.log('\n\n=== Tool Support Tests ===');
+    const toolResult = await testToolCall();
+
     console.log('\n=== All Tests Complete ===\n');
+    console.log('Summary:');
+    console.log('  Health: PASS');
+    console.log('  Non-streaming: PASS');
+    console.log('  Streaming: PASS');
+    if (toolResult.status === 'pass') {
+      console.log('  Tool calls: PASS');
+    } else if (toolResult.status === 'skipped') {
+      console.log('  Tool calls: SKIPPED (upstream does not support or did not return tool_calls)');
+    } else {
+      console.log('  Tool calls: FAIL or ERROR');
+    }
   } catch (error) {
     console.error('\nError:', error.message);
     process.exit(1);

package/src/server.js

@@ -22,7 +22,7 @@ const DEFAULT_MODEL = process.env.DEFAULT_MODEL || 'glm-4.7';
 
 // Env toggles for compatibility
 const ALLOW_SYSTEM = process.env.ALLOW_SYSTEM === '1';
-const ALLOW_TOOLS = process.env.ALLOW_TOOLS === '1';
+const ALLOW_TOOLS_ENV = process.env.ALLOW_TOOLS === '1';
 
 function nowSec() {
   return Math.floor(Date.now() / 1000);
@@ -90,6 +90,67 @@ function detectFormat(body) {
   return 'unknown';
 }
 
+/**
+ * Detect if request carries tool-related data
+ */
+function requestHasTools(request) {
+  if (!request || typeof request !== 'object') return false;
+
+  if (Array.isArray(request.tools) && request.tools.length > 0) return true;
+  if (request.tool_choice) return true;
+
+  if (Array.isArray(request.input)) {
+    for (const item of request.input) {
+      if (!item) continue;
+      if (item.type === 'function_call_output') return true;
+      if (Array.isArray(item.tool_calls) && item.tool_calls.length > 0) return true;
+      if (item.tool_call_id) return true;
+    }
+  }
+
+  if (Array.isArray(request.messages)) {
+    for (const msg of request.messages) {
+      if (!msg) continue;
+      if (msg.role === 'tool') return true;
+      if (Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) return true;
+      if (msg.tool_call_id) return true;
+    }
+  }
+
+  return false;
+}
+
+function summarizeTools(tools, limit = 8) {
+  if (!Array.isArray(tools)) return null;
+  const types = {};
+  const names = [];
+
+  for (const tool of tools) {
+    const type = tool?.type || 'unknown';
+    types[type] = (types[type] || 0) + 1;
+    if (names.length < limit) {
+      if (type === 'function') {
+        names.push(tool?.function?.name || '(missing_name)');
+      } else {
+        names.push(type);
+      }
+    }
+  }
+
+  return { count: tools.length, types, sample_names: names };
+}
+
+function summarizeToolShape(tool) {
+  if (!tool || typeof tool !== 'object') return null;
+  return {
+    keys: Object.keys(tool),
+    type: tool.type,
+    name: tool.name,
+    functionKeys: tool.function && typeof tool.function === 'object' ? Object.keys(tool.function) : null,
+    functionName: tool.function?.name
+  };
+}
+
 /**
  * Flatten content parts to string - supports text, input_text, output_text
  */
@@ -113,7 +174,7 @@ function flattenContent(content) {
 /**
  * Translate Responses format to Chat Completions format
  */
-function translateResponsesToChat(request) {
+function translateResponsesToChat(request, allowTools) {
   const messages = [];
 
   // Add system message from instructions (with ALLOW_SYSTEM toggle)
@@ -143,18 +204,41 @@ function translateResponsesToChat(request) {
         content: request.input
       });
     } else if (Array.isArray(request.input)) {
-      // Array of ResponseItem objects - filter only Message items with role
+      // Array of ResponseItem objects
       for (const item of request.input) {
+        // Handle function_call_output items (tool responses) - only if allowTools
+        if (allowTools && item.type === 'function_call_output') {
+          const toolMsg = {
+            role: 'tool',
+            tool_call_id: item.call_id || item.tool_call_id || '',
+            content: ''
+          };
+
+          // Extract content from output or content field
+          if (item.output !== undefined) {
+            toolMsg.content = typeof item.output === 'string'
+              ? item.output
+              : JSON.stringify(item.output);
+          } else if (item.content !== undefined) {
+            toolMsg.content = typeof item.content === 'string'
+              ? item.content
+              : JSON.stringify(item.content);
+          }
+
+          messages.push(toolMsg);
+          continue;
+        }
+
         // Only process items with a 'role' field (Message items)
         // Skip Reasoning, FunctionCall, LocalShellCall, etc.
         if (!item.role) continue;
 
         // Map non-standard roles to Z.AI-compatible roles
-        // Z.AI accepts: system, user, assistant
+        // Z.AI accepts: system, user, assistant, tool
         let role = item.role;
         if (role === 'developer') {
           role = 'user'; // Map developer to user
-        } else if (role !== 'system' && role !== 'user' && role !== 'assistant') {
+        } else if (role !== 'system' && role !== 'user' && role !== 'assistant' && role !== 'tool') {
           // Skip any other non-standard roles
           continue;
         }
@@ -164,13 +248,13 @@ function translateResponsesToChat(request) {
           content: flattenContent(item.content)
         };
 
-        // Handle tool calls if present (only if ALLOW_TOOLS)
-        if (ALLOW_TOOLS && item.tool_calls && Array.isArray(item.tool_calls)) {
+        // Handle tool calls if present (only if allowTools)
+        if (allowTools && item.tool_calls && Array.isArray(item.tool_calls)) {
           msg.tool_calls = item.tool_calls;
         }
 
-        // Handle tool call ID for tool responses (only if ALLOW_TOOLS)
-        if (ALLOW_TOOLS && item.tool_call_id) {
+        // Handle tool call ID for tool responses (only if allowTools)
+        if (allowTools && item.tool_call_id) {
           msg.tool_call_id = item.tool_call_id;
         }
 
@@ -203,27 +287,49 @@ function translateResponsesToChat(request) {
     chatRequest.top_p = request.top_p;
   }
 
-  // Tools handling (only if ALLOW_TOOLS)
-  if (ALLOW_TOOLS && request.tools && Array.isArray(request.tools)) {
-    // Filter out tools with null or empty function
-    chatRequest.tools = request.tools.filter(tool => {
-      if (tool.type === 'function') {
-        // Check if function has required fields
-        return tool.function && typeof tool.function === 'object' &&
-               tool.function.name && tool.function.name.length > 0 &&
-               tool.function.parameters !== undefined && tool.function.parameters !== null;
-      }
-      // Keep non-function tools (if any)
-      return true;
-    });
+  // Tools handling (only if allowTools)
+  if (allowTools && request.tools && Array.isArray(request.tools)) {
+    const originalCount = request.tools.length;
+    const normalized = [];
+
+    for (const tool of request.tools) {
+      if (!tool || tool.type !== 'function') continue;
+      const fn = tool.function && typeof tool.function === 'object' ? tool.function : null;
+      const name = (fn?.name || tool.name || '').trim();
+      if (!name) continue;
+
+      // Prefer nested function fields, fall back to top-level ones if present
+      const description = fn?.description ?? tool.description;
+      const parameters = fn?.parameters ?? tool.parameters ?? { type: 'object', properties: {} };
+
+      const functionObj = { name, parameters };
+      if (description) functionObj.description = description;
+
+      // Send minimal tool schema for upstream compatibility
+      normalized.push({
+        type: 'function',
+        function: functionObj
+      });
+    }
+
+    chatRequest.tools = normalized;
+
+    const dropped = originalCount - chatRequest.tools.length;
+    if (dropped > 0) {
+      log('warn', `Dropped ${dropped} non-function or invalid tools for upstream compatibility`);
+    }
+
     // Only add tools array if there are valid tools
     if (chatRequest.tools.length === 0) {
       delete chatRequest.tools;
     }
   }
 
-  if (ALLOW_TOOLS && request.tool_choice) {
+  if (allowTools && request.tool_choice) {
     chatRequest.tool_choice = request.tool_choice;
+    if (!chatRequest.tools || chatRequest.tools.length === 0) {
+      delete chatRequest.tool_choice;
+    }
   }
 
   log('debug', 'Translated Responses->Chat:', {
@@ -238,8 +344,9 @@ function translateResponsesToChat(request) {
 /**
  * Translate Chat Completions response to Responses format
  * Handles both output_text and reasoning_text content
+ * Handles tool_calls if present (only if allowTools)
  */
-function translateChatToResponses(chatResponse, responsesRequest, ids) {
+function translateChatToResponses(chatResponse, responsesRequest, ids, allowTools) {
   const msg = chatResponse.choices?.[0]?.message ?? {};
   const outputText = msg.content ?? '';
   const reasoningText = msg.reasoning_content ?? '';
@@ -262,6 +369,27 @@ function translateChatToResponses(chatResponse, responsesRequest, ids) {
     content,
   };
 
+  // Build output array: message item + any function_call items
+  const finalOutput = [msgItem];
+
+  // Handle tool_calls (only if allowTools)
+  if (allowTools && msg.tool_calls && Array.isArray(msg.tool_calls)) {
+    for (const tc of msg.tool_calls) {
+      const callId = tc.id || `call_${randomUUID().replace(/-/g, '')}`;
+      const name = tc.function?.name || '';
+      const args = tc.function?.arguments || '';
+
+      finalOutput.push({
+        id: callId,
+        type: 'function_call',
+        status: 'completed',
+        call_id: callId,
+        name: name,
+        arguments: typeof args === 'string' ? args : JSON.stringify(args),
+      });
+    }
+  }
+
   return buildResponseObject({
     id: responseId,
     model: responsesRequest?.model || chatResponse.model || DEFAULT_MODEL,
@@ -269,7 +397,7 @@ function translateChatToResponses(chatResponse, responsesRequest, ids) {
     created_at: createdAt,
     completed_at: nowSec(),
     input: responsesRequest?.input || [],
-    output: [msgItem],
+    output: finalOutput,
     tools: responsesRequest?.tools || [],
   });
 }
@@ -341,7 +469,7 @@ async function makeUpstreamRequest(path, body, headers) {
  * Handle streaming response from Z.AI with proper Responses API event format
  * Separates reasoning_content, content, and tool_calls into distinct events
  */
-async function streamChatToResponses(upstreamBody, res, responsesRequest, ids) {
+async function streamChatToResponses(upstreamBody, res, responsesRequest, ids, allowTools) {
   const decoder = new TextDecoder();
   const reader = upstreamBody.getReader();
   let buffer = '';
@@ -400,6 +528,10 @@ async function streamChatToResponses(upstreamBody, res, responsesRequest, ids) {
   let out = '';
   let reasoning = '';
 
+  // Tool call tracking (only if allowTools)
+  const toolCallsMap = new Map(); // index -> { callId, name, outputIndex, arguments, partialArgs }
+  const TOOL_BASE_INDEX = 1; // After message item
+
   while (true) {
     const { done, value } = await reader.read();
     if (done) break;
@@ -428,6 +560,108 @@ async function streamChatToResponses(upstreamBody, res, responsesRequest, ids) {
 
         const delta = chunk.choices?.[0]?.delta || {};
 
+        // Handle tool_calls (only if allowTools)
+        if (allowTools && delta.tool_calls && Array.isArray(delta.tool_calls)) {
+          for (const tc of delta.tool_calls) {
+            const index = tc.index;
+            if (index == null) continue;
+
+            if (!toolCallsMap.has(index)) {
+              // New tool call - send output_item.added
+              const callId = tc.id || `call_${randomUUID().replace(/-/g, '')}`;
+              const name = tc.function?.name || '';
+              const outputIndex = TOOL_BASE_INDEX + index;
+
+              toolCallsMap.set(index, {
+                callId,
+                name,
+                outputIndex,
+                arguments: '',
+                partialArgs: ''
+              });
+
+              const fnItemInProgress = {
+                id: callId,
+                type: 'function_call',
+                status: 'in_progress',
+                call_id: callId,
+                name: name,
+                arguments: '',
+              };
+
+              sse({
+                type: 'response.output_item.added',
+                output_index: outputIndex,
+                item: fnItemInProgress,
+              });
+
+              if (name) {
+                sse({
+                  type: 'response.function_call_name.done',
+                  item_id: callId,
+                  output_index: outputIndex,
+                  name: name,
+                });
+              }
+            }
+
+            const tcData = toolCallsMap.get(index);
+
+            // Handle name update if it comes later
+            if (tc.function?.name && !tcData.name) {
+              tcData.name = tc.function.name;
+              sse({
+                type: 'response.function_call_name.done',
+                item_id: tcData.callId,
+                output_index: tcData.outputIndex,
+                name: tcData.name,
+              });
+            }
+
+            // Handle arguments delta
+            if (tc.function?.arguments && typeof tc.function.arguments === 'string') {
+              tcData.partialArgs += tc.function.arguments;
+
+              sse({
+                type: 'response.function_call_arguments.delta',
+                item_id: tcData.callId,
+                output_index: tcData.outputIndex,
+                delta: tc.function.arguments,
+              });
+            }
+
+            // Check if this tool call is done (finish_reason comes later in the choice)
+            const finishReason = chunk.choices?.[0]?.finish_reason;
+            if (finishReason === 'tool_calls' || (tc.function?.arguments && tc.function.arguments.length > 0 && chunk.choices?.[0]?.delta !== null)) {
+              tcData.arguments = tcData.partialArgs;
+
+              sse({
+                type: 'response.function_call_arguments.done',
+                item_id: tcData.callId,
+                output_index: tcData.outputIndex,
+                arguments: tcData.arguments,
+              });
+
+              const fnItemDone = {
+                id: tcData.callId,
+                type: 'function_call',
+                status: 'completed',
+                call_id: tcData.callId,
+                name: tcData.name,
+                arguments: tcData.arguments,
+              };
+
+              sse({
+                type: 'response.output_item.done',
+                output_index: tcData.outputIndex,
+                item: fnItemDone,
+              });
+            }
+          }
+          // Skip to next iteration after handling tool_calls
+          continue;
+        }
+
         // NON mescolare reasoning in output_text
         if (typeof delta.reasoning_content === 'string' && delta.reasoning_content.length) {
           reasoning += delta.reasoning_content;
@@ -495,6 +729,22 @@ async function streamChatToResponses(upstreamBody, res, responsesRequest, ids) {
     item: msgItemDone,
   });
 
+  // Build final output array: message item + any function_call items
+  const finalOutput = [msgItemDone];
+  if (allowTools && toolCallsMap.size > 0) {
+    const ordered = Array.from(toolCallsMap.entries()).sort((a, b) => a[0] - b[0]);
+    for (const [, tcData] of ordered) {
+      finalOutput.push({
+        id: tcData.callId,
+        type: 'function_call',
+        status: 'completed',
+        call_id: tcData.callId,
+        name: tcData.name,
+        arguments: tcData.arguments,
+      });
+    }
+  }
+
   const completed = buildResponseObject({
     id: responseId,
     model: responsesRequest?.model || DEFAULT_MODEL,
@@ -502,14 +752,14 @@ async function streamChatToResponses(upstreamBody, res, responsesRequest, ids) {
     created_at: createdAt,
     completed_at: nowSec(),
     input: responsesRequest?.input || [],
-    output: [msgItemDone],
+    output: finalOutput,
     tools: responsesRequest?.tools || [],
   });
 
   sse({ type: 'response.completed', response: completed });
   res.end();
 
-  log('info', `Stream completed - ${out.length} output, ${reasoning.length} reasoning`);
+  log('info', `Stream completed - ${out.length} output, ${reasoning.length} reasoning, ${toolCallsMap.size} tool_calls`);
 }
 
 /**
@@ -543,19 +793,30 @@ async function handlePostRequest(req, res) {
     return;
   }
 
+  const hasTools = requestHasTools(request);
+  const allowTools = ALLOW_TOOLS_ENV || hasTools;
+
   log('info', 'Incoming request:', {
     path,
     format: detectFormat(request),
     model: request.model,
+    allowTools,
+    toolsPresent: hasTools,
     authHeader: req.headers['authorization'] || req.headers['Authorization'] || 'none'
   });
+  if (hasTools) {
+    log('debug', 'Tools summary:', summarizeTools(request.tools));
+    if (request.tools && request.tools[0]) {
+      log('debug', 'Tool[0] shape:', summarizeToolShape(request.tools[0]));
+    }
+  }
 
   let upstreamBody;
   const format = detectFormat(request);
 
   if (format === 'responses') {
     // Translate Responses to Chat
-    upstreamBody = translateResponsesToChat(request);
+    upstreamBody = translateResponsesToChat(request, allowTools);
   } else if (format === 'chat') {
     // Pass through Chat format
     upstreamBody = request;
@@ -605,7 +866,7 @@ async function handlePostRequest(req, res) {
       });
 
       try {
-        await streamChatToResponses(upstreamResponse.body, res, request, ids);
+        await streamChatToResponses(upstreamResponse.body, res, request, ids, allowTools);
         log('info', 'Streaming completed');
       } catch (e) {
         log('error', 'Streaming error:', e);
@@ -620,7 +881,7 @@ async function handlePostRequest(req, res) {
         msgId: `msg_${randomUUID().replace(/-/g, '')}`,
       };
 
-      const response = translateChatToResponses(chatResponse, request, ids);
+      const response = translateChatToResponses(chatResponse, request, ids, allowTools);
 
       res.writeHead(200, { 'Content-Type': 'application/json' });
       res.end(JSON.stringify(response));