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

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;
+};

package/dist/env/workflow/utils/shell-dialect-lint.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Shell dialect lint for workflow `tool` node commands
+ * (Task #4392 P0-3; root cause proven in Task #4385 §3.2.1).
+ *
+ * ## Why this exists
+ *
+ * The built-in `bash` tool spawns its command with Node's
+ * `child_process.spawn(command, [], { shell: true })`
+ * (see `env/tool/built-in/bash-effect.ts`). On POSIX, `shell: true` resolves to
+ * **`/bin/sh`**, which on Debian/Ubuntu is a symlink to **dash** — *not* bash.
+ *
+ * Every bash-only construct therefore fails inside a workflow tool node. Worse,
+ * half of them fail **silently**:
+ *
+ * | construct            | dash behaviour                | exit | loud? |
+ * | -------------------- | ----------------------------- | ---- | ----- |
+ * | `set -o pipefail`    | `Illegal option -o pipefail`  | 2    | ✅    |
+ * | `${PIPESTATUS[0]}`   | `Bad substitution`            | 2    | ✅    |
+ * | `${V//a/b}`          | `Bad substitution`            | 2    | ✅    |
+ * | `${BASH_SOURCE[0]}`  | `Bad substitution`            | 2    | ✅    |
+ * | `A=(1 2 3)`          | `Syntax error: "(" unexpected`| 2    | ✅    |
+ * | `function f() {}`    | `Syntax error: "(" unexpected`| 2    | ✅    |
+ * | `[[ ... ]]`          | `[[: not found`               | 127  | ✅    |
+ * | `source <file>`      | `source: not found`           | 0    | ❌    |
+ * | `echo -e "a\tb"`     | prints a literal `-e`         | 0    | ❌    |
+ * | `$RANDOM`            | empty string                  | 0    | ❌    |
+ *
+ * Task #4385 measured **63** `/bin/sh:` signature hits across 45 sessions, and
+ * these account for 27 of the workflow-creator's `exit 2` failures.
+ *
+ * ## Severity policy
+ *
+ * These findings are **warnings, never errors**. The 76 workflows already in
+ * `workflows.db` must keep validating cleanly, and a `dash`-safe workflow can
+ * legitimately contain the *string* `pipefail` inside an embedded heredoc that
+ * is executed by `bash -c` on purpose. Blocking on a heuristic regex would be
+ * wrong; surfacing it loudly for the author to judge is right.
+ *
+ * ## What is deliberately NOT flagged
+ *
+ * - `. <file>` (POSIX dot-command) — the correct replacement for `source`.
+ * - `$?`, `$0`, `$1`… — POSIX.
+ * - `[ ... ]` — POSIX test.
+ * - `sed 's/a/b/'` — no `${...}` involved.
+ * - Text inside shell **comments** (`# ...`) — cannot fail at runtime.
+ */
+/** A single detected bash-ism. */
+export interface ShellDialectFinding {
+    /** Stable rule name, e.g. `pipefail`. Used in machine-readable output. */
+    name: string;
+    /** Actionable replacement hint written for an LLM/tool author to act on. */
+    fix: string;
+    /** Short excerpt of the offending command (surrounding context). */
+    excerpt: string;
+}
+/**
+ * Detect bash-only constructs in a shell command intended for the `bash` tool.
+ *
+ * @param command - The raw command string (from `config.command`).
+ * @returns One finding per *distinct* rule that matched. Repeated occurrences of
+ *          the same rule are collapsed (a 50-line script using `$RANDOM` ten
+ *          times should produce one warning, not ten).
+ */
+export declare function lintShellDialect(command: string): ShellDialectFinding[];
+/**
+ * Render findings as one actionable line each, prefixed with the node id.
+ *
+ * Format is deliberately stable so it can be asserted in tests and grepped in
+ * logs:
+ *   `[shell-dialect] node "build-x" uses bash-only "pipefail": <fix> | near: <excerpt>`
+ *
+ * @param nodeId - The workflow node id that owns the command.
+ * @param findings - Output of `lintShellDialect`.
+ */
+export declare function formatShellDialectFindings(nodeId: string, findings: ShellDialectFinding[]): string[];

package/dist/env/workflow/utils/template-contract-validator.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Static **template-reference contract** validation for workflow
+ * definitions (Task #4298).
+ *
+ * ## The problem
+ *
+ * `workflow_validate` (and `workflow_add`) historically only ran DAG-structure
+ * checks (duplicate IDs / missing deps / cycles / empty IDs). It could not
+ * notice that a node's prompt referenced a field its upstream node can never
+ * produce — which is exactly how `wheels-validate-v1` v1.3.0 shipped a
+ * workflow whose `report-results` agent received an *empty string* for
+ * `{{nodes.run-validation-tests.result}}` (a **tool** node has no `result`)
+ * and then reported `completed` anyway.
+ *
+ * ## What this module does
+ *
+ * Walks every node's `config`, extracts *pure* `{{ ... }}` template paths, and
+ * checks each one against:
+ *
+ *   1. **R1** — the referenced source node actually exists            → error
+ *   2. **R2** — `.result` is an **agent-only** idiom; using it on a data
+ *      node (tool / python_call / skill / condition / merge / askUser)
+ *      is the canonical bug above                                    → error
+ *   3. **R3** — a first-level field that is not in the source node's
+ *      *closed* contract field set (may still resolve if the node's
+ *      `output` happens to be an object carrying that key)          → warning
+ *   4. **R4** — a deep path (`.output.<x>`) into a `tool` node whose
+ *      output is usually a plain string                              → info
+ *   5. **R5** — a field that contradicts an agent's **declared JSON
+ *      schema** (`config.output.schema.properties`)                   → warning
+ *   6. **R6** — the source node is not upstream of the consumer
+ *      (loops / forward refs legitimately consume prior-round output) → info
+ *
+ * Severity policy: only R1/R2 are `error` (blocking). R3/R5 are `warning`
+ * (advisory). R4/R6 are `info` (hint). This keeps the existing corpus clean —
+ * a scan of all 75 registered workflows yields **2 errors, both in
+ * `wheels-validate-v1`**, i.e. precisely the bug we set out to catch.
+ *
+ * ## Parsing rules (deliberately conservative)
+ *
+ * A `{{ ... }}` body is only considered a node reference when it is a *pure dot
+ * path* (`^[A-Za-z_][A-Za-z0-9_-]*(\\.[A-Za-z0-9_-]+|\\[-?\\d+\\])*$`). This
+ * excludes, in one stroke:
+ *   - scoped refs: `{{input.x}}` / `{{inputs.x}}` / `{{config.x}}` / `{{env.X}}`
+ *   - docker Go-templates: `{{index .RepoDigests 0}}`
+ *   - handlebars-ish conditionals: `{{#if input.x}}` / `{{/if}}`
+ *   - documentation placeholders: `{{nodes.<source-id>.<field>}}`
+ *   - shell parameter expansions and any prose containing a space
+ *
+ * It also explicitly ignores the `{{X | default ''}}` filter suffix used by a
+ * few workflows (the path is taken up to the first space or `|`).
+ */
+export type TemplateContractSeverity = "error" | "warning" | "info";
+export type TemplateContractRule = "R1-node-not-found" | "R2-result-on-non-agent" | "R3-unknown-field-on-closed" | "R4-deep-path-into-tool" | "R5-agent-schema-field" | "R6-not-upstream";
+export interface TemplateContractFinding {
+    /** `error` blocks `workflow_add`; `warning` / `info` are advisory. */
+    severity: TemplateContractSeverity;
+    rule: TemplateContractRule;
+    /** The node whose config contains the reference. */
+    nodeId: string;
+    /** The verbatim template, e.g. `{{nodes.run-validation-tests.result}}`. */
+    template: string;
+    /** The referenced source node id. */
+    sourceNodeId?: string;
+    /** The referenced source node type (when it exists). */
+    sourceNodeType?: string;
+    /** Human-readable, actionable explanation. */
+    message: string;
+    /** Suggested replacement template (when we can compute one). */
+    suggestion?: string;
+}
+/**
+ * Validate every template reference in a workflow definition against the
+ * source node's output contract.
+ *
+ * Never throws — malformed input yields `[]`.
+ *
+ * @param definition - Workflow definition (needs a `nodes` array)
+ * @returns Findings, in node-declaration order
+ */
+export declare function validateTemplateContracts(definition: unknown): TemplateContractFinding[];
+/** Convenience: only the blocking findings. */
+export declare function getTemplateContractErrors(definition: unknown): TemplateContractFinding[];
+/** Convenience: only the advisory findings. */
+export declare function getTemplateContractWarnings(definition: unknown): TemplateContractFinding[];
+/** Render findings as `string[]` for the `{ valid, errors }` callers. */
+export declare function formatTemplateContractFindings(findings: TemplateContractFinding[]): string[];

package/dist/env/workflow/utils/template-resolver.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview Template Resolver - Unified template resolution for workflow nodes
+ *
+ * This module provides a unified template resolution system for workflow nodes.
+ * Templates are in the format {{path}} where path can reference:
+ *
+ * - Input variables: {{input.key}} or {{input.key.nested}}
+ * - Node outputs: {{nodeId}} or {{nodeId.output}} or {{nodeId.output.path}}
+ * - With prefix: {{nodes.nodeId}} or {{nodes.nodeId.output.path}}
+ *
+ * @example
+ * ```typescript
+ * const resolver = new TemplateResolver({
+ *   input: { query: 'weather' },
+ *   previousOutputs: new Map([
+ *     ['fetch', { data: { temp: 25, condition: 'sunny' } }]
+ *   ])
+ * });
+ *
+ * resolver.resolve('Weather in {{input.query}}: {{nodes.fetch.data.condition}}');
+ * // => 'Weather in weather: sunny'
+ * ```
+ */
+import type { NodeExecutionContext } from '../types';
+/**
+ * Template resolution options
+ */
+export interface TemplateResolverOptions {
+    /** Input passed to the workflow/node */
+    input?: Record<string, unknown>;
+    /** Map of previous node outputs */
+    previousOutputs?: Map<string, unknown>;
+}
+/**
+ * Result of template resolution
+ */
+export interface ResolvedValue {
+    /** Whether the value was resolved */
+    resolved: boolean;
+    /** The resolved value */
+    value: unknown;
+}
+/**
+ * Result of resolveAndValidate operation
+ */
+export interface ResolveResult {
+    /** The resolved value (with templates replaced) */
+    resolved: unknown;
+    /** List of template strings that could not be resolved */
+    unresolved: string[];
+}
+/**
+ * TemplateResolver
+ *
+ * Resolves template strings that reference workflow inputs and node outputs.
+ */
+export declare class TemplateResolver {
+    private input;
+    private previousOutputs;
+    constructor(options?: TemplateResolverOptions);
+    /**
+     * Create a TemplateResolver from NodeExecutionContext
+     *
+     * @param context - Node execution context
+     * @returns TemplateResolver instance
+     */
+    static fromContext(context: NodeExecutionContext): TemplateResolver;
+    /**
+     * Resolve template references in an input value.
+     *
+     * Handles:
+     * - Primitive values (returned as-is)
+     * - Objects (recursively resolved)
+     * - Arrays (recursively resolved)
+     * - Strings (template resolution)
+     *
+     * Key behavior for template strings:
+     * - If the string is a pure template reference (e.g., "{{nodes.fetch}}"),
+     *   the resolved value is returned as-is (preserving objects/arrays)
+     * - If the string contains text + templates (e.g., "Hello {{name}}"),
+     *   returns a string with interpolated values
+     *
+     * @param input - Input value that may contain template strings
+     * @returns Input with template references resolved
+     */
+    resolveValue(input: unknown): unknown;
+    /**
+     * Check if a string is a pure template reference (starts with {{ and ends with }})
+     * @param str - String to check
+     * @returns The template content if pure, null otherwise
+     */
+    private extractPureTemplate;
+    /**
+     * Resolve a pure template reference and return the value as-is.
+     * @param templateContent - Content between {{ and }}
+     * @returns The resolved value (may be object, array, or primitive)
+     */
+    private resolvePureTemplate;
+    /**
+     * Resolve a path-style template reference and return the value.
+     *
+     * Task #2283 — added so the engine can read any previous-progress
+     * signal (e.g. `{{nodes.tdd-implement.commits[-1]}}`) inside
+     * loop_guard checks without having to re-parse the template.
+     *
+     * Supports:
+     *   - `{{input.foo}}` / `{{input.foo.bar}}`
+     *   - `{{nodes.X}}` / `{{nodes.X.Y}}` / `{{nodes.X.Y.Z}}`
+     *   - Array indexing: `{{nodes.X.list[0]}}`, `{{nodes.X.list[-1]}}`
+     *     (-1 means "last element"; -2 means "second to last", etc.)
+     *   - `.length` accessor on arrays
+     *
+     * The `{{` and `}}` wrappers are optional — a bare path string
+     * (`nodes.X.Y`) is also accepted.
+     *
+     * Returns `undefined` if any segment is missing, an array index is
+     * out of range, or the input is empty.
+     */
+    resolvePath(path: string): unknown;
+    /**
+     * Tokenize a path string into segments, respecting bracket notation
+     * `foo[0]`, `foo[-1]`, and the `.length` accessor.
+     *
+     * Examples:
+     *   "nodes.x.y"        -> ["nodes", "x", "y"]
+     *   "nodes.x.list[0]"  -> ["nodes", "x", "list", 0]
+     *   "nodes.x.list[-1]" -> ["nodes", "x", "list", -1]
+     *   "nodes.x.l.length" -> ["nodes", "x", "l", "length"]
+     */
+    private tokenizePath;
+    /**
+     * Navigate `tokens` (mix of string keys and integer indices) into
+     * `root`, returning the value at the end of the path or undefined.
+     *
+     * For negative indices, the engine resolves them as offset from the
+     * end of the array (-1 = last, -2 = second to last, ...).
+     */
+    private navigateTokens;
+    /**
+     * Resolve template content (the part inside {{ }}) and return the value.
+     * @param templateContent - The path to resolve (e.g., "input.key", "nodes.fetch.data")
+     * @returns The resolved value
+     */
+    private resolveTemplateContent;
+    /**
+     * Auto-unwrap AgentNode output format `{ result, metadata, ... }` when
+     * the caller asked for the bare node (no further path). Preserves the
+     * pre-tokenizer behavior where `{{nodeId}}` returns the result field
+     * rather than the whole wrapper object.
+     *
+     * Only unwraps when the value LOOKS like an AgentNode result wrapper
+     * (has `result` and not `nodes`); this guards against false positives
+     * on plain objects that happen to have a `result` key.
+     */
+    private unwrapAgentNodeResult;
+    /**
+     * Resolve a single template string.
+     *
+     * Supports patterns:
+     * - {{input.key}} - Input variable
+     * - {{nodeId}} - Node's entire output
+     * - {{nodeId.output}} - Node's output property
+     * - {{nodeId.output.path}} - Node's nested output property
+     * - {{nodes.nodeId}} - Node's entire output (with prefix)
+     * - {{nodes.nodeId.output.path}} - Node's nested property (with prefix)
+     *
+     * @param template - Template string to resolve
+     * @returns Resolved string
+     */
+    resolveString(template: string): string;
+    /**
+     * Resolve a node output path.
+     *
+     * @param path - Path like "nodeId" or "nodeId.output" or "nodeId.output.path"
+     * @returns The resolved value or undefined
+     */
+    private resolveNodePath;
+    /**
+     * Get a nested value from an object using dot notation.
+     *
+     * @param obj - Object to traverse
+     * @param path - Dot-separated path
+     * @returns The nested value or undefined
+     */
+    private getNestedValue;
+    /**
+     * Convert a value to string for template substitution.
+     *
+     * Task #2912: when value is undefined, return empty string instead of
+     * the original template. Returning the original template caused downstream
+     * bash guards (e.g. `[ -n "$SID_COOKIE_RAW" ]`) to evaluate as truthy
+     * on the template literal like `{{input.sidCookie}}`, which misrouted
+     * workflows into fallback paths when an input field was simply absent.
+     * null still returns the sentinel string "null" for backward compatibility.
+     */
+    private stringify;
+    /**
+     * Check if a string contains template references.
+     *
+     * @param str - String to check
+     * @returns True if the string contains template references
+     */
+    containsTemplates(str: string): boolean;
+    /**
+     * Extract all template references from a string.
+     *
+     * @param str - String to extract from
+     * @returns Array of template references
+     */
+    extractTemplates(str: string): string[];
+    /**
+     * Resolve and validate input, tracking unresolved templates.
+     *
+     * This method resolves all template references in the input and returns
+     * both the resolved value and a list of templates that could not be resolved.
+     *
+     * @param input - Input value that may contain template strings
+     * @returns Object containing resolved value and list of unresolved templates
+     */
+    resolveAndValidate(input: unknown): ResolveResult;
+    /**
+     * Internal method to resolve values while tracking unresolved templates.
+     */
+    private resolveValueWithTracking;
+    /**
+     * Resolve string templates while tracking unresolved ones.
+     */
+    private resolveStringWithTracking;
+    /**
+     * Resolve templates strictly, throwing on unresolved templates.
+     *
+     * This is useful when you want to ensure all templates are resolved
+     * before proceeding, and treat any unresolved templates as an error.
+     *
+     * Uses factory methods to create meaningful error messages with nodeId and reason.
+     *
+     * @param input - Input value that may contain template strings
+     * @param nodeId - Optional node ID for better error context
+     * @returns The resolved value
+     * @throws TemplateUnresolvedError if any templates could not be resolved
+     */
+    resolveStrict(input: unknown, nodeId?: string): unknown;
+    /**
+     * Evaluate a condition expression and return boolean result
+     * Supports operators: ==, !=, >, <, >=, <=, &&, ||, !
+     *
+     * @param condition - Condition expression with template references
+     * @returns Boolean result of the condition
+     * @throws Error if condition cannot be evaluated
+     */
+    evaluateCondition(condition: string): boolean;
+    /**
+     * Parse and evaluate a condition string
+     * Handles operator precedence: ! > && > ||
+     */
+    private parseCondition;
+    /**
+     * Split a string by an operator, respecting quoted strings
+     */
+    private splitByOperator;
+    /**
+     * Evaluate a value (handles strings, numbers, booleans)
+     */
+    private evaluateValue;
+    /**
+     * Compare two values with the given operator
+     */
+    private compare;
+}
+/**
+ * Resolve template references in input using context.
+ *
+ * @param input - Input value with potential templates
+ * @param context - Node execution context
+ * @returns Resolved input
+ */
+export declare function resolveTemplates(input: unknown, context: NodeExecutionContext): unknown;
+/**
+ * Resolve a template string using context.
+ *
+ * @param template - Template string
+ * @param context - Node execution context
+ * @returns Resolved string
+ */
+export declare function resolveTemplateString(template: string, context: NodeExecutionContext): string;

package/dist/env/workflow/utils/validate-workflow-definition.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Shared validateWorkflowDefinition helper.
+ *
+ * Single entry point for validating a workflow definition:
+ *
+ *   Layer 1 — DAG structure (delegated to DAGManager.validate()):
+ *     duplicate node IDs, missing dependencies, cycles, empty node IDs.
+ *
+ *   Layer 2 — Template-reference **contracts** (Task #4298, see
+ *     `template-contract-validator.ts`): does a `{{nodes.X.<field>}}`
+ *     reference actually match the output shape of node `X`? This is what
+ *     catches the `wheels-validate-v1` class of bug where an agent prompt
+ *     read `.result` off a **tool** node (which has no such field) and the
+ *     engine silently substituted an empty string.
+ *
+ *   Layer 3 — **Shell dialect lint** (Task #4392 P0-3, see
+ *     `shell-dialect-lint.ts`): the `bash` tool spawns with `shell: true`,
+ *     i.e. `/bin/sh` = dash. bash-only constructs (`set -o pipefail`,
+ *     `${PIPESTATUS[0]}`, `[[ ]]`, `source`, arrays, `$RANDOM`, `echo -e`, ...)
+ *     either fail loudly or -- worse -- silently no-op. Reported as **warning**
+ *     only: existing registered workflows must not be invalidated by a
+ *     heuristic regex.
+ *
+ * Wraps everything in a defensive try/catch so callers (workflow_add tool,
+ * `workflow add` CLI, workflow_validate tool, TaskTagPlugin.extractWorkflow)
+ * always get a consistent `{ valid, errors, warnings, infos }` shape — even
+ * when the input is garbage.
+ *
+ * Backward compatibility: the original `{ valid, errors }` shape is preserved;
+ * `warnings` / `infos` are additive. Only `error`-severity findings affect
+ * `valid`.
+ */
+import { type TemplateContractFinding } from "./template-contract-validator";
+export interface ValidateWorkflowResult {
+    valid: boolean;
+    /** Blocking problems. Non-empty ⟺ `valid === false`. */
+    errors: string[];
+    /**
+     * Advisory problems (Task #4298). These do NOT make the definition invalid,
+     * but the workflow-creator loop is expected to address them.
+     */
+    warnings?: string[];
+    /** Informational hints (e.g. references to non-upstream nodes). */
+    infos?: string[];
+    /** Structured findings, for callers that want machine-readable detail. */
+    findings?: TemplateContractFinding[];
+}
+export interface ValidateWorkflowOptions {
+    /**
+     * Skip the Layer-2 template-contract checks. Defaults to `false`.
+     *
+     * Provided for callers that only care about structural validity (e.g. a
+     * pre-flight DAG sanity check while a definition is still being authored
+     * incrementally).
+     */
+    skipTemplateContracts?: boolean;
+    /**
+     * Skip the Layer-3 shell-dialect lint. Defaults to `false`.
+     *
+     * Layer 3 emits **warnings only**, so there is rarely a reason to disable it;
+     * this switch exists for corpus/regression tests that pin the exact warning
+     * set of already-registered workflows.
+     */
+    lintShellDialect?: boolean;
+}
+/**
+ * Validate a workflow definition (structure + template contracts).
+ *
+ * @param definition - The workflow definition object (must have a `nodes` array).
+ * @param options - Optional behaviour switches.
+ * @returns `{ valid, errors, warnings, infos, findings }` — never throws.
+ */
+export declare function validateWorkflowDefinition(definition: unknown, options?: ValidateWorkflowOptions): ValidateWorkflowResult;
+/**
+ * Walk every `tool` node of a definition and lint its shell command(s).
+ *
+ * @returns Formatted, actionable warning lines (empty when clean).
+ */
+export declare function collectShellDialectWarnings(definition: unknown): string[];