nighthawk-python 0.9.0__tar.gz → 0.10.0__tar.gz

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/CHANGELOG.md

@@ -7,7 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0]
+
+### Added
+- Scope-level oversight hooks in `nh.scope(oversight=...)` for synchronous tool-call inspection and step-commit inspection.
+- Oversight trace events and backend/wrapper coverage for accept/reject decision paths.
+- Validation for `vote(min_success=...)` bounds (`>= 1` and `<= count`) with matching tests.
+- Tool-boundary regression test ensuring recoverable `ToolBoundaryError` is wrapped into JSON payload.
+
 ### Changed
+- Finalized committed binding validation at step boundaries, added write-root dirty tracking for dotted `nh_assign`, and aligned prompt/docs with the new validation contract.
+- Introduced `ExecutionRef` (`run_id`, `scope_id`, optional `step_id`) and renamed runtime accessor to `get_execution_ref`.
+- Added top-level module access for `oversight` and `resilience`, with docs and public API tests aligned.
+- Consolidated tool-call oversight inspection to a single wrapper-side entry point and removed duplicate inspection guard state.
+- Unified tool result handling to TypedDict-based envelope types (`ToolResult`, `ToolError`) instead of Pydantic models.
+- Clarified tool-boundary policy: recoverable tool-call failures are JSON-envelope responses, host invariant violations propagate as Python exceptions.
+- Updated specification and runtime configuration docs to codify envelope-vs-raise boundary semantics for tool-call failures.
+- Updated API and patterns docs for `ExecutionRef`, `get_execution_ref`, and oversight/resilience namespace exposure.
+
+### Fixed
+- Backend handler now preserves wrapped tool error payloads (`{"value": ..., "error": ...}`) without dropping error details.
+- Tool-call context propagation now preserves step identity in execution ref during step execution.
+
+## [0.9.0]
+
+### Changed
+
 - Redesigned `nh.scope()` around `mode` semantics (`"inherit"` default, `"replace"` for explicit replacement).
 - Scope prompt suffix arguments now use list-based forms: `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments`.
 
@@ -138,7 +163,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Step executor abstraction and provider integration foundation.
 - Core documentation and project scaffolding.
 
-[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...HEAD
+[Unreleased]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/kurusugawa-computer/nighthawk-python/compare/v0.6.0...v0.6.1

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nighthawk-python
-Version: 0.9.0
+Version: 0.10.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.9.0 → nighthawk_python-0.10.0}/docs/api.md

@@ -18,12 +18,14 @@
         - StepContextLimits
         - JsonableValue
         - to_jsonable_value
-        - ExecutionContext
+        - ExecutionRef
         - get_current_step_context
         - get_current_usage_meter
-        - get_execution_context
+        - get_execution_ref
         - get_step_executor
+        - resilience
         - UsageMeter
+        - oversight
 
 ## Errors
 
@@ -123,4 +125,3 @@
 ## Testing
 
 ::: nighthawk.testing
-

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/for-coding-agents.md

@@ -327,7 +327,7 @@ Async rule:
 Resilience rule:
 
 - Keep retry, fallback, timeout, budget, and circuit-breaker policy in Python, not inside Natural text.
-- Import from `nighthawk.resilience` (not re-exported from `nighthawk`):
+- Import primitives from `nighthawk.resilience`. After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`:
 
 ```py
 from nighthawk.resilience import retrying

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/natural-blocks.md

@@ -129,7 +129,7 @@ def detect_language(text: str):
     return language
 ```
 
-Type annotations on write bindings enable validation and coercion at commit time.
+Type annotations on write bindings enable validation and coercion at step finalization for values that are actually committed.
 
 ### Pydantic model write bindings
 

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/patterns.md

@@ -326,7 +326,8 @@ Natural blocks are non-deterministic by nature. Production deployments need stra
 from nighthawk.resilience import retrying, fallback, vote, timeout, budget, circuit_breaker
 ```
 
