minimal-agent 0.10.0 → 0.12.0

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),
+};