@indigoai-us/hq-cli 5.109.16 → 5.111.0

package/dist/lib/bot/scaffold.js

@@ -0,0 +1,94 @@
+/**
+ * personal/workers/<name>/ scaffold for a local bot (local-bots US-005/US-006).
+ * Never overwrites an existing file (the bot edits its own memory).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botWorkerRelDir } from "./paths.js";
+export function renderWorkerYaml(name, agentUid, runtime, memoryDir) {
+    const memory = (memoryDir?.trim() || `personal/workers/${name}/memory`).replace(/\/+$/, "");
+    return `worker:
+  id: ${name}
+  name: "${name}"
+  description: "Personal local HQ bot (${runtime}) — runs on this computer with the owner's permissions"
+  type: PersonalBot
+  version: "1.0"
+  kind: local-bot
+  agent_uid: ${agentUid}
+
+execution:
+  mode: resident
+  runtime: ${runtime}
+  managed_by: hq bot
+
+context:
+  base:
+    - personal/workers/${name}/persona.md
+    - ${memory}/
+`;
+}
+export function renderPersonaMd(name) {
+    return `# ${name}
+
+You are ${name}, a personal assistant bot that lives in this HQ.
+
+## Voice
+
+- Warm, direct, and brief. Answer the person, not the mechanics.
+- Ask one question at a time when something is genuinely ambiguous.
+- Never paste secrets, tokens, or credentials into a reply.
+
+## Standing instructions
+
+- Prefer HQ's own skills and \`hq\` commands over hand-rolled scripts.
+- When you finish a task, say what changed and where in one or two lines.
+- Keep durable facts about your owner in \`memory/\` (short markdown notes).
+`;
+}
+export function renderMemoryReadme(name) {
+    return `# ${name} memory
+
+Short markdown notes ${name} keeps between conversations: preferences, recurring
+context, and things the owner asked it to remember. ${name} may edit these files;
+you can too. Never store secrets here.
+`;
+}
+function writeIfMissing(io, file, body, result) {
+    if (io.existsSync(file)) {
+        result.kept.push(file);
+        return;
+    }
+    io.writeFileSync(file, body, { mode: 0o644 });
+    result.created.push(file);
+}
+/** Absolute memory folder for a scaffold: the override (relative to hqRoot unless absolute) or the default. */
+export function resolveScaffoldMemoryDir(hqRoot, name, memoryDir) {
+    const raw = memoryDir?.trim();
+    if (!raw)
+        return path.join(hqRoot, botWorkerRelDir(name), "memory");
+    return path.isAbsolute(raw) ? raw : path.join(hqRoot, raw);
+}
+/**
+ * The memory folder + README only — the memory a bot keeps between
+ * conversations: personal/workers/<name>/memory/ by default, or the given
+ * `memoryDir` (absolute for local memory). Used on its own for worker-sourced
+ * bots, whose definition lives in the company tree and must not be written
+ * to. Never overwrites an existing file.
+ */
+export function scaffoldBotMemory(hqRoot, name, io = fs, opts = {}) {
+    const dir = path.join(hqRoot, botWorkerRelDir(name));
+    const memoryDir = resolveScaffoldMemoryDir(hqRoot, name, opts.memoryDir);
+    const result = { dir, memoryDir, created: [], kept: [] };
+    io.mkdirSync(memoryDir, { recursive: true });
+    writeIfMissing(io, path.join(memoryDir, "README.md"), renderMemoryReadme(name), result);
+    return result;
+}
+export function scaffoldBotWorker(hqRoot, name, agentUid, runtime, io = fs, opts = {}) {
+    const result = scaffoldBotMemory(hqRoot, name, io, opts);
+    const { dir } = result;
+    io.mkdirSync(dir, { recursive: true });
+    writeIfMissing(io, path.join(dir, "worker.yaml"), renderWorkerYaml(name, agentUid, runtime, opts.memoryDir), result);
+    writeIfMissing(io, path.join(dir, "persona.md"), renderPersonaMd(name), result);
+    return result;
+}
+//# sourceMappingURL=scaffold.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * session.json — the model CLI's own session id so each DM turn resumes the
+ * same conversation (one headless invocation per DM, resumed by id).
+ * Rooms get their own file per channel (session-room-<channelId>.json) so the
+ * owner's DM context is never carried into a group chat, and vice versa.
+ */
+import { type BotSessionScope } from "./paths.js";
+import type { BotRuntimeId } from "./config.js";
+export interface BotSessionFile {
+    v: 1;
+    runtime: BotRuntimeId;
+    sessionId: string;
+    turns: number;
+    updatedAt: string;
+}
+export declare function readBotSession(dir: string, runtime: BotRuntimeId, scope?: BotSessionScope): BotSessionFile | null;
+export declare function writeBotSession(dir: string, session: BotSessionFile, scope?: BotSessionScope): void;
+export declare function clearBotSession(dir: string, scope?: BotSessionScope): void;
+//# sourceMappingURL=session.d.ts.map

