ruby_llm-browser 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6184d0ab1ce52e3a77ed427ff4e083790a7d573a51b5ea07ddffeab034b356e
+  data.tar.gz: c08d7fd335590fa99341551ce77ca6a8f8ec61662b3e63903308f56ea9ff05d6
+SHA512:
+  metadata.gz: 3f671bfe311dea830346ce657373b81f514c227eac636576f76fb962a4690a0e688fecb476d36ef83a288d02cdc28e0bd2f8fece092b00cd8925e57cae6b3509
+  data.tar.gz: 0f11137930c35dc67cf7642db5152864fa5b101bb957bba24edeab974279c66f33e728766bb5005c29bb331b37989f09edbbaee70f461acf419ea31db9b4a209

data/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-18
+
+### Fixed
+
+- Atomic start claims, actor quota locking, payload-bound idempotency, exact fence/state
+  checks, cancellation quota retention, and cleanup after post-start persistence errors.
+- Reaper fencing before cleanup and recovery of known sessions without a correlation API.
+- Host/operation output ceilings, UTF-8/escaped-JSON bounds, retained byte accounting,
+  malformed schema handling, and provider extraction schema validation.
+- Defensive policy/approval/schema copies, safer progress/errors/provenance, and suppressed
+  Active Job argument logging.
+- Real-clock durable timestamp round-trips and effective process budget/result defaults.
+- Stagehand response validation, explicit disabled self-healing/CAPTCHA solving/recording,
+  environment-drift rejection, remaining-time timeouts, and no guessed final URL.
+- Rails install generator namespace, README API errors, shipped documentation/examples,
+  and RubyLLM 2.0/2.1 public-API compatibility tests.
+
+### Security
+
+- Require patched CGI, DNS resolver, URI and zlib versions instead of accepting old
+  vulnerable default gems on a clean Ruby installation.
+- The first-release scope is offline read-only. Stagehand remains unsupported until
+  provider egress and confirmed cleanup are qualified; no live calls were made. Full live
+  Act is deferred to a later version, while offline Act simulation remains available.
+- See `docs/RELEASE_AUDIT.md` for findings, mitigations and residual limits.
+
+The first implementation milestone. Everything below is proven offline against the fake
+backend and an in-memory SQLite database; **no live browser provider call has been run**,
+and mocked tests never establish remote egress isolation, TTL or billing limits.
+
+### Added
+
+- Plain-Ruby Gem core (`require "ruby_llm/browser"`) with a manual require chain, no Rails
+  and no provider credentials loaded on require.
+- Read-only `RubyLLM::Browser::Inspect` and `Extract` tools; `Extract` takes a
+  host-pinned schema instead of a model-supplied one.
+- Simulation-only `RubyLLM::Browser::Act` (never registered by default) with a read-only RubyLLM
+  approval resolver and an atomic, digest-bound, single-use approval consumed in `execute`.
+- Source policy: URL normalization with userinfo/scheme/port and ambiguous-IP rejection,
+  allowlist matching, and fail-closed egress qualification that returns
+  `UNSUPPORTED_SECURITY_CAPABILITY` before any session when a backend cannot prove
+  browser-side egress isolation.
+- Durable operation lifecycle (`reserved → starting → active → closing → closed`, plus
+  `unknown` / `cleanup_pending` / `cancelled`), fencing and per-actor concurrency budgets,
+  with in-memory and ActiveRecord stores.
+- Official Stagehand Ruby SDK adapter (loaded lazily) that passes every client argument
+  explicitly, sets `max_retries: 0` on effectful calls, drops `cdp_url`, and reports honest
+  capabilities.
+- Bounded, sanitized `Result` with provenance, plus a redactor that strips secrets,
+  cookies and DevTools URLs.
+- Read-only preflight `Doctor`.
+- Optional Rails 8 adapter (`require "ruby_llm/browser/rails"`): ActiveRecord operation and
+  approval stores, a scoped Active Job with fence/cancel handling, a cleanup reaper, a
+  canonical schema module and an install generator with migration.
+- Offline examples, documentation and an FR evidence ledger (`docs/WORK.md`).

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,11 @@
+# Contributor Code of Conduct
+
+This project follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+Be respectful, assume good faith, and keep discussions focused on the work. Harassment,
+discrimination, doxxing and disclosure of other people's data or credentials are not
+acceptable. Maintainers may edit, lock or remove contributions and comments that violate
+this code, and may ban contributors for repeated or severe violations.
+
+Report concerns privately to the maintainer listed in the gemspec. Reports are handled
+confidentially.

