@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/agent/types.d.ts

@@ -0,0 +1,503 @@
+/**
+ * @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";
+type AbortSignalType = AbortSignal;
+export { Tool, ToolResult };
+export interface ProjectSummary {
+    projectPath: string;
+    projectName: string;
+    lastUpdated: number;
+    summary: string;
+    shortSummary: string;
+    draftCount: number;
+    memoryMdPath: string;
+    draftsDir: string;
+    detailsDir: string;
+}
+/**
+ * Agent 执行上下文
+ */
+export interface AgentContext {
+    /** 会话 ID */
+    sessionId?: string;
+    /** 消息 ID */
+    messageId?: string;
+    /** Trace ID（每次 query 唯一，用于 per-query 去重和追踪） */
+    traceId?: 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;
+    /**
+     * Task #2590 follow-up — caller-provided run id.
+     *
+     * If provided, the agent run uses this id instead of an internally generated
+     * one (AgentComponent.runCounter). The caller is responsible for ensuring
+     * the id is unique within the AgentComponent instance and stable for the
+     * lifetime of the run. Run id is used to key `aborted` / `abortControllers`
+     * maps inside AgentComponent, so callers wanting run-scoped abort
+     * (e.g. BackgroundTaskManager.executeWithAbort) should pre-allocate an id
+     * and pass it in. This eliminates the need for an onRunStarted callback
+     * and lets the caller record (runId, taskRecord) BEFORE the run actually
+     * starts.
+     *
+     * Validation:
+     *   - Must not be empty / whitespace-only (AgentComponent._run rejects explicitly)
+     *   - Must not already be in `aborted` / `abortControllers` Maps
+     *
+     * If not provided, AgentComponent allocates a new id from its internal
+     * `runCounter` (preserves backward compatibility with existing callers).
+     */
+    runId?: string;
+    /**
+     * Issue #1694 Layer 1: override message history for this run.
+     *
+     * RESERVED FOR FUTURE USE: When provided (non-empty), AgentComponent._run()
+     * will use this array INSTEAD of loading history from the session DB.
+     *
+     * Current callers (as of Task #1694 commit c6c10707):
+     *   - workflow-json-output-plugin does NOT yet pass `messages`
+     *   - json-extract sub-agent still reads session DB history
+     *
+     * Future use cases:
+     *   - Caller wants to inject SANITIZED history (strip main agent pollution)
+     *   - Caller wants to inject SYNTHETIC history (e.g., for testing)
+     *   - Caller wants to share history across multiple sub-agent runs
+     *
+     * Behavior when set:
+     *   - effectiveContext.messages.length > 0 → use as hookCtx.messages
+     *   - effectiveContext.messages is undefined or empty → fallback to session DB
+     *
+     * Only ModelMessage[] is accepted (matches the format the LLM expects).
+     * The first message, if any, MAY be a system message.
+     */
+    messages?: ModelMessage[];
+    /**
+     * Issue #1694 root-cause fix: Force LLM to call a specific tool (or any
+     * tool) when this context is used.
+     *
+     * - `"required"` — force LLM to call at least one tool
+     * - `{ type: "function", function: { name: "..." } }` — force a specific tool
+     * - undefined / "auto" — let LLM choose (default)
+     *
+     * Primary use case: workflow-json-output-plugin forces json-extract
+     * sub-agent to call `workflow_submit_output`, eliminating the
+     * non-deterministic failure where sub-agent sees the parent's markdown
+     * JSON output and decides "already done" (finishReason=stop, no tool call).
+     *
+     * Propagated by AgentComponent.invokeLLM to llmComponent.invoke, then to
+     * AI SDK streamText's `toolChoice`.
+     */
+    toolChoice?: "auto" | "none" | "required" | {
+        type: "function";
+        function: {
+            name: string;
+        };
+    };
+    /** 处理事件的 agent 名称（EventSource 指定） */
+    agentName?: string;
+    /** 启用的插件列表（EventSource 指定） */
+    plugins?: string[];
+    /** 关联的 EnvEvent（EventSource 事件） */
+    envEvent?: import("../types").EnvEvent;
+    /** Plugin 启用标记 { "sourceId:pluginName": true } */
+    pluginEnabled?: Record<string, boolean>;
+    /** 额外工具列表（上下文级别，会追加到可用工具列表末尾） */
+    extraTools?: import("../tool/types").Tool[];
+    /** 是否将 ReAct 消息持久化到 session DB（默认 true）。
+     *  设为 false 时，agent run 仍会读取 session history，但不会写入新消息。
+     *  用于子 agent 复用父 session 的 history 但不污染 session DB。 */
+    persistSession?: 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 点枚举（带 component 前缀）
+ */
+export type HookPoint = "agent:before.start" | "agent:before.llm" | "agent:after.llm" | "agent:before.tool" | "agent:after.tool" | "agent:on.iteration" | "agent:on.threshold" | "agent:after.complete" | "agent:on.error" | "agent:after.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 {
+    /** 当前 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;
+    /**
+     * Task #2744: session-scope cache snapshot (internal use)
+     *
+     * 持久化在 session.metadata.cacheSnapshot，由 AgentComponent._run 在 first-run
+     * 创建并透传给 buildMessages。buildMessages 使用 snapshot 的 additionInfo（而非
+     * 每轮重读 ctx.context.additionInfo）以保证 system prompt 字节级一致 → LLM
+     * prompt cache 命中。
+     *
+     * - systemPrompt: 含 {{memory}} 替换后的最终字符串
+     * - additionInfo: first-run 时的 additionInfo（冻结）
+     * - snapshotAt: 持久化时间戳
+     *
+     * 第三方代码不应直接修改此字段。如需强制重建 snapshot，可通过
+     * sessionComponent.update(sessionId, { metadata: { cacheSnapshot: null } }) 清除。
+     */
+    _cacheSnapshot?: {
+        systemPrompt: string;
+        additionInfo: string;
+        snapshotAt: number;
+    };
+    /** 执行上下文（可直接修改属性） */
+    context: AgentContext;
+    /** 是否已停止 */
+    _stopped?: boolean;
+    /** 停止原因 */
+    _stopReason?: string;
+    /** 待执行的干预动作 */
+    _pendingAction?: {
+        type: HookActionType;
+        payload?: unknown;
+    };
+    /** 错误列表 */
+    _errors?: Array<{
+        plugin: string;
+        error: string;
+    }>;
+    /** Structured JSON extracted by workflow plugin after ReAct (agent:after.react) */
+    structuredOutputExtracted?: Record<string, unknown>;
+    /** 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 类型
+ */
+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;
+    /** System Prompt 引用（指向 PromptComponent 中的 prompt） */
+    systemPromptRef?: 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;
+    /** 原始错误对象（用于保留 ContextError 等类型信息） */
+    originalError?: Error;
+    /** Structured JSON output (populated by workflow plugin after ReAct) */
+    structuredOutput?: Record<string, unknown>;
+}
+/**
+ * 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 配置
+ *
+ * 专门用于生成 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 生成选项
+ *
+ * 用于两阶段自动压缩流程中的第一阶段：
+ * 根据会话历史生成场景化的压缩提示
+ */
+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;
+}

