claude-sdk-proxy 2.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 dylanneve1
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# claude-sdk-proxy
+
+A drop-in Anthropic Messages API proxy backed by the **Claude Agent SDK**. Use your Claude Max subscription with any Anthropic API client — zero API cost.
+
+Also supports **OpenAI-compatible** endpoints so tools like LangChain, LiteLLM, and the OpenAI SDK work out of the box.
+
+```
+Any Anthropic/OpenAI client → claude-sdk-proxy (:3456) → Claude Agent SDK → Claude Max
+```
+
+## Features
+
+- **Drop-in replacement** — set `ANTHROPIC_BASE_URL=http://127.0.0.1:3456` and go
+- **OpenAI compatibility** — `/v1/chat/completions` with streaming + non-streaming
+- **Zero cost** — routes through your Claude Max subscription via the Agent SDK
+- **Full tool use** — proper `tool_use` content blocks, `stop_reason: "tool_use"`, `input_json_delta` streaming
+- **Built-in agent tools** — Claude has access to Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch
+- **API key protection** — optional `CLAUDE_PROXY_API_KEY` to secure network-exposed instances
+- **Streaming SSE** — `message_start` emitted immediately; 15s heartbeat keeps connections alive
+- **Request timeout** — configurable per-request timeout (default 5 minutes)
+- **Graceful shutdown** — SIGINT/SIGTERM handlers wait for in-flight requests
+- **Docker ready** — Dockerfile and docker-compose.yml included
+
+## Quick Start
+
+### Prerequisites
+
+1. **Claude Max subscription** + Claude CLI:
+   ```bash
+   npm install -g @anthropic-ai/claude-code
+   claude login
+   ```
+
+2. **Bun** runtime:
+   ```bash
+   curl -fsSL https://bun.sh/install | bash
+   ```
+
+### Install & Run
+
+```bash
+# From npm
+bunx claude-sdk-proxy
+
+# Or clone and run
+git clone https://github.com/dylanneve1/claude-sdk-proxy
+cd claude-sdk-proxy
+bun install
+bun run proxy
+# Proxy listening at http://127.0.0.1:3456
+```
+
+### Docker
+
+```bash
+docker compose up -d
+# or
+docker build -t claude-sdk-proxy . && docker run -p 3456:3456 -v ~/.claude:/root/.claude:ro claude-sdk-proxy
+```
+
+## Usage Examples
+
+### Anthropic SDK (Python)
+
+```python
+import anthropic
+
+client = anthropic.Anthropic(
+    base_url="http://127.0.0.1:3456",
+    api_key="dummy"  # any value works unless CLAUDE_PROXY_API_KEY is set
+)
+
+response = client.messages.create(
+    model="claude-sonnet-4-6",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.content[0].text)
+```
+
+### OpenAI SDK (Python)
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://127.0.0.1:3456/v1/chat",
+    api_key="dummy"
+)
+
+response = client.chat.completions.create(
+    model="claude-sonnet-4-6",
+    messages=[{"role": "user", "content": "Hello!"}]
+)
+print(response.choices[0].message.content)
+```
+
+### curl (Anthropic format)
+
+```bash
+curl http://127.0.0.1:3456/v1/messages \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "stream": false,
+    "messages": [{"role": "user", "content": "What is 2+2?"}]
+  }'
+```
+
+### curl (OpenAI format)
+
+```bash
+curl http://127.0.0.1:3456/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "claude-sonnet-4-6",
+    "stream": false,
+    "messages": [{"role": "user", "content": "What is 2+2?"}]
+  }'
+```
+
+### Environment variable approach
+
+```bash
+# Works with any Anthropic SDK client
+ANTHROPIC_BASE_URL=http://127.0.0.1:3456 ANTHROPIC_API_KEY=dummy your-app
+
+# Works with any OpenAI SDK client
+OPENAI_BASE_URL=http://127.0.0.1:3456/v1/chat OPENAI_API_KEY=dummy your-app
+```
+
+## Architecture
+
+### Agent mode (no caller tools)
+```
+POST /v1/messages
+  → Serialize messages → prompt
+  → Claude Agent SDK query() (maxTurns=50)
+       ├─ Built-in tools: Read, Write, Edit, Bash, Glob, Grep, ...
+       └─ MCP tools: message (optional gateway delivery)
+```
+
+### Client tool mode (caller provides tools)
+```
+POST /v1/messages  with  "tools": [...]
+  → Inject tool definitions into system prompt (all built-in tools disabled)
+  → Claude Agent SDK query() (maxTurns=1)
+       → Parse <tool_use> blocks → emit tool_use content blocks
+```
+
+Client tool mode is auto-detected when the request has a `tools` array and the system prompt doesn't contain agent session markers.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/` | Health check / service info |
+| `GET` | `/v1/models` | List available models (Anthropic format) |
+| `GET` | `/v1/models/:id` | Get model details |
+| `POST` | `/v1/messages` | Create a message (streaming or non-streaming) |
+| `POST` | `/v1/messages/count_tokens` | Estimate token count |
+| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |
+| `GET` | `/v1/chat/models` | List models (OpenAI format) |
+
+All Anthropic endpoints are also available without the `/v1` prefix.
+
+## CLI Options
+
+```
+claude-sdk-proxy [options]
+
+  -p, --port <port>   Listen port (default: 3456, env: CLAUDE_PROXY_PORT)
+  -H, --host <host>   Bind address (default: 127.0.0.1, env: CLAUDE_PROXY_HOST)
+  -d, --debug         Enable debug logging
+  -v, --version       Show version
+  -h, --help          Show help
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_PROXY_PORT` | `3456` | Proxy listen port |
+| `CLAUDE_PROXY_HOST` | `127.0.0.1` | Proxy bind address |
+| `CLAUDE_PROXY_DEBUG` | unset | Enable debug logging (`1` to enable) |
+| `CLAUDE_PROXY_API_KEY` | unset | When set, require this key via `x-api-key` or `Authorization: Bearer` header |
+| `CLAUDE_PROXY_MAX_CONCURRENT` | `5` | Max simultaneous Claude SDK sessions |
+| `CLAUDE_PROXY_TIMEOUT_MS` | `300000` | Per-request timeout in milliseconds |
+
+## Testing
+
+```bash
+# Unit tests (no running proxy needed)
+bun test
+
+# Integration tests (requires running proxy + Claude CLI auth)
+bun run test:integration
+
+# All tests
+bun run test:all
+
+# Type checking
+bun run typecheck
+```
+
+## Model Mapping
+
+| Request model string | Claude SDK tier |
+|---------------------|-----------------|
+| `*opus*` | opus |
+| `*haiku*` | haiku |
+| anything else | sonnet |
+
+## Deploying on a Server
+
+Expose the proxy as an HTTPS endpoint so you can use it from chat apps like TypingMind, ChatWise, or any Anthropic-compatible client.
+
+### 1. Install & configure the proxy
+
+```bash
+git clone https://github.com/dylanneve1/claude-sdk-proxy
+cd claude-sdk-proxy
+bun install
+```
+
+### 2. Set up systemd
+
+Create `~/.config/systemd/user/claude-sdk-proxy.service`:
+
+```ini
+[Unit]
+Description=Claude Max API Proxy
+After=network.target
+
+[Service]
+Type=simple
+WorkingDirectory=/path/to/claude-sdk-proxy
+ExecStart=/home/user/.bun/bin/bun run proxy
+Environment=PATH=/home/user/.bun/bin:/usr/local/bin:/usr/bin:/bin
+Environment=CLAUDE_PROXY_HOST=0.0.0.0
+Environment=CLAUDE_PROXY_API_KEY=your-secret-api-key
+Restart=always
+RestartSec=3
+
+[Install]
+WantedBy=default.target
+```
+
+- `CLAUDE_PROXY_HOST=0.0.0.0` binds to all interfaces (required for external access)
+- `CLAUDE_PROXY_API_KEY` protects the endpoint — clients must send this via `x-api-key` or `Authorization: Bearer` header
+
+Generate a random key:
+
+```bash
+openssl rand -hex 32
+```
+
+Enable and start:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now claude-sdk-proxy
+```
+
+### 3. Add HTTPS with Caddy
+
+A reverse proxy with auto TLS is the easiest way to get HTTPS. Get a free domain from [duckdns.org](https://www.duckdns.org) and point it at your server IP.
+
+Install Caddy:
+
+```bash
+sudo apt install caddy
+```
+
+Edit `/etc/caddy/Caddyfile`:
+
+```
+yourdomain.duckdns.org {
+    reverse_proxy localhost:3456 {
+        flush_interval -1
+    }
+}
+```
+
+`flush_interval -1` ensures SSE streaming responses are forwarded immediately without buffering.
+
+```bash
+sudo systemctl reload caddy
+```
+
+Caddy automatically provisions a Let's Encrypt TLS certificate.
+
+### 4. Connect a chat app
+
+Use your endpoint in any Anthropic-compatible chat app:
+
+| Setting | Value |
+|---------|-------|
+| **Base URL** | `https://yourdomain.duckdns.org` |
+| **API Key** | Your `CLAUDE_PROXY_API_KEY` value |
+| **Model** | `claude-opus-4-6`, `claude-sonnet-4-6`, or `claude-haiku-4-5-20251001` |
+
+## License
+
+MIT

