phronomy 0.20.0 → 0.22.0

data/docs/decisions/015-tool-public-facade-and-rbs-boundary.md

@@ -0,0 +1,184 @@
+# ADR-015: Public Tool Façade, Extension SPI, and RBS Contract Boundary
+
+## Status
+
+Accepted.
+
+## Context
+
+Phronomy has accumulated two related API-maintenance problems:
+
+1. Application-defined Tools are implemented by subclassing the internal-taxonomy
+   name `Phronomy::Agent::Context::Capability::Base`, even though the product
+   concept exposed to users is simply a Tool.
+2. The gem ships almost no RBS signatures, so the distinction between
+   application APIs, extension SPIs, and private implementation objects is not
+   machine-readable.
+
+At the same time, Phronomy already has compatibility mechanisms that must remain
+canonical: runtime behavior, focused contract tests, YARD `@api`
+classification, feature stability documentation, and API snapshots. RBS must not
+become a second specification system that silently promotes internal behavior to
+a compatibility promise.
+
+The LLM call boundary also needs an explicit extension contract. Configuration
+already allows replacing `llm_adapter`, and `LLMAdapter::Base` requires
+implementations of `complete` and `stream`, but those methods were previously
+classified as private. The current Agent pipeline still materializes a
+RubyLLM-shaped chat/runtime object before invoking the adapter; formalizing this
+SPI therefore must not be described as a provider-neutral replacement of the
+whole materialization pipeline.
+
+## Decision
+
+### Public Tool authoring façade
+
+The application-facing Tool authoring name is:
+
+```ruby
+Phronomy::Tool::Base
+```
+
+The existing implementation class remains:
+
+```ruby
+Phronomy::Agent::Context::Capability::Base
+```
+
+`Phronomy::Tool::Base` is an exact constant alias to that same class object. It
+is not a subclass and the implementation source is not moved.
+
+This preserves:
+
+- class identity;
+- Tool DSL class-instance state;
+- built-in Tool inheritance;
+- existing user code using the longer namespace;
+- existing serialization/debugging behavior based on the implementation class
+  name.
+
+Consequently, `Phronomy::Tool::Base.name` intentionally remains
+`"Phronomy::Agent::Context::Capability::Base"`. If a future public contract
+requires the runtime class name itself to become `Phronomy::Tool::Base`, that is
+a separate migration decision.
+
+`Phronomy::Tool` means the authoring API. `Phronomy::Tools` continues to mean
+Phronomy-provided built-in Tool classes.
+
+### Extension dependency direction
+
+Phronomy owns the interfaces that external implementations depend on:
+
+```text
+Phronomy Core ──────→ Phronomy-owned public contract
+External extension ─→ Phronomy-owned public contract
+External extension ─→ extension-specific dependency
+```
+
+External adapters/backends must not need private Runtime execution machinery
+such as EventLoop, FSMSession, AgentInvocation, ExecutionCoordinator, or private
+OffloadPool operation state merely to implement their domain contract.
+
+Synchronous work requiring an operating-system worker Thread is submitted by
+Phronomy to OffloadPool. The caller-facing completion handle is
+`Phronomy::Task`; OffloadPool-specific queue/worker/abandonment state remains
+private execution machinery as defined by ADR-010.
+
+### LLMAdapter SPI
+
+`Phronomy::LLMAdapter::Base` is a Beta extension SPI.
+
+The external implementer contract is centered on:
+
+```ruby
+def complete(chat, message, config: {})
+def stream(chat, message, config: {}, &block)
+```
+
+The adapter or provider client owns provider transport timeout, retry, backoff,
+and rate-limit behavior.
+
+Phronomy owns the asynchronous bridge:
+
+```text
+complete / stream
+       ↓
+complete_async / stream_async
+       ↓
+OffloadPool
+       ↓
+Task
+```
+
+External adapter implementations do not implement or depend on OffloadPool,
+EventLoop, FSMSession, or other Runtime internals.
+
+This SPI is the call boundary around the currently materialized chat/runtime
+object. It does **not** make the entire pipeline provider-neutral. In particular,
+this ADR does not remove `RubyLLMMaterializer`, introduce provider-neutral
+request/response objects, or claim that arbitrary LLM client libraries can
+replace RubyLLM without additional architecture work.
+
+### RBS ownership and scope
+
+RBS is a typed representation of contracts already established by Phronomy. The
+source of API meaning remains the combination of:
+
+```text
+runtime behavior
++ YARD @api classification
++ feature/API documentation
++ focused compatibility/contract tests
+```
+
+RBS describes the resulting type shape. It must not be used in the opposite
+direction to justify making an internal method public.
+
+Initial signatures cover:
+
+- primary application APIs;
+- explicit extension SPIs;
+- stable/common completion and configuration types needed to connect them.
+
+Private implementation classes are not exhaustively signed.
+
+Dynamic/external boundaries may use `untyped` where the framework does not own a
+stable type shape. Phronomy-owned contracts such as Task result flow,
+Persistence SPI methods, IDs/revisions, and documented fixed method arguments
+should be typed where practical.
+
+### Third-party RBS ownership
+
+Phronomy does not vendor placeholder signatures for RubyLLM or other third-party
+gems merely to make its own signatures validate. If a third-party type is not
+available or is too unstable, the Phronomy-owned boundary uses an appropriate
+`untyped` type until an authoritative signature is available.
+
+### Validation and source dependency checks
+
+RBS validation runs in a dedicated CI job so RBS tooling does not change the
+Ruby 3.2 runtime support contract.
+
+RBS verifies type/contract dependency shape. It does not prove Ruby source
+`require` or constant dependency direction. Existing lightweight architecture
+regression specs remain the appropriate place for source/runtime dependency
+rules when such checks are needed.
+
+Steep/full implementation type-checking is not introduced by this ADR.
+
+## Consequences
+
+- Tool authoring becomes shorter without moving the implementation class.
+- Existing Tool definitions remain source-compatible.
+- The alias has a deliberately different user-facing name and runtime
+  `Class#name`; that distinction is documented rather than hidden in API
+  snapshot machinery.
+- `LLMAdapter::Base#complete` and `#stream` become explicit Beta extension
+  contracts while async execution stays framework-owned.
+- RBS can describe external extension boundaries without exposing private
+  Runtime machinery.
+- Public API review gains one additional artifact (`sig/**/*.rbs`) but does not
+  gain a second semantic source of truth.
+- A future provider-neutral LLM architecture, genuine native-async backend SPI,
+  or implementation-class rename requires a separate ADR rather than being
+  smuggled into signature work.

