@corbat-tech/coco 2.33.1 → 2.34.0

package/dist/index.js

@@ -858,6 +858,22 @@ function isCopilotTokenExpired(creds) {
   if (!creds.copilotToken || !creds.copilotTokenExpiresAt) return true;
   return Date.now() >= creds.copilotTokenExpiresAt - REFRESH_BUFFER_MS;
 }
+function exchangeForCopilotTokenViaGhCli() {
+  return new Promise((resolve3) => {
+    execFile("gh", ["api", "/copilot_internal/v2/token"], { timeout: 1e4 }, (err, stdout) => {
+      if (err || !stdout) {
+        resolve3(null);
+        return;
+      }
+      try {
+        const parsed = JSON.parse(stdout);
+        resolve3(parsed.token && parsed.expires_at ? parsed : null);
+      } catch {
+        resolve3(null);
+      }
+    });
+  });
+}
 async function getValidCopilotToken() {
   const creds = await loadCopilotCredentials();
   const envToken = process.env["COPILOT_GITHUB_TOKEN"] || process.env["GH_TOKEN"] || process.env["GITHUB_TOKEN"];
@@ -871,8 +887,7 @@ async function getValidCopilotToken() {
       isNew: false
     };
   }
-  try {
-    const copilotToken = await exchangeForCopilotToken(githubToken);
+  const saveAndReturn = async (copilotToken) => {
     const updatedCreds = {
       ...creds ?? { githubToken },
       githubToken: creds?.githubToken ?? githubToken,
@@ -886,11 +901,23 @@ async function getValidCopilotToken() {
       baseUrl: getCopilotBaseUrl(updatedCreds.accountType),
       isNew: true
     };
+  };
+  try {
+    const copilotToken = await exchangeForCopilotToken(githubToken);
+    return saveAndReturn(copilotToken);
   } catch (error) {
     if (error instanceof CopilotAuthError && error.permanent) {
+      const ghCliToken2 = await exchangeForCopilotTokenViaGhCli();
+      if (ghCliToken2) {
+        return saveAndReturn(ghCliToken2);
+      }
       await deleteCopilotCredentials();
       return null;
     }
+    const ghCliToken = await exchangeForCopilotTokenViaGhCli();
+    if (ghCliToken) {
+      return saveAndReturn(ghCliToken);
+    }
     throw error;
   }
 }
@@ -1680,6 +1707,18 @@ function getDefaultProvider() {
   }
   return "anthropic";
 }
+function getEditorModel() {
+  const raw = process.env["COCO_EDITOR_MODEL"]?.trim();
+  if (!raw || raw.length === 0) return void 0;
+  if (["none", "default", "null", "undefined"].includes(raw.toLowerCase())) return void 0;
+  return raw;
+}
+function getWeakModel() {
+  const raw = process.env["COCO_WEAK_MODEL"]?.trim();
+  if (!raw || raw.length === 0) return void 0;
+  if (["none", "default", "null", "undefined"].includes(raw.toLowerCase())) return void 0;
+  return raw;
+}
 var VALID_PROVIDERS;
 var init_env = __esm({
   "src/config/env.ts"() {
@@ -1709,7 +1748,9 @@ var init_env = __esm({
       provider: getDefaultProvider(),
       getApiKey,
       getBaseUrl,
-      getDefaultModel
+      getDefaultModel,
+      getWeakModel,
+      getEditorModel
     });
   }
 });
@@ -10316,13 +10357,21 @@ var ToolRegistry = class {
           const field = issue.path.join(".") || "input";
           return `${field} (${issue.message.toLowerCase()})`;
         });
-        errorMessage = `Invalid tool input \u2014 ${fields.join(", ")}`;
+        errorMessage = `Invalid tool input for '${name}' \u2014 ${fields.join(", ")}`;
         const allUndefined = error.issues.every(
           (i) => i.message.toLowerCase().includes("received undefined")
         );
         if (allUndefined && error.issues.length > 1) {
           errorMessage += ". All parameters are missing \u2014 this is likely a JSON serialization error on our side. Please retry with the same arguments.";
         }
+        try {
+          const schema = zodToJsonSchema(tool.parameters);
+          errorMessage += `
+
+Expected schema for '${name}':
+${JSON.stringify(schema, null, 2)}`;
+        } catch {
+        }
       } else if (isCocoError(error)) {
         const causeMsg = error.cause instanceof Error ? error.cause.message : "";
         const isRawEnoent = causeMsg.startsWith("ENOENT:");
@@ -14368,6 +14417,129 @@ var ResponsesToolCallAssembler = class {
   }
 };
 
