pinecall 0.11.14 → 0.11.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f97d72a0ab4004e51b2f9bb07d601cb8c6007b10babece8ca03e6071f4f05aa4
-  data.tar.gz: 966cb68d6ac119c9d5c838910b242eaf3cf620a7688436f135475d47f3e9846e
+  metadata.gz: ccadca23b8a8165ca26d6378d9309a21fe194aa7f36768186feec8ded71113a9
+  data.tar.gz: db44663b616cdaaed4b616cddc7ef84105a2eb59c50228b359c975a4c433888a
 SHA512:
-  metadata.gz: 58596d5793c2003e72ae9c1cdcfe938db4834bf9e0b64177759daecfbdb7f7d83dd6869d8cd55ce6029eab7b81616da0dd1f80a378166efe572db593cf2257e0
-  data.tar.gz: f8c4ee0d9f134ac38c861d5b6bcb956c382299d4dd2fd6518af14e06afa7672f8d633be515f0590c56d9097289759a14294a0fb0fbfedc58f9d27119c6e7c793
+  metadata.gz: 6b81c136cc6986a767110f1dc169367c00799a45e42897150b506cfec1949d4f3470bddfe40dd864ae510240eb8fa93979a043e62de5d0a9c30b0fec71ba9024
+  data.tar.gz: 9b6afb0e418e3820b427e82bdbf868aa912f68459ce7e9f4388ea6c7e605be4fc3aaab6505e5e8e2b4d2b23edfbe86327a1fc35542d1253f0870788b93e538ea

data/CHANGELOG.md

@@ -4,6 +4,64 @@ Every change a person using this gem would notice. The format is
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version numbers and tags are the
 maintainer's call.
 
+## [0.11.16] — no object prints the API key, a failing view or hook fails its call, values reach the wire as fields (2026-10-23)
+
+- **SECURITY: no object of the gem prints the API key any more.** `Client` and its connection held the key
+  in an instance variable and Ruby's default `inspect` printed it (and the websocket driver's
+  `Authorization` header), as did every object holding a client (`Serve::Held`, `Client::Agent`, a `p`, an
+  exception that interpolated one, a log line); both now say their door and their agents, never the key.
+  (found by the 2026-10-23 eval, J F8 side note)
+- **The serve entry no longer prints the values an agent declared private.** `--events` printed every entry
+  as the gateway wrote it, so a tool's `pii` arguments, the state fields declared `pii` and a private value
+  echoed in a tool's answer or a logged line reached the terminal; they are masked as the call's log masks
+  them (by name, and by value as a whole word once a tool call carried it, never a value shorter than three
+  characters). (found by the 2026-10-23 eval, A F3, B D7, L D7)
+- **A `Data` or a `Struct` reaches the wire as its fields, wherever a Ruby value becomes JSON.** A tool's
+  return, a state field, a logged line or a payload holding one was sent as its `inspect` string
+  (`knowledge.search(…)` handed the model `"#<data Pinecall::CallWorld::Found …>"`); every command's data
+  now passes through one `Wire::Codec.plain` before it is validated, and `call.log` of a `Data` or a
+  `Struct` is its fields. (found by the 2026-10-23 eval, D D-2)
+- **A view that raises fails its own call and nothing else.** The call's log gets a `render.failed` entry
+  with the exception's class and message, the model keeps the view it had and the process goes on; before,
+  the first render's failure left the call without a prompt and without a trace in its log. (found by the
+  2026-10-23 eval, B B8)
+- **A hook that raises fails its own call and nothing else.** `on_call`, `on_event`, `on_memory` and `on_end`
+  raised through the call's job thread, which only printed a line: the call was left without a prompt, an
+  `on_event`'s cause stayed on the next write and an `on_end` never said `call.done`. The call's log now
+  gets a `hook.failed` entry naming the hook (and the event) and the error, and the call goes on with what
+  the hook wrote. (found by the 2026-10-23 eval, B B8)
+- **Every state write names its author on the wire.** Each `state.set` carries `cause`: the tool and the
+  model's id for its call, the outside fact (name and the entry's seq), or the hook (`on_call`,
+  `on_memory`); only the first write of a tool had one, from the runtime, and a hook's none. The
+  `state.cause` log line is gone, `on_event`'s `meta[:seq]` is the entry's seq, and the wire knows
+  `StateCauseHook`, `StateSet.cause` and `CallStarted.metadata`. A client tool's `run` takes the model's
+  call id as a third argument. (found by the 2026-10-23 eval, B B4)
+- **A line logged in `on_call` lands in the call's log.** The log was forwarded only after the hook had run.
+  (found by the 2026-10-23 eval, B B3)
+- **The gem sends `call.done` after the end hook, and registers `says_done`**, so the gateway's seal waits
+  for what the hook logs before it seals the log. (found by the 2026-10-23 eval, S2)
+- **`call.to`, `call.direction`, `call.caller` and `call.metadata`** are on the call a tool or a hook reads,
+  as in the TypeScript package; the testing gateway's `call_started` takes `direction:` and `metadata:`.
+  (found by the 2026-10-23 eval, K F6)
+- **A stop from the org leaves no `IOError: closed stream` behind.** The driver's answer to the gateway's
+  close frame was written to a socket this side had already closed and reported as an error; a write after
+  this side closed on purpose is not one. (found by the 2026-10-23 eval, J F2)
+- **`Pinecall.serve`'s `held.stop` says where the calls went**, one line on stderr as the serve entry does
+  (`draining · no live calls`); `Serve::Held.new` takes `err:`. (found by the 2026-10-23 eval, J F8)
+- **The serve entry says when an admin kills one of its agents**: one line on stderr, `<slug>  ✗ <slug> was
+  killed by <name>`, and `Client#on_killed` hands over the slug and the sentence. (found by the 2026-10-23
+  eval, J F3)
+- **The app no longer answers `end_call`.** The platform writes that call and its result itself; an error
+  result from the app was a second one. (found by the 2026-10-23 eval, R2)
+- **The testing page shows what `call.tool` returns when the tool succeeds**: `{ call_id:, name:, output:,
+  duration_s: }`, the tool's value under `[:output]`. (found by the 2026-10-23 eval, D R0-1)
+
+## [0.11.15] — the serve entry registers as its host (2026-10-23)
+
+- **The serve entry registers as `PINECALL_HOST` when it is set**, else as this machine's
+  hostname (`Client#host`). A hosted app's runner names each host, and the gateway knows a release
+  is serving by it, on a machine that runs several.
+
 ## [0.11.14] — the wire knows `KnowledgePushed.kept` (2026-10-23)
 
 - **`KnowledgePushed.kept`**: the files of the base a push did not name and kept.

