com.l1fe.forge:forge-tool

import com.l1fe.forge.tool.*

public interface ApprovalHandler

public suspend fun check(call: ToolCall, tier: ToolTier): ToolApproval
}

/**
* An approval handler that always approves tool calls.
*
* Useful for development, testing, and scenarios where all tools
* are pre-authorized.
*
* Security consideration: Using [AutoApprove] in production means
* every tool call is permitted. For production use with External-tier
* tools, prefer [TierBasedApproval] or a custom handler.
*/
public object AutoApprove : ApprovalHandler

public object AutoApprove : ApprovalHandler

public class DenyAll(
private val reason: String,
) : ApprovalHandler

public object TierBasedApproval : ApprovalHandler

public class ToolBuilder(private val name: String)

public fun description(description: String): ToolBuilder;

public fun tier(tier: ToolTier): ToolBuilder;

public fun parameters(parameters: JsonSchema): ToolBuilder;

public fun executor(executor: ToolExecutor): ToolBuilder;

public fun handler(handler: (ToolCall) -> ToolResult): ToolBuilder;

public fun build(): Pair<ToolDefinition, ToolExecutor?>

public sealed class ToolError(
message: String,
cause: Throwable?;

public class ToolNotFound(
public val name: String,
) : ToolError(
"tool '$name' not found in registry; register it with ToolRegistry.register() before invoking"

public val name: String,
) : ToolError(
"tool '$name' not found in registry; register it with ToolRegistry.register() before invoking"

public class ExecutionFailed(
public val name: String,
public val reason: String,
cause: Throwable?;

public val name: String,
public val reason: String,
cause: Throwable?;

public val reason: String,
cause: Throwable?;

public class ApprovalDenied(
public val name: String,
public val reason: String,
) : ToolError("tool '$name' invocation denied by approval handler: $reason")

/**
* Schema validation failed for tool arguments.
*
* @property name The tool whose schema was violated.
* @property path JSON pointer path to the failing field.
* @property reason Human-readable description of what was expected.
*/
public class SchemaValidation(
public val name: String,
public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.

public val name: String,
public val reason: String,
) : ToolError("tool '$name' invocation denied by approval handler: $reason")

/**
* Schema validation failed for tool arguments.
*
* @property name The tool whose schema was violated.
* @property path JSON pointer path to the failing field.
* @property reason Human-readable description of what was expected.
*/
public class SchemaValidation(
public val name: String,
public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/

public val reason: String,
) : ToolError("tool '$name' invocation denied by approval handler: $reason")

/**
* Schema validation failed for tool arguments.
*
* @property name The tool whose schema was violated.
* @property path JSON pointer path to the failing field.
* @property reason Human-readable description of what was expected.
*/
public class SchemaValidation(
public val name: String,
public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/
public class InvalidTier(

public class SchemaValidation(
public val name: String,
public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/
public class InvalidTier(
public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*

public val name: String,
public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/
public class InvalidTier(
public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.

public val path: String,
public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/
public class InvalidTier(
public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/

public val reason: String,
) : ToolError("schema validation failed for tool '$name' at path '$path': $reason")

/**
* A tool was registered or invoked with an incorrect tier classification.
*
* ANVIL Spec Section 8.1 -- Tool Tier Classification
*
* @property name The tool whose tier is mismatched.
* @property expected The expected tier classification.
* @property actual The actual tier classification provided.
*/
public class InvalidTier(
public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/
public class RegistryError(

public class InvalidTier(
public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/
public class RegistryError(
public val reason: String,
) : ToolError("tool registry error: $reason")
}

public val name: String,
public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/
public class RegistryError(
public val reason: String,
) : ToolError("tool registry error: $reason")
}

public val expected: String,
public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/
public class RegistryError(
public val reason: String,
) : ToolError("tool registry error: $reason")
}

public val actual: String,
) : ToolError(
"tool '$name' has invalid tier: expected $expected, got $actual (see ANVIL Spec SS8.1)"
)

/**
* A registry operation failed (e.g., duplicate registration).
*
* @property reason What went wrong with the registry operation.
*/
public class RegistryError(
public val reason: String,
) : ToolError("tool registry error: $reason")
}

public class RegistryError(
public val reason: String,
) : ToolError("tool registry error: $reason")
}

public val reason: String,
) : ToolError("tool registry error: $reason")
}

public interface ToolExecutor

public suspend fun execute(call: ToolCall): ToolResult

/**
* Returns the name of the tool this executor handles.
*/
public val name: String
}

/**
* A tool executor that wraps a synchronous function.
*
* Allows defining simple tools as lambdas without implementing the
* full [ToolExecutor] interface.
*
* @property name The tool name this executor handles.
* @property handler The synchronous handler function.
*/
public class FnToolExecutor(
override val name: String,
private val handler: (ToolCall) -> ToolResult,
) : ToolExecutor

public val name: String
}

/**
* A tool executor that wraps a synchronous function.
*
* Allows defining simple tools as lambdas without implementing the
* full [ToolExecutor] interface.
*
* @property name The tool name this executor handles.
* @property handler The synchronous handler function.
*/
public class FnToolExecutor(
override val name: String,
private val handler: (ToolCall) -> ToolResult,
) : ToolExecutor

public class FnToolExecutor(
override val name: String,
private val handler: (ToolCall) -> ToolResult,
) : ToolExecutor

public suspend fun executeToolCall(
call: ToolCall,
definition: ToolDefinition,
executor: ToolExecutor,
approvalHandler: ApprovalHandler,
): ToolResult

public enum class ExecutionContext

public data class TierClassification(
val toolName: String,
val tier: ToolTier,
val requiresAuthorization: Boolean,
val executionContext: ExecutionContext,
)

/**
* Classifies a tool by its tier, returning authorization requirements
* and execution context.
*
* ANVIL Spec Section 8.1--8.4
*
* @param toolName The name of the tool being classified.
* @param tier The tool's tier classification.
* @return A [TierClassification] with the tool's requirements.
*/
public fun classifyTier(toolName: String, tier: ToolTier): TierClassification;

public fun classifyTier(toolName: String, tier: ToolTier): TierClassification;

public fun requiresAuthorization(tier: ToolTier): Boolean;

public fun executionContextFor(tier: ToolTier): ExecutionContext;