+// src/providers/model-tier.ts
+var TIER_CONFIGS = {
+  mini: {
+    maxTools: 12,
+    parallelToolCalls: false,
+    compactionThreshold: 0.5,
+    supportsCoT: false
+  },
+  standard: {
+    maxTools: 40,
+    parallelToolCalls: true,
+    compactionThreshold: 0.75,
+    supportsCoT: true
+  },
+  advanced: {
+    maxTools: 128,
+    parallelToolCalls: true,
+    compactionThreshold: 0.8,
+    supportsCoT: true
+  }
+};
+var ANTHROPIC_TIERS = [
+  // Haiku — mini tier
+  { prefix: "claude-haiku", tier: "mini" },
+  { prefix: "claude-3-haiku", tier: "mini" },
+  // Sonnet / Claude 3.5 — standard tier
+  { prefix: "claude-3-5-sonnet", tier: "standard" },
+  { prefix: "claude-3-7-sonnet", tier: "standard" },
+  { prefix: "claude-sonnet", tier: "standard" },
+  // Opus — advanced tier
+  { prefix: "claude-opus", tier: "advanced" },
+  { prefix: "claude-3-opus", tier: "advanced" }
+  // claude-4+ (future) — default to standard unless matched above
+];
+var OPENAI_TIERS = [
+  // Mini models
+  { prefix: "gpt-4o-mini", tier: "mini" },
+  { prefix: "gpt-5-mini", tier: "mini" },
+  { prefix: "gpt-5.4-mini", tier: "mini" },
+  { prefix: "gpt-5.3-mini", tier: "mini" },
+  { prefix: "o1-mini", tier: "mini" },
+  { prefix: "o3-mini", tier: "mini" },
+  // Advanced / reasoning models
+  { prefix: "o1", tier: "advanced" },
+  { prefix: "o3", tier: "advanced" },
+  { prefix: "o4", tier: "advanced" },
+  { prefix: "gpt-4.1", tier: "advanced" },
+  { prefix: "gpt-5.4-codex", tier: "advanced" },
+  { prefix: "gpt-5.3-codex", tier: "advanced" },
+  { prefix: "gpt-5.2-codex", tier: "advanced" },
+  { prefix: "gpt-5.1-codex", tier: "advanced" },
+  { prefix: "gpt-5.4", tier: "advanced" },
+  { prefix: "gpt-5.3", tier: "advanced" },
+  { prefix: "gpt-5.2", tier: "advanced" },
+  { prefix: "gpt-5.1", tier: "advanced" },
+  // GPT-5 catch-all (non-mini/codex) — advanced
+  { prefix: "gpt-5", tier: "advanced" },
+  // GPT-4o — standard
+  { prefix: "gpt-4o", tier: "standard" },
+  // GPT-4 — standard
+  { prefix: "gpt-4", tier: "standard" }
+];
+var GEMINI_TIERS = [
+  // Flash — mini tier
+  { prefix: "gemini-3-flash", tier: "mini" },
+  { prefix: "gemini-2.5-flash", tier: "mini" },
+  { prefix: "gemini-2.0-flash", tier: "mini" },
+  { prefix: "gemini-1.5-flash", tier: "mini" },
+  // Pro — standard/advanced
+  { prefix: "gemini-3.1-pro", tier: "advanced" },
+  { prefix: "gemini-3-pro", tier: "advanced" },
+  { prefix: "gemini-2.5-pro", tier: "standard" },
+  { prefix: "gemini-2.0-pro", tier: "standard" },
+  { prefix: "gemini-1.5-pro", tier: "standard" }
+];
+var KIMI_TIERS = [
+  { prefix: "kimi-for-coding", tier: "advanced" },
+  { prefix: "kimi-k2", tier: "advanced" },
+  { prefix: "kimi-latest", tier: "standard" },
+  { prefix: "kimi", tier: "standard" }
+];
+var EVAL_TIERS = [
+  { prefix: "grok-code", tier: "standard" },
+  { prefix: "raptor", tier: "mini" },
+  { prefix: "goldeneye", tier: "standard" }
+];
+function matchTier(model, table) {
+  const lower = model.toLowerCase();
+  const sorted = [...table].sort((a, b) => b.prefix.length - a.prefix.length);
+  for (const { prefix, tier } of sorted) {
+    if (lower.startsWith(prefix.toLowerCase())) return tier;
+  }
+  return null;
+}
+function getModelTier(provider, model) {
+  if (!model) return "standard";
+  const p5 = provider.toLowerCase();
+  if (p5 === "anthropic") {
+    return matchTier(model, ANTHROPIC_TIERS) ?? "standard";
+  }
+  if (p5 === "kimi-code") {
+    return matchTier(model, KIMI_TIERS) ?? matchTier(model, ANTHROPIC_TIERS) ?? "standard";
+  }
+  if (p5 === "openai" || p5 === "copilot" || p5 === "codex") {
+    if (model.startsWith("claude-")) {
+      return matchTier(model, ANTHROPIC_TIERS) ?? "standard";
+    }
+    const evalMatch = matchTier(model, EVAL_TIERS);
+    if (evalMatch) return evalMatch;
+    return matchTier(model, OPENAI_TIERS) ?? "standard";
+  }
+  if (p5 === "gemini" || p5 === "vertex") {
+    return matchTier(model, GEMINI_TIERS) ?? "standard";
+  }
+  if (p5 === "kimi" || p5 === "moonshot") {
+    return matchTier(model, KIMI_TIERS) ?? "standard";
+  }
+  return "standard";
+}
+function getTierConfig(provider, model) {
+  return TIER_CONFIGS[getModelTier(provider, model)];
+}
+
 // src/providers/openai.ts
 var DEFAULT_MODEL2 = "gpt-5.3-codex";
 var CONTEXT_WINDOWS2 = {
@@ -14532,6 +14704,14 @@ var OpenAIProvider = class {
   supportsTemperature(model) {
     return !MODELS_WITHOUT_TEMPERATURE.some((m) => model.toLowerCase().includes(m.toLowerCase()));
   }
+  /**
+   * Whether this provider instance supports the Responses API for the given model.
+   * Subclasses (e.g. CopilotProvider) can override to force Chat Completions
+   * when their endpoint does not expose /v1/responses.
+   */
+  modelNeedsResponsesApi(model) {
+    return needsResponsesApi(model);
+  }
   /**
    * Get extra body parameters for API calls.
    * Honors the user's ThinkingMode for Kimi models; defaults to disabled
@@ -14551,7 +14731,7 @@ var OpenAIProvider = class {
   async chat(messages, options) {
     this.ensureInitialized();
     const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
-    if (needsResponsesApi(model)) {
+    if (this.modelNeedsResponsesApi(model)) {
       return this.chatViaResponses(messages, options);
     }
     return withRetry(async () => {
@@ -14591,21 +14771,24 @@ var OpenAIProvider = class {
   async chatWithTools(messages, options) {
     this.ensureInitialized();
     const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
-    if (needsResponsesApi(model)) {
+    if (this.modelNeedsResponsesApi(model)) {
       return this.chatWithToolsViaResponses(messages, options);
     }
+    const tierCfg = getTierConfig(this.id, model);
     return withRetry(async () => {
       try {
         const supportsTemp = this.supportsTemperature(model);
         const extraBody = this.getExtraBody(model, options?.thinking);
         const reasoningEffort = mapToOpenAIEffort(options?.thinking, model);
         const maxTokens = options?.maxTokens ?? this.config.maxTokens ?? 8192;
+        const tools = this.limitTools(options.tools, tierCfg.maxTools);
         const requestParams = {
           model,
           ...buildMaxTokensParam(model, maxTokens),
           messages: this.convertMessages(messages, options?.system),
-          tools: this.convertTools(options.tools),
-          tool_choice: this.convertToolChoice(options.toolChoice)
+          tools: this.convertTools(tools),
+          tool_choice: this.convertToolChoice(options.toolChoice),
+          parallel_tool_calls: tierCfg.parallelToolCalls
         };
         if (supportsTemp) {
           requestParams.temperature = options?.temperature ?? this.config.temperature ?? 0;
@@ -14643,7 +14826,7 @@ var OpenAIProvider = class {
   async *stream(messages, options) {
     this.ensureInitialized();
     const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
-    if (needsResponsesApi(model)) {
+    if (this.modelNeedsResponsesApi(model)) {
       yield* this.streamViaResponses(messages, options);
       return;
     }
@@ -14681,22 +14864,25 @@ var OpenAIProvider = class {
   async *streamWithTools(messages, options) {
     this.ensureInitialized();
     const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
-    if (needsResponsesApi(model)) {
+    if (this.modelNeedsResponsesApi(model)) {
       yield* this.streamWithToolsViaResponses(messages, options);
       return;
     }
+    const tierCfg = getTierConfig(this.id, model);
     let timeoutTriggered = false;
     try {
       const supportsTemp = this.supportsTemperature(model);
       const extraBody = this.getExtraBody(model, options?.thinking);
       const reasoningEffort = mapToOpenAIEffort(options?.thinking, model);
       const maxTokens = options?.maxTokens ?? this.config.maxTokens ?? 8192;
+      const tools = this.limitTools(options.tools, tierCfg.maxTools);
       const requestParams = {
         model,
         ...buildMaxTokensParam(model, maxTokens),
         messages: this.convertMessages(messages, options?.system),
-        tools: this.convertTools(options.tools),
+        tools: this.convertTools(tools),
         tool_choice: this.convertToolChoice(options.toolChoice),
+        parallel_tool_calls: tierCfg.parallelToolCalls,
         stream: true
       };
       if (supportsTemp) {
@@ -14933,7 +15119,7 @@ var OpenAIProvider = class {
     } catch {
       try {
         const model = this.config.model || DEFAULT_MODEL2;
-        if (needsResponsesApi(model)) {
+        if (this.modelNeedsResponsesApi(model)) {
           await this.client.responses.create({
             model,
             input: [{ role: "user", content: [{ type: "input_text", text: "Hi" }] }],
@@ -15066,6 +15252,17 @@ var OpenAIProvider = class {
     }
     return content.filter((block) => block.type === "text").map((block) => block.text).join("");
   }
+  /**
+   * Limit the tool list to at most `max` entries.
+   * Built-in tools (those without an `mcp_server` tag) are prioritised over
+   * MCP tools so core capabilities are never dropped.
+   */
+  limitTools(tools, max) {
+    if (tools.length <= max) return tools;
+    const builtin = tools.filter((t) => !("serverName" in t && t.serverName));
+    const mcp = tools.filter((t) => "serverName" in t && t.serverName);
+    return [...builtin, ...mcp].slice(0, max);
+  }
   /**
    * Convert tools to OpenAI format
    */
@@ -15074,8 +15271,9 @@ var OpenAIProvider = class {
       type: "function",
       function: {
         name: tool.name,
-        description: tool.description,
-        parameters: tool.input_schema
+        description: truncateToolDescription(tool.description),
+        parameters: tool.input_schema,
+        strict: true
       }
     }));
   }
