@kkelly-offical/kkcode 0.1.2

package/src/tool/image-util.mjs

@@ -0,0 +1,276 @@
+import { readFile, unlink, writeFile as fsWriteFile } from "node:fs/promises"
+import { access } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import path from "node:path"
+
+const execFileAsync = promisify(execFile)
+
+const IMAGE_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".svg"
+])
+
+const MIME_MAP = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml"
+}
+
+const MAX_IMAGE_SIZE = 20 * 1024 * 1024 // 20MB
+
+export function isImagePath(filePath) {
+  const ext = path.extname(String(filePath || "")).toLowerCase()
+  return IMAGE_EXTENSIONS.has(ext)
+}
+
+export function mimeType(filePath) {
+  const ext = path.extname(String(filePath || "")).toLowerCase()
+  return MIME_MAP[ext] || "application/octet-stream"
+}
+
+/**
+ * Extract image file references from user input text.
+ * Supports:
+ *   @path/to/image.png  (explicit file)
+ *   @https://example.com/image.png  (explicit URL)
+ *   Bare paths ending in image extensions
+ *   Bare http(s) URLs ending in image extensions
+ * Returns { text, imagePaths, imageUrls } where text has image refs removed.
+ */
+export function extractImageRefs(text, cwd = process.cwd()) {
+  const raw = String(text || "")
+  const imagePaths = []
+  const imageUrls = []
+
+  // Match @"url" or @url for http(s) URLs with image extensions
+  const atUrlPattern = /@"(https?:\/\/[^"]+\.(png|jpe?g|gif|webp|bmp|svg)(?:\?[^"]*)?)"|@(https?:\/\/\S+\.(png|jpe?g|gif|webp|bmp|svg)(?:\?\S*)?)/gi
+  let cleaned = raw.replace(atUrlPattern, (match, quoted, _e1, bare, _e2) => {
+    const ref = quoted || bare
+    if (ref) imageUrls.push(ref)
+    return ""
+  })
+
+  // Match @"path" or @path (with or without quotes) for local files
+  const atPattern = /@"([^"]+\.(png|jpe?g|gif|webp|bmp|svg))"|@(\S+\.(png|jpe?g|gif|webp|bmp|svg))/gi
+  cleaned = cleaned.replace(atPattern, (match, quoted, _e1, bare, _e2) => {
+    const ref = quoted || bare
+    if (ref) imagePaths.push(path.resolve(cwd, ref))
+    return ""
+  })
+
+  // Bare http(s) URLs ending in image extensions
+  const bareUrlPattern = /https?:\/\/\S+\.(png|jpe?g|gif|webp|bmp|svg)(?:\?\S*)?/gi
+  cleaned = cleaned.replace(bareUrlPattern, (match) => {
+    if (!imageUrls.includes(match)) imageUrls.push(match)
+    return ""
+  })
+
+  // Also detect bare absolute/relative paths ending in image extensions
+  const barePattern = /(?:(?:[A-Za-z]:[\\\/]|[.\/\\])[\w\-.\\/: ]*?\.(png|jpe?g|gif|webp|bmp|svg))/gi
+  cleaned = cleaned.replace(barePattern, (match) => {
+    const trimmed = match.trim()
+    if (trimmed && isImagePath(trimmed)) {
+      const resolved = path.resolve(cwd, trimmed)
+      if (!imagePaths.includes(resolved)) imagePaths.push(resolved)
+      return ""
+    }
+    return match
+  })
+
+  return {
+    text: cleaned.replace(/\s{2,}/g, " ").trim(),
+    imagePaths,
+    imageUrls
+  }
+}
+
+/**
+ * Read an image file and return a content block.
+ * Returns { type: "image", path, mediaType, data } or null on failure.
+ */
+export async function readImageAsBlock(filePath) {
+  try {
+    await access(filePath)
+    const buffer = await readFile(filePath)
+    if (buffer.length > MAX_IMAGE_SIZE) {
+      return { type: "text", text: `[image too large: ${filePath} (${Math.round(buffer.length / 1024 / 1024)}MB, max 20MB)]` }
+    }
+    const data = buffer.toString("base64")
+    const media = mimeType(filePath)
+    return {
+      type: "image",
+      path: filePath,
+      mediaType: media,
+      data
+    }
+  } catch (err) {
+    return { type: "text", text: `[image not found: ${filePath}]` }
+  }
+}
+
+/**
+ * Build content blocks from user text + image paths.
+ * Returns an array of content blocks suitable for message.content.
+ * If no images, returns the plain text string (backward compatible).
+ */
+/**
+ * Read an image from the system clipboard.
+ * Returns a content block { type: "image", mediaType, data } or null if no image.
+ * Supports Windows (PowerShell), macOS (pngpaste/osascript), Linux (xclip).
+ */
+export async function readClipboardImage({ onStatus } = {}) {
+  const tempPath = path.join(tmpdir(), `kkcode-clip-${Date.now()}.png`)
+  const status = typeof onStatus === "function" ? onStatus : () => {}
+
+  try {
+    if (process.platform === "win32") {
+      status("reading clipboard...")
+      // Use escaped path for PowerShell; try multiple clipboard formats
+      const psPath = tempPath.replace(/\\/g, "\\\\").replace(/'/g, "''")
+      const psScript = [
+        "Add-Type -AssemblyName System.Windows.Forms",
+        "Add-Type -AssemblyName System.Drawing",
+        `$outPath = '${psPath}'`,
+        "$img = [System.Windows.Forms.Clipboard]::GetImage()",
+        "if ($img) {",
+        "  $img.Save($outPath, [System.Drawing.Imaging.ImageFormat]::Png)",
+        "  Write-Output 'saved'",
+        "  exit",
+        "}",
+        // Fallback: try reading raw clipboard data stream (handles CF_DIB from some screenshot tools)
+        "$data = [System.Windows.Forms.Clipboard]::GetDataObject()",
+        "if ($data -and $data.GetDataPresent('PNG')) {",
+        "  $stream = $data.GetData('PNG')",
+        "  $fs = [System.IO.File]::Create($outPath)",
+        "  $stream.CopyTo($fs)",
+        "  $fs.Close()",
+        "  $stream.Close()",
+        "  Write-Output 'saved'",
+        "  exit",
+        "}",
+        "if ($data -and $data.GetDataPresent([System.Windows.Forms.DataFormats]::Bitmap)) {",
+        "  $bmp = $data.GetData([System.Windows.Forms.DataFormats]::Bitmap)",
+        "  if ($bmp) {",
+        "    $bmp.Save($outPath, [System.Drawing.Imaging.ImageFormat]::Png)",
+        "    Write-Output 'saved'",
+        "    exit",
+        "  }",
+        "}",
+        "Write-Output 'empty'"
+      ].join("\n")
+      const { stdout } = await execFileAsync("powershell", [
+        "-NoProfile", "-NonInteractive", "-Command", psScript
+      ], { timeout: 10000 })
+      if (!stdout.includes("saved")) {
+        status("")
+        return null
+      }
+    } else if (process.platform === "darwin") {
+      status("reading clipboard...")
+      try {
+        await execFileAsync("pngpaste", [tempPath], { timeout: 5000 })
+      } catch {
+        const script = `set theFile to POSIX file "${tempPath}"\ntry\n  set theImage to the clipboard as «class PNGf»\n  set fp to open for access theFile with write permission\n  write theImage to fp\n  close access fp\non error\n  return "empty"\nend try`
+        const { stdout } = await execFileAsync("osascript", ["-e", script], { timeout: 5000 })
+        if (stdout.includes("empty")) { status(""); return null }
+      }
+    } else {
+      status("reading clipboard...")
+      const result = await execFileAsync("xclip", [
+        "-selection", "clipboard", "-t", "image/png", "-o"
+      ], { timeout: 5000, maxBuffer: MAX_IMAGE_SIZE, encoding: "buffer" })
+      if (!result.stdout || !result.stdout.length) { status(""); return null }
+      await fsWriteFile(tempPath, result.stdout)
+    }
+
+    status("processing image...")
+    const block = await readImageAsBlock(tempPath)
+    await unlink(tempPath).catch(() => {})
+    status("")
+    return block && block.type === "image" ? block : null
+  } catch (err) {
+    await unlink(tempPath).catch(() => {})
+    status("")
+    return { type: "error", message: err.message || "clipboard read failed" }
+  }
+}
+
+/**
+ * Read text from the system clipboard.
+ * Returns string or null if clipboard is empty / not text.
+ */
+export async function readClipboardText() {
+  try {
+    if (process.platform === "win32") {
+      const { stdout } = await execFileAsync("powershell", [
+        "-NoProfile", "-NonInteractive", "-Command", "Get-Clipboard"
+      ], { timeout: 5000 })
+      return stdout || null
+    } else if (process.platform === "darwin") {
+      const { stdout } = await execFileAsync("pbpaste", [], { timeout: 5000 })
+      return stdout || null
+    } else {
+      // Try xclip first, fall back to xsel
+      try {
+        const { stdout } = await execFileAsync("xclip", [
+          "-selection", "clipboard", "-o"
+        ], { timeout: 5000 })
+        return stdout || null
+      } catch {
+        const { stdout } = await execFileAsync("xsel", [
+          "--clipboard", "--output"
+        ], { timeout: 5000 })
+        return stdout || null
+      }
+    }
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Fetch a remote image URL and return a content block.
+ * Returns { type: "image_url", url } for provider-native URL support,
+ * or fetches + base64-encodes as fallback.
+ */
+export async function fetchImageUrlAsBlock(url) {
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(15000) })
+    if (!response.ok) return { type: "text", text: `[image fetch failed: ${url} (${response.status})]` }
+    const contentType = response.headers.get("content-type") || ""
+    if (!contentType.startsWith("image/")) {
+      return { type: "text", text: `[not an image: ${url} (${contentType})]` }
+    }
+    const buffer = Buffer.from(await response.arrayBuffer())
+    if (buffer.length > MAX_IMAGE_SIZE) {
+      return { type: "text", text: `[image too large: ${url} (${Math.round(buffer.length / 1024 / 1024)}MB)]` }
+    }
+    return { type: "image", path: url, mediaType: contentType.split(";")[0], data: buffer.toString("base64") }
+  } catch (err) {
+    return { type: "text", text: `[image fetch error: ${url} — ${err.message}]` }
+  }
+}
+
+export async function buildContentBlocks(text, imagePaths = [], imageUrls = []) {
+  if (!imagePaths.length && !imageUrls.length) return text
+
+  const blocks = []
+  if (text) blocks.push({ type: "text", text })
+
+  for (const imgPath of imagePaths) {
+    const block = await readImageAsBlock(imgPath)
+    if (block) blocks.push(block)
+  }
+
+  for (const url of imageUrls) {
+    const block = await fetchImageUrlAsBlock(url)
+    if (block) blocks.push(block)
+  }
+
+  return blocks
+}

