aegiscode 3.1.8 → 3.1.10

package/src/tools/execution/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 
+ */
+
+// 类
+export {
+  PermissionMode,
+  PermissionResult,
+  ToolExecution,
+  type PipelineStage,
+  type PipelineExecutionContext,
+  type ExecutionPipelineConfig,
+  type ExecutionHistoryEntry,
+  type PermissionCheckResult,
+  type PermissionConfig,
+  type ToolInvocationDescriptor,
+  type ConfirmationDetails,
+  type ConfirmationResponse,
+  type ConfirmationHandler,
+  type ToolProgress,
+  type PreToolHookResult,
+  type PostToolHookParams,
+  type StageStartEvent,
+  type StageCompleteEvent,
+} from './types.js';
+
+// 主
+export { ExecutionPipeline, type ExecutionPipelineEvents } from './ExecutionPipeline.js';
+
+// 阶
+export {
+  DiscoveryStage,
+  CacheStage,
+  PermissionStage,
+  HookStage,
+  ConfirmationStage,
+  ExecutionStage,
+  PostHookStage,
+  FormattingStage,
+} from './stages/index.js';

package/src/tools/execution/stages/CacheStage.ts

@@ -0,0 +1,131 @@
+/**
+ * CacheStage — session-scoped tool result caching
+ *
+ * Caches results from read-only tools (Read, Grep, Glob) so that re-requesting
+ * the same file / same glob / same grep within the same session does not re-execute
+ * the tool. The result is injected directly into the ToolExecution object, allowing
+ * the pipeline to short-circuit.
+ *
+ * Design parallels Claude Code's `tool-results/` directory per session UUID.
+ *
+ * Key decisions:
+ *  - Cache key = SHA-256 hash of (toolName + sorted-JSON(params) + sessionId)
+ *  - Only caches SUCCESSFUL results from read-only tools
+ *  - Cache is in-memory (Map) + optionally persisted to disk
+ *  - TTL = session lifetime (cleared when session ends or cache is purged)
+ */
+
+import * as crypto from 'node:crypto';
+import type { ToolResult } from '../../types.js';
+import type { PipelineStage, ToolExecution } from '../types.js';
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export interface CacheEntry {
+  result: ToolResult;
+  cachedAt: number;
+  hitCount: number;
+}
+
+export interface CacheStageOptions {
+  /** Maximum cache entries (default 500) */
+  maxSize?: number;
+}
+
+// ── Read-only tool names that are safe to cache ──────────────────────────────
+
+const READONLY_TOOLS = new Set(['Read', 'Grep', 'Glob']);
+
+// ── CacheStage ───────────────────────────────────────────────────────────────
+
+export class CacheStage implements PipelineStage {
+  readonly name = 'cache';
+
+  /** Cache key → CacheEntry */
+  private store = new Map<string, CacheEntry>();
+  private maxSize: number;
+
+  constructor(options: CacheStageOptions = {}) {
+    this.maxSize = options.maxSize ?? 500;
+  }
+
+  async process(execution: ToolExecution): Promise<void> {
+    // Only cache read-only tools
+    if (!READONLY_TOOLS.has(execution.toolName)) return;
+
+    const cacheKey = this.buildKey(
+      execution.toolName,
+      execution.params,
+      execution.context.sessionId,
+    );
+
+    const cached = this.store.get(cacheKey);
+    if (cached) {
+      cached.hitCount++;
+      execution.setResult(cached.result);
+      return;
+    }
+
+    // Not in cache — ExecutionStage reads this key to store the result once
+    // the tool actually runs.
+    execution._internal.cacheKey = cacheKey;
+  }
+
+  /**
+   * Called by ExecutionStage after a tool executes successfully, to store
+   * the result in the cache.
+   */
+  cacheResult(cacheKey: string, result: ToolResult): void {
+    if (!result.success) return;
+    if (!result.llmContent && !result.displayContent) return;
+
+    // Evict oldest if at capacity
+    if (this.store.size >= this.maxSize) {
+      let oldestKey: string | undefined;
+      let oldestTime = Infinity;
+      for (const [k, v] of this.store) {
+        if (v.cachedAt < oldestTime) {
+          oldestTime = v.cachedAt;
+          oldestKey = k;
+        }
+      }
+      if (oldestKey) this.store.delete(oldestKey);
+    }
+
+    this.store.set(cacheKey, {
+      result,
+      cachedAt: Date.now(),
+      hitCount: 0,
+    });
+  }
+
+  /** Clear all cached entries */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Clear entries for a specific session */
+  clearSession(sessionId: string): void {
+    for (const [key, entry] of this.store) {
+      // Keys embed the sessionId — check by extracting it
+      if (key.includes(sessionId)) {
+        this.store.delete(key);
+      }
+    }
+  }
+
+  /** Get cache stats */
+  stats(): { size: number; maxSize: number } {
+    return { size: this.store.size, maxSize: this.maxSize };
+  }
+
+  // ── Private ──────────────────────────────────────────────────────────────
+
+  private buildKey(toolName: string, params: Record<string, unknown>, sessionId: string): string {
+    const hash = crypto.createHash('sha256');
+    hash.update(toolName);
+    hash.update(JSON.stringify(params, Object.keys(params).sort()));
+    hash.update(sessionId);
+    return hash.digest('hex');
+  }
+}

