feat: add tool/function calling support (#52)

* feat: add tool/function calling support (closes #50)

Adds OpenAI-style function tools, Anthropic tools, and Gemini function
declarations across all four API surfaces (/v1/chat/completions,
/v1/responses, /v1/messages, /v1beta/models/:model:generateContent),
both streaming and non-streaming.

OpenCode's own agent loop always executes tools itself, server-side,
and has no concept of a 'client-executed' tool call to hand off to a
caller. To bridge that gap:

- When a request includes tools, the proxy dynamically registers a
  small local MCP server (mcp-tool-bridge.js) whose tool list is
  exactly the caller's declared tool schemas, reused from a small
  fixed-size pool of slot names (OpenCode's server API has no endpoint
  to deregister an MCP server once added).
- Only those tools are enabled for that one prompt call via the
  existing tools enable/disable map; every built-in OpenCode tool
  stays disabled, same as before.
- As soon as the model proposes calling one of the bridge tools, the
  full call (name + arguments) is already present on OpenCode's event
  stream (ToolStatePending includes the parsed input even before
  execution starts) - the proxy captures it and immediately aborts the
  session before the bridge's no-op tools/call handler would ever be
  consulted, then translates the call into the caller's expected
  tool_calls / tool_use / functionCall shape instead of a text answer.

Also extends the OpenAI/Anthropic/Gemini/Responses message normalizers
to render prior tool_calls/tool_use/functionCall and their
results/tool_result/functionResponse as descriptive text when replaying
conversation history, so multi-turn tool use works end-to-end even
though sessions are stateless per-request.

- index.js: parseOpenAITools/parseAnthropicTools/parseGeminiTools +
  applyOpenAIToolChoice/applyAnthropicToolChoice/applyGeminiToolChoice,
  sanitizeToolName, tool bridge pool + registerToolBridge, unified
  runAgentTurn (event-driven turn execution shared by executePrompt
  and executePromptStreaming when tools are present), tool-call
  branches in all four response builders and SSE emitters.
- mcp-tool-bridge.js: minimal MCP stdio JSON-RPC server exposing
  caller-supplied tool schemas; tools/call is a harmless no-op since
  the proxy aborts the session before it would ever be consulted.
- index.test.js: unit tests for the new parse/tool_choice helpers and
  history round-tripping, plus end-to-end tool-calling tests for all
  four API formats (stream + non-stream).
- README.md: documents the new tools/tool_choice/toolConfig request
  fields, how the bridge mechanism works, its current limitations, and
  the new OPENCODE_LLM_PROXY_TOOL_BRIDGE_POOL_SIZE env var.

Testing:
- npm test — 138 passed (116 existing + 22 new)
- npm run lint — clean

* docs: feature tool calling prominently in README, expand discoverability keywords

- Move the Tool calling section up (right after Configuration) and add a
  runnable curl request/response example, instead of burying it near the
  bottom after How it works.
- Add a Contents section now that the README has grown to 10+ sections.
- Call out tool calling in the top-level tagline, architecture diagram,
  supported-formats table, and Why section (coding agents are now a
  first-class use case, not just chat clients).
- Note in Install that copying just index.js doesn't get you tool calling
  (needs mcp-tool-bridge.js alongside it) - use the npm plugin instead.
- package.json: mention tool/function calling in the description and add
  tool-calling/function-calling/tools/mcp/model-context-protocol/
  coding-agent/ai-agent/agentic keywords for npm search discoverability.

---------

Co-authored-by: Framewrk CI <ci@framewrklabs.ai>

Author: KochC

README.md

@@ -5,12 +5,12 @@
 [![CI](https://github.com/KochC/opencode-llm-proxy/actions/workflows/ci.yml/badge.svg)](https://github.com/KochC/opencode-llm-proxy/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**One local endpoint. Every model you have access to. Any API format.**
+**One local endpoint. Every model you have access to. Any API format. Tool calling included.**
 
 opencode-llm-proxy is an [OpenCode](https://opencode.ai) plugin that starts a local HTTP server on `http://127.0.0.1:4010`. It translates between the API format your tool speaks and whichever LLM provider OpenCode has configured — so you never reconfigure the same models twice.
 
 ```
-Your tool (OpenAI / Anthropic / Gemini SDK)
+Your tool (OpenAI / Anthropic / Gemini SDK, coding agent, etc.)
          │
          ▼  http://127.0.0.1:4010
   opencode-llm-proxy
@@ -19,7 +19,7 @@ Your tool (OpenAI / Anthropic / Gemini SDK)
   GitHub Copilot · Anthropic · Gemini · Ollama · OpenRouter · Bedrock · …
 ```
 
-**Supported API formats — all with streaming:**
+**Supported API formats — all with streaming and [tool/function calling](#tool-calling):**
 
 | Format | Endpoint |
 |---|---|
@@ -28,6 +28,24 @@ Your tool (OpenAI / Anthropic / Gemini SDK)
 | Anthropic Messages API | `POST /v1/messages` |
 | Google Gemini | `POST /v1beta/models/:model:generateContent` |
 
+**✨ Tool calling works with all four formats** — point a coding agent (Claude Code, Cursor, Continue, Cline, your own agent loop, ...) at the proxy and its `tools`/`tool_choice` calls are translated through to whatever model OpenCode has configured, with a real `tool_calls` / `tool_use` / `functionCall` response handed back. See [Tool calling](#tool-calling).
+
+---
+
+## Contents
+
+- [Why](#why)
+- [Quickstart](#quickstart)
+- [Install](#install)
+- [Configuration](#configuration)
+- [Tool calling](#tool-calling)
+- [Using with SDKs and tools](#using-with-sdks-and-tools)
+- [Finding model IDs](#finding-model-ids)
+- [API reference](#api-reference)
+- [How it works](#how-it-works)
+- [Limitations](#limitations)
+- [License](#license)
+
 ---
 
 ## Why
@@ -41,6 +59,7 @@ Most LLM tools speak exactly one API dialect. OpenCode already manages connectio
 - You want to **swap models without code changes**. Your app talks to the proxy; you change the model in OpenCode config.
 - You want to **share your models on a LAN**. Expose the proxy on `0.0.0.0` and give teammates the URL.
 - You use the **Anthropic SDK** but want to route through GitHub Copilot or Bedrock. No code change in the SDK — just point it at the proxy.
+- You're building or running a **coding agent** that needs real tool/function calling (read files, run shell commands, etc.) against whatever model OpenCode has configured. See [Tool calling](#tool-calling).
 
 ---
 
@@ -110,6 +129,8 @@ curl -o .opencode/plugins/llm-proxy.js \
   https://raw.githubusercontent.com/KochC/opencode-llm-proxy/main/index.js
 ```
 
+> Copying just `index.js` works for everything except [tool calling](#tool-calling), which also needs `mcp-tool-bridge.js` alongside it. Use the npm plugin install method if you want tool calling.
+
 ---
 
 ## Configuration
@@ -120,6 +141,7 @@ curl -o .opencode/plugins/llm-proxy.js \
 | `OPENCODE_LLM_PROXY_PORT` | `4010` | TCP port. |
 | `OPENCODE_LLM_PROXY_TOKEN` | _(unset)_ | Bearer token required on every request. Unset = no auth. |
 | `OPENCODE_LLM_PROXY_CORS_ORIGIN` | `*` | `Access-Control-Allow-Origin` value for browser clients. |
+| `OPENCODE_LLM_PROXY_TOOL_BRIDGE_POOL_SIZE` | `8` | Max concurrent in-flight requests using [tool calling](#tool-calling). |
 
 ```bash
 OPENCODE_LLM_PROXY_HOST=0.0.0.0 \
@@ -129,6 +151,67 @@ opencode
 
 ---
 
+## Tool calling
+
+The proxy supports real tool/function calling on **all four API formats** — OpenAI function tools (`tools` on `/v1/chat/completions` and `/v1/responses`), Anthropic tools (`tools` on `/v1/messages`), and Gemini function declarations (`tools` on `:generateContent`/`:streamGenerateContent`). This is what lets coding agents and other tool-using clients work through the proxy, not just plain chat.
+
+```bash
+curl http://127.0.0.1:4010/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "github-copilot/claude-sonnet-4.6",
+    "messages": [{"role": "user", "content": "What is the weather in NYC?"}],
+    "tools": [{
+      "type": "function",
+      "function": {
+        "name": "get_weather",
+        "description": "Get the current weather for a city",
+        "parameters": {
+          "type": "object",
+          "properties": { "city": { "type": "string" } },
+          "required": ["city"]
+        }
+      }
+    }]
+  }'
+```
+
+```json
+{
+  "choices": [{
+    "finish_reason": "tool_calls",
+    "message": {
+      "role": "assistant",
+      "content": null,
+      "tool_calls": [{
+        "id": "call_...",
+        "type": "function",
+        "function": { "name": "get_weather", "arguments": "{\"city\":\"NYC\"}" }
+      }]
+    }
+  }]
+}
+```
+
+Send the tool's result back on your next request (`role: "tool"` / `tool_result` / `functionResponse`, per your API's convention) alongside the full conversation history, same as any other multi-turn request — the proxy is stateless between calls either way.
+
+### How tool calling works under the hood
+
+OpenCode's own agent loop always executes tools itself, server-side, so there's no native concept of a "client-executed" tool call to hand off to. To bridge that gap, when a request includes `tools`:
+
+1. The proxy dynamically registers a small local [MCP](https://opencode.ai/docs/mcp-servers/) server whose tool list is exactly your declared tool schemas (see `mcp-tool-bridge.js`).
+2. Only those tools are enabled for that one prompt call — every built-in OpenCode tool stays disabled, same as always.
+3. As soon as the model proposes calling one of your tools, the proxy immediately aborts the OpenCode session (before the bridge's no-op handler is ever consulted) and translates the captured call name + arguments into your API's tool-call shape — `tool_calls` (OpenAI), `tool_use` (Anthropic), or a `functionCall` part (Gemini) — instead of a text answer.
+
+### Notes and current limitations
+
+- One tool call per turn — parallel/multiple simultaneous tool calls aren't supported.
+- `tool_choice: "none"` (OpenAI/Gemini `mode: "NONE"`/Anthropic `type: "none"`) disables tool calling for that request; forcing a specific named tool is supported.
+- Bridge servers are reused from a small fixed-size pool (`px_tools_0`, `px_tools_1`, ...) rather than registered fresh per request, since OpenCode's server API has no endpoint to deregister an MCP server once added. Configure the pool size with `OPENCODE_LLM_PROXY_TOOL_BRIDGE_POOL_SIZE` (default `8`) if you expect more than 8 concurrent in-flight tool-calling requests.
+- The bridge process is spawned with `node`, so `node` must be on `PATH` wherever OpenCode is running.
+
+---
+
 ## Using with SDKs and tools
 
 ### OpenAI SDK (JS/TS)
@@ -310,18 +393,18 @@ x-opencode-provider: anthropic
 Returns all models from all configured providers in OpenAI list format.
 
 ### POST /v1/chat/completions
-OpenAI Chat Completions. Required fields: `model`, `messages`. Optional: `stream`, `temperature`, `max_tokens`.
+OpenAI Chat Completions. Required fields: `model`, `messages`. Optional: `stream`, `temperature`, `max_tokens`, `tools`, `tool_choice`.
 
 ### POST /v1/responses
-OpenAI Responses API. Required fields: `model`, `input`. Optional: `instructions`, `stream`, `max_output_tokens`.
+OpenAI Responses API. Required fields: `model`, `input`. Optional: `instructions`, `stream`, `max_output_tokens`, `tools`, `tool_choice`.
 
 ### POST /v1/messages
-Anthropic Messages API. Required fields: `model`, `messages`. Optional: `system` (string or array of `{type: "text", text: string}` content blocks), `max_tokens`, `stream`.
+Anthropic Messages API. Required fields: `model`, `messages`. Optional: `system` (string or array of `{type: "text", text: string}` content blocks), `max_tokens`, `stream`, `tools`, `tool_choice`.
 
 Errors are returned in Anthropic format: `{ "type": "error", "error": { "type": "...", "message": "..." } }`.
 
 ### POST /v1beta/models/:model:generateContent
-Google Gemini non-streaming. Model name in URL path. Required field: `contents`. Optional: `systemInstruction`, `generationConfig`.
+Google Gemini non-streaming. Model name in URL path. Required field: `contents`. Optional: `systemInstruction`, `generationConfig`, `tools`, `toolConfig`.
 
 ### POST /v1beta/models/:model:streamGenerateContent
 Same as above, returns newline-delimited JSON stream.
@@ -345,9 +428,9 @@ Streaming uses OpenCode's `client.event.subscribe()` SSE stream. Text deltas are
 ## Limitations
 
 - Text only — image, audio, and file inputs are ignored
-- No tool/function calling — all OpenCode tools are disabled for proxy sessions
 - No cross-request session state — send full conversation history on every request
 - Temperature and max tokens are advisory (passed as system prompt hints)
+- Tool calling supports one call per turn — see [Tool calling](#tool-calling) above
 
 ---