V48 (impl-only): Codebase Try multi-tool registry

Host read/list/run tools + full LSP; useTools schema and Try prompts
for multi-call Discovery comprehension before 1.D23.

Author: geraldarthurdavis

packages/asset-packs-pipelines/syntheses/deposit/src/__tests__/deposit-agent-prompt-contracts.test.ts

@@ -123,8 +123,8 @@ const SPECS: DepositAgentPromptSpec[] = [
     agent: DepositCodebaseComprehensionAgent,
     identity:
       'You are the SynthesizeAssetPacks Discovery agent that comprehends the depositor Host checkout (sourceCheckoutCatalog).',
-    requirements: 'You receive: repository coordinates, sourceCheckoutCatalog paths, fileTree structure,',
-    wrapper: 'Return ONLY {"comprehension": {...}}',
+    requirements: 'Inputs may include: repository coordinates, sourceCheckoutCatalog paths, fileTree,',
+    wrapper: 'comprehension + optional useTools on Try/Retry',
     schemaFields: [
       'summary',
       'capabilities',
@@ -134,10 +134,10 @@ const SPECS: DepositAgentPromptSpec[] = [
       'structureInsights',
     ],
     ptrr: [
-      'Plan: combine absolute measurements, LSP signals, file-tree structure, and key file',
-      'Try: synthesize the codebase knowledge map — capabilities, knowledge areas, notable',
-      'Refine: ensure the map is source-safe, grounded in provided sourceCheckoutCatalog evidence',
-      'Retry: return a minimal source-safe knowledge map grounded in path list and measurements',
+      'Plan (no tools): design a multi-tool Host checkout exploration strategy',
+      'Try: EXECUTE rich multi-tool exploration then synthesize the knowledge map.',
+      'Refine (no tools): ensure the map is source-safe, grounded in tool results',
+      'Retry: if prior Try missed tools or evidence, select additional useTools',
     ],
     boundaryOutput: {
       comprehension: {

packages/asset-packs-pipelines/syntheses/deposit/src/agents/discovery/deposit-codebase-comprehension-agent.ts

@@ -49,6 +49,7 @@
     "./tools/DepositDepositoryAssetPackSearchTool": "./src/tools/DepositDepositoryAssetPackSearchTool.ts",
     "./tools/AssetPackCloneVCSRepositoryTool": "./src/tools/AssetPackCloneVCSRepositoryTool.ts",
     "./tools/lsp-setup-tools": "./src/tools/lsp-setup-tools.ts",
+    "./tools/discovery-host-workspace-tools": "./src/tools/discovery-host-workspace-tools.ts",
     "./types/PipelineSchemas": "./src/types/PipelineSchemas.ts",
     "./types/AssetPackWrittenAssetType": "./src/types/AssetPackWrittenAssetType.ts",
     "./agents/finish/upload-asset-packs-for-review-agent": "./src/agents/finish/upload-asset-packs-for-review-agent.ts",

packages/asset-packs-pipelines/syntheses/domain/package.json

@@ -0,0 +1,87 @@
+/**
+ * Host workspace tools for Discovery codebase Try multi-tool exploration.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {
+  HOST_WORKSPACE_TOOL_NAMES,
+  runHostWorkspaceListDir,
+  runHostWorkspaceReadFile,
+  runHostWorkspaceRunCommand,
+} from '../tools/discovery-host-workspace-tools';
+
+describe('discovery host workspace tools', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'bitcode-host-ws-'));
+
+  beforeAll(() => {
+    fs.writeFileSync(path.join(root, 'hello.js'), 'export const x = 1;\n', 'utf8');
+    fs.mkdirSync(path.join(root, 'src'));
+    fs.writeFileSync(path.join(root, 'src', 'a.ts'), 'export type A = number;\n', 'utf8');
+  });
+
+  afterAll(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('exports stable registry names', () => {
+    expect(HOST_WORKSPACE_TOOL_NAMES.readFile).toBe('host-workspace-read-file');
+    expect(HOST_WORKSPACE_TOOL_NAMES.listDir).toBe('host-workspace-list-dir');
+    expect(HOST_WORKSPACE_TOOL_NAMES.runCommand).toBe('host-workspace-run-command');
+  });
+
+  it('reads files under workspaceRoot and refuses escape', async () => {
+    const ok = await runHostWorkspaceReadFile({
+      workspaceRoot: root,
+      path: 'hello.js',
+    });
+    expect(ok.ok).toBe(true);
+    expect(ok.content).toContain('export const x');
+
+    const escape = await runHostWorkspaceReadFile({
+      workspaceRoot: root,
+      path: '../outside',
+    });
+    expect(escape.ok).toBe(false);
+  });
+
+  it('lists directories', async () => {
+    const listed = await runHostWorkspaceListDir({
+      workspaceRoot: root,
+      path: '.',
+    });
+    expect(listed.ok).toBe(true);
+    expect(listed.entries?.some((e) => e.name === 'src')).toBe(true);
+  });
+
+  it('runs allowlisted commands and rejects shell meta / forbidden git', async () => {
+    const ls = await runHostWorkspaceRunCommand({
+      workspaceRoot: root,
+      command: 'ls',
+      args: ['-1'],
+    });
+    expect(ls.ok).toBe(true);
+    expect(ls.stdout).toMatch(/hello\.js|src/);
+
+    const bad = await runHostWorkspaceRunCommand({
+      workspaceRoot: root,
+      command: 'rm',
+      args: ['-rf', '/'],
+    });
+    expect(bad.ok).toBe(false);
+
+    const meta = await runHostWorkspaceRunCommand({
+      workspaceRoot: root,
+      command: 'ls',
+      args: ['; echo pwned'],
+    });
+    expect(meta.ok).toBe(false);
+
+    const gitPush = await runHostWorkspaceRunCommand({
+      workspaceRoot: root,
+      command: 'git',
+      args: ['push', 'origin', 'main'],
+    });
+    expect(gitPush.ok).toBe(false);
+  });
+});

packages/asset-packs-pipelines/syntheses/domain/src/__tests__/discovery-host-workspace-tools.test.ts

@@ -3,7 +3,6 @@
  */
 import {
   ALL_LSP_QUERY_TOOLS,
-  DISCOVERY_CODEBASE_COMPREHENSION_LSP_TOOLS,
   SETUP_LSP_INITIALIZE_TOOLS,
   LSP_TOOL_NAMES,
   setupLspForWorkspace,
@@ -40,12 +39,22 @@ describe('Setup LSP tools for subsequent phases', () => {
     expect(initTools.length).toBeGreaterThan(0);
   });
 
-  it('binds Discovery codebase comprehension to the full LSP suite', () => {
+  it('binds Discovery codebase comprehension to LSP suite + host workspace tools', () => {
     const discovery = getAssetPackPipelineToolsForAgent('DepositCodebaseComprehensionAgent');
-    expect(discovery.map((t) => (t as any).name)).toEqual(
-      DISCOVERY_CODEBASE_COMPREHENSION_LSP_TOOLS.map((t) => (t as any).name),
+    const names = discovery.map((t) => (t as any).name);
+    expect(names).toEqual(
+      expect.arrayContaining([
+        LSP_TOOL_NAMES.workspaceSymbols,
+        LSP_TOOL_NAMES.documentSymbols,
+        LSP_TOOL_NAMES.definition,
+        LSP_TOOL_NAMES.references,
+        'host-workspace-read-file',
+        'host-workspace-list-dir',
+        'host-workspace-run-command',
+      ]),
     );
-    expect(discovery.length).toBeGreaterThanOrEqual(5);
+    // Full LSP suite + 3 host tools
+    expect(discovery.length).toBeGreaterThanOrEqual(ALL_LSP_QUERY_TOOLS.length + 3);
   });
 
   it('setupLspForWorkspace registers tools and marks readiness for later phases', async () => {