package/src/tool/prompt/background_cancel.txt

@@ -0,0 +1 @@
+Cancel a running background delegated task by `task_id`.

package/src/tool/prompt/background_output.txt

@@ -0,0 +1 @@
+Retrieve logs/result for a background delegated task by `task_id`.

package/src/tool/prompt/bash.txt

@@ -0,0 +1,71 @@
+Executes a shell command in the workspace directory with optional timeout.
+
+CRITICAL — tool selection rules. Do NOT use `bash` when a dedicated tool exists:
+- Read files → use `read` (NEVER cat/head/tail/type/Get-Content)
+- Search contents → use `grep` (NEVER bash grep/rg)
+- Find files → use `glob` (NEVER bash find/ls/dir)
+- Write files → use `write` (NEVER echo/cat heredoc)
+- Edit files → use `edit` (NEVER sed/awk)
+Only use `bash` for: git, npm, pip, docker, make, cargo, go, python, node, and other system commands.
+
+Parameters:
+- command (required): shell command to execute
+- timeout (optional): timeout in ms (default 120000, max 600000)
+- description (optional): human-readable description of what this command does. For simple commands keep it brief (5-10 words). For complex commands (piped commands, obscure flags), add enough context to clarify.
+- run_in_background (optional): run as background task, returns task_id immediately
+
+Rules:
+- Always quote file paths that contain spaces with double quotes.
+- NEVER run long-running/dev-server commands in foreground (npm run dev, jest --watch, webpack serve, nodemon, tsc --watch, etc.). Use run_in_background: true or tell user to run manually.
+- Use description to explain non-obvious commands.
+- When issuing multiple independent commands, make multiple bash calls in parallel.
+- When commands depend on each other, chain with && (e.g. `git add . && git commit -m "msg"`).
+- NEVER use interactive flags like -i (e.g. git rebase -i, git add -i) — they require interactive input which is not supported.
+
+# Committing changes with git
+
+Only create commits when requested by the user. If unclear, ask first. When creating a git commit:
+
+1. Run in parallel:
+   - `git status` (NEVER use -uall flag)
+   - `git diff` to see changes
+   - `git log --oneline -5` to follow commit message style
+
+2. Analyze changes and draft a concise commit message focusing on "why" not "what".
+   Do NOT commit files that likely contain secrets (.env, credentials.json, etc.).
+
+3. Stage and commit:
+   - Prefer `git add <specific-files>` over `git add -A` or `git add .`
+   - ALWAYS pass the commit message via a HEREDOC:
+     git commit -m "$(cat <<'EOF'
+     Commit message here.
+
+     Co-Authored-By: kkcode <noreply@kkcode.dev>
+     EOF
+     )"
+   - Run `git status` after commit to verify success
+
+4. Git safety rules:
+   - NEVER update git config
+   - NEVER run destructive commands (push --force, reset --hard, checkout ., clean -f, branch -D) unless user explicitly requests
+   - NEVER skip hooks (--no-verify) unless user explicitly requests
+   - NEVER force push to main/master — warn the user
+   - ALWAYS create NEW commits rather than amending, unless user explicitly asks for amend
+   - When a pre-commit hook fails, the commit did NOT happen — fix the issue, re-stage, create a NEW commit (do NOT --amend)
+   - NEVER commit unless the user explicitly asks
+
+# Creating pull requests
+
+When creating a PR:
+1. Run in parallel: git status, git diff, check remote tracking, git log + git diff <base>...HEAD
+2. Analyze ALL commits and draft PR title (under 70 chars) and summary
+3. Push and create PR:
+   gh pr create --title "title" --body "$(cat <<'EOF'
+   ## Summary
+   <1-3 bullet points>
+
+   ## Test plan
+   - [ ] testing checklist...
+   EOF
+   )"
+4. Return the PR URL

