@melaya/runner 1.0.15 → 1.0.18

package/dist/connection.js

@@ -154,6 +154,40 @@ export async function connect(opts) {
             socket.emit("runner:runComplete", { runId: payload.runId, status: "failed" });
         }
     });
+    // ── LinkedIn cookie capture (one-time) ────────────────────────────
+    // When the user clicks "Connect LinkedIn" in the platform UI, the
+    // server emits this event. We launch a controlled Chromium window on
+    // the user's machine, they sign in normally, and we read the resulting
+    // li_at + JSESSIONID cookies from the browser context. The cookies
+    // travel back to the server as `linkedin:login-result` and get stored
+    // envelope-encrypted in agents.credentials — identical to every other
+    // connector. After that, the LinkedIn pipelines (auto-like / auto-reply
+    // / auto-connect) just read LINKEDIN_LI_AT / LINKEDIN_JSESSIONID from
+    // env at run time and call Voyager directly with aiohttp.
+    socket.on("linkedin:start-login", async (req) => {
+        const sid = req?.session_id;
+        if (!sid)
+            return;
+        console.log(chalk.hex("#0A66C2")(`\n  ▶ LinkedIn login requested (session ${sid.slice(0, 8)}…)`));
+        const emitProgress = (msg) => {
+            socket.emit("linkedin:login-progress", { session_id: sid, message: msg });
+            if (opts.verbose)
+                console.log(chalk.gray(`  [linkedin] ${msg}`));
+        };
+        try {
+            const { runLinkedInLoginFlow, describeOutcome } = await import("./linkedinLogin.js");
+            const outcome = await runLinkedInLoginFlow(emitProgress);
+            console.log(describeOutcome(outcome));
+            socket.emit("linkedin:login-result", { session_id: sid, ...outcome });
+        }
+        catch (e) {
+            const msg = e?.message || "linkedin_login_unhandled_error";
+            console.log(chalk.red(`  ✗ LinkedIn login failed: ${msg}`));
+            socket.emit("linkedin:login-result", {
+                session_id: sid, ok: false, error: "login_unhandled_error", detail: msg,
+            });
+        }
+    });
     // ── Kill command ───────────────────────────────────────────────────
     socket.on("runner:kill", (data) => {
         const proc = activeProcesses.get(data.runId);
@@ -163,6 +197,102 @@ export async function connect(opts) {
             console.log(chalk.yellow(`  ■ Killed run ${data.runId.slice(0, 10)}...`));
         }
     });
