@jsonstudio/rcc 0.89.1189 → 0.89.1348

package/docs/web-search-service-design.md

@@ -0,0 +1,322 @@
+# Server-side Web Search Tool – Design
+
+## Goals
+
+- Provide a single, server-side `web_search` tool that any provider/model can call as a normal function/tool.
+- Use Virtual Router to pick which *search backend* (GLM / Gemini / others) actually performs web search.
+- Keep the main model routing unchanged: normal routes decide the “brain” model; `web_search` only plugs in as a tool.
+- Make search backends pluggable and config-driven; allow multiple engines with clear semantics (e.g. GLM vs Google/Gemini).
+
+## High-level Architecture
+
+### Roles
+
+- **Main model**  
+  - Selected by existing virtual router routes (`default`, `coding`, `longcontext`, …).  
+  - Sees a standard `web_search` function tool in its `tools` list when search is enabled.  
+  - Decides when to call `web_search` and with which arguments (including engine choice when multiple are exposed).
+
+- **Server-side `web_search` tool**  
+  - Implemented inside llmswitch-core / Hub Pipeline.  
+  - Intercepts `web_search` tool calls from the main model and runs the actual web search via a *search backend*.  
+  - Returns a normalized result payload back to the main model as a tool result (tool role / function_call_output).
+
+- **Search backend(s)**  
+  - One or more “search-capable” models, managed by Virtual Router:
+    - v1: `glm.glm-4.7` (via GLM WebSearchToolSchema).  
+    - Future: Gemini (`gemini-2.5-flash-lite`, `gemini-3-flash`, …).
+  - Only used for the *secondary* “search” call, not as the main model for the user request.
+
+### Routing Responsibilities
+
+- **Main route (`chatRoute`)**  
+  - Same as today: virtual router chooses providers for `/v1/chat/completions` / `/v1/responses` etc.
+  - `web_search` does **not** override the main route or main provider/model.
+
+- **Search intent route (`web_search` intent)**  
+  - A separate “intent flag” carried in pipeline metadata, derived from classifier output based on **the latest user message** (text-only).  
+  - Intent rules (substring match, not regex):
+    - **Chinese – hard hits (100%):** `"谷歌搜索"`, `"谷歌一下"`, `"百度一下"` 一旦出现，即视为联网搜索意图；这三种说法都会被视为 “Google‑preferred”（优先尝试谷歌系搜索后端）。  
+    - **Chinese – soft hits:**  
+      - 包含 `"上网"` 视为联网搜索意图；  
+      - 或者同时包含动词 {`"搜索"`, `"查找"`, `"搜"`} 与名词 {`"网络"`, `"联网"`, `"新闻"`, `"信息"`, `"报道"`} 中任意组合。  
+    - **English – hard hits:** `"/search"`, `"web search"`, `"websearch"`, `"internet search"`, `"search the web"`, `"web-search"`, `"internet-search"` 等常见短语。  
+    - **English – soft hits:** 当文本里同时包含动词 {`"search"`, `"find"`, `"look up"`, `"look for"`, `"google"`} 与名词 {`"web"`, `"internet"`, `"online"`, `"news"`, `"information"`, `"info"`, `"report"`, `"reports"`, `"article"`, `"articles"`} 时，也视为联网搜索意图；其中包含 `"google"` 时会被视为 “Google 优先”。  
+  - Controls whether the server injects the `web_search` tool for the main model (and whether the intent is marked as “Google‑preferred” for engine filtering).
+
+- **Search backend route (`routing.web_search`)**  
+  - Dedicated VR route that lists search backend targets (e.g. `glm.glm-4.7`, later Gemini).  
+  - Used only for the *secondary* search call, inside the server-side `web_search` tool implementation.
+  - Not exposed as a direct model name to clients.
+
+### Separation from existing `search`
+
+- Existing “search files / code / knowledge base” behaviour currently wired via `websearch` routes should be:
+  - Renamed to `search` (config + docs), as it is not “web search” but internal search.
+  - Kept functionally identical (same providers/behaviour).
+- New `web_search` is strictly *web* search:
+  - Uses external search-capable models / services.
+  - Implemented as a server-side tool that internally fans out to GLM / Gemini / others.
+
+## Configuration Model
+
+### Web Search Engines
+
+At the virtual router / host config level, expose a compact `webSearch` section that enumerates available engines and how they map to providers:
+
+```jsonc
+{
+  "webSearch": {
+    "engines": [
+      {
+        "id": "glm",
+        "providerKey": "glm.glm-4.7",
+        "description": "GLM 4.7 – better for Chinese / domestic news",
+        "default": true
+      },
+      {
+        "id": "google",
+        "providerKey": "antigravity.geetasamodgeetasamoda.gemini-3-flash",
+        "description": "Gemini – broader global web coverage",
+        "default": false
+      }
+    ],
+    "injectPolicy": "selective" // or "always"
+  }
+}
+```
+
+Behaviour:
+
+- `engines` may contain:
+  - Only one engine → server can treat it as implicit default; `engine` argument becomes optional.
+  - Multiple engines, no `default:true` → server does **not** choose for the model; instead, enumerates all engine ids and descriptions in the tool schema, so the main model can pick.
+- `injectPolicy`:
+  - `"selective"`: only inject `web_search` when the classifier detects web search intent (or a sticky flag is set).
+  - `"always"`: whenever this route/provider is used, always inject `web_search` into `tools`.
+- **Google‑preferred selection (中文 “谷歌搜索 / 谷歌一下”):**
+  - When the intent classifier detects explicit “Google search” wording (e.g. 中文 `"谷歌搜索"`, `"谷歌一下"` or English text mentioning `"google"` together with search verbs), the server treats this as a **Google‑preferred** web search intent.
+  - In Google‑preferred mode, the injected `web_search` tool’s `engine.enum` is **narrowed** to:
+    - Engines whose `providerKey` is backed by Gemini CLI / Antigravity search backends (e.g. `gemini-cli.*`, `antigravity.*`); and
+    - Engines whose `id` contains `"google"` (to support configs that encode Google in the id).  
+  - If this filtered set is non‑empty, only these engines are exposed to the main model for this call. If the filtered set is empty, the server falls back to the full `engines` list.
+
+### Search Backend Route
+
+The actual “search backend” route is declared as:
+
+```jsonc
+{
+  "virtualrouter": {
+    "routing": {
+      "web_search": [
+        {
+          "id": "web-search-backends",
+          "priority": 200,
+          "targets": [
+            "glm.glm-4.7"
+            // later: "antigravity.geetasamodgeetasamoda.gemini-3-flash", ...
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+- This route is used only for the *secondary* search call from the server-side `web_search` tool.
+- The mapping `engine.id → providerKey` is read from `webSearch.engines` and used to:
+  - Validate that the configured engines are present in `routing.web_search`.
+  - Find the correct backend when executing a web search.
+
+## Server-side `web_search` Tool Schema
+
+This is the unified tool presented to main models (OpenAI Chat / Responses shape):
+
+```jsonc
+{
+  "type": "function",
+  "function": {
+    "name": "web_search",
+    "description": "Perform web search for news and web pages using configured search engines.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "engine": {
+          "type": "string",
+          "enum": ["glm", "google"], // generated from config.webSearch.engines
+          "description": "Search engine id. For example: glm=better for Chinese/domestic information; google=better for global web coverage."
+        },
+        "query": {
+          "type": "string",
+          "description": "Search query or user question."
+        },
+        "recency": {
+          "type": "string",
+          "enum": ["oneDay", "oneWeek", "oneMonth", "oneYear", "noLimit"],
+          "description": "Time range filter; maps to backend-specific recency options."
+        },
+        "count": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 50,
+          "description": "Number of results to retrieve."
+        }
+      },
+      "required": ["query"]
+    }
+  }
+}
+```
+
+Notes:
+
+- If only one engine is configured:
+  - `engine` can be omitted by the main model; the server uses the sole engine as default.
+- If multiple engines are configured and no `default:true` is present:
+  - The server does **not** pick an engine; it expects the main model to choose.
+
+## Execution Flow
+
+### 1. First request – main model
+
+1. Client sends a standard `/v1/chat/completions` or `/v1/responses` request (no explicit `web_search` tool).
+2. Hub Pipeline / Virtual Router:
+   - Runs the normal route classifier to pick `chatRoute` and main provider/model (e.g. `tab.gpt-5.2-codex`).
+   - Runs intent classification; if web search intent is detected (or `injectPolicy="always"`), it:
+     - Marks metadata with `searchIntentRoute = 'web_search'`.
+     - Appends the unified `web_search` function tool to `tools` for the main model.
+3. Request is sent to the main provider with:
+   - The chosen model (from `chatRoute`).
+   - An augmented `tools` list containing `web_search`.
+
+### 2. Main model emits `web_search` tool call
+
+- The main provider responds with a function/tool call:
+
+```jsonc
+{
+  "role": "assistant",
+  "tool_calls": [
+    {
+      "id": "call_1",
+      "type": "function",
+      "function": {
+        "name": "web_search",
+        "arguments": "{\"engine\":\"glm\",\"query\":\"今天的国际新闻头条\",\"count\":3}"
+      }
+    }
+  ]
+}
+```
+
+- Hub Pipeline detects `function.name === "web_search"` and *intercepts* it as a server-side tool:
+  - Parses `engine`, `query`, `recency`, `count` and validates against `webSearch.engines`.
+
+### 3. Secondary request – search backend
+
+- Based on the parsed `engine`:
+  - Look up the selected engine in `config.webSearch.engines`.
+  - Resolve its `providerKey` (e.g. `glm.glm-4.7`).
+- A secondary request is constructed and sent via the internal pipeline:
+
+```jsonc
+{
+  "route": "web_search", // search backend route
+  "model": "glm.glm-4.7",
+  "messages": [
+    {
+      "role": "user",
+      "content": "今天的国际新闻头条"
+    }
+  ]
+}
+```
+
+- For each backend family, compat will:
+  - GLM: inject GLM’s `tools.web_search` schema (`type: "web_search"`, `web_search.search_engine`, `enable`, `search_result`, etc.) before sending upstream.
+  - Gemini: use Gemini’s equivalent search-specific schema when we add it.
+
+### 4. Backend response → tool result
+
+- The search backend returns:
+  - Answer text summarizing the news.
+  - Backend-specific metadata (e.g. GLM `web_search` field with hits, URLs, publish dates, etc.).
+- Server-side `web_search` handler:
+  - Normalizes this response into a tool result JSON, e.g.:
+
+```jsonc
+{
+  "summary": "<model-written summary>",
+  "hits": [
+    { "title": "...", "url": "...", "source": "...", "date": "..." },
+    ...
+  ],
+  "engine": "glm"
+}
+```
+
+- Wraps it as a tool result message associated with the original tool call id:
+
+```jsonc
+{
+  "role": "tool",
+  "tool_call_id": "call_1",
+  "name": "web_search",
+  "content": [
+    {
+      "type": "output_json",
+      "output": { /* normalized result as above */ }
+    }
+  ]
+}
+```
+
+### 5. Third request – back to the main model
+
+- Hub constructs a new request to the *same* main provider:
+  - `messages` = original messages + assistant tool_call + tool result (standard OpenAI tool-calling pattern).
+- Main model receives the web_search result as if the client had executed the tool locally.
+- Main model generates the final answer to the user.
+- When the final assistant message has `finish_reason == "stop"`, the server:
+  - Resets the “sticky web_search enabled” flag for this call chain.
+
+## Sticky Behaviour
+
+- During a single call chain (including tool calls and retries):
+  - Once web search intent is detected, or a `web_search` tool call has occurred, the session is considered “web_search-enabled” for this chain.
+  - Web search tools continue to be injected for the main model within this chain as needed.
+- Reset:
+  - When the final assistant response for the call has `finish_reason == "stop"`, the sticky state is reset.
+  - A subsequent user turn may re-trigger web search injection based on intent and `injectPolicy`.
+
+## Backends
+
+### GLM (`glm.glm-4.7`)
+
+- First production backend.
+- Implementation details:
+  - Maps canonical `web_search` parameters to GLM’s `web_search` schema:
+    - `engine` → choice of GLM backend (if GLM exposes multiple search engines).
+    - `query` → GLM prompt content.
+    - `recency` / `count` → `web_search` fields (`search_recency_filter`, `count`, etc.).
+  - Allows reading `web_search` field from GLM response and converting it into the normalized hit list.
+
+### Gemini (future)
+
+- Candidate models: `gemini-2.5-flash-lite`, `gemini-3-flash`, etc.
+- Many Gemini models restrict tools to *search tools only*; we need to:
+  - Ensure `web_search` backend requests use the correct Gemini schema and obey tool constraints.
+  - Treat these models as pure web search engines in the backend pool.
+
+## Summary of Changes vs. Current Behaviour
+
+- Introduce a server-side `web_search` tool:
+  - Main models see a standard function; actual web search execution runs via a separate search backend route.
+- Split “search” responsibilities:
+  - `search`: existing file/code/knowledge search (renamed from current websearch usage).
+  - `web_search`: true web search via GLM/Gemini backends.
+- Keep main routing unchanged:
+  - Main provider selection remains fully owned by the existing Virtual Router route logic.
+- Provide sticky but bounded web search capability:
+  - Enabled per call chain; automatically reset when final `finish_reason == "stop"` is observed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsonstudio/rcc",
-  "version": "0.89.1189",
+  "version": "0.89.1348",
   "description": "Multi-provider OpenAI proxy server with anthropic/responses/chat support (release)",
   "type": "module",
   "main": "dist/index.js",
@@ -20,7 +20,9 @@
     "scripts/",
     "rcc",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "docs/",
+    "configsamples/"
   ],
   "bundledDependencies": [],
   "engines": {
@@ -28,7 +30,7 @@
   },
   "scripts": {
     "build": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs",
-    "build:dev": "BUILD_MODE=dev npm run build && npm run verify:e2e-toolcall && npm run verify:apply-patch && npm run verify:apply-patch-regressions && npm run verify:exec-command && npm run test:routing-instructions && npm run test:cli && npm run install:global && npm run mock:regressions && npm run verify:errorsamples && npm run verify:e2e-gemini-followup-sample",
+    "build:dev": "bash -lc 'export BUILD_MODE=dev; npm run build && npm run test:unified-hub-shadow && npm run verify:e2e-toolcall && npm run verify:apply-patch && npm run verify:apply-patch-regressions && npm run verify:exec-command && npm run test:routing-instructions && npm run test:cli && npm run install:global && npm run mock:regressions && npm run verify:errorsamples && npm run verify:e2e-gemini-followup-sample'",
     "build:min": "npm run llmswitch:ensure && node scripts/build-core.mjs && node scripts/vendor-core.mjs && npm run clean && node scripts/gen-build-info.mjs && tsc && node scripts/copy-compat-assets.mjs && node scripts/copy-modules-config.mjs",
     "prepack": "echo skip-prepack",
     "postbuild": "chmod +x dist/cli.js || true",
@@ -37,7 +39,7 @@
     "dev": "tsx watch src/index.ts",
     "jest:run": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js",
     "test": "npm run test:routing-instructions && npm run mock:regressions",
-    "test:routing-instructions": "npm run jest:run -- --runTestsByPath tests/server/runtime/request-executor.single-attempt.spec.ts tests/server/runtime/executor-provider.retryable.spec.ts tests/providers/core/runtime/gemini-cli-http-provider.unit.test.ts tests/sharedmodule/gemini-mapper-functioncall-args.spec.ts tests/unified-hub/policy-observe-shadow.spec.ts tests/servertool/stop-message-auto.spec.ts tests/servertool/gemini-empty-reply-continue.spec.ts tests/servertool/apply-patch-guard.spec.ts tests/servertool/exec-command-guard.spec.ts tests/servertool/server-side-web-search.spec.ts tests/servertool/vision-flow.spec.ts tests/servertool/iflow-model-error-retry.spec.ts tests/servertool/virtual-router-routing-instructions.spec.ts tests/servertool/virtual-router-series-cooldown.spec.ts tests/servertool/virtual-router-quota-routing.spec.ts tests/servertool/virtual-router-engine-update-deps.spec.ts tests/manager/quota/provider-quota-center.spec.ts tests/manager/quota/provider-quota-store.spec.ts tests/server/http-server/daemon-admin.e2e.spec.ts tests/server/http-server/quota-view-injection.spec.ts tests/server/http-server/hub-policy-injection.spec.ts tests/server/handlers/sse-timeout.spec.ts tests/utils/is-direct-execution.test.ts tests/utils/windows-netstat.test.ts",
+    "test:routing-instructions": "npm run jest:run -- --runTestsByPath tests/server/runtime/request-executor.single-attempt.spec.ts tests/server/runtime/executor-provider.retryable.spec.ts tests/providers/core/runtime/gemini-cli-http-provider.unit.test.ts tests/providers/core/runtime/antigravity-quota-client.unit.test.ts tests/manager/quota/provider-quota-center.spec.ts tests/manager/quota/provider-quota-store.spec.ts tests/manager/quota/quota-manager-refresh.spec.ts tests/manager/quota/provider-quota-daemon-module.spec.ts tests/manager/quota/provider-key-normalization.spec.ts tests/server/http-server/daemon-admin.e2e.spec.ts tests/server/http-server/quota-view-injection.spec.ts tests/server/http-server/quota-refresh-triggers.e2e.spec.ts tests/server/http-server/hub-policy-injection.spec.ts tests/server/http-server/session-header-injection.spec.ts tests/server/http-server/session-dir.spec.ts tests/server/handlers/sse-timeout.spec.ts tests/utils/is-direct-execution.test.ts tests/utils/windows-netstat.test.ts tests/servertool/virtual-router-context-fallback.spec.ts tests/servertool/virtual-router-longcontext-fallback.spec.ts tests/servertool/virtual-router-series-cooldown.spec.ts tests/servertool/recursive-detection-guard.spec.ts tests/servertool/routing-instructions.spec.ts tests/servertool/stop-message-auto.spec.ts tests/servertool/stopmessage-session-scope.spec.ts tests/servertool/stopmessage-anthropic-stop-sequence.spec.ts tests/servertool/servertool-progress-logging.spec.ts tests/unified-hub/hub-v1-single-path-imports.spec.ts",
     "test:cli": "npm run jest:run -- --runTestsByPath tests/cli/clean-command.spec.ts tests/cli/code-command.spec.ts tests/cli/config-command.spec.ts tests/cli/env-command.spec.ts tests/cli/env-output.spec.ts tests/cli/examples-command.spec.ts tests/cli/port-command.spec.ts tests/cli/port-utils.spec.ts tests/cli/restart-command.spec.ts tests/cli/smoke.spec.ts tests/cli/start-command.spec.ts tests/cli/status-command.spec.ts tests/cli/stop-command.spec.ts",
     "test:watch": "npm run jest:run -- --watch",
     "test:coverage": "npm run jest:run -- --coverage",
@@ -124,7 +126,7 @@
     "test:v2:protocol": "node tests/v2/dist/protocol-conversion-test.js",
     "test:comprehensive": "node scripts/v2-consistency/comprehensive-consistency-test.mjs",
     "test:golden": "node scripts/tests/golden-provider-cycle.mjs",
-    "test:sharedmodule": "npm run jest:run -- tests/sharedmodule/*.spec.ts",
+    "test:sharedmodule": "echo 'sharedmodule tests moved to llmswitch-core repo; see scripts/move-tests-to-llmswitch.mjs for details'",
     "sync:ci-goldens": "node scripts/tools/sync-ci-goldens.mjs",
     "sync:apply-patch-regressions": "node scripts/tools/sync-apply-patch-regressions.mjs",
     "mock:extract": "node scripts/mock-provider/extract.mjs",
@@ -132,13 +134,13 @@
     "mock:regressions": "node scripts/mock-provider/run-regressions.mjs",
     "mock:clean": "node scripts/mock-provider/clean.mjs",
     "publish:rcc": "node scripts/publish-rcc.mjs",
+    "pack:rcc": "node scripts/pack-rcc.mjs",
     "build:rccx": "npm run build:min && node scripts/pack-mode.mjs --name @jsonstudio/rccx --bin rccx",
     "compare:codex:rccx": "node scripts/compare-codex-rccx.mjs"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.65.0",
-    "@jsonstudio/llms": "^0.6.938",
-    "@jsonstudio/rcc": "^0.89.555",
+    "@jsonstudio/llms": "^0.6.1172",
     "@lmstudio/sdk": "^1.5.0",
     "@radix-ui/react-switch": "^1.2.6",
     "@types/socket.io": "^3.0.1",
@@ -163,6 +165,9 @@
     "socket.io": "^4.8.1",
     "zod": "^3.23.8"
   },
+  "optionalDependencies": {
+    "@jsonstudio/llms-engine": "^0.3.0"
+  },
   "peerDependencies": {
     "@jest/globals": "^30.1.2"
   },