screenhand 0.2.0 → 0.3.1

package/dist/memory/seeds.js

@@ -1,89 +0,0 @@
-/**
- * Predefined seed strategies — common macOS desktop workflows.
- * Loaded on first boot so the memory system has knowledge from day one.
- */
-let seedCounter = 0;
-function makeFingerprint(tools) {
-    return tools.join("→");
-}
-function seed(task, steps, tags) {
-    seedCounter++;
-    return {
-        id: `seed_${String(seedCounter).padStart(3, "0")}`,
-        task,
-        steps,
-        totalDurationMs: 0,
-        successCount: 10,
-        failCount: 0,
-        lastUsed: new Date().toISOString(),
-        tags,
-        fingerprint: makeFingerprint(steps.map((s) => s.tool)),
-    };
-}
-export const SEED_STRATEGIES = [
-    // 1. Take a photo with Photo Booth
-    seed("Take a photo with Photo Booth", [
-        { tool: "launch", params: { bundleId: "com.apple.PhotoBooth" } },
-        { tool: "ui_press", params: { title: "Take Photo" } },
-    ], ["photo", "booth", "camera"]),
-    // 2. Open a URL in Chrome
-    seed("Open a URL in Chrome", [
-        { tool: "launch", params: { bundleId: "com.google.Chrome" } },
-        { tool: "browser_navigate", params: { url: "" } },
-    ], ["chrome", "browse", "url"]),
-    // 3. Save current document
-    seed("Save current document", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "key", params: { combo: "cmd+s" } },
-    ], ["save", "document"]),
-    // 4. Copy from one app and paste into another
-    seed("Copy from one app and paste into another", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "key", params: { combo: "cmd+c" } },
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "key", params: { combo: "cmd+v" } },
-    ], ["copy", "paste"]),
-    // 5. Navigate to a folder in Finder
-    seed("Navigate to a folder in Finder", [
-        { tool: "focus", params: { bundleId: "com.apple.finder" } },
-        { tool: "key", params: { combo: "cmd+shift+g" } },
-        { tool: "type_text", params: { text: "" } },
-    ], ["finder", "folder", "navigate"]),
-    // 6. Create a new folder in Finder
-    seed("Create a new folder in Finder", [
-        { tool: "focus", params: { bundleId: "com.apple.finder" } },
-        { tool: "key", params: { combo: "cmd+shift+n" } },
-        { tool: "type_text", params: { text: "" } },
-    ], ["finder", "folder", "create"]),
-    // 7. Close the current window
-    seed("Close the current window", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "key", params: { combo: "cmd+w" } },
-    ], ["close", "window"]),
-    // 8. Select all and copy
-    seed("Select all content and copy", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "key", params: { combo: "cmd+a" } },
-        { tool: "key", params: { combo: "cmd+c" } },
-    ], ["select", "all", "copy"]),
-    // 9. List running apps
-    seed("List all running applications", [
-        { tool: "apps", params: {} },
-    ], ["apps", "list", "running"]),
-    // 10. Inspect app UI tree
-    seed("Inspect an app's UI element tree", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "ui_tree", params: { pid: 0 } },
-    ], ["inspect", "tree", "accessibility"]),
-    // 11. Open a new tab in Chrome and navigate
-    seed("Open a new Chrome tab and navigate to URL", [
-        { tool: "focus", params: { bundleId: "com.google.Chrome" } },
-        { tool: "key", params: { combo: "cmd+t" } },
-        { tool: "browser_navigate", params: { url: "" } },
-    ], ["chrome", "tab", "new"]),
-    // 12. Export as PDF via menu
-    seed("Export document as PDF", [
-        { tool: "focus", params: { bundleId: "" } },
-        { tool: "menu_click", params: { menuPath: "File/Export as PDF" } },
-    ], ["export", "pdf"]),
-];

package/dist/memory/session.js

