minimal-agent 0.11.0 → 0.12.0

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,26 @@
+/** Minimal recoverability boundary for model-issued shell commands. */
+const BASH_DELETE = [
+    /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+    /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\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 function permanentDeleteReason(command, shell) {
+    let hit = (shell === 'bash' ? BASH_DELETE : POWERSHELL_DELETE).some((pattern) => pattern.test(command));
+    if (!hit && shell === 'bash') {
+        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,34 @@
+/** Minimal recoverability boundary for model-issued shell commands. */
+const BASH_DELETE = [
+  /(?:^|[;&|\n])\s*(?:sudo\s+)?(?:rm|unlink|rmdir)\b/i,
+  /(?:^|[;&|\n])\s*find\b[^\n;&|]*\s-delete\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 function permanentDeleteReason(
+  command: string,
+  shell: 'bash' | 'powershell',
+): string | undefined {
+  let hit = (shell === 'bash' ? BASH_DELETE : POWERSHELL_DELETE).some(
+    (pattern) => pattern.test(command),
+  );
+  if (!hit && shell === 'bash') {
+    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),
+};

package/src/tools/snip/snip.js

@@ -0,0 +1,67 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { resolveToolPath } from '../shared/fileUtils.js';
+import { recordRead } from '../shared/fileState.js';
+const schema = z
+    .object({
+    file_path: z.string().min(1),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    context: z.number().int().min(0).max(500).default(50).optional(),
+})
+    .refine((v) => v.end_line >= v.start_line, {
+    message: 'end_line 必须大于等于 start_line',
+});
+async function call(input, cwd, state) {
+    const resolved = resolveToolPath(input.file_path, cwd);
+    if (!resolved.ok)
+        return resolved;
+    const before = input.context ?? 50, from = Math.max(1, input.start_line - before), to = input.end_line + before;
+    const lines = [];
+    let total = 0;
+    let hasMore = false;
+    try {
+        const source = createReadStream(resolved.resolvedPath, {
+            encoding: 'utf8',
+        });
+        const rl = createInterface({
+            input: source,
+            crlfDelay: Infinity,
+        });
+        for await (const line of rl) {
+            total++;
+            if (total >= from && total <= to)
+                lines.push(`${String(total).padStart(6)}\t${line}`);
+            if (total > to) {
+                hasMore = true;
+                rl.close();
+                source.destroy();
+                break;
+            }
+        }
+    }
+    catch (e) {
+        return { ok: false, error: `Snip 读取失败：${e.message}` };
+    }
+    recordRead(resolved.resolvedPath, {
+        partial: true,
+        offset: from - 1,
+        limit: Math.max(0, Math.min(to, total) - from + 1),
+    }, state);
+    return {
+        ok: true,
+        content: `${lines.join('\n')}\n\n[requested ${input.start_line}-${input.end_line}; shown ${from}-${Math.min(to, total)}; ${hasMore ? `more than ${to} total lines; continue at ${to + 1}` : `total ${total} lines`}]`,
+    };
+}
+export const snipTool = {
+    name: 'Snip',
+    description: 'Reads a precise line range from a potentially huge text file with bounded surrounding context, without loading the whole file into memory.',
+    inputSchema: schema,
+    parameters: toToolParameters(schema),
+    isReadOnly: true,
+    isConcurrencySafe: true,
+    call: (input) => call(input),
+    callWithContext: (input, _s, ctx) => call(input, ctx.cwd, ctx.sessionState?.fileReads),
+};

package/src/tools/snip/snip.ts

@@ -0,0 +1,80 @@
+import { createReadStream } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { z } from 'zod';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { resolveToolPath } from '../shared/fileUtils.js';
+import { recordRead, type FileReadState } from '../shared/fileState.js';
+
+const schema = z
+  .object({
+    file_path: z.string().min(1),
+    start_line: z.number().int().min(1),
+    end_line: z.number().int().min(1),
+    context: z.number().int().min(0).max(500).default(50).optional(),
+  })
+  .refine((v) => v.end_line >= v.start_line, {
+    message: 'end_line 必须大于等于 start_line',
+  });
+type Input = z.infer<typeof schema>;
+async function call(
+  input: Input,
+  cwd?: string,
+  state?: FileReadState,
+): Promise<ToolResult> {
+  const resolved = resolveToolPath(input.file_path, cwd);
+  if (!resolved.ok) return resolved;
+  const before = input.context ?? 50,
+    from = Math.max(1, input.start_line - before),
+    to = input.end_line + before;
+  const lines: string[] = [];
+  let total = 0;
+  let hasMore = false;
+  try {
+    const source = createReadStream(resolved.resolvedPath, {
+      encoding: 'utf8',
+    });
+    const rl = createInterface({
+      input: source,
+      crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+      total++;
+      if (total >= from && total <= to)
+        lines.push(`${String(total).padStart(6)}\t${line}`);
+      if (total > to) {
+        hasMore = true;
+        rl.close();
+        source.destroy();
+        break;
+      }
+    }
+  } catch (e) {
+    return { ok: false, error: `Snip 读取失败：${(e as Error).message}` };
+  }
+  recordRead(
+    resolved.resolvedPath,
+    {
+      partial: true,
+      offset: from - 1,
+      limit: Math.max(0, Math.min(to, total) - from + 1),
+    },
+    state,
+  );
+  return {
+    ok: true,
+    content: `${lines.join('\n')}\n\n[requested ${input.start_line}-${input.end_line}; shown ${from}-${Math.min(to, total)}; ${hasMore ? `more than ${to} total lines; continue at ${to + 1}` : `total ${total} lines`}]`,
+  };
+}
+export const snipTool: Tool<Input> = {
+  name: 'Snip',
+  description:
+    'Reads a precise line range from a potentially huge text file with bounded surrounding context, without loading the whole file into memory.',
+  inputSchema: schema,
+  parameters: toToolParameters(schema),
+  isReadOnly: true,
+  isConcurrencySafe: true,
+  call: (input) => call(input),
+  callWithContext: (input, _s, ctx) =>
+    call(input, ctx.cwd, ctx.sessionState?.fileReads),
+};