browser agent

# valoswiss-browser-agent (32°)

**Macro-categoria**: 🌐 INFRA/AI/META
**Scope**: Safe browser automation per due-diligence scraping, peer benchmark extraction, document download da portali bancari/broker. Stagehand pattern (act/extract/observe) con Zod schema validation. Domain allowlist + AuthVault scoped credentials. Headless Chromium PM2-managed.
**Born**: 2026-05-03 (W1 sidecar Node + W2 NestJS module + W3 frontend + W4 admin/cron)
**Owner downstream**: SUPERVISOR/ADMIN (trigger scraping jobs) · ADVISOR (vista risultati estratti)
**Last aligned**: 2026-05-03 V20

---

## §0 · Pre-flight check (entry rituale dell'agente)

Prima di ogni intervento, verifica in quest'ordine:

1. **Branch + working tree**
   ```bash
   cd ~/git/valoswiss && git status --short && git log -3 --oneline
   ```
2. **Sidecar Node health**
   ```bash
   curl -s http://127.0.0.1:8901/healthz | jq .
   ```
   Deve ritornare `{"status":"ok","version":"...","chromium":"ready","activeSessions":0}`. Se 502/connection refused → sidecar PM2 down: `pm2 list | grep browser-agent`.
3. **NestJS proxy health**
   ```bash
   curl -s http://127.0.0.1:4010/api/browser-agent/health -H "Cookie: valo_token=<dev-token>"
   ```
   Deve ritornare `{ sidecar:{status:'ok'}, circuitBreaker:{state:'closed', failures:0}, domainAllowlist:{count:N} }`.
4. **Prisma schema sync**
   ```bash
   cd apps/api && npx prisma migrate status
   ```
   Verifica che i 2 model `BrowserSession` / `BrowserExtract` + enum `BrowserSessionStatus` / `BrowserExtractType` siano applicati.
5. **Tenant configs**: `tenants/ws.json` e `tenants/az.json` devono avere `"browserAgent": true`.
6. **Persona pack**: `apps/api/src/common/persona-packs/persona-packs.constants.ts` deve avere `'browserAgent'` in `defaultModules` per `SUPERVISOR` + `ADMIN` (NON advisor-facing diretto).
7. **Module registry**: `apps/web/src/lib/module-registry.ts` deve esporre entry `browserAgent` con `sidebarSection: 'INFRA'`, `requiredRole: 'SUPERVISOR'`, `personaHint: 'automation'`, icon `🌐`.
8. **Domain allowlist check**: `services/browser-agent/config/domain-allowlist.json` deve esistere con almeno 1 entry. R-Audit gate OBBLIGATORIO se il file viene modificato.
9. **R-Audit gate**: prima di qualsiasi commit su file CRITICAL (vedi §3), eseguire `npx tsx scripts/r-audit.ts <file> --validate-business-logic`.

Se uno qualunque degli 9 punti fallisce, **fermati e annota la deviazione** prima di procedere — la 3-Point Registration è invariante non negoziabile (vedi `feedback_new_module_registration.md`).

---

## §1 · Aree di competenza

### 1.1 Stack tecnico (repos di riferimento)

| Repo | Stars | Ruolo |
|---|---|---|
| **browserbase/stagehand** (Apache 2.0) | 10k+ | Framework primario: `act/extract/observe` + Zod schema typed extraction |
| **browser-use/browser-use** (MIT) | 91k | Full autonomous agent browser — fallback tasks complessi, LLM-driven navigation |
| **vercel-labs/agent-browser** | — | Auth Vault pattern + Domain Allowlist enforcement — reference security model |
| **niuzaisheng/ScreenAgent** | — | Screen understanding per portali legacy senza API strutturate |

### 1.2 Pattern operativo Stagehand (primario)

Stagehand è il framework principale per tutte le sessioni controllate (use case: scraping strutturato, form fill, document download):

```typescript
// Pattern Stagehand act/extract/observe
const stagehand = new Stagehand({ env: 'LOCAL', verbose: 1 });
await stagehand.init();
const page = stagehand.page;

// 1. Navigate con domain allowlist check
await this.domainGuard.assertAllowed(targetUrl);  // throw se fuori allowlist
await page.goto(targetUrl);

// 2. Observe — capisce struttura pagina
const structure = await stagehand.observe();

// 3. Act — esegue azione descritta in linguaggio naturale
await stagehand.act({ action: "click on login button" });
await stagehand.act({ action: "fill username field with value {username}", variables: { username } });

// 4. Extract — estrae dati strutturati con Zod schema
const data = await stagehand.extract({
  instruction: "extract all fund performance data from the table",
  schema: FundPerformanceSchema,  // Zod schema
});
```

