qiksy-mcp 1.45.0 → 1.46.0

package/connect.mjs

@@ -131,6 +131,43 @@ export function writeEntry(target, entry) {
   return existed ? 'updated' : 'created';
 }
 
+/**
+ * THE EXACT FINISH SIGNAL, for the one client that can give it.
+ *
+ * `qa_done` makes the tab pulse and the sound play, and the agent is asked to call it. The server
+ * also says it by itself after a long enough silence — but silence is an estimate, and Claude Code
+ * knows the real thing: it fires a `Stop` hook the moment the agent actually stops. One line in
+ * the project's settings turns the estimate into a fact.
+ *
+ * THREE RULES, and they are what makes writing into somebody's settings acceptable at all:
+ *   · everything already in the file survives, including other Stop hooks;
+ *   · running it twice adds nothing — the same command is recognised and left alone;
+ *   · it is reported out loud by the caller, because a command that will run on every stop is not
+ *     something to install quietly.
+ */
+export const STOP_COMMAND = 'npx qiksy-mcp done';
+
+export function stopHookFile(dir) {
+  return join(dir, '.claude', 'settings.json');
+}
+
+export function writeStopHook(file, command = STOP_COMMAND) {
+  const { json, existed } = readConfig(file);
+  const hooks = { ...(json.hooks || {}) };
+  const stop = Array.isArray(hooks.Stop) ? [...hooks.Stop] : [];
+  /* Already there — from a previous run, or written by hand. Adding a second copy would make the
+     browser say «done» twice for one stop. */
+  const has = stop.some((g) =>
+    Array.isArray(g?.hooks) && g.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('qiksy-mcp done')),
+  );
+  if (has) return 'already there';
+  stop.push({ hooks: [{ type: 'command', command }] });
+  hooks.Stop = stop;
+  mkdirSync(join(file, '..'), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ ...json, hooks }, null, 2)}\n`, 'utf8');
+  return existed ? 'updated' : 'created';
+}
+
 /** A port nothing is listening on, starting where the docs say and walking up a short way. */
 export async function freePort(from = 7333, tries = 12) {
   for (let p = from; p < from + tries; p++) {
@@ -173,7 +210,7 @@ export const mintToken = () => randomBytes(18).toString('base64url');
  * Do the whole thing and report what happened. No printing here — the caller owns the voice, and
  * a function that both decides and narrates cannot be tested without reading its output.
  */
-export async function connectAgents({ dir = process.cwd(), home = homedir(), platform = osPlatform(), port, token } = {}) {
+export async function connectAgents({ dir = process.cwd(), home = homedir(), platform = osPlatform(), port, token, hook = true } = {}) {
   const targets = agentTargets({ home, platform, dir });
   const installed = targets.filter((t) => existsSync(t.needs));
   const keptToken = token || tokenInPlace(targets);
@@ -191,6 +228,18 @@ export async function connectAgents({ dir = process.cwd(), home = homedir(), pla
       failed.push({ ...t, error: e.message });
     }
   }
+  /* Only where Claude Code actually is: the hook lives in the same project this just wrote a
+     `.mcp.json` into, and writing one into a folder with no agent in it is litter. */
+  let stopHook = null;
+  if (hook && installed.some((t) => t.id === 'claude-code')) {
+    const file = stopHookFile(dir);
+    try {
+      stopHook = { file, action: writeStopHook(file), command: STOP_COMMAND };
+    } catch (e) {
+      stopHook = { file, error: e.message };
+    }
+  }
+
   return {
     port: usePort,
     token: useToken,
@@ -198,6 +247,7 @@ export async function connectAgents({ dir = process.cwd(), home = homedir(), pla
     entry,
     wrote,
     failed,
+    stopHook,
     skipped: targets.filter((t) => !installed.includes(t)),
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiksy-mcp",
-  "version": "1.45.0",
+  "version": "1.46.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",

package/server.mjs

@@ -723,6 +723,9 @@ async function runConnect(argv, { after = false } = {}) {
       dir: resolve(flag('--dir') || process.cwd()),
       port: Number(flag('--port')) || 0,
       token: flag('--token') || '',
+      /* A hook RUNS A COMMAND every time the agent stops, which is more than an MCP entry does —
+         so there is a way to say no without giving up the rest of the setup. */
+      hook: !argv.includes('--no-hook'),
     });
   } catch (e) {
     console.error(`qiksy-mcp connect: ${e.message}`);
@@ -738,6 +741,14 @@ async function runConnect(argv, { after = false } = {}) {
   }
   for (const w of r.wrote) say(`✓ ${w.action} the qiksy server in ${w.label} → ${w.file}`);
   for (const f of r.failed) console.error(`  could not write ${f.label} → ${f.file}: ${f.error}`);
+  /* SAID OUT LOUD, ALWAYS. This one installs a command that will run on every stop — quietly
+     doing that is how a helpful tool becomes one people distrust. */
+  if (r.stopHook?.error) console.error(`  could not add the finish hook → ${r.stopHook.file}: ${r.stopHook.error}`);
+  else if (r.stopHook) {
+    say(`✓ ${r.stopHook.action} a finish hook in Claude Code → ${r.stopHook.file}`);
+    say(`  It runs \`${r.stopHook.command}\` when the agent stops, so the tab pulses and the sound`);
+    say('  plays the moment a run really ends. Remove that line, or re-run with --no-hook, to skip it.');
+  }
 
   const clip = toClipboard(r.token);
   say(`
@@ -1158,6 +1169,65 @@ function onConnection(ws, req) {
 /** What the person set the panel to — filled in by the first reply that carries it. */
 let uiLanguage = '';
 
+/**
+ * THE END OF A RUN, WITHOUT ANYBODY HAVING TO REMEMBER IT.
+ *
+ * `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).
+ *
+ * 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.
+ *
+ * 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.
+ */
+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;
+})();
+let doneTimer = null;
+let workSinceDone = false;
+
+function fireDone() {
+  doneTimer = null;
+  if (!workSinceDone) 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(() => {});
+}
+
+/** 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 (doneTimer) clearTimeout(doneTimer);
+  doneTimer = null;
+  if (tool === 'qa_done') {
+    /* Said out loud already — nothing left to announce until there is new work. */
+    workSinceDone = false;
+    return;
+  }
+  workSinceDone = true;
+  doneTimer = setTimeout(fireDone, DONE_AFTER_MS);
+  /* A pending timer must never be the reason this process stays alive. */
+  doneTimer.unref?.();
+}
+
 function callExtension(tool, args, timeoutMs = 15_000) {
   // The same choke point is where the voice watches the session: one place, both roles.
   noticedCall(tool);
@@ -1165,6 +1235,7 @@ function callExtension(tool, args, timeoutMs = 15_000) {
     p.then(
       (r) => {
         noticedResult(tool, r);
+        armDone(tool);
         /* THE HUMAN'S LANGUAGE, learned rather than guessed. This process never sees the
            conversation, so it cannot know what language they write in — but they told the panel
            directly by choosing one, and the extension sends that along with every bundle. One
@@ -1175,6 +1246,9 @@ function callExtension(tool, args, timeoutMs = 15_000) {
       },
       (e) => {
         noticedResult(tool, null);
+        /* A call that FAILED is still the agent having been here — the run is just as over when
+           the last thing it did did not work. */
+        armDone(tool);
         throw e;
       },
     );