All Classes and Interfaces
Class
Description
Base
LlmClient for HTTP JSON APIs: shared validation, transport, logging, and error
wrapping.Step that invokes a single agent with optional retry policy.
ArtifactValidator that asserts a generated agent bundle "loads as a valid AgentDefinition" by running
the production parse/validate path on the captured artifacts: Jackson-parse agent.json, validate core fields,
resolve the system prompt (inline or from the captured systemprompt.md / boundaries.md), and build
the definition (applying the record's invariants).Resolves shipped agent bundle resources from the classpath.
ArtifactValidator for the full Agent Creator output bundle: the agent definition plus the generated
verification starter.ArtifactValidatorFactory for the built-in agent-creator-bundle validator, discovered via
ServiceLoader.Represents the definition of an agent, including its configuration and capabilities.
Fluent builder for
AgentDefinition.Shared production path that turns a parsed
AgentDefinitionFile into a loadable AgentDefinition:
core-field validation, system-prompt resolution (inline, else a systemprompt.md sibling optionally appended
with boundaries.md), and conversion via AgentDefinitionFile.toDefinition(String) (which applies the
record's own invariants).Resolves a sibling file's content by name, returning
null when absent.Mutable DTO representing the JSON shape of an agent bundle file.
Immutable facade exposing the assembled AgentForge4j runtime and loaded configuration.
Static entry point for assembling an
AgentForge4j facade with framework-agnostic defaults.Builder for
AgentForge4j.Loads and validates agent and workflow configuration from filesystem and optional classpath
bundles.
The parsed result of a single LLM call: the raw response text plus the parsed list of commands.
Fluent builder for
AgentInvocationResult.Drives a single agent invocation: resolves the agent definition, picks the first enabled provider preference, renders
the input context as JSON, executes against the resolved
LlmClient, and parses the structured command
output.Builder for
AgentInvoker.Loads agent definitions from a backing source.
Specifies where an agent executes, determining the operational environment.
Thrown when an agent with the given id is not found in the agent repository.
Resolves effective system prompt text for an agent definition.
Repository for accessing agent definitions.
Deterministic, in-workflow aggregation: runs the registered
ContextAggregator named by
aggregatorId over the step's declared contextMapping input keys and writes each
returned logical field back to context under <outputContextKeyPrefix>.<fieldName>.Read-only view passed to a
ContextAggregator: the run context values keyed by the
selecting AGGREGATE step's declared contextMapping input keys.A step id that is reachable from more than one structural location across a workflow graph, with the conflicting
locations.
A human decision on a pending tool invocation, supplied to
ToolExecutionService.resume(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.ApprovalDecision).Approve the pending invocation.
Reject the pending invocation.
The outcome of a human approval decision on a gated step.
Defines a collection of input items that the UI renders as a form.
Durable, content-free record of a file a step emitted during a run, persisted on
WorkflowState.Sealed marker interface for form input items, dispatched by type for rendering.
Read-only view passed to an
ArtifactValidator: the artifacts the selecting VALIDATE step declared in
its requiredArtifacts, captured in-process for the run and keyed by their requested path.SPI for the format-specific validation of a generated artifact bundle, selected by a stable
ArtifactValidator.validatorId()
that a VALIDATE step names.Factory that produces an
ArtifactValidator configured with the supplied ObjectMapper.Deterministically assigns a literal scalar
ContextValue to contextKey, with no LLM call.How a collection gate authorizes operations.
Shared loading flow for agent bundle sources.
Loads workflow definitions from a backing source.
Loop configuration and post-loop transition for a reusable blueprint.
Reusable subgraph: id, display name, loop and transition behaviour, and an ordered list of child
executables.
Reference to a
BlueprintDefinition by id for inclusion in a parent workflow.Thrown by
WorkflowTreeWalker when a workflow's structural shape is broken — a
BlueprintRef that does not resolve, or
nesting past the walk's configured depth limit (indicating a circular blueprint reference).How the request body of an
HttpEndpointDefinition is formed from leftover arguments.Boolean artifact field with shared
ArtifactItem id and label rules.Boolean payload stored in workflow context.
Exposes the individual components assembled by
AgentForge4jBootstrap.Conditional routing: chooses one
Executable branch using the value at
contextKey.One ordered predicate evaluated by a
BranchBehaviour before its exact-match branches.The kind of match a
BranchPredicate performs against a branch step's resolved context value.Thrown when a capability cannot be resolved to exactly one provider — either none fulfils it or
more than one does (ambiguous).
The passive captures gathered during one harnessed run: the ordered event stream and the files
the run produced.
One file a run requested through the
CapturingFileSink, recorded in memory.In-memory
FileSink that captures every write instead of touching disk, so a test can
assert which files a run produced.A
WorkflowEventLog decorator that records every appended event in order while delegating
to a backing log.Thrown at load time when a shipped workflow catalog is present on the classpath but is
incompatible with the running framework: its manifest is missing or unparseable, the framework
version falls outside the catalog's declared bounds, or its workflow schema version is
unsupported.
Enforces compatibility between a shipped workflow catalog and the running framework, before the
catalog's workflows are loaded.
Compatibility metadata declared by a shipped workflow catalog, read from
shipped-workflows/agentforge4j-catalog.json.Loads agent definitions from shipped classpath bundles.
Loads JSON schema documents from classpath resources in
/schema.Loads shipped workflow bundles from classpath resources.
Why a collection gate was closed, recorded on
CollectionState and in the close audit event.Strips markdown code-fence markers from LLM output text.
Step that suspends the run into a collection gate, accepting zero or more submissions over time
while the run stays paused, until the gate is explicitly closed (and optionally reopened).
One logical submission slot in a collection gate.
Content carried by a single collection submission: an optional bounded inline JSON string and zero
or more file references.
Lifecycle phase of a collection gate held in
CollectionState.Immutable snapshot of one collection gate's state, held per step on the run's
WorkflowState.Immutable input bundle passed to
CommandHandler.apply(com.agentforge4j.core.command.LlmCommand, CommandApplicationRequest).Outcome of applying a sequence of
LlmCommands in order.Dispatches each
LlmCommand to its registered CommandHandler and returns the first
non-CommandApplicationResult.CONTINUE result, or CommandApplicationResult.CONTINUE
when every command continues.Strategy for applying one concrete
LlmCommand type to
WorkflowState and related context.Describes the allowed command set and required JSON properties per command for one agent.
Renders
CommandResponseSchema as a deterministic instruction block for prompt injection.Builds a
CommandResponseSchema from an agent's supportedCommands, using Jackson
introspection on the sealed LlmCommand implementations (no duplicated field lists).Per-command JSON contract: Jackson property names marked required (excluding the polymorphic
type discriminator).Signal that the current step or loop iteration is complete.
Deterministic complexity classification of a unit of work, ordered by increasing structure and
variance.
Confidence in an execution estimate, driven by structural predictability and envelope width.
In-memory
ModelTierResolver backed by a static provider→tier→model map.SPI for deterministic, in-workflow aggregation, selected by a stable
ContextAggregator.aggregatorId()
that an AGGREGATE step names.A deterministic equality contract a
VALIDATE step enforces between a generated artifact and a run-context
value: the JSON value at jsonPointer within the artifact at artifactPath must equal the value of
context key contextKey (exposed to the step via its inputKeys).Defines which context keys a step reads from and writes to.
Origin of a
ContextValue — who produced the content.Renders the subset of the shared context exposed to an agent as a JSON object — filtering by
ContextMapping.inputKeys() when a mapping is provided.Sealed marker interface for typed context values stored in the shared workflow context.
Ordered list of
ContextValue entries treated as a single context value for
serialization.Signal that the current step should proceed to the next iteration or phase.
Instruct the runtime to create a file with the given content at the given path.
Date input field.
Decorrelated-jitter backoff delay computation, shared by every retry loop in the codebase that
needs to space out attempts against a transient failure.
Default
LlmClientResolver: builds an immutable map of provider id to LlmClient.Pure-
core RequirementResolver: returns a requirement's declared default and nothing else.ToolCatalog that delegates to the ToolProviderResolver, so the advertised catalog
and the resolver can never drift.Default
ToolExecutionService: the single chokepoint for tool invocation.Default
WorkflowRuntime implementation.Thrown when the same agent id would be registered from more than one source.
How a collection gate treats duplicate submissions.
Thrown when the same workflow id would be registered from more than one source.
Outcome of an
OutboundEgressGuard classification of a target URL.OSS default
SecretResolver: resolves a reference key against the process environment first and JVM system
properties second, so a reference such as "GITHUB_TOKEN" is read from System.getenv(String) or,
failing that, System.getProperty(String).Default
LlmSecretResolver for the embeddable bootstrap path.One epic within an
EpicPackage — the minimal shape Mode 2 estimation needs: identity and
an optional expected-case rework-iteration hint.A minimal, typed epic breakdown for Mode 2 (SDLC / epic-package) estimation — the caller-supplied
package of epics an Epic Creator (or an equivalent requirements breakdown) produced.
Deterministic structural analysis of an
EpicPackage for Mode 2 (SDLC / epic-package)
estimation, producing the same WorkflowComplexityAnalysis shape
WorkflowComplexityAnalyzer produces for Mode 1 — so both modes compose through the same
WorkflowExecutionAggregator.Signal that the current step cannot proceed without human intervention.
Thin helper that builds
WorkflowEvent instances and appends them to the configured
WorkflowEventLog.Sealed marker interface for directly placeable workflow components: steps, blueprint references,
and nested workflows.
Thrown by a
RunExecutionInterceptor to deliberately block a run from proceeding — for example when a budget
control declines to admit the next LLM call.The neutral execution-estimate report produced by
WorkflowExecutionAggregator: the token
envelope, the deterministic minimum input floor, the sized turn / tool / step figures, the
complexity and confidence, the structural risk flags, and the continue/narrow/stop recommendation.Thrown when a workflow execution with the given id is not found.
Terminal behaviour that forces step failure with the supplied
reason (not validated
here).The discriminator of a run failure, mirroring the
kind of
com.agentforge4j.core.workflow.state.RunFailure.Configuration for the fake provider.
Identity a
FakeLlmClient passes to a FakeResponseSource for one invocation.Stateless
LlmClient that replays pre-scripted responses instead of calling a model.LlmClientFactory for the fake provider, discovered via ServiceLoader.Outcome of a single
FakeResponseSource.nextResponse(FakeInvocation) call.A scripted response was found for the invocation's key.
A script is registered for the run, but it has no entry for this key (the ordinal counter has already advanced past
the miss — acceptable, since a miss is a fail-closed terminal).
No script is registered for the invocation's run.
A single scripted response: the raw model text the fake provider returns, and optional script-specified token usage.
Thrown when the fake provider cannot resolve a scripted response: the request carried no invocation identity, no
script is registered for the run, or the run's script has no entry for the resolved key.
Supplies scripted responses to a
FakeLlmClient.The single per-run store for the fake provider: each run id maps to one entry holding the run's
FakeScript
and its ordinal counters, so registering, deregistering, or evicting a run clears both in one place — there
is no separate counter map to keep in sync, and the FakeLlmClient stays stateless.An immutable set of scripted responses for one run, keyed by
FakeScriptKey.Intra-script lookup key for a single scripted response.
Parses fake-provider script JSON into an immutable
FakeScript.Script-specified token usage for one response, mirroring
TokenUsageReport exactly:
four nullable counts, no total.Reference to a file submitted into a collection gate.
Abstraction over the
CreateFileCommand side effect.Loads agent bundles from filesystem directories.
Resolves agent prompt text from bundle-local prompt files (
systemprompt.md,
boundaries.md).Loads
IntegrationDefinitions from top-level *.json files in a single integrations
directory.Loads workflows from a workflows root directory: each immediate child directory must be named
<workflowId>.workflow and must contain workflow.json.Selects the first provider preference in agent order that is available in the resolver.
Generic, reusable scanner asserting that a configurable set of forbidden terms is absent from a
tree of shipped OSS resource files (workflow definitions, agent bundles, prompts, verification
fixtures, examples).
One forbidden-term hit.
Exposes the running AgentForge4j framework version.
A scripted human response that
WorkflowTestHarness drains
at each human-in-the-loop pause to drive a run forward deterministically.An approval note for an
AWAITING_APPROVAL pause raised by an ESCALATE command.Answers for an
AWAITING_INPUT pause, keyed by artifact item id.A forward-only note for an
AWAITING_REVIEW pause (a HUMAN_REVIEW gate).An approve/reject decision for an
AWAITING_STEP_APPROVAL pause (a HUMAN_APPROVAL
gate).An approve/reject decision for an
AWAITING_TOOL_APPROVAL pause (tool policy
RequireApproval).A continue/retry decision for an
AWAITING_TOOL_DECISION pause (tool policy Deny
or a failed invocation).A file emitted during a run and held transiently in a
GeneratedArtifactStore: the producing stepId,
the requested path, and the emitted content.Run-scoped, transient holder for the bytes a run emits via
CREATE_FILE, so a later deterministic step
(artifact validation) can read the authoritative emitted content in-process — never from disk and never from an
LLM-echoed copy.Return a structured list of questions that the UI should render as an input form.
Health of a
ToolProvider.Provider health state.
Default
OutboundEgressGuard: classifies a target URI as eligible only when its scheme is
http/https and its host resolves entirely to public addresses.Code-defined binding of a logical tool capability to a single HTTP endpoint.
Fluent builder for
HttpEndpointDefinition.HTTP methods an
HttpEndpointDefinition may use.ToolProvider that fulfils logical capabilities with single governed HTTP calls described
by code-defined HttpEndpointDefinitions.Realises
IntegrationType.HTTP_TOOL integrations: builds an HttpToolProvider over the
HttpEndpointDefinitions carried in the config payload (a JSON array, one object per capability).Thread-safe in-memory
AgentRepository whose global snapshot can be replaced atomically.Default
GeneratedArtifactStore retaining emitted bytes in memory, keyed by run.In-memory
MutableIntegrationRepository (OSS default).In-memory
PendingToolInvocationStore (OSS default).In-memory implementation of
WorkflowEventLog.In-memory
WorkflowFileRepository keyed by WorkflowFile.fileId().In-memory
WorkflowRepository whose snapshot can be replaced atomically.In-memory
WorkflowStateRepository backed by a concurrent map keyed by run id.Step that collects user input for the artifact identified by
artifactId before
continuing.Loads
IntegrationDefinitions from an external source (for example JSON definition files).Immutable, transport-agnostic description of one external integration: a single MCP server or a
single HTTP-endpoint set, and whether it is active.
Read access to the configured integrations that feed capability resolution.
Per-type contribution to
ToolProviderFactory: realises integrations of exactly one
IntegrationType as runtime ToolProviders.The single OSS
ToolProviderResolver: it merges two tool sources into one capability index
at construction (tool-load) time —
the active IntegrationDefinitions of an IntegrationRepository, each
materialized into a ToolProvider via a ToolProviderFactory; and
pre-built ToolProvider instances supplied directly — for example configuration-backed
MCP providers supplied by the embedding application, or providers passed to
withToolProviders.
The kind of external integration an
IntegrationDefinition describes.JSON text stored as a context value; treated as opaque JSON until parsed by a consumer.
Neutral context for
RunExecutionInterceptor.beforeLlmCall(LlmCallContext), supplied immediately before each
LLM provider call (after model resolution, before dispatch).Observes each completed LLM call: emits a
WorkflowEventType.LLM_CALL_COMPLETED event and
maintains the ReservedContextKeys.LLM_TOKENS_TOTAL running total in WorkflowState
context.Typed shape of the
WorkflowEventType.LLM_CALL_COMPLETED event payload.Executes LLM requests for a single registered provider (for example OpenAI, Ollama, or Claude).
Settings used to construct an
LlmClient for one provider: provider id, default model, and HTTP connect
timeout.Provider-owned mapping from a provider's
agentforge4j.llm.<providerId>.* configuration subtree to a neutral
LlmClientConfiguration.Factory for creating
LlmClient instances for one provider.Inputs passed to
LlmClientFactory.create(LlmClientFactoryContext): the JSON mapper, the neutral provider
LlmClientConfiguration, and the LlmSecretResolver a provider uses to resolve its credential
reference.Resolves a provider id string to the configured
LlmClient.Marker interface for commands that LLMs can return in structured JSON responses.
Raised when the LLM output cannot be parsed as a JSON array of
LlmCommand.Parses raw LLM output text into a list of
LlmCommands, validating each command's type
against the agent's CommandResponseSchema and required fields before binding.Single source of truth for LLM command type names: mirrors
LlmCommand's
JsonSubTypes declaration order.Immutable parameters for a single LLM invocation.
Shared validation for
LlmExecutionRequest across HTTP and non-HTTP clients.Result of a single
LlmClient invocation.Thrown when an LLM request fails due to network issues, HTTP errors, invalid responses, or provider-specific
validation failures.
Optional run/workflow/step/agent identity for a single LLM invocation.
Immutable configuration for a single LLM provider, used by
AgentForge4jBootstrap.Builder.withLlmProvider(LlmProviderConfig).Builder for
LlmProviderConfig.Thrown for provider configuration-time failures: an unknown provider, a missing or invalid provider option, an
unresolvable credential reference, or a duplicate provider contributor.
Validated, provider-specific configuration transport for the LLM SPI.
Selects which
ProviderPreference to use for an initial LLM invocation.Immutable retry settings for a retrying LLM client: attempt cap, decorrelated jitter bounds, and
optional total elapsed budget.
A resolved LLM provider credential.
An opaque reference to an LLM provider credential, carried through neutral provider configuration so a raw credential
value never has to travel through the wiring layer.
Resolves an
LlmSecretReference to a live LlmSecret at the point of use.Immutable snapshot of loaded agents and workflows.
FileSink that writes under baseDir, namespacing paths by runId and
rejecting paths that escape the base directory.Loop driver settings for blueprint expansion: how iterations end, optional evaluator or for-each
key, and iteration cap.
The read-only view of a run a
LoopEvaluator needs to decide whether an
LoopTerminationStrategy.EVALUATOR loop should
terminate.Evaluates whether an
LoopTerminationStrategy.EVALUATOR loop should
terminate after the current iteration.How a blueprint loop decides each iteration has finished and whether another iteration should
run.
Action taken when a loop reaches
LoopConfig.maxIterations() without terminating by
strategy.How the concrete model for an LLM call was determined, recorded as audit metadata on
AgentInvocationResult and the LLM_CALL_COMPLETED event.Capability tier an agent or step declares instead of a concrete, versioned model string.
Thrown when a declared
ModelTier cannot be resolved to a concrete model string for the
selected provider — that is, no mapping exists after shipped defaults and any operator
overrides have been applied.Resolves a declared
ModelTier to a concrete, versioned model string for a given
provider.Checkbox or multi-select choice field accepting zero or more selected values.
An
IntegrationRepository that also supports administrative writes (add/replace, toggle
active, remove).Small builder for the canonical dotted provider-option map emitted by
LlmClientConfigurationAdapter
implementations.Canonical
FileSink that accepts writes but performs no I/O.Numeric input field.
Numeric-typed context value.
Counter key for the per-sequence ordinal, held inside the per-run store (never on the client).
Classifies whether a target URL is an eligible outbound destination, as a defence against server-side request forgery
(SSRF) on tool-driven HTTP.
A tool invocation suspended awaiting human approval, persisted by
PendingToolInvocationStore.Discriminates why an invocation is suspended pending an operator decision, so a resume attempt
can be checked against the reason it suspended in the first place.
Run-scoped store of
PendingToolInvocations awaiting approval.A
ToolPolicy decision for a requested tool invocation.Allow the invocation to proceed.
Reject the invocation outright.
Suspend the invocation for human approval.
Byte offsets marking the end of each prompt layer in an assembled provider request body.
Loads UTF-8 prompt text files from a base directory.
Represents a preference for an LLM provider and optional model.
Provider-scoped lookup of a single raw property value, backing
RawProviderConfiguration.Deserializes an arbitrary JSON value into its compact raw-JSON
String form.Immutable neutral view over a provider's
agentforge4j.llm.<providerId>.* configuration subtree, handed to a
LlmClientConfigurationAdapter.A single reachable step occurrence in a workflow graph: the step, its id, and the structural location at which it is
reachable.
Walks the reachable step graph of a workflow, exactly as the runtime resolves a step id at a gate or input-submission
point.
Neutral continue/narrow/stop recommendation an execution estimate offers to a human (or a calling
workflow).
The read face of a
FakeRunLifecycle: resolves responses against scripts explicitly registered per run.Whether a closed collection gate may be reopened.
Whether and by whom an existing collection item may be replaced with a new version.
ArtifactValidator that performs no format-specific parsing: it asserts every artifact the selecting
VALIDATE step captured carries non-blank content.ArtifactValidatorFactory for the built-in required-artifacts-present validator, discovered via
ServiceLoader.Thrown when a required
WorkflowRequirement cannot be resolved — no
value is supplied by the configured RequirementResolver and no
default is declared.Resolves a declared
WorkflowRequirement to its opaque value for a given context.The target granularity of a
WorkflowRequirement.Reserved context key constants written by the runtime.
Opaque inputs handed to a
RequirementResolver when resolving a WorkflowRequirement.When a
WorkflowRequirement is expected to be resolved.A capability resolved to the provider that fulfils it together with its descriptor.
Step that loads content from
resourcePath into workflow context under
contextKey.The HTTP status codes that both the HTTP tool provider and the LLM retry client treat as
transient and safe to retry:
429 (Too Many Requests) and the 5xx statuses that
typically indicate a temporary upstream problem rather than a permanent request error.Wraps an LLM client with retry logic for transient failures (decorrelated jitter backoff).
Wraps an LLM client resolver with retrying clients (cached per normalized provider id).
Scope of execution retried when
RetryPreviousBehaviour is used.Flags and limits controlling whether a failed step may be retried, and what variations are
allowed.
Retries prior execution according to
RetryMode, up to maxAttempts, optionally
delegating to fallback.A neutral, structural risk signal contributing to an execution estimate's uncertainty.
Request execution of a shell command.
Opens a correlation scope for a drive or step so callers can attach run metadata (for example
MDC) without the runtime depending on a logging API.
Resource scope tied to a run or step; ends correlation when closed.
Neutral context for
RunExecutionInterceptor.beforeMainExecution(RunExecutionContext), supplied once when a
run first enters main execution.Control SPI for intercepting a run's execution at two pre-execution points: once before a run enters main execution,
and immediately before each LLM call.
Failure details attached to
WorkflowState when a run ends unsuccessfully.Failure caused by an exception or runtime error with a support correlation id.
Failure caused by a human rejecting a
HUMAN_APPROVAL step gate (no send-back).Accessor for the JSON-schema that defines the catalog scenario
expected-result.json
contract (the workflow to drive, the ordered human gate responses, and the assertions to project
onto a run).Loads a scenario's fake-llm script into a
FakeScript from a JSON string, a filesystem
path, or a classpath resource.Provides JSON schema documents used to validate AgentForge4j definition files.
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.Resolves a secret-reference key to its secret value at the point of use.
Secure-by-default OSS
ToolPolicy: allows in-process tools (the embedder's own registered code) and denies
remote-network and local-process tools, which require an explicit trust decision (ToolPolicy.allowAll() or a
custom policy).ToolProviderFactory that routes each IntegrationDefinition to the
IntegrationToolProviderFactory contribution matching its IntegrationType.Write a typed value into the shared workflow context under the given key.
Abstraction over the
RunCommandCommand side effect.The shipped OSS default mapping of
ModelTier to a concrete, versioned model string for
each of the nine built-in providers.Dropdown or radio button choice field accepting a single selected value.
Per-unit sizing magnitudes for the genuinely dynamic parts of an estimate — the figures the
execution-estimator agent produces over a structural summary and the host reads back to
feed WorkflowExecutionAggregator.Step that runs an adversarial exchange between the primary agent and a challenger before
continuing.
Configuration for a spar (adversarial) step: challenger identity, round cap, and prompt used to
resolve the debate.
Standard
LlmClientConfiguration shape shared by every provider's LlmClientConfigurationAdapter.A
FakeResponseSource backed by a single, run-agnostic FakeScript: every run is served the same
script.A human decision for a step suspended in
WorkflowStatus.AWAITING_STEP_APPROVAL by a
StepTransition.HUMAN_APPROVAL gate.Approve the step and advance the run.
Reject the step and fail the run.
Polymorphic model of how a
StepDefinition executes,
discriminated in JSON by type.One executable step in a workflow: identity, behaviour, optional context mapping, and prompt
text.
Fluent builder for
StepDefinition.Raised when a step fails during execution.
Thrown when a step with the given id is not found in the workflow definition.
Human gate applied after a step completes before the next step may run.
String-typed context value.
Supplies the constant, framework-authored system rules instructing the model to treat content under the
untrusted-input envelope — and, separately, content between the untrusted tool-metadata markers — as data, not
instructions.
Multi-line text input field.
Single-line text input field.
Token usage reported by an LLM provider for a single invocation.
Read-only aggregate view of available tools.
An operator's decision for a tool invocation suspended in
WorkflowStatus.AWAITING_TOOL_DECISION after policy denied it or it
failed (after retries).Proceed without the tool result; the runtime writes
tool.<capability>.error to context and advances the
run.Replay the exact stored call (re-resolve, re-validate, invoke) without re-invoking the LLM.
Logical, transport-agnostic description of a tool the runtime can invoke.
Tunables for tool invocation.
Lifecycle status of a tool invocation.
The single chokepoint for tool invocation: resolve, validate, evaluate policy, then invoke under
an authoritative timeout.
Thrown by
ToolExecutionService.resume(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.ApprovalDecision) when the pending invocation observed at the start
of the call no longer matches the row an atomic PendingToolInvocationStore.claim(java.lang.String, java.lang.String, com.agentforge4j.core.spi.tool.PendingToolInvocation) attempt
finds — a concurrent resume call already claimed it, or replaced it with a different
pending row, between this call's peek and its own claim attempt.Request from the LLM to invoke a logical tool capability.
Dispatches a
ToolInvocationCommand through the ToolExecutionService chokepoint.Identity propagated through a single tool invocation, matching the existing command pipeline.
Policy gate for tool invocation.
A source of invocable tools, for example an MCP server.
Creates the runtime
ToolProvider for an IntegrationDefinition, interpreting its
IntegrationDefinition.type() and config.Framework-supplied collaborators threaded into every
IntegrationToolProviderFactory.create(com.agentforge4j.core.spi.integration.IntegrationDefinition, com.agentforge4j.core.spi.integration.ToolProviderFactoryContext) call by the
aggregating ToolProviderFactory.The sole resolver of a logical capability to the provider that fulfils it.
Outcome of a single provider invocation.
The single routine that applies a successful
ToolResult to WorkflowState, used
identically by the inline ALLOW path (ToolInvocationCommandHandler) and the
approved-resume path (DefaultWorkflowRuntime#continueAfterToolApproval) so both produce
the same state shape.Realised risk signal for a tool the runtime can invoke, carried by every
ToolDescriptor.OSS-clean execution scope identifying the workflow and run a tool invocation belongs to.
Separates a logical capability from the physical remote tool that fulfils it.
Structural classification of where a tool physically executes.
Implemented by step behaviours that carry a post-completion
StepTransition gate.Thrown when loaded workflows reference agent ids that are not present in the merged agent
catalog.
The reserved root key under which a rendered prompt isolates untrusted (user- or external-tool-
supplied) context entries.
The reserved delimiter markers that isolate externally-supplied tool metadata (capability names,
descriptions, input schemas) within the assembled system prompt.
Surface a message to the user.
Provides static methods for validating arguments and paths.
Deterministic, in-workflow validation of the artifacts a prior step emitted via
CREATE_FILE and captured in
the run-scoped generated-artifact store.Single ordered registry of the named workflow-validation checks, shared by every validation entry
point so the suite of checks cannot drift between them.
Single validation failure item produced by draft validation.
Aggregate result returned by workflow draft validation.
Outcome of an
ArtifactValidator: either valid, or invalid with a non-blank reason.Whether and by whom an existing collection item may be withdrawn.
Collects
agentRef usages from a workflow tree, including blueprint refs, branch targets,
and nested workflows, each tagged with the enclosing workflow id for validation diagnostics.Records a reference to an agent id within a workflow, including the context for validation.
Step that runs a nested workflow by reference.
Immutable context for a single workflow bundle loading invocation.
Resolves shipped workflow bundle resources from the classpath.
Collects the union of
requiredArtifacts declared by every VALIDATE step reachable within a single
WorkflowDefinition — descending through branch targets, predicate targets, blueprint bodies, and inline
nested definitions, but not through workflowRef/WorkflowBehaviour boundaries.Deterministic structural analysis of a single
WorkflowDefinition, produced by
WorkflowComplexityAnalyzer.Deterministic structural analysis of a single
WorkflowDefinition for execution estimation.Defines a workflow: its steps, blueprints, and artifacts.
Fluent builder for
WorkflowDefinition.Result of loading a workflows directory or shipped workflow bundles: workflow definitions plus
agents discovered under each workflow's
agents/ tree (merged into a single map by id).Loads workflow bundles from an explicit filesystem root.
Runs non-throwing workflow draft validation and collects failures into a report.
Immutable audit entry for a workflow run: identity, classification, optional payload, actor, and timestamp.
Append-only store of
WorkflowEvent records keyed by run id.Classification of
WorkflowEvent entries written during workflow execution.Combines a deterministic
WorkflowComplexityAnalysis with the LLM-produced per-turn
SizingInputs to yield the final ExecutionEstimate: the min / expected / max token
envelope, the sized turn and tool figures, the confidence grade, the risk flags, and the
continue/narrow/stop recommendation.Facade over the deterministic estimation building blocks — the Java-shaped concerns a host owns
when driving an estimation-style workflow: turning a target definition into a structural summary
before the run, and, for a custom (non-catalog) workflow that does not use the
AGGREGATE
step behaviour, aggregating the sized figures after it.Built-in
ContextAggregator wrapping WorkflowExecutionAggregator.aggregate(com.agentforge4j.core.workflow.estimate.WorkflowComplexityAnalysis, com.agentforge4j.core.workflow.estimate.SizingInputs) for
in-workflow use by the workflow-execution-estimator catalog bundle's AGGREGATE
step.Metadata and addressing for a file produced or consumed during a workflow run.
Persistence for
WorkflowFile metadata and content addressing.Tracks the maturity state of a workflow definition.
Loads workflow definitions from a backing source.
Thrown when a workflow with the given id is not found in the workflow repository.
Resolves a
WORKFLOW behaviour's workflowRef to its definition while walking the reachable workflow
graph.Catalog of
WorkflowDefinition instances keyed by workflow id.A central, self-targeting declaration of something a workflow needs satisfied.
Fluent, framework-agnostic assertions over a
WorkflowRunResult.The outcome of one harnessed run: the run id, a defensive snapshot of the final
WorkflowState, and the CaptureBundle of observed effects.The runtime command model for workflow execution.
Fluent builder that wires a
DefaultWorkflowRuntime with the canonical executor graph, behaviour handlers,
loop strategies, and command handlers.The workflow schema version this framework build understands.
Indicates the origin of a workflow definition.
Mutable execution snapshot for one run: identity, status, pending gates, context maps, and
failure details.
Repository for internal runtime state.
High-level lifecycle state of a workflow run persisted in
WorkflowState.The bootstrap-facing harness adapter: assembles an AgentForge4j runtime with the deterministic
fake LLM provider active, runs a workflow, and returns a
WorkflowRunResult holding the
final state plus the captured event stream and files.Fluent builder for
WorkflowTestHarness.Shared structural traversal of a
WorkflowDefinition tree, used by the per-concern collectors in this package
(agent-ref discovery, capture-path collection) and by agentforge4j-config-loader's workflow validation, so
the walking logic exists in exactly one place.Structural and cross-reference validation checks run against loaded workflow and agent
definitions.