Obtain this service through {@code ExtensionGetter.getEnabledExtension(AiToolService.class)}. Tool selections use
+ * the catalog {@link ToolDescriptor#id()}, not the model-facing name. No tools are selected implicitly. The caller
+ * remains responsible for its own access policy and must pass trusted caller identity through the reactive subscriber
+ * context; a provider must check any domain-specific permissions before performing an operation.
+ *
+ *
+ */
+public interface AiToolService extends ExtensionPoint {
+
+ /**
+ * Lists tools contributed by enabled, valid providers, including globally disabled or unconfigured tools so
+ * administrators can manage their state and configuration.
+ *
+ * @return serializable metadata without executors or secret values
+ */
+ Flux listTools();
+
+ /**
+ * Resolves an explicit selection, preserving selection order, for a generation request.
+ *
+ *
Empty or null selections resolve to no tools. Blank, duplicate, unavailable, globally disabled, or
+ * unconfigured IDs fail with {@link IllegalArgumentException}. Resolve tools for each generation request. Tools
+ * using the default permission policy are excluded when unauthorized; tools opting into execution-time rejection
+ * remain in the result. Selection order is preserved. Execution always rechecks declared permissions, availability,
+ * enabled state, configuration readiness, and approval mode; changed schemas or approval modes require resolving
+ * again. Dynamic predicates and lifecycle callbacks remain request-scoped. Providers must enforce authorization in
+ * the executor independently of approval decisions.
+ *
+ * @param toolIds stable catalog IDs, or {@code null} for no tools
+ * @return request-scoped executable definitions in selection order after permission filtering
+ */
+ Mono> resolveTools(List toolIds);
+
+ /**
+ * Explicitly resolves globally enabled, configured tools according to their permission policies.
+ *
+ *
Unavailable tools and unauthorized tools using resolution-time filtering are excluded. Tools opting into
+ * execution-time rejection remain in the result. Executors retain their authorization, approval and lifecycle
+ * behavior. Consumers should normally prefer an explicit selection when only a subset is needed.
+ *
+ * @return all ready definitions permitted by their declared resolution policies
+ */
+ Mono> resolveAllTools();
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/AiToolProvider.java b/api/src/main/java/run/halo/aifoundation/tool/AiToolProvider.java
new file mode 100644
index 00000000..b9f1e4b7
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/AiToolProvider.java
@@ -0,0 +1,42 @@
+package run.halo.aifoundation.tool;
+
+import org.pf4j.ExtensionPoint;
+import reactor.core.publisher.Flux;
+
+/**
+ * Contributes discoverable server-side tools through the {@code ai-tool-provider} extension point.
+ *
+ *
Each definition must have a stable local name of 1-63 letters, numbers, underscores, or hyphens, an object input
+ * schema, and an executor. The catalog id is {@code pluginId/localName}; the registry derives a globally unique
+ * model-facing tool name.
+ *
+ *
Return a finite stream of tool registrations and complete promptly without side effects. Declare resource
+ * permissions on {@link ToolRegistration}; executors remain responsible for domain restrictions such as ownership,
+ * using trusted request or reactive security context.
+ *
+ *
A plugin may expose multiple provider beans, for example one per business domain. Their tool names share the
+ * plugin's namespace and must remain unique. Group presets may reference tools from another provider in that same
+ * plugin.
+ *
+ *
+ */
+public interface AiToolProvider extends ExtensionPoint {
+
+ /**
+ * Supplies this provider's complete, finite set of tool registrations.
+ *
+ *
Build descriptions and schemas here; perform actual external requests and mutations in the registered
+ * executor. Provider errors make that provider unavailable for discovery.
+ *
+ * @return registrations followed by completion, never {@code null}
+ */
+ Flux tools();
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPolicy.java b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPolicy.java
index da974227..f41e0e08 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPolicy.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPolicy.java
@@ -6,7 +6,17 @@
import lombok.Data;
import lombok.NoArgsConstructor;
-/** Provider-neutral approval policy for a request-scoped tool. */
+/**
+ * Provider-neutral approval policy for a request-scoped tool.
+ *
+ *
Approval is evaluated after input validation. It asks the caller to confirm an operation; it does not grant Halo
+ * permissions. Choose a constant policy or a predicate based on validated arguments, for example:
+ *
+ *
+ */
@Data
@Builder
@NoArgsConstructor
@@ -19,7 +29,7 @@ public enum Mode {
NEVER,
/** Always require approval before executor invocation. */
ALWAYS,
- /** Use {@link #predicate} to decide from validated call context. */
+ /** Use {@link ToolApprovalPolicy#predicate} to decide from validated call context. */
DYNAMIC
}
@@ -28,14 +38,31 @@ public enum Mode {
/** Dynamic approval predicate. Java-only and intentionally not serialized. */
private transient ToolApprovalPredicate predicate;
+ /**
+ * Creates a policy that executes without requesting confirmation.
+ *
+ * @return a policy using {@link Mode#NEVER}
+ */
public static ToolApprovalPolicy never() {
return ToolApprovalPolicy.builder().mode(Mode.NEVER).build();
}
+ /**
+ * Creates a policy that requests confirmation for every validated call.
+ *
+ * @return a policy using {@link Mode#ALWAYS}
+ */
public static ToolApprovalPolicy always() {
return ToolApprovalPolicy.builder().mode(Mode.ALWAYS).build();
}
+ /**
+ * Creates a policy that evaluates validated arguments before requesting confirmation.
+ *
+ * @param predicate decision callback, never {@code null}
+ * @return a policy using {@link Mode#DYNAMIC}
+ * @throws IllegalArgumentException if the predicate is {@code null}
+ */
public static ToolApprovalPolicy dynamic(ToolApprovalPredicate predicate) {
if (predicate == null) {
throw new IllegalArgumentException("tool approval predicate must not be null");
@@ -46,6 +73,13 @@ public static ToolApprovalPolicy dynamic(ToolApprovalPredicate predicate) {
.build();
}
+ /**
+ * Evaluates this policy for the current validated tool call.
+ *
+ * @param context current execution arguments and request metadata
+ * @return whether the caller must approve execution
+ * @throws IllegalArgumentException if a dynamic policy has no predicate
+ */
public boolean requiresApproval(ToolExecutionContext context) {
var effectiveMode = mode != null ? mode : Mode.NEVER;
return switch (effectiveMode) {
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPredicate.java b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPredicate.java
index 2a233775..c7182ce7 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPredicate.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalPredicate.java
@@ -1,12 +1,21 @@
package run.halo.aifoundation.tool;
-/** Decides whether a validated tool call requires explicit approval before execution. */
+/**
+ * Decides whether a validated tool call requires explicit approval before execution.
+ *
+ *
Return a decision from the supplied arguments without performing the requested operation. For example,
+ * {@code context -> Boolean.TRUE.equals(context.getInput().get("publish"))} requires confirmation only for publishing.
+ * Resource authorization still runs separately.
+ */
@FunctionalInterface
public interface ToolApprovalPredicate {
/**
* Returns {@code true} when the tool call should be returned as an approval request instead of executed
* immediately.
+ *
+ * @param context validated arguments and trusted request metadata
+ * @return whether confirmation is required
*/
boolean needsApproval(ToolExecutionContext context);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalRequest.java b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalRequest.java
index 44626ab4..cdd51f67 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalRequest.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalRequest.java
@@ -6,7 +6,12 @@
import lombok.Data;
import lombok.NoArgsConstructor;
-/** A pending approval request for a model-produced tool call. */
+/**
+ * A pending approval request for a model-produced tool call.
+ *
+ *
Show the validated input to the caller and correlate the decision using {@link #approvalId}. Continue with a
+ * matching {@link ToolApprovalResponse}; an approval decision does not replace the tool's resource permission checks.
+ */
@Data
@Builder
@NoArgsConstructor
@@ -25,6 +30,15 @@ public class ToolApprovalRequest {
/** Provider or Halo metadata associated with the request. */
private Map providerMetadata;
+ /**
+ * Creates an approval request correlated with an existing model call.
+ *
+ * @param toolCall validated call awaiting approval
+ * @param approvalId identity used by the later approval response
+ * @param stepIndex generation step that produced the call
+ * @param providerMetadata optional provider or Halo metadata
+ * @return request containing the original call identity and input
+ */
public static ToolApprovalRequest from(
ToolCall toolCall, String approvalId, Integer stepIndex, Map providerMetadata) {
return ToolApprovalRequest.builder()
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalResponse.java b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalResponse.java
index c50db988..1774fce5 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalResponse.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolApprovalResponse.java
@@ -6,7 +6,21 @@
import lombok.Data;
import lombok.NoArgsConstructor;
-/** Caller-supplied response to a pending tool approval request. */
+/**
+ * Caller-supplied response to a pending tool approval request.
+ *
+ *
Copy the pending request's approval identity and explicitly approve or reject it. Rejections may include a reason
+ * for the model; they must not include credentials or other sensitive values.
+ *
+ *
{@code
+ * ToolApprovalResponse response = ToolApprovalResponse.builder()
+ * .approvalId(pending.getApprovalId())
+ * .toolCallId(pending.getToolCallId())
+ * .approved(false)
+ * .reason("Keep this article as a draft")
+ * .build();
+ * }
+ */
@Data
@Builder
@NoArgsConstructor
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairCallback.java b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairCallback.java
index 193eeaa0..3e1d6d28 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairCallback.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairCallback.java
@@ -12,5 +12,11 @@
@FunctionalInterface
public interface ToolCallRepairCallback {
+ /**
+ * Proposes corrected arguments for a known tool whose input failed parsing or validation.
+ *
+ * @param context original call, matching definition, and validation details
+ * @return a corrected call or {@link ToolCallRepairResult#unrepaired()}
+ */
Mono repair(ToolCallRepairContext context);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairContext.java b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairContext.java
index 518f54dd..0581efde 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairContext.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairContext.java
@@ -8,7 +8,14 @@
import lombok.NoArgsConstructor;
import run.halo.aifoundation.message.ModelMessage;
-/** Provider-neutral context passed to a tool call repair callback. */
+/**
+ * Provider-neutral context passed to a tool call repair callback.
+ *
+ *
Inspect {@link #validationError} and {@link #validationPath} against the matching tool schema, then return a
+ * repaired call or leave the failure unchanged. Preserve the original tool name and call identity. For example, a
+ * callback can normalize a numeric string to the integer required by the input schema before returning
+ * {@link ToolCallRepairResult#repaired(ToolCall)}.
+ */
@Data
@Builder
@NoArgsConstructor
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairResult.java b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairResult.java
index 023eeaf0..32e7eee4 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairResult.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolCallRepairResult.java
@@ -5,7 +5,13 @@
import lombok.Data;
import lombok.NoArgsConstructor;
-/** Result returned by {@link ToolCallRepairCallback}. */
+/**
+ * Result returned by {@link ToolCallRepairCallback}.
+ *
+ *
Use {@link #repaired(ToolCall)} after correcting the original call's arguments, or {@link #unrepaired()} when no
+ * safe correction is possible. The runtime validates repaired input again before approval or execution; returning a
+ * repair does not bypass the input schema.
+ */
@Data
@Builder
@NoArgsConstructor
@@ -14,10 +20,21 @@ public class ToolCallRepairResult {
/** Repaired tool call. Leave empty to keep the original validation failure. */
private ToolCall toolCall;
+ /**
+ * Returns a call whose corrected arguments should be validated again.
+ *
+ * @param toolCall corrected call preserving the original identity
+ * @return repair proposal
+ */
public static ToolCallRepairResult repaired(ToolCall toolCall) {
return ToolCallRepairResult.builder().toolCall(toolCall).build();
}
+ /**
+ * Keeps the original parsing or validation failure.
+ *
+ * @return result without a replacement call
+ */
public static ToolCallRepairResult unrepaired() {
return ToolCallRepairResult.builder().build();
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolChoice.java b/api/src/main/java/run/halo/aifoundation/tool/ToolChoice.java
index 9331f6d5..290fbd11 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolChoice.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolChoice.java
@@ -34,22 +34,39 @@ public enum Type {
/** Required when {@link #type} is {@link Type#TOOL}; ignored for other modes. */
private String toolName;
- /** Creates an automatic tool choice. */
+ /**
+ * Creates an automatic tool choice.
+ *
+ * @return a choice allowing the model to decide whether a tool is useful
+ */
public static ToolChoice auto() {
return ToolChoice.builder().type(Type.AUTO).build();
}
- /** Creates a choice that disables tool calling for this request. */
+ /**
+ * Creates a choice that disables tool calling for this request.
+ *
+ * @return a choice using {@link Type#NONE}
+ */
public static ToolChoice none() {
return ToolChoice.builder().type(Type.NONE).build();
}
- /** Creates a choice that requires the model to call one of the provided tools. */
+ /**
+ * Creates a choice that requires the model to call one of the provided tools.
+ *
+ * @return a choice using {@link Type#REQUIRED}
+ */
public static ToolChoice required() {
return ToolChoice.builder().type(Type.REQUIRED).build();
}
- /** Creates a choice for a specific tool. */
+ /**
+ * Creates a choice for a specific tool.
+ *
+ * @param toolName model-facing name from the request's tool definitions, not a catalog ID
+ * @return a choice targeting the named request tool
+ */
public static ToolChoice tool(String toolName) {
return ToolChoice.builder().type(Type.TOOL).toolName(toolName).build();
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolConfiguration.java b/api/src/main/java/run/halo/aifoundation/tool/ToolConfiguration.java
new file mode 100644
index 00000000..10bb6b01
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolConfiguration.java
@@ -0,0 +1,40 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.function.Supplier;
+import lombok.Builder;
+import lombok.Value;
+import reactor.core.publisher.Mono;
+
+/**
+ * Optional provider-owned tool configuration, rendered with the supplied FormKit schema.
+ *
+ *
Values must contain configuration or Secret references, never secret contents. The provider must validate save
+ * requests authoritatively and persist them through its own configuration store. Callbacks are server-side code and are
+ * never included in catalog responses.
+ *
+ *
The schema uses Halo FormKit nodes, not a JSON Schema for model arguments. For example, a provider can expose a
+ * required text setting and keep persistence in its own service:
+ *
+ *
+ */
+@Value
+@Builder
+public class ToolConfiguration {
+ /** FormKit nodes rendered in the tool's settings dialog; must be nonempty when configured. */
+ List> schema;
+ /** Reads current editable values. Return Secret references instead of resolved credentials. */
+ transient Supplier>> values;
+ /** Validates and persists submitted values. A failed publisher leaves the form unsaved. */
+ transient Function, Mono> save;
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolDefinition.java b/api/src/main/java/run/halo/aifoundation/tool/ToolDefinition.java
index 9b7eb6b0..b38024c6 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolDefinition.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolDefinition.java
@@ -72,7 +72,15 @@ public class ToolDefinition {
/** Server-side tool implementation. Return values should be JSON serializable. */
private transient ToolExecutor executor;
- /** Creates a tool definition with typed schema helpers. */
+ /**
+ * Creates a tool definition with typed schema helpers.
+ *
+ * @param name stable model-facing tool name
+ * @param description explanation of when the model should use the tool
+ * @param inputSchema schema describing accepted JSON arguments
+ * @param executor server-side implementation
+ * @return executable tool definition
+ */
public static ToolDefinition of(String name, String description, JsonSchema inputSchema, ToolExecutor executor) {
return ToolDefinition.builder()
.name(name)
@@ -82,51 +90,117 @@ public static ToolDefinition of(String name, String description, JsonSchema inpu
.build();
}
+ /**
+ * Builds a provider-neutral definition using map or typed JSON Schema inputs.
+ *
+ *
For example, {@code inputSchema(JsonSchema.object().build())} declares a tool without arguments. Approval
+ * conveniences configure the same {@link ToolApprovalPolicy} field.
+ */
public static class ToolDefinitionBuilder {
+ /**
+ * Sets the argument schema as a JSON object.
+ *
+ * @param schema JSON Schema map
+ * @return this builder
+ */
public ToolDefinitionBuilder inputSchema(Map schema) {
this.inputSchema = schema;
return this;
}
+ /**
+ * Sets the argument schema using the typed schema API.
+ *
+ * @param schema typed schema, or {@code null} to clear it
+ * @return this builder
+ */
public ToolDefinitionBuilder inputSchema(JsonSchema schema) {
this.inputSchema = schema != null ? schema.toMap() : null;
return this;
}
+ /**
+ * Sets the argument schema from an unfinished typed schema builder.
+ *
+ * @param schema schema builder, or {@code null} to clear it
+ * @return this builder
+ */
public ToolDefinitionBuilder inputSchema(JsonSchema.Builder schema) {
this.inputSchema = schema != null ? schema.toMap() : null;
return this;
}
+ /**
+ * Sets the optional result schema as a JSON object.
+ *
+ * @param schema result JSON Schema map, or {@code null} for no validation
+ * @return this builder
+ */
public ToolDefinitionBuilder outputSchema(Map schema) {
this.outputSchema = schema;
return this;
}
+ /**
+ * Sets the optional result schema using the typed schema API.
+ *
+ * @param schema typed result schema, or {@code null} for no validation
+ * @return this builder
+ */
public ToolDefinitionBuilder outputSchema(JsonSchema schema) {
this.outputSchema = schema != null ? schema.toMap() : null;
return this;
}
+ /**
+ * Sets the optional result schema from a typed schema builder.
+ *
+ * @param schema result schema builder, or {@code null} for no validation
+ * @return this builder
+ */
public ToolDefinitionBuilder outputSchema(JsonSchema.Builder schema) {
this.outputSchema = schema != null ? schema.toMap() : null;
return this;
}
+ /**
+ * Configures a constant approval policy.
+ *
+ * @param requiresApproval whether every validated call requires confirmation
+ * @return this builder
+ */
public ToolDefinitionBuilder requiresApproval(boolean requiresApproval) {
this.approvalPolicy = requiresApproval ? ToolApprovalPolicy.always() : ToolApprovalPolicy.never();
return this;
}
+ /**
+ * Alias for {@link #requiresApproval(boolean)}.
+ *
+ * @param requiresApproval whether every validated call requires confirmation
+ * @return this builder
+ */
public ToolDefinitionBuilder needsApproval(boolean requiresApproval) {
return requiresApproval(requiresApproval);
}
+ /**
+ * Configures confirmation based on validated execution arguments.
+ *
+ * @param predicate dynamic approval decision, never {@code null}
+ * @return this builder
+ */
public ToolDefinitionBuilder approvalPredicate(ToolApprovalPredicate predicate) {
this.approvalPolicy = ToolApprovalPolicy.dynamic(predicate);
return this;
}
+ /**
+ * Alias for {@link #approvalPredicate(ToolApprovalPredicate)}.
+ *
+ * @param predicate dynamic approval decision, never {@code null}
+ * @return this builder
+ */
public ToolDefinitionBuilder needsApproval(ToolApprovalPredicate predicate) {
return approvalPredicate(predicate);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolDescriptor.java b/api/src/main/java/run/halo/aifoundation/tool/ToolDescriptor.java
new file mode 100644
index 00000000..acb4dcef
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolDescriptor.java
@@ -0,0 +1,124 @@
+package run.halo.aifoundation.tool;
+
+import java.math.BigDecimal;
+import java.math.BigInteger;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Serializable catalog metadata. Executors, approval policies, and lifecycle callbacks are never exposed by discovery.
+ * {@code id} is the stable selection value; {@code name} is for the model.
+ *
+ *
For example, a selector persists {@code article-tools/list_posts} from {@link #id()}, then passes it to
+ * {@link run.halo.aifoundation.AiToolService#resolveTools(List)}. It uses display fields for presentation and
+ * {@link #enabled()}, {@link #configured()}, and {@link #status()} to explain why a catalog entry cannot currently be
+ * selected. Schemas and lists are immutable snapshots.
+ *
+ * @param id stable {@code pluginId/localName} selection identity
+ * @param pluginName owning plugin identity
+ * @param localName provider-local definition name
+ * @param name unique model-facing name assigned by the registry
+ * @param displayName administrator-facing title
+ * @param description model-facing description
+ * @param displayDescription administrator-facing explanation
+ * @param category shared catalog category
+ * @param inputSchema JSON Schema for model-generated arguments
+ * @param outputSchema optional JSON Schema for execution results
+ * @param tags searchable presentation labels
+ * @param configurationSchema optional FormKit nodes for the settings dialog
+ * @param enabled whether an administrator permits use of this tool
+ * @param configured whether required provider settings are ready
+ * @param status derived state; constructor input is replaced from enabled and configured flags
+ * @param group optional group metadata
+ */
+public record ToolDescriptor(
+ String id,
+ String pluginName,
+ String localName,
+ String name,
+ String displayName,
+ String description,
+ String displayDescription,
+ String category,
+ Map inputSchema,
+ Map outputSchema,
+ List tags,
+ List> configurationSchema,
+ boolean enabled,
+ boolean configured,
+ String status,
+ ToolGroupDescriptor group) {
+ /**
+ * Validates catalog identities, snapshots JSON metadata, and derives the displayed status.
+ *
+ * @throws IllegalArgumentException if schemas contain unsupported JSON values or nesting
+ * @throws NullPointerException if an identity or the input schema is {@code null}
+ */
+ public ToolDescriptor {
+ Objects.requireNonNull(id, "id must not be null");
+ Objects.requireNonNull(pluginName, "pluginName must not be null");
+ Objects.requireNonNull(localName, "localName must not be null");
+ Objects.requireNonNull(name, "name must not be null");
+ Objects.requireNonNull(inputSchema, "inputSchema must not be null");
+ inputSchema = copyObject(inputSchema, 0);
+ outputSchema = outputSchema != null ? copyObject(outputSchema, 0) : null;
+ tags = tags == null ? List.of() : List.copyOf(tags);
+ configurationSchema = configurationSchema == null
+ ? List.of()
+ : configurationSchema.stream()
+ .map(schema -> copyObject(schema, 0))
+ .toList();
+ status = !enabled ? "DISABLED" : configured ? "ENABLED" : "UNCONFIGURED";
+ }
+
+ private static Map copyObject(Map value, int depth) {
+ var copy = new LinkedHashMap();
+ value.forEach((key, child) -> {
+ if (!(key instanceof String text)) {
+ throw new IllegalArgumentException("JSON object keys must be strings");
+ }
+ copy.put(text, copyJson(child, depth + 1));
+ });
+ return Collections.unmodifiableMap(copy);
+ }
+
+ private static Object copyJson(Object value, int depth) {
+ if (depth > 64) {
+ throw new IllegalArgumentException("Tool schema exceeds the maximum nesting depth");
+ }
+ if (value instanceof Map map) {
+ return copyObject(map, depth);
+ }
+ if (value instanceof List list) {
+ var copy = new ArrayList<>();
+ list.forEach(child -> copy.add(copyJson(child, depth + 1)));
+ return Collections.unmodifiableList(copy);
+ }
+ if (isJsonScalar(value)) {
+ return value;
+ }
+ throw new IllegalArgumentException("Tool schemas must contain only JSON values");
+ }
+
+ private static boolean isJsonScalar(Object value) {
+ if (value == null || value instanceof String || value instanceof Boolean) {
+ return true;
+ }
+ if (value instanceof Double number) {
+ return Double.isFinite(number);
+ }
+ if (value instanceof Float number) {
+ return Float.isFinite(number);
+ }
+ return value instanceof Byte
+ || value instanceof Short
+ || value instanceof Integer
+ || value instanceof Long
+ || value instanceof BigInteger
+ || value instanceof BigDecimal;
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolExecutionContext.java b/api/src/main/java/run/halo/aifoundation/tool/ToolExecutionContext.java
index 434df0a4..fd4ac122 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolExecutionContext.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolExecutionContext.java
@@ -14,6 +14,15 @@
*
*
The context includes the parsed input and enough call metadata to correlate tool execution with stream events and
* persisted conversation history.
+ *
+ *
Read model-generated arguments from {@link #input}. Request context is caller-supplied application data and is not
+ * inserted into prompts; only values established by trusted server code should be used for authorization. Check
+ * {@link #cancellationToken} during lengthy work.
+ *
+ *
*/
@Value
public class ToolExecutionContext {
@@ -34,6 +43,18 @@ public class ToolExecutionContext {
/** Request-scoped cooperative cancellation signal, when the caller supplied one. */
private CancellationToken cancellationToken;
+ /**
+ * Creates an execution snapshot, replacing absent maps and messages with empty collections.
+ *
+ * @param toolCallId original model call identity
+ * @param toolName model-facing tool name
+ * @param input validated JSON arguments
+ * @param stepIndex zero-based model invocation step
+ * @param messages messages used for this step
+ * @param providerMetadata provider or Halo metadata
+ * @param requestContext caller application context, excluded from prompts
+ * @param cancellationToken optional cooperative cancellation signal
+ */
@Builder
public ToolExecutionContext(
String toolCallId,
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolGroup.java b/api/src/main/java/run/halo/aifoundation/tool/ToolGroup.java
new file mode 100644
index 00000000..10d23e0a
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolGroup.java
@@ -0,0 +1,53 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Groups related tool registrations from one provider plugin for catalog and selector display.
+ *
+ *
Assign the same group metadata to every member registration. A group does not create a model-facing tool or
+ * combine executors; selected leaf tools retain their own schemas and permissions. Presets offer convenient selections
+ * of those leaves.
+ *
+ *
+ */
+@Value
+public class ToolGroup {
+ /** Stable provider-local group name, using the same naming rules as a local tool name. */
+ String name;
+ /** Administrator-facing title, falling back to {@link #name} when blank. */
+ String displayName;
+ /** Optional explanation of the operations collected in this group. */
+ String description;
+ /** Named selections containing tools from this group only. */
+ List presets;
+
+ /**
+ * Creates a group and snapshots its preset list.
+ *
+ * @param name stable provider-local group name
+ * @param displayName administrator-facing title
+ * @param description optional group explanation
+ * @param presets named selections, or {@code null} for none
+ */
+ @Builder
+ public ToolGroup(String name, String displayName, String description, List presets) {
+ this.name = name;
+ this.displayName = displayName;
+ this.description = description;
+ this.presets = presets == null ? List.of() : List.copyOf(presets);
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolGroupDescriptor.java b/api/src/main/java/run/halo/aifoundation/tool/ToolGroupDescriptor.java
new file mode 100644
index 00000000..c4baffe9
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolGroupDescriptor.java
@@ -0,0 +1,29 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Serializable group metadata with a catalog identity assigned by the owning plugin.
+ *
+ *
For example, plugin {@code article-tools} and local group {@code articles} produce ID
+ * {@code article-tools/articles}. Consumers can group tool descriptors by this ID and render the attached presets
+ * without constructing provider-local names themselves.
+ *
+ * @param id stable {@code pluginId/groupName} identity
+ * @param displayName administrator-facing title
+ * @param description optional group explanation
+ * @param presets named leaf selections with catalog IDs
+ */
+public record ToolGroupDescriptor(
+ String id, String displayName, String description, List presets) {
+ /**
+ * Validates the identity and snapshots the preset list.
+ *
+ * @throws NullPointerException if {@code id} is {@code null}
+ */
+ public ToolGroupDescriptor {
+ Objects.requireNonNull(id, "id must not be null");
+ presets = presets == null ? List.of() : List.copyOf(presets);
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableCallback.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableCallback.java
index f5a15d2a..56eae4d4 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableCallback.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableCallback.java
@@ -5,9 +5,19 @@
/**
* Backpressured callback invoked after normalized tool input becomes available and before any approval, external
* handoff, or server-side execution.
+ *
+ *
Complete the returned publisher before processing continues. Failures stop generation; callbacks should observe or
+ * prepare input without performing the requested tool operation. For example, an audit callback can persist the call
+ * identity through a reactive service and return its completion signal.
*/
@FunctionalInterface
public interface ToolInputAvailableCallback {
+ /**
+ * Processes this request-scoped input event.
+ *
+ * @param context immutable event arguments and request metadata
+ * @return completion signal; an error stops generation
+ */
Mono onInputAvailable(ToolInputAvailableContext context);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableContext.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableContext.java
index 0110116a..589d2fa2 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableContext.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputAvailableContext.java
@@ -7,18 +7,44 @@
import run.halo.aifoundation.control.CancellationToken;
import run.halo.aifoundation.message.ModelMessage;
-/** Immutable provider-neutral snapshot for normalized tool input availability. */
+/**
+ * Immutable provider-neutral snapshot for normalized tool input availability.
+ *
+ *
The runtime supplies this snapshot after parsing and validation, before approval or execution. Maps and message
+ * lists cannot be modified through this context. Use the tool call identity to correlate observations across callbacks,
+ * and honor the optional cancellation signal during asynchronous work.
+ */
@Value
public class ToolInputAvailableContext {
+ /** Original model tool call identity, used to correlate later input and result events. */
String toolCallId;
+ /** Model-facing name of the tool whose input is being processed. */
String toolName;
+ /** Validated parsed JSON arguments available to approval and execution. */
Map input;
+ /** Zero-based model invocation step that produced this callback. */
Integer stepIndex;
+ /** Immutable list of provider-neutral messages used for this generation step. */
List messages;
+ /** Caller application context, excluded from model prompts. */
Map requestContext;
+ /** Provider or Halo metadata associated with this call and step. */
Map providerMetadata;
+ /** Optional cooperative cancellation signal for request-scoped work. */
CancellationToken cancellationToken;
+ /**
+ * Creates a callback snapshot with immutable collection copies.
+ *
+ * @param toolCallId original model call identity
+ * @param toolName model-facing tool name
+ * @param input validated parsed JSON arguments
+ * @param stepIndex zero-based model invocation step
+ * @param messages messages used for this generation step
+ * @param requestContext caller application context
+ * @param providerMetadata provider or Halo metadata
+ * @param cancellationToken optional cooperative cancellation signal
+ */
@Builder
public ToolInputAvailableContext(
String toolCallId,
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaCallback.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaCallback.java
index d9bce470..1bc3e3da 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaCallback.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaCallback.java
@@ -2,9 +2,21 @@
import reactor.core.publisher.Mono;
-/** Backpressured callback invoked before one provider-native tool input delta is exposed. */
+/**
+ * Backpressured callback invoked before one provider-native tool input delta is exposed.
+ *
+ *
Complete the returned publisher before processing continues. Failures stop generation; callbacks should observe or
+ * prepare input without performing the requested tool operation. For example, an audit callback can persist the call
+ * identity through a reactive service and return its completion signal.
+ */
@FunctionalInterface
public interface ToolInputDeltaCallback {
+ /**
+ * Processes this request-scoped input event.
+ *
+ * @param context immutable event arguments and request metadata
+ * @return completion signal; an error stops generation
+ */
Mono onInputDelta(ToolInputDeltaContext context);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaContext.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaContext.java
index a6c3be73..84a6ff32 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaContext.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputDeltaContext.java
@@ -7,18 +7,44 @@
import run.halo.aifoundation.control.CancellationToken;
import run.halo.aifoundation.message.ModelMessage;
-/** Immutable provider-neutral snapshot for one streamed tool input delta callback. */
+/**
+ * Immutable provider-neutral snapshot for one streamed tool input delta callback.
+ *
+ *
The runtime supplies this snapshot before the next raw input fragment is exposed. Maps and message lists cannot be
+ * modified through this context. Use the tool call identity to correlate observations across callbacks, and honor the
+ * optional cancellation signal during asynchronous work.
+ */
@Value
public class ToolInputDeltaContext {
+ /** Original model tool call identity, used to correlate later input and result events. */
String toolCallId;
+ /** Model-facing name of the tool whose input is being processed. */
String toolName;
+ /** Unparsed provider-native argument fragment; it may not be valid JSON by itself. */
String inputTextDelta;
+ /** Zero-based model invocation step that produced this callback. */
Integer stepIndex;
+ /** Immutable list of provider-neutral messages used for this generation step. */
List messages;
+ /** Caller application context, excluded from model prompts. */
Map requestContext;
+ /** Provider or Halo metadata associated with this call and step. */
Map providerMetadata;
+ /** Optional cooperative cancellation signal for request-scoped work. */
CancellationToken cancellationToken;
+ /**
+ * Creates a callback snapshot with immutable collection copies.
+ *
+ * @param toolCallId original model call identity
+ * @param toolName model-facing tool name
+ * @param inputTextDelta raw streamed argument fragment
+ * @param stepIndex zero-based model invocation step
+ * @param messages messages used for this generation step
+ * @param requestContext caller application context
+ * @param providerMetadata provider or Halo metadata
+ * @param cancellationToken optional cooperative cancellation signal
+ */
@Builder
public ToolInputDeltaContext(
String toolCallId,
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputParseError.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputParseError.java
index cac090ac..075e0ff2 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputParseError.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputParseError.java
@@ -5,7 +5,13 @@
import lombok.Data;
import lombok.NoArgsConstructor;
-/** Describes a provider tool argument payload that could not be parsed as JSON. */
+/**
+ * Describes a provider tool argument payload that could not be parsed as JSON.
+ *
+ *
The failed {@link ToolCall} retains its raw input and carries this diagnostic. A repair callback can inspect it
+ * without losing the original payload. When the provider does not report an offset, {@link #characterOffset} remains
+ * {@code null}; do not infer a valid parsed input from that absence.
+ */
@Data
@Builder
@NoArgsConstructor
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartCallback.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartCallback.java
index 4efb3cc4..c8c7a641 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartCallback.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartCallback.java
@@ -2,9 +2,21 @@
import reactor.core.publisher.Mono;
-/** Backpressured callback invoked before tool input start is exposed. */
+/**
+ * Backpressured callback invoked before tool input start is exposed.
+ *
+ *
Complete the returned publisher before processing continues. Failures stop generation; callbacks should observe or
+ * prepare input without performing the requested tool operation. For example, an audit callback can persist the call
+ * identity through a reactive service and return its completion signal.
+ */
@FunctionalInterface
public interface ToolInputStartCallback {
+ /**
+ * Processes this request-scoped input event.
+ *
+ * @param context immutable event arguments and request metadata
+ * @return completion signal; an error stops generation
+ */
Mono onInputStart(ToolInputStartContext context);
}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartContext.java b/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartContext.java
index 4c1e4d50..4df877b9 100644
--- a/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartContext.java
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolInputStartContext.java
@@ -7,17 +7,41 @@
import run.halo.aifoundation.control.CancellationToken;
import run.halo.aifoundation.message.ModelMessage;
-/** Immutable provider-neutral snapshot for a tool input start callback. */
+/**
+ * Immutable provider-neutral snapshot for a tool input start callback.
+ *
+ *
The runtime supplies this snapshot before arguments are available. Maps and message lists cannot be modified
+ * through this context. Use the tool call identity to correlate observations across callbacks, and honor the optional
+ * cancellation signal during asynchronous work.
+ */
@Value
public class ToolInputStartContext {
+ /** Original model tool call identity, used to correlate later input and result events. */
String toolCallId;
+ /** Model-facing name of the tool whose input is being processed. */
String toolName;
+ /** Zero-based model invocation step that produced this callback. */
Integer stepIndex;
+ /** Immutable list of provider-neutral messages used for this generation step. */
List messages;
+ /** Caller application context, excluded from model prompts. */
Map requestContext;
+ /** Provider or Halo metadata associated with this call and step. */
Map providerMetadata;
+ /** Optional cooperative cancellation signal for request-scoped work. */
CancellationToken cancellationToken;
+ /**
+ * Creates a callback snapshot with immutable collection copies.
+ *
+ * @param toolCallId original model call identity
+ * @param toolName model-facing tool name
+ * @param stepIndex zero-based model invocation step
+ * @param messages messages used for this generation step
+ * @param requestContext caller application context
+ * @param providerMetadata provider or Halo metadata
+ * @param cancellationToken optional cooperative cancellation signal
+ */
@Builder
public ToolInputStartContext(
String toolCallId,
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolPermission.java b/api/src/main/java/run/halo/aifoundation/tool/ToolPermission.java
new file mode 100644
index 00000000..87a6bf98
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolPermission.java
@@ -0,0 +1,157 @@
+package run.halo.aifoundation.tool;
+
+import java.util.Arrays;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Declares the Halo resource operations a shared tool requires from its current caller.
+ *
+ *
Permissions use API groups, resource names, and verbs from Halo RBAC policy rules. UI permission labels such as
+ * {@code system:posts:manage} are not resource permissions. Register declarations through
+ * {@link ToolRegistration#getRequiredPermissions()}; every top-level entry must pass. Combine alternatives with
+ * {@link #anyOf(ToolPermission...)}.
+ *
+ *
+ */
+public sealed interface ToolPermission {
+
+ /**
+ * Requires a collection-level resource operation, such as listing posts.
+ *
+ * @param apiGroup concrete Halo API group; an empty string denotes the core API group
+ * @param resource concrete resource or subresource name, such as {@code posts}
+ * @param verb concrete operation, such as {@code list} or {@code create}
+ * @return collection-level permission declaration
+ */
+ static Resource resource(String apiGroup, String resource, String verb) {
+ return new Resource(apiGroup, resource, verb, null);
+ }
+
+ /**
+ * Requires an operation on the resource whose name is supplied by this input argument. Resolution checks whether a
+ * matching grant exists; execution checks the actual name. Array paths such as {@code items[].name} require
+ * permission for every supplied resource.
+ *
+ * @param apiGroup concrete Halo API group
+ * @param resource concrete resource or subresource name
+ * @param verb concrete operation, such as {@code get} or {@code update}
+ * @param nameArgument dot-separated input path containing a resource name or names
+ * @return name-aware permission declaration
+ * @throws IllegalArgumentException if the path or another declaration component is invalid
+ */
+ static Resource named(String apiGroup, String resource, String verb, String nameArgument) {
+ if (nameArgument == null) {
+ throw new IllegalArgumentException("Resource name argument is required");
+ }
+ return new Resource(apiGroup, resource, verb, nameArgument);
+ }
+
+ /**
+ * Requires every nested permission.
+ *
+ * @param permissions nonempty permission expressions without {@code null} entries
+ * @return a conjunction of the supplied expressions
+ */
+ static AllOf allOf(ToolPermission... permissions) {
+ return new AllOf(permissionList(permissions));
+ }
+
+ /**
+ * Requires at least one nested permission.
+ *
+ * @param permissions nonempty permission expressions without {@code null} entries
+ * @return a disjunction of the supplied expressions
+ */
+ static AnyOf anyOf(ToolPermission... permissions) {
+ return new AnyOf(permissionList(permissions));
+ }
+
+ /**
+ * A Halo API group, resource and verb. The empty API group denotes Halo core resources. A null resourceNameArgument
+ * requests a collection-level operation. Array paths such as {@code items[].name} check every resource name before
+ * the tool executes.
+ *
+ * @param apiGroup concrete Halo API group, or an empty string for the core group
+ * @param resource concrete resource or subresource name
+ * @param verb concrete operation name
+ * @param resourceNameArgument input path for target names, or {@code null} for a collection
+ */
+ record Resource(String apiGroup, String resource, String verb, String resourceNameArgument)
+ implements ToolPermission {
+ /**
+ * Rejects wildcard or whitespace-containing declarations before registration.
+ *
+ * @throws IllegalArgumentException if any declaration component is invalid
+ */
+ public Resource {
+ validate(apiGroup, "API group", true);
+ validate(resource, "Resource", false);
+ validate(verb, "Verb", false);
+ if (resourceNameArgument != null) {
+ validate(resourceNameArgument, "Resource name argument", false);
+ }
+ }
+ }
+
+ /**
+ * A nonempty conjunction of permissions.
+ *
+ * @param permissions expressions that must all pass
+ */
+ record AllOf(List permissions) implements ToolPermission {
+ /** Validates and snapshots the nested permission declarations. */
+ public AllOf {
+ permissions = nonemptyPermissions(permissions);
+ }
+ }
+
+ /**
+ * A nonempty disjunction of permissions.
+ *
+ * @param permissions expressions of which at least one must pass
+ */
+ record AnyOf(List permissions) implements ToolPermission {
+ /** Validates and snapshots the alternative permission declarations. */
+ public AnyOf {
+ permissions = nonemptyPermissions(permissions);
+ }
+ }
+
+ private static List permissionList(ToolPermission[] permissions) {
+ if (permissions == null) {
+ throw new IllegalArgumentException("Permissions are required");
+ }
+ return nonemptyPermissions(Arrays.asList(permissions));
+ }
+
+ private static List nonemptyPermissions(List permissions) {
+ if (permissions == null || permissions.isEmpty()) {
+ throw new IllegalArgumentException("At least one non-null permission is required");
+ }
+ if (permissions.stream().anyMatch(Objects::isNull)) {
+ throw new IllegalArgumentException("At least one non-null permission is required");
+ }
+ return List.copyOf(permissions);
+ }
+
+ private static void validate(String value, String label, boolean emptyAllowed) {
+ if (value == null) {
+ throw new IllegalArgumentException(label + " must be a concrete value without whitespace");
+ }
+ if (!emptyAllowed && value.isEmpty()) {
+ throw new IllegalArgumentException(label + " must be a concrete value without whitespace");
+ }
+ if (value.chars().anyMatch(Character::isWhitespace) || value.contains("*")) {
+ throw new IllegalArgumentException(label + " must be a concrete value without whitespace");
+ }
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolPermissionDeniedBehavior.java b/api/src/main/java/run/halo/aifoundation/tool/ToolPermissionDeniedBehavior.java
new file mode 100644
index 00000000..8a7de3fd
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolPermissionDeniedBehavior.java
@@ -0,0 +1,17 @@
+package run.halo.aifoundation.tool;
+
+/**
+ * Determines how shared tool resolution handles a caller lacking declared permissions.
+ *
+ *
{@link #FILTER_ON_RESOLVE} is the default: the model never receives unauthorized tools. Choose
+ * {@link #DENY_ON_EXECUTE} when the model should know an operation exists and report that it cannot execute it. Both
+ * modes recheck current permissions before invoking the executor.
+ *
+ * @see ToolRegistration#getPermissionDeniedBehavior()
+ */
+public enum ToolPermissionDeniedBehavior {
+ /** Omit unauthorized tools when resolving tools for a model. */
+ FILTER_ON_RESOLVE,
+ /** Keep the tool visible to the model, and reject unauthorized execution. */
+ DENY_ON_EXECUTE
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolPreset.java b/api/src/main/java/run/halo/aifoundation/tool/ToolPreset.java
new file mode 100644
index 00000000..ae058743
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolPreset.java
@@ -0,0 +1,48 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Defines a convenient selection of related tools within a {@link ToolGroup}.
+ *
+ *
Use local definition names such as {@code list_posts} and {@code get_post}, not catalog IDs. Every referenced
+ * registration must belong to the same group. Presets only assist selection; disabled, unconfigured, or unauthorized
+ * tools do not gain access by belonging to a preset.
+ *
+ *
+ */
+@Value
+public class ToolPreset {
+ /** Stable name unique within the containing group. */
+ String name;
+ /** Administrator-facing title, falling back to {@link #name} when blank. */
+ String displayName;
+ /** Optional explanation of when this selection is useful. */
+ String description;
+ /** Nonempty selection of distinct provider-local tool names in the containing group. */
+ List toolNames;
+
+ /**
+ * Creates a preset with an immutable snapshot of its local tool names.
+ *
+ * @param name stable preset name
+ * @param displayName administrator-facing title
+ * @param description optional selection explanation
+ * @param toolNames member tool names, validated when registered
+ */
+ @Builder
+ public ToolPreset(String name, String displayName, String description, List toolNames) {
+ this.name = name;
+ this.displayName = displayName;
+ this.description = description;
+ this.toolNames = toolNames == null ? List.of() : List.copyOf(toolNames);
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolPresetDescriptor.java b/api/src/main/java/run/halo/aifoundation/tool/ToolPresetDescriptor.java
new file mode 100644
index 00000000..b328d928
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolPresetDescriptor.java
@@ -0,0 +1,28 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Serializable preset containing the catalog identities of selected leaf tools.
+ *
+ *
A preset may reference tools currently disabled or awaiting configuration. Consumers should display their state
+ * and only select available members. For example, a read-only article preset can contain
+ * {@code article-tools/list_posts} and {@code article-tools/get_post}.
+ *
+ * @param id stable {@code pluginId/groupName/presetName} identity
+ * @param displayName administrator-facing title
+ * @param description optional selection explanation
+ * @param toolIds stable leaf tool identities, including unavailable members
+ */
+public record ToolPresetDescriptor(String id, String displayName, String description, List toolIds) {
+ /**
+ * Validates the identity and snapshots the selected IDs.
+ *
+ * @throws NullPointerException if {@code id} is {@code null}
+ */
+ public ToolPresetDescriptor {
+ Objects.requireNonNull(id, "id must not be null");
+ toolIds = toolIds == null ? List.of() : List.copyOf(toolIds);
+ }
+}
diff --git a/api/src/main/java/run/halo/aifoundation/tool/ToolRegistration.java b/api/src/main/java/run/halo/aifoundation/tool/ToolRegistration.java
new file mode 100644
index 00000000..65f3e9e3
--- /dev/null
+++ b/api/src/main/java/run/halo/aifoundation/tool/ToolRegistration.java
@@ -0,0 +1,102 @@
+package run.halo.aifoundation.tool;
+
+import java.util.List;
+import java.util.Objects;
+import lombok.Builder;
+import lombok.Value;
+
+/**
+ * Registers an executable tool and its presentation, configuration, and permission requirements.
+ *
+ *
A provider returns registrations from {@link AiToolProvider#tools()}. The definition name is local to that
+ * provider's plugin; consumers select the assigned catalog ID instead. Display metadata describes the tool to
+ * administrators, while {@link ToolDefinition#getDescription()} guides the model. All entries in
+ * {@link #requiredPermissions} must be satisfied.
+ *
+ *
Registrations are validated and copied before entering the catalog. Conflicting identities or inconsistent groups
+ * are excluded, administrator choices determine readiness, and declared permissions determine which definitions a
+ * caller receives. Catalog responses contain metadata only; executors and callbacks remain on the server.
+ *
+ *
For example, resolving {@code article-tools/get_post} returns a model-facing definition whose executor checks the
+ * current registration, readiness, and caller permissions before executing. This keeps a previously selected definition
+ * from retaining access after a provider is disabled.
+ */
+@Slf4j
+@Component
+public class AiToolServiceImpl implements AiToolService {
+
+ private static final Duration DEFAULT_PROVIDER_TIMEOUT = Duration.ofSeconds(5);
+ private static final Set JSON_TYPES =
+ Set.of("object", "array", "string", "number", "integer", "boolean", "null");
+ private static final Set CATEGORIES = Set.of("content", "web", "media", "site", "utility", "other");
+
+ private final ExtensionGetter extensionGetter;
+ private final PluginManager pluginManager;
+ private final List builtInProviders;
+ private final Duration providerTimeout;
+ private final LanguageModelStructuredOutputHandler valueValidator;
+ private final ToolSettingsStore settingsStore;
+ private final ToolPermissionChecker permissionChecker;
+
+ /**
+ * Creates the registry with Halo extension discovery and this plugin's tool-provider beans.
+ *
+ *
Business components implement {@link AiToolProvider} directly. Spring collects them without a separate
+ * registration list; enabled providers from other plugins are discovered through Halo.
+ *
+ * @param extensionGetter enabled cross-plugin extension lookup
+ * @param pluginWrapper owning plugin and plugin manager
+ * @param builtInProviders tool-provider beans from AI Foundation's application context
+ * @param settingsStore persisted administrator choices
+ * @param permissionChecker current caller's resource permission evaluator
+ */
+ @Autowired
+ public AiToolServiceImpl(
+ ExtensionGetter extensionGetter,
+ PluginWrapper pluginWrapper,
+ List builtInProviders,
+ ToolSettingsStore settingsStore,
+ ToolPermissionChecker permissionChecker) {
+ this(
+ extensionGetter,
+ pluginWrapper.getPluginManager(),
+ builtInProviders,
+ DEFAULT_PROVIDER_TIMEOUT,
+ settingsStore,
+ permissionChecker);
+ }
+
+ AiToolServiceImpl(
+ ExtensionGetter extensionGetter,
+ PluginManager pluginManager,
+ List builtInProviders,
+ Duration providerTimeout) {
+ this(extensionGetter, pluginManager, builtInProviders, providerTimeout, null);
+ }
+
+ AiToolServiceImpl(
+ ExtensionGetter extensionGetter,
+ PluginManager pluginManager,
+ List builtInProviders,
+ Duration providerTimeout,
+ ToolSettingsStore settingsStore) {
+ this(extensionGetter, pluginManager, builtInProviders, providerTimeout, settingsStore, null);
+ }
+
+ AiToolServiceImpl(
+ ExtensionGetter extensionGetter,
+ PluginManager pluginManager,
+ List builtInProviders,
+ Duration providerTimeout,
+ ToolSettingsStore settingsStore,
+ ToolPermissionChecker permissionChecker) {
+ this.extensionGetter = extensionGetter;
+ this.pluginManager = pluginManager;
+ this.builtInProviders = List.copyOf(builtInProviders);
+ this.providerTimeout = providerTimeout;
+ this.settingsStore = settingsStore;
+ this.permissionChecker = permissionChecker;
+ this.valueValidator = new LanguageModelStructuredOutputHandler(
+ new LanguageModelResponseMapper("tool-registry", new LanguageModelMessageMapper("tool-registry")),
+ new LanguageModelRuntimeSupport()::writeJson);
+ }
+
+ @Override
+ public Flux listTools() {
+ return registeredTools().flatMapMany(Flux::fromIterable).map(RegisteredTool::descriptor);
+ }
+
+ @Override
+ public Mono> resolveTools(List toolIds) {
+ return Mono.defer(() -> {
+ if (toolIds == null || toolIds.isEmpty()) {
+ return Mono.just(List.of());
+ }
+ var selection = new ArrayList();
+ var uniqueIds = new HashSet();
+ for (var id : toolIds) {
+ if (id == null || id.isBlank()) {
+ return Mono.error(new IllegalArgumentException("Tool IDs must not be blank"));
+ }
+ if (!uniqueIds.add(id)) {
+ return Mono.error(new IllegalArgumentException("Duplicate tool ID: " + id));
+ }
+ selection.add(id);
+ }
+ return registeredTools()
+ .map(tools -> {
+ var byId = new LinkedHashMap();
+ tools.forEach(tool -> byId.put(tool.descriptor().id(), tool));
+ return selection.stream()
+ .map(id -> {
+ var tool = byId.get(id);
+ if (tool == null) {
+ throw new IllegalArgumentException("Tool is unavailable: " + id);
+ }
+ if (!tool.descriptor().enabled()
+ || !tool.descriptor().configured()) {
+ throw new IllegalArgumentException("Tool is not ready: " + id + " ("
+ + tool.descriptor().status() + ")");
+ }
+ return tool;
+ })
+ .toList();
+ })
+ .flatMap(this::accessibleDefinitions);
+ });
+ }
+
+ @Override
+ public Mono> resolveAllTools() {
+ return registeredTools()
+ .flatMap(tools -> accessibleDefinitions(tools.stream()
+ .filter(tool ->
+ tool.descriptor().enabled() && tool.descriptor().configured())
+ .toList()));
+ }
+
+ private Mono> accessibleDefinitions(List tools) {
+ return Flux.fromIterable(tools)
+ .concatMap(tool -> canResolve(tool).filter(Boolean.TRUE::equals).map(allowed -> executable(tool)))
+ .collectList();
+ }
+
+ private Mono canResolve(RegisteredTool tool) {
+ if (tool.requiredPermissions().isEmpty()
+ || tool.permissionDeniedBehavior() == ToolPermissionDeniedBehavior.DENY_ON_EXECUTE) {
+ return Mono.just(true);
+ }
+ if (permissionChecker == null) {
+ return Mono.just(false);
+ }
+ return Mono.defer(() -> permissionChecker.canResolve(tool.requiredPermissions()))
+ .subscribeOn(Schedulers.boundedElastic())
+ .timeout(providerTimeout)
+ .defaultIfEmpty(false)
+ .onErrorReturn(false);
+ }
+
+ private Mono canExecute(RegisteredTool tool, Map input) {
+ if (tool.requiredPermissions().isEmpty()) {
+ return Mono.just(true);
+ }
+ if (permissionChecker == null) {
+ return Mono.just(false);
+ }
+ return Mono.defer(() -> permissionChecker.canExecute(tool.requiredPermissions(), input))
+ .subscribeOn(Schedulers.boundedElastic())
+ .timeout(providerTimeout)
+ .defaultIfEmpty(false)
+ .onErrorReturn(false);
+ }
+
+ /**
+ * Persists an administrator's enablement choice for an available catalog entry.
+ *
+ * @param id stable catalog ID
+ * @param enabled whether the tool may be selected and executed
+ * @return refreshed metadata after persistence
+ */
+ public Mono updateEnabled(String id, boolean enabled) {
+ return findTool(id).flatMap(ignored -> {
+ if (settingsStore == null) {
+ return Mono.error(new IllegalStateException("Tool settings store is unavailable"));
+ }
+ return settingsStore
+ .setEnabled(id, enabled)
+ .then(Mono.defer(() -> findTool(id)))
+ .map(RegisteredTool::descriptor);
+ });
+ }
+
+ /**
+ * Reads editable settings through the registered provider's configuration callback.
+ *
+ * @param id stable catalog ID of a configurable tool
+ * @return current values without resolved credentials
+ */
+ public Mono> getConfiguration(String id) {
+ return findTool(id).flatMap(tool -> {
+ var configuration = requireConfiguration(tool);
+ return Mono.defer(configuration.getValues())
+ .subscribeOn(Schedulers.boundedElastic())
+ .timeout(providerTimeout)
+ .defaultIfEmpty(Map.of());
+ });
+ }
+
+ /**
+ * Validates and saves settings through the provider, then rereads its current values.
+ *
+ * @param id stable catalog ID of a configurable tool
+ * @param values settings submitted by the administrator
+ * @return refreshed editable settings after a successful save
+ */
+ public Mono> updateConfiguration(String id, Map values) {
+ if (values == null) {
+ return Mono.error(new IllegalArgumentException("Tool configuration values are required"));
+ }
+ return findTool(id).flatMap(tool -> {
+ var configuration = requireConfiguration(tool);
+ return Mono.defer(() -> configuration.getSave().apply(values))
+ .subscribeOn(Schedulers.boundedElastic())
+ .timeout(providerTimeout)
+ .then(Mono.defer(() -> getConfiguration(id)));
+ });
+ }
+
+ private Mono findTool(String id) {
+ return registeredTools()
+ .map(tools -> tools.stream()
+ .filter(tool -> tool.descriptor().id().equals(id))
+ .findFirst()
+ .orElseThrow(() -> new IllegalArgumentException("Tool is unavailable: " + id)));
+ }
+
+ private static ToolConfiguration requireConfiguration(RegisteredTool tool) {
+ if (tool.configuration() == null) {
+ throw new IllegalArgumentException(
+ "Tool has no configuration: " + tool.descriptor().id());
+ }
+ return tool.configuration();
+ }
+
+ private Mono> registeredTools() {
+ var externalProviders = Flux.defer(() -> {
+ var providers = extensionGetter.getEnabledExtensions(AiToolProvider.class);
+ if (providers == null) {
+ return Flux.error(new IllegalStateException("Tool providers are unavailable"));
+ }
+ // Halo also scans this plugin's beans. Local built-ins are already included directly.
+ return providers.filter(provider -> builtInProviders.stream().noneMatch(builtin -> builtin == provider));
+ });
+ var tools = Flux.merge(
+ Flux.fromIterable(builtInProviders)
+ .flatMap(provider -> providerTools(provider, "ai-foundation")),
+ externalProviders.flatMap(provider -> providerTools(provider, null)))
+ .collectList()
+ .map(this::withoutConflicts)
+ .map(this::withoutGroupConflicts);
+ var states = settingsStore == null
+ ? Mono.>just(Map.of())
+ : Mono.defer(settingsStore::enabledStates);
+ return Mono.zip(tools, states)
+ .map(result -> result.getT1().stream()
+ .map(tool -> {
+ var descriptor = tool.descriptor();
+ var enabled = result.getT2().getOrDefault(descriptor.id(), true);
+ var managedDescriptor = new ToolDescriptor(
+ descriptor.id(),
+ descriptor.pluginName(),
+ descriptor.localName(),
+ descriptor.name(),
+ descriptor.displayName(),
+ descriptor.description(),
+ descriptor.displayDescription(),
+ descriptor.category(),
+ descriptor.inputSchema(),
+ descriptor.outputSchema(),
+ descriptor.tags(),
+ descriptor.configurationSchema(),
+ enabled,
+ descriptor.configured(),
+ null,
+ descriptor.group());
+ return new RegisteredTool(
+ managedDescriptor,
+ tool.definition(),
+ tool.configuration(),
+ tool.requiredPermissions(),
+ tool.permissionDeniedBehavior());
+ })
+ .toList());
+ }
+
+ private Flux providerTools(AiToolProvider provider, String builtInOwner) {
+ return Flux.defer(() -> {
+ var tools = provider.tools();
+ if (tools == null) {
+ return Flux.error(new IllegalStateException("Tool provider returned no stream"));
+ }
+ return tools;
+ })
+ .subscribeOn(Schedulers.boundedElastic())
+ .collectList()
+ .map(tools -> {
+ var owner = builtInOwner != null ? builtInOwner : providerOwner(provider);
+ return tools.stream().map(tool -> register(owner, tool)).toList();
+ })
+ .timeout(providerTimeout)
+ .flatMapMany(Flux::fromIterable)
+ .onErrorResume(error -> {
+ log.warn(
+ "Ignoring unavailable AI tool provider {}",
+ provider.getClass().getName(),
+ error);
+ return Flux.empty();
+ });
+ }
+
+ private String providerOwner(AiToolProvider provider) {
+ var owner = pluginManager.whichPlugin(AopUtils.getTargetClass(provider));
+ if (owner == null) {
+ throw new IllegalStateException("Cannot determine the AI tool provider plugin");
+ }
+ var pluginId = owner.getPluginId();
+ if (pluginId == null || pluginId.isBlank()) {
+ throw new IllegalStateException("Cannot determine the AI tool provider plugin");
+ }
+ if (pluginId.contains("/")) {
+ throw new IllegalStateException("Cannot determine the AI tool provider plugin");
+ }
+ return pluginId;
+ }
+
+ private RegisteredTool register(String owner, ToolRegistration registration) {
+ if (registration == null || registration.getDefinition() == null) {
+ throw new IllegalArgumentException("Tool provider returned no definition");
+ }
+ var definition = registration.getDefinition();
+ var localName = definition.getName();
+ if (localName == null || !localName.matches("[A-Za-z0-9_-]{1,63}")) {
+ throw new IllegalArgumentException(
+ "Tool local name must contain 1-63 letters, numbers," + " underscores, or hyphens");
+ }
+ if (definition.getExecutor() == null) {
+ throw new IllegalArgumentException("Discoverable tools must have a server-side executor");
+ }
+ var inputSchema = definition.getInputSchema();
+ if (inputSchema == null || !"object".equals(inputSchema.get("type"))) {
+ throw new IllegalArgumentException("Tool inputSchema must declare an object type");
+ }
+ var configuration = registration.getConfiguration();
+ validateConfiguration(configuration);
+ var id = owner + "/" + localName;
+ var category = category(registration.getCategory());
+ var descriptor = new ToolDescriptor(
+ id,
+ owner,
+ localName,
+ modelName(id, localName),
+ hasText(registration.getDisplayName()) ? registration.getDisplayName() : localName,
+ definition.getDescription(),
+ hasText(registration.getDisplayDescription())
+ ? registration.getDisplayDescription()
+ : definition.getDescription(),
+ category,
+ inputSchema,
+ definition.getOutputSchema(),
+ registration.getTags(),
+ configuration != null ? configuration.getSchema() : List.of(),
+ true,
+ registration.isConfigured(),
+ null,
+ group(owner, registration.getGroup()));
+ validateSchema(descriptor.inputSchema());
+ if (descriptor.outputSchema() != null) {
+ validateSchema(descriptor.outputSchema());
+ }
+ var snapshot = copyDefinition(definition, descriptor);
+ return new RegisteredTool(
+ descriptor,
+ snapshot,
+ configuration,
+ registration.getRequiredPermissions(),
+ registration.getPermissionDeniedBehavior());
+ }
+
+ private static void validateConfiguration(ToolConfiguration configuration) {
+ if (configuration == null) {
+ return;
+ }
+ if (configuration.getSchema() == null || configuration.getSchema().isEmpty()) {
+ throw new IllegalArgumentException("Tool configuration must provide a schema and callbacks");
+ }
+ if (configuration.getValues() == null || configuration.getSave() == null) {
+ throw new IllegalArgumentException("Tool configuration must provide a schema and callbacks");
+ }
+ }
+
+ private static String category(String value) {
+ return value != null && CATEGORIES.contains(value) ? value : "other";
+ }
+
+ private static ToolGroupDescriptor group(String owner, ToolGroup group) {
+ if (group == null) {
+ return null;
+ }
+ validateLocalName(group.getName(), "Tool group");
+ var id = owner + "/" + group.getName();
+ var presetNames = new HashSet();
+ var presets = new ArrayList();
+ for (var preset : group.getPresets()) {
+ validateLocalName(preset.getName(), "Tool preset");
+ if (!presetNames.add(preset.getName())) {
+ throw new IllegalArgumentException("Tool preset names must be unique within a group");
+ }
+ if (preset.getToolNames().isEmpty()) {
+ throw new IllegalArgumentException("Tool presets must reference at least one tool");
+ }
+ var localNames = new HashSet();
+ var toolIds = new ArrayList();
+ for (var localName : preset.getToolNames()) {
+ validateLocalName(localName, "Preset tool");
+ if (!localNames.add(localName)) {
+ throw new IllegalArgumentException("Tool presets must reference unique tools");
+ }
+ toolIds.add(owner + "/" + localName);
+ }
+ presets.add(new ToolPresetDescriptor(
+ id + "/" + preset.getName(),
+ hasText(preset.getDisplayName()) ? preset.getDisplayName() : preset.getName(),
+ preset.getDescription(),
+ toolIds));
+ }
+ return new ToolGroupDescriptor(
+ id,
+ hasText(group.getDisplayName()) ? group.getDisplayName() : group.getName(),
+ group.getDescription(),
+ presets);
+ }
+
+ private static void validateLocalName(String name, String label) {
+ if (name == null || !name.matches("[A-Za-z0-9_-]{1,63}")) {
+ throw new IllegalArgumentException(
+ label + " name must contain 1-63 letters, numbers," + " underscores, or hyphens");
+ }
+ }
+
+ private List withoutGroupConflicts(List tools) {
+ var groups = new LinkedHashMap();
+ var byId = new LinkedHashMap();
+ var invalidGroups = new HashSet();
+ for (var tool : tools) {
+ byId.put(tool.descriptor().id(), tool);
+ var group = tool.descriptor().group();
+ if (group == null) {
+ continue;
+ }
+ var existing = groups.putIfAbsent(group.id(), group);
+ if (existing != null && !existing.equals(group)) {
+ invalidGroups.add(group.id());
+ log.warn("Ignoring AI tool group with conflicting metadata: {}", group.id());
+ }
+ }
+ for (var group : groups.values()) {
+ if (!validGroupReferences(group, byId)) {
+ invalidGroups.add(group.id());
+ }
+ }
+ return tools.stream()
+ .filter(tool -> tool.descriptor().group() == null
+ || !invalidGroups.contains(tool.descriptor().group().id()))
+ .toList();
+ }
+
+ private static boolean validGroupReferences(ToolGroupDescriptor group, Map toolsById) {
+ var valid = true;
+ for (var preset : group.presets()) {
+ for (var id : preset.toolIds()) {
+ if (belongsToGroup(toolsById.get(id), group.id())) {
+ continue;
+ }
+ valid = false;
+ log.warn(
+ "Ignoring AI tool group {}: preset {} references a missing or " + "different-group tool {}",
+ group.id(),
+ preset.id(),
+ id);
+ }
+ }
+ return valid;
+ }
+
+ private static boolean belongsToGroup(RegisteredTool tool, String groupId) {
+ if (tool == null || tool.descriptor().group() == null) {
+ return false;
+ }
+ return groupId.equals(tool.descriptor().group().id());
+ }
+
+ private ToolDefinition copyDefinition(ToolDefinition source, ToolDescriptor descriptor) {
+ var examples = source.getInputExamples() == null
+ ? null
+ : source.getInputExamples().stream()
+ .map(example -> new ToolDescriptor(
+ descriptor.id(),
+ descriptor.pluginName(),
+ descriptor.localName(),
+ descriptor.name(),
+ null,
+ null,
+ null,
+ null,
+ example,
+ null,
+ List.of(),
+ List.of(),
+ true,
+ true,
+ null,
+ null)
+ .inputSchema())
+ .toList();
+ return ToolDefinition.builder()
+ .name(descriptor.name())
+ .description(descriptor.description())
+ .inputSchema(descriptor.inputSchema())
+ .outputSchema(descriptor.outputSchema())
+ .inputExamples(examples)
+ .strict(source.getStrict())
+ .approvalPolicy(copyApprovalPolicy(source.getApprovalPolicy()))
+ .onInputStart(source.getOnInputStart())
+ .onInputDelta(source.getOnInputDelta())
+ .onInputAvailable(source.getOnInputAvailable())
+ .executor(source.getExecutor())
+ .build();
+ }
+
+ private ToolDefinition executable(RegisteredTool tool) {
+ var descriptor = tool.descriptor();
+ var definition = copyDefinition(tool.definition(), descriptor);
+ var approvalMode = approvalMode(definition.getApprovalPolicy());
+ definition.setExecutor(context -> executeCurrent(descriptor, approvalMode, context));
+ return definition;
+ }
+
+ private Mono