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

package/dist/env/event-source/bounty-im-handler.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Bounty IM EventSource Handler
+ *
+ * Built-in handler for bounty-IM event source (roy-agent core)
+ *
+ * Decoupled from ai-agent-bounty's bountyConfig:
+ * - email / imServerUrl must be explicit (no env var fallback)
+ * - Uses component's eventHandler chain instead of dynamic env import
+ * - handleRule.agent is forwarded into metadata (aligned with larkCli handler)
+ *
+ * v0.14 (Task #2129): strict email-only
+ * - bounty IM identity = email (注册邮箱) ONLY
+ * - address 字段彻底移除（v0.12/v0.13 不再支持）
+ * - 启动时 hard error on 历史 address field
+ *
+ * 启动方式：
+ *   roy-agent interactive --es <source-id>
+ *   或
+ *   roy-agent eventsource start <source-id>
+ *
+ * 配置文件 ~/.roy-agent/event-sources.json 中应包含：
+ * {
+ *   "id": "bounty-im-auto",
+ *   "name": "Bounty IM (Auto)",
+ *   "type": "bounty-im",
+ *   "email": "alice@bounty.example.com",
+ *   "imServerUrl": "ws://localhost:4005/ws"
+ * }
+ */
+import type { EventSourceHandler, EventSourceInstance, EventSourceConfig, EventSourceEventHandler, EventSourceStatus } from "./types";
+/**
+ * v0.14 启动时迁移检查：如果用户 config 仍有历史 `address` 字段（v0.12/v0.13），
+ * 给 hard error 提示用户迁移。
+ *
+ * 设计选择（HARD ERROR）：
+ * - 与 bounty v0.14 strict philosophy 一致
+ * - 不做静默 fallback，避免"看起来 work 但行为不一致"问题
+ *
+ * @throws Error if address field is detected
+ */
+export declare function assertNoLegacyAddressField(config: EventSourceConfig): void;
+/**
+ * 决定当前进程是否需要写 `NODE_TLS_REJECT_UNAUTHORIZED=0` 来强制跳过 TLS 证书校验。
+ *
+ * ## 背景
+ *
+ * `ws@^8.16.0` 库的 `WebSocket` 构造选项里 `rejectUnauthorized: false` 在 **Node.js** runtime
+ * 下能正确禁用 TLS 证书验证；但 **bun** runtime 下该 per-WebSocket 选项被 bun 的 TLS 层
+ * 忽略（Bun 优先读取自身的 global TLS 配置）。这是已知 quirk，详见 bun issue tracker。
+ *
+ * bun 的 TLS 层会正确响应 `NODE_TLS_REJECT_UNAUTHORIZED=0` 环境变量，所以这是唯一在
+ * bun dev 模式下能强制跳过自签名证书校验的途径。
+ *
+ * ## 用户强约束（Phase B.9）
+ *
+ * 1. **绝对不允许**在 Node.js 生产环境下写 env var。
+ * 2. **绝对不允许**影响同进程其他 TLS 连接（这种"全进程 TLS skip"是已知副作用，
+ *    docs/event-source.md#tls-skip-verify 已注明）。
+ *
+ * 因此该 helper 同时检查两个条件：
+ * - `tlsSkipVerify === true`（用户显式开启）
+ * - runtime 是 bun（通过可选的 `isBunRuntimeOverride` 测试注入；默认用 `typeof Bun` 检测）
+ *
+ * @param tlsSkipVerify - 用户配置：是否要跳过 TLS 验证
+ * @param isBunRuntimeOverride - 测试 seam：默认 `typeof Bun !== "undefined"`；
+ *   测试可显式注入 `false` 模拟 Node.js runtime。
+ *
+ * @see docs/event-source.md#tls-skip-verify (Phase B.9)
+ */
+/**
+ * 构建 BountyIM 默认 systemPrompt（Phase B.11+）
+ *
+ * 当用户没有显式配置 EventSourceConfig.systemPrompt 时使用此默认值。
+ * 目的：让 agent 处理 bounty-IM 消息时，知道自己的 email、IM server URL、回复命令。
+ *
+ * 这对于 REPL dispatch 后正确生成回复消息至关重要——
+ * 没有这段 prompt，agent 不知道自己是哪个 email，也不知道用什么命令回复。
+ *
+ * v0.14 strict: 只支持 email 命令格式（`--from-email/--to-email`）。
+ * 不再有 `currentAddress` / `-f/-t` alias fallback（v0.12/v0.13 已彻底移除）。
+ */
+export declare function buildDefaultBountyIMSystemPrompt(input: {
+    currentEmail?: string;
+    imServerUrl?: string;
+}): string;
+/**
+ * v0.14.1+ email-display fix:
+ * 把 IM WebSocket 入站 URL (wss://host:port/ws) 转成出站 HTTP API URL
+ * (https://host:port) 供 `bounty com send --server-url <...>` 使用。
+ *
+ * 这是推荐回复模板里 `${imServerUrl}` 直接拿来当 `--server-url` 用的根本 bug——
+ * IM 入站走 wss，但 HTTP API 必须用 https。
+ *
+ * 规则（与 buildDefaultBountyIMSystemPrompt 一致；独立抽出便于复用 + 单测）：
+ * - `wss://host[:port]/path` → `https://host[:port]`
+ * - `ws://host[:port]/path`  → `http://host[:port]`
+ * - 末尾 `/ws` 自动剥离
+ */
+export declare function translateImServerUrlToHttpApi(imServerUrl: string): string;
+/**
+ * v0.14.1+ email-display fix:
+ * 解析 canonical `<uuid>@<host>` 形式到注册邮箱。
+ *
+ * 设计选择：
+ * - canonical = `<uuid>@host` (uuid 模式) → 返回 null（client 端没有 db，
+ *   不能确定；让 caller 决定是显示 canonical 还是 `<recipient-registered-email>`
+ *   占位符）
+ * - canonical = `<uuid>@authenticated` → 返回 profileEmail（best effort：
+ *   用于回包命令 `--from-email`，因为服务端 routing 这一侧能看到的就是当
+ *   前 WS subscriber 的 UUID）
+ * - canonical = 已经是 email 形式（`xxx@yyy.zzz`）→ 原样返回
+ *
+ * 注意：这只是 best-effort 的 client-side resolver。最权威的 email 始终
+ * 来自服务端：`msg.fromEmail`（服务端把 `<uuid>@authenticated` 解析成
+ * sender 注册邮箱后通过 WS push 下来）。caller 应该总是优先用
+ * `msg.fromEmail`，本函数仅作 fallback。
+ */
+export declare function resolveCanonicalToEmail(canonical: string | undefined | null, profileEmail: string | undefined | null): string | null;
+/**
+ * 决定当前 instance 的 systemPrompt（Phase B.11+）
+ *
+ * 优先级：
+ * 1. config.systemPrompt（用户显式配置）
+ * 2. 默认 prompt（通过 buildDefaultBountyIMSystemPrompt 构造）
+ *
+ * v0.14: 不再接受 currentAddress 参数（identity = email only）。
+ */
+export declare function resolveBountyIMSystemPrompt(input: {
+    configSystemPrompt?: string;
+    currentEmail?: string;
+    imServerUrl?: string;
+}): string;
+/**
+ * 检测当前 agent 自己发出去的消息被 server 推回 (Task #2136)
+ *
+ * 背景：bounty IM server 在某些情况下会把 agent 自己的 outbound 消息
+ * 推回给自己，造成 self-echo（用户日志里 [From gddzhaokun@126.com] 后
+ * 的 `--to-email` 也是 gddzhaokun@126.com）。
+ *
+ * 优先级：
+ * 1) 优先用 server enrichment 的注册邮箱 `msg.fromEmail`（v0.14.1+）
+ *    → 注册邮箱是 v0.14 strict 的 canonical identity，最精确
+ * 2) fallback: 客户端从 canonical `<uuid>@<host>` 形式推断
+ *    - pre-v0.14.1 server 不会 enrich fromEmail
+ *    - 比对 from 和 to 在 "@" 之前的 UUID 部分
+ *      如果相同，说明是同一个 agent（不管 host 后缀）
+ * 3) 都没有信息 → 返回 false（保守放行，让下游处理）
+ *
+ * @param msg bounty WS event.data（包含 from / to / fromEmail 字段）
+ * @param currentEmail 当前 instance 的注册邮箱（config.email）
+ * @returns true 表示这条消息是自己发的，应该 skip
+ */
+export declare function isSelfEcho(msg: unknown, currentEmail: string | undefined): boolean;
+/**
+ * 检测消息的收件人（msg.to）是不是当前 agent（Task #2136）
+ *
+ * 返回 true 表示"这条消息不属于我"，应该 skip。
+ *
+ * 用途：
+ * - v0.14 strict 1-to-1 routing：msg.to 必须指向当前 agent
+ * - 防止 server 误推其他 agent 的消息给当前 instance
+ * - 防止 broadcast / leak 类型的 noise
+ *
+ * 判定逻辑（避免 mixed-form 误判）：
+ * - msg.to 空 → false（broadcast / 未指定，让其通过）
+ * - currentEmail 空 → false（无 identity 比对信息）
+ * - msg.to 与 currentEmail 都是 email → 完整匹配才算 "to me"
+ * - msg.to 与 currentEmail 都是 canonical UUID 形式 → 比较 "@" 之前的 UUID
+ * - 一 email 一 canonical（mixed）→ false（incomparable，兼容 pre-v0.14 server）
+ *
+ * @param msg bounty WS event.data（包含 to 字段）
+ * @param currentEmail 当前 instance 的注册邮箱 / 身份
+ * @returns true 表示 msg.to 指向别人，应该 skip
+ */
+export declare function isWrongAddress(msg: unknown, currentEmail: string | undefined): boolean;
+export declare function shouldWriteBunTlsSkipEnv(tlsSkipVerify: boolean, isBunRuntimeOverride?: boolean): boolean;
+export declare class BountyIMInstance implements EventSourceInstance {
+    private config;
+    private status;
+    private ws;
+    private buffer;
+    private eventHandler?;
+    /**
+     * Environment 引用（由 EventSourceComponent.startSource 调用 setEnvironment 注入）
+     */
+    private environment?;
+    constructor(config: EventSourceConfig);
+    /**
+     * 注入 Environment 引用（实现 EventSourceInstance.setEnvironment）
+     */
+    setEnvironment(env: unknown): void;
+    /**
+     * 获取当前配置的 email（v0.14 strict single canonical identity）
+     *
+     * v0.14: bounty IM identity 只用 email 字段，address 字段不再支持。
+     */
+    private getCurrentIdentity;
+    /**
+     * 获取当前配置的地址（v0.14: 就是 email）
+     *
+     * v0.14 strict: address 字段不再支持，identity = email。
+     * 保留方法名（向后兼容现有调用方），内部直接返回 email。
+     */
+    private getCurrentAddress;
+    /**
+     * 获取当前 instance 的 systemPrompt（Phase B.11+）
+     *
+     * 优先用 config.systemPrompt，否则用默认 prompt。
+     * 该 prompt 会透传到 EventSourceEvent.metadata.systemPrompt，
+     * 由 interactive.ts 在 dispatch env event 时注入到 agent system prompt。
+     */
+    private getCurrentSystemPrompt;
+    getStatus(): EventSourceStatus;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onEvent(handler: EventSourceEventHandler): void;
+    offEvent(): void;
+    private setStatus;
+    /**
+     * 发送 ACK 到 IM 服务器，标记 message 已处理。
+     *
+     * Task #2136：self-echo filter + wrong-address filter 在 skip 时也调用此 helper，
+     * 让 server 端把消息标记为 delivered / acked，避免 reconnect 时重复 push。
+     *
+     * 静默处理失败（仅 log error，不抛）——ACK 是 best-effort，主流程不能被 ACK 失败阻塞。
+     */
+    private sendAck;
+    private handleMessage;
+    private processLine;
+    private formatMessage;
+}
+export declare const bountyIMHandler: EventSourceHandler;

package/dist/env/event-source/event-source-component.d.ts

@@ -0,0 +1,177 @@
+/**
+ * EventSourceComponent - 基于 Handler 注册机制的重构版本
+ *
+ * 这个文件包含重构后的 EventSourceComponent 实现
+ * 使用 Handler 注册模式替代原来的 switch-case 硬编码
+ */
+import { BaseComponent, type ComponentConfig, type ComponentStatus } from "../component";
+import type { ConfigComponent } from "../../config/config-component";
+import type { EventSourceConfig, EventSourceStatus, EventSourceEventHandler, EventSourceHandler, EventSourceComponentInterface } from "./types";
+import { larkCliHandler, builtInHandlers } from "./event-source-handlers";
+/**
+ * EventSourceComponent 配置选项
+ */
+export interface EventSourceComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选） */
+    configPath?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<EventSourceConfigOptions>;
+    /** 是否自动注册内置 Handler（默认 true） */
+    registerBuiltInHandlers?: boolean;
+}
+/**
+ * EventSourceComponent.update() 的返回结果
+ */
+export interface EventSourceUpdateResult {
+    /** 事件源 ID */
+    id: string;
+    /** 更新后的完整配置 */
+    updated: EventSourceConfig;
+    /** 更新前是否处于 running 状态 */
+    wasRunning: boolean;
+    /** 是否实际调用了 stopSource */
+    stopped: boolean;
+    /** 是否自动重启（当前实现恒为 false，由用户手动 start 生效） */
+    restarted: boolean;
+    /** 本次更新的字段名列表 */
+    fields: string[];
+}
+/**
+ * EventSourceComponent 内部配置
+ */
+interface EventSourceConfigOptions {
+    enabled: boolean;
+    persistenceEnabled: boolean;
+    configPath: string;
+}
+/**
+ * EventSourceComponent
+ *
+ * 事件源组件，管理所有事件源的注册、配置和生命周期
+ *
+ * 使用 Handler 注册机制，支持动态扩展事件源类型
+ */
+export declare class EventSourceComponent extends BaseComponent implements EventSourceComponentInterface {
+    readonly name = "event-source";
+    readonly version = "1.0.0";
+    private sources;
+    private statuses;
+    private handlers;
+    private instances;
+    private eventHandlers;
+    private buffers;
+    private configPath;
+    private persistenceEnabled;
+    /** ConfigComponent 用于配置管理 */
+    private configComponent?;
+    /** 配置热更新 watcher 清理函数 */
+    private configWatcher?;
+    /**
+     * 初始化
+     */
+    protected onInit(): Promise<void>;
+    /**
+     * 公开的初始化方法
+     */
+    init(options?: ComponentConfig): Promise<void>;
+    protected onStart(): Promise<void>;
+    protected onStop(): Promise<void>;
+    /**
+     * 创建默认的事件处理器
+     *
+     * 当没有用户注册的 handler 时使用，将事件转发到 env.pushEnvEvent
+     */
+    private createDefaultEventHandler;
+    /**
+     * 注册内置 Handler
+     */
+    private registerBuiltInHandlers;
+    /**
+     * 执行初始化钩子
+     *
+     * 调用所有注册的 EventSourceInitHook，允许第三方扩展 Handler
+     */
+    private executeInitHooks;
+    /**
+     * 注册 Handler
+     */
+    registerHandler(handler: EventSourceHandler): void;
+    /**
+     * 注销 Handler
+     */
+    unregisterHandler(type: string): boolean;
+    /**
+     * 获取 Handler
+     */
+    getHandler(type: string): EventSourceHandler | undefined;
+    /**
+     * 列出所有 Handler
+     */
+    listHandlers(): EventSourceHandler[];
+    /**
+     * 注册配置到 ConfigComponent
+     */
+    private registerConfig;
+    private buildConfig;
+    private flattenConfig;
+    private registerConfigWatcher;
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    /**
+     * 注册事件源
+     */
+    register(config: EventSourceConfig): void;
+    /**
+     * 注销事件源
+     */
+    unregister(id: string): boolean;
+    /**
+     * 更新事件源
+     *
+     * 行为：
+     * - 只更新 partial 中明确出现的字段，其他字段保留
+     * - 如果事件源正在 running，先 stop（不自动重启）
+     * - 修改后调用 saveConfig() 持久化
+     * - 找不到 id 抛出明确错误
+     * - type 字段不允许修改
+     *
+     * @param id 事件源 ID
+     * @param partial 要更新的字段子集
+     * @returns 更新结果
+     */
+    update(id: string, partial: Partial<EventSourceConfig>): Promise<EventSourceUpdateResult>;
+    get(id: string): EventSourceConfig | undefined;
+    list(): EventSourceConfig[];
+    /**
+     * 获取事件源状态
+     *
+     * Overload 1: 无参 → 返回组件级状态（继承自 BaseComponent.getStatus）
+     * Overload 2: 带 id → 返回指定事件源状态
+     */
+    getStatus(): ComponentStatus;
+    getStatus(id: string): EventSourceStatus | undefined;
+    /**
+     * 获取事件源状态（别名，兼容旧 API）
+     * @deprecated 使用 getStatus(id) 代替
+     */
+    getEventSourceStatus(id: string): EventSourceStatus | undefined;
+    onEvent(id: string, handler: EventSourceEventHandler): void;
+    offEvent(id: string): void;
+    /**
+     * 启动事件源
+     */
+    startSource(id: string): Promise<void>;
+    /**
+     * 停止事件源
+     */
+    stopSource(id: string): Promise<void>;
+    private getConfigFilePath;
+    saveConfig(): Promise<void>;
+    loadConfig(): Promise<void>;
+}
+export { builtInHandlers, larkCliHandler, };

package/dist/env/event-source/event-source-config-registration.d.ts

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