@indigoai-us/hq-cli 5.66.0 → 5.68.0

package/dist/commands/agents.d.ts

@@ -126,5 +126,29 @@ export declare function deprovisionAgent(token: string, agentUid: string): Promi
 }>;
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export declare function appliedHint(applied: boolean): string;
+/** One message in a DM thread, as returned by `GET /v1/notify/thread`. */
+export interface DmThreadMessage {
+    eventId: string;
+    fromPersonUid: string;
+    fromDisplayName?: string;
+    fromEmail?: string;
+    body: string;
+    createdAt: string;
+    /** "out" = sent by the caller; "in" = received (the agent's reply). */
+    direction: "in" | "out";
+}
+/**
+ * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
+ * directly; anything else is treated as a slug or display name and resolved
+ * against the company's roster (requires `--company` or a single active
+ * membership).
+ */
+export declare function resolveAgentUid(token: string, ref: string, companySlug: string | undefined): Promise<string>;
+/** Send a DM to an agent. Returns nothing meaningful beyond success. */
+export declare function sendAgentDm(token: string, agentUid: string, message: string): Promise<void>;
+/** Read the two-way DM conversation with an agent (most recent `limit`). */
+export declare function readAgentThread(token: string, agentUid: string, limit?: number): Promise<DmThreadMessage[]>;
+/** Render one thread message as a labeled line for the terminal. */
+export declare function formatThreadMessage(m: DmThreadMessage, agentLabel: string): string;
 export declare function registerAgentsCommand(program: Command): void;
 //# sourceMappingURL=agents.d.ts.map

package/dist/commands/agents.js

@@ -22,7 +22,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 
-!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]="581b1950-a9bc-50a4-b16b-6e6649e9db30")}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]="26009666-ef42-5f7d-88eb-6452eca4b47a")}catch(e){}}();
 import chalk from "chalk";
 import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
@@ -144,6 +144,69 @@ export function appliedHint(applied) {
         : "saved — takes effect on the agent's next launch";
 }
 // ---------------------------------------------------------------------------
