pi-agent-rb 0.1.18 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a86ab7926d2a79fcd0b1777fa3e646762e2940b570a2b3b23ec05f1b6a2b61ad
-  data.tar.gz: cbc2d4df9b4999003e0b2733d190beb0f972997478d3365ecd14770602440c8a
+  metadata.gz: 24f258d02d946aa8752944f4438581126665c94b5ee1253e61c8ebd16ecb6596
+  data.tar.gz: f98727ad546acbc6ea8dee3e2cf52af1cf7694f3875181fdec16c3773fd2e0b7
 SHA512:
-  metadata.gz: dc0fc51144b3820a94753bede3a0f3f14df30cf1b16bce2e4e87530b1a3fb7f9dcc422910ceefcd3ccff42a7978a4c4f81ccc5182606be89aa176cc4375819c9
-  data.tar.gz: 88100dce5b222fde9d481a402190dc1d6dbb205de75ee8f2528a95b697e752ed68696f3c642dabbb749bd00a9bf1e76a8a8846fe7ded16227e0e300bdfceb8f8
+  metadata.gz: 32e5f3a97a2f6b890a1f1c8aecdd59125a4588b6879e815471ad2257942d291a6ccc5c46d32e4bd04abe13020e8ccb4cde1643dfb9230bea9e7974bb8008513f
+  data.tar.gz: '099b2a2267bd8a7212c6d90473775d54a22e7d80982471682ae339cd01875383561bd77364f9f9fe54c8a9514ae26023811ec24a8bcbe1b2dd035f1412f30377'

data/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-23
+
+Minor (not patch) release: besides the stream-truncation fix, the block form
+of `Session#follow_up` and stream concurrency behave differently (see
+Changed).
+
+### Fixed
+- `Session#prompt`, `#follow_up`, `#events`, and `#run` now drain through
+  `agent_settled` instead of stopping at the first `agent_end`. Since pi
+  0.80.4, `agent_end` marks only one low-level run and may be followed by an
+  automatic retry, compaction retry, or queued continuation; stopping there
+  could unsubscribe early and silently drop the final response events.
+
+### Changed
+- The block form of `Session#follow_up` now uses pi's streaming-aware `prompt`
+  command, so sequential follow-ups start when the session is idle while
+  the blockless form remains a direct, queue-only `follow_up` RPC command for
+  active runs. High-level streams are now single-flight per session because
+  pi events have no run IDs; overlapping streams raise `SessionError` instead
+  of potentially consuming another run's `agent_settled` event.
+
 ## [0.1.18] - 2026-07-21
 
 ### Added

data/README.md

@@ -13,7 +13,7 @@ building interactive agent UIs (web, TUI) on top of pi.
 ## Requirements
 
 - Ruby 3.3+
-- `pi` on `PATH` (install via `npm i -g @earendil-works/pi-coding-agent`)
+- `pi` 0.80.4+ on `PATH` (install via `npm i -g @earendil-works/pi-coding-agent`)
 - This gem is pinned against pi `0.81.1`; other versions may work but are not verified.
 
 ## Installation
@@ -47,8 +47,10 @@ end
 A pi RPC process hosts one session, so there is no create/select step —
 `PiAgent.session` spawns `pi --mode rpc` and the session *is* that process.
 
-`prompt` yields each [`Event`](lib/pi_agent/event.rb) until the agent
-finishes (`agent_end`). Without a block it returns an `Enumerator`:
+`prompt` yields each [`Event`](lib/pi_agent/event.rb) until the agent fully
+finishes (`agent_settled`). Unlike `agent_end`, this includes any automatic
+retry, compaction retry, or queued continuation. Without a block it returns
+an `Enumerator`:
 
 ```ruby
 PiAgent.session do |session|
@@ -79,9 +81,10 @@ Other session methods:
 `set_model` accepts either `set_model("anthropic/claude-sonnet-4-5")` or
 `set_model("anthropic", "claude-sonnet-4-5")`.
 
-A `prompt` streams one agent cycle (`agent_start`..`agent_end`). A message
-queued with `follow_up` runs in a *later* cycle; pass a block to `follow_up`
-to drain that cycle. Like `prompt`, it yields each `Event` until `agent_end`:
+A `prompt` streams the complete session-level run
+(`agent_start`..`agent_settled`). Pass a block to `follow_up` for a sequential
+follow-up that starts immediately when idle (or queues when an agent is
+already running) and drains each `Event` through `agent_settled`:
 
 ```ruby
 PiAgent.session do |session|
