feat: add browser handoff creation

Author: igorcosta

README.md

@@ -379,6 +379,18 @@ Clear the current conversation and start a fresh CLI session. The returned
 const { sessionId } = await agent.reset();
 ```
 
+#### `createBrowserHandoff(params?): Promise<BrowserHandoffCreateResult>`
+
+Create a ten-minute, one-time handoff for the active session. Pass an extension
+ID to receive a Chrome extension URL, or an install URL for a web handoff.
+
+```typescript
+const handoff = await agent.createBrowserHandoff({
+  extensionId: 'your-extension-id',
+});
+console.log(handoff.url);
+```
+
 #### `getState(): Promise<GetStateResult>`
 
 Get the current agent state.

src/__tests__/session-control.test.ts

@@ -29,4 +29,37 @@ describe('session control RPCs', () => {
     const agent = Agent.fromSDK(sdk);
     await expect(agent.reset()).resolves.toEqual({ sessionId: 'session-reset' });
   });
+
+  it('creates a browser handoff through every public layer', async () => {
+    const client = new RPCClient();
+    const calls: Array<{ method: string; params?: unknown }> = [];
+    const handoff = {
+      token: 'handoff-token',
+      sessionId: 'session-browser',
+      workspaceRoot: '/workspace',
+      createdAt: '2026-07-20T00:00:00.000Z',
+      expiresAt: '2026-07-20T00:10:00.000Z',
+      url: 'chrome-extension://extension/sidepanel.html?handoff=handoff-token',
+    };
+    getTransport(client).request = async (method, params) => {
+      calls.push({ method, params });
+      return handoff;
+    };
+
+    const params = {
+      extensionId: 'extension',
+      installUrl: 'https://autohand.ai/chrome/installed',
+    };
+    await expect(client.createBrowserHandoff(params)).resolves.toEqual(handoff);
+    expect(calls).toEqual([{
+      method: 'autohand.browserHandoff.create',
+      params,
+    }]);
+
+    const sdk = {
+      createBrowserHandoff: async () => handoff,
+    } as unknown as AutohandSDK;
+    const agent = Agent.fromSDK(sdk);
+    await expect(agent.createBrowserHandoff(params)).resolves.toEqual(handoff);
+  });
 });

src/rpc/client.ts

@@ -34,6 +34,8 @@ import type {
   GetStateResult,
   GetMessagesParams,
   GetMessagesResult,
+  BrowserHandoffCreateParams,
+  BrowserHandoffCreateResult,
   PermissionDecision,
   PermissionResponseParams,
   SDKEvent,
@@ -350,6 +352,18 @@ export class RPCClient {
     return this.transport.request('autohand.getMessages', params) as Promise<GetMessagesResult>;
   }
 
+  /**
+   * Create a one-time browser handoff for the active session.
+   */
+  async createBrowserHandoff(
+    params: BrowserHandoffCreateParams = {}
+  ): Promise<BrowserHandoffCreateResult> {
+    return this.transport.request(
+      'autohand.browserHandoff.create',
+      params
+    ) as Promise<BrowserHandoffCreateResult>;
+  }
+
   /**
    * Respond to a permission request
    * 

src/sdk/agent.ts

@@ -32,6 +32,8 @@ import type {
   AutoresearchPruneResult,
   GetSkillsRegistryParams,
   GetSkillsRegistryResult,
+  BrowserHandoffCreateParams,
+  BrowserHandoffCreateResult,
   InstallSkillParams,
   InstallSkillResult,
   McpListServersResult,
@@ -553,6 +555,12 @@ export class Agent {
     return this.sdk.reset();
   }
 
+  async createBrowserHandoff(
+    params: BrowserHandoffCreateParams = {}
+  ): Promise<BrowserHandoffCreateResult> {
+    return this.sdk.createBrowserHandoff(params);
+  }
+
   async setPlanMode(enabled: boolean): Promise<void> {
     await this.sdk.setPlanMode(enabled);
   }

src/sdk/index.ts

@@ -34,6 +34,8 @@ import type {
   GetStateResult,
   GetMessagesParams,
   GetMessagesResult,
+  BrowserHandoffCreateParams,
+  BrowserHandoffCreateResult,
   ResetResult,
   PermissionDecisionScope,
   PermissionResponseParams,
@@ -1409,6 +1411,16 @@ export class AutohandSDK {
     return this.client.getMessages(params);
   }
 
+  /**
+   * Create a browser handoff URL for the active session.
+   */
+  async createBrowserHandoff(
+    params: BrowserHandoffCreateParams = {}
+  ): Promise<BrowserHandoffCreateResult> {
+    await this.ensureStarted();
+    return this.client.createBrowserHandoff(params);
+  }
+
   // ============================================================================
   // Permission Handling
   // ============================================================================

src/types/index.ts

@@ -1848,6 +1848,11 @@ export interface GetMessagesParams {
   limit?: number;
 }
 
+export interface BrowserHandoffCreateParams {
+  extensionId?: string;
+  installUrl?: string;
+}
+
 export interface PermissionResponseParams {
   requestId: string;
   decision?: PermissionDecision | PermissionDecisionAlias;
@@ -1876,6 +1881,15 @@ export interface ResetResult {
   sessionId: string;
 }
 
+export interface BrowserHandoffCreateResult {
+  token: string;
+  sessionId: string;
+  workspaceRoot: string;
+  createdAt: string;
+  expiresAt: string;
+  url: string;
+}
+
 export interface GetStateResult {
   status: 'idle' | 'processing' | 'waiting_permission';
   sessionId: string | null;