@indigoai-us/hq-cli 5.345.92 → 5.345.94

package/dist/commands/integrations-connect.js

@@ -305,6 +305,57 @@ async function resolveKey(opts, appLabel) {
     }
     throw new IntegrationsCliError(`${appLabel} needs an API key. Pass it with --token-stdin (recommended, keeps it out of shell history) or --token <key>.`, { expected: true });
 }
+/**
+ * Remote MCP endpoints the integrations.sh catalog lists as MCP without a URL.
+ *
+ * Gmail's documented server is `https://gmailmcp.googleapis.com/mcp/v1`
+ * (Google Workspace "Configure the Gmail MCP server"). Catalog connect and
+ * reconnect otherwise POST domain/query, and hq-pro throws
+ * FactoryInstallationUnsupported — printed as a failure that still exited 0
+ * when the command returned instead of throwing.
+ */
+const DOCUMENTED_REMOTE_MCP_BY_DOMAIN = {
+    "gmail.com": { mcpUrl: "https://gmailmcp.googleapis.com/mcp/v1" },
+};
+function documentedRemoteMcp(domainOrName) {
+    const want = domainOrName?.trim().toLowerCase() ?? "";
+    if (!want)
+        return undefined;
+    const direct = DOCUMENTED_REMOTE_MCP_BY_DOMAIN[want];
+    if (direct)
+        return { mcpUrl: direct.mcpUrl, domain: want };
+    for (const [domain, overlay] of Object.entries(DOCUMENTED_REMOTE_MCP_BY_DOMAIN)) {
+        if (domainLabel(domain) === want)
+            return { mcpUrl: overlay.mcpUrl, domain };
+    }
+    return undefined;
+}
+/**
+ * When the catalog names an MCP app but has no server URL, use the documented
+ * endpoint and drop catalog/query handles so hq-pro takes the direct `mcpUrl`
+ * path. Keep `domain` + `provider` so a revoked factory:gmail row is revived
+ * instead of creating a second connection keyed on gmailmcp.googleapis.com.
+ */
+function withDocumentedRemoteMcp(target, domainHint) {
+    if (target.ref.mcpUrl || target.ref.discoveryReceiptId)
+        return target;
+    const overlay = documentedRemoteMcp(domainHint) ?? documentedRemoteMcp(target.ref.domain);
+    if (!overlay)
+        return target;
+    return {
+        ...target,
+        ref: {
+            mcpUrl: overlay.mcpUrl,
+            domain: overlay.domain,
+            provider: target.ref.provider ?? domainLabel(overlay.domain),
+            displayName: target.ref.displayName ?? target.label,
+        },
+    };
+}
+function unsupportedCatalogSurfaceError(label, cause) {
+    return new IntegrationsCliError(`${label} cannot be connected because the app catalog has no MCP server URL. ` +
+        "Re-run with --mcp-url <endpoint> (find it with `hq integrations inspect`).", { expected: true, status: cause.status, code: cause.code });
+}
 /**
  * Turn the caller's arguments into one unambiguous target. Precedence is
  * most-specific-first so an explicit flag always wins over the positional
@@ -354,13 +405,13 @@ async function resolveTarget(token, companyUid, app, opts, preserveDomain = fals
             // hq-pro. A catalog entry id is useful auth metadata, but replacing the
             // domain with it can create a distinct connection instead of reviving
             // the original acct_ row.
-            return {
+            return withDocumentedRemoteMcp({
                 ref: { domain: app },
                 ...(match?.authClass ? { authClass: match.authClass } : {}),
                 label: redactUrlsInText(match?.name || app),
-            };
+            }, app);
         }
-        return catalogEntryToTarget(match, { ref: { domain: app }, label: redactUrlsInText(app) });
+        return withDocumentedRemoteMcp(catalogEntryToTarget(match, { ref: { domain: app }, label: redactUrlsInText(app) }), match?.domain ?? app);
     }
     // A bare name (`notion`, `atlassian`) is how the catalog reads to a person —
     // the rows are titled `notion.com`, `atlassian.com`. Resolve it to that row
@@ -370,9 +421,9 @@ async function resolveTarget(token, companyUid, app, opts, preserveDomain = fals
     // unmatched → fall back to the server-side query resolver.
     const named = await findCatalogEntryByName(token, companyUid, app);
     if (named) {
-        return catalogEntryToTarget(named, { ref: { query: app }, label: redactUrlsInText(app) });
+        return withDocumentedRemoteMcp(catalogEntryToTarget(named, { ref: { query: app }, label: redactUrlsInText(app) }), named.domain);
     }
-    return { ref: { query: app }, label: redactUrlsInText(app) };
+    return withDocumentedRemoteMcp({ ref: { query: app }, label: redactUrlsInText(app) }, app);
 }
 /**
  * Turn a matched catalog entry into a connect target, preferring its opaque
@@ -1065,6 +1116,10 @@ async function connectApp(token, companyUid, app, opts, expectedRevivedConnectio
             }
             return;
         }
+        if (err instanceof IntegrationsCliError &&
+            err.code === "INTEGRATION_FACTORY_UNSUPPORTED_SURFACE") {
+            throw unsupportedCatalogSurfaceError(target.label, err);
+        }
         throw err;
     }
 }
@@ -1407,6 +1462,10 @@ export function registerConnectCommands(integrations) {
                     reportInstall(result, opts);
                 return;
             }
+            if (err instanceof IntegrationsCliError &&
+                err.code === "INTEGRATION_FACTORY_UNSUPPORTED_SURFACE") {
+                throw unsupportedCatalogSurfaceError(target.label, err);
+            }
             throw err;
         }
     });

package/dist/commands/lanes-accounts.d.ts

@@ -12,6 +12,7 @@ export declare function createLaneAccountsHandlers(deps: LaneAccountsHandlerDeps
         home?: string;
         deviceAuth?: boolean;
         company?: string;
+        capacityOnly?: boolean;
     }) => Promise<void>;
     runAccountsSetHome: (ctx: Ctx, providerRaw: string, accountIdRaw: string, homeRaw: string, opts: {
         host?: string;

package/dist/commands/lanes-accounts.js

@@ -8,6 +8,7 @@ import { AccountResolutionError, DEFAULT_ACCOUNT_HOMES, LANE_PROVIDERS, PROVIDER
 import { assertUniqueAccountHomes, providerCompactAfterMs } from "../lib/lanes/config.js";
 import { resolveLaneEffort } from "../lib/lanes/effort.js";
 import { LanesError } from "../lib/lanes/errors.js";
+import { CAPACITY_ONLY_REASON } from "../lib/capacity/accounts.js";
 import { accountQuotaView, clearAccountQuota, loadQuotaState } from "../lib/lanes/quota.js";
 import { resolveLaneModel } from "../lib/lanes/spawn.js";
 import { leadLaneIds } from "../lib/lanes/admission.js";
@@ -362,6 +363,11 @@ export function createLaneAccountsHandlers(deps) {
             }
         }
         delete nextAccount.disabled_reason;
+        if (opts.capacityOnly && registeredAccount?.enabled !== true) {
+            const prior = registeredAccount?.disabled_reason;
+            nextAccount.enabled = false;
+            nextAccount.disabled_reason = prior && prior !== CAPACITY_ONLY_REASON ? prior : CAPACITY_ONLY_REASON;
+        }
         assertUniqueAccountHomes(provider, {
             ...config.providers[provider].accounts,
             [id]: nextAccount,

package/dist/lib/bot/api.d.ts

@@ -249,12 +249,33 @@ export declare class BotApi {
      * (someone else does). Anything else throws.
      */
     claimChannelUnit(channelId: string, unitId: string): Promise<boolean>;
