@mastra/code-sdk 1.0.3-alpha.0 → 1.1.0-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +49 -0
- package/dist/acp/agent.js +155 -167
- package/dist/acp/agent.js.map +1 -1
- package/dist/acp/event-mapper.js +193 -168
- package/dist/acp/event-mapper.js.map +1 -1
- package/dist/acp/index.js +60 -49
- package/dist/acp/index.js.map +1 -1
- package/dist/acp/server.js +31 -30
- package/dist/acp/server.js.map +1 -1
- package/dist/acp.js +1 -4
- package/dist/agents/credential-resolver.js +40 -29
- package/dist/agents/credential-resolver.js.map +1 -1
- package/dist/agents/custom-provider-source.js +16 -9
- package/dist/agents/custom-provider-source.js.map +1 -1
- package/dist/agents/instructions.js +27 -36
- package/dist/agents/instructions.js.map +1 -1
- package/dist/agents/mastracode-gateway.js +355 -428
- package/dist/agents/mastracode-gateway.js.map +1 -1
- package/dist/agents/memory.js +87 -78
- package/dist/agents/memory.js.map +1 -1
- package/dist/agents/model.js +114 -119
- package/dist/agents/model.js.map +1 -1
- package/dist/agents/modes/build.js +12 -13
- package/dist/agents/modes/build.js.map +1 -1
- package/dist/agents/modes/explore.js +14 -13
- package/dist/agents/modes/explore.js.map +1 -1
- package/dist/agents/modes/plan.js +14 -15
- package/dist/agents/modes/plan.js.map +1 -1
- package/dist/agents/prompts/agent-instructions.js +78 -69
- package/dist/agents/prompts/agent-instructions.js.map +1 -1
- package/dist/agents/prompts/build.js +19 -16
- package/dist/agents/prompts/build.js.map +1 -1
- package/dist/agents/prompts/fast.js +8 -4
- package/dist/agents/prompts/fast.js.map +1 -1
- package/dist/agents/prompts/index.js +48 -47
- package/dist/agents/prompts/index.js.map +1 -1
- package/dist/agents/prompts/model.js +6 -5
- package/dist/agents/prompts/model.js.map +1 -1
- package/dist/agents/prompts/plan.js +20 -16
- package/dist/agents/prompts/plan.js.map +1 -1
- package/dist/agents/prompts/tool-guidance.js +77 -109
- package/dist/agents/prompts/tool-guidance.js.map +1 -1
- package/dist/agents/sandbox-filesystem.js +245 -259
- package/dist/agents/sandbox-filesystem.js.map +1 -1
- package/dist/agents/sandbox-reattach.js +9 -11
- package/dist/agents/sandbox-reattach.js.map +1 -1
- package/dist/agents/thread-caveman-state.js +92 -81
- package/dist/agents/thread-caveman-state.js.map +1 -1
- package/dist/agents/tool-availability.js +62 -80
- package/dist/agents/tool-availability.js.map +1 -1
- package/dist/agents/tools.js +99 -139
- package/dist/agents/tools.js.map +1 -1
- package/dist/agents/workspace.js +232 -225
- package/dist/agents/workspace.js.map +1 -1
- package/dist/analytics.js +139 -128
- package/dist/analytics.js.map +1 -1
- package/dist/auth/authorization-input.js +39 -25
- package/dist/auth/authorization-input.js.map +1 -1
- package/dist/auth/device-code.js +112 -80
- package/dist/auth/device-code.js.map +1 -1
- package/dist/auth/index.js +2 -9
- package/dist/auth/pkce.js +27 -16
- package/dist/auth/pkce.js.map +1 -1
- package/dist/auth/providers/anthropic.js +107 -93
- package/dist/auth/providers/anthropic.js.map +1 -1
- package/dist/auth/providers/github-copilot.js +304 -293
- package/dist/auth/providers/github-copilot.js.map +1 -1
- package/dist/auth/providers/openai-codex.js +442 -460
- package/dist/auth/providers/openai-codex.js.map +1 -1
- package/dist/auth/providers/xai.js +179 -145
- package/dist/auth/providers/xai.js.map +1 -1
- package/dist/auth/storage.js +182 -175
- package/dist/auth/storage.js.map +1 -1
- package/dist/auth/types.js +1 -1
- package/dist/clipboard/index.js +206 -172
- package/dist/clipboard/index.js.map +1 -1
- package/dist/constants.js +11 -16
- package/dist/constants.js.map +1 -1
- package/dist/error-classification.js +19 -11
- package/dist/error-classification.js.map +1 -1
- package/dist/evals/context-builder.js +145 -104
- package/dist/evals/context-builder.js.map +1 -1
- package/dist/evals/index.js +4 -7
- package/dist/evals/scorers/classify-command.js +62 -41
- package/dist/evals/scorers/classify-command.js.map +1 -1
- package/dist/evals/scorers/efficiency.js +239 -181
- package/dist/evals/scorers/efficiency.js.map +1 -1
- package/dist/evals/scorers/extract-tools.js +51 -47
- package/dist/evals/scorers/extract-tools.js.map +1 -1
- package/dist/evals/scorers/index.js +1 -5
- package/dist/evals/scorers/outcome.js +321 -212
- package/dist/evals/scorers/outcome.js.map +1 -1
- package/dist/goal-manager.js +266 -261
- package/dist/goal-manager.js.map +1 -1
- package/dist/goal-signal.js +14 -13
- package/dist/goal-signal.js.map +1 -1
- package/dist/headless/cli.js +153 -154
- package/dist/headless/cli.js.map +1 -1
- package/dist/headless/flags.js +180 -178
- package/dist/headless/flags.js.map +1 -1
- package/dist/headless/format.js +72 -71
- package/dist/headless/format.js.map +1 -1
- package/dist/headless/index.js +5 -31
- package/dist/headless/policy.js +35 -31
- package/dist/headless/policy.js.map +1 -1
- package/dist/headless/run-mc.js +332 -334
- package/dist/headless/run-mc.js.map +1 -1
- package/dist/headless/types.js +16 -7
- package/dist/headless/types.js.map +1 -1
- package/dist/hooks/config.js +56 -61
- package/dist/hooks/config.js.map +1 -1
- package/dist/hooks/executor.js +118 -116
- package/dist/hooks/executor.js.map +1 -1
- package/dist/hooks/index.js +4 -15
- package/dist/hooks/manager.js +221 -280
- package/dist/hooks/manager.js.map +1 -1
- package/dist/hooks/types.js +5 -4
- package/dist/hooks/types.js.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +632 -712
- package/dist/index.js.map +1 -1
- package/dist/ipc/ipc-reporter.js +19 -22
- package/dist/ipc/ipc-reporter.js.map +1 -1
- package/dist/lsp/client.js +248 -306
- package/dist/lsp/client.js.map +1 -1
- package/dist/lsp/index.js +1 -6
- package/dist/lsp/language.js +39 -43
- package/dist/lsp/language.js.map +1 -1
- package/dist/lsp/manager.js +78 -93
- package/dist/lsp/manager.js.map +1 -1
- package/dist/lsp/server.js +151 -120
- package/dist/lsp/server.js.map +1 -1
- package/dist/lsp/workspace.js +50 -47
- package/dist/lsp/workspace.js.map +1 -1
- package/dist/mcp/config.js +210 -199
- package/dist/mcp/config.js.map +1 -1
- package/dist/mcp/index.js +2 -9
- package/dist/mcp/manager.js +482 -475
- package/dist/mcp/manager.js.map +1 -1
- package/dist/mcp/types.js +1 -1
- package/dist/onboarding/custom-packs.js +14 -17
- package/dist/onboarding/custom-packs.js.map +1 -1
- package/dist/onboarding/custom-providers.js +22 -20
- package/dist/onboarding/custom-providers.js.map +1 -1
- package/dist/onboarding/index.d.ts +1 -1
- package/dist/onboarding/index.d.ts.map +1 -1
- package/dist/onboarding/index.js +3 -21
- package/dist/onboarding/om-settings.d.ts +5 -0
- package/dist/onboarding/om-settings.d.ts.map +1 -1
- package/dist/onboarding/om-settings.js +41 -20
- package/dist/onboarding/om-settings.js.map +1 -1
- package/dist/onboarding/packs.d.ts +4 -6
- package/dist/onboarding/packs.d.ts.map +1 -1
- package/dist/onboarding/packs.js +154 -105
- package/dist/onboarding/packs.js.map +1 -1
- package/dist/onboarding/settings.js +575 -517
- package/dist/onboarding/settings.js.map +1 -1
- package/dist/permissions.js +112 -99
- package/dist/permissions.js.map +1 -1
- package/dist/plugin.js +21 -23
- package/dist/plugin.js.map +1 -1
- package/dist/plugins/dependencies.js +64 -87
- package/dist/plugins/dependencies.js.map +1 -1
- package/dist/plugins/install.js +159 -169
- package/dist/plugins/install.js.map +1 -1
- package/dist/plugins/loader.js +170 -185
- package/dist/plugins/loader.js.map +1 -1
- package/dist/plugins/manager.js +374 -380
- package/dist/plugins/manager.js.map +1 -1
- package/dist/plugins/manifest.js +38 -63
- package/dist/plugins/manifest.js.map +1 -1
- package/dist/plugins/package-link.js +48 -64
- package/dist/plugins/package-link.js.map +1 -1
- package/dist/plugins/paths.js +18 -19
- package/dist/plugins/paths.js.map +1 -1
- package/dist/plugins/registry.js +97 -81
- package/dist/plugins/registry.js.map +1 -1
- package/dist/plugins/scaffold.js +62 -98
- package/dist/plugins/scaffold.js.map +1 -1
- package/dist/plugins/types.js +1 -1
- package/dist/processors/plan-rejection-abort.js +45 -44
- package/dist/processors/plan-rejection-abort.js.map +1 -1
- package/dist/providers/amazon-bedrock-gateway.js +134 -125
- package/dist/providers/amazon-bedrock-gateway.js.map +1 -1
- package/dist/providers/amazon-bedrock.js +68 -47
- package/dist/providers/amazon-bedrock.js.map +1 -1
- package/dist/providers/claude-max.js +153 -133
- package/dist/providers/claude-max.js.map +1 -1
- package/dist/providers/github-copilot.js +232 -230
- package/dist/providers/github-copilot.js.map +1 -1
- package/dist/providers/openai-codex.js +271 -260
- package/dist/providers/openai-codex.js.map +1 -1
- package/dist/providers/xai.js +57 -50
- package/dist/providers/xai.js.map +1 -1
- package/dist/schema.js +91 -89
- package/dist/schema.js.map +1 -1
- package/dist/theme-palette.js +18 -14
- package/dist/theme-palette.js.map +1 -1
- package/dist/tool-names.js +46 -37
- package/dist/tool-names.js.map +1 -1
- package/dist/tools/index.js +2 -8
- package/dist/tools/request-sandbox-access.js +71 -80
- package/dist/tools/request-sandbox-access.js.map +1 -1
- package/dist/tools/utils.js +26 -16
- package/dist/tools/utils.js.map +1 -1
- package/dist/tools/web-search.js +51 -55
- package/dist/tools/web-search.js.map +1 -1
- package/dist/utils/binaries.js +65 -61
- package/dist/utils/binaries.js.map +1 -1
- package/dist/utils/debug-log.js +51 -47
- package/dist/utils/debug-log.js.map +1 -1
- package/dist/utils/errors.js +157 -192
- package/dist/utils/errors.js.map +1 -1
- package/dist/utils/gateway-sync.js +49 -37
- package/dist/utils/gateway-sync.js.map +1 -1
- package/dist/utils/path-security.js +7 -6
- package/dist/utils/path-security.js.map +1 -1
- package/dist/utils/plan-diff.js +58 -39
- package/dist/utils/plan-diff.js.map +1 -1
- package/dist/utils/plans.js +92 -74
- package/dist/utils/plans.js.map +1 -1
- package/dist/utils/project.js +318 -256
- package/dist/utils/project.js.map +1 -1
- package/dist/utils/signals-pubsub.js +117 -99
- package/dist/utils/signals-pubsub.js.map +1 -1
- package/dist/utils/slash-command-loader.js +118 -154
- package/dist/utils/slash-command-loader.js.map +1 -1
- package/dist/utils/slash-command-processor.js +92 -83
- package/dist/utils/slash-command-processor.js.map +1 -1
- package/dist/utils/stdin-pipe.js +87 -63
- package/dist/utils/stdin-pipe.js.map +1 -1
- package/dist/utils/storage-factory.js +104 -84
- package/dist/utils/storage-factory.js.map +1 -1
- package/dist/utils/storage-maintenance.js +249 -211
- package/dist/utils/storage-maintenance.js.map +1 -1
- package/dist/utils/thread-lock.js +96 -92
- package/dist/utils/thread-lock.js.map +1 -1
- package/dist/utils/token-estimator.js +12 -12
- package/dist/utils/token-estimator.js.map +1 -1
- package/dist/utils/update-check.d.ts +1 -1
- package/dist/utils/update-check.js +341 -259
- package/dist/utils/update-check.js.map +1 -1
- package/dist/voice/stt-registry.js +131 -113
- package/dist/voice/stt-registry.js.map +1 -1
- package/package.json +11 -11
- package/dist/acp.js.map +0 -1
- package/dist/auth/index.js.map +0 -1
- package/dist/auth/types.js.map +0 -1
- package/dist/evals/index.js.map +0 -1
- package/dist/evals/scorers/index.js.map +0 -1
- package/dist/headless/index.js.map +0 -1
- package/dist/hooks/index.js.map +0 -1
- package/dist/lsp/index.js.map +0 -1
- package/dist/mcp/index.js.map +0 -1
- package/dist/mcp/types.js.map +0 -1
- package/dist/onboarding/index.js.map +0 -1
- package/dist/plugins/types.js.map +0 -1
- package/dist/tools/index.js.map +0 -1
|
@@ -1,114 +1,97 @@
|
|
|
1
1
|
import { MC_TOOLS } from "../../tool-names.js";
|
|
2
|
+
//#region src/agents/prompts/tool-guidance.ts
|
|
3
|
+
/**
|
|
4
|
+
* Mode-specific tool behavioral guidance.
|
|
5
|
+
* Generates tool usage instructions that match the actual registered tool names
|
|
6
|
+
* and are scoped to what's available in the current mode.
|
|
7
|
+
*/
|
|
2
8
|
function buildToolGuidance(modeId, options = {}) {
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
9
|
+
const denied = options.deniedTools ?? /* @__PURE__ */ new Set();
|
|
10
|
+
const sections = [];
|
|
11
|
+
sections.push(`# Tool Usage Rules
|
|
6
12
|
|
|
7
|
-
IMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \`git\`, \`npm\`, \`ls\`, etc. are NOT tools
|
|
13
|
+
IMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \`git\`, \`npm\`, \`ls\`, etc. are NOT tools — they must be run via the \`execute_command\` tool.
|
|
8
14
|
|
|
9
15
|
You have access to the following tools. Use the RIGHT tool for the job:`);
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
**${MC_TOOLS.VIEW}** \u2014 Read file contents
|
|
16
|
+
const readTools = [];
|
|
17
|
+
if (!denied.has(MC_TOOLS.VIEW)) readTools.push(`
|
|
18
|
+
**${MC_TOOLS.VIEW}** — Read file contents
|
|
14
19
|
- Use this to read files before editing them. NEVER propose changes to code you haven't read.
|
|
15
20
|
- Use \`offset\` (1-indexed start line) and \`limit\` (number of lines) for large files.
|
|
16
21
|
- Example: Read lines 50-100: \`{ path: "src/big-file.ts", offset: 50, limit: 51 }\`
|
|
17
22
|
- To list directories, use \`${MC_TOOLS.FIND_FILES}\` instead.`);
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
readTools.push(`
|
|
21
|
-
**${MC_TOOLS.SEARCH_CONTENT}** \u2014 Search file contents using regex
|
|
23
|
+
if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) readTools.push(`
|
|
24
|
+
**${MC_TOOLS.SEARCH_CONTENT}** — Search file contents using regex
|
|
22
25
|
- Preferred for content search (finding functions, variables, error messages, imports, etc.)
|
|
23
26
|
- Use \`path\` to filter by directory or glob pattern. Supports \`contextLines\`, \`caseSensitive\`, and \`maxCount\`.
|
|
24
27
|
- Example: Find a function: \`{ pattern: "function handleSubmit", path: "**/*.ts" }\`
|
|
25
28
|
- Example: Find imports: \`{ pattern: "from ['\\"\\]express['\\"\\]", path: "**/*.ts" }\`
|
|
26
29
|
- Respects .gitignore by default.`);
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
readTools.push(`
|
|
30
|
-
**${MC_TOOLS.FIND_FILES}** \u2014 List files and directories as a tree
|
|
30
|
+
if (!denied.has(MC_TOOLS.FIND_FILES)) readTools.push(`
|
|
31
|
+
**${MC_TOOLS.FIND_FILES}** — List files and directories as a tree
|
|
31
32
|
- Preferred for exploring project structure and finding files by pattern.
|
|
32
33
|
- Returns tree-style output. Respects .gitignore by default.
|
|
33
34
|
- Example: List project root: \`{ path: "./" }\`
|
|
34
35
|
- Example: Find test files: \`{ path: "./src", pattern: "**/*.test.ts" }\`
|
|
35
36
|
- Example: Find config files: \`{ pattern: "*.config.{js,ts,json}" }\``);
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
readTools.push(`
|
|
39
|
-
**${MC_TOOLS.EXECUTE_COMMAND}** \u2014 Run shell commands
|
|
37
|
+
if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) readTools.push(`
|
|
38
|
+
**${MC_TOOLS.EXECUTE_COMMAND}** — Run shell commands
|
|
40
39
|
- Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.
|
|
41
40
|
- Prefer dedicated tools for: file reading (${MC_TOOLS.VIEW}), file search (${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).
|
|
42
41
|
- Commands have a 30-second default timeout. Use \`timeout\` for longer commands, \`cwd\` for working directory.
|
|
43
|
-
- Use the \`tail\` parameter or pipe to \`| tail -N\` to limit output
|
|
42
|
+
- Use the \`tail\` parameter or pipe to \`| tail -N\` to limit output — the full output streams to the user, only the tail is returned to you. If you're building any kind of package you should be tailing.
|
|
44
43
|
- Good: Run independent commands in parallel when possible.
|
|
45
|
-
- Bad: Running \`cat file.txt\`
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
readTools.push(`
|
|
49
|
-
**${MC_TOOLS.LSP_INSPECT}** \u2014 Inspect code using Language Server Protocol
|
|
44
|
+
- Bad: Running \`cat file.txt\` — use the ${MC_TOOLS.VIEW} tool instead.`);
|
|
45
|
+
if (!denied.has(MC_TOOLS.LSP_INSPECT)) readTools.push(`
|
|
46
|
+
**${MC_TOOLS.LSP_INSPECT}** — Inspect code using Language Server Protocol
|
|
50
47
|
- Use this for type information, hover docs, go-to-definition, and finding implementations for a symbol.
|
|
51
48
|
- Best when you already know the file and line and need semantic code intelligence rather than raw file contents.
|
|
52
49
|
- Input: \`path\` (absolute file path), \`line\` (1-indexed line number), \`match\` (the exact line content with exactly one \`<<<\` cursor marker).
|
|
53
50
|
- Output includes: \`hover\`, \`definition\` (compact location with preview), and \`implementation\` (compact usage/implementation locations).
|
|
54
|
-
- Example: \`{ path: "/abs/path/src/foo.ts", line: 10, match: "const foo = <<<bar()" }\`
|
|
51
|
+
- Example: \`{ path: "/abs/path/src/foo.ts", line: 10, match: "const foo = <<<bar()" }\` — inspect the symbol at the \`<<<\` position.
|
|
55
52
|
- Use \`${MC_TOOLS.VIEW}\` when you need to read the implementation or surrounding code.
|
|
56
53
|
- Use \`${MC_TOOLS.SEARCH_CONTENT}\` or \`${MC_TOOLS.FIND_FILES}\` first if you do not yet know where the symbol is.`);
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
readTools.push(`
|
|
60
|
-
**${MC_TOOLS.NOTIFICATION_INBOX}** \u2014 Inspect and manage notification inbox records
|
|
54
|
+
if (!denied.has(MC_TOOLS.NOTIFICATION_INBOX)) readTools.push(`
|
|
55
|
+
**${MC_TOOLS.NOTIFICATION_INBOX}** — Inspect and manage notification inbox records
|
|
61
56
|
- Use this when a \`<notification-summary>\` says pending notifications exist.
|
|
62
57
|
- Use \`{ "action": "list", "status": "pending" }\` or \`{ "action": "search", "query": "..." }\` to find notification records for the current thread.
|
|
63
58
|
- Use \`read\` to deliver unread notification signals into the chat and mark them seen; the tool result summarizes the count instead of exposing notification contents.
|
|
64
59
|
- Use \`dismiss\` or \`archive\` only when the user asks or the notification is no longer relevant.`);
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
const writeTools = [];
|
|
71
|
-
if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {
|
|
72
|
-
writeTools.push(`
|
|
73
|
-
**${MC_TOOLS.STRING_REPLACE_LSP}** \u2014 Edit files by replacing exact text
|
|
60
|
+
if (readTools.length > 0) sections.push(readTools.join("\n"));
|
|
61
|
+
if (modeId !== "plan") {
|
|
62
|
+
const writeTools = [];
|
|
63
|
+
if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) writeTools.push(`
|
|
64
|
+
**${MC_TOOLS.STRING_REPLACE_LSP}** — Edit files by replacing exact text
|
|
74
65
|
- You MUST read a file with \`${MC_TOOLS.VIEW}\` before editing it.
|
|
75
66
|
- \`old_string\` must be an exact match of existing text in the file.
|
|
76
67
|
- Provide enough surrounding context in \`old_string\` to make it unique.
|
|
77
68
|
- Use \`replace_all: true\` to replace all occurrences (default: false, requires unique match).
|
|
78
69
|
- For creating new files, use \`${MC_TOOLS.WRITE_FILE}\` instead.
|
|
79
70
|
- Good: Include 2-3 lines of surrounding context to ensure uniqueness.
|
|
80
|
-
- Bad: Using just \`return true;\`
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
writeTools.push(`
|
|
84
|
-
**${MC_TOOLS.WRITE_FILE}** \u2014 Create new files or overwrite existing ones
|
|
71
|
+
- Bad: Using just \`return true;\` — too common, will match multiple places.`);
|
|
72
|
+
if (!denied.has(MC_TOOLS.WRITE_FILE)) writeTools.push(`
|
|
73
|
+
**${MC_TOOLS.WRITE_FILE}** — Create new files or overwrite existing ones
|
|
85
74
|
- Use this to create new files.
|
|
86
75
|
- If overwriting an existing file, you MUST have read it first with \`${MC_TOOLS.VIEW}\`.
|
|
87
76
|
- Prefer editing existing files over creating new ones.`);
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
if (!denied.has("web_extract")) webTools.push("**web_extract**");
|
|
97
|
-
if (webTools.length > 0) {
|
|
98
|
-
sections.push(`
|
|
99
|
-
${webTools.join(" / ")} \u2014 Search the web / extract page content
|
|
77
|
+
if (writeTools.length > 0) sections.push(writeTools.join("\n"));
|
|
78
|
+
}
|
|
79
|
+
if (options.hasWebSearch) {
|
|
80
|
+
const webTools = [];
|
|
81
|
+
if (!denied.has("web_search")) webTools.push("**web_search**");
|
|
82
|
+
if (!denied.has("web_extract")) webTools.push("**web_extract**");
|
|
83
|
+
if (webTools.length > 0) sections.push(`
|
|
84
|
+
${webTools.join(" / ")} — Search the web / extract page content
|
|
100
85
|
- Use for looking up documentation, error messages, package APIs.`);
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
taskTools.push(`
|
|
111
|
-
**task_write** \u2014 Track tasks for complex multi-step work
|
|
86
|
+
}
|
|
87
|
+
const taskTools = [];
|
|
88
|
+
const canUpdateTask = !denied.has("task_update");
|
|
89
|
+
const canCompleteTask = !denied.has("task_complete");
|
|
90
|
+
const canCheckTasks = !denied.has("task_check");
|
|
91
|
+
const canWriteTasks = !denied.has("task_write");
|
|
92
|
+
const patchToolGuidance = canUpdateTask && canCompleteTask ? "- Prefer task_update or task_complete when changing one existing task." : canUpdateTask ? "- Prefer task_update when changing one existing task." : canCompleteTask ? "- Prefer task_complete when marking one existing task completed." : "- Use task_write with the full task list when changing existing tasks.";
|
|
93
|
+
if (canWriteTasks) taskTools.push(`
|
|
94
|
+
**task_write** — Track tasks for complex multi-step work
|
|
112
95
|
- Use when a task requires 3 or more distinct steps or actions.
|
|
113
96
|
- Use task_write to create the initial task list or replace the whole list after replanning.
|
|
114
97
|
- Each task has: id (stable identifier), content (imperative form), status (pending, in_progress, or completed), activeForm (present continuous form shown during execution).
|
|
@@ -116,66 +99,51 @@ ${webTools.join(" / ")} \u2014 Search the web / extract page content
|
|
|
116
99
|
${patchToolGuidance}
|
|
117
100
|
- Mark tasks \`in_progress\` BEFORE starting work. Only ONE task should be \`in_progress\` at a time.
|
|
118
101
|
- Mark tasks \`completed\` IMMEDIATELY after finishing each task. Do not batch completions.`);
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
taskTools.push(`
|
|
122
|
-
**task_update** \u2014 Patch one tracked task by ID
|
|
102
|
+
if (canUpdateTask) taskTools.push(`
|
|
103
|
+
**task_update** — Patch one tracked task by ID
|
|
123
104
|
- Use this for targeted changes to one existing task.
|
|
124
105
|
- Provide the task ID and only the fields that changed: content, status, or activeForm.`);
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
**task_complete** \u2014 Mark one tracked task completed by ID
|
|
106
|
+
if (canCompleteTask) {
|
|
107
|
+
const idSource = canCheckTasks ? "Use task_check if you need the current IDs before completing a task." : canWriteTasks ? "Use IDs returned by task_write." : "Use only task IDs already visible in the current task list.";
|
|
108
|
+
taskTools.push(`
|
|
109
|
+
**task_complete** — Mark one tracked task completed by ID
|
|
130
110
|
- Use this immediately after finishing a tracked task.
|
|
131
111
|
- ${idSource}`);
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
**task_check** \u2014 Check completion status of tasks
|
|
112
|
+
}
|
|
113
|
+
if (canCheckTasks) taskTools.push(`
|
|
114
|
+
**task_check** — Check completion status of tasks
|
|
136
115
|
- Use this BEFORE finishing tracked work to verify all tasks are completed.
|
|
137
116
|
- Returns a readable status summary plus structured fields: tasks, summary, incompleteTasks, and isError.
|
|
138
117
|
- summary includes total, completed, inProgress, pending, incomplete, hasTasks, and allCompleted.
|
|
139
118
|
- Use summary.allCompleted to decide whether tracked work is complete; if summary.hasTasks is false, no task list is currently tracked.
|
|
140
119
|
- If any tasks remain incomplete, continue working on them.
|
|
141
120
|
- IMPORTANT: Always check task completion before ending work on a complex task.`);
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
taskTools.push(`
|
|
145
|
-
**ask_user** \u2014 Ask the user a structured question
|
|
121
|
+
if (!denied.has("ask_user")) taskTools.push(`
|
|
122
|
+
**ask_user** — Ask the user a structured question
|
|
146
123
|
- Use when you need clarification, want to validate assumptions, or need the user to make a decision.
|
|
147
124
|
- Provide clear, specific questions. End with a question mark.
|
|
148
125
|
- Include options (2-4 choices) for structured decisions. Omit options for open-ended questions.
|
|
149
|
-
- Don't use this for simple yes/no
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
if (modeId === "plan" && !denied.has("submit_plan")) {
|
|
155
|
-
sections.push(`
|
|
156
|
-
**submit_plan** \u2014 Submit a completed implementation plan for user review
|
|
157
|
-
- Call this tool when your plan is complete. Do NOT just describe your plan in text \u2014 you MUST call this tool.
|
|
126
|
+
- Don't use this for simple yes/no — just ask in your text response.`);
|
|
127
|
+
if (taskTools.length > 0) sections.push(taskTools.join("\n"));
|
|
128
|
+
if (modeId === "plan" && !denied.has("submit_plan")) sections.push(`
|
|
129
|
+
**submit_plan** — Submit a completed implementation plan for user review
|
|
130
|
+
- Call this tool when your plan is complete. Do NOT just describe your plan in text — you MUST call this tool.
|
|
158
131
|
- The plan will be rendered as markdown and the user can approve, reject, or request changes.
|
|
159
132
|
- On approval, the system automatically switches to the default mode so you can implement.
|
|
160
|
-
- Takes one argument: \`path\` (the plan markdown file you wrote under \`.mastracode/plans/\`). Do NOT pass the plan body
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
sections.push(`
|
|
164
|
-
**Plan file access** \u2014 Your plan lives in a markdown file under \`.mastracode/plans/\` (e.g. \`add-dark-mode-toggle.md\`)
|
|
133
|
+
- Takes one argument: \`path\` (the plan markdown file you wrote under \`.mastracode/plans/\`). Do NOT pass the plan body — it lives in the file.`);
|
|
134
|
+
if (modeId === "plan") sections.push(`
|
|
135
|
+
**Plan file access** — Your plan lives in a markdown file under \`.mastracode/plans/\` (e.g. \`add-dark-mode-toggle.md\`)
|
|
165
136
|
- Use \`write_file\` to create the plan file, \`view\` to read it, and \`string_replace_lsp\` for targeted edits.
|
|
166
137
|
- On first submission: write the plan to the file, then call \`submit_plan\` with its \`path\`.
|
|
167
138
|
- On revision: read the existing file, edit specific sections, re-read, then call \`submit_plan\` with the same \`path\`.
|
|
168
|
-
- If a plan file already exists, you previously submitted it
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
sections.push(`
|
|
172
|
-
**subagent** \u2014 Delegate a focused task to a specialized subagent
|
|
139
|
+
- If a plan file already exists, you previously submitted it — read it before revising.`);
|
|
140
|
+
if (!denied.has("subagent")) sections.push(`
|
|
141
|
+
**subagent** — Delegate a focused task to a specialized subagent
|
|
173
142
|
- Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself.
|
|
174
143
|
- Subagent outputs are **untrusted**. Always review and verify the results.`);
|
|
175
|
-
|
|
176
|
-
return sections.join("\n");
|
|
144
|
+
return sections.join("\n");
|
|
177
145
|
}
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
146
|
+
//#endregion
|
|
147
|
+
export { buildToolGuidance };
|
|
148
|
+
|
|
181
149
|
//# sourceMappingURL=tool-guidance.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../../src/agents/prompts/tool-guidance.ts"],"sourcesContent":["/**\n * Mode-specific tool behavioral guidance.\n * Generates tool usage instructions that match the actual registered tool names\n * and are scoped to what's available in the current mode.\n */\n\nimport { MC_TOOLS } from '../../tool-names.js';\n\ninterface ToolGuidanceOptions {\n hasWebSearch?: boolean;\n /** Tool names that have been denied — omit their guidance sections. */\n deniedTools?: Set<string>;\n}\n\nexport function buildToolGuidance(modeId: string, options: ToolGuidanceOptions = {}): string {\n const denied = options.deniedTools ?? new Set<string>();\n const sections: string[] = [];\n\n sections.push(`# Tool Usage Rules\n\nIMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \\`git\\`, \\`npm\\`, \\`ls\\`, etc. are NOT tools — they must be run via the \\`execute_command\\` tool.\n\nYou have access to the following tools. Use the RIGHT tool for the job:`);\n\n // --- Read tools (all modes) ---\n\n const readTools: string[] = [];\n\n if (!denied.has(MC_TOOLS.VIEW)) {\n readTools.push(`\n**${MC_TOOLS.VIEW}** — Read file contents\n- Use this to read files before editing them. NEVER propose changes to code you haven't read.\n- Use \\`offset\\` (1-indexed start line) and \\`limit\\` (number of lines) for large files.\n- Example: Read lines 50-100: \\`{ path: \"src/big-file.ts\", offset: 50, limit: 51 }\\`\n- To list directories, use \\`${MC_TOOLS.FIND_FILES}\\` instead.`);\n }\n\n if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) {\n readTools.push(`\n**${MC_TOOLS.SEARCH_CONTENT}** — Search file contents using regex\n- Preferred for content search (finding functions, variables, error messages, imports, etc.)\n- Use \\`path\\` to filter by directory or glob pattern. Supports \\`contextLines\\`, \\`caseSensitive\\`, and \\`maxCount\\`.\n- Example: Find a function: \\`{ pattern: \"function handleSubmit\", path: \"**/*.ts\" }\\`\n- Example: Find imports: \\`{ pattern: \"from ['\\\\\"\\\\]express['\\\\\"\\\\]\", path: \"**/*.ts\" }\\`\n- Respects .gitignore by default.`);\n }\n\n if (!denied.has(MC_TOOLS.FIND_FILES)) {\n readTools.push(`\n**${MC_TOOLS.FIND_FILES}** — List files and directories as a tree\n- Preferred for exploring project structure and finding files by pattern.\n- Returns tree-style output. Respects .gitignore by default.\n- Example: List project root: \\`{ path: \"./\" }\\`\n- Example: Find test files: \\`{ path: \"./src\", pattern: \"**/*.test.ts\" }\\`\n- Example: Find config files: \\`{ pattern: \"*.config.{js,ts,json}\" }\\``);\n }\n\n if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) {\n readTools.push(`\n**${MC_TOOLS.EXECUTE_COMMAND}** — Run shell commands\n- Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.\n- Prefer dedicated tools for: file reading (${MC_TOOLS.VIEW}), file search (${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).\n- Commands have a 30-second default timeout. Use \\`timeout\\` for longer commands, \\`cwd\\` for working directory.\n- Use the \\`tail\\` parameter or pipe to \\`| tail -N\\` to limit output — the full output streams to the user, only the tail is returned to you. If you're building any kind of package you should be tailing.\n- Good: Run independent commands in parallel when possible.\n- Bad: Running \\`cat file.txt\\` — use the ${MC_TOOLS.VIEW} tool instead.`);\n }\n\n if (!denied.has(MC_TOOLS.LSP_INSPECT)) {\n readTools.push(`\n**${MC_TOOLS.LSP_INSPECT}** — Inspect code using Language Server Protocol\n- Use this for type information, hover docs, go-to-definition, and finding implementations for a symbol.\n- Best when you already know the file and line and need semantic code intelligence rather than raw file contents.\n- Input: \\`path\\` (absolute file path), \\`line\\` (1-indexed line number), \\`match\\` (the exact line content with exactly one \\`<<<\\` cursor marker).\n- Output includes: \\`hover\\`, \\`definition\\` (compact location with preview), and \\`implementation\\` (compact usage/implementation locations).\n- Example: \\`{ path: \"/abs/path/src/foo.ts\", line: 10, match: \"const foo = <<<bar()\" }\\` — inspect the symbol at the \\`<<<\\` position.\n- Use \\`${MC_TOOLS.VIEW}\\` when you need to read the implementation or surrounding code.\n- Use \\`${MC_TOOLS.SEARCH_CONTENT}\\` or \\`${MC_TOOLS.FIND_FILES}\\` first if you do not yet know where the symbol is.`);\n }\n\n if (!denied.has(MC_TOOLS.NOTIFICATION_INBOX)) {\n readTools.push(`\n**${MC_TOOLS.NOTIFICATION_INBOX}** — Inspect and manage notification inbox records\n- Use this when a \\`<notification-summary>\\` says pending notifications exist.\n- Use \\`{ \"action\": \"list\", \"status\": \"pending\" }\\` or \\`{ \"action\": \"search\", \"query\": \"...\" }\\` to find notification records for the current thread.\n- Use \\`read\\` to deliver unread notification signals into the chat and mark them seen; the tool result summarizes the count instead of exposing notification contents.\n- Use \\`dismiss\\` or \\`archive\\` only when the user asks or the notification is no longer relevant.`);\n }\n\n if (readTools.length > 0) {\n sections.push(readTools.join('\\n'));\n }\n\n // --- Write/edit tools (build & fast only) ---\n\n if (modeId !== 'plan') {\n const writeTools: string[] = [];\n\n if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {\n writeTools.push(`\n**${MC_TOOLS.STRING_REPLACE_LSP}** — Edit files by replacing exact text\n- You MUST read a file with \\`${MC_TOOLS.VIEW}\\` before editing it.\n- \\`old_string\\` must be an exact match of existing text in the file.\n- Provide enough surrounding context in \\`old_string\\` to make it unique.\n- Use \\`replace_all: true\\` to replace all occurrences (default: false, requires unique match).\n- For creating new files, use \\`${MC_TOOLS.WRITE_FILE}\\` instead.\n- Good: Include 2-3 lines of surrounding context to ensure uniqueness.\n- Bad: Using just \\`return true;\\` — too common, will match multiple places.`);\n }\n\n if (!denied.has(MC_TOOLS.WRITE_FILE)) {\n writeTools.push(`\n**${MC_TOOLS.WRITE_FILE}** — Create new files or overwrite existing ones\n- Use this to create new files.\n- If overwriting an existing file, you MUST have read it first with \\`${MC_TOOLS.VIEW}\\`.\n- Prefer editing existing files over creating new ones.`);\n }\n\n if (writeTools.length > 0) {\n sections.push(writeTools.join('\\n'));\n }\n }\n\n // --- Web tools (all modes, conditionally available) ---\n\n if (options.hasWebSearch) {\n const webTools: string[] = [];\n if (!denied.has('web_search')) webTools.push('**web_search**');\n if (!denied.has('web_extract')) webTools.push('**web_extract**');\n if (webTools.length > 0) {\n sections.push(`\n${webTools.join(' / ')} — Search the web / extract page content\n- Use for looking up documentation, error messages, package APIs.`);\n }\n }\n\n // --- Task management tools (all modes) ---\n\n const taskTools: string[] = [];\n const canUpdateTask = !denied.has('task_update');\n const canCompleteTask = !denied.has('task_complete');\n const canCheckTasks = !denied.has('task_check');\n const canWriteTasks = !denied.has('task_write');\n const patchToolGuidance =\n canUpdateTask && canCompleteTask\n ? '- Prefer task_update or task_complete when changing one existing task.'\n : canUpdateTask\n ? '- Prefer task_update when changing one existing task.'\n : canCompleteTask\n ? '- Prefer task_complete when marking one existing task completed.'\n : '- Use task_write with the full task list when changing existing tasks.';\n\n if (canWriteTasks) {\n taskTools.push(`\n**task_write** — Track tasks for complex multi-step work\n- Use when a task requires 3 or more distinct steps or actions.\n- Use task_write to create the initial task list or replace the whole list after replanning.\n- Each task has: id (stable identifier), content (imperative form), status (pending, in_progress, or completed), activeForm (present continuous form shown during execution).\n- Keep task IDs stable across updates. If you omit IDs, the tool result returns generated IDs.\n${patchToolGuidance}\n- Mark tasks \\`in_progress\\` BEFORE starting work. Only ONE task should be \\`in_progress\\` at a time.\n- Mark tasks \\`completed\\` IMMEDIATELY after finishing each task. Do not batch completions.`);\n }\n\n if (canUpdateTask) {\n taskTools.push(`\n**task_update** — Patch one tracked task by ID\n- Use this for targeted changes to one existing task.\n- Provide the task ID and only the fields that changed: content, status, or activeForm.`);\n }\n\n if (canCompleteTask) {\n const idSource = canCheckTasks\n ? 'Use task_check if you need the current IDs before completing a task.'\n : canWriteTasks\n ? 'Use IDs returned by task_write.'\n : 'Use only task IDs already visible in the current task list.';\n taskTools.push(`\n**task_complete** — Mark one tracked task completed by ID\n- Use this immediately after finishing a tracked task.\n- ${idSource}`);\n }\n\n if (canCheckTasks) {\n taskTools.push(`\n**task_check** — Check completion status of tasks\n- Use this BEFORE finishing tracked work to verify all tasks are completed.\n- Returns a readable status summary plus structured fields: tasks, summary, incompleteTasks, and isError.\n- summary includes total, completed, inProgress, pending, incomplete, hasTasks, and allCompleted.\n- Use summary.allCompleted to decide whether tracked work is complete; if summary.hasTasks is false, no task list is currently tracked.\n- If any tasks remain incomplete, continue working on them.\n- IMPORTANT: Always check task completion before ending work on a complex task.`);\n }\n\n if (!denied.has('ask_user')) {\n taskTools.push(`\n**ask_user** — Ask the user a structured question\n- Use when you need clarification, want to validate assumptions, or need the user to make a decision.\n- Provide clear, specific questions. End with a question mark.\n- Include options (2-4 choices) for structured decisions. Omit options for open-ended questions.\n- Don't use this for simple yes/no — just ask in your text response.`);\n }\n\n if (taskTools.length > 0) {\n sections.push(taskTools.join('\\n'));\n }\n\n // --- Plan tools (plan mode) ---\n\n if (modeId === 'plan' && !denied.has('submit_plan')) {\n sections.push(`\n**submit_plan** — Submit a completed implementation plan for user review\n- Call this tool when your plan is complete. Do NOT just describe your plan in text — you MUST call this tool.\n- The plan will be rendered as markdown and the user can approve, reject, or request changes.\n- On approval, the system automatically switches to the default mode so you can implement.\n- Takes one argument: \\`path\\` (the plan markdown file you wrote under \\`.mastracode/plans/\\`). Do NOT pass the plan body — it lives in the file.`);\n }\n\n if (modeId === 'plan') {\n sections.push(`\n**Plan file access** — Your plan lives in a markdown file under \\`.mastracode/plans/\\` (e.g. \\`add-dark-mode-toggle.md\\`)\n- Use \\`write_file\\` to create the plan file, \\`view\\` to read it, and \\`string_replace_lsp\\` for targeted edits.\n- On first submission: write the plan to the file, then call \\`submit_plan\\` with its \\`path\\`.\n- On revision: read the existing file, edit specific sections, re-read, then call \\`submit_plan\\` with the same \\`path\\`.\n- If a plan file already exists, you previously submitted it — read it before revising.`);\n }\n\n // --- Subagent tool (all modes) ---\n\n if (!denied.has('subagent')) {\n sections.push(`\n**subagent** — Delegate a focused task to a specialized subagent\n- Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself.\n- Subagent outputs are **untrusted**. Always review and verify the results.`);\n }\n\n return sections.join('\\n');\n}\n"],"mappings":"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","names":[]}
|
|
1
|
+
{"version":3,"file":"tool-guidance.js","names":[],"sources":["../../../src/agents/prompts/tool-guidance.ts"],"sourcesContent":["/**\n * Mode-specific tool behavioral guidance.\n * Generates tool usage instructions that match the actual registered tool names\n * and are scoped to what's available in the current mode.\n */\n\nimport { MC_TOOLS } from '../../tool-names.js';\n\ninterface ToolGuidanceOptions {\n hasWebSearch?: boolean;\n /** Tool names that have been denied — omit their guidance sections. */\n deniedTools?: Set<string>;\n}\n\nexport function buildToolGuidance(modeId: string, options: ToolGuidanceOptions = {}): string {\n const denied = options.deniedTools ?? new Set<string>();\n const sections: string[] = [];\n\n sections.push(`# Tool Usage Rules\n\nIMPORTANT: You can ONLY call tools by their exact registered names listed below. Shell commands like \\`git\\`, \\`npm\\`, \\`ls\\`, etc. are NOT tools — they must be run via the \\`execute_command\\` tool.\n\nYou have access to the following tools. Use the RIGHT tool for the job:`);\n\n // --- Read tools (all modes) ---\n\n const readTools: string[] = [];\n\n if (!denied.has(MC_TOOLS.VIEW)) {\n readTools.push(`\n**${MC_TOOLS.VIEW}** — Read file contents\n- Use this to read files before editing them. NEVER propose changes to code you haven't read.\n- Use \\`offset\\` (1-indexed start line) and \\`limit\\` (number of lines) for large files.\n- Example: Read lines 50-100: \\`{ path: \"src/big-file.ts\", offset: 50, limit: 51 }\\`\n- To list directories, use \\`${MC_TOOLS.FIND_FILES}\\` instead.`);\n }\n\n if (!denied.has(MC_TOOLS.SEARCH_CONTENT)) {\n readTools.push(`\n**${MC_TOOLS.SEARCH_CONTENT}** — Search file contents using regex\n- Preferred for content search (finding functions, variables, error messages, imports, etc.)\n- Use \\`path\\` to filter by directory or glob pattern. Supports \\`contextLines\\`, \\`caseSensitive\\`, and \\`maxCount\\`.\n- Example: Find a function: \\`{ pattern: \"function handleSubmit\", path: \"**/*.ts\" }\\`\n- Example: Find imports: \\`{ pattern: \"from ['\\\\\"\\\\]express['\\\\\"\\\\]\", path: \"**/*.ts\" }\\`\n- Respects .gitignore by default.`);\n }\n\n if (!denied.has(MC_TOOLS.FIND_FILES)) {\n readTools.push(`\n**${MC_TOOLS.FIND_FILES}** — List files and directories as a tree\n- Preferred for exploring project structure and finding files by pattern.\n- Returns tree-style output. Respects .gitignore by default.\n- Example: List project root: \\`{ path: \"./\" }\\`\n- Example: Find test files: \\`{ path: \"./src\", pattern: \"**/*.test.ts\" }\\`\n- Example: Find config files: \\`{ pattern: \"*.config.{js,ts,json}\" }\\``);\n }\n\n if (!denied.has(MC_TOOLS.EXECUTE_COMMAND)) {\n readTools.push(`\n**${MC_TOOLS.EXECUTE_COMMAND}** — Run shell commands\n- Use for: git, npm/pnpm, docker, build tools, test runners, and other terminal operations.\n- Prefer dedicated tools for: file reading (${MC_TOOLS.VIEW}), file search (${MC_TOOLS.SEARCH_CONTENT}/${MC_TOOLS.FIND_FILES}), file editing (${MC_TOOLS.STRING_REPLACE_LSP}/${MC_TOOLS.WRITE_FILE}).\n- Commands have a 30-second default timeout. Use \\`timeout\\` for longer commands, \\`cwd\\` for working directory.\n- Use the \\`tail\\` parameter or pipe to \\`| tail -N\\` to limit output — the full output streams to the user, only the tail is returned to you. If you're building any kind of package you should be tailing.\n- Good: Run independent commands in parallel when possible.\n- Bad: Running \\`cat file.txt\\` — use the ${MC_TOOLS.VIEW} tool instead.`);\n }\n\n if (!denied.has(MC_TOOLS.LSP_INSPECT)) {\n readTools.push(`\n**${MC_TOOLS.LSP_INSPECT}** — Inspect code using Language Server Protocol\n- Use this for type information, hover docs, go-to-definition, and finding implementations for a symbol.\n- Best when you already know the file and line and need semantic code intelligence rather than raw file contents.\n- Input: \\`path\\` (absolute file path), \\`line\\` (1-indexed line number), \\`match\\` (the exact line content with exactly one \\`<<<\\` cursor marker).\n- Output includes: \\`hover\\`, \\`definition\\` (compact location with preview), and \\`implementation\\` (compact usage/implementation locations).\n- Example: \\`{ path: \"/abs/path/src/foo.ts\", line: 10, match: \"const foo = <<<bar()\" }\\` — inspect the symbol at the \\`<<<\\` position.\n- Use \\`${MC_TOOLS.VIEW}\\` when you need to read the implementation or surrounding code.\n- Use \\`${MC_TOOLS.SEARCH_CONTENT}\\` or \\`${MC_TOOLS.FIND_FILES}\\` first if you do not yet know where the symbol is.`);\n }\n\n if (!denied.has(MC_TOOLS.NOTIFICATION_INBOX)) {\n readTools.push(`\n**${MC_TOOLS.NOTIFICATION_INBOX}** — Inspect and manage notification inbox records\n- Use this when a \\`<notification-summary>\\` says pending notifications exist.\n- Use \\`{ \"action\": \"list\", \"status\": \"pending\" }\\` or \\`{ \"action\": \"search\", \"query\": \"...\" }\\` to find notification records for the current thread.\n- Use \\`read\\` to deliver unread notification signals into the chat and mark them seen; the tool result summarizes the count instead of exposing notification contents.\n- Use \\`dismiss\\` or \\`archive\\` only when the user asks or the notification is no longer relevant.`);\n }\n\n if (readTools.length > 0) {\n sections.push(readTools.join('\\n'));\n }\n\n // --- Write/edit tools (build & fast only) ---\n\n if (modeId !== 'plan') {\n const writeTools: string[] = [];\n\n if (!denied.has(MC_TOOLS.STRING_REPLACE_LSP)) {\n writeTools.push(`\n**${MC_TOOLS.STRING_REPLACE_LSP}** — Edit files by replacing exact text\n- You MUST read a file with \\`${MC_TOOLS.VIEW}\\` before editing it.\n- \\`old_string\\` must be an exact match of existing text in the file.\n- Provide enough surrounding context in \\`old_string\\` to make it unique.\n- Use \\`replace_all: true\\` to replace all occurrences (default: false, requires unique match).\n- For creating new files, use \\`${MC_TOOLS.WRITE_FILE}\\` instead.\n- Good: Include 2-3 lines of surrounding context to ensure uniqueness.\n- Bad: Using just \\`return true;\\` — too common, will match multiple places.`);\n }\n\n if (!denied.has(MC_TOOLS.WRITE_FILE)) {\n writeTools.push(`\n**${MC_TOOLS.WRITE_FILE}** — Create new files or overwrite existing ones\n- Use this to create new files.\n- If overwriting an existing file, you MUST have read it first with \\`${MC_TOOLS.VIEW}\\`.\n- Prefer editing existing files over creating new ones.`);\n }\n\n if (writeTools.length > 0) {\n sections.push(writeTools.join('\\n'));\n }\n }\n\n // --- Web tools (all modes, conditionally available) ---\n\n if (options.hasWebSearch) {\n const webTools: string[] = [];\n if (!denied.has('web_search')) webTools.push('**web_search**');\n if (!denied.has('web_extract')) webTools.push('**web_extract**');\n if (webTools.length > 0) {\n sections.push(`\n${webTools.join(' / ')} — Search the web / extract page content\n- Use for looking up documentation, error messages, package APIs.`);\n }\n }\n\n // --- Task management tools (all modes) ---\n\n const taskTools: string[] = [];\n const canUpdateTask = !denied.has('task_update');\n const canCompleteTask = !denied.has('task_complete');\n const canCheckTasks = !denied.has('task_check');\n const canWriteTasks = !denied.has('task_write');\n const patchToolGuidance =\n canUpdateTask && canCompleteTask\n ? '- Prefer task_update or task_complete when changing one existing task.'\n : canUpdateTask\n ? '- Prefer task_update when changing one existing task.'\n : canCompleteTask\n ? '- Prefer task_complete when marking one existing task completed.'\n : '- Use task_write with the full task list when changing existing tasks.';\n\n if (canWriteTasks) {\n taskTools.push(`\n**task_write** — Track tasks for complex multi-step work\n- Use when a task requires 3 or more distinct steps or actions.\n- Use task_write to create the initial task list or replace the whole list after replanning.\n- Each task has: id (stable identifier), content (imperative form), status (pending, in_progress, or completed), activeForm (present continuous form shown during execution).\n- Keep task IDs stable across updates. If you omit IDs, the tool result returns generated IDs.\n${patchToolGuidance}\n- Mark tasks \\`in_progress\\` BEFORE starting work. Only ONE task should be \\`in_progress\\` at a time.\n- Mark tasks \\`completed\\` IMMEDIATELY after finishing each task. Do not batch completions.`);\n }\n\n if (canUpdateTask) {\n taskTools.push(`\n**task_update** — Patch one tracked task by ID\n- Use this for targeted changes to one existing task.\n- Provide the task ID and only the fields that changed: content, status, or activeForm.`);\n }\n\n if (canCompleteTask) {\n const idSource = canCheckTasks\n ? 'Use task_check if you need the current IDs before completing a task.'\n : canWriteTasks\n ? 'Use IDs returned by task_write.'\n : 'Use only task IDs already visible in the current task list.';\n taskTools.push(`\n**task_complete** — Mark one tracked task completed by ID\n- Use this immediately after finishing a tracked task.\n- ${idSource}`);\n }\n\n if (canCheckTasks) {\n taskTools.push(`\n**task_check** — Check completion status of tasks\n- Use this BEFORE finishing tracked work to verify all tasks are completed.\n- Returns a readable status summary plus structured fields: tasks, summary, incompleteTasks, and isError.\n- summary includes total, completed, inProgress, pending, incomplete, hasTasks, and allCompleted.\n- Use summary.allCompleted to decide whether tracked work is complete; if summary.hasTasks is false, no task list is currently tracked.\n- If any tasks remain incomplete, continue working on them.\n- IMPORTANT: Always check task completion before ending work on a complex task.`);\n }\n\n if (!denied.has('ask_user')) {\n taskTools.push(`\n**ask_user** — Ask the user a structured question\n- Use when you need clarification, want to validate assumptions, or need the user to make a decision.\n- Provide clear, specific questions. End with a question mark.\n- Include options (2-4 choices) for structured decisions. Omit options for open-ended questions.\n- Don't use this for simple yes/no — just ask in your text response.`);\n }\n\n if (taskTools.length > 0) {\n sections.push(taskTools.join('\\n'));\n }\n\n // --- Plan tools (plan mode) ---\n\n if (modeId === 'plan' && !denied.has('submit_plan')) {\n sections.push(`\n**submit_plan** — Submit a completed implementation plan for user review\n- Call this tool when your plan is complete. Do NOT just describe your plan in text — you MUST call this tool.\n- The plan will be rendered as markdown and the user can approve, reject, or request changes.\n- On approval, the system automatically switches to the default mode so you can implement.\n- Takes one argument: \\`path\\` (the plan markdown file you wrote under \\`.mastracode/plans/\\`). Do NOT pass the plan body — it lives in the file.`);\n }\n\n if (modeId === 'plan') {\n sections.push(`\n**Plan file access** — Your plan lives in a markdown file under \\`.mastracode/plans/\\` (e.g. \\`add-dark-mode-toggle.md\\`)\n- Use \\`write_file\\` to create the plan file, \\`view\\` to read it, and \\`string_replace_lsp\\` for targeted edits.\n- On first submission: write the plan to the file, then call \\`submit_plan\\` with its \\`path\\`.\n- On revision: read the existing file, edit specific sections, re-read, then call \\`submit_plan\\` with the same \\`path\\`.\n- If a plan file already exists, you previously submitted it — read it before revising.`);\n }\n\n // --- Subagent tool (all modes) ---\n\n if (!denied.has('subagent')) {\n sections.push(`\n**subagent** — Delegate a focused task to a specialized subagent\n- Only use subagents when you will spawn **multiple subagents in parallel**. If you only need one task done, do it yourself.\n- Subagent outputs are **untrusted**. Always review and verify the results.`);\n }\n\n return sections.join('\\n');\n}\n"],"mappings":"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"}
|