pinecall 0.0.1

data/lib/pinecall/client/endpoints.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # Gateway URLs built from the configured base URL.
+    module Endpoints
+      module_function
+
+      # `WS /v1/apps`; an http(s) base is converted to ws(s).
+      def apps(base) = door(base, "/v1/apps", websocket: true)
+
+      # `GET /v1/calls/{id}/events`: a call's log, as JSON or SSE.
+      def call_log(base, call) = door(base, "/v1/calls/#{CGI.escape(call)}/events")
+
+      # `GET /v1/agents/{slug}/calls`: the agent's log (registrations, configs, errors).
+      def agent_log(base, agent) = door(base, "/v1/agents/#{CGI.escape(agent)}/calls")
+
+      # `POST /v1/calls/{id}/lookup`: a platform tool run for one call this app serves.
+      def lookup(base, call) = door(base, "/v1/calls/#{CGI.escape(call)}/lookup")
+
+      def door(base, path, websocket: false)
+        url = URI.parse(base)
+        secure = %w[https wss].include?(url.scheme)
+        url.scheme = websocket ? (secure ? "wss" : "ws") : (secure ? "https" : "http")
+        url.path = "#{url.path.chomp("/")}#{path}"
+        url.to_s
+      end
+    end
+  end
+end

data/lib/pinecall/client/listeners.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # Event listener registry, used per agent and per call. A raising listener is reported to
+    # `on_error` and the remaining listeners still run.
+    class Listeners
+      def initialize(&on_error)
+        @by_type = Hash.new { |kept, type| kept[type] = [] }
+        @any = []
+        @on_error = on_error
+        @lock = Mutex.new
+      end
+
+      # Listen for one event type; the returned lambda unsubscribes.
+      def on(type, &listener)
+        @lock.synchronize { @by_type[type.to_s] << listener }
+        -> { @lock.synchronize { @by_type[type.to_s].delete(listener) } }
+      end
+
+      def on_any(&listener)
+        @lock.synchronize { @any << listener }
+        -> { @lock.synchronize { @any.delete(listener) } }
+      end
+
+      # Notify type listeners, then catch-all listeners.
+      def emit(event, context)
+        for_type, for_any = @lock.synchronize { [@by_type[event.type].dup, @any.dup] }
+        for_type.each { |listener| run { listener.call(event.data, context) } }
+        for_any.each { |listener| run { listener.call(event, context) } }
+      end
+
+      private
+
+      def run
+        yield
+      rescue StandardError => e
+        @on_error.call(e)
+      end
+    end
+  end
+end

