@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,83 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export interface MirroredInboxEntry {
+    id: string;
+    mirroredAt?: string;
+    [key: string]: unknown;
+}
+export declare function readDoneIds(paths: Pick<AgentKitPaths, "inboxDir">): Set<string>;
+export declare function markInboxDone(paths: Pick<AgentKitPaths, "inboxDir">, ids: string[]): string[];
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export declare function readMirroredInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+export declare function pendingInbox(paths: Pick<AgentKitPaths, "inboxDir">): MirroredInboxEntry[];
+/** One file reference carried on an inbox item (US-007 chat attachments). */
+export interface InboxAttachment {
+    vaultPath: string;
+    name?: string;
+    contentType?: string;
+    sizeBytes?: number;
+    companyUid?: string;
+}
+/**
+ * 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 | {
+    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
+ * as a bot is concerned — omitting them made an agent answer "no image came
+ * through" for a DM that carried a screenshot.
+ */
+export declare function summarizeInboxEntry(e: MirroredInboxEntry, done: boolean): {
+    done: boolean;
+    attachments?: InboxAttachment[] | undefined;
+    id: string;
+    channel: string | undefined;
+    channelId: string | undefined;
+    from: string;
+    fromUid: string | undefined;
+    at: string | undefined;
+    text: string | undefined;
+};
+/**
+ * The agent's inbox as the bot should see it: the kit's local mirror merged
+ * with the agent's own server inbox.
+ *
+ * Reading the mirror ALONE is a silent-blindness bug. The mirror is only as
+ * fresh as the kit's poller, and when that process dies nothing says so — the
+ * listing simply stops growing. Observed on the Muse pilot: its host rebooted,
+ * the kit supervisor died with it and was never restarted, and `hq agent
+ * inbox` kept answering with the eight messages from before the reboot while
+ * the server had every newer one. No error, no empty result, no stale marker —
+ * just an agent that had gone deaf and could not tell.
+ *
+ * So the server is consulted on every read and anything it knows about that
+ * the mirror lacks is included. When the server cannot be reached the mirror
+ * is still returned, with a `note` naming the degradation: a partial answer
+ * that says it is partial beats a confident wrong one.
+ */
+export interface MergedInbox {
+    entries: MirroredInboxEntry[];
+    /** Set when the server could not be consulted, so the caller can say so. */
+    note?: string;
+}
+export declare function mergeAgentInbox(paths: Pick<AgentKitPaths, "inboxDir">, fetchServerInbox: () => Promise<{
+    status: number;
+    body: unknown;
+}>): Promise<MergedInbox>;
+//# sourceMappingURL=inbox-state.d.ts.map

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