data/lib/pinecall/agent/author.rb

@@ -8,6 +8,7 @@ module Pinecall
     # `Fiber[]` is inherited by child fibers and separate per thread.
     module Author
       KEY = :pinecall_author
+      CALL = :pinecall_author_call
 
       module_function
 
@@ -16,14 +17,20 @@ module Pinecall
         Fiber[KEY]
       end
 
-      # Run the block with state writes attributed to `name`.
-      def with(name)
-        held = Fiber[KEY]
+      # The model's id for the tool call the current author is running, or nil.
+      def call_id
+        Fiber[CALL]
+      end
+
+      # Run the block with state writes attributed to `name`; a tool also says the model's `call_id`.
+      def with(name, call_id = nil)
+        held = [Fiber[KEY], Fiber[CALL]]
         Fiber[KEY] = name
+        Fiber[CALL] = call_id
         begin
           yield
         ensure
-          Fiber[KEY] = held
+          Fiber[KEY], Fiber[CALL] = held
         end
       end
     end

data/lib/pinecall/agent/state.rb

@@ -98,7 +98,7 @@ module Pinecall
       # back as JSON is a string, and is the declared stage it names.
       def restore(state)
         state = state.transform_keys(&:to_sym)
-        Author.with(Author.current || "restore") do
+        Author.with(Author.current || "restore", Author.call_id) do
           self.class.declared_state.each_key do |name|
             value = state.key?(name) ? state[name] : nil
             write_state(name, name == :stage ? declared_stage(value) : value)

data/lib/pinecall/agent/tools.rb

@@ -70,12 +70,13 @@ module Pinecall
         self.class.declared_tools.values.select { |declared| Tools.shows?(declared, state) }
       end
 
-      # Run a tool as the bridge does, with its writes attributed to it.
-      def run_tool(name, arguments = {})
+      # Run a tool as the bridge does, with its writes attributed to it; `call_id` is the model's id
+      # for the call, when there is one.
+      def run_tool(name, arguments = {}, call_id = nil)
         declared = self.class.tool_named(name)
         raise ToolFailed, "#{name}: this agent declares no such tool" if declared.nil?
 
-        Tools.run(self, declared, arguments)
+        Tools.run(self, declared, arguments, call_id)
       end
 
       class << self
@@ -93,10 +94,10 @@ module Pinecall
         end
 
         # Check arguments, run the method with its writes attributed, and trim to `preview`.
-        def run(agent, declared, arguments)
+        def run(agent, declared, arguments, call_id = nil)
           named = arguments.to_h { |key, value| [key.to_sym, value] }
           refuse_arguments_the_tool_never_asked_for(declared, named)
-          result = Author.with(declared.name.to_s) { agent.public_send(declared.name, **named) }
+          result = Author.with(declared.name.to_s, call_id) { agent.public_send(declared.name, **named) }
           preview(result, declared.options[:preview])
         end
 

data/lib/pinecall/bridge.rb

@@ -70,7 +70,7 @@ module Pinecall
       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:)
+      options = klass.wire_config(tools: tools_for(probe, live)).merge(takes_unclaimed:, says_done: true)
       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) }
@@ -81,11 +81,11 @@ module Pinecall
     # 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|
+        spec.merge(run: lambda do |arguments, call, call_id|
           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)
+          serving.agent.run_tool(spec[:name], arguments, call_id)
         end)
       end
     end
@@ -103,6 +103,7 @@ module Pinecall
       instance.serving(serving.world)
       live[call.id] = serving
       serving.later do
+        forward_log(serving, call)
         instance.restore(call.state)
         sync(serving, call)
         listen(serving, call)
@@ -117,7 +118,8 @@ module Pinecall
 
     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,
+      CallWorld.new(id: call.id, contact: call.contact&.dig(:id) || call.from, from: call.from, to: call.to,
+                    channel: call.channel, direction: call.direction, caller: call.contact, metadata: call.metadata,
                     medium: call.medium, today: call.today, claimed: call.claimed, searching:) do |type, data|
         call.command(type, data)
       end
@@ -125,7 +127,8 @@ module Pinecall
 
     # 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.
+    # after the hook, which would overwrite it, and before the first render. The log is open from the
+    # hook on: a line `on_call` writes is the call's.
     def start(klass, live, call, client, last, opened_in)
       instance = klass.new.seal
       instance.reads_last_from(last) unless last.nil?
@@ -134,32 +137,56 @@ module Pinecall
       serving = Live.new(instance, world)
       live[call.id] = serving
       serving.later do
-        instance.run_hook(:on_call, world)
+        forward_log(serving, call)
+        hooked(serving, call, :on_call, world)
         instance.start_in(opened_in) unless opened_in.nil?
-        call.set_state(instance.snapshot)
+        call.set_state(instance.snapshot, *opening(instance))
         sync(serving, call)
         listen(serving, call)
       end
     end
 
-    # Re-sync the prompt on every state change.
+    # What the opening `state.set` says: when `on_call` wrote, the fields written and the hook as the
+    # cause. Nothing written, nothing said: the whole state is the news.
+    def opening(instance)
+      return [] unless instance.changes.any? { |change| change.author == "hook:on_call" }
+
+      [instance.changes.map(&:field).uniq, { kind: "hook", hook: "on_call" }]
+    end
+
+    # Re-sync the prompt on every state change, each one sent with who wrote it.
     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?