package/src/tools/execution/stages/ConfirmationStage.ts

@@ -0,0 +1,203 @@
+/**
+ * Confirmation Stage - 用户确认阶段
+ * 
+ */
+
+import type {
+  PipelineStage,
+  ToolExecution,
+  ConfirmationDetails,
+} from '../types.js';
+
+export class ConfirmationStage implements PipelineStage {
+  readonly name = 'confirmation';
+
+  constructor(
+    private sessionApprovals: Set<string>,
+    private sessionDenials?: Set<string>
+  ) {}
+
+  async process(execution: ToolExecution): Promise<void> {
+    // 如果不需要确认，直接通
+    if (!execution._internal.needsConfirmation) {
+      return;
+    }
+
+    const forceConfirmation = execution._internal.forceConfirmation === true;
+
+    // 模型级设置：禁用确认提示时直接放行（除非该操作被标记为强制确认
+    if (!forceConfirmation && execution.context.requireConfirmation === false) {
+      return;
+    }
+
+    const tool = execution._internal.tool;
+    if (!tool) {
+      execution.abort('Tool not found in execution context');
+      return;
+    }
+
+    // 检查是否已在会话中拒绝
+    const signature = execution._internal.permissionSignature;
+    if (signature && this.sessionDenials?.has(signature)) {
+      execution.abort('Not executed: you tried this exact action earlier in this session and the user declined it. Choose a different approach.');
+      return;
+    }
+
+    // 检查是否已在会话中批准（强制确认的操作不允许通过"永远允许"跳过
+    if (!forceConfirmation && signature && this.sessionApprovals.has(signature)) {
+      return;
+    }
+
+    // 构建确认详
+    const confirmationDetails: ConfirmationDetails = {
+      title: `Permission Required: ${tool.name}`,
+      message: execution._internal.confirmationReason || 'This operation requires your confirmation',
+      details: this.generatePreview(execution),
+      risks: this.extractRisks(execution),
+      affectedFiles: this.getAffectedPaths(execution),
+    };
+
+    // 请求用户确
+    const handler = execution.context.confirmationHandler;
+    if (!handler) {
+      // 无确认处理器，默认拒
+      // Worded to avoid "permission/approval/dialog" vocabulary — this string becomes
+      // llmContent in a real tool_result, and re-using that vocabulary cluster is what
+      // lets the model later free-associate a hallucinated "blocked, click Allow" reply
+      // in an unrelated turn with no tool call at all.
+      execution.abort('Not executed: this session cannot ask the user a yes/no question right now. Retrying this exact action will not help — explain what you wanted to do in your text response instead, or ask the user directly.');
+      return;
+    }
+
+    const response = await handler.requestConfirmation(confirmationDetails);
+
+    if (!response.approved) {
+      // 如果用户选择"永远拒绝"，保存到会话拒绝列
+      if (response.scope === 'session' && signature && this.sessionDenials) {
+        this.sessionDenials.add(signature);
+      }
+      execution.abort(`Not executed: the user declined this action${response.reason ? ` — ${response.reason}` : ''}. Choose a different approach.`);
+      return;
+    }
+
+    // 如果用户选择"永远允许"，保存到会话批准列
+    if (response.scope === 'session' && signature) {
+      this.sessionApprovals.add(signature);
+    }
+  }
+
+  /**
+   * 
+   */
+  private generatePreview(execution: ToolExecution): string | undefined {
+    const { toolName, params } = execution;
+
+    switch (toolName) {
+      case 'Edit': {
+        const oldString = params.old_string as string;
+        const newString = params.new_string as string;
+        const filePath = params.file_path as string;
+
+        return `**File:** ${filePath}
+
+**Before:**
+\`\`\`
+${this.truncate(oldString, 10)}
+\`\`\`
+
+**After:**
+\`\`\`
+${this.truncate(newString, 10)}
+\`\`\``;
+      }
+
+      case 'Write': {
+        const content = params.contents as string;
+        const filePath = params.file_path as string;
+
+        return `**File:** ${filePath}
+
+**Content Preview:**
+\`\`\`
+${this.truncate(content, 20)}
+\`\`\``;
+      }
+
+      case 'Bash': {
+        const command = params.command as string;
+        const cwd = params.working_directory as string;
+
+        return `**Command:** \`${command}\`${cwd ? `\n**Directory:** ${cwd}` : ''}`;
+      }
+
+      default:
+        return undefined;
+    }
+  }
+
+  /**
+   * 
+   */
+  private extractRisks(execution: ToolExecution): string[] {
+    const risks: string[] = [];
+    const { toolName, params } = execution;
+    const tool = execution._internal.tool;
+
+    // 基于工具类型的风
+    if (tool?.kind === 'write') {
+      risks.push('This operation will modify files');
+    } else if (tool?.kind === 'execute') {
+      risks.push('This operation will execute system commands');
+    }
+
+    // 基于参数的风
+    if (toolName === 'Bash') {
+      const command = params.command as string;
+      if (command.includes('rm')) {
+        risks.push('Command may delete files');
+      }
+      if (command.includes('sudo')) {
+        risks.push('Command requires elevated privileges');
+      }
+      if (command.includes('|')) {
+        risks.push('Command uses piping');
+      }
+    }
+
+    // 检查敏感文
+    const confirmReason = execution._internal.confirmationReason || '';
+    if (confirmReason.includes('Sensitive file')) {
+      risks.push('Operation involves sensitive files');
+    }
+
+    return risks;
+  }
+
+  /**
+   * 
+   */
+  private getAffectedPaths(execution: ToolExecution): string[] {
+    const params = execution.params;
+    const pathKeys = ['file_path', 'path', 'target', 'destination'];
+    const paths: string[] = [];
+
+    for (const key of pathKeys) {
+      if (typeof params[key] === 'string') {
+        paths.push(params[key] as string);
+      }
+    }
+
+    return paths;
+  }
+
+  /**
+   * 
+   */
+  private truncate(text: string, maxLines: number = 10): string {
+    const lines = text.split('\n');
+    if (lines.length <= maxLines) {
+      return text;
+    }
+    return lines.slice(0, maxLines).join('\n') + `\n... (${lines.length - maxLines} more lines)`;
+  }
+}

