@hydra-acp/cli 0.1.5 → 0.1.6

package/README.md

@@ -178,7 +178,7 @@ hydra-acp daemon start
 #    spawned-by-editor cases where stdio is already piped. The first
 #    session/new asks the daemon which agent to spawn (defaults to
 #    config.defaultAgent). If you'd rather the editor pin a specific agent,
-#    spawn `hydra-acp launch <agent-id>` (see "Launcher mode" below).
+#    spawn `hydra-acp launch <agent>` (see "Launcher mode" below).
 
 # 4. From a terminal, drive a session interactively (TUI).
 hydra-acp                                   # bare invocation in a TTY launches the TUI
@@ -198,8 +198,8 @@ hydra-acp --session-id hydra_session_abc123
 hydra-acp                                   # auto-dispatch: TUI in a TTY, shim when stdio is piped
 hydra-acp shim                              # explicit shim mode (forces shim regardless of TTY)
 hydra-acp tui                               # explicit terminal-UI mode
-hydra-acp launch <agent-id>                 # launcher mode: shim that forces the
-                                            # daemon to spawn <agent-id> on session/new
+hydra-acp launch <agent>                    # launcher mode: shim that forces the
+                                            # daemon to spawn <agent> on session/new
 hydra-acp --session-id <id>                 # attach to existing session
                                             # (TUI in a TTY, shim otherwise)
 
@@ -234,7 +234,7 @@ A bare invocation (`hydra-acp` with no subcommand) auto-dispatches based on whet
 
 ### Launcher mode
 
-`hydra-acp launch <agent-id>` is a convenience for "shim me, and use *this* registry agent." It's the easiest way to wrap an existing ACP-speaking editor configuration whose agent-spawn surface is just a command and arguments:
+`hydra-acp launch <agent>` is a convenience for "shim me, and use *this* registry agent." It's the easiest way to wrap an existing ACP-speaking editor configuration whose agent-spawn surface is just a command and arguments:
 
 ```text
 # Configure your editor's ACP-launch command to:
@@ -243,9 +243,9 @@ hydra-acp launch claude-code
 
 When the editor sends `session/new`, the shim rewrites the params to `{ ..., agentId: "claude-code" }` before forwarding to the daemon. The daemon resolves `claude-code` against the cached ACP Registry, downloads/installs the agent on first use under `~/.hydra-acp/agents/`, and spawns the subprocess. The editor sees a normal ACP agent. From then on, `hydra-acp sessions` lists the live session and any other client can `session/attach` to it.
 
-`<agent-id>` is the registry ID — e.g. `claude-code`, `gemini-cli`, `codex`. Run `hydra-acp agents` to browse what's available, or fetch the registry CDN URL directly.
+`<agent>` is the registry ID — e.g. `claude-code`, `gemini-cli`, `codex`. Run `hydra-acp agents` to browse what's available, or fetch the registry CDN URL directly.
 
-If both `launch <agent-id>` and `--session-id` are given, `--session-id` wins (attach mode); the agent ID is ignored because the agent process is already running.
+If both `launch <agent>` and `--session-id` are given, `--session-id` wins (attach mode); the agent is ignored because the agent process is already running.
 
 ### Naming sessions from the editor
 
@@ -286,9 +286,9 @@ Each session carries a stable **`lineageId`** that survives every export/import
 
 The first attach to an imported session is slow: hydra spawns a fresh agent, runs `session/new`, and feeds the imported history back in as a synthesized takeover transcript (same machinery as `/hydra agent`). Subsequent attaches use the normal `session/load` path. This is a text-level handover — the originating agent's internal state (tool-call chains, compacted earlier turns) isn't preserved, so the resumed conversation may be cognitively shallower than the original.
 
-### Forwarding agent args (`hydra-acp launch <agent-id> ...`)
+### Forwarding agent args (`hydra-acp launch <agent> ...`)
 
-Anything you put after `<agent-id>` in launcher mode is forwarded to the underlying agent's command. Hydra appends the extra args to the registry-provided spawn plan. Example:
+Anything you put after `<agent>` in launcher mode is forwarded to the underlying agent's command. Hydra appends the extra args to the registry-provided spawn plan. Example:
 
 ```text
 hydra-acp launch codex-acp -c sandbox_mode=danger-full-access