+// Talking to agents (DM). Agents are members addressable over HQ's DM system:
+// a message rides `POST /v1/notify/dm` (the wire contract accepts `agt_*`), the
+// agent's box picks it up and replies over DM (a first-class agent reply
+// channel), and the two-way conversation is read back via `GET /v1/notify/thread`.
+// ---------------------------------------------------------------------------
+/** Agent uid shape (`agt_…`). */
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+/**
+ * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
+ * directly; anything else is treated as a slug or display name and resolved
+ * against the company's roster (requires `--company` or a single active
+ * membership).
+ */
+export async function resolveAgentUid(token, ref, companySlug) {
+    if (AGENT_UID_PATTERN.test(ref.trim()))
+        return ref.trim();
+    const companyUid = await getCompanyUid(token, companySlug);
+    const roster = await listAgents(token, companyUid);
+    const needle = ref.trim().toLowerCase();
+    const match = roster.find((a) => a.slug?.toLowerCase() === needle ||
+        a.name?.toLowerCase() === needle ||
+        a.uid === ref.trim());
+    if (!match) {
+        throw new AgentsHttpError(404, `No agent named "${ref}" in this company. Run \`hq agents list\` to see slugs/uids, ` +
+            `or pass the agt_ uid directly.`);
+    }
+    return match.uid;
+}
+/** Send a DM to an agent. Returns nothing meaningful beyond success. */
+export async function sendAgentDm(token, agentUid, message) {
+    await agentsRequest({
+        token,
+        path: "/v1/notify/dm",
+        method: "POST",
+        body: { toPersonUid: agentUid, body: message },
+    });
+}
+/** Read the two-way DM conversation with an agent (most recent `limit`). */
+export async function readAgentThread(token, agentUid, limit = 20) {
+    const data = await agentsRequest({
+        token,
+        path: "/v1/notify/thread",
+        query: { withPersonUid: agentUid, limit: String(limit) },
+    });
+    return data.messages ?? [];
+}
+/** Render one thread message as a labeled line for the terminal. */
+export function formatThreadMessage(m, agentLabel) {
+    const who = m.direction === "out"
+        ? chalk.cyan("you")
+        : chalk.magenta(m.fromDisplayName || agentLabel);
+    const when = chalk.dim(shortTime(m.createdAt));
+    return `${who} ${when}\n  ${m.body.replace(/\n/g, "\n  ")}`;
+}
+function shortTime(iso) {
+    // Keep it dependency-free and stable: trim the ISO string to `MM-DD HH:MM`.
+    const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}:\d{2})/);
+    return m ? `${m[2]}-${m[3]} ${m[4]}` : iso;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
 function fail(err) {
@@ -165,6 +228,88 @@ export function registerAgentsCommand(program) {
     // `hq agents --company acme list`.
     const companyOf = (sub) => sub.opts().company ??
         agents.opts().company;
+    agents
+        .command("message <agent> <message...>")
+        .alias("msg")
+        .description("Send a message to an agent and wait for its reply")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .option("--no-wait", "Send without waiting for the agent's reply")
+        .option("--timeout <seconds>", "How long to wait for a reply", "90")
+        .option("--json", "Emit raw JSON")
+        .action(async function (agent, messageParts, opts) {
+        try {
+            const message = messageParts.join(" ").trim();
+            if (!message) {
+                console.error(chalk.red("No message given. Usage: hq agents message <agent> <text>"));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+            // Baseline the conversation so we can detect the agent's NEW reply.
+            const before = opts.wait === false ? [] : await readAgentThread(token, agentUid, 1);
+            const lastBeforeAt = before.length ? before[before.length - 1].createdAt : "";
+            await sendAgentDm(token, agentUid, message);
+            if (opts.wait === false) {
+                console.log(chalk.green(`Sent to ${agent}.`));
+                console.log(chalk.dim(`Read replies later: hq agents thread ${agent}`));
+                return;
+            }
+            // Poll the thread until a new inbound (agent) message appears or timeout.
+            const timeoutMs = Math.max(5, Number(opts.timeout) || 90) * 1000;
+            const deadline = Date.now() + timeoutMs;
+            if (!opts.json)
+                console.log(chalk.dim(`Sent — waiting for ${agent} to reply…`));
+            let reply;
+            while (Date.now() < deadline) {
+                await sleep(3000);
+                const msgs = await readAgentThread(token, agentUid, 10);
+                reply = msgs.find((m) => m.direction === "in" && m.createdAt > lastBeforeAt);
+                if (reply)
+                    break;
+            }
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ agentUid, sent: message, reply: reply ?? null }, null, 2) + "\n");
+                return;
+            }
+            if (reply) {
+                console.log(formatThreadMessage(reply, agent));
+            }
+            else {
+                console.log(chalk.yellow(`No reply within ${Math.round(timeoutMs / 1000)}s. The agent may still respond — ` +
+                    `check with: hq agents thread ${agent}`));
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    agents
+        .command("thread <agent>")
+        .alias("history")
+        .description("Show your recent conversation with an agent")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .option("--limit <n>", "How many recent messages to show", "20")
+        .option("--json", "Emit raw JSON")
+        .action(async function (agent, opts) {
+        try {
+            const token = await ensureCognitoToken();
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+            const limit = Math.max(1, Number(opts.limit) || 20);
+            const msgs = await readAgentThread(token, agentUid, limit);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(msgs, null, 2) + "\n");
+                return;
+            }
+            if (msgs.length === 0) {
+                console.log(chalk.gray(`No conversation yet with ${agent}. Start one: hq agents message ${agent} "<text>"`));
+                return;
+            }
+            console.log(msgs.map((m) => formatThreadMessage(m, agent)).join("\n\n"));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     agents
         .command("provision <name>")
         .alias("new")
@@ -476,4 +621,4 @@ export function registerAgentsCommand(program) {
     });
 }
 //# sourceMappingURL=agents.js.map
-//# debugId=581b1950-a9bc-50a4-b16b-6e6649e9db30
+//# debugId=26009666-ef42-5f7d-88eb-6452eca4b47a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.66.0",
+  "version": "5.68.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.14.3",
+    "@indigoai-us/hq-cloud": "^6.14.4",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",

package/src/commands/agents.test.ts

@@ -379,3 +379,108 @@ describe("hq agents provision (billing gate)", () => {
     expect(fetchSpy).not.toHaveBeenCalled();
   });
 });
