thincoder 0.2.0 → 0.4.0

package/src/coder-overlay.md

@@ -0,0 +1,14 @@
+You are a coding subagent. The parent agent dispatched you to handle a self-contained coding task. The parent CANNOT see your context — it only sees your final report.
+
+Guidelines:
+- Work independently: read files, make edits, run tests
+- Be thorough: include what you did, which files you changed, why, and any caveats
+- If the task is ambiguous, note the ambiguity in your report; do not ask the user
+- BEFORE finishing, verify your changes:
+  1. Run the project's tests — confirm they pass
+  2. Read every file you changed — catch leftover debug code, stale comments, or incomplete edits
+  3. Check that comments and docstrings match what the code actually does
+- Your last message IS the report the parent sees — make it complete and self-contained
+- List every file you changed (with paths), why you changed it, and whether tests passed
+
+IMPORTANT — Tool permissions: when you see "permission denied by user" for a tool, it means the parent has not granted that tool. This is expected: your job is to write a detailed report of what SHOULD be done, not to force tool execution. Describe the needed changes clearly in your report so the parent agent can apply them.

package/src/config.mjs

@@ -27,7 +27,7 @@ const DEFAULTS = {
   providers: [{ name: "deepseek", ...deepseekPreset }],
   activeProvider: "deepseek",
   agent: {
-    maxTurns: 50,
+    maxTurns: 100,
     compactThreshold: 100000,
   },
   memory: {
@@ -39,6 +39,9 @@ const DEFAULTS = {
     baseURL: "https://api.siliconflow.cn/v1",
     model: "BAAI/bge-m3",
   },
+  mcp: {
+    servers: [],
+  },
 }
 
 /**
@@ -60,7 +63,9 @@ const MODEL_CONTEXT_WINDOWS = [
   ["qwen", 128_000],
 ]
 const DEFAULT_CONTEXT_WINDOW = 128_000
-const COMPACT_RATIO = 0.6
+// 窗口利用率上限：0.8（DeepSeek 内部即全窗口；压缩本身要花一次 LLM 调用，过早压缩是纯浪费。
+// 留 20% 余量给压缩后的尾部增长与输出 token）
+const COMPACT_RATIO = 0.8
 
 export function contextWindowForModel(model) {
   const m = (model ?? "").toLowerCase()
@@ -133,10 +138,15 @@ export function loadConfig() {
   if (process.env.THINCODER_BASE_URL) runtimeProvider.baseURL = process.env.THINCODER_BASE_URL
   if (process.env.THINCODER_MODEL) runtimeProvider.model = process.env.THINCODER_MODEL
 
-  // apiKey 还可用通用环境变量兜底（当 providers 里没配 key 时）
+  // apiKey 还可用环境变量兜底（当 providers 里没配 key 时）
+  // 提供商专用的环境变量只对同名 provider 生效，避免 key 串到错误的端点
+  if (!runtimeProvider.apiKey) {
+    const envMap = { deepseek: "DEEPSEEK_API_KEY", openai: "OPENAI_API_KEY" }
+    const keyVar = envMap[merged.activeProvider]
+    if (keyVar && process.env[keyVar]) runtimeProvider.apiKey = process.env[keyVar]
+  }
   if (!runtimeProvider.apiKey) {
-    runtimeProvider.apiKey =
-      process.env.THINCODER_API_KEY || process.env.DEEPSEEK_API_KEY || process.env.OPENAI_API_KEY
+    runtimeProvider.apiKey = process.env.THINCODER_API_KEY
   }
 
   // embedding apiKey

package/src/context.mjs

@@ -6,11 +6,12 @@
 
 import { chat } from "./provider.mjs"
 
-/** 粗估一组消息的 token 数（正文 + tool_calls 参数） */
+/** 粗估一组消息的 token 数（正文 + 思考链 + tool_calls 参数） */
 export function estimateTokens(messages) {
   let chars = 0
   for (const m of messages) {
     if (typeof m.content === "string") chars += m.content.length
+    if (typeof m.reasoning_content === "string") chars += m.reasoning_content.length
     for (const tc of m.tool_calls ?? []) {
       chars += (tc.function?.name?.length ?? 0) + (tc.function?.arguments?.length ?? 0)
     }
@@ -30,9 +31,16 @@ const SUMMARIZE_PROMPT = `你是一个对话压缩器。把下面的 agent 工
 工作记录：
 `
 
+/** 压缩后的上下文前缀，告知 agent 发生了什么 */
+const COMPACTION_PREFIX =
+  "[Context was automatically compacted. Below is a summary of earlier work. " +
+  "Trust its conclusions — don't redo what it reports as done — but re-verify " +
+  "transient state (open files, running processes) with tools.]\n\n"
+
 /**
  * 如果历史超长则压缩。返回是否发生了压缩。
  * 只在循环的安全点调用（history 末尾是 user 消息时）。
+ * 压缩后自动回注 task 列表状态。
  */
 export async function compressIfNeeded(agent, threshold) {
   const history = agent.history
@@ -63,14 +71,41 @@ export async function compressIfNeeded(agent, threshold) {
     messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
   })
 
+  // 摘要正文内嵌 task 快照（对齐 kimi-code 的 postProcessSummary）——
+  // 否则二次压缩时 task 列表会随旧提醒消息一起被摘要器丢掉
+  let compacted = COMPACTION_PREFIX + summary.content
+  if (agent.tasks.length > 0) {
+    const taskSummary = agent.tasks.map((t) => `- [${t.status}] ${t.title}`).join("\n")
+    compacted += `\n\n## Task List\n${taskSummary}`
+  }
+
   agent.history = [
     ...head,
-    {
-      role: "user",
-      content: `[前文摘要：以下是更早对话的压缩记录]\n${summary.content}`,
-    },
-    { role: "assistant", content: "了解，我会基于这份摘要和最近的对话继续工作。" },
+    { role: "user", content: compacted },
+    { role: "assistant", content: "Understood. I'll continue from this summary, re-verifying anything transient." },
     ...tail,
   ]
+
+  // 压缩后回注 task 列表（agent 需要知道自己做到哪了）
+  if (agent.tasks.length > 0) {
+    const taskSummary = agent.tasks.map((t) => `- [${t.status}] ${t.title}`).join("\n")
+    agent.history.push({
+      role: "user",
+      content: `[System reminder: your current task list after compaction:\n${taskSummary}\nContinue from where you left off.]`,
+    })
+  }
+
+  // 重置跟踪计数器（上下文已重建，从头开始计数）
+  agent._turnsSinceTaskUpdate = 0
+  agent._turnsInPlanMode = 0
+
+  // plan mode 中压缩：重新注入 plan 模式引导
+  if (agent.planMode) {
+    agent.history.push({
+      role: "user",
+      content: "[System reminder: plan mode is active. Explore the codebase read-only, design your solution, then call plan with action='exit' to present it for user approval.]",
+    })
+  }
+
   return true
 }

package/src/explore-overlay.md

@@ -0,0 +1,10 @@
+You are a codebase exploration specialist — an explore subagent. Your role is to search, read, and analyze. You do NOT have file editing tools.
+
+Guidelines:
+- On start, quickly orient yourself: run `git branch --show-current`, `git status --short`, and `git log -5 --oneline` to understand the repo state
+- Use Glob for file discovery, Grep for content search, Read for known paths
+- Run read-only shell commands (git log, git diff, ls, find) when helpful
+- Use WebSearch or Fetch when external context is needed (docs, error messages)
+- Issue parallel tool calls whenever possible — read multiple files at once
+- Complete the search efficiently and report findings in a structured format
+- If something is ambiguous, note it in your report; do not ask the user

package/src/mcp.mjs

@@ -0,0 +1,359 @@
+/**
+ * mcp.mjs — MCP (Model Context Protocol) client
+ * 零依赖：stdio transport (spawn + JSON-RPC) + HTTP transport (fetch + SSE)。
+ * config: { command, args?, name } 或 { url, name, headers? }
+ */
+
+import { spawn } from "node:child_process"
+
+const INIT_TIMEOUT_MS = 30_000
+const CALL_TIMEOUT_MS = 120_000
+
+// ---- JSON-RPC helpers ----
+
+let nextRpcId = 0
+function rpcId() {
+  return String(++nextRpcId) // 自增：随机数可能碰撞串响应
+}
+
+// ---- stdio transport ----
+
+function stdioTransport(command, args) {
+  // Windows 上 npx 等命令是 .cmd，Node 不带 shell 拒 spawn（EINVAL）；
+  // shell:true 又触发 DEP0190 且不转义参数——显式走 cmd.exe 并自己加引号；
+  // windowsVerbatimArguments 防止 Node 把内层引号转义成 \"（cmd 不认，会把引号当字面量传下去）
+  const spawnOptions = { stdio: ["pipe", "pipe", "pipe"], windowsHide: true, env: { ...process.env } }
+  const child =
+    process.platform === "win32" && !/\.exe$/i.test(command)
+      ? spawn("cmd.exe", ["/d", "/s", "/c", [command, ...(args ?? [])].map(quoteArg).join(" ")], {
+          ...spawnOptions,
+          windowsVerbatimArguments: true,
+        })
+      : spawn(command, args ?? [], spawnOptions)
+
+  const pending = new Map()
+  let buffer = ""
+  let stderrTail = "" // 诊断用：server 起不来时给用户一点线索
+  let spawnError = null
+  let closed = false
+
+  const failAll = (message) => {
+    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message } })
+    pending.clear()
+  }
+
+  child.stdout.on("data", (chunk) => {
+    buffer += typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk)
+    const lines = buffer.split("\n")
+    buffer = lines.pop() ?? ""
+    for (const line of lines) {
+      if (!line.trim()) continue
+      try {
+        const msg = JSON.parse(line)
+        const resolver = pending.get(msg.id)
+        if (resolver) {
+          pending.delete(msg.id)
+          resolver(msg)
+        }
+      } catch {
+        // 非 JSON 行忽略
+      }
+    }
+  })
+
+  child.stderr.on("data", (chunk) => {
+    stderrTail = (stderrTail + chunk.toString()).slice(-2000)
+  })
+
+  // spawn 失败（命令不存在/EINVAL）：没有这个监听，error 事件会崩掉整个进程
+  child.on("error", (error) => {
+    spawnError = error
+    closed = true
+    failAll(`spawn failed: ${error.message}`)
+  })
+
+  child.on("close", () => {
+    closed = true
+    const lastLine = stderrTail.trim().split("\n").pop()
+    failAll(`Connection closed${lastLine ? ` | stderr: ${lastLine}` : ""}`)
+  })
+
+  const send = (method, params) => {
+    if (spawnError) return Promise.resolve({ id: null, error: { code: -32000, message: `spawn failed: ${spawnError.message}` } })
+    if (closed) return Promise.reject(new Error("MCP connection closed"))
+    const id = rpcId()
+    const promise = new Promise((resolve) => pending.set(id, resolve))
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n")
+    return withTimeout(promise, CALL_TIMEOUT_MS).finally(() => pending.delete(id))
+  }
+
+  // notification：无 id，不期待响应（协议要求）
+  const notify = (method, params) => {
+    if (!closed) child.stdin.write(JSON.stringify({ jsonrpc: "2.0", method, params }) + "\n")
+  }
+
+  return { send, notify, close: () => { if (!closed) child.kill() } }
+}
+
+// ---- HTTP + SSE transport (Streamable HTTP) ----
+
+function httpTransport(baseURL, extraHeaders = {}) {
+  const url = baseURL.replace(/\/+$/, "")
+  let sessionId = null
+  let closed = false
+  let eventSource = null
+  let abortController = null
+
+  const headers = () => {
+    const h = { "Content-Type": "application/json", Accept: "text/event-stream, application/json", ...extraHeaders }
+    if (sessionId) h["Mcp-Session-Id"] = sessionId
+    return h
+  }
+
+  const pending = new Map()
+
+  // SSE 解析器：从 response body 逐行读，处理 data: / event: / id: / 空行(dispatch)
+  async function* parseSSE(response) {
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buf = ""
+    let current = { data: "", event: "message" }
+    try {
+      while (true) {
+        const { done, value } = await reader.read()
+        if (done) break
+        buf += decoder.decode(value, { stream: true })
+        const lines = buf.split("\n")
+        buf = lines.pop() ?? ""
+        for (const raw of lines) {
+          const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw
+          if (line === "") {
+            if (current.data) {
+              yield { event: current.event, data: current.data.trimEnd() }
+              current = { data: "", event: "message" }
+            }
+          } else if (line.startsWith("data:")) {
+            current.data += (current.data ? "\n" : "") + line.slice(5).replace(/^ /, "")
+          } else if (line.startsWith("event:")) {
+            current.event = line.slice(6).trim()
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock()
+    }
+  }
+
+  // 打开 SSE 长连接（用于接收服务端推送）
+  async function openSSE() {
+    if (closed) return
+    abortController?.abort()
+    abortController = new AbortController()
+    const resp = await fetch(url + "/sse", {
+      method: "GET",
+      headers: { Accept: "text/event-stream" },
+      signal: abortController.signal,
+    })
+    if (!resp.ok) throw new Error(`SSE connect failed: HTTP ${resp.status}`)
+    eventSource = parseSSE(resp)
+
+    // 后台消费 SSE 事件并分发到 pending
+    ;(async () => {
+      try {
+        for await (const { data } of eventSource) {
+          if (closed) break
+          try {
+            const msg = JSON.parse(data)
+            const resolver = pending.get(msg.id)
+            if (resolver) {
+              pending.delete(msg.id)
+              resolver(msg)
+            }
+            // 没有 pending resolver 的可能是通知，忽略
+          } catch { /* 非 JSON，忽略 */ }
+        }
+      } catch (error) {
+        if (!closed) {
+          for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: `SSE error: ${error.message}` } })
+        }
+      }
+    })()
+  }
+
+  // POST JSON-RPC 请求，同时监听响应
+  async function postRequest(method, params) {
+    const id = rpcId()
+    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params })
+
+    // 如果有活跃的 SSE 连接，服务器会通过 SSE 推回响应
+    if (eventSource) {
+      return new Promise((resolve) => {
+        pending.set(id, resolve)
+        fetch(url + "/messages", { method: "POST", headers: headers(), body, signal: AbortSignal.timeout(CALL_TIMEOUT_MS) })
+          .catch((e) => {
+            pending.delete(id)
+            resolve({ id, error: { code: -32000, message: `POST failed: ${e.message}` } })
+          })
+      })
+    }
+
+    // 没有 SSE：纯 HTTP POST，响应就是 JSON-RPC
+    const resp = await fetch(url + "/messages", {
+      method: "POST",
+      headers: headers(),
+      body,
+      signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+    })
+    if (!resp.ok) throw new Error(`HTTP ${resp.status}`)
+
+    const ct = resp.headers.get("content-type") ?? ""
+    const newSessionId = resp.headers.get("Mcp-Session-Id")
+    if (newSessionId) sessionId = newSessionId
+
+    if (ct.includes("text/event-stream")) {
+      // 服务器返回 SSE：第一个事件是响应
+      const sse = parseSSE(resp)
+      for await (const { data } of sse) {
+        try {
+          const msg = JSON.parse(data)
+          if (msg.id === id) return msg
+          // 可能是通知
+        } catch { /* skip */ }
+      }
+      return { id, error: { code: -32000, message: "No JSON-RPC response in SSE stream" } }
+    }
+
+    // 纯 JSON 响应
+    return resp.json()
+  }
+
+  const send = async (method, params) => withTimeout(postRequest(method, params), CALL_TIMEOUT_MS)
+
+  // notification：无 id，不期待响应（协议要求）
+  const notify = (method, params) => {
+    fetch(url + "/messages", {
+      method: "POST",
+      headers: headers(),
+      body: JSON.stringify({ jsonrpc: "2.0", method, params }),
+      signal: AbortSignal.timeout(10_000),
+    }).catch(() => {})
+  }
+
+  const close = () => {
+    closed = true
+    abortController?.abort()
+    for (const [, resolve] of pending) resolve({ id: null, error: { code: -32000, message: "Connection closed" } })
+    pending.clear()
+  }
+
+  return { send, notify, close, openSSE, url, headers: extraHeaders }
+}
+
+// ---- MCP lifecycle ----
+
+function buildTools(mcpTools, transport, config) {
+  const prefix = config.name ? `${config.name}_` : "mcp_"
+  return mcpTools.map((t) => ({
+    name: prefix + sanitizeToolName(t.name),
+    description: t.description ?? `MCP tool: ${t.name}`,
+    parameters: t.inputSchema ?? { type: "object", properties: {} },
+    readonly: false,
+    async execute(args) {
+      const resp = await transport.send("tools/call", { name: t.name, arguments: args })
+      if (resp.error) throw new Error(`MCP tool "${t.name}": ${resp.error.message}`)
+      const content = resp.result?.content ?? []
+      return content
+        .map((c) => (c.type === "text" ? c.text : c.type === "resource" ? `[resource: ${c.resource?.uri}]` : JSON.stringify(c)))
+        .join("\n") || "(no output)"
+    },
+    _mcpTransport: transport,
+    _mcpName: config.name,
+  }))
+}
+
+async function doInitialize(transport, name) {
+  const initResp = await withTimeout(
+    transport.send("initialize", {
+      protocolVersion: "2024-11-05",
+      capabilities: {},
+      clientInfo: { name: "thincoder", version: "1.0.0" },
+    }),
+    INIT_TIMEOUT_MS,
+  )
+  if (initResp.error) throw new Error(`initialize error: ${initResp.error.message}`)
+  transport.notify?.("notifications/initialized", {})
+
+  const toolsResp = await transport.send("tools/list", {})
+  if (toolsResp.error) throw new Error(`tools/list failed: ${toolsResp.error.message}`)
+  return toolsResp.result?.tools ?? []
+}
+
+/**
+ * 连接一个 MCP server。
+ * stdio: { name, command, args? }
+ * http:  { name, url, headers? }
+ */
+export async function connectMcpServer(config) {
+  if (config.url) {
+    const transport = httpTransport(config.url, config.headers ?? {})
+    try {
+      await transport.openSSE()
+    } catch {
+      // 不支持 GET /sse 的 server（纯 Streamable HTTP POST）：降级为无 SSE 模式
+    }
+    const mcpTools = await doInitialize(transport, config.name ?? config.url)
+    return buildTools(mcpTools, transport, config)
+  }
+
+  if (config.command) {
+    const transport = stdioTransport(config.command, config.args ?? [])
+    try {
+      const mcpTools = await doInitialize(transport, config.name ?? config.command)
+      return buildTools(mcpTools, transport, config)
+    } catch (error) {
+      transport.close()
+      throw error
+    }
+  }
+
+  throw new Error(`MCP server "${config.name}": needs either 'command' (stdio) or 'url' (http)`)
+}
+
+export function closeAllMcp(agent) {
+  for (const t of agent.tools) {
+    if (t._mcpTransport) t._mcpTransport.close()
+  }
+}
+
+export function removeMcpTools(agent, serverName) {
+  const keep = []
+  for (const t of agent.tools) {
+    if (t._mcpName === serverName) {
+      if (t._mcpTransport) t._mcpTransport.close()
+    } else {
+      keep.push(t)
+    }
+  }
+  agent.tools = keep
+}
+
+// ---- helpers ----
+
+function sanitizeToolName(name) {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 64)
+}
+
+/** cmd.exe 参数加引号（含空格/引号时） */
+function quoteArg(s) {
+  return /[\s"]/.test(s) ? `"${s.replace(/"/g, '\\"')}"` : s
+}
+
+function withTimeout(promise, ms) {
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms)
+    timer.unref?.() // 不拖住进程退出
+  })
+  // 竞速结束后清掉定时器，不留垃圾
+  return Promise.race([promise.finally(() => clearTimeout(timer)), timeout])
+}