@@ -90,14 +93,27 @@ PiAgent.session do |session|
 end
 ```
 
-The block form is race-free: `follow_up` subscribes to the event stream
-*before* sending the message, so none of the cycle's events are missed.
+The block form is race-free: `follow_up` subscribes to the event stream before
+sending a `prompt` with pi's `streamingBehavior: "followUp"`, so none of the
+cycle's events are missed. Use it only after the previous high-level stream has
+settled; pi events have no run IDs, so a session permits only one high-level
+event stream at a time. While a stream is active, use blockless `follow_up` to
+queue a continuation—the active stream will include it through
+`agent_settled`. The block form accepts plain agent input, not slash commands.
+
+Pi emits `agent_end` after each low-level agent run, but may then retry,
+compact and retry, or process queued continuations. It emits
+`agent_settled` only when no automatic work remains, so high-level streams
+use that as their completion boundary. Upstream added the RPC event in pi
+0.80.4; it is available in this gem's pinned pi 0.81.1.
 
 `events` is a lower-level, prompt-less drain of the same stream. Because it
 subscribes lazily when iteration begins, it only works when you subscribe
 *before* the cycle starts — e.g. begin iterating it from a thread, then
 trigger the cycle. For the common follow-up case, prefer the block form
-above.
+above. `prompt`, block-form `follow_up`, and `events` are single-flight on a
+session; starting another before the current stream settles raises
+`PiAgent::SessionError` rather than consuming an unrelated settlement event.
 
 ### Images
 

data/lib/pi_agent/event.rb

@@ -6,12 +6,13 @@ module PiAgent
   # dedicated accessor yet.
   #
   # Event types are exposed as Ruby symbols (e.g. `:text_delta`,
-  # `:agent_end`) matching the upstream protocol's `type` field.
+  # `:agent_settled`) matching the upstream protocol's `type` field.
   class Event
     # Event types that terminate a single prompt's event stream.
-    # `agent_end` fires when the agent finishes processing the current
-    # prompt cycle; we stop iterating then.
-    TERMINAL_TYPES = %i[agent_end].freeze
+    # `agent_end` only finishes one low-level run; retries, compaction, or
+    # queued continuations may follow. `agent_settled` is emitted once all
+    # automatic work has finished.
+    TERMINAL_TYPES = %i[agent_settled].freeze
 
     attr_reader :raw, :type
 

data/lib/pi_agent/session.rb

@@ -13,12 +13,12 @@ module PiAgent
   # A pi RPC process hosts exactly one session, so there is no
   # create/select step — the Session *is* the running pi process.
   #
-  # v1 limitation: `prompt` streams one agent cycle (agent_start..agent_end).
-  # A message queued with `follow_up` runs in a later cycle; pass a block to
-  # `follow_up` to drain that cycle race-free (it subscribes before sending).
-  # `events` is a prompt-less drain of the same stream for when you have
-  # already subscribed before the cycle starts. Bidirectional extension UI
-  # is not yet surfaced here.
+  # `prompt` streams until the session-level run settles, including retries,
+  # automatic compaction retries, and queued continuations. A message queued
+  # with blockless `follow_up` runs after an active agent; pass a block to
+  # submit it as a streaming-aware prompt and drain it race-free. `events` is
+  # a prompt-less drain for when you have already subscribed before processing
+  # starts.
   class Session
     # Max time to wait for the next event before assuming the agent stalled.
     DEFAULT_EVENT_TIMEOUT = 300
@@ -29,11 +29,14 @@ module PiAgent
 
     def initialize(client)
       @client = client
+      @stream_state_mutex = Mutex.new
+      @event_stream_active = false
     end
 
-    # Submit a user prompt. With a block, yields each Event until the
-    # agent finishes (agent_end), then returns self. Without a block,
-    # returns an Enumerator of Events.
+    # Submit a user prompt. With a block, yields each Event until the agent
+    # fully settles (agent_settled), then returns self. This includes any
+    # automatic retry, compaction retry, or queued continuation. Without a
+    # block, returns an Enumerator of Events.
     #
     # `images` accepts PiAgent::Image objects, file path strings, or
     # raw ImageContent hashes — in any mix.
@@ -47,8 +50,8 @@ module PiAgent
     end
 
     # Drain the event stream without submitting a new prompt. With a block,
-    # yields each Event until the cycle finishes (agent_end) and returns
-    # self; without a block, returns an Enumerator of Events.
+    # yields each Event until the run fully settles (agent_settled) and
+    # returns self; without a block, returns an Enumerator of Events.
     #
     # The subscription is established lazily, when iteration begins — so any
     # cycle triggered *before* you call `events` may have already emitted
@@ -76,12 +79,12 @@ module PiAgent
 
     # Queue a follow-up message, delivered only after the agent stops.
     #
-    # Without a block this is fire-and-forget: it queues the message and
-    # returns self. With a block it drains the resulting agent cycle
-    # race-free — the subscription is established *before* the message is
-    # sent, so no events are missed — yielding each Event until agent_end
-    # and returning self. Prefer the block form to consume a follow-up;
-    # the standalone `events` drain only works if you subscribe first.
+    # Without a block this maps to pi's raw `follow_up` command: it only queues
+    # the message and returns self, so call it while an agent run is active.
+    # With a block it uses pi's streaming-aware `prompt` command, which starts
+    # a run when idle or queues a follow-up when busy. The subscription is
+    # established before sending, then yields through agent_settled and returns
+    # self. Prefer this form for a sequential, consumable follow-up.
     def follow_up(message, images: nil, event_timeout: DEFAULT_EVENT_TIMEOUT, &block)
       params = message_params(message, images)
       unless block
@@ -89,7 +92,12 @@ module PiAgent
         return self
       end
 
-      event_stream("follow_up", params, event_timeout: event_timeout).each(&block)
+      if message.start_with?("/")
+        raise SessionError, "Block-form follow_up does not support slash commands; use prompt instead"
+      end
+
+      params[:streamingBehavior] = "followUp"
+      event_stream("prompt", params, event_timeout: event_timeout).each(&block)
       self
     end
 
@@ -280,17 +288,36 @@ module PiAgent
     # iteration of the returned Enumerator so cleanup is deterministic.
     def subscribed_stream(event_timeout:, &before_pump)
       Enumerator.new do |yielder|
-        queue = Queue.new
-        handle = @client.subscribe { |msg| queue << msg }
+        claim_event_stream!
+
+        handle = nil
         begin
+          queue = Queue.new
+          handle = @client.subscribe { |msg| queue << msg }
           before_pump&.call
           pump_events(queue, yielder, event_timeout)
         ensure
-          @client.unsubscribe(handle)
+          @client.unsubscribe(handle) if handle
+          release_event_stream
         end
       end
     end
 
+    def claim_event_stream!
+      claimed = @stream_state_mutex.synchronize do
+        next false if @event_stream_active
+
+        @event_stream_active = true
+      end
+      return if claimed
+
+      raise SessionError, "Another event stream is active; queue with blockless follow_up or wait for it to settle"
+    end
+
+    def release_event_stream
+      @stream_state_mutex.synchronize { @event_stream_active = false }
+    end
+
     def pump_events(queue, yielder, event_timeout)
       loop do
         msg = queue.pop(timeout: event_timeout)

data/lib/pi_agent/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module PiAgent
-  VERSION = "0.1.18"
+  VERSION = "0.2.0"
 
   # Pinned upstream pi-coding-agent version this gem is verified against.
   # See: https://www.npmjs.com/package/@earendil-works/pi-coding-agent

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pi-agent-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.2.0
 platform: ruby
 authors:
 - chagel