@loupekit/mcp 0.10.25 → 0.10.26-next.73

package/dist/index.js

@@ -6,6 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { pathToFileURL } from "url";
 import { realpathSync } from "fs";
 import { argv } from "process";
+import { existsSync as existsSync4 } from "fs";
 import { z } from "zod";
 import { Buffer as Buffer2 } from "buffer";
 
@@ -224,6 +225,404 @@ var PresenceRegistry = class {
   }
 };
 
+// src/bridge/event-store.ts
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from "fs";
+import { dirname } from "path";
+var EVENT_CAP = 1e3;
+var PAYLOAD_CHAR_CAP = 2e3;
+var FLUSH_DEBOUNCE_MS = 250;
+function truncate(value, cap = PAYLOAD_CHAR_CAP) {
+  if (value.length <= cap) return value;
+  return `${value.slice(0, cap)}\u2026 [truncated ${value.length - cap} chars]`;
+}
+function shrinkPayload(value, depth = 0, cap = PAYLOAD_CHAR_CAP) {
+  if (value === null || value === void 0) return value;
+  if (typeof value === "string") return truncate(value, cap);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (depth >= 4) return "[deeper]";
+  if (Array.isArray(value)) {
+    const head = value.slice(0, 20).map((v) => shrinkPayload(v, depth + 1, cap));
+    return value.length > 20 ? [...head, `\u2026 ${value.length - 20} more`] : head;
+  }
+  if (typeof value === "object") {
+    const out = {};
+    const entries = Object.entries(value).slice(0, 30);
+    for (const [k, v] of entries) out[k] = shrinkPayload(v, depth + 1, cap);
+    return out;
+  }
+  return String(value);
+}
+function newId() {
+  return `ev_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+var EventStore = class {
+  events = [];
+  cap;
+  file;
+  writeTimer;
+  dirty = false;
+  constructor(opts = {}) {
+    this.cap = opts.cap && opts.cap > 0 ? opts.cap : EVENT_CAP;
+    this.file = opts.file;
+    if (this.file) this.load();
+  }
+  /** Read what is on disk, ignoring anything unusable. A store that will not load must
+   *  not stop the bridge — the events are a convenience, not the product. */
+  load() {
+    if (!this.file || !existsSync(this.file)) return;
+    try {
+      const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+      if (!Array.isArray(parsed)) return;
+      this.events = parsed.filter((e) => e && typeof e.id === "string" && typeof e.type === "string").slice(-this.cap);
+    } catch {
+      this.events = [];
+    }
+  }
+  add(input) {
+    const event = {
+      id: newId(),
+      at: input.at ?? (/* @__PURE__ */ new Date()).toISOString(),
+      type: input.type,
+      sessionId: input.sessionId,
+      tool: input.tool ? truncate(input.tool, 200) : void 0,
+      summary: input.summary ? truncate(input.summary, 500) : void 0,
+      files: input.files?.length ? [...new Set(input.files)].slice(0, 50) : void 0,
+      payload: input.payload ? shrinkPayload(input.payload) : void 0
+    };
+    this.events.push(event);
+    if (this.events.length > this.cap) this.events = this.events.slice(-this.cap);
+    this.scheduleFlush();
+    return event;
+  }
+  /** Newest last. `limit` takes the most recent N, oldest of those first. */
+  recent(limit = 50) {
+    if (limit <= 0) return [];
+    return this.events.slice(-limit);
+  }
+  /** Newest first, for a feed. */
+  latest(limit = 50) {
+    return this.recent(limit).reverse();
+  }
+  size() {
+    return this.events.length;
+  }
+  clear() {
+    this.events = [];
+    this.scheduleFlush();
+  }
+  scheduleFlush() {
+    if (!this.file) return;
+    this.dirty = true;
+    if (this.writeTimer) return;
+    this.writeTimer = setTimeout(() => {
+      this.writeTimer = void 0;
+      this.flush();
+    }, FLUSH_DEBOUNCE_MS);
+    if (typeof this.writeTimer.unref === "function") this.writeTimer.unref();
+  }
+  /** Write now. Atomic: a temp file renamed into place, so a crash cannot leave a
+   *  half-written store that then fails to parse on the next start. */
+  flush() {
+    if (!this.file || !this.dirty) return;
+    if (this.writeTimer) {
+      clearTimeout(this.writeTimer);
+      this.writeTimer = void 0;
+    }
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = `${this.file}.tmp`;
+      writeFileSync(tmp, JSON.stringify(this.events));
+      renameSync(tmp, this.file);
+      this.dirty = false;
+    } catch {
+    }
+  }
+};
+
+// src/bridge/companion-queue.ts
+var CompanionQueue = class {
+  queue = [];
+  /** Taken but not yet acknowledged. Kept so a failure can put them back. */
+  inFlight = [];
+  replies = [];
+  replyCap;
+  now;
+  // Explicit fields, not constructor parameter properties — Node's strip-only TypeScript
+  // mode rejects those and this file runs unbundled from source.
+  constructor(replyCap = 100, now = Date.now) {
+    this.replyCap = replyCap;
+    this.now = now;
+  }
+  push(message) {
+    const full = {
+      ...message,
+      id: message.id ?? `cm_${this.now().toString(36)}${Math.random().toString(36).slice(2, 7)}`,
+      at: message.at ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.queue.push(full);
+    return full;
+  }
+  /** What is waiting, without taking it. Safe to call repeatedly. */
+  peek() {
+    return [...this.queue];
+  }
+  size() {
+    return this.queue.length;
+  }
+  /** In-flight count, for the panel to show "delivering…". */
+  pending() {
+    return this.inFlight.length;
+  }
+  /**
+   * Take everything waiting, marking it in flight.
+   *
+   * Deliberately *not* a plain drain: the caller must `ack()` for the messages to be
+   * gone. If the tool call they were attached to throws, the queue still holds them.
+   */
+  take() {
+    const taken = this.queue;
+    this.queue = [];
+    this.inFlight = [...this.inFlight, ...taken];
+    return taken;
+  }
+  /** Confirm delivery. Only what was actually handed over is dropped. */
+  ack(ids) {
+    if (!ids) {
+      this.inFlight = [];
+      return;
+    }
+    const done = new Set(ids);
+    this.inFlight = this.inFlight.filter((m) => !done.has(m.id));
+  }
+  /**
+   * Put the in-flight messages back at the front, in their original order.
+   *
+   * Used when a delivery did not happen — the tool failed, or the transport went away.
+   * Front, not back, because they were sent first and the conversation should read in
+   * the order it was written.
+   */
+  requeue() {
+    const restored = this.inFlight;
+    this.inFlight = [];
+    this.queue = [...restored, ...this.queue];
+    return restored;
+  }
+  /** All messages, queued and in flight — what the panel shows. */
+  list() {
+    return [...this.inFlight, ...this.queue];
+  }
+  addReply(reply) {
+    const full = {
+      ...reply,
+      id: reply.id ?? `cr_${this.now().toString(36)}${Math.random().toString(36).slice(2, 7)}`,
+      at: reply.at ?? (/* @__PURE__ */ new Date()).toISOString()
+    };
+    this.replies.push(full);
+    if (this.replies.length > this.replyCap) this.replies = this.replies.slice(-this.replyCap);
+    return full;
+  }
+  listReplies(limit = 50) {
+    return this.replies.slice(-limit);
+  }
+  clear() {
+    this.queue = [];
+    this.inFlight = [];
+  }
+};
+function companionPreamble(messages) {
+  const lines = messages.map((m) => {
+    const where = m.contexts?.length ? ` (re: ${m.contexts.map((c) => c.label ?? c.url ?? c.id ?? c.kind).join(", ")})` : "";
+    const atts = m.attachments?.length ? ` [${m.attachments.length} attachment(s)]` : "";
+    return `- ${m.author?.name ? `${m.author.name}: ` : ""}${m.body}${where}${atts}`;
+  });
+  return [
+    `\u26A0\uFE0F The person watching sent you ${messages.length} message${messages.length === 1 ? "" : "s"} while you were working. Read and act on this before continuing:`,
+    ...lines,
+    "",
+    "Answer with reply_to_companion so it reaches them, then carry on.",
+    ""
+  ].join("\n");
+}
+function prependToResult(result, messages) {
+  if (!messages.length) return result;
+  const content = Array.isArray(result?.content) ? result.content : [];
+  return { ...result, content: [{ type: "text", text: companionPreamble(messages) }, ...content] };
+}
+
+// src/bridge/session-manager.ts
+var SESSION_IDLE_MS = 10 * 60 * 1e3;
+var FILE_KEYS = ["file", "file_path", "path", "filepath", "notebook_path", "filename", "target_file"];
+function extractFiles(payload, depth = 0) {
+  if (depth >= 5 || !payload || typeof payload !== "object") return [];
+  const out = [];
+  const consider = (key, value) => {
+    if (typeof value !== "string" || !value) return;
+    const keyed = FILE_KEYS.includes(key.toLowerCase());
+    const pathish = /^[\w./~-]+\/[\w./~-]*\.[A-Za-z0-9]+$/.test(value) || /^[\w.-]+\.[A-Za-z0-9]{1,8}$/.test(value);
+    if (keyed && value.length < 500) out.push(value);
+    else if (pathish && !keyed && /[/.]/.test(value) && !value.includes(" ")) out.push(value);
+  };
+  if (Array.isArray(payload)) {
+    for (const item of payload) out.push(...extractFiles(item, depth + 1));
+    return out;
+  }
+  for (const [k, v] of Object.entries(payload)) {
+    consider(k, v);
+    if (v && typeof v === "object") out.push(...extractFiles(v, depth + 1));
+  }
+  return out;
+}
+function sessionsFromEvents(events2, now = Date.now()) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const e of events2) {
+    const id = e.sessionId || "unattributed";
+    const list = byId.get(id) ?? [];
+    list.push(e);
+    byId.set(id, list);
+  }
+  const sessions = [];
+  for (const [id, list] of byId) {
+    const sorted = [...list].sort((a, b) => a.at.localeCompare(b.at));
+    const counts = /* @__PURE__ */ new Map();
+    const files = [];
+    let prompts = 0;
+    let tools = 0;
+    let endedAt;
+    for (const e of sorted) {
+      if (e.type === "prompt_submit") prompts++;
+      if (e.type === "tool_use") {
+        tools++;
+        if (e.tool) counts.set(e.tool, (counts.get(e.tool) ?? 0) + 1);
+      }
+      if (e.type === "session_end") endedAt = e.at;
+      for (const f of e.files ?? []) if (!files.includes(f)) files.push(f);
+      for (const f of extractFiles(e.payload)) if (!files.includes(f)) files.push(f);
+    }
+    const lastEventAt = sorted[sorted.length - 1].at;
+    const quiet = now - Date.parse(lastEventAt) > SESSION_IDLE_MS;
+    sessions.push({
+      id,
+      startedAt: sorted[0].at,
+      endedAt,
+      // An explicit end wins; otherwise a session that has gone quiet is not "live"
+      // just because no hook said goodbye — a killed terminal never does.
+      active: !endedAt && !quiet,
+      prompts,
+      tools,
+      toolCounts: [...counts.entries()].map(([tool, count]) => ({ tool, count })).sort((a, b) => b.count - a.count || a.tool.localeCompare(b.tool)),
+      files,
+      eventCount: sorted.length,
+      lastEventAt
+    });
+  }
+  return sessions.sort((a, b) => b.startedAt.localeCompare(a.startedAt));
+}
+function sessionSummaryText(s) {
+  const parts = [
+    `${s.active ? "\u25CF live" : "\u25CB ended"} ${s.id}`,
+    `${s.prompts} prompt${s.prompts === 1 ? "" : "s"}`,
+    `${s.tools} tool call${s.tools === 1 ? "" : "s"}`,
+    `${s.files.length} file${s.files.length === 1 ? "" : "s"} touched`
+  ];
+  const top = s.toolCounts.slice(0, 3).map((t) => `${t.tool} \xD7${t.count}`).join(", ");
+  return `${parts.join(" \xB7 ")}${top ? `
+   most used: ${top}` : ""}`;
+}
+
+// src/hooks/hook-installer.ts
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2 } from "path";
+var HOOK_MARKER = "loupe-hook";
+var HOOK_EVENTS = [
+  "SessionStart",
+  "UserPromptSubmit",
+  "PreToolUse",
+  "PostToolUse",
+  "SubagentStop",
+  "Notification",
+  "SessionEnd"
+];
+function hookCommand(scriptPath, event) {
+  return `node "${scriptPath}" ${event}`;
+}
+function installHooks(settings, scriptPath) {
+  const base = settings && typeof settings === "object" && !Array.isArray(settings) ? { ...settings } : {};
+  const hooks = base.hooks && typeof base.hooks === "object" && !Array.isArray(base.hooks) ? { ...base.hooks } : {};
+  const added = [];
+  const repaired = [];
+  const preserved = [];
+  for (const event of HOOK_EVENTS) {
+    const existing = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    const want = hookCommand(scriptPath, event);
+    let found = false;
+    let alreadyRight = false;
+    const next = existing.map((entry) => {
+      if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks)) return entry;
+      const commands = entry.hooks.map((h) => {
+        if (!h || typeof h !== "object" || typeof h.command !== "string") return h;
+        if (!h.command.includes(HOOK_MARKER)) return h;
+        if (!found) {
+          found = true;
+          if (h.command === want) alreadyRight = true;
+          else return { ...h, command: want };
+        }
+        return h;
+      });
+      return { ...entry, hooks: commands };
+    });
+    if (found && alreadyRight) {
+      preserved.push(event);
+      hooks[event] = existing;
+      continue;
+    }
+    if (found) {
+      repaired.push(event);
+      hooks[event] = next;
+      continue;
+    }
+    added.push(event);
+    hooks[event] = [...existing, { hooks: [{ type: "command", command: want }] }];
+  }
+  return {
+    settings: { ...base, hooks },
+    changed: added.length > 0 || repaired.length > 0,
+    added,
+    repaired,
+    preserved
+  };
+}
+function installHooksFile(path, scriptPath, opts = {}) {
+  const empty = { settings: {}, changed: false, added: [], repaired: [], preserved: [], wrote: false };
+  try {
+    let current = null;
+    if (existsSync2(path)) {
+      const raw = readFileSync2(path, "utf8");
+      if (raw.trim()) {
+        try {
+          current = JSON.parse(raw);
+        } catch (e) {
+          return { ...empty, error: `settings file is not valid JSON (${e.message}); left untouched` };
+        }
+      }
+    }
+    const result = installHooks(current, scriptPath);
+    if (!result.changed) return { ...result, wrote: false };
+    let backup;
+    if (opts.backup !== false && existsSync2(path)) {
+      backup = `${path}.loupe-backup`;
+      copyFileSync(path, backup);
+    }
+    mkdirSync2(dirname2(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync2(tmp, `${JSON.stringify(result.settings, null, 2)}
+`);
+    renameSync2(tmp, path);
+    return { ...result, backup, wrote: true };
+  } catch (e) {
+    return { ...empty, error: e.message };
+  }
+}
+
 // src/bridge/events.ts
 var EventBus = class {
   subscribers = /* @__PURE__ */ new Set();
@@ -252,6 +651,10 @@ var EventBus = class {
     }
   }
   /** Publish a thread update. The seam the MCP tools use. */
+  /** A companion message or reply, so the panel updates without polling. */
+  publishCompanion(eventType, data) {
+    this.publish({ type: "companion", eventType, data, at: (/* @__PURE__ */ new Date()).toISOString() });
+  }
   publishThread(threadId, eventType, data) {
     this.publish({ type: "thread", threadId, eventType, data, at: (/* @__PURE__ */ new Date()).toISOString() });
   }
@@ -262,6 +665,102 @@ var EventBus = class {
 
 // src/bridge/http-bridge.ts
 import { createServer } from "http";
+
+// src/hooks/hook-events.ts
+var EVENT_MAP = {
+  sessionstart: "session_start",
+  sessionend: "session_end",
+  userpromptsubmit: "prompt_submit",
+  pretooluse: "tool_use",
+  posttooluse: "tool_result",
+  subagentstop: "subagent_stop",
+  subagentstart: "subagent_start",
+  notification: "notification",
+  stop: "turn_end",
+  precompact: "compact"
+};
+function eventTypeFor(hookName) {
+  const key = String(hookName || "").toLowerCase().replace(/[^a-z]/g, "");
+  return EVENT_MAP[key] ?? (hookName ? String(hookName) : "unknown");
+}
+function summarize(hookName, payload) {
+  const type = eventTypeFor(hookName);
+  const at = (s) => typeof s === "string" && s.trim() ? s.trim() : void 0;
+  if (type === "prompt_submit") return at(payload.prompt)?.slice(0, 200);
+  if (type === "notification") return at(payload.message)?.slice(0, 200);
+  if (type === "tool_use" || type === "tool_result") {
+    const tool = at(payload.tool_name);
+    return tool ? `${type === "tool_use" ? "used" : "finished"} ${tool}` : void 0;
+  }
+  if (type === "session_start" || type === "session_end") {
+    return at(payload.cwd) ?? at(payload.source);
+  }
+  return void 0;
+}
+function toolFailed(payload) {
+  const resp = payload.tool_response;
+  if (resp && typeof resp === "object") {
+    if (typeof resp.is_error === "boolean") return resp.is_error;
+    if (typeof resp.error === "string" && resp.error) return true;
+    if (typeof resp.success === "boolean") return !resp.success;
+    if (typeof resp.exit_code === "number") return resp.exit_code !== 0;
+    if (typeof resp.status === "number") return resp.status >= 400;
+  }
+  return void 0;
+}
+function normalizeHookEvent(hookName, payload, at) {
+  const type = eventTypeFor(hookName);
+  const sessionId = typeof payload.session_id === "string" ? payload.session_id : void 0;
+  const tool = typeof payload.tool_name === "string" ? payload.tool_name : void 0;
+  const files = [.../* @__PURE__ */ new Set([...extractFiles(payload.tool_input ?? {}), ...extractFiles(payload)])];
+  const extra = {};
+  const failed = type === "tool_result" ? toolFailed(payload) : void 0;
+  if (failed !== void 0) extra.ok = !failed;
+  return {
+    type,
+    sessionId,
+    tool,
+    summary: summarize(hookName, payload),
+    files: files.length ? files : void 0,
+    at,
+    payload: Object.keys(extra).length ? { ...extra, hook: hookName } : { hook: hookName }
+  };
+}
+
+// src/bridge/state-file.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, rmSync, writeFileSync as writeFileSync3 } from "fs";
+import { homedir } from "os";
+import { dirname as dirname3, join } from "path";
+function stateDir(env = process.env) {
+  return env.LOUPE_STATE_DIR || join(homedir(), ".loupe");
+}
+function stateFilePath(env = process.env) {
+  return join(stateDir(env), "bridge.json");
+}
+function writeBridgeState(port, env = process.env) {
+  const file = stateFilePath(env);
+  try {
+    mkdirSync3(dirname3(file), { recursive: true });
+    const state = { url: `http://127.0.0.1:${port}`, port, pid: process.pid, at: (/* @__PURE__ */ new Date()).toISOString() };
+    writeFileSync3(file, `${JSON.stringify(state, null, 2)}
+`);
+    return file;
+  } catch {
+    return null;
+  }
+}
+function clearBridgeState(port, env = process.env) {
+  const file = stateFilePath(env);
+  try {
+    if (!existsSync3(file)) return;
+    const state = JSON.parse(readFileSync3(file, "utf8"));
+    if (state?.port !== port) return;
+    rmSync(file, { force: true });
+  } catch {
+  }
+}
+
+// src/bridge/http-bridge.ts
 var MAX_BODY_BYTES = 1024 * 1024;
 var SSE_KEEPALIVE_MS = 15e3;
 async function startHttpBridge(port, deps, opts = {}) {
@@ -274,10 +773,14 @@ async function startHttpBridge(port, deps, opts = {}) {
     try {
       await listen(server2, port);
       const bound = server2.address()?.port ?? port;
+      writeBridgeState(bound);
       return {
         port: bound,
         url: `http://127.0.0.1:${bound}`,
-        close: () => close(server2)
+        close: async () => {
+          clearBridgeState(bound);
+          await close(server2);
+        }
       };
     } catch (e) {
       const code = e?.code;
@@ -451,13 +954,13 @@ async function handle(req, res, deps) {
       } catch {
         return send(res, 400, { error: "body is not valid JSON" }, origin);
       }
-      const join2 = parsed;
-      if (!join2 || typeof join2 !== "object" || !join2.url || !join2.userId || !join2.name) {
+      const join3 = parsed;
+      if (!join3 || typeof join3 !== "object" || !join3.url || !join3.userId || !join3.name) {
         return send(res, 400, { error: "url, userId and name are required" }, origin);
       }
-      const peer = deps.presence.join({ url: join2.url, userId: join2.userId, name: join2.name, tab: join2.tab });
+      const peer = deps.presence.join({ url: join3.url, userId: join3.userId, name: join3.name, tab: join3.tab });
       deps.bus.publish({ type: "presence", data: deps.presence.list(), at: (/* @__PURE__ */ new Date()).toISOString() });
-      return send(res, 201, { ok: true, peer, peers: deps.presence.list(join2.url, peer.id) }, origin);
+      return send(res, 201, { ok: true, peer, peers: deps.presence.list(join3.url, peer.id) }, origin);
     }
     if (method === "GET" && path === "/presence") {
       const pageUrl = url.searchParams.get("url") ?? void 0;
@@ -495,6 +998,90 @@ async function handle(req, res, deps) {
       deps.bus.publishThread(evt.threadId, evt.eventType, evt.data);
       return send(res, 202, { ok: true }, origin);
     }
+    if (method === "POST" && path === "/events/ingest") {
+      const body = await readBody(req);
+      if (!body.ok) return send(res, 400, { error: body.error }, origin);
+      let parsed;
+      try {
+        parsed = JSON.parse(body.text);
+      } catch {
+        return send(res, 400, { error: "body is not valid JSON" }, origin);
+      }
+      if (!parsed || typeof parsed !== "object" || typeof parsed.event !== "string" || !parsed.event) {
+        return send(res, 400, { error: "event is required" }, origin);
+      }
+      if (!deps.events) return send(res, 503, { error: "event store is not enabled" }, origin);
+      const payload = parsed.payload && typeof parsed.payload === "object" ? parsed.payload : {};
+      const event = deps.events.add(normalizeHookEvent(parsed.event, payload, parsed.at));
+      return send(res, 202, { ok: true, event }, origin);
+    }
+    if (method === "GET" && path === "/events/recent") {
+      if (!deps.events) return send(res, 503, { error: "event store is not enabled" }, origin);
+      const limit = Number(url.searchParams.get("limit") ?? 50);
+      const type = url.searchParams.get("type") ?? void 0;
+      const events2 = deps.events.latest(Number.isFinite(limit) ? limit : 50);
+      return send(res, 200, { events: type ? events2.filter((e) => e.type === type) : events2, total: deps.events.size() }, origin);
+    }
+    if (method === "GET" && path === "/sessions") {
+      if (!deps.events) return send(res, 503, { error: "event store is not enabled" }, origin);
+      return send(res, 200, { sessions: sessionsFromEvents(deps.events.recent(deps.events.size())) }, origin);
+    }
+    if (method === "POST" && path === "/companion") {
+      const body = await readBody(req);
+      if (!body.ok) return send(res, 400, { error: body.error }, origin);
+      let parsed;
+      try {
+        parsed = JSON.parse(body.text);
+      } catch {
+        return send(res, 400, { error: "body is not valid JSON" }, origin);
+      }
+      if (!parsed || typeof parsed !== "object" || typeof parsed.body !== "string" || !parsed.body.trim()) {
+        return send(res, 400, { error: "body is required" }, origin);
+      }
+      if (!deps.companion) return send(res, 503, { error: "companion is not enabled" }, origin);
+      const message = deps.companion.push({
+        body: parsed.body,
+        author: parsed.author,
+        contexts: Array.isArray(parsed.contexts) ? parsed.contexts.slice(0, 20) : void 0,
+        attachments: Array.isArray(parsed.attachments) ? parsed.attachments.slice(0, 10) : void 0,
+        voice: parsed.voice === true
+      });
+      deps.bus.publishCompanion("message", message);
+      return send(res, 201, { ok: true, message, queued: deps.companion.size() }, origin);
+    }
+    if (method === "GET" && path === "/companion") {
+      if (!deps.companion) return send(res, 503, { error: "companion is not enabled" }, origin);
+      if (url.searchParams.get("since")) {
+        return send(res, 200, {
+          replies: deps.companion.listReplies(50),
+          messages: deps.companion.list(),
+          queued: deps.companion.size()
+        }, origin);
+      }
+      return send(res, 200, {
+        messages: deps.companion.list(),
+        replies: deps.companion.listReplies(50),
+        queued: deps.companion.size(),
+        pending: deps.companion.pending()
+      }, origin);
+    }
+    if (method === "POST" && path === "/companion/reply") {
+      const body = await readBody(req);
+      if (!body.ok) return send(res, 400, { error: body.error }, origin);
+      let parsed;
+      try {
+        parsed = JSON.parse(body.text);
+      } catch {
+        return send(res, 400, { error: "body is not valid JSON" }, origin);
+      }
+      if (!parsed || typeof parsed.body !== "string" || !parsed.body.trim()) {
+        return send(res, 400, { error: "body is required" }, origin);
+      }
+      if (!deps.companion) return send(res, 503, { error: "companion is not enabled" }, origin);
+      const reply = deps.companion.addReply({ body: parsed.body, inReplyTo: parsed.inReplyTo });
+      deps.bus.publishCompanion("reply", reply);
+      return send(res, 201, { ok: true, reply }, origin);
+    }
     if (method === "GET" && (path === "/events" || path === "/thread-updates")) {
       return streamEvents(req, res, deps, path === "/thread-updates" ? "thread" : null, origin);
     }
@@ -535,7 +1122,7 @@ data: ${JSON.stringify(event)}
 
 // src/mapper.ts
 import { readdir, readFile, stat } from "fs/promises";
-import { basename, join, relative, sep } from "path";
+import { basename, join as join2, relative, sep } from "path";
 var SIGNAL_WEIGHTS = {
   id: 0.85,
   "aria-label": 0.8,
@@ -693,7 +1280,7 @@ async function collectFiles(root, opts = {}) {
         truncated = true;
         break;
       }
-      const full = join(dir, entry.name);
+      const full = join2(dir, entry.name);
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
         queue.push(full);
@@ -1578,6 +2165,8 @@ var BRIDGE_PORT = Number(process.env.LOUPE_BRIDGE_PORT ?? 9800);
 var store = new SelectionStore(Number(process.env.LOUPE_SELECTION_CAP ?? 50));
 var registry = new AgentRegistry();
 var presence = new PresenceRegistry();
+var events = new EventStore({ file: process.env.LOUPE_EVENT_FILE || void 0 });
+var companion = new CompanionQueue();
 var bus = new EventBus();
 var ADMIN = process.env.LOUPE_ADMIN_KEY || "";
 async function api(path, init) {
@@ -1727,8 +2316,28 @@ async function proposeChange({ id, html, css, notes }) {
   bus.publishThread(id, "preview_live", { author: proposal.author });
   return wrap(`Proposal saved for #${id}. The dev team can now review your modified HTML/CSS in the dashboard.`);
 }
-var server = new McpServer({ name: "loupe", version: "0.10.25" });
-server.tool(
+function hookScriptPath() {
+  const candidates = [
+    new URL("./hooks/loupe-hook.mjs", import.meta.url).pathname,
+    new URL("../hooks/loupe-hook.mjs", import.meta.url).pathname
+  ];
+  return candidates.find((c) => existsSync4(c)) ?? candidates[0];
+}
+var server = new McpServer({ name: "loupe", version: "0.10.26" });
+function withCompanion(handler) {
+  return (async (...args) => {
+    const result = await handler(...args);
+    const pending = companion.take();
+    if (!pending.length) return result;
+    const wrapped = prependToResult(result, pending);
+    companion.ack(pending.map((m) => m.id));
+    return wrapped;
+  });
+}
+function registerTool(name, description, schema, handler) {
+  return server.tool(name, description, schema, withCompanion(handler));
+}
+registerTool(
   "list_comments",
   "List Loupe product-feedback comments for the project as a task backlog. Each item carries its board stage, priority and change type, so you can start with the most urgent. Use this to see what a PM has flagged, then work through the items.",
   {
@@ -1741,19 +2350,19 @@ server.tool(
   },
   listComments
 );
-server.tool(
+registerTool(
   "get_comment",
   "Get the full context for one comment: the request, the page, the target element's HTML, and its computed styles \u2014 everything needed to make the change.",
   { id: z.string().describe("The comment id from list_comments.") },
   getComment
 );
-server.tool(
+registerTool(
   "update_status",
   "Move a comment along the board. Set In Progress when you start it, and In Review when the change is ready for a human \u2014 only a person resolves a comment, so never set Resolved yourself.",
   { id: z.string(), status: STAGE_ARG },
   updateStatus
 );
-server.tool(
+registerTool(
   "propose_change",
   "Submit the modified UI for a comment: the rewritten HTML (and optional CSS) that resolves the PM's request. This stores your proposal on the comment so the dev team can review the code and a live preview in the dashboard. Use get_comment first to see the original element, its computed styles, and the screenshot.",
   {
@@ -1784,19 +2393,19 @@ var SELECTION_ARGS = {
     "A specific selection by correlation id (see get_selection_history). Omit for the most recent."
   )
 };
-server.tool(
+registerTool(
   "get_latest_selection",
   `What the user last selected in the browser, with its element, computed styles and the source files most likely to render it. Use this when someone says "this element" or "what I'm looking at" and no thread exists yet.`,
   {},
   async () => wrap((await elementTools.getLatestSelection()).text)
 );
-server.tool(
+registerTool(
   "get_selection_history",
   "The recent element selections, newest first \u2014 useful when the user clicked a few things and you need to pick the right one.",
   { limit: z.number().int().positive().max(50).optional().describe("How many to list. Defaults to 10.") },
   async ({ limit }) => wrap((await elementTools.getSelectionHistory({ limit })).text)
 );
-server.tool(
+registerTool(
   "get_element_context",
   "Full context for one element: the element, the page, its key computed styles, the ranked source files that probably render it, and a ready-made edit prompt. Pass thread_id to work from a stored comment, or nothing to use the latest live selection. Call this before editing anything.",
   {
@@ -1805,12 +2414,92 @@ server.tool(
   },
   async ({ thread_id, selection_id, include_prompt }) => wrap((await elementTools.getElementContext({ thread_id, selection_id }, { include_prompt })).text)
 );
-server.tool(
+registerTool(
   "find_source_for_selection",
   "Just the ranked source files for the current selection or a stored thread \u2014 for when you only need to know where the component lives. Heuristic: verify the top candidate before editing it.",
   SELECTION_ARGS,
   async ({ thread_id, selection_id }) => wrap((await elementTools.findSourceForSelection({ thread_id, selection_id })).text)
 );
+registerTool(
+  "get_companion_messages",
+  "Read what the person watching has said while you were working. Messages are ALSO delivered automatically on every other tool result, so you rarely need this \u2014 use it when you want to check before finishing a task, or when someone asked you to wait for their input.",
+  { drain: z.boolean().optional().describe("Set false to read without consuming. Default true.") },
+  async ({ drain }) => {
+    const messages = drain === false ? companion.peek() : companion.take();
+    if (drain !== false) companion.ack(messages.map((m) => m.id));
+    if (!messages.length) return wrap("No companion messages waiting.");
+    return wrap(
+      messages.map((m) => {
+        const where = m.contexts?.length ? ` (re: ${m.contexts.map((c) => c.label ?? c.url ?? c.id ?? c.kind).join(", ")})` : "";
+        const atts = m.attachments?.length ? ` [${m.attachments.map((a) => a.url).join(", ")}]` : "";
+        return `[${m.at}] ${m.author?.name ? `${m.author.name}: ` : ""}${m.body}${where}${atts}`;
+      }).join("\n")
+    );
+  }
+);
+registerTool(
+  "reply_to_companion",
+  "Answer the person watching, in the panel they are looking at. Use this when a companion message needs a response, when you need a decision before continuing, or when you finish something they asked about.",
+  {
+    body: z.string().describe("Your reply. Markdown is fine."),
+    inReplyTo: z.string().optional().describe("The id of the message you are answering.")
+  },
+  async ({ body, inReplyTo }) => {
+    const reply = companion.addReply({ body, inReplyTo });
+    bus.publishCompanion("reply", reply);
+    return wrap(`Sent to the panel at ${reply.at}.`);
+  }
+);
+registerTool(
+  "get_activity_summary",
+  `What this machine's agent sessions have been doing: sessions, tool-call counts, files touched, and whether a session is still live. Use it to understand what has already been tried before starting, or to answer "what have you been working on?".`,
+  {
+    session_id: z.string().optional().describe("Just this session."),
+    limit: z.number().int().positive().max(50).optional().describe("How many sessions to summarize. Default 5.")
+  },
+  async ({ session_id, limit }) => {
+    const all = sessionsFromEvents(events.recent(events.size()));
+    const picked = session_id ? all.filter((s) => s.id === session_id) : all.slice(0, limit ?? 5);
+    if (!picked.length) {
+      return wrap(
+        events.size() ? `No session matched. Known sessions: ${all.map((s) => s.id).join(", ") || "(none)"}.` : "No agent events recorded yet. The hooks may not be installed \u2014 install_agent_hooks adds them."
+      );
+    }
+    return wrap(picked.map(sessionSummaryText).join("\n\n"));
+  }
+);
+registerTool(
+  "install_agent_hooks",
+  "Install the Claude Code hooks that report tool use, prompts and sessions to Loupe. Idempotent (running it twice changes nothing), backed up before writing, and it never touches another tool's hook entries. Opt-in: nothing installs these on its own.",
+  {
+    path: z.string().optional().describe("The settings file to write. Defaults to ~/.claude/settings.json.")
+  },
+  async ({ path: custom }) => {
+    const script = process.env.LOUPE_HOOK_SCRIPT || hookScriptPath();
+    const target = custom || process.env.LOUPE_CLAUDE_SETTINGS || `${process.env.HOME || ""}/.claude/settings.json`;
+    const result = installHooksFile(target, script);
+    if (result.error) return wrap(`Could not install: ${result.error}
+
+Nothing was changed.`);
+    if (!result.wrote) {
+      return wrap(`Already installed and current \u2014 nothing to change (${result.preserved.length} events already wired).
+
+Settings: ${target}
+Hook script: ${script}`);
+    }
+    const lines = [
+      `Installed into ${target}.`,
+      result.added.length ? `Added: ${result.added.join(", ")}` : null,
+      result.repaired.length ? `Repaired (pointed somewhere stale): ${result.repaired.join(", ")}` : null,
+      result.backup ? `Backup: ${result.backup}` : null,
+      `Hook script: ${script}`,
+      "",
+      "Restart Claude Code for the hooks to take effect. Loupe's own hooks are marked with",
+      `"${HOOK_MARKER}" and your other hook entries were left untouched.`
+    ].filter(Boolean);
+    return wrap(lines.join("\n"));
+  }
+);
 var AGENT = {
   id: process.env.LOUPE_AGENT_ID || "loupe-agent",
   name: process.env.LOUPE_AGENT_NAME || "Claude Code"
@@ -1827,7 +2516,7 @@ var handoff = createHandoffTools({
   }),
   listMessages: async (threadId) => await api(`/v1/comments/${encodeURIComponent(threadId)}/messages`)
 });
-server.tool(
+registerTool(
   "mark_thread_addressed",
   "Hand a thread back to a human: it moves to In Review and, optionally, posts your closing note. Use this when the change is ready. It CANNOT resolve a thread \u2014 only a person does that \u2014 which is why there is no status argument.",
   {
@@ -1836,7 +2525,7 @@ server.tool(
   },
   async ({ thread_id, message }) => wrap((await handoff.markThreadAddressed({ thread_id, message })).text)
 );
-server.tool(
+registerTool(
   "add_thread_message",
   "Reply on a thread without changing its status \u2014 progress notes, questions, or the preview URL when it goes live. The status is left exactly as it was.",
   {
@@ -1845,13 +2534,13 @@ server.tool(
   },
   async ({ thread_id, message }) => wrap((await handoff.addThreadMessage({ thread_id, message })).text)
 );
-server.tool(
+registerTool(
   "get_thread_conversation",
   "The whole conversation on a thread: the original request, then every reply with its author. Read it before answering so you are not repeating something already said.",
   { thread_id: z.string() },
   async ({ thread_id }) => wrap((await handoff.getThreadConversation({ thread_id })).text)
 );
-server.tool(
+registerTool(
   "create_pr_for_thread",
   "Open a pull request for a fix \u2014 or, more usually, add it to the one the repo already has. One working branch per repo accumulates every fix as its own commit, and the PR body keeps a table of them. If that PR was merged or closed, a fresh branch is started automatically. Use `get_element_context` first to find the file, then pass the full new contents of each file you changed.",
   {
@@ -1914,7 +2603,7 @@ function isEntrypoint() {
   }
 }
 if (isEntrypoint()) {
-  const bridge = BRIDGE_PORT ? await startHttpBridge(BRIDGE_PORT, { store, registry, presence, bus }) : null;
+  const bridge = BRIDGE_PORT ? await startHttpBridge(BRIDGE_PORT, { store, registry, presence, events, companion, bus }) : null;
   const self = registry.register({
     name: process.env.LOUPE_AGENT_NAME || "loupe-mcp",
     type: process.env.LOUPE_AGENT_TYPE || "claude-code",

package/hooks/loupe-hook.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * The Loupe hook.
+ *
+ * Claude Code runs this on each configured event and hands the event on stdin. It
+ * forwards to the bridge and gets out of the way.
+ *
+ * Three rules, all of them about not being the reason someone's agent misbehaves:
+ *  - **Never block.** A short timeout, and nothing is awaited that could hang.
+ *  - **Never throw.** A non-zero exit prints noise into the agent's session, and a
+ *    hook that fails is worse than a hook that did nothing.
+ *  - **Never write to stdout.** Claude Code interprets hook stdout; a stray line could
+ *    be read as a decision. Diagnostics go to stderr only when LOUPE_HOOK_DEBUG is set.
+ *
+ * The bridge binds an ephemeral port, so it publishes where it can be found rather
+ * than the port being baked into this command.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const TIMEOUT_MS = 1200;
+
+function debug(...args) {
+  if (process.env.LOUPE_HOOK_DEBUG) console.error("[loupe-hook]", ...args);
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    // A hook can be run with no stdin at all; resolve empty rather than hang.
+    if (process.stdin.isTTY) return resolve("");
+    let data = "";
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(data);
+    };
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => (data += chunk));
+    process.stdin.on("end", finish);
+    process.stdin.on("error", finish);
+    // Claude Code always closes stdin, but a wedged pipe must not hold the agent.
+    setTimeout(finish, 500).unref?.();
+  });
+}
+
+function stateFile() {
+  const dir = process.env.LOUPE_STATE_DIR || join(homedir(), ".loupe");
+  return join(dir, "bridge.json");
+}
+
+function bridgeUrl() {
+  if (process.env.LOUPE_BRIDGE_URL) return process.env.LOUPE_BRIDGE_URL.replace(/\/$/, "");
+  try {
+    const state = JSON.parse(readFileSync(stateFile(), "utf8"));
+    if (state && typeof state.url === "string" && state.url) return state.url.replace(/\/$/, "");
+  } catch {
+    // No bridge has run on this machine, or the file is stale. Either way there is
+    // nothing to report to, and that is not an error.
+  }
+  return null;
+}
+
+async function main() {
+  const event = process.argv[2] || "unknown";
+  const raw = await readStdin();
+  const url = bridgeUrl();
+  if (!url) {
+    debug("no bridge state file; nothing to report to");
+    return;
+  }
+
+  let payload = {};
+  if (raw.trim()) {
+    try {
+      payload = JSON.parse(raw);
+    } catch {
+      // Keep the raw text; a hook that sends something unparseable still tells us the
+      // event happened and when.
+      payload = { raw: raw.slice(0, 2000) };
+    }
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    await fetch(`${url}/events/ingest`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ event, payload, at: new Date().toISOString() }),
+      signal: controller.signal,
+    });
+  } catch (e) {
+    debug("forward failed:", e?.message ?? e);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Exit 0 whatever happened — see the rules at the top.
+main()
+  .catch((e) => debug("unexpected:", e?.message ?? e))
+  .finally(() => process.exit(0));

package/package.json

@@ -5,7 +5,7 @@
     "email": "m.ashraf.saed@gmail.com",
     "url": "https://www.linkedin.com/in/mohamedashrafelsaed/"
   },
-  "version": "0.10.25",
+  "version": "0.10.26-next.73",
   "description": "MCP server that exposes Loupe comments to Claude Code as an actionable, fully-contextualized backlog.",
   "keywords": [
     "loupe",
@@ -30,7 +30,8 @@
   "type": "module",
   "main": "./dist/index.js",
   "files": [
-    "dist"
+    "dist",
+    "hooks"
   ],
   "bin": {
     "loupe-mcp": "./dist/index.js"
@@ -46,6 +47,6 @@
     "zod": "^3.24.1"
   },
   "devDependencies": {
-    "@loupekit/shared": "0.10.25"
+    "@loupekit/shared": "0.10.26-next.73"
   }
 }