pinecall 0.0.1

data/lib/pinecall/agent.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "agent/author"
+require_relative "agent/doc"
+require_relative "agent/state"
+require_relative "agent/spec"
+require_relative "agent/tools"
+require_relative "agent/config"
+require_relative "agent/knowledge"
+require_relative "agent/searching"
+
+module Pinecall
+  # Base class for an agent: fields are state, `tool` methods are the model's tools, comments
+  # are the prompt.
+  #
+  #     class ClinicaNorte < Pinecall::Agent
+  #       language "es"
+  #
+  #       stage :identify, :book
+  #       state :patient
+  #
+  #       # Busca al paciente por nombre y teléfono.
+  #       tool stage: :identify, pii: %i[name phone]
+  #       def find_patient(name:, phone:)
+  #         self.patient = Agenda.find(name, phone)
+  #         self.stage = :book if patient
+  #         patient
+  #       end
+  #     end
+  class Agent
+    extend Config::Declaring
+    extend State::Declaring
+    extend Tools::Declaring
+    extend Prompt::Declaring
+    extend Panel::Declaring
+    include State
+    include Tools
+
+    # Agent subclasses in definition order; `pinecall prompt agent.rb` uses it to find the class.
+    def self.written = @written ||= []
+
+    def self.inherited(subclass)
+      super
+      Agent.written << subclass
+    end
+
+    def initialize
+      @state = {}
+      @changes = []
+      @change_listeners = []
+      @log = []
+      @log_listeners = []
+      @event_listeners = []
+      @seq = 0
+      @sealed = false
+      @call = nil
+      @last_call = nil
+      self.class.declared_state.each { |name, default| @state[name] = opening(default) }
+    end
+
+    # The call being served. A method, not a field, so it never reaches a view; raises outside a call.
+    def call
+      raise Error, "there is no call here: the bridge hands an agent its call when one starts" if @call.nil?
+
+      @call
+    end
+
+    # Whether this instance is serving a call.
+    def call? = !@call.nil?
+
+    # The knowledge bases attached to this agent: `knowledge.search("…")` inside a tool.
+    def knowledge = Knowledge.new(self)
+
+    # Speak `text` verbatim now, as a `turn.agent`.
+    def say(text, **options) = call.say(text, **options)
+
+    # Make the model speak now, guided by instructions the caller does not hear.
+    def reply(instructions, **options) = call.reply(instructions, **options)
+
+    # Append a named entry to the call's log.
+    def log(name, data = nil)
+      entry = LogEntry.new(seq: next_seq, name: name.to_s, data:, at: Time.now.to_f)
+      @log << entry
+      @log_listeners.each { |listener| listener.call(entry) }
+      entry
+    end
+
+    # Everything this agent has logged, oldest first.
+    def logged = @log.dup
+
+    # Subscribe to logged entries; the returned lambda unsubscribes.
+    def on_log(&listener)
+      @log_listeners << listener
+      -> { @log_listeners.delete(listener) }
+    end
+
+    # Subscribe to external events, after `on_event` has run; the returned lambda unsubscribes.
+    def on_heard(&listener)
+      @event_listeners << listener
+      -> { @event_listeners.delete(listener) }
+    end
+
+    # The contact's previous call, read from the store passed to `mount(last:)`.
+    def last(contact)
+      raise Error, "last(contact) needs a store: mount the agent with last: to give it one" if @last_call.nil?
+
+      @last_call.call(contact)
+    end
+
+    # ── hooks: override them; state written inside one is attributed to the hook ──
+
+    # A call started.
+    def on_call(call) = nil
+
+    # The call ended.
+    def on_end(call) = nil
+
+    # A declared external event arrived.
+    def on_event(name, data, meta) = nil
+
+    # Memory was written; persist the ops wherever the application keeps them.
+    def on_memory(ops, call) = nil
+
+    # ── called by the bridge ─────────────────────────────────────────────────
+
+    # Run a hook with its state writes attributed to it.
+    def run_hook(hook, *args)
+      Author.with("hook:#{hook}") { public_send(hook, *args) }
+    end
+
+    # Set the call this instance serves; called once, at start.
+    def serving(call)
+      @call = call
+      self
+    end
+
+    # Set the store `last(contact)` reads.
+    def reads_last_from(source)
+      @last_call = source
+      self
+    end
+
+    # Notify `on_heard` listeners.
+    def notify_heard(name, data, meta)
+      @event_listeners.each { |listener| listener.call(name, data, meta) }
+    end
+
+    private
+
+    # Initial value for a field: Procs are called and mutable defaults duped, so calls never share one.
+    def opening(default)
+      return default.call if default.is_a?(Proc)
+
+      case default
+      when Array, Hash, String then default.dup
+      else default
+      end
+    end
+  end
+end

