social-autoposter 1.6.56 → 1.6.58

package/bin/cli.js

@@ -1223,6 +1223,25 @@ function installRuntime() {
   process.exit(res.status == null ? 1 : res.status);
 }
 
+// Wipe a social-autoposter install back to factory-fresh (test machines /
+// uninstall). Shells out to the bundled scripts/reset-test-machine.sh, which is
+// the single source of truth: it removes the owned state dir (~/.social-
+// autoposter-mcp), packaged Chrome profiles + imported cookies, the browser-
+// harness clone/CLI/server.py, the global npm package, and the MCP registration.
+// DEFAULT IS A DRY RUN (prints what WOULD be removed); pass --yes to apply, and
+// --deep to also remove the shared uv toolchain + Chromium cache. Forwarding to
+// the shell script keeps npm and .mcpb installs behaving identically.
+function reset() {
+  const script = path.join(PKG_ROOT, 'scripts', 'reset-test-machine.sh');
+  if (!fs.existsSync(script)) {
+    console.error(`Cannot find ${script}. Re-run \`npx social-autoposter update\` to repair the install.`);
+    process.exit(1);
+  }
+  // Forward everything after `reset` (e.g. --yes, --deep) straight to the script.
+  const res = spawnSync('bash', [script, ...process.argv.slice(3)], { stdio: 'inherit' });
+  process.exit(res.status == null ? 1 : res.status);
+}
+
 const cmd = process.argv[2];
 if (cmd === 'init') {
   init();
@@ -1234,6 +1253,8 @@ if (cmd === 'init') {
   bootstrapVm();
 } else if (cmd === 'install-runtime') {
   installRuntime();
+} else if (cmd === 'reset' || cmd === 'uninstall') {
+  reset();
 } else if (cmd === 'export-cookies') {
   // Forward to cookie-helper with 'export' + remaining args
   process.argv = [process.argv[0], process.argv[1], 'export', ...process.argv.slice(3)];
@@ -1266,4 +1287,5 @@ if (cmd === 'init') {
   console.log('  npx social-autoposter install-runtime  provision owned Python + Chromium (panel-free)');
   console.log('  npx social-autoposter export-cookies [dir]  export browser cookies');
   console.log('  npx social-autoposter import-cookies [dir]  import browser cookies');
+  console.log('  npx social-autoposter reset [--yes] [--deep]  uninstall/wipe the install (dry-run unless --yes)');
 }

package/mcp/dist/index.js

@@ -13,16 +13,18 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { screencast, bringBrowserToFront } from "./screencast.js";
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs";
 import { repoDir, runPython, run, readPlan, writePlan, planPath, } from "./repo.js";
 import { applySetup, resolveProject, hasReadyProject, listManagedProjectStatus, REQUIRED_FIELDS, RECOMMENDED_FIELDS, configPath, } from "./setup.js";
-import { xStatus, xConnect, summarizeXAuth } from "./twitterAuth.js";
+import { xStatus, xConnect, xDetectSources, summarizeXAuth } from "./twitterAuth.js";
 import { startProvisioning, isProvisioning, readProgress, runtimeReady, readRuntime, resolvePython, } from "./runtime.js";
 import { VERSION, versionStatus, latestPublishedVersion } from "./version.js";
-import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { registerAppTool, registerAppResource, RESOURCE_MIME_TYPE, getUiCapability, } from "@modelcontextprotocol/ext-apps/server";
 import { fileURLToPath } from "node:url";
+import http from "node:http";
 // MCP Apps control panel. The self-contained HTML is built by vite
 // (vite-plugin-singlefile) into dist/panel.html alongside this compiled file.
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
@@ -127,7 +129,25 @@ const server = new McpServer({
         "TYPICAL FLOW: `setup` (configure the project once) -> `draft_cycle` (scan + review a batch; the " +
         "user approves / edits / skips every draft in a single form) -> `autopilot` (enable to also turn " +
         "on hands-free background posting AND daily auto-updates) -> `get_stats` (see performance). Run " +
-        "`setup` first; the other tools refuse until a project is fully configured.",
+        "`setup` first; the other tools refuse until a project is fully configured.\n\n" +
+        "RENDER THE DASHBOARD AFTER ACTIONS. After any state-changing or results-producing tool call " +
+        "(`draft_cycle`, `post_drafts`, `autopilot` enable/disable, `get_stats`), end your turn by " +
+        "calling the `dashboard` tool so the user sees the updated state visually. Do NOT call " +
+        "`dashboard` after pure Q&A, config explanations, or status-only checks that changed nothing.",
+});
+const TOOL_HANDLERS = {};
+const baseRegisterTool = server.registerTool.bind(server);
+// `tool` is TYPED as server.registerTool so every call site keeps the exact
+// same input-schema -> callback-arg inference it had before; the body is `any`
+// and just additionally stashes the callback by name. `appTool` drops the
+// leading `server` arg of registerAppTool (its callback takes no typed args).
+const tool = ((name, config, cb) => {
+    TOOL_HANDLERS[name] = cb;
+    return baseRegisterTool(name, config, cb);
+});
+const appTool = ((name, config, cb) => {
+    TOOL_HANDLERS[name] = cb;
+    return registerAppTool(server, name, config, cb);
 });
 function jsonContent(obj) {
     return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }] };