@@ -0,0 +1,159 @@
+/**
+ * Local handled-state for the external agent's mirrored inbox.
+ *
+ * The inbox poller appends every new item to ~/.hq-agent/inbox/inbox.jsonl.
+ * A bot marks an item handled with `hq agent inbox done <id>` (or the
+ * `hq_inbox_done` MCP tool); ids land in done-ids.json. "Pending" is every
+ * mirrored item whose id is not done, oldest first. This works the same
+ * whether or not the kit acks on the server (`inboxAck`), so a woken bot can
+ * always drain exactly what it has not handled yet and never reply twice.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { writePrivateFile } from "./private-file.js";
+const DONE_IDS_NAME = "done-ids.json";
+const MAX_DONE_IDS = 5000;
+const INBOX_JSONL = "inbox.jsonl";
+export function readDoneIds(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(paths.inboxDir, DONE_IDS_NAME), "utf8"));
+        return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === "string") : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+export function markInboxDone(paths, ids) {
+    const done = readDoneIds(paths);
+    const added = [];
+    for (const id of ids) {
+        if (!done.has(id)) {
+            done.add(id);
+            added.push(id);
+        }
+    }
+    writePrivateFile(path.join(paths.inboxDir, DONE_IDS_NAME), JSON.stringify([...done].slice(-MAX_DONE_IDS)), 0o600);
+    return added;
+}
+/** Every mirrored entry, oldest first, de-duplicated by id (last write wins). */
+export function readMirroredInbox(paths) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(paths.inboxDir, INBOX_JSONL), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const byId = new Map();
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const entry = JSON.parse(line);
+            if (typeof entry.id === "string" && entry.id) {
+                byId.delete(entry.id);
+                byId.set(entry.id, entry);
+            }
+        }
+        catch {
+            /* skip a torn line */
+        }
+    }
+    return [...byId.values()];
+}
+export function pendingInbox(paths) {
+    const done = readDoneIds(paths);
+    return readMirroredInbox(paths).filter((e) => !done.has(e.id));
+}
+/**
+ * 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 function inboxEntryAttachments(e) {
+    const raw = Array.isArray(e.attachments)
+        ? e.attachments
+        : e.attachment
+            ? [e.attachment]
+            : [];
+    const out = [];
+    for (const entry of raw) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const rec = entry;
+        const vaultPath = typeof rec.vaultPath === "string" ? rec.vaultPath.trim() : "";
+        if (!vaultPath)
+            continue;
+        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") } : {}),
+            ...(contentType ? { contentType } : {}),
+            ...(typeof rec.sizeBytes === "number" ? { sizeBytes: rec.sizeBytes } : {}),
+            ...(str("companyUid") ? { companyUid: str("companyUid") } : {}),
+        });
+    }
+    return out;
+}
+/**
+ * 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
+ * as a bot is concerned — omitting them made an agent answer "no image came
+ * through" for a DM that carried a screenshot.
+ */
+export function summarizeInboxEntry(e, done) {
+    const pick = (...keys) => {
+        for (const k of keys)
+            if (typeof e[k] === "string" && e[k])
+                return e[k];
+        return undefined;
+    };
+    const attachments = inboxEntryAttachments(e);
+    return {
+        id: e.id,
+        channel: pick("channel"),
+        // Set when the message arrived in a channel or group DM. Reply there
+        // (`hq dm <channelId> "…"`), not to the sender privately.
+        channelId: pick("channelId"),
+        from: pick("fromDisplayName", "fromEmail", "fromPersonUid") ?? "unknown",
+        fromUid: pick("fromPersonUid"),
+        at: pick("receivedAt", "createdAt", "mirroredAt"),
+        text: pick("text", "body"),
+        ...(attachments.length ? { attachments } : {}),
+        done,
+    };
+}
+export async function mergeAgentInbox(paths, fetchServerInbox) {
+    const byId = new Map();
+    for (const e of readMirroredInbox(paths))
+        byId.set(e.id, e);
+    let note;
+    try {
+        const res = await fetchServerInbox();
+        if (res.status === 200) {
+            const messages = res.body?.messages;
+            for (const m of Array.isArray(messages) ? messages : []) {
+                if (!m || typeof m !== "object")
+                    continue;
+                const raw = m;
+                const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
+                if (id && !byId.has(id))
+                    byId.set(id, { ...raw, id });
+            }
+        }
+        else {
+            note = `server inbox answered ${res.status}; showing the local mirror only, which may be stale`;
+        }
+    }
+    catch (err) {
+        note = `server inbox unavailable (${err instanceof Error ? err.message : String(err)}); showing the local mirror only, which may be stale`;
+    }
+    return { entries: [...byId.values()], ...(note ? { note } : {}) };
+}
+//# sourceMappingURL=inbox-state.js.map

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