### 1.3 Tier sessioni

| Tier | Framework | Use case | Timeout |
|---|---|---|---|
| `stagehand-controlled` | Stagehand act/extract/observe | Scraping strutturato, form, download | 120s |
| `browser-use-autonomous` | browser-use agent | Task complessi multi-step, portali legacy | 300s |
| `screen-agent` | ScreenAgent | Portali senza CSS/DOM accessibile | 180s |

### 1.4 Domain Allowlist (sicurezza critica)

**NESSUNA sessione browser può navigare fuori dal domain allowlist**. Questo è il gate di sicurezza primario.

File SSOT: `services/browser-agent/config/domain-allowlist.json`

```json
{
  "version": "1.0",
  "updatedAt": "2026-05-03",
  "updatedBy": "ops",
  "domains": [
    { "domain": "morningstar.com",      "category": "peer-benchmark", "allowSubdomains": true },
    { "domain": "bloomberg.com",        "category": "market-data",    "allowSubdomains": false },
    { "domain": "refinitiv.com",        "category": "market-data",    "allowSubdomains": true },
    { "domain": "sec.gov",              "category": "regulatory",     "allowSubdomains": true },
    { "domain": "finma.ch",             "category": "regulatory",     "allowSubdomains": true },
    { "domain": "six-group.com",        "category": "market-data",    "allowSubdomains": true },
    { "domain": "fundinfo.com",         "category": "fund-data",      "allowSubdomains": true },
    { "domain": "swissfunddata.ch",     "category": "fund-data",      "allowSubdomains": true },
    { "domain": "ethenea.com",          "category": "peer-benchmark", "allowSubdomains": true },
    { "domain": "pictet.com",           "category": "peer-benchmark", "allowSubdomains": false }
  ]
}
```

**R-Audit rule `BROWSER-AGENT-DOMAIN-WHITELIST.md`**: ogni modifica al file allowlist richiede gate R-Audit + approval SUPERVISOR/ADMIN. Nessun agente Claude può aggiungere domini autonomamente.

### 1.5 AuthVault — scoped credentials

Le credenziali di portali bancari/broker sono gestite da vault-pii con scoping per dominio:

```typescript
// credential lookup — NON in env variables globali
const creds = await this.vaultPii.getCredential({
  domain: 'morningstar.com',
  tenantSlug: dto.tenantSlug,
  credentialType: 'BROWSER_SESSION',
});
// → { username: '...', password: '...', ttl: 3600 }
// Credenziale usata una sola volta per sessione, poi scartata dalla memoria
```

**PROTOTYPE-PHASE**: Auth Vault implementato come lookup vault-pii. GDPR + sicurezza credenziali bancarie come signal target post-prototipo (audit trail completo, rotation automatica, MFA support).

---

## §2 · Pattern di codice

### 2.1 NestJS Module structure

```
apps/api/src/modules/browser-agent/
├─ browser-agent.module.ts
├─ browser-agent.controller.ts     # Roles SUPERVISOR/ADMIN (trigger) + ADVISOR (read results)
├─ browser-agent.service.ts        # facade
├─ browser-agent.cron.ts           # @Cron scheduled scraping jobs
├─ services/
│   ├─ session-runner.service.ts   # Prisma persist + Wave 1.6 getter espliciti
│   ├─ sidecar.client.ts           # circuit breaker 3-fail/30s → browser-agent :8901
│   ├─ domain-guard.service.ts     # domain allowlist enforcement
│   ├─ auth-vault.service.ts       # scoped credential lookup via vault-pii
│   └─ extract-processor.service.ts # post-extract Zod validation + persist
├─ types/
│   ├─ browser-session.zod.ts
│   ├─ browser-extract.zod.ts
│   └─ domain-allowlist.schema.ts
└─ README.md
```

### 2.2 Prisma schema (Wave 1.6 compliant)

