@indigoai-us/hq-cli 5.69.0 → 5.71.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## [Unreleased]
 
+## [5.71.0]
+
+### Added
+
+- **Async Outpost exec.** `hq outposts` gained three verbs for running commands
+  that exceed the synchronous `exec` limits (long-running turns, large payloads
+  and outputs), backed by the `mode` flag on `POST /outpost/exec`:
+  - `hq outposts exec-stage --file <path>` — upload an input payload to a
+    short-lived presigned URL and print `{ key, getUrl }`.
+  - `hq outposts exec-submit -- <command>` — submit an asynchronous command and
+    print `{ commandId }` immediately (no blocking).
+  - `hq outposts exec-result --command-id <id> [--wait]` — fetch the result;
+    non-terminal returns `{ done: false }`, `--wait` polls to completion.
+
+### Fixed
+
+- `outposts exec` / `exec-submit` now shell-quote multi-argument commands before
+  joining, so `-- bash -c "$script" a b` survives instead of collapsing on a
+  naive space-join. A single command string still passes through verbatim.
+
+## [5.70.0]
+
+### Added
+
+- **Read DMs from the CLI.** `hq dm` gained a receive side, wired to the notify
+  read endpoints that already back the HQ Sync menubar:
+  - `hq dm inbox` — list your incoming direct messages, with `--unread`,
+    `--limit`, `--json`, and `--mark-read`.
+  - `hq dm thread <person>` (alias `read`) — the two-way 1:1 conversation with a
+    person by email, personUid, or agentUid, read oldest-first. Marks their
+    messages read unless `--no-ack`. Reading by email uses the notify thread
+    endpoint's new `withEmail` resolution (requires the matching hq-pro deploy).
+  - `hq dm channel <name|#name|id>` (alias `history`) — channel and group-DM
+    message history, with `--mark-read` to advance your read cursor.
+- **`hq channels` now shows each group DM's channel id**, so unnamed group DMs
+  are addressable for reading with `hq dm channel <id>`.
+
 ## [5.69.0]
 
 ### Added

package/dist/commands/channels.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="891a3265-c9ff-53d8-8a3c-2a964f5a74b6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fe48059a-56b5-5f50-8ebf-b5fbbe1aa432")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -18,7 +18,10 @@ export function describeChannel(c) {
         const who = names.length > 0
             ? names.join(", ")
             : `${c.memberCount ?? "?"}-person group`;
-        return `${who}  ${chalk.dim("(group DM)")}`;
+        // Group DMs are unnamed, so their channel id is the only way to address them
+        // for reading (`hq dm channel <id>`). Surface it so it can be copied.
+        const readHint = chalk.dim(`— hq dm channel ${c.channelId}`);
+        return `${who}  ${chalk.dim("(group DM)")}  ${readHint}`;
     }
     const slug = c.slug ?? (c.name ? channelSlug(c.name) : "");
     const scopeTag = c.scope ? chalk.dim(`(${c.scope})`) : "";
@@ -75,4 +78,4 @@ export function registerChannelsCommand(program) {
     });
 }
 //# sourceMappingURL=channels.js.map
-//# debugId=891a3265-c9ff-53d8-8a3c-2a964f5a74b6
+//# debugId=fe48059a-56b5-5f50-8ebf-b5fbbe1aa432

package/dist/commands/dm.d.ts

@@ -119,5 +119,81 @@ export declare function buildConnectionActionBody(identifier: string, matched: C
 } | {
     withEmail: string;
 };
+/** 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 declare function senderLabel(m: {
+    fromDisplayName?: string;
+    fromEmail?: string;
+    fromPersonUid?: string;
+}): string;
+/**
+ * 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 declare function formatRelativeTime(iso: string, nowMs: number): string;
+/** A DM is unread until the recipient acks it. Pure. */
+export declare function isUnread(e: {
+    acknowledgedAt?: string;
+}): boolean;
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export declare function unreadEventIds(events: DmInboxEvent[]): string[];
+/** Keep only the unread messages. Pure. */
+export declare function filterUnread(events: DmInboxEvent[]): DmInboxEvent[];
+/**
+ * Collapse a message body to a single trimmed line for list rendering, capped
+ * so one row stays readable. Pure.
+ */
+export declare function firstLine(body: string, max?: number): string;
+/**
+ * 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 declare function buildThreadQuery(identifier: string): Record<string, string>;
+/** Render one inbox row (marker · age · sender · first line of body). */
+export declare function formatInboxEvent(e: DmInboxEvent, nowMs: number): string;
+/** Render one 1:1 thread line, tagged by direction. */
+export declare function formatThreadMessage(m: DmThreadMessage, nowMs: number): string;
+/** Render one channel/group message line. */
+export declare function formatChannelMessage(m: ChannelMessageItem, nowMs: number): string;
 export declare function registerDmCommand(program: Command): void;
 //# sourceMappingURL=dm.d.ts.map

