nighthawk-python 0.13.0__tar.gz → 0.14.0__tar.gz

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/.github/workflows/ci.yml

@@ -19,13 +19,17 @@ jobs:
     name: Lint and type check
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: "3.13"
+          # Same dependency set and cache key as "test (3.13)". Only that job
+          # saves the entry; concurrent writers race to reserve the same key.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --all-extras --all-groups
@@ -48,11 +52,12 @@ jobs:
         python-version: ["3.13", "3.14"]
     continue-on-error: ${{ matrix.python-version != '3.13' }}
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # Sole writer of the per-Python-version dependency cache.
+      - uses: astral-sh/setup-uv@v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -67,11 +72,15 @@ jobs:
     needs: [lint, test]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
 
-      - uses: astral-sh/setup-uv@v7
+      # "uv build" only resolves the build backend, so a cache entry would add
+      # no measurable benefit while colliding with the docs workflow key.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          enable-cache: false
 
       - name: Build sdist and wheel
         run: uv build

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/.github/workflows/docs.yml

@@ -24,9 +24,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no floating major tag since v8, so pin an exact release.
+      - uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.13"
+          # The docs group is a subset of the cache "test (3.13)" saves under
+          # this key, so restore it here but never overwrite it.
+          save-cache: false
 
       - name: Install dependencies
         run: uv sync --group docs

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/.github/workflows/publish.yml

@@ -24,7 +24,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifacts
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: python-package-distributions
           path: dist/

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.14.0]
+
+### Added
+
+- Scoped `nh.lifecycle.StepLifecycle` delivers typed completion, DSL raise, failure, or interruption records after generated caller assignments. Hosts can record one terminal event and translate failures with explicit exception chaining.
+- `Oversight.inspect_return_expression` approves expressions before core evaluation, await, and return validation.
+- `StepDeliveryError` supports host storage adapters without claiming persistence succeeded.
+
+### Changed
+
+- `ExecutionReference` and `get_execution_reference` replace the abbreviated identity API. `step_execution_id` identifies each invocation; `source_location` identifies its source. StepContext, inspection, testing observations, terminal records, and spans share this identity.
+- Runtime internal exceptions, including preparation and await failures, now propagate through `ExecutionError.step_failed` with the original exception as cause. Rejection is a classified failure. DSL exceptions remain distinct.
+- Completion tracing follows actual caller assignments. Cancellation retains priority if terminal delivery fails. Delivery errors never retry execution or undo effects.
+- Natural functions preserve original closure cells for nonlocal assignments and source locations for generated execution.
+
+### Fixed
+
+- Lifecycle handlers can rethrow an already-recorded host exception or interruption without replacing its original cause with a self-reference.
+- Host integration guidance distinguishes one delivery attempt from ledger deduplication and explains the validation, await, and rewrite limits of name-only return approval.
+
+### Removed
+
+- `ExecutionRef`, `get_execution_ref`, and `step_id`, without compatibility aliases. Span attributes use `step.execution.id` and `step.source_location`.
+
 ## [0.13.0]
 
 ### Added
@@ -240,7 +264,8 @@ Invalid initial results fail before oversight; use resilience retries to recover
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.10.0...v0.11.0

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nighthawk-python
-Version: 0.13.0
+Version: 0.14.0
 Summary: A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks.
 Project-URL: Repository, https://github.com/kurusugawa-computer/nighthawk-python
 Project-URL: Documentation, https://kurusugawa-computer.github.io/nighthawk-python/

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/docs/api.md

@@ -23,13 +23,14 @@
         - StepContextLimits
         - JsonableValue
         - to_jsonable_value
-        - ExecutionRef
+        - ExecutionReference
         - get_capabilities
         - get_step_context
         - get_usage_meter
-        - get_execution_ref
+        - get_execution_reference
         - get_implicit_references
         - get_oversight
+        - get_lifecycle
         - get_step_executor
         - get_system_prompt_suffix_fragments
         - get_tools
@@ -37,6 +38,7 @@
         - resilience
         - UsageMeter
         - oversight
