visiq 0.1.2-x86_64-linux → 0.1.4-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7dbb31a8e823edb4aef346185fbb5a0b5158216679bc7adfb51c3b42b9a7860e
-  data.tar.gz: 74e1c290d372e45c56ce266e832775f9851f6929cd92733614ca04aa9ede4361
+  metadata.gz: e4dbb0d7342d5cb72587db4bf9e6424fbd6272ab11b522a7648b94afdbc60491
+  data.tar.gz: f3ccae163b896a6f472bea95e81922e593f67a6930557cafba6364c07136ba2b
 SHA512:
-  metadata.gz: 63282971a7c52551376efb0cf336c161ec89c7558e53880ec42e025a3ca5fc3d71854b67381d6cd35d14f9c42621990373170fc5f7a852423be2ff7b64b1bc5d
-  data.tar.gz: e362ca021ad313422efaf0bc09357de343928ab827c0b21ae308aaf2ac60d2b166e187e415aa00fc6632bbd092946fd249b3c18a3535204e160691732a69fa47
+  metadata.gz: bba89fb5fe5b4944ebdea892b5ac6ae9f2a9af6fb6978a3280a0f7bed14f5e1ac684298df780625e749395f4da459ad2c443723027a299c59e61a4f2ff5b14c5
+  data.tar.gz: d8df3f3ef9389acde4c5ed5c798a57a0cf9c0aa7da7a19de49d45e9592e0594ac4ebebc247db57bb570a9dc439bc763332a33868601b23e6b63724dfb698f6bb

data/README.md

@@ -7,7 +7,8 @@ in-process by the compiled VisIQ core that every VisIQ SDK shares (the same engi
 behind `@visiq/harness`), bound to Ruby through the stdlib `Fiddle` FFI. The engine
 ships as **compiled machine code** (closed); the Ruby is thin FFI plumbing only.
 