package/dist/env/commands/commands-component.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview CommandsComponent
+ *
+ * 命令管理核心组件（收藏式）
+ *
+ * 功能：
+ * - 管理 user/project 多路径命令目录
+ * - 提供命令发现、添加、移除、执行能力
+ * - 支持 File/Env/Object 三种配置来源
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { CommandIndex, CommandMeta, ScanResult, DiscoverOptions, AddCommandOptions, RemoveCommandOptions, ExecutionResult } from "./types";
+export declare class CommandsComponent extends BaseComponent {
+    readonly name = "commands";
+    readonly version = "2.0.0";
+    private config?;
+    private configComponent?;
+    private userCommandsDir;
+    private projectCommandsDir;
+    private descriptionCache;
+    private descriptionCacheFile;
+    constructor();
+    private initDefaultDirs;
+    /**
+     * 初始化组件
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. File - 配置文件
+     * 2. Env - 环境变量
+     * 3. Object - 直接传入的 config 对象
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 使用 SessionComponent 的正确模式：
+     * 1. 使用 registerComponent() 注册配置（包含 sources、keys、defaults）
+     * 2. 使用 load("command") 加载配置值
+     * 3. 处理环境变量后备方案
+     * 4. 处理 config 对象（最高优先级）
+     */
+    private registerConfig;
+    /**
+     * 将嵌套配置扁平化
+     */
+    private flattenConfig;
+    /**
+     * 从 ConfigComponent 应用配置
+     */
+    private applyConfig;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 获取命令目录列表
+     */
+    getCommandDirs(): Promise<{
+        user: string;
+        project: string;
+    }>;
+    /**
+     * 发现命令
+     */
+    discover(options?: DiscoverOptions): Promise<ScanResult>;
+    /**
+     * 添加命令
+     */
+    add(options: AddCommandOptions): Promise<void>;
+    /**
+     * 创建命令的 meta.md 文件
+     */
+    private createCommandMeta;
+    /**
+     * 获取所有收藏命令的元信息（用于 Prompt 注入）
+     */
+    getCommandsMeta(): Promise<CommandMeta[]>;
+    /**
+     * 移除命令
+     */
+    remove(options: RemoveCommandOptions): Promise<void>;
+    /**
+     * 获取命令信息
+     */
+    getInfo(name: string): Promise<CommandIndex | null>;
+    /**
+     * 执行命令
+     */
+    exec(options: {
+        name: string;
+        args?: string[];
+        cwd?: string;
+    }): Promise<ExecutionResult>;
+    private scanDir;
+    private matchPattern;
+    private getDescription;
+    private loadDescriptionCache;
+    private saveDescriptionCache;
+}