+    // ── LLM stream relay ───────────────────────────────────────────────
+    //
+    // The cloud server picked the user's local Ollama / LM Studio model
+    // for an AI feature (Build-with-AI architect, etc.) — but the LLM
+    // server only exists on this machine, so we proxy the chat-completion
+    // here: fetch the local URL, stream chunks back over the existing
+    // socket. The server-side `streamLLMViaRunner()` consumes them.
+    //
+    // Protocol:
+    //   server → runner: runner:llm-stream-request { reqId, url, headers, body }
+    //   runner → server: runner:llm-stream-chunk   { reqId, chunk: string }
+    //   runner → server: runner:llm-stream-end     { reqId, status }
+    //   runner → server: runner:llm-stream-error   { reqId, error }
+    //   server → runner: runner:llm-stream-cancel  { reqId }
+    const _activeLLMStreams = new Map();
+    socket.on("runner:llm-stream-request", async (req) => {
+        const reqId = req?.reqId;
+        if (!reqId || typeof req.url !== "string")
+            return;
+        // Defense-in-depth: only allow loopback URLs. The server already
+        // generates these as `http://localhost:1234` / `http://localhost:11434`,
+        // but enforcing it here means a compromised server connection can't
+        // pivot the runner into making outbound requests on its behalf.
+        let parsed;
+        try {
+            parsed = new URL(req.url);
+        }
+        catch {
+            socket.emit("runner:llm-stream-error", { reqId, error: "invalid_url" });
+            return;
+        }
+        if (parsed.hostname !== "localhost" && parsed.hostname !== "127.0.0.1" && parsed.hostname !== "::1") {
+            socket.emit("runner:llm-stream-error", { reqId, error: "non_loopback_url_rejected" });
+            return;
+        }
+        if (opts.verbose)
+            console.log(chalk.gray(`  [llm-relay] ${reqId.slice(0, 12)} → ${req.url}`));
+        const ac = new AbortController();
+        _activeLLMStreams.set(reqId, ac);
+        try {
+            const upstream = await fetch(req.url, {
+                method: "POST",
+                headers: req.headers || { "content-type": "application/json" },
+                body: req.body || "",
+                signal: ac.signal,
+            });
+            if (!upstream.body) {
+                const text = await upstream.text().catch(() => "");
+                socket.emit("runner:llm-stream-error", {
+                    reqId,
+                    error: `upstream_no_body status=${upstream.status} ${text.slice(0, 200)}`,
+                });
+                return;
+            }
+            // Pipe chunks back as decoded text. The cloud server's parser is
+            // text-oriented (SSE `data:` lines) so we decode here and ship
+            // strings rather than base64 — keeps the WS payload small + lets
+            // the server keep its existing line-buffer code path.
+            const reader = upstream.body.getReader();
+            const decoder = new TextDecoder();
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                const chunk = decoder.decode(value, { stream: true });
+                if (chunk.length > 0) {
+                    socket.emit("runner:llm-stream-chunk", { reqId, chunk });
+                }
+            }
+            // Flush any tail bytes.
+            const tail = decoder.decode();
+            if (tail.length > 0)
+                socket.emit("runner:llm-stream-chunk", { reqId, chunk: tail });
+            socket.emit("runner:llm-stream-end", { reqId, status: upstream.status });
+            if (opts.verbose)
+                console.log(chalk.gray(`  [llm-relay] ${reqId.slice(0, 12)} ◄ end ${upstream.status}`));
+        }
+        catch (e) {
+            if (e?.name === "AbortError") {
+                socket.emit("runner:llm-stream-error", { reqId, error: "aborted" });
+            }
+            else {
+                socket.emit("runner:llm-stream-error", { reqId, error: String(e?.message || e) });
+            }
+        }
+        finally {
+            _activeLLMStreams.delete(reqId);
+        }
+    });
+    socket.on("runner:llm-stream-cancel", (req) => {
+        const ac = _activeLLMStreams.get(req?.reqId);
+        if (ac) {
+            ac.abort();
+            _activeLLMStreams.delete(req.reqId);
+        }
+    });
     // ── Graceful shutdown ──────────────────────────────────────────────
     const cleanup = () => {
         console.log(chalk.gray("\n  Shutting down..."));

package/dist/linkedinLogin.d.ts

@@ -0,0 +1,65 @@
+/**
+ * LinkedIn cookie capture via a controlled Chromium window.
+ *
+ * Flow
+ * ----
+ * 1. The Melaya server emits `linkedin:start-login` to this runner over
+ *    Socket.IO when the user clicks "Connect LinkedIn" in the platform UI.
+ * 2. We launch a HEADED Chromium window pointed at
+ *    https://www.linkedin.com/login. The user signs in normally — email,
+ *    password, any 2FA challenge — exactly like signing in in their
+ *    everyday browser. Their password never touches the runner or the
+ *    Melaya server: it goes from their keyboard straight to LinkedIn's
+ *    own login form.
+ * 3. We poll the page URL. As soon as it lands on a logged-in LinkedIn
+ *    page (`/feed/*`, `/in/*`, `/mynetwork/*`, …) we read the
+ *    `li_at` and `JSESSIONID` cookies from the browser context.
+ * 4. The cookies are returned over Socket.IO as `linkedin:login-result`.
+ *    The Melaya server stores them envelope-encrypted in
+ *    `agents.credentials` for that user, exactly like every other
+ *    connector credential. The browser window auto-closes.
+ *
+ * Lazy chromium install
+ * ---------------------
+ * We don't ship Chromium with the runner package (saves ~140 MB on
+ * `npx @melaya/runner` first run). The first time a user clicks
+ * "Connect LinkedIn", we shell out to `npx playwright install chromium`
+ * and stream the install progress back to the UI so they see something
+ * happening. Subsequent runs reuse the cached browser.
+ *
+ * Why a real browser at all
+ * -------------------------
+ * LinkedIn's Voyager API (the only LinkedIn surface that exposes likes,
+ * replies, and connection requests on personal accounts) is cookie-auth,
+ * not OAuth. The cookies can only be obtained by completing a real login
+ * that satisfies LinkedIn's CSRF + captcha + 2FA gauntlet. A headed
+ * Chromium is the only flow that's both "the user logs in normally" and
+ * "no DevTools required." The browser is used ONCE per ~year (or until
+ * the session expires) — every subsequent Voyager call is direct
+ * aiohttp HTTPS, no browser needed.
+ */
+export interface LinkedInLoginResult {
+    ok: true;
+    cookies: {
+        li_at: string;
+        JSESSIONID: string;
+    };
+    profileName?: string;
+}
+export interface LinkedInLoginError {
+    ok: false;
+    error: string;
+    detail?: string;
+}
+export type LinkedInLoginOutcome = LinkedInLoginResult | LinkedInLoginError;
+interface ProgressEmitter {
+    (msg: string): void;
+}
+export declare function runLinkedInLoginFlow(progress: ProgressEmitter): Promise<LinkedInLoginOutcome>;
+/**
+ * Pretty-print a one-liner summary of the outcome — used by the runner
+ * CLI logger so the operator sees something on stdout while the web UI
+ * also reflects the result via the relay.
+ */
+export declare function describeOutcome(outcome: LinkedInLoginOutcome): string;
+export {};

package/dist/linkedinLogin.js

@@ -0,0 +1,243 @@
+/**
+ * LinkedIn cookie capture via a controlled Chromium window.
+ *
+ * Flow
+ * ----
+ * 1. The Melaya server emits `linkedin:start-login` to this runner over
+ *    Socket.IO when the user clicks "Connect LinkedIn" in the platform UI.
+ * 2. We launch a HEADED Chromium window pointed at
+ *    https://www.linkedin.com/login. The user signs in normally — email,
+ *    password, any 2FA challenge — exactly like signing in in their
+ *    everyday browser. Their password never touches the runner or the
+ *    Melaya server: it goes from their keyboard straight to LinkedIn's
+ *    own login form.
+ * 3. We poll the page URL. As soon as it lands on a logged-in LinkedIn
+ *    page (`/feed/*`, `/in/*`, `/mynetwork/*`, …) we read the
+ *    `li_at` and `JSESSIONID` cookies from the browser context.
+ * 4. The cookies are returned over Socket.IO as `linkedin:login-result`.
+ *    The Melaya server stores them envelope-encrypted in
+ *    `agents.credentials` for that user, exactly like every other
+ *    connector credential. The browser window auto-closes.
+ *
+ * Lazy chromium install
+ * ---------------------
+ * We don't ship Chromium with the runner package (saves ~140 MB on
+ * `npx @melaya/runner` first run). The first time a user clicks
+ * "Connect LinkedIn", we shell out to `npx playwright install chromium`
+ * and stream the install progress back to the UI so they see something
+ * happening. Subsequent runs reuse the cached browser.
+ *
+ * Why a real browser at all
+ * -------------------------
+ * LinkedIn's Voyager API (the only LinkedIn surface that exposes likes,
+ * replies, and connection requests on personal accounts) is cookie-auth,
+ * not OAuth. The cookies can only be obtained by completing a real login
+ * that satisfies LinkedIn's CSRF + captcha + 2FA gauntlet. A headed
+ * Chromium is the only flow that's both "the user logs in normally" and
+ * "no DevTools required." The browser is used ONCE per ~year (or until
+ * the session expires) — every subsequent Voyager call is direct
+ * aiohttp HTTPS, no browser needed.
+ */
+import { spawn } from "child_process";
+import chalk from "chalk";
+const LOGIN_TIMEOUT_MS = 5 * 60_000; // 5 min for the user to finish typing
+const POLL_INTERVAL_MS = 750;
+// URL fragments that indicate "the user is logged in" — LinkedIn redirects
+// to /feed/ after the standard sign-in, but if 2FA was just completed it
+// might land on /checkpoint/lg/ first or /home — accept any logged-in path.
+const LOGGED_IN_PATHS = [
+    "/feed/", "/feed",
+    "/in/",
+    "/mynetwork/",
+    "/home/",
+    "/notifications/",
+    "/messaging/",
+];
+/**
+ * Ensure the `playwright` package is importable. We pre-declared it as
+ * a dependency in package.json — this is a guard for cases where npm
+ * stripped it (corrupt install) or the user is running from a weird env.
+ */
+async function _ensurePlaywrightAvailable(progress) {
+    try {
+        return await import("playwright");
+    }
+    catch (e) {
+        progress("Playwright module not found in node_modules. Re-installing the runner usually fixes this.");
+        throw new Error(`playwright_unavailable: ${e?.message || e}`);
+    }
+}
+/**
+ * Run `npx playwright install chromium` and stream stdout back via
+ * `progress`. Resolves when the child process exits with code 0,
+ * rejects otherwise. Idempotent — if Chromium is already installed,
+ * Playwright's installer prints a one-line "already installed" and
+ * exits 0 in well under a second.
+ */
+function _installChromium(progress) {
+    return new Promise((resolve, reject) => {
+        progress("Preparing browser for LinkedIn sign-in (one-time setup, ~140 MB)…");
+        // On Windows `npx` is a `.cmd` shim — `spawn` handles it correctly when
+        // given the bare command name and `shell: true`.
+        const child = spawn("npx", ["playwright", "install", "chromium"], {
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        child.stdout?.on("data", (b) => {
+            const line = b.toString().trim();
+            if (line)
+                progress(line);
+        });
+        child.stderr?.on("data", (b) => {
+            const line = b.toString().trim();
+            if (line)
+                progress(line);
+        });
+        child.on("error", (e) => reject(new Error(`chromium_install_error: ${e.message}`)));
+        child.on("exit", (code) => {
+            if (code === 0) {
+                progress("Browser ready.");
+                resolve();
+            }
+            else {
+                reject(new Error(`chromium_install_failed: exit code ${code}`));
+            }
+        });
+    });
+}
+function _pageLooksLoggedIn(url) {
+    try {
+        const u = new URL(url);
+        if (u.hostname !== "www.linkedin.com" && u.hostname !== "linkedin.com")
+            return false;
+        return LOGGED_IN_PATHS.some((p) => u.pathname.startsWith(p));
+    }
+    catch {
+        return false;
+    }
+}
+export async function runLinkedInLoginFlow(progress) {
+    // 1. Ensure Playwright + Chromium are available.
+    let playwright;
+    try {
+        playwright = await _ensurePlaywrightAvailable(progress);
+    }
+    catch (e) {
+        return { ok: false, error: "playwright_unavailable", detail: e?.message };
+    }
+    try {
+        await _installChromium(progress);
+    }
+    catch (e) {
+        return { ok: false, error: "chromium_install_failed", detail: e?.message };
+    }
+    // 2. Launch a headed Chromium window. Use a fresh context (no profile
+    //    reuse) so the user always sees a clean LinkedIn login page even
+    //    if they have an old / wrong account session lying around.
+    let browser = null;
+    try {
+        progress("Opening LinkedIn login window…");
+        browser = await playwright.chromium.launch({
+            headless: false,
+            args: [
+                "--disable-blink-features=AutomationControlled",
+            ],
+        });
+        const context = await browser.newContext({
+            userAgent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
+                "(KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36",
+            viewport: { width: 1280, height: 820 },
+        });
+        const page = await context.newPage();
+        await page.goto("https://www.linkedin.com/login", { waitUntil: "domcontentloaded" });
+        progress("Sign in with your LinkedIn account in the window that just opened.");
+        // 3. Wait for the user to finish signing in. Two terminal conditions:
+        //    (a) URL becomes a logged-in LinkedIn path → success.
+        //    (b) The user closes the window manually → cancellation.
+        //    A 5-minute total timeout protects against the user walking away.
+        const start = Date.now();
+        let succeeded = false;
+        while (Date.now() - start < LOGIN_TIMEOUT_MS) {
+            // browser closed externally → context.pages() throws.
+            let url;
+            try {
+                url = page.url();
+            }
+            catch {
+                return { ok: false, error: "user_cancelled", detail: "Login window was closed before sign-in completed." };
+            }
+            if (_pageLooksLoggedIn(url)) {
+                succeeded = true;
+                break;
+            }
+            await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+        }
+        if (!succeeded) {
+            return { ok: false, error: "login_timeout", detail: "5-minute sign-in window expired." };
+        }
+        // 4. Extract cookies. Voyager auth = `li_at` + `JSESSIONID`.
+        const cookies = await context.cookies("https://www.linkedin.com");
+        const li_at_c = cookies.find((c) => c.name === "li_at");
+        const js_c = cookies.find((c) => c.name === "JSESSIONID");
+        if (!li_at_c?.value || !js_c?.value) {
+            return {
+                ok: false, error: "cookies_not_found",
+                detail: "Sign-in completed but li_at / JSESSIONID cookies were missing. Try again and complete the LinkedIn 2FA challenge if prompted.",
+            };
+        }
+        const li_at = li_at_c.value;
+        const JSESSIONID = js_c.value;
+        // 5. Optional pretty touch: pull the operator's display name so the
+        //    UI can show "Connected as Antoine Roche". Use the now-logged-in
+        //    page to evaluate window.__INITIAL_SHARED_DATA__ — best effort,
+        //    failures are non-fatal.
+        let profileName;
+        try {
+            profileName = await page.evaluate(() => {
+                // The /feed page exposes the user's name in several places. Probe a few
+                // reliable selectors before falling back to undefined.
+                const sel = (s) => {
+                    const el = document.querySelector(s);
+                    return el ? (el.textContent || "").trim() : "";
+                };
+                return (sel(".global-nav__me .global-nav__primary-link-text")
+                    || sel(".feed-identity-module__actor-meta a")
+                    || sel("a[data-test-app-aware-link] .feed-identity-module__actor-meta")
+                    || undefined);
+            });
+        }
+        catch { /* swallow */ }
+        progress(profileName ? `Captured session for ${profileName}.` : "Captured session.");
+        // 6. Close the window — we're done with the browser. No need to keep
+        //    it open: every subsequent Voyager call uses the cookies via
+        //    direct aiohttp, not Playwright.
+        await context.close();
+        await browser.close();
+        return { ok: true, cookies: { li_at, JSESSIONID }, profileName };
+    }
+    catch (e) {
+        return {
+            ok: false, error: "login_flow_error",
+            detail: e?.message || String(e),
+        };
+    }
+    finally {
+        if (browser) {
+            try {
+                await browser.close();
+            }
+            catch { /* already closed */ }
+        }
+    }
+}
+/**
+ * Pretty-print a one-liner summary of the outcome — used by the runner
+ * CLI logger so the operator sees something on stdout while the web UI
+ * also reflects the result via the relay.
+ */
+export function describeOutcome(outcome) {
+    if (outcome.ok) {
+        return chalk.green(`  ✓ LinkedIn session captured${outcome.profileName ? ` (${outcome.profileName})` : ""}.`);
+    }
+    return chalk.red(`  ✗ LinkedIn login: ${outcome.error}${outcome.detail ? ` — ${outcome.detail}` : ""}`);
+}

package/dist/linkedinProxy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * LinkedIn Voyager-API egress for the @melaya/runner.
+ *
+ * The server (Alibaba) forwards LinkedIn API calls to the runner via
+ * Socket.IO `linkedin:exec` events. This module:
+ *
+ *   1. Reads the operator's local cookies (li_at + JSESSIONID) from
+ *      ~/.melaya-runner/linkedin/cookies.json. The cookies were saved
+ *      via `npx @melaya/runner linkedin-setup`. They never leave this
+ *      machine.
+ *
+ *   2. Issues the actual HTTPS call to LinkedIn's Voyager API
+ *      (https://www.linkedin.com/voyager/api/...) using Node's native
+ *      fetch. The egress IP is the operator's residential IP — exactly
+ *      what they normally browse LinkedIn from, so no automation
+ *      flags.
+ *
+ *   3. For "write" actions (likes / replies / connection requests)
+ *      inserts a 3-9s human pause before the call, increments a daily
+ *      counter at ~/.melaya-runner/linkedin/usage-{YYYY-MM-DD}.json,
+ *      and refuses with `daily_cap_reached` past the configured cap.
+ *
+ *   4. Returns { status, body } back to the server so the caller (the
+ *      Python agent's social_linkedin tool) can parse the response.
+ *
+ * Caps (override via env on the runner):
+ *   LINKEDIN_DAILY_LIKES_CAP        default 50
+ *   LINKEDIN_DAILY_REPLIES_CAP      default 20
+ *   LINKEDIN_DAILY_CONNECTIONS_CAP  default 15
+ */
+interface LinkedInCookies {
+    li_at: string;
+    JSESSIONID: string;
+}
+export declare function readCookies(): LinkedInCookies | null;
+export declare function writeCookies(c: LinkedInCookies): string;
+export interface LinkedInExecRequest {
+    correlation_id: string;
+    method: string;
+    path: string;
+    params?: Record<string, unknown> | null;
+    body?: unknown;
+    write?: boolean;
+}
+export interface LinkedInExecResult {
+    status?: number;
+    body?: unknown;
+    error?: string;
+}
+export declare function handleLinkedInExec(req: LinkedInExecRequest, verbose?: boolean): Promise<LinkedInExecResult>;
+export {};

package/dist/linkedinProxy.js

@@ -0,0 +1,216 @@
+/**
+ * LinkedIn Voyager-API egress for the @melaya/runner.
+ *
+ * The server (Alibaba) forwards LinkedIn API calls to the runner via
+ * Socket.IO `linkedin:exec` events. This module:
+ *
+ *   1. Reads the operator's local cookies (li_at + JSESSIONID) from
+ *      ~/.melaya-runner/linkedin/cookies.json. The cookies were saved
+ *      via `npx @melaya/runner linkedin-setup`. They never leave this
+ *      machine.
+ *
+ *   2. Issues the actual HTTPS call to LinkedIn's Voyager API
+ *      (https://www.linkedin.com/voyager/api/...) using Node's native
+ *      fetch. The egress IP is the operator's residential IP — exactly
+ *      what they normally browse LinkedIn from, so no automation
+ *      flags.
+ *
+ *   3. For "write" actions (likes / replies / connection requests)
+ *      inserts a 3-9s human pause before the call, increments a daily
+ *      counter at ~/.melaya-runner/linkedin/usage-{YYYY-MM-DD}.json,
+ *      and refuses with `daily_cap_reached` past the configured cap.
+ *
+ *   4. Returns { status, body } back to the server so the caller (the
+ *      Python agent's social_linkedin tool) can parse the response.
+ *
+ * Caps (override via env on the runner):
+ *   LINKEDIN_DAILY_LIKES_CAP        default 50
+ *   LINKEDIN_DAILY_REPLIES_CAP      default 20
+ *   LINKEDIN_DAILY_CONNECTIONS_CAP  default 15
+ */
+import { mkdirSync, readFileSync, writeFileSync, existsSync, chmodSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import chalk from "chalk";
+const VOYAGER_BASE = "https://www.linkedin.com/voyager/api";
+const USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " +
+    "AppleWebKit/537.36 (KHTML, like Gecko) " +
+    "Chrome/127.0.0.0 Safari/537.36";
+// ── Storage paths ─────────────────────────────────────────────────────────────
+function stateDir() {
+    return process.env.MELAYA_LINKEDIN_DIR || join(homedir(), ".melaya-runner", "linkedin");
+}
+function cookiesPath() {
+    return join(stateDir(), "cookies.json");
+}
+function usagePath() {
+    const day = new Date().toISOString().slice(0, 10);
+    return join(stateDir(), `usage-${day}.json`);
+}
+// ── Caps ──────────────────────────────────────────────────────────────────────
+function envCap(name, fallback) {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+const CAP_LIKES = envCap("LINKEDIN_DAILY_LIKES_CAP", 50);
+const CAP_REPLIES = envCap("LINKEDIN_DAILY_REPLIES_CAP", 20);
+const CAP_CONNECTIONS = envCap("LINKEDIN_DAILY_CONNECTIONS_CAP", 15);
+function readUsage() {
+    const p = usagePath();
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function bumpUsage(action) {
+    mkdirSync(stateDir(), { recursive: true });
+    const counts = readUsage();
+    counts[action] = (counts[action] || 0) + 1;
+    writeFileSync(usagePath(), JSON.stringify(counts));
+    return counts[action];
+}
+export function readCookies() {
+    const p = cookiesPath();
+    if (!existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(p, "utf-8"));
+        if (raw && typeof raw.li_at === "string" && typeof raw.JSESSIONID === "string"
+            && raw.li_at.length > 10 && raw.JSESSIONID.length > 10) {
+            return raw;
+        }
+    }
+    catch { /* corrupt file */ }
+    return null;
+}
+export function writeCookies(c) {
+    mkdirSync(stateDir(), { recursive: true });
+    const p = cookiesPath();
+    writeFileSync(p, JSON.stringify(c, null, 2), "utf-8");
+    // Lock down on POSIX. On Windows the user's profile dir ACL already
+    // restricts read access to the user.
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch { /* ignore Windows */ }
+    return p;
+}
+function csrfToken(jsessionid) {
+    // Voyager expects the JSESSIONID value with quotes stripped.
+    return jsessionid.replace(/^"+|"+$/g, "");
+}
+// ── Action classification (for cap + pause) ──────────────────────────────────
+function classifyAction(method, path) {
+    const m = method.toUpperCase();
+    if (m === "GET")
+        return "read";
+    // Best-effort classifier — the server already passes `write: true`
+    // for actions that should be paused/capped, so this only fires when
+    // the server didn't tag it.
+    if (path.includes("/feed/reactions"))
+        return "like";
+    if (path.includes("/feed/comments"))
+        return "reply";
+    if (path.includes("/voyagerRelationshipsDashMemberRelationships"))
+        return "connect";
+    return "read";
+}
+function capForAction(action) {
+    const u = readUsage();
+    switch (action) {
+        case "like": return { used: u.likes || 0, cap: CAP_LIKES };
+        case "reply": return { used: u.replies || 0, cap: CAP_REPLIES };
+        case "connect": return { used: u.connections || 0, cap: CAP_CONNECTIONS };
+        default: return null;
+    }
+}
+function bumpForAction(action) {
+    switch (action) {
+        case "like": return bumpUsage("likes");
+        case "reply": return bumpUsage("replies");
+        case "connect": return bumpUsage("connections");
+        default: return null;
+    }
+}
+async function humanPause() {
+    const ms = 3000 + Math.floor(Math.random() * 6000);
+    await new Promise((res) => setTimeout(res, ms));
+}
+export async function handleLinkedInExec(req, verbose = false) {
+    const cookies = readCookies();
+    if (!cookies) {
+        return { error: "cookies_missing — run `npx @melaya/runner linkedin-setup` once on this machine" };
+    }
+    const action = classifyAction(req.method, req.path);
+    const isWrite = !!req.write || action !== "read";
+    if (isWrite && action !== "read") {
+        const c = capForAction(action);
+        if (c && c.used >= c.cap) {
+            return { error: `daily_cap_reached: ${action} ${c.used}/${c.cap}. Resets 00:00 UTC.` };
+        }
+        await humanPause();
+    }
+    const csrf = csrfToken(cookies.JSESSIONID);
+    // Build URL with query params (URLSearchParams handles array/object encoding)
+    const url = new URL(VOYAGER_BASE + req.path);
+    if (req.params && typeof req.params === "object") {
+        for (const [k, v] of Object.entries(req.params)) {
+            if (v == null)
+                continue;
+            url.searchParams.append(k, String(v));
+        }
+    }
+    const headers = {
+        "User-Agent": USER_AGENT,
+        "Accept": "application/vnd.linkedin.normalized+json+2.1",
+        "Accept-Language": "en-US,en;q=0.9",
+        "csrf-token": csrf,
+        "x-restli-protocol-version": "2.0.0",
+        "x-li-lang": "en_US",
+        "x-li-track": JSON.stringify({
+            clientVersion: "1.13.0", mpVersion: "1.13.0", osName: "web",
+            timezoneOffset: -8, timezone: "America/Los_Angeles",
+            deviceFormFactor: "DESKTOP", mpName: "voyager-web",
+        }),
+        "Cookie": `li_at=${cookies.li_at}; JSESSIONID=${cookies.JSESSIONID}`,
+        "Referer": "https://www.linkedin.com/feed/",
+        "Origin": "https://www.linkedin.com",
+    };
+    const init = { method: req.method, headers };
+    if (req.body !== null && req.body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(req.body);
+    }
+    if (verbose) {
+        process.stdout.write(chalk.gray(`  [linkedin] ${req.method} ${req.path}${isWrite ? " (write)" : ""}\n`));
+    }
+    let res;
+    try {
+        res = await fetch(url.toString(), init);
+    }
+    catch (e) {
+        return { error: `network_error: ${e?.message || e}` };
+    }
+    const txt = await res.text().catch(() => "");
+    let body = txt;
+    try {
+        body = JSON.parse(txt);
+    }
+    catch { /* keep as text */ }
+    // Bump the counter ONLY on a 2xx — failures don't count toward the
+    // daily quota (LinkedIn doesn't count them either).
+    if (isWrite && res.ok) {
+        bumpForAction(action);
+    }
+    if (verbose) {
+        process.stdout.write(chalk.gray(`  [linkedin] → ${res.status}\n`));
+    }
+    return { status: res.status, body };
+}

package/dist/linkedinSetup.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `npx @melaya/runner linkedin-setup` — interactive cookie onboarding.
+ *
+ * Walks the operator through extracting their LinkedIn session cookies
+ * from a logged-in browser, saves them locally to ~/.melaya-runner/
+ * linkedin/cookies.json, and runs a sanity check (`GET /me`) to confirm
+ * the session is live.
+ *
+ * Cookies are stored ONLY on this machine — never transmitted to the
+ * Melaya server. The agents on the cloud side reach LinkedIn through
+ * a Socket.IO proxy that forwards each call back here for egress.
+ */
+export declare function runLinkedinSetup(): Promise<void>;

package/dist/linkedinSetup.js

@@ -0,0 +1,111 @@
+/**
+ * `npx @melaya/runner linkedin-setup` — interactive cookie onboarding.
+ *
+ * Walks the operator through extracting their LinkedIn session cookies
+ * from a logged-in browser, saves them locally to ~/.melaya-runner/
+ * linkedin/cookies.json, and runs a sanity check (`GET /me`) to confirm
+ * the session is live.
+ *
+ * Cookies are stored ONLY on this machine — never transmitted to the
+ * Melaya server. The agents on the cloud side reach LinkedIn through
+ * a Socket.IO proxy that forwards each call back here for egress.
+ */
+import chalk from "chalk";
+import { createInterface } from "readline";
+import { writeCookies, handleLinkedInExec } from "./linkedinProxy.js";
+function ask(prompt, hidden = false) {
+    return new Promise((resolve) => {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: !hidden,
+        });
+        if (hidden) {
+            // Mask while typing — best-effort; works in most TTYs. Falls back
+            // to plain echo if stdin isn't a TTY.
+            const stdout = process.stdout;
+            const stdin = process.stdin;
+            if (stdin.isTTY) {
+                const onKey = (char) => {
+                    const c = char.toString();
+                    if (c === "\r" || c === "\n")
+                        return;
+                    stdout.write("*");
+                };
+                stdin.on("data", onKey);
+                rl.question(prompt, (answer) => {
+                    stdin.off("data", onKey);
+                    process.stdout.write("\n");
+                    rl.close();
+                    resolve(answer);
+                });
+            }
+            else {
+                rl.question(prompt, (answer) => { rl.close(); resolve(answer); });
+            }
+        }
+        else {
+            rl.question(prompt, (answer) => { rl.close(); resolve(answer); });
+        }
+    });
+}
+const ORANGE = chalk.hex("#FF8C00");
+const CYAN = chalk.hex("#22D3EE");
+const DIM = chalk.gray;
+export async function runLinkedinSetup() {
+    console.log();
+    console.log(CYAN.bold("  ▸ LinkedIn — cookie setup"));
+    console.log(DIM("  ─────────────────────────────────────────────────────"));
+    console.log();
+    console.log(DIM("  Why: agents in cloud pipelines need to reach LinkedIn through"));
+    console.log(DIM("  this machine's residential IP (datacenter IPs get flagged)."));
+    console.log(DIM("  Cookies are saved locally only — never sent to the server."));
+    console.log();
+    console.log(chalk.bold("  Steps:"));
+    console.log(`    1. Open ${ORANGE("https://www.linkedin.com")} in a logged-in browser tab`);
+    console.log(`    2. Open DevTools ${DIM("(F12 / Cmd-Opt-I)")} → Application → Cookies → linkedin.com`);
+    console.log(`    3. Copy the value of ${ORANGE("li_at")}        (long base64-ish token)`);
+    console.log(`    4. Copy the value of ${ORANGE("JSESSIONID")}    (keep the surrounding quotes)`);
+    console.log();
+    const li_at = (await ask("  li_at: ", true)).trim();
+    if (!li_at || li_at.length < 20) {
+        console.log(chalk.red("\n  ✗ li_at looks invalid (too short). Aborting."));
+        process.exit(1);
+    }
+    const JSESSIONID = (await ask("  JSESSIONID: ", true)).trim();
+    if (!JSESSIONID || JSESSIONID.length < 5) {
+        console.log(chalk.red("\n  ✗ JSESSIONID looks invalid. Aborting."));
+        process.exit(1);
+    }
+    const path = writeCookies({ li_at, JSESSIONID });
+    console.log(chalk.green(`\n  ✓ Cookies saved to ${path}`));
+    // Sanity check: hit /me to confirm the session works.
+    console.log(DIM("  Verifying session…"));
+    const result = await handleLinkedInExec({
+        correlation_id: "setup-probe",
+        method: "GET",
+        path: "/me",
+    });
+    if (result.error) {
+        console.log(chalk.red(`  ✗ Verification failed: ${result.error}`));
+        console.log(DIM("    Cookies were saved but the test call failed. Try re-pasting from a fresh browser session."));
+        process.exit(2);
+    }
+    if (result.status && result.status >= 200 && result.status < 300) {
+        const body = result.body;
+        const name = body?.miniProfile?.firstName + " " + body?.miniProfile?.lastName
+            || body?.firstName + " " + body?.lastName
+            || "(name not in response)";
+        console.log(chalk.green(`  ✓ Connected as: ${name}`));
+        console.log();
+        console.log(DIM("  You can now run any LinkedIn pipeline from the platform."));
+        console.log(DIM("  Start the runner normally with:"));
+        console.log(`    ${chalk.bold("npx @melaya/runner --token=mel_run_…")}`);
+        console.log();
+    }
+    else {
+        console.log(chalk.yellow(`  ⚠ Unexpected status ${result.status} during verification`));
+        console.log(DIM(`    Body preview: ${JSON.stringify(result.body).slice(0, 200)}`));
+        console.log(DIM("    Cookies were saved; try a pipeline run to see if it works."));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melaya/runner",
-  "version": "1.0.15",
+  "version": "1.0.18",
   "description": "Run Melaya AI pipelines locally with your own LM Studio or Ollama models",
   "license": "UNLICENSED",
   "private": false,
@@ -22,7 +22,8 @@
     "socket.io-client": "^4.8.0",
     "commander": "^12.0.0",
     "chalk": "^5.3.0",
-    "ora": "^8.0.0"
+    "ora": "^8.0.0",
+    "playwright": "^1.47.0"
   },
   "devDependencies": {
     "typescript": "^5.5.0",