Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,11 @@ jobs:
output="$(PATH="$test_dir/fake-path:/usr/bin:/bin" "$test_dir/skill/scripts/doctor.sh")"
status=$?
set -e
test "$status" -eq 2
test "$output" = '{"ok":false,"error":"unsupported_platform","message":"This Skill supports macOS arm64 through scripts/doctor.sh and Windows x64 through scripts/doctor.ps1."}'
test "$status" -eq 1
test "$output" = '{"ok":false,"error":"command_not_found","message":"Skill-local browser-cli is missing. Run scripts/bootstrap.sh first."}'
! grep -q 'command -v browser-cli' skills/lexmount-browser/scripts/doctor.sh
! grep -q 'Get-Command browser-cli' skills/lexmount-browser/scripts/doctor.ps1
- run: ./tests/linux_bootstrap.py
- name: Verify runtime packaging contract
run: |
! grep -R -E 'python3[[:space:]]|python[[:space:]]+-m|uv[[:space:]]' scripts skills .github/workflows
Expand Down
2 changes: 1 addition & 1 deletion Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "lexmount-browser"
version = "1.3.0"
version = "1.4.0"
edition = "2024"
license = "MIT"
description = "Native Rust SDK and CLI for Lexmount cloud browsers"
Expand Down
30 changes: 27 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,8 +150,8 @@ automatic action retries. These changes require a new CLI release; published
Explicit page selection is introduced in version 1.2.0. Check that the installed
binary's `browser-cli action --help` lists `--target-id`; the published 1.1.15
binary does not have it. The package version and both bootstrap scripts target
1.3.0 together. Merging or building this source does not publish release assets:
bootstrap can install 1.3.0 only after its binaries and checksums are published
1.4.0 together. Merging or building this source does not publish release assets:
bootstrap can install 1.4.0 only after its binaries and checksums are published
to COS. Until then, use a source build for local verification.

