aegiscode 3.1.7 → 3.1.10

package/src/tools/builtin/task.ts

@@ -0,0 +1,106 @@
+/**
+ * Task tool — lets the running agent delegate read-only investigation
+ * work to parallel sub-agents, mid-conversation, without the user typing
+ * a slash command. Same machinery as /multi, restricted to Read/Grep/Glob
+ * (see plan: no confirmationHandler reaches a tool's execute(), so only
+ * ReadOnly-kind work is safe to trigger from inside a tool call).
+ */
+
+import { z } from 'zod';
+import { createTool } from '../createTool.js';
+import { ToolKind } from '../types.js';
+import { OrchestratorAgent, type SubAgentConfig } from '../../agent/orchestrator/OrchestratorAgent.js';
+import { requireModelConfig, buildSourceContext } from '../../agent/orchestrator/utils.js';
+
+const TaskSchema = z.object({
+  tasks: z.array(z.object({
+    description: z.string().describe('Short label for this investigation, e.g. "find auth bugs"'),
+    prompt: z.string().describe('Detailed instructions for the sub-agent'),
+  })).min(1).max(5).describe('One or more independent investigations to run in parallel'),
+});
+
+export const taskTool = createTool({
+  name: 'Task',
+  displayName: 'Delegate Task',
+  kind: ToolKind.ReadOnly,
+  schema: TaskSchema,
+
+  description: {
+    short: 'Delegate read-only investigation work to parallel sub-agents',
+    long: `Spin up one or more read-only sub-agents (Read/Grep/Glob only) to investigate
+the codebase in parallel, then return their findings.
+
+Use this when:
+- A question has multiple independent angles worth exploring at once
+- You want a focused sub-agent to dig into one area without cluttering the main conversation
+
+Sub-agents cannot write files or run commands — they only read and report back.
+You're responsible for synthesizing their findings into your final answer.`,
+  },
+
+  execute: async ({ tasks }, context) => {
+    let modelConfig;
+    try {
+      modelConfig = requireModelConfig();
+    } catch (e) {
+      const msg = (e as Error).message;
+      return { success: false, llmContent: msg, displayContent: msg };
+    }
+
+    const agentConfig = {
+      apiKey: modelConfig.apiKey,
+      baseURL: modelConfig.baseURL,
+      model: modelConfig.model,
+      timeout: modelConfig.timeout,
+    };
+
+    const cwd = context?.cwd || process.cwd();
+    const sourceCtx = buildSourceContext(cwd);
+    const codeContext = sourceCtx
+      ? `\n\nWorkspace context (project metadata + file tree + structure summaries + git changes):\n${sourceCtx}\n\nUse Read / Grep / Glob to examine these.`
+      : '\n\nUse Read / Grep / Glob to explore the codebase before responding.';
+
+    const orchestrator = new OrchestratorAgent(
+      'Task-Orchestrator',
+      'You coordinate read-only investigation sub-agents.',
+    );
+
+    tasks.forEach((task, i) => {
+      const agentCfg: SubAgentConfig = {
+        name: `agent-${i}`,
+        role: 'Investigator',
+        systemPrompt: `You are a focused investigation sub-agent. ${task.prompt}${codeContext}`,
+        config: agentConfig,
+        tools: ['Read', 'Grep', 'Glob'],
+      };
+      orchestrator.registerAgent(agentCfg);
+    });
+
+    try {
+      const responses = await orchestrator.delegateParallel(
+        tasks.map((task, i) => ({ agentName: `agent-${i}`, task: task.prompt })),
+        tasks.length,
+        context?.sessionId,
+      );
+
+      const lines: string[] = [];
+      responses.forEach((res, i) => {
+        lines.push(`### ${tasks[i]?.description || res.agentName}`);
+        lines.push(res.content || '*No response*');
+        lines.push('');
+      });
+
+      const formatted = lines.join('\n').trim();
+      return {
+        success: true,
+        llmContent: formatted,
+        displayContent: `✓ Ran ${tasks.length} investigation${tasks.length > 1 ? 's' : ''} in parallel`,
+      };
+    } catch (e) {
+      const msg = `Task delegation failed: ${(e as Error).message}`;
+      return { success: false, llmContent: msg, displayContent: msg };
+    }
+  },
+});
+
+export default taskTool;

