@wrongstack/tools 0.310.1 → 0.313.1

package/dist/chunk-GOIZNNOA.js

@@ -0,0 +1,221 @@
+// src/skill.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {
+  missingRequiredRuntimeTools,
+  missingRuntimeCapabilities,
+  runtimeToolReferencesFromText
+} from "@wrongstack/core/agent-catalog";
+import { SKILL_LIMITS, stripFrontmatter } from "@wrongstack/core/skills";
+import { ToolValidationError } from "@wrongstack/core/types";
+var MAX_BODY_CHARS = SKILL_LIMITS.MAX_SKILL_BODY_CHARS;
+var MAX_RESOURCE_CHARS = SKILL_LIMITS.MAX_RESOURCE_CHARS;
+var MAX_LISTED_RESOURCES = SKILL_LIMITS.MAX_LISTED_RESOURCES;
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build"]);
+function makeSkillTool(skillLoader) {
+  return {
+    name: "skill",
+    category: "Skills",
+    description: "Load a skill's instructions or a bundled resource on demand (agentskills.io progressive disclosure). With only `name`: returns the SKILL.md body + a list of bundled resource files. With `name` + `resource` (a relative path like `references/REF.md` or `scripts/extract.py`): returns that file content. Prefer this over the read tool for skill files \u2014 it reaches foreign skills outside the project root.",
+    usageHint: 'Load a skill body or one of its bundled resources (progressive disclosure).\n\nWHEN TO USE:\n- A task matches a skill trigger \u2192 load the body: skill({ name })\n- You need a reference/template/script bundled with the skill \u2192 skill({ name, resource: "references/REF.md" })\n\nThe body call lists every bundled resource; load the ones you need. Run scripts via bash using the returned abs path.',
+    permission: "auto",
+    mutating: false,
+    capabilities: ["fs.read"],
+    icon: "document",
+    timeoutMs: 5e3,
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Exact skill name (as shown in the available-skills list)."
+        },
+        resource: {
+          type: "string",
+          description: "Optional relative path of a bundled resource to load (e.g. references/REF.md, scripts/extract.py, assets/template.html). Omit to list resources."
+        }
+      },
+      required: ["name"]
+    },
+    async execute(input, ctx) {
+      const name = input?.name?.trim();
+      if (!name) {
+        throw new ToolValidationError({ message: "skill: name is required", field: "name" });
+      }
+      const manifest = await skillLoader.find(name);
+      if (!manifest) {
+        throw new ToolValidationError({
+          message: `skill "${name}" not found \u2014 use /skill to list available skills`,
+          field: "name"
+        });
+      }
+      const availableToolNames = (ctx?.catalogTools ?? ctx?.tools ?? []).map((tool) => tool.name);
+      const missingCapabilities = missingRuntimeCapabilities(
+        manifest.requiredCapabilities,
+        availableToolNames
+      );
+      const missingTools = missingRequiredRuntimeTools(manifest.requiredTools, availableToolNames);
+      if (missingCapabilities.length > 0 || missingTools.length > 0) {
+        throw new ToolValidationError({
+          message: `skill "${name}" is unavailable in this runtime; ` + [
+            missingCapabilities.length > 0 ? `missing capabilities: ${missingCapabilities.join(", ")}` : "",
+            missingTools.length > 0 ? `missing tools: ${missingTools.join(", ")}` : ""
+          ].filter(Boolean).join("; "),
+          field: "name"
+        });
+      }
+      const dir = path.dirname(manifest.path);
+      let loadedResource;
+      if (input.resource?.trim()) {
+        loadedResource = await loadResource(dir, input.resource.trim());
+      }
+      const raw = await skillLoader.readBody(name);
+      const missingBodyTools = missingRequiredRuntimeTools(
+        runtimeToolReferencesFromText(raw),
+        availableToolNames
+      );
+      const warning = missingBodyTools.length > 0 ? `Warning: skill "${name}" references tools not registered in this runtime: ${missingBodyTools.join(", ")}. Steps that call them may be unavailable.` : void 0;
+      const body = stripFrontmatter(raw).trim().slice(0, MAX_BODY_CHARS);
+      const resources = loadedResource ? [] : await listResources(dir);
+      try {
+        await ctx?.session?.append({
+          type: "skill_activated",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          skillName: manifest.name
+        });
+      } catch {
+      }
+      return {
+        name: manifest.name,
+        description: manifest.description,
+        body,
+        resources,
+        dir,
+        loadedResource,
+        warning
+      };
+    },
+    serialize(output) {
+      const warningLine = output.warning ? `
+
+${output.warning}` : "";
+      if (output.loadedResource) {
+        const lr = output.loadedResource;
+        const note = lr.truncated ? ` (truncated to ${lr.content.length} chars of ${lr.bytes} B)` : "";
+        return `# Resource: ${output.name}/${lr.rel}
+(abs path: ${lr.absPath})${note}
+
+${lr.content}${warningLine}`;
+      }
+      const head = `# Skill: ${output.name}
+${output.description}
+
+${output.body}`;
+      if (output.resources.length === 0) return `${head}${warningLine}`;
+      const listing = output.resources.map((r) => `- ${r.path} (${r.bytes} B)`).join("\n");
+      return `${head}
+
+## Bundled resources (load on demand)
+Load any with: \`skill({ name: "${output.name}", resource: "<path>" })\`. Run scripts via bash using their abs path under ${output.dir}.
+${listing}${warningLine}`;
+    }
+  };
+}
+async function loadResource(skillDir, rel) {
+  const norm = rel.replace(/\\/g, "/");
+  if (path.isAbsolute(rel) || norm.split("/").some((seg) => seg === "..")) {
+    throw new ToolValidationError({
+      message: `skill: invalid resource path "${rel}"`,
+      field: "resource"
+    });
+  }
+  const absPath = path.resolve(skillDir, rel);
+  const root = path.resolve(skillDir);
+  if (absPath !== root && !absPath.startsWith(root + path.sep)) {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" escapes the skill directory`,
+      field: "resource"
+    });
+  }
+  let realPath;
+  let realRoot;
+  try {
+    realRoot = await fs.realpath(root);
+    realPath = await fs.realpath(absPath);
+  } catch {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" not readable`,
+      field: "resource"
+    });
+  }
+  if (realPath !== realRoot && !realPath.startsWith(realRoot + path.sep)) {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" resolves outside the skill directory`,
+      field: "resource"
+    });
+  }
+  let buf;
+  try {
+    buf = await fs.readFile(realPath);
+  } catch {
+    throw new ToolValidationError({
+      message: `skill: resource "${rel}" not readable`,
+      field: "resource"
+    });
+  }
+  const raw = buf.toString("utf8");
+  const truncated = raw.length > MAX_RESOURCE_CHARS;
+  return {
+    rel: norm,
+    // The canonical path — the one actually opened, and the one a follow-up
+    // `bash` invocation should use.
+    absPath: realPath,
+    content: truncated ? raw.slice(0, MAX_RESOURCE_CHARS) : raw,
+    bytes: buf.length,
+    truncated
+  };
+}
+async function listResources(skillDir) {
+  const out = [];
+  await walk(skillDir, skillDir, out);
+  out.sort((a, b) => a.path.localeCompare(b.path));
+  return out.slice(0, MAX_LISTED_RESOURCES);
+}
+async function walk(root, dir, out) {
+  if (out.length >= MAX_LISTED_RESOURCES) return;
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (out.length >= MAX_LISTED_RESOURCES) return;
+    const fullPath = path.join(dir, e.name);
+    let isDir = e.isDirectory();
+    if (e.isSymbolicLink()) {
+      try {
+        isDir = (await fs.stat(fullPath)).isDirectory();
+      } catch {
+        continue;
+      }
+    }
+    if (isDir) {
+      if (SKIP_DIRS.has(e.name) || e.name.startsWith(".")) continue;
+      await walk(root, fullPath, out);
+    } else if (e.isFile()) {
+      if (e.name === "SKILL.md" || e.name === "SKILL.save.md") continue;
+      try {
+        const stat2 = await fs.stat(fullPath);
+        const rel = path.relative(root, fullPath).split(path.sep).join("/");
+        out.push({ path: rel, bytes: stat2.size });
+      } catch {
+      }
+    }
+  }
+}
+
+export {
+  makeSkillTool
+};
+//# sourceMappingURL=chunk-GOIZNNOA.js.map