-- **Local & fast** — every decision is in-process, no network.
+- **Local & fast**: every decision is in-process. `Visiq::Governor` fetches the
+  agent's rules from the control plane and keeps them current.
 - **Fail-open by default (G001 rescope, owner 2026-07-15)** — a harness-internal
   failure (the core can't load, an FFI error) returns a loud fail-open permit;
   set `VISIQ_FAIL_MODE=closed` to block instead. Malformed input and explicit
@@ -25,7 +26,46 @@ Native, per-platform "fat" gems are published for macOS (arm64, x86_64) and Linu
 (x86_64, aarch64) — `gem install` selects the one matching your platform and it
 bundles the compiled core. **Ruby ≥ 3.0.**
 
-## Usage
+## Usage (recommended): the self-refreshing `Visiq::Governor`
+
+```ruby
+require "visiq"
+
+# One per agent, kept for the life of the process. Reads VISIQ_API_KEY (and
+# VISIQ_ENDPOINT for on-premises) from the environment when not passed here.
+governor = Visiq::Governor.new(agent_id: "agent-1")
+
+d = governor.gate_action(tool_name: "wire_transfer", args: { "amount" => 999 })
+block_the_call unless d["allowed"]
+r = governor.gate_retrieval(resource_metadata: { "classification" => "ssn" })
+```
+
+The `Governor` fetches `GET /rules/bundle?agent_id=...` itself, fetches it again
+before a decision once it is more than 5 seconds old (sending `If-None-Match`, so
+an unchanged bundle costs a 304), and decides in-process against it. So a rule
+change, or the agent being put in Agent Jail, reaches the next call. A failed or
+timed-out fetch (2.5 s) keeps the rules already held, so a jail stays in force
+through a control-plane outage. With no rules yet (first fetch failed, or no API
+key configured) calls are permitted with a loud `[VisIQ] FAIL-OPEN (no-bundle)`
+stderr line; `VISIQ_FAIL_MODE=closed` (or `fail_mode: "closed"`) denies them
+instead. Refresh is lazy, on the calling thread, one fetch at a time; there is
+no background thread.
+
+| Option | Environment variable | Default |
+|---|---|---|
+| `endpoint:` | `VISIQ_ENDPOINT`, then `VISIQ_BASE_URL` | `https://api.visiqlabs.com` when an API key is set |
+| `api_key:` | `VISIQ_API_KEY`, then `VISIQ_ALLOW_API_KEY` | none |
+| `agent_id:` | `VISIQ_AGENT_ID` | `agent` |
+| `fail_mode:` | `VISIQ_FAIL_MODE` | `open` |
+
+`governor.decide(event)` decides any event; `governor.bundle` returns the
+(frozen) bundle in use.
+
+## Usage: if you fetch the bundle yourself
+
+The module functions decide against a bundle you pass in and make no network
+calls. Fetch the bundle again at least every few seconds: a kill switch such as
+Agent Jail reaches the agent only through a fresh bundle.
 
 ```ruby
 require "visiq"

data/lib/visiq/governor.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Visiq
+  # The self-refreshing VisIQ client for Ruby: it fetches the agent's rule bundle
+  # from the control plane itself, keeps it fresh, and decides every call through
+  # the same compiled core as Visiq.gate_action.
+  #
+  # Why it exists. The module functions (Visiq.gate_action and friends) decide
+  # against whatever bundle the caller passes in. When an operator puts an agent
+  # in Agent Jail, GET /rules/bundle starts serving a terminal bundle
+  # ("shutdown": true) and the core denies every facet for it, but a program that
+  # fetched once at startup never sees that bundle, so the jailed agent keeps
+  # acting. A Governor re-fetches on its own, so the jail reaches the next call.
+  #
+  # The contract (mirrors the Python Governor and the TypeScript UnifiedRuntime):
+  #
+  # - Config: explicit keyword options first, then the environment. Endpoint from
+  #   VISIQ_ENDPOINT or VISIQ_BASE_URL (trailing slash stripped); with an API key
+  #   and no endpoint, the SaaS default DEFAULT_SAAS_ENDPOINT. API key from
+  #   VISIQ_API_KEY then VISIQ_ALLOW_API_KEY. Agent id from VISIQ_AGENT_ID, else
+  #   "agent". Fail mode from VISIQ_FAIL_MODE, else "open".
+  # - Request: GET {endpoint}/rules/bundle?agent_id=... with Authorization: Bearer,
+  #   X-VisIQ-SDK: <version> (bare), X-VisIQ-Dialect: 1, and If-None-Match once an
+  #   ETag is held. A 304 keeps the held bundle. Timeout 2.5 s (connect, and each
+  #   read).
+  # - Refresh: lazy, on the calling thread, before a decision, once the last fetch
+  #   attempt is older than the refresh interval (5 s). Single flight: one caller
+  #   fetches; while a bundle is held the others decide on it without waiting, and
+  #   with no bundle yet they wait for that one fetch and do not start their own.
+  #   No background thread: a lazy refresh is safe here (the held bundle is one
+  #   frozen snapshot swapped by a single assignment), and a thread would keep
+  #   fetching for an agent that is idle and outlive forks the host app makes.
+  # - Failure: a failed, timed-out or malformed fetch keeps the last good bundle
+  #   whatever its age. A held shutdown:true bundle never expires, so a jail stays
+  #   in force through a control-plane outage and is lifted only by a successful
+  #   fetch of a non-shutdown bundle.
+  # - No bundle (never fetched one, or not configured): fail OPEN by default with
+  #   one loud "[VisIQ] FAIL-OPEN (no-bundle): ..." stderr line and a non-enforced
+  #   permit; under fail mode "closed", an enforced deny. A policy deny from a
+  #   loaded bundle (the jail is one) always applies (G001).
+  # - Not configured (no endpoint and key): never touches the network; every
+  #   decision takes the no-bundle path above.
+  #
+  #   governor = Visiq::Governor.new(agent_id: "support-bot")
+  #   decision = governor.gate_action(tool_name: "wire_transfer", args: { "amount" => 999 })
+  #   block_the_call unless decision["allowed"]
+  class Governor
+    # The managed SaaS control plane, used only when an API key is set and no endpoint is.
+    DEFAULT_SAAS_ENDPOINT = "https://api.visiqlabs.com"
+    # Seconds the held bundle may age before the next decision re-fetches it.
+    DEFAULT_REFRESH_INTERVAL = 5.0
+    # Seconds allowed to connect, and for each read, of the bundle request.
+    DEFAULT_TIMEOUT = 2.5
+    # The wire-contract capability integer sent as X-VisIQ-Dialect (the same value
+    # as the Python and TypeScript SDK_DIALECT).
+    SDK_DIALECT = 1
+    SDK_VERSION_HEADER = "X-VisIQ-SDK"
+    SDK_DIALECT_HEADER = "X-VisIQ-Dialect"
+    # The X-VisIQ-SDK value this SDK sends: the bare package version, as the
+    # Python and TypeScript SDKs send it. The backend reads the header against
+    # /^[A-Za-z0-9._+-]+$/ and treats anything else (a "ruby/" prefix included)
+    # as absent.
+    SDK_HEADER_VALUE = Visiq::VERSION
+
+    attr_reader :endpoint, :agent_id, :fail_mode, :refresh_interval, :timeout
+
+    # Every option left nil falls back to the environment. `env:` defaults to ENV
+    # and exists so a caller (or a test) can resolve from another source.
+    def initialize(endpoint: nil, api_key: nil, agent_id: nil, fail_mode: nil,
+                   refresh_interval: nil, timeout: nil, env: ENV)
+      ep = first_present(endpoint, env["VISIQ_ENDPOINT"], env["VISIQ_BASE_URL"])
+      key = first_present(api_key, env["VISIQ_API_KEY"], env["VISIQ_ALLOW_API_KEY"])
+      if ep
+        ep = ep.sub(%r{/+\z}, "")
+      elsif key
+        ep = DEFAULT_SAAS_ENDPOINT
+      end
+      @endpoint = ep
+      @api_key = key
+      @agent_id = first_present(agent_id, env["VISIQ_AGENT_ID"]) || "agent"
+      @fail_mode = Visiq.normalize_fail_mode(fail_mode) || Visiq.normalize_fail_mode(env["VISIQ_FAIL_MODE"]) || "open"
+      @refresh_interval = Float(refresh_interval || DEFAULT_REFRESH_INTERVAL)
+      @timeout = Float(timeout || DEFAULT_TIMEOUT)
+      raise ArgumentError, "refresh_interval must be positive" unless @refresh_interval.positive?
+      raise ArgumentError, "timeout must be positive" unless @timeout.positive?
+
+      @fetch_mutex = Mutex.new
+      @held = nil          # [frozen bundle Hash, etag String or nil], replaced whole
+      @last_attempt = nil  # monotonic seconds of the last fetch attempt
+    end
+
+    # True when an endpoint and an API key are both present, so it can fetch.
+    def configured?
+      !@endpoint.nil? && !@api_key.nil?
+    end
+
+    # The (deep-frozen) bundle decisions are made against, or nil before the first
+    # successful fetch. Safe to pass on to Visiq.gate_action.
+    def bundle
+      held = @held
+      held && held[0]
+    end
+
+    # Decide one tool/action call for this governor's agent. Same decision shape
+    # as Visiq.gate_action: check ["allowed"]; on "mask" apply
+    # ["action"]["argRedactionRules"] to the args before running the tool.
+    def gate_action(tool_name:, args: nil, target_resource: nil, normalized: nil)
+      event = Visiq.action_event(tool_name: tool_name, args: args, agent_id: @agent_id,
+                                 target_resource: target_resource, normalized: normalized)
+      decide_event(event, "tool #{tool_name.inspect}")
+    end
+
+    # Decide one retrieval for this governor's agent. Same decision shape as
+    # Visiq.gate_retrieval: inspect ["retrieval"]["action"].
+    def gate_retrieval(resource_metadata: nil, resource_type: "document", query: nil)
+      event = Visiq.retrieval_event(resource_metadata: resource_metadata, resource_type: resource_type,
+                                    agent_id: @agent_id, query: query)
+      decide_event(event, "retrieval")
+    end
+
+    # Decide any governed event Hash against the held bundle (an "agentId" is
+    # added when the event carries none). Same shape as Visiq.decide.
+    def decide(event)
+      ev = event
+      ev = event.merge("agentId" => @agent_id) if event.is_a?(Hash) && event["agentId"].nil?
+      decide_event(ev, "event")
+    end
+
+    private
+
+    def decide_event(event, subject)
+      ensure_fresh
+      held = @held # ONE consistent snapshot for this decision
+      return no_bundle_decision(event, subject) if held.nil?
+
+      Visiq.decide_with_fail_mode(event, held[0], @fail_mode)
+    end
+
+    def now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    def recently_attempted?
+      last = @last_attempt
+      !last.nil? && now - last < @refresh_interval
+    end
+
+    # Lazy, single-flight refresh on the calling thread.
+    def ensure_fresh
+      return if !configured? || recently_attempted?
+
+      if @held
+        # A bundle is held: if another caller is already fetching, decide on the
+        # held bundle now rather than queue behind (or repeat) its fetch.
+        return unless @fetch_mutex.try_lock
+      else
+        # No bundle yet: wait for the in-flight fetch instead of starting one.
+        @fetch_mutex.lock
+      end
+      begin
+        return if recently_attempted? # a caller ahead of us just fetched
+
+        begin
+          fetch_once
+        ensure
+          # Success or failure, the interval restarts here, so an outage costs one
+          # timed-out fetch per interval, not one per call.
+          @last_attempt = now
+        end
+      ensure
+        @fetch_mutex.unlock
+      end
+    end
+
+    # One GET /rules/bundle. Any failure keeps the held bundle.
+    def fetch_once
+      current = @held
+      query = URI.encode_www_form_component(@agent_id).gsub("+", "%20")
+      uri = URI("#{@endpoint}/rules/bundle?agent_id=#{query}")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+      http.ssl_timeout = @timeout if http.use_ssl?
+      req = Net::HTTP::Get.new(uri)
+      req["Accept"] = "application/json"
+      req["Authorization"] = "Bearer #{@api_key}"
+      req[SDK_VERSION_HEADER] = SDK_HEADER_VALUE
+      req[SDK_DIALECT_HEADER] = SDK_DIALECT.to_s
+      req["If-None-Match"] = current[1] if current && current[1]
+
+      res = http.start { |h| h.request(req) }
+      code = res.code.to_i
+      return if code == 304 && current # unchanged: keep the held bundle
+      return fetch_failed("HTTP #{code}") unless code >= 200 && code < 300
+
+      body = JSON.parse(res.body.to_s)
+      return fetch_failed("the bundle response was not a JSON object") unless body.is_a?(Hash)
+
+      @held = [deep_freeze(body), res["ETag"]].freeze
+    rescue StandardError => e
+      fetch_failed("#{e.class}: #{e.message}")
+    end
+
+    def fetch_failed(detail)
+      if @held.nil?
+        warn "[VisIQ] bundle fetch failed (ungoverned until loaded): #{detail}"
+      else
+        warn "[VisIQ] bundle refresh failed (keeping the last good rules): #{detail}"
+      end
+      nil
+    end
+
+    def no_bundle_decision(event, subject)
+      ops = event.is_a?(Hash) ? Array(event["operations"]) : []
+      has_action = ops.include?("action") || ops.include?("delegation")
+      has_retrieval = ops.include?("retrieval")
+      closed = @fail_mode == "closed"
+      unless closed
+        warn "[VisIQ] FAIL-OPEN (no-bundle): governance unavailable for #{subject}; " \
+             "proceeding UNGOVERNED. Set VISIQ_FAIL_MODE=closed to block instead."
+      end
+      {
+        "decision" => closed ? "deny" : "permit",
+        "allowed" => !closed,
+        "reason" => if closed
+                      "no rules bundle loaded (fail-closed, VISIQ_FAIL_MODE=closed)"
+                    else
+                      "fail-open: no rules bundle loaded; proceeding UNGOVERNED " \
+                        "(set VISIQ_FAIL_MODE=closed to block instead)"
+                    end,
+        "ruleId" => nil,
+        "ruleCode" => nil,
+        "enforced" => closed,
+        "action" => if has_action
+                      { "decision" => closed ? "deny" : "permit", "allowed" => !closed }
+                    else
+                      { "decision" => nil, "allowed" => true }
+                    end,
+        "retrieval" => { "action" => has_retrieval ? (closed ? "deny" : "allow") : nil }
+      }
+    end
+
+    def first_present(*values)
+      values.find { |v| !v.nil? && !v.to_s.empty? }&.to_s
+    end
+
+    def deep_freeze(obj)
+      case obj
+      when Hash then obj.each_value { |v| deep_freeze(v) }
+      when Array then obj.each { |v| deep_freeze(v) }
+      end
+      obj.freeze
+    end
+  end
+end

data/lib/visiq.rb

@@ -43,7 +43,12 @@ module Visiq
   # Semantic-Kernel adapter defect (see its Cargo.toml). That hold gates the PyPI
   # wheel, which ships the core's own version; Ruby and Java version independently
   # and are not implicated. Bumping here does not resume the Python release.
-  VERSION = "0.1.2"
+  #
+  # 0.1.3 -> 0.1.4 adds Visiq::Governor (lib/visiq/governor.rb), the
+  # self-refreshing client that fetches GET /rules/bundle itself, so an agent put
+  # in Agent Jail is denied on its next call. Additive: every module function
+  # below keeps its signature and behaviour.
+  VERSION = "0.1.4"
 
   # Low-level binding to the compiled core over the C-ABI seam.
   module Core
@@ -115,8 +120,13 @@ module Visiq
   # VisIQ packaging/outage bug never disrupts the agent; "closed": raise as
   # before. Policy outcomes from a successful evaluation are unaffected.
   def fail_mode
-    raw = ENV["VISIQ_FAIL_MODE"].to_s.strip.downcase
-    %w[open closed].include?(raw) ? raw : "open"
+    normalize_fail_mode(ENV["VISIQ_FAIL_MODE"]) || "open"
+  end
+
+  # "open" / "closed" (case-insensitive, trimmed), or nil for anything else.
+  def normalize_fail_mode(raw)
+    v = raw.to_s.strip.downcase
+    %w[open closed].include?(v) ? v : nil
   end
 
   # A non-enforced permit decision naming the failure cause — the fail-open
@@ -141,10 +151,17 @@ module Visiq
   # Evaluate one governed agent event against a rules bundle. Returns the
   # UnifiedDecision hash: {"decision","allowed","action","retrieval"}.
   def decide(event, bundle)
+    decide_with_fail_mode(event, bundle, fail_mode)
+  end
+
+  # #decide with the fail mode supplied by the caller rather than read from
+  # VISIQ_FAIL_MODE. Visiq::Governor uses it so an explicit fail_mode option
+  # governs core failures too.
+  def decide_with_fail_mode(event, bundle, mode)
     JSON.parse(Core.evaluate_json(JSON.generate(event), JSON.generate(bundle)))
   rescue StandardError, Fiddle::DLError => e
     # Core load / FFI / parse failure — a HARNESS error, never a policy one.
-    raise if fail_mode == "closed"
+    raise if mode == "closed"
 
     fail_open_decision(event["operations"] || [], e.message)
   end
@@ -152,19 +169,33 @@ module Visiq
   # Gate a tool/action call. Check ["allowed"]; on "mask" apply
   # ["action"]["argRedactionRules"] to the args before running the tool.
   def gate_action(bundle, tool_name:, args: nil, agent_id: "agent", target_resource: nil, normalized: nil)
+    decide(action_event(tool_name: tool_name, args: args, agent_id: agent_id,
+                        target_resource: target_resource, normalized: normalized), bundle)
+  end
+
+  # The event #gate_action decides; shared with Visiq::Governor.
+  def action_event(tool_name:, args: nil, agent_id: "agent", target_resource: nil, normalized: nil)
     event = { "operations" => ["action"], "agentId" => agent_id, "toolName" => tool_name }
     event["toolArgs"] = args unless args.nil?
     event["targetResource"] = target_resource unless target_resource.nil?
     event["normalized"] = normalized unless normalized.nil?
-    decide(event, bundle)
+    event
   end
 
   # Gate a retrieval. Inspect ["retrieval"]["action"] — drop on deny/escalate,
   # redact via ["retrieval"]["redactionRules"] — before content reaches the model.
   def gate_retrieval(bundle, resource_metadata: nil, resource_type: "document", agent_id: "agent", query: nil)
+    decide(retrieval_event(resource_metadata: resource_metadata, resource_type: resource_type,
+                           agent_id: agent_id, query: query), bundle)
+  end
+
+  # The event #gate_retrieval decides; shared with Visiq::Governor.
+  def retrieval_event(resource_metadata: nil, resource_type: "document", agent_id: "agent", query: nil)
     event = { "operations" => ["retrieval"], "agentId" => agent_id, "resourceType" => resource_type }
     event["resourceMetadata"] = resource_metadata unless resource_metadata.nil?
     event["query"] = query unless query.nil?
-    decide(event, bundle)
+    event
   end
 end
+
+require_relative "visiq/governor"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visiq
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: x86_64-linux
 authors:
 - VisIQ Labs Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-11 00:00:00.000000000 Z
+date: 2026-11-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fiddle
@@ -39,6 +39,7 @@ files:
 - LICENSE
 - README.md
 - lib/visiq.rb
+- lib/visiq/governor.rb
 - vendor/libvisiq_core.so
 homepage: https://docs.visiqlabs.com
 licenses: