b3-prosaic-runtime 0.9.4__tar.gz → 0.9.6__tar.gz

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.9.6 — 2026-10-17
+
+- Add opt-in host-controlled final-answer phases after a bounded number of tool rounds.
+- Add optional oMLX native tool-call envelope constraints, removed for final answers.
+- Validate envelope configuration before dispatch and reject further tool calls after finalization.
+- Retain native grant, budget and argument checks; defaults remain unchanged.
+
 ## 0.9.3 — 2026-10-14
 
 - Normalize negative provider timeout exit statuses to 124 in conversation turn

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b3-prosaic-runtime
-Version: 0.9.4
+Version: 0.9.6
 Summary: Bounded execution of neutral Prosaic agents on OpenAI-compatible and native Anthropic endpoints
 Author: B3 Cognition
 License-Expression: Apache-2.0
@@ -28,6 +28,42 @@ and the `prosaic-runtime` CLI remain unchanged. The separately installed recorde
 is `b3-prosaic-runtime-postgres` **0.3.0**, selecting Runtime 0.9.x.
 Candidates are not public index releases until the release qualification gate passes.
 
+### Opt-in final-answer phase
+
+The local `0.9.3+finalize.4` candidate adds an operator-controlled endpoint
+feature for bounded lookup workflows:
+
+```yaml
+features:
+  finalize_after_tool_rounds: 1
+```
+
+After that many tool rounds, the next OpenAI-compatible or native Anthropic
+request contains no tool declarations and receives trusted final-answer
+guidance. A provider that still requests a tool fails with
+`tool_finalization_not_honored` before another handler runs. Existing provider,
+tool, token and time budgets still apply; allow capacity for the final request.
+Cancellation or exhausted budgets can stop before that request. Missing usage
+remains unknown. This setting does not assert that the evidence is sufficient
+or that the final answer is correct.
+
+The value must be an integer from one through the invocation's effective
+`max_tool_rounds`. Omit it to retain existing multi-round and no-progress
+behavior. Agent prose and model output cannot set this host configuration.
+This candidate is for pinned-wheel qualification, not a published release.
+
+For an oMLX endpoint serving Qwen JSON tool envelopes, the host can also set
+`omlx_tool_call_envelope: true`. This requires an explicit
+`finalize_after_tool_rounds` and requests oMLX's `structured_outputs.regex`
+constraint while tools are offered. It forces a tool envelope rather than an
+ordinary answer during that phase; the final request removes this constraint.
+`json_mode` applies to the final answer and is suppressed during the tool phase.
+Native Anthropic rejects this vendor-specific setting before dispatch. Other
+servers may reject or ignore it; this is not a portable OpenAI protocol option.
+The constraint covers the envelope, not argument correctness or task quality.
+Runtime still validates native tool names, arguments, permissions and budgets.
+Assistant text is never converted to a tool call by this setting.
+
 The optional [stateless conversation API](docs/conversations.md) uses complete,
 bounded portable history through `prepare_turn()` and `turn()`. It requires no
 workspace for ordinary callbacks or tool-free turns. Durable sessions and human
@@ -695,3 +731,5 @@ budget as a durable ledger or reset uncertain allowances after a restart.
 PostgreSQL accounting remains the authoritative provider-call evidence. Saved
 host outcomes require a fenced ToolJournal or equivalent durable application
 repository; interrupted effects must not be repeated automatically.
+
+See [execution correlation and graceful drain](docs/execution-lifecycle.md) for the host shutdown contract.

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/README.md

@@ -6,6 +6,42 @@ and the `prosaic-runtime` CLI remain unchanged. The separately installed recorde
 is `b3-prosaic-runtime-postgres` **0.3.0**, selecting Runtime 0.9.x.
 Candidates are not public index releases until the release qualification gate passes.
 
