@wrongstack/tools 0.319.0 → 0.319.1

package/dist/{chunk-7WV3D4S3.js → chunk-OG2BEUBY.js}

@@ -1,6 +1,9 @@
+import {
+  mapWithConcurrency
+} from "./chunk-NWZ6XGBJ.js";
 import {
   safeResolveReal
-} from "./chunk-QLF74MSV.js";
+} from "./chunk-ZUFHAHTE.js";
 
 // src/diff.ts
 import { spawn } from "node:child_process";
@@ -59,6 +62,7 @@ var diffTool = {
   },
   async execute(input, ctx, opts) {
     const signal = opts?.signal ?? ctx.signal ?? new AbortController().signal;
+    signal.throwIfAborted();
     if (input.a !== void 0 || input.b !== void 0) {
       return await gitDiff(input, ctx, signal);
     }
@@ -66,13 +70,25 @@ var diffTool = {
   }
 };
 async function gitDiff(input, ctx, signal) {
-  if (input.a?.startsWith("-")) {
+  if (input.a !== void 0 && (!input.a || !input.a.trim())) {
+    throw new ToolValidationError({
+      message: "diff: ref 'a' cannot be empty or whitespace-only",
+      field: "a"
+    });
+  }
+  if (input.b !== void 0 && (!input.b || !input.b.trim())) {
+    throw new ToolValidationError({
+      message: "diff: ref 'b' cannot be empty or whitespace-only",
+      field: "b"
+    });
+  }
+  if (input.a?.trim().startsWith("-")) {
     throw new ToolValidationError({
       message: `diff: unsafe ref "${input.a}" \u2014 refs may not begin with '-' (flag injection)`,
       field: "a"
     });
   }
-  if (input.b?.startsWith("-")) {
+  if (input.b?.trim().startsWith("-")) {
     throw new ToolValidationError({
       message: `diff: unsafe ref "${input.b}" \u2014 refs may not begin with '-' (flag injection)`,
       field: "b"
@@ -82,9 +98,16 @@ async function gitDiff(input, ctx, signal) {
   const statMode = requestedMode === "stat";
   const effectiveMode = statMode ? "stat" : "unified";
   const sideBySideNote = requestedMode === "side-by-side" ? "side-by-side output is not supported; a unified diff was produced instead." : void 0;
-  const gitDir = findGitDir(ctx.cwd);
+  const basePath = input.path ? await safeResolveReal(input.path, ctx) : ctx.cwd;
+  const gitDir = findGitDir(basePath);
   if (!gitDir) {
-    return { diff: "", files: [], truncated: false, mode: effectiveMode };
+    return {
+      diff: "",
+      files: [],
+      truncated: false,
+      mode: effectiveMode,
+      note: "Not a git repository (or any parent up to root)."
+    };
   }
   const args = ["diff", "--no-color"];
   if (statMode) args.push("--stat");
@@ -93,11 +116,11 @@ async function gitDiff(input, ctx, signal) {
     if (Number.isFinite(contextLines)) args.push(`-U${contextLines}`);
   }
   if (input.staged) args.push("--staged");
-  if (input.a) args.push(input.a);
-  if (input.b) args.push(input.b);
+  if (input.a) args.push(input.a.trim());
+  if (input.b) args.push(input.b.trim());
   if (input.files) {
     const files = Array.isArray(input.files) ? input.files : input.files.split(",");
-    args.push("--", ...files.map((f) => f.trim()));
+    args.push("--", ...files.map((f) => f.trim().replace(/\\/g, "/")));
   }
   const result = await runGit(args, gitDir, signal);
   let diff = result.stdout;
@@ -110,12 +133,14 @@ async function gitDiff(input, ctx, signal) {
 \u2026[git diff truncated: ${result.stdout.length - clipped.length} of ${result.stdout.length} characters omitted]`;
     truncated = true;
   }
+  const exitNote = result.exitCode !== 0 ? `git diff exited with code ${result.exitCode}: ${result.stderr.trim() || "command failed"}` : void 0;
+  const combinedNote = [sideBySideNote, exitNote].filter(Boolean).join("\n") || void 0;
   return {
     diff,
     files: [],
     truncated,
     mode: effectiveMode,
-    note: sideBySideNote
+    note: combinedNote
   };
 }
 function findGitDir(cwd) {
@@ -133,7 +158,10 @@ function findGitDir(cwd) {
   return null;
 }
 function runGit(args, cwd, signal) {
-  return new Promise((resolve) => {
+  if (signal.aborted) {
+    return Promise.resolve({ stdout: "", stderr: "Aborted", exitCode: 124 });
+  }
+  return new Promise((resolve2) => {
     let stdout = "";
     let stderr = "";
     const child = spawn("git", args, {
@@ -149,11 +177,12 @@ function runGit(args, cwd, signal) {
     child.stderr?.on("data", (c) => {
       stderr += c.toString();
     });
-    child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 0 }));
-    child.on("error", (e) => resolve({ stdout: "", stderr: e.message, exitCode: 1 }));
+    child.on("close", (code) => resolve2({ stdout, stderr, exitCode: code ?? 0 }));
+    child.on("error", (e) => resolve2({ stdout: "", stderr: e.message, exitCode: 1 }));
   });
 }
-async function fileDiff(input, ctx, _signal) {
+async function fileDiff(input, ctx, signal) {
+  signal.throwIfAborted();
   void input.context;
   const files = input.files ? (Array.isArray(input.files) ? input.files : input.files.split(",")).map((f) => f.trim()).filter(Boolean) : [];
   if (files.length === 0) {
@@ -164,25 +193,26 @@ async function fileDiff(input, ctx, _signal) {
       mode: "dump"
     };
   }
-  const fileEntries = await Promise.all(
-    files.map(async (file) => {
-      const absPath = await safeResolveReal(file, ctx);
-      const stat2 = await fs.stat(absPath).catch(() => null);
-      if (!stat2?.isFile()) return null;
-      if (stat2.size > MAX_FILE_DUMP_BYTES) {
-        return {
-          truncated: true,
-          output: `--- ${file} (skipped: ${stat2.size} bytes exceeds the ${MAX_FILE_DUMP_BYTES} limit; use the read tool with offset/limit) ---`
-        };
-      }
-      const content = await fs.readFile(absPath, "utf8");
-      const lines = content.split(/\r?\n/);
+  const basePath = input.path ? await safeResolveReal(input.path, ctx) : ctx.cwd;
+  const fileEntries = await mapWithConcurrency(files, 16, async (file) => {
+    signal.throwIfAborted();
+    const fileToResolve = path.isAbsolute(file) ? file : path.resolve(basePath, file);
+    const absPath = await safeResolveReal(fileToResolve, ctx);
+    const stat2 = await fs.stat(absPath).catch(() => null);
+    if (!stat2?.isFile()) return null;
+    if (stat2.size > MAX_FILE_DUMP_BYTES) {
       return {
-        truncated: false,
-        output: formatWithLineNumbers(file, lines)
+        truncated: true,
+        output: `--- ${file} (skipped: ${stat2.size} bytes exceeds the ${MAX_FILE_DUMP_BYTES} limit; use the read tool with offset/limit) ---`
       };
-    })
-  );
+    }
+    const content = await fs.readFile(absPath, "utf8");
+    const lines = content.split(/\r?\n/);
+    return {
+      truncated: false,
+      output: formatWithLineNumbers(file, lines)
+    };
+  });
   const results = [];
   let truncated = false;
   for (const entry of fileEntries) {
@@ -201,13 +231,18 @@ async function fileDiff(input, ctx, _signal) {
   };
 }
 function formatWithLineNumbers(file, lines) {
-  const width = String(lines.length).length;
-  const numbered = lines.map((line, i) => `${String(i + 1).padStart(width)} | ${line}`).join("\n");
+  const count = lines.length;
+  const width = String(count).length;
+  const parts = new Array(count);
+  for (let i = 0; i < count; i++) {
+    const numStr = String(i + 1).padStart(width, " ");
+    parts[i] = `${numStr} | ${lines[i]}`;
+  }
   return `--- ${file} (line-numbered dump, not a unified diff) ---
-${numbered}`;
+${parts.join("\n")}`;
 }
 
 export {
   diffTool
 };
-//# sourceMappingURL=chunk-7WV3D4S3.js.map
+//# sourceMappingURL=chunk-OG2BEUBY.js.map

package/dist/{chunk-VALQFAY2.js → chunk-OTINMOKK.js}

@@ -1,6 +1,6 @@
 import {
   e2ePlanTool
-} from "./chunk-DPKTXJQS.js";
+} from "./chunk-VPALDFYM.js";
 import {
   codebaseAstReplaceTool,
   codebaseImpactAnalysisTool,
@@ -14,13 +14,13 @@ import {
   codebaseStatsTool,
   codebaseTargetedTestTool,
   deadCodeScanTool
-} from "./chunk-RK47IWO3.js";
+} from "./chunk-RTZWBNTY.js";
 import {
   planTool
-} from "./chunk-H6AWAZ2Y.js";
+} from "./chunk-B4HTSV6Z.js";
 import {
   taskTool
-} from "./chunk-X5K3U6GI.js";
+} from "./chunk-3M7LLN7W.js";
 import {
   toolSearchTool
 } from "./chunk-RJZQWEMS.js";
@@ -35,76 +35,76 @@ import {
 } from "./chunk-QBV725YG.js";
 import {
   designTool
-} from "./chunk-6RNIFLG4.js";
+} from "./chunk-ELRRTWNP.js";
 import {
   testTool
-} from "./chunk-Y7QXSE7N.js";
+} from "./chunk-UQQS3VNT.js";
 import {
   installTool
-} from "./chunk-4Q7LFU4T.js";
+} from "./chunk-RLMX75EM.js";
 import {
   auditTool
-} from "./chunk-QZDOQRF7.js";
+} from "./chunk-64VIJPFV.js";
 import {
   outdatedTool
-} from "./chunk-Z4VBTVUM.js";
+} from "./chunk-IYKXK356.js";
 import {
   logsTool
-} from "./chunk-YZHK4TLF.js";
+} from "./chunk-FQNXYA6W.js";
 import {
   documentTool
-} from "./chunk-HBM4QNXU.js";
+} from "./chunk-IU4DV2PA.js";
 import {
   scaffoldTool
-} from "./chunk-2472NT76.js";
+} from "./chunk-2OXHS3KZ.js";
 import {
   gitTool
-} from "./chunk-UMXVT7ST.js";
+} from "./chunk-6AAOT4PW.js";
 import {
   patchTool
-} from "./chunk-COUNXG4X.js";
+} from "./chunk-IWS56OY7.js";
 import {
   jsonTool
-} from "./chunk-D4CXUZIF.js";
+} from "./chunk-VD2LV5WO.js";
 import {
   diffTool
-} from "./chunk-7WV3D4S3.js";
+} from "./chunk-OG2BEUBY.js";
 import {
   treeTool
-} from "./chunk-HWDB2G7J.js";
+} from "./chunk-MNP3GE7H.js";
 import {
   lintTool
-} from "./chunk-ZKSBHXVB.js";
+} from "./chunk-LOBRWKCR.js";
 import {
   formatTool
-} from "./chunk-ODFVG54U.js";
+} from "./chunk-EADULOZV.js";
 import {
   typecheckTool
-} from "./chunk-VFF3Q5Z3.js";
+} from "./chunk-5EUJF3WC.js";
 import {
   languageInfoTool,
   languagePackageTool,
   languageTool
-} from "./chunk-UC3RKRIV.js";
+} from "./chunk-TTZOK6IY.js";
 import {
   replaceTool
-} from "./chunk-OYVPBPCL.js";
+} from "./chunk-X5FOFGXX.js";
 import {
   globTool
-} from "./chunk-OJ4FIBAN.js";
+} from "./chunk-JDPQOR7C.js";
 import {
   grepTool
-} from "./chunk-N5O3FK5Q.js";
+} from "./chunk-YOKD4GWJ.js";
 import {
   bashTool,
   checkAndBlockKillCommand,
   diagnoseBashism,
   shellArgs
-} from "./chunk-WNUJR3H4.js";
+} from "./chunk-AKHYMB4V.js";
 import {
   detectDanger,
   execTool
-} from "./chunk-PMHVSHMU.js";
+} from "./chunk-BSJSNVGA.js";
 import {
   buildChildEnv
 } from "./chunk-BTSFTGIL.js";
