dsh-browser-playwright-codex 0.8.2 → 0.9.0

package/lib/script-runner.js

@@ -0,0 +1,280 @@
+import { BrowserError } from "./errors.js";
+import { describeStep, ScriptStepError } from "./script-steps.js";
+/** How long a `urlContains` wait may take before the step fails. */
+const URL_WAIT_TIMEOUT_MS = 15000;
+/** How often a `urlContains` wait re-reads the URL. */
+const URL_WAIT_INTERVAL_MS = 250;
+/**
+ * Resolve a target to a ref using the freshest snapshot.
+ *
+ * A given ref is passed through untouched: the session validates it, and its
+ * REF_NOT_FOUND is the honest answer when the page moved on. A label is matched
+ * by accessible name — exact first, then a unique case-insensitive substring —
+ * and an ambiguous or missing label fails loudly instead of clicking the first
+ * thing that looks close, because a script that silently clicks the wrong node
+ * is worse than one that stops.
+ */
+/** Every node in the tree, depth first: the labels a script targets live at any depth. */
+function flatten(nodes) {
+    const out = [];
+    const walk = (list) => {
+        for (const node of list) {
+            out.push(node);
+            if (node.children.length > 0)
+                walk(node.children);
+        }
+    };
+    walk(nodes);
+    return out;
+}
+function resolveRef(snapshot, step, target) {
+    if (target.ref !== undefined)
+        return target.ref;
+    const wanted = String(target.text ?? '').trim();
+    // Walk the tree, not just the roots: a textbox sits three levels down under
+    // paragraph > form, and matching only the roots found nothing (real run on
+    // httpbin.org/forms/post, 2026-11-14).
+    const nodes = flatten(snapshot.nodes).filter((node) => node.ref !== undefined);
+    const exact = nodes.filter((node) => node.name.trim() === wanted);
+    if (exact.length === 1)
+        return String(exact[0]?.ref);
+    if (exact.length > 1) {
+        throw new ScriptStepError(step, String(exact.length) + ' elements are labelled "' + wanted + '"; use a ref instead');
+    }
+    const lower = wanted.toLowerCase();
+    const partial = nodes.filter((node) => node.name.toLowerCase().includes(lower));
+    if (partial.length === 1)
+        return String(partial[0]?.ref);
+    if (partial.length > 1) {
+        throw new ScriptStepError(step, String(partial.length) + ' elements contain "' + wanted + '"; use a ref instead');
+    }
+    throw new ScriptStepError(step, 'nothing on the page is labelled "' + wanted + '"');
+}
+/** Index of the step that failed, when the error came from a target lookup. */
+function failedStepOf(error) {
+    const withStep = error;
+    return typeof withStep.step === 'number' ? withStep.step : undefined;
+}
+/**
+ * Execute every step in order, stopping at the first failure.
+ *
+ * @param session - The calling session's live browser.
+ * @param steps - Steps already validated by `parseScriptSteps`.
+ * @param options - Cancellation and the snapshot callback.
+ * @returns What ran, what failed, and the last working snapshot.
+ */
+export async function runScript(session, steps, options = {}) {
+    const outcomes = [];
+    const { signal } = options;
+    // A snapshot taken before the first step, so a `text` target in step 1 has
+    // something to resolve against without spending an extra tool call.
+    // Lazy: a script that starts with navigate must not pay for a snapshot of
+    // the page it is about to replace.
+    let snapshot;
+    const current = async () => {
+        if (snapshot === undefined) {
+            snapshot = await session.snapshot({ interactiveOnly: false });
+            options.onSnapshot?.(await current());
+        }
+        return snapshot;
+    };
+    /**
+     * Resolve a step's element, re-reading the page once when a label misses.
+     *
+     * A label that resolved on the first run can miss on a replay because the
+     * page rendered a beat late or a list came back one row shorter. Re-reading
+     * once costs a snapshot and fixes that whole class outright. An explicit
+     * `ref` is never retried: a ref belongs to the document that produced it, so
+     * a fresh snapshot can only return new ones — the honest answer stays "this
+     * ref is stale, take a new snapshot".
+     */
+    const resolveTarget = async (index, target) => {
+        const first = await current();
+        try {
+            return resolveRef(first, index, target);
+        }
+        catch (error) {
+            if (target.ref !== undefined || signal?.aborted === true)
+                throw error;
+            snapshot = await session.snapshot({ interactiveOnly: false });
+            return resolveRef(snapshot, index, target);
+        }
+    };
+    /**
+     * Run one element action on a step's target, re-pointing it once when the
+     * page replaced the element between resolution and the action.
+     *
+     * Filling a search box is the canonical case: Wikipedia's header input is
+     * swapped for a new node the moment it takes focus, so the ref read from the
+     * snapshot `fill` returned is already stale for the `press` that follows
+     * (measured on the cloud box, 2026-11-14 — the Linux run failed at the Enter
+     * that had worked on Windows). A `REF_NOT_FOUND` also proves the action never
+     * ran, so re-pointing cannot double-click; every other failure is propagated
+     * untouched. A step that pinned an explicit `ref` is never retried: it asked
+     * for that exact node, and a fresh snapshot can only hand back new ones.
+     */
+    const actOnTarget = async (index, target, action) => {
+        const ref = await resolveTarget(index, target);
+        try {
+            return { snapshot: await action(ref), healed: false };
+        }
+        catch (error) {
+            if (target.ref !== undefined || signal?.aborted === true)
+                throw error;
+            if (!(error instanceof BrowserError) || error.code !== 'REF_NOT_FOUND')
+                throw error;
+            snapshot = await session.snapshot({ interactiveOnly: false });
+            const fresh = resolveRef(snapshot, index, target);
+            return { snapshot: await action(fresh), healed: true };
+        }
+    };
+    const fail = (index, step, error, fallbackCode) => {
+        const browserError = error;
+        // The step error already prefixes "step N: "; the render adds the index
+        // again, so strip it here instead of printing "step 3" twice.
+        const raw = String(browserError.message ?? error);
+        const message = raw.replace(/^step \d+: /, '');
+        const base = {
+            ran: outcomes.length + 1,
+            total: steps.length,
+            failedAt: index,
+            failedAction: step.action,
+            failure: message,
+            failureCode: typeof browserError.code === 'string' ? browserError.code : fallbackCode,
+            outcomes: [...outcomes, { index, step: describeStep(step), ok: false, note: message }],
+        };
+        return snapshot === undefined ? base : { ...base, snapshot };
+    };
+    for (let i = 0; i < steps.length; i += 1) {
+        const index = i + 1;
+        const step = steps[i];
+        if (step === undefined)
+            break;
+        if (signal?.aborted === true)
+            break;
+        try {
+            switch (step.action) {
+                case 'navigate': {
+                    snapshot = await session.navigate(step.url, step.waitFor ?? 'domcontentloaded', signal);
+                    outcomes.push({ index, step: describeStep(step), ok: true, note: snapshot.title });
+                    break;
+                }
+                case 'snapshot': {
+                    snapshot = await session.snapshot({ interactiveOnly: false });
+                    outcomes.push({ index, step: describeStep(step), ok: true, note: String(snapshot.totalRefs) + ' refs' });
+                    break;
+                }
+                case 'click': {
+                    const result = await actOnTarget(index, step.target, (ref) => session.click(ref, signal));
+                    snapshot = result.snapshot;
+                    outcomes.push({
+                        index,
+                        step: describeStep(step),
+                        ok: true,
+                        ...(result.healed ? { note: 're-pointed after the page re-rendered' } : {}),
+                    });
+                    break;
+                }
+                case 'fill': {
+                    const result = await actOnTarget(index, step.target, (ref) => session.fill(ref, step.value, signal));
+                    snapshot = result.snapshot;
+                    outcomes.push({
+                        index,
+                        step: describeStep(step),
+                        ok: true,
+                        ...(result.healed ? { note: 're-pointed after the page re-rendered' } : {}),
+                    });
+                    break;
+                }
+                case 'press': {
+                    const result = await actOnTarget(index, step.target, (ref) => session.press(ref, step.key, signal));
+                    snapshot = result.snapshot;
+                    outcomes.push({
+                        index,
+                        step: describeStep(step),
+                        ok: true,
+                        ...(result.healed ? { note: 're-pointed after the page re-rendered' } : {}),
+                    });
+                    break;
+                }
+                case 'hover': {
+                    const result = await actOnTarget(index, step.target, (ref) => session.hover(ref, signal));
+                    snapshot = result.snapshot;
+                    outcomes.push({
+                        index,
+                        step: describeStep(step),
+                        ok: true,
+                        ...(result.healed ? { note: 're-pointed after the page re-rendered' } : {}),
+                    });
+                    break;
+                }
+                case 'scroll': {
+                    // `target` is optional: without it the whole page scrolls, which is
+                    // what "load more" flows need and what costs no element lookup.
+                    const ref = step.target === undefined ? undefined : await resolveTarget(index, step.target);
+                    snapshot = await session.scroll(step.direction, step.amount, ref, signal);
+                    outcomes.push({ index, step: describeStep(step), ok: true });
+                    break;
+                }
+                case 'back': {
+                    snapshot = await session.back(signal);
+                    outcomes.push({ index, step: describeStep(step), ok: true, note: snapshot.url });
+                    break;
+                }
+                case 'forward': {
+                    snapshot = await session.forward(signal);
+                    outcomes.push({ index, step: describeStep(step), ok: true, note: snapshot.url });
+                    break;
+                }
+                case 'wait': {
+                    if (step.urlContains !== undefined) {
+                        // Polling the snapshot's URL is the only honest "the click
+                        // navigated" check available here: a text wait can be satisfied by
+                        // the text the same script just typed (seen on npmjs.com,
+                        // 2026-11-14 — the run reported the old page as the final one).
+                        const needle = step.urlContains;
+                        const deadline = Date.now() + URL_WAIT_TIMEOUT_MS;
+                        let hit = false;
+                        while (Date.now() < deadline) {
+                            const probe = await session.snapshot({ interactiveOnly: true });
+                            if (probe.url.includes(needle)) {
+                                hit = true;
+                                break;
+                            }
+                            await session.wait(URL_WAIT_INTERVAL_MS, signal);
+                        }
+                        if (!hit) {
+                            throw new BrowserError('ACTION_TIMEOUT', 'the URL never contained "' + needle + '" within ' + String(URL_WAIT_TIMEOUT_MS / 1000) + 's');
+                        }
+                    }
+                    else if (step.ms !== undefined) {
+                        await session.wait(step.ms, signal);
+                    }
+                    else {
+                        const condition = step.text !== undefined
+                            ? { text: step.text }
+                            : step.selector !== undefined
+                                ? { selector: step.selector }
+                                : { networkIdle: true };
+                        await session.waitForCondition(condition, signal);
+                    }
+                    snapshot = await session.snapshot({ interactiveOnly: false });
+                    outcomes.push({ index, step: describeStep(step), ok: true });
+                    break;
+                }
+            }
+            options.onSnapshot?.(await current());
+        }
+        catch (error) {
+            // A target lookup already names the step; a browser failure is reported
+            // with the index so the two read the same way to the model.
+            const stepIndex = failedStepOf(error) ?? index;
+            if (error instanceof BrowserError)
+                return fail(stepIndex, step, error, error.code);
+            return fail(stepIndex, step, error, 'SCRIPT_STEP_FAILED');
+        }
+    }
+    return snapshot === undefined
+        ? { ran: outcomes.length, total: steps.length, outcomes }
+        : { ran: outcomes.length, total: steps.length, snapshot, outcomes };
+}

