feat(#1015): tool(...) builders return typed Tool<Args, Result> handles

Add a Tool<Args, Result> @JvmInline value class wrapping the underlying
ToolDef. Every tool(...) overload in ToolsBuilder now returns a typed
handle: untyped overloads as Tool<Map<String, Any?>, Any?>, the typed
inline overload as Tool<Args, Result>.

Strictly additive — return value is meaningless on its own and existing
call sites continue to compile and behave identically. The handle is
the foundation for typed Skill.tools(...) / +autoTool(...) overloads
landing in #1016 (KSP P1.2), the first user-visible step of the
KSP initiative described in docs/ksp-design.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Skobeltsyn

src/main/kotlin/agents_engine/model/ToolDef.kt

@@ -28,6 +28,27 @@ class ToolDef(
         internal set
 }
 
+/**
+ * Typed handle returned by every `tool(...)` builder overload. Wraps a
+ * [ToolDef] with phantom type parameters that let `Skill.tools(...)` and
+ * `+autoTool(...)` accept compile-time-checked references instead of
+ * stringly-typed lookups (#1015 — KSP P1.1).
+ *
+ * `Args` is the deserialized input type for typed tools (the `@Generable`
+ * data class), `Map<String, Any?>` for untyped tools. `Result` is the lambda's
+ * return type. Both type parameters are erased at runtime — the [def]
+ * underneath is the canonical runtime representation.
+ */
+@JvmInline
+value class Tool<Args, Result> @PublishedApi internal constructor(
+    @PublishedApi internal val def: ToolDef,
+) {
+    val name: String get() = def.name
+    val description: String get() = def.description
+
+    override fun toString(): String = "Tool<${def.name}>"
+}
+
 class ToolDefaultsBuilder {
     internal var errorHandler: ToolErrorHandler? = null
 
@@ -64,21 +85,27 @@ class ToolsBuilder {
         defaultErrorHandler = builder.errorHandler
     }
 
-    fun tool(name: String, description: String, executor: (Map<String, Any?>) -> Any?) {
+    fun tool(
+        name: String,
+        description: String,
+        executor: (Map<String, Any?>) -> Any?,
+    ): Tool<Map<String, Any?>, Any?> {
         requireUserNotReservedToolName(name)
         require(defs.none { it.name == name }) {
             "Tool \"$name\" is already defined in this tools block. " +
                 "Tool names must be unique."
         }
-        defs.add(ToolDef(name = name, description = description, executor = executor))
+        val def = ToolDef(name = name, description = description, executor = executor)
+        defs.add(def)
+        return Tool(def)
     }
 
     fun tool(
         name: String,
         description: String,
         onError: OnErrorBuilder.() -> Unit,
         executor: (Map<String, Any?>) -> Any?,
-    ) {
+    ): Tool<Map<String, Any?>, Any?> {
         requireUserNotReservedToolName(name)
         require(defs.none { it.name == name }) {
             "Tool \"$name\" is already defined in this tools block. " +
@@ -87,9 +114,10 @@ class ToolsBuilder {
         val def = ToolDef(name = name, description = description, executor = executor)
         def.errorHandler = OnErrorBuilder().apply(onError).build()
         defs.add(def)
+        return Tool(def)
     }
 
-    fun tool(name: String, block: ToolDefBuilder.() -> Unit) {
+    fun tool(name: String, block: ToolDefBuilder.() -> Unit): Tool<Map<String, Any?>, Any?> {
         requireUserNotReservedToolName(name)
         require(defs.none { it.name == name }) {
             "Tool \"$name\" is already defined in this tools block. " +
@@ -99,6 +127,7 @@ class ToolsBuilder {
         builder.block()
         val def = builder.build()
         defs.add(def)
+        return Tool(def)
     }
 
     operator fun ToolDef.unaryPlus() {
@@ -127,7 +156,7 @@ class ToolsBuilder {
         name: String,
         description: String,
         crossinline executor: (Args) -> Result,
-    ) {
+    ): Tool<Args, Result> {
         requireUserNotReservedToolName(name)
         require(defs.none { it.name == name }) {
             "Tool \"$name\" is already defined in this tools block. " +
@@ -150,7 +179,9 @@ class ToolsBuilder {
                 )
             executor(typed)
         }
-        defs.add(ToolDef(name = name, description = description, executor = wrapped, argsType = argsClass))
+        val def = ToolDef(name = name, description = description, executor = wrapped, argsType = argsClass)
+        defs.add(def)
+        return Tool(def)
     }
 }
 

src/test/kotlin/agents_engine/model/ToolHandleTest.kt

@@ -0,0 +1,82 @@
+package agents_engine.model
+
+import agents_engine.core.agent
+import agents_engine.generation.Generable
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertSame
+
+/**
+ * #1015 — `tool(...)` builders return typed `Tool<Args, Result>` handles.
+ *
+ * The handle is the basis for typed `Skill.tools(...)` / `+autoTool(...)` overloads
+ * landing in #1016, but it must already work as a standalone return value in 0.2.x:
+ * existing call sites that ignore the return value continue to compile, and new
+ * call sites that bind the handle to a `val` see the type parameters propagate.
+ */
+class ToolHandleTest {
+
+    @Generable("a typed tool's args")
+    data class FetchArgs(val url: String, val timeoutMs: Int = 5_000)
+
+    @Test
+    fun `untyped tool builder returns Tool with Map Args`() {
+        var captured: Tool<Map<String, Any?>, Any?>? = null
+        agent<String, String>("untyped-tool-handle") {
+            tools {
+                captured = tool("fetch", "Fetch a URL") { args -> args["url"]?.toString() ?: "missing" }
+            }
+            skills { skill<String, String>("s") { implementedBy { it } } }
+        }
+        val handle = checkNotNull(captured)
+        assertEquals("fetch", handle.name)
+        assertEquals("Fetch a URL", handle.description)
+        assertEquals("Tool<fetch>", handle.toString())
+    }
+
+    @Test
+    fun `typed tool builder returns Tool with reified Args`() {
+        var captured: Tool<FetchArgs, String>? = null
+        agent<String, String>("typed-tool-handle") {
+            tools {
+                captured = tool<FetchArgs, String>("fetch_typed", "Fetch typed") { args ->
+                    "GET ${args.url} (${args.timeoutMs}ms)"
+                }
+            }
+            skills { skill<String, String>("s") { implementedBy { it } } }
+        }
+        val handle = checkNotNull(captured)
+        assertEquals("fetch_typed", handle.name)
+        assertEquals("Tool<fetch_typed>", handle.toString())
+    }
+
+    @Test
+    fun `block-builder tool returns Tool handle`() {
+        var captured: Tool<Map<String, Any?>, Any?>? = null
+        agent<String, String>("block-tool-handle") {
+            tools {
+                captured = tool("audit") {
+                    description("Audit log writer")
+                    executor { _ -> "logged" }
+                }
+            }
+            skills { skill<String, String>("s") { implementedBy { it } } }
+        }
+        val handle = checkNotNull(captured)
+        assertEquals("audit", handle.name)
+        assertEquals("Audit log writer", handle.description)
+    }
+
+    @Test
+    fun `Tool def points at the same ToolDef registered with the agent`() {
+        var captured: Tool<Map<String, Any?>, Any?>? = null
+        val a = agent<String, String>("ref-identity") {
+            tools {
+                captured = tool("ping", "ping") { _ -> "pong" }
+            }
+            skills { skill<String, String>("s") { implementedBy { it } } }
+        }
+        val handle = checkNotNull(captured)
+        assertSame(a.toolMap["ping"], handle.def)
+    }
+}