@anionex/dsh-tool-search 0.1.0 → 0.1.2

package/lib/types/runtime.d.ts

@@ -31,7 +31,38 @@ export declare class ToolSearchRuntime {
     private attach;
     private detach;
     private requireState;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    private resolveSdkRenderer;
+    private codeRuntime;
+    private toolDefinition;
 }
 //# sourceMappingURL=runtime.d.ts.map

package/lib/types/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,OAAO,EAEL,KAAK,cAAc,EAIpB,MAAM,wBAAwB,CAAA;AAI/B,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAA;AAMpB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAqFD,qBAAa,iBAAiB;IAQ1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,UAAU,CAAI;gBAGH,GAAG,EAAE,OAAO,EAC7B,QAAQ,EAAE,kBAAkB;IAO9B,OAAO,IAAI,MAAM,IAAI;IAgBrB,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAK/C,QAAQ,IAAI,eAAe;IAsB3B,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC;IAI9C,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,cAAc;CAqBvB"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/runtime.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAEnD,OAAO,EAKL,KAAK,cAAc,EAIpB,MAAM,wBAAwB,CAAA;AAI/B,OAAO,EAKL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAA;AAgBpB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,CAAC,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAqFD,qBAAa,iBAAiB;IAQ1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAA;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,UAAU,CAAI;gBAGH,GAAG,EAAE,OAAO,EAC7B,QAAQ,EAAE,kBAAkB;IAO9B,OAAO,IAAI,MAAM,IAAI;IAgBrB,cAAc,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI;IAK/C,QAAQ,IAAI,eAAe;IAsB3B,WAAW,CAAC,KAAK,EAAE,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC;IAI9C,OAAO,CAAC,gBAAgB;IAsDxB,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,MAAM;IAkBd,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,YAAY;IAOpB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAWtB;;;;;;;;;OASG;IACH,OAAO,CAAC,cAAc;IAiCtB;;;;;;OAMG;IACH,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,cAAc;CAMvB"}

package/lib/types/shared.d.ts

@@ -4,12 +4,24 @@ export declare const TOOL_SEARCH_SETTINGS_NAMESPACE = "tool-search";
 export declare const TOOL_SEARCH_CATALOG_ROUTE = "/_dsh/tool-search/catalog";
 export declare const DEFAULT_RESULT_LIMIT = 5;
 export declare const MAX_RESULT_LIMIT = 20;
