@indigoai-us/hq-cli 5.74.0 → 5.75.0

package/dist/commands/outposts.d.ts

@@ -120,6 +120,8 @@ export interface OutpostExecSubmission {
     instanceId: string;
     commandId: string;
     outputPrefix: string;
+    /** Shell budget applied server-side (AWS-RunShellScript executionTimeout). */
+    executionTimeoutSeconds?: number;
 }
 /** Poll response from `mode: "result"`; streams arrive only when terminal. */
 export interface OutpostExecAsyncResult {
@@ -134,7 +136,7 @@ export interface OutpostExecAsyncResult {
     truncated?: boolean;
 }
 export declare function stageExecInput(token: string, outpostId?: string): Promise<OutpostExecStage>;
-export declare function submitExec(token: string, command: string, outpostId?: string): Promise<OutpostExecSubmission>;
+export declare function submitExec(token: string, command: string, outpostId?: string, timeoutSeconds?: number): Promise<OutpostExecSubmission>;
 export declare function fetchExecResult(token: string, commandId: string, outpostId?: string): Promise<OutpostExecAsyncResult>;
 /** Preserve a single command string; safely join argv when Commander split it. */
 export declare function joinCommandParts(commandParts: string[]): string;

package/dist/commands/outposts.js

@@ -162,12 +162,16 @@ export async function stageExecInput(token, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
-export async function submitExec(token, command, outpostId) {
+export async function submitExec(token, command, outpostId, timeoutSeconds) {
     return outpostRequest({
         token,
         path: "/outpost/exec",
         method: "POST",
-        body: { mode: "submit", command },
+        body: {
+            mode: "submit",
+            command,
+            ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+        },
         query: outpostId ? { outpostId } : undefined,
     });
 }
@@ -835,8 +839,18 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     });
     outposts
         .command("exec <command...>")
-        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)")
+        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). " +
+        "Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.")
         .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--async", "Submit via the async transport and wait for completion (bypasses the ~20s sync cap; shell budget defaults to 48h)")
