browserctl 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '08df95ac04f1480c4e39d857c1472342b8b256a2047cb83808ba62daaf184330'
-  data.tar.gz: 1f67c6b991dd20af3907ab9a803f1021817e6d9b5dbe1774e42f0c509d907067
+  metadata.gz: 68f01c2bd0b65b0b6ac9243df7986b7d99c7d6a31b9ed346ae96da965b70588b
+  data.tar.gz: c1441ed479aad729c2af205313c35ea04793c1b6929a2a538584c907a982cff3
 SHA512:
-  metadata.gz: 5752121da2c9a9551773b6ab8b9c4f060744f14a6f505d7c38ab9338a99b2cda4012a22869b633be883ad1c810bb717e0edb77da8ef4eb3b7bf8eef19593efde
-  data.tar.gz: 4c44a6cfbb1b4402e30e1911c26bdfb608d3584ba463623fd8c75638ad836dcb428fcb0d99d58d37c2e557b0752c84f288288bad800667e18300cb36ace2570c
+  metadata.gz: 0ccabb955b4cfc4581d1afe8ea87b5d2afc432f0f31ef568a6aad2b9c13b37e28bb72b4ea74eef3056d5348aef4d1072059ab84a3721966d7cccb20bc9e69f1d
+  data.tar.gz: 2169db821391d766570667b3332672860db014e8ad3b35ab26e953127bd5fa9bba05f1b99c5d0195e01e988ee49409f197ccde4405981200384d7e60b67913b8

data/CHANGELOG.md