+/** Prompt section carrying the generated PTC tool SDK (`ptc` and `both` modes). */
+export declare 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 declare const TOOL_SDK_LANGUAGE_MARKERS: Readonly<{
+    readonly typescript: "interface ToolArgsMap";
+    readonly python: "class Tools(Protocol)";
+}>;
 /**
  * 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 declare const DEFAULT_CORE_TOOLS: readonly ["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"];
+export declare const DEFAULT_CORE_TOOLS: readonly ["apply_patch", "ask_user_question", "bash", "create_goal", "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"];
 export interface ToolSearchSettings {
     defaultLimit: number;
     alwaysVisible: string[];

package/lib/types/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/shared.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAC7C,eAAO,MAAM,8BAA8B,gBAAgB,CAAA;AAC3D,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAElC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,oTAsBpB,CAAA;AAEX,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAIxD,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAE1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,UAAU,CAAA;IAClB,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC5B"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/shared.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAEjE,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAC7C,eAAO,MAAM,8BAA8B,gBAAgB,CAAA;AAC3D,eAAO,MAAM,yBAAyB,8BAA8B,CAAA;AACpE,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,gBAAgB,KAAK,CAAA;AAElC,mFAAmF;AACnF,eAAO,MAAM,qBAAqB,cAAc,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;;EAG3B,CAAA;AAEX;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,8RAqBpB,CAAA;AAEX,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAA;IACpB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,WAAW,EAAE,MAAM,EAAE,CAAA;CACtB;AAED,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAIxD,CAAA;AAEF,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAA;AAE1D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,UAAU,CAAA;IAClB,UAAU,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,kBAAkB,EAAE,CAAA;CAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionex/dsh-tool-search",
-  "version": "0.1.0",
+  "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

@@ -1,14 +1,26 @@
 import { spawn } from 'node:child_process'
-import { access, mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises'
+import { access, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from 'node:fs/promises'
 import { createServer } from 'node:http'
 import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const packageVersion = JSON.parse(await readFile(join(root, 'package.json'), 'utf8')).version
 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) => {
@@ -88,14 +100,24 @@ async function fixturePackage(directory) {
     '    },',
     '    execute: args => Promise.resolve({ echo: args.value }),',
     '  }))',
+    '  ctx.tools.register(defineTool({',
+    "    name: 'dsh_im_return_file',",
+    "    description: 'Send a readable file to the user through the conversation.',",
+    "    parameters: { path: { type: 'string', required: true, description: 'Readable file path.' } },",
+    '    output: {',
+    "      schema: { type: 'object', additionalProperties: false, properties: { sent: { type: 'boolean', required: true } } },",
+    "      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],",
+    '    },',
+    '    execute: () => Promise.resolve({ sent: true }),',
+    '  }))',
     '}',
     '',
   ].join('\n'))
 }
 
 async function startLlm(script = [
-  { kind: 'tool', name: 'tool_search', arguments: '{"query":"fixture_echo","limit":1}' },
-  { kind: 'tool', name: 'fixture_echo', arguments: '{"value":"real-agent-ok"}' },
+  { kind: 'tool', name: 'tool_search', arguments: '{"query":"dsh_im_return_file","limit":1}' },
+  { kind: 'tool', name: 'dsh_im_return_file', arguments: '{"path":"/tmp/tool-search-e2e.txt"}' },
   { kind: 'text', text: 'tool search e2e done' },
 ]) {
   const requests = []
@@ -118,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"}}')
@@ -180,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')
@@ -323,7 +370,7 @@ try {
   const runResult = await runDsh([
     '--profile', 'headless',
     '--patch', patch,
-    'Find and call the fixture echo tool.',
+    'Find and call the tool that returns a file through the conversation.',
   ], {
     cwd: workspaceDirectory,
     env: {
@@ -341,12 +388,120 @@ try {
   const searchedNames = requestToolNames(llm.requests[1])
   assert(initialNames.includes('tool_search'), 'initial model call omits tool_search')
   assert(!initialNames.includes('fixture_echo'), 'initial model call exposes deferred fixture_echo')
-  assert(searchedNames.includes('fixture_echo'), 'next model call omits selected fixture_echo')
+  assert(!initialNames.includes('dsh_im_return_file'), 'initial model call exposes plugin-provided dsh_im_return_file')
+  assert(!searchedNames.includes('fixture_echo'), 'searching dsh_im_return_file exposes unrelated fixture_echo')
+  assert(searchedNames.includes('dsh_im_return_file'), 'next model call omits selected dsh_im_return_file')
   const searchResult = toolResultTexts(llm.requests[1]).at(-1) ?? ''
-  assert(searchResult.includes('fixture_echo'), 'tool_search result omits fixture_echo summary')
+  assert(searchResult.includes('dsh_im_return_file'), 'tool_search result omits dsh_im_return_file summary')
   assert(!searchResult.includes('"parameters"'), 'tool_search result duplicates a full schema')
-  const echoResult = toolResultTexts(llm.requests[2]).at(-1) ?? ''
-  assert(echoResult.includes('real-agent-ok'), 'fixture_echo did not execute through the real Agent loop')
+  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,
@@ -356,8 +511,11 @@ try {
     modelCalls: llm.requests.length,
     initialToolCount: initialNames.length,
     selectedToolCount: searchedNames.length,
-    selectedOnNextCall: searchedNames.includes('fixture_echo'),
-    package: '@anionex/dsh-tool-search@0.1.0',
+    selectedOnNextCall: searchedNames.includes('dsh_im_return_file'),
+    presentation,
+    modeRejection,
+    dshScript,
+    package: `@anionex/dsh-tool-search@${packageVersion}`,
     temporaryHome: keepTemp ? home : undefined,
   }, null, 2)}\n`)
 } finally {

package/scripts/validate.mjs

@@ -24,7 +24,7 @@ async function exists(path) {
 
 const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
 check(pkg.name === '@anionex/dsh-tool-search', 'package name is incorrect')
-check(pkg.version === '0.1.0', 'release version is incorrect')
+check(pkg.version === '0.1.1', 'release version is incorrect')
 check(pkg.main === './lib/index.js', 'main entrypoint is incorrect')
 check(pkg.types === './lib/types/index.d.ts', 'types entrypoint is incorrect')
 check(pkg.exports?.['./client']?.default === './lib/client.js', 'client export is incorrect')

package/src/client/index.tsx

@@ -73,6 +73,7 @@ const en = {
   selected: 'Live agents',
   defaultPolicy: 'Default',
   alwaysPolicy: 'Always',
+  deferredPolicy: 'Deferred',
   blockedPolicy: 'Blocked',
   loading: 'Loading...',
   empty: 'No matching tools',
@@ -93,6 +94,7 @@ const zh: typeof en = {
   selected: '活跃 Agent',
   defaultPolicy: '默认',
   alwaysPolicy: '常驻',
+  deferredPolicy: '延迟',
   blockedPolicy: '禁用',
   loading: '加载中...',
   empty: '没有匹配工具',
@@ -296,7 +298,9 @@ export function ToolSearchSettingsSection({ scope, t }: SettingsProps): ReactNod
                   disabled={!snapshot.writable || tool.name === TOOL_SEARCH_NAME}
                   onChange={event => changePolicy(tool.name, event.target.value as ToolPolicy | 'default')}
                 >
-                  <option value="default">{core.has(tool.name) ? `${translate('defaultPolicy')} (${translate('alwaysPolicy')})` : translate('defaultPolicy')}</option>
+                  <option value="default">
+                    {`${translate('defaultPolicy')} (${translate(core.has(tool.name) ? 'alwaysPolicy' : 'deferredPolicy')})`}
+                  </option>
                   <option value="always">{translate('alwaysPolicy')}</option>
                   <option value="blocked">{translate('blockedPolicy')}</option>
                 </select>

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
@@ -16,7 +30,6 @@ export const DEFAULT_CORE_TOOLS = Object.freeze([
   'ask_user_question',
   'bash',
   'create_goal',
-  'dsh_im_return_file',
   'exit_plan_mode',
   'get_goal',
   'interrupt_agent',

package/tests/client.spec.tsx

@@ -23,12 +23,21 @@ describe('Tool Search settings section', () => {
         description: 'Capture a browser screenshot.',
         policy: 'deferred',
         selectedBy: [],
+      }, {
+        name: 'dsh_im_return_file',
+        description: 'Send a readable file to the user.',
+        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')
+    const imPolicy = screen.getByLabelText('Policy: dsh_im_return_file') as HTMLSelectElement
+    expect(imPolicy.value).toBe('default')
+    expect(imPolicy.options[0]?.text).toBe('Default (Deferred)')
+    expect(screen.getAllByLabelText('Live agents: 0').map(element => element.getAttribute('data-label')))
+      .toEqual(['Live agents', 'Live agents'])
     fireEvent.change(screen.getByLabelText('Policy: browser_take_screenshot'), { target: { value: 'always' } })
     await waitFor(() => {
       expect(set).toHaveBeenCalledWith('alwaysVisible', ['browser_take_screenshot'])