minimal-agent 0.10.0 → 0.12.0

package/src/tools/powershell/powershell.ts

@@ -0,0 +1,239 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { z } from 'zod';
+
+import { requestUserChoice } from '../../askBridge.js';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { classifyCommand } from '../../irreversible/rules.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { checkForbidden, sanitizedChildEnv } from '../bash/bash.js';
+import { killTree } from '../shared/killTree.js';
+import { startBackgroundTask } from '../tasks/backgroundTaskService.js';
+import { processExecutionMetadata } from '../tasks/processEvidence.js';
+import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
+import { permanentDeleteReason } from '../shared/permanentDeleteGuard.js';
+import { ToolOutputStore } from '../shared/toolOutputStore.js';
+
+const MAX_TIMEOUT_MS = 600_000;
+function findPowerShell(): string | undefined {
+  if (process.platform !== 'win32') return undefined;
+  const explicit = process.env.MINIMAL_AGENT_POWERSHELL_PATH;
+  if (explicit && existsSync(explicit)) return explicit;
+  for (const name of ['pwsh.exe', 'powershell.exe']) {
+    for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+      const path = join(dir, name);
+      if (existsSync(path)) return path;
+    }
+  }
+  const system = join(
+    process.env.SystemRoot ?? 'C:\\Windows',
+    'System32',
+    'WindowsPowerShell',
+    'v1.0',
+    'powershell.exe',
+  );
+  return existsSync(system) ? system : undefined;
+}
+
+const inputSchema = z.object({
+  command: z.string().min(1),
+  timeout: z.number().int().positive().max(MAX_TIMEOUT_MS).optional(),
+  description: z.string().optional(),
+  run_in_background: z.boolean().optional(),
+});
+type PowerShellInput = z.infer<typeof inputSchema>;
+
+function invocation(command: string): string[] {
+  return [
+    '-NoLogo',
+    '-NoProfile',
+    '-NonInteractive',
+    '-Command',
+    `$OutputEncoding=[Console]::OutputEncoding=[Text.UTF8Encoding]::new(); ${command}`,
+  ];
+}
+
+async function approved(
+  command: string,
+  signal?: AbortSignal,
+): Promise<ToolResult | undefined> {
+  const permanentDelete = permanentDeleteReason(command, 'powershell');
+  if (permanentDelete)
+    return {
+      ok: false,
+      error: `永久删除检查拒绝执行：${permanentDelete}\n命令：${command}`,
+    };
+  const forbidden = checkForbidden(command);
+  if (forbidden)
+    return {
+      ok: false,
+      error: `安全检查拒绝执行：${forbidden}\n命令：${command}`,
+    };
+  const irreversible = classifyCommand(command);
+  if (!irreversible) return undefined;
+  const [answer] = await requestUserChoice(
+    [
+      {
+        question: `这条命令不可逆：${irreversible.why}。\n\n命令：${command}\n\n确认执行吗？`,
+        header: '不可逆操作',
+        options: [
+          { label: '取消，不执行 (推荐)', description: '放弃并改用可回滚做法' },
+          { label: '我已确认后果，执行', description: '继续执行不可逆操作' },
+        ],
+      },
+    ],
+    signal,
+  );
+  return answer?.selected?.[0]?.includes('执行') &&
+    !answer.selected[0]?.includes('取消')
+    ? undefined
+    : { ok: false, error: `已拒绝执行不可逆 PowerShell 命令：${command}` };
+}
+
+async function call(
+  input: PowerShellInput,
+  signal?: AbortSignal,
+  context?: ToolCallContext,
+): Promise<ToolResult> {
+  const executable = findPowerShell();
+  if (!executable) return { ok: false, error: '当前宿主没有可用的 PowerShell' };
+  const refusal = await approved(input.command, signal);
+  if (refusal) return refusal;
+  const args = invocation(input.command);
+  const cwd = context?.cwd ?? getWorkingDir();
+  if (input.run_in_background) {
+    try {
+      const task = await startBackgroundTask(
+        {
+          command: input.command,
+          executable,
+          args,
+          cwd,
+          env: sanitizedChildEnv(),
+          sessionId: context?.sessionId,
+          workspaceId: context?.workspaceId,
+          shellKind: 'powershell',
+        },
+        context?.sessionState?.backgroundTasks,
+      );
+      return {
+        ok: true,
+        content: `PowerShell 后台任务已启动。task_id=${task.id.replace(/^proc_/, '')}\nprocess_id=${task.id}\nlog=${task.logPath}`,
+        metadata: processExecutionMetadata({
+          shell: 'powershell',
+          mode: 'background',
+          command: input.command,
+          status: 'started',
+          taskId: task.id,
+        }),
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: `PowerShell 后台任务启动失败：${(error as Error).message}`,
+      };
+    }
+  }
+
+  return await new Promise<ToolResult>((resolvePromise) => {
+    const child = spawn(executable, args, {
+      cwd,
+      env: sanitizedChildEnv(),
+      windowsHide: true,
+      detached: false,
+    });
+    let finished = false;
+    const store = new ToolOutputStore({
+      workspaceId: context?.workspaceId,
+      sessionId: context?.sessionId,
+    });
+    const finish = async (
+      status: 'completed' | 'failed' | 'stopped',
+      code: number | null,
+      prefix = '',
+    ) => {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', abort);
+      const output = await store.finish();
+      const reference = output.path
+        ? `\n[完整输出: ${output.path}; bytes=${output.bytes}; sha256=${output.sha256}; complete=${output.complete}]`
+        : '';
+      let text = `${prefix}${output.stdout ? `<stdout>\n${output.stdout.trimEnd()}\n</stdout>\n` : ''}${output.stderr ? `<stderr>\n${output.stderr.trimEnd()}\n</stderr>\n` : ''}[exit code: ${code ?? 'killed'}]`;
+      if (text.length + reference.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        const suffix = `\n... (输出预览已截断)${reference}`;
+        text =
+          text.slice(
+            0,
+            Math.max(0, DEFAULT_MAX_RESULT_SIZE_CHARS - suffix.length),
+          ) + suffix;
+      } else text += reference;
+      const metadata = processExecutionMetadata({
+        shell: 'powershell',
+        mode: 'foreground',
+        command: input.command,
+        status,
+        exitCode: code,
+      });
+      resolvePromise(
+        status === 'completed'
+          ? { ok: true, content: text, metadata }
+          : { ok: false, error: text, metadata },
+      );
+    };
+    const abort = () => {
+      killTree(child);
+      void finish('stopped', null, 'PowerShell 命令被中断\n');
+    };
+    const timeout = input.timeout ?? 120_000;
+    const timer = setTimeout(() => {
+      killTree(child);
+      void finish('failed', null, `PowerShell 命令超时（${timeout}ms）\n`);
+    }, timeout);
+    signal?.addEventListener('abort', abort, { once: true });
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk) => {
+      if (!store.append('stdout', chunk)) {
+        child.stdout?.pause();
+        store.onDrain(() => child.stdout?.resume());
+      }
+    });
+    child.stderr?.on('data', (chunk) => {
+      if (!store.append('stderr', chunk)) {
+        child.stderr?.pause();
+        store.onDrain(() => child.stderr?.resume());
+      }
+    });
+    child.once('error', (error) => {
+      void finish('failed', null, `PowerShell 启动失败：${error.message}\n`);
+    });
+    child.once('close', (code) => {
+      void finish(code === 0 ? 'completed' : 'failed', code);
+    });
+  });
+}
+
+export const powerShellTool: Tool<PowerShellInput> = {
+  name: 'PowerShell',
+  description:
+    'Executes native PowerShell on Windows. Use for Windows-specific administration and scripts; use run_in_background for long builds, tests, or servers, then TaskOutput/TaskStop.',
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'block',
+  resolveAvailability: () => {
+    const executable = findPowerShell();
+    return {
+      available: Boolean(executable),
+      signature: executable ?? 'unavailable',
+    };
+  },
+  call: (input, signal) => call(input, signal),
+  callWithContext: (input, signal, context) => call(input, signal, context),
+};