+
+describe("hq agents talk (message / thread)", () => {
+  function agentRow(uid: string, slug: string, name: string) {
+    return { uid, slug, name, companyUid: "cmp_acme" };
+  }
+
+  it("resolves an agent by slug and reads the thread", async () => {
+    // 1) roster lookup for slug→uid, 2) thread read
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, { agents: [agentRow("agt_deacon", "deacon", "Deacon")] }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          messages: [
+            {
+              eventId: "e1",
+              fromPersonUid: "prs_me",
+              body: "hi",
+              createdAt: "2026-07-13T10:00",
+              direction: "out",
+            },
+            {
+              eventId: "e2",
+              fromPersonUid: "agt_deacon",
+              fromDisplayName: "Deacon",
+              body: "hello back",
+              createdAt: "2026-07-13T10:01",
+              direction: "in",
+            },
+          ],
+        }),
+      );
+
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...a) => {
+      logs.push(a.map(String).join(" "));
+    });
+    await run(["agents", "--company", "acme", "thread", "deacon"]);
+
+    // roster call then thread call
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("/v1/agents");
+    const threadUrl = String(fetchSpy.mock.calls[1][0]);
+    expect(threadUrl).toContain("/v1/notify/thread");
+    expect(threadUrl).toContain("withPersonUid=agt_deacon");
+    const out = logs.join("\n");
+    expect(out).toContain("hello back");
+    expect(out).toContain("hi");
+  });
+
+  it("passes an agt_ uid straight through (no roster lookup)", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { messages: [] }));
+    await run(["agents", "thread", "agt_xyz"]);
+    // Only the thread call — no /v1/agents roster fetch.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(String(fetchSpy.mock.calls[0][0])).toContain("withPersonUid=agt_xyz");
+    expect(mockGetCompanyUid).not.toHaveBeenCalled();
+  });
+
+  it("message --no-wait POSTs the DM and does not poll", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true })); // POST /v1/notify/dm
+    await run(["agents", "message", "agt_xyz", "--no-wait", "hello", "there"]);
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/notify/dm");
+    expect(init?.method).toBe("POST");
+    expect(JSON.parse(init?.body as string)).toEqual({
+      toPersonUid: "agt_xyz",
+      body: "hello there",
+    });
+  });
+
+  it("message waits for and prints the agent's reply", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(jsonResponse(200, { messages: [] })) // baseline read
+      .mockResolvedValueOnce(jsonResponse(200, { ok: true })) // POST dm
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          messages: [
+            {
+              eventId: "r1",
+              fromPersonUid: "agt_xyz",
+              fromDisplayName: "Xyz",
+              body: "on it",
+              createdAt: "2026-07-13T11:00",
+              direction: "in",
+            },
+          ],
+        }),
+      ); // first poll returns the reply
+
+    const logs: string[] = [];
+    vi.spyOn(console, "log").mockImplementation((...a) => {
+      logs.push(a.map(String).join(" "));
+    });
+    await run(["agents", "message", "agt_xyz", "--timeout", "10", "ping"]);
+    expect(logs.join("\n")).toContain("on it");
+  }, 10000);
+
+  it("requires a non-empty message", async () => {
+    await expect(
+      run(["agents", "message", "agt_xyz", "   "]),
+    ).rejects.toThrow("process.exit(1)");
+  });
+});

package/src/commands/agents.ts

@@ -265,6 +265,107 @@ export function appliedHint(applied: boolean): string {
     : "saved — takes effect on the agent's next launch";
 }
 
