Merge pull request #1 from DeliciousBuding/release/v0.2.0

Release v0.2.0

Author: DeliciousBuding

.gitignore

@@ -1,11 +1,13 @@
 # Binaries
 *.exe
 bin/
-bridge
-codex-browser-bridge
+/bridge
+/codex-browser-bridge
 
 # Test artifacts
 test_*.txt
+cover.out
+*.coverprofile
 
 # IDE
 .idea/

CHANGELOG.md

@@ -2,15 +2,30 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased]
+## [0.2.0] - 2026-05-16
 
 ### Added
-- Unit tests for `protocol`, `client`, `discovery`, and `mcp` packages
-- `NewMCPServerWithIO` for testable I/O injection
+- `codex_navigate_back` and `codex_navigate_forward` MCP tools (history navigation was already in the client; now exposed)
+- `codex_wait_for_load` MCP tool — polls `document.readyState` until `complete` or timeout
+- `codex_screenshot` now returns MCP `image` content so agents can view the screenshot directly (previously only base64 text)
+- `MCPServer.SetVersion` so the build version flows into the MCP `initialize` handshake (`serverInfo.version`)
+- Unit tests across `protocol`, `client`, `discovery`, and `mcp` packages
+  - In-memory `net.Pipe` fake server for end-to-end RPC tests without a real Codex pipe
+  - Concurrent `SendRequest` stress test under `-race`
+  - Wire-format invariants for `executeCdp`, `claimUserTab`, history navigation, JS escaping, CUA event sequencing, DOM box-model math
+  - MCP handler integration tests that exercise the full client → MCP path
+- `NewMCPServerWithIO` constructor for testable I/O injection
+- CI now runs `go test -race -cover`
 
 ### Fixed
 - `discovery.extractUUID` no longer truncates UUIDs containing hyphens
-- Better error messages on pipe-not-found and dial failures
+- Clearer error messages on pipe-not-found and dial failures
+- `Makefile install-local` now copies the `.exe` binary on Windows
+- Duplicate option numbering in README install sections
+
+### Internal
+- `client.NewFromConn` for wrapping an existing `net.Conn` (used by tests)
+- `cover.out` and `*.coverprofile` added to `.gitignore`
 
 ## [0.1.0] - 2026-05-16
 

README.md

@@ -235,11 +235,13 @@ quit
 
 ### Navigation
 
-| Tool                  | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| `codex_navigate`      | Navigate a tab to a URL                             |
-| `codex_reload`        | Reload a tab                                        |
-| `codex_wait_for_load` | Poll `document.readyState` until `complete`         |
+| Tool                       | Description                                         |
+| -------------------------- | --------------------------------------------------- |
+| `codex_navigate`           | Navigate a tab to a URL                             |
+| `codex_navigate_back`      | Navigate a tab back one entry in its history        |
+| `codex_navigate_forward`   | Navigate a tab forward one entry in its history     |
+| `codex_reload`             | Reload a tab                                        |
+| `codex_wait_for_load`      | Poll `document.readyState` until `complete`         |
 
 ### Page inspection
 

README.zh-CN.md

@@ -218,6 +218,8 @@ info          ping          try <method> [json]   quit
 | 工具 | 说明 |
 |------|------|
 | `codex_navigate` | 导航到指定 URL |
+| `codex_navigate_back` | 历史记录后退一项 |
+| `codex_navigate_forward` | 历史记录前进一项 |
 | `codex_reload` | 重新加载标签页 |
 | `codex_wait_for_load` | 轮询 `document.readyState` 直到 `complete` |
 

cmd/bridge/main.go

