screenhand 0.1.1 → 0.3.0

package/dist/src/jobs/store.js

@@ -0,0 +1,102 @@
+// 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/>.
+/**
+ * JobStore — atomic JSON persistence for jobs.
+ *
+ * All jobs are cached in memory. Writes are sync + atomic (temp+rename).
+ * File: jobs.json (array of Job objects).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomicSync, readJsonWithRecovery } from "../util/atomic-write.js";
+const MAX_COMPLETED_JOBS = 200;
+export class JobStore {
+    filePath;
+    jobs = [];
+    initialized = false;
+    constructor(dir) {
+        fs.mkdirSync(dir, { recursive: true });
+        this.filePath = path.join(dir, "jobs.json");
+    }
+    init() {
+        if (this.initialized)
+            return;
+        this.initialized = true;
+        this.jobs = readJsonWithRecovery(this.filePath) ?? [];
+    }
+    /** Get all jobs, optionally filtered by state. */
+    list(state) {
+        if (state)
+            return this.jobs.filter((j) => j.state === state);
+        return [...this.jobs];
+    }
+    /** Get a single job by ID. */
+    get(id) {
+        return this.jobs.find((j) => j.id === id);
+    }
+    /** Insert a new job. */
+    add(job) {
+        this.jobs.push(job);
+        this.persist();
+    }
+    /** Update an existing job in place, then persist. */
+    update(id, patch) {
+        const idx = this.jobs.findIndex((j) => j.id === id);
+        if (idx < 0)
+            return undefined;
+        this.jobs[idx] = { ...this.jobs[idx], ...patch, updatedAt: new Date().toISOString() };
+        this.persist();
+        return this.jobs[idx];
+    }
+    /** Remove a job by ID. */
+    remove(id) {
+        const before = this.jobs.length;
+        this.jobs = this.jobs.filter((j) => j.id !== id);
+        if (this.jobs.length < before) {
+            this.persist();
+            return true;
+        }
+        return false;
+    }
+    /** Evict old completed/failed jobs beyond the cap. */
+    prune() {
+        const terminal = this.jobs
+            .filter((j) => j.state === "done" || j.state === "failed")
+            .sort((a, b) => new Date(a.updatedAt).getTime() - new Date(b.updatedAt).getTime());
+        if (terminal.length <= MAX_COMPLETED_JOBS)
+            return 0;
+        const evictCount = terminal.length - MAX_COMPLETED_JOBS;
+        const evictIds = new Set(terminal.slice(0, evictCount).map((j) => j.id));
+        this.jobs = this.jobs.filter((j) => !evictIds.has(j.id));
+        this.persist();
+        return evictCount;
+    }
+    /** Next queued job by priority (lower number = higher priority), then creation order. */
+    nextQueued() {
+        return this.jobs
+            .filter((j) => j.state === "queued")
+            .sort((a, b) => a.priority - b.priority || new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime())[0];
+    }
+    persist() {
+        try {
+            writeFileAtomicSync(this.filePath, JSON.stringify(this.jobs, null, 2));
+        }
+        catch {
+            // Non-critical — in-memory cache is authoritative
+        }
+    }
+}

package/dist/src/jobs/types.js

@@ -0,0 +1,30 @@
+// 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/>.
+/**
+ * Job layer types — persistent multi-step automation jobs
+ * with state machine, playbook resume, and supervisor integration.
+ */
+export const JOB_STATES = ["queued", "running", "blocked", "waiting_human", "done", "failed"];
+/** Transition rules: state → allowed next states */
+export const VALID_TRANSITIONS = {
+    queued: ["running", "failed"],
+    running: ["blocked", "waiting_human", "done", "failed"],
+    blocked: ["running", "waiting_human", "failed"],
+    waiting_human: ["running", "failed"],
+    done: [], // terminal
+    failed: ["queued"], // can re-queue
+};

package/dist/src/jobs/worker.js

