phronomy 0.2.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e4dd11eb68b4f8d9f1eb9b75630a21424ee2d5c32035e2be9f9d8c34318feee
-  data.tar.gz: ba85c6000643e00d6bc20298385728cc67df70b17f3542b439f516b4a23e92e5
+  metadata.gz: 9bb874213c4687c9021be3c78d8972218ed56980cfff777a624311ce476d7314
+  data.tar.gz: ab3017e56357b057943d31a557e9e1cd12555ec13924fbee92c6f0f7791c9bd1
 SHA512:
-  metadata.gz: 1086a00d3ee1957b00954ac0a1ea70464c7e873e0cb873e23e53f27a38972d9a2bacca90204742c4c2c6cff90a3fa7972984ef2f16431187d5aa050ba4989ac3
-  data.tar.gz: 8728503fb317f3ce9f05624d648e8080001cac7096898bd5ff2c95c736a040159a42d7ce26eebb28451afd367331d7a50fbe26ce37bf879d20a2de337247a76d
+  metadata.gz: e3d71a750858fda7910addd2ea8de1a3b907e746a247635d0b7467b4ffb5cf1ca970e74a08118b58e950c5843f756462d87a324331d23f50720067a83bb87590
+  data.tar.gz: 5ce1868de692cd6807c910f3d4669791307564c5f3dc58055c82c4c0737e3696c0d5b1050e7b85f1aba30b1e6309c11e66fcbf7ffc4f9f6c63f3970b5bce2d52

data/CHANGELOG.md

