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

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

@@ -0,0 +1,145 @@
+/**
+ * @fileoverview Debug Component Types
+ *
+ * Type definitions for trace parsing, formatting, and debugging utilities.
+ */
+/**
+ * Trace action type
+ */
+export type TraceAction = 'enter' | 'quit' | 'error';
+/**
+ * Log level type
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Trace entry representing a single log line with trace info
+ */
+export interface TraceEntry {
+    /** Unique request/trace identifier */
+    traceId: string;
+    /** Timestamp of the entry (ISO format) */
+    timestamp: string;
+    /** Function/method name */
+    function: string;
+    /** Action type: enter, quit, or error */
+    action: TraceAction;
+    /** Parameters (for enter action) */
+    params?: unknown[];
+    /** Result (for quit action) */
+    result?: unknown;
+    /** Error message (for error action) */
+    error?: string;
+    /** Calculated duration in milliseconds (for quit action) */
+    durationMs?: number;
+    /** Span ID (for SQLite spans) */
+    spanId?: string;
+    /** Parent span ID (for SQLite spans) */
+    parentSpanId?: string;
+}
+/**
+ * Call tree node for hierarchical trace visualization
+ */
+export interface TraceTreeNode {
+    /** Unique request/trace identifier */
+    traceId: string;
+    /** Function/method name */
+    function: string;
+    /** Start timestamp */
+    startTime: string;
+    /** End timestamp (for completed nodes) */
+    endTime?: string;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Child nodes */
+    children: TraceTreeNode[];
+    /** Original trace entry (optional for programmatically created nodes) */
+    entry?: TraceEntry;
+    /** Span ID (for SQLite spans) */
+    spanId?: string;
+    /** Parent span ID (for SQLite spans) */
+    parentSpanId?: string;
+}
+/**
+ * Options for parsing logs
+ */
+export interface ParserOptions {
+    /** Log file path to read */
+    logFile?: string;
+    /** Filter by trace ID */
+    traceId?: string;
+    /** Filter by function name (supports partial match) */
+    function?: string;
+    /** Start time filter (ISO format or relative like "1h") */
+    since?: string;
+    /** End time filter (ISO format) */
+    until?: string;
+    /** Log level filter */
+    level?: LogLevel;
+}
+/**
+ * Options for log discovery
+ */
+export interface LogDiscoveryOptions {
+    /** Log directory to search */
+    logDir?: string;
+    /** File pattern to match */
+    pattern?: string;
+}
+/**
+ * Parsed log line with extracted fields
+ */
+export interface ParsedLogLine {
+    /** Original log line */
+    raw: string;
+    /** Timestamp extracted from log */
+    timestamp: string;
+    /** Log level (INFO, DEBUG, WARN, ERROR) */
+    level: string;
+    /** Source file/location */
+    source: string;
+    /** Category (traced:...) */
+    category: string;
+    /** Action symbol (>>> or <<< or !!!) */
+    action: string;
+    /** Method/function name */
+    method: string;
+    /** Action type (enter, quit, error) */
+    actionType: TraceAction;
+    /** Raw arguments string */
+    rawArgs: string;
+    /** Request ID extracted from log (if present) */
+    requestId: string | null;
+}
+/**
+ * Trace ID information summary
+ */
+export interface TraceIdInfo {
+    /** Trace ID */
+    traceId: string;
+    /** First occurrence timestamp */
+    firstTime: string;
+    /** Last occurrence timestamp */
+    lastTime?: string;
+    /** Number of entries for this trace */
+    count: number;
+}
+/**
+ * Output format options
+ */
+export interface FormatOptions {
+    /** Use pretty printing */
+    pretty?: boolean;
+    /** Maximum depth for recursive objects */
+    maxDepth?: number;
+    /** Include raw data */
+    includeRaw?: boolean;
+}
+/**
+ * Trace summary for list output
+ */
+export interface TraceSummary {
+    /** List of trace ID info */
+    traceIds: TraceIdInfo[];
+    /** Total count */
+    count: number;
+}

