phronomy 0.35.2 → 0.35.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: fd730052ab22e489edccab8719c26d5f25e66f15d798a35e7f6dd35ce2864033
4
- data.tar.gz: 31f924ae82bfc4206ffe151396c9c6ffed809a68ede9f968a5b6c4607c4d2629
3
+ metadata.gz: b18d52aafcaa833cf4ef1bd8d5f937088ca7f51a3dbc46fcd191580817885dfa
4
+ data.tar.gz: 6caea92395e99686a7ecbd051edb36aa48d5ee0abaf25e99f3cc4686ac92aa09
5
5
  SHA512:
6
- metadata.gz: 8e91585690b00f9566db0143fb56dd34961658c4b3c8c86c0131379b5922dc96458aecadd56f5a6323e36cb5f0041ff2c44030449ca38b26dcdd7d048f2ecc0c
7
- data.tar.gz: 01cf02a781f981c892c1e4d4b64e2d3b66c9aed0698a55f2546d2afd5aec9bf4107afc70f39a7a0b4a862662037b34bd1f086453e466b7a10d009bb7003dc65f
6
+ metadata.gz: 237eda3881df9a1b24fbd63a4b980c737acc2739f9006c4ab12030cf3fce3326d801b1c5612f1559b1a1c9dfe1a88d68b3d93bc59b7a3e36cf2db2d558ae0af9
7
+ data.tar.gz: 0c4609068ee6ab89dee9b64ebc53e245cd31c7d39a5d9817722941a25d17bf1fb81d1b82b1f0a54f93aa3ab90f172d6c8107f1f7b66a3898920955c14845aa3f
data/CHANGELOG.md CHANGED
@@ -12,6 +12,31 @@ Release history for 0.14.0 and earlier is archived in
12
12
 
13
13
  ## [Unreleased]
14
14
 
15
+ ## [0.35.3] - 2026-11-19
16
+
17
+ ### Fixed
18
+
19
+ - Allow an already accepted Agent Tool to finish its private child's release
20
+ during graceful Runtime draining. Track that release on the existing Agent
21
+ ownership entry without reopening new admission or adding a cleanup registry.
22
+ A child still awaiting human approval at the finite shutdown deadline leaves
23
+ cleanup incomplete instead of being treated as released.
24
+ - Preserve native subagent registration when `Orchestrator.with_tools` retains
25
+ a child Tool. Tool aliases now remain consistent across durable dispatch,
26
+ replay and hosted approval recovery. Removed Tools lose their registrations;
27
+ ordinary subclass inheritance keeps its existing behavior.
28
+
29
+ ### Compatibility and verification
30
+
31
+ - Public call signatures, dependency requirements and saved representations are
32
+ unchanged. An unresolved private-child approval wait can still leave cleanup
33
+ incomplete at the finite shutdown deadline; the Tool does not automatically
34
+ approve, force-release or recover the child.
35
+ - Candidate-source examples verification passed against the existing
36
+ llama-server with gpt-oss-20b. This does not establish resolution of the
37
+ previously observed PEG-format failure root cause or replace post-release
38
+ verification with the published gem.
39
+
15
40
  ## [0.35.2] - 2026-11-18
16
41
 
17
42
  ### Fixed
data/README.md CHANGED
@@ -37,7 +37,7 @@ tracking `main` directly.
37
37
 
38
38
  See [Features and Application Programming Interface (API) stability](docs/features.md) for the full feature matrix.
39
39
 
40
- The following table describes the application APIs available in v0.35.2.
40
+ The following table describes the application APIs available in v0.35.3.
41
41
  The public persistence resource catalogs are available starting with v0.35.0.
42
42
  The sharing, Tool composition and Context budgeting operations remain
43
43
  Experimental; their introduction version is shown below.