+### Opt-in final-answer phase
+
+The local `0.9.3+finalize.4` candidate adds an operator-controlled endpoint
+feature for bounded lookup workflows:
+
+```yaml
+features:
+  finalize_after_tool_rounds: 1
+```
+
+After that many tool rounds, the next OpenAI-compatible or native Anthropic
+request contains no tool declarations and receives trusted final-answer
+guidance. A provider that still requests a tool fails with
+`tool_finalization_not_honored` before another handler runs. Existing provider,
+tool, token and time budgets still apply; allow capacity for the final request.
+Cancellation or exhausted budgets can stop before that request. Missing usage
+remains unknown. This setting does not assert that the evidence is sufficient
+or that the final answer is correct.
+
+The value must be an integer from one through the invocation's effective
+`max_tool_rounds`. Omit it to retain existing multi-round and no-progress
+behavior. Agent prose and model output cannot set this host configuration.
+This candidate is for pinned-wheel qualification, not a published release.
+
+For an oMLX endpoint serving Qwen JSON tool envelopes, the host can also set
+`omlx_tool_call_envelope: true`. This requires an explicit
+`finalize_after_tool_rounds` and requests oMLX's `structured_outputs.regex`
+constraint while tools are offered. It forces a tool envelope rather than an
+ordinary answer during that phase; the final request removes this constraint.
+`json_mode` applies to the final answer and is suppressed during the tool phase.
+Native Anthropic rejects this vendor-specific setting before dispatch. Other
+servers may reject or ignore it; this is not a portable OpenAI protocol option.
+The constraint covers the envelope, not argument correctness or task quality.
+Runtime still validates native tool names, arguments, permissions and budgets.
+Assistant text is never converted to a tool call by this setting.
+
 The optional [stateless conversation API](docs/conversations.md) uses complete,
 bounded portable history through `prepare_turn()` and `turn()`. It requires no
 workspace for ordinary callbacks or tool-free turns. Durable sessions and human
@@ -673,3 +709,5 @@ budget as a durable ledger or reset uncertain allowances after a restart.
 PostgreSQL accounting remains the authoritative provider-call evidence. Saved
 host outcomes require a fenced ToolJournal or equivalent durable application
 repository; interrupted effects must not be repeated automatically.
+
+See [execution correlation and graceful drain](docs/execution-lifecycle.md) for the host shutdown contract.

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/docs/tool-effects.md

@@ -72,7 +72,7 @@ matching lowercase 64-hex signature and one of these closed states:
 | State | Permitted fields | Runtime action |
 | --- | --- | --- |
 | `new` | Bounded nonempty `claim_token`; no outcome | Dispatch the effect once. |
-| `replay` | No token; finite bounded `{'status': 'ok', 'result': ...}` outcome | Copy and return the recorded outcome. |
+| `replay` | No token; finite bounded `{'status': 'ok', 'result': ...}` or `{'status': 'error', 'error': code}` outcome | Copy and return the recorded outcome. |
 | `uncertain` | No token or outcome | Stop pending explicit host resolution. |
 
 The journal must atomically claim the namespace/key address and commit using a
@@ -112,3 +112,11 @@ or domain idempotency/fencing.
 The SQLite journal under `tests/support/` is test support only. Production business
 journals belong to host applications; usage recorders and Harness checkpoints are
 separate stores and responsibilities.
+
+A callback may return the public `ToolFailure("read_unavailable")` only for a
+proven completed failure. Its bounded machine code is journaled before cancellation
+or deadline checks; completion evidence is `completed` or `replayed`, never an
+assertion that the requested business operation succeeded. NEVER return this type
+for an unknown effect. ALWAYS leave generic exceptions and lost acknowledgements
+on the uncertain-effect path. Ordinary returned dictionaries remain successful
+JSON data and are not interpreted as this explicit failure contract.

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "b3-prosaic-runtime"
-version = "0.9.4"
+version = "0.9.6"
 description = "Bounded execution of neutral Prosaic agents on OpenAI-compatible and native Anthropic endpoints"
 requires-python = ">=3.11"
 readme = "README.md"

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/scripts/conversation_wheel_smoke.py

@@ -22,7 +22,7 @@ def ownership():
     import prosaic_runtime as api
     import prosaic_runtime_postgres as recorder
     for module, distribution, version in ((prosaic, 'b3-prosaic', '0.4.1'),
-            (api, 'b3-prosaic-runtime', '0.9.4'),
+            (api, 'b3-prosaic-runtime', '0.9.6'),
             (recorder, 'b3-prosaic-runtime-postgres', '0.3.0')):
         owner = metadata.distribution(distribution)
         assert module.__version__ == owner.version == version

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/scripts/production_wheel_smoke.py

@@ -49,7 +49,7 @@ def installed_origins():
     owners = {}
     origins = {}
     for package, name, version in ((prosaic, "b3-prosaic", "0.4.1"),
-            (runtime, "b3-prosaic-runtime", "0.9.4"),
+            (runtime, "b3-prosaic-runtime", "0.9.6"),
             (postgres, "b3-prosaic-runtime-postgres", "0.3.0")):
         owner = metadata.distribution(name)
         assert owner.version == package.__version__ == version

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/b3_prosaic_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: b3-prosaic-runtime
-Version: 0.9.4
+Version: 0.9.6
 Summary: Bounded execution of neutral Prosaic agents on OpenAI-compatible and native Anthropic endpoints
 Author: B3 Cognition
 License-Expression: Apache-2.0
@@ -28,6 +28,42 @@ and the `prosaic-runtime` CLI remain unchanged. The separately installed recorde
 is `b3-prosaic-runtime-postgres` **0.3.0**, selecting Runtime 0.9.x.
 Candidates are not public index releases until the release qualification gate passes.
 
+### Opt-in final-answer phase
+
+The local `0.9.3+finalize.4` candidate adds an operator-controlled endpoint
+feature for bounded lookup workflows:
+
+```yaml
+features:
+  finalize_after_tool_rounds: 1
+```
+
+After that many tool rounds, the next OpenAI-compatible or native Anthropic
+request contains no tool declarations and receives trusted final-answer
+guidance. A provider that still requests a tool fails with
+`tool_finalization_not_honored` before another handler runs. Existing provider,
+tool, token and time budgets still apply; allow capacity for the final request.
+Cancellation or exhausted budgets can stop before that request. Missing usage
+remains unknown. This setting does not assert that the evidence is sufficient
+or that the final answer is correct.
+
+The value must be an integer from one through the invocation's effective
+`max_tool_rounds`. Omit it to retain existing multi-round and no-progress
+behavior. Agent prose and model output cannot set this host configuration.
+This candidate is for pinned-wheel qualification, not a published release.
+
+For an oMLX endpoint serving Qwen JSON tool envelopes, the host can also set
+`omlx_tool_call_envelope: true`. This requires an explicit
+`finalize_after_tool_rounds` and requests oMLX's `structured_outputs.regex`
+constraint while tools are offered. It forces a tool envelope rather than an
+ordinary answer during that phase; the final request removes this constraint.
+`json_mode` applies to the final answer and is suppressed during the tool phase.
+Native Anthropic rejects this vendor-specific setting before dispatch. Other
+servers may reject or ignore it; this is not a portable OpenAI protocol option.
+The constraint covers the envelope, not argument correctness or task quality.
+Runtime still validates native tool names, arguments, permissions and budgets.
+Assistant text is never converted to a tool call by this setting.
+
 The optional [stateless conversation API](docs/conversations.md) uses complete,
 bounded portable history through `prepare_turn()` and `turn()`. It requires no
 workspace for ordinary callbacks or tool-free turns. Durable sessions and human
@@ -695,3 +731,5 @@ budget as a durable ledger or reset uncertain allowances after a restart.
 PostgreSQL accounting remains the authoritative provider-call evidence. Saved
 host outcomes require a fenced ToolJournal or equivalent durable application
 repository; interrupted effects must not be repeated automatically.
+
+See [execution correlation and graceful drain](docs/execution-lifecycle.md) for the host shutdown contract.

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/b3_prosaic_runtime.egg-info/SOURCES.txt

@@ -94,6 +94,7 @@ src/prosaic_runtime/events.py
 src/prosaic_runtime/execution.py
 src/prosaic_runtime/execution_budget.py
 src/prosaic_runtime/http_bounds.py
+src/prosaic_runtime/lifecycle.py
 src/prosaic_runtime/openai_compatible.py
 src/prosaic_runtime/openai_compatible_compaction.py
 src/prosaic_runtime/openai_compatible_filters.py
@@ -131,6 +132,7 @@ tests/test_conformance.py
 tests/test_context_assembly.py
 tests/test_context_contracts.py
 tests/test_context_execution.py
+tests/test_controlled_tool_failure.py
 tests/test_conversation_bounds.py
 tests/test_conversation_contracts.py
 tests/test_conversation_distribution.py
@@ -144,9 +146,13 @@ tests/test_custom_tools.py
 tests/test_distribution_metadata.py
 tests/test_execution_budget.py
 tests/test_features.py
+tests/test_finalization.py
 tests/test_http_boundaries.py
+tests/test_http_correlation.py
 tests/test_input_boundary.py
 tests/test_invocation_budgets.py
+tests/test_lifecycle.py
+tests/test_omlx_tool_envelope.py
 tests/test_package_compatibility.py
 tests/test_production_smoke.py
 tests/test_prompt_injection.py

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/__init__.py

@@ -1,5 +1,5 @@
 """Execute neutral Prosaic artifacts with explicitly granted authority."""
-__version__ = '0.9.4'
+__version__ = '0.9.6'
 
 from .artifacts import ProsaicArtifact
 from .config import EndpointConfig, RuntimeConfig, RunLimits, CliSandboxConfig
@@ -9,7 +9,7 @@ from .types import Result
 from .tools import CustomTool, validate_custom_tools, custom_descriptors
 from .admission import validate_execution_artifact
 from .operation_context import InvocationScope, ToolExecutionContext
-from .tool_effects import ToolClaim, ToolJournal, tool_journal_descriptor
+from .tool_effects import ToolFailure, ToolClaim, ToolJournal, tool_journal_descriptor
 from .telemetry import ObserverEmitter
 from .conformance import evaluate_conformance
 
@@ -44,3 +44,8 @@ from .context_counters import (TokenCounter, TokenCounterRegistration,
 __all__ += ["ContextPolicy", "TokenCounterDescriptor", "ContextAssemblyReport",
     "ContextSelection", "ContextWorkState", "TokenCounter", "TokenCounterRegistration",
     "TokenCounterRegistry"]
+
+from .lifecycle import ExecutionLifecycle, Draining
+__all__ += ["ExecutionLifecycle", "Draining"]
+
+__all__ += ["ToolFailure"]

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/accounting_capture.py

@@ -44,6 +44,8 @@ class Capture:
             self.recorder.prepare(intent)
         except Exception as exc:
             raise AccountingError('intent persistence failed') from exc
+        request.add_header("X-Correlation-ID", call_id)
+        request.add_header("X-Client-Request-Id", call_id)
         self.call_ids.append(call_id)
         observer = AnthropicObservation if self.provider == 'anthropic' else Observation
         observation = observer(self.recorder, call_id, on_observation=self.on_observation)

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/adapter.py

@@ -11,6 +11,7 @@ import re
 import time
 
 from .runtime import ProsaicRuntime
+from .lifecycle import tracked
 from .policy import RunPolicy
 from .types import Result
 from .budgets import InvocationBudgetExceeded
@@ -162,6 +163,10 @@ class RuntimeAdapter:
     def config(self):
         return self.runtime.config
 
+    @property
+    def lifecycle(self):
+        return self.runtime.lifecycle
+
     @property
     def capabilities(self):
         return self.runtime.capabilities | frozenset({'runtime_adapter_v1'})
@@ -174,6 +179,7 @@ class RuntimeAdapter:
     def cli_tool_names(self):
         return self.runtime.cli_tool_names
 
+    @tracked
     def run(self, artifact, arguments='', *, policy=None, on_event=None, cancelled=None, **options):
         self.validate_binding()
         policy = policy or RunPolicy()

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/anthropic.py

@@ -23,7 +23,8 @@ API_VERSION = '2023-06-01'
 
 def validate_anthropic_controls(features, prompt_metadata):
     """Validate known Messages controls without constructing a model request."""
-    unsupported = {'json_mode', 'reasoning_effort', 'effort', 'thinking', 'stream_options', 'web_tools'}
+    unsupported = {'json_mode', 'reasoning_effort', 'effort', 'thinking', 'stream_options', 'web_tools',
+                   'omlx_tool_call_envelope'}
     for name in unsupported:
         value = features.get(name)
         if value not in (None, False, 'off', 'false', 'disabled'):

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/execution.py

@@ -57,6 +57,7 @@ class ExecutionBackend:
         identical_tool_rounds = 0
         tools_disabled = False
         tool_no_progress_forced = False
+        finalization_forced = False
         max_tool_rounds = _feature_int(
             llm.features,
             "max_tool_rounds",
@@ -71,6 +72,11 @@ class ExecutionBackend:
             minimum=2,
             maximum=10,
         )
+        finalize_after = llm.features.get('finalize_after_tool_rounds')
+        if 'finalize_after_tool_rounds' in llm.features and (
+            type(finalize_after) is not int or not 1 <= finalize_after <= max_tool_rounds
+        ):
+            raise ValueError('finalize_after_tool_rounds must be an integer between 1 and max_tool_rounds')
         run_started = time.monotonic()
 
         while True:
@@ -192,6 +198,21 @@ class ExecutionBackend:
                         },
                     )
             if turn.tool_calls:
