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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: df772de1d87db545ebab3d68e344c1a040811d07188f597d90589c6bc5cdd0c6
4
- data.tar.gz: d34df90ebd9d088fe285bf3cf96cc10b95ad31cd3996acd15ecfc058845a3d95
3
+ metadata.gz: ea854d0434bfc24dd1bb49dc2420ead34b2a1ba1e0b5f9749e96cb91b0bc9108
4
+ data.tar.gz: 5fe68a72f9a4f7856f82ef564a0326b2d121d420bc7fa80b81d268430768b8a4
5
5
  SHA512:
6
- metadata.gz: 30d8b3679b309a2b8f90542db5a3b6fb0b6d8dde75b640d329653012a636bd86ca8f93e23f894fe8afb9f2d527900765c5d001f5e06d83d53aefa030b0e555b5
7
- data.tar.gz: c2d954341d08dca5b0e4721ea7573ea9ab7ffd114acccc83403140b5667513659f9ebff5c356bca55388be3f9fff8ab02d7e66852e3f33b37e19f32ed715324e
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.36.0.
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
@@ -4,7 +4,7 @@
4
4
 
5
5
  | Version | Supported |
6
6
  |---------|-----------|
7
- | 0.36.0 (latest release) | ✅ |
7
+ | 0.37.0 (latest release) | ✅ |
8
8
  | Older versions | ❌ — please upgrade |
9
9
 
10
10
  Only the latest released version of `phronomy` receives security patches. If you
@@ -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 final-output semantics apply to sync/async and invoke/stream.
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)
@@ -330,7 +330,7 @@ module Phronomy
330
330
  "tool_call_id" => invocation.tool_call_id.to_s
331
331
  },
332
332
  llm_call_id: @tool_batch_llm_call_id
333
- }.compact
333
+ }
334
334
  )
335
335
  )
336
336
  end
@@ -180,9 +180,8 @@ module Phronomy
180
180
 
181
181
  def materialize(execution)
182
182
  result = @agent.persistence.result(execution.execution_id)
183
- if result[:error].is_a?(Hash) && result[:error]["class"] == "Phronomy::Agent::OutputError"
184
- raise RecoverySupport.error_from_failure(result[:error])
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
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Phronomy
4
- VERSION = "0.36.0"
4
+ VERSION = "0.37.0"
5
5
  end
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.36.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-19 00:00:00.000000000 Z
11
+ date: 2026-11-21 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: ruby_llm