carouselbot 0.2.0

package/README.md

@@ -0,0 +1,62 @@
+# CarouselBot MCP
+
+Local-first MCP companion for the hosted [CarouselBot editor](https://carousel.bot). It exposes project, slide, text, image, layer, history, rendering, and export controls to any stdio MCP client while the editor remains in the browser.
+
+```bash
+npx carouselbot@latest setup
+```
+
+For non-interactive agent setup, select the current client explicitly:
+
+```bash
+npx carouselbot@latest setup --client=codex --yes
+```
+
+Replace `codex` with `claude`, `hermes`, `opencode`, or `openclaw`. OpenCode prints version-appropriate JSON to merge into its config. Other detected clients are configured through their official CLI.
+
+## Use it immediately without restarting
+
+The same validated tool surface is available through the package CLI when a running agent cannot refresh its native MCP tools:
+
+```bash
+npx -y carouselbot@latest call get_design_guidance
+npx -y carouselbot@latest call list_editors
+npx -y carouselbot@latest call begin_edit_session --json '{"editorId":"EDITOR_ID","purpose":"Build my deck"}'
+npx -y carouselbot@latest call create_project --json '{"editSessionId":"SESSION_ID","name":"My presentation"}'
+```
+
+Every MCP tool name and JSON argument shape works with `call`. The CLI-only `list_tools` helper lists names compactly or returns selected schemas. `render_slide` writes image output to a temporary `previewPath` instead of dumping base64 into the terminal.
+
+Always use `list_editors` to check the browser connection. Do not open CarouselBot or click **Connect AI** through a sandboxed, remote, or agent-controlled browser: that is a different browser session and may not reach the local companion.
+
+Browser reconnection is automatic. Retry transient disconnects; use `restart` only for an explicit protocol mismatch or failed daemon health check. Hermes can refresh native tools with `/reload-mcp` and `/reload-skills`. Claude may need a new session to register a newly added server, but the CLI fallback works immediately.
+
+The companion binds only to `127.0.0.1`. There is no hosted relay: projects remain in browser IndexedDB and local images remain on the user's computer.
+
+Any MCP client can launch it with:
+
+```bash
+npx -y carouselbot@latest serve
+```
+
+Useful commands:
+
+```bash
+npx carouselbot@latest setup --dry-run
+npx carouselbot@latest doctor
+npx carouselbot@latest restart
+```
+
+## Existing Slide Studio installations
+
+`slides-studio-mcp` remains as a compatibility package and delegates to CarouselBot. Existing MCP configurations therefore continue to launch, while running `carouselbot setup` replaces the visible `slide-studio` config key with `carouselbot`.
+
+The new companion accepts both `https://carousel.bot` and the legacy `https://slides-editor.pages.dev` origin during migration. Legacy environment variables beginning with `SLIDE_STUDIO_` and the old daemon state directory remain supported.
+
+## Parallel agents and browser tabs
+
+Call `begin_edit_session` before editing and pass its `editSessionId` to all operations. A session atomically reserves one browser tab and one project, follows that tab instead of global focus, and expires after inactivity. Always call `end_edit_session` when finished.
+
+For parallel editing, reserve a different connected editor for each worker. The daemon rejects conflicting claims with `EDITOR_BUSY` or `PROJECT_BUSY` and records a sanitized local audit through `list_recent_operations`; it never records slide text, prompts, file paths, or image bytes.
+
+Browser writes use revision-checked IndexedDB transactions and cross-tab synchronization. A stale tab cannot replace a newer project snapshot; it reloads the canonical copy and returns `STALE_PROJECT` so the agent can inspect and retry.

package/guidance/design.md

@@ -0,0 +1,49 @@
+# CarouselBot design guidance
+
+Read this before creating or editing slides. Use it as a compact quality bar, then inspect the rendered slide instead of assuming code values look good.
+
+## Defaults that usually look good
+
+- Build for a 9:16 phone canvas and keep one clear idea per slide.
+- Prefer `boxed` text with `backgroundShape: "lines"` for highlighted copy. Treat per-line boxes as the default; use `full` only for a deliberate card or label.
+- `add_text` and `update_text` automatically preserve width and fit height around all wrapped lines with safety padding. Do not render just to discover clipping or call `fit_text_boxes` after ordinary copy edits.
+- Use `fit_text_boxes` with `mode: "both"` only when you intentionally want width to shrink as well. If automatic fitting rejects copy that cannot fit on one slide, shorten it or split it across slides.
+- After creating or changing any full-box text, call `fit_text_boxes`. A full box must hug its rendered content instead of leaving a large empty rectangle.
+- Use plain or outlined text for supporting copy. Use no more than two text treatments on one slide.
+- Choose size by role rather than one universal value: titles `92–124`, subtitles `68–84`, body copy `54–68`, captions `44–52`. These are ranges, not fixed presets; render and adjust within them.
+- Do not shrink dense copy below the body range to make it fit. Shorten it or split it across slides. Aim for roughly 3–7 body lines on a slide.
+- Keep important content inside roughly `x: 0.06..0.86` and `y: 0.08..0.78` when the TikTok overlay matters. The right and bottom edges are occupied by interface controls and captions.
+- Give text boxes generous width while composing. Per-line backgrounds include protected edge padding; if content or size changes, render again and use `fit_text_boxes` when the box itself should hug the content.
+- Use short lines. Two to four lines for a headline is usually stronger than one dense paragraph.
+- Keep strong contrast between copy and the image. Use black boxed backgrounds with white text or white boxed backgrounds with near-black text.
+- Preserve an obvious focal image. Do not cover faces or the main subject unless the composition intentionally calls for it.
+- Align related text layers consistently. Center is a safe default; use left alignment for editorial layouts.
+- Use rotation sparingly. Small intentional angles can add energy; arbitrary angles make carousels feel inconsistent.
+- Reuse a small palette and consistent type scale across the project.
+
+## Working method
+
+1. Inspect the editor and use the returned project, slide, asset, and layer IDs.
+2. Create or update one slide at a time. If that project is already visible, the editor follows its most recently changed slide. Work on another project never takes over the user's current view.
+3. Use `apply_operations` when several related edits can be expressed compactly; the browser still shows each operation live.
+4. Call `render_slide` after a meaningful composition change and look at the returned image.
+5. Correct clipping, collisions, weak contrast, unsafe placement, inconsistent spacing, and visual imbalance before continuing.
+6. Render the complete set at least once before exporting.
+
+## Text-box clipping checklist
+
+- Increase width before shrinking type when a line almost fits.
+- Increase height when multiline text or per-line backgrounds approach the top or bottom edge.
+- Use `fit_text_boxes` after changing full-box copy or font size. Use `mode: "height"` when the chosen width must remain fixed.
+- Keep `x + width` and `y + height` within the canvas unless an off-canvas effect is intentional.
+- With boxed text, keep `backgroundShape: "lines"`; automatic height fitting includes minimum breathing room so rounded pills stay inside the text container.
+- If the result is uncertain, render it. Numeric state is not a visual review.
+
+## Agent behavior
+
+- Do not delete projects, slides, assets, or layers unless the request calls for it.
+- Do not overwrite an existing export unless explicitly requested.
+- Keep tool responses and progress messages concise.
+- Prefer IDs returned by tools over guessed names or array positions.
+- Do not claim a slide looks good until you have inspected a rendered image.
+- Do not call `open_project` merely to edit or render another project. It intentionally changes the user's browser view; use it only when the user asks to see that project.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "carouselbot",
+  "version": "0.2.0",
+  "description": "Local-first MCP companion for the hosted CarouselBot editor",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexgusevski/carouselbot.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://carousel.bot",
+  "bugs": "https://github.com/alexgusevski/carouselbot/issues",
+  "bin": {
+    "carouselbot": "src/cli.mjs"
+  },
+  "exports": {
+    "./cli": "./src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "guidance",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skill/carouselbot/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: carouselbot
+description: Create, edit, visually inspect, and export CarouselBot slides through the local CarouselBot MCP companion.
+---
+
+# CarouselBot
+
+Use the CarouselBot MCP tools for all carousel changes. The hosted browser editor is the live visual surface; local files and rendered images pass only through the local companion.
+
+Before using any browser or making edits, call `list_editors`. A registered editor is the user's real browser tab and is the only browser surface the agent should use.
+
+- If an editor is listed, use the MCP tools against it. Do not open CarouselBot or click **Connect AI** with browser automation.
+- Sandboxed, remote, and agent-controlled browser sessions are separate from the user's local browser and usually cannot reach the local companion. Never use one to test or establish the connection.
+- If no editor is listed, ask the user to open the editor in their normal browser on the same computer, click **Connect AI**, and accept the browser permission. Then retry `list_editors`.
+- A loaded MCP server and a connected browser editor are different states. Determine browser connectivity only from `list_editors`, not from a sandbox browser or the agent's tool catalog.
+
+Browser reconnection is automatic. After `EDITOR_DISCONNECTED`, `EDITOR_RELOADED`, a dropped browser request, or an empty `list_editors` result that follows a working connection, wait briefly and retry `list_editors` several times. Do not restart the companion for a transient browser disconnect: restarting invalidates every browser session and makes recovery slower. If the editor does not return, ask the user to keep or reload the real editor tab; preserve completed project work and begin a new edit session after it reconnects.
+
+Run `npx -y carouselbot@latest restart` only when the MCP explicitly reports an outdated companion protocol or `doctor` reports that the daemon itself is unhealthy. After a necessary restart, ask the user to reload their real editor tab and retry `list_editors`.
+
+If the native MCP tools are not registered in the current session, do not stop or ask for a restart. Use the same validated tools through the local CLI fallback:
+
+```bash
+npx -y carouselbot@latest call get_design_guidance
+npx -y carouselbot@latest call list_editors
+npx -y carouselbot@latest call list_tools --json '{"names":["add_slide","add_text"]}'
+npx -y carouselbot@latest call create_project --json '{"name":"My presentation"}'
+```
+
+Every tool accepts the same JSON arguments as MCP. Use `list_tools` without arguments for compact discovery or pass `{"names":[...]}` to retrieve selected schemas. Prefer `apply_operations` for batches. `render_slide` writes its returned image to a temporary local `previewPath`; inspect that file and remove the temporary directory after the review. Hermes can load the native tools in place with `/reload-mcp` and refresh this skill with `/reload-skills`.
+
+Before the first mutation in a task, call `get_design_guidance`. The server intentionally rejects mutations until this guidance has been read.
+
+Before editing, reserve a target with `begin_edit_session`. Pass its `editSessionId` to every mutating tool, relevant reads, notifications, and `apply_operations`. Release it with `end_edit_session` as soon as the work finishes or fails. Reservations expire after inactivity, but explicit release is the normal cleanup path.
+
+For parallel work, the parent agent owns orchestration:
+
+1. Call `list_editors` and `list_edit_sessions` before spawning editing workers.
+2. Reserve one distinct editor per editing worker with `begin_edit_session`, and assign one project per session. Never launch more editing workers than available unassigned editors. Research-only workers do not need a session.
+3. Give each worker its exact `editorId`, `editSessionId`, and `projectId` (once known). A worker must never select or use another worker's editor.
+4. If a worker creates a project, the daemon binds that new project to its session automatically. Report the returned `projectId` to the parent.
+5. Treat `EDITOR_BUSY`, `PROJECT_BUSY`, and `SESSION_PROJECT_MISMATCH` as coordination signals. Do not retry against a different target silently. Re-plan, wait, or use another unassigned editor.
+6. End every worker session in cleanup, including after errors. Use `list_recent_operations` to investigate routing, conflicts, or failed edits without exposing prompts, text, paths, or image bytes.
+
+With only one agent and one editor, the server can create an implicit session for compatibility. Explicit sessions are still preferred because they make routing deterministic. Never rely on which tab is focused once multiple editors exist.
+
+Inspect the assigned editor before editing and keep the returned IDs and revision. Work on the assigned project and slide. Pass `expectedRevision` for sensitive mutations. If `STALE_PROJECT` is returned, the browser has reloaded the canonical IndexedDB copy; inspect again and retry with current IDs. Prefer `apply_operations` for compact related changes while preserving logical order.
+
+Use readable role-based type ranges: title `92–124`, subtitle `68–84`, body `54–68`, caption `44–52`. Do not solve dense copy by dropping below the body range; shorten it or split it across slides. `add_text` and `update_text` automatically preserve width and fit height around every wrapped line with safe padding. For highlighted text, prefer `style: "boxed"` with `backgroundShape: "lines"`. Use `backgroundShape: "full"` only for a deliberate card. Call `fit_text_boxes` with `mode: "both"` only when you intentionally want the width to shrink too.
+
+After each meaningful composition or after a short batch, call `render_slide` and inspect the returned image. Fix clipping, spacing, contrast, unsafe overlay placement, and weak hierarchy before claiming the slide is finished. Use `export_slide` or `export_project` only when local files are requested; do not overwrite existing files unless authorized.
+
+Edits follow the latest changed slide only when their project is already visible. Creating or editing another project must not take over the user's current browser view. `open_project` and `set_view` intentionally navigate, so call them only when the user asks to see that project. Other tabs synchronize project cards and project state through local browser storage. Use `show_notification` only for short, useful status messages.

package/src/agent-identity.mjs

@@ -0,0 +1,49 @@
+const KNOWN_AGENTS = [
+  { label: "Hermes", matches: ["hermes"] },
+  { label: "Claude", matches: ["claude", "anthropic"] },
+  { label: "Codex", matches: ["codex", "openai"] },
+  { label: "OpenCode", matches: ["opencode"] },
+  { label: "OpenClaw", matches: ["openclaw"] },
+];
+
+const GENERIC_CLIENT_NAMES = new Set([
+  "ai agent",
+  "agent",
+  "client",
+  "mcp",
+  "mcp agent",
+  "mcp client",
+  "carouselbot cli fallback",
+  "slide studio cli fallback",
+]);
+
+export function canonicalAgentName(value) {
+  const name = String(value || "").trim();
+  const normalized = name.toLowerCase();
+  return KNOWN_AGENTS.find(({ matches }) => matches.some((match) => normalized.includes(match)))?.label || name || null;
+}
+
+export function isGenericAgentName(value) {
+  return GENERIC_CLIENT_NAMES.has(String(value || "").trim().toLowerCase());
+}
+
+export function detectHostAgent(explicitName = null, environment = process.env, runtime = process) {
+  const configured = canonicalAgentName(explicitName || environment.CAROUSELBOT_AGENT || environment.SLIDE_STUDIO_AGENT);
+  if (configured) return configured;
+  const environmentKeys = Object.keys(environment).filter((key) => environment[key]).join(" ");
+  const evidence = [
+    runtime.execPath,
+    ...(runtime.argv || []),
+    environment.PATH,
+    environment.TERM_PROGRAM,
+    environment.npm_execpath,
+    environmentKeys,
+  ].filter(Boolean).join(" ").toLowerCase();
+  return KNOWN_AGENTS.find(({ matches }) => matches.some((match) => evidence.includes(match)))?.label || "MCP agent";
+}
+
+export function preferHostAgent(reportedName, hostName) {
+  const reported = canonicalAgentName(reportedName);
+  const host = canonicalAgentName(hostName) || "MCP agent";
+  return !reported || isGenericAgentName(reported) ? host : reported;
+}

package/src/call.mjs

@@ -0,0 +1,124 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const CLI_PATH = fileURLToPath(new URL("cli.mjs", import.meta.url));
+
+async function stdinText() {
+  if (process.stdin.isTTY) return "";
+  let value = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) value += chunk;
+  return value.trim();
+}
+
+async function parseArguments(arguments_) {
+  const [toolName, ...rest] = arguments_;
+  if (!toolName) throw new Error("Usage: carouselbot call <tool> [--json '{\"key\":\"value\"}']");
+  const inline = rest.find((value) => value.startsWith("--json="));
+  const flagIndex = rest.indexOf("--json");
+  const raw = inline?.slice("--json=".length)
+    || (flagIndex >= 0 ? rest[flagIndex + 1] : rest.find((value) => !value.startsWith("--")))
+    || (rest.includes("--stdin") ? await stdinText() : "")
+    || "{}";
+  let args;
+  try { args = JSON.parse(raw); }
+  catch { throw new Error("--json must be a valid JSON object."); }
+  if (!args || Array.isArray(args) || typeof args !== "object") throw new Error("--json must be a JSON object.");
+  return { toolName, args };
+}
+
+async function printableResult(toolName, result) {
+  const error = result.isError && result.content?.find((item) => item.type === "text")?.text;
+  if (error) throw new Error(error);
+  if (toolName === "get_design_guidance") return { guidance: result.content?.find((item) => item.type === "text")?.text || "" };
+  const image = result.content?.find((item) => item.type === "image" && item.data);
+  if (!image) return result.structuredContent ?? { content: result.content || [] };
+  const extension = image.mimeType === "image/jpeg" ? "jpg" : "png";
+  const directory = await mkdtemp(join(tmpdir(), "carouselbot-preview-"));
+  const previewPath = join(directory, `slide.${extension}`);
+  await writeFile(previewPath, Buffer.from(image.data, "base64"));
+  return { ...(result.structuredContent || {}), previewPath, temporary: true };
+}
+
+function createRpc(child) {
+  let input = "";
+  let id = 0;
+  const pending = new Map();
+  child.stdout.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    input += chunk;
+    let newline;
+    while ((newline = input.indexOf("\n")) >= 0) {
+      const line = input.slice(0, newline).trim();
+      input = input.slice(newline + 1);
+      if (!line) continue;
+      const message = JSON.parse(line);
+      const waiter = pending.get(message.id);
+      if (!waiter) continue;
+      pending.delete(message.id);
+      clearTimeout(waiter.timer);
+      message.error ? waiter.reject(new Error(message.error.message)) : waiter.resolve(message.result);
+    }
+  });
+  child.once("exit", (code) => {
+    for (const waiter of pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(`Local MCP process exited before replying${code == null ? "" : ` (${code})`}.`));
+    }
+    pending.clear();
+  });
+  return {
+    notify(method, params = {}) { child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`); },
+    request(method, params = {}) {
+      const requestId = ++id;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(requestId); reject(new Error(`Timed out waiting for ${method}.`)); }, 120_000);
+        pending.set(requestId, { resolve, reject, timer });
+        child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id: requestId, method, params })}\n`);
+      });
+    },
+  };
+}
+
+async function stopChild(child) {
+  if (child.exitCode != null) return;
+  child.stdin.end();
+  const exited = new Promise((resolve) => child.once("exit", resolve));
+  const timeout = new Promise((resolve) => { const timer = setTimeout(resolve, 2000); timer.unref(); });
+  await Promise.race([exited, timeout]);
+  if (child.exitCode == null) child.kill("SIGTERM");
+}
+
+export async function runCall(arguments_) {
+  const { toolName, args } = await parseArguments(arguments_);
+  const child = spawn(process.execPath, [CLI_PATH, "serve"], { cwd: process.cwd(), env: process.env, stdio: ["pipe", "pipe", "pipe"] });
+  let errors = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => { errors = `${errors}${chunk}`.slice(-4000); });
+  const rpc = createRpc(child);
+  try {
+    await rpc.request("initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "CarouselBot CLI fallback", version: "1" } });
+    rpc.notify("notifications/initialized");
+    if (toolName === "list_tools") {
+      const listed = await rpc.request("tools/list");
+      const requested = Array.isArray(args.names) ? new Set(args.names.map(String)) : null;
+      const tools = listed.tools.filter((tool) => !requested || requested.has(tool.name)).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        ...(requested ? { inputSchema: tool.inputSchema } : {}),
+      }));
+      process.stdout.write(`${JSON.stringify({ tools }, null, 2)}\n`);
+      return;
+    }
+    if (toolName !== "get_design_guidance") await rpc.request("tools/call", { name: "get_design_guidance", arguments: {} });
+    const result = await rpc.request("tools/call", { name: toolName, arguments: args });
+    process.stdout.write(`${JSON.stringify(await printableResult(toolName, result), null, 2)}\n`);
+  } catch (error) {
+    throw new Error(`${error.message}${errors ? `\n${errors.trim()}` : ""}`);
+  } finally {
+    await stopChild(child);
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { companionDoctor, companionRestart } from "./companion.mjs";
+import { EDITOR_URL, PACKAGE_NAME, PACKAGE_VERSION } from "./config.mjs";
+import { runSetup } from "./setup.mjs";
+import { serveMcp } from "./stdio-server.mjs";
+
+const [command = "serve", ...arguments_] = process.argv.slice(2);
+
+async function main() {
+  if (command === "serve") {
+    const agentName = arguments_.find((value) => value.startsWith("--agent="))?.slice("--agent=".length) || null;
+    await serveMcp({ agentName });
+    return;
+  }
+  if (command === "setup") {
+    await runSetup(arguments_);
+    return;
+  }
+  if (command === "call") {
+    const { runCall } = await import("./call.mjs");
+    await runCall(arguments_);
+    return;
+  }
+  if (command === "doctor") {
+    const health = await companionDoctor();
+    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, packageVersion: PACKAGE_VERSION, editor: EDITOR_URL, daemon: health }, null, 2)}\n`);
+    return;
+  }
+  if (command === "restart") {
+    const health = await companionRestart();
+    process.stdout.write(`${JSON.stringify({ package: PACKAGE_NAME, packageVersion: PACKAGE_VERSION, daemon: health }, null, 2)}\n`);
+    return;
+  }
+  if (command === "version" || command === "--version" || command === "-v") {
+    process.stdout.write(`${PACKAGE_VERSION}\n`);
+    return;
+  }
+  if (command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(`CarouselBot MCP ${PACKAGE_VERSION}\n\nUsage:\n  carouselbot serve [--agent=claude|codex|hermes|opencode|openclaw]\n  carouselbot setup [--client=claude,codex,hermes,opencode,openclaw] [--yes] [--dry-run]\n  carouselbot call <tool> [--json '{"key":"value"}'] [--stdin]\n  carouselbot doctor\n  carouselbot restart\n  carouselbot version\n`);
+    return;
+  }
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error.message}\n`);
+  process.exit(1);
+});