package/dist/chunk-H5MJUAA6.js

@@ -0,0 +1,295 @@
+import {
+  getIndexState,
+  searchCodebaseIndex
+} from "./chunk-2ME7ZWDD.js";
+import {
+  codebaseIndexDirOverride
+} from "./chunk-OA6YJIWL.js";
+import {
+  isBinaryBuffer,
+  safeResolveReal,
+  sha256hex
+} from "./chunk-D33S4RQG.js";
+
+// src/read.ts
+import * as fs from "node:fs/promises";
+import { FsError, ToolValidationError } from "@wrongstack/core/types";
+import { toErrorMessage } from "@wrongstack/core/utils";
+var ADVANCED_MODE_META_KEY = "tools.read.advancedMode";
+var MAX_BYTES = 5 * 1024 * 1024;
+var readTool = {
+  name: "read",
+  category: "Filesystem",
+  description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed in the form `N\u2192content` (line number, then a `\u2192` separator, then the raw line). The `N\u2192` prefix is display-only \u2014 always strip it before reusing the text, e.g. never include it in `edit.old_string`. When advanced mode is on or `includeSymbols` is set, the result also includes a `symbols` field listing codebase-index symbol names, kinds, and line numbers for the file (not file content).",
+  usageHint: "FOUNDATIONAL TOOL \u2014 call this before almost any edit operation.\n\nBest practices:\n- Always read a file before using `edit`, `replace`, or `write` on it (the system often requires it for safety).\n- Use `offset` + `limit` for very large files instead of reading everything at once.\n- Default limit is generous (2000 lines) but can be increased.\n- The output format is designed to be directly usable as context for `edit` operations.\n- Set `includeSymbols: true` to also receive the codebase-index symbol listing for the file.\n- Enable advanced mode (`ctx.meta['tools.read.advancedMode'] = true`) to auto-inject symbols on every read.",
+  selection: {
+    doNotUseWhen: "you need to search many files for matching content.",
+    useInstead: ["grep"]
+  },
+  permission: "auto",
+  mutating: false,
+  capabilities: ["fs.read"],
+  icon: "file",
+  maxOutputBytes: 262144,
+  timeoutMs: 5e3,
+  inputSchema: {
+    type: "object",
+    properties: {
+      path: {
+        type: "string",
+        description: "Path to the file (relative to project root or absolute within project)."
+      },
+      offset: {
+        type: "integer",
+        minimum: 1,
+        description: "1-based starting line number. Use together with `limit` for large files."
+      },
+      limit: {
+        type: "integer",
+        minimum: 0,
+        description: "Maximum number of lines to return (default 2000). Values above 5000 are clamped to 5000 \u2014 page with `offset` for more."
+      },
+      mode: {
+        type: "string",
+        enum: ["content", "summary"],
+        description: "Return full line-numbered content (default) or a compact file summary with imports/exports/symbols."
+      },
+      includeSymbols: {
+        type: "boolean",
+        description: "When true, include the codebase-index symbol list for this file as a structured `symbols` field in the result. Overrides the advanced-mode meta flag per-call."
+      }
+    },
+    required: ["path"]
+  },
+  async execute(input, ctx, execOpts) {
+    if (!input?.path) {
+      throw new ToolValidationError({
+        message: "read: path is required",
+        field: "path"
+      });
+    }
+    const absPath = await safeResolveReal(input.path, ctx);
+    const shouldIncludeSymbols = input.includeSymbols === true || input.includeSymbols !== false && ctx.meta[ADVANCED_MODE_META_KEY] === true;
+    let stat2;
+    try {
+      stat2 = await fs.stat(absPath);
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT") {
+        throw new FsError({
+          message: `read: file not found "${input.path}"`,
+          code: "FS_READ_FAILED",
+          path: absPath,
+          context: { errno: "ENOENT" }
+        });
+      }
+      throw new FsError({
+        message: `read: failed to stat "${input.path}": ${toErrorMessage(err)}`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { errno: code },
+        cause: err
+      });
+    }
+    if (!stat2.isFile()) {
+      throw new FsError({
+        message: `read: "${input.path}" is not a regular file`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "not-a-regular-file" }
+      });
+    }
+    if (stat2.size > MAX_BYTES) {
+      throw new FsError({
+        message: `read: file too large (${stat2.size} bytes, limit ${MAX_BYTES})`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { size: stat2.size, limit: MAX_BYTES, reason: "too-large" }
+      });
+    }
+    const offset = Math.max(1, input.offset ?? 1);
+    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    const prior = getReadRangeRecord(ctx, absPath);
+    const requestedEnd = prior ? Math.min(offset + limit - 1, prior.totalLines) : offset + limit - 1;
+    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat2.mtimeMs, offset, requestedEnd)) {
+      ctx.recordRead(absPath, stat2.mtimeMs);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat2.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
+        total_lines: prior.totalLines,
+        encoding: "utf8",
+        truncated: requestedEnd < prior.totalLines,
+        cached: true,
+        note: mergeSymbolNote("Repeated read suppressed to save tokens.", symResult2?.note),
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {}
+      };
+    }
+    const buf = await fs.readFile(absPath);
+    if (isBinaryBuffer(buf)) {
+      throw new FsError({
+        message: `read: "${input.path}" appears to be binary`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "binary" }
+      });
+    }
+    const text = buf.toString("utf8");
+    const contentHash = sha256hex(text);
+    const allLines = text.split(/\r\n|\r|\n/);
+    const total = allLines.length;
+    if (input.mode === "summary") {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, 1, Math.min(total, 200));
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: summarizeFile(input.path, stat2.size, allLines),
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 200,
+        note: mergeSymbolNote(
+          "Summary mode returned compact structure instead of full file content.",
+          symResult2?.note
+        ),
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {}
+      };
+    }
+    if (limit === 0) {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, 1, 0);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: "",
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 0,
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {},
+        ...symResult2?.note ? { note: symResult2.note } : {}
+      };
+    }
+    if (offset > total) {
+      ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+      rememberReadRange(ctx, absPath, stat2.mtimeMs, total, total + 1, total + 1);
+      const symResult2 = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+      return {
+        text: `[offset ${offset} is past end of file "${input.path}" \u2014 file has ${total} line(s). Do not retry this offset.]`,
+        total_lines: total,
+        encoding: "utf8",
+        truncated: false,
+        ...symResult2?.symbols ? { symbols: symResult2.symbols } : {},
+        ...symResult2?.note ? { note: symResult2.note } : {}
+      };
+    }
+    const slice = allLines.slice(offset - 1, offset - 1 + limit);
+    const truncated = offset - 1 + slice.length < total;
+    const width = String(offset + slice.length - 1).length;
+    const numbered = slice.map((line, i) => `${String(offset + i).padStart(width, " ")}\u2192${line}`).join("\n");
+    ctx.recordRead(absPath, stat2.mtimeMs, "user", contentHash);
+    rememberReadRange(ctx, absPath, stat2.mtimeMs, total, offset, offset + slice.length - 1);
+    const symResult = shouldIncludeSymbols ? await fetchSymbolsForFile(absPath, ctx, execOpts?.signal) : void 0;
+    return {
+      text: numbered,
+      total_lines: total,
+      encoding: "utf8",
+      truncated,
+      ...symResult?.symbols ? { symbols: symResult.symbols } : {},
+      ...symResult?.note ? { note: symResult.note } : {}
+    };
+  }
+};
+async function fetchSymbolsForFile(absPath, ctx, signal) {
+  try {
+    const state = getIndexState();
+    if (!state.ready) return {};
+    const { results, total } = await searchCodebaseIndex(
+      {
+        projectRoot: ctx.projectRoot,
+        indexDir: codebaseIndexDirOverride(ctx),
+        query: "",
+        file: absPath,
+        limit: 500
+      },
+      { signal }
+    );
+    if (results.length === 0) return {};
+    const sorted = results.map((r) => ({
+      name: r.name,
+      kind: r.kind,
+      line: r.line,
+      col: r.col,
+      signature: r.signature
+    })).sort((a, b) => a.line - b.line || a.col - b.col);
+    const result = { symbols: sorted };
+    if (total > results.length) {
+      result.note = `Symbol listing truncated to ${results.length} of ${total} entries.`;
+    }
+    return result;
+  } catch {
+    return {};
+  }
+}
+function mergeSymbolNote(note, symNote) {
+  if (!symNote) return note;
+  if (!note) return symNote;
+  return `${note} ${symNote}`;
+}
+var READ_RANGES_META_KEY = "tools.read.ranges.v1";
+function getReadRanges(ctx) {
+  const existing = ctx.meta[READ_RANGES_META_KEY];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    return existing;
+  }
+  const next = {};
+  ctx.meta[READ_RANGES_META_KEY] = next;
+  return next;
+}
+function getReadRangeRecord(ctx, absPath) {
+  return getReadRanges(ctx)[absPath];
+}
+function rememberReadRange(ctx, absPath, mtimeMs, totalLines, start, end) {
+  if (end < start) return;
+  const ranges = getReadRanges(ctx);
+  const prior = ranges[absPath];
+  const nextRanges = prior && Math.abs(prior.mtimeMs - mtimeMs) <= 1 ? prior.ranges.slice() : [];
+  nextRanges.push({ start, end });
+  ranges[absPath] = {
+    mtimeMs,
+    totalLines,
+    ranges: mergeRanges(nextRanges)
+  };
+}
+function coversRange(record, mtimeMs, start, end) {
+  if (Math.abs(record.mtimeMs - mtimeMs) > 1) return false;
+  return record.ranges.some((range) => range.start <= start && range.end >= end);
+}
+function mergeRanges(ranges) {
+  const sorted = ranges.slice().sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (!last || range.start > last.end + 1) {
+      merged.push({ ...range });
+      continue;
+    }
+    last.end = Math.max(last.end, range.end);
+  }
+  return merged;
+}
+function summarizeFile(filePath, bytes, lines) {
+  const interesting = lines.map((line, index) => ({ line: line.trim(), number: index + 1 })).filter(
+    ({ line }) => /^(import\s|export\s|class\s|interface\s|type\s|function\s|const\s+\w+\s*=|let\s+\w+\s*=|var\s+\w+\s*=|def\s+|async\s+function\s)/.test(
+      line
+    )
+  ).slice(0, 80).map(({ line, number }) => `${number}: ${line}`);
+  return [
+    `summary: ${filePath}`,
+    `bytes=${bytes}`,
+    `total_lines=${lines.length}`,
+    interesting.length > 0 ? `symbols/imports:
+${interesting.join("\n")}` : "symbols/imports: (none detected)"
+  ].join("\n");
+}
+
+export {
+  readTool
+};
+//# sourceMappingURL=chunk-H5MJUAA6.js.map