package/lib/script-steps.d.ts

@@ -0,0 +1,95 @@
+/**
+ * One saved browser script: a short, deterministic list of steps that a first
+ * successful run left behind, so a repeat run costs one tool call instead of a
+ * snapshot round-trip per action.
+ *
+ * Why a step list and not generated code: every mature runner in this space
+ * separates "explore once" from "replay deterministically" — Stagehand caches
+ * the resolved action and replays it with self-healing off, browser-use's
+ * workflow-use records a workflow with variables, and Playwright MCP ships its
+ * only batch entry point as `browser_run_code_unsafe`, behind an explicit
+ * "unsafe" name. A step list keeps the validation the individual tools already
+ * have (URL policy, ref freshness, credential refusal) that generated code
+ * would walk around.
+ *
+ * Pure: no I/O, no browser, no clock. The runner and the store stay separate so
+ * this module can be tested on its own.
+ * @module dsh-browser-playwright-codex/script-steps
+ */
+import type { LoadState } from './types.ts';
+/** How a step names the element it acts on. */
+export interface ScriptTarget {
+    /** Ref from the snapshot the previous step returned. Stale after a navigation. */
+    ref?: string;
+    /** Visible label, matched against the current snapshot's accessible names. */
+    text?: string;
+}
+/** One deterministic step. */
+export type ScriptStep = {
+    action: 'navigate';
+    url: string;
+    waitFor?: LoadState;
+} | {
+    action: 'snapshot';
+} | {
+    action: 'click';
+    target: ScriptTarget;
+} | {
+    action: 'fill';
+    target: ScriptTarget;
+    value: string;
+} | {
+    action: 'press';
+    target: ScriptTarget;
+    key: string;
+} | {
+    action: 'hover';
+    target: ScriptTarget;
+} | {
+    action: 'scroll';
+    direction: 'up' | 'down';
+    amount: number;
+    target?: ScriptTarget;
+} | {
+    action: 'back';
+} | {
+    action: 'forward';
+} | {
+    action: 'wait';
+    ms?: number;
+    text?: string;
+    selector?: string;
+    networkIdle?: boolean;
+    /** Wait until the page URL contains this substring — the only condition a “did the click navigate” check can trust. */
+    urlContains?: string;
+};
+/** Upper bound on the steps one script may carry. A longer list is a loop, not a script. */
+export declare const MAX_SCRIPT_STEPS = 40;
+/** Step actions this version understands. */
+export declare const SCRIPT_ACTIONS: readonly ["navigate", "snapshot", "click", "fill", "press", "hover", "scroll", "back", "forward", "wait"];
+/** Default scroll distance when a scroll step omits `amount`. */
+export declare const DEFAULT_SCROLL_AMOUNT = 600;
+/** Upper bound on one scroll step's distance, so a typo cannot jump to the page end. */
+export declare const MAX_SCROLL_AMOUNT = 20000;
+/** One step action name. */
+export type ScriptAction = (typeof SCRIPT_ACTIONS)[number];
+/** Raised for a malformed script; the message names the offending step. */
+export declare class ScriptStepError extends Error {
+    /** Index of the offending step, 1-based as the model sees them. */
+    readonly step: number;
+    constructor(step: number, message: string);
+}
+/**
+ * Validate and normalise a script's steps.
+ *
+ * Throws {@link ScriptStepError} on the first bad step rather than collecting
+ * everything: a script runs as a unit, so the first error is the one that
+ * matters, and a partial list would read as if the rest were fine.
+ *
+ * @param raw - Steps exactly as the model sent them.
+ * @param maxSteps - Upper bound; a long list is a sign the model meant a loop.
+ * @returns The normalised steps.
+ */
+export declare function parseScriptSteps(raw: unknown, maxSteps: number): ScriptStep[];
+/** One line per step, for logs and for the model's summary. */
+export declare function describeStep(step: ScriptStep): string;

