@anionex/dsh-tool-search 0.1.0

package/src/runtime.ts

@@ -0,0 +1,326 @@
+/** Agent-local selected sets and model-visible tool filtering. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
+import {
+  defineTool,
+  type ToolDefinition,
+  type ToolExecution,
+  type ToolExecutionResult,
+  type ToolRunContext,
+} from '@deepseek-ai/dsh-tools'
+import { Bm25Index } from './bm25.ts'
+import { buildCatalog, type ToolCatalogEntry, type ToolSchemaLike } from './catalog.ts'
+import { ToolPolicyResolver, normalizeSettings } from './settings.ts'
+import {
+  MAX_RESULT_LIMIT,
+  TOOL_SEARCH_NAME,
+  type CatalogSnapshot,
+  type ToolSearchSettings,
+} from './shared.ts'
+
+const RESULT_SCHEMA_VERSION = 1
+const MAX_QUERY_LENGTH = 4096
+const MAX_DESCRIPTION_LENGTH = 240
+
+export interface ToolSearchMatch {
+  name: string
+  description: string
+  score: number
+}
+
+export interface ToolSearchResult {
+  schemaVersion: 1
+  query: string
+  tools: ToolSearchMatch[]
+}
+
+interface AgentState {
+  agent: Agent
+  selected: Set<string>
+  catalog: ToolCatalogEntry[]
+  catalogGeneration: number
+  disposeAssembly: () => void
+}
+
+function compareNames(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+function summarize(description: string): string {
+  const normalized = description.replace(/\s+/gu, ' ').trim()
+  if (normalized.length <= MAX_DESCRIPTION_LENGTH) return normalized
+  return `${normalized.slice(0, MAX_DESCRIPTION_LENGTH - 3)}...`
+}
+
+function parseSelectionResult(value: unknown): string[] {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return []
+  const record = value as Record<string, unknown>
+  if (record['schemaVersion'] !== RESULT_SCHEMA_VERSION || !Array.isArray(record['tools'])) return []
+  const names: string[] = []
+  for (const candidate of record['tools']) {
+    if (typeof candidate !== 'object' || candidate === null || Array.isArray(candidate)) continue
+    const name = (candidate as Record<string, unknown>)['name']
+    if (typeof name === 'string' && name.length > 0) names.push(name)
+  }
+  return names
+}
+
+function sessionEvents(agent: Agent): readonly unknown[] {
+  const session = agent.session as unknown as {
+    events?: readonly unknown[]
+    snapshotEvents?: () => readonly unknown[]
+  }
+  if (typeof session.snapshotEvents === 'function') return session.snapshotEvents()
+  return Array.isArray(session.events) ? session.events : []
+}
+
+function selectedFromSession(agent: Agent): Set<string> {
+  const searchCalls = new Set<string>()
+  const selected = new Set<string>()
+  for (const rawEvent of sessionEvents(agent)) {
+    if (typeof rawEvent !== 'object' || rawEvent === null || Array.isArray(rawEvent)) continue
+    const event = rawEvent as { type?: unknown, data?: Record<string, unknown> }
+    if (event.type === 'tool/call' && event.data?.['name'] === TOOL_SEARCH_NAME) {
+      searchCalls.add(String(event.data['callId']))
+      continue
+    }
+    if (event.type !== 'tool/result' || typeof event.data?.['message'] !== 'object' || event.data['message'] === null) continue
+    const content = (event.data['message'] as { content?: unknown }).content
+    const result = Array.isArray(content) ? content[0] : undefined
+    if (typeof result !== 'object' || result === null || Array.isArray(result)) continue
+    const resultRecord = result as Record<string, unknown>
+    if (!searchCalls.has(String(resultRecord['toolCallId'])) || resultRecord['isError'] === true) continue
+    const blocks = resultRecord['content']
+    if (!Array.isArray(blocks)) continue
+    const text = blocks
+      .filter((block): block is { type: 'text', text: string } => (
+        typeof block === 'object'
+        && block !== null
+        && !Array.isArray(block)
+        && (block as Record<string, unknown>)['type'] === 'text'
+        && typeof (block as Record<string, unknown>)['text'] === 'string'
+      ))
+      .map(block => block.text)
+      .join('')
+    try {
+      for (const name of parseSelectionResult(JSON.parse(text))) selected.add(name)
+    } catch {
+      // Failed and legacy tool results are not successful selection transitions.
+    }
+  }
+  return selected
+}
+
+function toolSectionName(sectionName: string): string | undefined {
+  if (!sectionName.startsWith('tool:')) return undefined
+  const name = sectionName.slice('tool:'.length)
+  return name.length > 0 ? name : undefined
+}
+
+export class ToolSearchRuntime {
+  readonly definition: ToolDefinition
+  private readonly states = new Map<Agent, AgentState>()
+  private readonly policy: ToolPolicyResolver
+  private settings: ToolSearchSettings
+  private generation = 0
+
+  constructor(
+    private readonly ctx: Context,
+    settings: ToolSearchSettings,
+  ) {
+    this.settings = normalizeSettings(settings)
+    this.policy = new ToolPolicyResolver(this.settings)
+    this.definition = this.createDefinition()
+  }
+
+  install(): () => void {
+    const disposers = [
+      this.ctx.on('agent/created', ({ agent }) => { this.attach(agent) }),
+      this.ctx.on('agent/disposed', ({ agent }) => { this.detach(agent) }),
+      this.ctx.on('tools/result', (exec, result) => { this.commitSelection(exec, result) }),
+      this.ctx.on('tools/change', () => { this.generation += 1 }),
+      this.ctx.on('system-prompt/change', () => { this.generation += 1 }),
+    ]
+    for (const agent of this.ctx.agents.list()) this.attach(agent)
+    return () => {
+      for (const state of this.states.values()) state.disposeAssembly()
+      this.states.clear()
+      for (const dispose of disposers.reverse()) dispose()
+    }
+  }
+
+  updateSettings(value: ToolSearchSettings): void {
+    this.settings = normalizeSettings(value)
+    this.policy.update(this.settings)
+  }
+
+  snapshot(): CatalogSnapshot {
+    const tools = new Map<string, ToolCatalogEntry>()
+    for (const entry of buildCatalog(this.ctx.tools.schemas() as ToolSchemaLike[])) tools.set(entry.name, entry)
+    for (const state of this.states.values()) {
+      this.refreshCatalog(state)
+      for (const entry of state.catalog) tools.set(entry.name, entry)
+    }
+    return {
+      schemaVersion: 1,
+      generation: this.generation,
+      tools: [...tools.values()].sort((left, right) => compareNames(left.name, right.name)).map(tool => ({
+        name: tool.name,
+        description: summarize(tool.description),
+        policy: this.policy.classify(tool.name),
+        selectedBy: [...this.states.values()]
+          .filter(state => state.selected.has(tool.name))
+          .map(state => String(state.agent.id))
+          .sort(compareNames),
+      })),
+    }
+  }
+
+  selectedFor(agent: Agent): ReadonlySet<string> {
+    return this.requireState(agent).selected
+  }
+
+  private createDefinition(): ToolDefinition {
+    return defineTool({
+      name: TOOL_SEARCH_NAME,
+      description: 'Search deferred tool metadata with deterministic local BM25. Matching tools become available by their real names on the next model call. Results contain summaries, not full schemas.',
+      parameters: {
+        query: {
+          type: 'string',
+          required: true,
+          description: 'Search query for deferred tools.',
+        },
+        limit: {
+          type: 'integer',
+          description: 'Maximum number of tools to return. Defaults to 5.',
+        },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            schemaVersion: { type: 'integer', const: RESULT_SCHEMA_VERSION, required: true },
+            query: { type: 'string', required: true },
+            tools: {
+              type: 'array',
+              required: true,
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                  name: { type: 'string', required: true },
+                  description: { type: 'string', required: true },
+                  score: { type: 'number', required: true },
+                },
+              },
+            },
+          },
+        },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+      },
+      execute: (args, exec) => Promise.resolve(this.search(args, exec)),
+      finalizeContent: (_exec, result) => result.isError
+        ? undefined
+        : [{ type: 'text', text: JSON.stringify(result.value) }],
+      presentCall: args => ({
+        card: 'generic',
+        title: 'Search deferred tools',
+        kind: 'read',
+        rawInput: typeof args === 'object' && args !== null && 'query' in args
+          ? String((args as { query: unknown }).query)
+          : undefined,
+      }),
+    })
+  }
+
+  private search(args: { query: string; limit?: number }, exec: ToolRunContext): ToolSearchResult {
+    const agent = exec.agent
+    if (agent === undefined) throw new Error(`${TOOL_SEARCH_NAME}: an Agent Session is required`)
+    const query = args.query.trim()
+    if (query.length === 0) throw new Error(`${TOOL_SEARCH_NAME}: query must not be empty`)
+    if (query.length > MAX_QUERY_LENGTH) throw new Error(`${TOOL_SEARCH_NAME}: query exceeds ${MAX_QUERY_LENGTH} characters`)
+    if (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || args.limit < 1 || args.limit > MAX_RESULT_LIMIT)) {
+      throw new Error(`${TOOL_SEARCH_NAME}: limit must be an integer between 1 and ${MAX_RESULT_LIMIT}`)
+    }
+
+    const state = this.requireState(agent)
+    this.refreshCatalog(state)
+    const deferred = state.catalog.filter(tool => this.policy.classify(tool.name, state.selected) === 'deferred')
+    const index = new Bm25Index(deferred.map(tool => ({ id: tool, name: tool.name, text: tool.searchText })))
+    const limit = args.limit ?? this.settings.defaultLimit
+    const tools = index.search(query, limit).map(match => ({
+      name: match.id.name,
+      description: summarize(match.id.description),
+      score: Number(match.score.toFixed(6)),
+    }))
+    return { schemaVersion: RESULT_SCHEMA_VERSION, query, tools }
+  }
+
+  private commitSelection(exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): void {
+    if (exec.name !== TOOL_SEARCH_NAME || exec.agent === undefined || result.isError) return
+    const state = this.requireState(exec.agent)
+    for (const name of parseSelectionResult(result.value)) state.selected.add(name)
+  }
+
+  private attach(agent: Agent): void {
+    if (this.states.has(agent)) return
+    const selected = selectedFromSession(agent)
+    const state = {
+      agent,
+      selected,
+      catalog: [],
+      catalogGeneration: -1,
+      disposeAssembly: () => {},
+    }
+    state.disposeAssembly = agent.ctx.on(
+      'system-prompt/assemble',
+      async (_assembly, _context, next) => this.filterAssembly(state, await next()),
+      { prepend: true },
+    )
+    this.states.set(agent, state)
+  }
+
+  private detach(agent: Agent): void {
+    const state = this.states.get(agent)
+    if (state === undefined) return
+    this.states.delete(agent)
+  }
+
+  private requireState(agent: Agent): AgentState {
+    this.attach(agent)
+    const state = this.states.get(agent)
+    if (state === undefined) throw new Error(`${TOOL_SEARCH_NAME}: Agent state could not be initialized`)
+    return state
+  }
+
+  private refreshCatalog(state: AgentState): void {
+    if (state.catalogGeneration === this.generation) return
+    state.catalog = buildCatalog(this.ctx.tools.schemas(state.agent) as ToolSchemaLike[])
+    state.catalogGeneration = this.generation
+  }
+
+  private filterAssembly(state: AgentState, assembly: PromptAssembly): PromptAssembly {
+    if (assembly.sections.some(section => section.name === 'tools:sdk' && section.text.trim().length > 0)) {
+      throw new Error('dsh-tool-search requires native tool presentation; code/PTC and both modes are unsupported')
+    }
+    state.catalog = buildCatalog(assembly.tools as ToolSchemaLike[])
+    state.catalogGeneration = this.generation
+    const visible = new Set(
+      assembly.tools
+        .map(tool => tool.name)
+        .filter(name => this.policy.classify(name, state.selected) === 'always'),
+    )
+    const hidden = new Set(assembly.tools.map(tool => tool.name).filter(name => !visible.has(name)))
+    return {
+      ...assembly,
+      tools: assembly.tools.filter(tool => visible.has(tool.name)),
+      sections: assembly.sections.filter(section => {
+        const name = toolSectionName(section.name)
+        return name === undefined || !hidden.has(name)
+      }),
+    }
+  }
+}

package/src/settings.ts

@@ -0,0 +1,63 @@
+/** Validated Host settings and policy resolution. */
+
+import z from '@deepseek-ai/schemastery'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import {
+  DEFAULT_CORE_TOOLS,
+  DEFAULT_RESULT_LIMIT,
+  MAX_RESULT_LIMIT,
+  TOOL_SEARCH_NAME,
+  TOOL_SEARCH_SETTINGS_NAMESPACE,
+  type ToolPolicy,
+  type ToolSearchSettings,
+} from './shared.ts'
+
+export const TOOL_SEARCH_SETTINGS_NS = TOOL_SEARCH_SETTINGS_NAMESPACE as SettingsNamespace
+
+export const Config: z<ToolSearchSettings> = z.object({
+  defaultLimit: z.number().step(1).min(1).max(MAX_RESULT_LIMIT).default(DEFAULT_RESULT_LIMIT),
+  alwaysVisible: z.array(z.string()).default([]),
+  neverSearch: z.array(z.string()).default([]),
+})
+
+function normalizeNames(names: readonly string[]): string[] {
+  const normalized = new Set<string>()
+  for (const value of names) {
+    const name = value.trim()
+    if (name.length > 0) normalized.add(name)
+  }
+  return [...normalized].sort()
+}
+
+export function normalizeSettings(value: ToolSearchSettings): ToolSearchSettings {
+  const defaultLimit = Number.isSafeInteger(value.defaultLimit)
+    ? Math.min(MAX_RESULT_LIMIT, Math.max(1, value.defaultLimit))
+    : DEFAULT_RESULT_LIMIT
+  return {
+    defaultLimit,
+    alwaysVisible: normalizeNames(value.alwaysVisible),
+    neverSearch: normalizeNames(value.neverSearch).filter(name => name !== TOOL_SEARCH_NAME),
+  }
+}
+
+export class ToolPolicyResolver {
+  private readonly core = new Set<string>(DEFAULT_CORE_TOOLS)
+  private always = new Set<string>()
+  private blocked = new Set<string>()
+
+  constructor(settings: ToolSearchSettings) {
+    this.update(settings)
+  }
+
+  update(settings: ToolSearchSettings): void {
+    this.always = new Set(settings.alwaysVisible)
+    this.blocked = new Set(settings.neverSearch)
+  }
+
+  classify(name: string, selected?: ReadonlySet<string>): ToolPolicy {
+    if (name === TOOL_SEARCH_NAME) return 'always'
+    if (this.blocked.has(name)) return 'blocked'
+    if (this.core.has(name) || this.always.has(name) || selected?.has(name) === true) return 'always'
+    return 'deferred'
+  }
+}

