stelo 1.0.1

package/dist/middleware.d.ts

@@ -0,0 +1,183 @@
+export type ActionType = 'mouse.move' | 'mouse.moveSmoothly' | 'mouse.moveHumanized' | 'mouse.click' | 'mouse.doubleClick' | 'mouse.tripleClick' | 'mouse.down' | 'mouse.up' | 'mouse.scroll' | 'mouse.drag' | 'mouse.clickAt' | 'keyboard.type' | 'keyboard.typeHumanized' | 'keyboard.typeBatch' | 'keyboard.press' | 'keyboard.down' | 'keyboard.up' | 'keyboard.hotkey' | 'keyboard.sequence' | 'screen.capture' | 'screen.pixelColor' | 'window.focus' | 'window.resize' | 'window.move' | 'window.close' | 'agent.batch' | 'agent.clickAndVerify' | 'custom' | string;
+/** Context passed to middleware at each stage */
+export interface MiddlewareContext {
+    /** The action type being performed */
+    action: ActionType;
+    /** Arguments passed to the action */
+    args: unknown[];
+    /** Timestamp when the action was initiated */
+    timestamp: string;
+    /** Arbitrary metadata (middleware can read/write) */
+    metadata: Record<string, unknown>;
+    /** Set to true to skip the action entirely */
+    skip: boolean;
+    /** Error info (set by 'after' if action failed) */
+    error?: Error;
+    /** Result (set by 'after' if action succeeded) */
+    result?: unknown;
+    /** Duration (set by 'after') */
+    durationMs?: number;
+    /** Was the action modified by middleware? */
+    modified: boolean;
+}
+/** Middleware function signature */
+export type MiddlewareFn = (ctx: MiddlewareContext, next: () => void | Promise<void>) => void | Promise<void>;
+export interface Middleware {
+    /** Unique name */
+    name: string;
+    /** Description */
+    description?: string;
+    /** Priority (higher = runs first). Default: 0 */
+    priority: number;
+    /** Which actions this middleware applies to (empty = all) */
+    actions: ActionType[];
+    /** The before-action hook */
+    before?: MiddlewareFn;
+    /** The after-action hook */
+    after?: MiddlewareFn;
+    /** Enabled? */
+    enabled: boolean;
+}
+export interface MiddlewarePipelineOptions {
+    /** Enable pipeline? Default: true */
+    enabled?: boolean;
+    /** Log middleware execution? Default: false */
+    debug?: boolean;
+}
+export interface BoundaryRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BoundaryPolicyOptions {
+    /** The region the mouse must stay within */
+    region: BoundaryRegion;
+    /** What to do when boundary is violated: 'clamp' | 'block' | 'warn' */
+    mode?: 'clamp' | 'block' | 'warn';
+    /** Priority. Default: 100 (very high, runs before most middleware) */
+    priority?: number;
+}
+/** Create a boundary enforcement middleware */
+export declare function boundaryPolicy(options: BoundaryPolicyOptions): Middleware;
+export interface RatePolicyOptions {
+    /** Maximum actions per period */
+    maxActions: number;
+    /** Period in ms (default: 1000) */
+    periodMs?: number;
+    /** Actions to rate limit (empty = all) */
+    actions?: ActionType[];
+    /** What to do when rate exceeded: 'block' | 'delay' */
+    mode?: 'block' | 'delay';
+    /** Priority. Default: 90 */
+    priority?: number;
+}
+/** Create a rate-limiting middleware */
+export declare function ratePolicy(options: RatePolicyOptions): Middleware;
+export interface CooldownPolicyOptions {
+    /** Cooldown period in ms between same action types */
+    cooldownMs: number;
+    /** Actions to apply cooldown to (empty = all) */
+    actions?: ActionType[];
+    /** Priority. Default: 80 */
+    priority?: number;
+}
+/** Create a cooldown middleware — prevents rapid repeat of same action type */
+export declare function cooldownPolicy(options: CooldownPolicyOptions): Middleware;
+export interface LoggingMiddlewareOptions {
+    /** Log level for actions. Default: 'debug' */
+    level?: 'trace' | 'debug' | 'info';
+    /** Include action args in logs? Default: false */
+    includeArgs?: boolean;
+    /** Include results in logs? Default: false */
+    includeResults?: boolean;
+    /** Priority. Default: -100 (very low, runs last before) */
+    priority?: number;
+}
+/** Create a logging middleware for action auditing */
+export declare function loggingMiddleware(options?: LoggingMiddlewareOptions): Middleware;
+export interface RetryMiddlewareOptions {
+    /** Max retries. Default: 2 */
+    maxRetries?: number;
+    /** Delay between retries in ms. Default: 500 */
+    delayMs?: number;
+    /** Backoff multiplier. Default: 2.0 */
+    backoff?: number;
+    /** Only retry these actions (empty = all) */
+    actions?: ActionType[];
+    /** Only retry if error matches predicate */
+    retryIf?: (error: Error) => boolean;
+    /** Priority. Default: -50 */
+    priority?: number;
+}
+/** Create a retry middleware for automatic action retry on failure */
+export declare function retryMiddleware(options?: RetryMiddlewareOptions): Middleware;
+/**
+ * Create a middleware that transforms action arguments.
+ * Useful for coordinate scaling, offset adjustment, etc.
+ */
+export declare function transformMiddleware(name: string, actions: ActionType[], transform: (action: ActionType, args: unknown[]) => unknown[], priority?: number): Middleware;
+export declare const middleware: {
+    /**
+     * Register a middleware.
+     */
+    use(mw: Middleware): void;
+    /**
+     * Remove a middleware by name.
+     */
+    remove(name: string): boolean;
+    /**
+     * Enable a middleware by name.
+     */
+    enable(name: string): boolean;
+    /**
+     * Disable a middleware by name.
+     */
+    disable(name: string): boolean;
+    /**
+     * List all registered middleware.
+     */
+    list(): {
+        name: string;
+        enabled: boolean;
+        priority: number;
+        description?: string;
+    }[];
+    /**
+     * Enable or disable the entire pipeline.
+     */
+    setEnabled(enabled: boolean): void;
+    /** Is the pipeline enabled? */
+    isEnabled(): boolean;
+    /** Enable debug logging for the pipeline */
+    setDebug(enabled: boolean): void;
+    /**
+     * Execute an action through the middleware pipeline.
+     *
+     * This is the core function that modules call to run actions through middleware.
+     * It runs all matching 'before' hooks, then the action, then all 'after' hooks.
+     *
+     * @example
+     * ```ts
+     * // Inside mouse.ts:
+     * const result = await middleware.execute('mouse.move', [x, y], () => {
+     *   native.mouseMove(x, y);
+     * });
+     * ```
+     */
+    execute<T>(action: ActionType, args: unknown[], fn: (...args: unknown[]) => T | Promise<T>): Promise<T>;
+    /**
+     * Execute an action synchronously through the pipeline.
+     * Only runs synchronous middleware (skips async middleware).
+     */
+    executeSync<T>(action: ActionType, args: unknown[], fn: (...args: unknown[]) => T): T;
+    /**
+     * Clear all middleware.
+     */
+    clear(): void;
+    /**
+     * Reset pipeline to defaults.
+     */
+    reset(): void;
+};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../ts/middleware.ts"],"names":[],"mappings":"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"}

