@indigoai-us/hq-cli 5.314.0 → 5.316.0

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/checkpoint-ontology/aliases.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Alias rules shared by `apply` and the multi-writer merge-back.
+ */
+import type { EntityIndex } from "./tree.js";
+/** Longest canonical name or alias the writer accepts. */
+export declare const MAX_NAME_LENGTH = 200;
+/** The index key for a normalised name of one type. */
+export declare function entityKey(type: string, normalized: string): string;
+/**
+ * Aliases worth adding to the entity at `self`: new to it, and held by no
+ * other entity of any type, so an alias can never make a later match
+ * ambiguous. `own` holds the normalised names the entity already answers to.
+ */
+export declare function freshAliases(index: EntityIndex, type: string, self: string, own: Set<string>, names: string[]): string[];
+/** The normalised names an indexed entity answers to, plus aliases queued this run. */
+export declare function ownNames(index: EntityIndex, rel: string, queued: string[]): Set<string>;
+//# sourceMappingURL=aliases.d.ts.map

package/dist/lib/checkpoint-ontology/aliases.js

@@ -0,0 +1,44 @@
+/**
+ * Alias rules shared by `apply` and the multi-writer merge-back.
+ */
+import { canonicalizeName, isRejectedName, normalizeEntityName } from "./identity.js";
+/** Longest canonical name or alias the writer accepts. */
+export const MAX_NAME_LENGTH = 200;
+/** The index key for a normalised name of one type. */
+export function entityKey(type, normalized) {
+    return `${type}\0${normalized}`;
+}
+/**
+ * Aliases worth adding to the entity at `self`: new to it, and held by no
+ * other entity of any type, so an alias can never make a later match
+ * ambiguous. `own` holds the normalised names the entity already answers to.
+ */
+export function freshAliases(index, type, self, own, names) {
+    const seen = new Set(own);
+    const out = [];
+    for (const raw of names) {
+        const alias = canonicalizeName(raw);
+        if (!alias || alias.length > MAX_NAME_LENGTH)
+            continue;
+        const normalized = normalizeEntityName(alias, type);
+        if (!normalized || seen.has(normalized) || isRejectedName(normalized))
+            continue;
+        const holders = [
+            ...(index.canonical.get(entityKey(type, normalized)) ?? []),
+            ...(index.alias.get(entityKey(type, normalized)) ?? []),
+        ];
+        if (holders.some((holder) => holder !== self))
+            continue;
+        if ([...(index.types.get(normalized) ?? [])].some((other) => other !== type))
+            continue;
+        seen.add(normalized);
+        out.push(alias);
+    }
+    return out;
+}
+/** The normalised names an indexed entity answers to, plus aliases queued this run. */
+export function ownNames(index, rel, queued) {
+    const entity = index.byRel.get(rel);
+    return new Set([entity.canonical_name, ...entity.aliases, ...queued].map((name) => normalizeEntityName(name, entity.type)));
+}
+//# sourceMappingURL=aliases.js.map

package/dist/lib/checkpoint-ontology/apply.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `hq core ontology apply`: turn the model's candidates into entity writes.
+ *
+ * Every rule that affects identity, scope or cost lives here (design
+ * sections 4.3, 5 and 14). The model output is untrusted input: a malformed
+ * candidate is rejected and counted, never repaired.
+ */
+import { type DuplicateReport, type MergeBackOutcome } from "./multi-writer.js";
+import { type CompanyBriefResult } from "./company-brief.js";
+import { type SyncClientVersions } from "./sync-client.js";
+export declare const CAPS: {
+    readonly creates: 25;
+    readonly updates: 100;
+    readonly bytes: number;
+    readonly newAliasesPerEntity: 3;
+    readonly aliasesPerCandidate: 5;
+    readonly nameLength: 200;
+};
+export interface ApplyReport {
+    schema: "hq-checkpoint-ontology-report.v1";
+    company: string;
+    run_id: string;
+    status: "applied" | "no_candidates" | "invalid_candidates" | "sync_client_old";
+    /** Present only with status `sync_client_old`: which sync client copy is older or unknown. */
+    skip_reason?: string;
+    planned_inputs: number;
+    planned_tokens: number;
+    candidates: number;
+    created: string[];
+    updated: string[];
+    matched: number;
+    session_links: Array<{
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    /** Per input, the entities it resolved to: `link` for an existing entity, `create` for a new file. */
+    links: Array<{
+        input: string;
+        action: "link" | "create";
+        type: string;
+        canonical_name: string;
+        path: string;
+    }>;
+    /** Present only when `checkpoint.ontology.dominant-sibling-link` was on: knowledge links moved from a weak sibling to the dominant one. */
+    dominant_sibling_redirects?: Array<{
+        input: string;
+        from: string;
+        to: string;
+    }>;
+    rejected: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    deferred: Array<{
+        input: string;
+        type: string;
+        name: string;
+        reason: string;
+    }>;
+    suspect_duplicates: Array<{
+        name: string;
+        type: string;
+        paths: string[];
+    }>;
+    backrefs_added: number;
+    bytes_written: number;
+    inputs_done: string[];
+    inputs_pending: string[];
+    write_errors: Array<{
+        path: string;
+        reason: string;
+    }>;
+    /** Present only when the plan ran the company brief and this apply created or updated entities. */
+    company_brief?: CompanyBriefResult;
+    /** Present only when `checkpoint.ontology.multi-writer` was on for the plan (design section 20). */
+    multi_writer?: {
+        conflicts: MergeBackOutcome[];
+        /** Entity files this apply wrote and recorded in the outbox. */
+        outbox_recorded: number;
+        outbox_reset?: true;
+        error?: string;
+        duplicates?: DuplicateReport;
+    };
+    duration_ms: number;
+}
+export interface ApplyOptions {
+    hqRoot: string;
+    runDir: string;
+    /** The payload company. Must equal the plan's company. */
+    company: string;
+    now?: Date;
+    /** Test seam for the sync client check; defaults to reading this machine's hq-cloud copies. */
+    syncClientVersions?: () => SyncClientVersions;
+}
+export declare class ApplyError extends Error {
+    constructor(message: string);
+}
+/**
+ * checkpoint.ontology.named-evidence: true when `evidence` holds one of
+ * `names` as a word, matching case. A name inside a path, domain, handle, tag
+ * or identifier does not count: `indigoai-us/hq`, `getindigo.ai`,
+ * `C:\\Indigo\\hq`, `scope: company:indigo`, `Indigo:internal`, `@indigo`,
+ * `` `indigo` ``.
+ */
+export declare function evidenceNames(evidence: string, names: string[]): boolean;
+export declare function applyOntologyRun(options: ApplyOptions): ApplyReport;
+//# sourceMappingURL=apply.d.ts.map