package/bin/claude-sdk-proxy.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+
+import { startProxyServer } from "../src/proxy/server"
+
+const args = process.argv.slice(2)
+
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(`claude-sdk-proxy — Anthropic Messages API proxy backed by Claude Agent SDK
+
+Usage: claude-sdk-proxy [options]
+
+Options:
+  -p, --port <port>   Listen port (default: 3456, env: CLAUDE_PROXY_PORT)
+  -H, --host <host>   Bind address (default: 127.0.0.1, env: CLAUDE_PROXY_HOST)
+  -d, --debug         Enable debug logging (env: OPENCODE_CLAUDE_PROVIDER_DEBUG=1)
+  -v, --version       Show version
+  -h, --help          Show this help
+
+Examples:
+  claude-sdk-proxy                       # Start on 127.0.0.1:3456
+  claude-sdk-proxy -p 8080               # Start on port 8080
+  claude-sdk-proxy -H 0.0.0.0 -p 3456   # Listen on all interfaces`)
+  process.exit(0)
+}
+
+if (args.includes("--version") || args.includes("-v")) {
+  const { readFileSync } = await import("fs")
+  const { join, dirname } = await import("path")
+  const { fileURLToPath } = await import("url")
+  try {
+    const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf-8"))
+    console.log(`claude-sdk-proxy v${pkg.version}`)
+  } catch {
+    console.log("claude-sdk-proxy (unknown version)")
+  }
+  process.exit(0)
+}
+
+function getArg(flags: string[]): string | undefined {
+  for (const flag of flags) {
+    const idx = args.indexOf(flag)
+    if (idx !== -1 && idx + 1 < args.length) return args[idx + 1]
+  }
+  return undefined
+}
+
+if (args.includes("--debug") || args.includes("-d")) {
+  process.env.CLAUDE_PROXY_DEBUG = "1"
+}
+
+const port = parseInt(getArg(["-p", "--port"]) ?? process.env.CLAUDE_PROXY_PORT ?? "3456", 10)
+const host = getArg(["-H", "--host"]) ?? process.env.CLAUDE_PROXY_HOST ?? "127.0.0.1"
+
+await startProxyServer({ port, host })

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "claude-sdk-proxy",
+  "version": "2.2.0",
+  "description": "Anthropic Messages API proxy backed by Claude Agent SDK — use Claude Max with any API client",
+  "type": "module",
+  "main": "./src/proxy/server.ts",
+  "bin": {
+    "claude-sdk-proxy": "./bin/claude-sdk-proxy.ts"
+  },
+  "exports": {
+    ".": "./src/proxy/server.ts"
+  },
+  "scripts": {
+    "start": "bun run ./bin/claude-sdk-proxy.ts",
+    "proxy": "bun run ./bin/claude-sdk-proxy.ts",
+    "test": "bun test tests/helpers.test.ts tests/api.test.ts tests/openai-compat.test.ts",
+    "test:integration": "INTEGRATION=1 bun test tests/integration.test.ts tests/openai-compat.test.ts",
+    "test:all": "bun test tests/helpers.test.ts tests/api.test.ts tests/openai-compat.test.ts && INTEGRATION=1 bun test tests/integration.test.ts tests/openai-compat.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.50",
+    "hono": "^4.11.4"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.21",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-max",
+    "claude-code",
+    "anthropic",
+    "proxy",
+    "api",
+    "claude-agent-sdk",
+    "llm",
+    "openai-compatible"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dylanneve1/claude-sdk-proxy.git"
+  },
+  "homepage": "https://github.com/dylanneve1/claude-sdk-proxy#readme",
+  "bugs": {
+    "url": "https://github.com/dylanneve1/claude-sdk-proxy/issues"
+  },
+  "author": "dylanneve1",
+  "license": "MIT",
+  "private": false
+}