package/src/tool/prompt/codesearch.txt

@@ -0,0 +1,18 @@
+Search for code examples, API docs, and SDK usage via Exa AI.
+
+IMPORTANT — When to use PROACTIVELY (reduce hallucination):
+- Working with an unfamiliar library or framework
+- Need correct function signatures, parameter types, or return values
+- Looking for configuration examples or migration guides
+- Unsure about best practices for a specific tool or pattern
+
+Do NOT invent API signatures. Search first, then write code.
+
+Parameters:
+- query (required): describe what you need (e.g. "Express.js middleware error handling", "Prisma schema relations")
+- tokensNum (optional): context size 1000-50000 (default: 5000). Use higher for comprehensive docs, lower for quick lookups.
+
+Tips:
+- Be specific: "Next.js 14 app router server actions" > "Next.js server"
+- Include the language/framework name in the query
+- For debugging, include the error message or symptom

package/src/tool/prompt/edit.txt

@@ -0,0 +1,27 @@
+Performs exact string replacements in files. Transactional with automatic rollback on failure.
+
+Usage:
+- You must use `read` at least once before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from `read` output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + arrow (→). Everything after that arrow is the actual file content to match. Never include any part of the line number prefix in the `before` or `after` strings.
+- ALWAYS prefer editing existing files. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it.
+- The edit will FAIL if `before` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance.
+- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful for renaming a variable, function, or class.
+
+Parameters:
+- path (required): file path
+- before (required): exact text to find in the file
+- after (required): replacement text (must be different from before)
+- replace_all (optional, default false): replace all occurrences instead of requiring unique match
+
+When to use replace_all:
+- Renaming a variable, function, or class across a file
+- Changing an import path that appears multiple times
+- Updating a repeated pattern (e.g. changing all "http://" to "https://")
+
+Common mistakes and how to avoid them:
+- Editing without reading first → always `read` before `edit`
+- `before` too short, matches multiple locations → include surrounding lines for uniqueness
+- Stale content after failed edit → re-read the file, it may have changed
+- Including line number prefixes in `before` → only use actual file content, not the "     1→" prefix
+- Using `edit` for whole-file replacement → use `write` instead for complete rewrites

