Skip to content

Commit de4b210

Browse files
CyrusNuevoDiaCyrusNuevoDia
committed
update cursorrules
1 parent 588191d commit de4b210

File tree

5 files changed

+161
-0
lines changed

5 files changed

+161
-0
lines changed

‎.cursor/rules/browser-agent-api.mdc‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,54 @@
1+
---
2+
description: browser-agent-api
3+
---
4+
### Endpoint
5+
6+
- `POST /apps/browser-agent/actions/perform` (Kernel action: `perform` in [main.py](mdc:main.py))
7+
8+
### Request body (JSON)
9+
10+
```json
11+
{
12+
"input": "Describe the task to perform",
13+
"provider": "anthropic|gemini|openai",
14+
"model": "<model-name>",
15+
"api_key": "<provider-api-key>",
16+
"instructions": "optional extra instructions",
17+
"stealth": true,
18+
"headless": false,
19+
"browser_timeout": 60,
20+
"max_steps": 100,
21+
"reasoning": true,
22+
"flash": false
23+
}
24+
```
25+
26+
Fields and defaults are defined in [lib/models.py](mdc:lib/models.py) (`BrowserAgentRequest`). Required: `input`, `provider`, `model`, `api_key`.
27+
28+
### Response body (JSON)
29+
30+
```json
31+
{
32+
"session": "<browser-session-id>",
33+
"success": true,
34+
"duration": 42.1,
35+
"result": "Task completion summary",
36+
"downloads": { "file.pdf": "https://..." }
37+
}
38+
```
39+
40+
Built by [main.py](mdc:main.py) with `BrowserAgentResponse.from_run(...)`.
41+
42+
### LLM provider routing
43+
44+
- Providers mapped in [lib/ai.py](mdc:lib/ai.py) via Cloudflare AI Gateway.
45+
- Required env: `AI_GATEWAY_URL`, `AI_GATEWAY_TOKEN`.
46+
47+
### Browser/session behavior
48+
49+
- Browser created via Kernel in [lib/browser.py](mdc:lib/browser.py) with fixed viewport and `auto_download_pdfs=True`.
50+
- Downloads detected via [lib/patch.py](mdc:lib/patch.py) watchdog patch and returned as presigned URLs after upload.
51+
152
---
253
description: API contract for `browser-agent` action and request model
354
globs: src/**/*.py

‎.cursor/rules/dev-commands.mdc‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,30 @@
1+
---
2+
description: dev-commands
3+
---
4+
### Development and tooling commands
5+
6+
Defined in [justfile](mdc:justfile):
7+
8+
```bash
9+
# Run local dev server (uvicorn)
10+
just dev
11+
12+
# Deploy to Kernel (entrypoint: main.py)
13+
just deploy
14+
15+
# Tail service logs
16+
just logs
17+
18+
# Format and lint (ruff)
19+
just fmt
20+
just lint
21+
22+
# Kernel CLI passthrough
23+
just kernel <args>
24+
```
25+
26+
Prereqs: `uv`, `just`, Node.js with `bun` for CLI tooling. See [README.md](mdc:README.md).
27+
128
---
229
description: Quick reference for dev commands and formatting
330
---

‎.cursor/rules/env-config.mdc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,28 @@
1+
---
2+
description: env-config
3+
---
4+
### Required environment variables
5+
6+
- **AI Gateway** (used in [lib/ai.py](mdc:lib/ai.py))
7+
- `AI_GATEWAY_URL`
8+
- `AI_GATEWAY_TOKEN`
9+
10+
- **Kernel platform** (used in [lib/browser.py](mdc:lib/browser.py))
11+
- `KERNEL_API_KEY`
12+
13+
- **Cloudflare R2 (S3 API)** for uploads (used in [lib/storage.py](mdc:lib/storage.py))
14+
- `R2_S3_BUCKET` (default: `browser-agent`)
15+
- `R2_S3_ENDPOINT_URL`
16+
- `R2_S3_ACCESS_KEY_ID`
17+
- `R2_S3_SECRET_ACCESS_KEY`
18+
19+
### Optional
20+
21+
- `BROWSER_USE_LOGGING_LEVEL` (e.g., `debug`)
22+
- `ANONYMIZED_TELEMETRY` (`false` to disable)
23+
24+
See example `.env` in [README.md](mdc:README.md). The app loads `.env` via `just` settings.
25+
126
---
227
description: Environment variables and .env usage for AI gateway and Kernel
328
---

