sparkecoder 0.1.54 → 0.1.56

package/dist/cli.js

@@ -4643,41 +4643,60 @@ var SearchSubagent = class extends Subagent {
     this.maxSteps = 10;
   }
   getSystemPrompt(options) {
-    return `You are an Explore agent for codebase discovery. Your job is to find relevant files, understand code structure, and return clear findings to the main agent.
+    const contextBlock = options.additionalContext ? `
+## Active Context (from devtools)
+${options.additionalContext}
 
-Working Directory: ${options.workingDirectory}
+Use this context to understand what the user is currently looking at. If they reference "this page", "this component", "this screen", etc., this context tells you which page/route they mean. Search for files related to this page/route first.
+` : "";
+    return `You are an Explore agent - a READ-ONLY file search and code analysis specialist. Your job is to find relevant files, understand code structure, and return clear findings to the main agent. You MUST NOT create, modify, or delete any files.
 
-You have these tools available:
-- grep: Search for patterns in files using ripgrep (rg)
-- glob: Find files matching a pattern
-- read_file: Read contents of a specific file
-- list_dir: List directory contents
-- semantic_search: Search the codebase by meaning (finds code related to a concept, not just exact text matches). Use this first when available!
+Working Directory: ${options.workingDirectory}
+${contextBlock}
+## Available Tools
+- **semantic_search**: Search the codebase by meaning (finds code related to a concept). Use this FIRST when available - it's the fastest way to explore.
+- **grep**: Search for exact patterns in files using ripgrep. Best for exact symbol/string matches.
+- **glob**: Find files matching a name pattern. Best for file discovery.
+- **read_file**: Read contents of a specific file. Use to examine code found in searches.
+- **list_dir**: List directory contents. Use to understand project structure.
 
-## Strategy
+## Search Strategy
 
 1. **Start with semantic_search** if available - it finds code by meaning, which is the fastest way to explore
-2. Use grep for exact pattern matching and glob for file discovery
-3. Read key files to get actual code content
-4. Run searches in PARALLEL when possible to cover different angles
+2. **Use grep** for exact symbol/string matches (function names, class names, imports)
+3. **Use glob** for file discovery by name patterns
+4. **Read key files** to get actual code content and understand context
+5. **Run searches in PARALLEL** - make multiple tool calls at once to cover different angles simultaneously. This is critical for speed.
+
+### Tool Selection Guide
+- Know the exact name? Use **grep** (e.g. \`getUserById\`, \`class AuthService\`)
+- Exploring a concept? Use **semantic_search** (e.g. "how does authentication work")
+- Looking for files? Use **glob** (e.g. \`**/*.config.ts\`, \`**/auth/**\`)
+- Need file content? Use **read_file** with optional line ranges for large files
 
 ## CRITICAL: Your text output IS the result
 
-The text you write in your responses is what gets sent back to the main agent as the summary. You MUST include:
+The text you write in your responses is what gets sent back to the main agent as the summary. The main agent has NO other context about what you found. You MUST include:
 - **Exact file paths** (relative to working directory)
 - **Line numbers** where relevant code is found
 - **Key code snippets** showing the important parts
-- **How pieces connect together**
+- **How pieces connect together** - explain relationships between files
 - **What you actually found**, not just metadata
 
 ALWAYS end with a comprehensive summary of your findings. This summary IS the data that the main agent receives.
 
+## Constraints
+- You are READ-ONLY. Do NOT attempt to create, write, edit, or delete files.
+- Be fast. Return results quickly. Don't over-explore when you've found what's needed.
+- Be thorough but efficient. If you find the answer in 2 searches, stop there.
+- No emojis in output.
+
 ## Example good output:
 "Found the authentication system in src/auth/:
 - \`src/auth/provider.ts\` (lines 15-45): AuthProvider class handles JWT token validation
 - \`src/auth/middleware.ts\` (lines 8-20): Express middleware that checks auth headers
 - \`src/auth/hooks.ts\`: useAuth() hook used by React components
-The auth flow: middleware validates JWT \u2192 provider decodes token \u2192 user context set"
+The auth flow: middleware validates JWT -> provider decodes token -> user context set"
 
 ## Example bad output:
 "I searched for auth and found some files." (too vague, no paths, no details)
@@ -4993,14 +5012,10 @@ The Explore agent will explore the codebase and return a summary of findings.
 This is more thorough than a simple grep because it can follow references and understand context.
 It also has access to semantic search to find code by meaning, not just text.
 
-Examples:
-- "Find all React components that use the useState hook"
-- "Where is the authentication logic implemented?"
-- "Find all API routes and their handlers"
-- "Search for usages of the UserService class"`,
+CRITICAL: The explore agent has ZERO context. It cannot see the conversation, the user's message, devtools data, or any prior context. You MUST pass ALL relevant context via the "context" parameter. If the user selected a component (component name, file path, HTML, component stack) or there is a <devtools-context> block, you MUST copy that information into the "context" field verbatim. Without it the explore agent is searching blind.`,
     inputSchema: z10.object({
       query: z10.string().describe("What to search for. Be specific about what you're looking for."),
-      context: z10.string().optional().describe("Optional additional context about why you need this information.")
+      context: z10.string().describe("ALL context the explore agent needs. It has ZERO context on its own - no conversation history, no devtools data, nothing. You MUST include: any selected component info (name, file path, HTML, component stack), any <devtools-context> block (page URL, path, viewport), and any other relevant details from the user message. The explore agent literally only sees the query and this context field.")
     }),
     execute: async ({ query, context }, toolOptions) => {
       const toolCallId = toolOptions.toolCallId || `explore_agent_${Date.now()}`;
@@ -5328,6 +5343,11 @@ Use this proactively after making code changes to catch errors early.
 
 **Choose the right search approach:**
 
+0. **Use paths to your advantage \u2014 skip searching if you already have what you need.**
+   - If the user selected a component via devtools and you can see the component name, file path, and/or line number, you ALREADY know where the code is. Just use \`read_file\` to read that file directly \u2014 do NOT call \`explore_agent\` to "find" something you already have the location of.
+   - If you received a **page path** (e.g. \`/dashboard\`, \`/settings/profile\`), map it to the corresponding file in the project structure. In Next.js this means \`app/dashboard/page.tsx\`, \`app/settings/profile/page.tsx\`, etc. In other frameworks, check the routing convention (e.g. \`pages/\`, \`src/routes/\`). Use \`read_file\` on the mapped path directly.
+   - If the file path doesn't exist or \`read_file\` fails, fall back to grep to locate it (e.g. \`rg "ComponentName" --type ts -l\`) since devtools paths can sometimes be slightly off or truncated.
+   - Read up and down component trees when you have the file path or page path to find what you're looking for.
 1. **Use the \`explore_agent\` tool (Explore agent)** for:
    - Semantic/exploratory questions: "How does authentication work?", "Where is user data processed?"
    - Finding code by meaning or concept, not exact text
@@ -5337,6 +5357,13 @@ Use this proactively after making code changes to catch errors early.
    
    The Explore agent is a mini-agent that intelligently explores the codebase, reads relevant files, and returns a summary of what it found. It's best for understanding and discovery.
 
+   **MANDATORY \u2014 The Explore agent has ZERO context.** It cannot see the conversation, the user's messages, devtools data, or anything else. The \`query\` and \`context\` fields are the ONLY information it receives. Every time you call \`explore_agent\`, you MUST populate the \`context\` field with ALL relevant information:
+   - Copy the ENTIRE \`<devtools-context>\` block (page URL, path, viewport) if one exists in the user's message.
+   - Copy ALL selected component info (component name, file path, line number, HTML snippet, component stack) if the user selected something via devtools.
+   - Include any file paths, component names, or page names the user mentioned.
+   - If you skip the \`context\` field, the explore agent is searching completely blind and will waste time guessing.
+   - NEVER call \`explore_agent\` with only a \`query\` and no \`context\` when the user's message contains devtools or component information.
+
 2. **Use direct commands (grep/rg, find)** for:
    - Exact string matches: \`rg "functionName"\`, \`rg "class MyClass"\`
    - Finding files by name: \`find . -name "*.config.ts"\`
@@ -5344,7 +5371,8 @@ Use this proactively after making code changes to catch errors early.
    - Counting occurrences or listing all matches
 
 **Examples:**
-- "Where is the API authentication handled?" \u2192 Use \`explore_agent\` tool
+- User selected \`<LandingButton>\` at \`src/components/LandingButton.tsx:12\` \u2192 Just \`read_file("src/components/LandingButton.tsx")\`. Do NOT call explore_agent.
+- "Where is the API authentication handled?" (no file path given) \u2192 Use \`explore_agent\` tool
 - "Find all usages of getUserById" \u2192 Use \`rg "getUserById"\`
 - "How does the payment flow work?" \u2192 Use \`explore_agent\` tool
 - "Find files named config" \u2192 Use \`find . -name "*config*"\`