package/src/tools/builtin/write.ts

@@ -0,0 +1,134 @@
+/**
+ * Write 工具
+ * 
+ * 
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { z } from 'zod';
+import { createTool } from '../createTool.js';
+import { ToolKind, ToolErrorType } from '../types.js';
+import { createSnapshot } from './snapshot.js';
+
+// ========== Schema 定
+
+const WriteSchema = z.object({
+  file_path: z.string()
+    .min(1, '文件路径不能为空')
+    .describe('The absolute path to the file to write'),
+  contents: z.string()
+    .describe('The contents to write to the file'),
+});
+
+// ========== Write 工
+
+export const writeTool = createTool({
+  name: 'Write',
+  displayName: 'File Write',
+  kind: ToolKind.Write,
+  schema: WriteSchema,
+  
+  description: {
+    short: 'Writes a file to the local filesystem',
+    long: 'Creates a new file or overwrites an existing file with the specified contents.',
+    usageNotes: [
+      'This tool will overwrite the existing file if there is one at the provided path',
+      'ALWAYS prefer editing existing files in the codebase using Edit tool',
+      'NEVER write new files unless explicitly required',
+      'NEVER proactively create documentation files (*.md) or README files',
+      'Parent directories will be created automatically if they do not exist',
+    ],
+    examples: [
+      {
+        description: 'Create a new TypeScript file',
+        params: {
+          file_path: '/path/to/new-file.ts',
+          contents: 'export const hello = "world";',
+        },
+      },
+    ],
+    important: [
+      'Only create files that are absolutely necessary',
+      'Do not create README or documentation files unless explicitly requested',
+    ],
+  },
+
+  category: '文件操作',
+  tags: ['file', 'io', 'write', 'create'],
+
+  // 提取签名内容（用于权限规
+  extractSignatureContent: (params: unknown) => {
+    const p = params as { file_path: string };
+    return p.file_path;
+  },
+
+  // 抽象权限规
+  abstractPermissionRule: (params: unknown) => {
+    const p = params as { file_path: string };
+    const dir = path.dirname(p.file_path);
+    return `Write:${dir}/*`;
+  },
+
+  async execute(params, context) {
+    const { file_path, contents } = params;
+
+    try {
+      // 1. 检查目标是否是目
+      try {
+        const stat = await fs.stat(file_path);
+        if (stat.isDirectory()) {
+          return {
+            success: false,
+            llmContent: `Error: ${file_path} is a directory, cannot write to it`,
+            displayContent: `error: ${file_path} is a directory`,
+            error: {
+              type: ToolErrorType.VALIDATION_ERROR,
+              message: 'Path is a directory',
+            },
+          };
+        }
+      } catch {
+        // 文件不存在，这是允许
+      }
+
+      // 2. 确保父目录存
+      const dir = path.dirname(file_path);
+      await fs.mkdir(dir, { recursive: true });
+
+      // 3. 快照原始文件（如果已存在）
+      let snapshotPath: string | null = null;
+      try { await fs.access(file_path); snapshotPath = await createSnapshot(file_path); } catch { /* new file */ }
+
+      // 4. 写入文
+      await fs.writeFile(file_path, contents, 'utf8');
+
+      // 5. 计算写入信
+      const lines = contents.split('\n').length;
+      const bytes = Buffer.byteLength(contents, 'utf8');
+
+      return {
+        success: true,
+        llmContent: `Successfully wrote to ${file_path} (${lines} lines, ${bytes} bytes)`,
+        displayContent: `${path.basename(file_path)}  ${lines} lines`,
+        metadata: {
+          file_path,
+          lines,
+          bytes,
+          snapshot: snapshotPath,
+        },
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'unknown error';
+      return {
+        success: false,
+        llmContent: `Error writing file: ${errorMessage}`,
+        displayContent: `error: ${errorMessage}`,
+        error: {
+          type: ToolErrorType.EXECUTION_ERROR,
+          message: errorMessage,
+        },
+      };
+    }
+  },
+});

