phronomy 0.13.0 → 0.15.0

data/docs/decisions/004-invoke-timeout-is-not-cancellation.md

@@ -2,74 +2,21 @@
 
 ## Status
 
-Accepted
+Superseded by [ADR-011](011-delegate-transport-policy-to-adapters.md).
 
-## Context
+## Historical decision
 
-`Agent::Base` exposes `invoke_timeout N` as a class-level DSL. When an invocation
-exceeds the timeout, `Phronomy::TimeoutError` is raised to the caller.
+Phronomy previously exposed `Agent::Base.invoke_timeout` as a class-level wait
+boundary. The initial implementation did not stop background work; a later
+implementation attached a cancellation scope to the complete Agent invocation.
 
-The question is: should the timeout also stop the agent's background work?
-
-Ruby's `Timeout.timeout` / `Thread#kill` can interrupt a running thread, but
-doing so is unsafe: it can leave mutexes locked, database connections in a broken
-state, and external API calls mid-flight without cleanup. `Thread#raise` has the
-same hazards because it can interrupt anywhere inside a `rescue`/`ensure` block.
-
-Cooperative cancellation (checking a shared flag periodically) is safe but
-requires every tool, every LLM call, and every framework-internal loop to
-participate — a significant API surface change.
-
-## Decision
-
-`invoke_timeout` is a **wait timeout only**. When the deadline is reached:
-
-- `TimeoutError` is raised in the calling thread.
-- The agent's background thread continues running until it either completes
-  normally or is garbage-collected when the process ends.
-- No cancellation signal is sent to the agent.
-
-This is explicitly documented in the README and in the DSL source.
-
-A proper cooperative cancellation mechanism is tracked in Issue #216
-(`CancellationToken`), which is a separate feature requiring agent, tool, and
-transport layer participation.
-
-## Consequences
-
-**Positive:**
-- No risk of leaving shared resources (DB connections, mutexes, sockets) in a
-  broken state due to forced thread interruption.
-- Implementation is simple: `Timeout.timeout` on the calling side only.
-- The contract is explicit and predictable.
-
-**Negative / Tradeoffs:**
-- Background threads may continue consuming resources (LLM API quota, etc.)
-  after the caller has given up.
-- Users who expect "cancel" semantics from a timeout will be surprised.
-- Proper cancellation requires the `CancellationToken` feature (#216), which
-  has not yet been implemented.
-
-## Extension: PendingOperation#await cooperative cancellation semantics
-
-`BlockingAdapterPool::PendingOperation#await` also supports both `timeout:` and
-`cancellation_token:` parameters. The same non-preemptive rule applies here,
-consistent with ADR-010 (cooperative-first, non-preemptive concurrency model):
-
-1. **No forcible thread termination.** When a `cancellation_token` is cancelled,
-   `CancellationError` is raised to the `await` caller; when the timeout fires,
-   `TimeoutError` is raised instead. In both cases, the underlying worker thread
-   is **not** killed. The worker runs its block to natural completion.
-2. **Cooperative, not preemptive.** Cancellation takes effect only at `await`
-   call sites or at explicit `token.check!` checkpoints inside the submitted
-   block. Code that ignores the token will not be interrupted.
-3. **Timeout scope.** `timeout:` at `await` time is measured from the moment
-   `await` is called. If both submit-time and await-time timeouts are provided,
-   the earlier deadline wins.
-4. **Error propagation.** `CancellationError` (or `TimeoutError`) is raised to
-   the `await` caller; the submitter is responsible for handling it.
-
-These semantics are identical in spirit to the `invoke_timeout` decision above:
-the framework exposes a *wait* boundary, not a hard-kill boundary. Safe resource
-cleanup is the caller's responsibility.
+The API has been removed. An Agent class no longer owns a default invocation
+timeout. Applications that need a deadline for a particular root operation pass
+an `InvocationContext` with `deadline:` or `cancellation_token:`. Those values are
+coordination context supplied by the caller, not an implicit Agent execution
+policy.
 
+LLM transport timeout belongs to RubyLLM or another configured LLM adapter.
+Tool transport timeout belongs to the Tool implementation or its underlying
+client. Phronomy retains generic deadline and cancellation primitives for the
+execution tree it coordinates.

data/docs/decisions/011-delegate-transport-policy-to-adapters.md

@@ -0,0 +1,82 @@
+# ADR-011: Delegate Transport Timeout and Retry to Adapters
+
+## Status
+
+Accepted
+
+## Context
+
+Phronomy accumulated execution-policy settings at several layers:
+
+- `Agent::Base.retry_policy`, which replayed the complete Agent invocation;
+- `Agent::Base.invoke_timeout`, which imposed an Agent-class deadline;
+- `config[:llm_timeout]`, applied outside RubyLLM;
+- Tool `retry_on` and `config[:tool_timeout]`;
+- `max_parallel_tools` and the unused `InvocationContext#provider_limits`.
+
+The policies did not share a reliable resource model. In particular, replaying
+an Agent or Tool can repeat external side effects, and a pool-level timeout does
+not terminate a blocking provider call that is already running. RubyLLM already
+owns LLM request timeout, transient-error retry, backoff, and jitter. Tool
+implementations commonly use clients that own equivalent transport behavior.
+
+## Decision
+
+1. RubyLLM, or another configured LLM adapter, owns LLM transport timeout,
+   retry, backoff, jitter, and provider rate-limit handling.
+2. Phronomy translates final provider errors but does not replay the complete
+   Agent invocation.
+3. Tool implementations or their underlying clients own Tool-specific timeout
+   and retry. Phronomy does not provide a generic Tool replay policy.
+4. Agent classes do not own a default invocation timeout. Callers may pass an
+   `InvocationContext` containing a `deadline` or `cancellation_token` when a
+   specific root operation needs a boundary.
+5. Phronomy retains the timeout mechanisms for boundaries it owns: Workflow
+   actions, authorization evaluation, Orchestrator aggregate waits, Runtime
+   shutdown/drain, and generic concurrency primitives.
+6. Parallel Tool execution is a boolean mode. When enabled, all authorized
+   calls in the intercepted batch are dispatched. Runtime's bounded workers and
+   queues remain the coarse process-protection mechanism.
+7. No resource manager, provider limiter, priority scheduler, or compatibility
+   shim is introduced by this change.
+
+## Consequences
+
+### Positive
+
+- LLM transport behavior has one configuration authority.
+- Agent and Tool side effects are not implicitly replayed by the framework.
+- Timeout behavior is controlled at the layer capable of interrupting or
+  cancelling the underlying I/O safely.
+- Invocation context remains small and contains only values consumed by the
+  execution path.
+- The Agent FSM has one invocation attempt and one error propagation path.
+
+### Tradeoffs
+
+- Applications must configure RubyLLM explicitly when its defaults are not
+  appropriate for production.
+- Custom LLM adapters must document and implement their own transport policy.
+- Tool authors are responsible for idempotency when they choose to retry in a
+  Tool or client.
+- Enabling parallel Tool execution dispatches the complete authorized batch;
+  applications should leave it disabled when unbounded batch fan-out is not
+  acceptable.
+
+## Example
+
+```ruby
+RubyLLM.configure do |config|
+  config.request_timeout = 120
+  config.max_retries = 3
+  config.retry_interval = 0.1
+  config.retry_backoff_factor = 2
+  config.retry_interval_randomness = 0.5
+end
+
+context = Phronomy::InvocationContext.new(
+  deadline: Phronomy::Concurrency::Deadline.in(30)
+)
+
+result = MyAgent.new.invoke("Hello", invocation_context: context)
+```

data/docs/mcp-client.md

@@ -0,0 +1,75 @@
+# MCP client support
+
+Phronomy supports the official `mcp` Ruby SDK **1.x**. MCP SDK 0.x is not supported.
+
+## Transports
+
+`Phronomy::Tools::Mcp.from_server` supports:
+
+- `stdio://...`
+- `http://...`
+- `https://...`
+
+HTTP and SSE support are standard dependencies of Phronomy through `faraday` and
+`event_stream_parser`.
+
+## Input-schema subset
+
+Phronomy intentionally supports a strict subset of JSON Schema 2020-12 for MCP
+Tool inputs.
+
+Supported root keywords:
+
+- `$schema`
+- `type` (`object` only)
+- `properties`
+- `required`
+- `title`
+- `description`
+- `additionalProperties` when omitted or `false`
+
+Supported property types:
+
+- `string`
+- `integer`
+- `number`
+- `boolean`
+
+Supported property keywords:
+
+- `type`
+- `description`
+- `enum`
+- `title`
+
+The following validation keywords are accepted but ignored with a warning:
+
+- `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`
+- `minLength`, `maxLength`, `pattern`, `format`, `default`, `examples`
+
+Unknown keywords, structural composition (`oneOf`, `anyOf`, `allOf`, `$ref`,
+conditionals), arrays, nested objects, and nullable type arrays fail fast with
+`Phronomy::ToolError` rather than silently changing the Tool contract.
+
+When `additionalProperties` is omitted, the remote schema is accepted, but
+Phronomy still exposes and accepts only names declared in `properties`.
+
+`outputSchema` is detected and reported with a warning, but is not validated in
+this phase.
+
+## Errors and cancellation
+
+- JSON-RPC errors raised by the SDK are converted to `Phronomy::ToolError`.
+- MCP Tool results with `isError: true` are returned to the model as Tool error
+  text so the model can correct its arguments.
+- An expired HTTP session is reconnected for future calls. The failed Tool call
+  is not replayed because Tool side effects are not assumed to be idempotent.
+- Cancellation invalidates the current client and transport. The next call creates
+  a new connection, preventing an abandoned SDK worker from sharing the old stdio
+  stream with a new request.
+
+Calls, reconnects, and explicit `close` operations on a Tool instance are
+serialized. `close` synchronously closes the current client and permits a later
+call to reconnect. A transport detached by cancellation is owned by the bounded
+MCP cleanup pool and is drained during Runtime shutdown; `close` does not wait
+for an older detached transport.

data/examples/workflows/agent_event_mapping.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "phronomy"
+require "securerandom"
+
+class GenerationContext
+  include Phronomy::WorkflowContext
+
+  field :prompt
+  field :generation_request_id
+  field :answer
+  field :error_message
+
+  # This is application logic. Phronomy transports the event and payload but
+  # does not decide which Agent invocation is current or where the result lives.
+  def handle_fsm_event(event)
+    request_id = event.payload[:generation_request_id]
+    return :consume unless request_id == generation_request_id
+
+    case event.type
+    when :generation_completed
+      self.answer = event.payload[:agent_result][:output]
+    when :generation_failed
+      self.error_message = event.payload[:error].message
+    end
+    false
+  end
+end
+
+class AnswerAgent < Phronomy::Agent::Base
+  model "gpt-4o-mini"
+  instructions "Answer clearly and briefly."
+end
+
+agent = AnswerAgent.new
+workflow = nil
+
+workflow = Phronomy::Workflow.define(GenerationContext) do
+  initial :generating
+
+  state :generating, action: ->(context) {
+    request_id = context.generation_request_id
+
+    # The Agent Task is intentionally not returned from the entry action.
+    # on_event is the application-level integration channel.
+    agent.invoke_async(
+      context.prompt,
+      on_event: ->(agent_event) {
+        workflow_event =
+          case agent_event.type
+          when :done
+            :generation_completed
+          when :error, :timeout, :cancelled, :approval_required
+            :generation_failed
+          end
+        next unless workflow_event
+
+        workflow.signal(
+          thread_id: context.thread_id,
+          event: workflow_event,
+          payload: {
+            generation_request_id: request_id,
+            agent_result: (
+              agent_event.payload if agent_event.type == :done
+            ),
+            error:
+              agent_event.payload[:error] ||
+              Phronomy::Error.new(
+                "Agent requested Tool approval"
+              )
+          }
+        )
+      }
+    )
+
+    context
+  }
+
+  state :succeeded
+  state :failed
+
+  transition(
+    from: :generating,
+    on: :generation_completed,
+    to: :succeeded
+  )
+  transition(
+    from: :generating,
+    on: :generation_failed,
+    to: :failed
+  )
+  transition from: :succeeded, to: :__finish__
+  transition from: :failed, to: :__finish__
+end
+
+result = workflow.invoke(
+  {
+    prompt: "What is Run-to-Completion?",
+    generation_request_id: SecureRandom.uuid
+  },
+  config: {thread_id: SecureRandom.uuid}
+)
+
+puts(result.answer || result.error_message)

data/examples/workflows/generic_task_event_mapping.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "phronomy"
+
+class ImportContext
+  include Phronomy::WorkflowContext
+
+  field :record_count, default: 0
+  field :error_message
+
+  def handle_fsm_event(event)
+    case event.type
+    when :import_completed
+      self.record_count = event.payload[:record_count]
+    when :import_failed
+      self.error_message = event.payload[:error].message
+    end
+    false
+  end
+end
+
+workflow = nil
+
+workflow = Phronomy::Workflow.define(ImportContext) do
+  initial :importing
+
+  state :importing, action: ->(context) {
+    task = Phronomy::Runtime.instance.spawn do
+      # Replace with application-owned asynchronous work.
+      100
+    end
+
+    task.on_complete do |record_count, error|
+      workflow.signal(
+        thread_id: context.thread_id,
+        event: error ? :import_failed : :import_completed,
+        payload: {
+          record_count: record_count,
+          error: error
+        }
+      )
+    end
+
+    # Do not return task. The state is active after this synchronous entry ends.
+    context
+  }
+
+  state :completed
+  state :failed
+
+  transition from: :importing, on: :import_completed, to: :completed
+  transition from: :importing, on: :import_failed, to: :failed
+  transition from: :completed, to: :__finish__
+  transition from: :failed, to: :__finish__
+end
+
+result = workflow.invoke({})
+puts "Imported #{result.record_count} records"

data/gemfiles/mcp_1_0.gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec path: ".."
+
+gem "mcp", "= 1.0.0"
+gem "rspec", "~> 3.0"
+gem "webrick", "~> 1.8"