package/dist/commands/dm.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e95f345b-0e15-52b3-a851-fc97da935a99")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8ba6c13e-f0d4-58c7-a62e-eede4fb7873f")}catch(e){}}();
 import chalk from "chalk";
 import { readFileSync } from "node:fs";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -497,10 +497,294 @@ async function runDmRequests() {
         process.exit(1);
     }
 }
+/**
+ * Human label for a message sender — display name, else email, else uid. Pure →
+ * unit-testable.
+ */
+export function senderLabel(m) {
+    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, nowMs) {
+    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) {
+    return !e.acknowledgedAt;
+}
+/** Event ids of the unread messages in a fetched inbox page. Pure. */
+export function unreadEventIds(events) {
+    return events
+        .filter(isUnread)
+        .map((e) => e.eventId)
+        .filter((id) => typeof id === "string" && id.length > 0);
+}
+/** Keep only the unread messages. Pure. */
+export function filterUnread(events) {
+    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, max = 240) {
+    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) {
+    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, nowMs) {
+    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, 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)}`;
+}
+/** Render one channel/group message line. */
+export function formatChannelMessage(m, nowMs) {
+    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, eventIds) {
+    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(() => ({})));
+        throw new Error(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText));
+    }
+}
+async function runDmInbox(opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const query = {};
+        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(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        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);
+    }
+}
+async function runDmThread(identifier, opts) {
+    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(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        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) => 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, 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;
+    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.`);
+}
+async function runDmChannel(target, opts) {
+    try {
+        const token = await ensureCognitoToken();
+        const channelId = await resolveChannelId(token, target);
+        const query = {};
+        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(() => ({})));
+            console.error(chalk.red(friendlyDmError(res.status, err.code, err.error ?? err.message ?? res.statusText)));
+            process.exit(1);
+        }
+        const data = (await res.json());
+        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) {
     const dm = program
         .command("dm")
-        .description("Send a direct message and manage connection requests.");
+        .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`.')
@@ -514,6 +798,36 @@ export function registerDmCommand(program) {
         .action(async (recipient, message, opts) => {
         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) => {
+        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, opts) => {
+        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, opts) => {
+        await runDmChannel(target, opts);
+    });
     dm
         .command("requests")
         .description("List your pending incoming connection requests.")
@@ -540,4 +854,4 @@ export function registerDmCommand(program) {
     });
 }
 //# sourceMappingURL=dm.js.map
-//# debugId=e95f345b-0e15-52b3-a851-fc97da935a99
+//# debugId=8ba6c13e-f0d4-58c7-a62e-eede4fb7873f

package/dist/commands/outposts.d.ts

@@ -95,6 +95,42 @@ export interface OutpostExecResult {
  * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
  */
 export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
+/** Presigned input-upload details from `mode: "stage"`. */
+export interface OutpostExecStage {
+    ok: true;
+    userId: string;
+    outpostId: string;
+    key: string;
+    putUrl: string;
+    getUrl: string;
+    expiresInSeconds: number;
+}
+/** Asynchronous SSM command details from `mode: "submit"`. */
+export interface OutpostExecSubmission {
+    ok: true;
+    userId: string;
+    outpostId: string;
+    instanceId: string;
+    commandId: string;
+    outputPrefix: string;
+}
+/** Poll response from `mode: "result"`; streams arrive only when terminal. */
+export interface OutpostExecAsyncResult {
+    ok: true;
+    userId: string;
+    outpostId: string;
+    status: string;
+    done: boolean;
+    exitCode?: number | null;
+    stdout?: string;
+    stderr?: string;
+    truncated?: boolean;
+}
+export declare function stageExecInput(token: string, outpostId?: string): Promise<OutpostExecStage>;
+export declare function submitExec(token: string, command: string, outpostId?: string): Promise<OutpostExecSubmission>;
+export declare function fetchExecResult(token: string, commandId: string, outpostId?: string): Promise<OutpostExecAsyncResult>;
+/** Preserve a single command string; safely join argv when Commander split it. */
+export declare function joinCommandParts(commandParts: string[]): string;
 /**
  * Prefix that best-effort `cd`s into the box's HQ checkout before running the
  * caller's command. `exec` runs over two transports with two different default