@@ -118,28 +118,28 @@ import {
 } from "./chunk-3PVYQFRQ.js";
 import {
   fetchTool
-} from "./chunk-KD5EHYA2.js";
+} from "./chunk-C2DQKVLO.js";
 import {
   searchTool
-} from "./chunk-PQTONQ4P.js";
+} from "./chunk-QPNYDH5B.js";
 import {
   todoTool
-} from "./chunk-5ZYEGP2P.js";
+} from "./chunk-BK732J7I.js";
 import {
   kanbanTool
-} from "./chunk-FJEQZHZN.js";
+} from "./chunk-W2CECGTG.js";
 import {
   browserTools
 } from "./chunk-45JPRMC2.js";
 import {
   readTool
-} from "./chunk-C3W3V54D.js";
+} from "./chunk-RNWUCZ2U.js";
 import {
   writeTool
-} from "./chunk-MYRMD6PZ.js";
+} from "./chunk-O44IMQCN.js";
 import {
   editTool
-} from "./chunk-PRXZOIEW.js";
+} from "./chunk-CFLJFDYV.js";
 import {
   resolvePowerShell
 } from "./chunk-V43EQ6VR.js";
@@ -147,7 +147,7 @@ import {
   normalizeCommandOutput,
   safeResolveProjectPath,
   safeResolveReal
-} from "./chunk-QLF74MSV.js";
+} from "./chunk-ZUFHAHTE.js";
 
 // src/clarify.ts
 import { toErrorMessage } from "@wrongstack/core/utils";