@@ -1,161 +0,0 @@
-/**
- * Learning Memory — Session tracking with auto-save
- *
- * Tracks a rolling buffer of actions within a "task session".
- * Auto-saves strategies when a successful sequence is detected:
- * - 3+ consecutive successes followed by a gap (>60s) or session end
- * - Or explicit endSession() call
- */
-import { MemoryStore } from "./store.js";
-const SESSION_GAP_MS = 60_000; // 60s gap = new session
-const MAX_BUFFER_SIZE = 100;
-const MIN_AUTO_SAVE_STEPS = 3; // Need at least 3 successful steps to auto-save
-export class SessionTracker {
-    store;
-    sessionId;
-    taskDescription = null;
-    buffer = [];
-    lastActionTime = 0;
-    constructor(store) {
-        this.store = store;
-        this.sessionId = SessionTracker.generateId();
-    }
-    static generateId() {
-        return "s_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
-    }
-    /** Start (or restart) a named task session */
-    startSession(taskDescription) {
-        // Auto-save previous session if it had successful actions
-        this.tryAutoSave();
-        this.sessionId = SessionTracker.generateId();
-        this.taskDescription = taskDescription ?? null;
-        this.buffer = [];
-        this.lastActionTime = Date.now();
-        return this.sessionId;
-    }
-    /** Get the current session ID, auto-rotating if stale */
-    getSessionId() {
-        const now = Date.now();
-        if (this.lastActionTime > 0 && now - this.lastActionTime > SESSION_GAP_MS) {
-            // Session gap detected — auto-save previous sequence then start fresh
-            this.tryAutoSave();
-            this.sessionId = SessionTracker.generateId();
-            this.buffer = [];
-            this.taskDescription = null;
-        }
-        return this.sessionId;
-    }
-    /** Record an action into the current session buffer */
-    recordAction(entry) {
-        const now = Date.now();
-        if (this.lastActionTime > 0 && now - this.lastActionTime > SESSION_GAP_MS) {
-            // Gap detected — auto-save then start new session
-            this.tryAutoSave();
-            this.sessionId = SessionTracker.generateId();
-            this.buffer = [];
-            this.taskDescription = null;
-        }
-        this.lastActionTime = now;
-        this.buffer.push(entry);
-        if (this.buffer.length > MAX_BUFFER_SIZE) {
-            this.buffer.shift();
-        }
-    }
-    /** End the session and save a strategy if successful */
-    endSession(success, taskDescription) {
-        const task = taskDescription ?? this.taskDescription;
-        if (!success || !task || this.buffer.length === 0) {
-            this.buffer = [];
-            return null;
-        }
-        const strategy = this.buildStrategy(task, this.buffer);
-        this.store.appendStrategy(strategy);
-        this.buffer = [];
-        return strategy;
-    }
-    /** Get the current session's action buffer */
-    getBuffer() {
-        return [...this.buffer];
-    }
-    /** Get recent tool names (for strategy hint matching) */
-    getRecentToolNames(limit = 10) {
-        return this.buffer.slice(-limit).map((a) => a.tool);
-    }
-    /** Get current task description */
-    getTaskDescription() {
-        return this.taskDescription;
-    }
-    // ── auto-save logic ────────────────────────────
-    /**
-     * Try to auto-save the current buffer as a strategy.
-     * Only saves if there are MIN_AUTO_SAVE_STEPS+ consecutive successes.
-     * Uses tool sequence as task description if no explicit one was given.
-     */
-    tryAutoSave() {
-        if (this.buffer.length < MIN_AUTO_SAVE_STEPS)
-            return;
-        // Find the longest trailing streak of successes
-        let successStreak = [];
-        for (let i = this.buffer.length - 1; i >= 0; i--) {
-            if (this.buffer[i].success) {
-                successStreak.unshift(this.buffer[i]);
-            }
-            else {
-                break;
-            }
-        }
-        if (successStreak.length < MIN_AUTO_SAVE_STEPS)
-            return;
-        // Build a task description from the tool sequence if none provided
-        const task = this.taskDescription ?? this.inferTaskDescription(successStreak);
-        const strategy = this.buildStrategy(task, successStreak);
-        this.store.appendStrategy(strategy);
-    }
-    /** Infer a task description from a sequence of actions */
-    inferTaskDescription(actions) {
-        const tools = [...new Set(actions.map((a) => a.tool))];
-        // Extract key param values (bundle IDs, titles, URLs, etc.)
-        const keyParams = [];
-        for (const a of actions) {
-            for (const [key, val] of Object.entries(a.params)) {
-                if (typeof val === "string" && val.length > 2 && val.length < 60) {
-                    if (["bundleId", "title", "url", "text", "script", "selector", "menuPath"].includes(key)) {
-                        keyParams.push(val);
-                    }
-                }
-            }
-        }
-        const paramHint = keyParams.length > 0 ? ` (${keyParams.slice(0, 3).join(", ")})` : "";
-        return `${tools.join(" → ")}${paramHint}`;
-    }
-    buildStrategy(task, actions) {
-        const steps = actions.map((a) => ({
-            tool: a.tool,
-            params: a.params,
-        }));
-        const totalDurationMs = actions.reduce((sum, a) => sum + a.durationMs, 0);
-        const tags = extractTags(task, steps);
-        const fingerprint = MemoryStore.makeFingerprint(steps.map((s) => s.tool));
-        return {
-            id: "str_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
-            task,
-            steps,
-            totalDurationMs,
-            successCount: 1,
-            failCount: 0,
-            lastUsed: new Date().toISOString(),
-            tags,
-            fingerprint,
-        };
-    }
-}
-/** Extract tags from task description and tool names */
-function extractTags(task, steps) {
-    const tags = new Set();
-    const words = task.toLowerCase().split(/\W+/).filter((w) => w.length >= 3);
-    for (const w of words)
-        tags.add(w);
-    for (const s of steps)
-        tags.add(s.tool);
-    return [...tags];
-}

