feat: add browser handoff attachment

Author: igorcosta

README.md

@@ -391,6 +391,14 @@ const handoff = await agent.createBrowserHandoff({
 console.log(handoff.url);
 ```
 
+#### `attachBrowserHandoff(params): Promise<BrowserHandoffAttachResult>`
+
+Consume a one-time handoff token and attach the referenced CLI session.
+
+```typescript
+const attached = await agent.attachBrowserHandoff({ token: handoff.token });
+```
+
 #### `getState(): Promise<GetStateResult>`
 
 Get the current agent state.

src/__tests__/session-control.test.ts

@@ -62,4 +62,32 @@ describe('session control RPCs', () => {
     const agent = Agent.fromSDK(sdk);
     await expect(agent.createBrowserHandoff(params)).resolves.toEqual(handoff);
   });
+
+  it('attaches a browser handoff token through every public layer', async () => {
+    const client = new RPCClient();
+    const calls: Array<{ method: string; params?: unknown }> = [];
+    const attached = {
+      success: true,
+      sessionId: 'session-attached',
+      workspaceRoot: '/workspace',
+      messageCount: 12,
+    };
+    getTransport(client).request = async (method, params) => {
+      calls.push({ method, params });
+      return attached;
+    };
+
+    const params = { token: 'handoff-token' };
+    await expect(client.attachBrowserHandoff(params)).resolves.toEqual(attached);
+    expect(calls).toEqual([{
+      method: 'autohand.browserHandoff.attach',
+      params,
+    }]);
+
+    const sdk = {
+      attachBrowserHandoff: async () => attached,
+    } as unknown as AutohandSDK;
+    const agent = Agent.fromSDK(sdk);
+    await expect(agent.attachBrowserHandoff(params)).resolves.toEqual(attached);
+  });
 });

src/rpc/client.ts

@@ -36,6 +36,8 @@ import type {
   GetMessagesResult,
   BrowserHandoffCreateParams,
   BrowserHandoffCreateResult,
+  BrowserHandoffAttachParams,
+  BrowserHandoffAttachResult,
   PermissionDecision,
   PermissionResponseParams,
   SDKEvent,
@@ -364,6 +366,18 @@ export class RPCClient {
     ) as Promise<BrowserHandoffCreateResult>;
   }
 
+  /**
+   * Consume a browser handoff token and attach its session.
+   */
+  async attachBrowserHandoff(
+    params: BrowserHandoffAttachParams
+  ): Promise<BrowserHandoffAttachResult> {
+    return this.transport.request(
+      'autohand.browserHandoff.attach',
+      params
+    ) as Promise<BrowserHandoffAttachResult>;
+  }
+
   /**
    * Respond to a permission request
    * 

src/sdk/agent.ts

@@ -34,6 +34,8 @@ import type {
   GetSkillsRegistryResult,
   BrowserHandoffCreateParams,
   BrowserHandoffCreateResult,
+  BrowserHandoffAttachParams,
+  BrowserHandoffAttachResult,
   InstallSkillParams,
   InstallSkillResult,
   McpListServersResult,
@@ -561,6 +563,12 @@ export class Agent {
     return this.sdk.createBrowserHandoff(params);
   }
 
+  async attachBrowserHandoff(
+    params: BrowserHandoffAttachParams
+  ): Promise<BrowserHandoffAttachResult> {
+    return this.sdk.attachBrowserHandoff(params);
+  }
+
   async setPlanMode(enabled: boolean): Promise<void> {
     await this.sdk.setPlanMode(enabled);
   }

src/sdk/index.ts

@@ -36,6 +36,8 @@ import type {
   GetMessagesResult,
   BrowserHandoffCreateParams,
   BrowserHandoffCreateResult,
+  BrowserHandoffAttachParams,
+  BrowserHandoffAttachResult,
   ResetResult,
   PermissionDecisionScope,
   PermissionResponseParams,
@@ -1421,6 +1423,16 @@ export class AutohandSDK {
     return this.client.createBrowserHandoff(params);
   }
 
+  /**
+   * Attach the session referenced by a one-time browser handoff token.
+   */
+  async attachBrowserHandoff(
+    params: BrowserHandoffAttachParams
+  ): Promise<BrowserHandoffAttachResult> {
+    await this.ensureStarted();
+    return this.client.attachBrowserHandoff(params);
+  }
+
   // ============================================================================
   // Permission Handling
   // ============================================================================

src/types/index.ts

@@ -1853,6 +1853,10 @@ export interface BrowserHandoffCreateParams {
   installUrl?: string;
 }
 
+export interface BrowserHandoffAttachParams {
+  token: string;
+}
+
 export interface PermissionResponseParams {
   requestId: string;
   decision?: PermissionDecision | PermissionDecisionAlias;
@@ -1890,6 +1894,13 @@ export interface BrowserHandoffCreateResult {
   url: string;
 }
 
+export interface BrowserHandoffAttachResult {
+  success: boolean;
+  sessionId?: string;
+  workspaceRoot?: string;
+  messageCount?: number;
+}
+
 export interface GetStateResult {
   status: 'idle' | 'processing' | 'waiting_permission';
   sessionId: string | null;