free-computer-use 0.1.0

package/.env.example

@@ -0,0 +1,31 @@
+# openai-compatible, anthropic, codex-subscription or claude-subscription
+LLM_PROVIDER=openai-compatible
+LLM_API_KEY=
+LLM_MODEL=
+LLM_BASE_URL=https://api.deepseek.com
+# json_schema | json_object
+LLM_RESPONSE_FORMAT=json_object
+# Optional override. Defaults to max_completion_tokens for api.openai.com,
+# max_tokens for other OpenAI-compatible APIs.
+# LLM_MAX_OUTPUT_TOKENS_PARAM=max_tokens
+# For Anthropic Messages API, use LLM_PROVIDER=anthropic, set LLM_MODEL and
+# LLM_API_KEY, and keep LLM_RESPONSE_FORMAT=json_object.
+# Default base URL: https://api.anthropic.com/v1
+# For a ChatGPT plan, install Codex CLI, run `codex login`, then set
+# LLM_PROVIDER=codex-subscription. No LLM_API_KEY is needed for this mode.
+# Optional: set CODEX_CLI_PATH if `codex` is not on PATH.
+# For Claude Pro/Max, install Claude Code, run `claude auth login` without
+# `--console`, then set LLM_PROVIDER=claude-subscription. No API key is needed.
+# Claude Code v2.1.248+ is required. Optional: set CLAUDE_CLI_PATH if needed.
+# Optional: use an installed Chrome/Edge instead of Playwright's bundled Chromium.
+# FCU_BROWSER_CHANNEL=chrome
+# Optional prices, USD per million tokens. Leave blank for unknown cost.
+LLM_INPUT_PRICE=
+LLM_OUTPUT_PRICE=
+LLM_CACHED_INPUT_PRICE=
+# Local state; browser cookies, profile, traces and workflows stay here.
+FCU_DATA_DIR=.fcu
+# Optional total limits for a task. Unset means no model-call or token cap.
+# FCU_MAX_LLM_CALLS=100
+# FCU_MAX_INPUT_TOKENS=250000
+# FCU_MAX_OUTPUT_TOKENS=30000

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- Local Playwright browser workspace with explicit origin permissions, sensitive
+  action confirmation, result checks and compatible workflow replay.
+- API-key provider routes and local Codex / Claude Code subscription CLI routes.
+- Local dashboard, command-line diagnostics, synthetic practice lab and public
+  evidence reports.
+- Support, provider, security, local-data and reproducible validation guides.
+
+### Security and privacy
+
+- Browser profiles, traces, workflows and downloads stay in local storage, which
+  is not encrypted and has no automatic expiry.
+- Provider support and tested platform limits are listed in
+  [the support matrix](docs/SUPPORT_MATRIX.md).

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for helping make browser automation safer and easier to verify. Keep
+changes focused, preserve the local permission model, and include evidence for
+behavior changes.
+
+## Development setup
+
+The package declares Node.js `>=22.13.0`; only the environment in the
+[support matrix](docs/SUPPORT_MATRIX.md) is currently validated. Install Node,
+npm and a browser Playwright can launch. To use an already installed Chrome
+without downloading a browser, set `FCU_BROWSER_CHANNEL=chrome`.
+
+```sh
+git clone https://github.com/OthmaneBlial/FreeComputerUse.git
+cd FreeComputerUse
+npm ci
+cp .env.example .env
+chmod 600 .env
+```
+
+Run `npm run agent -- doctor` to check the local runtime, then `npm run dev` and
+open `http://127.0.0.1:4318`. The deterministic practice task works without a
+provider key. See [provider setup](docs/PROVIDERS.md) before opting into a live
+provider request.
+
+## Before opening a pull request
+
+```sh
+npm run check
+FCU_BROWSER_CHANNEL=chrome npm test
+npm run validate
+```
+
+`npm run validate` is the full local gate and includes the serial tests, build,
+security scan and production dependency audit. It needs registry access for the
+audit. The ordinary test suite uses local fixtures and does not call a model.
+The optional live benchmarks can spend API tokens; do not run them in a change
+that only needs deterministic coverage. See [local validation](docs/LOCAL_VALIDATION.md)
+for the exact scope and known limits.
+
+For browser behavior, add a focused regression test using the existing fixture
+helpers. Check both the denied case and an authorized case where applicable.
+For UI changes, run `FCU_BROWSER_CHANNEL=chrome npm run ui:smoke` or
+`npm run lab:smoke` and inspect any changed screenshots. Do not include real
+browser profiles, cookies, API keys or personal data in fixtures or reports.
+
+Use the existing TypeScript, Playwright and Zod patterns. Explain any new
+dependency and keep provider/network tests opt-in. GitHub Actions is disabled
+by owner instruction; do not add or dispatch workflows.
+
+## Issues and security reports
+
+Use the repository's bug or feature form. Include a small reproduction and
+versions, but remove API keys, tokens, cookies, private URLs and personal data
+from logs and screenshots. Report vulnerabilities privately through GitHub's
+private vulnerability reporting when it is enabled; do not file them as public
+issues.
+
+## Review and support policy
+
+Pull requests target `main` and should state the problem, behavior change,
+validation run and remaining limitation. There are no published releases or
+release branches yet, so `main` is the only maintained line. After the first
+release, the latest stable release and current `main` are the supported lines;
+older releases have no promised maintenance window. There is no LTS policy.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeComputerUse contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+<h1><img src="docs/brand-mark.svg" alt="" width="40" height="40" align="absmiddle"> FreeComputerUse</h1>
+
+![FreeComputerUse — a local-first browser agent that plans, acts and verifies with you in control](assets/readme/hero.svg)
+
+<p align="center">
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-c4e967?style=flat-square&labelColor=18251f"></a>
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-3178c6?style=flat-square&labelColor=18251f">
+  <img alt="Playwright" src="https://img.shields.io/badge/Playwright-45ba4b?style=flat-square&labelColor=18251f">
+  <img alt="Local-first" src="https://img.shields.io/badge/local--first-browser_runs-c4e967?style=flat-square&labelColor=18251f">
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="https://othmaneblial.github.io/FreeComputerUse/">Project site</a> ·
+  <a href="https://othmaneblial.github.io/FreeComputerUse/lab/index.html">Try the task lab</a> ·
+  <a href="SECURITY.md">Security</a>
+</p>
+
+**Your browser. Your model. Your call.** Tell it what done looks like, then stay in control of every step.
+
+FreeComputerUse is a local-first AI browser automation agent. A model plans small action batches; TypeScript and Playwright execute and verify them in your browser. Compatible workflows can be learned once and replayed later with **zero model calls**.
+
+## Watch a real run
+
+[![A real browser run: investigate a synthetic API incident and save a checked report](assets/readme/incident-demo.gif)](https://othmaneblial.github.io/FreeComputerUse/#watch)
+
+One goal led through six pages to a verified incident brief: **21 successful actions, 10 model calls, one repaired failure**. The configured cost estimate was **$0.00650**. This is one recorded synthetic task, not a general success-rate claim. [Watch the full recording](https://othmaneblial.github.io/FreeComputerUse/lab/media/incident-demo.mp4) · [Inspect the evidence](assets/readme/incident-evidence.json).
+
+## How it works
+
+1. **Observe** the page’s DOM and accessible controls.
+2. **Plan** a bounded batch with the model you choose.
+3. **Execute** browser actions locally with Playwright; direct navigation to a new origin asks for approval.
+4. **Verify** results, repair only what failed, then reuse compatible learned workflows.
+
+The model does not run shell commands or arbitrary JavaScript. Browser previews stay local; the goal and selected page context are sent to your configured model provider.
+
+## Quick start
+
+Requires **Node.js 22.13+**, npm and an installed browser. The verified setup is macOS 26.6 (Apple Silicon), Node 25.9.0 and system Chrome 154.0.8037.57; the complete serial validation passed on this combination. The declared Node minimum and other OS/browser combinations remain unverified. This setup selects installed Chrome and avoids a separate Playwright browser download; see the [support matrix](docs/SUPPORT_MATRIX.md) for exact coverage and limits.
+
+```bash
+git clone https://github.com/OthmaneBlial/FreeComputerUse.git
+cd FreeComputerUse
+npm ci
+cp .env.example .env
+chmod 600 .env
+```
+
+Set `FCU_BROWSER_CHANNEL=chrome` in `.env` to use the verified installed-Chrome path without downloading a browser binary.
+
+For model-planned tasks, configure a provider in `.env`. The browser sandbox task below works without a model key:
+
+```dotenv
+FCU_BROWSER_CHANNEL=chrome
+LLM_PROVIDER=openai-compatible
+LLM_API_KEY=your-key
+LLM_BASE_URL=https://api.deepseek.com
+LLM_MODEL=deepseek-flash
+```
+
+```bash
+npm run agent -- doctor
+npm run dev
+```
+
+Open **http://127.0.0.1:4318**, enter a starting URL and goal, then approve site access.
+
+**Try it without an API key:** open [the practice revenue table](https://othmaneblial.github.io/FreeComputerUse/lab/reports.html) and run the goal `Extract the table`. This narrow workflow has a deterministic local strategy; general tasks need a model provider.
+
+## Troubleshooting
+
+- **The browser does not start:** install Chrome, set `FCU_BROWSER_CHANNEL=chrome` in `.env`, then run `npm run agent -- doctor`. See the [verified platform limits](docs/SUPPORT_MATRIX.md); other OS/browser combinations are not certified here.
+- **The dashboard says no model is configured:** the practice revenue-table task works without a provider. For model planning, configure one route from [Pick your model](#pick-your-model). `npm run agent -- doctor --api` makes an opt-in request to the configured provider; use it only when you want that network check.
+- **A site is blocked or asks for approval:** normal mode asks before a new origin and blocks private/reserved DNS answers. Approve only the site needed for the task. Ultra mode disables those protections; do not use it as a workaround for a blocked destination.
+- **The run finishes without proving the goal:** inspect the result checks and use a narrower goal. Browser clicks alone do not mean the requested outcome was verified.
+- **You need to find or remove local data:** see [local storage, export, retention and deletion](docs/LOCAL_DATA.md). Data is not encrypted and is not automatically expired.
+
+## Pick your model
+
+Use a provider API key, or sign in through the official CLI for a supported subscription. API usage and consumer subscriptions are separate billing products.
+
+| Provider | Configuration |
+| --- | --- |
+| OpenAI, xAI Grok, DeepSeek, Mistral or another OpenAI-compatible API | `LLM_PROVIDER=openai-compatible`; set `LLM_API_KEY`, `LLM_MODEL` and `LLM_BASE_URL` |
+| Google Gemini API | OpenAI-compatible mode with `LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/` and your Gemini API key |
+| OpenRouter | OpenAI-compatible mode with `LLM_BASE_URL=https://openrouter.ai/api/v1` and the chosen `provider/model` slug |
+| Anthropic API | `LLM_PROVIDER=anthropic`; set `LLM_API_KEY` and `LLM_MODEL` |
+| ChatGPT plan | Install Codex CLI, sign in with `codex login`, set `LLM_PROVIDER=codex-subscription` |
+| Claude Pro/Max plan | Install Claude Code 2.1.248+, sign in with `claude auth login` (not Console), set `LLM_PROVIDER=claude-subscription` |
+
+The provider API routes have not all been live-tested here; DeepSeek Flash is the measured default. Subscription modes use the local CLI sign-in, need no API key and respect plan limits. Their local agent tools and MCP servers are disabled while planning. See [provider setup and limits](docs/PROVIDERS.md), the [support matrix](docs/SUPPORT_MATRIX.md) and [.env.example](.env.example) for route-specific setup, tests and live-evidence status.
+
+## Connect an MCP host
+
+Run FreeComputerUse as a local MCP server over `stdio` with `agent mcp`. It
+provides tools to start a task, inspect the observed page, follow and verify the
+result, and stop a task. Site and sensitive-action approvals still require a
+human response in an MCP host that supports form elicitation. No HTTP endpoint
+is opened. See the [MCP setup and validation limits](docs/MCP.md). The separate
+provider CLI adapters keep their own tools and MCP disabled while planning.
+
+## FAQ
+
+**Can I try it without a model key?** Yes, the practice revenue-table workflow runs with a deterministic local strategy. General tasks need a configured model.
+
+**Which providers have live evidence?** The current matrix records DeepSeek Flash and one synthetic plan through Codex CLI `0.156.1` with ChatGPT. Contract tests do not certify a live provider; see the [dated support matrix](docs/SUPPORT_MATRIX.md).
+
+**Does the model receive screenshots or browser profiles?** No screenshots are sent. The task and selected page context go to your provider; browser execution, profiles, history and downloads stay local. Local data is not encrypted.
+
+**Which platform is verified?** macOS 26.6 on Apple Silicon, Node 25.9.0 and system Chrome 154. Other OS, Node and browser combinations remain unverified in the [support matrix](docs/SUPPORT_MATRIX.md).
+
+## Control and privacy
+
+- Normal mode asks before direct navigation to a new origin and blocks hostnames resolving to private or reserved address ranges, including private IPv4 embedded in a discovered NAT64 prefix. A loopback-only proxy connects to the vetted numeric address, closing the DNS lookup-to-connection rebinding gap for browser HTTP(S) and WebSocket traffic. Explicit IP destinations require an exact origin grant. Ultra mode and the low-level `allowExternal` option opt out of origin and private-address checks. Chrome 154 tests cover redirect denial, simulated DNS rebinding, approved/blocked plain WebSockets, and approved/blocked browser-originated WSS. The WSS fixture uses a generated local certificate and ignores its certificate error only in the test; a separate opt-in smoke verifies Chrome TLS and an echo against one public WSS endpoint. Other WSS endpoints, live network-specific NAT64 discovery and other browser builds remain unverified. Sensitive actions have a separate confirmation gate. Ultra mode is explicit and off by default.
+- Browser execution, profiles, history and downloads stay on your machine. Page context needed for a plan goes to the chosen model provider; screenshots are not sent.
+- The planner receives aliases for local profile and file values, not their contents. Local storage is **not encrypted**.
+- Chromium profiles disable WebRTC UDP that the proxy cannot carry. Sites needing direct UDP for voice/video may fail; one local Chrome STUN fixture confirms no direct packet reached its receiver. Other non-HTTP traffic remains unverified.
+- Runs record actions, checks, repairs, token estimates and workflow reuse so you can inspect what happened.
+
+Read [the security boundaries](SECURITY.md) before using personal or sensitive data.
+See [where local data is stored and how to inspect, export or delete it](docs/LOCAL_DATA.md).
+
+## Evidence
+
+In a focused public suite recorded **18 September 2026**, 14/14 first-run results and 14/14 compatible learned repeats passed independent checks. First runs used 18 model calls; repeats used zero. These single-trial sandbox results do not predict success on arbitrary websites. [Report](artifacts/benchmark-public.json) · [Method and limitations](docs/BENCHMARKS.md).
+
+## Explore and contribute
+
+- [Project site and task library](https://othmaneblial.github.io/FreeComputerUse/)
+- [Frequently asked questions](https://othmaneblial.github.io/FreeComputerUse/#faq)
+- [Useful browser-task examples](docs/USEFUL_EXAMPLES.md)
+- [Implementation notes](docs/IMPLEMENTATION.md)
+- [Architecture](docs/ARCHITECTURE.md)
+- [Local validation commands](docs/LOCAL_VALIDATION.md)
+- [Contributing](CONTRIBUTING.md) · [Changelog](CHANGELOG.md)
+
+Useful contributions: reproducible browser tasks, safer permission scopes and checks that make results easier to trust. Keep shared examples synthetic or read-only; remove credentials and personal data from traces.
+
+[MIT License](LICENSE) · Built with TypeScript and Playwright.

package/SECURITY.md

@@ -0,0 +1,133 @@
+# Security model
+
+See the [threat model](docs/THREAT_MODEL.md) for assets, trust boundaries,
+verified controls, residual risks and prioritized follow-up work.
+
+Report vulnerabilities privately through GitHub's private vulnerability reporting
+when enabled. Never include credentials or real browser profile data in an issue.
+
+## Permission model
+
+Normal mode requires a human to approve each website origin before its first
+document request. The grant covers the requested task in that browser session,
+including subsequent pages on the same origin. New origins need another grant.
+Rejecting an initial grant leaves the target website unvisited. Cached workflows
+and replay do not bypass site grants or sensitive-action policy.
+
+With the default `sensitive` policy, explicit submit actions and controls marked
+sensitive are gated separately; label and form heuristics catch some additional
+high-impact actions. Detection cannot identify every ambiguously named or
+adversarial control. Use `--confirmation always` in normal mode when every
+action needs review. `--confirmation never` and Ultra mode skip action prompts.
+
+**Ultra mode is explicit, off by default.** It skips website/action approvals and
+allows external HTTP(S) destinations. It does not add shell access, arbitrary
+JavaScript execution, arbitrary local-file access, or remove step/token budgets.
+The model still cannot read environment variables or supply an arbitrary upload
+path. User restrictions and final completion criteria still apply.
+
+## Execution and network boundary
+
+- Every model plan/action/repair passes strict Zod validation.
+- Browser operations use a fixed Playwright action API; there is no eval/exec DSL.
+- Page text has an escaped untrusted-content boundary and cannot replace the
+  original goal. Local warnings flag common injection phrases.
+- In normal mode, local vault aliases require a goal authorizing profile, details,
+  credentials, resume/CV or local files. Vault values cannot appear in navigation
+  URL templates. Uploads require an explicit `{{files.alias}}` defined locally.
+- HTTP(S) only; URL credentials are rejected. `Agent` grants origins after
+  approval, while the low-level exported `Browser` denies all network requests
+  unless the caller supplies `allowedOrigins` or explicitly opts into
+  `allowExternal`. Cross-origin resources and WebSockets follow that policy.
+  A loopback-only Chromium DevTools Protocol connection attaches to each page
+  before its first navigation and checks redirect hops; redirected document
+  navigations use the same approval callback, and redirected subresources need
+  an approved origin. A local Chrome 154 test confirms an unapproved fast popup
+  redirect is stopped before the target server receives it, then succeeds after
+  approval. A loopback-only proxy resolves hostnames and connects to the vetted
+  numeric address for HTTP, HTTPS tunnels and WebSockets. In normal mode,
+  private/reserved answers and private IPv4 addresses embedded in the
+  system-resolver's discovered NAT64 prefix are blocked, including when the
+  hostname is allowlisted. Discovery uses `ipv4only.arpa`; if the resolver does
+  not return synthesized AAAA records, network-specific prefixes cannot be
+  checked. Explicit IP destinations still use exact origin permissions. Ultra
+  mode and the low-level `allowExternal` option bypass
+  origin and private-address checks. A synthetic public-to-loopback DNS change
+  test confirms the proxy rejects the connection before the target receives it;
+  system Chrome `154.0.8037.57` also passes approved and denied plain WebSocket
+  tests. Chrome 154 also completes an approved WSS handshake/frame through the
+  proxy and blocks an unapproved WSS origin before the target receives a TCP
+  connection. That fixture ignores errors from its generated local certificate;
+  it does not verify public certificate trust. The separate opt-in
+  `FCU_BROWSER_CHANNEL=chrome npm run security:wss` smoke connected to Postman
+  Echo using Chrome's normal TLS validation and received its fixed synthetic
+  payload on 24 September 2026; this covers one endpoint/runtime only.
+  Chromium's persistent profile
+  disables WebRTC UDP the proxy cannot carry. A Chrome 154 local STUN fixture
+  received no packets, but sites requiring direct UDP for voice/video may fail.
+  Network-specific NAT64 prefixes, other non-HTTP traffic and other browser
+  builds remain unverified. The
+  DevTools endpoint is available only on loopback while the browser runs; a
+  process under the same OS account is outside this boundary. Service workers
+  are blocked.
+- Selector ambiguity is rejected for mutations; collection extraction may select
+  several nodes. Browser dialogs are dismissed by default.
+- A failed click/submit with an uncertain outcome requires human review before
+  repair. Replay has no provider and stops on incompatible state.
+
+Prompt isolation, origin restrictions and approval gates reduce injection risk;
+they do not mathematically establish that a model always follows the goal, nor
+that an allowed website is trustworthy. Websites still run their own JavaScript
+inside Chromium and can access data intentionally entered on them. No CAPTCHA or
+security bypass is implemented. Do not automate a site without authorization.
+
+## Local data
+
+The default data directory, its contents, backup and deletion steps are listed
+in [Local data](docs/LOCAL_DATA.md).
+
+`.env`, `.fcu`, profiles, session cookies, localStorage, downloads and SQLite traces
+are ignored by Git. On macOS/Linux, the environment loader rejects a symlinked
+`.env` and removes group/other permission bits before reading it; set mode `0600`
+before editing or running other tools. App-written profile/history files use
+mode `0600`; state/profile directories use mode `0700` on verified filesystems.
+The configured app data directory must be a dedicated real directory, not a
+shared system/workspace root. Direct `TraceStore` use requires a private parent
+directory and refuses shared parents rather than changing their permissions;
+SQLite files are created owner-only and symbolic-link database paths are
+rejected.
+Profile JSON imports are schema-checked, reject symbolic-link files and replace
+saved data atomically. This is local storage with file permissions, **not
+encrypted storage**. Browser session data and extracted website content can be
+sensitive; use an OS-protected account/disk. History, workflows, browser sessions
+and downloads have no automatic expiry; see [retention and deletion steps](docs/LOCAL_DATA.md#retention).
+On macOS, download directories use mode `0700` and saved download files use mode
+`0600`; Windows/Linux data-directory permissions remain unverified.
+
+Known profile/file values are redacted from prompts, event logs and traces and
+resolve locally during actions. Common credentials in URL queries and fragments,
+as well as bearer-shaped tokens, are redacted before model requests, new trace
+saves and dashboard/CLI history output; the browser still opens the original URL.
+Secret-looking key strings are also redacted. Records extraction omits
+password/payment field values. These filters do not identify every possible
+secret in arbitrary website content. Do not publish local traces, browser
+profiles or screenshots from a real account. Replays that depended on a
+redacted URL credential need a fresh starting URL.
+
+## Dashboard boundary
+
+The UI binds only to `127.0.0.1`; Host checks prevent simple DNS rebinding. API
+requests require a random HttpOnly SameSite=Strict session cookie. Mutations also
+require the exact local Origin and an unguessable CSRF header. No CORS access is
+enabled. CSP restricts assets/connections to the same local origin. API keys are
+never exposed through the UI or API. A process/user already controlling the local
+OS account is outside this boundary; the loopback UI is not a multi-user service.
+
+## Verification evidence
+
+`npm test` includes rejection-before-network, normal/Ultra permission separation,
+strict code rejection, upload alias confinement, origin restrictions, duplicate
+selectors, concurrent token reservations, redaction, local UI authorization/CSRF,
+approval and zero-provider replay. Public benchmarks use only read-only sandbox
+tasks or browser-only simulations on the project-owned lab. They never send a
+message, purchase, create an account or modify a real user's account.