@insitue/claude-plugin 0.4.1 → 0.4.2

package/commands/connect.md

@@ -81,9 +81,25 @@ Either path is fine; pick whichever your runtime has.
    `[insitue]` (e.g. "companion disconnected"), tell the user
    what happened in one sentence and call `next_pick` again —
    the bridge auto-reconnects.
-5. Exit the loop when the user says "stop", "done", "quit",
-   "thanks", "exit", or anything else that clearly ends the
-   session.
+5. **End the session properly.** When the user says "stop",
+   "done", "quit", "thanks", "exit", "disconnect", "stop
+   insitue", or anything else that clearly ends the InSitue
+   session, do BOTH of these:
+   a. Call `mcp__insitue__end_session` ONCE. This is non-
+      optional. Without it the browser launcher stays purple
+      forever — the user sees you as "still listening" when
+      you're not. The teardown is cheap (closes a WS, drops a
+      file) and safe to repeat.
+   b. Stop calling `next_pick`. Acknowledge the disconnect in
+      one short line.
+
+   If the user's "stop" is clearly scoped to *the current task*
+   ("stop reading that file", "stop, that's not what I meant")
+   — i.e. they're not signalling end-of-InSitue — leave the
+   subscriber attached and keep the loop alive. Read the room.
+
+   On Claude Code the user can also run `/insitue:disconnect`
+   directly; that hits `end_session` the same way.
 
 ## Guardrails
 

package/commands/disconnect.md

@@ -0,0 +1,37 @@
+---
+description: Cleanly disconnect this Claude session from InSitue — mutes the browser launcher, frees the companion port.
+---
+
+# /insitue:disconnect
+
+Tears down the InSitue session in this Claude Code window
+without exiting claude. Use when you're done picking for now —
+the launcher in the browser goes muted, the companion process
+the MCP server spawned is killed, the stale session file is
+removed.
+
+## Your behaviour
+
+1. Call `mcp__insitue__end_session` once.
+2. Summarise what was torn down in a single line — e.g.
+   *"Disconnected. Companion stopped, session cleared. Run
+   `/insitue:connect` again whenever you want to start picking."*
+   Don't narrate every field of the response; the user just
+   needs to know it worked.
+3. **Exit any active pick loop** — stop calling `next_pick`.
+4. Stay in the chat. The user may have more for you here that
+   isn't pick-related. Don't `/exit`; that's their call.
+
+## Symmetric with /insitue:connect
+
+`/insitue:connect` attaches the subscriber → browser launcher
+goes purple. `/insitue:disconnect` detaches → browser launcher
+goes muted. Both safe to call any number of times, in any
+order; the MCP holds the lifecycle straight.
+
+## Reconnecting after disconnect
+
+Just run `/insitue:connect` again. The MCP re-spawns the
+companion if needed (the kill in `end_session` left `npx` ready
+to restart), re-attaches the WS, and you're back in the loop.
+No claude restart required.

package/dist/mcp-server.js

