@hasna/knowledge 0.2.17 → 0.2.18

package/docs/architecture/ai-native-knowledge-base.md

@@ -255,6 +255,13 @@ returns a local citation draft by default, optionally calls AI SDK generation vi
 `--generate`, records `runs`, `run_events`, and `provider_usage`, and only
 proposes durable wiki updates until the wiki compile/write task owns writes.
 
+Provider-native web search is exposed separately as
+`open-knowledge web search <query>` and MCP `ok_web_search`. Real network access
+is safety-gated; OpenAI and Anthropic use provider web-search tools through AI
+SDK, while DeepSeek remains a future fallback/external-search path. Returned web
+snippets can optionally be filed as read-only `web` source refs for later local
+search and citation.
+
 ## Provider Registry
 
 AI provider setup is BYOK and AI SDK v6 based. The local provider layer tracks:

package/docs/architecture/hybrid-semantic-search.md

@@ -142,6 +142,11 @@ source refs, artifact URIs, revision/hash metadata, offsets, and provenance.
 and MCP `knowledge_ask` wrap this context pack in a run ledger and return a
 citation draft or explicit AI SDK generated answer.
 
+Provider-native web search lives beside local retrieval. `open-knowledge web
+search` and MCP `ok_web_search` are safety-gated, capture provider sources, and
+can file snippets as read-only `web` source refs so later local retrieval treats
+them like other cited sources.
+
 ## Reindexing
 
 Reindexing is driven by source revisions:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -54,6 +54,9 @@ interface Flags {
   context?: boolean;
   generate?: boolean;
   approveWrite?: boolean;
+  provider?: string;
+  domain?: string[];
+  fileResults?: boolean;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -68,7 +71,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -111,6 +114,9 @@ function parseArgs(argv: string[]): ParseResult {
       case '--context': flags.context = true; break;
       case '--generate': flags.generate = true; break;
       case '--approve-write': flags.approveWrite = true; break;
+      case '--provider': flags.provider = argv[i + 1]; i += 1; break;
+      case '--domain': flags.domain = [...(flags.domain ?? []), argv[i + 1]]; i += 1; break;
+      case '--file-results': flags.fileResults = true; break;
       case '--fake': flags.fake = true; break;
       case '--no-color': flags.noColor = true; break;
       case '--scope': flags.scope = argv[i + 1]; i += 1; break;
@@ -190,6 +196,7 @@ Commands:
   ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
   search <query>               Hybrid search sources, wiki pages, indexes, or context
+  web search <query>           Provider-native web search with citations
   ask|build <prompt>           Build a read-only citation answer/context pack
   embeddings status|index|search Build/query local vector embeddings
   providers status|models|check Inspect AI SDK provider config and credentials
@@ -206,6 +213,9 @@ Global Options:
   --context                    Return a reranked citation context pack for search
   --generate                   Call AI SDK text generation for ask/build
   --approve-write              Record approval intent for future durable wiki writes
+  --provider <name>            Provider override for web search
+  --domain <domain>            Restrict provider web search to a domain
+  --file-results               File web snippets as web source refs
   --fake                       Use deterministic fake embeddings for local tests
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
@@ -268,6 +278,7 @@ function printCommandHelp(command: string): void {
   if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
   if (command === 'search') { console.log('Usage: open-knowledge search <query> [--context] [--semantic] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
+  if (command === 'web') { console.log('Usage: open-knowledge web search <query> [--provider openai|anthropic] [--model provider:model] [--domain <domain>] [--file-results] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'ask' || command === 'build' || command === 'knowledge') { console.log('Usage: open-knowledge ask|build <prompt> [--generate] [--semantic] [--model default|provider:model] [--approve-write] [--scope local|global|project] [--json]'); return; }
   if (command === 'embeddings') { console.log('Usage: open-knowledge embeddings status|index|search [query] [--model openai:text-embedding-3-small] [--limit <n>] [--dimensions <n>] [--fake] [--scope local|global|project] [--json]'); return; }
   if (command === 'providers') { console.log('Usage: open-knowledge providers status|models|check [provider|model-alias] [--scope local|global|project] [--json]'); return; }
@@ -316,11 +327,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --domain --file-results --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--domain)--domain[domain]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search ask build embeddings providers safety help ls rm edit unarchive knowledge"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -632,6 +643,24 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'web') {
+    const action = positional[1] ?? 'search';
+    if (action !== 'search') throw new Error("Invalid web action. Use 'search'.");
+    const query = positional.slice(2).join(' ');
+    if (!query) throw new Error('Usage: open-knowledge web search <query>');
+    const result = await service.webSearch({
+      query,
+      limit: flags.limit,
+      modelRef: flags.model,
+      provider: flags.provider as AiProviderId | undefined,
+      domains: flags.domain,
+      fake: flags.fake,
+      fileResults: flags.fileResults,
+    });
+    output({ ok: true, ...result, message: `${result.sources.length} web source(s)` }, flags.json);
+    return;
+  }
+
   if (command === 'ask' || command === 'build') {
     const prompt = positional.slice(commandArgOffset).join(' ');
     if (!prompt) throw new Error('Usage: open-knowledge ask <prompt>');

package/src/mcp.js

@@ -222,6 +222,24 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_web_search', 'Provider web search', 'Run safety-gated provider-native web search and return citations/sources', {
+    scope: scopeField,
+    query: z.string().describe('Web search query'),
+    limit: z.number().optional().describe('Maximum sources'),
+    provider: z.enum(['openai', 'anthropic', 'deepseek']).optional().describe('Provider override'),
+    model: z.string().optional().describe('Model alias/ref'),
+    domains: z.array(z.string()).optional().describe('Allowed domains'),
+    fake: z.boolean().optional().describe('Use deterministic fake web results'),
+    file_results: z.boolean().optional().describe('File web snippets as web source refs'),
+  }, async ({ scope, query, limit, provider, model, domains, fake, file_results }) => {
+    const service = createKnowledgeService({ scope });
+    try {
+      return jsonText({ ok: true, ...await service.webSearch({ query, limit, provider, modelRef: model, domains, fake, fileResults: file_results }) });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/service.ts

@@ -16,6 +16,7 @@ import { providerStatus, listModelRegistry, type ProviderStatusResult, type Mode
 import { retrieveKnowledgeContext, type RetrievalOptions } from './retrieval';
 import { hybridSearch, type HybridSearchOptions } from './search';
 import { resolveSafetyPolicy } from './safety';
+import { runProviderWebSearch, type WebSearchOptions } from './web-search';
 import {
   recordStorageObjects,
   resolveStorageContract,
@@ -244,6 +245,16 @@ export class KnowledgeService {
       config: this.config(),
     });
   }
+
+  async webSearch(options: Omit<WebSearchOptions, 'dbPath' | 'config' | 'safetyPolicy'>) {
+    const workspace = this.ensureWorkspace();
+    return runProviderWebSearch({
+      ...options,
+      dbPath: workspace.knowledgeDbPath,
+      config: this.config(),
+      safetyPolicy: this.safetyPolicy(),
+    });
+  }
 }
 
 export function createKnowledgeService(options: KnowledgeServiceOptions = {}): KnowledgeService {

package/src/web-search.ts

@@ -0,0 +1,330 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
+import { ingestOpenFilesManifestItems } from './manifest-ingest';
+import {
+  assertProviderCredentials,
+  normalizeAiSdkUsage,
+  parseModelRef,
+  providerSettings,
+  recordProviderUsage,
+  resolveModelRef,
+  type AiProviderId,
+} from './providers';
+import { assertWebSearchAllowed, recordAuditEvent, type SafetyPolicy } from './safety';
+import type { KnowledgeConfig } from './workspace';
+
+export interface WebSearchOptions {
+  dbPath: string;
+  query: string;
+  config?: KnowledgeConfig;
+  safetyPolicy?: SafetyPolicy;
+  modelRef?: string;
+  provider?: AiProviderId;
+  limit?: number;
+  maxUses?: number;
+  domains?: string[];
+  fake?: boolean;
+  fileResults?: boolean;
+  env?: Record<string, string | undefined>;
+  now?: Date;
+}
+
+export interface WebSearchSource {
+  url: string;
+  title: string | null;
+  snippet: string | null;
+  provider_metadata: Record<string, unknown>;
+}
+
+export interface WebSearchResult {
+  run_id: string;
+  query: string;
+  provider: string;
+  model: string;
+  answer: string;
+  sources: WebSearchSource[];
+  filed_sources: number;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cost_usd: number;
+  };
+  warnings: string[];
+}
+
+function stableHash(value: string): string {
+  return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+
+function estimateTokens(text: string): number {
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(1, Math.ceil(words * 1.25));
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function sourceFromRecord(value: unknown): WebSearchSource | null {
+  const record = asRecord(value);
+  const url = asString(record.url) ?? asString(record.uri) ?? asString(record.sourceUrl);
+  if (!url) return null;
+  return {
+    url,
+    title: asString(record.title) ?? asString(record.name),
+    snippet: asString(record.snippet) ?? asString(record.text) ?? asString(record.description),
+    provider_metadata: record,
+  };
+}
+
+function collectSources(value: unknown, output: Map<string, WebSearchSource>): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectSources(entry, output);
+    return;
+  }
+  const source = sourceFromRecord(value);
+  if (source) output.set(source.url, source);
+  const record = asRecord(value);
+  for (const key of ['sources', 'results', 'citations', 'annotations', 'output']) {
+    if (record[key]) collectSources(record[key], output);
+  }
+}
+
+function fakeSources(query: string, limit: number): WebSearchSource[] {
+  return Array.from({ length: Math.min(limit, 3) }, (_, index) => ({
+    url: `https://example.com/knowledge-web-${index + 1}`,
+    title: `Fake web source ${index + 1}`,
+    snippet: `Deterministic web-search fixture for "${query}"`,
+    provider_metadata: { fake: true, rank: index + 1 },
+  }));
+}
+
+async function openAiWebSearch(input: {
+  query: string;
+  model: string;
+  config?: KnowledgeConfig;
+  env: Record<string, string | undefined>;
+  maxUses: number;
+  domains: string[];
+}) {
+  const { generateText } = await import('ai');
+  const { createOpenAI } = await import('@ai-sdk/openai');
+  const settings = providerSettings(input.config, 'openai');
+  const openai = createOpenAI({
+    apiKey: input.env[settings.api_key_env],
+    baseURL: settings.base_url,
+  }) as any;
+  const webSearch = openai.tools?.webSearch;
+  if (!webSearch) throw new Error('OpenAI provider does not expose tools.webSearch.');
+  return generateText({
+    model: openai(input.model),
+    prompt: input.query,
+    tools: {
+      web_search: webSearch({
+        externalWebAccess: true,
+        searchContextSize: 'medium',
+        ...(input.domains.length > 0 ? { allowedDomains: input.domains } : {}),
+      }),
+    },
+    toolChoice: { type: 'tool', toolName: 'web_search' },
+  });
+}
+
+async function anthropicWebSearch(input: {
+  query: string;
+  model: string;
+  config?: KnowledgeConfig;
+  env: Record<string, string | undefined>;
+  maxUses: number;
+  domains: string[];
+}) {
+  const { generateText } = await import('ai');
+  const { createAnthropic } = await import('@ai-sdk/anthropic');
+  const settings = providerSettings(input.config, 'anthropic');
+  const anthropic = createAnthropic({
+    apiKey: input.env[settings.api_key_env],
+    baseURL: settings.base_url,
+  }) as any;
+  const factory = anthropic.tools?.webSearch_20250305 ?? anthropic.tools?.webSearch;
+  if (!factory) throw new Error('Anthropic provider does not expose a web search tool.');
+  return generateText({
+    model: anthropic(input.model),
+    prompt: input.query,
+    tools: {
+      web_search: factory({
+        maxUses: input.maxUses,
+        ...(input.domains.length > 0 ? { allowedDomains: input.domains } : {}),
+      }),
+    },
+  });
+}
+
+async function fileWebSources(options: WebSearchOptions, sources: WebSearchSource[], now: string): Promise<number> {
+  if (!options.fileResults || sources.length === 0) return 0;
+  const items = sources.map((source) => {
+    const text = [source.title, source.snippet, source.url].filter(Boolean).join('\n');
+    const hash = stableHash(text);
+    return {
+      source_ref: source.url,
+      name: source.title ?? source.url,
+      url: source.url,
+      mime: 'text/plain',
+      hash,
+      revision: hash,
+      status: 'active',
+      updated_at: now,
+      permissions: { mode: 'read_only', allowed_purposes: ['knowledge_answer', 'knowledge_index'] },
+      metadata: {
+        source_ref: source.url,
+        content_source: 'provider_web_search',
+        provider_metadata: source.provider_metadata,
+      },
+      extracted_text: text,
+    };
+  });
+  const result = await ingestOpenFilesManifestItems({
+    dbPath: options.dbPath,
+    items,
+    sourceLabel: `web-search:${options.query}`,
+    readAction: 'provider_web_search_file_results',
+    safetyPolicy: options.safetyPolicy,
+    now: new Date(now),
+  });
+  return result.sources_upserted;
+}
+
+export async function runProviderWebSearch(options: WebSearchOptions): Promise<WebSearchResult> {
+  const query = options.query.trim();
+  if (!query) throw new Error('Web search query is required.');
+  const env = options.env ?? process.env;
+  const now = (options.now ?? new Date()).toISOString();
+  const limit = Math.max(1, Math.min(options.limit ?? 5, 20));
+  const maxUses = Math.max(1, Math.min(options.maxUses ?? 3, 10));
+  const domains = options.domains ?? [];
+  const modelRef = resolveModelRef(options.modelRef ?? (options.provider ? `${options.provider}:${providerSettings(options.config, options.provider).default_model}` : 'default'), options.config);
+  const parsed = parseModelRef(modelRef);
+  const provider = options.provider ?? parsed.provider;
+  const model = parsed.provider === provider ? parsed.model : providerSettings(options.config, provider).default_model;
+  const runId = `run_${randomUUID()}`;
+
+  if (!options.fake && options.safetyPolicy) assertWebSearchAllowed(options.safetyPolicy);
+  if (!options.fake && provider !== 'openai' && provider !== 'anthropic') {
+    throw new Error(`Provider ${provider} does not expose native web search yet.`);
+  }
+  if (!options.fake) assertProviderCredentials(provider, options.config, env);
+
+  migrateKnowledgeDb(options.dbPath);
+  const db = openKnowledgeDb(options.dbPath);
+  try {
+    db.run(
+      `INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        runId,
+        'provider-web-search',
+        query,
+        'running',
+        provider,
+        model,
+        JSON.stringify({ domains, max_uses: maxUses, fake: options.fake === true }),
+        now,
+        now,
+      ],
+    );
+    recordAuditEvent(db, {
+      event_type: 'source_read',
+      action: options.fake ? 'fake_provider_web_search' : 'provider_web_search',
+      target_uri: query,
+      decision: 'allow',
+      metadata: { provider, model, domains, max_uses: maxUses },
+      created_at: now,
+    });
+  } finally {
+    db.close();
+  }
+
+  let answer = '';
+  let sources: WebSearchSource[] = [];
+  let usage = { input_tokens: estimateTokens(query), output_tokens: 0, cost_usd: 0 };
+  const warnings: string[] = [];
+  if (options.fake) {
+    sources = fakeSources(query, limit);
+    answer = `Fake web search answer for: ${query}`;
+    usage.output_tokens = estimateTokens(answer);
+  } else {
+    const result = provider === 'openai'
+      ? await openAiWebSearch({ query, model, config: options.config, env, maxUses, domains })
+      : await anthropicWebSearch({ query, model, config: options.config, env, maxUses, domains });
+    answer = result.text;
+    const collected = new Map<string, WebSearchSource>();
+    collectSources((result as any).sources, collected);
+    collectSources((result as any).toolResults, collected);
+    sources = Array.from(collected.values()).slice(0, limit);
+    const normalized = normalizeAiSdkUsage({
+      provider,
+      model,
+      usage: (result as any).usage,
+      providerMetadata: (result as any).providerMetadata,
+    });
+    usage = {
+      input_tokens: normalized.input_tokens,
+      output_tokens: normalized.output_tokens,
+      cost_usd: normalized.cost_usd,
+    };
+  }
+
+  const filedSources = await fileWebSources(options, sources, now);
+  const writeDb = openKnowledgeDb(options.dbPath);
+  try {
+    writeDb.run(
+      `UPDATE runs SET status = ?, metadata_json = ?, updated_at = ? WHERE id = ?`,
+      [
+        'completed',
+        JSON.stringify({ domains, max_uses: maxUses, sources: sources.length, filed_sources: filedSources, fake: options.fake === true }),
+        now,
+        runId,
+      ],
+    );
+    writeDb.run(
+      `INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        `evt_${randomUUID()}`,
+        runId,
+        'info',
+        'provider_web_search_completed',
+        JSON.stringify({ sources: sources.length, filed_sources: filedSources }),
+        now,
+      ],
+    );
+    recordProviderUsage(writeDb, {
+      run_id: runId,
+      provider,
+      model,
+      input_tokens: usage.input_tokens,
+      output_tokens: usage.output_tokens,
+      cost_usd: usage.cost_usd,
+      metadata: { web_search: true, sources: sources.length, filed_sources: filedSources },
+      created_at: now,
+    });
+  } finally {
+    writeDb.close();
+  }
+
+  if (sources.length === 0) warnings.push('no_web_sources_returned');
+  return {
+    run_id: runId,
+    query,
+    provider,
+    model,
+    answer,
+    sources,
+    filed_sources: filedSources,
+    usage,
+    warnings,
+  };
+}