package/src/tool/prompt/enter_plan.txt

@@ -0,0 +1,74 @@
+Enter planning mode before implementing non-trivial tasks. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment.
+
+## When to Use — call enter_plan PROACTIVELY when ANY of these apply:
+
+1. **New Feature Implementation**: Adding meaningful new functionality
+   - Example: "Add a logout button" — where should it go? What should happen on click?
+   - Example: "Add form validation" — what rules? What error messages?
+
+2. **Multiple Valid Approaches**: The task can be solved in several different ways
+   - Example: "Add caching to the API" — could use Redis, in-memory, file-based, etc.
+   - Example: "Improve performance" — many optimization strategies possible
+
+3. **Code Modifications**: Changes that affect existing behavior or structure
+   - Example: "Update the login flow" — what exactly should change?
+   - Example: "Refactor this component" — what's the target architecture?
+
+4. **Architectural Decisions**: The task requires choosing between patterns or technologies
+   - Example: "Add real-time updates" — WebSockets vs SSE vs polling
+   - Example: "Implement state management" — Redux vs Context vs custom solution
+
+5. **Multi-File Changes**: The task will likely touch more than 2-3 files
+   - Example: "Refactor the authentication system"
+   - Example: "Add a new API endpoint with tests"
+
+6. **Unclear Requirements**: You need to explore before understanding the full scope
+   - Example: "Make the app faster" — need to profile and identify bottlenecks
+   - Example: "Fix the bug in checkout" — need to investigate root cause
+
+7. **User Preferences Matter**: The implementation could reasonably go multiple ways.
+   If you would use `question` to clarify the approach, use enter_plan instead — it lets you explore first, then present options with context.
+
+## When NOT to Use
+
+Only skip enter_plan for simple tasks:
+- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
+- Adding a single function with clear requirements
+- Tasks where the user has given very specific, detailed instructions
+- Pure research/exploration tasks (use `task` with explore subagent instead)
+
+<example>
+GOOD — Use enter_plan:
+User: "Add user authentication to the app"
+→ Requires architectural decisions (session vs JWT, storage, middleware)
+
+User: "Optimize the database queries"
+→ Multiple approaches possible, need to profile first
+
+User: "Add a delete button to the user profile"
+→ Involves placement, confirmation dialog, API call, error handling, state updates
+
+User: "Update the error handling in the API"
+→ Affects multiple files, user should approve the approach
+</example>
+
+<example>
+BAD — Don't use enter_plan:
+User: "Fix the typo in the README"
+→ Straightforward, no planning needed
+
+User: "Add a console.log to debug this function"
+→ Simple, obvious implementation
+
+User: "What files handle routing?"
+→ Research task, not implementation planning
+</example>
+
+## After calling enter_plan:
+
+1. Thoroughly explore the codebase using `glob`, `grep`, and `read`
+2. Understand existing patterns and architecture
+3. Design an implementation approach
+4. Present your plan with `exit_plan` for user approval
+5. Use `question` if you need to clarify approaches DURING planning
+6. Wait for approval before making any code changes