+        call.set_state(instance.snapshot, [change.field], cause_of(change, serving))
         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"
+        received(serving, call, event) if event.type == "event.received"
         rerendered(serving, call, event)
       end
     end
 
+    # Who made a write, as the wire's `StateCause` says it: the lifecycle hook, the outside fact the hook is
+    # handling, or the tool and the model's id for the call that ran it. A write the wire has no word for
+    # (a restore) says nothing.
+    def cause_of(change, serving)
+      author = change.author.to_s
+      case author
+      when "hook:on_call", "hook:on_memory" then { kind: "hook", hook: author.delete_prefix("hook:") }
+      when "hook:on_event" then (fact = serving.world.cause) && { kind: "event", **fact }
+      else
+        call_id = Agent::Author.call_id
+        { kind: "tool", tool: author, call_id: } if call_id && serving.agent.class.tool_named(author)
+      end
+    end
+
+    # What the class logs reaches the call's log until `on_end` has run.
+    def forward_log(serving, call)
+      serving.stops[:log] = serving.agent.on_log { |entry| call.log(entry.name, as_object(entry.data)) }
+    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. What memory did then
     # reaches `on_memory`, after the view already says it.
@@ -169,7 +196,7 @@ module Pinecall
       when "memory.ops"
         serving.remembered = words_recalled(event.data)
         sync(serving, call)
-        serving.later { serving.agent.run_hook(:on_memory, event.data[:ops] || [], serving.world) }
+        serving.later { hooked(serving, call, :on_memory, event.data[:ops] || [], serving.world) }
       end
     end
 
@@ -182,19 +209,23 @@ module Pinecall
 
     # Drop events whose (name, source) the class did not declare: an `:app` event arriving from
     # a browser could be spoofed.
-    def received(serving, fact)
+    def received(serving, call, event)
+      fact = event.data
       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
+      meta = { source: fact[:source], identity: fact[:identity], seq: event.seq }.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
+        serving.world.cause = { name:, seq: event.seq }
+        begin
+          hooked(serving, call, :on_event, name, fact[:data] || {}, meta, event: name)
+          serving.agent.notify_heard(name, fact[:data] || {}, meta)
+        ensure
+          serving.world.cause = nil
+        end
       end
     end
 
@@ -205,8 +236,11 @@ module Pinecall
 
       serving.stops.values_at(:state, :entries).compact.each(&:call)
       serving.later do
-        serving.agent.run_hook(:on_end, serving.world)
+        hooked(serving, call, :on_end, serving.world)
         serving.stops[:log]&.call
+        # After every line the hook logged, whether it ran or raised: the gateway seals the call on this
+        # word, and a line sent after the seal is refused.
+        call.done
       end
       serving.finish
     end
@@ -215,27 +249,48 @@ module Pinecall
     # 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:)
+      begin
+        rendered = Prompt.render(serving.agent, remembered: serving.remembered, line:)
+        visible = serving.agent.visible_tools
+      rescue StandardError => e
+        return failed_to_render(call, e)
+      end
       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
 
+    # A view that fails fails its call, never the process: the model keeps the view it had, and the log says why.
+    def failed_to_render(call, error)
+      call.log("render.failed", { error: error.class.to_s, message: error.message })
+      warn("pinecall: #{call.id} could not render its view and goes on with the one it had: #{error.message}")
+    end
+
+    # A hook that raises fails its call, never the process: the call goes on with what the hook wrote
+    # before it raised, and the log says which hook and why.
+    def hooked(serving, call, hook, *args, event: nil)
+      serving.agent.run_hook(hook, *args)
+    rescue StandardError => e
+      call.log("hook.failed", { hook: hook.to_s, event:, error: e.class.to_s, message: e.message }.compact)
+      warn("pinecall: #{call.id} #{hook} raised and the call goes on without it: #{e.message}")
+      nil
+    end
+
     def agent_class(serving) = serving.agent.class
 
-    # `call.log` data must be an object; wrap scalars under `value`.
+    # `call.log` data must be an object: a `Data` or a `Struct` is its fields, other values go under `value`.
     def as_object(data)
-      return {} if data.nil?
+      fields = Wire::Codec.plain(data)
+      return {} if fields.nil?
 
-      data.is_a?(Hash) ? data : { value: data }
+      fields.is_a?(Hash) ? fields : { value: fields }
     end
   end
 end

data/lib/pinecall/call_world.rb

@@ -9,17 +9,26 @@ module Pinecall
   # State is reduced from received entries; each verb is one wire command. No LiveKit access by
   # design: a missing capability should become a new command of the wire.
   class CallWorld
-    attr_reader :id, :contact, :from, :channel, :medium, :room, :turns, :today, :claimed
+    attr_reader :id, :contact, :from, :to, :channel, :direction, :caller, :metadata, :medium, :room, :turns, :today,
+                :claimed
 
     # `send` puts one command on the wire for this call; `searching` asks the gateway to search for
     # it. Both are supplied by the bridge. `today` is the day the call opened, YYYY-MM-DD. `medium` is
     # spoken (`voice`) or written (`text`); a gateway that does not say gets it from the channel.
-    def initialize(id:, contact: nil, from: nil, channel: nil, medium: nil, today: Time.now.strftime("%Y-%m-%d"),
-                   claimed: nil, searching: nil, &send)
+    # `to` is the number called, or the agent a visitor reached; `direction` is `inbound` when the public
+    # reached the agent and `outbound` when it dialled; `caller` is who the platform knows is on the line
+    # (`id`, `name`, `phone`, `email`), nil when nobody is named; `metadata` is what the call was opened with,
+    # such as a token's, `{}` when none.
+    def initialize(id:, contact: nil, from: nil, to: nil, channel: nil, direction: nil, caller: nil, metadata: nil,
+                   medium: nil, today: Time.now.strftime("%Y-%m-%d"), claimed: nil, searching: nil, &send)
       @id = id
       @contact = contact
       @from = from
