@indigoai-us/hq-cli 5.345.104 → 5.345.106

package/dist/lib/packages/setup-block.js

@@ -0,0 +1,236 @@
+/**
+ * The `setup:` block of a content pack's package.yaml (sample-pack-in-app-setup
+ * US-001, build contract section 1).
+ *
+ * A pack that declares one can be set up from the HQ app chat: the pack's own
+ * bot (`setup.bot.name`, also a worker under `contributes.workers`) asks the
+ * questions in order with tap-to-answer suggestions, then runs `setup.run`
+ * with the answers. `hq packages install` validates the block and fails naming
+ * the field; a pack without the block is untouched.
+ *
+ * Validation (contract):
+ * - `setup.bot.name` matches ^[a-z0-9-]{2,32}$ and appears in contributes.workers
+ * - question ids unique, ^[a-z_]+$; options is a list of strings (may be empty)
+ * - `run.script` exists in the pack; every `run.args` key is a question id;
+ *   every `then` entry's first token exists in the pack
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const SETUP_BOT_NAME_RE = /^[a-z0-9-]{2,32}$/;
+export const SETUP_QUESTION_ID_RE = /^[a-z_]+$/;
+/** A validation failure; `field` is the dotted path of the offending field. */
+export class PackSetupError extends Error {
+    field;
+    constructor(field, detail) {
+        super(`${field} ${detail}`);
+        this.field = field;
+        this.name = "PackSetupError";
+    }
+}
+function isMapping(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new PackSetupError(field, "must be a non-empty string");
+    }
+    return value;
+}
+function optionalBoolean(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new PackSetupError(field, "must be true or false");
+    return value;
+}
+/** A relative pack path that stays inside the pack root; null when it escapes. */
+function insidePack(packDir, rel) {
+    if (path.isAbsolute(rel))
+        return null;
+    const root = path.resolve(packDir);
+    const abs = path.resolve(root, rel);
+    if (abs !== root && !abs.startsWith(`${root}${path.sep}`))
+        return null;
+    return abs;
+}
+function requirePackFile(ctx, rel, field) {
+    const exists = ctx.existsSync ?? fs.existsSync;
+    const abs = insidePack(ctx.packDir, rel);
+    if (!abs)
+        throw new PackSetupError(field, `"${rel}" must be a relative path inside the pack`);
+    if (!exists(abs))
+        throw new PackSetupError(field, `"${rel}" does not exist in the pack`);
+}
+function parseQuestion(raw, index) {
+    const field = `setup.questions[${index}]`;
+    if (!isMapping(raw))
+        throw new PackSetupError(field, "must be a mapping with id and text");
+    const id = requireString(raw.id, `${field}.id`);
+    if (!SETUP_QUESTION_ID_RE.test(id)) {
+        throw new PackSetupError(`${field}.id`, `"${id}" must match ${SETUP_QUESTION_ID_RE.source}`);
+    }
+    const text = requireString(raw.text, `${field}.text`);
+    let options = [];
+    if (raw.options !== undefined) {
+        if (!Array.isArray(raw.options) || !raw.options.every((o) => typeof o === "string")) {
+            throw new PackSetupError(`${field}.options`, "must be a list of strings (it may be empty)");
+        }
+        options = raw.options;
+    }
+    const skippable = optionalBoolean(raw.skippable, `${field}.skippable`, false);
+    let defaultFrom;
+    if (raw.default_from !== undefined)
+        defaultFrom = requireString(raw.default_from, `${field}.default_from`);
+    let goal;
+    if (raw.goal !== undefined)
+        goal = requireString(raw.goal, `${field}.goal`);
+    return { id, text, options, skippable, ...(defaultFrom ? { default_from: defaultFrom } : {}), ...(goal ? { goal } : {}) };
+}
+/**
+ * Validate a raw `setup:` value. Returns the typed block, or undefined when the
+ * manifest has no block (a legacy pack). Throws PackSetupError naming the field.
+ */
+export function parseSetupBlock(raw, ctx) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isMapping(raw))
+        throw new PackSetupError("setup", "must be a mapping (bot, questions, run, done)");
+    // bot
+    if (!isMapping(raw.bot))
+        throw new PackSetupError("setup.bot", "must be a mapping with name, display_name, intro");
+    const botName = requireString(raw.bot.name, "setup.bot.name");
+    if (!SETUP_BOT_NAME_RE.test(botName)) {
+        throw new PackSetupError("setup.bot.name", `"${botName}" must match ${SETUP_BOT_NAME_RE.source}`);
+    }
+    if (!ctx.workers.includes(botName)) {
+        throw new PackSetupError("setup.bot.name", `"${botName}" is not listed under contributes.workers` +
+            (ctx.workers.length ? ` (declared: ${ctx.workers.join(", ")})` : " (none declared)"));
+    }
+    const displayName = requireString(raw.bot.display_name, "setup.bot.display_name");
+    const intro = requireString(raw.bot.intro, "setup.bot.intro");
+    const takeoverSetup = optionalBoolean(raw.takeover_setup, "setup.takeover_setup", false);
+    // questions
+    if (!Array.isArray(raw.questions) || raw.questions.length === 0) {
+        throw new PackSetupError("setup.questions", "must be a non-empty list");
+    }
+    const questions = raw.questions.map(parseQuestion);
+    const ids = new Set();
+    questions.forEach((q, i) => {
+        if (ids.has(q.id))
+            throw new PackSetupError(`setup.questions[${i}].id`, `"${q.id}" is used more than once`);
+        ids.add(q.id);
+    });
+    // run
+    if (!isMapping(raw.run))
+        throw new PackSetupError("setup.run", "must be a mapping with script (and optional args, then)");
+    const script = requireString(raw.run.script, "setup.run.script");
+    requirePackFile(ctx, script, "setup.run.script");
+    const args = {};
+    if (raw.run.args !== undefined) {
+        if (!isMapping(raw.run.args))
+            throw new PackSetupError("setup.run.args", "must be a mapping of question id to flag");
+        for (const [key, flag] of Object.entries(raw.run.args)) {
+            if (!ids.has(key)) {
+                throw new PackSetupError(`setup.run.args.${key}`, `is not a question id (questions: ${[...ids].join(", ")})`);
+            }
+            args[key] = requireString(flag, `setup.run.args.${key}`);
+        }
+    }
+    const then = [];
+    if (raw.run.then !== undefined) {
+        if (!Array.isArray(raw.run.then))
+            throw new PackSetupError("setup.run.then", "must be a list of commands");
+        raw.run.then.forEach((entry, i) => {
+            const field = `setup.run.then[${i}]`;
+            const command = requireString(entry, field);
+            const first = command.trim().split(/\s+/)[0];
+            requirePackFile(ctx, first, field);
+            then.push(command.trim());
+        });
+    }
+    // done
+    if (!isMapping(raw.done))
+        throw new PackSetupError("setup.done", "must be a mapping with message (and optional suggestion)");
+    const message = requireString(raw.done.message, "setup.done.message");
+    let suggestion;
+    if (raw.done.suggestion !== undefined)
+        suggestion = requireString(raw.done.suggestion, "setup.done.suggestion");
+    // documents
+    let documents;
+    if (raw.documents !== undefined) {
+        if (!Array.isArray(raw.documents) || raw.documents.length === 0 || !raw.documents.every((d) => typeof d === "string" && d.trim())) {
+            throw new PackSetupError("setup.documents", "must be a non-empty list of document descriptions");
+        }
+        documents = raw.documents.map((d) => d.trim());
+    }
+    // sources
+    let sources;
+    if (raw.sources !== undefined) {
+        if (!Array.isArray(raw.sources) || raw.sources.length === 0) {
+            throw new PackSetupError("setup.sources", "must be a non-empty list of { kind, read, informs, options }");
+        }
+        sources = raw.sources.map((entry, i) => {
+            const field = `setup.sources[${i}]`;
+            if (!isMapping(entry))
+                throw new PackSetupError(field, "must be a mapping with kind, read, informs and options");
+            const kind = requireString(entry.kind, `${field}.kind`);
+            const read = requireString(entry.read, `${field}.read`);
+            if (!Array.isArray(entry.informs) || entry.informs.length === 0 || !entry.informs.every((x) => typeof x === "string")) {
+                throw new PackSetupError(`${field}.informs`, "must be a non-empty list of question ids");
+            }
+            for (const id of entry.informs) {
+                if (!ids.has(id))
+                    throw new PackSetupError(`${field}.informs`, `"${id}" is not a question id (questions: ${[...ids].join(", ")})`);
+            }
+            if (!Array.isArray(entry.options) || entry.options.length === 0) {
+                throw new PackSetupError(`${field}.options`, "must be a non-empty list of { name, domain }");
+            }
+            const options = entry.options.map((o, j) => {
+                const of = `${field}.options[${j}]`;
+                if (!isMapping(o))
+                    throw new PackSetupError(of, "must be a mapping with name and a domain or a tool");
+                const name = requireString(o.name, `${of}.name`);
+                const available = optionalBoolean(o.available, `${of}.available`, true);
+                const opt = { name, ...(available ? {} : { available: false }) };
+                for (const key of ["domain", "tool", "connect", "status", "usage", "note"]) {
+                    if (o[key] !== undefined)
+                        opt[key] = requireString(o[key], `${of}.${key}`);
+                }
+                if (opt.tool)
+                    requirePackFile(ctx, opt.tool, `${of}.tool`);
+                if (available && !opt.domain && !opt.tool)
+                    throw new PackSetupError(of, "needs a domain (HQ integrations) or a tool (pack script), or available: false");
+                return opt;
+            });
+            return { kind, read, informs: [...entry.informs], options };
+        });
+    }
+    return {
+        bot: { name: botName, display_name: displayName, intro },
+        takeover_setup: takeoverSetup,
+        questions,
+        run: { script, args, then },
+        done: { message, ...(suggestion ? { suggestion } : {}) },
+        ...(documents ? { documents } : {}),
+        ...(sources ? { sources } : {}),
+    };
+}
+/**
+ * The validated setup block of an installed pack, or undefined when the pack
+ * has none or the block is invalid (`hq packages list` prints `setup: no`).
+ */
+export function readInstalledPackSetup(manifest, packDir, existsSync) {
+    if (!manifest || manifest.setup === undefined)
+        return undefined;
+    try {
+        return parseSetupBlock(manifest.setup, {
+            packDir,
+            workers: manifest.contributes?.workers ?? [],
+            ...(existsSync ? { existsSync } : {}),
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=setup-block.js.map

package/dist/lib/packages/setup-prompt.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The auto-generated "Pack setup" section of a pack bot's system prompt
+ * (build contract section 3). Rendered from the pack's validated `setup:`
+ * block: the questions in order with their options, the one-at-a-time rule
+ * with the `hq-block` suggestions envelope (contract section 2), the exact
+ * command to run with the collected answers, and the done message.
+ */
+import type { PackSetup, PackSetupQuestion } from "../../types.js";
+export declare const SKIP_SUGGESTION = "Skip";
+export declare const HQ_BLOCK_FENCE = "hq-block";
+export interface PackSetupPromptInput {
+    /** Manifest name, e.g. hq-pack-sample. */
+    packName: string;
+    /** Absolute installed pack root (core/packages/<pack>). */
+    packRoot: string;
+    setup: PackSetup;
+}
+/** The fenced JSON envelope the app draws as buttons (contract section 2). */
+export declare function suggestionsEnvelope(items: readonly string[]): string;
+/** The buttons for one question: its options, plus Skip when it is skippable. */
+export declare function questionSuggestions(q: PackSetupQuestion): string[];
+/** `bash <packRoot>/<script> --firm <company slug> --flag '<answer>' ...` */
+export declare function renderRunCommand(input: PackSetupPromptInput): string;
+/** The `then` commands, each run from the pack root with the same --firm. */
+export declare function renderThenCommands(input: PackSetupPromptInput): string[];
+/**
+ * "Their tools": what the bot needs to know to learn from the person's tools
+ * before asking. Facts (how each tool connects and is read) and principles;
+ * the bot decides how to run the conversation.
+ */
+export declare function renderLearnFirst(setup: PackSetup, packRoot: string): string;
+/** The whole "## Pack setup" section: a brief, not a script. */
+export declare function renderPackSetupSection(input: PackSetupPromptInput): string;
+//# sourceMappingURL=setup-prompt.d.ts.map

package/dist/lib/packages/setup-prompt.js

@@ -0,0 +1,128 @@
+/**
+ * The auto-generated "Pack setup" section of a pack bot's system prompt
+ * (build contract section 3). Rendered from the pack's validated `setup:`
+ * block: the questions in order with their options, the one-at-a-time rule
+ * with the `hq-block` suggestions envelope (contract section 2), the exact
+ * command to run with the collected answers, and the done message.
+ */
+import * as path from "node:path";
+export const SKIP_SUGGESTION = "Skip";
+export const HQ_BLOCK_FENCE = "hq-block";
+/** The fenced JSON envelope the app draws as buttons (contract section 2). */
+export function suggestionsEnvelope(items) {
+    const json = JSON.stringify({ v: 1, blocks: [{ kind: "suggestions", items }] });
+    return `\`\`\`${HQ_BLOCK_FENCE}\n${json}\n\`\`\``;
+}
+/** The buttons for one question: its options, plus Skip when it is skippable. */
+export function questionSuggestions(q) {
+    const items = [...q.options];
+    if (q.skippable && !items.includes(SKIP_SUGGESTION))
+        items.push(SKIP_SUGGESTION);
+    return items;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** `bash <packRoot>/<script> --firm <company slug> --flag '<answer>' ...` */
+export function renderRunCommand(input) {
+    const { setup, packRoot } = input;
+    const flags = setup.questions
+        .filter((q) => setup.run.args[q.id] !== undefined)
+        .map((q) => `${setup.run.args[q.id]} ${shellQuote(`<${q.id}>`)}`);
+    return ["bash", path.join(packRoot, setup.run.script), "--firm", "<company slug>", ...flags].join(" ");
+}
+/** The `then` commands, each run from the pack root with the same --firm. */
+export function renderThenCommands(input) {
+    return input.setup.run.then.map((entry) => {
+        const [first, ...rest] = entry.trim().split(/\s+/);
+        return ["bash", path.join(input.packRoot, first), "--firm", "<company slug>", ...rest].join(" ");
+    });
+}
+/** How to run a pack tool script: node for .mjs/.js, bash otherwise. */
+function toolCommand(packRoot, tool, args) {
+    const runner = /\.(m?js|cjs)$/.test(tool) ? "node" : "bash";
+    return `${runner} ${path.join(packRoot, tool)} ${args}`.trim();
+}
+/** One tool option, rendered with exactly how it connects and how it is read. */
+function renderSourceOption(packRoot, o) {
+    if (o.available === false)
+        return `  - ${o.name}: no direct connection yet${o.note ? ` (${o.note})` : ""}. Offer a workaround if one helps; otherwise say so once, plainly, and move on.`;
+    if (o.tool) {
+        return (`  - ${o.name}: connect with \`${toolCommand(packRoot, o.tool, o.connect ?? "connect")}\`, check with \`${toolCommand(packRoot, o.tool, o.status ?? "status")}\`` +
+            (o.usage ? `, read with \`${toolCommand(packRoot, o.tool, o.usage)}\`` : "") +
+            ` (read-only).`);
+    }
+    return (`  - ${o.name}: connect with \`hq integrations connect ${o.domain} --company <company slug> --link-only\`, read with \`hq integrations tools\` / \`hq integrations call\` (read-only tools only)` +
+        (o.note ? `; ${o.note}` : "") +
+        `.`);
+}
+/**
+ * "Their tools": what the bot needs to know to learn from the person's tools
+ * before asking. Facts (how each tool connects and is read) and principles;
+ * the bot decides how to run the conversation.
+ */
+export function renderLearnFirst(setup, packRoot) {
+    const sources = setup.sources ?? [];
+    const lines = [
+        `### Their tools`,
+        ``,
+        `Start here, before asking about the topics below: most of them should come from their tools, not from questions. \`hq integrations list --usable --json --company <company slug>\` shows what this company already has connected. ` +
+            `Find out which tools they use in whatever way fits the conversation, connect the ones that help, and read them (with a yes first) to fill in as much of the setup as you can; then ask only what is still missing. ` +
+            `Talk about tools by what they are for until the person has named one.`,
+    ];
+    if (sources.length) {
+        lines.push(``, `What each kind of tool is good for, and the routes known to work for common tools. These are examples, not a limit: any tool they use is worth trying. Never tell the person a tool cannot be connected before you have tried the routes below:`, ...sources.flatMap((s) => [`- ${s.kind} (to read ${s.read}; helps with ${s.informs.join(", ")}):`, ...s.options.map((o) => renderSourceOption(path.resolve(packRoot), o))]), ``, `Any other tool: work out how to connect it yourself, trying these in order and stopping at the first that works. ` +
+            `(1) HQ's catalog: \`hq integrations catalog <name> --company <company slug>\`, then \`hq integrations connect <domain> --company <company slug> --link-only\` for a sign-in link. ` +
+            `(2) An access key: if the sign-in needs a key, or the tool only offers API keys or tokens, look up where the tool issues one, tell them the exact steps, and send \`hq secrets --company <company slug> generate-link <TOOL>_API_KEY --expires 1h\` so they paste it into HQ, never into the chat. Then connect with \`hq secrets --company <company slug> get --reveal <TOOL>_API_KEY | hq integrations connect <domain> --company <company slug> --token-stdin\`, or call the tool's own read API with the key through \`hq secrets exec --company <company slug> --only <TOOL>_API_KEY -- <command>\`, never printing it. ` +
+            `(3) A docs page or MCP server: \`hq integrations discover <docs url>\`, or \`hq integrations connect --mcp-url <url> --company <company slug> --link-only\`. ` +
+            `(4) A workaround: an export (CSV, PDF) or a few shared files dropped into the chat, a public page you can read, or the same data in a tool they already connected. ` +
+            `If none works, say so once and move on; the setup does not depend on any one tool.`, ``, `Mechanics: a connect command prints JSON. A \`url\` (or \`authorizationUrl\`) is a link to send them; \`started: true\` means a sign-in page already opened in their browser. ` +
+            `Never run \`hq integrations connect\` without \`--link-only\`: it waits for a sign-in the person has not been sent. ` +
+            `After they say they are done, confirm with the tool's check command (or \`hq integrations list\`).`);
+    }
+    lines.push(``, `Reading: ask before you read, read only what you said you would, and use read-only commands; never send, post or change anything. ` +
+        `Propose what you found with where it came from and let them correct it, rather than asking questions the data already answers. ` +
+        `Describe what you found in your own words; never paste private messages back.`);
+    return lines.join("\n");
+}
+function renderQuestion(q) {
+    const lines = [`- \`${q.id}\`: ${q.goal ?? q.text}`];
+    if (q.goal)
+        lines.push(`  The pack phrases it: "${q.text}"`);
+    if (q.options.length)
+        lines.push(`  Typical answers (to help you understand, not to show as buttons): ${q.options.join(", ")}`);
+    if (q.default_from)
+        lines.push(`  Start from the value of \`${q.default_from}\` and let them confirm or change it.`);
+    lines.push(q.skippable ? `  Optional: if they would rather not say, pass \`skipped\`.` : `  Required.`);
+    return lines.join("\n");
+}
+/** The whole "## Pack setup" section: a brief, not a script. */
+export function renderPackSetupSection(input) {
+    const { setup, packName, packRoot } = input;
+    const parts = [];
+    parts.push(`## Pack setup (${packName})\n\n` +
+        `You are the setup bot of the \`${packName}\` pack, installed at \`${packRoot}\`. Set the pack up for this person from this chat. ` +
+        `This section is a brief, not a script: it says what you need to learn, what you can use, and what done looks like. How you run the conversation is your call. Adapt to the person: follow their lead, skip what you already know, ask follow-ups when an answer is vague, and keep messages short. ` +
+        `You run every command yourself; never ask the person to open a terminal or Claude Code. ` +
+        `Everything you write in a turn is posted to the person, including text between commands, so never narrate your steps or write notes to yourself. ` +
+        `Keep your progress in \`pack-setup-${packName}.md\` in your memory folder so a later turn carries on instead of starting over.`);
+    parts.push(renderLearnFirst(setup, packRoot));
+    parts.push(`### What you need to learn\n\n${setup.questions.map(renderQuestion).join("\n")}`);
+    if (setup.documents?.length) {
+        parts.push(`### Documents\n\nThese are worth asking for if their tools do not have them: ${setup.documents.join(", ")}. They can drop files into the chat; read what arrives and use it.`);
+    }
+    parts.push(`### Buttons\n\n` +
+        `You can offer tap-to-answer buttons by ending a message with an \`${HQ_BLOCK_FENCE}\` fenced JSON envelope, for example ${suggestionsEnvelope(["Done", "Skip"])} The app draws each item as a button and sends its text back as the person's reply. ` +
+        `Use them only when there is a real, short set of choices: at most four, all of the same kind (never mix answers with actions like connecting a tool). Leave them off questions answered by typing, and never put a guessed or example answer in one. Typed replies always work too.`);
+    const thenCommands = renderThenCommands(input);
+    parts.push(`### Setting it up\n\n` +
+        `When you know enough, run this from the HQ folder, filling each \`<question id>\` with what you learned (\`skipped\` when they skipped) and \`<company slug>\` with their company's folder under \`companies/\`:\n\n` +
+        `\`\`\`bash\n${renderRunCommand(input)}\n\`\`\`` +
+        (thenCommands.length ? `\n\nThen, with the same \`--firm\`:\n\n\`\`\`bash\n${thenCommands.join("\n")}\n\`\`\`` : "") +
+        `\n\nIf a command fails, say plainly what did not work and offer to try again; never paste a stack trace.`);
+    parts.push(`### When it is done\n\n` +
+        `Tell them what you set up: what you created and where to find it in Files, what you connected, and anything left undone. The pack's own summary of the moment is: "${setup.done.message}"` +
+        (setup.done.suggestion ? ` A natural next step to offer: "${setup.done.suggestion}".` : ""));
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=setup-prompt.js.map

package/dist/lib/packages/setup-takeover.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Takeover of HQ's generic setup by a pack bot (build contract section 3).
+ *
+ * When a pack's `setup.takeover_setup` is true and HQ's setup bot has not
+ * recorded that setup is finished, the pack bot's system prompt also carries
+ * the setup worker's skills and a note to finish HQ setup first, then run the
+ * pack setup. "Finished" follows the setup worker's own rule: its progress
+ * note (`setup-progress.md` in the setup bot's memory folder) says
+ * `Status: finished`. No note, or any other status, means not finished.
+ *
+ * Where the note lives: the setup bot's config at `~/.hq/bots/setup/bot.json`
+ * names its memory folder (`personal/workers/setup/memory` under the HQ root
+ * for synced memory, or `~/.hq/bots/setup/memory` for local memory).
+ */
+import type { WorkerSkillSource } from "../bot/prompt.js";
+export declare const HQ_SETUP_BOT_NAME = "setup";
+export declare const SETUP_PROGRESS_NOTE = "setup-progress.md";
+/** Same rule as the setup worker: the note says `Status: finished`. */
+export declare function progressNoteSaysFinished(note: string | null | undefined): boolean;
+/**
+ * The HQ setup bot's progress note on this computer, or null when the setup
+ * bot was never created here or has not written one.
+ */
+export declare function readHqSetupProgressNote(opts?: {
+    botsRoot?: string;
+    hqRootFallback?: string;
+}): {
+    path: string | null;
+    note: string | null;
+};
+/**
+ * Whether the pack bot takes over HQ setup: the pack asked for it and the
+ * progress note does not say setup is finished.
+ */
+export declare function decideTakeover(input: {
+    takeoverSetup: boolean;
+    progressNote: string | null | undefined;
+}): boolean;
+export interface TakeoverPromptInput {
+    packName: string;
+    /** hqRoot-relative folder of HQ's setup worker. */
+    setupWorkerDir: string;
+    /** The setup worker's skills (name, description, hqRoot-relative file). */
+    skills: readonly WorkerSkillSource[];
+    /** Where HQ's setup bot keeps (or would keep) its progress note; null when unknown. */
+    progressNotePath: string | null;
+}
+/** The "## Finish HQ setup first" section, placed before the pack setup section. */
+export declare function renderTakeoverSection(input: TakeoverPromptInput): string;
+//# sourceMappingURL=setup-takeover.d.ts.map

package/dist/lib/packages/setup-takeover.js

@@ -0,0 +1,75 @@
+/**
+ * Takeover of HQ's generic setup by a pack bot (build contract section 3).
+ *
+ * When a pack's `setup.takeover_setup` is true and HQ's setup bot has not
+ * recorded that setup is finished, the pack bot's system prompt also carries
+ * the setup worker's skills and a note to finish HQ setup first, then run the
+ * pack setup. "Finished" follows the setup worker's own rule: its progress
+ * note (`setup-progress.md` in the setup bot's memory folder) says
+ * `Status: finished`. No note, or any other status, means not finished.
+ *
+ * Where the note lives: the setup bot's config at `~/.hq/bots/setup/bot.json`
+ * names its memory folder (`personal/workers/setup/memory` under the HQ root
+ * for synced memory, or `~/.hq/bots/setup/memory` for local memory).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { readBotConfig, resolveBotMemoryDir } from "../bot/config.js";
+import { botDir } from "../bot/paths.js";
+export const HQ_SETUP_BOT_NAME = "setup";
+export const SETUP_PROGRESS_NOTE = "setup-progress.md";
+/** Same rule as the setup worker: the note says `Status: finished`. */
+export function progressNoteSaysFinished(note) {
+    if (typeof note !== "string")
+        return false;
+    return /^Status:[ \t]*finished/im.test(note);
+}
+/**
+ * The HQ setup bot's progress note on this computer, or null when the setup
+ * bot was never created here or has not written one.
+ */
+export function readHqSetupProgressNote(opts = {}) {
+    const config = readBotConfig(botDir(HQ_SETUP_BOT_NAME, opts.botsRoot));
+    if (!config)
+        return { path: null, note: null };
+    const notePath = path.join(resolveBotMemoryDir(config), SETUP_PROGRESS_NOTE);
+    return { path: notePath, note: readNote(notePath) };
+}
+function readNote(p) {
+    try {
+        return fs.readFileSync(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether the pack bot takes over HQ setup: the pack asked for it and the
+ * progress note does not say setup is finished.
+ */
+export function decideTakeover(input) {
+    if (!input.takeoverSetup)
+        return false;
+    return !progressNoteSaysFinished(input.progressNote);
+}
+/** The "## Finish HQ setup first" section, placed before the pack setup section. */
+export function renderTakeoverSection(input) {
+    const skillLines = input.skills.map((s) => {
+        const desc = s.description ? ` — ${s.description}` : "";
+        const file = s.file ? ` — ${s.file}` : " — (no skill file on disk)";
+        return `- ${s.name}${desc}${file}`;
+    });
+    return (`## Finish HQ setup first\n\n` +
+        `HQ's own setup bot has not recorded that this HQ is set up` +
+        (input.progressNotePath ? ` (its progress note at \`${input.progressNotePath}\` does not say \`Status: finished\`)` : " (it has no progress note on this computer)") +
+        `. Before the \`${input.packName}\` pack setup, finish the generic HQ setup yourself, using HQ's setup worker skills below: ` +
+        `read \`${path.join(input.setupWorkerDir, "worker.yaml")}\` for the walkthrough and its progress-note rules, do only the steps that are not done, and ` +
+        (input.progressNotePath
+            ? `keep HQ's setup progress note at \`${input.progressNotePath}\` up to date as you go (not a copy in your own memory folder), ending with \`Status: finished\`, so HQ's setup bot and later packs see that setup is done. `
+            : `write the same \`setup-progress.md\` note in your memory folder as you go, ending with \`Status: finished\`. `) +
+        `Skip any step the HQ plainly shows is done (signed in, a company they belong to). Then carry on with the Pack setup section. ` +
+        `Tell the person in one line that you are finishing HQ setup first, and ask one question at a time, as the Pack setup section says.\n\n` +
+        `### HQ setup worker skills (${path.join(input.setupWorkerDir, "skills")}/)\n\n` +
+        (skillLines.length ? skillLines.join("\n") : "- (none found on disk)"));
+}
+//# sourceMappingURL=setup-takeover.js.map

package/dist/lib/packages/start-bot.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `hq packages install <source> --start-bot` (sample-pack-in-app-setup US-003,
+ * build contract section 3).
+ *
+ * After a pack with a valid `setup:` block is wired, create the personal bot
+ * `setup.bot.name` running the pack worker of the same id, with the display
+ * name and intro from the block, through the same code path as
+ * `hq bot create` (never a child `hq` process), and start it the way
+ * `hq bot create` does (launchd when installed). A bot of that name that
+ * already exists is restarted and re-sends its intro. If the bot cannot start,
+ * the install still succeeds: the reason is printed and the owner gets one
+ * plain DM with one next step. On success the install prints `bot: <name>`,
+ * which the desktop app reads to open the right DM.
+ */
+import type { PackSetup } from "../../types.js";
+export interface StartPackBotDeps {
+    /** A bot of this name exists on this computer. */
+    botExists: (name: string) => boolean;
+    /** `hq bot create <name> --worker <id> --display-name ... --intro ... --kickoff ...` */
+    createBot: (name: string, opts: {
+        worker: string;
+        displayName: string;
+        intro: string;
+        kickoff: string;
+    }) => Promise<void>;
+    /** `hq bot restart <name>` */
+    restartBot: (name: string) => Promise<void>;
+    /** `hq bot intro <name>` (re-send the hello) */
+    sendIntro: (name: string) => Promise<void>;
+    /** One DM to the owner, best effort; failures are reported, never thrown. */
+    dmOwner: (name: string, body: string) => Promise<void>;
+    /** Human output (stdout). */
+    say: (line: string) => void;
+}
+export interface StartPackBotResult {
+    ok: boolean;
+    bot: string;
+    /** "created" | "restarted" */
+    action: "created" | "restarted";
+    reason?: string;
+}
+/** The kickoff turn that makes the bot begin the pack setup as soon as it is online. */
+export declare function packSetupKickoff(packName: string, setup: PackSetup): string;
+/** One plain sentence plus one next step, for the owner's DM when the start failed. */
+export declare function startFailureDm(setup: PackSetup, reason: string): string;
+export declare function startPackSetupBot(packName: string, setup: PackSetup, deps: StartPackBotDeps): Promise<StartPackBotResult>;
+//# sourceMappingURL=start-bot.d.ts.map

package/dist/lib/packages/start-bot.js

@@ -0,0 +1,66 @@
+/**
+ * `hq packages install <source> --start-bot` (sample-pack-in-app-setup US-003,
+ * build contract section 3).
+ *
+ * After a pack with a valid `setup:` block is wired, create the personal bot
+ * `setup.bot.name` running the pack worker of the same id, with the display
+ * name and intro from the block, through the same code path as
+ * `hq bot create` (never a child `hq` process), and start it the way
+ * `hq bot create` does (launchd when installed). A bot of that name that
+ * already exists is restarted and re-sends its intro. If the bot cannot start,
+ * the install still succeeds: the reason is printed and the owner gets one
+ * plain DM with one next step. On success the install prints `bot: <name>`,
+ * which the desktop app reads to open the right DM.
+ */
+/** The kickoff turn that makes the bot begin the pack setup as soon as it is online. */
+export function packSetupKickoff(packName, setup) {
+    return (`Kickoff: I just added the ${packName} pack and you are its setup bot. Begin now. ` +
+        `Follow the Pack setup section of your instructions: if a "Finish HQ setup first" section is present, start there; ` +
+        `otherwise ask the first setup question (\`${setup.questions[0].id}\`) with its suggestions. One question per message.`);
+}
+/** One plain sentence plus one next step, for the owner's DM when the start failed. */
+export function startFailureDm(setup, reason) {
+    const next = `hq bot start ${setup.bot.name}`;
+    return `${setup.bot.display_name} could not start (${plain(reason)}). Next step: open Terminal and run \`${next}\`, or ask your setup bot to start it.`;
+}
+function plain(reason) {
+    return reason.replace(/\s+/g, " ").trim().replace(/[.:]+$/, "");
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export async function startPackSetupBot(packName, setup, deps) {
+    const name = setup.bot.name;
+    const exists = deps.botExists(name);
+    const action = exists ? "restarted" : "created";
+    try {
+        if (exists) {
+            deps.say(`bot ${name} already exists; restarting it and sending its intro again`);
+            await deps.restartBot(name);
+            await deps.sendIntro(name);
+        }
+        else {
+            await deps.createBot(name, {
+                worker: name,
+                displayName: setup.bot.display_name,
+                intro: setup.bot.intro,
+                kickoff: packSetupKickoff(packName, setup),
+            });
+        }
+        deps.say(`bot: ${name}`);
+        return { ok: true, bot: name, action };
+    }
+    catch (err) {
+        const reason = errorMessage(err);
+        deps.say(`bot ${name} could not be started: ${reason}`);
+        deps.say(`The pack is installed. Start the bot later with: hq bot start ${name}`);
+        try {
+            await deps.dmOwner(name, startFailureDm(setup, reason));
+        }
+        catch (dmErr) {
+            deps.say(`could not DM you about it: ${errorMessage(dmErr)}`);
+        }
+        return { ok: false, bot: name, action, reason };
+    }
+}
+//# sourceMappingURL=start-bot.js.map

package/dist/lib/session-company-lock.d.ts

@@ -0,0 +1,7 @@
+export type SessionCompanyLock = {
+    sessionId: string;
+    companies: string[];
+} | undefined;
+/** Read the session's validated company scope capability or legacy metadata. */
+export declare function readSessionCompanyLock(env?: NodeJS.ProcessEnv): SessionCompanyLock;
+//# sourceMappingURL=session-company-lock.d.ts.map