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

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/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;