aegiscode 3.1.8 → 3.1.10

package/src/tools/execution/types.ts

@@ -0,0 +1,273 @@
+/**
+ * 
+ */
+
+import type { Tool, ToolResult, ToolInvocation } from '../types.js';
+
+// ========== 权限模
+
+/**
+ * 
+ */
+export enum PermissionMode {
+  /** 默认模式：写操作需确认 */
+  DEFAULT = 'default',
+  /** 自动批准编辑 */
+  AUTO_EDIT = 'autoEdit',
+  /** 自动批准所有 */
+  YOLO = 'yolo',
+  /** 只读调研模式 */
+  PLAN = 'plan',
+}
+
+// ========== 权限检
+
+/**
+ * 
+ */
+export enum PermissionResult {
+  ALLOW = 'allow',
+  ASK = 'ask',
+  DENY = 'deny',
+}
+
+/**
+ * 
+ */
+export interface PermissionCheckResult {
+  result: PermissionResult;
+  matchedRule?: string;
+  reason?: string;
+}
+
+/**
+ * 
+ */
+export interface PermissionConfig {
+  allow: string[];
+  deny: string[];
+  ask: string[];
+}
+
+/**
+ * 
+ */
+export interface ToolInvocationDescriptor {
+  toolName: string;
+  params: Record<string, unknown>;
+  affectedPaths?: string[];
+  tool?: Tool;
+}
+
+// ========== 确认机
+
+/**
+ * 
+ */
+export interface ConfirmationDetails {
+  title: string;
+  message: string;
+  details?: string;
+  risks?: string[];
+  affectedFiles?: string[];
+}
+
+/**
+ * 
+ */
+export interface ConfirmationResponse {
+  approved: boolean;
+  reason?: string;
+  scope?: 'once' | 'session';
+}
+
+/**
+ * 
+ */
+export interface ConfirmationHandler {
+  requestConfirmation(details: ConfirmationDetails): Promise<ConfirmationResponse>;
+}
+
+// ========== 执行上下
+
+/**
+ * 
+ */
+export interface PipelineExecutionContext {
+  sessionId: string;
+  workspaceRoot: string;
+  permissionMode: PermissionMode;
+  signal?: AbortSignal;
+  onProgress?: (progress: ToolProgress) => void;
+  confirmationHandler?: ConfirmationHandler;
+  messageId?: string;
+  /** Per-model setting: false skips confirmation prompts entirely. Defaults to true. */
+  requireConfirmation?: boolean;
+}
+
+/**
+ * 
+ */
+export interface ToolProgress {
+  stage: string;
+  message: string;
+  percent?: number;
+}
+
+// ========== 工具执
+
+/**
+ * 
+ */
+export interface ToolExecutionInternal {
+  tool?: Tool;
+  invocation?: ToolInvocation;
+  needsConfirmation?: boolean;
+  confirmationReason?: string;
+  permissionSignature?: string;
+  hookToolUseId?: string;
+  /**
+   * Set when the command pilots another terminal session (tmux send-keys,
+   * screen -X stuff, etc.) — a vector for a model to mutate shared state
+   * (config.json, files) by typing into a second instance's stdin as if it
+   * were a real user, bypassing both per-model requireConfirmation and any
+   * session "always allow" approval. When true, ConfirmationStage must show
+   * the prompt regardless of either.
+   */
+  forceConfirmation?: boolean;
+
+  /** Cache key set by CacheStage — ExecutionStage uses it to store results */
+  cacheKey?: string;
+}
+
+/**
+ * 
+ */
+export class ToolExecution {
+  private result?: ToolResult;
+  private aborted = false;
+  private abortReason?: string;
+
+  readonly _internal: ToolExecutionInternal = {};
+
+  constructor(
+    public readonly toolName: string,
+    public params: Record<string, unknown>,
+    public readonly context: PipelineExecutionContext
+  ) {}
+
+  /**
+   * 
+   */
+  abort(reason: string): void {
+    this.aborted = true;
+    this.abortReason = reason;
+  }
+
+  /**
+   * 
+   */
+  isAborted(): boolean {
+    return this.aborted;
+  }
+
+  /**
+   * 
+   */
+  getAbortReason(): string | undefined {
+    return this.abortReason;
+  }
+
+  /**
+   * 
+   */
+  setResult(result: ToolResult): void {
+    this.result = result;
+  }
+
+  /**
+   * 
+   */
+  getResult(): ToolResult | undefined {
+    return this.result;
+  }
+}
+
+// ========== 管道阶
+
+/**
+ * 
+ */
+export interface PipelineStage {
+  readonly name: string;
+  process(execution: ToolExecution): Promise<void>;
+}
+
+// ========== 管道配
+
+/**
+ * 
+ */
+export interface ExecutionPipelineConfig {
+  permissions?: PermissionConfig;
+  defaultMode?: PermissionMode;
+  /** Per-model allowed tools — overrides global whitelist for the current model */
+  allowedTools?: string[];
+  /** Per-model disallowed tools — overrides global blacklist for the current model */
+  disallowedTools?: string[];
+}
+
+// ========== 执行历
+
+/**
+ * 
+ */
+export interface ExecutionHistoryEntry {
+  toolName: string;
+  params: Record<string, unknown>;
+  result: ToolResult;
+  timestamp: number;
+  duration: number;
+  permissionMode: PermissionMode;
+  stages: string[];
+}
+
+// ========== Hook 相
+
+/**
+ * Pre-Tool Hook 结果
+ */
+export interface PreToolHookResult {
+  decision: 'allow' | 'ask' | 'deny';
+  modifiedInput?: Record<string, unknown>;
+  reason?: string;
+  warning?: string;
+}
+
+/**
+ * Post-Tool Hook 参数
+ */
+export interface PostToolHookParams {
+  toolName: string;
+  params: Record<string, unknown>;
+  result?: ToolResult;
+  context: PipelineExecutionContext;
+}
+
+// ========== 管道事
+
+/**
+ * 
+ */
+export interface StageStartEvent {
+  stage: string;
+  execution: ToolExecution;
+}
+
+/**
+ * 
+ */
+export interface StageCompleteEvent {
+  stage: string;
+  execution: ToolExecution;
+}

