screenhand 0.2.0 → 0.3.1

package/dist/src/jobs/runner.js

@@ -45,6 +45,8 @@ export class JobRunner {
     config;
     heartbeatTimer = null;
     stopped = false;
+    /** PID of the currently focused target app, resolved during focusTargetApp */
+    activePid = 0;
     constructor(bridge, jobs, leaseManager, supervisor, config) {
         this.bridge = bridge;
         this.jobs = jobs;
@@ -154,11 +156,12 @@ export class JobRunner {
         const engineSessionId = runtimeSessionId ?? sessionId;
         let stepsCompleted = 0;
         const result = await engine.run(engineSessionId, remainingPlaybook, {
+            ...(job.vars ? { vars: job.vars } : {}),
             onStep: (i, step, res) => {
                 const globalIdx = resumeIdx + i;
-                this.jobs.completeStep(job.id, globalIdx, { durationMs: 0 });
+                this.jobs.completeStep(job.id, globalIdx, { durationMs: 0, output: res });
                 stepsCompleted++;
-                this.log(`  Step ${globalIdx}/${playbook.steps.length - 1}: ${step.description ?? step.action} → ${res}`);
+                this.log(`  Step ${globalIdx}/${playbook.steps.length - 1}: ${step.description ?? step.action} → ${res.substring(0, 200)}`);
             },
         });
         if (result.success) {
@@ -211,7 +214,10 @@ export class JobRunner {
             const stepStart = Date.now();
             const result = await this.executeStep(step);
             if (result.ok) {
-                this.jobs.completeStep(job.id, i, { durationMs: Date.now() - stepStart });
+                const stepOpts = { durationMs: Date.now() - stepStart };
+                if (result.target)
+                    stepOpts.output = result.target;
+                this.jobs.completeStep(job.id, i, stepOpts);
                 stepsCompleted++;
                 consecutiveFailures = 0;
                 this.log(`    ✓ ${result.method} in ${result.durationMs}ms${result.fallbackFrom ? ` (fallback from ${result.fallbackFrom})` : ""}`);
@@ -235,11 +241,17 @@ export class JobRunner {
                     this.log(`  → blocked (transient): ${reason}`);
                     return this.finalize(job, start, stepsCompleted, reason);
                 }
-                if (consecutiveFailures >= this.config.maxConsecutiveFailures) {
+                // L2-72 fix: Use job's maxRetries if set, otherwise use runner's maxConsecutiveFailures
+                const maxFails = job.maxRetries ?? this.config.maxConsecutiveFailures;
+                if (consecutiveFailures >= maxFails) {
                     this.jobs.transition(job.id, "failed", { error: `${consecutiveFailures} consecutive step failures. Last: ${lastError}` });
                     this.log(`  → failed: ${consecutiveFailures} consecutive failures`);
                     return this.finalize(job, start, stepsCompleted, lastError);
                 }
+                // L2-72 fix: A failed step blocks subsequent steps — break out of the loop
+                // (the job will be marked as failed in the allAttempted check below)
+                this.log(`  Step failed — stopping execution (${consecutiveFailures}/${maxFails} consecutive failures)`);
+                break;
             }
             // Delay between steps
             if (i < job.steps.length - 1) {
@@ -252,10 +264,23 @@ export class JobRunner {
             return this.finalize(job, start, stepsCompleted, "Job disappeared");
         }
         const allDone = updated.steps.every((s) => s.status === "done" || s.status === "skipped");
+        const allAttempted = updated.steps.every((s) => s.status === "done" || s.status === "skipped" || s.status === "failed");
         if (allDone && !this.stopped) {
             this.jobs.transition(job.id, "done");
             this.log(`Job ${job.id} → done (${stepsCompleted} steps in ${Date.now() - start}ms)`);
         }
+        else if (allAttempted && !this.stopped) {
+            // L2-72 fix: All steps attempted but some failed → mark as failed, not done
+            const failedCount = updated.steps.filter((s) => s.status === "failed").length;
+            this.jobs.transition(job.id, "failed", { error: `${failedCount} step(s) failed` });
+            this.log(`Job ${job.id} → failed with ${failedCount} failed step(s) (${stepsCompleted}/${updated.steps.length} in ${Date.now() - start}ms)`);
+        }
+        else if (!this.stopped && lastError) {
+            // L2-72 fix: Broke out of loop due to a failed step with pending steps remaining
+            const failedCount = updated.steps.filter((s) => s.status === "failed").length;
+            this.jobs.transition(job.id, "failed", { error: `Step failed, ${updated.steps.length - stepsCompleted - failedCount} step(s) skipped. Last: ${lastError}` });
+            this.log(`Job ${job.id} → failed at step (${stepsCompleted}/${updated.steps.length}, ${failedCount} failed)`);
+        }
         else if (this.stopped) {
             this.log(`Job ${job.id} paused at step ${updated.lastStep + 1}`);
         }
@@ -276,6 +301,8 @@ export class JobRunner {
             if (!target) {
                 throw new Error(`Target app ${job.bundleId} is not running`);
             }
+            // Store resolved PID for use in execClick/execType AX calls
+            this.activePid = target.pid;
             // Focus the app
             await this.bridge.call("app.focus", { bundleId: job.bundleId });
             // If windowId specified, validate it exists
@@ -288,8 +315,14 @@ export class JobRunner {
             }
         }
         catch (err) {
-            // Log but don't fail — the step itself will fail if the target isn't right
-            this.log(`  Warning: focus target app failed: ${err instanceof Error ? err.message : String(err)}`);
+            const msg = err instanceof Error ? err.message : String(err);
+            // If the target app is dead, this is fatal — don't silently continue
+            // sending keystrokes to the wrong app
+            if (msg.includes("is not running")) {
+                throw new Error(`Target app killed: ${msg}`);
+            }
+            // Other focus errors (e.g. window not found) are non-fatal
+            this.log(`  Warning: focus target app failed: ${msg}`);
         }
     }
     /**
@@ -422,6 +455,13 @@ export class JobRunner {
                 case "read":
                 case "extract":
                     return await this.execRead(method, target, start, attempt);
+                case "focus":
+                case "launch":
+                    return await this.execFocus(target, start, attempt);
+                case "browser_js":
+                    return await this.execBrowserJs(step.description ?? "", start, attempt);
+                case "cdp_key_event":
+                    return await this.execCdpKeyEvent(step.keys ?? "", start, attempt);
                 default:
                     // Try as a generic click on the target text
                     if (target)
@@ -439,8 +479,8 @@ export class JobRunner {
             return { ok: false, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: "Click requires a target", target };
         switch (method) {
             case "ax": {
-                const found = await this.bridge.call("ax.findElement", { pid: 0, title: target, exact: false });
-                await this.bridge.call("ax.performAction", { pid: 0, elementPath: found.elementPath, action: "AXPress" });
+                const found = await this.bridge.call("ax.findElement", { pid: this.activePid, title: target, exact: false });
+                await this.bridge.call("ax.performAction", { pid: this.activePid, elementPath: found.elementPath, action: "AXPress" });
                 return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target };
             }
             case "cdp": {
@@ -482,12 +522,12 @@ export class JobRunner {
         switch (method) {
             case "ax": {
                 if (target) {
-                    const found = await this.bridge.call("ax.findElement", { pid: 0, title: target, exact: false });
-                    await this.bridge.call("ax.setElementValue", { pid: 0, elementPath: found.elementPath, value: text });
+                    const found = await this.bridge.call("ax.findElement", { pid: this.activePid, title: target, exact: false });
+                    await this.bridge.call("ax.setElementValue", { pid: this.activePid, elementPath: found.elementPath, value: text });
                 }
                 else {
-                    // Type into focused element via key events
-                    await this.bridge.call("cg.typeText", { text });
+                    // Type into focused element via key events — use pid for targeting
+                    await this.bridge.call("cg.typeText", { text, pid: this.activePid });
                 }
                 return { ok: true, method, durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target };
             }
@@ -520,6 +560,14 @@ export class JobRunner {
     async execNavigate(url, start, attempt) {
         if (!url)
             return { ok: false, method: "ax", durationMs: 0, fallbackFrom: null, retries: attempt, error: "Navigate requires a URL target", target: null };
+        // L2-74 fix: Block dangerous URL protocols (mirrors L2-71 fix in mcp-desktop.ts)
+        const BLOCKED_PROTOCOLS = ["javascript:", "data:", "blob:", "vbscript:"];
+        const urlLower = url.trim().toLowerCase();
+        for (const proto of BLOCKED_PROTOCOLS) {
+            if (urlLower.startsWith(proto)) {
+                return { ok: false, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: `Blocked: "${proto}" URLs are not allowed for security reasons`, target: url };
+            }
+        }
         if (this.config.cdpConnect) {
             const client = await this.config.cdpConnect();
             try {
@@ -530,9 +578,16 @@ export class JobRunner {
                 await client.close();
             }
         }
-        // Fallback: use AppleScript / open command
-        await this.bridge.call("app.openURL", { url });
-        return { ok: true, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: url };
+        // Fallback: try bridge openURL, then macOS `open` command
+        try {
+            await this.bridge.call("app.openURL", { url });
+            return { ok: true, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: url };
+        }
+        catch {
+            const { execSync } = await import("node:child_process");
+            execSync(`open ${JSON.stringify(url)}`, { timeout: 10_000 });
+            return { ok: true, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: url };
+        }
     }
     async execScreenshot(start, attempt) {
         const shot = await this.bridge.call("cg.captureScreen", {});
@@ -562,6 +617,24 @@ export class JobRunner {
         }
         throw new Error(`Method ${method} does not support scroll`);
     }
+    async execFocus(bundleId, start, attempt) {
+        if (!bundleId)
+            return { ok: false, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: "Focus/launch requires a bundleId target", target: null };
+        try {
+            await this.bridge.call("app.focus", { bundleId });
+            return { ok: true, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: bundleId };
+        }
+        catch {
+            // Fallback: try launch (app might not be running)
+            try {
+                await this.bridge.call("app.launch", { bundleId });
+                return { ok: true, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: bundleId };
+            }
+            catch (err) {
+                return { ok: false, method: "ax", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: err instanceof Error ? err.message : String(err), target: bundleId };
+            }
+        }
+    }
     async execKey(keys, start, attempt) {
         // keys is a "+" separated combo like "cmd+a"
         const parts = keys.split("+").map((k) => k.trim());
@@ -618,6 +691,56 @@ export class JobRunner {
         }
         throw new Error(`Method ${method} does not support read`);
     }
+    async execBrowserJs(code, start, attempt) {
+        if (!this.config.cdpConnect)
+            throw new Error("browser_js requires CDP");
+        const client = await this.config.cdpConnect();
+        try {
+            const result = await client.Runtime.evaluate({
+                expression: code,
+                awaitPromise: true,
+                returnByValue: true,
+            });
+            if (result.exceptionDetails) {
+                throw new Error(`JS Error: ${result.exceptionDetails.text ?? result.exceptionDetails.exception?.description ?? "unknown"}`);
+            }
+            return { ok: true, method: "cdp", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: String(result.result?.value ?? "") };
+        }
+        finally {
+            await client.close();
+        }
+    }
+    async execCdpKeyEvent(keys, start, attempt) {
+        if (!this.config.cdpConnect)
+            throw new Error("cdp_key_event requires CDP");
+        const client = await this.config.cdpConnect();
+        try {
+            // Parse "mod4+Enter" format or raw key
+            const parts = keys.split("+").map(k => k.trim());
+            let modifiers = 0;
+            let key = parts[parts.length - 1] ?? "";
+            for (const p of parts.slice(0, -1)) {
+                if (p.startsWith("mod"))
+                    modifiers = parseInt(p.replace("mod", ""), 10) || 0;
+                if (p === "Meta" || p === "Cmd")
+                    modifiers = 4;
+                if (p === "Shift")
+                    modifiers |= 8;
+                if (p === "Ctrl")
+                    modifiers |= 2;
+                if (p === "Alt")
+                    modifiers |= 1;
+            }
+            const keyCode = key === "Enter" ? 13 : key === "Tab" ? 9 : key === "Escape" ? 27 : 0;
+            const baseParams = { key, code: key, modifiers, windowsVirtualKeyCode: keyCode, nativeVirtualKeyCode: keyCode };
+            await client.Input.dispatchKeyEvent({ type: "keyDown", ...baseParams });
+            await client.Input.dispatchKeyEvent({ type: "keyUp", ...baseParams });
+            return { ok: true, method: "cdp", durationMs: Date.now() - start, fallbackFrom: null, retries: attempt, error: null, target: keys };
+        }
+        finally {
+            await client.close();
+        }
+    }
     // ── Blocker classification ──────────────────────
     /** Check a single error string for blocker patterns. */
     classifyBlocker(error) {

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";