data/lib/pinecall/client/observe.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # Reads a log as a JSON page or an SSE stream, reduced by the wire's reducer.
+    #
+    # Reconnects resume with `Last-Event-ID`. A reader that fell behind gets `log.gap` (with a
+    # snapshot when available), then `log.caught_up` once the stream is live.
+    module Observe
+      # One page of entries after the cursor, their reduced state, and the next cursor.
+      Page = Data.define(:entries, :state, :live, :next)
+
+      # One entry, its decoded event, and the reduced state including it.
+      Observation = Data.define(:entry, :event, :state)
+
+      RETRY_S = 1.0
+      LONGEST_RETRY_S = 30.0
+
+      module_function
+
+      # Fetch one page after `after`. Use the page's `next`, not the last entry's seq: an empty
+      # page of a live log still has one.
+      def history(target, url:, api_key:, after: 0)
+        answer = get(target, url:, api_key:, after:, accept: "application/json")
+        page = JSON.parse(answer.body, symbolize_names: true)
+        raise Error, "the log page is not { entries, live, next }" unless page.is_a?(Hash) && page[:entries].is_a?(Array)
+
+        entries = page[:entries].map { |raw| Wire.decode_entry(raw) }
+        Page.new(entries:, state: Wire.reduce(entries), live: page[:live] == true,
+                 next: page[:next].is_a?(Integer) ? page[:next] : nil)
+      end
+
+      # Stream entries after `after`, reconnecting as needed. Yields an Observation per entry;
+      # returns when the block breaks or `stop` returns true.
+      def observe(target, url:, api_key:, after: 0, stop: nil)
+        state = Wire.initial_state
+        attempt = 0
+        opened = false
+        until stop&.call
+          begin
+            stream(target, url:, api_key:, after:) do |entry|
+              attempt = 0
+              opened = true
+              after = entry.seq
+              state = Wire.apply(state, entry)
+              yield Observation.new(entry:, event: Wire.event_of(entry), state:)
+            end
+          rescue StandardError
+            # Failing before the first entry means misconfiguration: raise. Later drops resume.
+            raise unless opened
+          end
+          attempt += 1
+          sleep([LONGEST_RETRY_S, RETRY_S * (2**(attempt - 1))].min * rand)
+        end
+      end
+
+      def stream(target, url:, api_key:, after:)
+        get(target, url:, api_key:, after:, accept: "text/event-stream") do |answer|
+          buffered = +""
+          answer.read_body do |chunk|
+            buffered << chunk
+            while (cut = buffered.index("\n\n"))
+              block = buffered.slice!(0, cut + 2)
+              entry = entry_in(block)
+              yield entry unless entry.nil?
+            end
+          end
+        end
+      end
+
+      # Parse one SSE block; nil for comments and keep-alives.
+      def entry_in(block)
+        data = block.lines.filter_map { |line| line.delete_prefix("data:").lstrip.chomp if line.start_with?("data:") }
+        return nil if data.empty?
+
+        Wire.decode_entry(JSON.parse(data.join("\n"), symbolize_names: true))
+      end
+
+      def get(target, url:, api_key:, after:, accept:, &block)
+        where = URI.parse(door(target, url))
+        where.query = URI.encode_www_form(after:) if after.positive?
+        request = Net::HTTP::Get.new(where)
+        request["accept"] = accept
+        request["authorization"] = "Bearer #{api_key}"
+        request["last-event-id"] = after.to_s if after.positive?
+        answer(where, request, &block)
+      end
+
+      def answer(where, request)
+        http = Net::HTTP.new(where.host, where.port)
+        http.use_ssl = where.scheme == "https"
+        http.read_timeout = nil
+        http.start do |open|
+          open.request(request) do |response|
+            raise Error, "#{where.path}: the gateway answered #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+            return block_given? ? yield(response) : response.tap(&:body)
+          end
+        end
+      end
+
+      def door(target, url)
+        return Endpoints.call_log(url, target[:call]) if target[:call]
+
+        Endpoints.agent_log(url, target.fetch(:agent))
+      end
+    end
+  end
+end

