@melaya/runner 1.0.118 → 1.1.0

package/dist/sessionManager.js

@@ -0,0 +1,290 @@
+// packages/runner/src/sessionManager.ts
+//
+// Melaya Browser, Phase 1 (plan Section 7): runner-side session, Space,
+// target-lease, and ownership state machine.
+//
+// Core invariants:
+//   - OWNERSHIP: a session is "owned" (we launched the browser process
+//     into a dedicated Melaya user-data-dir) or "attached" (we connected
+//     over CDP to a browser the user controls). Teardown closes ONLY
+//     owned browsers/contexts; attached browsers are merely detached
+//     from (playwright.Browser.close() on a connectOverCDP handle only
+//     severs the connection, it does not kill the user's browser — we
+//     still guard it and NEVER close attached pages/contexts).
+//   - LEASES: every operated target is leased to exactly one run.
+//     A lease carries a snapshotGeneration (incremented on every
+//     re-snapshot) and a documentGeneration (incremented on every
+//     main-frame navigation). @eN refs bind to BOTH; a mismatch is a
+//     typed stale_ref error upstream (fail closed).
+//   - TTLs: idle sessions are swept; a hard max-lifetime cap bounds
+//     even a busy session. Crash recovery marks the session crashed so
+//     the next op returns a typed error instead of hanging.
+//   - Spaces: an ephemeral Space is a temp user-data-dir deleted at
+//     teardown; a persistent Space maps to a stable directory under
+//     ~/.melaya-runner/browser-spaces/<spaceId> that survives runs.
+//     NEVER the real default browser profile (Chrome 136+ ignores the
+//     debug port on the default dir; plan Section 7).
+import { mkdirSync, rmSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir, homedir } from "node:os";
+import { randomBytes, randomUUID } from "node:crypto";
+// ---------------------------------------------------------------------
+// Runner device identity (stable across restarts; advertised in the
+// runner hello and asserted against grant.runnerDevice)
+// ---------------------------------------------------------------------
+let _deviceId = "";
+export function getRunnerDeviceId() {
+    if (_deviceId)
+        return _deviceId;
+    const dir = join(homedir(), ".melaya-runner");
+    const file = join(dir, "device-id");
+    try {
+        if (existsSync(file)) {
+            const v = readFileSync(file, "utf-8").trim();
+            if (/^rnr_[a-f0-9]{32}$/.test(v)) {
+                _deviceId = v;
+                return v;
+            }
+        }
+    }
+    catch { /* regenerate below */ }
+    const fresh = `rnr_${randomBytes(16).toString("hex")}`;
+    try {
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(file, fresh, "utf-8");
+    }
+    catch { /* still usable in-memory for this process */ }
+    _deviceId = fresh;
+    return fresh;
+}
+export class SessionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SessionError";
+        this.code = code;
+    }
+}
+const DEFAULT_IDLE_TTL_MS = 10 * 60 * 1000; // 10 min without an op
+const DEFAULT_MAX_LIFETIME_MS = 60 * 60 * 1000; // 60 min hard cap
+// ---------------------------------------------------------------------
+// Space directories
+// ---------------------------------------------------------------------
+export function spaceUserDataDir(space, runId) {
+    if (space.kind === "persistent") {
+        const id = String(space.id || "").replace(/[^A-Za-z0-9._-]/g, "_");
+        if (!id)
+            throw new SessionError("session_not_found", "persistent Space requires a stable id");
+        const dir = join(homedir(), ".melaya-runner", "browser-spaces", id);
+        mkdirSync(dir, { recursive: true });
+        return { dir, ephemeral: false };
+    }
+    const dir = join(tmpdir(), `melaya-browser-${runId}-${randomBytes(4).toString("hex")}`);
+    mkdirSync(dir, { recursive: true });
+    return { dir, ephemeral: true };
+}
+// ---------------------------------------------------------------------
+// SessionManager
+// ---------------------------------------------------------------------
+export class SessionManager {
+    sessions = new Map(); // by runId
+    sweeper = null;
+    log;
+    constructor(opts = {}) {
+        this.log = opts.log ?? (() => { });
+        this.sweeper = setInterval(() => this.sweep(), 60_000);
+        // Never keep the runner process alive just for the sweeper.
+        if (typeof this.sweeper.unref === "function")
+            this.sweeper.unref();
+    }
+    /** Create the session record; the caller (bridge) supplies the live
+     *  Playwright handles once launch/attach succeeds. */
+    createSession(opts) {
+        if (this.sessions.has(opts.runId)) {
+            throw new SessionError("lease_conflict", `run ${opts.runId} already holds a browser session`);
+        }
+        const rec = {
+            id: randomUUID(),
+            runId: opts.runId,
+            ownership: opts.ownership,
+            engine: opts.engine,
+            state: "connecting",
+            space: opts.space,
+            browser: null,
+            context: null,
+            targets: new Map(),
+            createdAt: Date.now(),
+            lastActivity: Date.now(),
+            idleTtlMs: opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS,
+            maxLifetimeMs: opts.maxLifetimeMs ?? DEFAULT_MAX_LIFETIME_MS,
+            ephemeralUserDataDir: null,
+            cancelled: false,
+        };
+        this.sessions.set(opts.runId, rec);
+        return rec;
+    }
+    attachHandles(rec, handles) {
+        rec.browser = handles.browser ?? null;
+        rec.context = handles.context;
+        rec.ephemeralUserDataDir = handles.ephemeralUserDataDir ?? null;
+        rec.state = "ready";
+        // Crash recovery: a dying browser flips the session to "crashed" so
+        // subsequent ops return a typed error instead of a Playwright hang;
+        // leases and refs are dropped (they can never be valid again).
+        const onGone = () => {
+            if (rec.state === "closed")
+                return;
+            rec.state = "crashed";
+            rec.targets.clear();
+            this.log(`browser session for run ${rec.runId.slice(0, 10)} crashed/disconnected`);
+        };
+        if (rec.browser)
+            rec.browser.on("disconnected", onGone);
+        rec.context.on("close", () => {
+            if (rec.state !== "closed")
+                onGone();
+        });
+    }
+    getSession(runId) {
+        const rec = this.sessions.get(runId);
+        if (!rec)
+            throw new SessionError("session_not_found", `no browser session for run ${runId}`);
+        if (rec.state === "crashed")
+            throw new SessionError("session_crashed", "browser session crashed; relaunch required");
+        if (rec.state === "closed" || rec.cancelled)
+            throw new SessionError("session_closed", "browser session is closed");
+        return rec;
+    }
+    peekSession(runId) {
+        return this.sessions.get(runId);
+    }
+    touch(rec) {
+        rec.lastActivity = Date.now();
+    }
+    // -- Target leases ---------------------------------------------------
+    leaseTarget(rec, ref, page) {
+        const existing = rec.targets.get(ref);
+        if (existing)
+            return existing;
+        const lease = {
+            ref,
+            page,
+            snapshotGeneration: 0,
+            documentGeneration: 0,
+            refs: new Map(),
+            lastActivity: Date.now(),
+            opChain: Promise.resolve(),
+        };
+        // Main-frame navigation invalidates every ref bound to the previous
+        // document (documentGeneration bump; plan Section 8 fail-closed rule).
+        page.on("framenavigated", (frame) => {
+            if (frame === page.mainFrame()) {
+                lease.documentGeneration += 1;
+                lease.refs.clear();
+            }
+        });
+        page.on("close", () => {
+            rec.targets.delete(ref);
+        });
+        rec.targets.set(ref, lease);
+        return lease;
+    }
+    getLease(rec, ref) {
+        const lease = rec.targets.get(ref);
+        if (!lease)
+            throw new SessionError("target_not_found", `no leased target '${ref}' (tab closed or lease expired)`);
+        return lease;
+    }
+    /** New snapshot -> new generation; every previously issued @eN ref
+     *  becomes stale by construction. */
+    beginSnapshot(lease) {
+        lease.snapshotGeneration += 1;
+        lease.refs.clear();
+        lease.lastActivity = Date.now();
+        return lease.snapshotGeneration;
+    }
+    bindRef(lease, binding) {
+        lease.refs.set(binding.ref, binding);
+    }
+    /** Resolve an @eN ref, failing closed on ANY generation mismatch. */
+    resolveRef(lease, ref) {
+        const b = lease.refs.get(ref);
+        if (!b) {
+            throw new SessionError("stale_ref", `ref '${ref}' is unknown in the current snapshot; call get_screen_tree and retry with a fresh ref`);
+        }
+        if (b.snapshotGeneration !== lease.snapshotGeneration || b.documentGeneration !== lease.documentGeneration) {
+            throw new SessionError("stale_ref", `ref '${ref}' is stale (snapshot ${b.snapshotGeneration}/${lease.snapshotGeneration}, document ${b.documentGeneration}/${lease.documentGeneration}); re-snapshot required`);
+        }
+        return b;
+    }
+    /** Serialize an operation on a target (one write at a time per lease). */
+    runOnTarget(lease, op) {
+        const next = lease.opChain.then(op, op);
+        lease.opChain = next.catch(() => { });
+        lease.lastActivity = Date.now();
+        return next;
+    }
+    // -- Teardown ----------------------------------------------------------
+    /** Tear down a run's session. Closes ONLY owned contexts/browsers; an
+     *  attached (user-owned) browser is disconnected from, never closed.
+     *  Idempotent; safe on every terminal path. */
+    async teardownRun(runId, reason) {
+        const rec = this.sessions.get(runId);
+        if (!rec)
+            return;
+        this.sessions.delete(runId);
+        if (rec.state === "closed")
+            return;
+        rec.cancelled = true; // cancels in-flight ops at their next gate
+        const wasState = rec.state;
+        rec.state = "closed";
+        rec.targets.clear();
+        this.log(`teardown browser session run=${runId.slice(0, 10)} ownership=${rec.ownership} reason=${reason} (was ${wasState})`);
+        try {
+            if (rec.ownership === "owned") {
+                // Owned: close context (persistent-context launches close the
+                // whole browser process with it), then the browser if separate.
+                if (rec.context)
+                    await rec.context.close().catch(() => { });
+                if (rec.browser)
+                    await rec.browser.close().catch(() => { });
+            }
+            else {
+                // Attached: sever the CDP connection ONLY. Browser.close() on a
+                // connectOverCDP browser disconnects without killing the user's
+                // browser (Playwright-documented behavior); we still avoid
+                // touching contexts/pages so nothing user-visible closes.
+                if (rec.browser)
+                    await rec.browser.close().catch(() => { });
+            }
+        }
+        finally {
+            if (rec.ephemeralUserDataDir) {
+                try {
+                    rmSync(rec.ephemeralUserDataDir, { recursive: true, force: true, maxRetries: 3 });
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    async teardownAll(reason) {
+        const ids = [...this.sessions.keys()];
+        await Promise.all(ids.map((id) => this.teardownRun(id, reason)));
+    }
+    /** TTL sweep: idle timeout + hard max lifetime. */
+    sweep() {
+        const now = Date.now();
+        for (const [runId, rec] of this.sessions) {
+            const idle = now - rec.lastActivity > rec.idleTtlMs;
+            const overMax = now - rec.createdAt > rec.maxLifetimeMs;
+            if (idle || overMax) {
+                void this.teardownRun(runId, idle ? "idle_ttl" : "max_lifetime");
+            }
+        }
+    }
+    dispose() {
+        if (this.sweeper)
+            clearInterval(this.sweeper);
+        this.sweeper = null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.0.118",
+  "version": "1.1.0",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,
@@ -20,17 +20,19 @@
   ],
   "scripts": {
     "build": "tsc && node -e \"const fs=require('fs'); fs.copyFileSync('localRagIngest.py','dist/localRagIngest.py'); fs.copyFileSync('localRagRetrieve.py','dist/localRagRetrieve.py'); fs.copyFileSync('src/assistantHost.py','dist/assistantHost.py')\"",
+    "test": "node --test --import tsx \"src/**/*.test.ts\"",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "ora": "^8.0.0",
-    "playwright": "^1.47.0",
+    "playwright": "^1.48.0",
     "socket.io-client": "^4.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "tsx": "^4.19.2",
     "typescript": "^5.5.0"
   },
   "engines": {