data/docs/features.md

@@ -19,7 +19,9 @@ for production deployments.
 |---|---|
 | **Workflow** — Stateful, branching workflows with `wait_state` and explicit events | Stable |
 | **Agent** — Stateful ReAct-style agents with stable `agent_id`, persistence-backed execution state, canonical history, guardrails, and conversation context | Stable |
+| **Tool authoring façade** — `Phronomy::Tool::Base` is the public authoring name for the existing Capability base class; the legacy namespace remains compatible | Beta |
 | **Unified Persistence** — One durable backend abstraction for Agent state and Workflow `workflow_states`; live Agent/Workflow state remains owned by the active instance/session between durable commits; custom backends implement the documented Backend SPI and repository/transaction semantics | Beta |
+| **LLMAdapter SPI** — `Phronomy::LLMAdapter::Base#complete` / `#stream` define the Beta call-adapter extension boundary; Phronomy owns async/offload wrapping | Beta |
 | **Before-Large-Language-Model (LLM) Input Hook** — Three-tier per-call LLM input customization via `before_llm_input` and `LLMInputPatch` | Stable |
 | **Context Management** — Journal + Context Policy + per-LLM-call Manifest with token-budget-aware selection and protocol-safe Tool Call / Tool message dependencies | Stable |
 | **Filters** — Input/output transformation and blocking via `Filter::Base` | Beta |
@@ -35,7 +37,8 @@ for production deployments.
 |---|---|
 | **Knowledge** — Journal-backed persistent Agent context registered with `knowledge:` / `add_knowledge`, selected per LLM call by Context Policy | Beta |
 | **`VectorStore#size`** — Document count for InMemory, RedisSearch, and Pgvector backends | Beta |
-| **`VectorStore::AsyncBackend`** — Pluggable async VectorStore interface with pool-backed defaults and native-async override points | Beta |
+| **VectorStore async convenience** — `add_async` / `search_async` / `remove_async` / `clear_async` offload the synchronous Backend SPI through Phronomy and return `Task`; native async override is not part of the current Backend SPI | Beta |
+| **Embedding async convenience** — `embed_async` offloads synchronous `embed` through Phronomy and returns `Task` | Beta |
 | **Model Context Protocol (MCP) Tool** — `Phronomy::Tools::Mcp` integration through the official `mcp` gem | Beta |
 | **Agent Tool** — `Phronomy::Tools::Agent.from_agent` exposes a child Agent as a Tool without occupying a worker while waiting | Beta |
 | **Vector Search Tool** — `Phronomy::Tools::VectorSearch` wraps VectorStore and Embeddings adapters | Beta |
@@ -50,6 +53,7 @@ for production deployments.
 | **Agent async events** — `invoke_async(..., on_event:)` and `stream_async(..., on_event:)`; streaming additionally emits `:token` | Beta |
 | **`stream` / `stream_async`** — Event callbacks execute on EventLoop and must return quickly | Beta |
 | **`stream_callback_error_policy`** — Terminal event callback error policy (`:report` / `:fail_task`) | Beta |