@@ -0,0 +1,97 @@
+// 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/>.
+/**
+ * JobWorker — persistent state for the worker daemon.
+ *
+ * The actual daemon runs as a separate process (scripts/worker-daemon.ts).
+ * This module provides the state types and filesystem persistence
+ * shared between the daemon and the MCP tools that query/control it.
+ *
+ * State directory: ~/.screenhand/worker/
+ * Files: state.json, worker.pid, worker.log
+ */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { writeFileAtomicSync, readJsonWithRecovery } from "../util/atomic-write.js";
+/** Default worker directory — used by MCP tools and the daemon. */
+export const WORKER_DIR = path.join(os.homedir(), ".screenhand", "worker");
+export const WORKER_PID_FILE = path.join(WORKER_DIR, "worker.pid");
+export const WORKER_LOG_FILE = path.join(WORKER_DIR, "worker.log");
+function stateFile(dir) {
+    return path.join(dir, "state.json");
+}
+function pidFile(dir) {
+    return path.join(dir, "worker.pid");
+}
+/** Read the persisted worker state from disk. */
+export function readWorkerStatus(dir = WORKER_DIR) {
+    return readJsonWithRecovery(stateFile(dir));
+}
+/** Write worker state to disk atomically. */
+export function writeWorkerStatus(status, dir = WORKER_DIR) {
+    fs.mkdirSync(dir, { recursive: true });
+    writeFileAtomicSync(stateFile(dir), JSON.stringify(status, null, 2));
+}
+/** Check if the worker daemon is alive by reading its PID file. */
+export function getWorkerDaemonPid(dir = WORKER_DIR) {
+    try {
+        const pf = pidFile(dir);
+        if (!fs.existsSync(pf))
+            return null;
+        const pid = Number(fs.readFileSync(pf, "utf-8").trim());
+        if (isNaN(pid) || pid <= 0)
+            return null;
+        // Check if process is alive (signal 0 = test existence)
+        process.kill(pid, 0);
+        return pid;
+    }
+    catch {
+        return null;
+    }
+}
+/** Get a live status: reads persisted state + validates PID is alive. */
+export function getWorkerLiveStatus(dir = WORKER_DIR) {
+    const persisted = readWorkerStatus(dir);
+    const pid = getWorkerDaemonPid(dir);
+    if (!persisted) {
+        return {
+            pid: null,
+            running: false,
+            startedAt: null,
+            pollMs: 3000,
+            maxJobs: 0,
+            jobsProcessed: 0,
+            jobsDone: 0,
+            jobsFailed: 0,
+            jobsBlocked: 0,
+            lastJobId: null,
+            lastJobState: null,
+            uptimeMs: 0,
+            recentResults: [],
+        };
+    }
+    // If PID file says alive but process is dead, mark as not running
+    if (persisted.running && pid === null) {
+        return { ...persisted, running: false, pid: null };
+    }
+    // Update uptime from startedAt
+    if (persisted.running && persisted.startedAt) {
+        persisted.uptimeMs = Date.now() - new Date(persisted.startedAt).getTime();
+    }
+    return { ...persisted, pid };
+}

package/dist/src/learning/engine.js

