@indigoai-us/hq-cli 5.109.15 → 5.110.0

package/dist/commands/workers.d.ts

@@ -1,18 +1,6 @@
 import { Command } from "commander";
-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[];
+export { readWorkerRegistry, type RegistryWorker } from "../lib/workers-registry/read.js";
+import { type RegistryWorker } from "../lib/workers-registry/read.js";
 /**
  * Best-effort active company: workspace/sessions/.current -> meta.yaml
  * company_slug. Undefined when no session context is set. Pure/read-only.

package/dist/commands/workers.js

@@ -7,14 +7,8 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "./secrets.js";
 import { GROUP_ID_PATTERN, EMAIL_PATTERN, normalizeFilePrefix } from "./_patterns.js";
 import { findHqRoot } from "../utils/manifest.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 ?? [];
-}
+export { readWorkerRegistry } from "../lib/workers-registry/read.js";
+import { readWorkerRegistry } from "../lib/workers-registry/read.js";
 /**
  * Best-effort active company: workspace/sessions/.current -> meta.yaml
  * company_slug. Undefined when no session context is set. Pure/read-only.

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

@@ -0,0 +1,202 @@
+/**
+ * Typed HQ API client for the bot runtime (local-bots US-004).
+ *
+ * Every call goes through the shared `vaultApiFetch` helper with a token
+ * supplier so the bot's machine identity (agt_) is minted and refreshed by the
+ * existing Cognito machinery. `fetch` is injectable for tests.
+ */
+import { vaultApiFetch } from "../../utils/vault-api.js";
+export type TokenSupplier = () => Promise<string>;
+/**
+ * One agent-inbox item. DMs carry the base fields; room (channel / group chat)
+ * items add the optional room fields (server: hq-pro-core
+ * room-agent-delivery.ts `RoomInboxMessage`).
+ */
+export interface InboxItem {
+    messageId: string;
+    channel: string;
+    eventId?: string;
+    fromPersonUid?: string;
+    fromDisplayName?: string;
+    text?: string;
+    rootEventId?: string;
+    receivedAt?: string;
+    /** Room items only (channel === "room"). */
+    channelId?: string;
+    channelName?: string;
+    channelScope?: string;
+    mentionedMe?: boolean;
+    memberCount?: number;
+    senderTrust?: "member";
+}
+/** @deprecated use InboxItem */
+export type DmInboxItem = InboxItem;
+/** A simplified channel message for the "Recent messages" context block. */
+export interface ChannelMessageSummary {
+    eventId?: string;
+    fromPersonUid?: string;
+    fromDisplayName?: string;
+    body: string;
+    createdAt?: string;
+}
+export interface AgentRecord {
+    uid: string;
+    name?: string;
+    ownerUid?: string | null;
+    computeMode?: string;
+    botKind?: string;
+    online?: boolean;
+    runtime?: {
+        status?: string;
+        lastHeartbeat?: {
+            at?: string;
+        } | null;
+    };
+}
+export declare class BotApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly code?: string | undefined;
+    constructor(status: number, path: string, code?: string | undefined, detail?: string);
+}
+export interface BotApiOptions {
+    token: TokenSupplier;
+    baseUrl?: string;
+    fetchImpl?: typeof vaultApiFetch;
+}
+export interface BotPromotionState {
+    version: number;
+    operationId: string;
+    agentUid: string;
+    ownerUid: string;
+    companyUid: string;
+    snapshotSha256: string;
+    phase: "preparing" | "local-stopped" | "imported" | "cloud-ready" | "active" | "cancelled";
+    updatedAt: string;
+}
+export interface BotPromotionUpload {
+    url: string;
+    method: "PUT";
+    headers: Record<string, string>;
+    bytes: number;
+    sha256: string;
+    expiresInSeconds: number;
+}
+export declare class BotApi {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: BotApiOptions);
+    private call;
+    /** GET /v1/agents/{uid} — owner-only local bot record (403/404 for others). */
+    getAgent(agentUid: string): Promise<AgentRecord>;
+    /** POST /v1/agents/{uid}/heartbeat — agent-JWT only. */
+    heartbeat(agentUid: string, components: Record<string, "ok" | "degraded" | "failed" | "unknown">): Promise<{
+        ok: boolean;
+        at?: string;
+        local?: boolean;
+    }>;
+    /** GET /v1/agents/{uid}/inbox → { messages } (agent-JWT only). */
+    pullInbox(agentUid: string): Promise<InboxItem[]>;
+    /** POST /v1/agents/{uid}/inbox/{messageId}/ack */
+    ackInbox(agentUid: string, messageId: string): Promise<void>;
+    /** POST /v1/notify/dm — send as the bot (agent identity). */
+    sendDm(input: {
+        toPersonUid: string;
+        body: string;
+        rootEventId?: string;
+    }): Promise<{
+        eventId?: string;
+        createdAt?: string;
+        state?: string;
+    }>;
+    /** POST|DELETE /v1/notify/reactions on a DM message (best-effort thinking status). */
+    setReaction(input: {
+        peerUid: string;
+        messageId: string;
+        emoji: string;
+    }, present: boolean): Promise<boolean>;
+    /**
+     * POST /v1/notify/channels/{id}/claims — first-claim-wins on a room unit.
+     * 200 → true (this bot answers), 409 THREAD_ALREADY_CLAIMED → false
+     * (someone else does). Anything else throws.
+     */
+    claimChannelUnit(channelId: string, unitId: string): Promise<boolean>;
+    /** POST /v1/notify/channels/{id}/messages — post in a room as the bot. */
+    sendChannelMessage(input: {
+        channelId: string;
+        body: string;
+        rootEventId?: string;
+    }): Promise<{
+        eventId?: string;
+        createdAt?: string;
+        rootEventId?: string;
+    }>;
+    /**
+     * POST /v1/notify/channels/{id}/agent-status — ephemeral "thinking" hint in
+     * a room (never durable; the server clears it on the next event). Best-effort.
+     */
+    postAgentStatus(channelId: string, status: string, threadRoot?: string): Promise<boolean>;
+    /**
+     * GET /v1/notify/channels/{id}/messages?limit=N — the newest N messages,
+     * returned oldest-first so they read as a transcript.
+     */
+    fetchChannelMessages(channelId: string, limit?: number): Promise<ChannelMessageSummary[]>;
+    /** POST /v1/agents — person identity creates a local bot (US-002). */
+    /** Promotion mutations must use a human owner token, not bot credentials. */
+    preparePromotion(agentUid: string, input: {
+        companyUid: string;
+        operationId: string;
+        snapshotSha256: string;
+    }): Promise<BotPromotionState>;
+    promotionDetails(agentUid: string, companyUid: string): Promise<{
+        promotion: BotPromotionState | null;
+        failure?: string;
+        pairing: {
+            url: string;
+            code: string;
+            capturedAt?: string;
+        } | null;
+    }>;
+    promotionStatus(agentUid: string, companyUid: string): Promise<BotPromotionState | null>;
+    resumePromotion(agentUid: string, input: {
+        companyUid: string;
+        operationId: string;
+    }): Promise<{
+        promotion: BotPromotionState;
+        pending: boolean;
+    }>;
+    confirmPromotionStopped(agentUid: string, input: {
+        companyUid: string;
+        operationId: string;
+        proof: string;
+    }): Promise<BotPromotionState>;
+    promotionUpload(agentUid: string, input: {
+        companyUid: string;
+        operationId: string;
+        sha256: string;
+        bytes: number;
+        kind: "snapshot" | "machine-credential";
+    }): Promise<{
+        promotion: BotPromotionState;
+        upload: BotPromotionUpload;
+    }>;
+    createLocalBot(input: {
+        name: string;
+        slug?: string;
+    }): Promise<{
+        agent: AgentRecord;
+        identity: {
+            cognitoUsername: string;
+            secret: string;
+        };
+    }>;
+    /** DELETE /v1/agents/{uid} — owner tears the identity down. */
+    deleteLocalBot(agentUid: string): Promise<{
+        uid: string;
+        terminal: boolean;
+        compensations: string[];
+        failures?: Record<string, string>;
+        code?: string;
+    }>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/lib/bot/api.js

@@ -0,0 +1,202 @@
+/**
+ * Typed HQ API client for the bot runtime (local-bots US-004).
+ *
+ * Every call goes through the shared `vaultApiFetch` helper with a token
+ * supplier so the bot's machine identity (agt_) is minted and refreshed by the
+ * existing Cognito machinery. `fetch` is injectable for tests.
+ */
+import { vaultApiFetch } from "../../utils/vault-api.js";
+export class BotApiError extends Error {
+    status;
+    path;
+    code;
+    constructor(status, path, code, detail) {
+        super(`HQ API ${path} → ${status}${code ? ` ${code}` : ""}${detail ? `: ${detail}` : ""}`);
+        this.status = status;
+        this.path = path;
+        this.code = code;
+        this.name = "BotApiError";
+    }
+}
+async function readError(res) {
+    try {
+        const body = (await res.json());
+        return {
+            code: typeof body.code === "string" ? body.code : undefined,
+            detail: typeof body.error === "string"
+                ? body.error
+                : typeof body.message === "string"
+                    ? body.message
+                    : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export class BotApi {
+    opts;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetchImpl = opts.fetchImpl ?? vaultApiFetch;
+    }
+    async call(path, init = {}, accept = [200, 201, 202]) {
+        const token = await this.opts.token();
+        const res = await this.fetchImpl({
+            token,
+            path,
+            method: init.method,
+            body: init.body,
+            query: init.query,
+            ...(this.opts.baseUrl ? { baseUrl: this.opts.baseUrl } : {}),
+        });
+        if (!accept.includes(res.status)) {
+            const err = await readError(res);
+            throw new BotApiError(res.status, path, err.code, err.detail);
+        }
+        const text = await res.text();
+        return { status: res.status, body: (text ? JSON.parse(text) : {}) };
+    }
+    /** GET /v1/agents/{uid} — owner-only local bot record (403/404 for others). */
+    async getAgent(agentUid) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}`);
+        return body.agent ?? body;
+    }
+    /** POST /v1/agents/{uid}/heartbeat — agent-JWT only. */
+    async heartbeat(agentUid, components) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/heartbeat`, { method: "POST", body: { components } });
+        return body;
+    }
+    /** GET /v1/agents/{uid}/inbox → { messages } (agent-JWT only). */
+    async pullInbox(agentUid) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/inbox`);
+        return body.messages ?? body.items ?? [];
+    }
+    /** POST /v1/agents/{uid}/inbox/{messageId}/ack */
+    async ackInbox(agentUid, messageId) {
+        await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/inbox/${encodeURIComponent(messageId)}/ack`, { method: "POST", body: {} });
+    }
+    /** POST /v1/notify/dm — send as the bot (agent identity). */
+    async sendDm(input) {
+        const payload = { toPersonUid: input.toPersonUid, body: input.body };
+        if (input.rootEventId)
+            payload.rootEventId = input.rootEventId;
+        const { body } = await this.call("/v1/notify/dm", { method: "POST", body: payload });
+        return body;
+    }
+    /** POST|DELETE /v1/notify/reactions on a DM message (best-effort thinking status). */
+    async setReaction(input, present) {
+        try {
+            await this.call("/v1/notify/reactions", {
+                method: present ? "POST" : "DELETE",
+                body: { messageScope: `dm:${input.peerUid}`, messageId: input.messageId, emoji: input.emoji },
+            }, [200, 201, 204]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * POST /v1/notify/channels/{id}/claims — first-claim-wins on a room unit.
+     * 200 → true (this bot answers), 409 THREAD_ALREADY_CLAIMED → false
+     * (someone else does). Anything else throws.
+     */
+    async claimChannelUnit(channelId, unitId) {
+        try {
+            await this.call(`/v1/notify/channels/${encodeURIComponent(channelId)}/claims`, { method: "POST", body: { unitId } }, [200]);
+            return true;
+        }
+        catch (err) {
+            if (err instanceof BotApiError && err.status === 409)
+                return false;
+            throw err;
+        }
+    }
+    /** POST /v1/notify/channels/{id}/messages — post in a room as the bot. */
+    async sendChannelMessage(input) {
+        const payload = { body: input.body };
+        if (input.rootEventId)
+            payload.rootEventId = input.rootEventId;
+        const { body } = await this.call(`/v1/notify/channels/${encodeURIComponent(input.channelId)}/messages`, { method: "POST", body: payload });
+        return body;
+    }
+    /**
+     * POST /v1/notify/channels/{id}/agent-status — ephemeral "thinking" hint in
+     * a room (never durable; the server clears it on the next event). Best-effort.
+     */
+    async postAgentStatus(channelId, status, threadRoot) {
+        try {
+            await this.call(`/v1/notify/channels/${encodeURIComponent(channelId)}/agent-status`, { method: "POST", body: { status, ...(threadRoot ? { threadRoot } : {}) } }, [200]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * GET /v1/notify/channels/{id}/messages?limit=N — the newest N messages,
+     * returned oldest-first so they read as a transcript.
+     */
+    async fetchChannelMessages(channelId, limit = 15) {
+        const { body } = await this.call(`/v1/notify/channels/${encodeURIComponent(channelId)}/messages`, { query: { limit: String(limit) } });
+        const rows = Array.isArray(body.messages) ? body.messages : [];
+        const out = [];
+        for (const row of rows) {
+            const text = typeof row.body === "string" ? row.body.trim() : "";
+            if (!text)
+                continue;
+            out.push({
+                ...(typeof row.eventId === "string" ? { eventId: row.eventId } : {}),
+                ...(typeof row.fromPersonUid === "string" ? { fromPersonUid: row.fromPersonUid } : {}),
+                ...(typeof row.fromDisplayName === "string" && row.fromDisplayName.trim()
+                    ? { fromDisplayName: row.fromDisplayName.trim() }
+                    : {}),
+                body: text,
+                ...(typeof row.createdAt === "string" ? { createdAt: row.createdAt } : {}),
+            });
+        }
+        out.sort((a, b) => (a.createdAt ?? "").localeCompare(b.createdAt ?? ""));
+        return out;
+    }
+    /** POST /v1/agents — person identity creates a local bot (US-002). */
+    /** Promotion mutations must use a human owner token, not bot credentials. */
+    async preparePromotion(agentUid, input) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote/prepare`, { method: "POST", body: input })).body.promotion;
+    }
+    async promotionDetails(agentUid, companyUid) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote?companyUid=${encodeURIComponent(companyUid)}`, { method: "GET" })).body;
+    }
+    async promotionStatus(agentUid, companyUid) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote?companyUid=${encodeURIComponent(companyUid)}`, { method: "GET" })).body.promotion;
+    }
+    async resumePromotion(agentUid, input) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote/resume`, { method: "POST", body: input })).body;
+    }
+    async confirmPromotionStopped(agentUid, input) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote/local-stopped`, { method: "POST", body: input })).body.promotion;
+    }
+    async promotionUpload(agentUid, input) {
+        return (await this.call(`/v1/agents/${encodeURIComponent(agentUid)}/promote/snapshot-upload`, { method: "POST", body: input })).body;
+    }
+    async createLocalBot(input) {
+        const { body } = await this.call("/v1/agents", {
+            method: "POST",
+            body: {
+                name: input.name,
+                ...(input.slug ? { slug: input.slug } : {}),
+                computeMode: "local",
+                botKind: "personal",
+                role: "local-bot",
+            },
+        });
+        return body;
+    }
+    /** DELETE /v1/agents/{uid} — owner tears the identity down. */
+    async deleteLocalBot(agentUid) {
+        const { body } = await this.call(`/v1/agents/${encodeURIComponent(agentUid)}`, { method: "DELETE" });
+        return body;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/lib/bot/company-bind.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Company bind for worker-sourced bots (local-bots Feature 4).
+ *
+ * HQ's company hooks key on workspace/sessions/<sid>/meta.yaml `company_slug`,
+ * where <sid> is the Claude session id carried in the hook payload. A bot that
+ * runs a company worker writes that file for the session id it is about to
+ * use, before every turn, so the hooks resolve the company exactly as they do
+ * for the owner. Idempotent: an existing file keeps its other keys and only
+ * has `company_slug` replaced.
+ *
+ * Coverage note: Claude bots get the full company hook set (their session id
+ * is in the hook payload). Codex/Grok bots only see HQ_SESSION_ID in the env.
+ */
+export interface CompanyBindFs {
+    existsSync: (p: string) => boolean;
+    readFileSync: (p: string) => string;
+    writeFileSync: (p: string, body: string) => void;
+    mkdirSync: (p: string) => void;
+}
+export declare const defaultCompanyBindFs: CompanyBindFs;
+export declare function botSessionMetaRelPath(sessionId: string): string;
+export declare function ensureBotSessionMeta(hqRoot: string, sessionId: string, companySlug: string, io?: CompanyBindFs, now?: () => Date): {
+    path: string;
+    created: boolean;
+    changed: boolean;
+};
+//# sourceMappingURL=company-bind.d.ts.map

package/dist/lib/bot/company-bind.js

@@ -0,0 +1,62 @@
+/**
+ * Company bind for worker-sourced bots (local-bots Feature 4).
+ *
+ * HQ's company hooks key on workspace/sessions/<sid>/meta.yaml `company_slug`,
+ * where <sid> is the Claude session id carried in the hook payload. A bot that
+ * runs a company worker writes that file for the session id it is about to
+ * use, before every turn, so the hooks resolve the company exactly as they do
+ * for the owner. Idempotent: an existing file keeps its other keys and only
+ * has `company_slug` replaced.
+ *
+ * Coverage note: Claude bots get the full company hook set (their session id
+ * is in the hook payload). Codex/Grok bots only see HQ_SESSION_ID in the env.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const defaultCompanyBindFs = {
+    existsSync: (p) => fs.existsSync(p),
+    readFileSync: (p) => fs.readFileSync(p, "utf8"),
+    writeFileSync: (p, body) => fs.writeFileSync(p, body, { mode: 0o644 }),
+    mkdirSync: (p) => fs.mkdirSync(p, { recursive: true }),
+};
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const COMPANY_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export function botSessionMetaRelPath(sessionId) {
+    return path.join("workspace", "sessions", sessionId, "meta.yaml");
+}
+export function ensureBotSessionMeta(hqRoot, sessionId, companySlug, io = defaultCompanyBindFs, now = () => new Date()) {
+    if (!SESSION_ID_RE.test(sessionId))
+        throw new Error(`Invalid session id for company bind: "${sessionId}"`);
+    if (!COMPANY_SLUG_RE.test(companySlug))
+        throw new Error(`Invalid company slug for company bind: "${companySlug}"`);
+    const file = path.join(hqRoot, botSessionMetaRelPath(sessionId));
+    io.mkdirSync(path.dirname(file));
+    if (!io.existsSync(file)) {
+        const body = `session_id: ${sessionId}\nstarted_at: "${now().toISOString()}"\ncompany_slug: ${companySlug}\n`;
+        io.writeFileSync(file, body);
+        return { path: file, created: true, changed: true };
+    }
+    const current = io.readFileSync(file);
+    const lines = current.split("\n");
+    let replaced = false;
+    const next = lines.map((line) => {
+        if (/^company_slug\s*:/.test(line)) {
+            replaced = true;
+            return `company_slug: ${companySlug}`;
+        }
+        return line;
+    });
+    if (!replaced) {
+        while (next.length > 0 && next[next.length - 1] === "")
+            next.pop();
+        next.push(`company_slug: ${companySlug}`);
+    }
+    if (!next.some((l) => /^session_id\s*:/.test(l)))
+        next.unshift(`session_id: ${sessionId}`);
+    const body = `${next.join("\n").replace(/\n+$/, "")}\n`;
+    if (body === current)
+        return { path: file, created: false, changed: false };
+    io.writeFileSync(file, body);
+    return { path: file, created: false, changed: true };
+}
+//# sourceMappingURL=company-bind.js.map

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

@@ -0,0 +1,106 @@
+/**
+ * bot.json — non-secret per-bot configuration (local-bots US-003/US-005).
+ */
+export declare const BOT_RUNTIMES: readonly ["claude", "codex", "grok"];
+export type BotRuntimeId = (typeof BOT_RUNTIMES)[number];
+export declare function isBotRuntimeId(value: unknown): value is BotRuntimeId;
+/** Longest `intro` (first-start hello DM) a bot may store. */
+export declare const BOT_INTRO_MAX_CHARS = 500;
+/** Longest `kickoff` (first-start model turn prompt) a bot may store. */
+export declare const BOT_KICKOFF_MAX_CHARS = 2000;
+/**
+ * Where a bot keeps its memory: "synced" = personal/workers/<name>/memory
+ * inside the HQ tree (follows the owner across machines); "local" =
+ * ~/.hq/bots/<name>/memory, outside the synced tree (this computer only).
+ */
+export declare const BOT_MEMORY_MODES: readonly ["synced", "local"];
+export type BotMemoryMode = (typeof BOT_MEMORY_MODES)[number];
+export declare function isBotMemoryMode(value: unknown): value is BotMemoryMode;
+/**
+ * Thinking ("effort") levels each runtime's CLI accepts, verified 2026-09-12:
+ * `claude --effort`, `codex -c model_reasoning_effort=…`, `grok --reasoning-effort`.
+ */
+export declare const BOT_EFFORT_LEVELS: Record<BotRuntimeId, readonly string[]>;
+/** Every bot thinks at medium unless its owner picks otherwise: quick chat replies. */
+export declare const DEFAULT_BOT_EFFORT = "medium";
+/** The thinking level a bot actually runs with. */
+export declare function effectiveBotEffort(config: Pick<BotConfig, "effort">): string;
+/**
+ * A thinking level for this runtime, or undefined for "default" / empty
+ * (the bot then runs at DEFAULT_BOT_EFFORT). Throws an expected error otherwise.
+ */
+export declare function validateBotEffort(runtime: BotRuntimeId, value: string): string | undefined;
+/**
+ * A model id for the runtime CLI, or undefined for "default" / empty (the
+ * CLI's own default for the owner's account). Throws an expected error when
+ * it cannot be a model id.
+ */
+export declare function validateBotModel(value: string): string | undefined;
+/** Trim and bound the intro text; throws an expected error when unusable. */
+export declare function validateBotIntro(text: string): string;
+/** Trim and bound the kickoff prompt; throws an expected error when unusable. */
+export declare function validateBotKickoff(text: string): string;
+export interface BotConfig {
+    v: 1;
+    name: string;
+    /** The bot's own agt_ identity (owned by `ownerUid`). */
+    agentUid: string;
+    /** The person (prs_) who created and owns the bot. */
+    ownerUid: string;
+    runtime: BotRuntimeId;
+    /** Optional model override handed to the runtime CLI (unset = the CLI's own default). */
+    model?: string;
+    /** Thinking level for the runtime CLI (see BOT_EFFORT_LEVELS; unset = DEFAULT_BOT_EFFORT). */
+    effort?: string;
+    /** HQ root the session starts in (and the cwd of every model turn). */
+    hqRoot: string;
+    /**
+     * Run the model with every permission pre-approved (default true): a bot
+     * answers DMs headlessly and cannot show an approval prompt, so a gated
+     * command simply fails. Set false to keep the runtime's normal gates.
+     */
+    autoApprove?: boolean;
+    /**
+     * Worker folder relative to hqRoot: personal/workers/<name> for a scaffolded
+     * bot, or companies/<co>/workers/<id> when the bot runs a company worker.
+     */
+    workerDir: string;
+    /** Where the worker definition came from (default "scaffold"). */
+    workerSource?: "scaffold" | "worker";
+    /** Registry id of the company worker this bot runs (workerSource "worker"). */
+    workerId?: string;
+    /** Company the bot is bound to on every turn (workerSource "worker"). */
+    companySlug?: string;
+    /**
+     * Memory folder: hqRoot-relative for "synced" memory (default
+     * `${workerDir}/memory`; a worker-sourced bot keeps its own memory in
+     * personal/workers/<name>/memory so the shared company tree is never
+     * written to), or an absolute path for "local" memory that lives outside
+     * the synced tree (~/.hq/bots/<name>/memory).
+     */
+    memoryDir?: string;
+    /**
+     * Verbatim hello the bot DMs its owner when it first comes online (and on
+     * `hq bot intro`). Unset = the default introduction.
+     */
+    intro?: string;
+    /**
+     * Prompt for ONE model turn the bot runs on its first start, right after the
+     * intro DM, as if the owner had sent it (same session, system prompt and
+     * permissions); the answer is DMed to the owner. Runs once, never on restart.
+     */
+    kickoff?: string;
+    createdAt: string;
+    /** When `false` the run loop exits 0 immediately (launchd does not respawn). */
+    enabled: boolean;
+    /** Set once the bot has introduced itself to the owner (US-008 intro). */
+    introSentAt?: string;
+}
+export declare function readBotConfig(dir: string): BotConfig | null;
+export declare function writeBotConfig(dir: string, config: BotConfig): void;
+/** "local" when the memory folder is an absolute path outside the HQ tree. */
+export declare function botMemoryMode(config: Pick<BotConfig, "memoryDir">): BotMemoryMode;
+/** Absolute memory folder for a bot (synced memory is resolved against hqRoot). */
+export declare function resolveBotMemoryDir(config: Pick<BotConfig, "hqRoot" | "workerDir" | "memoryDir">): string;
+export declare function patchBotConfig(dir: string, patch: Partial<BotConfig>): BotConfig;
+//# sourceMappingURL=config.d.ts.map