refactor(agents): share connector validation and load the CDP spec from a live session

[ben-reitz]

TL;DR: Groundwork refactor shared by later PRs

---

Groundwork for the persistent browser connector: #2370 and #2371 build on it. BrowserConnector behaves the same as before.

1. connector-validation.ts: the JSON-schema argument validation moves out of connector.ts unchanged, so the second connector can reuse it.
2. loadCdpSpec can read from a live session, so a connected browser's spec() (feat(agents): add active-tab tracking and spec() to named browsers #2370) doesn't create an extra browser just to fetch the protocol:

 loadCdpSpec({ browser })              // create session → GET /json/protocol → delete
+loadCdpSpec({ browser, sessionId })   // GET /json/protocol from that session

Results are still cached per binding. The two paths are covered in the new browser-spec.test.ts.

Architecture diff

Outlined boxes are components this PR changes, with one box per change (green added, red removed). Green-filled boxes are new. Grey boxes are unchanged, and dashed boxes arrive later in the stack.

flowchart TB
  classDef ctx fill:none,stroke:#8c959f,color:#8c959f
  classDef changes fill:#dafbe1,stroke:#1a7f37,color:#1f2328
  classDef removed fill:#ffebe9,stroke:#cf222e,color:#1f2328
  classDef later fill:none,stroke:#8c959f,stroke-dasharray:4 3,color:#8c959f

  Runtime["codemode runtime"]:::ctx

  subgraph BC["BrowserConnector · connector.ts"]
    C1["− inline argument validation (moved out)"]:::removed
  end

  subgraph Val["connector-validation.ts (new)"]
    V1["+ validateConnectorArgs(connector, name, tool)"]:::changes
  end

  subgraph Spec["loadCdpSpec · spec.ts"]
    S1["+ optional sessionId: read the protocol from that session"]:::changes
  end

  BR["Browser Run"]:::ctx
  NextSpec["BrowserConnection.spec() (#2370)<br/>reads the spec from its own browser"]:::later
  Next["BrowserSessionConnector (#2371)<br/>validates args"]:::later

  Runtime -->|"tool calls"| BC
  BC --> Val
  BC -->|"no sessionId: temporary session, as before"| Spec
  Spec --> BR
  Next -.-> Val
  NextSpec -.->|"with sessionId"| Spec

  style BC stroke:#1a7f37,stroke-width:2px
  style Val fill:#dafbe1,stroke:#1a7f37,stroke-width:2px,color:#1f2328
  style Spec stroke:#1a7f37,stroke-width:2px

Loading

[changeset-bot]

🦋 Changeset detected

Latest commit: 83479fd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[agent-think]

✅ agents import sizes: no significant changes (61b511e4 → 83479fdf, workflow run)

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2369

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2369

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2369

hono-agents

npm i https://pkg.pr.new/hono-agents@2369

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2369

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2369

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2369

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2369

commit: 83479fd