@trim21/personal-pi-extensions 0.0.209 → 0.0.210

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.209",
+  "version": "0.0.210",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/index.ts

@@ -62,11 +62,12 @@ import { access as fsAccess } from "node:fs/promises";
 import { delimiter, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import { type BashOperations, createBashTool, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
+import { type TObject, Type } from "typebox";
 import { Value } from "typebox/value";
 
+import { type CommandSpec, parseCommand } from "../lib/cli.js";
 import { expandHome } from "../lib/path.js";
 
 const SANDBOX_PROMPT = `
@@ -711,25 +712,80 @@ export default function bwrapExtension(pi: ExtensionAPI) {
     };
   });
 
-  pi.registerCommand("bwrap", {
+  const BWRAP_SPEC = {
+    name: "bwrap",
+    usage: "",
     description: "Show bwrap sandbox configuration",
-    handler: (_args, ctx) => {
-      const r = getResolved(ctx.hasUI);
-      if (!r.bwrapEnabled) {
-        ctx.ui.notify(`bwrap disabled (mode: ${r.mode})`, "info");
-        return Promise.resolve();
-      }
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const BWRAP_ALLOW_ALL_SPEC = {
+    name: "bwrap-allow-all",
+    usage: "",
+    description: "Disable bwrap sandbox, full access",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
 
-      const net = r.network ? "net" : "no-net";
-      const w = r.writablePaths.map((p) => resolvePath(p, localCwd));
-      const t = r.tmpfsPaths.map((p) => resolvePath(p, localCwd));
+  const BWRAP_WORKSPACE_WRITE_SPEC = {
+    name: "bwrap-workspace-write",
+    usage: "",
+    description: "Sandbox on, network off, workspace writable",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
 
-      ctx.ui.notify(
-        `bwrap ${r.mode} ${net} write:[${w.join(", ")}] tmpfs:[${t.join(", ") || "-"}]`,
-        "info",
-      );
+  const BWRAP_ALLOW_NET_SPEC = {
+    name: "bwrap-allow-net",
+    usage: "",
+    description: "Sandbox on, network on, workspace writable",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const BWRAP_READONLY_SPEC = {
+    name: "bwrap-readonly",
+    usage: "",
+    description: "Sandbox on, network off, no writes",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  /** Parse a /bwrap command; on help/error the text is sent to the session, otherwise run() executes. */
+  function runBwrapCommand(
+    spec: CommandSpec<TObject>,
+    args: string,
+    ctx: ExtensionCommandContext,
+    run: (ctx: ExtensionCommandContext) => void | Promise<void>,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: "info", content: parsed.text, display: true });
       return Promise.resolve();
-    },
+    }
+    return Promise.resolve(run(ctx));
+  }
+
+  pi.registerCommand("bwrap", {
+    description: BWRAP_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_SPEC, args, ctx, (c) => {
+        const r = getResolved(c.hasUI);
+        if (!r.bwrapEnabled) {
+          c.ui.notify(`bwrap disabled (mode: ${r.mode})`, "info");
+          return;
+        }
+
+        const net = r.network ? "net" : "no-net";
+        const w = r.writablePaths.map((p) => resolvePath(p, localCwd));
+        const t = r.tmpfsPaths.map((p) => resolvePath(p, localCwd));
+
+        c.ui.notify(
+          `bwrap ${r.mode} ${net} write:[${w.join(", ")}] tmpfs:[${t.join(", ") || "-"}]`,
+          "info",
+        );
+      }),
   });
 
   function switchMode(
@@ -760,22 +816,28 @@ export default function bwrapExtension(pi: ExtensionAPI) {
   }
 
   pi.registerCommand("bwrap-allow-all", {
-    description: "Disable bwrap sandbox, full access",
-    handler: (_args, ctx) => Promise.resolve(switchMode("allow-all", ctx)),
+    description: BWRAP_ALLOW_ALL_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_ALLOW_ALL_SPEC, args, ctx, (c) => switchMode("allow-all", c)),
   });
 
   pi.registerCommand("bwrap-workspace-write", {
-    description: "Sandbox on, network off, workspace writable",
-    handler: (_args, ctx) => Promise.resolve(switchMode("workspace-write", ctx)),
+    description: BWRAP_WORKSPACE_WRITE_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_WORKSPACE_WRITE_SPEC, args, ctx, (c) =>
+        switchMode("workspace-write", c),
+      ),
   });
 
   pi.registerCommand("bwrap-allow-net", {
-    description: "Sandbox on, network on, workspace writable",
-    handler: (_args, ctx) => Promise.resolve(switchMode("allow-net", ctx)),
+    description: BWRAP_ALLOW_NET_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_ALLOW_NET_SPEC, args, ctx, (c) => switchMode("allow-net", c)),
   });
 
   pi.registerCommand("bwrap-readonly", {
-    description: "Sandbox on, network off, no writes",
-    handler: (_args, ctx) => Promise.resolve(switchMode("readonly", ctx)),
+    description: BWRAP_READONLY_SPEC.description,
+    handler: (args, ctx) =>
+      runBwrapCommand(BWRAP_READONLY_SPEC, args, ctx, (c) => switchMode("readonly", c)),
   });
 }

package/src/lib/cli.ts

@@ -0,0 +1,340 @@
+/**
+ * Declarative command-line parsing for `/command` handlers.
+ *
+ * The shell-like tokenizer from `cli-args.ts` splits the raw argument string;
+ * this module parses the tokens into positional args plus typed flags. Flags
+ * are declared as a typebox object schema: each property is a flag and the
+ * property key is the long name (`--key`). The property schema decides the
+ * flag kind:
+ *
+ *   Type.Boolean()                    boolean flag (`--flag`)
+ *   Type.String()                     string value flag (`--flag value`)
+ *   Type.Number() / Type.Integer()    number value flag (value is coerced)
+ *   Type.Union([Type.Literal(...)])   string enum value flag (validated)
+ *
+ * Supported syntax (common unix CLI conventions):
+ *
+ *   -s            short boolean flag
+ *   -s value      short flag with value (also `-s=value` and `-svalue`)
+ *   -abc          combined short boolean flags
+ *   --long        long boolean flag
+ *   --long=value  long flag with inline value
+ *   --long value  long flag consuming the next token
+ *   --            everything after is a positional
+ *
+ * `Type.Optional(...)` marks a flag optional (no error when absent) and a
+ * `default` fills in a missing value; both flow through typebox's value
+ * pipeline (default → convert → check) so the `ok` result carries
+ * `Static<TFlags>` flags plus `string[]` args.
+ *
+ * `-h`/`--help` is registered automatically unless the schema declares a
+ * `help` property or a short `h` alias; it renders a usage/options text as
+ * the result so handlers can display it in chat instead of writing stdout.
+ */
+
+import type { Static, TObject } from "typebox";
+import { Value } from "typebox/value";
+
+import { shlexSplit } from "./cli-args.js";
+
+/** Per-flag CLI metadata on top of the typebox schema. */
+export interface FlagMeta {
+  /** Optional short alias (single character), e.g. "n" for `-n`. */
+  short?: string;
+  /** Help line for this flag; defaults to the schema `description`. */
+  description?: string;
+  /** Placeholder shown for value flags in help, e.g. "<alias>"; defaults to `<key>`. */
+  valuePlaceholder?: string;
+}
+
+export interface CommandSpec<TFlags extends TObject> {
+  /** Command name used in usage/help, e.g. "talk-group-join". */
+  name: string;
+  /** Usage text after the command name, e.g. "[group name] [options]". */
+  usage: string;
+  /** One-line description shown under the usage line. */
+  description?: string;
+  /** Typebox object schema describing the flags (key = long flag name). */
+  flags: TFlags;
+  /** Per-flag CLI metadata (short alias, help text). */
+  flagMeta?: { [K in keyof Static<TFlags>]?: FlagMeta };
+  /** Positional count constraints. */
+  arity?: { min?: number; max?: number };
+  /** Example lines rendered under the help text. */
+  examples?: string[];
+}
+
+export type CommandResult<TFlags extends TObject> =
+  | { kind: "ok"; flags: Static<TFlags>; args: string[] }
+  | { kind: "help"; text: string }
+  | { kind: "error"; text: string };
+
+/** Runtime view of a flag schema (typebox's `TSchema` is empty at the type level). */
+interface FlagSchema {
+  "~kind"?: string;
+  "~optional"?: boolean;
+  type?: string;
+  default?: unknown;
+  description?: string;
+  anyOf?: { type?: string; const?: unknown }[];
+}
+
+type FlagKind = "boolean" | "string" | "number" | "enum";
+
+interface FlagInfo {
+  key: string;
+  kind: FlagKind;
+  short?: string;
+  required: boolean;
+  placeholder: string;
+  description: string;
+  schema: FlagSchema;
+}
+
+function kindOf(key: string, schema: FlagSchema): FlagKind {
+  switch (schema["~kind"]) {
+    case "Boolean": {
+      return "boolean";
+    }
+    case "String": {
+      return "string";
+    }
+    case "Number":
+    case "Integer": {
+      return "number";
+    }
+    case "Union": {
+      return "enum";
+    }
+    default: {
+      throw new TypeError(
+        `Unsupported flag type for '${key}': ${schema["~kind"] ?? schema.type ?? "unknown"} ` +
+          "(use Type.Boolean/String/Number/Integer or a string literal union)",
+      );
+    }
+  }
+}
+
+/** Allowed values for a string-literal union flag, or undefined for mixed unions. */
+function enumValues(schema: FlagSchema): string[] | undefined {
+  const anyOf = schema.anyOf;
+  if (!anyOf) return undefined;
+  const values = anyOf.map((s) => s.const).filter((c) => typeof c === "string");
+  return values.length === anyOf.length ? values : undefined;
+}
+
+function buildFlagInfos<TFlags extends TObject>(spec: CommandSpec<TFlags>): FlagInfo[] {
+  const meta = spec.flagMeta as Record<string, FlagMeta> | undefined;
+  const infos: FlagInfo[] = [];
+  for (const [key, rawSchema] of Object.entries(spec.flags.properties)) {
+    const schema = rawSchema as unknown as FlagSchema;
+    const m = meta?.[key];
+    infos.push({
+      key,
+      kind: kindOf(key, schema),
+      short: m?.short,
+      required: schema["~optional"] !== true && schema.default === undefined,
+      placeholder: m?.valuePlaceholder ?? `<${key}>`,
+      description: m?.description ?? schema.description ?? "",
+      schema,
+    });
+  }
+  return infos;
+}
+
+/** Is this token a flag-like argument (a negative number is a value)? */
+function looksLikeFlag(token: string): boolean {
+  return token.startsWith("-") && !/^-\d/.test(token);
+}
+
+function errorResult<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  message: string,
+): CommandResult<TFlags> {
+  return { kind: "error", text: `${message}\nTry '/${spec.name} --help' for usage.` };
+}
+
+function helpResult<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  flags: FlagInfo[],
+  autoHelp: boolean,
+): CommandResult<TFlags> {
+  const lines = [`Usage: /${spec.name} ${spec.usage}`];
+  if (spec.description) lines.push("", spec.description);
+  const rows = flags.map((f) => ({
+    rawName:
+      (f.short ? `-${f.short}, ` : "") +
+      `--${f.key}` +
+      (f.kind === "boolean" ? "" : ` ${f.placeholder}`),
+    description: f.description,
+  }));
+  if (autoHelp) rows.push({ rawName: "-h, --help", description: "Display this message" });
+  if (rows.length > 0) {
+    lines.push("", "Options:");
+    const width = Math.max(...rows.map((r) => r.rawName.length));
+    for (const r of rows) lines.push(`  ${r.rawName.padEnd(width)}  ${r.description}`);
+  }
+  if (spec.examples?.length) {
+    lines.push("", "Examples:");
+    for (const e of spec.examples) lines.push(`  ${e}`);
+  }
+  return { kind: "help", text: lines.join("\n") };
+}
+
+export function parseCommand<TFlags extends TObject>(
+  spec: CommandSpec<TFlags>,
+  raw: string,
+): CommandResult<TFlags> {
+  const flags = buildFlagInfos(spec);
+  const byLong = new Map(flags.map((f) => [f.key, f]));
+  const byShort = new Map<string, FlagInfo>();
+  for (const f of flags) {
+    if (!f.short) {
+      continue;
+    }
+
+    if (byShort.has(f.short)) {
+      throw new TypeError(`Duplicate short option '-${f.short}' in /${spec.name}`);
+    }
+    byShort.set(f.short, f);
+  }
+  const autoHelp = !byLong.has("help") && !byShort.has("h");
+
+  let tokens: string[];
+  try {
+    tokens = shlexSplit(raw);
+  } catch (error) {
+    return errorResult(spec, error instanceof Error ? error.message : String(error));
+  }
+
+  const rawFlags: Record<string, unknown> = {};
+  const args: string[] = [];
+  let positionalOnly = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (positionalOnly) {
+      args.push(token);
+      continue;
+    }
+    if (token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (token === "-") {
+      args.push(token);
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const body = token.slice(2);
+      const eq = body.indexOf("=");
+      const name = eq === -1 ? body : body.slice(0, eq);
+      if (autoHelp && name === "help") return helpResult(spec, flags, autoHelp);
+      const info = byLong.get(name);
+      if (!info) return errorResult(spec, `Unknown option '--${name}'`);
+      const inline = eq === -1 ? undefined : body.slice(eq + 1);
+      if (inline !== undefined) {
+        rawFlags[info.key] = inline;
+      } else if (info.kind === "boolean") {
+        rawFlags[info.key] = true;
+      } else {
+        const next = tokens[i + 1];
+        if (next !== undefined && !looksLikeFlag(next)) {
+          rawFlags[info.key] = next;
+          i++;
+        } else if (autoHelp && next !== undefined && (next === "--help" || next === "-h")) {
+          return helpResult(spec, flags, autoHelp);
+        } else {
+          return errorResult(spec, `Option '--${name}' requires a value`);
+        }
+      }
+      continue;
+    }
+    if (token.startsWith("-")) {
+      const rest = token.slice(1);
+      for (let j = 0; j < rest.length; j++) {
+        const c = rest[j];
+        if (autoHelp && c === "h") return helpResult(spec, flags, autoHelp);
+        const info = byShort.get(c);
+        if (!info) return errorResult(spec, `Unknown option '-${c}'`);
+        if (info.kind === "boolean") {
+          rawFlags[info.key] = true;
+          continue;
+        }
+        if (rest[j + 1] === "=") {
+          rawFlags[info.key] = rest.slice(j + 2);
+        } else if (j + 1 < rest.length) {
+          rawFlags[info.key] = rest.slice(j + 1);
+        } else {
+          const next = tokens[i + 1];
+          if (next !== undefined && !looksLikeFlag(next)) {
+            rawFlags[info.key] = next;
+            i++;
+          } else if (autoHelp && next !== undefined && (next === "--help" || next === "-h")) {
+            return helpResult(spec, flags, autoHelp);
+          } else {
+            return errorResult(spec, `Option '-${c}' requires a value`);
+          }
+        }
+        break;
+      }
+      continue;
+    }
+    args.push(token);
+  }
+
+  for (const f of flags) {
+    if (f.required && !(f.key in rawFlags)) {
+      return errorResult(spec, `Missing required option '--${f.key}'`);
+    }
+  }
+
+  for (const f of flags) {
+    if (f.kind === "enum" && typeof rawFlags[f.key] === "string") {
+      const values = enumValues(f.schema);
+      if (values && !values.includes(rawFlags[f.key] as string)) {
+        return errorResult(
+          spec,
+          `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}' (expected one of: ${values.join(", ")})`,
+        );
+      }
+    }
+    if (f.kind === "number" && typeof rawFlags[f.key] === "string") {
+      const n = Number(rawFlags[f.key]);
+      if (Number.isNaN(n)) {
+        return errorResult(spec, `Invalid value for '--${f.key}': '${String(rawFlags[f.key])}'`);
+      }
+      rawFlags[f.key] = n;
+    }
+  }
+
+  const { min, max } = spec.arity ?? {};
+  if (max !== undefined && args.length > max) {
+    const extra = args
+      .slice(max)
+      .map((a) => `'${a}'`)
+      .join(", ");
+    return errorResult(spec, `Too many arguments: ${extra} (expected at most ${max})`);
+  }
+  if (min !== undefined && args.length < min) {
+    return errorResult(spec, `Missing required argument: expected ${spec.usage}`);
+  }
+
+  // typebox value pipeline: defaults → coercion → check.
+  let parsed: unknown;
+  try {
+    parsed = Value.Default(spec.flags, rawFlags);
+    parsed = Value.Convert(spec.flags, Value.Clone(parsed));
+    if (!Value.Check(spec.flags, parsed)) {
+      const [first] = [...Value.Errors(spec.flags, parsed)];
+      return errorResult(
+        spec,
+        `Invalid arguments: ${first?.message ?? "value does not match flags"}`,
+      );
+    }
+  } catch {
+    return errorResult(spec, "Invalid arguments");
+  }
+
+  return { kind: "ok", flags: parsed, args };
+}