package/src/tool/prompt/exit_plan.txt

@@ -0,0 +1,62 @@
+Present your completed plan to the user for approval. The user will see the plan and can approve, reject, or request changes.
+
+## How This Tool Works
+- You should have already outlined your plan in your text response after calling enter_plan
+- This tool submits the plan for user review
+- The user will see the plan content and the list of files affected
+
+## When to Use
+IMPORTANT: Only use this tool when planning implementation steps for a task that requires writing code.
+For research tasks where you're gathering information, searching files, or understanding the codebase — do NOT use this tool.
+
+## Before Using This Tool
+Ensure your plan is complete and unambiguous:
+- If you have unresolved questions about requirements or approach, use `question` first
+- Once your plan is finalized, use THIS tool to request approval
+- Do NOT use `question` to ask "Is this plan okay?" — that's exactly what exit_plan does
+
+## Requirements
+- You MUST have called enter_plan first
+- Your plan must be complete and specific — include file paths, function names, and concrete changes
+- Include ALL files that will be created or modified in the `files` parameter
+
+## Parameters
+- plan (required): the complete plan text to present to the user
+- files (optional): array of file paths that will be created or modified
+
+## User Response
+The user will:
+- Approve: you proceed with implementation
+- Reject: you receive their feedback and should revise
+- Provide custom feedback: treat as rejection with specific guidance
+
+## Examples
+
+<good-example>
+# Complete plan with structure
+plan:
+## Context
+Adding dark mode toggle to the settings page.
+
+## Approach
+Use CSS custom properties for theme switching with React Context for state management.
+
+## Files to modify
+- src/contexts/ThemeContext.tsx — new context provider
+- src/components/Settings/ThemeToggle.tsx — new toggle component
+- src/styles/variables.css — add dark theme variables
+- src/App.tsx — wrap with ThemeProvider
+
+## Verification
+- Toggle switches theme visually
+- Theme persists across page refresh (localStorage)
+- All existing tests still pass
+</good-example>
+<bad-example>
+# Plan too vague — no files, no specifics
+plan: "I'll add dark mode by creating some components and updating styles"
+</bad-example>
+
+IMPORTANT:
+- Do NOT start implementation before receiving approval
+- If rejected, address the user's feedback and submit a revised plan