package/src/tools/execution/stages/DiscoveryStage.ts

@@ -0,0 +1,46 @@
+/**
+ * Discovery Stage - 工具发现阶段
+ * 
+ * Per-model allowedTools/disallowedTools filtering added here.
+ */
+
+import type { PipelineStage, ToolExecution } from '../types.js';
+import type { ToolRegistry } from '../../registry.js';
+
+export class DiscoveryStage implements PipelineStage {
+  readonly name = 'discovery';
+
+  constructor(
+    private registry: ToolRegistry,
+    private allowedTools?: string[],
+    private disallowedTools?: string[],
+  ) {}
+
+  async process(execution: ToolExecution): Promise<void> {
+    // 1. Check per-model disallowed tools
+    if (this.disallowedTools?.includes(execution.toolName)) {
+      execution.abort(`Tool "${execution.toolName}" is disallowed for the current model`);
+      return;
+    }
+
+    // 2. Check per-model allowed tools (if set, only these are allowed)
+    if (this.allowedTools && this.allowedTools.length > 0) {
+      if (!this.allowedTools.includes(execution.toolName)) {
+        execution.abort(
+          `Tool "${execution.toolName}" is not in the allowed tools list for the current model`
+        );
+        return;
+      }
+    }
+
+    const tool = this.registry.get(execution.toolName);
+
+    if (!tool) {
+      execution.abort(`Tool "${execution.toolName}" not found in registry`);
+      return;
+    }
+
+    // 将工具实例附加到执行上下
+    execution._internal.tool = tool;
+  }
+}

package/src/tools/execution/stages/ExecutionStage.ts

