hyperforge 1.0.0.post326__tar.gz → 1.0.0.post332__tar.gz

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hyperforge
-Version: 1.0.0.post326
+Version: 1.0.0.post332
 Summary: Agentic Framework for Orchestrated Runtime, Governance, and Execution
 Author: AI Data Team
 Author-email: AI Data Team <learning@nuclia.com>

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "hyperforge"
-version = "1.0.0.post326"
+version = "1.0.0.post332"
 description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
 readme = "README.md"
 requires-python = ">=3.12"

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "hyperforge"
-version = "1.0.0.post326"
+version = "1.0.0.post332"
 authors = [{ name = "AI Data Team", email = "learning@nuclia.com" }]
 description = "Agentic Framework for Orchestrated Runtime, Governance, and Execution"
 readme = "README.md"

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/codemode/sandbox.py

@@ -8,7 +8,7 @@ from concurrent.futures import Executor, ThreadPoolExecutor
 from concurrent.futures import Future as ConcurrentFuture
 from multiprocessing import Pipe, Process
 from multiprocessing.connection import Connection
-from typing import Any, Callable, Coroutine
+from typing import Any, Awaitable, Callable, Coroutine
 
 import httpx
 import nucliadb_telemetry.metrics
@@ -25,7 +25,6 @@ from .model import (
 from .worker import PythonAgentWorker
 
 logger = logging.getLogger("hyperforge_codemode_sandbox")
-WORKER_CPU_LIMIT = 1
 WORKER_EXIT_TIMEOUT = 1
 MAX_PACKET_BYTES = 16 * 1024 * 1024
 
@@ -35,6 +34,7 @@ class SandboxSettings(BaseSettings):
     sandbox_socket: str | None = None
     sandbox_metrics_port: int = 8091
     sandbox_token: str | None = None
+    sandbox_callback_wait_seconds: float = 1.0
 
 
 settings = SandboxSettings()
@@ -60,8 +60,16 @@ class SandboxRunner:
         socket: str,
         callback: Callable[[RestrictedPythonTask], Coroutine[Any, Any, WorkerTypes]],
         debug: bool = False,
+        *,
+        token: str | Callable[[], str] | None = None,
     ) -> "SandboxRunner":
-        return cls(pool=None, socket=socket, callback=callback, debug=debug)
+        return cls(
+            pool=None,
+            socket=socket,
+            callback=callback,
+            debug=debug,
+            token=token,
+        )
 
     @classmethod
     def isolated_process(
@@ -78,12 +86,14 @@ class SandboxRunner:
         socket: str | None,
         callback: Callable[[RestrictedPythonTask], Coroutine[Any, Any, WorkerTypes]],
         debug: bool,
+        token: str | Callable[[], str] | None = None,
     ):
         self.pool = pool
         self.socket = socket
         self.callback = callback
         self.debug = debug
         self.isolated = False
+        self.token = token
 
     async def run(self, request: WorkerExecutionRequest):
         if self.pool is not None:
@@ -137,14 +147,19 @@ class SandboxRunner:
             await asyncio.gather(controller_task, return_exceptions=True)
 
     async def _run_remotely(self, request: WorkerExecutionRequest):
-        if settings.sandbox_token is None:
+        token_source = self.token
+        if token_source is None:
+            token = SandboxSettings().sandbox_token
+        elif isinstance(token_source, str):
+            token = token_source
+        else:
+            token = token_source()
+        if token is None:
             raise RuntimeError("SANDBOX_TOKEN is required for remote codemode")
         rx, tx = await asyncio.open_unix_connection(self.socket)
         reader, writer = SandboxReader(rx), SandboxWriter(tx)
         try:
-            await writer.write_message(
-                SandboxMessage.Run(run=request, token=settings.sandbox_token)
-            )
+            await writer.write_message(SandboxMessage.Run(run=request, token=token))
             while True:
                 try:
                     msg = await reader.read_message()
@@ -291,9 +306,15 @@ class SandboxReader:
 
 
 class SandboxSession:
-    def __init__(self, reader: SandboxReader, writer: SandboxWriter):
+    def __init__(
+        self,
+        reader: SandboxReader,
+        writer: SandboxWriter,
+        callback_wait_seconds: float = 1.0,
+    ):
         self.reader = reader
         self.writer = writer