```prisma
model BrowserSession {
  id              String               @id @default(cuid())
  tenantSlug      String
  jobType         String               // 'PEER_BENCHMARK' | 'FUND_DATA' | 'REGULATORY' | 'DUE_DILIGENCE' | 'PSD2_FALLBACK'
  targetDomain    String
  targetUrl       String
  tier            String               @default("stagehand-controlled")
  status          BrowserSessionStatus
  triggeredBy     String               // userId o 'CRON'
  durationMs      Int?
  pagesVisited    Int                  @default(0)
  extractCount    Int                  @default(0)
  errorMessage    String?
  startedAt       DateTime             @default(now())
  endedAt         DateTime?
  createdAt       DateTime             @default(now())
  updatedAt       DateTime             @updatedAt
  extracts        BrowserExtract[]

  @@index([tenantSlug, status])
  @@index([tenantSlug, jobType, startedAt(sort: Desc)])
  @@index([triggeredBy, startedAt(sort: Desc)])
}

model BrowserExtract {
  id              String              @id @default(cuid())
  sessionId       String
  extractType     BrowserExtractType
  sourceUrl       String
  sourceDomain    String
  rawData         Json
  structuredData  Json?               // post-Zod validated
  zodSchema       String              // schema name used for validation
  isValid         Boolean             @default(false)
  validationErrors Json?
  downloadPath    String?             // se extract è un file scaricato
  createdAt       DateTime            @default(now())
  session         BrowserSession      @relation(fields: [sessionId], references: [id])

  @@index([sessionId, createdAt])
  @@index([tenantSlug: false, extractType, createdAt(sort: Desc)])
}

enum BrowserSessionStatus {
  PENDING
  ACTIVE
  COMPLETED
  FAILED
  ABORTED
}

enum BrowserExtractType {
  FUND_PERFORMANCE
  PEER_BENCHMARK
  DOCUMENT_PDF
  REGULATORY_FILING
  NAV_DATA
  PORTFOLIO_STATEMENT
  CUSTOM_JSON
}
```

**Wave 1.6 — getter espliciti obbligatori** su `TenantPrismaService`:
```typescript
// NON usare legacy cast as-any su prisma — pre-commit triage blocca
get browserSession() { return this.client.browserSession; }
get browserExtract()  { return this.client.browserExtract; }
```

### 2.3 NestJS controller pattern

```typescript
@Controller('browser-agent')
@UseGuards(JwtAuthGuard, RolesGuard)
export class BrowserAgentController {
  constructor(private readonly browserAgentService: BrowserAgentService) {}

  // SUPERVISOR/ADMIN: trigger scraping job
  @Post('sessions')
  @Roles('SUPERVISOR', 'ADMIN')
  async triggerSession(
    @Body() dto: TriggerSessionDto,
    @Request() req: AuthenticatedRequest,
  ) {
    const triggeredBy = req.user?.id;  // NON field variant legacy — Wave 1.6
    return this.browserAgentService.triggerSession({ ...dto, triggeredBy });
  }

  // ADVISOR+: lista sessioni + risultati
  @Get('sessions')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async listSessions(@Query() query: ListSessionsQueryDto) {
    return this.browserAgentService.listSessions(query);
  }

  // ADVISOR+: drill-down sessione + extracts
  @Get('sessions/:id')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async getSession(@Param('id') id: string) {
    return this.browserAgentService.getSession(id);
  }

  // SUPERVISOR/ADMIN: domain allowlist management
  @Get('allowlist')
  @Roles('SUPERVISOR', 'ADMIN')
  async getAllowlist() {
    return this.browserAgentService.getAllowlist();
  }

  // Admin: health
  @Get('health')
  @Roles('ADVISOR', 'RELATIONSHIP_MANAGER', 'SUPERVISOR', 'ADMIN')
  async health() {
    return this.browserAgentService.health();
  }
}
```

### 2.4 Sidecar Node :8901 (Stagehand + Playwright)

```typescript
// services/browser-agent/src/app.ts
import express from 'express';
import { Stagehand } from '@browserbasehq/stagehand';
import { chromium } from 'playwright';

const app = express();
app.use(express.json());

const sessionStore = new Map<string, SessionState>();

app.get('/healthz', (req, res) => {
  res.json({
    status: 'ok',
    version: '1.0.0',
    chromium: 'ready',
    activeSessions: sessionStore.size,
  });
});

app.post('/sessions/start', async (req, res) => {
  const { sessionId, targetUrl, jobType, tier, credential } = req.body;

  // Domain guard FIRST — prima di aprire browser
  const allowed = isDomainAllowed(targetUrl

…[truncato — apri il file MD per testo completo]