package/src/tools/presentresult/presentresult.js

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { realpath, stat } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+const MIME_BY_EXT = {
+    '.csv': 'text/csv',
+    '.css': 'text/css',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.js': 'text/javascript',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.mp4': 'video/mp4',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.py': 'text/x-python',
+    '.svg': 'image/svg+xml',
+    '.ts': 'text/typescript',
+    '.tsx': 'text/typescript',
+    '.txt': 'text/plain',
+    '.webp': 'image/webp',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.zip': 'application/zip',
+};
+const verificationSchema = z.enum(['passed', 'failed', 'not_run']).default('not_run');
+const inputSchema = z.object({
+    summary: z.string().max(2_000).optional().describe('交付结果的简短说明'),
+    files: z.array(z.object({
+        path: z.string().min(1).describe('当前工作目录内要交付的原文件路径'),
+        label: z.string().max(200).optional().describe('面向用户的显示名称'),
+        verification: verificationSchema.optional(),
+    })).max(50).optional(),
+    links: z.array(z.object({
+        url: z.string().url(),
+        title: z.string().max(300).optional(),
+    })).max(20).optional(),
+}).refine((value) => (value.files?.length ?? 0) + (value.links?.length ?? 0) > 0, {
+    message: '至少提交一个文件或网页链接',
+});
+function isWithin(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+async function hashFile(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path))
+        hash.update(chunk);
+    return hash.digest('hex');
+}
+async function resolveDeliverable(root, entry) {
+    const lexical = resolve(root, entry.path);
+    const real = await realpath(lexical);
+    if (!isWithin(root, real))
+        throw new Error(`文件超出当前工作目录：${entry.path}`);
+    const info = await stat(real);
+    if (!info.isFile())
+        throw new Error(`交付目标不是文件：${entry.path}`);
+    const relativePath = relative(root, real).split(sep).join('/');
+    const sha256 = await hashFile(real);
+    const mime = MIME_BY_EXT[extname(relativePath).toLowerCase()] ?? 'application/octet-stream';
+    return {
+        relativePath,
+        sha256,
+        mime,
+        ...(entry.label ? { label: entry.label } : {}),
+        size: info.size,
+        modifiedAt: info.mtimeMs,
+        verification: entry.verification ?? 'not_run',
+        purpose: 'deliverable',
+    };
+}
+async function call(input) {
+    const lexicalRoot = resolve(getWorkingDir());
+    const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
+    let files;
+    try {
+        files = await Promise.all((input.files ?? []).map((entry) => resolveDeliverable(root, entry)));
+    }
+    catch (error) {
+        return { ok: false, error: `无法提交结果：${error.message}` };
+    }
+    const links = (input.links ?? []).filter((link) => /^https?:\/\//i.test(link.url));
+    if (links.length !== (input.links ?? []).length) {
+        return { ok: false, error: '网页结果只支持 http 或 https 链接' };
+    }
+    const hasFailedFile = files.some((file) => file.verification === 'failed');
+    const allFilesVerified = files.length > 0 && files.every((file) => file.verification === 'passed');
+    // `final` means the result is safe to present as the completed delivery. A file
+    // with `not_run` verification is still useful, but it must remain an honest draft.
+    const status = hasFailedFile
+        ? 'draft'
+        : allFilesVerified
+            ? 'final'
+            : files.length === 0 && links.length > 0
+                ? 'final'
+                : 'draft';
+    const warnings = files.some((file) => file.verification === 'not_run')
+        ? ['文件已提交，但尚未通过结构化验证。']
+        : hasFailedFile
+            ? ['至少一个文件未通过结构化验证。']
+            : [];
+    const manifest = {
+        status,
+        summary: input.summary?.trim() || (files.length ? `已提交 ${files.length} 个文件` : `已提交 ${links.length} 个网页结果`),
+        files,
+        ...(links.length ? { links } : {}),
+        warnings,
+    };
+    const names = files.map((file) => file.label || basename(file.relativePath));
+    return {
+        ok: true,
+        content: [
+            manifest.summary,
+            ...names.map((name) => `- 文件：${name}`),
+            ...links.map((link) => `- 网页：${link.title || link.url}`),
+            '这些结果已通过结构化结果卡提交给用户。',
+        ].join('\n'),
+        metadata: { kind: 'result_manifest', manifest },
+    };
+}
+export const presentResultTool = {
+    name: 'PresentResult',
+    description: `Formally presents files or web links as the user-facing result.
+
+Use this tool whenever the user asks you to send, give, deliver, submit, or hand over a file. It is also the correct way to present the final generated document, spreadsheet, slide deck, PDF, image, archive, or web result.
+
+Rules:
+- Submit the real source or final output file, never a temporary script, unpacked XML fragment, cache file, or intermediate conversion artifact.
+- Files must exist inside the current working directory.
+- Finding or mentioning a path in normal text is not delivery; the user receives a result card only after this tool succeeds.
+- If delivery fails, explain the failure instead of claiming the file was delivered.`,
+    inputSchema,
+    parameters: toToolParameters(inputSchema),
+    isReadOnly: true,
+    isConcurrencySafe: false,
+    interruptBehavior: () => 'block',
+    call,
+};

package/src/tools/presentresult/presentresult.ts

@@ -0,0 +1,156 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { realpath, stat } from 'node:fs/promises';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import type { DeliverableManifest, Tool, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+
+const MIME_BY_EXT: Record<string, string> = {
+  '.csv': 'text/csv',
+  '.css': 'text/css',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.gif': 'image/gif',
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.json': 'application/json',
+  '.md': 'text/markdown',
+  '.mp4': 'video/mp4',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.py': 'text/x-python',
+  '.svg': 'image/svg+xml',
+  '.ts': 'text/typescript',
+  '.tsx': 'text/typescript',
+  '.txt': 'text/plain',
+  '.webp': 'image/webp',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.zip': 'application/zip',
+};
+
+const verificationSchema = z.enum(['passed', 'failed', 'not_run']).default('not_run');
+const inputSchema = z.object({
+  summary: z.string().max(2_000).optional().describe('交付结果的简短说明'),
+  files: z.array(z.object({
+    path: z.string().min(1).describe('当前工作目录内要交付的原文件路径'),
+    label: z.string().max(200).optional().describe('面向用户的显示名称'),
+    verification: verificationSchema.optional(),
+  })).max(50).optional(),
+  links: z.array(z.object({
+    url: z.string().url(),
+    title: z.string().max(300).optional(),
+  })).max(20).optional(),
+}).refine((value) => (value.files?.length ?? 0) + (value.links?.length ?? 0) > 0, {
+  message: '至少提交一个文件或网页链接',
+});
+
+type PresentResultInput = z.infer<typeof inputSchema>;
+
+function isWithin(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+async function hashFile(path: string): Promise<string> {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+async function resolveDeliverable(
+  root: string,
+  entry: NonNullable<PresentResultInput['files']>[number],
+): Promise<DeliverableManifest['files'][number]> {
+  const lexical = resolve(root, entry.path);
+  const real = await realpath(lexical);
+  if (!isWithin(root, real)) throw new Error(`文件超出当前工作目录：${entry.path}`);
+  const info = await stat(real);
+  if (!info.isFile()) throw new Error(`交付目标不是文件：${entry.path}`);
+  const relativePath = relative(root, real).split(sep).join('/');
+  const sha256 = await hashFile(real);
+  const mime = MIME_BY_EXT[extname(relativePath).toLowerCase()] ?? 'application/octet-stream';
+  return {
+    relativePath,
+    sha256,
+    mime,
+    ...(entry.label ? { label: entry.label } : {}),
+    size: info.size,
+    modifiedAt: info.mtimeMs,
+    verification: entry.verification ?? 'not_run',
+    purpose: 'deliverable',
+  };
+}
+
+async function call(input: PresentResultInput): Promise<ToolResult> {
+  const lexicalRoot = resolve(getWorkingDir());
+  const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
+  let files: DeliverableManifest['files'];
+  try {
+    files = await Promise.all((input.files ?? []).map((entry) => resolveDeliverable(root, entry)));
+  } catch (error) {
+    return { ok: false, error: `无法提交结果：${(error as Error).message}` };
+  }
+
+  const links = (input.links ?? []).filter((link) => /^https?:\/\//i.test(link.url));
+  if (links.length !== (input.links ?? []).length) {
+    return { ok: false, error: '网页结果只支持 http 或 https 链接' };
+  }
+  const hasFailedFile = files.some((file) => file.verification === 'failed');
+  const allFilesVerified = files.length > 0 && files.every((file) => file.verification === 'passed');
+  // `final` means the result is safe to present as the completed delivery. A file
+  // with `not_run` verification is still useful, but it must remain an honest draft.
+  const status = hasFailedFile
+    ? 'draft'
+    : allFilesVerified
+      ? 'final'
+      : files.length === 0 && links.length > 0
+        ? 'final'
+        : 'draft';
+  const warnings = files.some((file) => file.verification === 'not_run')
+    ? ['文件已提交，但尚未通过结构化验证。']
+    : hasFailedFile
+      ? ['至少一个文件未通过结构化验证。']
+      : [];
+  const manifest: DeliverableManifest = {
+    status,
+    summary: input.summary?.trim() || (files.length ? `已提交 ${files.length} 个文件` : `已提交 ${links.length} 个网页结果`),
+    files,
+    ...(links.length ? { links } : {}),
+    warnings,
+  };
+  const names = files.map((file) => file.label || basename(file.relativePath));
+  return {
+    ok: true,
+    content: [
+      manifest.summary,
+      ...names.map((name) => `- 文件：${name}`),
+      ...links.map((link) => `- 网页：${link.title || link.url}`),
+      '这些结果已通过结构化结果卡提交给用户。',
+    ].join('\n'),
+    metadata: { kind: 'result_manifest', manifest },
+  };
+}
+
+export const presentResultTool: Tool<PresentResultInput> = {
+  name: 'PresentResult',
+  description: `Formally presents files or web links as the user-facing result.
+
+Use this tool whenever the user asks you to send, give, deliver, submit, or hand over a file. It is also the correct way to present the final generated document, spreadsheet, slide deck, PDF, image, archive, or web result.
+
+Rules:
+- Submit the real source or final output file, never a temporary script, unpacked XML fragment, cache file, or intermediate conversion artifact.
+- Files must exist inside the current working directory.
+- Finding or mentioning a path in normal text is not delivery; the user receives a result card only after this tool succeeds.
+- If delivery fails, explain the failure instead of claiming the file was delivered.`,
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: true,
+  isConcurrencySafe: false,
+  interruptBehavior: () => 'block',
+  call,
+};