@@ -7,6 +7,92 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2026-05-18
+
+### Removed
+
+- **`Phronomy::Memory` module fully removed**: `ConversationManager`, all
+  `Storage` backends (InMemory, ActiveRecord), all `Retrieval` strategies
+  (Recent, Semantic, Composite), and all `Compression` helpers (ToolOutputPruner,
+  Summary) have been deleted. Conversation history is now the responsibility of
+  the calling application — pass prior messages via `config[:messages]`
+  (`Array<RubyLLM::Message>`) and receive the updated array in `result[:messages]`.
+- **`Phronomy::StateStore` module fully removed**: `InMemory`, `ActiveRecord`,
+  `Redis`, and `FileSystem` state-store backends have been deleted. The Workflow
+  halted-state object is now returned directly from `invoke` and `send_event`
+  and must be stored by the caller if resumption is needed.
+- **`Phronomy::Configuration#default_state_store` removed**: No longer meaningful
+  without a built-in state store.
+- **`Phronomy::Configuration#default_memory` / `#memory_async` / `#memory_job_queue` removed**:
+  No longer meaningful without the Memory module.
+- **Rails integration removed**: `Railtie` initializers for `AgentJob` and
+  `acts_as_phronomy_message` no longer load. The `rails/` and `active_record/`
+  directories have been deleted.
+- **`Phronomy::Actor` and `Phronomy::ThreadActorRegistry` deleted**: The Active
+  Object pattern implementation (`actor.rb`, `thread_actor_registry.rb`) has been
+  removed. It provided synchronous blocking only (no true async) and was
+  architecturally inconsistent with the `WorkflowRunner` halt/resume model. All
+  thread coordination now uses plain `Mutex` where needed.
+- **`Phronomy.configuration.max_actors` removed**: The configuration option is no
+  longer meaningful without `ThreadActorRegistry`.
+
+### Changed
+
+- **`Agent::Base#invoke` and `#stream`** no longer route execution through a
+  per-thread Actor. Both methods now call `_invoke_impl` / `_stream_impl` directly
+  on the calling thread.
+- **`Memory::Storage::InMemory`** now stores all thread data in an instance-level
+  `Hash` instead of `Thread.current` thread-local storage. The class-level
+  `THREAD_DATA_KEY` constant has been removed. `with_thread_lock` uses a
+  per-thread-id `Mutex` to preserve concurrent-compaction safety (issue #44).
+- **`StateStore::InMemory`** now stores state in an instance-level `Hash`.
+  The `THREAD_DATA_KEY` constant has been removed.
+- **`VectorStore::RedisSearch`** uses a `Mutex` for `ensure_index!` and `clear`
+  instead of an Actor, preserving the thread-safety invariant on `@index_created`.
+- **`Tool::McpTool::StdioTransport`**, **`Tracing::LangfuseTracer`**,
+  **`TrustPipeline`**, and **`Memory::Retrieval::Semantic`** no longer hold a
+  dedicated Actor instance. All operations execute directly on the calling thread.
+- **`PIIPatternDetector` — `:my_number` replaced by `:ssn`** ([#77]): The built-in PII
+  detector now checks for US Social Security Numbers (`\b\d{3}-\d{2}-\d{4}\b`) instead
+  of Japanese My Numbers. The JIS X 0076 check-digit validation and `my_number_valid?`
+  helper have been removed. Category key renamed from `:my_number` to `:ssn`.
+- **`PIIPatternDetector` — phone pattern updated to international format** ([#77]):
+  The `:phone` pattern now matches 3-digit area code + 3–4-digit exchange + 4-digit
+  subscriber number with optional E.164 country-code prefix
+  (`(?:\+\d{1,3}[.\- ]?)?\(?\d{3}\)?[.\- ]?\d{3,4}[.\- ]?\d{4}\b`),
+  replacing the previous Japan-specific pattern.
+
+### Fixed
+
+- **`RubyLLM::Providers::OpenAI#handle_error_chunk` — `NoMethodError` on single-line SSE error chunks**:
+  Some models (e.g. Qwen running via LM Studio) return SSE error events as a
+  single line (`data: {...}`) without a preceding `event:` line. The upstream
+  implementation called `chunk.split("\n")[1].delete_prefix(...)`, which raised
+  `NoMethodError: undefined method 'delete_prefix' for nil` when the second
+  element was absent. A monkey-patch in `lib/phronomy/ruby_llm_patches.rb` guards
+  against this by returning an empty string when the split result has fewer than
+  two elements.
+- **`README` — stale Memory API examples** ([#76]): All references to the
+  non-existent `WindowMemory`, `ActiveRecordMemory`, `SemanticMemory` classes and
+  `load_messages` / `memory_compression` API have been replaced with the correct
+  `ConversationManager`-based API.
+- **`README` — `PIIPatternDetector` comment** ([#77]): Inline comment updated to
+  `# Detect SSNs, credit cards, emails, and phone numbers`.
+- **`README` — Configuration block markdown** ([#80]): The `max_actors` Note block
+  was incorrectly placed inside the Ruby code fence; moved outside so it renders
+  as a blockquote.
+- **`README` — `Guardrails` stability label** ([#76]): Changed from `Stable` to `Beta`
+  to reflect that the built-in detector patterns may evolve.
+- **`CHANGELOG` — stale entries** ([#78]): Removed the orphaned `[Unreleased]` section
+  describing a never-released API, and replaced a forward `"As of 0.3.0"` reference
+  with future-tense wording.
+- **`McpTool` — YARD class comment** ([#79]): Updated to document both the
+  `stdio://` and `http://`/`https://` transport schemes.
+- **`README` — `max_actors` configuration reference** ([#80]): Added `c.max_actors`
+  example and LRU eviction note to the Configuration section.
+
+---
+
 ## [0.2.2] - 2026-05-17
 
 ### Fixed
@@ -61,8 +147,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`WorkflowRunner` — state_machines fully drives execution** (architecture overhaul).
   Previously `state_machines` was used only for post-hoc transition validation;
   the next-node was calculated by Phronomy internally (`resolve_next_node`).
-  As of 0.3.0, all state transition decisions — including guard evaluation for
-  routing events — are delegated entirely to `state_machines`.
+  After this change, all state transition decisions — including guard evaluation for
+  routing events — will be delegated entirely to `state_machines`.
   - `PhaseTracker` now exposes `attr_accessor :context` so guard lambdas can
     access the `WorkflowContext` via `m.context`.
   - Guard bridge pattern: `if: ->(m) { guard_proc.call(m.context) }`.
@@ -87,34 +173,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## [Unreleased]
-
-### Added
-
-- **`Phronomy::Graph::Context`** module — canonical module for defining workflow
-  context classes (replaces the removed `Phronomy::Graph::State`).
-- **`Phronomy::Graph.register_context_class`** — registers context classes for
-  deserialization from external stores (Redis, DB).
-- **`Phronomy::Workflow.define`** DSL — primary high-level API for declaring
-  stateful workflows (`state`, `wait_state`, `event`, `after`, `initial`).
-- **`Phronomy::Graph::WorkflowRunner`** — state-machine execution engine backing
-  the Workflow DSL. Replaces the removed `CompiledGraph`.
-- **`app.send_event(event, config:)`** — event-driven resume for workflows halted
-  at a `wait_state`.
-- **`state.halted?`** — returns `true` when the workflow is paused at a `wait_state`.
-- **`state.phase`** — single source of truth for execution state.
-
-### Removed
-
-- `Phronomy::Graph::StateGraph` / `CompiledGraph` — use `Phronomy::Workflow.define`.
-- `Phronomy::Graph::State` — use `Phronomy::Graph::Context`.
-- `Phronomy::Graph.register_state_class` — use `register_context_class`.
-- `state.current_nodes` / `state.halted_before` — use `state.phase` / `state.halted?`.
-- `compiled.interrupt_before` / `compiled.interrupt_after` — use `wait_state` + `event`.
-- `compiled.resume` — use `app.send_event`.
-
----
-
 ## [0.2.0] - 2026-05-13
 
 ### Added

data/README.md

@@ -1,7 +1,7 @@
 # Phronomy
 
 **Phronomy** is a Ruby AI agent framework inspired by open-source AI agent frameworks.  
-It provides composable building blocks — Workflows, Agents, and Memory — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
+It provides composable building blocks — Workflows, Agents, Tools, Guardrails, RAG, and Tracing — all powered by [RubyLLM](https://github.com/crmne/ruby_llm) for LLM abstraction.
 
 ## Features
 
@@ -13,21 +13,17 @@ It provides composable building blocks — Workflows, Agents, and Memory — all
 |---|---|
 | **Workflow** — Stateful, branching workflows with wait_state/send_event | Stable |
 | **Workflow Parallel Node** — Concurrent branches via application-level threads | Beta |
-| **Agent** — ReAct-style tool-calling agents with memory and guardrails | Stable |
+| **Agent** — ReAct-style tool-calling agents with guardrails and conversation history | Stable |
 | **Before-Completion Hook** — Three-tier LLM parameter injection | Stable |
-| **Memory** — Window, summary, ActiveRecord-backed, semantic, and composite memory | Stable |
-| **Memory Compression** — Automatic summarisation and tool-output pruning | Beta |
 | **Context Management** — Token budget calculation, estimation, and pruning | Stable |
 | **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores | Beta |
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
 | **TrustPipeline** — Self-review loop and confidence gate (citations are LLM-self-reported) | Experimental |
-| **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Stable |
+| **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
 | **Tracing** — Pluggable span-based observability | Stable |
-| **StateStore** — Persist graph state to memory, ActiveRecord, Redis, or file system | Stable |
 | **MCP Tool** — Model Context Protocol server integration | Beta |
-| **Rails integration** — `AgentJob`, `acts_as_phronomy_message`, and generators | Beta |
 
 ## Installation
 
@@ -49,7 +45,7 @@ For Rails apps, run the install generator after bundling:
 rails generate phronomy:install
 ```
 
-This creates an initializer and the required database migrations.
+This creates a configuration initializer.
 
 ## Quick Start
 
@@ -99,8 +95,6 @@ app = Phronomy::Workflow.define(ReviewContext) do
   event :reject,  from: :awaiting_approval, to: :write
 end
 
-Phronomy.configure { |c| c.default_state_store = Phronomy::StateStore::InMemory.new }
-
 # First run — halts at :awaiting_approval
 state = app.invoke({ draft: "" }, config: { thread_id: "doc-1" })
 puts "Halted: #{state.halted?}"   # => true
@@ -160,7 +154,7 @@ agent.add_input_guardrail(NoSensitiveDataGuardrail.new)
 ### Built-in Guardrails — PII and prompt injection detection
 
 ```ruby
-# Detect credit cards, SSNs, emails, and phone numbers automatically
+# Detect SSNs, credit cards, emails, and phone numbers
 agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PIIPatternDetector.new)
 
 # Block common prompt-injection attempts
@@ -332,35 +326,28 @@ search_tool = Phronomy::Tool::McpTool.from_server(
 )
 ```
 
-### Rails — ActiveRecord persistence
-
-```ruby
-# In your migration (generated by rails generate phronomy:install):
-# create_table :phronomy_messages ...
-# create_table :phronomy_states ...
+### Conversation History — passing prior messages
 
-class PhronomyMessage < ApplicationRecord
-  acts_as_phronomy_message
-end
+Phronomy does not manage conversation history internally. Instead, the application owns the
+message array and passes it in via `config[:messages]`:
 
-# config/initializers/phronomy.rb
-Phronomy.configure do |c|
-  c.default_state_store = Phronomy::StateStore::ActiveRecord.new(
-    model_class: PhronomyState  # AR model backed by phronomy_states table
-  )
-end
-
-# Use in a controller:
-agent = ResearchAgent.new
-result = agent.invoke(
-  params[:message],
-  config: {
-    thread_id: "user_#{current_user.id}",
-    memory:    PhronomyMessage.phronomy_memory
-  }
+```ruby
+# First turn
+result1 = MyAgent.new.invoke("Hello! I'm Alice.", config: { thread_id: "session-1" })
+prior_messages = result1[:messages]   # Array<RubyLLM::Message>
+
+# Second turn — pass prior messages so the agent has context
+result2 = MyAgent.new.invoke(
+  "What is my name?",
+  config: { messages: prior_messages, thread_id: "session-1" }
 )
+puts result2[:output]   # => "Your name is Alice."
 ```
 
+`result[:messages]` contains the complete message history after each invocation.
+Persist it however suits your application (in-memory hash, Redis, ActiveRecord, etc.).
+
+
 ## Configuration
 
 ```ruby
@@ -368,9 +355,7 @@ Phronomy.configure do |c|
   c.default_model       = "gpt-4o-mini"
   c.recursion_limit     = 25
   c.tracer              = Phronomy::Tracing::NullTracer.new
-  c.default_state_store = Phronomy::StateStore::InMemory.new  # optional
-  c.memory_compression  = []                                   # optional; Array of compressors
-  c.before_completion   = nil                                  # optional; global hook lambda
+  c.before_completion   = nil   # optional; global hook lambda
 end
 ```
 
@@ -402,24 +387,6 @@ budget = Phronomy::Context::TokenBudget.new(
 )
 ```
 
-### Budget-aware Memory
-
-Pass a budget to `load_messages` and only the newest messages that fit are returned:
-
-```ruby
-memory = Phronomy::Memory::WindowMemory.new
-messages = memory.load_messages(thread_id: "t1", token_budget: budget)
-```
-
-`ActiveRecordMemory` also accepts `pruner:` to truncate oversized tool results:
-
-```ruby
-memory = Phronomy::Memory::ActiveRecordMemory.new(
-  model_class: PhronomyMessage,
-  pruner: Phronomy::Memory::Compression::ToolOutputPruner.new(max_chars: 4000)
-)
-```
-
 ### Agent DSL extensions
 
 ```ruby
@@ -430,59 +397,8 @@ class MyAgent < Phronomy::Agent::Base
 end
 ```
 
-`Agent::Base#invoke` builds a `TokenBudget` automatically and passes it to
-`memory.load_messages`.  When the model is not in the registry the budget is
-silently skipped.
-
-### SemanticMemory
-
-Embedding-based retrieval of relevant past messages:
-
-```ruby
-semantic = Phronomy::Memory::SemanticMemory.new(
-  embedding_model: "text-embedding-3-small",
-  k: 10
-)
-messages = semantic.load_messages(thread_id: "t1", query: "user's current question")
-```
-
-### Composite retrieval
-
-Merge multiple retrieval strategies within a shared `ConversationManager`:
-
-```ruby
-composite_retrieval = Phronomy::Memory::Retrieval::Composite.new(
-  sources: [
-    { retrieval: Phronomy::Memory::Retrieval::Recent.new(k: 5),    weight: 0.4 },
-    { retrieval: Phronomy::Memory::Retrieval::Semantic.new(k: 10), weight: 0.6 }
-  ]
-)
-
-manager = Phronomy::Memory::ConversationManager.new(
-  storage:   Phronomy::Memory::Storage::InMemory.new,
-  retrieval: composite_retrieval
-)
-```
-
-### Memory Compression
-
-Automatically shrink conversation history before it reaches the LLM.
-
-```ruby
-# Truncate oversized tool outputs (no LLM call, cheap)
-pruner = Phronomy::Memory::Compression::ToolOutputPruner.new(max_chars: 4000)
-
-# Summarise old messages when history exceeds max_tokens (calls summarizer_model)
-summary = Phronomy::Memory::Compression::Summary.new(
-  max_tokens:       4000,
-  keep:             10,             # always preserve the N most recent messages
-  summarizer_model: "gpt-4o-mini"
-)
-
-Phronomy.configure do |c|
-  c.memory_compression = [pruner, summary]   # applied in order: pruner first, then summary
-end
-```
+`Agent::Base#invoke` builds a `TokenBudget` automatically. When the model is not in the
+registry the budget is silently skipped.
 
 
 ## Examples
@@ -512,7 +428,7 @@ bundle exec ruby NN_example_name/run.rb
 | 12 | `12_prompt_template/` | Advanced prompt templates |
 | 13 | `13_mcp_http_tool/` | HTTP-based MCP tool server |
 | 14 | `14_code_review/` | Automated code review agent |
-| 15 | `15_rails_secure_chat/` | Rails chat with PII guardrails and secure memory |
+| 15 | `15_rails_secure_chat/` | Rails chat with PII guardrails |
 | 16 | `16_before_completion_hook/` | Global/class/instance before_completion hooks |
 | 17 | `17_multi_agent_handoff/` | Hub-and-spoke agent routing via Runner |
 | 18 | `18_rails_agent_job/` | Rails app with AgentJob + ActionCable streaming |

data/lib/phronomy/agent/base.rb

@@ -402,18 +402,25 @@ module Phronomy
       #   +:message+, +:query+, or +:user+ as the text key, plus any template
       #   variables consumed by the configured instructions template.
       # @param config [Hash] runtime options:
-      #   +:memory+     ({Phronomy::Memory::ConversationManager}) — memory backend
+      #   +:messages+   (Array<RubyLLM::Message>)  — conversation history from a previous invocation
       #   +:thread_id+  (+String+)                 — conversation thread identifier
       #   +:user_id+    (+String+, optional)        — caller identity forwarded to the tracer
       #   +:session_id+ (+String+, optional)        — session identity forwarded to the tracer
-      # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+
+      # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
+      #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
+      #   messages: Array }+ when the invocation was suspended awaiting tool approval.
       # @raise [Phronomy::GuardrailError] when an input or output guardrail rejects the value
-      # @example
+      # @example Normal invocation
       #   result = MyAgent.new.invoke("What is Ruby?")
       #   puts result[:output]
+      # @example Suspend / resume flow
+      #   result = agent.invoke("Perform task X")
+      #   if result[:suspended]
+      #     result = agent.resume(result[:checkpoint], approved: true)
+      #   end
+      #   puts result[:output]
       def invoke(input, config: {})
-        thread_id = config[:thread_id]
-        _run_in_thread_actor(thread_id) { _invoke_impl(input, config: config) }
+        _invoke_impl(input, config: config)
       end
 
       # Streaming version of #invoke. Yields {Phronomy::Agent::StreamEvent} objects
@@ -433,23 +440,73 @@ module Phronomy
       def stream(input, config: {}, &block)
         return invoke(input, config: config) unless block
 
-        thread_id = config[:thread_id]
-        _run_in_thread_actor(thread_id) { _stream_impl(input, config: config, &block) }
+        _stream_impl(input, config: config, &block)
       rescue => e
         block&.call(StreamEvent.new(type: :error, payload: {error: e}))
         raise
       end
 
+      # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
+      #
+      # This method reconstructs the conversation state captured at suspension
+      # time, injects the tool result (executed or denied), and continues the
+      # LLM loop until it produces a final answer.
+      #
+      # @param checkpoint [Phronomy::Agent::Checkpoint] the checkpoint returned by
+      #   the suspended #invoke call
+      # @param approved   [Boolean] +true+ to execute the pending tool; +false+
+      #   to inject a denial message and let the LLM handle it gracefully
+      # @param config     [Hash] same runtime options as #invoke
+      # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
+      # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+      def resume(checkpoint, approved:, config: {})
+        checkpoint.thread_id
+
+        # Build a fresh chat with all tools registered.
+        chat = build_chat
+
+        # Restore the full conversation (system + history + user + assistant).
+        checkpoint.messages.each { |msg| chat.messages << msg }
+
+        # Determine the tool result: execute it or inject a denial string.
+        tool_result =
+          if approved
+            tool_instance = chat.tools[checkpoint.pending_tool_name.to_sym]
+            tool_instance ? tool_instance.call(checkpoint.pending_tool_args) : "Tool not found."
+          else
+            "Tool execution denied."
+          end
+
+        # Inject the tool result so the LLM can continue.
+        chat.add_message(
+          role: :tool,
+          content: tool_result.to_s,
+          tool_call_id: checkpoint.pending_tool_call_id
+        )
+
+        # Continue the React loop.
+        response = chat.complete
+
+        output = response.content
+        usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+
+        run_output_guardrails!(output)
+
+        {output: output, suspended: false, messages: chat.messages, usage: usage}
+      end
+
       # Registers a callback that is invoked before executing any tool that has
       # +requires_approval true+ set. The block receives the tool name (String)
       # and the arguments Hash, and must return a truthy value to allow execution.
       # Returning a falsy value causes the tool to return a denial message instead
       # of executing.
       #
-      # When no handler is registered, tools with +requires_approval+ execute
-      # without interruption (backward-compatible behaviour).
+      # When no handler is registered and a tool with +requires_approval+ is
+      # called, #invoke returns a suspended result hash containing a
+      # {Phronomy::Agent::Checkpoint}.  Call #resume to continue execution after
+      # obtaining an approval decision from the user or an external system.
       #
-      # @example
+      # @example Synchronous handler
       #   agent = MyAgent.new
       #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
       # @return [self]
@@ -510,7 +567,6 @@ module Phronomy
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)
 
-          memory = config[:memory]
           thread_id = config[:thread_id]
 
           chat = build_chat
@@ -528,8 +584,8 @@ module Phronomy
             end
           end
 
-          if memory && thread_id
-            msgs = load_from_memory(memory, thread_id: thread_id, query: user_message)
+          msgs = Array(config[:messages])
+          unless msgs.empty?
             message_elements = build_message_elements(msgs)
 
             # Run on_trim: app may call ctx.remove(seqs) to drop messages this turn.
@@ -547,8 +603,7 @@ module Phronomy
                   compact_ctx = Context::CompactionContext.new(
                     message_elements: message_elements,
                     budget: budget,
-                    thread_id: thread_id,
-                    memory: memory
+                    thread_id: thread_id
                   )
                   compact_cb.call(compact_ctx)
                   message_elements = build_message_elements(compact_ctx.result_messages)
@@ -564,8 +619,18 @@ module Phronomy
           context[:messages].each { |msg| chat.messages << msg }
 
           # Wire per-event callbacks to yield StreamEvents.
-          chat.before_tool_call { |tool_call| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tool_call})) }
-          chat.after_tool_result { |tool_result| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tool_result})) }
+          current_tool_call = nil
+          chat.on_tool_call do |tool_call|
+            current_tool_call = tool_call
+            block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tool_call}))
+          end
+          chat.on_tool_result do |tool_result|
+            block.call(StreamEvent.new(type: :tool_result, payload: {
+              tool_call_id: current_tool_call&.id,
+              tool_name: current_tool_call&.name,
+              tool_result: tool_result
+            }))
+          end
 
           # Run before_completion hooks (global → class → instance) before the LLM call.
           run_before_completion_hooks!(chat, config)
@@ -574,8 +639,6 @@ module Phronomy
             block.call(StreamEvent.new(type: :token, payload: {content: chunk.content}))
           end
 
-          save_to_memory(memory, thread_id: thread_id, messages: chat.messages) if memory && thread_id
-
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
 
@@ -587,14 +650,6 @@ module Phronomy
         end
       end
 
-      # Runs +block+ inside the {Phronomy::ThreadActorRegistry} Actor for
-      # +thread_id+. When +thread_id+ is nil the block executes on the calling thread.
-      def _run_in_thread_actor(thread_id, &block)
-        return block.call unless thread_id
-
-        Phronomy::ThreadActorRegistry.for(thread_id).call(&block)
-      end
-
       # Performs a single (non-retried) invocation. Extracted so that #invoke can
       # wrap it in a retry loop without duplicating the LLM interaction logic.
       def invoke_once(input, config: {})
@@ -606,15 +661,13 @@ module Phronomy
           # Run input guardrails before touching the LLM.
           run_input_guardrails!(input)
 
-          memory = config[:memory]
           thread_id = config[:thread_id]
           user_message = extract_message(input)
           chat = build_chat
           budget = build_token_budget
 
-          # Load conversation history from memory.
-          raw_messages = (memory && thread_id) ?
-            load_from_memory(memory, thread_id: thread_id, query: user_message) : []
+          # Load conversation history from config[:messages] (app-managed).
+          raw_messages = Array(config[:messages])
 
           # Assign synthetic 0-based seq numbers for use by trim/compaction callbacks.
           message_elements = build_message_elements(raw_messages)
@@ -636,8 +689,7 @@ module Phronomy
                 compact_ctx = Context::CompactionContext.new(
                   message_elements: message_elements,
                   budget: budget,
-                  thread_id: thread_id,
-                  memory: memory
+                  thread_id: thread_id
                 )
                 compact_cb.call(compact_ctx)
                 message_elements = build_message_elements(compact_ctx.result_messages)
@@ -671,10 +723,23 @@ module Phronomy
           # Run before_completion hooks (global → class → instance) before the LLM call.
           run_before_completion_hooks!(chat, config)
 
-          response = chat.ask(user_message)
-
-          # Persist the updated conversation to memory.
-          save_to_memory(memory, thread_id: thread_id, messages: chat.messages) if memory && thread_id
+          # Register suspension hook for approval-required tools (no-op when a
+          # synchronous on_approval_required handler is already registered).
+          _register_suspension_hook!(chat)
+
+          begin
+            response = chat.ask(user_message)
+          rescue SuspendSignal => signal
+            checkpoint = Checkpoint.new(
+              thread_id: thread_id,
+              messages: chat.messages.dup,
+              pending_tool_name: signal.tool_name,
+              pending_tool_args: signal.args,
+              pending_tool_call_id: signal.tool_call_id
+            )
+            suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
+            next [suspended_result, nil]
+          end
 
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
@@ -832,23 +897,6 @@ module Phronomy
 
       # Load messages from a ConversationManager.
       #
-      # @param memory    [Memory::ConversationManager]
-      # @param thread_id [String]
-      # @param query     [String, nil]
-      # @return [Array]
-      def load_from_memory(memory, thread_id:, query: nil)
-        memory.load(thread_id: thread_id, query: query)
-      end
-
-      # Persist messages to a ConversationManager.
-      #
-      # @param memory    [Memory::ConversationManager]
-      # @param thread_id [String]
-      # @param messages  [Array]
-      def save_to_memory(memory, thread_id:, messages:)
-        memory.save(thread_id: thread_id, messages: messages)
-      end
-
       def build_chat
         opts = {}
         m = self.class.model
@@ -917,6 +965,31 @@ module Phronomy
         (@output_guardrails || []).each { |g| g.run!(output) }
       end
 
+      # Registers an on_tool_call hook on the chat object that raises SuspendSignal
+      # when an approval-required tool is about to be executed and no synchronous
+      # on_approval_required handler has been registered.
+      #
+      # Does nothing when:
+      #   - a synchronous handler is already registered (@approval_handler is set), or
+      #   - none of the agent's tools have requires_approval set.
+      #
+      # @param chat [RubyLLM::Chat]
+      def _register_suspension_hook!(chat)
+        return if @approval_handler
+        return if self.class.tools.none? { |tc| tc.requires_approval }
+
+        chat.on_tool_call do |tool_call|
+          tool_instance = chat.tools[tool_call.name.to_sym]
+          if tool_instance&.requires_approval
+            raise SuspendSignal.new(
+              tool_name: tool_call.name,
+              args: tool_call.arguments,
+              tool_call_id: tool_call.id
+            )
+          end
+        end
+      end
+
       # Builds the final tool class to register with the chat.
       #
       # Two transformations are applied in order: