@anionex/dsh-tool-search 0.1.0

package/tests/execution-regression.spec.ts

@@ -0,0 +1,200 @@
+import { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime, { defineTool } from '@deepseek-ai/dsh-tools'
+import { describe, expect, it, vi } from 'vitest'
+import { ToolSearchRuntime } from '../src/runtime.ts'
+import { TOOL_SEARCH_NAME } from '../src/shared.ts'
+
+describe('real ToolRuntime execution regression', () => {
+  it('preserves approval, guard, around, body, post, and result semantics for a deferred tool', async () => {
+    const ctx = new Context()
+    const promptFiber = ctx.plugin(SystemPrompt, {})
+    await promptFiber.await()
+    const toolFiber = ctx.plugin(ToolRuntime, { mode: 'native' })
+    await toolFiber.await()
+
+    const order: string[] = []
+    const approval = vi.fn(() => {
+      order.push('approval')
+      return Promise.resolve('allowed-once' as const)
+    })
+    ctx.provide('approval', { request: approval } as never)
+    ctx.provide('agents', { list: () => [] } as never)
+
+    ctx.on('tools/pre-execute', async () => {
+      order.push('pre')
+      return { kind: 'ask', reason: 'regression approval' }
+    })
+    ctx.tools.guard(() => {
+      order.push('guard')
+      return undefined
+    })
+    ctx.on('tools/execute', async (_exec, next) => {
+      order.push('around:before')
+      const result = await next()
+      order.push('around:after')
+      return result
+    })
+    ctx.on('tools/post-execute', async (_exec, _result, next) => {
+      order.push('post')
+      return next()
+    })
+    ctx.on('tools/result', () => { order.push('result') })
+
+    ctx.tools.register(defineTool({
+      name: 'deferred_dangerous_operation',
+      description: 'A deferred operation used by the pipeline regression test.',
+      parameters: {},
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { ok: { type: 'boolean', required: true } },
+        },
+        render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+      },
+      execute: () => {
+        order.push('body')
+        return Promise.resolve({ ok: true })
+      },
+    }))
+
+    const assemblyListeners: Array<(...args: never[]) => unknown> = []
+    const agent = {
+      id: 'pipeline-agent',
+      session: { events: [] },
+      ctx: {
+        on: (_name: string, listener: (...args: never[]) => unknown) => {
+          assemblyListeners.push(listener)
+          return () => {}
+        },
+      },
+    } as unknown as Agent
+    const search = new ToolSearchRuntime(ctx, {
+      defaultLimit: 5,
+      alwaysVisible: [],
+      neverSearch: [],
+    })
+    const disposeSearch = search.install()
+    search.selectedFor(agent)
+
+    const result = await ctx.tools.execute({
+      callId: 'pipeline-call' as never,
+      name: 'deferred_dangerous_operation',
+      arguments: {},
+      agent,
+      signal: new AbortController().signal,
+    })
+
+    expect(result.isError).toBe(false)
+    expect(approval).toHaveBeenCalledOnce()
+    expect(order).toEqual([
+      'pre',
+      'approval',
+      'guard',
+      'around:before',
+      'body',
+      'around:after',
+      'post',
+      'result',
+    ])
+    expect(ctx.tools.get('deferred_dangerous_operation', agent)).toBeDefined()
+    expect(assemblyListeners).toHaveLength(1)
+    disposeSearch()
+    await toolFiber.dispose()
+    await promptFiber.dispose()
+  })
+
+  it('commits selection after final success and preserves a recoverable canonical result', async () => {
+    const ctx = new Context()
+    const promptFiber = ctx.plugin(SystemPrompt, {})
+    await promptFiber.await()
+    const toolFiber = ctx.plugin(ToolRuntime, { mode: 'native' })
+    await toolFiber.await()
+    ctx.provide('agents', { list: () => [] } as never)
+
+    ctx.tools.register(defineTool({
+      name: 'browser_take_screenshot',
+      description: 'Capture a screenshot of a browser page.',
+      parameters: {},
+      output: {
+        schema: { type: 'string' },
+        render: (_args, value) => [{ type: 'text', text: value }],
+      },
+      execute: () => Promise.resolve('captured'),
+    }))
+
+    ctx.on('tools/post-execute', async (exec, _result, next) => {
+      if (exec.name !== TOOL_SEARCH_NAME) return next()
+      if ((exec.arguments as { query?: string }).query?.includes('blocked') === true) {
+        return { kind: 'block', feedback: [{ type: 'text', text: 'blocked after body' }] }
+      }
+      return { kind: 'accept', content: [{ type: 'text', text: 'post-execute replacement' }] }
+    })
+
+    const agent = {
+      id: 'search-commit-agent',
+      session: { events: [] },
+      ctx: { on: () => () => {} },
+    } as unknown as Agent
+    const search = new ToolSearchRuntime(ctx, {
+      defaultLimit: 5,
+      alwaysVisible: [],
+      neverSearch: [],
+    })
+    ctx.tools.register(search.definition)
+    const disposeSearch = search.install()
+
+    const blocked = await ctx.tools.execute({
+      callId: 'blocked-search' as never,
+      name: TOOL_SEARCH_NAME,
+      arguments: { query: 'browser screenshot blocked', limit: 1 },
+      agent,
+      signal: new AbortController().signal,
+    })
+    expect(blocked.isError).toBe(true)
+    expect([...search.selectedFor(agent)]).toEqual([])
+
+    const accepted = await ctx.tools.execute({
+      callId: 'accepted-search' as never,
+      name: TOOL_SEARCH_NAME,
+      arguments: { query: 'browser screenshot', limit: 1 },
+      agent,
+      signal: new AbortController().signal,
+    })
+    expect(accepted.isError).toBe(false)
+    expect([...search.selectedFor(agent)]).toEqual(['browser_take_screenshot'])
+    const text = accepted.content.filter(block => block.type === 'text').map(block => block.text).join('')
+    expect(text).not.toBe('post-execute replacement')
+    expect(JSON.parse(text).tools[0].name).toBe('browser_take_screenshot')
+
+    const resumedAgent = {
+      id: 'resumed-search-agent',
+      session: {
+        events: [{
+          type: 'tool/call',
+          data: { callId: 'accepted-search', name: TOOL_SEARCH_NAME, arguments: '{"query":"browser screenshot"}' },
+        }, {
+          type: 'tool/result',
+          data: {
+            message: {
+              content: [{
+                type: 'tool-result',
+                toolCallId: 'accepted-search',
+                isError: false,
+                content: accepted.content,
+              }],
+            },
+          },
+        }],
+      },
+      ctx: { on: () => () => {} },
+    } as unknown as Agent
+    expect([...search.selectedFor(resumedAgent)]).toEqual(['browser_take_screenshot'])
+
+    disposeSearch()
+    await toolFiber.dispose()
+    await promptFiber.dispose()
+  })
+})

package/tests/runtime.spec.ts

@@ -0,0 +1,271 @@
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
+import { describe, expect, it, vi } from 'vitest'
+import type { ToolSchemaLike } from '../src/catalog.ts'
+import { ToolSearchRuntime, type ToolSearchResult } from '../src/runtime.ts'
+import { TOOL_SEARCH_NAME, type ToolSearchSettings } from '../src/shared.ts'
+
+type AssemblyListener = (
+  assembly: PromptAssembly,
+  context: object,
+  next: () => Promise<PromptAssembly>,
+) => Promise<PromptAssembly>
+
+type RootListener = (...args: unknown[]) => unknown
+
+function schema(name: string, description: string): ToolSchemaLike {
+  return {
+    name,
+    description,
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        target: { type: 'string', description: `${description} target.` },
+      },
+    },
+  }
+}
+
+function makeAgent(id: string, events: unknown[] = [], sessionApi: 'events' | 'snapshot' = 'events') {
+  let assemblyListener: AssemblyListener | undefined
+  const agent = {
+    id,
+    session: sessionApi === 'snapshot' ? { snapshotEvents: () => events } : { events },
+    ctx: {
+      on(name: string, listener: AssemblyListener) {
+        if (name === 'system-prompt/assemble') assemblyListener = listener
+        return () => {
+          if (assemblyListener === listener) assemblyListener = undefined
+        }
+      },
+    },
+  } as unknown as Agent
+  return {
+    agent,
+    assemble(assembly: PromptAssembly): Promise<PromptAssembly> {
+      if (assemblyListener === undefined) throw new Error('assembly listener was not installed')
+      return assemblyListener(assembly, {}, () => Promise.resolve(assembly))
+    },
+  }
+}
+
+function harness(options: {
+  agents?: ReturnType<typeof makeAgent>[]
+  settings?: Partial<ToolSearchSettings>
+  schemas?: ToolSchemaLike[]
+} = {}) {
+  const agents = options.agents ?? [makeAgent('agent-1')]
+  let schemas = options.schemas ?? [
+    schema('apply_patch', 'Edit files with a patch'),
+    schema(TOOL_SEARCH_NAME, 'Search deferred tools'),
+    schema('browser_take_screenshot', 'Capture a browser screenshot'),
+    schema('web_search', 'Search current public web sources'),
+    schema('read_image', 'Inspect a local image'),
+  ]
+  const listeners = new Map<string, RootListener[]>()
+  const ctx = {
+    agents: { list: () => agents.map(item => item.agent) },
+    tools: { schemas: () => schemas },
+    logger: { warn: vi.fn() },
+    on(name: string, listener: RootListener) {
+      const rows = listeners.get(name) ?? []
+      rows.push(listener)
+      listeners.set(name, rows)
+      return () => listeners.set(name, rows.filter(row => row !== listener))
+    },
+  }
+  const runtime = new ToolSearchRuntime(ctx as never, {
+    defaultLimit: 5,
+    alwaysVisible: [],
+    neverSearch: [],
+    ...options.settings,
+  })
+  const dispose = runtime.install()
+  const assembly = (): PromptAssembly => ({
+    sections: schemas.map(tool => ({ name: `tool:${tool.name}`, text: `${tool.name} guidance` })),
+    contexts: [],
+    tools: schemas as never,
+    variables: {},
+  })
+  return {
+    agents,
+    runtime,
+    dispose,
+    setSchemas(next: ToolSchemaLike[]) { schemas = next },
+    emit(name: string, ...args: unknown[]) {
+      for (const listener of listeners.get(name) ?? []) listener(...args)
+    },
+    assembly,
+    async search(agent: Agent, query: string, limit?: number): Promise<ToolSearchResult> {
+      const exec = {
+        agent,
+        name: TOOL_SEARCH_NAME,
+        callId: 'call-search',
+        rootCallId: 'call-search',
+        token: Symbol('test-token'),
+        arguments: { query },
+        signal: new AbortController().signal,
+      }
+      const value = await runtime.definition.execute(
+        { query, ...(limit === undefined ? {} : { limit }) },
+        exec as never,
+      ) as ToolSearchResult
+      this.emit('tools/result', exec, {
+        isError: false,
+        value,
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+      })
+      return value
+    },
+  }
+}
+
+function recoveryEvents(selected: string[]): unknown[] {
+  return [{
+    type: 'tool/call',
+    data: { callId: 'search-1', name: TOOL_SEARCH_NAME, arguments: '{"query":"image"}' },
+  }, {
+    type: 'tool/result',
+    data: {
+      message: {
+        content: [{
+          type: 'tool-result',
+          toolCallId: 'search-1',
+          isError: false,
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              schemaVersion: 1,
+              query: 'image',
+              tools: selected.map(name => ({ name, description: '', score: 1 })),
+            }),
+          }],
+        }],
+      },
+    },
+  }]
+}
+
+describe('ToolSearchRuntime', () => {
+  it('reveals deferred schemas on the next assembly and never returns full schemas', async () => {
+    const app = harness()
+    const initial = await app.agents[0]!.assemble(app.assembly())
+    expect(initial.tools.map(tool => tool.name)).toEqual(['apply_patch', TOOL_SEARCH_NAME])
+    expect(initial.sections.map(section => section.name)).toEqual(['tool:apply_patch', `tool:${TOOL_SEARCH_NAME}`])
+
+    let modelCalls = 1
+    const result = await app.search(app.agents[0]!.agent, 'browser_take_screenshot', 1)
+    expect(JSON.stringify(result)).not.toMatch(/parameters|properties|schema\s*:/u)
+    expect(result.tools.map(tool => tool.name)).toEqual(['browser_take_screenshot'])
+
+    modelCalls += 1
+    const next = await app.agents[0]!.assemble(app.assembly())
+    expect(next.tools.map(tool => tool.name)).toEqual(['apply_patch', TOOL_SEARCH_NAME, 'browser_take_screenshot'])
+    expect(modelCalls).toBe(2)
+    app.dispose()
+  })
+
+  it('keeps selected sets isolated per agent and monotonically growing', async () => {
+    const first = makeAgent('first')
+    const second = makeAgent('second')
+    const app = harness({ agents: [first, second] })
+    await app.search(first.agent, 'browser_take_screenshot', 1)
+    await app.search(first.agent, 'web_search', 1)
+    expect([...app.runtime.selectedFor(first.agent)].sort()).toEqual(['browser_take_screenshot', 'web_search'])
+    expect([...app.runtime.selectedFor(second.agent)]).toEqual([])
+    expect((await first.assemble(app.assembly())).tools.map(tool => tool.name)).toContain('web_search')
+    expect((await second.assemble(app.assembly())).tools.map(tool => tool.name)).not.toContain('web_search')
+    app.dispose()
+  })
+
+  it('recovers selected sets independently from resume and fork history prefixes', async () => {
+    const resume = makeAgent('resume', recoveryEvents(['read_image', 'web_search']), 'snapshot')
+    const fork = makeAgent('fork', recoveryEvents(['read_image']))
+    const app = harness({ agents: [resume, fork] })
+    expect([...app.runtime.selectedFor(resume.agent)].sort()).toEqual(['read_image', 'web_search'])
+    expect([...app.runtime.selectedFor(fork.agent)]).toEqual(['read_image'])
+    expect((await resume.assemble(app.assembly())).tools.map(tool => tool.name)).toContain('web_search')
+    expect((await fork.assemble(app.assembly())).tools.map(tool => tool.name)).not.toContain('web_search')
+    app.dispose()
+  })
+
+  it('invalidates every agent catalog when registry metadata changes', async () => {
+    const app = harness()
+    await app.agents[0]!.assemble(app.assembly())
+    app.setSchemas([
+      ...app.assembly().tools as never,
+      schema('browser_pdf_export', 'Export the browser page as a PDF document'),
+    ])
+    app.emit('tools/change')
+    const result = await app.search(app.agents[0]!.agent, 'browser_pdf_export', 1)
+    expect(result.tools[0]?.name).toBe('browser_pdf_export')
+    app.dispose()
+  })
+
+  it('applies live policies without deleting selected history', async () => {
+    const app = harness()
+    await app.search(app.agents[0]!.agent, 'web_search', 1)
+    app.runtime.updateSettings({
+      defaultLimit: 5,
+      alwaysVisible: ['read_image'],
+      neverSearch: ['web_search'],
+    })
+    const blocked = await app.agents[0]!.assemble(app.assembly())
+    expect(blocked.tools.map(tool => tool.name)).toContain('read_image')
+    expect(blocked.tools.map(tool => tool.name)).not.toContain('web_search')
+    expect(app.runtime.selectedFor(app.agents[0]!.agent).has('web_search')).toBe(true)
+    app.runtime.updateSettings({ defaultLimit: 5, alwaysVisible: [], neverSearch: [] })
+    expect((await app.agents[0]!.assemble(app.assembly())).tools.map(tool => tool.name)).toContain('web_search')
+    app.dispose()
+  })
+
+  it('commits selections only from final successful tool results', async () => {
+    const app = harness()
+    const agent = app.agents[0]!.agent
+    const exec = {
+      agent,
+      name: TOOL_SEARCH_NAME,
+      callId: 'pending-search',
+      rootCallId: 'pending-search',
+      token: Symbol('pending-search'),
+      arguments: { query: 'web_search' },
+      signal: new AbortController().signal,
+    }
+    const value = await app.runtime.definition.execute({ query: 'web_search', limit: 1 }, exec as never) as ToolSearchResult
+    expect([...app.runtime.selectedFor(agent)]).toEqual([])
+
+    app.emit('tools/result', exec, {
+      isError: true,
+      error: { message: 'blocked after execution' },
+      content: [{ type: 'text', text: 'blocked' }],
+    })
+    expect([...app.runtime.selectedFor(agent)]).toEqual([])
+
+    app.emit('tools/result', exec, {
+      isError: false,
+      value,
+      content: [{ type: 'text', text: 'post-execute replacement' }],
+    })
+    expect([...app.runtime.selectedFor(agent)]).toEqual(['web_search'])
+    app.dispose()
+  })
+
+  it('rejects code and both presentation assemblies', async () => {
+    const app = harness()
+    const assembly = app.assembly()
+    assembly.sections.push({ name: 'tools:sdk', text: 'generated tool SDK' })
+    await expect(app.agents[0]!.assemble(assembly)).rejects.toThrow(/requires native tool presentation/u)
+    app.dispose()
+  })
+
+  it('accepts an empty SDK section from an Agent-scoped native override', async () => {
+    const app = harness()
+    const assembly = app.assembly()
+    assembly.sections.push({ name: 'tools:sdk', text: '' })
+    await expect(app.agents[0]!.assemble(assembly)).resolves.toMatchObject({
+      tools: [{ name: 'apply_patch' }, { name: TOOL_SEARCH_NAME }],
+    })
+    app.dispose()
+  })
+})

package/tests/settings.spec.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { ToolPolicyResolver, normalizeSettings } from '../src/settings.ts'
+import { TOOL_SEARCH_NAME } from '../src/shared.ts'
+
+describe('tool exposure policy', () => {
+  it('normalizes exact-name lists deterministically', () => {
+    expect(normalizeSettings({
+      defaultLimit: 200,
+      alwaysVisible: [' zeta ', 'alpha', '', 'alpha'],
+      neverSearch: ['danger', TOOL_SEARCH_NAME, 'danger'],
+    })).toEqual({
+      defaultLimit: 20,
+      alwaysVisible: ['alpha', 'zeta'],
+      neverSearch: ['danger'],
+    })
+  })
+
+  it('keeps core tools visible, defers long-tail tools, and lets blacklist win', () => {
+    const policy = new ToolPolicyResolver({
+      defaultLimit: 5,
+      alwaysVisible: ['custom_tool', 'conflict_tool'],
+      neverSearch: ['conflict_tool', 'bash'],
+    })
+    expect(policy.classify(TOOL_SEARCH_NAME)).toBe('always')
+    expect(policy.classify('apply_patch')).toBe('always')
+    expect(policy.classify('report')).toBe('always')
+    expect(policy.classify('bash')).toBe('blocked')
+    expect(policy.classify('custom_tool')).toBe('always')
+    expect(policy.classify('conflict_tool')).toBe('blocked')
+    expect(policy.classify('browser_take_screenshot')).toBe('deferred')
+    expect(policy.classify('browser_take_screenshot', new Set(['browser_take_screenshot']))).toBe('always')
+  })
+})

package/tsconfig.client.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "rootDir": "src",
+    "outDir": ".client-build",
+    "declarationDir": "lib/types",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": false,
+    "noEmitOnError": true,
+    "types": ["react", "react-dom"]
+  },
+  "include": ["src/shared.ts", "src/client/**/*.ts", "src/client/**/*.tsx"],
+  "exclude": ["tests", "lib", ".client-build", "node_modules"]
+}

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true,
+    "rootDir": "src",
+    "outDir": "lib",
+    "declarationDir": "./lib/types",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": false,
+    "noEmitOnError": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/client", "tests", "lib", ".client-build", "node_modules"]
+}

package/tsconfig.test.json

@@ -0,0 +1,23 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": false,
+    "types": ["node", "react", "react-dom", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "tests/**/*.ts", "tests/**/*.tsx"],
+  "exclude": ["lib", ".client-build", "node_modules"]
+}

package/tsdown.config.mjs

@@ -0,0 +1,37 @@
+import { defineConfig } from 'tsdown'
+
+const id = '@anionex/dsh-tool-search'
+const platformModules = [
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-runtime/client',
+  '@deepseek-ai/dsh-client-ui-settings/client',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-locale/client',
+]
+
+export default defineConfig({
+  entry: { client: 'src/client/index.tsx' },
+  format: 'cjs',
+  platform: 'browser',
+  target: 'es2022',
+  outDir: 'lib',
+  clean: false,
+  sourcemap: true,
+  dts: false,
+  minify: false,
+  deps: {
+    neverBundle: platformModules,
+    alwaysBundle: dependency => platformModules.includes(dependency) ? undefined : true,
+    onlyBundle: false,
+  },
+  outputOptions: {
+    entryFileNames: 'client.js',
+    banner: `window.__ModuleLoader__.load({ id: ${JSON.stringify(id)}, factory: (require) => {`,
+    footer: 'return module.exports; } });',
+    intro: 'var module = { exports: {} }; var exports = module.exports;',
+  },
+})