package/src/shared.ts

@@ -0,0 +1,63 @@
+/** Values shared by the Host runtime and Web settings client. */
+
+export const TOOL_SEARCH_NAME = 'tool_search'
+export const TOOL_SEARCH_SETTINGS_NAMESPACE = 'tool-search'
+export const TOOL_SEARCH_CATALOG_ROUTE = '/_dsh/tool-search/catalog'
+export const DEFAULT_RESULT_LIMIT = 5
+export const MAX_RESULT_LIMIT = 20
+
+/**
+ * Stable bootstrap surface for current DSH releases. Unknown future first-party
+ * names are deferred until this list or the user allowlist is updated because
+ * ToolDefinition does not expose package provenance.
+ */
+export const DEFAULT_CORE_TOOLS = Object.freeze([
+  'apply_patch',
+  'ask_user_question',
+  'bash',
+  'create_goal',
+  'dsh_im_return_file',
+  'exit_plan_mode',
+  'get_goal',
+  'interrupt_agent',
+  'job_kill',
+  'job_list',
+  'job_output',
+  'list_agents',
+  'ralph',
+  'report',
+  'send_message',
+  'skill',
+  'subagent',
+  'subagent_fork',
+  'todo_write',
+  'update_goal',
+  'workflow',
+] as const)
+
+export interface ToolSearchSettings {
+  defaultLimit: number
+  alwaysVisible: string[]
+  neverSearch: string[]
+}
+
+export const DEFAULT_SETTINGS: Readonly<ToolSearchSettings> = Object.freeze({
+  defaultLimit: DEFAULT_RESULT_LIMIT,
+  alwaysVisible: [],
+  neverSearch: [],
+})
+
+export type ToolPolicy = 'always' | 'deferred' | 'blocked'
+
+export interface CatalogToolSummary {
+  name: string
+  description: string
+  policy: ToolPolicy
+  selectedBy: string[]
+}
+
+export interface CatalogSnapshot {
+  schemaVersion: 1
+  generation: number
+  tools: CatalogToolSummary[]
+}

