feat: give each browser client a stable id reported to node

Groundwork for #394. Each browser tab mints a stable client id
(`sessionStorage`-backed nanoid that survives reloads and RPC reconnects) and
tags its `devframe:agent:sync-client-tools` payload with it, so the node-side
client-agent registry records which tab each session belongs to.

This is the identifier only: no per-tab listing or routing yet. Tab
duplication copies `sessionStorage`, so duplicated tabs can briefly share an id
until the wider tab-metadata work adds disambiguation.

Co-authored-by: agent <agent@opencode>

Author: antfubot

packages/devframe/src/client/browser-agent-rpc.test.ts

@@ -19,9 +19,10 @@ describe('browser agent RPC bridge', () => {
       },
       callOptional(
         method: 'devframe:agent:sync-client-tools',
+        clientId: string,
         tools: BrowserAgentToolManifest[],
       ) {
-        return callOptional(method, tools)
+        return callOptional(method, clientId, tools)
       },
       events: { on: () => () => {} },
     }
@@ -36,6 +37,7 @@ describe('browser agent RPC bridge', () => {
     disposals.push(setupBrowserAgentRpcBridge(rpc))
     await vi.waitFor(() => expect(callOptional).toHaveBeenCalledWith(
       'devframe:agent:sync-client-tools',
+      expect.any(String),
       [{
         id: 'todos:add',
         description: 'Add a todo.',

packages/devframe/src/client/browser-agent-rpc.ts

@@ -4,6 +4,7 @@ import {
   listBrowserAgentTools,
   onBrowserAgentToolsChanged,
 } from './browser-agent'
+import { resolveClientId } from './client-id'
 
 export interface BrowserAgentInvocationDefinition {
   name: 'devframe:agent:invoke-client-tool'
@@ -16,6 +17,7 @@ interface BrowserAgentRpcClient {
   client: { register: (definition: BrowserAgentInvocationDefinition) => void }
   callOptional: (
     method: 'devframe:agent:sync-client-tools',
+    clientId: string,
     tools: BrowserAgentToolManifest[],
   ) => Promise<unknown>
   events: {
@@ -57,7 +59,7 @@ export function setupBrowserAgentRpcBridge(rpc: BrowserAgentRpcClient): () => vo
       if (manifests.length === 0 && lastSyncedCount === 0)
         return
       lastSyncedCount = manifests.length
-      await rpc.callOptional('devframe:agent:sync-client-tools', manifests).catch(() => {})
+      await rpc.callOptional('devframe:agent:sync-client-tools', resolveClientId(), manifests).catch(() => {})
     })
   }
 

packages/devframe/src/client/client-id.ts

@@ -0,0 +1,31 @@
+import { nanoid } from 'devframe/utils/nanoid'
+
+const CLIENT_ID_STORAGE_KEY = 'devframe:client-id'
+let memoryClientId: string | undefined
+
+/**
+ * This browser tab's stable client id: one nanoid per tab, persisted in
+ * `sessionStorage` so it survives page reloads and RPC reconnects. The node
+ * side uses it to tell connected tabs apart across reconnects (see #394).
+ *
+ * Tab duplication copies `sessionStorage`, so two tabs can briefly share an id
+ * until per-tab disambiguation lands with the wider tab-metadata work.
+ */
+export function resolveClientId(win: Window | undefined = globalThis.window): string {
+  try {
+    const storage = win?.sessionStorage
+    if (storage) {
+      let id = storage.getItem(CLIENT_ID_STORAGE_KEY)
+      if (!id) {
+        id = nanoid()
+        storage.setItem(CLIENT_ID_STORAGE_KEY, id)
+      }
+      return id
+    }
+  }
+  catch {
+    // Storage unavailable (sandboxed iframe, disabled cookies); fall through.
+  }
+  memoryClientId ??= nanoid()
+  return memoryClientId
+}

packages/devframe/src/node/__tests__/client-agent.test.ts

@@ -20,7 +20,7 @@ describe('client agent tools', () => {
       rpc: { $callRaw: callRaw },
     }
 
-    syncClientAgentTools(context, session, [{
+    syncClientAgentTools(context, session, 'tab-abc', [{
       id: 'pinia-colada:refetch',
       description: 'Refetch matching queries.',
       safety: 'action',

packages/devframe/src/node/client-agent.ts

@@ -15,6 +15,8 @@ interface ClientAgentSession {
 interface ClientAgentState {
   sessions: Map<DevframeNodeRpcSessionMeta, {
     session: ClientAgentSession
+    /** Stable per-tab id the browser reports, so reconnecting tabs stay identifiable (see #394). */
+    clientId: string
     tools: BrowserAgentToolManifest[]
   }>
   notifyChanged: () => void
@@ -53,10 +55,11 @@ function getState(context: ClientAgentContext): ClientAgentState {
 export function syncClientAgentTools(
   context: ClientAgentContext,
   session: ClientAgentSession,
+  clientId: string,
   tools: BrowserAgentToolManifest[],
 ): void {
   const state = getState(context)
-  state.sessions.set(session.meta, { session, tools })
+  state.sessions.set(session.meta, { session, clientId, tools })
   state.notifyChanged()
 }
 

packages/devframe/src/node/rpc/agent-sync-client-tools.ts

@@ -7,10 +7,10 @@ export const agentSyncClientTools = defineRpcFunction({
   type: 'action',
   jsonSerializable: true,
   setup: context => ({
-    handler(tools: BrowserAgentToolManifest[]): void {
+    handler(clientId: string, tools: BrowserAgentToolManifest[]): void {
       const session = context.rpc.getCurrentRpcSession()
       if (session)
-        syncClientAgentTools(context, session, tools)
+        syncClientAgentTools(context, session, clientId, tools)
     },
   }),
 })

packages/devframe/src/node/rpc/index.ts

@@ -23,6 +23,6 @@ declare module 'devframe/types' {
     'devframe:agent:invoke-tool': (id: string, args: unknown) => Promise<unknown>
     'devframe:agent:list-resources': () => Promise<readonly import('devframe/types').AgentResource[]>
     'devframe:agent:read-resource': (id: string) => Promise<import('devframe/types').AgentResourceContent>
-    'devframe:agent:sync-client-tools': (tools: import('../../client/browser-agent').BrowserAgentToolManifest[]) => Promise<void>
+    'devframe:agent:sync-client-tools': (clientId: string, tools: import('../../client/browser-agent').BrowserAgentToolManifest[]) => Promise<void>
   }
 }

packages/devframe/src/types/rpc-augments.ts

@@ -53,8 +53,8 @@ export interface DevframeRpcClientFunctions {
  * To be extended
  */
 export interface DevframeRpcServerFunctions {
-  /** Replace this connection's browser-agent tool manifest. @internal */
-  'devframe:agent:sync-client-tools': (tools: import('../client/browser-agent').BrowserAgentToolManifest[]) => Promise<void>
+  /** Replace this connection's browser-agent tool manifest, tagged with the calling tab's stable client id. @internal */
+  'devframe:agent:sync-client-tools': (clientId: string, tools: import('../client/browser-agent').BrowserAgentToolManifest[]) => Promise<void>
   /**
    * Authenticate a connection with a previously-issued bearer token; resolves
    * whether the connection is now trusted. The interactive handler is provided

tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts

@@ -255,7 +255,7 @@ export interface DevframeRpcOptions {
   snapshot?: DevframeSnapshotRpcEntry[];
 }
 export interface DevframeRpcServerFunctions {
-  'devframe:agent:sync-client-tools': (_: BrowserAgentToolManifest[]) => Promise<void>;
+  'devframe:agent:sync-client-tools': (_: string, _: BrowserAgentToolManifest[]) => Promise<void>;
   'anonymous:devframe:auth': (_: {
     authToken: string;
     ua: string;