Resource-aware, coroutine-safe execution boundary for tools. More...

#include <neograph/api.h>
#include <neograph/host_admission.h>
#include <neograph/json.h>
#include <asio/awaitable.hpp>
#include <chrono>
#include <cstdint>
#include <memory>
#include <optional>
#include <stdexcept>
#include <string>
#include <string_view>

Include dependency graph for tool_execution.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	neograph::ResourceArbiter
	Thread-safe FIFO resource arbiter. More...

class	neograph::ResourceLease
	RAII proof that the caller owns one ResourceArbiter capacity slot. More...

struct	neograph::ResourceRequest
	One admission request to the fair resource arbiter. More...

struct	neograph::ToolEffectGrantIdentity
	Exact host authorization for one invocation of mediated Tool dispatch. More...

class	neograph::ToolExecutionController
	The single tool execution boundary shared by Agent and graph dispatch. More...

class	neograph::ToolExecutionError
	Thrown by the throwing facade ToolExecutionController::execute_async for every terminal status except Succeeded and the two cancellation statuses (which throw graph::CancelledException): it carries the whole typed result. More...

struct	neograph::ToolExecutionIdentity
	Stable request identity used for resource accounting and audit correlation. More...

struct	neograph::ToolExecutionPolicy
	Host-owned policy for a named tool. More...

class	neograph::ToolExecutionPolicyRegistry
	Thread-safe named policy registry owned by an application host. More...

struct	neograph::ToolExecutionResult
	One stable result contract for native async and blocking Tool bridges. More...

class	neograph::ToolRequestRefusal
	What an exception says when the call it ended is known not to have run: the service that hosts the tool refused the request before executing it, such as an MCP JSON-RPC protocol error for invalid params or a gRPC `INVALID_ARGUMENT`. More...

class	neograph::ToolRequestRejected
	Thrown by a Tool that knows its call did not run (see ToolRequestRefusal). More...

Enumerations
enum class	neograph::ToolConcurrency : std::uint8_t { Reentrant , KeyedExclusive , Exclusive , Capacity , SingleFlight , ExternalLimited }
	Scheduler concurrency semantics for one policy-derived resource key. More...

enum class	neograph::ToolEffectClass : std::uint8_t
	Explicit effect classification used to decide retry and recovery behavior.

enum class	neograph::ToolExecutionImplementation : std::uint8_t { NativeAsync , BlockingThread , BlockingProcess }
	How an admitted invocation enters a Tool implementation. More...

enum class	neograph::ToolTerminalStatus : std::uint8_t
	Terminal state returned by the typed tool-execution surface.

Functions
NEOGRAPH_API std::shared_ptr< ToolExecutionController >	neograph::default_tool_execution_controller ()
	Process-default conservative controller for legacy callers.

asio::awaitable< std::string >	neograph::detail::execute_blocking_tool_async (Tool &tool, json arguments)
	Shared bounded executor used only by synchronous Tool fallbacks.

asio::awaitable< std::string >	neograph::detail::execute_process_tool_async (Tool &tool, json arguments, ToolExecutionContext context, std::size_t output_limit_bytes, std::chrono::milliseconds timeout)
	ProcessTool bridge. It returns stdout/stderr and throws a typed bridge exception for timeout, cancellation, input-required, or non-zero exit.

bool	neograph::tool_call_not_started (ToolTerminalStatus status) noexcept
	The statuses of a call that never started: the run was cancelled first, its deadline or queue wait ran out, or admission refused it.

Detailed Description

Resource-aware, coroutine-safe execution boundary for tools.

A Tool is an untrusted unit of work from the scheduler's perspective: an implementation may suspend, block, mutate an external system, or hold a process-wide resource. This contract keeps admission separate from Tool's historical synchronous interface. Every dispatcher enters through a ToolExecutionController; the controller applies a named policy, obtains a lease from a fair FIFO resource arbiter, and only then invokes the tool.

The default policy is deliberately conservative: calls with the same tool name are keyed-exclusive, while different tools may overlap. Hosts that know a tool is re-entrant or that a concrete resource supports N sessions must opt in through ToolExecutionPolicyRegistry. A policy never grants more concurrency implicitly.

Definition in file tool_execution.h.

Enumeration Type Documentation

◆ ToolConcurrency

enum class neograph::ToolConcurrency : std::uint8_t

strong

Scheduler concurrency semantics for one policy-derived resource key.

Enumerator
Reentrant	No arbiter lease. Only safe for a host-declared re-entrant tool.
KeyedExclusive	One active invocation for each derived resource key.
Exclusive	One process-wide invocation regardless of argument-derived aliases.
Capacity	Up to capacity active invocations for each derived resource key.
SingleFlight	One in-flight invocation per key; concurrent callers share its result.
ExternalLimited	The external service owns concurrency; enforce the declared local capacity.

Definition at line 171 of file tool_execution.h.

◆ ToolExecutionImplementation

enum class neograph::ToolExecutionImplementation : std::uint8_t

strong

How an admitted invocation enters a Tool implementation.

Enumerator
NativeAsync	Call Tool::execute_async. The base implementation offloads sync work.
BlockingThread	Invoke Tool::execute on the bounded blocking executor explicitly.
BlockingProcess	Launch a ProcessTool in its own process group on the blocking bridge.

Definition at line 42 of file tool_execution.h.

Function Documentation

◆ tool_call_not_started()

bool neograph::tool_call_not_started ( ToolTerminalStatus status )

inlinenoexcept

The statuses of a call that never started: the run was cancelled first, its deadline or queue wait ran out, or admission refused it.

Such a call performed no effect; a ToolEffectBroker records it as terminal with no effect and frees its slot.

Definition at line 72 of file tool_execution.h.

References neograph::tool_call_not_started().

Referenced by neograph::tool_call_not_started().

Classes