package/src/web.ts

@@ -0,0 +1,34 @@
+/** Read-only live catalog endpoint for the Web settings page. */
+
+import type { ServerResponse } from 'node:http'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { TOOL_SEARCH_CATALOG_ROUTE } from './shared.ts'
+import type { ToolSearchRuntime } from './runtime.ts'
+
+function sendJson(res: ServerResponse, status: number, value: unknown): void {
+  const body = Buffer.from(JSON.stringify(value))
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  res.setHeader('Content-Length', String(body.length))
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('X-Content-Type-Options', 'nosniff')
+  res.writeHead(status)
+  res.end(body)
+}
+
+export function installCatalogRoute(ctx: Context, runtime: ToolSearchRuntime): void {
+  ctx.inject(['webServer'], webCtx => {
+    webCtx.effect(() => webCtx.webServer.register({
+      kind: 'exact',
+      path: TOOL_SEARCH_CATALOG_ROUTE,
+      handler: (req, res) => {
+        if (req.method !== 'GET') {
+          res.setHeader('Allow', 'GET')
+          sendJson(res, 405, { error: 'method-not-allowed' })
+          return
+        }
+        sendJson(res, 200, runtime.snapshot())
+      },
+    }), 'dsh-tool-search: Web catalog route')
+  })
+}