+    /**
+     * GET /v1/notify/channels/{id}/members — roster used to resolve `@Name`
+     * into structured mentions on a room post. Agents may read members of a
+     * channel they belong to (same gate as reading messages).
+     */
+    fetchChannelMembers(channelId: string): Promise<Array<{
+        personUid: string;
+        displayName?: string;
+        email?: string;
+        slug?: string;
+        handle?: string;
+    }>>;
     /** POST /v1/notify/channels/{id}/messages — post in a room as the bot. */
     sendChannelMessage(input: {
         channelId: string;
         body: string;
         rootEventId?: string;
         audience?: "human" | "agent" | "both";
+        /**
+         * Structured HQ mentions. The server never parses `@Name` from the body;
+         * without this array the addressed bot is not written to the agent inbox.
+         */
+        mentions?: ReadonlyArray<{
+            participantUid: string;
+            participantType: "agent" | "human";
+            displayName: string;
+        }>;
     }): Promise<{
         eventId?: string;
         createdAt?: string;

package/dist/lib/bot/api.js

@@ -192,6 +192,30 @@ export class BotApi {
             throw err;
         }
     }
+    /**
+     * GET /v1/notify/channels/{id}/members — roster used to resolve `@Name`
+     * into structured mentions on a room post. Agents may read members of a
+     * channel they belong to (same gate as reading messages).
+     */
+    async fetchChannelMembers(channelId) {
+        const { body } = await this.call(`/v1/notify/channels/${encodeURIComponent(channelId)}/members`);
+        const rows = Array.isArray(body.members) ? body.members : [];
+        const out = [];
+        for (const row of rows) {
+            if (typeof row.personUid !== "string" || !row.personUid.trim())
+                continue;
+            out.push({
+                personUid: row.personUid.trim(),
+                ...(typeof row.displayName === "string" && row.displayName.trim()
+                    ? { displayName: row.displayName.trim() }
+                    : {}),
+                ...(typeof row.email === "string" && row.email.trim() ? { email: row.email.trim() } : {}),
+                ...(typeof row.slug === "string" && row.slug.trim() ? { slug: row.slug.trim() } : {}),
+                ...(typeof row.handle === "string" && row.handle.trim() ? { handle: row.handle.trim() } : {}),
+            });
+        }
+        return out;
+    }
     /** POST /v1/notify/channels/{id}/messages — post in a room as the bot. */
     async sendChannelMessage(input) {
         const payload = { body: input.body };
@@ -199,6 +223,8 @@ export class BotApi {
             payload.rootEventId = input.rootEventId;
         if (input.audience)
             payload.audience = input.audience;
+        if (input.mentions && input.mentions.length > 0)
+            payload.mentions = input.mentions;
         const { body } = await this.call(`/v1/notify/channels/${encodeURIComponent(input.channelId)}/messages`, { method: "POST", body: payload });
         return body;
     }

package/dist/lib/bot/prompt.js

@@ -382,7 +382,8 @@ export function buildSystemPrompt(input) {
         `- \`agent\`: status pings, tool handoffs, and in-progress notes that only another agent needs to read.\n` +
         `- \`human\`: anything a person must read — answers, results, questions, summaries.\n` +
         `- \`both\`: when the content is relevant to both a person and a downstream agent.\n` +
-        `When unsure, use \`human\`. Progress messages sent before the final answer should use \`agent\`; the final answer should use \`human\`.`);
+        `When unsure, use \`human\`. Progress messages sent before the final answer should use \`agent\`; the final answer should use \`human\`.\n\n` +
+        `In a group room, write \`@Name\` to address another person or bot on the roster. That becomes a real mention and puts the post in the addressed bot's inbox. A room post that does not mention another bot does not wake that bot.`);
     return `${parts.join("\n\n")}\n`;
 }
 /**

package/dist/lib/bot/room-mentions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Best-effort structured mentions for a local bot's room post.
+ *
+ * HQ Rooms mentions are structured-only: the server never parses `@Name` out of
+ * the body. `hq dm` already resolves names against the roster and sends the
+ * `mentions` array. Bot room posts did not, so an addressed bot never got an
+ * inbox item (feedback #2774). Unknown or ambiguous `@` words are skipped so a
+ * model typo cannot swallow the visible reply; matched roster members become
+ * real mentions. The sender is never included.
+ */
+import { type ChannelMember } from "../../commands/dm.js";
+export type StructuredChannelMention = {
+    participantUid: string;
+    participantType: "agent" | "human";
+    displayName: string;
+};
+export declare function roomPostHasMentionTokens(body: string): boolean;
+export declare function resolveRoomMentionsForBot(args: {
+    body: string;
+    members: readonly ChannelMember[];
+    selfUid: string;
+}): {
+    body: string;
+    mentions: StructuredChannelMention[];
+};
+//# sourceMappingURL=room-mentions.d.ts.map

