@tylerl0706/ahpx 0.2.0

package/dist/bin.js

@@ -0,0 +1,3090 @@
+#!/usr/bin/env node
+import {
+  AhpClient,
+  AuthHandler,
+  ForwardingFormatter,
+  HealthChecker,
+  SessionPersistence,
+  SessionStore,
+  WebSocketForwarder,
+  WebhookForwarder,
+  createLogger,
+  ensureFileUri,
+  setVerbose
+} from "./chunk-B6RV43UP.js";
+
+// src/bin.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import * as fs4 from "fs/promises";
+import * as path4 from "path";
+import { Command } from "commander";
+import pc6 from "picocolors";
+
+// src/completions.ts
+var COMMANDS = ["connect", "server", "config", "session", "prompt", "exec", "cancel", "completions"];
+var SERVER_SUBCOMMANDS = ["add", "list", "remove", "test"];
+var SESSION_SUBCOMMANDS = ["new", "list", "show", "close", "history"];
+var CONFIG_SUBCOMMANDS = ["show", "init"];
+var COMPLETIONS_SUBCOMMANDS = ["bash", "zsh", "fish"];
+var FORMATS = ["text", "json", "quiet"];
+function bashCompletion() {
+  return `# ahpx bash completion
+_ahpx_completions() {
+    local cur prev commands
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    commands="${COMMANDS.join(" ")}"
+
+    case "\${COMP_WORDS[1]}" in
+        server)
+            COMPREPLY=( $(compgen -W "${SERVER_SUBCOMMANDS.join(" ")}" -- "$cur") )
+            return 0
+            ;;
+        session)
+            COMPREPLY=( $(compgen -W "${SESSION_SUBCOMMANDS.join(" ")}" -- "$cur") )
+            return 0
+            ;;
+        config)
+            COMPREPLY=( $(compgen -W "${CONFIG_SUBCOMMANDS.join(" ")}" -- "$cur") )
+            return 0
+            ;;
+        completions)
+            COMPREPLY=( $(compgen -W "${COMPLETIONS_SUBCOMMANDS.join(" ")}" -- "$cur") )
+            return 0
+            ;;
+    esac
+
+    case "$prev" in
+        --format)
+            COMPREPLY=( $(compgen -W "${FORMATS.join(" ")}" -- "$cur") )
+            return 0
+            ;;
+    esac
+
+    if [[ "$cur" == -* ]]; then
+        COMPREPLY=( $(compgen -W "--format --verbose --json-strict --help --version" -- "$cur") )
+        return 0
+    fi
+
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    return 0
+}
+complete -F _ahpx_completions ahpx
+`;
+}
+function zshCompletion() {
+  return `#compdef ahpx
+# ahpx zsh completion
+
+_ahpx() {
+    local -a commands
+    commands=(
+        'connect:Connect to an AHP server'
+        'server:Manage saved server connections'
+        'config:Manage ahpx configuration'
+        'session:Manage agent sessions'
+        'prompt:Send a prompt to an agent session'
+        'exec:One-shot prompt with temp session'
+        'cancel:Cancel the active turn'
+        'completions:Generate shell completion scripts'
+    )
+
+    _arguments -C \\
+        '--format[Output format]:format:(${FORMATS.join(" ")})' \\
+        '--verbose[Enable debug logging]' \\
+        '--json-strict[Suppress non-JSON stderr output]' \\
+        '--help[Show help]' \\
+        '--version[Show version]' \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case $state in
+        command)
+            _describe -t commands 'ahpx commands' commands
+            ;;
+        args)
+            case $words[1] in
+                server)
+                    _describe -t subcommands 'server subcommands' \\
+                        '(${SERVER_SUBCOMMANDS.map((s) => `"${s}"`).join(" ")})'
+                    ;;
+                session)
+                    _describe -t subcommands 'session subcommands' \\
+                        '(${SESSION_SUBCOMMANDS.map((s) => `"${s}"`).join(" ")})'
+                    ;;
+                config)
+                    _describe -t subcommands 'config subcommands' \\
+                        '(${CONFIG_SUBCOMMANDS.map((s) => `"${s}"`).join(" ")})'
+                    ;;
+                completions)
+                    _describe -t subcommands 'completions subcommands' \\
+                        '(${COMPLETIONS_SUBCOMMANDS.map((s) => `"${s}"`).join(" ")})'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_ahpx "$@"
+`;
+}
+function fishCompletion() {
+  return `# ahpx fish completion
+
+# Disable file completions by default
+complete -c ahpx -f
+
+# Top-level commands
+${COMMANDS.map((c) => `complete -c ahpx -n "__fish_use_subcommand" -a "${c}"`).join("\n")}
+
+# Global flags
+complete -c ahpx -l format -d "Output format" -xa "${FORMATS.join(" ")}"
+complete -c ahpx -l verbose -d "Enable debug logging"
+complete -c ahpx -l json-strict -d "Suppress non-JSON stderr output"
+
+# server subcommands
+${SERVER_SUBCOMMANDS.map((s) => `complete -c ahpx -n "__fish_seen_subcommand_from server" -a "${s}"`).join("\n")}
+
+# session subcommands
+${SESSION_SUBCOMMANDS.map((s) => `complete -c ahpx -n "__fish_seen_subcommand_from session" -a "${s}"`).join("\n")}
+
+# config subcommands
+${CONFIG_SUBCOMMANDS.map((s) => `complete -c ahpx -n "__fish_seen_subcommand_from config" -a "${s}"`).join("\n")}
+
+# completions subcommands
+${COMPLETIONS_SUBCOMMANDS.map((s) => `complete -c ahpx -n "__fish_seen_subcommand_from completions" -a "${s}"`).join("\n")}
+`;
+}
+
+// src/config/index.ts
+import * as fs2 from "fs/promises";
+import * as os2 from "os";
+import * as path2 from "path";
+
+// src/config/connections.ts
+import { randomUUID } from "crypto";
+import * as fs from "fs/promises";
+import * as os from "os";
+import * as path from "path";
+var log = createLogger("connections");
+function isValidWsUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "ws:" || parsed.protocol === "wss:";
+  } catch {
+    return false;
+  }
+}
+function isLocalUrl(url) {
+  try {
+    const parsed = new URL(url);
+    const host = parsed.hostname;
+    return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+  } catch {
+    return false;
+  }
+}
+var ConnectionValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionValidationError";
+  }
+};
+var ConnectionStore = class {
+  filePath;
+  constructor(configDir) {
+    const dir = configDir ?? path.join(os.homedir(), ".ahpx");
+    this.filePath = path.join(dir, "connections.json");
+  }
+  /** Ensure the config directory exists. */
+  async ensureDir() {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true, mode: 448 });
+  }
+  /** Read the connections file, returning an empty list if it doesn't exist. */
+  async read() {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        return { connections: [] };
+      }
+      log.warn("corrupt connections file, using empty list", { error: String(err) });
+      return { connections: [] };
+    }
+  }
+  /** Atomic write: write to temp file then rename. */
+  async write(data) {
+    await this.ensureDir();
+    const tmp = `${this.filePath}.${randomUUID()}.tmp`;
+    await fs.writeFile(tmp, `${JSON.stringify(data, null, "	")}
+`, { mode: 384, encoding: "utf-8" });
+    await fs.rename(tmp, this.filePath);
+  }
+  /** List all connection profiles. */
+  async list() {
+    const data = await this.read();
+    return data.connections;
+  }
+  /** Get a connection by name, or undefined if not found. */
+  async get(name) {
+    const data = await this.read();
+    return data.connections.find((c) => c.name === name);
+  }
+  /** Get the default connection, or undefined if none is set. */
+  async getDefault() {
+    const data = await this.read();
+    return data.connections.find((c) => c.default === true);
+  }
+  /** Add a new connection profile. Throws if name already exists or URL is invalid. */
+  async add(profile) {
+    if (!isValidWsUrl(profile.url)) {
+      throw new ConnectionValidationError(`Invalid WebSocket URL: ${profile.url} (must be ws:// or wss://)`);
+    }
+    const data = await this.read();
+    if (data.connections.some((c) => c.name === profile.name)) {
+      throw new ConnectionValidationError(`Connection "${profile.name}" already exists`);
+    }
+    if (profile.default) {
+      for (const c of data.connections) {
+        c.default = false;
+      }
+    }
+    data.connections.push({ ...profile });
+    await this.write(data);
+  }
+  /** Remove a connection by name. Returns true if found and removed, false otherwise. */
+  async remove(name) {
+    const data = await this.read();
+    const idx = data.connections.findIndex((c) => c.name === name);
+    if (idx === -1) return false;
+    data.connections.splice(idx, 1);
+    await this.write(data);
+    return true;
+  }
+  /** Set a connection as the default. Throws if name not found. */
+  async setDefault(name) {
+    const data = await this.read();
+    const target = data.connections.find((c) => c.name === name);
+    if (!target) {
+      throw new ConnectionValidationError(`Connection "${name}" not found`);
+    }
+    for (const c of data.connections) {
+      c.default = c.name === name;
+    }
+    await this.write(data);
+  }
+};
+
+// src/config/index.ts
+var CONFIG_KEYS = /* @__PURE__ */ new Set([
+  "defaultServer",
+  "defaultProvider",
+  "defaultModel",
+  "permissions",
+  "timeout",
+  "format",
+  "verbose"
+]);
+var DEFAULT_CONFIG = Object.freeze({
+  permissions: "approve-reads",
+  timeout: 30,
+  format: "text",
+  verbose: false
+});
+function globalConfigDir() {
+  return path2.join(os2.homedir(), ".ahpx");
+}
+function globalConfigPath() {
+  return path2.join(globalConfigDir(), "config.json");
+}
+function projectConfigPath(cwd) {
+  return path2.join(cwd ?? process.cwd(), ".ahpxrc.json");
+}
+async function readJsonFile(filePath) {
+  try {
+    const raw = await fs2.readFile(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return void 0;
+    }
+    throw err;
+  }
+}
+function pickConfigKeys(raw) {
+  const result = {};
+  for (const key of Object.keys(raw)) {
+    if (CONFIG_KEYS.has(key)) {
+      result[key] = raw[key];
+    }
+  }
+  return result;
+}
+async function loadConfig(options) {
+  const gPath = options?.globalPath ?? globalConfigPath();
+  const pPath = options?.projectPath ?? projectConfigPath();
+  const globalRaw = await readJsonFile(gPath);
+  const projectRaw = await readJsonFile(pPath);
+  const overrides = {};
+  if (options?.overrides) {
+    for (const [k, v] of Object.entries(options.overrides)) {
+      if (v !== void 0) {
+        overrides[k] = v;
+      }
+    }
+  }
+  return {
+    ...DEFAULT_CONFIG,
+    ...globalRaw ? pickConfigKeys(globalRaw) : {},
+    ...projectRaw ? pickConfigKeys(projectRaw) : {},
+    ...overrides
+  };
+}
+async function initGlobalConfig(configPath) {
+  const p = configPath ?? globalConfigPath();
+  try {
+    await fs2.access(p);
+    return false;
+  } catch {
+    await fs2.mkdir(path2.dirname(p), { recursive: true });
+    await fs2.writeFile(p, `${JSON.stringify(DEFAULT_CONFIG, null, "	")}
+`, "utf-8");
+    return true;
+  }
+}
+async function loadConfigWithSources(options) {
+  const gPath = options?.globalPath ?? globalConfigPath();
+  const pPath = options?.projectPath ?? projectConfigPath();
+  const globalRaw = await readJsonFile(gPath);
+  const projectRaw = await readJsonFile(pPath);
+  const globalConfig = globalRaw ? pickConfigKeys(globalRaw) : {};
+  const projectConfig = projectRaw ? pickConfigKeys(projectRaw) : {};
+  const overrides = {};
+  if (options?.overrides) {
+    for (const [k, v] of Object.entries(options.overrides)) {
+      if (v !== void 0) {
+        overrides[k] = v;
+      }
+    }
+  }
+  const merged = {
+    ...DEFAULT_CONFIG,
+    ...globalConfig,
+    ...projectConfig,
+    ...overrides
+  };
+  const sources = {};
+  for (const key of CONFIG_KEYS) {
+    if (DEFAULT_CONFIG[key] !== void 0) {
+      sources[key] = "default";
+    }
+  }
+  for (const key of Object.keys(globalConfig)) {
+    sources[key] = "global";
+  }
+  for (const key of Object.keys(projectConfig)) {
+    sources[key] = "project";
+  }
+  for (const key of Object.keys(overrides)) {
+    sources[key] = "cli";
+  }
+  return { config: merged, sources, globalPath: gPath, projectPath: pPath };
+}
+
+// src/errors.ts
+var ExitCode = {
+  Success: 0,
+  Error: 1,
+  Usage: 2,
+  Timeout: 3,
+  NoSession: 4,
+  PermissionDenied: 5,
+  Interrupted: 130
+};
+var AhpxError = class extends Error {
+  constructor(message, exitCode) {
+    super(message);
+    this.exitCode = exitCode;
+    this.name = "AhpxError";
+  }
+};
+var UsageError = class extends AhpxError {
+  constructor(message) {
+    super(message, ExitCode.Usage);
+    this.name = "UsageError";
+  }
+};
+var TimeoutError = class extends AhpxError {
+  constructor(message) {
+    super(message, ExitCode.Timeout);
+    this.name = "TimeoutError";
+  }
+};
+var NoSessionError = class extends AhpxError {
+  constructor(message) {
+    super(message, ExitCode.NoSession);
+    this.name = "NoSessionError";
+  }
+};
+
+// src/output/renderer.ts
+import pc from "picocolors";
+function textOf(v) {
+  return typeof v === "string" ? v : v.markdown;
+}
+var PromptRenderer = class {
+  constructor(out = process.stdout) {
+    this.out = out;
+  }
+  hasStreamedText = false;
+  reasoningOpen = false;
+  /** Append streaming text delta. */
+  onDelta(text) {
+    if (!this.hasStreamedText) {
+      this.out.write("\n");
+      this.hasStreamedText = true;
+    }
+    this.closeReasoningIfNeeded();
+    this.out.write(text);
+  }
+  /** Show [thinking] block text. */
+  onReasoning(text) {
+    if (!this.reasoningOpen) {
+      this.out.write(`${pc.dim("[thinking]")} `);
+      this.reasoningOpen = true;
+    }
+    this.out.write(pc.dim(text));
+  }
+  /** Tool call started (streaming parameters). */
+  onToolCallStart(_id, name) {
+    this.closeReasoningIfNeeded();
+    this.ensureNewline();
+    this.out.write(`${pc.yellow("[tool]")} ${name} ${pc.dim("(running)")}
+`);
+  }
+  /** Tool call streaming parameter delta — silent, state tracked internally. */
+  onToolCallDelta(_id, _paramsDelta) {
+  }
+  /** Tool call parameters complete, pending confirmation. */
+  onToolCallReady(_id, call) {
+    this.closeReasoningIfNeeded();
+    this.ensureNewline();
+    const msg = textOf(call.invocationMessage);
+    this.out.write(`${pc.yellow("[tool]")} ${msg} ${pc.dim("(pending confirmation)")}
+`);
+  }
+  /** Tool call completed with result. */
+  onToolCallComplete(_id, result) {
+    const msg = textOf(result.pastTenseMessage);
+    const color = result.success ? pc.green : pc.red;
+    this.out.write(`${color("[tool]")} ${msg} ${pc.dim("(completed)")}
+`);
+    if (result.content) {
+      for (const block of result.content) {
+        if ("text" in block && block.text) {
+          const preview = block.text.length > 200 ? `${block.text.slice(0, 200)}\u2026` : block.text;
+          for (const line of preview.split("\n")) {
+            this.out.write(`  ${pc.dim(line)}
+`);
+          }
+        }
+      }
+    }
+  }
+  /** Tool call was cancelled. */
+  onToolCallCancelled(_id, reason) {
+    this.out.write(`${pc.red("[tool]")} cancelled: ${reason}
+`);
+  }
+  /** Token usage report. */
+  onUsage(usage) {
+    const parts = [];
+    if (usage.inputTokens != null) {
+      parts.push(`${usage.inputTokens.toLocaleString()} in`);
+    }
+    if (usage.outputTokens != null) {
+      parts.push(`${usage.outputTokens.toLocaleString()} out`);
+    }
+    const model = usage.model ? ` (${usage.model})` : "";
+    if (parts.length > 0) {
+      this.out.write(pc.dim(`Tokens: ${parts.join(" / ")}${model}
+`));
+    }
+  }
+  /** Turn completed successfully. */
+  onTurnComplete(_responseText) {
+    this.closeReasoningIfNeeded();
+    this.ensureNewline();
+    this.out.write(`
+${pc.green("[done]")} end_turn
+`);
+  }
+  /** Turn ended with an error. */
+  onTurnError(error) {
+    this.closeReasoningIfNeeded();
+    this.ensureNewline();
+    this.out.write(`
+${pc.red("[error]")} ${error.message}
+`);
+  }
+  /** Turn was cancelled. */
+  onTurnCancelled() {
+    this.closeReasoningIfNeeded();
+    this.ensureNewline();
+    this.out.write(`
+${pc.yellow("[cancelled]")} turn cancelled
+`);
+  }
+  /** Session title changed. */
+  onTitleChanged(_title) {
+  }
+  // ── Private helpers ───────────────────────────────────────────────────
+  closeReasoningIfNeeded() {
+    if (this.reasoningOpen) {
+      this.out.write("\n\n");
+      this.reasoningOpen = false;
+    }
+  }
+  ensureNewline() {
+  }
+};
+
+// src/output/json-formatter.ts
+var JsonFormatter = class {
+  constructor(out = process.stdout, strict = false, tags) {
+    this.out = out;
+    this.strict = strict;
+    this.tags = tags;
+  }
+  /** Whether strict mode is active (suppresses non-JSON stderr). */
+  get isStrict() {
+    return this.strict;
+  }
+  onDelta(text) {
+    this.emit("delta", { content: text });
+  }
+  onReasoning(text) {
+    this.emit("reasoning", { content: text });
+  }
+  onToolCallStart(id, name) {
+    this.emit("tool_call_start", { toolCallId: id, name });
+  }
+  onToolCallDelta(id, paramsDelta) {
+    this.emit("tool_call_delta", { toolCallId: id, content: paramsDelta });
+  }
+  onToolCallReady(id, call) {
+    this.emit("tool_call_ready", {
+      toolCallId: id,
+      toolName: call.toolName,
+      displayName: call.displayName,
+      invocationMessage: call.invocationMessage,
+      ...call.toolInput !== void 0 ? { toolInput: call.toolInput } : {}
+    });
+  }
+  onToolCallComplete(id, result) {
+    this.emit("tool_call_complete", { toolCallId: id, result });
+  }
+  onToolCallCancelled(id, reason) {
+    this.emit("tool_call_cancelled", { toolCallId: id, reason });
+  }
+  onUsage(usage) {
+    this.emit("usage", { usage });
+  }
+  onTurnComplete(responseText) {
+    this.emit("turn_complete", { responseText });
+  }
+  onTurnError(error) {
+    this.emit("turn_error", { error });
+  }
+  onTurnCancelled() {
+    this.emit("turn_cancelled", {});
+  }
+  onTitleChanged(title) {
+    this.emit("title_changed", { title });
+  }
+  // ── Helpers ───────────────────────────────────────────────────────────
+  emit(type, data) {
+    const envelope = {
+      type,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...this.tags && Object.keys(this.tags).length > 0 ? { tags: this.tags } : {},
+      data
+    };
+    this.out.write(`${JSON.stringify(envelope)}
+`);
+  }
+};
+
+// src/output/quiet-formatter.ts
+var QuietFormatter = class {
+  constructor(out = process.stdout, err = process.stderr) {
+    this.out = out;
+    this.err = err;
+  }
+  onDelta(_text) {
+  }
+  onReasoning(_text) {
+  }
+  onToolCallStart(_id, _name) {
+  }
+  onToolCallDelta(_id, _paramsDelta) {
+  }
+  onToolCallReady(_id, _call) {
+  }
+  onToolCallComplete(_id, _result) {
+  }
+  onToolCallCancelled(_id, _reason) {
+  }
+  onUsage(_usage) {
+  }
+  onTurnComplete(responseText) {
+    if (responseText) {
+      this.out.write(`${responseText}
+`);
+    }
+  }
+  onTurnError(error) {
+    this.err.write(`${error.message}
+`);
+  }
+  onTurnCancelled() {
+  }
+  onTitleChanged(_title) {
+  }
+};
+
+// src/output/spinner.ts
+import pc2 from "picocolors";
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+var INTERVAL = 80;
+function startSpinner(message, enabled = true) {
+  if (!enabled || !process.stderr.isTTY) {
+    let stopped2 = false;
+    return {
+      update() {
+      },
+      stop() {
+        stopped2 = true;
+      },
+      succeed(msg) {
+        if (stopped2) return;
+        stopped2 = true;
+        process.stderr.write(`${pc2.green("\u2713")} ${msg}
+`);
+      },
+      fail(msg) {
+        if (stopped2) return;
+        stopped2 = true;
+        process.stderr.write(`${pc2.red("\u2717")} ${msg}
+`);
+      }
+    };
+  }
+  let frameIdx = 0;
+  let text = message;
+  let stopped = false;
+  const render = () => {
+    if (stopped) return;
+    const frame = FRAMES[frameIdx % FRAMES.length];
+    process.stderr.write(`\r\x1B[K${frame} ${text}`);
+    frameIdx++;
+  };
+  const timer = setInterval(render, INTERVAL);
+  render();
+  return {
+    update(msg) {
+      text = msg;
+    },
+    stop(finalMessage) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stderr.write("\r\x1B[K");
+      if (finalMessage) {
+        process.stderr.write(`${finalMessage}
+`);
+      }
+    },
+    succeed(msg) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stderr.write(`\r\x1B[K${pc2.green("\u2713")} ${msg}
+`);
+    },
+    fail(msg) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      process.stderr.write(`\r\x1B[K${pc2.red("\u2717")} ${msg}
+`);
+    }
+  };
+}
+
+// src/output/index.ts
+function createFormatter(format, options) {
+  switch (format) {
+    case "json":
+      return new JsonFormatter(options?.out, options?.jsonStrict, options?.tags);
+    case "quiet":
+      return new QuietFormatter(options?.out, options?.err);
+    default:
+      return new PromptRenderer(options?.out);
+  }
+}
+
+// src/permissions/handler.ts
+import * as readline from "readline";
+import pc3 from "picocolors";
+var PermissionHandler = class {
+  constructor(mode, options) {
+    this.mode = mode;
+    this.input = options?.input ?? process.stdin;
+    this.output = options?.output ?? process.stdout;
+  }
+  input;
+  output;
+  /**
+   * Handle tool call confirmation.
+   * Returns true (approved) or false (denied).
+   */
+  async handleToolConfirmation(toolCall) {
+    if (this.mode === "approve-all") {
+      this.output.write(`${pc3.dim("  [auto-approved]")}
+`);
+      return true;
+    }
+    if (this.mode === "deny-all") {
+      this.output.write(`${pc3.dim("  [denied]")}
+`);
+      return false;
+    }
+    const msg = typeof toolCall.invocationMessage === "string" ? toolCall.invocationMessage : toolCall.invocationMessage.markdown;
+    return this.promptUser("tool", msg);
+  }
+  /**
+   * Interactive y/N prompt.
+   */
+  promptUser(kind, detail) {
+    return new Promise((resolve3) => {
+      let resolved = false;
+      const label = kind.charAt(0).toUpperCase() + kind.slice(1);
+      this.output.write(`  Allow ${label}: ${detail}? (y/N): `);
+      const rl = readline.createInterface({
+        input: this.input,
+        terminal: false
+      });
+      rl.once("line", (answer) => {
+        if (resolved) return;
+        resolved = true;
+        rl.close();
+        const approved = answer.trim().toLowerCase() === "y";
+        if (approved) {
+          this.output.write(`${pc3.dim("  [approved]")}
+`);
+        } else {
+          this.output.write(`${pc3.dim("  [denied]")}
+`);
+        }
+        resolve3(approved);
+      });
+      rl.once("close", () => {
+        if (resolved) return;
+        resolved = true;
+        resolve3(false);
+      });
+    });
+  }
+};
+
+// src/prompt/controller.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var TurnController = class {
+  constructor(client, sessionUri, renderer, permissionHandler) {
+    this.client = client;
+    this.sessionUri = sessionUri;
+    this.renderer = renderer;
+    this.permissionHandler = permissionHandler;
+  }
+  activeTurnId;
+  cancelled = false;
+  /** The currently active turn ID, if any. */
+  get turnId() {
+    return this.activeTurnId;
+  }
+  /**
+   * Send a message and stream the full response.
+   */
+  async prompt(text, attachments, options) {
+    const turnId = randomUUID2();
+    this.activeTurnId = turnId;
+    this.cancelled = false;
+    let responseText = "";
+    let toolCallCount = 0;
+    let usage;
+    return new Promise((resolve3) => {
+      let idleTimer;
+      const resetIdleTimer = () => {
+        if (idleTimer !== void 0) clearTimeout(idleTimer);
+        if (options?.idleTimeout) {
+          idleTimer = setTimeout(() => {
+            cleanup();
+            this.renderer.onTurnCancelled();
+            resolve3({
+              turnId,
+              responseText,
+              toolCalls: toolCallCount,
+              usage: usage ? {
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                model: usage.model
+              } : void 0,
+              state: "idle_timeout"
+            });
+          }, options.idleTimeout);
+        }
+      };
+      const onAction = (envelope) => {
+        const action = envelope.action;
+        if (!("session" in action) || action.session !== this.sessionUri) {
+          return;
+        }
+        if ("turnId" in action && action.turnId !== turnId) {
+          return;
+        }
+        resetIdleTimer();
+        switch (action.type) {
+          case "session/delta" /* SessionDelta */: {
+            const a = action;
+            responseText += a.content;
+            this.renderer.onDelta(a.content);
+            break;
+          }
+          case "session/reasoning" /* SessionReasoning */: {
+            const a = action;
+            this.renderer.onReasoning(a.content);
+            break;
+          }
+          case "session/toolCallStart" /* SessionToolCallStart */: {
+            const a = action;
+            toolCallCount++;
+            this.renderer.onToolCallStart(a.toolCallId, a.displayName);
+            break;
+          }
+          case "session/toolCallDelta" /* SessionToolCallDelta */: {
+            const a = action;
+            this.renderer.onToolCallDelta(a.toolCallId, a.content);
+            break;
+          }
+          case "session/toolCallReady" /* SessionToolCallReady */: {
+            const a = action;
+            const serverConfirmed = !!a.confirmed;
+            let toolClientId;
+            let stateName;
+            let stateDisplayName;
+            const session2 = this.client.state.getSession(this.sessionUri);
+            if (session2?.activeTurn) {
+              for (const part of session2.activeTurn.responseParts) {
+                if (part.kind === "toolCall" /* ToolCall */ && part.toolCall.toolCallId === a.toolCallId) {
+                  toolClientId = part.toolCall.toolClientId;
+                  stateName = part.toolCall.toolName;
+                  stateDisplayName = part.toolCall.displayName;
+                  break;
+                }
+              }
+            }
+            if (serverConfirmed) {
+              const isClientTool = toolClientId !== void 0 && toolClientId === this.client.clientId;
+              if (isClientTool) {
+                break;
+              }
+            }
+            const callInfo = {
+              toolCallId: a.toolCallId,
+              toolName: stateName ?? a.toolCallId,
+              displayName: stateDisplayName ?? a.toolCallId,
+              invocationMessage: a.invocationMessage,
+              toolInput: a.toolInput
+            };
+            this.renderer.onToolCallReady(a.toolCallId, callInfo);
+            this.permissionHandler.handleToolConfirmation(callInfo).then((approved) => {
+              if (this.cancelled) return;
+              if (serverConfirmed && approved) {
+                return;
+              }
+              if (approved) {
+                this.client.dispatchAction({
+                  type: "session/toolCallConfirmed" /* SessionToolCallConfirmed */,
+                  session: this.sessionUri,
+                  turnId,
+                  toolCallId: a.toolCallId,
+                  approved: true,
+                  confirmed: "user-action" /* UserAction */
+                });
+              } else {
+                this.client.dispatchAction({
+                  type: "session/toolCallConfirmed" /* SessionToolCallConfirmed */,
+                  session: this.sessionUri,
+                  turnId,
+                  toolCallId: a.toolCallId,
+                  approved: false,
+                  reason: "denied" /* Denied */
+                });
+              }
+            });
+            break;
+          }
+          case "session/toolCallComplete" /* SessionToolCallComplete */: {
+            const a = action;
+            this.renderer.onToolCallComplete(a.toolCallId, a.result);
+            break;
+          }
+          case "session/usage" /* SessionUsage */: {
+            const a = action;
+            usage = a.usage;
+            this.renderer.onUsage(a.usage);
+            break;
+          }
+          case "session/titleChanged" /* SessionTitleChanged */: {
+            const a = action;
+            this.renderer.onTitleChanged(a.title);
+            break;
+          }
+          case "session/turnComplete" /* SessionTurnComplete */: {
+            cleanup();
+            this.renderer.onTurnComplete(responseText);
+            resolve3({
+              turnId,
+              responseText,
+              toolCalls: toolCallCount,
+              usage: usage ? {
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                model: usage.model
+              } : void 0,
+              state: "complete"
+            });
+            break;
+          }
+          case "session/error" /* SessionError */: {
+            const a = action;
+            cleanup();
+            this.renderer.onTurnError(a.error);
+            resolve3({
+              turnId,
+              responseText,
+              toolCalls: toolCallCount,
+              usage: usage ? {
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                model: usage.model
+              } : void 0,
+              state: "error",
+              error: a.error.message
+            });
+            break;
+          }
+          case "session/turnCancelled" /* SessionTurnCancelled */: {
+            cleanup();
+            this.renderer.onTurnCancelled();
+            resolve3({
+              turnId,
+              responseText,
+              toolCalls: toolCallCount,
+              usage: usage ? {
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+                model: usage.model
+              } : void 0,
+              state: "cancelled"
+            });
+            break;
+          }
+          default:
+            break;
+        }
+      };
+      const cleanup = () => {
+        if (idleTimer !== void 0) clearTimeout(idleTimer);
+        this.client.removeListener("action", onAction);
+        this.activeTurnId = void 0;
+      };
+      this.client.on("action", onAction);
+      this.client.dispatchAction({
+        type: "session/turnStarted" /* SessionTurnStarted */,
+        session: this.sessionUri,
+        turnId,
+        userMessage: {
+          text,
+          ...attachments && attachments.length > 0 ? { attachments } : {}
+        }
+      });
+      resetIdleTimer();
+    });
+  }
+  /**
+   * Cancel the active turn.
+   */
+  async cancel() {
+    if (!this.activeTurnId) return;
+    this.cancelled = true;
+    this.client.dispatchAction({
+      type: "session/turnCancelled" /* SessionTurnCancelled */,
+      session: this.sessionUri,
+      turnId: this.activeTurnId
+    });
+  }
+};
+
+// src/session/scope.ts
+import * as fs3 from "fs/promises";
+import * as path3 from "path";
+async function findGitRoot(from) {
+  let current = path3.resolve(from);
+  while (true) {
+    try {
+      await fs3.access(path3.join(current, ".git"));
+      return current;
+    } catch {
+    }
+    const parent = path3.dirname(current);
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+async function resolveSession(options) {
+  const { serverName, cwd, name, store: store2 } = options;
+  const resolvedCwd = path3.resolve(cwd);
+  const gitRoot = await findGitRoot(resolvedCwd);
+  if (!gitRoot) {
+    return store2.getByScope({ serverName, workingDirectory: resolvedCwd, name });
+  }
+  let current = resolvedCwd;
+  while (true) {
+    const match = await store2.getByScope({ serverName, workingDirectory: current, name });
+    if (match) return match;
+    if (current === gitRoot) break;
+    const parent = path3.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return void 0;
+}
+
+// src/session/connect-helper.ts
+import pc4 from "picocolors";
+async function withConnection(options, fn) {
+  const store2 = new ConnectionStore();
+  const { server: server2, config: config2, timeout } = options;
+  let url;
+  let token;
+  let name;
+  if (server2 && isValidWsUrl(server2)) {
+    url = server2;
+    name = server2;
+  } else if (server2) {
+    const conn = await store2.get(server2);
+    if (!conn) {
+      throw new Error(`Unknown connection "${server2}". Run ${pc4.bold("ahpx server list")} to see saved connections.`);
+    }
+    url = conn.url;
+    token = conn.token;
+    name = conn.name;
+  } else if (config2.defaultServer) {
+    const conn = await store2.get(config2.defaultServer);
+    if (!conn) {
+      throw new Error(
+        `Default server "${config2.defaultServer}" not found in connections. Run ${pc4.bold("ahpx server list")} to check.`
+      );
+    }
+    url = conn.url;
+    token = conn.token;
+    name = conn.name;
+  } else {
+    const def = await store2.getDefault();
+    if (!def) {
+      throw new Error(
+        `No server specified and no default is set.
+Run ${pc4.bold("ahpx server add <name> --url <ws://...> --default")} to save one.`
+      );
+    }
+    url = def.url;
+    token = def.token;
+    name = def.name;
+  }
+  const client = new AhpClient({
+    connectTimeout: timeout ?? (config2.timeout ? config2.timeout * 1e3 : 1e4),
+    initialSubscriptions: ["agenthost:/root"]
+  });
+  try {
+    await client.connect(url);
+    if (token) {
+      await client.authenticate(url, token);
+    }
+    const authHandler = new AuthHandler(client, { token });
+    const onNotification = (notification) => {
+      if (notification.type === "notify/authRequired" /* AuthRequired */) {
+        const authNotification = notification;
+        authHandler.handleAuthRequired({ resource: authNotification.resource }).catch(() => {
+        });
+      }
+    };
+    client.on("notification", onNotification);
+    try {
+      await fn(client, { name, url, token });
+    } finally {
+      client.removeListener("notification", onNotification);
+    }
+  } finally {
+    await client.disconnect();
+  }
+}
+
+// src/watch/watcher.ts
+import pc5 from "picocolors";
+var SessionWatcher = class {
+  constructor(client, sessionUri, formatter, options = {}) {
+    this.client = client;
+    this.sessionUri = sessionUri;
+    this.formatter = formatter;
+    this.statusOut = options.statusOut ?? process.stderr;
+  }
+  onAction;
+  onDisconnect;
+  stopped = false;
+  resolveWatch;
+  statusOut;
+  /**
+   * Start watching — subscribes to the session and streams all actions.
+   * Resolves when `stop()` is called or the session is disposed.
+   *
+   * Listeners are registered synchronously so callers can emit events
+   * immediately after calling watch() without a microtask gap.
+   */
+  async watch() {
+    this.stopped = false;
+    const finished = new Promise((resolve3) => {
+      this.resolveWatch = resolve3;
+      this.onAction = (envelope) => {
+        if (this.stopped) return;
+        this.handleAction(envelope);
+      };
+      this.client.on("action", this.onAction);
+      this.onDisconnect = () => {
+        this.cleanup();
+        resolve3();
+      };
+      this.client.once("disconnected", this.onDisconnect);
+    });
+    try {
+      await this.client.subscribe(this.sessionUri);
+      const sessionState = this.client.state.getSession(this.sessionUri);
+      if (!sessionState) {
+        this.cleanup();
+        throw new Error(`Session ${this.sessionUri} not found after subscribe`);
+      }
+      this.showCurrentState(sessionState);
+    } catch (err) {
+      this.cleanup();
+      throw err;
+    }
+    return finished;
+  }
+  /**
+   * Stop watching and clean up listeners.
+   */
+  stop() {
+    this.cleanup();
+  }
+  /**
+   * Show the current in-progress state when joining mid-turn.
+   */
+  showCurrentState(state) {
+    const turn = state.activeTurn;
+    if (!turn) return;
+    this.statusOut.write(pc5.dim("[watch] Joining turn in progress...\n"));
+    for (const part of turn.responseParts) {
+      switch (part.kind) {
+        case "markdown" /* Markdown */:
+          if (part.content) {
+            this.formatter.onDelta(part.content);
+          }
+          break;
+        case "reasoning" /* Reasoning */:
+          if (part.content) {
+            this.formatter.onReasoning(part.content);
+          }
+          break;
+        case "toolCall" /* ToolCall */: {
+          const tc = part.toolCall;
+          if (tc.status === "streaming" /* Streaming */ || tc.status === "running" /* Running */) {
+            this.formatter.onToolCallStart(tc.toolCallId, tc.displayName);
+          } else if (tc.status === "pending-confirmation" /* PendingConfirmation */) {
+            const info = {
+              toolCallId: tc.toolCallId,
+              toolName: tc.toolName,
+              displayName: tc.displayName,
+              invocationMessage: tc.invocationMessage,
+              toolInput: tc.toolInput
+            };
+            this.formatter.onToolCallReady(tc.toolCallId, info);
+          } else if (tc.status === "completed" /* Completed */) {
+            this.formatter.onToolCallComplete(tc.toolCallId, {
+              success: tc.success,
+              pastTenseMessage: tc.pastTenseMessage,
+              content: tc.content
+            });
+          }
+          break;
+        }
+      }
+    }
+  }
+  /**
+   * Route an incoming action to the formatter.
+   */
+  handleAction(envelope) {
+    const action = envelope.action;
+    if (!("session" in action) || action.session !== this.sessionUri) {
+      return;
+    }
+    switch (action.type) {
+      case "session/delta" /* SessionDelta */: {
+        const a = action;
+        this.formatter.onDelta(a.content);
+        break;
+      }
+      case "session/reasoning" /* SessionReasoning */: {
+        const a = action;
+        this.formatter.onReasoning(a.content);
+        break;
+      }
+      case "session/turnStarted" /* SessionTurnStarted */: {
+        const origin = this.getOriginLabel(envelope);
+        this.statusOut.write(pc5.dim(`[watch] Turn started${origin}
+`));
+        break;
+      }
+      case "session/toolCallStart" /* SessionToolCallStart */: {
+        const a = action;
+        this.formatter.onToolCallStart(a.toolCallId, a.displayName);
+        break;
+      }
+      case "session/toolCallDelta" /* SessionToolCallDelta */: {
+        const a = action;
+        this.formatter.onToolCallDelta(a.toolCallId, a.content);
+        break;
+      }
+      case "session/toolCallReady" /* SessionToolCallReady */: {
+        const a = action;
+        const info = {
+          toolCallId: a.toolCallId,
+          toolName: a.toolCallId,
+          displayName: a.toolCallId,
+          invocationMessage: a.invocationMessage,
+          toolInput: a.toolInput
+        };
+        const session2 = this.client.state.getSession(this.sessionUri);
+        if (session2?.activeTurn) {
+          for (const part of session2.activeTurn.responseParts) {
+            if (part.kind === "toolCall" /* ToolCall */ && part.toolCall.toolCallId === a.toolCallId) {
+              info.toolName = part.toolCall.toolName;
+              info.displayName = part.toolCall.displayName;
+              break;
+            }
+          }
+        }
+        this.formatter.onToolCallReady(a.toolCallId, info);
+        break;
+      }
+      case "session/toolCallComplete" /* SessionToolCallComplete */: {
+        const a = action;
+        this.formatter.onToolCallComplete(a.toolCallId, a.result);
+        break;
+      }
+      case "session/usage" /* SessionUsage */: {
+        const a = action;
+        this.formatter.onUsage(a.usage);
+        break;
+      }
+      case "session/titleChanged" /* SessionTitleChanged */: {
+        const a = action;
+        this.formatter.onTitleChanged(a.title);
+        break;
+      }
+      case "session/turnComplete" /* SessionTurnComplete */: {
+        const session2 = this.client.state.getSession(this.sessionUri);
+        const lastTurn = session2?.turns[session2.turns.length - 1];
+        let responseText = "";
+        if (lastTurn) {
+          for (const p of lastTurn.responseParts) {
+            if (p.kind === "markdown" /* Markdown */) {
+              responseText += p.content;
+            }
+          }
+        }
+        this.formatter.onTurnComplete(responseText);
+        break;
+      }
+      case "session/error" /* SessionError */: {
+        const a = action;
+        this.formatter.onTurnError(a.error);
+        break;
+      }
+      case "session/turnCancelled" /* SessionTurnCancelled */: {
+        this.formatter.onTurnCancelled();
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  /**
+   * Get a label describing who started the turn (if from another client).
+   */
+  getOriginLabel(envelope) {
+    if (envelope.origin) {
+      return ` (from ${envelope.origin.clientId})`;
+    }
+    return "";
+  }
+  /**
+   * Clean up listeners and resolve the watch promise.
+   */
+  cleanup() {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.onAction) {
+      this.client.removeListener("action", this.onAction);
+      this.onAction = void 0;
+    }
+    if (this.onDisconnect) {
+      this.client.removeListener("disconnected", this.onDisconnect);
+      this.onDisconnect = void 0;
+    }
+    if (this.resolveWatch) {
+      this.resolveWatch();
+      this.resolveWatch = void 0;
+    }
+  }
+};
+
+// src/bin.ts
+var store = new ConnectionStore();
+var sessionStore = new SessionStore();
+var sessionPersistence = new SessionPersistence(sessionStore);
+function turnResponseText(turn) {
+  let text = "";
+  for (const p of turn.responseParts) {
+    if (p.kind === "markdown" /* Markdown */) {
+      text += p.content;
+    }
+  }
+  return text;
+}
+function turnToolCallCount(turn) {
+  let count = 0;
+  for (const p of turn.responseParts) {
+    if (p.kind === "toolCall" /* ToolCall */) {
+      count++;
+    }
+  }
+  return count;
+}
+function parseGlobalOpts(cmd) {
+  const opts = cmd.optsWithGlobals();
+  return {
+    format: opts.format ?? "text",
+    jsonStrict: opts.jsonStrict ?? false,
+    verbose: opts.verbose ?? false
+  };
+}
+function formatterFromOpts(globalOpts, tags) {
+  return createFormatter(globalOpts.format, { jsonStrict: globalOpts.jsonStrict, tags });
+}
+function parseTags(raw) {
+  if (!raw || raw.length === 0) return void 0;
+  const tags = {};
+  for (const entry of raw) {
+    const eq = entry.indexOf("=");
+    if (eq <= 0) {
+      throw new UsageError(`Invalid --tag format: "${entry}". Expected key=value`);
+    }
+    tags[entry.slice(0, eq)] = entry.slice(eq + 1);
+  }
+  return tags;
+}
+function parseIdleTimeout(raw) {
+  if (raw === void 0) return void 0;
+  const seconds = Number.parseInt(raw, 10);
+  if (Number.isNaN(seconds) || seconds <= 0) {
+    throw new UsageError(`--idle-timeout must be a positive integer (got: "${raw}")`);
+  }
+  return seconds;
+}
+function parseForwardHeaders(raw) {
+  if (!raw) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new UsageError(`--forward-headers must be a JSON object (e.g. '{"Authorization": "Bearer ..."}')`);
+    }
+    return parsed;
+  } catch (err) {
+    if (err instanceof UsageError) throw err;
+    throw new UsageError(`--forward-headers must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+function buildForwarders(opts) {
+  const forwarders = [];
+  const headers = parseForwardHeaders(opts.forwardHeaders);
+  const filter = opts.forwardFilter?.split(",").map((s) => s.trim()).filter(Boolean);
+  if (opts.forwardWebhook) {
+    for (const url of opts.forwardWebhook) {
+      forwarders.push(new WebhookForwarder({ url, headers, filter }));
+    }
+  }
+  if (opts.forwardWs) {
+    for (const url of opts.forwardWs) {
+      forwarders.push(new WebSocketForwarder({ url, headers, filter }));
+    }
+  }
+  return forwarders;
+}
+function spinnersEnabled(globalOpts) {
+  return globalOpts.format === "text" && !!process.stdout.isTTY;
+}
+var program = new Command().name("ahpx").description(
+  `Agent Host Protocol CLI \u2014 manage AHP server connections, sessions, and agent interactions
+
+Usage:
+  ahpx <prompt>                  Send a prompt (implicit)
+  ahpx prompt <text>             Send a prompt (explicit)
+  ahpx exec <text>               One-shot prompt
+  ahpx session new               Create a new session
+  ahpx server add <name> --url   Save a server connection
+  ahpx connect [server]          Connect and show server info
+
+Examples:
+  ahpx "fix the failing tests"
+  ahpx --format json exec "summarize this repo"
+  echo "review changes" | ahpx`
+).version("0.1.0").option("--format <format>", "Output format: text, json, or quiet", "text").option("--json-strict", "Suppress non-JSON stderr output (only with --format json)").option("-v, --verbose", "Enable debug logging to stderr");
+async function resolveTarget(target) {
+  if (target && isValidWsUrl(target)) {
+    return { url: target };
+  }
+  if (target) {
+    const conn = await store.get(target);
+    if (!conn) {
+      throw new AhpxError(
+        `Unknown connection "${target}". Run ${pc6.bold("ahpx server list")} to see saved connections.`,
+        ExitCode.Error
+      );
+    }
+    return { url: conn.url, token: conn.token };
+  }
+  const def = await store.getDefault();
+  if (!def) {
+    throw new AhpxError(
+      `No server specified and no default is set.
+Run ${pc6.bold("ahpx server add <name> --url <ws://...> --default")} to save one.`,
+      ExitCode.Error
+    );
+  }
+  return { url: def.url, token: def.token };
+}
+function printServerInfo(client, result) {
+  console.log(pc6.green("\u2713 Connected"));
+  console.log();
+  console.log(pc6.bold("Protocol version:"), result.protocolVersion);
+  console.log(pc6.bold("Server seq:"), result.serverSeq);
+  if (result.defaultDirectory) {
+    console.log(pc6.bold("Default directory:"), result.defaultDirectory);
+  }
+  const rootState = client.state.root;
+  if (rootState.agents.length > 0) {
+    console.log();
+    console.log(pc6.bold("Agents:"));
+    for (const agent of rootState.agents) {
+      console.log(`  ${pc6.cyan(agent.provider)} \u2014 ${agent.displayName}`);
+      if (agent.models.length > 0) {
+        console.log(`    Models: ${agent.models.map((m) => m.name || m.id).join(", ")}`);
+      }
+    }
+  }
+  if (rootState.activeSessions !== void 0) {
+    console.log();
+    console.log(pc6.bold("Active sessions:"), rootState.activeSessions);
+  }
+}
+function serverInfoJson(client, result) {
+  const rootState = client.state.root;
+  return {
+    protocolVersion: result.protocolVersion,
+    serverSeq: result.serverSeq,
+    defaultDirectory: result.defaultDirectory,
+    agents: rootState.agents.map((a) => ({
+      provider: a.provider,
+      displayName: a.displayName,
+      models: a.models.map((m) => ({ id: m.id, name: m.name }))
+    })),
+    activeSessions: rootState.activeSessions
+  };
+}
+function outputResult(globalOpts, textFn, data) {
+  if (globalOpts.format === "json") {
+    console.log(JSON.stringify(data));
+  } else if (globalOpts.format === "quiet") {
+    console.log(JSON.stringify(data));
+  } else {
+    textFn();
+  }
+}
+function handleError(err, globalOpts) {
+  const raw = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? err.code : void 0;
+  const message = raw || code || "Unknown error";
+  const exitCode = err instanceof AhpxError ? err.exitCode : ExitCode.Error;
+  if (globalOpts?.format === "json") {
+    console.log(JSON.stringify({ error: message, exitCode }));
+  } else if (globalOpts?.format !== "quiet" || exitCode !== ExitCode.Success) {
+    console.error(pc6.red("\u2717"), message);
+  }
+  if (globalOpts?.verbose && err instanceof Error && err.stack) {
+    console.error(pc6.dim(err.stack));
+  }
+  process.exitCode = exitCode;
+}
+program.command("connect").description("Connect to an AHP server and print server info").argument("[target]", "WebSocket URL or saved connection name (uses default if omitted)").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").action(async (target, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  const client = new AhpClient({
+    connectTimeout: Number.parseInt(opts.timeout, 10),
+    initialSubscriptions: ["agenthost:/root"]
+  });
+  try {
+    const { url, token } = await resolveTarget(target);
+    const spinner = startSpinner(`Connecting to ${url}...`, spinnersEnabled(globalOpts));
+    try {
+      const result = await client.connect(url);
+      spinner.stop();
+      if (token) {
+        await client.authenticate(url, token);
+      }
+      outputResult(globalOpts, () => printServerInfo(client, result), serverInfoJson(client, result));
+    } catch (err) {
+      spinner.stop();
+      throw err;
+    }
+  } catch (err) {
+    handleError(err, globalOpts);
+  } finally {
+    await client.disconnect();
+  }
+});
+var server = program.command("server").description("Manage saved server connections");
+server.command("add").description("Save a named connection profile").argument("<name>", "Connection name").requiredOption("--url <url>", "WebSocket URL (ws:// or wss://)").option("--token <token>", "Authentication token").option("--default", "Set as the default server").option(
+  "--tag <tag>",
+  "Add a tag to this server (repeatable)",
+  (val, prev) => [...prev, val],
+  []
+).action(
+  async (name, opts, cmd) => {
+    const globalOpts = parseGlobalOpts(cmd);
+    applyGlobalOpts(globalOpts);
+    try {
+      const tags = opts.tag.length > 0 ? opts.tag : void 0;
+      await store.add({
+        name,
+        url: opts.url,
+        token: opts.token,
+        default: opts.default ?? false,
+        tags
+      });
+      outputResult(
+        globalOpts,
+        () => {
+          console.log(pc6.green("\u2713"), `Saved connection ${pc6.bold(name)} \u2192 ${pc6.dim(opts.url)}`);
+          if (opts.default) {
+            console.log(pc6.dim("  Set as default server"));
+          }
+          if (tags) {
+            console.log(pc6.dim(`  Tags: ${tags.join(", ")}`));
+          }
+        },
+        { name, url: opts.url, default: opts.default ?? false, tags: tags ?? [] }
+      );
+    } catch (err) {
+      if (err instanceof ConnectionValidationError) {
+        handleError(new UsageError(err.message), globalOpts);
+      } else {
+        handleError(err, globalOpts);
+      }
+    }
+  }
+);
+server.command("list").description("List saved connections").action(async (_opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const connections = await store.list();
+    outputResult(
+      globalOpts,
+      () => {
+        if (connections.length === 0) {
+          console.log(pc6.dim("No saved connections. Run"), pc6.bold("ahpx server add"), pc6.dim("to add one."));
+          return;
+        }
+        const nameW = Math.max(4, ...connections.map((c) => c.name.length));
+        const urlW = Math.max(3, ...connections.map((c) => c.url.length));
+        console.log(`  ${pc6.bold("Name".padEnd(nameW))}  ${pc6.bold("URL".padEnd(urlW))}  ${pc6.bold("Default")}`);
+        console.log(`  ${"\u2500".repeat(nameW)}  ${"\u2500".repeat(urlW)}  ${"\u2500".repeat(7)}`);
+        for (const c of connections) {
+          const def = c.default ? pc6.green("  \u2713") : pc6.dim("  \xB7");
+          console.log(`  ${pc6.cyan(c.name.padEnd(nameW))}  ${c.url.padEnd(urlW)}  ${def}`);
+        }
+      },
+      connections.map((c) => ({ name: c.name, url: c.url, default: c.default ?? false }))
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+server.command("remove").description("Remove a saved connection").argument("<name>", "Connection name to remove").action(async (name, _opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const conn = await store.get(name);
+    if (!conn) {
+      throw new AhpxError(`Connection "${name}" not found`, ExitCode.Error);
+    }
+    if (conn.default && globalOpts.format === "text") {
+      console.log(pc6.yellow("\u26A0"), `"${name}" is the default server.`);
+    }
+    const removed = await store.remove(name);
+    if (removed) {
+      outputResult(globalOpts, () => console.log(pc6.green("\u2713"), `Removed connection ${pc6.bold(name)}`), {
+        removed: name
+      });
+    }
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+server.command("test").description("Test connectivity to a server").argument("<target>", "Connection name or WebSocket URL").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").action(async (target, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  const client = new AhpClient({
+    connectTimeout: Number.parseInt(opts.timeout, 10),
+    initialSubscriptions: ["agenthost:/root"]
+  });
+  try {
+    const { url, token } = await resolveTarget(target);
+    const spinner = startSpinner(`Testing connection to ${url}...`, spinnersEnabled(globalOpts));
+    try {
+      const result = await client.connect(url);
+      spinner.stop();
+      if (token) {
+        await client.authenticate(url, token);
+      }
+      outputResult(globalOpts, () => printServerInfo(client, result), serverInfoJson(client, result));
+    } catch (err) {
+      spinner.stop();
+      throw err;
+    }
+  } catch (err) {
+    handleError(err, globalOpts);
+  } finally {
+    await client.disconnect();
+  }
+});
+server.command("status").description("Health check all saved servers").option("--all", "Show all servers including unreachable").option("-t, --timeout <ms>", "Health check timeout in milliseconds", "10000").action(async (opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const connections = await store.list();
+    if (connections.length === 0) {
+      outputResult(
+        globalOpts,
+        () => console.log(pc6.dim("No saved connections. Run"), pc6.bold("ahpx server add"), pc6.dim("to add one.")),
+        []
+      );
+      return;
+    }
+    const spinner = startSpinner(`Checking ${connections.length} server(s)...`, spinnersEnabled(globalOpts));
+    const checker = new HealthChecker({ timeout: Number.parseInt(opts.timeout, 10) });
+    const results = await checker.checkAll(connections);
+    spinner.stop();
+    const displayed = opts.all ? results : results.filter((r) => r.status !== "unreachable");
+    outputResult(
+      globalOpts,
+      () => {
+        if (displayed.length === 0) {
+          console.log(pc6.dim("No servers to check."));
+          return;
+        }
+        const nameW = Math.max(4, ...displayed.map((r) => r.name.length));
+        const urlW = Math.max(3, ...displayed.map((r) => r.url.length));
+        console.log(
+          `  ${pc6.bold("Name".padEnd(nameW))}  ${pc6.bold("URL".padEnd(urlW))}  ${pc6.bold("Status".padEnd(11))}  ${pc6.bold("Latency".padEnd(9))}  ${pc6.bold("Sessions".padEnd(8))}  ${pc6.bold("Agents")}`
+        );
+        console.log(
+          `  ${"\u2500".repeat(nameW)}  ${"\u2500".repeat(urlW)}  ${"\u2500".repeat(11)}  ${"\u2500".repeat(9)}  ${"\u2500".repeat(8)}  ${"\u2500".repeat(10)}`
+        );
+        for (const r of displayed) {
+          const statusColor = r.status === "healthy" ? pc6.green : r.status === "degraded" ? pc6.yellow : pc6.red;
+          const latency = r.status === "unreachable" ? pc6.dim("\u2014") : `${Math.round(r.latencyMs)}ms`;
+          const sessions = r.status === "unreachable" ? pc6.dim("\u2014") : String(r.activeSessions);
+          const agents = r.status === "unreachable" ? pc6.dim("\u2014") : r.agents.map((a) => a.provider).join(", ") || pc6.dim("none");
+          console.log(
+            `  ${pc6.cyan(r.name.padEnd(nameW))}  ${r.url.padEnd(urlW)}  ${statusColor(r.status.padEnd(11))}  ${String(latency).padEnd(9)}  ${String(sessions).padEnd(8)}  ${agents}`
+          );
+        }
+      },
+      displayed.map((r) => ({
+        name: r.name,
+        url: r.url,
+        status: r.status,
+        latencyMs: r.latencyMs,
+        activeSessions: r.activeSessions,
+        agents: r.agents,
+        error: r.error
+      }))
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+server.command("health").description("Detailed health check for a single server").argument("<name>", "Connection name").option("-t, --timeout <ms>", "Health check timeout in milliseconds", "10000").action(async (name, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const conn = await store.get(name);
+    if (!conn) {
+      throw new AhpxError(
+        `Connection "${name}" not found. Run ${pc6.bold("ahpx server list")} to see saved connections.`,
+        ExitCode.Error
+      );
+    }
+    const spinner = startSpinner(`Checking ${name}...`, spinnersEnabled(globalOpts));
+    const checker = new HealthChecker({ timeout: Number.parseInt(opts.timeout, 10) });
+    const health = await checker.check(conn.url, conn.name);
+    spinner.stop();
+    outputResult(
+      globalOpts,
+      () => {
+        const statusColor = health.status === "healthy" ? pc6.green : health.status === "degraded" ? pc6.yellow : pc6.red;
+        console.log(pc6.bold("Server:"), pc6.cyan(health.name));
+        console.log(pc6.bold("URL:"), health.url);
+        console.log(pc6.bold("Status:"), statusColor(health.status));
+        console.log(
+          pc6.bold("Latency:"),
+          health.status === "unreachable" ? pc6.dim("\u2014") : `${Math.round(health.latencyMs)}ms`
+        );
+        if (health.protocolVersion !== void 0) {
+          console.log(pc6.bold("Protocol:"), `v${health.protocolVersion}`);
+        }
+        console.log(
+          pc6.bold("Active sessions:"),
+          health.status === "unreachable" ? pc6.dim("\u2014") : String(health.activeSessions)
+        );
+        if (health.agents.length > 0) {
+          console.log(pc6.bold("Agents:"));
+          for (const agent of health.agents) {
+            console.log(`  ${pc6.cyan(agent.provider)}: ${agent.models.join(", ") || pc6.dim("no models")}`);
+          }
+        } else if (health.status !== "unreachable") {
+          console.log(pc6.bold("Agents:"), pc6.dim("none"));
+        }
+        if (conn.tags && conn.tags.length > 0) {
+          console.log(pc6.bold("Tags:"), conn.tags.join(", "));
+        }
+        if (health.error) {
+          console.log(pc6.bold("Error:"), pc6.red(health.error));
+        }
+        console.log(pc6.bold("Checked at:"), health.checkedAt);
+      },
+      health
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+var config = program.command("config").description("Manage ahpx configuration");
+config.command("show").description("Print resolved configuration with source annotations").action(async (_opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const result = await loadConfigWithSources({
+      overrides: buildConfigOverrides(globalOpts)
+    });
+    const sourceLabel = (src) => {
+      switch (src) {
+        case "default":
+          return pc6.dim("(default)");
+        case "global":
+          return pc6.blue(`(global: ${result.globalPath})`);
+        case "project":
+          return pc6.green(`(project: ${result.projectPath})`);
+        case "cli":
+          return pc6.yellow("(cli flag)");
+      }
+    };
+    outputResult(
+      globalOpts,
+      () => {
+        console.log(pc6.bold("Resolved configuration:"));
+        console.log(pc6.dim(`  Global: ${result.globalPath}`));
+        console.log(pc6.dim(`  Project: ${result.projectPath}`));
+        console.log();
+        for (const [key, value] of Object.entries(result.config)) {
+          if (value !== void 0) {
+            const src = result.sources[key] ?? "default";
+            console.log(`  ${pc6.cyan(key)}: ${value}  ${sourceLabel(src)}`);
+          }
+        }
+      },
+      {
+        config: result.config,
+        sources: result.sources,
+        globalPath: result.globalPath,
+        projectPath: result.projectPath
+      }
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+config.command("init").description("Create ~/.ahpx/config.json with defaults").action(async (_opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const created = await initGlobalConfig();
+    outputResult(
+      globalOpts,
+      () => {
+        if (created) {
+          console.log(pc6.green("\u2713"), `Created ${pc6.dim(globalConfigPath())}`);
+        } else {
+          console.log(pc6.dim("Config already exists at"), globalConfigPath());
+        }
+      },
+      { created, path: globalConfigPath() }
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+var session = program.command("session").description("Manage agent sessions");
+function formatAge(isoTimestamp) {
+  const ms = Date.now() - new Date(isoTimestamp).getTime();
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+function truncate(str, maxLen) {
+  if (str.length <= maxLen) return str;
+  return `${str.slice(0, maxLen - 1)}\u2026`;
+}
+async function resolveServerName(serverFlag, cfg) {
+  if (serverFlag) {
+    if (isValidWsUrl(serverFlag)) return serverFlag;
+    const conn = await store.get(serverFlag);
+    if (!conn) {
+      throw new AhpxError(
+        `Unknown connection "${serverFlag}". Run ${pc6.bold("ahpx server list")} to see saved connections.`,
+        ExitCode.Error
+      );
+    }
+    return conn.name;
+  }
+  if (cfg.defaultServer) {
+    const conn = await store.get(cfg.defaultServer);
+    if (!conn) {
+      throw new AhpxError(
+        `Default server "${cfg.defaultServer}" not found. Run ${pc6.bold("ahpx server list")} to check.`,
+        ExitCode.Error
+      );
+    }
+    return conn.name;
+  }
+  const def = await store.getDefault();
+  if (!def) {
+    throw new AhpxError(
+      `No server specified and no default is set.
+Run ${pc6.bold("ahpx server add <name> --url <ws://...> --default")} to save one.`,
+      ExitCode.Error
+    );
+  }
+  return def.name;
+}
+async function resolveSessionRecord(id, opts) {
+  if (id) {
+    const record2 = await sessionStore.get(id);
+    if (!record2) {
+      throw new NoSessionError(`Session "${id}" not found.`);
+    }
+    return record2;
+  }
+  const cfg = await loadConfig();
+  const serverName = await resolveServerName(opts.server, cfg);
+  const cwd = process.cwd();
+  const record = await resolveSession({
+    serverName,
+    cwd,
+    name: opts.name,
+    store: sessionStore
+  });
+  if (!record) {
+    const hint = opts.name ? ` named "${opts.name}"` : "";
+    throw new NoSessionError(
+      `No active session${hint} found for ${pc6.bold(serverName)} in ${pc6.dim(cwd)}.
+Run ${pc6.bold("ahpx session new")} to create one.`
+    );
+  }
+  return record;
+}
+function buildConfigOverrides(globalOpts) {
+  const overrides = {};
+  if (globalOpts.format !== "text") overrides.format = globalOpts.format;
+  if (globalOpts.verbose) overrides.verbose = true;
+  return overrides;
+}
+function applyGlobalOpts(globalOpts) {
+  setVerbose(globalOpts.verbose);
+}
+async function requireCwdForRemoteServer(server2, cwd) {
+  if (!server2 || cwd) return;
+  let url;
+  if (isValidWsUrl(server2)) {
+    url = server2;
+  } else {
+    const store2 = new ConnectionStore();
+    const conn = await store2.get(server2);
+    if (!conn) return;
+    url = conn.url;
+  }
+  if (!isLocalUrl(url)) {
+    throw new UsageError(
+      `--cwd is required when targeting a remote server.
+Use 'ahpx browse --server ${server2}' to browse the remote filesystem and find the correct working directory.`
+    );
+  }
+}
+session.command("new").description("Create a new agent session").option("-s, --server <name>", "Server name or WebSocket URL").option("-p, --provider <provider>", "Agent provider (e.g. copilot)").option("-m, --model <model>", "Model to use").option("-n, --name <name>", "Name this session (for scoped lookups)").option("--cwd <dir>", "Working directory").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").action(
+  async (opts, cmd) => {
+    const globalOpts = parseGlobalOpts(cmd);
+    applyGlobalOpts(globalOpts);
+    try {
+      await requireCwdForRemoteServer(opts.server, opts.cwd);
+      const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+      const provider = opts.provider ?? cfg.defaultProvider;
+      const model = opts.model ?? cfg.defaultModel;
+      const cwd = opts.cwd ?? process.cwd();
+      const gitRoot = await findGitRoot(cwd);
+      await withConnection(
+        {
+          server: opts.server,
+          config: cfg,
+          timeout: Number.parseInt(opts.timeout, 10)
+        },
+        async (client, serverInfo) => {
+          const rootState = client.state.root;
+          const resolvedProvider = provider ?? (rootState.agents.length > 0 ? rootState.agents[0].provider : void 0);
+          if (!resolvedProvider) {
+            throw new UsageError(
+              "No agent provider available. Specify one with --provider or configure defaultProvider."
+            );
+          }
+          const sessionId = randomUUID3();
+          const sessionUri = `${resolvedProvider}:/${sessionId}`;
+          const spinner = startSpinner(`Creating session on ${serverInfo.name}...`, spinnersEnabled(globalOpts));
+          try {
+            await client.createSession(sessionUri, resolvedProvider, model, ensureFileUri(cwd));
+            await client.subscribe(sessionUri);
+            spinner.update("Waiting for session ready...");
+            const ready = await new Promise((resolve3, reject) => {
+              const timeout = setTimeout(() => {
+                reject(new TimeoutError("Timed out waiting for session to be ready"));
+              }, 3e4);
+              client.on("action", (envelope) => {
+                const action = envelope.action;
+                if (action.type === "session/ready" /* SessionReady */ && action.session === sessionUri) {
+                  clearTimeout(timeout);
+                  resolve3(true);
+                } else if (action.type === "session/creationFailed" /* SessionCreationFailed */ && action.session === sessionUri) {
+                  clearTimeout(timeout);
+                  resolve3(false);
+                }
+              });
+              const sessionState2 = client.state.getSession(sessionUri);
+              if (sessionState2?.lifecycle === "ready") {
+                clearTimeout(timeout);
+                resolve3(true);
+              } else if (sessionState2?.lifecycle === "creationFailed") {
+                clearTimeout(timeout);
+                resolve3(false);
+              }
+            });
+            spinner.stop();
+            if (!ready) {
+              const sessionState2 = client.state.getSession(sessionUri);
+              const errMsg = sessionState2?.creationError?.message ?? "Unknown error";
+              throw new AhpxError(`Session creation failed: ${errMsg}`, ExitCode.Error);
+            }
+            const sessionState = client.state.getSession(sessionUri);
+            const record = {
+              id: sessionId,
+              sessionUri,
+              serverName: serverInfo.name,
+              serverUrl: serverInfo.url,
+              provider: resolvedProvider,
+              model: model ?? sessionState?.summary.model,
+              name: opts.name,
+              workingDirectory: cwd,
+              gitRoot,
+              title: sessionState?.summary.title,
+              status: "active",
+              createdAt: (/* @__PURE__ */ new Date()).toISOString()
+            };
+            await sessionStore.save(record);
+            outputResult(
+              globalOpts,
+              () => {
+                console.log(pc6.green("\u2713 Session created"));
+                console.log();
+                console.log(pc6.bold("ID:"), sessionId);
+                console.log(pc6.bold("URI:"), pc6.cyan(sessionUri));
+                console.log(pc6.bold("Provider:"), resolvedProvider);
+                if (record.model) console.log(pc6.bold("Model:"), record.model);
+                if (opts.name) console.log(pc6.bold("Name:"), opts.name);
+                console.log(pc6.bold("Directory:"), cwd);
+                if (gitRoot) console.log(pc6.bold("Git root:"), gitRoot);
+                console.log(pc6.bold("Status:"), pc6.green("active"));
+              },
+              {
+                id: sessionId,
+                sessionUri,
+                provider: resolvedProvider,
+                model: record.model,
+                name: opts.name,
+                workingDirectory: cwd,
+                gitRoot,
+                status: "active"
+              }
+            );
+          } catch (err) {
+            spinner.stop();
+            throw err;
+          }
+        }
+      );
+    } catch (err) {
+      handleError(err, globalOpts);
+    }
+  }
+);
+session.command("list").description("List sessions (default: active only)").option("-s, --server <name>", "Filter by server name").option("-a, --all", "Include closed sessions").action(async (opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const records = await sessionStore.list({
+      ...opts.server ? { serverName: opts.server } : {},
+      ...opts.all ? {} : { status: "active" }
+    });
+    outputResult(
+      globalOpts,
+      () => {
+        if (records.length === 0) {
+          const hint = opts.all ? "" : " active";
+          console.log(
+            pc6.dim(`No${hint} sessions found.`),
+            pc6.dim("Run"),
+            pc6.bold("ahpx session new"),
+            pc6.dim("to create one.")
+          );
+          return;
+        }
+        const idW = 8;
+        const nameW = Math.max(4, ...records.map((r) => (r.name ?? "\u2014").length));
+        const provW = Math.max(8, ...records.map((r) => r.provider.length));
+        const modelW = Math.max(5, ...records.map((r) => (r.model ?? "\u2014").length));
+        const titleW = 30;
+        const statusW = 6;
+        const ageW = 10;
+        console.log(
+          `  ${pc6.bold("ID".padEnd(idW))}  ${pc6.bold("Name".padEnd(nameW))}  ${pc6.bold("Provider".padEnd(provW))}  ${pc6.bold("Model".padEnd(modelW))}  ${pc6.bold("Title".padEnd(titleW))}  ${pc6.bold("Status".padEnd(statusW))}  ${pc6.bold("Age".padEnd(ageW))}`
+        );
+        console.log(
+          `  ${"\u2500".repeat(idW)}  ${"\u2500".repeat(nameW)}  ${"\u2500".repeat(provW)}  ${"\u2500".repeat(modelW)}  ${"\u2500".repeat(titleW)}  ${"\u2500".repeat(statusW)}  ${"\u2500".repeat(ageW)}`
+        );
+        for (const r of records) {
+          const status = r.status === "active" ? pc6.green("active") : pc6.dim("closed");
+          const shortId = r.id.slice(0, 8);
+          const name = r.name ?? pc6.dim("\u2014");
+          const model = r.model ?? pc6.dim("\u2014");
+          const title = truncate(r.title ?? "\u2014", titleW);
+          console.log(
+            `  ${pc6.cyan(shortId.padEnd(idW))}  ${String(name).padEnd(nameW)}  ${r.provider.padEnd(provW)}  ${String(model).padEnd(modelW)}  ${title.padEnd(titleW)}  ${String(status).padEnd(statusW + 10)}  ${formatAge(r.createdAt)}`
+          );
+        }
+      },
+      records.map((r) => ({
+        id: r.id,
+        sessionUri: r.sessionUri,
+        serverName: r.serverName,
+        provider: r.provider,
+        model: r.model,
+        name: r.name,
+        title: r.title,
+        status: r.status,
+        workingDirectory: r.workingDirectory,
+        createdAt: r.createdAt
+      }))
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+session.command("show").description("Show session details").argument("[id]", "Session ID").option("-n, --name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").action(async (id, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const record = await resolveSessionRecord(id, opts);
+    outputResult(
+      globalOpts,
+      () => {
+        console.log(pc6.bold("Session Details"));
+        console.log();
+        console.log(pc6.bold("ID:"), record.id);
+        console.log(pc6.bold("URI:"), pc6.cyan(record.sessionUri));
+        console.log(pc6.bold("Server:"), record.serverName);
+        console.log(pc6.bold("Provider:"), record.provider);
+        if (record.model) console.log(pc6.bold("Model:"), record.model);
+        if (record.name) console.log(pc6.bold("Name:"), record.name);
+        if (record.title) console.log(pc6.bold("Title:"), record.title);
+        console.log(pc6.bold("Status:"), record.status === "active" ? pc6.green("active") : pc6.dim("closed"));
+        if (record.workingDirectory) console.log(pc6.bold("Directory:"), record.workingDirectory);
+        if (record.gitRoot) console.log(pc6.bold("Git root:"), record.gitRoot);
+        console.log(pc6.bold("Created:"), record.createdAt, pc6.dim(`(${formatAge(record.createdAt)})`));
+        if (record.lastPromptAt) {
+          console.log(pc6.bold("Last prompt:"), record.lastPromptAt, pc6.dim(`(${formatAge(record.lastPromptAt)})`));
+        }
+        if (record.closedAt) {
+          console.log(pc6.bold("Closed:"), record.closedAt, pc6.dim(`(${formatAge(record.closedAt)})`));
+        }
+      },
+      record
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+session.command("close").description("Close a session (soft-close: keeps record for history)").argument("[id]", "Session ID").option("-n, --name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").action(async (id, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const record = await resolveSessionRecord(id, opts);
+    if (record.status === "closed") {
+      if (globalOpts.format === "text") {
+        console.log(pc6.dim("Session is already closed."));
+      }
+      return;
+    }
+    const spinner = startSpinner("Disposing session...", spinnersEnabled(globalOpts));
+    try {
+      const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+      await withConnection(
+        {
+          server: record.serverName,
+          config: cfg,
+          timeout: Number.parseInt(opts.timeout, 10)
+        },
+        async (client) => {
+          await client.disposeSession(record.sessionUri);
+        }
+      );
+      spinner.stop();
+    } catch {
+      spinner.stop();
+      if (globalOpts.format === "text") {
+        console.log(pc6.yellow("\u26A0"), "Could not dispose session on server (closing locally only)");
+      }
+    }
+    const closed = await sessionStore.close(record.id);
+    if (closed) {
+      outputResult(
+        globalOpts,
+        () => console.log(
+          pc6.green("\u2713"),
+          `Closed session ${pc6.bold(record.id.slice(0, 8))}`,
+          record.name ? pc6.dim(`(${record.name})`) : ""
+        ),
+        { closed: record.id }
+      );
+    }
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+function formatTurnEntry(entry) {
+  const userMsg = truncate(entry.userMessage, 80);
+  const responseMsg = truncate(entry.responsePreview, 80);
+  const usageStr = entry.usage ? `${entry.usage.inputTokens ?? "?"}\u2192${entry.usage.outputTokens ?? "?"}t` : "";
+  const timeStr = entry.timestamp ? pc6.dim(` (${formatAge(entry.timestamp)})`) : "";
+  console.log(pc6.bold(pc6.cyan(`  Turn ${entry.id.slice(0, 8)}`)) + timeStr);
+  console.log(`    ${pc6.bold("User:")} ${userMsg}`);
+  console.log(`    ${pc6.bold("Response:")} ${responseMsg}`);
+  if (entry.toolCalls > 0) {
+    console.log(`    ${pc6.bold("Tool calls:")} ${entry.toolCalls}`);
+  }
+  if (usageStr) {
+    console.log(`    ${pc6.bold("Tokens:")} ${usageStr}`);
+  }
+  if (entry.usage?.model) {
+    console.log(`    ${pc6.bold("Model:")} ${entry.usage.model}`);
+  }
+  console.log();
+}
+session.command("history").description("Show turn history for a session").argument("[id]", "Session ID").option("-n, --name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").option("-l, --limit <n>", "Maximum number of turns to show", "10").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").option("--local", "Show only locally-cached turn history (no server connection)").action(
+  async (id, opts, cmd) => {
+    const globalOpts = parseGlobalOpts(cmd);
+    applyGlobalOpts(globalOpts);
+    try {
+      const record = await resolveSessionRecord(id, opts);
+      const limit = Number.parseInt(opts.limit, 10);
+      if (opts.local) {
+        showLocalHistory(record, limit, globalOpts);
+        return;
+      }
+      const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+      try {
+        await withConnection(
+          {
+            server: record.serverName,
+            config: cfg,
+            timeout: Number.parseInt(opts.timeout, 10)
+          },
+          async (client) => {
+            const result = await client.fetchTurns(record.sessionUri, void 0, limit);
+            outputResult(
+              globalOpts,
+              () => {
+                if (result.turns.length === 0) {
+                  console.log(pc6.dim("No turns in this session."));
+                  return;
+                }
+                console.log(
+                  pc6.bold(`History for session ${record.id.slice(0, 8)}`),
+                  result.hasMore ? pc6.dim(`(showing last ${result.turns.length}, more available)`) : ""
+                );
+                console.log();
+                for (const turn of result.turns) {
+                  formatTurnEntry({
+                    id: turn.id,
+                    userMessage: turn.userMessage.text,
+                    responsePreview: turnResponseText(turn) || "(no response)",
+                    toolCalls: turnToolCallCount(turn),
+                    usage: turn.usage
+                  });
+                }
+              },
+              {
+                source: "server",
+                sessionId: record.id,
+                hasMore: result.hasMore,
+                turns: result.turns.map((t) => ({
+                  id: t.id,
+                  userMessage: t.userMessage.text,
+                  responseText: turnResponseText(t),
+                  toolCalls: turnToolCallCount(t),
+                  usage: t.usage
+                }))
+              }
+            );
+          }
+        );
+      } catch {
+        if (globalOpts.format === "text") {
+          console.error(pc6.yellow("Server unavailable. Showing locally-cached history.\n"));
+        }
+        showLocalHistory(record, limit, globalOpts);
+      }
+    } catch (err) {
+      handleError(err, globalOpts);
+    }
+  }
+);
+function showLocalHistory(record, limit, globalOpts) {
+  const turns = record.turns ?? [];
+  const display = turns.slice(-limit);
+  outputResult(
+    globalOpts,
+    () => {
+      if (display.length === 0) {
+        console.log(pc6.dim("No locally-cached turns for this session."));
+        return;
+      }
+      console.log(
+        pc6.bold(`Local history for session ${record.id.slice(0, 8)}`),
+        pc6.dim(`(${display.length} of ${turns.length} turns)`)
+      );
+      console.log();
+      for (const turn of display) {
+        formatTurnEntry({
+          id: turn.turnId,
+          userMessage: turn.userMessage,
+          responsePreview: turn.responsePreview,
+          toolCalls: turn.toolCallCount,
+          usage: turn.tokenUsage ? { inputTokens: turn.tokenUsage.input, outputTokens: turn.tokenUsage.output, model: turn.tokenUsage.model } : void 0,
+          timestamp: turn.timestamp
+        });
+      }
+    },
+    {
+      source: "local",
+      sessionId: record.id,
+      turns: display.map((t) => ({
+        turnId: t.turnId,
+        userMessage: t.userMessage,
+        responsePreview: t.responsePreview,
+        toolCallCount: t.toolCallCount,
+        tokenUsage: t.tokenUsage,
+        state: t.state,
+        timestamp: t.timestamp
+      }))
+    }
+  );
+}
+session.command("export").description("Export a session record (with local turn history) to JSON").argument("<id>", "Session ID").option("-o, --output <file>", "Write to file instead of stdout").action(async (id, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const record = await sessionStore.get(id);
+    if (!record) {
+      throw new NoSessionError(`Session "${id}" not found.`);
+    }
+    const exported = JSON.stringify(record, null, "	");
+    if (opts.output) {
+      await fs4.writeFile(path4.resolve(opts.output), `${exported}
+`, "utf-8");
+      if (globalOpts.format === "text") {
+        console.error(pc6.green(`Session exported to ${opts.output}`));
+      }
+    } else {
+      console.log(exported);
+    }
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+session.command("import").description("Import a session record from a JSON file").argument("<file>", "Path to JSON file").action(async (filePath, _opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const resolved = path4.resolve(filePath);
+    const raw = await fs4.readFile(resolved, "utf-8");
+    let record;
+    try {
+      record = JSON.parse(raw);
+    } catch {
+      throw new UsageError(`Failed to parse "${filePath}" as JSON.`);
+    }
+    if (!record.id || !record.sessionUri || !record.serverName || !record.serverUrl || !record.provider) {
+      throw new UsageError(
+        "Invalid session record: missing required fields (id, sessionUri, serverName, serverUrl, provider)."
+      );
+    }
+    if (!record.status || record.status !== "active" && record.status !== "closed") {
+      throw new UsageError('Invalid session record: status must be "active" or "closed".');
+    }
+    if (!record.createdAt) {
+      throw new UsageError("Invalid session record: missing createdAt timestamp.");
+    }
+    await sessionStore.save(record);
+    outputResult(
+      globalOpts,
+      () => {
+        console.log(pc6.green(`Session ${record.id.slice(0, 8)} imported successfully.`));
+        console.log(`  ${pc6.bold("URI:")} ${record.sessionUri}`);
+        console.log(`  ${pc6.bold("Server:")} ${record.serverName}`);
+        console.log(`  ${pc6.bold("Status:")} ${record.status}`);
+        if (record.turns?.length) {
+          console.log(`  ${pc6.bold("Local turns:")} ${record.turns.length}`);
+        }
+      },
+      { id: record.id, sessionUri: record.sessionUri, status: record.status }
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+session.command("active").description("Show all active sessions on the server (live query)").option("-s, --server <name>", "Server name or WebSocket URL").option("-t, --timeout <ms>", "Connection timeout in milliseconds", "10000").action(async (opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    await withConnection(
+      {
+        server: opts.server,
+        config: cfg,
+        timeout: Number.parseInt(opts.timeout, 10)
+      },
+      async (client, serverInfo) => {
+        const result = await client.listSessions();
+        outputResult(
+          globalOpts,
+          () => {
+            if (result.items.length === 0) {
+              console.log(pc6.dim(`No active sessions on ${serverInfo.name}.`));
+              return;
+            }
+            console.log(pc6.bold(`Active sessions on ${serverInfo.name}`), pc6.dim(`(${result.items.length})`));
+            console.log();
+            for (const s of result.items) {
+              const status = s.status === "in-progress" ? pc6.yellow("\u25CF in-progress") : s.status === "error" ? pc6.red("\u25CF error") : pc6.green("\u25CF idle");
+              console.log(`  ${pc6.bold(pc6.cyan(s.resource))}`);
+              console.log(`    ${pc6.bold("Provider:")} ${s.provider}`);
+              if (s.model) console.log(`    ${pc6.bold("Model:")} ${s.model}`);
+              if (s.title) console.log(`    ${pc6.bold("Title:")} ${s.title}`);
+              console.log(`    ${pc6.bold("Status:")} ${status}`);
+              console.log();
+            }
+          },
+          {
+            server: serverInfo.name,
+            sessions: result.items.map((s) => ({
+              resource: s.resource,
+              provider: s.provider,
+              model: s.model,
+              title: s.title,
+              status: s.status,
+              createdAt: s.createdAt
+            }))
+          }
+        );
+      }
+    );
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+async function readPromptFile(filePath) {
+  if (filePath === "-") {
+    return readStdin();
+  }
+  const { readFile: readFile4 } = await import("fs/promises");
+  const resolved = path4.resolve(filePath);
+  return (await readFile4(resolved, "utf-8")).trim();
+}
+function readStdin() {
+  return new Promise((resolve3, reject) => {
+    let data = "";
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve3(data.trim()));
+    process.stdin.on("error", reject);
+  });
+}
+function stdinIsPipe() {
+  return !process.stdin.isTTY;
+}
+function resolvePermissionMode(opts, cfg) {
+  if (opts.approveAll) return "approve-all";
+  if (opts.approveReads) return "approve-reads";
+  if (opts.denyAll) return "deny-all";
+  return cfg.permissions ?? "approve-reads";
+}
+async function runPrompt(opts, globalOpts) {
+  await requireCwdForRemoteServer(opts.server, opts.cwd);
+  const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+  const cwd = opts.cwd ?? process.cwd();
+  const gitRoot = await findGitRoot(cwd);
+  const permMode = resolvePermissionMode(opts, cfg);
+  let formatter = formatterFromOpts(globalOpts, opts.tags);
+  let forwardingFormatter;
+  if (opts.forwarders && opts.forwarders.length > 0) {
+    forwardingFormatter = new ForwardingFormatter({
+      inner: formatter,
+      forwarders: opts.forwarders,
+      tags: opts.tags
+    });
+    formatter = forwardingFormatter;
+  }
+  await withConnection(
+    {
+      server: opts.server,
+      config: cfg
+    },
+    async (client, serverInfo) => {
+      let sessionUri;
+      let sessionRecord;
+      if (opts.oneShot) {
+        const spinner = startSpinner("Creating session...", spinnersEnabled(globalOpts));
+        try {
+          sessionUri = await createTempSession(client, opts, cfg, cwd);
+          spinner.stop();
+        } catch (err) {
+          spinner.stop();
+          throw err;
+        }
+      } else {
+        const resolved = await resolveOrCreateSession(client, serverInfo, opts, cfg, cwd, gitRoot, globalOpts);
+        sessionUri = resolved.sessionUri;
+        sessionRecord = resolved.record;
+      }
+      if (forwardingFormatter) {
+        forwardingFormatter.sessionUri = sessionUri;
+      }
+      const permHandler = new PermissionHandler(permMode);
+      const controller = new TurnController(client, sessionUri, formatter, permHandler);
+      let sigintCount = 0;
+      const sigintHandler = () => {
+        sigintCount++;
+        if (sigintCount >= 2) {
+          process.exitCode = ExitCode.Interrupted;
+          process.exit(ExitCode.Interrupted);
+        }
+        if (globalOpts.format === "text") {
+          console.error(pc6.dim("\nCancelling..."));
+        }
+        controller.cancel();
+      };
+      process.on("SIGINT", sigintHandler);
+      try {
+        const result = await controller.prompt(opts.text, void 0, {
+          idleTimeout: opts.idleTimeout ? opts.idleTimeout * 1e3 : void 0
+        });
+        if (sessionRecord) {
+          await sessionStore.update(sessionRecord.id, {
+            lastPromptAt: (/* @__PURE__ */ new Date()).toISOString(),
+            title: client.state.getSession(sessionUri)?.summary.title ?? sessionRecord.title
+          });
+          if (result.state === "complete" || result.state === "cancelled" || result.state === "error") {
+            await sessionPersistence.saveTurn(sessionRecord.id, {
+              turnId: result.turnId,
+              responseText: result.responseText,
+              toolCalls: result.toolCalls,
+              usage: result.usage,
+              state: result.state,
+              userMessage: opts.text
+            });
+          }
+        }
+        if (result.state === "error") {
+          process.exitCode = ExitCode.Error;
+        }
+        if (result.state === "idle_timeout") {
+          throw new TimeoutError(`Idle timeout: no events received for ${opts.idleTimeout} seconds`);
+        }
+      } finally {
+        process.removeListener("SIGINT", sigintHandler);
+        if (forwardingFormatter) {
+          await forwardingFormatter.close();
+        }
+        if (opts.oneShot) {
+          const spinner = startSpinner("Disposing session...", spinnersEnabled(globalOpts));
+          try {
+            await client.disposeSession(sessionUri);
+            spinner.stop();
+          } catch {
+            spinner.stop();
+          }
+        }
+      }
+    }
+  );
+}
+async function createTempSession(client, opts, cfg, cwd) {
+  const rootState = client.state.root;
+  const provider = opts.provider ?? cfg.defaultProvider ?? (rootState.agents.length > 0 ? rootState.agents[0].provider : void 0);
+  if (!provider) {
+    throw new UsageError("No agent provider available. Specify one with --provider.");
+  }
+  const sessionId = randomUUID3();
+  const sessionUri = `${provider}:/${sessionId}`;
+  await client.createSession(sessionUri, provider, opts.model ?? cfg.defaultModel, ensureFileUri(cwd));
+  await client.subscribe(sessionUri);
+  await waitForReady(client, sessionUri);
+  return sessionUri;
+}
+async function resolveOrCreateSession(client, serverInfo, opts, cfg, cwd, gitRoot, globalOpts) {
+  const record = await resolveSession({
+    serverName: serverInfo.name,
+    cwd,
+    name: opts.sessionName,
+    store: sessionStore
+  });
+  if (record) {
+    const outcome = await sessionPersistence.resume(record, client);
+    if (outcome.status === "resumed") {
+      return { sessionUri: record.sessionUri, record };
+    }
+    if (outcome.status === "not_found") {
+      if (globalOpts.format === "text") {
+        console.error(
+          pc6.yellow(`Previous session ${record.id.slice(0, 8)} was disposed on the server. Creating a new one.`)
+        );
+      }
+      await sessionStore.close(record.id);
+    }
+  }
+  const rootState = client.state.root;
+  const provider = opts.provider ?? cfg.defaultProvider ?? (rootState.agents.length > 0 ? rootState.agents[0].provider : void 0);
+  if (!provider) {
+    throw new UsageError("No agent provider available. Specify one with --provider.");
+  }
+  const sessionId = randomUUID3();
+  const sessionUri = `${provider}:/${sessionId}`;
+  const spinner = startSpinner(`Creating session on ${serverInfo.name}...`, spinnersEnabled(globalOpts));
+  try {
+    await client.createSession(sessionUri, provider, opts.model ?? cfg.defaultModel, ensureFileUri(cwd));
+    await client.subscribe(sessionUri);
+    spinner.update("Waiting for session ready...");
+    await waitForReady(client, sessionUri);
+    spinner.stop();
+  } catch (err) {
+    spinner.stop();
+    throw err;
+  }
+  const newRecord = {
+    id: sessionId,
+    sessionUri,
+    serverName: serverInfo.name,
+    serverUrl: serverInfo.url,
+    provider,
+    model: opts.model ?? cfg.defaultModel ?? client.state.getSession(sessionUri)?.summary.model,
+    name: opts.sessionName,
+    workingDirectory: cwd,
+    gitRoot,
+    title: client.state.getSession(sessionUri)?.summary.title,
+    status: "active",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await sessionStore.save(newRecord);
+  return { sessionUri, record: newRecord };
+}
+function waitForReady(client, sessionUri) {
+  return new Promise((resolve3, reject) => {
+    const timeout = setTimeout(() => {
+      reject(new TimeoutError("Timed out waiting for session to be ready"));
+    }, 3e4);
+    client.on("action", (envelope) => {
+      const action = envelope.action;
+      if (action.type === "session/ready" /* SessionReady */ && action.session === sessionUri) {
+        clearTimeout(timeout);
+        resolve3();
+      } else if (action.type === "session/creationFailed" /* SessionCreationFailed */ && action.session === sessionUri) {
+        clearTimeout(timeout);
+        const sessionState2 = client.state.getSession(sessionUri);
+        const errMsg = sessionState2?.creationError?.message ?? "Unknown error";
+        reject(new AhpxError(`Session creation failed: ${errMsg}`, ExitCode.Error));
+      }
+    });
+    const sessionState = client.state.getSession(sessionUri);
+    if (sessionState?.lifecycle === "ready") {
+      clearTimeout(timeout);
+      resolve3();
+    } else if (sessionState?.lifecycle === "creationFailed") {
+      clearTimeout(timeout);
+      const errMsg = sessionState?.creationError?.message ?? "Unknown error";
+      reject(new AhpxError(`Session creation failed: ${errMsg}`, ExitCode.Error));
+    }
+  });
+}
+program.command("prompt").description("Send a prompt to an agent session").argument("<text...>", "Prompt text").option("-s, --server <name>", "Server name or WebSocket URL").option("-n, --session-name <name>", "Session name for scoped lookup").option("-f, --file <path>", "Read prompt from file (- for stdin)").option("--cwd <dir>", "Working directory for auto-created sessions").option("--approve-all", "Auto-approve all permissions").option("--approve-reads", "Auto-approve read permissions, prompt for others").option("--deny-all", "Auto-deny all permissions").option("--idle-timeout <seconds>", "Cancel if no events received within N seconds").option("--tag <key=value...>", "Add metadata tags to JSON events (repeatable)").option("--forward-webhook <url...>", "POST events to webhook URL (repeatable)").option("--forward-ws <url...>", "Stream events over WebSocket (repeatable)").option("--forward-filter <types>", "Comma-separated event types to forward (default: all)").option("--forward-headers <json>", "Custom headers for forwarders (JSON object)").action(
+  async (textParts, opts, cmd) => {
+    const globalOpts = parseGlobalOpts(cmd);
+    applyGlobalOpts(globalOpts);
+    try {
+      let text = textParts.join(" ");
+      if (opts.file) {
+        text = await readPromptFile(opts.file);
+      }
+      if (!text) {
+        throw new UsageError("No prompt text provided.");
+      }
+      await runPrompt(
+        {
+          text,
+          ...opts,
+          tags: parseTags(opts.tag),
+          idleTimeout: parseIdleTimeout(opts.idleTimeout),
+          forwarders: buildForwarders(opts)
+        },
+        globalOpts
+      );
+    } catch (err) {
+      handleError(err, globalOpts);
+    }
+  }
+);
+program.command("exec").description("One-shot prompt: create temp session, prompt, dispose").argument("<text...>", "Prompt text").option("-s, --server <name>", "Server name or WebSocket URL").option("-p, --provider <provider>", "Agent provider (e.g. copilot)").option("-m, --model <model>", "Model to use").option("--cwd <dir>", "Working directory for the session").option("--approve-all", "Auto-approve all permissions").option("--approve-reads", "Auto-approve read permissions, prompt for others").option("--deny-all", "Auto-deny all permissions").option("--idle-timeout <seconds>", "Cancel if no events received within N seconds").option("--tag <key=value...>", "Add metadata tags to JSON events (repeatable)").option("--forward-webhook <url...>", "POST events to webhook URL (repeatable)").option("--forward-ws <url...>", "Stream events over WebSocket (repeatable)").option("--forward-filter <types>", "Comma-separated event types to forward (default: all)").option("--forward-headers <json>", "Custom headers for forwarders (JSON object)").action(
+  async (textParts, opts, cmd) => {
+    const globalOpts = parseGlobalOpts(cmd);
+    applyGlobalOpts(globalOpts);
+    try {
+      const text = textParts.join(" ");
+      if (!text) {
+        throw new UsageError("No prompt text provided.");
+      }
+      await runPrompt(
+        {
+          text,
+          oneShot: true,
+          ...opts,
+          tags: parseTags(opts.tag),
+          idleTimeout: parseIdleTimeout(opts.idleTimeout),
+          forwarders: buildForwarders(opts)
+        },
+        globalOpts
+      );
+    } catch (err) {
+      handleError(err, globalOpts);
+    }
+  }
+);
+program.command("cancel").description("Cancel the active turn in a session").option("-n, --session-name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").action(async (opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    const serverName = await resolveServerName(opts.server, cfg);
+    const cwd = process.cwd();
+    const record = await resolveSession({
+      serverName,
+      cwd,
+      name: opts.sessionName,
+      store: sessionStore
+    });
+    if (!record) {
+      if (globalOpts.format === "text") {
+        console.log(pc6.dim("No active session found. Nothing to cancel."));
+      }
+      return;
+    }
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      await client.subscribe(record.sessionUri);
+      const sessionState = client.state.getSession(record.sessionUri);
+      if (!sessionState?.activeTurn) {
+        if (globalOpts.format === "text") {
+          console.log(pc6.dim("No active turn. Nothing to cancel."));
+        }
+        return;
+      }
+      client.dispatchAction({
+        type: "session/turnCancelled" /* SessionTurnCancelled */,
+        session: record.sessionUri,
+        turnId: sessionState.activeTurn.id
+      });
+      outputResult(globalOpts, () => console.log(pc6.green("\u2713"), "Cancellation dispatched."), {
+        cancelled: true,
+        sessionUri: record.sessionUri
+      });
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+program.command("watch").description("Attach to a session as an observer and stream all activity").argument("[id]", "Session ID").option("-n, --session-name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").action(async (id, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const record = await resolveSessionRecord(id, { name: opts.sessionName, server: opts.server });
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    const formatter = formatterFromOpts(globalOpts);
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      const watcher = new SessionWatcher(client, record.sessionUri, formatter, {
+        statusOut: process.stderr
+      });
+      const onSigint = () => watcher.stop();
+      process.on("SIGINT", onSigint);
+      if (globalOpts.format === "text") {
+        process.stderr.write(
+          pc6.dim(
+            `[watch] Observing session ${pc6.bold(record.id.slice(0, 8))}${record.name ? ` (${record.name})` : ""}...
+`
+          )
+        );
+        process.stderr.write(pc6.dim("[watch] Press Ctrl+C to detach.\n"));
+      }
+      try {
+        await watcher.watch();
+      } finally {
+        process.removeListener("SIGINT", onSigint);
+      }
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+program.command("browse").description("Browse server filesystem").argument("[directory]", "Directory URI to browse (uses server default if omitted)").option("-s, --server <name>", "Server name").action(async (directory, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      const result = await client.resourceList(directory ? ensureFileUri(directory) : "");
+      outputResult(
+        globalOpts,
+        () => {
+          if (result.entries.length === 0) {
+            console.log(pc6.dim("Directory is empty."));
+            return;
+          }
+          const sorted = [...result.entries].sort((a, b) => {
+            if (a.type !== b.type) return a.type === "directory" ? -1 : 1;
+            return a.name.localeCompare(b.name);
+          });
+          for (const entry of sorted) {
+            const icon = entry.type === "directory" ? pc6.blue("\u{1F4C1}") : "\u{1F4C4}";
+            const name = entry.type === "directory" ? pc6.bold(entry.name) : entry.name;
+            console.log(`  ${icon} ${name}`);
+          }
+        },
+        result
+      );
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+program.command("content").description("Fetch content by URI from the server").argument("<uri>", "Content reference URI").option("-s, --server <name>", "Server name").option("-o, --output <file>", "Write content to a file instead of stdout").action(async (uri, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      const result = await client.resourceRead(ensureFileUri(uri));
+      const data = result.encoding === "base64" ? Buffer.from(result.data, "base64") : Buffer.from(result.data, "utf-8");
+      if (opts.output) {
+        await fs4.writeFile(opts.output, data);
+        if (globalOpts.format === "text") {
+          console.log(pc6.green("\u2713"), `Wrote ${data.length} bytes to ${pc6.bold(opts.output)}`);
+        }
+      } else if (globalOpts.format === "json") {
+        console.log(
+          JSON.stringify({
+            uri,
+            encoding: result.encoding,
+            contentType: result.contentType,
+            data: result.data,
+            size: data.length
+          })
+        );
+      } else {
+        process.stdout.write(data);
+      }
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+program.command("model").description("Switch the model for a session").argument("<model-id>", "Model ID to switch to").option("-n, --session-name <name>", "Session name (for scoped lookup)").option("-s, --server <name>", "Server name").action(async (modelId, opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const record = await resolveSessionRecord(void 0, { name: opts.sessionName, server: opts.server });
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      await client.subscribe(record.sessionUri);
+      client.dispatchAction({
+        type: "session/modelChanged" /* SessionModelChanged */,
+        session: record.sessionUri,
+        model: modelId
+      });
+      outputResult(globalOpts, () => console.log(pc6.green("\u2713"), `Model change to ${pc6.bold(modelId)} dispatched.`), {
+        sessionUri: record.sessionUri,
+        model: modelId
+      });
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+program.command("agents").description("List available agents and models on the server").option("-s, --server <name>", "Server name").action(async (opts, cmd) => {
+  const globalOpts = parseGlobalOpts(cmd);
+  applyGlobalOpts(globalOpts);
+  try {
+    const cfg = await loadConfig({ overrides: buildConfigOverrides(globalOpts) });
+    await withConnection({ server: opts.server, config: cfg }, async (client) => {
+      const rootState = client.state.root;
+      outputResult(
+        globalOpts,
+        () => {
+          if (rootState.agents.length === 0) {
+            console.log(pc6.dim("No agents available on this server."));
+            return;
+          }
+          for (const agent of rootState.agents) {
+            console.log(pc6.bold(pc6.cyan(agent.provider)), pc6.dim("\u2014"), agent.displayName);
+            if (agent.description) {
+              console.log(`  ${pc6.dim(agent.description)}`);
+            }
+            if (agent.models.length > 0) {
+              console.log(`  ${pc6.bold("Models:")}`);
+              for (const m of agent.models) {
+                console.log(`    ${pc6.cyan(m.id)}${m.name ? ` \u2014 ${m.name}` : ""}`);
+              }
+            }
+            console.log();
+          }
+        },
+        rootState.agents.map((a) => ({
+          provider: a.provider,
+          displayName: a.displayName,
+          description: a.description,
+          models: a.models.map((m) => ({ id: m.id, name: m.name }))
+        }))
+      );
+    });
+  } catch (err) {
+    handleError(err, globalOpts);
+  }
+});
+var completions = program.command("completions").description("Generate shell completion scripts");
+completions.command("bash").description("Print bash completion script").action(() => {
+  process.stdout.write(bashCompletion());
+});
+completions.command("zsh").description("Print zsh completion script").action(() => {
+  process.stdout.write(zshCompletion());
+});
+completions.command("fish").description("Print fish completion script").action(() => {
+  process.stdout.write(fishCompletion());
+});
+async function handleImplicitPrompt() {
+  const args = process.argv.slice(2);
+  const globalOpts = { format: "text", jsonStrict: false, verbose: false };
+  for (let i2 = 0; i2 < args.length; i2++) {
+    if (args[i2] === "--format" && i2 + 1 < args.length) {
+      globalOpts.format = args[i2 + 1];
+      i2++;
+    } else if (args[i2] === "--json-strict") {
+      globalOpts.jsonStrict = true;
+    } else if (args[i2] === "--verbose" || args[i2] === "-v") {
+      globalOpts.verbose = true;
+    }
+  }
+  applyGlobalOpts(globalOpts);
+  if (args.length === 0 && stdinIsPipe()) {
+    const text = await readStdin();
+    if (text) {
+      await runPrompt({ text }, globalOpts);
+      return true;
+    }
+    return false;
+  }
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  while (i < args.length) {
+    if (args[i] === "--format") {
+      i += 2;
+      continue;
+    }
+    if (args[i] === "--json-strict" || args[i] === "--verbose" || args[i] === "-v") {
+      i++;
+      continue;
+    }
+    if (args[i] === "--server" || args[i] === "-s") {
+      flags.server = args[++i];
+    } else if (args[i] === "--session-name" || args[i] === "-n") {
+      flags.sessionName = args[++i];
+    } else if (args[i] === "--cwd") {
+      flags.cwd = args[++i];
+    } else if (args[i] === "--approve-all") {
+      flags.approveAll = true;
+    } else if (args[i] === "--approve-reads") {
+      flags.approveReads = true;
+    } else if (args[i] === "--deny-all") {
+      flags.denyAll = true;
+    } else if (args[i] === "--file" || args[i] === "-f") {
+      flags.file = args[++i];
+    } else if (!args[i].startsWith("-")) {
+      positional.push(args[i]);
+    }
+    i++;
+  }
+  if (positional.length > 0) {
+    const knownCommands = /* @__PURE__ */ new Set([
+      "connect",
+      "server",
+      "config",
+      "session",
+      "prompt",
+      "exec",
+      "cancel",
+      "watch",
+      "browse",
+      "content",
+      "model",
+      "agents",
+      "completions",
+      "help",
+      "--help",
+      "-h",
+      "--version",
+      "-V"
+    ]);
+    if (!knownCommands.has(positional[0])) {
+      let text;
+      if (flags.file && typeof flags.file === "string") {
+        text = await readPromptFile(flags.file);
+      } else {
+        text = positional.join(" ");
+      }
+      if (text) {
+        await runPrompt(
+          {
+            text,
+            server: typeof flags.server === "string" ? flags.server : void 0,
+            sessionName: typeof flags.sessionName === "string" ? flags.sessionName : void 0,
+            cwd: typeof flags.cwd === "string" ? flags.cwd : void 0,
+            approveAll: flags.approveAll === true ? true : void 0,
+            approveReads: flags.approveReads === true ? true : void 0,
+            denyAll: flags.denyAll === true ? true : void 0
+          },
+          globalOpts
+        );
+        return true;
+      }
+    }
+  }
+  if (positional.length === 0 && stdinIsPipe()) {
+    const text = await readStdin();
+    if (text) {
+      await runPrompt({ text }, globalOpts);
+      return true;
+    }
+  }
+  return false;
+}
+(async () => {
+  try {
+    const handled = await handleImplicitPrompt();
+    if (!handled) {
+      program.hook("preAction", (thisCommand) => {
+        const globalOpts = parseGlobalOpts(thisCommand);
+        applyGlobalOpts(globalOpts);
+      });
+      program.parse();
+    }
+  } catch (err) {
+    const exitCode = err instanceof AhpxError ? err.exitCode : ExitCode.Error;
+    console.error(pc6.red("\u2717"), err instanceof Error ? err.message : String(err));
+    process.exitCode = exitCode;
+  }
+})();