screenhand 0.1.0 → 0.2.0

package/dist/src/supervisor/supervisor.js

@@ -0,0 +1,403 @@
+// 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/>.
+/**
+ * SessionSupervisor — generic, client-agnostic session supervisor.
+ *
+ * Manages session leases, detects stalls, and coordinates recovery actions
+ * via the filesystem. Does NOT perform OCR or interact with the native bridge
+ * directly — that responsibility belongs to the daemon layer.
+ *
+ * State directory: ~/.screenhand/supervisor/
+ * Files: state.json, recoveries.json, supervisor.pid, supervisor.log
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { writeFileAtomicSync, readJsonWithRecovery } from "../util/atomic-write.js";
+import { LeaseManager } from "./locks.js";
+import { DEFAULT_SUPERVISOR_CONFIG, } from "./types.js";
+/** Known blocker patterns for stall detection (matched against screen content) */
+const BLOCKER_PATTERNS = [
+    "captcha",
+    "2fa",
+    "two-factor",
+    "rate limit",
+    "timed out",
+    "login",
+    "permission",
+    "approve",
+    "blocked",
+];
+export class SessionSupervisor {
+    config;
+    stateDir;
+    lockDir;
+    leaseManager;
+    stateFile;
+    recoveriesFile;
+    pidFile;
+    logFile;
+    startedAt;
+    running = false;
+    pollTimer = null;
+    // Health counters
+    totalSessions = 0;
+    expiredLeases = 0;
+    stallsDetected = 0;
+    recoveriesAttempted = 0;
+    consecutiveErrors = 0;
+    // In-memory recovery list (also persisted)
+    recoveries = [];
+    // Last known screen content per session (set externally via stall detection)
+    screenContent = new Map();
+    logStream = null;
+    constructor(config) {
+        this.config = { ...DEFAULT_SUPERVISOR_CONFIG, ...config };
+        this.startedAt = new Date().toISOString();
+        this.stateDir = this.config.stateDir;
+        this.lockDir = this.config.lockDir;
+        this.stateFile = path.join(this.stateDir, "state.json");
+        this.recoveriesFile = path.join(this.stateDir, "recoveries.json");
+        this.pidFile = path.join(this.stateDir, "supervisor.pid");
+        this.logFile = path.join(this.stateDir, "supervisor.log");
+        this.leaseManager = new LeaseManager(this.lockDir, this.config.leaseTimeoutMs);
+        // Ensure directories exist
+        fs.mkdirSync(this.stateDir, { recursive: true });
+        fs.mkdirSync(this.lockDir, { recursive: true });
+        // Load persisted recoveries if any
+        this.loadRecoveries();
+    }
+    /**
+     * Start the supervisor poll loop (meant to be called when running as daemon).
+     */
+    /**
+     * Check if another supervisor daemon is already running via PID file.
+     * Returns the existing PID if alive, null otherwise.
+     */
+    getExistingDaemonPid() {
+        try {
+            if (!fs.existsSync(this.pidFile))
+                return null;
+            const pid = Number(fs.readFileSync(this.pidFile, "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;
+        }
+    }
+    async start() {
+        if (this.running)
+            return;
+        // Enforce single daemon: refuse to start if another is alive
+        const existingPid = this.getExistingDaemonPid();
+        if (existingPid !== null && existingPid !== process.pid) {
+            throw new Error(`Another supervisor daemon is already running (pid=${existingPid}). Stop it first or remove ${this.pidFile}.`);
+        }
+        this.running = true;
+        this.startedAt = new Date().toISOString();
+        this.logStream = fs.createWriteStream(this.logFile, { flags: "a" });
+        // Write PID file (atomic-ish — we checked above)
+        fs.writeFileSync(this.pidFile, String(process.pid));
+        this.log(`Supervisor started (pid=${process.pid})`);
+        this.writeState();
+        // Start poll loop
+        this.pollTimer = setInterval(() => {
+            this.pollCycle();
+        }, this.config.pollMs);
+    }
+    /**
+     * Stop the supervisor.
+     */
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.log("Supervisor stopped");
+        this.writeState();
+        // Clean up PID file
+        try {
+            fs.unlinkSync(this.pidFile);
+        }
+        catch {
+            // Ignore
+        }
+        if (this.logStream) {
+            this.logStream.end();
+            this.logStream = null;
+        }
+    }
+    /**
+     * Get current supervisor state.
+     */
+    getState() {
+        const activeSessions = this.leaseManager.getActive();
+        return {
+            pid: process.pid,
+            startedAt: this.startedAt,
+            running: this.running,
+            sessions: activeSessions,
+            health: this.getHealth(activeSessions),
+            config: { ...this.config },
+        };
+    }
+    /**
+     * Register a session for monitoring.
+     * Claims a window lease for the given client.
+     */
+    registerSession(client, app, windowId) {
+        const lease = this.leaseManager.claim(client, app, windowId);
+        if (lease) {
+            this.totalSessions++;
+            this.log(`Session registered: ${lease.sessionId} (client=${client.id}, type=${client.type}, app=${app}, window=${windowId})`);
+            this.writeState();
+        }
+        return lease;
+    }
+    /**
+     * Heartbeat from a client.
+     */
+    heartbeat(sessionId) {
+        return this.leaseManager.heartbeat(sessionId);
+    }
+    /**
+     * Release a session lease.
+     */
+    releaseSession(sessionId) {
+        const released = this.leaseManager.release(sessionId);
+        if (released) {
+            this.screenContent.delete(sessionId);
+            this.log(`Session released: ${sessionId}`);
+            this.writeState();
+        }
+        return released;
+    }
+    /**
+     * Add a recovery action for a session.
+     */
+    addRecovery(sessionId, type, instruction) {
+        const action = {
+            id: "recv_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 8),
+            sessionId,
+            type,
+            instruction,
+            status: "pending",
+            createdAt: new Date().toISOString(),
+            attemptedAt: null,
+            result: null,
+        };
+        this.recoveries.push(action);
+        this.saveRecoveries();
+        this.log(`Recovery added: ${action.id} (session=${sessionId}, type=${type})`);
+        return action;
+    }
+    /**
+     * List recovery actions, optionally filtered by status.
+     */
+    getRecoveries(status) {
+        if (status) {
+            return this.recoveries.filter((r) => r.status === status);
+        }
+        return [...this.recoveries];
+    }
+    /**
+     * Update a recovery's status and result, then persist to disk.
+     */
+    updateRecovery(id, status, result) {
+        const recovery = this.recoveries.find((r) => r.id === id);
+        if (recovery) {
+            recovery.status = status;
+            if (result !== undefined)
+                recovery.result = result;
+            this.saveRecoveries();
+        }
+    }
+    /**
+     * Detect stalls across all active sessions.
+     * A session is stalled if its lastHeartbeat is older than stallThresholdMs.
+     */
+    detectStalls() {
+        const now = Date.now();
+        const active = this.leaseManager.getActive();
+        const stalls = [];
+        for (const lease of active) {
+            const lastHb = new Date(lease.lastHeartbeat).getTime();
+            const elapsed = now - lastHb;
+            if (elapsed >= this.config.stallThresholdMs) {
+                const content = this.screenContent.get(lease.sessionId) ?? null;
+                const matchedBlockers = content
+                    ? BLOCKER_PATTERNS.filter((p) => content.toLowerCase().includes(p))
+                    : [];
+                stalls.push({
+                    sessionId: lease.sessionId,
+                    stalledSince: lease.lastHeartbeat,
+                    durationMs: elapsed,
+                    lastScreenContent: content,
+                    matchedBlockers,
+                });
+            }
+        }
+        return stalls;
+    }
+    /**
+     * Set screen content for a session (used by external daemons for blocker matching).
+     */
+    setScreenContent(sessionId, content) {
+        this.screenContent.set(sessionId, content);
+    }
+    // ── Private methods ──
+    pollCycle() {
+        try {
+            // 1. Expire stale leases
+            const expired = this.leaseManager.expireStale();
+            if (expired > 0) {
+                this.expiredLeases += expired;
+                this.log(`Expired ${expired} stale lease(s)`);
+            }
+            // 2. Detect stalls
+            const stalls = this.detectStalls();
+            if (stalls.length > 0) {
+                this.stallsDetected += stalls.length;
+                for (const stall of stalls) {
+                    this.log(`Stall detected: session=${stall.sessionId}, duration=${stall.durationMs}ms, blockers=[${stall.matchedBlockers.join(", ")}]`);
+                }
+            }
+            // 3. Auto-recover if enabled
+            if (this.config.autoRecover) {
+                this.attemptAutoRecovery(stalls);
+            }
+            // 4. Process pending recovery actions
+            this.processPendingRecoveries();
+            // 5. Write state
+            this.writeState();
+            this.consecutiveErrors = 0;
+        }
+        catch (err) {
+            this.consecutiveErrors++;
+            this.log(`Poll error (${this.consecutiveErrors}/${this.config.maxConsecutiveErrors}): ${err instanceof Error ? err.message : String(err)}`);
+            if (this.consecutiveErrors >= this.config.maxConsecutiveErrors) {
+                this.log("Max consecutive errors reached — stopping supervisor");
+                this.stop().catch(() => { });
+            }
+        }
+    }
+    attemptAutoRecovery(stalls) {
+        for (const stall of stalls) {
+            // Skip if there is already a pending/in-flight recovery, or a recent one (cooldown = stall threshold)
+            const cooldownMs = this.config.stallThresholdMs;
+            const hasActiveOrRecent = this.recoveries.some((r) => {
+                if (r.sessionId !== stall.sessionId)
+                    return false;
+                if (r.status === "pending" || r.status === "attempted")
+                    return true;
+                // Skip if a recovery completed recently (cooldown)
+                if (r.attemptedAt) {
+                    const age = Date.now() - new Date(r.attemptedAt).getTime();
+                    if (age < cooldownMs)
+                        return true;
+                }
+                return false;
+            });
+            if (hasActiveOrRecent)
+                continue;
+            // Determine recovery type based on blockers
+            let type = "nudge";
+            let instruction = "Session appears stalled — send a heartbeat or check status.";
+            if (stall.matchedBlockers.length > 0) {
+                type = "escalate";
+                instruction = `Session blocked by: ${stall.matchedBlockers.join(", ")}. Requires human intervention.`;
+            }
+            else if (stall.durationMs > this.config.stallThresholdMs * 2) {
+                type = "restart";
+                instruction = "Session stalled for extended period — consider restarting.";
+            }
+            this.addRecovery(stall.sessionId, type, instruction);
+        }
+    }
+    processPendingRecoveries() {
+        // Re-read from disk to pick up recoveries added by MCP tools
+        this.loadRecoveries();
+        for (const recovery of this.recoveries) {
+            if (recovery.status !== "pending")
+                continue;
+            // Mark as attempted (actual execution is the daemon's responsibility)
+            recovery.status = "attempted";
+            recovery.attemptedAt = new Date().toISOString();
+            this.recoveriesAttempted++;
+            this.log(`Recovery attempted: ${recovery.id} (type=${recovery.type})`);
+        }
+        this.saveRecoveries();
+    }
+    getHealth(activeSessions) {
+        const uptimeMs = this.running
+            ? Date.now() - new Date(this.startedAt).getTime()
+            : 0;
+        // Derive counters from filesystem state so they survive across MCP/daemon restarts
+        // and reflect activity from both MCP tools and the daemon
+        const recoveries = this.recoveries;
+        const recoveriesAttempted = recoveries.filter((r) => r.status === "attempted" || r.status === "succeeded" || r.status === "failed").length;
+        // totalSessions = active + unique sessions that have completed recoveries (proxy for historical)
+        const historicalSessionIds = new Set(recoveries.map((r) => r.sessionId));
+        const activeSessionIds = new Set(activeSessions.map((s) => s.sessionId));
+        // Merge: active sessions + sessions only known from recovery history
+        const allKnownSessions = new Set([...historicalSessionIds, ...activeSessionIds]);
+        const totalSessions = Math.max(allKnownSessions.size, this.totalSessions);
+        return {
+            uptimeMs,
+            totalSessions,
+            activeSessions: activeSessions.length,
+            expiredLeases: this.expiredLeases,
+            stallsDetected: this.stallsDetected,
+            recoveriesAttempted,
+        };
+    }
+    writeState() {
+        const state = this.getState();
+        try {
+            writeFileAtomicSync(this.stateFile, JSON.stringify(state, null, 2));
+        }
+        catch {
+            // Ignore write errors
+        }
+    }
+    loadRecoveries() {
+        const loaded = readJsonWithRecovery(this.recoveriesFile);
+        this.recoveries = loaded ?? [];
+    }
+    saveRecoveries() {
+        try {
+            writeFileAtomicSync(this.recoveriesFile, JSON.stringify(this.recoveries, null, 2));
+        }
+        catch {
+            // Ignore write errors
+        }
+    }
+    log(msg) {
+        const line = `[${new Date().toISOString()}] ${msg}`;
+        if (this.logStream) {
+            this.logStream.write(line + "\n");
+        }
+    }
+}
+export { DEFAULT_SUPERVISOR_CONFIG } from "./types.js";
+export { LeaseManager } from "./locks.js";

package/dist/src/supervisor/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/>.
+/**
+ * Session Supervisor types — generic, client-agnostic session management
+ */
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_SUPERVISOR_CONFIG = {
+    pollMs: 5000,
+    leaseTimeoutMs: 300000,
+    stallThresholdMs: 300000,
+    maxConsecutiveErrors: 5,
+    autoRecover: true,
+    stateDir: path.join(os.homedir(), ".screenhand", "supervisor"),
+    lockDir: path.join(os.homedir(), ".screenhand", "locks"),
+};

package/dist/src/test-mcp-protocol.js

@@ -0,0 +1,154 @@
+// 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 { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, "..");
+const tsxBin = path.join(projectRoot, "node_modules", ".bin", "tsx");
+const TIMEOUT_MS = 10_000;
+const proc = spawn(tsxBin, [path.join(projectRoot, "src/mcp-entry.ts")], {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, SCREENHAND_ADAPTER: "placeholder" },
+    cwd: projectRoot,
+});
+let stderrBuf = "";
+proc.stderr.on("data", (d) => { stderrBuf += d.toString(); });
+// MCP SDK v1.27 uses newline-delimited JSON (NDJSON), not Content-Length framing
+function send(msg) {
+    proc.stdin.write(JSON.stringify(msg) + "\n");
+}
+const rl = createInterface({ input: proc.stdout });
+const lineQueue = [];
+let lineWaiter = null;
+rl.on("line", (line) => {
+    if (lineWaiter) {
+        const w = lineWaiter;
+        lineWaiter = null;
+        w(line);
+    }
+    else {
+        lineQueue.push(line);
+    }
+});
+function readResponse() {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            lineWaiter = null;
+            reject(new Error(`Timeout. stderr: ${stderrBuf.slice(-300)}`));
+        }, TIMEOUT_MS);
+        const handle = (line) => {
+            clearTimeout(timer);
+            resolve(JSON.parse(line));
+        };
+        const queued = lineQueue.shift();
+        if (queued) {
+            clearTimeout(timer);
+            resolve(JSON.parse(queued));
+        }
+        else {
+            lineWaiter = handle;
+        }
+    });
+}
+function fail(msg) {
+    console.error("FAIL:", msg);
+    proc.kill();
+    process.exit(1);
+}
+try {
+    // Wait for server to start
+    await new Promise((r) => setTimeout(r, 2000));
+    // 1. Initialize
+    console.log("Sending initialize...");
+    send({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "test-client", version: "1.0" },
+        },
+    });
+    const initResp = await readResponse();
+    const initResult = initResp.result;
+    if (!initResult)
+        fail(`No init result: ${JSON.stringify(initResp)}`);
+    console.log("=== Initialize ===");
+    console.log(`  Protocol: ${initResult.protocolVersion}`);
+    console.log(`  Server: ${JSON.stringify(initResult.serverInfo)}`);
+    // 2. Send initialized notification
+    send({ jsonrpc: "2.0", method: "notifications/initialized" });
+    await new Promise((r) => setTimeout(r, 300));
+    // 3. List tools
+    console.log("\nListing tools...");
+    send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+    const toolsResp = await readResponse();
+    const toolsResult = toolsResp.result;
+    if (!toolsResult)
+        fail(`No tools result: ${JSON.stringify(toolsResp)}`);
+    const tools = toolsResult.tools ?? [];
+    console.log("=== Tools ===");
+    for (const tool of tools) {
+        console.log(`  ${tool.name}: ${(tool.description ?? "").slice(0, 70)}`);
+    }
+    console.log(`\n  Total: ${tools.length} tools`);
+    if (tools.length < 10)
+        fail(`Expected 16 tools, got ${tools.length}`);
+    // 4. Test session_start
+    console.log("\nCalling session_start...");
+    send({
+        jsonrpc: "2.0",
+        id: 3,
+        method: "tools/call",
+        params: { name: "session_start", arguments: {} },
+    });
+    const sessionResp = await readResponse();
+    const sessionResult = sessionResp.result;
+    if (!sessionResult)
+        fail(`No session result: ${JSON.stringify(sessionResp)}`);
+    const sessionContent = sessionResult.content;
+    const sessionData = JSON.parse(sessionContent?.[0]?.text ?? "{}");
+    console.log("=== session_start ===");
+    console.log(`  Session ID: ${sessionData.sessionId}`);
+    console.log(`  Profile: ${sessionData.profile}`);
+    if (!sessionData.sessionId)
+        fail("No sessionId returned");
+    // 5. Test app_list (should work with placeholder)
+    console.log("\nCalling app_list...");
+    send({
+        jsonrpc: "2.0",
+        id: 4,
+        method: "tools/call",
+        params: { name: "app_list", arguments: { sessionId: sessionData.sessionId } },
+    });
+    const appResp = await readResponse();
+    const appResult = appResp.result;
+    console.log("=== app_list ===");
+    const appContent = appResult?.content;
+    const isError = appResult?.isError;
+    console.log(`  isError: ${isError ?? false}`);
+    console.log(`  Response: ${(appContent?.[0]?.text ?? "").slice(0, 100)}`);
+    proc.kill();
+    console.log("\nAll tests passed!");
+    process.exit(0);
+}
+catch (e) {
+    fail(e instanceof Error ? e.message : String(e));
+}

package/dist/src/types.js

@@ -0,0 +1,17 @@
+// 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 {};