package/dist/env/commands/commands-config-registration.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Commands Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * Commands Component 默认配置值（占位，实际值在 registerConfig 中动态设置）
+ *
+ * 注意：这些默认值在 CommandsComponent.registerConfig() 中
+ * 通过 configComponent.set() 设置到 ConfigComponent，使用基于 HOME 的绝对路径
+ */
+export declare const COMMANDS_DEFAULTS: Record<string, unknown>;
+/**
+ * Commands Component 配置注册常量
+ *
+ * 定义了所有 Commands 相关的配置项和来源
+ */
+export declare const COMMANDS_CONFIG_REGISTRATION: ComponentRegistration;

package/dist/env/commands/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Commands Component Module
+ *
+ * 导出 CommandsComponent 及其类型
+ */
+export { CommandsComponent } from "./commands-component";
+export type { CommandsComponentOptions, CommandsComponentConfig, CommandSource, CommandIndex, ScanResult, DiscoverOptions, AddCommandOptions, RemoveCommandOptions, ExecutionResult, } from "./types";

package/dist/env/commands/parser.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Command Meta.md Parser
+ *
+ * 解析命令目录下的 meta.md 文件，提取 Frontmatter 元信息
+ */
+import type { CommandMeta, CommandSource } from "./types";
+/**
+ * 解析 frontmatter 文本
+ */
+export declare function parseFrontmatter(text: string): Record<string, string>;
+/**
+ * 解析单个 meta.md 文件
+ */
+export declare function parseMetaFile(filePath: string, source: CommandSource): Promise<CommandMeta | null>;
+/**
+ * 扫描目录下的所有 meta.md 文件
+ */
+export declare function scanMetaFiles(dirPath: string, source: CommandSource): Promise<CommandMeta[]>;