@insitue/claude-plugin 0.0.3 → 0.1.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "insitue",
-  "version": "0.0.3",
+  "version": "0.1.1",
   "description": "Drive a Claude Code session from the InSitue browser overlay. Pick an element in your app, claude reads the file and proposes the edit.",
   "mcpServers": {
     "insitue": {

package/commands/connect.md

@@ -19,14 +19,17 @@ Connect this Claude Code session to the running InSitue companion and turn each
 
 - **First**, call `mcp__insitue__list_recent_picks` once to see if the user already picked things before attaching. If there are recent picks the user hasn't acted on, summarise them so they can choose which to address.
 - **Then enter the loop**: call `mcp__insitue__next_pick`. It blocks for ~5 min by default. When it returns:
-  - If `status: "ok"`: read the `pick.source.file` at `pick.source.line`, plus a few surrounding lines for context.
-  - The `pick.userNote` is the user's instruction. If empty, ask "What would you like to change at `<componentName>` (`<file>:<line>`)?" before doing anything.
+  - If `status: "ok"`:
+    - **If `pick.userNote` is set**: the user typed an instruction in the browser panel before sending. Read the `pick.source.file` at `pick.source.line`, propose an edit, show the diff, wait for "approve"/"yes" before writing.
+    - **If `pick.userNote` is null** (user clicked without typing): the user might still be about to type in the browser panel — they have an ASK textbox in the panel that streams here as a `broadcast-ask` event. **Call `next_pick` AGAIN with a 30-second timeout** to wait for the follow-up note. The MCP bridge re-delivers the same pick with `userNote` populated once the user sends it. If that second call returns `status: "timeout"` instead, ONLY THEN fall back to asking "What would you like to change at `<componentName>` (`<file>:<line>`)?" in the terminal.
   - Propose an edit. Show a small diff in chat. Wait for the user to say "go" / "approve" / "yes" before writing.
   - On approval, apply with Edit/Write. Confirm what changed.
   - Loop back to `next_pick`.
 - **If a pick comes through with `target` starting with `[insitue]`**: the companion disconnected (HMR / restart). Tell the user, then call `next_pick` again — the bridge auto-reconnects.
 - **Exit the loop** when the user says "stop", "done", "quit", or similar.
 
+**Why the double-poll on note-less picks**: the user's hands are on the browser, not the terminal. Their natural workflow is pick → type intent in the panel's ASK textbox → click Send. That ASK arrives via MCP as a `broadcast-ask` joined to the previous pick. If you ask in the terminal while the user is typing in the browser, both messages land at once and the user is confused. Default to "user is about to type in the browser" — re-poll first, only ask in the terminal as a last resort.
+
 ## Guardrails
 
 - Don't touch any file outside the pick's `pick.source.file` unless the user explicitly asks for cross-file changes.

package/dist/mcp-server.js

@@ -61,19 +61,65 @@ var PickBuffer = class {
     if (this.picks.length > MAX_BUFFERED_PICKS) {
       this.picks.shift();
     }
+    this.flushWaiters();
+  }
+  /** #162: merge a `broadcast-ask` into the matching `pick.userNote`.
+   *  Two ordering modes the user might create:
+   *   1. Pick first (auto on click), THEN type + Send → ask lands
+   *      AFTER pick. If the pick is still queued (not yet delivered
+   *      to claude), update it in place. If already delivered, the
+   *      ask arrives as a standalone update — surfaced as a synthetic
+   *      pick whose `userNote` is set so claude treats it as new
+   *      input on the most-recent target.
+   *   2. Ask before pick is impossible (the panel needs a pick first
+   *      to enable the ASK textbox), so we don't handle that. */
+  attachAsk(bundleId, text) {
+    const idx = this.picks.findIndex((p) => p.id === bundleId);
+    if (idx >= 0) {
+      this.picks[idx] = { ...this.picks[idx], userNote: text };
+      this.flushWaiters();
+      return;
+    }
+    if (this.lastDelivered === bundleId && this.lastDeliveredPick) {
+      this.picks.push({
+        ...this.lastDeliveredPick,
+        userNote: text,
+        at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      this.flushWaiters();
+      return;
+    }
+    const orphan = {
+      id: bundleId,
+      at: (/* @__PURE__ */ new Date()).toISOString(),
+      source: null,
+      confidence: "n/a",
+      target: "[insitue] note without pick",
+      selector: null,
+      userNote: text,
+      url: null,
+      componentStack: []
+    };
+    this.picks.push(orphan);
+    this.flushWaiters();
+  }
+  flushWaiters() {
     while (this.waiters.length && this.picks.length) {
       const w = this.waiters.shift();
       clearTimeout(w.timer);
       const next = this.picks.shift();
       this.lastDelivered = next.id;
+      this.lastDeliveredPick = next;
       w.resolve(next);
     }
   }
+  lastDeliveredPick = null;
   /** Resolve with the next pick to land OR null on timeout. */
   next(timeoutMs) {
     if (this.picks.length) {
       const next = this.picks.shift();
       this.lastDelivered = next.id;
+      this.lastDeliveredPick = next;
       return Promise.resolve(next);
     }
     return new Promise((resolve2) => {
@@ -120,7 +166,9 @@ function connectToCompanion(session) {
         t: "hello",
         // Pin to the published companion protocol version — bumped
         // when the wire format breaks, NOT for every release.
-        protocolVersion: 4,
+        // v5 added broadcast-ask + subscribers-attached + agent-
+        // ask-external for the external-claude routing flow.
+        protocolVersion: 5,
         token: session.token
       })
     );
@@ -136,6 +184,13 @@ function connectToCompanion(session) {
       ws.send(JSON.stringify({ t: "subscribe" }));
       return;
     }
+    if (m && typeof m === "object" && m.t === "broadcast-ask") {
+      const ask = m;
+      if (typeof ask.bundleId === "string" && typeof ask.text === "string") {
+        buffer.attachAsk(ask.bundleId, ask.text);
+      }
+      return;
+    }
     if (m && typeof m === "object" && m.t === "broadcast-capture") {
       try {
         buffer.push(summariseBundle(m));

package/package.json

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