Skip to content

Commit 71e4b08

Browse files
SandyTao520liamhelmer
SandyTao520
authored and
liamhelmer
committed
refactor(core): Extract tool parameter names as constants (google-gemini#20460)
1 parent 567a99c commit 71e4b08

File tree

7 files changed

+565
-178
lines changed

7 files changed

+565
-178
lines changed

‎packages/core/src/prompts/snippets.ts‎

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,16 @@ import {
1717
SHELL_TOOL_NAME,
1818
WRITE_FILE_TOOL_NAME,
1919
WRITE_TODOS_TOOL_NAME,
20+
GREP_PARAM_TOTAL_MAX_MATCHES,
21+
GREP_PARAM_INCLUDE_PATTERN,
22+
GREP_PARAM_EXCLUDE_PATTERN,
23+
GREP_PARAM_CONTEXT,
24+
GREP_PARAM_BEFORE,
25+
GREP_PARAM_AFTER,
26+
READ_FILE_PARAM_START_LINE,
27+
READ_FILE_PARAM_END_LINE,
28+
SHELL_PARAM_IS_BACKGROUND,
29+
EDIT_PARAM_OLD_STRING,
2030
} from '../tools/tool-names.js';
2131
import type { HierarchicalMemory } from '../config/memory.js';
2232
import { DEFAULT_CONTEXT_FILENAME } from '../tools/memoryTool.js';
@@ -183,16 +193,16 @@ Use the following guidelines to optimize your search and read patterns.
183193
- Prefer using tools like ${GREP_TOOL_NAME} to identify points of interest instead of reading lots of files individually.
184194
- If you need to read multiple ranges in a file, do so parallel, in as few turns as possible.
185195
- It is more important to reduce extra turns, but please also try to minimize unnecessarily large file reads and search results, when doing so doesn't result in extra turns. Do this by always providing conservative limits and scopes to tools like ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME}.
186-
- ${READ_FILE_TOOL_NAME} fails if old_string is ambiguous, causing extra turns. Take care to read enough with ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME} to make the edit unambiguous.
196+
- ${READ_FILE_TOOL_NAME} fails if ${EDIT_PARAM_OLD_STRING} is ambiguous, causing extra turns. Take care to read enough with ${READ_FILE_TOOL_NAME} and ${GREP_TOOL_NAME} to make the edit unambiguous.
187197
- You can compensate for the risk of missing results with scoped or limited searches by doing multiple searches in parallel.
188198
- Your primary goal is still to do your best quality work. Efficiency is an important, but secondary concern.
189199
</guidelines>
190200
191201
<examples>
192-
- **Searching:** utilize search tools like ${GREP_TOOL_NAME} and ${GLOB_TOOL_NAME} with a conservative result count (\`total_max_matches\`) and a narrow scope (\`include_pattern\` and \`exclude_pattern\` parameters).
193-
- **Searching and editing:** utilize search tools like ${GREP_TOOL_NAME} with a conservative result count and a narrow scope. Use \`context\`, \`before\`, and/or \`after\` to request enough context to avoid the need to read the file before editing matches.
202+
- **Searching:** utilize search tools like ${GREP_TOOL_NAME} and ${GLOB_TOOL_NAME} with a conservative result count (\`${GREP_PARAM_TOTAL_MAX_MATCHES}\`) and a narrow scope (\`${GREP_PARAM_INCLUDE_PATTERN}\` and \`${GREP_PARAM_EXCLUDE_PATTERN}\` parameters).
203+
- **Searching and editing:** utilize search tools like ${GREP_TOOL_NAME} with a conservative result count and a narrow scope. Use \`${GREP_PARAM_CONTEXT}\`, \`${GREP_PARAM_BEFORE}\`, and/or \`${GREP_PARAM_AFTER}\` to request enough context to avoid the need to read the file before editing matches.
194204
- **Understanding:** minimize turns needed to understand a file. It's most efficient to read small files in their entirety.
195-
- **Large files:** utilize search tools like ${GREP_TOOL_NAME} and/or ${READ_FILE_TOOL_NAME} called in parallel with 'start_line' and 'end_line' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
205+
- **Large files:** utilize search tools like ${GREP_TOOL_NAME} and/or ${READ_FILE_TOOL_NAME} called in parallel with '${READ_FILE_PARAM_START_LINE}' and '${READ_FILE_PARAM_END_LINE}' to reduce the impact on context. Minimize extra turns, unless unavoidable due to the file being too large.
196206
- **Navigating:** read the minimum required to not require additional turns spent reading the file.
197207
</examples>
198208
@@ -659,11 +669,11 @@ function toolUsageInteractive(
659669
? ' If you choose to execute an interactive command consider letting the user know they can press `ctrl + f` to focus into the shell to provide input.'
660670
: '';
661671
return `
662-
- **Background Processes:** To run a command in the background, set the \`is_background\` parameter to true. If unsure, ask the user.
672+
- **Background Processes:** To run a command in the background, set the \`${SHELL_PARAM_IS_BACKGROUND}\` parameter to true. If unsure, ask the user.
663673
- **Interactive Commands:** Always prefer non-interactive commands (e.g., using 'run once' or 'CI' flags for test runners to avoid persistent watch modes or 'git --no-pager') unless a persistent process is specifically required; however, some commands are only interactive and expect user input during their execution (e.g. ssh, vim).${ctrlF}`;
664674
}
665675
return `
666-
- **Background Processes:** To run a command in the background, set the \`is_background\` parameter to true.
676+
- **Background Processes:** To run a command in the background, set the \`${SHELL_PARAM_IS_BACKGROUND}\` parameter to true.
667677
- **Interactive Commands:** Always prefer non-interactive commands (e.g., using 'run once' or 'CI' flags for test runners to avoid persistent watch modes or 'git --no-pager') unless a persistent process is specifically required; however, some commands are only interactive and expect user input during their execution (e.g. ssh, vim).`;
668678
}
669679