@@ -59,7 +59,7 @@ the current saved representation.
59
59
  | `PersistenceComposition.resources` and `.agent_resources` | Beta (since v0.35.0) | Supply canonical frozen resource catalogs to an application-selected backend for `.build(backend:)` or `.agent(backend:)`, without creating a backend, stores or Runtime. [Backend catalog](docs/persistence-backends.md#supplying-a-backend-catalog) |
60
60
  | `Persistence::Migration::InitialFormatMigration` | Removed (v0.34.0) | The pre-S3 conversion API is retired without a replacement. Current domain codecs and the separate Unit4 snapshot migration remain. [Legacy-format cleanup](docs/migrations/legacy-format-removal.md) |
61
61
  | `Context::ContextPolicyInput#input_token_limit / #with_input_token_limit` and protected `ContextPolicy#estimate_tokens` | Experimental (since v0.33.0) | Inspect and constrain selection budgets and estimate candidate content through Context-owned operations. [Policy budgeting](docs/context-policy-budgeting.md) |
62
- | `Agent::Base.with_tools(definitions, id:, version:)` | Experimental (since v0.33.0) | Derive an Agent class with a complete replacement Tool map and explicit definition identity while preserving Phronomy authoring settings and filters. [Tool composition](docs/shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) |
62
+ | `Agent::Base.with_tools(definitions, id:, version:)` | Experimental (since v0.33.0) | Derive an Agent class with a complete replacement Tool map and explicit definition identity while preserving Phronomy authoring settings and filters. Orchestrator derivation also preserves native subagent registrations for retained child Tools, including their aliases. [Tool composition](docs/shared-state-sharing.md#deriving-an-agent-with-a-complete-tool-set) |
63
63
  | `MultiAgent::SharedState.sharing(provider, id:, version:)`, `SharedState::Binding` and `SharedState::MemberLifecycleError` | Experimental (since v0.33.0) | Sequential coordination releases its terminal member Agents in both default and custom modes; an optional invocation-scoped provider supplies application-owned data and Tools. [Sharing and member lifetime contract](docs/shared-state-sharing.md) |
64
64
  | `Tool::Base#approval_display(arguments:, facts:)` | Beta (since v0.33.0) | The Tool selects the arguments and derived facts a person can see in an approval request. [Approval display](docs/runtime-and-concurrency.md#tool-approval-display) |
65
65
  | `Runtime#shutdown` result predicates `cleanup_complete?` and `clean?` | Beta | Check resource release with `cleanup_complete?`; `clean?` additionally requires a graceful shutdown. The obsolete `success?` alias is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#runtime-cleanup-completion) |
data/SECURITY.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Version | Supported |
6
6
  |---------|-----------|
7
- | 0.35.2 (latest release) | ✅ |
7
+ | 0.35.3 (latest release) | ✅ |
8
8
  | Older versions | ❌ — please upgrade |
9
9
 
10
10
  Only the latest released version of `phronomy` receives security patches. If you
@@ -23,6 +23,27 @@ used merely to wait for the child or its release. The existing Agent release can
23
23
  perform its ordinary asynchronous persistence checks. Records are not purged,
24
24
  and unrelated Agents or shared stores are not shut down.
25
25
 
26
+ ## Graceful Runtime shutdown
27
+
28
+ An accepted private child's final release is part of its existing Agent
29
+ ownership entry. Runtime waits for that release within the drain budget, and
30
+ Agent can transfer the pending release to its ordinary unload transition after
31
+ new admission closes. This adds no separate cleanup registry or application
32
+ lifetime handle. Ordinary application-requested unloads do not gain admission
33
+ during draining.
34
+
35
+ For example, if shutdown begins while an Agent Tool waits for an LLM response,
36
+ a successful response can still finish the child's release and return its normal
37
+ output. Provider failure keeps its original error after release, and cancelling
38
+ only the observer does not abandon physical cleanup. New Agent creation and
39
+ invocation remain rejected once draining starts.
40
+
41
+ The finite drain budget still applies. If a child remains suspended for human
42
+ approval, shutdown reports incomplete cleanup rather than treating the retained
43
+ child as released. The Tool result can remain pending; shutdown does not supply
44
+ approval or promise later finalization after incomplete shutdown. The existing
45
+ incomplete-cleanup rule prevents replacement of that default Runtime.
46
+
26
47
  ## Cancellation and approval
27
48
 
28
49
  Logical result settlement does not prove that physical work has ended. The
@@ -132,6 +132,18 @@ The original class is unchanged. This explicit factory does not change general
132
132
  Agent subclass inheritance or define copying rules for application-specific
133
133
  class state.
134
134
 
135
+ For an Orchestrator, this explicit factory also preserves native subagent
136
+ registrations for the child Tools kept in the replacement map. Removed child
137
+ Tools lose their registrations, and retained child Tools use their effective
138
+ aliases for durable dispatch, replay and hosted approval recovery. Registration
139
+ settings are independent of the original class. Ordinary subclass inheritance
140
+ still starts with no native subagent registrations.
141
+
142
+ For example, keeping a `dispatch_to_worker` Tool under the alias `consult_worker`
143
+ still runs the registered child through the Orchestrator's coordination Store.
144
+ Replacing that Tool with an unrelated application Tool removes the child
145
+ registration; it does not keep an unreachable coordination entry.
146
+
135
147
  The default findings-store mode now preserves these settings through the same
136
148
  factory. For example, a member configured with `max_iterations 3` and
137
149
  `temperature 0.25` keeps those settings when SharedState adds `read_store` and
@@ -165,6 +165,34 @@ module Phronomy
165
165
  true
166
166
  end
167
167
 
168
+ # A private child already owned by this Runtime must finish its final
169
+ # release before the shutdown participant can become idle. Keep that
170
+ # obligation on the existing owner entry, not in a second registry.
171
+ def expect_unload(agent)
172
+ @mutex.synchronize do
173
+ ensure_running!
174
+ entry = @entries[agent.agent_id]
175
+ unless entry&.state == :live && entry.agent.equal?(agent) && entry.token.nil?
176
+ raise Phronomy::AgentBusyError, "Agent is not available for owned release"
177
+ end
178
+ @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: :pending_unload)
179
+ end
180
+ true
181
+ end
182
+
183
+ # A failed finalizer leaves the child with its existing error owner. Never
184
+ # clear an accepted transition or a newer owner while removing the marker.
185
+ def cancel_expected_unload(agent)
186
+ @mutex.synchronize do
187
+ entry = @entries[agent.agent_id]
188
+ if entry&.state == :live && entry.agent.equal?(agent) && entry.token == :pending_unload
189
+ @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: nil)
190
+ @condition.broadcast
191
+ end
192
+ end
193
+ true
194
+ end
195
+
168
196
  # Transfer only the single outstanding hosting operation, atomically with
169
197
  # the same admission gate used by all other Agent operations.
170
198
  def reserve_approval_detach!(agent, operation_token, transition, parent: nil)
@@ -191,8 +219,10 @@ module Phronomy
191
219
  # Returns the already accepted transition for duplicate callers.
192
220
  def reserve_unload(agent)
193
221
  @mutex.synchronize do
194
- ensure_running!
195
222
  entry = @entries[agent.agent_id]
223
+ accepted_release = @state == :draining && entry&.state == :live &&
224
+ entry.agent.equal?(agent) && entry.token == :pending_unload
225
+ ensure_running! unless accepted_release
196
226
  if entry&.state == :unloading && entry.agent.equal?(agent)
197
227
  unless entry.token.is_a?(UnloadTransition)
198
228
  raise Phronomy::AgentBusyError, "Agent has a coordinated release in progress"
@@ -320,11 +350,15 @@ module Phronomy
320
350
  self
321
351
  end
322
352
 
323
- # Live/recovery-required entries do not prevent Runtime shutdown. Only an
324
- # ownership transition that is still actively changing state must settle.
353
+ # Ordinary live/recovery-required entries do not prevent Runtime shutdown.
354
+ # Accepted final releases stay pending through their atomic transition to
355
+ # unloading, so shutdown cannot observe an idle gap between the two.
325
356
  def wait_until_idle(deadline)
326
357
  @mutex.synchronize do
327
- while @entries.values.any? { |entry| %i[constructing purging unloading].include?(entry.state) }
358
+ while @entries.values.any? { |entry|
359
+ %i[constructing purging unloading].include?(entry.state) ||
360
+ (entry.state == :live && entry.token == :pending_unload)
361
+ }
328
362
  remaining = deadline - monotonic_now
329
363
  # :nocov:
330
364
  return false if remaining <= 0
@@ -47,7 +47,7 @@ module Phronomy
47
47
  child["imported"] = true if observed.terminal? && change.kind == :dispatch && change.operations.empty?
48
48
  end
49
49
  change.operations.each do |operation|
50
- entry = @definitions.find { |name, _| "dispatch_to_#{name}" == operation.name }
50
+ entry = @definitions.find { |name, _| @agent_class.__subagent_tool_name(name) == operation.name }
51
51
  next unless entry
52
52
  next if children.any? { |child| child.fetch("slot") == operation.invocation_id }
53
53
  name, settings = entry
@@ -97,8 +97,10 @@ module Phronomy
97
97
  child = children.first
98
98
  next unless !child.fetch("imported") && child.fetch("execution_id") == execution_id
99
99
  next unless matching_child_class?(child, live_child)
100
+ tool_name = @agent_class.__subagent_tool_name(child.fetch("name"))
101
+ next unless tool_name
100
102
  next unless store.single_dispatch_wait?(agent_id: parent_id, execution_id: parent_execution_id,
101
- invocation_id: child.fetch("slot"), name: "dispatch_to_#{child.fetch("name")}", expected_revision: parent_revision, scope: scope)
103
+ invocation_id: child.fetch("slot"), name: tool_name, expected_revision: parent_revision, scope: scope)
102
104
  next unless hosted_retentions?(parent_id, parent_execution_id, scope)