package/dist/lib/bot/room-mentions.js

@@ -0,0 +1,40 @@
+/**
+ * Best-effort structured mentions for a local bot's room post.
+ *
+ * HQ Rooms mentions are structured-only: the server never parses `@Name` out of
+ * the body. `hq dm` already resolves names against the roster and sends the
+ * `mentions` array. Bot room posts did not, so an addressed bot never got an
+ * inbox item (feedback #2774). Unknown or ambiguous `@` words are skipped so a
+ * model typo cannot swallow the visible reply; matched roster members become
+ * real mentions. The sender is never included.
+ */
+import { parseMentionTokens, resolveMentions, stripMentionQuotes, } from "../../commands/dm.js";
+export function roomPostHasMentionTokens(body) {
+    return parseMentionTokens(body).length > 0;
+}
+export function resolveRoomMentionsForBot(args) {
+    const tokens = parseMentionTokens(args.body);
+    if (tokens.length === 0)
+        return { body: args.body, mentions: [] };
+    const members = [...args.members];
+    const mentions = [];
+    const claimed = new Set();
+    for (const token of tokens) {
+        const resolved = resolveMentions([token], members);
+        if (!resolved.ok)
+            continue;
+        for (const mention of resolved.mentions) {
+            if (mention.participantUid === args.selfUid)
+                continue;
+            if (claimed.has(mention.participantUid))
+                continue;
+            claimed.add(mention.participantUid);
+            mentions.push(mention);
+        }
+    }
+    return {
+        body: mentions.length > 0 ? stripMentionQuotes(args.body) : args.body,
+        mentions,
+    };
+}
+//# sourceMappingURL=room-mentions.js.map