+        self.callback_wait_seconds = callback_wait_seconds
         self.runner = SandboxRunner(
             pool=None, socket=None, callback=self._callback, debug=False
         )
@@ -303,7 +324,7 @@ class SandboxSession:
     async def run(self, request: WorkerExecutionRequest):
         self.task, self.process = self.runner.run_in_process(request)
         try:
-            await self._start_timeout(WORKER_CPU_LIMIT)
+            await self._start_timeout(self.callback_wait_seconds)
             if request.max_runtime_seconds is None:
                 clean_exit = await self.task
             else:
@@ -358,7 +379,7 @@ class SandboxSession:
             self.task.cancel()
             return None
         assert isinstance(response, SandboxMessage.Response)
-        await self._start_timeout(WORKER_CPU_LIMIT)
+        await self._start_timeout(self.callback_wait_seconds)
         return response.result
 
     async def _start_timeout(self, timeout: float):
@@ -382,12 +403,15 @@ agents_running = prometheus_client.Gauge(
 execution_observer = nucliadb_telemetry.metrics.Observer("arag_sandbox_execution")
 
 
-async def run_sandbox_server():
-    assert settings.sandbox_socket is not None
-    sandbox_token = settings.sandbox_token
-    if sandbox_token is None:
+async def run_sandbox_server(
+    *, token_verifier: Callable[[str], Awaitable[bool]] | None = None
+):
+    server_settings = SandboxSettings()
+    assert server_settings.sandbox_socket is not None
+    sandbox_token = server_settings.sandbox_token
+    if token_verifier is None and sandbox_token is None:
         raise RuntimeError("SANDBOX_TOKEN is required for the sandbox server")
-    if settings.sandbox_verify:
+    if server_settings.sandbox_verify:
         _verify_connectivity()
 
     async def handler(rx: asyncio.StreamReader, tx: asyncio.StreamWriter):
@@ -397,10 +421,16 @@ async def run_sandbox_server():
             async with asyncio.timeout(1):
                 msg = await reader.read_message()
                 assert isinstance(msg, SandboxMessage.Run)
-                if not hmac.compare_digest(msg.token or "", sandbox_token):
+                token = msg.token or ""
+                valid_token = (
+                    await token_verifier(token)
+                    if token_verifier is not None
+                    else hmac.compare_digest(token, sandbox_token or "")
+                )
+                if not valid_token:
                     raise PermissionError("Invalid sandbox token")
-        except (AssertionError, PermissionError, TimeoutError, ValueError):
-            logger.warning("Rejected invalid sandbox connection")
+        except Exception as exc:
+            logger.warning("Rejected invalid sandbox connection: %r", exc)
             writer.close()
             await writer.wait_closed()
             return
@@ -409,7 +439,9 @@ async def run_sandbox_server():
         observation = execution_observer()
         observation.start()
         try:
-            session = SandboxSession(reader, writer)
+            session = SandboxSession(
+                reader, writer, SandboxSettings().sandbox_callback_wait_seconds
+            )
             await session.run(msg.run)
         except Exception as exc:
             observation.set_status("error")
@@ -420,7 +452,7 @@ async def run_sandbox_server():
             writer.close()
             await writer.wait_closed()
 
-    server = await asyncio.start_unix_server(handler, settings.sandbox_socket)
-    os.chmod(settings.sandbox_socket, 0o600)
+    server = await asyncio.start_unix_server(handler, server_settings.sandbox_socket)
+    os.chmod(server_settings.sandbox_socket, 0o600)
     async with server:
         await server.serve_forever()

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/__init__.py

@@ -39,13 +39,14 @@ from .models import (
     HarnessToolCall,
 )
 from .storage import HarnessStorageProtocol, InMemoryHarnessStorage
-from .tools import HarnessTool, tool
+from .tools import HarnessTool, ToolCallContext, tool
 from .tools.codemode import CodemodeInput, CodemodeOutput, codemode
 from .usage import HarnessUsage, UsageLimitExceeded, UsageLimits
 
 __all__ = [
     "SYSTEM_PROMPT",
     "AgentHarness",
+    "ToolCallContext",
     "AgentResult",
     "ChatCompletionChunk",
     "ChatCompletionChoice",

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/agents.py

@@ -23,7 +23,7 @@ from hyperforge.memory.memory import BaseSessionMemory
 from hyperforge.models import Context, MemoryConfig, Rules
 
 from .models import HarnessContextReference, HarnessContextType
-from .tools import HarnessTool
+from .tools import HarnessTool, ToolCallContext
 
 if TYPE_CHECKING:
     from hyperforge.agent import Agent as HyperforgeAgent
@@ -64,8 +64,9 @@ class HarnessAgentToTool:
 
     def as_tool(self) -> HarnessTool[AgentToolInput, AgentToolOutput]:
         async def execute(
-            harness: AgentHarness, input_value: AgentToolInput
+            context: ToolCallContext, input_value: AgentToolInput
         ) -> AgentToolOutput:
+            harness = context.harness
             memory = self.memory_factory(harness, input_value.prompt)
             if inspect.isawaitable(memory):
                 memory = await memory
@@ -143,8 +144,9 @@ def _published_function_tool(
     input_model = _published_input_model(method, function_id, definition)
 
     async def execute(
-        harness: AgentHarness, input_value: BaseModel
+        context: ToolCallContext, input_value: BaseModel
     ) -> PublishedFunctionOutput:
+        harness = context.harness
         compat_manager = manager or _compat_manager(harness)
         memory = harness.execution_context.get("memory")
         if memory is None:

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/harness.py

@@ -23,7 +23,7 @@ from .models import (
     HarnessToolCall,
 )
 from .storage import HarnessStorageProtocol, InMemoryHarnessStorage
-from .tools import HarnessTool
+from .tools import HarnessTool, ToolCallContext
 from .tools.core import DictOutput, SendMessageInput, SpawnAgentInput, create_core_tools
 from .usage import HarnessUsage, UsageLimitExceeded, UsageLimits
 
@@ -955,7 +955,8 @@ class AgentHarness:
     async def _execute_tool_call(self, call: HarnessToolCall) -> HarnessMessage:
         assert call.id is not None
         await self.emit(
-            HarnessEventType.TOOL_REQUESTED, {"call": call.model_dump(mode="json")}
+            HarnessEventType.TOOL_REQUESTED,
+            {"call": call.model_dump(mode="json")},
         )
         tool = self._tools.get(call.name)
         try:
@@ -965,7 +966,8 @@ class AgentHarness:
             elif tool.lazy_load and tool.name not in self._active_lazy_tools:
                 raise ValueError(f"Tool is not active: {call.name}")
             else:
-                output = await tool.execute(self, call.arguments)
+                context = ToolCallContext(harness=self, name=call.name, id=call.id)
+                output = await tool.execute(context, call.arguments)
                 result = output.model_dump(mode="json")
                 reference = tool.context(output)
                 content = format_context(reference)
@@ -981,7 +983,7 @@ class AgentHarness:
                 context=reference,
             )
         except Exception as exc:
-            logger.warning(
+            logger.info(
                 "Agent tool execution failed: tool=%s call_id=%s error_type=%s error=%s",
                 call.name,
                 call.id,

hyperforge-1.0.0.post332/src/hyperforge/harness_sdk/tools/__init__.py

@@ -0,0 +1,9 @@
+from .utils import (
+    ContextFactory,
+    HarnessTool,
+    ToolCallContext,
+    ToolHandler,
+    tool,
+)
+
+__all__ = ["ContextFactory", "HarnessTool", "ToolCallContext", "ToolHandler", "tool"]

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/tools/codemode.py

@@ -10,7 +10,7 @@ from hyperforge.codemode import (
 from hyperforge.codemode.sandbox import settings
 from hyperforge.definition import FunctionDefinition
 
-from . import HarnessTool, tool
+from . import HarnessTool, ToolCallContext, tool
 
 CODEMODE_TOOL_NAME = "codemode"
 OUTPUT_FUNCTION_NAME = "output"
@@ -31,7 +31,10 @@ class CodemodeOutput(BaseModel):
         "call output(value) to return a result."
     ),
 )
-async def codemode(harness: Any, input_value: CodemodeInput) -> CodemodeOutput:
+async def codemode(
+    context: ToolCallContext, input_value: CodemodeInput
+) -> CodemodeOutput:
+    harness = context.harness
     tools = {
         tool.name: tool
         for tool in harness.iter_tools()
@@ -54,7 +57,9 @@ async def codemode(harness: Any, input_value: CodemodeInput) -> CodemodeOutput:
         harness.usage.tool_calls += 1
         harness._check_limit("max_tool_calls", harness.usage.tool_calls)
         arguments = _tool_arguments(tool, task.args, task.keyword_args)
-        output = await tool.execute(harness, arguments)
+        output = await tool.execute(
+            ToolCallContext(harness=harness, name=tool.name), arguments
+        )
         return output.model_dump(mode="json")
 
     runner = (

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/tools/core.py

@@ -2,15 +2,12 @@ from __future__ import annotations
 
 import uuid
 from re import findall
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from pydantic import BaseModel
 
 from ..models import HarnessEventType, HarnessMemory, HarnessMessage
-from . import HarnessTool, tool
-
-if TYPE_CHECKING:
-    from ..harness import AgentHarness
+from . import HarnessTool, ToolCallContext, tool
 
 
 class RememberInput(BaseModel):
@@ -78,8 +75,9 @@ def _search_terms(value: str) -> set[str]:
 
 @tool(description="Search for additional tools that can be activated.")
 async def search_tools(
-    harness: AgentHarness, input_value: SearchToolsInput
+    context: ToolCallContext, input_value: SearchToolsInput
 ) -> ListOutput:
+    harness = context.harness
     terms = _search_terms(input_value.query)
     candidates: list[tuple[int, HarnessTool[Any, Any]]] = []
     for candidate in harness._external_tools:
@@ -104,8 +102,9 @@ async def search_tools(
 
 @tool(description="Activate additional tools by their exact names.")
 async def activate_tools(
-    harness: AgentHarness, input_value: ActivateToolsInput
+    context: ToolCallContext, input_value: ActivateToolsInput
 ) -> DictOutput:
+    harness = context.harness
     names = list(dict.fromkeys(input_value.names))
     unknown = [
         name
@@ -119,7 +118,8 @@ async def activate_tools(
 
 
 @tool()
-async def remember(harness: AgentHarness, input_value: RememberInput) -> DictOutput:
+async def remember(context: ToolCallContext, input_value: RememberInput) -> DictOutput:
+    harness = context.harness
     memory = HarnessMemory(
         id=uuid.uuid4().hex,
         text=input_value.text,
@@ -135,7 +135,8 @@ async def remember(harness: AgentHarness, input_value: RememberInput) -> DictOut
 
 
 @tool()
-async def recall(harness: AgentHarness, input_value: RecallInput) -> ListOutput:
+async def recall(context: ToolCallContext, input_value: RecallInput) -> ListOutput:
+    harness = context.harness
     memories = await harness.storage.recall(
         scope=input_value.scope,
         query=input_value.query,
@@ -144,7 +145,8 @@ async def recall(harness: AgentHarness, input_value: RecallInput) -> ListOutput:
 
 
 @tool()
-async def forget(harness: AgentHarness, input_value: ForgetInput) -> DictOutput:
+async def forget(context: ToolCallContext, input_value: ForgetInput) -> DictOutput:
+    harness = context.harness
     await harness.storage.forget(input_value.id)
     await harness.emit(HarnessEventType.MEMORY_FORGOTTEN, {"id": input_value.id})
     return DictOutput(value={"id": input_value.id})
@@ -152,25 +154,26 @@ async def forget(harness: AgentHarness, input_value: ForgetInput) -> DictOutput:
 
 @tool()
 async def spawn_agent(
-    harness: AgentHarness, input_value: SpawnAgentInput
+    context: ToolCallContext, input_value: SpawnAgentInput
 ) -> DictOutput:
-    return await harness._child_agents.spawn(input_value)
+    return await context.harness._child_agents.spawn(input_value)
 
 
 @tool()
 async def send_message(
-    harness: AgentHarness, input_value: SendMessageInput
+    context: ToolCallContext, input_value: SendMessageInput
 ) -> DictOutput:
-    return await harness._child_agents.send_message(input_value)
+    return await context.harness._child_agents.send_message(input_value)
 
 
 @tool()
-async def wait_agent(harness: AgentHarness, input_value: AgentIdInput) -> DictOutput:
-    return await harness._child_agents.wait(input_value.agent_id)
+async def wait_agent(context: ToolCallContext, input_value: AgentIdInput) -> DictOutput:
+    return await context.harness._child_agents.wait(input_value.agent_id)
 
 
 @tool()
-async def compact(harness: AgentHarness, input_value: CompactInput) -> DictOutput:
+async def compact(context: ToolCallContext, input_value: CompactInput) -> DictOutput:
+    harness = context.harness
     harness.messages = [
         HarnessMessage(role="system", content=harness.system_prompt),
         HarnessMessage(
@@ -185,8 +188,8 @@ async def compact(harness: AgentHarness, input_value: CompactInput) -> DictOutpu
 
 
 @tool()
-async def feedback(harness: AgentHarness, input_value: FeedbackInput) -> DictOutput:
-    response = await harness.request_feedback(
+async def feedback(context: ToolCallContext, input_value: FeedbackInput) -> DictOutput:
+    response = await context.harness.request_feedback(
         question=input_value.question,
         response_schema={
             "type": "object",

{hyperforge-1.0.0.post326 → hyperforge-1.0.0.post332}/src/hyperforge/harness_sdk/tools/utils.py

@@ -16,11 +16,24 @@ if TYPE_CHECKING:
     from ..harness import AgentHarness
 
 type ToolHandler[InputT: BaseModel, OutputT: BaseModel] = Callable[
-    ["AgentHarness", InputT], Awaitable[OutputT]
+    [ToolCallContext, InputT], Awaitable[OutputT]
 ]
 type ContextFactory[OutputT: BaseModel] = Callable[[OutputT], HarnessContextReference]
 
 
+@dataclass(frozen=True)
+class ToolCallContext:
+    """Execution context passed to a tool handler.
+
+    Provides the harness along with the identity of the tool call
+    currently being executed.
+    """
+
+    harness: "AgentHarness"
+    name: str
+    id: str | None = None
+
+
 @dataclass(frozen=True)
 class HarnessTool[InputT: BaseModel, OutputT: BaseModel]:
     name: str
@@ -38,10 +51,11 @@ class HarnessTool[InputT: BaseModel, OutputT: BaseModel]:
         parameters = list(inspect.signature(self.handler).parameters.values())
         if len(parameters) != 2:
             raise TypeError(
-                f"Tool handler {self.name!r} must accept harness and input parameters"
+                f"Tool handler {self.name!r} must accept context and input parameters"
             )
         globalns = dict(getattr(self.handler, "__globals__", {}))
         globalns.setdefault("AgentHarness", object)
+        globalns.setdefault("ToolCallContext", ToolCallContext)
         hints = get_type_hints(self.handler, globalns=globalns)
         input_model = hints.get(parameters[1].name)
         output_model = hints.get("return")
@@ -65,12 +79,12 @@ class HarnessTool[InputT: BaseModel, OutputT: BaseModel]:
         return self._parameters
 
     def __call__(
-        self, harness: AgentHarness, input_value: InputT
+        self, context: ToolCallContext, input_value: InputT
     ) -> Awaitable[OutputT]:
-        return self.handler(harness, input_value)
+        return self.handler(context, input_value)
 
     async def execute(
-        self, harness: AgentHarness, arguments: dict[str, Any]
+        self, context: ToolCallContext, arguments: dict[str, Any]
     ) -> OutputT:
         if error := arguments.get("_tool_error"):
             raise ValueError(str(error))
@@ -85,7 +99,7 @@ class HarnessTool[InputT: BaseModel, OutputT: BaseModel]:
             value = self.input_model.model_validate(arguments)
         except ValidationError as exc:
             raise ValueError(f"Invalid {self.name} arguments: {exc}") from exc
-        result = await self.handler(harness, value)
+        result = await self.handler(context, value)
         return self.output_model.model_validate(result)
 
     def context(self, output: OutputT) -> HarnessContextReference:
@@ -123,4 +137,4 @@ def _is_model_type(value: Any) -> bool:
     return isinstance(value, type) and issubclass(value, BaseModel)
 
 
-__all__ = ["ContextFactory", "HarnessTool", "ToolHandler", "tool"]
+__all__ = ["ContextFactory", "HarnessTool", "ToolCallContext", "ToolHandler", "tool"]

hyperforge-1.0.0.post326/src/hyperforge/harness_sdk/tools/__init__.py

@@ -1,8 +0,0 @@
-from .utils import (
-    ContextFactory,
-    HarnessTool,
-    ToolHandler,
-    tool,
-)
-
-__all__ = ["ContextFactory", "HarnessTool", "ToolHandler", "tool"]