@indigoai-us/hq-cli 5.156.0 → 5.157.0

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [5.157.0] — 2026-09-24
+
+### Fixed
+
+- Local bots (`hq bot run`) now receive HQ chat attachments. The runner reads
+  `attachments` on each inbox item, downloads every file with the bot's own
+  machine identity through the same checks `hq_attachment_fetch` uses (chat
+  attachment path only, DM must include the bot, company must be one of the
+  bot's own, 26 MiB cap), and saves it under `~/.hq/bots/<name>/attachments/`
+  (dir 0700, files 0600). The turn text lists each file's name, type, size and
+  local path, with small text files inlined; a file that could not be fetched
+  gets a one-line reason, which is also logged. A message that is only an
+  attachment is answered instead of being acked and dropped. Claude turns get
+  `--add-dir` for the attachments folder so gated permission modes can read it.
+  The MIME type is also read from the server's `kind` field.
+
 ## [5.156.0] — 2026-09-24
 
 ### Fixed

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

@@ -9,18 +9,16 @@
  * 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";
 import type { ExternalMachineCreds } from "../lib/agent-kit/creds.js";
+export { readBounded } from "../lib/agent-kit/attachment-download.js";
 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" | "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,15 +12,15 @@ 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 { 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 { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { buildAgentMcpTools } from "../lib/agent-kit/mcp/tools.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { requireExternalCreds } from "./agent-kit.js";
+// Re-exported for callers that imported it from here before it moved.
+export { readBounded } from "../lib/agent-kit/attachment-download.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), " +
@@ -78,14 +78,8 @@ export function defaultMcpClients(creds, credsPath, paths = agentKitPaths(os.hom
                 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);
-        },
+        // Same presign path `hq files cat` uses; the vault API's per-key ACL decides.
+        downloadVaultObject: createVaultObjectDownloader({ getToken, baseUrl: creds.apiBaseUrl }),
         apiJson: async (token, path, init) => {
             const res = await vaultApiFetch({
                 token,
@@ -100,21 +94,6 @@ 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/bot.js

@@ -25,6 +25,7 @@ import { hasPromotionHold, promotionHoldSummary } from "../lib/bot/promotion-hol
  * list (online flag), and rm. Secrets are never printed.
  */
 import { promoteLocalBot } from "../lib/bot/promote.js";
+import { createVaultObjectDownloader } from "../lib/agent-kit/attachment-download.js";
 import { addBotToCompanies, describeCompanyFailures, removeBotFromCompanies } from "./bot-companies.js";
 import { registerBotContinuityCommand } from "./bot-continuity.js";
 import { registerBotJobsCommand } from "./bot-jobs.js";
@@ -680,9 +681,19 @@ async function runBotResident(nameArg) {
             console.log(orphanBotRunMessage(name, outcome));
         return;
     }
-    const api = new BotApi({ token: botTokenSupplier(dir) });
+    const token = botTokenSupplier(dir);
+    const api = new BotApi({ token });
     const owner = new OwnerContextCache(() => lookupOwnerContext(config.ownerUid), Date.now, undefined, config.ownerUid);
-    const handle = await runBot({ dir, config, api, runtime: runtimeFor(config.runtime), ownerContext: () => owner.get() });
+    const handle = await runBot({
+        dir,
+        config,
+        api,
+        runtime: runtimeFor(config.runtime),
+        ownerContext: () => owner.get(),
+        // Chat attachments are fetched with the bot's own machine identity against
+        // the same API its inbox and posts use (BotApi has no baseUrl override either).
+        downloadAttachment: createVaultObjectDownloader({ getToken: token }),
+    });
     await handle.done;
     void name;
 }

package/dist/lib/agent-kit/attachment-download.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Vault object download for chat attachments, shared by `hq agent mcp`
+ * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
+ * machine token, so the server's per-key ACL stays the authority. The body is
+ * read with a hard byte cap so a crafted key cannot pull a large object into
+ * memory.
+ */
+import type { Readable } from "node:stream";
+export type VaultObjectDownloader = (scopeUid: string, key: string) => Promise<Buffer>;
+/** Drain a stream into memory, refusing past `max` bytes. */
+export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
+/**
+ * A downloader bound to one identity. `baseUrl` pins the API the token is sent
+ * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
+ * vault API, the same one the caller's other API calls use).
+ */
+export declare function createVaultObjectDownloader(opts: {
+    getToken: () => Promise<string>;
+    baseUrl?: string;
+}): VaultObjectDownloader;
+//# sourceMappingURL=attachment-download.d.ts.map

package/dist/lib/agent-kit/attachment-download.js

@@ -0,0 +1,47 @@
+/**
+ * Vault object download for chat attachments, shared by `hq agent mcp`
+ * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
+ *
+ * Bytes come through the same vault presign path `hq files cat` uses
+ * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
+ * machine token, so the server's per-key ACL stays the authority. The body is
+ * read with a hard byte cap so a crafted key cannot pull a large object into
+ * memory.
+ */
+import { GetObjectCommand } from "@aws-sdk/client-s3";
+import { createCompanyPresignClient } from "../../commands/files-browse.js";
+import { MAX_ATTACHMENT_BYTES } from "./mcp/attachments.js";
+/** 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);
+}
+/**
+ * A downloader bound to one identity. `baseUrl` pins the API the token is sent
+ * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
+ * vault API, the same one the caller's other API calls use).
+ */
+export function createVaultObjectDownloader(opts) {
+    return async (scopeUid, key) => {
+        const client = createCompanyPresignClient({
+            token: await opts.getToken(),
+            companyUid: scopeUid,
+            ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
+        });
+        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);
+    };
+}
+//# sourceMappingURL=attachment-download.js.map

package/dist/lib/agent-kit/inbox-state.d.ts

@@ -30,11 +30,15 @@ export interface InboxAttachment {
     companyUid?: string;
 }
 /**
- * The file references on an inbox entry, plural `attachments[]` first and the
+ * The file references on an inbox entry (a mirrored kit entry or a bot
+ * runner's raw inbox item), plural `attachments[]` first and the
  * legacy singular `attachment` as a fallback. Entries without a `vaultPath` are
  * dropped: a reference the bot cannot fetch is worse than none. Pure.
  */
-export declare function inboxEntryAttachments(e: MirroredInboxEntry): InboxAttachment[];
+export declare function inboxEntryAttachments(e: MirroredInboxEntry | {
+    attachments?: unknown;
+    attachment?: unknown;
+}): InboxAttachment[];
 /**
  * Compact view for bots: who, when, which channel, the text, and any attached
  * files. The attachments belong here because this summary IS the message as far

package/dist/lib/agent-kit/inbox-state.js

@@ -66,7 +66,8 @@ export function pendingInbox(paths) {
     return readMirroredInbox(paths).filter((e) => !done.has(e.id));
 }
 /**
- * The file references on an inbox entry, plural `attachments[]` first and the
+ * The file references on an inbox entry (a mirrored kit entry or a bot
+ * runner's raw inbox item), plural `attachments[]` first and the
  * legacy singular `attachment` as a fallback. Entries without a `vaultPath` are
  * dropped: a reference the bot cannot fetch is worse than none. Pure.
  */
@@ -87,10 +88,13 @@ export function inboxEntryAttachments(e) {
         const str = (k) => typeof rec[k] === "string" && rec[k].trim()
             ? rec[k].trim()
             : undefined;
+        // The chat server records the MIME type as `kind` (hq-pro MessageAttachment);
+        // `contentType` wins when both are present. A coarse kind ("image") is not a MIME type.
+        const contentType = str("contentType") ?? (str("kind")?.includes("/") ? str("kind") : undefined);
         out.push({
             vaultPath,
             ...(str("name") ? { name: str("name") } : {}),
-            ...(str("contentType") ? { contentType: str("contentType") } : {}),
+            ...(contentType ? { contentType } : {}),
             ...(typeof rec.sizeBytes === "number" ? { sizeBytes: rec.sizeBytes } : {}),
             ...(str("companyUid") ? { companyUid: str("companyUid") } : {}),
         });

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

@@ -68,7 +68,8 @@ export declare function assertAttachmentRef(input: {
 export declare function assertAttachmentScope(input: {
     scopeUid: string;
     key: string;
-    botCompanyUid: string;
+    /** The bot's company, or every company it is a member of (a local company bot can have several). */
+    botCompanyUid: string | readonly string[];
     botEntityUid: string;
 }): void;
 /** Reduce an untrusted name to a safe single path component. */
@@ -96,4 +97,30 @@ export declare function saveAttachment(input: {
     contentType?: string;
     download: (scopeUid: string, key: string) => Promise<Buffer>;
 }): Promise<FetchAttachmentResult>;
+/** The bot's own company could not be looked up, so a cmp_ attachment could not be gated. */
+export declare class AttachmentCompanyUnresolvedError extends Error {
+    constructor(cause: unknown);
+}
+/**
+ * Validate one sender-supplied attachment ref and download it privately.
+ * The single path every caller uses (the `hq_attachment_fetch` MCP tool and
+ * the local bot runner), so the tenant checks cannot drift apart:
+ *   1. key shape (assertAttachmentKey) and the no-network ref checks
+ *      (uid format, DM-pair membership, prs_ scope rule) — before any request;
+ *   2. for a cmp_ scope only, the bot's own company (resolved lazily, so a
+ *      prs_ DM attachment never costs a lookup) must be the scope;
+ *   3. saveAttachment: size cap, sanitized 0600 file in a 0700 dir, temp cleanup.
+ * Refusals throw McpToolInputError; a failed company lookup throws
+ * AttachmentCompanyUnresolvedError; a download/write failure throws as-is.
+ */
+export declare function fetchChatAttachment(input: {
+    vaultPath: string;
+    scopeUid: string;
+    name?: string;
+    contentType?: string;
+    botEntityUid: string;
+    resolveBotCompanyUids: () => Promise<string | readonly string[]>;
+    attachmentsDir: string;
+    download: (scopeUid: string, key: string) => Promise<Buffer>;
+}): Promise<FetchAttachmentResult>;
 //# sourceMappingURL=attachments.d.ts.map

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

@@ -113,8 +113,9 @@ export function assertAttachmentRef(input) {
 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`);
+    const own = typeof botCompanyUid === "string" ? [botCompanyUid] : botCompanyUid;
+    if (scopeUid.startsWith("cmp_") && !own.includes(scopeUid)) {
+        throw new McpToolInputError(`attachment belongs to company ${scopeUid}; this agent is ${own.length ? `enrolled in ${own.join(", ")}` : "not a member of any company"} and cannot read another company's files`);
     }
 }
 /** Reduce an untrusted name to a safe single path component. */
@@ -185,4 +186,49 @@ export async function saveAttachment(input) {
         ...(note ? { note } : {}),
     };
 }
+/** The bot's own company could not be looked up, so a cmp_ attachment could not be gated. */
+export class AttachmentCompanyUnresolvedError extends Error {
+    constructor(cause) {
+        super(`could not resolve this agent's company: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "AttachmentCompanyUnresolvedError";
+    }
+}
+/**
+ * Validate one sender-supplied attachment ref and download it privately.
+ * The single path every caller uses (the `hq_attachment_fetch` MCP tool and
+ * the local bot runner), so the tenant checks cannot drift apart:
+ *   1. key shape (assertAttachmentKey) and the no-network ref checks
+ *      (uid format, DM-pair membership, prs_ scope rule) — before any request;
+ *   2. for a cmp_ scope only, the bot's own company (resolved lazily, so a
+ *      prs_ DM attachment never costs a lookup) must be the scope;
+ *   3. saveAttachment: size cap, sanitized 0600 file in a 0700 dir, temp cleanup.
+ * Refusals throw McpToolInputError; a failed company lookup throws
+ * AttachmentCompanyUnresolvedError; a download/write failure throws as-is.
+ */
+export async function fetchChatAttachment(input) {
+    const key = assertAttachmentKey(input.vaultPath);
+    const scopeUid = input.scopeUid.trim();
+    const { botEntityUid } = input;
+    // 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 });
+    if (scopeUid.startsWith("cmp_")) {
+        let botCompanyUid;
+        try {
+            botCompanyUid = await input.resolveBotCompanyUids();
+        }
+        catch (err) {
+            throw new AttachmentCompanyUnresolvedError(err);
+        }
+        assertAttachmentScope({ scopeUid, key, botCompanyUid, botEntityUid });
+    }
+    return saveAttachment({
+        attachmentsDir: input.attachmentsDir,
+        scopeUid,
+        key,
+        name: input.name,
+        contentType: input.contentType,
+        download: input.download,
+    });
+}
 //# sourceMappingURL=attachments.js.map

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

@@ -19,7 +19,7 @@ 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 { AttachmentCompanyUnresolvedError, fetchChatAttachment } 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/, " +
@@ -295,35 +295,29 @@ export function buildAgentMcpTools(clients) {
                 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 vaultPath = str(args, "vault_path", { required: true, max: 1000 });
+                const scopeUid = str(args, "company_uid", { required: true, max: 220 });
                 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,
+                    const result = await fetchChatAttachment({
+                        vaultPath,
                         scopeUid,
-                        key,
                         name,
                         contentType,
+                        botEntityUid: creds.entityUid,
+                        resolveBotCompanyUids: clients.resolveCompanyUid,
+                        attachmentsDir: clients.paths.attachmentsDir,
                         download: clients.downloadVaultObject,
                     });
                     return textResult(clampOutput(JSON.stringify(result, null, 2)));
                 }
                 catch (err) {
+                    // A refused ref is bad tool input (JSON-RPC invalid params).
+                    if (err instanceof McpToolInputError)
+                        throw err;
+                    if (err instanceof AttachmentCompanyUnresolvedError)
+                        return errorResult(err.message);
                     return errorResult(`attachment fetch failed: ${err instanceof Error ? err.message : String(err)}`);
                 }
             },

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

@@ -22,6 +22,15 @@ export interface InboxItem {
     text?: string;
     rootEventId?: string;
     receivedAt?: string;
+    /**
+     * Files attached to the message, as vault references (never content):
+     * `{ vaultPath, name, sizeBytes, contentType | kind, companyUid }`, where
+     * `companyUid` is the vault scope (the sender's prs_ for a DM). Server:
+     * hq-pro-agents channels/agent-dm-dispatch.ts. Parse with
+     * `inboxEntryAttachments`; the singular `attachment` is the legacy form.
+     */
+    attachments?: unknown[];
+    attachment?: unknown;
     /** Room items only (channel === "room"). */
     channelId?: string;
     channelName?: string;

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

@@ -0,0 +1,45 @@
+/**
+ * Chat attachments for local bot turns (`hq bot run`).
+ *
+ * A local bot's runtime (claude / codex / grok) runs without the `hq agent
+ * mcp` server, so it cannot call `hq_attachment_fetch`. The runner therefore
+ * downloads every file named on an inbox item BEFORE the turn, through the
+ * same validated path the MCP tool uses (`fetchChatAttachment`: key shape,
+ * DM-pair membership, company gate, size cap, private file), with the bot's
+ * own machine credentials, into the bot's own directory. The turn text gets a
+ * short block naming each file and where it is on disk; a file that could
+ * not be fetched gets a one-line reason instead of a path. Doing it in the
+ * runner makes it work the same for every runtime.
+ */
+import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
+import type { InboxAttachment } from "../agent-kit/inbox-state.js";
+export interface TurnAttachment {
+    /** Display name (sanitized file name once saved). */
+    name: string;
+    contentType?: string;
+    sizeBytes?: number;
+    /** Set when the file was saved; absent when `error` is set. */
+    localPath?: string;
+    /** Bounded inline rendering for text-like files. */
+    text?: string;
+    /** How to open a non-text file. */
+    note?: string;
+    /** One-line reason the file was not downloaded. */
+    error?: string;
+}
+/**
+ * Download each attachment for one turn. Never throws: a per-file failure is
+ * returned as `error` (the caller logs it and shows it to the model), so one
+ * bad reference never costs the sender their reply.
+ */
+export declare function downloadTurnAttachments(input: {
+    attachments: readonly InboxAttachment[];
+    botEntityUid: string;
+    attachmentsDir: string;
+    /** The bot's own company uids (its server memberships); consulted only for a cmp_ scope. */
+    resolveBotCompanyUids: () => Promise<readonly string[]>;
+    download?: VaultObjectDownloader;
+}): Promise<TurnAttachment[]>;
+/** The plain block appended to the turn text. Empty when there are no files. */
+export declare function attachmentTurnBlock(files: readonly TurnAttachment[]): string;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/lib/bot/attachments.js

@@ -0,0 +1,89 @@
+/**
+ * Chat attachments for local bot turns (`hq bot run`).
+ *
+ * A local bot's runtime (claude / codex / grok) runs without the `hq agent
+ * mcp` server, so it cannot call `hq_attachment_fetch`. The runner therefore
+ * downloads every file named on an inbox item BEFORE the turn, through the
+ * same validated path the MCP tool uses (`fetchChatAttachment`: key shape,
+ * DM-pair membership, company gate, size cap, private file), with the bot's
+ * own machine credentials, into the bot's own directory. The turn text gets a
+ * short block naming each file and where it is on disk; a file that could
+ * not be fetched gets a one-line reason instead of a path. Doing it in the
+ * runner makes it work the same for every runtime.
+ */
+import { fetchChatAttachment, sanitizeAttachmentFileName } from "../agent-kit/mcp/attachments.js";
+function oneLine(s, max = 300) {
+    const flat = s.replace(/\s+/g, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Download each attachment for one turn. Never throws: a per-file failure is
+ * returned as `error` (the caller logs it and shows it to the model), so one
+ * bad reference never costs the sender their reply.
+ */
+export async function downloadTurnAttachments(input) {
+    const out = [];
+    for (const ref of input.attachments) {
+        const name = sanitizeAttachmentFileName(ref.name || ref.vaultPath.split("/").pop() || "file");
+        const base = {
+            name,
+            ...(ref.contentType ? { contentType: ref.contentType } : {}),
+            ...(typeof ref.sizeBytes === "number" ? { sizeBytes: ref.sizeBytes } : {}),
+        };
+        if (!ref.companyUid) {
+            out.push({ ...base, error: "the message did not say which vault holds this file (no companyUid)" });
+            continue;
+        }
+        if (!input.download) {
+            out.push({ ...base, error: "this bot runner cannot download attachments" });
+            continue;
+        }
+        try {
+            const saved = await fetchChatAttachment({
+                vaultPath: ref.vaultPath,
+                scopeUid: ref.companyUid,
+                ...(ref.name ? { name: ref.name } : {}),
+                ...(ref.contentType ? { contentType: ref.contentType } : {}),
+                botEntityUid: input.botEntityUid,
+                resolveBotCompanyUids: input.resolveBotCompanyUids,
+                attachmentsDir: input.attachmentsDir,
+                download: input.download,
+            });
+            out.push({
+                name: saved.name,
+                ...(saved.contentType ? { contentType: saved.contentType } : {}),
+                sizeBytes: saved.sizeBytes,
+                localPath: saved.localPath,
+                ...(saved.text !== undefined ? { text: saved.text } : {}),
+                ...(saved.note ? { note: saved.note } : {}),
+            });
+        }
+        catch (err) {
+            out.push({ ...base, error: oneLine(err instanceof Error ? err.message : String(err)) });
+        }
+    }
+    return out;
+}
+/** The plain block appended to the turn text. Empty when there are no files. */
+export function attachmentTurnBlock(files) {
+    if (files.length === 0)
+        return "";
+    const lines = [`[Attached files: ${files.length}]`];
+    for (const f of files) {
+        const meta = [f.contentType, typeof f.sizeBytes === "number" ? `${f.sizeBytes} bytes` : undefined].filter(Boolean).join(", ");
+        const head = `- ${f.name}${meta ? ` (${meta})` : ""}`;
+        if (f.error || !f.localPath) {
+            lines.push(`${head}: not downloaded: ${f.error ?? "unknown error"}`);
+            continue;
+        }
+        lines.push(`${head}: saved at ${f.localPath}`);
+        if (f.text !== undefined) {
+            lines.push(`  Contents of ${f.name}:`, `----- begin ${f.name} -----`, f.text, `----- end ${f.name} -----`);
+        }
+        else if (f.note) {
+            lines.push(`  ${f.note.replace(/localPath/g, "the saved file")}`);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=attachments.js.map

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

@@ -63,6 +63,11 @@ export declare function botTokenStateDir(dir: string): string;
 export declare function botTurnCwd(dir: string): string;
 /** ~/.hq/bots/<name>/memory — "local" memory, outside the synced HQ tree. */
 export declare function botLocalMemoryDir(dir: string): string;
+/**
+ * ~/.hq/bots/<name>/attachments — chat attachments the runner downloads for a
+ * turn (dir 0700, files 0600), one subfolder per vault scope.
+ */
+export declare function botAttachmentsDir(dir: string): string;
 export declare function botLogsDir(dir: string): string;
 export declare function botLogPath(dir: string): string;
 export declare function launchdLabel(name: string): string;

package/dist/lib/bot/paths.js

@@ -108,6 +108,13 @@ export function botTurnCwd(dir) {
 export function botLocalMemoryDir(dir) {
     return path.join(dir, "memory");
 }
+/**
+ * ~/.hq/bots/<name>/attachments — chat attachments the runner downloads for a
+ * turn (dir 0700, files 0600), one subfolder per vault scope.
+ */
+export function botAttachmentsDir(dir) {
+    return path.join(dir, "attachments");
+}
 export function botLogsDir(dir) {
     return path.join(dir, BOT_LOGS_DIRNAME);
 }

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

@@ -50,6 +50,7 @@ import type { BotConfig, BotKind } from "./config.js";
 import { type ProgressPosterOptions } from "./progress.js";
 import { type BotLogger } from "./log.js";
 import { type BotRuntime, type RuntimeTurnInput, type RuntimeTurnResult } from "./runtime/index.js";
+import type { VaultObjectDownloader } from "../agent-kit/attachment-download.js";
 import { type HeartbeatAgentUidSource, type HeartbeatCredsSource, type HeartbeatIdentityMismatchReporter } from "../heartbeat-identity.js";
 import { type BotState, type BotStatusFile } from "./status.js";
 export declare const INBOX_POLL_INTERVAL_MS = 2000;
@@ -140,6 +141,12 @@ export interface BotRunDeps {
     maxParallelTurns?: number;
     /** Wait between retries while the coding tool needs a sign-in (default SIGN_IN_RETRY_MS). */
     signInRetryMs?: number;
+    /**
+     * Downloads a chat attachment's bytes with the bot's own machine identity
+     * (vault presign). Unset = attachments are listed with a "cannot download"
+     * reason instead of a path.
+     */
+    downloadAttachment?: VaultObjectDownloader;
     agentUidSource?: HeartbeatAgentUidSource;
     credsSource?: HeartbeatCredsSource;
     reportIdentityMismatch?: HeartbeatIdentityMismatchReporter;

package/dist/lib/bot/run.js

@@ -63,7 +63,9 @@ import { createBotLogger } from "./log.js";
 import { buildSystemPrompt, introDmText, readPromptSources } from "./prompt.js";
 import { FALLBACK_CLAUDE_PERMISSION_MODE, isClaudeBypassDisabled } from "./runtime/claude.js";
 import { runRuntimeTurn, RuntimeError } from "./runtime/index.js";
-import { dmSessionScope } from "./paths.js";
+import { botAttachmentsDir, dmSessionScope } from "./paths.js";
+import { attachmentTurnBlock, downloadTurnAttachments } from "./attachments.js";
+import { inboxEntryAttachments } from "../agent-kit/inbox-state.js";
 import { isDmItem, resolveReplyTarget } from "./room-policy.js";
 import { buildJobTurnPrompt, isCatchUpRun, isJobItem, jobReportHeader, jobRunOutput, machineTimeZone, planJobRuns, stripJobHeader, SUPERSEDED_DISPOSITION } from "./job-run.js";
 import { clearPendingJobCompletion, isCompletionDue, isCompletionExpired, isCompletionForOtherAgent, readPendingJobCompletions, recordPendingJobCompletion } from "./job-completions.js";
@@ -660,6 +662,7 @@ export async function runBot(deps) {
                         poster.message(event.text);
                 },
                 signal: controller.signal,
+                ...(args.readDirs?.length ? { readDirs: args.readDirs } : {}),
             });
             running = false;
             await poster.finish(turn.text);
@@ -1226,8 +1229,10 @@ export async function runBot(deps) {
             await handleJobItem(item, target);
             return;
         }
-        const text = (item.text ?? "").trim();
-        if (!text) {
+        const messageText = (item.text ?? "").trim();
+        // A message can be only a file (no text): that is still a message to answer.
+        const attachmentRefs = inboxEntryAttachments(item);
+        if (!messageText && attachmentRefs.length === 0) {
             markProcessed(dir, id, now().toISOString());
             await api.ackInbox(config.agentUid, id);
             return;
@@ -1237,7 +1242,7 @@ export async function runBot(deps) {
         const reactionId = item.eventId ?? id;
         const tReceived = now().getTime();
         const where = target.kind === "room" ? `room ${target.channelId}` : "dm";
-        log("info", `received ${id} (${text.length} chars, ${where})`);
+        log("info", `received ${id} (${messageText.length} chars${attachmentRefs.length ? `, ${attachmentRefs.length} attachment${attachmentRefs.length === 1 ? "" : "s"}` : ""}, ${where})`);
         // Rooms: an UNMENTIONED responder (a plain room message)
         // claims first so the owner's several bots produce one answer, not one
         // each. A bot that was @mentioned never claims — it was asked by name and
@@ -1267,6 +1272,30 @@ export async function runBot(deps) {
                 await api.setReaction({ peerUid: target.peerUid, messageId: reactionId, emoji: THINKING_EMOJI }, false);
             }
         };
+        // Attachments are fetched here, in the runner, so every runtime sees them
+        // the same way: the turn text names each saved file (or why it is missing).
+        let text = messageText;
+        const readDirs = [];
+        if (attachmentRefs.length > 0) {
+            const attachmentsDir = botAttachmentsDir(dir);
+            const files = await downloadTurnAttachments({
+                attachments: attachmentRefs,
+                botEntityUid: config.agentUid,
+                attachmentsDir,
+                resolveBotCompanyUids: async () => (await api.getAgent(config.agentUid)).companyMemberships ?? [],
+                ...(deps.downloadAttachment ? { download: deps.downloadAttachment } : {}),
+            });
+            for (const f of files) {
+                if (f.error)
+                    log("warn", `attachment ${f.name} on ${id} not downloaded: ${f.error}`);
+                else
+                    log("info", `attachment ${f.name} on ${id} saved (${f.sizeBytes ?? 0} bytes)`);
+            }
+            if (files.some((f) => f.localPath))
+                readDirs.push(attachmentsDir);
+            const block = attachmentTurnBlock(files);
+            text = text ? `${text}\n\n${block}` : block;
+        }
         const sessionScope = target.kind === "room" ? target.sessionScope : dmSessionScope(target.peerUid, config.ownerUid);
         const prompt = target.kind === "room" ? await buildRoomTurn(item, target, text) : target.peerUid === config.ownerUid ? text :
             `[HQ DM sender: ${target.peerUid}; owner: ${config.ownerUid}; sender is not the owner.]\n\n${text}`;
@@ -1284,6 +1313,7 @@ export async function runBot(deps) {
             tReceived,
             send,
             workingNotice: !isSetupBot,
+            ...(readDirs.length ? { readDirs } : {}),
             ...(target.kind === "room"
                 ? { afterProgressPost: () => api.postAgentStatus(target.channelId, ROOM_THINKING_STATUS, target.rootEventId) }
                 : {}),

package/dist/lib/bot/runtime/claude.d.ts

@@ -7,6 +7,7 @@
  *   when the bot's autoApprove is false; HQ_BOT_CLAUDE_PERMISSION_MODE
  *   overrides both)
  *          --append-system-prompt-file <file> --effort <level> [--model m]
+ *          [--add-dir <hqRoot>] [--add-dir <attachments dir>]
  *          (--session-id <uuid> | --resume <uuid>)
  *
  * stdout is NDJSON (see messages-stream.ts): each finished assistant message

package/dist/lib/bot/runtime/claude.js

@@ -7,6 +7,7 @@
  *   when the bot's autoApprove is false; HQ_BOT_CLAUDE_PERMISSION_MODE
  *   overrides both)
  *          --append-system-prompt-file <file> --effort <level> [--model m]
+ *          [--add-dir <hqRoot>] [--add-dir <attachments dir>]
  *          (--session-id <uuid> | --resume <uuid>)
  *
  * stdout is NDJSON (see messages-stream.ts): each finished assistant message
@@ -134,6 +135,11 @@ export function createClaudeRuntime(env = process.env) {
             // Keep the HQ tree writable even if a caller runs the turn elsewhere.
             if (input.hqRoot && input.hqRoot !== input.cwd)
                 args.push("--add-dir", input.hqRoot);
+            // Downloaded attachments live in the bot's own dir, outside the HQ tree.
+            for (const d of input.readDirs ?? []) {
+                if (d && d !== input.cwd && d !== input.hqRoot)
+                    args.push("--add-dir", d);
+            }
             if (input.model)
                 args.push("--model", input.model);
             if (input.sessionId)

package/dist/lib/bot/runtime/types.d.ts

@@ -21,6 +21,14 @@ export interface RuntimeTurnInput {
     /** The owner's HQ root: runtimes with a write sandbox must allow it too,
      *  or the bot cannot edit its own memory notes under personal/workers/. */
     hqRoot?: string;
+    /**
+     * Directories outside cwd/hqRoot the turn must be able to READ (the bot's
+     * downloaded chat attachments). Claude restricts file tools to its working
+     * dirs outside bypassPermissions, so it gets `--add-dir` for each. Codex
+     * (read-anywhere in every sandbox mode) and Grok (--always-approve / ACP
+     * auto-allow) already read them and ignore this.
+     */
+    readDirs?: string[];
     /** Previous session id to resume, if any. */
     sessionId?: string;
     /** Optional model override. */

package/package.json

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