@indigoai-us/hq-cli 5.103.19 → 5.103.21

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+## [5.103.21] — 2026-08-24
+
+### Fixed
+
+- `hq agents jobs list|pause|cancel` now fails closed on an agent box instead of
+  provoking a cross-agent rejection on the server. These off-box operator
+  commands are reachable on agent boxes, where the CLI authenticates with the
+  box's own agent machine identity; forwarding another agent's identifier into
+  `GET /v1/agents/{uid}/jobs` was refused server-side by hq-pro's self-only jobs
+  guard and logged as an unexpected warning, while the CLI mislabeled the 403 as
+  "You need owner/admin on this company." — a role problem a box can never
+  satisfy. The commands now resolve the agent reference through the company
+  roster (a slug or name becomes an `agt_` uid, or fails locally), and refuse a
+  cross-agent target before any request leaves the box, naming the on-box
+  `hq-agent-jobs` tool and the person session required to manage another agent's
+  jobs. A server-side `CROSS_AGENT_JOB` denial is now rendered as identity-scoped
+  guidance rather than the owner/admin copy. Separately, every authenticated
+  vault-API request now carries an `x-hq-client-name` header so its origin is
+  attributable in telemetry and error reports. (Sentry 7617401436)
+
+## [5.103.20] — 2026-08-24
+
+### Changed
+
+- The bundled sync engine now requires `@indigoai-us/hq-cloud` 6.15.37, the
+  current production release.
+
 ## [5.103.19] — 2026-08-22
 
 ### Fixed

package/dist/commands/agents.d.ts

@@ -267,6 +267,29 @@ export interface DmThreadMessage {
  * membership).
  */
 export declare function resolveAgentUid(token: string, ref: string, companySlug: string | undefined): Promise<string>;