@@ -0,0 +1,56 @@
+/**
+ * ~/.hq-agent/kit.json — settings `hq agent kit install` records so the
+ * services (which only receive `hq agent kit run <service>`) know where to
+ * sync and how often. Kept separate from machine-creds.json, which is the
+ * contract-shaped credential file and nothing else.
+ */
+import { type AgentKitPaths, type KitComponent } from "./paths.js";
+export interface KitConfig {
+    /** Local HQ tree the company vault syncs into (companies/<slug>/ …). */
+    hqRoot: string;
+    syncIntervalMs: number;
+    inboxPollMs: number;
+    heartbeatIntervalMs: number;
+    meshRefreshMs: number;
+    /** Ack mirrored inbox items on the server after writing them locally. */
+    inboxAck: boolean;
+    /**
+     * Mirror the company vault onto local disk.
+     *
+     * Off by default. An external bot reads and writes vault files on demand
+     * through the `hq` MCP server (hq_files_read / hq_files_list /
+     * hq_files_write) and the `hq files` CLI, so a local mirror buys nothing
+     * for the common case and costs a full copy of the company's assets — on a
+     * team with a large brand library that is hundreds of megabytes, and on a
+     * sandboxed bot host whose egress proxy truncates large responses it can
+     * never finish at all (every file retried three times, all failing with
+     * ERR_HQ_TRUNCATED_RESPONSE, leaving the probe stuck and component-sync in
+     * error while the bot was otherwise a healthy team member).
+     *
+     * Turn it on with `hq agent kit install --sync-files` when the bot genuinely
+     * needs files on disk for shell-based work (grep, build tools, a local
+     * index).
+     *
+     * A kit.json written before this field existed reads as `false`, the same as
+     * a fresh install. Reading it as `true` (its behaviour at the time) was the
+     * safer-looking choice and was wrong: the bots with such a file are exactly
+     * the ones the mirror is failing on, and because a bare reinstall preserves
+     * recorded settings, the documented fix — reinstall the kit — left the sync
+     * loop running and the probe still pulling. A bot that genuinely wants the
+     * mirror passes `--sync-files` once.
+     */
+    syncFiles: boolean;
+    installedAt: string;
+    cliVersion: string;
+}
+/**
+ * Kit components whose health this install actually reports. `sync` drops out
+ * when the vault is not mirrored to disk — there is no loop to be healthy or
+ * unhealthy, so reporting it either way would be a lie.
+ */
+export declare function enabledKitComponents(config: Pick<KitConfig, "syncFiles">): readonly KitComponent[];
+export declare function defaultKitConfig(paths: Pick<AgentKitPaths, "agentDir">, cliVersion: string, now?: () => Date): KitConfig;
+export declare function writeKitConfig(paths: Pick<AgentKitPaths, "kitConfigPath">, config: KitConfig): void;
+/** Read kit.json, falling back to defaults for any missing/invalid field. */
+export declare function readKitConfig(paths: Pick<AgentKitPaths, "kitConfigPath" | "agentDir">, cliVersion: string): KitConfig;
+//# sourceMappingURL=kit-config.d.ts.map

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

@@ -0,0 +1,65 @@
+/**
+ * ~/.hq-agent/kit.json — settings `hq agent kit install` records so the
+ * services (which only receive `hq agent kit run <service>`) know where to
+ * sync and how often. Kept separate from machine-creds.json, which is the
+ * contract-shaped credential file and nothing else.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { KIT_COMPONENTS } from "./paths.js";
+import { writePrivateFile } from "./private-file.js";
+const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
+const DEFAULT_INBOX_POLL_MS = 15_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
+const DEFAULT_MESH_REFRESH_MS = 5 * 60_000;
+/**
+ * Kit components whose health this install actually reports. `sync` drops out
+ * when the vault is not mirrored to disk — there is no loop to be healthy or
+ * unhealthy, so reporting it either way would be a lie.
+ */
+export function enabledKitComponents(config) {
+    return KIT_COMPONENTS.filter((c) => c !== "sync" || config.syncFiles);
+}
+function defaultHqRoot(paths) {
+    return path.join(paths.agentDir, "hq");
+}
+export function defaultKitConfig(paths, cliVersion, now = () => new Date()) {
+    return {
+        hqRoot: defaultHqRoot(paths),
+        syncIntervalMs: DEFAULT_SYNC_INTERVAL_MS,
+        inboxPollMs: DEFAULT_INBOX_POLL_MS,
+        heartbeatIntervalMs: DEFAULT_HEARTBEAT_INTERVAL_MS,
+        meshRefreshMs: DEFAULT_MESH_REFRESH_MS,
+        inboxAck: false,
+        syncFiles: false,
+        installedAt: now().toISOString(),
+        cliVersion,
+    };
+}
+export function writeKitConfig(paths, config) {
+    writePrivateFile(paths.kitConfigPath, `${JSON.stringify(config, null, 2)}\n`, 0o600);
+}
+/** Read kit.json, falling back to defaults for any missing/invalid field. */
+export function readKitConfig(paths, cliVersion) {
+    const base = defaultKitConfig(paths, cliVersion);
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(paths.kitConfigPath, "utf8"));
+    }
+    catch {
+        return base;
+    }
+    const num = (k) => typeof raw[k] === "number" && raw[k] > 0 ? raw[k] : base[k];
+    return {
+        hqRoot: typeof raw.hqRoot === "string" && raw.hqRoot ? raw.hqRoot : base.hqRoot,
+        syncIntervalMs: num("syncIntervalMs"),
+        inboxPollMs: num("inboxPollMs"),
+        heartbeatIntervalMs: num("heartbeatIntervalMs"),
+        meshRefreshMs: num("meshRefreshMs"),
+        inboxAck: raw.inboxAck === true,
+        syncFiles: raw.syncFiles === true,
+        installedAt: typeof raw.installedAt === "string" ? raw.installedAt : base.installedAt,
+        cliVersion: typeof raw.cliVersion === "string" ? raw.cliVersion : base.cliVersion,
+    };
+}
+//# sourceMappingURL=kit-config.js.map

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