@@ -9,7 +9,7 @@ import {
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { spawn } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync3 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3, rmSync } from "fs";
 import { request as httpRequest } from "http";
 import { dirname as dirname3, join as join3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
@@ -360,11 +360,15 @@ process.on("SIGTERM", () => {
   process.exit(143);
 });
 var buffer = new PickBuffer();
-function connectToCompanion(session2) {
-  const url = `ws://127.0.0.1:${session2.port}/insitue/cli`;
+var activeWs = null;
+var reconnectTimer = null;
+var disconnecting = false;
+function connectToCompanion(s) {
+  const url = `ws://127.0.0.1:${s.port}/insitue/cli`;
   const ws = new WebSocket(url, {
     headers: { "user-agent": "insitue-claude-plugin" }
   });
+  activeWs = ws;
   ws.on("open", () => {
     ws.send(
       JSON.stringify({
@@ -372,7 +376,7 @@ function connectToCompanion(session2) {
         // Pin to the companion's pinned protocol version. Bump
         // when the wire format breaks.
         protocolVersion: 5,
-        token: session2.token
+        token: s.token
       })
     );
   });
@@ -413,8 +417,10 @@ function connectToCompanion(session2) {
     }
   });
   ws.on("close", () => {
+    if (activeWs === ws) activeWs = null;
     buffer.rejectAll("companion disconnected \u2014 restart `claude` to reconnect");
-    setTimeout(() => connectToCompanion(session2), 2e3);
+    if (disconnecting) return;
+    reconnectTimer = setTimeout(() => connectToCompanion(s), 2e3);
   });
   ws.on("error", () => {
   });
@@ -431,11 +437,51 @@ if (!session) {
   );
 }
 var attached = false;
-function ensureSubscriberAttached() {
-  if (attached || !session) return;
+async function ensureSubscriberAttached() {
+  if (attached) return;
+  disconnecting = false;
+  if (!session) {
+    session = await ensureCompanion(projectDir.dir);
+    if (!session) return;
+  }
   attached = true;
   connectToCompanion(session);
 }
+function endSession() {
+  disconnecting = true;
+  attached = false;
+  let closedWs = false;
+  let killedCompanion = false;
+  let removedSessionFile = false;
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  if (activeWs) {
+    try {
+      activeWs.close();
+      closedWs = true;
+    } catch {
+    }
+    activeWs = null;
+  }
+  if (ownedChild) {
+    killedCompanion = true;
+    cleanupOwnedChild();
+  }
+  if (killedCompanion) {
+    const f = join3(projectDir.dir, ".insitue", "session.json");
+    if (existsSync2(f)) {
+      try {
+        rmSync(f);
+        removedSessionFile = true;
+      } catch {
+      }
+    }
+  }
+  session = null;
+  return { closedWs, killedCompanion, removedSessionFile };
+}
 var server = new McpServer({
   name: "insitue",
   version: "0.3.0"
@@ -451,7 +497,7 @@ server.registerTool(
     }
   },
   async ({ timeout_ms }) => {
-    ensureSubscriberAttached();
+    await ensureSubscriberAttached();
     const ms = timeout_ms ?? NEXT_PICK_DEFAULT_TIMEOUT_MS;
     const pick = await buffer.next(ms);
     if (!pick) {
@@ -480,7 +526,7 @@ server.registerTool(
     }
   },
   async ({ limit }) => {
-    ensureSubscriberAttached();
+    await ensureSubscriberAttached();
     const picks = buffer.recent(limit ?? 10);
     return {
       content: [
@@ -499,7 +545,7 @@ server.registerTool(
     inputSchema: {}
   },
   async () => {
-    ensureSubscriberAttached();
+    await ensureSubscriberAttached();
     const instructions = loadInstructions();
     const buffered = buffer.recent(32).length;
     const status = `
@@ -520,6 +566,24 @@ Begin the loop by calling \`list_recent_picks\` once, then loop on \`next_pick\`
     };
   }
 );
+server.registerTool(
+  "end_session",
+  {
+    description: "Cleanly disconnect this MCP from the InSitue companion: close the WS subscriber (browser launcher mutes immediately), suppress auto-reconnect, kill the companion if we spawned it, and remove the stale session file. The user can reconnect later in the same claude session via `/insitue:connect` (Code) or by calling `start_session` again (Desktop). Safe to call repeatedly. Returns what was actually torn down.",
+    inputSchema: {}
+  },
+  async () => {
+    const r = endSession();
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ status: "disconnected", ...r })
+        }
+      ]
+    };
+  }
+);
 server.registerTool(
   "diagnose",
   {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insitue/claude-plugin",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Drive Claude (Code AND Desktop) from the InSitue browser overlay — pick an element in your app, claude reads the file and proposes the edit.",
   "license": "MIT",
   "type": "module",