@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -0,0 +1,397 @@
+/**
+ * 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 { 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 { AttachmentCompanyUnresolvedError, fetchChatAttachment } from "./attachments.js";
+import { errorResult, McpToolInputError, textResult } from "./jsonrpc.js";
+const MAX_TOOL_OUTPUT_CHARS = 40_000;
+const ATTACHMENTS_HINT = "Some messages carry files. For each entry in a message's `attachments` whose vaultPath starts with chat/attachments/, " +
+    "call hq_attachment_fetch with that vaultPath and companyUid to download it; hq_files_read cannot open message attachments. " +
+    "Anything else (a folder or shared vault path) is not a chat attachment: use hq_files_list / hq_files_read for those.";
+function str(args, key, opts = {}) {
+    const v = args[key];
+    if (v === undefined || v === null) {
+        if (opts.required)
+            throw new McpToolInputError(`"${key}" is required`);
+        return undefined;
+    }
+    if (typeof v !== "string")
+        throw new McpToolInputError(`"${key}" must be a string`);
+    if (opts.required && v.trim().length === 0)
+        throw new McpToolInputError(`"${key}" must not be empty`);
+    if (opts.max !== undefined && v.length > opts.max)
+        throw new McpToolInputError(`"${key}" exceeds ${opts.max} characters`);
+    return v;
+}
+function int(args, key, opts) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return opts.fallback;
+    if (typeof v !== "number" || !Number.isInteger(v))
+        throw new McpToolInputError(`"${key}" must be an integer`);
+    return Math.min(opts.max, Math.max(opts.min, v));
+}
+function strList(args, key) {
+    const v = args[key];
+    if (!Array.isArray(v) || v.length === 0 || !v.every((x) => typeof x === "string" && x.length > 0)) {
+        throw new McpToolInputError(`"${key}" must be a non-empty array of strings`);
+    }
+    return v;
+}
+export function clampOutput(text, max = MAX_TOOL_OUTPUT_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}\n… [truncated ${text.length - max} chars]` : text;
+}
+/** Vault paths are company-anchored and must not escape. */
+export function assertVaultPath(p) {
+    const clean = p.trim().replace(/^\/+/, "");
+    if (!/^companies\/[a-z0-9][a-z0-9-]*(\/[^\0]*)?$/i.test(clean) || clean.split("/").includes("..")) {
+        throw new McpToolInputError(`"path" must be vault-relative and start with companies/<slug>/ (got ${JSON.stringify(p)})`);
+    }
+    return clean;
+}
+const SECRET_NAME = /^[A-Z][A-Z0-9_]*(\/[A-Z][A-Z0-9_]+)*$/;
+function fromRun(r, label) {
+    const out = [r.stdout.trim(), r.stderr.trim()].filter(Boolean).join("\n");
+    if (r.code !== 0)
+        return errorResult(clampOutput(`${label} failed (exit ${r.code})\n${out}`));
+    return textResult(clampOutput(out || `${label}: (no output)`));
+}
+export function buildAgentMcpTools(clients) {
+    const { creds } = clients;
+    const company = creds.companySlug;
+    return [
+        {
+            name: "hq_whoami",
+            description: "Identity this MCP server acts as: the enrolled external agent, its company, and the control plane.",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: async () => {
+                let tokenOk;
+                let claimUid;
+                try {
+                    const claims = peekIdToken(await clients.getToken());
+                    claimUid = typeof claims["custom:entityUid"] === "string" ? claims["custom:entityUid"] : undefined;
+                    tokenOk = claimUid === creds.entityUid;
+                }
+                catch {
+                    tokenOk = false;
+                }
+                return textResult(JSON.stringify({
+                    agentUid: creds.entityUid,
+                    runtime: "external",
+                    companySlug: company,
+                    apiBaseUrl: creds.apiBaseUrl,
+                    cliVersion: CLI_VERSION,
+                    session: tokenOk ? "ok" : `unavailable${claimUid ? ` (token names ${claimUid})` : ""}`,
+                }, null, 2));
+            },
+        },
+        {
+            name: "hq_search",
+            description: clients.syncFiles
+                ? "Search the synced company vault (local qmd index). Modes: keyword (default), semantic, hybrid."
+                : "Search the company vault by file name and path, server-side (no local copy is kept). Content and semantic search need a kit installed with --sync-files.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Search text" },
+                    mode: { type: "string", enum: ["keyword", "semantic", "hybrid"] },
+                    count: { type: "integer", minimum: 1, maximum: 50 },
+                },
+                required: ["query"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const query = str(args, "query", { required: true, max: 2000 });
+                const mode = str(args, "mode");
+                if (mode !== undefined && !["keyword", "semantic", "hybrid"].includes(mode)) {
+                    throw new McpToolInputError('"mode" must be keyword, semantic or hybrid');
+                }
+                const count = int(args, "count", { min: 1, max: 50, fallback: 10 });
+                if (!clients.syncFiles) {
+                    // No local copy means no local index. Say so plainly instead of
+                    // running a local search that can only ever return nothing.
+                    if (mode && mode !== "keyword") {
+                        throw new McpToolInputError(`"${mode}" search needs a local copy of the vault; this agent reads files on demand. Use keyword, or reinstall the kit with \`hq agent kit install --sync-files\`.`);
+                    }
+                    return fromRun(await clients.runHq(["files", "search", query, "--company", company]), "hq files search");
+                }
+                const hqArgs = ["search", query, "--mode", mode ?? "keyword", "-n", String(count), "--json"];
+                return fromRun(await clients.runHq(hqArgs), "hq search");
+            },
+        },
+        {
+            name: "hq_files_list",
+            description: "List vault objects under a company path without syncing them (hq files browse).",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string", description: "companies/<slug>/<folder>" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const p = assertVaultPath(str(args, "path", { required: true, max: 1000 }));
+                return fromRun(await clients.runHq(["files", "browse", p]), "hq files browse");
+            },
+        },
+        {
+            name: "hq_files_read",
+            description: "Read one company vault file's contents (hq files cat). Text files only; output is truncated at 40k chars. " +
+                "For files attached to an HQ message use hq_attachment_fetch instead.",
+            inputSchema: {
+                type: "object",
+                properties: { path: { type: "string", description: "companies/<slug>/<file>" } },
+                required: ["path"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const p = assertVaultPath(str(args, "path", { required: true, max: 1000 }));
+                return fromRun(await clients.runHq(["files", "cat", p]), "hq files cat");
+            },
+        },
+        {
+            name: "hq_secrets_list",
+            description: "List the NAMES of company secrets this agent can use. Values are never returned.",
+            inputSchema: {
+                type: "object",
+                properties: { prefix: { type: "string", description: "Optional path prefix, e.g. DEV" } },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const prefix = str(args, "prefix", { max: 200 });
+                const hqArgs = ["secrets", "--company", company, "list"];
+                if (prefix)
+                    hqArgs.push("--prefix", prefix);
+                return fromRun(await clients.runHq(hqArgs), "hq secrets list");
+            },
+        },
+        {
+            name: "hq_secrets_exec",
+            description: "Run a command with the named company secrets injected as environment variables. " +
+                "Returns the command's exit code and output only — never the secret values. " +
+                "Do not run commands that print their environment.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    secrets: { type: "array", items: { type: "string" }, description: "Secret names to inject (UPPER_SNAKE, optional / path)" },
+                    command: { type: "array", items: { type: "string" }, description: "argv of the command to run" },
+                },
+                required: ["secrets", "command"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const secrets = strList(args, "secrets");
+                for (const s of secrets) {
+                    if (!SECRET_NAME.test(s))
+                        throw new McpToolInputError(`invalid secret name ${JSON.stringify(s)}`);
+                }
+                const command = strList(args, "command");
+                if (/^(env|printenv|export|set)$/.test(command[0])) {
+                    throw new McpToolInputError("refusing to run an environment-dumping command under hq_secrets_exec");
+                }
+                const r = await clients.runHq(["secrets", "--company", company, "exec", "--only", secrets.join(","), "--", ...command]);
+                const out = [r.stdout.trim(), r.stderr.trim()].filter(Boolean).join("\n");
+                const text = clampOutput(`exit ${r.code}\n${out}`);
+                return r.code === 0 ? textResult(text) : errorResult(text);
+            },
+        },
+        {
+            name: "hq_dm_send",
+            description: "Send an HQ message as this agent to a person (email or prs_…), an agent (agt_…), or a channel or group DM (chn_…). When replying to an inbox item that has a channelId, pass that channelId as `to` so the answer lands in the conversation it came from. Use audience='agent' for progress/status messages that only agents need to see; audience='human' for messages a person must read; audience='both' when unsure.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    to: { type: "string", description: "Email, prs_… or agt_… uid, or a chn_… channel id" },
+                    message: { type: "string" },
+                    audience: { type: "string", enum: ["human", "agent", "both"], description: "Who this message is for (default: human)" },
+                },
+                required: ["to", "message"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const to = str(args, "to", { required: true, max: 320 }).trim();
+                const message = str(args, "message", { required: true, max: 20_000 }).trim();
+                const audience = str(args, "audience");
+                if (audience !== undefined && !["human", "agent", "both"].includes(audience)) {
+                    throw new McpToolInputError('"audience" must be human, agent, or both');
+                }
+                if (/^chn_[A-Za-z0-9]+$/.test(to)) {
+                    // A channel or group DM: post into it, so a reply lands where the
+                    // message arrived instead of in a private DM to the sender.
+                    const token = await clients.getToken();
+                    const res = await clients.apiJson(token, `/v1/notify/channels/${encodeURIComponent(to)}/messages`, {
+                        method: "POST",
+                        body: { body: message },
+                    });
+                    if (res.status < 200 || res.status >= 300) {
+                        return errorResult(`Channel send failed (${res.status}): ${describeError(res.body)}`);
+                    }
+                    return textResult(`posted in ${to}`);
+                }
+                const body = /^[^\s]+@[^\s]+$/.test(to)
+                    ? { toEmail: to.toLowerCase(), body: message }
+                    : isRecipientUid(to)
+                        ? { toPersonUid: to, body: message }
+                        : (() => {
+                            throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid, or a chn_… channel id');
+                        })();
+                if (audience)
+                    body.audience = audience;
+                const token = await clients.getToken();
+                const res = await clients.apiJson(token, "/v1/notify/dm", { method: "POST", body });
+                if (res.status < 200 || res.status >= 300) {
+                    return errorResult(`DM send failed (${res.status}): ${describeError(res.body)}`);
+                }
+                return textResult(`sent to ${to}`);
+            },
+        },
+        {
+            name: "hq_inbox_read",
+            description: "Read this agent's HQ inbox (DMs, channel mentions, jobs), oldest first. By default only items not yet " +
+                "marked handled. Items with `attachments` carry files: download each with hq_attachment_fetch (pass its vaultPath " +
+                "and companyUid) when its vaultPath is under chat/attachments/ before answering. Reply with hq_dm_send, passing the item's channelId as `to` when it has one so the reply lands in that channel or group; do not reply to another bot's greeting or sign-off that asks for nothing. Then mark each one handled with hq_inbox_done so it is never answered twice.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    limit: { type: "integer", minimum: 1, maximum: 100 },
+                    include_done: { type: "boolean", description: "Also return items already marked handled" },
+                    unread_only: { type: "boolean", description: "Deprecated alias: true is the default behaviour" },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const limit = int(args, "limit", { min: 1, max: 100, fallback: 20 });
+                const includeDone = args.include_done === true;
+                const done = readDoneIds(clients.paths);
+                const { entries, note: serverNote } = await mergeAgentInbox(clients.paths, async () => {
+                    const token = await clients.getToken();
+                    return clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox`);
+                });
+                const byId = new Map(entries.map((e) => [e.id, e]));
+                const rows = [...byId.values()]
+                    .filter((e) => includeDone || !done.has(e.id))
+                    .slice(0, limit)
+                    .map((e) => summarizeInboxEntry(e, done.has(e.id)));
+                const hasFiles = rows.some((r) => r.attachments?.length);
+                return textResult(clampOutput(JSON.stringify({
+                    count: rows.length,
+                    messages: rows,
+                    ...(serverNote ? { note: serverNote } : {}),
+                    ...(hasFiles ? { attachmentsHint: ATTACHMENTS_HINT } : {}),
+                }, null, 2)));
+            },
+        },
+        {
+            name: "hq_attachment_fetch",
+            description: "Download a file attached to an HQ chat message (from hq_inbox_read `attachments`, vaultPath under chat/attachments/) " +
+                "to a private local file and return its localPath, contentType and size. Text-like files (csv, txt, json, …) also come back inline, bounded. " +
+                "Works for any type (xlsx, pdf, images): open localPath with a suitable tool. Only chat attachments in this agent's company, " +
+                "or in a DM with this agent; for other vault files or folders use hq_files_list / hq_files_read.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    vault_path: { type: "string", description: "attachments[].vaultPath exactly as hq_inbox_read returned it (chat/attachments/…)" },
+                    company_uid: { type: "string", description: "attachments[].companyUid (cmp_… or prs_…)" },
+                    name: { type: "string", description: "attachments[].name (optional; used for the local file name)" },
+                    content_type: { type: "string", description: "attachments[].contentType (optional)" },
+                },
+                required: ["vault_path", "company_uid"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const 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 });
+                try {
+                    const result = await fetchChatAttachment({
+                        vaultPath,
+                        scopeUid,
+                        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)}`);
+                }
+            },
+        },
+        {
+            name: "hq_inbox_done",
+            description: "Mark inbox items handled (after replying) so they stop showing as pending and the wake hook stops retrying.",
+            inputSchema: {
+                type: "object",
+                properties: { ids: { type: "array", items: { type: "string" }, description: "Item ids from hq_inbox_read" } },
+                required: ["ids"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const ids = strList(args, "ids");
+                for (const id of ids) {
+                    if (!/^[A-Za-z0-9._:-]{1,200}$/.test(id))
+                        throw new McpToolInputError(`invalid id ${JSON.stringify(id)}`);
+                }
+                const added = markInboxDone(clients.paths, ids);
+                const acked = [];
+                const failed = [];
+                try {
+                    const token = await clients.getToken();
+                    for (const id of ids) {
+                        const res = await clients.apiJson(token, `/v1/agents/${encodeURIComponent(creds.entityUid)}/inbox/${encodeURIComponent(id)}/ack`, { method: "POST" });
+                        if (res.status >= 200 && res.status < 300)
+                            acked.push(id);
+                        else
+                            failed.push(`${id} (${res.status})`);
+                    }
+                }
+                catch (err) {
+                    failed.push(`ack skipped: ${err instanceof Error ? err.message : String(err)}`);
+                }
+                return textResult(JSON.stringify({ marked: added.length, alreadyDone: ids.length - added.length, serverAcked: acked.length, ...(failed.length ? { ackFailures: failed } : {}) }, null, 2));
+            },
+        },
+        {
+            name: "hq_work_mesh_status",
+            description: "Live read of what the team is working on right now (work-mesh session status for this agent's company).",
+            inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            handler: async () => fromRun(await clients.runHq(["mesh", "session", "status", "--company", company, "--json"]), "hq mesh session status"),
+        },
+    ];
+}
+function describeError(body) {
+    if (body && typeof body === "object") {
+        const b = body;
+        const code = typeof b.code === "string" ? `${b.code}: ` : "";
+        const msg = typeof b.message === "string" ? b.message : typeof b.error === "string" ? b.error : "";
+        if (code || msg)
+            return `${code}${msg}`;
+    }
+    return "request failed";
+}
+//# sourceMappingURL=tools.js.map

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

