Expose a public browser bind-current command and clarify the shared browser runtime contract

[madlouse]

Summary

Two downstream projects on the same machine, madlouse/qifu-web-opencli and madlouse/360teams-opencli, both depend on OpenCLI but use it in different ways:

• qifu-web-opencli is browser-backed and needs a human-visible shared-tab workflow for internal Qifu web systems.
• 360teams-opencli is Electron/CDP-backed, but still shares the same machine-level Node/OpenCLI runtime baseline.

The shared problem is not cookie export. The user wants a true "human + agent shared environment": reuse the user's existing Chrome profile, login state, installed extensions, and ideally the currently visible tab when the task is page-centric.

What we verified

1. OpenCLI already reuses the real Chrome profile

This part is working as designed. The main pain point is not profile loss.

2. Default browser behavior still opens a separate automation window

The browser bridge background script creates a new window through chrome.windows.create(...).

That means:

• session reuse still happens through the same Chrome profile
• but the operator experience feels isolated because the agent is working in a separate automation window

3. Upstream already has an internal bind-current capability

There is already an internal path for binding a workspace to the currently focused tab:

• daemon client exposes bind-current
• extension background script handles that action and binds the workspace to the current tab/window

So the missing piece is productization, not feasibility.

4. Versioning and upgrade behavior are easy to misread

Observed healthy state on this machine:

• OpenCLI CLI: 1.7.7
• Browser extension: 1.0.2

This is compatible, but the numbering streams are different, which makes upgrade diagnostics harder to reason about.

5. Node runtime drift is a real source of false-success upgrades

OpenCLI 1.7.7 requires node >= 21, but non-login shells and some agent runtimes can still resolve an older node@20 first.

Result:

• operator thinks OpenCLI was upgraded
• runtime still fails in some paths because the wrong Node is executing the installed binary

Why this matters upstream

Downstream projects can package wrappers and documentation, but they should not have to patch the globally installed OpenCLI package or rely on hidden internal actions forever.

The durable owner for browser workspace binding and shared-runtime diagnostics is upstream OpenCLI.

Proposal

1. Expose a supported public command

Please add a public browser command such as:

opencli browser bind-current [--domain <host>] [--path-prefix </path>]

Expected behavior:

• bind the current browser workspace to the user's already visible/current tab
• optionally fail closed unless the active tab matches the requested domain/path
• preserve the current login/profile/extensions because it is the same real Chrome tab

2. Clarify the browser runtime contract in docs and doctor output

Please document explicitly:

• same profile reuse vs separate automation window are different concerns
• CLI version and extension version do not need to be string-equal
• extension reload may still be required after upgrading files on disk
• a successful CLI upgrade is not enough if the active runtime still resolves the wrong Node

3. Improve operator guidance for downstream projects

Suggested guidance pattern:

• preserve already-correct shared runtime state
• repair only incorrect shared runtime state
• keep downstream installers focused on their own plugin payloads

Acceptance criteria

• A public opencli browser bind-current command exists and is documented.
• The browser contract clearly distinguishes:
  • shared Chrome profile/session reuse
  • separate automation window behavior
  • visible current-tab binding
• The docs or doctor output make extension reload/version compatibility less ambiguous.
• The docs explicitly call out the Node runtime requirement in a way that helps non-login shell environments.

Lessons learned downstream

1. "new automation window" is not the same thing as "new profile".
2. The missing feature is current-tab binding as a public product surface.
3. CLI upgrade alone is insufficient if the extension worker is stale.
4. Downstream projects should not solve this by copying cookies or patching npm globals.

[Astro-Han]

Your investigation is accurate. The internal bind-current capability does exist:

• src/browser/daemon-client.ts: bindCurrentTab() function
• extension/src/background.ts: handleBindCurrent() handler
• Protocol includes 'bind-current' action type

However, there's relevant history that affects the decision:

#664 intentionally removed bind-current with this rationale: "mixed two incompatible concepts into the same workspace — an owned OpenCLI automation window/tab and a borrowed user tab. That design broke the browser core invariant." The PR restored the browser runtime to an "owned-only automation model."

#671 later brought it back for Instagram publishing workflows, but only as an internal mechanism — no public CLI command was added.

The core question isn't just productization. It's whether exposing bind-current as a public surface re-introduces the session semantics problem #664 was trying to solve. A public command would need clear constraints (domain/path matching, session lifecycle) to avoid breaking the owned-workspace invariant again.

This is an architectural tradeoff. Maintainers will need to weigh the downstream convenience against the invariant risk.