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

package/dist/env/workflow/utils/agent-session-metadata.d.ts

@@ -0,0 +1,48 @@
+import type { AgentSessionRef } from '../types/workflow-message';
+/**
+ * Update a single agent session's status by nodeId.
+ * Returns a new array; does not mutate input. Returns empty array if input is undefined/empty.
+ */
+export declare function updateAgentSessionStatus(agentSessions: AgentSessionRef[] | undefined, nodeId: string, status: AgentSessionRef['status']): AgentSessionRef[];
+/**
+ * Mark a single node's agent session as 'completed'.
+ * Convenience wrapper over updateAgentSessionStatus for symmetry with Failed/Stopped.
+ */
+export declare function markAgentSessionCompleted(agentSessions: AgentSessionRef[] | undefined, nodeId: string): AgentSessionRef[];
+/**
+ * Register (or refresh) a node's agent sub-session reference.
+ *
+ * Replaces an existing entry for the same `nodeId` (refresh + reset to
+ * 'active') or appends a new one. Returns a new array; does not mutate input.
+ *
+ * Task #4412 C1: this used to be inline in `AgentNode.createAgentSubSession()`
+ * operating directly on the metadata it had just read, which loses entries when
+ * sibling agent nodes register concurrently. Extracted here so the engine can
+ * run it *inside* its serialized metadata queue (where the array it receives is
+ * guaranteed to be the current one).
+ */
+export declare function upsertAgentSession(agentSessions: AgentSessionRef[] | undefined, nodeId: string, agentSessionId: string): AgentSessionRef[];
+/**
+ * Mark a single node's agent session as 'failed'.
+ */
+export declare function markAgentSessionFailed(agentSessions: AgentSessionRef[] | undefined, nodeId: string): AgentSessionRef[];
+/**
+ * Mark a single node's agent session as 'stopped'.
+ */
+export declare function markAgentSessionStopped(agentSessions: AgentSessionRef[] | undefined, nodeId: string): AgentSessionRef[];
+/**
+ * Mark ALL non-terminal (active/paused) agent sessions as 'completed'.
+ * Already-terminal sessions (completed/failed/stopped) are preserved.
+ * Used by WorkflowEngine.completeWorkflow().
+ */
+export declare function markAllAgentSessionsCompleted(agentSessions: AgentSessionRef[] | undefined): AgentSessionRef[];
+/**
+ * Mark ALL non-terminal (active/paused) agent sessions as 'stopped'.
+ * Used by WorkflowEngine.stop() — distinguishes a graceful stop from a failure.
+ */
+export declare function markAllAgentSessionsStopped(agentSessions: AgentSessionRef[] | undefined): AgentSessionRef[];
+/**
+ * Mark ALL non-terminal (active/paused) agent sessions as 'failed'.
+ * Used by WorkflowEngine.failWorkflow().
+ */
+export declare function markAllAgentSessionsFailed(agentSessions: AgentSessionRef[] | undefined): AgentSessionRef[];

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/index.js

@@ -14,7 +14,7 @@ import {
   hasClosedOutputContract,
   validateTemplateContracts,
   validateWorkflowDefinition
-} from "../../../shared/@ai-setting/roy-agent-core-na73mym1.js";
+} from "../../../shared/@ai-setting/roy-agent-core-a4vzsn0g.js";
 import {
   TemplateResolver,
   init_template_resolver,

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/redact-command-secrets.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview redact-command-secrets.ts — Mask inline secrets in shell commands
+ * before they are embedded in a user/agent-visible error message (Task #4392 P0-2).
+ *
+ * Background: #4385 §5.5 diff-1 asks for `Tool exited with code N` to be enriched
+ * with the command that was run. That command may legitimately contain inline
+ * credentials (`twine upload --password=...`, `curl -H "Authorization: Bearer ..."`,
+ * `PIP_INDEX_TOKEN=... npm publish`), which must NOT leak into:
+ *   - `workflow.node.end` session messages,
+ *   - trace span attributes,
+ *   - the LLM context of the next turn.
+ *
+ * This helper is a *best-effort* shell-string masker (complementary to
+ * `sensitive-redact.ts`, which only redacts object **field names**). It never
+ * tries to parse shell; it matches the common credential shapes:
+ *
+ *   1. `KEY=value` / `KEY: value` / `--flag value` / `--flag=value`
+ *      where KEY looks sensitive (`ASSIGNMENT_RE`, `FLAG_RE`).
+ *   2. `<Scheme> <credential>` auth headers — `Authorization: Bearer <token>`,
+ *      `Basic <base64>`, `Token <value>`, `Digest <value>` (`AUTH_SCHEME_RE`).
+ *      The value is a *separate* word from the scheme, hence its own rule.
+ *   3. URL query credentials — `?token=`, `&api_key=`, `&secret=`, `&sig=`
+ *      (`URL_QUERY_RE`).
+ *   4. URL userinfo credentials — `https://user:pass@host` (`URL_USERINFO_RE`).
+ *   5. Short-option credentials — `curl -u user:pass`, `docker login -p <pw>`,
+ *      `mysql -pVALUE` (`SHORT_CRED_RE`).
+ *
+ * ## Why rules 2–5 exist (Task #4419, from #4417 §B-1)
+ *
+ * The original implementation only had rules 1, and its bare-value branch stops
+ * at the first whitespace. `Authorization: Bearer <token>` is *two* words, so it
+ * masked `Bearer` and left the token intact. #4417 measured 9 of 14 real command
+ * shapes still leaking. Rules 2–5 close those holes.
+ *
+ * ## Ordering / idempotency
+ *
+ * The rules are applied in a fixed order and each rule already skips values that
+ * equal the `[REDACTED]` sentinel, so `redact(redact(x)) === redact(x)` holds.
+ * Rule 2 is applied **before** rule 1: rule 1 would otherwise see
+ * `Authorization: Bearer` and mask only the scheme word, leaving an
+ * `Authorization: [REDACTED] <token>` remainder that rule 2 can no longer anchor.
+ *
+ * ## Non-goals
+ *
+ * - No shell parsing / word-splitting (quoting, `$VAR` expansion, heredocs).
+ * - Environment-variable *references* (`$TOKEN`, `${TOKEN}`) are left alone —
+ *   the variable name is not itself a secret, and masking it destroys the
+ *   diagnostic value of the message.
+ */
+/**
+ * Mask inline secrets inside a single shell command string.
+ *
+ * Idempotent: masked values (`[REDACTED]`) are left as-is.
+ *
+ * @param command - The raw command string (may be multi-line).
+ * @returns The command with sensitive values replaced by `[REDACTED]`.
+ */
+export declare function redactCommandSecrets(command: string): string;
+/**
+ * Collapse a multi-line command into a single readable line and truncate it.
+ *
+ * Rationale: error messages are rendered as one line in `workflow.node.end`
+ * messages and in most logs; embedding raw newlines makes them unreadable and
+ * breaks naive `grep`-based diagnosis.
+ *
+ * @param command - Raw command (possibly multi-line, possibly huge).
+ * @param maxLen - Maximum length of the returned string (default 120).
+ * @returns Single-line, whitespace-normalized, truncated command.
+ */
+export declare function summarizeCommand(command: string, maxLen?: number): string;

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;