package/src/logger.ts

@@ -0,0 +1,13 @@
+const shouldLog = () =>
+  process.env["CLAUDE_PROXY_DEBUG"] === "1" ||
+  process.env["OPENCODE_CLAUDE_PROVIDER_DEBUG"] === "1"
+
+export const claudeLog = (message: string, extra?: Record<string, unknown>) => {
+  if (!shouldLog()) return
+  const ts = new Date().toISOString()
+  const parts = [`[${ts}] [claude-sdk-proxy]`, message]
+  if (extra && Object.keys(extra).length > 0) {
+    parts.push(JSON.stringify(extra))
+  }
+  console.debug(parts.join(" "))
+}

package/src/mcpTools.ts

@@ -0,0 +1,237 @@
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk"
+import { z } from "zod"
+import { createPrivateKey, createPublicKey, sign, randomBytes } from "node:crypto"
+import { readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { execSync } from "node:child_process"
+
+// ── Gateway helpers ──────────────────────────────────────────────────────────
+
+function b64urlEncode(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "")
+}
+
+function signPayload(privateKeyPem: string, payload: string): string {
+  const key = createPrivateKey(privateKeyPem)
+  return b64urlEncode(sign(null, Buffer.from(payload, "utf8"), key))
+}
+
+function pubKeyRawB64url(publicKeyPem: string): string {
+  const pubKey = createPublicKey(publicKeyPem)
+  const der = pubKey.export({ type: "spki", format: "der" }) as Buffer
+  return b64urlEncode(der.slice(12)) // strip 12-byte ED25519 SPKI prefix
+}
+
+let _identity: { deviceId: string; privateKeyPem: string; publicKeyPem: string } | null = null
+let _gatewayToken: string | null = null
+
+function loadGatewayConfig(): { identity: typeof _identity; token: string } {
+  if (!_identity || !_gatewayToken) {
+    const identity = JSON.parse(readFileSync(`${homedir()}/.openclaw/identity/device.json`, "utf8"))
+    const cfg = JSON.parse(readFileSync(`${homedir()}/.openclaw/openclaw.json`, "utf8"))
+    const token: string = cfg?.gateway?.auth?.token
+    if (!token) throw new Error("gateway token not found in openclaw.json")
+    _identity = identity
+    _gatewayToken = token
+  }
+  return { identity: _identity!, token: _gatewayToken! }
+}
+
+function invalidateGatewayConfig() {
+  _identity = null
+  _gatewayToken = null
+}
+
+async function sendViaGateway(
+  to: string,
+  message?: string,
+  mediaUrl?: string
+): Promise<{ ok: boolean; error?: string }> {
+  let identity: ReturnType<typeof loadGatewayConfig>["identity"]
+  let token: string
+  try {
+    const cfg = loadGatewayConfig()
+    identity = cfg.identity
+    token = cfg.token
+  } catch (e) {
+    invalidateGatewayConfig()
+    return { ok: false, error: `config error: ${e instanceof Error ? e.message : String(e)}` }
+  }
+
+  return new Promise((resolve) => {
+    const ws = new WebSocket("ws://127.0.0.1:18789")
+    let settled = false
+    let connected = false
+
+    const finish = (result: { ok: boolean; error?: string }) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      try { ws.close() } catch {}
+      resolve(result)
+    }
+
+    const timer = setTimeout(() => finish({ ok: false, error: "timeout waiting for gateway" }), 10_000)
+
+    ws.onerror = () => finish({ ok: false, error: "gateway websocket error" })
+
+    ws.onclose = (event: CloseEvent) => {
+      if (!settled) finish({ ok: false, error: `gateway closed unexpectedly (code=${event.code})` })
+    }
+
+    ws.onmessage = (event: MessageEvent) => {
+      try {
+        const frame = JSON.parse(event.data as string)
+
+        if (!connected && frame.type === "event" && frame.event === "connect.challenge") {
+          const nonce: string = frame.payload.nonce
+          const signedAtMs = Date.now()
+          const SCOPES = ["operator.admin", "operator.write"]
+          const authPayload = ["v2", identity!.deviceId, "cli", "cli", "operator",
+            SCOPES.join(","), String(signedAtMs), token, nonce].join("|")
+          ws.send(JSON.stringify({
+            type: "req", id: "conn1", method: "connect",
+            params: {
+              minProtocol: 3, maxProtocol: 3,
+              client: { id: "cli", version: "1.0.0", platform: "linux", mode: "cli" },
+              caps: [],
+              scopes: SCOPES,
+              auth: { token },
+              device: {
+                id: identity!.deviceId,
+                publicKey: pubKeyRawB64url(identity!.publicKeyPem),
+                signature: signPayload(identity!.privateKeyPem, authPayload),
+                signedAt: signedAtMs,
+                nonce
+              }
+            }
+          }))
+
+        } else if (!connected && frame.type === "res" && frame.id === "conn1") {
+          if (!frame.ok) {
+            if (frame.error?.message?.includes("unauthorized") ||
+                frame.error?.message?.includes("pairing")) {
+              invalidateGatewayConfig()
+            }
+            finish({ ok: false, error: `gateway connect failed: ${frame.error?.message || "unknown"}` })
+            return
+          }
+          connected = true
+          const sendParams: Record<string, unknown> = {
+            to,
+            channel: "telegram",
+            idempotencyKey: randomBytes(16).toString("hex")
+          }
+          if (message) sendParams.message = message
+          if (mediaUrl) sendParams.mediaUrl = mediaUrl
+          ws.send(JSON.stringify({
+            type: "req", id: "send1", method: "send",
+            params: sendParams
+          }))
+
+        } else if (connected && frame.type === "res" && frame.id === "send1") {
+          if (frame.ok) {
+            finish({ ok: true })
+          } else {
+            finish({ ok: false, error: frame.error?.message || "send failed" })
+          }
+        }
+      } catch (e) {
+        finish({ ok: false, error: `parse error: ${e instanceof Error ? e.message : String(e)}` })
+      }
+    }
+  })
+}
+
+// ── MCP server factory ───────────────────────────────────────────────────────
+// Provides only the gateway message tool. File operations, bash, etc. use
+// Claude Code's built-in tools (which are more robust and don't need MCP).
+//
+// state.messageSent is set on successful delivery. The proxy uses this to
+// auto-suppress text responses when messages were sent via tool (prevents
+// double-delivery without requiring Claude to know about any sentinel value).
+
+export interface McpServerState { messageSent: boolean }
+
+export function createMcpServer(state: McpServerState = { messageSent: false }) {
+  return createSdkMcpServer({
+    name: "opencode",
+    version: "1.0.0",
+    tools: [
+      // exec: fallback for callers whose system prompt references "exec" instead of
+      // Claude Code's built-in "Bash" tool.  Maps to child_process.execSync.
+      tool(
+        "exec",
+        "Execute a shell command and return its output. Use this for running scripts, system commands, and file operations.",
+        {
+          command: z.string().describe("The shell command to execute"),
+          timeout: z.number().optional().describe("Timeout in milliseconds (default 120000)"),
+        },
+        async (args) => {
+          try {
+            const output = execSync(args.command, {
+              encoding: "utf-8",
+              timeout: args.timeout ?? 120_000,
+              maxBuffer: 10 * 1024 * 1024,
+              cwd: "/tmp",
+            })
+            return { content: [{ type: "text", text: output || "(no output)" }] }
+          } catch (error: any) {
+            const stderr = error.stderr ? String(error.stderr) : ""
+            const stdout = error.stdout ? String(error.stdout) : ""
+            const msg = error.message ?? "Command failed"
+            return {
+              content: [{ type: "text", text: `Error: ${msg}\n${stderr}\n${stdout}`.trim() }],
+              isError: true
+            }
+          }
+        }
+      ),
+      tool(
+        "message",
+        "Send a message or file to a chat. Provide `to` (chat ID from conversation_label, e.g. '-1001426819337'), and either `message` (text) or `filePath`/`path`/`media` (absolute path to a file). Write files to /tmp/ before sending.",
+        {
+          action: z.string().optional().describe("Action to perform. Default: 'send'."),
+          to: z.string().describe("Chat ID, extracted from conversation_label."),
+          message: z.string().optional().describe("Text message to send."),
+          filePath: z.string().optional().describe("Absolute path to a file to send as attachment."),
+          path: z.string().optional().describe("Alias for filePath."),
+          media: z.string().optional().describe("Alias for filePath."),
+          caption: z.string().optional().describe("Caption for a media attachment."),
+        },
+        async (args) => {
+          try {
+            const rawMedia = args.media ?? args.path ?? args.filePath
+            let mediaUrl: string | undefined
+            if (rawMedia) {
+              if (rawMedia.startsWith("http://") || rawMedia.startsWith("https://") || rawMedia.startsWith("file://")) {
+                mediaUrl = rawMedia
+              } else {
+                const absPath = rawMedia.startsWith("/") ? rawMedia : `/tmp/${rawMedia}`
+                mediaUrl = `file://${absPath}`
+              }
+            }
+            const textMessage = args.message ?? args.caption
+            if (!textMessage && !mediaUrl) {
+              return { content: [{ type: "text", text: "Error: provide message or filePath/path/media" }], isError: true }
+            }
+            const result = await sendViaGateway(args.to, textMessage, mediaUrl)
+            if (result.ok) {
+              state.messageSent = true
+              return { content: [{ type: "text", text: `Sent to ${args.to}` }] }
+            }
+            return {
+              content: [{ type: "text", text: `Failed: ${result.error}` }],
+              isError: true
+            }
+          } catch (error) {
+            return {
+              content: [{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` }],
+              isError: true
+            }
+          }
+        }
+      )
+    ]
+  })
+}