package/dist/lib/bot/session.js

@@ -0,0 +1,39 @@
+/**
+ * session.json — the model CLI's own session id so each DM turn resumes the
+ * same conversation (one headless invocation per DM, resumed by id).
+ * Rooms get their own file per channel (session-room-<channelId>.json) so the
+ * owner's DM context is never carried into a group chat, and vice versa.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botSessionPath } from "./paths.js";
+export function readBotSession(dir, runtime, scope = "dm") {
+    const p = botSessionPath(dir, scope);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || raw.runtime !== runtime || typeof raw.sessionId !== "string")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeBotSession(dir, session, scope = "dm") {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botSessionPath(dir, scope);
+    const tmp = path.join(dir, `.session.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+}
+export function clearBotSession(dir, scope = "dm") {
+    try {
+        fs.unlinkSync(botSessionPath(dir, scope));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=session.js.map

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

@@ -0,0 +1,40 @@
+/**
+ * status.json — atomic, metadata-only runtime status (local-bots US-003).
+ */
+import type { BotRuntimeId } from "./config.js";
+export type BotState = "starting" | "running" | "stopped" | "failed";
+export interface BotStatusFile {
+    v: 1;
+    pid: number;
+    state: BotState;
+    runtime: BotRuntimeId;
+    startedAt: string;
+    lastActivityAt: string;
+    /** Model-CLI restarts since this process started. */
+    restarts: number;
+    /** Consecutive model-CLI failures inside the failure window. */
+    recentFailures: number;
+    lastHeartbeatAt?: string;
+    lastHeartbeatOk?: boolean;
+    lastInboxPollAt?: string;
+    /** Bounded, redacted stderr excerpt of the last model-CLI failure. */
+    lastError?: string;
+    /** Inbound DMs answered since start. */
+    repliesSent: number;
+    /** True only after this process has installed its graceful promotion signal. */
+    canDrainForPromotion?: boolean;
+    /**
+     * Claude only: permission mode the bot settled on after a fallback
+     * (e.g. "auto" when this Claude Code's settings disable bypassPermissions).
+     * Persisted so later turns skip the failed attempt.
+     */
+    claudePermissionMode?: string;
+    updatedAt: string;
+}
+export declare function defaultBotStatus(pid: number, runtime: BotRuntimeId, now?: () => Date): BotStatusFile;
+export declare function readBotStatus(dir: string): BotStatusFile | null;
+export declare function writeBotStatus(dir: string, status: BotStatusFile): void;
+export declare function patchBotStatus(dir: string, patch: Partial<BotStatusFile>, fallback: () => BotStatusFile, now?: () => Date): BotStatusFile;
+/** Live process check for a status file's pid. */
+export declare function isPidAlive(pid: number): boolean;
+//# sourceMappingURL=status.d.ts.map

