@indigoai-us/hq-cli 5.103.34 → 5.104.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## [Unreleased]
 
+## [5.104.0] — 2026-08-31
+
+### Added
+
+- `hq agents terminal <agent>` — open an interactive terminal (real TTY over
+  SSM Session Manager) on a fleet agent's box using HQ identity alone: no SSH,
+  no local AWS credentials. Owner/admin only; auto-starts a dormant box and
+  waits for it to come online. `--forward <port>` (with optional
+  `--local-port`) tunnels a port on the box to your machine instead of opening
+  a shell. Requires the AWS `session-manager-plugin` installed locally.
+- `hq outposts terminal` — the same interactive terminal for personal
+  Outposts (via `@indigoai-us/hq-cloud`).
+
 ## [5.103.34] — 2026-08-30
 
 ## [5.103.33] — 2026-08-30

package/dist/commands/agents.d.ts

@@ -25,6 +25,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 import { Command } from "commander";
+import { type TerminalSessionPayload } from "@indigoai-us/hq-cloud/outposts/node";
 import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export declare const VALID_EFFORTS: Set<string>;
@@ -201,6 +202,19 @@ export declare function startStopAgent(token: string, agentUid: string, action:
     uid: string;
     runtime?: Record<string, unknown>;
 }>;
+/** `POST /v1/agents/{uid}/terminal` wire shape: vended session or 202 starting. */
+export type AgentTerminalResponse = ({
+    ok: true;
+    uid: string;
+    mode: "shell" | "port-forward";
+} & TerminalSessionPayload) | {
+    ok: false;
+    step: "starting";
+    state: "starting-instance" | "awaiting-ssm";
+    retryAfterSeconds?: number;
+    uid: string;
+};
+export declare function openAgentTerminal(token: string, agentUid: string, body: Record<string, unknown>): Promise<AgentTerminalResponse>;
 export declare function retryAgent(token: string, agentUid: string): Promise<Record<string, unknown>>;
 export declare function deprovisionAgent(token: string, agentUid: string): Promise<{
     uid: string;

package/dist/commands/agents.js

@@ -30,6 +30,7 @@ import * as readline from "node:readline";
 import { resolveVaultCredential } from "../utils/resolve-vault-credential.js";
 import { gateApiKeyCapabilities } from "../utils/api-key-command-gate.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { launchSessionManagerPlugin, SessionManagerPluginLaunchError, TerminalSessionTimeoutError, waitForTerminalSession, } from "@indigoai-us/hq-cloud/outposts/node";
 import { peekIdToken } from "../utils/id-token.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
@@ -299,6 +300,14 @@ export async function startStopAgent(token, agentUid, action) {
         method: "POST",
     });
 }
+export async function openAgentTerminal(token, agentUid, body) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/terminal`,
+        method: "POST",
+        body,
+    });
+}
 export async function retryAgent(token, agentUid) {
     return agentsRequest({
         token,
@@ -540,6 +549,17 @@ function sleep(ms) {
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
+/** Parse an optional port flag: integer 1..65535 or exit(1) with the flag name. */
+function parsePortOption(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isInteger(n) || n < 1 || n > 65_535) {
+        console.error(chalk.red(`${flag} must be an integer between 1 and 65535.`));
+        process.exit(1);
+    }
+    return n;
+}
 function fail(err) {
     // Let the CLI boundary render and offer the one shared Team checkout flow.
     // Local exits would otherwise prevent interactive plan-limit remediation.
@@ -578,6 +598,9 @@ export function registerAgentsCommand(program) {
         bySubcommand: {
             message: { capability: "agents:use", routeAvailable: false },
             thread: { capability: "agents:use", routeAvailable: false },
+            // Interactive terminals are for humans: hq-pro serves no keyed
+            // `/v1/keys/agents/{uid}/terminal` route, so machine keys fail closed.
+            terminal: { capability: "agents:use", routeAvailable: false },
         },
     });
     // `--company` may live on the group or the subcommand; the subcommand value
@@ -667,6 +690,74 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    agents
+        .command("terminal <agent>")
+        .description("Open an interactive terminal on an agent's box — a real TTY over SSM Session Manager (no SSH, no local AWS credentials). " +
+        "Owner/admin only; requires the AWS session-manager-plugin installed locally. With --forward, tunnels a port on the box instead.")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .option("--forward <port>", "Forward this port on the box to your machine instead of opening a shell")
+        .option("--local-port <port>", "Local port for --forward (defaults to the forwarded port)")
+        .action(async function (agent, opts) {
+        try {
+            const forwardPort = parsePortOption(opts.forward, "--forward");
+            const localPort = parsePortOption(opts.localPort, "--local-port");
+            if (localPort !== undefined && forwardPort === undefined) {
+                console.error(chalk.red("--local-port requires --forward <port>."));
+                process.exit(1);
+            }
+            // A shell needs a real TTY on both ends; a port-forward does not.
+            if (forwardPort === undefined && !process.stdin.isTTY) {
+                console.error(chalk.red("hq agents terminal needs an interactive terminal (stdin is not a TTY)."));
+                process.exit(1);
+            }
+            const token = (await resolveVaultCredential()).token;
+            const agentUid = await resolveAgentUid(token, agent, companyOf(this));
+            const body = forwardPort !== undefined
+                ? {
+                    mode: "port-forward",
+                    portNumber: forwardPort,
+                    ...(localPort !== undefined ? { localPortNumber: localPort } : {}),
+                }
+                : { mode: "shell" };
+            // 202-retry loop: a dormant box is auto-started server-side; SSM
+            // registration after a cold start takes ~30-90s. Status lines go to
+            // stderr (once per state) so stdout stays the session's.
+            let lastState;
+            const session = await waitForTerminalSession(async () => {
+                const result = await openAgentTerminal(token, agentUid, body);
+                if (result.ok)
+                    return { kind: "ready", session: result };
+                return {
+                    kind: "starting",
+                    state: result.state,
+                    ...(result.retryAfterSeconds !== undefined
+                        ? { retryAfterSeconds: result.retryAfterSeconds }
+                        : {}),
+                };
+            }, {
+                onStatus: (state) => {
+                    if (state === lastState)
+                        return;
+                    lastState = state;
+                    console.error(chalk.dim(state === "starting-instance"
+                        ? `${agent}'s box is starting — waiting for it to come online (Ctrl-C to cancel)…`
+                        : `${agent}'s box is up — waiting for its agent to register (Ctrl-C to cancel)…`));
+                },
+            });
+            console.error(chalk.dim(forwardPort !== undefined
+                ? `Forwarding box port ${forwardPort} to localhost:${localPort ?? forwardPort} — Ctrl-C to end.`
+                : `Connected to ${agent}'s box — type 'exit' or Ctrl-D to leave.`));
+            process.exitCode = await launchSessionManagerPlugin(session);
+        }
+        catch (err) {
+            if (err instanceof SessionManagerPluginLaunchError ||
+                err instanceof TerminalSessionTimeoutError) {
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+            fail(err);
+        }
+    });
     agents
         .command("provision <name>")
         .alias("new")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.34",
+  "version": "5.104.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -30,7 +30,7 @@
   "dependencies": {
     "@aws-sdk/client-iot-data-plane": "^3.1096.0",
     "@aws-sdk/client-s3": "^3.1049.0",
-    "@indigoai-us/hq-cloud": "~6.15.95",
+    "@indigoai-us/hq-cloud": "~6.16.0",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",