feat: close AgentRun commander task plane gaps

scripts/src/cli.ts

@@ -1,6 +1,6 @@
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { spawn } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
 import { closeSync, existsSync, openSync } from "node:fs";
 import path from "node:path";
 import { startManagerServer } from "../../src/mgr/server.js";
@@ -33,7 +33,10 @@ export async function runCli(argv: string[]): Promise<void> {
 
 async function dispatch(args: ParsedArgs): Promise<JsonValue> {
   const [group, command, id] = args.positional;
-  if (!group || group === "help") return help();
+  if (!group || group === "help" || group === "--help") return help(args);
+  if (args.flags.get("help") === true) return help(args, group);
+  if (command === "help" || command === "--help") return help(args, group);
+  if (group === "manager" && (command === "url" || command === "resolve-url" || command === "status")) return managerEndpoint(args);
   if (group === "server" && command === "start") return startServer(args);
   if (group === "server" && command === "status") return serverStatus(args);
   if (group === "server" && command === "logs") return serverLogs(args);
@@ -556,7 +559,40 @@ function client(args: ParsedArgs): ManagerClient {
 }
 
 function managerUrl(args: ParsedArgs): string {
-  return optionalFlag(args, "manager-url") ?? process.env.AGENTRUN_MGR_URL ?? "http://127.0.0.1:8080";
+  const explicit = optionalFlag(args, "manager-url") ?? process.env.AGENTRUN_MGR_URL;
+  if (explicit && explicit !== "auto") return explicit;
+  if (explicit === "auto") return resolveRuntimeManagerUrl();
+  return "http://127.0.0.1:8080";
+}
+
+function managerEndpoint(args: ParsedArgs): JsonRecord {
+  const url = managerUrl(args);
+  const explicit = optionalFlag(args, "manager-url") ?? process.env.AGENTRUN_MGR_URL ?? null;
+  return {
+    action: "manager-endpoint",
+    managerUrl: url,
+    source: explicit === "auto" ? "auto" : explicit ? (optionalFlag(args, "manager-url") ? "--manager-url" : "AGENTRUN_MGR_URL") : "default-localhost",
+    runtimeNamespace: "agentrun-v01",
+    serviceName: "agentrun-mgr",
+    valuesPrinted: false,
+    examples: {
+      commander: "./scripts/agentrun --manager-url auto queue commander",
+      sessions: "./scripts/agentrun --manager-url auto sessions ps --state default --reader-id cli",
+      explicit: "./scripts/agentrun --manager-url http://<reachable-host>:8080 queue commander",
+    },
+  };
+}
+
+function resolveRuntimeManagerUrl(): string {
+  const fromEnv = process.env.AGENTRUN_RUNTIME_MANAGER_URL;
+  if (fromEnv) return fromEnv;
+  try {
+    const serviceIp = execFileSync("kubectl", ["-n", "agentrun-v01", "get", "svc", "agentrun-mgr", "-o", "jsonpath={.spec.clusterIP}"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    if (serviceIp.length > 0 && serviceIp !== "None") return `http://${serviceIp}:8080`;
+  } catch {
+    // Fall through to localhost so the following request produces a structured connection failure.
+  }
+  return "http://127.0.0.1:8080";
 }
 
 function portFromManagerUrl(args: ParsedArgs): string {
@@ -758,9 +794,8 @@ function cancelBody(args: ParsedArgs): JsonRecord {
   return reason ? { reason } : {};
 }
 
-function help(): JsonRecord {
-  return {
-    commands: [
+function help(args: ParsedArgs, group?: string): JsonRecord {
+  const commands = [
       "runs create --json-file <run.json>",
       "runs show <runId>",
       "runs events <runId> --after-seq <n> --limit <n>",
@@ -808,7 +843,16 @@ function help(): JsonRecord {
       "server status [--port <port>]",
       "server logs [--port <port>] [--tail-bytes <bytes>] [--log-file <path>]",
       "server stop [--port <port>]",
-    ],
+    ];
+  if (group) {
+    const prefix = `${group} `;
+    const groupCommands = commands.filter((item) => item === group || item.startsWith(prefix));
+    return { group, commands: groupCommands, commandCount: groupCommands.length, supported: groupCommands.length > 0, manager: managerEndpoint(args) };
+  }
+  return {
+    groups: [...new Set(commands.map((item) => item.split(" ")[0]).filter(Boolean))].sort(),
+    commands,
+    manager: managerEndpoint(args),
   };
 }