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

package/dist/env/workflow/tools/workflow-search-tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Workflow Search Tool (v2)
+ *
+ * Search workflows by keyword + multi-tag AND filter.
+ * Returns available_tags so the caller knows what tags exist.
+ */
+import { z } from "zod";
+import type { Tool } from "../../tool/types";
+import type { WorkflowService } from "../service/workflow-service";
+/**
+ * Input schema for workflow_search tool
+ */
+export declare const WorkflowSearchInputSchema: z.ZodObject<{
+    keyword: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    tags?: string[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    keyword?: string | undefined;
+}, {
+    tags?: string[] | undefined;
+    limit?: number | undefined;
+    offset?: number | undefined;
+    keyword?: string | undefined;
+}>;
+export type WorkflowSearchInput = z.infer<typeof WorkflowSearchInputSchema>;
+/**
+ * Create a workflow_search tool with the given WorkflowService
+ */
+export declare function createWorkflowSearchTool(workflowService: WorkflowService): Tool;

package/dist/env/workflow/tools/workflow-tag-list-tool.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Workflow Tag List Tool (v3)
+ *
+ * MCP tool for listing all existing workflow tags from the workflow_tags table.
+ *
+ * Design goal: Let agents discover the existing tag pool BEFORE calling
+ * `workflow_add`, so they can:
+ *   1. Reuse existing tags for semantic consistency
+ *   2. Avoid accidental fragmentation (many near-duplicate tags)
+ *
+ * Strategy A (soft prompt): We do NOT hard-reject new tags. This tool only
+ * exposes what's already in the pool. The agent decides whether to reuse or
+ * create new tags, guided by the soft prompt in `workflow_add` description.
+ *
+ * Sort options:
+ *   - usage_count (default DESC) — most-used tags first
+ *   - name (default ASC) — alphabetical
+ *   - created_at (default DESC) — newest first
+ */
+import { z } from "zod";
+import type { Tool } from "../../tool/types";
+import type { WorkflowService } from "../service/workflow-service";
+/**
+ * Input schema for workflow_tag_list tool.
+ *
+ * All options have defaults so the agent can call with `{}` to get the
+ * default top-100 most-used tags.
+ */
+export declare const WorkflowTagListInputSchema: z.ZodObject<{
+    sort_by: z.ZodDefault<z.ZodEnum<["usage_count", "name", "created_at"]>>;
+    order: z.ZodDefault<z.ZodEnum<["asc", "desc"]>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    sort_by: "name" | "created_at" | "usage_count";
+    order: "asc" | "desc";
+    limit?: number | undefined;
+}, {
+    limit?: number | undefined;
+    sort_by?: "name" | "created_at" | "usage_count" | undefined;
+    order?: "asc" | "desc" | undefined;
+}>;
+export type WorkflowTagListInput = z.infer<typeof WorkflowTagListInputSchema>;
+/**
+ * Output structure returned to the agent.
+ */
+export interface WorkflowTagListOutput {
+    tags: Array<{
+        name: string;
+        usage_count: number;
+        created_at: string;
+        updated_at: string;
+    }>;
+    total: number;
+    hint: string;
+}
+/**
+ * Create a workflow_tag_list tool with the given WorkflowService.
+ */
+export declare function createWorkflowTagListTool(workflowService: WorkflowService): Tool;

package/dist/env/workflow/tools/workflow-validate-tool.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Workflow Validate Tool
+ *
+ * MCP tool for validating a workflow definition (YAML or JSON) without
+ * persisting it.
+ *
+ * Layer 1 — DAG structure (DAGManager.validate()):
+ *   - duplicate node IDs
+ *   - missing dependencies
+ *   - cycles
+ *   - empty node IDs
+ *
+ * Layer 2 — Template-reference **contracts** (Task #4298):
+ *   - does `{{nodes.X.<field>}}` match the output shape of node `X`?
+ *   - e.g. `.result` on a `tool` node is an ERROR (the tool's stored output has
+ *     no `result` field → the engine silently substitutes `''`), while `.output`
+ *     is correct. Also reports unknown fields on nodes with a closed output
+ *     contract (warning) and references to non-upstream nodes (info).
+ *
+ * Used by:
+ * 1. The built-in 'workflow-extract' agent — iterative generate→validate→fix loop
+ * 2. The built-in 'workflow-creator' agent — the same loop, driven by the
+ *    actionable `errors` / `warnings` this tool returns
+ * 3. task-tag-plugin — pre-flight check before workflowRepo.create() to avoid
+ *    polluting the database with invalid workflows extracted from chat history
+ *
+ * The tool does NOT require a WorkflowService — it only parses the YAML and
+ * runs the validator. The signature accepts WorkflowService for API consistency
+ * with other workflow tools (workflow_get, workflow_list, etc.) but ignores it.
+ */
+import { z } from "zod";
+import type { Tool } from "../../tool/types";
+import type { WorkflowService } from "../service/workflow-service";
+/**
+ * Input schema for workflow_validate tool.
+ *
+ * Accepts `file` (path), `yaml`/`definition_yaml` (string) or `definition`
+ * (object). Precedence: `definition` > `file` > `yaml` / `definition_yaml`.
+ *
+ * Task #4392 P0-4: `file` was added because the tool performs **no shell
+ * expansion**, yet LLMs kept passing `yaml: "$(cat /tmp/x.yaml)"`. That string
+ * is literal, YAML.parse returns a *string*, and the tool replied
+ * `Parsed definition is not an object` — 30 of the 31 measured validate
+ * failures in #4385 §2 C2.
+ */
+export declare const WorkflowValidateInputSchema: z.ZodObject<{
+    definition: z.ZodOptional<z.ZodAny>;
+    definition_yaml: z.ZodOptional<z.ZodString>;
+    yaml: z.ZodOptional<z.ZodString>;
+    file: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    file?: string | undefined;
+    definition?: any;
+    definition_yaml?: string | undefined;
+    yaml?: string | undefined;
+}, {
+    file?: string | undefined;
+    definition?: any;
+    definition_yaml?: string | undefined;
+    yaml?: string | undefined;
+}>;
+export type WorkflowValidateInput = z.infer<typeof WorkflowValidateInputSchema>;
+/**
+ * Create a workflow_validate tool with the given WorkflowService.
+ *
+ * Note: WorkflowService is required for API consistency with other workflow
+ * tools but is NOT used by this tool — validation is pure (no DB lookup).
+ */
+export declare function createWorkflowValidateTool(_workflowService: WorkflowService): Tool;

package/dist/env/workflow/types/context.d.ts

@@ -0,0 +1,17 @@
+/**
+ * askUser 选项
+ */
+export interface AskUserOptions {
+    options?: string[];
+    required_confirm?: boolean;
+}
+/**
+ * 从 Session 恢复的运行时状态
+ */
+export interface RuntimeState {
+    sessionId: string;
+    nodeOutputs: Map<string, unknown>;
+    pendingNodeId: string | null;
+    waitingForUser: boolean;
+    agentSessionId?: string;
+}

package/dist/env/workflow/types/decorators-types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @fileoverview Workflow Decorators - Type Definitions
+ *
+ * 定义 @Workflow、@NodeAs、@Edge 装饰器相关的类型
+ *
+ * 注意: RetryConfig 和 WorkflowConfig 已迁移到 ../types.ts
+ */
+export type { RetryConfig } from '../types';
+export { type WorkflowConfig } from '../types';
+/**
+ * @Workflow 装饰器选项
+ */
+export interface WorkflowOptions {
+    /** Workflow 名称 */
+    name: string;
+    /** 版本号，默认 "1.0" */
+    version?: string;
+    /** 描述 */
+    description?: string;
+    /** 入口节点 ID */
+    entry?: string | string[];
+    /** 全局配置 */
+    config?: {
+        parallel_limit?: number | null;
+        timeout?: number | null;
+        retry?: {
+            max_attempts: number;
+            backoff: 'fixed' | 'exponential';
+            initial_delay: number;
+        };
+        debug?: boolean;
+    };
+    /** 标签 */
+    tags?: string[];
+    /** 作者 */
+    author?: string;
+}
+/**
+ * @NodeAs 装饰器选项
+ */
+export interface NodeAsOptions {
+    /** 节点 ID，默认使用方法名 */
+    nodeId?: string;
+    /** 节点类型 */
+    nodeType?: 'tool' | 'skill' | 'agent' | 'workflow';
+    /** 显示名称 */
+    name?: string;
+    /** 依赖的节点 ID 列表 */
+    dependsOn?: string | string[];
+    /** 执行条件 */
+    condition?: string;
+    /** 重试配置 */
+    retry?: {
+        max_attempts: number;
+        backoff: 'fixed' | 'exponential';
+        initial_delay: number;
+    };
+    /** 超时时间（毫秒） */
+    timeout?: number;
+    /** 节点配置 */
+    config?: Record<string, unknown>;
+}
+/**
+ * @Edge 装饰器选项
+ */
+export interface EdgeOptions {
+    from: string;
+    to: string;
+    /** 条件表达式 */
+    condition?: string;
+}
+/**
+ * Workflow 元数据（存储在类的 Reflect Metadata 中）
+ */
+export interface WorkflowMetadata {
+    name: string;
+    version: string;
+    description?: string;
+    entry?: string | string[];
+    config?: {
+        parallel_limit?: number | null;
+        timeout?: number | null;
+        retry?: {
+            max_attempts: number;
+            backoff: 'fixed' | 'exponential';
+            initial_delay: number;
+        };
+        debug?: boolean;
+    };
+    tags?: string[];
+    author?: string;
+    /** 类实例引用 */
+    instance?: any;
+}
+/**
+ * Node 元数据（存储在类的 Reflect Metadata 中）
+ */
+export interface NodeMetadata {
+    nodeId: string;
+    nodeType: string;
+    name?: string;
+    dependsOn: string[];
+    condition?: string;
+    retry?: {
+        max_attempts: number;
+        backoff: 'fixed' | 'exponential';
+        initial_delay: number;
+    };
+    timeout?: number;
+    config: Record<string, unknown>;
+    methodName: string;
+    method: Function;
+}
+/**
+ * Edge 元数据（存储在类的 Reflect Metadata 中）
+ */
+export interface EdgeMetadata {
+    from: string;
+    to: string;
+    condition?: string;
+}
+/**
+ * Workflow 验证结果
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * 转换为 workflow 包中的 NodeDefinition
+ * 这是最终输出给 WorkflowEngine 使用的格式
+ */
+export interface ConvertedNodeDefinition {
+    id: string;
+    type: string;
+    name?: string;
+    config: Record<string, unknown>;
+    depends_on: string[];
+    condition?: string;
+    retry?: {
+        max_attempts: number;
+        backoff: 'fixed' | 'exponential';
+        initial_delay: number;
+    };
+    timeout?: number;
+}
+/**
+ * 转换为标准的 WorkflowDefinition
+ * 这是最终输出给 WorkflowEngine 使用的格式
+ */
+export interface ConvertedWorkflowDefinition {
+    name: string;
+    version: string;
+    description?: string;
+    config: {
+        parallel_limit?: number | null;
+        timeout?: number | null;
+        retry?: {
+            max_attempts: number;
+            backoff: 'fixed' | 'exponential';
+            initial_delay: number;
+        };
+        debug?: boolean;
+    };
+    nodes: ConvertedNodeDefinition[];
+    edges?: Array<{
+        from: string;
+        to: string;
+        when?: string;
+    }>;
+    entry: string | string[];
+    outputs: Array<{
+        name: string;
+        source: string;
+        path: string;
+    }>;
+    metadata: {
+        tags?: string[];
+        author?: string;
+    };
+}

package/dist/env/workflow/types/edge.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+/**
+ * Edge Definition Schema
+ * Represents a directed edge between two nodes with optional condition
+ */
+export declare const EdgeDefinitionSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+    when: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    from: string;
+    to: string;
+    when?: string | undefined;
+}, {
+    from: string;
+    to: string;
+    when?: string | undefined;
+}>;
+export type EdgeDefinition = z.infer<typeof EdgeDefinitionSchema>;
+/** Result of evaluating outgoing edges after a node completes */
+export interface EdgeProcessingResult {
+    /** Node IDs that should be started */
+    toStart: string[];
+    /** Node IDs re-entered from completed state (back-edges) */
+    reEntries: string[];
+    /** Nodes skipped due to false edge conditions */
+    skipped: Array<{
+        nodeId: string;
+        reason: string;
+    }>;
+    /** Nodes reset for re-entry (includes downstream cascade) */
+    resetNodes: string[];
+}