@indigoai-us/hq-cli 5.101.7 → 5.103.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 ## [Unreleased]
 
+## [5.103.0] — 2026-08-18
+
+### Added
+
+- `hq doctor` now checks the AI runtimes themselves, not just their hook
+  wiring. A new "AI runtime health" family verifies the `claude`, `codex`, and
+  `grok` CLIs are on PATH (a pure filesystem scan — the default run stays
+  offline; a missing CLI is WARN, never FAIL). A new `--live-runtimes` flag
+  additionally reads each installed CLI's version and sends it a one-line
+  prompt from a temp directory, proving the full binary → login → subscription
+  → response path; without the flag those checks report UNTESTED, so a
+  logged-out or broken runtime can no longer hide behind green wiring checks.
+
+## [5.102.0] — 2026-08-17
+
+### Added
+
+- **`hq integrations` now covers the whole lifecycle**, not just using an
+  already-connected app. Previously the CLI could `list` / `tools` / `call` /
+  `approve` / `reject`, and everything else had to happen on the console.
+
+  Find and add:
+  - `hq integrations catalog [query]` (alias `search`) — browse or search
+    connectable apps, showing each one's sign-in style and provenance.
+  - `hq integrations inspect <app>` — surfaces, credentials, and warnings for
+    an app before you commit to it.
+  - `hq integrations discover <docsUrl>` — find a connectable server from a
+    documentation page.
+  - `hq integrations connect <app>` (alias `add`) — connect by domain, catalog
+    entry (`--entry-id`), docs page (`--docs-url`), or a raw endpoint
+    (`--mcp-url`). Auth mode is detected rather than declared: no-auth installs
+    directly, API-key apps read the key from `--token-stdin` / a hidden prompt
+    / `--token`, and OAuth apps run a browser sign-in. If hq-pro answers
+    `INTEGRATION_FACTORY_OAUTH_REQUIRED` to a direct install, the browser flow
+    starts automatically.
+  - `hq integrations reconnect [app]` — re-authenticate an app whose stored
+    credentials stopped working.
+
+  Govern and remove:
+  - `hq integrations show [app]` — one connection in full.
+  - `hq integrations policy [app] [--set auto-allow|confirm|deny]`.
+  - `hq integrations grants|grant|ungrant` — per-tool approval exceptions.
+  - `hq integrations access|share|unshare` — who in the company may use an app.
+  - `hq integrations audit` / `pending` — recent activity and queued approvals.
+  - `hq integrations disconnect [app]` (alias `remove`) — deletes stored
+    credentials; confirms first, and refuses non-interactively without `--yes`.
+
+  OAuth sign-in uses an RFC 8252 §7.3 loopback listener (`127.0.0.1`, ephemeral
+  port, pinned callback path), so the code never leaves the machine and the
+  PKCE verifier stays server-side in hq-pro. Against a backend that does not
+  admit a loopback callback, connect degrades to printing the sign-in URL for
+  the console to finish, and says so rather than reporting a false success.
+
+  Requires hq-pro with `INTEGRATION_FACTORY_OAUTH_LOOPBACK_ENABLED` for the
+  fully CLI-native OAuth path; every other verb works against any current
+  deployment.
+
 ## [5.101.7] — 2026-08-17
 
 ### Changed

package/dist/commands/agents.d.ts

@@ -15,6 +15,9 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
+ *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
+ *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
  *
  * Agents are company-scoped. `--company <slug>` may sit on the group
  * (`hq agents --company acme list`) or on a subcommand
@@ -204,6 +207,46 @@ export declare function deprovisionAgent(token: string, agentUid: string): Promi
     setupState?: string;
     terminal?: boolean;
 }>;
