screenhand 0.1.1 → 0.3.0

package/dist/scripts/worker-daemon.js

@@ -0,0 +1,228 @@
+#!/usr/bin/env npx tsx
+/**
+ * Worker Daemon — runs as a standalone background process.
+ *
+ * Survives MCP/client restarts. Continuously processes the job queue
+ * via JobRunner with playbook engine support.
+ *
+ * Usage:
+ *   npx tsx scripts/worker-daemon.ts
+ *   npx tsx scripts/worker-daemon.ts --poll 3000 --max-jobs 0
+ *
+ * State files:
+ *   ~/.screenhand/worker/state.json   — worker status + recent results
+ *   ~/.screenhand/worker/worker.pid   — PID of this process
+ *   ~/.screenhand/worker/worker.log   — log output
+ *   ~/.screenhand/jobs/               — job persistence
+ *   ~/.screenhand/locks/              — session leases
+ */
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { BridgeClient } from "../src/native/bridge-client.js";
+import { SessionSupervisor, LeaseManager } from "../src/supervisor/supervisor.js";
+import { JobManager } from "../src/jobs/manager.js";
+import { JobRunner } from "../src/jobs/runner.js";
+import { PlaybookEngine } from "../src/playbook/engine.js";
+import { PlaybookStore } from "../src/playbook/store.js";
+import { AccessibilityAdapter } from "../src/runtime/accessibility-adapter.js";
+import { AutomationRuntimeService } from "../src/runtime/service.js";
+import { TimelineLogger } from "../src/logging/timeline-logger.js";
+import { MemoryService } from "../src/memory/service.js";
+import { WORKER_DIR, WORKER_PID_FILE, WORKER_LOG_FILE, getWorkerDaemonPid, writeWorkerStatus, } from "../src/jobs/worker.js";
+// ── Config from CLI args ──
+const args = process.argv.slice(2);
+function getArg(name, fallback) {
+    const idx = args.indexOf("--" + name);
+    if (idx === -1)
+        return fallback;
+    return args[idx + 1] ?? fallback;
+}
+const POLL_MS = Number(getArg("poll", "3000"));
+const MAX_JOBS = Number(getArg("max-jobs", "0")); // 0 = unlimited
+// ── Directories ──
+const JOB_DIR = path.join(os.homedir(), ".screenhand", "jobs");
+const LOCK_DIR = path.join(os.homedir(), ".screenhand", "locks");
+const PLAYBOOKS_DIR = path.join(os.homedir(), ".screenhand", "playbooks");
+const SUPERVISOR_STATE_DIR = path.join(os.homedir(), ".screenhand", "supervisor");
+fs.mkdirSync(WORKER_DIR, { recursive: true });
+fs.mkdirSync(JOB_DIR, { recursive: true });
+// ── Logging ──
+const logStream = fs.createWriteStream(WORKER_LOG_FILE, { flags: "a" });
+let daemonized = false;
+function log(msg) {
+    const line = `[${new Date().toISOString()}] ${msg}`;
+    logStream.write(line + "\n");
+    if (!daemonized)
+        process.stderr.write(line + "\n");
+}
+// ── Bridge setup ──
+const scriptDir = import.meta.dirname ?? path.dirname(new URL(import.meta.url).pathname);
+const projectRoot = scriptDir.includes("/dist/")
+    ? path.resolve(scriptDir, "../..")
+    : path.resolve(scriptDir, "..");
+const bridgePath = process.platform === "win32"
+    ? path.resolve(projectRoot, "native/windows-bridge/bin/Release/net8.0-windows/windows-bridge.exe")
+    : path.resolve(projectRoot, "native/macos-bridge/.build/release/macos-bridge");
+const bridge = new BridgeClient(bridgePath);
+let bridgeReady = false;
+async function ensureBridge() {
+    if (!bridgeReady) {
+        await bridge.start();
+        bridgeReady = true;
+    }
+}
+// ── Services ──
+const leaseManager = new LeaseManager(LOCK_DIR);
+const supervisor = new SessionSupervisor({
+    stateDir: SUPERVISOR_STATE_DIR,
+    lockDir: LOCK_DIR,
+});
+const memory = new MemoryService(os.homedir());
+const jobManager = new JobManager({ jobDir: JOB_DIR, memory, supervisor });
+jobManager.init();
+// ── State ──
+let stopped = false;
+let processing = false;
+const recentResults = [];
+const MAX_RECENT = 50;
+let jobsProcessed = 0;
+let jobsDone = 0;
+let jobsFailed = 0;
+let jobsBlocked = 0;
+let lastJobId = null;
+let lastJobState = null;
+let startedAt = null;
+function buildStatus() {
+    return {
+        pid: process.pid,
+        running: !stopped,
+        startedAt,
+        pollMs: POLL_MS,
+        maxJobs: MAX_JOBS,
+        jobsProcessed,
+        jobsDone,
+        jobsFailed,
+        jobsBlocked,
+        lastJobId,
+        lastJobState,
+        uptimeMs: startedAt ? Date.now() - new Date(startedAt).getTime() : 0,
+        recentResults: recentResults.slice(-MAX_RECENT),
+    };
+}
+function persistState() {
+    try {
+        writeWorkerStatus(buildStatus());
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function recordResult(result) {
+    jobsProcessed++;
+    lastJobId = result.jobId;
+    lastJobState = result.finalState;
+    switch (result.finalState) {
+        case "done":
+            jobsDone++;
+            break;
+        case "failed":
+            jobsFailed++;
+            break;
+        case "blocked":
+        case "waiting_human":
+            jobsBlocked++;
+            break;
+    }
+    recentResults.push(result);
+    if (recentResults.length > MAX_RECENT)
+        recentResults.shift();
+    log(`Completed: ${result.jobId} → ${result.finalState} (${result.stepsCompleted}/${result.totalSteps} steps, ${result.durationMs}ms)`);
+    persistState();
+}
+// ── Main loop ──
+async function main() {
+    // Enforce single daemon
+    const existingPid = getWorkerDaemonPid();
+    if (existingPid !== null && existingPid !== process.pid) {
+        const msg = `Another worker daemon is already running (pid=${existingPid}). Aborting.`;
+        log(msg);
+        process.stderr.write(msg + "\n");
+        process.exit(1);
+    }
+    fs.writeFileSync(WORKER_PID_FILE, String(process.pid));
+    daemonized = true;
+    startedAt = new Date().toISOString();
+    log(`Worker daemon started (pid=${process.pid})`);
+    log(`Config: poll=${POLL_MS}ms max-jobs=${MAX_JOBS || "unlimited"}`);
+    // Ensure bridge is ready
+    await ensureBridge();
+    // Build playbook engine stack
+    const adapter = new AccessibilityAdapter(bridge);
+    const logger = new TimelineLogger();
+    const runtimeService = new AutomationRuntimeService(adapter, logger);
+    const playbookEngine = new PlaybookEngine(runtimeService);
+    const playbookStore = new PlaybookStore(PLAYBOOKS_DIR);
+    playbookStore.load();
+    const runner = new JobRunner(bridge, jobManager, leaseManager, supervisor, {
+        playbookEngine,
+        playbookStore,
+        runtimeService,
+        onLog: log,
+    });
+    persistState();
+    // Poll loop
+    while (!stopped) {
+        if (!processing) {
+            processing = true;
+            try {
+                const result = await runner.run();
+                if (result) {
+                    recordResult(result);
+                    // Check maxJobs limit
+                    if (MAX_JOBS > 0 && jobsProcessed >= MAX_JOBS) {
+                        log(`Reached max-jobs limit (${MAX_JOBS})`);
+                        break;
+                    }
+                    // Job found — poll again immediately
+                    continue;
+                }
+            }
+            catch (err) {
+                log(`Poll error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                processing = false;
+            }
+        }
+        // Queue empty or error — wait before next poll
+        await sleep(POLL_MS);
+    }
+    log(`Worker daemon exiting (${jobsProcessed} jobs: ${jobsDone} done, ${jobsFailed} failed, ${jobsBlocked} blocked)`);
+    await shutdown();
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Graceful shutdown ──
+process.on("SIGINT", () => { stopped = true; });
+process.on("SIGTERM", () => { stopped = true; });
+async function shutdown() {
+    stopped = true;
+    persistState();
+    try {
+        fs.unlinkSync(WORKER_PID_FILE);
+    }
+    catch { /* ignore */ }
+    try {
+        await bridge.stop();
+    }
+    catch { /* ignore */ }
+    logStream.end();
+    process.exit(0);
+}
+main().catch((err) => {
+    log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+    persistState();
+    process.exit(1);
+});

package/dist/src/agent/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// 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 { TimelineLogger } from "../logging/timeline-logger.js";
+import { AutomationRuntimeService } from "../runtime/service.js";
+import { runAgentLoop } from "./loop.js";
+const task = process.argv.slice(2).join(" ");
+if (!task) {
+    console.error("Usage: screenhand-agent <task description>");
+    console.error("Example: screenhand-agent \"Open Safari and search for MCP protocol\"");
+    process.exit(1);
+}
+async function createAdapter() {
+    const adapterType = process.env.SCREENHAND_ADAPTER ?? "accessibility";
+    switch (adapterType) {
+        case "placeholder": {
+            const { PlaceholderAppAdapter } = await import("../runtime/app-adapter.js");
+            return new PlaceholderAppAdapter();
+        }
+        case "cdp": {
+            const { CdpChromeAdapter } = await import("../runtime/cdp-chrome-adapter.js");
+            return new CdpChromeAdapter({ headless: process.env.SCREENHAND_HEADLESS === "1" });
+        }
+        case "composite": {
+            const { BridgeClient } = await import("../native/bridge-client.js");
+            const { CompositeAdapter } = await import("../runtime/composite-adapter.js");
+            return new CompositeAdapter(new BridgeClient(), { headless: process.env.SCREENHAND_HEADLESS === "1" });
+        }
+        default: {
+            const { BridgeClient } = await import("../native/bridge-client.js");
+            const { AccessibilityAdapter } = await import("../runtime/accessibility-adapter.js");
+            return new AccessibilityAdapter(new BridgeClient());
+        }
+    }
+}
+try {
+    const adapter = await createAdapter();
+    const runtime = new AutomationRuntimeService(adapter, new TimelineLogger());
+    const session = await runtime.sessionStart();
+    console.log(`\n🔄 Task: ${task}`);
+    console.log(`   Session: ${session.sessionId}`);
+    console.log(`   Model: ${process.env.SCREENHAND_MODEL ?? "claude-sonnet-4-20250514"}\n`);
+    const cliModel = process.env.SCREENHAND_MODEL;
+    const result = await runAgentLoop(runtime, session.sessionId, task, {
+        maxSteps: parseInt(process.env.SCREENHAND_MAX_STEPS ?? "50", 10),
+        ...(cliModel ? { model: cliModel } : {}),
+        onStep: (step) => {
+            const icon = step.done ? "✅" : step.action ? "→" : "⚠️";
+            console.log(`  ${icon} [${step.index}] ${step.reasoning.slice(0, 100)}`);
+            if (step.action && step.action.tool !== "done") {
+                console.log(`     ${step.action.tool}: ${JSON.stringify(step.action).slice(0, 120)}`);
+            }
+            if (step.result) {
+                console.log(`     Result: ${step.result.slice(0, 100)}`);
+            }
+            console.log(`     (${step.durationMs}ms)\n`);
+        },
+    });
+    console.log(`\n${"=".repeat(60)}`);
+    console.log(`${result.success ? "✅ SUCCESS" : "❌ INCOMPLETE"}: ${result.summary}`);
+    console.log(`Steps: ${result.steps.length} | Total: ${result.totalMs}ms`);
+    console.log(`${"=".repeat(60)}\n`);
+    process.exit(result.success ? 0 : 1);
+}
+catch (e) {
+    console.error(`Fatal: ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+}

package/dist/src/agent/loop.js

@@ -0,0 +1,274 @@
+// 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/>.
+/**
+ * ScreenHand Agent Loop
+ *
+ * Continuous observe → decide → act loop powered by Claude.
+ * Uses element_tree (accessibility tree) as the primary observation — not screenshots.
+ * ~50ms per observe, ~50ms per action. Only the LLM call adds latency.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+/**
+ * Compact AX tree representation for LLM consumption.
+ * Converts the full AXNode tree into a concise text format:
+ *   [button] "Send" (350,200)
+ *   [textField] "Search" value="hello" (100,50)
+ */
+function compactTree(node, depth = 0, maxDepth = 5) {
+    if (depth > maxDepth)
+        return "";
+    const indent = "  ".repeat(depth);
+    const parts = [];
+    // Role
+    const role = node.role.replace("AX", "").toLowerCase();
+    // Label — prefer title, then description, then identifier
+    const label = node.title || node.description || node.identifier || "";
+    // Value
+    const val = node.value ? ` value="${node.value.slice(0, 50)}"` : "";
+    // Position
+    const pos = node.position ? ` (${Math.round(node.position.x)},${Math.round(node.position.y)})` : "";
+    // Focused/enabled markers
+    const markers = [];
+    if (node.focused)
+        markers.push("focused");
+    if (node.enabled === false)
+        markers.push("disabled");
+    const markerStr = markers.length ? ` [${markers.join(",")}]` : "";
+    // Skip noise nodes with no useful info
+    const isNoise = !label && !val && !node.focused && (role === "group" || role === "splitgroup" || role === "scrollarea");
+    if (!isNoise) {
+        parts.push(`${indent}[${role}] "${label}"${val}${pos}${markerStr}`);
+    }
+    if (node.children) {
+        for (const child of node.children) {
+            const childStr = compactTree(child, isNoise ? depth : depth + 1, maxDepth);
+            if (childStr)
+                parts.push(childStr);
+        }
+    }
+    return parts.join("\n");
+}
+const SYSTEM_PROMPT = `You are a desktop automation agent. You control a computer through ScreenHand tools.
+
+On each turn you receive the current UI state as an accessibility tree. You must decide the SINGLE next action to take.
+
+Respond in this exact JSON format (no markdown, no explanation outside the JSON):
+{
+  "reasoning": "Brief explanation of what you see and why you're taking this action",
+  "action": { "tool": "...", ... },
+  "done": false
+}
+
+When the task is fully complete, respond with:
+{
+  "reasoning": "Task is complete because ...",
+  "action": { "tool": "done", "summary": "What was accomplished" },
+  "done": true
+}
+
+Available actions:
+- {"tool": "press", "target": "Button text or element name"}
+- {"tool": "type_into", "target": "Field name", "text": "text to type"}
+- {"tool": "navigate", "url": "https://..."}
+- {"tool": "scroll", "direction": "up|down|left|right", "amount": 3}
+- {"tool": "key_combo", "keys": ["cmd", "c"]}
+- {"tool": "menu_click", "menuPath": ["File", "Save"]}
+- {"tool": "app_launch", "bundleId": "com.apple.Safari"}
+- {"tool": "app_focus", "bundleId": "com.apple.Safari"}
+- {"tool": "extract", "target": "element name", "format": "text"}
+- {"tool": "wait", "ms": 1000}
+- {"tool": "done", "summary": "what was accomplished"}
+
+Rules:
+- Take ONE action per turn. After each action you'll see the updated UI.
+- Use the accessibility tree to find elements — look for roles and labels.
+- Target elements by their visible text/label, not coordinates (unless no label exists).
+- If an action fails, try an alternative approach — don't repeat the same failed action.
+- If you're stuck after 3 attempts, explain what's blocking you and mark done.
+- Be efficient. Don't take unnecessary actions.`;
+export async function runAgentLoop(runtime, sessionId, task, options = {}) {
+    const { maxSteps = 50, model = "claude-sonnet-4-20250514", maxTokens = 1024, onStep, screenshotOnStart = false, } = options;
+    const client = new Anthropic();
+    const steps = [];
+    const messages = [];
+    const startTime = Date.now();
+    // Optional initial screenshot for context
+    if (screenshotOnStart) {
+        await runtime.screenshot({ sessionId });
+    }
+    for (let i = 0; i < maxSteps; i++) {
+        const stepStart = Date.now();
+        // 1. OBSERVE — get accessibility tree (~50ms)
+        const treeResult = await runtime.elementTree({ sessionId, maxDepth: 5 });
+        let observation;
+        if (treeResult.ok) {
+            observation = compactTree(treeResult.data);
+            // Truncate if too large to keep tokens manageable
+            if (observation.length > 8000) {
+                observation = observation.slice(0, 8000) + "\n... (truncated)";
+            }
+        }
+        else {
+            observation = `[Error getting UI tree: ${treeResult.error.message}]`;
+        }
+        // Also get app context
+        let contextLine = "";
+        try {
+            const apps = await runtime.appList(sessionId);
+            if (apps.ok) {
+                const active = apps.data.find(a => a.isActive);
+                if (active)
+                    contextLine = `Active app: ${active.name} (${active.bundleId})`;
+            }
+        }
+        catch { /* ignore */ }
+        // 2. BUILD prompt
+        const userMsg = i === 0
+            ? `Task: ${task}\n\nCurrent UI state:\n${contextLine}\n${observation}`
+            : `Action result: ${steps[i - 1].result}\n\nUpdated UI state:\n${contextLine}\n${observation}`;
+        messages.push({ role: "user", content: userMsg });
+        // 3. DECIDE — ask Claude what to do next
+        let reasoning = "";
+        let action = null;
+        let done = false;
+        try {
+            const resp = await client.messages.create({
+                model,
+                max_tokens: maxTokens,
+                system: SYSTEM_PROMPT,
+                messages,
+            });
+            const text = resp.content[0]?.type === "text" ? resp.content[0].text : "";
+            messages.push({ role: "assistant", content: text });
+            // Parse JSON response
+            const jsonMatch = text.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                const parsed = JSON.parse(jsonMatch[0]);
+                reasoning = parsed.reasoning ?? "";
+                action = parsed.action ?? null;
+                done = parsed.done === true;
+            }
+            else {
+                reasoning = text;
+            }
+        }
+        catch (e) {
+            reasoning = `LLM error: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        // 4. ACT — execute the action (~50ms)
+        let result = "";
+        if (action) {
+            try {
+                result = await executeAction(runtime, sessionId, action);
+            }
+            catch (e) {
+                result = `Error: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        else {
+            result = "No action taken";
+        }
+        // Record step
+        const step = {
+            index: i,
+            observation: observation.slice(0, 500),
+            reasoning,
+            action,
+            result,
+            done,
+            durationMs: Date.now() - stepStart,
+        };
+        steps.push(step);
+        if (onStep)
+            onStep(step);
+        if (done)
+            break;
+    }
+    const lastStep = steps[steps.length - 1];
+    const summary = lastStep?.action?.tool === "done"
+        ? lastStep.action.summary
+        : `Stopped after ${steps.length} steps`;
+    return {
+        success: lastStep?.done ?? false,
+        summary,
+        steps,
+        totalMs: Date.now() - startTime,
+    };
+}
+async function executeAction(runtime, sessionId, action) {
+    switch (action.tool) {
+        case "press": {
+            const r = await runtime.press({
+                sessionId,
+                target: { type: "text", value: action.target },
+            });
+            return r.ok ? `Pressed "${action.target}"` : `Failed: ${r.error.message}`;
+        }
+        case "type_into": {
+            const r = await runtime.typeInto({
+                sessionId,
+                target: { type: "text", value: action.target },
+                text: action.text,
+            });
+            return r.ok ? `Typed "${action.text}" into "${action.target}"` : `Failed: ${r.error.message}`;
+        }
+        case "navigate": {
+            const r = await runtime.navigate({ sessionId, url: action.url });
+            return r.ok ? `Navigated to ${action.url}` : `Failed: ${r.error.message}`;
+        }
+        case "scroll": {
+            const input = { sessionId, direction: action.direction };
+            if (typeof action.amount === "number")
+                input.amount = action.amount;
+            const r = await runtime.scroll(input);
+            return r.ok ? `Scrolled ${action.direction}` : `Failed: ${r.error.message}`;
+        }
+        case "key_combo": {
+            const r = await runtime.keyCombo({ sessionId, keys: action.keys });
+            return r.ok ? `Key combo: ${action.keys.join("+")}` : `Failed: ${r.error.message}`;
+        }
+        case "menu_click": {
+            const r = await runtime.menuClick({ sessionId, menuPath: action.menuPath });
+            return r.ok ? `Menu: ${action.menuPath.join(" → ")}` : `Failed: ${r.error.message}`;
+        }
+        case "app_launch": {
+            const r = await runtime.appLaunch({ sessionId, bundleId: action.bundleId });
+            return r.ok ? `Launched ${action.bundleId}` : `Failed: ${r.error.message}`;
+        }
+        case "app_focus": {
+            const r = await runtime.appFocus({ sessionId, bundleId: action.bundleId });
+            return r.ok ? `Focused ${action.bundleId}` : `Failed: ${r.error.message}`;
+        }
+        case "extract": {
+            const r = await runtime.extract({
+                sessionId,
+                target: { type: "text", value: action.target },
+                format: action.format,
+            });
+            return r.ok ? `Extracted: ${JSON.stringify(r.data).slice(0, 500)}` : `Failed: ${r.error.message}`;
+        }
+        case "wait": {
+            await new Promise(resolve => setTimeout(resolve, action.ms));
+            return `Waited ${action.ms}ms`;
+        }
+        case "done": {
+            return `Task complete: ${action.summary}`;
+        }
+        default:
+            return `Unknown action: ${action.tool}`;
+    }
+}

package/dist/src/community/fetcher.js

@@ -0,0 +1,109 @@
+// 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 { RemoteCommunityAPI } from "./remote-api.js";
+/**
+ * PlaybookFetcher — fetches community playbooks from local disk
+ * and optionally from a remote API (when SCREENHAND_COMMUNITY_URL is set).
+ *
+ * Local repo is always read. Remote results are merged and deduplicated.
+ */
+export class PlaybookFetcher {
+    repoDir;
+    cache = null;
+    remote;
+    constructor(repoDir, remote) {
+        this.repoDir = repoDir ?? path.join(os.homedir(), ".screenhand", "community");
+        this.remote = remote ?? RemoteCommunityAPI.fromEnv();
+    }
+    /**
+     * Fetch community playbooks matching the query.
+     * Reads from local disk; async variant also merges remote results.
+     */
+    fetch(query) {
+        return this.filterAndRank(this.loadAll(), query);
+    }
+    /**
+     * Fetch with remote API merge (when SCREENHAND_COMMUNITY_URL is set).
+     * Local results are always included; remote results are deduplicated and merged.
+     */
+    async fetchWithRemote(query) {
+        const local = this.loadAll();
+        if (!this.remote) {
+            return this.filterAndRank(local, query);
+        }
+        try {
+            const remote = await this.remote.fetch(query);
+            // Deduplicate: local wins on ID collision
+            const localIds = new Set(local.map((pb) => pb.id));
+            const merged = [...local, ...remote.filter((pb) => !localIds.has(pb.id))];
+            return this.filterAndRank(merged, query);
+        }
+        catch {
+            return this.filterAndRank(local, query);
+        }
+    }
+    filterAndRank(all, query) {
+        return all
+            .filter((pb) => {
+            if (query.platform && pb.platform !== query.platform)
+                return false;
+            if (query.bundleId && pb.bundleId !== query.bundleId)
+                return false;
+            if (query.workflow) {
+                const lower = query.workflow.toLowerCase();
+                if (!pb.name.toLowerCase().includes(lower) &&
+                    !pb.description.toLowerCase().includes(lower) &&
+                    !pb.metadata.tags.some((t) => t.toLowerCase().includes(lower))) {
+                    return false;
+                }
+            }
+            if (query.minScore !== undefined && pb.ratings.score < query.minScore)
+                return false;
+            return true;
+        })
+            .sort((a, b) => {
+            const scoreA = a.metadata.successRate * Math.max(a.ratings.score, 1);
+            const scoreB = b.metadata.successRate * Math.max(b.ratings.score, 1);
+            return scoreB - scoreA;
+        })
+            .slice(0, query.limit ?? 20);
+    }
+    /**
+     * Get a specific playbook by ID.
+     */
+    get(id) {
+        const all = this.loadAll();
+        return all.find((pb) => pb.id === id) ?? null;
+    }
+    /**
+     * Invalidate the cache (after a new playbook is published).
+     */
+    invalidateCache() {
+        this.cache = null;
+    }
+    loadAll() {
+        if (this.cache)
+            return this.cache;
+        const playbooks = [];
+        try {
+            if (!fs.existsSync(this.repoDir))
+                return playbooks;
+            const files = fs.readdirSync(this.repoDir);
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue;
+                try {
+                    const raw = fs.readFileSync(path.join(this.repoDir, file), "utf-8");
+                    playbooks.push(JSON.parse(raw));
+                }
+                catch { /* skip malformed */ }
+            }
+        }
+        catch { /* dir not found */ }
+        this.cache = playbooks;
+        return playbooks;
+    }
+}