data/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to ruby_llm-browser
+
+Thanks for helping. This is an unofficial community extension for
+[RubyLLM](https://rubyllm.com), not an official RubyLLM project.
+
+## Ground rules
+
+1. **Fail closed.** Anything that touches URLs, egress, sessions, approvals, budgets or
+   secrets must default to deny and must be provable by a test.
+2. **No new unsafe surface.** No arbitrary JS/shell, no credential or cookie scraping,
+   no CAPTCHA/age/access bypass, no purchases, posting or account changes, and no
+   second browser engine.
+3. **Offline by default.** CI must never make a paid provider call. Use the fake backend
+   or an injected client. Live tests are opt-in and owner-authorized.
+4. **Say what is not proven.** Distinguish PASS from NOT RUN. Mocked egress proves the
+   Gem's logic, never a provider's network isolation.
+
+## Development
+
+```bash
+bin/setup          # bundle install
+bundle exec rake   # specs + rubocop
+bundle exec rspec  # specs only
+bundle exec bundle-audit check --update
+bundle exec rubocop -A   # autocorrect style
+```
+
+## Changing behaviour
+
+- Add a failing spec first, including the negative/denial case.
+- Update `CHANGELOG.md` under `Unreleased`.
+- Update `docs/SECURITY_MODEL.md` or `README.md` if a boundary or public API moved.
+- Keep runnable examples and the package's local links green in
+  `spec/integration/documentation_spec.rb`.
+- Run both alternate bundles in `gemfiles/` when changing Tool or Rails integration.
+- Keep the Gem core loadable without Rails: `ruby -e 'require "ruby_llm/browser"'` must
+  not load `rails`, `active_job` or open any browser session.
+
+## Pull requests
+
+Keep commits small and focused. Explain the security impact of the change, list the
+tests you ran, and note anything you could not verify. Maintainers control releases.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Wang
+
+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.

data/NOTICE.md

@@ -0,0 +1,92 @@
+# Third-party notices
+
+`ruby_llm-browser` is MIT licensed (see `LICENSE.txt`). It declares separate runtime
+dependencies; no upstream source code is vendored in this Gem. The inventory below covers
+the 26 runtime dependency gems resolved in the local lockfile on 2026-10-18 and matches
+their exact installed gemspec license metadata. Stagehand has no license metadata in its
+published gem, so its MIT license is tied to the pinned upstream source tag below.
+
+This is a point-in-time technical inventory, not legal advice or trademark, affiliation,
+account-ownership, or publication clearance. Version ranges can resolve different
+versions later; recheck the exact artifact before distribution.
+
+## RubyLLM (`ruby_llm`)
+
+- License: MIT
+- Source: <https://github.com/crmne/ruby_llm>
+- Used for: the `RubyLLM::Tool` protocol and the chat tool-execution loop.
+
+## Stagehand Ruby SDK (`stagehand`)
+
+- License: MIT, as declared in the repository `LICENSE` file, "Copyright 2026 stagehand"
+  (`https://github.com/browserbase/stagehand-ruby/blob/v3.21.0/LICENSE`).
+- Source tag: `v3.21.0` (commit `b389c6e3ca7e4a5f9d46511082a6466d37163e17`).
+- Used for: the reference browser REST client behind
+  `RubyLLM::Browser::StagehandBackend`.
+- Note: the published `stagehand` gem ships without license metadata and without the
+  `LICENSE` file, so this notice cites the repository license at the pinned tag. Pin
+  the exact version and checksum in your `Gemfile.lock`.
+
+## Point-in-time runtime inventory (2026-10-18)
+
+Resolved locally on Ruby 3.3.5 with RubyLLM 2.1.1. Every dependency row was matched to
+the local lockfile version and installed gemspec license metadata. RubyGems version links
+identify the exact distributed releases; Stagehand's pinned-source exception is noted
+above. Rails/Active Record/Active Job and sqlite3 are host/test dependencies and are not
+part of this Gem's runtime dependency graph.
+
+| Dependency | Version | Declared license(s) | RubyGems version record |
+| --- | --- | --- | --- |
+| [`ruby_llm`](https://rubygems.org/gems/ruby_llm/versions/2.1.1) | 2.1.1 | MIT | [RubyGems version](https://rubygems.org/gems/ruby_llm/versions/2.1.1) |
+| [`stagehand`](https://rubygems.org/gems/stagehand/versions/3.21.0) | 3.21.0 | No gem metadata; pinned source MIT text below | [RubyGems version](https://rubygems.org/gems/stagehand/versions/3.21.0) |
+| [`json_schemer`](https://rubygems.org/gems/json_schemer/versions/2.5.0) | 2.5.0 | MIT | [RubyGems version](https://rubygems.org/gems/json_schemer/versions/2.5.0) |
+| [`hana`](https://rubygems.org/gems/hana/versions/1.3.7) | 1.3.7 | MIT | [RubyGems version](https://rubygems.org/gems/hana/versions/1.3.7) |
+| [`simpleidn`](https://rubygems.org/gems/simpleidn/versions/0.3.0) | 0.3.0 | MIT | [RubyGems version](https://rubygems.org/gems/simpleidn/versions/0.3.0) |
+| [`regexp_parser`](https://rubygems.org/gems/regexp_parser/versions/2.13.1) | 2.13.1 | MIT | [RubyGems version](https://rubygems.org/gems/regexp_parser/versions/2.13.1) |
+| [`schematist`](https://rubygems.org/gems/schematist/versions/1.1.0) | 1.1.0 | MIT | [RubyGems version](https://rubygems.org/gems/schematist/versions/1.1.0) |
+| [`zeitwerk`](https://rubygems.org/gems/zeitwerk/versions/2.8.3) | 2.8.3 | MIT | [RubyGems version](https://rubygems.org/gems/zeitwerk/versions/2.8.3) |
+| [`connection_pool`](https://rubygems.org/gems/connection_pool/versions/3.0.2) | 3.0.2 | MIT | [RubyGems version](https://rubygems.org/gems/connection_pool/versions/3.0.2) |
+| [`faraday`](https://rubygems.org/gems/faraday/versions/2.15.0) | 2.15.0 | MIT | [RubyGems version](https://rubygems.org/gems/faraday/versions/2.15.0) |
+| [`faraday-net_http`](https://rubygems.org/gems/faraday-net_http/versions/3.5.0) | 3.5.0 | MIT | [RubyGems version](https://rubygems.org/gems/faraday-net_http/versions/3.5.0) |
+| [`faraday-multipart`](https://rubygems.org/gems/faraday-multipart/versions/1.2.0) | 1.2.0 | MIT | [RubyGems version](https://rubygems.org/gems/faraday-multipart/versions/1.2.0) |
+| [`faraday-retry`](https://rubygems.org/gems/faraday-retry/versions/2.4.0) | 2.4.0 | MIT | [RubyGems version](https://rubygems.org/gems/faraday-retry/versions/2.4.0) |
+| [`multipart-post`](https://rubygems.org/gems/multipart-post/versions/2.4.1) | 2.4.1 | MIT | [RubyGems version](https://rubygems.org/gems/multipart-post/versions/2.4.1) |
+| [`marcel`](https://rubygems.org/gems/marcel/versions/2.1.0) | 2.1.0 | MIT / Apache-2.0 | [RubyGems version](https://rubygems.org/gems/marcel/versions/2.1.0) |
+| [`base64`](https://rubygems.org/gems/base64/versions/0.3.0) | 0.3.0 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/base64/versions/0.3.0) |
+| [`bigdecimal`](https://rubygems.org/gems/bigdecimal/versions/4.1.3) | 4.1.3 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/bigdecimal/versions/4.1.3) |
+| [`cgi`](https://rubygems.org/gems/cgi/versions/0.5.2) | 0.5.2 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/cgi/versions/0.5.2) |
+| [`json`](https://rubygems.org/gems/json/versions/3.1.0) | 3.1.0 | Ruby | [RubyGems version](https://rubygems.org/gems/json/versions/3.1.0) |
+| [`logger`](https://rubygems.org/gems/logger/versions/1.7.0) | 1.7.0 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/logger/versions/1.7.0) |
+| [`net-http`](https://rubygems.org/gems/net-http/versions/0.10.0) | 0.10.0 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/net-http/versions/0.10.0) |
+| [`net-protocol`](https://rubygems.org/gems/net-protocol/versions/0.4.0) | 0.4.0 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/net-protocol/versions/0.4.0) |
+| [`timeout`](https://rubygems.org/gems/timeout/versions/0.6.1) | 0.6.1 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/timeout/versions/0.6.1) |
+| [`uri`](https://rubygems.org/gems/uri/versions/1.1.2) | 1.1.2 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/uri/versions/1.1.2) |
+| [`resolv`](https://rubygems.org/gems/resolv/versions/0.8.1) | 0.8.1 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/resolv/versions/0.8.1) |
+| [`zlib`](https://rubygems.org/gems/zlib/versions/3.2.4) | 3.2.4 | Ruby / BSD-2-Clause | [RubyGems version](https://rubygems.org/gems/zlib/versions/3.2.4) |
+
+Rails/Active Record/Active Job are optional host dependencies (MIT); sqlite3 is a test/
+host adapter (BSD-3-Clause). Development-only dependencies are not gem runtime requirements.
+
+## Stagehand pinned source license text
+
+Source: <https://github.com/browserbase/stagehand-ruby/blob/v3.21.0/LICENSE>, fetched
+2026-10-18. Included because the published Stagehand 3.21.0 gem omits the license file.
+
+Copyright 2026 stagehand
+
+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.

data/README.md

@@ -0,0 +1,139 @@
+# ruby_llm-browser
+
+An **unofficial community extension** for [RubyLLM](https://rubyllm.com), with an
+experimental adapter for the official [Stagehand Ruby SDK](https://github.com/browserbase/stagehand-ruby).
+It provides read-only `Inspect` and schema-pinned `Extract` tools, operation bookkeeping,
+and an optional Rails 8 adapter. It does not implement a browser engine.
+
+The first release supports the offline `FakeBackend` only. `StagehandBackend` is present
+for future qualification, but it refuses live operations until browser-side egress and
+provider cleanup are qualified.
+
+> **Version 0.1.0 is the offline-only first release.** The built-in Stagehand backend
+> is unsupported, and the full live Act approval protocol is deferred. No live provider
+> calls were made. See the [release audit](docs/RELEASE_AUDIT.md). This project is not
+> maintained or endorsed by RubyLLM or Browserbase.
+
+## Install
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "ruby_llm-browser", "~> 0.1.0"
+```
+
+The core requires Ruby 3.2+, RubyLLM `>= 2.0, < 3`, `json_schemer ~> 2.5`, and
+`stagehand ~> 3.21.0`, plus patched DNS/URL/CGI/compression gems (see the
+[dependency reference](docs/API.md)). Requiring `ruby_llm/browser` loads neither Rails nor the Stagehand
+client, discovers no provider credentials, and opens no browser session.
+
+## Try it offline
+
+This complete example makes no network request and requires no API key:
+
+```ruby
+# smoke-test: offline
+require "ruby_llm/browser"
+
+# Fake DNS is only for this offline demonstration. Production uses real DNS.
+class OfflineResolver
+  def getaddresses(_host) = [ "93.184.216.34" ]
+end
+
+context = RubyLLM::Browser::Context.new(
+  actor_id: "demo-actor", run_id: "demo-run",
+  backend: RubyLLM::Browser::FakeBackend.new,
+  source_policy: RubyLLM::Browser::Policy.new(
+    allowed_hosts: [ "docs.example.com" ], resolver: OfflineResolver.new
+  ),
+  operation_store: RubyLLM::Browser::InMemoryOperationStore.new
+)
+schema = {
+  "type" => "object",
+  "properties" => { "title" => { "type" => "string" } },
+  "required" => [ "title" ], "additionalProperties" => false
+}
+
+inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
+extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+puts inspect_tool.execute(url: "https://docs.example.com/")[:status] # => ok
+puts extract_tool.execute(url: "https://docs.example.com/")[:data]   # => {"title"=>"Example"}
+```
+
+Register these instances on your configured RubyLLM chat with
+`chat.with_tools(inspect_tool, extract_tool)`. Never register `Act` by default.
+The host supplies authenticated **string** actor/run IDs, authorization, consent,
+the pinned extraction schema, budgets, and the backend.
+
+The tools return a **Hash**, not a `Result` object. Direct `Engine` calls return a
+`Result`. Check `status` and `error`; page data is untrusted evidence, not verified truth.
+
+## Safety boundaries
+
+- URL policy checks hosts, schemes, ports, and public DNS/IP addresses. It cannot
+  sandbox a remote browser or control page-triggered requests.
+- No built-in live backend is supported in this release. `StagehandBackend` always
+  reports egress as unverified and refuses live operations. A host assertion cannot
+  enable it.
+- The model cannot increase the host's output limit. Results are redacted, schema-checked
+  for extraction, and bounded by the policy and remaining operation bytes.
+- A durable operation is claimed before start. Duplicate jobs cannot start it again.
+  SDK retries are disabled; uncertain outcomes are never automatically replayed.
+- Cancellation fences workers but cannot undo an in-flight request. Dispatched operations
+  retain quota until cleanup is confirmed. Run a reaper independently of job workers.
+- `max_cost_usd` is advisory metadata, not an enforced billing cap. Provider timeouts and
+  cleanup are also not a promise of zero future charges.
+- `Act` is an offline simulation only. The full same-session live approval protocol is
+  deferred to a later version. Candidate-list hashes and selector keyword filters are
+  not proof of target identity or action safety.
+
+## Rails integration
+
+Add Rails 8's `activerecord` and `activejob` to your host application, then opt in:
+
+```ruby
+require "ruby_llm/browser/rails"
+```
+
+```bash
+bin/rails generate ruby_llm:browser:install
+bin/rails db:migrate
+```
+
+The adapter provides durable operation/approval stores, actor-scoped jobs, cancellation,
+and a reaper. Follow the [Rails guide](docs/RAILS.md) for the context factory, matching
+budgets, status access, scheduling, and upgrading an earlier development database.
+Only SQLite concurrency is tested locally; PostgreSQL requires its own qualification.
+
+## Documentation
+
+- [Documentation website](https://rubyllm-browser.wangyaodi.com) (GitHub Pages)
+- [Documentation index](docs/README.md)
+- [API, configuration, and result reference](docs/API.md)
+- [Rails jobs and recovery](docs/RAILS.md)
+- [Security model and live qualification](docs/SECURITY_MODEL.md)
+- [Compatibility and release checklist](docs/RELEASING.md)
+- [Audit findings and unresolved blockers](docs/RELEASE_AUDIT.md)
+- [Requirement evidence](docs/WORK.md)
+- [Offline scripts](examples/)
+
+These documents and examples are included in the built gem.
+
+## Development
+
+```bash
+bin/setup
+bundle exec rake
+bundle exec bundle-audit check --update
+bundle exec ruby examples/plain_ruby.rb
+bundle exec ruby examples/rails_adapter.rb
+bundle exec rake build
+bundle exec ruby bin/verify-package --rails --audit
+```
+
+Tests block unmocked network requests. No paid live call or RubyGems publication is part
+of the default workflow. See [contributing](CONTRIBUTING.md).
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt) and [third-party notices](NOTICE.md).

data/SECURITY.md

@@ -0,0 +1,46 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Report security issues privately via GitHub Security Advisories on
+<https://github.com/yorzi/ruby_llm-browser> ("Report a vulnerability"), or by email
+to the maintainer listed in the gemspec. Please do not open a public issue for a
+suspected vulnerability.
+
+Include: affected version, a minimal reproduction, the impact you observed, and
+whether secrets, cross-actor data, browser sessions or provider billing are involved.
+We aim to acknowledge within a few days and to publish a fix and advisory once a
+patch is available. Never include real credentials, cookies, `cdp_url` values or
+private page payloads in a report; use synthetic fixtures.
+
+## Security model in one page
+
+- **Untrusted everything external.** Model output and page text are untrusted data.
+  They can never change tool policy, grant permissions or authorize actions.
+- **Default deny.** Only hosts you allow explicitly, over `http`/`https`, on approved
+  ports, are reachable. Loopback, private, link-local, multicast and cloud-metadata
+  addresses are rejected, including IPv6 and IPv4-mapped forms.
+- **Fail closed on egress.** Ruby-side URL checks cannot prove what a *remote* browser
+  does. `Policy#egress_qualified?` must be satisfied by the backend before a session
+  starts; otherwise the Gem raises `UNSUPPORTED_SECURITY_CAPABILITY` and never
+  contacts a provider.
+- **Effectful retries are off.** Session creation, navigation, `act` and `end_` are
+  issued with `max_retries: 0`. Unknown outcomes stay `unknown` /
+  `cleanup_pending` and are never silently retried into a second session or a
+  duplicated action.
+- **Reduce secret exposure.** Credential-like fields, known secret literals and
+  `cdp_url` endpoints are redacted; this is not a general PII/page-secret detector.
+  Avoid authenticated/private browsing and raw payload logging. SDK client arguments are passed
+  explicitly; the Gem never reads SDK environment defaults for credentials or base
+  URLs, and refuses to start when `STAGEHAND_CUSTOM_HEADERS` is set unless the host
+  approved it.
+- **Live Act is disabled.** `RubyLLM::Browser::Act` is never registered by default,
+  and the Engine refuses non-fake action backends. Offline single-use approval tests
+  do not establish the missing same-session/target authorization protocol. Purchases,
+  posting, account changes and access-control bypass remain unsupported.
+
+## Scope of guarantees
+
+Mocked or fake backends demonstrate the Gem's API logic only. They do not prove
+provider-side network egress isolation, provider TTL enforcement or billing limits.
+See `docs/SECURITY_MODEL.md` and `docs/SPEC_BASELINE.md` for the full, honest status.

data/docs/API.md

@@ -0,0 +1,177 @@
+---
+layout: default
+title: API and Configuration
+permalink: /api-and-configuration/
+description: Configure trusted host objects and interpret bounded untrusted results.
+---
+
+# API and configuration
+
+Configure trusted host objects and interpret bounded, untrusted results.
+
+After reading this guide, you will know:
+
+- How to register read-only tools.
+- Which inputs belong to the host and which belong to the model.
+- How to configure budgets, schemas, backends, and error handling.
+
+## Creating a context
+
+Use the complete offline example in [Getting Started]({% link _getting_started/getting-started.md %}). `Context.new` requires:
+
+| Keyword | Type and meaning |
+| --- | --- |
+| `actor_id`, `run_id` | Nonempty strings from authenticated host records. Convert numeric database IDs with `to_s`. |
+| `backend` | A `Backend` instance. Use `FakeBackend` for offline tests. |
+| `source_policy` | A host-created `Policy`. |
+| `operation_store` | An `OperationStore`; durable storage is required across restarts or workers. |
+| `approval_store` | Optional `ApprovalStore`, needed only for experimental Act. |
+| `budget` | Optional `Budget`; defaults listed below. |
+| `clock` | Optional callable returning a UTC `Time`. |
+| `logger` | Optional host logger. Do not enable raw provider or tool payload logging. |
+| `consent` | Optional host consent record. The gem records its presence; it does not collect or authenticate consent. |
+| `metadata` | Optional host metadata. Never supply credentials here. |
+
+The host must reauthorize actor/run access when building a context, including background
+jobs. Passing IDs alone is not authentication. The model must never choose a backend,
+credential, schema, source allowlist, consent record, or budget.
+
+## Registering tools
+
+```ruby
+inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
+extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+chat.with_tools(inspect_tool, extract_tool)
+```
+
+Both tools expose `url`, optional `instruction`, and optional positive integer
+`max_bytes`. `max_bytes` can only tighten the policy and operation ceilings.
+`Extract` takes its schema in the constructor, not in model arguments.
+
+`Inspect` returns **candidate interactions**, not a screenshot or arbitrary page dump.
+Neither read-only tool dispatches candidates automatically. Pages may still run scripts
+and initiate requests; read-only does not mean browsing has no external effects.
+
+`Tool#execute` and RubyLLM `Tool#call` return a Hash. If you need a `Result` object, use:
+
+```ruby
+engine = RubyLLM::Browser::Engine.new(context: context)
+result = engine.inspect(url: url)
+result = engine.extract(url: url, schema: schema, instruction: "Find the title")
+```
+
+The optional `operation:` Engine keyword accepts a host-reserved operation with the
+same actor/run and budget. Starting it is an atomic reserved-to-starting claim. It is
+not a resume or retry API for active, unknown, or closed operations.
+
+## Source policy
+
+`Policy.new(allowed_hosts: [...])` accepts exact hosts and `*.example.com` subdomains.
+A wildcard does not allow the bare domain. Defaults are HTTP/HTTPS and ports 80/443.
+Keep `verify_dns: true`; `resolver:` is injectable for offline fixtures.
+
+Other options are `allowed_schemes`, `allowed_ports`, `max_result_bytes` (65,536),
+`max_schema_depth` (8), `max_schema_properties` (64 root properties), and
+`max_schema_bytes` (16,384). Browser-side enforcement must also cover explicitly
+approved asset origins, redirects, frames, popups, WebSockets, and subresources.
+
+## Extraction schemas
+
+Schemas must be bounded object JSON Schemas, passed as a Hash, JSON object string, or
+an object/class supporting `to_json_schema`. Supported keywords are `type`,
+`description`, `properties`, `required`, `items`, `enum`, `additionalProperties`,
+`title`, `minimum`, `maximum`, `minLength`, `maxLength`, `minItems`, `maxItems`,
+`format`, and `default`. Remote references and arbitrary schema extensions are refused.
+
+Use `required` and `additionalProperties: false` when an exact shape matters. Provider
+data must satisfy the schema before redaction or truncation. Invalid data returns
+`PROVIDER_ERROR`; it is not returned as a successful extraction. A truncated preview
+or redacted field need not retain the original schema's type. Always check the status.
+
+## Results and errors
+
+`Result#to_h` contains symbol keys: `status`, `operation_id`, `final_url`,
+`captured_at` (UTC ISO 8601), `locator`, `digest`, `truncated`, `data`, and optional
+`error: { code:, message: }`. Locator/data objects use string keys. JSON encodes all
+keys as strings. Credential-like query values are redacted in URL provenance.
+
+Statuses are `ok`, `truncated`, `error`, `unknown`, and `cleanup_pending`.
+`Result#ok?` accepts `ok` and `truncated`; it makes no factual verification claim.
+`digest` is SHA-256 of canonical JSON of the returned, sanitized data. Very small byte
+limits can produce an empty string or scalar preview; `truncated` is authoritative.
+
+Engine preflight denials raise typed errors. Tools convert them into error Hashes.
+After a session starts, the Engine attempts cleanup and returns a failure result.
+Cleanup failure can supersede the original result with `cleanup_pending`; inspect the
+durable operation's `error_code` and arrange host review for unknown effects.
+
+Safe error codes: `INVALID_INPUT`, `NOT_AUTHORIZED`, `UNSUPPORTED_SECURITY_CAPABILITY`,
+`BUDGET_EXHAUSTED`, `SESSION_UNKNOWN`, `CLEANUP_PENDING`, `APPROVAL_REQUIRED`,
+`APPROVAL_STALE`, and `PROVIDER_ERROR`.
+
+## Budgets
+
+`Budget.new` defaults to `max_seconds: 60`, `max_steps: 12`, `max_bytes: 262_144`,
+`max_concurrent: 1`, and `max_cost_usd: nil`.
+
+`RubyLLM::Browser.configure` sets process defaults for `default_budget`,
+`max_result_bytes`, `clock`, and `logger`. New contexts/policies use those defaults;
+existing objects do not change. `configuration.backend` is only a reserved host slot:
+contexts always require an explicitly supplied backend and never use a fallback.
+
+- Steps count navigation, observation, extraction, and action calls, not start/cleanup.
+- Bytes count retained sanitized result data, not all bytes the remote browser receives.
+- Wall-clock checks refuse new calls after expiry. Stagehand request timeouts are bounded
+  by remaining time. Cleanup has a separate timeout and may outlive this budget.
+- Concurrency is scoped to the actor across runs. Unknown/pending cleanup holds a slot.
+- `max_cost_usd` is **advisory only**. There is no cost ledger or provider hard spending
+  cap in this release. Enforce billing limits in the provider/host.
+
+## Stagehand backend status
+
+`StagehandBackend` is unsupported for live operations in this release. It always reports
+`egress_isolation: :unverified` and `act_supported?: false`. `Engine` refuses it before
+the first provider request, and direct start, navigation, observation, extraction, and
+Act calls also fail closed. No constructor option or injected client enables live use.
+
+The adapter remains in the source for future qualification. Its client pins credentials
+and base URL, disables retries, self-healing, CAPTCHA solving, session recording and
+session logging, and requests a provider timeout. These controls do not prove egress,
+TTL, billing, final-URL reporting, or cleanup. `end_session` sends no request in this
+release and returns `false`; the operation remains `cleanup_pending`.
+
+The constructor accepts `server: :remote`, `base_url:`, `timeout: 60.0`,
+`custom_headers_approved: false`, `env: ENV`, and an injected `client:` for internal
+contract tests. A future live implementation must verify all relevant environment
+settings, egress across every browser request path, TTL and closure status, and provider
+billing controls before it can advertise support.
+
+## Dependency security floors
+
+Old Ruby installations can supply vulnerable default gems even when a developer's
+lockfile audit passes. Runtime requirements explicitly exclude those versions:
+`cgi >= 0.4.2, < 1`, `resolv >= 0.7.2, < 1`, `uri >= 1.0.4, < 2`, and
+`zlib >= 3.2.3, < 4`. A fresh install may build native extensions for these gems.
+Use a supported, patched Ruby interpreter as well; these floors do not patch Ruby or
+system libraries. Audit the versions actually activated by your application, including
+default gems, not just a development lockfile.
+
+## Experimental Act
+
+`Act.new(context:)` declares RubyLLM `requires_approval`. Its arguments are `url`,
+`approval_id`, `method`, `selector`, optional `description`, and optional `arguments`.
+The resolver reads the host store without consuming. Consumption immediately before
+dispatch checks actor/run, exact URL/action digest, expiry, and any supplied
+page/operation/session bindings. Revocation and consumption are atomic in the stores.
+
+**Do not use this as a production authorization protocol yet.** Bindings are currently
+optional; a candidate-list digest is not a DOM/target revision, and each Engine action
+opens a fresh session. The same-session host approval flow required by the specification
+is deferred to a later version. The Engine refuses all non-fake Act calls before starting
+a session. Selector/description keyword filters are defense in depth, not semantic proof
+that a click is harmless. The Stagehand adapter does not support Act in this release.
+
+## Next steps
+
+- Read [Rails integration]({% link RAILS.md %}) for durable workers and recovery.
+- Read [security boundaries]({% link SECURITY_MODEL.md %}) before qualifying a live backend.

data/docs/CNAME

@@ -0,0 +1 @@
+rubyllm-browser.wangyaodi.com