pi-agent-rb 0.1.17 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c9ee93c9a0be8b3186fdfed49511db3d50c4c1a72c0f3058d5ba745d65f1cfa
-  data.tar.gz: 8c046616ce13be91c30e2d34ddcbf6b42badca576187bf65994e0084da71375b
+  metadata.gz: 24f258d02d946aa8752944f4438581126665c94b5ee1253e61c8ebd16ecb6596
+  data.tar.gz: f98727ad546acbc6ea8dee3e2cf52af1cf7694f3875181fdec16c3773fd2e0b7
 SHA512:
-  metadata.gz: 33a6418db510ba841bc2ed974592aba167fcdf44dcb86a54bcc1c046869c9e900caf510457933aea602abf0e647b053c157d5f350109d8613bb4c667c1ce1870
-  data.tar.gz: d742668832dc0ea144d690cfc766125fee9b017d4094339b7bf46164155e4d248fb05f787dd306fc39f2f1eba838b060d5d44cd31c7c3f5f3d0b00f36dcd924d
+  metadata.gz: 32e5f3a97a2f6b890a1f1c8aecdd59125a4588b6879e815471ad2257942d291a6ccc5c46d32e4bd04abe13020e8ccb4cde1643dfb9230bea9e7974bb8008513f
+  data.tar.gz: '099b2a2267bd8a7212c6d90473775d54a22e7d80982471682ae339cd01875383561bd77364f9f9fe54c8a9514ae26023811ec24a8bcbe1b2dd035f1412f30377'

data/CHANGELOG.md

@@ -7,6 +7,58 @@ 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
+- `Session#available_thinking_levels`, wrapping the upstream
+  `get_available_thinking_levels` RPC command (added in pi `0.81.0`).
+  Returns the thinking levels supported by the current model as an array of
+  strings (e.g. `["off", "low", "medium", "high"]`), or `["off"]` for a
+  model without reasoning support. Complements the existing `set_thinking`.
+
+### Changed
+- Bumped pinned upstream `pi-coding-agent` version to `0.81.1` (from
+  `0.80.10`), covering both `0.81.0` and `0.81.1`.
+  - `0.81.0` adds local llama.cpp model management, full provider
+    extensions (extensions can register complete pi-ai providers), Qwen
+    Token Plan built-in providers, and expanded usage accounting for
+    tools, compaction, and branch summaries. The one change touching the
+    JSONL RPC surface this gem drives is the new
+    `get_available_thinking_levels` command, now exposed as
+    `Session#available_thinking_levels`.
+  - `0.81.1` adds resilient compaction/branch summaries that retry
+    transient provider failures, emitting new `summarization_retry_*`
+    lifecycle events (`summarization_retry_scheduled`,
+    `summarization_retry_attempt_start`, `summarization_retry_finished`) to
+    RPC consumers, plus checksummed release source archives. The retry
+    events flow through `PiAgent::Event` transparently — it preserves the
+    native payload on `#raw` and exposes `#type` as a symbol — so no gem
+    change is needed to consume them.
+  - No RPC commands or responses changed shape across either release, so
+    the rest is provider/model/accounting concerns that leave the existing
+    contract unchanged.
+
 ## [0.1.17] - 2026-07-17
 
 ### Changed

data/README.md

@@ -13,8 +13,8 @@ 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`)
-- This gem is pinned against pi `0.80.10`; other versions may work but are not verified.
+- `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|
@@ -70,7 +72,7 @@ end
 Other session methods:
 
 - Prompting: `steer`, `follow_up`, `events`, `abort`
-- Model: `set_model`, `cycle_model`, `available_models`, `set_thinking`
+- Model: `set_model`, `cycle_model`, `available_models`, `set_thinking`, `available_thinking_levels`
 - State: `get_state`, `messages`, `last_assistant_text`, `session_stats`
 - Context: `compact`
 - Sessions: `new_session`, `switch_session`, `fork`, `clone_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
 
@@ -138,6 +146,13 @@ module PiAgent
       self
     end
 
+    # Thinking levels supported by the current model, as an array of strings
+    # (e.g. ["off", "low", "medium", "high"]). Returns ["off"] for a model
+    # without reasoning support.
+    def available_thinking_levels
+      request_data("get_available_thinking_levels").fetch("levels", [])
+    end
+
     def get_state
       @client.request("get_state").value!(timeout: DEFAULT_ACK_TIMEOUT)
     end
@@ -273,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,9 +1,9 @@
 # frozen_string_literal: true
 
 module PiAgent
-  VERSION = "0.1.17"
+  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
-  SUPPORTED_PI_VERSION = "0.80.10"
+  SUPPORTED_PI_VERSION = "0.81.1"
 end

metadata

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