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 +4 -4
- data/CHANGELOG.md +25 -0
- data/README.md +2 -2
- data/SECURITY.md +1 -1
- data/docs/architecture/agent-tool-child-lifetime.md +21 -0
- data/docs/shared-state-sharing.md +12 -0
- data/lib/phronomy/agent/lifecycle/ownership_registry.rb +38 -4
- data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb +4 -2
- data/lib/phronomy/multi_agent/orchestrator.rb +21 -1
- data/lib/phronomy/tools/agent.rb +6 -1
- data/lib/phronomy/version.rb +1 -1
- data/sig/phronomy/multi_agent.rbs +1 -0
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: b18d52aafcaa833cf4ef1bd8d5f937088ca7f51a3dbc46fcd191580817885dfa
|
|
4
|
+
data.tar.gz: 6caea92395e99686a7ecbd051edb36aa48d5ee0abaf25e99f3cc4686ac92aa09
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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
|
@@ -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
|
-
#
|
|
324
|
-
#
|
|
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|
|
|
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, _|
|
|
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:
|
|
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|
|
|
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
|
data/lib/phronomy/tools/agent.rb
CHANGED
|
@@ -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) {
|
|
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)
|
data/lib/phronomy/version.rb
CHANGED
|
@@ -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
|