browserbase_session_close

Instructions

Implementation Reference

• src/tools/session.ts:144-218 (handler)

  The primary handler function that executes the tool's logic: retrieves the current session ID, attempts to clean up the session using SessionManager, handles cases where no session exists, logs details, and returns appropriate text content responses.

  async function handleCloseSession(context: Context): Promise<ToolResult> {
    const action = async (): Promise<ToolActionResult> => {
      // Store the current session ID before cleanup
      const previousSessionId = context.currentSessionId;
      let cleanupSuccessful = false;
      let cleanupErrorMessage = "";
  
      // Step 1: Get session info before cleanup
      let browserbaseSessionId: string | undefined;
      const sessionManager = context.getSessionManager();
  
      try {
        const session = await sessionManager.getSession(
          previousSessionId,
          context.config,
          false,
        );
  
        if (session && session.stagehand) {
          // Store the actual Browserbase session ID for the replay URL
          browserbaseSessionId = session.sessionId;
  
          // cleanupSession handles both closing Stagehand and cleanup (idempotent)
          await sessionManager.cleanupSession(previousSessionId);
          cleanupSuccessful = true;
        } else {
          process.stderr.write(
            `[tool.closeSession] No session found for ID: ${previousSessionId || "default/unknown"}\n`,
          );
        }
      } catch (error: unknown) {
        cleanupErrorMessage =
          error instanceof Error ? error.message : String(error);
        process.stderr.write(
          `[tool.closeSession] Error cleaning up session (ID was ${previousSessionId || "default/unknown"}): ${cleanupErrorMessage}\n`,
        );
      }
  
      // Step 2: SessionManager automatically resets to default on cleanup
      // Context.currentSessionId getter will reflect the new active session
      const oldContextSessionId = previousSessionId;
      process.stderr.write(
        `[tool.closeSession] Session context reset to default. Previous context session ID was ${oldContextSessionId || "default/unknown"}.\n`,
      );
  
      // Step 3: Determine the result message
      const defaultSessionId = sessionManager.getDefaultSessionId();
      if (cleanupErrorMessage && !cleanupSuccessful) {
        throw new Error(
          `Failed to cleanup session (session ID was ${previousSessionId || "default/unknown"}). Error: ${cleanupErrorMessage}. Session context has been reset to default.`,
        );
      }
  
      if (cleanupSuccessful) {
        let successMessage = `Browserbase session (${previousSessionId || "default"}) closed successfully. Context reset to default.`;
        if (browserbaseSessionId && previousSessionId !== defaultSessionId) {
          successMessage += ` View replay at https://www.browserbase.com/sessions/${browserbaseSessionId}`;
        }
        return { content: [{ type: "text", text: successMessage }] };
      }
  
      // No session was found
      let infoMessage =
        "No active session found to close. Session context has been reset to default.";
      if (previousSessionId && previousSessionId !== defaultSessionId) {
        infoMessage = `No active session found for session ID '${previousSessionId}'. The context has been reset to default.`;
      }
      return { content: [{ type: "text", text: infoMessage }] };
    };
  
    return {
      action: action,
      waitForNetwork: false,
    };
  }

• src/tools/session.ts:135-142 (schema)

  Defines the Zod input schema (empty, no parameters required) and the tool schema with name and description for the browserbase_session_close tool.

  const CloseSessionInputSchema = z.object({});
  
  const closeSessionSchema: ToolSchema<typeof CloseSessionInputSchema> = {
    name: "browserbase_session_close",
    description:
      "Close the current Browserbase session and reset the active context.",
    inputSchema: CloseSessionInputSchema,
  };

• src/tools/index.ts:21-30 (registration)

  Registers the session tools (including browserbase_session_close from sessionTools) into the central TOOLS array, likely used by the MCP server to expose available tools.

  export const TOOLS = [
    ...sessionTools,
    navigateTool,
    actTool,
    extractTool,
    observeTool,
    screenshotTool,
    getUrlTool,
    agentTool,
  ];

• src/tools/session.ts:220-224 (registration)

  Assembles the complete tool object by combining the schema, handler function, and capability for browserbase_session_close.

  const closeSessionTool: Tool<typeof CloseSessionInputSchema> = {
    capability: "core",
    schema: closeSessionSchema,
    handle: handleCloseSession,
  };

• src/sessionManager.ts:428-450 (helper)

  Supporting helper method in SessionManager called by the tool handler to perform the actual session cleanup and closure.

  async cleanupSession(sessionId: string): Promise<void> {
    process.stderr.write(
      `[SessionManager] Cleaning up session: ${sessionId}\n`,
    );
  
    // Get the session to close it gracefully
    const session = this.browsers.get(sessionId);
    if (session) {
      await this.closeBrowserGracefully(session, sessionId);
    }
  
    // Remove from browsers map
    this.browsers.delete(sessionId);
  
    // Clear default session reference if this was the default
    if (sessionId === this.defaultSessionId && this.defaultBrowserSession) {
      this.defaultBrowserSession = null;
    }
  
    // Reset active session to default if this was the active one
    if (this.activeSessionId === sessionId) {
      process.stderr.write(
        `[SessionManager] Cleaned up active session ${sessionId}, resetting to default.\n`,