‎packages/core/src/tools/definitions/base-declarations.ts‎

Lines changed: 91 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,25 +10,115 @@
1010
*/
1111

1212
// ============================================================================
13-
// TOOL NAMES
13+
// SHARED PARAMETER NAMES (used by multiple tools)
1414
// ============================================================================
1515

16+
export const PARAM_FILE_PATH = 'file_path';
17+
export const PARAM_DIR_PATH = 'dir_path';
18+
export const PARAM_PATTERN = 'pattern';
19+
export const PARAM_CASE_SENSITIVE = 'case_sensitive';
20+
export const PARAM_RESPECT_GIT_IGNORE = 'respect_git_ignore';
21+
export const PARAM_RESPECT_GEMINI_IGNORE = 'respect_gemini_ignore';
22+
export const PARAM_FILE_FILTERING_OPTIONS = 'file_filtering_options';
23+
export const PARAM_DESCRIPTION = 'description';
24+
25+
// ============================================================================
26+
// TOOL NAMES & TOOL-SPECIFIC PARAMETER NAMES
27+
// ============================================================================
28+
29+
// -- glob --
1630
export const GLOB_TOOL_NAME = 'glob';
31+
32+
// -- grep_search --
1733
export const GREP_TOOL_NAME = 'grep_search';
34+
export const GREP_PARAM_INCLUDE_PATTERN = 'include_pattern';
35+
export const GREP_PARAM_EXCLUDE_PATTERN = 'exclude_pattern';
36+
export const GREP_PARAM_NAMES_ONLY = 'names_only';
37+
export const GREP_PARAM_MAX_MATCHES_PER_FILE = 'max_matches_per_file';
38+
export const GREP_PARAM_TOTAL_MAX_MATCHES = 'total_max_matches';
39+
// ripgrep only
40+
export const GREP_PARAM_FIXED_STRINGS = 'fixed_strings';
41+
export const GREP_PARAM_CONTEXT = 'context';
42+
export const GREP_PARAM_AFTER = 'after';
43+
export const GREP_PARAM_BEFORE = 'before';
44+
export const GREP_PARAM_NO_IGNORE = 'no_ignore';
45+
46+
// -- list_directory --
1847
export const LS_TOOL_NAME = 'list_directory';
48+
export const LS_PARAM_IGNORE = 'ignore';
49+
50+
// -- read_file --
1951
export const READ_FILE_TOOL_NAME = 'read_file';
52+
export const READ_FILE_PARAM_START_LINE = 'start_line';
53+
export const READ_FILE_PARAM_END_LINE = 'end_line';
54+
55+
// -- run_shell_command --
2056
export const SHELL_TOOL_NAME = 'run_shell_command';
57+
export const SHELL_PARAM_COMMAND = 'command';
58+
export const SHELL_PARAM_IS_BACKGROUND = 'is_background';
59+
60+
// -- write_file --
2161
export const WRITE_FILE_TOOL_NAME = 'write_file';
62+
export const WRITE_FILE_PARAM_CONTENT = 'content';
63+
64+
// -- replace (edit) --
2265
export const EDIT_TOOL_NAME = 'replace';
66+
export const EDIT_PARAM_INSTRUCTION = 'instruction';
67+
export const EDIT_PARAM_OLD_STRING = 'old_string';
68+
export const EDIT_PARAM_NEW_STRING = 'new_string';
69+
export const EDIT_PARAM_ALLOW_MULTIPLE = 'allow_multiple';
70+
71+
// -- google_web_search --
2372
export const WEB_SEARCH_TOOL_NAME = 'google_web_search';
73+
export const WEB_SEARCH_PARAM_QUERY = 'query';
2474

