@anionex/dsh-tool-search 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-tool-search",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Codex-style deferred tool loading for DSH with deterministic local BM25 search",
   "keywords": [
     "deepseek",
@@ -83,7 +83,7 @@
       ]
     },
     "compatibility": {
-      "dsh": "^0.1.1-rc.1 || ^0.1.2-alpha.1",
+      "dsh": "^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
       "profiles": [
         "web",
         "headless"
@@ -92,14 +92,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-renderer": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.8 || ^0.1.1-rc.1 || ^0.1.2-alpha.1 || ^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.1",
     "react": "^18.2.0"
   },

package/scripts/profile-e2e.mjs

@@ -10,6 +10,17 @@ const packageVersion = JSON.parse(await readFile(join(root, 'package.json'), 'ut
 const dsh = process.env.DSH_BIN ?? 'dsh'
 const keepTemp = process.argv.includes('--keep-temp')
 const timeoutMs = Number(process.env.DSH_TOOL_SEARCH_E2E_TIMEOUT_MS ?? 180_000)
+const maxModelRequests = Number(process.env.DSH_TOOL_SEARCH_E2E_MAX_REQUESTS ?? 12)
+
+/**
+ * PTC presentation is selected by name: DSH renders it as `code` up to 0.1.1
+ * and as `ptc` from 0.1.2. Override with DSH_TOOL_SEARCH_PRESENTATION_MODE.
+ */
+function presentationModeFor(version) {
+  const override = process.env.DSH_TOOL_SEARCH_PRESENTATION_MODE
+  if (override !== undefined && override !== '') return override
+  return version.startsWith('0.1.0') || version.startsWith('0.1.1') ? 'code' : 'ptc'
+}
 
 function run(command, args, options = {}) {
   return new Promise((resolve, reject) => {
@@ -129,7 +140,19 @@ async function startLlm(script = [
         return
       }
       requests.push(body)
-      const step = script[index++]
+      const names = requestToolNames(body)
+      const last = body?.messages?.at(-1)
+      process.stderr.write(
+        `[e2e] model request #${requests.length} tools=[${names.join(',')}] `
+        + `last=${JSON.stringify(last?.role ?? 'none')}:${JSON.stringify(String(last?.content ?? '').slice(0, 80))}\n`,
+      )
+      if (requests.length > maxModelRequests) {
+        // A runaway loop must fail here instead of growing the recorded bodies.
+        response.writeHead(500, { 'content-type': 'application/json' })
+        response.end(JSON.stringify({ error: { message: `request-limit-${maxModelRequests}` } }))
+        return
+      }
+      const step = typeof script === 'function' ? script(body) : script[index++]
       if (step === undefined) {
         response.writeHead(500, { 'content-type': 'application/json' })
         response.end('{"error":{"message":"script-exhausted"}}')
@@ -191,6 +214,19 @@ function requestToolNames(body) {
   return body?.tools?.map(tool => tool?.function?.name).filter(name => typeof name === 'string') ?? []
 }
 
+function messageText(body) {
+  return body?.messages
+    ?.filter(message => message?.role === 'system' || message?.role === 'developer')
+    .map(message => typeof message.content === 'string' ? message.content : JSON.stringify(message.content ?? ''))
+    .join('\n') ?? ''
+}
+
+function conversationText(body) {
+  return body?.messages
+    ?.map(message => typeof message.content === 'string' ? message.content : JSON.stringify(message.content ?? ''))
+    .join('\n') ?? ''
+}
+
 function toolResultTexts(body) {
   return body?.messages
     ?.filter(message => message?.role === 'tool')
@@ -361,6 +397,112 @@ try {
   const returnFileResult = toolResultTexts(llm.requests[2]).at(-1) ?? ''
   assert(returnFileResult.includes('"sent":true'), 'dsh_im_return_file did not execute through the real Agent loop')
 
+  const presentationChooser = step => {
+    // Under PTC the model only reaches tools through run_code, so the scripted
+    // calls are programs that search first and dispatch the selection after.
+    const names = requestToolNames(step)
+    if (!names.includes('run_code')) return { kind: 'text', text: 'auxiliary call' }
+    const transcript = conversationText(step)
+    // Match compact and pretty-printed results alike; a literal match loops.
+    if (/"sent"\s*:\s*true/u.test(transcript)) return { kind: 'text', text: 'presentation e2e done' }
+    if (transcript.includes('dsh_im_return_file') && transcript.includes('tool_search')) {
+      return {
+        kind: 'tool',
+        name: 'run_code',
+        arguments: JSON.stringify({
+          code: "const sent = await tools.dsh_im_return_file({ path: '/tmp/tool-search-e2e.txt' })\nreturn sent",
+          description: 'Return the file through the selected tool',
+        }),
+      }
+    }
+    return {
+      kind: 'tool',
+      name: 'run_code',
+      arguments: JSON.stringify({
+        code: "const selected = await tools.tool_search({ query: 'dsh_im_return_file', limit: 1 })\nreturn selected",
+        description: 'Search deferred tools',
+      }),
+    }
+  }
+
+  /** Run the presentation pass in one mode, asserting the loader-level guarantees. */
+  const runPresentationPass = async mode => {
+    const presentationLlm = await startLlm(presentationChooser)
+    try {
+      const presentationResult = await runDsh([
+        '--profile', 'headless',
+        '--patch', patch,
+        'Find and call the tool that returns a file through the conversation.',
+      ], {
+        cwd: workspaceDirectory,
+        env: {
+          DSH_HOME: home,
+          DSH_TOOLS_MODE: mode,
+          DSH_TELEMETRY_DISABLED: '1',
+          DSH_PERMISSION_MODE: 'danger-full-access',
+          DEEPSEEK_API_KEY: 'tool-search-e2e-key',
+          DEEPSEEK_BASE_URL: presentationLlm.baseUrl,
+        },
+      })
+      assert(
+        presentationResult.stdout.trim() === 'presentation e2e done',
+        `unexpected ${mode}-mode Agent output: ${presentationResult.stdout}`,
+      )
+      const agentRequests = presentationLlm.requests.filter(body => requestToolNames(body).includes('run_code'))
+      assert(agentRequests.length === 3, `expected 3 ${mode}-mode model calls, received ${agentRequests.length}`)
+      const first = agentRequests[0]
+      assert(
+        requestToolNames(first).join(',') === 'run_code',
+        `${mode} assembly exposes more than the reserved transport: ${requestToolNames(first).join(',')}`,
+      )
+      const firstText = messageText(first)
+      assert(firstText.includes('tool_search'), `${mode} SDK omits the searchable tool_search`)
+      assert(firstText.includes('bash'), `${mode} SDK omits the always-visible bash`)
+      assert(!firstText.includes('fixture_echo'), `${mode} SDK advertises deferred fixture_echo`)
+      assert(!firstText.includes('dsh_im_return_file'), `${mode} SDK advertises deferred dsh_im_return_file`)
+      const afterSelection = agentRequests[1]
+      const afterText = messageText(afterSelection)
+      assert(afterText.includes('dsh_im_return_file'), `${mode} SDK omits the tool selected by tool_search`)
+      assert(!afterText.includes('fixture_echo'), `${mode} SDK advertises unrelated fixture_echo after search`)
+      assert(
+        presentationLlm.requests.some(body => /"sent"\s*:\s*true/u.test(conversationText(body))),
+        `the selected tool did not dispatch through run_code under ${mode}`,
+      )
+      return {
+        mode,
+        modelCalls: agentRequests.length,
+        transportOnly: true,
+        sdkHasToolSearch: true,
+        sdkHidesDeferredBeforeSearch: true,
+        sdkAddsSelectionAfterSearch: true,
+        selectedToolDispatched: true,
+      }
+    } finally {
+      await presentationLlm.close()
+    }
+  }
+
+  // The presentation name for the PTC collapse is `code` up to DSH 0.1.1 and
+  // `ptc` from 0.1.2. The guess is validated against the host, and a rejected
+  // name is retried once with the other spelling.
+  const presentationModes = [presentationModeFor(dshVersion)]
+  presentationModes.push(presentationModes[0] === 'ptc' ? 'code' : 'ptc')
+  let presentation
+  let modeRejection
+  for (const [index, mode] of presentationModes.entries()) {
+    try {
+      presentation = await runPresentationPass(mode)
+      break
+    } catch (error) {
+      const text = String(error)
+      // The loader reports `expected "native" | "ptc" | "both" but got "code"`.
+      const rejectedName = /expected[\s\S]{0,80}but got\s+"[a-z]+"/u.test(text)
+      if (!rejectedName || index === presentationModes.length - 1) throw error
+      modeRejection = text.split('\n').find(line => line.includes('but got'))?.trim()
+    }
+  }
+
+
   process.stdout.write(`${JSON.stringify({
     ok: true,
     dsh: dshVersion,
@@ -370,6 +512,9 @@ try {
     initialToolCount: initialNames.length,
     selectedToolCount: searchedNames.length,
     selectedOnNextCall: searchedNames.includes('dsh_im_return_file'),
+    presentation,
+    modeRejection,
+    dshScript,
     package: `@anionex/dsh-tool-search@${packageVersion}`,
     temporaryHome: keepTemp ? home : undefined,
   }, null, 2)}\n`)

package/src/runtime.ts

@@ -5,6 +5,9 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import {
   defineTool,
+  renderToolsSdk,
+  renderToolsSdkPy,
+  RUN_CODE_NAME,
   type ToolDefinition,
   type ToolExecution,
   type ToolExecutionResult,
@@ -16,6 +19,8 @@ import { ToolPolicyResolver, normalizeSettings } from './settings.ts'
 import {
   MAX_RESULT_LIMIT,
   TOOL_SEARCH_NAME,
+  TOOL_SDK_LANGUAGE_MARKERS,
+  TOOL_SDK_SECTION_NAME,
   type CatalogSnapshot,
   type ToolSearchSettings,
 } from './shared.ts'
@@ -24,6 +29,16 @@ const RESULT_SCHEMA_VERSION = 1
 const MAX_QUERY_LENGTH = 4096
 const MAX_DESCRIPTION_LENGTH = 240
 
+/** One entry of the generated PTC SDK contract, as `renderToolsSdk` expects it. */
+type SdkSchema = Parameters<typeof renderToolsSdk>[0][number]
+
+/** The subset of a registered tool definition the SDK projection consumes. */
+interface ToolDefinitionLike {
+  description?: string
+  parameters?: unknown
+  output?: { schema?: unknown }
+}
+
 export interface ToolSearchMatch {
   name: string
   description: string
@@ -296,31 +311,123 @@ export class ToolSearchRuntime {
     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
+  /**
+   * The searchable registry view for one Agent: every tool it could reach,
+   * whether or not the current presentation shows it.
+   *
+   * The reserved PTC transport is excluded: it is never searchable, never
+   * constrained by policy, and never part of the generated SDK it carries.
+   * Reading the registry (rather than the assembled schemas) is what keeps the
+   * corpus complete under PTC presentation, where the assembly itself carries
+   * only `run_code`.
+   */
+  private refreshCatalog(state: AgentState): ToolCatalogEntry[] {
+    if (state.catalogGeneration !== this.generation) {
+      state.catalog = buildCatalog(
+        (this.ctx.tools.schemas(state.agent) as ToolSchemaLike[])
+          .filter(tool => tool.name !== RUN_CODE_NAME),
+      )
+      state.catalogGeneration = this.generation
+    }
+    return state.catalog
   }
 
+  /**
+   * Hide every deferred tool from one final assembly.
+   *
+   * Two surfaces carry tools and both must agree: the native schema list plus
+   * its `tool:<name>` guidance sections, and — under `ptc`/`both` — the
+   * generated `tools:sdk` section. The SDK text is regenerated with the same
+   * renderer `dsh-tools` uses, from the surviving tools alone, so the filtered
+   * assembly is byte-identical to the one the registry would have built for
+   * that smaller tool set.
+   */
   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 catalog = this.refreshCatalog(state)
+    const known = new Set(catalog.map(tool => tool.name))
     const visible = new Set(
-      assembly.tools
+      catalog
         .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 hidden = new Set(catalog.map(tool => tool.name).filter(name => !visible.has(name)))
+    const tools = assembly.tools.filter(tool => !known.has(tool.name) || visible.has(tool.name))
+    let sdkRewritten = false
+    const sections = assembly.sections
+      .filter(section => {
         const name = toolSectionName(section.name)
         return name === undefined || !hidden.has(name)
-      }),
+      })
+      .map(section => {
+        // An empty SDK section is an Agent-scoped opt-out of PTC presentation
+        // (a native override under a PTC deployment): there is nothing to filter.
+        if (section.name !== TOOL_SDK_SECTION_NAME || hidden.size === 0 || section.text.trim().length === 0) {
+          return section
+        }
+        const text = this.renderSdk(state, visible, section.text)
+        if (text === section.text) return section
+        sdkRewritten = true
+        return { ...section, text }
+      })
+    if (tools.length === assembly.tools.length && sections.length === assembly.sections.length && !sdkRewritten) {
+      return assembly
+    }
+    return { ...assembly, tools, sections }
+  }
+
+  /**
+   * Rebuild the PTC SDK section for the surviving tools.
+   *
+   * The flavor must be the one the session already programs against, so it
+   * comes from the mounted code runtime; a host that cannot answer for it
+   * falls back to the marker the existing section was rendered with.
+   */
+  private renderSdk(state: AgentState, visible: ReadonlySet<string>, original: string): string {
+    const render = this.resolveSdkRenderer(original)
+    const schemas: SdkSchema[] = []
+    for (const tool of state.catalog) {
+      if (!visible.has(tool.name)) continue
+      const definition = this.toolDefinition(tool.name, state.agent)
+      schemas.push({
+        name: tool.name,
+        description: definition?.description ?? tool.description,
+        parameters: cloneJson(definition?.parameters ?? tool.parameters) as SdkSchema['parameters'],
+        output: cloneJson(definition?.output?.schema ?? {}) as SdkSchema['output'],
+      })
     }
+    return render(schemas)
+  }
+
+  private resolveSdkRenderer(original: string): (schemas: SdkSchema[]) => string {
+    const runtime = this.codeRuntime()
+    if (runtime.language === 'typescript') return renderToolsSdk
+    if (runtime.language === 'python') return renderToolsSdkPy
+    if (original.includes(TOOL_SDK_LANGUAGE_MARKERS.python)) return renderToolsSdkPy
+    if (original.includes(TOOL_SDK_LANGUAGE_MARKERS.typescript)) return renderToolsSdk
+    throw new Error(
+      `${TOOL_SEARCH_NAME}: cannot filter the generated tool SDK for code runtime language `
+      + `${JSON.stringify(runtime.language ?? 'unknown')}`,
+    )
+  }
+
+  private codeRuntime(): { language?: unknown } {
+    const runtime = (this.ctx as unknown as { get?: (name: string) => unknown }).get?.('codeRuntime')
+    return typeof runtime === 'object' && runtime !== null ? runtime as { language?: unknown } : {}
+  }
+
+  private toolDefinition(name: string, agent: Agent): ToolDefinitionLike | undefined {
+    const registry = this.ctx.tools as unknown as { get?: (name: string, scope?: unknown) => unknown }
+    if (typeof registry.get !== 'function') return undefined
+    const definition = registry.get(name, agent)
+    return typeof definition === 'object' && definition !== null ? definition as ToolDefinitionLike : undefined
+  }
+}
+
+/** Lossless clone of a schema node; a value that cannot be cloned is used as-is. */
+function cloneJson<T>(value: T): T {
+  try {
+    return structuredClone(value)
+  } catch {
+    return value
   }
 }

package/src/shared.ts

@@ -6,6 +6,20 @@ export const TOOL_SEARCH_CATALOG_ROUTE = '/_dsh/tool-search/catalog'
 export const DEFAULT_RESULT_LIMIT = 5
 export const MAX_RESULT_LIMIT = 20
 
+/** Prompt section carrying the generated PTC tool SDK (`ptc` and `both` modes). */
+export const TOOL_SDK_SECTION_NAME = 'tools:sdk'
+
+/**
+ * Markers identifying which renderer produced an SDK section we did not
+ * assemble ourselves. Used only when the code runtime cannot be read from the
+ * context, because the renderer must match the flavor the model was told to
+ * program against.
+ */
+export const TOOL_SDK_LANGUAGE_MARKERS = Object.freeze({
+  typescript: 'interface ToolArgsMap',
+  python: 'class Tools(Protocol)',
+} as const)
+
 /**
  * Stable bootstrap surface for current DSH releases. Unknown future first-party
  * names are deferred until this list or the user allowlist is updated because