@indigoai-us/hq-cli 5.314.0 → 5.316.0

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

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

@@ -0,0 +1,75 @@
+/**
+ * Minimal stdio MCP server core (JSON-RPC 2.0, newline-delimited).
+ *
+ * hq-cli carries no MCP SDK dependency and the full HQ MCP surface lives in
+ * the separate @indigoai-us/hq-mcp package (a bin, not a library). `hq agent
+ * mcp` needs only the tools subset of the protocol — initialize, ping,
+ * tools/list, tools/call — so this module implements exactly that over a
+ * transport-agnostic `dispatch()` (tests drive it directly) plus a stdio
+ * pump. Every request is answered; notifications are consumed silently;
+ * malformed input yields a JSON-RPC error rather than a crash.
+ */
+export interface JsonRpcResponse {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export declare const JSONRPC_PARSE_ERROR = -32700;
+export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface McpToolContent {
+    type: "text";
+    text: string;
+}
+export interface McpToolResult {
+    content: McpToolContent[];
+    isError?: boolean;
+}
+type McpToolHandler = (args: Record<string, unknown>) => Promise<McpToolResult>;
+export interface McpTool extends McpToolDefinition {
+    handler: McpToolHandler;
+}
+export interface McpServerOptions {
+    name: string;
+    version: string;
+    instructions?: string;
+    tools: McpTool[];
+}
+export declare class McpToolInputError extends Error {
+    constructor(message: string);
+}
+export declare function textResult(text: string): McpToolResult;
+export declare function errorResult(text: string): McpToolResult;
+export declare class McpServer {
+    private readonly opts;
+    private readonly tools;
+    private initialized;
+    constructor(opts: McpServerOptions);
+    listTools(): McpToolDefinition[];
+    /**
+     * Handle one decoded message. Returns null for notifications (no reply)
+     * and for responses the client sends us (we issue no requests).
+     */
+    dispatch(message: unknown): Promise<JsonRpcResponse | null>;
+    /** Decode one line, dispatch, and encode the reply (or null). */
+    handleLine(line: string): Promise<string | null>;
+    isInitialized(): boolean;
+    /**
+     * Pump newline-delimited messages from `input` to `output` until EOF.
+     * Requests are processed strictly in order so tool side effects (a DM
+     * send, a secrets exec) never interleave.
+     */
+    serve(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<void>;
+}
+export {};
+//# sourceMappingURL=jsonrpc.d.ts.map

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

@@ -0,0 +1,164 @@
+/**
+ * Minimal stdio MCP server core (JSON-RPC 2.0, newline-delimited).
+ *
+ * hq-cli carries no MCP SDK dependency and the full HQ MCP surface lives in
+ * the separate @indigoai-us/hq-mcp package (a bin, not a library). `hq agent
+ * mcp` needs only the tools subset of the protocol — initialize, ping,
+ * tools/list, tools/call — so this module implements exactly that over a
+ * transport-agnostic `dispatch()` (tests drive it directly) plus a stdio
+ * pump. Every request is answered; notifications are consumed silently;
+ * malformed input yields a JSON-RPC error rather than a crash.
+ */
+const MCP_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+const MCP_LATEST_PROTOCOL_VERSION = MCP_PROTOCOL_VERSIONS[0];
+export const JSONRPC_PARSE_ERROR = -32700;
+const JSONRPC_INVALID_REQUEST = -32600;
+export const JSONRPC_METHOD_NOT_FOUND = -32601;
+export const JSONRPC_INVALID_PARAMS = -32602;
+const JSONRPC_INTERNAL_ERROR = -32603;
+export class McpToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "McpToolInputError";
+    }
+}
+export function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+export function errorResult(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function ok(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function fail(id, code, message, data) {
+    return { jsonrpc: "2.0", id, error: { code, message, ...(data !== undefined ? { data } : {}) } };
+}
+export class McpServer {
+    opts;
+    tools = new Map();
+    initialized = false;
+    constructor(opts) {
+        this.opts = opts;
+        for (const tool of opts.tools) {
+            if (this.tools.has(tool.name))
+                throw new Error(`duplicate MCP tool ${tool.name}`);
+            this.tools.set(tool.name, tool);
+        }
+    }
+    listTools() {
+        return [...this.tools.values()].map(({ name, description, inputSchema }) => ({
+            name,
+            description,
+            inputSchema,
+        }));
+    }
+    /**
+     * Handle one decoded message. Returns null for notifications (no reply)
+     * and for responses the client sends us (we issue no requests).
+     */
+    async dispatch(message) {
+        if (!message || typeof message !== "object" || Array.isArray(message)) {
+            return fail(null, JSONRPC_INVALID_REQUEST, "expected a JSON-RPC object");
+        }
+        const msg = message;
+        if (typeof msg.method !== "string") {
+            // A response to a server-initiated request; we never send any.
+            if ("result" in msg || "error" in msg)
+                return null;
+            return fail(msg.id ?? null, JSONRPC_INVALID_REQUEST, "missing method");
+        }
+        const isNotification = msg.id === undefined;
+        const id = msg.id ?? null;
+        const params = (msg.params && typeof msg.params === "object" ? msg.params : {});
+        if (isNotification) {
+            if (msg.method === "notifications/initialized")
+                this.initialized = true;
+            return null;
+        }
+        switch (msg.method) {
+            case "initialize": {
+                const requested = typeof params.protocolVersion === "string" ? params.protocolVersion : "";
+                const protocolVersion = MCP_PROTOCOL_VERSIONS.includes(requested)
+                    ? requested
+                    : MCP_LATEST_PROTOCOL_VERSION;
+                return ok(id, {
+                    protocolVersion,
+                    capabilities: { tools: { listChanged: false } },
+                    serverInfo: { name: this.opts.name, version: this.opts.version },
+                    ...(this.opts.instructions ? { instructions: this.opts.instructions } : {}),
+                });
+            }
+            case "ping":
+                return ok(id, {});
+            case "tools/list":
+                return ok(id, { tools: this.listTools() });
+            case "tools/call": {
+                const name = typeof params.name === "string" ? params.name : "";
+                const tool = this.tools.get(name);
+                if (!tool)
+                    return fail(id, JSONRPC_INVALID_PARAMS, `unknown tool: ${name || "(missing name)"}`);
+                const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
+                    ? params.arguments
+                    : {};
+                try {
+                    return ok(id, await tool.handler(args));
+                }
+                catch (err) {
+                    if (err instanceof McpToolInputError)
+                        return fail(id, JSONRPC_INVALID_PARAMS, err.message);
+                    // Tool execution failures are results, not protocol errors, so the
+                    // model can read and react to them.
+                    return ok(id, errorResult(err instanceof Error ? err.message : String(err)));
+                }
+            }
+            default:
+                return fail(id, JSONRPC_METHOD_NOT_FOUND, `method not found: ${msg.method}`);
+        }
+    }
+    /** Decode one line, dispatch, and encode the reply (or null). */
+    async handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return JSON.stringify(fail(null, JSONRPC_PARSE_ERROR, "invalid JSON"));
+        }
+        const reply = await this.dispatch(parsed);
+        return reply ? JSON.stringify(reply) : null;
+    }
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Pump newline-delimited messages from `input` to `output` until EOF.
+     * Requests are processed strictly in order so tool side effects (a DM
+     * send, a secrets exec) never interleave.
+     */
+    async serve(input, output) {
+        let buffer = "";
+        const write = (s) => new Promise((resolve, reject) => output.write(`${s}\n`, (err) => (err ? reject(err) : resolve())));
+        input.setEncoding("utf8");
+        for await (const chunk of input) {
+            buffer += chunk;
+            let nl;
+            while ((nl = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, nl);
+                buffer = buffer.slice(nl + 1);
+                const reply = await this.handleLine(line);
+                if (reply)
+                    await write(reply);
+            }
+        }
+        if (buffer.trim()) {
+            const reply = await this.handleLine(buffer);
+            if (reply)
+                await write(reply);
+        }
+    }
+}
+//# sourceMappingURL=jsonrpc.js.map

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

