phronomy 0.19.0 → 0.21.0

data/sig/phronomy/runtime.rbs

@@ -0,0 +1,43 @@
+module Phronomy
+  class Task[A]
+    attr_reader name: String?
+    attr_reader parent: Task[untyped]?
+
+    def status: () -> (:pending | :completed | :failed | :cancelled)
+    def done?: () -> bool
+    def alive?: () -> bool
+    def wait_result: (?timeout: Numeric?) -> A
+    def on_complete: () { (A?, Exception?) -> void } -> self
+    def map: [B] () { (A) -> B } -> Task[B]
+  end
+
+  module Concurrency
+    class CancellationToken
+      def self.timeout_after: (Numeric seconds) -> CancellationToken
+      def initialize: (?monotonic_deadline: Float?) -> void
+      def remaining_monotonic_seconds: () -> Float?
+      def on_cancel: () { () -> void } -> self
+      def cancel!: () -> self
+      def cancelled?: () -> bool
+      def raise_if_cancelled!: (?String message) -> nil
+    end
+  end
+end
+
+module Phronomy
+  class InvocationContext
+    attr_reader thread_id: String?
+    attr_reader session_id: String?
+    attr_reader user_id: String?
+    attr_reader cancellation_token: Concurrency::CancellationToken?
+    attr_reader deadline: untyped
+    attr_reader tracer_span: untyped
+    attr_reader token_budget: Integer?
+    attr_reader approval_policy: untyped
+    attr_reader redaction_policy: untyped
+    attr_reader task_id: String?
+    attr_reader parent_task_id: String?
+
+    def initialize: (?thread_id: String?, ?session_id: String?, ?user_id: String?, ?cancellation_token: Concurrency::CancellationToken?, ?deadline: untyped, ?tracer_span: untyped, ?token_budget: Integer?, ?approval_policy: untyped, ?redaction_policy: untyped, ?task_id: String?, ?parent_task_id: String?) -> void
+  end
+end

data/sig/phronomy/tool.rbs

@@ -0,0 +1,39 @@
+module Phronomy
+  module Tool
+    class Base
+      def self.tool_name: (?untyped value) -> String?
+      def self.description: (?String text) -> String?
+      def self.desc: (?String text) -> String?
+      def self.parameters: () -> Hash[untyped, untyped]
+      def self.params_schema_definition: () -> untyped
+      def self.provider_params: () -> Hash[untyped, untyped]
+      def self.param: (untyped name, ?enum: untyped, ?properties: untyped, **untyped options) -> untyped
+      def self.execution_mode: (?(:cooperative | :offloaded) value) -> (:cooperative | :offloaded)
+      def self.on_error: (?(:raise | :suppress) behavior) -> (:raise | :suppress)
+      def self.on_schema_error: (?untyped behavior) -> untyped
+      def self.requires_approval: (?untyped value) { () -> untyped } -> untyped
+                               | (?untyped value) -> untyped
+      def self.approval_facts: () { (untyped, untyped) -> untyped } -> untyped
+                             | () -> untyped
+      def self.redact_params: (*untyped names) -> Array[Symbol]
+      def self.max_result_size: (?untyped value) -> untyped
+
+      def name: () -> String
+      def params_schema: () -> untyped
+      def call: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?) -> untyped
+      def call_async: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?, ?config: Hash[untyped, untyped]) -> Task[untyped]
+      def requires_approval?: () -> untyped
+      def tool_origin: () -> Symbol
+      def approval_metadata: () -> Hash[untyped, untyped]
+      def execute: (**untyped args) -> untyped
+    end
+  end
+
+  module Agent
+    module Context
+      module Capability
+        class Base = ::Phronomy::Tool::Base
+      end
+    end
+  end
+end

data/sig/phronomy/workflow.rbs

