@prompd/core 0.5.0-beta.10

package/dist/index.d.ts

@@ -0,0 +1,2929 @@
+import * as nunjucks from 'nunjucks';
+
+/**
+ * File System Abstraction (core, environment-agnostic).
+ *
+ * Defines the IFileSystem interface and the in-memory implementation used for
+ * browser + server compilation. The Node-backed NodeFileSystem and the adm-zip
+ * .pdpkg helpers live in @prompd/cli (they need Node APIs). Path operations here
+ * are inlined as POSIX so this module has zero Node imports.
+ */
+/**
+ * File system interface that can be implemented for different storage backends.
+ */
+interface IFileSystem {
+    /** Check if a file or directory exists. */
+    exists(filePath: string): boolean | Promise<boolean>;
+    /** Read a file's contents as a UTF-8 string. */
+    readFile(filePath: string): string | Promise<string>;
+    /** Check if a path is a directory. */
+    isDirectory(filePath: string): boolean | Promise<boolean>;
+    /** List files in a directory. */
+    readdir(dirPath: string): string[] | Promise<string[]>;
+    /** Resolve a path (for package resolution). */
+    resolve(...pathSegments: string[]): string;
+    /** Get the directory name of a path. */
+    dirname(filePath: string): string;
+    /** Join path segments. */
+    join(...pathSegments: string[]): string;
+}
+/**
+ * In-memory file system for browser + server-side compilation.
+ * Files are provided as a map of path -> content.
+ */
+declare class MemoryFileSystem implements IFileSystem {
+    private files;
+    constructor(files?: Record<string, string>);
+    /** Add or update a file in the in-memory file system. */
+    addFile(filePath: string, content: string): void;
+    /** Add multiple files at once. */
+    addFiles(files: Record<string, string>): void;
+    exists(filePath: string): boolean;
+    readFile(filePath: string): string;
+    isDirectory(filePath: string): boolean;
+    readdir(dirPath: string): string[];
+    resolve(...pathSegments: string[]): string;
+    dirname(filePath: string): string;
+    join(...pathSegments: string[]): string;
+    /** Get the virtual file system path for a package. */
+    getPackagePath(packageName: string, version: string): string;
+    /** Get all files under an optional base path. */
+    getAllFiles(basePath?: string): Map<string, string>;
+    /** Calculate total size (bytes) and file count under a base path. */
+    getTotalSize(basePath: string): {
+        size: number;
+        files: number;
+    };
+    /** Normalize path to forward slashes, drop leading ./ and /, no trailing slash. */
+    protected normalizePath(filePath: string): string;
+}
+/**
+ * Async backend for files NOT held in memory by a HybridFileSystem. Paths are
+ * normalized relative keys (forward slashes, no leading ./ or /), matching the
+ * keys MemoryFileSystem uses. readFile resolves null when the file is absent.
+ *
+ * This is how a host streams files lazily — e.g. a browser
+ * FileSystemDirectoryHandle, or a registry/package fetch — without loading the
+ * whole tree up front.
+ */
+interface AsyncFileBackend {
+    /** Read a file's UTF-8 contents; resolve null when it does not exist. */
+    readFile(path: string): Promise<string | null>;
+    /** Optional: report whether a path is a directory. */
+    isDirectory?(path: string): Promise<boolean>;
+    /** Optional: list a directory's immediate entry names. */
+    readdir?(path: string): Promise<string[]>;
+}
+/**
+ * In-memory file system with an async fall-through backend.
+ *
+ * Files placed in memory (constructor map / addFile) are served SYNCHRONOUSLY,
+ * so the synchronous Nunjucks {% include %} loader keeps working for them —
+ * pre-load the .prmd sources a compilation can {% include %} or inherit. Any
+ * path NOT in memory is read from the async backend, returning a Promise that
+ * the compiler's awaiting stages (inherits:, package context, asset extraction)
+ * consume. This lets a browser compile a folder of prompts: load the .prmd
+ * sources up front, stream binary/context assets on demand.
+ *
+ * Known limitation: the synchronous Nunjucks {% include %} loader cannot read
+ * backend-only files (it gets a Promise and throws a "requires synchronous"
+ * error). So anything {% include %}'d must be in memory — pre-load every source
+ * a compilation can include (the web host pre-loads all .prmd/.md). inherits:
+ * has no such limit; it resolves through the async stages.
+ *
+ * Composes (does not extend) MemoryFileSystem so the in-memory methods keep
+ * their strict sync return types and existing consumers are untouched.
+ */
+declare class HybridFileSystem implements IFileSystem {
+    private mem;
+    private backend;
+    constructor(files: Record<string, string> | undefined, backend: AsyncFileBackend);
+    /** Add or update an in-memory (synchronously-served) file. */
+    addFile(filePath: string, content: string): void;
+    /** Add multiple in-memory files at once. */
+    addFiles(files: Record<string, string>): void;
+    exists(filePath: string): boolean | Promise<boolean>;
+    readFile(filePath: string): string | Promise<string>;
+    isDirectory(filePath: string): boolean | Promise<boolean>;
+    readdir(dirPath: string): string[] | Promise<string[]>;
+    resolve(...pathSegments: string[]): string;
+    dirname(filePath: string): string;
+    join(...pathSegments: string[]): string;
+    /** Normalize to the same relative keys MemoryFileSystem uses, for backend lookups. */
+    private normalize;
+}
+
+/**
+ * Code file extensions that need frontmatter protection for security.
+ * These files will have prompd content frontmatter added to make them non-executable.
+ * Used by: CLI packager, registry security validation, frontend file selection
+ */
+declare const CODE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py", ".pyw", ".pyi", ".sh", ".bash", ".zsh", ".fish", ".ps1", ".psm1", ".psd1", ".bat", ".cmd", ".rb", ".rake", ".gemspec", ".go", ".rs", ".c", ".cpp", ".cc", ".cxx", ".h", ".hpp", ".hxx", ".java", ".kt", ".kts", ".scala", ".groovy", ".cs", ".fs", ".vb", ".php", ".phtml", ".pl", ".pm", ".swift", ".lua", ".r", ".R", ".jl", ".ex", ".exs", ".erl", ".hs", ".lhs", ".vue", ".svelte", ".sql"];
+/**
+ * Map file extensions to content type names for frontmatter metadata.
+ */
+declare const CONTENT_TYPES: Record<string, string>;
+/**
+ * Check if a file extension requires frontmatter protection.
+ */
+declare function needsFrontmatterProtection(filePath: string): boolean;
+/**
+ * Get the content type for a file extension.
+ */
+declare function getContentType(filePath: string): string;
+/**
+ * Package types supported by the prompd ecosystem.
+ * Defined in prompd.json under the "type" field.
+ */
+type PackageType = 'package' | 'workflow' | 'skill' | 'node-template';
+/**
+ * Maps each PackageType to its install directory name.
+ * e.g., .prompd/packages/, .prompd/workflows/, .prompd/skills/, .prompd/templates/
+ */
+declare const PACKAGE_TYPE_DIRS: Record<PackageType, string>;
+/**
+ * All valid package type strings, for validation.
+ */
+declare const VALID_PACKAGE_TYPES: readonly string[];
+/**
+ * Maps tool names to their native skill deployment directories.
+ * Used by `prompd install --tools <tool>` to deploy skills into tool-native locations.
+ */
+declare const TOOL_DEPLOY_DIRS: Record<string, string>;
+/**
+ * Check if a string is a valid PackageType.
+ */
+declare function isValidPackageType(type: string): type is PackageType;
+/**
+ * Get the install directory name for a given package type.
+ * Defaults to 'packages' for unknown types.
+ */
+declare function getInstallDirForType(type: string): string;
+interface PrompdParameter {
+    name: string;
+    /**
+     * string   — plain text
+     * number   — integer or float
+     * integer  — whole number only
+     * float    — decimal number
+     * boolean  — true / false
+     * array    — JSON array (untyped elements)
+     * object   — plain key-value object (non-array)
+     * json     — any JSON value: objects, arrays of objects, nested structures, etc.
+     * file     — file path; caller supplies file content as a string
+     * base64   — base64-encoded binary data (images, blobs, streams)
+     * date     — calendar date "YYYY-MM-DD"; default may be a relative expression
+     *            (now, today, now-7d, now+1w, now-3m, now-1y) resolved at compile time
+     * datetime — date + time "YYYY-MM-DDTHH:mm:ss"; same relative-default support
+     *            (now, now-2h, now-30min) resolved at compile time
+     */
+    type: 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'array' | 'object' | 'json' | 'file' | 'base64' | 'date' | 'datetime';
+    description?: string;
+    required?: boolean;
+    default?: any;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    enum?: string[];
+}
+interface UsingPackage {
+    name: string;
+    prefix?: string;
+}
+interface PrompdMetadata {
+    id: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    parameters?: PrompdParameter[];
+    variables?: PrompdParameter[];
+    system?: string | string[];
+    context?: string | string[];
+    task?: string | string[];
+    user?: string | string[];
+    assistant?: string | string[];
+    response?: string | string[];
+    output?: string | string[];
+    requires?: string[];
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    max_tokens?: number;
+    using?: string | UsingPackage[] | Record<string, string>;
+    inherits?: string;
+    override?: Record<string, string | null>;
+}
+interface PrompdFile {
+    metadata: PrompdMetadata;
+    content: string;
+    sections: Record<string, string>;
+}
+interface CustomProvider {
+    apiKey?: string;
+    baseUrl: string;
+    enabled: boolean;
+    models: string[];
+    type: string;
+}
+interface RegistryConfig {
+    url: string;
+    api_key?: string;
+    token?: string;
+    username?: string;
+}
+interface ProviderConfig {
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+    extraHeaders?: Record<string, string>;
+    extraParams?: Record<string, any>;
+}
+interface Config {
+    apiKeys: Record<string, string>;
+    defaultProvider?: string;
+    defaultModel?: string;
+    customProviders: Record<string, CustomProvider>;
+    providerConfigs?: Record<string, ProviderConfig>;
+    registry: {
+        default?: string;
+        registries: Record<string, RegistryConfig>;
+    };
+    scopes: Record<string, string>;
+    namespaces?: Record<string, string>;
+    currentNamespace?: string;
+    maxRetries?: number;
+    timeout?: number;
+    verbose?: boolean;
+}
+interface LLMResponse {
+    success: boolean;
+    response?: string;
+    error?: string;
+    content?: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+interface ValidationIssue {
+    level: 'error' | 'warning' | 'info';
+    message: string;
+    line?: number;
+    column?: number;
+}
+interface ExecuteOptions {
+    provider: string;
+    model: string;
+    apiKey?: string;
+    output?: string;
+    params?: Record<string, any>;
+    paramFiles?: string[];
+    version?: string;
+    metaSystem?: string;
+    metaContext?: string;
+    metaUser?: string;
+    verbose?: boolean;
+    registryUrl?: string;
+    workspaceRoot?: string;
+    fileSystem?: IFileSystem;
+    temperature?: number;
+    maxTokens?: number;
+}
+
+/**
+ * Environment-agnostic .prmd parser. Pure string -> structure; no file system.
+ * The Node CLI subclasses this to add fs-backed parseFile()/validateFile().
+ */
+declare class PrompdParser {
+    parseContent(content: string, _filePath?: string): PrompdFile;
+    /**
+     * Parse + validate .prmd content. Pure (no file system) so it runs in the
+     * browser. Returns parse errors as a single issue when content is malformed.
+     */
+    validateContent(content: string, _filePath?: string): ValidationIssue[];
+    protected validatePrompdFile(prompd: PrompdFile): ValidationIssue[];
+    private isValidSemver;
+}
+
+/**
+ * Custom error classes for Prompd CLI.
+ */
+declare class PrompdError extends Error {
+    constructor(message: string);
+}
+declare class ParseError extends PrompdError {
+    constructor(message: string);
+}
+declare class ValidationError extends PrompdError {
+    constructor(message: string);
+}
+declare class CompilationError extends PrompdError {
+    constructor(message: string);
+}
+declare class SecurityError extends PrompdError {
+    constructor(message: string);
+}
+
+/**
+ * Compilation pipeline types and interfaces.
+ *
+ * This module defines the core types used throughout the 6-stage compilation pipeline,
+ * mirroring the Python CLI's architecture for feature parity.
+ */
+
+/**
+ * Options for resolving a package reference to a path.
+ */
+interface ResolvePackageOptions {
+    fileSystem?: IFileSystem;
+    registryUrl?: string;
+    workspaceRoot?: string;
+}
+/**
+ * Injectable package resolver. The Node CLI provides a disk/registry-backed
+ * implementation; the browser omits it (single-file compile only), in which
+ * case stages that need package/inherits resolution emit a diagnostic instead
+ * of importing Node-only code.
+ */
+interface IPackageResolver {
+    resolvePackage(packageRef: string, options: ResolvePackageOptions): Promise<string>;
+}
+/**
+ * Stages of the compilation pipeline.
+ */
+declare enum CompilationStage {
+    LEXICAL_ANALYSIS = "lexical_analysis",
+    DEPENDENCY_RESOLUTION = "dependency_resolution",
+    SEMANTIC_ANALYSIS = "semantic_analysis",
+    ASSET_EXTRACTION = "asset_extraction",
+    TEMPLATE_PROCESSING = "template_processing",
+    CODE_GENERATION = "code_generation"
+}
+/**
+ * Resolved package information.
+ */
+interface ResolvedPackage {
+    path: string;
+    prefix?: string;
+}
+/**
+ * Structured diagnostic message with location information.
+ * Used for both errors and warnings to enable IDE integration.
+ */
+interface CompilationDiagnostic {
+    /** The diagnostic message */
+    message: string;
+    /** Severity level */
+    severity: 'error' | 'warning' | 'info';
+    /** Source stage that generated this diagnostic */
+    source?: string;
+    /** Starting line number (1-indexed) */
+    line?: number;
+    /** Starting column number (1-indexed) */
+    column?: number;
+    /** Ending line number (1-indexed) */
+    endLine?: number;
+    /** Ending column number (1-indexed) */
+    endColumn?: number;
+    /** Optional error code for quick-fix identification */
+    code?: string;
+    /** File path if different from main source file */
+    file?: string;
+}
+/**
+ * Context passed between compilation stages.
+ *
+ * Accumulates data as it flows through the pipeline, collecting errors,
+ * warnings, and transforming content at each stage.
+ */
+declare class CompilationContext {
+    sourceFile: string;
+    metadata?: PrompdMetadata;
+    content?: string;
+    /** Raw source content for line number calculation */
+    rawSource?: string;
+    dependencies: {
+        imports?: Record<string, ResolvedPackage>;
+        inherits?: string;
+    };
+    parameters: Record<string, any>;
+    contexts: string[];
+    /** Legacy string errors for backward compatibility */
+    errors: string[];
+    /** Legacy string warnings for backward compatibility */
+    warnings: string[];
+    /** Structured diagnostics with location information */
+    diagnostics: CompilationDiagnostic[];
+    outputFormat: string;
+    compiledResult?: string | Uint8Array;
+    verbose: boolean;
+    fileSystem: IFileSystem;
+    registryUrl?: string;
+    workspaceRoot?: string;
+    packageResolver?: IPackageResolver;
+    constructor(sourceFile: string, options?: CompilationOptions);
+    /**
+     * Add an error to the compilation context (legacy string format).
+     */
+    addError(message: string): void;
+    /**
+     * Add a warning to the compilation context (legacy string format).
+     */
+    addWarning(message: string): void;
+    /**
+     * Add a structured diagnostic with location information.
+     */
+    addDiagnostic(diagnostic: CompilationDiagnostic): void;
+    /**
+     * Find line and column for a pattern in the raw source.
+     * Returns 1-indexed line and column numbers.
+     */
+    findLocation(pattern: string | RegExp): {
+        line: number;
+        column: number;
+        endLine: number;
+        endColumn: number;
+    } | null;
+    /**
+     * Check if compilation has errors.
+     */
+    hasErrors(): boolean;
+    /**
+     * Get all diagnostics (errors and warnings).
+     */
+    getDiagnostics(): CompilationDiagnostic[];
+    /**
+     * Get only error diagnostics.
+     */
+    getErrors(): CompilationDiagnostic[];
+    /**
+     * Get only warning diagnostics.
+     */
+    getWarnings(): CompilationDiagnostic[];
+}
+/**
+ * Options for compilation.
+ */
+interface CompilationOptions {
+    outputFormat?: string;
+    parameters?: Record<string, any>;
+    outputFile?: string;
+    verbose?: boolean;
+    fileSystem?: IFileSystem;
+    /** Injected package resolver (Node CLI provides disk/registry; browser omits). */
+    packageResolver?: IPackageResolver;
+    /** Registry URL for package resolution. Defaults to https://registry.prompdhub.ai in production. */
+    registryUrl?: string;
+    /** Root directory for workspace (for package cache location). */
+    workspaceRoot?: string;
+    /**
+     * When true, skip required parameter validation.
+     * Use this for validation/diagnostics during editing when parameters won't be provided.
+     * When false (default), required parameters are validated during execution.
+     */
+    validateOnly?: boolean;
+}
+/**
+ * Abstract base interface for compiler pipeline stages.
+ */
+interface CompilerStage {
+    /**
+     * Process the compilation context through this stage.
+     */
+    process(context: CompilationContext): Promise<void>;
+    /**
+     * Get the name of this compilation stage.
+     */
+    getName(): string;
+}
+/**
+ * Represents a compiled prompt ready for formatting.
+ */
+interface CompiledPrompt {
+    metadata?: PrompdMetadata;
+    content?: string;
+    contexts: string[];
+    parameters: Record<string, any>;
+    verbose: boolean;
+}
+/**
+ * Protocol for output format plugins.
+ */
+interface OutputFormatter {
+    name: string;
+    fileExtension: string;
+    mimeType: string;
+    /**
+     * Format the compiled prompt into the target format.
+     */
+    format(compiled: CompiledPrompt): Promise<string>;
+}
+/**
+ * Information about a markdown section.
+ */
+interface SectionInfo {
+    id: string;
+    headingText: string;
+    content: string;
+    startLine: number;
+    endLine: number;
+    headingLevel: number;
+}
+/**
+ * Security configuration for file operations.
+ */
+interface SecurityConfig {
+    maxFileSize: number;
+    allowedExtensions: string[];
+    maxTemplateDepth: number;
+    templateTimeout: number;
+}
+/**
+ * Default security configuration.
+ */
+declare const DEFAULT_SECURITY_CONFIG: SecurityConfig;
+
+/**
+ * Compilation pipeline orchestrator.
+ *
+ * Manages the execution of the 6-stage compilation pipeline, ensuring stages
+ * run in order and errors are properly propagated.
+ */
+
+/**
+ * The main compiler pipeline orchestrator.
+ */
+declare class CompilerPipeline {
+    private stages;
+    private securityConfig;
+    constructor(stages?: CompilerStage[], securityConfig?: SecurityConfig);
+    /**
+     * Register a compilation stage.
+     */
+    registerStage(stage: CompilerStage): void;
+    /**
+     * Execute the compilation pipeline.
+     *
+     * @param source - Path to .prmd file or package reference
+     * @param options - Compilation options
+     * @returns Compilation context with result or errors
+     */
+    execute(source: string, options?: CompilationOptions): Promise<CompilationContext>;
+    /**
+     * Resolve source to file path (handles package references).
+     *
+     * @param source - Package reference or file path
+     * @param fileSystem - File system to use for resolution
+     * @param customFileSystem - Optional custom file system (used to detect in-memory mode)
+     * @param registryUrl - Optional registry URL for package resolution
+     * @param workspaceRoot - Optional workspace root for package cache location
+     */
+    private resolveSource;
+    /**
+     * Find all .prmd files in a directory.
+     *
+     * @param dir - Directory path
+     * @param fileSystem - File system to use
+     */
+    private findPromdFiles;
+    /**
+     * Get registered stages.
+     */
+    getStages(): CompilerStage[];
+}
+
+/**
+ * Pure package-reference helpers.
+ *
+ * These are the parts of the CLI's package-resolver that are environment-agnostic
+ * (string parsing + path-safety checks). The Node-only disk/registry resolution
+ * (`resolvePackage`, base-dir lookups) lives in @prompd/cli and is injected via
+ * IPackageResolver. Path operations are inlined as POSIX so this stays node-free.
+ */
+/**
+ * Strip a file path suffix from a package reference.
+ * @example "@ns/pkg@1.0.0/prompts/file.prmd" -> "@ns/pkg@1.0.0"
+ */
+declare function stripFilePath(packageRef: string): string;
+/**
+ * Parse package reference into name and version. Strips any file path suffix.
+ */
+declare function parsePackageReference(packageRef: string): {
+    name: string;
+    version: string;
+    scope?: string;
+};
+/**
+ * Parse a package reference that may include a file path within the package.
+ * Format: @namespace/package@version/path/to/file.prmd
+ */
+declare function parsePackageReferenceWithPath(packageRef: string): {
+    name: string;
+    version: string;
+    scope?: string;
+    filePath?: string;
+};
+/**
+ * Validate package reference format. Accepts optional file path suffix.
+ */
+declare function isValidPackageReference(packageRef: string): boolean;
+/**
+ * Resolve a file path within a package (POSIX, path-traversal safe).
+ */
+declare function resolvePackageFile(packagePath: string, filePath: string): string;
+
+/**
+ * Language Mapping Utilities
+ *
+ * Centralized file extension to programming language mappings
+ * used across the compilation pipeline for:
+ * - Wrapping extracted code files in markdown code blocks
+ * - Filtering code blocks based on context file types
+ */
+/**
+ * Map of file extensions to primary markdown code block language identifier.
+ * Used when wrapping extracted code files in markdown code blocks.
+ */
+declare const EXTENSION_TO_LANGUAGE: Record<string, string>;
+/**
+ * Map of file extensions to all valid code block language identifiers.
+ * Used when filtering code blocks - includes aliases (e.g., 'ts' for 'typescript').
+ */
+declare const EXTENSION_TO_LANGUAGE_ALIASES: Record<string, string[]>;
+/**
+ * Get the primary language identifier for a file extension.
+ * @param ext - File extension (e.g., '.ts')
+ * @returns Primary language identifier or undefined
+ */
+declare function getLanguageForExtension(ext: string): string | undefined;
+/**
+ * Get all valid language identifiers (including aliases) for a file extension.
+ * @param ext - File extension (e.g., '.ts')
+ * @returns Array of language identifiers or empty array
+ */
+declare function getLanguageAliasesForExtension(ext: string): string[];
+
+/**
+ * Minimal POSIX path helpers so @prompd/core needs no Node 'path' import.
+ * The in-memory/virtual file system uses POSIX-style paths throughout.
+ */
+declare function normalizePosix(p: string): string;
+declare function joinPosix(...segments: string[]): string;
+/** POSIX-style resolve relative to a base (absolute segments win). */
+declare function resolvePosix(base: string, p: string): string;
+declare function dirnamePosix(p: string): string;
+declare function basenamePosix(p: string): string;
+declare function isAbsolutePosix(p: string): boolean;
+/** Return the extension including the dot (e.g. ".prmd"), or "" if none. */
+declare function extname(p: string): string;
+/**
+ * Prompd source file extensions. A .prmd is just markdown (.md) with YAML
+ * frontmatter, so both are treated as first-class prompt sources.
+ */
+declare const PROMPD_EXTENSIONS: readonly [".prmd", ".md"];
+/** True if the path is a Prompd source file (.prmd or .md). */
+declare function isPrompdFile(p: string): boolean;
+
+/**
+ * Lexical Analysis Stage - Parse YAML frontmatter + Markdown content.
+ *
+ * This stage parses the .prmd file into structured metadata and content,
+ * populating the compilation context for subsequent stages.
+ */
+
+declare class LexicalAnalysisStage implements CompilerStage {
+    private parser;
+    constructor();
+    process(context: CompilationContext): Promise<void>;
+    /**
+     * Convert YAML-defined sections (system, user, assistant, etc.) to markdown sections.
+     * These are appended to the content after any markdown-defined sections.
+     */
+    private injectYamlSections;
+    getName(): string;
+}
+
+/**
+ * Dependency Resolution Stage
+ *
+ * Resolves 'using:' imports and 'inherits:' chains, handling both local file
+ * paths and package references with alias resolution.
+ *
+ * This is a direct port of the Python CLI's DependencyResolutionStage.
+ */
+
+declare class DependencyResolutionStage implements CompilerStage {
+    /**
+     * Resolve a package reference via the injected resolver. Absent in the browser
+     * (single-file compile), where package/inherits resolution is the backend's job.
+     */
+    private resolvePackage;
+    process(context: CompilationContext): Promise<void>;
+    /**
+     * Process the 'using' field for package imports.
+     */
+    private processUsingField;
+    /**
+     * Resolve a single package import.
+     */
+    private resolvePackageImport;
+    /**
+     * Process the 'inherits' field.
+     */
+    private processInheritsField;
+    /**
+     * Process content reference fields (system, context, user, assistant, response) for alias resolution.
+     */
+    private processContentFieldAliases;
+    /**
+     * Resolve alias prefixes in file paths.
+     *
+     * Examples:
+     * - "@pkg/templates/file.prmd" with "@pkg" aliased to "@scope/package@version"
+     *   becomes "@scope/package@version/templates/file.prmd"
+     */
+    private resolveAliasInPath;
+    getName(): string;
+}
+
+/**
+ * Semantic Analysis Stage - Validate parameters and references.
+ *
+ * This stage validates the semantic correctness of the prompt, checks required
+ * parameters, applies default values, and validates parameter types.
+ */
+
+declare class SemanticAnalysisStage implements CompilerStage {
+    process(context: CompilationContext): Promise<void>;
+    /**
+     * Validate parameter type.
+     */
+    private validateParameterType;
+    /**
+     * Coerce a parameter value to its declared type.
+     * CLI args always arrive as strings; this converts them to the correct runtime type
+     * before the value is handed to the template engine.
+     * Already-correct types (e.g. from a JSON params file) are passed through unchanged.
+     */
+    private coerceParameterValue;
+    /**
+     * Validate required metadata fields (id, name, version).
+     */
+    private validateRequiredMetadata;
+    getName(): string;
+}
+
+/**
+ * Template Processing Stage
+ *
+ * Processes Jinja2/Nunjucks templates, package references, and section overrides.
+ * This is the most complex stage, handling:
+ * - Nunjucks template rendering with custom filters (fromcsv, fromjson, tojson, lines)
+ * - Package reference resolution and content injection
+ * - Inheritance processing with section-aware merging
+ * - Enhanced variable substitution with nested property access
+ */
+
+declare class TemplateProcessingStage implements CompilerStage {
+    private sectionProcessor;
+    private nunjucksEnv;
+    constructor();
+    /**
+     * Register custom Jinja2/Nunjucks filters for data transformation.
+     */
+    private registerFilters;
+    /**
+     * Parse CSV string into array of record objects.
+     */
+    private parseCsv;
+    /**
+     * Parse a single CSV line, handling quoted values.
+     */
+    private parseCsvLine;
+    process(context: CompilationContext): Promise<void>;
+    /**
+     * Process package references (e.g., @prefix/path/to/file).
+     */
+    private processPackageReferences;
+    /**
+     * Load a resource from a package.
+     */
+    private loadPackageResource;
+    /**
+     * Process inheritance with section-aware merging.
+     */
+    private processInheritance;
+    /**
+     * Process standalone overrides (without inheritance).
+     */
+    private processStandaloneOverrides;
+    /**
+     * Filter code blocks in content based on context file types.
+     *
+     * When context files are attached (e.g., .ts files), this method filters
+     * the prompt content to only keep code blocks that match those file types.
+     *
+     * Example:
+     * - If context contains "typescript-examples.ts", keep only ```typescript blocks
+     * - Non-code content and unmatched code blocks are preserved as plain text
+     *
+     * @param context - The compilation context with extracted contexts
+     * @param content - The markdown content to filter
+     * @returns Filtered content with only matching code blocks
+     */
+    private filterCodeBlocksByContext;
+    /**
+     * Extract file extensions from context metadata.
+     * Context can be a single file path string or an array of file paths.
+     */
+    private extractContextExtensions;
+    /**
+     * Filter code blocks in markdown content, keeping only those with matching languages.
+     *
+     * @param content - Markdown content with code blocks
+     * @param allowedLanguages - Set of allowed language identifiers (lowercase)
+     * @param verbose - Whether to log filtering actions
+     * @returns Object with filtered content and count of removed blocks
+     */
+    private filterCodeBlocks;
+    /**
+     * Process template with Jinja2/Nunjucks.
+     * Uses a context-aware environment with PrompdLoader to support {% include %}.
+     */
+    private processTemplate;
+    /**
+     * Resolve relative {% include %} paths in content to absolute paths.
+     * This ensures that when parent content is merged into a child file,
+     * the includes still resolve correctly relative to the parent's directory.
+     */
+    private resolveIncludePaths;
+    /**
+     * Register custom filters on a Nunjucks environment.
+     */
+    private registerFiltersOnEnv;
+    /**
+     * Enhanced simple substitution with nested property access.
+     * Supports both single brace {var} and double brace {{var}} syntax for backward compatibility.
+     */
+    private enhancedSimpleSubstitution;
+    /**
+     * Escape special regex characters.
+     */
+    private escapeRegex;
+    /**
+     * Validate that all file references in a parent .prmd's metadata actually exist.
+     * Called during inheritance processing because AssetExtractionStage only runs on
+     * the child file's metadata — the parent is only parsed, never fully compiled.
+     */
+    private validateParentFileReferences;
+    getName(): string;
+}
+
+/**
+ * Code Generation Stage
+ *
+ * Generates output in the target format using registered formatters.
+ */
+
+declare class CodeGenerationStage implements CompilerStage {
+    private formatters;
+    constructor(formatters?: Map<string, OutputFormatter>);
+    /**
+     * Register a new output formatter.
+     */
+    registerFormatter(formatter: OutputFormatter): void;
+    process(context: CompilationContext): Promise<void>;
+    getName(): string;
+}
+
+/**
+ * Section Override Processing
+ *
+ * Provides complete functionality for parsing, validating, and applying
+ * section-based content overrides in prompd template inheritance.
+ *
+ * This is a direct port of the Python CLI's SectionOverrideProcessor.
+ */
+
+declare class SectionOverrideProcessor {
+    /** Max override file size (DoS protection). */
+    private static readonly MAX_OVERRIDE_SIZE;
+    private headingPattern;
+    private sectionIdPattern;
+    constructor();
+    /**
+     * Pattern to detect any section-id comment (for validation)
+     */
+    private detectSectionIdComment;
+    /**
+     * Extract all sections from markdown content.
+     */
+    extractSections(content: string): Map<string, SectionInfo>;
+    /**
+     * Apply overrides and merge parent/child sections.
+     */
+    applyOverrides(parentSections: Map<string, SectionInfo>, childSections: Map<string, SectionInfo>, overrides: Record<string, string | null>, baseDir: string, verbose?: boolean, fileSystem?: IFileSystem): Promise<string>;
+    /**
+     * Load override content from a file.
+     */
+    loadOverrideContent(overridePath: string, baseDir: string, fileSystem?: IFileSystem): Promise<string>;
+    /**
+     * Resolve override path with security checks.
+     */
+    private resolveOverridePath;
+    /**
+     * Generate a section ID from heading text (kebab-case).
+     */
+    private generateSectionId;
+    /**
+     * Validate section ID format.
+     */
+    private validateSectionId;
+}
+
+/**
+ * Custom Nunjucks Loader for Prompd Files
+ *
+ * This loader enables {% include %} directives in .prmd files with compile-aware behavior:
+ * - .prmd files: Parses and returns only the body content (frontmatter stripped)
+ * - Other files (.md, .txt, etc.): Returns raw content as-is
+ *
+ * Features:
+ * - Workspace-aware path resolution (relative to source file)
+ * - Circular include detection
+ * - Compile-on-demand for .prmd files
+ */
+
+/**
+ * Options for the Prompd loader.
+ */
+interface PrompdLoaderOptions {
+    /** File system abstraction (real FS or in-memory) */
+    fileSystem: IFileSystem;
+    /** Base directory for resolving relative paths */
+    baseDir: string;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Maximum include depth to prevent infinite recursion */
+    maxDepth?: number;
+    /** Unique compilation ID for tracking include stack across loader instances */
+    compilationId?: string;
+}
+/**
+ * Loader result with source content and metadata.
+ * Matches Nunjucks LoaderSource interface.
+ */
+interface LoaderResult {
+    src: string;
+    path: string;
+    noCache: boolean;
+}
+/**
+ * Custom Nunjucks loader that handles .prmd files specially.
+ *
+ * When a .prmd file is included, this loader:
+ * 1. Parses the frontmatter
+ * 2. Extracts only the body content
+ * 3. Returns the body for inclusion
+ *
+ * This allows prompts to be composed from other prompts without
+ * duplicating frontmatter or metadata.
+ */
+declare class PrompdLoader extends nunjucks.Loader {
+    async: boolean;
+    private fileSystem;
+    private baseDir;
+    private verbose;
+    private maxDepth;
+    private parser;
+    private compilationId;
+    constructor(options: PrompdLoaderOptions);
+    /**
+     * Get the include stack for this compilation.
+     */
+    private getIncludeStack;
+    /**
+     * Clean up the global stack after compilation is complete.
+     * Should be called when the top-level compilation finishes.
+     */
+    static cleanupCompilation(compilationId: string): void;
+    /**
+     * Get the source content for a template.
+     * This is the main entry point called by Nunjucks.
+     * Throws an error if the file is not found (required by Nunjucks interface).
+     */
+    getSource(name: string): LoaderResult;
+    /**
+     * Load and process a file.
+     * Note: We do NOT remove from stack after loading because Nunjucks will process
+     * the returned content which may contain more includes. The stack tracks the
+     * entire include chain during a single compilation.
+     */
+    private loadFile;
+    /**
+     * Process a .prmd file: parse frontmatter and return only the body.
+     */
+    private processPrompdFile;
+    /**
+     * Resolve a path relative to the base directory.
+     */
+    private resolvePath;
+    /**
+     * Create a child loader for nested includes.
+     * The child loader shares the compilation ID to use the same include stack.
+     */
+    createChildLoader(newBaseDir: string): PrompdLoader;
+    /**
+     * Get the compilation ID for this loader.
+     * Useful for cleanup after compilation.
+     */
+    getCompilationId(): string;
+}
+/**
+ * Create a Nunjucks environment configured with the Prompd loader.
+ *
+ * @param options - Loader options
+ * @returns Configured Nunjucks environment
+ */
+declare function createPrompdEnvironment(options: PrompdLoaderOptions): nunjucks.Environment;
+
+/**
+ * Markdown Output Formatter
+ *
+ * Formats compiled prompts as human-readable markdown with optional YAML frontmatter.
+ */
+
+declare class MarkdownFormatter implements OutputFormatter {
+    name: string;
+    fileExtension: string;
+    mimeType: string;
+    format(compiled: CompiledPrompt): Promise<string>;
+    /**
+     * Clean metadata dictionary for YAML display, converting complex objects to strings.
+     */
+    private cleanMetadataForDisplay;
+}
+
+/**
+ * OpenAI API JSON Formatter
+ *
+ * Formats compiled prompts for OpenAI API consumption with proper message structure.
+ */
+
+declare class OpenAIFormatter implements OutputFormatter {
+    name: string;
+    fileExtension: string;
+    mimeType: string;
+    format(compiled: CompiledPrompt): Promise<string>;
+    /**
+     * Parse all sections from markdown content.
+     */
+    private parseSections;
+    /**
+     * Convert section name to message role.
+     */
+    private sectionToRole;
+}
+
+/**
+ * Anthropic Claude API JSON Formatter
+ *
+ * Formats compiled prompts for Anthropic Claude API with system field and messages.
+ */
+
+declare class AnthropicFormatter implements OutputFormatter {
+    name: string;
+    fileExtension: string;
+    mimeType: string;
+    format(compiled: CompiledPrompt): Promise<string>;
+    /**
+     * Parse all sections from markdown content.
+     */
+    private parseSections;
+    /**
+     * Convert section name to message role.
+     */
+    private sectionToRole;
+}
+
+/**
+ * @prompd/core compiler — environment-agnostic assembly.
+ *
+ * Assembles the browser/server-safe compilation pipeline:
+ *   Lexical -> Dependency -> Semantic -> Template -> CodeGeneration
+ *
+ * The binary AssetExtractionStage (sharp/pdf/exceljs/mammoth) is Node-only and
+ * lives in @prompd/cli, which assembles the full pipeline. Package/inheritance
+ * resolution is injected via IPackageResolver (also Node-only); without it, the
+ * dependency stage emits a diagnostic and single-file compilation still works.
+ */
+
+/**
+ * Default browser/server-safe stage set (no binary asset extraction).
+ */
+declare function createCoreStages(): CompilerStage[];
+/**
+ * High-level compiler. Defaults to the core (browser-safe) stage set; callers
+ * such as @prompd/cli pass a custom stage list (adding asset extraction).
+ */
+declare class PrompdCompiler {
+    protected pipeline: CompilerPipeline;
+    protected securityConfig: SecurityConfig;
+    constructor(options?: {
+        stages?: CompilerStage[];
+        securityConfig?: SecurityConfig;
+    });
+    /**
+     * Compile a .prmd source to a string. Throws CompilationError on errors.
+     */
+    compile(source: string, options?: CompilationOptions): Promise<string>;
+    /**
+     * Compile and return the full context (output + diagnostics, no throw).
+     */
+    compileWithContext(source: string, options?: CompilationOptions): Promise<CompilationContext>;
+    /** Access the underlying pipeline (advanced customization). */
+    getPipeline(): CompilerPipeline;
+}
+/**
+ * Convenience function for quick single-file compilation.
+ */
+declare function compile(source: string, outputFormat?: string, parameters?: Record<string, any>, options?: Omit<CompilationOptions, 'outputFormat' | 'parameters'>): Promise<string>;
+
+/**
+ * Workflow Types - TypeScript interfaces for .pdflow files
+ */
+interface WorkflowFile {
+    version: string;
+    metadata: WorkflowMetadata;
+    parameters?: WorkflowParameter[];
+    using?: PackageAlias[];
+    variables?: WorkflowVariable[];
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    errorHandling?: ErrorHandlingConfig;
+    execution?: ExecutionConfig;
+}
+interface WorkflowMetadata {
+    id: string;
+    name: string;
+    description?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+}
+interface WorkflowParameter {
+    name: string;
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'integer' | 'date' | 'datetime';
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+    enum?: string[];
+    min?: number;
+    max?: number;
+}
+interface PackageAlias {
+    name: string;
+    prefix: string;
+}
+interface WorkflowVariable {
+    name: string;
+    type: string;
+    scope?: 'workflow' | 'node';
+    default?: unknown;
+}
+type WorkflowNodeType = 'trigger' | 'prompt' | 'provider' | 'condition' | 'loop' | 'parallel' | 'merge' | 'transformer' | 'api' | 'tool' | 'tool-call-parser' | 'tool-call-router' | 'agent' | 'chat-agent' | 'guardrail' | 'callback' | 'checkpoint' | 'user-input' | 'error-handler' | 'command' | 'claude-code' | 'workflow' | 'mcp-tool' | 'code' | 'memory' | 'output' | 'web-search' | 'database-query';
+interface WorkflowNode {
+    id: string;
+    type: WorkflowNodeType;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: TriggerNodeData | PromptNodeData | ProviderNodeData | ConditionNodeData | LoopNodeData | ParallelNodeData | MergeNodeData | TransformerNodeData | ApiNodeData | ToolNodeData | ToolCallParserNodeData | ToolCallRouterNodeData | AgentNodeData | ChatAgentNodeData | GuardrailNodeData | CallbackNodeData | UserInputNodeData | ErrorHandlerNodeData | CommandNodeData | ClaudeCodeNodeData | WorkflowNodeData | McpToolNodeData | CodeNodeData | MemoryNodeData | OutputNodeData | WebSearchNodeData;
+    /** Parent node ID for compound nodes (loop/parallel containers) */
+    parentId?: string;
+    /** Extent for child nodes - 'parent' constrains to parent bounds */
+    extent?: 'parent' | [number, number, number, number];
+    /** Whether this node is expandable (container nodes) */
+    expandParent?: boolean;
+    /** Width for resizable container nodes */
+    width?: number;
+    /** Height for resizable container nodes */
+    height?: number;
+    /** Style overrides */
+    style?: Record<string, unknown>;
+}
+interface BaseNodeData {
+    label: string;
+    /** Disable this node to skip it during workflow execution */
+    disabled?: boolean;
+    /** Lock the node to prevent dragging/moving */
+    locked?: boolean;
+    /** Reference to ErrorHandler node for this node's errors */
+    errorHandlerNodeId?: string;
+    /** Override: stop workflow immediately on error (ignores errorHandler) */
+    failFast?: boolean;
+    /** Reference to a Connection for external service access (SSH, Database, HTTP API, etc.) */
+    connectionId?: string;
+    /**
+     * Docking configuration - when this node is docked to another node's handle.
+     * Docked nodes appear as mini 24px circle previews attached to the host handle.
+     */
+    dockedTo?: {
+        /** ID of the host node this node is docked to */
+        nodeId: string;
+        /** Handle ID on the host node (e.g., 'rejected', 'onError', 'output') */
+        handleId: string;
+    };
+    /** Saved width before docking (for restoring on undock) */
+    _preDockWidth?: number;
+    /** Saved height before docking (for restoring on undock) */
+    _preDockHeight?: number;
+    /** Saved position before docking (for restoring on undock) */
+    _preDockPosition?: {
+        x: number;
+        y: number;
+    };
+    [key: string]: unknown;
+}
+/** Node types that can be docked to handles */
+declare const DOCKABLE_NODE_TYPES: WorkflowNodeType[];
+/** Handle configurations that accept docked nodes */
+declare const DOCKABLE_HANDLES: Array<{
+    nodeType: WorkflowNodeType;
+    handleId: string;
+    position: {
+        side: 'left' | 'right' | 'bottom';
+        topPercent: number;
+    };
+    acceptsTypes: WorkflowNodeType[];
+}>;
+/**
+ * TriggerNodeData - Workflow entry point configuration
+ *
+ * Trigger types:
+ * - manual: User clicks "Run" button (default)
+ * - webhook: HTTP POST to a generated endpoint
+ * - schedule: Cron expression or interval-based
+ * - file-watch: File system changes (Electron only)
+ * - event: Internal event from another workflow
+ *
+ * Every workflow should have exactly one TriggerNode as its entry point.
+ * The trigger node has no inputs and one output that starts the workflow.
+ */
+interface TriggerNodeData extends BaseNodeData {
+    /** Type of trigger */
+    triggerType: 'manual' | 'webhook' | 'schedule' | 'file-watch' | 'event';
+    /** Description of when/how this workflow runs */
+    description?: string;
+    /** Webhook path suffix (e.g., '/my-workflow' -> POST /api/webhooks/my-workflow) */
+    webhookPath?: string;
+    /** Secret for HMAC signature validation */
+    webhookSecret?: string;
+    /** HTTP methods to accept (default: POST only) */
+    webhookMethods?: ('GET' | 'POST' | 'PUT')[];
+    /** Whether to require authentication */
+    webhookRequireAuth?: boolean;
+    /** Schedule type */
+    scheduleType?: 'cron' | 'interval';
+    /** Cron expression (e.g., '0 9 * * *' for 9am daily) */
+    scheduleCron?: string;
+    /** Interval in milliseconds (e.g., 60000 for every minute) */
+    scheduleIntervalMs?: number;
+    /** Timezone for cron expressions (default: UTC) */
+    scheduleTimezone?: string;
+    /** Whether schedule is currently active */
+    scheduleEnabled?: boolean;
+    /** Glob patterns for files to watch */
+    fileWatchPaths?: string[];
+    /** Events to trigger on */
+    fileWatchEvents?: ('create' | 'modify' | 'delete')[];
+    /** Debounce time in ms to batch rapid changes */
+    fileWatchDebounceMs?: number;
+    /** Whether to watch subdirectories */
+    fileWatchRecursive?: boolean;
+    /** Event name to listen for */
+    eventName?: string;
+    /** Optional filter expression for event data */
+    eventFilter?: string;
+    /** Schema for data this trigger provides to the workflow */
+    outputSchema?: JsonSchema;
+}
+interface PromptNodeData extends BaseNodeData {
+    /** Source type: 'file' for .prmd file reference, 'raw' for inline text */
+    sourceType?: 'file' | 'raw';
+    /** Path to .prmd file or package reference (used when sourceType is 'file' or undefined) */
+    source: string;
+    /** Raw prompt text (used when sourceType is 'raw') */
+    rawPrompt?: string;
+    /** Reference to a provider node ID, or inline provider name */
+    provider?: string;
+    /** Model name (used with inline provider, ignored if providerNodeId is set) */
+    model?: string;
+    /** Reference to a provider node by ID (preferred over inline provider/model) */
+    providerNodeId?: string;
+    parameters?: Record<string, string>;
+    context?: {
+        previous_output?: 'auto' | string;
+    };
+    outputMapping?: Record<string, string>;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    /** Temperature override (0-2) — overrides frontmatter hint, overridden by provider node */
+    temperature?: number;
+    /** Max tokens override — overrides frontmatter hint, overridden by provider node */
+    maxTokens?: number;
+    /** Guardrail configuration (for content filtering/validation) */
+    guardrail?: {
+        /** Whether the guardrail is enabled */
+        enabled?: boolean;
+        /** Output mode when guardrail passes */
+        outputMode?: 'passthrough' | 'original' | 'reject-message';
+        /** Expected response format from LLM */
+        expectedFormat?: 'json' | 'text';
+        /** JSON field to check for rejection status */
+        rejectionField?: string;
+        /** Pass when field is true or false */
+        passWhen?: 'true' | 'false';
+        /** Action to take when guardrail fails */
+        failAction?: 'error' | 'stop' | 'continue';
+        /** Custom message when rejected */
+        customRejectMessage?: string;
+        /** Custom rejection expression (advanced) - overrides simple field check */
+        rejectionExpression?: string;
+    };
+}
+/**
+ * ProviderNodeData - LLM provider configuration node
+ *
+ * Centralizes provider/model selection so multiple prompt nodes can reference
+ * the same provider configuration. This makes it easy to switch providers
+ * across an entire workflow.
+ */
+interface ProviderNodeData extends BaseNodeData {
+    /** Provider ID (e.g., 'openai', 'anthropic', 'google') */
+    providerId: string;
+    /** Model ID (e.g., 'gpt-4o', 'claude-sonnet-4-20250514') */
+    model: string;
+    /** Optional description for this provider configuration */
+    description?: string;
+    /** Temperature override (0-2) */
+    temperature?: number;
+    /** Max tokens override */
+    maxTokens?: number;
+}
+interface ConditionNodeData extends BaseNodeData {
+    conditions: ConditionBranch[];
+    default?: string;
+}
+interface ConditionBranch {
+    id: string;
+    expression: string;
+    target: string;
+}
+interface LoopNodeData extends BaseNodeData {
+    loopType: 'while' | 'for-each' | 'count';
+    condition?: string;
+    items?: string;
+    itemVariable?: string;
+    count?: number;
+    maxIterations: number;
+    body: string[];
+    onComplete?: string;
+    /** Whether the container is collapsed (hides child nodes) */
+    collapsed?: boolean;
+}
+interface ParallelNodeData extends BaseNodeData {
+    /** Execution mode: 'broadcast' (container) or 'fork' (edge-based branches) */
+    mode: 'broadcast' | 'fork';
+    /** Number of output handles in fork mode */
+    forkCount?: number;
+    /** Custom labels for fork branches (indexed by branch number) */
+    forkLabels?: string[];
+    branches: ParallelBranch[];
+    waitFor: 'all' | 'any' | 'race';
+    mergeStrategy: 'object' | 'array' | 'first';
+    /** Whether the container is collapsed (hides child nodes) */
+    collapsed?: boolean;
+}
+interface ParallelBranch {
+    id: string;
+    label?: string;
+    nodes: string[];
+}
+interface MergeNodeData extends BaseNodeData {
+    inputs: string[];
+    mergeAs: 'object' | 'array';
+    /**
+     * Merge mode determines how the merge node behaves:
+     * - 'wait': Waits for all connected inputs to have outputs before executing (default)
+     * - 'transform': Executes immediately with whatever inputs are available (router/passthrough)
+     */
+    mode?: 'wait' | 'transform';
+}
+/**
+ * TransformerNodeData - Data transformation node
+ *
+ * Transform, reshape, or filter data using templates with {{ variable }} syntax.
+ * Supports multiple transform modes for different use cases.
+ *
+ * Transform Modes:
+ * - template: JSON template with {{ }} variable interpolation
+ * - jq: JQ-style query expressions (future)
+ * - javascript: Inline JS expression (sandboxed)
+ *
+ * Variables:
+ * - {{ previous_output }} - Output from the connected input node
+ * - {{ node_id.property }} - Access specific node outputs
+ * - {{ workflow.param_name }} - Workflow parameters
+ */
+interface TransformerNodeData extends BaseNodeData {
+    /** Transform mode */
+    mode: 'template' | 'jq' | 'expression';
+    /** JSON template string with {{ variable }} syntax (for template mode) */
+    template?: string;
+    /** JQ-style query expression (for jq mode, future) */
+    jqExpression?: string;
+    /** JavaScript expression that returns transformed value (for expression mode) */
+    expression?: string;
+    /** Input variable name (defaults to 'input') */
+    inputVariable?: string;
+    /** Whether to pass through unchanged if transform fails */
+    passthroughOnError?: boolean;
+    /** Description of what this transform does */
+    description?: string;
+    transform?: string;
+}
+interface ApiNodeData extends BaseNodeData {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    url: string;
+    headers?: Record<string, string>;
+    body?: string;
+    retryPolicy?: RetryPolicy;
+}
+/**
+ * ToolNodeData - Unified tool execution node
+ *
+ * Supports five tool types:
+ * - function: Call a registered function/callback provided to the workflow executor
+ * - mcp: Call a tool exposed by an MCP (Model Context Protocol) server
+ * - http: Make an HTTP request (similar to ApiNodeData but unified interface)
+ * - command: Execute a whitelisted shell command (npm, git, python, etc.)
+ * - code: Execute code snippets (TypeScript/JavaScript, Python, or C#)
+ *
+ * Use cases:
+ * - Database lookups
+ * - Code execution
+ * - External API integration
+ * - MCP-compatible AI tools
+ * - Custom business logic
+ * - Shell command execution
+ * - Data transformation via code
+ */
+interface ToolNodeData extends BaseNodeData {
+    /** Tool type determines how the tool is invoked */
+    toolType: 'function' | 'mcp' | 'http' | 'command' | 'code';
+    /** Tool name - for function/mcp types, this identifies the tool to call */
+    toolName: string;
+    /** Description shown in the node and used for documentation */
+    description?: string;
+    /** Input parameters - template expressions supported */
+    parameters?: Record<string, unknown>;
+    /** Parameter schema for validation and UI generation */
+    parameterSchema?: {
+        type: 'object';
+        properties?: Record<string, {
+            type: string;
+            description?: string;
+            default?: unknown;
+            enum?: string[];
+        }>;
+        required?: string[];
+    };
+    /** HTTP method (only for http type) */
+    httpMethod?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    /** URL template (only for http type) */
+    httpUrl?: string;
+    /** HTTP headers (only for http type) */
+    httpHeaders?: Record<string, string>;
+    /** Request body template (only for http type) */
+    httpBody?: string;
+    /** MCP server URL (only for mcp type) */
+    mcpServerUrl?: string;
+    /** MCP server name/identifier (alternative to URL for configured servers) */
+    mcpServerName?: string;
+    /** The executable to run (must be in allowed list or custom commands) */
+    commandExecutable?: string;
+    /** Action/subcommand (e.g., 'run' for npm, 'status' for git) */
+    commandAction?: string;
+    /** Arguments template (supports {{ }} expressions) */
+    commandArgs?: string;
+    /** Working directory (relative to workspace) */
+    commandCwd?: string;
+    /** Whether this command requires user approval before execution */
+    commandRequiresApproval?: boolean;
+    /** Custom command ID (references CustomCommandConfig from connections) */
+    customCommandId?: string;
+    /** Programming language for code execution */
+    codeLanguage?: 'typescript' | 'javascript' | 'python' | 'csharp';
+    /** The code snippet to execute */
+    codeSnippet?: string;
+    /** Variable name for previous_output (default: 'input') */
+    codeInputVariable?: string;
+    /** For TS/JS: execution context */
+    codeExecutionContext?: 'isolated' | 'main';
+    /** Timeout in milliseconds */
+    timeout?: number;
+    /** Retry policy for failed executions */
+    retryPolicy?: RetryPolicy;
+    /** Transform the result before passing to next node */
+    outputTransform?: string;
+}
+/**
+ * ToolCallParserNodeData - Parse LLM output for tool call requests
+ *
+ * This node detects and extracts tool calls from LLM responses, enabling
+ * agentic workflows where the LLM decides which tools to call.
+ *
+ * Supported formats:
+ * - openai: OpenAI function calling format (tool_calls array)
+ * - anthropic: Anthropic tool_use blocks
+ * - xml: XML-style <tool_call> tags
+ * - json: Generic JSON with configurable field names
+ * - auto: Automatically detect format
+ *
+ * Output structure:
+ * {
+ *   hasToolCall: boolean,
+ *   toolName: string | null,
+ *   toolParameters: Record<string, unknown> | null,
+ *   remainingText: string,  // Text after tool call extraction
+ *   rawToolCall: unknown,   // Original tool call data
+ *   format: string          // Detected format
+ * }
+ */
+interface ToolCallParserNodeData extends BaseNodeData {
+    /** Format to parse - 'auto' will attempt to detect */
+    format: 'auto' | 'openai' | 'anthropic' | 'xml' | 'json';
+    /** For 'json' format: field name containing the tool name */
+    jsonToolNameField?: string;
+    /** For 'json' format: field name containing the parameters */
+    jsonParametersField?: string;
+    /** For 'xml' format: tag name for tool calls (default: 'tool_call') */
+    xmlTagName?: string;
+    /** List of valid tool names - if provided, only these will be recognized */
+    allowedTools?: string[];
+    /** What to do if no tool call is found */
+    noToolCallBehavior: 'passthrough' | 'error' | 'default';
+    /** Default tool to use if noToolCallBehavior is 'default' */
+    defaultTool?: string;
+    defaultParameters?: Record<string, unknown>;
+}
+/**
+ * ToolCallRouterNodeData - Container node for grouping Tool nodes
+ *
+ * This node acts as a container that groups Tool nodes together and routes
+ * tool calls from Agent nodes to the appropriate Tool node based on tool name.
+ *
+ * Usage:
+ * 1. Create a ToolCallRouter node on the canvas
+ * 2. Drag Tool nodes inside the container (they become children via parentId)
+ * 3. Connect Agent's onCheckpoint handle to router's toolCall input
+ * 4. Connect router's toolResult output back to Agent's toolResult input
+ *
+ * The router automatically collects tool schemas from child Tool nodes and
+ * dispatches tool calls to the matching Tool node for execution.
+ */
+interface ToolCallRouterNodeData extends BaseNodeData {
+    /** How tool calls are matched to Tool nodes */
+    routingMode: 'name-match' | 'pattern' | 'fallback';
+    /** Behavior when no Tool node matches the requested tool name */
+    onNoMatch: 'error' | 'passthrough' | 'fallback-tool';
+    /** ID of a Tool node inside this router to use as fallback */
+    fallbackToolId?: string;
+    /** Whether the container is collapsed (hides child nodes) */
+    collapsed?: boolean;
+}
+interface OutputNodeData extends BaseNodeData {
+    outputSchema?: JsonSchema;
+    result?: unknown;
+}
+/**
+ * ErrorHandlerNodeData - Workflow-level error handling configuration
+ *
+ * Error handling is configured as a **workflow-level node** that other nodes
+ * reference by ID (similar to how nodes reference Provider nodes). This avoids
+ * cluttering the graph with inline error edges.
+ *
+ * Nodes reference an ErrorHandler via `errorHandlerNodeId` in BaseNodeData.
+ * When an error occurs, the executor routes it to the referenced ErrorHandler
+ * for retry, fallback, or notification handling.
+ *
+ * Strategies:
+ * - retry: Attempt the operation again with backoff
+ * - fallback: Return a fallback value or execute a fallback node
+ * - notify: Send notification (webhook, log) and continue
+ * - ignore: Swallow the error and continue with null/undefined
+ * - rethrow: Re-throw the error to stop execution
+ *
+ * Visual representation:
+ * - Displayed in "Error Handlers" section of NodePalette
+ * - Rose/red color theme
+ * - Dashed border to indicate "config node" vs "flow node"
+ * - No edges - referenced by ID from other nodes
+ */
+interface ErrorHandlerNodeData extends BaseNodeData {
+    /** Error handling strategy */
+    strategy: 'retry' | 'fallback' | 'notify' | 'ignore' | 'rethrow';
+    /** Retry policy */
+    retry?: {
+        /** Maximum number of retry attempts */
+        maxAttempts: number;
+        /** Initial backoff delay in milliseconds */
+        backoffMs: number;
+        /** Backoff multiplier for exponential backoff (e.g., 2 for doubling) */
+        backoffMultiplier?: number;
+        /** Maximum backoff delay in milliseconds */
+        maxBackoffMs?: number;
+        /** Error codes/patterns that should trigger a retry (empty = retry all) */
+        retryOn?: string[];
+        /** Error codes/patterns that should NOT trigger a retry */
+        noRetryOn?: string[];
+    };
+    /** Fallback value or node when all retries exhausted or strategy is 'fallback' */
+    fallback?: {
+        /** Type of fallback */
+        type: 'value' | 'template' | 'node';
+        /** Static value to return (when type is 'value') */
+        value?: unknown;
+        /** Template expression to evaluate (when type is 'template') */
+        template?: string;
+        /** Node ID to execute as fallback (when type is 'node') */
+        nodeId?: string;
+    };
+    /** Notification settings */
+    notify?: {
+        /** Webhook URL to POST error details */
+        webhookUrl?: string;
+        /** HTTP headers for webhook */
+        webhookHeaders?: Record<string, string>;
+        /** Whether to include stack trace in notification */
+        includeStack?: boolean;
+        /** Whether to include node input/context in notification */
+        includeContext?: boolean;
+        /** Custom message template (supports {{ error.message }}, {{ node.id }}, etc.) */
+        messageTemplate?: string;
+    };
+    /** Logging settings */
+    log?: {
+        /** Log level for this error handler */
+        level: 'error' | 'warn' | 'info' | 'debug';
+        /** Whether to include the node data that caused the error */
+        includeNodeData?: boolean;
+        /** Whether to include input data */
+        includeInput?: boolean;
+    };
+    /** Only handle errors matching these conditions */
+    conditions?: {
+        /** Error codes/patterns to match (regex supported) */
+        errorCodes?: string[];
+        /** Error message patterns to match (regex supported) */
+        messagePatterns?: string[];
+        /** Node types this handler applies to */
+        nodeTypes?: WorkflowNodeType[];
+    };
+    /** Description of this error handler */
+    description?: string;
+}
+/**
+ * CheckpointNodeData - Configurable observation point for workflow execution
+ *
+ * The Checkpoint node is a flexible observation/control point that can:
+ * - Log data to console and execution history
+ * - Pause execution in debug mode (breakpoint)
+ * - Gate execution requiring human approval (production use)
+ * - Send webhook notifications to external systems
+ *
+ * Pre-Node Aware: The checkpoint detects what type of node feeds into it
+ * and can subscribe to specific events from that node (e.g., Agent iterations).
+ *
+ * All behaviors are toggleable and can be combined.
+ */
+interface CallbackNodeData extends BaseNodeData {
+    /** Custom name for this checkpoint (shown in logs/UI) */
+    checkpointName?: string;
+    /** Description of what this checkpoint monitors */
+    description?: string;
+    /** Log checkpoint data to console/stdout */
+    logToConsole?: boolean;
+    /** Store checkpoint data in execution history for later review */
+    logToHistory?: boolean;
+    /** Pause execution when running in debug mode (breakpoint) */
+    pauseInDebug?: boolean;
+    /** Require human approval before continuing (works in production) */
+    requireApproval?: boolean;
+    /** Send HTTP webhook notification */
+    sendWebhook?: boolean;
+    /** Include the previous node's output in checkpoint data */
+    capturePreviousOutput?: boolean;
+    /** Include timestamp and execution duration */
+    captureTimestamp?: boolean;
+    /** Include full execution context (all variables, workflow state) */
+    captureFullContext?: boolean;
+    /** Custom message template (supports {{ }} expressions) */
+    message?: string;
+    /** Title shown in approval dialog */
+    approvalTitle?: string;
+    /** Instructions for the reviewer */
+    approvalInstructions?: string;
+    /** Timeout in ms to wait for approval (0 = wait indefinitely) */
+    approvalTimeoutMs?: number;
+    /** What to do if approval times out */
+    approvalTimeoutAction?: 'continue' | 'fail' | 'skip';
+    /** Webhook URL to POST checkpoint data */
+    webhookUrl?: string;
+    /** Custom headers to include in webhook request */
+    webhookHeaders?: Record<string, string>;
+    /** Whether to wait for webhook acknowledgment before continuing */
+    webhookWaitForAck?: boolean;
+    /** Timeout in ms to wait for acknowledgment (0 = no timeout) */
+    webhookAckTimeoutMs?: number;
+    /**
+     * Detected type of the node connected to this checkpoint's input.
+     * This is auto-populated and used to show relevant options in the UI.
+     * @readonly - Set automatically, not user-configurable
+     */
+    _detectedSourceType?: WorkflowNodeType;
+    /** Include full iteration history from agent execution */
+    agentCaptureIterations?: boolean;
+    /** Include conversation/message history */
+    agentCaptureConversation?: boolean;
+    /** Include tool call details and results */
+    agentCaptureToolCalls?: boolean;
+    /** Include agent's thinking/reasoning (if available) */
+    agentCaptureThinking?: boolean;
+    /**
+     * Event types to listen for when connected to an Agent's onCheckpoint handle.
+     * If empty or undefined, listens to all event types.
+     */
+    listenTo?: AgentCheckpointEventType[];
+    /** Capture current iteration index */
+    loopCaptureIteration?: boolean;
+    /** Capture loop variable value */
+    loopCaptureVariable?: boolean;
+    /** Include the compiled prompt that was sent to the LLM */
+    promptCaptureCompiled?: boolean;
+    /** Include token usage stats */
+    promptCaptureTokens?: boolean;
+    /** @deprecated Use individual behavior toggles instead */
+    mode?: 'passthrough' | 'pause' | 'report';
+    /** @deprecated Use capturePreviousOutput instead */
+    includePreviousOutput?: boolean;
+    /** @deprecated Use captureFullContext instead */
+    includeNextNodeInfo?: boolean;
+    /** @deprecated Use webhookWaitForAck instead */
+    waitForAck?: boolean;
+    /** @deprecated Use webhookAckTimeoutMs instead */
+    ackTimeoutMs?: number;
+    /** @deprecated Use agentCaptureIterations instead */
+    agentIncludeIterationHistory?: boolean;
+    /** @deprecated Use agentCaptureConversation instead */
+    agentIncludeConversationHistory?: boolean;
+    /** @deprecated Use agentCaptureToolCalls instead */
+    agentIncludeToolCalls?: boolean;
+}
+/**
+ * UserInputNodeData - Pause workflow and collect user input
+ *
+ * This node pauses execution and waits for user input. It can be used for:
+ * - Interactive chat loops (user message -> LLM -> user message -> ...)
+ * - Human-in-the-loop approval workflows
+ * - Data collection mid-workflow
+ * - Debugging with manual input injection
+ *
+ * The node provides context (previous output, conversation history) to help
+ * the user understand what input is needed.
+ */
+interface UserInputNodeData extends BaseNodeData {
+    /** Prompt message shown to the user (supports {{ }} template expressions) */
+    prompt: string;
+    /** Type of input to collect */
+    inputType: 'text' | 'textarea' | 'choice' | 'confirm' | 'number';
+    /** Choices for 'choice' input type */
+    choices?: string[];
+    /** Placeholder text for input field */
+    placeholder?: string;
+    /** Default value for the input */
+    defaultValue?: string;
+    /** Whether input is required to continue */
+    required?: boolean;
+    /** Whether to show the previous node's output to the user */
+    showContext?: boolean;
+    /** Custom template for displaying context (supports {{ previous_output }}, {{ variables }}) */
+    contextTemplate?: string;
+    /** Timeout in ms (0 = wait indefinitely) */
+    timeout?: number;
+}
+/**
+ * CommandNodeData - Execute whitelisted shell commands
+ *
+ * This node executes shell commands with proper security controls:
+ * - Commands can be whitelisted by admin
+ * - Arguments are passed safely (not interpolated into command string)
+ * - Output is captured and parsed
+ * - Requires approval for sensitive operations
+ */
+interface CommandNodeData extends BaseNodeData {
+    /** Command template (supports {{ }} expressions for arguments) */
+    command: string;
+    /** Command arguments (safer than string interpolation) */
+    args?: string[];
+    /** Working directory (relative to workspace) */
+    cwd?: string;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Output parsing format */
+    outputFormat: 'text' | 'json' | 'lines';
+    /** Whether this command requires user approval before execution */
+    requiresApproval?: boolean;
+    /** Description shown in approval dialog */
+    approvalMessage?: string;
+}
+/**
+ * WebSearchNodeData - Search the web via configurable provider
+ *
+ * Uses the connection system to configure which search provider to use.
+ * Supports SearXNG (free, no key), Brave Search, and Tavily.
+ */
+interface WebSearchNodeData extends BaseNodeData {
+    /** Search query template (supports {{ }} expressions) */
+    query: string;
+    /** Maximum number of results to return (default: 5) */
+    resultCount?: number;
+    /** Search provider: 'searxng' (free, default), 'brave', or 'tavily' */
+    provider?: 'searxng' | 'brave' | 'tavily';
+    /** API key for Brave/Tavily providers */
+    apiKey?: string;
+    /** SearXNG instance URL (default: https://search.sapti.me) */
+    instanceUrl?: string;
+}
+/**
+ * ClaudeCodeNodeData - Claude Code agent with SSH support for remote development
+ *
+ * This node encapsulates a full Claude Code agent that can:
+ * - Connect to local or remote systems via SSH
+ * - Execute multi-turn development tasks
+ * - Use file editing, command execution, and web tools
+ * - Stream progress back to the workflow
+ */
+interface ClaudeCodeNodeData extends BaseNodeData {
+    /** Connection type and configuration */
+    connection: {
+        type: 'local' | 'ssh';
+        /** SSH settings (when type === 'ssh') */
+        ssh?: {
+            /** Reference to SSH connection from Connections Panel */
+            connectionId?: string;
+            /** Or inline config (deprecated - use connectionId) */
+            host?: string;
+            port?: number;
+            username?: string;
+            authMethod?: 'key' | 'agent';
+            keyPath?: string;
+        };
+    };
+    /** Task configuration */
+    task: {
+        /** Main task description (supports {{ }} template expressions) */
+        prompt: string;
+        /** Optional system prompt override */
+        systemPrompt?: string;
+        /** Working directory on target (relative or absolute) */
+        workingDirectory?: string;
+        /** Files to include as context (glob patterns) */
+        contextFiles?: string[];
+    };
+    /** Execution constraints */
+    constraints: {
+        /** Maximum agent turns before forcing completion */
+        maxTurns?: number;
+        /** Allowed tool categories */
+        allowedTools?: ('read' | 'write' | 'execute' | 'web')[];
+        /** Blocked file patterns (security) */
+        blockedPaths?: string[];
+        /** Require approval for write operations */
+        requireApprovalForWrites?: boolean;
+        /** Timeout for entire execution (ms) */
+        timeoutMs?: number;
+    };
+    /** Output configuration */
+    output: {
+        /** What to return as node output */
+        format: 'final-response' | 'full-conversation' | 'files-changed' | 'structured';
+        /** For structured output - JSON schema to enforce */
+        schema?: JsonSchema;
+        /** Include execution metadata (tokens, duration, etc.) */
+        includeMetadata?: boolean;
+    };
+}
+/**
+ * WorkflowNodeData - Invoke another .pdflow as a sub-workflow
+ *
+ * This enables workflow composition:
+ * - Call reusable workflow modules
+ * - Pass parameters and receive outputs
+ * - Support for recursive workflows (with depth limit)
+ */
+interface WorkflowNodeData extends BaseNodeData {
+    /** Source workflow path or package reference */
+    source: string;
+    /** Parameter mapping (input to sub-workflow) */
+    parameters: Record<string, string>;
+    /** Output mapping (sub-workflow output to this node's output) */
+    outputMapping?: Record<string, string>;
+    /** Execution options */
+    timeout?: number;
+    /** Whether to pass parent workflow variables */
+    inheritVariables?: boolean;
+    /** Maximum recursion depth (to prevent infinite loops) */
+    maxDepth?: number;
+}
+/**
+ * McpToolNodeData - Execute tools from external MCP servers
+ *
+ * This node connects to external MCP servers and executes their tools.
+ * Unlike the generic Tool node, this is specifically for MCP protocol
+ * and supports MCP-specific features like resources and prompts.
+ */
+interface McpToolNodeData extends BaseNodeData {
+    /** Reference to MCP server connection from Connections Panel */
+    connectionId?: string;
+    /** Or inline MCP server config (deprecated - use connectionId) */
+    serverConfig?: {
+        serverUrl?: string;
+        serverName?: string;
+        transport?: 'stdio' | 'http' | 'websocket';
+    };
+    /** Tool name to execute */
+    toolName: string;
+    /** Parameter mapping (supports {{ }} expressions) */
+    parameters: Record<string, string>;
+    /** Timeout for tool execution (ms) */
+    timeoutMs?: number;
+    /** Whether to include tool result in conversation context */
+    includeInContext?: boolean;
+}
+/**
+ * CodeNodeData - Execute code snippets in various languages
+ *
+ * Supports:
+ * - TypeScript/JavaScript: Runs in isolated VM context or via temp file
+ * - Python: Executes via python -c or temp file
+ * - C#: Executes via dotnet-script or compiled temp file
+ *
+ * The previous_output is available as a variable (default name: 'input')
+ */
+interface CodeNodeData extends BaseNodeData {
+    /** Programming language */
+    language: 'typescript' | 'javascript' | 'python' | 'csharp';
+    /** The code to execute */
+    code: string;
+    /** Variable name for the input (previous_output), default: 'input' */
+    inputVariable?: string;
+    /** For TS/JS: run in isolated VM or main context */
+    executionContext?: 'isolated' | 'main';
+    /** Timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+    /** Description of what this code does */
+    description?: string;
+}
+/**
+ * MemoryNodeData - Configurable memory storage node
+ *
+ * Supports multiple memory patterns:
+ * - 'kv': Key-value store for passing state between nodes
+ * - 'conversation': Message history with sliding window for chat context
+ * - 'cache': Time-based caching for expensive operations
+ *
+ * Memory is scoped to workflow execution by default, but can be
+ * persisted across executions via the 'persistent' flag.
+ *
+ * Handles:
+ * - input (left) - Data to store or key to retrieve
+ * - output (right) - Retrieved value or confirmation
+ */
+/** Memory operation type */
+type MemoryOperation = 'get' | 'set' | 'delete' | 'clear' | 'list' | 'append';
+/** Operations available per memory mode */
+declare const MEMORY_OPERATIONS_BY_MODE: Record<string, MemoryOperation[]>;
+interface MemoryNodeData extends BaseNodeData {
+    /** Memory operation mode */
+    mode: 'kv' | 'conversation' | 'cache';
+    /**
+     * Operations this node can perform (multi-select).
+     * When multiple operations are enabled, the input data's `operation` field
+     * determines which to execute, or defaults to the first enabled operation.
+     */
+    operations: MemoryOperation[];
+    /**
+     * Key for the value (supports {{ }} template expressions).
+     * Used in kv and cache modes.
+     */
+    key?: string;
+    /**
+     * Value to store (supports {{ }} template expressions).
+     * Used with 'set' operation. If not provided, uses input data.
+     */
+    value?: string;
+    /**
+     * Default value to return if key doesn't exist.
+     * Used with 'get' operation.
+     */
+    defaultValue?: string;
+    /**
+     * Conversation/thread identifier (supports {{ }} expressions).
+     * Allows multiple separate conversation histories.
+     */
+    conversationId?: string;
+    /**
+     * Role for the message being appended ('user', 'assistant', 'system').
+     * Used with 'append' operation in conversation mode.
+     */
+    messageRole?: 'user' | 'assistant' | 'system';
+    /**
+     * Maximum messages to retain in sliding window.
+     * Older messages are removed when limit is exceeded.
+     * Set to 0 for unlimited.
+     */
+    maxMessages?: number;
+    /**
+     * Include system messages in the sliding window count.
+     * If false, system messages are always retained.
+     */
+    includeSystemInWindow?: boolean;
+    /**
+     * Time-to-live in seconds for cached values.
+     * After TTL expires, 'get' returns defaultValue or undefined.
+     * Set to 0 for no expiration.
+     */
+    ttlSeconds?: number;
+    /**
+     * Refresh TTL on read (sliding expiration).
+     * If true, reading a value resets its TTL.
+     */
+    refreshOnRead?: boolean;
+    /**
+     * Memory scope:
+     * - 'execution': Cleared when workflow execution completes (default)
+     * - 'workflow': Persists across executions of this workflow
+     * - 'global': Shared across all workflows (use with caution)
+     */
+    scope?: 'execution' | 'workflow' | 'global';
+    /**
+     * Namespace to isolate this memory from others.
+     * Useful for avoiding key collisions in global scope.
+     */
+    namespace?: string;
+    /**
+     * What to output after the operation:
+     * - 'value': The retrieved/stored value
+     * - 'success': Boolean indicating success
+     * - 'metadata': Object with value, timestamp, ttl info
+     * - 'passthrough': Pass input through unchanged
+     */
+    outputMode?: 'value' | 'success' | 'metadata' | 'passthrough';
+}
+interface DatabaseQueryNodeData extends BaseNodeData {
+    /** Reference to a saved database connection */
+    connectionId: string;
+    /** Query type determines how the query is executed */
+    queryType: 'select' | 'insert' | 'update' | 'delete' | 'raw' | 'aggregate';
+    /** SQL query, MongoDB JSON query document, or Redis command */
+    query: string;
+    /** JSON-encoded parameter array for parameterized queries (SQL only) */
+    parameters?: string;
+    /** MongoDB collection name (only for MongoDB connections) */
+    collection?: string;
+    /** Maximum rows to return (default 1000) */
+    maxRows?: number;
+    /** Query timeout in milliseconds (default 30000) */
+    timeoutMs?: number;
+}
+/**
+ * CustomCommandConfig - User-defined allowed commands
+ *
+ * Stored in the Connections panel, these allow users to whitelist
+ * additional shell commands for use in Tool nodes.
+ */
+interface CustomCommandConfig {
+    /** Unique identifier */
+    id: string;
+    /** The executable name (e.g., 'cargo', 'terraform', 'kubectl') */
+    executable: string;
+    /** Allowed actions/subcommands (if empty, any args allowed with validation) */
+    allowedActions?: string[];
+    /** Human-readable description */
+    description?: string;
+    /** Whether to require approval before execution */
+    requiresApproval: boolean;
+    /** When this command was added */
+    addedAt: number;
+}
+/**
+ * Built-in allowed executables for command tool type
+ */
+declare const BUILTIN_COMMAND_EXECUTABLES: readonly [{
+    readonly executable: "npm";
+    readonly description: "Node.js package manager";
+    readonly actions: readonly ["run", "install", "test", "build", "start"];
+}, {
+    readonly executable: "npx";
+    readonly description: "Execute npm packages";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "node";
+    readonly description: "Node.js runtime";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "yarn";
+    readonly description: "Yarn package manager";
+    readonly actions: readonly ["run", "install", "test", "build", "start"];
+}, {
+    readonly executable: "pnpm";
+    readonly description: "PNPM package manager";
+    readonly actions: readonly ["run", "install", "test", "build", "start"];
+}, {
+    readonly executable: "git";
+    readonly description: "Version control";
+    readonly actions: readonly ["status", "add", "commit", "push", "pull", "log", "diff", "branch"];
+}, {
+    readonly executable: "python";
+    readonly description: "Python interpreter";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "python3";
+    readonly description: "Python 3 interpreter";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "pip";
+    readonly description: "Python package manager";
+    readonly actions: readonly ["install", "list", "show"];
+}, {
+    readonly executable: "prompd";
+    readonly description: "Prompd CLI";
+    readonly actions: readonly ["compile", "run", "validate", "package"];
+}, {
+    readonly executable: "dotnet";
+    readonly description: ".NET CLI";
+    readonly actions: readonly ["build", "run", "test", "publish"];
+}, {
+    readonly executable: "tsc";
+    readonly description: "TypeScript compiler";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "eslint";
+    readonly description: "JavaScript linter";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "prettier";
+    readonly description: "Code formatter";
+    readonly actions: readonly [];
+}, {
+    readonly executable: "echo";
+    readonly description: "Print text";
+    readonly actions: readonly [];
+}];
+/**
+ * AgentIterationRecord - Record of a single agent iteration for debugging
+ */
+interface AgentIterationRecord {
+    iteration: number;
+    timestamp: number;
+    llmInput: {
+        systemPrompt: string;
+        conversationHistory: Array<{
+            role: string;
+            content: string;
+        }>;
+    };
+    llmOutput: {
+        response: string;
+        hasToolCall: boolean;
+        toolName?: string;
+        toolParams?: Record<string, unknown>;
+    };
+    toolExecution?: {
+        toolName: string;
+        parameters: Record<string, unknown>;
+        result: unknown;
+        error?: string;
+        durationMs: number;
+    };
+    durationMs: number;
+}
+/**
+ * AgentCheckpointEvent - Events emitted by Agent nodes during execution
+ *
+ * Agent nodes emit these events through their onCheckpoint handle, allowing
+ * connected Callback nodes to observe and react to agent execution.
+ *
+ * Event types:
+ * - toolCall: Agent is requesting a tool execution
+ * - iteration: Agent completed an iteration of the ReAct loop
+ * - thinking: Agent emitted reasoning/chain-of-thought
+ * - error: An error occurred during agent execution
+ * - complete: Agent finished execution
+ */
+type AgentCheckpointEventType = 'toolCall' | 'iteration' | 'thinking' | 'error' | 'complete';
+interface AgentCheckpointEvent {
+    /** Type of event */
+    type: AgentCheckpointEventType;
+    /** When the event occurred */
+    timestamp: number;
+    /** Current iteration number (1-indexed) */
+    iteration: number;
+    /** Node ID of the agent that emitted this event */
+    agentNodeId: string;
+    /** Event-specific data */
+    data: ToolCallEventData | IterationEventData | ThinkingEventData | ErrorEventData | CompleteEventData;
+}
+/** Data for 'toolCall' events - agent is requesting tool execution */
+interface ToolCallEventData {
+    toolName: string;
+    parameters: Record<string, unknown>;
+    /** Tool schema for validation (if available) */
+    schema?: {
+        type: 'object';
+        properties?: Record<string, {
+            type: string;
+            description?: string;
+        }>;
+        required?: string[];
+    };
+}
+/** Data for 'iteration' events - agent completed a ReAct loop iteration */
+interface IterationEventData {
+    iterationNumber: number;
+    llmInput: {
+        systemPrompt: string;
+        messages: Array<{
+            role: string;
+            content: string;
+        }>;
+    };
+    llmOutput: {
+        response: string;
+        hasToolCall: boolean;
+        toolName?: string;
+        toolParams?: Record<string, unknown>;
+    };
+    durationMs: number;
+}
+/** Data for 'thinking' events - agent's reasoning/chain-of-thought */
+interface ThinkingEventData {
+    thought: string;
+}
+/** Data for 'error' events - an error occurred */
+interface ErrorEventData {
+    message: string;
+    code?: string;
+    stack?: string;
+    recoverable: boolean;
+}
+/** Data for 'complete' events - agent finished execution */
+interface CompleteEventData {
+    finalResponse: string;
+    totalIterations: number;
+    totalDurationMs: number;
+    stopReason: 'max-iterations' | 'stop-phrase' | 'no-tool-call' | 'error' | 'completed';
+}
+/**
+ * AgentNodeData - Autonomous AI agent with tool-use loop
+ *
+ * Implements a ReAct-style (Reasoning + Acting) agent that:
+ * 1. Sends a prompt to an LLM with tool definitions
+ * 2. Parses the response for tool calls
+ * 3. Executes requested tools
+ * 4. Feeds results back to the LLM
+ * 5. Repeats until LLM provides final answer or max iterations reached
+ *
+ * This encapsulates the common "agentic loop" pattern into a single node.
+ *
+ * Debug Mode:
+ * When debugConfig.debugMode is enabled, the agent emits detailed traces at
+ * internal checkpoints and can optionally pause at each checkpoint (like breakpoints).
+ * Iteration history is stored in the node output for downstream analysis.
+ */
+interface AgentNodeData extends BaseNodeData {
+    /** System prompt that defines the agent's behavior and available tools */
+    systemPrompt: string;
+    /** Initial user message / task description (supports {{ }} template expressions) */
+    userPrompt: string;
+    /** Reference to a Provider node by ID (preferred - enables centralized config) */
+    providerNodeId?: string;
+    /** Inline LLM provider (fallback if no providerNodeId) */
+    provider?: string;
+    /** Inline model (fallback if no providerNodeId) */
+    model?: string;
+    /** Tool definitions available to the agent (legacy - prefer toolRouterNodeId) */
+    tools: AgentTool[];
+    /** Reference to a ToolCallRouter node by ID (preferred over inline tools) */
+    toolRouterNodeId?: string;
+    /** Maximum number of tool-use iterations before stopping */
+    maxIterations: number;
+    /** Format for tool calls in LLM responses */
+    toolCallFormat: 'auto' | 'openai' | 'anthropic' | 'xml' | 'json';
+    /** What to output when agent completes */
+    outputMode: 'final-response' | 'full-conversation' | 'last-tool-result';
+    /** Whether to include conversation history in context */
+    includeHistory?: boolean;
+    /** Stop phrases that indicate the agent is done (in addition to no tool call) */
+    stopPhrases?: string[];
+    /** Temperature for LLM calls */
+    temperature?: number;
+    /** Timeout per LLM call in ms */
+    llmTimeout?: number;
+}
+/**
+ * GuardrailNodeData - Input validation node with success/rejected branching
+ *
+ * Validates input against a system prompt and routes to success or rejected paths.
+ * Uses an LLM to evaluate the input and determine if it passes validation.
+ *
+ * Handles:
+ * - input (left, top) - Data to validate
+ * - rejected (left, bottom) - Source handle for routing rejected input back
+ *
+ * Outputs:
+ * - output (right) - Validated input passes through on success
+ *
+ * The guardrail evaluates the input using the configured provider and system prompt,
+ * then uses the passExpression to determine if the result indicates pass or fail.
+ */
+interface GuardrailNodeData extends BaseNodeData {
+    /** System prompt that defines the validation criteria */
+    systemPrompt: string;
+    /** Reference to a Provider node by ID for LLM evaluation */
+    providerNodeId?: string;
+    /** Inline provider (fallback if no providerNodeId) */
+    provider?: string;
+    /** Inline model (fallback if no providerNodeId) */
+    model?: string;
+    /**
+     * Expression to evaluate pass/fail from the LLM response.
+     * Supports {{ }} template syntax with access to the parsed response.
+     *
+     * Examples:
+     * - "{{ score >= 0.8 }}" - Pass if score is 0.8 or higher
+     * - "{{ !rejected }}" - Pass if rejected is falsy
+     * - "{{ score >= 0.8 && !rejected }}" - Combined conditions
+     *
+     * The expression is evaluated against the parsed JSON response from the LLM.
+     * If the LLM returns a non-JSON response, it's wrapped as { response: "..." }
+     */
+    passExpression?: string;
+    /**
+     * Numeric threshold for pass/fail (alternative to passExpression).
+     * If the LLM response contains a 'score' field, this threshold is used.
+     * Input passes if score >= scoreThreshold.
+     */
+    scoreThreshold?: number;
+    /** Temperature for LLM evaluation (default: 0 for deterministic) */
+    temperature?: number;
+    /** Timeout for LLM call in ms */
+    timeout?: number;
+    /** Description of what this guardrail validates */
+    description?: string;
+}
+/**
+ * ChatAgentNodeData - Composite container for conversational AI agent pattern
+ *
+ * Bundles the common pattern of: User Input → Guardrail → AI Agent ↔ Tool Router
+ * into a single, configurable node with checkpoints at each stage.
+ *
+ * When collapsed: Shows as a single node with key metrics
+ * When expanded: Shows all internal nodes for detailed editing
+ *
+ * Internal nodes (auto-created):
+ * - UserInput: Collects user message
+ * - Guardrail: Validates input before processing
+ * - Agent: AI agent with ReAct loop
+ * - ToolRouter: Container for available tools
+ *
+ * Handles:
+ * - input (left) - Workflow data / conversation context
+ * - output (right) - Final agent response
+ * - rejected (left, bottom) - Guardrail rejection path
+ */
+interface ChatAgentNodeData extends BaseNodeData {
+    /** Whether the container is collapsed (shows as single node) */
+    collapsed?: boolean;
+    /** Saved dimensions when expanded */
+    _savedWidth?: number;
+    _savedHeight?: number;
+    /**
+     * Agent prompt source type:
+     * - 'raw': Inline text prompt (agentSystemPrompt field)
+     * - 'file': Reference to .prmd file or package (agentPromptSource field)
+     */
+    agentPromptSourceType?: 'raw' | 'file';
+    /** System prompt for the AI agent (used when agentPromptSourceType is 'raw' or not set) */
+    agentSystemPrompt: string;
+    /** Source file for agent prompt (used when agentPromptSourceType is 'file') - local .prmd path or package reference */
+    agentPromptSource?: string;
+    /** Initial user prompt template (supports {{ }} expressions) */
+    agentUserPrompt?: string;
+    /** Reference to Provider node for LLM */
+    providerNodeId?: string;
+    /** Inline provider (fallback) */
+    provider?: string;
+    /** Inline model (fallback) */
+    model?: string;
+    /** Maximum ReAct loop iterations */
+    maxIterations?: number;
+    /** Tool call format detection */
+    toolCallFormat?: 'auto' | 'openai' | 'anthropic' | 'xml' | 'json';
+    /** What to output when complete */
+    outputMode?: 'final-response' | 'full-conversation' | 'last-tool-result';
+    /** Temperature for LLM calls */
+    temperature?: number;
+    /**
+     * Loop mode for the chat agent:
+     * - 'single-turn': Execute once and return (no looping)
+     * - 'multi-turn': Continue until stop condition or max iterations
+     * - 'until-complete': Loop until agent signals completion
+     * - 'user-driven': Loop back for user input after each response
+     */
+    loopMode?: 'single-turn' | 'multi-turn' | 'until-complete' | 'user-driven';
+    /**
+     * Condition expression to continue looping (for multi-turn mode).
+     * Evaluated after each iteration. Loop continues while this is true.
+     * Uses {{ }} template syntax with access to iteration context.
+     *
+     * Examples:
+     * - "{{ iteration < 5 }}" - Continue for 5 iterations
+     * - "{{ !response.includes('DONE') }}" - Until response contains DONE
+     * - "{{ tools_used > 0 }}" - Continue if tools were used
+     */
+    loopCondition?: string;
+    /**
+     * Stop phrases that signal the agent is done.
+     * If the response contains any of these, the loop terminates.
+     */
+    stopPhrases?: string[];
+    /**
+     * Whether to prompt for user input after each agent response (for user-driven mode).
+     * When true, the loop pauses for user input before continuing.
+     */
+    loopOnUserInput?: boolean;
+    /**
+     * Minimum number of iterations before stop condition is checked.
+     * Ensures the agent runs at least this many times.
+     */
+    minIterations?: number;
+    /**
+     * Delay between iterations in milliseconds.
+     * Useful for rate limiting or allowing processing time.
+     */
+    iterationDelayMs?: number;
+    /** Whether guardrail is enabled */
+    guardrailEnabled?: boolean;
+    /** Guardrail system prompt */
+    guardrailSystemPrompt?: string;
+    /** Reference to Provider node for guardrail LLM (can be different from agent's provider) */
+    guardrailProviderNodeId?: string;
+    /** Inline provider for guardrail (fallback if no guardrailProviderNodeId) */
+    guardrailProvider?: string;
+    /** Inline model for guardrail (fallback if no guardrailProviderNodeId) */
+    guardrailModel?: string;
+    /** Temperature for guardrail LLM evaluation (default: 0 for deterministic) */
+    guardrailTemperature?: number;
+    /** Pass/fail expression */
+    guardrailPassExpression?: string;
+    /** Score threshold alternative */
+    guardrailScoreThreshold?: number;
+    /** Output mode when guardrail passes */
+    guardrailOutputMode?: 'passthrough' | 'original' | 'reject-message';
+    /** Expected response format from guardrail LLM */
+    guardrailExpectedFormat?: 'json' | 'text';
+    /** JSON field to check for rejection status */
+    guardrailRejectionField?: string;
+    /** Pass when field is true or false */
+    guardrailPassWhen?: 'true' | 'false';
+    /** Action to take when guardrail fails */
+    guardrailFailAction?: 'error' | 'stop' | 'continue';
+    /** Custom message when rejected */
+    guardrailCustomRejectMessage?: string;
+    /** Custom rejection expression (advanced) - overrides simple field check */
+    guardrailRejectionExpression?: string;
+    /** Whether to prompt for user input at start of each iteration */
+    userInputEnabled?: boolean;
+    /** Prompt message shown to user */
+    userInputPrompt?: string;
+    /** Input type */
+    userInputType?: 'text' | 'textarea' | 'choice' | 'confirm';
+    /** Placeholder text */
+    userInputPlaceholder?: string;
+    /** Whether to show previous context to user */
+    userInputShowContext?: boolean;
+    /** Inline tool definitions (for simple cases) */
+    tools?: AgentTool[];
+    /** Reference to external ToolRouter node (for complex tool setups) */
+    toolRouterNodeId?: string;
+    /** Checkpoint settings for different stages */
+    checkpoints?: {
+        /** On user input received */
+        onUserInput?: ChatAgentCheckpointConfig;
+        /** Before guardrail validation */
+        beforeGuardrail?: ChatAgentCheckpointConfig;
+        /** After guardrail (pass or reject) */
+        afterGuardrail?: ChatAgentCheckpointConfig;
+        /** Before each agent iteration */
+        onIterationStart?: ChatAgentCheckpointConfig;
+        /** After each agent iteration */
+        onIterationEnd?: ChatAgentCheckpointConfig;
+        /** When agent requests a tool call */
+        onToolCall?: ChatAgentCheckpointConfig;
+        /** After tool execution returns */
+        onToolResult?: ChatAgentCheckpointConfig;
+        /** When agent completes */
+        onAgentComplete?: ChatAgentCheckpointConfig;
+    };
+    /** IDs of internal nodes (auto-created, managed by the container) */
+    _internalNodes?: {
+        userInputId?: string;
+        guardrailId?: string;
+        agentId?: string;
+        toolRouterId?: string;
+    };
+}
+/**
+ * Checkpoint configuration for ChatAgentNode stages
+ */
+interface ChatAgentCheckpointConfig {
+    /** Whether this checkpoint is enabled */
+    enabled: boolean;
+    /** Pause execution at this point (debug mode) */
+    pause?: boolean;
+    /** Log to console */
+    logToConsole?: boolean;
+    /** Log to execution history */
+    logToHistory?: boolean;
+    /** Require approval to continue */
+    requireApproval?: boolean;
+    /** Send webhook notification */
+    sendWebhook?: boolean;
+    webhookUrl?: string;
+    /** Custom message template */
+    message?: string;
+    /** Include full context in checkpoint data */
+    includeFullContext?: boolean;
+}
+/**
+ * Tool definition for an agent
+ */
+interface AgentTool {
+    /** Unique tool name */
+    name: string;
+    /** Description shown to the LLM */
+    description: string;
+    /** JSON schema for tool parameters */
+    parameters?: {
+        type: 'object';
+        properties?: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+    /** How this tool is executed */
+    toolType: 'function' | 'http' | 'mcp' | 'workflow' | 'command' | 'code' | 'web-search' | 'database-query';
+    /** For HTTP tools */
+    httpConfig?: {
+        method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+        url: string;
+        headers?: Record<string, string>;
+        bodyTemplate?: string;
+    };
+    /** For MCP tools */
+    mcpConfig?: {
+        serverUrl?: string;
+        serverName?: string;
+    };
+    /** For workflow tools - execute a sub-workflow */
+    workflowConfig?: {
+        workflowPath: string;
+    };
+    /** For command tools - execute shell commands */
+    commandConfig?: {
+        executable: string;
+        action?: string;
+        args?: string;
+        cwd?: string;
+        requiresApproval?: boolean;
+    };
+    /** For code tools - execute code snippets */
+    codeConfig?: {
+        language: 'typescript' | 'javascript' | 'python' | 'csharp';
+        snippet: string;
+        inputVariable?: string;
+        executionContext?: 'isolated' | 'main';
+    };
+}
+/**
+ * WorkflowEdge uses React Flow's standard edge format directly.
+ * This eliminates conversion overhead and makes debugging easier.
+ */
+interface WorkflowEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string;
+    targetHandle?: string;
+    animated?: boolean;
+    label?: string;
+}
+interface ErrorHandlingConfig {
+    onError: 'continue' | 'stop' | 'retry';
+    retryPolicy?: RetryPolicy;
+    fallbackNode?: string;
+}
+interface RetryPolicy {
+    enabled: boolean;
+    maxRetries: number;
+    backoffMs: number;
+    backoffMultiplier?: number;
+}
+interface ExecutionConfig {
+    timeout?: number;
+    parallelism?: {
+        enabled: boolean;
+        maxConcurrency: number;
+    };
+    logging?: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        includeTimings?: boolean;
+    };
+    caching?: {
+        enabled: boolean;
+        ttlMs: number;
+    };
+}
+interface JsonSchema {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'integer';
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    enum?: unknown[];
+}
+interface WorkflowValidationError {
+    nodeId?: string;
+    connectionId?: string;
+    field?: string;
+    message: string;
+    code: string;
+}
+interface WorkflowValidationWarning {
+    nodeId?: string;
+    message: string;
+    code: string;
+}
+type WorkflowExecutionStatus = 'idle' | 'running' | 'paused' | 'completed' | 'failed';
+type NodeExecutionStatus = 'pending' | 'running' | 'paused' | 'completed' | 'failed' | 'skipped';
+interface WorkflowExecutionState {
+    workflowId: string;
+    status: WorkflowExecutionStatus;
+    currentNodeId?: string;
+    nodeStates: Record<string, NodeExecutionState>;
+    nodeOutputs: Record<string, unknown>;
+    variables: Record<string, unknown>;
+    errors: WorkflowExecutionError[];
+    startTime?: number;
+    endTime?: number;
+    /** Memory storage for MemoryNode operations */
+    memory?: {
+        /** Key-value store (by namespace or root) */
+        kv: Record<string, unknown>;
+        /** Conversation histories (by conversation ID) */
+        conversation: Record<string, unknown[]>;
+        /** Cache entries with TTL (by namespace or root) */
+        cache: Record<string, unknown>;
+    };
+}
+interface NodeExecutionState {
+    nodeId: string;
+    status: NodeExecutionStatus;
+    startTime?: number;
+    endTime?: number;
+    output?: unknown;
+    error?: string;
+    retryCount: number;
+    streamingContent?: string;
+}
+interface WorkflowExecutionError {
+    nodeId?: string;
+    message: string;
+    stack?: string;
+    timestamp: number;
+}
+interface WorkflowResult {
+    success: boolean;
+    output?: unknown;
+    nodeOutputs: Record<string, unknown>;
+    errors: WorkflowExecutionError[];
+    metrics: {
+        totalDuration: number;
+        nodeMetrics: Record<string, {
+            duration: number;
+            tokens?: number;
+        }>;
+    };
+}
+/**
+ * WorkflowConnectionType - Types of external connections managed in the Connections panel
+ *
+ * Connections are managed in a dedicated panel (not canvas nodes) to scale to
+ * hundreds of connection types. Nodes reference connections by ID.
+ */
+type WorkflowConnectionType = 'ssh' | 'database' | 'http-api' | 'slack' | 'github' | 'mcp-server' | 'websocket' | 'custom';
+type WorkflowConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+/**
+ * WorkflowConnection - External service connection managed in the Connections panel
+ *
+ * Stored separately from workflow nodes - connections are workflow-scoped resources
+ * that can be referenced by multiple nodes via connectionId.
+ */
+interface WorkflowConnection {
+    id: string;
+    name: string;
+    type: WorkflowConnectionType;
+    status: WorkflowConnectionStatus;
+    lastConnected?: number;
+    lastError?: string;
+    config: WorkflowConnectionConfig;
+}
+/** Union type for all connection configs */
+type WorkflowConnectionConfig = SSHConnectionConfig | DatabaseConnectionConfig | HttpApiConnectionConfig | SlackConnectionConfig | GitHubConnectionConfig | McpServerConnectionConfig | WebSocketConnectionConfig | CustomConnectionConfig;
+interface SSHConnectionConfig {
+    type: 'ssh';
+    host: string;
+    port?: number;
+    username: string;
+    authMethod: 'key' | 'password' | 'agent';
+    keyPath?: string;
+}
+interface DatabaseConnectionConfig {
+    type: 'database';
+    dbType: 'postgresql' | 'mysql' | 'mongodb' | 'redis' | 'sqlite';
+    host?: string;
+    port?: number;
+    database: string;
+    username?: string;
+    ssl?: boolean;
+    connectionString?: string;
+}
+interface HttpApiConnectionConfig {
+    type: 'http-api';
+    baseUrl: string;
+    authType: 'none' | 'bearer' | 'api-key' | 'basic' | 'oauth2';
+    headers?: Record<string, string>;
+    apiKeyHeader?: string;
+}
+interface SlackConnectionConfig {
+    type: 'slack';
+    workspace: string;
+    defaultChannel?: string;
+}
+interface GitHubConnectionConfig {
+    type: 'github';
+    owner?: string;
+    repo?: string;
+    baseUrl?: string;
+}
+interface McpServerConnectionConfig {
+    type: 'mcp-server';
+    serverUrl: string;
+    serverName: string;
+    transport: 'stdio' | 'http' | 'websocket';
+}
+interface WebSocketConnectionConfig {
+    type: 'websocket';
+    url: string;
+    protocols?: string[];
+    headers?: Record<string, string>;
+}
+interface CustomConnectionConfig {
+    type: 'custom';
+    [key: string]: unknown;
+}
+
+/**
+ * Workflow Parser - Parse and validate .pdflow JSON files
+ * Converts between .pdflow format and React Flow format
+ */
+
+interface WorkflowCanvasNode {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: BaseNodeData;
+    parentId?: string;
+    extent?: 'parent';
+    width?: number;
+    height?: number;
+    selected?: boolean;
+    dragging?: boolean;
+    [key: string]: unknown;
+}
+interface WorkflowCanvasEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceHandle?: string | null;
+    targetHandle?: string | null;
+    animated?: boolean;
+    label?: string;
+    selected?: boolean;
+    [key: string]: unknown;
+}
+interface ParsedWorkflow {
+    file: WorkflowFile;
+    nodes: WorkflowCanvasNode[];
+    edges: WorkflowCanvasEdge[];
+    errors: WorkflowValidationError[];
+    warnings: WorkflowValidationWarning[];
+}
+/**
+ * Parse a .pdflow JSON string into a ParsedWorkflow
+ */
+declare function parseWorkflow(json: string): ParsedWorkflow;
+/**
+ * Serialize a workflow back to JSON string
+ */
+declare function serializeWorkflow(file: WorkflowFile, nodes: WorkflowCanvasNode[], edges: WorkflowCanvasEdge[]): string;
+/**
+ * Create an empty workflow file
+ */
+declare function createEmptyWorkflow(): WorkflowFile;
+/**
+ * Create a new workflow node
+ *
+ * IMPORTANT: When adding a new node type, you MUST update THREE places:
+ * 1. This switch statement (createWorkflowNode) - add a case with default data
+ * 2. getDefaultLabel() below - add the default label for the node type
+ * 3. nodes/index.ts - add the component to nodeTypes registry
+ *
+ * If you only add to nodes/index.ts without adding a case here, the node
+ * will render as "UNKNOWN: <type>" because createWorkflowNode falls back
+ * to a generic tool node for unhandled types.
+ */
+declare function createWorkflowNode(type: WorkflowNodeType, position: {
+    x: number;
+    y: number;
+}, id?: string): WorkflowNode;
+/**
+ * Build execution order using topological sort
+ *
+ * Important: Child nodes (nodes with parentId) are EXCLUDED from the main execution order.
+ * They are executed by their parent container node (loop, parallel), not by the main executor.
+ *
+ * Excludes:
+ * - Internal back-edges that would create cycles (e.g., loop-end -> container)
+ * - Child nodes that belong to container nodes (they have parentId set)
+ */
+declare function getExecutionOrder(workflow: ParsedWorkflow): string[];
+
+/**
+ * Centralized Workflow Validation System
+ *
+ * Validates workflow structure, edges, and node configurations.
+ * Returns errors (blocking issues) and warnings (non-blocking suggestions).
+ */
+
+interface ValidationResult {
+    errors: WorkflowValidationError[];
+    warnings: WorkflowValidationWarning[];
+    isValid: boolean;
+}
+/**
+ * Validates an entire workflow
+ */
+declare function validateWorkflow(workflow: WorkflowFile): ValidationResult;
+/**
+ * Quick validation for real-time feedback (lighter weight)
+ */
+declare function validateWorkflowQuick(workflow: WorkflowFile): Pick<ValidationResult, 'isValid'>;
+
+export { type AgentCheckpointEvent, type AgentCheckpointEventType, type AgentIterationRecord, type AgentNodeData, type AgentTool, AnthropicFormatter, type ApiNodeData, type AsyncFileBackend, BUILTIN_COMMAND_EXECUTABLES, type BaseNodeData, CODE_EXTENSIONS, CONTENT_TYPES, type CallbackNodeData, type ChatAgentCheckpointConfig, type ChatAgentNodeData, type ClaudeCodeNodeData, CodeGenerationStage, type CodeNodeData, type CommandNodeData, CompilationContext, type CompilationDiagnostic, CompilationError, type CompilationOptions, CompilationStage, type CompiledPrompt, CompilerPipeline, type CompilerStage, type CompleteEventData, type ConditionBranch, type ConditionNodeData, type Config, type CustomCommandConfig, type CustomConnectionConfig, type CustomProvider, DEFAULT_SECURITY_CONFIG, DOCKABLE_HANDLES, DOCKABLE_NODE_TYPES, type DatabaseConnectionConfig, type DatabaseQueryNodeData, DependencyResolutionStage, EXTENSION_TO_LANGUAGE, EXTENSION_TO_LANGUAGE_ALIASES, type ErrorEventData, type ErrorHandlerNodeData, type ErrorHandlingConfig, type ExecuteOptions, type ExecutionConfig, type GitHubConnectionConfig, type GuardrailNodeData, type HttpApiConnectionConfig, HybridFileSystem, type IFileSystem, type IPackageResolver, type IterationEventData, type JsonSchema, type LLMResponse, LexicalAnalysisStage, type LoopNodeData, MEMORY_OPERATIONS_BY_MODE, MarkdownFormatter, type McpServerConnectionConfig, type McpToolNodeData, MemoryFileSystem, type MemoryNodeData, type MemoryOperation, type MergeNodeData, type NodeExecutionState, type NodeExecutionStatus, OpenAIFormatter, type OutputFormatter, type OutputNodeData, PACKAGE_TYPE_DIRS, PROMPD_EXTENSIONS, type PackageAlias, type PackageType, type ParallelBranch, type ParallelNodeData, ParseError, type ParsedWorkflow, PrompdCompiler, PrompdError, type PrompdFile, PrompdLoader, type PrompdMetadata, type PrompdParameter, PrompdParser, type PromptNodeData, type ProviderConfig, type ProviderNodeData, type RegistryConfig, type ResolvePackageOptions, type ResolvedPackage, type RetryPolicy, type SSHConnectionConfig, type SectionInfo, SectionOverrideProcessor, type SecurityConfig, SecurityError, SemanticAnalysisStage, type SlackConnectionConfig, TOOL_DEPLOY_DIRS, TemplateProcessingStage, type ThinkingEventData, type ToolCallEventData, type ToolCallParserNodeData, type ToolCallRouterNodeData, type ToolNodeData, type TransformerNodeData, type TriggerNodeData, type UserInputNodeData, type UsingPackage, VALID_PACKAGE_TYPES, ValidationError, type ValidationIssue, type ValidationResult, type WebSearchNodeData, type WebSocketConnectionConfig, type WorkflowConnection, type WorkflowConnectionConfig, type WorkflowConnectionStatus, type WorkflowConnectionType, type WorkflowEdge, type WorkflowExecutionError, type WorkflowExecutionState, type WorkflowExecutionStatus, type WorkflowFile, type WorkflowMetadata, type WorkflowNode, type WorkflowNodeData, type WorkflowNodeType, type WorkflowParameter, type WorkflowResult, type WorkflowValidationError, type WorkflowValidationWarning, type WorkflowVariable, basenamePosix, compile, createCoreStages, createEmptyWorkflow, createPrompdEnvironment, createWorkflowNode, dirnamePosix, extname, getContentType, getExecutionOrder, getInstallDirForType, getLanguageAliasesForExtension, getLanguageForExtension, isAbsolutePosix, isPrompdFile, isValidPackageReference, isValidPackageType, joinPosix, needsFrontmatterProtection, normalizePosix, parsePackageReference, parsePackageReferenceWithPath, parseWorkflow, resolvePackageFile, resolvePosix, serializeWorkflow, stripFilePath, validateWorkflow, validateWorkflowQuick };