package/src/tools/index.ts

@@ -0,0 +1,81 @@
+/**
+ * 
+ */
+
+// 类
+export {
+  ToolKind,
+  ToolErrorType,
+} from './types.js';
+
+export type {
+  Tool,
+  ToolResult,
+  ToolError,
+  ToolDescription,
+  ToolExample,
+  ExecutionContext,
+  FunctionDeclaration,
+  ToolInvocation,
+} from './types.js';
+
+// 工厂函
+export { createTool } from './createTool.js';
+export type { ToolConfig } from './createTool.js';
+
+// Schema
+export { ToolSchemas, optional } from './schemas.js';
+
+// 注册
+export { ToolRegistry, createToolRegistry } from './registry.js';
+
+// 注册表事
+export type { ToolRegisteredEvent } from './registry.js';
+
+// 内置工
+export {
+  readTool,
+  editTool,
+  writeTool,
+  grepTool,
+  bashTool,
+  getBuiltinTools,
+} from './builtin/index.js';
+
+// 执行管
+export {
+  ExecutionPipeline,
+  PermissionMode,
+  PermissionResult,
+  ToolExecution,
+} from './execution/index.js';
+
+export type {
+  ExecutionPipelineEvents,
+  PipelineStage,
+  PipelineExecutionContext,
+  ExecutionPipelineConfig,
+  ExecutionHistoryEntry,
+  PermissionCheckResult,
+  PermissionConfig,
+  ToolInvocationDescriptor,
+  ConfirmationDetails,
+  ConfirmationResponse,
+  ConfirmationHandler,
+  ToolProgress,
+  PreToolHookResult,
+  PostToolHookParams,
+} from './execution/index.js';
+
+// 验
+export {
+  PermissionChecker,
+  DEFAULT_PERMISSION_CONFIG,
+  SensitiveFileDetector,
+  SensitivityLevel,
+} from './validation/index.js';
+
+export type {
+  SensitivityResult,
+  SensitivityResultWithPath,
+} from './validation/index.js';

