@indigoai-us/hq-cli 5.153.0 → 5.154.0

package/CHANGELOG.md

@@ -2,12 +2,25 @@
 
 ## [Unreleased]
 
+## [5.154.0] — 2026-09-24
+
+### Fixed
+
+- Local bots can now open files attached in HQ chat. The new `hq_attachment_fetch` agent tool downloads a chat or DM attachment into a private folder under the bot's agent directory and returns its local path, content type, and size (text files also come back inline). It accepts only the scope-relative `chat/attachments/...` paths that `hq_inbox_read` reports, fetches only from the bot's own company or from a DM the bot is part of, refuses files over 26 MiB, and uses the API the bot enrolled against. Because the attachment reference comes from the sender, any other vault path (for example `knowledge/...`, or a folder) is refused and the bot is pointed at `hq_files_read`. Previously `hq_files_read` rejected those paths and could not read binary files such as .xlsx.
+
 ## [5.153.0] — 2026-09-23
 
 ### Fixed
 
 - `hq mesh context prd-sync` rebinds a session to the PRD's project when that project is in the same company, then emits `task_status` against the new project so the Board and channel line land there. A PRD in another company is still skipped and does not rebind.
 
+### Tests
+
+- Cover Outpost admission when account a is at its Codex cap and account b
+  has queued work with available capacity.
+- Cover fresh pending resumes and answered-lane resumes against provider
+  capacity.
+
 ## [5.152.1] — 2026-09-23
 
 ### Fixed

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

@@ -9,6 +9,7 @@
  * hq binary with the machine-identity env pinned.
  */
 import { Command } from "commander";
+import type { Readable } from "node:stream";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { type HqRunResult, type McpToolClients } from "../lib/agent-kit/mcp/tools.js";
 import { type AgentKitPaths } from "../lib/agent-kit/paths.js";
@@ -17,7 +18,9 @@ export declare const AGENT_MCP_SERVER_NAME = "hq-agent";
 export declare const AGENT_MCP_INSTRUCTIONS: string;
 export declare const HQ_SUBPROCESS_TIMEOUT_MS = 120000;
 export declare function defaultRunHq(nodeBinary: string, hqBinary: string, env: NodeJS.ProcessEnv): (args: string[]) => Promise<HqRunResult>;
-export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir">): McpToolClients;
+export declare function defaultMcpClients(creds: ExternalMachineCreds, credsPath: string, paths?: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">): McpToolClients;
+/** Drain a stream into memory, refusing past `max` bytes. */
+export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
 export declare function createAgentMcpServer(clients: McpToolClients): McpServer;
 export declare function registerAgentMcpCommand(agent: Command): void;
 //# sourceMappingURL=agent-mcp.d.ts.map

package/dist/commands/agent-mcp.js

@@ -12,7 +12,10 @@ import { spawn } from "node:child_process";
 import * as os from "node:os";
 import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
-import { vaultApiFetch } from "../utils/vault-api.js";
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { createCompanyPresignClient } from "./files-browse.js";
+import { MAX_ATTACHMENT_BYTES } from "../lib/agent-kit/mcp/attachments.js";
 import { McpServer } from "../lib/agent-kit/mcp/jsonrpc.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
@@ -21,6 +24,7 @@ import { requireExternalCreds } from "./agent-kit.js";
 export const AGENT_MCP_SERVER_NAME = "hq-agent";
 export const AGENT_MCP_INSTRUCTIONS = "You are acting inside HQ as an enrolled external agent. Tools run as that machine identity: " +
     "hq_whoami (identity), hq_search / hq_files_list / hq_files_read (company vault), " +
+    "hq_attachment_fetch (download a chat attachment — a chat/attachments/… vaultPath on an inbox message — any file type), " +
     "hq_secrets_list / hq_secrets_exec (secrets by NAME only — values are never returned), " +
     "hq_inbox_read / hq_dm_send / hq_inbox_done (read pending HQ messages, reply, then mark each handled), hq_work_mesh_status (what the team is doing). " +
     "Never ask a user for a token or secret value; if a secret is missing, name it and ask an admin to add it.";
@@ -54,12 +58,34 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
         HQ_VAULT_API_URL: creds.apiBaseUrl,
         NO_COLOR: "1",
     };