+/** EventBridge Scheduler State as the operator list/pause surface reports it. */
+export type JobScheduleState = "ENABLED" | "DISABLED";
+/** One operator list row from `GET /v1/agents/{uid}/jobs`. */
+export interface AgentJobView {
+    jobId: string;
+    scheduleState: JobScheduleState | string;
+    rate: string;
+    lastRunOutcome: string | null;
+    status?: string;
+    nextRunAt?: string | null;
+    lastRunAt?: string | null;
+    prompt?: string;
+}
+export interface PauseJobResult {
+    ok: true;
+    jobId: string;
+    scheduleState: "DISABLED" | string;
+    changed: boolean;
+    previousState?: string;
+}
+export interface CancelJobResult {
+    ok: true;
+    jobId: string;
+}
+export declare function listAgentJobs(token: string, agentUid: string): Promise<AgentJobView[]>;
+export declare function pauseAgentJob(token: string, agentUid: string, jobId: string): Promise<PauseJobResult>;
+export declare function cancelAgentJob(token: string, agentUid: string, jobId: string): Promise<CancelJobResult>;
+/**
+ * Map a jobs-control HTTP error to a single operator-facing line. Pure so the
+ * status/code → copy mapping is unit-tested without a process exit.
+ *
+ * 404 without `JOB_NOT_FOUND` is also the deploy-order-safe path: hq-cli
+ * shipped before the hq-pro endpoints exist (or the agents flag is OFF, or
+ * the agent is cross-company) must print a clear message and exit non-zero,
+ * never throw a stack trace.
+ */
+export declare function formatJobsHttpError(err: AgentsHttpError, jobId?: string): string;
+/** Stable padEnd table: jobId, scheduleState, rate, lastRunOutcome, status. */
+export declare function formatJobsTable(jobs: AgentJobView[]): string;
+export declare function formatPauseResult(result: PauseJobResult): string;
 /** 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`. */

package/dist/commands/agents.js

@@ -15,6 +15,9 @@
  *   hq agents start|stop <uid>     — EC2 start/stop
  *   hq agents retry <uid>          — resume setup from first non-done step
  *   hq agents rm <uid> --yes       — deprovision (destructive; flag-guarded)
+ *   hq agents jobs list <uid>      — off-box job roster (schedule + rate)
+ *   hq agents jobs pause <uid> <jobId>  — flip schedule State=DISABLED
+ *   hq agents jobs cancel <uid> <jobId> — delete schedule + drop the job
  *
  * Agents are company-scoped. `--company <slug>` may sit on the group
  * (`hq agents --company acme list`) or on a subcommand
@@ -309,6 +312,79 @@ export async function deprovisionAgent(token, agentUid) {
         method: "DELETE",
     });
 }
+export async function listAgentJobs(token, agentUid) {
+    const data = await agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs`,
+    });
+    return data.jobs ?? [];
+}
+export async function pauseAgentJob(token, agentUid, jobId) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/pause`,
+        method: "POST",
+    });
+}
+export async function cancelAgentJob(token, agentUid, jobId) {
+    return agentsRequest({
+        token,
+        path: `/v1/agents/${encodeURIComponent(agentUid)}/jobs/${encodeURIComponent(jobId)}/cancel`,
+        method: "POST",
+    });
+}
+/**
+ * Map a jobs-control HTTP error to a single operator-facing line. Pure so the
+ * status/code → copy mapping is unit-tested without a process exit.
+ *
+ * 404 without `JOB_NOT_FOUND` is also the deploy-order-safe path: hq-cli
+ * shipped before the hq-pro endpoints exist (or the agents flag is OFF, or
+ * the agent is cross-company) must print a clear message and exit non-zero,
+ * never throw a stack trace.
+ */
+export function formatJobsHttpError(err, jobId) {
+    if (err.status === 401)
+        return "Not authenticated — run `hq login`.";
+    if (err.status === 403)
+        return "You need owner/admin on this company.";
+    if (err.status === 404 && err.code === "JOB_NOT_FOUND") {
+        const id = jobId ?? extractQuotedJobId(err.message) ?? "unknown";
+        return `Job '${id}' not found.`;
+    }
+    if (err.status === 404)
+        return "Agent not found or not accessible.";
+    if (err.code === "JOBS_SCHEDULER_UNAVAILABLE" ||
+        err.code === "SCHEDULE_DELETE_FAILED") {
+        return `${err.code}: ${err.message}`;
+    }
+    return err.message;
+}
+function extractQuotedJobId(message) {
+    const m = message.match(/Job '([^']+)'/i);
+    return m?.[1];
+}
+/** Stable padEnd table: jobId, scheduleState, rate, lastRunOutcome, status. */
+export function formatJobsTable(jobs) {
+    if (jobs.length === 0)
+        return "No jobs.";
+    const cols = ["JOB_ID", "STATE", "RATE", "LAST_RUN", "STATUS"];
+    const rows = jobs.map((j) => [
+        j.jobId,
+        String(j.scheduleState ?? ""),
+        j.rate ?? "",
+        j.lastRunOutcome ?? "-",
+        j.status ?? "",
+    ]);
+    const widths = cols.map((c, i) => Math.max(c.length, ...rows.map((r) => r[i].length)));
+    const render = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+    return [chalk.bold(render(cols)), ...rows.map(render)].join("\n");
+}
+export function formatPauseResult(result) {
+    if (!result.changed)
+        return "Already paused";
+    const from = result.previousState ?? "ENABLED";
+    return `Paused ${result.jobId} (${from} → ${result.scheduleState})`;
+}
 /** Human-readable "hot-applied to the running box" vs "saved for next launch". */
 export function appliedHint(applied) {
     return applied
@@ -394,6 +470,13 @@ function fail(err) {
     }
     process.exit(1);
 }
+function failJobs(err, jobId) {
+    if (err instanceof AgentsHttpError) {
+        console.error(chalk.red(formatJobsHttpError(err, jobId)));
+        process.exit(1);
+    }
+    fail(err);
+}
 export function registerAgentsCommand(program) {
     const agents = program
         .command("agents")
@@ -842,5 +925,59 @@ export function registerAgentsCommand(program) {
             fail(err);
         }
     });
+    // Off-box job control (US-003). Nested group so `hq agents jobs --help`
+    // lists list|pause|cancel. Same vaultApiFetch + person JWT as the rest of
+    // this file; keyed HQ_API_KEY rewrites /v1/agents → /v1/keys/agents.
+    const jobs = agents
+        .command("jobs")
+        .description("List, pause, or cancel an agent's scheduled jobs");
+    jobs
+        .command("list <agentUid>")
+        .description("List an agent's scheduled jobs")
+        .option("--json", "Emit raw JSON")
+        .action(async (agentUid, opts) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const roster = await listAgentJobs(token, agentUid);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(roster, null, 2) + "\n");
+                return;
+            }
+            if (roster.length === 0) {
+                console.log(chalk.gray("No jobs."));
+                return;
+            }
+            console.log(formatJobsTable(roster));
+        }
+        catch (err) {
+            failJobs(err);
+        }
+    });
+    jobs
+        .command("pause <agentUid> <jobId>")
+        .description("Pause a job's schedule (reversible)")
+        .action(async (agentUid, jobId) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await pauseAgentJob(token, agentUid, jobId);
+            console.log(chalk.green(formatPauseResult(result)));
+        }
+        catch (err) {
+            failJobs(err, jobId);
+        }
+    });
+    jobs
+        .command("cancel <agentUid> <jobId>")
+        .description("Cancel a job and delete its schedule")
+        .action(async (agentUid, jobId) => {
+        try {
+            const token = (await resolveVaultCredential()).token;
+            const result = await cancelAgentJob(token, agentUid, jobId);
+            console.log(chalk.green(`Cancelled ${result.jobId}.`));
+        }
+        catch (err) {
+            failJobs(err, jobId);
+        }
+    });
 }
 //# sourceMappingURL=agents.js.map

package/dist/commands/doctor.d.ts

@@ -8,7 +8,9 @@
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
  *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree.
+ *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
+ *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
+ *     grok) with a version read and a one-line prompt.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -77,6 +79,13 @@ export interface RunDoctorOptions {
      * does — so a plain `hq doctor` stays purely a function of the on-disk shape.
      */
     deepTest?: boolean;
+    /**
+     * Additionally probe each installed AI CLI (claude, codex, grok) with a
+     * version read and a one-line prompt (`--live-runtimes`). Off by default:
+     * this is the doctor's only networked tier, and without it the runtime-health
+     * family reports UNTESTED rather than spawning anything.
+     */
+    liveRuntimes?: boolean;
 }
 /** The outcome of a doctor run, returned rather than thrown so it is testable. */
 export interface RunDoctorResult {

package/dist/commands/doctor.js

@@ -8,7 +8,9 @@
  *   - Running outside any HQ tree exits non-zero with a message naming exactly
  *     what it looked for — never a throw, never a false PASS.
  *   - The command performs no network calls and needs no authentication; it is
- *     purely a function of the on-disk shape of the tree.
+ *     purely a function of the on-disk shape of the tree. `--live-runtimes` is
+ *     the one opt-in exception: it probes the installed AI CLIs (claude, codex,
+ *     grok) with a version read and a one-line prompt.
  *
  * US-015 adds reporting, `--json`, and the exit-code contract: the exit code is
  * 0 unless some result is FAIL or UNKNOWN (WARN/UNTESTED/NA/KNOWN-DEFECT never
@@ -99,6 +101,7 @@ export async function runDoctor(options = {}) {
         hqRoot,
         platform: { id: platform.id, evidence: platform.evidence },
         sessionId: options.sessionId,
+        liveRuntimes: options.liveRuntimes === true,
     };
     const families = await registry.run(context);
     // `--deep-test` (US-008): after the read-only tiers, actually fire pure-guard
@@ -147,12 +150,13 @@ export async function runDoctor(options = {}) {
 export function registerDoctorCommand(program) {
     program
         .command("doctor")
-        .description("Verify HQ hook guardrails are wired and firing (read-only, offline).")
+        .description("Verify HQ hook guardrails are wired and firing (read-only, offline; --live-runtimes adds networked AI CLI probes).")
         .option("--json", "Emit the machine-readable JSON document (no colour).")
         .option("--verbose", "Also print every PASS result in text output.")
         .option("--no-color", "Disable ANSI colour even on a TTY.")
         .option("--session-id <id>", "Scope the runtime probe's ledger check to this exact session.")
         .option("--deep-test", "Also fire pure-guard hooks through the real gate under all three profiles (sandboxed).")
+        .option("--live-runtimes", "Also probe each installed AI CLI (claude, codex, grok) with a one-line prompt to verify login and subscription (networked; uses your subscriptions).")
         .option("--fix", "Apply the allowlisted safe repairs (backs up first; read-only without this flag).")
         .option("--yes", "Skip the interactive --fix confirmation (non-interactive use).")
         .option("--force", "Let --fix run despite uncommitted changes under .claude/, .codex/, or .grok/.")
@@ -199,6 +203,7 @@ export function registerDoctorCommand(program) {
             platform,
             sessionId: opts.sessionId,
             deepTest: opts.deepTest === true,
+            liveRuntimes: opts.liveRuntimes === true,
         });
         // Set the exit code rather than calling process.exit, so the CLI's
         // normal shutdown (telemetry flush) still runs. Non-zero means either an

package/dist/commands/integrations-api.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Typed client for hq-pro's integration-factory routes.
+ *
+ * One function per endpoint, each a thin `vaultApiFetch` + `raiseForResponse`
+ * pair. The wire shapes below MIRROR hq-pro (`src/vault-service/handlers/
+ * integrations-admin.ts`) rather than importing from it — hq-cli takes no
+ * cross-repo source dependency — so every field a newer backend might not emit
+ * is optional and read defensively.
+ */
+import { type GranteeType, type Permission, type WriteAllowlistGrant, type WritePolicy } from "./integrations-core.js";
+export interface CatalogEntry {
+    name: string;
+    domain: string;
+    description?: string;
+    /** True when the app is one-click connectable (has a remote MCP surface). */
+    mcpReady: boolean;
+    scope?: "company" | "global";
+    /**
+     * Provenance: `integrations.sh` is the curated third-party feed,
+     * `hq-recommended` is first-party, `hq-discovered` is a Community definition
+     * learned from a successful connect elsewhere.
+     */
+    source?: "hq-discovered" | "integrations.sh" | "hq-recommended";
+    authClass?: "none" | "key" | "oauth";
+    /** Opaque server-owned id; prefer it over echoing connection details back. */
+    entryId?: string;
+}
+export declare function listCatalog(token: string, companyUid: string, opts?: {
+    limit?: number;
+    query?: string;
+}): Promise<CatalogEntry[]>;
+export interface BlueprintSurface {
+    kind: string;
+    slug: string;
+    name: string;
+    url?: string;
+    docs?: string;
+    authStatus: "required" | "optional" | "none" | "unknown";
+    credentialIds: string[];
+    readiness: {
+        strategy: string;
+        score: number;
+        reason: string;
+    };
+}
+export interface Blueprint {
+    provider: string;
+    displayName: string;
+    domain: string;
+    summary?: string;
+    description?: string;
+    credentials: Array<{
+        id: string;
+        type: string;
+        label: string;
+        generateUrl?: string;
+    }>;
+    surfaces: BlueprintSurface[];
+    recommendedSurface?: BlueprintSurface;
+    warnings: Array<{
+        code: string;
+        message: string;
+        source?: string;
+    }>;
+}
+export declare function pullBlueprint(token: string, companyUid: string, input: {
+    domain?: string;
+    query?: string;
+    catalogEntryId?: string;
+}): Promise<Blueprint>;
+export interface DocsDiscovery {
+    docsUrl: string;
+    displayName: string;
+    provider: string;
+    mcpUrl: string;
+    authMode: "none" | "bearer" | "oauth";
+    transport: string;
+    verification: "verified" | "pending-auth";
+    confidence: "high" | "medium";
+    evidenceUrls: string[];
+}
+export interface DiscoverDocsResult {
+    /** Absent when hq-pro verified no MCP surface on the page. */
+    discovery?: DocsDiscovery;
+    /**
+     * Caller- and company-bound continuation token. Passing this to connect is
+     * what lets hq-pro trust the endpoint WITHOUT re-reading a URL the terminal
+     * echoed back at it. Short-lived (~15 min).
+     */
+    discoveryReceiptId?: string;
+    sourceTruncated?: boolean;
+}
+export declare function discoverDocs(token: string, companyUid: string, docsUrl: string): Promise<DiscoverDocsResult>;
+export interface InstallResult {
+    connection: {
+        id: string;
+        provider: string;
+        status: string;
+        scopes?: string[];
+    };
+    installation: {
+        id: string;
+        displayName: string;
+        domain: string;
+        status: "installed" | "needs_credentials";
+        surface?: {
+            kind?: string;
+            url?: string;
+            authStatus?: string;
+        };
+    };
+    mcp?: {
+        tools?: Array<{
+            name: string;
+            description?: string;
+            mode?: string;
+        }>;
+    };
+    credential?: {
+        required: boolean;
+        configured: boolean;
+        authStatus?: string;
+    };
+    writeAllowlist?: WriteAllowlistGrant[];
+}
+export interface InstallInput {
+    domain?: string;
+    query?: string;
+    catalogEntryId?: string;
+    discoveryReceiptId?: string;
+    mcpUrl?: string;
+    provider?: string;
+    displayName?: string;
+    docsUrl?: string;
+    authMode?: "none" | "bearer";
+    bearerToken?: string;
+}
+export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
+export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{
+    installationId: string;
+    connectionId: string;
+}>;
+export interface OAuthStartResult {
+    provider: string;
+    displayName: string;
+    /** The remote auth server's authorize URL — open this in a browser. */
+    authorizationUrl: string;
+    state: string;
+    expiresAt: string;
+}
+export interface OAuthStartInput {
+    mcpUrl?: string;
+    catalogEntryId?: string;
+    discoveryReceiptId?: string;
+    provider?: string;
+    displayName?: string;
+    domain?: string;
+    docsUrl?: string;
+    /**
+     * The native client's loopback callback. hq-pro accepts it only when its
+     * loopback flag is on and the URI matches the pinned RFC 8252 §7.3 shape;
+     * omitting it pins the console callback instead.
+     */
+    redirectUri?: string;
+}
+export declare function startOAuth(token: string, companyUid: string, input: OAuthStartInput): Promise<OAuthStartResult>;
+export declare function completeOAuth(token: string, companyUid: string, input: {
+    state: string;
+    code: string;
+}): Promise<InstallResult>;
+export declare function updateGovernance(token: string, companyUid: string, input: {
+    connectionId: string;
+    writePolicy?: WritePolicy;
+    /**
+     * REPLACES the connection's whole per-tool allowlist — hq-pro has no
+     * add/remove verb. Callers must read the current list, merge, and send the
+     * full result, never a delta.
+     */
+    writeAllowlist?: WriteAllowlistGrant[];
+}): Promise<{
+    writePolicy?: WritePolicy;
+    writeAllowlist: WriteAllowlistGrant[];
+}>;
+export interface ConnectionAccess {
+    connectionId: string;
+    provider: string;
+    creator: {
+        uid: string;
+        name?: string | null;
+    };
+    /** True when the connection predates access control and has no ACL row. */
+    grandfathered: boolean;
+    /** Whether THIS caller may grant/revoke. */
+    canManage: boolean;
+    access: {
+        mode: string;
+        grantCount: number;
+    };
+    entries: Array<{
+        granteeType: GranteeType;
+        granteeId: string;
+        granteeName?: string | null;
+        permission: Permission;
+        grantedBy: string;
+        grantedByName?: string | null;
+        grantedAt: string;
+    }>;
+}
+export declare function getConnectionAccess(token: string, companyUid: string, connectionId: string): Promise<ConnectionAccess>;
+export declare function mutateConnectionAccess(token: string, companyUid: string, action: "grant" | "revoke", input: {
+    connectionId: string;
+    granteeType: GranteeType;
+    granteeId?: string;
+    permission?: Permission;
+}): Promise<ConnectionAccess>;
+//# sourceMappingURL=integrations-api.d.ts.map