@indigoai-us/hq-cli 5.77.14 → 5.79.0

package/src/commands/dm.ts

@@ -1,1226 +0,0 @@
-import { Command } from "commander";
-import chalk from "chalk";
-import { readFileSync } from "node:fs";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
-
-const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
-// People (prs_) and agents (agt_) are both first-class DM participants; the
-// server applies the same membership-overlap gate to either and delivers
-// agt_* recipients into the agent's durable box inbox.
-const RECIPIENT_UID_PATTERN = /^(prs|agt)_[A-Za-z0-9_-]+$/;
-
-export interface DmRecipient {
-  toEmail?: string;
-  toPersonUid?: string;
-}
-
-/**
- * Classify a recipient arg as an email or a person/agent uid. Mirrors the
- * email/uid heuristic used by `hq members`. Returns null for neither.
- * Agent uids (agt_*) ride the same `toPersonUid` wire field — that is the
- * server contract (POST /v1/notify/dm accepts prs_* or agt_*).
- */
-export function detectRecipient(recipient: string): DmRecipient | null {
-  const r = recipient.trim();
-  if (EMAIL_PATTERN.test(r)) return { toEmail: r.toLowerCase() };
-  if (RECIPIENT_UID_PATTERN.test(r)) return { toPersonUid: r };
-  return null;
-}
-
-/**
- * A comma in the recipient arg signals a GROUP DM. Split into trimmed, de-duped
- * recipient tokens (emails or personUids). Returns null when there's no comma
- * (the normal 1:1 path). Pure → unit-testable.
- */
-export function parseGroupRecipients(recipient: string): string[] | null {
-  if (!recipient.includes(",")) return null;
-  const parts = recipient
-    .split(",")
-    .map((s) => s.trim())
-    .filter(Boolean);
-  return [...new Set(parts)];
-}
-
-/**
- * Normalize a channel name into a stable slug for name matching. MIRRORS the
- * server's `channelSlug` (hq-pro src/vault-service/lib/channels.ts): lowercase,
- * collapse runs of non-alphanumerics to single hyphens, trim leading/trailing
- * hyphens. Keep in lockstep with the server so `hq dm vyg-dev` matches the
- * channel the server stored as slug `vyg-dev`. Pure → unit-testable.
- */
-export function channelSlug(name: string): string {
-  return name
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-}
-
-/**
- * Decide whether a positional recipient token addresses a DM CHANNEL by name
- * (rather than a person/agent or a group). Returns the bare channel name to
- * resolve, or null when the token is a person path (email / prs_ / agt_ uid) or
- * a comma group. Pure → unit-testable.
- *
- *   "#vyg-dev" → "vyg-dev"   (explicit hash form)
- *   "vyg-dev"  → "vyg-dev"   (bare name — not an email/uid/group)
- *   "a@b.com"  → null        (person)
- *   "prs_…"    → null        (person)   "agt_…" → null (agent)
- *   "a@x,b@y"  → null        (group DM)
- */
-export function parseChannelName(recipient: string): string | null {
-  const r = recipient.trim();
-  if (!r) return null;
-  if (r.startsWith("#")) {
-    const name = r.slice(1).trim();
-    return name || null;
-  }
-  // A comma is the group-DM signal; emails and prs_/agt_ uids are person paths.
-  if (r.includes(",")) return null;
-  if (EMAIL_PATTERN.test(r)) return null;
-  if (RECIPIENT_UID_PATTERN.test(r)) return null;
-  return r;
-}
-
-/** Minimal channel shape the CLI reads back from GET /v1/notify/channels. */
-export interface ChannelSummary {
-  channelId: string;
-  name?: string;
-  slug?: string;
-  scope?: string;
-  memberCount?: number;
-  members?: { personUid: string; displayName?: string }[];
-}
-
-/**
- * Find the caller's channel(s) whose name matches `name`, by slug or
- * case-insensitive display name. Group DMs are unnamed (participant-keyed), so
- * they never match a name. Returns ALL matches so the caller can detect an
- * ambiguous name (same slug across personal + company scope). Pure →
- * unit-testable.
- */
-export function matchChannelsByName(
-  channels: ChannelSummary[],
-  name: string,
-): ChannelSummary[] {
-  const targetSlug = channelSlug(name);
-  const targetName = name.trim().toLowerCase();
-  if (!targetSlug && !targetName) return [];
-  return channels.filter((c) => {
-    if (c.scope === "group") return false;
-    const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
-    if (slug && slug === targetSlug) return true;
-    if (c.name && c.name.trim().toLowerCase() === targetName) return true;
-    return false;
-  });
-}
-
-/**
- * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
- * Returns null on anything that doesn't match. Pure → unit-testable.
- */
-export function parseDuration(input: string): number | null {
-  const m = /^(\d+)\s*(s|m|h|d)$/.exec(input.trim());
-  if (!m) return null;
-  const n = parseInt(m[1], 10);
-  const mult: Record<string, number> = {
-    s: 1000,
-    m: 60_000,
-    h: 3_600_000,
-    d: 86_400_000,
-  };
-  return n * mult[m[2]];
-}
-
-export interface DmSendBody {
-  toEmail?: string;
-  toPersonUid?: string;
-  body: string;
-  prompt?: string;
-  details?: string;
-  deliverAt?: string;
-}
-
-/**
- * Build the POST /v1/notify/dm request body from CLI inputs. Pure (no I/O,
- * no clock) so the option-resolution logic is unit-testable; the caller
- * supplies `now` for the `--in` relative-delay computation.
- *
- * Throws Error with a user-facing message on invalid input.
- */
-export function buildDmBody(args: {
-  recipient: string;
-  message: string;
-  prompt?: string;
-  details?: string;
-  at?: string;
-  inDelay?: string;
-  now: number;
-}): DmSendBody {
-  const rcpt = detectRecipient(args.recipient);
-  if (!rcpt) {
-    throw new Error(
-      `Invalid recipient '${args.recipient}': must be an email address, a personUid (prs_…), or an agentUid (agt_…).`,
-    );
-  }
-  const body = (args.message ?? "").trim();
-  if (!body) {
-    throw new Error("A message body is required: hq dm <recipient> <message>");
-  }
-
-  if (args.at && args.inDelay) {
-    throw new Error("Use only one of --at or --in, not both.");
-  }
-  let deliverAt: string | undefined;
-  if (args.at) {
-    const when = new Date(args.at);
-    if (isNaN(when.getTime())) {
-      throw new Error(`Invalid --at '${args.at}': must be an ISO8601 date.`);
-    }
-    deliverAt = when.toISOString();
-  } else if (args.inDelay) {
-    const ms = parseDuration(args.inDelay);
-    if (ms === null) {
-      throw new Error(
-        `Invalid --in '${args.inDelay}': use a relative delay like 30s, 10m, 2h, 1d.`,
-      );
-    }
-    deliverAt = new Date(args.now + ms).toISOString();
-  }
-
-  const prompt = args.prompt?.trim();
-  const details = args.details?.trim();
-
-  return {
-    ...rcpt,
-    body,
-    ...(prompt ? { prompt } : {}),
-    ...(details ? { details } : {}),
-    ...(deliverAt ? { deliverAt } : {}),
-  };
-}
-
-function friendlyDmError(status: number, code: string | undefined, fallback: string): string {
-  if (status === 401) return "Not authenticated — run `hq login` and try again.";
-  if (status === 404 || code === "RECIPIENT_NOT_FOUND") {
-    return "Recipient not found or not reachable — you can only DM someone you share an active company with.";
-  }
-  if (status >= 500) return `Server error: ${fallback}`;
-  return fallback;
-}
-
-/** A pending incoming connection request, as returned by the backend. */
-export interface ConnectionRequest {
-  pairKey: string;
-  fromPersonUid: string;
-  fromDisplayName?: string;
-  fromEmail?: string;
-  message?: string;
-  createdAt?: string;
-}
-
-/**
- * Resolve a connection request from a pending-requests list by a caller-supplied
- * identifier (email, personUid, or pairKey). Pure → unit-testable.
- *
- * Matching is case-insensitive for emails. Returns the matched request, or null
- * if no request matches.
- */
-export function matchRequest(
-  requests: ConnectionRequest[],
-  identifier: string,
-): ConnectionRequest | null {
-  const id = identifier.trim();
-  const idLower = id.toLowerCase();
-  for (const r of requests) {
-    if (r.pairKey === id) return r;
-    if (r.fromPersonUid === id) return r;
-    if (r.fromEmail && r.fromEmail.toLowerCase() === idLower) return r;
-  }
-  return null;
-}
-
-/**
- * Build the POST body for an accept/decline/block action. Prefers a resolved
- * pairKey (from a matched pending request); otherwise falls back to the
- * recipient identifier the backend can resolve (`withPersonUid` for a prs_ UID,
- * `toEmail`-style is not supported by the connections endpoints so we send
- * `withEmail`). Pure → unit-testable.
- *
- * Throws Error with a user-facing message when the identifier can't be resolved.
- */
-export function buildConnectionActionBody(
-  identifier: string,
-  matched: ConnectionRequest | null,
-): { pairKey: string } | { withPersonUid: string } | { withEmail: string } {
-  if (matched) {
-    return { pairKey: matched.pairKey };
-  }
-  const r = identifier.trim();
-  const rcpt = detectRecipient(r);
-  if (rcpt?.toPersonUid) return { withPersonUid: rcpt.toPersonUid };
-  if (rcpt?.toEmail) return { withEmail: rcpt.toEmail };
-  throw new Error(
-    `Could not resolve '${identifier}' to a pending request — pass the requester's email, personUid, or the pairKey from \`hq dm requests\`.`,
-  );
-}
-
-const CONNECTION_ACTIONS = {
-  accept: { path: "accept", done: "Connection accepted" },
-  decline: { path: "decline", done: "Request declined" },
-  block: { path: "block", done: "Blocked" },
-} as const;
-
-type ConnectionAction = keyof typeof CONNECTION_ACTIONS;
-
-/** Fetch the caller's pending incoming connection requests. */
-async function fetchRequests(token: string): Promise<ConnectionRequest[]> {
-  const res = await vaultApiFetch({
-    token,
-    path: "/v1/notify/connections/requests",
-  });
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new Error(
-      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-    );
-  }
-  const data = (await res.json()) as { requests?: ConnectionRequest[] };
-  return data.requests ?? [];
-}
-
-async function runConnectionAction(
-  action: ConnectionAction,
-  identifier: string,
-): Promise<void> {
-  try {
-    const token = await ensureCognitoToken();
-    // Resolve the pairKey from the caller's pending requests when possible so
-    // accept/decline/block work against a friendly email or personUid.
-    const requests = await fetchRequests(token).catch(() => [] as ConnectionRequest[]);
-    const matched = matchRequest(requests, identifier);
-    const body = buildConnectionActionBody(identifier, matched);
-
-    const res = await vaultApiFetch({
-      token,
-      path: `/v1/notify/connections/${CONNECTION_ACTIONS[action].path}`,
-      method: "POST",
-      body: body as unknown as Record<string, unknown>,
-    });
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-
-    const who = matched?.fromDisplayName ?? matched?.fromEmail ?? identifier;
-    console.log(chalk.green(`${CONNECTION_ACTIONS[action].done} — ${who}.`));
-    if (action === "accept" && matched?.message) {
-      console.log(chalk.dim("Their held message will now be delivered."));
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-interface DmSendOpts {
-  prompt?: string;
-  promptFile?: string;
-  details?: string;
-  detailsFile?: string;
-  at?: string;
-  in?: string;
-  channel?: string;
-}
-
-/**
- * Group DM path: `hq dm send "a@x.com,b@y.com" "msg"`. Creates (or reopens, via
- * the server's idempotent participant-key dedupe) a group channel, then posts
- * the message into it. Reuses the same vault API client + auth as the 1:1 path.
- */
-async function runGroupSend(
-  recipients: string[],
-  message: string | undefined,
-): Promise<void> {
-  try {
-    const participants: string[] = [];
-    for (const r of recipients) {
-      const rc = detectRecipient(r);
-      if (!rc) {
-        console.error(
-          chalk.red(
-            `Invalid recipient '${r}': each must be an email address or a personUid (prs_…).`,
-          ),
-        );
-        process.exit(1);
-      }
-      // Group DMs are channels — agents don't participate in channels (their
-      // DM surface is 1:1 via the durable box inbox). DM an agent directly.
-      if (rc.toPersonUid?.startsWith("agt_")) {
-        console.error(
-          chalk.red(
-            `Agents can't join group DMs yet — DM '${r}' directly: hq dm ${r} "<message>".`,
-          ),
-        );
-        process.exit(1);
-      }
-      participants.push(rc.toEmail ?? rc.toPersonUid!);
-    }
-    if (participants.length < 2) {
-      console.error(
-        chalk.red(
-          'A group DM needs at least 2 other people — list them comma-separated, e.g. hq dm send "a@x.com,b@y.com" "hi".',
-        ),
-      );
-      process.exit(1);
-    }
-    const body = (message ?? "").trim();
-    if (!body) {
-      console.error(
-        chalk.red('A message body is required: hq dm send "a@x,b@y" <message>'),
-      );
-      process.exit(1);
-    }
-
-    const token = await ensureCognitoToken();
-
-    // 1) Create or reopen the group (idempotent on the participant set).
-    const createRes = await vaultApiFetch({
-      token,
-      path: "/v1/notify/channels",
-      method: "POST",
-      body: { scope: "group", participants },
-    });
-    if (!createRes.ok) {
-      const err = (await createRes.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(
-            createRes.status,
-            err.code,
-            err.error ?? err.message ?? createRes.statusText,
-          ),
-        ),
-      );
-      process.exit(1);
-    }
-    const createData = (await createRes.json()) as {
-      channel?: { channelId?: string };
-      created?: boolean;
-    };
-    const channelId = createData.channel?.channelId;
-    if (!channelId) {
-      console.error(chalk.red("Group create returned no channel id."));
-      process.exit(1);
-    }
-
-    // 2) Post the message into the group.
-    const sendRes = await vaultApiFetch({
-      token,
-      path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
-      method: "POST",
-      body: { body },
-    });
-    if (!sendRes.ok) {
-      const err = (await sendRes.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(
-            sendRes.status,
-            err.code,
-            err.error ?? err.message ?? sendRes.statusText,
-          ),
-        ),
-      );
-      process.exit(1);
-    }
-    console.log(
-      chalk.green(
-        `Group DM sent to ${participants.length} people${
-          createData.created ? " (new group)" : ""
-        }.`,
-      ),
-    );
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-/** Fetch the caller's channels (GET /v1/notify/channels). */
-async function fetchChannels(token: string): Promise<ChannelSummary[]> {
-  const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new Error(
-      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-    );
-  }
-  const data = (await res.json()) as { channels?: ChannelSummary[] };
-  return data.channels ?? [];
-}
-
-/**
- * Channel DM path: `hq dm vyg-dev "msg"`, `hq dm '#vyg-dev' "msg"`, or
- * `hq dm --channel vyg-dev "msg"`. Resolves the caller's channel by name via
- * GET /v1/notify/channels, then posts the message into it. Scheduling /
- * prompt / details are 1:1-DM features and are rejected here rather than
- * silently dropped.
- */
-async function runChannelSend(
-  channelName: string,
-  message: string | undefined,
-  opts: DmSendOpts,
-): Promise<void> {
-  try {
-    const body = (message ?? "").trim();
-    if (!body) {
-      console.error(
-        chalk.red(
-          `A message body is required: hq dm ${channelName} "<message>" (or hq dm --channel ${channelName} "<message>").`,
-        ),
-      );
-      process.exit(1);
-    }
-    const unsupported = [
-      opts.prompt || opts.promptFile ? "--prompt/--prompt-file" : null,
-      opts.details || opts.detailsFile ? "--details/--details-file" : null,
-      opts.at ? "--at" : null,
-      opts.in ? "--in" : null,
-    ].filter(Boolean);
-    if (unsupported.length > 0) {
-      console.error(
-        chalk.red(
-          `${unsupported.join(", ")} ${
-            unsupported.length === 1 ? "is" : "are"
-          } only supported for 1:1 DMs, not channel messages.`,
-        ),
-      );
-      process.exit(1);
-    }
-
-    const token = await ensureCognitoToken();
-    const channels = await fetchChannels(token);
-    const matches = matchChannelsByName(channels, channelName);
-
-    if (matches.length === 0) {
-      console.error(
-        chalk.red(`No channel named '${channelName}' — run \`hq channels\` to see your channels.`),
-      );
-      process.exit(1);
-    }
-    if (matches.length > 1) {
-      const scopes = matches.map((m) => m.scope ?? "?").join(", ");
-      console.error(
-        chalk.red(
-          `'${channelName}' matches ${matches.length} channels (${scopes}) — this is ambiguous. Open the channel in HQ Sync to post, or rename one.`,
-        ),
-      );
-      process.exit(1);
-    }
-
-    const channel = matches[0];
-    const sendRes = await vaultApiFetch({
-      token,
-      path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
-      method: "POST",
-      body: { body },
-    });
-    if (!sendRes.ok) {
-      const err = (await sendRes.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(sendRes.status, err.code, err.error ?? err.message ?? sendRes.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-    console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.`));
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-async function runDmSend(
-  recipient: string | undefined,
-  message: string | undefined,
-  opts: DmSendOpts,
-): Promise<void> {
-  // --channel <name> is an explicit channel target; the positional carries the
-  // message (recipient slot), e.g. `hq dm --channel vyg-dev "hello"`.
-  if (opts.channel !== undefined) {
-    await runChannelSend(opts.channel, message ?? recipient, opts);
-    return;
-  }
-  if (recipient === undefined) {
-    console.error(
-      chalk.red(
-        'A recipient is required: hq dm <email|personUid|#channel> "<message>" (or --channel <name>).',
-      ),
-    );
-    process.exit(1);
-    return;
-  }
-  // A comma in the recipient means a group DM — fan into the channel path.
-  const group = parseGroupRecipients(recipient);
-  if (group) {
-    await runGroupSend(group, message);
-    return;
-  }
-  // A bare name or #hash addresses a named DM channel.
-  const channelName = parseChannelName(recipient);
-  if (channelName !== null) {
-    await runChannelSend(channelName, message, opts);
-    return;
-  }
-  try {
-    // Resolve prompt/details from inline text or a file.
-    let prompt = opts.prompt;
-    if (opts.promptFile) prompt = readFileSync(opts.promptFile, "utf8");
-    let details = opts.details;
-    if (opts.detailsFile) details = readFileSync(opts.detailsFile, "utf8");
-
-    const reqBody = buildDmBody({
-      recipient,
-      message: message ?? "",
-      prompt,
-      details,
-      at: opts.at,
-      inDelay: opts.in,
-      now: Date.now(),
-    });
-
-    const token = await ensureCognitoToken();
-    const res = await vaultApiFetch({
-      token,
-      path: "/v1/notify/dm",
-      method: "POST",
-      body: reqBody as unknown as Record<string, unknown>,
-    });
-
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-
-    // 202 connection_requested: the recipient isn't connected yet, so the DM is
-    // held as a connection request rather than delivered. This is a success, not
-    // an error — surface it quietly.
-    const data = (await res.json()) as {
-      eventId?: string;
-      createdAt?: string;
-      scheduled?: boolean;
-      deliverAt?: string;
-      state?: string;
-    };
-
-    if (res.status === 202 || data.state === "connection_requested") {
-      console.log(
-        chalk.green(`Request sent — pending ${recipient}'s acceptance.`),
-      );
-      console.log(
-        chalk.dim("Your message is held and delivers automatically once they accept."),
-      );
-      return;
-    }
-
-    if (data.scheduled) {
-      console.log(
-        chalk.green(
-          `Scheduled DM to ${recipient} for ${data.deliverAt} (eventId ${data.eventId}).`,
-        ),
-      );
-      console.log(
-        chalk.dim("It delivers within ~60s of that time, even if you're offline."),
-      );
-    } else {
-      console.log(
-        chalk.green(`DM sent to ${recipient} (eventId ${data.eventId}).`),
-      );
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-async function runDmRequests(): Promise<void> {
-  try {
-    const token = await ensureCognitoToken();
-    const requests = await fetchRequests(token);
-    if (requests.length === 0) {
-      console.log(chalk.dim("No pending connection requests."));
-      return;
-    }
-    console.log(
-      chalk.green(
-        `${requests.length} pending connection request${requests.length === 1 ? "" : "s"}:`,
-      ),
-    );
-    for (const r of requests) {
-      const name = r.fromDisplayName ?? r.fromEmail ?? r.fromPersonUid;
-      const emailPart = r.fromEmail ? chalk.dim(` <${r.fromEmail}>`) : "";
-      console.log(`\n  ${chalk.bold(name)}${emailPart}`);
-      if (r.message) {
-        console.log(`    ${chalk.dim('"' + r.message + '"')}`);
-      }
-      const idHint = r.fromEmail ?? r.fromPersonUid ?? r.pairKey;
-      console.log(
-        chalk.dim(`    Accept: hq dm accept ${idHint}   ·   Decline: hq dm decline ${idHint}`),
-      );
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Receive side — reading DMs (inbox, 1:1 thread, channel/group history).
-// The backend read endpoints (GET /v1/notify/inbox, GET /v1/notify/thread,
-// GET /v1/notify/channels/{id}/messages) already back the HQ Sync menubar; the
-// commands below expose the same reads from the CLI.
-// ---------------------------------------------------------------------------
-
-/** One incoming DM as returned by GET /v1/notify/inbox. */
-export interface DmInboxEvent {
-  eventId: string;
-  fromPersonUid?: string;
-  fromEmail?: string;
-  fromDisplayName?: string;
-  body: string;
-  createdAt: string;
-  details?: string;
-  prompt?: string;
-  acknowledgedAt?: string;
-}
-
-/** One message in a 1:1 thread as returned by GET /v1/notify/thread. */
-export interface DmThreadMessage {
-  eventId: string;
-  fromPersonUid?: string;
-  fromEmail?: string;
-  fromDisplayName?: string;
-  body: string;
-  createdAt: string;
-  direction: "in" | "out";
-  details?: string;
-  prompt?: string;
-}
-
-/** One channel/group message from GET /v1/notify/channels/{id}/messages. */
-export interface ChannelMessageItem {
-  eventId?: string;
-  messageId?: string;
-  fromPersonUid?: string;
-  fromEmail?: string;
-  fromDisplayName?: string;
-  body: string;
-  createdAt: string;
-}
-
-/**
- * Human label for a message sender — display name, else email, else uid. Pure →
- * unit-testable.
- */
-export function senderLabel(m: {
-  fromDisplayName?: string;
-  fromEmail?: string;
-  fromPersonUid?: string;
-}): string {
-  return (
-    m.fromDisplayName?.trim() ||
-    m.fromEmail?.trim() ||
-    m.fromPersonUid?.trim() ||
-    "unknown"
-  );
-}
-
-/**
- * Render an ISO timestamp as a compact relative age ("3m ago", "2h ago",
- * "5d ago"), falling back to a YYYY-MM-DD date for anything older than a week or
- * an unparseable input. `nowMs` is injected so the formatting is unit-testable.
- * Pure.
- */
-export function formatRelativeTime(iso: string, nowMs: number): string {
-  const t = new Date(iso).getTime();
-  if (isNaN(t)) return iso;
-  const diff = nowMs - t;
-  if (diff < 60_000) return "just now";
-  const mins = Math.floor(diff / 60_000);
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}d ago`;
-  return new Date(t).toISOString().slice(0, 10);
-}
-
-/** A DM is unread until the recipient acks it. Pure. */
-export function isUnread(e: { acknowledgedAt?: string }): boolean {
-  return !e.acknowledgedAt;
-}
-
-/** Event ids of the unread messages in a fetched inbox page. Pure. */
-export function unreadEventIds(events: DmInboxEvent[]): string[] {
-  return events
-    .filter(isUnread)
-    .map((e) => e.eventId)
-    .filter((id): id is string => typeof id === "string" && id.length > 0);
-}
-
-/** Keep only the unread messages. Pure. */
-export function filterUnread(events: DmInboxEvent[]): DmInboxEvent[] {
-  return events.filter(isUnread);
-}
-
-/**
- * Collapse a message body to a single trimmed line for list rendering, capped
- * so one row stays readable. Pure.
- */
-export function firstLine(body: string, max = 240): string {
-  const oneLine = (body ?? "").replace(/\s+/g, " ").trim();
-  if (oneLine.length <= max) return oneLine;
-  return oneLine.slice(0, max - 1) + "…";
-}
-
-/**
- * Turn a person identifier into the query the thread endpoint expects. An email
- * rides `withEmail` (server resolves it); a prs_/agt_ uid rides `withPersonUid`.
- * A bare name is rejected — resolve it first with `hq people resolve`. Pure →
- * unit-testable. Throws with a user-facing message on an invalid identifier.
- */
-export function buildThreadQuery(identifier: string): Record<string, string> {
-  const rcpt = detectRecipient(identifier);
-  if (!rcpt) {
-    throw new Error(
-      `Invalid person '${identifier}': pass an email or a personUid/agentUid (prs_… / agt_…). Resolve a name first with \`hq people resolve\`.`,
-    );
-  }
-  if (rcpt.toEmail) return { withEmail: rcpt.toEmail };
-  return { withPersonUid: rcpt.toPersonUid! };
-}
-
-/** Render one inbox row (marker · age · sender · first line of body). */
-export function formatInboxEvent(e: DmInboxEvent, nowMs: number): string {
-  const marker = isUnread(e) ? chalk.cyan("●") : " ";
-  const when = chalk.dim(formatRelativeTime(e.createdAt, nowMs));
-  const who = chalk.bold(senderLabel(e));
-  const email =
-    e.fromEmail && e.fromDisplayName ? chalk.dim(` <${e.fromEmail}>`) : "";
-  return `${marker} ${when}  ${who}${email}\n    ${firstLine(e.body)}`;
-}
-
-/** Render one 1:1 thread line, tagged by direction. */
-export function formatThreadMessage(m: DmThreadMessage, nowMs: number): string {
-  const arrow = m.direction === "out" ? chalk.dim("→") : chalk.cyan("←");
-  const who = m.direction === "out" ? "you" : senderLabel(m);
-  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-  return `${arrow} ${chalk.bold(who)} ${when}\n    ${firstLine(m.body)}`;
-}
-
-/** Render one channel/group message line. */
-export function formatChannelMessage(
-  m: ChannelMessageItem,
-  nowMs: number,
-): string {
-  const who = chalk.bold(senderLabel(m));
-  const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-  return `${who} ${when}\n    ${firstLine(m.body)}`;
-}
-
-/** POST /v1/notify/inbox/ack — idempotently mark messages read. */
-async function ackEvents(token: string, eventIds: string[]): Promise<void> {
-  if (eventIds.length === 0) return;
-  const res = await vaultApiFetch({
-    token,
-    path: "/v1/notify/inbox/ack",
-    method: "POST",
-    body: { eventIds },
-  });
-  if (!res.ok) {
-    const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-    throw new Error(
-      friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-    );
-  }
-}
-
-interface DmInboxOpts {
-  limit?: string;
-  unread?: boolean;
-  markRead?: boolean;
-  json?: boolean;
-}
-
-async function runDmInbox(opts: DmInboxOpts): Promise<void> {
-  try {
-    const token = await ensureCognitoToken();
-    const query: Record<string, string> = {};
-    if (opts.limit) query.limit = opts.limit;
-    const res = await vaultApiFetch({ token, path: "/v1/notify/inbox", query });
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-    const data = (await res.json()) as {
-      events?: DmInboxEvent[];
-      nextCursor?: string;
-    };
-    const all = data.events ?? [];
-    const shown = opts.unread ? filterUnread(all) : all;
-
-    if (opts.json) {
-      console.log(JSON.stringify(shown, null, 2));
-    } else if (shown.length === 0) {
-      console.log(
-        chalk.dim(opts.unread ? "No unread messages." : "No messages yet."),
-      );
-    } else {
-      const unreadCount = filterUnread(all).length;
-      const suffix = unreadCount > 0 ? ` (${unreadCount} unread)` : "";
-      console.log(
-        chalk.green(
-          `${shown.length} message${shown.length === 1 ? "" : "s"}${suffix}:`,
-        ),
-      );
-      const now = Date.now();
-      for (const e of shown) console.log(`\n${formatInboxEvent(e, now)}`);
-      if (data.nextCursor) {
-        console.log(
-          chalk.dim("\nMore messages available — raise --limit to see them."),
-        );
-      }
-    }
-
-    // Ack every unread message on the fetched page (not just the filtered view).
-    if (opts.markRead) {
-      const ids = unreadEventIds(all);
-      await ackEvents(token, ids);
-      if (!opts.json && ids.length > 0) {
-        console.log(chalk.dim(`\nMarked ${ids.length} read.`));
-      }
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-interface DmThreadOpts {
-  limit?: string;
-  ack?: boolean;
-  json?: boolean;
-}
-
-async function runDmThread(
-  identifier: string,
-  opts: DmThreadOpts,
-): Promise<void> {
-  try {
-    const query = buildThreadQuery(identifier);
-    if (opts.limit) query.limit = opts.limit;
-    const token = await ensureCognitoToken();
-    const res = await vaultApiFetch({
-      token,
-      path: "/v1/notify/thread",
-      query,
-    });
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-    const data = (await res.json()) as { messages?: DmThreadMessage[] };
-    const messages = data.messages ?? [];
-    // The server returns newest-first; read a conversation oldest-first.
-    const ordered = [...messages].reverse();
-
-    if (opts.json) {
-      console.log(JSON.stringify(ordered, null, 2));
-    } else if (ordered.length === 0) {
-      console.log(chalk.dim(`No messages with ${identifier} yet.`));
-    } else {
-      console.log(
-        chalk.green(
-          `${ordered.length} message${ordered.length === 1 ? "" : "s"} with ${identifier}:`,
-        ),
-      );
-      const now = Date.now();
-      for (const m of ordered) console.log(`\n${formatThreadMessage(m, now)}`);
-    }
-
-    // Mark the incoming messages read unless the caller opted out. Best-effort:
-    // a read is a side effect, not the point of the command, so an ack failure
-    // is surfaced but does not fail the read.
-    if (opts.ack !== false) {
-      const inIds = messages
-        .filter((m) => m.direction === "in")
-        .map((m) => m.eventId)
-        .filter((id): id is string => typeof id === "string" && id.length > 0);
-      try {
-        await ackEvents(token, inIds);
-      } catch (ackErr) {
-        console.error(
-          chalk.dim(
-            `(could not mark read: ${
-              ackErr instanceof Error ? ackErr.message : String(ackErr)
-            })`,
-          ),
-        );
-      }
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-/**
- * Resolve a `hq dm channel <target>` argument to a channelId. Accepts a channel
- * name (bare or `#name`) resolved against the caller's channels, or a raw
- * channelId (the only way to address an unnamed group DM — copy it from
- * `hq channels`). Throws a user-facing message when nothing matches or a name is
- * ambiguous.
- */
-async function resolveChannelId(token: string, target: string): Promise<string> {
-  const raw = target.trim().replace(/^#/, "");
-  if (!raw) throw new Error("A channel name or id is required.");
-  const channels = await fetchChannels(token);
-  const named = matchChannelsByName(channels, raw);
-  if (named.length === 1) return named[0].channelId;
-  if (named.length > 1) {
-    throw new Error(
-      `'${raw}' matches ${named.length} channels — pass the channel id instead (see \`hq channels\`).`,
-    );
-  }
-  const byId = channels.find((c) => c.channelId === raw);
-  if (byId) return byId.channelId;
-  throw new Error(
-    `No channel named or with id '${raw}' — run \`hq channels\` to see yours.`,
-  );
-}
-
-interface DmChannelOpts {
-  limit?: string;
-  markRead?: boolean;
-  json?: boolean;
-}
-
-async function runDmChannel(
-  target: string,
-  opts: DmChannelOpts,
-): Promise<void> {
-  try {
-    const token = await ensureCognitoToken();
-    const channelId = await resolveChannelId(token, target);
-    const query: Record<string, string> = {};
-    if (opts.limit) query.limit = opts.limit;
-    const res = await vaultApiFetch({
-      token,
-      path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
-      query,
-    });
-    if (!res.ok) {
-      const err = (await res.json().catch(() => ({}))) as Record<string, string>;
-      console.error(
-        chalk.red(
-          friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText),
-        ),
-      );
-      process.exit(1);
-    }
-    const data = (await res.json()) as { messages?: ChannelMessageItem[] };
-    const messages = data.messages ?? [];
-    const ordered = [...messages].reverse(); // oldest-first for reading
-
-    if (opts.json) {
-      console.log(JSON.stringify(ordered, null, 2));
-    } else if (ordered.length === 0) {
-      console.log(chalk.dim("No messages in this channel yet."));
-    } else {
-      console.log(
-        chalk.green(
-          `${ordered.length} message${ordered.length === 1 ? "" : "s"}:`,
-        ),
-      );
-      const now = Date.now();
-      for (const m of ordered) console.log(`\n${formatChannelMessage(m, now)}`);
-    }
-
-    if (opts.markRead) {
-      // messages are newest-first from the server; advance the read cursor to
-      // the newest one we saw.
-      const newest = messages[0]?.createdAt;
-      const readRes = await vaultApiFetch({
-        token,
-        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/read`,
-        method: "POST",
-        body: newest ? { lastReadAt: newest } : {},
-      });
-      if (!opts.json && readRes.ok) {
-        console.log(chalk.dim("\nMarked read."));
-      }
-    }
-  } catch (err) {
-    console.error(
-      chalk.red("Error:"),
-      err instanceof Error ? err.message : String(err),
-    );
-    process.exit(1);
-  }
-}
-
-export function registerDmCommand(program: Command): void {
-  const dm = program
-    .command("dm")
-    .description(
-      "Send and read direct messages, and manage connection requests.",
-    );
-
-  dm
-    .command("send [recipient] [message]", { isDefault: true, hidden: true })
-    .description(
-      'Send a direct message. RECIPIENT can be a person (email, personUid, or agentUid), a GROUP DM (comma-separated: "a@x.com,b@y.com"), or one of your DM CHANNELS by name — bare (hq dm vyg-dev "hi"), hash form (hq dm "#vyg-dev" "hi"), or via --channel (hq dm --channel vyg-dev "hi"). A person receives a DM as an HQ Sync notification; an agent receives it in its durable box inbox. If you aren\'t connected yet, it sends a connection request that holds your message. See your channels with `hq channels`.',
-    )
-    .option(
-      "--channel <name>",
-      "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)",
-    )
-    .option(
-      "--prompt <text>",
-      "Agent-context prompt the recipient can one-click copy into their agent (1:1 DMs only)",
-    )
-    .option("--prompt-file <path>", "Read the agent prompt from a file (1:1 DMs only)")
-    .option(
-      "--details <text>",
-      "Longer detail shown in the recipient's DM detail window (1:1 DMs only)",
-    )
-    .option("--details-file <path>", "Read the details from a file (1:1 DMs only)")
-    .option(
-      "--at <iso>",
-      "Schedule delivery at an ISO8601 time (store-and-forward; delivered within ~60s of the time; 1:1 DMs only)",
-    )
-    .option(
-      "--in <duration>",
-      "Schedule delivery after a relative delay: 30s, 10m, 2h, 1d (1:1 DMs only)",
-    )
-    .action(
-      async (
-        recipient: string | undefined,
-        message: string | undefined,
-        opts: DmSendOpts,
-      ) => {
-        await runDmSend(recipient, message, opts);
-      },
-    );
-
-  dm
-    .command("inbox")
-    .description("List your recent incoming direct messages.")
-    .option("--limit <n>", "Max messages to fetch (server-capped)")
-    .option("--unread", "Show only unread messages")
-    .option("--mark-read", "Mark the fetched messages as read after listing")
-    .option("--json", "Output raw JSON instead of a list")
-    .action(async (opts: DmInboxOpts) => {
-      await runDmInbox(opts);
-    });
-
-  dm
-    .command("thread <person>")
-    .alias("read")
-    .description(
-      "Show your two-way conversation with a person (email, personUid, or agentUid). Reads oldest-first and marks their messages read unless --no-ack.",
-    )
-    .option("--limit <n>", "Max messages to fetch (server-capped)")
-    .option("--no-ack", "Do not mark the incoming messages as read")
-    .option("--json", "Output raw JSON instead of a transcript")
-    .action(async (person: string, opts: DmThreadOpts) => {
-      await runDmThread(person, opts);
-    });
-
-  dm
-    .command("channel <target>")
-    .alias("history")
-    .description(
-      "Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`.",
-    )
-    .option("--limit <n>", "Max messages to fetch (server-capped)")
-    .option("--mark-read", "Advance your read marker to the newest message")
-    .option("--json", "Output raw JSON instead of a transcript")
-    .action(async (target: string, opts: DmChannelOpts) => {
-      await runDmChannel(target, opts);
-    });
-
-  dm
-    .command("requests")
-    .description("List your pending incoming connection requests.")
-    .action(async () => {
-      await runDmRequests();
-    });
-
-  dm
-    .command("accept <person>")
-    .description(
-      "Accept a pending connection request (by email, personUid, or pairKey). Their held message is then delivered.",
-    )
-    .action(async (person: string) => {
-      await runConnectionAction("accept", person);
-    });
-
-  dm
-    .command("decline <person>")
-    .description("Decline a pending connection request (by email, personUid, or pairKey).")
-    .action(async (person: string) => {
-      await runConnectionAction("decline", person);
-    });
-
-  dm
-    .command("block <person>")
-    .description("Block a person so they can't send you further requests (by email, personUid, or pairKey).")
-    .action(async (person: string) => {
-      await runConnectionAction("block", person);
-    });
-}