package/dist/env/environment.d.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview BaseEnvironment Implementation
+ *
+ * Environment 的基础实现类（非抽象），提供：
+ * - 组件注册与管理
+ * - 核心调度方法（handle_query, handle_action）
+ * - EnvEvent 事件机制
+ *
+ * 设计原则：
+ * 1. Environment 只做两件事：
+ *    - 组件管理：持有、注册、获取组件
+ *    - 核心调度：handle_query / handle_action / EnvEvent
+ * 2. 其他能力归属到对应 Component
+ *
+ * 子类可覆盖：
+ * - registerDefaultComponents(): 注册默认组件
+ * - handle_query(): 查询处理逻辑
+ * - handle_action(): 动作处理逻辑
+ * - onInit/onStart/onStop: 生命周期钩子
+ */
+import { BaseComponent, type Component } from "./component";
+import type { Environment, ServiceConfig, ComponentConfigEntry, GeneratedComponentOptions } from "./interface";
+import type { EnvironmentConfig, BaseEnvironmentConfig, EnvEvent, EnvEventInput, EnvEventHandler, Action, ToolResult, Context } from "./types";
+import type { AgentContext } from "./agent/types";
+import type { ContentPart } from "./llm/types";
+/**
+ * 默认 agent 名字（向后兼容）
+ */
+export declare const DEFAULT_AGENT_NAME = "Roy";
+/**
+ * 注入 {{agent_name}} 占位符
+ *
+ * - 若 prompt 不含占位符 → 原样返回（零开销）
+ * - 从 context.metadata.defaultAgentName 读取值
+ * - 缺失/null/undefined/空字符串 → 回退到 DEFAULT_AGENT_NAME
+ *
+ * 用 `global` 正则（/g）确保替换所有出现，避免残留占位符。
+ */
+export declare function injectAgentNamePlaceholder(prompt: string, context?: AgentContext): string;
+/**
+ * BaseEnvironment 实现类（非抽象）
+ *
+ * 实现 Environment 接口，提供简洁的环境基础功能。
+ * 子类可继承此类并覆盖特定方法来自定义行为。
+ */
+export declare class BaseEnvironment extends BaseComponent implements Environment {
+    readonly name: string;
+    readonly version: string;
+    protected components: Map<string, Component>;
+    /**
+     * 构造函数
+     */
+    constructor(config?: BaseEnvironmentConfig);
+    /**
+     * 注册默认组件（子类可覆盖）
+     */
+    protected registerDefaultComponents(): void;
+    /**
+     * 获取环境配置
+     */
+    getConfig(): EnvironmentConfig & {
+        env: Environment;
+    };
+    /**
+     * 注册组件
+     */
+    registerComponent(component: Component): void;
+    /**
+     * 注销组件
+     */
+    unregisterComponent(name: string): void;
+    /**
+     * 获取组件
+     */
+    getComponent<T extends Component>(name: string): T | undefined;
+    /**
+     * 列出所有组件
+     */
+    listComponents(): Component[];
+    /**
+     * 处理自然语言查询（核心入口）
+     *
+     * 委托给 AgentComponent.run() 处理
+     */
+    handle_query(query: string | ContentPart[], context?: AgentContext): Promise<string>;
+    /**
+     * ★ Workflow 类型 agent 查询处理
+     *
+     * 检查 agentDef.type 是否为 "workflow"，是则通过 WorkflowComponent 执行 workflow。
+     * 非 workflow 类型返回 null，让 handle_query 走原有 ReAct 路径。
+     */
+    private handleWorkflowAgentQuery;
+    /**
+     * 处理动作
+     *
+     * 默认实现抛出错误，子类必须实现。
+     */
+    handle_action(action: Action, context: Context): Promise<ToolResult>;
+    /**
+     * 事件订阅者映射
+     */
+    protected eventHandlers: Map<string, Set<EnvEventHandler>>;
+    /**
+     * 通配符订阅者（接收所有事件）
+     */
+    protected wildcardHandlers: Set<EnvEventHandler>;
+    /**
+     * 订阅 EnvEvent（返回取消订阅函数）
+     */
+    subscribe(handler: EnvEventHandler): () => void;
+    /**
+     * 订阅指定类型事件
+     */
+    subscribeTo(eventType: string | string[], handler: EnvEventHandler): () => void;
+    /**
+     * 订阅所有事件（通配符）
+     *
+     * 与 subscribe 相同，为保持 API 一致性
+     */
+    subscribeAll(handler: EnvEventHandler): () => void;
+    /**
+     * 推送事件
+     */
+    pushEnvEvent(event: EnvEvent | EnvEventInput): void;
+    /**
+     * 创建并推送事件（便捷方法）
+     */
+    protected emit<T = unknown>(type: string, payload: T, metadata?: Partial<EnvEvent["metadata"]>): void;
+    /**
+     * 初始化所有组件（分阶段初始化）
+     *
+     * 1. 第一阶段：初始化 ConfigComponent（如果存在）
+     * 2. 第二阶段：初始化其他组件
+     */
+    protected initializeComponents(): Promise<void>;
+    /**
+     * 启动所有组件
+     *
+     * 注意：由于 Environment.init() 会将组件状态设为 "running"，我们需要确保
+     * 即使组件已经是 "running" 状态，它们的 start() 方法仍然被调用。
+     * 这是因为 start() 负责注册工具等运行时资源。
+     */
+    protected startComponents(): Promise<void>;
+    /**
+     * 停止所有组件
+     */
+    protected stopComponents(): Promise<void>;
+    /**
+     * 初始化（可覆盖）
+     */
+    protected onInit(): Promise<void>;
+    /**
+     * 启动（可覆盖）
+     */
+    protected onStart(): Promise<void>;
+    /**
+     * 停止（可覆盖）
+     */
+    protected onStop(): Promise<void>;
+    /**
+     * BaseComponent 钩子
+     *
+     * Environment 特殊处理：它本身就是 env，所以不需要外部传入。
+     * 此方法覆盖 BaseComponent.init()，直接设置自引用。
+     */
+    init(): Promise<void>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 从配置文件加载服务配置
+     */
+    loadServiceConfig(configPath: string): Promise<ServiceConfig>;
+    /**
+     * 生成组件初始化选项
+     */
+    generateComponentOptions(componentName: string, configEntry: ComponentConfigEntry): GeneratedComponentOptions;
+    /**
+     * 注册组件并用配置初始化
+     */
+    registerComponentWithConfig(component: Component, configEntry: ComponentConfigEntry): Promise<void>;
+    /**
+     * 从配置文件初始化整个环境
+     */
+    initFromConfig(configPath: string): Promise<void>;
+}