103
105
 
104
106
  child_id = child.fetch("agent_id")
@@ -20,6 +20,19 @@ module Phronomy
20
20
  super(agent_id, persistence: persistence, execution_wiring: {phronomy_execution_participant: participant}, **options, &block)
21
21
  end
22
22
 
23
+ # Preserve native child ownership when explicitly replacing the Tool map.
24
+ # Ordinary subclass inheritance still starts with no subagent registrations.
25
+ def self.with_tools(definitions, id:, version:)
26
+ derived = super
27
+ retained = _subagent_tool_classes & derived.tools
28
+ registrations = registered_subagents.select do |name, _|
29
+ retained.any? { |tool| tool.tool_name == "dispatch_to_#{name}" }
30
+ end.transform_values(&:dup)
31
+ derived.instance_variable_set(:@_subagent_tool_classes, retained)
32
+ derived.instance_variable_set(:@registered_subagents, registrations)
33
+ derived
34
+ end
35
+
23
36
  def initialize(coordination_store: nil, execution_wiring: {}, **options, &block)
24
37
  @coordination_store = coordination_store || execution_wiring[:phronomy_execution_participant]&.persistence || Phronomy::MultiAgent::Store.configured
25
38
  super(execution_wiring: execution_wiring, **options, &block)
@@ -156,6 +169,13 @@ module Phronomy
156
169
  @registered_subagents ||= {}