@@ -413,7 +433,7 @@ server.registerPrompt("getting-started", {
 // across several calls — readiness is derived from config.json, never a stored
 // flag. Call with status:true (or just no name) to list every project this
 // install manages and what each still needs.
-server.registerTool("setup", {
+tool("setup", {
     title: "Set up a project",
     description: "Run this FIRST, before any drafting or autopilot. Two jobs:\n" +
         "1) Configure a project this install posts for: its website, what it does (description), who " +
@@ -431,10 +451,16 @@ server.registerTool("setup", {
     inputSchema: {
         status: z.boolean().optional(),
         action: z
-            .enum(["connect_x"])
+            .enum(["connect_x", "detect_x_sources", "reseed_queries"])
             .optional()
             .describe("connect_x = import/validate your X session in the autoposter's managed browser. " +
-            "Without confirm:true it only EXPLAINS what it will do (so you can tell the user first)."),
+            "Without confirm:true it only EXPLAINS what it will do (so you can tell the user first). " +
+            "detect_x_sources = list the browsers/profiles the X session can be imported from " +
+            "(read-only, no keychain prompt) so the user can pick the right one; returns " +
+            "{sources:[{spec,label,x_session}], recommended}. " +
+            "reseed_queries = (re-)expand an EXISTING project's search topics into ~30 real X search " +
+            "queries and return them. Use for projects configured before query-expansion existed, or " +
+            "to refresh the query bank. Requires name. Returns the resulting query list."),
         confirm: z
             .boolean()
             .optional()
@@ -473,6 +499,20 @@ server.registerTool("setup", {
             .describe("Anything the posts must avoid saying / claiming"),
     },
 }, async (args) => {
+    // ---- List import sources (for the panel dropdown) ---------------------
+    // Read-only browser/profile detection. Never reads the keychain or decrypts
+    // a cookie, so it shows no macOS Safe Storage prompt. Lets the user pick the
+    // exact browser+profile that holds their X session.
+    if (args.action === "detect_x_sources") {
+        const r = await xDetectSources();
+        return jsonContent({
+            action: "detect_x_sources",
+            ok: r.ok,
+            sources: r.sources,
+            recommended: r.recommended,
+            error: r.error,
+        });
+    }
     // ---- Connect X/Twitter: import the user's session into our browser ----
     // Explain-then-confirm: the first call (no confirm) describes exactly what
     // will happen so the agent can get the user's OK; confirm:true runs it.
@@ -519,6 +559,69 @@ server.registerTool("setup", {
                     : "X is not connected yet. " + summarizeXAuth(r),
         });
     }
+    // ---- Reseed search queries: (re-)expand an existing project's topics ----
+    // For projects configured before query-expansion shipped (their topics live
+    // in the DB but the seed-query bank is empty, so the cycle cold-starts on one
+    // crude query), or to refresh the bank on demand. Idempotent: the seeder
+    // dedups against what's already there. Returns the resulting queries so the
+    // agent can show the user exactly what the cycle will fan out over.
+    if (args.action === "reseed_queries") {
+        if (!args.name) {
+            return jsonContent({
+                action: "reseed_queries",
+                error: "name is required — tell me which configured project to reseed.",
+            });
+        }
+        try {
+            const qseed = await runPython("scripts/seed_search_queries.py", ["--project", args.name, "--supply-test", "auto", "--emit-json"], { timeoutMs: 600_000 });
+            const qm = /seeded=(\d+)\s+inserted=(\d+)\s+updated=(\d+)/.exec(qseed.stdout);
+            let queries = [];
+            const jm = qseed.stdout.split("===QUERIES_JSON===")[1];
+            if (jm) {
+                try {
+                    queries = (JSON.parse(jm.trim()).queries ?? []);
+                }
+                catch {
+                    /* leave queries empty; count note below still informs the user */
+                }
+            }
+            if (qseed.code !== 0 && queries.length === 0) {
+                const qtail = (qseed.stderr || qseed.stdout).trim().split("\n").slice(-1)[0] ||
+                    "unknown error";
+                return jsonContent({
+                    action: "reseed_queries",
+                    project: args.name,
+                    ok: false,
+                    error: qtail,
+                    note: `Couldn't expand search queries for '${args.name}' — ${qtail}. ` +
+                        `Common causes: the project has no search topics seeded yet (run setup with name='${args.name}' ` +
+                        `and its search_topics first), or X/Claude wasn't reachable. The cycle still runs off the seeded topics.`,
+                });
+            }
+            return jsonContent({
+                action: "reseed_queries",
+                project: args.name,
+                ok: true,
+                seeded: qm ? Number(qm[1]) : queries.length,
+                inserted: qm ? Number(qm[2]) : undefined,
+                updated: qm ? Number(qm[3]) : undefined,
+                query_count: queries.length,
+                queries,
+                note: `Expanded '${args.name}' into ${queries.length} active search quer` +
+                    `${queries.length === 1 ? "y" : "ies"}. The cycle now fans out over these instead of ` +
+                    `running a single query. Show the user the list so they can confirm they look on-target; ` +
+                    `re-run this anytime to refresh, or run draft_cycle to use them.`,
+            });
+        }
+        catch (e) {
+            return jsonContent({
+                action: "reseed_queries",
+                project: args.name,
+                ok: false,
+                error: e.message,
+            });
+        }
+    }
     // Status / discovery mode: no project name supplied, or explicitly asked.
     if (args.status === true || !args.name) {
         const projects = listManagedProjectStatus();
@@ -568,6 +671,7 @@ server.registerTool("setup", {
         // the user if topics are missing. Only runs once the project is ready
         // (i.e. it actually has search_topics to seed). (2026-06-02)
         let seedNote = "";
+        let searchQueries = [];
         if (result.ready) {
             const seed = await runPython("scripts/seed_search_topics.py", ["--project", result.project], { timeoutMs: 60_000 });
             if (seed.code === 0) {
@@ -590,10 +694,20 @@ server.registerTool("setup", {
             // stays fast when X isn't connected yet. (2026-06-04)
             if (seed.code === 0) {
                 try {
-                    const qseed = await runPython("scripts/seed_search_queries.py", ["--project", result.project, "--supply-test", "auto"], { timeoutMs: 600_000 });
+                    const qseed = await runPython("scripts/seed_search_queries.py", ["--project", result.project, "--supply-test", "auto", "--emit-json"], { timeoutMs: 600_000 });
                     const qm = /seeded=(\d+)\s+inserted=(\d+)\s+updated=(\d+)/.exec(qseed.stdout);
+                    const qjson = qseed.stdout.split("===QUERIES_JSON===")[1];
+                    if (qjson) {
+                        try {
+                            searchQueries = (JSON.parse(qjson.trim()).queries ?? []);
+                        }
+                        catch {
+                            /* leave empty; count note still informs the user */
+                        }
+                    }
                     if (qseed.code === 0 && qm) {
-                        seedNote += ` Expanded them into ${qm[1]} search quer${qm[1] === "1" ? "y" : "ies"} so the cycle can fan out instead of running a single query.`;
+                        const n = searchQueries.length || Number(qm[1]);
+                        seedNote += ` Expanded them into ${n} search quer${n === 1 ? "y" : "ies"} so the cycle can fan out instead of running a single query.`;
                     }
                     else if (qseed.code !== 0) {
                         const qtail = (qseed.stderr || qseed.stdout).trim().split("\n").slice(-1)[0] || "unknown error";
@@ -612,6 +726,7 @@ server.registerTool("setup", {
             ready: result.ready,
             missing_required: result.missing_required,
             topics_seeded: result.ready,
+            search_queries: searchQueries,
             config_path: configPath(),
             note: result.ready
                 ? `Project '${result.project}' is fully set up.${seedNote} Next: connect X so the autoposter can post — ` +
@@ -629,14 +744,15 @@ server.registerTool("setup", {
 // Posting is a SEPARATE step (post_drafts) so the user picks by number in chat.
 // This host doesn't support elicitation, so there is no in-tool form: the model
 // relays the table and asks which to post / edit, then calls post_drafts.
-server.registerTool("draft_cycle", {
+tool("draft_cycle", {
     title: "Draft an X reply cycle",
     description: "Scan X and draft replies on this machine, then return ALL drafts as a numbered table " +
         "for review. This tool POSTS NOTHING. Show the table to the user and ask which numbers " +
         "to post and which to rewrite, then call `post_drafts` with their decision and the " +
         "returned batch_id. The table MUST show, per draft: the thread being replied to " +
         "(thread_text), the draft reply, and the link target (link_url) when present; never " +
-        "drop those columns. Flow: discover -> draft -> review in chat -> post_drafts.",
+        "drop those columns. Flow: discover -> draft -> review in chat -> post_drafts. " +
+        "After returning the table, call the `dashboard` tool so the user sees the updated state.",
     inputSchema: {
         project: z
             .string()
@@ -735,14 +851,15 @@ server.registerTool("draft_cycle", {
 // Second half of the manual loop. The user reviewed the table from draft_cycle
 // and said which numbers to post / edit; this posts exactly those. Editing a
 // draft implies posting it. Indices are 1-based, matching the table.
-server.registerTool("post_drafts", {
+tool("post_drafts", {
     title: "Post chosen drafts",
     description: "Post the drafts the user approved from a draft_cycle batch. Pass the batch_id from " +
         "draft_cycle and the user's decision by NUMBER (1-based, matching the table): `post` is " +
         "the list of draft numbers to post as drafted; `edits` rewrites a draft's text before " +
         "posting it (editing implies posting); `post_all` posts every draft. Only the chosen " +
         "drafts post; anything not listed is left unposted. Call this ONLY after the user has " +
-        "told you which drafts they want.",
+        "told you which drafts they want. After posting, call the `dashboard` tool so the user " +
+        "sees the updated state.",
     inputSchema: {
         batch_id: z.string().describe("The batch_id returned by draft_cycle."),
         post: z
@@ -816,11 +933,12 @@ server.registerTool("post_drafts", {
     });
 });
 // ---- autopilot: one tool, three actions -----------------------------------
-server.registerTool("autopilot", {
+tool("autopilot", {
     title: "X autopilot",
     description: "Control background X/Twitter posting. action=enable loads the launchd job so the " +
         "cycle fires automatically; action=disable unloads it (manual draft_cycle still works); " +
-        "action=status reports whether it is loaded.",
+        "action=status reports whether it is loaded. After enable/disable, call the `dashboard` " +
+        "tool so the user sees the updated autopilot state.",
     inputSchema: {
         action: z.enum(["enable", "disable", "status"]),
     },
@@ -898,10 +1016,11 @@ server.registerTool("autopilot", {
     });
 });
 // ---- get_stats: read-only -------------------------------------------------
-server.registerTool("get_stats", {
+tool("get_stats", {
     title: "Get X/Twitter stats",
     description: "Read-only post + engagement stats for the X/Twitter rail over the last N days. " +
-        "Wraps project_stats_json.py. Use to show the user how their posts are performing.",
+        "Wraps project_stats_json.py. Use to show the user how their posts are performing. " +
+        "After returning the numbers, call the `dashboard` tool so the user sees them rendered.",
     inputSchema: {
         days: z.number().int().min(1).max(90).default(7),
         project: z
@@ -929,7 +1048,7 @@ server.registerTool("get_stats", {
     }
 });
 // ---- version: report installed version + deliver updates on demand ---------
-server.registerTool("version", {
+tool("version", {
     title: "Version & updates",
     description: "Report the installed social-autoposter version and check npm for a newer release. " +
         "action:'status' (default) shows installed vs latest published and whether an update is " +
@@ -996,7 +1115,7 @@ function runtimeSnapshot() {
         progress: progress ?? null,
     };
 }
-server.registerTool("install_runtime", {
+tool("install_runtime", {
     title: "Install the Python runtime",
     description: "One-time setup that provisions the self-contained runtime the autoposter needs: a private " +
         "Python (via uv, not your system Python), its dependencies, and the Chromium browser. Runs in " +
@@ -1016,7 +1135,7 @@ server.registerTool("install_runtime", {
         progress,
     });
 });
-server.registerTool("install_status", {
+tool("install_status", {
     title: "Runtime install status",
     description: "Report whether the self-contained Python/Chromium runtime is installed and, if an install is " +
         "in progress, the per-step progress (uv, Python, venv, dependencies, Chromium). Poll this after " +
@@ -1027,7 +1146,7 @@ server.registerTool("install_status", {
 // The panel renders the full config and lets the user edit it. Writing is
 // guarded: the new content must parse as JSON, and we always drop a timestamped
 // backup next to config.json before overwriting, so a bad paste is recoverable.
-server.registerTool("config", {
+tool("config", {
     title: "View or edit config.json",
     description: "Read or update the autoposter's config.json (the source of truth for every project, the X/" +
         "Reddit/LinkedIn account handles, topics, and exclusions). action:'get' (default) returns the " +
@@ -1137,14 +1256,140 @@ async function buildSnapshot() {
         runtime_provisioning: isProvisioning(),
     };
 }
-registerAppTool(server, "panel", {
-    title: "Social Autoposter panel",
-    description: "Open the Social Autoposter control panel: a visual dashboard showing project setup, X " +
+// ---- dashboard localhost fallback -----------------------------------------
+// When the connected host doesn't support MCP Apps UI (Claude Code / Cowork
+// today), serve the SAME dist/panel.html from a loopback HTTP server. The page
+// detects it's running over HTTP (window.__SAPS_BRIDGE__) and routes every
+// app.callServerTool through POST /tool/<name>, which replays the exact captured
+// handler in TOOL_HANDLERS. No pipeline or front-end logic is duplicated.
+// True if the host advertised it can render our ui:// HTML resource inline.
+function hostRendersAppUi() {
+    try {
+        const caps = (server.server.getClientCapabilities?.() ?? null);
+        const uiCap = getUiCapability(caps);
+        return !!uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE);
+    }
+    catch {
+        return false;
+    }
+}
+let localPanel = null;
+// Read the built panel.html and flip it into HTTP-bridge mode by injecting a
+// flag the front-end reads at boot. Same bytes as the inline ui:// resource,
+// minus the postMessage host (there's none over loopback).
+function panelHtmlForHttp() {
+    const html = fs.readFileSync(path.join(DIST_DIR, "panel.html"), "utf-8");
+    const inject = `<script>window.__SAPS_BRIDGE__=${JSON.stringify("http")};</script>`;
+    if (html.includes("</head>"))
+        return html.replace("</head>", inject + "</head>");
+    return inject + html;
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(Buffer.from(c)));
+        req.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        req.on("error", reject);
+    });
+}
+// Start (or reuse) the loopback HTTP server that serves the dashboard plus a
+// /tool/<name> dispatch endpoint backed by TOOL_HANDLERS. Bound to 127.0.0.1 on
+// an OS-assigned ephemeral port so nothing is exposed off-box.
+function startLocalPanel() {
+    if (localPanel)
+        return Promise.resolve(localPanel.url);
+    return new Promise((resolve, reject) => {
+        const srv = http.createServer(async (req, res) => {
+            try {
+                const url = new URL(req.url || "/", "http://127.0.0.1");
+                if (req.method === "GET" &&
+                    (url.pathname === "/" || url.pathname === "/panel" || url.pathname === "/index.html")) {
+                    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                    res.end(panelHtmlForHttp());
+                    return;
+                }
+                if (req.method === "GET" && url.pathname === "/health") {
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ ok: true }));
+                    return;
+                }
+                if (req.method === "POST" && url.pathname.startsWith("/tool/")) {
+                    const name = decodeURIComponent(url.pathname.slice("/tool/".length));
+                    const handler = TOOL_HANDLERS[name];
+                    if (!handler) {
+                        res.writeHead(404, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ isError: true, content: [{ type: "text", text: `Unknown tool: ${name}` }] }));
+                        return;
+                    }
+                    const raw = await readBody(req);
+                    let args = {};
+                    if (raw.trim()) {
+                        try {
+                            args = JSON.parse(raw);
+                        }
+                        catch {
+                            args = {};
+                        }
+                    }
+                    let result;
+                    try {
+                        result = await handler(args ?? {}, {});
+                    }
+                    catch (e) {
+                        result = { isError: true, content: [{ type: "text", text: String(e?.message || e) }] };
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify(result ?? {}));
+                    return;
+                }
+                res.writeHead(404, { "Content-Type": "text/plain" });
+                res.end("not found");
+            }
+            catch (e) {
+                try {
+                    res.writeHead(500, { "Content-Type": "text/plain" });
+                    res.end(String(e?.message || e));
+                }
+                catch { /* response already sent */ }
+            }
+        });
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            const port = typeof addr === "object" && addr ? addr.port : 0;
+            localPanel = { url: `http://127.0.0.1:${port}/`, server: srv };
+            resolve(localPanel.url);
+        });
+    });
+}
+// Open a URL in the user's default browser, cross-platform. Honors
+// SAPS_PANEL_NO_OPEN (set on headless autopilot boxes or in tests) to skip the
+// actual open while still returning the URL to the caller.
+async function openInBrowser(url) {
+    if (process.env.SAPS_PANEL_NO_OPEN)
+        return;
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        await run(cmd, args, { timeoutMs: 10_000 });
+    }
+    catch (e) {
+        console.error("[social-autoposter-mcp] openInBrowser failed:", e?.message || e);
+    }
+}
+appTool("dashboard", {
+    title: "Social Autoposter dashboard",
+    description: "Render the Social Autoposter dashboard in chat: a visual surface showing project setup, X " +
         "connection, autopilot state, and 7-day stats, with buttons to run a draft cycle, toggle " +
-        "autopilot, connect X, and refresh. Use when the user asks to see the panel, dashboard, " +
-        "status, or controls. Hosts without UI support get the same data as text.",
+        "autopilot, connect X, and refresh. Use when the user asks to see the dashboard, panel, " +
+        "status, or controls. ALSO call this at the end of any state-changing or results-producing " +
+        "action (draft_cycle, post_drafts, autopilot enable/disable, get_stats) so the user sees the " +
+        "updated dashboard. Hosts without UI support get the same data as text.",
     inputSchema: {},
-    outputSchema: { snapshot: z.string() },
+    // fallback_url is set only when the host can't render the ui:// resource and
+    // we open the dashboard via the loopback HTTP server instead. Declared
+    // optional so the SDK's strict output-schema check accepts both shapes.
+    outputSchema: { snapshot: z.string(), fallback_url: z.string().optional() },
     _meta: { ui: { resourceUri: PANEL_URI } },
 }, async () => {
     const snap = await buildSnapshot();
@@ -1153,10 +1398,101 @@ registerAppTool(server, "panel", {
         ` — projects ${snap.projects_ready}/${snap.projects_total} ready, ` +
         `X ${snap.x_connected ? "connected" : "not connected"}, ` +
         `autopilot ${snap.autopilot_on ? "on" : "off"}.`;
-    return {
+    const base = {
         content: [{ type: "text", text: human }],
         structuredContent: { snapshot: JSON.stringify(snap) },
     };
+    // If the host can render MCP Apps UI inline, the _meta.ui.resourceUri above
+    // makes it paint the panel; just return the snapshot. If it CAN'T (Claude
+    // Code / Cowork today), fall back to serving the identical panel.html from a
+    // loopback HTTP server and opening it in the browser, so the user still gets
+    // the visual surface instead of a wall of text.
+    if (hostRendersAppUi())
+        return base;
+    try {
+        const url = await startLocalPanel();
+        await openInBrowser(url);
+        return {
+            content: [{
+                    type: "text",
+                    text: human +
+                        `\n\nThis host can't render the dashboard inline, so I opened it in your browser: ${url}`,
+                }],
+            structuredContent: { snapshot: JSON.stringify(snap), fallback_url: url },
+        };
+    }
+    catch (e) {
+        // Loopback server failed to start; degrade to the text-only snapshot.
+        console.error("[social-autoposter-mcp] local panel fallback failed:", e?.message || e);
+        return base;
+    }
+});
+// ---- show browser to user: live CDP screencast ----------------------------
+// Streams a live view of the autoposter's managed Chrome into the panel. Frames
+// travel back through the normal tool-result channel as a data: URL (which the
+// default panel CSP already permits), so this needs no CSP widening and no
+// direct network access from the iframe. The panel polls action:"frame".
+//
+// This is a PLAIN tool (not appTool): it renders nothing of its own, it only
+// feeds frames into the existing `dashboard` panel via callServerTool. Registering
+// it as an app-tool requires a `_meta.ui.resourceUri`; without one,
+// registerAppTool throws "Cannot read properties of undefined (reading 'ui')" at
+// startup and the whole server fails to connect. So keep it a regular tool.
+tool("show_browser_to_user", {
+    title: "Show browser to user",
+    description: "Show the user a LIVE view of the autoposter's managed Chrome (what the bot " +
+        "is doing in the browser right now). Attaches a CDP screencast to the active " +
+        "browser session and returns the newest frame as a data: image. Actions: " +
+        "'start' begins the screencast, 'frame' returns the latest frame (poll this on " +
+        "a short interval to animate), 'stop' ends it, 'front' raises the real browser " +
+        "window above everything else so the user can interact with it directly. Use when " +
+        "the user asks to see / watch the browser, or to bring the browser to the front.",
+    inputSchema: {
+        action: z.enum(["start", "frame", "stop", "front"]).optional(),
+        port: z.number().int().optional().describe("CDP debugging port to attach to; auto-detected if omitted."),
+    },
+}, async (args) => {
+    const action = args?.action || "frame";
+    if (action === "stop") {
+        screencast.stop();
+        return jsonContent({ ok: true, running: false });
+    }
+    if (action === "front") {
+        const res = await bringBrowserToFront(typeof args?.port === "number" ? args.port : undefined);
+        if (!res.ok) {
+            const message = res.error === "no_browser"
+                ? "No managed Chrome is running right now, so there's nothing to bring to the front. Start a draft cycle or autopilot first."
+                : "Couldn't bring the browser to the front: " + String(res.error);
+            return jsonContent({ ok: false, brought_to_front: false, message });
+        }
+        return jsonContent({ ok: true, brought_to_front: true, port: res.port });
+    }
+    const ensured = await screencast.ensure(typeof args?.port === "number" ? args.port : undefined);
+    if (!ensured.ok) {
+        const message = ensured.error === "no_browser"
+            ? "No managed Chrome is running right now. Start a draft cycle or autopilot so there's a live browser session to show."
+            : ensured.error === "no_websocket"
+                ? "This Node runtime has no WebSocket support (needs Node 21+), so a screencast can't be opened."
+                : "Couldn't attach to the browser: " + String(ensured.error);
+        return jsonContent({ ok: false, running: false, frame: null, message });
+    }
+    // On a fresh start the first frame takes a beat to arrive; wait briefly so the
+    // caller's first poll already has something to paint.
+    let frame = screencast.frame();
+    for (let i = 0; i < 12 && !frame; i++) {
+        await new Promise((r) => setTimeout(r, 120));
+        frame = screencast.frame();
+    }
+    const st = screencast.status();
+    return jsonContent({
+        ok: true,
+        running: st.running,
+        port: st.port,
+        title: st.title,
+        url: st.url,
+        age_ms: st.age_ms,
+        frame: frame ? `data:image/jpeg;base64,${frame}` : null,
+    });
 });
 registerAppResource(server, "Social Autoposter panel", PANEL_URI, { mimeType: RESOURCE_MIME_TYPE }, async () => ({
     contents: [