package/src/tools/registry.ts

@@ -0,0 +1,304 @@
+/**
+ * 
+ * 
+ * 
+ */
+
+import { EventEmitter } from 'events';
+import type { Tool, FunctionDeclaration } from './types.js';
+
+/**
+ * 
+ */
+export interface ToolRegisteredEvent {
+  type: 'builtin' | 'mcp';
+  tool: Tool;
+}
+
+/**
+ * 
+ */
+export class ToolRegistry extends EventEmitter {
+  /** 内置工具 */
+  private tools = new Map<string, Tool>();
+  
+  /** MCP 工具 */
+  private mcpTools = new Map<string, Tool>();
+  
+  /** 分类索引 */
+  private categories = new Map<string, Set<string>>();
+  
+  /** 标签索引 */
+  private tagIndex = new Map<string, Set<string>>();
+
+  /**
+   * 
+   */
+  register(tool: Tool): void {
+    if (this.tools.has(tool.name) || this.mcpTools.has(tool.name)) {
+      throw new Error(`工具 '${tool.name}' 已注册`);
+    }
+    
+    this.tools.set(tool.name, tool);
+    this.updateIndexes(tool);
+    this.emit('toolRegistered', { type: 'builtin', tool } as ToolRegisteredEvent);
+  }
+
+  /**
+   * 
+   */
+  registerMcpTool(tool: Tool): void {
+    if (this.tools.has(tool.name) || this.mcpTools.has(tool.name)) {
+      throw new Error(`工具 '${tool.name}' 已注册`);
+    }
+    
+    this.mcpTools.set(tool.name, tool);
+    this.updateIndexes(tool);
+    this.emit('toolRegistered', { type: 'mcp', tool } as ToolRegisteredEvent);
+  }
+
+  /**
+   * 
+   */
+  registerMcpTools(tools: Tool[]): void {
+    for (const tool of tools) {
+      this.registerMcpTool(tool);
+    }
+  }
+
+  /**
+   * 
+   */
+  unregisterMcpTool(name: string): boolean {
+    const tool = this.mcpTools.get(name);
+    if (!tool) return false;
+
+    this.mcpTools.delete(name);
+    this.removeFromIndexes(tool);
+    this.emit('toolUnregistered', { type: 'mcp', tool });
+    return true;
+  }
+
+  /**
+   * 
+   */
+  clearMcpTools(): void {
+    for (const tool of this.mcpTools.values()) {
+      this.removeFromIndexes(tool);
+    }
+    this.mcpTools.clear();
+  }
+
+  /**
+   * 
+   */
+  registerAll(tools: Tool[]): void {
+    for (const tool of tools) {
+      this.register(tool);
+    }
+  }
+
+  /**
+   * 
+   */
+  get(name: string): Tool | undefined {
+    return this.tools.get(name) || this.mcpTools.get(name);
+  }
+
+  /**
+   * 
+   */
+  has(name: string): boolean {
+    return this.tools.has(name) || this.mcpTools.has(name);
+  }
+
+  /**
+   * 
+   */
+  getAll(): Tool[] {
+    return [...this.tools.values(), ...this.mcpTools.values()];
+  }
+
+  /**
+   * 
+   */
+  getBuiltinTools(): Tool[] {
+    return [...this.tools.values()];
+  }
+
+  /**
+   * 
+   */
+  getMcpTools(): Tool[] {
+    return [...this.mcpTools.values()];
+  }
+
+  /**
+   * 
+   */
+  getNames(): string[] {
+    return [...this.tools.keys(), ...this.mcpTools.keys()];
+  }
+
+  /**
+   * 
+   */
+  getReadOnlyTools(): Tool[] {
+    return this.getAll().filter(tool => tool.isReadOnly);
+  }
+
+  /**
+   * 
+   */
+  getWriteTools(): Tool[] {
+    return this.getAll().filter(tool => !tool.isReadOnly);
+  }
+
+  /**
+   * 
+   */
+  getByCategory(category: string): Tool[] {
+    const names = this.categories.get(category);
+    if (!names) return [];
+    return [...names].map(name => this.tools.get(name)!).filter(Boolean);
+  }
+
+  /**
+   * 
+   */
+  getByTag(tag: string): Tool[] {
+    const names = this.tagIndex.get(tag);
+    if (!names) return [];
+    return [...names].map(name => this.tools.get(name)!).filter(Boolean);
+  }
+
+  /**
+   * 
+   */
+  getCategories(): string[] {
+    return [...this.categories.keys()];
+  }
+
+  /**
+   * 
+   */
+  getTags(): string[] {
+    return [...this.tagIndex.keys()];
+  }
+
+  /**
+   * 
+   */
+  getFunctionDeclarations(): FunctionDeclaration[] {
+    return this.getAll().map(tool => tool.getFunctionDeclaration());
+  }
+
+  /**
+   * 
+   */
+  getFunctionDeclarationsByMode(mode?: string): FunctionDeclaration[] {
+    if (mode === 'plan') {
+      // Plan 模式只返回只读工
+      return this.getReadOnlyTools().map(t => t.getFunctionDeclaration());
+    }
+    return this.getFunctionDeclarations();
+  }
+
+  /**
+   * 
+   */
+  search(query: string): Tool[] {
+    const lowerQuery = query.toLowerCase();
+    return this.getAll().filter(tool => 
+      tool.name.toLowerCase().includes(lowerQuery) ||
+      tool.displayName.toLowerCase().includes(lowerQuery) ||
+      tool.description.short.toLowerCase().includes(lowerQuery)
+    );
+  }
+
+  /**
+   * 
+   */
+  get size(): number {
+    return this.tools.size + this.mcpTools.size;
+  }
+
+  /**
+   * 
+   */
+  get builtinSize(): number {
+    return this.tools.size;
+  }
+
+  /**
+   * 
+   */
+  get mcpSize(): number {
+    return this.mcpTools.size;
+  }
+
+  /**
+   * 
+   */
+  clear(): void {
+    this.tools.clear();
+    this.mcpTools.clear();
+    this.categories.clear();
+    this.tagIndex.clear();
+  }
+
+  /**
+   * 
+   */
+  private updateIndexes(tool: Tool): void {
+    // 更新分类索
+    if (tool.category) {
+      if (!this.categories.has(tool.category)) {
+        this.categories.set(tool.category, new Set());
+      }
+      this.categories.get(tool.category)!.add(tool.name);
+    }
+
+    // 更新标签索
+    for (const tag of tool.tags) {
+      if (!this.tagIndex.has(tag)) {
+        this.tagIndex.set(tag, new Set());
+      }
+      this.tagIndex.get(tag)!.add(tool.name);
+    }
+  }
+
+  /**
+   * 
+   */
+  private removeFromIndexes(tool: Tool): void {
+    // 从分类索引中移
+    if (tool.category) {
+      const categorySet = this.categories.get(tool.category);
+      if (categorySet) {
+        categorySet.delete(tool.name);
+        if (categorySet.size === 0) {
+          this.categories.delete(tool.category);
+        }
+      }
+    }
+
+    // 从标签索引中移
+    for (const tag of tool.tags) {
+      const tagSet = this.tagIndex.get(tag);
+      if (tagSet) {
+        tagSet.delete(tool.name);
+        if (tagSet.size === 0) {
+          this.tagIndex.delete(tag);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * 
+ */
+export function createToolRegistry(): ToolRegistry {
+  return new ToolRegistry();
+}