@@ -15208,8 +15406,11 @@ var OpenAIProvider = class {
     return withRetry(async () => {
       try {
         const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
+        const tierCfg = getTierConfig(this.id, model);
         const { input, instructions } = this.convertToResponsesInput(messages, options?.system);
-        const tools = this.convertToolsForResponses(options.tools);
+        const tools = this.convertToolsForResponses(
+          this.limitTools(options.tools, tierCfg.maxTools)
+        );
         const supportsTemp = this.supportsTemperature(model);
         const reasoningEffort = mapToOpenAIEffort(options?.thinking, model);
         const response = await this.client.responses.create({
@@ -15329,8 +15530,10 @@ var OpenAIProvider = class {
     let timeoutTriggered = false;
     try {
       const model = options?.model ?? this.config.model ?? DEFAULT_MODEL2;
+      const tierCfg = getTierConfig(this.id, model);
       const { input, instructions } = this.convertToResponsesInput(messages, options?.system);
-      const tools = options.tools.length > 0 ? this.convertToolsForResponses(options.tools) : void 0;
+      const limitedTools = this.limitTools(options.tools, tierCfg.maxTools);
+      const tools = limitedTools.length > 0 ? this.convertToolsForResponses(limitedTools) : void 0;
       const supportsTemp = this.supportsTemperature(model);
       const reasoningEffort = mapToOpenAIEffort(options?.thinking, model);
       const requestParams = {
@@ -15560,12 +15763,17 @@ var OpenAIProvider = class {
     return tools.map((tool) => ({
       type: "function",
       name: tool.name,
-      description: tool.description ?? void 0,
+      description: tool.description ? truncateToolDescription(tool.description) : void 0,
       parameters: tool.input_schema ?? null,
-      strict: false
+      strict: true
     }));
   }
 };
+var MAX_TOOL_DESCRIPTION_LENGTH = 1024;
+function truncateToolDescription(description) {
+  if (description.length <= MAX_TOOL_DESCRIPTION_LENGTH) return description;
+  return description.slice(0, MAX_TOOL_DESCRIPTION_LENGTH - 1) + "\u2026";
+}
 function createKimiProvider(config) {
   const provider = new OpenAIProvider("kimi", "Kimi (Moonshot)");
   const kimiConfig = {
@@ -16334,6 +16542,14 @@ var CopilotProvider = class extends OpenAIProvider {
   /**
    * Count tokens (approximate — Copilot models vary in tokenizer)
    */
+  /**
+   * The GitHub Copilot endpoint (api.githubcopilot.com) does not expose the
+   * OpenAI Responses API (/v1/responses). Always use Chat Completions so that
+   * gpt-5-mini and similar models work correctly with MCP tools.
+   */
+  modelNeedsResponsesApi(_model) {
+    return false;
+  }
   countTokens(text) {
     if (!text) return 0;
     return Math.ceil(text.length / 3.5);
@@ -18401,7 +18617,7 @@ Use list_dir or glob to find the correct path.`;
 }
 var readFileTool = defineTool({
   name: "read_file",
-  description: `Read the contents of a file.
+  description: `Read the full text content of a file at the given path and return it as a string. Use this when you need the actual source code, configuration values, or text content of a specific file you already know the path to. Do NOT use this to list files in a directory (use list_directory), to check if a file exists (use file_exists), or to search for files by name pattern (use find_files). Returns an error if the path does not exist or is not a readable text file.
 
 Examples:
 - Read config: { "path": "package.json" }
@@ -18459,7 +18675,7 @@ Examples:
 });
 var writeFileTool = defineTool({
   name: "write_file",
-  description: `Write content to a file, creating it if it doesn't exist.
+  description: `Write text content to a file, replacing it entirely if it already exists or creating it if it does not. Use this when you want to create a new file or fully replace an existing file's content. Do NOT use this to make a small change to an existing file (use edit_file instead, which performs a targeted find-and-replace without rewriting the whole file). Set createDirs: true to automatically create missing parent directories; otherwise the parent directory must already exist.
 
 Examples:
 - Create file: { "path": "src/utils.ts", "content": "export const foo = 1;" }
@@ -18520,7 +18736,7 @@ Examples:
 });
 var editFileTool = defineTool({
   name: "edit_file",
-  description: `Edit a file by replacing text (find and replace).
+  description: `Make a targeted text replacement inside an existing file by finding oldText and replacing it with newText. Use this for surgical edits to source code, configuration files, or documentation \u2014 it is much safer than rewriting the whole file with write_file because it only touches the exact bytes you specify. The oldText must match exactly (including whitespace and indentation); if it appears more than once in the file, use all: true to replace every occurrence or make oldText longer to be unique. Do NOT use this to create new files (use write_file) or to rename/move files (use move_path).
 
 Examples:
 - Single replace: { "path": "src/app.ts", "oldText": "TODO:", "newText": "DONE:" }
@@ -18604,7 +18820,7 @@ Hint: Use read_file first to verify the exact content.`
 });
 var globTool = defineTool({
   name: "glob",
-  description: `Find files matching a glob pattern.
+  description: `Find files whose paths match a glob pattern and return their relative paths as a list. Use this when you know the file extension or naming convention but not the exact path (e.g. find all TypeScript test files, all JSON configs). Do NOT use this to search inside file contents \u2014 use grep or search for that. Returns an empty list when nothing matches; does not throw an error for zero results. node_modules, .git, and dist directories are excluded by default.
 
 Examples:
 - All TypeScript: { "pattern": "**/*.ts" }
@@ -18646,7 +18862,7 @@ Examples:
 });
 var fileExistsTool = defineTool({
   name: "file_exists",
-  description: `Check if a file or directory exists.
+  description: `Check whether a path exists on disk and whether it is a file or directory. Use this before attempting to read or write a path when you are unsure it exists \u2014 it never throws, always returning { exists: false } for missing paths. Do NOT use this to read file contents (use read_file) or to list directory contents (use list_directory). Returns isFile and isDirectory flags so you can distinguish files from directories in a single call.
 
 Examples:
 - Check file: { "path": "package.json" } \u2192 { "exists": true, "isFile": true, "isDirectory": false }
@@ -18676,7 +18892,7 @@ Examples:
 });
 var listDirTool = defineTool({
   name: "list_dir",
-  description: `List contents of a directory.
+  description: `List the immediate entries (files and subdirectories) inside a directory and return their names, types, and sizes. Use this to understand what's in a folder before deciding which files to read. Do NOT use this to find files matching a pattern across the whole project (use glob) or to read file contents (use read_file). Returns an error if the path does not exist or is not a directory.
 
 Examples:
 - List src: { "path": "src" }
@@ -19109,16 +19325,11 @@ var SENSITIVE_ENV_PATTERNS = [
 ];
 var bashExecTool = defineTool({
   name: "bash_exec",
-  description: `Execute a bash/shell command in the user's shell environment.
+  description: `Execute a shell command and return its stdout, stderr, and exit code. Use this for running build scripts, test runners, linters, package managers, CLI tools, git commands, or any other shell operation. Runs in the user's shell environment with their full PATH and locally-configured credentials (kubeconfig, gcloud auth, AWS profiles, SSH keys) so never claim you cannot run a command due to missing credentials \u2014 always attempt and report the actual exit code. Do NOT use this to read or write files (use read_file / write_file / edit_file which are safer); prefer specific file tools for file operations.
 
 Runs with the user's full PATH and inherited environment \u2014 any tool installed
 on the user's machine is available: kubectl, gcloud, aws, docker, git, node,
-pnpm, and others. Credentials configured locally are inherited automatically:
-kubeconfig contexts, gcloud auth, AWS profiles, SSH keys, etc.
-
-IMPORTANT: never claim you cannot run a command because you lack credentials
-or access \u2014 the environment is the user's own shell. Always attempt; report
-failure only if the command actually returns a non-zero exit code.
+pnpm, and others.
 
 Examples:
 - List files:          { "command": "ls -la" }
@@ -19387,7 +19598,7 @@ function getGit(cwd) {
 }
 var gitStatusTool = defineTool({
   name: "git_status",
-  description: `Get the current git repository status including branch, staged, modified, and untracked files.
+  description: `Return the current git repository state: branch name, staged files, modified files, and untracked files. Use this before committing to see what has changed, or to check which branch is active. Do NOT use this to see the content of changes (use git_diff), or to view history (use git_log). Returns isClean: true when the working tree is clean with nothing to commit.
 
 Examples:
 - Current dir: {} \u2192 { "branch": "main", "isClean": false, "modified": ["src/app.ts"] }
@@ -19421,7 +19632,7 @@ Examples:
 });
 var gitDiffTool = defineTool({
   name: "git_diff",
-  description: `Get git diff showing file changes.
+  description: `Show the unified diff of changes in the working tree or staging area. Use this to see exactly what lines changed in files before committing, or to review changes the user just made. Use staged: true to see only what has been staged (git add), or omit it to see all unstaged changes. Do NOT use this to see commit history (use git_log) or file status summary (use git_status).
 
 Examples:
 - All changes: {} \u2192 { "diff": "...", "filesChanged": 3, "insertions": 42, "deletions": 10 }
@@ -19458,7 +19669,7 @@ Examples:
 });
 var gitAddTool = defineTool({
   name: "git_add",
-  description: `Stage files for commit.
+  description: `Stage one or more files (or patterns) so they are included in the next git commit. Use this after making file edits to mark them ready for commit. Pass ["."] to stage all changes, or list specific file paths to stage selectively. Do NOT use this to commit (use git_commit after staging) or to view what is staged (use git_status or git_diff with staged: true).
 
 Examples:
 - Stage all: { "files": ["."] }
@@ -19484,7 +19695,7 @@ Examples:
 });
 var gitCommitTool = defineTool({
   name: "git_commit",
-  description: `Create a git commit with the staged changes.
+  description: `Create a git commit from whatever is currently staged (git add must run first). Use conventional commit format (feat/fix/docs/chore). Do NOT use this when nothing is staged \u2014 check git_status first; do NOT use this to stage files (use git_add) or to see what will be committed (use git_diff with staged: true).
 
 Examples:
 - Simple commit: { "message": "fix: resolve auth bug" }
@@ -19517,7 +19728,7 @@ Examples:
 });
 var gitLogTool = defineTool({
   name: "git_log",
-  description: `Get git commit history.
+  description: `Show git commit history with hashes, messages, authors, and dates. Use this to understand what changed recently, find the commit that introduced a bug, or check whether a feature was already merged. Do NOT use this to see the content of changes \u2014 use git_diff; do NOT use this to check current file state \u2014 use git_status.
 
 Examples:
 - Last 10 commits: {} (default)
@@ -19557,7 +19768,7 @@ Examples:
 });
 var gitBranchTool = defineTool({
   name: "git_branch",
-  description: `Manage git branches (list, create, delete).
+  description: `List all local branches, create a new branch from the current HEAD, or delete a branch. Use this to see available branches before checking out, or to create a feature branch. Do NOT use this to switch the active branch \u2014 use git_checkout; do NOT delete branches that have unmerged work.
 
 Examples:
 - List branches: {} \u2192 { "branches": ["main", "feature/x"], "current": "main" }
@@ -19601,7 +19812,7 @@ Examples:
 });
 var gitCheckoutTool = defineTool({
   name: "git_checkout",
-  description: `Switch branches or create and switch to a new branch.
+  description: `Switch the working directory to an existing branch, or create a new branch and switch to it in one step. Use this to move between branches or start a new feature branch. Do NOT use this with unsaved file edits (stage or stash first); do NOT use this to just list branches \u2014 use git_branch.
 
 Examples:
 - Switch branch: { "branch": "main" }
@@ -19631,7 +19842,7 @@ Examples:
 });
 var gitPushTool = defineTool({
   name: "git_push",
-  description: `Push commits to remote repository.
+  description: `Upload local commits to a remote repository. Use setUpstream: true the first time you push a new branch to create the tracking relationship. Do NOT use this on main/master without explicit user confirmation \u2014 it modifies shared history; do NOT push without first checking git_status to confirm all commits are clean.
 
 Examples:
 - Push current: {} \u2192 pushes to origin
@@ -19669,7 +19880,7 @@ Examples:
 });
 var gitPullTool = defineTool({
   name: "git_pull",
-  description: `Pull changes from remote repository.
+  description: `Fetch and integrate remote commits into the current branch. Use rebase: true to keep a linear history (preferred for feature branches). Do NOT use this when you have uncommitted local changes \u2014 stage or stash them first; if a merge conflict is reported, use read_file / edit_file to resolve then git_add and git_commit.
 
 Examples:
 - Pull current: {} \u2192 pulls from origin
@@ -20792,7 +21003,7 @@ var qualityTools = [runLinterTool, analyzeComplexityTool, calculateQualityTool];
 init_errors();
 var grepTool = defineTool({
   name: "grep",
-  description: `Search for text patterns in files using regex.
+  description: `Search for a regex pattern across all files in a directory and return matching lines with file paths and line numbers. Use this when you know a symbol name, string literal, or pattern and want to find where it appears in the codebase (function definitions, imports, error messages, config keys). Do NOT use this to find files by name \u2014 use glob for that. Do NOT use this when you already know the file path \u2014 use read_file directly. Searches are recursive by default; narrow with the include glob to restrict to specific file types.
 
 Examples:
 - Simple search: { "pattern": "TODO" }
@@ -20925,7 +21136,7 @@ Examples:
 });
 var findInFileTool = defineTool({
   name: "find_in_file",
-  description: `Search for a pattern in a single file.
+  description: `Search for a text or regex pattern inside a single known file and return matching line numbers and content. Use this when you already have the file path and want to quickly find which lines match (e.g. locate a function signature, find an import, or confirm a value exists). Do NOT use this to search across the whole project \u2014 use grep for that. Returns line numbers so you can navigate directly to the match.
 
 Examples:
 - Find text: { "file": "src/app.ts", "pattern": "export" }
@@ -22426,7 +22637,7 @@ async function searchSerpApi(query, maxResults, timeout) {
 }
 var webSearchTool = defineTool({
   name: "web_search",
-  description: `Search the web for information, documentation, error solutions, and API references.
+  description: `Search the web using a natural-language query and return a list of result titles, URLs, and short excerpts. Use this when you need to find documentation, research an error message, discover API references, or learn about a library before you have a specific URL. Do NOT use this when you already have the URL \u2014 use web_fetch to read a known page directly. Returns result titles and URLs you can then fetch with web_fetch for full content.
 
 Examples:
 - Basic search: { "query": "typescript zod validation examples" }
@@ -22707,7 +22918,7 @@ ${rows.join("\n")}
 }
 var webFetchTool = defineTool({
   name: "web_fetch",
-  description: `Fetch a URL and convert its content to clean markdown. Extracts main content, strips navigation/ads, and returns readable text.
+  description: `Fetch the content of a specific URL and return it as clean, readable markdown text. Use this when you already have the exact URL \u2014 for example a documentation page, a GitHub file, or an API response \u2014 and want to read its content. Do NOT use this to find information without a URL; use web_search instead to discover relevant URLs first. By default strips navigation menus, headers, and ads to return only the main content; set extractContent: false to get the raw HTML/text.
 
 Examples:
 - Fetch documentation: { "url": "https://docs.example.com/api" }
@@ -24418,8 +24629,7 @@ async function saveMemory(scope, memory) {
 }
 var createMemoryTool = defineTool({
   name: "create_memory",
-  description: `Save a memory (key-value pair) that persists between sessions.
-Use for storing project conventions, patterns, preferences, and learnings.
+  description: `Persist a named key-value fact that survives across sessions \u2014 use this for project conventions, patterns, user preferences, or discovered constraints you'll need later. If the key already exists the value is overwritten. Do NOT use this for temporary scratch data within a single session; do NOT use this to store file contents \u2014 use write_file for that.
 
 Examples:
 - Save convention: { "key": "naming-convention", "value": "Use camelCase for variables", "tags": ["style"] }
@@ -24476,7 +24686,7 @@ Examples:
 });
 var recallMemoryTool = defineTool({
   name: "recall_memory",
-  description: `Search and recall stored memories by key, tags, or free text query.
+  description: `Search previously saved memories by key substring, tags, or free-text value match. Use this at the start of a task to check if relevant conventions or patterns were already learned. Returns full memory content. Do NOT use this to list all memories (use list_memories) or to search file content (use grep).
 
 Examples:
 - By key substring: { "query": "naming" }
@@ -24531,7 +24741,7 @@ Examples:
 });
 var listMemoriesTool = defineTool({
   name: "list_memories",
-  description: `List all stored memories with optional filtering. Returns lightweight index entries.
+  description: `List stored memory keys and tags without loading full values \u2014 useful for browsing what has been saved before recalling specific entries. Do NOT use this to get memory content (use recall_memory for that).
 
 Examples:
 - List all: { "scope": "all" }
@@ -27053,7 +27263,7 @@ async function ghExec(args, cwd) {
 }
 var ghCheckAuthTool = defineTool({
   name: "gh_check_auth",
-  description: "Check if the GitHub CLI is installed and authenticated.",
+  description: "Verify the gh CLI is installed and the user is logged into GitHub. Call this before any other gh_ tool to confirm authentication is working. Returns the logged-in username if authenticated.",
   category: "git",
   parameters: z.object({
     cwd: z.string().optional()
@@ -27073,7 +27283,7 @@ var ghCheckAuthTool = defineTool({
 });
 var ghRepoInfoTool = defineTool({
   name: "gh_repo_info",
-  description: "Get GitHub repository information (name, default branch, URL).",
+  description: "Get the remote GitHub repository's name, owner, default branch, and URL from within the current git working directory. Use before creating PRs to confirm the target repo. Requires gh_check_auth to pass first.",
   category: "git",
   parameters: z.object({
     cwd: z.string().optional()
@@ -27095,7 +27305,7 @@ var ghRepoInfoTool = defineTool({
 });
 var ghPrCreateTool = defineTool({
   name: "gh_pr_create",
-  description: "Create a GitHub pull request.",
+  description: "Open a pull request on GitHub from the current branch. Requires commits to be pushed first (use git_push with setUpstream: true). Do NOT use this if a PR for this branch already exists \u2014 use gh_pr_list to check first. Use draft: true for work in progress.",
   category: "git",
   parameters: z.object({
     title: z.string().describe("PR title"),
@@ -27119,7 +27329,7 @@ var ghPrCreateTool = defineTool({
 });
 var ghPrMergeTool = defineTool({
   name: "gh_pr_merge",
-  description: "Merge a GitHub pull request.",
+  description: "Merge a pull request into its base branch. Use squash (default) for feature branches to keep history clean. Always confirm with gh_pr_checks first to ensure CI passed. Do NOT merge if anyFailed is true.",
   category: "git",
   parameters: z.object({
     number: z.number().describe("PR number"),
@@ -27140,7 +27350,7 @@ var ghPrMergeTool = defineTool({
 });
 var ghPrChecksTool = defineTool({
   name: "gh_pr_checks",
-  description: "Get CI check statuses for a pull request.",
+  description: "Poll the CI check results for a pull request \u2014 returns pass/fail/pending per check and convenience flags (allPassed, anyFailed). Call this after pushing to confirm CI is green before merging. Check anyPending to know if results are still arriving.",
   category: "git",
   parameters: z.object({
     number: z.number().describe("PR number"),
@@ -27174,7 +27384,7 @@ var ghPrChecksTool = defineTool({
 });
 var ghPrListTool = defineTool({
   name: "gh_pr_list",
-  description: "List pull requests, optionally filtered by head branch.",
+  description: "List open (or all) pull requests for this repository, optionally filtered to a specific branch. Use before gh_pr_create to ensure a PR for the current branch doesn't already exist. Returns PR number, title, URL, and state.",
   category: "git",
   parameters: z.object({
     head: z.string().optional().describe("Filter by head branch name"),
@@ -27191,7 +27401,7 @@ var ghPrListTool = defineTool({
 });
 var ghReleaseCreateTool = defineTool({
   name: "gh_release_create",
-  description: "Create a GitHub release with notes.",
+  description: "Publish a versioned GitHub release attached to a tag. The tag must already exist in the repo (push it with git_push first). Provide markdown release notes. Use prerelease: true for release candidates or beta builds.",
   category: "git",
   parameters: z.object({
     tag: z.string().describe("Tag name (e.g., v1.2.3)"),