package/lib/script-steps.js

@@ -0,0 +1,234 @@
+/** Upper bound on the steps one script may carry. A longer list is a loop, not a script. */
+export const MAX_SCRIPT_STEPS = 40;
+/** Step actions this version understands. */
+export const SCRIPT_ACTIONS = [
+    'navigate',
+    'snapshot',
+    'click',
+    'fill',
+    'press',
+    'hover',
+    'scroll',
+    'back',
+    'forward',
+    'wait',
+];
+/** Default scroll distance when a scroll step omits `amount`. */
+export const DEFAULT_SCROLL_AMOUNT = 600;
+/** Upper bound on one scroll step's distance, so a typo cannot jump to the page end. */
+export const MAX_SCROLL_AMOUNT = 20000;
+/** Raised for a malformed script; the message names the offending step. */
+export class ScriptStepError extends Error {
+    /** Index of the offending step, 1-based as the model sees them. */
+    step;
+    constructor(step, message) {
+        super('step ' + String(step) + ': ' + message);
+        this.name = 'ScriptStepError';
+        this.step = step;
+    }
+}
+/** Normalise a target given as a plain string or an object. */
+function parseTarget(raw, step) {
+    if (typeof raw === 'string') {
+        const text = raw.trim();
+        if (text === '')
+            throw new ScriptStepError(step, 'target is an empty label');
+        return { text };
+    }
+    if (raw === null || typeof raw !== 'object') {
+        throw new ScriptStepError(step, 'target must be a ref, a label, or { ref } / { text }');
+    }
+    const record = raw;
+    const ref = typeof record.ref === 'string' ? record.ref.trim() : '';
+    const text = typeof record.text === 'string' ? record.text.trim() : '';
+    if (ref === '' && text === '')
+        throw new ScriptStepError(step, 'target needs a ref or a text label');
+    if (ref !== '' && text !== '')
+        throw new ScriptStepError(step, 'target takes a ref OR a text label, not both');
+    return ref !== '' ? { ref } : { text };
+}
+/** Resolve a step's target from either `target` or the `ref` / `text` shorthand. */
+function targetOf(record, step) {
+    if (record.target !== undefined)
+        return parseTarget(record.target, step);
+    if (typeof record.ref === 'string')
+        return parseTarget({ ref: record.ref }, step);
+    if (typeof record.text === 'string')
+        return parseTarget({ text: record.text }, step);
+    return parseTarget(undefined, step);
+}
+/** How many conditions a wait step may carry: exactly one, like browser_wait. */
+function countWaitConditions(step) {
+    let n = 0;
+    if (step.ms !== undefined)
+        n += 1;
+    if (step.text !== undefined)
+        n += 1;
+    if (step.selector !== undefined)
+        n += 1;
+    if (step.networkIdle === true)
+        n += 1;
+    if (step.urlContains !== undefined)
+        n += 1;
+    return n;
+}
+/**
+ * Validate and normalise a script's steps.
+ *
+ * Throws {@link ScriptStepError} on the first bad step rather than collecting
+ * everything: a script runs as a unit, so the first error is the one that
+ * matters, and a partial list would read as if the rest were fine.
+ *
+ * @param raw - Steps exactly as the model sent them.
+ * @param maxSteps - Upper bound; a long list is a sign the model meant a loop.
+ * @returns The normalised steps.
+ */
+export function parseScriptSteps(raw, maxSteps) {
+    if (!Array.isArray(raw))
+        throw new ScriptStepError(1, 'steps must be an array');
+    if (raw.length === 0)
+        throw new ScriptStepError(1, 'steps is empty');
+    if (raw.length > maxSteps) {
+        throw new ScriptStepError(1, 'steps has ' + String(raw.length) + ' entries; the cap is ' + String(maxSteps));
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i += 1) {
+        const step = 1 + i;
+        const item = raw[i];
+        if (item === null || typeof item !== 'object')
+            throw new ScriptStepError(step, 'each step must be an object');
+        const record = item;
+        const action = typeof record.action === 'string' ? record.action.trim() : '';
+        switch (action) {
+            case 'navigate': {
+                const url = typeof record.url === 'string' ? record.url.trim() : '';
+                if (url === '')
+                    throw new ScriptStepError(step, 'navigate needs a url');
+                const waitFor = record.waitFor;
+                if (waitFor !== undefined &&
+                    waitFor !== 'load' &&
+                    waitFor !== 'domcontentloaded' &&
+                    waitFor !== 'networkidle') {
+                    throw new ScriptStepError(step, 'waitFor must be load, domcontentloaded or networkidle');
+                }
+                out.push(waitFor === undefined ? { action, url } : { action, url, waitFor: waitFor });
+                break;
+            }
+            case 'snapshot':
+                out.push({ action });
+                break;
+            case 'click':
+                out.push({ action, target: targetOf(record, step) });
+                break;
+            case 'fill': {
+                const value = typeof record.value === 'string' ? record.value : undefined;
+                if (value === undefined)
+                    throw new ScriptStepError(step, 'fill needs a value');
+                out.push({ action, target: targetOf(record, step), value });
+                break;
+            }
+            case 'press': {
+                const key = typeof record.key === 'string' ? record.key.trim() : '';
+                if (key === '')
+                    throw new ScriptStepError(step, 'press needs a key (e.g. Enter, Escape, Tab)');
+                out.push({ action, target: targetOf(record, step), key });
+                break;
+            }
+            case 'hover':
+                out.push({ action, target: targetOf(record, step) });
+                break;
+            case 'scroll': {
+                const direction = record.direction;
+                if (direction !== 'up' && direction !== 'down') {
+                    throw new ScriptStepError(step, 'scroll needs direction "up" or "down"');
+                }
+                const rawAmount = record.amount === undefined ? DEFAULT_SCROLL_AMOUNT : record.amount;
+                if (typeof rawAmount !== 'number' || !Number.isFinite(rawAmount) || rawAmount <= 0) {
+                    throw new ScriptStepError(step, 'scroll amount must be a positive number of pixels');
+                }
+                if (rawAmount > MAX_SCROLL_AMOUNT) {
+                    throw new ScriptStepError(step, 'scroll amount is capped at ' + String(MAX_SCROLL_AMOUNT) + 'px');
+                }
+                const amount = Math.round(rawAmount);
+                // `target` is optional here: without it the whole page scrolls. Parse it
+                // only when the step actually carries one, so a plain page scroll does
+                // not require a ref the page may not have.
+                const hasTarget = record.target !== undefined || record.ref !== undefined || record.text !== undefined;
+                const parsed = { action, direction, amount };
+                out.push(hasTarget ? { ...parsed, target: targetOf(record, step) } : parsed);
+                break;
+            }
+            case 'back':
+            case 'forward':
+                out.push({ action });
+                break;
+            case 'wait': {
+                const conditions = countWaitConditions(record);
+                if (conditions === 0) {
+                    throw new ScriptStepError(step, 'wait needs exactly one of ms, text, selector, networkIdle, urlContains');
+                }
+                if (conditions > 1)
+                    throw new ScriptStepError(step, 'wait takes exactly one condition, got ' + String(conditions));
+                const stepOut = { action };
+                if (typeof record.ms === 'number')
+                    stepOut.ms = record.ms;
+                if (typeof record.text === 'string')
+                    stepOut.text = record.text;
+                if (typeof record.selector === 'string')
+                    stepOut.selector = record.selector;
+                if (record.networkIdle === true)
+                    stepOut.networkIdle = true;
+                if (typeof record.urlContains === 'string' && record.urlContains.trim() !== '') {
+                    stepOut.urlContains = record.urlContains.trim();
+                }
+                out.push(stepOut);
+                break;
+            }
+            default:
+                throw new ScriptStepError(step, 'unknown action ' +
+                    (action === '' ? '(missing)' : '"' + action + '"') +
+                    '; supported: ' +
+                    SCRIPT_ACTIONS.join(', '));
+        }
+    }
+    return out;
+}
+/** One line per step, for logs and for the model's summary. */
+export function describeStep(step) {
+    const targetLabel = (target) => target.ref === undefined ? '"' + String(target.text) + '"' : target.ref;
+    switch (step.action) {
+        case 'navigate':
+            return 'navigate ' + step.url;
+        case 'snapshot':
+            return 'snapshot';
+        case 'click':
+            return 'click ' + targetLabel(step.target);
+        case 'fill':
+            return 'fill ' + targetLabel(step.target);
+        case 'press':
+            return 'press ' + step.key + ' on ' + targetLabel(step.target);
+        case 'hover':
+            return 'hover ' + targetLabel(step.target);
+        case 'scroll':
+            return ('scroll ' +
+                step.direction +
+                ' ' +
+                String(step.amount) +
+                'px' +
+                (step.target === undefined ? '' : ' in ' + targetLabel(step.target)));
+        case 'back':
+            return 'back';
+        case 'forward':
+            return 'forward';
+        case 'wait':
+            if (step.ms !== undefined)
+                return 'wait ' + String(step.ms) + 'ms';
+            if (step.text !== undefined)
+                return 'wait for text "' + step.text + '"';
+            if (step.selector !== undefined)
+                return 'wait for ' + step.selector;
+            if (step.urlContains !== undefined)
+                return 'wait for url containing ' + step.urlContains;
+            return 'wait for network idle';
+    }
+}