package/src/companion.mjs

@@ -0,0 +1,140 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { BRIDGE_URL, DAEMON_STATE_PATH, PACKAGE_VERSION, PROTOCOL_VERSION } from "./config.mjs";
+import { preferHostAgent } from "./agent-identity.mjs";
+
+const DAEMON_ENTRY = fileURLToPath(new URL("daemon.mjs", import.meta.url));
+
+const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function readState() {
+  try { return JSON.parse(await readFile(DAEMON_STATE_PATH, "utf8")); }
+  catch { return null; }
+}
+
+async function daemonRequest(state, path, init = {}) {
+  const response = await fetch(`${BRIDGE_URL}${path}`, {
+    ...init,
+    headers: { "Authorization": `Bearer ${state.secret}`, "Content-Type": "application/json", ...(init.headers || {}) },
+  });
+  const value = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const error = new Error(value.error || `Local companion returned ${response.status}.`);
+    error.status = response.status;
+    throw error;
+  }
+  return value;
+}
+
+async function healthyState() {
+  const state = await readState();
+  if (!state?.secret || state.port == null) return null;
+  try {
+    const result = await daemonRequest(state, "/internal/health");
+    if (result.protocolVersion !== PROTOCOL_VERSION) {
+      const error = new Error(`Local companion ${result.version || "unknown"} uses protocol ${result.protocolVersion}; ${PACKAGE_VERSION} requires protocol ${PROTOCOL_VERSION}. Run \`npx -y carouselbot@latest restart\`, then reload the editor.`);
+      error.code = "EPROTOCOL";
+      throw error;
+    }
+    return state;
+  } catch (error) {
+    if (error.code === "EPROTOCOL") throw error;
+    return null;
+  }
+}
+
+async function ensureDaemon() {
+  const existing = await healthyState();
+  if (existing) return existing;
+  const child = spawn(process.execPath, [DAEMON_ENTRY], {
+    detached: true,
+    stdio: "ignore",
+    env: process.env,
+  });
+  child.unref();
+  const deadline = Date.now() + 8000;
+  while (Date.now() < deadline) {
+    await wait(100);
+    const state = await healthyState();
+    if (state) return state;
+  }
+  throw new Error("Could not start the local CarouselBot companion. Run `npx carouselbot doctor` for details.");
+}
+
+export async function createCompanion(initialName = "MCP agent", initialVersion = null) {
+  let state = await ensureDaemon();
+  const clientId = randomUUID();
+  let clientName = initialName;
+  let clientVersion = initialVersion;
+  let closed = false;
+
+  const rawPost = (path, body) => daemonRequest(state, path, { method: "POST", body: JSON.stringify(body) });
+  const register = () => rawPost("/internal/client/connect", { clientId, name: clientName, version: clientVersion });
+  const post = async (path, body) => {
+    try {
+      return await rawPost(path, body);
+    } catch (error) {
+      if (closed || (error.status && error.status !== 401)) throw error;
+      state = await ensureDaemon();
+      await register();
+      return rawPost(path, body);
+    }
+  };
+  await register();
+  const heartbeat = setInterval(() => {
+    if (!closed) void post("/internal/client/heartbeat", { clientId }).catch(() => {});
+  }, 15_000);
+  heartbeat.unref();
+
+  return {
+    clientId,
+    get daemon() { return { pid: state.pid, url: BRIDGE_URL, version: state.version, packageVersion: PACKAGE_VERSION }; },
+    async identify(name, version) {
+      clientName = preferHostAgent(name, clientName);
+      clientVersion = version || clientVersion;
+      await register();
+    },
+    async call(action, body = {}) {
+      const response = await post("/internal/call", { clientId, action, ...body });
+      return response.result;
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      clearInterval(heartbeat);
+      await rawPost("/internal/client/disconnect", { clientId }).catch(() => {});
+    },
+  };
+}
+
+export async function companionDoctor() {
+  const state = await ensureDaemon();
+  const health = await daemonRequest(state, "/internal/health");
+  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH };
+}
+
+export async function companionRestart() {
+  const previous = await readState();
+  if (previous?.secret && Number.isInteger(previous.pid) && previous.pid > 0) {
+    const health = await daemonRequest(previous, "/internal/health").catch(() => null);
+    if (health?.pid === previous.pid) {
+      await daemonRequest(previous, "/internal/shutdown", { method: "POST", body: "{}" }).catch(() => {
+        try { process.kill(previous.pid, "SIGTERM"); } catch { /* It already stopped. */ }
+      });
+      const deadline = Date.now() + 8000;
+      while (Date.now() < deadline) {
+        try {
+          process.kill(previous.pid, 0);
+          await wait(100);
+        } catch {
+          break;
+        }
+      }
+    }
+  }
+  const state = await ensureDaemon();
+  const health = await daemonRequest(state, "/internal/health");
+  return { ...health, url: BRIDGE_URL, stateFile: DAEMON_STATE_PATH, previousPid: previous?.pid || null };
+}