75+
// -- write_todos --
2576
export const WRITE_TODOS_TOOL_NAME = 'write_todos';
77+
export const TODOS_PARAM_TODOS = 'todos';
78+
export const TODOS_ITEM_PARAM_DESCRIPTION = 'description';
79+
export const TODOS_ITEM_PARAM_STATUS = 'status';
80+
81+
// -- web_fetch --
2682
export const WEB_FETCH_TOOL_NAME = 'web_fetch';
83+
export const WEB_FETCH_PARAM_PROMPT = 'prompt';
84+
85+
// -- read_many_files --
2786
export const READ_MANY_FILES_TOOL_NAME = 'read_many_files';
87+
export const READ_MANY_PARAM_INCLUDE = 'include';
88+
export const READ_MANY_PARAM_EXCLUDE = 'exclude';
89+
export const READ_MANY_PARAM_RECURSIVE = 'recursive';
90+
export const READ_MANY_PARAM_USE_DEFAULT_EXCLUDES = 'useDefaultExcludes';
2891

92+
// -- save_memory --
2993
export const MEMORY_TOOL_NAME = 'save_memory';
94+
export const MEMORY_PARAM_FACT = 'fact';
95+
96+
// -- get_internal_docs --
3097
export const GET_INTERNAL_DOCS_TOOL_NAME = 'get_internal_docs';
98+
export const DOCS_PARAM_PATH = 'path';
99+
100+
// -- activate_skill --
31101
export const ACTIVATE_SKILL_TOOL_NAME = 'activate_skill';
102+
export const SKILL_PARAM_NAME = 'name';
103+
104+
// -- ask_user --
32105
export const ASK_USER_TOOL_NAME = 'ask_user';
106+
export const ASK_USER_PARAM_QUESTIONS = 'questions';
107+
// ask_user question item params
108+
export const ASK_USER_QUESTION_PARAM_QUESTION = 'question';
109+
export const ASK_USER_QUESTION_PARAM_HEADER = 'header';
110+
export const ASK_USER_QUESTION_PARAM_TYPE = 'type';
111+
export const ASK_USER_QUESTION_PARAM_OPTIONS = 'options';
112+
export const ASK_USER_QUESTION_PARAM_MULTI_SELECT = 'multiSelect';
113+
export const ASK_USER_QUESTION_PARAM_PLACEHOLDER = 'placeholder';
114+
// ask_user option item params
115+
export const ASK_USER_OPTION_PARAM_LABEL = 'label';
116+
export const ASK_USER_OPTION_PARAM_DESCRIPTION = 'description';
117+
118+
// -- exit_plan_mode --
33119
export const EXIT_PLAN_MODE_TOOL_NAME = 'exit_plan_mode';
120+
export const EXIT_PLAN_PARAM_PLAN_PATH = 'plan_path';
121+
122+
// -- enter_plan_mode --
34123
export const ENTER_PLAN_MODE_TOOL_NAME = 'enter_plan_mode';
124+
export const PLAN_MODE_PARAM_REASON = 'reason';