@@ -0,0 +1,356 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import { writeFileAtomicSync } from "../util/atomic-write.js";
+import { LocatorPolicy } from "./locator-policy.js";
+import { RecoveryPolicy } from "./recovery-policy.js";
+import { TimingModel } from "./timing-model.js";
+import { SensorPolicy } from "./sensor-policy.js";
+import { PatternPolicy } from "./pattern-policy.js";
+import { TopologyPolicy } from "./topology-policy.js";
+import { DEFAULT_LEARNING_CONFIG } from "./types.js";
+/**
+ * Prune an array to `max` entries, keeping the most recent by date field.
+ */
+function pruneByDate(entries, max, getDate) {
+    return [...entries]
+        .sort((a, b) => getDate(b).localeCompare(getDate(a)))
+        .slice(0, max);
+}
+/**
+ * LearningEngine — the central coordinator for all learning policies.
+ *
+ * Observes outcomes from tool execution, recovery, and perception,
+ * updates the four sub-policies, and provides recommendations that
+ * make the system smarter over time.
+ *
+ * Persistence: each policy writes its own JSONL file in the data directory.
+ * Loading is eager (on init), saving is debounced.
+ */
+export class LearningEngine {
+    locators;
+    recovery;
+    timing;
+    sensors;
+    patterns;
+    topology;
+    config;
+    dirty = false;
+    saveTimer = null;
+    constructor(config) {
+        this.config = {
+            ...DEFAULT_LEARNING_CONFIG,
+            dataDir: config?.dataDir ??
+                path.join(os.homedir(), ".screenhand", "learning"),
+            ...config,
+        };
+        this.locators = new LocatorPolicy(this.config.priorStrength);
+        this.recovery = new RecoveryPolicy(this.config.priorStrength);
+        this.timing = new TimingModel(this.config.maxTimingSamples);
+        this.sensors = new SensorPolicy(this.config.priorStrength);
+        this.patterns = new PatternPolicy(this.config.priorStrength);
+        this.topology = new TopologyPolicy(this.config.priorStrength);
+    }
+    /**
+     * Initialize: create data directory and load persisted data.
+     */
+    init() {
+        fs.mkdirSync(this.config.dataDir, { recursive: true });
+        this.load();
+    }
+    // ── Record Outcomes ─────────────────────────────────────────────
+    recordLocatorOutcome(outcome) {
+        this.locators.record(outcome);
+        this.scheduleSave();
+    }
+    recordRecoveryOutcome(outcome) {
+        this.recovery.record(outcome);
+        this.scheduleSave();
+    }
+    recordToolTiming(event) {
+        this.timing.record(event);
+        this.scheduleSave();
+    }
+    recordSensorOutcome(outcome) {
+        this.sensors.record(outcome);
+        this.scheduleSave();
+    }
+    recordPattern(outcome) {
+        this.patterns.record(outcome);
+        this.scheduleSave();
+    }
+    recordTopologyOutcome(outcome) {
+        this.topology.record(outcome);
+        this.scheduleSave();
+    }
+    // ── Recommendations ─────────────────────────────────────────────
+    /**
+     * Get the best locator for a given app×action.
+     */
+    recommendLocator(bundleId, actionKey) {
+        return this.locators.recommend(bundleId, actionKey, this.config.minSamplesForConfidence);
+    }
+    /**
+     * Get ranked recovery strategies for a blocker×app pair.
+     */
+    rankRecoveryStrategies(blockerType, bundleId) {
+        return this.recovery.rank(blockerType, bundleId);
+    }
+    /**
+     * Get adaptive timeouts for a given app.
+     */
+    getAdaptiveBudget(bundleId) {
+        return this.timing.getAdaptiveBudget(bundleId, this.config.minSamplesForConfidence);
+    }
+    /**
+     * Get per-app source confidence using Bayesian posterior from observed accuracy.
+     * Falls back to hardcoded defaults if insufficient data.
+     */
+    getSourceConfidence(bundleId, source) {
+        const DEFAULTS = { ax: 0.9, cdp: 0.85, ocr: 0.7, vision: 0.6 };
+        const ranked = this.sensors.rank(bundleId);
+        const match = ranked.find((r) => r.sourceType === source);
+        if (match && match.score > 0) {
+            // Bayesian posterior from sensor policy is already computed
+            return match.score;
+        }
+        return DEFAULTS[source] ?? 0.5;
+    }
+    /**
+     * Get ranked perception sources for a given app.
+     */
+    rankSensors(bundleId) {
+        return this.sensors.rank(bundleId);
+    }
+    /**
+     * Query verified UI patterns for a given app, optionally filtered by tool.
+     */
+    queryPatterns(bundleId, tool) {
+        return this.patterns.query(bundleId, tool);
+    }
+    /**
+     * Get the best verified pattern for a given app×tool.
+     */
+    recommendPattern(bundleId, tool) {
+        return this.patterns.recommend(bundleId, tool, this.config.minSamplesForConfidence);
+    }
+    /**
+     * Query all topology entries (navigation edges) for a given app.
+     */
+    queryTopology(bundleId) {
+        return this.topology.query(bundleId);
+    }
+    /**
+     * Get the best navigation edge from a given node.
+     */
+    recommendNextNavigation(bundleId, fromNode) {
+        return this.topology.recommend(bundleId, fromNode, this.config.minSamplesForConfidence);
+    }
+    /**
+     * Get a summary of learning stats for a given app.
+     */
+    getAppSummary(bundleId) {
+        const locPrefix = `${bundleId.length}:${bundleId}\0`;
+        const locEntries = this.locators
+            .getAllEntries()
+            .filter((e) => e.key.startsWith(locPrefix));
+        const recEntries = this.recovery
+            .getAllEntries()
+            .filter((e) => {
+            const parts = e.key.split("::");
+            return parts[parts.length - 1] === bundleId;
+        });
+        const timSamples = this.timing
+            .getAllSamples()
+            .filter((s) => s.bundleId === bundleId);
+        const senEntries = this.sensors
+            .getAllEntries()
+            .filter((e) => e.bundleId === bundleId);
+        const patEntries = this.patterns.query(bundleId);
+        const topoEntries = this.topology.query(bundleId);
+        const topSensor = this.sensors.recommend(bundleId, 1);
+        const topLoc = locEntries.sort((a, b) => b.score - a.score)[0];
+        return {
+            locatorEntries: locEntries.length,
+            recoveryEntries: recEntries.length,
+            timingSamples: timSamples.length,
+            sensorEntries: senEntries.length,
+            patternEntries: patEntries.length,
+            topologyEntries: topoEntries.length,
+            topLocatorMethod: topLoc?.method ?? null,
+            topSensor,
+            adaptiveBudget: this.getAdaptiveBudget(bundleId),
+        };
+    }
+    // ── Persistence ─────────────────────────────────────────────────
+    /**
+     * Clear all learning data and flush empty state to disk.
+     */
+    reset() {
+        this.locators.clear();
+        this.recovery.clear();
+        this.timing.clear();
+        this.sensors.clear();
+        this.patterns.clear();
+        this.topology.clear();
+        this.flush();
+    }
+    /**
+     * Force save all policies to disk.
+     */
+    flush() {
+        if (this.saveTimer) {
+            clearTimeout(this.saveTimer);
+            this.saveTimer = null;
+        }
+        this.save();
+    }
+    scheduleSave() {
+        this.dirty = true;
+        if (this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            if (this.dirty) {
+                this.save();
+                this.dirty = false;
+            }
+        }, 500);
+    }
+    save() {
+        try {
+            const dir = this.config.dataDir;
+            const max = this.config.maxEntriesPerFile;
+            // Locator entries — prune by lastUsed
+            let locatorEntries = this.locators.getAllEntries();
+            if (locatorEntries.length > max) {
+                locatorEntries = pruneByDate(locatorEntries, max, (e) => e.lastUsed);
+                this.locators.loadEntries(locatorEntries);
+            }
+            const locatorData = locatorEntries.map((e) => JSON.stringify(e)).join("\n");
+            if (locatorData) {
+                writeFileAtomicSync(path.join(dir, "locators.jsonl"), locatorData + "\n");
+            }
+            // Recovery entries — prune by lastUsed
+            let recoveryEntries = this.recovery.getAllEntries();
+            if (recoveryEntries.length > max) {
+                recoveryEntries = pruneByDate(recoveryEntries, max, (e) => e.lastUsed);
+                this.recovery.loadEntries(recoveryEntries);
+            }
+            const recoveryData = recoveryEntries.map((e) => JSON.stringify(e)).join("\n");
+            if (recoveryData) {
+                writeFileAtomicSync(path.join(dir, "recoveries.jsonl"), recoveryData + "\n");
+            }
+            // Timing samples — prune by timestamp
+            let timingSamples = this.timing.getAllSamples();
+            if (timingSamples.length > max) {
+                timingSamples = pruneByDate(timingSamples, max, (s) => s.timestamp);
+                this.timing.loadSamples(timingSamples);
+            }
+            const timingData = timingSamples.map((s) => JSON.stringify(s)).join("\n");
+            if (timingData) {
+                writeFileAtomicSync(path.join(dir, "timings.jsonl"), timingData + "\n");
+            }
+            // Sensor entries — prune by lastUsed
+            let sensorEntries = this.sensors.getAllEntries();
+            if (sensorEntries.length > max) {
+                sensorEntries = pruneByDate(sensorEntries, max, (e) => e.lastUsed);
+                this.sensors.loadEntries(sensorEntries);
+            }
+            const sensorData = sensorEntries.map((e) => JSON.stringify(e)).join("\n");
+            if (sensorData) {
+                writeFileAtomicSync(path.join(dir, "sensors.jsonl"), sensorData + "\n");
+            }
+            // Pattern entries — prune by lastSeen
+            let patternEntries = this.patterns.getAllEntries();
+            if (patternEntries.length > max) {
+                patternEntries = pruneByDate(patternEntries, max, (e) => e.lastSeen);
+                this.patterns.loadEntries(patternEntries);
+            }
+            const patternData = patternEntries.map((e) => JSON.stringify(e)).join("\n");
+            if (patternData) {
+                writeFileAtomicSync(path.join(dir, "patterns.jsonl"), patternData + "\n");
+            }
+            // Topology entries — prune by lastUsed
+            let topologyEntries = this.topology.getAllEntries();
+            if (topologyEntries.length > max) {
+                topologyEntries = pruneByDate(topologyEntries, max, (e) => e.lastUsed);
+                this.topology.loadEntries(topologyEntries);
+            }
+            const topologyData = topologyEntries.map((e) => JSON.stringify(e)).join("\n");
+            if (topologyData) {
+                writeFileAtomicSync(path.join(dir, "topology.jsonl"), topologyData + "\n");
+            }
+        }
+        catch {
+            // Persistence failure is non-fatal — data stays in memory
+        }
+    }
+    load() {
+        const dir = this.config.dataDir;
+        // Load locators
+        const locatorEntries = this.readJsonl(path.join(dir, "locators.jsonl"));
+        if (locatorEntries.length > 0) {
+            this.locators.loadEntries(locatorEntries);
+        }
+        // Load recoveries
+        const recoveryEntries = this.readJsonl(path.join(dir, "recoveries.jsonl"));
+        if (recoveryEntries.length > 0) {
+            this.recovery.loadEntries(recoveryEntries);
+        }
+        // Load timings
+        const timingSamples = this.readJsonl(path.join(dir, "timings.jsonl"));
+        if (timingSamples.length > 0) {
+            this.timing.loadSamples(timingSamples);
+        }
+        // Load sensors
+        const sensorEntries = this.readJsonl(path.join(dir, "sensors.jsonl"));
+        if (sensorEntries.length > 0) {
+            this.sensors.loadEntries(sensorEntries);
+        }
+        // Load patterns
+        const patternEntries = this.readJsonl(path.join(dir, "patterns.jsonl"));
+        if (patternEntries.length > 0) {
+            this.patterns.loadEntries(patternEntries);
+        }
+        // Load topology
+        const topologyEntries = this.readJsonl(path.join(dir, "topology.jsonl"));
+        if (topologyEntries.length > 0) {
+            this.topology.loadEntries(topologyEntries);
+        }
+    }
+    readJsonl(filePath) {
+        try {
+            if (!fs.existsSync(filePath))
+                return [];
+            // Guard against oversized files: skip if larger than 10MB
+            const stat = fs.statSync(filePath);
+            if (stat.size > 10 * 1024 * 1024) {
+                console.error(`[Learning] Skipping oversized file: ${filePath} (${stat.size} bytes)`);
+                return [];
+            }
+            const content = fs.readFileSync(filePath, "utf-8");
+            const results = [];
+            const maxEntries = this.config.maxEntriesPerFile;
+            for (const line of content.split("\n")) {
+                if (results.length >= maxEntries)
+                    break;
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    results.push(JSON.parse(trimmed));
+                }
+                catch {
+                    // Skip corrupt lines
+                }
+            }
+            return results;
+        }
+        catch {
+            return [];
+        }
+    }
+}

package/dist/src/learning/index.js

@@ -0,0 +1,9 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+export { LearningEngine } from "./engine.js";
+export { LocatorPolicy } from "./locator-policy.js";
+export { RecoveryPolicy } from "./recovery-policy.js";
+export { TimingModel } from "./timing-model.js";
+export { SensorPolicy } from "./sensor-policy.js";
+export { TopologyPolicy } from "./topology-policy.js";
+export { DEFAULT_LEARNING_CONFIG } from "./types.js";