ask-agent 0.36.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcbe9fc4bae7e7eddc9fc206e35ef22499a9fb3a308bac6d9f48c2d1d2e12f8f
-  data.tar.gz: ae9c72d61a839330d2bbc68b8049fe1e54680f0462d4dee2e886d8377df439b3
+  metadata.gz: e22262139bd8142b9e45f22e831d59360f9465aad8fea93247352591b742d6c3
+  data.tar.gz: 1486719187105e25f794bff150fd9aa59e902096a40c15fdb822b2e7061d9bac
 SHA512:
-  metadata.gz: 7a34904c0d8c0d6397753262d4f3c359674893b5ddab7a85714f8eebf797db0cdd3b6a076ea2c18eb693ad1f2211677e88bf4f4a7f4e2e2f7fe5545892af5062
-  data.tar.gz: d78f87319a5d6b63c22e1bd7d9cacde6fd6306131f746ad5b4166d509acf5dad11b03db7e9fab6f908db752f7a592f2a4dc51fdb13fb4fa30ebc39c193894acb
+  metadata.gz: 2eaacd8c0a7a32392546ccde9d218d271afa22a3a2d1c154bfc3665691060b9cc4e7ab8d658c25eb2b2e79cccb1ad3bbbf10cd65e36c4324e2fc408f8eb8d973
+  data.tar.gz: d9abb9f16f260d5ece0c403346ae0f1cb5a9edadb3e9fad0a2a56fd05c66748eb0070f16efa8441aa55275c5fc1aff724d43f0d4d6809751b932978272563fcf

data/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [0.37.0] — 2026-08-07
+
+### Added
+
+- **Steer — concurrency-safe message injection.**
+  `Session#steer(message, expected_turn_id:)` lets any thread (web, CLI,
+  another agent) inject a message safely:
+  - **`:stale`** — `expected_turn_id` doesn't match the current turn id
+    (the caller was looking at an older state); the message is rejected.
+  - **`:queued`** — a turn is running; the message is held and dispatched
+    as the next user message at the next turn boundary (the loop now
+    resolves each recursive turn's message from a steer source). No more
+    abort-and-retry.
+  - **`:steered`** — the session is idle; the message enters the
+    conversation and the next run processes it. Queued leftovers drain at
+    the next run start.
+  - `Session#turn_id` tracks the running turn (bumped on `TurnStart`);
+    `Session#queued_steers` reports pending messages.
+
+### Fixed
+
+- **No more duplicate tail checkpoints.** The loop persists after every
+  turn and `run()` persists again on the way out, so every run previously
+  appended a redundant checkpoint (seqs 1,2,3 for two turns). `persist!`
+  now skips the checkpoint when the message count and turn count are
+  unchanged — `checkpoint_history` is exact.
+
 ## [0.36.0] — 2026-08-07
 
 ### Added

data/lib/ask/agent/loop.rb

@@ -17,7 +17,7 @@ module Ask
       @max_consecutive_tool_turns = max_consecutive_tool_turns
       end
 
-      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil, tool_call_repair: nil)
+      def run_turn(chat:, message:, tools:, tool_executor:, compactor:, hooks:, event_emitter:, session_id: nil, persist: nil, tool_call_repair: nil, steer_source: nil)
         raise MaxTurnsExceeded if @turn_count >= @max_turns
 
         event_emitter.emit(Events::TurnStart.new)
@@ -157,10 +157,12 @@ module Ask
         # Aborted while tools ran? Skip the follow-up LLM call.
         return response.content.to_s if aborted?(event_emitter)
 
-        # Recursive call — LLM processes tool results
+        # Recursive call — LLM processes tool results. When a steer source
+        # is provided, queued steer messages become the next user message
+        # instead of an empty continuation.
         run_turn(
           chat: chat,
-          message: "",
+          message: steer_source ? steer_source.call.to_s : "",
           tools: tools,
           tool_executor: tool_executor,
           compactor: compactor,
@@ -168,7 +170,8 @@ module Ask
           event_emitter: event_emitter,
           session_id: session_id,
           persist: persist,
-          tool_call_repair: tool_call_repair
+          tool_call_repair: tool_call_repair,
+          steer_source: steer_source
         )
       end
 

data/lib/ask/agent/memory_extractor.rb

@@ -5,8 +5,7 @@ require "json"
 module Ask
   module Agent
     # Extracts durable facts from a finished session's transcript and writes
-    # them to the session's {Memory} — the "learning" half of durable memory
-    # (codex two-phase pattern, phase 1).
+    # them to the session's {Memory} — the "learning" half of durable memory.
     #
     # One LLM call with a structured-output prompt: the model reads the
     # memory-relevant messages and returns a JSON list of durable facts.

