@indigoai-us/hq-cli 5.65.0 → 5.67.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/dist/commands/outposts.d.ts

@@ -94,5 +94,34 @@ export interface OutpostExecResult {
  * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
  */
 export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
+/** SSH connection details vended by `POST /outpost/ssh-access`. */
+export interface OutpostSshAccess {
+    outpostId: string;
+    platform: "ec2" | "lightsail";
+    host: string;
+    port: number;
+    username: string;
+    /** PEM private key for the box. SENSITIVE — never printed or logged. */
+    privateKey: string;
+}
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export declare function getOutpostSshAccess(token: string, outpostId?: string): Promise<OutpostSshAccess>;
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export declare function execViaSsh(access: OutpostSshAccess, command: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    error?: string;
+};
 export declare function registerOutpostsCommand(program: Command): void;
 //# sourceMappingURL=outposts.d.ts.map

package/dist/commands/outposts.js

@@ -21,8 +21,13 @@
  * and status routes that exist. Renaming an Outpost is not a backend capability.
  */
 
-!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]="067e20d6-0132-565a-8a22-9c27520669d2")}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]="951a0bc6-7dc3-5b10-b8f6-728df1074817")}catch(e){}}();
 import chalk from "chalk";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -133,6 +138,72 @@ export async function execOutpost(token, command, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export async function getOutpostSshAccess(token, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/ssh-access",
+        method: "POST",
+        body: {},
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export function execViaSsh(access, command) {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-outpost-ssh-"));
+    const keyPath = path.join(dir, `id_${randomBytes(6).toString("hex")}`);
+    const knownHosts = path.join(dir, "known_hosts");
+    try {
+        fs.writeFileSync(keyPath, ensureTrailingNewline(access.privateKey), {
+            mode: 0o600,
+        });
+        const result = spawnSync("ssh", [
+            "-i",
+            keyPath,
+            "-p",
+            String(access.port),
+            "-o",
+            "BatchMode=yes",
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            `UserKnownHostsFile=${knownHosts}`,
+            "-o",
+            "ConnectTimeout=15",
+            "-o",
+            "LogLevel=ERROR",
+            `${access.username}@${access.host}`,
+            command,
+        ], { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 });
+        if (result.error) {
+            const hint = result.error.code === "ENOENT"
+                ? "the `ssh` client is not installed or not on PATH"
+                : result.error.message;
+            return { stdout: "", stderr: "", exitCode: null, error: hint };
+        }
+        return {
+            stdout: result.stdout ?? "",
+            stderr: result.stderr ?? "",
+            exitCode: result.status,
+        };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : s + "\n";
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -294,27 +365,60 @@ export function registerOutpostsCommand(program) {
                 process.exit(1);
             }
             const token = await ensureCognitoToken();
-            const result = await execOutpost(token, command, opts.id);
-            if (opts.json) {
-                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-            }
-            else {
-                // Stream the remote streams to ours so the command feels local, then
-                // exit with the remote exit code.
-                if (result.stdout)
-                    process.stdout.write(result.stdout);
-                if (result.stderr)
-                    process.stderr.write(result.stderr);
-                if (result.truncated) {
-                    console.error(chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"));
+            try {
+                const result = await execOutpost(token, command, opts.id);
+                if (opts.json) {
+                    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+                }
+                else {
+                    // Stream the remote streams to ours so the command feels local.
+                    if (result.stdout)
+                        process.stdout.write(result.stdout);
+                    if (result.stderr)
+                        process.stderr.write(result.stderr);
+                    if (result.truncated) {
+                        console.error(chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"));
+                    }
+                    if (result.status !== "Success" && result.exitCode === null) {
+                        console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+                    }
                 }
-                if (result.status !== "Success" && result.exitCode === null) {
-                    console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+                // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
+                process.exitCode =
+                    typeof result.exitCode === "number" ? result.exitCode : 0;
+            }
+            catch (err) {
+                // Lightsail boxes have no SSM agent — transparently fall back to SSH.
+                if (err instanceof OutpostHttpError &&
+                    err.step === "platform-unsupported") {
+                    const access = await getOutpostSshAccess(token, opts.id);
+                    const ssh = execViaSsh(access, command);
+                    if (ssh.error) {
+                        console.error(chalk.red(`Could not run the command over SSH: ${ssh.error}`));
+                        process.exit(1);
+                    }
+                    if (opts.json) {
+                        process.stdout.write(JSON.stringify({
+                            via: "ssh",
+                            platform: access.platform,
+                            host: access.host,
+                            exitCode: ssh.exitCode,
+                            stdout: ssh.stdout,
+                            stderr: ssh.stderr,
+                        }, null, 2) + "\n");
+                    }
+                    else {
+                        if (ssh.stdout)
+                            process.stdout.write(ssh.stdout);
+                        if (ssh.stderr)
+                            process.stderr.write(ssh.stderr);
+                    }
+                    process.exitCode =
+                        typeof ssh.exitCode === "number" ? ssh.exitCode : 1;
+                    return;
                 }
+                throw err;
             }
-            // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
-            process.exitCode =
-                typeof result.exitCode === "number" ? result.exitCode : 0;
         }
         catch (err) {
             fail(err);
@@ -392,4 +496,4 @@ export function registerOutpostsCommand(program) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=067e20d6-0132-565a-8a22-9c27520669d2
+//# debugId=951a0bc6-7dc3-5b10-b8f6-728df1074817

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.65.0",
+  "version": "5.67.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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")

package/src/commands/outposts.test.ts

@@ -42,9 +42,20 @@ vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
   };
 });
 
+// The SSH fallback shells out to `ssh` via spawnSync — stub it so tests don't
+// touch a real box or need the ssh binary.
+vi.mock("node:child_process", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("node:child_process")>();
+  return { ...original, spawnSync: vi.fn() };
+});
+
+import { spawnSync } from "node:child_process";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { registerOutpostsCommand } from "./outposts.js";
 
+const mockSpawnSync = vi.mocked(spawnSync);
+
 function jsonResponse(status: number, body: unknown): Response {
   return new Response(JSON.stringify(body), {
     status,
@@ -354,3 +365,112 @@ describe("hq outposts exec", () => {
     expect(printed).toContain('"commandId": "cmd-3"');
   });
 });
+
+describe("hq outposts exec — Lightsail SSH fallback", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  function platformUnsupported(): Response {
+    return jsonResponse(409, {
+      error: true,
+      step: "platform-unsupported",
+      message: "remote exec requires the EC2 platform",
+    });
+  }
+
+  function sshAccess(): Response {
+    return jsonResponse(200, {
+      ok: true,
+      outpostId: "primary",
+      platform: "lightsail",
+      host: "52.2.2.2",
+      port: 22,
+      username: "ec2-user",
+      privateKey: "-----BEGIN KEY-----\nx\n-----END KEY-----\n",
+    });
+  }
+
+  it("falls back to SSH when the box is Lightsail, streams stdout, propagates exit", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy
+      .mockResolvedValueOnce(platformUnsupported()) // /outpost/exec (SSM) → 409
+      .mockResolvedValueOnce(sshAccess()); // /outpost/ssh-access → 200
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: "lightsail-out\n",
+      stderr: "",
+      signal: null,
+      output: [],
+      pid: 1,
+    } as unknown as ReturnType<typeof spawnSync>);
+
+    // Flags meant for the remote command go after `--` (same as the SSM path).
+    await run(["outposts", "exec", "--", "uname", "-a"]);
+
+    // Second HTTP call is the ssh-access mint.
+    expect(String(fetchSpy.mock.calls[1][0])).toContain("/outpost/ssh-access");
+    // ssh was invoked with the box coordinates and the command as the last arg.
+    const args = mockSpawnSync.mock.calls[0][1] as string[];
+    expect(mockSpawnSync.mock.calls[0][0]).toBe("ssh");
+    expect(args).toContain("ec2-user@52.2.2.2");
+    expect(args[args.length - 1]).toBe("uname -a");
+    expect(args).toContain("BatchMode=yes");
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain("lightsail-out\n");
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("propagates a non-zero SSH exit code", async () => {
+    vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    fetchSpy
+      .mockResolvedValueOnce(platformUnsupported())
+      .mockResolvedValueOnce(sshAccess());
+    mockSpawnSync.mockReturnValue({
+      status: 7,
+      stdout: "",
+      stderr: "boom\n",
+      signal: null,
+      output: [],
+      pid: 1,
+    } as unknown as ReturnType<typeof spawnSync>);
+    await run(["outposts", "exec", "false"]);
+    expect(process.exitCode).toBe(7);
+  });
+
+  it("exits 1 with a clear message when the ssh client is missing", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(platformUnsupported())
+      .mockResolvedValueOnce(sshAccess());
+    const enoent = Object.assign(new Error("spawnSync ssh ENOENT"), {
+      code: "ENOENT",
+    });
+    mockSpawnSync.mockReturnValue({
+      error: enoent,
+      status: null,
+      stdout: "",
+      stderr: "",
+      signal: null,
+      output: [],
+      pid: 0,
+    } as unknown as ReturnType<typeof spawnSync>);
+    await expect(run(["outposts", "exec", "echo", "hi"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+  });
+
+  it("does NOT fall back for a non-platform error (e.g. not-ready)", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(409, { error: true, step: "not-ready", message: "not ready" }),
+    );
+    await expect(
+      run(["outposts", "exec", "echo", "hi"]),
+    ).rejects.toThrow("process.exit(1)");
+    // Only the SSM call happened; no ssh-access mint, no ssh.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+  });
+});

package/src/commands/outposts.ts

@@ -23,6 +23,11 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { randomBytes } from "node:crypto";
 import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
@@ -222,6 +227,96 @@ export async function execOutpost(
   });
 }
 
+/** SSH connection details vended by `POST /outpost/ssh-access`. */
+export interface OutpostSshAccess {
+  outpostId: string;
+  platform: "ec2" | "lightsail";
+  host: string;
+  port: number;
+  username: string;
+  /** PEM private key for the box. SENSITIVE — never printed or logged. */
+  privateKey: string;
+}
+
+/**
+ * Fetch SSH connection info + key for the caller's Outpost and open the caller's
+ * IP on the box's SSH port. Used to reach a Lightsail box (no SSM). Throws
+ * `OutpostHttpError` on a non-2xx.
+ */
+export async function getOutpostSshAccess(
+  token: string,
+  outpostId?: string,
+): Promise<OutpostSshAccess> {
+  return outpostRequest({
+    token,
+    path: "/outpost/ssh-access",
+    method: "POST",
+    body: {},
+    query: outpostId ? { outpostId } : undefined,
+  });
+}
+
+/**
+ * Run `command` on the box over SSH using vended access details. Writes the
+ * private key to a locked-down temp file, runs a non-interactive `ssh`, and
+ * returns stdout/stderr/exitCode. The key file + a throwaway known_hosts file
+ * are always cleaned up; the key is never printed. `exitCode` is `null` only
+ * when `ssh` itself couldn't run (e.g. binary missing) — surfaced via `error`.
+ */
+export function execViaSsh(
+  access: OutpostSshAccess,
+  command: string,
+): { stdout: string; stderr: string; exitCode: number | null; error?: string } {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-outpost-ssh-"));
+  const keyPath = path.join(dir, `id_${randomBytes(6).toString("hex")}`);
+  const knownHosts = path.join(dir, "known_hosts");
+  try {
+    fs.writeFileSync(keyPath, ensureTrailingNewline(access.privateKey), {
+      mode: 0o600,
+    });
+    const result = spawnSync(
+      "ssh",
+      [
+        "-i",
+        keyPath,
+        "-p",
+        String(access.port),
+        "-o",
+        "BatchMode=yes",
+        "-o",
+        "StrictHostKeyChecking=accept-new",
+        "-o",
+        `UserKnownHostsFile=${knownHosts}`,
+        "-o",
+        "ConnectTimeout=15",
+        "-o",
+        "LogLevel=ERROR",
+        `${access.username}@${access.host}`,
+        command,
+      ],
+      { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
+    );
+    if (result.error) {
+      const hint =
+        (result.error as NodeJS.ErrnoException).code === "ENOENT"
+          ? "the `ssh` client is not installed or not on PATH"
+          : result.error.message;
+      return { stdout: "", stderr: "", exitCode: null, error: hint };
+    }
+    return {
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+      exitCode: result.status,
+    };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function ensureTrailingNewline(s: string): string {
+  return s.endsWith("\n") ? s : s + "\n";
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -423,27 +518,64 @@ export function registerOutpostsCommand(program: Command): void {
           process.exit(1);
         }
         const token = await ensureCognitoToken();
-        const result = await execOutpost(token, command, opts.id);
 
-        if (opts.json) {
-          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-        } else {
-          // Stream the remote streams to ours so the command feels local, then
-          // exit with the remote exit code.
-          if (result.stdout) process.stdout.write(result.stdout);
-          if (result.stderr) process.stderr.write(result.stderr);
-          if (result.truncated) {
-            console.error(
-              chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"),
-            );
+        try {
+          const result = await execOutpost(token, command, opts.id);
+          if (opts.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+          } else {
+            // Stream the remote streams to ours so the command feels local.
+            if (result.stdout) process.stdout.write(result.stdout);
+            if (result.stderr) process.stderr.write(result.stderr);
+            if (result.truncated) {
+              console.error(
+                chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"),
+              );
+            }
+            if (result.status !== "Success" && result.exitCode === null) {
+              console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+            }
           }
-          if (result.status !== "Success" && result.exitCode === null) {
-            console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+          // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
+          process.exitCode =
+            typeof result.exitCode === "number" ? result.exitCode : 0;
+        } catch (err) {
+          // Lightsail boxes have no SSM agent — transparently fall back to SSH.
+          if (
+            err instanceof OutpostHttpError &&
+            err.step === "platform-unsupported"
+          ) {
+            const access = await getOutpostSshAccess(token, opts.id);
+            const ssh = execViaSsh(access, command);
+            if (ssh.error) {
+              console.error(chalk.red(`Could not run the command over SSH: ${ssh.error}`));
+              process.exit(1);
+            }
+            if (opts.json) {
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    via: "ssh",
+                    platform: access.platform,
+                    host: access.host,
+                    exitCode: ssh.exitCode,
+                    stdout: ssh.stdout,
+                    stderr: ssh.stderr,
+                  },
+                  null,
+                  2,
+                ) + "\n",
+              );
+            } else {
+              if (ssh.stdout) process.stdout.write(ssh.stdout);
+              if (ssh.stderr) process.stderr.write(ssh.stderr);
+            }
+            process.exitCode =
+              typeof ssh.exitCode === "number" ? ssh.exitCode : 1;
+            return;
           }
+          throw err;
         }
-        // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
-        process.exitCode =
-          typeof result.exitCode === "number" ? result.exitCode : 0;
       } catch (err) {
         fail(err);
       }