nighthawk-python 0.13.0__py3-none-any.whl → 0.14.0__py3-none-any.whl

nighthawk/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from . import oversight, resilience
+from . import lifecycle, oversight, resilience
 from .composition import UNSET, Extend, Merge, UnsetType
 from .configuration import (
     StepContextLimits,
@@ -20,11 +20,12 @@ from .errors import (
 from .json_renderer import JsonableValue, to_jsonable_value
 from .natural.decorator import get_transformed_function, natural_function
 from .runtime.scoping import (
-    ExecutionRef,
+    ExecutionReference,
     UsageMeter,
     get_capabilities,
-    get_execution_ref,
+    get_execution_reference,
     get_implicit_references,
+    get_lifecycle,
     get_oversight,
     get_step_executor,
     get_system_prompt_suffix_fragments,
@@ -46,7 +47,7 @@ __all__ = [
     "ToolNameConflictError",
     "AgentStepExecutor",
     "ExecutionError",
-    "ExecutionRef",
+    "ExecutionReference",
     "JsonableValue",
     "NaturalParseError",
     "NighthawkError",
@@ -62,7 +63,7 @@ __all__ = [
     "get_capabilities",
     "get_step_context",
     "get_usage_meter",
-    "get_execution_ref",
+    "get_execution_reference",
     "get_implicit_references",
     "get_oversight",
     "get_step_executor",
@@ -70,6 +71,8 @@ __all__ = [
     "get_system_prompt_suffix_fragments",
     "get_user_prompt_suffix_fragments",
     "oversight",
+    "lifecycle",
+    "get_lifecycle",
     "natural_function",
     "get_transformed_function",
     "resilience",

nighthawk/errors.py

@@ -1,5 +1,10 @@
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .lifecycle import StepFailed
+
 
 class NighthawkError(Exception):
     """Base exception for all Nighthawk errors."""
@@ -10,7 +15,16 @@ class NaturalParseError(NighthawkError):
 
 
 class ExecutionError(NighthawkError):
-    """Raised when a Natural block execution fails."""
+    """Runtime failure exposing its terminal record and chaining the original error.
+
+    Internal helpers may supply a message; the runtime boundary attaches a
+    StepFailed record to every outward internal execution failure.
+    """
+
+    def __init__(self, failure: StepFailed | str, *, description: str | None = None) -> None:
+        self.step_failed = None if isinstance(failure, str) else failure
+        message = failure if isinstance(failure, str) else str(failure.original_exception)
+        super().__init__(f"{description}: {message}" if description else message)
 
 
 class ToolEvaluationError(NighthawkError):

nighthawk/lifecycle.py

@@ -0,0 +1,129 @@
+"""Terminal delivery for host-owned execution ledgers.
+
+Records snapshot collection structure, retaining the exact live Python values.
+Hosts own serialization, persistence, and deduplication by step_execution_id.
+Delivery is synchronous and attempted once, after caller binding assignments.
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Literal
+
+from .errors import NighthawkError
+from .runtime.execution_reference import ExecutionReference
+from .runtime.step_contract import StepKind, StepOutcome
+from .runtime.step_result import Break, Continue, Pass, Raise, Return, StepResult
+
+type FailureStage = Literal[
+    "preparation",
+    "executor",
+    "outcome_validation",
+    "binding_validation",
+    "return_inspection",
+    "return_evaluation",
+    "return_await",
+    "return_validation",
+    "commit_inspection",
+    "rewrite_validation",
+    "oversight_rejection",
+    "raise_resolution",
+    "raise_construction",
+    "binding_assignment",
+]
+
+
+@dataclass(frozen=True, kw_only=True)
+class _StepFinished:
+    execution_reference: ExecutionReference
+    processed_natural_program: str | None = None
+    input_binding_name_to_value: Mapping[str, object] | None = None
+    allowed_step_kinds: tuple[StepKind, ...] | None = None
+    assigned_binding_name_to_value: Mapping[str, object] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.execution_reference.step_execution_id is None or self.execution_reference.source_location is None:
+            raise ValueError("Terminal records require invocation and source identity")
+        for name in ("input_binding_name_to_value", "assigned_binding_name_to_value", "validated_binding_name_to_value"):
+            value = getattr(self, name, None)
+            if value is not None:
+                object.__setattr__(self, name, MappingProxyType(dict(value)))
+        if self.allowed_step_kinds is not None:
+            object.__setattr__(self, "allowed_step_kinds", tuple(self.allowed_step_kinds))
+
+
+@dataclass(frozen=True, kw_only=True)
+class StepCompleted(_StepFinished):
+    """A resolved control result whose generated assignments completed."""
+
+    outcome: Pass | Return | Break | Continue
+    kind: Literal["completed"] = field(default="completed", init=False)
+
+
+@dataclass(frozen=True, kw_only=True)
+class StepRaised(_StepFinished):
+    """An approved DSL Raise, with its successfully constructed exception."""
+
+    outcome: Raise
+    exception: BaseException
+    kind: Literal["raised"] = field(default="raised", init=False)
+
+
+@dataclass(frozen=True, kw_only=True)
+class StepFailed(_StepFinished):
+    """An ordinary execution failure, distinct from a DSL-selected Raise."""
+
+    failure_stage: FailureStage
+    original_exception: Exception
+    attempted_outcome: StepOutcome | StepResult | None = None
+    validated_binding_name_to_value: Mapping[str, object] | None = None
+    inspection_subject: Literal["return_expression", "step_commit", "tool_call"] | None = None
+    rejection_reason: str | None = None
+    kind: Literal["failed"] = field(default="failed", init=False)
+
+
+@dataclass(frozen=True, kw_only=True)
+class StepInterrupted(_StepFinished):
+    """Cancellation or process control; propagation takes priority over delivery."""
+
+    failure_stage: FailureStage
+    original_exception: BaseException
+    kind: Literal["interrupted"] = field(default="interrupted", init=False)
+
+
+type StepFinished = StepCompleted | StepRaised | StepFailed | StepInterrupted
+
+
+@dataclass(frozen=True)
+class StepLifecycle:
+    """Scoped synchronous notification, inherited with UNSET and cleared by None.
+
+    A callback may persist a record and raise a host exception referencing it.
+    Callback errors never trigger another execution notification or rollback.
+    Rethrowing the exact original exception preserves its existing cause.
+    Host deduplication must match both execution identity and the stored event.
+    """
+
+    on_step_finished: Callable[[StepFinished], None] | None = None
+
+
+class StepDeliveryError(NighthawkError):
+    """Host adapter delivery failure; does not assert that persistence succeeded."""
+
+    def __init__(self, execution_reference: ExecutionReference, cause: BaseException) -> None:
+        self.execution_reference = execution_reference
+        self.delivery_cause = cause
+        super().__init__(f"Step terminal delivery failed: {cause}")
+        self.__cause__ = cause
+
+
+__all__ = [
+    "FailureStage",
+    "StepCompleted",
+    "StepDeliveryError",
+    "StepFailed",
+    "StepFinished",
+    "StepInterrupted",
+    "StepLifecycle",
+    "StepRaised",
+]

nighthawk/natural/decorator.py

@@ -6,10 +6,12 @@ import logging
 import sys
 import textwrap
 from collections.abc import Awaitable, Callable
+from contextlib import AbstractContextManager
 from functools import wraps
+from types import FunctionType
 from typing import Any, cast
 
-from ..runtime.runner import Runner, StepEnvelope
+from ..runtime.runner import Runner
 from ..runtime.scoping import get_step_executor
 from ..runtime.step_context import python_cell_scope, python_name_scope
 from .blocks import extract_program, find_natural_blocks
@@ -20,48 +22,10 @@ type NaturalFunctionCallable = Callable[..., Any]
 
 class _RunnerProxy:
     @staticmethod
-    def run_step(
-        natural_program: str,
-        input_binding_names: list[str],
-        output_binding_names: list[str],
-        binding_name_to_type: dict[str, object],
-        return_annotation: object,
-        is_in_loop: bool,
-    ) -> StepEnvelope:
+    def execution() -> AbstractContextManager[Runner]:
         caller_frame = sys._getframe(1)
-        current_step_executor = get_step_executor()
-        runner = Runner(current_step_executor)
-        return runner.run_step(
-            natural_program,
-            input_binding_names,
-            output_binding_names,
-            binding_name_to_type,
-            return_annotation,
-            is_in_loop,
-            caller_frame=caller_frame,
-        )
-
-    @staticmethod
-    async def run_step_async(
-        natural_program: str,
-        input_binding_names: list[str],
-        output_binding_names: list[str],
-        binding_name_to_type: dict[str, object],
-        return_annotation: object,
-        is_in_loop: bool,
-    ) -> StepEnvelope:
-        caller_frame = sys._getframe(1)
-        current_step_executor = get_step_executor()
-        runner = Runner(current_step_executor)
-        return await runner.run_step_async(
-            natural_program,
-            input_binding_names,
-            output_binding_names,
-            binding_name_to_type,
-            return_annotation,
-            is_in_loop,
-            caller_frame=caller_frame,
-        )
+        runner = Runner(get_step_executor())
+        return runner.execution(caller_frame=caller_frame)
 
 
 def _extract_inline_fstring_name_set(function_source: str, *, function_name: str) -> set[str]:
@@ -222,6 +186,7 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
         original_module = ast.Module(body=[], type_ignores=[])
 
     capture_name_set = _build_capture_name_set(source, func.__name__)
+    capture_name_set.update(func.__code__.co_freevars)
 
     definition_frame = inspect.currentframe()
     name_to_value: dict[str, object] = {}
@@ -232,6 +197,13 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
                 if name in caller_frame.f_locals:
                     name_to_value[name] = caller_frame.f_locals[name]
 
+    original_name_to_cell = dict(zip(func.__code__.co_freevars, func.__closure__ or (), strict=True))
+    for name, cell in original_name_to_cell.items():
+        try:
+            name_to_value[name] = cell.cell_contents
+        except ValueError:
+            name_to_value[name] = None
+
     captured_name_tuple = tuple(sorted(capture_name_set))
 
     transformed_module = transform_module_ast(original_module, captured_name_tuple=captured_name_tuple)
@@ -267,6 +239,25 @@ def natural_function(func: NaturalFunctionCallable | None = None) -> NaturalFunc
     if not callable(transformed):
         raise RuntimeError("Transformed function not found after factory execution")
 
+    if transformed.__closure__ is not None:
+        # Preserve original Python cells, including nonlocal writes and late rebinding.
+        transformed = FunctionType(
+            transformed.__code__,
+            transformed.__globals__,
+            transformed.__name__,
+            transformed.__defaults__,
+            tuple(
+                original_name_to_cell.get(name, cell)
+                for name, cell in zip(
+                    transformed.__code__.co_freevars,
+                    transformed.__closure__,
+                    strict=True,
+                )
+            ),
+        )
+        transformed.__kwdefaults__ = func.__kwdefaults__
+        transformed.__annotations__ = func.__annotations__
+
     transformed_freevar_name_set = set(transformed.__code__.co_freevars)
     captured_name_set = set(factory_name_to_value.keys())
 

nighthawk/natural/transform.py

@@ -12,6 +12,12 @@ from .blocks import (
 )
 
 
+def _copy_generated_location(statement: ast.stmt, source: ast.AST) -> ast.stmt:
+    for child in ast.walk(statement):
+        ast.copy_location(child, source)
+    return statement
+
+
 class NaturalTransformer(ast.NodeTransformer):
     def __init__(self, *, captured_name_tuple: tuple[str, ...]) -> None:
         super().__init__()
@@ -58,7 +64,7 @@ class NaturalTransformer(ast.NodeTransformer):
                         sentinel_location.end_lineno = sentinel_location.lineno
                         sentinel_location.end_col_offset = sentinel_location.col_offset
 
-                        injected_with_location = [ast.copy_location(statement, sentinel_location) for statement in injected]
+                        injected_with_location = [_copy_generated_location(statement, sentinel_location) for statement in injected]
 
                         body_without_docstring = node.body[1:]
                         node.body = injected_with_location + body_without_docstring
@@ -201,7 +207,7 @@ class NaturalTransformer(ast.NodeTransformer):
                 sentinel_location.end_lineno = sentinel_location.lineno
                 sentinel_location.end_col_offset = sentinel_location.col_offset
 
-                return [ast.copy_location(statement, sentinel_location) for statement in statements]  # type: ignore[return-value]
+                return [_copy_generated_location(statement, sentinel_location) for statement in statements]  # type: ignore[return-value]
 
         if isinstance(value, ast.JoinedStr) and _joined_string_is_natural_sentinel(value):
             _validate_joined_string_bindings_do_not_span_formatted_values(value)
@@ -233,7 +239,7 @@ class NaturalTransformer(ast.NodeTransformer):
             sentinel_location.end_lineno = sentinel_location.lineno
             sentinel_location.end_col_offset = sentinel_location.col_offset
 
-            return [ast.copy_location(statement, sentinel_location) for statement in statements]  # type: ignore[return-value]
+            return [_copy_generated_location(statement, sentinel_location) for statement in statements]  # type: ignore[return-value]
 
         return node
 
@@ -300,7 +306,7 @@ def build_runtime_call_and_assignments(
     method_name = "run_step_async" if is_async_function else "run_step"
     call_expression = ast.Call(
         func=ast.Attribute(
-            value=ast.Name(id="__nighthawk_runner__", ctx=ast.Load()),
+            value=ast.Name(id="__nh_execution__", ctx=ast.Load()),
             attr=method_name,
             ctx=ast.Load(),
         ),
@@ -323,7 +329,16 @@ def build_runtime_call_and_assignments(
 
     # Add binding commit assignments (dynamic per output binding).
     for name in output_binding_names:
-        statements.extend(ast.parse(f'if "{name}" in __nh_bindings__:\n    {name} = __nh_bindings__["{name}"]\n').body)
+        statements.extend(
+            ast.parse(
+                f'if "{name}" in __nh_bindings__:\n    {name} = __nh_bindings__["{name}"]\n    __nh_execution__.record_assignment("{name}", {name})\n'
+            ).body
+        )
+
+    guarded = ast.parse("with __nighthawk_runner__.execution() as __nh_execution__:\n    pass\n").body[0]
+    assert isinstance(guarded, ast.With)
+    guarded.body = statements
+    statements = [guarded]
 
     # Add outcome extraction and dispatch.
     statements.extend(ast.parse('__nh_step_outcome__ = __nh_envelope__["outcome"]').body)

nighthawk/oversight.py

@@ -8,7 +8,7 @@ from opentelemetry.trace import get_current_span
 
 from .composition import UNSET, UnsetType
 from .errors import NighthawkError
-from .runtime.scoping import ExecutionRef
+from .runtime.execution_reference import ExecutionReference
 from .runtime.step_contract import StepKind
 from .runtime.step_result import Break, Continue, Pass, Raise, Return, StepResult
 
@@ -18,12 +18,17 @@ def _reference_mapping(name_to_value: Mapping[str, object]) -> Mapping[str, obje
 
 
 class OversightRejectedError(NighthawkError):
-    """Raised when oversight rejects a tool call or step commit."""
+    """Raised when oversight explicitly rejects an execution boundary."""
+
+    def __init__(self, reason: str, *, subject: str = "tool_call") -> None:
+        self.reason = reason
+        self.subject = subject
+        super().__init__(reason)
 
 
 @dataclass(frozen=True)
 class ToolCall:
-    execution_ref: ExecutionRef
+    execution_reference: ExecutionReference
     tool_name: str
     argument_name_to_value: Mapping[str, object]
     processed_natural_program: str
@@ -46,7 +51,7 @@ class StepCommit:
     Rewrite for changes and copy or serialize explicitly for durable history.
     """
 
-    execution_ref: ExecutionRef
+    execution_reference: ExecutionReference
     processed_natural_program: str
     input_binding_name_to_value: Mapping[str, object]
     outcome: StepResult
@@ -78,6 +83,25 @@ class StepCommit:
         )
 
 
+@dataclass(frozen=True)
+class ReturnExpression:
+    """Trusted expression approval before core evaluation, await, and validation.
+
+    The mapping contains writes supplied and validated for this candidate, not
+    every declared write binding. A bare name can still refer to an awaitable;
+    return validation and later rewrites can change the relationship to writes.
+    """
+
+    execution_reference: ExecutionReference
+    expression: str
+    expected_type: object
+    processed_natural_program: str
+    validated_binding_name_to_value: Mapping[str, object]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "validated_binding_name_to_value", _reference_mapping(self.validated_binding_name_to_value))
+
+
 @dataclass(frozen=True)
 class Accept:
     reason: str | None = None
@@ -121,6 +145,7 @@ type StepCommitDecision = Accept | Reject | Rewrite
 
 @dataclass(frozen=True)
 class Oversight:
+    inspect_return_expression: Callable[[ReturnExpression], Accept | Reject] | None = None
     inspect_tool_call: Callable[[ToolCall], ToolCallDecision] | None = None
     inspect_step_commit: Callable[[StepCommit], StepCommitDecision] | None = None
 
@@ -129,20 +154,21 @@ def record_oversight_decision(
     *,
     subject: str,
     verdict: str,
-    execution_ref: ExecutionRef,
+    execution_reference: ExecutionReference,
     tool_name: str | None = None,
     reason: str | None = None,
 ) -> None:
     current_span = get_current_span()
     if not current_span.is_recording():
         return
-    if execution_ref.step_id is None:
-        raise NighthawkError("Oversight decision events require ExecutionRef.step_id")
+    if execution_reference.step_execution_id is None:
+        raise NighthawkError("Oversight decision events require ExecutionReference.step_execution_id")
 
     attributes: dict[str, str] = {
-        "run.id": execution_ref.run_id,
-        "scope.id": execution_ref.scope_id,
-        "step.id": execution_ref.step_id,
+        "run.id": execution_reference.run_id,
+        "scope.id": execution_reference.scope_id,
+        "step.execution.id": execution_reference.step_execution_id,
+        "step.source_location": execution_reference.source_location or "",
         "nighthawk.oversight.subject": subject,
         "nighthawk.oversight.verdict": verdict,
     }
@@ -167,6 +193,7 @@ __all__ = [
     "Reject",
     "Rewrite",
     "StepCommit",
+    "ReturnExpression",
     "StepCommitDecision",
     "ToolCall",
     "ToolCallDecision",

nighthawk/runtime/execution_reference.py

@@ -0,0 +1,13 @@
+"""Immutable invocation identity, independent of runtime configuration."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ExecutionReference:
+    """Run and scope identity, plus invocation and source identity during a step."""
+
+    run_id: str
+    scope_id: str
+    step_execution_id: str | None = None
+    source_location: str | None = None

nighthawk/runtime/prompt.py

@@ -23,9 +23,9 @@ from ._user_content import (
 from .scoping import (
     RUN_ID,
     SCOPE_ID,
-    STEP_ID,
+    STEP_EXECUTION_ID,
     _current_user_prompt_suffix_fragments,
-    get_execution_ref,
+    get_execution_reference,
 )
 from .step_context import _MISSING, StepContext, resolve_name_in_step_context
 
@@ -538,7 +538,7 @@ def _render_reference_and_value_list_section(
         if token_limit_reached:
             dropped_multimodal = any(try_project_user_prompt_value(value) is not None for _, value in reference_and_value_list[shown_items:])
             log_attributes: dict[str, Any] = {
-                STEP_ID: step_context.step_id,
+                STEP_EXECUTION_ID: step_context.execution_reference.step_execution_id or "",
                 "nighthawk.prompt_context.section": section_name,
                 "nighthawk.prompt_context.reason": "token_limit",
                 "nighthawk.prompt_context.rendered_items": shown_items,
@@ -549,9 +549,9 @@ def _render_reference_and_value_list_section(
             # Spec §8.2.2: token truncation can drop explicit dotted multimodal
             # leaves because section ordering and budgets remain authoritative.
             try:
-                execution_ref = get_execution_ref()
-                log_attributes[RUN_ID] = execution_ref.run_id
-                log_attributes[SCOPE_ID] = execution_ref.scope_id
+                execution_reference = get_execution_reference()
+                log_attributes[RUN_ID] = execution_reference.run_id
+                log_attributes[SCOPE_ID] = execution_reference.scope_id
             except Exception:
                 pass
             logging.getLogger("nighthawk").info("prompt_context_truncated %s", log_attributes)