@indigoai-us/hq-cli 5.39.3 → 5.41.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.41.0]
+
+### Added
+
+- **`hq dm` accepts agent recipients (`agt_…`).** Agents are first-class DM
+  participants server-side (hq-pro #468): an `agt_*` recipient rides the same
+  `toPersonUid` wire field, is gated by the unchanged membership-overlap rule
+  (you can only DM an agent you share an active company with), and is
+  delivered into the agent's durable box inbox — the agent replies by DM as
+  its own `agt_*` identity. Group DMs stay person-only (they're channels);
+  an `agt_*` in a comma-separated recipient list gets a clear error pointing
+  at the 1:1 form.
+
 ## [5.39.3]
 
 ### Fixed

package/dist/commands/auth.js

@@ -14,9 +14,9 @@
  * by the deploy + sync skills.
  */
 
-!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]="e8f8cd77-2f24-5e71-8cb6-518095482b22")}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]="b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8")}catch(e){}}();
 import chalk from "chalk";
-import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, CognitoAuthError, } from "@indigoai-us/hq-cloud";
+import { browserLogin, clearCachedTokens, loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, CognitoAuthError, } from "@indigoai-us/hq-cloud";
 import { refreshCachedSession, } from "../utils/cognito-session.js";
 import { cognitoConfigForLoginProvider } from "../utils/login-provider.js";
 /**
@@ -32,12 +32,22 @@ function peekIdToken(idToken) {
         const pad = payload.length % 4 === 0 ? "" : "=".repeat(4 - (payload.length % 4));
         const normalized = payload.replace(/-/g, "+").replace(/_/g, "/") + pad;
         const decoded = JSON.parse(Buffer.from(normalized, "base64").toString("utf-8"));
-        return { email: decoded.email, sub: decoded.sub };
+        return {
+            email: decoded.email,
+            sub: decoded.sub,
+            entityType: decoded["custom:entityType"],
+            entityUid: decoded["custom:entityUid"],
+        };
     }
     catch {
         return {};
     }
 }
+/** Display label for the local machine identity (company agents). */
+function machineIdentityLabel() {
+    const creds = loadMachineCreds();
+    return creds ? `machine identity ${creds.username}` : "machine identity";
+}
 export function registerAuthCommands(program) {
     const authCmd = program
         .command("auth")
@@ -47,6 +57,10 @@ export function registerAuthCommands(program) {
         .description("Sign in to HQ — opens the Cognito Hosted UI and caches tokens locally")
         .option("--provider <provider>", "OAuth provider to use: google, microsoft, or picker")
         .action(async (options) => {
+        if (isMachineIdentity()) {
+            console.log(chalk.green(`Running as ${machineIdentityLabel()} — sessions mint automatically; no browser login needed.`));
+            return;
+        }
         const existing = loadCachedTokens();
         if (existing && !isExpiring(existing, 120)) {
             const who = peekIdToken(existing.idToken).email ?? "cached session";
@@ -98,12 +112,22 @@ export function registerAuthCommands(program) {
         .command("status")
         .description("Show whether a valid HQ session is cached")
         .action(() => {
+        const machine = isMachineIdentity();
         const cached = loadCachedTokens();
         if (!cached) {
+            if (machine) {
+                // No cached session yet, but machine creds mint one on demand —
+                // report ready, not signed-out.
+                console.log(chalk.green(`${machineIdentityLabel()} — no cached session yet (mints automatically on first use)`));
+                return;
+            }
             console.log(chalk.yellow("No cached HQ session — run `hq auth login`"));
             process.exit(1);
         }
-        const who = peekIdToken(cached.idToken).email;
+        const claims = peekIdToken(cached.idToken);
+        const who = machine
+            ? `${machineIdentityLabel()}${claims.entityUid ? ` (${claims.entityUid})` : ""}`
+            : claims.email;
         const expiring = isExpiring(cached);
         const label = who ? `${who} — ` : "";
         console.log(expiring
@@ -112,4 +136,4 @@ export function registerAuthCommands(program) {
     });
 }
 //# sourceMappingURL=auth.js.map
-//# debugId=e8f8cd77-2f24-5e71-8cb6-518095482b22
+//# debugId=b9690c95-1d23-5c58-8cb3-0e3bdc8b35e8

package/dist/commands/dm.d.ts

@@ -4,10 +4,18 @@ export interface DmRecipient {
     toPersonUid?: string;
 }
 /**
- * Classify a recipient arg as an email or a personUid. Mirrors the
- * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ * 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 declare function detectRecipient(recipient: string): DmRecipient | 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 declare function parseGroupRecipients(recipient: string): string[] | null;
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.

package/dist/commands/dm.js

@@ -1,23 +1,42 @@
 
-!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]="19c5d8e0-ec0a-5b57-b3dc-e2209b60cf2f")}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]="f4bc9146-4033-5a73-a246-6f80a5e0f7ef")}catch(e){}}();
 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]+$/;
-const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+// 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_-]+$/;
 /**
- * Classify a recipient arg as an email or a personUid. Mirrors the
- * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ * 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) {
     const r = recipient.trim();
     if (EMAIL_PATTERN.test(r))
         return { toEmail: r.toLowerCase() };
-    if (PERSON_UID_PATTERN.test(r))
+    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) {
+    if (!recipient.includes(","))
+        return null;
+    const parts = recipient
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return [...new Set(parts)];
+}
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.
@@ -45,7 +64,7 @@ export function parseDuration(input) {
 export function buildDmBody(args) {
     const rcpt = detectRecipient(args.recipient);
     if (!rcpt) {
-        throw new Error(`Invalid recipient '${args.recipient}': must be an email address or a personUid (prs_…).`);
+        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) {
@@ -178,7 +197,82 @@ async function runConnectionAction(action, identifier) {
         process.exit(1);
     }
 }
+/**
+ * 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, message) {
+    try {
+        const participants = [];
+        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(() => ({})));
+            console.error(chalk.red(friendlyDmError(createRes.status, err.code, err.error ?? err.message ?? createRes.statusText)));
+            process.exit(1);
+        }
+        const createData = (await createRes.json());
+        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(() => ({})));
+            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);
+    }
+}
 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) {
+        await runGroupSend(group, message);
+        return;
+    }
     try {
         // Resolve prompt/details from inline text or a file.
         let prompt = opts.prompt;
@@ -261,7 +355,7 @@ export function registerDmCommand(program) {
         .description("Send a direct message and manage connection requests.");
     dm
         .command("send <recipient> [message]", { isDefault: true, hidden: true })
-        .description("Send a direct message to someone (email or personUid). They receive it as an HQ Sync notification. If you aren't connected yet, it sends a connection request that holds your message.")
+        .description('Send a direct message to someone (email, personUid, or agentUid). A person receives it as an HQ Sync notification; an agent receives it in its durable box inbox and replies by DM. If you aren\'t connected yet, it sends a connection request that holds your message. For a GROUP DM, pass a comma-separated recipient: hq dm send "a@x.com,b@y.com" "hi".')
         .option("--prompt <text>", "Agent-context prompt the recipient can one-click copy into their agent")
         .option("--prompt-file <path>", "Read the agent prompt from a file")
         .option("--details <text>", "Longer detail shown in the recipient's DM detail window")
@@ -297,4 +391,4 @@ export function registerDmCommand(program) {
     });
 }
 //# sourceMappingURL=dm.js.map
-//# debugId=19c5d8e0-ec0a-5b57-b3dc-e2209b60cf2f
+//# debugId=f4bc9146-4033-5a73-a246-6f80a5e0f7ef

package/dist/commands/whoami.js

@@ -2,9 +2,9 @@
  * hq whoami — displays current user or 'not logged in'
  */
 
-!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]="7d12196e-3212-5692-9383-5431e2b6a97f")}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]="1603fcc9-75f6-5855-b7b2-8333ffda9389")}catch(e){}}();
 import chalk from 'chalk';