‎packages/core/src/tools/definitions/coreTools.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,59 @@ export {
3838
ASK_USER_TOOL_NAME,
3939
EXIT_PLAN_MODE_TOOL_NAME,
4040
ENTER_PLAN_MODE_TOOL_NAME,
41+
// Shared parameter names
42+
PARAM_FILE_PATH,
43+
PARAM_DIR_PATH,
44+
PARAM_PATTERN,
45+
PARAM_CASE_SENSITIVE,
46+
PARAM_RESPECT_GIT_IGNORE,
47+
PARAM_RESPECT_GEMINI_IGNORE,
48+
PARAM_FILE_FILTERING_OPTIONS,
49+
PARAM_DESCRIPTION,
50+
// Tool-specific parameter names
51+
READ_FILE_PARAM_START_LINE,
52+
READ_FILE_PARAM_END_LINE,
53+
WRITE_FILE_PARAM_CONTENT,
54+
GREP_PARAM_INCLUDE_PATTERN,
55+
GREP_PARAM_EXCLUDE_PATTERN,
56+
GREP_PARAM_NAMES_ONLY,
57+
GREP_PARAM_MAX_MATCHES_PER_FILE,
58+
GREP_PARAM_TOTAL_MAX_MATCHES,
59+
GREP_PARAM_FIXED_STRINGS,
60+
GREP_PARAM_CONTEXT,
61+
GREP_PARAM_AFTER,
62+
GREP_PARAM_BEFORE,
63+
GREP_PARAM_NO_IGNORE,
64+
EDIT_PARAM_INSTRUCTION,
65+
EDIT_PARAM_OLD_STRING,
66+
EDIT_PARAM_NEW_STRING,
67+
EDIT_PARAM_ALLOW_MULTIPLE,
68+
LS_PARAM_IGNORE,
69+
SHELL_PARAM_COMMAND,
70+
SHELL_PARAM_IS_BACKGROUND,
71+
WEB_SEARCH_PARAM_QUERY,
72+
WEB_FETCH_PARAM_PROMPT,
73+
READ_MANY_PARAM_INCLUDE,
74+
READ_MANY_PARAM_EXCLUDE,
75+
READ_MANY_PARAM_RECURSIVE,
76+
READ_MANY_PARAM_USE_DEFAULT_EXCLUDES,
77+
MEMORY_PARAM_FACT,
78+
TODOS_PARAM_TODOS,
79+
TODOS_ITEM_PARAM_DESCRIPTION,
80+
TODOS_ITEM_PARAM_STATUS,
81+
DOCS_PARAM_PATH,
82+
ASK_USER_PARAM_QUESTIONS,
83+
ASK_USER_QUESTION_PARAM_QUESTION,
84+
ASK_USER_QUESTION_PARAM_HEADER,
85+
ASK_USER_QUESTION_PARAM_TYPE,
86+
ASK_USER_QUESTION_PARAM_OPTIONS,
87+
ASK_USER_QUESTION_PARAM_MULTI_SELECT,
88+
ASK_USER_QUESTION_PARAM_PLACEHOLDER,
89+
ASK_USER_OPTION_PARAM_LABEL,
90+
ASK_USER_OPTION_PARAM_DESCRIPTION,
91+
PLAN_MODE_PARAM_REASON,
92+
EXIT_PLAN_PARAM_PLAN_PATH,
93+
SKILL_PARAM_NAME,
4194
} from './base-declarations.js';
4295

4396
// Re-export sets for compatibility

‎packages/core/src/tools/definitions/dynamic-declaration-helpers.ts‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ import {
1717
SHELL_TOOL_NAME,
1818
EXIT_PLAN_MODE_TOOL_NAME,
1919
ACTIVATE_SKILL_TOOL_NAME,
20+
SHELL_PARAM_COMMAND,
21+
PARAM_DESCRIPTION,
22+
PARAM_DIR_PATH,
23+
SHELL_PARAM_IS_BACKGROUND,
24+
EXIT_PLAN_PARAM_PLAN_PATH,
25+
SKILL_PARAM_NAME,
2026
} from './base-declarations.js';
2127

