@indigoai-us/hq-cli 5.109.16 → 5.110.0

package/dist/lib/bot/config.js

@@ -0,0 +1,141 @@
+/**
+ * bot.json — non-secret per-bot configuration (local-bots US-003/US-005).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botConfigPath } from "./paths.js";
+export const BOT_RUNTIMES = ["claude", "codex", "grok"];
+export function isBotRuntimeId(value) {
+    return typeof value === "string" && BOT_RUNTIMES.includes(value);
+}
+/** Longest `intro` (first-start hello DM) a bot may store. */
+export const BOT_INTRO_MAX_CHARS = 500;
+/** Longest `kickoff` (first-start model turn prompt) a bot may store. */
+export const BOT_KICKOFF_MAX_CHARS = 2000;
+/**
+ * Where a bot keeps its memory: "synced" = personal/workers/<name>/memory
+ * inside the HQ tree (follows the owner across machines); "local" =
+ * ~/.hq/bots/<name>/memory, outside the synced tree (this computer only).
+ */
+export const BOT_MEMORY_MODES = ["synced", "local"];
+export function isBotMemoryMode(value) {
+    return typeof value === "string" && BOT_MEMORY_MODES.includes(value);
+}
+/**
+ * Thinking ("effort") levels each runtime's CLI accepts, verified 2026-09-12:
+ * `claude --effort`, `codex -c model_reasoning_effort=…`, `grok --reasoning-effort`.
+ */
+export const BOT_EFFORT_LEVELS = {
+    claude: ["low", "medium", "high", "xhigh", "max"],
+    codex: ["minimal", "low", "medium", "high", "xhigh"],
+    grok: ["low", "medium", "high", "xhigh"],
+};
+/** Every bot thinks at medium unless its owner picks otherwise: quick chat replies. */
+export const DEFAULT_BOT_EFFORT = "medium";
+/** The thinking level a bot actually runs with. */
+export function effectiveBotEffort(config) {
+    return config.effort?.trim() || DEFAULT_BOT_EFFORT;
+}
+/**
+ * A thinking level for this runtime, or undefined for "default" / empty
+ * (the bot then runs at DEFAULT_BOT_EFFORT). Throws an expected error otherwise.
+ */
+export function validateBotEffort(runtime, value) {
+    const v = (value ?? "").trim().toLowerCase();
+    if (!v || v === "default")
+        return undefined;
+    const levels = BOT_EFFORT_LEVELS[runtime];
+    if (!levels.includes(v)) {
+        throw Object.assign(new Error(`--effort for ${runtime} must be one of ${levels.join(", ")} (or default).`), { expected: true });
+    }
+    return v;
+}
+/**
+ * A model id for the runtime CLI, or undefined for "default" / empty (the
+ * CLI's own default for the owner's account). Throws an expected error when
+ * it cannot be a model id.
+ */
+export function validateBotModel(value) {
+    const v = (value ?? "").trim();
+    if (!v || v.toLowerCase() === "default")
+        return undefined;
+    if (v.length > 100 || !/^[A-Za-z0-9][\w.:\[\]/-]*$/.test(v)) {
+        throw Object.assign(new Error(`--model "${v.slice(0, 40)}" is not a model id (letters, digits, . _ - : / [ ]).`), { expected: true });
+    }
+    return v;
+}
+/** Trim and bound the intro text; throws an expected error when unusable. */
+export function validateBotIntro(text) {
+    const trimmed = (text ?? "").replace(/\r\n/g, "\n").trim();
+    if (!trimmed) {
+        throw Object.assign(new Error("--intro needs some text (the hello the bot sends you when it first comes online)."), {
+            expected: true,
+        });
+    }
+    if (trimmed.length > BOT_INTRO_MAX_CHARS) {
+        throw Object.assign(new Error(`--intro is too long (${trimmed.length} chars); keep it under ${BOT_INTRO_MAX_CHARS}.`), {
+            expected: true,
+        });
+    }
+    return trimmed;
+}
+/** Trim and bound the kickoff prompt; throws an expected error when unusable. */
+export function validateBotKickoff(text) {
+    const trimmed = (text ?? "").replace(/\r\n/g, "\n").trim();
+    if (!trimmed) {
+        throw Object.assign(new Error("--kickoff needs some text (the first task the bot starts on, right after its hello)."), {
+            expected: true,
+        });
+    }
+    if (trimmed.length > BOT_KICKOFF_MAX_CHARS) {
+        throw Object.assign(new Error(`--kickoff is too long (${trimmed.length} chars); keep it under ${BOT_KICKOFF_MAX_CHARS}.`), {
+            expected: true,
+        });
+    }
+    return trimmed;
+}
+export function readBotConfig(dir) {
+    const p = botConfigPath(dir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || typeof raw.name !== "string" || typeof raw.agentUid !== "string") {
+            return null;
+        }
+        if (!isBotRuntimeId(raw.runtime))
+            return null;
+        const { intro: rawIntro, kickoff: rawKickoff, ...rest } = raw;
+        const intro = typeof rawIntro === "string" && rawIntro.trim() ? rawIntro : undefined;
+        const kickoff = typeof rawKickoff === "string" && rawKickoff.trim() ? rawKickoff : undefined;
+        return { ...rest, ...(intro ? { intro } : {}), ...(kickoff ? { kickoff } : {}), enabled: raw.enabled !== false };
+    }
+    catch {
+        return null;
+    }
+}
+export function writeBotConfig(dir, config) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botConfigPath(dir);
+    const tmp = path.join(dir, `.bot.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+}
+/** "local" when the memory folder is an absolute path outside the HQ tree. */
+export function botMemoryMode(config) {
+    return config.memoryDir && path.isAbsolute(config.memoryDir) ? "local" : "synced";
+}
+/** Absolute memory folder for a bot (synced memory is resolved against hqRoot). */
+export function resolveBotMemoryDir(config) {
+    const rel = config.memoryDir?.trim() ? config.memoryDir.replace(/\/+$/, "") : path.join(config.workerDir, "memory");
+    return path.isAbsolute(rel) ? rel : path.join(config.hqRoot, rel);
+}
+export function patchBotConfig(dir, patch) {
+    const current = readBotConfig(dir);
+    if (!current)
+        throw new Error(`No bot config at ${botConfigPath(dir)}`);
+    const next = { ...current, ...patch, v: 1 };
+    writeBotConfig(dir, next);
+    return next;
+}
+//# sourceMappingURL=config.js.map

package/dist/lib/bot/continuity-download.d.ts

@@ -0,0 +1,28 @@
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+declare function readOwnVault(input: {
+    bucket: string;
+    key: string;
+    credentials: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken: string;
+    };
+}): Promise<{
+    body: ReadableStream<any>;
+    close: () => void;
+}>;
+/** The box uses its own HQ machine login; its shared EC2 role gets no vault access. */
+export declare function downloadContinuitySnapshot(input: {
+    agentUid: string;
+    key: string;
+    sha256: string;
+    bytes: number;
+    destination: string;
+}, deps?: {
+    credential: typeof ensureCognitoIdToken;
+    api: typeof vaultApiFetch;
+    download: typeof readOwnVault;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=continuity-download.d.ts.map

package/dist/lib/bot/continuity-download.js

@@ -0,0 +1,75 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { ensureCognitoIdToken } from "../../utils/cognito-session.js";
+import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
+import { vaultApiFetch } from "../../utils/vault-api.js";
+async function readOwnVault(input) {
+    const client = new S3Client({ region: "us-east-1", credentials: input.credentials });
+    try {
+        const response = await client.send(new GetObjectCommand({ Bucket: input.bucket, Key: input.key }), { abortSignal: AbortSignal.timeout(30000) });
+        if (!response.Body)
+            throw new Error("Promotion snapshot download failed");
+        return { body: response.Body.transformToWebStream(), close: () => client.destroy() };
+    }
+    catch (error) {
+        client.destroy();
+        throw error;
+    }
+}
+/** The box uses its own HQ machine login; its shared EC2 role gets no vault access. */
+export async function downloadContinuitySnapshot(input, deps = { credential: ensureCognitoIdToken, api: vaultApiFetch, download: readOwnVault }) {
+    if (!/^agt_[0-9A-HJKMNP-TV-Z]{26}$/.test(input.agentUid) || !/^[a-f0-9]{64}$/.test(input.sha256) ||
+        !Number.isSafeInteger(input.bytes) || input.bytes < 1 || input.bytes > 48 * 1024 * 1024 ||
+        !new RegExp(`^personal/bots/${input.agentUid}/promotions/[A-Za-z0-9_-]{16,128}/${input.sha256}\\.json$`).test(input.key)) {
+        throw new Error("Invalid promotion snapshot scope");
+    }
+    const token = await deps.credential({ interactive: false, tokenSource: "machine" });
+    const response = await deps.api({ token, path: "/sts/vend-self", method: "POST",
+        body: { personUid: input.agentUid, durationSeconds: 900 }, signal: AbortSignal.timeout(10000) });
+    if (!response.ok)
+        throw new Error(`Promotion snapshot authorization failed (${response.status})`);
+    const payload = await response.json();
+    const credentials = payload.credentials;
+    if (!credentials || !credentials.accessKeyId || !credentials.secretAccessKey || !credentials.sessionToken)
+        throw new Error("Promotion snapshot access was not granted");
+    const bucket = `hq-vault-agt-${input.agentUid.slice(4).toLowerCase()}`;
+    const download = await deps.download({ bucket, key: input.key, credentials: {
+            accessKeyId: credentials.accessKeyId, secretAccessKey: credentials.secretAccessKey, sessionToken: credentials.sessionToken,
+        } });
+    const chunks = [];
+    let count = 0;
+    const reader = download.body.getReader();
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            count += next.value.length;
+            if (count > input.bytes)
+                throw new Error("Promotion snapshot exceeded its expected size");
+            chunks.push(Buffer.from(next.value));
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        download.close();
+    }
+    const bytes = Buffer.concat(chunks);
+    if (bytes.length !== input.bytes || createHash("sha256").update(bytes).digest("hex") !== input.sha256) {
+        throw new Error("Promotion snapshot integrity check failed");
+    }
+    const destination = path.resolve(input.destination);
+    if (fs.realpathSync(path.dirname(destination)) !== path.dirname(destination))
+        throw new Error("Snapshot directory cannot use symlinks");
+    const temporary = `${destination}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, bytes, { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, destination);
+    }
+    finally {
+        bytes.fill(0);
+        fs.rmSync(temporary, { force: true });
+    }
+}
+//# sourceMappingURL=continuity-download.js.map

