pinecall 0.0.1

data/lib/pinecall/wire/codec.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+# Entries and commands read and written: a log line decoded, a command built and encoded.
+
+module Pinecall
+  module Wire
+    # One log line. The streamed and stored forms are identical, and `seq` is assigned before the
+    # write returns, so two readers never disagree.
+    Entry = Data.define(:seq, :ts, :call, :agent, :type, :ephemeral, :data)
+
+    # One app-to-gateway instruction. The gateway answers with the events it produces, or with an
+    # `error` naming the command's id.
+    Command = Data.define(:type, :agent, :call, :id, :data)
+
+    # An entry read as what it means: the wire type, and the payload that type names.
+    Event = Data.define(:type, :data)
+
+    # JSON encoding and decoding. Keys are symbols in Ruby and strings on the wire; both are
+    # snake_case, so unlike TypeScript there is no key renaming.
+    module Codec
+      module_function
+
+      # One log line from parsed JSON. A shape the protocol does not declare is a WireError.
+      def decode_entry(raw)
+        fields = symbolize(raw)
+        Validate.call!("Entry", fields, where: "entry")
+        Entry.new(**fields)
+      end
+
+      # The entry's data as the shape its type names. An unknown type is a WireError.
+      def event_of(entry)
+        shape = Registry::EVENTS[entry.type]
+        raise WireError, "unknown event type: #{entry.type}" if shape.nil?
+
+        Validate.call!(shape, entry.data, where: entry.type)
+        Event.new(type: entry.type, data: entry.data)
+      end
+
+      # Build a command frame, validating its data and then the whole envelope. Validating here
+      # keeps the backtrace in the app's code.
+      def command(type:, agent:, data:, call: nil, id: nil)
+        shape = Registry::COMMANDS[type]
+        raise WireError, "unknown command type: #{type}" if shape.nil?
+
+        Validate.call!(shape, data, where: type)
+        frame = { type:, agent:, call:, data: }
+        frame[:id] = id unless id.nil?
+        Validate.call!("Command", frame, where: type)
+        Command.new(type:, agent:, call:, id:, data:)
+      end
+
+      # A frame as JSON text. A command without an id omits the key (the schema refuses null);
+      # `call` stays null, since a command about the agent itself belongs to no call.
+      def encode(frame)
+        fields = frame.to_h
+        fields.delete(:id) if frame.is_a?(Command) && fields[:id].nil?
+        JSON.generate(fields)
+      end
+
+      # Whether an entry of this type is one a store may drop and a slow reader may miss.
+      def ephemeral?(type)
+        Registry::EPHEMERAL_EVENTS.include?(type)
+      end
+
+      # JSON.parse can symbolize keys, but a hand-built Hash may use strings.
+      def symbolize(value)
+        case value
+        when Hash then value.to_h { |key, inner| [key.to_sym, symbolize(inner)] }
+        when Array then value.map { |inner| symbolize(inner) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/pinecall/wire/enums.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Every closed list of the wire this gem reads, as a frozen array.
+
+module Pinecall
+  module Wire
+    module Enums
+      # The door the public came through: a phone call over SIP, the browser widget over WebRTC,
+      # or WhatsApp text.
+      CHANNEL = %w[phone web whatsapp].freeze
+      # Inbound: the public reached the agent. Outbound: the agent reached out (a dial).
+      DIRECTION = %w[inbound outbound].freeze
+      # How a call is had: spoken in a room, or written. A web call can be either.
+      MEDIUM = %w[voice text].freeze
+      # Which of the two worlds a key opens, and so which world an agent is held in and a call ran
+      # in. A key is issued into one; an agent registered on it and every call it takes carry that
+      # one; a door claimed in one is refused to a key of the other. `sandbox` is where things are
+      # written and `production` is what the public reaches — and whether a sandbox agent is one
+      # PERSON's copy or the team's shared one is not this field: it is whether the key that
+      # registered it names a person. Every key issued before the field existed is production.
+      ENV = %w[production sandbox].freeze
+      # What a console may ask of the process standing in the agent's directory, relayed by the
+      # gateway: a written call to the class mounted there (chat), a simulated caller put on the
+      # class it holds, its goldens and a suite of them, its knowledge folder pushed or its golden
+      # asked, its memory goldens, the panel it draws beside a conversation (view), a call
+      # promoted to a candidate file, the drift of the last two windows, and the reproductions a
+      # broken run left on that disk. Everything else a console needs is a door of the gateway.
+      DEV_VERB = %w[chat.roster chat.start chat.say chat.end view.render simulate.start goldens.roster goldens.run knowledge.roster knowledge.push knowledge.eval memory.roster memory.eval memory.extraction promote.roster promote.write drift.read reproductions.roster reproductions.read].freeze
+      # Why the call is over. Who hung up, what failed before anybody could, drained: the platform
+      # took the worker down (a deploy, a stop) with the call still on it, or app_detached: the
+      # app holding the agent closed its socket mid-call, so nothing was rendering the prompt or
+      # answering a tool — both are nobody's fault and neither is an error.
+      END_REASON = %w[caller_hung_up agent_hung_up supervisor_ended transferred no_answer busy dial_failed timeout drained app_detached error].freeze
+      # Whose action ended the call. platform covers timeouts, errors and a drained worker.
+      ENDED_BY = %w[caller agent supervisor platform].freeze
+      # What one judge answered about a finished call. Held: the rule held. Broken: it did not,
+      # and the reason names the evidence. Deferred: the judge was asked and could not settle it.
+      # Skipped: nobody asked it — no model was reachable inside the call's judging budget.
+      SCORE_VERDICT = %w[held broken deferred skipped].freeze
+      # Cold: the caller is sent on with a REFER on their SIP leg and the call ends here. Warm:
+      # the number is dialled into the call's own room, the agent stays on the line until the
+      # other side answers and then falls silent; the call ends when either of them hangs up.
+      TRANSFER_MODE = %w[cold warm].freeze
+      # Which region of the prompt a block lives in: static, before the history, cached by the
+      # provider; or dynamic, after the history, replaced every turn. The append-only history in
+      # between is never written by the app.
+      PROMPT_REGION = %w[static dynamic].freeze
+      # How the knowledge base reaches the model: retrieved, the platform runs search itself when
+      # the caller's turn ends; or tool, the model calls search when it decides to. Either way the
+      # chunks arrive as a tool result.
+      DOCS_MODE = %w[retrieved tool].freeze
+      # What the platform believes the person on the line is doing right now. The states are the
+      # session's own.
+      USER_STATE = %w[listening speaking away].freeze
+      # What the agent is doing right now, in the session's own words: warming up, waiting,
+      # hearing the caller, generating, or playing audio.
+      AGENT_STATE = %w[initializing idle listening thinking speaking].freeze
+      # Who a participant is to the call: the person the agent serves (over SIP or the widget),
+      # the agent itself, a supervisor who took a seat in the room, a listener who only hears, or
+      # a second SIP leg that room.invite brought in.
+      PARTICIPANT_KIND = %w[caller agent supervisor listener sip].freeze
+      # What a track carries: a microphone's audio, a camera's video, or a screen share.
+      TRACK_KIND = %w[audio video screen].freeze
+      # Where a track comes from, as livekit's TrackSource names it, in lower case.
+      TRACK_SOURCE = %w[microphone camera screen_share screen_share_audio unknown].freeze
+      # Where an outside fact came from: the tenant's backend over the app socket (app), or a
+      # participant's browser over the DataChannel (participant).
+      EVENT_SOURCE = %w[app participant].freeze
+      # Who may see a field of the app's state: everyone in the call (public), the tenant's own
+      # readers (tenant, the default for a field never declared), or nobody without masking (pii).
+      VISIBILITY = %w[public tenant pii].freeze
+      # Which projection a sink applies before a state or an entry leaves the platform: public for
+      # a participant reading its own call, tenant for the tenant's readers. The contract is
+      # docs/protocol/projections.md; a client never applies one.
+      PROJECTION = %w[public tenant].freeze
+      # Where the call is in its life. idle before any call.* entry, which is what an agent's own
+      # log looks like.
+      CALL_STATUS = %w[idle ringing dialing active ended].freeze
+      # Every closed list by the name the schema gave it, for a validator to look up.
+      ALL = {
+        "Channel" => CHANNEL,
+        "Direction" => DIRECTION,
+        "Medium" => MEDIUM,
+        "Env" => ENV,
+        "DevVerb" => DEV_VERB,
+        "EndReason" => END_REASON,
+        "EndedBy" => ENDED_BY,
+        "ScoreVerdict" => SCORE_VERDICT,
+        "TransferMode" => TRANSFER_MODE,
+        "PromptRegion" => PROMPT_REGION,
+        "DocsMode" => DOCS_MODE,
+        "UserState" => USER_STATE,
+        "AgentState" => AGENT_STATE,
+        "ParticipantKind" => PARTICIPANT_KIND,
+        "TrackKind" => TRACK_KIND,
+        "TrackSource" => TRACK_SOURCE,
+        "EventSource" => EVENT_SOURCE,
+        "Visibility" => VISIBILITY,
+        "Projection" => PROJECTION,
+        "CallStatus" => CALL_STATUS
+      }.freeze
+    end
+  end
+end

data/lib/pinecall/wire/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# The one error of the wire: a frame, an entry or a body that does not fit its shape.
+
+module Pinecall
+  module Wire
+    # A message did not match the protocol: an unknown type, a bad shape, an undeclared key.
+    # Raised where the frame is built or received, so the backtrace points at the caller.
+    class WireError < StandardError
+    end
+  end
+end

data/lib/pinecall/wire/reduce.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+# Folds a log into its State, entry by entry, as the runtime's reducer does.
+
+module Pinecall
+  module Wire
+    # Folds a log into its State, entry by entry. Must match the TypeScript and Python reducers;
+    # the golden fixture checks all three.
+    module Reduce
+      # Error code recorded for an entry the reader cannot decode.
+      UNREADABLE = "unreadable"
+
+      module_function
+
+      # Fold every entry, in the order given, into the state an empty log starts from.
+      def reduce(entries)
+        entries.reduce(State.initial) { |state, entry| apply(state, entry) }
+      end
+
+      # Fold one entry in. A gap with a snapshot replaces the state; every other entry mutates it
+      # in place. The seq always advances.
+      def apply(state, entry)
+        event = begin
+          Codec.event_of(entry)
+        rescue WireError => why
+          return moved(unreadable(state, entry, why), entry)
+        end
+        following = event.type == "log.gap" ? on_log_gap(state, event.data) : apply_event(state, entry, event)
+        moved(following, entry)
+      end
+
+      # Old logs may hold entries in shapes this reader no longer accepts. Record one error and
+      # keep folding instead of rejecting the whole call; the Python and TypeScript reducers agree.
+      def unreadable(state, entry, why)
+        said = why.message.to_s.lines.first.to_s.strip
+        state[:errors] << {
+          seq: entry.seq,
+          code: UNREADABLE,
+          message: "#{entry.type} at seq #{entry.seq} is not the shape this reader knows: #{said}"
+        }
+        state
+      end
+
+      # Advance the fold to the entry's seq, whatever the entry was.
+      def moved(state, entry)
+        state[:seq] = entry.seq
+        state[:agent] = entry.agent
+        state[:call] = entry.call unless entry.call.nil?
+        state
+      end
+
+      # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+      def apply_event(state, entry, event)
+        data = event.data
+        case event.type
+        # ── the call ──
+        when "call.ringing" then the_line(state, data, status: "ringing", direction: "inbound")
+        when "call.dialing" then the_line(state, data, status: "dialing", direction: "outbound")
+        when "call.started" then started(state, data)
+        when "call.ended" then ended(state, data)
+        when "call.transferred" then transferred(state, data)
+        when "call.line" then state.merge!(held: data[:held], muted: data[:muted])
+        when "call.summary" then summarised(state, data)
+        # ── the conversation ──
+        when "user.state" then state[:user_state] = data[:state]
+        when "agent.state" then state[:agent_state] = data[:state]
+        when "user.transcript" then state[:live][:user] = data[:final] ? nil : data[:text]
+        when "agent.transcript" then state[:live][:agent] = data[:final] ? nil : said_so_far(state[:live][:agent], data)
+        when "turn.user" then turn(state, data, "user")
+        when "turn.agent" then turn(state, data, "agent")
+        when "memory.ops" then state[:memory].concat(data[:ops])
+        when "docs.sources" then state[:sources] = data[:sources].dup
+        # ── metrics: every block is kept, in order, by kind ──
+        when "metrics.llm", "metrics.stt", "metrics.tts", "metrics.vad", "metrics.eou",
+             "metrics.eot", "metrics.interruption", "metrics.realtime", "metrics.avatar"
+          state[:metrics][event.type.delete_prefix("metrics.").to_sym] << data
+        # ── tools, state, confirmation ──
+        when "tool.call" then state[:tools] << data.merge(status: "running", seq: entry.seq)
+        when "tool.result" then on_tool_result(state, data)
+        when "state.changed" then state[:app_state] = data[:state].dup
+        when "prompt.changed" then on_prompt_changed(state, data, entry)
+        when "tools.changed" then state[:tools_visible] = data[:visible].dup
+        when "confirm.request" then requested(state, data)
+        when "confirm.granted" then settle(state, data[:call_id], { status: "granted", said: data[:said] })
+        when "confirm.declined" then declined(state, data)
+        # ── supervision, the agent, markers ──
+        when "supervisor.took_over" then state[:handoff] = { active: true, by: data[:by] }
+        when "supervisor.released" then state[:handoff] = { active: false, by: nil }
+        when "supervisor.transferred" then took_the_line(state, data)
+        when "attention.requested" then asked_for_a_person(state, data, entry.ts)
+        when "attention.answered" then answered(state, data)
+        when "agent.registered" then state[:routes] = data[:routes].dup
+        when "error" then state[:errors] << { seq: entry.seq, code: data[:code], message: data[:message] }
+        when "custom" then state[:custom] << { seq: entry.seq, name: data[:name], data: data[:data].dup }
+        # ── the room and the outside world ──
+        when "room.opened" then state[:room] = { name: data[:name], sid: data[:sid], participants: [], caller: nil }
+        when "participant.joined" then joined(state, data, entry.ts)
+        when "participant.left" then left(state, data[:identity])
+        when "participant.speaking" then speaking(state, data)
+        when "event.received" then state[:events] << data.except(:data).merge(seq: entry.seq)
+        end
+        state
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+
+      # Not reduced (the case above leaves the state unchanged): supervisor.said/.whispered surface
+      # as turns and prompt changes, supervisor.ended as call.ended; agent.configured, pong,
+      # log.caught_up, track.published, track.unpublished and room.sent stay in the log only.
+
+      def the_line(state, line, status:, direction:)
+        state.merge!(
+          status:,
+          direction:,
+          channel: line[:channel],
+          from: line[:from],
+          to: line[:to],
+          caller: line[:caller]
+        )
+      end
+
+      def started(state, data)
+        the_line(state, data, status: "active", direction: data[:direction])
+        state[:started_at] = data[:started_at]
+      end
+
+      def ended(state, data)
+        state[:status] = "ended"
+        state[:ended_at] = data[:ended_at]
+        state[:end_reason] = data[:reason]
+        state[:live] = { user: nil, agent: nil }
+        # A caller who hung up while waiting for a person was never answered.
+        state[:attention] = state[:attention].merge(status: "lapsed") if state[:attention]&.fetch(:status) == "open"
+      end
+
+      def transferred(state, data)
+        state[:transfer] = {
+          to: data[:to],
+          mode: data[:mode],
+          status: data[:ok] ? "done" : "failed",
+          by: state[:transfer]&.fetch(:by, nil) || "agent"
+        }
+      end
+
+      def took_the_line(state, data)
+        state[:transfer] = { to: data[:to], mode: data[:mode], status: "requested", by: "supervisor" }
+      end
+
+      def asked_for_a_person(state, data, asked_at)
+        state[:attention] = { reason: data[:reason], wait_s: data[:wait_s], status: "open", asked_at: asked_at, by: nil }
+      end
+
+      def answered(state, data)
+        return if state[:attention].nil?
+
+        state[:attention] = state[:attention].merge(status: data[:ok] ? "answered" : "lapsed", by: data[:by])
+      end
+
+      def summarised(state, data)
+        state[:usage] = data[:usage].dup
+        state[:cost] = data[:cost]
+        state[:outcome] = data[:outcome]
+        state[:end_reason] ||= data[:reason]
+      end
+
+      # A delta: one word of a spoken reply or one token of a written one. Aligned voice words
+      # arrive bare and are joined with a space; written tokens carry their own spacing.
+      def said_so_far(so_far, data)
+        return data[:text] if so_far.nil? || so_far.empty?
+
+        apart = so_far.match?(/\s\z/) || data[:text].match?(/\A\s/)
+        !data[:start].nil? && !apart ? "#{so_far} #{data[:text]}" : "#{so_far}#{data[:text]}"
+      end
+
+      def turn(state, data, who)
+        state[:turns] << { role: who }.merge(data)
+        state[:live][who.to_sym] = nil
+      end
+
+      def requested(state, data)
+        state[:confirms] << {
+          tool: data[:tool],
+          call_id: data[:call_id],
+          audience: data[:audience],
+          phrase: data[:phrase],
+          status: "pending"
+        }
+      end
+
+      def declined(state, data)
+        verdict = { status: "declined", reason: data[:reason] }
+        verdict[:said] = data[:said] if data.key?(:said)
+        settle(state, data[:call_id], verdict)
+      end
+
+      def on_tool_result(state, result)
+        at = state[:tools].rindex { |run| run[:call_id] == result[:call_id] }
+        return if at.nil?
+
+        outcome = result.except(:call_id, :name)
+        state[:tools][at] = state[:tools][at].merge(outcome, status: outcome.key?(:error) ? "failed" : "done")
+      end
+
+      def settle(state, call_id, verdict)
+        at = state[:confirms].rindex { |confirm| confirm[:call_id] == call_id }
+        return if at.nil?
+
+        state[:confirms][at] = state[:confirms][at].merge(verdict)
+      end
+
+      def on_prompt_changed(state, data, entry)
+        state[:prompt][data[:name].to_sym] = { hash: data[:hash], chars: data[:chars], seq: entry.seq }
+      end
+
+      # joined_at is the entry's ts; the event does not repeat it.
+      def joined(state, joined, at)
+        return if state[:room].nil?
+
+        state[:room][:participants] << joined.merge(joined_at: at, speaking: false)
+        state[:room][:caller] = joined[:identity] if joined[:kind] == "caller"
+      end
+
+      # An identity is unique within a room: LiveKit disconnects the first of two that share one.
+      def left(state, identity)
+        return if state[:room].nil?
+
+        state[:room][:participants].reject! { |one| one[:identity] == identity }
+        state[:room][:caller] = nil if state[:room][:caller] == identity
+      end
+
+      def speaking(state, data)
+        who = state[:room]&.fetch(:participants)&.find { |one| one[:identity] == data[:identity] }
+        who[:speaking] = data[:speaking] unless who.nil?
+      end
+
+      # With a snapshot the state is replaced; without one only the gap is recorded.
+      def on_log_gap(state, data)
+        following = data[:snapshot].nil? ? state : deep_copy(data[:snapshot])
+        following[:gaps] << { from_seq: data[:from_seq], to_seq: data[:to_seq] }
+        following
+      end
+
+      # Copy the snapshot so later writes do not mutate the entry. Plain JSON data, so Marshal is a
+      # safe deep copy.
+      def deep_copy(value)
+        Marshal.load(Marshal.dump(value))
+      end
+    end
+  end
+end

data/lib/pinecall/wire/registry.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+# Every event and command of the wire by its type, and the shape its data is.
+
+require "set"
+
+module Pinecall
+  module Wire
+    module Registry
+      # The shape each event's data is, by the event's wire type.
+      EVENTS = {
+        "agent.configured" => "AgentConfigured",
+        "agent.detached" => "AgentDetached",
+        "agent.draining" => "AgentDraining",
+        "agent.registered" => "AgentRegistered",
+        "agent.state" => "AgentStateChanged",
+        "agent.transcript" => "AgentTranscript",
+        "attention.answered" => "AttentionAnswered",
+        "attention.requested" => "AttentionRequested",
+        "call.attached" => "CallAttached",
+        "call.claimed" => "CallClaimed",
+        "call.dialing" => "CallDialing",
+        "call.ended" => "CallEnded",
+        "call.line" => "CallLine",
+        "call.ringing" => "CallRinging",
+        "call.score" => "CallScore",
+        "call.started" => "CallStarted",
+        "call.summary" => "CallSummary",
+        "call.transferred" => "CallTransferred",
+        "callback.requested" => "CallbackRequested",
+        "code.claimed" => "CodeClaimed",
+        "code.issued" => "CodeIssued",
+        "confirm.declined" => "ConfirmDeclined",
+        "confirm.granted" => "ConfirmGranted",
+        "confirm.request" => "ConfirmRequest",
+        "credits.exhausted" => "CreditsExhausted",
+        "custom" => "Custom",
+        "dev.request" => "DevRequest",
+        "docs.sources" => "DocsSources",
+        "dtmf.received" => "DtmfReceived",
+        "error" => "ErrorEvent",
+        "event.received" => "EventReceived",
+        "fleet.full" => "FleetFull",
+        "log.caught_up" => "LogCaughtUp",
+        "log.gap" => "LogGap",
+        "memory.ops" => "MemoryOps",
+        "message.taken" => "MessageTaken",
+        "message.waiting" => "MessageWaiting",
+        "metrics.avatar" => "AvatarMetrics",
+        "metrics.eot" => "EOTInferenceMetrics",
+        "metrics.eou" => "EOUMetrics",
+        "metrics.interruption" => "InterruptionMetrics",
+        "metrics.llm" => "LLMMetrics",
+        "metrics.realtime" => "RealtimeModelMetrics",
+        "metrics.stt" => "STTMetrics",
+        "metrics.tts" => "TTSMetrics",
+        "metrics.vad" => "VADMetrics",
+        "participant.joined" => "ParticipantJoined",
+        "participant.left" => "ParticipantLeft",
+        "participant.speaking" => "ParticipantSpeaking",
+        "pong" => "Pong",
+        "prompt.changed" => "PromptChanged",
+        "room.opened" => "RoomOpened",
+        "room.sent" => "RoomSent",
+        "spend.unusual" => "SpendUnusual",
+        "state.changed" => "StateChanged",
+        "supervisor.ended" => "SupervisorEnded",
+        "supervisor.released" => "SupervisorReleased",
+        "supervisor.said" => "SupervisorSaid",
+        "supervisor.took_over" => "SupervisorTookOver",
+        "supervisor.transferred" => "SupervisorTransferred",
+        "supervisor.whispered" => "SupervisorWhispered",
+        "tool.call" => "ToolCall",
+        "tool.result" => "ToolResult",
+        "tools.changed" => "ToolsChanged",
+        "track.published" => "TrackPublished",
+        "track.unpublished" => "TrackUnpublished",
+        "turn.agent" => "AgentTurnEnded",
+        "turn.user" => "UserTurnEnded",
+        "user.state" => "UserStateChanged",
+        "user.transcript" => "UserTranscript",
+        "vendor.switched" => "VendorSwitched"
+      }.freeze
+
+      # The shape each command's data is, by the command's wire type.
+      COMMANDS = {
+        "agent.configure" => "AgentConfigure",
+        "agent.drain" => "AgentDrain",
+        "agent.register" => "AgentRegister",
+        "agent.reply" => "AgentReply",
+        "agent.say" => "AgentSay",
+        "call.attention" => "CallAttention",
+        "call.callback" => "CallCallback",
+        "call.claim" => "CallClaim",
+        "call.dial" => "CallDial",
+        "call.dtmf" => "CallDtmf",
+        "call.event" => "CallEvent",
+        "call.hangup" => "CallHangup",
+        "call.hold" => "CallHold",
+        "call.log" => "CallLog",
+        "call.mute" => "CallMute",
+        "call.opt_out" => "CallOptOut",
+        "call.transfer" => "CallTransfer",
+        "call.unhold" => "CallUnhold",
+        "call.unmute" => "CallUnmute",
+        "dev.answer" => "DevAnswer",
+        "participant.mute" => "ParticipantMute",
+        "participant.remove" => "ParticipantRemove",
+        "ping" => "Ping",
+        "prompt.set" => "PromptSet",
+        "room.invite" => "RoomInvite",
+        "room.send" => "RoomSend",
+        "session.configure" => "SessionConfigure",
+        "state.set" => "StateSet",
+        "supervisor.verb" => "SupervisorVerb",
+        "tool.result" => "ToolResult",
+        "tools.set" => "ToolsSet"
+      }.freeze
+
+      # Every event this protocol declares, in the schema's own order.
+      EVENT_TYPES = %w[agent.configured agent.detached agent.draining agent.registered agent.state agent.transcript attention.answered attention.requested call.attached call.claimed call.dialing call.ended call.line call.ringing call.score call.started call.summary call.transferred callback.requested code.claimed code.issued confirm.declined confirm.granted confirm.request credits.exhausted custom dev.request docs.sources dtmf.received error event.received fleet.full log.caught_up log.gap memory.ops message.taken message.waiting metrics.avatar metrics.eot metrics.eou metrics.interruption metrics.llm metrics.realtime metrics.stt metrics.tts metrics.vad participant.joined participant.left participant.speaking pong prompt.changed room.opened room.sent spend.unusual state.changed supervisor.ended supervisor.released supervisor.said supervisor.took_over supervisor.transferred supervisor.whispered tool.call tool.result tools.changed track.published track.unpublished turn.agent turn.user user.state user.transcript vendor.switched].freeze
+
+      # Every command an app may send.
+      COMMAND_TYPES = %w[agent.configure agent.drain agent.register agent.reply agent.say call.attention call.callback call.claim call.dial call.dtmf call.event call.hangup call.hold call.log call.mute call.opt_out call.transfer call.unhold call.unmute dev.answer participant.mute participant.remove ping prompt.set room.invite room.send session.configure state.set supervisor.verb tool.result tools.set].freeze
+
+      # Entries a store may drop and a slow reader may miss without harm: the entry's
+      # own ephemeral flag defaults to this.
+      EPHEMERAL_EVENTS = %w[agent.transcript dev.request log.caught_up log.gap metrics.vad participant.speaking pong room.sent user.transcript].to_set.freeze
+
+      # The one event that ends a call: after it nothing more is true and the log seals.
+      TERMINAL_EVENT = "call.score"
+
+      # Which events a command lands in the log as, so a caller knows what to wait for.
+      PRODUCES = {
+        "agent.configure" => %w[agent.configured],
+        "agent.drain" => %w[agent.draining],
+        "agent.register" => %w[agent.registered],
+        "agent.reply" => %w[turn.agent],
+        "agent.say" => %w[turn.agent],
+        "call.attention" => %w[attention.requested call.line attention.answered],
+        "call.callback" => %w[callback.requested],
+        "call.claim" => %w[call.claimed],
+        "call.dial" => %w[call.dialing],
+        "call.dtmf" => [],
+        "call.event" => %w[event.received],
+        "call.hangup" => %w[call.ended],
+        "call.hold" => %w[call.line],
+        "call.log" => %w[custom],
+        "call.mute" => %w[call.line],
+        "call.transfer" => %w[call.transferred],
+        "call.unhold" => %w[call.line],
+        "call.unmute" => %w[call.line],
+        "dev.answer" => [],
+        "participant.mute" => %w[track.unpublished],
+        "participant.remove" => %w[participant.left],
+        "ping" => %w[pong],
+        "prompt.set" => %w[prompt.changed],
+        "room.invite" => %w[participant.joined],
+        "room.send" => %w[room.sent],
+        "session.configure" => %w[state.changed agent.configured],
+        "state.set" => %w[state.changed],
+        "supervisor.verb" => %w[supervisor.said supervisor.whispered supervisor.took_over supervisor.released supervisor.transferred supervisor.ended],
+        "tool.result" => %w[tool.result],
+        "tools.set" => %w[tools.changed]
+      }.freeze
+    end
+  end
+end

data/lib/pinecall/wire/shapes.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Every named shape of the wire, as the table Validate walks. A shape is closed: a key nobody
+# declared is refused by name, since it means the gateway speaks a newer wire than this gem.
+
+require_relative "shapes_parts"
+require_relative "shapes_call_events"
+require_relative "shapes_events"
+require_relative "shapes_commands"
+require_relative "shapes_doors"
+require_relative "shapes_config"
+require_relative "shapes_metrics"
+
+module Pinecall
+  module Wire
+    module Shapes
+      SHAPES = [PARTS, CONFIG, METRICS, CALL_EVENTS, EVENTS, COMMANDS, DOORS].reduce(:merge).freeze
+
+      # A union is told apart by one field, the way the schema's discriminator says.
+      UNIONS = {
+        "ModelUsage" => { on: :type, members: %w[LLMModelUsage TTSModelUsage STTModelUsage InterruptionModelUsage EOTModelUsage] }.freeze,
+        "Turn" => { on: :role, members: %w[UserTurn AgentTurn] }.freeze,
+        "Verb" => { on: :verb, members: %w[SayVerb WhisperVerb TakeoverVerb ReleaseVerb TransferVerb EndVerb] }.freeze,
+        "StateCause" => { on: :kind, members: %w[StateCauseTool StateCauseEvent] }.freeze
+      }.freeze
+
+      # A map is keyed by names the app chose; every value is the one shape given here.
+      MAPS = {
+        "PromptState" => { kind: :ref, ref: "PromptBlockState" }.freeze
+      }.freeze
+    end
+  end
+end