@indigoai-us/hq-cli 5.313.0 → 5.314.0

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

@@ -1,397 +0,0 @@
-/**
- * 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

@@ -1,65 +0,0 @@
-/**
- * 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

@@ -1,118 +0,0 @@
-/**
- * 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

@@ -1,29 +0,0 @@
-/**
- * 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