@@ -0,0 +1,48 @@
+/**
+ * Execution Stage - 实际执行阶段
+ * 
+ */
+
+import type { PipelineStage, ToolExecution } from '../types.js';
+import type { ExecutionContext } from '../../types.js';
+import type { CacheStage } from './CacheStage.js';
+
+export class ExecutionStage implements PipelineStage {
+  readonly name = 'execution';
+
+  constructor(private cacheStage?: CacheStage) {}
+
+  async process(execution: ToolExecution): Promise<void> {
+    // CacheStage already set the result on a cache hit — nothing to run.
+    if (execution.getResult()) return;
+
+    const tool = execution._internal.tool;
+
+    if (!tool) {
+      execution.abort('Tool not found in execution context');
+      return;
+    }
+
+    try {
+      // 构建执行上下
+      const context: ExecutionContext = {
+        sessionId: execution.context.sessionId,
+        signal: execution.context.signal,
+        cwd: execution.context.workspaceRoot,
+      };
+
+      // 执行工
+      const result = await tool.execute(execution.params, context);
+
+      // 设置结
+      execution.setResult(result);
+
+      const cacheKey = execution._internal.cacheKey;
+      if (cacheKey) this.cacheStage?.cacheResult(cacheKey, result);
+    } catch (error) {
+      // 处理执行错
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      execution.abort(`Tool execution failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/execution/stages/FormattingStage.ts

@@ -0,0 +1,44 @@
+/**
+ * Formatting Stage - 结果格式化阶段
+ * 
+ */
+
+import type { PipelineStage, ToolExecution } from '../types.js';
+
+export class FormattingStage implements PipelineStage {
+  readonly name = 'formatting';
+
+  async process(execution: ToolExecution): Promise<void> {
+    const result = execution.getResult();
+
+    if (!result) {
+      // 没有结果（可能是被中止了），不处
+      return;
+    }
+
+    // 确保结果格式正
+    if (!result.llmContent) {
+      result.llmContent = result.success
+        ? 'Execution completed successfully'
+        : 'Execution failed';
+    }
+
+    if (!result.displayContent) {
+      result.displayContent = result.success
+        ? `✅ ${execution.toolName} completed`
+        : `❌ ${execution.toolName} failed`;
+    }
+
+    // 添加执行元数
+    result.metadata = {
+      ...result.metadata,
+      executionId: execution.context.sessionId,
+      toolName: execution.toolName,
+      timestamp: Date.now(),
+      permissionMode: execution.context.permissionMode,
+    };
+
+    // 更新结
+    execution.setResult(result);
+  }
+}

package/src/tools/execution/stages/HookStage.ts

@@ -0,0 +1,72 @@
+/**
+ * Hook Stage (Pre) - PreToolUse Hooks 执行阶段
+ * 
+ */
+
+import { nanoid } from 'nanoid';
+import type { PipelineStage, ToolExecution } from '../types.js';
+import { onPreToolUse } from '../../../hooks/index.js';
+
+export class HookStage implements PipelineStage {
+  readonly name = 'hook';
+
+  async process(execution: ToolExecution): Promise<void> {
+    const tool = execution._internal.tool;
+    if (!tool) {
+      return;
+    }
+
+    // 生成唯一的 toolUseId（PostToolUse 阶段复
+    const toolUseId = execution.context.messageId || `tool_${nanoid()}`;
+    execution._internal.hookToolUseId = toolUseId;
+
+    // 执行 PreToolUse hooks（通
+    const result = await onPreToolUse(
+      tool.name,
+      toolUseId,
+      execution.params as Record<string, unknown>,
+      execution.context.sessionId || 'unknown',
+      execution.context.workspaceRoot || process.cwd(),
+      execution.context.permissionMode
+    );
+
+    // 处理 Hook 决
+    if (result.decision === 'deny') {
+      // 直接拒绝，中止执
+      execution.abort(result.reason || 'Hook blocked execution');
+      return;
+    }
+
+    if (result.decision === 'ask') {
+      // 标记需要用户确认（传递给 Confirmation 阶
+      execution._internal.needsConfirmation = true;
+      execution._internal.confirmationReason =
+        result.reason || 'Hook requires confirmation';
+      return;
+    }
+
+    // decision === 'allow'：应用修改后的输
+    if (result.modifiedInput) {
+      const newParams = { ...execution.params, ...result.modifiedInput };
+
+      // 重新验证修改后的参
+      if (tool.build) {
+        try {
+          tool.build(newParams);
+          // 更新参
+          execution.params = newParams;
+        } catch (err) {
+          execution.abort(
+            `Hook modified parameters are invalid: ${err instanceof Error ? err.message : String(err)}`
+          );
+          return;
+        }
+      }
+    }
+
+    // 输出警告信
+    if (result.warning) {
+      console.warn(`[Hook Warning] ${result.warning}`);
+    }
+  }
+}