+      @to = to
       @channel = channel
+      @direction = direction
+      @caller = caller
+      @metadata = metadata || {}
       @medium = (medium || (channel.to_s == "whatsapp" ? "text" : "voice")).to_s
       @today = today
       @claimed = claimed
@@ -29,15 +38,11 @@ module Pinecall
       @turns = []
       @waiting = Waiting.new
       @cause = nil
-      @events = 0
     end
 
-    # The external event being handled, if any; logged as the cause of state changes.
+    # The external event being handled, if any (`name` and the entry's `seq`); the cause of the writes it makes.
     attr_accessor :cause
 
-    # Next per-call event sequence number (not the wire's seq).
-    def numbered = @events += 1
-
     # ── commands ─────────────────────────────────────────────────────────────
 
     # Speak `text` verbatim now. Returns true once the turn arrives, false after `LANDS_WITHIN_S`.
@@ -110,7 +115,8 @@ module Pinecall
 
     # Append an application entry to the call's log.
     def log(name, data = {})
-      @send.call("call.log", { name: name.to_s, data: data.is_a?(Hash) ? data : { value: data } })
+      fields = Wire::Codec.plain(data)
+      @send.call("call.log", { name: name.to_s, data: fields.is_a?(Hash) ? fields : { value: fields } })
     end
 
     # The caller asked never to be called again: their number joins the org's do-not-call list, and no

data/lib/pinecall/client/agent.rb

@@ -20,9 +20,11 @@ module Pinecall
         @client = client
         @routes = options[:routes] || []
         @takes_unclaimed = options.fetch(:takes_unclaimed, true)
+        # Sends `call.done` once a call's end hook ran: the gateway's seal waits for the hook's lines.
+        @says_done = options.fetch(:says_done, false)
         @tools = {}
         @waiting = []
-        @config = options.reject { |key, _| %i[routes tools takes_unclaimed].include?(key) }
+        @config = options.reject { |key, _| %i[routes tools takes_unclaimed says_done].include?(key) }
         @app = nil
         @running = []
         @dev = nil
@@ -46,7 +48,8 @@ module Pinecall
 
       # Replace the tools; sent with the next `configure`.
       #
-      # A tool is `{ **spec, run: ->(arguments, call) { … } }`.
+      # A tool is `{ **spec, run: ->(arguments, call, call_id) { … } }`: `call_id` is the model's id for the
+      # call, which a state write it makes names as its cause.
       def declare(tools)
         @tools = tools.to_h { |tool| [tool[:name].to_s, tool] }
         @config = @config.merge(tools: tools.map { |tool| tool.reject { |key, _| key == :run } })
@@ -61,8 +64,8 @@ module Pinecall
       # Register the slug and send the config. Runs on every reconnect.
       def open
         registered = ask("agent.register", lands_as: "agent.registered", data: {
-                           routes: @routes, sdk: @client.sdk, host: Socket.gethostname,
-                           takes_unclaimed: @takes_unclaimed
+                           routes: @routes, sdk: @client.sdk, host: @client.host,
+                           takes_unclaimed: @takes_unclaimed, **(@says_done ? { says_done: true } : {})
                          })
         # Each connection gets a new app id.
         @app = registered[:app]
@@ -117,12 +120,17 @@ module Pinecall
       def run_tool(event, call)
         call_id, name, arguments = event.data.values_at(:call_id, :name, :arguments)
         tool = @tools[name.to_s]
-        return call.tool_result({ call_id:, name:, error: "this app declares no tool called #{name}" }) if tool.nil?
+        if tool.nil?
+          # The platform answers its own tool, and an answer from here would race it.
+          return if name == Wire::Enums::END_CALL
+
+          return call.tool_result({ call_id:, name:, error: "this app declares no tool called #{name}" })
+        end
 
         running = Thread.new do
           started = now
           begin
-            output = tool[:run].call(arguments || {}, call)
+            output = tool[:run].call(arguments || {}, call, call_id)
             call.tool_result({ call_id:, name:, output:, duration_s: now - started })
           rescue StandardError => e
             # Report the exception to the model as the tool's `error`.

data/lib/pinecall/client/call.rb

@@ -6,7 +6,7 @@ module Pinecall
     #
     # Commands are not awaited; their effects arrive later as log entries.
     class Call
-      attr_reader :id, :today, :claimed, :run, :medium
+      attr_reader :id, :today, :claimed, :run, :medium, :direction, :metadata
       attr_accessor :status, :channel, :from, :to, :contact, :state
 
       def initialize(id, agent, opened_at)
@@ -17,6 +17,8 @@ module Pinecall
         @channel = nil
         # Spoken or written, as `call.started` says; nil before it, and from a gateway that does not say.
         @medium = nil
+        @direction = nil
+        @metadata = {}
         @from = nil
         @to = nil
         @contact = nil
@@ -48,11 +50,13 @@ module Pinecall
       # Set the tools currently visible to the model (a subset of the declared ones).
       def set_tools(tools) = command("tools.set", { tools: })
 
-      # Send the full state; answered with `state.changed`.
-      def set_state(state, changed = nil)
+      # Send the full state; answered with `state.changed`. `cause` says who wrote it, in the wire's
+      # `StateCause`: a tool, an outside event or a lifecycle hook.
+      def set_state(state, changed = nil, cause = nil)
         @state = state
         wire = { state: }
         wire[:changed] = Array(changed).map(&:to_s) unless changed.nil?
+        wire[:cause] = cause unless cause.nil?
         command("state.set", wire)
       end
 
@@ -67,6 +71,9 @@ module Pinecall
       # Append an application entry to the call's log, as a `custom` entry.
       def log(name, data = {}) = command("call.log", { name: name.to_s, data: })
 
+      # Say the end hook ran and what it wrote was sent: the gateway seals the call on this word.
+      def done = command("call.done", {})
+
       # Send any call-scoped command of the wire.
       def command(type, data) = @agent.command(type, @id, data)
 
@@ -104,6 +111,8 @@ module Pinecall
       def started(line)
         the_line(line, "active")
         @medium = line[:medium]