package/src/session.mjs

@@ -23,6 +23,8 @@ export function saveSession(agent) {
     updatedAt: Date.now(),
     history: agent.history,
     tasks: agent.tasks ?? [],
+    planMode: agent.planMode ?? false,
+    goal: agent.goal ?? null,
   }
   const p = sessionPath(agent.cwd)
   mkdirSync(dirname(p), { recursive: true })

package/src/skills.mjs

@@ -0,0 +1,75 @@
+/**
+ * skills.mjs — 技能系统
+ * 从 .thincoder/skills/ 目录发现 .md 技能文件，
+ * 注入到 system prompt 供 agent 按需加载。
+ * 用 skill 工具激活指定技能，内容以 <skill-loaded> 包裹写入对话历史。
+ */
+
+import { readFile, readdir, stat } from "node:fs/promises"
+import { join } from "node:path"
+
+/**
+ * 扫描 .thincoder/skills/ 目录，返回技能列表。
+ * 每个技能：{ name, path, description } — name 取文件名（去扩展名）。
+ * 目录不存在或无文件返回空数组。
+ */
+export async function loadSkills(cwd) {
+  const dir = join(cwd, ".thincoder", "skills")
+  let entries
+  try {
+    entries = await readdir(dir)
+  } catch {
+    return []
+  }
+  const skills = []
+  for (const name of entries) {
+    if (!/^[a-zA-Z0-9_-]+\.md$/.test(name)) continue // 与 readSkill 的名字校验一致，防"列得出、读不了"
+    const p = join(dir, name)
+    try {
+      const s = await stat(p)
+      if (!s.isFile()) continue
+      // 提取描述（前 400 字符里第一段非空、非标题行）
+      const head = await readFile(p, "utf8")
+      const body = head.slice(0, 400).split("\n")
+      let desc = ""
+      for (const line of body) {
+        const t = line.trim()
+        if (t && !t.startsWith("#") && !t.startsWith("---")) {
+          desc = t.slice(0, 120)
+          break
+        }
+      }
+      skills.push({ name: name.replace(/\.md$/, ""), path: p, description: desc || "(no description)" })
+    } catch {
+      // 读失败跳过
+    }
+  }
+  return skills
+}
+
+/**
+ * 生成技能列表文本，注入 system prompt。
+ * 最多 3 个（占位少），超过则标 "... and N more"。
+ */
+export function formatSkillListing(skills) {
+  if (skills.length === 0) return ""
+  const listed = skills.slice(0, 3)
+  const lines = listed.map((s) => `- **${s.name}**: ${s.description}`)
+  if (skills.length > 3) lines.push(`  ... and ${skills.length - 3} more`)
+  return "Available skills (use the skill tool to load one):\n" + lines.join("\n")
+}
+
+/**
+ * 读取指定技能文件的完整内容。
+ * 返回文本，找不到返回 null。
+ */
+export async function readSkill(cwd, name) {
+  // 安全检查：技能名只能是字母数字 + 连字符/下划线
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) return null
+  const p = join(cwd, ".thincoder", "skills", `${name}.md`)
+  try {
+    return await readFile(p, "utf8")
+  } catch {
+    return null
+  }
+}

