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

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

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

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Shared validateWorkflowDefinition helper.
+ *
+ * Single entry point for validating a workflow definition:
+ *
+ *   Layer 1 — DAG structure (delegated to DAGManager.validate()):
+ *     duplicate node IDs, missing dependencies, cycles, empty node IDs.
+ *
+ *   Layer 2 — Template-reference **contracts** (Task #4298, see
+ *     `template-contract-validator.ts`): does a `{{nodes.X.<field>}}`
+ *     reference actually match the output shape of node `X`? This is what
+ *     catches the `wheels-validate-v1` class of bug where an agent prompt
+ *     read `.result` off a **tool** node (which has no such field) and the
+ *     engine silently substituted an empty string.
+ *
+ * Wraps everything in a defensive try/catch so callers (workflow_add tool,
+ * `workflow add` CLI, workflow_validate tool, TaskTagPlugin.extractWorkflow)
+ * always get a consistent `{ valid, errors, warnings, infos }` shape — even
+ * when the input is garbage.
+ *
+ * Backward compatibility: the original `{ valid, errors }` shape is preserved;
+ * `warnings` / `infos` are additive. Only `error`-severity findings affect
+ * `valid`.
+ */
+import { type TemplateContractFinding } from "./template-contract-validator";
+export interface ValidateWorkflowResult {
+    valid: boolean;
+    /** Blocking problems. Non-empty ⟺ `valid === false`. */
+    errors: string[];
+    /**
+     * Advisory problems (Task #4298). These do NOT make the definition invalid,
+     * but the workflow-creator loop is expected to address them.
+     */
+    warnings?: string[];
+    /** Informational hints (e.g. references to non-upstream nodes). */
+    infos?: string[];
+    /** Structured findings, for callers that want machine-readable detail. */
+    findings?: TemplateContractFinding[];
+}
+export interface ValidateWorkflowOptions {
+    /**
+     * Skip the Layer-2 template-contract checks. Defaults to `false`.
+     *
+     * Provided for callers that only care about structural validity (e.g. a
+     * pre-flight DAG sanity check while a definition is still being authored
+     * incrementally).
+     */
+    skipTemplateContracts?: boolean;
+}
+/**
+ * Validate a workflow definition (structure + template contracts).
+ *
+ * @param definition - The workflow definition object (must have a `nodes` array).
+ * @param options - Optional behaviour switches.
+ * @returns `{ valid, errors, warnings, infos, findings }` — never throws.
+ */
+export declare function validateWorkflowDefinition(definition: unknown, options?: ValidateWorkflowOptions): ValidateWorkflowResult;

package/dist/env/workflow/utils/validation-rules.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Validation Rules for Workflow Recovery
+ *
+ * Defines types for validation errors, results, and recovery plans.
+ */
+/**
+ * Validation error types for workflow recovery
+ */
+export declare enum ValidationErrorType {
+    /** Variable referenced by node input is missing */
+    MISSING_VARIABLE = "MISSING_VARIABLE",
+    /** Parallel branch is incomplete */
+    INCOMPLETE_PARALLEL = "INCOMPLETE_PARALLEL",
+    /** Condition branch cannot be determined */
+    AMBIGUOUS_BRANCH = "AMBIGUOUS_BRANCH",
+    /** Loop state is lost */
+    LOOP_STATE_LOST = "LOOP_STATE_LOST",
+    /** Nested workflow state is invalid */
+    NESTED_WORKFLOW_INVALID = "NESTED_WORKFLOW_INVALID",
+    /** Node execution state is inconsistent */
+    NODE_STATE_INCONSISTENT = "NODE_STATE_INCONSISTENT",
+    /** Critical dependency is missing */
+    MISSING_DEPENDENCY = "MISSING_DEPENDENCY"
+}
+/**
+ * Suggested actions for recovery
+ */
+export declare enum SuggestedAction {
+    /** Re-run the workflow from the beginning */
+    RE_RUN = "RE_RUN",
+    /** Confirm with user before proceeding */
+    CONFIRM = "CONFIRM",
+    /** Skip the problematic node */
+    SKIP = "SKIP",
+    /** Provide the missing value */
+    PROVIDE_VALUE = "PROVIDE_VALUE",
+    /** Ignore the warning and proceed */
+    IGNORE = "IGNORE"
+}
+/**
+ * Validation error detail
+ */
+export interface ValidationError {
+    /** Error type */
+    type: ValidationErrorType;
+    /** Node ID where error occurred */
+    nodeId: string;
+    /** Human-readable error description */
+    description: string;
+    /** Suggested action to resolve */
+    suggestedAction: SuggestedAction;
+    /** Additional context information */
+    context?: Record<string, unknown>;
+}
+/**
+ * Result of validation
+ */
+export interface ValidationResult {
+    /** Whether the workflow can be safely resumed */
+    isValid: boolean;
+    /** List of validation errors */
+    errors: ValidationError[];
+    /** List of warnings (non-critical issues) */
+    warnings: string[];
+}
+/**
+ * Recovery plan for resuming a workflow
+ */
+export interface RecoveryPlan {
+    /** Whether the workflow can be resumed */
+    canResume: boolean;
+    /** Node ID where execution should resume */
+    resumePoint: string;
+    /** List of completed node IDs */
+    completedNodes: string[];
+    /** List of pending node IDs */
+    pendingNodes: string[];
+    /** List of node IDs that will be skipped */
+    skippedNodes: string[];
+    /** Validation errors encountered */
+    validationErrors: ValidationError[];
+    /** Human-readable summary */
+    summary: string;
+}
+/**
+ * Execution state of a workflow
+ */
+export interface ExecutionState {
+    /** Set of completed node IDs */
+    completedNodes: Set<string>;
+    /** Set of in-progress node IDs */
+    inProgressNodes: Set<string>;
+    /** Set of pending node IDs */
+    pendingNodes: Set<string>;
+    /** Map of node ID to output */
+    nodeOutputs: Map<string, unknown>;
+    /** Map of node ID to input */
+    nodeInputs: Map<string, unknown>;
+    /** Map of variable name to value */
+    variables: Map<string, unknown>;
+    /** Loop iteration counts */
+    loopCounts: Map<string, number>;
+}

