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

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

@@ -0,0 +1,646 @@
+/**
+ * @fileoverview AgentComponent - Agent执行核心组件
+ *
+ * 基于 roy-agent docs/agent-component-design.md
+ * 参考 agent-core Agent.run 实现
+ *
+ * 核心功能：
+ * - ReAct 循环编排
+ * - Hook 机制和 Plugin 扩展
+ * - 多 Agent 管理
+ * - 工具调用
+ *
+ * 依赖：
+ * - ../llm - LLMComponent 用于 LLM 调用
+ * - ../log-trace/logger - createLogger 用于日志
+ */
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { AgentInstance, AgentInstanceConfig, AgentRunResult, AgentContext, Plugin, Tool } from "./types";
+import type { ModelMessage } from "ai";
+import type { LLMMessage } from "../llm/types";
+import type { ContentPart } from "../llm/types";
+import { z } from "zod";
+import type { ConfigComponent } from "../../config/config-component";
+import { type EnvContext } from "../context";
+import { AgentRegistry, type AgentDefinition } from "./agent-registry";
+/**
+ * Parse a tool list (allowedTools / deniedTools) from heterogeneous config sources.
+ *
+ * Task #2024 follow-up: EnvSource has no transform; when allowedTools/deniedTools
+ * is set via env var (e.g. AGENT_AGENT_DEFAULT_AGENT_ALLOWED_TOOLS=tool_a,tool_b),
+ * ConfigComponent.get() returns the raw string "tool_a,tool_b" rather than an array.
+ * The previous `as string[] | undefined` cast was a TypeScript lie: at runtime
+ * `allowedTools.includes(t.name)` became `String.prototype.includes` (substring match),
+ * not `Array.prototype.includes` (element match).
+ *
+ * Behavior:
+ *   - undefined / null → undefined (no filter)
+ *   - Array → returned as-is (after filtering out non-string entries defensively)
+ *   - String → split on ',', trim each entry, drop empty strings
+ *   - Anything else → undefined (defensive default)
+ *
+ * @param v - The raw value from constructor, config, env, or file source
+ * @returns Normalized string[] | undefined
+ */
+export declare function parseToolList(v: unknown): string[] | undefined;
+/**
+ * Task #2391 — v0.7.3 unknown-error hardening.
+ *
+ * Compose the LLM-facing tool-output string from a `ToolResult`. The
+ * previous code used `result.error || "Unknown error"` which silently
+ * dropped the runId + recovery hint whenever the tool's error field was
+ * empty. This helper produces a structured diagnostic instead, using
+ * whatever runId / status / metadata bits are present.
+ *
+ * Behavior:
+ *   - `success: true` → returns `output` (string or JSON-stringified record)
+ *   - `success: false` with non-empty `error` → returns `error`
+ *   - `success: false` with empty/missing `error` AND a runId →
+ *       returns `[ErrorType=EmptyErrorField] tool=<name> status=<s> runId=<id>
+ *               (no error message provided by tool — query workflow_run_status)`
+ *   - `success: false` with empty/missing `error` AND no runId →
+ *       returns `[ErrorType=EmptyErrorField] tool=<name> status=<s>
+ *               (no error message and no runId — tool did not surface a diagnostic)`
+ *
+ * Exported for testability (so the fallback string can be asserted
+ * directly without spinning up the full agent + LLM stack).
+ */
+export declare function composeToolOutputForLLM(toolName: string, result: {
+    success: boolean;
+    output: string | Record<string, unknown>;
+    error?: string;
+    metadata?: {
+        run_id?: string | number;
+        [k: string]: unknown;
+    };
+} | null | undefined): string;
+/**
+ * 将 ModelMessage 转换为 LLMMessage
+ *
+ * ModelMessage 来自 ai SDK，LLMMessage 是内部格式
+ */
+export declare function toLLMMessage(msg: ModelMessage): LLMMessage;
+/**
+ * AgentComponent 配置 Schema
+ */
+export declare const AgentComponentConfigSchema: z.ZodObject<{
+    defaultAgent: z.ZodObject<{
+        type: z.ZodDefault<z.ZodEnum<["primary", "sub"]>>;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        behaviorSpecId: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        maxIterations: z.ZodDefault<z.ZodNumber>;
+        maxErrorRetries: z.ZodDefault<z.ZodNumber>;
+        doomLoopThreshold: z.ZodDefault<z.ZodNumber>;
+        allowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        deniedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        toolTimeout: z.ZodDefault<z.ZodNumber>;
+        toolRetries: z.ZodDefault<z.ZodNumber>;
+        /** 是否过滤 history 中的 tool 消息（默认不过滤，保留完整上下文） */
+        filterHistory: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        type: "primary" | "sub";
+        maxIterations: number;
+        maxErrorRetries: number;
+        toolTimeout: number;
+        toolRetries: number;
+        doomLoopThreshold: number;
+        filterHistory: boolean;
+        systemPrompt?: string | undefined;
+        model?: string | undefined;
+        allowedTools?: string[] | undefined;
+        deniedTools?: string[] | undefined;
+        behaviorSpecId?: string | undefined;
+    }, {
+        type?: "primary" | "sub" | undefined;
+        systemPrompt?: string | undefined;
+        model?: string | undefined;
+        maxIterations?: number | undefined;
+        maxErrorRetries?: number | undefined;
+        allowedTools?: string[] | undefined;
+        deniedTools?: string[] | undefined;
+        toolTimeout?: number | undefined;
+        toolRetries?: number | undefined;
+        doomLoopThreshold?: number | undefined;
+        filterHistory?: boolean | undefined;
+        behaviorSpecId?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    defaultAgent: {
+        type: "primary" | "sub";
+        maxIterations: number;
+        maxErrorRetries: number;
+        toolTimeout: number;
+        toolRetries: number;
+        doomLoopThreshold: number;
+        filterHistory: boolean;
+        systemPrompt?: string | undefined;
+        model?: string | undefined;
+        allowedTools?: string[] | undefined;
+        deniedTools?: string[] | undefined;
+        behaviorSpecId?: string | undefined;
+    };
+}, {
+    defaultAgent: {
+        type?: "primary" | "sub" | undefined;
+        systemPrompt?: string | undefined;
+        model?: string | undefined;
+        maxIterations?: number | undefined;
+        maxErrorRetries?: number | undefined;
+        allowedTools?: string[] | undefined;
+        deniedTools?: string[] | undefined;
+        toolTimeout?: number | undefined;
+        toolRetries?: number | undefined;
+        doomLoopThreshold?: number | undefined;
+        filterHistory?: boolean | undefined;
+        behaviorSpecId?: string | undefined;
+    };
+}>;
+export type AgentComponentConfig = z.infer<typeof AgentComponentConfigSchema>;
+/**
+ * AgentComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface AgentComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "AGENT"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<AgentComponentConfig>;
+}
+/**
+ * 按 agent 的 `allowedAgentTypes` 工具级可见性过滤工具列表。
+ *
+ * 应用规则（与 ToolRegistry.listTools({ allowedAgent }) 保持一致）：
+ * - `metadata.allowedAgentTypes` 未设置 / 空数组 → 工具对所有 agent 可见
+ * - 非空数组 → 仅当 agent.name 命中任一元素时工具可见
+ * - 字符串精确匹配，大小写敏感
+ *
+ * 用途（2026-07-15 修复 review #14143 Medium #3）：
+ * - 统一在 AgentComponent.getAvailableTools 的三个入口（defaultTools / componentTools
+ *   / extraTools）都调用一次，避免某些路径绕过此过滤
+ * - ToolComponent.listTools 已经过滤过 componentTools 一次，此处再过滤属于
+ *   防御性二次保险
+ *
+ * @param tools 待过滤的工具列表（不会修改入参）
+ * @param agent 当前请求工具列表的 agent
+ * @returns 过滤后的新数组（保留原数组的相对顺序）
+ */
+export declare function filterToolsByAgent(tools: Tool[], agent: AgentInstance): Tool[];
+/**
+ * 构建一次 Agent run 的 EnvContext（effectiveContext + 父级 ALS 继承）。
+ *
+ * ★ Blocker 1（Task #4111 P0-2 / #4108 v2 根因）：把原先内联在
+ *   `AgentComponent._run()` 里的 EnvContext 构建抽为**纯函数**，便于用真实生产
+ *   代码做回归测试（此前测试 inline 复刻优先级，revert 生产代码后测试仍全绿 =
+ *   tautological，无法捕获回归）。
+ *
+ * 继承策略：
+ *   - 大部分字段沿用 `...parentEnvContext` 展开（父级 ALS 兜底）
+ *   - `envEvent` / `replyChannel`：**effective（当前事件）优先**，parent 兜底
+ *     —— 修复 #4106 → #3990 群送错群（parent ALS 缓存的上一事件 replyChannel
+ *     污染了当前事件的 replyChannel）
+ *   - 兼容：effective.envEvent.metadata 无 replyChannel（老 API 直接传 envEvent）时
+ *     仍回落 parent ALS，保证子 Agent 可用父级 replyChannel 发通知
+ */
+export declare function buildRunEnvContext(inputs: {
+    effectiveContext: AgentContext;
+    parentEnvContext: EnvContext | undefined;
+    envBoundParentTaskId: number | undefined;
+}): EnvContext;
+/**
+ * AgentComponent
+ *
+ * 提供 Agent 执行能力和 Hook 扩展机制
+ */
+export declare class AgentComponent extends BaseComponent {
+    readonly name = "agent";
+    readonly version = "1.0.0";
+    private agents;
+    private config;
+    private llmComponent;
+    private toolComponent;
+    private aborted;
+    private abortControllers;
+    private defaultTools;
+    private doomLoopCaches;
+    /** ConfigComponent 用于配置管理 */
+    private configComponent?;
+    /** 配置变更 watcher 清理函数 */
+    private configWatcher?;
+    /** Session 消息转换器 */
+    private messageConverter;
+    /** 构造函数传入的配置（最高优先级） */
+    private _constructorConfig?;
+    /** Run ID 计数器（用于生成唯一的 runId） */
+    /** AgentRegistry 用于持久化 agent 配置 */
+    private registry?;
+    private runCounter;
+    constructor(options?: {
+        config?: Partial<AgentComponentConfig>;
+    });
+    /**
+     * 初始化组件
+     *
+     * 配置加载优先级（从高到低）：
+     * 1. Object - 直接传入的 config 对象
+     * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+     * 3. File - 配置文件（通过 configPath 指定）
+     */
+    init(config: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    private registerConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 初始化 AgentRegistry
+     *
+     * 从 agent config folder 加载 agent 配置
+     */
+    private initRegistry;
+    /**
+     * 在 PromptComponent 就绪后，重新同步 registry agent 的 systemPrompt
+     */
+    syncRegistryAgentsFromConfig(): Promise<void>;
+    /**
+     * 获取 AgentRegistry
+     */
+    getRegistry(): AgentRegistry | undefined;
+    /**
+     * 从 Registry 获取 agent 定义
+     */
+    getAgentFromRegistry(name: string): AgentDefinition | undefined;
+    /**
+     * 列出 Registry 中所有 agent 定义
+     */
+    listAgentsFromRegistry(): AgentDefinition[];
+    /**
+     * 组件停止时的清理逻辑
+     *
+     * 清理内容：
+     * 1. 终止所有正在运行的 Agent（调用 abort() 以中断 LLM 调用）
+     * 2. 清空 AbortController 注册表
+     * 3. 清空 Doom Loop 缓存
+     * 4. 取消配置变更监听
+     * 5. 清空 Agent 注册表
+     */
+    protected onStop(): Promise<void>;
+    /**
+     * 刷新依赖组件引用
+     *
+     * 当组件被添加到 Environment 后调用，以确保获取到最新的组件引用
+     */
+    refreshDependencies(): Promise<void>;
+    /**
+     * 解析 agent 的 systemPrompt
+     *
+     * 处理 PromptComponent 延迟初始化的情况：
+     * - 若 agent 有 systemPromptRef 但尚无 systemPrompt，从 registry 延迟解析
+     * - 若已有 systemPrompt 则跳过（sync 或上次 run 已解析）
+     */
+    private resolveSystemPrompt;
+    /**
+     * 获取 Agent 实例
+     */
+    getAgent(agentName: string): AgentInstance | undefined;
+    /**
+     * 获取所有 Agent 实例
+     */
+    listAgents(): AgentInstance[];
+    /**
+     * Add placeholder tool results for remaining unprocessed tool calls
+     *
+     * This ensures that the message history maintains a 1:1 correspondence
+     * between tool-calls and tool-results, which is required by AI SDK v6.
+     *
+     * @param ctx - Hook context containing messages
+     * @param allToolCalls - All tool calls from the LLM response
+     * @param processedCount - Number of tool calls that have been processed
+     * @param reason - Reason for the abort/interruption
+     */
+    private addRemainingToolResults;
+    /**
+     * 注册 Agent
+     *
+     * 配置优先级（从高到低）：
+     * 1. registerAgent 传入的 config（来自 PromptComponent）
+     * 2. defaultAgent 配置（来自 ConfigComponent，作为 fallback）
+     */
+    registerAgent(name: string, config: Partial<AgentInstanceConfig>): AgentInstance;
+    /**
+     * 注销 Agent
+     */
+    unregisterAgent(name: string): boolean;
+    /**
+     * 注册 Plugin 到指定 Agent
+     */
+    registerPlugin(agentName: string, plugin: Plugin): void;
+    /**
+     * 注销 Plugin
+     */
+    unregisterPlugin(agentName: string, pluginName: string): boolean;
+    /**
+     * 设置默认工具列表
+     */
+    setDefaultTools(tools: Tool[]): void;
+    /**
+     * 获取可用工具
+     */
+    getAvailableTools(agent: AgentInstance, context?: AgentContext): Tool[];
+    /**
+     * 执行 Agent
+     *
+     * @param agentName Agent 名称
+     * @param query 用户查询
+     * @param context 执行上下文
+     * @returns Agent 执行结果
+     */
+    run(agentName: string, query: string | ContentPart[], context?: AgentContext): Promise<AgentRunResult>;
+    private pushMessage;
+    /**
+     * ✅ META PROTOCOL helper #1 — Task #2170.
+     * Captures (reads-and-deletes) the `toAddFakeUserMessage` metadata set by plugins
+     * such as `AutoTaskPlugin`. Idempotent: subsequent calls return undefined.
+     *
+     * Returns the captured `ModelMessage` (or undefined). The caller is responsible
+     * for storing it in `pendingFakeUserMessage` and pushing it AFTER all
+     * tool-results in the iteration complete (see `flushPendingFakeUserMessage`).
+     *
+     * Span: `agent.meta-protocol.consumeUserMessage`
+     */
+    private consumeMetaProtocolUserMessage;
+    /**
+     * ✅ META PROTOCOL helper #2 — Task #2170.
+     * Pushes the previously-captured `toAddFakeUserMessage` to `ctx.messages`.
+     * Called ONCE per ReAct iteration AFTER the for-loop ends, so the user message
+     * is appended after ALL tool-results (not between them), preserving AI SDK v6's
+     * strict `tool_call` ↔ `tool_result` adjacency requirement.
+     *
+     * Span: `agent.meta-protocol.flushPendingUserMessage`
+     */
+    private flushPendingFakeUserMessage;
+    /**
+     * 执行 Agent（核心方法，内部实现）
+     */
+    private _run;
+    /**
+     * 中止 Agent
+     *
+     * 调用此方法会：
+     * 1. 设置 aborted 标志（用于 ReAct 循环检查）
+     * 2. 触发 AbortController.abort()（用于中断正在进行的 LLM 调用）
+     *
+     * 注意：不直接修改 agent.status，由 _run() 的 finally 统一处理
+     */
+    abort(agentName: string): void;
+    /**
+     * Task #2590 follow-up — run-scoped abort.
+     *
+     * Abort a single agent run by its runId, rather than by agent name. The
+     * agent-name-scoped `abort(agentName)` is "every concurrent run of the
+     * same type" — silent-fail root cause when invoked from a sub-agent's
+     * signal listener that escaped after the sub-agent already finished.
+     *
+     * Caller contract: pass a runId that was either pre-allocated via
+     * `AgentContext.runId` and stored on the caller's task record, or
+     * otherwise observed through normal AgentComponent logging.
+     *
+     * Idempotent: aborting an already-aborted or already-finalized run is a
+     * no-op. The AbortController itself is also idempotent.
+     *
+     * @returns true if the runId was found and the abort signal was issued,
+     *          false if the runId had already finalized and was removed from
+     *          the registry.
+     */
+    abortRun(runId: string, reason?: string): boolean;
+    /**
+     * 中止所有正在运行的 Agent
+     *
+     * 与 abort(name) 不同，此方法会终止全部 Agent run，
+     * 包括父 agent 通过 delegate_task 创建的子 agent。
+     * 用于 ESC/abort 等用户主动中断场景。
+     */
+    abortAll(): void;
+    /**
+     * 构建消息列表
+     *
+     * 注意：ctx.messages 已经包含了历史消息（包括 system prompt 和 user query）
+     * 这里只需要构建当前请求的消息，不重复添加
+     */
+    /**
+     * 【Task #2744】session-scope cache snapshot 加载/创建/持久化
+     *
+     * 设计目标：把 systemPrompt（{{memory}} 已替换）和 additionInfo 绑定到 session 生命周期，
+     * first-run 计算一次并持久化到 session.metadata.cacheSnapshot，后续 _run 直接复用
+     * → 字节级一致 → LLM prompt cache 命中。
+     *
+     * @returns
+     * - snapshot: 冻结的 { systemPrompt, additionInfo, snapshotAt } 快照
+     * - systemPromptOverride: 如果 snapshot 命中，覆盖调用方的 resolvedSystemPrompt
+     *   （值是 snapshot.systemPrompt，命中时与 snapshot.systemPrompt 相同）
+     *
+     * 错误处理：所有 I/O 失败均降级为"返回 null"（调用方走 fallback 路径），
+     * 不阻塞 run。
+     */
+    private _loadOrCreateCacheSnapshot;
+    /**
+     * 【Task #2744】无 sessionId 时的 {{memory}} fallback 替换
+     *
+     * 场景：sub-agent 或单元测试不传 sessionId → 走原 P1-1 行为（每 run 重新 recallMemory）。
+     * 这是为了保持对无 session 路径的向后兼容，不影响 cache 路径。
+     */
+    private _fallbackReplaceMemory;
+    /**
+     * 构建 additionInfo（含 currentTaskId 上下文注入）
+     *
+     * 通过 @TracedAs 追踪，可在 debug trace / debug span 中查看
+     * currentTaskId 是否成功注入到 LLM 上下文
+     *
+     * Task #2744 (session-scope cache optimization):
+     * 如果 ctx._cacheSnapshot 存在（由 AgentComponent._run 在 first-run 时持久化到
+     * session.metadata.cacheSnapshot），则返回 snapshot 的 additionInfo，**跨多轮
+     * 保持字节级一致** —— 这是 LLM prompt cache 命中的前提。
+     *
+     * 否则降级到当前行为：从 ctx.context.additionInfo 读取（每次 buildMessages 都
+     * 重读，可能因 caller 传入不同值而变化 → cache miss）。
+     */
+    private _buildAdditionInfo;
+    private buildMessages;
+    /**
+     * 【Task #2760 Dim 6】把 ctx.tools 格式化为 toolDefinitions 字符串
+     *
+     * 目的：让 buildMultiBlockSystem 输出一段独立的 toolDefinitions 段（挂 cache_control），
+     * 这样 OpenAI-Compatible provider 也可以通过 prompt_cache_key 命中工具 schema 前缀。
+     * Anthropic 已经有 applyToolCacheControl 在 tool 字段挂 cache_control（独立 cache），
+     * 但 system prompt 内的 toolDefinitions 段是冗余但无害的（AI SDK 会去重）。
+     *
+     * 格式化策略：每行 `name: description` 的紧凑列表。JSON 序列化参数过于详细，
+     * 紧凑列表足以让 LLM 列出可用工具。
+     *
+     * 内容稳定性：相同 ctx.tools 跨 run 输出 byte-equal → 缓存命中。
+     * （按 name 排序，确保多 run 工具顺序变化也 byte-stable）
+     */
+    private _formatToolDefinitions;
+    /**
+     * 调用 LLM
+     *
+     * 流式事件由 LLMComponent 通过 env.pushEnvEvent() 发布
+     */
+    private invokeLLM;
+    /**
+     * Task #2723: 归一化上游 tool-call shape → 内部 `Record<string, unknown>`。
+     *
+     * 两种上游 shape 都会在调用前被转换成 JSON object：
+     * - AI SDK 兼容：`{ id, function: { name, arguments: string } }`
+     * - pi-ai 顶层：`{ id, name, arguments: string }` (无 `function` 包装)
+     *
+     * `safeParseToolArgs()` 递归处理 normal / double-stringified / already-object /
+     * malformed 输入，失败 fallback 到 `{}`，避免把 `_raw` 泄漏到 session。
+     *
+     * Trace 维度只记录 source / type / keys（不记录 raw value），以免污染 span store。
+     */
+    private parseToolCallArguments;
+    /**
+     * 严格版参数解析（Task #4231）
+     *
+     * 与 `parseToolCallArguments` 的差别：失败时返回 `ok:false` 而不是空对象，
+     * 让调用方能把错误回给模型、并**拒绝执行**这条工具调用。
+     * 会先尝试抢救上游退化格式（GLM 的 `<arg_key>/<arg_value>` 文本标记）。
+     */
+    private parseToolCallArgumentsStrict;
+    /**
+     * 执行工具
+     *
+     * errorIf：只有「工具根本不存在」（未注册 / 被 allowedTools|deniedTools 过滤掉）
+     * 才把 span 标成 ERROR —— 这是 prompt 承诺与实际工具表不一致的**配置错误**，
+     * 属于必须显式可见的 bug。
+     *
+     * 刻意不覆盖「工具执行失败」（`success:false` 且有真实 error，如 bash exit!=0）：
+     * 那是正常运行时结果，全标 ERROR 会让 trace 里遍布红色噪音、反而掩盖真问题。
+     */
+    private executeTool;
+    /**
+     * 执行 Plugin Hooks (Agent 特有的 Hook 执行机制)
+     *
+     * 执行顺序：
+     * 1. Agent 自己的 plugins（通过 agent.plugins）
+     * 2. EventSource 加载的 plugins（通过 globalHookManager + pluginEnabled 检查）
+     */
+    private executePluginHooks;
+    /**
+     * 处理 Hook 动作
+     */
+    private handleHookAction;
+    /**
+     * 通知消息添加（扩展点）
+     */
+    protected notifyMessageAdded(message: ModelMessage): void;
+    /**
+     * 结束结果
+     */
+    private finalizeResult;
+    /**
+     * Record messages to session
+     *
+     * 存储策略：
+     * 1. 存储 allMessages 中的所有 user、assistant、tool 消息
+     * 2. 跳过 system 消息
+     * 3. 跳过空内容的 assistant/tool 消息
+     *
+     * Layer 3 wiring (sessions.db fix): instead of N individual addMessage
+     * calls (each = INSERT message + UPDATE session.message_count = 2
+     * statements per row), we filter first and dispatch ONCE per React
+     * iteration through sessionComponent.addMessages, which performs the
+     * whole batch in a single BEGIN/COMMIT. This eliminates the lock
+     * amplification that turned short contentions into full SQLITE_BUSY
+     * storms (the root cause of the 2026-07-07 incident).
+     */
+    private recordSessionMessages;
+    /**
+     * 检查消息内容是否为空
+     *
+     * 空内容定义：
+     * - 空字符串 ""
+     * - 空数组 []
+     * - null
+     * - undefined
+     *
+     * @param content - 消息内容
+     * @returns 是否为空
+     */
+    private isEmptyMessage;
+    /**
+     * 通过 Environment 发送事件
+     */
+    private pushEnvEvent;
+    /**
+     * 获取会话对话历史
+     *
+     * 核心逻辑：
+     * 1. 使用 sessionComponent.getContext() 获取消息（自动从 checkpoint 开始）
+     * 2. 根据 messageLimit 限制消息数量（向后兼容 minUserMessages）
+     * 3. 过滤掉 tool_call/tool_result 消息（如果 filterHistory=true）
+     *
+     * 关键改进：利用 checkpoint 概念，避免重复获取已压缩的历史消息，
+     * 从而减少重复触发压缩的问题。
+     *
+     * @param sessionComponent - SessionComponent 实例
+     * @param sessionId - 会话 ID
+     * @param options - 配置选项
+     * @param options.minUserMessages - 最少包含的 user 消息数量（默认 100）
+     * @param options.filterHistory - 是否过滤 tool 消息（默认 true）
+     * @returns 过滤后的会话消息列表
+     */
+    private getConversationHistory;
+}
+/**
+ * 【Task #2748 §5.6】Multi-block system prompt 构造（顶层 helper，可独立测试）
+ *
+ * 把 system prompt 拆分为 4 段独立 cache 块（每段独立 cache_control）：
+ * - [0] characterSheet: 角色设定（极少变，独立 cache 长期命中）
+ * - [1] toolDefinitions: 工具定义（config 不变就不变）
+ * - [2] memoryBlock: 记忆块（变化频率低）
+ * - [3] dynamicContext: 动态上下文（currentTaskId 等，可能变）
+ *
+ * 设计依据（参考 pi-agent multi-block system）：
+ * - Anthropic 端原生支持多 system block + 每 block 独立 cache_control
+ * - 拆段后，dynamic 段变化只让 [3] 段 cache 失效，[0][1][2] 仍命中
+ *
+ * 当前 buildMessages 仍使用单段 system message（向后兼容）。
+ * 本函数作为 helper 暴露，便于测试 + 未来切到 multi-block 模式时复用。
+ */
+export declare function buildMultiBlockSystem(ctx: {
+    characterSheet: string;
+    toolDefinitions?: string;
+    memoryBlock?: string;
+    dynamicContext?: string;
+}): ModelMessage[];

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

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Agent Component 配置注册
+ *
+ * 使用 ConfigComponent.registerComponent() 机制统一管理配置
+ */
+import type { ComponentRegistration } from "../../config/config-component";
+/**
+ * Agent Component 默认配置值
+ *
+ * 注意：键使用完整格式（带 "agent." 前缀），在 registerConfig 中手动设置
+ */
+export declare const AGENT_DEFAULTS: Record<string, unknown>;
+/**
+ * Agent Component 配置注册常量
+ *
+ * 定义了所有 Agent 相关的配置项和来源
+ */
+export declare const AGENT_CONFIG_REGISTRATION: ComponentRegistration;