+| **Task completion contract** — `Task` is the common caller-facing completion handle for EventLoop/FSMSession lifecycles and OffloadPool work | Beta |
 | **`Task#map`** — Application-level Task result transformation and error propagation | Stable |
 | **CancellationToken** — Cooperative cancellation with explicit `cancel!`, lazy monotonic deadlines, and callback registration | Experimental |
 | **Tool `execution_mode`** — `:cooperative` for short EventLoop-safe work; `:offloaded` for synchronous work that must stay off EventLoop | Experimental |
@@ -80,18 +84,23 @@ compatibility guarantees.
 
 The YARD `@api` classification is independent from Ruby language visibility in
 both directions. `@api public` marks a compatibility contract, but the Ruby
-visibility still follows the intended calling model: ordinary APIs may be
-public, subclass extension helpers may be protected, and constructors use
-Ruby-private `initialize` behind `.new`. `@api private` means "internal/no
-compatibility promise" and does not require a Ruby `private` declaration; some
-internal methods remain Ruby-public because Phronomy components call them
-through explicit receivers.
-
-Persistence Backend SPI methods are a deliberate exception to the ordinary
-application-facing interpretation of `@api public`: they are public extension
-contracts for backend implementers, but application business logic should usually
-interact with Agents/Workflows instead of calling low-level repository operations.
-See [Persistence backend contract](persistence-backends.md).
+visibility still follows the intended calling model. `@api private` means
+"internal/no compatibility promise" and does not require a Ruby `private`
+declaration; some internal methods remain Ruby-public because Phronomy components
+call them through explicit receivers.
+
+`Task` is the caller-facing completion abstraction. Framework components own
+settlement (`complete` / `fail` / `cancel!`); application code observes Tasks via
+`wait_result`, `on_complete`, `map`, and state readers. Operation-wide cancellation
+is requested through the `CancellationToken` accepted by the API that created the
+Task.
+
+Persistence Backend SPI methods, LLMAdapter methods, and other documented
+extension contracts are deliberate exceptions to the ordinary
+application-facing interpretation of `@api public`: they are compatibility
+contracts for implementers. Extension implementations must not depend on Runtime
+private execution objects such as EventLoop/FSMSession/OffloadPool operation
+records.
 
 `Phronomy::StateStore` is no longer a public backend abstraction. Workflow
 durability is provided through `Phronomy::Persistence#workflow_states`; see the

data/docs/getting-started.md

@@ -49,8 +49,12 @@ Install only the backend gems required by your application:
 
 ## Define a Tool and Agent
 
+Use `Phronomy::Tool::Base` as the application-facing authoring API. It is an
+exact alias of the existing `Phronomy::Agent::Context::Capability::Base`, so
+existing Tool definitions using the longer namespace remain compatible.
+
 ```ruby
-class WebSearch < Phronomy::Agent::Context::Capability::Base
+class WebSearch < Phronomy::Tool::Base
   description "Search the web"
   param :query, type: :string, desc: "Search query"
 
@@ -138,6 +142,24 @@ task = agent.invoke_async("Hello")
 result = task.wait_result
 ```
 
+Both `invoke` and `invoke_async` can receive public Agent events through either
+an `on_event:` listener or a block. A block is convenient when the listener is
+local to the call:
+
+```ruby
+task = agent.invoke_async("Hello") do |event|
+  puts event.payload[:output] if event.type == :done
+end
+```
+
+Use `on_event:` when the listener already exists as a callable. Do not provide
+both `on_event:` and a block to the same invocation.
+
+`Phronomy::Task` is the common caller-facing completion handle for asynchronous
+Phronomy work. Logical lifecycle progress is driven by EventLoop/FSMSession;
+synchronous work that must execute away from EventLoop is submitted to
+OffloadPool. Both paths expose completion as a `Task`.
+
 `Task#wait_result` is for an external caller. Do not block EventLoop waiting for
 a Task that can only complete through that same EventLoop.
 
@@ -150,13 +172,12 @@ end
 ```
 
 ```ruby
-task = agent.stream_async(
-  "Explain the design",
-  on_event: ->(event) { puts event.payload if event.type == :token }
-)
+task = agent.stream_async("Explain the design") do |event|
+  puts event.payload if event.type == :token
+end
 ```
 
-Streaming callbacks execute on EventLoop and therefore should return quickly.
+Agent event callbacks execute on EventLoop and therefore should return quickly.
 
 ## Human-in-the-loop approval
 
@@ -274,18 +295,15 @@ workflow = Phronomy::Workflow.define(AnswerContext) do
   entry :asking, ->(ctx) {
     thread_id = ctx.thread_id
 
-    my_agent.invoke_async(
-      ctx.question,
-      on_event: ->(event) {
-        next unless event.type == :done
-
-        workflow.signal(
-          thread_id: thread_id,
-          event: :answer_ready,
-          payload: {answer: event.payload[:output]}
-        )
-      }
-    )
+    my_agent.invoke_async(ctx.question) do |event|
+      next unless event.type == :done
+
+      workflow.signal(
+        thread_id: thread_id,
+        event: :answer_ready,
+        payload: {answer: event.payload[:output]}
+      )
+    end
 
     ctx
   }