@indigoai-us/hq-cli 5.109.16 → 5.111.0

package/dist/lib/bot/continuity.js

@@ -0,0 +1,301 @@
+/** Portable, identity-bound context for the local -> Fleet provisioning bridge.
+ * This module does not provision compute, copy credentials, or enable a consumer.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { isUtf8 } from "node:buffer";
+import * as yaml from "js-yaml";
+import { resolveBotMemoryDir } from "./config.js";
+import { packageRoot } from "../../utils/hq-roots.js";
+const MAX_FILES = 2000;
+const MAX_BYTES = 32 * 1024 * 1024;
+const PRIVATE_NAME = /^(?:\.env(?:\..*)?|\.ssh|\.aws|\.gnupg|\.netrc|\.git|node_modules|machine-creds\.json|bot\.json|auth\.json|credentials(?:\..*)?|id_rsa|id_ed25519)$/i;
+const BUNDLED_SETUP_WORKER_DIR = "assets/bot-workers/setup";
+const BUNDLED_SETUP_CONTEXT = new Set([
+    "skills/",
+    "context/quick-reference.md",
+    "context/USER-GUIDE.md",
+]);
+function sha(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function reject(message) { throw new Error(`Bot continuity: ${message}`); }
+function containsControl(value) { return [...value].some((character) => character.charCodeAt(0) < 32); }
+function relativeFile(value) {
+    if (!value || value.includes("\\") || value.split("/").some((part) => !part || part.startsWith(".") || PRIVATE_NAME.test(part)) || containsControl(value)) {
+        reject(`unsafe or private path: ${value}`);
+    }
+}
+function assertIdentity(agentUid, ownerUid) {
+    if (!/^agt_[A-Z0-9]+$/.test(agentUid) || !/^prs_[A-Z0-9]+$/.test(ownerUid))
+        reject("invalid identity");
+}
+function digestOf(bundle) {
+    return sha(JSON.stringify(bundle));
+}
+/** Reject links in every component before reading anything from the subtree. */
+function plainDirectory(absolute, allowPrivateComponents = false) {
+    const resolved = path.resolve(absolute);
+    let cursor = path.parse(resolved).root;
+    for (const part of resolved.slice(cursor.length).split(path.sep).filter(Boolean)) {
+        if (!allowPrivateComponents && PRIVATE_NAME.test(part))
+            reject(`private directory: ${part}`);
+        cursor = path.join(cursor, part);
+        const st = fs.lstatSync(cursor);
+        if (st.isSymbolicLink() || !st.isDirectory())
+            reject(`directory must not be a symlink: ${cursor}`);
+    }
+    return resolved;
+}
+/** Capture original bytes, including supporting scripts and Mac-only memory. */
+export function snapshotBotContinuity(config, stateDir) {
+    assertIdentity(config.agentUid, config.ownerUid);
+    const configuredWorkerRoot = path.resolve(config.hqRoot, config.workerDir);
+    const bundledSetupRoot = path.resolve(packageRoot(), BUNDLED_SETUP_WORKER_DIR);
+    const isBundledSetup = configuredWorkerRoot === bundledSetupRoot;
+    if (!isBundledSetup)
+        relativeFile(config.workerDir);
+    const expectedPersonal = `personal/workers/${config.name}`;
+    const companyPrefix = config.companySlug ? `companies/${config.companySlug}/workers/` : null;
+    if (!isBundledSetup && config.workerDir !== expectedPersonal && !config.workerDir.startsWith("core/workers/") && !(companyPrefix && config.workerDir.startsWith(companyPrefix)))
+        reject("worker is outside this bot's scope");
+    const hqRoot = plainDirectory(config.hqRoot);
+    // The generic validator still rejects every node_modules path. This one
+    // trusted path is compared first, then every component is checked for links.
+    const workerRoot = plainDirectory(isBundledSetup ? bundledSetupRoot : path.join(hqRoot, config.workerDir), isBundledSetup);
+    const sourceWorkerDir = isBundledSetup ? BUNDLED_SETUP_WORKER_DIR : config.workerDir;
+    const memoryRoot = path.resolve(resolveBotMemoryDir(config));
+    const ownSyncedMemory = path.join(hqRoot, expectedPersonal, "memory");
+    const ownLocalMemory = path.resolve(stateDir, "memory");
+    if (memoryRoot !== ownSyncedMemory && memoryRoot !== ownLocalMemory)
+        reject("memory is outside this bot's own memory folders");
+    plainDirectory(memoryRoot);
+    const files = [];
+    let total = 0;
+    const walk = (root, area, rel = "") => {
+        for (const entry of fs.readdirSync(path.join(root, rel)).sort()) {
+            const child = rel ? `${rel}/${entry}` : entry;
+            relativeFile(child);
+            const absolute = path.join(root, child);
+            // Memory is captured once from its configured location, never a stale worker copy.
+            if (area === "worker" && child === "memory")
+                continue;
+            const st = fs.lstatSync(absolute);
+            if (st.isSymbolicLink())
+                reject(`symlink in context: ${child}`);
+            if (st.isDirectory()) {
+                walk(root, area, child);
+                continue;
+            }
+            if (!st.isFile())
+                reject(`not a regular file: ${child}`);
+            if (files.length >= MAX_FILES || total + st.size > MAX_BYTES)
+                reject("context exceeds transfer limit; nothing was truncated");
+            const fd = fs.openSync(absolute, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+            try {
+                const current = fs.fstatSync(fd);
+                if (!current.isFile() || current.ino !== st.ino || current.dev !== st.dev)
+                    reject(`file changed while reading: ${child}`);
+                const bytes = fs.readFileSync(fd);
+                const after = fs.fstatSync(fd);
+                if (after.size !== current.size || after.mtimeMs !== current.mtimeMs || bytes.length !== current.size)
+                    reject(`file changed while reading: ${child}`);
+                total += bytes.length;
+                if (total > MAX_BYTES)
+                    reject("context exceeds transfer limit");
+                files.push({ area, path: child, bytes: bytes.length, sha256: sha(bytes), executable: Boolean(st.mode & 0o111), base64: bytes.toString("base64") });
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        }
+    };
+    walk(workerRoot, "worker");
+    walk(memoryRoot, "memory");
+    if (!files.some((f) => f.area === "worker" && f.path === "worker.yaml"))
+        reject("worker.yaml is missing");
+    const payload = {
+        version: 1, agentUid: config.agentUid, ownerUid: config.ownerUid, name: config.name,
+        ...(config.companySlug ? { companySlug: config.companySlug } : {}),
+        source: { hqRoot, workerDir: sourceWorkerDir, memoryDir: memoryRoot }, files,
+    };
+    return { ...payload, digest: digestOf(payload) };
+}
+/** Validate all bytes and ownership before planning any destination write. */
+export function validateBotContinuity(bundle, identity) {
+    assertIdentity(bundle.agentUid, bundle.ownerUid);
+    if (bundle.version !== 1 || bundle.agentUid !== identity.agentUid || bundle.ownerUid !== identity.ownerUid)
+        reject("identity mismatch");
+    if (!bundle.source || !path.isAbsolute(bundle.source.hqRoot) || !path.isAbsolute(bundle.source.memoryDir))
+        reject("invalid source roots");
+    relativeFile(bundle.source.workerDir);
+    if (typeof bundle.name !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(bundle.name))
+        reject("invalid bot name");
+    const { digest, ...payload } = bundle;
+    if (digestOf(payload) !== digest)
+        reject("manifest digest mismatch");
+    if (!Array.isArray(bundle.files) || bundle.files.length > MAX_FILES)
+        reject("invalid file count");
+    let total = 0;
+    const seen = new Set();
+    for (const file of bundle.files) {
+        relativeFile(file.path);
+        if (file.area !== "worker" && file.area !== "memory")
+            reject("invalid context area");
+        const key = `${file.area}/${file.path}`;
+        if (seen.has(key))
+            reject(`duplicate file: ${key}`);
+        seen.add(key);
+        if (typeof file.base64 !== "string" || file.base64.length > Math.ceil(MAX_BYTES / 3) * 4 || !Number.isSafeInteger(file.bytes) || file.bytes < 0 || typeof file.executable !== "boolean")
+            reject(`invalid file metadata: ${key}`);
+        const bytes = Buffer.from(file.base64, "base64");
+        total += bytes.length;
+        if (bytes.toString("base64") !== file.base64 || bytes.length !== file.bytes || sha(bytes) !== file.sha256 || total > MAX_BYTES)
+            reject(`invalid file bytes: ${key}`);
+    }
+    validateDeclaredDependencies(bundle);
+}
+/** A relocated reference must resolve to bytes actually present in the bundle. */
+function validateDeclaredDependencies(bundle) {
+    const worker = bundle.files.find((file) => file.area === "worker" && file.path === "worker.yaml");
+    if (!worker)
+        reject("worker.yaml is missing");
+    const parsed = yaml.load(Buffer.from(worker.base64, "base64").toString("utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        reject("invalid worker.yaml");
+    const spec = parsed;
+    const bundledSetup = bundle.source.workerDir === BUNDLED_SETUP_WORKER_DIR;
+    const requireReference = (reference, directory) => {
+        if (typeof reference !== "string" || !reference || containsControl(reference))
+            reject("invalid context or skill reference");
+        const absolute = path.resolve(bundle.source.hqRoot, reference);
+        const roots = [
+            ["memory", bundle.source.memoryDir],
+            ["worker", path.resolve(bundle.source.hqRoot, bundle.source.workerDir)],
+        ];
+        for (const [area, root] of roots) {
+            const relative = path.relative(root, absolute).split(path.sep).join("/");
+            if (relative === ".." || relative.startsWith("../") || path.isAbsolute(relative))
+                continue;
+            if (bundle.files.some((file) => file.area === area && (file.path === relative || (directory && (!relative || file.path.startsWith(`${relative}/`))))))
+                return;
+        }
+        reject(`dependency is not included in the transfer: ${reference}`);
+    };
+    if (spec.context?.base !== undefined) {
+        if (!Array.isArray(spec.context.base))
+            reject("context.base must be an array");
+        for (const reference of spec.context.base) {
+            const declared = typeof reference === "object" && reference !== null ? reference.path : reference;
+            if (bundledSetup) {
+                if (typeof declared !== "string" || !BUNDLED_SETUP_CONTEXT.has(declared))
+                    reject(`unsupported bundled setup dependency: ${String(declared)}`);
+                requireReference(path.join(bundle.source.workerDir, declared), true);
+            }
+            else {
+                requireReference(declared, true);
+            }
+        }
+    }
+    if (spec.skills !== undefined) {
+        if (!Array.isArray(spec.skills))
+            reject("skills must be an array");
+        for (const skill of spec.skills) {
+            if (!skill || typeof skill !== "object" || Array.isArray(skill))
+                reject("invalid skill declaration");
+            for (const field of ["path", "run"]) {
+                if (skill[field] !== undefined)
+                    requireReference(skill[field], false);
+            }
+            // Worker templates resolve `doc` relative to the worker, unlike the
+            // scaffold's HQ-root-relative `path` and `run` entries.
+            if (skill.doc !== undefined) {
+                if (typeof skill.doc !== "string")
+                    reject("invalid skill doc reference");
+                requireReference(path.isAbsolute(skill.doc) ? skill.doc : path.join(bundle.source.workerDir, skill.doc), false);
+            }
+        }
+    }
+}
+/** Produce a reviewable write plan, never mutate a live Fleet installation.
+ * Source files remain in the bundle. Only known source roots are relocated;
+ * unaccounted Mac paths fail rather than silently producing broken skills.
+ */
+export function planBotContinuityImport(bundle, target) {
+    validateBotContinuity(bundle, target);
+    if (bundle.companySlug && bundle.companySlug !== target.companySlug)
+        reject("company context cannot cross tenants");
+    if (!path.isAbsolute(target.hqRoot) || containsControl(target.hqRoot))
+        reject("invalid destination root");
+    const ownRoot = `personal/bots/${bundle.agentUid}/continuity`;
+    const worker = `${ownRoot}/worker`;
+    const memory = `${ownRoot}/memory`;
+    const replacements = [
+        [bundle.source.memoryDir, path.join(target.hqRoot, memory)],
+        [path.join(bundle.source.hqRoot, bundle.source.workerDir), path.join(target.hqRoot, worker)],
+        [bundle.source.workerDir, worker],
+        [bundle.source.hqRoot, target.hqRoot],
+    ].sort((a, b) => b[0].length - a[0].length);
+    const mapping = new Map(replacements.map(([from, to]) => [from, to]));
+    const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const roots = new RegExp(`(?:${[...mapping.keys()].map(escapeRegex).join("|")})(?![\\w.-])`, "g");
+    return bundle.files.map((file) => {
+        let bytes = Buffer.from(file.base64, "base64");
+        if (isUtf8(bytes)) {
+            let text = bytes.toString("utf8");
+            text = text.replace(roots, (from) => mapping.get(from));
+            if (file.area === "worker" && file.path === "worker.yaml" && bundle.source.workerDir === BUNDLED_SETUP_WORKER_DIR) {
+                const spec = yaml.load(text);
+                if (spec.context?.base) {
+                    spec.context.base = spec.context.base.map((entry) => typeof entry === "string"
+                        ? `${worker}/${entry}`
+                        : { ...entry, path: `${worker}/${entry.path}` });
+                }
+                text = yaml.dump(spec, { lineWidth: -1 });
+            }
+            if (file.area === "worker" && /\/(?:Users|Volumes)\//.test(text))
+                reject(`unresolved Mac path in ${file.area}/${file.path}`);
+            bytes = Buffer.from(text);
+        }
+        return { path: `${ownRoot}/${file.area}/${file.path}`, bytes, executable: file.executable, sourceSha256: file.sha256, sha256: sha(bytes) };
+    });
+}
+/** Prepare the existing Fleet SOUL seam before the first gateway session.
+ * This is generated from the private continuity copy, not the owner's overlay.
+ * Installation, prompt-cache invalidation and gateway activation remain the
+ * provisioning coordinator's responsibility; this function performs no writes.
+ */
+export function planFleetContinuity(bundle, target) {
+    const files = planBotContinuityImport(bundle, target);
+    const workerRoot = `personal/bots/${bundle.agentUid}/continuity/worker`;
+    const workerFile = files.find((file) => file.path === `${workerRoot}/worker.yaml`);
+    const spec = yaml.load(workerFile.bytes.toString("utf8"));
+    const persona = files.find((file) => file.path === `${workerRoot}/persona.md`);
+    const identity = { worker: spec.worker, identity: spec.identity, instructions: spec.instructions };
+    const sections = [
+        "# Continuing your HQ identity",
+        "You are the same teammate described below. Moving from this person's computer to cloud compute does not change your identity, role, voice, learned context, or relationship with them. Use your established name from the persona and identity below. Do not introduce yourself as a new bot or as the underlying runtime.",
+        `## Identity and role\n\n${JSON.stringify(identity, null, 2)}`,
+    ];
+    if (persona) {
+        if (!isUtf8(persona.bytes))
+            reject("persona must be UTF-8 text");
+        sections.push(`## Established persona\n\n${persona.bytes.toString("utf8")}`);
+    }
+    sections.push(`## Existing skills\n\n${JSON.stringify(spec.skills ?? [], null, 2)}\n\nRead the matching skill document before using a skill. Supporting scripts are preserved with the same relative layout. Worker-relative doc references resolve under ${path.join(target.hqRoot, workerRoot)}.`, "## Saved private context\n\nThe following files are your existing context, including memories learned before promotion. Consult the relevant saved files before answering questions about prior work or preferences. These private files are not company-shared knowledge; do not publish or move their contents into the company index. Memory may mention paths on the original Mac. Treat those as historical references, not files available on this cloud computer; do not claim to have accessed them. Runtime credentials and the owner's broader permissions are not part of this transfer. Follow the current HQ authorization and company policies for actions.", ...files.map((file) => `- ${JSON.stringify(path.join(target.hqRoot, file.path))}`));
+    const soul = `${sections.join("\n\n")}\n`;
+    // Current Fleet render-soul.sh replaces any SOUL containing this marker.
+    // Reject rather than ship a persona that the installer would erase.
+    if (soul.includes("Nous Research"))
+        reject("persona conflicts with Fleet's default-identity replacement marker");
+    if (Buffer.byteLength(soul, "utf8") > 32 * 1024)
+        reject("identity context exceeds the SOUL transfer budget; nothing was truncated");
+    const policyContent = `${JSON.stringify({ schemaVersion: 1, agentUid: bundle.agentUid, scope: "private" })}\n`;
+    return { files, soul, soulSha256: sha(soul), sourceDigest: bundle.digest,
+        memoryPolicy: {
+            path: `personal/bots/${bundle.agentUid}/continuity/memory-policy.json`,
+            content: policyContent,
+            sha256: sha(policyContent),
+        },
+    };
+}
+//# sourceMappingURL=continuity.js.map

package/dist/lib/bot/creds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Per-bot Cognito machine credentials (local-bots US-005).
+ *
+ * Written 0600 in the exact shape `ensureCognitoToken({ tokenSource:
+ * "machine" })` / hq-cloud `loadMachineCreds` read from HQ_MACHINE_CREDS_FILE.
+ * The secret is never logged or printed; `hq bot status` only reports whether
+ * the file exists and which agt_ it is for.
+ */
+export interface BotMachineCreds {
+    username: string;
+    secret: string;
+    entityType: "agent";
+    entityUid: string;
+    clientId: string;
+    region: string;
+}
+export declare function writeBotCreds(dir: string, creds: BotMachineCreds): string;
+/** Non-secret view of the creds file: which identity it is for. */
+export declare function readBotCredsIdentity(dir: string): {
+    entityUid: string;
+    username: string;
+} | null;
+export declare function deleteBotCreds(dir: string): void;
+//# sourceMappingURL=creds.d.ts.map

package/dist/lib/bot/creds.js

@@ -0,0 +1,51 @@
+/**
+ * Per-bot Cognito machine credentials (local-bots US-005).
+ *
+ * Written 0600 in the exact shape `ensureCognitoToken({ tokenSource:
+ * "machine" })` / hq-cloud `loadMachineCreds` read from HQ_MACHINE_CREDS_FILE.
+ * The secret is never logged or printed; `hq bot status` only reports whether
+ * the file exists and which agt_ it is for.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botCredsPath } from "./paths.js";
+export function writeBotCreds(dir, creds) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botCredsPath(dir);
+    const tmp = path.join(dir, `.creds.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(creds, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+    try {
+        fs.chmodSync(dest, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    return dest;
+}
+/** Non-secret view of the creds file: which identity it is for. */
+export function readBotCredsIdentity(dir) {
+    const p = botCredsPath(dir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (typeof raw.entityUid !== "string" || typeof raw.username !== "string")
+            return null;
+        if (typeof raw.secret !== "string" || !raw.secret)
+            return null;
+        return { entityUid: raw.entityUid, username: raw.username };
+    }
+    catch {
+        return null;
+    }
+}
+export function deleteBotCreds(dir) {
+    try {
+        fs.unlinkSync(botCredsPath(dir));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=creds.js.map

package/dist/lib/bot/daemon.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-bot launchd user agent (local-bots US-005). macOS only for this PRD;
+ * Linux writes a systemd user unit as a best-effort extra.
+ *
+ *   ~/Library/LaunchAgents/ai.getindigo.hq-bot.<name>.plist
+ *     ProgramArguments: <node> <hq> bot run <name>
+ *     RunAtLoad + KeepAlive{SuccessfulExit:false}  — starts at login, restarts
+ *     on crash, but a clean exit 0 (bot disabled via `hq bot stop`) stays down.
+ *
+ * `launchctl` is injected so tests never touch the real service manager.
+ */
+import * as fs from "node:fs";
+export type BotDaemonPlatform = "darwin" | "linux" | "other";
+export interface BotDaemonPaths {
+    home: string;
+    name: string;
+    label: string;
+    hqBinary: string;
+    nodeBinary: string;
+    botDir: string;
+    logPath: string;
+    plistPath: string;
+    systemdUnitPath: string;
+    /** Extra PATH entries so the model CLI resolves under launchd. */
+    pathEntries: string[];
+    hqRoot?: string;
+}
+export interface LaunchctlExec {
+    (args: string[]): {
+        ok: boolean;
+        stdout: string;
+        stderr: string;
+    };
+}
+export declare function detectBotPlatform(platform?: NodeJS.Platform): BotDaemonPlatform;
+export declare function defaultPathEntries(home: string): string[];
+export declare function buildBotDaemonPaths(opts: {
+    name: string;
+    botDir: string;
+    home?: string;
+    hqBinary?: string;
+    nodeBinary?: string;
+    hqRoot?: string;
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    execPath?: string;
+}): BotDaemonPaths;
+export declare function renderBotLaunchdPlist(p: BotDaemonPaths): string;
+export declare function renderBotSystemdUnit(p: BotDaemonPaths): string;
+export declare function launchdDomain(uid?: number): string;
+export interface BotDaemonResult {
+    platform: BotDaemonPlatform;
+    action: "install" | "uninstall" | "status" | "start" | "stop";
+    installed: boolean;
+    loaded: boolean;
+    dest?: string;
+    message: string;
+}
+export interface BotDaemonDeps {
+    platform?: BotDaemonPlatform;
+    launchctl?: LaunchctlExec;
+    uid?: number;
+    fsImpl?: Pick<typeof fs, "existsSync" | "writeFileSync" | "mkdirSync" | "unlinkSync">;
+    /** Blocking sleep, injectable for tests. */
+    sleepMs?: (ms: number) => void;
+}
+/** Write the unit and load it (RunAtLoad starts the bot immediately). */
+export declare function installBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
+export declare function uninstallBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
+export declare function botDaemonStatus(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
+/** Load an installed LaunchAgent (idempotent: already-loaded is fine). */
+export declare function startBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
+/** Unload the job (plist stays, so the bot returns at next login unless disabled). */
+export declare function stopBotDaemon(p: BotDaemonPaths, deps?: BotDaemonDeps): BotDaemonResult;
+//# sourceMappingURL=daemon.d.ts.map