refactor: split examples into mill submodules

Author: arcaputo3

AGENTS.md

@@ -11,7 +11,8 @@
 - `bun install`: install JS dependencies (Bun is the preferred runtime).
 - `./mill agent.compile` or `bun run build`: compile the Scala.js library.
 - `./mill agent.test`: run the MUnit test suite.
-- `./mill examples.run`: run the default example; use `EXAMPLE=simple ./mill examples.run` for a specific example.
+- `./mill examples.run`: run the default example.
+- `./mill examples.simple.run`: run a specific example by submodule, e.g. `./mill examples.hook.run`.
 - `bun run run`: compile and execute the JS output for examples.
 - `./mill examples.list`: list available example entry points.
 

build.mill

@@ -258,7 +258,7 @@ object agent extends ScalaJSModule with PublishModule with BunNpmModule {
 // Example application module
 // ---------------------------------------------------------------------------
 
-object examples extends BunNpmModule {
+trait ExampleModule extends BunNpmModule {
   def scalaVersion = agent.scalaVersion
   def scalaJSVersion = agent.scalaJSVersion
 
@@ -280,22 +280,29 @@ object examples extends BunNpmModule {
   override def moduleDir = build.moduleDir
   override def sources = Task.Sources(moduleDir / "examples")
 
+  def exampleMainClass: String
+
+  override def mainClass = Task { Some(exampleMainClass) }
+}
+
+object examples extends ExampleModule {
+  def exampleMainClass = "com.tjclp.scalagent.examples.MacroToolExample"
+
   // Available examples - add new ones here
-  val exampleClasses = Map(
-    "simple"       -> "com.tjclp.scalagent.examples.SimpleQuery",
-    "macro"        -> "com.tjclp.scalagent.examples.MacroToolExample",
-    "custom"       -> "com.tjclp.scalagent.examples.CustomToolExample",
-    "hook"         -> "com.tjclp.scalagent.examples.HookExample",
-    "permission"   -> "com.tjclp.scalagent.examples.PermissionExample",
-    "session"      -> "com.tjclp.scalagent.examples.SessionExample",
-    // New examples for recent features
-    "structured"   -> "com.tjclp.scalagent.examples.StructuredOutputExample",
-    "subagent"     -> "com.tjclp.scalagent.examples.SubagentExample",
-    "plugin"       -> "com.tjclp.scalagent.examples.PluginExample",
-    "prompt"       -> "com.tjclp.scalagent.examples.SystemPromptExample",
-    "command"      -> "com.tjclp.scalagent.examples.SlashCommandExample",
-    "a2a"          -> "com.tjclp.scalagent.examples.A2AExample",
-    "agent-hooks"  -> "com.tjclp.scalagent.examples.AgentHooksExample"
+  val exampleCommands = Map(
+    "simple"       -> "examples.simple.run",
+    "macro"        -> "examples.run",
+    "custom"       -> "examples.custom.run",
+    "hook"         -> "examples.hook.run",
+    "permission"   -> "examples.permission.run",
+    "session"      -> "examples.session.run",
+    "structured"   -> "examples.structured.run",
+    "subagent"     -> "examples.subagent.run",
+    "plugin"       -> "examples.plugin.run",
+    "prompt"       -> "examples.prompt.run",
+    "command"      -> "examples.command.run",
+    "a2a"          -> "examples.a2a.run",
+    "agent-hooks"  -> "examples.agentHooks.run"
   )
 
   private val defaultExample = "macro"
@@ -304,25 +311,64 @@ object examples extends BunNpmModule {
   def list() = Task.Command {
     println("Available examples:")
     println("-------------------")
-    exampleClasses.toSeq.sortBy(_._1).foreach { case (name, cls) =>
-      println(s"  $name -> $cls")
+    exampleCommands.toSeq.sortBy(_._1).foreach { case (name, command) =>
+      println(s"  $name -> ./$command")
     }
     println()
     println("Run with:")
     println(s"  ./mill examples.run                   # runs '$defaultExample' by default")
-    println("  EXAMPLE=simple ./mill examples.run    # run specific example")
-    println("  EXAMPLE=hook ./mill examples.run      # run hook example")
+    println("  ./mill examples.simple.run           # run simple example")
+    println("  ./mill examples.hook.run             # run hook example")
     println()
     println("Or run the compiled JS directly:")
     println("  bun out/examples/fastLinkJS.dest/main.js")
   }
 
-  // Dynamic mainClass based on environment or default
-  // Task.Input ensures this is re-evaluated each run
-  override def mainClass = Task.Input {
-    val example = Task.env.get("EXAMPLE").getOrElse(defaultExample)
-    val cls = exampleClasses.get(example)
-    if cls.isEmpty then println(s"Warning: Unknown example '$example', using '$defaultExample'")
-    cls.orElse(Some(exampleClasses(defaultExample)))
+  object simple extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.SimpleQuery"
+  }
+
+  object custom extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.CustomToolExample"
+  }
+
+  object hook extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.HookExample"
+  }
+
+  object permission extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.PermissionExample"
+  }
+
+  object session extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.SessionExample"
+  }
+
+  object structured extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.StructuredOutputExample"
+  }
+
+  object subagent extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.SubagentExample"
+  }
+
+  object plugin extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.PluginExample"
+  }
+
+  object prompt extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.SystemPromptExample"
+  }
+
+  object command extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.SlashCommandExample"
+  }
+
+  object a2a extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.A2AExample"
+  }
+
+  object agentHooks extends ExampleModule {
+    def exampleMainClass = "com.tjclp.scalagent.examples.AgentHooksExample"
   }
 }