@@ -193,8 +193,10 @@ var clarifyTool = {
     required: ["question", "options"],
     additionalProperties: false
   },
-  async execute(input, ctx) {
+  async execute(input, ctx, opts) {
     try {
+      const signal = opts?.signal ?? ctx?.signal;
+      signal?.throwIfAborted();
       const options = input.options;
       if (!options || options.length < 2) {
         throw new Error("clarify requires at least 2 distinct options.");
@@ -238,6 +240,7 @@ import {
   emitProcessOutput,
   emitProcessStarted
 } from "@wrongstack/core/observability";
+import { ToolValidationError } from "@wrongstack/core/types";
 var MAX_OUTPUT = 32768;
 var DEFAULT_TIMEOUT_MS = 3e5;
 var STREAM_FLUSH_INTERVAL_MS = 200;
@@ -383,8 +386,38 @@ var pwshTool = {
     if (!final) throw new Error("pwsh: stream ended without final event");
     return final;
   },
+  async cleanup(_input, ctx) {
+    const registry = getProcessRegistry();
+    const sessionId = ctx.session?.id;
+    if (!sessionId) return;
+    for (const entry of registry.bySession(sessionId)) {
+      if (entry.name !== "pwsh") continue;
+      if (entry.child && entry.child.exitCode !== null) continue;
+      if (entry.protected) continue;
+      registry.kill(entry.pid, { force: true });
+    }
+  },
   async *executeStream(input, ctx, opts) {
-    if (!input?.command) throw new Error("pwsh: command is required");
+    if (!input?.command || typeof input.command !== "string" || !input.command.trim()) {
+      throw new ToolValidationError({
+        message: "pwsh: command is required and cannot be empty",
+        field: "command"
+      });
+    }
+    const callerSignal = opts?.signal ?? ctx?.signal ?? new AbortController().signal;
+    if (callerSignal.aborted) {
+      yield {
+        type: "final",
+        output: {
+          output: "",
+          exit_code: 124,
+          timed_out: false,
+          pid: null,
+          error: "Aborted"
+        }
+      };
+      return;
+    }
     const isBackground = !!(input.run_in_background || input.background);
     const registry = getProcessRegistry();
     if (!registry.beforeCall(isBackground)) {
@@ -438,7 +471,6 @@ var pwshTool = {
       return;
     }
     const startedAt = Date.now();
-    const callerSignal = opts?.signal ?? ctx.signal ?? new AbortController().signal;
     const detached = !isWin;
     if (isBackground) {
       const child2 = spawn(bin, args, {
@@ -546,7 +578,8 @@ Working directory: ${targetCwd}`,
         processGroupLeader: detached && child.pid === pid
       });
     }
-    const timeoutMs = Math.min(Math.max(1e3, input.timeout_ms ?? DEFAULT_TIMEOUT_MS), 6e5);
+    const rawTimeout = typeof input.timeout_ms === "number" && !Number.isNaN(input.timeout_ms) ? input.timeout_ms : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = Math.min(Math.max(1e3, rawTimeout), 6e5);
     let timedOut = false;
     const timers = [];
     const killWithTimeout = (timeout) => {
@@ -1018,6 +1051,78 @@ var setWorkingDirTool = {
 };
 
 // src/builtin.ts
+var BUILTIN_TOOL_DESCRIPTIONS = {
+  browser_open: "Create an isolated, agent-owned Playwright browser session, optionally opening an approved HTTP(S) URL. Use it to begin browser QA; private and localhost origins require an explicit allowlist.",
+  browser_list: "List browser sessions owned by this agent, including their state and current page, without exposing sessions owned by other agents.",
+  browser_status: "Check whether the managed Playwright Chromium installation is available before attempting browser automation.",
+  browser_navigate: "Navigate one of this agent\u2019s browser sessions to an approved HTTP(S) URL. Use browser_open first; private and localhost origins require an explicit allowlist.",
+  browser_snapshot: "Inspect the current page through a bounded accessibility snapshot, with redacted console and network summaries. Prefer this before interacting with page elements.",
+  browser_screenshot: "Capture a PNG of the current page or a selected element for visual QA. The result is a sensitive artifact with integrity metadata.",
+  browser_type: "Fill a form control in an owned browser session. Use secretEnv for credentials so secret values never enter tool arguments or the audit trail.",
+  browser_click: "Click a verified page element in an owned browser session. Snapshot first and use the most specific stable selector available.",
+  browser_hover: "Hover over a verified page element in an owned browser session to reveal menus, tooltips, or other hover-driven UI state.",
+  browser_select: "Choose an option in a select control in an owned browser session after confirming the target selector and intended value.",
+  browser_press: "Send a keyboard key or shortcut to an owned browser session, such as Enter after verifying a form is ready to submit.",
+  browser_drag: "Drag one page element onto another in an owned browser session. Use only when the page\u2019s drag-and-drop interaction is the intended action.",
+  browser_wait: "Wait for a selector, navigation condition, or bounded duration in an owned browser session before taking the next browser action.",
+  browser_evaluate: "Run a bounded JavaScript expression in an owned page when browser APIs cannot inspect the needed state. Treat page code as arbitrary and use sparingly.",
+  browser_upload: "Upload project-local files through a page file input in an owned browser session. Verify both the file path and target control before uploading.",
+  browser_close: "Close an owned browser session and reclaim its resources, returning trace-artifact metadata when tracing was enabled.",
+  e2e_plan: "Create an end-to-end test plan from a feature or user flow. Use it to identify scenarios and acceptance coverage; it plans tests rather than executing them.",
+  read: "Read a project file safely, with optional line ranges and binary-aware output. Use it to inspect source before editing; paths must stay within the project.",
+  write: "Create or replace one project file with the complete supplied content. Use for new files or intentional full rewrites, after reading existing content when applicable.",
+  edit: "Make a precise, guarded text edit by replacing an expected block in a project file. Prefer it for small source changes so mismatches prevent accidental overwrites.",
+  clarify: "Record or ask a focused clarification when a missing decision would materially change the implementation. Do not use it for questions that can be answered from the repository.",
+  "codebase-ast-replace": "Replace a named declaration using source-aware structure instead of fragile text matching. Use it for a function, method, class, interface, or variable when the target is unambiguous.",
+  "codebase-invariant-check": "Compare candidate code with its original source and report structural invariants that may have changed. Use before writing a risky refactor; it validates but does not modify files.",
+  "codebase-stats": "Report codebase-index health, indexed file and symbol counts, languages, and freshness. Use it before relying on indexed discovery results.",
+  "codebase-search": "Search indexed symbols, signatures, and documentation with optional language, kind, path, or LSP-kind filters. Use it for semantic discovery before broad text search.",
+  "codebase-skeleton": "Extract a compact structural skeleton from a source file or directory, preserving declarations while omitting implementation detail. Use it to understand unfamiliar code quickly.",
+  "codebase-repo-map": "Generate a concise map of important files, symbols, and relationships in a project area. Use it for orientation before a cross-file change.",
+  "codebase-impact-analysis": "Find likely callers, dependents, related tests, and change risk for a named symbol. Use it before changing a public or widely used declaration.",
+  "codebase-targeted-test": "Discover and run tests that cover a specified symbol, source file, or explicit test files. Use it for focused regression validation after a change.",
+  "security-ast-scan": "Statically scan source code for supported security patterns and return findings with locations. Use it as a focused code check, not as a substitute for a full security assessment.",
+  "codebase-incoming-calls": "Find indexed call sites that invoke a named function, method, or type, optionally scoped to a file. Use it to estimate breakage before changing an API.",
+  "codebase-outgoing-calls": "Find indexed symbols called by a named function, method, or type, optionally scoped to a file. Use it to understand dependencies before refactoring behavior.",
+  "codebase-index": "Build or refresh the local semantic codebase index, optionally for selected languages. Use it when index results are absent or stale; force performs a full reindex.",
+  "dead-code-scan": "Analyze the indexed project for declarations that appear unreachable from configured entry points. Treat results as candidates for review, not automatic deletion instructions.",
+  replace: "Preview or apply a regular-expression replacement across selected project files. Start with dry_run, constrain files and globs carefully, then apply only reviewed changes.",
+  glob: "Find project files by glob pattern, respecting repository boundaries and ignore rules. Use it to locate candidate paths before reading or editing them.",
+  grep: "Search project text with a bounded regular expression and contextual matches. Use it for exact literals or patterns when semantic codebase search is not appropriate.",
+  bash: "Run a shell command in the project with bounded output and timeout controls. Use it for development commands after checking side effects; background mode returns a process handle.",
+  exec: "Execute a command directly without shell interpretation, using explicit program arguments. Prefer it when argument safety and predictable process invocation matter.",
+  pwsh: "Execute a PowerShell command in the project with timeout, output, and background controls. Use it for Windows-native project operations and verify commands that can modify state.",
+  fetch: "Fetch and extract content from an approved HTTP(S) URL for research or integration work. Use it for a known page or endpoint, not for general web discovery.",
+  search: "Search the public web for current external information, then inspect selected results with fetch. Use it when repository evidence is insufficient or the fact may have changed.",
+  todo: "Create, update, or list the session\u2019s concrete work items and their progress. Use it to keep multi-step work visible; it does not implement the tasks itself.",
+  plan: "Create and manage higher-level plan-board items, priorities, and status. Use it for strategic work tracking rather than small immediate edits.",
+  kanban: "Manage project Kanban boards, cards, assignments, and acceptance evidence. Use it for persistent team workflow; changing board state is intentional and reviewable.",
+  task: "Manage structured task records, dependencies, ownership, and promotion into actionable session work. Use it to organize bounded work before delegation or execution.",
+  git: "Inspect or run scoped Git operations in the project, including status, diff, history, branches, and commits. Review the target and working tree before mutating operations.",
+  patch: "Apply a unified diff to project files with patch-style context checking. Use it for a reviewed multi-file change when exact patch content is available.",
+  json: "Read, query, validate, or update JSON files while preserving valid structure. Use it instead of raw text edits when changing structured JSON data.",
+  diff: "Compare two files, revisions, or text inputs and return a readable unified diff. Use it to review intended changes before applying or committing them.",
+  tree: "Render a bounded directory tree with depth, file, hidden-file, and ignore controls. Use it for repository orientation without reading every file.",
+  lint: "Run the project\u2019s configured linter for a target path or working directory and return diagnostics. Use it after code edits to catch style and static-analysis issues.",
+  format: "Run the project\u2019s configured formatter on selected files or directories. Use it after editing code, while reviewing the resulting diff for unintended formatting scope.",
+  typecheck: "Run TypeScript type checking for an auto-detected or specified tsconfig. Use it after type-affecting changes; it reports diagnostics without writing source files.",
+  test: "Run the detected test runner for selected tests, with optional name filtering, coverage, watch, and timeout controls. Prefer focused tests first, then broader validation as needed.",
+  language_info: "Inspect detected language tooling, workspaces, and supported operations for the project or target path. Use it before invoking language-specific tooling.",
+  language: "Run a supported language-tooling operation in a detected workspace. Use it when the language profile provides a safer, structured alternative to an arbitrary shell command.",
+  language_package: "Plan or perform a dependency operation through the detected package ecosystem. Use dry-run first when possible and specify the workspace or dependency scope deliberately.",
+  install: "Install project dependencies with the detected package manager. Use only when dependency changes are required, and inspect lockfile and manifest changes afterward.",
+  audit: "Run the package manager\u2019s dependency vulnerability audit and summarize actionable findings. Use it to assess known dependency advisories, not source-code vulnerabilities.",
+  outdated: "List outdated project dependencies and available versions without changing manifests or lockfiles. Use it to plan dependency maintenance.",
+  logs: "Read or tail configured local, container, or process logs with bounded output. Use it to investigate a known runtime failure or service behavior.",
+  document: "Generate or update project documentation from supplied scope and source context. Use it to record verified behavior; review generated text before treating it as authoritative.",
+  scaffold: "Preview or generate files from a built-in or custom scaffold template. Use dry_run first to inspect paths and content before creating project files.",
+  design: "Create a structured implementation design with goals, constraints, approach, and risks. Use it before a substantial change that needs an explicit technical decision.",
+  tool_search: "Discover registered tools by name, description, tag, permission, or mutating status. Use it to find a lazy capability before calling it through tool-use.",
+  tool_use: "Invoke a registered tool by name with its input object, including a tool discovered lazily. Use it only after confirming the target tool\u2019s schema and side effects.",
+  batch_tool_use: "Invoke several independent registered tools as a batch and return each result. Use it for parallel read-only discovery; avoid batching dependent or destructive operations.",
+  tool_help: "Show a tool\u2019s purpose, input schema, permission, and examples, or summarize the catalog. Use it before invoking an unfamiliar or lazily discovered tool.",
+  set_working_dir: "Show or change the session working directory within the permitted project scope. Use it when subsequent commands must target another project subdirectory."
+};
 var OPTIONAL_TOOLS = [
   ...browserTools,
   e2ePlanTool,
@@ -1093,7 +1198,7 @@ var TIER3_TOOLS = [
   toolHelpTool,
   setWorkingDirTool
 ];
-var builtinTools = [
+var rawBuiltinTools = [
   ...browserTools,
   e2ePlanTool,
   readTool,
@@ -1150,6 +1255,13 @@ var builtinTools = [
   toolHelpTool,
   setWorkingDirTool
 ];
+var builtinTools = rawBuiltinTools.map((tool) => {
+  const description = BUILTIN_TOOL_DESCRIPTIONS[tool.name];
+  if (!description) {
+    throw new Error(`Missing provider-facing description for built-in tool: ${tool.name}`);
+  }
+  return { ...tool, description };
+});
 
 export {
   clarifyTool,
@@ -1157,6 +1269,7 @@ export {
   pwshTool,
   analyzeSecurityAndPerformance,
   securityAstScanTool,
+  BUILTIN_TOOL_DESCRIPTIONS,
   OPTIONAL_TOOLS,
   OFF_ONLY_TOOLS,
   TIER1_TOOLS,
@@ -1164,4 +1277,4 @@ export {
   TIER3_TOOLS,
   builtinTools
 };
-//# sourceMappingURL=chunk-VALQFAY2.js.map
+//# sourceMappingURL=chunk-OTINMOKK.js.map

package/dist/{chunk-PQTONQ4P.js → chunk-QPNYDH5B.js}

@@ -56,17 +56,19 @@ var searchTool = {
     return final;
   },
   async *executeStream(input, ctx, opts) {
-    if (!input?.query || input.query.trim() === "") {
+    if (!input?.query || typeof input.query !== "string" || input.query.trim() === "") {
       throw new ToolValidationError({
         message: "search: query is required and must be a non-empty string",
         field: "query"
       });
     }
     const signal = opts?.signal ?? ctx?.signal ?? new AbortController().signal;
-    const num = Math.max(1, Math.min(input.num_results ?? DEFAULT_NUM, MAX_RESULTS));
+    const rawNum = typeof input.num_results === "number" && !Number.isNaN(input.num_results) ? input.num_results : DEFAULT_NUM;
+    const num = Math.max(1, Math.min(Math.floor(rawNum), MAX_RESULTS));
     const source = input.source ?? "duckduckgo";
     const skipCache = input.skip_cache ?? false;
-    const cacheKey = `${source}:${input.query}`;
+    const normalizedQuery = input.query.trim().toLowerCase().replace(/\s+/g, " ");
+    const cacheKey = `${source}:${normalizedQuery}`;
     if (!skipCache) {
       const entry = cache.get(cacheKey);
       if (entry && Date.now() - entry.timestamp < CACHE_TTL_MS) {
@@ -426,11 +428,23 @@ function capSnippet(snippet) {
   return snippet.length > MAX_SNIPPET_CHARS ? `${snippet.slice(0, MAX_SNIPPET_CHARS - 1)}\u2026` : snippet;
 }
 function decodeHtmlEntities(text) {
-  return text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'");
+  return text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&#x27;/gi, "'").replace(/&#039;/g, "'").replace(/&nbsp;/g, " ").replace(/&ndash;/g, "\u2013").replace(/&mdash;/g, "\u2014").replace(/&ldquo;|&rdquo;/g, '"').replace(/&lsquo;|&rsquo;/g, "'").replace(/&#(\d+);/g, (_, code) => {
+    try {
+      return String.fromCodePoint(Number(code));
+    } catch {
+      return _;
+    }
+  }).replace(/&#x([0-9a-f]+);/gi, (_, hex) => {
+    try {
+      return String.fromCodePoint(parseInt(hex, 16));
+    } catch {
+      return _;
+    }
+  });
 }
 
 export {
   searchTool,
   __clearSearchCache
 };
-//# sourceMappingURL=chunk-PQTONQ4P.js.map
+//# sourceMappingURL=chunk-QPNYDH5B.js.map