minimal-agent 0.11.0 → 0.13.0

package/src/tools/shared/diffSummary.ts

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { createTwoFilesPatch, diffLines } from 'diff';
+
+import type { FilePatchSummary } from '../../types.js';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 200_000;
+const MAX_DIFF_CHARS = 16_000;
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function buildPatchSummary(
+  before: string,
+  after: string,
+  label: string,
+): FilePatchSummary {
+  const beforeHash = hash(before);
+  const afterHash = hash(after);
+  const totalBytes = Buffer.byteLength(before) + Buffer.byteLength(after);
+  const totalLines =
+    (before.match(/\n/g)?.length ?? 0) + (after.match(/\n/g)?.length ?? 0) + 2;
+  if (totalBytes > MAX_BYTES || totalLines > MAX_LINES) {
+    return {
+      beforeHash,
+      afterHash,
+      additions: 0,
+      deletions: 0,
+      truncated: true,
+      omittedReason: 'too_large',
+    };
+  }
+
+  const changes = diffLines(before, after);
+  const additions = changes
+    .filter((change) => change.added)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  const deletions = changes
+    .filter((change) => change.removed)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  let unifiedDiff = createTwoFilesPatch(
+    `a/${label}`,
+    `b/${label}`,
+    before,
+    after,
+    undefined,
+    undefined,
+    { context: 3 },
+  );
+  const truncated = unifiedDiff.length > MAX_DIFF_CHARS;
+  if (truncated) {
+    unifiedDiff = `${unifiedDiff.slice(0, MAX_DIFF_CHARS)}\n... (diff preview truncated)`;
+  }
+  return {
+    unifiedDiff,
+    beforeHash,
+    afterHash,
+    additions,
+    deletions,
+    truncated,
+  };
+}

package/src/tools/shared/fileActivity.js

@@ -22,7 +22,7 @@ function within(root, candidate) {
         return rel === '' ? '' : null;
     return rel.split(sep).join('/');
 }
-export async function fileActivityMetadata(filePath, activity, verification = 'not_run', purpose = activity === 'read' ? 'source' : 'support', cwd = getWorkingDir()) {
+export async function fileActivityMetadata(filePath, activity, verification = 'not_run', purpose = activity === 'read' ? 'source' : 'support', cwd = getWorkingDir(), patch) {
     const lexicalRoot = resolve(cwd);
     const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
     const candidate = await realpath(filePath).catch(() => resolve(filePath));
@@ -45,6 +45,7 @@ export async function fileActivityMetadata(filePath, activity, verification = 'n
                 ...(MIME_BY_EXT[extname(relativePath).toLowerCase()] ? { mime: MIME_BY_EXT[extname(relativePath).toLowerCase()] } : {}),
                 verification,
                 purpose,
+                ...(patch ? { patch } : {}),
             }],
     };
 }

package/src/tools/shared/fileActivity.ts

@@ -8,6 +8,7 @@ import type {
   FileActivityKind,
   FileActivityMetadata,
   FileVerification,
+  FilePatchSummary,
 } from '../../types.js';
 
 const MIME_BY_EXT: Record<string, string> = {
@@ -37,6 +38,7 @@ export async function fileActivityMetadata(
   verification: FileVerification = 'not_run',
   purpose: ConversationFilePurpose = activity === 'read' ? 'source' : 'support',
   cwd = getWorkingDir(),
+  patch?: FilePatchSummary,
 ): Promise<FileActivityMetadata | undefined> {
   const lexicalRoot = resolve(cwd);
   const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
@@ -58,6 +60,7 @@ export async function fileActivityMetadata(
       ...(MIME_BY_EXT[extname(relativePath).toLowerCase()] ? { mime: MIME_BY_EXT[extname(relativePath).toLowerCase()] } : {}),
       verification,
       purpose,
+      ...(patch ? { patch } : {}),
     }],
   };
 }

package/src/tools/shared/permanentDeleteGuard.js

