stelo 1.0.1

package/dist/session.js

@@ -0,0 +1,479 @@
+"use strict";
+// ============================================================================
+// Stelo — Session Management
+// ============================================================================
+// Checkpoint creation, state persistence, session restore, undo/rollback,
+// and session isolation for enterprise automation workflows.
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.session = void 0;
+const events_1 = require("./events");
+const logger_1 = require("./logger");
+let _sessionIdCounter = 0;
+let _activeSession = null;
+const _sessions = new Map();
+const _log = logger_1.logger.child('session');
+function generateSessionId() {
+    return `sess_${Date.now()}_${++_sessionIdCounter}`;
+}
+function generateCheckpointId() {
+    return `ckpt_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function toMetadata(s) {
+    return {
+        id: s.id,
+        name: s.name,
+        status: s.status,
+        createdAt: new Date(s.createdAt).toISOString(),
+        updatedAt: new Date(s.updatedAt).toISOString(),
+        checkpointCount: s.checkpoints.length,
+        actionCount: s.actions.length,
+        tags: [...s.tags],
+        custom: { ...s.custom },
+    };
+}
+// ── Public API ───────────────────────────────────────────────────────────────
+exports.session = {
+    /**
+     * Start a new session.
+     */
+    start(options) {
+        const id = generateSessionId();
+        const now = Date.now();
+        const sess = {
+            id,
+            name: options?.name ?? `Session ${id}`,
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+            checkpoints: [],
+            actions: [],
+            store: {},
+            tags: options?.tags ?? [],
+            custom: options?.custom ?? {},
+            options: {
+                name: options?.name ?? `Session ${id}`,
+                autoCheckpointInterval: options?.autoCheckpointInterval ?? 0,
+                maxCheckpoints: options?.maxCheckpoints ?? 50,
+                maxActions: options?.maxActions ?? 10000,
+                tags: options?.tags ?? [],
+                custom: options?.custom ?? {},
+            },
+            undoStack: [],
+        };
+        _sessions.set(id, sess);
+        _activeSession = sess;
+        events_1.events.emit('session.start', 'session', { sessionId: id, name: sess.name }, { source: 'session' });
+        _log.info('Session started', { id, name: sess.name });
+        return id;
+    },
+    /**
+     * Get the active session ID (or null).
+     */
+    getActiveId() {
+        return _activeSession?.id ?? null;
+    },
+    /**
+     * Get the active session metadata.
+     */
+    getActive() {
+        if (!_activeSession)
+            return null;
+        return toMetadata(_activeSession);
+    },
+    /**
+     * Switch to a different (existing) session.
+     */
+    switchTo(sessionId) {
+        const sess = _sessions.get(sessionId);
+        if (!sess)
+            return false;
+        _activeSession = sess;
+        return true;
+    },
+    /**
+     * Pause the active session.
+     */
+    pause() {
+        if (!_activeSession || _activeSession.status !== 'active')
+            return false;
+        _activeSession.status = 'paused';
+        _activeSession.updatedAt = Date.now();
+        events_1.events.emit('session.pause', 'session', { sessionId: _activeSession.id }, { source: 'session' });
+        return true;
+    },
+    /**
+     * Resume the active session.
+     */
+    resume() {
+        if (!_activeSession || _activeSession.status !== 'paused')
+            return false;
+        _activeSession.status = 'active';
+        _activeSession.updatedAt = Date.now();
+        events_1.events.emit('session.resume', 'session', { sessionId: _activeSession.id }, { source: 'session' });
+        return true;
+    },
+    /**
+     * End the active session.
+     */
+    end(status = 'completed') {
+        if (!_activeSession)
+            return null;
+        _activeSession.status = status;
+        _activeSession.updatedAt = Date.now();
+        const meta = toMetadata(_activeSession);
+        events_1.events.emit('session.end', 'session', { sessionId: _activeSession.id, status }, { source: 'session' });
+        _log.info('Session ended', { id: _activeSession.id, status, actions: _activeSession.actions.length });
+        _activeSession = null;
+        return meta;
+    },
+    // ── Action Recording ───────────────────────────────────────────────────
+    /**
+     * Record an action in the active session.
+     */
+    recordAction(type, args, options) {
+        if (!_activeSession || _activeSession.status !== 'active')
+            return -1;
+        const index = _activeSession.actions.length;
+        const action = {
+            index,
+            type,
+            args,
+            timestamp: new Date().toISOString(),
+            durationMs: options?.durationMs ?? 0,
+            result: options?.result,
+            error: options?.error,
+            undoable: options?.undoable ?? false,
+            undoHint: options?.undoHint,
+        };
+        _activeSession.actions.push(action);
+        _activeSession.updatedAt = Date.now();
+        // Track undo function
+        if (options?.undoFn) {
+            _activeSession.undoStack.push(options.undoFn);
+        }
+        // Enforce max actions
+        while (_activeSession.actions.length > _activeSession.options.maxActions) {
+            _activeSession.actions.shift();
+        }
+        // Auto-checkpoint
+        const autoInterval = _activeSession.options.autoCheckpointInterval;
+        if (autoInterval > 0 && index > 0 && index % autoInterval === 0) {
+            exports.session.checkpoint(`auto-${index}`);
+        }
+        return index;
+    },
+    /**
+     * Get the action history from the active session.
+     */
+    getActions(filter) {
+        if (!_activeSession)
+            return [];
+        let actions = [..._activeSession.actions];
+        if (filter?.type) {
+            actions = actions.filter((a) => a.type.startsWith(filter.type));
+        }
+        if (filter?.since) {
+            const since = new Date(filter.since).getTime();
+            actions = actions.filter((a) => new Date(a.timestamp).getTime() >= since);
+        }
+        if (filter?.limit && filter.limit > 0) {
+            actions = actions.slice(-filter.limit);
+        }
+        return actions;
+    },
+    // ── Checkpoints ────────────────────────────────────────────────────────
+    /**
+     * Create a checkpoint (snapshot) at the current point.
+     */
+    checkpoint(label, metadata) {
+        if (!_activeSession)
+            return null;
+        const id = generateCheckpointId();
+        const ckpt = {
+            id,
+            label: label ?? `Checkpoint ${_activeSession.checkpoints.length + 1}`,
+            timestamp: new Date().toISOString(),
+            actionIndex: _activeSession.actions.length,
+            state: JSON.parse(JSON.stringify(_activeSession.store)),
+            metadata,
+        };
+        _activeSession.checkpoints.push(ckpt);
+        _activeSession.updatedAt = Date.now();
+        // Enforce max checkpoints
+        while (_activeSession.checkpoints.length > _activeSession.options.maxCheckpoints) {
+            _activeSession.checkpoints.shift();
+        }
+        events_1.events.emit('session.checkpoint', 'session', {
+            sessionId: _activeSession.id,
+            checkpointId: id,
+            label: ckpt.label,
+            actionIndex: ckpt.actionIndex,
+        }, { source: 'session' });
+        _log.debug('Checkpoint created', { id, label: ckpt.label });
+        return id;
+    },
+    /**
+     * List all checkpoints in the active session.
+     */
+    listCheckpoints() {
+        if (!_activeSession)
+            return [];
+        return [..._activeSession.checkpoints];
+    },
+    /**
+     * Restore state from a checkpoint (does NOT undo actions — use rollback for that).
+     */
+    restoreCheckpoint(checkpointId) {
+        if (!_activeSession)
+            return false;
+        const ckpt = _activeSession.checkpoints.find((c) => c.id === checkpointId);
+        if (!ckpt)
+            return false;
+        _activeSession.store = JSON.parse(JSON.stringify(ckpt.state));
+        _activeSession.updatedAt = Date.now();
+        events_1.events.emit('session.restore', 'session', {
+            sessionId: _activeSession.id,
+            checkpointId,
+            label: ckpt.label,
+        }, { source: 'session' });
+        _log.info('Restored checkpoint', { checkpointId, label: ckpt.label });
+        return true;
+    },
+    /**
+     * Rollback: undo actions back to a checkpoint.
+     * This calls the undo functions for actions recorded since the checkpoint.
+     */
+    async rollback(checkpointId) {
+        if (!_activeSession)
+            return { undone: 0, errors: 0 };
+        const ckpt = _activeSession.checkpoints.find((c) => c.id === checkpointId);
+        if (!ckpt)
+            return { undone: 0, errors: 0 };
+        // Restore state
+        _activeSession.store = JSON.parse(JSON.stringify(ckpt.state));
+        // Undo actions in reverse order
+        const actionsToUndo = _activeSession.actions.slice(ckpt.actionIndex);
+        let undone = 0;
+        let errors = 0;
+        // Calculate how many undo fns to pop
+        const undoCount = Math.min(actionsToUndo.filter((a) => a.undoable).length, _activeSession.undoStack.length);
+        for (let i = 0; i < undoCount; i++) {
+            const undoFn = _activeSession.undoStack.pop();
+            if (undoFn) {
+                try {
+                    await undoFn();
+                    undone++;
+                }
+                catch (err) {
+                    errors++;
+                    _log.error('Undo failed', err);
+                }
+            }
+        }
+        // Trim action history
+        _activeSession.actions = _activeSession.actions.slice(0, ckpt.actionIndex);
+        // Remove checkpoints after this one
+        const ckptIdx = _activeSession.checkpoints.indexOf(ckpt);
+        _activeSession.checkpoints = _activeSession.checkpoints.slice(0, ckptIdx + 1);
+        _activeSession.status = 'rolled_back';
+        _activeSession.updatedAt = Date.now();
+        events_1.events.emit('session.rollback', 'session', {
+            sessionId: _activeSession.id,
+            checkpointId,
+            undone,
+            errors,
+        }, { source: 'session' });
+        _log.info('Rolled back to checkpoint', { checkpointId, undone, errors });
+        return { undone, errors };
+    },
+    /**
+     * Undo the last undoable action.
+     */
+    async undo() {
+        if (!_activeSession || _activeSession.undoStack.length === 0)
+            return false;
+        const undoFn = _activeSession.undoStack.pop();
+        if (!undoFn)
+            return false;
+        try {
+            await undoFn();
+            _activeSession.updatedAt = Date.now();
+            events_1.events.emit('session.undo', 'session', { sessionId: _activeSession.id }, { source: 'session' });
+            return true;
+        }
+        catch (err) {
+            _log.error('Undo failed', err);
+            return false;
+        }
+    },
+    // ── State Store ────────────────────────────────────────────────────────
+    /**
+     * Set a key in the session store.
+     */
+    set(key, value) {
+        if (!_activeSession)
+            return;
+        _activeSession.store[key] = value;
+        _activeSession.updatedAt = Date.now();
+    },
+    /**
+     * Get a value from the session store.
+     */
+    get(key, defaultValue) {
+        if (!_activeSession)
+            return defaultValue;
+        return (key in _activeSession.store
+            ? _activeSession.store[key]
+            : defaultValue);
+    },
+    /**
+     * Check if a key exists in the session store.
+     */
+    has(key) {
+        if (!_activeSession)
+            return false;
+        return key in _activeSession.store;
+    },
+    /**
+     * Delete a key from the session store.
+     */
+    delete(key) {
+        if (!_activeSession)
+            return false;
+        if (key in _activeSession.store) {
+            delete _activeSession.store[key];
+            return true;
+        }
+        return false;
+    },
+    /**
+     * Get all keys in the session store.
+     */
+    keys() {
+        if (!_activeSession)
+            return [];
+        return Object.keys(_activeSession.store);
+    },
+    // ── Serialization ──────────────────────────────────────────────────────
+    /**
+     * Export the active session as a JSON-serializable snapshot.
+     */
+    export() {
+        if (!_activeSession)
+            return null;
+        return {
+            metadata: toMetadata(_activeSession),
+            checkpoints: [..._activeSession.checkpoints],
+            actions: [..._activeSession.actions],
+            store: JSON.parse(JSON.stringify(_activeSession.store)),
+            version: 1,
+        };
+    },
+    /**
+     * Export session as a JSON string.
+     */
+    toJSON(pretty = false) {
+        const snapshot = exports.session.export();
+        if (!snapshot)
+            return null;
+        return JSON.stringify(snapshot, null, pretty ? 2 : undefined);
+    },
+    /**
+     * Import a session from a snapshot (creates a new session).
+     */
+    import(snapshot) {
+        const id = generateSessionId();
+        const now = Date.now();
+        const sess = {
+            id,
+            name: snapshot.metadata.name + ' (imported)',
+            status: 'active',
+            createdAt: now,
+            updatedAt: now,
+            checkpoints: [...snapshot.checkpoints],
+            actions: [...snapshot.actions],
+            store: JSON.parse(JSON.stringify(snapshot.store)),
+            tags: [...snapshot.metadata.tags],
+            custom: { ...snapshot.metadata.custom, importedFrom: snapshot.metadata.id },
+            options: {
+                name: snapshot.metadata.name,
+                autoCheckpointInterval: 0,
+                maxCheckpoints: 50,
+                maxActions: 10000,
+                tags: snapshot.metadata.tags,
+                custom: snapshot.metadata.custom,
+            },
+            undoStack: [],
+        };
+        _sessions.set(id, sess);
+        _activeSession = sess;
+        _log.info('Session imported', {
+            id,
+            fromId: snapshot.metadata.id,
+            actions: snapshot.actions.length,
+        });
+        return id;
+    },
+    /**
+     * Import session from a JSON string.
+     */
+    fromJSON(json) {
+        const snapshot = JSON.parse(json);
+        return exports.session.import(snapshot);
+    },
+    // ── Management ─────────────────────────────────────────────────────────
+    /**
+     * List all sessions.
+     */
+    listSessions() {
+        return [..._sessions.values()].map(toMetadata);
+    },
+    /**
+     * Delete a session.
+     */
+    deleteSession(sessionId) {
+        if (_activeSession?.id === sessionId) {
+            _activeSession = null;
+        }
+        return _sessions.delete(sessionId);
+    },
+    /**
+     * Get session duration (ms) for the active session.
+     */
+    getDuration() {
+        if (!_activeSession)
+            return 0;
+        return Date.now() - _activeSession.createdAt;
+    },
+    /**
+     * Get a summary of the active session (for display/logging).
+     */
+    getSummary() {
+        if (!_activeSession)
+            return 'No active session';
+        const durationSec = Math.round(exports.session.getDuration() / 1000);
+        const actionTypes = new Map();
+        for (const a of _activeSession.actions) {
+            actionTypes.set(a.type, (actionTypes.get(a.type) ?? 0) + 1);
+        }
+        const typesSummary = [...actionTypes.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .map(([t, c]) => `${t}:${c}`)
+            .join(', ');
+        return [
+            `Session: ${_activeSession.name} [${_activeSession.status}]`,
+            `Duration: ${durationSec}s`,
+            `Actions: ${_activeSession.actions.length}`,
+            `Checkpoints: ${_activeSession.checkpoints.length}`,
+            `Types: ${typesSummary || 'none'}`,
+        ].join(' | ');
+    },
+    /** Reset all session state */
+    reset() {
+        _activeSession = null;
+        _sessions.clear();
+        _sessionIdCounter = 0;
+    },
+};
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/stream.d.ts

@@ -0,0 +1,168 @@
+import type { Region } from './types';
+/** Configuration for the screen stream. */
+export interface StreamConfig {
+    /** Target frames per second (1–120, default: 30) */
+    fps?: number;
+    /** Capture a specific region instead of full screen */
+    region?: Region;
+    /** Scale factor (0.1–1.0, default: 1.0). Use 0.5 for half resolution. */
+    scale?: number;
+    /** Number of frames to keep in the ring buffer (default: 3) */
+    bufferSize?: number;
+}
+/** A single captured frame with metadata. */
+export interface StreamFrame {
+    /** Raw RGBA pixel data (4 bytes per pixel) */
+    data: Buffer;
+    /** Frame width in pixels */
+    width: number;
+    /** Frame height in pixels */
+    height: number;
+    /** Monotonic frame sequence number (starts at 1) */
+    sequence: number;
+    /** Milliseconds since stream started */
+    timestampMs: number;
+    /** Actual measured FPS at this point */
+    measuredFps: number;
+    /** Cursor X position at time of capture */
+    cursorX: number;
+    /** Cursor Y position at time of capture */
+    cursorY: number;
+}
+/** Stream performance statistics. */
+export interface StreamStats {
+    /** Whether the stream is currently running */
+    isRunning: boolean;
+    /** Total frames captured since stream started */
+    totalFrames: number;
+    /** Frames that failed to capture */
+    droppedFrames: number;
+    /** Current measured FPS */
+    currentFps: number;
+    /** Configured target FPS */
+    targetFps: number;
+    /** Milliseconds since stream started */
+    uptimeMs: number;
+}
+/** Callback for frame events */
+export type FrameHandler = (frame: StreamFrame) => void;
+/**
+ * Real-time screen streaming engine.
+ *
+ * Provides continuous, non-blocking screen capture at up to 4K resolution
+ * and 120fps. The capture runs on a dedicated native thread, so it never
+ * blocks the Node.js event loop.
+ *
+ * @example
+ * ```typescript
+ * import { stream } from 'stelo';
+ *
+ * // Start 4K stream at 60fps
+ * stream.start({ fps: 60 });
+ *
+ * // Get latest frame for processing
+ * const frame = stream.latestFrame();
+ *
+ * // Get stream performance info
+ * const stats = stream.stats();
+ * console.log(`Running at ${stats.currentFps} fps`);
+ *
+ * // Subscribe to frames
+ * const unsub = stream.onFrame(frame => {
+ *   // Process every frame
+ * });
+ *
+ * // Async iteration
+ * for await (const frame of stream) {
+ *   await analyzeFrame(frame);
+ * }
+ *
+ * stream.stop();
+ * ```
+ */
+export declare const stream: {
+    _frameHandlers: FrameHandler[];
+    _pollTimer: ReturnType<typeof setInterval> | null;
+    _lastSequence: number;
+    /**
+     * Start a continuous real-time screen stream.
+     *
+     * The stream runs on a dedicated native thread and captures frames
+     * continuously at the configured FPS. Frames are double-buffered,
+     * so reading never blocks capture.
+     *
+     * @param config - Stream configuration (fps, region, scale, buffer)
+     */
+    start(config?: StreamConfig): void;
+    /**
+     * Stop the screen stream and release all resources.
+     */
+    stop(): void;
+    /**
+     * Check if a stream is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Get the latest captured frame.
+     * Returns null if no frames have been captured yet.
+     *
+    * This is the primary method for real-time automation — call it whenever
+     * you need the current screen state.
+     */
+    latestFrame(): StreamFrame | null;
+    /**
+     * Get the most recent N frames from the ring buffer.
+     * Useful for temporal analysis (motion detection, change tracking).
+     *
+     * @param count - Number of recent frames to retrieve (default: 3)
+     */
+    recentFrames(count?: number): StreamFrame[];
+    /**
+     * Wait for the next new frame (blocks until available or timeout).
+     * Returns null if timeout is reached before a new frame arrives.
+     *
+     * @param timeoutMs - Maximum time to wait in ms (default: 1000)
+     */
+    waitForFrame(timeoutMs?: number): StreamFrame | null;
+    /**
+     * Get stream performance statistics.
+     */
+    stats(): StreamStats;
+    /**
+     * Register a callback that fires for every new frame.
+     * Returns an unsubscribe function.
+     *
+     * @param handler - Function called with each new frame
+     * @returns Unsubscribe function
+     *
+     * @example
+     * ```typescript
+     * const unsub = stream.onFrame(frame => {
+     *   console.log(`Frame ${frame.sequence}: ${frame.width}x${frame.height}`);
+     * });
+     *
+     * // Later: stop receiving frames
+     * unsub();
+     * ```
+     */
+    onFrame(handler: FrameHandler): () => void;
+    /**
+     * Async iterator for frames. Yields new frames as they arrive.
+     *
+     * @example
+     * ```typescript
+     * stream.start({ fps: 30 });
+     * for await (const frame of stream) {
+     *   const result = await model.analyze(frame.data);
+     *   if (result.found) break;
+     * }
+     * stream.stop();
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<StreamFrame>;
+    /** @internal */
+    _startPollingIfNeeded(): void;
+    /** @internal */
+    _stopPolling(): void;
+};
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../ts/stream.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAMtC,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qCAAqC;AACrC,MAAM,WAAW,WAAW;IAC1B,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,gCAAgC;AAChC,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;AAIxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,MAAM;oBAEK,YAAY,EAAE;gBAChB,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI;;IAGzD;;;;;;;;OAQG;mBACY,YAAY,GAAG,IAAI;IA+BlC;;OAEG;YACK,IAAI;IAMZ;;OAEG;iBACU,OAAO;IAIpB;;;;;;OAMG;mBACY,WAAW,GAAG,IAAI;IAKjC;;;;;OAKG;yBACkB,MAAM,GAAG,WAAW,EAAE;IAK3C;;;;;OAKG;6BACsB,MAAM,GAAG,WAAW,GAAG,IAAI;IAKpD;;OAEG;aACM,WAAW;IAYpB;;;;;;;;;;;;;;;;OAgBG;qBACc,YAAY,GAAG,MAAM,IAAI;IAe1C;;;;;;;;;;;;OAYG;8BACuB,qBAAqB,CAAC,WAAW,CAAC;IAqB5D,gBAAgB;6BACS,IAAI;IA0B7B,gBAAgB;oBACA,IAAI;CAMrB,CAAC"}