Metadata-Version: 2.3
Name: browser-auto-shinebed
Version: 0.1.4
Summary: AdsPower bridge wrapper for browser-act automation
Requires-Dist: aiohttp>=3.9
Requires-Python: >=3.12, <3.13
Description-Content-Type: text/markdown

# browser-auto-shinebed

`browser-auto-shinebed` is a publishable wrapper around `browser-act` that adds
AdsPower browser mode and a combined entry Skill for teams that operate
multiple stores through AdsPower profiles.

The wrapper only connects browser-act to an AdsPower browser. It does not
reimplement page automation. After an AdsPower profile is opened, all
session-scoped browser automation commands are still handled by the original
`browser-act` session server, including `state`, `click`, `input`, `eval`,
`get`, `network`, `wait`, `tab`, `cookies`, `dialog`, `screenshot`, and upload
flows.

The included `browser-auto-shinebed` Skill also contains Forge Mode, so agents
can generate reusable browser-act workflow Skills without installing a separate
`browser-act-skill-forge` Skill.

This wrapper also includes a local-only Shinebed Assist MVP for handing an
AdsPower browser to a human on the same machine when a workflow hits a visual
verification step.

## Install For Another Agent

Ask the agent to install this entry Skill:

```text
Install browser-auto-shinebed.
Skill URL:
https://github.com/DingShineShine/browser-auto-shinebed-skills/tree/main/browser-auto-shinebed

After installation, verify that browser-act is the browser-auto-shinebed wrapper
and AdsPower bridge mode is available.

Then load the full installed guide with:
browser-act get-skills browser-auto-shinebed --skill-version 0.1.4
```

The public entry Skill is intentionally thin. It tells the agent to install this
CLI package, then the CLI serves the full AdsPower, assist, and Forge Mode guide
that matches the installed package version.

## Manual CLI Install

```powershell
uv tool install browser-auto-shinebed --python 3.12
browser-act doctor
browser-act --version
browser-act browser list
browser-act get-skills browser-auto-shinebed --skill-version 0.1.4
```

`browser-auto-shinebed` manages `browser-act-cli==1.0.6` internally. Users do
not need to install `browser-act-cli` separately. If no compatible browser-act
CLI is already available, the wrapper installs a private managed copy on first
use.

Forge Mode is included in the installed `browser-auto-shinebed` guide. When an agent is
asked to create, forge, or permanently automate a site workflow, it uses normal
`browser-act` commands through this wrapper and writes generated Skills under
`output/{skill-name}/`.

The `browser-act` command on `PATH` is expected to be this wrapper. This is the
healthy state: the wrapper preserves the original browser-act command surface
and adds AdsPower routing for `adspower:<user_id>` browser opens.

If a later manual install of `browser-act-cli` overwrites the `browser-act`
command, reinstall this package to restore wrapper ownership:

Upgrade:

```powershell
uv tool install --force browser-auto-shinebed --python 3.12
```

Default AdsPower Local API base:

```text
http://local.adspower.net:50325
```

If AdsPower requires an API key:

```powershell
$env:ADSPOWER_API_KEY="..."
```

## Usage

Open a profile directly without pre-creating a record:

```powershell
browser-act --session ads1 browser open adspower:<user_id> https://example.com
browser-act --session ads1 state
browser-act --session ads1 click 1
browser-act --session ads1 get markdown
browser-act --session ads1 assist open
browser-act session close ads1
```

Or create a local AdsPower browser record:

```powershell
browser-act browser create --type adspower `
  --name "ads-profile" `
  --desc "AdsPower profile for browser-act" `
  --adspower-user-id <user_id>
```

Then open it:

```powershell
browser-act --session ads1 browser open adspower:<user_id> https://example.com
```

Start a local assist page for an AdsPower profile:

```powershell
browser-act --session ads1 assist open
browser-act assist open adspower:<user_id>
browser-act assist open ads:<user_id> --url https://example.com
```

The command prints a `http://127.0.0.1:<port>/assist/<token>` URL and stays in
the foreground until Ctrl+C or the page's End button. The link is local-only,
short-lived, and does not expose the underlying CDP websocket to the page.
When `assist open` is used with `--session`, the wrapper resolves the AdsPower
profile from the last successful `browser open adspower:<user_id>` for that
session, so a workflow can keep running normally and only hand off when it
hits a visual verification step.

## How It Works

Original browser-act is already CDP-based. The main difference between browser
modes is where the browser process comes from:

- `chrome`: browser-act starts a Chrome/Chromium browser.
- `chrome-direct`: browser-act connects to an existing Chrome browser.
- `stealth`: browser-act starts or connects to a stealth browser.
- `adspower`: this wrapper asks AdsPower to start a profile, then passes
  AdsPower's `ws.puppeteer` CDP endpoint to the original browser-act session
  server.
- `assist`: this wrapper asks AdsPower for the active profile CDP endpoint,
  streams frames through a local `aiohttp` page, and replays human input through
  Chrome DevTools Protocol input events.

Flow:

1. `browser-act --session s browser open adspower:<user_id> <url>` is
   intercepted by this wrapper.
2. The wrapper calls AdsPower Local API `browser/start`.
3. AdsPower returns a CDP websocket such as
   `ws://127.0.0.1:<port>/devtools/browser/...`.
4. The wrapper starts a patched browser-act session server with an AdsPower
   launch driver.
5. The wrapper records `session_name -> AdsPower user_id` in its local state.
6. The original browser-act session server consumes that CDP endpoint.
7. All later commands for the session run through original browser-act.
8. If `browser-act --session s assist open` is called later, the wrapper uses
   the local session mapping to attach a control page to the same AdsPower
   profile without navigating away from the current page.

Non-AdsPower commands are delegated to `browser-act-cli==1.0.6`, loaded from
the current environment, an existing `uv tool install browser-act-cli`, or the
wrapper's private managed copy. `BROWSER_ACT_REAL_BIN` remains available as a
compatibility fallback.

## Diagnostics

```powershell
browser-act doctor
```

The doctor checks:

- whether `browser-act` is on `PATH`;
- whether `browser-act` is owned by the `browser-auto-shinebed` wrapper;
- whether the original `browser_act_cli` package can be imported;
- whether AdsPower Local API is reachable;
- how many local AdsPower bridge records are configured.