package/lib/script-store.d.ts

@@ -0,0 +1,32 @@
+import { type ScriptStep } from './script-steps.ts';
+/** Directory holding the saved scripts. `DSH_BROWSER_SCRIPTS_DIR` overrides it (tests). */
+export declare function scriptsDir(): string;
+/** Validate a script name, returning the trimmed value. */
+export declare function validName(raw: unknown): string;
+/** One saved script, as stored. */
+export interface StoredScript {
+    readonly name: string;
+    readonly savedAt: string;
+    readonly steps: readonly ScriptStep[];
+}
+/**
+ * Write a script, replacing any file of the same name.
+ *
+ * @param name - Validated script name.
+ * @param steps - Steps already validated by `parseScriptSteps`.
+ * @returns The file path and how many steps were stored.
+ */
+export declare function saveScript(name: string, steps: readonly ScriptStep[]): {
+    path: string;
+    steps: number;
+};
+/**
+ * Read one script.
+ *
+ * @param name - Validated script name.
+ * @param maxSteps - Cap applied to the file's steps, so an edited file cannot
+ *   smuggle in a longer list than the tool accepts.
+ */
+export declare function loadScript(name: string, maxSteps: number): StoredScript;
+/** Names of the saved scripts, sorted. Missing directory means none yet. */
+export declare function listScripts(): string[];