package/dist/env/error-reply.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Task #4418: React 循环异常中断 → 给飞书发 reply
+ *
+ * ## 问题（用户飞书 p2p 2026-10-21）
+ *
+ * ```
+ * RetryError [AI_RetryError]: Failed after 4 attempts.
+ * Last error: Upstream request failed: Endpoint is unavailable.
+ * statusCode: 429 / isRetryable: true
+ * ```
+ *
+ * 上游 429 不是 roy-agent 的 bug；但**异常中断后飞书侧完全静默**是。
+ * 用户原话：「这个失败导致的 react 中断，也需要找到对应的 triggerEvent
+ * 构建 response 让飞书方知道（送一个 reply 哈）」。
+ *
+ * ## 为什么必须由框架直接发（不能靠 prompt 引导 agent）
+ *
+ * 正常路径的 reply 是 **LLM 自己调 lark-cli**（prompt 由
+ * `buildNotifyHandlePrompt` / event-source-handlers 生成，告诉 agent
+ * 用 `recommendedAction.replyTo` 回消息）。
+ *
+ * 但异常路径的根本问题是：**LLM 调用本身失败了**，React 循环从未拿到
+ * 一个可用的 assistant turn，自然也不可能再调工具发消息。所以框架必须
+ * 自己 spawn `lark-cli`，这是与正常路径的本质区别。
+ *
+ * ## 断点（为什么曾经没 reply）
+ *
+ * 1. `agent-component.ts:2096` 捕获异常 → `result.error` + `result.originalError`
+ * 2. `environment.ts:430` 非 ContextError → `throw new Error(result.error)`
+ *    ⚠️ 类型在这里丢掉，下游只能拿到字符串
+ * 3. `context-handler.service.ts:224` 直接 rethrow
+ * 4. `query-executor.ts:287` 只处理 ContextError，其余 rethrow
+ * 5. `interactive.ts:1301` / `event-handler.ts:620` 的 catch **只 console.error**
+ *    → 静默丢失
+ *
+ * ## 现在的接线（四处，去重保证不重复）
+ *
+ * 1. `QueryExecutor.execute` 的 catch —— 唯一执行入口，覆盖
+ *    interactive / run / run --es 三种模式，带完整 `agentContext.envEvent`
+ * 2. `EventHandler.processQueue` 的 catch —— 兜住「还没走到 QueryExecutor
+ *    就失败」的路径（session 解析 / 事件分发），并作为 TUI 层吞异常时的
+ *    最后一道防线
+ * 3. REPL `executeInternal` 的 catch —— 兜住 agentContext 组装 / plugin
+ *    加载 / REPL 包装层（这些异常会被 REPL 自己吞掉，到不了 EventHandler）
+ * 4. `LarkCliInstance.handleEvent` 的 catch —— event-source 自身的解析 /
+ *    落库 / 分发失败
+ *
+ * 四处都调用本模块，意味着**任何 React 中断都至少有一个出口到飞书**。
+ *
+ * ## 设计原则
+ *
+ * - **规则表驱动（rule base）**：错误分类 + 是否通知 + 用户文案收敛成
+ *   `FAILURE_RULES` 有序表；表尾 `UNKNOWN_RULE` 是 `notify: true` 的
+ *   catch-all —— 结构上保证**任何未分类错误也不会沉默**。只有
+ *   `ask_user`（正常交互）显式 `notify: false`
+ * - **best-effort**：任何异常（spawn 失败 / lark-cli 非 0 / 库挂了）
+ *   都不得向上抛，绝不污染原始错误传播链
+ * - **有硬超时**：兜底 reply 在 5s 内一定 settle（超时 kill 子进程）。
+ *   否则 lark-cli 卡住会把 `QueryExecutor` 的 rethrow 拖死 → 事件队列堵死
+ * - **复用现有机制**：spawn 参数形态与 `LarkCliNotificationChannel` /
+ *   `event-source-handlers.sendLarkMessage` 保持一致（`--profile` 前置、
+ *   messageId → `+messages-reply`、chatId → `+messages-send`）
+ * - **去重**：同一 triggerEvent（messageId）只回一次；chat-only 通道走
+ *   5 分钟窗口，**不会**把整个群永久封锁；发送失败回滚去重标记
+ * - **无 channel 不崩但也不静默**：本地 REPL / `act` 没有飞书上下文 → debug；
+ *   有 triggerEvent 却拿不到 replyChannel = 衔接 bug → warn
+ * - **用户可读**：给用户看中文原因，技术细节单独放 `technical` 字段（截断）
+ */
+/**
+ * 失败分类。
+ *
+ * 顺序即优先级：越具体的越先匹配。
+ */
+export type ReactFailureKind = "ask_user" | "upstream_retry" | "timeout" | "upstream_aborted" | "aborted" | "context_overflow" | "unknown";
+export interface ReactFailureInfo {
+    kind: ReactFailureKind;
+    /** 命中的规则 id（可观测性 / 测试锚点） */
+    ruleId: string;
+    /** 一行标题（中文，给用户看） */
+    title: string;
+    /** 可读原因（中文，不含 stack trace） */
+    reason: string;
+    /** 是否值得用户稍后重试 */
+    retryable: boolean;
+    /**
+     * 是否应该把这条失败反馈到飞书。
+     *
+     * 只有 `ask_user`（正常交互）为 false —— **所有真正的失败/中断都必须通知**，
+     * 这是 #4418 的硬契约：不允许静默。
+     */
+    notify: boolean;
+    /** 技术细节（截断，供定位；不直接展示给用户） */
+    technical?: string;
+}
+/** replyChannel 的最小形态（同时兼容 EnvReplyChannel / event-source ReplyChannel） */
+export interface FailureReplyChannelLike {
+    type?: string;
+    chatId?: string;
+    messageId?: string;
+    profile?: string;
+    appId?: string;
+    userId?: string;
+}
+export interface NotifyReactFailureOptions {
+    /** 触发 React 中断的错误（任意类型，内部会做类型安全处理） */
+    error: unknown;
+    /**
+     * 触发本次执行的 EnvEvent。
+     *
+     * 从中提取 replyChannel（优先 `metadata.replyChannel`，
+     * 兼容 `payload.replyChannel`），这就是用户说的「找到对应的 triggerEvent」。
+     */
+    envEvent?: unknown;
+    /** 显式 replyChannel（优先级最高，便于调用方直接指定） */
+    replyChannel?: FailureReplyChannelLike;
+    /** 原始 query 摘要（会被截断后放进 reply，便于用户对上号） */
+    query?: string;
+    /** 会话 ID（仅用于日志 / 去重兜底） */
+    sessionId?: string;
+    /** 去重 key 覆盖（默认从 messageId/chatId 推导） */
+    dedupKey?: string;
+    /**
+     * 兜底 reply 的硬超时（ms）。
+     *
+     * 生产默认 5s；仅测试注入短值用。超时后 kill 子进程并按失败返回，
+     * 保证 `QueryExecutor` 的 catch 不会被 lark-cli 挂住。
+     */
+    replyTimeoutMs?: number;
+}
+export interface NotifyReactFailureResult {
+    /** 是否成功投递到飞书 */
+    sent: boolean;
+    /** 失败分类（即使没发送也会返回，调用方可记日志） */
+    kind: ReactFailureKind;
+    /** 结构化失败信息 */
+    info: ReactFailureInfo;
+    /** 跳过原因（sent=false 时有值） */
+    skipped?: "no_channel" | "duplicate" | "not_a_failure";
+    /** 投递错误（sent=false 且确实尝试过时有值） */
+    error?: string;
+}
+/** 当前生效的规则 id 列表（供可观测性 / 文档 / 测试锚定顺序）。 */
+export declare function getFailureRuleIds(): string[];
+/**
+ * 把任意错误分类成结构化、用户可读的失败信息。
+ *
+ * ⚠️ 关键：必须能处理**类型已丢失**的场景 —— 真实调用链上
+ * `environment.ts` 会把 RetryError 字符串化成普通 `Error`，所以只能靠
+ * message 文本特征识别，不能依赖 `instanceof RetryError`。
+ */
+export declare function classifyReactFailure(error: unknown): ReactFailureInfo;
+/**
+ * 生成发给用户的 reply 正文（Markdown）。
+ *
+ * 契约：
+ * - 不含裸 stack trace（`    at `）
+ * - 含「怎么办」的可操作建议
+ * - 总长度远小于飞书 4096 单条上限
+ */
+export declare function buildFailureReplyMarkdown(info: ReactFailureInfo, opts?: {
+    query?: string;
+    sessionId?: string;
+}): string;
+/** 测试用：清空去重状态 */
+export declare function __resetFailureReplyDedupForTest(): void;
+/**
+ * React 循环异常中断时，尽最大努力给飞书发一条失败说明。
+ *
+ * **绝不抛异常** —— 所有错误都被吞掉并记日志，保证不污染原始错误传播。
+ *
+ * @example
+ * ```ts
+ * // interactive.ts executeInternal 的 catch 分支
+ * } catch (error) {
+ *   await notifyReactFailure({
+ *     error,
+ *     envEvent: this.currentAgentContext?.envEvent,
+ *     sessionId: agentContext?.eventSessionId,
+ *   });
+ *   // …原有错误处理继续
+ * }
+ * ```
+ */
+export declare function notifyReactFailure(options: NotifyReactFailureOptions): Promise<NotifyReactFailureResult>;

