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

package/dist/env/workflow/utils/build-agent-node-output.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Build AgentNode execution output, flattening JSON fields for template access.
+ *
+ * When output.mode=json, the structured JSON is extracted from agentResult.structuredOutput
+ * (populated by workflow-json-output-plugin via json-extract sub-agent tool call).
+ * Individual JSON fields are spread so downstream nodes can reference them directly:
+ *   {{nodes.foo.output.field}} rather than {{nodes.foo.output.result.field}}
+ */
+import type { AgentResult } from '../nodes/agent-node';
+import type { AgentOutputConfig } from './parse-agent-output-config';
+export declare function buildAgentNodeOutput(agentResult: AgentResult, outputConfig: AgentOutputConfig): Record<string, unknown>;

package/dist/env/workflow/utils/create-workflow.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 便捷函数：createWorkflowFromClass
+ */
+import type { ConvertedWorkflowDefinition } from '../types/decorators-types';
+/**
+ * 从装饰器类创建 WorkflowDefinition
+ *
+ * 这是最常用的便捷函数，自动处理实例创建和转换
+ *
+ * @param targetClass - 使用 @Workflow 装饰的类
+ * @param options - 可选配置
+ * @returns WorkflowDefinition
+ *
+ * @example
+ * ```typescript
+ * @Workflow({ name: 'my-workflow', entry: 'start' })
+ * class MyWorkflow {
+ *   @NodeAs({ nodeId: 'start' })
+ *   async start() { return { done: true }; }
+ * }
+ *
+ * // 方式一：自动创建实例
+ * const workflow = createWorkflowFromClass(MyWorkflow);
+ *
+ * // 方式二：传入自定义实例
+ * const myInstance = new MyWorkflow(customDep);
+ * const workflow = createWorkflowFromClass(MyWorkflow, { instance: myInstance });
+ * ```
+ */
+export declare function createWorkflowFromClass(targetClass: new (...args: any[]) => any, options?: {
+    /** 自定义实例，不传则自动创建 */
+    instance?: any;
+    /** 构造函数参数 */
+    constructorArgs?: any[];
+}): ConvertedWorkflowDefinition;

package/dist/env/workflow/utils/dependency-prescan.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Workflow 依赖前置检查 (Step 6.0.5 of roy-rd-with-trace v1.3.0)
+ *
+ * 在 cli-e2e-test 节点的 build/test/cli_smoke/trace_check 之前，对任务涉及的
+ * workflow YAML 文件做 4 类静态依赖一致性检查：
+ *
+ *   1. checkDependsOnNodesExist       — depends_on 节点 ID 是否都存在
+ *   2. checkEdgesNodesExist           — edges from/to 节点 ID 是否都存在
+ *   3. checkEdgesDependsOnConsistency — edges 目标节点的 depends_on 是否包含 from (fan-out/fan-in 反模式)
+ *   4. checkEntryNodeExists           — entry 节点是否存在
+ *
+ * 任何一个 FAIL → cli_e2e_status = "FAIL"，fail-fast。
+ *
+ * Task #2241 — v1.3.0 新增（Plan: docs/superpowers/plans/2026-07-21-fix-workflow-parallel-deps-reverify-plan.md）
+ */
+import type { WorkflowDefinition } from '../types/workflow';
+/**
+ * A single finding from prescan.
+ */
+export interface PrescanFinding {
+    checkName: 'checkDependsOnNodesExist' | 'checkEdgesNodesExist' | 'checkEdgesDependsOnConsistency' | 'checkEntryNodeExists';
+    severity: 'FAIL' | 'WARN';
+    message: string;
+    nodeIds?: string[];
+}
+/**
+ * Aggregate result of prescan.
+ */
+export interface PrescanResult {
+    ok: boolean;
+    findings: PrescanFinding[];
+}
+declare function _prescanWorkflowImpl(workflow: WorkflowDefinition): PrescanResult;
+declare function _checkDependsOnNodesExistImpl(workflow: WorkflowDefinition, nodeIds: Set<string>): PrescanFinding[];
+declare function _checkEdgesNodesExistImpl(workflow: WorkflowDefinition, nodeIds: Set<string>): PrescanFinding[];
+declare function _checkEdgesDependsOnConsistencyImpl(workflow: WorkflowDefinition, _nodeIds: Set<string>): PrescanFinding[];
+declare function _checkEntryNodeExistsImpl(workflow: WorkflowDefinition, nodeIds: Set<string>): PrescanFinding[];
+/**
+ * Main entry: prescan a workflow definition object.
+ */
+export declare const prescanWorkflow: typeof _prescanWorkflowImpl;
+/**
+ * Check 1: every depends_on reference resolves to an existing node ID.
+ */
+export declare const checkDependsOnNodesExist: typeof _checkDependsOnNodesExistImpl;
+/**
+ * Check 2: every edge from/to resolves to an existing node ID.
+ */
+export declare const checkEdgesNodesExist: typeof _checkEdgesNodesExistImpl;
+/**
+ * Check 3: for every edge from → to, target node declares from in depends_on.
+ * This catches the fan-out/fan-in anti-pattern where edges trigger downstream
+ * but the downstream's depends_on declaration doesn't include the source.
+ */
+export declare const checkEdgesDependsOnConsistency: typeof _checkEdgesDependsOnConsistencyImpl;
+/**
+ * Check 4: the entry node must exist in the nodes list.
+ * (Only checked when entry is a string; arrays are skipped — array entry is
+ * considered advanced and not covered by this fail-fast rule.)
+ */
+export declare const checkEntryNodeExists: typeof _checkEntryNodeExistsImpl;
+/**
+ * Load a workflow YAML file from disk and run prescan.
+ * Convenience wrapper for Step 6.0.5 CLI invocation.
+ */
+export declare function prescanWorkflowFile(path: string): PrescanResult;
+export {};