+    const getToken = () => ensureCognitoToken({ tokenSource: "machine", interactive: false });
+    let companyUid;
     return {
         creds,
         paths,
         syncFiles: readKitConfig(agentKitPaths(os.homedir(), process.env), CLI_VERSION).syncFiles,
         runHq: defaultRunHq(process.execPath, process.argv[1], env),
-        getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
+        getToken,
+        resolveCompanyUid: async () => {
+            // Pin the enrolled API: DEFAULT_VAULT_API_URL was read from env at module
+            // load, before `hq agent mcp` sets HQ_VAULT_API_URL from the creds.
+            companyUid ??= getCompanyUid(await getToken(), creds.companySlug, creds.apiBaseUrl);
+            try {
+                return await companyUid;
+            }
+            catch (err) {
+                companyUid = undefined;
+                throw err;
+            }
+        },
+        downloadVaultObject: async (scopeUid, key) => {
+            // Same presign path `hq files cat` uses; the vault API's per-key ACL decides.
+            const client = createCompanyPresignClient({ token: await getToken(), companyUid: scopeUid, baseUrl: creds.apiBaseUrl });
+            const res = await client.send(new GetObjectCommand({ Bucket: scopeUid, Key: key }));
+            if (!res.Body)
+                throw new Error(`no body returned for '${key}'`);
+            return readBounded(res.Body, MAX_ATTACHMENT_BYTES);
+        },
         apiJson: async (token, path, init) => {
             const res = await vaultApiFetch({
                 token,
@@ -74,6 +100,21 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
         },
     };
 }
+/** Drain a stream into memory, refusing past `max` bytes. */
+export async function readBounded(body, max) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += b.length;
+        if (total > max) {
+            body.destroy();
+            throw new Error(`object exceeds the ${max}-byte attachment limit`);
+        }
+        chunks.push(b);
+    }
+    return Buffer.concat(chunks);
+}
 export function createAgentMcpServer(clients) {
     return new McpServer({
         name: AGENT_MCP_SERVER_NAME,

package/dist/commands/files-browse.d.ts

@@ -450,6 +450,12 @@ export declare function createCompanyPresignClient(input: {
      * (keys on these errors are bucket-relative and carry no slug).
      */
     companySlug?: string;
+    /**
+     * Control-plane origin for list/presign calls. Defaults to
+     * DEFAULT_VAULT_API_URL (via vaultApiFetch); an enrolled agent passes its
+     * own `apiBaseUrl` so its token only goes to the API it enrolled against.
+     */
+    baseUrl?: string;
 }): FilesBrowseS3Client;
 /**
  * Production company-mode client factory — closes over the caller's token and

package/dist/commands/files-browse.js

@@ -678,7 +678,7 @@ export const PRESIGN_BUFFER_MAX_BYTES = 32 * 1024 * 1024;
  * `send(...)` as if it held an S3 client.
  */
 export function createCompanyPresignClient(input) {
-    const { token, companyUid, companySlug } = input;
+    const { token, companyUid, companySlug, baseUrl } = input;
     const denied = (message, key, extra) => Object.assign(new Error(message), {
         status: 403,
         key,
@@ -692,7 +692,7 @@ export function createCompanyPresignClient(input) {
             query.prefix = prefix;
         if (cmd.input.ContinuationToken)
             query.cursor = cmd.input.ContinuationToken;
-        const res = await vaultApiFetch({ token, path: "/v1/files/list", query });
+        const res = await vaultApiFetch({ token, baseUrl, path: "/v1/files/list", query });
         if (!res.ok) {
             const body = (await res.json().catch(() => ({})));
             const message = body.message ?? body.error ?? `files list failed (${res.status})`;
@@ -723,6 +723,7 @@ export function createCompanyPresignClient(input) {
         const key = cmd.input.Key;
         const res = await vaultApiFetch({
             token,
+            baseUrl,
             path: "/v1/files/presign",
             method: "POST",
             body: { company: companyUid, key, op: "get" },

package/dist/lib/agent-kit/mcp/attachments.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `hq_attachment_fetch` — pull a chat attachment named on an inbox item down
+ * to a private local file the bot can open.
+ *
+ * Inbox items carry attachments as `{ vaultPath, companyUid, … }` where
+ * `vaultPath` is SCOPE-relative (`chat/attachments/{dm|chan}/<id>/<file>`) and
+ * `companyUid` is the vault scope the bytes live in: the company uid for a
+ * company channel, or the SENDER's person uid (`prs_…`) for a DM, because a DM
+ * attachment is stored in the sender's personal vault. Neither `hq_files_read`
+ * (which only accepts `companies/<slug>/…` and returns clamped text) nor
+ * anything else on the MCP surface could read those, so bots answered
+ * "I can't open the file".
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign), minted with the
+ * bot's own machine token, so the server's per-key ACL stays the authority.
+ * The client-side checks here are the tenant boundary the bot can state
+ * before any request leaves the machine. They matter because an attachment
+ * ref is SENDER-controlled while the server authorizes against the BOT's own
+ * access: without them a sender could attach any key the bot can read (say
+ * `knowledge/restricted/x.csv` in the bot's company) and have the bot fetch
+ * it for them.
+ *   - the key must be a plain relative path with no traversal, under
+ *     `chat/attachments/`;
+ *   - a DM key (`chat/attachments/dm/<a>--<b>/…`) must name this bot in the
+ *     pair, whichever scope it is read from;
+ *   - a `cmp_` scope must be the bot's own enrolled company;
+ *   - a `prs_` scope is only a DM attachment between that person and this
+ *     bot (the pair naming both).
+ *
+ * Files land under `<agentDir>/attachments/<scopeUid>/` (dir 0700, file 0600)
+ * with a sanitized name, so nothing from the message can pick the location.
+ */
+/**
+ * Refuse anything larger than this. Chat uploads are capped at 25 MB
+ * (MAX_CHAT_ATTACHMENT_BYTES in hq-desktop-app); 26 MiB leaves a little
+ * headroom over that without letting a crafted key pull a large vault object.
+ */
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** Upper bound on the inline text rendering returned alongside the path. */
+export declare const MAX_ATTACHMENT_TEXT_CHARS = 20000;
+/** Every chat upload lands under this prefix in its scope. */
+export declare const CHAT_ATTACHMENT_PREFIX = "chat/attachments/";
+/**
+ * Validate a scope-relative attachment key. Accepts only `chat/attachments/…`
+ * file keys exactly as inbox items carry them. Folder / share refs (`/`,
+ * `…/`) get a "not a chat attachment" error pointing at hq_files_read.
+ * Rejects absolute paths, traversal, empty / dot segments, backslashes and
+ * control characters. Returns the key with any leading slashes stripped.
+ */
+export declare function assertAttachmentKey(p: string): string;
+/** Throws unless `scopeUid` is a well-formed cmp_/prs_ uid. No network. */
+export declare function assertAttachmentScopeUid(scopeUid: string): void;
+/**
+ * The checks that need no network: uid format, DM-pair membership for any
+ * `chat/attachments/dm/…` key, and the prs_ scope rule. Run before resolving
+ * the bot's company so a refused ref never costs (or leaks) a request.
+ */
+export declare function assertAttachmentRef(input: {
+    scopeUid: string;
+    key: string;
+    botEntityUid: string;
+}): void;
+/**
+ * Tenant gate. Throws unless the scope is this bot's own company, or a
+ * person vault holding a DM attachment between that person and this bot.
+ */
+export declare function assertAttachmentScope(input: {
+    scopeUid: string;
+    key: string;
+    botCompanyUid: string;
+    botEntityUid: string;
+}): void;
+/** Reduce an untrusted name to a safe single path component. */
+export declare function sanitizeAttachmentFileName(raw: string): string;
+export interface FetchAttachmentResult {
+    localPath: string;
+    name: string;
+    contentType?: string;
+    sizeBytes: number;
+    vaultPath: string;
+    companyUid: string;
+    /** Inline rendering for text-like files (csv, txt, json, …), bounded. */
+    text?: string;
+    note?: string;
+}
+/**
+ * Download `key` from `scopeUid` and write it privately under `attachmentsDir`.
+ * `download` is the presign-backed reader; the caller has already gated scope.
+ */
+export declare function saveAttachment(input: {
+    attachmentsDir: string;
+    scopeUid: string;
+    key: string;
+    name?: string;
+    contentType?: string;
+    download: (scopeUid: string, key: string) => Promise<Buffer>;
+}): Promise<FetchAttachmentResult>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/lib/agent-kit/mcp/attachments.js

@@ -0,0 +1,188 @@
+/**
+ * `hq_attachment_fetch` — pull a chat attachment named on an inbox item down
+ * to a private local file the bot can open.
+ *
+ * Inbox items carry attachments as `{ vaultPath, companyUid, … }` where
+ * `vaultPath` is SCOPE-relative (`chat/attachments/{dm|chan}/<id>/<file>`) and
+ * `companyUid` is the vault scope the bytes live in: the company uid for a
+ * company channel, or the SENDER's person uid (`prs_…`) for a DM, because a DM
+ * attachment is stored in the sender's personal vault. Neither `hq_files_read`
+ * (which only accepts `companies/<slug>/…` and returns clamped text) nor
+ * anything else on the MCP surface could read those, so bots answered
+ * "I can't open the file".
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign), minted with the
+ * bot's own machine token, so the server's per-key ACL stays the authority.
+ * The client-side checks here are the tenant boundary the bot can state
+ * before any request leaves the machine. They matter because an attachment
+ * ref is SENDER-controlled while the server authorizes against the BOT's own
+ * access: without them a sender could attach any key the bot can read (say
+ * `knowledge/restricted/x.csv` in the bot's company) and have the bot fetch
+ * it for them.
+ *   - the key must be a plain relative path with no traversal, under
+ *     `chat/attachments/`;
+ *   - a DM key (`chat/attachments/dm/<a>--<b>/…`) must name this bot in the
+ *     pair, whichever scope it is read from;
+ *   - a `cmp_` scope must be the bot's own enrolled company;
+ *   - a `prs_` scope is only a DM attachment between that person and this
+ *     bot (the pair naming both).
+ *
+ * Files land under `<agentDir>/attachments/<scopeUid>/` (dir 0700, file 0600)
+ * with a sanitized name, so nothing from the message can pick the location.
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { McpToolInputError } from "./jsonrpc.js";
+/**
+ * Refuse anything larger than this. Chat uploads are capped at 25 MB
+ * (MAX_CHAT_ATTACHMENT_BYTES in hq-desktop-app); 26 MiB leaves a little
+ * headroom over that without letting a crafted key pull a large vault object.
+ */
+export const MAX_ATTACHMENT_BYTES = 26 * 1024 * 1024;
+/** Upper bound on the inline text rendering returned alongside the path. */
+export const MAX_ATTACHMENT_TEXT_CHARS = 20_000;
+const SCOPE_UID = /^(cmp|prs)_[A-Za-z0-9_-]{1,200}$/;
+/** Every chat upload lands under this prefix in its scope. */
+export const CHAT_ATTACHMENT_PREFIX = "chat/attachments/";
+const DM_KEY = /^chat\/attachments\/dm\/([^/]+)\/[^/]+$/;
+function notChatAttachment(p) {
+    return new McpToolInputError(`${JSON.stringify(p)} is not a chat attachment (expected chat/attachments/…); ` +
+        `hq_attachment_fetch only downloads files attached to HQ messages. For vault files and folders use hq_files_list / hq_files_read.`);
+}
+/**
+ * Validate a scope-relative attachment key. Accepts only `chat/attachments/…`
+ * file keys exactly as inbox items carry them. Folder / share refs (`/`,
+ * `…/`) get a "not a chat attachment" error pointing at hq_files_read.
+ * Rejects absolute paths, traversal, empty / dot segments, backslashes and
+ * control characters. Returns the key with any leading slashes stripped.
+ */
+export function assertAttachmentKey(p) {
+    const trimmed = p.trim();
+    // A folder or share ref is not a traversal attempt, just the wrong tool.
+    if (trimmed.endsWith("/"))
+        throw notChatAttachment(p);
+    const clean = trimmed.replace(/^\/+/, "");
+    const segs = clean.split("/");
+    const bad = clean.length === 0 ||
+        clean.length > 1000 ||
+        /\\/.test(clean) ||
+        [...clean].some((c) => c.charCodeAt(0) < 0x20 || c.charCodeAt(0) === 0x7f) ||
+        segs.some((s) => s === "" || s === "." || s === "..");
+    if (bad) {
+        throw new McpToolInputError(`"vault_path" must be a relative vault key without traversal (got ${JSON.stringify(p)})`);
+    }
+    if (segs[0] === "companies") {
+        throw new McpToolInputError(`"vault_path" is scope-relative (e.g. chat/attachments/dm/<id>/<file>); pass it exactly as hq_inbox_read returned it, without companies/<slug>/`);
+    }
+    if (!clean.startsWith(CHAT_ATTACHMENT_PREFIX)) {
+        throw notChatAttachment(p);
+    }
+    return clean;
+}
+/** Throws unless `scopeUid` is a well-formed cmp_/prs_ uid. No network. */
+export function assertAttachmentScopeUid(scopeUid) {
+    if (!SCOPE_UID.test(scopeUid)) {
+        throw new McpToolInputError(`"company_uid" must be a cmp_… or prs_… uid from hq_inbox_read (got ${JSON.stringify(scopeUid)})`);
+    }
+}
+/**
+ * The checks that need no network: uid format, DM-pair membership for any
+ * `chat/attachments/dm/…` key, and the prs_ scope rule. Run before resolving
+ * the bot's company so a refused ref never costs (or leaks) a request.
+ */
+export function assertAttachmentRef(input) {
+    const { scopeUid, key, botEntityUid } = input;
+    assertAttachmentScopeUid(scopeUid);
+    const isDmKey = key.startsWith(`${CHAT_ATTACHMENT_PREFIX}dm/`);
+    const m = DM_KEY.exec(key);
+    const members = m ? m[1].split("--") : [];
+    const botInPair = members.length === 2 && members.includes(botEntityUid);
+    if (isDmKey && !botInPair) {
+        throw new McpToolInputError(`a DM attachment is only readable by a member of that DM; this agent (${botEntityUid}) is not in ${JSON.stringify(key.split("/")[3] ?? "")}`);
+    }
+    if (scopeUid.startsWith("prs_") && !(m && botInPair && members.includes(scopeUid))) {
+        throw new McpToolInputError(`a personal-vault attachment is only readable when it is a DM between that person and this agent (chat/attachments/dm/<uid>--<uid>/…)`);
+    }
+}
+/**
+ * Tenant gate. Throws unless the scope is this bot's own company, or a
+ * person vault holding a DM attachment between that person and this bot.
+ */
+export function assertAttachmentScope(input) {
+    const { scopeUid, key, botCompanyUid, botEntityUid } = input;
+    assertAttachmentRef({ scopeUid, key, botEntityUid });
+    if (scopeUid.startsWith("cmp_") && scopeUid !== botCompanyUid) {
+        throw new McpToolInputError(`attachment belongs to company ${scopeUid}; this agent is enrolled in ${botCompanyUid} and cannot read another company's files`);
+    }
+}
+/** Reduce an untrusted name to a safe single path component. */
+export function sanitizeAttachmentFileName(raw) {
+    const base = raw.trim().split(/[/\\]/).pop() ?? "";
+    const cleaned = base.replace(/[^\w.\- ()[\]]+/g, "_").replace(/^[.\s]+/, "");
+    return cleaned.slice(0, 180) || "file";
+}
+const TEXT_EXT = new Set(["csv", "tsv", "txt", "md", "json", "yaml", "yml", "xml", "html", "log"]);
+function renderText(buf, name, contentType) {
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    const textual = TEXT_EXT.has(ext) || (contentType ?? "").startsWith("text/") || contentType === "application/json";
+    if (!textual || buf.includes(0))
+        return undefined;
+    const text = buf.toString("utf8");
+    return text.length > MAX_ATTACHMENT_TEXT_CHARS
+        ? `${text.slice(0, MAX_ATTACHMENT_TEXT_CHARS)}\n… [truncated ${text.length - MAX_ATTACHMENT_TEXT_CHARS} chars; read the local file for the rest]`
+        : text;
+}
+/**
+ * Download `key` from `scopeUid` and write it privately under `attachmentsDir`.
+ * `download` is the presign-backed reader; the caller has already gated scope.
+ */
+export async function saveAttachment(input) {
+    const { attachmentsDir, scopeUid, key } = input;
+    const bytes = await input.download(scopeUid, key);
+    if (bytes.length > MAX_ATTACHMENT_BYTES) {
+        throw new Error(`attachment is ${bytes.length} bytes, over the ${MAX_ATTACHMENT_BYTES}-byte limit`);
+    }
+    const name = sanitizeAttachmentFileName(input.name || key.split("/").pop() || "file");
+    const dir = path.join(attachmentsDir, sanitizeAttachmentFileName(scopeUid));
+    for (const d of [attachmentsDir, dir]) {
+        fs.mkdirSync(d, { recursive: true, mode: 0o700 });
+        fs.chmodSync(d, 0o700);
+    }
+    // A short digest of scope+key keeps two same-named files apart and makes a
+    // re-fetch of the same attachment overwrite rather than pile up.
+    const digest = createHash("sha256").update(`${scopeUid}\0${key}`).digest("hex").slice(0, 12);
+    const localPath = path.join(dir, `${digest}-${name}`);
+    if (path.dirname(localPath) !== dir)
+        throw new Error("refusing to write outside the attachments directory");
+    const tmp = `${localPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tmp, bytes, { mode: 0o600 });
+        fs.chmodSync(tmp, 0o600);
+        fs.renameSync(tmp, localPath);
+    }
+    catch (err) {
+        // Never leave a partial copy of the attachment behind.
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    const ext = name.split(".").pop()?.toLowerCase() ?? "";
+    const text = renderText(bytes, name, input.contentType);
+    const note = text !== undefined
+        ? undefined
+        : ext === "xlsx" || ext === "xls"
+            ? "Spreadsheet saved locally; open localPath with a spreadsheet library (e.g. openpyxl / pandas) to read the sheets."
+            : "Binary file saved locally; open localPath with a suitable tool.";
+    return {
+        localPath,
+        name,
+        ...(input.contentType ? { contentType: input.contentType } : {}),
+        sizeBytes: bytes.length,
+        vaultPath: key,
+        companyUid: scopeUid,
+        ...(text !== undefined ? { text } : {}),
+        ...(note ? { note } : {}),
+    };
+}
+//# sourceMappingURL=attachments.js.map

package/dist/lib/agent-kit/mcp/tools.d.ts

@@ -25,8 +25,11 @@ export interface HqRunResult {
 }
 export interface McpToolClients {
     creds: ExternalMachineCreds;
-    /** Kit layout; the inbox tools read the mirror and done-state here. */
-    paths: Pick<AgentKitPaths, "inboxDir">;
+    /**
+     * Kit layout; the inbox tools read the mirror and done-state here, and
+     * `hq_attachment_fetch` writes downloaded attachments under attachmentsDir.
+     */
+    paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
     /** Run `hq <args…>` as the machine identity; never throws. */
     runHq: (args: string[]) => Promise<HqRunResult>;
     getToken: () => Promise<string>;
@@ -37,6 +40,13 @@ export interface McpToolClients {
      * match on file names and paths, not on contents.
      */
     syncFiles?: boolean;
+    /** The cmp_ uid of this agent's enrolled company (creds.companySlug). */
+    resolveCompanyUid: () => Promise<string>;
+    /**
+     * Read one vault object's bytes by scope uid (cmp_/prs_) + scope-relative
+     * key through the presign API, as the machine identity.
+     */
+    downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
     /** Authenticated JSON call against the control plane. */
     apiJson: (token: string, path: string, init?: {
         method?: string;
@@ -48,6 +58,7 @@ export interface McpToolClients {
     }>;
 }
 export declare const MAX_TOOL_OUTPUT_CHARS = 40000;
+export declare const ATTACHMENTS_HINT: string;
 export declare function clampOutput(text: string, max?: number): string;
 /** Vault paths are company-anchored and must not escape. */
 export declare function assertVaultPath(p: string): string;

package/dist/lib/agent-kit/mcp/tools.js

@@ -19,8 +19,12 @@ import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
 import { isRecipientUid } from "../../../lib/notify-recipient.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
+import { assertAttachmentKey, assertAttachmentRef, assertAttachmentScope, saveAttachment } from "./attachments.js";
 import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
 export const MAX_TOOL_OUTPUT_CHARS = 40_000;
+export const ATTACHMENTS_HINT = "Some messages carry files. For each entry in a message's `attachments` whose vaultPath starts with chat/attachments/, " +
+    "call hq_attachment_fetch with that vaultPath and companyUid to download it; hq_files_read cannot open message attachments. " +
+    "Anything else (a folder or shared vault path) is not a chat attachment: use hq_files_list / hq_files_read for those.";
 function str(args, key, opts = {}) {
     const v = args[key];
     if (v === undefined || v === null) {
@@ -148,7 +152,8 @@ export function buildAgentMcpTools(clients) {
         },
         {
             name: "hq_files_read",
-            description: "Read one vault file's contents (hq files cat). Text files only; output is truncated at 40k chars.",
+            description: "Read one company vault file's contents (hq files cat). Text files only; output is truncated at 40k chars. " +
+                "For files attached to an HQ message use hq_attachment_fetch instead.",
             inputSchema: {
                 type: "object",
                 properties: { path: { type: "string", description: "companies/<slug>/<file>" } },
@@ -239,7 +244,8 @@ export function buildAgentMcpTools(clients) {
         {
             name: "hq_inbox_read",
             description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
-                "marked handled. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
+                "marked handled. Items with `attachments` carry files: download each with hq_attachment_fetch (pass its vaultPath " +
+                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, then mark each one handled with hq_inbox_done so it is never answered twice.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -262,7 +268,64 @@ export function buildAgentMcpTools(clients) {
                     .filter((e) => includeDone || !done.has(e.id))
                     .slice(0, limit)
                     .map((e) => summarizeInboxEntry(e, done.has(e.id)));
-                return textResult(clampOutput(JSON.stringify({ count: rows.length, messages: rows, ...(serverNote ? { note: serverNote } : {}) }, null, 2)));
+                const hasFiles = rows.some((r) => r.attachments?.length);
+                return textResult(clampOutput(JSON.stringify({
+                    count: rows.length,
+                    messages: rows,
+                    ...(serverNote ? { note: serverNote } : {}),
+                    ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),
+                }, null, 2)));
+            },
+        },
+        {
+            name: "hq_attachment_fetch",
+            description: "Download a file attached to an HQ chat message (from hq_inbox_read `attachments`, vaultPath under chat/attachments/) " +
+                "to a private local file and return its localPath, contentType and size. Text-like files (csv, txt, json, …) also come back inline, bounded. " +
+                "Works for any type (xlsx, pdf, images): open localPath with a suitable tool. Only chat attachments in this agent's company, " +
+                "or in a DM with this agent; for other vault files or folders use hq_files_list / hq_files_read.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    vault_path: { type: "string", description: "attachments[].vaultPath exactly as hq_inbox_read returned it (chat/attachments/…)" },
+                    company_uid: { type: "string", description: "attachments[].companyUid (cmp_… or prs_…)" },
+                    name: { type: "string", description: "attachments[].name (optional; used for the local file name)" },
+                    content_type: { type: "string", description: "attachments[].contentType (optional)" },
+                },
+                required: ["vault_path", "company_uid"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const key = assertAttachmentKey(str(args, "vault_path", { required: true, max: 1000 }));
+                const scopeUid = str(args, "company_uid", { required: true, max: 220 }).trim();
+                const name = str(args, "name", { max: 500 });
+                const contentType = str(args, "content_type", { max: 200 });
+                // Format, DM-pair and prs_ checks need no network: refuse bad refs
+                // before resolving the company (a lookup that sends the bot's token).
+                assertAttachmentRef({ scopeUid, key, botEntityUid: creds.entityUid });
+                if (scopeUid.startsWith("cmp_")) {
+                    let botCompanyUid;
+                    try {
+                        botCompanyUid = await clients.resolveCompanyUid();
+                    }
+                    catch (err) {
+                        return errorResult(`could not resolve this agent's company: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    assertAttachmentScope({ scopeUid, key, botCompanyUid, botEntityUid: creds.entityUid });
+                }
+                try {
+                    const result = await saveAttachment({
+                        attachmentsDir: clients.paths.attachmentsDir,
+                        scopeUid,
+                        key,
+                        name,
+                        contentType,
+                        download: clients.downloadVaultObject,
+                    });
+                    return textResult(clampOutput(JSON.stringify(result, null, 2)));
+                }
+                catch (err) {
+                    return errorResult(`attachment fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+                }
             },
         },
         {

package/dist/lib/agent-kit/paths.d.ts

@@ -7,6 +7,7 @@
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
  *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service
  *   ~/.hq-agent/skills/<name>/SKILL.md
  *
@@ -39,6 +40,8 @@ export interface AgentKitPaths {
     kitConfigPath: string;
     stateDir: string;
     inboxDir: string;
+    /** Private (0700) home for message attachments fetched by hq_attachment_fetch. */
+    attachmentsDir: string;
     logsDir: string;
     skillsDir: string;
     lastHeartbeatPath: string;

package/dist/lib/agent-kit/paths.js

@@ -7,6 +7,7 @@
  *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
  *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
  *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
  *   ~/.hq-agent/logs/*.log           one log per kit service
  *   ~/.hq-agent/skills/<name>/SKILL.md
  *
@@ -102,6 +103,7 @@ export function agentKitPaths(home = os.homedir(), env = process.env) {
         kitConfigPath: path.join(dir, KIT_CONFIG_NAME),
         stateDir,
         inboxDir: path.join(dir, "inbox"),
+        attachmentsDir: path.join(dir, "attachments"),
         logsDir: path.join(dir, "logs"),
         skillsDir: path.join(dir, "skills"),
         lastHeartbeatPath: path.join(stateDir, LAST_HEARTBEAT_NAME),

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

@@ -61,7 +61,13 @@ export declare function vaultApiFetchPublic(opts: {
 }): Promise<Response>;
 export declare function looksLikeCompanyUid(ref: string): boolean;
 export declare function looksLikePersonVaultUid(ref: string): boolean;
-export declare function getCompanyUid(token: string, companySlug: string | undefined): Promise<string>;
+export declare function getCompanyUid(token: string, companySlug: string | undefined, 
+/**
+ * Control-plane origin for the lookups. Defaults to DEFAULT_VAULT_API_URL;
+ * pass it when the caller is bound to another API (an enrolled agent's
+ * `apiBaseUrl`) so its token never goes to the default host.
+ */
+baseUrl?: string): Promise<string>;
 export declare function resolveCallerPersonUid(token: string, baseUrl?: string): Promise<string>;
 export declare function getEntityUid(token: string, opts: {
     personal?: boolean;

package/dist/utils/vault-api.js

@@ -314,10 +314,11 @@ function raiseIfUnauthorized(res) {
     if (res.status === 401)
         throw new AuthError();
 }
-async function resolveCompanyByUid(token, uid) {
+async function resolveCompanyByUid(token, uid, baseUrl) {
     const res = await vaultApiFetch({
         token,
         path: `/entity/${encodeURIComponent(uid)}`,
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
@@ -370,11 +371,12 @@ function isTransientSlugLookupStatus(status) {
  * stranger's same-slug company is correctly invisible to resolution. This is
  * the same primitive hq-cloud's `context.ts` already resolves slugs through.
  */
-async function resolveSlugInCallerNamespace(token, slug) {
+async function resolveSlugInCallerNamespace(token, slug, baseUrl) {
     const attempt = async () => {
         const res = await vaultApiFetch({
             token,
             path: "/entity/check-slug/me",
+            baseUrl,
             query: { type: "company", slug },
             signal: AbortSignal.timeout(identityLookupTimeoutMs()),
         });
@@ -411,10 +413,11 @@ async function resolveSlugInCallerNamespace(token, slug) {
         return first;
     return run();
 }
-async function fetchGlobalCompanyBySlug(token, ref) {
+async function fetchGlobalCompanyBySlug(token, ref, baseUrl) {
     const attempt = () => vaultApiFetch({
         token,
         path: `/entity/by-slug/company/${encodeURIComponent(ref)}`,
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     try {
@@ -429,10 +432,10 @@ async function fetchGlobalCompanyBySlug(token, ref) {
     }
     return attempt();
 }
-async function resolveCompanyUid(token, ref) {
+async function resolveCompanyUid(token, ref, baseUrl) {
     // Silent escape hatch: a `cmp_` ref is a uid, not a slug — resolve directly.
     if (looksLikeCompanyUid(ref)) {
-        return resolveCompanyByUid(token, ref);
+        return resolveCompanyByUid(token, ref, baseUrl);
     }
     // A `prs_` ref names a person's vault (DM attachments). There is no slug to
     // resolve and no company lookup that could succeed; pass it through as the
@@ -453,7 +456,7 @@ async function resolveCompanyUid(token, ref) {
     // hq-cli defect still throws, and the 401 AuthError that
     // `raiseIfUnauthorized` throws still short-circuits before any fallback
     // (Sentry HQ-CLI-1P / issue 7716090679).
-    const mine = await resolveSlugInCallerNamespace(token, ref);
+    const mine = await resolveSlugInCallerNamespace(token, ref, baseUrl);
     if (mine.kind === "hit") {
         return mine.uid;
     }
@@ -462,7 +465,7 @@ async function resolveCompanyUid(token, ref) {
     // cross-company / admin resolutions that intentionally target a company the
     // caller isn't a member of (e.g. a group-grant target). A single global
     // match resolves cleanly.
-    const res = await fetchGlobalCompanyBySlug(token, ref);
+    const res = await fetchGlobalCompanyBySlug(token, ref, baseUrl);
     if (!res.ok) {
         raiseIfUnauthorized(res);
         const body = (await res.json().catch(() => ({})));
@@ -494,10 +497,11 @@ async function resolveCompanyUid(token, ref) {
     const data = (await res.json());
     return data.entity.uid;
 }
-async function resolveCompanyFromMemberships(token) {
+async function resolveCompanyFromMemberships(token, baseUrl) {
     const res = await vaultApiFetch({
         token,
         path: '/membership/me',
+        baseUrl,
         signal: AbortSignal.timeout(identityLookupTimeoutMs()),
     });
     if (!res.ok) {
@@ -519,7 +523,13 @@ async function resolveCompanyFromMemberships(token) {
         `pick one:\n` +
         picks.join('\n'));
 }
-export async function getCompanyUid(token, companySlug) {
+export async function getCompanyUid(token, companySlug, 
+/**
+ * Control-plane origin for the lookups. Defaults to DEFAULT_VAULT_API_URL;
+ * pass it when the caller is bound to another API (an enrolled agent's
+ * `apiBaseUrl`) so its token never goes to the default host.
+ */
+baseUrl) {
     // Vault API keys are company-bound. Entity slug resolution has no keyed
     // route, so under hqk_ we accept an explicit cmp_ uid (or HQ_COMPANY_UID)
     // and otherwise fall through to keyed GET /v1/keys/membership/me.
@@ -532,12 +542,12 @@ export async function getCompanyUid(token, companySlug) {
             }
             return ref;
         }
-        return resolveCompanyFromMemberships(token);
+        return resolveCompanyFromMemberships(token, baseUrl);
     }
     if (companySlug) {
-        return resolveCompanyUid(token, companySlug);
+        return resolveCompanyUid(token, companySlug, baseUrl);
     }
-    return resolveCompanyFromMemberships(token);
+    return resolveCompanyFromMemberships(token, baseUrl);
 }
 // Same selection rule as the backend's `resolveCallerPersonUid`: ascending by
 // createdAt, tie-break by uid ascending. Returns the `prs_*` UID.

package/package.json

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