@@ -0,0 +1,57 @@
+/**
+ * 永久删除守卫：把「绕过回收站的删除」从 shell 里挡回去，逼模型改用可恢复的 Trash。
+ *
+ * ⚠️ 可靠性边界（与 src/irreversible/rules.ts 同一标准，别高估它）：
+ * 这是**防模型误删**的护栏，不是对抗性沙盒。判据是对命令文本做正则匹配，
+ * 因此下列写法一律漏过，且**有意不追**（越追越像军备竞赛，误伤率先爆）：
+ *   · 绝对路径调用    /bin/rm -rf x
+ *   · 间接执行        xargs rm / find -exec rm / echo $(rm x)
+ *   · 换语言          python -c "import shutil; shutil.rmtree('x')"
+ *   · 跨 shell 转发   cmd 里 powershell -c "Remove-Item x"
+ * 真正兜底的是「模型没有恶意」+ Trash 提供了更顺手的替代路径，不是这张正则表。
+ *
+ * ⚠️ `shell` 必须是**实际执行命令的那个 shell**，不是调用它的工具名。
+ * Bash 工具在 win32 找不到 Git Bash 时会回落 cmd.exe（见 tools/bash/bash.ts 的
+ * WIN_BASH 探测，且它的 description 会主动告诉模型「这里是 cmd」），那时模型写的是
+ * cmd 语法（del / rd），若仍按 'bash' 匹配 —— 三层防护全部落空、文件直接永久丢失。
+ */
+/** POSIX shell：删除动词在命令位置（串首或 ; & | 换行之后）。 */
+const BASH_DELETE = [
+    /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+    /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i,
+];
+/**
+ * cmd.exe：del / erase 删文件，rd / rmdir 删目录，一律不进回收站。
+ * 分隔符**必须含 `&`** —— cmd 用 `&` / `&&` 串命令，这正是 POWERSHELL_DELETE
+ * 的分隔符类 `[;|\n]` 不能直接复用的原因。
+ * `rm` 一并收进来：Git 的 usr\bin 可能在 PATH 上（此时 rm.exe 可用），而 cmd 本身没有 rm。
+ */
+const CMD_DELETE = [/(?:^|[;&|\n])\s*(?:del|erase|rd|rmdir|rm)\b/i];
+const GIT_CLEAN = /(?:^|[;&|\n])\s*git\b[^\n;&|]*\bclean\b([^\n;&|]*)/i;
+const POWERSHELL_DELETE = [
+    /(?:^|[;|\n])\s*(?:Remove-Item|Clear-RecycleBin)\b/i,
+    /(?:^|[;|\n])\s*(?:del|erase|rd|rmdir|rm|ri)\b/i,
+    /\.Delete\s*\(/i,
+];
+const RULES = {
+    bash: BASH_DELETE,
+    cmd: CMD_DELETE,
+    powershell: POWERSHELL_DELETE,
+};
+export function permanentDeleteReason(command, shell) {
+    let hit = RULES[shell].some((pattern) => pattern.test(command));
+    // `git clean -f` 三种 shell 里都能跑、都永久删除，所以不按 shell 分支。
+    // `-n` / `--dry-run` 是只读预演，必须放行（否则模型连"先看看会删什么"都做不到）。
+    if (!hit) {
+        const gitClean = GIT_CLEAN.exec(command);
+        const options = gitClean?.[1] ?? '';
+        const dryRun = /--dry-run\b/.test(options) ||
+            /(?:^|\s)-[a-z]*n[a-z]*(?:\s|$)/i.test(options);
+        hit = Boolean(gitClean &&
+            !dryRun &&
+            /(?:^|\s)-[a-z]*f[a-z]*(?:\s|$)|--force\b/i.test(options));
+    }
+    return hit
+        ? '该命令会绕过系统回收站永久删除文件。请改用 Trash；清理 Git 未跟踪文件请用 Trash(action="git-clean")。'
+        : undefined;
+}

package/src/tools/shared/permanentDeleteGuard.ts

@@ -0,0 +1,71 @@
+/**
+ * 永久删除守卫：把「绕过回收站的删除」从 shell 里挡回去，逼模型改用可恢复的 Trash。
+ *
+ * ⚠️ 可靠性边界（与 src/irreversible/rules.ts 同一标准，别高估它）：
+ * 这是**防模型误删**的护栏，不是对抗性沙盒。判据是对命令文本做正则匹配，
+ * 因此下列写法一律漏过，且**有意不追**（越追越像军备竞赛，误伤率先爆）：
+ *   · 绝对路径调用    /bin/rm -rf x
+ *   · 间接执行        xargs rm / find -exec rm / echo $(rm x)
+ *   · 换语言          python -c "import shutil; shutil.rmtree('x')"
+ *   · 跨 shell 转发   cmd 里 powershell -c "Remove-Item x"
+ * 真正兜底的是「模型没有恶意」+ Trash 提供了更顺手的替代路径，不是这张正则表。
+ *
+ * ⚠️ `shell` 必须是**实际执行命令的那个 shell**，不是调用它的工具名。
+ * Bash 工具在 win32 找不到 Git Bash 时会回落 cmd.exe（见 tools/bash/bash.ts 的
+ * WIN_BASH 探测，且它的 description 会主动告诉模型「这里是 cmd」），那时模型写的是
+ * cmd 语法（del / rd），若仍按 'bash' 匹配 —— 三层防护全部落空、文件直接永久丢失。
+ */
+
+/** POSIX shell：删除动词在命令位置（串首或 ; & | 换行之后）。 */
+const BASH_DELETE = [
+  /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+  /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\b/i,
+];
+
+/**
+ * cmd.exe：del / erase 删文件，rd / rmdir 删目录，一律不进回收站。
+ * 分隔符**必须含 `&`** —— cmd 用 `&` / `&&` 串命令，这正是 POWERSHELL_DELETE
+ * 的分隔符类 `[;|\n]` 不能直接复用的原因。
+ * `rm` 一并收进来：Git 的 usr\bin 可能在 PATH 上（此时 rm.exe 可用），而 cmd 本身没有 rm。
+ */
+const CMD_DELETE = [/(?:^|[;&|\n])\s*(?:del|erase|rd|rmdir|rm)\b/i];
+
+const GIT_CLEAN = /(?:^|[;&|\n])\s*git\b[^\n;&|]*\bclean\b([^\n;&|]*)/i;
+
+const POWERSHELL_DELETE = [
+  /(?:^|[;|\n])\s*(?:Remove-Item|Clear-RecycleBin)\b/i,
+  /(?:^|[;|\n])\s*(?:del|erase|rd|rmdir|rm|ri)\b/i,
+  /\.Delete\s*\(/i,
+];
+
+export type ShellKind = 'bash' | 'cmd' | 'powershell';
+
+const RULES: Readonly<Record<ShellKind, RegExp[]>> = {
+  bash: BASH_DELETE,
+  cmd: CMD_DELETE,
+  powershell: POWERSHELL_DELETE,
+};
+
+export function permanentDeleteReason(
+  command: string,
+  shell: ShellKind,
+): string | undefined {
+  let hit = RULES[shell].some((pattern) => pattern.test(command));
+  // `git clean -f` 三种 shell 里都能跑、都永久删除，所以不按 shell 分支。
+  // `-n` / `--dry-run` 是只读预演，必须放行（否则模型连"先看看会删什么"都做不到）。
+  if (!hit) {
+    const gitClean = GIT_CLEAN.exec(command);
+    const options = gitClean?.[1] ?? '';
+    const dryRun =
+      /--dry-run\b/.test(options) ||
+      /(?:^|\s)-[a-z]*n[a-z]*(?:\s|$)/i.test(options);
+    hit = Boolean(
+      gitClean &&
+      !dryRun &&
+      /(?:^|\s)-[a-z]*f[a-z]*(?:\s|$)|--force\b/i.test(options),
+    );
+  }
+  return hit
+    ? '该命令会绕过系统回收站永久删除文件。请改用 Trash；清理 Git 未跟踪文件请用 Trash(action="git-clean")。'
+    : undefined;
+}

package/src/tools/shared/toolOutputStore.js

@@ -0,0 +1,97 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { sessionRuntimeDir, pruneRuntimeOutputs, registerRuntimeOutput, unregisterRuntimeOutput, } from '../../session/runtimeStore.js';
+const SPILL_AT = 64 * 1024, MAX_BYTES = 512 * 1024 * 1024, PREVIEW = 32 * 1024;
+export class ToolOutputStore {
+    stdout = '';
+    stderr = '';
+    stdoutTail = '';
+    stderrTail = '';
+    stream;
+    pending = [];
+    hash = createHash('sha256');
+    diskHash;
+    diskBytes = 0;
+    bytes = 0;
+    complete = true;
+    path;
+    constructor(identity) {
+        const dir = join(sessionRuntimeDir(identity), 'outputs');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        this.path = join(dir, `procout_${randomUUID()}.log`);
+    }
+    append(source, value) {
+        const raw = Buffer.from(value);
+        if (this.bytes >= MAX_BYTES) {
+            this.complete = false;
+            return true;
+        }
+        const selected = raw.subarray(0, MAX_BYTES - this.bytes);
+        if (selected.length < raw.length)
+            this.complete = false;
+        const shouldSpill = !this.stream && this.bytes + selected.length > SPILL_AT;
+        if (shouldSpill) {
+            this.stream = createWriteStream(this.path, { flags: 'wx', mode: 0o600 });
+            this.diskHash = createHash('sha256');
+            registerRuntimeOutput(this.path);
+            for (const item of this.pending)
+                this.writeFrame(item.source, item.data);
+            this.pending = [];
+        }
+        this.bytes += selected.length;
+        this.hash.update(selected);
+        const text = selected.toString('utf8');
+        if (source === 'stdout') {
+            if (this.stdout.length < PREVIEW)
+                this.stdout += text.slice(0, PREVIEW - this.stdout.length);
+            this.stdoutTail = (this.stdoutTail + text).slice(-PREVIEW);
+        }
+        else {
+            if (this.stderr.length < PREVIEW)
+                this.stderr += text.slice(0, PREVIEW - this.stderr.length);
+            this.stderrTail = (this.stderrTail + text).slice(-PREVIEW);
+        }
+        if (this.stream)
+            return this.writeFrame(source, selected);
+        this.pending.push({ source, data: Buffer.from(selected) });
+        return true;
+    }
+    frame(source, data) {
+        return Buffer.concat([Buffer.from(`[${source}] `), data]);
+    }
+    writeFrame(source, data) {
+        const framed = this.frame(source, data);
+        this.diskBytes += framed.length;
+        this.diskHash.update(framed);
+        return this.stream.write(framed);
+    }
+    onDrain(callback) {
+        this.stream?.once('drain', callback);
+    }
+    async finish() {
+        if (this.stream) {
+            try {
+                await new Promise((resolve, reject) => {
+                    this.stream.once('error', reject);
+                    this.stream.end(() => resolve());
+                });
+            }
+            finally {
+                unregisterRuntimeOutput(this.path);
+                void pruneRuntimeOutputs();
+            }
+        }
+        const preview = (head, tail) => this.stream && tail && !head.endsWith(tail)
+            ? `${head}\n... [middle stored on disk] ...\n${tail}`
+            : head;
+        return {
+            stdout: preview(this.stdout, this.stdoutTail),
+            stderr: preview(this.stderr, this.stderrTail),
+            ...(this.stream ? { path: this.path } : {}),
+            bytes: this.stream ? this.diskBytes : this.bytes,
+            sha256: this.stream ? this.diskHash.digest('hex') : this.hash.digest('hex'),
+            complete: this.complete,
+        };
+    }
+}

package/src/tools/shared/toolOutputStore.ts

@@ -0,0 +1,110 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createWriteStream, mkdirSync, type WriteStream } from 'node:fs';
+import { join } from 'node:path';
+import {
+  sessionRuntimeDir,
+  pruneRuntimeOutputs,
+  registerRuntimeOutput,
+  type RuntimeIdentity,
+  unregisterRuntimeOutput,
+} from '../../session/runtimeStore.js';
+
+const SPILL_AT = 64 * 1024,
+  MAX_BYTES = 512 * 1024 * 1024,
+  PREVIEW = 32 * 1024;
+export interface StoredOutput {
+  stdout: string;
+  stderr: string;
+  path?: string;
+  bytes: number;
+  sha256: string;
+  complete: boolean;
+}
+export class ToolOutputStore {
+  private stdout = '';
+  private stderr = '';
+  private stdoutTail = '';
+  private stderrTail = '';
+  private stream?: WriteStream;
+  private pending: Array<{ source: 'stdout' | 'stderr'; data: Buffer }> = [];
+  private hash = createHash('sha256');
+  private diskHash?: ReturnType<typeof createHash>;
+  private diskBytes = 0;
+  private bytes = 0;
+  private complete = true;
+  readonly path: string;
+  constructor(identity: RuntimeIdentity) {
+    const dir = join(sessionRuntimeDir(identity), 'outputs');
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    this.path = join(dir, `procout_${randomUUID()}.log`);
+  }
+  append(source: 'stdout' | 'stderr', value: Buffer | string): boolean {
+    const raw = Buffer.from(value);
+    if (this.bytes >= MAX_BYTES) {
+      this.complete = false;
+      return true;
+    }
+    const selected = raw.subarray(0, MAX_BYTES - this.bytes);
+    if (selected.length < raw.length) this.complete = false;
+    const shouldSpill = !this.stream && this.bytes + selected.length > SPILL_AT;
+    if (shouldSpill) {
+      this.stream = createWriteStream(this.path, { flags: 'wx', mode: 0o600 });
+      this.diskHash = createHash('sha256');
+      registerRuntimeOutput(this.path);
+      for (const item of this.pending) this.writeFrame(item.source, item.data);
+      this.pending = [];
+    }
+    this.bytes += selected.length;
+    this.hash.update(selected);
+    const text = selected.toString('utf8');
+    if (source === 'stdout') {
+      if (this.stdout.length < PREVIEW)
+        this.stdout += text.slice(0, PREVIEW - this.stdout.length);
+      this.stdoutTail = (this.stdoutTail + text).slice(-PREVIEW);
+    } else {
+      if (this.stderr.length < PREVIEW)
+        this.stderr += text.slice(0, PREVIEW - this.stderr.length);
+      this.stderrTail = (this.stderrTail + text).slice(-PREVIEW);
+    }
+    if (this.stream) return this.writeFrame(source, selected);
+    this.pending.push({ source, data: Buffer.from(selected) });
+    return true;
+  }
+  private frame(source: 'stdout' | 'stderr', data: Buffer): Buffer {
+    return Buffer.concat([Buffer.from(`[${source}] `), data]);
+  }
+  private writeFrame(source: 'stdout' | 'stderr', data: Buffer): boolean {
+    const framed = this.frame(source, data);
+    this.diskBytes += framed.length;
+    this.diskHash!.update(framed);
+    return this.stream!.write(framed);
+  }
+  onDrain(callback: () => void): void {
+    this.stream?.once('drain', callback);
+  }
+  async finish(): Promise<StoredOutput> {
+    if (this.stream) {
+      try {
+        await new Promise<void>((resolve, reject) => {
+          this.stream!.once('error', reject);
+          this.stream!.end(() => resolve());
+        });
+      } finally {
+        unregisterRuntimeOutput(this.path);
+        void pruneRuntimeOutputs();
+      }
+    }
+    const preview = (head: string, tail: string) =>
+      this.stream && tail && !head.endsWith(tail)
+        ? `${head}\n... [middle stored on disk] ...\n${tail}`
+        : head;
+    return {
+      stdout: preview(this.stdout, this.stdoutTail),
+      stderr: preview(this.stderr, this.stderrTail),
+      ...(this.stream ? { path: this.path } : {}),
+      bytes: this.stream ? this.diskBytes : this.bytes,
+      sha256: this.stream ? this.diskHash!.digest('hex') : this.hash.digest('hex'),
+      complete: this.complete,
+    };
+  }
+}

package/src/tools/skill/skill.js

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { parse as parseYaml } from 'yaml';
+import { getResourceSearchPaths } from '../../utils/resourcePaths.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+const MAX_SKILL_BYTES = 256 * 1024;
+const schema = z.object({
+    name: z
+        .string()
+        .min(1)
+        .max(200)
+        .regex(/^[^/\\]+$/),
+    arguments: z.string().max(20_000).optional(),
+});
+const activated = new Map();
+async function candidates(name, cwd) {
+    const exact = [];
+    for (const root of getResourceSearchPaths('skills', import.meta.url, cwd)) {
+        let entries;
+        try {
+            entries = await readdir(root, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            const path = join(root, entry.name, 'SKILL.md');
+            try {
+                const text = await readFile(path, 'utf8');
+                const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+                const metadata = frontmatter
+                    ? parseYaml(frontmatter[1])
+                    : undefined;
+                const declared = typeof metadata?.name === 'string' ? metadata.name.trim() : undefined;
+                if (entry.name === name || declared === name)
+                    exact.push(path);
+            }
+            catch { }
+        }
+    }
+    return [...new Set(exact)];
+}
+async function call(input, context) {
+    const found = await candidates(input.name, context.cwd);
+    if (!found.length)
+        return { ok: false, error: `没有找到名称精确匹配的 Skill：${input.name}` };
+    // Search roots are ordered: project skill intentionally overrides the bundled skill.
+    const path = found[0];
+    const content = await readFile(path);
+    if (content.length > MAX_SKILL_BYTES)
+        return {
+            ok: false,
+            error: `Skill 指令过大（${content.length} > ${MAX_SKILL_BYTES} bytes），拒绝加载半份指令。`,
+        };
+    const hash = createHash('sha256').update(content).digest('hex');
+    const key = `${context.workspaceId ?? context.cwd ?? 'local'}:${input.name}`;
+    const activationSignature = createHash('sha256')
+        .update(hash)
+        .update('\0')
+        .update(input.arguments ?? '')
+        .digest('hex');
+    if (activated.get(key) === activationSignature)
+        return {
+            ok: true,
+            content: `Skill ${input.name} 已按相同内容激活（sha256=${hash}，目录=${join(path, '..')}）。无需重复注入。`,
+        };
+    activated.set(key, activationSignature);
+    return {
+        ok: true,
+        content: `Skill: ${input.name}\nRoot: ${join(path, '..')}\nSHA-256: ${hash}${input.arguments ? `\nUser arguments: ${input.arguments}` : ''}\n\n${content.toString('utf8')}`,
+    };
+}
+export const skillTool = {
+    name: 'Skill',
+    description: 'Loads one installed Skill by exact name and returns its complete SKILL.md instructions, root directory and content hash. Use this instead of manually locating SKILL.md.',
+    inputSchema: schema,
+    parameters: toToolParameters(schema),
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    call: async () => ({ ok: false, error: 'Skill requires runtime context' }),
+    callWithContext: (input, _signal, context) => call(input, context),
+};

package/src/tools/skill/skill.ts

@@ -0,0 +1,94 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { parse as parseYaml } from 'yaml';
+
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { getResourceSearchPaths } from '../../utils/resourcePaths.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+const MAX_SKILL_BYTES = 256 * 1024;
+const schema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .max(200)
+    .regex(/^[^/\\]+$/),
+  arguments: z.string().max(20_000).optional(),
+});
+type Input = z.infer<typeof schema>;
+const activated = new Map<string, string>();
+
+async function candidates(name: string, cwd?: string): Promise<string[]> {
+  const exact: string[] = [];
+  for (const root of getResourceSearchPaths('skills', import.meta.url, cwd)) {
+    let entries;
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const path = join(root, entry.name, 'SKILL.md');
+      try {
+        const text = await readFile(path, 'utf8');
+        const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+        const metadata = frontmatter
+          ? (parseYaml(frontmatter[1]!) as { name?: unknown })
+          : undefined;
+        const declared =
+          typeof metadata?.name === 'string' ? metadata.name.trim() : undefined;
+        if (entry.name === name || declared === name) exact.push(path);
+      } catch {}
+    }
+  }
+  return [...new Set(exact)];
+}
+
+async function call(
+  input: Input,
+  context: ToolCallContext,
+): Promise<ToolResult> {
+  const found = await candidates(input.name, context.cwd);
+  if (!found.length)
+    return { ok: false, error: `没有找到名称精确匹配的 Skill：${input.name}` };
+  // Search roots are ordered: project skill intentionally overrides the bundled skill.
+  const path = found[0]!;
+  const content = await readFile(path);
+  if (content.length > MAX_SKILL_BYTES)
+    return {
+      ok: false,
+      error: `Skill 指令过大（${content.length} > ${MAX_SKILL_BYTES} bytes），拒绝加载半份指令。`,
+    };
+  const hash = createHash('sha256').update(content).digest('hex');
+  const key = `${context.workspaceId ?? context.cwd ?? 'local'}:${input.name}`;
+  const activationSignature = createHash('sha256')
+    .update(hash)
+    .update('\0')
+    .update(input.arguments ?? '')
+    .digest('hex');
+  if (activated.get(key) === activationSignature)
+    return {
+      ok: true,
+      content: `Skill ${input.name} 已按相同内容激活（sha256=${hash}，目录=${join(path, '..')}）。无需重复注入。`,
+    };
+  activated.set(key, activationSignature);
+  return {
+    ok: true,
+    content: `Skill: ${input.name}\nRoot: ${join(path, '..')}\nSHA-256: ${hash}${input.arguments ? `\nUser arguments: ${input.arguments}` : ''}\n\n${content.toString('utf8')}`,
+  };
+}
+
+export const skillTool: Tool<Input> = {
+  name: 'Skill',
+  description:
+    'Loads one installed Skill by exact name and returns its complete SKILL.md instructions, root directory and content hash. Use this instead of manually locating SKILL.md.',
+  inputSchema: schema,
+  parameters: toToolParameters(schema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  call: async () => ({ ok: false, error: 'Skill requires runtime context' }),
+  callWithContext: (input, _signal, context) => call(input, context),
+};