@wenathlan/saddle 1.8.2 → 1.8.5

package/README.md

@@ -8,7 +8,7 @@
   <strong>Storage-backed jobs, scraping contracts and portable runners for Node.js.</strong><br/>
   <strong>Binary computing agent, agent browser, computer-use, scraper and packager.</strong><br/>
   <a href="https://github.com/wenathlan/saddle/actions/workflows/ci.yml"><img src="https://github.com/wenathlan/saddle/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
-  <a href="https://github.com/wenathlan/saddle/releases/tag/v1.8.2"><img src="https://img.shields.io/badge/release-v1.8.2-d35d3d" alt="Release 1.8.2" /></a>
+  <a href="https://github.com/wenathlan/saddle/releases/tag/v1.8.4"><img src="https://img.shields.io/badge/release-v1.8.4-d35d3d" alt="Release 1.8.4" /></a>
   <a href="https://github.com/wenathlan/saddle/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-202a2f" alt="GPL 3.0 license" /></a>
 </p>
 
@@ -109,7 +109,7 @@ The caller still chooses how to provide `fetcher`, browser transport, persistenc
 
 ## Browser extension
 
-Version 1.8.2 includes a pure JavaScript Manifest V3 reference surface in [`extension/`](extension/). It is deliberately narrow: the user invokes the action, the popup sends a versioned command, the service worker routes it, and an isolated content bridge returns bounded page metadata, visible text or a user initiated action result. The exported `permissionpolicy` keeps base permissions minimal and makes optional escalation caller-owned.
+Version 1.8.4 includes a pure JavaScript Manifest V3 reference surface in [`extension/`](extension/). It is deliberately narrow: the user invokes the action, the popup sends a versioned command, the service worker routes it, and an isolated content bridge returns bounded page metadata, visible text or a user initiated action result. The exported `permissionpolicy` keeps base permissions minimal and makes optional escalation caller-owned.
 
 ```bash
 # load the unpacked extension from chrome://extensions
@@ -145,12 +145,12 @@ saddle mcp
 
 | Registry | Artifact | Workflow | Status |
 | --- | --- | --- | --- |
-| GitHub npm | `@wenathlan/saddle@1.8.2` | publishgithubnpm.yml | release candidate |
-| GHCR | `ghcr.io/wenathlan/saddle:1.8.2` and `latest` | publishghcr.yml | release candidate |
-| Maven | `io.wenathlan:saddle:1.8.2` | publishmaven.yml | release candidate |
-| NuGet | `Saddle.1.8.2.nupkg` | publishnuget.yml | release candidate |
-| RubyGems | `saddle 1.8.2` | publishrubygems.yml | release candidate |
-| npmjs | `@wenathlan/saddle@1.8.2` | publishnpmjs.yml | release candidate |
+| GitHub npm | `@wenathlan/saddle@1.8.5` | publishgithubnpm.yml | pending release |
+| GHCR | `ghcr.io/wenathlan/saddle:1.8.5` and `latest` | publishghcr.yml | pending release |
+| Maven | `io.wenathlan:saddle:1.8.5` | publishmaven.yml | pending release |
+| NuGet | `Saddle.1.8.5.nupkg` | publishnuget.yml | pending release |
+| RubyGems | `saddle 1.8.5` | publishrubygems.yml | pending release |
+| npmjs | `@wenathlan/saddle@1.8.5` | publishnpmjs.yml | pending release |
 
 ## Development
 
@@ -188,7 +188,7 @@ Root-based JavaScript ESM layout, no src/ directory, no TypeScript build require
 
 ## Current scope
 
-Version 1.8.2 establishes the engine contracts, browser snapshot foundation, storage sync primitives, runner recovery contracts, scraping context provenance and normalization, API/MCP security contracts, bot integration lifecycle, the tested extension bridge and permission policy, deterministic extension packaging, context-aware replay, desktop/mobile/n8n surface contracts, a framework-neutral operator control boundary and the first cross-runtime import boundary. Native runtimes, n8n host registration, provider credentials, persistent databases and production deployment remain caller-selected adapters. The next improvements should extend these contracts without coupling the core to one forge, registry, browser or storage vendor.
+Version 1.8.5 extends the 1.8.4 engine contracts with package metadata for Node.js 26.7.0 and npm 12, an optional Playwright peer, and an explicit Node-only `browser-playwright` adapter. Native runtimes, browser binaries, n8n host registration, provider credentials, persistent databases and production deployment remain caller-selected adapters. The next improvements should extend these contracts without coupling the core to one forge, registry, browser or storage vendor.
 
 ## License
 

package/browser/playwright.js

@@ -0,0 +1,22 @@
+/**
+ * browser playwright adapter keeps the optional Node browser provider outside the transport-neutral surface.
+ */
+
+/** Creates a caller-owned Playwright browser session when the optional peer is installed. */
+export async function createplaywrightsession(options = {}) {
+  let playwright;
+  try {
+    playwright = await import("playwright");
+  } catch (error) {
+    const missing = new Error("optional peer dependency 'playwright' is required for the Playwright adapter", { cause: error });
+    missing.code = "OPTIONAL_DEPENDENCY_MISSING";
+    throw missing;
+  }
+  const browsername = options.browser ?? "chromium";
+  const browsertype = playwright[browsername];
+  if (!browsertype || typeof browsertype.launch !== "function") throw new TypeError(`unsupported Playwright browser: ${browsername}`);
+  const browser = await browsertype.launch({ headless: options.headless ?? true, ...(options.launch ?? {}) });
+  const context = await browser.newContext(options.context ?? {});
+  const page = await context.newPage();
+  return { browser, context, page, close: () => browser.close() };
+}

package/docs/gapmatrix.md

@@ -16,12 +16,12 @@ This matrix turns the supplied README and conclusions into implementation decisi
 | Area | Current state | Gap | Priority | Decision |
 | --- | --- | --- | --- | --- |
 | Root library | Implemented ESM entry point with broad exports | No extension subpath or extension files are shipped | P0 | Add a small `extension/` package surface and export only serializable contracts |
-| Browser agent | Implemented injected action adapter for navigate, click, type, screenshot, DOM, title, scroll and command batches | Vendor-neutral action results and bounded action batches are now public | P1 | Keep the adapter boundary; add vendor adapters without moving browser ownership into the core |
+| Browser agent | Implemented injected action adapter for navigate, click, type, screenshot, DOM, title, scroll and command batches | Vendor-neutral action results and bounded action batches are public; optional Playwright provider is isolated behind `browser-playwright` | P1 | Keep the adapter boundary; browser binaries and credentials remain caller-owned |
 | Browser snapshots | Implemented public contract | Snapshot ids, bounded elements, stable refs, stale checks and diffs are covered by deterministic tests | P0 | Reuse the contract from MCP and extension transport |
 | Session replay | Implemented | Replay restores caller-owned window, tab and frame context before actions; context identifiers are validated and counted | P1 | Keep browser selection and restoration in injected adapters |
 | Extension runtime | Surface is only declared in `surfaces/manifest.js` and `surfaces/targets.js` | No Manifest V3 manifest, service worker, content bridge, popup or build artifact | P0 | Implement a pure JavaScript MV3 reference surface with minimal permissions |
 | Extension messaging | Not implemented | No versioned envelope, correlation id, timeout, sender metadata or error response contract | P0 | Add transport-neutral message contracts and Chrome runtime adapter |
-| Service worker resilience | Not implemented | No rehydration or durable state strategy for worker termination | P0 | Persist pending command metadata and session summaries through injected storage |
+| Service worker resilience | Implemented contract slice | Pending command envelopes, attempt metadata and snapshot summaries persist through injected storage; resume remains explicit and user-owned | P0 | Rehydrate metadata on startup and never replay a command without an explicit caller action |
 | Permissions | Contract slice | `permissionpolicy` keeps the base permissions minimal and optional escalation caller-owned | P0 | Start with `storage` and no broad host permissions; make host access caller-configured |
 | Content isolation | Not implemented | No isolated-world DOM bridge or page-to-extension boundary | P0 | Add a narrow content script that reports page facts through the message contract |
 | Task agent | Partial | Jobs, workflows and bot commands exist, but no browser task planner or tool registry | P1 | Reuse workflow, trigger and bot contracts; add browser task commands only after snapshots |
@@ -29,7 +29,7 @@ This matrix turns the supplied README and conclusions into implementation decisi
 | API security | Implemented URL protocol and private hostname/IP checks | Request envelopes, optional authorization, security headers, redirect bounds and injected DNS resolution checks are now available | P0 | Keep credentials caller-owned and reject private or rebinding targets before transport |
 | Apps and bots | Implemented platform adapter, commands, bot and webhook signature contracts | App install/suspend/revoke, command scope checks, idempotency and delivery retry/dead-letter records are now available | P1 | Keep platform tokens and OAuth lifecycle caller-owned |
 | Storage | Implemented local, chunked, S3-compatible, GitHub Contents and file hosting adapters | Range reads, content dedupe, tiered cache, capabilities and conflict-aware sync were missing | P1 | Use the new neutral storage helpers and keep extension storage injected |
-| Queue | Implemented in-memory and persistent queue contracts | No worker-aware resume protocol for extension commands | P1 | Add resumable command records and idempotency keys to extension transport |
+| Queue | Implemented in-memory, persistent and extension-resumable command contracts | Browser host still owns long-lived queue workers and cancellation policy | P1 | Keep command records serializable and resume explicit through the extension adapter |
 | Remote execution | Implemented provider, scheduler, health, triggers, heartbeat and resumable run contracts | No permissioned extension-to-runner bridge or forge-specific status adapters for every provider | P1 | Require explicit caller-provided endpoint and auth; no default remote host |
 | Scraping | Implemented robots, cache, HTML extraction, schema extraction, scraper and content normalization | Rich document parsers and binary format adapters remain caller-owned | P1 | Keep extraction safe and bounded; add adapters for richer document types |
 | Crawl | Implemented normalized BFS and persistent frontier | Priority and per-domain budget frontier now exist; sitemap refresh remains absent | P1 | Keep frontier state serializable and caller-persistable |

package/docs/libraryapi.md

@@ -39,6 +39,7 @@ The public API is designed around injected transports. Consumers can use the sam
 | `commandguard` | enforce caller-defined bot command scopes |
 | `deliveryqueue` | retry webhook deliveries and retain dead letters |
 | `nodeserver` | expose a Web Request/Response handler through Node HTTP |
+| `@wenathlan/saddle/browser-playwright` | optional Node-only Playwright session adapter; the peer is caller-installed and the root remains vendor-neutral |
 
 ```js
 import { scrapeurl, formatforagent } from "@wenathlan/saddle";