+        @direction = line[:direction]
+        @metadata = line[:metadata] || {}
         # A run's call says its day, which a golden may have pinned; a person's runs on the clock's.
         @today = line[:today] if line[:today]
       end

data/lib/pinecall/client/connection.rb

@@ -32,6 +32,9 @@ module Pinecall
 
       def open? = @open
 
+      # Never the key, nor the driver, which holds it in its headers.
+      def inspect = "#<#{self.class} #{@url} #{@open ? "open" : "closed"}>"
+
       # Connect and return once `on_open` has run; reconnects are handled internally afterwards.
       def start
         @closed = false
@@ -70,11 +73,12 @@ module Pinecall
         nil
       end
 
-      # Called by websocket-driver.
+      # Called by websocket-driver. Once this side closed the socket, what the driver still writes (the
+      # answer to the gateway's close frame) has nowhere to go, and that is not a failure.
       def write(bytes)
         @socket.write(bytes)
       rescue IOError, SystemCallError => e
-        @handlers.on_error.call(e)
+        @handlers.on_error.call(e) unless @closed
       end
 
       private

data/lib/pinecall/client.rb

@@ -44,6 +44,8 @@ module Pinecall
     Drained = Data.define(:handed, :parked, :tools, :finished)
 
     attr_reader :url, :api_key, :env
+    # The machine it says it runs on: a hosted app's is the name its runner gave it.
+    attr_accessor :host
 
     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?
@@ -51,10 +53,12 @@ module Pinecall
       @url = url
       @api_key = api_key
       @env = env
+      @host = Socket.gethostname
       @agents = {}
       @errors = []
       @entries = []
       @stops = []