package/src/config.mjs

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+export const PACKAGE_JSON = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+export const PACKAGE_NAME = PACKAGE_JSON.name;
+export const PACKAGE_VERSION = PACKAGE_JSON.version;
+export const PROTOCOL_VERSION = 3;
+export const BRIDGE_HOST = "127.0.0.1";
+export const BRIDGE_PORT = Number(process.env.CAROUSELBOT_BRIDGE_PORT || process.env.SLIDE_STUDIO_BRIDGE_PORT) || 43117;
+export const BRIDGE_URL = `http://${BRIDGE_HOST}:${BRIDGE_PORT}`;
+export const EDITOR_URL = "https://carousel.bot";
+export const LEGACY_EDITOR_URL = "https://slides-editor.pages.dev";
+export const ALLOWED_ORIGINS = new Set((process.env.CAROUSELBOT_ALLOWED_ORIGINS || process.env.SLIDE_STUDIO_ALLOWED_ORIGINS || [
+  EDITOR_URL,
+  LEGACY_EDITOR_URL,
+  "http://127.0.0.1:4173",
+  "http://localhost:4173",
+].join(",")).split(",").map((value) => value.trim()).filter(Boolean));
+export const GUIDANCE_PATH = join(PACKAGE_ROOT, "guidance", "design.md");
+
+function defaultStateDirectory() {
+  if (process.env.CAROUSELBOT_STATE_DIR || process.env.SLIDE_STUDIO_STATE_DIR) return process.env.CAROUSELBOT_STATE_DIR || process.env.SLIDE_STUDIO_STATE_DIR;
+  const legacy = platform() === "win32"
+    ? join(process.env.LOCALAPPDATA || homedir(), "SlideStudioMCP")
+    : platform() === "darwin"
+      ? join(homedir(), "Library", "Caches", "SlideStudioMCP")
+      : join(process.env.XDG_RUNTIME_DIR || join(homedir(), ".cache"), "slides-studio-mcp");
+  if (existsSync(legacy)) return legacy;
+  if (platform() === "win32") return join(process.env.LOCALAPPDATA || homedir(), "CarouselBot");
+  if (platform() === "darwin") return join(homedir(), "Library", "Caches", "CarouselBot");
+  return join(process.env.XDG_RUNTIME_DIR || join(homedir(), ".cache"), "carouselbot");
+}
+
+export const STATE_DIRECTORY = defaultStateDirectory();
+export const DAEMON_STATE_PATH = join(STATE_DIRECTORY, `daemon-${BRIDGE_PORT}.json`);
+export const DAEMON_LOCK_PATH = join(STATE_DIRECTORY, `daemon-${BRIDGE_PORT}.lock`);
+export const AUDIT_LOG_PATH = join(STATE_DIRECTORY, `operations-${BRIDGE_PORT}.jsonl`);