ruby_llm-browser 0.1.0 → 0.3.0

data/docs/_reference/roadmap.md

@@ -0,0 +1,171 @@
+---
+layout: default
+title: Roadmap to 1.0
+nav_order: 8
+description: Plan small releases toward a reliable read-only browser integration for RubyLLM.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- What works today and what still blocks practical live use.
+- Which small features belong in the next release.
+- What must pass before the project releases 1.0.0.
+
+## Start with a Narrow 1.0
+
+The proposed 1.0 supports one complete workflow: your RubyLLM application inspects an
+approved public page or extracts schema-checked data, receives a bounded result with
+provenance, and can account for the browser session through cleanup. It works in plain
+Ruby and through the optional Rails adapter.
+
+Version 0.1.0 introduced the offline foundation: Inspect, Extract, URL policy, bounded
+results, operation bookkeeping, Rails jobs, and Act simulation. It does not provide a
+supported live backend. The current Stagehand adapter refuses live operations. The
+0.3.0 release adds opt-in Rails result delivery to host-owned storage;
+it does not add a gem-managed results database or guaranteed delivery.
+
+**This is a proposed development sequence, not a list of available features or release
+dates.** Future API names below are proposals. Keep each release small; use patch
+releases for fixes and split a milestone if implementation reveals a larger change.
+
+## Release Sequence
+
+Build convenience on the current offline API first. Complete the Rails result path
+next. Qualify one live deployment before advertising browser support, then use pilot
+feedback to settle the public API.
+
+| Version | Outcome | Release condition |
+| --- | --- | --- |
+| 0.2.0 | Easier tool setup and clearer offline diagnostics | Two additive features, tested with no provider requests |
+| 0.3.0 | Usable Rails result delivery | A host can retrieve a job's result after the worker exits |
+| 0.4.0 | One supported live read-only deployment | Egress, final URL, session expiry and cleanup qualified on that deployment |
+| 0.5.0 | Pilot feedback and recovery hardening | Plain-Ruby and Rails workflows exercised outside the test suite |
+| 1.0.0-rc.1 | Stable API candidate | Feature freeze, complete upgrade instructions, candidate package verified |
+| 1.0.0 | Supported read-only integration | All acceptance criteria below pass on the release candidate |
+
+### 0.2.0: Two Small Features
+
+Version `0.2.0` adds both features below. Milestones after 0.3 remain proposed scope. See
+[What's New]({% link _reference/whats-new-in-0-2.md %}) for usage and
+[development and testing]({% link _advanced/development-and-testing.md %}) for validation.
+
+1. Add the read-only tool factory `RubyLLM::Browser.tools(context:, schema:)`.
+   Return Inspect and Extract instances suitable for `chat.with_tools(*tools)`. Keep
+   the context and extraction schema explicit; never include Act. Reuse the existing
+   constructors and validation instead of creating a second configuration API.
+2. Make Doctor distinguish offline and live-backend checks. FakeBackend diagnostics
+   should not warn that provider credentials are missing. Live-backend reports must
+   keep the unsupported Stagehand reason visible. Preserve the structured report and
+   make clear that a passing local check does not qualify a provider.
+
+Acceptance: exercise the factory through RubyLLM's public tool-registration API on
+both supported RubyLLM versions; reject an invalid schema; verify no Act registration,
+provider request, credential discovery, or Rails load. Test Doctor with fake and
+unsupported live backends. Update the relevant guides and changelog with the features.
+
+Do not add a CLI, a context builder, new database tables, or live support in this slice.
+The factory and Doctor are implemented in separate commits. Local and remote
+validation precede the release tag and publication.
+
+### 0.3.0: Complete the Rails Result Path
+
+Version `0.3.0` implements `Rails.result_delivery`, typed
+host-delivery failures, and a runnable SQLite host example with separate workers.
+Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}) and
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}) for the current API.
+The source repository's `docs/evidence/V0_3_VALIDATION.md` records local candidate
+checks. `docs/evidence/V0_3_RELEASE.md` records remote verification and publication.
+
+The result-delivery hook lets the host persist the sanitized `Result`
+against its operation ID. Its runnable host example stores and retrieves
+the result after an asynchronous job finishes. The host owns access checks, retention,
+and storage; the gem does not need an admin interface or a general results database.
+
+Acceptance: retrieve a schema-checked extraction after worker exit; refuse cross-actor
+reads in the host example; handle success, truncation, failure, and pending cleanup.
+A delivery failure must be visible and must never cause the browser operation to run
+again. Document delivery semantics, duplicate handling, and recovery separately from
+the operation's session state. Verify generator upgrades preserve existing records.
+
+### 0.4.0: Qualify One Live Read-only Deployment
+
+Begin with a feasibility check of the pinned SDK and a named deployment. Determine
+whether the deployment can enforce every required browser request boundary and report
+verified final URLs and terminal session state. Implement only the missing adapter
+integration needed for that deployment. Keep live Act disabled.
+
+Acceptance requires deployment-specific evidence for redirects, subresources, frames,
+popups, WebSockets, connection-time DNS/IP restrictions, final URLs, session expiry,
+and confirmed cleanup. Exercise timeouts, worker death, and lost start responses with
+controlled fixtures. Unknown sessions retain quota and have an explicit host review
+path; an SDK acknowledgement alone cannot release them.
+
+Prepare the fixtures and opt-in qualification runner offline first. Live runs require
+separate owner authorization for the deployment, data, and spending. Keep default CI
+offline. Report provider billing controls separately from the advisory cost field.
+
+If the deployment cannot meet the required controls, stop this milestone and record
+the gap. Keep live support disabled. Do not replace qualification with a boolean flag
+or promote an offline-only package to 1.0 under this plan.
+
+### 0.5.0: Exercise Real Application Workflows
+
+Run two authorized pilots: a plain-Ruby extraction and a Rails background extraction
+with durable host result retrieval. Record the exact dependency/deployment versions,
+fixture expectations, observed results, failures, and cleanup outcomes. A controlled
+host application is sufficient; customer adoption is not a release prerequisite.
+
+Use pilot findings to improve errors, delivery, cancellation, and recovery. Confirm
+that duplicate jobs do not repeat provider starts, unknown outcomes remain visible,
+and result limits and redaction behave as documented. Resolve public API changes now
+and provide migrations before freezing the API.
+
+### 1.0.0-rc.1: Freeze and Verify
+
+Freeze tool constructors, factory arguments, result fields, error codes, backend/store
+contracts, and Rails schema/delivery hooks. Publish migration instructions for every
+breaking pre-1.0 change. Run the declared Ruby/RubyLLM/Rails matrix, build the gem,
+install the actual artifact in a clean environment, and verify its shipped examples,
+generator, guides, and dependency audit.
+
+Repeat the live qualification against the candidate's exact artifact and deployment.
+Fix defects through further release candidates. Feature requests return to a later
+minor release. A candidate with an unresolved blocker does not advance to 1.0.0.
+
+## 1.0.0 Acceptance Criteria
+
+- **Useful:** both pilot workflows complete, and one named live read-only deployment
+  is supported with reproducible evidence and documented limits.
+- **Controlled:** URL policy, schema validation, result bounds, and redaction pass
+  positive and denial cases. Deployment qualification covers all browser request paths.
+- **Recoverable:** cancellation, duplicate jobs, worker death, unknown starts, and
+  pending cleanup preserve correct state and quota. Host recovery steps are tested.
+- **Retrievable:** a Rails host can persist and authorize result retrieval after a job
+  exits. Delivery failure cannot trigger a repeated browser action.
+- **Stable:** the public API and database upgrade path are documented and covered by
+  compatibility checks. Unsupported databases and backends are identified explicitly.
+- **Distributable:** the release artifact passes the compatibility matrix, clean
+  installation, examples, documentation build, and dependency checks. Version, tag,
+  changelog, and stable documentation agree. The owner authorizes publication.
+
+Live Act, multiple providers, PostgreSQL qualification, authenticated browsing,
+screenshots, downloads, arbitrary JavaScript, a hosted UI, and a cost ledger are not
+required for this 1.0. Keep unsupported capabilities explicit. Consider live Act only
+as a separate feature with same-session approval and target identity guarantees.
+
+## Keep Planning and Documentation Separate
+
+The README introduces the project. Site guides teach supported behavior and provide
+the API reference. This page owns future scope; the changelog records shipped changes.
+Historical release audits remain evidence for their exact versions, not a current
+task queue. Plan changes do not rewrite the approved specification baseline.
+
+Read [API and configuration]({% link _reference/api-and-configuration.md %}),
+[Rails jobs and recovery]({% link _advanced/rails-integration.md %}), and
+[live-backend qualification]({% link _advanced/live-backend-qualification.md %}) for
+the current contracts. Follow [the release checklist]({% link RELEASING.md %}) when a
+milestone is ready to ship.