package/src/tool/prompt/glob.txt

@@ -0,0 +1,33 @@
+Fast file pattern matching tool that works with any codebase size.
+Supports glob patterns like "**/*.js" or "src/**/*.ts".
+Returns matching file paths sorted by name, limited to 200 results.
+ALWAYS use `glob` instead of `bash` with find/ls/dir.
+
+Parameters:
+- pattern (required): glob pattern to match files against
+- path (optional): directory to search in (default: cwd). Use this to limit search to a subdirectory.
+
+Examples:
+- "**/*.mjs" — all .mjs files recursively
+- "src/**/*.ts" — TypeScript files under src/
+- "*.json" — JSON files in root only
+- "src/components/**" — everything under components/
+- pattern="**/*.test.mjs" path="src/tool/" — test files under src/tool/
+
+## When NOT to Use
+- Do NOT use glob to search file *contents* — use `grep` for that.
+- Do NOT use glob when you need a simple directory listing — use `bash` with `ls` only if truly needed.
+- Do NOT use glob to find a file when you already know its exact path — use `read` directly.
+- If you need to search both file names AND contents, use glob for names and grep for contents in parallel.
+
+Tips:
+- When doing an open-ended search that may require multiple rounds of globbing and grepping, use the `task` tool with explore subagent instead.
+- You can call multiple glob tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.
+- Use `path` parameter to narrow search to a specific directory for faster results.
+- When unsure of exact file naming convention, launch multiple speculative globs in parallel:
+  <good-example>
+  # Looking for config files — try multiple patterns at once:
+  glob "**/*.config.{js,ts,mjs}"
+  glob "**/config.{js,ts,mjs,json}"
+  glob "**/.{eslint,prettier,babel}*"
+  </good-example>

package/src/tool/prompt/grep.txt