package/dist/env/workflow/utils/workflow-message-metadata.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared helpers for workflow session message metadata.
+ * Ensures nodeId / workflowNodeId and _workflowNodeMetadata are consistent.
+ */
+export type WorkflowNodeMessageType = 'workflow.node.start' | 'workflow.node.end' | 'workflow.node.interrupt' | 'workflow.node.resume' | 'workflow.node.call' | 'workflow.node.result';
+/**
+ * Resolve node id from message metadata (supports nodeId and workflowNodeId).
+ */
+export declare function getWorkflowNodeIdFromMetadata(metadata: Record<string, unknown> | undefined | null): string | undefined;
+/**
+ * Build base workflow node message metadata with nodeId aliases.
+ */
+export declare function buildWorkflowNodeMetadata(type: WorkflowNodeMessageType, nodeId: string, nodeType: string, extra?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Patch agentSessionId onto an existing metadata object and optional parts.
+ */
+export declare function patchAgentSessionIdOnMessage(metadata: Record<string, unknown> | undefined, parts: unknown[] | undefined, agentSessionId: string): {
+    metadata: Record<string, unknown>;
+    parts?: unknown[];
+};

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

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Workflow Definition Sanitization
+ *
+ * Task #2926: Persist fixes for shell-script bugs that previously lived only as
+ * runtime SQLite patches (e.g. `query-wiki-iteration-tasks v2.4.0` had three
+ * known issues that the previous subagent patched directly in the database).
+ *
+ * Without this sanitizer, those patches vanish on any reinstall / reimport /
+ * fresh db migration. The sanitize step runs inside the service layer
+ * (`WorkflowService.createWorkflow` / `updateWorkflow`) before the definition
+ * is JSON-stringified and written to SQLite, so every persistence path is
+ * covered.
+ *
+ * Currently fixed defects (all match bugs observed in Task #2924):
+ *
+ *   1. `python3 -c "; <module> ..."` — leading `; ` inside the `-c` argument
+ *      causes `SyntaxError: invalid syntax` (Python rejects a statement
+ *      starting with `;`).  Fix: drop the leading `; `.
+ *
+ *   2. Bare `$RANDOM` reference inside a script run by `dash` (the default
+ *      `/bin/sh` on Debian/Ubuntu) with `set -u` enabled throws
+ *      `RANDOM: parameter not set`.  Fix: expand to `${RANDOM:-0}`.
+ *
+ * The sanitizer is intentionally conservative:
+ *   - It mutates only string values reachable through known command fields
+ *     (`config.command`, `config.inputs.command`, `config.input.command`,
+ *     `config.message`, `config.inputs.message`).
+ *   - It walks `depends_on` and arbitrary nested config (e.g. retry block
+ *     does not contain shell but other extensions might).
+ *   - It returns a deep clone to keep callers from sharing references with
+ *     SQLite-bound objects.
+ *
+ * Anything that doesn't match a known bad pattern is left untouched.
+ */
+import type { WorkflowDefinition } from '../types/workflow';
+/**
+ * Public entry point. Returns a sanitized deep-clone of the workflow
+ * definition (the original object is not mutated).
+ */
+export declare function sanitizeWorkflowDefinition(definition: WorkflowDefinition): WorkflowDefinition;
+/**
+ * Apply the known shell-script bug fixes to a single string.
+ *
+ * Bug 1: `python3 -c "; <stmt>"` (or `python3 -c ";<stmt>"`) — drop leading
+ * `; ` so Python sees a valid statement.
+ *
+ * Bug 2: bare `$RANDOM` reference — wrap with `${RANDOM:-0}` so `dash` under
+ * `set -u` doesn't blow up.  Already-safe forms (`${RANDOM:-x}`,
+ * `${RANDOM}`, `$RANDOM9`, `${RANDOM:-}`) are left alone.
+ */
+export declare function sanitizeShellScript(script: string): string;