Module agentforge4j.testkit
Package com.agentforge4j.testkit.tool

Class ScriptedToolProvider

java.lang.Object
com.agentforge4j.testkit.tool.ScriptedToolProvider
All Implemented Interfaces:
ToolProvider
public final class ScriptedToolProvider extends Object implements ToolProvider
A deterministic, in-process ToolProvider for tests: it advertises a single capability and — depending on the factory — returns a fixed ToolResult, throws, or blocks until interrupted, with no network transport. Use it to drive the runtime tool-governance path (resolve → validate → policy → invoke, the approval / decision suspend-resume branches, and the provider-crash / authoritative-timeout failure arms) without standing up an MCP server.

  • Constructor Details

    • ScriptedToolProvider

      public ScriptedToolProvider(String providerId, String capability, ToolResult result, String inputSchema)
      Creates a provider serving one capability with a fixed result and an explicit input schema (used to drive the argument-validation branch of the governance chokepoint).
      Parameters:
      providerId - stable provider id; must not be blank
      capability - the capability id; must not be blank
      result - the result returned on every invocation; must not be null
      inputSchema - the JSON-schema text advertised for the capability; must not be blank

  • Method Details

    • succeeding

      public static ScriptedToolProvider succeeding(String providerId, String capability, String output)
      Creates a provider whose capability succeeds with the given output.
      Parameters:
      providerId - stable provider id
      capability - the capability id
      output - the success output payload
      Returns:
      a succeeding provider

    • requiring

      public static ScriptedToolProvider requiring(String providerId, String capability, String output, String requiredProperty)
      Creates a succeeding provider that advertises requiredProperty as a required top-level input field, so a TOOL_INVOCATION whose arguments omit it fails argument validation and drives the run to AWAITING_TOOL_DECISION before the provider is ever invoked.
      Parameters:
      providerId - stable provider id
      capability - the capability id
      output - the success output payload (returned only if validation passed)
      requiredProperty - the input property the capability requires
      Returns:
      a succeeding provider with a required-field input schema

    • failing

      public static ScriptedToolProvider failing(String providerId, String capability, String errorMessage)
      Creates a provider whose capability fails with the given message (drives the decision-on-failure path to AWAITING_TOOL_DECISION).
      Parameters:
      providerId - stable provider id
      capability - the capability id
      errorMessage - the failure message
      Returns:
      a failing provider

    • throwing

      public static ScriptedToolProvider throwing(String providerId, String capability, RuntimeException failure)
      Creates a provider whose capability throws from invoke instead of returning a result — driving the execution-exception arm of the governance chokepoint (a provider bug or transport crash), which a result-failure cannot reach.
      Parameters:
      providerId - stable provider id
      capability - the capability id
      failure - the exception thrown on every invocation; must not be null
      Returns:
      a throwing provider

    • hanging

      public static ScriptedToolProvider hanging(String providerId, String capability)
      Creates a provider whose capability blocks until interrupted — driving the authoritative-timeout arm of the governance chokepoint. Pair it with a short ToolExecutionOptions timeout on the harness so the test stays fast; the execution service cancels the invocation, which interrupts and releases the blocked call.
      Parameters:
      providerId - stable provider id
      capability - the capability id
      Returns:
      a hanging provider

    • providerId

      public String providerId()
      Specified by:
      providerId in interface ToolProvider
      Returns:
      stable, non-blank provider id, for example "mcp:github-official"

    • listTools

      public List<ToolDescriptor> listTools()
      Specified by:
      listTools in interface ToolProvider
      Returns:
      descriptors for every tool this provider currently exposes

    • invoke

      public ToolResult invoke(ToolDescriptor descriptor, String arguments, ToolInvocationContext ctx, ToolExecutionOptions options)
      Description copied from interface: ToolProvider
      Invokes the resolved tool.
      Specified by:
      invoke in interface ToolProvider
      Parameters:
      descriptor - resolved descriptor; use ToolSource.remoteToolName() for the remote name
      arguments - tool arguments as JSON text, or null
      ctx - invocation context
      options - tunables; the provider may honour these best-effort, but the authoritative timeout is enforced by the execution service
      Returns:
      the invocation result

    • health

      public HealthStatus health()
      Specified by:
      health in interface ToolProvider
      Returns:
      current provider health