package/dist/lib/bot/status.js

@@ -0,0 +1,66 @@
+/**
+ * status.json — atomic, metadata-only runtime status (local-bots US-003).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { botStatusPath } from "./paths.js";
+export function defaultBotStatus(pid, runtime, now = () => new Date()) {
+    const at = now().toISOString();
+    return {
+        v: 1,
+        pid,
+        state: "starting",
+        runtime,
+        startedAt: at,
+        lastActivityAt: at,
+        restarts: 0,
+        recentFailures: 0,
+        repliesSent: 0,
+        updatedAt: at,
+    };
+}
+export function readBotStatus(dir) {
+    const p = botStatusPath(dir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        if (raw.v !== 1 || typeof raw.pid !== "number")
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeBotStatus(dir, status) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const dest = botStatusPath(dir);
+    const tmp = path.join(dir, `.status.tmp.${process.pid}.${Date.now()}`);
+    fs.writeFileSync(tmp, `${JSON.stringify(status, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, dest);
+}
+export function patchBotStatus(dir, patch, fallback, now = () => new Date()) {
+    const current = readBotStatus(dir) ?? fallback();
+    const next = {
+        ...current,
+        ...patch,
+        v: 1,
+        updatedAt: now().toISOString(),
+    };
+    writeBotStatus(dir, next);
+    return next;
+}
+/** Live process check for a status file's pid. */
+export function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=status.js.map