@@ -0,0 +1,43 @@
+Search file contents by regex pattern across the project.
+ALWAYS use `grep` instead of `bash` with grep/rg.
+Supports full regex syntax (e.g. "log.*Error", "function\\s+\\w+").
+
+Parameters:
+- pattern (required): regex or literal string to search for
+- path (optional): file or directory to search in (default: cwd). Use this to search within a specific file or subdirectory.
+- output_mode (optional): "content" (matching lines with line numbers), "files" (file paths only, default), "count" (match counts per file)
+- type (optional): file type filter — js, ts, py, go, rs, etc. More efficient than glob for standard types.
+- glob (optional): glob filter — "*.mjs", "src/**/*.ts"
+- context (optional): lines of context around each match (-C)
+- before_context (optional): lines before each match (-B)
+- after_context (optional): lines after each match (-A)
+- ignoreCase (optional): case-insensitive search
+- maxCount (optional): max matches per file
+- multiline (optional): enable cross-line matching. By default patterns match within single lines only. Use for patterns like "struct \\{[\\s\\S]*?field" that span multiple lines.
+- head_limit (optional): limit output to first N lines/entries. Works across all output modes.
+- offset (optional): skip first N lines/entries before applying head_limit. Combine with head_limit for paginated browsing.
+
+## When NOT to Use
+- Do NOT use grep to find files by *name* — use `glob` for that.
+- Do NOT use grep to read a whole file — use `read` instead.
+- Do NOT use grep when you already know the exact file and line — use `read` with offset/limit.
+- For open-ended exploration requiring multiple search rounds, use `task` with explore subagent.
+
+Tips:
+- Use `path` to search within a specific file: grep pattern="TODO" path="src/main.mjs"
+- Use `path` to search a directory: grep pattern="import" path="src/utils/"
+- Use output_mode "files" for quick file discovery, "content" for understanding code
+- Use multiline to match patterns spanning multiple lines
+- Combine head_limit + offset for paginated browsing of large result sets:
+  <example>
+  # Page 1: first 20 matches
+  grep pattern="TODO" output_mode="content" head_limit=20
+  # Page 2: next 20 matches
+  grep pattern="TODO" output_mode="content" head_limit=20 offset=20
+  </example>
+- Pattern syntax uses ripgrep — literal braces need escaping (use "interface\\{\\}" to find "interface{}" in Go)
+
+## Using grep with patch/edit:
+- Use output_mode="content" to see line numbers alongside matches.
+- Line numbers from grep correspond directly to `read` (offset/limit) and `patch` (start_line/end_line).
+- Workflow: grep to find location → read surrounding context → patch or edit the section.

package/src/tool/prompt/list.txt

@@ -0,0 +1,8 @@
+List files and subdirectories in a single directory level.
+Returns entries with type prefix: d=directory, f=file.
+
+Use `list` for quick directory overview (what's in this folder?).
+Use `glob` for recursive pattern matching across the project (find all *.ts files).
+Use `grep` to search file contents by pattern.
+
+Do NOT use `bash` with ls or find — use `list` or `glob` instead.

package/src/tool/prompt/multiedit.txt

@@ -0,0 +1,20 @@
+Apply multiple file edits in a single atomic operation.
+All changes succeed together or are rolled back entirely — no half-applied states.
+
+When to use (instead of sequential `edit` calls):
+- Renaming an export and updating all its import sites
+- Refactoring a function signature and all call sites
+- Moving code between files (delete from one, add to another)
+- Any change where partial application would break the codebase
+
+Parameters:
+- changes (required): array of file operations:
+  - path: file path
+  - before: text to find (omit to create a new file)
+  - after: replacement text (for edits) or full content (for new files)
+  - replace_all: replace all occurrences of `before` (default: false)
+
+Rules:
+- You MUST `read` each file before editing it (same as `edit` tool).
+- If any change fails validation (no match, ambiguous match), the entire batch is rejected before any writes.
+- On write failure mid-batch, all previously applied changes are rolled back.

package/src/tool/prompt/notebookedit.txt

@@ -0,0 +1,21 @@
+Edit a Jupyter notebook (.ipynb) cell. Supports replace, insert, and delete operations.
+
+Parameters:
+- path (required): absolute or relative path to the .ipynb file
+- cell_number (optional): 0-indexed cell number to operate on (default: 0)
+- new_source (required): new cell source content (ignored for delete)
+- cell_type (optional): "code" or "markdown" — required for insert, defaults to existing cell type for replace
+- edit_mode (optional): "replace" (default), "insert", or "delete"
+
+Operations:
+- replace: Replace the source of cell at cell_number with new_source. Preserves cell type unless cell_type is specified.
+- insert: Insert a new cell AFTER cell_number. cell_type is required. If cell_number is -1, inserts at the beginning.
+- delete: Remove the cell at cell_number. new_source is ignored but must be provided.
+
+IMPORTANT:
+- The notebook must be a valid .ipynb JSON file with a "cells" array.
+- cell_number is 0-indexed. The first cell is 0, second is 1, etc.
+- For insert mode, cell_type must be specified ("code" or "markdown").
+- Cell outputs are preserved during replace; cleared only if cell_type changes to "markdown".
+- When inserting code cells, outputs default to an empty array.
+- This tool reads the notebook, modifies the cells array, and writes it back atomically.