@@ -0,0 +1,16 @@
+/**
+ * Per-service log under ~/.hq-agent/logs/<service>.log, rotated at 5 MB.
+ * Lines are sanitized so a bearer token or secret reference can never land
+ * on disk even through an error message.
+ */
+import type { AgentKitPaths } from "./paths.js";
+export type KitLogLevel = "info" | "warn" | "error";
+export type KitLogger = (level: KitLogLevel, message: string) => void;
+export declare function sanitizeLogLine(message: string): string;
+export declare function formatKitLogLine(level: KitLogLevel, message: string, now?: () => Date): string;
+export declare function createKitLogger(paths: Pick<AgentKitPaths, "logsDir">, service: string, opts?: {
+    now?: () => Date;
+    echo?: boolean;
+    maxBytes?: number;
+}): KitLogger;
+//# sourceMappingURL=log.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Per-service log under ~/.hq-agent/logs/<service>.log, rotated at 5 MB.
+ * Lines are sanitized so a bearer token or secret reference can never land
+ * on disk even through an error message.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { serviceLogPath } from "./paths.js";
+const KIT_LOG_MAX_BYTES = 5 * 1024 * 1024;
+export function sanitizeLogLine(message) {
+    return message
+        .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]")
+        .replace(/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g, "[JWT REDACTED]")
+        .replace(/"secret"\s*:\s*"[^"]*"/g, '"secret":"[REDACTED]"')
+        .replace(/\r?\n/g, " ")
+        .slice(0, 1000);
+}
+export function formatKitLogLine(level, message, now = () => new Date()) {
+    return `${now().toISOString()} ${level} ${sanitizeLogLine(message)}`;
+}
+export function createKitLogger(paths, service, opts = {}) {
+    const file = serviceLogPath(paths, service);
+    const maxBytes = opts.maxBytes ?? KIT_LOG_MAX_BYTES;
+    return (level, message) => {
+        const line = formatKitLogLine(level, message, opts.now);
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+            try {
+                if (fs.statSync(file).size > maxBytes) {
+                    fs.renameSync(file, `${file}.1`);
+                }
+            }
+            catch {
+                /* no file yet */
+            }
+            fs.appendFileSync(file, `${line}\n`, { mode: 0o600 });
+        }
+        catch {
+            /* best-effort */
+        }
+        if (opts.echo) {
+            (level === "error" ? process.stderr : process.stdout).write(`${line}\n`);
+        }
+    };
+}
+//# sourceMappingURL=log.js.map

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

@@ -0,0 +1,126 @@
+/**
+ * `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;
+    /** 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. */
+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>;
+/** 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