‎.cursor/rules/project-structure.mdc‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,46 @@
1+
---
2+
alwaysApply: true
3+
---
4+
### Project structure and entrypoints
5+
6+
- **Entrypoint**: [main.py](mdc:main.py) defines the Kernel `App("browser-agent")` and the `perform` action that runs the browser agent.
7+
8+
### Key modules
9+
10+
- **LLM gateway and providers**: [lib/ai.py](mdc:lib/ai.py)
11+
- Maps `provider` → chat client (`anthropic`, `gemini`, `openai`) via Cloudflare AI Gateway (`AI_GATEWAY_URL`, `AI_GATEWAY_TOKEN`).
12+
13+
- **Request/response models**: [lib/models.py](mdc:lib/models.py)
14+
- `BrowserAgentRequest` (task, provider/model/api_key, browser flags, reasoning) and `BrowserAgentResponse` (session, success, duration, result, downloads).
15+
16+
- **Browser lifecycle**: [lib/browser.py](mdc:lib/browser.py)
17+
- `create_browser` creates a remote Kernel browser from `KERNEL_API_KEY`, returns `(session, browser)` with fixed viewport and auto PDF downloads.
18+
- `downloaded_files(agent)` collects files from the profile downloads path.
19+
20+
- **Browser patches**: [lib/patch.py](mdc:lib/patch.py)
21+
- `PatchedBrowser` and `PatchedDownloadsWatchdog` ensure download events fire reliably (injects a synthetic `NavigationCompleteEvent`).
22+
23+
- **Storage (Cloudflare R2)**: [lib/storage.py](mdc:lib/storage.py)
24+
- Uploads downloaded files and trajectory JSON to R2; returns presigned URLs.
25+
26+
- **Async helpers**: [lib/asyncio.py](mdc:lib/asyncio.py)
27+
- `asyncify`/`syncify` wrappers used by storage uploads.
28+
29+
### Runtime flow
30+
31+
1. `POST /apps/browser-agent/actions/perform` is invoked (Kernel).
32+
2. [main.py](mdc:main.py) validates payload into `BrowserAgentRequest`.
33+
3. LLM client resolved from [lib/ai.py](mdc:lib/ai.py) using AI Gateway.
34+
4. Browser created via Kernel in [lib/browser.py](mdc:lib/browser.py), returning `session` and `browser`.
35+
5. `Agent(...).run(max_steps)` executes the task; downloads auto-captured.
36+
6. Files and trajectory uploaded via [lib/storage.py](mdc:lib/storage.py); response built from `AgentHistoryList`.
37+
38+
### Useful references
39+
40+
- [pyproject.toml](mdc:pyproject.toml): deps and dev tools
41+
- [README.md](mdc:README.md): API contract, examples, env
42+
- [justfile](mdc:justfile): `dev`, `deploy`, `logs`, `fmt`, `lint`
43+
144
---
245
alwaysApply: true
346
---

‎.cursor/rules/python-style.mdc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
1+
---
2+
description: python-style
3+
globs: *.py
4+
---
5+
### Python style for this repo
6+
7+
- **Typing**: Prefer explicit function signatures and precise types; avoid `Any`.
8+
- **Control flow**: Use guard clauses; handle errors meaningfully; avoid deep nesting.
9+
- **Comments**: Document non-obvious intent succinctly; no inline noise.
10+
- **Formatting**: Use ruff for lint/format (`just fmt` / `just lint`).
11+
- **Structure**: Keep modules small and purpose-driven (`lib/ai.py`, `lib/browser.py`, `lib/models.py`, etc.).
12+
- **I/O**: Centralize env and external I/O (Kernel, R2) in dedicated modules.
13+
14+
Follow repository conventions in [pyproject.toml](mdc:pyproject.toml) and commands in [justfile](mdc:justfile).
15+
116
---
217
globs: src/**/*.py
318
description: Python style guidance for this repo

0 commit comments

Comments
 (0)