+        .option("--detach", "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)")
+        .option("--timeout-seconds <n>", "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.", (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+            throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+    })
         .option("--json", "Emit raw JSON")
         .action(async function (commandParts, opts) {
         try {
@@ -845,9 +859,94 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
                 process.exit(1);
             }
+            if (opts.async && opts.detach) {
+                console.error(chalk.red("Use either --async (submit + wait) or --detach (submit only), not both."));
+                process.exit(1);
+            }
+            // --timeout-seconds only applies to the async path; bare use implies --async.
+            const useAsync = Boolean(opts.async) ||
+                Boolean(opts.detach) ||
+                opts.timeoutSeconds !== undefined;
+            if (opts.timeoutSeconds !== undefined) {
+                if (!Number.isInteger(opts.timeoutSeconds) ||
+                    opts.timeoutSeconds < 1 ||
+                    opts.timeoutSeconds > 172_800) {
+                    console.error(chalk.red("--timeout-seconds must be an integer between 1 and 172800 (48h, the AWS-RunShellScript max)"));
+                    process.exit(1);
+                }
+            }
             const token = await ensureCognitoToken();
             // Run from the box's HQ folder by default (works over both SSM and SSH).
             const remoteCommand = withRemoteHqDir(command);
+            if (useAsync) {
+                try {
+                    const submitted = await submitExec(token, remoteCommand, opts.id, opts.timeoutSeconds);
+                    if (opts.detach) {
+                        const output = {
+                            commandId: submitted.commandId,
+                            ...(submitted.executionTimeoutSeconds !== undefined
+                                ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                                : opts.timeoutSeconds !== undefined
+                                    ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                                    : {}),
+                        };
+                        if (opts.json) {
+                            process.stdout.write(JSON.stringify(output) + "\n");
+                        }
+                        else {
+                            printKeyValues(output);
+                            console.error(chalk.dim("Submitted. Poll with: hq outposts exec-result --command-id " +
+                                submitted.commandId +
+                                (opts.id ? ` --id ${opts.id}` : "") +
+                                " --wait"));
+                        }
+                        return;
+                    }
+                    // --async (or --timeout-seconds without --detach): wait for terminal.
+                    if (!opts.json) {
+                        console.error(chalk.dim(`Submitted ${submitted.commandId}; waiting for completion…`));
+                    }
+                    const result = await waitForExecResult(token, submitted.commandId, opts.id);
+                    if (opts.json) {
+                        process.stdout.write(JSON.stringify({
+                            commandId: submitted.commandId,
+                            done: result.done,
+                            status: result.status,
+                            exitCode: result.exitCode ?? null,
+                            stdout: result.stdout ?? "",
+                            stderr: result.stderr ?? "",
+                            truncated: result.truncated ?? false,
+                        }, null, 2) + "\n");
+                    }
+                    else {
+                        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 — 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})`));
+                        }
+                    }
+                    process.exitCode =
+                        typeof result.exitCode === "number" ? result.exitCode : 0;
+                    return;
+                }
+                catch (err) {
+                    // Async requires EC2/SSM. Lightsail has no async channel — refuse
+                    // rather than silently falling back to a live SSH hold, which is
+                    // the exact timeout failure mode --async is meant to escape.
+                    if (err instanceof OutpostHttpError &&
+                        err.step === "platform-unsupported") {
+                        console.error(chalk.red("Async exec requires an EC2 Outpost (SSM). This box is Lightsail — " +
+                            "re-provision on EC2, or run a short sync command / SSH session instead."));
+                        process.exit(1);
+                    }
+                    throw err;
+                }
+            }
             try {
                 const result = await execOutpost(token, remoteCommand, opts.id);
                 if (opts.json) {
@@ -940,8 +1039,15 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
     });
     outposts
         .command("exec-submit <command...>")
-        .description("Submit an asynchronous shell command to an Outpost")
+        .description("Submit an asynchronous shell command to an Outpost (returns immediately with commandId; shell budget defaults to 48h)")
         .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--timeout-seconds <n>", "Shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)", (v) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+            throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+    })
         .option("--json", "Emit raw JSON")
         .action(async function (commandParts, opts) {
         try {
@@ -950,9 +1056,27 @@ export function registerOutpostsCommand(program, selfDeployOverrides = {}) {
                 console.error(chalk.red("No command given. Usage: hq outposts exec-submit -- <command>"));
                 process.exit(1);
             }
+            if (opts.timeoutSeconds !== undefined) {
+                if (!Number.isInteger(opts.timeoutSeconds) ||
+                    opts.timeoutSeconds < 1 ||
+                    opts.timeoutSeconds > 172_800) {
+                    console.error(chalk.red("--timeout-seconds must be an integer between 1 and 172800 (48h)"));
+                    process.exit(1);
+                }
+            }
             const token = await ensureCognitoToken();
-            const submitted = await submitExec(token, command, opts.id);
-            const output = { commandId: submitted.commandId };
+            // exec-submit is the raw fire-and-forget path — do NOT wrap with
+            // withRemoteHqDir here (callers that want the HQ cwd use `exec --async`
+            // or prefix their own cd). Matches the existing contract.
+            const submitted = await submitExec(token, command, opts.id, opts.timeoutSeconds);
+            const output = {
+                commandId: submitted.commandId,
+                ...(submitted.executionTimeoutSeconds !== undefined
+                    ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                    : opts.timeoutSeconds !== undefined
+                        ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                        : {}),
+            };
             if (opts.json) {
                 process.stdout.write(JSON.stringify(output) + "\n");
             }

package/package.json

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

package/src/commands/outposts.test.ts

@@ -534,6 +534,140 @@ describe("hq outposts exec — Lightsail SSH fallback", () => {
   });
 });
 
+
+describe("hq outposts exec --async / --detach", () => {
+  afterEach(() => {
+    process.exitCode = undefined;
+  });
+
+  it("--detach submits with HQ-dir wrapper and prints commandId without waiting", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        ok: true,
+        userId: "u",
+        outpostId: "3",
+        instanceId: "i-3",
+        commandId: "cmd-detach",
+        outputPrefix: "outpost-exec/u/3/n/out",
+        executionTimeoutSeconds: 172800,
+      }),
+    );
+
+    await run(["outposts", "exec", "--detach", "--id", "3", "--json", "sleep", "999"]);
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/exec");
+    expect(String(url)).toContain("outpostId=3");
+    expect(JSON.parse(init?.body as string)).toEqual({
+      mode: "submit",
+      command: withRemoteHqDir("'sleep' '999'"),
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain('"commandId":"cmd-detach"');
+    // No second poll.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("--async submits then polls until done and streams stdout", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u",
+          outpostId: "primary",
+          instanceId: "i",
+          commandId: "cmd-async",
+          outputPrefix: "p",
+          executionTimeoutSeconds: 7200,
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, {
+          ok: true,
+          userId: "u",
+          outpostId: "primary",
+          status: "Success",
+          done: true,
+          exitCode: 0,
+          stdout: "finished\n",
+          stderr: "",
+        }),
+      );
+
+    await run([
+      "outposts",
+      "exec",
+      "--async",
+      "--timeout-seconds",
+      "7200",
+      "echo",
+      "finished",
+    ]);
+
+    // submit + one result poll (terminal on first poll)
+    expect(fetchSpy).toHaveBeenCalledTimes(2);
+    expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body as string)).toEqual({
+      mode: "submit",
+      command: withRemoteHqDir("'echo' 'finished'"),
+      timeoutSeconds: 7200,
+    });
+    expect(JSON.parse(fetchSpy.mock.calls[1][1]?.body as string)).toEqual({
+      mode: "result",
+      commandId: "cmd-async",
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain("finished\n");
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("refuses --async and --detach together", async () => {
+    await expect(
+      run(["outposts", "exec", "--async", "--detach", "true"]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+
+  it("exec-submit forwards --timeout-seconds", async () => {
+    const stdoutSpy = vi
+      .spyOn(process.stdout, "write")
+      .mockImplementation(() => true);
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, {
+        ok: true,
+        commandId: "cmd-sub",
+        executionTimeoutSeconds: 3600,
+        userId: "u",
+        outpostId: "primary",
+        instanceId: "i",
+        outputPrefix: "p",
+      }),
+    );
+    await run([
+      "outposts",
+      "exec-submit",
+      "--timeout-seconds",
+      "3600",
+      "--json",
+      "sleep",
+      "10",
+    ]);
+    expect(JSON.parse(fetchSpy.mock.calls[0][1]?.body as string)).toEqual({
+      mode: "submit",
+      command: "'sleep' '10'",
+      timeoutSeconds: 3600,
+    });
+    const printed = stdoutSpy.mock.calls.map((c) => String(c[0])).join("");
+    expect(printed).toContain("cmd-sub");
+  });
+});
+
 describe("hq outposts asynchronous exec", () => {
   it("sends the stage, submit, and result mode request bodies", async () => {
     fetchSpy

package/src/commands/outposts.ts

@@ -268,6 +268,8 @@ export interface OutpostExecSubmission {
   instanceId: string;
   commandId: string;
   outputPrefix: string;
+  /** Shell budget applied server-side (AWS-RunShellScript executionTimeout). */
+  executionTimeoutSeconds?: number;
 }
 
 /** Poll response from `mode: "result"`; streams arrive only when terminal. */
@@ -300,12 +302,17 @@ export async function submitExec(
   token: string,
   command: string,
   outpostId?: string,
+  timeoutSeconds?: number,
 ): Promise<OutpostExecSubmission> {
   return outpostRequest({
     token,
     path: "/outpost/exec",
     method: "POST",
-    body: { mode: "submit", command },
+    body: {
+      mode: "submit",
+      command,
+      ...(timeoutSeconds !== undefined ? { timeoutSeconds } : {}),
+    },
     query: outpostId ? { outpostId } : undefined,
   });
 }
@@ -1250,14 +1257,40 @@ export function registerOutpostsCommand(
   outposts
     .command("exec <command...>")
     .description(
-      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)",
+      "Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command). " +
+        "Default is synchronous (API Gateway ~20s cap). Use --async for long jobs, or --detach to print the commandId and return immediately.",
     )
     .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option(
+      "--async",
+      "Submit via the async transport and wait for completion (bypasses the ~20s sync cap; shell budget defaults to 48h)",
+    )
+    .option(
+      "--detach",
+      "Submit via the async transport, print commandId, and return immediately (pair with `hq outposts exec-result --wait`)",
+    )
+    .option(
+      "--timeout-seconds <n>",
+      "Async shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800). Implies --async unless --detach is set.",
+      (v: string) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+          throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+      },
+    )
     .option("--json", "Emit raw JSON")
     .action(async function (
       this: Command,
       commandParts: string[],
-      opts: { id?: string; json?: boolean },
+      opts: {
+        id?: string;
+        json?: boolean;
+        async?: boolean;
+        detach?: boolean;
+        timeoutSeconds?: number;
+      },
     ) {
       try {
         const command = joinCommandParts(commandParts);
@@ -1265,11 +1298,137 @@ export function registerOutpostsCommand(
           console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
           process.exit(1);
         }
+        if (opts.async && opts.detach) {
+          console.error(
+            chalk.red("Use either --async (submit + wait) or --detach (submit only), not both."),
+          );
+          process.exit(1);
+        }
+        // --timeout-seconds only applies to the async path; bare use implies --async.
+        const useAsync =
+          Boolean(opts.async) ||
+          Boolean(opts.detach) ||
+          opts.timeoutSeconds !== undefined;
+        if (opts.timeoutSeconds !== undefined) {
+          if (
+            !Number.isInteger(opts.timeoutSeconds) ||
+            opts.timeoutSeconds < 1 ||
+            opts.timeoutSeconds > 172_800
+          ) {
+            console.error(
+              chalk.red(
+                "--timeout-seconds must be an integer between 1 and 172800 (48h, the AWS-RunShellScript max)",
+              ),
+            );
+            process.exit(1);
+          }
+        }
         const token = await ensureCognitoToken();
 
         // Run from the box's HQ folder by default (works over both SSM and SSH).
         const remoteCommand = withRemoteHqDir(command);
 
+        if (useAsync) {
+          try {
+            const submitted = await submitExec(
+              token,
+              remoteCommand,
+              opts.id,
+              opts.timeoutSeconds,
+            );
+            if (opts.detach) {
+              const output = {
+                commandId: submitted.commandId,
+                ...(submitted.executionTimeoutSeconds !== undefined
+                  ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+                  : opts.timeoutSeconds !== undefined
+                    ? { executionTimeoutSeconds: opts.timeoutSeconds }
+                    : {}),
+              };
+              if (opts.json) {
+                process.stdout.write(JSON.stringify(output) + "\n");
+              } else {
+                printKeyValues(output);
+                console.error(
+                  chalk.dim(
+                    "Submitted. Poll with: hq outposts exec-result --command-id " +
+                      submitted.commandId +
+                      (opts.id ? ` --id ${opts.id}` : "") +
+                      " --wait",
+                  ),
+                );
+              }
+              return;
+            }
+
+            // --async (or --timeout-seconds without --detach): wait for terminal.
+            if (!opts.json) {
+              console.error(
+                chalk.dim(
+                  `Submitted ${submitted.commandId}; waiting for completion…`,
+                ),
+              );
+            }
+            const result = await waitForExecResult(
+              token,
+              submitted.commandId,
+              opts.id,
+            );
+            if (opts.json) {
+              process.stdout.write(
+                JSON.stringify(
+                  {
+                    commandId: submitted.commandId,
+                    done: result.done,
+                    status: result.status,
+                    exitCode: result.exitCode ?? null,
+                    stdout: result.stdout ?? "",
+                    stderr: result.stderr ?? "",
+                    truncated: result.truncated ?? false,
+                  },
+                  null,
+                  2,
+                ) + "\n",
+              );
+            } else {
+              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 — 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})`),
+                );
+              }
+            }
+            process.exitCode =
+              typeof result.exitCode === "number" ? result.exitCode : 0;
+            return;
+          } catch (err) {
+            // Async requires EC2/SSM. Lightsail has no async channel — refuse
+            // rather than silently falling back to a live SSH hold, which is
+            // the exact timeout failure mode --async is meant to escape.
+            if (
+              err instanceof OutpostHttpError &&
+              err.step === "platform-unsupported"
+            ) {
+              console.error(
+                chalk.red(
+                  "Async exec requires an EC2 Outpost (SSM). This box is Lightsail — " +
+                    "re-provision on EC2, or run a short sync command / SSH session instead.",
+                ),
+              );
+              process.exit(1);
+            }
+            throw err;
+          }
+        }
+
         try {
           const result = await execOutpost(token, remoteCommand, opts.id);
           if (opts.json) {
@@ -1369,13 +1528,26 @@ export function registerOutpostsCommand(
 
   outposts
     .command("exec-submit <command...>")
-    .description("Submit an asynchronous shell command to an Outpost")
+    .description(
+      "Submit an asynchronous shell command to an Outpost (returns immediately with commandId; shell budget defaults to 48h)",
+    )
     .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+    .option(
+      "--timeout-seconds <n>",
+      "Shell budget in seconds (AWS-RunShellScript executionTimeout; 1..172800)",
+      (v: string) => {
+        const n = Number(v);
+        if (!Number.isInteger(n)) {
+          throw new Error("--timeout-seconds must be an integer");
+        }
+        return n;
+      },
+    )
     .option("--json", "Emit raw JSON")
     .action(async function (
       this: Command,
       commandParts: string[],
-      opts: { id?: string; json?: boolean },
+      opts: { id?: string; json?: boolean; timeoutSeconds?: number },
     ) {
       try {
         const command = joinCommandParts(commandParts);
@@ -1385,9 +1557,38 @@ export function registerOutpostsCommand(
           );
           process.exit(1);
         }
+        if (opts.timeoutSeconds !== undefined) {
+          if (
+            !Number.isInteger(opts.timeoutSeconds) ||
+            opts.timeoutSeconds < 1 ||
+            opts.timeoutSeconds > 172_800
+          ) {
+            console.error(
+              chalk.red(
+                "--timeout-seconds must be an integer between 1 and 172800 (48h)",
+              ),
+            );
+            process.exit(1);
+          }
+        }
         const token = await ensureCognitoToken();
-        const submitted = await submitExec(token, command, opts.id);
-        const output = { commandId: submitted.commandId };
+        // exec-submit is the raw fire-and-forget path — do NOT wrap with
+        // withRemoteHqDir here (callers that want the HQ cwd use `exec --async`
+        // or prefix their own cd). Matches the existing contract.
+        const submitted = await submitExec(
+          token,
+          command,
+          opts.id,
+          opts.timeoutSeconds,
+        );
+        const output = {
+          commandId: submitted.commandId,
+          ...(submitted.executionTimeoutSeconds !== undefined
+            ? { executionTimeoutSeconds: submitted.executionTimeoutSeconds }
+            : opts.timeoutSeconds !== undefined
+              ? { executionTimeoutSeconds: opts.timeoutSeconds }
+              : {}),
+        };
         if (opts.json) {
           process.stdout.write(JSON.stringify(output) + "\n");
         } else {