@@ -303,14 +303,17 @@ Every config-knob flag has an `HYDRA_ACP_FOO_BAR` env-var equivalent. Flag wins
 | Flag | Env var |
 |---|---|
 | `--name` | `HYDRA_ACP_NAME` |
-| `--agent-id` | `HYDRA_ACP_AGENT_ID` |
+| `--agent` | `HYDRA_ACP_AGENT` |
+| `--model` | `HYDRA_ACP_MODEL` |
 | `--session-id` | `HYDRA_ACP_SESSION_ID` |
 
+`--model` is a one-shot override for the per-agent `defaultModels` entry in `~/.hydra-acp/config.json`. It only applies at fresh session creation — resurrect and `/hydra agent` switch ignore it (resurrected sessions stay on whatever model they were last using).
+
 Action commands (`init`, `daemon`, `sessions`, `--help`, `--version`, `--rotate-token`) are not config knobs and are flag-only.
 
 ### Registry id resolution
 
-When you ask hydra to spawn an agent (via `launch <id>`, `--agent-id`, or `HYDRA_ACP_AGENT_ID`), the daemon first tries an exact match against the ACP Registry's `id` field. If nothing matches, it falls back to matching against the **npx package basename** (the segment after the last `/` and before the version `@`). That means common binary names work transparently:
+When you ask hydra to spawn an agent (via `launch <agent>`, `--agent`, or `HYDRA_ACP_AGENT`), the daemon first tries an exact match against the ACP Registry's `id` field. If nothing matches, it falls back to matching against the **npx package basename** (the segment after the last `/` and before the version `@`). That means common binary names work transparently:
 
 | You spawn… | Registry `id` | Resolves via |
 |---|---|---|

package/dist/cli.js

@@ -248,6 +248,9 @@ function extractHydraMeta(meta) {
       out.resume = parsed.data;
     }
   }
+  if (typeof obj.model === "string") {
+    out.model = obj.model;
+  }
   if (typeof obj.currentModel === "string") {
     out.currentModel = obj.currentModel;
   }
@@ -5420,8 +5423,17 @@ function formatPlan(event) {
       }
     ];
   }
