qiksy-mcp 1.63.0 → 1.65.0

package/open-tab.mjs

@@ -0,0 +1,165 @@
+/**
+ * OPENING A TAB IN THE BROWSER THE BRIDGE IS ACTUALLY CONNECTED TO.
+ *
+ * The bridge refuses to navigate a tab onto a foreign domain, and that refusal is correct: it is
+ * the thing that stops an agent from walking somebody's browser wherever it likes. But the way
+ * OUT of that dead end lived nowhere near the product — it was a shell trick written down in one
+ * person's instructions, so every fresh agent rediscovered the dead end and stopped there
+ * (owner, 30.09.2026: «постоянно возникает вопрос, он говорит, что я не нахожу таб»).
+ *
+ * THE PROFILE IS THE WHOLE DIFFICULTY, AND ANCHORING IS WHAT REMOVES IT. A machine has several
+ * Chrome profiles; the extension lives in exactly one, and a tab opened anywhere else is invisible
+ * to the bridge — every reading afterwards is then about a tab nobody can see. Naming the profile
+ * does not work: a running Chrome silently ignores `--profile-directory`, the command still exits
+ * 0, and the tab still lands elsewhere. There is no error to diagnose.
+ *
+ * So this never names a profile. It takes a tab the bridge ALREADY SEES, finds the window holding
+ * it, and inserts the new tab beside it. Same window, therefore same profile, therefore visible —
+ * by construction rather than by care.
+ */
+import { spawnSync } from 'node:child_process';
+
+/**
+ * ONLY http AND https. `file://` hands an agent the local disk through a browser and
+ * `javascript:` hands it the page it lands on; neither is «open a site», and a verb that accepts
+ * them is a different, much larger verb wearing this one's name.
+ */
+export function safeUrl(raw) {
+  let u;
+  try {
+    u = new URL(String(raw ?? '').trim());
+  } catch {
+    return null;
+  }
+  return u.protocol === 'http:' || u.protocol === 'https:' ? u.toString() : null;
+}
+
+/**
+ * The anchor: the ORIGIN of a tab the bridge can see. An origin rather than a whole address
+ * because the address moves — a single-page app rewrites its path as the person clicks, and an
+ * anchor that has to match what was there a second ago is an anchor that misses.
+ */
+export function anchorFrom(tabs) {
+  for (const t of Array.isArray(tabs) ? tabs : []) {
+    try {
+      const u = new URL(String(t?.url || ''));
+      if (u.protocol === 'http:' || u.protocol === 'https:') return u.origin;
+    } catch {
+      /* a tab with no readable address is simply not an anchor */
+    }
+  }
+  return null;
+}
+
+/* AppleScript string literals take the same two escapes as C. The script goes in on stdin rather
+   than through `-e`, so the SHELL never sees the address: an OAuth redirect full of & and % is
+   exactly the kind of URL this is for, and quoting it for a shell is where that goes wrong. */
+const esc = (s) => String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+
+export function appleScript({ anchor, url, app = 'Google Chrome' }) {
+  return `tell application "${esc(app)}"
+  set wi to 0
+  repeat with w in windows
+    set wi to wi + 1
+    repeat with t in tabs of w
+      if (URL of t) contains "${esc(anchor)}" then
+        make new tab at end of tabs of w with properties {URL:"${esc(url)}"}
+        set active tab index of w to (count of tabs of w)
+        return "opened in window " & wi
+      end if
+    end repeat
+  end repeat
+  return "no window holds the anchor"
+end tell`;
+}
+
+/** Runs the script. Separated so the gate can drive every branch without a browser on the machine. */
+export function runAppleScript(script) {
+  const r = spawnSync('osascript', ['-'], { input: script, encoding: 'utf8', timeout: 15_000 });
+  if (r.error) return { ok: false, said: String(r.error.message || r.error) };
+  const said = String(r.stdout || '').trim() || String(r.stderr || '').trim();
+  return { ok: r.status === 0 && /^opened in window/.test(said), said };
+}
+
+/**
+ * The whole verb, with the platform check and both ways it can legitimately fail.
+ *
+ * `tabsNow` returns the bridge's current tab list; it is asked TWICE on purpose — once for the
+ * anchor, once to find out what actually happened. A command that exits 0 proves the script ran,
+ * not that a tab the bridge can see now exists, and those are the two facts that get confused.
+ */
+export async function openTabHere({
+  url,
+  tabsNow,
+  platform = process.platform,
+  run = runAppleScript,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  tries = 8,
+}) {
+  const clean = safeUrl(url);
+  if (!clean) return { ok: false, error: 'bad-url', note: 'Only http:// and https:// addresses can be opened this way.' };
+
+  const before = await tabsNow();
+  const anchor = anchorFrom(before);
+  if (!anchor) {
+    return {
+      ok: false,
+      error: 'no-anchor',
+      note:
+        'The bridge can see no tab at all, so there is no window to open this beside — and opening it anywhere else would put it in a Chrome profile the extension does not live in, where nothing you do next is visible. Ask the person to open any page in the browser that has Qiksy in it, then call this again.',
+    };
+  }
+
+  if (platform !== 'darwin') {
+    return {
+      ok: false,
+      error: 'not-on-this-platform',
+      anchor,
+      note: `Opening a tab this way is macOS-only for now. Ask the person to open ${clean} themselves in the browser that has Qiksy in it — any other browser or profile is invisible to the bridge.`,
+    };
+  }
+
+  const said = run(appleScript({ anchor, url: clean }));
+  if (!said.ok) {
+    return {
+      ok: false,
+      error: 'could-not-open',
+      anchor,
+      said: said.said,
+      note: 'The browser did not take the new tab. If this says the anchor was not found, the window holding it was probably closed between the two steps.',
+    };
+  }
+
+  /* WAIT FOR THE TAB TO BE VISIBLE TO THE BRIDGE, not for a number of milliseconds: a page that
+     is still loading has no address the extension reports yet, and answering before it does would
+     hand back «opened, and I cannot see it», which reads as a failure. */
+  const wantOrigin = new URL(clean).origin;
+  const knownIds = new Set((before || []).map((t) => t.tabId));
+  let fresh = null;
+  for (let i = 0; i < tries && !fresh; i++) {
+    await sleep(600);
+    const now = await tabsNow();
+    fresh = (now || []).find((t) => !knownIds.has(t.tabId)) || null;
+    if (!fresh) fresh = (now || []).find((t) => String(t.url || '').startsWith(wantOrigin) && !knownIds.has(t.tabId)) || null;
+  }
+
+  if (fresh) {
+    return { ok: true, tabId: fresh.tabId, url: fresh.url, inSession: true, said: said.said, note: 'The tab is open and the bridge can act on it. Pass this tabId to the other verbs.' };
+  }
+
+  /**
+   * OPENED, BUT NOT IN THE SESSION — and this is the ordinary case rather than a fault.
+   *
+   * The active tab counts as the session only while NOTHING has been attached; the moment a person
+   * has switched «Agent drives this tab» on anywhere, the session is that explicit set and a new
+   * tab is not in it. Reporting «opened» and stopping would leave the agent measuring a tab it
+   * cannot see and blaming the bridge, which is the exact failure this verb was built to end.
+   */
+  return {
+    ok: true,
+    tabId: null,
+    inSession: false,
+    said: said.said,
+    note: `The tab is open in the right browser, but it is not in the agent's session: once any tab has been switched on for the agent, the session is that explicit set and a new tab does not join it by itself. Ask the person to switch «Agent drives this tab» on for ${wantOrigin} — reading and driving both start working the moment they do.`,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.63.0",
+  "version": "1.65.0",
   "description": "Browser MCP server for the Chrome tab you already have open — your session, your logins. Gives Claude Code, Cursor, Codex and VS Code the live page: findings, forms, failed requests with server bodies.",
   "keywords": [
     "mcp",
@@ -34,6 +34,7 @@
     "project.mjs",
     "gaps.mjs",
     "reports.mjs",
+    "open-tab.mjs",
     "gallery.mjs",
     "svg-shot.mjs",
     "connect.mjs",

package/server.mjs

@@ -35,6 +35,7 @@ import { LIBRARIES, datePlan, hintsFor, recipeFor, classifyNode, classifySnapsho
 import { project } from './project.mjs';
 import { recordGap, listGaps, gapInvite, GAPS_FILE } from './gaps.mjs';
 import { reportsDir, reportFileName } from './reports.mjs';
+import { openTabHere } from './open-tab.mjs';
 import { STATES, STATE_KEYS, renderGallery } from './gallery.mjs';
 import { renderSearchableSvg } from './svg-shot.mjs';
 import { connectAgents, toClipboard, pairingInPlace } from './connect.mjs';
@@ -1292,6 +1293,11 @@ function onConnection(ws, req) {
     // answer back under the follower's own id. Ours is a fresh randomUUID, so the two
     // id spaces cannot collide.
     if (msg.t === 'req' && isFollower) {
+      /* A REAL full stop from a sibling window or from `npx qiksy-mcp done` — the Stop hook's
+         route into this process. Our OWN estimate travels the same way when a follower guesses,
+         which is why the flag it carries is checked here: a guess must not teach the hub that
+         this setup reports its endings. */
+      if (msg.tool === 'qa_done' && !msg.args?.guessed) noteRealDone();
       callExtension(msg.tool, msg.args, msg.timeoutMs)
         .then((result) => safeSend(ws, { t: 'res', id: msg.id, ok: true, result }))
         .catch((err) => safeSend(ws, { t: 'res', id: msg.id, ok: false, error: err?.message || String(err) }));
@@ -1315,51 +1321,69 @@ function onConnection(ws, req) {
 let uiLanguage = '';
 
 /**
- * THE END OF A RUN, WITHOUT ANYBODY HAVING TO REMEMBER IT.
+ * GUESSING THE END OF A RUN — OFF BY DEFAULT SINCE 1.64.0, AND THE REASON IS WORTH KEEPING.
  *
- * `qa_done` is the verb that makes the tab pulse and the sound play, and the agent is asked to
- * call it in the instructions handed over at connect. An instruction is a request, though, not a
- * mechanism: some clients follow it, some do not, and every agent already installed has the old
- * habit. So the person updates, everything is switched on by default — and hears nothing. That is
- * the state this exists to prevent (owner, 21.09.2026).
+ * It was added on 21.09.2026 to cover clients that never call `qa_done`: the person updates,
+ * everything is on, and they hear nothing. The guess is silence — no bridge call for a while means
+ * the run is over — and it was defended as safe to be wrong, because a later call cancels the
+ * pulse and the extension refuses to sound twice in half a minute.
  *
- * What this process CAN observe is the same thing the voice already watches: it timestamps every
- * call and knows when the last one finished. A run that did real work and then went quiet past a
- * threshold is over in every sense that matters to somebody in the next room.
+ * THAT DEFENCE ONLY COVERED THE PULSE. A sound cannot be cancelled after it has been heard, and
+ * the silence it keys on is not silence at all: an agent that walked away from the browser to read
+ * files, edit code or think makes no bridge call for MINUTES while working flat out. So the signal
+ * arrived mid-run, and again on the next lull, and again — which is exactly what the owner
+ * reported hearing (28.09.2026: «звук отрабатывает, а агент продолжает маслать… QADone несколько
+ * раз отрабатывает, то есть он не по окончанию»). His ruling covers the mark as well as the
+ * sound: both announce the END of a task, so neither may fire on a guess.
  *
- * IT IS AN ESTIMATE, AND IT IS BUILT TO BE WRONG SAFELY. Three things make a premature signal
- * cheap rather than annoying, and none of them are new — they all shipped with the verb:
- *   · the extension refuses to sound when no work has been recorded;
- *   · it refuses to sound twice within half a minute;
- *   · ANY later call stops the pulse, so an agent that was merely thinking cancels the signal by
- *     carrying on — the mistake undoes itself without anybody touching anything.
- * The exact path — a Stop hook running `npx qiksy-mcp done` — stays available for clients that
- * have one, and is what `init` writes. This is the floor under it, not a replacement.
+ * A signal that is right most of the time is worse than no signal, because it is learned as noise
+ * and then switched off — taking the true ones with it.
+ *
+ * WHAT REPLACES IT IS NOT NOTHING. Two routes report a real full stop, and `connect` writes the
+ * second one into the client's settings, so an ordinary install has it:
+ *   · the agent calling `qa_done` itself, which every client is told about at `initialize`;
+ *   · a Stop hook running `npx qiksy-mcp done`, which fires whether or not the model remembered.
+ * The guess survives as an opt-in for a client that has neither: `QIKSY_MCP_DONE_AFTER=<seconds>`.
  */
 const DONE_AFTER_MS = (() => {
   const raw = process.env.QIKSY_MCP_DONE_AFTER;
-  if (raw === '0' || /^(off|no|false)$/i.test(raw || '')) return 0;
   const n = Number(raw);
   /* Below twenty seconds this would fire inside an ordinary pause for thought, so a smaller
-     number is read as a mistake and the default is used instead. */
-  return Number.isFinite(n) && n >= 20 ? n * 1000 : 90_000;
+     number is refused rather than honoured. Anything else, including nothing at all, is off. */
+  return Number.isFinite(n) && n >= 20 ? n * 1000 : 0;
 })();
 let doneTimer = null;
 let workSinceDone = false;
+/**
+ * A SETUP THAT REPORTS ITS OWN FULL STOP NEEDS NO GUESS, and the guess is the part that can be
+ * wrong. One real `qa_done` proves this client has a working route, so the estimate stands down
+ * for the rest of the process — nobody has to notice that they opted into both.
+ */
+let realDoneSeen = false;
+
+/** Called where a REAL full stop enters this process, and nowhere else — never from `fireDone`. */
+function noteRealDone() {
+  if (realDoneSeen) return;
+  realDoneSeen = true;
+  if (doneTimer) clearTimeout(doneTimer);
+  doneTimer = null;
+  workSinceDone = false;
+  if (DONE_AFTER_MS) log('▸ this setup announces the end of a run itself — the quiet-timer guess is off from here on');
+}
 
 function fireDone() {
   doneTimer = null;
-  if (!workSinceDone) return;
+  if (!workSinceDone || realDoneSeen) return;
   workSinceDone = false;
   log(`▸ quiet for ${Math.round(DONE_AFTER_MS / 1000)}s after a run — saying it has finished`);
   /* Failure here is nothing: the browser may have gone, the tab may have closed. The pulse is a
      courtesy, and a courtesy that throws is worse than one that does not happen. */
-  callExtension('qa_done', { verdict: 'ok' }, 8_000).catch(() => {});
+  callExtension('qa_done', { verdict: 'ok', guessed: true }, 8_000).catch(() => {});
 }
 
 /** Called when a call FINISHES, not when it starts: a slow verb must not look like silence. */
 function armDone(tool) {
-  if (!DONE_AFTER_MS) return;
+  if (!DONE_AFTER_MS || realDoneSeen) return;
   if (doneTimer) clearTimeout(doneTimer);
   doneTimer = null;
   if (tool === 'qa_done') {
@@ -1543,12 +1567,20 @@ function stuckHelp(text) {
         };
   }
   if (kind === 'scope') {
+    /* THE DEAD END HAS TO NAME ITS OWN WAY OUT. This refusal used to end at «open it in a tab
+       yourself», and the only reliable way to do that — anchoring on a window the bridge can
+       already see — lived in one person's notes rather than in the product. So every fresh agent
+       rediscovered the dead end and stopped there, and the person watching saw the bridge give up
+       (owner, 30.09.2026). `qa_open_tab` is that way out, and it belongs in the answer that
+       refuses, not two hundred lines up in a manual read once at initialize. */
     return brief
-      ? { stayHere: 'Ask the human to attach the tab (right-click → "Qiksy — test this tab"). Do not reach around it with another driver.' }
+      ? { nextCall: 'qa_open_tab { url } — a NEW tab in their own browser, beside the ones already open. Do not reach around this with another driver.' }
       : {
           whyThisHappened: 'The agent session is a SET of tabs the human opted into. This one is not in it — by design, so nothing you do can wander into their mail or bank.',
-          nextCall: 'qa_tabs — see what IS attached; a tab opened BY an attached tab joins automatically.',
-          sayThis: 'Ask them to attach it: the popup switch "Agent drives this tab", or right-click on the page → "Qiksy — test this tab".',
+          nextCall:
+            'qa_open_tab { url } opens the address as a NEW tab in the very browser this bridge is connected to, losing nothing. Or qa_tabs to see what IS attached; a tab opened BY an attached tab joins automatically.',
+          sayThis:
+            'If the new tab comes back with inSession:false, ask them to attach it: the popup switch "Agent drives this tab", or right-click on the page → "Qiksy — test this tab".',
           stayHere: 'Do not open the page in another driver to get around the boundary — that browser has none of their sessions in it anyway.',
         };
   }
@@ -4844,6 +4876,32 @@ server.registerTool(
  * A shot is addressed by NAME («checkout»), never by «the last one»: there is no implicit current
  * shot, so marking the wrong picture is not a mistake that can be made by default.
  */
+server.registerTool(
+  'qa_open_tab',
+  {
+    title: 'Open a page in the browser the bridge is connected to',
+    description:
+      'OPEN AN ADDRESS THE BRIDGE WILL NOT NAVIGATE TO. The driving verbs stay inside the site under test on purpose — that refusal is what stops an agent from walking somebody\'s browser onto an arbitrary domain, and it must not be worked around. This is the sanctioned way through it: a NEW tab, beside the ones already open, losing nothing. ' +
+      'It goes into the RIGHT BROWSER by construction, not by care: the machine has several Chrome profiles, the extension lives in exactly one, and a tab opened into any other is invisible here — so this finds the window holding a tab the bridge can already see and inserts the new one beside it. Never start a browser yourself instead; a second browser is a DIFFERENT, EMPTY browser with none of the person\'s logins, and everything measured in it stops being the run that was asked for. ' +
+      'Read the answer rather than assuming: `inSession: true` means the tab is yours to drive and carries the tabId to pass to the other verbs; `inSession: false` means it is open and the person has to switch «Agent drives this tab» on for it, because once any tab has been switched on the session is that explicit set. macOS for now; elsewhere it says so and names what to ask for. Free.',
+    inputSchema: {
+      url: z.string().describe('The full http(s) address to open. Query strings are fine — nothing here goes through a shell.'),
+    },
+  },
+  async ({ url }, extra) => {
+    const bar = loader(extra, 'opening a tab');
+    try {
+      const tabsNow = async () => {
+        const r = await callExtension('qa_tabs', {}, 15_000).catch(() => null);
+        return Array.isArray(r?.tabs) ? r.tabs : [];
+      };
+      return asText(await openTabHere({ url, tabsNow }));
+    } finally {
+      bar.stop();
+    }
+  },
+);
+
 server.registerTool(
   'qa_shot_list',
   {
@@ -7147,6 +7205,8 @@ server.registerTool(
   },
   async ({ tabId, verdict }) => {
     try {
+      /* The agent said it itself — the one route that needs no guessing behind it. */
+      noteRealDone();
       return asText(await callExtension('qa_done', { tabId, verdict }, 15_000));
     } catch (e) {
       /* The verb lives in the EXTENSION, which updates on the Web Store's clock while this server