package/src/tools/createTool.ts

@@ -0,0 +1,221 @@
+/**
+ * 
+ * 
+ * 
+ */
+
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import {
+  ToolErrorType,
+  type Tool,
+  type ToolKind,
+  type ToolDescription,
+  type ToolResult,
+  type ExecutionContext,
+  type FunctionDeclaration,
+  type ToolInvocation,
+} from './types.js';
+
+// ========== 配置类
+
+/**
+ * 
+ */
+export interface ToolConfig<TSchema extends z.ZodType> {
+  /** 工具唯一名称 */
+  name: string;
+  /** 显示名称 */
+  displayName?: string;
+  /** 工具类型 */
+  kind: ToolKind;
+  /** 参数 Schema */
+  schema: TSchema;
+  /** 工具描述 */
+  description: ToolDescription;
+  /** 执行函数 */
+  execute: (
+    params: z.infer<TSchema>,
+    context?: ExecutionContext
+  ) => Promise<ToolResult>;
+  /** 版本 */
+  version?: string;
+  /** 分类 */
+  category?: string;
+  /** 标签 */
+  tags?: string[];
+  /** 是否只读（默认根据 kind 推断） */
+  isReadOnly?: boolean;
+  /** 是否并发安全（默认 true） */
+  isConcurrencySafe?: boolean;
+  /** 是否启用结构化输出（默认 false） */
+  strict?: boolean;
+  /** 提取签名内容（用于权限规则） */
+  extractSignatureContent?: (params: unknown) => string;
+  /** 抽象权限规则（用于权限匹配） */
+  abstractPermissionRule?: (params: unknown) => string;
+}
+
+// ========== 工厂函
+
+/**
+ * 
+ * 
+ * @example
+ * ```typescript
+ * const readTool = createTool({
+ *   name: 'Read',
+ *   kind: ToolKind.ReadOnly,
+ *   schema: z.object({
+ *     file_path: z.string(),
+ *   }),
+ *   description: { short: 'Read files' },
+ *   execute: async (params) => {
+ *     // ...
+ *   },
+ * });
+ * ```
+ */
+export function createTool<TSchema extends z.ZodType>(
+  config: ToolConfig<TSchema>
+): Tool<z.infer<TSchema>> {
+  const {
+    name,
+    displayName,
+    kind,
+    schema,
+    description,
+    execute,
+    version = '1.0.0',
+    category,
+    tags = [],
+    isReadOnly,
+    isConcurrencySafe = true,
+    strict = false,
+    extractSignatureContent,
+    abstractPermissionRule,
+  } = config;
+
+  // 从 Zod Schema 生
+  const jsonSchema = zodToJsonSchema(schema, {
+    $refStrategy: 'none',
+    target: 'openApi3',
+  });
+
+  // 提取 properties 
+  const schemaObj = jsonSchema as {
+    type?: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+  };
+
+  return {
+    name,
+    displayName: displayName || name,
+    kind,
+    isReadOnly: isReadOnly ?? kind === 'readonly',
+    isConcurrencySafe,
+    strict,
+    description,
+    version,
+    category,
+    tags,
+
+    /**
+     * 
+     */
+    getFunctionDeclaration(): FunctionDeclaration {
+      return {
+        name,
+        description: buildFullDescription(description),
+        parameters: {
+          type: 'object',
+          properties: schemaObj.properties || {},
+          required: schemaObj.required,
+        },
+      };
+    },
+
+    /**
+     * 
+     */
+    build(params: z.infer<TSchema>): ToolInvocation<z.infer<TSchema>> {
+      return {
+        toolName: name,
+        params,
+      };
+    },
+
+    /**
+     * 
+     */
+    async execute(
+      params: z.infer<TSchema>,
+      context?: ExecutionContext
+    ): Promise<ToolResult> {
+      try {
+        // 验证参
+        const validated = schema.parse(params);
+        // 执行工
+        return await execute(validated, context);
+      } catch (error) {
+        // 处理 Zod 验证错
+        if (error instanceof z.ZodError) {
+          const messages = error.errors.map(e => 
+            `${e.path.join('.')}: ${e.message}`
+          ).join('; ');
+          
+          return {
+            success: false,
+            llmContent: `Parameter validation failed: ${messages}`,
+            displayContent: `❌ 参数验证失败: ${messages}`,
+            error: {
+              type: ToolErrorType.VALIDATION_ERROR,
+              message: messages,
+              details: error.errors,
+            },
+          };
+        }
+
+        // 处理其他错
+        const errorMessage = error instanceof Error ? error.message : '未知错误';
+        return {
+          success: false,
+          llmContent: `Tool execution failed: ${errorMessage}`,
+          displayContent: `❌ 执行失败: ${errorMessage}`,
+          error: {
+            type: ToolErrorType.EXECUTION_ERROR,
+            message: errorMessage,
+          },
+        };
+      }
+    },
+
+    // 可选方
+    extractSignatureContent,
+    abstractPermissionRule,
+  };
+}
+
+/**
+ * 
+ */
+function buildFullDescription(desc: ToolDescription): string {
+  const parts: string[] = [desc.short];
+
+  if (desc.long) {
+    parts.push(desc.long);
+  }
+
+  if (desc.usageNotes && desc.usageNotes.length > 0) {
+    parts.push('\nUsage notes:');
+    parts.push(...desc.usageNotes.map(note => `- ${note}`));
+  }
+
+  if (desc.important && desc.important.length > 0) {
+    parts.push('\nIMPORTANT:');
+    parts.push(...desc.important.map(note => `- ${note}`));
+  }
+
+  return parts.join('\n');
+}