data/lib/pinecall/blocks.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Pinecall
+  # One named prompt block and its region (`static` or `dynamic`).
+  Block = Data.define(:name, :region, :text)
+
+  # One rendered prompt: blocks in send order, plus the history between the two regions.
+  Blocks = Data.define(:blocks, :history) do
+    def [](name) = blocks.find { |block| block.name == name.to_s }&.text
+
+    # Blocks before the history; cached by the provider.
+    def static = blocks.select { |block| block.region == "static" }
+
+    # Blocks after the history; replaced every turn.
+    def dynamic = blocks.select { |block| block.region == "dynamic" }
+
+    # Non-empty static blocks joined into one text.
+    def instructions = static.map(&:text).reject(&:empty?).join("\n\n")
+  end
+
+  # Renders the prompt as named blocks in two regions.
+  #
+  # Static blocks precede the history and are cached; the view follows it and changes every turn.
+  # Do not reorder them: the region boundary is the cache boundary. Blocks hold only the
+  # operator's text; lookup results go in the history as tool results.
+  module Prompt
+    # Blocks every agent has, in send order.
+    FRAMEWORK = [
+      { name: "identity", region: "static" }.freeze,
+      { name: "knowledge", region: "static" }.freeze,
+      { name: "tools", region: "static" }.freeze,
+      { name: "view", region: "dynamic" }.freeze
+    ].freeze
+
+    module Declaring
+      # Declare or read the template for the `view` block.
+      #
+      #     view                          # views/<slug>.erb next to this file (the default)
+      #     view "views/reception.erb"    # relative to this file
+      #     view template: <<~ERB         # inline
+      #
+      # The default lookup runs once and is memoized.
+      def view(path = nil, template: nil)
+        unless path.nil? && template.nil?
+          @view = template ? View.inline(template, "#{name} (inline view)") : View.file(beside_this_file(path))
+          return @view
+        end
+        return @view if defined?(@view)
+
+        @view = view_of_this_class || (superclass.respond_to?(:view) ? superclass.view : nil)
+      end
+
+      def view_of_this_class
+        here = source_file
+        return nil if here.nil?
+
+        path = View.beside(here, slug)
+        File.exist?(path) ? View.file(path) : nil
+      end
+
+      # Relative paths resolve against the class's file, not the working directory.
+      def beside_this_file(path)
+        here = source_file
+        return path if here.nil? || path.start_with?("/")
+
+        File.expand_path(path, File.dirname(here))
+      end
+
+      def source_file
+        found = name && Object.const_source_location(name)
+        found&.first
+      end
+    end
+
+    module_function
+
+    def render(agent, resumed: false, remembered: [], line: nil)
+      reading = reading_for(agent, resumed:, remembered:, line:)
+      blocks = FRAMEWORK.map do |spec|
+        Block.new(name: spec[:name], region: spec[:region], text: text_of(agent, spec[:name], reading))
+      end
+      Blocks.new(blocks:, history: history(agent))
+    end
+
+    # The class docstring, the framework's rules and protocols, and the channel's. Reads no state.
+    def identity(agent)
+      [agent.doc, tagged("rules", Rules::RULES), tagged("protocols", Rules::PROTOCOLS), channel(agent)]
+        .compact.reject { |part| part.strip.empty? }.join("\n\n")
+    end
+
+    # Static because a call never changes its channel or medium. With no call (an offline prompt), a
+    # phone call's.
+    def channel(agent)
+      return nil if agent.class.channel_rules == false
+
+      call = agent.call? ? agent.call : nil
+      tagged("channel", Rules.channel_rules_for(call&.channel || "phone", call&.medium || "voice"))
+    end
+
+    # Every declared tool's docstring, visible or not; schemas travel separately on the wire.
+    def tools(agent)
+      docs = agent.tools.map { |spec| "- #{spec[:name]}: #{spec[:description]}" }.join("\n")
+      tagged("tools", docs)
+    end
+
+    # The runtime owns the turns; the framework adds only the summaries left by `collapse`.
+    def history(agent)
+      agent.changes.select { |change| change.field == "@summary" }
+           .map { |change| "#{collapsed(change.seq)}\n#{change.next}" }
+           .join("\n\n")
+    end
+
+    # Marker for a collapsed stretch of the call.
+    def collapsed(seq) = "<!-- collapsed: #{JSON.generate({ seq: })} -->"
+
+    def view(agent, reading)
+      view = agent.class.view
+      view.nil? ? "" : view.render(reading)
+    end
+
+    # The view's scope: state, call context, and remembered facts (queryable, never printed).
+    def reading_for(agent, resumed: false, remembered: [], line: nil)
+      Reading.new(agent.snapshot.merge(resumed:, call: line || { channel: "web" }), remembered)
+    end
+
+    # What `Pinecall::Serve`'s `prompt` prints: every block under its header.
+    def header_for(section, region = nil) = "── #{[section, region && "(#{region})"].compact.join(" ")} ──"
+
+    # The prompt as one page, as `pinecall prompt` prints it.
+    def show(agent, **context)
+      rendered = render(agent, **context)
+      sections = rendered.static.map { |block| [header_for(block.name, block.region), block.text] }
+      sections << [header_for("history"), rendered.history]
+      sections += rendered.dynamic.map { |block| [header_for(block.name, block.region), block.text] }
+      sections.map { |header, text| "#{header}\n#{text}".rstrip }.join("\n\n")
+    end
+
+    def text_of(agent, called, reading)
+      case called
+      when "identity" then identity(agent)
+      # Filled by the gateway from the agent's settings (`pinecall agent knowledge edit`).
+      when "knowledge" then ""
+      when "tools" then tools(agent)
+      when "view" then view(agent, reading)
+      end
+    end
+
+    def tagged(name, body)
+      body.to_s.empty? ? "" : "<#{name}>\n#{body}\n</#{name}>"
+    end
+  end
+end

data/lib/pinecall/bridge.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Pinecall
+  # Mounts an agent class on a client, with one instance per call. The only module that knows
+  # both the agent and the socket.
+  module Bridge
+    # A mounted agent and its live instances.
+    class Mounted
+      attr_reader :slug, :agent, :options
+
+      def initialize(slug:, agent:, options:, live:)
+        @slug = slug
+        @agent = agent
+        @options = options
+        @live = live
+      end
+
+      # The instance serving `call_id`, or nil.
+      def serving(call_id) = @live[call_id]&.agent
+    end
+
+    # One served call: its instance, what was last sent, and a thread running its jobs in order.
+    class Live
+      attr_reader :agent, :world, :sent, :stops
+      # What memory recalled about this caller in this call: what `remembers?` answers from.
+      attr_accessor :tools_shown, :remembered
+
+      def initialize(agent, world)
+        @agent = agent
+        @world = world
+        @sent = {}
+        @tools_shown = nil
+        @remembered = []
+        @stops = {}
+        @work = Thread::Queue.new
+        @thread = Thread.new { work }
+      end
+
+      # Queue a job; jobs run one at a time in order, which keeps `world.cause` accurate.
+      def later(&job) = @work << job
+
+      def finish
+        @work << :done
+        @thread.join(5)
+      end
+
+      private
+
+      def work
+        while (job = @work.pop)
+          break if job == :done
+
+          begin
+            job.call
+          rescue StandardError => e
+            warn("pinecall: #{e.class}: #{e.message}")
+          end
+        end
+      end
+    end
+
+    module_function
+
+    # Mount a class on a client; each call gets its own instance. Nothing is sent until `connect`.
+    #
+    # @param last [Proc] source for `last(contact)`
+    # @param takes_unclaimed [Boolean] false for a console, which serves only calls it opens
+    def mount(klass, client:, slug: nil, last: nil, takes_unclaimed: true)
+      name = slug || klass.slug
+      live = {}
+      # Throwaway instance used only to read the class's declarations.
+      probe = klass.new
+      options = klass.wire_config(tools: tools_for(probe, live)).merge(takes_unclaimed:)
+      agent = client.agent(name, **options)
+      agent.on("call.started") { |started, call| start(klass, live, call, client, last, started[:state]) }
+      agent.on("call.attached") { |_data, call| attached(klass, live, call, client, last) }
+      agent.on("call.ended") { |_data, call| finish(live, call) }
+      Mounted.new(slug: name, agent:, options:, live:)
+    end
+
+    # Tool specs with a `run` routed to the instance serving the calling call.
+    def tools_for(probe, live)
+      probe.tools.map do |spec|
+        spec.merge(run: lambda do |arguments, call|
+          serving = live[call.id]
+          raise ToolFailed, "#{spec[:name]}: this call is no longer being served" if serving.nil?
+
+          serving.agent.run_tool(spec[:name], arguments)
+        end)
+      end
+    end
+
+    # A call handed to this process mid-conversation: no `on_call`, the state the gateway kept
+    # instead. One served here already (the gateway restarted) keeps its instance, and its whole
+    # prompt is sent again, which the gateway may have lost.
+    def attached(klass, live, call, client, last)
+      held = live[call.id]
+      return held.later { resend(held, call) } unless held.nil?
+
+      instance = klass.new.seal
+      instance.reads_last_from(last) unless last.nil?
+      serving = Live.new(instance, world_for(call, client))
+      instance.serving(serving.world)
+      live[call.id] = serving
+      serving.later do
+        instance.restore(call.state)
+        sync(serving, call)
+        listen(serving, call)
+      end
+    end
+
+    def resend(serving, call)
+      serving.sent.clear
+      serving.tools_shown = nil
+      sync(serving, call)
+    end
+
+    def world_for(call, client)
+      searching = ->(query, k) { client.search(call.id, query, k:) }
+      CallWorld.new(id: call.id, contact: call.contact&.dig(:id) || call.from, from: call.from, channel: call.channel,
+                    medium: call.medium, today: call.today, claimed: call.claimed, searching:) do |type, data|
+        call.command(type, data)
+      end
+    end
+
+    # Build the instance and run `on_call` before listening, so the first prompt is sent once
+    # rather than once per field. The state the opener asked for (`call.started.state`) is applied
+    # after the hook, which would overwrite it, and before the first render.
+    def start(klass, live, call, client, last, opened_in)
+      instance = klass.new.seal
+      instance.reads_last_from(last) unless last.nil?
+      world = world_for(call, client)
+      instance.serving(world)
+      serving = Live.new(instance, world)
+      live[call.id] = serving
+      serving.later do
+        instance.run_hook(:on_call, world)
+        instance.start_in(opened_in) unless opened_in.nil?
+        call.set_state(instance.snapshot)
+        sync(serving, call)
+        listen(serving, call)
+      end
+    end
+
+    # Re-sync the prompt on every state change.
+    def listen(serving, call)
+      instance = serving.agent
+      serving.stops[:state] = instance.on_change do |change|
+        call.set_state(instance.snapshot, [change.field])
+        # `state.set` has no cause field on the wire, so log it separately.
+        cause = serving.world.cause
+        call.log("state.cause", { field: change.field.to_s, kind: "event" }.merge(cause)) unless cause.nil?
+        sync(serving, call)
+      end
+      serving.stops[:log] = instance.on_log { |entry| call.log(entry.name, as_object(entry.data)) }
+      serving.stops[:entries] = call.on_any do |event|
+        serving.world.take(event.type, event.data, Time.now.to_f)
+        received(serving, event.data) if event.type == "event.received"
+        rerendered(serving, call, event)
+      end
+    end
+
+    # The view answers the turn being taken, not the one before it; a claim lets the caller see the
+    # page; recall is not state, so nothing else would render what it brought.
+    def rerendered(serving, call, event)
+      case event.type
+      when "turn.user", "call.claimed" then sync(serving, call)
+      when "memory.ops"
+        serving.remembered = words_recalled(event.data)
+        sync(serving, call)
+      end
+    end
+
+    # Each recalled fact's text and category; a `remember` op stores this call's facts, it surfaces none.
+    def words_recalled(data)
+      (data[:ops] || []).select { |op| op[:op] == "recall" }.flat_map do |op|
+        (op[:facts] || []).flat_map { |fact| [fact[:text], fact[:category] || ""] }
+      end
+    end
+
+    # Drop events whose (name, source) the class did not declare: an `:app` event arriving from
+    # a browser could be spoofed.
+    def received(serving, fact)
+      name = fact[:name].to_s
+      allowed = agent_class(serving).declared_events[name]
+      unless allowed&.include?(fact[:source].to_s)
+        return warn("pinecall: #{name} from #{fact[:source]} is not declared by this agent")
+      end
+
+      meta = { source: fact[:source], identity: fact[:identity], seq: serving.world.numbered }.compact
+      serving.later do
+        serving.world.cause = { event: name, event_seq: meta[:seq] }
+        serving.agent.run_hook(:on_event, name, fact[:data] || {}, meta)
+        serving.agent.notify_heard(name, fact[:data] || {}, meta)
+        serving.world.cause = nil
+      end
+    end
+
+    # Stop rendering and reading entries; the log stays open until `on_end` has run.
+    def finish(live, call)
+      serving = live.delete(call.id)
+      return if serving.nil?
+
+      serving.stops.values_at(:state, :entries).compact.each(&:call)
+      serving.later do
+        serving.agent.run_hook(:on_end, serving.world)
+        serving.stops[:log]&.call
+      end
+      serving.finish
+    end
+
+    # Send only blocks whose text changed since this call's last send: identical re-sends waste
+    # the provider's prompt cache. Unsent blocks count as empty.
+    def sync(serving, call)
+      line = { channel: call.channel || "web", from: call.from, claimed: serving.world.claimed }
+      rendered = Prompt.render(serving.agent, remembered: serving.remembered, line:)
+      rendered.blocks.each do |block|
+        next if block.text == serving.sent.fetch(block.name, "")
+
+        serving.sent[block.name] = block.text
+        call.set_prompt(block.name, block.text)
+      end
+      visible = serving.agent.visible_tools
+      return if visible == serving.tools_shown
+
+      serving.tools_shown = visible
+      call.set_tools(visible)
+    end
+
+    def agent_class(serving) = serving.agent.class
+
+    # `call.log` data must be an object; wrap scalars under `value`.
+    def as_object(data)
+      return {} if data.nil?
+
+      data.is_a?(Hash) ? data : { value: data }
+    end
+  end
+end

data/lib/pinecall/call_world/answers.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# What a verb of the call waits for, and the answers it gets: a transfer, a supervisor, a search.
+
+module Pinecall
+  class CallWorld
+    # Seconds `say`/`reply` wait for their turn before returning false.
+    LANDS_WITHIN_S = 30
+    # A transfer's far end may ring for 25 s before it fails.
+    TRANSFER_WITHIN_S = 90
+    # What `attention` waits beyond `wait_s` for the answer entry to arrive.
+    A_MOMENT_S = 15
+    # No answer came back: the gateway, not the far end, went quiet.
+    NO_ANSWER = "the runtime never said how it went"
+    # A pending verb when the call ends first.
+    THE_CALL_ENDED = "the call ended before it was answered"
+    # `search` on a call no gateway serves (an offline prompt, a test).
+    NO_GATEWAY_TO_SEARCH = "this call cannot search: no gateway is serving it"
+
+    # How a transfer went. `ok: false` means the caller is still with the agent.
+    Transferred = Data.define(:to, :mode, :ok, :error)
+
+    # Who took the line, or why nobody did.
+    Attended = Data.define(:ok, :by, :error)
+
+    # One search hit: its source path, heading and text.
+    Found = Data.define(:path, :heading, :text)
+
+    # The verbs waiting for an entry, by kind: `:spoken`, `:transfers`, `:asks`. The runtime always
+    # answers with an entry; the ceiling only guards against a gateway that went away.
+    class Waiting
+      def initialize
+        @waiting = Hash.new { |kinds, kind| kinds[kind] = [] }
+        @lock = Mutex.new
+      end
+
+      # Block until the answer of this kind arrives, or return `lapsed` after `ceiling_s`.
+      def wait(kind, ceiling_s, lapsed)
+        answer = Thread::Queue.new
+        @lock.synchronize { @waiting[kind] << answer }
+        yield
+        got = answer.pop(timeout: ceiling_s)
+        got.nil? ? lapsed : got
+      ensure
+        @lock.synchronize { @waiting[kind].delete(answer) }
+      end
+
+      # Answer every verb waiting for this kind.
+      def settle(kind, answer)
+        @lock.synchronize { @waiting.delete(kind) || [] }.each { |waiting| waiting.push(answer) }
+      end
+
+      # The call ended: every verb waiting is answered now instead of at its ceiling.
+      def end_all
+        settle(:spoken, false)
+        settle(:transfers, Transferred.new(to: "", mode: nil, ok: false, error: THE_CALL_ENDED))
+        settle(:asks, Attended.new(ok: false, by: nil, error: THE_CALL_ENDED))
+      end
+    end
+  end
+end

data/lib/pinecall/call_world/room.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Who is in the call's room and what was said: the participants, a seat's two verbs, the turns.
+
+module Pinecall
+  # A room participant, as reported by the room's entries.
+  Participant = Struct.new(:identity, :kind, :name, :joined_at, :speaking, keyword_init: true)
+
+  # A finished conversation turn.
+  Turn = Data.define(:who, :text, :speech_id, :interrupted, :at)
+
+  class CallWorld
+    # A participant handle. Removing the caller ends the call.
+    class Seat
+      def initialize(identity, send)
+        @identity = identity
+        @send = send
+      end
+
+      def mute(muted: true) = @send.call("participant.mute", { identity: @identity, muted: })
+
+      def remove = @send.call("participant.remove", { identity: @identity })
+    end
+  end
+end