phronomy 0.36.0 → 0.37.0
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 +33 -0
- data/README.md +2 -1
- data/SECURITY.md +1 -1
- data/docs/architecture/structured-output-and-scope.md +58 -1
- data/docs/features.md +1 -0
- data/lib/phronomy/agent/async_event_api.rb +13 -0
- data/lib/phronomy/agent/execution/agent_invocation.rb +1 -1
- data/lib/phronomy/agent/execution/exact_execution.rb +2 -3
- data/lib/phronomy/version.rb +1 -1
- metadata +2 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: ea854d0434bfc24dd1bb49dc2420ead34b2a1ba1e0b5f9749e96cb91b0bc9108
|
|
4
|
+
data.tar.gz: 5fe68a72f9a4f7856f82ef564a0326b2d121d420bc7fa80b81d268430768b8a4
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 1aa266e0d0fd39a069f955c314b58c35d9ac9976a6273d2705477e273501a938dbf06dd217802f25ae869ef5527527d837e851197582d43593d8d2fab1920700
|
|
7
|
+
data.tar.gz: 5cdc5a5e88ece7863c51055aa28f647603171a801a9206b3422b09ace4aa5c423a0347668e2fee0d8615ee3e22c97b6180ad581b866e57033ec1375f61be12ff
|
data/CHANGELOG.md
CHANGED
|
@@ -12,6 +12,39 @@ Release history for 0.14.0 and earlier is archived in
|
|
|
12
12
|
|
|
13
13
|
## [Unreleased]
|
|
14
14
|
|
|
15
|
+
## [0.37.0] - 2026-11-21
|
|
16
|
+
|
|
17
|
+
### Changed
|
|
18
|
+
|
|
19
|
+
- Agent `start_reserved_async`, `resume_async` and `resume` return saved
|
|
20
|
+
`OutputError` failures as ordinary execution-result hashes with `status: :failed`
|
|
21
|
+
and the original diagnostic, consistently with other confirmed execution
|
|
22
|
+
failures. Their TaskResult completion reports successful observation of that
|
|
23
|
+
result; starting, resuming or observing the execution can still fail separately.
|
|
24
|
+
Ordinary `invoke` / `invoke_async` / `stream` / `stream_async` retain their
|
|
25
|
+
output-failure exception contract.
|
|
26
|
+
|
|
27
|
+
### Fixed
|
|
28
|
+
|
|
29
|
+
- Let Team consume a child's confirmed output failure through its existing result
|
|
30
|
+
handling. The assignment records `failed`, then the Team applies its configured
|
|
31
|
+
failure policy and releases its active-run slot after the Team result commits.
|
|
32
|
+
Observing the same terminal child after restart does not run that child again.
|
|
33
|
+
- Preserve a legitimate `nil` Tool result in runtime events so it can be saved
|
|
34
|
+
as JSON null. This also lets the existing Orchestrator `on_error: :skip`
|
|
35
|
+
policy complete after a confirmed child output failure.
|
|
36
|
+
- Make Agent Tool collection tests wait for completed worker frames to
|
|
37
|
+
return while preserving Runtime ownership registries and completed handles
|
|
38
|
+
as retention checks. Production lifetime behavior is unchanged.
|
|
39
|
+
|
|
40
|
+
### Compatibility
|
|
41
|
+
|
|
42
|
+
- Exact-execution output-failure handling is an intentional public behavior
|
|
43
|
+
change. Callers must inspect the returned status/error, or explicitly unwrap
|
|
44
|
+
through `Agent::ExecutionObservation.from_result(result).value!` to raise the
|
|
45
|
+
saved failure. Call signatures, result shapes and saved formats are unchanged;
|
|
46
|
+
no new event bus, state machine or coordination layer is introduced.
|
|
47
|
+
|
|
15
48
|
## [0.36.0] - 2026-11-20
|
|
16
49
|
|
|
17
50
|
### 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.
|
|
40
|
+
The following table describes the application APIs available in v0.37.0.
|
|
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.
|
|
@@ -66,6 +66,7 @@ the current saved representation.
|
|
|
66
66
|
| `Phronomy::EventLoopReentrancyError` | Beta | Raised when a synchronous operation would block the EventLoop control thread. The obsolete `SchedulerReentrancyError` subclass is removed in v0.34.0. [Cleanup migration](docs/migrations/cleanup-audit.md#eventloop-reentrancy-errors) |
|
|
67
67
|
| `Phronomy::LLMAdapter::LMStudio` | Beta | Explicit known-output-error identification and bounded opt-in retry; [policy and evidence limits](docs/architecture/lm-studio-output-failures.md) |
|
|
68
68
|
| Agent `output_schema:`, `schema_delivery:`, `Agent::OutputError` and `OutputParser::JsonSchemaParser` | Beta | Agent returns validated immutable JSON or an explicit output failure; [contract and migration](docs/architecture/structured-output-and-scope.md) |
|
|
69
|
+
| Agent `start_reserved_async`, `resume_async` and `resume` | Beta (behavior changed in v0.37.0) | Return the confirmed execution result, including `status: :failed` and saved `OutputError` diagnostics. Errors in starting, resuming or observing the execution remain operation failures; [exact execution results](docs/architecture/structured-output-and-scope.md#exact-execution-results) |
|
|
69
70
|
| Agent `transcript_messages` / `transcript_messages_async` | Beta | Read immutable conversation Message values with the same restoration rules as execution results; [reading conversation state](docs/getting-started.md) |
|
|
70
71
|
| `Phronomy::GeneratorVerifier`, its approval/lifetime operations and immutable `Result` with output-failure diagnostics | Beta | [Generation and structured-output contract](docs/architecture/structured-output-and-scope.md) |
|
|
71
72
|
| `Agent.open_scope`, `Agent::Scope`, `Agent::Base#unload_async / #unload!`, `AgentUnloadedError` and `Agent::ScopeCleanupError` | Beta | Runtime-bound ownership and safe release of idle Agent incarnations without changing saved history or closing the Store; [contract](docs/architecture/dx05-agent-scope.md) |
|
data/SECURITY.md
CHANGED
|
@@ -12,7 +12,9 @@ authorization and any decision to start another attempt.
|
|
|
12
12
|
`run_once` forwards both options. With a schema, omitted/nil delivery means
|
|
13
13
|
`:native`; explicit `:native` and `:none` are supported. A non-nil delivery without
|
|
14
14
|
a schema, or any other value, raises ArgumentError before admission. The same
|
|
15
|
-
keywords and
|
|
15
|
+
keywords and output-validation rules apply to sync/async and invoke/stream.
|
|
16
|
+
The exact-execution APIs report confirmed failures as result values, as described
|
|
17
|
+
under [Exact execution results](#exact-execution-results).
|
|
16
18
|
Without a schema the existing free-text behavior remains. With a schema, successful
|
|
17
19
|
`output` and `result` are deeply frozen JSON objects with String keys; `raw_output`
|
|
18
20
|
preserves the model text. Token events are provisional, not validated objects.
|
|
@@ -148,6 +150,61 @@ Fresh-runtime and new SQL connection-pool tests verify success, failure and appr
|
|
|
148
150
|
continuation without replay of confirmed LLM/Tool work. This is a durable-facts
|
|
149
151
|
claim, not an external side-effect exactly-once guarantee.
|
|
150
152
|
|
|
153
|
+
## Exact execution results
|
|
154
|
+
|
|
155
|
+
An exact-execution operation starts or continues a specific Agent execution and
|
|
156
|
+
reports its confirmed terminal result. The execution's outcome is distinct from
|
|
157
|
+
whether that operation could start, resume or observe the execution. This behavior
|
|
158
|
+
changed in v0.37.0 for saved `OutputError` failures.
|
|
159
|
+
|
|
160
|
+
For example, a Team worker can finish with invalid structured output. The Agent
|
|
161
|
+
saves `status: :failed`; the Team receives that result, records the failed
|
|
162
|
+
assignment, and applies its existing failure policy. No Team-specific callback,
|
|
163
|
+
state machine or exception handler is required in the Agent.
|
|
164
|
+
|
|
165
|
+
| Operation | Confirmed output failure | Operation failure |
|
|
166
|
+
| --- | --- | --- |
|
|
167
|
+
| `invoke`, `invoke_async`, `stream`, `stream_async` | Raise/fail the TaskResult with `OutputError` | Raise/fail the TaskResult |
|
|
168
|
+
| `start_reserved_async`, `resume_async`, `resume` | Return the existing execution-result hash with `status: :failed` and saved `error` diagnostic | Raise/fail the TaskResult |
|
|
169
|
+
| `Store#observe_execution` | Return an `ExecutionObservation` containing the saved status and error | Raise when observation cannot be completed |
|
|
170
|
+
|
|
171
|
+
The exact-execution rule also applies to other confirmed terminal states,
|
|
172
|
+
including cancellation. `resume` returns an already terminal execution without
|
|
173
|
+
running that Agent again. `start_reserved_async` also reuses a terminal result
|
|
174
|
+
when its reservation, input and saved output contract match. Output validation
|
|
175
|
+
remains strict: a failed result is not validated output and must not be treated
|
|
176
|
+
as a successful Agent response.
|
|
177
|
+
|
|
178
|
+
The existing completion callback receives `(result, nil)` when the terminal
|
|
179
|
+
result was obtained, even when `result[:status] == :failed`. An `error` in
|
|
180
|
+
`on_complete` means that the exact-execution operation could not deliver a
|
|
181
|
+
confirmed result. Examples include a persistence read failure, mismatched
|
|
182
|
+
ownership or reservation, and an unresolved execution requiring recovery or
|
|
183
|
+
approval wiring. Such errors do not manufacture a failed execution record.
|
|
184
|
+
The ordinary Agent event listener and its existing error policy are unchanged.
|
|
185
|
+
|
|
186
|
+
Applications that need the saved failure raised explicitly can use the existing
|
|
187
|
+
observation conversion after receiving the result:
|
|
188
|
+
|
|
189
|
+
```ruby
|
|
190
|
+
result = agent.resume(execution_id)
|
|
191
|
+
observation = Phronomy::Agent::ExecutionObservation.from_result(result)
|
|
192
|
+
observation.value!
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
For a failed output contract, `value!` restores and raises `OutputError` with its
|
|
196
|
+
saved diagnostic. Coordination code instead inspects `status` and `error` before
|
|
197
|
+
deciding whether to fail the parent, skip the child or continue. This keeps that
|
|
198
|
+
policy with the caller rather than the child Agent.
|
|
199
|
+
|
|
200
|
+
For the F0 child-output failure, result delivery is conditional on reading the
|
|
201
|
+
committed Agent execution and its diagnostic through Agent Persistence. After
|
|
202
|
+
F4 Runtime/process loss, the same identity and readable saved result permit
|
|
203
|
+
re-observation without rerunning that terminal child. Local callbacks themselves
|
|
204
|
+
are not persisted, and this contract makes no X0 external-effect exactly-once
|
|
205
|
+
guarantee. Persistence/ownership failures and unfinished executions retain their
|
|
206
|
+
existing recovery requirements.
|
|
207
|
+
|
|
151
208
|
## Generation evaluation
|
|
152
209
|
|
|
153
210
|
`GeneratorVerifier.new` and `.open` accept `schema_delivery: :native` (default) or
|
data/docs/features.md
CHANGED
|
@@ -73,6 +73,7 @@ Backend authors continue to implement the synchronous SPI only.
|
|
|
73
73
|
|---|---|
|
|
74
74
|
| **EventLoop** — Runtime-owned event-driven execution core shared by Agent, ToolInvocation, Workflow, and MultiAgent sessions; single writer for Phronomy-managed live Agent execution state | Beta |
|
|
75
75
|
| **Agent execution result authority** — Session-local routing plus current FSM state and purpose-specific semantic IDs (`llm_call_id`, `tool_invocation_id`) reject stale async results | Beta |
|
|
76
|
+
| **Exact Agent execution results** — `start_reserved_async`, `resume_async` and `resume` return confirmed terminal results, including saved `OutputError` failures, separately from operation failures; [contract and migration](architecture/structured-output-and-scope.md#exact-execution-results) | Beta (behavior changed in v0.37.0) |
|
|
76
77
|
| **Agent scope and unload** — `Agent.open_scope` owns newly acquired Agents; `unload_async` / `unload!` release idle incarnations without changing saved state, with typed invalidation and cleanup failures; [contract](architecture/dx05-agent-scope.md) | Beta |
|
|
77
78
|
| **Agent live ownership/admission** — Runtime owns one mutable live Agent per `agent_id`; EventLoop rejects competing same-Agent top-level executions while suspension retains the logical execution slot; Persistence admission remains durable defense | Beta |
|
|
78
79
|
| **Workflow durable admission** — Same-process admission is keyed by durable `workflow_instance_id` from pre-hydration admission through the durable terminal/halted save barrier; admission-owner representation is Runtime-internal | Beta |
|
|
@@ -33,6 +33,11 @@ module Phronomy
|
|
|
33
33
|
end
|
|
34
34
|
end
|
|
35
35
|
|
|
36
|
+
# Starts or observes the reserved execution and returns its committed result.
|
|
37
|
+
# Failed executions, including OutputError, fulfill the Task with status
|
|
38
|
+
# and error details. Admission, recovery and observation errors reject it.
|
|
39
|
+
# @return [Phronomy::TaskResult] the exact execution result
|
|
40
|
+
# @api public
|
|
36
41
|
def start_reserved_async(reservation:, input:, config: {}, output_schema: nil, schema_delivery: nil)
|
|
37
42
|
__with_operation(async: true) do
|
|
38
43
|
unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
|
|
@@ -44,6 +49,11 @@ module Phronomy
|
|
|
44
49
|
end
|
|
45
50
|
end
|
|
46
51
|
|
|
52
|
+
# Continues an existing execution or returns its committed terminal result.
|
|
53
|
+
# A saved failed/cancelled result is a fulfilled observation; an inability
|
|
54
|
+
# to resume or observe the execution remains an operation error.
|
|
55
|
+
# @return [Phronomy::TaskResult] the exact execution result
|
|
56
|
+
# @api public
|
|
47
57
|
def resume_async(execution_id, config: {})
|
|
48
58
|
__with_operation(async: true) do
|
|
49
59
|
config = __invocation_config(_prepare_invocation_config(config, nil))
|
|
@@ -51,6 +61,9 @@ module Phronomy
|
|
|
51
61
|
end
|
|
52
62
|
end
|
|
53
63
|
|
|
64
|
+
# Waits for the same committed result returned by resume_async.
|
|
65
|
+
# @return [Hash] execution status, output and saved error details
|
|
66
|
+
# @api public
|
|
54
67
|
def resume(execution_id, config: {})
|
|
55
68
|
__with_operation(wait_on_shutdown: false) do
|
|
56
69
|
_check_event_loop_reentrancy(:resume, :resume_async)
|
|
@@ -180,9 +180,8 @@ module Phronomy
|
|
|
180
180
|
|
|
181
181
|
def materialize(execution)
|
|
182
182
|
result = @agent.persistence.result(execution.execution_id)
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
end
|
|
183
|
+
# A committed failure is an observed outcome, not an observation error.
|
|
184
|
+
# Callers decide how that outcome affects their own execution.
|
|
186
185
|
result.merge(output: result[:result]).freeze
|
|
187
186
|
end
|
|
188
187
|
end
|
data/lib/phronomy/version.rb
CHANGED
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: phronomy
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.
|
|
4
|
+
version: 0.37.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Raizo T.C.S
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2026-11-
|
|
11
|
+
date: 2026-11-21 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: ruby_llm
|