package/dist/lib/bot/run.js

@@ -73,6 +73,7 @@ import { appendDmHistory, dmHistoryHasModelThread, markDmHistoryModelTurn, readD
 import { attachmentTurnBlock, downloadTurnAttachments } from "./attachments.js";
 import { inboxEntryAttachments } from "../agent-kit/inbox-state.js";
 import { isAgentSender, isDmItem, isMetaNonReply, resolveReplyTarget } from "./room-policy.js";
+import { resolveRoomMentionsForBot, roomPostHasMentionTokens, } from "./room-mentions.js";
 import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
 import { botJobQuietOptionEnabled } from "./job-quiet-flag.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
@@ -755,6 +756,15 @@ export async function runBot(deps) {
         }
         return `${header}\n${recent}${from}: ${text}`;
     };
+    const channelMemberCache = new Map();
+    const loadChannelMembers = async (channelId) => {
+        const cached = channelMemberCache.get(channelId);
+        if (cached)
+            return cached;
+        const members = await api.fetchChannelMembers(channelId);
+        channelMemberCache.set(channelId, members);
+        return members;
+    };
     const rememberDm = (scope, message) => {
         if (!isDmSessionScope(scope))
             return;
@@ -1052,13 +1062,16 @@ export async function runBot(deps) {
         }
         await sendToTarget(target, notice.text, rootEventId, "human");
     };