@@ -0,0 +1,30 @@
+module Phronomy
+  module WorkflowContext
+    def phase: () -> Symbol
+    def halted?: () -> bool
+    def thread_id: () -> String?
+    def merge: (Hash[Symbol, untyped] updates) -> self
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class Workflow
+    def self.define: (Class context_class, ?persistence: Persistence?) { () -> void } -> Workflow
+
+    def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> untyped
+    def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[untyped]
+    def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) { (untyped) -> void } -> untyped
+    def resume: (state: untyped, ?input: untyped) -> untyped
+    def send_event: (state: untyped, event: Symbol, ?input: untyped) -> untyped
+    def signal: (thread_id: String, event: Symbol, ?payload: untyped) -> bool
+
+    class Builder
+      def initial: (Symbol state_name) -> untyped
+      def state: (Symbol name, ?action: untyped) -> untyped
+      def entry: (Symbol name, untyped callable) -> untyped
+      def exit: (Symbol name, untyped callable) -> untyped
+      def wait_state: (Symbol name) -> untyped
+      def transition: (from: Symbol, to: Symbol, ?guard: untyped, ?on: Symbol?, ?action: untyped) -> untyped
+      def build: () -> Workflow
+    end
+  end
+end

data/sig/phronomy.rbs

@@ -1,4 +1,52 @@
 module Phronomy
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  class Error < StandardError
+  end
+
+  class ParseError < Error
+  end
+
+  class RecursionLimitError < Error
+  end
+
+  class ToolError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class TransportError < Error
+  end
+
+  class RateLimitError < TransportError
+  end
+
+  class AuthenticationError < TransportError
+  end
+
+  class ContextLengthError < Error
+  end
+
+  class CancellationError < Error
+  end
+
+  class EventLoopReentrancyError < Error
+  end
+
+  class PoolShutdownError < Error
+  end
+
+  class BackpressureError < Error
+  end
+
+  class Configuration
+    attr_accessor llm_adapter: LLMAdapter::Base
+  end
+
+  def self.configuration: () -> Configuration
+  def self.configure: () { (Configuration) -> void } -> void
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.19.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-15 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -120,12 +120,14 @@ files:
 - docs/decisions/012-canonical-execution-log-and-context-policy.md
 - docs/decisions/013-journal-backed-knowledge-as-context-candidates.md
 - docs/decisions/014-unified-persistence-durable-state.md
+- docs/decisions/015-tool-public-facade-and-rbs-boundary.md
 - docs/features.md
 - docs/getting-started.md
 - docs/mcp-client.md
 - docs/migrations/0.15.md
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
+- docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
 - examples/workflows/agent_event_mapping.rb
 - examples/workflows/generic_task_event_mapping.rb
@@ -250,7 +252,16 @@ files:
 - lib/phronomy/testing/eval/scorer/includes_scorer.rb
 - lib/phronomy/testing/eval/scorer/llm_judge.rb
 - lib/phronomy/testing/fake_clock.rb
+- lib/phronomy/testing/persistence_contract.rb
+- lib/phronomy/testing/persistence_contract/a_content_store.rb
+- lib/phronomy/testing/persistence_contract/a_journal_repository.rb
+- lib/phronomy/testing/persistence_contract/a_persistence_backend.rb
+- lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
+- lib/phronomy/testing/persistence_contract/an_agent_repository.rb
+- lib/phronomy/testing/persistence_contract/an_execution_repository.rb
 - lib/phronomy/token_usage.rb
+- lib/phronomy/tool.rb
+- lib/phronomy/tool/base.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb
 - lib/phronomy/tools/vector_search.rb
@@ -283,7 +294,6 @@ files:
 - scripts/add_to_h_unnamed_doubles.rb
 - scripts/api_snapshot.rb
 - scripts/check_api_annotations.rb
-- scripts/check_private_enforcement.rb
 - scripts/check_readme_ruby.rb
 - scripts/check_readme_runnable.rb
 - scripts/migrate_spec_agent_definition.rb
@@ -291,6 +301,13 @@ files:
 - scripts/migrate_spec_inline_pass3.rb
 - scripts/run_mutation.sh
 - sig/phronomy.rbs
+- sig/phronomy/agent.rbs
+- sig/phronomy/extensions.rbs
+- sig/phronomy/llm_adapter.rbs
+- sig/phronomy/persistence.rbs
+- sig/phronomy/runtime.rbs
+- sig/phronomy/tool.rbs
+- sig/phronomy/workflow.rbs
 homepage: https://github.com/Raizo-TCS/phronomy
 licenses:
 - MIT

data/scripts/check_private_enforcement.rb

@@ -1,93 +0,0 @@
-#!/usr/bin/env ruby
-# frozen_string_literal: true
-
-# check_private_enforcement.rb
-#
-# Verifies that every instance method annotated @api private in lib/ is
-# actually non-public at the Ruby level (i.e., NOT in Module#public_instance_methods).
-#
-# Class methods (def self.xxx) are excluded from this check because their
-# visibility is managed separately on the singleton class and rarely causes
-# accidental public exposure to consumers.
-#
-# Usage (run from the phronomy/ repository root):
-#   bundle exec ruby scripts/check_private_enforcement.rb
-#
-# Exit codes:
-#   0 — all @api private instance methods are non-public (or have no Ruby def)
-#   1 — one or more @api private instance methods are exposed as public
-
-require "bundler/setup"
-require_relative "../lib/phronomy"
-
-lib_dir = File.expand_path("../lib", __dir__)
-
-unless File.directory?(lib_dir)
-  warn "ERROR: lib directory not found at #{lib_dir}"
-  exit 1
-end
-
-# Step 1: Collect instance methods annotated @api private via static analysis.
-api_private_entries = []
-
-Dir.glob(File.join(lib_dir, "**", "*.rb")).sort.each do |file|
-  lines = File.readlines(file)
-
-  lines.each_with_index do |line, i|
-    next unless line.match?(/^\s*#\s*@api\s+private\s*$/)
-
-    # Advance past any further comment or blank lines to reach the def.
-    j = i + 1
-    j += 1 while j < lines.size && lines[j].match?(/^\s*(#|$)/)
-    next unless j < lines.size
-
-    # Skip class-level methods — they live on the singleton class, not as
-    # public instance methods accessible to consumers.
-    next if lines[j].match?(/def\s+self\./)
-
-    # Match both plain def and "private def".
-    m = lines[j].match(/^\s*(?:private\s+)?def\s+(\w+[!?=]?)/)
-    next unless m
-
-    rel_path = file.sub("#{lib_dir}/../", "")
-    api_private_entries << {name: m[1].to_sym, file: rel_path, line: j + 1}
-  end
-end
-
-if api_private_entries.empty?
-  puts "No @api private instance methods found."
-  exit 0
-end
-
-# Step 2: Build a map of publicly exposed instance methods across all
-# Phronomy-namespaced modules/classes (own methods only, no inheritance).
-all_phronomy_modules = ObjectSpace.each_object(Module).select do |mod|
-  mod.name&.start_with?("Phronomy")
-end
-
-public_exposure_map = {}
-all_phronomy_modules.each do |mod|
-  mod.public_instance_methods(false).each do |meth|
-    (public_exposure_map[meth] ||= []) << mod.name
-  end
-end
-
-# Step 3: Report violations — @api private methods that are still public.
-errors = []
-
-api_private_entries.each do |entry|
-  exposing_modules = public_exposure_map[entry[:name]]
-  next unless exposing_modules
-
-  errors << "#{entry[:file]}:#{entry[:line]}  def #{entry[:name]}" \
-            "  (annotated @api private but public in: #{exposing_modules.join(", ")})"
-end
-
-if errors.empty?
-  puts "OK: all #{api_private_entries.size} @api private instance methods are non-public."
-  exit 0
-else
-  warn "ERROR: #{errors.size} @api private instance method(s) are exposed as public:"
-  errors.each { |e| warn "  #{e}" }
-  exit 1
-end