-import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+import { loadCachedTokens, isExpiring, isMachineIdentity, loadMachineCreds, } from '@indigoai-us/hq-cloud';
 function peekIdToken(idToken) {
     try {
         const payload = idToken.split('.')[1];
@@ -13,7 +13,12 @@ function peekIdToken(idToken) {
         const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
         const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
         const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
-        return { email: decoded.email, sub: decoded.sub };
+        return {
+            email: decoded.email,
+            sub: decoded.sub,
+            entityType: decoded['custom:entityType'],
+            entityUid: decoded['custom:entityUid'],
+        };
     }
     catch {
         return {};
@@ -25,7 +30,19 @@ export function registerWhoamiCommand(program) {
         .description('Show the currently authenticated user')
         .action(async () => {
         try {
+            const machine = isMachineIdentity();
             const cached = loadCachedTokens();
+            if (machine) {
+                // Machine identities (company agents) mint sessions on demand from
+                // long-lived creds — report the machine identity honestly even when
+                // no session is cached yet.
+                const username = loadMachineCreds()?.username ?? 'unknown';
+                const entityUid = cached
+                    ? peekIdToken(cached.idToken).entityUid
+                    : undefined;
+                console.log(`Machine identity ${username}${entityUid ? ` (agent ${entityUid})` : ''} — sessions mint automatically`);
+                return;
+            }
             if (!cached) {
                 console.log("Not logged in. Run 'hq login' to authenticate.");
                 return;
@@ -45,4 +62,4 @@ export function registerWhoamiCommand(program) {
     });
 }
 //# sourceMappingURL=whoami.js.map
-//# debugId=7d12196e-3212-5692-9383-5431e2b6a97f
+//# debugId=1603fcc9-75f6-5855-b7b2-8333ffda9389

package/dist/utils/cognito-session.js

@@ -19,13 +19,13 @@
  *   HQ_VAULT_API_URL           — vault-service API Gateway URL
  */
 
-!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]="984bafe3-242a-5322-a2fe-65261b24ee0b")}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]="783fe478-9e12-55a7-a3d8-241ea2cf5886")}catch(e){}}();
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import * as yaml from "js-yaml";
 import chalk from "chalk";