-    const postOne = (target, body, rootEventId, audience) => {
+    const postOne = async (target, body, rootEventId, audience) => {
         const root = rootEventId ? { rootEventId } : {};
-        const send = target.kind === "dm"
-            ? api.sendDm({ toPersonUid: target.peerUid, body, ...root, ...(audience ? { audience } : {}) })
-            : api.sendChannelMessage({ channelId: target.channelId, body, ...root, ...(audience ? { audience } : {}) });
-        return send.then((posted) => {
-            if (target.kind === "dm" && audience !== "agent") {
+        if (target.kind === "dm") {
+            const posted = await api.sendDm({
+                toPersonUid: target.peerUid,
+                body,
+                ...root,
+                ...(audience ? { audience } : {}),
+            });
+            if (audience !== "agent") {
                 const eventId = posted && typeof posted === "object" && "eventId" in posted && typeof posted.eventId === "string"
                     ? posted.eventId
                     : undefined;
@@ -1072,6 +1085,31 @@ export async function runBot(deps) {
                 });
             }
             return posted;
+        }
+        let bodyToSend = body;
+        let mentions;
+        if (roomPostHasMentionTokens(body)) {
+            try {
+                const members = await loadChannelMembers(target.channelId);
+                const resolved = resolveRoomMentionsForBot({
+                    body,
+                    members,
+                    selfUid: config.agentUid,
+                });
+                bodyToSend = resolved.body;
+                if (resolved.mentions.length > 0)
+                    mentions = resolved.mentions;
+            }
+            catch (err) {
+                log("warn", `room mentions for ${target.channelId} unresolved: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        return api.sendChannelMessage({
+            channelId: target.channelId,
+            body: bodyToSend,
+            ...root,
+            ...(audience ? { audience } : {}),
+            ...(mentions ? { mentions } : {}),
         });
     };
     /**

package/dist/lib/capacity/accounts.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Capacity account list (US-011).
+ *
+ * The lane account registry plus each provider's default home. A missing
+ * config file is an empty registry: this module does not call
+ * documentedDefaultConfig, which would invent an enabled account "a".
+ */
+import { type LaneProvider, type LanesConfig } from "../lanes/types.js";
+export type CapacityAccountSource = "default" | "registry" | "host";
+export interface CapacityAccount {
+    provider: LaneProvider;
+    label: string;
+    home: string;
+    source: CapacityAccountSource;
+    /** False for a capacity-only account: read for usage, never used by lanes. */
+    lanes?: boolean;
+}
+/**
+ * `disabled_reason` that marks a registry account as capacity-only. Signing in
+ * for usage visibility must not opt an account into lane work, because lanes
+ * spread work across every enabled account and the accounts can belong to
+ * different companies. `hq lanes accounts enable` opts one in.
+ */
+export declare const CAPACITY_ONLY_REASON = "capacity-only: read for usage, not used by lanes";
+export interface ListCapacityAccountsOptions {
+    home?: string;
+    hqRoot?: string;
+    hostname?: string;
+    /** Injected config. `null` means the registry is empty. Omit to read the file. */
+    config?: LanesConfig | null;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function defaultProviderHome(provider: LaneProvider, home?: string): string;
+export declare function listCapacityAccounts(options?: ListCapacityAccountsOptions): CapacityAccount[];
+export declare function registryAccountIds(hqRoot: string, provider: string): string[];
+//# sourceMappingURL=accounts.d.ts.map

package/dist/lib/capacity/accounts.js

@@ -0,0 +1,90 @@
+/**
+ * Capacity account list (US-011).
+ *
+ * The lane account registry plus each provider's default home. A missing
+ * config file is an empty registry: this module does not call
+ * documentedDefaultConfig, which would invent an enabled account "a".
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { effectiveAccountHome } from "../lanes/account-home.js";
+import { lanesConfigPath, loadLanesConfig } from "../lanes/config.js";
+import { resolveLanesHqRoot } from "../lanes/hq-root.js";
+import { LANE_PROVIDERS } from "../lanes/types.js";
+/**
+ * `disabled_reason` that marks a registry account as capacity-only. Signing in
+ * for usage visibility must not opt an account into lane work, because lanes
+ * spread work across every enabled account and the accounts can belong to
+ * different companies. `hq lanes accounts enable` opts one in.
+ */
+export const CAPACITY_ONLY_REASON = "capacity-only: read for usage, not used by lanes";
+const DEFAULT_DIR = {
+    claude: ".claude",
+    codex: ".codex",
+    grok: ".grok",
+};
+export function defaultProviderHome(provider, home = os.homedir()) {
+    return path.join(home, DEFAULT_DIR[provider]);
+}
+export function listCapacityAccounts(options = {}) {
+    const home = options.home ?? os.homedir();
+    const hostname = options.hostname ?? os.hostname();
+    const config = resolveConfig(options);
+    const accounts = [];
+    for (const provider of LANE_PROVIDERS) {
+        accounts.push({
+            provider,
+            label: "default",
+            home: defaultProviderHome(provider, home),
+            source: "default",
+        });
+        const configured = config?.providers[provider]?.accounts ?? {};
+        for (const [label, account] of Object.entries(configured)) {
+            if (!account)
+                continue;
+            const capacityOnly = !account.enabled && account.disabled_reason === CAPACITY_ONLY_REASON;
+            if (!account.enabled && !capacityOnly)
+                continue;
+            const effective = effectiveAccountHome(account, hostname);
+            accounts.push({
+                provider,
+                label,
+                home: effective.home,
+                source: effective.source === "host" ? "host" : "registry",
+                lanes: account.enabled,
+            });
+        }
+    }
+    return accounts;
+}
+export function registryAccountIds(hqRoot, provider) {
+    if (!LANE_PROVIDERS.includes(provider))
+        return [];
+    const filePath = lanesConfigPath(hqRoot);
+    if (!fs.existsSync(filePath))
+        return [];
+    const config = loadLanesConfig(hqRoot);
+    return Object.keys(config.providers[provider].accounts);
+}
+function resolveConfig(options) {
+    if (options.config === null)
+        return null;
+    if (options.config)
+        return options.config;
+    const explicit = options.hqRoot?.trim() || options.env?.HQ_ROOT?.trim() || "";
+    let hqRoot = explicit;
+    if (!hqRoot) {
+        try {
+            hqRoot = resolveLanesHqRoot({ env: options.env });
+        }
+        catch {
+            return null;
+        }
+    }
+    const filePath = lanesConfigPath(hqRoot);
+    if (!fs.existsSync(filePath))
+        return null;
+    return loadLanesConfig(hqRoot);
+}
+//# sourceMappingURL=accounts.js.map

package/dist/lib/capacity/collect.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One-shot capacity collection (US-011).
+ *
+ * The daemon is the resident collector. This runs the same readers once
+ * into whatever ledger root the caller passes, so a check never writes
+ * ~/.hq/capacity unless that root is requested.
+ */
+import { type CapacityAccount } from "./accounts.js";
+import { type CodexAppServerSpawn } from "./collectors/codex.js";
+import { type CollectClaudeOAuthOptions } from "./collectors/claude-oauth.js";
+import { type CollectGrokOptions } from "./collectors/grok.js";
+import { type NowView } from "./ledger.js";
+export interface CollectCapacityOnceOptions {
+    root?: string;
+    home?: string;
+    hqRoot?: string;
+    hostname?: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => Date;
+    /** Replaces registry discovery. Tests pass fixture homes here. */
+    accounts?: readonly CapacityAccount[];
+    claude?: Pick<CollectClaudeOAuthOptions, "platform" | "securityExec" | "fetchImpl" | "cliVersion" | "readVersion" | "endpoint">;
+    grok?: Pick<CollectGrokOptions, "fetchImpl" | "cliVersion" | "readVersion" | "endpoint">;
+    codex?: {
+        spawn?: CodexAppServerSpawn;
+        cliVersion?: string;
+        skipAppServer?: boolean;
+    };
+    /** Login passes false so a partial account list cannot label the whole spool. */
+    includeSpool?: boolean;
+}
+export declare function collectCapacityOnce(options?: CollectCapacityOnceOptions): Promise<NowView>;
+//# sourceMappingURL=collect.d.ts.map