@indigoai-us/hq-cli 5.155.0 → 5.157.0

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/dist/lib/lanes/mesh-events.d.ts

@@ -42,11 +42,11 @@
  * of opening a browser nobody is watching, and the watcher records
  * `mesh_event_failed` and moves on. No credential file is read here.
  */
-import type { LaneCompanyRef, LaneEnvelope, LaneRecord } from "./types.js";
-export declare const LANE_MESH_EVENTS: readonly ["lane_started", "lane_progress", "lane_question", "lane_question_at_user", "lane_ask", "lane_blocked", "lane_done"];
+import type { LaneCompanyRef, LaneEnvelope, LaneRecord, TerminalLaneState } from "./types.js";
+export declare const LANE_MESH_EVENTS: readonly ["lane_started", "lane_progress", "lane_question", "lane_question_at_user", "lane_ask", "lane_blocked", "lane_done", "lane_failed", "lane_interrupted", "lane_cancelled", "lane_killed"];
 export type LaneMeshEvent = (typeof LANE_MESH_EVENTS)[number];
 /** Roster kinds this module emits. Subset of the server's `validKinds`. */
-export declare const WIRE_EVENT_KINDS: readonly ["run_started", "run_progress", "run_complete", "question", "note"];
+export declare const WIRE_EVENT_KINDS: readonly ["run_started", "run_progress", "run_complete", "blocked", "question", "note"];
 export type WireEventKind = (typeof WIRE_EVENT_KINDS)[number];
 /** Server caps: activity title/summary 2000, question text 500, note text 500. */
 export declare const WIRE_ACTIVITY_TEXT_MAX = 2000;
@@ -70,6 +70,7 @@ export declare function toWireThreadEvent(event: LaneMeshEvent, payload: Record<
  */
 export interface LaneMesh {
     ensureProjectThread: (company: LaneCompanyRef, projectId: string) => Promise<string>;
+    ensureLaneThread?: (company: LaneCompanyRef, lane: LaneRecord, laneStatus?: string, signal?: AbortSignal) => Promise<string>;
     appendThreadEvent: (company: LaneCompanyRef, threadId: string, event: LaneMeshEvent, payload: Record<string, unknown>, signal?: AbortSignal) => Promise<void>;
     patchStoryStatus: (company: LaneCompanyRef, projectId: string, storyId: string, status: string) => Promise<void>;
 }
@@ -92,6 +93,7 @@ export declare function createLaneMesh(opts?: CreateLaneMeshOptions): LaneMesh;
 export declare function laneMeshCompany(lane: Pick<LaneRecord, "company" | "mesh_company">): LaneCompanyRef | undefined;
 /** Company attribution + thread present. Unscoped personal lanes emit nothing. */
 export declare function laneCanEmit(lane: Pick<LaneRecord, "company" | "mesh_company" | "thread_id">): boolean;
+export declare function laneMeshEventIdentity(lane: LaneRecord): Record<string, unknown>;
 /**
  * Spec §8 terminal-envelope events. `done` → lane_done and story → review;
  * `blocked` → lane_blocked; `ask` → lane_ask with the queue ids. The story is
@@ -101,6 +103,8 @@ export declare function emitLaneDecisionEvents(mesh: LaneMesh, lane: LaneRecord,
     questionIds?: string[];
     signal?: AbortSignal;
 }): Promise<void>;
+/** Emit an abnormal terminal state even when the worker produced no envelope. */
+export declare function emitLaneTerminalStateEvent(mesh: LaneMesh, lane: LaneRecord, state: Exclude<TerminalLaneState, "done">, summary?: string, signal?: AbortSignal): Promise<void>;
 export declare function emitLaneProgressEvent(mesh: LaneMesh, lane: LaneRecord, detail: string, signal?: AbortSignal): Promise<void>;
 /**
  * Throttle for lane_progress (spec §8 progress row). True when no progress