package/src/tools/bash.md

@@ -0,0 +1,13 @@
+Execute a shell command and return stdout+stderr. Use for running commands, builds, tests.
+
+Parameters:
+- command (required): Shell command to execute
+- timeout: Timeout in milliseconds (default 120000, max ~300000)
+
+Notes:
+- There is NO TTY — editors, pagers (vim, less), and interactive prompts WILL hang. Always pass non-interactive flags: `git commit -m`, `git --no-pager`, `-y`/`--yes` where applicable
+- The environment sets GIT_PAGER=cat, PAGER=cat, EDITOR=true, TERM=dumb — but still always use non-interactive flags
+- Output is capped at ~50000 chars; if you need more, redirect to a file and read it
+- On Windows, use Unix shell syntax inside bash commands (Git Bash): forward slashes, `/dev/null` not `NUL`
+- Never use bash to read, copy, or transmit secret files (.env, keys, tokens)
+- Do NOT run destructive commands (rm -rf, force-push, drop table) without explicit user confirmation

package/src/tools/delete.md

@@ -0,0 +1,9 @@
+Delete a file. Use when the agent created a temporary or junk file that should be cleaned up, or when the user explicitly asks to delete something. Refuses to delete git-tracked files as a safety measure — tracked files should be edited or removed via bash with explicit user confirmation.
+
+Parameters:
+- path (required): File path, relative to cwd or absolute
+
+Notes:
+- Untracked or non-git files are deleted immediately
+- Tracked files require force=true (user must confirm separately)
+- Directories must be removed with bash (rm -rf)

