# Glasswarp — Agent Setup Skill

Glasswarp gives an AI agent **eyes and hands on a real Windows machine**:
native-resolution vision and native input through one API. The customer supplies
the brain (model, prompts, and task logic).

Follow every step. Do not claim setup is complete until the verification step
passes.

## Step 1: Inspect the project and ask one question

Before installing anything, inspect:

- Language, framework, and runtime versions
- Package manager and dependency files
- Project structure, entry points, tests, and file conventions
- Existing agent/computer-use code
- Existing environment-variable and secrets conventions

Then ask:

> Should I add Glasswarp to this existing project, or create a minimal Python
> quickstart alongside it?

The supported SDK is Python 3.9+. If the existing project is not Python, explain
that clearly and offer either:

1. A small Python worker/sidecar using the supported SDK, or
2. Direct REST integration from the existing language using
   `https://docs.glasswarp.com`.

Do not silently introduce a second runtime.

## Step 2: Install dependencies using the project's package manager

Core SDK dependencies are managed by the package: `httpx>=0.24`.

Use the command matching the project:

```bash
# pip / venv
python -m pip install glasswarp

# uv
uv add glasswarp

# Poetry
poetry add glasswarp

# Pipenv
pipenv install glasswarp
```

If the project uses `requirements.txt` or `pyproject.toml`, update that file
rather than installing an untracked dependency.

For grounding helpers, ROI processing, or image inspection, install the optional
Pillow dependency:

```bash
python -m pip install "glasswarp[grounding]"
# or: uv add "glasswarp[grounding]"
# or: poetry add "glasswarp[grounding]"
```

Do not install the grounding extra for the basic session/input loop.

If PyPI reports that `glasswarp` is unavailable, do not install a similarly
named package. Tell the user the public package has not been released yet and
ask for the approved SDK repository or package artifact. When working inside
the Glasswarp monorepo, install the local SDK with:

```bash
python -m pip install -e sdk/python
```

## Step 3: Collect credentials safely

Ask the user to create an API key at:

`https://www.glasswarp.com/console` → **API Keys**

Sign-up is at `https://www.glasswarp.com/signup`.

Store the key as `GLASSWARP_API_KEY` using the project's existing secrets
convention. Never print, commit, or hardcode the key.

- If the project already loads `.env`, add `GLASSWARP_API_KEY` to `.env` and
  add only a placeholder to `.env.example`.
- If it uses a secret manager, follow that system.
- Add `python-dotenv` only when the project needs local `.env` loading and does
  not already provide it.

## Step 4: Guide the human through Windows host setup

A real Windows host is a product requirement, not an error. The coding agent
cannot complete this physical-machine step for the user.

Tell the user:

1. On the Windows machine, download and install the Glasswarp host agent from
   `https://www.glasswarp.com/downloads`.
2. Sign in and pair the machine once.
3. Open `https://www.glasswarp.com/console` → **Rigs**.
4. Confirm the rig is online.
5. Enable **API access** for that rig. It is off by default and requires owner
   consent.

Pause and ask the user to confirm that an online, API-enabled rig appears in the
console. Continue after confirmation. Do not ask for remote-machine passwords
or attempt to bypass owner consent.

## Step 5: Create or integrate

For a fresh quickstart, create a small file matching the project's conventions
(for example `glasswarp_quickstart.py`). For an existing agent, put the
Glasswarp adapter at the existing integration boundary; do not mix prompts or
task logic into the transport client.

Use this minimal, safe loop:

```python
import os

from glasswarp import GlasswarpClient

gw = GlasswarpClient(api_key=os.environ["GLASSWARP_API_KEY"])

rigs = gw.list_rigs()
rig = next(
    (r for r in rigs if r.online and r.api_access_enabled),
    None,
)
if rig is None:
    raise RuntimeError("No online rig with API access enabled")

session = gw.create_session(rig_id=rig.id, mode="desktop")
sid = session.session_id

try:
    shot = gw.screenshot(sid)                 # eyes: native-resolution JPEG
    with open("glasswarp_first_frame.jpg", "wb") as output:
        output.write(shot.jpeg)

    gw.click(sid, x=500, y=400)               # hands: native input
    gw.type_text(sid, "Hello from an agent")
finally:
    gw.end_session(sid)                       # always end metered sessions
```

Useful primitives:

- `screenshot(sid)` — native-resolution JPEG
- `observe(sid)` — JPEG + dirty regions + grounding targets
- `list_targets(sid)` / `click_target(...)` — UIA roles, names, and bounds
- `click`, `type_text`, `key_press`, `drag`, `mouse_down`, `mouse_up` — input
- `launch_app(sid, path)` — launch a Windows application
- Console **Sessions → Eye** — human Live View at 60fps

Rules:

- Always end sessions in `finally`; sessions meter usage.
- Reuse the project's logging/error conventions.
- Do not log API keys or full sensitive screenshots.
- Glasswarp supplies eyes, hands, and safe session controls. Prompts, CV,
  solvers, and agent decisions remain customer code.

## Step 6: Verify and fix

Run the integration and verify all of the following:

1. The SDK imports in the project's actual environment.
2. `list_rigs()` returns an online rig with API access enabled.
3. A desktop session starts.
4. `glasswarp_first_frame.jpg` is a non-empty valid JPEG.
5. The session appears at **Console → Sessions** and can be opened in Live View.
6. The session ends even if an action fails.

Run the project's formatter, type checker, and relevant tests after integration.

Common failures:

- `No matching distribution found` — PyPI release is not live; use only an
  approved package artifact/repository.
- `401` — missing, expired, or invalid `GLASSWARP_API_KEY`.
- No eligible rig — host offline or API access disabled in **Console → Rigs**.
- Request timeout — verify the host remains online and retry once.
- Input/drag not recognized — update the Windows host agent.
- Screenshot succeeds but model misses targets — use `observe()` or
  `list_targets()` instead of guessing coordinates.

Report exactly what was installed, which files changed, what command was run,
and which verification checks passed.

## Reference

- API reference: `https://docs.glasswarp.com`
- Host download: `https://www.glasswarp.com/downloads`
- Console: `https://www.glasswarp.com/console`
- Example code: `sdk/python/examples/` in the approved SDK repository