+// ---------------------------------------------------------------------------
+// Talking to agents (DM). Agents are members addressable over HQ's DM system:
+// a message rides `POST /v1/notify/dm` (the wire contract accepts `agt_*`), the
+// agent's box picks it up and replies over DM (a first-class agent reply
+// channel), and the two-way conversation is read back via `GET /v1/notify/thread`.
+// ---------------------------------------------------------------------------
+
+/** Agent uid shape (`agt_…`). */
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/;
+
+/** One message in a DM thread, as returned by `GET /v1/notify/thread`. */
+export interface DmThreadMessage {
+  eventId: string;
+  fromPersonUid: string;
+  fromDisplayName?: string;
+  fromEmail?: string;
+  body: string;
+  createdAt: string;
+  /** "out" = sent by the caller; "in" = received (the agent's reply). */
+  direction: "in" | "out";
+}
+
+/**
+ * Resolve an agent reference to its `agt_` uid. An `agt_…` value is used
+ * directly; anything else is treated as a slug or display name and resolved
+ * against the company's roster (requires `--company` or a single active
+ * membership).
+ */
+export async function resolveAgentUid(
+  token: string,
+  ref: string,
+  companySlug: string | undefined,
+): Promise<string> {
+  if (AGENT_UID_PATTERN.test(ref.trim())) return ref.trim();
+  const companyUid = await getCompanyUid(token, companySlug);
+  const roster = await listAgents(token, companyUid);
+  const needle = ref.trim().toLowerCase();
+  const match = roster.find(
+    (a) =>
+      a.slug?.toLowerCase() === needle ||
+      a.name?.toLowerCase() === needle ||
+      a.uid === ref.trim(),
+  );
+  if (!match) {
+    throw new AgentsHttpError(
+      404,
+      `No agent named "${ref}" in this company. Run \`hq agents list\` to see slugs/uids, ` +
+        `or pass the agt_ uid directly.`,
+    );
+  }
+  return match.uid;
+}
+
+/** Send a DM to an agent. Returns nothing meaningful beyond success. */
+export async function sendAgentDm(
+  token: string,
+  agentUid: string,
+  message: string,
+): Promise<void> {
+  await agentsRequest({
+    token,
+    path: "/v1/notify/dm",
+    method: "POST",
+    body: { toPersonUid: agentUid, body: message },
+  });
+}
+
+/** Read the two-way DM conversation with an agent (most recent `limit`). */
+export async function readAgentThread(
+  token: string,
+  agentUid: string,
+  limit = 20,
+): Promise<DmThreadMessage[]> {
+  const data = await agentsRequest<{ messages: DmThreadMessage[] }>({
+    token,
+    path: "/v1/notify/thread",
+    query: { withPersonUid: agentUid, limit: String(limit) },
+  });
+  return data.messages ?? [];
+}
+
+/** Render one thread message as a labeled line for the terminal. */
+export function formatThreadMessage(m: DmThreadMessage, agentLabel: string): string {
+  const who =
+    m.direction === "out"
+      ? chalk.cyan("you")
+      : chalk.magenta(m.fromDisplayName || agentLabel);
+  const when = chalk.dim(shortTime(m.createdAt));
+  return `${who} ${when}\n  ${m.body.replace(/\n/g, "\n  ")}`;
+}
+
+function shortTime(iso: string): string {
+  // Keep it dependency-free and stable: trim the ISO string to `MM-DD HH:MM`.
+  const m = iso.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}:\d{2})/);
+  return m ? `${m[2]}-${m[3]} ${m[4]}` : iso;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -294,6 +395,107 @@ export function registerAgentsCommand(program: Command): void {
     (sub.opts().company as string | undefined) ??
     (agents.opts().company as string | undefined);
 
+  agents
+    .command("message <agent> <message...>")
+    .alias("msg")
+    .description("Send a message to an agent and wait for its reply")
+    .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+    .option("--no-wait", "Send without waiting for the agent's reply")
+    .option("--timeout <seconds>", "How long to wait for a reply", "90")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      agent: string,
+      messageParts: string[],
+      opts: { company?: string; wait?: boolean; timeout?: string; json?: boolean },
+    ) {
+      try {
+        const message = messageParts.join(" ").trim();
+        if (!message) {
+          console.error(chalk.red("No message given. Usage: hq agents message <agent> <text>"));
+          process.exit(1);
+        }
+        const token = await ensureCognitoToken();
+        const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+
+        // Baseline the conversation so we can detect the agent's NEW reply.
+        const before = opts.wait === false ? [] : await readAgentThread(token, agentUid, 1);
+        const lastBeforeAt = before.length ? before[before.length - 1].createdAt : "";
+
+        await sendAgentDm(token, agentUid, message);
+
+        if (opts.wait === false) {
+          console.log(chalk.green(`Sent to ${agent}.`));
+          console.log(chalk.dim(`Read replies later: hq agents thread ${agent}`));
+          return;
+        }
+
+        // Poll the thread until a new inbound (agent) message appears or timeout.
+        const timeoutMs = Math.max(5, Number(opts.timeout) || 90) * 1000;
+        const deadline = Date.now() + timeoutMs;
+        if (!opts.json) console.log(chalk.dim(`Sent — waiting for ${agent} to reply…`));
+        let reply: DmThreadMessage | undefined;
+        while (Date.now() < deadline) {
+          await sleep(3000);
+          const msgs = await readAgentThread(token, agentUid, 10);
+          reply = msgs.find(
+            (m) => m.direction === "in" && m.createdAt > lastBeforeAt,
+          );
+          if (reply) break;
+        }
+
+        if (opts.json) {
+          process.stdout.write(
+            JSON.stringify({ agentUid, sent: message, reply: reply ?? null }, null, 2) + "\n",
+          );
+          return;
+        }
+        if (reply) {
+          console.log(formatThreadMessage(reply, agent));
+        } else {
+          console.log(
+            chalk.yellow(
+              `No reply within ${Math.round(timeoutMs / 1000)}s. The agent may still respond — ` +
+                `check with: hq agents thread ${agent}`,
+            ),
+          );
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
+  agents
+    .command("thread <agent>")
+    .alias("history")
+    .description("Show your recent conversation with an agent")
+    .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+    .option("--limit <n>", "How many recent messages to show", "20")
+    .option("--json", "Emit raw JSON")
+    .action(async function (
+      this: Command,
+      agent: string,
+      opts: { company?: string; limit?: string; json?: boolean },
+    ) {
+      try {
+        const token = await ensureCognitoToken();
+        const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+        const limit = Math.max(1, Number(opts.limit) || 20);
+        const msgs = await readAgentThread(token, agentUid, limit);
+        if (opts.json) {
+          process.stdout.write(JSON.stringify(msgs, null, 2) + "\n");
+          return;
+        }
+        if (msgs.length === 0) {
+          console.log(chalk.gray(`No conversation yet with ${agent}. Start one: hq agents message ${agent} "<text>"`));
+          return;
+        }
+        console.log(msgs.map((m) => formatThreadMessage(m, agent)).join("\n\n"));
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   agents
     .command("provision <name>")
     .alias("new")