+      @kills = []
       @connects = []
       @listeners = Listeners.new { |error| on_error(error) }
       @connection = Connection.new(
@@ -73,6 +77,9 @@ module Pinecall
       @agents[slug] = Agent.new(slug, options, self)
     end
 
+    # What a log line or an exception prints of the client: its door and its agents, never the key.
+    def inspect = "#<#{self.class} #{@url} env=#{@env.inspect} agents=#{@agents.keys.inspect}>"
+
     # Declared agents by slug.
     def agents = @agents.dup
 
@@ -120,6 +127,13 @@ module Pinecall
       -> { @stops.delete(listener) }
     end
 
+    # Called when an admin lets go of one of this client's agents: the listener takes its slug and the
+    # gateway's sentence. The socket stays open for the others. Returns a lambda that unsubscribes.
+    def on_killed(&listener)
+      @kills << listener
+      -> { @kills.delete(listener) }
+    end
+
     # True while the socket is up.
     def connected? = @connection.open?
 
@@ -177,7 +191,7 @@ module Pinecall
       return if agent.nil?
 
       guarded { agent.take(entry) }
-      @agents.delete(entry.agent) if killed?(entry)
+      killed(entry) if killed?(entry)
     end
 
     # An `error` coded `stopped` for no agent: a member of the org pressed Stop.
@@ -185,6 +199,12 @@ module Pinecall
 
     def killed?(entry) = entry.type == "error" && entry.data[:code] == KILLED
 
+    # The agent is no longer declared, so a reconnect leaves it out; then whoever asked to know.
+    def killed(entry)
+      @agents.delete(entry.agent)
+      @kills.each { |listener| guarded { listener.call(entry.agent, entry.data[:message]) } }
+    end
+
     # 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

data/lib/pinecall/serve/held.rb

@@ -8,21 +8,24 @@ module Pinecall
     class Held
       attr_reader :client, :mounted
 
-      def initialize(client, mounted)
+      def initialize(client, mounted, err: $stderr)
         @client = client
         @mounted = mounted
+        @err = err
         @stopped = Thread::Queue.new
         @lock = Mutex.new
         @drained = nil
       end
 
-      # Drain every agent, then close the socket; asked twice, the first answer. Returns the drain.
+      # Drain every agent, close the socket and say on stderr where the calls went; asked twice, the
+      # first answer. Returns the drain.
       def stop
         @lock.synchronize do
           return @drained unless @drained.nil?
 
           @drained = @client.drain
           close
+          @err.puts(Serve.drain_line(@drained))
           @drained
         end
       end

data/lib/pinecall/serve/masking.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+# What a served process prints of its agent's entries: the values the agent declared private, masked as the call's log masks them.
+
+module Pinecall
+  module Serve
+    # One agent's private names and, as its tool calls pass, the private values they carried.
+    class Masking
+      MASK = "***"
+
+      # Shorter than this a value is never learned as a secret: "7", "ok" or "Al" cannot be told from a
+      # word, and hunting it in what else is written would mask every such digit or word. The argument is
+      # still masked by its name; only its value is not looked for.
+      LEAST_SECRET_LENGTH = 3
+
+      # What the agent wrote down, by entry: the fields of its data a private value may be in. What was
+      # said is the caller's and the model's words, and never masked.
+      WRITTEN_DOWN = {
+        "tool.call" => %i[arguments],
+        "tool.result" => %i[output error summary],
+        "state.changed" => %i[state],
+        "call.attached" => %i[state],
+        "custom" => %i[data]
+      }.freeze
+
+      # `declared` is the agent's wire config: the arguments its tools list under `pii`, and the state
+      # fields declared `pii`.
+      def initialize(declared)
+        @arguments = (declared[:tools] || []).to_h { |tool| [tool[:name].to_s, Array(tool[:pii]).map(&:to_sym)] }
+        @fields = (declared[:state_fields] || []).filter_map { |field| field[:name].to_sym if field[:visibility].to_s == "pii" }
+        @values = Set.new
+        @pattern = nil
+      end
+
+      # The entry with every private value masked: by name where the agent named it, by value wherever
+      # else it was written down. An entry with nothing private to hide is the entry itself.
+      def entry(entry)
+        fields = WRITTEN_DOWN[entry.type]
+        return entry if fields.nil?
+
+        named = @arguments.fetch(entry.data[:name].to_s, [])
+        return entry unless @values.any? || @fields.any? || (entry.type == "tool.call" && named.any?)
+
+        learn(named, entry.data) if entry.type == "tool.call"
+        data = entry.data.dup
+        fields.each { |field| data[field] = masked(data[field], names_in(entry, field, named)) if data.key?(field) }
+        entry.with(data:)
+      end
+
+      private
+
+      def names_in(entry, field, named)
+        return named if entry.type == "tool.call" && field == :arguments
+
+        field == :state ? @fields : []
+      end
+
+      def learn(named, data)
+        given = data[:arguments]
+        return unless given.is_a?(Hash)
+
+        known = @values.size
+        named.each { |name| @values.merge(leaves(given[name])) }
+        @pattern = whole_words if @values.size != known
+      end
+
+      # A hash is masked member by member; any other value is masked of the secrets alone.
+      def masked(value, names)
+        return scrubbed(value) unless value.is_a?(Hash)
+
+        value.to_h { |name, member| [name, names.include?(name.to_sym) ? MASK : scrubbed(member)] }
+      end
+
+      # A leaf that is a private value goes whole; a string that holds one as a whole word has it
+      # replaced, so the rest of what it said stays readable.
+      def scrubbed(value)
+        return value if @pattern.nil?
+
+        case value
+        when String then value.gsub(@pattern, MASK)
+        when Numeric then @values.include?(value.to_s) ? MASK : value
+        when Array then value.map { |item| scrubbed(item) }
+        when Hash then value.to_h { |name, member| [name, scrubbed(member)] }
+        else value
+        end
+      end
+
+      # A value is a secret where it stands as a whole word: `Ana` is no part of `Banana` or `Anabel`, nor
+      # `7` of `1700`. The longest comes first, so a value that holds another is masked whole.
+      def whole_words
+        ordered = @values.sort_by { |secret| -secret.length }
+        Regexp.new("(?<![[:alnum:]_])(?:#{ordered.map { |secret| Regexp.escape(secret) }.join("|")})(?![[:alnum:]_])")
+      end
+
+      # Every string and number inside a value, as text; a blank is no secret, it would mask everything.
+      def leaves(value)
+        case value
+        when String then secret_of(value.strip)
+        when Numeric then secret_of(value.to_s)
+        when Array then value.flat_map { |item| leaves(item) }
+        when Hash then value.values.flat_map { |member| leaves(member) }
+        else []
+        end
+      end
+
+      def secret_of(text) = text.length >= LEAST_SECRET_LENGTH ? [text] : []
+    end
+  end
+end

data/lib/pinecall/serve.rb

@@ -2,6 +2,7 @@
 
 require_relative "serve/loading"
 require_relative "serve/held"
+require_relative "serve/masking"
 require_relative "serve/viewing"
 
 module Pinecall
@@ -40,18 +41,18 @@ module Pinecall
     def start(flags, out:, err:, env:, input:, signals:)
       client = client_from(env, prod: flags.prod)
       classes = flags.served.map { |served| [served, Loading.load_served(served)] }
-      said(client, out:, err:, events: flags.events)
       mounted = classes.map do |served, klass|
         held = Pinecall.mount(klass, client:, slug: served.slug, takes_unclaimed: !flags.console)
         held.agent.on_dev { |verb, data| Viewing.answer(klass, served.slug, verb, data) }
         held
       end
-      held = Held.new(client, mounted)
+      said(client, out:, err:, events: flags.events, maskings: mounted.to_h { |one| [one.slug, Masking.new(one.options)] })
+      held = Held.new(client, mounted, err:)
       asked = signals || trapped
       client.on_stopped { |why| err.puts(why) || asked.push(:stopped) }
       client.connect
       Thread.new { ended(input, asked) }
-      leave(held, asked, err)
+      leave(held, asked)
     end
 
     # Load the class, open it in the state the pairs name, and print its prompt. No gateway, no key.
@@ -115,21 +116,27 @@ module Pinecall
       world = nil if world.to_s.empty?
       raise CannotServe, "PINECALL_ENV is sandbox or production, not #{world}" unless world.nil? || WORLDS.include?(world)
 
-      Client.new(url:, api_key: key, env: world)
+      client = Client.new(url:, api_key: key, env: world)
+      # The name a hosted app's runner gave it: the gateway knows the release by it.
+      client.host = env["PINECALL_HOST"] unless env["PINECALL_HOST"].to_s.empty?
+      client
     end
 
     # Listening starts before connect, so `agent.registered` is the first line of a pipe. A pipe's
     # $stdout is buffered: each line is flushed, or the CLI waiting on it sees it only at exit.
-    def said(client, out:, err:, events:)
+    def said(client, out:, err:, events:, maskings:)
       client.on_entries do |entry|
         if events
-          out.puts(JSON.generate({ type: entry.type, agent: entry.agent, call: entry.call, data: entry.data }))
+          # What it prints is what the call's log keeps: a value the agent declared private never reaches a terminal.
+          shown = maskings[entry.agent]&.entry(entry) || entry
+          out.puts(JSON.generate({ type: shown.type, agent: shown.agent, call: shown.call, data: shown.data }))
         elsif entry.type == "agent.registered"
           out.puts("#{entry.agent}  · answering as #{entry.data[:app]}")
         end
         out.flush
       end
       client.on_errors { |error| err.puts("#{error.class}: #{error.message}") }
+      client.on_killed { |slug, why| err.puts("#{slug}  ✗ #{why}") }
     end
 
     # A trap only pushes: the main thread does the leaving, as a trap may not take a lock.
@@ -150,7 +157,7 @@ module Pinecall
 
     # The first reason drains (unless the org already stopped it); only a second signal closes at
     # once. The end of stdin is not one: the CLI passes a signal on and closes the pipe together.
-    def leave(held, asked, err)
+    def leave(held, asked)
       if asked.pop == :stopped
         held.close
         return 0
@@ -161,8 +168,7 @@ module Pinecall
         nil until asked.pop == :signalled
         outcome.push(:again)
       end
-      drained = outcome.pop
-      drained == :again ? held.close : err.puts(drain_line(drained))
+      held.close if outcome.pop == :again
       0
     end
   end

data/lib/pinecall/testing.rb

@@ -104,6 +104,9 @@ module Pinecall
 
       def sdk = "pinecall-ruby-testing/#{VERSION}"
 
+      # Same as `Pinecall::Client#host`: the machine it says it runs on.
+      def host = Socket.gethostname
+
       # Same signature as `Pinecall::Client#agent`.
       def agent(slug, **options)
         @agents[slug] = Client::Agent.new(slug, options, self)
@@ -128,13 +131,14 @@ module Pinecall
       attr_reader :errors
 
       # Start a call and return its `Fake` handle; `state:` is the state its opener asked for,
-      # `today:` the day a golden pinned (YYYY-MM-DD).
-      def call_started(id: nil, channel: "web", from: "+34600000000", to: "+34910000000", caller: nil, state: nil,
-                       today: nil)
+      # `today:` the day a golden pinned (YYYY-MM-DD), `metadata:` what a token opened it with.
+      def call_started(id: nil, channel: "web", direction: "inbound", from: "+34600000000", to: "+34910000000",
+                       caller: nil, state: nil, today: nil, metadata: nil)
         id ||= "CA_#{next_seq}"
-        started = { channel:, direction: "inbound", from:, to:, caller:, started_at: Time.now.to_f }
+        started = { channel:, direction:, from:, to:, caller:, started_at: Time.now.to_f }
         started = started.merge(state:) unless state.nil?
         started = started.merge(today:) unless today.nil?
+        started = started.merge(metadata:) unless metadata.nil?
         deliver("call.started", started, call: id)
         settle
         Fake.new(self, id)

data/lib/pinecall/version.rb

@@ -2,5 +2,5 @@
 
 module Pinecall
   # Set by the maintainer at release time.
-  VERSION = "0.11.14"
+  VERSION = "0.11.16"
 end

data/lib/pinecall/wire/codec.rb

@@ -12,8 +12,8 @@ module Pinecall
     # `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)
+    # An entry read as what it means: the wire type, the payload that type names, and the entry's seq.
+    Event = Data.define(:type, :data, :seq)
 
     # 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.
@@ -33,7 +33,7 @@ module Pinecall
         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)
