@ai-setting/roy-agent-core 1.3.10 → 1.3.11

package/src/env/agent/types.ts

@@ -1,536 +0,0 @@
-/**
- * @fileoverview AgentComponent Types
- * 
- * 基于 roy-agent docs/agent-component-design.md
- * 
- * 注意：Tool 相关类型从 ToolComponent 复用，保持统一
- */
-
-import type { ModelMessage } from "ai";
-import type { Tool, ToolResult } from "../tool/types";
-import type { LLMOutput } from "../llm/types";
-
-// AbortSignal type from global scope (instance type, not constructor)
-type AbortSignalType = AbortSignal;
-
-// ============================================================================
-// Re-export types from other components
-// ============================================================================
-
-// Tool 和 ToolResult 从 ToolComponent 复用
-export { Tool, ToolResult };
-
-// Forward declaration for ProjectSummary (avoid circular dependency)
-export interface ProjectSummary {
-  projectPath: string;
-  projectName: string;
-  lastUpdated: number;
-  summary: string;
-  shortSummary: string;
-  draftCount: number;
-  memoryMdPath: string;
-  draftsDir: string;
-  detailsDir: string;
-}
-
-// ============================================================================
-// Agent Context
-// ============================================================================
-
-/**
- * Agent 执行上下文
- */
-export interface AgentContext {
-  /** 会话 ID */
-  sessionId?: string;
-  /** 消息 ID */
-  messageId?: string;
-  /** 中断信号 */
-  abort?: AbortSignalType;
-  /** 额外的上下文信息（会添加到 system prompt） */
-  additionInfo?: string;
-  /** 元数据 */
-  metadata?: Record<string, unknown>;
-  /** Agent 类型（用于选择 Behavior Spec） */
-  agentType?: string;
-  /** 使用的模型 */
-  model?: string;
-  /** 允许的工具列表（上下文级别，会覆盖 agent 配置） */
-  allowedTools?: string[];
-  /** 拒绝的工具列表（上下文级别，会覆盖 agent 配置） */
-  deniedTools?: string[];
-  /** 是否过滤 history 中的 tool 消息（上下文级别，会覆盖 agent 配置） */
-  filterHistory?: boolean;
-}
-
-/**
- * 工具调用（内部使用）
- */
-export interface ToolCall {
-  /** 调用 ID */
-  id: string;
-
-  /** 工具名称 */
-  name: string;
-
-  /** 调用参数 */
-  arguments: Record<string, unknown>;
-}
-
-/**
- * 工具调用结果
- */
-export interface ToolCallResult {
-  /** 调用 ID */
-  id: string;
-
-  /** 工具名称 */
-  name: string;
-
-  /** 调用结果 */
-  result: ToolResult;
-
-  /** 是否成功 */
-  success: boolean;
-}
-
-// ============================================================================
-// Hook Types
-// ============================================================================
-
-/**
- * Hook 点枚举（带 component 前缀）
- */
-export type HookPoint =
-  | "agent:before.start"      // Agent 开始执行前
-  | "agent:before.llm"        // 调用 LLM 前
-  | "agent:after.llm"         // 调用 LLM 后
-  | "agent:before.tool"        // 执行工具前
-  | "agent:after.tool"         // 执行工具后
-  | "agent:on.iteration"       // 每次迭代后
-  | "agent:on.threshold"       // 达到阈值时
-  | "agent:after.complete"     // 执行完成后
-  | "agent:on.error"           // 发生错误时
-  | "agent:after.react"        // React 循环结束后
-  | "on.error";               // 简化写法（兼容）
-
-/**
- * Context data for agent:after.react hook
- */
-export interface AgentReactContext {
-  /** Current messages for memory extraction */
-  messages: ModelMessage[];
-  /** Current session ID */
-  sessionId?: string;
-  /** Execution summary */
-  summary?: string;
-}
-
-/**
- * Hook 上下文（Agent 特有版本）
- * 
- * 注意：这是 AgentComponent 使用的 HookContext 扩展版本
- * 包含 iteration, maxIterations, messages 等 Agent 特有字段
- */
-export interface HookContext {
-  
-  // ===== Hook 点特定字段 =====
-
-  /** 当前 LLM 输出（after.llm hook 可用） */
-  llmOutput?: AgentLLMOutput;
-
-  /** 当前工具调用（before.tool/after.tool hook 可用） */
-  currentToolCall?: ToolCall;
-
-  /** 工具执行结果（after.tool hook 可用） */
-  toolResult?: ToolCallResult;
-
-  /** 阈值信息（on.threshold hook 可用） */
-  threshold?: {
-    type: "tokens" | "turns" | "iterations" | "custom";
-    value: number;
-    limit?: number;
-  };
-
-  /** 当前错误（on.error hook 可用） */
-  error?: Error;
-
-  /** 当前 Agent 实例 */
-  agent: AgentInstance;
-
-  /** 当前迭代次数（可修改） */
-  iteration: number;
-
-  /** 最大迭代次数限制（before.llm hook 可用） */
-  maxIterations: number;
-
-  /** 消息列表（可直接修改） */
-  messages: ModelMessage[];
-
-  /** 可用工具列表（可直接修改） */
-  tools: Tool[];
-
-  /** 当前 system prompt（可直接修改） */
-  systemPrompt: string;
-
-  /** 额外的上下文信息（可直接修改） */
-  additionInfo?: string;
-
-  /** 执行上下文（可直接修改属性） */
-  context: AgentContext;
-
-  // ===== 内部状态（Plugin 通常不需要修改） =====
-
-  /** 是否已停止 */
-  _stopped?: boolean;
-
-  /** 停止原因 */
-  _stopReason?: string;
-
-  /** 待执行的干预动作 */
-  _pendingAction?: {
-    type: HookActionType;
-    payload?: unknown;
-  };
-
-  /** 错误列表 */
-  _errors?: Array<{
-    plugin: string;
-    error: string;
-  }>;
-
-  // ===== Memory Agent 特定字段 =====
-
-  /** Project Memory Agent 生成的摘要列表（由 Project Agent 写入，Global Agent 读取） */
-  projectSummaries?: ProjectSummary[];
-}
-
-/**
- * Hook 干预动作
- */
-export type HookActionType =
-  | "stop"             // 停止执行
-  | "retry"            // 重试当前迭代
-  | "compress"         // 执行压缩
-  | "extract_memory"   // 提取记忆
-  | "inject_message"   // 注入消息
-  | "skip_tool";      // 跳过当前工具调用
-
-/**
- * Hook 返回结果
- */
-export interface HookResult {
-  /** 是否继续执行（false = 停止 Agent） */
-  continue: boolean;
-
-  /** 干预动作（可选） */
-  action?: {
-    type: HookActionType;
-    payload?: unknown;
-  };
-}
-
-/**
- * Plugin 定义
- */
-export interface Plugin {
-  /** Plugin 唯一名称 */
-  name: string;
-
-  /** Plugin 版本 */
-  version: string;
-
-  /** Plugin 描述 */
-  description?: string;
-
-  /** 订阅的 Hook 点及优先级 */
-  hooks: Array<{
-    point: HookPoint;
-    /** 优先级，默认 0，数字越大越先执行 */
-    priority?: number;
-  }>;
-
-  /** 执行函数 */
-  execute: (ctx: HookContext) => HookResult | Promise<HookResult>;
-}
-
-// ============================================================================
-// Agent Types
-// ============================================================================
-
-/**
- * Agent 类型
- */
-export type AgentType = "primary" | "sub" | "summary";
-
-/**
- * Agent 状态
- */
-export type AgentStatus = "idle" | "running" | "paused" | "stopped" | "error";
-
-/**
- * Agent 实例配置
- */
-export interface AgentInstanceConfig {
-  /** Agent 类型 */
-  type: AgentType;
-
-  /** Agent 名称 */
-  name?: string;
-
-  /** System Prompt */
-  systemPrompt?: string;
-
-  /** Behavior Spec ID */
-  behaviorSpecId?: string;
-
-  /** 使用的模型 */
-  model?: string;
-
-  /** 最大迭代次数 */
-  maxIterations?: number;
-
-  /** 最大错误重试次数 */
-  maxErrorRetries?: number;
-
-  /** 死循环检测阈值 */
-  doomLoopThreshold?: number;
-
-  /** 允许的工具列表 */
-  allowedTools?: string[];
-
-  /** 拒绝的工具列表 */
-  deniedTools?: string[];
-
-  /** 工具超时（毫秒） */
-  toolTimeout?: number;
-
-  /** 工具重试次数 */
-  toolRetries?: number;
-
-  /** 是否过滤 history 中的 tool 消息（默认过滤，避免上下文过长） */
-  filterHistory?: boolean;
-}
-
-/**
- * Agent 实例
- */
-export interface AgentInstance {
-  /** Agent 名称 */
-  name: string;
-
-  /** Agent 配置 */
-  config: Required<AgentInstanceConfig>;
-
-  /** 当前状态 */
-  status: AgentStatus;
-
-  /** 注册的 Plugins */
-  plugins: Map<string, Plugin>;
-}
-
-/**
- * Agent 执行结果
- */
-export interface AgentRunResult {
-  /** 最终文本响应 */
-  finalText?: string;
-
-  /** 是否被 hook 停止 */
-  stopped?: boolean;
-
-  /** 停止原因 */
-  stopReason?: string;
-
-  /** 执行的迭代次数 */
-  iterations: number;
-
-  /** 工具调用列表 */
-  toolCalls: ToolCall[];
-
-  /** 错误信息（如有） */
-  error?: string;
-}
-
-// ============================================================================
-// LLM Types (from ../llm/types)
-// ============================================================================
-
-/**
- * LLM 调用结果
- * 
- * 复用 LLMComponent 的 LLMOutput，并扩展 Agent 特有字段
- */
-export interface LLMCallResult {
-  /** 成功 */
-  success: boolean;
-
-  /** 输出 */
-  output?: LLMOutput;
-
-  /** 错误信息 */
-  error?: string;
-
-  /** Usage 信息 */
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-}
-
-/**
- * Agent 内部使用的 LLM 输出
- * 独立定义以避免与 LLMOutput 的类型冲突
- */
-export interface AgentLLMOutput {
-  /** 生成的内容 */
-  content: string;
-  /** 完成原因 */
-  finishReason: "stop" | "length" | "content-filter" | "tool-calls" | "function-call";
-  /** 工具调用（兼容格式） */
-  toolCalls?: Array<{
-    id: string;
-    function?: {
-      name: string;
-      arguments: string;
-    };
-    name?: string;
-    arguments?: string;
-  }>;
-  /** Usage 信息 */
-  usage?: {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-  };
-  /** 生成模型 */
-  model?: string;
-  /** 推理内容（思考过程） */
-  reasoning?: string;
-}
-
-// ============================================================================
-// Summary Agent Types (new)
-// ============================================================================
-
-/**
- * Summary Agent 配置
- * 
- * 专门用于生成 session checkpoint 的 Agent
- */
-export interface SummaryAgentConfig extends AgentInstanceConfig {
-  /** Agent 类型 */
-  type: "summary";
-  
-  /** 使用的 prompt */
-  promptName: "session/compact";
-  
-  /** 默认模型 */
-  model?: string;
-  
-  /** 最大迭代次数（summary 任务只需 1 次） */
-  maxIterations: 1;
-}
-
-/**
- * Summary Agent 运行选项
- */
-export interface SummaryAgentRunOptions {
-  /** 消息列表 */
-  messages: Array<{
-    role: string;
-    content: string;
-  }>;
-  
-  /** 用户提供的上下文/提示 */
-  userContext?: string;
-  
-  /** 期望的输出格式 */
-  outputFormat: "json";
-  
-  /** 
-   * 场景化提示 (Scenario Hint)
-   * 
-   * 用于指导 checkpoint 生成的重点方向。
-   * 当提供此参数时，会在系统提示中添加场景上下文，
-   * 帮助 LLM 生成更符合当前场景的 checkpoint。
-   */
-  scenarioHint?: string;
-}
-
-/**
- * Summary Agent 运行结果
- */
-export interface SummaryAgentResult {
-  /** Checkpoint 标题 */
-  title: string;
-  
-  /** 过程要点 */
-  processKeyPoints: string[];
-  
-  /** 当前状态 */
-  currentState: string;
-  
-  /** 后续待跟进 */
-  nextSteps: string[];
-  
-  /** 用户意图列表 - 从对话中提取的用户相关意图 */
-  userIntents: string[];
-  
-  /** 原始 LLM 响应 */
-  rawResponse?: string;
-}
-
-// ============================================================================
-// Compact Hint Generation Types (new)
-// ============================================================================
-
-/**
- * Compact Hint 生成选项
- * 
- * 用于两阶段自动压缩流程中的第一阶段：
- * 根据会话历史生成场景化的压缩提示
- */
-export interface CompactHintGenerationOptions {
-  /** 消息列表 */
-  messages: Array<{
-    role: string;
-    content: string;
-  }>;
-  
-  /** 
-   * 会话上下文信息（可选）
-   * 
-   * 包含会话相关的额外信息，如：
-   * - 当前活跃任务信息
-   * - 工作目录
-   * - 最近的操作记录等
-   */
-  sessionContext?: {
-    activeTaskId?: string;
-    activeTaskTitle?: string;
-    workingDirectory?: string;
-    recentActions?: string[];
-  };
-}
-
-/**
- * Compact Hint 生成结果
- */
-export interface CompactHintGenerationResult {
-  /** 
-   * 场景化压缩指导提示（自然语言）
-   * 
-   * 这是一段"压缩指导 Prompt"，用于告诉 Compact 阶段：
-   * "在当前这个场景/目标/任务下，生成 checkpoint 时应该重点关注什么"
-   * 
-   * 示例：
-   * "Feature development. User is implementing JWT authentication for auth-service.
-   *  Focus on: auth flow decisions, token refresh progress, middleware implementation."
-   */
-  hint: string;
-  
-  /** 原始 LLM 响应 */
-  rawResponse?: string;
-}