@@ -0,0 +1,65 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ *
+ * LOCAL BOTS. A bot that runs on its owner's own computer cannot use the
+ * default tree: that machine already has the owner's HQ session, and an agent
+ * identity must not share a host account with a person's login. Such a bot
+ * enrolls into a SIBLING directory instead — `~/.hq-agent/<name>/` with the
+ * same layout — and every `hq agent …` command finds it here, so the bot does
+ * not have to carry environment variables around to be itself. Two or more
+ * local agents are ambiguous on purpose: pick one with `HQ_AGENT_DIR`.
+ */
+export declare const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export declare const HOST_KEY_NAME = "host-key";
+export declare const HOST_KEY_PUB_NAME = "host-key.pub";
+export declare const MACHINE_CREDS_NAME = "machine-creds.json";
+export declare const KIT_CONFIG_NAME = "kit.json";
+export declare const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export type KitComponent = "sync" | "inbox";
+export declare const KIT_COMPONENTS: readonly KitComponent[];
+export interface AgentKitPaths {
+    home: string;
+    agentDir: string;
+    hostKeyPath: string;
+    hostKeyPubPath: string;
+    machineCredsPath: string;
+    kitConfigPath: string;
+    stateDir: string;
+    inboxDir: string;
+    /** Private (0700) home for message attachments fetched by hq_attachment_fetch. */
+    attachmentsDir: string;
+    logsDir: string;
+    skillsDir: string;
+    lastHeartbeatPath: string;
+}
+/** Default name for a bot enrolled alongside its owner's own session. */
+export declare const DEFAULT_LOCAL_AGENT_NAME = "local";
+/** `~/.hq-agent` — the root, whether or not it holds an identity itself. */
+export declare function agentRootDir(home?: string): string;
+/** `~/.hq-agent/<name>` — an isolated home for one local bot. */
+export declare function localAgentDir(name: string, home?: string): string;
+/**
+ * Local agent homes under `~/.hq-agent`, by name, oldest name order. A
+ * directory counts only once it holds a creds file, so a half-written tree is
+ * never mistaken for an identity.
+ */
+export declare function listLocalAgentDirs(home?: string): string[];
+export declare function agentDir(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function agentKitPaths(home?: string, env?: NodeJS.ProcessEnv): AgentKitPaths;
+export declare function componentStatePath(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent): string;
+export declare function serviceLogPath(paths: Pick<AgentKitPaths, "logsDir">, service: string): string;
+//# sourceMappingURL=paths.d.ts.map

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

@@ -0,0 +1,118 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/attachments/<scope>/ message attachments fetched on demand (0700 / 0600)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ *
+ * LOCAL BOTS. A bot that runs on its owner's own computer cannot use the
+ * default tree: that machine already has the owner's HQ session, and an agent
+ * identity must not share a host account with a person's login. Such a bot
+ * enrolls into a SIBLING directory instead — `~/.hq-agent/<name>/` with the
+ * same layout — and every `hq agent …` command finds it here, so the bot does
+ * not have to carry environment variables around to be itself. Two or more
+ * local agents are ambiguous on purpose: pick one with `HQ_AGENT_DIR`.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+export const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export const HOST_KEY_NAME = "host-key";
+export const HOST_KEY_PUB_NAME = "host-key.pub";
+export const MACHINE_CREDS_NAME = "machine-creds.json";
+export const KIT_CONFIG_NAME = "kit.json";
+export const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export const KIT_COMPONENTS = ["sync", "inbox"];
+/** Default name for a bot enrolled alongside its owner's own session. */
+export const DEFAULT_LOCAL_AGENT_NAME = "local";
+/** `~/.hq-agent` — the root, whether or not it holds an identity itself. */
+export function agentRootDir(home = os.homedir()) {
+    return path.join(home, ".hq-agent");
+}
+/** `~/.hq-agent/<name>` — an isolated home for one local bot. */
+export function localAgentDir(name, home = os.homedir()) {
+    return path.join(agentRootDir(home), name);
+}
+/**
+ * Local agent homes under `~/.hq-agent`, by name, oldest name order. A
+ * directory counts only once it holds a creds file, so a half-written tree is
+ * never mistaken for an identity.
+ */
+export function listLocalAgentDirs(home = os.homedir()) {
+    const root = agentRootDir(home);
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isDirectory())
+        .map((e) => path.join(root, e.name))
+        .filter((dir) => {
+        try {
+            return fs.statSync(path.join(dir, MACHINE_CREDS_NAME)).isFile();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+export function agentDir(home = os.homedir(), env = process.env) {
+    const override = env[AGENT_DIR_ENV]?.trim();
+    if (override)
+        return override;
+    const root = agentRootDir(home);
+    // An identity in the root wins: that is the dedicated-host layout, and a
+    // host that has one is not running a local bot beside a person.
+    try {
+        if (fs.statSync(path.join(root, MACHINE_CREDS_NAME)).isFile())
+            return root;
+    }
+    catch {
+        /* no identity in the root — fall through to the local homes */
+    }
+    const locals = listLocalAgentDirs(home);
+    // Exactly one is unambiguous. Two or more cannot be guessed, so keep the
+    // root and let the caller fail with a message naming HQ_AGENT_DIR rather
+    // than silently acting as whichever agent sorted first.
+    return locals.length === 1 ? locals[0] : root;
+}
+export function agentKitPaths(home = os.homedir(), env = process.env) {
+    const dir = agentDir(home, env);
+    const credsOverride = env.HQ_MACHINE_CREDS_FILE?.trim();
+    const stateDir = path.join(dir, "state");
+    return {
+        home,
+        agentDir: dir,
+        hostKeyPath: path.join(dir, HOST_KEY_NAME),
+        hostKeyPubPath: path.join(dir, HOST_KEY_PUB_NAME),
+        machineCredsPath: credsOverride || path.join(dir, MACHINE_CREDS_NAME),
+        kitConfigPath: path.join(dir, KIT_CONFIG_NAME),
+        stateDir,
+        inboxDir: path.join(dir, "inbox"),
+        attachmentsDir: path.join(dir, "attachments"),
+        logsDir: path.join(dir, "logs"),
+        skillsDir: path.join(dir, "skills"),
+        lastHeartbeatPath: path.join(stateDir, LAST_HEARTBEAT_NAME),
+    };
+}
+export function componentStatePath(paths, component) {
+    return path.join(paths.stateDir, `component-${component}`);
+}
+export function serviceLogPath(paths, service) {
+    return path.join(paths.logsDir, `${service}.log`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/agent-kit/private-file.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What a write could actually guarantee about who can read the file.
+ * `enforced: false` means the bytes are on disk but readable beyond the
+ * owner — true of a share mounted with a fixed `file_mode`.
+ */
+export interface PrivateFileOutcome {
+    enforced: boolean;
+    /** Mode observed after the write, when it could be read back. */
+    observedMode?: number;
+    /** errno of a refused chmod (EPERM on Azure Files), when there was one. */
+    chmodError?: string;
+}
+/**
+ * chmod failures that mean "this filesystem does not do modes" rather than
+ * "something is wrong". Anything else still throws: a refused chmod on a
+ * local disk is a real fault and must not be swallowed.
+ */
+export declare const MODE_UNSUPPORTED_CODES: Set<string>;
+/** Apply a mode, tolerating filesystems that do not have modes. Returns the errno if refused. */
+export declare function chmodIfSupported(target: string, mode: number): string | undefined;
+/**
+ * Make a directory and try to make it owner-only. The `mode` argument to
+ * mkdir(2) is silently ignored on a share, and the follow-up chmod is refused
+ * there, so neither is allowed to fail the call.
+ */
+export declare function mkdirPrivate(dir: string, mode?: number): void;
+/** Write a file atomically with the given mode, replacing any existing one. */
+export declare function writePrivateFile(dest: string, contents: string | Uint8Array, mode: number): PrivateFileOutcome;
+//# sourceMappingURL=private-file.d.ts.map