bizrouter 0.2.1 → 0.3.0

package/AGENT_MANUAL.md

@@ -48,8 +48,10 @@ bizrouter logout                               revoke the console session, delet
 bizrouter doctor                               connectivity, key, session, installed agents, conflicts
 bizrouter models [query] [--json]              models this key may use, KRW prices per 1M tokens
 
-bizrouter claude|codex|opencode|hermes [--model ID] [--reasoning-effort L] [--no-mcp] [tool args…]
+bizrouter claude|codex|opencode|hermes [--model ID] [--reasoning-effort L] [--search] [--no-mcp] [tool args…]
                                                run a coding agent through BizRouter (config files untouched)
+bizrouter search "question" [--model ID] [--max-tokens N] [--json] [--no-stream]
+                                               BizRouter Search: answer grounded in 50+ live data sources (see §7a)
 
 bizrouter api --list [keyword]                 every console API operation (from the live OpenAPI)
 bizrouter api --schema [METHOD] <path>         request/response fields of one operation
@@ -179,13 +181,43 @@ setting, everything after our flags is passed through untouched.
 When a console session exists, the launcher also registers this CLI as an MCP
 server named `bizrouter` inside Claude Code, Codex and OpenCode for that run
 (`--no-mcp` disables it). The agent then has tools `bizrouter_api`,
-`bizrouter_openapi`, `bizrouter_docs`, `bizrouter_models` and `bizrouter_whoami`
-with the same rules as above — `bizrouter_api` refuses mutating calls unless
-`confirm: true` is passed after the user agreed.
+`bizrouter_openapi`, `bizrouter_docs`, `bizrouter_models`, `bizrouter_whoami`
+and `bizrouter_search` with the same rules as above — `bizrouter_api` refuses
+mutating calls unless `confirm: true` is passed after the user agreed.
 
 Claude Code can only run Anthropic models (it always sends Anthropic-only
 fields); use Codex/OpenCode/Hermes for GPT or Gemini.
 
+## 7a. BizRouter Search — answers grounded in live data
+
+`POST /v1/search` (docs: https://bizrouter.ai/docs/search) makes the model
+look facts up before it answers. The gateway embeds the question, picks the
+matching sources out of 50+ agent.store data servers, lets the model call them
+as tools, and returns a normal chat completion plus a `bizrouter_search`
+block. Sources include Korean law and National Assembly bills, corporate
+filings and financials (DART, FSC), real-estate transactions, national
+statistics and Bank of Korea rates, transport (flights, transit, maps),
+papers and clinical trials, web search and news, weather and air quality, US
+market data. Questions that need no data are answered without tools.
+
+Use it whenever an answer must be current or authoritative instead of model
+memory — especially anything about Korean public data, prices, laws, filings
+or news. Lookups are free; only the model's tokens are billed (tool results
+count as input tokens, so keep `max_tokens` ≥ 1500).
+
+Three ways to reach it, all using the API key:
+
+| Where | How |
+| --- | --- |
+| Terminal | `bizrouter search "질문" [--model ID] [--max-tokens N] [--json] [--no-stream]` — answer on stdout, a one-line summary (sources · calls · rounds · model · cost) on stderr. `--json` prints the full completion including `bizrouter_search.sources[]` and `calls[]`. |
+| Inside an agent (MCP) | Tool `bizrouter_search {query, model?, max_tokens?}` → `{answer, sources, calls, rounds, routed_model, usage}`. Available in Claude Code, Codex and OpenCode launched by this CLI when a console session exists. This is the **only** route for Claude Code (Messages API) and Codex (Responses API), because Search rides on Chat Completions. |
+| Harness model | `bizrouter opencode --search` / `bizrouter hermes --search` pins `<model>:search` so every turn of that session is grounded. Any Chat Completions client can do the same with `model: "openai/gpt-5.5:search"`, `model: "bizrouter/search"`, or body `"search": true`. |
+
+Default model is `bizrouter/route` (the organization's Smart Routing policy
+chooses the concrete model). `--model`/`model` accepts any chat model id.
+When the answer cites sources, keep the citation when you relay it to the
+user; when `calls` is empty, say the answer came from the model alone.
+
 ## 8. Troubleshooting
 
 - `콘솔 세션이 없습니다` / 401 → `bizrouter login` (human step).

package/README.md