+                if finalization_forced:
+                    return CliRunResult(
+                        exit_code=1, stdout='',
+                        stderr='model requested tools during final-answer phase',
+                        token_usage=token_usage,
+                        metadata={
+                            'provider': self.name,
+                            'provider_error_code': 'tool_finalization_not_honored',
+                            'failure_reason': 'tool_finalization_not_honored',
+                            'tool_call_count': tool_call_count,
+                            'tool_rounds': tool_rounds,
+                            'token_usage_details': token_usage_details,
+                            **_transcript_metadata(transcript),
+                        },
+                    )
                 if initial_messages is not None:
                     if turn.finish_reason not in {'tool_calls', 'tool_use'}:
                         return CliRunResult(1, '', 'incomplete tool batch', token_usage=token_usage,
@@ -339,7 +360,13 @@ class ExecutionBackend:
                 if acquiring:
                     messages.append({'role': 'user', 'content': prompt_metadata['final_prompt']})
                     emit('acquisition_completed', tool=initial_tool, turn=turn_number)
-                if identical_tool_rounds >= max_identical_tool_rounds:
+                if finalize_after is not None and tool_rounds >= finalize_after:
+                    tools_disabled = True
+                    finalization_forced = True
+                    messages.append({'role': 'system', 'content':
+                        'The tool phase has ended. Return the requested final answer using '
+                        'the information available. Do not request any more tools.'})
+                elif identical_tool_rounds >= max_identical_tool_rounds:
                     tools_disabled = True
                     tool_no_progress_forced = True
                     initial_guidance = messages[0].get("content")

b3_prosaic_runtime-0.9.6/src/prosaic_runtime/lifecycle.py

@@ -0,0 +1,85 @@
+"""Cooperative admission and drain for synchronous execution and persistence.
+
+Hosts own signal handlers and must wait before closing stores or cancelling work.
+A timeout reports unfinished work; it never cancels or kills admitted execution.
+"""
+from contextlib import contextmanager
+from functools import wraps
+import math
+import threading
+import time
+
+
+class Draining(RuntimeError):
+    """New root execution was refused because its lifecycle is draining."""
+
+
+class ExecutionLifecycle:
+    def __init__(self):
+        self._condition = threading.Condition()
+        self._local = threading.local()
+        self._draining = False
+        self._active = 0
+
+    @property
+    def draining(self):
+        with self._condition:
+            return self._draining
+
+    @property
+    def active(self):
+        with self._condition:
+            return self._active
+
+    @contextmanager
+    def work(self):
+        """Admit synchronous work; nested work on the admitted thread may finish."""
+        depth = getattr(self._local, 'depth', 0)
+        with self._condition:
+            if self._draining and not depth:
+                raise Draining('service-draining')
+            self._active += 1
+        self._local.depth = depth + 1
+        try:
+            yield
+        finally:
+            self._local.depth = depth
+            with self._condition:
+                self._active -= 1
+                self._condition.notify_all()
+
+    def begin(self):
+        """Permanently fence new root work. Does not cancel admitted work."""
+        with self._condition:
+            self._draining = True
+            self._condition.notify_all()
+
+    def wait(self, timeout=None):
+        """Fence and wait through persistence; return False on an optional timeout.
+
+        Call from a separate supervisor thread, never inside admitted work.
+        Nested admission is thread-scoped, not inherited by new worker threads.
+        """
+        if getattr(self._local, 'depth', 0):
+            raise RuntimeError('cannot wait for own admitted execution')
+        if timeout is not None and (isinstance(timeout, bool) or not isinstance(timeout, (int, float))
+                                   or not math.isfinite(timeout) or timeout < 0):
+            raise ValueError('timeout must be finite and nonnegative')
+        deadline = None if timeout is None else time.monotonic() + timeout
+        self.begin()
+        with self._condition:
+            while self._active:
+                remaining = None if deadline is None else deadline - time.monotonic()
+                if remaining is not None and remaining <= 0:
+                    return False
+                self._condition.wait(remaining)
+            return True
+
+
+def tracked(method):
+    """Track a synchronous operation on its owner's public lifecycle."""
+    @wraps(method)
+    def execute(self, *args, **kwargs):
+        with self.lifecycle.work():
+            return method(self, *args, **kwargs)
+    return execute

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/openai_compatible.py

@@ -229,6 +229,7 @@ class OpenAICompatibleBackend(ExecutionBackend):
 
     def run_prompt(self, request: CliRunRequest) -> CliRunResult:
         llm = self._config
+        _omlx_tool_envelope(llm.features)
         assert llm.base_url is not None
         assert llm.model is not None
         prompt_metadata = _prompt_metadata(request)
@@ -409,6 +410,12 @@ class OpenAICompatibleBackend(ExecutionBackend):
         if tools:
             payload["tools"] = tools
             payload["tool_choice"] = "auto"
+        envelope = _omlx_tool_envelope(llm.features)
+        if envelope and tools:
+            # oMLX constrains generation; only native tool_calls may execute.
+            # An answer JSON grammar cannot also constrain the tool envelope.
+            payload.pop('response_format', None)
+            payload['structured_outputs'] = {'regex': r'<tool_call>\s*\{[\s\S]*\}\s*</tool_call>'}
         if streaming:
             payload["stream"] = True
             if _feature_enabled(llm.features, "stream_options", default=True):
@@ -1514,6 +1521,16 @@ def _api_key(
     return token, ""
 
 
+def _omlx_tool_envelope(features):
+    envelope = features.get('omlx_tool_call_envelope', False)
+    if type(envelope) is not bool or (envelope and (
+        type(features.get('finalize_after_tool_rounds')) is not int
+        or features['finalize_after_tool_rounds'] < 1
+    )):
+        raise ValueError('omlx_tool_call_envelope requires a boolean and explicit finalize_after_tool_rounds')
+    return envelope
+
+
 def _feature_enabled(
     features: dict[str, object], name: str, *, default: bool
 ) -> bool:

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/runtime.py

@@ -23,6 +23,7 @@ from .cli_tools import load_cli_tools, cli_tool_context
 from .tool_registry import BoundedToolRegistry, DisabledBuiltinRegistry, InvalidToolRequest
 from .accounting import AccountingError, resolve_context
 from .accounting_capture import Capture, InvalidEvidence, strict_json
+from .lifecycle import ExecutionLifecycle, tracked
 from .http_bounds import LimitExceeded, set_response_timeout, BoundedNativeStream
 from .operation_context import InvocationScope
 from .tool_effects import admit_tool_effects, ToolEffectFailure
@@ -209,6 +210,10 @@ class _BoundedMixin:
         observe('provider_request_started')
         outcome = 'execution_failure'
         status = None
+        if self.capture is None:
+            call_id = uuid4().hex
+            request.add_header("X-Correlation-ID", call_id)
+            request.add_header("X-Client-Request-Id", call_id)
         opener = urllib.request.build_opener(_NoRedirect())
         try:
             # Observers and persisted intent preparation can stop execution.
@@ -338,9 +343,12 @@ class ProsaicRuntime:
     capabilities = frozenset({'conformance_v1', 'invocation_budgets_v1', 'observer_v1', 'accounting_v1', 'read_receipts_v1', 'initial_tool_v1', 'initial_tool_enforcement_v1', 'acquisition_v1', 'custom_tools_v1', 'cli_tools_v1', 'cli_sandbox_v1'})
     capabilities |= frozenset({'tool_context_v1', 'tool_journal_v1'})
     capabilities |= frozenset({'conversation_turn_v1'})
-    capabilities |= frozenset({'context_assembly_v1'})
+    capabilities |= frozenset({'context_assembly_v1', 'http_correlation_v1', 'execution_lifecycle_v1'})
     def __init__(self, config: RuntimeConfig, *, source=".prosaic", executable="prosaic", custom_tools=None,
-                 accounting=None, context_defaults=None):
+                 accounting=None, context_defaults=None, lifecycle=None):
+        self.lifecycle = lifecycle if lifecycle is not None else ExecutionLifecycle()
+        if not isinstance(self.lifecycle, ExecutionLifecycle):
+            raise TypeError("lifecycle must be an ExecutionLifecycle")
         self.config = config
         self.source = Path(source)
         self.executable = executable
@@ -371,6 +379,7 @@ class ProsaicRuntime:
                             context_selection=context_selection, context_report=context_report,
                             context_work=context_work)
 