examples/A2AExample.scala

@@ -18,7 +18,7 @@ import com.tjclp.scalagent.*
   * Claude Writer (local) --> A2ATool --> A2A Client --> A2A Server --> Claude Researcher
   * ```
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.A2AExample
+  * Run with: ./mill examples.a2a.run
   *
   * Requires:
   *   - ANTHROPIC_API_KEY environment variable when Claude Code auth is not already available

examples/AgentHooksExample.scala

@@ -14,7 +14,7 @@ import com.tjclp.scalagent.hooks.HookConfig
   *   4. Use the permissionMode field in AgentDefinition
   *   5. Use the fluent extension methods (withShellHook, withCallbackHook)
   *
-  * Run with: EXAMPLE=agent-hooks mill examples.run
+  * Run with: ./mill examples.agentHooks.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/CustomToolExample.scala

@@ -12,7 +12,7 @@ import com.tjclp.scalagent.*
   *   2. Create an in-process MCP server with those tools
   *   3. Use the custom tools in a Claude agent query
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.CustomToolExample
+  * Run with: ./mill examples.custom.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/HookExample.scala

@@ -11,7 +11,7 @@ import com.tjclp.scalagent.*
   *   2. Block specific tools (e.g., Bash commands)
   *   3. Modify tool behavior based on custom logic
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.HookExample
+  * Run with: ./mill examples.hook.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/MacroToolExample.scala

@@ -16,7 +16,7 @@ import com.tjclp.scalagent.*
   *   - Support for structured output with ToolResult.json()
   *   - Support for multimodal output with ToolResult.multi
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.MacroToolExample
+  * Run with: ./mill examples.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/PermissionExample.scala

@@ -14,7 +14,7 @@ import com.tjclp.scalagent.permissions.{PermissionUpdate, PermissionUpdateDestin
   *   3. Use permission utilities for common patterns
   *   4. Programmatic permission updates with PermissionUpdateDestination
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.PermissionExample
+  * Run with: ./mill examples.permission.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/PluginExample.scala

@@ -11,7 +11,7 @@ import com.tjclp.scalagent.*
   * - Handle PluginError types (PathNotFound, NotADirectory, MissingManifest)
   * - Use convenience methods like withLocalPlugins()
   *
-  * Run with: EXAMPLE=plugin mill examples.run
+  * Run with: ./mill examples.plugin.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   */

examples/SessionExample.scala

@@ -17,7 +17,7 @@ import com.tjclp.scalagent.*
   *   - Proper resource cleanup with `session.close`
   *   - Validated session UUIDs with `SessionUuid`
   *
-  * Run with: mill examples.runMain com.tjclp.scalagent.examples.SessionExample
+  * Run with: ./mill examples.session.run
   *
   * Requires ANTHROPIC_API_KEY environment variable to be set when Claude Code auth is not already available.
   *