+        - lifecycle
 
 ## Errors
 
@@ -104,15 +106,42 @@
         - get_step_context
         - step_context_scope
 
+## Step Contracts
+
+Import these types from `nighthawk.runtime.step_contract` when implementing a custom
+`StepExecutor` or constructing a `nighthawk.testing.StepResponse`.
+`StepKind` describes the allowed outcome kinds, and `StepOutcome` is the union of
+the five outcome models, discriminated by their `kind` field.
+
+These models describe executor results before the runner resolves them for
+oversight. In particular, `ReturnStepOutcome.return_expression` holds a Python
+expression that the runner evaluates, whereas `nighthawk.oversight.Return.value`
+holds the evaluated value. Oversight hooks use `nighthawk.oversight.StepResult`.
+
+::: nighthawk.runtime.step_contract
+    options:
+      members:
+        - StepKind
+        - StepOutcome
+        - PassStepOutcome
+        - ReturnStepOutcome
+        - BreakStepOutcome
+        - ContinueStepOutcome
+        - RaiseStepOutcome
+
 ## Tool Contracts
 
 ::: nighthawk.tools.contracts
     options:
       members:
-        - ToolResult
+        - ToolOutcome
         - ToolBoundaryError
-        - Error
+        - ToolError
         - ErrorKind
+
+::: nighthawk.tools.execution
+    options:
+      members:
         - ToolResultWrapperToolset
 
 ## Resilience
@@ -147,6 +176,7 @@
         - Raise
         - StepResult
         - StepCommit
+        - ReturnExpression
         - Rewrite
         - Accept
         - Reject
@@ -155,3 +185,17 @@
         - OversightRejectedError
         - StepCommitDecision
         - ToolCallDecision
+
+## Lifecycle
+
+::: nighthawk.lifecycle
+    options:
+      members:
+        - StepLifecycle
+        - StepFinished
+        - StepCompleted
+        - StepRaised
+        - StepFailed
+        - StepInterrupted
+        - FailureStage
+        - StepDeliveryError

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/docs/for-coding-agents.md

@@ -151,7 +151,7 @@ with nh.run(fast_executor):
 - `nh.scope()` must run inside `nh.run()`; it keeps `run_id` and creates a new `scope_id`.
 - Omission or `nh.UNSET` inherits; ordinary values replace and `[]`/`{}` clear collections.
 - Use `nh.Extend([...])` to append suffix fragments and `nh.Merge({...})` to merge implicit references by identity.
-- Only `oversight` accepts `None` to clear hooks; other scope fields reject it.
+- `oversight` and `lifecycle` accept `None` to clear their hooks; other scope fields reject it.
 - Executor replacement precedes full configuration replacement. Managed Model instances retain identity; external agents own their model selection.
 
 ## 4. The standard contract shape
@@ -321,9 +321,9 @@ Error-handling rule:
 
 Async rule:
 
-- Async natural functions can use async binding functions.
-- If a sync natural function triggers an async binding function and gets an awaitable, Nighthawk raises `ExecutionError`.
-- Fix that by making the natural function `async`.
+- Both sync and async Natural functions can call async binding functions through tools; tool expressions await their results.
+- Only an async Natural function may have a final return expression that produces an awaitable. A sync Natural function rejects that final result with `ExecutionError`.
+- Make the Natural function `async` when it needs an awaitable final return expression, not merely because it uses an async binding function.
 
 Resilience rule:
 

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/docs/patterns.md

@@ -224,12 +224,12 @@ Each concurrent Natural block executes independently -- there is no shared messa
 
 Async natural functions can call sync binding functions, and sync natural functions can reference async binding functions. Nighthawk detects awaitable return values and handles them automatically:
 
-- In async natural functions: awaitable results from `nh_eval` and `nh_assign` expressions are awaited before returning to the LLM.
-- In sync natural functions: if the resolved return value is awaitable, execution fails (the caller must be async to await).
+- Tool expressions await async binding function results in both sync and async Natural functions before returning them to the LLM.
+- A final return expression may produce an awaitable only in an async Natural function. A sync Natural function rejects an awaitable final return value.
 