package/src/talk/index.ts

@@ -16,9 +16,9 @@ import { fileURLToPath } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Box, Text } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
+import { type TObject, Type } from "typebox";
 
-import { parseArgs } from "../lib/cli-args.js";
+import { type CommandResult, type CommandSpec, parseCommand } from "../lib/cli.js";
 import { resolveHomePath } from "../lib/path.js";
 import { TalkCore } from "./core.js";
 import { formatDelivery } from "./format.js";
@@ -281,92 +281,155 @@ export default function talk(pi: ExtensionAPI) {
 
   // ── /talk commands ────────────────────────────────────────────────────
 
-  pi.registerCommand("talk", {
-    description: "List registered pi agents",
-    async handler() {
-      const text = requireInit() ?? (await core.list());
+  type OkResult<TFlags extends TObject> = Extract<CommandResult<TFlags>, { kind: "ok" }>;
+
+  /** Parse a /talk command; on help/error or init failure the text is sent, otherwise run() produces the listing text. */
+  function handleCommand<TFlags extends TObject>(
+    spec: CommandSpec<TFlags>,
+    args: string,
+    run: (parsed: OkResult<TFlags>) => Promise<string> | string,
+  ): Promise<void> {
+    const parsed = parseCommand(spec, args);
+    if (parsed.kind !== "ok") {
+      pi.sendMessage({ customType: LIST_TYPE, content: parsed.text, display: true });
+      return Promise.resolve();
+    }
+    return (async () => {
+      const initError = requireInit();
+      const text = initError ?? (await run(parsed));
       pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
-  });
+    })();
+  }
 
-  pi.registerCommand("talk-dead", {
+  const TALK_SPEC = {
+    name: "talk",
+    usage: "",
+    description: "List registered pi agents",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_DEAD_SPEC = {
+    name: "talk-dead",
+    usage: "[agentId] [options]",
     description:
       "Mark a talk agent as dead (shown offline, swept soon): no arg = this agent, <agentId> = that agent, --all = every other visible agent",
-    async handler(args) {
-      const initError = requireInit();
-      const trimmed = args.trim();
-      const text =
-        initError ??
-        (trimmed === "--all"
+    flags: Type.Object({
+      all: Type.Optional(Type.Boolean({ description: "Mark every other visible agent dead" })),
+    }),
+    flagMeta: { all: { short: "a" } },
+    arity: { max: 1 },
+  };
+
+  const TALK_GROUP_JOIN_SPEC = {
+    name: "talk-group-join",
+    usage: "[group name] [options]",
+    description:
+      "Join or create a private agent group (members see only each other; an agent in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist; --name <alias> additionally sets this agent's display name",
+    flags: Type.Object({
+      name: Type.Optional(Type.String({ description: "Set this agent's display name" })),
+    }),
+    flagMeta: { name: { short: "n", valuePlaceholder: "<alias>" } },
+    arity: { max: 1 },
+    examples: ["/talk-group-join frontend", "/talk-group-join --name frontend"],
+  };
+
+  const TALK_GROUP_JOIN_LAST_SPEC = {
+    name: "talk-group-join-last",
+    usage: "",
+    description: "Join the most recently created agent group (no-op when already in it).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LEAVE_SPEC = {
+    name: "talk-group-leave",
+    usage: "",
+    description: "Leave the current agent group (an emptied group is deleted).",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_LIST_SPEC = {
+    name: "talk-group-list",
+    usage: "",
+    description: "List all agent groups and their members, newest first.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  const TALK_GROUP_DEL_SPEC = {
+    name: "talk-group-del",
+    usage: "<group name>",
+    description:
+      "Delete an agent group by name; its members become ungrouped (see only themselves).",
+    flags: Type.Object({}),
+    arity: { min: 1, max: 1 },
+  };
+
+  const TALK_GROUP_CLEAR_SPEC = {
+    name: "talk-group-clear",
+    usage: "",
+    description: "Delete every agent group; all agents become ungrouped.",
+    flags: Type.Object({}),
+    arity: { max: 0 },
+  };
+
+  pi.registerCommand("talk", {
+    description: TALK_SPEC.description,
+    handler: (args) => handleCommand(TALK_SPEC, args, async () => core.list()),
+  });
+
+  pi.registerCommand("talk-dead", {
+    description: TALK_DEAD_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_DEAD_SPEC, args, async (parsed) => {
+        if (parsed.flags.all && parsed.args.length > 0) {
+          return "--all cannot be combined with an agent id.\nTry '/talk-dead --help' for usage.";
+        }
+        return parsed.flags.all
           ? await core.markAllDead()
-          : trimmed
-            ? await core.markDead(trimmed)
-            : await core.markDead());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+          : parsed.args[0]
+            ? await core.markDead(parsed.args[0])
+            : await core.markDead();
+      }),
   });
 
   pi.registerCommand("talk-group-join", {
-    description:
-      "Join or create a private agent group (members see only each other; an agent in no group sees only itself). No arg = new group with a generated uuid; <name> = join that group, or create it when it does not exist; --name <alias> additionally sets this agent's display name (e.g. --name frontend)",
-    async handler(args) {
-      const initError = requireInit();
-      const parsed = parseArgs(args);
-      const groupName = parsed.positionals[0];
-      const flag = parsed.flags.name;
-      const agentName = typeof flag === "string" && flag.trim() !== "" ? flag.trim() : undefined;
-      if (agentName !== undefined) explicitName = agentName;
-      const text = initError ?? (await core.groupJoin(groupName || undefined, agentName));
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_JOIN_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_SPEC, args, async (parsed) => {
+        const agentName = parsed.flags.name?.trim() || undefined;
+        if (agentName !== undefined) explicitName = agentName;
+        return core.groupJoin(parsed.args[0], agentName);
+      }),
   });
 
   pi.registerCommand("talk-group-join-last", {
-    description: "Join the most recently created agent group (no-op when already in it).",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupJoinLast());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_JOIN_LAST_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_JOIN_LAST_SPEC, args, async () => core.groupJoinLast()),
   });
 
   pi.registerCommand("talk-group-leave", {
-    description: "Leave the current agent group (an emptied group is deleted).",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupLeave());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_LEAVE_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LEAVE_SPEC, args, async () => core.groupLeave()),
   });
 
   pi.registerCommand("talk-group-list", {
-    description: "List all agent groups and their members, newest first.",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupList());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_LIST_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_LIST_SPEC, args, async () => core.groupList()),
   });
 
   pi.registerCommand("talk-group-del", {
-    description:
-      "Delete an agent group by name; its members become ungrouped (see only themselves).",
-    async handler(args) {
-      const initError = requireInit();
-      const name = args.trim();
-      const text =
-        initError ?? (name ? await core.groupDelete(name) : "Usage: /talk-group-del <group name>");
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_DEL_SPEC.description,
+    handler: (args) =>
+      handleCommand(TALK_GROUP_DEL_SPEC, args, async (parsed) => core.groupDelete(parsed.args[0])),
   });
 
   pi.registerCommand("talk-group-clear", {
-    description: "Delete every agent group; all agents become ungrouped.",
-    async handler() {
-      const initError = requireInit();
-      const text = initError ?? (await core.groupClear());
-      pi.sendMessage({ customType: LIST_TYPE, content: text, display: true });
-    },
+    description: TALK_GROUP_CLEAR_SPEC.description,
+    handler: (args) => handleCommand(TALK_GROUP_CLEAR_SPEC, args, async () => core.groupClear()),
   });
 
   // ── Delivery card ──────────────────────────────────────────────────────