conversun
diff --git a/‎examples/plugin/Makefile‎
Lines changed: 1 addition & 1 deletion b/‎examples/plugin/Makefile‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎examples/plugin/README.md‎
Lines changed: 1 addition & 0 deletions b/‎examples/plugin/README.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎examples/plugin/claude-web-search-router/README.md‎
Lines changed: 175 additions & 0 deletions b/‎examples/plugin/claude-web-search-router/README.md‎
Lines changed: 175 additions & 0 deletions
diff --git a/‎examples/plugin/claude-web-search-router/go/claude_response.go‎
Lines changed: 173 additions & 0 deletions b/‎examples/plugin/claude-web-search-router/go/claude_response.go‎
Lines changed: 173 additions & 0 deletions
diff --git a/‎examples/plugin/claude-web-search-router/go/config_test.go‎
Lines changed: 22 additions & 0 deletions b/‎examples/plugin/claude-web-search-router/go/config_test.go‎
Lines changed: 22 additions & 0 deletions
@@ -1,4 +1,4 @@
-EXAMPLES := simple model auth frontend-auth executor protocol-format request-translator request-normalizer response-translator response-normalizer thinking usage cli management-api host-callback host-callback-auth-files host-model-callback
+EXAMPLES := simple model auth frontend-auth executor protocol-format request-translator request-normalizer response-translator response-normalizer thinking usage cli management-api host-callback host-callback-auth-files host-model-callback claude-web-search-router
 LANGUAGES := go c rust
 BIN_DIR := $(CURDIR)/bin
 BUILD_DIR := $(BIN_DIR)/build
 
@@ -16,6 +16,7 @@ This directory contains standard dynamic library plugin examples for the CLIProx
 - `request-normalizer/`: request normalization capability only.
 - `codex-service-tier/`: Go-only request normalizer that sets Codex `gpt-5.5` requests to the priority service tier when enabled.
 - `scheduler/`: Go-only scheduler that can select a configured auth ID, delegate to a built-in scheduler, or deny picks.
+- `claude-web-search-router/`: ModelRouter + executor for Claude Code built-in `web_search` (antigravity / codex / xai / Tavily). See `claude-web-search-router/README.md`.
 - `response-translator/`: response translation capability only.
 - `response-normalizer/`: response normalization capability only.
 - `thinking/`: thinking applier capability only.
 