@@ -65,6 +65,7 @@ func runMCP(pipeName string, logger *log.Logger) {
 	logger.Println("Connected to Codex browser pipe")
 
 	srv := mcp.NewMCPServer(c)
+	srv.SetVersion(version)
 	if err := srv.Run(); err != nil {
 		fmt.Fprintf(os.Stderr, "MCP server error: %v\n", err)
 		os.Exit(1)

internal/mcp/handlers_test.go

@@ -190,6 +190,72 @@ func TestHandleNavigate(t *testing.T) {
 	}
 }
 
+func TestHandleNavigateBack(t *testing.T) {
+	srv, pipe, cleanup := newServerWithPipe(t, func(req protocol.Request) (interface{}, *protocol.ErrorObject) {
+		if req.Method != "executeCdp" {
+			return map[string]bool{"ok": true}, nil
+		}
+		params, _ := req.Params.(map[string]interface{})
+		if params["method"] == "Page.getNavigationHistory" {
+			return map[string]interface{}{
+				"currentIndex": 1,
+				"entries": []map[string]interface{}{
+					{"id": 100, "url": "https://a.test"},
+					{"id": 101, "url": "https://b.test"},
+				},
+			}, nil
+		}
+		return map[string]bool{"ok": true}, nil
+	})
+	defer cleanup()
+
+	out, ok := callTool(t, srv, "codex_navigate_back", map[string]interface{}{"tab_id": "5"})
+	if !ok {
+		t.Fatalf("handler errored: %s", out)
+	}
+	if !strings.Contains(out, "back") {
+		t.Errorf("output should mention back navigation: %s", out)
+	}
+
+	hasNavigate := false
+	for _, m := range pipe.recordedMethods() {
+		if m == "executeCdp" {
+			hasNavigate = true
+		}
+	}
+	if !hasNavigate {
+		t.Errorf("expected executeCdp calls, got %v", pipe.recordedMethods())
+	}
+}
+
+func TestHandleNavigateForward(t *testing.T) {
+	srv, _, cleanup := newServerWithPipe(t, func(req protocol.Request) (interface{}, *protocol.ErrorObject) {
+		if req.Method != "executeCdp" {
+			return map[string]bool{"ok": true}, nil
+		}
+		params, _ := req.Params.(map[string]interface{})
+		if params["method"] == "Page.getNavigationHistory" {
+			return map[string]interface{}{
+				"currentIndex": 0,
+				"entries": []map[string]interface{}{
+					{"id": 100, "url": "https://a.test"},
+					{"id": 101, "url": "https://b.test"},
+				},
+			}, nil
+		}
+		return map[string]bool{"ok": true}, nil
+	})
+	defer cleanup()
+
+	out, ok := callTool(t, srv, "codex_navigate_forward", map[string]interface{}{"tab_id": "5"})
+	if !ok {
+		t.Fatalf("handler errored: %s", out)
+	}
+	if !strings.Contains(out, "forward") {
+		t.Errorf("output should mention forward navigation: %s", out)
+	}
+}
+
 func TestHandleScreenshot(t *testing.T) {
 	srv, _, cleanup := newServerWithPipe(t, func(req protocol.Request) (interface{}, *protocol.ErrorObject) {
 		if req.Method == "executeCdp" {

internal/mcp/server.go

@@ -17,6 +17,7 @@ type MCPServer struct {
 	toolMap map[string]Tool
 	in      io.Reader
 	out     io.Writer
+	version string
 }
 
 type Tool struct {
@@ -52,11 +53,20 @@ func NewMCPServerWithIO(c *client.Client, in io.Reader, out io.Writer) *MCPServe
 		toolMap: make(map[string]Tool),
 		in:      in,
 		out:     out,
+		version: "dev",
 	}
 	s.registerTools()
 	return s
 }
 
+// SetVersion overrides the version reported in the MCP initialize handshake.
+// main.go calls this with the ldflags-injected build version.
+func (s *MCPServer) SetVersion(v string) {
+	if v != "" {
+		s.version = v
+	}
+}
+
 func (s *MCPServer) registerTools() {
 	s.tools = []Tool{
 		// Tab management
@@ -80,6 +90,12 @@ func (s *MCPServer) registerTools() {
 		{Name: "codex_reload", Description: "Reload a tab",
 			InputSchema: schema(`{"type":"object","properties":{"tab_id":{"type":"string"}},"required":["tab_id"]}`),
 			Handler:     s.handleReload},
+		{Name: "codex_navigate_back", Description: "Navigate a tab back one entry in its history",
+			InputSchema: schema(`{"type":"object","properties":{"tab_id":{"type":"string"}},"required":["tab_id"]}`),
+			Handler:     s.handleNavigateBack},
+		{Name: "codex_navigate_forward", Description: "Navigate a tab forward one entry in its history",
+			InputSchema: schema(`{"type":"object","properties":{"tab_id":{"type":"string"}},"required":["tab_id"]}`),
+			Handler:     s.handleNavigateForward},
 		{Name: "codex_wait_for_load", Description: "Poll document.readyState until it equals \"complete\" or timeout (ms) elapses. Useful after navigation on slow pages.",
 			InputSchema: schema(`{"type":"object","properties":{"tab_id":{"type":"string"},"timeout_ms":{"type":"number","description":"Timeout in milliseconds. Defaults to 10000."}},"required":["tab_id"]}`),
 			Handler:     s.handleWaitForLoad},
@@ -182,7 +198,7 @@ func (s *MCPServer) handleMessage(req struct {
 		s.writeResult(req.ID, map[string]interface{}{
 			"protocolVersion": "2024-11-05",
 			"capabilities":    map[string]interface{}{"tools": map[string]interface{}{}},
-			"serverInfo":      map[string]interface{}{"name": "codex-browser-bridge", "version": "0.1.0"},
+			"serverInfo":      map[string]interface{}{"name": "codex-browser-bridge", "version": s.version},
 		})
 	case "tools/list":
 		tools := make([]map[string]interface{}, len(s.tools))
@@ -324,6 +340,28 @@ func (s *MCPServer) handleReload(args json.RawMessage) ([]Content, error) {
 	return textContent(fmt.Sprintf("Reloaded tab %s", p.TabID)), nil
 }
 
+func (s *MCPServer) handleNavigateBack(args json.RawMessage) ([]Content, error) {
+	var p struct {
+		TabID string `json:"tab_id"`
+	}
+	json.Unmarshal(args, &p)
+	if err := s.client.NavigateBack(p.TabID); err != nil {
+		return nil, err
+	}
+	return textContent(fmt.Sprintf("Navigated tab %s back", p.TabID)), nil
+}
+
+func (s *MCPServer) handleNavigateForward(args json.RawMessage) ([]Content, error) {
+	var p struct {
+		TabID string `json:"tab_id"`
+	}
+	json.Unmarshal(args, &p)
+	if err := s.client.NavigateForward(p.TabID); err != nil {
+		return nil, err
+	}
+	return textContent(fmt.Sprintf("Navigated tab %s forward", p.TabID)), nil
+}
+
 func (s *MCPServer) handleWaitForLoad(args json.RawMessage) ([]Content, error) {
 	var p struct {
 		TabID     string `json:"tab_id"`

internal/mcp/server_test.go

@@ -31,7 +31,7 @@ func decodeResponses(t *testing.T, out *bytes.Buffer) []map[string]interface{} {
 
 func TestRegisteredToolCount(t *testing.T) {
 	s, _ := newTestServer("")
-	const want = 22
+	const want = 24
 	if len(s.tools) != want {
 		t.Errorf("tool count = %d, want %d", len(s.tools), want)
 	}

npm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delicious233/codex-browser-bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "MCP server that exposes Codex Desktop's Chrome browser bridge for Claude Code and other agents.",
   "bin": {