-import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, } from "@indigoai-us/hq-cloud";
+import { loadCachedTokens, isExpiring, refreshTokens, browserLogin, detectHqCoreVersion, isMachineIdentity, getValidMachineTokens, mintMachineTokens, } from "@indigoai-us/hq-cloud";
 import { CLI_NAME, CLI_VERSION } from "../cli-version.js";
 export const DEFAULT_COGNITO = {
     region: process.env.AWS_REGION ?? "us-east-1",
@@ -232,6 +232,18 @@ export const DEFAULT_HQ_ROOT = resolveDefaultHqRoot();
  */
 export async function ensureCognitoToken(options = {}) {
     const interactive = options.interactive ?? true;
+    // Machine identities (company agents) mint sessions on demand via
+    // USER_PASSWORD_AUTH — no refresh-token dance, no browser. The vault API's
+    // JWT authorizer accepts ID tokens, and the agent's identity claims
+    // (custom:entityType=agent, custom:entityUid=agt_*) ride the ID token ONLY,
+    // so vault-API calls from a machine identity send the ID token. The cached
+    // token file keeps correct field semantics (real access token in
+    // accessToken) for consumers that need token_use=access, e.g. the deploy
+    // API via the deploy skill.
+    if (isMachineIdentity()) {
+        const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+        return machine.idToken;
+    }
     const cached = loadCachedTokens();
     if (cached && !isExpiring(cached, 120)) {
         return cached.accessToken;
@@ -286,6 +298,20 @@ export function buildVaultConfig(authToken) {
  * with a reason string so the caller can decide what to do.
  */
 export async function refreshCachedSession() {
+    // Machine identities have no refresh token — a "refresh" is a fresh mint
+    // from the long-lived machine creds.
+    if (isMachineIdentity()) {
+        try {
+            await mintMachineTokens(DEFAULT_COGNITO);
+            return { refreshed: true };
+        }
+        catch (err) {
+            return {
+                refreshed: false,
+                reason: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
     const cached = loadCachedTokens();
     if (!cached) {
         return { refreshed: false, reason: "no cached session" };
@@ -302,4 +328,4 @@ export async function refreshCachedSession() {
     }
 }
 //# sourceMappingURL=cognito-session.js.map
-//# debugId=984bafe3-242a-5322-a2fe-65261b24ee0b
+//# debugId=783fe478-9e12-55a7-a3d8-241ea2cf5886

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.39.3",
-  "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
+  "version": "5.41.0",
+  "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
     "hq": "dist/index.js",
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.6.0",
+    "@indigoai-us/hq-cloud": "^6.7.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "chalk": "^5.3.0",

package/src/commands/auth.ts

@@ -21,6 +21,8 @@ import {
   clearCachedTokens,
   loadCachedTokens,
   isExpiring,
+  isMachineIdentity,
+  loadMachineCreds,
   CognitoAuthError,
 } from "@indigoai-us/hq-cloud";
 import {
@@ -36,7 +38,7 @@ import { cognitoConfigForLoginProvider } from "../utils/login-provider.js";
  */
 function peekIdToken(
   idToken: string,
-): { email?: string; sub?: string } {
+): { email?: string; sub?: string; entityType?: string; entityUid?: string } {
   try {
     const payload = idToken.split(".")[1];
     if (!payload) return {};
@@ -47,12 +49,23 @@ function peekIdToken(
     const decoded = JSON.parse(
       Buffer.from(normalized, "base64").toString("utf-8"),
     );
-    return { email: decoded.email, sub: decoded.sub };
+    return {
+      email: decoded.email,
+      sub: decoded.sub,
+      entityType: decoded["custom:entityType"],
+      entityUid: decoded["custom:entityUid"],
+    };
   } catch {
     return {};
   }
 }
 
+/** Display label for the local machine identity (company agents). */
+function machineIdentityLabel(): string {
+  const creds = loadMachineCreds();
+  return creds ? `machine identity ${creds.username}` : "machine identity";
+}
+
 export function registerAuthCommands(program: Command): void {
   const authCmd = program
     .command("auth")
@@ -68,6 +81,14 @@ export function registerAuthCommands(program: Command): void {
       "OAuth provider to use: google, microsoft, or picker",
     )
     .action(async (options: { provider?: string }) => {
+      if (isMachineIdentity()) {
+        console.log(
+          chalk.green(
+            `Running as ${machineIdentityLabel()} — sessions mint automatically; no browser login needed.`,
+          ),
+        );
+        return;
+      }
       const existing = loadCachedTokens();
       if (existing && !isExpiring(existing, 120)) {
         const who = peekIdToken(existing.idToken).email ?? "cached session";
@@ -134,12 +155,26 @@ export function registerAuthCommands(program: Command): void {
     .command("status")
     .description("Show whether a valid HQ session is cached")
     .action(() => {
+      const machine = isMachineIdentity();
       const cached = loadCachedTokens();
       if (!cached) {
+        if (machine) {
+          // No cached session yet, but machine creds mint one on demand —
+          // report ready, not signed-out.
+          console.log(
+            chalk.green(
+              `${machineIdentityLabel()} — no cached session yet (mints automatically on first use)`,
+            ),
+          );
+          return;
+        }
         console.log(chalk.yellow("No cached HQ session — run `hq auth login`"));
         process.exit(1);
       }
-      const who = peekIdToken(cached.idToken).email;
+      const claims = peekIdToken(cached.idToken);
+      const who = machine
+        ? `${machineIdentityLabel()}${claims.entityUid ? ` (${claims.entityUid})` : ""}`
+        : claims.email;
       const expiring = isExpiring(cached);
       const label = who ? `${who} — ` : "";
       console.log(

package/src/commands/dm.test.ts

@@ -21,6 +21,7 @@ import { Command } from "commander";
 import {
   detectRecipient,
   parseDuration,
+  parseGroupRecipients,
   buildDmBody,
   matchRequest,
   buildConnectionActionBody,
@@ -28,6 +29,19 @@ import {
   type ConnectionRequest,
 } from "./dm.js";
 
+describe("parseGroupRecipients", () => {
+  it("returns null with no comma (the 1:1 path)", () => {
+    expect(parseGroupRecipients("a@x.com")).toBeNull();
+    expect(parseGroupRecipients("prs_1")).toBeNull();
+  });
+  it("splits, trims, and de-dupes a comma list", () => {
+    expect(parseGroupRecipients("a@x.com, b@y.com ,a@x.com")).toEqual([
+      "a@x.com",
+      "b@y.com",
+    ]);
+  });
+});
+
 describe("detectRecipient", () => {
   it("classifies an email", () => {
     expect(detectRecipient("Stefan@Getindigo.ai")).toEqual({
@@ -37,9 +51,16 @@ describe("detectRecipient", () => {
   it("classifies a personUid", () => {
     expect(detectRecipient("prs_01ABC")).toEqual({ toPersonUid: "prs_01ABC" });
   });
+  it("classifies an agentUid on the same wire field (server accepts agt_*)", () => {
+    expect(detectRecipient("agt_01KTT1RJJ6KQRHNHHST0K4VRGT")).toEqual({
+      toPersonUid: "agt_01KTT1RJJ6KQRHNHHST0K4VRGT",
+    });
+  });
   it("rejects anything else", () => {
     expect(detectRecipient("not-an-email")).toBeNull();
     expect(detectRecipient("")).toBeNull();
+    expect(detectRecipient("cmp_01ABC")).toBeNull();
+    expect(detectRecipient("agt")).toBeNull();
   });
 });
 
@@ -79,6 +100,12 @@ describe("buildDmBody", () => {
     ).toEqual({ toPersonUid: "prs_x", body: "m", prompt: "do the thing" });
   });
 
+  it("builds an agent DM (agt_* rides toPersonUid)", () => {
+    expect(
+      buildDmBody({ recipient: "agt_01ABC", message: "status?", now }),
+    ).toEqual({ toPersonUid: "agt_01ABC", body: "status?" });
+  });
+
   it("resolves --in to a future deliverAt", () => {
     const out = buildDmBody({ recipient: "a@b.com", message: "m", inDelay: "10m", now });
     expect(out.deliverAt).toBe("2026-05-29T00:10:00.000Z");
@@ -220,6 +247,36 @@ describe("dm command actions", () => {
     expect(errSpy).not.toHaveBeenCalled();
   });
 
+  it("group send: a comma recipient creates a group then posts the message", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { channel: { channelId: "chn_grp1" }, created: true }),
+      )
+      .mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_g" }));
+    await program.parseAsync(
+      ["dm", "alice@example.com,bob@example.com", "hey team"],
+      { from: "user" },
+    );
+    // 1st call creates the group channel...
+    const createCall = fetchSpy.mock.calls[0];
+    expect(String(createCall[0])).toContain("/v1/notify/channels");
+    const createBody = JSON.parse((createCall[1]?.body as string) ?? "{}");
+    expect(createBody.scope).toBe("group");
+    expect(createBody.participants).toEqual(["alice@example.com", "bob@example.com"]);
+    // ...2nd posts the message into it.
+    const sendCall = fetchSpy.mock.calls[1];
+    expect(String(sendCall[0])).toContain("/v1/notify/channels/chn_grp1/messages");
+    expect(JSON.parse((sendCall[1]?.body as string) ?? "{}").body).toBe("hey team");
+    expect(logged()).toMatch(/Group DM sent to 2 people \(new group\)\./);
+    expect(errSpy).not.toHaveBeenCalled();
+  });
+
+  it("group send: a single recipient still uses the 1:1 dm path", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { eventId: "evt_1" }));
+    await program.parseAsync(["dm", "alice@example.com", "hi"], { from: "user" });
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/notify/dm");
+  });
+
   it("send: prints pending request on 202 connection_requested (not an error)", async () => {
     fetchSpy.mockResolvedValueOnce(
       jsonResponse(202, { state: "connection_requested" }),

package/src/commands/dm.ts

@@ -5,7 +5,10 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
 
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
-const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+// 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;
@@ -13,16 +16,32 @@ export interface DmRecipient {
 }
 
 /**
- * Classify a recipient arg as an email or a personUid. Mirrors the
- * email/prs_ heuristic used by `hq members`. Returns null for neither.
+ * 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 (PERSON_UID_PATTERN.test(r)) return { toPersonUid: r };
+  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)];
+}
+
 /**
  * Parse a relative duration like `30s`, `10m`, `2h`, `1d` into milliseconds.
  * Returns null on anything that doesn't match. Pure → unit-testable.
@@ -68,7 +87,7 @@ export function buildDmBody(args: {
   const rcpt = detectRecipient(args.recipient);
   if (!rcpt) {
     throw new Error(
-      `Invalid recipient '${args.recipient}': must be an email address or a personUid (prs_…).`,
+      `Invalid recipient '${args.recipient}': must be an email address, a personUid (prs_…), or an agentUid (agt_…).`,
     );
   }
   const body = (args.message ?? "").trim();
@@ -248,11 +267,134 @@ interface DmSendOpts {
   in?: 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);
+  }
+}
+
 async function runDmSend(
   recipient: string,
   message: string | undefined,
   opts: DmSendOpts,
 ): Promise<void> {
+  // 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;
+  }
   try {
     // Resolve prompt/details from inline text or a file.
     let prompt = opts.prompt;
@@ -376,7 +518,7 @@ export function registerDmCommand(program: Command): void {
   dm
     .command("send <recipient> [message]", { isDefault: true, hidden: true })
     .description(
-      "Send a direct message to someone (email or personUid). They receive it as an HQ Sync notification. If you aren't connected yet, it sends a connection request that holds your message.",
+      'Send a direct message to someone (email, personUid, or agentUid). A person receives it as an HQ Sync notification; an agent receives it in its durable box inbox and replies by DM. If you aren\'t connected yet, it sends a connection request that holds your message. For a GROUP DM, pass a comma-separated recipient: hq dm send "a@x.com,b@y.com" "hi".',
     )
     .option(
       "--prompt <text>",

package/src/commands/whoami.ts

@@ -4,16 +4,31 @@
 
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { loadCachedTokens, isExpiring } from '@indigoai-us/hq-cloud';
+import {
+  loadCachedTokens,
+  isExpiring,
+  isMachineIdentity,
+  loadMachineCreds,
+} from '@indigoai-us/hq-cloud';
 
-function peekIdToken(idToken: string): { email?: string; sub?: string } {
+function peekIdToken(idToken: string): {
+  email?: string;
+  sub?: string;
+  entityType?: string;
+  entityUid?: string;
+} {
   try {
     const payload = idToken.split('.')[1];
     if (!payload) return {};
     const pad = payload.length % 4 === 0 ? '' : '='.repeat(4 - (payload.length % 4));
     const normalized = payload.replace(/-/g, '+').replace(/_/g, '/') + pad;
     const decoded = JSON.parse(Buffer.from(normalized, 'base64').toString('utf-8'));
-    return { email: decoded.email, sub: decoded.sub };
+    return {
+      email: decoded.email,
+      sub: decoded.sub,
+      entityType: decoded['custom:entityType'],
+      entityUid: decoded['custom:entityUid'],
+    };
   } catch {
     return {};
   }
@@ -25,8 +40,23 @@ export function registerWhoamiCommand(program: Command): void {
     .description('Show the currently authenticated user')
     .action(async () => {
       try {
+        const machine = isMachineIdentity();
         const cached = loadCachedTokens();
 
+        if (machine) {
+          // Machine identities (company agents) mint sessions on demand from
+          // long-lived creds — report the machine identity honestly even when
+          // no session is cached yet.
+          const username = loadMachineCreds()?.username ?? 'unknown';
+          const entityUid = cached
+            ? peekIdToken(cached.idToken).entityUid
+            : undefined;
+          console.log(
+            `Machine identity ${username}${entityUid ? ` (agent ${entityUid})` : ''} — sessions mint automatically`
+          );
+          return;
+        }
+
         if (!cached) {
           console.log("Not logged in. Run 'hq login' to authenticate.");
           return;

package/src/utils/cognito-session.machine.test.ts

@@ -0,0 +1,114 @@
+/**
+ * Machine-identity behavior of the shared Cognito session helpers.
+ *
+ * When machine creds are present (company agent boxes), the CLI must:
+ *   - return the ID token from ensureCognitoToken() — the vault API's JWT
+ *     authorizer accepts ID tokens and the agent claims
+ *     (custom:entityType/custom:entityUid) ride the ID token only
+ *   - never refresh or open a browser — sessions re-mint on demand
+ *   - treat `hq auth refresh` as a fresh mint instead of "no cached session"
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  isMachineIdentity: vi.fn(),
+  getValidMachineTokens: vi.fn(),
+  mintMachineTokens: vi.fn(),
+  loadCachedTokens: vi.fn(),
+  refreshTokens: vi.fn(),
+  browserLogin: vi.fn(),
+  isExpiring: vi.fn(),
+}));
+
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return { ...actual, ...mocks };
+});
+
+import {
+  ensureCognitoToken,
+  refreshCachedSession,
+} from "./cognito-session.js";
+
+const MACHINE_TOKENS = {
+  accessToken: "machine-access-token",
+  idToken: "machine-id-token",
+  refreshToken: "",
+  expiresAt: Date.now() + 3600_000,
+  tokenType: "Bearer" as const,
+};
+
+beforeEach(() => {
+  vi.resetAllMocks();
+});
+
+describe("ensureCognitoToken in machine mode", () => {
+  it("returns the ID token (agent claims ride the ID token only)", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.getValidMachineTokens.mockResolvedValue(MACHINE_TOKENS);
+
+    const token = await ensureCognitoToken({ interactive: false });
+
+    expect(token).toBe("machine-id-token");
+    expect(mocks.getValidMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
+    expect(mocks.loadCachedTokens).not.toHaveBeenCalled();
+  });
+
+  it("falls through to the browser-session path for human identities", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue({
+      ...MACHINE_TOKENS,
+      accessToken: "human-access-token",
+    });
+    mocks.isExpiring.mockReturnValue(false);
+
+    const token = await ensureCognitoToken({ interactive: false });
+
+    expect(token).toBe("human-access-token");
+    expect(mocks.getValidMachineTokens).not.toHaveBeenCalled();
+  });
+
+  it("propagates mint failures instead of opening a browser", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.getValidMachineTokens.mockRejectedValue(new Error("mint failed"));
+
+    await expect(ensureCognitoToken()).rejects.toThrow("mint failed");
+    expect(mocks.browserLogin).not.toHaveBeenCalled();
+  });
+});
+
+describe("refreshCachedSession in machine mode", () => {
+  it("re-mints instead of answering 'no cached session'", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.mintMachineTokens.mockResolvedValue(MACHINE_TOKENS);
+    mocks.loadCachedTokens.mockReturnValue(null);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: true });
+    expect(mocks.mintMachineTokens).toHaveBeenCalledTimes(1);
+    expect(mocks.refreshTokens).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the mint error as the reason on failure", async () => {
+    mocks.isMachineIdentity.mockReturnValue(true);
+    mocks.mintMachineTokens.mockRejectedValue(new Error("NotAuthorized"));
+
+    const result = await refreshCachedSession();
+
+    expect(result.refreshed).toBe(false);
+    expect(result.reason).toContain("NotAuthorized");
+  });
+
+  it("keeps the human refresh path unchanged", async () => {
+    mocks.isMachineIdentity.mockReturnValue(false);
+    mocks.loadCachedTokens.mockReturnValue(null);
+
+    const result = await refreshCachedSession();
+
+    expect(result).toEqual({ refreshed: false, reason: "no cached session" });
+  });
+});

package/src/utils/cognito-session.ts

@@ -30,6 +30,9 @@ import {
   refreshTokens,
   browserLogin,
   detectHqCoreVersion,
+  isMachineIdentity,
+  getValidMachineTokens,
+  mintMachineTokens,
   type CognitoAuthConfig,
   type ClientInfo,
   type VaultServiceConfig,
@@ -266,6 +269,20 @@ export async function ensureCognitoToken(options: {
   interactive?: boolean;
 } = {}): Promise<string> {
   const interactive = options.interactive ?? true;
+
+  // Machine identities (company agents) mint sessions on demand via
+  // USER_PASSWORD_AUTH — no refresh-token dance, no browser. The vault API's
+  // JWT authorizer accepts ID tokens, and the agent's identity claims
+  // (custom:entityType=agent, custom:entityUid=agt_*) ride the ID token ONLY,
+  // so vault-API calls from a machine identity send the ID token. The cached
+  // token file keeps correct field semantics (real access token in
+  // accessToken) for consumers that need token_use=access, e.g. the deploy
+  // API via the deploy skill.
+  if (isMachineIdentity()) {
+    const machine = await getValidMachineTokens(DEFAULT_COGNITO);
+    return machine.idToken;
+  }
+
   const cached = loadCachedTokens();
 
   if (cached && !isExpiring(cached, 120)) {
@@ -335,6 +352,20 @@ export async function refreshCachedSession(): Promise<{
   refreshed: boolean;
   reason?: string;
 }> {
+  // Machine identities have no refresh token — a "refresh" is a fresh mint
+  // from the long-lived machine creds.
+  if (isMachineIdentity()) {
+    try {
+      await mintMachineTokens(DEFAULT_COGNITO);
+      return { refreshed: true };
+    } catch (err) {
+      return {
+        refreshed: false,
+        reason: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
   const cached = loadCachedTokens();
   if (!cached) {
     return { refreshed: false, reason: "no cached session" };