package/docs/packageaudit185.md

@@ -0,0 +1,23 @@
+# package metadata audit for 1.8.5
+
+The attached package manifest was used as a format reference, not as a dependency source. Its large application-oriented dependency graph, TypeScript build paths, workspace references and unrelated command names do not match the Saddle root-based JavaScript ESM library. Copying those entries would increase install cost, introduce unverified runtime coupling and weaken the transport-neutral package boundary.
+
+| Field | Decision | Reason |
+| --- | --- | --- |
+| `engines` | `node >=26.7.0`, `npm >=10.9.2` | matches the release toolchain and prevents silently testing on the older Node 22 floor |
+| `packageManager` | `npm@12.0.2` | records the current npm major used for the package contract without changing the existing release scripts |
+| `main`, `module`, `browser` | `./index.js` | gives older bundlers and browser-aware tooling a stable hint while `exports` remains authoritative |
+| `sideEffects` | `false` | the exported library modules are contract factories; CLI-only execution is guarded by direct-entry checks |
+| `peerDependencies.playwright` | `^1.62.1`, optional | the new explicit `browser-playwright` adapter dynamically loads a caller-installed provider |
+| `optionalDependencies` | not added | no optional package is required by a current implementation; an empty field would add no behavior |
+| `trustedDependencies` | not added | no install-time package script requires trust escalation; this is not an npm core field |
+| patch metadata | not added | no active dependency patch exists; pnpm 11 no longer reads settings from the `pnpm` field in `package.json` |
+
+The root entry remains free of Node-only imports and external runtime imports. The Playwright provider is only reachable through the explicit `./browser-playwright` subpath and is absent from the root transport-neutral graph. Consumers that do not need a browser provider do not need to install Playwright.
+
+## References
+
+1. [npm package.json documentation](https://docs.npmjs.com/cli/v12/configuring-npm/package-json/)
+2. [pnpm package.json documentation](https://pnpm.io/package_json)
+3. [Node.js package entry points and exports](https://nodejs.org/api/packages.html)
+4. [Playwright npm package](https://www.npmjs.com/package/playwright)

package/docs/plans/00.index.md

@@ -0,0 +1,50 @@
+# Index
+
+Project: **UKA** — computer use agent, sandbox for AI and captcha bypass. Super bot with computational memory. Package `@devthink/saddle`. Domain acquired.
+
+Theme: computer use, bypasses, captcha, sandbox for AI, container for AI, multi-platform bot, storage-to-compute memory transformation.
+
+## Planning Documents (`docs/plans`)
+
+| # | File | Subject |
+|---|------|---------|
+| 01 | [architecture.md](./01.architecture.md) | General system architecture |
+| 02 | [research.computer.use.md](./02.research.computer.use.md) | Research: computer use agents 2026 |
+| 03 | [research.captcha.bypass.md](./03.research.captcha.bypass.md) | Research: hcaptcha cloudflare recaptcha bypass |
+| 04 | [research.sandbox.ai.md](./04.research.sandbox.ai.md) | Research: virtual sandbox and containers for AI |
+| 05 | [capture.platform.md](./05.capture.platform.md) | Browser movement capture platform |
+| 06 | [dependencies.md](./06.dependencies.md) | 60+ project dependencies |
+| 07 | [captcha.test.page.md](./07.captcha.test.page.md) | Test page with hcaptcha cloudflare |
+| 08 | [production.infra.md](./08.production.infra.md) | Production infra (vercel/netlify) and sandbox backend |
+| 09 | [database.schema.md](./09.database.schema.md) | Database schema (drizzle/prisma/mysql2) |
+| 10 | [cloudinary.storage.md](./10.cloudinary.storage.md) | Data storage on cloudinary |
+| 11 | [movement.logs.json.md](./11.movement.logs.json.md) | JSON movement log format (brave) |
+| 12 | [research.atlas.agent.browser.md](./12.research.atlas.agent.browser.md) | Atlas: agent browser repos with same classification |
+| 28 | [action.plan.md](./28.action.plan.md) | Action plan and next steps |
+
+## Super Bot Documentation (`docs/plans`)
+
+| # | File | Subject |
+|---|------|---------|
+| 45 | [robotarchitecture.md](./45.robotarchitecture.md) | Super bot architecture overview |
+| 37 | [deploystrategy.md](./37.deploystrategy.md) | Deploy strategies (Netlify, Vercel, CI/CD, Docker, VM) |
+| 36 | [computational.memory.md](./36.computational.memory.md) | Storage-to-compute memory transformation system |
+| 39 | [multi.platform.bot.md](./39.multi.platform.bot.md) | Multi-platform bot (GitHub, GitLab, Forgejo, Gitea, Discord) |
+| 40 | [npm.publish.md](./40.npm.publish.md) | NPM package publishing (`@devthink/saddle`) |
+| 46 | [scdnintegration.md](./46.scdnintegration.md) | SCDN integration for assets and deployment |
+| 44 | [reference.md](./44.reference.md) | Reference index for all saddle documentation |
+| 33 | [bots.codigo.revisao.md](./33.bots.codigo.revisao.md) | Best AI code review bots (research) |
+| 32 | [bots.automacao.computacional.md](./32.bots.automacao.computacional.md) | Best computational automation bots (research) |
+| 34 | [bots.seguranca.cicd.md](./34.bots.seguranca.cicd.md) | Bot research (security + CI/CD) |
+
+## Folders
+
+- `docs/plans/` — planning and research (this index)
+- `docs/talks/` — decision transcripts
+- `docs/logs/` — JSON movement logs from Brave (`examplesession.json`)
+- `tests/` — unit tests (`examples/`, `output/`, `scripts/`)
+- `web/` — production site, deployed to Vercel or Netlify (files at root, no `src/`)
+
+## Phase Decision
+
+We are in **planning + research**. Platform implementation starts **only after user approval** (see `28.action.plan.md`).

package/docs/plans/01.architecture.md

@@ -0,0 +1,86 @@
+# 01 Architecture
+
+## Goal
+
+Build **UKA**, a computer use agent for ai that:
+
+1. Captures human movement in the browser (virtual mouse, virtual arrow, click, rotation, coordinates) in a real environment (brave / chromium).
+2. Exports movement as json logs to `docs/logs/`.
+3. Runs in a virtual sandbox to isolate ai agent execution.
+4. Faces strong captchas (hcaptcha, cloudflare turnstile, recaptcha) in controlled tests, opening test pages in brave.
+5. Persists data in production via a deployed site (vercel/netlify) plus db (drizzle/prisma/mysql2) plus cloudinary.
+
+## Architecture rules (skill arch)
+
+- No `src/` folder. Logic lives at the root of `web/`.
+- No vercel functions. No netlify functions. Use prisma, drizzle, mysql2, socket.
+- No localhost. Host is parametrized (`host`). Ports randomized then locked.
+- Files lowercase. No underscore. No hyphen. English docs. Jsdoc comments.
+- Logic grouped. Up to 20 related logics per file.
+- Runs as a library across modes (computer, browser, cli, binary, headless, etc).
+
+## Atlas (the browser)
+
+Atlas is the real browser component of UKA. It works across the 30 modes from the
+architecture skill (computer, browser, cli, binary, headless, etc) and its primary
+job is to bypass hcaptcha so the agent can act. It serves both the agent and the
+sandbox, and talks to our own database on vercel/netlify. See
+[12 research atlas agent browser](./12-research-atlas-agent-browser.md) for the
+prior-art survey and the p1 stealth / p2 vlm / p3 token fallback layering.
+
+## Components
+
+```
+atlas (web/atlas.js + deps)
+  - real browser across 30 modes
+  - stealth layer + hcaptcha bypass (vlm or token api fallback)
+  - feeds agent and sandbox
+
+capture ui (web/*.html + web/capture.js)
+  - virtual arrow / virtual mouse injected via cdp
+  - captures click, drag, scroll, coordinates, rotation
+  - exports json to docs/logs/
+
+sandbox (web/ + @vercel/sandbox)
+  - isolated firecracker microvm per session/agent
+  - chrome/brave ready, novnc streaming
+  - api https (post/get) to the deployed site
+
+production backend (web/, deployed to vercel/netlify)
+  - open node server (hono/express), not platform functions
+  - db (drizzle + mysql2 + prisma schema)
+  - cloudinary for assets and replays
+```
+
+## Main flows
+
+### A. Capture (local/dev)
+1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
+2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
+3. Record each event with timestamp, type, coordinates, target, rng seed.
+4. Compact trajectories and export to `docs/logs/<session>.json`.
+
+### B. Captcha test
+1. Open test page (`tests/examples/hcaptchatest.html` or a real site).
+2. Run solver (hcaptcha challenger / vision) or record manual bypass.
+3. Save evidence (screenshot, token, log) to `tests/output/`.
+
+### C. Production
+1. Agent calls the deployed site api (`web/`).
+2. Backend writes session to db (drizzle/mysql2) and assets to cloudinary.
+3. Logs and replays available via get https.
+
+## Key technologies (details in `06-dependencies.md`)
+
+- Browser automation: `playwright`, `puppeteer`, `chromium-bidi`, `@playwright/test`
+- Human mouse: `bezier-js`, `@napi-rs/canvas`, `d3`
+- Ai / vision: `ai`, `@ai-sdk/*`, `@xenova/transformers`, `onnxruntime-web`, `tesseract.js`
+- Sandbox: `@vercel/sandbox`, `vercel`
+- Server: `hono`, `express`, `cors`, `helmet`, `socket.io` (socket realtime)
+- Db: `drizzle-orm`, `mysql2`, `@prisma/client`, `prisma`
+- Storage: `cloudinary`
+- Validation: `zod`, `valibot`, `arktype`
+
+## Next steps
+
+See `action-plan.md`. Implementation starts after user approval.

package/docs/plans/02.research.computer.use.md

@@ -0,0 +1,58 @@
+# 02 — Pesquisa: Computer Use Agents (2026)
+
+## Estado da arte
+
+Em 2026, *computer-use agents* deixaram de ser protótipos e entraram em produção para
+tarefas restritas e supervisionadas. Principais provedores e frameworks:
+
+- **Anthropic Computer Use** (`computer_use_20251124`): ferramentas `computer` (mouse/teclado),
+  `text_editor`, `bash`. Recomenda rodar em **VMs/containers com privilégios mínimos**.
+- **OpenAI Operator / CUA**: 87% de sucesso em sites JS complexos; 58% no WebArena.
+- **Google Project Mariner**: 83.5% WebVoyager, 84% ScreenSpot.
+- **Microsoft UFO²**: funde Windows UI Automation + OmniParser (visão).
+- **browser-use** (open source): 89.1% WebVoyager (abordagem híbrida DOM + visão).
+
+### Benchmarks
+- **OSWorld:** humano 72.36% vs SOTA ~12–20% (desktop ainda imaturo).
+- **WebArena:** tops ~71%, produção na faixa 50–60%.
+- **WebVoyager:** browser-use 89.1% (híbrido).
+
+### Conclusão de arquitetura
+Ganham abordagens **híbridas**:
+1. Raciocínio por **DOM / accessibility tree** para elementos estruturados.
+2. **Visão** (VLM) para layouts não-padrão, canvas, imagens.
+3. **Scripts determinísticos** para validação e replay.
+4. **Verificação** (screenshot antes/depois, diff de elementos).
+
+## Projetos de referência encontrados
+
+| Projeto | Diferencial relevante para UKA |
+|---------|-------------------------------|
+| [agentbrowser](https://github.com/AshtonVaughan/agentbrowser) | Cursor visível humano via CDP, trilha SVG, trajetórias Bézier com jitter/overshoot, **traces JSONL** em `~/.agentbrowser/traces/`, replay determinístico por seed, bypass de Cloudflare/OneTrust |
+| [humanjs](https://github.com/totigm/humanjs) | Playwright humanizado: curvas Bézier, ritmo de digitação, scroll, **personalidades** (careful/fast/distracted/precise), gravador → JSON timeline, MCP server |
+| [human-browser-use](https://github.com/andyless/human-browser-use) | Extensão p/ browser-use: trajetória Bézier, typing lognormal, scroll inercial, stealth fingerprint (`navigator.webdriver`, WebGL, canvas) |
+| [agentic-stealth-browser](https://github.com/shanewas/agentic-stealth-browser) | TLS spoofing (JA3/JA4), fingerprint, recovery chain (detecta captcha → rotaciona proxy), account warming |
+| [mantis](https://github.com/mercurialsolo/mantis) | Agent perception-reasoning-action em Xvfb+Chrome+xdotool (sem fingerprint Playwright), vídeo screencast, deploy em Baseten/Modal/EKS/GKE |
+| [win-pilot-mcp](https://github.com/omidmanoochehri/win-pilot-mcp) | MCP Windows computer-use: screen capture, OCR, mouse humano, logging estruturado, replay de macros |
+| [cloakbrowser-human](https://github.com/evelaa123/cloakbrowser-human) | Wrapper Playwright que adiciona camada **comportamental** (mouse Bézier, typing, scroll) — complementa stealth de fingerprint |
+
+## Padrões de movimento humano (extraídos da pesquisa)
+
+- **Trajetória do mouse:** curva Bézier única, velocidade variável por arc-length:
+  - 0–5%: ramp-up (0.3x → 2.5x)
+  - 5–75%: cruise (2.3–2.5x) com variação senoidal
+  - 75–100%: ease-out cúbico (2.5x → 0.3x)
+  - sub-pixel drift final (σ 0.3–1.5px)
+  - duração via **Lei de Fitts**: `0.05 + 0.07*log2(1 + distance/20)` s
+- **Overshoot:** ~15% de chance, auto-aumenta em movimentos longos.
+- **Typing:** inter-key delay lognormal (μ=4.17, σ=0.3 → ~65ms), bigram speedup, 2% typo.
+- **Scroll:** wheel events com acel/decel, overshoot, settle delay.
+- **Stealth:** `navigator.webdriver → undefined`, spoof de plugins/WebGL/canvas, flags de launch.
+
+## Aplicação no UKA
+
+- Implementar `HumanCursor` (SVG overlay + CDP `Input.dispatchMouseEvent`) inspirado no
+  agentbrowser/humanjs, com trajetórias Bézier + jitter + overshoot determinísticas por seed.
+- Gravar **todos os eventos** como `SessionEvent` tipado → exportar JSON para `docs/logs/`.
+- Usar replay determinístico (seed) para testes reprodutíveis.
+- Tratar GUI como imagem (visão) + DOM/accessibility para alvos estruturados.

package/docs/plans/03.research.captcha.bypass.md

@@ -0,0 +1,68 @@
+# 03 — Pesquisa: hCaptcha / Cloudflare / reCAPTCHA Bypass
+
+## Contexto
+
+O UKA precisa **testar** a capacidade do computer-use de enfrentar captchas fortes. A
+pesquisa abaixo levanta abordagens open-source e comerciais (uso edUKAcional / automação
+supervisionada).
+
+## hCaptcha
+
+### hcaptcha-challenger (QIN2DIM) — referência principal
+- Resolve hCaptcha com **LLM multimodal** (sem Tampermonkey, sem serviço anti-captcha 3º).
+- Modelos plugáveis (ONNX):
+  - `image_label_binary` → ResNet ✅
+  - `image_label_area_select: point` → YOLOv8 ✅
+  - `image_label_area_select: bounding box` → YOLOv8 segmentation
+  - `image_drag_drop` → Spatial Chain-of-Thought ✅
+  - `image_label_multiple_choice` → ViT zero-shot
+- Pipeline: `install()` → `AgentT.from_page()` → `handle_checkbox()` → `execute()` loop.
+- Deps: `playwright`, `httpx`, `opencv-python`, `pillow`, `loguru`, `pydantic-settings`.
+
+### Outros solvers
+- **hCaptcha-Solver (Camoufox + Multibot):** usa Camoufox p/ HSW token + Groq vision +
+  **geração de movimento de mouse realista** (Multibot API). Lida com `image_label_binary`,
+  `area_select`, `drag_drop`. Requer proxy.
+- **maximedrn/hcaptcha-solver-python-selenium:** userscript Tampermonkey + Selenium (edUKAcional).
+- **auto-captcha-solver / auto-captcha (NopeCHA):** detecta hCaptcha, reCAPTCHA v2/v3,
+  Cloudflare Turnstile via **API de token NopeCHA**; injeta token automaticamente. Tem MCP
+  server e CLI. Tipos: hCaptcha ✅, reCAPTCHA v2/v3 ✅, Turnstile ⚠️ (lento).
+
+## Cloudflare (Turnstile / interstitials)
+
+- **agentic-stealth-browser** passa Cloudflare interstitial usando TLS spoofing + fingerprint
+  + comportamento humano + **recovery chain** (detecta captcha → rotaciona proxy/sessão → retry).
+- **auto-captcha** resolve Turnstile via NopeCHA (fila lenta, requer proxy em produção).
+- **captcha-solver (CloakBrowser + 2Captcha/CapSolver):** Turnstile resolvido em ~5s via
+  ClickSolver (free) ou fallback pago.
+
+## reCAPTCHA
+
+- v2/v3/Enterprise: cobertos por hcaptcha-challenger (via proxy), auto-captcha (NopeCHA),
+  2Captcha, CapSolver.
+
+## Capes (tipos suportados por 2Captcha/CapSolver — 30+)
+
+reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile, hCaptcha, FunCaptcha (Arkose), GeeTest,
+KeyCaptcha, Amazon WAF, DataDome, Akamai, Imperva, Friendly, MTCaptcha, Lemin, Cutcaptcha,
+Tencent, Yandex, ALTCHA, Prosopo, entre outros.
+
+## Camadas de defesa que o UKA deve considerar
+
+| Camada | O que ataca | Mitigação no UKA |
+|--------|-------------|------------------|
+| Fingerprint (WebDriver, CDP, headless, GPU) | detecta automação | stealth JS + Brave real/CDP, spoof WebGL/canvas |
+| Comportamental (mouse/keyboard/scroll) | analisa padrões | trajetórias Bézier humanas, typing lognormal |
+| TLS (JA3/JA4) | identifica cliente | TLS regional / proxy residencial sticky |
+| IP reputation | bloqueia faixas | proxies residenciais com sessão sticky |
+| Captcha | desafio final | solver VLM (hcaptcha-challenger) ou token API |
+
+## Aplicação no UKA
+
+- Criar `tests/examples/hcaptcha-test.html` (página de teste local) + usar sites reais fortes
+  (Cloudflare, Google reCAPTCHA demo, hCaptcha demo) no Brave.
+- Pipeline de teste: abrir → detectar captcha → resolver (VLM ou token API) → registrar
+  token/screenshot/log em `tests/output/`.
+- **Não** usar para abuso: foco em automação supervisionada e pesquisa.
+- Dependências relevantes: `playwright`, `puppeteer`, `@xenova/transformers`,
+  `onnxruntime-web`, `tesseract.js`, `cloudinary` (evidências).

package/docs/plans/04.research.sandbox.ai.md

@@ -0,0 +1,52 @@
+# 04 — Pesquisa: Sandbox Virtual e Containers para IA
+
+## Por que sandbox?
+
+Computer-use agents executam código/inputs não confiáveis (saída de LLM, uploads de
+usuário). Rodar em sandbox isola a execução, impede acesso ao sistema de produção e limita
+recursos. A pesquisa mostra que provedores ladearam para **microVMs Firecracker**.
+
+## Vercel Sandbox (opção principal do UKA)
+
+- Compute primitive para rodar código não confiável com segurança (AI agents, code gen).
+- **Firecracker microVM** por sandbox, filesystem e rede próprios, isolamento forte.
+- Runtimes: `node26/24/22`, `python3.13`. Default `node24`.
+- Cada sandbox roda como `vercel-sandbox` (sudo disponível), working dir `/vercel/sandbox`.
+- Startup em **milissegundos**; suporta Docker/FUSE dentro do microVM (privilégio elevado).
+- **Credential brokering:** injeta secrets em requests de saída sem expor dentro do VM
+  (`console.log(process.env)` não vaza a chave).
+- **Network policy:** allowlist de domínios, atualizável em runtime.
+- SDK JS e Python; CLI. Multi-agent isolation (usuário Linux por agente, grupos p/ compartilhar).
+
+### AI SDK Computer Use (vercel-labs) — template de referência
+- Next.js + AI SDK + Claude Sonnet 4.5 + **Vercel Sandbox**.
+- Snapshot pré-construído com: **Xvnc**, **openbox**, **noVNC + websockify**, **Google
+  Chrome**, **xdotool + ImageMagick**.
+- Fluxo: User ↔ Chat UI ↔ AI SDK ↔ Claude → Vercel Sandbox (desktop via noVNC iframe).
+- Ferramentas: `computer` (screenshot/click/type/scroll) + `bash`.
+- Env: `ANTHROPIC_API_KEY`, `SANDBOX_SNAPSHOT_ID`, `VERCEL_OIDC_TOKEN`/`VERCEL_TOKEN`.
+
+### vercel-labs/agent-browser (serverless)
+- CLI Rust nativo; roda agent-browser + Chrome em Vercel Sandbox microVM efêmero.
+- Helper `@agent-browser/sandbox/vercel` + `@vercel/sandbox`.
+
+### vercel-labs/sandcastle (PoC desktop)
+- Desktop Linux web sobre Vercel Sandbox. Stack: Next.js, Tailwind, **Zustand + SWR**,
+  **Neon Postgres + Drizzle ORM**, `@vercel/sandbox`, code-server, Xpra. Auth password/OAuth.
+
+## Outras opções
+
+- **Modal / Baseten / EKS / GKE** (usados pelo mantis) — containers Docker customizados.
+- **Daytona / Cloudflare** — alternativas de sandbox (citadas mas com menos fit p/ TS).
+- **Containers Docker locais** (xdotool + Xvfb + Chromium) para dev sem nuvem.
+
+## Decisão para o UKA
+
+- **Produção:** Vercel Sandbox como camada de execução do computer-use; site de controle
+  deployado em **Vercel** (ou Netlify) (`web/`).
+- **Banco:** criado no deploy (Drizzle/LibSQL ou Prisma em Neon/Turso), conforme `09-esquema-banco-dados.md`.
+- **Armazenamento:** Cloudinary para assets/replays (`10-cloudinary-storage.md`).
+- **Dev local:** Brave real via Playwright/CDP para a plataforma de captura (`05-plataforma-captura-movimentos.md`).
+- **Comunicação:** requests **POST/GET HTTPS** do agente → site deployado → DB + Cloudinary.
+- Dependências: `@vercel/sandbox`, `vercel`, `@netlify/blobs`, `@netlify/functions`,
+  `hono`/`express`, `drizzle-orm`, `@libsql/client`, `socket.io`.

package/docs/plans/05.capture.platform.md

@@ -0,0 +1,57 @@
+# 05 Capture Platform
+
+## Purpose
+
+Build a web platform that captures the user/agent movement inside the browser (focus: brave) and exports everything as json logs to `docs/logs/`. This is the base to train and replay the UKA computer use with human behavior.
+
+## Core concepts
+
+- Virtual mouse / virtual arrow: an svg cursor injected in the page (via cdp init script) that follows the real movement and draws a trail and click ripple.
+- Event capture: click, double click, drag, scroll, coordinates (x,y), rotation (scroll/wheel angle), timing, target (selector/role/text), deterministic seed.
+- Export: compacted json in `docs/logs/<session>.json`.
+
+## Platform architecture (root based, no src)
+
+```
+web/ (capture frontend)
+ ├─ index.html              # capture page
+ ├─ capture.js              # injects svg cursor + listeners
+ ├─ recorder.js             # collects sessionevent to buffer
+ └─ exporter.js             # serializes to docs/logs/<session>.json
+
+(root logic files, grouped per skill arch)
+ ├─ humancursor.js          # bezier + jitter + overshoot (cdp Input.dispatchMouseEvent)
+ ├─ trajectory.js           # path generator (ghost-cursor / humanjs inspired)
+ ├─ fingerprint.js          # stealth patches webgl/canvas/audio
+ ├─ recorder.js             # json event stream
+ ├─ replay.js               # deterministic replay by seed
+ └─ runcapture.js           # entrypoint (opens brave via cdp)
+```
+
+## Sessionevent format
+
+```ts
+type SessionEvent =
+  | { t: number; type: "move"; x: number; y: number; tx: number; ty: number }
+  | { t: number; type: "click"; x: number; y: number; button: "left"|"right"; target?: string }
+  | { t: number; type: "drag"; x0: number; y0: number; x1: number; y1: number }
+  | { t: number; type: "scroll"; dx: number; dy: number; angle: number }
+  | { t: number; type: "key"; key: string; target?: string }
+  | { t: number; type: string; [k: string]: unknown };
+```
+
+## How it works (summary)
+
+1. Open brave via playwright/chromium with `chrome.debugger` (cdp).
+2. Inject svg cursor sprite plus event listeners (`Input.dispatchMouseEvent`).
+3. Move the cursor humanly (bezier with jitter/overshoot), all via cdp, not locators.
+4. Each action emits a `SessionEvent` with timestamp, coordinates, target, seed.
+5. Compact trajectories (collapse move runs) and export to `docs/logs/`.
+
+## Relation with logs
+
+The final json format of `docs/logs/` files is detailed in `11-movement-logs-json.md`. An example log is at `docs/logs/examplesession.json`.
+
+## Dependencies involved
+
+`playwright`, `puppeteer`, `chromium-bidi`, `bezier-js`, `@napi-rs/canvas`, `d3`, `socket.io-client`, `zod` (event validation).

package/docs/plans/06.dependencies.md

@@ -0,0 +1,97 @@
+# 06 Dependencies
+
+Dependency list of the `@devthink/UKA` package, grouped by function. Total: 65 packages (including the dev tooling set). The user asked for "50 to 60, or 60+. Counting 10 more", so this set covers browser automation, ai/vision, sandbox, server, db, storage and validation.
+
+## Browser automation and mouse (8)
+1. `playwright` — real brave/chromium automation via cdp.
+2. `puppeteer` — fallback automation / stealth.
+3. `chromium-bidi` — bidi protocol for input control.
+4. `@playwright/test` — e2e tests for the platform and captcha.
+5. `bezier-js` — human mouse trajectory generation (bezier).
+6. `@napi-rs/canvas` — draw virtual cursor / trail / ripple.
+7. `d3` — movement trajectory visualization.
+8. `sharp` — screenshot/evidence processing.
+
+## Ai / vision / captcha (12)
+9. `ai` — ai sdk core.
+10. `@ai-sdk/anthropic` — claude (computer use).
+11. `@ai-sdk/google` — gemini (vision).
+12. `@ai-sdk/openai` — gpt (vision/reasoning).
+13. `@ai-sdk/react` — agent ui hooks.
+14. `@ai-sdk/vercel` — vercel integration.
+15. `@xenova/transformers` — local vlm models (onnx).
+16. `onnxruntime-web` — onnx inference in browser (yolo/resnet).
+17. `tesseract.js` — ocr for captcha/text.
+18. `openai` — raw sdk for vision/solvers.
+19. `comlink` — workers for inference in a separate thread.
+20. `jsdom` — virtual dom for parsing/tests.
+
+## Sandbox and deploy (3)
+21. `@vercel/sandbox` — firecracker microvm for isolated execution.
+22. `vercel` — cli/deploy to vercel.
+23. `nanoid` — short url-safe ids.
+
+> Note: `@netlify/functions` and `@netlify/blobs` were removed. The architecture skill rejects netlify/vercel functions and platform locked storage. Realtime uses socket. Db uses prisma/drizzle/mysql2.
+
+## Server / api (7)
+24. `hono` — light http api (production).
+25. `express` — alternative api / dev.
+26. `cors` — cors for agent requests.
+27. `helmet` — security headers.
+28. `socket.io` — realtime event streaming (socket).
+29. `socket.io-client` — replay/stream client.
+30. `multer` — file upload (tokens, evidence).
+
+## Database / orm (5)
+31. `drizzle-orm` — primary orm.
+32. `mysql2` — mysql driver (skill arch: data uses mysql2).
+33. `@prisma/client` — prisma client.
+34. `prisma` — cli/migrations.
+35. `yaml` — schema/env config.
+
+## Storage (1)
+36. `cloudinary` — upload replays, screenshots, assets.
+
+## Validation / types (3)
+37. `zod` — event/log schema.
+38. `valibot` — light validation.
+39. `arktype` — runtime types.
+
+## Logging (1)
+40. `pino` — structured (json) agent logs.
+
+## Frontend / build (8)
+41. `react` — platform ui.
+42. `react-dom` — react render.
+43. `next` — production web framework.
+44. `vite` — bundler.
+45. `@vitejs/plugin-react` — react plugin for vite.
+46. `tailwindcss` — styling.
+47. `@tailwindcss/vite` — tailwind+vite integration.
+48. `@testing-library/react` — component tests.
+49. `@testing-library/dom` — dom test utils.
+50. `@testing-library/jest-dom` — test matchers.
+
+## Media / util (4)
+51. `pngjs` — png read/write (click masks).
+52. `ffmpeg-static` — replay video recording.
+53. `@t3-oss/env-core` — typed env validation.
+54. `uuid` — session/agent ids.
+
+## Dev tooling (11 — the "10+")
+55. `typescript` — compiler.
+56. `@biomejs/biome` — lint/format.
+57. `vitest` — test runner.
+58. `@vitest/coverage-v8` — coverage.
+59. `tsx` — run ts without build.
+60. `@types/node` — node types.
+61. `@types/react` — react types.
+62. `@types/react-dom` — react dom types.
+63. `@ai-sdk/anthropic` (dev) — mirrored in devdeps.
+64. `@vercel/sandbox` (dev) — mirrored in devdeps.
+65. `prisma` (dev) — cli in devdeps.
+
+## Conventions
+- Files lowercase. No underscore. No hyphen.
+- English only. Jsdoc comments. Third person voice.
+- No hardcoded host. Use `host`. Ports randomized then locked.