@kmmao/happy-agent 0.2.0

package/dist/index.cjs

@@ -0,0 +1,1037 @@
+'use strict';
+
+var commander = require('commander');
+var node_os = require('node:os');
+var node_path = require('node:path');
+var node_fs = require('node:fs');
+var node_crypto = require('node:crypto');
+var tweetnacl = require('tweetnacl');
+var axios = require('axios');
+var qrcode = require('qrcode-terminal');
+var node_events = require('node:events');
+var socket_ioClient = require('socket.io-client');
+
+var version = "0.2.0";
+
+function loadConfig() {
+  const serverUrl = (process.env.HAPPY_SERVER_URL ?? "https://api.cluster-fluster.com").replace(/\/+$/, "");
+  const homeDir = process.env.HAPPY_HOME_DIR ?? node_path.join(node_os.homedir(), ".happy");
+  const credentialPath = node_path.join(homeDir, "agent.key");
+  return { serverUrl, homeDir, credentialPath };
+}
+
+function encodeBase64(buffer) {
+  return Buffer.from(buffer).toString("base64");
+}
+function decodeBase64(base64) {
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+function encodeBase64Url(buffer) {
+  return Buffer.from(buffer).toString("base64").replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+function getRandomBytes(size) {
+  return new Uint8Array(node_crypto.randomBytes(size));
+}
+function hmac_sha512(key, data) {
+  const hmac = node_crypto.createHmac("sha512", key);
+  hmac.update(data);
+  return new Uint8Array(hmac.digest());
+}
+function deriveSecretKeyTreeRoot(seed, usage) {
+  const I = hmac_sha512(new TextEncoder().encode(usage + " Master Seed"), seed);
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32)
+  };
+}
+function deriveSecretKeyTreeChild(chainCode, index) {
+  const data = new Uint8Array([0, ...new TextEncoder().encode(index)]);
+  const I = hmac_sha512(chainCode, data);
+  return {
+    key: I.slice(0, 32),
+    chainCode: I.slice(32)
+  };
+}
+function deriveKey(master, usage, path) {
+  let state = deriveSecretKeyTreeRoot(master, usage);
+  for (const index of path) {
+    state = deriveSecretKeyTreeChild(state.chainCode, index);
+  }
+  return state.key;
+}
+function deriveContentKeyPair(secret) {
+  const seed = deriveKey(secret, "Happy EnCoder", ["content"]);
+  const hashedSeed = new Uint8Array(node_crypto.createHash("sha512").update(seed).digest());
+  const boxSecretKey = hashedSeed.slice(0, 32);
+  const keyPair = tweetnacl.box.keyPair.fromSecretKey(boxSecretKey);
+  return { publicKey: keyPair.publicKey, secretKey: keyPair.secretKey };
+}
+function encryptWithDataKey(data, dataKey) {
+  const nonce = getRandomBytes(12);
+  const cipher = node_crypto.createCipheriv("aes-256-gcm", dataKey, nonce);
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  const bundle = new Uint8Array(1 + 12 + encrypted.length + 16);
+  bundle[0] = 0;
+  bundle.set(nonce, 1);
+  bundle.set(new Uint8Array(encrypted), 13);
+  bundle.set(new Uint8Array(authTag), 13 + encrypted.length);
+  return bundle;
+}
+function decryptWithDataKey(bundle, dataKey) {
+  if (bundle.length < 1 + 12 + 16) return null;
+  if (bundle[0] !== 0) return null;
+  const nonce = bundle.slice(1, 13);
+  const authTag = bundle.slice(bundle.length - 16);
+  const ciphertext = bundle.slice(13, bundle.length - 16);
+  try {
+    const decipher = node_crypto.createDecipheriv("aes-256-gcm", dataKey, nonce);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } catch {
+    return null;
+  }
+}
+function encryptLegacy(data, secret) {
+  const nonce = getRandomBytes(tweetnacl.secretbox.nonceLength);
+  const plaintext = new TextEncoder().encode(JSON.stringify(data));
+  const encrypted = tweetnacl.secretbox(plaintext, nonce, secret);
+  const result = new Uint8Array(nonce.length + encrypted.length);
+  result.set(nonce);
+  result.set(encrypted, nonce.length);
+  return result;
+}
+function decryptLegacy(data, secret) {
+  try {
+    const nonce = data.slice(0, tweetnacl.secretbox.nonceLength);
+    const encrypted = data.slice(tweetnacl.secretbox.nonceLength);
+    const decrypted = tweetnacl.secretbox.open(encrypted, nonce, secret);
+    if (!decrypted) return null;
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } catch {
+    return null;
+  }
+}
+function encrypt(key, variant, data) {
+  if (variant === "legacy") {
+    return encryptLegacy(data, key);
+  } else {
+    return encryptWithDataKey(data, key);
+  }
+}
+function decrypt(key, variant, data) {
+  if (variant === "legacy") {
+    return decryptLegacy(data, key);
+  } else {
+    return decryptWithDataKey(data, key);
+  }
+}
+function libsodiumEncryptForPublicKey(data, recipientPublicKey) {
+  const ephemeralKeyPair = tweetnacl.box.keyPair();
+  const nonce = getRandomBytes(tweetnacl.box.nonceLength);
+  const encrypted = tweetnacl.box(data, nonce, recipientPublicKey, ephemeralKeyPair.secretKey);
+  const result = new Uint8Array(32 + 24 + encrypted.length);
+  result.set(ephemeralKeyPair.publicKey, 0);
+  result.set(nonce, 32);
+  result.set(encrypted, 56);
+  return result;
+}
+function decryptBoxBundle(bundle, recipientSecretKey) {
+  if (bundle.length < 32 + 24) return null;
+  const ephemeralPublicKey = bundle.slice(0, 32);
+  const nonce = bundle.slice(32, 56);
+  const ciphertext = bundle.slice(56);
+  const decrypted = tweetnacl.box.open(ciphertext, nonce, ephemeralPublicKey, recipientSecretKey);
+  return decrypted ? new Uint8Array(decrypted) : null;
+}
+
+function readCredentials(config) {
+  try {
+    const raw = node_fs.readFileSync(config.credentialPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed.token || !parsed.secret) return null;
+    const secret = decodeBase64(parsed.secret);
+    const contentKeyPair = deriveContentKeyPair(secret);
+    return {
+      token: parsed.token,
+      secret,
+      contentKeyPair
+    };
+  } catch {
+    return null;
+  }
+}
+function writeCredentials(config, token, secret) {
+  node_fs.mkdirSync(node_path.dirname(config.credentialPath), { recursive: true, mode: 448 });
+  const data = JSON.stringify({ token, secret: encodeBase64(secret) });
+  node_fs.writeFileSync(config.credentialPath, data, { mode: 384 });
+}
+function clearCredentials(config) {
+  try {
+    node_fs.unlinkSync(config.credentialPath);
+  } catch {
+  }
+}
+function requireCredentials(config) {
+  const creds = readCredentials(config);
+  if (!creds) {
+    throw new Error("Not authenticated. Run `happy-agent auth login` first.");
+  }
+  return creds;
+}
+
+const POLL_INTERVAL_MS = 1e3;
+const AUTH_TIMEOUT_MS = 12e4;
+async function authLogin(config) {
+  const seed = getRandomBytes(32);
+  const keypair = tweetnacl.box.keyPair.fromSecretKey(seed);
+  const publicKeyBase64 = encodeBase64(keypair.publicKey);
+  try {
+    await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+      publicKey: publicKeyBase64
+    });
+  } catch (err) {
+    if (err instanceof axios.AxiosError) {
+      throw new Error(`Failed to initiate auth: ${err.message}`);
+    }
+    throw err;
+  }
+  const qrData = `happy:///account?${encodeBase64Url(keypair.publicKey)}`;
+  console.log("");
+  qrcode.generate(qrData, { small: true }, (code) => {
+    console.log(code);
+  });
+  console.log("## Authentication");
+  console.log("- Action: Scan this QR code with the Happy app");
+  console.log("- Path: Settings -> Account -> Link New Device");
+  console.log("");
+  const startTime = Date.now();
+  while (Date.now() - startTime < AUTH_TIMEOUT_MS) {
+    await sleep(POLL_INTERVAL_MS);
+    let result;
+    try {
+      const resp = await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+        publicKey: publicKeyBase64
+      });
+      result = resp.data;
+    } catch (err) {
+      if (err instanceof axios.AxiosError) {
+        throw new Error(`Auth polling failed: ${err.message}`);
+      }
+      throw err;
+    }
+    if (result.state === "authorized" && result.token && result.response) {
+      const encryptedResponse = decodeBase64(result.response);
+      const secret = decryptBoxBundle(encryptedResponse, keypair.secretKey);
+      if (!secret) {
+        throw new Error("Failed to decrypt auth response");
+      }
+      writeCredentials(config, result.token, secret);
+      console.log("## Authentication");
+      console.log("- Status: Authenticated");
+      return;
+    }
+  }
+  throw new Error("Authentication timed out. Please try again.");
+}
+async function authLogout(config) {
+  clearCredentials(config);
+  console.log("## Authentication");
+  console.log("- Status: Logged out");
+  console.log("- Credentials: Cleared");
+}
+async function authStatus(config) {
+  const creds = readCredentials(config);
+  console.log("## Authentication");
+  if (creds) {
+    console.log("- Status: Authenticated");
+    console.log(`- Public Key: \`${encodeBase64(creds.contentKeyPair.publicKey)}\``);
+  } else {
+    console.log("- Status: Not authenticated");
+    console.log("- Action: Run `happy-agent auth login` to authenticate.");
+  }
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function resolveSessionEncryption(session, creds) {
+  if (session.dataEncryptionKey) {
+    const encrypted = decodeBase64(session.dataEncryptionKey);
+    const bundle = encrypted.slice(1);
+    const sessionKey = decryptBoxBundle(bundle, creds.contentKeyPair.secretKey);
+    if (!sessionKey) {
+      throw new Error(
+        `Failed to decrypt session key for session ${session.id}`
+      );
+    }
+    return { key: sessionKey, variant: "dataKey" };
+  }
+  return { key: creds.secret, variant: "legacy" };
+}
+function decryptField(encrypted, encryption) {
+  if (!encrypted) return null;
+  const data = decodeBase64(encrypted);
+  if (encryption.variant === "dataKey") {
+    return decryptWithDataKey(data, encryption.key);
+  }
+  return decryptLegacy(data, encryption.key);
+}
+function decryptSession(raw, creds) {
+  const encryption = resolveSessionEncryption(raw, creds);
+  return {
+    id: raw.id,
+    seq: raw.seq,
+    createdAt: raw.createdAt,
+    updatedAt: raw.updatedAt,
+    active: raw.active,
+    activeAt: raw.activeAt,
+    metadata: decryptField(raw.metadata, encryption),
+    agentState: decryptField(raw.agentState, encryption),
+    dataEncryptionKey: raw.dataEncryptionKey,
+    encryption
+  };
+}
+function handleApiError(err, context) {
+  if (err instanceof axios.AxiosError) {
+    const status = err.response?.status;
+    if (status === 401) {
+      throw new Error(
+        "Authentication expired. Run `happy-agent auth login` to re-authenticate."
+      );
+    }
+    if (status === 403) {
+      throw new Error(`Forbidden: ${context}. Check your account permissions.`);
+    }
+    if (status === 404) {
+      throw new Error(`Not found: ${context}`);
+    }
+    if (status && status >= 400 && status < 500) {
+      const detail = err.response?.data ? `: ${JSON.stringify(err.response.data)}` : "";
+      throw new Error(`Request failed (${status})${detail}`);
+    }
+    if (status && status >= 500) {
+      throw new Error(`Server error (${status}): ${context}`);
+    }
+    throw new Error(`Request failed: ${err.message}`);
+  }
+  throw err;
+}
+function authHeaders(creds) {
+  return { Authorization: `Bearer ${creds.token}` };
+}
+async function listSessions(config, creds) {
+  const allSessions = [];
+  let cursor;
+  while (true) {
+    const params = { limit: "100" };
+    if (cursor) params.cursor = cursor;
+    let data;
+    try {
+      const resp = await axios.get(`${config.serverUrl}/v2/sessions`, {
+        headers: authHeaders(creds),
+        params
+      });
+      data = resp.data;
+    } catch (err) {
+      handleApiError(err, "listing sessions");
+    }
+    allSessions.push(...data.sessions);
+    if (!data.nextCursor || data.sessions.length === 0) break;
+    cursor = data.nextCursor;
+  }
+  return allSessions.map((raw) => decryptSession(raw, creds));
+}
+async function listActiveSessions(config, creds) {
+  let data;
+  try {
+    const resp = await axios.get(`${config.serverUrl}/v2/sessions/active`, {
+      headers: authHeaders(creds)
+    });
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "listing active sessions");
+  }
+  return data.sessions.map((raw) => decryptSession(raw, creds));
+}
+async function createSession(config, creds, opts) {
+  const sessionKey = getRandomBytes(32);
+  const encryptedKey = libsodiumEncryptForPublicKey(
+    sessionKey,
+    creds.contentKeyPair.publicKey
+  );
+  const withVersion = new Uint8Array(1 + encryptedKey.length);
+  withVersion[0] = 0;
+  withVersion.set(encryptedKey, 1);
+  const dataEncryptionKeyBase64 = encodeBase64(withVersion);
+  const encryptedMetadata = encryptWithDataKey(opts.metadata, sessionKey);
+  const metadataBase64 = encodeBase64(encryptedMetadata);
+  let data;
+  try {
+    const resp = await axios.post(
+      `${config.serverUrl}/v1/sessions`,
+      {
+        tag: opts.tag,
+        metadata: metadataBase64,
+        dataEncryptionKey: dataEncryptionKeyBase64
+      },
+      { headers: authHeaders(creds) }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, "creating session");
+  }
+  const decrypted = decryptSession(data.session, creds);
+  return { ...decrypted, sessionKey: decrypted.encryption.key };
+}
+async function deleteSession(config, creds, sessionId) {
+  try {
+    await axios.delete(
+      `${config.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}`,
+      {
+        headers: authHeaders(creds)
+      }
+    );
+  } catch (err) {
+    handleApiError(err, `deleting session ${sessionId}`);
+  }
+}
+async function getSessionMessages(config, creds, sessionId, encryption) {
+  let data;
+  try {
+    const resp = await axios.get(
+      `${config.serverUrl}/v1/sessions/${encodeURIComponent(sessionId)}/messages`,
+      { headers: authHeaders(creds) }
+    );
+    data = resp.data;
+  } catch (err) {
+    handleApiError(err, `session ${sessionId} messages`);
+  }
+  return data.messages.map((msg) => ({
+    id: msg.id,
+    seq: msg.seq,
+    content: decryptField(msg.content.c, encryption),
+    localId: msg.localId ?? null,
+    createdAt: msg.createdAt,
+    updatedAt: msg.updatedAt
+  }));
+}
+
+class SessionClient extends node_events.EventEmitter {
+  sessionId;
+  encryptionKey;
+  encryptionVariant;
+  socket;
+  metadata = null;
+  metadataVersion = 0;
+  agentState = null;
+  agentStateVersion = 0;
+  aliveInterval = null;
+  constructor(opts) {
+    super();
+    this.sessionId = opts.sessionId;
+    this.encryptionKey = opts.encryptionKey;
+    this.encryptionVariant = opts.encryptionVariant;
+    if (opts.initialAgentState !== void 0) {
+      this.agentState = opts.initialAgentState;
+    }
+    this.on("error", () => {
+    });
+    this.socket = socket_ioClient.io(opts.serverUrl, {
+      auth: {
+        token: opts.token,
+        clientType: "session-scoped",
+        sessionId: opts.sessionId
+      },
+      path: "/v1/updates",
+      reconnection: true,
+      reconnectionAttempts: Infinity,
+      reconnectionDelay: 1e3,
+      reconnectionDelayMax: 5e3,
+      transports: ["websocket"],
+      autoConnect: false
+    });
+    this.socket.on("connect", () => {
+      this.emit("connected");
+      this.aliveInterval = setInterval(() => {
+        this.socket.emit("session-alive", {
+          sid: this.sessionId,
+          time: Date.now()
+        });
+      }, 2e4);
+    });
+    this.socket.on("disconnect", (reason) => {
+      if (this.aliveInterval !== null) {
+        clearInterval(this.aliveInterval);
+        this.aliveInterval = null;
+      }
+      this.emit("disconnected", reason);
+    });
+    this.socket.on("connect_error", (error) => {
+      this.emit("connect_error", error);
+    });
+    this.socket.on("update", (data) => {
+      try {
+        const body = data?.body;
+        if (!body) return;
+        if (body.t === "new-message" && body.message?.content?.t === "encrypted") {
+          const msg = body.message;
+          const decrypted = decrypt(
+            this.encryptionKey,
+            this.encryptionVariant,
+            decodeBase64(msg.content.c)
+          );
+          if (decrypted === null) return;
+          this.emit("message", {
+            id: msg.id,
+            seq: msg.seq,
+            content: decrypted,
+            localId: msg.localId,
+            createdAt: msg.createdAt,
+            updatedAt: msg.updatedAt
+          });
+        } else if (body.t === "update-session") {
+          if (body.metadata && body.metadata.version > this.metadataVersion) {
+            this.metadata = decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.metadata.value)
+            );
+            this.metadataVersion = body.metadata.version;
+          }
+          if (body.agentState && body.agentState.version > this.agentStateVersion) {
+            this.agentState = body.agentState.value ? decrypt(
+              this.encryptionKey,
+              this.encryptionVariant,
+              decodeBase64(body.agentState.value)
+            ) : null;
+            this.agentStateVersion = body.agentState.version;
+          }
+          this.emit("state-change", {
+            metadata: this.metadata,
+            agentState: this.agentState
+          });
+        }
+      } catch (err) {
+        this.emit("error", err);
+      }
+    });
+    this.socket.connect();
+  }
+  sendMessage(text, meta) {
+    const content = {
+      role: "user",
+      content: {
+        type: "text",
+        text
+      },
+      meta: {
+        sentFrom: "happy-agent",
+        ...meta
+      }
+    };
+    const encrypted = encodeBase64(
+      encrypt(this.encryptionKey, this.encryptionVariant, content)
+    );
+    this.socket.emit("message", {
+      sid: this.sessionId,
+      message: encrypted
+    });
+  }
+  getMetadata() {
+    return this.metadata;
+  }
+  getAgentState() {
+    return this.agentState;
+  }
+  waitForConnect(timeoutMs = 1e4) {
+    return new Promise((resolve, reject) => {
+      if (this.socket.connected) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        this.removeListener("connected", onConnect);
+        this.removeListener("connect_error", onError);
+        reject(new Error("Timeout waiting for socket connection"));
+      }, timeoutMs);
+      const onConnect = () => {
+        clearTimeout(timeout);
+        this.removeListener("connect_error", onError);
+        resolve();
+      };
+      const onError = (err) => {
+        clearTimeout(timeout);
+        this.removeListener("connected", onConnect);
+        reject(err);
+      };
+      this.once("connected", onConnect);
+      this.once("connect_error", onError);
+    });
+  }
+  waitForIdle(timeoutMs = 3e5) {
+    return new Promise((resolve, reject) => {
+      const checkIdle = () => {
+        const meta = this.metadata;
+        if (meta?.lifecycleState === "archived") {
+          return "archived";
+        }
+        const state = this.agentState;
+        if (!state) {
+          return false;
+        }
+        const controlledByUser = state.controlledByUser === true;
+        const requests = state.requests;
+        const hasRequests = requests != null && typeof requests === "object" && !Array.isArray(requests) && Object.keys(requests).length > 0;
+        return !controlledByUser && !hasRequests;
+      };
+      const cleanup = () => {
+        clearTimeout(timeout);
+        this.removeListener("state-change", onStateChange);
+        this.removeListener("disconnected", onDisconnect);
+      };
+      const result = checkIdle();
+      if (result === "archived") {
+        reject(new Error("Session is archived"));
+        return;
+      }
+      if (result === true) {
+        resolve();
+        return;
+      }
+      const timeout = setTimeout(() => {
+        cleanup();
+        reject(new Error("Timeout waiting for agent to become idle"));
+      }, timeoutMs);
+      const onStateChange = () => {
+        const r = checkIdle();
+        if (r === "archived") {
+          cleanup();
+          reject(new Error("Session is archived"));
+        } else if (r === true) {
+          cleanup();
+          resolve();
+        }
+      };
+      const onDisconnect = () => {
+        cleanup();
+        reject(
+          new Error(
+            "Socket disconnected while waiting for agent to become idle"
+          )
+        );
+      };
+      this.on("state-change", onStateChange);
+      this.on("disconnected", onDisconnect);
+    });
+  }
+  sendStop() {
+    this.socket.emit("session-end", {
+      sid: this.sessionId,
+      time: Date.now()
+    });
+  }
+  close() {
+    if (this.aliveInterval !== null) {
+      clearInterval(this.aliveInterval);
+      this.aliveInterval = null;
+    }
+    this.socket.close();
+  }
+}
+
+function formatTime(ts) {
+  if (!ts) return "-";
+  const date = new Date(ts);
+  const now = /* @__PURE__ */ new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMin = Math.floor(diffMs / 6e4);
+  if (diffMin < 1) return "just now";
+  if (diffMin < 60) return `${diffMin}m ago`;
+  const diffHr = Math.floor(diffMin / 60);
+  if (diffHr < 24) return `${diffHr}h ago`;
+  const diffDay = Math.floor(diffHr / 24);
+  return `${diffDay}d ago`;
+}
+function formatIsoTime(ts) {
+  if (!ts) return "-";
+  const date = new Date(ts);
+  if (Number.isNaN(date.getTime())) return "-";
+  return date.toISOString();
+}
+function formatLastActive(ts) {
+  const relative = formatTime(ts);
+  const absolute = formatIsoTime(ts);
+  if (absolute === "-") return relative;
+  return `${relative} (${absolute})`;
+}
+function toMarkdownInline(value) {
+  const escaped = value.replace(/`/g, "\\`");
+  return `\`${escaped}\``;
+}
+function normalizeCodeBlockText(value) {
+  const text = value.trim().length > 0 ? value : "(empty)";
+  return text.replace(/```/g, "``\\`");
+}
+function normalizeListValue(value) {
+  return value.replace(/\r?\n/g, " ").trim();
+}
+function toNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+}
+function extractSessionSummary(meta) {
+  const direct = toNonEmptyString(meta.summary);
+  if (direct) return direct;
+  if (meta.summary != null && typeof meta.summary === "object") {
+    return toNonEmptyString(meta.summary.text);
+  }
+  return void 0;
+}
+function formatSessionTable(sessions) {
+  if (sessions.length === 0) {
+    return "## Sessions\n\n- Total: 0\n- Items: none";
+  }
+  const sections = sessions.map((s, index) => {
+    const meta = s.metadata ?? {};
+    const name = normalizeListValue(extractSessionSummary(meta) ?? toNonEmptyString(meta.tag) ?? "-");
+    const path = normalizeListValue(toNonEmptyString(meta.path) ?? "-");
+    const status = s.active ? "active" : "inactive";
+    const lastActive = normalizeListValue(formatLastActive(s.activeAt));
+    return [
+      `### Session ${index + 1}`,
+      `- ID: ${toMarkdownInline(s.id)}`,
+      `- Name: ${name}`,
+      `- Path: ${path}`,
+      `- Status: ${status}`,
+      `- Last Active: ${lastActive}`
+    ].join("\n");
+  });
+  return `## Sessions
+
+- Total: ${sessions.length}
+
+${sections.join("\n\n")}`;
+}
+function formatSessionStatus(session) {
+  const meta = session.metadata ?? {};
+  const state = session.agentState ?? null;
+  const tag = toNonEmptyString(meta.tag);
+  const summary = extractSessionSummary(meta);
+  const path = toNonEmptyString(meta.path);
+  const host = toNonEmptyString(meta.host);
+  const lifecycleState = toNonEmptyString(meta.lifecycleState);
+  const lines = [
+    "## Session Status",
+    "",
+    `- Session ID: ${toMarkdownInline(session.id)}`
+  ];
+  if (tag) lines.push(`- Tag: ${tag}`);
+  if (summary) lines.push(`- Summary: ${summary}`);
+  if (path) lines.push(`- Path: ${path}`);
+  if (host) lines.push(`- Host: ${host}`);
+  if (lifecycleState) lines.push(`- Lifecycle: ${lifecycleState}`);
+  lines.push(`- Active: ${session.active ? "yes" : "no"}`);
+  lines.push(`- Last Active: ${formatLastActive(session.activeAt)}`);
+  if (state) {
+    const requests = state.requests != null && typeof state.requests === "object" ? Object.keys(state.requests).length : 0;
+    const busy = state.controlledByUser === true || requests > 0;
+    const agentStatus = busy ? "busy" : "idle";
+    lines.push(`- Agent: ${agentStatus}`);
+    if (requests > 0) {
+      lines.push(`- Pending Requests: ${requests}`);
+    }
+  } else {
+    lines.push("- Agent: no state");
+  }
+  return lines.join("\n");
+}
+function formatMessageHistory(messages) {
+  if (messages.length === 0) {
+    return "## Message History\n\n- Count: 0\n- Items: none";
+  }
+  const sections = messages.map((msg, index) => {
+    const content = msg.content;
+    const role = content?.role ?? "unknown";
+    const timestamp = formatIsoTime(msg.createdAt);
+    let text;
+    if (content?.content && typeof content.content === "object" && content.content.text) {
+      text = String(content.content.text);
+    } else if (content?.content && typeof content.content === "string") {
+      text = content.content;
+    } else {
+      text = JSON.stringify(content);
+    }
+    return [
+      `### Message ${index + 1}`,
+      `- ID: ${toMarkdownInline(msg.id)}`,
+      `- Time: ${timestamp}`,
+      `- Role: ${role}`,
+      "- Text:",
+      "```text",
+      normalizeCodeBlockText(text),
+      "```"
+    ].join("\n");
+  });
+  return `## Message History
+
+- Count: ${messages.length}
+
+${sections.join("\n\n")}`;
+}
+function formatJson(data) {
+  return JSON.stringify(data, (key, value) => {
+    if (key === "encryption" || key === "dataEncryptionKey") return void 0;
+    if (value instanceof Uint8Array) {
+      return Buffer.from(value).toString("base64");
+    }
+    return value;
+  }, 2);
+}
+
+async function resolveSession(config, creds, sessionId) {
+  if (!sessionId || sessionId.trim().length === 0) {
+    throw new Error("Session ID is required");
+  }
+  const sessions = await listSessions(config, creds);
+  const matches = sessions.filter((s) => s.id.startsWith(sessionId));
+  if (matches.length === 0) {
+    throw new Error(`No session found matching "${sessionId}"`);
+  }
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous session ID "${sessionId}" matches ${matches.length} sessions. Be more specific.`
+    );
+  }
+  return matches[0];
+}
+function createClient(session, creds, config) {
+  return new SessionClient({
+    sessionId: session.id,
+    encryptionKey: session.encryption.key,
+    encryptionVariant: session.encryption.variant,
+    token: creds.token,
+    serverUrl: config.serverUrl,
+    initialAgentState: session.agentState ?? null
+  });
+}
+const program = new commander.Command();
+program.name("happy-agent").description("CLI client for controlling Happy Coder agents remotely").version(version);
+program.command("auth").description("Manage authentication").addCommand(
+  new commander.Command("login").description("Authenticate via QR code").action(async () => {
+    const config = loadConfig();
+    await authLogin(config);
+  })
+).addCommand(
+  new commander.Command("logout").description("Clear stored credentials").action(async () => {
+    const config = loadConfig();
+    await authLogout(config);
+  })
+).addCommand(
+  new commander.Command("status").description("Show authentication status").action(async () => {
+    const config = loadConfig();
+    await authStatus(config);
+  })
+);
+program.command("list").description("List all sessions").option("--active", "Show only active sessions").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const sessions = opts.active ? await listActiveSessions(config, creds) : await listSessions(config, creds);
+  if (opts.json) {
+    console.log(formatJson(sessions));
+  } else {
+    console.log(formatSessionTable(sessions));
+  }
+});
+program.command("status").description("Get live session state").argument("<session-id>", "Session ID or prefix").option("--json", "Output as JSON").action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  let liveData = false;
+  try {
+    await new Promise((resolve) => {
+      let resolved = false;
+      const done = () => {
+        if (resolved) return;
+        resolved = true;
+        clearTimeout(timeout);
+        client.removeAllListeners("state-change");
+        client.removeAllListeners("connect_error");
+        resolve();
+      };
+      const timeout = setTimeout(done, 3e3);
+      client.once(
+        "state-change",
+        (data) => {
+          session.metadata = data.metadata ?? session.metadata;
+          session.agentState = data.agentState ?? session.agentState;
+          liveData = true;
+          done();
+        }
+      );
+      client.once("connect_error", () => {
+        done();
+      });
+    });
+  } finally {
+    client.close();
+  }
+  if (opts.json) {
+    console.log(formatJson(session));
+  } else {
+    if (!liveData) {
+      console.log("> Note: showing cached data (could not get live status).");
+    }
+    console.log(formatSessionStatus(session));
+  }
+});
+program.command("create").description("Create a new session").requiredOption("--tag <tag>", "Session tag").option("--path <path>", "Working directory path").option("--json", "Output as JSON").action(async (opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const metadata = {
+    tag: opts.tag,
+    path: opts.path ?? process.cwd(),
+    host: node_os.hostname()
+  };
+  const session = await createSession(config, creds, {
+    tag: opts.tag,
+    metadata
+  });
+  if (opts.json) {
+    console.log(formatJson(session));
+  } else {
+    console.log(
+      ["## Session Created", "", `- Session ID: \`${session.id}\``].join(
+        "\n"
+      )
+    );
+  }
+});
+program.command("send").description("Send a message to a session").argument("<session-id>", "Session ID or prefix").argument("<message>", "Message text").option("--wait", "Wait for agent to become idle").option(
+  "--timeout <seconds>",
+  "Timeout in seconds when using --wait",
+  (v) => {
+    const n = parseInt(v, 10);
+    if (isNaN(n) || n <= 0)
+      throw new Error("--timeout must be a positive integer");
+    return n;
+  },
+  300
+).option("--json", "Output as JSON").action(
+  async (sessionId, message, opts) => {
+    const config = loadConfig();
+    const creds = requireCredentials(config);
+    const session = await resolveSession(config, creds, sessionId);
+    const client = createClient(session, creds, config);
+    try {
+      await client.waitForConnect();
+      client.sendMessage(message);
+      if (opts.wait) {
+        await client.waitForIdle(opts.timeout * 1e3);
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    } finally {
+      client.close();
+    }
+    if (opts.json) {
+      console.log(formatJson({ sessionId: session.id, message, sent: true }));
+    } else {
+      console.log(
+        [
+          "## Message Sent",
+          "",
+          `- Session ID: \`${session.id}\``,
+          `- Waited For Idle: ${opts.wait ? "yes" : "no"}`
+        ].join("\n")
+      );
+    }
+  }
+);
+program.command("history").description("Read message history").argument("<session-id>", "Session ID or prefix").option("--limit <n>", "Limit number of messages", (v) => {
+  const n = parseInt(v, 10);
+  if (isNaN(n) || n <= 0)
+    throw new Error("--limit must be a positive integer");
+  return n;
+}).option("--json", "Output as JSON").action(
+  async (sessionId, opts) => {
+    const config = loadConfig();
+    const creds = requireCredentials(config);
+    const session = await resolveSession(config, creds, sessionId);
+    let messages = await getSessionMessages(
+      config,
+      creds,
+      session.id,
+      session.encryption
+    );
+    messages.sort((a, b) => a.createdAt - b.createdAt);
+    if (opts.limit && opts.limit > 0) {
+      messages = messages.slice(-opts.limit);
+    }
+    if (opts.json) {
+      console.log(formatJson(messages));
+    } else {
+      console.log(formatMessageHistory(messages));
+    }
+  }
+);
+program.command("stop").description("Stop a session").argument("<session-id>", "Session ID or prefix").action(async (sessionId) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  try {
+    await client.waitForConnect();
+    client.sendStop();
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  } finally {
+    client.close();
+  }
+  console.log(
+    ["## Session Stopped", "", `- Session ID: \`${session.id}\``].join("\n")
+  );
+});
+program.command("delete").description("Delete a session permanently").argument("<session-id>", "Session ID or prefix").action(async (sessionId) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  await deleteSession(config, creds, session.id);
+  console.log(
+    ["## Session Deleted", "", `- Session ID: \`${session.id}\``].join("\n")
+  );
+});
+program.command("wait").description("Wait for agent to become idle").argument("<session-id>", "Session ID or prefix").option(
+  "--timeout <seconds>",
+  "Timeout in seconds",
+  (v) => {
+    const n = parseInt(v, 10);
+    if (isNaN(n) || n <= 0)
+      throw new Error("--timeout must be a positive integer");
+    return n;
+  },
+  300
+).action(async (sessionId, opts) => {
+  const config = loadConfig();
+  const creds = requireCredentials(config);
+  const session = await resolveSession(config, creds, sessionId);
+  const client = createClient(session, creds, config);
+  try {
+    await client.waitForConnect();
+    await client.waitForIdle(opts.timeout * 1e3);
+    console.log(
+      ["## Session Idle", "", `- Session ID: \`${session.id}\``].join("\n")
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(msg);
+    process.exitCode = 1;
+  } finally {
+    client.close();
+  }
+});
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exitCode = 1;
+});