-Import directly from `nighthawk.resilience`. Resilience primitives are not re-exported from the top-level `nighthawk` namespace.
+Import directly from `nighthawk.resilience`.
+After `import nighthawk as nh`, the module namespace is also available as `nh.resilience`.
 
 ### Retrying
 

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/philosophy.md

@@ -23,7 +23,7 @@ calculate_average([1, "2", "three", "cuatro", "五"])  # 3.0
 
 Binding functions like `<python_average>` appear in the prompt as a compact signature line. The LLM's pre-trained Python knowledge lets it reason about types, return values, and composition from the signature alone, without JSON Schema or protocol overhead. See [Tool exposure efficiency](#tool-exposure-efficiency) for the quantitative comparison with MCP and CLI tool exposure.
 
-With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates the type annotation at runtime, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
+With provider-backed executors, each Natural block is a single LLM call. A sentiment classifier whose write binding is typed as `Literal["positive", "negative", "neutral"]` rejects any output outside the declared set -- Pydantic validates committed write bindings at step finalization, not as a hint. The same mechanism applies to numeric extraction (`int`, `float`), structured parsing (Pydantic models), and any task where the judgment space is bounded. Because the host program owns the loop, a misclassified result can be retried, logged, or routed to a fallback -- all in ordinary Python.
 
 With [coding agent backends](coding-agent-backends.md), the same boundary contract applies, but each Natural block becomes an autonomous agent execution. The agent can read files, run commands, and invoke skills -- while typed bindings enforce what crosses the boundary back to Python. The same `scope()` and `run()` context managers that structure human-written workflows are equally legible to a coding agent constructing workflows programmatically. When a coding agent operates inside a Natural block, binding functions appear as Python signatures in the prompt:
 

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/runtime-configuration.md

@@ -35,6 +35,15 @@ with nh.run(step_executor):
     # Add implicit global references for this scope
     with nh.scope(implicit_references={"search_repository": search_repository}):
         typed_labeling_step(ticket_text)
+
+    # Add synchronous oversight for this scope
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
 ```
 
 Parameters:
@@ -42,6 +51,7 @@ Parameters:
 - `mode`: scope composition mode. Default: `"inherit"`.
 - `step_executor_configuration`: replace the entire configuration.
 - `step_executor`: replace the step executor entirely.
+- `oversight`: scope-level synchronous tool-call inspection and step-commit inspection hooks.
 - `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.
@@ -56,6 +66,8 @@ Mode semantics:
   - Explicit `[]` or `{}` clears inherited list/dict values.
   - Explicit list/dict values (for example `[e1, e2]` or `{k1: v1, k2: v2}`) fully replace inherited values.
 
+For `oversight`, omitted means inherit the current hooks, while explicit `None` clears them for the nested scope.
+
 The context manager yields the resolved `StepExecutor` for the scope.
 
 `StepExecutorConfiguration` also accepts `system_prompt_suffix_fragments` and `user_prompt_suffix_fragments` (tuples of strings) as baseline suffix fragments for the whole run. In `mode="inherit"`, scope-level fragments are appended after configuration-level fragments.
