@indigoai-us/hq-cli 5.313.0 → 5.314.0

package/dist/lib/agent-kit/adopt-identity.d.ts

@@ -1,27 +0,0 @@
-/**
- * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
- * is signed in to HQ.
- *
- * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
- * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
- * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
- * a computer with its owner lives in a sibling directory instead, so without
- * this the CLI would find the layout of an agent and the credentials of a
- * person: `hq agent probe` would report its owner's identity and the bot would
- * act as them.
- *
- * So before any `hq agent` subcommand runs, the resolved tree is published to
- * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
- * a daemon unit that pins one stays pinned.
- *
- * The person's own session file is not read, moved, or changed by any of this.
- */
-import type { AgentKitPaths } from "./paths.js";
-export declare const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
-export declare const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
-/**
- * Point the token layer at `paths` unless the caller already pinned it.
- * Returns the variables it set, for tests and for `--verbose` output.
- */
-export declare function adoptAgentIdentityEnv(paths: Pick<AgentKitPaths, "agentDir" | "machineCredsPath">, env?: NodeJS.ProcessEnv): Record<string, string>;
-//# sourceMappingURL=adopt-identity.d.ts.map

package/dist/lib/agent-kit/adopt-identity.js

@@ -1,60 +0,0 @@
-/**
- * Make `hq agent …` act as THIS host's agent, even on a computer whose owner
- * is signed in to HQ.
- *
- * The token layer resolves machine credentials from `HQ_MACHINE_CREDS_FILE`,
- * falling back to the one fixed path `~/.hq-agent/machine-creds.json` — and
- * hq-cloud's own `loadMachineCreds` reads the same variable. A bot that shares
- * a computer with its owner lives in a sibling directory instead, so without
- * this the CLI would find the layout of an agent and the credentials of a
- * person: `hq agent probe` would report its owner's identity and the bot would
- * act as them.
- *
- * So before any `hq agent` subcommand runs, the resolved tree is published to
- * the environment. An explicit `HQ_MACHINE_CREDS_FILE` is never overwritten —
- * a daemon unit that pins one stays pinned.
- *
- * The person's own session file is not read, moved, or changed by any of this.
- */
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { ensureHostKeyPath } from "./creds.js";
-export const MACHINE_CREDS_FILE_ENV = "HQ_MACHINE_CREDS_FILE";
-export const MACHINE_TOKEN_STATE_DIR_ENV = "HQ_MACHINE_TOKEN_STATE_DIR";
-/**
- * Point the token layer at `paths` unless the caller already pinned it.
- * Returns the variables it set, for tests and for `--verbose` output.
- */
-export function adoptAgentIdentityEnv(paths, env = process.env) {
-    const applied = {};
-    if (env[MACHINE_CREDS_FILE_ENV]?.trim())
-        return applied;
-    // Only adopt a tree that actually holds an identity: on a host that has not
-    // enrolled yet, leaving the environment alone keeps today's error messages.
-    try {
-        if (!fs.statSync(paths.machineCredsPath).isFile())
-            return applied;
-    }
-    catch {
-        return applied;
-    }
-    // A moved or copied identity keeps a stale host-key path until the next
-    // token refresh fails; repoint it at the key beside the creds file first.
-    try {
-        ensureHostKeyPath(paths);
-    }
-    catch {
-        /* never block a command on the repair; probe reports a missing key */
-    }
-    applied[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
-    env[MACHINE_CREDS_FILE_ENV] = paths.machineCredsPath;
-    // Per-agent token cache. Two identities on one computer must never share a
-    // minted-token file; the agent's belongs inside the agent's own tree.
-    if (!env[MACHINE_TOKEN_STATE_DIR_ENV]?.trim()) {
-        const dir = path.join(paths.agentDir, "token-state");
-        applied[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
-        env[MACHINE_TOKEN_STATE_DIR_ENV] = dir;
-    }
-    return applied;
-}
-//# sourceMappingURL=adopt-identity.js.map

package/dist/lib/agent-kit/attachment-download.d.ts

@@ -1,24 +0,0 @@
-/**
- * Vault object download for chat attachments, shared by `hq agent mcp`
- * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
- *
- * Bytes come through the same vault presign path `hq files cat` uses
- * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
- * machine token, so the server's per-key ACL stays the authority. The body is
- * read with a hard byte cap so a crafted key cannot pull a large object into
- * memory.
- */
-import type { Readable } from "node:stream";
-export type VaultObjectDownloader = (scopeUid: string, key: string) => Promise<Buffer>;
-/** Drain a stream into memory, refusing past `max` bytes. */
-export declare function readBounded(body: Readable, max: number): Promise<Buffer>;
-/**
- * A downloader bound to one identity. `baseUrl` pins the API the token is sent
- * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
- * vault API, the same one the caller's other API calls use).
- */
-export declare function createVaultObjectDownloader(opts: {
-    getToken: () => Promise<string>;
-    baseUrl?: string;
-}): VaultObjectDownloader;
-//# sourceMappingURL=attachment-download.d.ts.map

package/dist/lib/agent-kit/attachment-download.js

@@ -1,47 +0,0 @@
-/**
- * Vault object download for chat attachments, shared by `hq agent mcp`
- * (hq_attachment_fetch) and the local bot runner (`hq bot run`).
- *
- * Bytes come through the same vault presign path `hq files cat` uses
- * (`createCompanyPresignClient` → POST /v1/files/presign) with the caller's own
- * machine token, so the server's per-key ACL stays the authority. The body is
- * read with a hard byte cap so a crafted key cannot pull a large object into
- * memory.
- */
-import { GetObjectCommand } from "@aws-sdk/client-s3";
-import { createCompanyPresignClient } from "../../commands/files-browse.js";
-import { MAX_ATTACHMENT_BYTES } from "./mcp/attachments.js";
-/** Drain a stream into memory, refusing past `max` bytes. */
-export async function readBounded(body, max) {
-    const chunks = [];
-    let total = 0;
-    for await (const chunk of body) {
-        const b = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        total += b.length;
-        if (total > max) {
-            body.destroy();
-            throw new Error(`object exceeds the ${max}-byte attachment limit`);
-        }
-        chunks.push(b);
-    }
-    return Buffer.concat(chunks);
-}
-/**
- * A downloader bound to one identity. `baseUrl` pins the API the token is sent
- * to (an enrolled agent passes its own `apiBaseUrl`; undefined = the default
- * vault API, the same one the caller's other API calls use).
- */
-export function createVaultObjectDownloader(opts) {
-    return async (scopeUid, key) => {
-        const client = createCompanyPresignClient({
-            token: await opts.getToken(),
-            companyUid: scopeUid,
-            ...(opts.baseUrl ? { baseUrl: opts.baseUrl } : {}),
-        });
-        const res = await client.send(new GetObjectCommand({ Bucket: scopeUid, Key: key }));
-        if (!res.Body)
-            throw new Error(`no body returned for '${key}'`);
-        return readBounded(res.Body, MAX_ATTACHMENT_BYTES);
-    };
-}
-//# sourceMappingURL=attachment-download.js.map

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

@@ -1,106 +0,0 @@
-/**
- * Host key + machine-creds file handling for external agents.
- *
- * The private key and the creds file are the whole credential: a stolen
- * creds file without the key mints nothing (hq-cloud signs every mint with
- * the key), so both are written 0600 and never printed. Nothing in this
- * module reads `~/.hq/cognito-tokens.json` — a human's session is never
- * consulted, copied, or reused by an agent identity (policy
- * never-extract-stored-session-tokens-to-forge-privileged-calls).
- *
- * NOT EVERY FILESYSTEM CAN KEEP THAT PROMISE. A CIFS/SMB mount (Azure Files
- * is the one that found this) is mounted with a fixed `file_mode` and fails
- * `chmod` outright with EPERM; an NFS export or a Docker volume may accept
- * the call and ignore it. A bot whose only persistent storage is such a
- * share used to be unable to enroll at all — enrollment died on the chmod,
- * leaving a stray temp file behind, and the only alternative was to keep the
- * identity on disposable storage where a rebuild erases it.
- *
- * So the write no longer fails there: it reports whether owner-only
- * permissions actually took, and the caller says so out loud. The file is
- * still requested 0600 at creation, the outcome is read back from the
- * filesystem rather than assumed, and a host that cannot honour it learns
- * that its credential is readable by anything else with access to the same
- * share. Refusing to enroll would not have made that credential safer; it
- * would only have moved it somewhere it silently disappears.
- */
-import type { AgentKitPaths, KitComponent } from "./paths.js";
-import { type PrivateFileOutcome } from "./private-file.js";
-/** Exact `machine-creds.json` shape for an external agent (api-contract v1). */
-export interface ExternalMachineCreds {
-    username: string;
-    secret: string;
-    /** Cognito user pool the machine user lives in (informational for the host). */
-    userPoolId?: string;
-    clientId: string;
-    region: string;
-    entityType: "agent";
-    entityUid: string;
-    runtime: "external";
-    hostKeyPath: string;
-    companySlug: string;
-    apiBaseUrl: string;
-}
-export interface HostKeyPair {
-    privatePem: string;
-    publicPem: string;
-    /** SHA-256 of the DER (SPKI) public key, hex, first 16 chars. */
-    fingerprint: string;
-}
-/** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
-export declare function hostFingerprint(publicPem: string): string;
-export declare function generateHostKeyPair(): HostKeyPair;
-export type { PrivateFileOutcome } from "./private-file.js";
-export declare function writeHostKeyPair(paths: Pick<AgentKitPaths, "hostKeyPath" | "hostKeyPubPath">, pair: HostKeyPair): PrivateFileOutcome;
-export declare function writeMachineCreds(paths: Pick<AgentKitPaths, "machineCredsPath">, creds: ExternalMachineCreds): PrivateFileOutcome;
-/**
- * Read the creds file without trusting it: returns null unless it is an
- * external-agent file with every contract field present.
- */
-export declare function readExternalMachineCreds(paths: Pick<AgentKitPaths, "machineCredsPath">): ExternalMachineCreds | null;
-/** Whether ANY machine-creds file exists (external or hosted) at the kit path. */
-export declare function machineCredsFileExists(paths: Pick<AgentKitPaths, "machineCredsPath">): boolean;
-/**
- * Component health stamp the kit services write and the heartbeat reads:
- * `<status> <iso8601>` — same line shape as the hosted box's component files.
- */
-export type ComponentStatus = "ok" | "error";
-export declare function writeComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, status: ComponentStatus, now?: () => Date): void;
-export interface ComponentReading {
-    status: ComponentStatus;
-    at: Date | null;
-}
-/**
- * Read a component stamp. A missing file, an unparseable line, or a stamp
- * older than `staleAfterMs` reads as `error` — silence is never health.
- */
-export declare function readComponentStatus(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent, staleAfterMs: number, now?: () => Date): ComponentReading;
-export type HostKeyPathCheck = {
-    status: "ok";
-    hostKeyPath: string;
-} | {
-    status: "healed";
-    hostKeyPath: string;
-    previous: string;
-} | {
-    status: "missing";
-    hostKeyPath: string;
-} | {
-    status: "no-creds";
-};
-/**
- * Make the recorded host-key path point at a key that exists.
- *
- * The creds file records the key's absolute path, and hq-cloud signs every
- * token mint with the key at that path. When the identity is moved or copied —
- * the Runneth pilot copied its files from a disposable $HOME to persistent
- * storage — the recorded path goes stale, and nothing fails until the cached
- * token expires up to an hour later. Then every mint fails and the agent goes
- * silent until someone re-enrolls it.
- *
- * The key always travels with the creds file, so when the recorded path is
- * gone and a key sits beside the creds file, point at that one. The key
- * itself is never read or copied here; only the recorded path changes.
- */
-export declare function ensureHostKeyPath(paths: Pick<AgentKitPaths, "machineCredsPath">): HostKeyPathCheck;
-//# sourceMappingURL=creds.d.ts.map

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

@@ -1,163 +0,0 @@
-/**
- * Host key + machine-creds file handling for external agents.
- *
- * The private key and the creds file are the whole credential: a stolen
- * creds file without the key mints nothing (hq-cloud signs every mint with
- * the key), so both are written 0600 and never printed. Nothing in this
- * module reads `~/.hq/cognito-tokens.json` — a human's session is never
- * consulted, copied, or reused by an agent identity (policy
- * never-extract-stored-session-tokens-to-forge-privileged-calls).
- *
- * NOT EVERY FILESYSTEM CAN KEEP THAT PROMISE. A CIFS/SMB mount (Azure Files
- * is the one that found this) is mounted with a fixed `file_mode` and fails
- * `chmod` outright with EPERM; an NFS export or a Docker volume may accept
- * the call and ignore it. A bot whose only persistent storage is such a
- * share used to be unable to enroll at all — enrollment died on the chmod,
- * leaving a stray temp file behind, and the only alternative was to keep the
- * identity on disposable storage where a rebuild erases it.
- *
- * So the write no longer fails there: it reports whether owner-only
- * permissions actually took, and the caller says so out loud. The file is
- * still requested 0600 at creation, the outcome is read back from the
- * filesystem rather than assumed, and a host that cannot honour it learns
- * that its credential is readable by anything else with access to the same
- * share. Refusing to enroll would not have made that credential safer; it
- * would only have moved it somewhere it silently disappears.
- */
-import { createHash, createPublicKey, generateKeyPairSync } from "node:crypto";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { componentStatePath, HOST_KEY_NAME } from "./paths.js";
-import { writePrivateFile, } from "./private-file.js";
-/** Contract fingerprint: sha256(DER SPKI public key) hex, first 16 chars. */
-export function hostFingerprint(publicPem) {
-    const der = createPublicKey(publicPem).export({ type: "spki", format: "der" });
-    return createHash("sha256").update(der).digest("hex").slice(0, 16);
-}
-export function generateHostKeyPair() {
-    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
-    const privatePem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
-    const publicPem = publicKey.export({ type: "spki", format: "pem" }).toString();
-    return { privatePem, publicPem, fingerprint: hostFingerprint(publicPem) };
-}
-export function writeHostKeyPair(paths, pair) {
-    const key = writePrivateFile(paths.hostKeyPath, pair.privatePem, 0o600);
-    // The public half is public; its mode is not a promise worth reporting.
-    writePrivateFile(paths.hostKeyPubPath, pair.publicPem, 0o644);
-    return key;
-}
-export function writeMachineCreds(paths, creds) {
-    return writePrivateFile(paths.machineCredsPath, `${JSON.stringify(creds, null, 2)}\n`, 0o600);
-}
-/**
- * Read the creds file without trusting it: returns null unless it is an
- * external-agent file with every contract field present.
- */
-export function readExternalMachineCreds(paths) {
-    let raw;
-    try {
-        raw = JSON.parse(fs.readFileSync(paths.machineCredsPath, "utf8"));
-    }
-    catch {
-        return null;
-    }
-    if (!raw || typeof raw !== "object")
-        return null;
-    const r = raw;
-    const str = (k) => typeof r[k] === "string" && r[k].length > 0 ? r[k] : null;
-    const username = str("username");
-    const secret = str("secret");
-    const clientId = str("clientId");
-    const region = str("region");
-    const entityUid = str("entityUid");
-    const userPoolId = str("userPoolId");
-    const hostKeyPath = str("hostKeyPath");
-    const companySlug = str("companySlug");
-    const apiBaseUrl = str("apiBaseUrl");
-    if (r.runtime !== "external" ||
-        r.entityType !== "agent" ||
-        !username ||
-        !secret ||
-        !clientId ||
-        !region ||
-        !entityUid ||
-        !entityUid.startsWith("agt_") ||
-        !hostKeyPath ||
-        !companySlug ||
-        !apiBaseUrl) {
-        return null;
-    }
-    return {
-        username,
-        secret,
-        ...(userPoolId ? { userPoolId } : {}),
-        clientId,
-        region,
-        entityType: "agent",
-        entityUid,
-        runtime: "external",
-        hostKeyPath,
-        companySlug,
-        apiBaseUrl,
-    };
-}
-/** Whether ANY machine-creds file exists (external or hosted) at the kit path. */
-export function machineCredsFileExists(paths) {
-    return fs.existsSync(paths.machineCredsPath);
-}
-export function writeComponentStatus(paths, component, status, now = () => new Date()) {
-    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
-    fs.writeFileSync(componentStatePath(paths, component), `${status} ${now().toISOString()}\n`, { mode: 0o600 });
-}
-/**
- * Read a component stamp. A missing file, an unparseable line, or a stamp
- * older than `staleAfterMs` reads as `error` — silence is never health.
- */
-export function readComponentStatus(paths, component, staleAfterMs, now = () => new Date()) {
-    let line;
-    try {
-        line = fs.readFileSync(componentStatePath(paths, component), "utf8").trim();
-    }
-    catch {
-        return { status: "error", at: null };
-    }
-    const [status, iso] = line.split(/\s+/, 2);
-    const at = iso ? new Date(iso) : null;
-    if (status !== "ok" || !at || Number.isNaN(at.getTime())) {
-        return { status: "error", at: at && !Number.isNaN(at.getTime()) ? at : null };
-    }
-    if (now().getTime() - at.getTime() > staleAfterMs) {
-        return { status: "error", at };
-    }
-    return { status: "ok", at };
-}
-/**
- * Make the recorded host-key path point at a key that exists.
- *
- * The creds file records the key's absolute path, and hq-cloud signs every
- * token mint with the key at that path. When the identity is moved or copied —
- * the Runneth pilot copied its files from a disposable $HOME to persistent
- * storage — the recorded path goes stale, and nothing fails until the cached
- * token expires up to an hour later. Then every mint fails and the agent goes
- * silent until someone re-enrolls it.
- *
- * The key always travels with the creds file, so when the recorded path is
- * gone and a key sits beside the creds file, point at that one. The key
- * itself is never read or copied here; only the recorded path changes.
- */
-export function ensureHostKeyPath(paths) {
-    const creds = readExternalMachineCreds(paths);
-    if (!creds)
-        return { status: "no-creds" };
-    if (fs.existsSync(creds.hostKeyPath))
-        return { status: "ok", hostKeyPath: creds.hostKeyPath };
-    const sibling = path.join(path.dirname(paths.machineCredsPath), HOST_KEY_NAME);
-    if (sibling === creds.hostKeyPath || !fs.existsSync(sibling)) {
-        return { status: "missing", hostKeyPath: creds.hostKeyPath };
-    }
-    const raw = JSON.parse(fs.readFileSync(paths.machineCredsPath, "utf8"));
-    raw.hostKeyPath = sibling;
-    writePrivateFile(paths.machineCredsPath, `${JSON.stringify(raw, null, 2)}\n`, 0o600);
-    return { status: "healed", hostKeyPath: sibling, previous: creds.hostKeyPath };
-}
-//# sourceMappingURL=creds.js.map

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

@@ -1,78 +0,0 @@
-/**
- * No-service-manager fallback for `hq agent kit install`.
- *
- * When systemd --user cannot be reached (no user session bus, permission
- * refused) or launchd is unavailable, the kit is started as ONE detached
- * `hq agent kit run all` supervisor with output appended to
- * ~/.hq-agent/logs/kit.log and its pid recorded in ~/.hq-agent/kit.pid.
- * `kit status` reads the pidfile; `kit uninstall` kills it and removes it.
- */
-import type { ServiceHostPaths, ServiceSetResult } from "../service-manager/index.js";
-import type { AgentKitPaths } from "./paths.js";
-export declare function kitPidPath(paths: Pick<AgentKitPaths, "agentDir">): string;
-/** True when an activation error means the service manager itself is unusable. */
-export declare function isServiceManagerUnavailable(error: string | undefined): boolean;
-/**
- * Pick the fallback when activation was requested and the host has no service
- * manager integration, or every failure is a service-manager-unavailable error.
- */
-export declare function shouldUseFallback(result: ServiceSetResult, activate: boolean): boolean;
-export declare function readKitPid(paths: Pick<AgentKitPaths, "agentDir">): number | null;
-export type KillFn = (pid: number, signal?: NodeJS.Signals | 0) => boolean;
-export declare function isPidAlive(pid: number, kill?: KillFn): boolean;
-export interface FallbackStatus {
-    pidFile: string;
-    pid: number | null;
-    running: boolean;
-}
-export declare function fallbackStatus(paths: Pick<AgentKitPaths, "agentDir">, kill?: KillFn): FallbackStatus | null;
-/** Kill a recorded supervisor (if alive) and remove the pidfile. */
-export declare function stopFallback(paths: Pick<AgentKitPaths, "agentDir">, kill?: KillFn): {
-    pid: number | null;
-    killed: boolean;
-};
-export interface DetachedSpawn {
-    (cmd: string, args: string[], opts: {
-        detached: true;
-        windowsHide: true;
-        stdio: ["ignore", number, number];
-        env: NodeJS.ProcessEnv;
-        cwd: string;
-    }): {
-        pid?: number;
-        unref(): void;
-    };
-}
-/** crontab line that restarts the fallback supervisor after a reboot. */
-export declare function rebootCrontabLine(paths: Pick<AgentKitPaths, "agentDir" | "logsDir">, host: ServiceHostPaths): string;
-export declare function startFallback(paths: AgentKitPaths, host: ServiceHostPaths, deps?: {
-    spawn?: DetachedSpawn;
-    kill?: KillFn;
-    env?: NodeJS.ProcessEnv;
-}): {
-    pid: number;
-    logPath: string;
-    pidFile: string;
-};
-/**
- * Marker for the crontab entry this module owns. Present so a reinstall
- * replaces its own line instead of stacking duplicates, and so a human reading
- * their crontab can see what wrote it and that removing it is safe.
- */
-export declare const REBOOT_CRON_MARKER = "# hq-agent-kit (managed): restart the HQ agent kit after a reboot";
-export interface CronRunner {
-    (args: string[], input?: string): {
-        status: number;
-        stdout: string;
-        stderr: string;
-    };
-}
-export interface RebootCronResult {
-    installed: boolean;
-    /** Why it could not be installed, for the caller to print verbatim. */
-    reason?: string;
-}
-/** Drop any previously managed block, leaving every other entry untouched. */
-export declare function stripManagedCron(existing: string): string;
-export declare function ensureRebootCrontab(paths: Pick<AgentKitPaths, "agentDir" | "logsDir">, host: ServiceHostPaths, run?: CronRunner): RebootCronResult;
-//# sourceMappingURL=fallback.d.ts.map