@indigoai-us/hq-cli 5.345.170 → 5.345.171

package/dist/lib/bot/fleet-local.js

@@ -0,0 +1,638 @@
+import { execFileSync } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { HQ_FLEET_RUNTIME_ENGINE_ID, } from "./config.js";
+export const HQ_FLEET_LOCAL_RELEASE = {
+    repository: "indigoai-us/hq-fleet-local",
+    tag: "v0.4.2",
+    version: "0.4.2",
+    artifact: "hq-fleet-local-0.4.2.zip",
+    artifactSha256: "61af88c3e783f5cc6bc1bf99920e981680f67d3485fae6edc52cdfee61ce2108",
+    runtimeArtifact: "hq-fleet-runtime-abccac13bd9e.tar",
+    runtimeArtifactSha256: "29bcfe718ad7fbd3636afd00623772f2a25bc84c4f6f10d8d57f38e549d528d5",
+    manifestSha256: "d55a4b84d08659991f8bf2dba4b8590bd7874bf3adf4dad6bc1e08eac5462884",
+    signatureSha256: "31f0d27890f54956f3684e9401d04ed49b9f57fcb6da0440c25f5a31c5db1082",
+    runtimeCommit: "abccac13bd9ea593b24c8cd9c0ba28d5c6050cc9",
+};
+export const HQ_FLEET_LOCAL_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAOOL7NRKQgjMYI5cWxLY+HGppXf2AtwpQbCg5v+nBksM=
+-----END PUBLIC KEY-----
+`;
+function digest(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}
+function expectedError(message) {
+    return Object.assign(new Error(message), { expected: true });
+}
+function engineMetadata(release) {
+    return {
+        id: HQ_FLEET_RUNTIME_ENGINE_ID,
+        distribution: "hq-fleet-local",
+        version: release.version,
+        artifactSha256: release.artifactSha256,
+        runtimeCommit: release.runtimeCommit,
+    };
+}
+export function fleetHome(home = os.homedir(), env = process.env) {
+    return env.HQ_FLEET_HOME?.trim() || path.join(home, ".hq-fleet");
+}
+export function verifyFleetLocalRelease(files, release = HQ_FLEET_LOCAL_RELEASE, publicKey = HQ_FLEET_LOCAL_PUBLIC_KEY) {
+    if (digest(files.archive) !== release.artifactSha256) {
+        throw expectedError(`HQ Fleet Local ${release.version} archive hash did not match the release pin.`);
+    }
+    if (digest(files.runtimeArchive) !== release.runtimeArtifactSha256) {
+        throw expectedError(`HQ Fleet Local ${release.version} runtime archive hash did not match the release pin.`);
+    }
+    if (digest(files.manifest) !== release.manifestSha256) {
+        throw expectedError(`HQ Fleet Local ${release.version} manifest hash did not match the release pin.`);
+    }
+    if (digest(files.signature) !== release.signatureSha256) {
+        throw expectedError(`HQ Fleet Local ${release.version} signature hash did not match the release pin.`);
+    }
+    let manifest;
+    let signature;
+    try {
+        manifest = JSON.parse(files.manifest.toString("utf8"));
+        signature = JSON.parse(files.signature.toString("utf8"));
+    }
+    catch (error) {
+        throw expectedError(`HQ Fleet Local ${release.version} release metadata is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const distribution = manifest.distribution;
+    const runtime = manifest.runtime;
+    if (distribution?.name !== "hq-fleet-local" ||
+        distribution.version !== release.version ||
+        runtime?.commit !== release.runtimeCommit) {
+        throw expectedError(`HQ Fleet Local ${release.version} manifest does not match the pinned distribution.`);
+    }
+    if (signature.algorithm !== "ed25519" || typeof signature.signature !== "string") {
+        throw expectedError(`HQ Fleet Local ${release.version} signature record is invalid.`);
+    }
+    const valid = crypto.verify(null, files.manifest, crypto.createPublicKey(publicKey), Buffer.from(signature.signature, "base64"));
+    if (!valid) {
+        throw expectedError(`HQ Fleet Local ${release.version} manifest signature is invalid.`);
+    }
+}
+export function resolveFleetReleaseToken(env = process.env) {
+    for (const name of ["HQ_FLEET_RELEASE_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"]) {
+        const value = env[name]?.trim();
+        if (value)
+            return value;
+    }
+    try {
+        const value = execFileSync("gh", ["auth", "token"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            windowsHide: true,
+        }).trim();
+        if (value)
+            return value;
+    }
+    catch {
+        throw expectedError("HQ Fleet Local is a private Indigo preview. Sign in with GitHub CLI or set HQ_FLEET_RELEASE_GITHUB_TOKEN before creating this bot.");
+    }
+    throw expectedError("GitHub CLI returned an empty token for the private HQ Fleet Local release. Run gh auth login and retry.");
+}
+async function responseBytes(response, label) {
+    if (!response.ok) {
+        throw expectedError(`Could not download ${label}: GitHub returned HTTP ${response.status}.`);
+    }
+    return Buffer.from(await response.arrayBuffer());
+}
+export const FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS = 30_000;
+export const FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
+export const FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS = 20 * 60_000;
+async function downloadFleetLocalRelease(release, fetcher, token) {
+    const headers = {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "User-Agent": "hq-cli-fleet-local",
+        "X-GitHub-Api-Version": "2022-11-28",
+    };
+    const releaseUrl = `https://api.github.com/repos/${release.repository}/releases/tags/${release.tag}`;
+    const response = await fetcher(releaseUrl, { headers, signal: AbortSignal.timeout(30_000) });
+    if (!response.ok) {
+        throw expectedError(`Could not read HQ Fleet Local ${release.tag}: GitHub returned HTTP ${response.status}.`);
+    }
+    const body = (await response.json());
+    const assets = new Map((body.assets ?? [])
+        .filter((asset) => !!asset.name && !!asset.url)
+        .map((asset) => [asset.name, asset.url]));
+    const get = async (name, timeoutMs) => {
+        const url = assets.get(name);
+        if (!url)
+            throw expectedError(`HQ Fleet Local ${release.tag} is missing release asset ${name}.`);
+        if (new URL(url).origin !== "https://api.github.com") {
+            throw expectedError(`HQ Fleet Local ${release.tag} returned an untrusted asset URL for ${name}.`);
+        }
+        return responseBytes(await fetcher(url, {
+            headers: { ...headers, Accept: "application/octet-stream" },
+            signal: AbortSignal.timeout(timeoutMs),
+        }), name);
+    };
+    const [archive, runtimeArchive, manifest, signature] = await Promise.all([
+        get(release.artifact, FLEET_LOCAL_ARCHIVE_DOWNLOAD_TIMEOUT_MS),
+        get(release.runtimeArtifact, FLEET_LOCAL_RUNTIME_DOWNLOAD_TIMEOUT_MS),
+        get("release-manifest.json", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
+        get("release-manifest.sig", FLEET_LOCAL_METADATA_DOWNLOAD_TIMEOUT_MS),
+    ]);
+    return { archive, runtimeArchive, manifest, signature };
+}
+function installedFiles(dir, release) {
+    const archive = path.join(dir, release.artifact);
+    const runtimeArchive = path.join(dir, release.runtimeArtifact);
+    const manifest = path.join(dir, "release-manifest.json");
+    const signature = path.join(dir, "release-manifest.sig");
+    if (![archive, runtimeArchive, manifest, signature].every((file) => fs.existsSync(file)))
+        return null;
+    return {
+        archive: fs.readFileSync(archive),
+        runtimeArchive: fs.readFileSync(runtimeArchive),
+        manifest: fs.readFileSync(manifest),
+        signature: fs.readFileSync(signature),
+    };
+}
+function installFiles(target, files, release, publicKey) {
+    const parent = path.dirname(target);
+    fs.mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const staging = path.join(parent, `.install-${release.version}-${process.pid}-${crypto.randomUUID()}`);
+    const backup = path.join(parent, `.replace-${release.version}-${process.pid}-${crypto.randomUUID()}`);
+    fs.mkdirSync(staging, { mode: 0o700 });
+    try {
+        fs.writeFileSync(path.join(staging, release.artifact), files.archive, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, release.runtimeArtifact), files.runtimeArchive, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, "release-manifest.json"), files.manifest, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, "release-manifest.sig"), files.signature, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, "release-public.pem"), publicKey, { mode: 0o644 });
+        fs.writeFileSync(path.join(staging, "install.json"), `${JSON.stringify({ schemaVersion: 1, release, engine: engineMetadata(release) }, null, 2)}\n`, { mode: 0o644 });
+        if (fs.existsSync(target))
+            fs.renameSync(target, backup);
+        try {
+            fs.renameSync(staging, target);
+        }
+        catch (error) {
+            if (fs.existsSync(backup) && !fs.existsSync(target))
+                fs.renameSync(backup, target);
+            throw error;
+        }
+        if (fs.existsSync(backup))
+            fs.rmSync(backup, { recursive: true, force: true });
+    }
+    finally {
+        if (fs.existsSync(staging))
+            fs.rmSync(staging, { recursive: true, force: true });
+    }
+}
+export async function installPinnedFleetLocalDistribution(deps = {}) {
+    const release = deps.release ?? HQ_FLEET_LOCAL_RELEASE;
+    const publicKey = deps.publicKey ?? HQ_FLEET_LOCAL_PUBLIC_KEY;
+    const root = deps.fleetHome ?? fleetHome();
+    const dir = path.join(root, "distributions", "hq-fleet-local", release.version);
+    const current = installedFiles(dir, release);
+    if (current) {
+        verifyFleetLocalRelease(current, release, publicKey);
+    }
+    else {
+        const token = (deps.token ?? resolveFleetReleaseToken)();
+        const files = await downloadFleetLocalRelease(release, deps.fetch ?? fetch, token);
+        verifyFleetLocalRelease(files, release, publicKey);
+        installFiles(dir, files, release, publicKey);
+    }
+    return {
+        release,
+        dir,
+        archive: path.join(dir, release.artifact),
+        runtimeArchive: path.join(dir, release.runtimeArtifact),
+        manifest: path.join(dir, "release-manifest.json"),
+        signature: path.join(dir, "release-manifest.sig"),
+        engine: engineMetadata(release),
+    };
+}
+function profileRoot(agentUid, root) {
+    return path.join(root, "profiles", agentUid);
+}
+function venvExecutable(runtimeDir, name, platform) {
+    return platform === "win32"
+        ? path.join(runtimeDir, "Scripts", `${name}.exe`)
+        : path.join(runtimeDir, "bin", name);
+}
+function fleetLocalExecutables(agentUid, deps) {
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid)) {
+        throw expectedError(`Cannot use an HQ Fleet profile for invalid bot id ${agentUid}.`);
+    }
+    const root = deps.fleetHome ?? fleetHome();
+    const platform = deps.platform ?? process.platform;
+    const profileDir = profileRoot(agentUid, root);
+    const runtimeDir = path.join(profileDir, "runtime");
+    const profile = path.join(profileDir, "profile.json");
+    const runtime = venvExecutable(runtimeDir, "hq-fleet", platform);
+    const helper = venvExecutable(runtimeDir, "hq-fleet-local", platform);
+    if (![profile, runtime, helper].every((item) => fs.existsSync(item))) {
+        throw expectedError(`HQ Fleet Local is not fully installed for ${agentUid}.`);
+    }
+    return { profileDir, profile, runtime, helper };
+}
+function runJson(run, executable, args, options, label) {
+    let output;
+    try {
+        output = run(executable, args, { windowsHide: true, encoding: "utf8", ...options });
+    }
+    catch {
+        throw expectedError(`HQ Fleet Local ${label} failed.`);
+    }
+    try {
+        const value = JSON.parse(Buffer.isBuffer(output) ? output.toString("utf8") : output);
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            throw new Error("not an object");
+        return value;
+    }
+    catch {
+        throw expectedError(`HQ Fleet Local ${label} returned an invalid result.`);
+    }
+}
+export function controlFleetLocalBot(agentUid, action, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const files = fleetLocalExecutables(agentUid, deps);
+    return runJson(run, files.helper, ["service", action, "--profile", files.profileDir, "--runtime", files.runtime], { stdio: ["ignore", "pipe", "pipe"] }, `service ${action}`);
+}
+const providerProfiles = {
+    chatgpt: {
+        provider: "custom:personal-chatgpt",
+        runtimeProvider: "openai-codex",
+        model: "gpt-5.6-sol",
+        baseUrl: "https://chatgpt.com/backend-api/codex",
+        transport: "codex_responses",
+        oauth: true,
+    },
+    codex: {
+        provider: "custom:personal-chatgpt",
+        runtimeProvider: "openai-codex",
+        model: "gpt-5.6-sol",
+        baseUrl: "https://chatgpt.com/backend-api/codex",
+        transport: "codex_responses",
+        oauth: true,
+    },
+    "openai-codex": {
+        provider: "custom:personal-chatgpt",
+        runtimeProvider: "openai-codex",
+        model: "gpt-5.6-sol",
+        baseUrl: "https://chatgpt.com/backend-api/codex",
+        transport: "codex_responses",
+        oauth: true,
+    },
+    grok: {
+        provider: "custom:personal-grok",
+        runtimeProvider: "xai-oauth",
+        model: "grok-4",
+        baseUrl: "https://api.x.ai/v1",
+        transport: "chat_completions",
+        oauth: true,
+    },
+    xai: {
+        provider: "custom:personal-grok",
+        runtimeProvider: "xai-oauth",
+        model: "grok-4",
+        baseUrl: "https://api.x.ai/v1",
+        transport: "chat_completions",
+        oauth: true,
+    },
+    "xai-oauth": {
+        provider: "custom:personal-grok",
+        runtimeProvider: "xai-oauth",
+        model: "grok-4",
+        baseUrl: "https://api.x.ai/v1",
+        transport: "chat_completions",
+        oauth: true,
+    },
+    claude: {
+        provider: "custom:personal-anthropic",
+        runtimeProvider: "anthropic",
+        model: "claude-sonnet-4-6",
+        baseUrl: "https://api.anthropic.com",
+        transport: "anthropic_messages",
+        oauth: false,
+    },
+    anthropic: {
+        provider: "custom:personal-anthropic",
+        runtimeProvider: "anthropic",
+        model: "claude-sonnet-4-6",
+        baseUrl: "https://api.anthropic.com",
+        transport: "anthropic_messages",
+        oauth: false,
+    },
+};
+function replaceProfileProvider(profilePath, agentUid, provider) {
+    let profile;
+    try {
+        profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
+    }
+    catch {
+        throw expectedError(`HQ Fleet Local profile is unreadable for ${agentUid}.`);
+    }
+    if (profile.schemaVersion !== 1 || profile.botId !== agentUid) {
+        throw expectedError(`HQ Fleet Local profile does not belong to ${agentUid}.`);
+    }
+    profile.provider = provider;
+    const credentialProviders = Array.isArray(profile.credentialProviders)
+        ? profile.credentialProviders.filter((value) => typeof value === "string")
+        : [];
+    profile.credentialProviders = [...new Set([...credentialProviders, provider.credentialProvider])];
+    const temporary = `${profilePath}.${process.pid}.${crypto.randomUUID()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, profilePath);
+}
+export function exportFleetLocalMachineCredential(agentUid, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const files = fleetLocalExecutables(agentUid, deps);
+    const record = runJson(run, files.helper, ["machine-credential", "export", "--profile", files.profileDir, "--bot-id", agentUid], { stdio: ["ignore", "pipe", "pipe"] }, "machine credential export");
+    const text = (key) => (typeof record[key] === "string" ? record[key].trim() : "");
+    const credential = {
+        username: text("username"),
+        secret: typeof record.secret === "string" ? record.secret : "",
+        entityType: "agent",
+        entityUid: text("entityUid"),
+        clientId: text("clientId"),
+        region: text("region"),
+    };
+    const entityType = record.entityType ?? "agent";
+    if (entityType !== "agent" ||
+        credential.entityUid !== agentUid ||
+        !credential.username ||
+        !credential.secret ||
+        !credential.clientId ||
+        !credential.region) {
+        credential.secret = "";
+        throw expectedError(`HQ Fleet Local machine credential does not belong to ${agentUid}.`);
+    }
+    return credential;
+}
+export function fleetLocalPromotionRuntime(agentUid, deps = {}) {
+    return {
+        stop: () => {
+            controlFleetLocalBot(agentUid, "stop", deps);
+        },
+        machineCredential: () => exportFleetLocalMachineCredential(agentUid, deps),
+    };
+}
+export function removeFleetLocalBot(agentUid, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(agentUid)) {
+        throw expectedError(`Cannot use an HQ Fleet profile for invalid bot id ${agentUid}.`);
+    }
+    const profileDir = profileRoot(agentUid, deps.fleetHome ?? fleetHome());
+    if (!fs.existsSync(profileDir))
+        return { removed: false, credentialsRemoved: 0 };
+    const platform = deps.platform ?? process.platform;
+    const runtimeDir = path.join(profileDir, "runtime");
+    const partial = ![
+        path.join(profileDir, "profile.json"),
+        venvExecutable(runtimeDir, "hq-fleet", platform),
+        venvExecutable(runtimeDir, "hq-fleet-local", platform),
+    ].every((item) => fs.existsSync(item));
+    if (partial) {
+        fs.rmSync(profileDir, { recursive: true, force: true });
+        return { removed: true, credentialsRemoved: 0 };
+    }
+    const files = fleetLocalExecutables(agentUid, deps);
+    let profile;
+    try {
+        profile = JSON.parse(fs.readFileSync(files.profile, "utf8"));
+    }
+    catch {
+        throw expectedError(`HQ Fleet Local profile is unreadable for ${agentUid}.`);
+    }
+    const providers = Array.isArray(profile.credentialProviders)
+        ? profile.credentialProviders.filter((value) => typeof value === "string")
+        : [];
+    runJson(run, files.helper, ["service", "remove", "--profile", files.profileDir, "--runtime", files.runtime], { stdio: ["ignore", "pipe", "pipe"] }, "service removal");
+    for (const provider of providers) {
+        runJson(run, files.helper, ["auth", "logout", "--profile", files.profileDir, "--bot-id", agentUid, "--provider", provider], { stdio: ["ignore", "pipe", "pipe"] }, `${provider} credential removal`);
+    }
+    runJson(run, files.helper, ["machine-credential", "delete", "--profile", files.profileDir, "--bot-id", agentUid], { stdio: ["ignore", "pipe", "pipe"] }, "machine credential removal");
+    fs.rmSync(files.profileDir, { recursive: true, force: true });
+    return { removed: true, credentialsRemoved: providers.length + 1 };
+}
+export function authenticateFleetLocalBot(input, deps = {}) {
+    const requested = input.provider.trim().toLowerCase();
+    if (!/^[a-z0-9][a-z0-9._:-]*$/.test(requested)) {
+        throw expectedError("HQ Fleet provider identifier is invalid.");
+    }
+    const known = providerProfiles[requested];
+    const provider = known ?? {
+        provider: `custom:personal-${requested}`,
+        runtimeProvider: requested,
+        model: input.model?.trim() ?? "",
+        baseUrl: input.baseUrl?.trim() ?? "",
+        transport: input.transport ?? "chat_completions",
+        oauth: false,
+    };
+    const model = input.model?.trim() || provider.model;
+    const baseUrl = input.baseUrl?.trim() || provider.baseUrl;
+    const transport = input.transport ?? provider.transport;
+    if (!model)
+        throw expectedError(`Pass --model for runtime provider ${requested}.`);
+    if (!baseUrl)
+        throw expectedError(`Pass --base-url for runtime provider ${requested}.`);
+    if (!provider.oauth && !input.apiKey) {
+        throw expectedError(`Pass --api-key and provide ${provider.runtimeProvider} credentials on stdin.`);
+    }
+    const run = deps.run ?? execFileSync;
+    const files = fleetLocalExecutables(input.agentUid, deps);
+    const authArgs = provider.oauth && !input.apiKey
+        ? [
+            "auth",
+            "login",
+            "--profile",
+            files.profileDir,
+            "--bot-id",
+            input.agentUid,
+            "--provider",
+            provider.runtimeProvider,
+            ...(input.openBrowser === false ? ["--no-browser"] : []),
+        ]
+        : [
+            "auth",
+            "api-key",
+            "--profile",
+            files.profileDir,
+            "--bot-id",
+            input.agentUid,
+            "--provider",
+            provider.runtimeProvider,
+            "--base-url",
+            baseUrl,
+        ];
+    const auth = runJson(run, files.helper, authArgs, input.apiKey
+        ? { input: input.apiKey, stdio: ["pipe", "pipe", "pipe"] }
+        : { stdio: ["inherit", "pipe", "inherit"] }, `${provider.runtimeProvider} authentication`);
+    if (auth.authenticated !== true) {
+        throw expectedError(`HQ Fleet Local could not authenticate ${provider.runtimeProvider}.`);
+    }
+    replaceProfileProvider(files.profile, input.agentUid, {
+        id: provider.provider,
+        model,
+        credentialProvider: provider.runtimeProvider,
+        baseUrl,
+        transport,
+    });
+    runJson(run, files.helper, ["render-profile", "--spec", files.profile, "--mode", "update"], { stdio: ["ignore", "pipe", "pipe"] }, "profile update");
+    runJson(run, files.helper, ["doctor-profile", "--profile", files.profileDir, "--runtime", files.runtime], { stdio: ["ignore", "pipe", "pipe"] }, "profile validation");
+    const restarted = controlFleetLocalBot(input.agentUid, "restart", deps).ok === true;
+    return {
+        provider: requested,
+        runtimeProvider: provider.runtimeProvider,
+        model,
+        authenticated: true,
+        restarted,
+    };
+}
+export function writeFleetLocalProfile(input, deps = {}) {
+    if (!/^agt_[A-Za-z0-9_-]+$/.test(input.agentUid)) {
+        throw expectedError(`Cannot create an HQ Fleet profile for invalid bot id ${input.agentUid}.`);
+    }
+    if (!/^prs_[A-Za-z0-9_-]+$/.test(input.ownerUid)) {
+        throw expectedError(`Cannot create an HQ Fleet profile for invalid owner id ${input.ownerUid}.`);
+    }
+    const root = deps.fleetHome ?? fleetHome();
+    const dir = profileRoot(input.agentUid, root);
+    const runtimeDir = path.join(dir, "runtime");
+    const destination = path.join(dir, "profile.json");
+    const temporary = path.join(dir, `.profile-${process.pid}-${crypto.randomUUID()}`);
+    const profile = {
+        schemaVersion: 1,
+        botId: input.agentUid,
+        ownerUid: input.ownerUid,
+        provider: { id: "custom:personal-chatgpt", model: "gpt-5.6-sol" },
+        hqRoot: path.resolve(input.hqRoot),
+        profileDir: path.resolve(dir),
+        runtime: { commit: input.installation.release.runtimeCommit, path: path.resolve(runtimeDir) },
+        paths: {
+            pluginSource: path.resolve(path.join(dir, "sources", "distribution", "src", "hq_fleet_local", "plugins", "hqdm")),
+            statusFile: path.resolve(path.join(input.botDir, "status.json")),
+            logsDir: path.resolve(path.join(input.botDir, "logs")),
+        },
+    };
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.mkdirSync(profile.paths.logsDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(temporary, `${JSON.stringify(profile, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, destination);
+    return destination;
+}
+function pythonCommand(run, platform) {
+    const candidates = platform === "win32"
+        ? [
+            { executable: "py", prefix: ["-3.13"] },
+            { executable: "py", prefix: ["-3.12"] },
+            { executable: "py", prefix: ["-3.11"] },
+            { executable: "python3", prefix: [] },
+        ]
+        : [
+            { executable: "python3.13", prefix: [] },
+            { executable: "python3.12", prefix: [] },
+            { executable: "python3.11", prefix: [] },
+            { executable: "python3", prefix: [] },
+        ];
+    for (const candidate of candidates) {
+        try {
+            run(candidate.executable, [
+                ...candidate.prefix,
+                "-c",
+                "import sys; raise SystemExit(0 if (3,11) <= sys.version_info[:2] < (3,14) else 1)",
+            ], { stdio: "ignore", windowsHide: true });
+            return candidate;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw expectedError("HQ Fleet Runtime needs Python 3.11, 3.12, or 3.13. Install one and retry.");
+}
+function checkedRun(run, executable, args, options, label) {
+    try {
+        run(executable, args, { windowsHide: true, ...options });
+    }
+    catch {
+        throw expectedError(`HQ Fleet Local ${label} failed.`);
+    }
+}
+export function bootstrapFleetLocalBot(input, deps = {}) {
+    const run = deps.run ?? execFileSync;
+    const platform = deps.platform ?? process.platform;
+    const root = deps.fleetHome ?? fleetHome();
+    const profileDir = profileRoot(input.agentUid, root);
+    const sources = path.join(profileDir, "sources");
+    const distributionSource = path.join(sources, "distribution");
+    const runtimeSource = path.join(sources, "runtime");
+    const runtimeDir = path.join(profileDir, "runtime");
+    const marker = path.join(profileDir, "bootstrap.json");
+    const python = pythonCommand(run, platform);
+    fs.mkdirSync(profileDir, { recursive: true, mode: 0o700 });
+    if (!fs.existsSync(marker)) {
+        fs.rmSync(sources, { recursive: true, force: true });
+        fs.rmSync(runtimeDir, { recursive: true, force: true });
+        fs.mkdirSync(distributionSource, { recursive: true, mode: 0o700 });
+        fs.mkdirSync(runtimeSource, { recursive: true, mode: 0o700 });
+        checkedRun(run, python.executable, [
+            ...python.prefix,
+            "-m",
+            "zipfile",
+            "-e",
+            input.installation.archive,
+            distributionSource,
+        ], { stdio: "ignore" }, "distribution extraction");
+        checkedRun(run, python.executable, [
+            ...python.prefix,
+            "-m",
+            "tarfile",
+            "-e",
+            input.installation.runtimeArchive,
+            runtimeSource,
+        ], { stdio: "ignore" }, "runtime extraction");
+        checkedRun(run, python.executable, [
+            ...python.prefix,
+            "-m",
+            "venv",
+            runtimeDir,
+        ], { stdio: "ignore" }, "environment creation");
+        const runtimePython = venvExecutable(runtimeDir, "python", platform);
+        checkedRun(run, runtimePython, [
+            "-m",
+            "pip",
+            "install",
+            "--disable-pip-version-check",
+            "--editable",
+            `${runtimeSource}[all,messaging,slack,anthropic]`,
+            distributionSource,
+        ], { stdio: ["ignore", 2, 2] }, "package installation");
+        fs.writeFileSync(marker, `${JSON.stringify({ schemaVersion: 1, engine: input.installation.engine }, null, 2)}\n`, { mode: 0o600 });
+    }
+    const profile = writeFleetLocalProfile(input, { fleetHome: root, platform });
+    const helper = venvExecutable(runtimeDir, "hq-fleet-local", platform);
+    const runtime = venvExecutable(runtimeDir, "hq-fleet", platform);
+    if (!fs.existsSync(helper) || !fs.existsSync(runtime)) {
+        throw expectedError("HQ Fleet Local installed without its runtime executables.");
+    }
+    checkedRun(run, helper, ["render-profile", "--spec", profile, "--mode", "create"], { stdio: "ignore" }, "profile rendering");
+    const machineValue = fs.readFileSync(input.machineCredentials, "utf8").trim();
+    if (!machineValue) {
+        throw expectedError(`HQ Fleet Local machine credential file is empty: ${input.machineCredentials}`);
+    }
+    checkedRun(run, helper, [
+        "machine-credential",
+        "import",
+        "--profile",
+        profileDir,
+        "--bot-id",
+        input.agentUid,
+    ], { input: machineValue, stdio: ["pipe", "ignore", "pipe"] }, "machine credential import");
+    fs.rmSync(input.machineCredentials, { force: true });
+    checkedRun(run, helper, ["doctor-profile", "--profile", profileDir, "--runtime", runtime], { stdio: "ignore" }, "profile validation");
+    const start = deps.start !== false;
+    if (start) {
+        checkedRun(run, helper, ["service", "install", "--profile", profileDir, "--runtime", runtime], { stdio: ["ignore", 2, 2] }, "service installation");
+    }
+    return { profile, runtime, helper, running: start };
+}
+//# sourceMappingURL=fleet-local.js.map

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

@@ -25,4 +25,5 @@ export * from "./pack-link.js";
 export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
+export * from "./fleet-local.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/bot/index.js

@@ -25,4 +25,5 @@ export * from "./pack-link.js";
 export * from "./lock.js";
 export * from "./display-name.js";
 export * from "./decisions.js";
+export * from "./fleet-local.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/bot/local-config.d.ts

@@ -9,7 +9,7 @@
  * checks the result before it leaves this machine: a bot's machine credentials
  * live only in ~/.hq/bots/<name>/machine-creds.json and never travel here.
  */
-import { type BotConfig, type BotKind, type BotMemoryMode, type BotRuntimeId } from "./config.js";
+import { type BotConfig, type BotEngineMetadata, type BotKind, type BotMemoryMode, type BotRuntimeId } from "./config.js";
 /**
  * Everything needed to rebuild a bot here, minus anything secret. Written on
  * create, returned by `GET /v1/agents/mine?local=1` and by the credential
@@ -18,6 +18,7 @@ import { type BotConfig, type BotKind, type BotMemoryMode, type BotRuntimeId } f
 export interface BotLocalConfig {
     v: 1;
     runtime?: BotRuntimeId;
+    engine?: BotEngineMetadata;
     /** "scaffold" (its own personal/workers/<name>) or "worker" (an HQ worker). */
     workerSource?: "scaffold" | "worker";
     workerId?: string;
@@ -37,7 +38,7 @@ export interface BotLocalConfig {
 /** Walks a value and throws when any key looks like it could carry a secret. */
 export declare function assertNoSecretKeys(value: unknown, path?: string): void;
 /** The bot.json fields a localConfig is built from — nothing else is read. */
-export type BotLocalConfigSource = Pick<BotConfig, "runtime" | "workerSource" | "workerId" | "companySlug" | "model" | "effort" | "kind" | "companies" | "autoApprove" | "memoryDir" | "displayName" | "intro" | "kickoff">;
+export type BotLocalConfigSource = Pick<BotConfig, "runtime" | "engine" | "workerSource" | "workerId" | "companySlug" | "model" | "effort" | "kind" | "companies" | "autoApprove" | "memoryDir" | "displayName" | "intro" | "kickoff">;
 /**
  * The non-secret settings of a bot, for the cloud to keep. Absolute paths
  * (hqRoot, memoryDir, workerDir) are deliberately left out: they belong to the