Every `action` command accepts an optional `--target-id`. Obtain the page's CDP
Expand Down Expand Up @@ -263,7 +263,7 @@ overwrite an existing release with changed binaries.
`skills/lexmount-browser/scripts/bootstrap.ps1` and `bootstrap.sh`.
2. Run `.github/scripts/test-release-version.ps1` with Windows PowerShell 5.1
or PowerShell 7, then `.github/scripts/verify-release-version.ps1 -ReleaseTag
v1.3.0` (substitute the intended version). Complete CI and merge the PR.
v1.4.0` (substitute the intended version). Complete CI and merge the PR.
3. Create the matching tag **on that merged commit**. Typing a new tag or
release title in GitHub does not update any source version. The release
workflow rejects inconsistent versions before building, signing or uploading.
Expand Down Expand Up @@ -299,3 +299,27 @@ Tencent Cloud COS through the `cos-release` GitHub environment. It requires
`TENCENT_CLOUD_SECRET_ID` and `TENCENT_CLOUD_SECRET_KEY` secrets plus
`COS_BUCKET`, `COS_REGION`, `COS_PUBLIC_BASE_URL`, and `COS_OBJECT_PREFIX`
variables.


### Linux and SSH login

Linux x86_64 uses the static musl release and the same `scripts/bootstrap.sh` and `scripts/doctor.sh` as macOS. Linux ARM64 is not currently a published target.

`browser-cli auth login --no-open` prints the authorization URL on stderr and waits for the callback; stdout remains the final JSON result. The default login attempts to open a browser, but keeps waiting if the desktop opener is missing. On a headless/SSH host, forward the printed callback port from your desktop using `ssh -L PORT:127.0.0.1:PORT HOST`, then open the printed URL on your desktop. Keep the login process running until it completes. Do not post authorization URLs or credentials in chat.

### Device login for SSH / headless Linux

`browser-cli auth login --device` prints a console address and short code. Open it
on a phone or another computer, sign in, enter the code and approve the request.
The terminal polls over HTTPS and saves credentials automatically (0600 on Unix).
No inbound port or SSH forwarding is required. The console must have device-login
support deployed before using this mode.

`auth login` automatically selects device mode over SSH or on Linux without
DISPLAY/WAYLAND_DISPLAY. Use `--browser` to force local loopback login; `--no-open`
retains manual loopback behavior. CI should supply credentials instead of starting
interactive login; explicit `--device` is available when a human is present.
`--project-id` verifies the approved account's project before saving credentials.
An expired, denied or consumed request requires a new login; API keys are never
printed. Ctrl+C stops polling. The console authorization request expires in ten
minutes even if the terminal is closed.
9 changes: 9 additions & 0 deletions docs/linux-support.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Linux support audit

The current release builds a static Linux x86_64 musl binary, but the bundled Skill bootstrap and doctor scripts rejected Linux. Both now select the published Linux target. The doctor retains Skill-local binary isolation rather than falling back to an unrelated executable on PATH. Linux ARM64 remains unsupported by the release pipeline.

The loopback PKCE login previously had two unusable paths on headless Linux: browser-opening failure aborted login, and `--no-open` waited without exposing the URL. Login now emits its URL and SSH callback forwarding guidance to stderr before waiting; a missing opener falls back to manual authorization. Stdout remains machine-readable final JSON. This does not automate account consent or reuse another user's credentials.

Unrelated callbacks (including an incorrect state) no longer terminate the pending flow. The callback page acknowledges receipt and asks the user to confirm CLI completion, rather than claiming that credential exchange has already succeeded.

Validation covers a real CLI child process, loopback callback, local mock credential exchange, missing desktop opener, no-open login, and Linux bootstrap with checksum-verified fixtures. These tests do not substitute for a human completing real website consent on a Linux desktop or SSH workstation. No release is published by this change.
4 changes: 2 additions & 2 deletions skills/lexmount-browser/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Do not infer `<skill-root>` from the working directory.

Select the native Rust binary for the current platform:

- macOS arm64: run `sh "<skill-root>/scripts/bootstrap.sh"` when `<skill-root>/bin/browser-cli` is missing, then invoke `"<skill-root>/bin/browser-cli"`.
- Linux x86_64 and macOS arm64: run `sh "<skill-root>/scripts/bootstrap.sh"` when `<skill-root>/bin/browser-cli` is missing, then invoke `"<skill-root>/bin/browser-cli"`.
- Windows x64: run `& "<skill-root>\scripts\bootstrap.ps1"` in PowerShell when `<skill-root>\bin\browser-cli.exe` is missing, then invoke `& "<skill-root>\bin\browser-cli.exe"`.

Both bootstrap scripts download the fixed release version from Tencent Cloud COS and verify its SHA-256 digest.
Expand All @@ -29,7 +29,7 @@ Do not run the binary for the other platform. Both platform binaries emit JSON.
## Setup

1. Resolve `<skill-root>` from this `SKILL.md` and select the matching platform paths above.
2. Run the Skill-local bootstrap script if the binary is missing. Then run `sh "<skill-root>/scripts/doctor.sh"` on macOS arm64. On Windows, invoke the installed binary's `doctor` command directly, not `scripts/doctor.ps1`: PowerShell uses `& "<skill-root>\bin\browser-cli.exe" doctor`; Bash/Git Bash uses `"<skill-root>/bin/browser-cli.exe" doctor` with forward slashes in the absolute path. In WorkBuddy on Windows, prefer its Bash tool when available: its PowerShell tool can return only an exit code and omit the JSON. Keep the tool's normal permissions and sandbox.
2. Run the Skill-local bootstrap script if the binary is missing. Then run `sh "<skill-root>/scripts/doctor.sh"` on Linux x86_64 or macOS arm64. On Windows, invoke the installed binary's `doctor` command directly, not `scripts/doctor.ps1`: PowerShell uses `& "<skill-root>\bin\browser-cli.exe" doctor`; Bash/Git Bash uses `"<skill-root>/bin/browser-cli.exe" doctor` with forward slashes in the absolute path. In WorkBuddy on Windows, prefer its Bash tool when available: its PowerShell tool can return only an exit code and omit the JSON. Keep the tool's normal permissions and sandbox.
3. If credentials are missing, run `browser-cli auth login`. Pass `--client-name "<agent-name>"` when the current Agent has a user-facing name; otherwise the CLI uses `Agent`. Let the user approve in their browser. Never ask them to paste an API key into chat.
4. After changing credentials, run `browser-cli doctor` again; otherwise use the doctor result already obtained. Continue only when its actual JSON reports `ready_for_browser_actions: true`. An exit code without that JSON is not a readiness result; see [Windows diagnostic output](references/troubleshooting.md#windows-diagnostic-output).

Expand Down
19 changes: 19 additions & 0 deletions skills/lexmount-browser/references/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,22 @@ The file is mode `0600` on Unix. The CLI redacts the API key from all JSON outpu
For managed environments, the SDK also accepts `LEXMOUNT_API_KEY`, `LEXMOUNT_PROJECT_ID`, optional `LEXMOUNT_BASE_URL`, and optional `LEXMOUNT_REGION`. Do not ask users to paste secret values into an Agent chat.

Use `browser-cli auth logout` to remove only the local credential file. Environment variables are managed outside the CLI.


### Linux and SSH login

Linux x86_64 uses the static musl release and the same `scripts/bootstrap.sh` and `scripts/doctor.sh` as macOS. Linux ARM64 is not currently a published target.

`browser-cli auth login --no-open` prints the authorization URL on stderr and waits for the callback; stdout remains the final JSON result. The default login attempts to open a browser, but keeps waiting if the desktop opener is missing. On a headless/SSH host, forward the printed callback port from your desktop using `ssh -L PORT:127.0.0.1:PORT HOST`, then open the printed URL on your desktop. Keep the login process running until it completes. Do not post authorization URLs or credentials in chat.

## Device authorization

Use `browser-cli auth login --device` on a machine without a desktop browser.
Ask the human to open the displayed console URL on another device and enter the
short code. The CLI waits for explicit approval, then stores the credential. Never
ask them to send their password or API key in chat. This requires the console's
`/api/connect/device/authorize` and `/api/connect/device/token` endpoints.

SSH and headless Linux choose this automatically; `--browser` forces loopback
login, while `--no-open` preserves manual loopback login. CI should use preconfigured
credentials. Denial or expiry stops login; do not silently retry a denied request.
2 changes: 1 addition & 1 deletion skills/lexmount-browser/scripts/bootstrap.ps1
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ function Invoke-Tls12Download {
}
}

$version = if ($env:LEXMOUNT_BROWSER_CLI_VERSION) { $env:LEXMOUNT_BROWSER_CLI_VERSION } else { "1.3.0" }
$version = if ($env:LEXMOUNT_BROWSER_CLI_VERSION) { $env:LEXMOUNT_BROWSER_CLI_VERSION } else { "1.4.0" }
$downloadBaseUrl = if ($env:LEXMOUNT_BROWSER_CLI_DOWNLOAD_BASE_URL) { $env:LEXMOUNT_BROWSER_CLI_DOWNLOAD_BASE_URL.TrimEnd('/') } else { "https://cli-bin-1377899528.cos.ap-nanjing.myqcloud.com/releases/browser-cli" }
$architecture = if ($env:PROCESSOR_ARCHITEW6432) { $env:PROCESSOR_ARCHITEW6432 } else { $env:PROCESSOR_ARCHITECTURE }
if ($architecture -ne "AMD64") { throw "Only Windows x64 is supported" }
Expand Down
5 changes: 3 additions & 2 deletions skills/lexmount-browser/scripts/bootstrap.sh
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
#!/bin/sh
set -eu

version="${LEXMOUNT_BROWSER_CLI_VERSION:-1.3.0}"
version="${LEXMOUNT_BROWSER_CLI_VERSION:-1.4.0}"
download_base_url="${LEXMOUNT_BROWSER_CLI_DOWNLOAD_BASE_URL:-https://cli-bin-1377899528.cos.ap-nanjing.myqcloud.com/releases/browser-cli}"
repo="${download_base_url%/}/v${version}"
case "$(uname -s)-$(uname -m)" in
Linux-x86_64) target="x86_64-unknown-linux-musl" ;;
Darwin-arm64) target="aarch64-apple-darwin" ;;
*) echo "Unsupported platform: $(uname -s) $(uname -m). This release supports macOS arm64 and Windows x86_64." >&2; exit 2 ;;
*) echo "Unsupported platform: $(uname -s) $(uname -m). This release supports Linux x86_64, macOS arm64 and Windows x86_64." >&2; exit 2 ;;
esac

asset="browser-cli-v${version}-${target}"
Expand Down
3 changes: 2 additions & 1 deletion skills/lexmount-browser/scripts/doctor.sh
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
#!/bin/sh
set -eu
case "$(uname -s)-$(uname -m)" in
Linux-x86_64) ;;
Darwin-arm64) ;;
*) echo '{"ok":false,"error":"unsupported_platform","message":"This Skill supports macOS arm64 through scripts/doctor.sh and Windows x64 through scripts/doctor.ps1."}'; exit 2 ;;
*) echo '{"ok":false,"error":"unsupported_platform","message":"This Skill supports Linux x86_64 and macOS arm64 through scripts/doctor.sh and Windows x64 through scripts/doctor.ps1."}'; exit 2 ;;
esac
skill_dir="$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)"
if [ -x "$skill_dir/bin/browser-cli" ]; then exec "$skill_dir/bin/browser-cli" doctor; fi
Expand Down
Loading
Loading