+/**
+ * Fail-closed local guard for the off-box `hq agents jobs` operator commands.
+ *
+ * hq-pro's jobs endpoints are self-only for an agent machine identity: an
+ * agent-authenticated list/pause/cancel against `/v1/agents/{uid}/jobs` whose
+ * `{uid}` is not the caller's OWN agt_ uid is refused server-side as 403
+ * `CROSS_AGENT_JOB` and logged loud (`caller_uid_mismatch`, Sentry hq-pro
+ * 7617401436). That happens when these commands are run ON an agent box, where
+ * {@link resolveVaultCredential} silently returns the box's own agent ID token —
+ * the operator meant to act as a person with owner/admin, not as the box.
+ *
+ * Catch it locally so the call never leaves the box: decode the (already
+ * locally trusted, signature-unverified) bearer token and, ONLY when it proves
+ * an agent identity acting on a DIFFERENT agent, return a refusal string for the
+ * command to print before any HTTP request. Every other shape fails OPEN
+ * (returns `null`) and proceeds to the server exactly as today: a person session
+ * (no `custom:entityType` claim), an opaque / non-JWT credential (an `hqk_` API
+ * key), a token with a missing or malformed uid claim, or an agent acting on its
+ * OWN jobs.
+ *
+ * Pure: no network, no logging; never prints or returns the token itself.
+ */
+export declare function crossAgentJobsRefusal(token: string, resolvedAgentUid: string): string | null;
 /** 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`). */

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 { peekIdToken } from "../utils/id-token.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { confirmChargeOrExit, formatUsd, parseBillingPayload, surfaceBillingBlocked, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
@@ -345,6 +346,17 @@ export async function cancelAgentJob(token, agentUid, jobId) {
 export function formatJobsHttpError(err, jobId) {
     if (err.status === 401)
         return "Not authenticated — run `hq login`.";
+    // A 403 CROSS_AGENT_JOB is hq-pro's self-only jobs guard, not a role problem:
+    // the caller authenticated as one agent and asked about another. Naming it as
+    // "owner/admin required" (below) is misleading copy an agent box can never
+    // satisfy, so distinguish it here (defence in depth — the CLI now also fails
+    // closed locally before the request, see crossAgentJobsRefusal).
+    if (err.status === 403 && err.code === "CROSS_AGENT_JOB") {
+        return ("Jobs are scoped to the calling agent's own identity — an agent may only " +
+            "list, pause, or cancel its OWN jobs (use the on-box `hq-agent-jobs` tool). " +
+            "Managing another agent's jobs needs a person session with owner/admin on " +
+            "the company.");
+    }
     if (err.status === 403)
         return "You need owner/admin on this company.";
     if (err.status === 404 && err.code === "JOB_NOT_FOUND") {
@@ -420,6 +432,77 @@ export async function resolveAgentUid(token, ref, companySlug) {
     }
     return match.uid;
 }
+/**
+ * Fail-closed local guard for the off-box `hq agents jobs` operator commands.
+ *
+ * hq-pro's jobs endpoints are self-only for an agent machine identity: an
+ * agent-authenticated list/pause/cancel against `/v1/agents/{uid}/jobs` whose
+ * `{uid}` is not the caller's OWN agt_ uid is refused server-side as 403
+ * `CROSS_AGENT_JOB` and logged loud (`caller_uid_mismatch`, Sentry hq-pro
+ * 7617401436). That happens when these commands are run ON an agent box, where
+ * {@link resolveVaultCredential} silently returns the box's own agent ID token —
+ * the operator meant to act as a person with owner/admin, not as the box.
+ *
+ * Catch it locally so the call never leaves the box: decode the (already
+ * locally trusted, signature-unverified) bearer token and, ONLY when it proves
+ * an agent identity acting on a DIFFERENT agent, return a refusal string for the
+ * command to print before any HTTP request. Every other shape fails OPEN
+ * (returns `null`) and proceeds to the server exactly as today: a person session
+ * (no `custom:entityType` claim), an opaque / non-JWT credential (an `hqk_` API
+ * key), a token with a missing or malformed uid claim, or an agent acting on its
+ * OWN jobs.
+ *
+ * Pure: no network, no logging; never prints or returns the token itself.
+ */
+export function crossAgentJobsRefusal(token, resolvedAgentUid) {
+    const claims = peekIdToken(token);
+    const entityType = typeof claims["custom:entityType"] === "string"
+        ? claims["custom:entityType"]
+        : undefined;
+    const entityUid = typeof claims["custom:entityUid"] === "string"
+        ? claims["custom:entityUid"].trim()
+        : "";
+    // Positive proof required before refusing: an agent identity, a well-formed
+    // agt_ own-uid, and a target that differs from it. Anything else proceeds.
+    if (entityType !== "agent")
+        return null;
+    if (!AGENT_UID_PATTERN.test(entityUid))
+        return null;
+    if (entityUid === resolvedAgentUid.trim())
+        return null;
+    return (`Refusing to manage ${resolvedAgentUid}'s scheduled jobs using this agent's ` +
+        `own identity (${entityUid}). On an agent box, \`hq agents jobs\` authenticates ` +
+        `as the box itself, and hq-pro scopes an agent to its OWN jobs only — inspect ` +
+        `those with the on-box \`hq-agent-jobs\` tool. To manage another agent's jobs, ` +
+        `run this from a person session with owner/admin on the company (\`hq login\`), ` +
+        `not on the agent box.`);
+}
+/**
+ * Shared preamble for the three `hq agents jobs` actions: resolve the caller's
+ * credential, turn the (possibly slug/name) reference into an `agt_` uid via the
+ * roster, and fail closed BEFORE any jobs request when an agent identity targets
+ * another agent ({@link crossAgentJobsRefusal}). Returns the token + resolved
+ * uid for the caller's single jobs request. Never returns on a refusal or a
+ * resolution error — it prints and exits non-zero. The refusal exit lives
+ * OUTSIDE the resolution try so it is not re-wrapped as a generic failure.
+ */
+async function resolveJobsTargetOrExit(ref, company) {
+    let token;
+    let targetUid;
+    try {
+        token = (await resolveVaultCredential()).token;
+        targetUid = await resolveAgentUid(token, ref, company);
+    }
+    catch (err) {
+        return failJobs(err);
+    }
+    const refusal = crossAgentJobsRefusal(token, targetUid);
+    if (refusal) {
+        console.error(chalk.red(refusal));
+        process.exit(1);
+    }
+    return { token, targetUid };
+}
 /** Send a DM to an agent. Returns nothing meaningful beyond success. */
 export async function sendAgentDm(token, agentUid, message) {
     await agentsRequest({
@@ -934,11 +1017,12 @@ export function registerAgentsCommand(program) {
     jobs
         .command("list <agentUid>")
         .description("List an agent's scheduled jobs")
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
         .option("--json", "Emit raw JSON")
-        .action(async (agentUid, opts) => {
+        .action(async function (agentUid, opts) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const roster = await listAgentJobs(token, agentUid);
+            const roster = await listAgentJobs(token, targetUid);
             if (opts.json) {
                 process.stdout.write(JSON.stringify(roster, null, 2) + "\n");
                 return;
@@ -956,10 +1040,11 @@ export function registerAgentsCommand(program) {
     jobs
         .command("pause <agentUid> <jobId>")
         .description("Pause a job's schedule (reversible)")
-        .action(async (agentUid, jobId) => {
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .action(async function (agentUid, jobId) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const result = await pauseAgentJob(token, agentUid, jobId);
+            const result = await pauseAgentJob(token, targetUid, jobId);
             console.log(chalk.green(formatPauseResult(result)));
         }
         catch (err) {
@@ -969,10 +1054,11 @@ export function registerAgentsCommand(program) {
     jobs
         .command("cancel <agentUid> <jobId>")
         .description("Cancel a job and delete its schedule")
-        .action(async (agentUid, jobId) => {
+        .option("--company <slug>", "Company slug (to resolve an agent by name/slug)")
+        .action(async function (agentUid, jobId) {
+        const { token, targetUid } = await resolveJobsTargetOrExit(agentUid, companyOf(this));
         try {
-            const token = (await resolveVaultCredential()).token;
-            const result = await cancelAgentJob(token, agentUid, jobId);
+            const result = await cancelAgentJob(token, targetUid, jobId);
             console.log(chalk.green(`Cancelled ${result.jobId}.`));
         }
         catch (err) {

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

@@ -134,6 +134,22 @@ export interface InstallInput {
     docsUrl?: string;
     authMode?: "none" | "bearer";
     bearerToken?: string;
+    /** Preserve a non-default placement for a pasted key (for example X-API-Key). */
+    authScheme?: {
+        placement: "authorization";
+        format: "bearer";
+    } | {
+        placement: "authorization";
+        format: "prefix";
+        prefix: string;
+    } | {
+        placement: "authorization";
+        format: "basic";
+        username?: string;
+    } | {
+        placement: "header";
+        header: string;
+    };
 }
 export declare function installIntegration(token: string, companyUid: string, input: InstallInput): Promise<InstallResult>;
 export declare function uninstallIntegration(token: string, companyUid: string, installationId: string): Promise<{

package/dist/commands/integrations-connect.js

@@ -278,6 +278,14 @@ async function findCatalogEntry(token, companyUid, domain) {
 function domainLabel(domain) {
     return domain.trim().toLowerCase().split(".")[0] ?? "";
 }
+/** A catalog display name's copy-pasteable command-line slug. */
+function displayNameSlug(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 /**
  * Best-effort resolution of a bare name to a single catalog entry. Matches the
  * entry's registrable domain label (`notion` → `notion.com`) or an exact
@@ -293,7 +301,8 @@ async function findCatalogEntryByName(token, companyUid, name) {
             return null;
         const entries = await listCatalog(token, companyUid, { query: name, limit: 20 });
         const matches = entries.filter((entry) => domainLabel(entry.domain) === want ||
-            entry.name?.trim().toLowerCase() === want);
+            entry.name?.trim().toLowerCase() === want ||
+            (entry.name !== undefined && displayNameSlug(entry.name) === displayNameSlug(want)));
         if (matches.length === 0)
             return null;
         // Collapse rows that point at the same app (same domain) before deciding

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

@@ -201,8 +201,10 @@ export declare function fetchAdminSurface(token: string, companyUid: string): Pr
 export declare function fetchConnections(token: string, companyUid: string): Promise<AdminConnection[]>;
 /**
  * Resolve one connection by `--connection acct_…` or `--provider linear`
- * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
- * list what IS connected so the fix is one command away.
+ * (matches `factory:<slug>`, bare provider ids, and an installation's human
+ * display-name slug, case-insensitive). The legacy provider id remains a
+ * first-class match, so scripts that saved opaque historical slugs keep
+ * working. Errors list what IS connected so the fix is one command away.
  */
 export declare function selectConnection(connections: AdminConnection[], opts: {
     connection?: string;

package/dist/commands/integrations-core.js

@@ -199,6 +199,14 @@ export function toolPrefixForProvider(provider) {
 export function bareProvider(provider) {
     return provider.replace(/^factory:/, "");
 }
+/** Turn a factory display name into the human-friendly slug people type. */
+function humanSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
 /**
  * Read the whole admin surface: connections with their governance state, the
  * viewer's role, and the recent audit feed. Several verbs need more than the
@@ -231,8 +239,10 @@ export async function fetchConnections(token, companyUid) {
 }
 /**
  * Resolve one connection by `--connection acct_…` or `--provider linear`
- * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
- * list what IS connected so the fix is one command away.
+ * (matches `factory:<slug>`, bare provider ids, and an installation's human
+ * display-name slug, case-insensitive). The legacy provider id remains a
+ * first-class match, so scripts that saved opaque historical slugs keep
+ * working. Errors list what IS connected so the fix is one command away.
  */
 export function selectConnection(connections, opts) {
     const active = connections.filter((c) => c.status !== "revoked");
@@ -245,16 +255,28 @@ export function selectConnection(connections, opts) {
     }
     if (opts.provider) {
         const want = opts.provider.trim().toLowerCase();
-        const match = active.find((c) => {
-            const bare = bareProvider(c.provider).toLowerCase();
-            return bare === want || c.provider.toLowerCase() === want;
-        });
-        if (!match) {
-            const available = active.map((c) => bareProvider(c.provider)).join(", ");
-            throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
-                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps with `hq integrations connect <app>`."), { expected: true });
+        const wantHumanSlug = humanSlug(opts.provider);
+        const providerMatch = active.find((c) => bareProvider(c.provider).toLowerCase() === want || c.provider.toLowerCase() === want);
+        if (providerMatch)
+            return providerMatch;
+        const displayNameMatch = active.find((c) => c.installation?.displayName?.trim().toLowerCase() === want);
+        if (displayNameMatch)
+            return displayNameMatch;
+        const aliasMatches = wantHumanSlug
+            ? active.filter((c) => {
+                const displayName = c.installation?.displayName;
+                const displayNameSlug = displayName ? humanSlug(displayName) : "";
+                return displayNameSlug !== "" && displayNameSlug === wantHumanSlug;
+            })
+            : [];
+        if (aliasMatches.length === 1)
+            return aliasMatches[0];
+        if (aliasMatches.length > 1) {
+            throw new IntegrationsCliError(`Display-name alias '${opts.provider}' matches multiple connected apps. Use --connection to choose one.`, { expected: true });
         }
-        return match;
+        const available = active.map((c) => bareProvider(c.provider)).join(", ");
+        throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
+            (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps with `hq integrations connect <app>`."), { expected: true });
     }
     if (active.length === 1)
         return active[0];

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

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import { type McpManifest } from "./mcp-registration.js";
+export type DesktopConnector = McpManifest & {
+    [key: string]: unknown;
+};
+export type ImportStatus = "imported" | "needs-signin" | "shared-for-local" | "skipped";
+export interface ImportOutcome {
+    name: string;
+    status: ImportStatus;
+    reason?: string;
+    provider?: string;
+    path?: string;
+    installCommand?: string;
+    authorizationUrl?: string;
+    redactedArgumentCredentials?: boolean;
+}
+/** Claude Desktop's documented connector-config location for the current OS. */
+export declare function claudeDesktopConfigPath(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string;
+/** Read only the supported Claude Desktop `mcpServers` object. */
+export declare function readClaudeDesktopConnectors(configPath?: string): Record<string, DesktopConnector>;
+/** Never persist local desktop credentials in a company-synced connector file. */
+export declare function stripConnectorSecrets(entry: DesktopConnector): McpManifest;
+export declare function registerImportCommands(integrations: Command): void;
+//# sourceMappingURL=integrations-import.d.ts.map

package/dist/commands/integrations-import.js

@@ -0,0 +1,364 @@
+/**
+ * Import Claude Desktop MCP connectors into an HQ company.
+ *
+ * Remote servers are handed to integration-factory; stdio servers remain local
+ * and are shared as secret-stripped manifests for each teammate to install.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import chalk from "chalk";
+import { ensureCognitoIdToken, ensureCognitoToken, resolveDefaultHqRoot } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { bareProvider, IntegrationsCliError, printJson } from "./integrations-core.js";
+import { installIntegration, startOAuth } from "./integrations-api.js";
+import { loadRevealedSecrets } from "./secrets.js";
+import { registerServer } from "./mcp-registration.js";
+const OAUTH_REQUIRED_CODE = "INTEGRATION_FACTORY_OAUTH_REQUIRED";
+/** Claude Desktop's documented connector-config location for the current OS. */
+export function claudeDesktopConfigPath(platform = process.platform, home = os.homedir(), env = process.env) {
+    if (platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (platform === "win32") {
+        const appData = env.APPDATA?.trim();
+        return path.join(appData || path.join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    }
+    return path.join(home, ".config", "Claude", "claude_desktop_config.json");
+}
+/** Read only the supported Claude Desktop `mcpServers` object. */
+export function readClaudeDesktopConnectors(configPath = claudeDesktopConfigPath()) {
+    if (!fs.existsSync(configPath))
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new IntegrationsCliError(`Could not parse Claude Desktop connector config at ${configPath}: ${message}`, {
+            expected: true,
+        });
+    }
+    if (!parsed || typeof parsed !== "object")
+        return {};
+    const servers = parsed.mcpServers;
+    if (!servers || typeof servers !== "object" || Array.isArray(servers))
+        return {};
+    return Object.fromEntries(Object.entries(servers).filter((entry) => Boolean(entry[1]) && typeof entry[1] === "object" && !Array.isArray(entry[1])));
+}
+function selectedNames(value) {
+    if (value === undefined)
+        return undefined;
+    const names = value.split(",").map((name) => name.trim()).filter(Boolean);
+    if (names.length === 0) {
+        throw new IntegrationsCliError("--only needs at least one connector name.", { expected: true });
+    }
+    return new Set(names);
+}
+function providerSlug(name) {
+    const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return slug || "desktop-mcp";
+}
+function safeConnectorName(name) {
+    return /^[a-z0-9_-]+$/.test(name) ? name : null;
+}
+function secretReference(name) {
+    const normalized = name.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+    const resolverSafe = /^[A-Z]/.test(normalized) ? normalized : `SECRET_${normalized.replace(/^_+/, "")}`;
+    return `\${secret:${resolverSafe || "CONNECTOR_SECRET"}}`;
+}
+const CREDENTIAL_ARGUMENT_FLAG = /^(?:--)?(?:api[-_]?key|token|password|secret|apikey|auth|bearer|client[-_]?secret)$/i;
+function argumentSecretName(flag) {
+    return flag.replace(/^--?/, "").toUpperCase().replace(/[^A-Z0-9]+/g, "_") || "ARGUMENT_SECRET";
+}
+/** Redact explicit credential flags and standalone token-shaped argument values. */
+function redactConnectorArguments(args) {
+    let redacted = false;
+    const clean = args.map((arg, index) => {
+        const [flag, inlineValue] = arg.split("=", 2);
+        if (CREDENTIAL_ARGUMENT_FLAG.test(flag)) {
+            redacted = true;
+            return inlineValue === undefined ? arg : `${flag}=${secretReference(argumentSecretName(flag))}`;
+        }
+        if (index > 0 && CREDENTIAL_ARGUMENT_FLAG.test(args[index - 1])) {
+            redacted = true;
+            return secretReference(argumentSecretName(args[index - 1]));
+        }
+        // Avoid treating package names and URLs as tokens, but err on the side of
+        // safety for opaque, mixed-character strings commonly used as credentials.
+        if (!arg.startsWith("-") && !/[/@:]/.test(arg) && arg.length >= 16 && /[A-Za-z]/.test(arg) && /\d/.test(arg)) {
+            redacted = true;
+            return secretReference("ARGUMENT_SECRET");
+        }
+        return arg;
+    });
+    return { args: clean, redacted };
+}
+function connectorArguments(entry) {
+    return Array.isArray(entry.args) && entry.args.every((arg) => typeof arg === "string") ? entry.args : [];
+}
+function hasRedactedArgumentCredentials(entry) {
+    return redactConnectorArguments(connectorArguments(entry)).redacted;
+}
+/** Never persist local desktop credentials in a company-synced connector file. */
+export function stripConnectorSecrets(entry) {
+    const stringMap = (value) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        const clean = Object.entries(value).filter((pair) => typeof pair[1] === "string")
+            .map(([key]) => [key, secretReference(key)]);
+        return clean.length > 0 ? Object.fromEntries(clean) : undefined;
+    };
+    const args = redactConnectorArguments(connectorArguments(entry)).args;
+    return {
+        type: typeof entry.command === "string" ? "stdio" : entry.type,
+        ...(typeof entry.command === "string" ? { command: entry.command } : {}),
+        ...(typeof entry.url === "string" ? { url: entry.url } : {}),
+        ...(typeof entry.command === "string" ? { args } : {}),
+        ...(stringMap(entry.env) ? { env: stringMap(entry.env) } : {}),
+        ...(stringMap(entry.headers) ? { headers: stringMap(entry.headers) } : {}),
+    };
+}
+function isLocal(entry) {
+    return typeof entry.command === "string";
+}
+function isRemote(entry) {
+    return typeof entry.url === "string";
+}
+function staticCredential(entry) {
+    if (!entry.headers || typeof entry.headers !== "object" || Array.isArray(entry.headers))
+        return undefined;
+    for (const [key, raw] of Object.entries(entry.headers)) {
+        if (typeof raw !== "string" || raw.trim() === "")
+            continue;
+        if (!/(authorization|api[-_]?key|token|secret)/i.test(key))
+            continue;
+        if (/^authorization$/i.test(key) && /^Bearer\s+/i.test(raw)) {
+            return { value: raw.replace(/^Bearer\s+/i, "").trim() };
+        }
+        return { value: raw.trim(), authScheme: { placement: "header", header: key } };
+    }
+    return undefined;
+}
+function oauthRequired(error) {
+    return error instanceof IntegrationsCliError &&
+        (error.code === OAUTH_REQUIRED_CODE || error.oauthProtected === true);
+}
+function reconnectCommand(name, provider) {
+    return `hq integrations reconnect ${name} --provider ${bareProvider(provider)}`;
+}
+function connectorPath(hqRoot, company, name) {
+    return path.join(hqRoot, "companies", company, "settings", "connectors", `${name}.json`);
+}
+/**
+ * The API's default-company resolver returns a UID, while the synced on-disk
+ * layout is deliberately slug-addressed. Read the same active membership set
+ * to retain its canonical slug instead of inventing a folder from an ID.
+ */
+async function companyFolderSlug(token, companyUid) {
+    const response = await vaultApiFetch({ token, path: "/membership/me" });
+    if (!response.ok) {
+        throw new IntegrationsCliError("Could not resolve the active company's slug for the shared connector folder.", {
+            expected: true,
+        });
+    }
+    const body = (await response.json());
+    const membership = body.memberships?.find((candidate) => candidate.status === "active" && candidate.companyUid === companyUid);
+    const folderSlug = membership?.companyFolderSlug ?? membership?.companySlug;
+    if (!folderSlug) {
+        throw new IntegrationsCliError("The active company has no slug. Re-run with --company <slug> to choose the shared connector folder.", { expected: true });
+    }
+    return folderSlug;
+}
+function writeLocalConnector(hqRoot, company, name, entry) {
+    const target = connectorPath(hqRoot, company, name);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, `${JSON.stringify(stripConnectorSecrets(entry), null, 2)}\n`, { mode: 0o600 });
+    return target;
+}
+async function importRemote(token, companyUid, name, entry, dryRun) {
+    const provider = providerSlug(name);
+    if (dryRun)
+        return { name, status: "imported", reason: "would connect remote MCP endpoint", provider };
+    const credential = staticCredential(entry);
+    try {
+        const result = await installIntegration(token, companyUid, {
+            mcpUrl: entry.url,
+            provider,
+            displayName: name,
+            ...(credential ? { authMode: "bearer", bearerToken: credential.value, ...(credential.authScheme ? { authScheme: credential.authScheme } : {}) } : {}),
+        });
+        const resultProvider = bareProvider(result.connection.provider);
+        if (result.installation.status === "needs_credentials" || result.credential?.configured === false) {
+            return {
+                name,
+                status: "needs-signin",
+                provider: resultProvider,
+                reason: reconnectCommand(name, resultProvider),
+            };
+        }
+        return { name, status: "imported", provider: resultProvider };
+    }
+    catch (error) {
+        if (!oauthRequired(error))
+            throw error;
+        // Start the server-authoritative OAuth record but deliberately do not open a
+        // browser: a Desktop session cannot be transferred headlessly to HQ cloud.
+        const pending = await startOAuth(token, companyUid, {
+            mcpUrl: entry.url,
+            provider,
+            displayName: name,
+        });
+        return {
+            name,
+            status: "needs-signin",
+            provider: bareProvider(pending.provider),
+            reason: reconnectCommand(name, pending.provider),
+            authorizationUrl: pending.authorizationUrl,
+        };
+    }
+}
+function renderOutcomes(outcomes) {
+    console.log("Connector                 Outcome             Details");
+    for (const outcome of outcomes) {
+        console.log(`${outcome.name.padEnd(25)} ${outcome.status.padEnd(19)} ${outcome.reason ?? outcome.path ?? ""}`);
+    }
+    for (const outcome of outcomes.filter((item) => item.status === "shared-for-local")) {
+        console.log(chalk.dim(`  Shared manifest: ${outcome.path}`));
+        console.log(chalk.dim(`  Teammate install: ${outcome.installCommand}`));
+    }
+    if (outcomes.some((item) => item.status === "shared-for-local")) {
+        console.log(chalk.yellow("  Local connector credentials were replaced with ${secret:ENV_NAME}. Set them with `hq secrets` before installing."));
+    }
+    if (outcomes.some((item) => item.redactedArgumentCredentials)) {
+        console.log(chalk.yellow("  Local connector argument credentials were replaced with ${secret:FLAG_NAME}. Set them with `hq secrets` before installing."));
+    }
+    for (const outcome of outcomes.filter((item) => item.status === "needs-signin")) {
+        console.log(chalk.yellow(`  ${outcome.name} needs sign-in: ${outcome.reason}`));
+        if (outcome.authorizationUrl)
+            console.log(chalk.yellow(`  Open this URL to sign in:\n  ${outcome.authorizationUrl}`));
+    }
+}
+export function registerImportCommands(integrations) {
+    integrations
+        .command("import")
+        .description("Import Claude Desktop connectors into company Integrations")
+        .option("--company <slug>", "Company slug (defaults to your single active company)")
+        .option("--dry-run", "Detect and classify connectors without writing or connecting")
+        .option("--only <name[,name...]>", "Import only these Claude Desktop connector names")
+        .option("--json", "Machine-readable per-connector outcomes")
+        .option("--config <path>", "Claude Desktop config path (defaults to this OS's standard location)")
+        .action(async (opts) => {
+        const configPath = opts.config ?? claudeDesktopConfigPath();
+        const connectors = readClaudeDesktopConnectors(configPath);
+        const only = selectedNames(opts.only);
+        const entries = Object.entries(connectors).filter(([name]) => !only || only.has(name));
+        if (entries.length === 0) {
+            if (opts.json) {
+                printJson([]);
+            }
+            else {
+                console.log(`No Claude Desktop connectors found at ${configPath}`);
+            }
+            return;
+        }
+        const token = await ensureCognitoIdToken();
+        // getCompanyUid owns the single-membership fallback and multi-company
+        // disambiguation, exactly like every other integrations verb.
+        const companyUid = await getCompanyUid(token, opts.company);
+        const outcomes = [];
+        let company;
+        let hqRoot;
+        const localCompany = async () => company ??= await companyFolderSlug(token, companyUid);
+        const localHqRoot = () => hqRoot ??= resolveDefaultHqRoot({ onMissing: "throw" });
+        const normalizedNames = new Map();
+        for (const [name] of entries) {
+            if (!safeConnectorName(name))
+                continue;
+            const provider = providerSlug(name);
+            normalizedNames.set(provider, [...(normalizedNames.get(provider) ?? []), name]);
+        }
+        for (const [name, entry] of entries) {
+            const safeName = safeConnectorName(name);
+            if (!safeName) {
+                outcomes.push({ name, status: "skipped", reason: "name must use lowercase letters, digits, _ or -" });
+                continue;
+            }
+            const collisions = normalizedNames.get(providerSlug(name)) ?? [];
+            if (collisions.length > 1) {
+                outcomes.push({
+                    name,
+                    status: "skipped",
+                    reason: `normalized provider name '${providerSlug(name)}' collides with ${collisions.filter((other) => other !== name).join(", ")}`,
+                });
+                continue;
+            }
+            if (isLocal(entry)) {
+                const resolvedCompany = await localCompany();
+                const target = connectorPath(localHqRoot(), resolvedCompany, safeName);
+                outcomes.push({
+                    name,
+                    status: "shared-for-local",
+                    ...(opts.dryRun ? { reason: "would write secret-stripped local manifest" } : { path: writeLocalConnector(localHqRoot(), resolvedCompany, safeName, entry) }),
+                    installCommand: `hq integrations install-local ${safeName} --company ${resolvedCompany}`,
+                    ...(hasRedactedArgumentCredentials(entry) ? { redactedArgumentCredentials: true } : {}),
+                });
+                // Keep dry-run output useful without leaking a filesystem write target.
+                if (opts.dryRun)
+                    outcomes[outcomes.length - 1].path = target;
+                continue;
+            }
+            if (isRemote(entry) && typeof entry.url === "string") {
+                outcomes.push(await importRemote(token, companyUid, name, entry, Boolean(opts.dryRun)));
+                continue;
+            }
+            outcomes.push({ name, status: "skipped", reason: "unsupported MCP entry (expected command for local stdio or url for remote MCP)" });
+        }
+        if (opts.json)
+            printJson(outcomes);
+        else
+            renderOutcomes(outcomes);
+    });
+    integrations
+        .command("install-local <name>")
+        .description("Register a company-shared local connector in this machine's Claude/Codex MCP config")
+        .option("--company <slug>", "Company slug (defaults to your single active company)")
+        .option("--json", "Machine-readable registration result")
+        .action(async (name, opts) => {
+        const safeName = safeConnectorName(name);
+        if (!safeName) {
+            throw new IntegrationsCliError("Connector name must use lowercase letters, digits, _ or -.", { expected: true });
+        }
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(token, opts.company);
+        const company = await companyFolderSlug(token, companyUid);
+        const hqRoot = resolveDefaultHqRoot({ onMissing: "throw" });
+        const manifestPath = connectorPath(hqRoot, company, safeName);
+        if (!fs.existsSync(manifestPath)) {
+            throw new IntegrationsCliError(`Shared connector not found: ${manifestPath}`, { expected: true });
+        }
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new IntegrationsCliError(`Could not parse shared connector ${manifestPath}: ${message}`, { expected: true });
+        }
+        const secretNames = [...Object.values({ ...(manifest.env ?? {}), ...(manifest.headers ?? {}) }), ...(manifest.args ?? [])]
+            .flatMap((value) => [...value.matchAll(/\$\{secret:([A-Z][A-Z0-9_]*(?:\/[A-Z][A-Z0-9_]*)*)\}/g)].map((match) => match[1]));
+        const secrets = await loadRevealedSecrets(token, companyUid, secretNames);
+        const result = registerServer({
+            name: safeName,
+            manifest,
+            pack: `company-${company}-connectors`,
+            resolveSecret: (secret) => secrets.get(secret) ?? null,
+        });
+        if (opts.json)
+            printJson(result);
+        else
+            console.log(`Registered ${safeName} in local MCP config (Claude${"skipped" in result.codex ? "; Codex not installed" : " and Codex"}).`);
+    });
+}
+//# sourceMappingURL=integrations-import.js.map

package/dist/commands/integrations.d.ts

@@ -14,6 +14,7 @@
  *   hq integrations discover <docsUrl>       Find a server from its docs page.
  *   hq integrations connect <app>            Connect it (no-auth, key, OAuth).
  *   hq integrations reconnect [app]          Re-authenticate a broken app.
+ *   hq integrations import                   Import Claude Desktop connectors.
  *
  * Use:
  *   hq integrations list --company indigo    Connected apps for a company.

package/dist/commands/integrations.js

@@ -14,6 +14,7 @@
  *   hq integrations discover <docsUrl>       Find a server from its docs page.
  *   hq integrations connect <app>            Connect it (no-auth, key, OAuth).
  *   hq integrations reconnect [app]          Re-authenticate a broken app.
+ *   hq integrations import                   Import Claude Desktop connectors.
  *
  * Use:
  *   hq integrations list --company indigo    Connected apps for a company.
@@ -51,8 +52,40 @@ import { ensureCognitoIdToken } from "../utils/cognito-session.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { IntegrationsCliError, bareProvider, callGateway, fetchConnections, isClientError, printJson, raiseIfUnauthorized, raiseIfUpstreamUnavailable, gatewayResultIsError, selectConnection, toolPrefixForProvider, unwrapGatewayResult, queuedOutcome, } from "./integrations-core.js";
 import { registerConnectCommands } from "./integrations-connect.js";
+import { registerImportCommands } from "./integrations-import.js";
 import { registerManageCommands } from "./integrations-manage.js";
 export { IntegrationsCliError, callGateway, fetchConnections, queuedOutcome, selectConnection, toolPrefixForProvider, unwrapGatewayResult, } from "./integrations-core.js";
+/**
+ * The gateway relays MCP tool schemas verbatim. Keep the default listing
+ * compact, but make required inputs visible before a caller has to discover
+ * them through a validation error.
+ */
+function requiredInputHint(inputSchema) {
+    if (!inputSchema || typeof inputSchema !== "object")
+        return null;
+    const required = inputSchema.required;
+    if (!Array.isArray(required))
+        return null;
+    const names = required.filter((name) => typeof name === "string");
+    return names.length > 0 ? `requires: ${names.join(", ")}` : null;
+}
+/** The user-facing slug stays first; the factory's display name is additive. */
+function connectionLabel(connection) {
+    const slug = bareProvider(connection.provider);
+    const displayName = connection.installation?.displayName?.trim();
+    return displayName && displayName.toLowerCase() !== slug.toLowerCase()
+        ? `${slug} (${displayName})`
+        : slug;
+}
+function printToolSchema(tool) {
+    if (tool.inputSchema === undefined) {
+        console.log(chalk.dim("  Input schema was not reported by this app."));
+        return;
+    }
+    const schema = JSON.stringify(tool.inputSchema, null, 2);
+    console.log(chalk.dim("  Input schema:"));
+    console.log(chalk.dim(schema.split("\n").map((line) => `  ${line}`).join("\n")));
+}
 export function registerIntegrationsCommand(program) {
     const integrations = program
         .command("integrations")
@@ -75,7 +108,6 @@ export function registerIntegrationsCommand(program) {
             return;
         }
         for (const c of connections) {
-            const name = c.installation?.displayName ?? bareProvider(c.provider);
             const flags = [
                 c.status,
                 c.writePolicy ? `writes: ${c.writePolicy}` : null,
@@ -83,16 +115,18 @@ export function registerIntegrationsCommand(program) {
             ]
                 .filter(Boolean)
                 .join(" · ");
-            console.log(`${chalk.bold(name)}  (${bareProvider(c.provider)})  ${chalk.dim(flags)}`);
+            console.log(`${chalk.bold(connectionLabel(c))}  ${chalk.dim(flags)}`);
             console.log(chalk.dim(`  connection: ${c.id}`));
         }
     });
+    registerImportCommands(integrations);
     integrations
         .command("tools")
         .description("List what a connected app can do")
         .option("--provider <slug>", "Connected app (e.g. linear)")
         .option("--connection <id>", "Connection id (acct_…)")
         .option("--company <slug>", "Company slug, e.g. indigo")
+        .option("--describe <tool>", "Print the full input schema for one tool")
         .option("--json", "Machine-readable output")
         .action(async (opts) => {
         const token = await ensureCognitoIdToken();
@@ -105,20 +139,41 @@ export function registerIntegrationsCommand(program) {
             arguments: { companyUid, connectionId: connection.id },
         });
         const payload = unwrapGatewayResult(message.result);
-        if (opts.json) {
-            printJson(payload);
-            return;
-        }
         const tools = payload?.tools ?? [];
         if (tools.length === 0) {
+            if (opts.json) {
+                printJson(payload);
+                return;
+            }
             console.log("The app reported no tools.");
             return;
         }
+        if (opts.describe) {
+            const tool = tools.find((candidate) => candidate.name === opts.describe);
+            if (!tool) {
+                throw new IntegrationsCliError(`No tool named '${opts.describe}' on ${connectionLabel(connection)}.`, { expected: true });
+            }
+            if (opts.json) {
+                printJson(tool);
+                return;
+            }
+            console.log(`${chalk.bold(tool.name)}  ${chalk.dim(`on ${connectionLabel(connection)}`)}`);
+            if (tool.description)
+                console.log(chalk.dim(`  ${tool.description}`));
+            printToolSchema(tool);
+            return;
+        }
+        if (opts.json) {
+            printJson(payload);
+            return;
+        }
+        console.log(chalk.dim(`App: ${connectionLabel(connection)}`));
         for (const tool of tools) {
             const label = tool.title && tool.title !== tool.name ? `  ${chalk.dim(tool.title)}` : "";
-            console.log(`${chalk.bold(tool.name)}${label}`);
+            const required = requiredInputHint(tool.inputSchema);
+            console.log(`${chalk.bold(tool.name)}${label}${required ? `  ${chalk.dim(required)}` : ""}`);
         }
-        console.log(chalk.dim(`\n${tools.length} tools. Call one with: hq integrations call <tool> --provider ${bareProvider(connection.provider)} --args '<json>'`));
+        console.log(chalk.dim(`\n${tools.length} tools. Describe inputs: hq integrations tools --provider ${bareProvider(connection.provider)} --describe <tool>\nCall one with: hq integrations call <tool> --provider ${bareProvider(connection.provider)} --args '<json>'`));
     });
     integrations
         .command("call <tool>")

package/dist/commands/mcp-registration.d.ts

@@ -471,7 +471,7 @@ export declare const claudeConfigFormat: ConfigFormat<Record<string, unknown>>;
 /**
  * Build the Claude server definition emitted into `mcpServers.<name>` from a
  * manifest: pass the transport fields through, resolve `${secret:}` in every
- * header/env value (recording the plaintexts in `secretSink` for redaction), and
+ * argument/header/env value (recording the plaintexts in `secretSink` for redaction), and
  * stamp `_hqPack` provenance. The output object's key order is deterministic so a
  * re-run produces a byte-identical def (idempotency depends on stable serialize).
  */
@@ -673,7 +673,7 @@ export declare const codexConfigFormat: ConfigFormat<CodexTomlDoc>;
 export declare function appendCodexTable(originalText: string, name: string, def: TomlTable): string;
 /**
  * Build the Codex server table emitted as `[mcp_servers.<name>]`: pass the
- * transport fields through, resolve `${secret:}` in every header/env value
+ * transport fields through, resolve `${secret:}` in every argument/header/env value
  * (recording plaintexts in `secretSink` for redaction), stamp `_hqPack` provenance,
  * and write the per-tool `approval_mode` from the manifest where present (the Codex-
  * specific field — `[mcp_servers.<name>.tools.<t>]` with `approval_mode = "…"`).

package/dist/commands/mcp-registration.js

@@ -934,7 +934,7 @@ export const claudeConfigFormat = {
 /**
  * Build the Claude server definition emitted into `mcpServers.<name>` from a
  * manifest: pass the transport fields through, resolve `${secret:}` in every
- * header/env value (recording the plaintexts in `secretSink` for redaction), and
+ * argument/header/env value (recording the plaintexts in `secretSink` for redaction), and
  * stamp `_hqPack` provenance. The output object's key order is deterministic so a
  * re-run produces a byte-identical def (idempotency depends on stable serialize).
  */
@@ -944,8 +944,9 @@ export function buildClaudeServerDef(manifest, pack, resolve, secretSink) {
         def.url = manifest.url;
     if (manifest.command !== undefined)
         def.command = manifest.command;
-    if (manifest.args !== undefined)
-        def.args = manifest.args;
+    if (manifest.args !== undefined) {
+        def.args = manifest.args.map((arg) => resolveSecretRefs(arg, resolve, secretSink));
+    }
     if (manifest.headers !== undefined) {
         def.headers = resolveStringMap(manifest.headers, resolve, secretSink);
     }
@@ -1371,7 +1372,7 @@ export function appendCodexTable(originalText, name, def) {
 }
 /**
  * Build the Codex server table emitted as `[mcp_servers.<name>]`: pass the
- * transport fields through, resolve `${secret:}` in every header/env value
+ * transport fields through, resolve `${secret:}` in every argument/header/env value
  * (recording plaintexts in `secretSink` for redaction), stamp `_hqPack` provenance,
  * and write the per-tool `approval_mode` from the manifest where present (the Codex-
  * specific field — `[mcp_servers.<name>.tools.<t>]` with `approval_mode = "…"`).
@@ -1384,8 +1385,9 @@ export function buildCodexServerDef(manifest, pack, resolve, secretSink) {
         def.url = manifest.url;
     if (manifest.command !== undefined)
         def.command = manifest.command;
-    if (manifest.args !== undefined)
-        def.args = manifest.args;
+    if (manifest.args !== undefined) {
+        def.args = manifest.args.map((arg) => resolveSecretRefs(arg, resolve, secretSink));
+    }
     if (manifest.headers !== undefined) {
         def.headers = resolveStringMap(manifest.headers, resolve, secretSink);
     }

package/dist/utils/vault-api.d.ts

@@ -34,6 +34,18 @@ export interface VaultApiOptions {
  * network call; this stays the backstop for a new call site that forgets to.
  */
 export declare function rewritePathForApiKey(path: string): string | null;
+/**
+ * Client-family identifier sent on every authenticated vault-API request.
+ *
+ * hq-pro reads this exact header into its closed `RosterClientFamily` enum
+ * (`roster-client-family.ts`) and tags each agents-request Sentry event with it
+ * (`handler.ts` setSentryClientFamily). Sending it means an event this CLI
+ * raises reads `hq_client=hq_cli` and names its origin instead of `absent` — the
+ * missing attribution behind Sentry hq-pro 7617401436. It is a fixed literal,
+ * never caller-supplied text, used only for telemetry/attribution: no
+ * authorization or request signing depends on it.
+ */
+export declare const HQ_CLIENT_NAME = "@indigoai-us/hq-cli";
 export declare function vaultApiFetch(opts: VaultApiOptions): Promise<Response>;
 /**
  * Public (NONE-auth) GET against the vault API — no bearer token. The

package/dist/utils/vault-api.js

@@ -124,6 +124,18 @@ export function rewritePathForApiKey(path) {
     }
     return null;
 }
+/**
+ * Client-family identifier sent on every authenticated vault-API request.
+ *
+ * hq-pro reads this exact header into its closed `RosterClientFamily` enum
+ * (`roster-client-family.ts`) and tags each agents-request Sentry event with it
+ * (`handler.ts` setSentryClientFamily). Sending it means an event this CLI
+ * raises reads `hq_client=hq_cli` and names its origin instead of `absent` — the
+ * missing attribution behind Sentry hq-pro 7617401436. It is a fixed literal,
+ * never caller-supplied text, used only for telemetry/attribution: no
+ * authorization or request signing depends on it.
+ */
+export const HQ_CLIENT_NAME = "@indigoai-us/hq-cli";
 export async function vaultApiFetch(opts) {
     let path = opts.path;
     if (opts.token.startsWith("hqk_")) {
@@ -156,6 +168,7 @@ export async function vaultApiFetch(opts) {
             headers: {
                 Authorization: `Bearer ${opts.token}`,
                 'Content-Type': 'application/json',
+                'x-hq-client-name': HQ_CLIENT_NAME,
             },
             body: opts.body ? JSON.stringify(opts.body) : undefined,
             signal: opts.signal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.103.19",
+  "version": "5.103.21",
   "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.30",
+    "@indigoai-us/hq-cloud": "~6.15.37",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "@tobilu/qmd": "2.5.3",