+    @tracked
     def turn(self, artifact, *, message=None, history=(), input_data=None,
              policy=None, limits=None, workspace=None, on_event=None, cancelled=None,
              env=None, context=None, accounting=None, observer=None,
@@ -540,6 +549,7 @@ class ProsaicRuntime:
         return self._preflight_names(names, str(Path(cwd).resolve()), policy,
                                      dict(os.environ if env is None else env), deadline)
 
+    @tracked
     def run(self, artifact: str | ProsaicArtifact, arguments: str = "", *,
             cwd: str | Path = '.', policy: RunPolicy | None = None,
             on_event=None, cancelled=None, env=None,

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/tool_effects.py

@@ -8,6 +8,28 @@ from typing import Protocol
 from .operation_context import InvocationScope, bounded_reference
 
 
+@dataclass(frozen=True)
+class ToolFailure:
+    """A trusted callback's proven completed failure, never an unknown effect.
+
+    Return only after establishing that the operation failed deterministically.
+    Generic exceptions and lost acknowledgements retain uncertain-effect fencing.
+    Codes are safe public machine identifiers, never raw exception text.
+    """
+    code: str
+
+    def __post_init__(self):
+        if type(self.code) is not str or re.fullmatch(r'[a-z][a-z0-9_]{0,63}', self.code) is None:
+            raise ValueError('invalid controlled tool failure code')
+
+
+def failure_outcome(value):
+    if type(value) is ToolFailure:
+        ToolFailure.__post_init__(value)
+        return {'status': 'error', 'error': value.code}
+    return {'status': 'ok', 'result': value}
+
+
 @dataclass(frozen=True)
 class ToolClaim:
     state: str
@@ -79,7 +101,11 @@ def canonical_json(value):
 
 def snapshot_outcome(outcome, maximum):
     from .tools import depth
-    if type(outcome) is not dict or set(outcome) != {'status', 'result'} or outcome['status'] != 'ok':
+    if type(outcome) is not dict:
+        raise ValueError('invalid committed outcome')
+    if set(outcome)=={'status','error'} and outcome['status']=='error':
+        ToolFailure(outcome['error'])
+    elif set(outcome)!={'status','result'} or outcome['status']!='ok':
         raise ValueError('invalid committed outcome')
     depth(outcome)
     serialized = canonical_json(outcome)

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/src/prosaic_runtime/tools.py

@@ -11,7 +11,7 @@ from jsonschema.exceptions import ValidationError, SchemaError
 from .events import Cancelled
 from .policy import BUILTIN_TOOLS
 from .operation_context import ToolExecutionContext, bounded_reference
-from .tool_effects import ToolEffectFailure, canonical_json, snapshot_outcome, validate_claim
+from .tool_effects import ToolEffectFailure, canonical_json, snapshot_outcome, validate_claim, failure_outcome
 
 
 class ToolDeadlineExceeded(TimeoutError):
@@ -168,8 +168,8 @@ def parse_arguments(raw, schema, maximum):
 
 def bounded_result(value, maximum):
     try:
-        depth(value)
-        envelope = {'status': 'ok', 'result': value}
+        envelope = failure_outcome(value)
+        depth(envelope['result'] if envelope['status']=='ok' else envelope)
         text = json.dumps(envelope, allow_nan=False)
         if len(text.encode('utf-8')) > maximum:
             return {'status': 'error', 'error': 'result_limit'}
@@ -250,7 +250,7 @@ def execute_custom_tool(tool, raw_arguments, *, check_boundary, scope=None,
         check_boundary()
         try:
             value = invoke(tool.handler, context)
-            outcome = snapshot_outcome({'status': 'ok', 'result': value}, tool.max_result_bytes)
+            outcome = snapshot_outcome(failure_outcome(value), tool.max_result_bytes)
         except Exception:
             # Dispatch errors and unusable results cannot establish completion.
             if on_completion is not None:

{b3_prosaic_runtime-0.9.4 → b3_prosaic_runtime-0.9.6}/tests/test_conformance.py

@@ -44,7 +44,7 @@ def test_canonical_order_owned_snapshot_and_source_version():
     encode = lambda value: json.dumps(value, sort_keys=True, ensure_ascii=False,
                                      separators=(',', ':'), allow_nan=False)
     assert encode(a) == encode(b)
-    assert a['version'] == 1 and a['runtimeVersion'] == '0.9.4'
+    assert a['version'] == 1 and a['runtimeVersion'] == '0.9.6'
     assert tuple(case['id'] for case in a['cases']) == CASES
     assert a['cases'][0]['origin'] == 'fixture'
     assert a['cases'][1]['state'] == 'not_run'