package/dist/lib/bot/continuity-install.d.ts

@@ -0,0 +1,14 @@
+import { type BotContinuityBundle, type ContinuityTarget } from "./continuity.js";
+export declare function installFleetContinuity(bundle: BotContinuityBundle, target: ContinuityTarget, fleetHome: string): {
+    version: number;
+    agentUid: string;
+    ownerUid: string;
+    sourceDigest: string;
+    soulSha256: string;
+    files: {
+        path: string;
+        sha256: string;
+        sourceSha256: string;
+    }[];
+};
+//# sourceMappingURL=continuity-install.d.ts.map

package/dist/lib/bot/continuity-install.js

@@ -0,0 +1,101 @@
+/** On-box import before the first gateway start. Never replaces an existing bot. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { planFleetContinuity } from "./continuity.js";
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
+function directory(root) {
+    const absolute = path.resolve(root);
+    let cursor = path.parse(absolute).root;
+    for (const part of absolute.slice(cursor.length).split(path.sep).filter(Boolean)) {
+        cursor = path.join(cursor, part);
+        try {
+            fs.mkdirSync(cursor, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const stat = fs.lstatSync(cursor);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error("Continuity destination must use real directories");
+    }
+}
+function verify(file, digest, executable = false) {
+    const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
+    try {
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > 32 * 1024 * 1024 || hash(fs.readFileSync(fd)) !== digest ||
+            Boolean(stat.mode & 0o111) !== executable || Boolean(stat.mode & 0o077)) {
+            throw new Error("Continuity readback failed");
+        }
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function exclusive(file, bytes, executable = false) {
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, executable ? 0o700 : 0o600);
+    try {
+        fs.writeFileSync(fd, bytes);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    verify(file, hash(bytes), executable);
+}
+export function installFleetContinuity(bundle, target, fleetHome) {
+    // Validate every byte, path, tenant and reference before the first mutation.
+    const plan = planFleetContinuity(bundle, target);
+    if (!path.isAbsolute(fleetHome))
+        throw new Error("Fleet home must be absolute");
+    const prefix = `personal/bots/${target.agentUid}/continuity/`;
+    const destination = path.join(target.hqRoot, prefix);
+    const parent = path.dirname(destination);
+    const soulPath = path.join(fleetHome, "SOUL.md");
+    directory(target.hqRoot);
+    directory(parent);
+    directory(fleetHome);
+    // An existing customized or default persona requires an explicit coordinator
+    // decision. Never overwrite it, including when a retry races another import.
+    if (fs.existsSync(soulPath) || fs.lstatSync(fleetHome).isSymbolicLink())
+        verify(soulPath, plan.soulSha256);
+    const receipt = {
+        version: 1, agentUid: target.agentUid, ownerUid: target.ownerUid,
+        sourceDigest: bundle.digest, soulSha256: plan.soulSha256,
+        files: plan.files.map(file => ({ path: file.path, sha256: file.sha256, sourceSha256: file.sourceSha256 })),
+    };
+    const receiptBytes = JSON.stringify(receipt) + "\n";
+    if (!fs.existsSync(destination)) {
+        const staging = fs.mkdtempSync(path.join(parent, ".continuity-import-"));
+        try {
+            directory(path.join(staging, "memory"));
+            for (const file of plan.files) {
+                const dest = path.join(staging, file.path.slice(prefix.length));
+                directory(path.dirname(dest));
+                exclusive(dest, file.bytes, file.executable);
+            }
+            exclusive(path.join(staging, "receipt.json"), receiptBytes);
+            // Policy is last: memory cannot become active with unverified imports.
+            exclusive(path.join(staging, "memory-policy.json"), plan.memoryPolicy.content);
+            fs.renameSync(staging, destination);
+        }
+        finally {
+            if (fs.existsSync(staging))
+                fs.rmSync(staging, { recursive: true });
+        }
+    }
+    directory(destination);
+    verify(path.join(destination, "receipt.json"), hash(receiptBytes));
+    for (const file of plan.files) {
+        directory(path.dirname(path.join(target.hqRoot, file.path)));
+        verify(path.join(target.hqRoot, file.path), file.sha256, file.executable);
+    }
+    verify(path.join(destination, "memory-policy.json"), plan.memoryPolicy.sha256);
+    if (!fs.existsSync(soulPath))
+        exclusive(soulPath, plan.soul);
+    verify(soulPath, plan.soulSha256);
+    return receipt;
+}
+//# sourceMappingURL=continuity-install.js.map

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

@@ -0,0 +1,66 @@
+import type { BotConfig } from "./config.js";
+export interface ContinuityFile {
+    area: "worker" | "memory";
+    path: string;
+    bytes: number;
+    sha256: string;
+    executable: boolean;
+    base64: string;
+}
+export interface BotContinuityBundle {
+    version: 1;
+    agentUid: string;
+    ownerUid: string;
+    name: string;
+    companySlug?: string;
+    source: {
+        hqRoot: string;
+        workerDir: string;
+        memoryDir: string;
+    };
+    files: ContinuityFile[];
+    digest: string;
+}
+/** Capture original bytes, including supporting scripts and Mac-only memory. */
+export declare function snapshotBotContinuity(config: BotConfig, stateDir: string): BotContinuityBundle;
+/** Validate all bytes and ownership before planning any destination write. */
+export declare function validateBotContinuity(bundle: BotContinuityBundle, identity: {
+    agentUid: string;
+    ownerUid: string;
+}): void;
+export interface ContinuityImportFile {
+    path: string;
+    bytes: Buffer;
+    executable: boolean;
+    sourceSha256: string;
+    sha256: string;
+}
+export interface ContinuityTarget {
+    agentUid: string;
+    ownerUid: string;
+    hqRoot: string;
+    companySlug?: string;
+}
+/** 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 declare function planBotContinuityImport(bundle: BotContinuityBundle, target: ContinuityTarget): ContinuityImportFile[];
+/** 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 declare function planFleetContinuity(bundle: BotContinuityBundle, target: ContinuityTarget): {
+    files: ContinuityImportFile[];
+    soul: string;
+    soulSha256: string;
+    sourceDigest: string;
+    /** Install only after all imported file hashes have been verified. */
+    memoryPolicy: {
+        path: string;
+        content: string;
+        sha256: string;
+    };
+};
+//# sourceMappingURL=continuity.d.ts.map