data/lib/pinecall/client/rest.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pinecall
+  class Client
+    # Authenticated JSON requests to the gateway's REST endpoints. Non-2xx responses raise
+    # `Refused` with the gateway's message, never a bare status.
+    module Rest
+      # The header naming the world a request or a socket acts in.
+      ENV_HEADER = "pinecall-env"
+
+      module_function
+
+      def get(url, api_key:, env: nil) = ask(Net::HTTP::Get.new(URI.parse(url)), api_key:, env:)
+
+      def put(url, body, api_key:, env: nil)
+        request = Net::HTTP::Put.new(URI.parse(url))
+        request["content-type"] = "application/json"
+        request.body = JSON.generate(body)
+        ask(request, api_key:, env:)
+      end
+
+      def post(url, body, api_key:, env: nil)
+        request = Net::HTTP::Post.new(URI.parse(url))
+        request["content-type"] = "application/json"
+        request.body = JSON.generate(body)
+        ask(request, api_key:, env:)
+      end
+
+      def delete(url, api_key:, env: nil) = ask(Net::HTTP::Delete.new(URI.parse(url)), api_key:, env:)
+
+      # Returns the body with symbol keys (nil if empty); raises `Refused` on failure. `env` names
+      # the world the request acts in (`pinecall-env`); a server's token needs none.
+      def ask(request, api_key:, env: nil)
+        request["authorization"] = "Bearer #{api_key}"
+        request[ENV_HEADER] = env unless env.nil?
+        request["accept"] = "application/json"
+        where = request.uri
+        http = Net::HTTP.new(where.host, where.port)
+        http.use_ssl = where.scheme == "https"
+        answer = http.request(request)
+        body = parsed(answer.body)
+        return body if answer.is_a?(Net::HTTPSuccess)
+
+        raise Refused.new({ code: answer.code, message: sentence(body, answer) })
+      end
+
+      def parsed(text)
+        return nil if text.nil? || text.strip.empty?
+
+        JSON.parse(text, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Gateway refusals use `detail`; otherwise pass the body through.
+      def sentence(body, answer)
+        (body.is_a?(Hash) && (body[:detail] || body[:message])) || answer.body.to_s.strip
+      end
+    end
+  end
+end

data/lib/pinecall/client.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "net/http"
+require "openssl"
+require "socket"
+require "uri"
+require "websocket/driver"
+
+require_relative "client/endpoints"
+require_relative "client/listeners"
+require_relative "client/connection"
+require_relative "client/call"
+require_relative "client/agent"
+require_relative "client/observe"
+require_relative "client/rest"
+
+module Pinecall
+  # A connection to the Pinecall gateway: one socket, its agents, log reads, and a search for a call
+  # it serves. `Pinecall::Agent` is built on top of it.
+  #
+  #     pc = Pinecall::Client.new(url: "https://cloud.pinecall.io", api_key: ENV.fetch("PINECALL_KEY"))
+  #     agent = pc.agent("clinica-norte", tools: [])
+  #     agent.on("turn.user") { |data, call| call.say("Le he oído: #{data[:text]}") }
+  #     pc.connect
+  #
+  # It reads nothing from the environment: the app hands it the gateway and the key it keeps, and
+  # `env: "production"` names production for a person's key (a server's token needs none).
+  class Client
+    # The `sdk` field sent on register.
+    def sdk = "pinecall-ruby/#{VERSION}"
+
+    # A stop from the org: the socket is closed for good and the app decides what comes next.
+    STOPPED = "stopped"
+
+    # Seconds the running tools are given to answer once a drain was asked.
+    TOOLS_FINISH_WITHIN_S = 30
+
+    # Where a drain sent the calls, and what became of the tools running then.
+    Drained = Data.define(:handed, :parked, :tools, :finished)
+
+    attr_reader :url, :api_key, :env
+
+    def initialize(url:, api_key:, env: nil, ping_every: Connection::PINGS_EVERY_S, backoff: {})
+      raise ArgumentError, "Pinecall::Client.new(url:, api_key:): one of the two was not given" if url.nil? || api_key.nil?
+
+      @url = url
+      @api_key = api_key
+      @env = env
+      @agents = {}
+      @errors = []
+      @entries = []
+      @stops = []
+      @connects = []
+      @listeners = Listeners.new { |error| on_error(error) }
+      @connection = Connection.new(
+        url:, api_key:, env:, ping_every:, backoff:,
+        handlers: Connection::Handlers.new(
+          on_open: -> { opened },
+          on_entry: ->(entry) { took(entry) },
+          on_error: ->(error) { on_error(error) },
+          on_heartbeat: -> { @agents.each_value { |agent| guarded { agent.ping } } }
+        )
+      )
+    end
+
+    # Declare an agent. Nothing is sent until `connect`.
+    def agent(slug, **options)
+      @agents[slug] = Agent.new(slug, options, self)
+    end
+
+    # Declared agents by slug.
+    def agents = @agents.dup
+
+    # Open the socket and register every agent.
+    def connect
+      @connection.start
+      self
+    end
+
+    # Close the socket without reconnecting; agents are unregistered.
+    def close = @connection.close
+
+    # Leave without cutting calls: each agent drains (its live calls go to another holder, or wait
+    # for the next one) and the tools running get up to `tools_s` to answer. Close afterwards.
+    def drain(answer_s: Agent::ANSWERS_WITHIN_S, tools_s: TOOLS_FINISH_WITHIN_S)
+      @connection.leaving!
+      return Drained.new(handed: 0, parked: 0, tools: 0, finished: 0) unless connected?
+
+      answers = @agents.values.filter_map { |agent| guarded { drained(agent, answer_s) } }
+      running = @agents.values.sum(&:in_flight)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + tools_s
+      @agents.each_value { |agent| agent.settled(within_s: [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max) }
+      Drained.new(handed: answers.sum { |one| one[:handed] }, parked: answers.sum { |one| one[:parked] },
+                  tools: running, finished: running - @agents.values.sum(&:in_flight))
+    end
+
+    # Every entry the socket receives, as the gateway wrote it, before any agent takes it — other
+    # agents' entries and the client's own errors included. Returns a lambda that unsubscribes.
+    def on_entries(&listener)
+      @entries << listener
+      -> { @entries.delete(listener) }
+    end
+
+    # Called each time the socket is up and every agent on it registered: the first connect and every
+    # reconnect after a drop. Returns a lambda that unsubscribes.
+    def on_connected(&listener)
+      @connects << listener
+      -> { @connects.delete(listener) }
+    end
+
+    # Called when a member of the org stops this app: the socket is closed for good. Returns a
+    # lambda that unsubscribes.
+    def on_stopped(&listener)
+      @stops << listener
+      -> { @stops.delete(listener) }
+    end
+
+    # True while the socket is up.
+    def connected? = @connection.open?
+
+    # Listen for one event type across all agents.
+    def on(type, &listener) = @listeners.on(type, &listener)
+
+    # Listen for every event across all agents.
+    def on_any(&listener) = @listeners.on_any(&listener)
+
+    # Listen for unhandled errors (bad frames, raising tools, socket loss). Without a listener
+    # they go to stderr. Returns a lambda that unsubscribes.
+    def on_errors(&listener)
+      @errors << listener
+      -> { @errors.delete(listener) }
+    end
+
+    # Stream a log, reduced by the wire's reducer. `target` is `{ call: "CA_1" }` or `{ agent: … }`.
+    def observe(target, **options, &block) = Observe.observe(target, url: @url, api_key: @api_key, **options, &block)
+
+    # Fetch one page of a log and its reduced state.
+    def history(target, **options) = Observe.history(target, url: @url, api_key: @api_key, **options)
+
+    # Search the agent's knowledge bases on behalf of a call this client serves; the gateway runs
+    # the search and logs it. Returns the chunks as the gateway answered them.
+    def search(call, query, k: nil)
+      input = k.nil? ? { query: } : { query:, k: }
+      answer = Rest.post(Endpoints.lookup(@url, call), { tool: "search", input: }, api_key: @api_key, env: @env)
+      answer.dig(:output, :chunks) || []
+    end
+
+    # ── used by agents ───────────────────────────────────────────────────────
+
+    # Send one command, validated against its schema.
+    def send_command(type:, agent:, call:, data:, id: nil)
+      @connection.send_frame(Wire.command(type:, agent:, call:, data:, id:))
+    end
+
+    # Forward an event to client-wide listeners.
+    def seen(event, call) = @listeners.emit(event, call)
+
+    def on_error(error)
+      return warn("pinecall: #{error.class}: #{error.message}") if @errors.empty?
+
+      @errors.each { |listener| listener.call(error) }
+    end
+
+    private
+
+    def took(entry)
+      @entries.each { |listener| guarded { listener.call(entry) } }
+      return stopped(entry.data[:message]) if stop?(entry)
+
+      agent = @agents[entry.agent]
+      # The socket may carry entries for agents this client did not declare.
+      return if agent.nil?
+
+      guarded { agent.take(entry) }
+    end
+
+    # An `error` coded `stopped` for no agent: a member of the org pressed Stop.
+    def stop?(entry) = entry.type == "error" && entry.agent.to_s.empty? && entry.data[:code] == STOPPED
+
+    # With no stop listener the stop is reported as an error, so it is never silent.
+    # Every agent registered again, then whoever asked to know.
+    def opened
+      @agents.each_value(&:open)
+      @connects.each { |listener| guarded { listener.call } }
+    end
+
+    def stopped(why)
+      @connection.close
+      return on_error(NotConnected.new(why)) if @stops.empty?
+
+      @stops.each { |listener| guarded { listener.call(why) } }
+    end
+
+    # The socket can close between `connected?` and the ask: then nothing was left to hand over. A
+    # gateway still connected that never answered is still said.
+    def drained(agent, answer_s)
+      agent.drain(answer_s:)
+    rescue NotConnected
+      raise if connected?
+
+      nil
+    end
+
+    def guarded
+      yield
+    rescue StandardError => e
+      on_error(e)
+      nil
+    end
+  end
+end

data/lib/pinecall/errors.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pinecall
+  # Base class for every error raised by this library. Messages say what went wrong and how to
+  # fix it.
+  class Error < StandardError
+  end
+
+  # The gateway refused a command with an `error` entry.
+  class Refused < Error
+    # @return [Hash{Symbol=>Object}] the wire refusal: code, message and id
+    attr_reader :refusal
+
+    def initialize(refusal)
+      @refusal = refusal
+      super("#{refusal[:code]}: #{refusal[:message]}")
+    end
+
+    # Machine-readable refusal code.
+    def code = @refusal[:code]
+  end
+
+  # A state field was assigned outside a tool or hook.
+  class UnauthoredWrite < Error
+    def initialize(field)
+      super("state field #{field} was assigned outside a tool and outside a lifecycle hook; " \
+            "tools are the only writers of state")
+    end
+  end
+
+  # A declaration the gateway would refuse, raised at load.
+  class DeclarationRefused < Error
+  end
+
+  # A console's ask refused with a status: raised by an `on_dev` handler, answered as `refused`.
+  class DevRefused < Error
+    attr_reader :status, :detail
+
+    def initialize(status, detail)
+      @status = status
+      @detail = detail
+      super("#{status}: #{detail}")
+    end
+  end
+
+  # A tool failed; the message is returned to the model as the tool result.
+  class ToolFailed < Error
+  end
+
+  # The socket is not connected.
+  class NotConnected < Error
+  end
+end

data/lib/pinecall/panel.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Pinecall
+  # The console panel an agent draws beside a conversation: the TypeScript package's `@view` and
+  # its `@pinecall/agents/panels` tags. The nodes are the same JSON, drawn by the console's own
+  # components, so a tenant's panel cannot inject styles or scripts.
+  #
+  #     panel "Ficha" do |who|
+  #       patient = Crm.find(who.contact)
+  #       panel patient.name do
+  #         rows do
+  #           row "Alta", patient.since
+  #           row "Zona", patient.area
+  #         end
+  #         badge "con saldo", tone: :warn if patient.owes?
+  #       end
+  #     end
+  #
+  # A panel identifies a thread, not live call state: it is drawn for ended calls too, so it fetches
+  # its data from the tenant's own systems.
+  module Panel
+    # The conversation a panel is drawn for: the agent, the other party, the thread's newest call.
+    Who = Data.define(:agent, :contact, :call)
+
+    # A class's declared panel: its title and the block that draws it.
+    Declared = Data.define(:name, :draw)
+
+    TONES = %w[neutral good warn bad].freeze
+
+    # A value as the console shows it: nil and booleans are "", a whole float is written whole.
+    def self.said(value)
+      case value
+      when nil, true, false then ""
+      when Float then value.finite? && (value % 1).zero? ? value.to_i.to_s : value.to_s
+      else value.to_s
+      end
+    end
+
+    # Draw a class's panel for one conversation: `{ name:, nodes: }`, what `view.render` answers.
+    def self.draw(klass, who)
+      declared = klass.declared_panel
+      drawing = Drawing.new(klass)
+      drawing.instance_exec(who, &declared.draw)
+      { name: declared.name, nodes: drawing.nodes }
+    end
+
+    module Declaring
+      # Declare the class's console panel; the block draws it for a `Who`. One per class, and a
+      # subclass does not inherit it.
+      def panel(name = "View", &draw)
+        raise DeclarationRefused, "panel takes the block that draws it" if draw.nil?
+
+        standing = @pinecall_panel
+        unless standing.nil?
+          raise DeclarationRefused,
+                "#{self.name || "this class"} declares two panels (#{standing.name} and #{name}); a class draws one panel"
+        end
+
+        @pinecall_panel = Declared.new(name: name.to_s, draw:)
+      end
+
+      # The panel this class declares itself, or nil.
+      def declared_panel = @pinecall_panel
+    end
+
+    # What a panel's block draws on: one method per node of the console's closed catalogue. Any
+    # other method the block calls is the agent class's, where a tenant keeps its own helpers.
+    class Drawing
+      attr_reader :nodes
+
+      def initialize(klass)
+        @klass = klass
+        @nodes = []
+      end
+
+      # A titled section; several stack vertically.
+      def panel(title = nil, &) = add(tag: "panel", title: title.nil? ? nil : Panel.said(title), children: inside(&))
+
+      # A list of labelled rows.
+      def rows(&) = add(tag: "rows", children: inside(&))
+
+      # A labelled line: `row "Alta", "12 Mar 2024"`.
+      def row(label, value = nil) = add(tag: "row", label: Panel.said(label), value: Panel.said(value))
+
+      # A prominent labelled number.
+      def stat(label, value) = add(tag: "stat", label: Panel.said(label), value: Panel.said(value))
+
+      # A table. Each row is an array in column order, or a hash keyed by the columns' names.
+      def table(columns:, rows:)
+        add(tag: "table", columns: columns.map { |column| Panel.said(column) }, rows: rows.map { |row| cells(row, columns) })
+      end
+
+      # A status badge with a tone: neutral, good, warn or bad; a word it does not know is neutral.
+      def badge(text, tone: :neutral)
+        add(tag: "badge", tone: TONES.include?(tone.to_s) ? tone.to_s : "neutral", text: Panel.said(text))
+      end
+
+      # A line of text; an empty one draws nothing.
+      def text(said)
+        line = Panel.said(said).strip
+        line.empty? ? nil : add(tag: "text", text: line)
+      end
+
+      def respond_to_missing?(name, include_private = false) = @klass.respond_to?(name) || super
+
+      def method_missing(name, ...)
+        return super unless @klass.respond_to?(name)
+
+        @klass.public_send(name, ...)
+      end
+
+      private
+
+      def add(node)
+        @nodes << node
+        nil
+      end
+
+      # The nodes a nested block draws, collected apart from the ones around it.
+      def inside
+        outer = @nodes
+        @nodes = []
+        yield if block_given?
+        @nodes
+      ensure
+        @nodes = outer
+      end
+
+      def cells(row, columns)
+        case row
+        when Array then row.map { |cell| Panel.said(cell) }
+        when Hash then columns.map { |column| Panel.said(row.fetch(column) { row[column.to_s] || row[column.to_s.to_sym] }) }
+        else [Panel.said(row)]
+        end
+      end
+    end
+  end
+end

data/lib/pinecall/reading.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pinecall
+  # Read-only view of a state snapshot for `when:` and views: `s.slots` and `s[:slots]` are
+  # equivalent, and an undeclared field raises instead of returning nil.
+  class Reading
+    # @param remembered [Array<String>] facts known about the caller, supplied by the runtime
+    def initialize(state, remembered = [])
+      @state = state
+      @remembered = remembered
+    end
+
+    def to_h = @state
+
+    def [](name) = @state[name.to_sym]
+
+    def key?(name) = @state.key?(name.to_sym)
+
+    def fetch(name, *rest) = @state.fetch(name.to_sym, *rest)
+
+    # Whether a remembered fact contains `text`. Views may branch on facts but never print them;
+    # facts reach the model only as tool results.
+    def remembers?(text) = @remembered.any? { |fact| fact.to_s.include?(text.to_s) }
+
+    def respond_to_missing?(name, include_private = false)
+      @state.key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      return @state[name] if args.empty? && @state.key?(name)
+
+      super
+    end
+
+    def inspect = "#<Pinecall::Reading #{@state.inspect}>"
+  end
+end