package/dist/env/workflow/utils/execution-state.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Execution State Builder
+ *
+ * Builds execution state from session messages and workflow definition.
+ */
+import type { WorkflowDefinition } from '../types';
+import type { SessionMessage } from '../../session/types';
+import type { ExecutionState } from './validation-rules';
+/**
+ * Builder for constructing ExecutionState from session data
+ */
+export declare class ExecutionStateBuilder {
+    build(messages: SessionMessage[], definition: WorkflowDefinition): ExecutionState;
+    /**
+     * Parse session messages to extract node states and outputs
+     */
+    private parseMessages;
+    /**
+     * Build pending nodes from workflow definition
+     */
+    private buildPendingNodes;
+    /**
+     * Get entry nodes from workflow definition
+     */
+    private getEntryNodes;
+    /**
+     * Mark all nodes as pending starting from a given node
+     */
+    private markPendingFromNode;
+    /**
+     * Get direct children of a node
+     */
+    private getDirectChildren;
+    /**
+     * Extract input from a workflow.node.call message
+     */
+    private extractInput;
+    /**
+     * Extract output from a workflow.node.result message
+     */
+    private extractOutput;
+    /**
+     * Extract variables from node output and add to state
+     */
+    private extractVariables;
+}

package/dist/env/workflow/utils/extract-agent-json-output.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract structured JSON output from agent result (tool submission only).
+ */
+import type { AgentResult } from '../nodes/agent-node';
+import type { JsonSchemaObject } from './json-schema-to-zod';
+export declare function extractAgentJsonOutput(agentResult: AgentResult, schema?: JsonSchemaObject): Record<string, unknown> | undefined;

package/dist/env/workflow/utils/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Workflow Utilities
+ */
+export { TemplateResolver, resolveTemplates, resolveTemplateString } from './template-resolver';
+export type { TemplateResolverOptions, ResolvedValue } from './template-resolver';
+export { getFromMapWithNormalization } from './node-id-utils';
+export { validateWorkflowDefinition, type ValidateWorkflowResult, type ValidateWorkflowOptions, } from './validate-workflow-definition';
+export { validateTemplateContracts, getTemplateContractErrors, getTemplateContractWarnings, formatTemplateContractFindings, type TemplateContractFinding, type TemplateContractRule, type TemplateContractSeverity, } from './template-contract-validator';
+export { NODE_OUTPUT_CONTRACTS, VIRTUAL_OUTPUT_FIELD, RESULT_INVALID_NODE_TYPES, getNodeOutputContract, hasClosedOutputContract, getAgentDeclaredJsonFields, type NodeOutputContract, } from './node-output-contracts';
+export { RecoveryValidator } from './recovery-validator';
+export { ExecutionStateBuilder } from './execution-state';
+export { ValidationErrorType, SuggestedAction, } from './validation-rules';
+export type { ValidationError, ValidationResult, RecoveryPlan, ExecutionState, } from './validation-rules';
+export { sanitizeWorkflowDefinition, sanitizeShellScript, } from './workflow-sanitize';

package/dist/env/workflow/utils/json-schema-to-zod.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Minimal JSON Schema → Zod converter for workflow agent output schemas.
+ * Supports object types with boolean, string, number, and integer properties.
+ */
+import { z } from 'zod';
+export interface JsonSchemaObject {
+    type?: string;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+export interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+/**
+ * Validate workflow AgentNode output.schema at config parse time (YAML load path).
+ * Only supports the minimal JSON Schema subset used by jsonSchemaToZod.
+ */
+export declare function validateJsonOutputSchema(schema: unknown): JsonSchemaObject;
+export declare function jsonSchemaToZod(schema: JsonSchemaObject): z.ZodObject<z.ZodRawShape>;

package/dist/env/workflow/utils/node-id-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Node ID utility functions
+ *
+ * Provides shared utilities for node ID handling, including
+ * hyphen/underscore normalization for flexible node ID matching.
+ */
+/**
+ * Get a value from a Map with hyphen/underscore normalization.
+ *
+ * First tries exact match, then tries replacing hyphens with underscores,
+ * then tries replacing underscores with hyphens.
+ *
+ * This handles cases where workflow defines a node with underscore but
+ * a template uses hyphen, or vice versa.
+ *
+ * @param map - The Map to search in
+ * @param key - The key to look up
+ * @returns The value if found, undefined otherwise
+ */
+export declare function getFromMapWithNormalization<V>(map: Map<string, V>, key: string): V | undefined;

package/dist/env/workflow/utils/node-output-contracts.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Node output contracts — what a node's stored output looks like
+ * at runtime, expressed as the set of first-level fields that a downstream
+ * template (`{{nodes.<id>.<field>}}`) can legally navigate into.
+ *
+ * ## Why this exists (Task #4296 / #4298)
+ *
+ * A real incident: `wheels-validate-v1` v1.3.0 shipped a workflow whose final
+ * `report-results` (agent) node built its prompt from
+ * `{{nodes.run-validation-tests.result}}`. But `run-validation-tests` is a
+ * **tool** node, and the workflow engine stores `result.output` into
+ * `sessionState.nodeOutputs` (engine.ts `nodeOutputs.set(nodeId, result.output)`),
+ * i.e. the stored value is the tool's *output*, **never** a `{ result, ... }`
+ * envelope.
+ *
+ * Consequences of the mismatch (all silent):
+ *   - `template-resolver.navigateTokens()` does property access on a string → `undefined`
+ *   - `stringify(undefined)` → `''` (Task #2912 behavior)
+ *   - the engine's non-strict pre-execute validation only `warn`s
+ *     (`Node "report-results" has unresolved templates: [...]`)
+ *
+ * Net effect: the agent received an empty string, mis-judged the run and wrote
+ * 0/0/0 while the workflow reported `completed`. Nothing failed, nothing was
+ * blocked — the definition was semantically wrong but structurally fine.
+ *
+ * This module supplies the missing *semantic* contract so `workflow_validate`
+ * can reject such definitions up-front with an actionable message.
+ *
+ * ## The contract table (derived from source, not guessed)
+ *
+ * Every node's `execute()` returns a `NodeExecutionResult`
+ * (`{ success?, output, error?, durationMs?/duration? }`) — see
+ * `types/run.ts` `NodeExecutionResult`. The engine then stores **only
+ * `result.output`** into the shared outputs map. Therefore the fields a
+ * downstream template can reach are the fields of that *inner* `output` value
+ * (plus the virtual `.output` prefix, which `template-resolver` treats as
+ * "unwrap the stored value").
+ *
+ * | node type      | node returns (`output`)                        | reachable first-level fields        |
+ * |----------------|-----------------------------------------------|-------------------------------------|
+ * | `tool`         | tool result (`output`, usually a string)       | `output`                            |
+ * | `python_call`  | JSON-parsed stdout (object / scalar / string)  | `output`                            |
+ * | `skill`        | `skill.invoke()` return value                  | `output`                            |
+ * | `condition`    | `{ success, condition }`                       | `output`, `success`, `condition`    |
+ * | `merge`        | `{ strategy, results, count }`                 | `output`, `strategy`, `results`, `count` |
+ * | `agent`        | `{ result, metadata, workflowHistory, ...json }` | `result`, `output`, `metadata`, `workflowHistory`, + declared JSON schema fields |
+ * | `workflow`     | child workflow's top-level output (unknown)     | `output`, `result` (both tolerated) |
+ * | `ask_user`     | never returns (always throws to pause)          | (none)                              |
+ *
+ * Source anchors:
+ *   - `tool-node.ts` (returns `{ output: extractedOutput, error, durationMs }`)
+ *   - `python-call-node.ts` (`{ output, error: undefined, durationMs }`)
+ *   - `skill-node.ts` (`{ output, error: undefined, durationMs }`)
+ *   - `condition-node.ts` (`output: { success, condition }`)
+ *   - `merge-node.ts` (`output: { strategy, results, count }`)
+ *   - `agent-node.ts` + `build-agent-node-output.ts` (`{ result, ...json }`)
+ *   - `workflow-node.ts` (`output: result.output` of the child run)
+ */
+/** Fields that are always reachable because `.output` is a virtual prefix
+ *  (template-resolver treats `{{nodes.X.output}}` as "unwrap the stored value"). */
+export declare const VIRTUAL_OUTPUT_FIELD = "output";
+export interface NodeOutputContract {
+    /**
+     * First-level fields reachable via `{{nodes.<id>.<field>}}` **in addition to**
+     * the virtual `output` prefix (`VIRTUAL_OUTPUT_FIELD` is always allowed).
+     */
+    fields: string[];
+    /**
+     * `true` when the field set is *closed* — i.e. any other first-level field is
+     * provably unresolvable at runtime and should be flagged.
+     * `false` when the shape is open/unknown (agent free-text, child workflow),
+     * in which case only a best-effort hint is produced.
+     */
+    closed: boolean;
+    /** Human-readable description of the stored value, used in error messages. */
+    description: string;
+    /**
+     * Suggested replacement field when an unresolvable one is referenced. Used to
+     * mint the "Did you mean ...?" hint.
+     *
+     * Note: for `.result` misuse on a *structured* node (condition / merge) the
+     * validator prefers `canonicalField` over this generic fallback — see
+     * `getSuggestionFieldForResultMisuse()`.
+     */
+    suggestedField?: string;
+    /**
+     * The field that actually carries the node's *answer* (CV-4298 P2#2). Used to
+     * make the "Did you mean ...?" hint point at the useful field rather than the
+     * generic `.output` wrapper.
+     *
+     * e.g. a `condition` node's answer is `.condition`; a `merge` node's is
+     * `.results`. Leaving it undefined means "no better answer than `.output`".
+     */
+    canonicalField?: string;
+}
+/**
+ * Canonical contracts keyed by node `type`.
+ *
+ * NOTE on `python_call`: the YAML type token is `pythonCall` in some docs but
+ * the registered node type is `python_call` (`python-call-node.ts`:
+ * `readonly type = 'python_call'`). Both spellings are registered here so the
+ * validator is robust to either.
+ */
+export declare const NODE_OUTPUT_CONTRACTS: Record<string, NodeOutputContract>;
+/**
+ * Resolve the contract for a node type. Unknown/custom node types get an
+ * open-ended contract (`closed: false`) so the validator never false-positives
+ * on node types it does not know about.
+ */
+export declare function getNodeOutputContract(nodeType: string): NodeOutputContract;
+/**
+ * Pick the field to recommend when a `.result` reference is invalid on this node
+ * type (CV-4298 P2#2).
+ *
+ * Order of preference:
+ *   1. `canonicalField` — the field that carries the node's answer
+ *      (condition → `condition`, merge → `results`).
+ *   2. `suggestedField` — generic fallback (usually `.output`).
+ *   3. `.output` — always resolvable (the virtual unwrap prefix).
+ */
+export declare function getSuggestionFieldForResultMisuse(nodeType: string): string;
+/** Whether a contracted node type has a *closed* (fully enumerable) field set. */
+export declare function hasClosedOutputContract(nodeType: string): boolean;
+/**
+ * Node types whose stored value is *definitely not* an `{ result, ... }`
+ * envelope. Referencing `.result` on these is the canonical "agent idiom
+ * misapplied to a data node" bug — treated as an **error**.
+ */
+export declare const RESULT_INVALID_NODE_TYPES: Set<string>;
+/**
+ * Extract the declared JSON output field names from an agent node's config
+ * (`config.output.schema.properties`), when `output.mode === "json"`.
+ *
+ * Returns `undefined` when the node does not declare a structured schema — in
+ * which case the agent's field set is unknowable and the validator stays lenient.
+ */
+export declare function getAgentDeclaredJsonFields(config: Record<string, unknown> | undefined): string[] | undefined;

package/dist/env/workflow/utils/node-registry-helper.d.ts

@@ -0,0 +1,36 @@
+/**
+ * NodeRegistry 集成辅助
+ *
+ * 提供函数来帮助将 decorator 节点类型注册到 NodeRegistry
+ */
+import type { NodeRegistry } from '../engine/node-registry';
+/**
+ * 将所有内置节点类型注册到 NodeRegistry
+ *
+ * @param registry - NodeRegistry 实例
+ *
+ * @example
+ * ```typescript
+ * import { registerDecoratorNodeType } from '@roy-agent/workflow-decorators';
+ *
+ * // 在 WorkflowComponent 初始化时调用
+ * registerDecoratorNodeType(registry);
+ * ```
+ */
+export declare function registerDecoratorNodeType(registry: NodeRegistry): void;
+/**
+ * 检查 WorkflowDefinition 是否包含 decorator 类型的节点
+ */
+export declare function hasDecoratorNodes(nodes: Array<{
+    type: string;
+}>): boolean;
+/**
+ * 从 WorkflowDefinition 中提取所有 decorator 类型的节点
+ */
+export declare function getDecoratorNodes(nodes: Array<{
+    type: string;
+    id: string;
+}>): Array<{
+    type: string;
+    id: string;
+}>;

package/dist/env/workflow/utils/output-schema-hint.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Human-readable hints derived from AgentNode output JSON schema.
+ */
+import type { JsonSchemaObject } from './json-schema-to-zod';
+export declare function describeOutputSchema(schema: JsonSchemaObject | Record<string, unknown> | undefined): string;
+export declare function buildJsonOutputNudgeMessage(schema?: JsonSchemaObject | Record<string, unknown>): string;
+export declare function buildJsonOutputRerunHint(schema?: JsonSchemaObject | Record<string, unknown>): string;

package/dist/env/workflow/utils/parse-agent-output-config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse AgentNode output configuration from workflow node config.
+ */
+export type AgentOutputMode = 'string' | 'json';
+export interface AgentOutputConfig {
+    mode: AgentOutputMode;
+    schema?: Record<string, unknown>;
+}
+export declare function parseAgentOutputConfig(config: Record<string, unknown>): AgentOutputConfig;

package/dist/env/workflow/utils/recovery-validator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * RecoveryValidator - 分层恢复验证框架
+ *
+ * 遵循保守策略，严格验证状态完整性
+ */
+import type { WorkflowDefinition } from '../types';
+import type { SessionMessage } from '../../session/types';
+import type { ValidationResult, RecoveryPlan } from './validation-rules';
+/**
+ * RecoveryValidator - 分层恢复验证框架
+ *
+ * 遵循保守策略，严格验证状态完整性
+ */
+export declare class RecoveryValidator {
+    private stateBuilder;
+    constructor();
+    validate(messages: SessionMessage[], definition: WorkflowDefinition): Promise<ValidationResult>;
+    generatePlan(messages: SessionMessage[], definition: WorkflowDefinition): Promise<RecoveryPlan>;
+    private validateStateIntegrity;
+    private validateParallelBranches;
+    private validateConditionBranches;
+    private validateLoopState;
+    private validateNestedWorkflows;
+    private extractVariableRefs;
+    private identifyParallelGroups;
+    private findMergeNodeForParallel;
+    private identifyLoops;
+    private determineResumePoint;
+    private generateSummary;
+}

package/dist/env/workflow/utils/sensitive-redact.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview sensitive-redact.ts — Redact sensitive fields from input before persisting (Task #2900 P1)
+ *
+ * Background: engine.ts was persisting the raw workflow `input` object into
+ * session metadata.input, leaking sensitive fields (password / LDAP_PASSWORD /
+ * apiKey / token / secret) to the session DB. This util produces a deep-copy
+ * with sensitive keys replaced by the `"[REDACTED]"` sentinel.
+ *
+ * Design choices:
+ *   - Case-insensitive matching (PASSWORD / Password / password all redacted).
+ *   - Recurses into nested objects AND arrays (so {config:{auth:{password}}}
+ *     and [{user, password}] are both safe).
+ *   - Does NOT mutate the input — callers can safely pass the original object
+ *     elsewhere.
+ *   - Returns undefined for undefined/null input so engine.ts:447 etc. behave
+ *     identically when no input was supplied.
+ *   - Returns non-object scalars (strings, numbers, booleans) unchanged —
+ *     they can't contain field names.
+ *
+ * Sensitive key list (lowercase, prefix-matched):
+ *   password, ldap_password, apikey, api_key, token, secret, auth,
+ *   access_token, refresh_token, authorization, cookie, private_key,
+ *   session_token, sid
+ *
+ * Note: 'sid' is included to redact the ONES ones-ids-sid cookie value if
+ * accidentally passed as a top-level field (the workflow uses sidCookie,
+ * not sid, so this is defensive).
+ */
+/** Sentinel value used to replace redacted fields. */
+export declare const REDACTED_SENTINEL = "[REDACTED]";
+/**
+ * Redact sensitive fields from `input`. Returns a new object/array with
+ * sensitive values replaced by "[REDACTED]". Non-sensitive scalars and
+ * non-object values pass through unchanged. Returns undefined for
+ * undefined/null input.
+ */
+export declare function redactSensitiveFields<T = unknown>(input: T): T | undefined;

package/dist/env/workflow/utils/session-parser.d.ts

@@ -0,0 +1,23 @@
+import type { SessionMessage } from '../../session/types';
+/**
+ * 查找最后一个 workflow.node.interrupt 消息
+ */
+export declare function findLastInterruptMessage(messages: SessionMessage[]): SessionMessage | null;
+/**
+ * 解析节点输出
+ *
+ * 通过匹配 workflow.node.start 和 workflow.node.end 消息对来提取节点输出
+ */
+export declare function parseNodeOutputs(messages: SessionMessage[]): Map<string, unknown>;
+/**
+ * 获取下一个待执行的节点
+ */
+export declare function getNextPendingNode(messages: SessionMessage[]): string | null;
+/**
+ * 从 interrupt 消息获取 agentSessionId
+ */
+export declare function getAgentSessionIdFromInterrupt(interruptMessage: SessionMessage): string | undefined;
+/**
+ * 检查 session 是否在等待用户
+ */
+export declare function isWaitingForUser(messages: SessionMessage[]): boolean;

package/dist/env/workflow/utils/session-recovery.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Session Recovery Utilities
+ *
+ * Utilities for inferring the next execution point from session messages.
+ * This is the core of the unified run/resume mechanism.
+ *
+ * Message types:
+ * - workflow.node.start: Node execution started (对应 tool-call)
+ * - workflow.node.interrupt: Node waiting for user input
+ * - workflow.node.end: Node execution completed (对应 tool-result)
+ * - workflow.node.resume: Node resumed after user response
+ */
+import type { SessionMessage } from '../../session/types';
+import type { AgentSessionRef } from '../types/workflow-message';
+/**
+ * Represents a resume point - where to continue execution from
+ */
+export interface ResumePoint {
+    /** Type of resume point */
+    type: 'entry_node' | 'resume_node' | 'ask_user' | 'next_nodes';
+    /** Node ID (for single node resume) */
+    nodeId?: string;
+    /** Node IDs (for multiple next nodes) */
+    nodeIds?: string[];
+    /** Agent sub-session ID (for agent node resume) */
+    agentSessionId?: string;
+    /** Input for the node */
+    input?: unknown;
+}
+/**
+ * Infer the next node to execute based on session messages
+ *
+ * Decision logic:
+ * - No messages → execute entry node
+ * - Last = workflow.node.start → resume this node (incomplete/interrupted)
+ * - Last = workflow.node.interrupt → resume this node (ask_user)
+ * - Last = workflow.node.end → execute next nodes from DAG
+ * - Unknown → find last start, resume it, or fallback to entry
+ */
+export declare function inferNextNode(messages: SessionMessage[], definition: {
+    entryNode?: string;
+    edges?: Array<{
+        from: string;
+        to: string;
+    }>;
+}): ResumePoint;
+/**
+ * Find the last interrupt message in the session
+ */
+export declare function findLastInterruptMessage(messages: SessionMessage[]): SessionMessage | null;
+/**
+ * Find the last start message in the session
+ */
+export declare function findLastStartMessage(messages: SessionMessage[]): SessionMessage | null;
+/**
+ * Find the last call message (workflow.node.call) in the session
+ */
+export declare function findLastCallMessage(messages: SessionMessage[]): SessionMessage | null;
+/**
+ * Parse node outputs from session messages
+ *
+ * Extracts outputs by matching:
+ * - workflow.node.start with workflow.node.end pairs
+ * - workflow.node.call with workflow.node.result pairs
+ */
+export declare function parseNodeOutputs(messages: SessionMessage[]): Map<string, unknown>;
+/**
+ * Check if session has pending ask_user interrupt
+ */
+export declare function hasPendingAskUser(messages: SessionMessage[]): boolean;
+/**
+ * Get agent session ID from last interrupt message
+ */
+export declare function getAgentSessionIdFromInterrupt(messages: SessionMessage[]): string | null;
+/**
+ * Resolve agent sub-session ID for a pending node.
+ * Prefers explicit agentSessionId from messages; falls back to workflow metadata.agentSessions.
+ */
+export declare function resolveAgentSessionId(nodeId: string | undefined, agentSessionId: string | undefined, agentSessions?: AgentSessionRef[]): string | undefined;
+export declare function enrichResumeInfoWithAgentSessions(resumeInfo: ResumeInfo, agentSessions?: AgentSessionRef[]): ResumeInfo;
+export declare function enrichResumePointWithAgentSessions(resumePoint: ResumePoint, agentSessions?: AgentSessionRef[]): ResumePoint;
+/**
+ * Complete resume information extracted from session messages
+ */
+export interface ResumeInfo {
+    /** Pending node ID (if any node was interrupted) */
+    pendingNodeId: string | undefined;
+    /** Agent sub-session ID for the pending node */
+    agentSessionId: string | undefined;
+    /** Whether there is a pending interrupt (ask_user) */
+    hasInterrupt: boolean;
+    /** Node outputs from completed nodes */
+    nodeOutputs: Map<string, unknown>;
+    /** Last interrupt message content (query) */
+    lastInterruptQuery?: string;
+}
+/**
+ * Extract complete resume information from session messages
+ *
+ * This function consolidates the logic that was previously scattered across
+ * engine.ts and other places. It extracts all information needed to resume
+ * a workflow from its session messages.
+ *
+ * The key insight is:
+ * - If the last message is an interrupt, use its metadata for resume
+ * - No need for complex userResponse distinction
+ * - agentSessionId comes from interrupt message metadata
+ * - userQuery comes from the input provided during resume
+ *
+ * @param messages - Session messages to analyze
+ * @returns Complete resume information
+ */
+export declare function extractResumeInfo(messages: SessionMessage[]): ResumeInfo;
+/**
+ * Split ephemeral resume userQuery from durable workflow input.
+ * userQuery is only valid for the node being resumed and must not persist
+ * in workflowInput for subsequent nodes.
+ */
+export declare function stripEphemeralResumeInput(input?: Record<string, unknown>): {
+    workflowInput?: Record<string, unknown>;
+    userQuery?: unknown;
+};