[antfubot]

Closes #394. MVP of the plan discussed there.

What changes

With several tabs of the same app open, the MCP surface behaved as if there were one client: devframe connect lists instances per port, and in-page tools (from #376) were silently owned by whichever tab synced last.

• Ports the feat: eagerly expose in-page tools to browser agents #376 bridge onto 0.10 (@devframes/agentic era): agent-flagged in-page channel functions register in a per-document browser-agent registry and sync to the node over the page's RPC connection; the node exposes them as MCP tools and relays calls back. Not yet on main, so it lands here as the foundation.
• Each tab reports itself with its manifest: a per-tab id (the in-page channel's existing sessionStorage-backed instance id, so it survives reloads), URL, title, visible, focused. Re-synced on connect, tool changes, and focus/blur/visibilitychange.
• devframe:agent:list-clients (wire devframe_agent_list-clients): built-in tool listing the connected tabs and the tool ids each exposes. Appears once a tab is connected, so a devframe with no agent surface of its own doesn't flip MCP auto-mount.
• Per-tab routing: tools/list stays deduped (one entry per tool id). Forwarded tools take a reserved client_id argument; an unknown id fails with the new DF0081 listing the live ids. Without client_id, the call goes to the most recently focused visible tab, falling back to the last-synced one — which is what medula's vendored patch approximated with "last sync wins".
• devframe connect: list-instances nests mcp.clients per instance (fetched in the same MCP session it already opens to list tools); call-tool passes client_id through.
• Docs: guide section, DF0080 (the feat: eagerly expose in-page tools to browser agents #376 jsonSerializable guard, renumbered since DF0078 is taken on main) and DF0081 pages.

Verification

• Unit tests for the routing rules (focus → visible → last synced, client_id targeting/stripping, missing id, no re-publish on focus-only re-sync).
• Integration test over a live dev server + real MCP client: two WS tabs, tools/list dedup + injected client_id schema, list-clients output, addressed/unaddressed/missing-id calls, focus follow.
• pnpm lint && pnpm knip && pnpm test && pnpm typecheck && pnpm build green (knip's remaining items are the pre-existing unbuilt-starter hints).

Known limits (MVP)

• A duplicated tab copies sessionStorage, so two tabs can briefly share an id; targeting then picks the better-ranked one.
• A tab with several RPC connections (host page + dock iframes) lists once per connection.
• URL/title lag briefly after an SPA navigation until the next focus/visibility/tool event.

Supersedes the in-page-tools part of #376 (ported and extended here).

---

This PR was created with the help of an agent.

[coldtea-pr-lens]

◈ PR Lens

🟢 +4 new · 🟠 ~6 changed · 🔴 -0 removed · 2 flows · 14 files · commit fc6a624

Architecture

10 components touched across 3 lanes.

Play the interactive walkthrough

Inside the changed components — 2 views

Component view — Browser Agent Bridge

In-tab registry and RPC sync bridge forwarding page functions to Devframe

Component view — Client Agent Manager

Node session manager tracking tabs, focus state, and routing tool calls

Data flow

Syncing browser tools to node MCP · Calling a forwarded tool from an agent

Follow each request, response and payload

The other flows — 1 sequence

Calling a forwarded tool from an agent

View

• Architecture lens
• Data flow lens
• Expand every detail

Tip

Click the link under each diagram to open it on a canvas you can zoom, pan and step through

🪧 More tips

• Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists
• Untick Architecture lens or Data flow lens under View to hide a diagram, or tick Expand every detail to open every section. The comment redraws in a few seconds
• The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change
• Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
• The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
• Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture and data flow row. Drawing still runs as before
• Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing pull requests on its own. Comment @pr-lens draw on a pull request when you want that one drawn
• Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
• Push a commit and the drawing stays, with a note that it is out of date. Tick Redraw in the note to draw the new head
• Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion

---

Thanks for using PR Lens! It's built by Coldtea, free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Bluesky
• Mastodon
• Reddit
• LinkedIn

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
devframe	Ready	Preview	Oct 21, 2026 1:51am UTC

[github-actions]

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/413?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-10-21 01:49 UTC
🔗 head 0077dd9
🤖 automated by pulls.review

{
  "headSha": "0077dd9a2b93aec9cac65f010e5b15e869a98f92",
  "result": {
    "overallSummary": "Ports the browser-agent/in-page-tools bridge to the current RPC stack and extends it so multiple open tabs of the same app are distinguishable and individually addressable: each tab now reports an id plus URL/title/visibility/focus, the node exposes a `devframe:agent:list-clients` tool and dedupes forwarded tool ids across tabs, calls can target one tab via a reserved `client_id` (with a new DF0082 error for unknown ids), and `devframe connect` surfaces the same tab list under `mcp.clients`.",
    "groups": [
      {
        "key": "client-agent-routing",
        "label": "Per-tab client agent routing",
        "summary": "Core of the feature: each browser tab now reports its own manifest plus visibility/focus/URL/title info over RPC; the node tracks one entry per tab, dedupes tool ids across tabs, exposes a built-in `devframe:agent:list-clients` tool, and routes forwarded tool calls to a specific tab via a reserved `client_id` argument (falling back to focused → visible → last-synced), with a new DF0082 diagnostic for an unknown/missing id.",
        "category": "core",
        "filePaths": [
          "packages/devframe/src/node/client-agent.ts",
          "packages/devframe/src/node/diagnostics.ts",
          "packages/devframe/src/node/rpc/agent-sync-client-tools.ts",
          "packages/devframe/src/node/rpc/index.ts",
          "packages/devframe/src/types/rpc-augments.ts",
          "packages/devframe/src/internal/index.ts",
          "packages/devframe/src/client/browser-agent.ts",
          "packages/devframe/src/client/browser-agent-rpc.ts"
        ],
        "critical": true,
        "fileNotes": [
          {
            "path": "packages/devframe/src/node/client-agent.ts",
            "text": "Holds the targeting/ranking logic (`pickTarget`), the `client_id` schema injection/stripping, and the dedup across tabs sharing tool ids — the riskiest and most central piece of this PR.",
            "critical": true
          },
          {
            "path": "packages/devframe/src/client/browser-agent-rpc.ts",
            "text": "Adds focus/blur/visibilitychange listeners that re-sync the tab's info without necessarily republishing the tool list."
          }
        ]
      },
      {
        "key": "connect-cli-clients",
        "label": "devframe connect: list clients",
        "summary": "Extends `devframe connect`'s `list-instances` to nest connected browser tabs under `mcp.clients` (by calling the new `list-clients` tool in the same MCP session) and documents `client_id` for `call-tool`.",
        "category": "cli",
        "filePaths": [
          "packages/agentic/src/connect/index.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/agentic/src/connect/index.ts",
            "text": "`indexInstanceMcp` now also calls the built-in `list-clients` tool when present, reading its result from `structuredContent`, which is typed only via a cast (the tool's output schema is the real source of truth)."
          }
        ]
      },
      {
        "key": "tests",
        "label": "Routing and integration tests",
        "summary": "Unit tests for the tab-targeting rules (focus → visible → last synced, addressed/missing `client_id`, no re-publish on focus-only sync) plus a live WS + real MCP client integration test exercising dedup, `list-clients`, and routed calls end to end.",
        "category": "tests",
        "filePaths": [
          "packages/devframe/src/node/__tests__/client-agent.test.ts",
          "packages/devframe/src/client/browser-agent-rpc.test.ts",
          "packages/agentic/src/mcp/__tests__/mcp-client-tools.test.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/agentic/src/mcp/__tests__/mcp-client-tools.test.ts",
            "text": "Spins up a real dev server and two WS-connected fake tabs, then drives the public MCP endpoint, so it's a good smoke test to run if the core routing logic is touched."
          }
        ]
      },
      {
        "key": "docs",
        "label": "Docs for in-page tools over MCP",
        "summary": "Documents the new 'in-page tools over MCP' flow, the `client_id` routing contract, `devframe:agent:list-clients`, and the new DF0082 error.",
        "category": "docs",
        "filePaths": [
          "docs/content/1.guide/12.in-page-channel.md",
          "docs/content/1.guide/15.agent-native.md",
          "docs/content/6.errors/DF0082.md",
          "docs/content/6.errors/index.md"
        ]
      },
      {
        "key": "generated-snapshots",
        "label": "Generated API snapshots",
        "summary": "Auto-generated public API snapshots updated to reflect the new `BrowserAgentClientInfo` parameter, `ConnectedClient` type, `LIST_CLIENTS_TOOL` export and DF0082 diagnostic.",
        "category": "other",
        "filePaths": [
          "tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts",
          "tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts",
          "tests/__snapshots__/tsnapi/devframe/internal.snapshot.js"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-10-21T01:49:52.145Z",
    "model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
    "locale": "en"
  }
}