@indigoai-us/hq-cli 5.62.1 → 5.63.0

package/src/commands/members.ts

@@ -5,7 +5,13 @@ import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
 
 const EMAIL_PATTERN = /^[^\s]+@[^\s]+$/;
 const PERSON_UID_PATTERN = /^prs_[A-Za-z0-9_-]+$/;
+const AGENT_UID_PATTERN = /^agt_[A-Za-z0-9_-]+$/i;
+/** Fleet agent machine email: agt-…@agents.getindigo.ai */
+const AGENT_EMAIL_PATTERN =
+  /^agt-[a-z0-9]+@agents\.getindigo\.ai$/i;
 export const VALID_ROLES = new Set(["owner", "admin", "member", "guest"]);
+/** Roles allowed when inviting an existing fleet agent into a company. */
+export const AGENT_INVITE_ROLES = new Set(["admin", "member"]);
 
 export type Role = "owner" | "admin" | "member" | "guest";
 
@@ -100,6 +106,13 @@ export interface InviteResult {
   emailSkipped?: boolean;
   /** Resend was attempted but failed — human-readable reason. */
   emailError?: string;
+  /**
+   * Present when hq-pro treated the target as a fleet agent (guest invite).
+   * Always `false` on the agent path — host keeps billing.
+   */
+  activationBilled?: boolean;
+  /** Host company uid when the server returned an agent guest-invite result. */
+  hostCompanyUid?: string;
 }
 
 export interface ResendInviteOptions {
@@ -122,16 +135,29 @@ export interface ResendInviteResult {
 }
 
 export interface DetectedTarget {
-  type: "email" | "person";
+  type: "email" | "person" | "agent";
   value: string;
+  /** True when the target is a fleet agent (uid or machine email). */
+  isAgent?: boolean;
 }
 
 export function detectTarget(target: string): DetectedTarget | null {
-  if (EMAIL_PATTERN.test(target)) {
-    return { type: "email", value: target.trim().toLowerCase() };
+  const trimmed = target.trim();
+  if (AGENT_UID_PATTERN.test(trimmed)) {
+    return { type: "agent", value: trimmed, isAgent: true };
+  }
+  if (AGENT_EMAIL_PATTERN.test(trimmed)) {
+    return {
+      type: "email",
+      value: trimmed.toLowerCase(),
+      isAgent: true,
+    };
   }
-  if (PERSON_UID_PATTERN.test(target)) {
-    return { type: "person", value: target };
+  if (EMAIL_PATTERN.test(trimmed)) {
+    return { type: "email", value: trimmed.toLowerCase() };
+  }
+  if (PERSON_UID_PATTERN.test(trimmed)) {
+    return { type: "person", value: trimmed };
   }
   return null;
 }
@@ -180,11 +206,35 @@ export async function inviteMember(
   const detected = detectTarget(options.target);
   if (!detected) {
     throw new Error(
-      `Invalid target '${options.target}': must be an email address or a personUid matching prs_<alphanumeric>`,
+      `Invalid target '${options.target}': must be an email, personUid (prs_…), agent uid (agt_…), or agent email (agt-…@agents.getindigo.ai)`,
     );
   }
 
-  if (options.groupIds && options.groupIds.length > 0 && detected.type === "person") {
+  // Fleet agents: same invite command as humans, but only member|admin.
+  // Host company keeps billing — server never double-bills on guest invite.
+  if (detected.isAgent) {
+    if (!AGENT_INVITE_ROLES.has(options.role)) {
+      throw new Error(
+        `Agents can only be invited as member or admin (got '${options.role}'). Host company keeps billing.`,
+      );
+    }
+    if (options.paths) {
+      throw new Error(
+        "--paths / guest role is not valid for agents — invite as member or admin",
+      );
+    }
+    if (options.groupIds && options.groupIds.length > 0) {
+      throw new Error(
+        "--groups is not supported on agent invites — share secrets after membership with `hq secrets share`",
+      );
+    }
+  }
+
+  if (
+    options.groupIds &&
+    options.groupIds.length > 0 &&
+    (detected.type === "person" || detected.type === "agent")
+  ) {
     throw new Error(
       "--groups is only valid on email-keyed invites (server rejects personUid + groupIds with 400)",
     );
@@ -236,6 +286,8 @@ export async function inviteMember(
     emailSent?: boolean;
     emailSkipped?: boolean;
     emailError?: string;
+    activationBilled?: boolean;
+    hostCompanyUid?: string;
   };
   if (!data.membership) {
     const keys = Object.keys(data ?? {}).join(", ") || "<empty>";
@@ -267,6 +319,12 @@ export async function inviteMember(
       ? { emailSkipped: data.emailSkipped }
       : {}),
     ...(data.emailError ? { emailError: data.emailError } : {}),
+    ...(typeof data.activationBilled === "boolean"
+      ? { activationBilled: data.activationBilled }
+      : {}),
+    ...(typeof data.hostCompanyUid === "string"
+      ? { hostCompanyUid: data.hostCompanyUid }
+      : {}),
   };
 }
 
@@ -436,9 +494,16 @@ export function resolveRevokeTargetToMembershipKey(
   if (arg.includes("#")) return arg;
   const detected = detectTarget(arg);
   if (detected?.type === "email") {
+    // Active agent guest memberships are personUid-keyed (agt_…#cmp_…), not
+    // email-keyed. Map machine emails to that key so revoke works after invite.
+    if (detected.isAgent) {
+      const local = detected.value.split("@")[0] ?? "";
+      const m = local.match(/^agt-(.+)$/i);
+      if (m) return `agt_${m[1].toUpperCase()}#${companyUid}`;
+    }
     return `email:${detected.value}#${companyUid}`;
   }
-  if (detected?.type === "person") {
+  if (detected?.type === "person" || detected?.type === "agent") {
     return `${detected.value}#${companyUid}`;
   }
   return arg;
@@ -604,11 +669,11 @@ export function registerMembersCommand(program: Command): void {
   members
     .command("invite <target>")
     .description(
-      "Invite a person to the company by email or personUid (sends an invitation email by default)",
+      "Invite a person or fleet agent to the company. People: email or prs_…. Agents: agt_… or agt-…@agents.getindigo.ai (member|admin; host keeps billing, no double charge).",
     )
     .option(
       "--role <role>",
-      "Role for the invitee: owner, admin, member, or guest",
+      "Role: person → owner|admin|member|guest; agent → member|admin only",
       "member",
     )
     .option(
@@ -681,17 +746,49 @@ export function registerMembersCommand(program: Command): void {
             role: opts.role,
             paths: opts.paths,
             groupIds,
-            sendEmail: opts.sendEmail,
+            // Agents join actively — no Resend email.
+            sendEmail: detectTarget(target)?.isAgent ? false : opts.sendEmail,
             companyUid,
             callerUid,
             token,
           });
 
+          const agentTarget = detectTarget(target)?.isAgent === true;
           console.log(
             chalk.green(
               `Invited ${target} as ${result.membership.role} (status: ${result.membership.status})`,
             ),
           );
+          // Agent path is confirmed only when the server returned the guest-invite
+          // envelope (activationBilled present) AND status is active. A pending
+          // row means this hq-pro stage has not rolled the agent invite path yet —
+          // do NOT claim active join / no-double-bill.
+          if (
+            agentTarget &&
+            result.membership.status === "active" &&
+            typeof result.activationBilled === "boolean"
+          ) {
+            console.log(
+              chalk.dim(
+                `Fleet agent: active membership granted immediately` +
+                  (result.hostCompanyUid
+                    ? ` (host ${result.hostCompanyUid} keeps billing)`
+                    : " (host keeps billing, no double charge)") +
+                  `. Next: share secrets / vault paths as needed (\`hq secrets share\`, \`/new-agent\`).`,
+              ),
+            );
+            console.log();
+            return;
+          }
+          if (agentTarget && result.membership.status !== "active") {
+            console.log(
+              chalk.yellow(
+                "⚠ Agent invite landed as a pending membership — this hq-pro stage may not yet have multi-company agent invite. Wait for prod deploy of the agent membership path, then re-invite (or revoke this pending row).",
+              ),
+            );
+            console.log();
+            return;
+          }
           console.log();
           if (result.magicLink) {
             // Legacy server schema — magic-link redemption.

package/src/commands/outposts.test.ts

@@ -27,6 +27,21 @@ vi.mock("../utils/cognito-session.js", async (importOriginal) => {
   };
 });
 
+// Outpost provision reads the cached refresh token to send to the box. Stub the
+// hq-cloud token store so tests don't need a real session on disk.
+vi.mock("@indigoai-us/hq-cloud", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("@indigoai-us/hq-cloud")>();
+  return {
+    ...original,
+    loadCachedTokens: vi.fn(() => ({
+      refreshToken: "rt_test",
+      idToken: "id_test",
+      accessToken: "at_test",
+    })),
+  };
+});
+
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { registerOutpostsCommand } from "./outposts.js";
 
@@ -175,3 +190,58 @@ describe("hq outposts destroy", () => {
     ).rejects.toThrow("process.exit(1)");
   });
 });
+
+describe("hq outposts provision (billing gate)", () => {
+  it("refuses without --yes, prints the cost, and makes NO API call", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(run(["outposts", "provision"])).rejects.toThrow(
+      "process.exit(1)",
+    );
+    expect(fetchSpy).not.toHaveBeenCalled();
+    const printed = errSpy.mock.calls
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toMatch(/\$80\.00\/month/);
+  });
+
+  it("POSTs /outpost/provision with the refresh token when --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(jsonResponse(200, { ok: true }));
+    await run(["outposts", "provision", "--runtime", "codex", "--yes"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/outpost/provision");
+    expect(init?.method).toBe("POST");
+    const sent = JSON.parse(init?.body as string);
+    expect(sent.refreshToken).toBe("rt_test");
+    expect(sent.agentRuntime).toBe("codex");
+  });
+
+  it("mints a card-capture link on 402 billing_required and exits 1", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          billing: {
+            status: "billing_required",
+            setup: {
+              payerType: "person",
+              path: "/v1/billing/checkout/person",
+              method: "POST",
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/outpost" }),
+      );
+
+    await expect(
+      run(["outposts", "provision", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    expect(String(fetchSpy.mock.calls[1][0])).toContain(
+      "/v1/billing/checkout/person",
+    );
+    const printed = logSpy.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/outpost");
+  });
+});

package/src/commands/outposts.ts

@@ -23,18 +23,34 @@
 
 import { Command } from "commander";
 import chalk from "chalk";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import {
+  OUTPOST_PRICE_CENTS,
+  confirmChargeOrExit,
+  parseBillingPayload,
+  surfaceBillingRequired,
+  type BillingErrorPayload,
+} from "../utils/billing-gate.js";
 
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export class OutpostHttpError extends Error {
   status: number;
   step?: string;
-  constructor(status: number, message: string, step?: string) {
+  /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+  billing?: BillingErrorPayload;
+  constructor(
+    status: number,
+    message: string,
+    step?: string,
+    billing?: BillingErrorPayload,
+  ) {
     super(message);
     this.name = "OutpostHttpError";
     this.status = status;
     this.step = step;
+    this.billing = billing;
   }
 }
 
@@ -61,6 +77,7 @@ export async function outpostRequest<T>(opts: {
   token: string;
   path: string;
   method?: string;
+  body?: Record<string, unknown>;
   query?: Record<string, string>;
 }): Promise<T> {
   const res = await vaultApiFetch(opts);
@@ -76,11 +93,45 @@ export async function outpostRequest<T>(opts: {
         : typeof body.error === "string"
           ? body.error
           : res.statusText;
-    throw new OutpostHttpError(res.status, message, body.step);
+    throw new OutpostHttpError(
+      res.status,
+      message,
+      body.step,
+      parseBillingPayload(body),
+    );
   }
   return (await res.json()) as T;
 }
 
+/**
+ * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
+ * box can authenticate AS the caller (the same body the console's
+ * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
+ * per-person cap gets their existing box back rather than a duplicate. The
+ * refresh token is sent over HTTPS and NEVER printed.
+ */
+export async function provisionOutpost(
+  token: string,
+  input: {
+    refreshToken: string;
+    clientIp?: string;
+    diskSizeGb?: number;
+    agentRuntime?: "claude" | "codex";
+  },
+): Promise<Record<string, unknown>> {
+  return outpostRequest({
+    token,
+    path: "/outpost/provision",
+    method: "POST",
+    body: {
+      refreshToken: input.refreshToken,
+      ...(input.clientIp ? { clientIp: input.clientIp } : {}),
+      ...(input.diskSizeGb ? { diskSizeGb: input.diskSizeGb } : {}),
+      ...(input.agentRuntime ? { agentRuntime: input.agentRuntime } : {}),
+    },
+  });
+}
+
 export async function listOutposts(token: string): Promise<OutpostSummary[]> {
   const data = await outpostRequest<{ outposts: OutpostSummary[] }>({
     token,
@@ -165,6 +216,81 @@ export function registerOutpostsCommand(program: Command): void {
     .command("outposts")
     .description("Manage your personal HQ Outposts (EC2 boxes)");
 
+  outposts
+    .command("provision")
+    .alias("create")
+    .description("Provision a new Outpost ($80/month — requires --yes)")
+    .option("--runtime <runtime>", "Agent runtime: claude | codex (default claude)")
+    .option("--disk <gb>", "Root disk size in GB (EC2 only)")
+    .option(
+      "--client-ip <ip>",
+      "Your public IP for the box's SSH ingress (optional; server derives it otherwise)",
+    )
+    .option("--yes", "Confirm the $80/month charge (required to provision)")
+    .action(async function (
+      this: Command,
+      opts: { runtime?: string; disk?: string; clientIp?: string; yes?: boolean },
+    ) {
+      try {
+        const agentRuntime =
+          opts.runtime === "codex"
+            ? "codex"
+            : opts.runtime
+              ? "claude"
+              : undefined;
+        let diskSizeGb: number | undefined;
+        if (opts.disk !== undefined) {
+          diskSizeGb = Number(opts.disk);
+          if (!Number.isFinite(diskSizeGb) || diskSizeGb <= 0) {
+            console.error(chalk.red(`Invalid --disk '${opts.disk}': must be a positive number of GB.`));
+            process.exit(1);
+          }
+        }
+
+        // Paid gate: print the monthly cost and require --yes before any call.
+        confirmChargeOrExit({
+          resource: "Outpost",
+          unitCents: OUTPOST_PRICE_CENTS,
+          yes: opts.yes,
+        });
+
+        // The box authenticates AS the caller using the cached refresh token —
+        // the same body the console sends. Never printed.
+        const refreshToken = loadCachedTokens()?.refreshToken;
+        if (!refreshToken) {
+          console.error(
+            chalk.red("No cached session found — run `hq login` first, then re-run."),
+          );
+          process.exit(1);
+        }
+
+        const token = await ensureCognitoToken();
+        try {
+          await provisionOutpost(token, {
+            refreshToken,
+            ...(opts.clientIp ? { clientIp: opts.clientIp } : {}),
+            ...(diskSizeGb ? { diskSizeGb } : {}),
+            ...(agentRuntime ? { agentRuntime } : {}),
+          });
+          console.log(chalk.green("Provisioning started for your Outpost."));
+          console.log(chalk.dim("Track it: hq outposts status"));
+        } catch (err) {
+          // No card on file → surface the shareable payment link, not an opaque 402.
+          if (
+            err instanceof OutpostHttpError &&
+            err.status === 402 &&
+            err.billing
+          ) {
+            await surfaceBillingRequired(token, err.billing);
+            process.exit(1);
+          }
+          throw err;
+        }
+      } catch (err) {
+        fail(err);
+      }
+    });
+
   outposts
     .command("list")
     .description("List every Outpost you own")

package/src/main.ts

@@ -56,6 +56,7 @@ import { registerCrmCommand } from "./commands/crm.js";
 import { registerCompanyCommand } from "./commands/company.js";
 import { registerAgentsCommand } from "./commands/agents.js";
 import { registerOutpostsCommand } from "./commands/outposts.js";
+import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
@@ -258,6 +259,11 @@ registerAgentsCommand(program);
 // /outpost/* control plane.
 registerOutpostsCommand(program);
 
+// Billing (subcommand group — `hq billing …`). Check subscription/card state and
+// mint a shareable Stripe card-capture link — the client side of the paid-
+// provisioning gate for agents & Outposts.
+registerBillingCommand(program);
+
 export async function runCli(): Promise<void> {
   try {
     Sentry.addBreadcrumb({

package/src/utils/billing-gate.test.ts

@@ -0,0 +1,95 @@
+/**
+ * Unit tests for the billing-gate helpers (pure parsers + price formatting).
+ * The command-level flows are covered in commands/{agents,outposts,billing}.test.ts;
+ * this pins the trust-boundary parsing and the cost string.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  AGENT_PRICE_CENTS,
+  OUTPOST_PRICE_CENTS,
+  formatUsd,
+  isBillingSetupAction,
+  parseBillingPayload,
+} from "./billing-gate.js";
+
+describe("prices", () => {
+  it("match the console's authoritative constants", () => {
+    expect(AGENT_PRICE_CENTS).toBe(10_000);
+    expect(OUTPOST_PRICE_CENTS).toBe(8_000);
+  });
+});
+
+describe("formatUsd", () => {
+  it("renders cents as $X.YZ", () => {
+    expect(formatUsd(10_000)).toBe("$100.00");
+    expect(formatUsd(8_000)).toBe("$80.00");
+    expect(formatUsd(0)).toBe("$0.00");
+  });
+  it("clamps negatives to zero", () => {
+    expect(formatUsd(-500)).toBe("$0.00");
+  });
+});
+
+describe("isBillingSetupAction", () => {
+  it("accepts a valid org setup", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "company",
+        path: "/v1/billing/checkout/org",
+        method: "POST",
+        body: { companyUid: "cmp_x" },
+      }),
+    ).toBe(true);
+  });
+  it("accepts a valid person setup with no body", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "person",
+        path: "/v1/billing/checkout/person",
+        method: "POST",
+      }),
+    ).toBe(true);
+  });
+  it("rejects unknown paths / shapes", () => {
+    expect(
+      isBillingSetupAction({
+        payerType: "company",
+        path: "/v1/billing/checkout/evil",
+        method: "POST",
+      }),
+    ).toBe(false);
+    expect(isBillingSetupAction(null)).toBe(false);
+    expect(isBillingSetupAction({ payerType: "company" })).toBe(false);
+  });
+});
+
+describe("parseBillingPayload", () => {
+  it("extracts status + setup from a 402 body", () => {
+    const parsed = parseBillingPayload({
+      error: "payment required",
+      billing: {
+        status: "billing_required",
+        setup: {
+          payerType: "company",
+          path: "/v1/billing/checkout/org",
+          method: "POST",
+          body: { companyUid: "cmp_x" },
+        },
+      },
+    });
+    expect(parsed?.status).toBe("billing_required");
+    expect(parsed?.setup?.path).toBe("/v1/billing/checkout/org");
+  });
+  it("returns status with no setup when the setup is malformed", () => {
+    const parsed = parseBillingPayload({
+      billing: { status: "billing_required", setup: { bogus: true } },
+    });
+    expect(parsed?.status).toBe("billing_required");
+    expect(parsed?.setup).toBeUndefined();
+  });
+  it("returns undefined for a non-billing error body", () => {
+    expect(parseBillingPayload({ error: "forbidden" })).toBeUndefined();
+    expect(parseBillingPayload(null)).toBeUndefined();
+  });
+});