@@ -0,0 +1,175 @@
+# Claude Code Web Search Router (ModelRouter example)
+
+This plugin demonstrates **ModelRouter** on Claude Code built-in `web_search` requests (see `temp/1.json` in the repo root for a captured request/response).
+
+## What it detects
+
+- Inbound protocol `claude` / `anthropic`
+- `tools[]` with `type` `web_search_20250305` or `web_search_20260209`
+- Optional Claude Code heuristics: system text like “web search tool use”, or user text
+  `Perform a web search for the query: …`
+
+## Routes (`route` config)
+
+| Value                    | Behavior                                                                                                                                                                                                                                                                                                  |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fallback` (**default**) | Plugin **executor** runs **antigravity → codex → xai → tavily** (built-ins via `host.model.*`, Tavily in-plugin). On **429/503/502**, tries the next backend in the same request. Backends that fail often are **deprioritized on later requests** (in-memory penalty; no extra config). |
+| `antigravity_google` / `codex_web_search` / `xai_web_search` / `tavily` | Same orchestration for that backend’s chain member(s): execution retry + penalty apply when multiple backends are eligible. |
+| `default_provider`             | `default_provider` + optional `default_provider_model` via built-in AuthManager (not orchestrated).                                                                                                                                                                                                                          |
+Routing for `fallback` requires at least one runnable backend (providers in `AvailableProviders` where needed, resolvable antigravity model, or `tavily_api_keys`).
+
+### xAI web search notes (aligned with upstream docs)
+
+- **Model**: xAI documents `grok-4.3` for server-side `web_search`. This example sets `TargetModel` to **`grok-4.3`** when `xai_model` is empty (do not forward `claude-sonnet-4-6` to xAI).
+- **Request shape**: Responses API `input` + `tools[]` with `"type": "web_search"`. Optional `filters.allowed_domains` / `filters.excluded_domains` (max 5 each, mutually exclusive).
+- **Claude mapping today**: `internal/translator/codex/claude` copies Claude `allowed_domains` → `filters.allowed_domains`. Claude `blocked_domains` is **not** mapped to `excluded_domains` yet.
+- **Executor**: `xai_executor` normalizes tools (drops unsupported `external_web_access` if present) and posts to `/responses`.
+- **Response**: Citations / server tool metadata come back through OpenAI Responses SSE and are converted toward Claude `server_tool_use` / `web_search_tool_result` where the response translator supports it.
+
+## Configuration
+
+Plugin config lives under `plugins.configs.claude-web-search-router` (key must match the plugin name). Load the shared library via `plugins.path`.
+
+### Recommended: fallback chain (default)
+
+Tries **antigravity → codex → xai → tavily**; configure `tavily_api_keys` so the last step can succeed when built-in providers are missing or unavailable.
+
+```yaml
+plugins:
+  path:
+    - /absolute/path/to/examples/plugin/bin/claude-web-search-router-go.dylib
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: fallback
+      antigravity_model: "" # empty: registry lookup, then first supports_web_search
+      codex_model: "gpt-5.4-mini"
+      xai_model: "grok-4.3"
+      tavily_api_keys:
+        - "tvly-xxxxxxxx"
+        # - "tvly-yyyyyyyy" # optional: round-robin
+      require_web_search_only: true
+```
+
+Omit `route` to use the same default (`fallback`).
+
+### Minimal fallback (Tavily as last resort only)
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: fallback
+      tavily_api_keys:
+        - "tvly-xxxxxxxx"
+      require_web_search_only: true
+```
+
+### Single backend (no fallback)
+
+**Antigravity only:**
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: antigravity_google
+      antigravity_model: "gemini-3.1-flash-lite"
+      require_web_search_only: true
+```
+
+**Codex only:**
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: codex_web_search
+      codex_model: "gpt-5.4-mini"
+      require_web_search_only: true
+```
+
+**xAI only:**
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: xai_web_search
+      xai_model: "grok-4.3"
+      require_web_search_only: true
+```
+
+**Tavily only (plugin executor):**
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: tavily
+      tavily_api_keys:
+        - "tvly-xxxxxxxx"
+      require_web_search_only: true
+```
+
+**Built-in provider via `default_provider`:**
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: true
+      priority: 20
+      route: default_provider
+      default_provider: claude
+      default_provider_model: ""
+      require_web_search_only: true
+```
+
+### Disable or relax detection
+
+```yaml
+plugins:
+  configs:
+    claude-web-search-router:
+      enabled: false # plugin declines; host may use default Claude path
+
+# Or keep enabled but allow mixed tool lists:
+    claude-web-search-router:
+      enabled: true
+      route: fallback
+      require_web_search_only: false
+```
+
+### Config field reference
+
+| Field | Description |
+| ----- | ----------- |
+| `enabled` | `false` → `Handled: false` for all web_search matches |
+| `priority` | Host plugin order for ModelRouter (higher runs earlier; see main repo plugins docs) |
+| `route` | `fallback` (default), `antigravity_google`, `codex_web_search`, `xai_web_search`, `tavily`, `default_provider` |
+| `antigravity_model` | Antigravity execution model; never the client Claude model name |
+| `codex_model` | Codex model; empty → `gpt-5.4-mini` |
+| `xai_model` | xAI model; empty → `grok-4.3` |
+| `default_provider` / `default_provider_model` | Used when `route=default_provider` |
+| `tavily_api_keys` | Required for `route=tavily` or fallback last step |
+| `require_web_search_only` | `true` matches Claude Code–style exclusive `web_search` tools |
+
+## Build
+
+```bash
+make -C examples/plugin bin/claude-web-search-router-go.dylib
+```
+
+Use `.so` on Linux and `.dll` on Windows. Point `plugins.path` at the built artifact.
@@ -0,0 +1,173 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"time"
+)
+
+type claudeStreamBuilder struct {
+	model       string
+	messageID   string
+	toolUseID   string
+	index       int
+	inputTokens int
+}
+
+func newClaudeStreamBuilder(model string) *claudeStreamBuilder {
+	model = strings.TrimSpace(model)
+	if model == "" {
+		model = "claude-sonnet-4-6"
+	}
+	now := time.Now().UnixNano()
+	return &claudeStreamBuilder{
+		model:       model,
+		messageID:   fmt.Sprintf("msg_%x", now),
+		toolUseID:   fmt.Sprintf("srvtoolu_%d", now),
+		inputTokens: 85,
+	}
+}
+
+func (b *claudeStreamBuilder) buildStreamWithQuery(query string, hits []claudeWebSearchHit, answer string) []byte {
+	var chunks []string
+	chunks = append(chunks, b.event("message_start", map[string]any{
+		"type": "message_start",
+		"message": map[string]any{
+			"id": b.messageID, "type": "message", "role": "assistant", "content": []any{},
+			"model": b.model, "stop_reason": nil, "stop_sequence": nil,
+			"usage": map[string]any{"input_tokens": b.inputTokens, "output_tokens": 0},
+		},
+	}))
+	chunks = append(chunks, b.blockStart(b.index, map[string]any{
+		"type": "server_tool_use", "id": b.toolUseID, "name": "web_search", "input": map[string]any{},
+	}))
+	partial, _ := json.Marshal(map[string]string{"query": query})
+	chunks = append(chunks, b.event("content_block_delta", map[string]any{
+		"type": "content_block_delta", "index": b.index,
+		"delta": map[string]any{"type": "input_json_delta", "partial_json": string(partial)},
+	}))
+	chunks = append(chunks, b.event("content_block_stop", map[string]any{"type": "content_block_stop", "index": b.index}))
+	b.index++
+
+	resultContent := webSearchResultBlocks(hits)
+	chunks = append(chunks, b.blockStart(b.index, map[string]any{
+		"type": "web_search_tool_result", "tool_use_id": b.toolUseID, "content": resultContent,
+	}))
+	chunks = append(chunks, b.event("content_block_stop", map[string]any{"type": "content_block_stop", "index": b.index}))
+	b.index++
+
+	text := composeAnswerText(answer, hits)
+	outputTokens := estimateTokens(text)
+	chunks = append(chunks, b.blockStart(b.index, map[string]any{"type": "text", "text": ""}))
+	chunks = append(chunks, b.event("content_block_delta", map[string]any{
+		"type": "content_block_delta", "index": b.index,
+		"delta": map[string]any{"type": "text_delta", "text": text},
+	}))
+	chunks = append(chunks, b.event("content_block_stop", map[string]any{"type": "content_block_stop", "index": b.index}))
+
+	chunks = append(chunks, b.event("message_delta", map[string]any{
+		"type":  "message_delta",
+		"delta": map[string]any{"stop_reason": "end_turn", "stop_sequence": nil},
+		"usage": map[string]any{
+			"input_tokens": b.inputTokens, "output_tokens": outputTokens,
+			"server_tool_use": map[string]any{"web_search_requests": 1},
+		},
+	}))
+	chunks = append(chunks, b.event("message_stop", map[string]any{"type": "message_stop"}))
+	return []byte(strings.Join(chunks, ""))
+}
+
+func (b *claudeStreamBuilder) buildMessageJSON(query string, hits []claudeWebSearchHit, answer string) []byte {
+	text := composeAnswerText(answer, hits)
+	content := []map[string]any{
+		{"type": "server_tool_use", "id": b.toolUseID, "name": "web_search", "input": map[string]string{"query": query}},
+		{"type": "web_search_tool_result", "tool_use_id": b.toolUseID, "content": webSearchResultBlocks(hits)},
+		{"type": "text", "text": text},
+	}
+	out := map[string]any{
+		"id": b.messageID, "type": "message", "role": "assistant", "model": b.model,
+		"content": content, "stop_reason": "end_turn", "stop_sequence": nil,
+		"usage": map[string]any{
+			"input_tokens": b.inputTokens, "output_tokens": estimateTokens(text),
+			"server_tool_use": map[string]any{"web_search_requests": 1},
+		},
+	}
+	raw, _ := json.Marshal(out)
+	return raw
+}
+
+func webSearchResultBlocks(hits []claudeWebSearchHit) []map[string]any {
+	resultContent := make([]map[string]any, 0, len(hits))
+	for _, hit := range hits {
+		title := hit.Title
+		if title == "" {
+			title = hostFromURL(hit.URL)
+		}
+		resultContent = append(resultContent, map[string]any{
+			"type": "web_search_result", "title": title, "url": hit.URL, "page_age": nil,
+		})
+	}
+	return resultContent
+}
+
+func (b *claudeStreamBuilder) event(eventType string, data map[string]any) string {
+	raw, _ := json.Marshal(data)
+	return fmt.Sprintf("event: %s\ndata: %s\n\n", eventType, string(raw))
+}
+
+func (b *claudeStreamBuilder) blockStart(index int, block map[string]any) string {
+	return b.event("content_block_start", map[string]any{
+		"type": "content_block_start", "index": index, "content_block": block,
+	})
+}
+
+func composeAnswerText(answer string, hits []claudeWebSearchHit) string {
+	if strings.TrimSpace(answer) != "" {
+		return answer
+	}
+	if len(hits) == 0 {
+		return "No web search results were returned."
+	}
+	var buf strings.Builder
+	for i, hit := range hits {
+		if i > 0 {
+			buf.WriteString("\n\n")
+		}
+		if hit.Title != "" {
+			buf.WriteString(hit.Title)
+			buf.WriteString("\n")
+		}
+		if hit.URL != "" {
+			buf.WriteString(hit.URL)
+			buf.WriteString("\n")
+		}
+		if hit.Snippet != "" {
+			buf.WriteString(hit.Snippet)
+		}
+	}
+	return buf.String()
+}
+
+func hostFromURL(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+	withoutScheme := raw
+	if idx := strings.Index(raw, "://"); idx >= 0 {
+		withoutScheme = raw[idx+3:]
+	}
+	if slash := strings.Index(withoutScheme, "/"); slash >= 0 {
+		return withoutScheme[:slash]
+	}
+	return withoutScheme
+}
+
+func estimateTokens(text string) int {
+	n := len([]rune(text)) / 4
+	if n < 1 {
+		return 1
+	}
+	return n
+}
@@ -0,0 +1,22 @@
+package main
+
+import "testing"
+
+func TestConfigurePreservesDefaultBooleansWhenConfigIsPartial(t *testing.T) {
+	raw := mustJSON(t, lifecycleRequest{ConfigYAML: []byte("route: codex_web_search\n")})
+
+	if errConfigure := configure(raw); errConfigure != nil {
+		t.Fatalf("configure() error = %v", errConfigure)
+	}
+
+	cfg := loadedConfig()
+	if !cfg.Enabled {
+		t.Fatal("Enabled = false, want default true")
+	}
+	if !cfg.RequireWebSearchOnly {
+		t.Fatal("RequireWebSearchOnly = false, want default true")
+	}
+	if cfg.Route != string(backendCodexWebSearch) {
+		t.Fatalf("Route = %q, want codex_web_search", cfg.Route)
+	}
+}
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-EXAMPLES := simple model auth frontend-auth executor protocol-format request-translator request-normalizer response-translator response-normalizer thinking usage cli management-api host-callback host-callback-auth-files host-model-callback`
	`1`	`+EXAMPLES := simple model auth frontend-auth executor protocol-format request-translator request-normalizer response-translator response-normalizer thinking usage cli management-api host-callback host-callback-auth-files host-model-callback claude-web-search-router`
`2`	`2`	`LANGUAGES := go c rust`
`3`	`3`	`BIN_DIR := $(CURDIR)/bin`
`4`	`4`	`BUILD_DIR := $(BIN_DIR)/build`