+        Event.new(type: entry.type, data: entry.data, seq: entry.seq)
       end
 
       # Build a command frame, validating its data and then the whole envelope. Validating here
@@ -42,6 +42,7 @@ module Pinecall
         shape = Registry::COMMANDS[type]
         raise WireError, "unknown command type: #{type}" if shape.nil?
 
+        data = plain(data)
         Validate.call!(shape, data, where: type)
         frame = { type:, agent:, call:, data: }
         frame[:id] = id unless id.nil?
@@ -49,6 +50,17 @@ module Pinecall
         Command.new(type:, agent:, call:, id:, data:)
       end
 
+      # A Ruby value as the JSON the wire carries: a `Data` or a `Struct` is its fields, wherever it sits in
+      # an array or a hash, since `JSON.generate` would send its `inspect`.
+      def plain(value)
+        case value
+        when Data, Struct then plain(value.to_h)
+        when Hash then value.to_h { |key, inner| [key, plain(inner)] }
+        when Array then value.map { |inner| plain(inner) }
+        else value
+        end
+      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)

data/lib/pinecall/wire/enums.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Every closed list of the wire this gem reads, as a frozen array.
+# Every closed list of the wire this gem reads, as a frozen array, and the name the platform keeps for itself.
 
 module Pinecall
   module Wire
@@ -8,6 +8,9 @@ module Pinecall
       # 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
+      # The tool the platform puts in front of a model that may hang up. Its tool.call and its
+      # tool.result are both the platform's, so an app answers none.
+      END_CALL = "end_call"
       # 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.

data/lib/pinecall/wire/registry.rb

@@ -101,6 +101,7 @@ module Pinecall
         "call.callback" => "CallCallback",
         "call.claim" => "CallClaim",
         "call.dial" => "CallDial",
+        "call.done" => "CallDone",
         "call.dtmf" => "CallDtmf",
         "call.event" => "CallEvent",
         "call.hangup" => "CallHangup",
@@ -129,7 +130,7 @@ module Pinecall
       EVENT_TYPES = %w[agent.configured agent.detached agent.draining agent.registered agent.state agent.transcript app.failed 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 evals.spent event.received fleet.full judge.broke 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 release.changed room.opened room.sent run.changed spend.unusual state.changed supervisor.ended supervisor.released supervisor.said supervisor.took_over supervisor.transferred supervisor.whispered tool.call tool.failed tool.ran tool.result tools.changed track.published track.unpublished turn.agent turn.user user.state user.transcript vendor.switched worker.changed].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
+      COMMAND_TYPES = %w[agent.configure agent.drain agent.register agent.reply agent.say call.attention call.callback call.claim call.dial call.done 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.
@@ -149,6 +150,7 @@ module Pinecall
         "call.callback" => %w[callback.requested],
         "call.claim" => %w[call.claimed],
         "call.dial" => %w[call.dialing],
+        "call.done" => [],
         "call.dtmf" => [],
         "call.event" => %w[event.received],
         "call.hangup" => %w[call.ended],

data/lib/pinecall/wire/shapes.rb

@@ -21,7 +21,7 @@ module Pinecall
         "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
+        "StateCause" => { on: :kind, members: %w[StateCauseTool StateCauseEvent StateCauseHook] }.freeze
       }.freeze
 
       # A map is keyed by names the app chose; every value is the one shape given here.

data/lib/pinecall/wire/shapes_call_events.rb

@@ -100,7 +100,8 @@ module Pinecall
           worker: { kind: :str, null: true },
           medium: { kind: :ref, ref: "Medium", null: true },
           state: { kind: :json },