package/src/tools/execution/ExecutionPipeline.ts

@@ -0,0 +1,263 @@
+/**
+ * ExecutionPipeline - 执行管道
+ * 
+ */
+
+import {
+  ToolExecution,
+  PermissionMode,
+  type PipelineStage,
+  type PipelineExecutionContext,
+  type ExecutionPipelineConfig,
+  type ExecutionHistoryEntry,
+  type StageStartEvent,
+  type StageCompleteEvent,
+} from './types.js';
+import type { ToolResult, ToolErrorType } from '../types.js';
+import type { ToolRegistry } from '../registry.js';
+import {
+  DiscoveryStage,
+  CacheStage,
+  PermissionStage,
+  HookStage,
+  ConfirmationStage,
+  ExecutionStage,
+  PostHookStage,
+  FormattingStage,
+} from './stages/index.js';
+
+/**
+ * 
+ */
+export interface ExecutionPipelineEvents {
+  stageStart: (event: StageStartEvent) => void;
+  stageComplete: (event: StageCompleteEvent) => void;
+  executionStart: (execution: ToolExecution) => void;
+  executionComplete: (execution: ToolExecution, result: ToolResult) => void;
+  executionError: (execution: ToolExecution, error: Error) => void;
+}
+
+/**
+ * 
+ */
+export class ExecutionPipeline {
+  private stages: PipelineStage[];
+  private cacheStage: CacheStage;
+  private executionHistory: ExecutionHistoryEntry[] = [];
+  private readonly sessionApprovals = new Set<string>();
+  private readonly sessionDenials = new Set<string>();
+  private readonly maxHistorySize = 1000;
+
+  constructor(
+    private registry: ToolRegistry,
+    config: ExecutionPipelineConfig = {}
+  ) {
+
+    const defaultMode = config.defaultMode || PermissionMode.DEFAULT;
+    this.cacheStage = new CacheStage();
+
+    // 初始化八个执行阶
+    this.stages = [
+      new DiscoveryStage(this.registry, config.allowedTools, config.disallowedTools),
+      this.cacheStage,
+      new PermissionStage(config.permissions, this.sessionApprovals, this.sessionDenials, defaultMode),
+      new HookStage(),
+      new ConfirmationStage(this.sessionApprovals, this.sessionDenials),
+      new ExecutionStage(this.cacheStage),
+      new PostHookStage(),
+      new FormattingStage(),
+    ];
+  }
+
+  /**
+   * 
+   */
+  async execute(
+    toolName: string,
+    params: Record<string, unknown>,
+    context: PipelineExecutionContext
+  ): Promise<ToolResult> {
+    const startTime = Date.now();
+    const executedStages: string[] = [];
+
+    // 创建执行实
+    const execution = new ToolExecution(toolName, params, context);
+
+    // 发出执行开始事
+
+    try {
+      // 依次执行各阶
+      for (const stage of this.stages) {
+        if (execution.isAborted()) {
+          break;
+        }
+
+        // 发出阶段开始事
+
+        // 执行阶
+        await stage.process(execution);
+
+        // 记录已执行的阶
+        executedStages.push(stage.name);
+
+        // 发出阶段完成事
+      }
+
+      // 获取或创建结
+      const result = execution.getResult() || this.createErrorResult(execution);
+
+      // 记录执行历
+      this.recordExecution({
+        toolName,
+        params,
+        result,
+        timestamp: startTime,
+        duration: Date.now() - startTime,
+        permissionMode: context.permissionMode,
+        stages: executedStages,
+      });
+
+      // 发出执行完成事
+
+      return result;
+    } catch (error) {
+      // 发出执行错误事
+      const err = error instanceof Error ? error : new Error(String(error));
+
+      // 返回错误结
+      return {
+        success: false,
+        llmContent: `Pipeline execution error: ${err.message}`,
+        displayContent: `❌ Pipeline error: ${err.message}`,
+        error: {
+          type: 'execution_error' as ToolErrorType,
+          message: err.message,
+        },
+      };
+    }
+  }
+
+  /**
+   * 
+   */
+  private createErrorResult(execution: ToolExecution): ToolResult {
+    const reason = execution.getAbortReason() || 'Unknown error';
+    return {
+      success: false,
+      llmContent: `Tool execution aborted: ${reason}`,
+      displayContent: `❌ ${execution.toolName}: ${reason}`,
+      error: {
+        type: 'execution_error' as ToolErrorType,
+        message: reason,
+      },
+    };
+  }
+
+  /**
+   * 
+   */
+  private recordExecution(entry: ExecutionHistoryEntry): void {
+    this.executionHistory.push(entry);
+
+    // 限制历史大
+    if (this.executionHistory.length > this.maxHistorySize) {
+      this.executionHistory.shift();
+    }
+  }
+
+  /**
+   * 
+   */
+  getRegistry(): ToolRegistry {
+    return this.registry;
+  }
+
+  /**
+   * 
+   */
+  getHistory(): ExecutionHistoryEntry[] {
+    return [...this.executionHistory];
+  }
+
+  /**
+   * 
+   */
+  clearHistory(): void {
+    this.executionHistory = [];
+  }
+
+  /**
+   * 
+   */
+  getSessionApprovals(): Set<string> {
+    return new Set(this.sessionApprovals);
+  }
+
+  /**
+   * 
+   */
+  clearSessionApprovals(): void {
+    this.sessionApprovals.clear();
+  }
+
+  /**
+   * 
+   */
+  addSessionApproval(signature: string): void {
+    this.sessionApprovals.add(signature);
+  }
+
+  /**
+   * 
+   */
+  hasSessionApproval(signature: string): boolean {
+    return this.sessionApprovals.has(signature);
+  }
+
+  // ==================== Session Denials ====================
+
+  /**
+   * 
+   */
+  getSessionDenials(): Set<string> {
+    return new Set(this.sessionDenials);
+  }
+
+  /**
+   * 
+   */
+  clearSessionDenials(): void {
+    this.sessionDenials.clear();
+  }
+
+  /**
+   * 
+   */
+  addSessionDenial(signature: string): void {
+    this.sessionDenials.add(signature);
+  }
+
+  /**
+   * 
+   */
+  hasSessionDenial(signature: string): boolean {
+    return this.sessionDenials.has(signature);
+  }
+
+  /**
+   * 
+   */
+  getStageNames(): string[] {
+    return this.stages.map(s => s.name);
+  }
+
+  /** Stats for the session-scoped Read/Grep/Glob result cache */
+  getCacheStats(): { size: number; maxSize: number } {
+    return this.cacheStage.stats();
+  }
+
+  /** Clear cached entries for a specific session */
+  clearSessionCache(sessionId: string): void {
+    this.cacheStage.clearSession(sessionId);
+  }
+}