package/dist/env/errors.d.ts

@@ -0,0 +1,120 @@
+/**
+ * @fileoverview 统一错误类型体系
+ *
+ * 提供 AgentError, ToolError, LLMError, ComponentError, ContextError 等错误类型
+ * 每个错误包含 code（错误码）和 details（额外信息）
+ */
+/**
+ * 错误码枚举
+ */
+export declare const ErrorCodes: {
+    readonly AGENT_NOT_FOUND: "AGENT_001";
+    readonly AGENT_RUN_FAILED: "AGENT_002";
+    readonly AGENT_TIMEOUT: "AGENT_003";
+    readonly AGENT_CONFIG_INVALID: "AGENT_004";
+    readonly TOOL_NOT_FOUND: "TOOL_001";
+    readonly TOOL_DISABLED: "TOOL_002";
+    readonly TOOL_EXECUTION_FAILED: "TOOL_003";
+    readonly TOOL_VALIDATION_FAILED: "TOOL_004";
+    readonly LLM_PROVIDER_NOT_FOUND: "LLM_001";
+    readonly LLM_INVOCATION_FAILED: "LLM_002";
+    readonly LLM_TIMEOUT: "LLM_003";
+    readonly LLM_CONFIG_INVALID: "LLM_004";
+    readonly COMPONENT_NOT_FOUND: "COMP_001";
+    readonly COMPONENT_INIT_FAILED: "COMP_002";
+    readonly COMPONENT_NOT_RUNNING: "COMP_003";
+    readonly CONFIG_NOT_FOUND: "CONFIG_001";
+    readonly CONFIG_INVALID: "CONFIG_002";
+    readonly CONFIG_SOURCE_ERROR: "CONFIG_003";
+    readonly CONTEXT_THRESHOLD_EXCEEDED: "CTX_001";
+    readonly CONTEXT_COMPACTION_FAILED: "CTX_002";
+    readonly MCP_INIT_FAILED: "MCP_001";
+    readonly MCP_SERVER_ERROR: "MCP_002";
+    readonly MCP_TOOL_ERROR: "MCP_003";
+};
+export type ErrorCode = typeof ErrorCodes[keyof typeof ErrorCodes];
+/**
+ * RoyError 基类
+ */
+export declare class RoyError extends Error {
+    readonly code: ErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: ErrorCode, details?: unknown | undefined);
+}
+/**
+ * Agent 相关错误
+ */
+export declare class AgentError extends RoyError {
+    constructor(message: string, code?: ErrorCode, details?: unknown);
+}
+/**
+ * Tool 相关错误
+ */
+export declare class ToolError extends RoyError {
+    readonly toolName?: string | undefined;
+    constructor(message: string, code?: ErrorCode, toolName?: string | undefined, details?: unknown);
+}
+/**
+ * LLM 相关错误
+ */
+export declare class LLMError extends RoyError {
+    readonly provider?: string | undefined;
+    constructor(message: string, code?: ErrorCode, provider?: string | undefined, details?: unknown);
+}
+/**
+ * Component 相关错误
+ */
+export declare class ComponentError extends RoyError {
+    readonly componentName?: string | undefined;
+    constructor(message: string, code?: ErrorCode, componentName?: string | undefined, details?: unknown);
+}
+/**
+ * LLM Output 结构（用于 ContextError 携带 assistant message）
+ *
+ * 这是简化版本，仅包含保存到 session 所需的最少字段。
+ * 与 llm/types.ts 中的 LLMOutput 不同，那个版本包含完整的 LLM 调用结果。
+ */
+export interface LLMOutput {
+    content?: string;
+    reasoning?: string;
+    toolCalls?: Array<{
+        id: string;
+        function?: {
+            name: string;
+            arguments: string;
+        };
+        name?: string;
+        arguments?: unknown;
+    }>;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/**
+ * Context 相关错误
+ */
+export declare class ContextError extends RoyError {
+    readonly sessionId?: string | undefined;
+    readonly usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | undefined;
+    readonly contextWindow?: number | undefined;
+    readonly llmOutput?: LLMOutput | undefined;
+    constructor(message: string, code?: ErrorCode, sessionId?: string | undefined, usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    } | undefined, contextWindow?: number | undefined, llmOutput?: LLMOutput | undefined, details?: unknown);
+}
+/**
+ * 检查是否是 RoyError
+ */
+export declare function isRoyError(error: unknown): error is RoyError;
+/**
+ * 获取错误码
+ */
+export declare function getErrorCode(error: unknown): ErrorCode | undefined;

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

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview BountyCli EventSource Handler
+ *
+ * Built-in handler for `bounty-cli` event source. Spawns the
+ * `@ai-setting/bounty-cli` Go binary (a `lark-cli`-style Mattermost
+ * event-source CLI) and forwards its NDJSON event stream into the
+ * roy-agent event bus.
+ *
+ * ## Wire format
+ *
+ * `bounty event consume --channel <name>` emits one JSON object per line
+ * (NDJSON). Each object is a bounty Event struct:
+ *
+ *   {
+ *     "event_id": "...",
+ *     "event_type": "mm.message.posted",
+ *     "source_time": "...",
+ *     "app_id": "...",
+ *     "tenant_key": "...",
+ *     "payload": { ... MM post data ... },
+ *     "timestamp": "2026-..."
+ *   }
+ *
+ * Status messages are written to stderr (not stdout).
+ *
+ * ## Configuration
+ *
+ * EventSourceConfig requires:
+ * - `channel` (top-level): Mattermost channel name (positional arg)
+ * - `profile` (optional): bounty profile name (multi-account scenario, #1637)
+ *
+ * Optional:
+ * - `command` (top-level): override the default command line (advanced)
+ *
+ * ## Reply channel
+ *
+ * The reply channel uses `type: "bounty-cli"` so that
+ * `BountyCliNotificationChannel` (packages/core/src/env/plugin) picks up
+ * notification sends and routes them to `bounty event publish`.
+ */
+import type { EventSourceHandler } from "./types";
+export declare const bountyCliHandler: EventSourceHandler;