data/lib/ask/agent/session.rb

@@ -41,6 +41,13 @@ module Ask
         @pending_mutex = Mutex.new
         @followup_pending = false
         @turn_count = 0
+        # Concurrency-safe steering: turn id bumped at every
+        # TurnStart; steers arriving mid-turn are queued and dispatched at
+        # the next turn boundary.
+        @turn_id = 0
+        @queued_steers = []
+        @steer_mutex = Mutex.new
+        on(Events::TurnStart) { @turn_id += 1 }
         @created_at = Time.now
         @_no_tools_instructed = false
 
@@ -197,6 +204,10 @@ module Ask
           @_no_tools_instructed = true
         end
 
+        # Leftover queued steers from a previous run become user messages
+        # before this run starts.
+        drain_leftover_steers
+
         begin
           @tool_executor.telemetry = @telemetry
 
@@ -210,6 +221,7 @@ module Ask
 	            event_emitter: self,
 	            session_id: @id,
             tool_call_repair: @tool_call_repair,
+            steer_source: method(:drain_one_steer),
 	            persist: @state ? method(:persist!) : nil
 	          )
 
@@ -517,6 +529,20 @@ module Ask
 
       # --- Plan mode ---
 
+      # Pop the next queued steer (called by the loop at each turn
+      # boundary); returns "" when nothing is queued.
+      def drain_one_steer
+        @steer_mutex.synchronize { @queued_steers.shift }.to_s
+      end
+
+      # Move any queued steers left over from a previous run into the
+      # conversation (the session was idle, so they are dispatched now).
+      def drain_leftover_steers
+        while (message = drain_one_steer) != ""
+          @chat.add_message(role: :user, content: message)
+        end
+      end
+
       # Extract durable facts from this session's transcript into memory
       # (memory_learning: true). Best-effort — extraction never breaks the
       # session; failures are swallowed.
@@ -582,6 +608,45 @@ module Ask
         )
       end
 
+      # --- Steer (concurrency-safe message injection) ---
+
+      # @return [Integer] id of the turn currently running (or the last
+      #   completed turn when idle)
+      attr_reader :turn_id
+
+      # Inject a message into the session safely, from any thread (web, CLI,
+      # another agent):
+      #
+      # - **:stale** — the caller's `expected_turn_id` does not match the
+      #   current turn id (the caller was looking at an older state).
+      # - **:queued** — a turn is running; the message is held and dispatched
+      #   as the next user message at the next turn boundary.
+      # - **:steered** — the session is idle; the message is added to the
+      #   conversation and processed by the next run.
+      #
+      # @param message [String]
+      # @param expected_turn_id [Integer, nil] the turn id the caller
+      #   believes is current; nil skips the check
+      # @return [Hash] {status: :stale|:queued|:steered, turn_id: Integer}
+      def steer(message, expected_turn_id: nil)
+        @steer_mutex.synchronize do
+          if expected_turn_id && expected_turn_id != @turn_id
+            return { status: :stale, turn_id: @turn_id }
+          end
+          if @running
+            @queued_steers << message.to_s
+            return { status: :queued, turn_id: @turn_id }
+          end
+        end
+        @chat.add_message(role: :user, content: message.to_s)
+        { status: :steered, turn_id: @turn_id }
+      end
+
+      # @return [Integer] steers queued and not yet dispatched
+      def queued_steers
+        @steer_mutex.synchronize { @queued_steers.size }
+      end
+
       # --- Async (pending) tools ---
 
       # Registers a pending tool call (called by the loop when a tool
@@ -895,7 +960,17 @@ module Ask
           }
         }
         @state.set(@id, payload)
-        @checkpoint_store.checkpoint(@id, payload) if @checkpoints
+        # Checkpoint only when the conversation actually changed since the
+        # last one: the loop persists after every turn and run() persists
+        # again on the way out, so without this check every run would append
+        # a duplicate tail checkpoint.
+        if @checkpoints
+          head = @checkpoint_store.load(@id)
+          head_messages = head ? (head["messages"] || head[:messages] || []) : []
+          head_turn = head ? (head.dig("metadata", "turn_count") || head.dig(:metadata, :turn_count)) : nil
+          unchanged = head_messages.size == payload[:messages].size && head_turn == @turn_count
+          @checkpoint_store.checkpoint(@id, payload) unless unchanged
+        end
       end
 
       def try_auto_meta_agent

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.36.0"
+    VERSION = "0.37.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Kaka Ruto