package/dist/lib/bot/worker-source.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Workers a local bot can be created from (local-bots Feature 4; the desktop
+ * shows them as "templates").
+ *
+ * The registry (core/workers/registry.yaml) is the index; a worker is only
+ * offered when its worker.yaml actually exists on disk in the owner's synced
+ * tree — that tree is the ACL, so no session or company lookup is needed.
+ * Company workers (companies/<co>/workers/<id>) and core workers
+ * (core/workers/…) are both offered; personal bots' own scaffolds
+ * (personal/workers/*) are excluded. Because the registry generator keeps one
+ * entry per id, core workers it dropped are picked up straight from disk
+ * (core/workers/**\/worker.yaml, a few levels deep). Ids are unique across the
+ * registry; if a duplicate ever appears, a company worker (one with a company
+ * slug) wins over the core one, which in turn wins over an unslugged copy
+ * elsewhere in a company folder (e.g. a repo checkout's template workers).
+ * The CLI ships a setup-only fallback for a fresh HQ with no setup template.
+ */
+import { type RegistryWorker } from "../workers-registry/read.js";
+export declare const WORKER_SUMMARY_MAX_CHARS = 140;
+export type BotWorkerSource = "core" | "company";
+export interface BotWorkerOption {
+    id: string;
+    /** Display name (`worker.name` in worker.yaml), when the worker has one. */
+    name?: string;
+    /** hqRoot-relative worker folder, no trailing slash. */
+    path: string;
+    type: string;
+    /** "core" for core/workers/…, "company" for everything else. */
+    source: BotWorkerSource;
+    /** Company slug; null for core workers (and registry entries without one). */
+    company: string | null;
+    status?: string;
+    description?: string;
+    /**
+     * One-line blurb for pickers: worker.yaml's top-level `summary:`, else the
+     * first sentence of the description, at most WORKER_SUMMARY_MAX_CHARS.
+     * Empty string when the worker has neither.
+     */
+    summary: string;
+    /** Number of entries under `skills:` in worker.yaml. */
+    skillCount: number;
+}
+export interface WorkerSourceFs {
+    existsSync: (p: string) => boolean;
+    readFileSync?: (p: string, encoding: "utf8") => string;
+    readdirSync?: (p: string, opts: {
+        withFileTypes: true;
+    }) => Array<{
+        name: string;
+        isDirectory: () => boolean;
+    }>;
+}
+/** Collapse whitespace and take the first sentence, capped at `max` chars. */
+export declare function summarizeDescription(text: string | undefined, max?: number): string;
+/**
+ * Development-only override: extra folders whose immediate children hold a
+ * worker.yaml are offered as templates too, so a worker staged in a worktree
+ * can be tested before it is promoted into `core/`. Colon-separated absolute
+ * paths; unset means no change at all. Entries win over a same-id worker found
+ * anywhere else, which is the whole point — the staged copy is the one under
+ * test.
+ */
+export declare const EXTRA_WORKERS_DIR_ENV = "HQ_BOT_EXTRA_WORKERS_DIR";
+export declare function listBotWorkerOptions(hqRoot: string, io?: WorkerSourceFs, registry?: RegistryWorker[], env?: NodeJS.ProcessEnv): BotWorkerOption[];
+export declare function resolveBotWorker(hqRoot: string, workerId: string, io?: WorkerSourceFs, registry?: RegistryWorker[], env?: NodeJS.ProcessEnv): BotWorkerOption;
+//# sourceMappingURL=worker-source.d.ts.map

package/dist/lib/bot/worker-source.js

@@ -0,0 +1,283 @@
+/**
+ * Workers a local bot can be created from (local-bots Feature 4; the desktop
+ * shows them as "templates").
+ *
+ * The registry (core/workers/registry.yaml) is the index; a worker is only
+ * offered when its worker.yaml actually exists on disk in the owner's synced
+ * tree — that tree is the ACL, so no session or company lookup is needed.
+ * Company workers (companies/<co>/workers/<id>) and core workers
+ * (core/workers/…) are both offered; personal bots' own scaffolds
+ * (personal/workers/*) are excluded. Because the registry generator keeps one
+ * entry per id, core workers it dropped are picked up straight from disk
+ * (core/workers/**\/worker.yaml, a few levels deep). Ids are unique across the
+ * registry; if a duplicate ever appears, a company worker (one with a company
+ * slug) wins over the core one, which in turn wins over an unslugged copy
+ * elsewhere in a company folder (e.g. a repo checkout's template workers).
+ * The CLI ships a setup-only fallback for a fresh HQ with no setup template.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+import { packageRoot } from "../../utils/hq-roots.js";
+import { readWorkerRegistry } from "../workers-registry/read.js";
+export const WORKER_SUMMARY_MAX_CHARS = 140;
+const CORE_WORKERS_REL = path.join("core", "workers");
+/** core/workers/public/<team>/<id>/worker.yaml is the deepest layout in use. */
+const CORE_SCAN_MAX_DEPTH = 4;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", "skills", "memory"]);
+function normalizeWorkerPath(p) {
+    return p.replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function workerSourceFor(rel) {
+    return rel === "core/workers" || rel.startsWith("core/workers/") ? "core" : "company";
+}
+/** Higher wins when two registry entries share an id. */
+function duplicateRank(w, rel) {
+    if (workerSourceFor(rel) === "core")
+        return 1;
+    return w.company ? 2 : 0;
+}
+function asString(v) {
+    return typeof v === "string" && v.trim() ? v.trim() : undefined;
+}
+/** Collapse whitespace and take the first sentence, capped at `max` chars. */
+export function summarizeDescription(text, max = WORKER_SUMMARY_MAX_CHARS) {
+    const flat = (text ?? "").replace(/\s+/g, " ").trim();
+    if (!flat)
+        return "";
+    const m = /^(.*?[.!?])(?:\s|$)/.exec(flat);
+    let sentence = (m ? m[1] : flat).trim();
+    if (sentence.length > max) {
+        const cut = sentence.slice(0, max - 1);
+        const atWord = cut.lastIndexOf(" ");
+        sentence = `${(atWord > max / 2 ? cut.slice(0, atWord) : cut).replace(/[\s,;:]+$/, "")}…`;
+    }
+    return sentence;
+}
+function readWorkerYamlFacts(file, io) {
+    const out = { skillCount: 0 };
+    const read = io.readFileSync ?? ((p, enc) => fs.readFileSync(p, enc));
+    let doc = {};
+    try {
+        const parsed = yaml.load(read(file, "utf8"));
+        if (parsed && typeof parsed === "object")
+            doc = parsed;
+    }
+    catch {
+        return out;
+    }
+    const meta = (doc.worker && typeof doc.worker === "object" ? doc.worker : {});
+    out.id = asString(meta.id);
+    out.name = asString(meta.name);
+    out.type = asString(meta.type);
+    out.status = asString(meta.status);
+    out.summary = asString(doc.summary);
+    out.description = asString(meta.description) ?? asString(doc.description);
+    out.skillCount = Array.isArray(doc.skills) ? doc.skills.length : 0;
+    return out;
+}
+function toOption(w, rel, facts) {
+    const description = w.description ?? facts.description;
+    const source = workerSourceFor(rel);
+    return {
+        id: w.id,
+        ...(facts.name ? { name: facts.name } : {}),
+        path: rel,
+        type: w.type,
+        source,
+        company: source === "core" ? null : (w.company ?? null),
+        ...(w.status ? { status: w.status } : {}),
+        ...(description ? { description } : {}),
+        summary: facts.summary ? summarizeDescription(facts.summary) : summarizeDescription(description),
+        skillCount: facts.skillCount,
+    };
+}
+/** hqRoot-relative folders under core/workers/ that hold a worker.yaml. */
+function scanCoreWorkerDirs(hqRoot, io) {
+    const readdir = io.readdirSync ?? ((p, opts) => fs.readdirSync(p, opts));
+    const found = [];
+    const walk = (rel, depth) => {
+        if (depth > CORE_SCAN_MAX_DEPTH)
+            return;
+        let entries;
+        try {
+            entries = readdir(path.join(hqRoot, rel), { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (entries.some((e) => e.name === "worker.yaml" && !e.isDirectory())) {
+            found.push(rel);
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+                continue;
+            walk(path.join(rel, e.name), depth + 1);
+        }
+    };
+    if (io.existsSync(path.join(hqRoot, CORE_WORKERS_REL)))
+        walk(CORE_WORKERS_REL, 0);
+    return found;
+}
+/**
+ * Development-only override: extra folders whose immediate children hold a
+ * worker.yaml are offered as templates too, so a worker staged in a worktree
+ * can be tested before it is promoted into `core/`. Colon-separated absolute
+ * paths; unset means no change at all. Entries win over a same-id worker found
+ * anywhere else, which is the whole point — the staged copy is the one under
+ * test.
+ */
+export const EXTRA_WORKERS_DIR_ENV = "HQ_BOT_EXTRA_WORKERS_DIR";
+/** Above company (2) and core (1): a staged template outranks what is on disk. */
+const EXTRA_RANK = 3;
+/** Absolute, existing paths from the env var, in order, without duplicates. */
+function extraWorkerRoots(env, io) {
+    const raw = env[EXTRA_WORKERS_DIR_ENV];
+    if (typeof raw !== "string" || !raw.trim())
+        return [];
+    const roots = [];
+    for (const part of raw.split(":")) {
+        const dir = part.trim();
+        // A relative or missing path is a misconfiguration, not an error: a stale
+        // export in a shell profile must never break `hq bot workers`.
+        if (!dir || !path.isAbsolute(dir))
+            continue;
+        if (!io.existsSync(dir) || roots.includes(dir))
+            continue;
+        roots.push(dir);
+    }
+    return roots;
+}
+/**
+ * Absolute worker folders directly under `root` (one level, unlike the core
+ * scan). A root that is a file, or unreadable, yields nothing: readdir throws
+ * ENOTDIR / EACCES and we swallow it.
+ */
+function scanExtraWorkerDirs(root, io) {
+    const readdir = io.readdirSync ?? ((p, opts) => fs.readdirSync(p, opts));
+    let entries;
+    try {
+        entries = readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+            continue;
+        const dir = path.join(root, e.name);
+        if (io.existsSync(path.join(dir, "worker.yaml")))
+            found.push(dir);
+    }
+    return found;
+}
+export function listBotWorkerOptions(hqRoot, io = fs, registry = readWorkerRegistry(hqRoot), env = process.env) {
+    const byId = new Map();
+    // Duplicate id: company (slugged) > core > unslugged; ties keep the first.
+    const offer = (rank, option) => {
+        const existing = byId.get(option.id);
+        if (existing && existing.rank >= rank)
+            return;
+        byId.set(option.id, { rank, option });
+    };
+    const seenPaths = new Set();
+    for (const w of registry) {
+        if (!w?.id || !w.path)
+            continue;
+        const rel = normalizeWorkerPath(w.path);
+        if (rel.startsWith("personal/workers/") || rel === "personal/workers")
+            continue;
+        const yamlPath = path.join(hqRoot, rel, "worker.yaml");
+        if (!io.existsSync(yamlPath))
+            continue;
+        seenPaths.add(rel);
+        offer(duplicateRank(w, rel), toOption(w, rel, readWorkerYamlFacts(yamlPath, io)));
+    }
+    // Core workers the registry left out (its generator keeps one entry per id).
+    for (const rel of scanCoreWorkerDirs(hqRoot, io)) {
+        if (seenPaths.has(rel))
+            continue;
+        const facts = readWorkerYamlFacts(path.join(hqRoot, rel, "worker.yaml"), io);
+        const id = facts.id ?? path.basename(rel);
+        const entry = {
+            id,
+            path: rel,
+            type: facts.type ?? "Worker",
+            visibility: "public",
+            ...(facts.status ? { status: facts.status } : {}),
+            ...(facts.description ? { description: facts.description } : {}),
+        };
+        offer(duplicateRank(entry, rel), toOption(entry, rel, facts));
+    }
+    // Opt-in override, last so it outranks everything found above.
+    for (const root of extraWorkerRoots(env, io)) {
+        for (const abs of scanExtraWorkerDirs(root, io)) {
+            const facts = readWorkerYamlFacts(path.join(abs, "worker.yaml"), io);
+            const id = facts.id ?? path.basename(abs);
+            // Stay hqRoot-relative (possibly via `..`): callers resolve the folder as
+            // path.join(hqRoot, option.path), which an absolute path would break.
+            const rel = normalizeWorkerPath(path.relative(hqRoot, abs));
+            const entry = {
+                id,
+                path: rel,
+                type: facts.type ?? "Worker",
+                visibility: "public",
+                ...(facts.status ? { status: facts.status } : {}),
+                ...(facts.description ? { description: facts.description } : {}),
+            };
+            // Presented as a core worker: it is a core template being staged.
+            offer(EXTRA_RANK, { ...toOption(entry, rel, facts), source: "core", company: null });
+        }
+    }
+    // Setup must work before an HQ has synced core workers. Never replace a
+    // workspace or explicitly staged template, and never discover other bundled ids.
+    if (!byId.has("setup")) {
+        const dir = path.join(packageRoot(), "assets", "bot-workers", "setup");
+        const yamlPath = path.join(dir, "worker.yaml");
+        if (io.existsSync(yamlPath)) {
+            const facts = readWorkerYamlFacts(yamlPath, io);
+            if (facts.id === "setup") {
+                const rel = normalizeWorkerPath(path.relative(hqRoot, dir));
+                const entry = { id: "setup", path: rel, type: facts.type ?? "Worker", visibility: "public" };
+                offer(-1, { ...toOption(entry, rel, facts), source: "core", company: null });
+            }
+        }
+    }
+    return [...byId.values()].map((e) => e.option).sort((a, b) => a.id.localeCompare(b.id));
+}
+function nearestIds(target, ids, max = 5) {
+    const t = target.toLowerCase();
+    const scored = ids.map((id) => {
+        const l = id.toLowerCase();
+        let score = 3;
+        if (l.includes(t) || t.includes(l))
+            score = 0;
+        else if (l.startsWith(t.slice(0, 3)))
+            score = 1;
+        else if (t.split(/[-_]/).some((part) => part.length > 2 && l.includes(part)))
+            score = 2;
+        return { id, score };
+    });
+    return scored
+        .sort((a, b) => a.score - b.score || a.id.localeCompare(b.id))
+        .filter((s) => s.score < 3)
+        .slice(0, max)
+        .map((s) => s.id);
+}
+export function resolveBotWorker(hqRoot, workerId, io = fs, registry, env = process.env) {
+    const id = (workerId ?? "").trim();
+    const options = listBotWorkerOptions(hqRoot, io, registry, env);
+    const hit = options.find((o) => o.id === id);
+    if (hit)
+        return hit;
+    const near = nearestIds(id, options.map((o) => o.id));
+    const hint = near.length > 0
+        ? ` Did you mean: ${near.join(", ")}?`
+        : options.length > 0
+            ? ` Run \`hq bot workers\` to see the ${options.length} available.`
+            : " No workers are available in this HQ.";
+    throw Object.assign(new Error(`No worker "${id}" in this HQ.${hint}`), { expected: true });
+}
+//# sourceMappingURL=worker-source.js.map

package/dist/lib/workers-registry/read.d.ts

@@ -0,0 +1,15 @@
+export interface RegistryWorker {
+    id: string;
+    path: string;
+    type: string;
+    visibility: string;
+    company?: string;
+    team?: string;
+    status?: string;
+    description?: string;
+    triggers?: string;
+    grants?: string;
+}
+/** Read + parse the worker registry. Empty array if it does not exist. */
+export declare function readWorkerRegistry(hqRoot: string): RegistryWorker[];
+//# sourceMappingURL=read.d.ts.map

package/dist/lib/workers-registry/read.js

@@ -0,0 +1,17 @@
+/**
+ * Reader for the auto-generated core/workers/registry.yaml (see ./index.ts
+ * for the generator). Lives in lib so bot code can use it without importing
+ * a command module.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseUserYaml } from "../../utils/user-yaml-error.js";
+/** Read + parse the worker registry. Empty array if it does not exist. */
+export function readWorkerRegistry(hqRoot) {
+    const p = path.join(hqRoot, "core/workers/registry.yaml");
+    if (!fs.existsSync(p))
+        return [];
+    const doc = parseUserYaml(fs.readFileSync(p, "utf8"), p);
+    return doc?.workers ?? [];
+}
+//# sourceMappingURL=read.js.map

package/dist/register-all.js

@@ -82,6 +82,7 @@ import { registerSearchCommand } from "./commands/search.js";
 import { registerIndexCommand } from "./commands/index-cmd.js";
 import { registerDoctorCommand } from "./commands/doctor.js";
 import { registerMeshCommand } from "./commands/mesh.js";
+import { registerBotCommand } from "./commands/bot.js";
 /** Register the complete hq command graph onto `program`. */
 export function registerAllCommands(program) {
     // Module management subcommand group
@@ -232,5 +233,6 @@ export function registerAllCommands(program) {
     // Work mesh (subcommand group — `hq mesh …`). Native REST + cache. Distinct
     // from `hq doctor` (hook guardrails). Does not start MQTT listen.
     registerMeshCommand(program);
+    registerBotCommand(program);
 }
 //# sourceMappingURL=register-all.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.109.16",
+  "version": "5.111.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -11,6 +11,7 @@
     "dist",
     "!dist/**/*.map",
     "assets/scaffold",
+    "assets/bot-workers",
     "assets/mesh-daemon",
     "CHANGELOG.md"
   ],