@@ -0,0 +1,64 @@
+/**
+ * The `hq agent mcp` tool surface. Each tool wraps an existing hq CLI
+ * capability so a bot framework (OpenClaw, grokbot, any MCP client)
+ * can act as the enrolled agent without a token ever crossing the MCP
+ * channel: the machine identity lives in machine-creds.json and every call
+ * mints through hq-cloud.
+ *
+ * Two seams keep this testable and honest:
+ *   - `runHq(args)` — spawn the SAME hq binary for capabilities that are
+ *     already complete CLI commands (search, files, secrets exec, work mesh).
+ *   - `api` — token + vault-API fetch for the notify surface (DM, inbox).
+ *
+ * `hq_secrets_exec` runs a command with secrets injected and returns ONLY
+ * the command's exit code and (bounded) output — never an environment dump,
+ * never a secret value. `hq_secrets_list` names secrets; values are never a
+ * tool result.
+ */
+import type { ExternalMachineCreds } from "../creds.js";
+import type { AgentKitPaths } from "../paths.js";
+import { type McpTool } from "./jsonrpc.js";
+export interface HqRunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export interface McpToolClients {
+    creds: ExternalMachineCreds;
+    /**
+     * Kit layout; the inbox tools read the mirror and done-state here, and
+     * `hq_attachment_fetch` writes downloaded attachments under attachmentsDir.
+     */
+    paths: Pick<AgentKitPaths, "inboxDir" | "attachmentsDir">;
+    /** Run `hq <args…>` as the machine identity; never throws. */
+    runHq: (args: string[]) => Promise<HqRunResult>;
+    getToken: () => Promise<string>;
+    /**
+     * Whether this kit mirrors the vault to disk. Off by default, and it decides
+     * what `hq_search` can honestly do: the local qmd index only exists when
+     * there is a local copy to index, so without one the search is a server-side
+     * match on file names and paths, not on contents.
+     */
+    syncFiles?: boolean;
+    /** The cmp_ uid of this agent's enrolled company (creds.companySlug). */
+    resolveCompanyUid: () => Promise<string>;
+    /**
+     * Read one vault object's bytes by scope uid (cmp_/prs_) + scope-relative
+     * key through the presign API, as the machine identity.
+     */
+    downloadVaultObject: (scopeUid: string, key: string) => Promise<Buffer>;
+    /** Authenticated JSON call against the control plane. */
+    apiJson: (token: string, path: string, init?: {
+        method?: string;
+        body?: Record<string, unknown>;
+        query?: Record<string, string>;
+    }) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export declare function clampOutput(text: string, max?: number): string;
+/** Vault paths are company-anchored and must not escape. */
+export declare function assertVaultPath(p: string): string;
+export declare function buildAgentMcpTools(clients: McpToolClients): McpTool[];
+//# sourceMappingURL=tools.d.ts.map