opencode-agent-skills-md 1.0.0

package/packages/opencode-agent-skills-md/src/tools.ts

@@ -0,0 +1,373 @@
+/**
+ * OpenCode tool factories.
+ *
+ * The four skill tools (get_available_skills, read_skill_file, run_skill_script,
+ * use_skill) compose the portable core engine with the OpenCode host. Tools
+ * consume the host's bounded client surface; they never reference the
+ * OpenCode SDK client or the `node:fs` module directly.
+ *
+ * `createSkillTools(host, $, directory)` returns the four tool factories
+ * pre-bound to the host, the shell runner, and the project directory. The
+ * plugin instantiates them at registration time.
+ */
+
+import type { PluginInput } from "@opencode-ai/plugin";
+import { tool } from "@opencode-ai/plugin";
+import * as path from "node:path";
+import {
+  discoverAllSkills,
+  findClosestMatch,
+  isPathSafe,
+  listSkillFiles,
+  resolveSkill,
+  searchSkills,
+} from "opencode-agent-skills-md-core";
+import type { OpencodeSkillHost } from "./host";
+
+/** Escape XML special characters to prevent wrapper breakout. */
+const escapeXml = (s: string): string => {
+  return s
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+};
+
+/** Wrap a shell argument in single quotes and escape embedded single quotes (Bourne-shell pattern). */
+const escapeShellArg = (arg: string): string => {
+  const escaped = arg.replace(/'/g, "'\\''");
+  return "'" + escaped + "'";
+};
+
+/** @internal - exported for testing */
+export const _escapeXml = escapeXml;
+/** @internal - exported for testing */
+export const _escapeShellArg = escapeShellArg;
+
+/**
+ * Portable return type for tool factory consts.
+ *
+ * The `tool()` helper captures the Zod shape of its `args` parameter in the
+ * generic parameter, so the inferred return type of each factory leaks Zod
+ * types. When TypeScript emits `.d.ts` files for the package, that generic
+ * instantiation cannot be named portably across zod versions. Annotating
+ * the return type as `ReturnType<typeof tool>` erases the per-call Zod
+ * shape and leaves a stable, portable declaration for downstream consumers.
+ */
+type SkillTool = ReturnType<typeof tool>;
+
+/**
+ * Tool translation guide for skills written for Claude Code.
+ * Injected into skill content to help the AI use OpenCode equivalents.
+ */
+export const toolTranslation = `<tool-translation>
+This skill may reference Claude Code tools. Use OpenCode equivalents:
+- TodoWrite/TodoRead -> todowrite/todoread
+- Task (subagents) -> task tool with subagent_type parameter
+- Skill tool -> use_skill tool
+- Read/Write/Edit/Bash/Glob/Grep/WebFetch -> lowercase (read/write/edit/bash/glob/grep/webfetch)
+</tool-translation>`;
+
+export interface SkillTools {
+  GetAvailableSkills: ReturnType<typeof GetAvailableSkills>;
+  ReadSkillFile: ReturnType<typeof ReadSkillFile>;
+  RunSkillScript: ReturnType<typeof RunSkillScript>;
+  UseSkill: ReturnType<typeof UseSkill>;
+}
+
+/**
+ * Callback fired by `UseSkill` after a successful load so the host can
+ * update its session-level bookkeeping (loaded-skill set, TUI icon, etc.).
+ * The core never assumes a callback is registered; missing it must not
+ * break the load.
+ */
+export type OnSkillLoaded = (sessionID: string, skillName: string) => void;
+
+/**
+ * Build the four skill tool factories bound to the host, shell, and
+ * project directory. The returned object is what the plugin registers
+ * under its `tool` hook.
+ *
+ * The optional `onSkillLoaded` callback is threaded through to `UseSkill`
+ * so a successful load can update host session state (e.g., the loaded-
+ * skill set used to suppress duplicate match injection in `chat.message`).
+ */
+export const createSkillTools = (
+  host: OpencodeSkillHost,
+  $: PluginInput["$"],
+  directory: string,
+  onSkillLoaded?: OnSkillLoaded
+): SkillTools => {
+  return {
+    GetAvailableSkills: GetAvailableSkills(directory),
+    ReadSkillFile: ReadSkillFile(directory, host),
+    RunSkillScript: RunSkillScript(directory, $),
+    UseSkill: UseSkill(directory, host, onSkillLoaded),
+  };
+};
+
+/**
+ * Resolve a skill by name, or return a "not found" message with a
+ * close-match suggestion.
+ *
+ * Centralizes the duplicated resolve-then-suggest pattern that
+ * `use_skill`, `read_skill_file`, and `run_skill_script` all need.
+ * Returning a single `string` keeps the call site trivial:
+ *
+ *   - skill found              → returns `skill.name`
+ *   - skill missing, suggestion → `Skill "<name>" not found. Did you mean "<suggestion>"?`
+ *   - skill missing, no hint    → `Skill "<name>" not found. Use get_available_skills to list available skills.`
+ *
+ * Not-found messages always start with the literal `Skill "` so callers
+ * can detect them with `result.startsWith('Skill "')`. The skill-name
+ * regex (`/^[\p{Ll}\p{N}-]+$/u`) forbids uppercase initial characters,
+ * so a legitimate skill name can never collide with that prefix.
+ *
+ * The helper does its own discovery; callers that need the `Skill` object
+ * (rather than just its name) re-resolve via a second `discoverAllSkills`
+ * call. Discovery is cheap (file-listing only) and the OS-level metadata
+ * cache absorbs most of the cost.
+ */
+export const resolveSkillOrSuggest = async (
+  directory: string,
+  skillName: string
+): Promise<string> => {
+  const skillsByName = await discoverAllSkills(directory);
+  const skill = resolveSkill(skillName, skillsByName);
+  if (skill) return skill.name;
+
+  const allSkillNames = Array.from(skillsByName.values()).map(s => s.name);
+  const suggestion = findClosestMatch(skillName, allSkillNames);
+  if (suggestion) {
+    return `Skill "${skillName}" not found. Did you mean "${suggestion}"?`;
+  }
+  return `Skill "${skillName}" not found. Use get_available_skills to list available skills.`;
+};
+
+const GetAvailableSkills = (directory: string): SkillTool => {
+  return tool({
+    description:
+      "Get available skills with their descriptions. Optionally filter by free-text query and/or tag keywords.",
+    args: {
+      query: tool.schema.string().optional()
+        .describe("Free-text search query. Matched against skill name and description; relevance-ranked."),
+      keywords: tool.schema.array(tool.schema.string()).optional()
+        .describe("Optional list of tag keywords. Only skills whose metadata.tags include at least one entry are returned.")
+    },
+    async execute(args) {
+      const skillsByName = await discoverAllSkills(directory);
+      const allSkills = Array.from(skillsByName.values());
+
+      const matched = searchSkills(allSkills, args.query ?? "", args.keywords);
+
+      if (matched.length === 0) {
+        if (args.query) {
+          const allSkillNames = allSkills.map(s => s.name);
+          const suggestion = findClosestMatch(args.query, allSkillNames);
+
+          if (suggestion) {
+            return `No skills found matching "${args.query}". Did you mean "${suggestion}"?`;
+          }
+        }
+
+        return "No skills found matching your query.";
+      }
+
+      return matched
+        .map(s => {
+          const scripts = s.scripts.length > 0
+            ? ` [scripts: ${s.scripts.map(sc => sc.relativePath).join(', ')}]`
+            : '';
+          // PR 2: render `trigger: <text>` on its own line when set.
+          // The always-on `<available-skills>` block stays compact; only
+          // this targeted listing surfaces the trigger.
+          const trigger = s.trigger && s.trigger.length > 0
+            ? `\n  trigger: ${s.trigger}`
+            : '';
+          return `${s.name} (${s.label})\n  ${s.description}${trigger}${scripts}`;
+        })
+        .join('\n\n');
+    }
+  });
+};
+
+const ReadSkillFile = (directory: string, host: OpencodeSkillHost): SkillTool => {
+  return tool({
+    description: "Read a supporting file from a skill's directory (docs, examples, configs).",
+    args: {
+      skill: tool.schema.string()
+        .describe("Name of the skill"),
+      filename: tool.schema.string()
+        .describe("File to read, relative to skill directory (e.g., 'anthropic-best-practices.md', 'scripts/helper.sh')")
+    },
+    async execute(args, ctx) {
+      const resolved = await resolveSkillOrSuggest(directory, args.skill);
+      if (resolved.startsWith('Skill "')) return resolved;
+
+      // Helper confirmed existence; resolve to the full Skill object so we
+      // can read its path, scripts, and other metadata below.
+      const skillsByName = await discoverAllSkills(directory);
+      const skill = skillsByName.get(resolved);
+      if (!skill) {
+        return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+      }
+
+      // Security: ensure path doesn't escape skill directory
+      if (!(await isPathSafe(skill.path, args.filename))) {
+        return `Invalid path: cannot access files outside skill directory.`;
+      }
+
+      const filePath = path.join(skill.path, args.filename);
+
+      try {
+        const content = await host.client.readFile(filePath);
+
+        // Inject via noReply for context persistence
+        const wrappedContent = `<skill-file skill="${escapeXml(skill.name)}" file="${escapeXml(args.filename)}">
+  <metadata>
+    <directory>${escapeXml(skill.path)}</directory>
+  </metadata>
+
+  <content>
+${content}
+  </content>
+</skill-file>`;
+
+        const context = await host.client.getSessionContext(ctx.sessionID);
+        await host.client.injectContent(ctx.sessionID, wrappedContent, context);
+
+        return `File "${args.filename}" from skill "${skill.name}" loaded.`;
+      } catch {
+        try {
+          const files = await host.client.readdir(skill.path);
+          return `File "${args.filename}" not found. Available files: ${files.join(', ')}`;
+        } catch {
+          return `File "${args.filename}" not found in skill "${skill.name}".`;
+        }
+      }
+    }
+  });
+};
+
+const RunSkillScript = (directory: string, $: PluginInput["$"]): SkillTool => {
+  return tool({
+    description: "Execute a script from a skill's directory. Scripts are run with the skill directory as CWD.",
+    args: {
+      skill: tool.schema.string()
+        .describe("Name of the skill"),
+      script: tool.schema.string()
+        .describe("Relative path to the script (e.g., 'build.sh', 'tools/deploy.sh')"),
+      arguments: tool.schema.array(tool.schema.string()).optional()
+        .describe("Arguments to pass to the script")
+    },
+    async execute(args) {
+      const resolved = await resolveSkillOrSuggest(directory, args.skill);
+      if (resolved.startsWith('Skill "')) return resolved;
+
+      // Helper confirmed existence; resolve to the full Skill object so we
+      // can inspect its scripts and run them below.
+      const skillsByName = await discoverAllSkills(directory);
+      const skill = skillsByName.get(resolved);
+      if (!skill) {
+        return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+      }
+
+      const script = skill.scripts.find(s => s.relativePath === args.script);
+
+      if (!script) {
+        const scriptPaths = skill.scripts.map(s => s.relativePath);
+        const suggestion = findClosestMatch(args.script, scriptPaths);
+
+        if (suggestion) {
+          return `Script "${args.script}" not found in skill "${skill.name}". Did you mean "${suggestion}"?`;
+        }
+
+        const available = scriptPaths.join(', ') || 'none';
+        return `Script "${args.script}" not found in skill "${skill.name}". Available scripts: ${available}`;
+      }
+
+      try {
+        $.cwd(skill.path);
+        const scriptArgs = (args.arguments || []).map(escapeShellArg).join(' ');
+        const result = await $`${script.absolutePath} ${scriptArgs}`.text();
+        return result;
+      } catch (error: unknown) {
+        if (error instanceof Error && 'exitCode' in error) {
+          const shellError = error as Error & { exitCode: number; stderr?: Buffer; stdout?: Buffer };
+          const stderr = shellError.stderr?.toString() || '';
+          const stdout = shellError.stdout?.toString() || '';
+          return `Script failed (exit ${shellError.exitCode}): ${stderr || stdout || shellError.message}`;
+        }
+        if (error instanceof Error) {
+          return `Script failed: ${error.message}`;
+        }
+        return `Script failed: ${String(error)}`;
+      }
+    }
+  });
+};
+
+const UseSkill = (
+  directory: string,
+  host: OpencodeSkillHost,
+  onSkillLoaded?: (sessionID: string, skillName: string) => void
+): SkillTool => {
+  return tool({
+    description: "Load a skill's SKILL.md content into context. Skills contain proven workflows, techniques, and patterns.",
+    args: {
+      skill: tool.schema.string()
+        .describe("Name of the skill (e.g., 'brainstorming', 'project:my-skill', 'user:my-skill')")
+    },
+    async execute(args, ctx) {
+      const resolved = await resolveSkillOrSuggest(directory, args.skill);
+      if (resolved.startsWith('Skill "')) return resolved;
+
+      // Helper confirmed existence; resolve to the full Skill object so we
+      // can read its template, scripts, and files for injection below.
+      const skillsByName = await discoverAllSkills(directory);
+      const skill = skillsByName.get(resolved);
+      if (!skill) {
+        return `Skill "${args.skill}" not found. Use get_available_skills to list available skills.`;
+      }
+
+      const skillFiles = await listSkillFiles(skill.path);
+
+      const scriptsXml = skill.scripts.length > 0
+        ? `\n    <scripts>\n${skill.scripts.map(s => `      <script>${escapeXml(s.relativePath)}</script>`).join('\n')}\n    </scripts>`
+        : '';
+
+      const filesXml = skillFiles.length > 0
+        ? `\n    <files>\n${skillFiles.map(f => `      <file>${escapeXml(f)}</file>`).join('\n')}\n    </files>`
+        : '';
+
+      const skillContent = `<skill name="${escapeXml(skill.name)}">
+  <metadata>
+    <source>${escapeXml(skill.label)}</source>
+    <directory>${escapeXml(skill.path)}</directory>${scriptsXml}${filesXml}
+  </metadata>
+
+  ${toolTranslation}
+
+  <content>
+${skill.template}
+  </content>
+</skill>`;
+
+      const context = await host.client.getSessionContext(ctx.sessionID);
+      await host.client.injectContent(ctx.sessionID, skillContent, context);
+
+      onSkillLoaded?.(ctx.sessionID, skill.name);
+
+      const scriptInfo = skill.scripts.length > 0
+        ? `\nAvailable scripts: ${skill.scripts.map(s => s.relativePath).join(', ')}`
+        : '';
+
+      const filesInfo = skillFiles.length > 0
+        ? `\nAvailable files: ${skillFiles.join(', ')}`
+        : '';
+
+      return `Skill "${skill.name}" loaded.${scriptInfo}${filesInfo}`;
+    }
+  });
+};