157
170
  end
158
171
 
172
+ # @api private
173
+ def self.__subagent_tool_name(name)
174
+ native_name = "dispatch_to_#{name}"
175
+ tool = _subagent_tool_classes.find { |candidate| candidate.tool_name == native_name }
176
+ tool && (tool_aliases[tool] || native_name)
177
+ end
178
+
159
179
  def dispatch_parallel(
160
180
  *tasks,
161
181
  max_concurrency: nil,
@@ -237,7 +257,7 @@ module Phronomy
237
257
 
238
258
  # @api private
239
259
  def __framework_tool_replayable?(name)
240
- self.class.registered_subagents.keys.any? { |key| "dispatch_to_#{key}" == name.to_s }
260
+ self.class.registered_subagents.keys.any? { |key| self.class.__subagent_tool_name(key) == name.to_s }
241
261
  end
242
262
 
243
263
  private
@@ -73,9 +73,14 @@ module Phronomy
73
73
 
74
74
  persistence = Phronomy::Agent::DefaultPersistence.build
75
75
  agent = agent_class.create(persistence: persistence)
76
+ ownership = Phronomy::Agent::OwnershipRegistry.current
77
+ ownership.expect_unload(agent)
76
78
  Phronomy::AsyncOperation.finalize(name: "agent-tool-#{name}-release",
77
79
  cleanup: -> { agent.unload_async },
78
- on_cleanup_error: ->(value, primary, cleanup) { child_cleanup_failed(agent, value, primary, cleanup) }) do
80
+ on_cleanup_error: ->(value, primary, cleanup) {
81
+ ownership.cancel_expected_unload(agent)
82
+ child_cleanup_failed(agent, value, primary, cleanup)
83
+ }) do
79
84
  Phronomy::AsyncOperation.call(name: "agent-tool-#{name}-invoke",
80
85
  transform: ->(result) { result[:output].to_s }) do
81
86
  agent.invoke_async(input, config: task_config)
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Phronomy
4
- VERSION = "0.35.2"
4
+ VERSION = "0.35.3"
5
5
  end
@@ -46,6 +46,7 @@ module Phronomy
46
46
  attr_reader coordination_store: Store?
47
47
  def self.create: (?coordination_store: Store?, **Object options) ?{ (Object) -> void } -> instance
48
48
  def self.load: (String agent_id, persistence: Agent::Store, coordination_store: Store, **Object options) ?{ (Object) -> void } -> instance
49
+ def self.with_tools: (Hash[Class, String?] definitions, id: String, version: Integer) -> singleton(Orchestrator)
49
50
  def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
50
51
  def unload_with_completed_child!: (String parent_execution_id, execution_id: String) -> bool
51
52
  def approve_hosted_child: (String parent_execution_id, execution_id: String, approval_request_id: String, ?approved: bool, ?config: Hash[Symbol, untyped]) -> ::Phronomy::Agent::HostedInvocation
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: phronomy
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.35.2
4
+ version: 0.35.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Raizo T.C.S