-This means you can mix sync and async binding functions freely in async natural functions without special handling.
+You can therefore use async binding functions through tools without changing a synchronous Natural function into an async function.
 
-**Failure mode:** if a sync natural function references an async binding function and the LLM calls it, the expression produces an awaitable that cannot be awaited in a sync context. Nighthawk raises an `ExecutionError`. To fix, make the natural function `async`.
+**Failure mode:** if a sync Natural function selects a return expression such as `fetch_result()` and that expression produces an awaitable, Nighthawk raises `ExecutionError`. Make the Natural function `async` to permit an awaitable final return expression. This restriction does not apply when the model calls `fetch_result()` through a tool and writes its resolved result to a binding. See [async execution semantics](specification.md#85-async-execution-model).
 
 ## Cross-block composition
 

{nighthawk_python-0.13.0 → nighthawk_python-0.14.0}/docs/runtime-configuration.md

@@ -10,7 +10,8 @@ Use `nh.scope()` to override execution settings within an existing run. Each sco
 
 ```py
 with nh.run(step_executor):
-    # Replace the full executor configuration; omitted fields inherit scope state
+    # Replace the full executor configuration, including defaults for its omitted fields.
+    # Other omitted scope arguments inherit the parent scope values.
     with nh.scope(
         step_executor_configuration=nh.StepExecutorConfiguration(
             model="openai-responses:gpt-5.6-luna",
@@ -48,7 +49,8 @@ Parameters:
 - `step_executor_configuration`: replace the entire configuration.
 - `step_executor`: replace the step executor entirely.
 - `usage_meter`: replace the `UsageMeter` that steps in this scope record into. See [Usage metering](#usage-metering).
-- `oversight`: scope-level synchronous tool-call inspection and step-commit inspection hooks.
+- `oversight`: scope-level synchronous tool-call, return-expression, and resolved step-commit inspection hooks.
+- `lifecycle`: synchronous terminal delivery after caller assignments.
 - `system_prompt_suffix_fragments`: scope-level system suffix fragments.
 - `user_prompt_suffix_fragments`: scope-level user suffix fragments.
 - `implicit_references`: scope-level implicit global references.
@@ -62,7 +64,7 @@ Composition is selected by each supplied value:
 - `nh.Extend(sequence)` appends prompt fragments, tools, or capabilities.
 - `nh.Merge(mapping)` merges implicit references, rejecting a same-name value unless it is the identical Python object.
 
-Only `oversight` accepts `None`, which clears the hooks. Other scope fields reject it. `usage_meter` replaces the enclosing meter without forwarding totals. Resolution errors leave the parent context intact.
+`oversight` and `lifecycle` accept `None`, which clears their hooks. Other scope fields reject it. `usage_meter` replaces the enclosing meter without forwarding totals. Resolution errors leave the parent context intact.
 
 The context manager yields the resolved `StepExecutor` for the scope.
 
@@ -118,13 +120,13 @@ from pydantic_ai import RunContext
 from pydantic_ai.tools import Tool
 
 
-def read_step_id(run_context: RunContext[nh.StepContext]) -> str:
+def read_step_execution_id(run_context: RunContext[nh.StepContext]) -> str:
     """Return the current step Id."""
-    return run_context.deps.step_id
+    return run_context.deps.execution_reference.step_execution_id or ""
 
 
 with nh.run(step_executor):
-    with nh.scope(tools=[read_step_id, Tool(lookup_user, name="find_user")]):
+    with nh.scope(tools=[read_step_execution_id, Tool(lookup_user, name="find_user")]):
         triage_issue(ticket_text)
 ```
 
@@ -152,7 +154,7 @@ with nh.run(step_executor):
         triage_issue(ticket_text)
 ```
 
-Use capabilities to observe, gate, or instrument model requests with Pydantic AI's own hook vocabulary (`before_model_request`, `after_model_request`, `wrap_model_request`, and the rest of `AbstractCapability`). Nighthawk's `oversight` covers the two boundaries Nighthawk owns, tool calls and step commits; the model request boundary belongs to Pydantic AI. Use `nh.Extend([capability])` to append capabilities; a plain list replaces them. Repeated capability entries are preserved.
+Use capabilities to observe, gate, or instrument model requests with Pydantic AI's own hook vocabulary (`before_model_request`, `after_model_request`, `wrap_model_request`, and the rest of `AbstractCapability`). Nighthawk's `oversight` covers tool calls, return-expression approval, and resolved step commits; the model request boundary belongs to Pydantic AI. Use `nh.Extend([capability])` to append capabilities; a plain list replaces them. Repeated capability entries are preserved.
 
 ## Prompt suffix fragments in scopes
 
@@ -204,6 +206,7 @@ Within an active `nh.run()` context, snapshot getters expose the current scope's
 - `nh.get_user_prompt_suffix_fragments()` returns the user prompt suffix fragments as a `tuple[str, ...]`.
 - `nh.get_tools()` returns the scoped native tools as a `tuple[Tool[StepContext], ...]`, excluding built-in tools.
 - `nh.get_capabilities()` returns the scoped Pydantic AI capabilities as a tuple.
+- `nh.get_lifecycle()` returns the active `StepLifecycle`, or `None`.
 - `nh.get_oversight()` returns the active `Oversight`, or `None` when none is installed.
 
 The prompt suffix getters return only fragments accumulated via `nh.scope(...)`; configuration-level baseline fragments from `StepExecutorConfiguration` are not included.
@@ -219,7 +222,36 @@ with nh.run(step_executor):
             triage_issue(ticket_text)
 ```
 
-The getters other than `nh.get_oversight()` require an active run context. Outside `nh.run()` they raise `NighthawkError`, matching `nh.get_step_executor()` semantics. Catch `NighthawkError` if a helper needs to detect the absence of a run.
+All getters listed above, including `nh.get_oversight()`, require an active run context. Outside `nh.run()` they raise `NighthawkError`, matching `nh.get_step_executor()` semantics. Catch `NighthawkError` if a helper needs to detect the absence of a run.
+
+## Record completed executions
+
+Install `nh.lifecycle.StepLifecycle` to record actual execution endings, including preparation, validation, and return-await failures. The callback runs after generated assignments and can raise a host exception referring to its stored record. Return-expression approval is available separately through `Oversight.inspect_return_expression`; core retains evaluation and validation.
+
+```python
+import nighthawk as nh
+
+execution_id_to_event: dict[str, nh.lifecycle.StepFinished] = {}
+
+
+def record_finished(event: nh.lifecycle.StepFinished) -> None:
+    execution_id = event.execution_reference.step_execution_id
+    assert execution_id is not None
+    execution_id_to_event[execution_id] = event
+
+
+# Inside an active nh.run(executor):
+with nh.scope(lifecycle=nh.lifecycle.StepLifecycle(record_finished)):
+    result = my_natural_function()
+```
+
+This example is an in-memory history. Durable storage, serialization, and deduplication belong to the host. Callback failures do not roll back assignments or retry execution. See [terminal delivery semantics](specification.md#104-terminal-delivery-and-host-ledgers) for exception chaining, cancellation, and storage failure handling.
+
+For a host ledger, use the executor boundary for admission and execution accounting, `inspect_step_commit` for approval before assignment, and StepLifecycle for terminal recording and exception translation. Correlate them with `execution_reference.step_execution_id`, which is unique per invocation; `source_location` only groups executions of the same source block. Preparation failures may have no admission record.
+
+If an earlier host boundary already stored a failure and raised its public exception, the lifecycle handler still receives StepFailed. Skip a duplicate append only after verifying that exception refers to the stored event for this same execution, then rethrow the same exception. Core preserves its original cause. Merely returning from the handler results in an ExecutionError wrapper; suppressing all exceptions of the host type would incorrectly omit parent events for failed nested executions.
+
+At a host-controlled admission boundary, `nh.get_lifecycle() is expected_lifecycle` can verify that the required callback is configured. If it has been cleared, record the bypass through that still-active boundary: the missing lifecycle cannot record its own absence. Delivery is one in-process attempt with a configured handler, not guaranteed persistence. A callback exception after successful assignment propagates without undoing writes; host delivery-failure and anomaly records are separate from the completed core record. The full rules are in [terminal delivery semantics](specification.md#104-terminal-delivery-and-host-ledgers).
 
 ## Synchronous oversight in scopes
 
@@ -256,7 +288,9 @@ Acceptance preserves validated values without repeating validators. Replacements
 
 Inspection mappings are shallow read-only reference views: their entries retain Python types and identity. Trusted hooks must not mutate referenced objects; use `Rewrite`. Copy or serialize explicitly for durable history. Rejection cannot roll back effects of tools, validators, or return expressions. See [Specification](specification.md#102-host-commit-boundary) for the complete contract.
 
-Tool rejections are returned to the model as a recoverable observation. On preview-based paths this appears with `error.kind == "oversight"` in the projected preview; provider-backed paths that use Pydantic AI's standard retry loop may instead surface the same structured details as a retry prompt whose final line is compact JSON. Step rejections raise `nh.oversight.OversightRejectedError` to the host. For the normative boundary rule on which tool-call failures are projected back to the model versus propagated as host exceptions, see [Specification Section 8.3](specification.md#83-tools-available-to-the-llm).
+Tool rejections are returned to the model as a recoverable observation. On preview-based paths this appears with `error.kind == "oversight"` in the projected preview; provider-backed paths that use Pydantic AI's standard retry loop may instead surface the same structured details as a retry prompt whose final line is compact JSON. Step rejections produce a failed terminal record and raise `nh.ExecutionError` chained from `nh.oversight.OversightRejectedError`, unless the lifecycle callback supplies a host exception. For the normative boundary rule on which tool-call failures are projected back to the model versus propagated as host exceptions, see [Specification Section 8.3](specification.md#83-tools-available-to-the-llm).
+
+For return approval, a host may parse `ReturnExpression.expression` and permit only a bare name present in `validated_binding_name_to_value`. Declaration alone does not prove that this candidate supplied a validated value. This policy does not skip return validation, prevent awaiting an awaitable binding, or keep the return synchronized with later binding rewrites. Arbitrary constants also bypass write bindings. Keep `deny: [return]` if the host's value policy has not admitted these behaviors; see [return approval semantics](specification.md#103-return-expression-approval).
 
 ## Caller-authenticated models
 
@@ -326,13 +360,14 @@ See [Specification Section 8.2](specification.md#82-prompt-context) for the full
 
 ## Runtime execution identity
 
-Each `nh.run()` generates an `ExecutionRef` with a unique `run_id` (trace root) and `scope_id`. Nested `nh.scope()` calls generate new `scope_id` values while keeping the same `run_id`.
+Each `nh.run()` generates an `ExecutionReference` with a unique `run_id` (trace root) and `scope_id`. Nested `nh.scope()` calls generate new `scope_id` values while keeping the same `run_id`.
 
 ```py
-execution_ref = nh.get_execution_ref()
-execution_ref.run_id  # trace root -- stable across nested scopes
-execution_ref.scope_id  # current scope -- changes with each nh.scope()
-execution_ref.step_id  # None outside active step execution
+execution_reference = nh.get_execution_reference()
+execution_reference.run_id  # trace root -- stable across nested scopes
+execution_reference.scope_id  # current scope -- changes with each nh.scope()
+execution_reference.step_execution_id  # Unique per invocation; None outside a step
+execution_reference.source_location  # Source module and line; None outside a step
 ```
 
 Use `run_id` to correlate distributed agent processes in logs and traces. Use `scope_id` to identify the current logical execution context. See [Specification Section 10](specification.md#10-runtime-scoping) for the full specification and [Verification: observability](verification.md#observability) for tracing integration.