@jobshimo/browser-link 0.5.1 → 0.5.3

package/dist/tools/browser-dispatch.d.ts

@@ -4,15 +4,37 @@
  * runServer().
  *
  * The handlers do not own state: they receive a `BrowserToolDeps` object
- * with the live tab map and the call function. This makes the dispatcher
- * unit-testable with a fake `callBrowserTool`.
+ * with the live tab map, the call function, and the claim registry. This
+ * makes the dispatcher unit-testable with a fake `callBrowserTool` and a
+ * fresh `TabClaimRegistry`.
+ *
+ * Each invocation also receives an `AgentCaller` so claim/ownership
+ * decisions can be made per request. The bridge layers (primary's stdio
+ * handler + IPC server) are responsible for supplying it.
  */
 import type { BridgeEvent } from '../bridge/events.js';
+import { type AgentCaller, type TabClaimRegistry } from './tab-claims.js';
 export interface TabSnapshot {
     tab_id: string;
     url: string;
     title: string;
 }
+/** Public view of a TabClaim — what other agents and the user are allowed to see.
+ * Keeps the wire payload stable even if the internal `TabClaim` grows fields. */
+export interface PublicClaim {
+    tab_id: string;
+    agent_id: string;
+    pid: number;
+    binary: string;
+    label?: string;
+    claimed_at: number;
+    last_activity_at: number;
+    ttl_ms: number;
+}
+export interface EnrichedTabSnapshot extends TabSnapshot {
+    claimed_by: PublicClaim | null;
+    claimed_by_me: boolean;
+}
 export interface BrowserToolDeps {
     listTabs(): TabSnapshot[];
     callBrowserTool(tabId: string, tool: string, params: unknown, timeoutMs?: number): Promise<unknown>;
@@ -22,6 +44,20 @@ export interface BrowserToolDeps {
         sinceId?: number;
         limit?: number;
     }): BridgeEvent[];
+    /** Claim registry. Optional so existing test fixtures keep compiling — when
+     * absent the dispatcher behaves as before (no enforcement, list_tabs
+     * returns claimed_by:null for every tab). */
+    tabClaims?: TabClaimRegistry;
 }
 export declare function isBrowserTool(name: string): boolean;
-export declare function handleBrowserTool(name: string, args: unknown, deps: BrowserToolDeps): Promise<unknown>;
+/**
+ * Dispatch a browser tool call.
+ *
+ * The switch is intentional: every reachable arm is matched against the
+ * closed `BrowserToolName` literal union, so the `name` string can only
+ * reach a known handler (or fall through to the `default` throw). This
+ * pattern is what CodeQL's `js/unvalidated-dynamic-method-call` accepts as
+ * a fixed allowlist — a Map-of-handlers lookup looks identical at runtime
+ * but is flagged because the static analyser can't prove the bound.
+ */
+export declare function handleBrowserTool(name: string, args: unknown, deps: BrowserToolDeps, caller: AgentCaller): Promise<unknown>;

package/dist/tools/browser-dispatch.js

@@ -4,83 +4,190 @@
  * runServer().
  *
  * The handlers do not own state: they receive a `BrowserToolDeps` object
- * with the live tab map and the call function. This makes the dispatcher
- * unit-testable with a fake `callBrowserTool`.
+ * with the live tab map, the call function, and the claim registry. This
+ * makes the dispatcher unit-testable with a fake `callBrowserTool` and a
+ * fresh `TabClaimRegistry`.
+ *
+ * Each invocation also receives an `AgentCaller` so claim/ownership
+ * decisions can be made per request. The bridge layers (primary's stdio
+ * handler + IPC server) are responsible for supplying it.
  */
 import { requireTabId } from './responses.js';
