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

package/dist/env/session-tree-stopper.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview SessionTreeStopper — single-entry orchestrator for ESC cascade
+ * stop across the entire session tree (Task #2245).
+ *
+ * When the user presses ESC in the REPL, `handleEscKey()` previously only
+ * aborted the top-level LLM stream + the top-level agent stream. This left
+ * BackgroundTaskManager-spawned sub-sessions, workflow runs (including those
+ * started directly by the main session), and agentNode-nested delegates
+ * running as orphans.
+ *
+ * `cascadeStopSessionTree(env, parentSessionId, { force })` is the single
+ * entry point that:
+ *   1. Calls BackgroundTaskManager.stopAllForParent(parentSessionId) —
+ *      stops every background task whose parent matches, including their
+ *      attached workflow runs (Task #2144 propagation).
+ *   2. Calls WorkflowService.stopAllForParent(parentSessionId) — stops every
+ *      workflow session whose parent matches via engine.stop().
+ *   3. (force=true only) Calls task.forceStopAll() and
+ *      workflow.forceStopAll() — traverses ALL entries (regardless of parent)
+ *      to nuke any orphan that graceful path missed.
+ *
+ * Errors from individual stages are caught and accumulated in `result.errors`
+ * so a partial-failure does not block other stages.
+ *
+ * @module session-tree-stopper
+ */
+export interface CascadeStopOptions {
+    /**
+     * If true, also invoke force-stop variants (`forceStopAll()`) which
+     * traverse ALL entries (regardless of parent) to kill residual orphans.
+     * Set on second ESC press within 2 seconds.
+     */
+    force?: boolean;
+}
+export interface CascadeStopResult {
+    /** Background task ids stopped via BackgroundTaskManager.stopAllForParent */
+    stoppedTaskIds: string[];
+    /** Workflow session ids stopped via WorkflowService.stopAllForParent */
+    stoppedWorkflowSessionIds: string[];
+    /** Echo of the requested force flag */
+    force: boolean;
+    /** Per-stage error info for partial-failure visibility */
+    errors: Array<{
+        stage: CascadeStage;
+        error: string;
+        stack?: string;
+    }>;
+}
+/**
+ * P1-#9: Type-safe enum of cascade stop stages. Use this union instead of
+ * raw strings when calling or matching against `result.errors[].stage`.
+ */
+export type CascadeStage = "task.stopAllForParent" | "task.forceStopAll" | "workflow.stopAllForParent" | "workflow.forceStopAll";
+/**
+ * Internal (untraced) implementation. The exported `cascadeStopSessionTree`
+ * below wraps this with `wrapFunction("session.tree.cascadeStop", ...)` so
+ * the span_name is stable for cli-e2e-test verification.
+ *
+ * P1-#6: reentrancy guard — concurrent calls with the same
+ * `(parentSessionId, force)` key coalesce to a single in-flight Promise.
+ * Different keys run independently.
+ */
+declare function cascadeStopSessionTreeImpl(env: {
+    getComponent: (name: string) => any;
+} | undefined | null, parentSessionId: string, opts?: CascadeStopOptions): Promise<CascadeStopResult>;
+/**
+ * Cascade stop the entire session tree rooted at `parentSessionId`.
+ *
+ * @param env - BaseEnvironment-like object exposing `getComponent(name)`.
+ *              Reads `task.backgroundTaskManager` and
+ *              `workflow.workflowService` if available; missing components are
+ *              silently skipped (no error thrown).
+ * @param parentSessionId - The session id whose tree should be stopped
+ *              (typically the main REPL session id).
+ * @param opts - `{ force: false }` by default; `{ force: true }` invokes
+ *              force-stop variants in addition to graceful stop.
+ */
+export declare const cascadeStopSessionTree: typeof cascadeStopSessionTreeImpl;
+export {};

package/dist/env/skill/config.d.ts

@@ -0,0 +1,13 @@
+import { type SkillConfig } from "./types";
+/**
+ * 默认配置
+ */
+export declare const DEFAULT_SKILL_CONFIG: SkillConfig;
+/**
+ * 优先级映射（后面的优先级更高）
+ */
+export declare const SOURCE_PRIORITY: Record<string, number>;
+/**
+ * 获取来源优先级
+ */
+export declare function getSourcePriority(source: string): number;

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

@@ -0,0 +1,6 @@
+export { SkillComponent } from "./skill-component";
+export * from "./types";
+export * from "./config";
+export * from "./parser";
+export * from "./scanner";
+export * from "./tool";

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

@@ -0,0 +1,9 @@
+import type { SkillEntry, SkillSource } from "./types";
+/**
+ * 解析 frontmatter 文本
+ */
+export declare function parseFrontmatter(text: string): Record<string, string>;
+/**
+ * 解析 SKILL.md 文件
+ */
+export declare function parseSkillFile(filePath: string, source: SkillSource): Promise<SkillEntry | null>;

package/dist/env/skill/scanner.d.ts

@@ -0,0 +1,25 @@
+import type { SkillConfig, SkillEntry } from "./types";
+/**
+ * Skill 扫描器
+ */
+export declare class SkillScanner {
+    private config;
+    private skillsMap;
+    constructor(config: SkillConfig);
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    scan(): Promise<Map<string, SkillEntry>>;
+    /**
+     * 扫描单个路径
+     */
+    private scanPath;
+    /**
+     * 处理单个 SKILL.md 文件
+     */
+    private processFile;
+    /**
+     * 获取扫描结果
+     */
+    getSkills(): Map<string, SkillEntry>;
+}

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

@@ -0,0 +1,89 @@
+import { BaseComponent, type ComponentConfig } from "../component";
+import type { SkillConfig, SkillEntry, SkillListItem } from "./types";
+import type { ConfigComponent } from "../../config/config-component";
+/**
+ * SkillComponent 配置选项（通过 options 传递）
+ *
+ * 配置加载顺序（优先级从低到高）：
+ * 1. File - 配置文件（通过 configPath 指定）
+ * 2. Env - 环境变量（通过 envPrefix 配置前缀）
+ * 3. Object - 直接传入的 config 对象（最高优先级）
+ */
+export interface SkillComponentOptions {
+    /** ConfigComponent 实例（必填） */
+    configComponent: ConfigComponent;
+    /** 配置文件相对路径（可选，基于 XDG_DATA_HOME） */
+    configPath?: string;
+    /** 环境变量前缀（可选，默认 "SKILL"） */
+    envPrefix?: string;
+    /** 直接传入的配置对象（可选，优先级最高） */
+    config?: Partial<SkillConfig>;
+}
+export declare class SkillComponent extends BaseComponent {
+    name: string;
+    version: string;
+    private config;
+    private toolComponent?;
+    private scanner;
+    private skillsMap;
+    private configComponent?;
+    private configWatcher?;
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * 注册配置到 ConfigComponent
+     *
+     * 配置加载顺序（优先级从低到高）：
+     * 1. Defaults - 默认值（最低）
+     * 2. FileSource - 从配置文件加载
+     * 3. EnvSource - 从环境变量加载
+     * 4. config 对象 - 直接传入的配置（最高）
+     */
+    private registerConfig;
+    /**
+     * 构建最终配置对象
+     */
+    private buildConfig;
+    /**
+     * 将配置对象展平为点号路径
+     */
+    private flattenConfig;
+    /**
+     * 注册配置热更新监听
+     */
+    private registerConfigWatcher;
+    /**
+     * 处理配置变更
+     */
+    protected onConfigChange(event: {
+        key: string;
+        oldValue?: unknown;
+        newValue?: unknown;
+    }): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * 获取指定 skill
+     */
+    getSkill(name: string): SkillEntry | undefined;
+    /**
+     * 获取所有 skill 列表（用于 tool description）
+     */
+    getSkillList(): SkillListItem[];
+    /**
+     * 检查 skill 是否存在
+     */
+    hasSkill(name: string): boolean;
+    /**
+     * 获取所有 skills
+     */
+    getAllSkills(): SkillEntry[];
+    /**
+     * 扫描所有 skillPaths 并加载 skills
+     */
+    scanSkills(): Promise<void>;
+    /**
+     * 重新扫描并更新 Tool
+     */
+    reload(): Promise<void>;
+    private registerTool;
+}

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

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

package/dist/env/skill/tool/index.d.ts

@@ -0,0 +1 @@
+export { createSkillTool, buildSkillDescription } from "./skill-tool";

package/dist/env/skill/tool/skill-tool.d.ts

@@ -0,0 +1,15 @@
+import type { Tool } from "../../tool/types";
+import { type SkillListItem } from "../types";
+/**
+ * 构建 SkillTool 的 description
+ */
+export declare function buildSkillDescription(items: SkillListItem[]): string;
+/**
+ * 创建 SkillTool
+ *
+ * @param getSkillList - 获取 skill 列表的回调
+ * @param getSkill - 获取单个 skill 的回调
+ */
+export declare function createSkillTool(getSkillList: () => SkillListItem[], getSkill: (name: string) => {
+    content: string;
+} | undefined): Tool;

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

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * Skill 来源类型
+ */
+export type SkillSource = "built-in" | "user" | "project";
+/**
+ * Skill 条目
+ */
+export interface SkillEntry {
+    /** Skill 名称（唯一标识） */
+    name: string;
+    /** Skill 描述 */
+    description: string;
+    /** SKILL.md 文件路径 */
+    filePath: string;
+    /** 完整 markdown 内容 */
+    content: string;
+    /** 来源类型 */
+    source: SkillSource;
+    /** 加载时间戳 */
+    loadedAt: number;
+}
+/**
+ * Skill 列表项（用于 list 和 description）
+ */
+export interface SkillListItem {
+    name: string;
+    description: string;
+    source: SkillSource;
+}
+/**
+ * Skill 路径配置
+ */
+export interface SkillPath {
+    /** 来源类型 */
+    type: SkillSource;
+    /** 绝对路径 */
+    path: string;
+}
+/**
+ * SkillComponent 配置
+ */
+export interface SkillConfig {
+    /** 多路径配置 */
+    skillPaths: SkillPath[];
+    /** 是否递归扫描子目录 */
+    recursive: boolean;
+    /** 是否启用缓存 */
+    cacheEnabled: boolean;
+}
+/**
+ * SkillTool 参数 Schema
+ */
+export declare const SkillToolSchema: z.ZodObject<{
+    skill: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    skill: string;
+}, {
+    skill: string;
+}>;
+export type SkillToolParams = z.infer<typeof SkillToolSchema>;

package/dist/env/task/backend/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Task Backend — roy 语义的单一实现点
+ *
+ * Task #4380（架构 review #4371 §8.1「把 roy 语义从 roy-bridge 上移到
+ * roy-agent-core」的落地）。
+ *
+ * ```ts
+ * import {
+ *   TaskStoreBackend,
+ *   createSQLiteTaskPort,
+ *   type TaskBackend,
+ *   type TaskPersistencePort,
+ * } from "@ai-setting/roy-agent-core/env/task/backend";
+ * ```
+ *
+ * - `TaskStoreBackend` — 全部 roy 语义（子树 / depth / deliverable /
+ *   create-operation / total / milestone 过滤 / 词汇单一来源）
+ * - `TaskPersistencePort` — 纯存取原语，任何 agent 插件实现它即可获得全部语义
+ * - `createSQLiteTaskPort` — roy 自己 `SQLiteTaskStore` 的现成 port 实现
+ */
+export * from "./types";
+export { TaskStoreBackend, DELIVERABLE_OPERATION_PREFIX, formatDeliverableForOperation, mergeDeliverableIntoContext, allowedIdsByDepth, toNumericHandle, } from "./task-store-backend";
+export { createSQLiteTaskPort } from "./sqlite-task-port";
+export { createRoySidecarTaskPort, type RoySidecarTaskStore, type RoySidecarPortOptions, type SidecarOperation, type SidecarTask, type SidecarVocabulary, } from "./roy-sidecar-task-port";