@fl-penly/vertex-claude 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FL-Penly
+
+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,193 @@
+# openclaw-vertex-claude
+
+[OpenClaw](https://github.com/openclaw/openclaw) plugin that adds Claude model support via [Google Cloud Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude).
+
+Use Claude Sonnet, Opus, and other Anthropic models through your own GCP project — no direct Anthropic API key required.
+
+## How it works
+
+OpenClaw's built-in `google-vertex` provider only supports Gemini models. This plugin bridges the gap by:
+
+1. Registering a `vertex-claude` provider with `api: "anthropic-messages"`
+2. Running a lightweight local proxy (`127.0.0.1:18832`) that translates Anthropic Messages API requests into Vertex AI `rawPredict`/`streamRawPredict` calls
+3. Handling GCP authentication via Application Default Credentials (ADC)
+
+```
+OpenClaw → anthropic-messages runtime → local proxy → Vertex AI → Claude
+```
+
+## Prerequisites
+
+- [OpenClaw](https://github.com/openclaw/openclaw) `>= 2026.2.2`
+- A GCP project with the Vertex AI API enabled
+- Claude model access enabled in your GCP project ([request access](https://console.cloud.google.com/vertex-ai/publishers/anthropic))
+- `gcloud` CLI installed and authenticated
+
+## Installation
+
+```bash
+openclaw plugins install @fl-penly/vertex-claude
+```
+
+## Setup
+
+### 1. Authenticate with GCP
+
+```bash
+gcloud auth application-default login
+```
+
+### 2. Set environment variables
+
+Add these to your shell profile (`.zshrc`, `.bashrc`, etc.):
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
+export VERTEX_LOCATION="us-east5"  # optional, defaults to us-east5
+```
+
+### 3. Restart OpenClaw gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Authenticate the plugin
+
+```bash
+openclaw auth login vertex-claude
+```
+
+### 5. Verify
+
+```bash
+openclaw models list | grep vertex-claude
+```
+
+You should see:
+
+```
+vertex-claude/claude-sonnet-4-5            text+image 195k     yes   yes   configured
+vertex-claude/claude-opus-4-5              text+image 195k     yes   yes   configured
+vertex-claude/claude-opus-4-6              text+image 195k     yes   yes   configured
+...
+```
+
+## Usage
+
+Switch to a Vertex Claude model:
+
+```
+/model vertex-claude/claude-sonnet-4-5
+```
+
+Or set up aliases in `openclaw.json`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "models": {
+        "vertex-claude/claude-sonnet-4-5": { "alias": "vc-sonnet" },
+        "vertex-claude/claude-opus-4-5": { "alias": "vc-opus" },
+        "vertex-claude/claude-opus-4-6": { "alias": "vc-opus46" }
+      }
+    }
+  }
+}
+```
+
+Then switch with `/model vc-sonnet`.
+
+## Available models
+
+| Model ID | Description | Reasoning |
+|----------|-------------|-----------|
+| `claude-sonnet-4-5` | Claude Sonnet 4.5 | No |
+| `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking | Yes |
+| `claude-opus-4-5` | Claude Opus 4.5 | No |
+| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking | Yes |
+| `claude-opus-4-6` | Claude Opus 4.6 | Yes |
+
+## Configuration
+
+### Environment variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GOOGLE_CLOUD_PROJECT` | Yes | — | GCP project ID |
+| `VERTEX_LOCATION` | No | `us-east5` | Vertex AI region |
+| `VERTEX_CLAUDE_PORT` | No | `18832` | Local proxy port |
+
+### Vertex AI regions with Claude support
+
+Not all GCP regions support Claude models. Check the [Anthropic on Vertex AI docs](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-claude#regions) for the latest availability. Common regions:
+
+- `us-east5`
+- `us-central1`
+- `europe-west1`
+
+## Troubleshooting
+
+### "GOOGLE_CLOUD_PROJECT is not set"
+
+Export the environment variable before starting OpenClaw:
+
+```bash
+export GOOGLE_CLOUD_PROJECT="your-project-id"
+openclaw gateway restart
+```
+
+### "Failed to get GCP access token"
+
+Re-authenticate:
+
+```bash
+gcloud auth application-default login
+```
+
+### Models show `auth: missing`
+
+Run `openclaw auth login vertex-claude` to set up credentials.
+
+### Proxy not starting (port conflict)
+
+Change the proxy port:
+
+```bash
+export VERTEX_CLAUDE_PORT=18833
+openclaw gateway restart
+```
+
+### 403 from Vertex AI
+
+Ensure Claude models are enabled in your GCP project. Visit [Vertex AI Model Garden](https://console.cloud.google.com/vertex-ai/publishers/anthropic) and enable the models you want to use.
+
+## AI-assisted setup
+
+Have an AI assistant set this up for you — just share the setup guide:
+
+```
+https://github.com/FL-Penly/vertex-claude/blob/main/SETUP.md
+```
+
+Paste the URL into Claude Code, OpenClaw, or any AI coding assistant. It will follow the steps automatically.
+
+## Development
+
+```bash
+git clone https://github.com/FL-Penly/vertex-claude.git
+cd vertex-claude
+npm install
+
+# Link for local development
+ln -s "$(pwd)" ~/.openclaw/extensions/vertex-claude
+
+# Enable the plugin
+openclaw plugins enable vertex-claude
+openclaw gateway restart
+```
+
+## License
+
+MIT

package/SETUP.md

@@ -0,0 +1,164 @@
+# AI Setup Guide — openclaw-vertex-claude
+
+> This document is designed for AI coding assistants (Claude Code, OpenClaw, etc.) to follow automatically. If you are an AI assistant, execute the steps below in order. If any step fails, stop and report the error.
+
+## What this plugin does
+
+Adds Claude model support (Sonnet, Opus) to OpenClaw via Google Cloud Vertex AI. It runs a local proxy that translates Anthropic Messages API calls into Vertex AI rawPredict requests.
+
+## Step 1: Check prerequisites
+
+Run these checks. ALL must pass before proceeding:
+
+```bash
+# OpenClaw must be installed (>= 2026.2.2)
+openclaw --version
+
+# gcloud CLI must be installed
+gcloud --version
+
+# Node.js >= 20
+node --version
+
+# GCP project must be set
+echo $GOOGLE_CLOUD_PROJECT
+```
+
+If `GOOGLE_CLOUD_PROJECT` is empty, ask the user for their GCP project ID, then:
+
+```bash
+# Add to shell profile (~/.zshrc or ~/.bashrc)
+echo 'export GOOGLE_CLOUD_PROJECT="<project-id>"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+Optionally set `VERTEX_LOCATION` (defaults to `us-east5`):
+
+```bash
+echo 'export VERTEX_LOCATION="us-east5"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+## Step 2: Ensure GCP authentication
+
+```bash
+gcloud auth application-default login
+```
+
+If already authenticated, this can be skipped. Verify with:
+
+```bash
+gcloud auth application-default print-access-token > /dev/null 2>&1 && echo "OK" || echo "NEED LOGIN"
+```
+
+## Step 3: Install the plugin
+
+```bash
+openclaw plugins install @fl-penly/vertex-claude
+```
+
+If install fails (e.g. not yet published to npm), install from source:
+
+```bash
+git clone https://github.com/FL-Penly/vertex-claude.git ~/.openclaw/extensions/vertex-claude
+cd ~/.openclaw/extensions/vertex-claude
+npm install --production
+```
+
+Then enable manually by adding to `~/.openclaw/openclaw.json` under `plugins.entries`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "vertex-claude": {
+        "enabled": true
+      }
+    }
+  }
+}
+```
+
+## Step 4: Configure model aliases (optional but recommended)
+
+Add model aliases to `~/.openclaw/openclaw.json` under `agents.defaults.models`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "models": {
+        "vertex-claude/claude-sonnet-4-5": { "alias": "vc-sonnet" },
+        "vertex-claude/claude-opus-4-5": { "alias": "vc-opus" },
+        "vertex-claude/claude-opus-4-6": { "alias": "vc-opus46" }
+      }
+    }
+  }
+}
+```
+
+IMPORTANT: Merge these into the existing JSON structure. Do NOT overwrite the file. Use `jq` or read-modify-write.
+
+## Step 5: Restart the gateway
+
+```bash
+openclaw gateway restart
+```
+
+## Step 6: Verify installation
+
+```bash
+# Check models are registered
+openclaw models list | grep vertex-claude
+
+# Expected output (3+ lines with "yes yes configured"):
+# vertex-claude/claude-sonnet-4-5  text+image 195k  yes  yes  configured
+# vertex-claude/claude-opus-4-5    text+image 195k  yes  yes  configured
+# vertex-claude/claude-opus-4-6    text+image 195k  yes  yes  configured
+
+# Check proxy is running
+curl -s http://127.0.0.1:18832/health
+# Expected: OK
+```
+
+If models show `auth: missing`, run:
+
+```bash
+openclaw auth login vertex-claude
+```
+
+## Step 7: Test end-to-end (optional)
+
+```bash
+curl -s http://127.0.0.1:18832/v1/messages \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: vertex-proxy-local" \
+  -d '{
+    "model": "claude-sonnet-4-5",
+    "max_tokens": 64,
+    "messages": [{"role": "user", "content": "Say hi in one word"}]
+  }' | head -c 200
+```
+
+Expected: A JSON response with `"type": "message"` and a content block.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `GOOGLE_CLOUD_PROJECT is not set` | `export GOOGLE_CLOUD_PROJECT=your-project-id` then restart gateway |
+| `Failed to get GCP access token` | `gcloud auth application-default login` |
+| Models show `auth: missing` | `openclaw auth login vertex-claude` |
+| Port 18832 in use | `export VERTEX_CLAUDE_PORT=18833` then restart gateway |
+| 403 from Vertex AI | Enable Claude models at https://console.cloud.google.com/vertex-ai/publishers/anthropic |
+| Plugin not loading | Check `~/.openclaw/logs/gateway.err.log` for errors |
+
+## Available models after setup
+
+| Alias | Full ID | Use for |
+|-------|---------|---------|
+| `vc-sonnet` | `vertex-claude/claude-sonnet-4-5` | General coding, fast |
+| `vc-opus` | `vertex-claude/claude-opus-4-5` | Complex reasoning |
+| `vc-opus46` | `vertex-claude/claude-opus-4-6` | Latest, extended thinking |
+
+Switch model: `/model vc-sonnet`

package/index.ts

@@ -0,0 +1,153 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import type { ProxyHandle } from "./proxy.js";
+
+const DEFAULT_PORT = 18832;
+
+function resolvePort(): number {
+  return Number(process.env.VERTEX_CLAUDE_PORT) || DEFAULT_PORT;
+}
+
+const CLAUDE_MODELS = [
+  {
+    id: "claude-sonnet-4-5",
+    name: "Claude Sonnet 4.5 (Vertex)",
+    reasoning: false,
+    input: ["text", "image"] as string[],
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 8192,
+  },
+  {
+    id: "claude-sonnet-4-5-thinking",
+    name: "Claude Sonnet 4.5 Thinking (Vertex)",
+    reasoning: true,
+    input: ["text", "image"] as string[],
+    cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+    contextWindow: 200000,
+    maxTokens: 16000,
+  },
+  {
+    id: "claude-opus-4-5",
+    name: "Claude Opus 4.5 (Vertex)",
+    reasoning: false,
+    input: ["text", "image"] as string[],
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 8192,
+  },
+  {
+    id: "claude-opus-4-5-thinking",
+    name: "Claude Opus 4.5 Thinking (Vertex)",
+    reasoning: true,
+    input: ["text", "image"] as string[],
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+  {
+    id: "claude-opus-4-6",
+    name: "Claude Opus 4.6 (Vertex)",
+    reasoning: true,
+    input: ["text", "image"] as string[],
+    cost: { input: 15, output: 75, cacheRead: 1.5, cacheWrite: 18.75 },
+    contextWindow: 200000,
+    maxTokens: 32000,
+  },
+];
+
+let proxyHandle: ProxyHandle | null = null;
+
+const plugin = {
+  id: "vertex-claude",
+  name: "Vertex Claude",
+  description: "Claude models via Google Vertex AI",
+  configSchema: emptyPluginConfigSchema(),
+
+  register(api: OpenClawPluginApi) {
+    const port = resolvePort();
+    const baseUrl = "http://127.0.0.1:" + port;
+
+    api.registerProvider({
+      id: "vertex-claude",
+      label: "Vertex AI Claude",
+      aliases: ["vc"],
+      envVars: ["GOOGLE_CLOUD_PROJECT", "VERTEX_LOCATION"],
+      models: {
+        baseUrl,
+        apiKey: "vertex-proxy-local",
+        api: "anthropic-messages",
+        models: CLAUDE_MODELS,
+      },
+      auth: [
+        {
+          id: "gcp-adc",
+          label: "GCP Application Default Credentials",
+          hint: "Uses gcloud ADC — run: gcloud auth application-default login",
+          kind: "custom" as const,
+          run: async () => {
+            const project = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT;
+            if (!project) {
+              throw new Error(
+                "GOOGLE_CLOUD_PROJECT is not set. Export it before starting OpenClaw:\n" +
+                "  export GOOGLE_CLOUD_PROJECT=your-project-id",
+              );
+            }
+
+            const { GoogleAuth } = await import("google-auth-library");
+            const gauth = new GoogleAuth({ scopes: ["https://www.googleapis.com/auth/cloud-platform"] });
+            const token = await gauth.getAccessToken();
+            if (!token) {
+              throw new Error(
+                "Failed to get GCP access token. Run:\n  gcloud auth application-default login",
+              );
+            }
+
+            const location = process.env.VERTEX_LOCATION || process.env.GOOGLE_CLOUD_LOCATION || "us-east5";
+
+            return {
+              profiles: [
+                {
+                  profileId: "vertex-claude:gcp-adc",
+                  credential: {
+                    type: "api_key" as const,
+                    provider: "vertex-claude",
+                    key: "vertex-proxy-local",
+                  },
+                },
+              ],
+              defaultModel: "vertex-claude/claude-sonnet-4-5",
+              notes: [
+                "Using GCP project: " + project,
+                "Vertex location: " + location,
+                "Auth: Application Default Credentials",
+              ],
+            };
+          },
+        },
+      ],
+    });
+
+    api.registerService({
+      id: "vertex-claude-proxy",
+      start: async (ctx) => {
+        const { startProxy } = await import("./proxy.js");
+        proxyHandle = await startProxy({
+          port,
+          logger: {
+            info: (msg: string) => ctx.logger.info(msg),
+            error: (msg: string) => ctx.logger.error(msg),
+          },
+        });
+      },
+      stop: async () => {
+        if (proxyHandle) {
+          await proxyHandle.stop();
+          proxyHandle = null;
+        }
+      },
+    });
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "vertex-claude",
+  "providers": ["vertex-claude"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@fl-penly/vertex-claude",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "OpenClaw plugin: use Claude models via Google Cloud Vertex AI",
+  "license": "MIT",
+  "author": "FL-Penly",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FL-Penly/vertex-claude.git"
+  },
+  "homepage": "https://github.com/FL-Penly/vertex-claude#readme",
+  "bugs": {
+    "url": "https://github.com/FL-Penly/vertex-claude/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "claude",
+    "vertex-ai",
+    "google-cloud",
+    "anthropic",
+    "ai",
+    "llm",
+    "plugin"
+  ],
+  "files": [
+    "index.ts",
+    "proxy.ts",
+    "openclaw.plugin.json",
+    "LICENSE",
+    "README.md",
+    "SETUP.md"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "google-auth-library": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": ">=2026.2.2",
+    "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.2.2"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/proxy.ts

@@ -0,0 +1,213 @@
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { GoogleAuth } from "google-auth-library";
+
+export interface ProxyLogger {
+  info(msg: string): void;
+  error(msg: string): void;
+}
+
+export interface ProxyHandle {
+  server: Server;
+  port: number;
+  stop: () => Promise<void>;
+}
+
+const DEFAULT_PORT = 18832;
+const DEFAULT_LOCATION = "us-east5";
+const REQUEST_TIMEOUT_MS = 300_000; // 5 minutes — long for streaming responses
+const MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024; // 10 MB
+
+function resolveEnv() {
+  const project = process.env.GOOGLE_CLOUD_PROJECT || process.env.GCLOUD_PROJECT || "";
+  const location = process.env.VERTEX_LOCATION || process.env.GOOGLE_CLOUD_LOCATION || DEFAULT_LOCATION;
+  return { project, location };
+}
+
+function jsonError(res: ServerResponse, status: number, message: string) {
+  const body = JSON.stringify({ type: "error", error: { type: "proxy_error", message } });
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(body);
+}
+
+async function readBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let totalBytes = 0;
+  for await (const chunk of req) {
+    totalBytes += (chunk as Buffer).length;
+    if (totalBytes > MAX_REQUEST_BODY_BYTES) {
+      throw new Error(`Request body exceeds maximum size of ${MAX_REQUEST_BODY_BYTES} bytes`);
+    }
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function startProxy(opts: {
+  port?: number;
+  logger?: ProxyLogger;
+}): Promise<ProxyHandle> {
+  const port = opts.port || (Number(process.env.VERTEX_CLAUDE_PORT) || DEFAULT_PORT);
+  const log = opts.logger || { info: console.log, error: console.error };
+
+  const auth = new GoogleAuth({ scopes: ["https://www.googleapis.com/auth/cloud-platform"] });
+
+  async function getAccessToken(retries: number = 1): Promise<string> {
+    let lastErr: Error | undefined;
+    for (let i = 0; i <= retries; i++) {
+      try {
+        const token = await auth.getAccessToken();
+        if (token) return token;
+      } catch (err) {
+        lastErr = err instanceof Error ? err : new Error(String(err));
+        if (i < retries) {
+          log.info(`[vertex-claude] Token fetch failed, retrying (${i + 1}/${retries})...`);
+        }
+      }
+    }
+    throw lastErr || new Error("Failed to get GCP access token. Run: gcloud auth application-default login");
+  }
+
+  const server = createServer(async (req, res) => {
+    if (req.method === "GET" && req.url === "/health") {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("OK");
+      return;
+    }
+
+    if (req.method !== "POST" || req.url !== "/v1/messages") {
+      jsonError(res, 404, "Not found: " + req.method + " " + req.url);
+      return;
+    }
+
+    try {
+      const { project, location } = resolveEnv();
+      if (!project) {
+        jsonError(res, 500, "GOOGLE_CLOUD_PROJECT env var is required. Export it before starting OpenClaw.");
+        return;
+      }
+
+      const rawBody = await readBody(req);
+      let body: Record<string, unknown>;
+      try {
+        body = JSON.parse(rawBody.toString("utf-8"));
+      } catch (_parseErr) {
+        jsonError(res, 400, "Invalid JSON body");
+        return;
+      }
+
+      const modelId = body.model as string;
+      if (!modelId) {
+        jsonError(res, 400, "Missing 'model' field in request body");
+        return;
+      }
+
+      const isStream = body.stream === true;
+
+      // Vertex AI requires: model in URL path, anthropic_version in body (not header)
+      const endpoint = isStream ? "streamRawPredict" : "rawPredict";
+      const vertexUrl =
+        "https://" + location + "-aiplatform.googleapis.com/v1/projects/" + project +
+        "/locations/" + location + "/publishers/anthropic/models/" + modelId + ":" + endpoint;
+
+      const vertexBody: Record<string, unknown> = {
+        ...body,
+        anthropic_version: "vertex-2023-10-16",
+      };
+      delete vertexBody.model;
+      const vertexPayload = JSON.stringify(vertexBody);
+
+      const accessToken = await getAccessToken(1);
+
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+
+      let vertexRes: Response;
+      try {
+        vertexRes = await fetch(vertexUrl, {
+          method: "POST",
+          headers: {
+            "Authorization": "Bearer " + accessToken,
+            "Content-Type": "application/json",
+          },
+          body: vertexPayload,
+          signal: controller.signal,
+        });
+      } catch (fetchErr) {
+        clearTimeout(timeout);
+        const msg = fetchErr instanceof Error ? fetchErr.message : String(fetchErr);
+        if (msg.includes("aborted")) {
+          jsonError(res, 504, "Upstream request to Vertex AI timed out after " + (REQUEST_TIMEOUT_MS / 1000) + "s");
+        } else {
+          jsonError(res, 502, "Failed to connect to Vertex AI: " + msg);
+        }
+        return;
+      }
+
+      if (!vertexRes.ok) {
+        clearTimeout(timeout);
+        const errBody = await vertexRes.text();
+        log.error("[vertex-claude] Vertex returned " + vertexRes.status + ": " + errBody.slice(0, 500));
+        const contentType = vertexRes.headers.get("content-type") || "application/json";
+        res.writeHead(vertexRes.status, { "Content-Type": contentType });
+        res.end(errBody);
+        return;
+      }
+
+      const contentType = vertexRes.headers.get("content-type") || "application/json";
+      res.writeHead(vertexRes.status, { "Content-Type": contentType });
+
+      if (!vertexRes.body) {
+        clearTimeout(timeout);
+        const text = await vertexRes.text();
+        res.end(text);
+        return;
+      }
+
+      const reader = (vertexRes.body as ReadableStream<Uint8Array>).getReader();
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          res.write(value);
+        }
+      } catch (streamErr) {
+        const msg = streamErr instanceof Error ? streamErr.message : String(streamErr);
+        log.error("[vertex-claude] Stream error: " + msg);
+      } finally {
+        clearTimeout(timeout);
+        res.end();
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      log.error("[vertex-claude] Proxy error: " + msg);
+      if (!res.headersSent) {
+        jsonError(res, 500, msg);
+      } else {
+        res.end();
+      }
+    }
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    const onError = (err: Error) => {
+      server.off("error", onError);
+      reject(err);
+    };
+    server.once("error", onError);
+    server.listen(port, "127.0.0.1", () => {
+      server.off("error", onError);
+      log.info("[vertex-claude] Proxy listening on http://127.0.0.1:" + port);
+      resolve();
+    });
+  });
+
+  const stop = () =>
+    new Promise<void>((resolve) => {
+      server.close(() => {
+        log.info("[vertex-claude] Proxy stopped");
+        resolve();
+      });
+    });
+
+  return { server, port, stop };
+}