+  const allComplete = event.entries.every(
+    (e) => (e.status ?? "pending") === "completed"
+  );
+  const headerStyle = allComplete ? "plan-done" : "plan";
   const lines = [
-    { prefix: "\u25A3 ", prefixStyle: "plan", body: "Plan", bodyStyle: "plan" }
+    {
+      prefix: "\u25A3 ",
+      prefixStyle: headerStyle,
+      body: "Plan",
+      bodyStyle: headerStyle
+    }
   ];
   for (const entry of event.entries) {
     const status = entry.status ?? "pending";
@@ -5718,10 +5730,17 @@ async function runSession(term, config, opts, exitHint) {
   let initialCommands;
   let initialTurnStartedAt;
   if (ctx.sessionId === "__new__") {
+    const hydraNewMeta = {};
+    if (opts.name) {
+      hydraNewMeta.name = opts.name;
+    }
+    if (opts.model) {
+      hydraNewMeta.model = opts.model;
+    }
     const created = await conn.request("session/new", {
       cwd: ctx.cwd,
       ...opts.agentId ? { agentId: opts.agentId } : {},
-      ...opts.name ? { _meta: { [HYDRA_META_KEY]: { name: opts.name } } } : {}
+      ...Object.keys(hydraNewMeta).length > 0 ? { _meta: { [HYDRA_META_KEY]: hydraNewMeta } } : {}
     });
     resolvedSessionId = created.sessionId;
     exitHint.sessionId = resolvedSessionId;
@@ -7816,7 +7835,8 @@ var SessionManager = class {
       agentId: params.agentId,
       cwd: params.cwd,
       agentArgs: params.agentArgs,
-      mcpServers: params.mcpServers
+      mcpServers: params.mcpServers,
+      model: params.model
     });
     const session = new Session({
       cwd: params.cwd,
@@ -8008,7 +8028,7 @@ var SessionManager = class {
         );
       }
       let initialModel = extractInitialModel(newResult);
-      const desired = this.defaultModels[params.agentId];
+      const desired = params.model ?? this.defaultModels[params.agentId];
       if (desired && desired !== initialModel) {
         try {
           await agent.connection.request("session/set_model", {
@@ -9459,7 +9479,8 @@ function registerAcpWsEndpoint(app, deps) {
         agentId: params.agentId ?? deps.defaultAgent,
         mcpServers: params.mcpServers,
         title: hydraMeta.name,
-        agentArgs: hydraMeta.agentArgs
+        agentArgs: hydraMeta.agentArgs,
+        model: hydraMeta.model
       });
       const client = bindClientToSession(connection, session, state);
       await session.attach(client, "full");
@@ -10834,6 +10855,9 @@ function wireShim({
         outgoing = injectHydraMeta(outgoing, { name: namingState.name });
         namingState.used = true;
       }
+      if (opts.model) {
+        outgoing = injectHydraMeta(outgoing, { model: opts.model });
+      }
       void upstream.send(outgoing);
       return;
     }
@@ -10976,10 +11000,10 @@ async function main() {
     const positionalAgentId = afterLaunch[0];
     const agentArgs = afterLaunch.slice(1);
     const { flags: flags2 } = parseArgs(beforeLaunch);
-    const agentId = positionalAgentId ?? resolveOption(flags2, "agent-id");
+    const agentId = positionalAgentId ?? resolveOption(flags2, "agent");
     if (!agentId) {
       process.stderr.write(
-        "Usage: hydra-acp launch <agent-id> [agent-args...]\n"
+        "Usage: hydra-acp launch <agent> [agent-args...]\n"
       );
       process.exit(2);
       return;
@@ -10987,7 +11011,8 @@ async function main() {
     const launchResume = flags2.resume;
     const sessionId2 = typeof launchResume === "string" ? launchResume : resolveOption(flags2, "session-id");
     const name2 = resolveOption(flags2, "name");
-    await runShim({ sessionId: sessionId2, agentId, agentArgs, name: name2 });
+    const model2 = resolveOption(flags2, "model");
+    await runShim({ sessionId: sessionId2, agentId, agentArgs, name: name2, model: model2 });
     return;
   }
   const { positional, flags } = parseArgs(argv);
@@ -11004,22 +11029,24 @@ async function main() {
   const resumeFlag = flags.resume;
   const sessionId = typeof resumeFlag === "string" ? resumeFlag : resolveOption(flags, "session-id");
   const name = resolveOption(flags, "name");
-  const agentIdFromFlag = resolveOption(flags, "agent-id");
+  const agentIdFromFlag = resolveOption(flags, "agent");
+  const model = resolveOption(flags, "model");
   if (!subcommand) {
     if (process.stdout.isTTY) {
       await dispatchTui(flags, {
         sessionId,
         agentId: agentIdFromFlag,
-        name
+        name,
+        model
       });
       return;
     }
-    await runShim({ sessionId, name, agentId: agentIdFromFlag });
+    await runShim({ sessionId, name, agentId: agentIdFromFlag, model });
     return;
   }
   switch (subcommand) {
     case "shim":
-      await runShim({ sessionId, name, agentId: agentIdFromFlag });
+      await runShim({ sessionId, name, agentId: agentIdFromFlag, model });
       return;
     case "init":
       await runInit(flags);
@@ -11141,7 +11168,8 @@ async function main() {
       await dispatchTui(flags, {
         sessionId,
         agentId: agentIdFromFlag,
-        name
+        name,
+        model
       });
       return;
     default:
@@ -11169,6 +11197,9 @@ async function dispatchTui(flags, base) {
   if (base.name !== void 0) {
     tuiOpts.name = base.name;
   }
+  if (base.model !== void 0) {
+    tuiOpts.model = base.model;
+  }
   await runTui(tuiOpts);
 }
 function readVersion() {
@@ -11191,9 +11222,9 @@ function printHelp() {
       "  hydra-acp                          Auto: TUI when stdout is a TTY, shim otherwise (the editor-spawned case)",
       "  hydra-acp shim                     Run as ACP shim explicitly (forces shim mode regardless of TTY)",
       "  hydra-acp tui [opts]               Run the terminal UI explicitly (see below for opts)",
-      "  hydra-acp launch <agent-id> [agent-args...]",
-      "                                     Shim mode, force daemon to spawn <agent-id>",
-      "                                     from the registry. Args after <agent-id>",
+      "  hydra-acp launch <agent> [agent-args...]",
+      "                                     Shim mode, force daemon to spawn <agent>",
+      "                                     from the registry. Args after <agent>",
       "                                     are forwarded to the agent's command.",
       "  hydra-acp --resume <id>            Attach to an existing session (TUI when in a terminal, shim otherwise)",
       "  hydra-acp init [--rotate-token]    Initialize ~/.hydra-acp/config.json",
@@ -11214,14 +11245,15 @@ function printHelp() {
       "  hydra-acp extensions logs <name> [-f] [-n N]Tail or follow an extension's log",
       "  hydra-acp agents [list]                     List agents in the cached registry",
       "  hydra-acp agents refresh                    Force a registry re-fetch",
-      "  hydra-acp tui flags: [--resume [<id>]] [--new] [--agent-id <id>] [--cwd <path>] [--name <label>]",
+      "  hydra-acp tui flags: [--resume [<id>]] [--new] [--agent <id>] [--model <id>] [--cwd <path>] [--name <label>]",
       "                                     --resume <id> attaches to a specific session; bare --resume picks the most-recent",
       "                                     in cwd. Smart default (no flags): picks if any live sessions exist, else new.",
       "  hydra-acp --version                Print version",
       "  hydra-acp --help                   Show this help",
       "",
       "Config knob flags accept env-var equivalents (flag wins):",
-      "  --agent-id              HYDRA_ACP_AGENT_ID",
+      "  --agent                 HYDRA_ACP_AGENT",
+      "  --model                 HYDRA_ACP_MODEL    (one-shot at session/new; ignored on --resume)",
       "  --resume / --session-id HYDRA_ACP_SESSION_ID",
       "  --name                  HYDRA_ACP_NAME",
       ""

package/dist/index.d.ts

@@ -1964,6 +1964,7 @@ interface CreateSessionParams {
     mcpServers?: unknown[];
     title?: string;
     agentArgs?: string[];
+    model?: string;
 }
 interface ResurrectParams {
     hydraSessionId: string;

package/dist/index.js

@@ -696,6 +696,9 @@ function extractHydraMeta(meta) {
       out.resume = parsed.data;
     }
   }
+  if (typeof obj.model === "string") {
+    out.model = obj.model;
+  }
   if (typeof obj.currentModel === "string") {
     out.currentModel = obj.currentModel;
   }
@@ -2598,7 +2601,8 @@ var SessionManager = class {
       agentId: params.agentId,
       cwd: params.cwd,
       agentArgs: params.agentArgs,
-      mcpServers: params.mcpServers
+      mcpServers: params.mcpServers,
+      model: params.model
     });
     const session = new Session({
       cwd: params.cwd,
@@ -2790,7 +2794,7 @@ var SessionManager = class {
         );
       }
       let initialModel = extractInitialModel(newResult);
-      const desired = this.defaultModels[params.agentId];
+      const desired = params.model ?? this.defaultModels[params.agentId];
       if (desired && desired !== initialModel) {
         try {
           await agent.connection.request("session/set_model", {
@@ -4305,7 +4309,8 @@ function registerAcpWsEndpoint(app, deps) {
         agentId: params.agentId ?? deps.defaultAgent,
         mcpServers: params.mcpServers,
         title: hydraMeta.name,
-        agentArgs: hydraMeta.agentArgs
+        agentArgs: hydraMeta.agentArgs,
+        model: hydraMeta.model
       });
       const client = bindClientToSession(connection, session, state);
       await session.attach(client, "full");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hydra-acp/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Multi-client ACP session daemon: spawn agents, attach over WSS, multiplex sessions across editors.",
   "license": "MIT",
   "type": "module",