@@ -40,7 +40,23 @@ bizrouter opencode --model google/gemini-3.5-pro
 bizrouter claude --dry-run          # 실행 대신 넘겨줄 환경 변수와 명령을 보여줍니다
 ```
 
-콘솔 세션이 있으면 Claude Code·Codex·OpenCode에 이 CLI가 **MCP 서버 `bizrouter`** 로 함께 연결됩니다. 에이전트는 `bizrouter_api`(콘솔 API 호출)·`bizrouter_openapi`(API 탐색)·`bizrouter_docs`(문서)·`bizrouter_models`·`bizrouter_whoami` 도구로 API 키를 만들고, 정책을 바꾸고, 사용량을 읽습니다. 데이터를 바꾸는 호출은 사용자 확인 뒤 `confirm: true`를 받아야만 실행됩니다. `--no-mcp`로 끕니다.
+콘솔 세션이 있으면 Claude Code·Codex·OpenCode에 이 CLI가 **MCP 서버 `bizrouter`** 로 함께 연결됩니다. 에이전트는 `bizrouter_api`(콘솔 API 호출)·`bizrouter_openapi`(API 탐색)·`bizrouter_docs`(문서)·`bizrouter_models`·`bizrouter_whoami`·`bizrouter_search`(Search) 도구로 API 키를 만들고, 정책을 바꾸고, 사용량을 읽고, 실제 데이터를 찾아 답합니다. 데이터를 바꾸는 호출은 사용자 확인 뒤 `confirm: true`를 받아야만 실행됩니다. `--no-mcp`로 끕니다.
+
+## Search — 실제 데이터를 찾아 답하기
+
+`bizrouter search`는 [BizRouter Search](https://bizrouter.ai/docs/search)(`POST /v1/search`)를 호출합니다. 모델이 질문에 맞는 출처(법령·국회, 기업 공시·재무, 부동산 실거래, 국가통계·금리, 교통, 논문·임상, 웹 검색·뉴스, 날씨, 지도, 미국 주식 등 50종 이상)를 골라 조회한 뒤 출처와 함께 답합니다. 조회는 무료이고 모델 토큰만 과금됩니다.
+
+```bash
+bizrouter search "근로기준법 60조 연차 휴가 조문"
+bizrouter search "한국은행 기준금리 최근 결정" --model openai/gpt-5.5
+bizrouter search "삼성전자 2024년 매출" --json | jq '.bizrouter_search.sources'
+echo "인천공항 오늘 출발 지연 편" | bizrouter search --no-stream
+
+bizrouter opencode --search                     # OpenCode 세션 전체에 Search 를 켬 (<모델>:search)
+bizrouter hermes --search --model openai/gpt-5.5
+```
+
+답은 stdout, 출처·조회 횟수·라운드·모델·비용 한 줄은 stderr로 나옵니다. 로그인한 뒤 실행한 Claude Code·Codex·OpenCode 안에서는 MCP 도구 `bizrouter_search`로 같은 일을 합니다. Claude Code(Messages API)·Codex(Responses API)는 `:search` 접미사를 쓸 수 없으므로 이 도구가 두 에이전트에서 Search를 쓰는 길입니다.
 
 ## 콘솔 관리 명령
 
@@ -69,6 +85,7 @@ bizrouter mcp                                      # MCP 서버(stdio)로 직접
 
 ```bash
 bizrouter models [검색어]        # 이 키로 쓸 수 있는 모델·컨텍스트·원화 단가
+bizrouter search "질문"          # Search 호출 (--model, --max-tokens, --json, --no-stream)
 bizrouter doctor                 # 키·세션·연결·설치·충돌 점검
 bizrouter setup claude|codex|opencode   # 도구 설정 파일에 BizRouter를 영구 등록 (백업 생성)
 bizrouter auth / logout / env / update

package/dist/args.js

@@ -7,7 +7,7 @@ export class ArgError extends Error {
  * the harness untouched, so `bizrouter claude -p "hi"` still works.
  */
 export function parseLaunchArgs(argv) {
-    const out = { closedNetwork: false, dryRun: false, help: false, noMcp: false, passthrough: [] };
+    const out = { closedNetwork: false, dryRun: false, help: false, noMcp: false, search: false, passthrough: [] };
     let i = 0;
     const takeValue = (flag) => {
         const value = argv[i + 1];
@@ -51,6 +51,10 @@ export function parseLaunchArgs(argv) {
                 out.noMcp = true;
                 i += 1;
                 continue;
+            case '--search':
+                out.search = true;
+                i += 1;
+                continue;
             case '--help':
             case '-h':
                 out.help = true;

package/dist/commands/misc.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { ENV_KEY_NAME } from '../config.js';
 import { c, info, print } from '../ui.js';
 import { requireApiKey } from './shared.js';
-export const VERSION = '0.2.1';
+export const VERSION = '0.3.0';
 /** `eval "$(bizrouter env)"` exports the saved key for tools configured by `bizrouter setup`. */
 export function envCommand() {
     const key = requireApiKey();
@@ -32,10 +32,12 @@ ${c.bold('시작하기')}
   bizrouter opencode              OpenCode를 BizRouter로 실행합니다
   bizrouter hermes                Hermes를 BizRouter로 실행합니다
   도구는 평소처럼 실행되고, 이번 실행의 모델 호출·과금만 BizRouter를 거칩니다. 설정 파일은 바뀌지 않습니다.
+  bizrouter search "질문"          모델이 법령·공시·통계·웹 검색 등 실제 데이터를 찾아 출처와 함께 답합니다 (Search)
 
 ${c.bold('실행 옵션')} (실행 명령 뒤, 도구 자체 옵션 앞에 씁니다)
   --model <ID>                    BizRouter 모델 ID (예: anthropic/claude-sonnet-5, openai/gpt-5.5)
   --reasoning-effort <단계>       minimal · low · medium · high · xhigh (Codex·OpenCode)
+  --search                        모델에 Search를 켭니다(<모델>:search · OpenCode·Hermes). Claude Code·Codex는 MCP 도구 bizrouter_search로
   --closed-network                Claude Code의 부수 트래픽(버전 확인·텔레메트리)을 끕니다
   --no-mcp                        콘솔 MCP 서버(bizrouter)를 에이전트에 연결하지 않습니다
   --dry-run                       실행하지 않고 넘겨줄 환경 변수와 명령만 보여줍니다
@@ -54,8 +56,9 @@ ${c.bold('콘솔 관리')} (브라우저 승인 로그인 뒤 · 모두 --json
 
 ${c.bold('그 밖에')}
   bizrouter models [검색어]       이 키로 쓸 수 있는 모델과 원화 단가
+  bizrouter search "질문"          Search 호출 (--model, --max-tokens, --json, --no-stream · 답은 stdout, 출처는 stderr)
   bizrouter docs [주제]           에이전트 매뉴얼 · 개발 문서 (--list, --full)
-  bizrouter mcp                   MCP 서버(stdio)로 실행 — 에이전트가 콘솔을 도구로 다룹니다
+  bizrouter mcp                   MCP 서버(stdio)로 실행 — 에이전트가 콘솔·Search를 도구로 다룹니다
   bizrouter setup <도구>          claude · codex · opencode 설정 파일에 BizRouter를 영구 등록
   bizrouter doctor                연결·키·세션·설치·충돌 점검
   bizrouter auth                  지금 어떤 계정·키가 쓰이는지 확인

package/dist/commands/models.js

@@ -53,5 +53,6 @@ export async function modelsCommand(argv) {
     print();
     print(c.dim(`${rows.length}개 · 원화 단가는 100만 토큰당 · 환율 ${catalog.exchange_rate}원/달러 · ${catalog.from_cache ? '캐시(최대 10분)' : '지금 조회'}`));
     print(c.dim('예: bizrouter codex --model openai/gpt-5.5 · bizrouter claude --model anthropic/claude-opus-5'));
+    print(c.dim('Search: 어느 채팅 모델이든 뒤에 :search 를 붙이면 실제 데이터를 조회해 답합니다 (예: bizrouter search "질문" --model openai/gpt-5.5)'));
     return 0;
 }

package/dist/commands/search.js

@@ -0,0 +1,119 @@
+import { describeSearch, search, SEARCH_DEFAULT_MODEL, SEARCH_MIN_MAX_TOKENS, searchStream, stripSearchSuffix } from '../search.js';
+import { c, CliError, info, print, warn } from '../ui.js';
+import { requireApiKey } from './shared.js';
+export const SEARCH_USAGE = 'bizrouter search "질문" [--model ID] [--max-tokens N] [--json] [--no-stream]';
+export function parseSearchFlags(argv) {
+    const flags = { json: false, stream: true, help: false };
+    const words = [];
+    let i = 0;
+    const takeValue = (flag) => {
+        const value = argv[i + 1];
+        if (value === undefined || value.startsWith('-'))
+            throw new CliError(`${flag} 뒤에 값이 필요합니다.`, { hint: SEARCH_USAGE });
+        i += 2;
+        return value;
+    };
+    while (i < argv.length) {
+        const token = argv[i];
+        const eq = token.indexOf('=');
+        const name = token.startsWith('--') && eq > 0 ? token.slice(0, eq) : token;
+        const inline = token.startsWith('--') && eq > 0 ? token.slice(eq + 1) : undefined;
+        const value = (flag) => (inline !== undefined ? ((i += 1), inline) : takeValue(flag));
+        switch (name) {
+            case '--model':
+            case '-m':
+                flags.model = value(name);
+                continue;
+            case '--max-tokens': {
+                const raw = value(name);
+                const n = Number(raw);
+                if (!Number.isInteger(n) || n <= 0)
+                    throw new CliError(`--max-tokens 값은 양의 정수여야 합니다: ${raw}`, { hint: SEARCH_USAGE });
+                flags.maxTokens = n;
+                continue;
+            }
+            case '--json':
+                flags.json = true;
+                i += 1;
+                continue;
+            case '--no-stream':
+                flags.stream = false;
+                i += 1;
+                continue;
+            case '--help':
+            case '-h':
+                flags.help = true;
+                i += 1;
+                continue;
+            default:
+                if (token.startsWith('-') && token.length > 1)
+                    throw new CliError(`알 수 없는 옵션입니다: ${token}`, { hint: SEARCH_USAGE });
+                words.push(token);
+                i += 1;
+        }
+    }
+    if (words.length)
+        flags.query = words.join(' ');
+    return flags;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8').trim();
+}
+export function searchHelpText() {
+    return `${c.bold('bizrouter search')} — 모델이 실제 데이터를 찾아 출처와 함께 답합니다 (BizRouter Search · POST /v1/search)
+
+  ${SEARCH_USAGE}
+  echo "질문" | bizrouter search
+
+  --model <ID>        답을 쓸 모델. 기본 ${SEARCH_DEFAULT_MODEL}(스마트 라우팅 기본 정책). 예: openai/gpt-5.5, anthropic/claude-sonnet-5
+  --max-tokens <N>    출력 상한. 기본 ${SEARCH_MIN_MAX_TOKENS} (도구 결과가 입력에 들어가므로 이보다 작게 잡지 않는 편이 좋습니다)
+  --json              화면 출력 대신 응답 JSON 전체 (choices · usage · bizrouter_search)
+  --no-stream         답을 한 번에 받아 출력합니다 (기본은 글자가 오는 대로 출력)
+
+  법령·국회, 기업 공시·재무, 부동산 실거래, 국가통계·금리, 교통, 논문·임상, 웹 검색·뉴스, 날씨, 지도, 미국 주식 등
+  50종이 넘는 출처를 질문에 맞게 골라 조회합니다. 데이터가 필요 없는 질문은 도구 없이 답합니다. 조회 자체는 무료이고 모델 토큰만 과금됩니다.
+  답은 stdout, 출처·비용은 stderr 로 나옵니다. 문서: https://bizrouter.ai/docs/search
+`;
+}
+export async function searchCommand(argv) {
+    const flags = parseSearchFlags(argv);
+    if (flags.help) {
+        print(searchHelpText());
+        return 0;
+    }
+    let query = flags.query;
+    if (!query && !process.stdin.isTTY)
+        query = await readStdin();
+    if (!query)
+        throw new CliError('질문이 없습니다.', { hint: SEARCH_USAGE });
+    const apiKey = requireApiKey();
+    if (flags.maxTokens !== undefined && flags.maxTokens < SEARCH_MIN_MAX_TOKENS) {
+        warn(`--max-tokens ${flags.maxTokens}은 작은 편입니다. 도구 결과가 입력에 포함되므로 답이 잘리면 ${SEARCH_MIN_MAX_TOKENS} 이상으로 올리십시오.`);
+    }
+    const model = flags.model ? stripSearchSuffix(flags.model) : undefined;
+    const request = { query, model, max_tokens: flags.maxTokens };
+    if (flags.json) {
+        const result = await search(apiKey, request);
+        print(JSON.stringify(result.raw, null, 2));
+        return 0;
+    }
+    const streaming = flags.stream && Boolean(process.stdout.isTTY);
+    info(`데이터를 찾아 답을 씁니다 · 모델 ${model ?? SEARCH_DEFAULT_MODEL} (보통 3~20초, 출처가 느리면 더 걸립니다)`);
+    let result;
+    if (streaming) {
+        result = await searchStream(apiKey, request, (delta) => process.stdout.write(delta));
+        if (result.answer && !result.answer.endsWith('\n'))
+            process.stdout.write('\n');
+    }
+    else {
+        result = await search(apiKey, request);
+        print(result.answer);
+    }
+    if (!result.answer)
+        warn('모델이 빈 답을 돌려주었습니다. --max-tokens 를 올리거나 다른 모델로 다시 시도하십시오.');
+    info(describeSearch(result));
+    return 0;
+}

package/dist/harness/hermes.js

@@ -34,6 +34,9 @@ export function buildHermesPlan(options) {
             CUSTOM_BASE_URL: `${options.apiBase}/v1`,
             CUSTOM_API_KEY: options.apiKey,
         },
-        notes: [`Hermes → custom provider ${options.apiBase}/v1 · 모델 ${options.model}`],
+        notes: [
+            `Hermes → custom provider ${options.apiBase}/v1 · 모델 ${options.model}`,
+            ...(options.model.endsWith(':search') ? ['BizRouter Search 켬: 모델이 답하기 전에 법령·공시·통계·웹 검색 등 실제 데이터를 조회합니다 (조회 무료 · 모델 토큰만 과금).'] : []),
+        ],
     };
 }

package/dist/harness/opencode.js

@@ -1,5 +1,6 @@
 import { chatModels } from '../api.js';
 import { ENV_KEY_NAME } from '../config.js';
+import { SEARCH_MODEL_SUFFIX } from '../search.js';
 import { opencodeMcpBlock } from './mcp.js';
 export const OPENCODE_PROVIDER_ID = 'bizrouter';
 // The generic OpenAI-compatible provider against /v1 finishes turns cleanly.
@@ -31,10 +32,25 @@ export function opencodeProvider(models, reasoningEffort, apiBase = 'https://api
         models: entries,
     };
 }
+/**
+ * A pinned model that is not a catalog row (`bizrouter/route`, `openai/gpt-5.5:search`)
+ * still needs an entry, or OpenCode refuses the `model` setting. Limits come
+ * from the underlying catalog row when there is one.
+ */
+export function withPinnedModel(provider, model, models) {
+    const entries = provider.models;
+    if (entries[model])
+        return provider;
+    const base = model.endsWith(SEARCH_MODEL_SUFFIX) ? model.slice(0, -SEARCH_MODEL_SUFFIX.length) : model;
+    const row = entries[base] ?? models.find((m) => m.id === base);
+    const limit = row ? { context: 'limit' in row ? row.limit.context : row.context_length, output: 'limit' in row ? row.limit.output : row.max_output_tokens } : { context: 200_000, output: 64_000 };
+    const label = model.endsWith(SEARCH_MODEL_SUFFIX) ? `${row?.name ?? base} · Search` : model.startsWith('bizrouter/route') ? 'Smart Routing' : model;
+    return { ...provider, models: { ...entries, [model]: { name: label, limit } } };
+}
 export function opencodeConfigContent(options) {
     return JSON.stringify({
         $schema: 'https://opencode.ai/config.json',
-        provider: { [OPENCODE_PROVIDER_ID]: opencodeProvider(options.models, options.reasoningEffort, options.apiBase) },
+        provider: { [OPENCODE_PROVIDER_ID]: withPinnedModel(opencodeProvider(options.models, options.reasoningEffort, options.apiBase), options.model, options.models) },
         model: `${OPENCODE_PROVIDER_ID}/${options.model}`,
         ...(options.mcp ? { mcp: opencodeMcpBlock(options.mcp) } : {}),
     });
@@ -54,6 +70,7 @@ export function buildOpencodePlan(options) {
         },
         notes: [
             `OpenCode → provider "${OPENCODE_PROVIDER_ID}" (${chatModels(options.models).length}개 모델) · 기본 모델 ${options.model}`,
+            ...(options.model.endsWith(SEARCH_MODEL_SUFFIX) ? ['BizRouter Search 켬: 모델이 답하기 전에 법령·공시·통계·웹 검색 등 실제 데이터를 조회합니다 (조회 무료 · 모델 토큰만 과금).'] : []),
             ...(options.mcp ? ['콘솔 MCP 서버 「bizrouter」 를 이 세션에 연결합니다 (끄기: --no-mcp).'] : []),
         ],
     };

package/dist/index.js

@@ -11,6 +11,8 @@ import { bizrouterMcpServer } from './harness/mcp.js';
 import { doctorCommand } from './commands/doctor.js';
 import { envCommand, helpText, updateCommand, VERSION } from './commands/misc.js';
 import { modelsCommand } from './commands/models.js';
+import { searchCommand } from './commands/search.js';
+import { isVirtualModelId, searchModelFor, stripSearchSuffix } from './search.js';
 import { setupCommand } from './commands/setup.js';
 import { requireApiKey } from './commands/shared.js';
 import { apiBase, loadUserConfig, resolveSession } from './config.js';
@@ -25,8 +27,8 @@ import { CliError, fail, info, maskKey, print, warn } from './ui.js';
 const LAUNCH_HELP = {
     claude: 'bizrouter claude [--model ID] [--closed-network] [--dry-run] [claude 옵션…]',
     codex: 'bizrouter codex [--model ID] [--reasoning-effort 단계] [--dry-run] [codex 옵션…]',
-    opencode: 'bizrouter opencode [--model ID] [--reasoning-effort 단계] [--dry-run] [opencode 옵션…]',
-    hermes: 'bizrouter hermes [--model ID] [--dry-run] [hermes 옵션…]',
+    opencode: 'bizrouter opencode [--model ID] [--reasoning-effort 단계] [--search] [--dry-run] [opencode 옵션…]',
+    hermes: 'bizrouter hermes [--model ID] [--search] [--dry-run] [hermes 옵션…]',
 };
 async function resolveModel(harness, args, apiKey) {
     const pinned = args.model ?? loadUserConfig().defaults?.[harness];
@@ -41,8 +43,10 @@ async function resolveModel(harness, args, apiKey) {
         warn(`모델 목록을 가져오지 못해 기본값으로 진행합니다. (${error instanceof Error ? error.message : String(error)})`);
     }
     if (pinned) {
-        if (models.length && !models.some((m) => m.id === pinned)) {
-            const suggestions = suggestModels(models, pinned);
+        // `bizrouter/route`, `bizrouter/search` and `<id>:search` are policies layered on catalog rows, not rows themselves.
+        const lookup = stripSearchSuffix(pinned);
+        if (models.length && !isVirtualModelId(pinned) && !models.some((m) => m.id === lookup)) {
+            const suggestions = suggestModels(models, lookup);
             warn(`「${pinned}」 는 이 키로 쓸 수 있는 모델 목록에 없습니다.${suggestions.length ? ` 비슷한 모델: ${suggestions.join(', ')}` : ''}`);
             info('그대로 시도합니다. 키의 「API key 사용 범위」나 조직의 모델 정책이 막고 있으면 요청이 거절됩니다.');
         }
@@ -69,7 +73,19 @@ async function launch(harness, argv) {
     }
     const apiKey = requireApiKey();
     const base = apiBase();
-    const { model, models } = await resolveModel(harness, args, apiKey);
+    const resolved = await resolveModel(harness, args, apiKey);
+    const { models } = resolved;
+    let model = resolved.model;
+    if (args.search || (model && model.endsWith(':search'))) {
+        // Search rides on Chat Completions. Claude Code speaks Messages and Codex speaks Responses,
+        // so for them Search is reachable only through the MCP tool `bizrouter_search`.
+        if (harness === 'claude' || harness === 'codex') {
+            throw new CliError(`${harness === 'claude' ? 'Claude Code' : 'Codex'}는 모델 이름에 :search 를 붙이는 방식(Chat Completions 전용)을 쓸 수 없습니다.`, {
+                hint: '로그인돼 있으면 에이전트에 MCP 도구 bizrouter_search 가 함께 연결되어 세션 안에서 "BizRouter Search 로 찾아봐" 하면 됩니다. 터미널에서는 `bizrouter search "질문"`, OpenCode·Hermes 는 `--search` 를 그대로 쓸 수 있습니다.',
+            });
+        }
+        model = searchModelFor(model ?? FALLBACK_DEFAULT[harness]);
+    }
     // With a console session the agent gets the console as MCP tools; without one there is nothing to expose.
     const mcp = !args.noMcp && harness !== 'hermes' && resolveSession().source !== 'none' ? bizrouterMcpServer() : undefined;
     if (!args.noMcp && harness !== 'hermes' && !mcp && !args.dryRun)
@@ -162,6 +178,8 @@ async function main(argv) {
             return mcpCommand();
         case 'models':
             return modelsCommand(rest);
+        case 'search':
+            return searchCommand(rest);
         case 'setup':
             return setupCommand(rest);
         case 'doctor':

package/dist/mcp.js

@@ -8,6 +8,7 @@ import { resolveCredential, resolveSession } from './config.js';
 import { ConsoleApiError, consoleRequest, fetchOpenApi, fetchProfile, findOperation, HTTP_METHODS, listOperations, MUTATING_METHODS, normalizeConsolePath } from './console.js';
 import { findDocsPages, loadLlmsFull, parseLlmsFull, readAgentManual } from './commands/docs.js';
 import { VERSION } from './commands/misc.js';
+import { search, stripSearchSuffix } from './search.js';
 import { CliError } from './ui.js';
 export const MCP_PROTOCOL_VERSION = '2025-06-18';
 export const MCP_SERVER_NAME = 'bizrouter';
@@ -53,13 +54,27 @@ export const TOOLS = [
     },
     {
         name: 'bizrouter_docs',
-        description: 'BizRouter documentation. Without `topic` returns the agent manual (how the CLI, credentials, console API and safety rules work). With `topic` returns matching developer-docs pages (e.g. "chat-completions", "smart-routing", "cli", "인증"). `list: true` returns the page index.',
+        description: 'BizRouter documentation. Without `topic` returns the agent manual (how the CLI, credentials, console API and safety rules work). With `topic` returns matching developer-docs pages (e.g. "chat-completions", "smart-routing", "cli", "search", "인증"). `list: true` returns the page index.',
         inputSchema: {
             type: 'object',
             properties: { topic: { type: 'string' }, list: { type: 'boolean' } },
             additionalProperties: false,
         },
     },
+    {
+        name: 'bizrouter_search',
+        description: 'BizRouter Search (POST /v1/search): ask a question and a model looks the facts up in 50+ live sources before answering — Korean law and National Assembly bills, corporate filings and financials (DART/FSC), real-estate transactions, national statistics and BOK rates, transport (flights, transit), papers and clinical trials, web search and news, weather, maps/places, US market data — then answers with sources. Use it whenever an answer needs current or authoritative data instead of model memory (Korean public data especially). Uses the stored API key; billed as model tokens only, lookups are free. Returns the answer plus `sources`, `calls`, `rounds` and `routed_model`.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'The question, in the language the answer should be in.' },
+                model: { type: 'string', description: 'Model to write the answer with (default bizrouter/route = the organization\'s Smart Routing policy). Any chat model id, e.g. "openai/gpt-5.5".' },
+                max_tokens: { type: 'integer', description: 'Output cap. Default 1500; tool results share the context, so do not go much lower.' },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        },
+    },
 ];
 function text(value) {
     return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
@@ -142,6 +157,26 @@ export async function callTool(name, args) {
                 }
                 return text(readAgentManual());
             }
+            case 'bizrouter_search': {
+                const cred = resolveCredential();
+                if (!cred.apiKey)
+                    return errorResult('No API key stored. Ask the user to run `bizrouter login`.');
+                if (typeof args.query !== 'string' || !args.query.trim())
+                    return errorResult('`query` is required.');
+                const model = typeof args.model === 'string' && args.model.trim() ? stripSearchSuffix(args.model.trim()) : undefined;
+                const maxTokens = typeof args.max_tokens === 'number' && Number.isInteger(args.max_tokens) && args.max_tokens > 0 ? args.max_tokens : undefined;
+                const result = await search(cred.apiKey, { query: args.query, model, max_tokens: maxTokens });
+                const meta = result.meta;
+                return text({
+                    answer: result.answer,
+                    sources: meta?.sources ?? [],
+                    calls: meta?.calls ?? [],
+                    rounds: meta?.rounds ?? 1,
+                    routed_model: meta?.routed_model ?? result.model ?? null,
+                    usage: result.usage ?? null,
+                    note: meta && meta.calls.length ? undefined : 'No data source was consulted; the answer comes from the model alone.',
+                });
+            }
             default:
                 return errorResult(`Unknown tool: ${name}`);
         }
@@ -165,7 +200,7 @@ export async function handleMessage(message) {
                 protocolVersion: typeof message.params?.protocolVersion === 'string' ? message.params.protocolVersion : MCP_PROTOCOL_VERSION,
                 capabilities: { tools: { listChanged: false } },
                 serverInfo: { name: MCP_SERVER_NAME, version: VERSION },
-                instructions: 'BizRouter console and docs. Call bizrouter_whoami first. Reads are free; for POST/PUT/PATCH/DELETE ask the user, then pass confirm: true. Never paste a full API key into files or replies.',
+                instructions: 'BizRouter console, docs and Search. Call bizrouter_whoami first. Reads are free; for POST/PUT/PATCH/DELETE ask the user, then pass confirm: true. Never paste a full API key into files or replies. When an answer needs current or authoritative data (Korean law, filings, statistics, prices, news…), call bizrouter_search instead of guessing.',
             });
         case 'notifications/initialized':
         case 'notifications/cancelled':

package/dist/search.js

@@ -0,0 +1,184 @@
+// BizRouter Search (`POST /v1/search`): the model looks real data up in
+// agent.store's public and web sources (law, filings, statistics, transport,
+// papers, web search, …) before it answers. This module is the thin client
+// shared by `bizrouter search` and the MCP tool `bizrouter_search`.
+import { apiBase } from './config.js';
+import { CliError } from './ui.js';
+/** Virtual model that follows the organization's default Smart Routing policy. */
+export const SEARCH_DEFAULT_MODEL = 'bizrouter/route';
+/** `openai/gpt-5.5:search` turns Search on for a Chat Completions call. */
+export const SEARCH_MODEL_SUFFIX = ':search';
+/** Time to wait for the first byte; Search rounds can take 30 s when a source is slow. */
+const SEARCH_TIMEOUT_MS = 180_000;
+/** Below this the tool results tend to leave no room for the answer. */
+export const SEARCH_MIN_MAX_TOKENS = 1500;
+export function searchModelFor(base) {
+    return base.endsWith(SEARCH_MODEL_SUFFIX) ? base : `${base}${SEARCH_MODEL_SUFFIX}`;
+}
+/** `openai/gpt-5.5:search` → `openai/gpt-5.5`; ids without the suffix are returned as-is. */
+export function stripSearchSuffix(id) {
+    return id.endsWith(SEARCH_MODEL_SUFFIX) ? id.slice(0, -SEARCH_MODEL_SUFFIX.length) : id;
+}
+/** `bizrouter/route[/slug]` and `bizrouter/search[/slug]` are policies, not catalog rows. */
+export function isVirtualModelId(id) {
+    return /^bizrouter\/(route|search)(\/|$)/.test(stripSearchSuffix(id));
+}
+function buildBody(request, stream) {
+    const body = {};
+    if (request.query)
+        body.query = request.query;
+    if (request.messages?.length)
+        body.messages = request.messages;
+    if (request.model)
+        body.model = request.model;
+    body.max_tokens = request.max_tokens ?? SEARCH_MIN_MAX_TOKENS;
+    if (stream)
+        body.stream = true;
+    return body;
+}
+async function post(apiKey, body) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SEARCH_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetch(`${apiBase()}/v1/search`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', 'User-Agent': 'bizrouter-cli' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        clearTimeout(timer);
+        const reason = error instanceof Error && error.name === 'AbortError' ? `${SEARCH_TIMEOUT_MS / 1000}초 안에 응답이 오지 않았습니다` : String(error);
+        throw new CliError(`BizRouter Search(${apiBase()}/v1/search)에 연결할 수 없습니다: ${reason}`);
+    }
+    // The timer only guards the connection; a streaming body is read by the caller.
+    clearTimeout(timer);
+    if (response.status === 401 || response.status === 403) {
+        throw new CliError('API 키가 유효하지 않습니다.', { hint: '`bizrouter login`으로 키를 다시 저장하십시오.' });
+    }
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        let message = `BizRouter Search가 ${response.status}를 돌려주었습니다.`;
+        try {
+            const parsed = JSON.parse(text);
+            const detail = typeof parsed.error === 'string' ? parsed.error : parsed.error?.message;
+            if (detail)
+                message = `${message} ${detail}`;
+        }
+        catch {
+            if (text)
+                message = `${message} ${text.slice(0, 300)}`;
+        }
+        throw new CliError(message);
+    }
+    return response;
+}
+/** One request, one JSON answer. */
+export async function search(apiKey, request) {
+    const response = await post(apiKey, buildBody(request, false));
+    const json = (await response.json());
+    return {
+        answer: json.choices?.[0]?.message?.content ?? '',
+        model: json.model,
+        meta: json.bizrouter_search,
+        usage: json.usage,
+        raw: json,
+    };
+}
+/**
+ * Parse the `data:` payloads of an SSE stream. Exposed for tests; the gateway
+ * sends `: connected` and keep-alive comments before the first token, then
+ * normal chat.completion.chunk frames, then a final chunk carrying `usage` and
+ * `bizrouter_search`, then `[DONE]`.
+ */
+export function* sseData(buffer) {
+    for (const line of buffer.split('\n')) {
+        const trimmed = line.replace(/\r$/, '');
+        if (trimmed.startsWith('data:'))
+            yield trimmed.slice(5).trim();
+    }
+}
+/** Streaming request; `onText` receives content deltas as they arrive. */
+export async function searchStream(apiKey, request, onText) {
+    const response = await post(apiKey, buildBody(request, true));
+    if (!response.body)
+        throw new CliError('BizRouter Search 응답에 본문이 없습니다.');
+    const decoder = new TextDecoder();
+    const reader = response.body.getReader();
+    let pending = '';
+    let answer = '';
+    let model;
+    let meta;
+    let usage;
+    const consume = (data) => {
+        if (data === '[DONE]' || !data)
+            return;
+        let chunk;
+        try {
+            chunk = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        model = chunk.model ?? model;
+        const delta = chunk.choices?.[0]?.delta?.content;
+        if (delta) {
+            answer += delta;
+            onText(delta);
+        }
+        if (chunk.usage)
+            usage = chunk.usage;
+        if (chunk.bizrouter_search)
+            meta = chunk.bizrouter_search;
+    };
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        pending += decoder.decode(value, { stream: true });
+        const lastBreak = pending.lastIndexOf('\n');
+        if (lastBreak < 0)
+            continue;
+        const complete = pending.slice(0, lastBreak + 1);
+        pending = pending.slice(lastBreak + 1);
+        for (const data of sseData(complete))
+            consume(data);
+    }
+    for (const data of sseData(pending))
+        consume(data);
+    return { answer, model, meta, usage, raw: undefined };
+}
+/** Korean one-liner about what was looked up, for stderr after the answer. */
+export function describeSearch(result) {
+    const meta = result.meta;
+    if (!meta)
+        return '출처 정보가 없습니다.';
+    const okCalls = meta.calls.filter((c) => c.status === 'ok').length;
+    const failed = meta.calls.length - okCalls;
+    const label = (s) => (s.name && s.name !== s.slug ? `${s.name}(${s.slug})` : s.slug);
+    const parts = [];
+    if (meta.calls.length) {
+        // `sources` also lists sources that were only offered as hints; name the ones actually consulted.
+        const consulted = new Set(meta.calls.map((c) => c.source ?? c.tool.split('__')[0]));
+        const names = meta.sources.filter((s) => consulted.has(s.slug)).map(label);
+        parts.push(names.length ? `출처 ${names.join(', ')}` : `출처 ${[...consulted].join(', ')}`);
+        parts.push(`조회 ${okCalls}회${failed ? ` (실패 ${failed})` : ''}`);
+    }
+    else {
+        parts.push('데이터 조회 없이 답했습니다');
+    }
+    parts.push(`라운드 ${meta.rounds}`);
+    const routed = meta.routed_model ?? result.model;
+    if (routed)
+        parts.push(`모델 ${routed}`);
+    if (result.usage?.cost !== undefined)
+        parts.push(`비용 ${formatCost(result.usage.cost)}`);
+    return parts.join(' · ');
+}
+function formatCost(krw) {
+    if (krw >= 10)
+        return `${Math.round(krw).toLocaleString('ko-KR')}원`;
+    return `${krw.toLocaleString('ko-KR', { maximumFractionDigits: 1 })}원`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bizrouter",
-  "version": "0.2.1",
-  "description": "BizRouter CLI - run Claude Code, Codex, OpenCode, and Hermes through BizRouter, and operate the BizRouter console (API keys, usage, policies, audit logs) from the terminal or as an MCP server",
+  "version": "0.3.0",
+  "description": "BizRouter CLI - run Claude Code, Codex, OpenCode, and Hermes through BizRouter, operate the BizRouter console (API keys, usage, policies, audit logs) from the terminal or as an MCP server, and ask BizRouter Search for answers grounded in 50+ live data sources",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {