@indigoai-us/hq-cli 5.109.16 → 5.111.0

package/dist/lib/bot/runtime/index.js

@@ -0,0 +1,279 @@
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createClaudeRuntime } from "./claude.js";
+import { createCodexRuntime } from "./codex.js";
+import { createGrokRuntime } from "./grok.js";
+import { parseJsonLine, RuntimeError, turnTimeoutMs, stderrExcerpt, } from "./types.js";
+export * from "./types.js";
+export { createClaudeRuntime, claudePermissionMode } from "./claude.js";
+export { createCodexRuntime, codexPrompt } from "./codex.js";
+export { createGrokRuntime, grokPrompt } from "./grok.js";
+export function runtimeFor(id, env = process.env) {
+    if (id === "claude")
+        return createClaudeRuntime(env);
+    if (id === "codex")
+        return createCodexRuntime();
+    return createGrokRuntime();
+}
+/**
+ * Real child spawn, stdin closed. stdout is delivered line by line while the
+ * process runs (for streaming runtimes) and also returned whole at the end.
+ * No time limit unless `timeoutMs` is set; `signal` kills the process.
+ */
+/**
+ * Every live descendant of `pid` (children first found, deepest last). The
+ * model CLI starts its own tools and shells; stopping only the top process
+ * leaves those running and holding the output pipe open, so a stop would hang
+ * until they finish. POSIX only; empty when `ps` is unavailable.
+ */
+export function descendantPids(pid, listProcesses = defaultListProcesses) {
+    let table;
+    try {
+        table = listProcesses();
+    }
+    catch {
+        return [];
+    }
+    const children = new Map();
+    for (const row of table.split("\n")) {
+        const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(row);
+        if (!m)
+            continue;
+        const child = Number(m[1]);
+        const parent = Number(m[2]);
+        const list = children.get(parent) ?? [];
+        list.push(child);
+        children.set(parent, list);
+    }
+    const out = [];
+    const queue = [...(children.get(pid) ?? [])];
+    const seen = new Set([pid]);
+    while (queue.length > 0) {
+        const next = queue.shift();
+        if (seen.has(next))
+            continue;
+        seen.add(next);
+        out.push(next);
+        queue.push(...(children.get(next) ?? []));
+    }
+    return out;
+}
+function defaultListProcesses() {
+    return execFileSync("ps", ["-A", "-o", "pid=,ppid="], { encoding: "utf8", timeout: 5_000 });
+}
+/** After a stop, wait this long for the output pipes to close before settling anyway. */
+export const STOP_SETTLE_GRACE_MS = 2_000;
+export const defaultSpawn = (command, args, options) => new Promise((resolve, reject) => {
+    let stdout = "";
+    let stderr = "";
+    let partial = "";
+    let settled = false;
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stopping = false;
+    const signalTree = (sig, pids) => {
+        for (const p of pids) {
+            try {
+                process.kill(p, sig);
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    };
+    const kill = () => {
+        stopping = true;
+        // Snapshot the tree before the parent dies (its children get re-parented).
+        const tree = process.platform === "win32" || child.pid === undefined ? [] : descendantPids(child.pid);
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            /* ignore */
+        }
+        signalTree("SIGTERM", tree);
+        // A CLI (or a tool it started) that ignores SIGTERM still goes.
+        setTimeout(() => {
+            try {
+                if (child.exitCode === null && child.signalCode === null)
+                    child.kill("SIGKILL");
+            }
+            catch {
+                /* ignore */
+            }
+            signalTree("SIGKILL", tree);
+        }, 5_000).unref?.();
+    };
+    const timer = options.timeoutMs !== undefined
+        ? setTimeout(() => {
+            if (settled)
+                return;
+            stderr += `\n[hq bot] runtime turn exceeded ${options.timeoutMs}ms (HQ_BOT_TURN_TIMEOUT_MS) and was stopped`;
+            kill();
+        }, options.timeoutMs)
+        : null;
+    const onAbort = () => {
+        if (!settled)
+            kill();
+    };
+    if (options.signal) {
+        if (options.signal.aborted)
+            onAbort();
+        else
+            options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    const emit = (line) => {
+        if (!options.onStdoutLine || !line.trim())
+            return;
+        try {
+            options.onStdoutLine(line);
+        }
+        catch {
+            /* a listener must never break the turn */
+        }
+    };
+    const cleanup = () => {
+        if (timer)
+            clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    };
+    child.stdout?.on("data", (d) => {
+        const chunk = d.toString();
+        stdout += chunk;
+        if (!options.onStdoutLine)
+            return;
+        partial += chunk;
+        let nl = partial.indexOf("\n");
+        while (nl >= 0) {
+            emit(partial.slice(0, nl));
+            partial = partial.slice(nl + 1);
+            nl = partial.indexOf("\n");
+        }
+    });
+    child.stderr?.on("data", (d) => {
+        stderr += d.toString();
+    });
+    child.on("error", (err) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        reject(err);
+    });
+    // A stopped process can exit while something it started (and we could not
+    // reach) still holds stdout open; settle shortly after the exit instead of
+    // waiting for that pipe.
+    child.on("exit", (code, signal) => {
+        if (!stopping)
+            return;
+        setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            if (partial)
+                emit(partial);
+            resolve({ code, signal, stdout, stderr });
+        }, STOP_SETTLE_GRACE_MS).unref?.();
+    });
+    child.on("close", (code, signal) => {
+        if (settled)
+            return;
+        settled = true;
+        cleanup();
+        if (partial)
+            emit(partial);
+        resolve({ code, signal, stdout, stderr });
+    });
+});
+/**
+ * Run one turn: spawn the runtime CLI, parse the reply, clean up scratch.
+ * Throws RuntimeError (with a bounded stderr excerpt) on any failure.
+ */
+export async function runRuntimeTurn(runtime, input, deps = {}) {
+    const spawnImpl = deps.spawnImpl ?? defaultSpawn;
+    const scratchDir = deps.scratchDir ?? fs.mkdtempSync(path.join(os.tmpdir(), "hq-bot-turn-"));
+    const outputFile = path.join(scratchDir, "last-message.txt");
+    const newSessionId = input.newSessionId ?? (deps.newSessionId ?? randomUUID)();
+    const args = runtime.buildArgs(input, { outputFile, newSessionId });
+    const env = input.env ?? deps.env ?? process.env;
+    const binary = runtime.resolveBinary?.(env) ?? runtime.binary;
+    const onEvent = input.onEvent;
+    const onStdoutLine = onEvent && runtime.parseStreamLine
+        ? (line) => {
+            for (const event of runtime.parseStreamLine(line)) {
+                try {
+                    onEvent(event);
+                }
+                catch {
+                    /* a listener must never break the turn */
+                }
+            }
+        }
+        : undefined;
+    const timeoutMs = deps.timeoutMs ?? turnTimeoutMs(env);
+    let result;
+    try {
+        result = await spawnImpl(binary, args, {
+            cwd: input.cwd,
+            env,
+            ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            ...(onStdoutLine ? { onStdoutLine } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
+    catch (err) {
+        const code = err.code;
+        const msg = code === "ENOENT"
+            ? `${runtime.binary} is not installed or not on PATH`
+            : `failed to start ${runtime.binary}: ${err instanceof Error ? err.message : String(err)}`;
+        throw new RuntimeError(msg, msg, null, { started: false });
+    }
+    if (input.signal?.aborted) {
+        throw new RuntimeError(`${runtime.binary} was stopped`, "stopped by the owner", result.code, { aborted: true });
+    }
+    let outputFileText;
+    try {
+        if (fs.existsSync(outputFile))
+            outputFileText = fs.readFileSync(outputFile, "utf8");
+    }
+    catch {
+        /* ignore */
+    }
+    finally {
+        if (!deps.scratchDir) {
+            try {
+                fs.rmSync(scratchDir, { recursive: true, force: true });
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    if (result.code !== 0 || result.signal) {
+        const reason = runtime.failureReason?.(result.stdout, result.stderr);
+        // Streaming runtimes write JSON events to stdout: never show those to a
+        // person as the reason. stderr, then a plain description, instead.
+        const stdoutIsEvents = result.stdout.split("\n").some((line) => parseJsonLine(line) !== null);
+        const fallback = result.stderr.trim()
+            ? stderrExcerpt(result.stderr)
+            : result.stdout.trim() && !stdoutIsEvents
+                ? stderrExcerpt(result.stdout)
+                : result.signal
+                    ? `the ${runtime.binary} process was killed (${result.signal})`
+                    : `${runtime.binary} exited with code ${result.code}`;
+        throw new RuntimeError(`${runtime.binary} exited with ${result.code ?? `signal ${result.signal}`}${reason ? `: ${reason.slice(0, 200)}` : ""}`, reason ? reason.slice(0, 400) : fallback, result.code);
+    }
+    const parsed = runtime.parseOutput(result.stdout, { outputFile, outputFileText });
+    // A resumed session keeps its id even when the CLI omits it from the envelope.
+    return { text: parsed.text, sessionId: parsed.sessionId ?? input.sessionId };
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/bot/runtime/messages-stream.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The NDJSON stream Claude Code (`--output-format stream-json --verbose`) and
+ * Grok (`--output-format streaming-messages-json`) both write: Anthropic
+ * Messages wire shapes, one event per line.
+ *
+ *   {"type":"system","subtype":"init","session_id":…}
+ *   {"type":"assistant","message":{"content":[{"type":"text","text":…},
+ *     {"type":"tool_use","name":…},{"type":"thinking",…}]},"parent_tool_use_id":null,"session_id":…}
+ *   {"type":"user","message":{"content":[{"type":"tool_result",…}]}}
+ *   {"type":"result","subtype":"success","is_error":false,"result":"<last message>","session_id":…}
+ *
+ * Recorded from Claude Code 2.1.258 and grok (model grok-4.6) on 2026-09-12;
+ * fixtures in runtime/fixtures/. Claude sends one content block per assistant
+ * event; Grok sends a whole message (thinking + text + tool_use) per event.
+ */
+import { type RuntimeStreamEvent, type RuntimeTurnResult } from "./types.js";
+/** Progress events in one stream line: top-level assistant text and tool starts only. */
+export declare function messagesStreamEvents(line: string): RuntimeStreamEvent[];
+/**
+ * The turn's result from the whole stream. Prefers the `result` event; also
+ * accepts the older single-object `--output-format json` envelope. Throws a
+ * RuntimeError for an error result, or when there is nothing usable.
+ */
+export declare function messagesStreamResult(stdout: string, runtimeName: string): RuntimeTurnResult;
+/** The error text of an `is_error` result event, if the stream has one. */
+export declare function messagesStreamFailure(stdout: string): string | undefined;
+//# sourceMappingURL=messages-stream.d.ts.map

package/dist/lib/bot/runtime/messages-stream.js

@@ -0,0 +1,85 @@
+/**
+ * The NDJSON stream Claude Code (`--output-format stream-json --verbose`) and
+ * Grok (`--output-format streaming-messages-json`) both write: Anthropic
+ * Messages wire shapes, one event per line.
+ *
+ *   {"type":"system","subtype":"init","session_id":…}
+ *   {"type":"assistant","message":{"content":[{"type":"text","text":…},
+ *     {"type":"tool_use","name":…},{"type":"thinking",…}]},"parent_tool_use_id":null,"session_id":…}
+ *   {"type":"user","message":{"content":[{"type":"tool_result",…}]}}
+ *   {"type":"result","subtype":"success","is_error":false,"result":"<last message>","session_id":…}
+ *
+ * Recorded from Claude Code 2.1.258 and grok (model grok-4.6) on 2026-09-12;
+ * fixtures in runtime/fixtures/. Claude sends one content block per assistant
+ * event; Grok sends a whole message (thinking + text + tool_use) per event.
+ */
+import { parseJsonLine, RuntimeError } from "./types.js";
+/** Progress events in one stream line: top-level assistant text and tool starts only. */
+export function messagesStreamEvents(line) {
+    const ev = parseJsonLine(line);
+    if (!ev || ev.type !== "assistant")
+        return [];
+    // Sub-agent traffic is the sub-agent's business, not a message to the person.
+    if (ev.parent_tool_use_id !== null && ev.parent_tool_use_id !== undefined)
+        return [];
+    const message = ev.message && typeof ev.message === "object" ? ev.message : null;
+    const content = Array.isArray(message?.content) ? message.content : [];
+    const out = [];
+    for (const block of content) {
+        if (!block || typeof block !== "object")
+            continue;
+        const b = block;
+        if (b.type === "text" && typeof b.text === "string" && b.text.trim())
+            out.push({ kind: "message", text: b.text.trim() });
+        else if (b.type === "tool_use" && typeof b.name === "string")
+            out.push({ kind: "tool", name: b.name });
+    }
+    return out;
+}
+/**
+ * The turn's result from the whole stream. Prefers the `result` event; also
+ * accepts the older single-object `--output-format json` envelope. Throws a
+ * RuntimeError for an error result, or when there is nothing usable.
+ */
+export function messagesStreamResult(stdout, runtimeName) {
+    let result = null;
+    let sessionId;
+    let lastText;
+    let sawJson = false;
+    for (const line of stdout.split("\n")) {
+        const ev = parseJsonLine(line);
+        if (!ev)
+            continue;
+        sawJson = true;
+        if (typeof ev.session_id === "string")
+            sessionId = ev.session_id;
+        if (ev.type === "result" || (ev.type === undefined && ("result" in ev || "is_error" in ev)))
+            result = ev;
+        else if (ev.type === "assistant") {
+            const texts = messagesStreamEvents(line).flatMap((e) => (e.kind === "message" ? [e.text] : []));
+            if (texts.length > 0)
+                lastText = texts.join("\n\n");
+        }
+    }
+    if (!sawJson)
+        throw new RuntimeError(`${runtimeName} returned non-JSON output`, stdout.trim().slice(-400), null);
+    if (result?.is_error === true) {
+        const detail = typeof result.result === "string" && result.result ? result.result : String(result.subtype ?? "error");
+        throw new RuntimeError(`${runtimeName} reported an error: ${detail.slice(0, 200)}`, detail.slice(0, 400), null);
+    }
+    const text = (typeof result?.result === "string" && result.result.trim() ? result.result : lastText) ?? "";
+    if (typeof result?.session_id === "string")
+        sessionId = result.session_id;
+    return { text, sessionId };
+}
+/** The error text of an `is_error` result event, if the stream has one. */
+export function messagesStreamFailure(stdout) {
+    let reason;
+    for (const line of stdout.split("\n")) {
+        const ev = parseJsonLine(line);
+        if (ev?.type === "result" && ev.is_error === true && typeof ev.result === "string" && ev.result.trim())
+            reason = ev.result.trim();
+    }
+    return reason;
+}
+//# sourceMappingURL=messages-stream.js.map

package/dist/lib/bot/runtime/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Model-CLI runtime adapters (local-bots US-003).
+ *
+ * One headless invocation per inbound DM, resumed by the CLI's own session id
+ * so context carries across turns and across restarts. The CLI runs under the
+ * OWNER's login (claude / codex / grok) — no Indigo-billed model keys.
+ */
+export interface RuntimeTurnInput {
+    /** The owner's DM text (the user turn). */
+    prompt: string;
+    /** Absolute path of the rendered system prompt file. */
+    systemPromptFile: string;
+    /** The system prompt text (for runtimes that cannot take a file). */
+    systemPrompt: string;
+    /** Working directory — the owner's HQ root, so skills and `hq` work. */
+    cwd: string;
+    /** Pre-approve every tool/command (headless bots cannot prompt). Default true. */
+    autoApprove?: boolean;
+    /** Claude only: explicit permission mode (a remembered fallback) — beats autoApprove. */
+    permissionMode?: string;
+    /** The owner's HQ root: runtimes with a write sandbox must allow it too,
+     *  or the bot cannot edit its own memory notes under personal/workers/. */
+    hqRoot?: string;
+    /** Previous session id to resume, if any. */
+    sessionId?: string;
+    /** Optional model override. */
+    model?: string;
+    /** Thinking level for the CLI (runtimes fall back to medium). */
+    effort?: string;
+    /**
+     * The session id to start a NEW session under (ignored when resuming).
+     * Set by the run loop when the bot is company-bound so the hooks' session
+     * meta file and the CLI session share one id.
+     */
+    newSessionId?: string;
+    /** Environment for the runtime process (default: process.env). */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Called for each event parsed from the runtime's stdout WHILE the turn runs
+     * (a finished assistant message, a tool call). Exceptions are swallowed.
+     */
+    onEvent?: (event: RuntimeStreamEvent) => void;
+    /** Aborting kills the runtime process (owner stop); the turn then fails with `aborted`. */
+    signal?: AbortSignal;
+}
+/**
+ * What a runtime's streaming output means to the bot, per stdout line:
+ * - `message`: one whole assistant message worth posting as progress
+ * - `tool`: the model started a tool (name only — never arguments or results)
+ * Reasoning/thinking content, token deltas, tool payloads and tool results are
+ * never surfaced.
+ */
+export type RuntimeStreamEvent = {
+    kind: "message";
+    text: string;
+} | {
+    kind: "tool";
+    name: string;
+};
+export interface RuntimeTurnResult {
+    text: string;
+    sessionId?: string;
+}
+export interface SpawnResult {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}
+export interface SpawnOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    /** Kill the process after this long. Undefined = no limit (the default). */
+    timeoutMs?: number;
+    /** Each complete stdout line as it arrives (the trailing partial line on close). */
+    onStdoutLine?: (line: string) => void;
+    /** Kill the process when aborted. */
+    signal?: AbortSignal;
+}
+export interface SpawnLike {
+    (command: string, args: string[], options: SpawnOptions): Promise<SpawnResult>;
+}
+export declare class RuntimeError extends Error {
+    readonly stderrExcerpt: string;
+    readonly exitCode: number | null;
+    /** False when the runtime process never started (missing binary, spawn error): safe to retry. */
+    readonly started: boolean;
+    /** True when the turn was ended on purpose (owner stop), not by a model failure. */
+    readonly aborted: boolean;
+    constructor(message: string, stderrExcerpt: string, exitCode: number | null, opts?: {
+        started?: boolean;
+        aborted?: boolean;
+    });
+}
+export interface BotRuntime {
+    readonly id: "claude" | "codex" | "grok";
+    /** Executable name looked up on PATH (or an absolute path). */
+    readonly binary: string;
+    /**
+     * Optional: the executable to spawn for this turn when `binary` is not on
+     * PATH (e.g. Claude Code that only exists inside the Claude desktop app).
+     * Resolved per turn so an app update that swaps the version folder is picked up.
+     */
+    resolveBinary?(env: NodeJS.ProcessEnv): string;
+    /** Build the argv for one turn. Pure. */
+    buildArgs(input: RuntimeTurnInput, scratch: {
+        outputFile: string;
+        newSessionId: string;
+    }): string[];
+    /** Parse the CLI's stdout (and optional output file) into the reply. Pure. */
+    parseOutput(stdout: string, extra: {
+        outputFile?: string;
+        outputFileText?: string;
+    }): RuntimeTurnResult;
+    /** Optional: events in ONE stdout line of the streaming output format. Pure. */
+    parseStreamLine?(line: string): RuntimeStreamEvent[];
+    /**
+     * Optional: the human-readable reason for a failed turn (non-zero exit),
+     * mined from stdout/stderr — e.g. the API's "usage limit" or "model
+     * requires a newer CLI" message — so the owner sees the real cause instead
+     * of the CLI's last stderr chatter. Return undefined when nothing better
+     * than the stderr excerpt is known. Pure.
+     */
+    failureReason?(stdout: string, stderr: string): string | undefined;
+}
+/**
+ * Turns have no time limit: a turn runs until the model process exits (the
+ * owner can still stop the bot). `HQ_BOT_TURN_TIMEOUT_MS` is an escape hatch;
+ * unset, empty, zero or invalid means unlimited.
+ */
+export declare const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+export declare function turnTimeoutMs(env?: NodeJS.ProcessEnv): number | undefined;
+/** Parse one NDJSON line; null when it is not a JSON object. */
+export declare function parseJsonLine(line: string): Record<string, unknown> | null;
+export declare function stderrExcerpt(stderr: string, max?: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/bot/runtime/types.js

@@ -0,0 +1,51 @@
+/**
+ * Model-CLI runtime adapters (local-bots US-003).
+ *
+ * One headless invocation per inbound DM, resumed by the CLI's own session id
+ * so context carries across turns and across restarts. The CLI runs under the
+ * OWNER's login (claude / codex / grok) — no Indigo-billed model keys.
+ */
+export class RuntimeError extends Error {
+    stderrExcerpt;
+    exitCode;
+    /** False when the runtime process never started (missing binary, spawn error): safe to retry. */
+    started;
+    /** True when the turn was ended on purpose (owner stop), not by a model failure. */
+    aborted;
+    constructor(message, stderrExcerpt, exitCode, opts = {}) {
+        super(message);
+        this.stderrExcerpt = stderrExcerpt;
+        this.exitCode = exitCode;
+        this.name = "RuntimeError";
+        this.started = opts.started ?? true;
+        this.aborted = opts.aborted ?? false;
+    }
+}
+/**
+ * Turns have no time limit: a turn runs until the model process exits (the
+ * owner can still stop the bot). `HQ_BOT_TURN_TIMEOUT_MS` is an escape hatch;
+ * unset, empty, zero or invalid means unlimited.
+ */
+export const TURN_TIMEOUT_ENV = "HQ_BOT_TURN_TIMEOUT_MS";
+export function turnTimeoutMs(env = process.env) {
+    const raw = Number(env[TURN_TIMEOUT_ENV]);
+    return Number.isFinite(raw) && raw > 0 ? raw : undefined;
+}
+/** Parse one NDJSON line; null when it is not a JSON object. */
+export function parseJsonLine(line) {
+    const t = line.trim();
+    if (!t.startsWith("{"))
+        return null;
+    try {
+        const v = JSON.parse(t);
+        return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function stderrExcerpt(stderr, max = 400) {
+    const lines = stderr.split("\n").map((l) => l.trim()).filter(Boolean);
+    return lines.slice(-6).join(" | ").slice(0, max);
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,38 @@
+/**
+ * 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";
+export interface ScaffoldResult {
+    /** personal/workers/<name> (absolute). */
+    dir: string;
+    /** The memory folder (absolute) — inside `dir` unless `memoryDir` was given. */
+    memoryDir: string;
+    created: string[];
+    kept: string[];
+}
+export interface ScaffoldOptions {
+    /**
+     * Memory folder override: hqRoot-relative or absolute (`--memory local`
+     * keeps it under ~/.hq/bots/<name>/memory, outside the synced tree).
+     * Default: personal/workers/<name>/memory.
+     */
+    memoryDir?: string;
+}
+export declare function renderWorkerYaml(name: string, agentUid: string, runtime: string, memoryDir?: string): string;
+export declare function renderPersonaMd(name: string): string;
+export declare function renderMemoryReadme(name: string): string;
+type ScaffoldFs = Pick<typeof fs, "existsSync" | "mkdirSync" | "writeFileSync">;
+/** Absolute memory folder for a scaffold: the override (relative to hqRoot unless absolute) or the default. */
+export declare function resolveScaffoldMemoryDir(hqRoot: string, name: string, memoryDir?: string): string;
+/**
+ * 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 declare function scaffoldBotMemory(hqRoot: string, name: string, io?: ScaffoldFs, opts?: ScaffoldOptions): ScaffoldResult;
+export declare function scaffoldBotWorker(hqRoot: string, name: string, agentUid: string, runtime: string, io?: ScaffoldFs, opts?: ScaffoldOptions): ScaffoldResult;
+export {};
+//# sourceMappingURL=scaffold.d.ts.map