screenhand 0.1.1 → 0.3.0

package/dist/src/memory/service.js

@@ -0,0 +1,446 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+/**
+ * MemoryService — unified facade over MemoryStore, SessionTracker, and RecallEngine
+ *
+ * Single entry-point for all memory operations. Adds:
+ * - state.json snapshot (debounced, written on every action)
+ * - learnings.jsonl (verified patterns, separate from strategies)
+ * - MemoryPolicy (error/stall thresholds)
+ * - Mission tracking
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomicSync } from "../util/atomic-write.js";
+import { MemoryStore } from "./store.js";
+import { SessionTracker } from "./session.js";
+import { RecallEngine } from "./recall.js";
+import { seedLearningsFromPlaybooks } from "./playbook-seeds.js";
+// ── Defaults ─────────────────────────────────────
+const DEFAULT_POLICY = {
+    maxConsecutiveErrors: 5,
+    stallThresholdMs: 300_000,
+    escalateAfterRetries: 3,
+    pauseBetweenActionsMs: 500,
+};
+const SNAPSHOT_DEBOUNCE_MS = 200;
+const MAX_LEARNINGS = 1000;
+// ── Service ──────────────────────────────────────
+export class MemoryService {
+    store;
+    session;
+    recall;
+    baseDir;
+    memDir;
+    learningsCache = [];
+    snapshot;
+    snapshotTimer = null;
+    consecutiveErrors = 0;
+    lastError = null;
+    actionsFailed = 0;
+    actionsTotal = 0;
+    sessionStartedAt;
+    initialized = false;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+        this.memDir = path.join(baseDir, ".screenhand", "memory");
+        this.store = new MemoryStore(baseDir);
+        this.session = new SessionTracker(this.store);
+        this.recall = new RecallEngine(this.store);
+        this.sessionStartedAt = new Date().toISOString();
+        this.snapshot = {
+            session: {
+                id: this.session.getSessionId(),
+                client: "unknown",
+                startedAt: this.sessionStartedAt,
+                lastActionAt: this.sessionStartedAt,
+            },
+            mission: { current: null, phase: "idle" },
+            health: {
+                actionsTotal: 0,
+                actionsFailed: 0,
+                successRate: 1,
+                lastError: null,
+                consecutiveErrors: 0,
+            },
+            patterns: { topWorking: [], topFailing: [], knownBlockers: [] },
+            policy: { ...DEFAULT_POLICY },
+        };
+    }
+    // ── Initialization ───────────────────────────────
+    /** Load all caches from disk. Call once at startup. */
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        this.store.init();
+        this.ensureMemDir();
+        // Load learnings
+        this.learningsCache = this.readJsonlSafe("learnings.jsonl");
+        // Seed learnings from playbooks — selectors, detection, policy notes.
+        // These have scope prefixes like "chrome/figma" so they merge cleanly
+        // with runtime-discovered learnings without duplicating.
+        const playbooksDir = path.join(this.baseDir, "references");
+        const pbLearnings = seedLearningsFromPlaybooks(playbooksDir);
+        if (pbLearnings.length > 0) {
+            const existingKeys = new Set(this.learningsCache.map(l => `${l.scope}::${l.pattern}::${l.method}`));
+            let added = 0;
+            for (const pl of pbLearnings) {
+                const key = `${pl.scope}::${pl.pattern}::${pl.method}`;
+                if (!existingKeys.has(key)) {
+                    this.learningsCache.push({
+                        id: `pb_lrn_${added}`,
+                        ...pl,
+                    });
+                    existingKeys.add(key);
+                    added++;
+                }
+            }
+        }
+        // Load existing snapshot if present (to restore mission/policy across restarts)
+        const snapPath = this.filePath("state.json");
+        if (fs.existsSync(snapPath)) {
+            try {
+                const raw = fs.readFileSync(snapPath, "utf-8");
+                const loaded = JSON.parse(raw);
+                // Restore mission and policy from previous run
+                if (loaded.mission)
+                    this.snapshot.mission = loaded.mission;
+                if (loaded.policy)
+                    this.snapshot.policy = { ...DEFAULT_POLICY, ...loaded.policy };
+            }
+            catch {
+                // Corrupted snapshot — start fresh
+            }
+        }
+        // Sync stats from store
+        const stats = this.store.getStats();
+        this.actionsTotal = stats.totalActions;
+        this.actionsFailed = stats.totalActions - Math.round(stats.successRate * stats.totalActions);
+        this.rebuildPatterns();
+        this.updateHealthInSnapshot();
+        this.writeSnapshotSync();
+    }
+    // ── Snapshot ─────────────────────────────────────
+    /** Get the current in-memory snapshot (zero-cost). */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    scheduleSnapshotWrite() {
+        if (this.snapshotTimer)
+            return;
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            this.writeSnapshotSync();
+        }, SNAPSHOT_DEBOUNCE_MS);
+    }
+    writeSnapshotSync() {
+        this.ensureMemDir();
+        try {
+            writeFileAtomicSync(this.filePath("state.json"), JSON.stringify(this.snapshot, null, 2));
+        }
+        catch {
+            // Non-critical
+        }
+    }
+    updateHealthInSnapshot() {
+        this.snapshot.health = {
+            actionsTotal: this.actionsTotal,
+            actionsFailed: this.actionsFailed,
+            successRate: this.actionsTotal > 0 ? (this.actionsTotal - this.actionsFailed) / this.actionsTotal : 1,
+            lastError: this.lastError,
+            consecutiveErrors: this.consecutiveErrors,
+        };
+    }
+    rebuildPatterns() {
+        // Top working: learnings with high confidence, sorted desc
+        const working = this.learningsCache
+            .filter((l) => l.confidence >= 0.6 && l.successCount > l.failCount)
+            .sort((a, b) => b.confidence - a.confidence)
+            .slice(0, 10)
+            .map((l) => `${l.scope}: ${l.pattern} (${l.method})`);
+        // Top failing: learnings with low confidence or high fail count
+        const failing = this.learningsCache
+            .filter((l) => l.failCount > l.successCount)
+            .sort((a, b) => b.failCount - a.failCount)
+            .slice(0, 10)
+            .map((l) => `${l.scope}: ${l.pattern} (${l.method})`);
+        // Known blockers: errors with no resolution
+        const errors = this.store.readErrors();
+        const blockers = errors
+            .filter((e) => !e.resolution && e.occurrences >= 2)
+            .sort((a, b) => b.occurrences - a.occurrences)
+            .slice(0, 10)
+            .map((e) => `${e.tool}: ${e.error}`);
+        this.snapshot.patterns = {
+            topWorking: working,
+            topFailing: failing,
+            knownBlockers: blockers,
+        };
+    }
+    // ── Recording ────────────────────────────────────
+    /** Record an action event. Delegates to store + session tracker, updates snapshot. */
+    recordEvent(entry) {
+        this.store.appendAction(entry);
+        this.session.recordAction(entry);
+        this.actionsTotal++;
+        if (!entry.success) {
+            this.actionsFailed++;
+            this.consecutiveErrors++;
+            this.lastError = entry.error;
+        }
+        else {
+            this.consecutiveErrors = 0;
+        }
+        this.snapshot.session.id = this.session.getSessionId();
+        this.snapshot.session.lastActionAt = entry.timestamp;
+        this.updateHealthInSnapshot();
+        this.scheduleSnapshotWrite();
+    }
+    /** Record an error pattern. Delegates to store, optionally creates a learning. */
+    recordError(tool, error, fix, scope) {
+        const pattern = {
+            id: "err_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+            tool,
+            params: {},
+            error,
+            resolution: fix,
+            occurrences: 1,
+            lastSeen: new Date().toISOString(),
+        };
+        this.store.appendError(pattern);
+        // If a fix is provided, record it as a learning
+        if (fix && scope) {
+            this.recordLearning({
+                scope,
+                pattern: error,
+                method: "ax",
+                confidence: 0.5,
+                successCount: 0,
+                failCount: 1,
+                lastSeen: new Date().toISOString(),
+                fix,
+            });
+        }
+        this.rebuildPatterns();
+        this.scheduleSnapshotWrite();
+    }
+    // ── Learnings ────────────────────────────────────
+    /** Append a verified learning to learnings.jsonl. */
+    recordLearning(learning) {
+        const full = {
+            id: "lrn_" + Date.now().toString(36) + Math.random().toString(36).slice(2, 6),
+            ...learning,
+        };
+        // Check for existing learning with same scope + pattern + method
+        const idx = this.learningsCache.findIndex((l) => l.scope === full.scope && l.pattern === full.pattern && l.method === full.method);
+        if (idx >= 0) {
+            const existing = this.learningsCache[idx];
+            this.learningsCache[idx] = {
+                ...existing,
+                successCount: existing.successCount + full.successCount,
+                failCount: existing.failCount + full.failCount,
+                confidence: this.computeConfidence(existing.successCount + full.successCount, existing.failCount + full.failCount),
+                lastSeen: full.lastSeen,
+                fix: full.fix ?? existing.fix,
+            };
+        }
+        else {
+            this.learningsCache.push(full);
+            this.enforceLearningsLimit();
+        }
+        this.writeLearningsAsync();
+        this.rebuildPatterns();
+        this.scheduleSnapshotWrite();
+    }
+    /** Search learnings by scope and/or method. */
+    queryPatterns(scope, method) {
+        let results = this.learningsCache;
+        if (scope) {
+            results = results.filter((l) => l.scope === scope || l.scope.startsWith(scope + "/"));
+        }
+        if (method) {
+            results = results.filter((l) => l.method === method);
+        }
+        return results;
+    }
+    computeConfidence(success, fail) {
+        const total = success + fail;
+        if (total === 0)
+            return 0;
+        return success / total;
+    }
+    enforceLearningsLimit() {
+        if (this.learningsCache.length <= MAX_LEARNINGS)
+            return;
+        // Evict lowest-confidence, oldest learnings
+        this.learningsCache.sort((a, b) => {
+            const confDiff = a.confidence - b.confidence;
+            if (Math.abs(confDiff) > 0.1)
+                return confDiff;
+            return new Date(a.lastSeen).getTime() - new Date(b.lastSeen).getTime();
+        });
+        this.learningsCache = this.learningsCache.slice(-MAX_LEARNINGS);
+    }
+    writeLearningsAsync() {
+        this.ensureMemDir();
+        const data = this.learningsCache.map((l) => JSON.stringify(l)).join("\n") + (this.learningsCache.length ? "\n" : "");
+        fs.writeFile(this.filePath("learnings.jsonl"), data, () => { });
+    }
+    // ── Recall (delegates to RecallEngine) ───────────
+    /** Search error patterns, optionally filtered by tool. */
+    queryErrors(tool) {
+        return this.recall.recallErrors(tool);
+    }
+    /** Fuzzy-match strategies by query string. Optionally filter by current app. */
+    recallStrategies(query, limit, currentBundleId) {
+        return this.recall.recallStrategies(query, limit, currentBundleId);
+    }
+    /** Quick error check for interceptor (~0ms). */
+    quickErrorCheck(tool) {
+        return this.recall.quickErrorCheck(tool);
+    }
+    /** Quick strategy hint for interceptor (~0ms). */
+    quickStrategyHint(recentTools, currentBundleId) {
+        return this.recall.quickStrategyHint(recentTools, currentBundleId);
+    }
+    /** Record strategy outcome for feedback loop. */
+    recordStrategyOutcome(fingerprint, success) {
+        this.store.recordStrategyOutcome(fingerprint, success);
+    }
+    // ── Session / Strategy ───────────────────────────
+    /** Get the current session ID. */
+    getSessionId() {
+        return this.session.getSessionId();
+    }
+    /** Get recent tool names from session buffer. */
+    getRecentToolNames(limit) {
+        return this.session.getRecentToolNames(limit);
+    }
+    /** End current session and save a strategy if successful. */
+    saveStrategy(task, tags) {
+        const strategy = this.session.endSession(true, task);
+        if (strategy && tags && tags.length > 0) {
+            // Merge additional tags
+            const merged = new Set([...strategy.tags, ...tags]);
+            strategy.tags = [...merged];
+        }
+        return strategy;
+    }
+    /** Read raw actions from store (for exports/playbooks). */
+    readActions() {
+        return this.store.readActions();
+    }
+    /** Read raw errors from store. */
+    readErrors() {
+        return this.store.readErrors();
+    }
+    /** Read raw strategies from store. */
+    readStrategies() {
+        return this.store.readStrategies();
+    }
+    /** Append an error pattern directly (for interceptor compatibility). */
+    appendError(pattern) {
+        this.store.appendError(pattern);
+    }
+    /** Append a strategy directly. */
+    appendStrategy(strategy) {
+        this.store.appendStrategy(strategy);
+    }
+    // ── Stats ────────────────────────────────────────
+    /** Get aggregate memory stats. */
+    getStats() {
+        return this.store.getStats();
+    }
+    // ── Mission ──────────────────────────────────────
+    /** Set the current mission and optionally a phase. */
+    setMission(mission, phase) {
+        this.snapshot.mission.current = mission;
+        if (phase)
+            this.snapshot.mission.phase = phase;
+        this.scheduleSnapshotWrite();
+    }
+    /** Set the client identifier (e.g., "claude-code", "mcp-desktop"). */
+    setClient(client) {
+        this.snapshot.session.client = client;
+        this.scheduleSnapshotWrite();
+    }
+    // ── Clear ────────────────────────────────────────
+    /** Clear specific memory categories or everything. */
+    clear(what) {
+        if (what === "learnings" || what === "all") {
+            this.learningsCache = [];
+            const fp = this.filePath("learnings.jsonl");
+            if (fs.existsSync(fp))
+                fs.writeFileSync(fp, "");
+        }
+        if (what !== "learnings") {
+            // Delegate non-learnings clears to the store
+            const storeWhat = what === "all" ? "all" : what;
+            this.store.clear(storeWhat);
+        }
+        if (what === "all" || what === "actions") {
+            this.actionsTotal = 0;
+            this.actionsFailed = 0;
+            this.consecutiveErrors = 0;
+            this.lastError = null;
+        }
+        this.updateHealthInSnapshot();
+        this.rebuildPatterns();
+        this.writeSnapshotSync();
+    }
+    // ── Helpers ──────────────────────────────────────
+    ensureMemDir() {
+        if (!fs.existsSync(this.memDir)) {
+            fs.mkdirSync(this.memDir, { recursive: true });
+        }
+    }
+    filePath(name) {
+        return path.join(this.memDir, name);
+    }
+    readJsonlSafe(file) {
+        const fp = this.filePath(file);
+        if (!fs.existsSync(fp))
+            return [];
+        let text;
+        try {
+            // Guard against oversized files (same 10MB limit as LearningEngine)
+            const stat = fs.statSync(fp);
+            if (stat.size > 10 * 1024 * 1024)
+                return [];
+            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
+            }
+        }
+        return results;
+    }
+}

package/dist/src/memory/session.js

@@ -0,0 +1,169 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+//
+// This file is part of ScreenHand.
+//
+// ScreenHand is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as
+// published by the Free Software Foundation, version 3.
+//
+// ScreenHand is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+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];
+}