package/dist/memory/store.js

@@ -1,391 +0,0 @@
-/**
- * Learning Memory — JSONL persistence layer (production-ready)
- *
- * - All data cached in-memory for zero-latency reads
- * - Disk writes are non-blocking, buffered, flushed on exit
- * - Per-line JSONL parsing — corrupted lines are skipped, not fatal
- * - Cache size limits with LRU eviction
- * - File locking for multi-instance safety
- */
-import fs from "node:fs";
-import path from "node:path";
-import { SEED_STRATEGIES } from "./seeds.js";
-const MAX_ACTION_FILE_BYTES = 10 * 1024 * 1024; // 10 MB
-const MAX_STRATEGIES = 500;
-const MAX_ERRORS = 200;
-export class MemoryStore {
-    dir;
-    // ── in-memory caches ──
-    strategiesCache = [];
-    errorsCache = [];
-    /** Fingerprint → Strategy index for O(1) exact lookup */
-    fingerprintIndex = new Map();
-    actionCount = 0;
-    actionSuccessCount = 0;
-    toolCounts = new Map();
-    initialized = false;
-    dirCreated = false;
-    /** True if ensureDir() had to create the memory directory (first boot) */
-    justCreatedDir = false;
-    // ── write buffer for flush-on-exit ──
-    pendingActionWrites = [];
-    flushTimer = null;
-    lockPath;
-    hasLock = false;
-    // Global flag — only register exit handlers once across all instances
-    static exitHandlerRegistered = false;
-    static activeInstance = null;
-    constructor(baseDir) {
-        this.dir = path.join(baseDir, ".screenhand", "memory");
-        this.lockPath = path.join(this.dir, ".lock");
-    }
-    /** Load caches from disk. Call once at startup. */
-    init() {
-        if (this.initialized)
-            return;
-        this.initialized = true;
-        this.ensureDir();
-        this.acquireLock();
-        this.registerExitHandler();
-        // Detect first boot: memory directory was just created (didn't exist before ensureDir)
-        const isFirstBoot = this.justCreatedDir;
-        this.strategiesCache = this.readLinesSafe("strategies.jsonl");
-        if (this.strategiesCache.length === 0 && isFirstBoot) {
-            for (const s of SEED_STRATEGIES)
-                this.strategiesCache.push(s);
-            this.writeLinesAsync("strategies.jsonl", this.strategiesCache);
-        }
-        this.enforceStrategyLimit();
-        this.rebuildFingerprintIndex();
-        this.errorsCache = this.readLinesSafe("errors.jsonl");
-        this.enforceErrorLimit();
-        // Build action stats without caching all entries
-        const actions = this.readLinesSafe("actions.jsonl");
-        this.actionCount = actions.length;
-        for (const a of actions) {
-            if (a.success)
-                this.actionSuccessCount++;
-            this.toolCounts.set(a.tool, (this.toolCounts.get(a.tool) ?? 0) + 1);
-        }
-    }
-    // ── file locking ──────────────────────────────
-    acquireLock() {
-        try {
-            // Check for stale lock (PID no longer running)
-            if (fs.existsSync(this.lockPath)) {
-                const lockContent = fs.readFileSync(this.lockPath, "utf-8").trim();
-                const lockPid = parseInt(lockContent, 10);
-                if (lockPid && !this.isProcessRunning(lockPid)) {
-                    // Stale lock — remove it
-                    fs.unlinkSync(this.lockPath);
-                }
-            }
-            // Write our PID
-            fs.writeFileSync(this.lockPath, String(process.pid), { flag: "wx" });
-            this.hasLock = true;
-        }
-        catch {
-            // Another instance holds the lock — we still work but skip writes
-            // to avoid corruption. Reads are from our own cache (stale but safe).
-            this.hasLock = false;
-        }
-    }
-    releaseLock() {
-        if (this.hasLock) {
-            try {
-                fs.unlinkSync(this.lockPath);
-            }
-            catch { /* ignore */ }
-            this.hasLock = false;
-        }
-    }
-    isProcessRunning(pid) {
-        try {
-            process.kill(pid, 0);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    // ── exit handling ─────────────────────────────
-    registerExitHandler() {
-        MemoryStore.activeInstance = this;
-        if (MemoryStore.exitHandlerRegistered)
-            return;
-        MemoryStore.exitHandlerRegistered = true;
-        const flush = () => MemoryStore.activeInstance?.flushSync();
-        process.on("beforeExit", flush);
-        process.on("exit", flush);
-        // SIGINT/SIGTERM — flush then re-raise
-        for (const sig of ["SIGINT", "SIGTERM"]) {
-            process.on(sig, () => {
-                flush();
-                process.exit(128 + (sig === "SIGINT" ? 2 : 15));
-            });
-        }
-    }
-    /** Synchronously flush all pending action writes to disk */
-    flushSync() {
-        if (this.pendingActionWrites.length === 0)
-            return;
-        if (!this.hasLock)
-            return;
-        try {
-            this.ensureDir();
-            const data = this.pendingActionWrites.join("");
-            fs.appendFileSync(this.filePath("actions.jsonl"), data);
-            this.pendingActionWrites = [];
-        }
-        catch {
-            // Non-critical on exit
-        }
-        this.releaseLock();
-    }
-    // ── helpers ────────────────────────────────────
-    ensureDir() {
-        if (!this.dirCreated) {
-            if (!fs.existsSync(this.dir)) {
-                fs.mkdirSync(this.dir, { recursive: true });
-                this.justCreatedDir = true;
-            }
-            this.dirCreated = true;
-        }
-    }
-    filePath(name) {
-        return path.join(this.dir, name);
-    }
-    /**
-     * Parse JSONL safely — skip corrupted lines instead of crashing.
-     * Returns all successfully parsed entries.
-     */
-    readLinesSafe(file) {
-        const fp = this.filePath(file);
-        if (!fs.existsSync(fp))
-            return [];
-        let text;
-        try {
-            text = fs.readFileSync(fp, "utf-8").trim();
-        }
-        catch {
-            return [];
-        }
-        if (!text)
-            return [];
-        const results = [];
-        for (const line of text.split("\n")) {
-            const trimmed = line.trim();
-            if (!trimmed)
-                continue;
-            try {
-                results.push(JSON.parse(trimmed));
-            }
-            catch {
-                // Skip corrupted line — don't crash
-            }
-        }
-        return results;
-    }
-    /** Non-blocking full rewrite — fire and forget (only if we hold lock) */
-    writeLinesAsync(file, items) {
-        if (!this.hasLock)
-            return;
-        this.ensureDir();
-        const data = items.map((i) => JSON.stringify(i)).join("\n") + (items.length ? "\n" : "");
-        fs.writeFile(this.filePath(file), data, () => { });
-    }
-    fileSize(file) {
-        const fp = this.filePath(file);
-        if (!fs.existsSync(fp))
-            return 0;
-        try {
-            return fs.statSync(fp).size;
-        }
-        catch {
-            return 0;
-        }
-    }
-    // ── actions (buffered async write) ─────────────
-    appendAction(entry) {
-        // Update in-memory stats
-        this.actionCount++;
-        if (entry.success)
-            this.actionSuccessCount++;
-        this.toolCounts.set(entry.tool, (this.toolCounts.get(entry.tool) ?? 0) + 1);
-        if (!this.hasLock)
-            return;
-        this.rotateActionsIfNeeded();
-        // Buffer the write
-        this.pendingActionWrites.push(JSON.stringify(entry) + "\n");
-        // Schedule batch flush (debounced 100ms)
-        if (!this.flushTimer) {
-            this.flushTimer = setTimeout(() => {
-                this.flushTimer = null;
-                if (this.pendingActionWrites.length === 0)
-                    return;
-                this.ensureDir();
-                const data = this.pendingActionWrites.join("");
-                this.pendingActionWrites = [];
-                fs.appendFile(this.filePath("actions.jsonl"), data, () => { });
-            }, 100);
-        }
-    }
-    rotateActionsIfNeeded() {
-        if (this.fileSize("actions.jsonl") >= MAX_ACTION_FILE_BYTES) {
-            const src = this.filePath("actions.jsonl");
-            const dst = this.filePath("actions.1.jsonl");
-            try {
-                if (fs.existsSync(dst))
-                    fs.unlinkSync(dst);
-                fs.renameSync(src, dst);
-            }
-            catch {
-                // Non-critical
-            }
-        }
-    }
-    /** Read actions from disk (only used by stats/clear, not in hot path) */
-    readActions() {
-        return this.readLinesSafe("actions.jsonl");
-    }
-    // ── strategies (cached + fingerprint indexed + LRU capped) ──
-    rebuildFingerprintIndex() {
-        this.fingerprintIndex.clear();
-        for (const s of this.strategiesCache) {
-            if (s.fingerprint) {
-                this.fingerprintIndex.set(s.fingerprint, s);
-            }
-        }
-    }
-    /** Evict least-recently-used strategies beyond MAX_STRATEGIES */
-    enforceStrategyLimit() {
-        if (this.strategiesCache.length <= MAX_STRATEGIES)
-            return;
-        // Sort by lastUsed ascending (oldest first), remove from the front
-        this.strategiesCache.sort((a, b) => new Date(a.lastUsed).getTime() - new Date(b.lastUsed).getTime());
-        this.strategiesCache = this.strategiesCache.slice(-MAX_STRATEGIES);
-    }
-    appendStrategy(strategy) {
-        // Ensure fingerprint exists
-        if (!strategy.fingerprint) {
-            strategy.fingerprint = MemoryStore.makeFingerprint(strategy.steps.map((s) => s.tool));
-        }
-        const idx = this.strategiesCache.findIndex((s) => s.task === strategy.task);
-        if (idx >= 0) {
-            const old = this.strategiesCache[idx];
-            this.strategiesCache[idx] = {
-                ...strategy,
-                successCount: old.successCount + 1,
-                failCount: old.failCount ?? 0,
-                lastUsed: strategy.lastUsed,
-            };
-            this.fingerprintIndex.set(strategy.fingerprint, this.strategiesCache[idx]);
-        }
-        else {
-            this.strategiesCache.push(strategy);
-            this.fingerprintIndex.set(strategy.fingerprint, strategy);
-            this.enforceStrategyLimit();
-            // Rebuild index after eviction
-            if (this.strategiesCache.length >= MAX_STRATEGIES) {
-                this.rebuildFingerprintIndex();
-            }
-        }
-        this.writeLinesAsync("strategies.jsonl", this.strategiesCache);
-    }
-    /** O(1) exact lookup by tool sequence fingerprint */
-    lookupByFingerprint(fingerprint) {
-        return this.fingerprintIndex.get(fingerprint);
-    }
-    /** Record that a recalled strategy succeeded or failed */
-    recordStrategyOutcome(fingerprint, success) {
-        const strategy = this.fingerprintIndex.get(fingerprint);
-        if (!strategy)
-            return;
-        if (success) {
-            strategy.successCount++;
-            strategy.lastUsed = new Date().toISOString();
-        }
-        else {
-            strategy.failCount = (strategy.failCount ?? 0) + 1;
-        }
-        this.writeLinesAsync("strategies.jsonl", this.strategiesCache);
-    }
-    /** Read from cache — ~0ms */
-    readStrategies() {
-        return this.strategiesCache;
-    }
-    /** Generate a fingerprint from a tool sequence */
-    static makeFingerprint(tools) {
-        return tools.join("→");
-    }
-    // ── errors (cached + LRU capped) ──────────────
-    /** Evict least-recently-seen errors beyond MAX_ERRORS */
-    enforceErrorLimit() {
-        if (this.errorsCache.length <= MAX_ERRORS)
-            return;
-        this.errorsCache.sort((a, b) => new Date(a.lastSeen).getTime() - new Date(b.lastSeen).getTime());
-        this.errorsCache = this.errorsCache.slice(-MAX_ERRORS);
-    }
-    appendError(pattern) {
-        const idx = this.errorsCache.findIndex((e) => e.tool === pattern.tool && e.error === pattern.error);
-        if (idx >= 0) {
-            this.errorsCache[idx] = {
-                ...this.errorsCache[idx],
-                occurrences: this.errorsCache[idx].occurrences + 1,
-                lastSeen: pattern.lastSeen,
-                resolution: pattern.resolution ?? this.errorsCache[idx].resolution,
-            };
-        }
-        else {
-            this.errorsCache.push(pattern);
-            this.enforceErrorLimit();
-        }
-        this.writeLinesAsync("errors.jsonl", this.errorsCache);
-    }
-    /** Read from cache — ~0ms */
-    readErrors() {
-        return this.errorsCache;
-    }
-    // ── stats (from in-memory counters) ────────────
-    getStats() {
-        const topTools = [...this.toolCounts.entries()]
-            .sort((a, b) => b[1] - a[1])
-            .slice(0, 10)
-            .map(([tool, count]) => ({ tool, count }));
-        const diskUsageBytes = this.fileSize("actions.jsonl") +
-            this.fileSize("strategies.jsonl") +
-            this.fileSize("errors.jsonl");
-        return {
-            totalActions: this.actionCount,
-            totalStrategies: this.strategiesCache.length,
-            totalErrors: this.errorsCache.length,
-            diskUsageBytes,
-            topTools,
-            successRate: this.actionCount > 0 ? this.actionSuccessCount / this.actionCount : 0,
-        };
-    }
-    // ── clear ──────────────────────────────────────
-    clear(what) {
-        const targets = what === "all"
-            ? ["actions", "strategies", "errors"]
-            : [what];
-        for (const category of targets) {
-            const fp = this.filePath(`${category}.jsonl`);
-            if (fs.existsSync(fp))
-                fs.writeFileSync(fp, "");
-            if (category === "actions") {
-                this.actionCount = 0;
-                this.actionSuccessCount = 0;
-                this.toolCounts.clear();
-                this.pendingActionWrites = [];
-            }
-            else if (category === "strategies") {
-                this.strategiesCache = [];
-                this.fingerprintIndex.clear();
-            }
-            else if (category === "errors") {
-                this.errorsCache = [];
-            }
-        }
-    }
-}

package/dist/memory/types.js

@@ -1,4 +0,0 @@
-/**
- * Learning Memory — Data types
- */
-export {};