@@ -138,6 +150,36 @@ with nh.scope(mode="replace", system_prompt_suffix_fragments=None):
 ```
 
 The same `replace` semantics apply to `user_prompt_suffix_fragments`.
+
+## Synchronous oversight in scopes
+
+Use `nh.scope(oversight=...)` when the host needs synchronous inspection around tool calls or a final rewrite/reject checkpoint before Nighthawk commits a step result.
+
+```py
+def inspect_tool_call(tool_call: nh.oversight.ToolCall) -> nh.oversight.ToolCallDecision:
+    if tool_call.tool_name == "delete_file":
+        return nh.oversight.Reject("Deletion must be approved by a human.")
+    return nh.oversight.Accept()
+
+
+def inspect_step_commit(proposal: nh.oversight.StepCommitProposal) -> nh.oversight.StepCommitDecision:
+    if "result" in proposal.proposed_binding_name_to_value:
+        return nh.oversight.Rewrite(rewritten_binding_name_to_value={"result": "reviewed"})
+    return nh.oversight.Accept()
+
+
+with nh.run(step_executor):
+    with nh.scope(
+        oversight=nh.oversight.Oversight(
+            inspect_tool_call=inspect_tool_call,
+            inspect_step_commit=inspect_step_commit,
+        )
+    ):
+        inspected_step(ticket_text)
+```
+
+Tool rejections are returned to the model as a normal tool result envelope with `error.kind == "oversight"`. Step rejections raise `nh.oversight.OversightRejectedError` to the host. Rewrite values still flow through the normal step finalization path. For the normative boundary rule on which tool-call failures are envelope-wrapped versus propagated as host exceptions, see [Specification Section 8.3](specification.md#83-tool-boundary-contract-built-in-tooling).
+
 ## Mixing executors
 
 Use `nh.scope(step_executor=...)` to switch executors within a single run. This is the standard pattern for mixing a cheap classifier with a deep autonomous step:
@@ -181,12 +223,13 @@ See [Specification Section 8.2](specification.md#82-prompt-context) for the full
 
 ## Runtime execution identity
 
-Each `nh.run()` generates an `ExecutionContext` 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 `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`.
 
 ```py