package/src/wink-porter2-stemmer.d.ts

@@ -0,0 +1,3 @@
+declare module 'wink-porter2-stemmer' {
+  export default function stem(token: string): string
+}

package/tests/bm25.spec.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest'
+import { Bm25Index, tokenize } from '../src/bm25.ts'
+import { toolSearchText, type ToolSchemaLike } from '../src/catalog.ts'
+
+const tools: ToolSchemaLike[] = [
+  {
+    name: 'browser_take_screenshot',
+    description: 'Capture a screenshot of a web page or selected element.',
+    parameters: { properties: { target: { description: 'Element to capture.' } } },
+  },
+  {
+    name: 'web_search',
+    description: 'Search the public web for current information and sources.',
+    parameters: { properties: { queries: { description: 'Search queries.' } } },
+  },
+  {
+    name: 'read_image',
+    description: 'Inspect a local PNG JPEG WebP or GIF image.',
+    parameters: { properties: { file_path: { description: 'Image path.' } } },
+  },
+  {
+    name: 'browser_file_upload',
+    description: 'Upload one or more local files through a browser file chooser.',
+    parameters: { properties: { paths: { description: 'Absolute file paths.' } } },
+  },
+  {
+    name: 'browser_network_requests',
+    description: 'List HTTP network requests made by the current browser page.',
+    parameters: { properties: { filter: { description: 'URL regular expression.' } } },
+  },
+  {
+    name: 'dsh_im_return_file',
+    description: 'Send an existing local file to the user.',
+    parameters: { properties: { path: { description: 'File to deliver.' } } },
+  },
+  {
+    name: 'browser_navigate',
+    description: 'Navigate the browser to a URL.',
+    parameters: { properties: { url: { description: 'Destination URL.' } } },
+  },
+]
+
+function index() {
+  return new Bm25Index(tools.map(tool => ({ id: tool.name, name: tool.name, text: toolSearchText(tool) })))
+}
+
+describe('deterministic BM25', () => {
+  it('guarantees exact-name Recall@1 even for a weak lexical score', () => {
+    expect(index().search('browser_network_requests', 1)[0]?.name).toBe('browser_network_requests')
+  })
+
+  it.each([
+    ['take a screenshot of this page', 'browser_take_screenshot'],
+    ['search online for recent sources', 'web_search'],
+    ['inspect this png image', 'read_image'],
+    ['upload a file in the web page', 'browser_file_upload'],
+    ['send this local file to the user', 'dsh_im_return_file'],
+  ])('places capability query %j within Top-5', (query, expected) => {
+    expect(index().search(query, 5).map(result => result.name)).toContain(expected)
+  })
+
+  it('uses lexical tool name as the stable equal-score tie-break', () => {
+    const tied = new Bm25Index([
+      { id: 2, name: 'zeta_tool', text: 'shared capability' },
+      { id: 1, name: 'alpha_tool', text: 'shared capability' },
+    ])
+    const first = tied.search('shared capability', 2)
+    for (let run = 0; run < 20; run += 1) expect(tied.search('shared capability', 2)).toEqual(first)
+    expect(first.map(result => result.name)).toEqual(['alpha_tool', 'zeta_tool'])
+  })
+
+  it('normalizes, removes English stop words, and stems terms', () => {
+    expect(tokenize('The uploaded files are RUNNING')).toEqual(['upload', 'file', 'run'])
+  })
+})

package/tests/catalog.spec.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { appendSchemaSearchText, toolSearchText } from '../src/catalog.ts'
+
+describe('Codex-aligned search documents', () => {
+  it('indexes the exact required fields and recursively nested descriptions', () => {
+    const text = toolSearchText({
+      name: 'browser_take_screenshot',
+      description: 'Capture the active browser page.',
+      parameters: {
+        type: 'object',
+        description: 'Screenshot request.',
+        properties: {
+          target: {
+            type: 'object',
+            description: 'Optional element target.',
+            properties: {
+              selector: { type: 'string', description: 'Unique CSS selector.' },
+            },
+          },
+          formats: {
+            type: 'array',
+            description: 'Requested encodings.',
+            items: { type: 'string', description: 'One image encoding.' },
+          },
+          destination: {
+            anyOf: [
+              { type: 'string', description: 'Output filename.' },
+              {
+                type: 'object',
+                properties: {
+                  artifact: { type: 'boolean', description: 'Return an artifact.' },
+                },
+              },
+            ],
+          },
+        },
+      },
+    })
+
+    expect(text).toContain('browser_take_screenshot browser take screenshot')
+    expect(text).toContain('Capture the active browser page.')
+    expect(text).toContain('Screenshot request.')
+    expect(text).toContain('destination')
+    expect(text).toContain('formats Requested encodings. One image encoding.')
+    expect(text).toContain('target Optional element target. selector Unique CSS selector.')
+    expect(text).toContain('Output filename.')
+    expect(text).toContain('artifact Return an artifact.')
+    expect(text.indexOf('destination')).toBeLessThan(text.indexOf('formats'))
+    expect(text.indexOf('formats')).toBeLessThan(text.indexOf('target'))
+  })
+
+  it('ignores unsupported schema annotations and malformed nodes', () => {
+    const parts: string[] = []
+    appendSchemaSearchText({
+      title: 'Not indexed',
+      examples: ['Not indexed'],
+      properties: null,
+      items: 'not-a-schema',
+      anyOf: [{ description: 'Indexed branch' }, null],
+    }, parts)
+    expect(parts).toEqual(['Indexed branch'])
+  })
+})

package/tests/client.spec.tsx

@@ -0,0 +1,39 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { ToolSearchSettingsSection } from '../src/client/index.tsx'
+import type { ToolSearchSettings } from '../src/shared.ts'
+
+describe('Tool Search settings section', () => {
+  it('renders the live catalog and persists policy changes', async () => {
+    const set = vi.fn(() => Promise.resolve())
+    const value: ToolSearchSettings = { defaultLimit: 5, alwaysVisible: [], neverSearch: [] }
+    const snapshot = { status: 'ready' as const, value, writable: true }
+    const scope = {
+      getSnapshot: () => snapshot,
+      subscribe: () => () => {},
+      set,
+    }
+    vi.stubGlobal('fetch', vi.fn(() => Promise.resolve(new Response(JSON.stringify({
+      schemaVersion: 1,
+      generation: 2,
+      tools: [{
+        name: 'browser_take_screenshot',
+        description: 'Capture a browser screenshot.',
+        policy: 'deferred',
+        selectedBy: [],
+      }],
+    }), { status: 200 }))))
+
+    render(<ToolSearchSettingsSection scope={scope} />)
+    expect(await screen.findByText('browser_take_screenshot')).toBeDefined()
+    expect(screen.getByLabelText('Live agents: 0').getAttribute('data-label')).toBe('Live agents')
+    fireEvent.change(screen.getByLabelText('Policy: browser_take_screenshot'), { target: { value: 'always' } })
+    await waitFor(() => {
+      expect(set).toHaveBeenCalledWith('alwaysVisible', ['browser_take_screenshot'])
+      expect(set).toHaveBeenCalledWith('neverSearch', [])
+    })
+    vi.unstubAllGlobals()
+  })
+})