data/docs/_reference/upgrading.md

@@ -2,32 +2,66 @@
 layout: default
 title: Upgrading
 nav_order: 2
-description: Check the supported upgrade path before moving a RubyLLM::Browser application to a new version.
+description: Upgrade from 0.2.0 while preserving operation data and configuring optional Rails result delivery.
 ---
 
 # {{ page.title }}
 
 {{ page.description }}
-{: .fs-6 .fw-300 }
 
 After reading this guide, you will know:
 
-* What changed in the first public release.
-* Where to find migration steps for earlier development snapshots.
-* What evidence must exist before a release tag is treated as supported.
+- How to update an application from 0.2.0.
+- How to preserve existing data and enable result delivery.
+- Which result and worker behaviors change.
 
-## Public Releases
+## Upgrade from 0.2.0
 
-Version `{{ site.version }}` is the first public release. It has no earlier public version
-to migrate from. Install it with `bundle add ruby_llm-browser --version "~> {{ site.version }}"`.
+Update your Gemfile and bundle:
 
-## Earlier Development Snapshots
+```ruby
+gem "ruby_llm-browser", "~> {{ site.version }}"
+```
 
-If you ran an earlier development Rails generator, do not drop existing operation data
-or rerun a create-table migration. Follow the additive migration instructions under
-"Upgrading an earlier development snapshot" in the [Rails guide]({% link RAILS.md %}). Drain workers during the migration and do not reuse idempotency keys for legacy rows that lack request digests.
+```sh
+bundle update ruby_llm-browser
+```
+
+This release adds no gem-managed database migration or runtime dependency. Preserve all
+operation, approval, and actor-lock rows. Do not rerun the install generator on an
+existing installation. Result storage belongs to your application.
+
+## Enable Result Delivery When Needed
+
+`RubyLLM::Browser::Rails.result_delivery` defaults to `nil`. Existing job return values
+remain supported. To retain results after a worker exits, follow
+[Rails Result Delivery]({% link _advanced/result-delivery.md %}). Configure persistence,
+authorized reads, idempotent writes, and recovery before enabling the callback.
+
+A callback failure raises `Rails::ResultDeliveryError`. Queue retries do not redeliver
+a result. The error retains the result only in process; it is not durable storage.
+Recover delivery separately from browser execution. A crash before host persistence
+can still lose the result, so do not treat this hook as guaranteed delivery.
+
+## Account for Immutable Results and Fenced Workers
+
+`Result` now also copies and freezes operation ID, error code and error message strings,
+consistent with its other fields. Mutating these attributes raises `FrozenError`;
+duplicate a string before changing it in host code. Caller-owned inputs stay mutable.
+
+A worker fenced during browser execution now returns `:fenced_out` and cannot deliver
+its stale result. Cancelled work never invokes the delivery hook, including while
+cleanup remains pending. Delivery failures do not change the session state or free
+quota. Stagehand and live Act remain unsupported.
+
+## Earlier Versions
+
+For upgrades from 0.1.0 and earlier development snapshots, first follow the
+[0.2.0 upgrading guide](https://github.com/yorzi/ruby_llm-browser/blob/v0.2.0/docs/_reference/upgrading.md).
+Preserve operation data and use additive migrations where required.
 
 ## Next Steps
 
-* Review the [release history]({% link _reference/release-history.md %}) for version records.
-* Review the [release audit]({% link RELEASE_AUDIT.md %}) before enabling a live backend.
+- Read [What's New in 0.3]({% link _getting_started/whats-new-in-0-3.md %}).
+- Review [release history]({% link _reference/release-history.md %}) and
+  [live-backend qualification]({% link _advanced/live-backend-qualification.md %}).

data/docs/_reference/whats-new-in-0-2.md

@@ -0,0 +1,46 @@
+---
+layout: default
+title: What's New in 0.2
+parent: Release History
+nav_order: 1
+description: Use the read-only tool factory and backend-aware diagnostics in this release.
+---
+
+# {{ page.title }}
+
+{{ page.description }}
+
+After reading this guide, you will know:
+
+- How to register the read-only tool pair.
+- How to distinguish offline diagnostics from live-backend checks.
+- Where to verify changes locally before upgrading.
+
+## Read-only Tool Factory
+
+You can register the read-only tools in one call:
+
+```ruby
+chat.with_tools(*RubyLLM::Browser.tools(context: context, schema: schema))
+```
+
+The host still supplies context and schema. The factory returns Inspect and Extract
+instances and never registers Act. Individual constructors remain supported. Read
+[Inspecting and extracting]({% link _core_features/inspect-extract.md %}) for a complete
+offline example and the validation behavior.
+
+## Backend-aware Diagnostics
+
+Doctor adds a `mode` field while preserving `ok`, `summary`, and `checks`. FakeBackend
+reports `offline` mode and skips provider environment and SDK checks. Stagehand
+reports `live` mode and remains blocked. Custom backends no longer receive unrelated
+Stagehand warnings. Read [Checking Configuration]({% link _core_features/diagnostics.md %}).
+
+## Development Verification
+
+Use `bin/check` for offline contracts, lint, alternate bundles, and examples. Use
+`bin/check-browser` for desktop/mobile workflows and fixture screenshots. The
+[development guide]({% link _advanced/development-and-testing.md %}) explains setup,
+package verification, and the limits of this evidence.
+
+Stagehand and live Act remain unsupported. This release remains offline-only.

data/docs/index.md

@@ -35,7 +35,7 @@ features:
 
 ## Before You Install
 
-The first release is `0.1.0` and supports only the offline `FakeBackend`. The built-in
+Version `{{ site.version }}` supports only the offline `FakeBackend`. The built-in
 Stagehand adapter is unsupported until provider egress and confirmed cleanup are
 qualified. The full live Act protocol is deferred to a later version.
 
@@ -70,8 +70,7 @@ schema = {
   "required" => [ "title" ], "additionalProperties" => false
 }
 
-inspect_tool = RubyLLM::Browser::Inspect.new(context: context)
-extract_tool = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+inspect_tool, extract_tool = RubyLLM::Browser.tools(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"}
 ```

data/examples/plain_ruby.rb

@@ -23,12 +23,15 @@ context = RubyLLM::Browser::Context.new(
   budget: RubyLLM::Browser::Budget.new(max_seconds: 30, max_steps: 6)
 )
 
-inspect = RubyLLM::Browser::Inspect.new(context: context)
-puts "Inspect: #{inspect.execute(url: "https://docs.example.com/")}"
-
 schema = { "type" => "object", "properties" => { "title" => { "type" => "string" } } }
-extract = RubyLLM::Browser::Extract.new(context: context, schema: schema)
+inspect, extract = RubyLLM::Browser.tools(context: context, schema: schema)
+puts "Inspect: #{inspect.execute(url: "https://docs.example.com/")}"
 puts "Extract: #{extract.execute(url: "https://docs.example.com/", instruction: "the title")}"
 
 blocked = inspect.execute(url: "http://169.254.169.254/latest/meta-data")
 puts "Blocked: #{blocked[:error][:code]}"
+
+report = RubyLLM::Browser::Doctor.new(backend: context.backend).report
+raise "offline diagnostic failed" unless report[:ok] && report[:mode] == :offline
+raise "provider checks ran offline" if report[:checks].any? { |check| check[:name] == :credentials }
+puts "Doctor: #{report[:mode]}"

data/examples/rails_results.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# A host-owned result table and a single-job file queue, using only FakeBackend.
+# This disposable demonstration is not a production queue, controller or migration.
+require "ruby_llm/browser/rails"
+require "logger"
+require "open3"
+require "tmpdir"
+
+module BrowserResultsExample
+  SCHEMA = { "type" => "object", "properties" => { "title" => { "type" => "string" } },
+             "required" => [ "title" ], "additionalProperties" => false }.freeze
+  RESOLVER = Object.new
+  def RESOLVER.getaddresses(_host) = [ "93.184.216.34" ]
+
+  class ResultRecord < ActiveRecord::Base
+    self.table_name = "example_browser_results"
+    self.primary_key = "operation_id"
+  end
+
+  class FileQueue
+    def initialize(path) = @path = path
+    def enqueue(job) = File.write(@path, JSON.generate(job.serialize))
+    def enqueue_at(*) = raise(ArgumentError, "demo queue supports immediate jobs only")
+  end
+
+  module_function
+
+  def connect(database)
+    ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: database, timeout: 5000)
+    ActiveRecord::Base.logger = Logger.new(IO::NULL)
+    ActiveJob::Base.logger = Logger.new(IO::NULL)
+    RubyLLM::Browser::Rails::Schema.create!
+    connection = ActiveRecord::Base.connection
+    return if connection.table_exists?(ResultRecord.table_name)
+
+    connection.create_table(ResultRecord.table_name, id: false) do |table|
+      table.string :operation_id, primary_key: true, null: false
+      table.string :actor_id, null: false
+      table.string :run_id, null: false
+      table.text :body, null: false
+      table.datetime :created_at, null: false
+    end
+  end
+
+  def configure(backend: RubyLLM::Browser::FakeBackend.new)
+    RubyLLM::Browser::Rails.context_factory = lambda do |actor_id:, run_id:|
+      RubyLLM::Browser::Context.new(
+        actor_id: actor_id, run_id: run_id, backend: backend,
+        source_policy: RubyLLM::Browser::Policy.new(allowed_hosts: [ "docs.example.com" ], resolver: RESOLVER),
+        operation_store: RubyLLM::Browser::Rails.operation_store
+      )
+    end
+    RubyLLM::Browser::Rails.result_delivery = lambda do |operation:, result:|
+      store_result(operation: operation, payload: result.to_h)
+    end
+  end
+
+  # Trusted server API. The worker supplies identity, never a model or request body.
+  def store_result(operation:, payload:)
+    body = RubyLLM::Browser::Redactor.canonical_json(payload)
+    ResultRecord.transaction do
+      record = ResultRecord.create_or_find_by!(operation_id: operation.id) do |row|
+        row.actor_id = operation.actor_id
+        row.run_id = operation.run_id
+        row.body = body
+      end
+      unless [ record.actor_id, record.run_id, record.body ] == [ operation.actor_id, operation.run_id, body ]
+        raise RubyLLM::Browser::InvalidInput, "conflicting result delivery"
+      end
+    end
+  end
+
+  # In an HTTP host, derive actor/run from authenticated records and recheck access.
+  # Use the same response for a missing result and an inaccessible result.
+  def read_result(operation_id:, actor_id:, run_id:)
+    record = ResultRecord.find_by(operation_id: operation_id, actor_id: actor_id, run_id: run_id)
+    raise RubyLLM::Browser::NotAuthorized, "result unavailable" unless record
+
+    JSON.parse(record.body)
+  end
+
+  def worker(database, queue_file)
+    connect(database)
+    backend = RubyLLM::Browser::FakeBackend.new
+    configure(backend: backend)
+    ActiveJob::Base.execute(JSON.parse(File.read(queue_file)))
+    puts JSON.generate(starts: backend.call_count(:start), closes: backend.call_count(:end_session))
+  end
+
+  def run_demo
+    Dir.mktmpdir("browser-results-") do |directory|
+      database = File.join(directory, "host.sqlite3")
+      queue_file = File.join(directory, "job.json")
+      connect(database)
+      ActiveJob::Base.queue_adapter = FileQueue.new(queue_file)
+      operation = RubyLLM::Browser::Rails::OperationJob.enqueue(
+        actor_id: "demo-actor", run_id: "demo-run", kind: :extract,
+        url: "https://docs.example.com/", schema: SCHEMA,
+        budget: RubyLLM::Browser::Budget.new, idempotency_key: "demo-result"
+      )
+      # capture3 waits for exit. Execute the serialized job twice in separate workers.
+      [ 1, 0 ].each do |expected_starts|
+        stdout, stderr, status = Open3.capture3(RbConfig.ruby, "-I", File.expand_path("../lib", __dir__),
+                                               __FILE__, "worker", database, queue_file)
+        raise "worker failed: #{stderr}" unless status.success?
+        unless JSON.parse(stdout) == { "starts" => expected_starts, "closes" => expected_starts }
+          raise "unexpected browser dispatch"
+        end
+      end
+
+      payload = read_result(operation_id: operation.id, actor_id: "demo-actor", run_id: "demo-run")
+      raise "lost extraction" unless payload.fetch("data") == { "title" => "Example" } && payload.fetch("status") == "ok"
+      raise "lost provenance" unless payload.fetch("locator").fetch("schema_digest") == RubyLLM::Browser::Redactor.digest(SCHEMA)
+      puts "RESULT_AFTER_WORKER_EXIT_PASS"
+
+      [ [ "other-actor", "demo-run" ], [ "demo-actor", "other-run" ] ].each do |actor, run|
+        begin
+          read_result(operation_id: operation.id, actor_id: actor, run_id: run)
+          raise "cross-scope result leak"
+        rescue RubyLLM::Browser::NotAuthorized
+          # Expected refusal, including after the worker has exited.
+        end
+      end
+      puts "SCOPED_READS_PASS"
+      2.times { store_result(operation: operation, payload: payload) }
+      raise "duplicate result rows" unless ResultRecord.count == 1
+      puts "IDEMPOTENT_WRITE_PASS"
+    ensure
+      ActiveRecord::Base.connection_pool.disconnect!
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  if ARGV.first == "worker"
+    BrowserResultsExample.worker(*ARGV.drop(1))
+  else
+    BrowserResultsExample.run_demo
+  end
+end

data/lib/ruby_llm/browser/doctor.rb

@@ -2,12 +2,13 @@
 
 module RubyLLM
   module Browser
-    # Read-only preflight diagnostics for a live browser deployment.
+    # Read-only configuration diagnostics for an offline or live backend.
     #
     # The Doctor never makes a network call, never starts a session and never prints a
-    # credential. It reports the version pins, the environment overrides that the SDK
-    # would otherwise honour, and whether the configured backend is qualified to start a
-    # session. A `:fail` check means live use must not proceed.
+    # credential. Common checks report RubyLLM compatibility and backend capabilities.
+    # Only Stagehand backends inspect Stagehand's SDK and environment. FakeBackend
+    # checks do not load the SDK or inspect provider credentials. A local pass never
+    # qualifies a provider's actual guarantees. A `:fail` check blocks use.
     #
     #   report = RubyLLM::Browser::Doctor.new(backend: backend).report
     #   raise report[:summary] unless report[:ok]
@@ -23,13 +24,15 @@ module RubyLLM
         @env = env
       end
 
-      # @return [Hash] `{ ok:, summary:, checks: [...] }`, safe to log
+      # @return [Hash] `{ mode:, ok:, summary:, checks: [...] }`, safe to log.
+      #   Mode is `:offline` for FakeBackend in fake mode, `:unconfigured` without
+      #   a backend, and `:live` otherwise. Existing report keys remain available.
       def report
-        checks = [
-          ruby_llm_check, stagehand_check, egress_check, local_binary_check,
-          custom_headers_check, base_url_check, credentials_check
-        ].compact
+        checks = [ ruby_llm_check, egress_check, local_binary_check, custom_headers_check ]
+        checks.concat([ stagehand_check, base_url_check, credentials_check ]) if backend.is_a?(StagehandBackend)
+        checks.compact!
         {
+          mode: mode,
           ok: checks.none? { |check| check[:status] == :fail },
           summary: summary_for(checks),
           checks: checks
@@ -40,6 +43,13 @@ module RubyLLM
 
       private
 
+      def mode
+        return :unconfigured unless backend
+        return :offline if backend.is_a?(FakeBackend) && backend.capabilities.server_mode == :fake
+
+        :live
+      end
+
       def ruby_llm_check
         version = Gem::Version.new(RubyLLM::VERSION)
         required = Gem::Version.new("2.0.0")
@@ -72,7 +82,12 @@ module RubyLLM
                        "Stagehand backend is unsupported until provider egress and cleanup are qualified")
         end
         if capabilities.enforced_egress?
-          check(:egress_isolation, :pass, "the backend asserts enforced, browser-side egress isolation")
+          detail = if mode == :offline
+            "FakeBackend performs no network I/O; live egress is not verified"
+          else
+            "the backend asserts enforced, browser-side egress isolation"
+          end
+          check(:egress_isolation, :pass, detail)
         else
           check(:egress_isolation, :fail,
                 "the backend does not assert enforced egress isolation; live sessions are refused")

data/lib/ruby_llm/browser/rails/operation_job.rb

@@ -91,8 +91,14 @@ module RubyLLM
                                      max_bytes: max_bytes)
 
           # Keep unknown action/start results, even when cleanup later closes a session.
-          final = settled(operation_id)
+          completed = store.fetch!(operation_id)
+          final = settled(completed)
           return :cancelled if final == :cancelled
+          # Cancellation can still await cleanup. A reaper or newer worker can also
+          # fence this job while the browser call is in flight.
+          return :fenced_out unless completed.cancel_requested? || completed.fence == leased.fence
+
+          deliver(completed, result) unless completed.cancel_requested?
 
           result.ok? ? (final || result.to_h) : result.to_h
         rescue InvalidInput => e
@@ -106,15 +112,21 @@ module RubyLLM
         # Reports the durable state if the host cancelled or another worker fenced this
         # one while the operation was running; otherwise returns nil so the engine's own
         # result is used.
-        def settled(operation_id)
-          final = store.fetch(operation_id)
-          case final&.state
+        def settled(operation)
+          case operation.state
           when :cancelled then :cancelled
           when :cleanup_pending then :cleanup_pending
           when :unknown then :unknown
           end
         end
 
+        def deliver(operation, result)
+          RubyLLM::Browser::Rails.result_delivery&.call(operation: operation, result: result)
+        rescue StandardError
+          # Queue logs may print chained exceptions containing host credentials.
+          raise ResultDeliveryError.new(operation: operation, result: result), cause: nil
+        end
+
         def run(kind, operation, url:, instruction:, schema:, max_bytes:)
           context = build_context(operation)
           unless context.is_a?(Context) && context.operation_store.equal?(store)

data/lib/ruby_llm/browser/rails/result_delivery_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Browser
+    module Rails
+      # The host callback failed after browser execution and cleanup were attempted.
+      # Retain these values in host storage to retry delivery without rerunning a job.
+      # These are in-process objects, not a durable queue or automatic retry policy.
+      class ResultDeliveryError < Error
+        CODE = "RESULT_DELIVERY_FAILED"
+
+        attr_reader :operation, :result
+
+        def initialize(operation:, result:)
+          @operation = operation
+          @result = result
+          super("host result delivery failed; retry delivery without repeating browser work")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/browser/rails.rb

@@ -27,6 +27,7 @@ require_relative "rails/operation_record"
 require_relative "rails/approval_record"
 require_relative "rails/active_record_operation_store"
 require_relative "rails/active_record_approval_store"
+require_relative "rails/result_delivery_error"
 require_relative "rails/operation_job"
 require_relative "rails/reaper"
 
@@ -41,6 +42,20 @@ module RubyLLM
         # ->(actor_id:, run_id:) { RubyLLM::Browser::Context }, supplied by the host.
         attr_accessor :context_factory
 
+        # Optional host callback: ->(operation:, result:) { persist_result }.
+        # Runs synchronously after execution and cleanup, before the job returns.
+        # Raise to report failure; return values are ignored. Duplicate jobs do not
+        # redeliver. The host owns persistence, idempotency, access and recovery.
+        attr_reader :result_delivery
+
+        def result_delivery=(callback)
+          unless callback.nil? || callback.respond_to?(:call)
+            raise InvalidInput, "result_delivery must be callable or nil"
+          end
+
+          @result_delivery = callback
+        end
+
         # Returns the current UTC time used by the adapter.
         def clock
           @clock ||= -> { Time.now.utc }
@@ -68,6 +83,7 @@ module RubyLLM
         # Restores process defaults. Primarily a test helper.
         def reset!
           @context_factory = nil
+          @result_delivery = nil
           @clock = nil
           @job_queue = nil
           @operation_store = nil