-context = nh.get_execution_context()
-context.run_id    # trace root -- stable across nested scopes
-context.scope_id  # current scope -- changes with each nh.scope()
+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
 ```
 
 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.

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/docs/specification.md

@@ -103,17 +103,18 @@ The condensed coding agent guide (`for-coding-agents.md`) is a derivative docume
     - Fields: `locals_max_tokens`, `locals_max_items`, `globals_max_tokens`, `globals_max_items`, `value_max_tokens`, `object_max_methods`, `object_max_fields`, `object_field_value_max_tokens`, `tool_result_max_tokens`.
 - `JsonableValue`
     - Type alias for JSON-serializable Python values (`dict | list | str | int | float | bool | None`).
-- `ExecutionContext`
+- `ExecutionRef`
     - Frozen dataclass representing runtime execution identity.
     - `run_id`: the Id of the outermost run (trace root).
     - `scope_id`: the Id of the current scope.
+    - `step_id`: the Id of the current step when available, otherwise `None`.
 
 ### 5.4. Runtime accessors
 
 - `nighthawk.get_current_step_context() -> StepContext`
     - Get the `StepContext` for the currently executing Natural block. Raises if no step is active.
 
-See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_context`).
+See [Section 10](#10-runtime-scoping) for additional runtime accessors (`get_step_executor`, `get_execution_ref`).
 
 ## 6. Natural block detection
 
@@ -392,6 +393,7 @@ Eval tool:
 
 - `nh_eval(expression: str) -> object`
     - Evaluate a Python expression and return the result. Use to inspect values, call functions, and mutate objects in-place.
+    - In-place mutations performed via `nh_eval` are not runtime-validated.
     - If the evaluated expression is awaitable, it is awaited before returning.
 
 Binding tool:
@@ -421,13 +423,16 @@ Semantics of `nh_assign`:
     - Traverse attributes for each intermediate segment.
     - Assign using attribute assignment on the final segment.
     - Validation:
-        - Validate only when runtime type metadata is available; otherwise assign without validation.
+        - Validate only the final assigned field when runtime type metadata is available; otherwise assign without validation.
 
 Commit and mutation notes:
 
 - Commit selection is controlled only by `<:name>` bindings.
 - `<:name>` selects which top-level names are committed from `step_locals` into Python locals at Natural block boundaries.
-- Dotted mutation is independent of `<:name>`.
+- Dotted `nh_assign` on a write binding root marks that root as dirty for commit selection.
+- Dotted `nh_assign` on a read binding root does not participate in commit selection.
+- Final validation is applied only to committed write bindings at step finalization.
+- Dotted mutation on read bindings and in-place mutation via `nh_eval` are outside the final validation guarantee.
 
 Write tool return value:
 
@@ -446,6 +451,11 @@ All tool results are wrapped in a JSON envelope with the following structure:
 
 Error kind categories: `invalid_input`, `resolution`, `execution`, `transient`, `internal`.
 
+Boundary rule for tool-call failures:
+
+- If the model can recover by changing tool arguments, choosing another tool, or continuing without the tool, the failure MUST be returned in the JSON envelope (`{"value": null, "error": ...}`).
+- Host invariant violations (for example, broken runtime contract or invalid host-side oversight hook contract) MAY propagate as Python exceptions to the host instead of being envelope-wrapped.
+
 The `value` field is bounded by `context_limits.tool_result_max_tokens` and may be summarized using [headson](https://github.com/kantord/headson) truncation when the full rendering exceeds the token budget. Headson is a structure-aware JSON summarizer: it parses the full JSON tree, then selects representative nodes to produce a compact preview that preserves the shape and key values of the data within a strict byte budget (analogous to `head`/`tail` but for structured data).
 
 Atomicity requirement:
@@ -570,10 +580,11 @@ The required runtime object for step execution is:
 
 - `step_executor` (required): a strategy object responsible for executing steps (Natural blocks).
 
-Runtime execution identity is modeled separately in `ExecutionContext`:
+Runtime execution identity is modeled separately in `ExecutionRef`:
 
 - `run_id`: the Id of the outermost run (trace root). This serves as the golden thread that connects distributed agent processes (e.g. parent, child, grandchild) across process boundaries in observability tools.
 - `scope_id`: the Id of the current (possibly nested) run scope. This serves as the identity of the current logical execution context.
+- `step_id`: the Id of the current step when available. Outside active step execution it is `None`.
 
 Nighthawk does not own workspace filesystem concerns (such as include resolution or host file operations). Those concerns belong to the host application layer that embeds Nighthawk.
 
@@ -582,14 +593,15 @@ API:
 
 - `nighthawk.run(step_executor: StepExecutor, *, run_id: str | None = None)`
     - Replaces the current context step executor with the provided step executor.
-    - Generates a new `ExecutionContext` for the duration of the `with`.
+    - Generates a new `ExecutionRef` for the duration of the `with`.
     - Uses provided `run_id` when given; otherwise generates a new `run_id` (trace root).
     - Always generates a fresh `scope_id`.
     - Can be used even when no step executor is currently set.
-- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
+- `nighthawk.scope(*, mode: Literal["inherit", "replace"] = "inherit", step_executor_configuration: StepExecutorConfiguration | None = None, step_executor: StepExecutor | None = None, oversight: Oversight | None = None, system_prompt_suffix_fragments: Sequence[str] | None = None, user_prompt_suffix_fragments: Sequence[str] | None = None, implicit_references: Mapping[str, object] | None = None) -> Iterator[StepExecutor]`
     - Enter a nested scope within the current run.
     - Requires an existing step executor.
     - Generates a new `scope_id` (keeps the current `run_id`).
+    - `oversight` omitted means inherit the current hooks; explicit `None` clears them for the nested scope.
     - `mode="inherit"` (default):
         - Appends prompt suffix fragment lists.
         - Merges `implicit_references` additively with conflict checks.
@@ -601,7 +613,7 @@ API:
     - Yields the resolved `StepExecutor` for the scope.
 - `nighthawk.get_step_executor() -> StepExecutor`
     - Get the current step executor. Raises if unset.
-- `nighthawk.get_execution_context() -> ExecutionContext`
+- `nighthawk.get_execution_ref() -> ExecutionRef`
     - Get the current runtime execution identity. Raises if unset.
 
 ### 10.1. Observability contract (OpenTelemetry span/event)

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nighthawk-python"
-version = "0.9.0"
+version = "0.10.0"
 description = "A Python library where Python controls flow and LLMs or coding agents reason within constrained Natural blocks."
 readme = "README.md"
 requires-python = ">=3.13"

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/src/nighthawk/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from . import oversight, resilience
 from .configuration import (
     StepContextLimits,
     StepExecutorConfiguration,
@@ -15,15 +16,15 @@ from .errors import (
 )
 from .json_renderer import JsonableValue, to_jsonable_value
 from .natural.decorator import natural_function
-from .runtime.scoping import ExecutionContext, UsageMeter, get_current_usage_meter, get_execution_context, get_step_executor, run, scope
+from .runtime.scoping import ExecutionRef, UsageMeter, get_current_usage_meter, get_execution_ref, get_step_executor, run, scope
 from .runtime.step_context import StepContext, get_current_step_context
 from .runtime.step_executor import AgentStepExecutor, StepExecutor
 from .tools.registry import tool
 
 __all__ = [
     "AgentStepExecutor",
-    "ExecutionContext",
     "ExecutionError",
+    "ExecutionRef",
     "JsonableValue",
     "NaturalParseError",
     "NighthawkError",
@@ -38,9 +39,11 @@ __all__ = [
     "UsageMeter",
     "get_current_step_context",
     "get_current_usage_meter",
-    "get_execution_context",
+    "get_execution_ref",
     "get_step_executor",
+    "oversight",
     "natural_function",
+    "resilience",
     "run",
     "scope",
     "to_jsonable_value",

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/src/nighthawk/backends/mcp_server.py

@@ -23,6 +23,7 @@ from pydantic_ai import RunContext
 from pydantic_ai.exceptions import UnexpectedModelBehavior
 from pydantic_ai.tools import ToolDefinition
 
+from ..errors import NighthawkError
 from ..runtime.step_context import (
     DEFAULT_TOOL_RESULT_RENDERING_POLICY,
     StepContext,
@@ -203,7 +204,7 @@ async def mcp_server_if_needed(
     parent_otel_context = otel_context.get_current()
     parent_run_context = get_current_run_context()
     if parent_run_context is None:
-        raise RuntimeError("Codex MCP tool server requires an active RunContext")
+        raise NighthawkError("Codex MCP tool server requires an active RunContext")
     typed_parent_run_context = cast(RunContext[StepContext], parent_run_context)
     tool_result_rendering_policy = typed_parent_run_context.deps.tool_result_rendering_policy
     if tool_result_rendering_policy is None:

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/src/nighthawk/backends/tool_bridge.py

@@ -20,13 +20,10 @@ from pydantic_ai.messages import RetryPromptPart
 from pydantic_ai.models import ModelRequestParameters
 from pydantic_ai.toolsets.function import FunctionToolset
 
+from ..errors import NighthawkError
 from ..runtime.step_context import DEFAULT_TOOL_RESULT_RENDERING_POLICY, StepContext, ToolResultRenderingPolicy
 from ..runtime.tool_calls import generate_tool_call_id, run_tool_instrumented
-from ..tools.contracts import (
-    ToolBoundaryError,
-    ToolResult,
-    render_tool_result_json_text,
-)
+from ..tools.contracts import ToolBoundaryError, render_tool_result_json_text
 from ..tools.execution import ToolResultWrapperToolset
 
 type ToolHandler = Callable[[dict[str, Any]], Awaitable[str]]
@@ -44,7 +41,7 @@ def get_current_run_context_required() -> RunContext[StepContext]:
 
     run_context = get_current_run_context()
     if run_context is None:
-        raise RuntimeError("Nighthawk tool boundaries require an active RunContext")
+        raise NighthawkError("Nighthawk tool boundaries require an active RunContext")
     return cast(RunContext[StepContext], run_context)
 
 
@@ -71,6 +68,7 @@ async def execute_tool_call(
     *,
     tool_name: str,
     tool: Any,
+    toolset: ToolResultWrapperToolset,
     arguments: dict[str, Any],
     run_context: RunContext[StepContext],
     tool_call_id: str,
@@ -102,7 +100,7 @@ async def execute_tool_call(
             ).model_response()
 
         try:
-            tool_result = await tool.toolset.call_tool(tool_name, validated_arguments, run_context, tool)
+            tool_result = await toolset.call_tool(tool_name, validated_arguments, run_context, tool)
         except (ModelRetry, CallDeferred, ApprovalRequired):
             raise
         except ToolBoundaryError as exception:
@@ -121,6 +119,9 @@ async def execute_tool_call(
                 encoding=encoding,
                 style=rendering_policy.json_renderer_style,
             )
+        except NighthawkError:
+            # Preserve host-invariant failures as Python exceptions; these are not LLM-recoverable tool-call errors and must propagate to the host.
+            raise
         except Exception as exception:
             return render_tool_result_json_text(
                 value=None,
@@ -134,10 +135,10 @@ async def execute_tool_call(
                 style=rendering_policy.json_renderer_style,
             )
 
-    if isinstance(tool_result, ToolResult):
+    if isinstance(tool_result, dict) and set(tool_result.keys()) == {"value", "error"}:
         return render_tool_result_json_text(
-            value=tool_result.value,
-            error=None,
+            value=tool_result["value"],
+            error=tool_result["error"],
             max_tokens=rendering_policy.tool_result_max_tokens,
             encoding=encoding,
             style=rendering_policy.json_renderer_style,
@@ -193,6 +194,7 @@ async def build_tool_name_to_handler(
                 return await execute_tool_call(
                     tool_name=tool_name,
                     tool=tool,
+                    toolset=toolset,
                     arguments=arguments,
                     run_context=tool_run_context,
                     tool_call_id=tool_call_id,

nighthawk_python-0.10.0/src/nighthawk/oversight.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from opentelemetry.trace import get_current_span
+from pydantic import BaseModel
+
+from .errors import NighthawkError
+from .runtime.scoping import ExecutionRef
+from .runtime.step_contract import StepKind, StepOutcome
+
+
+def _snapshot_value(value: object) -> object:
+    if isinstance(value, BaseModel):
+        return value.model_copy(deep=True)
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _snapshot_value(item) for key, item in value.items()})
+    if isinstance(value, tuple):
+        return tuple(_snapshot_value(item) for item in value)
+    if isinstance(value, list):
+        return tuple(_snapshot_value(item) for item in value)
+    if isinstance(value, set):
+        return frozenset(_snapshot_value(item) for item in value)
+    if isinstance(value, frozenset):
+        return frozenset(_snapshot_value(item) for item in value)
+    return value
+
+
+def _snapshot_mapping(name_to_value: Mapping[str, object]) -> Mapping[str, object]:
+    return MappingProxyType({name: _snapshot_value(value) for name, value in name_to_value.items()})
+
+
+def _snapshot_optional_step_outcome(step_outcome: StepOutcome | None) -> StepOutcome | None:
+    if step_outcome is None:
+        return None
+    return _snapshot_value(step_outcome)  # type: ignore[return-value]
+
+
+class OversightRejectedError(NighthawkError):
+    """Raised when oversight rejects a tool call or step commit."""
+
+
+@dataclass(frozen=True)
+class ToolCall:
+    execution_ref: ExecutionRef
+    tool_name: str
+    argument_name_to_value: Mapping[str, object]
+    processed_natural_program: str
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "argument_name_to_value",
+            _snapshot_mapping(self.argument_name_to_value),
+        )
+
+
+@dataclass(frozen=True)
+class StepCommitProposal:
+    execution_ref: ExecutionRef
+    processed_natural_program: str
+    input_binding_name_to_value: Mapping[str, object]
+    proposed_step_outcome: StepOutcome
+    proposed_binding_name_to_value: Mapping[str, object]
+    allowed_step_kinds: tuple[StepKind, ...]
+    output_binding_name_set: frozenset[str]
+    binding_name_to_type: Mapping[str, object]
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "input_binding_name_to_value",
+            _snapshot_mapping(self.input_binding_name_to_value),
+        )
+        object.__setattr__(
+            self,
+            "proposed_step_outcome",
+            _snapshot_value(self.proposed_step_outcome),
+        )
+        object.__setattr__(
+            self,
+            "proposed_binding_name_to_value",
+            _snapshot_mapping(self.proposed_binding_name_to_value),
+        )
+        object.__setattr__(
+            self,
+            "output_binding_name_set",
+            frozenset(self.output_binding_name_set),
+        )
+        object.__setattr__(
+            self,
+            "binding_name_to_type",
+            _snapshot_mapping(self.binding_name_to_type),
+        )
+
+
+@dataclass(frozen=True)
+class Accept:
+    reason: str | None = None
+
+
+@dataclass(frozen=True)
+class Reject:
+    reason: str
+
+
+@dataclass(frozen=True)
+class Rewrite:
+    rewritten_step_outcome: StepOutcome | None = None
+    rewritten_binding_name_to_value: Mapping[str, object] | None = None
+    reason: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(
+            self,
+            "rewritten_step_outcome",
+            _snapshot_optional_step_outcome(self.rewritten_step_outcome),
+        )
+        if self.rewritten_binding_name_to_value is not None:
+            object.__setattr__(
+                self,
+                "rewritten_binding_name_to_value",
+                _snapshot_mapping(self.rewritten_binding_name_to_value),
+            )
+        if self.rewritten_step_outcome is None and self.rewritten_binding_name_to_value is None:
+            raise ValueError("Rewrite must change rewritten_step_outcome or rewritten_binding_name_to_value")
+
+
+type ToolCallDecision = Accept | Reject
+type StepCommitDecision = Accept | Reject | Rewrite
+
+
+@dataclass(frozen=True)
+class Oversight:
+    inspect_tool_call: Callable[[ToolCall], ToolCallDecision] | None = None
+    inspect_step_commit: Callable[[StepCommitProposal], StepCommitDecision] | None = None
+
+
+def record_oversight_decision(
+    *,
+    subject: str,
+    verdict: str,
+    execution_ref: ExecutionRef,
+    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")
+
+    attributes: dict[str, str] = {
+        "run.id": execution_ref.run_id,
+        "scope.id": execution_ref.scope_id,
+        "step.id": execution_ref.step_id,
+        "nighthawk.oversight.subject": subject,
+        "nighthawk.oversight.verdict": verdict,
+    }
+    if tool_name:
+        attributes["tool.name"] = tool_name
+    if reason:
+        attributes["nighthawk.oversight.reason"] = reason
+
+    current_span.add_event("nighthawk.oversight.decision", attributes)
+
+
+__all__ = [
+    "Accept",
+    "Oversight",
+    "OversightRejectedError",
+    "Reject",
+    "Rewrite",
+    "StepCommitDecision",
+    "StepCommitProposal",
+    "ToolCall",
+    "ToolCallDecision",
+]

{nighthawk_python-0.9.0 → nighthawk_python-0.10.0}/src/nighthawk/resilience/__init__.py

@@ -8,9 +8,8 @@ Import directly from this module::
 
     from nighthawk.resilience import retrying, fallback, vote, timeout, budget, circuit_breaker
 
-These primitives are **not** re-exported from the top-level ``nighthawk``
-namespace.  See [Patterns: Resilience patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/#resilience-patterns)
-for usage patterns and composition examples.
+The ``nighthawk.resilience`` module is available as ``nh.resilience`` after ``import nighthawk as nh``. Individual resilience primitives are **not** re-exported from the top-level ``nighthawk`` namespace.
+See [Patterns: Resilience patterns](https://kurusugawa-computer.github.io/nighthawk-python/patterns/#resilience-patterns) for usage patterns and composition examples.
 """
 
 from __future__ import annotations