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

nighthawk/__init__.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from . import lifecycle, oversight, resilience
+from . import lifecycle, oversight, resilience, runtime
 from .composition import UNSET, Extend, Merge, UnsetType
 from .configuration import (
+    ModelSelection,
     StepContextLimits,
     StepExecutorConfiguration,
     StepPromptTemplates,
@@ -13,18 +14,17 @@ from .errors import (
     NaturalParseError,
     NighthawkError,
     ToolDeclarationError,
-    ToolEvaluationError,
     ToolNameConflictError,
-    ToolValidationError,
 )
+from .function_call import FunctionCall, FunctionCallError, FunctionCallHandler, function_call_scope, get_function_call
 from .json_renderer import JsonableValue, to_jsonable_value
 from .natural.decorator import get_transformed_function, natural_function
+from .natural.definition import NaturalFunctionDefinition, get_natural_function_definition
 from .runtime.scoping import (
     ExecutionReference,
     UsageMeter,
     get_capabilities,
     get_execution_reference,
-    get_implicit_references,
     get_lifecycle,
     get_oversight,
     get_step_executor,
@@ -36,9 +36,19 @@ from .runtime.scoping import (
     scope,
 )
 from .runtime.step_context import StepContext, get_step_context
-from .runtime.step_executor import AgentStepExecutor, StepExecutor
+from .runtime.step_executor import AgentStepExecutor, ConfigurableStepExecutor, StepExecutor
 
 __all__ = [
+    "FunctionCall",
+    "FunctionCallError",
+    "FunctionCallHandler",
+    "function_call_scope",
+    "get_function_call",
+    "NaturalFunctionDefinition",
+    "get_natural_function_definition",
+    "ModelSelection",
+    "ConfigurableStepExecutor",
+    "runtime",
     "UNSET",
     "Extend",
     "Merge",
@@ -56,15 +66,12 @@ __all__ = [
     "StepExecutor",
     "StepExecutorConfiguration",
     "StepPromptTemplates",
-    "ToolEvaluationError",
     "ToolDeclarationError",
-    "ToolValidationError",
     "UsageMeter",
     "get_capabilities",
     "get_step_context",
     "get_usage_meter",
     "get_execution_reference",
-    "get_implicit_references",
     "get_oversight",
     "get_step_executor",
     "get_tools",

nighthawk/backends/_text_fallback.py

@@ -1,10 +1,4 @@
-"""Backend-private text-fallback formatting for multimodal content.
-
-Used by both the text-projected coding-agent backends (``text_projection``)
-and the MCP tool-return transport (``mcp_boundary``) to emit a consistent
-``<image>``/``<file>`` placeholder line followed by descriptive metadata when
-multimodal content cannot be carried natively by the transport.
-"""
+"""Text fallback lines shared by text-projected backends and the MCP tool-return transport."""
 
 from __future__ import annotations
 
@@ -20,7 +14,6 @@ from pydantic_ai.messages import (
 
 
 def is_image_content(*, content: object) -> bool:
-    """Return True when *content* represents image media."""
     if isinstance(content, ImageUrl):
         return True
     if isinstance(content, BinaryContent):
@@ -32,13 +25,7 @@ def is_image_content(*, content: object) -> bool:
 
 
 def _safe_file_url_media_type(*, content: FileUrl) -> str | None:
-    """Return ``content.media_type`` for a FileUrl, or ``None`` when unresolvable.
-
-    ``FileUrl.media_type`` is a pydantic-ai property that may raise
-    ``ValueError`` when the MIME type cannot be inferred from the URL and no
-    explicit ``media_type`` was supplied (for example ``VideoUrl`` pointing at
-    a YouTube-like URL with no extension).
-    """
+    """``FileUrl.media_type`` raises ``ValueError`` when neither the URL nor the caller supplies a media type."""
     try:
         return content.media_type
     except ValueError:
@@ -46,14 +33,6 @@ def _safe_file_url_media_type(*, content: FileUrl) -> str | None:
 
 
 def format_file_url_as_text_lines(*, content: FileUrl) -> list[str]:
-    """Format ``FileUrl`` metadata lines for transports that need a text fallback.
-
-    Returns only the descriptive metadata lines (the ``"... URL: <url>"`` line
-    plus an optional ``"Media type: ..."`` line). The ``<image>`` / ``<file>``
-    placeholder is emitted by :func:`format_file_url_with_placeholder`; this
-    helper is exported separately for tests and for callers that already know
-    which placeholder to use.
-    """
     if isinstance(content, ImageUrl):
         label = "Image"
         include_media_type = False
@@ -83,18 +62,9 @@ def format_unresolvable_content_text(
     content: UploadedFile | BinaryContent,
     transport_label: str,
 ) -> str:
-    """Build the fallback metadata text for content the transport cannot resolve.
-
-    Used only on the tool-return path. Spec §8.3 requires the rest of a
-    successful tool-return payload to be preserved and only the unresolvable
-    item replaced with explanatory text. Coding-agent user-prompt admission
-    rejects ``UploadedFile`` outright at the backend boundary instead (see
-    ``backends/base.py``), so this helper is not reused there.
-
-    ``BinaryContent`` reaches this helper only on transports that cannot carry
-    embedded bytes natively (today: MCP, for non-image/non-audio blobs).
-    Text-projected backends stage the bytes to a local file rather than fall
-    back to this metadata text.
+    """Tool-return path only.
+
+    Coding-agent user-prompt admission rejects ``UploadedFile`` earlier, and text-projected backends stage ``BinaryContent`` as files.
     """
     if isinstance(content, UploadedFile):
         return f"UploadedFile: provider={content.provider_name}, file_id={content.file_id} (not resolvable by {transport_label})"
@@ -102,7 +72,6 @@ def format_unresolvable_content_text(
 
 
 def format_file_url_with_placeholder(*, content: FileUrl) -> list[str]:
-    """Format ``FileUrl`` text-fallback lines including the ``<image>``/``<file>`` placeholder."""
     placeholder = "<image>" if isinstance(content, ImageUrl) else "<file>"
     return [placeholder, *format_file_url_as_text_lines(content=content)]
 
@@ -112,13 +81,7 @@ def format_uploaded_file_with_placeholder(
     content: UploadedFile,
     transport_label: str,
 ) -> list[str]:
-    """Format ``UploadedFile`` fallback lines including placeholder.
-
-    Used by text-projected backends (coding-agent backends) that cannot resolve
-    provider-owned file references but still want to surface the failure as
-    inline content. The MCP transport intentionally bypasses this helper and
-    emits only the bare fallback text without a placeholder.
-    """
+    """For text-projected backends; the MCP transport intentionally emits the fallback text without a placeholder."""
     placeholder = "<image>" if is_image_content(content=content) else "<file>"
     metadata_line_list = [format_unresolvable_content_text(content=content, transport_label=transport_label)]
     if content.media_type is not None:
@@ -131,11 +94,6 @@ def format_unresolvable_binary_content_with_placeholder(
     content: BinaryContent,
     transport_label: str,
 ) -> list[str]:
-    """Format unresolvable ``BinaryContent`` fallback lines including placeholder.
-
-    Used on transports that cannot carry embedded bytes natively (today: MCP,
-    for non-image/non-audio blobs). Text-projected backends stage the bytes to
-    a local file instead and do not use this helper.
-    """
+    """For transports that cannot carry embedded bytes; text-projected backends stage them as files instead."""
     placeholder = "<image>" if is_image_content(content=content) else "<file>"
     return [placeholder, format_unresolvable_content_text(content=content, transport_label=transport_label)]

nighthawk/backends/base.py

@@ -12,6 +12,7 @@ from pydantic_ai.messages import (
     InstructionPart,
     ModelMessage,
     ModelRequest,
+    ModelResponse,
     RetryPromptPart,
     SystemPromptPart,
     TextContent,
@@ -27,6 +28,7 @@ from pydantic_ai.settings import ModelSettings
 from ..configuration import TEXT_PROJECTED_TOOL_RESULT_PREVIEW_SYSTEM_PROMPT_FRAGMENT
 from ..runtime.prompt import resolve_step_system_prompt_template_text
 from .tool_bridge import ToolHandler, prepare_allowed_tools, resolve_current_tool_result_rendering_policy
+from .tool_transport import ToolTransport
 
 if TYPE_CHECKING:
     from .text_projection import TextProjectedRequest
@@ -36,20 +38,7 @@ type RequestPromptPartList = list[RequestPromptPart]
 
 
 def _validate_coding_agent_user_prompt_content_item(*, item: UserContent, backend_label: str) -> None:
-    """Enforce the coding-agent-backend user-prompt admission policy.
-
-    This layers two checks:
-
-    1. Structural check (policy-free): reject anything outside the Pydantic AI
-       ``UserContent`` union (``str | TextContent | CachePoint | <multimodal>``).
-    2. Admission policy (coding-agent-specific): reject ``UploadedFile`` even
-       though it is a legal ``UserContent`` member, because coding-agent
-       backends cannot resolve provider-owned file references.
-
-    Only backends subclassing :class:`BackendModelBase` (the coding-agent
-    backends) route through this helper; provider-backed executors send
-    ``UserContent`` natively and bypass this path.
-    """
+    """Reject non-``UserContent`` items and ``UploadedFile``, whose provider-owned references coding-agent backends cannot resolve."""
     if isinstance(item, UploadedFile):
         raise UserError(
             f"{backend_label} does not support UploadedFile user prompt content; provider-owned uploaded files cannot be resolved by this backend"
@@ -172,6 +161,22 @@ class BackendModelBase(Model):
         super().__init__(profile=profile)
         self.backend_label = backend_label
 
+    async def request(
+        self,
+        messages: list[ModelMessage],
+        model_settings: ModelSettings | None,
+        model_request_parameters: ModelRequestParameters,
+    ) -> ModelResponse:
+        return await ToolTransport().run(lambda: self._request(messages, model_settings, model_request_parameters))
+
+    async def _request(
+        self,
+        messages: list[ModelMessage],
+        model_settings: ModelSettings | None,
+        model_request_parameters: ModelRequestParameters,
+    ) -> ModelResponse:
+        raise NotImplementedError
+
     def _prepare_common_request_parts(
         self,
         *,

nighthawk/backends/claude_code_cli.py

@@ -19,6 +19,7 @@ from ..tools.declarations import get_visible_tools
 from .base import BackendModelBase, append_text_projected_tool_result_preview_prompt
 from .claude_code_settings import ClaudeCodeModelSettings
 from .mcp_server import mcp_server_if_needed
+from .process_management import stop_process
 from .text_projection import TextProjectedRequest, resolve_text_projection_staging_root_directory
 
 
@@ -149,7 +150,7 @@ class ClaudeCodeCliModel(BackendModelBase):
     def system(self) -> str:
         return "anthropic"
 
-    async def request(
+    async def _request(
         self,
         messages: list[ModelMessage],
         model_settings: ModelSettings | None,
@@ -159,6 +160,7 @@ class ClaudeCodeCliModel(BackendModelBase):
         mcp_configuration_file: IO[str] | None = None
         projected_request: TextProjectedRequest | None = None
 
+        process: asyncio.subprocess.Process | None = None
         try:
             model_settings, model_request_parameters = self.prepare_request(model_settings, model_request_parameters)
             claude_code_cli_model_settings = ClaudeCodeCliModelSettings.from_model_settings(model_settings)
@@ -304,6 +306,7 @@ class ClaudeCodeCliModel(BackendModelBase):
         except Exception as exception:
             raise UnexpectedModelBehavior("Claude Code CLI backend failed") from exception
         finally:
+            await stop_process(process)
             if system_prompt_file is not None:
                 with contextlib.suppress(Exception):
                     system_prompt_file.close()

nighthawk/backends/claude_code_sdk.py

@@ -123,7 +123,7 @@ class ClaudeCodeSdkModel(BackendModelBase):
     def system(self) -> str:
         return "anthropic"
 
-    async def request(
+    async def _request(
         self,
         messages: list[ModelMessage],
         model_settings: ModelSettings | None,

nighthawk/backends/codex.py

@@ -19,6 +19,7 @@ from pydantic_ai.usage import RequestUsage
 from ..tools.declarations import get_visible_tools
 from .base import BackendModelBase, BackendModelSettings, append_text_projected_tool_result_preview_prompt
 from .mcp_server import mcp_server_if_needed
+from .process_management import stop_process
 from .text_projection import TextProjectedRequest, resolve_text_projection_staging_root_directory
 
 type SandboxMode = Literal["read-only", "workspace-write", "danger-full-access"]
@@ -178,7 +179,7 @@ class CodexModel(BackendModelBase):
     def system(self) -> str:
         return "openai"
 
-    async def request(
+    async def _request(
         self,
         messages: list[ModelMessage],
         model_settings: ModelSettings | None,
@@ -193,6 +194,8 @@ class CodexModel(BackendModelBase):
 
         output_schema_file: IO[str] | None = None
         projected_request: TextProjectedRequest | None = None
+        process: asyncio.subprocess.Process | None = None
+        stderr_task: asyncio.Task[bytes] | None = None
 
         try:
             codex_model_settings = CodexModelSettings.from_model_settings(model_settings)
@@ -334,6 +337,10 @@ class CodexModel(BackendModelBase):
         except Exception as exception:
             raise UnexpectedModelBehavior("Codex backend failed") from exception
         finally:
+            if stderr_task is not None and not stderr_task.done():
+                stderr_task.cancel()
+                await asyncio.gather(stderr_task, return_exceptions=True)
+            await stop_process(process)
             if output_schema_file is not None:
                 with contextlib.suppress(Exception):
                     output_schema_file.close()

nighthawk/backends/mcp_boundary.py

@@ -18,12 +18,8 @@ from ..runtime.step_context import (
 )
 from ..tools._tool_return_content import resolve_tool_return_segments
 from ..tools.contracts import (
-    BoundaryFailureObservation,
-    ToolError,
     ToolHandlerResult,
     ToolOutcome,
-    ToolResultObservation,
-    build_tool_result_observation,
     render_tool_handler_result_preview_text,
 )
 from ._text_fallback import (
@@ -53,18 +49,11 @@ def _resolve_effective_tool_result_rendering_policy(
     return _resolve_tool_result_rendering_policy()
 
 
-def _tool_boundary_failure_result(*, message: str, guidance: str) -> ToolResultObservation:
-    tool_outcome: ToolOutcome = {
-        "payload": None,
-        "error": {"kind": "internal", "message": message, "guidance": guidance},
-    }
-    return build_tool_result_observation(tool_outcome=tool_outcome)
-
-
 def _tool_outcome_to_mcp_content_list(
     *,
     tool_name: str,
     tool_outcome: ToolOutcome,
+    rendering_policy: ToolResultRenderingPolicy,
 ) -> list[object]:
     from mcp import types as mcp_types
 
@@ -73,6 +62,7 @@ def _tool_outcome_to_mcp_content_list(
     segments = resolve_tool_return_segments(
         tool_name=tool_name,
         payload=tool_outcome["payload"],
+        rendering_policy=rendering_policy,
     )
     if segments.is_empty_success():
         return []
@@ -97,10 +87,8 @@ def _tool_outcome_to_mcp_content_list(
             if content_item.is_audio:
                 content_block_list.append(mcp_types.AudioContent(type="audio", data=content_item.base64, mime_type=content_item.media_type))
                 continue
-            # Non-image / non-audio blobs project to text per spec §8.3:
-            # MCP's rich transport only has first-class slots for image and
-            # audio media, and Nighthawk intentionally does NOT wrap other
-            # blobs in an ``EmbeddedResource`` with a synthetic URI scheme.
+            # MCP has first-class slots only for image and audio media.
+            # Other blobs project to text rather than an ``EmbeddedResource`` with a synthetic URI scheme.
             content_block_list.append(
                 mcp_types.TextContent(
                     type="text",
@@ -192,6 +180,7 @@ def tool_handler_result_to_low_level_mcp_content(
         return _tool_outcome_to_mcp_content_list(
             tool_name=tool_name,
             tool_outcome=tool_outcome,
+            rendering_policy=effective_rendering_policy,
         )
     except Exception as exception:
         _record_mcp_projection_fallback(tool_name=tool_name, exception=exception)
@@ -221,36 +210,18 @@ def _tool_handler_result_to_claude_code_sdk_content(
     return {"content": dumped_content_block_list}
 
 
-async def _get_safe_tool_handler_result(
+async def _get_tool_handler_result(
     *,
     tool_name: str,
     arguments: dict[str, object],
     tool_handler: ToolHandler,
     parent_otel_context: OtelContext,
 ) -> ToolHandlerResult:
+    context_token = otel_context.attach(parent_otel_context)
     try:
-        context_token = otel_context.attach(parent_otel_context)
-        try:
-            try:
-                return await tool_handler(arguments)
-            except Exception as exception:
-                error_message = str(exception) or "Tool boundary wrapper failed"
-                return _tool_boundary_failure_result(
-                    message=error_message,
-                    guidance="The tool boundary wrapper failed. Retry or report this error.",
-                )
-        finally:
-            otel_context.detach(context_token)
-    except Exception as exception:
-        tool_error: ToolError = {
-            "kind": "internal",
-            "message": str(exception) or "Tool boundary wrapper failed",
-            "guidance": "The tool boundary wrapper failed. Retry or report this error.",
-        }
-        return BoundaryFailureObservation(
-            kind="boundary_failure",
-            tool_error=tool_error,
-        )
+        return await tool_handler(arguments)
+    finally:
+        otel_context.detach(context_token)
 
 
 async def call_tool_for_claude_code_sdk(
@@ -261,7 +232,7 @@ async def call_tool_for_claude_code_sdk(
     parent_otel_context: OtelContext,
     rendering_policy: ToolResultRenderingPolicy | None = None,
 ) -> dict[str, object]:
-    tool_handler_result = await _get_safe_tool_handler_result(
+    tool_handler_result = await _get_tool_handler_result(
         tool_name=tool_name,
         arguments=arguments,
         tool_handler=tool_handler,
@@ -282,7 +253,7 @@ async def call_tool_for_low_level_mcp_server(
     parent_otel_context: OtelContext,
     rendering_policy: ToolResultRenderingPolicy | None = None,
 ) -> list[object]:
-    tool_handler_result = await _get_safe_tool_handler_result(
+    tool_handler_result = await _get_tool_handler_result(
         tool_name=tool_name,
         arguments=arguments,
         tool_handler=tool_handler,

nighthawk/backends/mcp_server.py

@@ -1,10 +1,3 @@
-"""Embedded MCP tool server for provider backends.
-
-Starts a Streamable HTTP MCP server in a background thread, exposing
-Nighthawk tools to CLI-based backends (e.g. Codex) that consume tools
-via an MCP endpoint.
-"""
-
 from __future__ import annotations
 
 import asyncio
@@ -31,8 +24,6 @@ from .tool_bridge import get_current_step_run_context_required
 
 
 class McpServer:
-    """In-process MCP tool server backed by Nighthawk tool handlers."""
-
     def __init__(
         self,
         *,

nighthawk/backends/process_management.py

@@ -0,0 +1,24 @@
+"""Bound cleanup of a coding-agent process after request failure or cancellation."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+
+
+async def stop_process(process: asyncio.subprocess.Process | None) -> None:
+    if process is None or process.returncode is not None:
+        return
+    with suppress(ProcessLookupError):
+        process.terminate()
+    try:
+        await asyncio.wait_for(process.communicate(), timeout=1.0)
+    except TimeoutError:
+        with suppress(ProcessLookupError):
+            process.kill()
+        with suppress(TimeoutError):
+            await asyncio.wait_for(process.communicate(), timeout=1.0)
+    except BaseException:
+        with suppress(ProcessLookupError):
+            process.kill()
+        raise

nighthawk/backends/text_projection.py

@@ -1,12 +1,6 @@
-"""Text projection for backends that must talk to a CLI text channel.
+"""Project request parts into CLI prompt text and staged files.
 
-Converts a ``RequestPromptPartList`` (user-prompt tuples plus tool-return parts)
-into a single prompt string and, when needed, a staged temporary directory that
-holds ``BinaryContent`` bytes as local files.
-
-Backend-specific concerns (transport selection, CLI option assembly) live in
-the individual backend modules. This module must not grow into a general
-projection layer.
+Backend-specific concerns stay in the backend modules; this module must not grow into a general projection layer.
 """
 
 from __future__ import annotations
@@ -38,6 +32,7 @@ from ._text_fallback import (
     is_image_content,
 )
 from .base import RequestPromptPartList
+from .tool_bridge import resolve_current_tool_result_rendering_policy
 
 
 @dataclass
@@ -46,7 +41,6 @@ class TextProjectedRequest:
     temporary_directory: tempfile.TemporaryDirectory[str] | None
 
     def cleanup(self) -> None:
-        """Clean up the temporary directory, if any, suppressing all exceptions."""
         if self.temporary_directory is not None:
             with contextlib.suppress(Exception):
                 self.temporary_directory.cleanup()
@@ -106,22 +100,6 @@ def _sanitize_projected_file_stem(*, identifier: str) -> str:
 
 
 class _TextProjectionStager:
-    """Owns the staging temporary directory for a single projection pass.
-
-    Per-pass orchestration responsibilities bundled here:
-
-    - Lazy lifetime of the staging temporary directory: created on the first
-      call to :meth:`stage_binary` and kept alive across the rest of the
-      projection so that adjacent ``BinaryContent`` items share one directory.
-    - Per-pass file-name collision avoidance via
-      :meth:`_build_unique_projected_file_path`, so two ``BinaryContent`` items
-      that share an identifier within one step do not clobber each other.
-    - Coordination of stem sanitization
-      (:func:`_sanitize_projected_file_stem`) and extension selection
-      (:func:`_guess_file_extension` plus the deterministic
-      ``_KNOWN_MEDIA_TYPE_TO_EXTENSION`` map) at staging time.
-    """
-
     def __init__(self, *, staging_root_directory: Path | None) -> None:
         self._staging_root_directory = staging_root_directory
         self._temporary_directory: tempfile.TemporaryDirectory[str] | None = None
@@ -230,6 +208,7 @@ def _project_tool_return_part_to_text(
     segments = resolve_tool_return_segments(
         tool_name=tool_return_part.tool_name,
         payload=tool_return_part.content,
+        rendering_policy=resolve_current_tool_result_rendering_policy(),
     )
     if segments.is_empty_success():
         return f"Tool return from {tool_return_part.tool_name}:"