@@ -10,6 +10,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.0](https://github.com/patrick204nqh/browserctl/compare/v0.14.0...v0.15.0) (2026-05-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* Cookie and storage wire / CLI / client surfaces are deprecated in favour of the unified `data --scope ...` verb. Old paths still work in v0.15 but emit a one-line deprecation warning to stderr (suppressed under `--output json`) and are removed at 1.0. See docs/architecture/decisions/0021-data-verb-consolidation.md.
+
+### Features
+
+* data verb consolidates cookie and storage commands (v0.15 WS-1 PR 2) ([#207](https://github.com/patrick204nqh/browserctl/issues/207)) ([4b0beca](https://github.com/patrick204nqh/browserctl/commit/4b0becaf014fe27f92dfdc48f03bd1d75e06896d))
+* pluggable tracing hook (v0.15 WS-4 PR 7) ([#203](https://github.com/patrick204nqh/browserctl/issues/203)) ([f8f725e](https://github.com/patrick204nqh/browserctl/commit/f8f725e4022defa2c56e1c3dfda831f348bf2fc4))
+* plugin command timeout and error isolation (v0.15 WS-2 PR 5) ([#202](https://github.com/patrick204nqh/browserctl/issues/202)) ([5bc1e36](https://github.com/patrick204nqh/browserctl/commit/5bc1e3609a1d0739369cdad7e5c5cd27f6116ec7))
+
+
+### Bug Fixes
+
+* dialog handlers use with_page mutex pattern (v0.15 WS-2 PR 4) ([#193](https://github.com/patrick204nqh/browserctl/issues/193)) ([f35f513](https://github.com/patrick204nqh/browserctl/commit/f35f5137011db40b52a77008bba62e19e73ccb0d))
+* sweep remaining [@pages](https://github.com/pages) raw access in handlers (v0.15 WS-2 PR 4b) ([#208](https://github.com/patrick204nqh/browserctl/issues/208)) ([9d57a6d](https://github.com/patrick204nqh/browserctl/commit/9d57a6d2bb0a20a06c3a04024517448cd37c290a))
+
 ## [0.14.0](https://github.com/patrick204nqh/browserctl/compare/v0.13.1...v0.14.0) (2026-05-11)
 
 

data/README.md

@@ -5,7 +5,11 @@
 <h1 align="center">browserctl</h1>
 
 <p align="center">
-  The browser you delegate to your agents — with a pause button for the parts that still need you.
+  persistent browser sessions with human-in-the-loop.
+</p>
+
+<p align="center">
+  <sub>Built for AI agents. Useful to the engineers and QA folks who work with them.</sub>
 </p>
 
 <p align="center">
@@ -55,8 +59,8 @@ browserctl url main
 browserctl page snapshot main --diff       # only what changed
 
 # Session persistence: save now, pick up later
-browserctl session save my-session
-# On a fresh daemon tomorrow: `browserctl session load my-session`
+browserctl state save my-session
+# On a fresh daemon tomorrow: `browserctl state load my-session`
 # → tabs restored, cookies intact, no re-login needed
 
 # 7. Done

data/bin/browserctl

@@ -25,6 +25,7 @@ require "browserctl/commands/init"
 require "browserctl/commands/page"
 require "browserctl/commands/cookie"
 require "browserctl/commands/storage"
+require "browserctl/commands/data"
 require "browserctl/commands/state"
 require "browserctl/commands/daemon"
 require "browserctl/commands/workflow"
@@ -93,14 +94,20 @@ def usage
       dialog accept  <page> [text]
       dialog dismiss <page>
 
-    Cookie:
+    Data (v0.15+, replaces 'cookie *' and 'storage *' — removed at 1.0):
+      data get    <page> <key> --scope {cookies|localStorage|sessionStorage}
+      data set    <page> <key> <value> --scope SCOPE [--domain D] [--path /]
+      data delete <page> --scope SCOPE
+      data list   <page> --scope SCOPE
+
+    Cookie (deprecated, removed at 1.0 — use 'data --scope cookies'):
       cookie list   <page>
       cookie set    <page> <name> <value> --domain DOMAIN [--path /]
       cookie delete <page>
       cookie export <page> <path>
       cookie import <page> <path>
 
-    Storage:
+    Storage (deprecated, removed at 1.0 — use 'data --scope localStorage|sessionStorage'):
       storage get    <page> <key> [--store local|session]
       storage set    <page> <key> <value> [--store local|session]
       storage export <page> <path> [--store local|session|all]
@@ -214,6 +221,7 @@ begin
     when "page"     then Browserctl::Commands::Page.run(client, args)
     when "cookie"   then Browserctl::Commands::Cookie.run(client, args)
     when "storage"  then Browserctl::Commands::Storage.run(client, args)
+    when "data"     then Browserctl::Commands::Data.run(client, args)
     when "state"    then Browserctl::Commands::State.run(client, args)
     when "daemon"   then Browserctl::Commands::Daemon.run(client, args)
     when "auth-check"

data/examples/tracing_otel.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Example: wire browserctl's tracing seam to an OpenTelemetry exporter.
+#
+# This file is doc-only — it is NOT required by the gem, and OpenTelemetry
+# is NOT a runtime dependency. Add `opentelemetry-sdk` and an exporter to
+# your own application's Gemfile if you want this wiring.
+#
+# Usage (from a host app, before any browserctl commands are dispatched):
+#
+#   require "opentelemetry/sdk"
+#   require "opentelemetry/exporter/otlp"
+#   require "browserctl"
+#   require_relative "path/to/tracing_otel"
+#
+#   Browserctl::Tracing.backend = OtelTracingBackend.new
+#
+# Every command dispatched by the daemon will then emit a span named
+# `command.<cmd>` with `command`, `page`, and `duration_ms` attributes.
+
+require "opentelemetry/sdk"
+
+# Adapter from browserctl's Backend contract to the OpenTelemetry Ruby API.
+class OtelTracingBackend
+  def initialize(tracer_name: "browserctl", version: Browserctl::VERSION)
+    @tracer = OpenTelemetry.tracer_provider.tracer(tracer_name, version)
+  end
+
+  def start_span(name, attributes: {})
+    @tracer.start_span(name, attributes: stringify(attributes))
+  end
+
+  def end_span(span, status:, attributes: {})
+    return if span.nil?
+
+    attributes.each { |k, v| span.set_attribute(k.to_s, v) unless v.nil? }
+    span.status = OpenTelemetry::Trace::Status.error if status == :error
+    span.finish
+  end
+
+  private
+
+  def stringify(attrs)
+    attrs.each_with_object({}) { |(k, v), h| h[k.to_s] = v unless v.nil? }
+  end
+end

data/lib/browserctl/callable_definition.rb

@@ -20,8 +20,8 @@ module Browserctl
   # deliberately absent from `FlowContext` — flows return state, workflows
   # share state.
   class CallableDefinition
-    ParamDef = Struct.new(:name, :required, :secret, :default, :secret_ref, keyword_init: true)
-    StepDef  = Struct.new(:label, :block, :retry_count, :timeout, keyword_init: true)
+    ParamDef = Data.define(:name, :required, :secret, :default, :secret_ref)
+    StepDef  = Data.define(:label, :block, :retry_count, :timeout)
 
     attr_reader :name, :description, :param_defs, :steps
 

data/lib/browserctl/client.rb

@@ -245,6 +245,47 @@ module Browserctl
       call("storage_delete", name: name, stores: stores)
     end
 
+    # Reads a single key from the given browser-side scope.
+    # Introduced in v0.15 as the unified replacement for `storage_get` /
+    # `cookies` (see ADR-0021).
+    # @param name [String] logical page name
+    # @param key [String] storage key (n/a for `scope: "cookies"`; use {#data_list})
+    # @param scope [String] one of "cookies", "localStorage", "sessionStorage"
+    # @return [Hash] `{ ok: true, scope:, key:, value: }` or `{ error:, code: }`
+    def data_get(name, key, scope:)
+      call("data_get", name: name, key: key, scope: scope)
+    end
+
+    # Writes a single key/value into the given browser-side scope.
+    # For `scope: "cookies"`, `domain:` is required and `path:` defaults to "/".
+    # @param name [String] logical page name
+    # @param key [String] storage key (cookie name when scope is cookies)
+    # @param value [String] value to store
+    # @param scope [String] one of "cookies", "localStorage", "sessionStorage"
+    # @param domain [String, nil] cookie domain (required when scope is cookies)
+    # @param path [String] cookie path (default: "/")
+    # @return [Hash] `{ ok: true, scope:, key: }` or `{ error:, code: }`
+    def data_set(name, key, value, scope:, domain: nil, path: "/") # rubocop:disable Metrics/ParameterLists
+      call("data_set", name: name, key: key, value: value,
+                       scope: scope, domain: domain, path: path)
+    end
+
+    # Clears every entry in the given browser-side scope.
+    # @param name [String] logical page name
+    # @param scope [String] one of "cookies", "localStorage", "sessionStorage"
+    # @return [Hash] `{ ok: true, scope:, deleted: N }` or `{ error:, code: }`
+    def data_delete(name, scope:)
+      call("data_delete", name: name, scope: scope)
+    end
+
+    # Lists every entry in the given browser-side scope.
+    # @param name [String] logical page name
+    # @param scope [String] one of "cookies", "localStorage", "sessionStorage"
+    # @return [Hash] `{ ok: true, scope:, entries: [...], count: N }` or `{ error:, code: }`
+    def data_list(name, scope:)
+      call("data_list", name: name, scope: scope)
+    end
+
     # Fires a keydown + keyup event for the given key name on a page.
     # @param name [String] logical page name
     # @param key [String] key name e.g. "Enter", "Tab", "Escape", "ArrowDown"

data/lib/browserctl/commands/cookie.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "cli_output"
+require_relative "deprecation_notice"
 
 module Browserctl
   module Commands
@@ -11,6 +12,11 @@ module Browserctl
 
       def self.run(client, args)
         sub = args.shift or abort USAGE
+        # Deprecated in v0.15 — see ADR-0021. Removed at 1.0.
+        DeprecationNotice.emit(
+          "cookie #{sub}",
+          deprecation_replacement(sub)
+        )
         case sub
         when "list"   then run_list(client, args)
         when "set"    then run_set(client, args)
@@ -21,6 +27,17 @@ module Browserctl
         end
       end
 
+      def self.deprecation_replacement(sub)
+        case sub
+        when "list"   then "data list <page> --scope cookies"
+        when "set"    then "data set <page> <name> <value> --scope cookies --domain DOMAIN"
+        when "delete" then "data delete <page> --scope cookies"
+        when "export" then "data list <page> --scope cookies  # write to file client-side"
+        when "import" then "data set <page> --scope cookies"
+        else "data <op> --scope cookies"
+        end
+      end
+
       def self.run_list(client, args)
         page = args.shift or abort "usage: browserctl cookie list <page>"
         print_result(client.cookies(page))

data/lib/browserctl/commands/data.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "cli_output"
+
+module Browserctl
+  module Commands
+    # `browserctl data <op> --scope <scope>` — unified verb for browser-side
+    # persistent data. Introduced in v0.15 (ADR-0021) as the replacement for
+    # the duplicated `cookie *` and `storage *` families.
+    module Data
+      extend CliOutput
+
+      USAGE = "Usage: browserctl data <get|set|delete|list> --scope " \
+              "{cookies|localStorage|sessionStorage} [args]"
+
+      def self.run(client, args)
+        sub = args.shift or abort USAGE
+        case sub
+        when "get"    then run_get(client, args)
+        when "set"    then run_set(client, args)
+        when "delete" then run_delete(client, args)
+        when "list"   then run_list(client, args)
+        else abort "unknown data subcommand '#{sub}'\n#{USAGE}"
+        end
+      end
+
+      def self.run_get(client, args)
+        page  = args.shift or abort "usage: browserctl data get <page> <key> --scope SCOPE"
+        key   = args.shift or abort "usage: browserctl data get <page> <key> --scope SCOPE"
+        scope = extract_required_scope(args)
+        print_result(client.data_get(page, key, scope: scope))
+      end
+
+      SET_USAGE = "usage: browserctl data set <page> <key> <value> --scope SCOPE [--domain D] [--path /]"
+
+      def self.run_set(client, args)
+        page   = args.shift or abort SET_USAGE
+        key    = args.shift or abort SET_USAGE
+        value  = args.shift or abort SET_USAGE
+        scope  = extract_required_scope(args)
+        domain = extract_opt(args, "--domain")
+        path   = extract_opt(args, "--path") || "/"
+        print_result(client.data_set(page, key, value, scope: scope, domain: domain, path: path))
+      end
+
+      def self.run_delete(client, args)
+        page  = args.shift or abort "usage: browserctl data delete <page> --scope SCOPE"
+        scope = extract_required_scope(args)
+        print_result(client.data_delete(page, scope: scope))
+      end
+
+      def self.run_list(client, args)
+        page  = args.shift or abort "usage: browserctl data list <page> --scope SCOPE"
+        scope = extract_required_scope(args)
+        print_result(client.data_list(page, scope: scope))
+      end
+
+      def self.extract_required_scope(args)
+        scope = extract_opt(args, "--scope")
+        abort "missing required flag: --scope {cookies|localStorage|sessionStorage}" unless scope
+        scope
+      end
+
+      def self.extract_opt(args, flag)
+        idx = args.index(flag)
+        return nil unless idx
+
+        args.delete_at(idx)
+        args.delete_at(idx)
+      end
+    end
+  end
+end

data/lib/browserctl/commands/deprecation_notice.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "output_format"
+
+module Browserctl
+  module Commands
+    # One-shot deprecation warning emitter for v0.15 alias verbs.
+    #
+    # Per ADR-0021: when a CLI invocation uses `cookie *` or `storage *`,
+    # we emit exactly one line to stderr — never under `--output json`, so
+    # JSON consumers (AI agents, scripts) keep a clean parser input. The
+    # warning is memoised process-wide so a single CLI invocation only ever
+    # prints it once even if a wrapper calls the dispatcher multiple times.
+    module DeprecationNotice
+      REMOVAL = "Removed at 1.0."
+
+      module_function
+
+      def emit(old_verb, replacement, io: $stderr)
+        return if @emitted
+        return if OutputFormat.current.json?
+
+        @emitted = true
+        io.puts "warning: '#{old_verb}' is deprecated; use '#{replacement}'. #{REMOVAL}"
+      end
+
+      # Test-only — reset memoisation between examples.
+      def reset!
+        @emitted = false
+      end
+    end
+  end
+end

data/lib/browserctl/commands/storage.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "cli_output"
+require_relative "deprecation_notice"
 
 module Browserctl
   module Commands
@@ -11,6 +12,11 @@ module Browserctl
 
       def self.run(client, args)
         sub = args.shift or abort USAGE
+        # Deprecated in v0.15 — see ADR-0021. Removed at 1.0.
+        DeprecationNotice.emit(
+          "storage #{sub}",
+          deprecation_replacement(sub)
+        )
         case sub
         when "get"    then run_get(client, args)
         when "set"    then run_set(client, args)
@@ -21,6 +27,17 @@ module Browserctl
         end
       end
 
+      def self.deprecation_replacement(sub)
+        case sub
+        when "get"    then "data get <page> <key> --scope localStorage"
+        when "set"    then "data set <page> <key> <value> --scope localStorage"
+        when "delete" then "data delete <page> --scope localStorage"
+        when "export" then "data list <page> --scope localStorage  # write to file client-side"
+        when "import" then "data set <page> --scope localStorage"
+        else "data <op> --scope localStorage"
+        end
+      end
+
       def self.run_get(client, args)
         page  = args.shift or abort "usage: browserctl storage get <page> <key> [--store local|session]"
         key   = args.shift or abort "usage: browserctl storage get <page> <key> [--store local|session]"

data/lib/browserctl/detectors/auth_required.rb

@@ -21,7 +21,7 @@ module Browserctl
     # runs server-side (handlers/observation.rb) and client-side (workflow
     # `load_state` hook).
     module AuthRequired
-      Result = Struct.new(:triggered, :code, :reason, :suggested_flow, keyword_init: true) do
+      Result = Data.define(:triggered, :code, :reason, :suggested_flow) do
         def to_h
           { triggered: triggered, code: code, reason: reason, suggested_flow: suggested_flow }.compact
         end

data/lib/browserctl/driver/cdp.rb

@@ -45,9 +45,9 @@ module Browserctl
         capability == :devtools
       end
 
-      def devtools_info(page)
+      def devtools_info(page_driver)
         port      = @ferrum.process.port
-        target_id = page.target_id
+        target_id = page_driver.target_id
         { port: port, target_id: target_id }
       end
 

data/lib/browserctl/driver/ferrum_page_driver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "page_driver"
+
+module Browserctl
+  module Driver
+    # The only {PageDriver} implementation v0.15 ships. Wraps a Ferrum page
+    # (or {CDPPage} delegator over one) and forwards each interface method to
+    # the underlying Ferrum API. Intentionally dumb — no caching, no policy,
+    # no logging. Anything beyond plain forwarding belongs in the handler or
+    # in a dedicated wrapper, not here.
+    class FerrumPageDriver
+      include PageDriver
+
+      # @return [Object] the underlying Ferrum/CDP page. Exposed for callers
+      #   that still bridge through Ferrum-typed APIs (currently only the CDP
+      #   driver's `devtools_info`). New handler code must not use this.
+      attr_reader :raw_page
+
+      def initialize(page)
+        @raw_page = page
+      end
+
+      def go_to(url) = @raw_page.go_to(url)
+      def current_url = @raw_page.current_url
+      def body = @raw_page.body
+      def evaluate(expression) = @raw_page.evaluate(expression)
+      def at_css(selector) = @raw_page.at_css(selector)
+      def screenshot(path:, full: false) = @raw_page.screenshot(path: path, full: full)
+      def activate = @raw_page.activate
+      def close = @raw_page.close
+      def on(event, &) = @raw_page.on(event, &)
+      def off(event, id) = @raw_page.off(event, id)
+      def keyboard_down(key) = @raw_page.keyboard.down(key)
+      def keyboard_up(key) = @raw_page.keyboard.up(key)
+      def mouse_move(x:, y:) = @raw_page.mouse.move(x: x, y: y) # rubocop:disable Naming/MethodParameterName
+      def cookies_all = @raw_page.cookies.all
+      def cookies_set(**) = @raw_page.cookies.set(**)
+      def cookies_clear = @raw_page.cookies.clear
+      def target_id = @raw_page.target_id
+    end
+  end
+end

data/lib/browserctl/driver/page_driver.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Browserctl
+  module Driver
+    # PageDriver is the interface every handler in `lib/browserctl/server/handlers/`
+    # talks to instead of touching a raw Ferrum page. It exists so unit tests can
+    # swap in a `FakePageDriver` (see `spec/support/fake_page_driver.rb`) without
+    # spawning a real browser.
+    #
+    # This module is intentionally a thin contract: Ruby has no real interfaces,
+    # so the implementation is duck-typed. The method list below is the entire
+    # public surface handlers may use. New entries here require a corresponding
+    # implementation in {FerrumPageDriver} **and** the test double, plus a
+    # handler that justifies them — do not add methods speculatively.
+    #
+    # Element-returning methods (currently only {#at_css}) return whatever the
+    # underlying driver returns. The fake driver returns stub objects with
+    # matching duck-typed methods (`focus`, `type`, `click`, `evaluate`,
+    # `select_file`). Handlers should treat these as opaque element handles.
+    #
+    # PageDriver lives in the **Extension** zone of the public surface
+    # (see `docs/reference/api-stability.md`). It is a testing seam, not an
+    # invitation to ship a non-Ferrum backend — that path is explicitly a
+    # non-goal of v0.15 (`docs/plans/v0.15-lock.md`).
+    module PageDriver
+      # Navigate the page to the given URL. Blocks until load completes.
+      # @param url [String]
+      def go_to(url) = raise NotImplementedError
+
+      # @return [String] the current top-frame URL
+      def current_url = raise NotImplementedError
+
+      # @return [String] the current page body HTML
+      def body = raise NotImplementedError
+
+      # Evaluate a JS expression in the page context.
+      # @param expression [String]
+      # @return [Object] the JSON-decoded result
+      def evaluate(expression) = raise NotImplementedError
+
+      # Find the first element matching the CSS selector.
+      # @param selector [String]
+      # @return [Object, nil] an element handle (duck-typed: `focus`, `type`,
+      #   `click`, `evaluate`, `select_file`) or nil if no match
+      def at_css(selector) = raise NotImplementedError
+
+      # Capture a screenshot to disk.
+      # @param path [String]
+      # @param full [Boolean]
+      def screenshot(path:, full: false) = raise NotImplementedError
+
+      # Bring the page tab to the foreground (headed mode only).
+      def activate = raise NotImplementedError
+
+      # Close the underlying page/tab.
+      def close = raise NotImplementedError
+
+      # Subscribe to a page event (currently only `:dialog`).
+      # @return [Object] a subscription id usable with {#off}
+      def on(event, &) = raise NotImplementedError
+
+      # Remove a subscription created by {#on}.
+      def off(event, id) = raise NotImplementedError
+
+      # Press a key down. Pair with {#keyboard_up}.
+      def keyboard_down(key) = raise NotImplementedError
+
+      # Release a key.
+      def keyboard_up(key) = raise NotImplementedError
+
+      # Move the mouse pointer to viewport coordinates.
+      def mouse_move(x:, y:) = raise NotImplementedError # rubocop:disable Naming/MethodParameterName
+
+      # @return [Hash{String => Object}] all cookies for the page, keyed by
+      #   cookie name, with each value responding to `to_h`.
+      def cookies_all = raise NotImplementedError
+
+      # Set a cookie. Accepts `name:`, `value:`, `domain:`, `path:`, and any
+      # of `httponly:`, `secure:`, `expires:`.
+      def cookies_set(**) = raise NotImplementedError
+
+      # Clear every cookie on the page.
+      def cookies_clear = raise NotImplementedError
+
+      # Underlying CDP target id; used by the devtools handler. Backends that
+      # do not expose CDP should raise.
+      def target_id = raise NotImplementedError
+    end
+  end
+end

data/lib/browserctl/error/codes.rb

@@ -29,6 +29,18 @@ module Browserctl
       INVALID_STATE_NAME       = "INVALID_STATE_NAME"
       INVALID_DSL_USAGE        = "INVALID_DSL_USAGE"
       INVALID_FORMAT_VERSION   = "INVALID_FORMAT_VERSION"
+      INVALID_ARGUMENT         = "INVALID_ARGUMENT"
+
+      # Plugin family — introduced in v0.15 WS-2 PR 5 to isolate the daemon
+      # from misbehaving third-party commands registered via
+      # `Browserctl.register_command`. PLUGIN_FAILED is the catch-all when an
+      # uncaught exception escapes the plugin block; PLUGIN_TIMED_OUT is
+      # emitted when the per-plugin timeout (default 30s, configurable via
+      # `timeout:` on `register_command`, opt-out via `timeout: nil`) elapses
+      # before the block returns. Both codes carry the plugin name in the
+      # response payload's `context` so agents can branch on it.
+      PLUGIN_FAILED            = "PLUGIN_FAILED"
+      PLUGIN_TIMED_OUT         = "PLUGIN_TIMED_OUT"
 
       GENERIC                  = "GENERIC"
 
@@ -46,6 +58,9 @@ module Browserctl
         INVALID_STATE_NAME,
         INVALID_DSL_USAGE,
         INVALID_FORMAT_VERSION,
+        INVALID_ARGUMENT,
+        PLUGIN_FAILED,
+        PLUGIN_TIMED_OUT,
         GENERIC
       ].freeze
 

data/lib/browserctl/error/exit_codes.rb

@@ -36,6 +36,13 @@ module Browserctl
       # entry in this table — drift-related raises fall through to GENERIC
       # until that code is introduced.
       #
+      # The plugin family (PLUGIN_FAILED, PLUGIN_TIMED_OUT) intentionally has
+      # no dedicated entry — plugins are Extension-zone surface (see
+      # api-stability.md), so their failures collapse to GENERIC (1) like the
+      # other Extension-adjacent codes (DOMAIN_NOT_ALLOWED, KEY_NOT_FOUND,
+      # SECRET_RESOLUTION_FAILED). Agents must branch on the `code` field for
+      # plugin failures, not on `$?`.
+      #
       # The validation family (VALIDATION_FAILED parent plus INVALID_*
       # specialisations) all map to exit code 8 — agents and scripts can
       # branch on `$? == 8` for any caller-side validation failure without
@@ -50,7 +57,8 @@ module Browserctl
         Codes::INVALID_SELECTOR_REF => VALIDATION_FAILED,
         Codes::INVALID_STATE_NAME => VALIDATION_FAILED,
         Codes::INVALID_DSL_USAGE => VALIDATION_FAILED,
-        Codes::INVALID_FORMAT_VERSION => VALIDATION_FAILED
+        Codes::INVALID_FORMAT_VERSION => VALIDATION_FAILED,
+        Codes::INVALID_ARGUMENT => VALIDATION_FAILED
       }.freeze
 
       # @param code [String, nil] a canonical code from {Browserctl::Error::Codes}

data/lib/browserctl/error/suggested_actions.rb

@@ -39,6 +39,13 @@ module Browserctl
           "required blocks or arguments are missing.",
         Codes::INVALID_FORMAT_VERSION =>
           "Use a non-negative Integer for the format version header; see docs/reference/format-versions.md.",
+        Codes::INVALID_ARGUMENT =>
+          "Check the argument value against the documented contract; " \
+          "e.g. --scope must be one of cookies|localStorage|sessionStorage.",
+        Codes::PLUGIN_FAILED =>
+          "Check the plugin's logs; the daemon caught an uncaught exception from the plugin and is otherwise healthy.",
+        Codes::PLUGIN_TIMED_OUT =>
+          "Increase the plugin's `timeout:` on register_command, or pass `timeout: nil` to opt out (not recommended).",
         Codes::GENERIC => DEFAULT
       }.freeze
 

data/lib/browserctl/flow.rb

@@ -4,7 +4,7 @@ require_relative "callable_definition"
 require_relative "errors"
 
 module Browserctl
-  FlowConditionDef = Struct.new(:kind, :label, :block, keyword_init: true)
+  FlowConditionDef = Data.define(:kind, :label, :block)
 
   # Back-compat aliases — flow_wrapper specs reference these directly.
   FlowParamDef = CallableDefinition::ParamDef

data/lib/browserctl/flows/stdlib/cloudflare_solve.rb

@@ -13,7 +13,7 @@ require_relative "../../flow"
 # the duck-typed (current_url, body) interface the detector expects.
 module Browserctl
   module Flows
-    PageDetectorAdapter = Struct.new(:current_url, :body)
+    PageDetectorAdapter = Data.define(:current_url, :body)
 
     module CloudflareSolve
       module_function

data/lib/browserctl/migrations.rb

@@ -22,11 +22,11 @@ module Browserctl
     # absolute path of the file being migrated; it is responsible for
     # rewriting that file in place, advancing it from `from_version` to
     # `to_version`.
-    Migration = Struct.new(:format, :from_version, :to_version, :upgrade, keyword_init: true)
+    Migration = Data.define(:format, :from_version, :to_version, :upgrade)
 
     # Result of {.run}. `applied` is the ordered list of {Migration} steps
     # that ran. When the artifact was already at target, `applied` is empty.
-    Result = Struct.new(:format, :from, :to, :applied, keyword_init: true)
+    Result = Data.define(:format, :from, :to, :applied)
 
     FORMAT_EXTENSIONS = {
       ".bctl" => :bundle,