package/dist/middleware.js

@@ -0,0 +1,493 @@
+"use strict";
+// ============================================================================
+// Stelo — Middleware & Policy Pipeline
+// ============================================================================
+// Pluggable before/after hooks for EVERY automation action. Built-in policies
+// for boundary enforcement, rate limiting, cooldowns, logging, retry, and
+// action transformation.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.middleware = void 0;
+exports.boundaryPolicy = boundaryPolicy;
+exports.ratePolicy = ratePolicy;
+exports.cooldownPolicy = cooldownPolicy;
+exports.loggingMiddleware = loggingMiddleware;
+exports.retryMiddleware = retryMiddleware;
+exports.transformMiddleware = transformMiddleware;
+const events_1 = require("./events");
+const logger_1 = require("./logger");
+/** Create a boundary enforcement middleware */
+function boundaryPolicy(options) {
+    const { region, mode = 'clamp', priority = 100 } = options;
+    const log = logger_1.logger.child('boundary');
+    return {
+        name: 'boundary-enforcement',
+        description: `Keep mouse within [${region.x},${region.y}]-[${region.x + region.width},${region.y + region.height}]`,
+        priority,
+        actions: [
+            'mouse.move', 'mouse.moveSmoothly', 'mouse.moveHumanized',
+            'mouse.click', 'mouse.clickAt', 'mouse.drag',
+            'agent.clickAndVerify',
+        ],
+        enabled: true,
+        before: (ctx) => {
+            // Find x, y in args
+            const args = ctx.args;
+            let x;
+            let y;
+            if (ctx.action === 'mouse.move' || ctx.action === 'mouse.moveSmoothly' || ctx.action === 'mouse.moveHumanized') {
+                x = args[0];
+                y = args[1];
+            }
+            else if (ctx.action === 'mouse.clickAt' || ctx.action === 'agent.clickAndVerify') {
+                x = args[0];
+                y = args[1];
+            }
+            else if (ctx.action === 'mouse.drag') {
+                // Check both from and to coordinates
+                const fromX = args[0], fromY = args[1], toX = args[2], toY = args[3];
+                if (typeof toX === 'number' && typeof toY === 'number') {
+                    x = toX;
+                    y = toY;
+                }
+            }
+            if (x === undefined || y === undefined)
+                return;
+            const minX = region.x;
+            const minY = region.y;
+            const maxX = region.x + region.width;
+            const maxY = region.y + region.height;
+            const outOfBounds = x < minX || x > maxX || y < minY || y > maxY;
+            if (outOfBounds) {
+                if (mode === 'block') {
+                    log.warn('Action blocked: mouse target out of bounds', { x, y, region });
+                    ctx.skip = true;
+                    events_1.events.emit('middleware.boundary.blocked', 'safety', { x, y, region, action: ctx.action }, { source: 'middleware' });
+                }
+                else if (mode === 'clamp') {
+                    const clampedX = Math.max(minX, Math.min(maxX, x));
+                    const clampedY = Math.max(minY, Math.min(maxY, y));
+                    log.debug('Clamping mouse to boundary', { original: { x, y }, clamped: { x: clampedX, y: clampedY } });
+                    // Modify args in-place
+                    if (ctx.action === 'mouse.move' || ctx.action === 'mouse.moveSmoothly' || ctx.action === 'mouse.moveHumanized') {
+                        ctx.args[0] = clampedX;
+                        ctx.args[1] = clampedY;
+                    }
+                    else if (ctx.action === 'mouse.clickAt' || ctx.action === 'agent.clickAndVerify') {
+                        ctx.args[0] = clampedX;
+                        ctx.args[1] = clampedY;
+                    }
+                    else if (ctx.action === 'mouse.drag') {
+                        ctx.args[2] = clampedX;
+                        ctx.args[3] = clampedY;
+                    }
+                    ctx.modified = true;
+                    events_1.events.emit('middleware.boundary.clamped', 'safety', { original: { x, y }, clamped: { x: clampedX, y: clampedY } }, { source: 'middleware' });
+                }
+                else {
+                    log.warn('Mouse target out of bounds (warning only)', { x, y, region });
+                    events_1.events.emit('middleware.boundary.warning', 'safety', { x, y, region, action: ctx.action }, { source: 'middleware' });
+                }
+            }
+        },
+    };
+}
+/** Create a rate-limiting middleware */
+function ratePolicy(options) {
+    const { maxActions, periodMs = 1000, mode = 'block', priority = 90 } = options;
+    const log = logger_1.logger.child('rate-policy');
+    const timestamps = [];
+    return {
+        name: 'rate-policy',
+        description: `Max ${maxActions} actions per ${periodMs}ms`,
+        priority,
+        actions: options.actions ?? [],
+        enabled: true,
+        before: async (ctx) => {
+            const now = Date.now();
+            // Remove timestamps outside the window
+            while (timestamps.length > 0 && timestamps[0] < now - periodMs) {
+                timestamps.shift();
+            }
+            if (timestamps.length >= maxActions) {
+                if (mode === 'block') {
+                    log.warn('Action rate-limited', { action: ctx.action, count: timestamps.length, max: maxActions });
+                    ctx.skip = true;
+                    events_1.events.emit('middleware.rate.blocked', 'safety', { action: ctx.action, count: timestamps.length }, { source: 'middleware' });
+                }
+                else {
+                    // Delay until there's room
+                    const waitUntil = timestamps[0] + periodMs;
+                    const delay = waitUntil - now;
+                    if (delay > 0) {
+                        log.debug('Action delayed by rate policy', { action: ctx.action, delayMs: delay });
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                }
+            }
+            if (!ctx.skip) {
+                timestamps.push(Date.now());
+            }
+        },
+    };
+}
+/** Create a cooldown middleware — prevents rapid repeat of same action type */
+function cooldownPolicy(options) {
+    const { cooldownMs, priority = 80 } = options;
+    const lastExecution = new Map();
+    return {
+        name: 'cooldown-policy',
+        description: `${cooldownMs}ms cooldown between same action types`,
+        priority,
+        actions: options.actions ?? [],
+        enabled: true,
+        before: async (ctx) => {
+            const last = lastExecution.get(ctx.action);
+            if (last) {
+                const elapsed = Date.now() - last;
+                if (elapsed < cooldownMs) {
+                    const remaining = cooldownMs - elapsed;
+                    await new Promise((resolve) => setTimeout(resolve, remaining));
+                }
+            }
+        },
+        after: (ctx) => {
+            if (!ctx.skip && !ctx.error) {
+                lastExecution.set(ctx.action, Date.now());
+            }
+        },
+    };
+}
+/** Create a logging middleware for action auditing */
+function loggingMiddleware(options) {
+    const { level = 'debug', includeArgs = false, includeResults = false, priority = -100 } = options ?? {};
+    const log = logger_1.logger.child('action-audit');
+    const logFn = level === 'trace' ? log.trace.bind(log)
+        : level === 'info' ? log.info.bind(log)
+            : log.debug.bind(log);
+    return {
+        name: 'logging',
+        description: 'Log all actions for auditing',
+        priority,
+        actions: [],
+        enabled: true,
+        before: (ctx) => {
+            const data = { action: ctx.action };
+            if (includeArgs)
+                data.args = ctx.args;
+            logFn(`Action starting: ${ctx.action}`, data);
+        },
+        after: (ctx) => {
+            const data = {
+                action: ctx.action,
+                durationMs: ctx.durationMs,
+                skipped: ctx.skip,
+                modified: ctx.modified,
+            };
+            if (ctx.error) {
+                data.error = ctx.error.message;
+                log.warn(`Action failed: ${ctx.action}`, data);
+            }
+            else {
+                if (includeResults)
+                    data.result = ctx.result;
+                logFn(`Action completed: ${ctx.action}`, data);
+            }
+        },
+    };
+}
+/** Create a retry middleware for automatic action retry on failure */
+function retryMiddleware(options) {
+    const { maxRetries = 2, delayMs = 500, backoff = 2.0, priority = -50, retryIf } = options ?? {};
+    const log = logger_1.logger.child('retry');
+    return {
+        name: 'retry',
+        description: `Retry failed actions up to ${maxRetries} times`,
+        priority,
+        actions: options?.actions ?? [],
+        enabled: true,
+        after: async (ctx) => {
+            if (!ctx.error)
+                return;
+            if (retryIf && !retryIf(ctx.error))
+                return;
+            const attempts = ctx.metadata._retryAttempt || 0;
+            if (attempts >= maxRetries)
+                return;
+            ctx.metadata._retryAttempt = attempts + 1;
+            const delay = delayMs * Math.pow(backoff, attempts);
+            log.debug(`Retrying action: ${ctx.action}`, {
+                attempt: attempts + 1,
+                maxRetries,
+                delayMs: delay,
+                error: ctx.error.message,
+            });
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            // Signal that the action should be retried
+            ctx.metadata._shouldRetry = true;
+        },
+    };
+}
+// ── Transform Middleware ─────────────────────────────────────────────────────
+/**
+ * Create a middleware that transforms action arguments.
+ * Useful for coordinate scaling, offset adjustment, etc.
+ */
+function transformMiddleware(name, actions, transform, priority = 50) {
+    return {
+        name,
+        description: `Transform args for [${actions.join(', ')}]`,
+        priority,
+        actions,
+        enabled: true,
+        before: (ctx) => {
+            ctx.args = transform(ctx.action, ctx.args);
+            ctx.modified = true;
+        },
+    };
+}
+// ── Pipeline ─────────────────────────────────────────────────────────────────
+const _middlewares = [];
+let _pipelineEnabled = true;
+let _debug = false;
+const _log = logger_1.logger.child('middleware');
+function getMatchingMiddleware(action) {
+    return _middlewares
+        .filter((m) => m.enabled && (m.actions.length === 0 || m.actions.includes(action)))
+        .sort((a, b) => b.priority - a.priority);
+}
+exports.middleware = {
+    /**
+     * Register a middleware.
+     */
+    use(mw) {
+        _middlewares.push(mw);
+        if (_debug)
+            _log.debug(`Middleware registered: ${mw.name}`, { priority: mw.priority });
+        events_1.events.emit('middleware.registered', 'middleware', { name: mw.name }, { source: 'middleware' });
+    },
+    /**
+     * Remove a middleware by name.
+     */
+    remove(name) {
+        const idx = _middlewares.findIndex((m) => m.name === name);
+        if (idx !== -1) {
+            _middlewares.splice(idx, 1);
+            return true;
+        }
+        return false;
+    },
+    /**
+     * Enable a middleware by name.
+     */
+    enable(name) {
+        const mw = _middlewares.find((m) => m.name === name);
+        if (mw) {
+            mw.enabled = true;
+            return true;
+        }
+        return false;
+    },
+    /**
+     * Disable a middleware by name.
+     */
+    disable(name) {
+        const mw = _middlewares.find((m) => m.name === name);
+        if (mw) {
+            mw.enabled = false;
+            return true;
+        }
+        return false;
+    },
+    /**
+     * List all registered middleware.
+     */
+    list() {
+        return _middlewares.map((m) => ({
+            name: m.name,
+            enabled: m.enabled,
+            priority: m.priority,
+            description: m.description,
+        }));
+    },
+    /**
+     * Enable or disable the entire pipeline.
+     */
+    setEnabled(enabled) {
+        _pipelineEnabled = enabled;
+    },
+    /** Is the pipeline enabled? */
+    isEnabled() {
+        return _pipelineEnabled;
+    },
+    /** Enable debug logging for the pipeline */
+    setDebug(enabled) {
+        _debug = enabled;
+    },
+    /**
+     * Execute an action through the middleware pipeline.
+     *
+     * This is the core function that modules call to run actions through middleware.
+     * It runs all matching 'before' hooks, then the action, then all 'after' hooks.
+     *
+     * @example
+     * ```ts
+     * // Inside mouse.ts:
+     * const result = await middleware.execute('mouse.move', [x, y], () => {
+     *   native.mouseMove(x, y);
+     * });
+     * ```
+     */
+    async execute(action, args, fn) {
+        if (!_pipelineEnabled) {
+            return fn(...args);
+        }
+        const matching = getMatchingMiddleware(action);
+        if (matching.length === 0) {
+            return fn(...args);
+        }
+        const ctx = {
+            action,
+            args: [...args],
+            timestamp: new Date().toISOString(),
+            metadata: {},
+            skip: false,
+            modified: false,
+        };
+        // Run before hooks
+        for (const mw of matching) {
+            if (mw.before) {
+                try {
+                    await mw.before(ctx, () => { });
+                }
+                catch (err) {
+                    if (_debug)
+                        _log.error(`Before middleware error: ${mw.name}`, err);
+                }
+                if (ctx.skip)
+                    break;
+            }
+        }
+        // Execute action (unless skipped)
+        const startTime = performance.now();
+        if (!ctx.skip) {
+            try {
+                ctx.result = await Promise.resolve(fn(...ctx.args));
+            }
+            catch (err) {
+                ctx.error = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+        ctx.durationMs = performance.now() - startTime;
+        // Run after hooks (in reverse priority order)
+        const reversedMatching = [...matching].reverse();
+        for (const mw of reversedMatching) {
+            if (mw.after) {
+                try {
+                    await mw.after(ctx, () => { });
+                }
+                catch (err) {
+                    if (_debug)
+                        _log.error(`After middleware error: ${mw.name}`, err);
+                }
+                // Check if retry was requested
+                if (ctx.metadata._shouldRetry) {
+                    ctx.metadata._shouldRetry = false;
+                    ctx.error = undefined;
+                    ctx.result = undefined;
+                    try {
+                        ctx.result = await Promise.resolve(fn(...ctx.args));
+                    }
+                    catch (err) {
+                        ctx.error = err instanceof Error ? err : new Error(String(err));
+                    }
+                }
+            }
+        }
+        if (ctx.error)
+            throw ctx.error;
+        return ctx.result;
+    },
+    /**
+     * Execute an action synchronously through the pipeline.
+     * Only runs synchronous middleware (skips async middleware).
+     */
+    executeSync(action, args, fn) {
+        if (!_pipelineEnabled) {
+            return fn(...args);
+        }
+        const matching = getMatchingMiddleware(action);
+        if (matching.length === 0) {
+            return fn(...args);
+        }
+        const ctx = {
+            action,
+            args: [...args],
+            timestamp: new Date().toISOString(),
+            metadata: {},
+            skip: false,
+            modified: false,
+        };
+        // Run synchronous before hooks
+        for (const mw of matching) {
+            if (mw.before) {
+                try {
+                    const result = mw.before(ctx, () => { });
+                    // Skip async middleware in sync mode
+                    if (result instanceof Promise)
+                        continue;
+                }
+                catch (err) {
+                    if (_debug)
+                        _log.error(`Before middleware error (sync): ${mw.name}`, err);
+                }
+                if (ctx.skip)
+                    break;
+            }
+        }
+        // Execute
+        const startTime = performance.now();
+        if (!ctx.skip) {
+            try {
+                ctx.result = fn(...ctx.args);
+            }
+            catch (err) {
+                ctx.error = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+        ctx.durationMs = performance.now() - startTime;
+        // Run synchronous after hooks
+        const reversedMatching = [...matching].reverse();
+        for (const mw of reversedMatching) {
+            if (mw.after) {
+                try {
+                    const result = mw.after(ctx, () => { });
+                    if (result instanceof Promise)
+                        continue;
+                }
+                catch (err) {
+                    if (_debug)
+                        _log.error(`After middleware error (sync): ${mw.name}`, err);
+                }
+            }
+        }
+        if (ctx.error)
+            throw ctx.error;
+        return ctx.result;
+    },
+    /**
+     * Clear all middleware.
+     */
+    clear() {
+        _middlewares.length = 0;
+    },
+    /**
+     * Reset pipeline to defaults.
+     */
+    reset() {
+        _middlewares.length = 0;
+        _pipelineEnabled = true;
+        _debug = false;
+    },
+};
+//# sourceMappingURL=middleware.js.map