fix: upgrade to Spring Shell 4

Signed-off-by: Arnab Nandy <arnab_nandy7@yahoo.com>

Author: arnabnandy7

embabel-agent-docs/src/main/asciidoc/reference/rag/page.adoc

@@ -1111,8 +1111,8 @@ Java::
 +
 [source,java]
 ----
-@ShellMethod("Ingest URL or file path")
-String ingest(@ShellOption(defaultValue = "./data/document.md") String location) {
+@Command("Ingest URL or file path")
+String ingest(@Option(defaultValue = "./data/document.md") String location) {
     var uri = location.startsWith("http://") || location.startsWith("https://")
             ? location
             : Path.of(location).toAbsolutePath().toUri().toString();
@@ -1132,8 +1132,8 @@ Kotlin::
 +
 [source,kotlin]
 ----
-@ShellMethod("Ingest URL or file path")
-fun ingest(@ShellOption(defaultValue = "./data/document.md") location: String): String {
+@Command("Ingest URL or file path")
+fun ingest(@Option(defaultValue = "./data/document.md") location: String): String {
     val uri = if (location.startsWith("http://") || location.startsWith("https://")) {
         location
     } else {
@@ -1632,4 +1632,3 @@ See the https://github.com/embabel/rag-demo[rag-demo] project for a complete wor
 - Chatbot with RAG-powered responses
 - Jinja prompt templates for system prompts
 - Spring Shell commands for interactive testing
-

embabel-agent-docs/src/main/asciidoc/shell/commands.adoc

@@ -124,7 +124,7 @@ The persistent context remains `{tenantId=acme, authToken=bearer-xyz123}` for fu
 ==== Implementing Custom Shell Commands
 
 During development you may want to add your own shell commands to invoke specific agents or flows directly, bypassing the natural-language routing of `execute`.
-Because the Embabel Shell is a standard Spring Shell application, any `@ShellComponent` bean is discovered and registered automatically by Spring.
+Because the Embabel Shell is a standard Spring Shell application, commands declared in any Spring `@Component` bean are discovered and registered automatically.
 
 Inject `AgentPlatform` and use `AgentInvocation` to call agents with strong typing:
 
@@ -134,15 +134,15 @@ Java::
 +
 [source,java]
 ----
-@ShellComponent
+@Component
 public record SupportAgentShellCommands(
         AgentPlatform agentPlatform
 ) {
 
-    @ShellMethod("Get bank support for a customer query")
+    @Command("Get bank support for a customer query")
     public String bankSupport(
-            @ShellOption(value = "id", help = "customer id", defaultValue = "123") Long id,
-            @ShellOption(value = "query", help = "customer query", defaultValue = "What's my balance, including pending amounts?") String query
+            @Option(longName = "id", description = "customer id", defaultValue = "123") Long id,
+            @Option(longName = "query", description = "customer query", defaultValue = "What's my balance, including pending amounts?") String query
     ) {
         var supportInput = new SupportInput(id, query);
         System.out.println("Support input: " + supportInput);
@@ -159,15 +159,15 @@ Kotlin::
 +
 [source,kotlin]
 ----
-@ShellComponent
+@Component
 class SupportAgentShellCommands(
     private val agentPlatform: AgentPlatform
 ) {
 
-    @ShellMethod("Get bank support for a customer query")
+    @Command("Get bank support for a customer query")
     fun bankSupport(
-        @ShellOption(value = ["id"], help = "customer id", defaultValue = "123") id: Long,
-        @ShellOption(value = ["query"], help = "customer query", defaultValue = "What's my balance, including pending amounts?") query: String
+        @Option(longName = "id", description = "customer id", defaultValue = "123") id: Long,
+        @Option(longName = "query", description = "customer query", defaultValue = "What's my balance, including pending amounts?") query: String
     ): String {
         val supportInput = SupportInput(id, query)
         println("Support input: $supportInput")
@@ -182,4 +182,4 @@ class SupportAgentShellCommands(
 ====
 
 TIP: Custom shell commands are particularly useful when you want to pre-populate inputs with test data or invoke a specific agent directly rather than relying on Autonomy's natural-language selection.
-For full `AgentInvocation` API details see <<reference.invoking>>.
+For full `AgentInvocation` API details see <<reference.invoking>>.

embabel-agent-shell/src/main/kotlin/com/embabel/agent/shell/ShellCommands.kt

@@ -38,16 +38,16 @@ import org.springframework.beans.factory.annotation.Autowired
 import org.springframework.boot.SpringApplication
 import org.springframework.context.ConfigurableApplicationContext
 import org.springframework.core.env.ConfigurableEnvironment
-import org.springframework.shell.standard.ShellComponent
-import org.springframework.shell.standard.ShellMethod
-import org.springframework.shell.standard.ShellOption
+import org.springframework.shell.core.command.annotation.Command
+import org.springframework.shell.core.command.annotation.Option
+import org.springframework.stereotype.Component
 import kotlin.system.exitProcess
 
 
 /**
  * Main shell entry point
  */
-@ShellComponent
+@Component
 class ShellCommands(
     private val autonomy: Autonomy,
     private val asyncer: Asyncer,
@@ -93,20 +93,21 @@ class ShellCommands(
         )
     )
 
-    @ShellMethod(value = "Clear blackboard")
+    @Command(description = "Clear blackboard")
     fun clear(): String {
         blackboard = null
         return "Blackboard cleared"
     }
 
-    @ShellMethod(
-        value = "Set persistent tool call context as key=value pairs, passed to all tools during execution. " +
+    @Command(
+        description = "Set persistent tool call context as key=value pairs, passed to all tools during execution. " +
                 "Example: set-context tenantId=acme,apiKey=secret123",
-        key = ["set-context", "sc"],
+        name = ["set-context"],
+        alias = ["sc"],
     )
     fun setContext(
-        @ShellOption(
-            help = "Comma-separated key=value pairs (e.g. tenantId=acme,apiKey=secret). Use 'clear' to reset.",
+        @Option(
+            description = "Comma-separated key=value pairs (e.g. tenantId=acme,apiKey=secret). Use 'clear' to reset.",
             defaultValue = "",
         ) context: String,
     ): String {
@@ -118,9 +119,9 @@ class ShellCommands(
         return "Tool call context set: ${persistentToolCallContext.toMap()}".color(colorPalette.color2)
     }
 
-    @ShellMethod(
-        value = "Show current tool call context",
-        key = ["show-context"],
+    @Command(
+        description = "Show current tool call context",
+        name = ["show-context"],
     )
     fun showContext(): String {
         val ctx = persistentToolCallContext.toMap()
@@ -131,7 +132,7 @@ class ShellCommands(
         }.color(colorPalette.color2)
     }
 
-    @ShellMethod(value = "Show recent agent process runs. This is what actually happened, not just what was planned.")
+    @Command(description = "Show recent agent process runs. This is what actually happened, not just what was planned.")
     fun runs(): String {
         val plans = agentProcesses.map {
             "[${it.id}] Goal: ${it.agent.goals.map { g -> g.name }}; usage - ${it.costInfoString(verbose = false)}\n\t\t" +
@@ -140,7 +141,7 @@ class ShellCommands(
         return "Recent runs:\n\t${plans.joinToString("\n\t")}"
     }
 
-    @ShellMethod(value = "List all active Spring profiles")
+    @Command(description = "List all active Spring profiles")
     fun profiles(): String {
         val profiles = environment.activeProfiles
         return "Active profiles: ${profiles.joinToString()}"
@@ -161,7 +162,7 @@ class ShellCommands(
             })
     }
 
-    @ShellMethod("Chat")
+    @Command("Chat")
     fun chat(): String {
 
         fun runChat(): String {
@@ -187,7 +188,7 @@ class ShellCommands(
         }
     }
 
-    @ShellMethod("List agents")
+    @Command("List agents")
     fun agents(): String {
         val detail = "${"Agents:".bold()}\n${
             agentPlatform.agents()
@@ -198,7 +199,7 @@ class ShellCommands(
         return detail + "\n\nTL;DR\n${agentPlatform.agents().joinToString("\n") { "${it.name}: ${it.description}" }}"
     }
 
-    @ShellMethod("List actions")
+    @Command("List actions")
     fun actions(): String {
         val detail = "${"Actions:".bold()}\n${
             agentPlatform.actions
@@ -207,25 +208,25 @@ class ShellCommands(
         return detail + "\n\nTL;DR\n${agentPlatform.actions.joinToString("\n") { "${it.name}: ${it.description}" }}"
     }
 
-    @ShellMethod("List conditions")
+    @Command("List conditions")
     fun conditions(): String {
         return "${"Conditions:".bold()}\n${
             agentPlatform.conditions
                 .joinToString(separator = "\n") { it.infoString(verbose = true, indent = 1) }
         }"
     }
 
-    @ShellMethod("List goals")
+    @Command("List goals")
     fun goals(): String {
         return "${"Goals:".bold()}\n${
             agentPlatform.goals
                 .joinToString(separator = "\n") { it.infoString(verbose = true, indent = 1) }
         }"
     }
 
-    @ShellMethod("Try to choose a goal for a given intent. Show all goal rankings")
+    @Command("Try to choose a goal for a given intent. Show all goal rankings")
     fun chooseGoal(
-        @ShellOption(help = "what the agent system should do") intent: String,
+        @Option(description = "what the agent system should do") intent: String,
     ): String {
         try {
             val goalSeeker = autonomy.createGoalSeeker(
@@ -245,21 +246,22 @@ class ShellCommands(
         }
     }
 
-    @ShellMethod("Information about the AgentPlatform")
+    @Command("Information about the AgentPlatform")
     fun platform(): String = "AgentPlatform: ${agentPlatform.name}"
 
 
-    @ShellMethod(
+    @Command(
         "Show last blackboard: The final state of a previous operation",
-        key = ["blackboard", "bb"],
+        name = ["blackboard"],
+        alias = ["bb"],
     )
     fun blackboard(): String {
         return if (blackboard == null) {
             "No blackboard available. Please run a command first."
         } else blackboard!!.infoString(verbose = true)
     }
 
-    @ShellMethod("List available tool groups")
+    @Command("List available tool groups")
     fun tools(): String {
         val tgr = agentPlatform.toolGroupResolver
         return String.format(
@@ -275,16 +277,16 @@ class ShellCommands(
         )
     }
 
-    @ShellMethod("Show tool stats")
+    @Command("Show tool stats")
     fun toolStats(): String {
         return toolsStats.infoString(verbose = true)
     }
 
-    @ShellMethod("List available models")
+    @Command("List available models")
     fun models(): String =
         modelProvider.infoString(true)
 
-    @ShellMethod("Show options")
+    @Command("Show options")
     fun showOptions(): String {
         // Don't show the blackboard as it's long
         return embabelObjectMapperHolder.get().writerWithDefaultPrettyPrinter().writeValueAsString(
@@ -298,24 +300,26 @@ class ShellCommands(
             .color(colorPalette.color2)
     }
 
-    @ShellMethod(
+    @Command(
         "Set options",
     )
     fun setOptions(
-        @ShellOption(
-            value = ["-o", "--open"],
-            help = "run in open mode, choosing a goal and using all actions that can help achieve it",
+        @Option(
+            shortName = 'o',
+            longName = "open",
+            description = "run in open mode, choosing a goal and using all actions that can help achieve it",
         ) open: Boolean = false,
-        @ShellOption(value = ["-t", "--test"], help = "run in help mode") test: Boolean = false,
-        @ShellOption(value = ["-p", "--showPrompts"], help = "show prompts to LLMs") showPrompts: Boolean,
-        @ShellOption(value = ["-r", "--showResponses"], help = "show LLM responses") showLlmResponses: Boolean = false,
-        @ShellOption(value = ["-d", "--debug"], help = "show debug info") debug: Boolean = false,
-        @ShellOption(value = ["-s", "--state"], help = "Use existing blackboard") state: Boolean = false,
-        @ShellOption(value = ["-td", "--toolDelay"], help = "Tool delay") toolDelay: Boolean = false,
-        @ShellOption(value = ["-od", "--operationDelay"], help = "Operation delay") operationDelay: Boolean = false,
-        @ShellOption(
-            value = ["-s", "--showPlanning"],
-            help = "show detailed planning info",
+        @Option(shortName = 't', longName = "test", description = "run in help mode") test: Boolean = false,
+        @Option(shortName = 'p', longName = "showPrompts", description = "show prompts to LLMs") showPrompts: Boolean,
+        @Option(shortName = 'r', longName = "showResponses", description = "show LLM responses") showLlmResponses: Boolean = false,
+        @Option(shortName = 'd', longName = "debug", description = "show debug info") debug: Boolean = false,
+        @Option(shortName = 's', longName = "state", description = "Use existing blackboard") state: Boolean = false,
+        @Option(longName = "toolDelay", description = "Tool delay") toolDelay: Boolean = false,
+        @Option(longName = "operationDelay", description = "Operation delay") operationDelay: Boolean = false,
+        @Option(
+            shortName = 'P',
+            longName = "showPlanning",
+            description = "show detailed planning info",
             defaultValue = "true",
         ) showPlanning: Boolean = true,
     ): String {
@@ -338,32 +342,35 @@ class ShellCommands(
         return "Options updated:\nOpen mode:$openMode\n${showOptions()}".color(colorPalette.color2)
     }
 
-    @ShellMethod(
+    @Command(
         "Execute a task. Put the task in double quotes. For example:\n\tx \"Lynda is a scorpio. Find news for her\" -p",
-        key = ["execute", "x"],
+        name = ["execute"],
+        alias = ["x"],
     )
     fun execute(
-        @ShellOption(help = "what the agent system should do") intent: String,
-        @ShellOption(
-            value = ["-o", "--open"],
-            help = "run in open mode, choosing a goal and using all actions that can help achieve it",
+        @Option(description = "what the agent system should do") intent: String,
+        @Option(
+            shortName = 'o',
+            longName = "open",
+            description = "run in open mode, choosing a goal and using all actions that can help achieve it",
         ) open: Boolean = false,
-        @ShellOption(value = ["-p", "--showPrompts"], help = "show prompts to LLMs") showPrompts: Boolean,
-        @ShellOption(value = ["-r", "--showResponses"], help = "show LLM responses") showLlmResponses: Boolean = false,
-        @ShellOption(value = ["-d", "--debug"], help = "show debug info") debug: Boolean = false,
-        @ShellOption(value = ["-s", "--state"], help = "Use existing blackboard") state: Boolean = false,
-        @ShellOption(value = ["-td", "--toolDelay"], help = "Tool delay") toolDelay: Boolean = false,
-        @ShellOption(value = ["-od", "--operationDelay"], help = "Operation delay") operationDelay: Boolean = false,
-        @ShellOption(
-            value = ["-P", "--showPlanning"],
-            help = "show detailed planning info",
+        @Option(shortName = 'p', longName = "showPrompts", description = "show prompts to LLMs") showPrompts: Boolean,
+        @Option(shortName = 'r', longName = "showResponses", description = "show LLM responses") showLlmResponses: Boolean = false,
+        @Option(shortName = 'd', longName = "debug", description = "show debug info") debug: Boolean = false,
+        @Option(shortName = 's', longName = "state", description = "Use existing blackboard") state: Boolean = false,
+        @Option(longName = "toolDelay", description = "Tool delay") toolDelay: Boolean = false,
+        @Option(longName = "operationDelay", description = "Operation delay") operationDelay: Boolean = false,
+        @Option(
+            shortName = 'P',
+            longName = "showPlanning",
+            description = "show detailed planning info",
             defaultValue = "true",
         ) showPlanning: Boolean = true,
-        @ShellOption(
-            value = ["-c", "--context"],
-            help = "Tool call context as comma-separated key=value pairs (e.g. tenantId=acme,apiKey=secret). " +
+        @Option(
+            shortName = 'c',
+            longName = "context",
+            description = "Tool call context as comma-separated key=value pairs (e.g. tenantId=acme,apiKey=secret). " +
                     "Merged with persistent context set via set-context; these values win on conflict.",
-            defaultValue = ShellOption.NULL,
         ) context: String? = null,
     ): String {
         // Override any options
@@ -398,7 +405,7 @@ class ShellCommands(
         )
     }
 
-    @ShellMethod(value = "Exit the application", key = ["exit", "quit", "bye"])
+    @Command(description = "Exit the application", name = ["exit"], alias = ["quit", "bye"])
     fun exit(): String {
         println("Exiting...".color(colorPalette.color2))
         logger.info("Shutting down application...")

embabel-agent-starters/embabel-agent-starter-shell/README.md

@@ -158,7 +158,7 @@ fun main(args: Array<String>) {
 
 1. **Auto-Configuration**: `AgentShellAutoConfiguration` activates when the starter is present
 2. **Component Scanning**: Shell commands and services are discovered via `@ComponentScan`
-3. **Spring Shell Integration**: Commands are registered as `@ShellComponent` beans
+3. **Spring Shell Integration**: Commands are registered from Spring `@Component` beans
 4. **Agent Platform Access**: Shell commands interact with the `Autonomy` and `AgentPlatform` APIs
 
 ## Architecture