haltija 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.5.2
+
+Two follow-ups from the 1.5.0 review, both about the multi-tab experience on a shared server.
+
+### Fixed
+
+- **`hj tabs focus <id>` no longer times out** ([#4](https://github.com/tonioloewald/haltija/issues/4)).
+  It was dispatching a `focus` command to the browser, routed to the *focused* tab rather than the
+  target, so nobody answered — and even routed correctly, a backgrounded tab can't raise itself.
+  Focus is now a **server-side** routing change: it validates the tab and points untargeted commands
+  at it, returning instantly (unknown tab → a clean error, never a timeout). It does not physically
+  raise the tab; to pin a single command use `--window <id>`. "Focus follows the visible tab" still
+  applies when you physically switch tabs — that's genuine intent that should win over a stale pin.
+
+### Changed
+
+- **The hidden-tab / focus-ambiguity warnings are de-duplicated within a short (15s) cooldown**, so
+  a burst of commands from one agent doesn't repeat the same block every time. A *changed* condition
+  (different tab, newly-hidden tab, a new origin on the server) always re-warns; the cooldown
+  re-arms rather than suppressing forever. Set `HALTIJA_NO_TAB_WARN=1` to silence them entirely.
+
 ## 1.5.1
 
 Low-risk follow-ups from the 1.5.0 pre-release review — the two new "instrument must not lie"

package/apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija-desktop",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "private": true,
   "description": "Haltija Desktop - God Mode Browser for AI Agents",
   "homepage": "https://github.com/tonioloewald/haltija",

package/apps/desktop/resources/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/bin/tosijs-dev.mjs

@@ -88,6 +88,7 @@ Environment Variables:
   HALTIJA_NO_RETIRE        Set to 1: do not stop pre-1.4.0 haltija servers
   HALTIJA_NO_INSTALL       Set to 1: do not install hj into ~/.local/bin
   HALTIJA_NO_SKEW_WARN     Set to 1: silence hj's version-skew warning
+  HALTIJA_NO_TAB_WARN      Set to 1: silence hidden-tab / focus-ambiguity result warnings
   HALTIJA_REGISTRY_DIR     Instance registry location (default: ~/.haltija/servers)
   DEV_CHANNEL_PORT         Legacy alias for HALTIJA_PORT
   DEV_CHANNEL_HTTPS_PORT   HTTPS port (default: 8701)

package/bin/version.mjs

@@ -3,4 +3,4 @@
  * ⚠️  To change the version, update package.json and run: bun run build
  */
 
-export const HJ_VERSION = '1.5.1'
+export const HJ_VERSION = '1.5.2'

package/dist/api-handlers.d.ts

@@ -52,6 +52,18 @@ export interface HandlerContext {
     headers: Record<string, string>;
     url: URL;
     getWindowInfo: (windowId?: string) => WindowInfo | undefined;
+    /**
+     * Set the server-side focused window — the tab that receives untargeted commands. This is pure
+     * server state, NOT a browser roundtrip: it validates the tab exists and returns immediately, so
+     * it can never time out the way dispatching a command *to* the (possibly hidden) tab does (#4).
+     */
+    focusWindow: (windowId: string) => {
+        ok: boolean;
+        error?: string;
+        active?: boolean;
+        windowType?: string;
+        title?: string;
+    };
     startRecordingSession: (windowId: string, url: string, name?: string) => void;
     stopRecordingSession: (windowId: string) => RecordingSessionInfo | undefined;
     getRecordingSession: (windowId: string) => RecordingSessionInfo | undefined;

package/dist/component.d.ts

@@ -20,7 +20,7 @@
  * - Option+Tab toggles visibility (but active state always shows briefly)
  * - Localhost only by default
  */
-export declare const VERSION = "1.5.1";
+export declare const VERSION = "1.5.2";
 export declare class DevChannel extends HTMLElement {
     static get tagName(): string;
     static elementCreator(): () => DevChannel;

package/dist/component.esm.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.2";
 
 // src/text-selector.ts
 var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/component.js

@@ -46,7 +46,7 @@
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\(/;

package/dist/hj.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-// haltija-cli:do-not-edit v1.5.1
+// haltija-cli:do-not-edit v1.5.2
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
@@ -756,7 +756,7 @@ function substituteGeneratedVars(text, seed) {
 }
 
 // bin/version.mjs
-var HJ_VERSION = "1.5.1";
+var HJ_VERSION = "1.5.2";
 
 // bin/semver.mjs
 function parseVersion(v) {

package/dist/index.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2224,11 +2224,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2242,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2806,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3097,7 +3101,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12857,10 +12861,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12877,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -14252,10 +14260,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -15275,6 +15292,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16129,6 +16162,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16443,6 +16479,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
   return new Promise((resolve) => {
     let sentTo = null;
     const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16452,7 +16490,12 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      return warning ? { ...res, warning } : res;
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -16623,6 +16666,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18300,12 +18352,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

package/dist/server.js

@@ -674,7 +674,7 @@ var injectorCode = `
 `;
 
 // src/version.ts
-var VERSION = "1.5.1";
+var VERSION = "1.5.2";
 
 // src/embedded-assets.ts
 var APP_MD = `# Haltija App
@@ -2224,11 +2224,15 @@ Get window IDs from /windows endpoint.
 
 ### \`POST /tabs/focus\`
 
-**Focus a tab**
+**Focus a tab (route untargeted commands to it)**
 
-Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.
+Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.
 
 **Parameters:**
 
@@ -2238,7 +2242,7 @@ Useful when working with multiple tabs to ensure the right one is visible.
 
 **Examples:**
 
-- **focus**: Bring tab to front
+- **focus**: Route untargeted commands to this tab
   \`\`\`json
   {"window":"window-abc123"}
   \`\`\`
@@ -2802,7 +2806,7 @@ hj --help              # All commands
 - \`hj windows\` - List connected windows
 - \`hj tabs-open [url]\` - Open a new tab
 - \`hj tabs-close [window]\` - Close a tab
-- \`hj tabs-focus [window]\` - Focus a tab
+- \`hj tabs-focus [window]\` - Focus a tab (route untargeted commands to it)
 
 ### Record & Replay
 
@@ -3097,7 +3101,7 @@ var COMPONENT_JS = `(() => {
   });
 
   // src/version.ts
-  var VERSION = "1.5.1";
+  var VERSION = "1.5.2";
 
   // src/text-selector.ts
   var TEXT_PSEUDO_RE = /:(?:text-is|has-text|text)\\(/;
@@ -12857,10 +12861,14 @@ Get window IDs from /windows endpoint.`,
 var tabsFocus = endpoint({
   path: "/tabs/focus",
   method: "POST",
-  summary: "Focus a tab",
-  description: `Desktop app only. Brings the specified tab to front.
-
-Useful when working with multiple tabs to ensure the right one is visible.`,
+  summary: "Focus a tab (route untargeted commands to it)",
+  description: `Make the given tab the target of untargeted commands. This is a server-side
+routing change, NOT a browser action: it does not physically raise the tab (a backgrounded browser
+tab cannot be raised remotely), and because it never dispatches to the tab it can't time out \u2014 even
+if the tab is hidden. After this, commands without a \`window\`/\`--window\` go to this tab until you
+focus another or physically switch tabs in the browser. To pin a single command instead, use
+\`--window <id>\`. If the tab is hidden the response includes a warning (a backgrounded tab's results
+can be stale). Returns \`{ success, focused, active, title }\`.`,
   category: "windows",
   input: L.object({
     window: L.string.describe("Window ID to focus")
@@ -12869,7 +12877,7 @@ Useful when working with multiple tabs to ensure the right one is visible.`,
     {
       name: "focus",
       input: { window: "window-abc123" },
-      description: "Bring tab to front"
+      description: "Route untargeted commands to this tab"
     }
   ],
   hints: "<window-id> | see: windows, tabs-close, tabs-open"
@@ -14252,10 +14260,19 @@ registerHandler(tabsClose, async (body, ctx) => {
 registerHandler(tabsFocus, async (body, ctx) => {
   const windowId = body.window || ctx.targetWindowId;
   if (!windowId) {
-    return Response.json({ success: false, error: "window id is required" }, { status: 400, headers: ctx.headers });
+    return Response.json({ success: false, error: "window id is required (run `hj tabs` to list connected tabs)" }, { status: 400, headers: ctx.headers });
   }
-  const response = await ctx.requestFromBrowser("tabs", "focus", { windowId });
-  return Response.json(response, { headers: ctx.headers });
+  const r = ctx.focusWindow(windowId);
+  if (!r.ok) {
+    return Response.json({ success: false, error: r.error }, { status: 404, headers: ctx.headers });
+  }
+  const result = { success: true, focused: windowId, active: r.active !== false };
+  if (r.title)
+    result.title = r.title;
+  if (r.active === false) {
+    result.warning = "Untargeted commands now route to this tab, but it reports HIDDEN \u2014 browsers freeze " + "requestAnimationFrame and throttle timers in a backgrounded tab, so results can be stale " + '("not mounted yet", not "broken"). Bring it to the front in your browser to wake it.';
+  }
+  return Response.json(result, { headers: ctx.headers });
 });
 registerHandler(mutationsWatch, async (body, ctx) => {
   const response = await ctx.requestFromBrowser("mutations", "watch", {
@@ -15275,6 +15292,22 @@ function ambiguousFocusWarning(opts) {
 ${pins}${more}`;
 }
 
+// src/warning-dedupe.ts
+function shouldEmitWarning(warning, cache, now, cooldownMs) {
+  const last = cache.get(warning);
+  if (last !== undefined && now - last < cooldownMs) {
+    return false;
+  }
+  cache.set(warning, now);
+  if (cache.size > 64) {
+    for (const [key2, ts] of cache) {
+      if (now - ts >= cooldownMs)
+        cache.delete(key2);
+    }
+  }
+  return true;
+}
+
 // src/server.ts
 init_terminal();
 
@@ -16129,6 +16162,9 @@ function getComponentJs() {
 }
 var browsers = new Map;
 var windows2 = new Map;
+var recentTabWarnings = new Map;
+var TAB_WARN_COOLDOWN_MS = 15000;
+var TAB_WARN_DISABLED = process.env.HALTIJA_NO_TAB_WARN === "1";
 var agents = new Set;
 var focusedWindowId = null;
 var isDesktopApp = process.env.HALTIJA_DESKTOP === "1";
@@ -16443,6 +16479,8 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
   return new Promise((resolve) => {
     let sentTo = null;
     const attachWarning = (res) => {
+      if (TAB_WARN_DISABLED)
+        return res;
       const hidden = hiddenTabWarning(sentTo);
       const ambiguous = ambiguousFocusWarning({
         windows: Array.from(windows2.values()),
@@ -16452,7 +16490,12 @@ async function requestFromBrowser(channel, action, payload, timeoutMs = 5000, wi
       const warning = [hidden, ambiguous].filter(Boolean).join(`
 
 `);
-      return warning ? { ...res, warning } : res;
+      if (!warning)
+        return res;
+      if (!shouldEmitWarning(warning, recentTabWarnings, Date.now(), TAB_WARN_COOLDOWN_MS)) {
+        return res;
+      }
+      return { ...res, warning };
     };
     const timeout = setTimeout(() => {
       pendingResponses.delete(id);
@@ -16623,6 +16666,15 @@ var createHandlerContext = (req, url) => {
     headers,
     url,
     getWindowInfo,
+    focusWindow: (windowId) => {
+      const win = windows2.get(windowId);
+      if (!win) {
+        return { ok: false, error: `Tab ${windowId} not found (run \`hj tabs\` to list connected tabs)` };
+      }
+      focusedWindowId = windowId;
+      updateHjStatus();
+      return { ok: true, active: win.active, windowType: win.windowType, title: win.title };
+    },
     startRecordingSession,
     stopRecordingSession,
     getRecordingSession,
@@ -18300,12 +18352,10 @@ Type 'help <topic>' for details.`);
             break;
           }
           case "tabs-focus": {
-            const resp = await requestFromBrowser("tabs", "focus", { windowId: step.window }, stepTimeout);
-            if (!resp.success) {
+            if (!step.window || !windows2.has(step.window)) {
               stepPassed = false;
-              error = resp.error || "Failed to focus tab";
-            }
-            if (step.window && windows2.has(step.window)) {
+              error = `Tab ${step.window ?? "(none)"} not found`;
+            } else {
               focusedWindowId = step.window;
             }
             break;

package/dist/version.d.ts

@@ -8,4 +8,4 @@
  * ⚠️  AUTO-GENERATED FROM package.json - DO NOT EDIT THIS FILE
  * ⚠️  To change the version, update package.json and run: bun run build
  */
-export declare const VERSION = "1.5.1";
+export declare const VERSION = "1.5.2";

package/dist/warning-dedupe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * De-duplicate the tab warnings (hidden-tab #3, focus-ambiguity #2) so a burst of untargeted
+ * commands from one agent doesn't repeat the same multi-line block on every single one. That
+ * repetition is the alarm-fatigue the repo's own skew-warning rationale warns about: a caveat that
+ * fires on every command trains agents to ignore it, including the time it matters.
+ *
+ * **Why a short cooldown and not "once, forever":** the server has many clients and can't tell them
+ * apart, so a permanent global suppression would hide the warning from a *second* agent that never
+ * saw it — the exact "plausible-but-wrong answer with no caveat" failure these warnings exist to
+ * prevent. A short cooldown collapses the one-agent burst (the real fatigue source) while keeping
+ * the window in which another client could miss it tiny; the condition persists, so their next
+ * command past the cooldown re-warns.
+ *
+ * **Why key on the whole warning string:** the text already encodes the full condition — which tab
+ * answered, whether it's hidden, the exact set of other origins. So a *changed* situation (a
+ * different tab, a newly-hidden tab, a new origin on the server) produces different text and is
+ * never suppressed. Identical text means identical situation.
+ */
+export declare function shouldEmitWarning(warning: string, cache: Map<string, number>, now: number, cooldownMs: number): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "haltija",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "description": "Browser control for AI agents - query DOM, click, type, run JS, watch mutations",
   "type": "module",
   "main": "dist/index.js",