screenhand 0.1.1 → 0.2.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/logging/timeline-logger.js

@@ -0,0 +1,45 @@
+// 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/>.
+export class TimelineLogger {
+    timeline = [];
+    start(action, sessionId) {
+        return {
+            action,
+            sessionId,
+            startedAt: new Date().toISOString(),
+            locateMs: 0,
+            actMs: 0,
+            verifyMs: 0,
+            retries: 0,
+        };
+    }
+    finish(telemetry, status) {
+        const finishedAt = new Date().toISOString();
+        const totalMs = new Date(finishedAt).getTime() - new Date(telemetry.startedAt).getTime();
+        const finalized = {
+            ...telemetry,
+            finishedAt,
+            totalMs,
+            status,
+        };
+        this.timeline.push(finalized);
+        return finalized;
+    }
+    getRecent(limit = 50) {
+        return this.timeline.slice(-limit);
+    }
+}