-          today: { kind: :str, null: true }
+          today: { kind: :str, null: true },
+          metadata: { kind: :json }
         }.freeze,
         "CallSummary" => {
           reason: { kind: :ref, ref: "EndReason", required: true },

data/lib/pinecall/wire/shapes_commands.rb

@@ -15,7 +15,8 @@ module Pinecall
           sdk: { kind: :str },
           host: { kind: :str },
           takes_unclaimed: { kind: :bool, default: true },
-          answers_dev: { kind: :bool, default: false }
+          answers_dev: { kind: :bool, default: false },
+          says_done: { kind: :bool, default: false }
         }.freeze,
         "AgentReply" => {
           instructions: { kind: :str, required: true },
@@ -50,6 +51,7 @@ module Pinecall
           name: { kind: :str, required: true },
           data: { kind: :json, required: true }
         }.freeze,
+        "CallDone" => {}.freeze,
         "CallHangup" => {
           reason: { kind: :str }
         }.freeze,
@@ -99,7 +101,8 @@ module Pinecall
         }.freeze,
         "StateSet" => {
           state: { kind: :json, required: true },
-          changed: { kind: :list, items: { kind: :str } }
+          changed: { kind: :list, items: { kind: :str } },
+          cause: { kind: :ref, ref: "StateCause" }
         }.freeze,
         "SupervisorVerb" => {
           by: { kind: :ref, ref: "Supervisor", required: true },

data/lib/pinecall/wire/shapes_parts.rb

@@ -337,6 +337,10 @@ module Pinecall
           name: { kind: :str, required: true },
           seq: { kind: :int, required: true }
         }.freeze,
+        "StateCauseHook" => {
+          kind: { kind: :const, const: "hook", required: true },
+          hook: { kind: :enum, values: %w[on_call on_memory], required: true }
+        }.freeze,
       }.freeze
     end
   end

data/sig/pinecall.rbs

@@ -125,7 +125,7 @@ module Pinecall
     def doc: () -> String?
     def tools: () -> Array[spec]
     def visible_tools: () -> Array[spec]
-    def run_tool: (String | Symbol, ?Hash[Symbol, untyped]) -> untyped
+    def run_tool: (String | Symbol, ?Hash[Symbol, untyped], ?String?) -> untyped
     def snapshot: () -> state
     def restore: (state) -> Agent
     def start_in: (state) -> Agent
@@ -156,8 +156,10 @@ module Pinecall
 
     module Author
       KEY: Symbol
+      CALL: Symbol
       def self?.current: () -> String?
-      def self?.with: [T] (String) { () -> T } -> T
+      def self?.call_id: () -> String?
+      def self?.with: [T] (String, ?String?) { () -> T } -> T
     end
 
     module Doc
@@ -221,14 +223,18 @@ module Pinecall
     attr_reader id: String
     attr_reader contact: String?
     attr_reader from: String?
+    attr_reader to: String?
     attr_reader channel: String?
+    attr_reader direction: String?
+    attr_reader caller: Hash[Symbol, untyped]?
+    attr_reader metadata: Hash[Symbol, untyped]
     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 initialize: (id: String, ?contact: String?, ?from: String?, ?to: String?, ?channel: String?, ?direction: String?,
+                     ?caller: Hash[Symbol, untyped]?, ?metadata: Hash[Symbol, untyped]?, ?medium: String?, ?today: String,
+                     ?claimed: String?, ?searching: (^(String, Integer?) -> Array[Hash[Symbol, untyped]])?) { (String, Hash[Symbol, untyped]) -> untyped } -> void
     def say: (String, **untyped) -> bool
     def reply: (String, **untyped) -> bool
     def search: (String, ?k: Integer?) -> Array[Found]
@@ -266,10 +272,12 @@ module Pinecall
     end
 
     attr_reader env: String?
+    attr_accessor host: 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 on_killed: () { (String, String) -> void } -> ^() -> void
     def sdk: () -> String
     def agent: (String, **untyped) -> Client::Agent
     def agents: () -> Hash[String, Client::Agent]
@@ -313,6 +321,8 @@ module Pinecall
       attr_reader claimed: String?
       attr_reader run: String?
       attr_reader medium: String?
+      attr_reader direction: String?
+      attr_reader metadata: Hash[Symbol, untyped]
       attr_reader today: String
       attr_accessor status: String
       attr_accessor channel: String?
@@ -324,11 +334,12 @@ module Pinecall
       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 set_state: (Hash[Symbol, untyped], ?Array[Symbol | String]?, ?Hash[Symbol, untyped]?) -> 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 done: () -> untyped
       def command: (String, Hash[Symbol, untyped]) -> untyped
       def take: (untyped) -> void
       def on: (String) { (Hash[Symbol, untyped], Call) -> void } -> ^() -> void
@@ -380,10 +391,18 @@ module Pinecall
       def initialize: (file: String, slug: String) -> void
     end
 
+    class Masking
+      MASK: String
+      LEAST_SECRET_LENGTH: Integer
+      WRITTEN_DOWN: Hash[String, Array[Symbol]]
+      def initialize: (Hash[Symbol, untyped]) -> void
+      def entry: (untyped) -> untyped
+    end
+
     class Held
       attr_reader client: Client
       attr_reader mounted: Array[Bridge::Mounted]
-      def initialize: (Client, Array[Bridge::Mounted]) -> void
+      def initialize: (Client, Array[Bridge::Mounted], ?err: IO) -> void
       def stop: () -> Client::Drained
       def close: () -> untyped
       def join: () -> untyped

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pinecall
 version: !ruby/object:Gem::Version
-  version: 0.11.14
+  version: 0.11.16
 platform: ruby
 authors:
 - Pinecall
@@ -66,6 +66,7 @@ files:
 - lib/pinecall/serve.rb
 - lib/pinecall/serve/held.rb
 - lib/pinecall/serve/loading.rb
+- lib/pinecall/serve/masking.rb
 - lib/pinecall/serve/viewing.rb
 - lib/pinecall/testing.rb
 - lib/pinecall/version.rb