pinecall 0.0.1

data/sig/pinecall.rbs

@@ -0,0 +1,453 @@
+# The public surface, as types. Ruby's answer to the `.d.ts` the TypeScript package ships.
+#
+# The state a class declares is generated at load, so it cannot be typed here — that is what a
+# tenant's own `sig/` is for, one line per `state`. Everything the framework itself offers is.
+
+module Pinecall
+  VERSION: String
+
+  type state = Hash[Symbol, untyped]
+  type spec = Hash[Symbol, untyped]
+  type line = { channel: String, ?from: String?, ?claimed: String? }
+
+  class Error < StandardError
+  end
+
+  class Refused < Error
+    attr_reader refusal: Hash[Symbol, untyped]
+    def code: () -> String
+  end
+
+  class UnauthoredWrite < Error
+  end
+
+  class DeclarationRefused < Error
+  end
+
+  class DevRefused < Error
+    attr_reader status: Integer
+    attr_reader detail: String
+    def initialize: (Integer, String) -> void
+  end
+
+  class ToolFailed < Error
+  end
+
+  class NotConnected < Error
+  end
+
+  class Reading
+    def initialize: (state, ?Array[String]) -> void
+    def to_h: () -> state
+    def []: (String | Symbol) -> untyped
+    def key?: (String | Symbol) -> bool
+    def fetch: (String | Symbol, *untyped) -> untyped
+    def remembers?: (String) -> bool
+  end
+
+  type block_spec = { name: String, region: String }
+
+  class Block
+    attr_reader name: String
+    attr_reader region: String
+    attr_reader text: String
+  end
+
+  class Blocks
+    attr_reader blocks: Array[Block]
+    attr_reader history: String
+    def []: (String | Symbol) -> String?
+    def static: () -> Array[Block]
+    def dynamic: () -> Array[Block]
+    def instructions: () -> String
+  end
+
+  class View
+    def self.beside: (String, String) -> String
+    def self.file: (String) -> View
+    def self.inline: (String, ?String) -> View
+    attr_reader path: String
+    def render: (Reading) -> String
+    def tidy: (String) -> String
+  end
+
+  class Agent
+    def self.written: () -> Array[Class]
+
+    # config, declared on the class
+    def self.phone: (?String) -> untyped
+    def self.whatsapp: (?String) -> untyped
+    def self.web: (?bool) -> untyped
+    def self.channel_rules: (?bool) -> untyped
+
+    # the console's panel, drawn by `view.render`
+    def self.panel: (?String) { (Panel::Who) -> void } -> Panel::Declared
+    def self.declared_panel: () -> Panel::Declared?
+
+    # the world's, refused at load with the verb that sets each
+    def self.voice: (*untyped, **untyped) -> bot
+    def self.llm: (*untyped, **untyped) -> bot
+    def self.stt: (*untyped, **untyped) -> bot
+    def self.greeting: (*untyped, **untyped) -> bot
+    def self.hangup: (*untyped, **untyped) -> bot
+    def self.says: (*untyped, **untyped) -> bot
+    def self.hears: (*untyped, **untyped) -> bot
+    def self.memory: (*untyped, **untyped) -> bot
+    def self.record: (*untyped, **untyped) -> bot
+    def self.knowledge: (*untyped, **untyped) -> bot
+    def self.docs: (*untyped, **untyped) -> bot
+
+    def self.doc: (?String) -> String?
+    def self.slug: (?String) -> String
+    def self.declared_slug: () -> String?
+    def self.accepts: (String | Symbol, from: Array[String | Symbol]) -> untyped
+    def self.wire_config: (?tools: Array[spec]?) -> Hash[Symbol, untyped]
+
+    # the state and the verbs
+    def self.state: (Symbol, ?untyped, ?visibility: Symbol?) ?{ () -> untyped } -> Symbol
+    def self.stage: (*Symbol) -> Array[Symbol]
+    def self.stages: () -> Array[Symbol]?
+    def self.declared_state: () -> Hash[Symbol, untyped]
+    def self.derived_state: () -> Hash[Symbol, untyped]
+    def self.state_names: () -> Array[Symbol]
+    def self.tool: (**untyped) -> untyped
+    def self.declared_tools: () -> Hash[Symbol, untyped]
+    def self.tool_named: (String | Symbol) -> untyped
+    def self.view: (?String?, ?template: String?) -> View?
+    def self.beside_this_file: (String) -> String
+    def self.source_file: () -> String?
+
+    def doc: () -> String?
+    def tools: () -> Array[spec]
+    def visible_tools: () -> Array[spec]
+    def run_tool: (String | Symbol, ?Hash[Symbol, untyped]) -> untyped
+    def snapshot: () -> state
+    def restore: (state) -> Agent
+    def start_in: (state) -> Agent
+    def diff: (state, ?state) -> Array[Hash[Symbol, untyped]]
+    def collapse: (String) -> untyped
+    def changes: () -> Array[untyped]
+    def on_change: () { (untyped) -> void } -> ^() -> void
+    def on_log: () { (untyped) -> void } -> ^() -> void
+    def on_heard: () { (String, Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void } -> ^() -> void
+    def seal: () -> Agent
+    def sealed?: () -> bool
+    def call: () -> CallWorld
+    def call?: () -> bool
+    def knowledge: () -> Agent::Knowledge
+    def say: (String, **untyped) -> bool
+    def reply: (String, **untyped) -> bool
+    def log: (String | Symbol, ?untyped) -> untyped
+    def logged: () -> Array[untyped]
+    def last: (String) -> state?
+    def on_call: (CallWorld) -> void
+    def on_end: (CallWorld) -> void
+    def on_event: (String, Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void
+    def on_memory: (Array[untyped], CallWorld) -> void
+    def run_hook: (Symbol, *untyped) -> untyped
+    def serving: (CallWorld?) -> Agent
+    def reads_last_from: (^(String) -> state?) -> Agent
+    def notify_heard: (String, Hash[Symbol, untyped], Hash[Symbol, untyped]) -> void
+
+    module Author
+      KEY: Symbol
+      def self?.current: () -> String?
+      def self?.with: [T] (String) { () -> T } -> T
+    end
+
+    module Doc
+      def self.for_class: (Class) -> String?
+      def self.for_method: (Class, Symbol) -> String?
+      def self.above: (String, Integer) -> String?
+      def self.one_line: (Array[String]) -> String?
+      def self.forget: () -> untyped
+    end
+  end
+
+  class Agent
+    class Knowledge
+      def initialize: (Agent) -> void
+      def search: (String, ?k: Integer?) -> Array[CallWorld::Found]
+    end
+
+    module Searching
+      SEARCHES: Array[Array[String]]
+      def self.searches?: (Class) -> bool
+      def self.in_source?: (String) -> bool
+    end
+  end
+
+  class CallWorld
+    LANDS_WITHIN_S: Integer
+    TRANSFER_WITHIN_S: Integer
+    A_MOMENT_S: Integer
+    NO_ANSWER: String
+    THE_CALL_ENDED: String
+    NO_GATEWAY_TO_SEARCH: String
+
+    class Transferred
+      attr_reader to: String
+      attr_reader mode: String?
+      attr_reader ok: bool
+      attr_reader error: String?
+      def initialize: (to: String, mode: String?, ok: bool, error: String?) -> void
+    end
+
+    class Attended
+      attr_reader ok: bool
+      attr_reader by: Hash[Symbol, untyped]?
+      attr_reader error: String?
+      def initialize: (ok: bool, by: Hash[Symbol, untyped]?, error: String?) -> void
+    end
+
+    class Found
+      attr_reader path: String
+      attr_reader heading: String?
+      attr_reader text: String
+      def initialize: (path: String, heading: String?, text: String) -> void
+    end
+
+    class Waiting
+      def wait: [T] (Symbol, Numeric, T) { () -> void } -> T
+      def settle: (Symbol, untyped) -> void
+      def end_all: () -> void
+    end
+
+    attr_reader id: String
+    attr_reader contact: String?
+    attr_reader from: String?
+    attr_reader channel: String?
+    attr_reader medium: String
+    attr_reader today: String
+    attr_reader claimed: String?
+    attr_accessor cause: Hash[Symbol, untyped]?
+    def initialize: (id: String, ?contact: String?, ?from: String?, ?channel: String?, ?medium: String?, ?today: String, ?claimed: String?,
+                     ?searching: (^(String, Integer?) -> Array[Hash[Symbol, untyped]])?) { (String, Hash[Symbol, untyped]) -> untyped } -> void
+    def numbered: () -> Integer
+    def say: (String, **untyped) -> bool
+    def reply: (String, **untyped) -> bool
+    def search: (String, ?k: Integer?) -> Array[Found]
+    def transfer: (String, ?mode: (String | Symbol)?) -> Transferred
+    def attention: (String, wait_s: Numeric) -> Attended
+    def hold: () -> untyped
+    def unhold: () -> untyped
+    def dtmf: (String) -> untyped
+    def claim: (String) -> untyped
+    def callback: (String, ?at: String?, ?note: String?) -> untyped
+    def send_to: (String, untyped, ?to: Array[String]?) -> untyped
+    def participant: (String) -> untyped
+    def invite: (String, ?kind: String?) -> untyped
+    def log: (String | Symbol, ?Hash[Symbol, untyped]) -> untyped
+    def opt_out: (?String?) -> untyped
+    def hangup: (?String?) -> untyped
+    def take: (String, Hash[Symbol, untyped], Float) -> untyped
+    def participants: () -> Array[untyped]
+    def caller_seat: () -> untyped
+    def last_turn: () -> untyped
+  end
+
+  class Client
+    attr_reader url: String
+    attr_reader api_key: String
+    STOPPED: String
+    TOOLS_FINISH_WITHIN_S: Integer
+
+    class Drained
+      attr_reader handed: Integer
+      attr_reader parked: Integer
+      attr_reader tools: Integer
+      attr_reader finished: Integer
+      def initialize: (handed: Integer, parked: Integer, tools: Integer, finished: Integer) -> void
+    end
+
+    attr_reader env: String?
+    def initialize: (url: String, api_key: String, ?env: String?, ?ping_every: Numeric, ?backoff: Hash[Symbol, Numeric]) -> void
+    def drain: (?answer_s: Numeric, ?tools_s: Numeric) -> Drained
+    def on_entries: () { (untyped) -> void } -> ^() -> void
+    def on_stopped: () { (String) -> void } -> ^() -> void
+    def sdk: () -> String
+    def agent: (String, **untyped) -> Client::Agent
+    def agents: () -> Hash[String, Client::Agent]
+    def connect: () -> Client
+    def close: () -> untyped
+    def connected?: () -> bool
+    def on: (String) { (Hash[Symbol, untyped], Client::Call?) -> void } -> ^() -> void
+    def on_any: () { (untyped, Client::Call?) -> void } -> ^() -> void
+    def on_errors: () { (StandardError) -> void } -> ^() -> void
+    def observe: (Hash[Symbol, String], **untyped) { (untyped) -> void } -> void
+    def history: (Hash[Symbol, String], **untyped) -> untyped
+    def search: (String, String, ?k: Integer?) -> Array[Hash[Symbol, untyped]]
+    def send_command: (type: String, agent: String, call: String?, data: Hash[Symbol, untyped], ?id: String?) -> untyped
+    def seen: (untyped, Client::Call?) -> void
+    def on_error: (StandardError) -> void
+    def on_connected: () { () -> void } -> ^() -> void
+
+    class Agent
+      NO_DEV_HANDLER: String
+      attr_reader slug: String
+      attr_reader calls: CallBook
+      attr_reader config: Hash[Symbol, untyped]
+      attr_reader app: String?
+      def on: (String) { (Hash[Symbol, untyped], Client::Call?) -> void } -> ^() -> void
+      def on_any: () { (untyped, Client::Call?) -> void } -> ^() -> void
+      def on_dev: () { (String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped] } -> untyped
+      def declare: (Array[Hash[Symbol, untyped]]) -> void
+      def configure: (?Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def open: () -> Agent
+      def take: (untyped) -> void
+      def command: (String, String?, Hash[Symbol, untyped]) -> untyped
+      def ping: () -> untyped
+      def drain: (?answer_s: Numeric) -> Hash[Symbol, untyped]
+      def in_flight: () -> Integer
+      def settled: (?within_s: Numeric?) -> nil
+      def on_error: (StandardError) -> void
+    end
+
+    class Call
+      attr_reader id: String
+      attr_reader claimed: String?
+      attr_reader run: String?
+      attr_reader medium: String?
+      attr_reader today: String
+      attr_accessor status: String
+      attr_accessor channel: String?
+      attr_accessor from: String?
+      attr_accessor to: String?
+      attr_accessor contact: Hash[Symbol, untyped]?
+      attr_accessor state: Hash[Symbol, untyped]
+      def say: (String, **untyped) -> untyped
+      def reply: (String, **untyped) -> untyped
+      def set_prompt: (String | Symbol, String) -> untyped
+      def set_tools: (Array[Hash[Symbol, untyped]]) -> untyped
+      def set_state: (Hash[Symbol, untyped], ?Array[Symbol | String]?) -> untyped
+      def tool_result: (Hash[Symbol, untyped]) -> untyped
+      def event: (String, Hash[Symbol, untyped]) -> untyped
+      def hangup: (?String?) -> untyped
+      def log: (String | Symbol, ?Hash[Symbol, untyped]) -> untyped
+      def command: (String, Hash[Symbol, untyped]) -> untyped
+      def take: (untyped) -> void
+      def on: (String) { (Hash[Symbol, untyped], Call) -> void } -> ^() -> void
+      def on_any: () { (untyped, Call) -> void } -> ^() -> void
+    end
+
+    class CallBook
+      def live: () -> Array[Call]
+      def of: (String, Float) -> Call
+      def forget: (Call) -> untyped
+    end
+
+    class Listeners
+      def on: (String | Symbol) { (untyped, untyped) -> void } -> ^() -> void
+      def on_any: () { (untyped, untyped) -> void } -> ^() -> void
+      def emit: (untyped, untyped) -> void
+    end
+
+    module Rest
+      def self?.get: (String, api_key: String) -> Hash[Symbol, untyped]?
+      def self?.put: (String, untyped, api_key: String) -> Hash[Symbol, untyped]?
+      def self?.post: (String, untyped, api_key: String) -> Hash[Symbol, untyped]?
+      def self?.delete: (String, api_key: String) -> Hash[Symbol, untyped]?
+    end
+  end
+
+  module Prompt
+    FRAMEWORK: Array[block_spec]
+    def self?.render: (Agent, ?resumed: bool, ?remembered: Array[String], ?line: line?) -> Blocks
+    def self?.identity: (Agent) -> String
+    def self?.tools: (Agent) -> String
+    def self?.history: (Agent) -> String
+    def self?.collapsed: (Integer) -> String
+    def self?.show: (Agent, **untyped) -> String
+    def self?.header_for: (Symbol | String, ?String?) -> String
+  end
+
+  module Serve
+    USAGE: String
+    NO_DOOR: String
+    WORLDS: Array[String]
+
+    class CannotServe < Error
+    end
+
+    class Served
+      attr_reader file: String
+      attr_reader slug: String
+      def initialize: (file: String, slug: String) -> void
+    end
+
+    class Held
+      attr_reader client: Client
+      attr_reader mounted: Array[Bridge::Mounted]
+      def initialize: (Client, Array[Bridge::Mounted]) -> void
+      def stop: () -> Client::Drained
+      def close: () -> untyped
+      def join: () -> untyped
+    end
+
+    module Viewing
+      ONLY_THE_VIEW: String
+      def self?.answer: (Class, String, String, untyped) -> Hash[Symbol, untyped]
+      def self?.a_conversation: (String, untyped) -> Panel::Who
+    end
+
+    def self?.main: (Array[String], ?out: IO, ?err: IO, ?env: Hash[String, String], ?input: IO, ?signals: Thread::Queue?) -> Integer
+    def self?.drain_line: (Client::Drained) -> String
+  end
+
+  module Bridge
+    def self?.mount: (Class, client: untyped, ?slug: String?, ?last: untyped, ?takes_unclaimed: bool) -> Mounted
+
+    class Mounted
+      attr_reader slug: String
+      attr_reader agent: Client::Agent
+      attr_reader options: Hash[Symbol, untyped]
+      def serving: (String) -> Agent?
+    end
+  end
+
+  module Panel
+    TONES: Array[String]
+
+    class Who
+      attr_reader agent: String
+      attr_reader contact: String
+      attr_reader call: String
+      def initialize: (agent: String, contact: String, call: String) -> void
+    end
+
+    class Declared
+      attr_reader name: String
+      attr_reader draw: Proc
+      def initialize: (name: String, draw: Proc) -> void
+    end
+
+    class Drawing
+      attr_reader nodes: Array[Hash[Symbol, untyped]]
+      def initialize: (Class) -> void
+      def panel: (?untyped) ?{ () -> void } -> nil
+      def rows: () ?{ () -> void } -> nil
+      def row: (untyped, ?untyped) -> nil
+      def stat: (untyped, untyped) -> nil
+      def table: (columns: Array[untyped], rows: Array[untyped]) -> nil
+      def badge: (untyped, ?tone: String | Symbol) -> nil
+      def text: (untyped) -> nil
+    end
+
+    def self.said: (untyped) -> String
+    def self.draw: (Class, Panel::Who) -> Hash[Symbol, untyped]
+  end
+
+  module Rules
+    RULES: String
+    PROTOCOLS: String
+    SPOKEN: String
+    ON_A_WEBSITE: String
+    ON_WHATSAPP: String
+    def self?.channel_rules_for: (String | Symbol, String | Symbol) -> String
+  end
+
+  def self.mount: (Class, client: untyped, **untyped) -> Bridge::Mounted
+  def self.render: (Agent, **untyped) -> Blocks
+  def self.show_prompt: (Agent, **untyped) -> String
+  def self.serve: (Class, ?client: Client?, ?url: String?, ?api_key: String?, ?env: String?, ?slug: String?, ?last: untyped) -> Serve::Held
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: pinecall
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Pinecall
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-driver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: The application's side of Pinecall. A class whose declared fields are
+  the state, whose `tool` methods are the model's verbs, whose comments are the prompt,
+  and whose ERB view is the part of that prompt which changes. It speaks commands
+  and reads entries over one socket; it never imports the runtime and never sees audio.
+email:
+- hello@pinecall.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pinecall.rb
+- lib/pinecall/agent.rb
+- lib/pinecall/agent/author.rb
+- lib/pinecall/agent/config.rb
+- lib/pinecall/agent/doc.rb
+- lib/pinecall/agent/knowledge.rb
+- lib/pinecall/agent/searching.rb
+- lib/pinecall/agent/spec.rb
+- lib/pinecall/agent/state.rb
+- lib/pinecall/agent/tools.rb
+- lib/pinecall/blocks.rb
+- lib/pinecall/bridge.rb
+- lib/pinecall/call_world.rb
+- lib/pinecall/call_world/answers.rb
+- lib/pinecall/call_world/room.rb
+- lib/pinecall/client.rb
+- lib/pinecall/client/agent.rb
+- lib/pinecall/client/call.rb
+- lib/pinecall/client/connection.rb
+- lib/pinecall/client/endpoints.rb
+- lib/pinecall/client/listeners.rb
+- lib/pinecall/client/observe.rb
+- lib/pinecall/client/rest.rb
+- lib/pinecall/errors.rb
+- lib/pinecall/panel.rb
+- lib/pinecall/reading.rb
+- lib/pinecall/rules.rb
+- lib/pinecall/serve.rb
+- lib/pinecall/serve/held.rb
+- lib/pinecall/serve/loading.rb
+- lib/pinecall/serve/viewing.rb
+- lib/pinecall/testing.rb
+- lib/pinecall/version.rb
+- lib/pinecall/view.rb
+- lib/pinecall/wire.rb
+- lib/pinecall/wire/codec.rb
+- lib/pinecall/wire/enums.rb
+- lib/pinecall/wire/errors.rb
+- lib/pinecall/wire/reduce.rb
+- lib/pinecall/wire/registry.rb
+- lib/pinecall/wire/shapes.rb
+- lib/pinecall/wire/shapes_call_events.rb
+- lib/pinecall/wire/shapes_commands.rb
+- lib/pinecall/wire/shapes_config.rb
+- lib/pinecall/wire/shapes_doors.rb
+- lib/pinecall/wire/shapes_events.rb
+- lib/pinecall/wire/shapes_metrics.rb
+- lib/pinecall/wire/shapes_parts.rb
+- lib/pinecall/wire/state.rb
+- lib/pinecall/wire/validate.rb
+- sig/pinecall.rbs
+homepage: https://github.com/pinecall/ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/pinecall/ruby
+  source_code_uri: https://github.com/pinecall/ruby
+  changelog_uri: https://github.com/pinecall/ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: 'Write a voice agent as a Ruby class: fields are state, tools are verbs,
+  the view is the prompt'
+test_files: []