2228
/**
@@ -47,12 +53,12 @@ export function getShellToolDescription(
4753

4854
if (os.platform() === 'win32') {
4955
const backgroundInstructions = enableInteractiveShell
50-
? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use PowerShell background constructs.'
56+
? `To run a command in the background, set the \`${SHELL_PARAM_IS_BACKGROUND}\` parameter to true. Do NOT use PowerShell background constructs.`
5157
: 'Command can start background processes using PowerShell constructs such as `Start-Process -NoNewWindow` or `Start-Job`.';
5258
return `This tool executes a given shell command as \`powershell.exe -NoProfile -Command <command>\`. ${backgroundInstructions}${efficiencyGuidelines}${returnedInfo}`;
5359
} else {
5460
const backgroundInstructions = enableInteractiveShell
55-
? 'To run a command in the background, set the `is_background` parameter to true. Do NOT use `&` to background commands.'
61+
? `To run a command in the background, set the \`${SHELL_PARAM_IS_BACKGROUND}\` parameter to true. Do NOT use \`&\` to background commands.`
5662
: 'Command can start background processes using `&`.';
5763
return `This tool executes a given shell command as \`bash -c <command>\`. ${backgroundInstructions} Command is executed as a subprocess that leads its own process group. Command process group can be terminated as \`kill -- -PGID\` or signaled as \`kill -s SIGNAL -- -PGID\`.${efficiencyGuidelines}${returnedInfo}`;
5864
}
@@ -84,27 +90,27 @@ export function getShellDeclaration(
8490
parametersJsonSchema: {
8591
type: 'object',
8692
properties: {
87-
command: {
93+
[SHELL_PARAM_COMMAND]: {
8894
type: 'string',
8995
description: getCommandDescription(),
9096
},
91-
description: {
97+
[PARAM_DESCRIPTION]: {
9298
type: 'string',
9399
description:
94100
'Brief description of the command for the user. Be specific and concise. Ideally a single sentence. Can be up to 3 sentences for clarity. No line breaks.',
95101
},
96-
dir_path: {
102+
[PARAM_DIR_PATH]: {
97103
type: 'string',
98104
description:
99105
'(OPTIONAL) The path of the directory to run the command in. If not provided, the project root directory is used. Must be a directory within the workspace and must already exist.',
100106
},
101-
is_background: {
107+
[SHELL_PARAM_IS_BACKGROUND]: {
102108
type: 'boolean',
103109
description:
104110
'Set to true if this command should be run in the background (e.g. for long-running servers or watchers). The command will be started, allowed to run for a brief moment to check for immediate errors, and then moved to the background.',
105111
},
106112
},
107-
required: ['command'],
113+
required: [SHELL_PARAM_COMMAND],
108114
},
109115
};
110116
}
@@ -121,9 +127,9 @@ export function getExitPlanModeDeclaration(
121127
'Finalizes the planning phase and transitions to implementation by presenting the plan for user approval. This tool MUST be used to exit Plan Mode before any source code edits can be performed. Call this whenever a plan is ready or the user requests implementation.',
122128
parametersJsonSchema: {
123129
type: 'object',
124-
required: ['plan_path'],
130+
required: [EXIT_PLAN_PARAM_PLAN_PATH],
125131
properties: {
126-
plan_path: {
132+
[EXIT_PLAN_PARAM_PLAN_PATH]: {
127133
type: 'string',
128134
description: `The file path to the finalized plan (e.g., "${plansDir}/feature-x.md"). This path MUST be within the designated plans directory: ${plansDir}/`,
129135
},
@@ -146,11 +152,13 @@ export function getActivateSkillDeclaration(
146152
let schema: z.ZodTypeAny;
147153
if (skillNames.length === 0) {
148154
schema = z.object({
149-
name: z.string().describe('No skills are currently available.'),
155+
[SKILL_PARAM_NAME]: z
156+
.string()
157+
.describe('No skills are currently available.'),
150158
});
151159
} else {
152160
schema = z.object({
153-
name: z
161+
[SKILL_PARAM_NAME]: z
154162
// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
155163
.enum(skillNames as [string, ...string[]])
156164
.describe('The name of the skill to activate.'),

0 commit comments

Comments
 (0)