package/src/tools/edit.md

@@ -0,0 +1,12 @@
+Edit a file by exact string replacement. old_string must match exactly once unless replace_all is set.
+
+Parameters:
+- path (required): File path
+- old_string (required): Exact text to find and replace
+- new_string (required): Replacement text
+- replace_all: Replace all occurrences instead of just one (default false)
+
+Notes:
+- Prefer this over write for targeted edits — it's safer and keeps diffs small
+- If old_string matches zero times: error. If it matches multiple times without replace_all: error — add more surrounding context to make it unique
+- Never fabricate the old_string — copy it verbatim from the actual file using read first

package/src/tools/fetch.md

@@ -0,0 +1,10 @@
+Fetch a URL and return its content as text. HTML pages are stripped to readable text. Use after websearch to read full documents.
+
+Parameters:
+- url (required): http/https URL
+
+Notes:
+- Follows redirects automatically
+- Timeout: 20 seconds
+- HTML pages are converted to plain text (scripts, styles, navigation stripped)
+- Non-HTML responses are returned as-is (truncated at ~50000 chars)

package/src/tools/git_diff.md

@@ -0,0 +1,11 @@
+Show git diff (unified format). Use to see uncommitted changes, staged changes, or diff against a specific ref.
+
+Parameters:
+- staged: Show staged changes (default false, shows working tree diff)
+- path: File or directory to diff (default all)
+- ref: Compare against a ref (default HEAD)
+
+Notes:
+- Only works inside a git repository
+- Output is standard unified diff — LLMs understand this natively
+- If no changes, returns "(no changes)"

package/src/tools/git_log.md

@@ -0,0 +1,10 @@
+Show recent git commit history. Use to understand the project's recent changes, conventions, and pace.
+
+Parameters:
+- count: Number of commits to show (default 10)
+- path: File or directory to show history for (default all)
+- oneline: Compact one-line-per-commit format (default false)
+
+Notes:
+- Only works inside a git repository
+- Output includes hash, author, date, and message

package/src/tools/git_status.md

@@ -0,0 +1,8 @@
+Show structured git status. Use to understand the current working tree state: what files are staged, modified, untracked, or conflicting.
+
+Returns categorized lists: staged, unstaged, untracked, conflicts.
+
+Notes:
+- Only works inside a git repository
+- Output is categorized for easy parsing by the agent
+- No side effects — read-only