@indigoai-us/hq-cli 5.314.0 → 5.315.0

package/dist/commands/dm.js

@@ -2,11 +2,9 @@ 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_-]+$/;
+import { isMachineIdentity } from "@indigoai-us/hq-cloud";
+import { peekIdToken } from "../utils/id-token.js";
+import { EMAIL_PATTERN, RECIPIENT_UID_PATTERN } from "../lib/notify-recipient.js";
 /**
  * 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.
@@ -86,6 +84,13 @@ export function parseChannelName(recipient) {
  * unit-testable.
  */
 export function matchChannelsByName(channels, name) {
+    // A channel id is exact and names nothing else, so it may target any scope,
+    // including an unnamed group DM. Bots reply this way: their inbox carries
+    // the id of the conversation a message arrived in, not its name.
+    const trimmed = name.trim().replace(/^#/, "");
+    if (/^chn_[A-Za-z0-9]+$/.test(trimmed)) {
+        return channels.filter((c) => c.channelId === trimmed);
+    }
     const targetSlug = channelSlug(name);
     const targetName = name.trim().toLowerCase();
     if (!targetSlug && !targetName)
@@ -136,6 +141,15 @@ export function mentionParticipantType(uid) {
  * Trailing punctuation is trimmed ("@Izzy," → "Izzy"), so a name is never
  * polluted by the sentence around it.
  */
+/**
+ * Once a quoted token has resolved to a real mention, the quotes have done
+ * their job (they only exist so a multi-word name parses as one token). Post
+ * the body with `@"Jacob Posel"` rewritten to `@Jacob Posel`, which is how a
+ * person would have typed it and how the room should read it. Pure.
+ */
+export function stripMentionQuotes(body) {
+    return body.replace(/(^|[\s([{<])@"([^"\n]{1,80})"/g, "$1@$2");
+}
 export function parseMentionTokens(body) {
     const pattern = /(^|[\s([{<])@(?:"([^"\n]{1,80})"|([A-Za-z0-9][A-Za-z0-9._-]*))/g;
     const names = [];
@@ -269,6 +283,7 @@ export function parseDuration(input) {
     };
     return n * mult[m[2]];
 }
+const DM_AUDIENCE_VALUES = ["human", "agent", "both"];
 /**
  * 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
@@ -305,12 +320,20 @@ export function buildDmBody(args) {
     }
     const prompt = args.prompt?.trim();
     const details = args.details?.trim();
+    let audience;
+    if (args.audience !== undefined && args.audience !== "") {
+        if (!DM_AUDIENCE_VALUES.includes(args.audience)) {
+            throw new Error(`Invalid --audience '${args.audience}': must be human, agent, or both.`);
+        }
+        audience = args.audience;
+    }
     return {
         ...rcpt,
         body,
         ...(prompt ? { prompt } : {}),
         ...(details ? { details } : {}),
         ...(deliverAt ? { deliverAt } : {}),
+        ...(audience ? { audience } : {}),
     };
 }
 function friendlyDmError(status, code, fallback) {
@@ -344,25 +367,22 @@ export function matchRequest(requests, identifier) {
     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.
+ * Build the POST body for an accept/decline/block action. The connections
+ * endpoints accept the requester's `personUid`, so resolve friendly email or
+ * pairKey input through the pending request before building the body. Pure →
+ * unit-testable.
  *
  * Throws Error with a user-facing message when the identifier can't be resolved.
  */
 export function buildConnectionActionBody(identifier, matched) {
     if (matched) {
-        return { pairKey: matched.pairKey };
+        return { personUid: matched.fromPersonUid };
     }
     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\`.`);
+        return { personUid: rcpt.toPersonUid };
+    throw new Error(`Could not resolve '${identifier}' to a pending request — pass the requester's email or personUid, or a pairKey from \`hq dm requests\`.`);
 }
 const CONNECTION_ACTIONS = {
     accept: { path: "accept", done: "Connection accepted" },
@@ -387,7 +407,12 @@ async function runConnectionAction(action, identifier) {
         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(() => []);
+        const requests = await fetchRequests(token).catch((err) => {
+            console.error("hq dm: pending connection request lookup failed", {
+                errorName: err instanceof Error ? err.name : typeof err,
+            });
+            return [];
+        });
         const matched = matchRequest(requests, identifier);
         const body = buildConnectionActionBody(identifier, matched);
         const res = await vaultApiFetch({
@@ -478,7 +503,7 @@ async function runGroupSend(recipients, message) {
     }
 }
 /** Fetch the caller's channels (GET /v1/notify/channels). */
-async function fetchChannels(token) {
+export async function fetchChannels(token) {
     const res = await vaultApiFetch({ token, path: "/v1/notify/channels" });
     if (!res.ok) {
         const err = (await res.json().catch(() => ({})));
@@ -492,7 +517,7 @@ async function fetchChannels(token) {
  * who can read the channel may read its members, so this is the same gate the
  * post itself passes. Used to resolve `@name` mentions into participant uids.
  */
-async function fetchChannelMembers(token, channelId) {
+export async function fetchChannelMembers(token, channelId) {
     const res = await vaultApiFetch({
         token,
         path: `/v1/notify/channels/${encodeURIComponent(channelId)}/members`,
@@ -504,6 +529,20 @@ async function fetchChannelMembers(token, channelId) {
     const data = (await res.json());
     return data.members ?? [];
 }
+/** Fetch a channel history page (GET /v1/notify/channels/{id}/messages). Newest-first. */
+async function fetchChannelMessages(token, channelId, query = {}) {
+    const res = await vaultApiFetch({
+        token,
+        path: `/v1/notify/channels/${encodeURIComponent(channelId)}/messages`,
+        query,
+    });
+    if (!res.ok) {
+        const err = (await res.json().catch(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+    const data = (await res.json());
+    return data.messages ?? [];
+}
 /**
  * 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
@@ -513,7 +552,7 @@ async function fetchChannelMembers(token, channelId) {
  */
 async function runChannelSend(channelName, message, opts) {
     try {
-        const body = (message ?? "").trim();
+        let 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);
@@ -541,6 +580,20 @@ async function runChannelSend(channelName, message, opts) {
             process.exit(1);
         }
         const channel = matches[0];
+        let rootEventId;
+        if (opts.thread !== undefined) {
+            let recent = [];
+            if (opts.thread.trim().toLowerCase() === "last") {
+                recent = await fetchChannelMessages(token, channel.channelId);
+            }
+            const resolved = resolveThreadFlag(opts.thread, recent, callerFromToken(token));
+            if (!resolved.ok) {
+                console.error(chalk.red(resolved.error));
+                process.exit(1);
+                return;
+            }
+            rootEventId = resolved.rootEventId;
+        }
         // Mentions are structured-only server-side: resolve `@name` against the
         // roster and send the array, or fail before posting. --no-mentions opts out
         // and posts the text literally.
@@ -558,11 +611,19 @@ async function runChannelSend(channelName, message, opts) {
                 mentions = resolved.mentions;
             }
         }
+        // Send the human-readable form: the quotes only existed for parsing.
+        if (mentions.length > 0)
+            body = stripMentionQuotes(body);
+        const payload = { body };
+        if (mentions.length > 0)
+            payload.mentions = mentions;
+        if (rootEventId)
+            payload.rootEventId = rootEventId;
         const sendRes = await vaultApiFetch({
             token,
             path: `/v1/notify/channels/${encodeURIComponent(channel.channelId)}/messages`,
             method: "POST",
-            body: mentions.length > 0 ? { body, mentions } : { body },
+            body: payload,
         });
         if (!sendRes.ok) {
             const err = (await sendRes.json().catch(() => ({})));
@@ -572,7 +633,8 @@ async function runChannelSend(channelName, message, opts) {
         const mentionSuffix = mentions.length > 0
             ? ` Mentioned ${mentions.map((m) => m.displayName).join(", ")}.`
             : "";
-        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.${mentionSuffix}`));
+        const threadSuffix = rootEventId ? ` Reply in thread ${rootEventId}.` : "";
+        console.log(chalk.green(`Message posted to #${channel.name ?? channelName}.${mentionSuffix}${threadSuffix}`));
     }
     catch (err) {
         console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
@@ -594,6 +656,11 @@ async function runDmSend(recipient, message, opts) {
     // A comma in the recipient means a group DM — fan into the channel path.
     const group = parseGroupRecipients(recipient);
     if (group) {
+        if (opts.thread !== undefined) {
+            console.error(chalk.red("--thread is only supported for named channel messages (hq dm <channel> --thread <eventId|last> \"…\")."));
+            process.exit(1);
+            return;
+        }
         await runGroupSend(group, message);
         return;
     }
@@ -603,6 +670,11 @@ async function runDmSend(recipient, message, opts) {
         await runChannelSend(channelName, message, opts);
         return;
     }
+    if (opts.thread !== undefined) {
+        console.error(chalk.red("--thread is only supported for channel messages (hq dm <channel> --thread <eventId|last> \"…\")."));
+        process.exit(1);
+        return;
+    }
     try {
         // Resolve prompt/details from inline text or a file.
         let prompt = opts.prompt;
@@ -619,6 +691,7 @@ async function runDmSend(recipient, message, opts) {
             at: opts.at,
             inDelay: opts.in,
             now: Date.now(),
+            audience: opts.audience,
         });
         const token = await ensureCognitoToken();
         const res = await vaultApiFetch({
@@ -679,6 +752,27 @@ async function runDmRequests() {
         process.exit(1);
     }
 }
+/**
+ * Render the attachment lines for one message. An agent reading its DMs through
+ * the CLI only ever sees this text, so the vault path AND the command that
+ * fetches it both have to be on screen — a bare "[image]" marker is why a bot
+ * answers "no image came through". Returns "" when there is nothing attached.
+ * Pure → unit-testable.
+ */
+export function formatAttachments(m, indent = "    ") {
+    const files = (m.attachments?.length ? m.attachments : m.attachment ? [m.attachment] : [])
+        .filter((f) => Boolean(f?.vaultPath));
+    if (files.length === 0)
+        return "";
+    return files
+        .map((f) => {
+        const label = f.name?.trim() || f.vaultPath.split("/").pop() || "file";
+        const type = f.contentType ? ` ${chalk.dim(f.contentType)}` : "";
+        const company = f.companyUid ? chalk.dim(` company=${f.companyUid}`) : "";
+        return `\n${indent}${chalk.dim("[file]")} ${label}${type}\n${indent}   ${chalk.dim(`vault: ${f.vaultPath}`)}${company}`;
+    })
+        .join("");
+}
 /**
  * Human label for a message sender — display name, else email, else uid. Pure →
  * unit-testable.
@@ -759,20 +853,179 @@ export function formatInboxEvent(e, nowMs) {
     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)}`;
+    const audienceTag = e.audience === "agent" ? chalk.dim(" [agent]") : "";
+    return `${marker} ${when}  ${who}${email}${audienceTag}\n    ${firstLine(e.body)}${formatAttachments(e)}`;
 }
 /** Render one 1:1 thread line, tagged by direction. */
 export function formatThreadMessage(m, nowMs) {
     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)}`;
+    const audienceTag = m.audience === "agent" ? chalk.dim(" [agent]") : "";
+    return `${arrow} ${chalk.bold(who)} ${when}${audienceTag}\n    ${firstLine(m.body)}${formatAttachments(m)}`;
 }
 /** Render one channel/group message line. */
-export function formatChannelMessage(m, nowMs) {
+export function formatChannelMessage(m, nowMs, opts = {}) {
+    const indent = opts.indent ?? "";
     const who = chalk.bold(senderLabel(m));
     const when = chalk.dim(formatRelativeTime(m.createdAt, nowMs));
-    return `${who} ${when}\n    ${firstLine(m.body)}`;
+    const id = opts.showEventId ? (m.eventId ?? m.messageId) : undefined;
+    const idPart = id ? `  ${chalk.dim(id)}` : "";
+    const bodyIndent = `${indent}    `;
+    const body = firstLine(m.body);
+    const readableBody = body ||
+        (senderLabel(m).toLowerCase() === "hq"
+            ? "System notification (no text provided)."
+            : "(no message text)");
+    return `${indent}${who} ${when}${idPart}\n${bodyIndent}${readableBody}${formatAttachments(m, bodyIndent)}`;
+}
+/**
+ * Read the caller's person/agent uid and email from a JWT we already hold.
+ * Used to resolve `--thread last` (most recent top-level message *by us*).
+ * Pure → unit-testable.
+ */
+export function callerFromToken(token) {
+    const claims = peekIdToken(token);
+    const uid = claims["custom:entityUid"];
+    const email = claims.email;
+    const personUid = typeof uid === "string" && uid.trim() ? uid.trim() : undefined;
+    const emailNorm = typeof email === "string" && email.trim()
+        ? email.trim().toLowerCase()
+        : undefined;
+    return {
+        ...(personUid ? { personUid } : {}),
+        ...(emailNorm ? { email: emailNorm } : {}),
+    };
+}
+function isCallerMessage(m, me) {
+    if (me.personUid && m.fromPersonUid === me.personUid)
+        return true;
+    if (me.email && (m.fromEmail ?? "").trim().toLowerCase() === me.email) {
+        return true;
+    }
+    return false;
+}
+function messageEventId(m) {
+    const id = (m.eventId ?? m.messageId ?? "").trim();
+    return id || undefined;
+}
+/**
+ * Newest-first channel history → the caller's most recent top-level eventId.
+ * Replies (those with rootEventId) are skipped. Pure → unit-testable.
+ */
+export function lastCallerRootEventId(messagesNewestFirst, me) {
+    for (const m of messagesNewestFirst) {
+        if ((m.rootEventId ?? "").trim())
+            continue;
+        if (!isCallerMessage(m, me))
+            continue;
+        const id = messageEventId(m);
+        if (id)
+            return id;
+    }
+    return undefined;
+}
+/**
+ * Resolve `--thread <eventId|last>` against a newest-first message page.
+ * An explicit eventId is passed through; `last` picks our most recent
+ * top-level message. Pure → unit-testable (the fetch is the caller's job).
+ */
+export function resolveThreadFlag(thread, messagesNewestFirst, me) {
+    if (thread === undefined)
+        return { ok: true };
+    const value = thread.trim();
+    if (!value) {
+        return { ok: false, error: "--thread requires an eventId or 'last'." };
+    }
+    if (value.toLowerCase() !== "last") {
+        return { ok: true, rootEventId: value };
+    }
+    if (!me.personUid && !me.email) {
+        return {
+            ok: false,
+            error: "Cannot resolve --thread last: the session token has no person uid or email. Pass --thread <eventId> from `hq dm channel`.",
+        };
+    }
+    const id = lastCallerRootEventId(messagesNewestFirst, me);
+    if (!id) {
+        return {
+            ok: false,
+            error: "No top-level message from you in this channel's recent history. Pass --thread <eventId> (copy it from `hq dm channel <name>`).",
+        };
+    }
+    return { ok: true, rootEventId: id };
+}
+function sortByCreatedAt(a, b) {
+    return (a.createdAt ?? "").localeCompare(b.createdAt ?? "");
+}
+/**
+ * Group a channel history page into roots with their replies underneath.
+ * Orphan replies (root not in this page) hang off a placeholder carrying the
+ * missing root's eventId. Pure → unit-testable.
+ */
+export function groupChannelMessages(messages) {
+    const roots = [];
+    const repliesByRoot = new Map();
+    for (const m of messages) {
+        const rootId = (m.rootEventId ?? "").trim();
+        if (!rootId) {
+            roots.push(m);
+            continue;
+        }
+        const bucket = repliesByRoot.get(rootId) ?? [];
+        bucket.push(m);
+        repliesByRoot.set(rootId, bucket);
+    }
+    const used = new Set();
+    const threads = [];
+    roots.sort(sortByCreatedAt);
+    for (const root of roots) {
+        const id = messageEventId(root) ?? "";
+        if (id)
+            used.add(id);
+        threads.push({
+            root,
+            replies: (repliesByRoot.get(id) ?? []).slice().sort(sortByCreatedAt),
+        });
+    }
+    for (const [rootId, replies] of repliesByRoot) {
+        if (used.has(rootId))
+            continue;
+        const sorted = replies.slice().sort(sortByCreatedAt);
+        threads.push({
+            root: {
+                eventId: rootId,
+                body: "",
+                createdAt: sorted[0]?.createdAt ?? "",
+            },
+            replies: sorted,
+            missingRoot: true,
+        });
+    }
+    return threads;
+}
+/**
+ * Human channel history: each root prints its eventId so `--thread` can copy
+ * it; replies render indented under their root. `--json` does not use this.
+ * Pure → unit-testable.
+ */
+export function formatChannelTranscript(messages, nowMs) {
+    const threads = groupChannelMessages(messages);
+    const blocks = [];
+    for (const t of threads) {
+        const parts = [];
+        if (t.missingRoot) {
+            parts.push(chalk.dim(`… ${t.root.eventId ?? ""} (root not in this page)`));
+        }
+        else {
+            parts.push(formatChannelMessage(t.root, nowMs, { showEventId: true }));
+        }
+        for (const reply of t.replies) {
+            parts.push(formatChannelMessage(reply, nowMs, { indent: "  " }));
+        }
+        blocks.push(parts.join("\n"));
+    }
+    return blocks.join("\n\n");
 }
 /** POST /v1/notify/inbox/ack — idempotently mark messages read. */
 async function ackEvents(token, eventIds) {
@@ -789,9 +1042,89 @@ async function ackEvents(token, eventIds) {
         throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
     }
 }
+/**
+ * The agent uid when the caller is an agent (machine) identity, else null.
+ * Agents may not read /v1/notify/inbox or /v1/notify/thread (the server
+ * allow-list is intentionally human-only); their read surface is
+ * GET /v1/agents/{uid}/inbox.
+ */
+export function agentCallerUid(token, machine = isMachineIdentity) {
+    const claims = peekIdToken(token);
+    const uid = claims["custom:entityUid"];
+    if (typeof uid !== "string" || !uid.startsWith("agt_"))
+        return null;
+    if (claims["custom:entityType"] === "agent")
+        return uid;
+    try {
+        return machine() ? uid : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const AGENT_THREAD_UNAVAILABLE = "`hq dm thread` reads /v1/notify/thread, which is not available to agent identities. " +
+    "Use `hq dm inbox` — for agents it reads GET /v1/agents/{uid}/inbox.";
+/** One-line summary of an agent inbox item (DM, email, … — shapes vary by channel). Pure. */
+function formatAgentInboxItem(item) {
+    const str = (k) => (typeof item[k] === "string" ? item[k] : "");
+    const id = str("messageId") || str("id") || "?";
+    const channel = str("channel") || "inbox";
+    const from = str("fromDisplayName") || str("fromEmail") || str("from") || str("fromPersonUid") || "unknown";
+    const when = str("createdAt") || str("receivedAt");
+    const text = str("text") || str("body") || str("subject");
+    return `${chalk.bold(from)} ${chalk.dim(`[${channel}] ${id}${when ? ` ${when}` : ""}`)}\n  ${firstLine(text)}`;
+}
+/** Remove delegated execution context before agent inbox items can be emitted. */
+function redactAgentInboxItem(item) {
+    const { actingContext: _actingContext, ...safe } = item;
+    return safe;
+}
+async function runAgentInbox(token, agentUid, opts) {
+    const route = `/v1/agents/${encodeURIComponent(agentUid)}/inbox`;
+    const res = await vaultApiFetch({ token, path: route });
+    if (!res.ok) {
+        // Error bodies are not constrained to the success response shape. Do not
+        // echo them: a proxy or partial failure could include inbox items.
+        console.error(chalk.red(`GET ${route} → ${res.status}`));
+        process.exit(1);
+    }
+    const data = (await res.json().catch(() => ({})));
+    let items = (Array.isArray(data.messages) ? data.messages : []).map(redactAgentInboxItem);
+    if (opts.limit && Number(opts.limit) > 0)
+        items = items.slice(0, Number(opts.limit));
+    if (opts.json) {
+        console.log(JSON.stringify(items, null, 2));
+    }
+    else if (items.length === 0) {
+        console.log(chalk.dim("No pending inbox items."));
+    }
+    else {
+        console.log(chalk.green(`${items.length} pending inbox item${items.length === 1 ? "" : "s"}:`));
+        for (const item of items)
+            console.log(`\n${formatAgentInboxItem(item)}`);
+    }
+    if (opts.markRead) {
+        let acked = 0;
+        for (const item of items) {
+            const id = typeof item.messageId === "string" ? item.messageId : typeof item.id === "string" ? item.id : null;
+            if (!id)
+                continue;
+            const ack = await vaultApiFetch({ token, path: `${route}/${encodeURIComponent(id)}/ack`, method: "POST" });
+            if (ack.ok)
+                acked += 1;
+        }
+        if (!opts.json && acked > 0)
+            console.log(chalk.dim(`\nAcked ${acked}.`));
+    }
+}
 async function runDmInbox(opts) {
     try {
         const token = await ensureCognitoToken();
+        const agentUid = agentCallerUid(token);
+        if (agentUid) {
+            await runAgentInbox(token, agentUid, opts);
+            return;
+        }
         const query = {};
         if (opts.limit)
             query.limit = opts.limit;
@@ -841,6 +1174,10 @@ async function runDmThread(identifier, opts) {
         if (opts.limit)
             query.limit = opts.limit;
         const token = await ensureCognitoToken();
+        if (agentCallerUid(token)) {
+            console.error(chalk.yellow(AGENT_THREAD_UNAVAILABLE));
+            process.exit(1);
+        }
         const res = await vaultApiFetch({
             token,
             path: "/v1/notify/thread",
@@ -895,26 +1232,27 @@ async function runDmThread(identifier, opts) {
  * `hq channels`). Throws a user-facing message when nothing matches or a name is
  * ambiguous.
  */
-async function resolveChannelId(token, target) {
+async function resolveChannel(token, target) {
     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;
+        return named[0];
     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;
+        return byId;
     throw new Error(`No channel named or with id '${raw}' — run \`hq channels\` to see yours.`);
 }
 async function runDmChannel(target, opts) {
     try {
         const token = await ensureCognitoToken();
-        const channelId = await resolveChannelId(token, target);
+        const channel = await resolveChannel(token, target);
+        const channelId = channel.channelId;
         const query = {};
         if (opts.limit)
             query.limit = opts.limit;
@@ -930,18 +1268,28 @@ async function runDmChannel(target, opts) {
         }
         const data = (await res.json());
         const messages = data.messages ?? [];
-        const ordered = [...messages].reverse(); // oldest-first for reading
+        const agentCaller = agentCallerUid(token) !== null;
+        const ordered = [...messages].reverse().map((message) => agentCaller ? redactAgentInboxItem(message) : message); // oldest-first for reading; agent JSON must not expose delegated context
         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."));
+            const channelType = channel.scope === "personal"
+                ? "personal"
+                : channel.scope === "group"
+                    ? "group"
+                    : "shared";
+            const channelName = channel.name?.trim() || channel.slug?.trim() || channelId;
+            const requestedTarget = target.trim().replace(/^#/, "");
+            const sendTarget = requestedTarget === channelId
+                ? channelId
+                : channel.slug?.trim() || requestedTarget;
+            console.log(chalk.dim(`No messages in ${channelType} channel "${channelName}" yet.\nSend a message with: hq dm ${sendTarget} "Hello"`));
         }
         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)}`);
+            console.log(`\n${formatChannelTranscript(ordered, now)}`);
         }
         if (opts.markRead) {
             // messages are newest-first from the server; advance the read cursor to
@@ -969,15 +1317,17 @@ export function registerDmCommand(program) {
         .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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.')
+        .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`.\n\nCHANNEL MENTIONS: HQ mentions are structured — the server never reads `@name` out of your text, so a channel message has to carry the participants alongside the body. When you write `@name` in a channel message, this command looks the name up in the channel roster (case-insensitive on display name and slug/handle; quote multi-word names as @"Jacob Posel") and sends it as a real mention, which notifies people and wakes agents. If a name is unknown or matches more than one member, the send FAILS with the candidates instead of posting something that mentions nobody. A bare "@" or an email address in your prose is never treated as a mention. Pass --no-mentions to post the text literally.\n\nCHANNEL THREADS: `hq dm <channel> --thread <eventId> "…"` replies under an existing root (the request carries rootEventId). `--thread last` replies to your most recent top-level message in that channel. Copy a root eventId from `hq dm channel <name>`, which prints each root\'s id and indents replies underneath.')
         .option("--channel <name>", "Post the message to one of your DM channels by name (e.g. --channel vyg-dev)")
         .option("--no-mentions", "Do not resolve `@name` in a channel message into structured mentions — post the text literally")
+        .option("--thread <eventId>", 'Reply in a channel thread. Pass a root eventId from `hq dm channel`, or `last` for your most recent top-level message in that channel')
         .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)")
+        .option("--audience <human|agent|both>", "Tag who this message is for: human (a person must read it), agent (progress/status, hidden from humans by default), or both (1:1 DMs only)")
         .action(async (recipient, message, opts) => {
         await runDmSend(recipient, message, opts);
     });
@@ -1004,7 +1354,7 @@ export function registerDmCommand(program) {
     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`.")
+        .description("Show recent messages in a DM channel or group DM — by name, #name, or a channel id from `hq channels`. Roots print their eventId; replies indent under their root. --json is the raw oldest-first array (ungrouped).")
         .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")
@@ -1019,19 +1369,19 @@ export function registerDmCommand(program) {
     });
     dm
         .command("accept <person>")
-        .description("Accept a pending connection request (by email, personUid, or pairKey). Their held message is then delivered.")
+        .description("Accept a pending connection request (by requester email, personUid, or pairKey from `hq dm requests`). Their held message is then delivered.")
         .action(async (person) => {
         await runConnectionAction("accept", person);
     });
     dm
         .command("decline <person>")
-        .description("Decline a pending connection request (by email, personUid, or pairKey).")
+        .description("Decline a pending connection request (by requester email, personUid, or pairKey from `hq dm requests`).")
         .action(async (person) => {
         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).")
+        .description("Block a person so they can't send you further requests (by requester email, personUid, or pairKey from `hq dm requests`).")
         .action(async (person) => {
         await runConnectionAction("block", person);
     });