+import { formatClaimConflict, } from './tab-claims.js';
+/** Closed set of browser tool names. Used both as the discriminant in
+ * `handleBrowserTool`'s switch and as the allowlist behind `isBrowserTool`,
+ * so adding a tool requires touching one place. The literal-union type lets
+ * TypeScript prove the switch is exhaustive at compile time. */
+const BROWSER_TOOL_NAMES = [
+    'browser.list_tabs',
+    'browser.claim_tab',
+    'browser.release_tab',
+    'browser.my_tabs',
+    'browser.ping',
+    'browser.navigate',
+    'browser.snapshot',
+    'browser.console',
+    'browser.network',
+    'browser.network_body',
+    'browser.click',
+    'browser.type',
+    'browser.evaluate',
+    'browser.events',
+];
+const BROWSER_TOOL_NAME_SET = new Set(BROWSER_TOOL_NAMES);
 export function isBrowserTool(name) {
-    return name === 'browser.list_tabs' || BROWSER_TOOL_HANDLERS.has(name);
+    return BROWSER_TOOL_NAME_SET.has(name);
 }
 const NAVIGATE_TIMEOUT_MS = 30_000;
-const BROWSER_TOOL_HANDLERS = new Map([
-    ['browser.list_tabs', (_args, deps) => deps.listTabs()],
-    ['browser.ping', (args, deps) => deps.callBrowserTool(requireTabId(args), 'ping', {})],
-    [
-        'browser.navigate',
-        (args, deps) => {
+/** Convert an internal TabClaim into the wire-safe `PublicClaim`. */
+function toPublicClaim(claim) {
+    const publicClaim = {
+        tab_id: claim.tab_id,
+        agent_id: claim.agent_id,
+        pid: claim.pid,
+        binary: claim.binary,
+        claimed_at: claim.claimed_at,
+        last_activity_at: claim.last_activity_at,
+        ttl_ms: claim.ttl_ms,
+    };
+    if (claim.label !== undefined)
+        publicClaim.label = claim.label;
+    return publicClaim;
+}
+/** Run an action through the claim registry. Returns the response payload of
+ * the action when the agent is allowed, or throws a descriptive Error otherwise.
+ * When no registry is wired (test fixtures, or future configs that disable
+ * coordination), behaves like the pre-claim dispatcher. */
+async function runAction(tool, tabId, params, deps, caller, timeoutMs) {
+    if (deps.tabClaims) {
+        const outcome = deps.tabClaims.ensureActionAllowed(tabId, caller);
+        if (!outcome.ok) {
+            throw new Error(formatClaimConflict(caller, outcome.existing));
+        }
+    }
+    // Preserve the pre-claim call shape — only forward timeoutMs when set so
+    // existing assertions and the bridge's default behaviour stay unchanged.
+    return timeoutMs !== undefined
+        ? deps.callBrowserTool(tabId, tool, params, timeoutMs)
+        : deps.callBrowserTool(tabId, tool, params);
+}
+function handleListTabs(deps, caller) {
+    return deps.listTabs().map((t) => {
+        const claim = deps.tabClaims?.getClaim(t.tab_id) ?? null;
+        return {
+            ...t,
+            claimed_by: claim ? toPublicClaim(claim) : null,
+            claimed_by_me: claim ? claim.agent_id === caller.agent_id : false,
+        };
+    });
+}
+function handleClaimTab(args, deps, caller) {
+    const { tab_id, ttl_minutes, label } = (args ?? {});
+    if (!tab_id)
+        throw new Error('tab_id required');
+    if (!deps.tabClaims) {
+        return {
+            ok: false,
+            reason: 'unsupported',
+            message: 'Tab coordination is disabled in this build of browser-link.',
+        };
+    }
+    const outcome = deps.tabClaims.claim(tab_id, caller, { ttlMinutes: ttl_minutes, label });
+    if (!outcome.ok) {
+        return { ok: false, reason: outcome.reason, existing: toPublicClaim(outcome.existing) };
+    }
+    return { ok: true, created: outcome.created, claim: toPublicClaim(outcome.claim) };
+}
+function handleReleaseTab(args, deps, caller) {
+    const tab_id = requireTabId(args);
+    if (!deps.tabClaims)
+        return { ok: true };
+    const result = deps.tabClaims.release(tab_id, caller);
+    if (result.ok)
+        return { ok: true };
+    const payload = { ok: false, reason: result.reason };
+    if (result.existing)
+        payload.existing = toPublicClaim(result.existing);
+    return payload;
+}
+function handleMyTabs(deps, caller) {
+    if (!deps.tabClaims)
+        return { claims: [] };
+    return { claims: deps.tabClaims.myTabs(caller).map(toPublicClaim) };
+}
+function handleEvents(args, deps) {
+    const { since_id, limit } = args ?? {};
+    if (!deps.recentEvents)
+        return { events: [], latest_id: 0 };
+    const events = deps.recentEvents({ sinceId: since_id, limit });
+    const latest_id = events.length > 0 ? events[events.length - 1].id : (since_id ?? 0);
+    return { events, latest_id };
+}
+/**
+ * Dispatch a browser tool call.
+ *
+ * The switch is intentional: every reachable arm is matched against the
+ * closed `BrowserToolName` literal union, so the `name` string can only
+ * reach a known handler (or fall through to the `default` throw). This
+ * pattern is what CodeQL's `js/unvalidated-dynamic-method-call` accepts as
+ * a fixed allowlist — a Map-of-handlers lookup looks identical at runtime
+ * but is flagged because the static analyser can't prove the bound.
+ */
+export async function handleBrowserTool(name, args, deps, caller) {
+    if (!isBrowserTool(name))
+        throw new Error(`Unknown browser tool: ${name}`);
+    const toolName = name;
+    switch (toolName) {
+        case 'browser.list_tabs':
+            return handleListTabs(deps, caller);
+        case 'browser.claim_tab':
+            return handleClaimTab(args, deps, caller);
+        case 'browser.release_tab':
+            return handleReleaseTab(args, deps, caller);
+        case 'browser.my_tabs':
+            return handleMyTabs(deps, caller);
+        case 'browser.ping':
+            return deps.callBrowserTool(requireTabId(args), 'ping', {});
+        case 'browser.navigate': {
             const { url, wait_for_load = true } = args;
-            return deps.callBrowserTool(requireTabId(args), 'navigate', { url, wait_for_load }, NAVIGATE_TIMEOUT_MS);
-        },
-    ],
-    ['browser.snapshot', (args, deps) => deps.callBrowserTool(requireTabId(args), 'snapshot', {})],
-    [
-        'browser.console',
-        (args, deps) => {
+            return runAction('navigate', requireTabId(args), { url, wait_for_load }, deps, caller, NAVIGATE_TIMEOUT_MS);
+        }
+        case 'browser.snapshot':
+            return deps.callBrowserTool(requireTabId(args), 'snapshot', {});
+        case 'browser.console': {
             const { level } = args ?? {};
             return deps.callBrowserTool(requireTabId(args), 'console', { level });
-        },
-    ],
-    [
-        'browser.network',
-        (args, deps) => {
+        }
+        case 'browser.network': {
             const { url_filter } = args ?? {};
             return deps.callBrowserTool(requireTabId(args), 'network', { url_filter });
-        },
-    ],
-    [
-        'browser.network_body',
-        (args, deps) => {
+        }
+        case 'browser.network_body': {
             const { request_id } = args;
             return deps.callBrowserTool(requireTabId(args), 'network_body', { request_id });
-        },
-    ],
-    [
-        'browser.click',
-        (args, deps) => {
+        }
+        case 'browser.click': {
             const { selector } = args;
-            return deps.callBrowserTool(requireTabId(args), 'click', { selector });
-        },
-    ],
-    [
-        'browser.type',
-        (args, deps) => {
+            return runAction('click', requireTabId(args), { selector }, deps, caller);
+        }
+        case 'browser.type': {
             const { selector, text, clear = false, } = args;
-            return deps.callBrowserTool(requireTabId(args), 'type', { selector, text, clear });
-        },
-    ],
-    [
-        'browser.evaluate',
-        (args, deps) => {
+            return runAction('type', requireTabId(args), { selector, text, clear }, deps, caller);
+        }
+        case 'browser.evaluate': {
             const { expression } = args;
-            return deps.callBrowserTool(requireTabId(args), 'evaluate', { expression });
-        },
-    ],
-    [
-        'browser.events',
-        (args, deps) => {
-            const { since_id, limit } = args ?? {};
-            if (!deps.recentEvents)
-                return { events: [], latest_id: 0 };
-            const events = deps.recentEvents({ sinceId: since_id, limit });
-            const latest_id = events.length > 0 ? events[events.length - 1].id : (since_id ?? 0);
-            return { events, latest_id };
-        },
-    ],
-]);
-export async function handleBrowserTool(name, args, deps) {
-    const handler = BROWSER_TOOL_HANDLERS.get(name);
-    if (!handler)
-        throw new Error(`Unknown browser tool: ${name}`);
-    return handler(args, deps);
+            return runAction('evaluate', requireTabId(args), { expression }, deps, caller);
+        }
+        case 'browser.events':
+            return handleEvents(args, deps);
+        default: {
+            // The earlier `isBrowserTool(name)` check makes this branch unreachable
+            // for any value within `BrowserToolName`. The exhaustive cast surfaces a
+            // compile error if a future tool name is added to the union but missed
+            // here.
+            const _exhaustive = toolName;
+            throw new Error(`Unhandled browser tool: ${String(_exhaustive)}`);
+        }
+    }
 }
 //# sourceMappingURL=browser-dispatch.js.map

package/dist/tools/browser-dispatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser-dispatch.js","sourceRoot":"","sources":["../../src/tools/browser-dispatch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-dispatch.js","sourceRoot":"","sources":["../../src/tools/browser-dispatch.ts"],"names":[],"mappings":"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"}

package/dist/tools/server-instructions.d.ts

@@ -1,3 +1,3 @@
 /** Usage protocol pushed to the MCP client on `initialize`. Plain string,
  * intentionally kept short. Edit here when the protocol changes. */
-export declare const SERVER_INSTRUCTIONS = "browser-link bridges Claude Code to the Chrome tabs the user has\nexplicitly connected through the companion extension, and ships a\npersistent UI map backed by a local SQLite DB. The data dir resolves\nper-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,\n~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link\non Windows). Override with $BROWSER_LINK_DATA_DIR. The map is private\nand per-machine; never persisted in any repo.\n\n## When operating on a tab\n\n1. Before doing anything on a tab whose URL you don't already know,\n   call `browser.map.recall` with { origin } (and optionally url) to load\n   selectors, flows and gotchas previously learned for that app.\n2. If recall returns entries with `failed_at` more recent than\n   `verified_at`, treat them as suspect: re-verify (snapshot / evaluate)\n   before reusing, or replace them.\n3. After every interaction that used a map entry, call\n   `browser.map.record_use` with { entry_id, ok }. ok=true updates\n   verified_at; ok=false updates failed_at. Keep the map honest.\n4. After a non-trivial flow that worked end-to-end, persist it with\n   `browser.map.save`. Three `kind` values:\n   - selector: { selector, evidence? } \u2014 a CSS selector tied to a purpose.\n   - flow: { steps: [...] } \u2014 an ordered list of actions to reach an outcome.\n   - gotcha: { body } \u2014 free-form note about something non-obvious.\n   Use `url_pattern` = pathname (exact). Promote to glob only if you have\n   evidence of a parametric route. Provide `purpose` as a stable, reusable\n   label (\"open task detail dialog\", not \"open IB0311 detail\").\n5. Never save selectors or flows you have not just successfully executed.\n6. Never store domain data (IDs, user names, dates, etc.). The map captures\n   UI structure only.\n\n## Identifying the app\n\n- `origin` = scheme://host:port of the tab.\n- `app_key` distinguishes apps that share an origin over time. On first\n  save you may omit it; it will be derived from the page title (slugified).\n  Use `browser.map.rename_app` if that initial guess is poor.\n\n## When something is wrong\n\n- A selector from recall fails \u2192 record_use({ok:false}), learn the new\n  one, save it (upsert on purpose).\n- A whole app got refactored \u2192 `browser.map.forget` the app_id and let\n  the map repopulate as you learn the new structure.\n- A tool call fails with \"Tab not connected: tab_X\" \u2192 call\n  `browser.events` to see whether the bridge changed primary (the\n  Chrome tab probably got a new tab_id after a reconnect). Look for a\n  `tab-renamed` event with previous=tab_X and resume on the current id.\n\nThe map is a cache of navigation, not a substitute for `browser.snapshot`.\nThe live snapshot is always the source of truth.";
+export declare const SERVER_INSTRUCTIONS = "browser-link bridges Claude Code to the Chrome tabs the user has\nexplicitly connected through the companion extension, and ships a\npersistent UI map backed by a local SQLite DB. The data dir resolves\nper-OS via env-paths ($XDG_DATA_HOME/browser-link on Linux,\n~/Library/Application Support/browser-link on macOS, %APPDATA%/browser-link\non Windows). Override with $BROWSER_LINK_DATA_DIR. The map is private\nand per-machine; never persisted in any repo.\n\n## When operating on a tab\n\n1. Before doing anything on a tab whose URL you don't already know,\n   call `browser.map.recall` with { origin } (and optionally url) to load\n   selectors, flows and gotchas previously learned for that app.\n2. If recall returns entries with `failed_at` more recent than\n   `verified_at`, treat them as suspect: re-verify (snapshot / evaluate)\n   before reusing, or replace them.\n3. After every interaction that used a map entry, call\n   `browser.map.record_use` with { entry_id, ok }. ok=true updates\n   verified_at; ok=false updates failed_at. Keep the map honest.\n4. After a non-trivial flow that worked end-to-end, persist it with\n   `browser.map.save`. Three `kind` values:\n   - selector: { selector, evidence? } \u2014 a CSS selector tied to a purpose.\n   - flow: { steps: [...] } \u2014 an ordered list of actions to reach an outcome.\n   - gotcha: { body } \u2014 free-form note about something non-obvious.\n   Use `url_pattern` = pathname (exact). Promote to glob only if you have\n   evidence of a parametric route. Provide `purpose` as a stable, reusable\n   label (\"open task detail dialog\", not \"open IB0311 detail\").\n5. Never save selectors or flows you have not just successfully executed.\n6. Never store domain data (IDs, user names, dates, etc.). The map captures\n   UI structure only.\n\n## Identifying the app\n\n- `origin` = scheme://host:port of the tab.\n- `app_key` distinguishes apps that share an origin over time. On first\n  save you may omit it; it will be derived from the page title (slugified).\n  Use `browser.map.rename_app` if that initial guess is poor.\n\n## Sharing tabs with other agents\n\nThis primary may be serving several MCP clients at once (multi-agent mode).\nTo stop two agents fighting over the same Chrome tab there is a cooperative\nclaim layer:\n\n- `browser.list_tabs` includes `claimed_by` (null if free, otherwise the\n  agent that holds the claim) and `claimed_by_me` (boolean). Use it before\n  starting work on a tab whose state you don't already own.\n- `browser.my_tabs` returns YOUR active claims with timestamps. If the\n  user asks which tab you are using, this is the answer.\n- Action tools (`browser.click`, `browser.type`, `browser.navigate`,\n  `browser.evaluate`) auto-claim a free tab on first use and refresh\n  activity on subsequent calls. If another agent holds the tab, they\n  return an error naming the owner \u2014 do NOT retry blindly; ask the user\n  whose tab it should be, or use a different tab.\n- Read tools (`browser.snapshot`, `browser.console`, `browser.network`,\n  `browser.network_body`, `browser.events`, `browser.ping`) ignore claims.\n- `browser.claim_tab({ tab_id, ttl_minutes?, label? })` reserves a tab\n  explicitly. Provide a stable `label` (eg \"claude-code\", \"opencode\") so\n  other agents and the user see WHO holds the tab. The label is display\n  only \u2014 security relies on the IPC session id (kernel-vetted), not on\n  what an agent calls itself.\n- `browser.release_tab({ tab_id })` hands a tab back. Claims also auto-\n  release when an agent disconnects or after the inactivity TTL elapses\n  (default 10 minutes), so explicit release is only needed for early\n  hand-off.\n\nWhen you get a claim-conflict error: do NOT spin-retry. Either work on a\ndifferent tab from `list_tabs`, or surface the conflict to the user and\nlet them decide.\n\n## When something is wrong\n\n- A selector from recall fails \u2192 record_use({ok:false}), learn the new\n  one, save it (upsert on purpose).\n- A whole app got refactored \u2192 `browser.map.forget` the app_id and let\n  the map repopulate as you learn the new structure.\n- A tool call fails with \"Tab not connected: tab_X\" \u2192 call\n  `browser.events` to see whether the bridge changed primary (the\n  Chrome tab probably got a new tab_id after a reconnect). Look for a\n  `tab-renamed` event with previous=tab_X and resume on the current id.\n\nThe map is a cache of navigation, not a substitute for `browser.snapshot`.\nThe live snapshot is always the source of truth.";

package/dist/tools/server-instructions.js

@@ -38,6 +38,38 @@ and per-machine; never persisted in any repo.
   save you may omit it; it will be derived from the page title (slugified).
   Use \`browser.map.rename_app\` if that initial guess is poor.
 
+## Sharing tabs with other agents
+
+This primary may be serving several MCP clients at once (multi-agent mode).
+To stop two agents fighting over the same Chrome tab there is a cooperative
+claim layer:
+
+- \`browser.list_tabs\` includes \`claimed_by\` (null if free, otherwise the
+  agent that holds the claim) and \`claimed_by_me\` (boolean). Use it before
+  starting work on a tab whose state you don't already own.
+- \`browser.my_tabs\` returns YOUR active claims with timestamps. If the
+  user asks which tab you are using, this is the answer.
+- Action tools (\`browser.click\`, \`browser.type\`, \`browser.navigate\`,
+  \`browser.evaluate\`) auto-claim a free tab on first use and refresh
+  activity on subsequent calls. If another agent holds the tab, they
+  return an error naming the owner — do NOT retry blindly; ask the user
+  whose tab it should be, or use a different tab.
+- Read tools (\`browser.snapshot\`, \`browser.console\`, \`browser.network\`,
+  \`browser.network_body\`, \`browser.events\`, \`browser.ping\`) ignore claims.
+- \`browser.claim_tab({ tab_id, ttl_minutes?, label? })\` reserves a tab
+  explicitly. Provide a stable \`label\` (eg "claude-code", "opencode") so
+  other agents and the user see WHO holds the tab. The label is display
+  only — security relies on the IPC session id (kernel-vetted), not on
+  what an agent calls itself.
+- \`browser.release_tab({ tab_id })\` hands a tab back. Claims also auto-
+  release when an agent disconnects or after the inactivity TTL elapses
+  (default 10 minutes), so explicit release is only needed for early
+  hand-off.
+
+When you get a claim-conflict error: do NOT spin-retry. Either work on a
+different tab from \`list_tabs\`, or surface the conflict to the user and
+let them decide.
+
 ## When something is wrong
 
 - A selector from recall fails → record_use({ok:false}), learn the new

package/dist/tools/server-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/tools/server-instructions.ts"],"names":[],"mappings":"AAAA;oEACoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDAkDc,CAAC"}
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/tools/server-instructions.ts"],"names":[],"mappings":"AAAA;oEACoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iDAkFc,CAAC"}

package/dist/tools/tab-claims.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Cooperative tab-ownership registry for multi-agent mode.
+ *
+ * Several MCP clients can share a single browser-link primary. Without
+ * coordination they end up racing on the same Chrome tab — clicking,
+ * navigating, evaluating in interleaved order. This module tracks who
+ * "owns" each tab and lets the dispatcher refuse cross-agent action.
+ *
+ * Identity model:
+ *   - `agent_id` is the IPC session id for proxies (UUID minted after the
+ *     hello/token handshake) and the literal string `"primary"` for the
+ *     primary's own MCP client.
+ *   - The auth that the agent passed (peerLookup + Node binary allowlist +
+ *     rotated token) is the trust anchor. This registry never re-validates
+ *     identity — it consumes the `AgentCaller` the bridge layer supplies.
+ *   - Self-declared `label` (eg `"claude-code"`) is display-only and is
+ *     never used for ownership comparisons.
+ *
+ * TTL model:
+ *   - Claims expire after `ttl_minutes` of inactivity. Every action on the
+ *     tab refreshes `last_activity_at`. Stale claims are dropped by
+ *     `pruneStale()` (called periodically by the primary).
+ *   - Sessions ending (proxy disconnect) drop the agent's claims
+ *     immediately via `onAgentDisconnect()`.
+ */
+export interface AgentCaller {
+    agent_id: string;
+    pid: number;
+    binary: string;
+    label?: string;
+}
+export interface TabClaim {
+    tab_id: string;
+    agent_id: string;
+    pid: number;
+    binary: string;
+    label?: string;
+    claimed_at: number;
+    last_activity_at: number;
+    ttl_ms: number;
+}
+export type ClaimEvent = {
+    kind: 'tab-claimed';
+    tab_id: string;
+    agent_id: string;
+    pid: number;
+    binary: string;
+    label?: string;
+    ttl_ms: number;
+    auto: boolean;
+} | {
+    kind: 'tab-released';
+    tab_id: string;
+    agent_id: string;
+    reason: 'explicit' | 'agent-disconnect' | 'ttl';
+} | {
+    kind: 'tab-claim-rejected';
+    tab_id: string;
+    requester_agent_id: string;
+    existing_agent_id: string;
+};
+export type ClaimOutcome = {
+    ok: true;
+    claim: TabClaim;
+    created: boolean;
+} | {
+    ok: false;
+    reason: 'conflict';
+    existing: TabClaim;
+};
+export interface TabClaimRegistryOptions {
+    /** Default TTL when a claim does not specify one. Defaults to 10 minutes. */
+    defaultTtlMinutes?: number;
+    /** Upper bound on TTL a caller may request. Defaults to 60 minutes. */
+    maxTtlMinutes?: number;
+    /** Time source. Tests inject a fake clock to make TTL assertions deterministic. */
+    nowMs?: () => number;
+    /** Event callback. The primary wires this to its `BridgeEventLog`. */
+    onEvent?: (event: ClaimEvent) => void;
+}
+export declare class TabClaimRegistry {
+    private claims;
+    private readonly defaultTtlMs;
+    private readonly maxTtlMs;
+    private readonly now;
+    private readonly onEvent;
+    constructor(opts?: TabClaimRegistryOptions);
+    /** Snapshot of the current claim for a tab, or null when free or expired. */
+    getClaim(tab_id: string): TabClaim | null;
+    /** Explicit claim. Returns conflict if another agent owns the tab. Same-agent re-claims refresh activity and update the label/TTL. */
+    claim(tab_id: string, caller: AgentCaller, opts?: {
+        ttlMinutes?: number;
+        label?: string;
+    }): ClaimOutcome;
+    /** For action tools. Auto-claims a free tab for the caller, refreshes when the caller already owns it, conflicts otherwise. */
+    ensureActionAllowed(tab_id: string, caller: AgentCaller): ClaimOutcome;
+    /** Explicit release. Only the owner may release. */
+    release(tab_id: string, caller: AgentCaller): {
+        ok: true;
+    } | {
+        ok: false;
+        reason: 'not-claimed' | 'not-owner';
+        existing?: TabClaim;
+    };
+    /** Claims owned by this caller, sorted by `claimed_at`. */
+    myTabs(caller: AgentCaller): TabClaim[];
+    /** Drop every claim held by `agent_id` (called when a proxy disconnects). */
+    onAgentDisconnect(agent_id: string): TabClaim[];
+    /** Sweep claims past their TTL. Returns the dropped claims. */
+    pruneStale(): TabClaim[];
+    /** Test helper. Production callers should not need this. */
+    size(): number;
+    private isExpired;
+    private claimInternal;
+}
+/** User-facing error string for action tools when another agent holds the tab. Kept here so the wording is consistent across handlers. */
+export declare function formatClaimConflict(caller: AgentCaller, existing: TabClaim, nowMs?: number): string;