@indigoai-us/hq-cli 5.345.191 → 5.345.193

package/dist/lib/signals/failure-alert.d.ts

@@ -0,0 +1,89 @@
+/**
+ * The signals-failure alert for the `hq signals run` engine (Hot-Signal Sync
+ * US-018).
+ *
+ * The engine's run record already counts what each step took in and put out.
+ * A run whose extract step read sources and produced no candidates is a
+ * silent stall, the shape of the 2026-10-14 stall. Only sources extract reads
+ * count: hot-channel landings (Slack, Linear, Gmail) that no declared source
+ * channel covers never reach extract, so they cannot show a stall. This module
+ * checks the run record for that shape and hands the failure to the existing
+ * ledger alert path (`raiseSignalsFailureAlerts` in
+ * `src/lib/hot-channels/alert.ts`), so the alert text, the owner DM and the
+ * hourly dedupe in `sources/_runs/@{personKey}/_alerts.json` are the same ones
+ * the hot-channel sync uses. No new posting path is added here.
+ */
+import { type RaiseSignalsFailureAlertsResult } from "../hot-channels/alert.js";
+import type { RunLedgerEntry } from "../hot-channels/ledger.js";
+import type { RunRecord, StepRecord } from "./engine.js";
+/**
+ * Extract skips that are not a stall: no source channel to read, or the
+ * ontology worker is not installed. Both are reported in the run record
+ * already, and an hourly alert would only repeat them.
+ */
+export declare const EXTRACT_SKIPS_WITHOUT_ALERT: ReadonlySet<string>;
+/** The adapter name the engine's alert uses in the shared dedupe file: one key per company vault. */
+export declare const SIGNALS_RUN_ALERT_ADAPTER = "signals-run";
+/** Who the alert is for, and the key of their dedupe file. */
+export interface SignalsAlertPerson {
+    /** The audience key of the person's `sources/_runs/@{personKey}/` folder. */
+    personKey: string;
+    /** Shown in the alert text; usually the person's email. */
+    personName?: string;
+    /** The Cognito sub, recorded on the ledger line the alert is built from. */
+    personUid?: string;
+}
+/** Where the engine sends a signals-failure alert. */
+export interface SignalsRunAlertSenders {
+    /** The primary alert to the owner; throws when it was not delivered. */
+    sendOwnerDm: (text: string) => Promise<void>;
+    /**
+     * The person whose dedupe file is used. Defaults to the signed-in person
+     * (the same key `hq sources sync` uses). Null skips the alert.
+     */
+    resolvePerson?: (company: string) => SignalsAlertPerson | null | Promise<SignalsAlertPerson | null>;
+    log?: (message: string) => void;
+    /**
+     * False for a sender no one reads later, such as the terminal of a manual
+     * `hq signals run`. Its alert neither reads nor writes the hourly dedupe, so
+     * it never suppresses the owner DM the bot sends for the same company.
+     * Default true.
+     */
+    recordsDelivery?: boolean;
+}
+/** The signed-in person, as `runCompanyHotChannelSync` resolves them; null when no one is signed in. */
+export declare function resolveSignedInAlertPerson(): SignalsAlertPerson | null;
+/** Source items the extract step read: its worklist items minus the ones the worklist skipped. */
+export declare function extractSourcesRead(extract: StepRecord): number;
+/**
+ * True when a run's sources produced no signals. The run must be real (not a
+ * dry run, not a repeat of an earlier job run) and have both an adapters and an
+ * extract step (one-step runs and late starts are not judged), and extract
+ * must have produced no candidates. Then either:
+ * - extract ran and read at least one source item, or
+ * - extract did not finish (failed, or skipped for a reason other than
+ *   `no-sources` / `ontology-worker-missing`) after the adapters step landed
+ *   new sources.
+ * Hot-channel landings extract never reads do not count on their own, so a
+ * day with Slack activity and no declared-source items is not a stall.
+ */
+export declare function isSignalsRunFailure(record: RunRecord): boolean;
+/**
+ * The run record as one ledger line, so the existing alert path formats,
+ * sends and dedupes it. `sourcesLanded` is the source items extract read (or,
+ * when extract read none, what the adapters step landed) and
+ * `signalsGenerated` is what extract produced.
+ */
+export declare function signalsRunLedgerLine(record: RunRecord, person: SignalsAlertPerson): RunLedgerEntry;
+/**
+ * Alert the owner for each run record that landed sources and produced no
+ * signals. Never throws; a failed send is logged and left unrecorded, so the
+ * next run tries again. Returns the alert result per company that alerted.
+ */
+export declare function raiseSignalsRunAlerts(input: {
+    hqRoot: string;
+    records: readonly RunRecord[];
+    senders: SignalsRunAlertSenders;
+    now: () => Date;
+}): Promise<Record<string, RaiseSignalsFailureAlertsResult>>;
+//# sourceMappingURL=failure-alert.d.ts.map

package/dist/lib/signals/failure-alert.js

@@ -0,0 +1,175 @@
+/**
+ * The signals-failure alert for the `hq signals run` engine (Hot-Signal Sync
+ * US-018).
+ *
+ * The engine's run record already counts what each step took in and put out.
+ * A run whose extract step read sources and produced no candidates is a
+ * silent stall, the shape of the 2026-10-14 stall. Only sources extract reads
+ * count: hot-channel landings (Slack, Linear, Gmail) that no declared source
+ * channel covers never reach extract, so they cannot show a stall. This module
+ * checks the run record for that shape and hands the failure to the existing
+ * ledger alert path (`raiseSignalsFailureAlerts` in
+ * `src/lib/hot-channels/alert.ts`), so the alert text, the owner DM and the
+ * hourly dedupe in `sources/_runs/@{personKey}/_alerts.json` are the same ones
+ * the hot-channel sync uses. No new posting path is added here.
+ */
+import * as path from "node:path";
+import { audienceKey } from "../hot-channels/audience.js";
+import { findSignalsFailures, formatSignalsFailureAlert, raiseSignalsFailureAlerts, signalsAlertKey, signalsAlertStatePath, } from "../hot-channels/alert.js";
+import { assertAllowedPath } from "./write-guard.js";
+import { resolveUploadAuthor } from "../../utils/upload-author.js";
+/**
+ * Extract skips that are not a stall: no source channel to read, or the
+ * ontology worker is not installed. Both are reported in the run record
+ * already, and an hourly alert would only repeat them.
+ */
+export const EXTRACT_SKIPS_WITHOUT_ALERT = new Set(["no-sources", "ontology-worker-missing"]);
+/** The adapter name the engine's alert uses in the shared dedupe file: one key per company vault. */
+export const SIGNALS_RUN_ALERT_ADAPTER = "signals-run";
+/** The signed-in person, as `runCompanyHotChannelSync` resolves them; null when no one is signed in. */
+export function resolveSignedInAlertPerson() {
+    const author = resolveUploadAuthor();
+    if (!author)
+        return null;
+    return { personKey: audienceKey([author.email]), personName: author.email, personUid: author.userSub };
+}
+function firstStep(record, name) {
+    return record.steps.find((s) => s.name === name);
+}
+/** Source items the extract step read: its worklist items minus the ones the worklist skipped. */
+export function extractSourcesRead(extract) {
+    return Math.max(0, extract.itemsIn - (extract.skippedItems?.length ?? 0));
+}
+/**
+ * True when a run's sources produced no signals. The run must be real (not a
+ * dry run, not a repeat of an earlier job run) and have both an adapters and an
+ * extract step (one-step runs and late starts are not judged), and extract
+ * must have produced no candidates. Then either:
+ * - extract ran and read at least one source item, or
+ * - extract did not finish (failed, or skipped for a reason other than
+ *   `no-sources` / `ontology-worker-missing`) after the adapters step landed
+ *   new sources.
+ * Hot-channel landings extract never reads do not count on their own, so a
+ * day with Slack activity and no declared-source items is not a stall.
+ */
+export function isSignalsRunFailure(record) {
+    if (record.dryRun || record.alreadyRanToday)
+        return false;
+    const adapters = firstStep(record, "adapters");
+    const extract = firstStep(record, "extract");
+    if (!adapters || !extract)
+        return false;
+    if (extract.itemsOut !== 0)
+        return false;
+    if (extract.status === "skipped" && extract.skippedReason && EXTRACT_SKIPS_WITHOUT_ALERT.has(extract.skippedReason)) {
+        return false;
+    }
+    if (extractSourcesRead(extract) > 0)
+        return true;
+    // extract read nothing. Only a broken extract after new landings is a stall;
+    // adapters itemsOut is what landed (itemsIn also counts duplicates).
+    return (extract.status === "failed" || extract.status === "skipped") && adapters.itemsOut > 0;
+}
+/**
+ * The run record as one ledger line, so the existing alert path formats,
+ * sends and dedupes it. `sourcesLanded` is the source items extract read (or,
+ * when extract read none, what the adapters step landed) and
+ * `signalsGenerated` is what extract produced.
+ */
+export function signalsRunLedgerLine(record, person) {
+    const adapters = firstStep(record, "adapters");
+    const extract = firstStep(record, "extract");
+    const extractNote = extract?.error ?? (extract?.skippedReason ? `extract skipped: ${extract.skippedReason}` : null);
+    return {
+        runId: `signals-run ${record.company} ${record.startedAt}`,
+        trigger: record.trigger === "job" ? "scheduled" : "on-demand",
+        adapter: SIGNALS_RUN_ALERT_ADAPTER,
+        connectionId: null,
+        sourcesLanded: extract && extractSourcesRead(extract) > 0 ? extractSourcesRead(extract) : (adapters?.itemsOut ?? 0),
+        signalsGenerated: extract?.itemsOut ?? 0,
+        startedAt: record.startedAt,
+        finishedAt: record.finishedAt ?? record.startedAt,
+        status: record.status === "failed" || record.status === "partial" ? "failed" : "ok",
+        error: extractNote,
+        personUid: person.personUid ?? person.personKey,
+        ...(record.catchUp ? { catchUp: true } : {}),
+    };
+}
+/**
+ * Alert the owner for each run record that landed sources and produced no
+ * signals. Never throws; a failed send is logged and left unrecorded, so the
+ * next run tries again. Returns the alert result per company that alerted.
+ */
+export async function raiseSignalsRunAlerts(input) {
+    const out = {};
+    const log = input.senders.log ?? (() => { });
+    const resolvePerson = input.senders.resolvePerson ?? (() => resolveSignedInAlertPerson());
+    for (const record of input.records) {
+        if (!isSignalsRunFailure(record))
+            continue;
+        if (input.senders.recordsDelivery === false) {
+            out[record.company] = await sendWithoutDedupe(record, input.senders, resolvePerson, log);
+            continue;
+        }
+        let person;
+        try {
+            person = await resolvePerson(record.company);
+        }
+        catch (err) {
+            log(`signals alert for ${record.company} skipped: ${err instanceof Error ? err.message : String(err)}`);
+            continue;
+        }
+        if (!person) {
+            log(`signals alert for ${record.company} skipped: no signed-in person to alert`);
+            continue;
+        }
+        const vaultRoot = path.join(input.hqRoot, "companies", record.company);
+        try {
+            // The dedupe file is the one engine write outside guardedWrite; hold it to the same roots.
+            const stateRel = path.relative(input.hqRoot, signalsAlertStatePath(vaultRoot, person.personKey));
+            assertAllowedPath(input.hqRoot, stateRel.split(path.sep).join("/"), { company: record.company });
+            out[record.company] = await raiseSignalsFailureAlerts({
+                vaultRoot,
+                personKey: person.personKey,
+                entries: [signalsRunLedgerLine(record, person)],
+                now: input.now,
+                ...(person.personName ? { personName: person.personName } : {}),
+                sendOwnerDm: input.senders.sendOwnerDm,
+                log,
+            });
+        }
+        catch (err) {
+            log(`signals alert for ${record.company} failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return out;
+}
+/**
+ * Deliver one alert to a sender that keeps no record (the terminal). The
+ * dedupe file is neither read nor written, and no signed-in person is needed.
+ */
+async function sendWithoutDedupe(record, senders, resolvePerson, log) {
+    const result = { sent: [], suppressed: [], failed: [] };
+    let person;
+    try {
+        person = await resolvePerson(record.company);
+    }
+    catch {
+        // The terminal needs no person; print the alert without a name.
+        person = null;
+    }
+    const line = signalsRunLedgerLine(record, person ?? { personKey: "-" });
+    if (findSignalsFailures([line]).length === 0)
+        return result;
+    const key = signalsAlertKey(line);
+    try {
+        await senders.sendOwnerDm(formatSignalsFailureAlert(line, person?.personName ? { personName: person.personName } : {}));
+        result.sent.push(key);
+    }
+    catch (err) {
+        log(`signals alert for ${key} was not delivered: ${err instanceof Error ? err.message : String(err)}`);
+        result.failed.push(key);
+    }
+    return result;
+}
+//# sourceMappingURL=failure-alert.js.map

package/dist/lib/signals/local-date.d.ts

@@ -0,0 +1,3 @@
+/** Local calendar date, YYYY-MM-DD. The signals engine and its steps name every dated folder with it. */
+export declare function localDate(d: Date): string;
+//# sourceMappingURL=local-date.d.ts.map

package/dist/lib/signals/local-date.js

@@ -0,0 +1,6 @@
+/** Local calendar date, YYYY-MM-DD. The signals engine and its steps name every dated folder with it. */
+export function localDate(d) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+//# sourceMappingURL=local-date.js.map

package/dist/lib/signals/projection.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Member projection pull for the upload step (Hot-Signal Sync US-005).
+ *
+ * hq-pro writes each member's entity projection to
+ * `ontology/projections/members/{memberUid}/v1/{manifest.json,entities.jsonl}`
+ * in the company bucket (src/ontology/member-projection.ts). The desktop only
+ * pulls that prefix; this module does the same and mirrors it into
+ * `workspace/signals/projections/{company}/{memberUid}/v1/`.
+ */
+export type ProjectionState = "missing" | "stale" | "ready";
+export declare const PROJECTION_STALE_AFTER_MS: number;
+export declare function memberProjectionPrefix(memberUid: string): string;
+export interface ProjectionRefreshResult {
+    state: ProjectionState;
+    /** Manifest watermark, else generatedAt, else "none". */
+    watermark: string;
+    entityCount: number;
+    error?: string;
+}
+export interface RefreshMemberProjectionInput {
+    company: string;
+    memberUid: string;
+    /** Reads one bucket-relative key from the company vault; null when absent. */
+    read: (key: string) => Promise<string | null>;
+    /** Guarded writer bound to hqRoot. */
+    write: (relPath: string, data: string) => void;
+    now: () => Date;
+}
+/** Pull the member's own projection prefix into workspace/signals/projections/. */
+export declare function refreshMemberProjection(input: RefreshMemberProjectionInput): Promise<ProjectionRefreshResult>;
+/**
+ * Seam for asking hq-pro to regenerate the member projection. hq-pro main
+ * (9f172092d, 2026-10-31) has no route that calls `exportMemberProjection`
+ * (src/ontology/member-projection.ts has no caller), so there is nothing to
+ * call yet. The signals engine is intended to be the only caller once such a
+ * route exists; until then this always reports `not-available`.
+ */
+export declare function triggerProjectionExport(_input: {
+    company: string;
+    memberUid: string;
+}): Promise<"not-available">;
+//# sourceMappingURL=projection.d.ts.map

package/dist/lib/signals/projection.js

@@ -0,0 +1,67 @@
+/**
+ * Member projection pull for the upload step (Hot-Signal Sync US-005).
+ *
+ * hq-pro writes each member's entity projection to
+ * `ontology/projections/members/{memberUid}/v1/{manifest.json,entities.jsonl}`
+ * in the company bucket (src/ontology/member-projection.ts). The desktop only
+ * pulls that prefix; this module does the same and mirrors it into
+ * `workspace/signals/projections/{company}/{memberUid}/v1/`.
+ */
+export const PROJECTION_STALE_AFTER_MS = 48 * 60 * 60 * 1000;
+export function memberProjectionPrefix(memberUid) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(memberUid))
+        throw new Error("invalid member uid");
+    return `ontology/projections/members/${memberUid}/v1/`;
+}
+/** Pull the member's own projection prefix into workspace/signals/projections/. */
+export async function refreshMemberProjection(input) {
+    const prefix = memberProjectionPrefix(input.memberUid);
+    const localDir = `workspace/signals/projections/${input.company}/${input.memberUid}/v1`;
+    let manifestText;
+    try {
+        manifestText = await input.read(`${prefix}manifest.json`);
+    }
+    catch (err) {
+        return { state: "missing", watermark: "none", entityCount: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    if (manifestText === null)
+        return { state: "missing", watermark: "none", entityCount: 0 };
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestText);
+    }
+    catch {
+        return { state: "missing", watermark: "none", entityCount: 0, error: "manifest.json is not JSON" };
+    }
+    let entities;
+    try {
+        entities = await input.read(`${prefix}entities.jsonl`);
+    }
+    catch (err) {
+        return { state: "stale", watermark: "none", entityCount: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    input.write(`${localDir}/manifest.json`, manifestText);
+    if (entities !== null)
+        input.write(`${localDir}/entities.jsonl`, entities);
+    const generatedAt = typeof manifest.generatedAt === "string" ? Date.parse(manifest.generatedAt) : NaN;
+    const fresh = Number.isFinite(generatedAt) && input.now().getTime() - generatedAt <= PROJECTION_STALE_AFTER_MS;
+    const state = manifest.state === "ready" && entities !== null && fresh ? "ready" : "stale";
+    const watermark = typeof manifest.watermark === "string" && manifest.watermark
+        ? manifest.watermark
+        : typeof manifest.generatedAt === "string" && manifest.generatedAt
+            ? manifest.generatedAt
+            : "none";
+    const entityCount = Number.isInteger(manifest.entityCount) ? manifest.entityCount : 0;
+    return { state, watermark, entityCount };
+}
+/**
+ * Seam for asking hq-pro to regenerate the member projection. hq-pro main
+ * (9f172092d, 2026-10-31) has no route that calls `exportMemberProjection`
+ * (src/ontology/member-projection.ts has no caller), so there is nothing to
+ * call yet. The signals engine is intended to be the only caller once such a
+ * route exists; until then this always reports `not-available`.
+ */
+export async function triggerProjectionExport(_input) {
+    return "not-available";
+}
+//# sourceMappingURL=projection.js.map

package/dist/lib/signals/reply.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The storyboarded bot replies for the signals job
+ * (companies/indigo/projects/hot-signal-sync/design/bot-replies.md).
+ *
+ * Every reply is plain prose followed by ONE `hq-block` fence whose JSON is on
+ * one line: `{"v":1,"blocks":[...]}`. Block kinds, tones and icons come from
+ * closed enums. Values come only from the run record; a value the record does
+ * not carry drops its row. Pure functions: no clock, no I/O.
+ */
+import type { LockedCompany, RunRecord, RunSummary } from "./engine.js";
+export declare const REPLY_BLOCK_KINDS: readonly ["keyValue", "callout", "badge", "progress", "decision"];
+export declare const REPLY_TONES: readonly ["neutral", "info", "success", "warning", "danger"];
+export declare const REPLY_ICONS: readonly ["check", "clock", "folder", "calendar"];
+export type ReplyTone = (typeof REPLY_TONES)[number];
+export type ReplyIcon = (typeof REPLY_ICONS)[number];
+export type ReplyBlock = {
+    kind: "keyValue";
+    items: {
+        key: string;
+        value: string;
+        icon?: ReplyIcon;
+    }[];
+} | {
+    kind: "callout";
+    tone: ReplyTone;
+    title?: string;
+    body: string;
+} | {
+    kind: "badge";
+    label: string;
+    tone: ReplyTone;
+    icon?: ReplyIcon;
+} | {
+    kind: "progress";
+    value: number;
+    label: string;
+    tone: ReplyTone;
+} | {
+    kind: "decision";
+    questionId: string;
+    question: string;
+    options: {
+        id: string;
+        label: string;
+        recommended?: boolean;
+    }[];
+    allowOther: boolean;
+};
+export interface FormattedReply {
+    /** The full message: prose, blank line, fence. */
+    text: string;
+    prose: string;
+    blocks: ReplyBlock[];
+    variant: "complete" | "catch-up" | "late-start" | "partial" | "failed" | "already-ran" | "skipped" | "running";
+}
+export interface RunReplyOptions {
+    /** IANA zone the times are written in (the job's zone). */
+    timeZone: string;
+    /** The job's name in words. Default "Morning signals". */
+    jobName?: string;
+    /** When the run was due (the fired job's `firedAt`); used by the catch-up line. */
+    scheduledFor?: string;
+    /** Display names per company slug; default title-cases the slug. */
+    companyNames?: Record<string, string>;
+    /**
+     * The bot scheduled one automatic retry at the record's `nextRetryAt`. Only
+     * then does a failure reply say when it tries again and offer to wait.
+     */
+    retryScheduled?: boolean;
+    /** This run was the automatic retry; a failure says no further retry follows. */
+    wasRetry?: boolean;
+}
+/** One fence, JSON on one line, not indented. */
+export declare function hqBlockFence(blocks: ReplyBlock[]): string;
+/** "6:02 AM" in the given zone. */
+export declare function timeInWords(iso: string | null | undefined, timeZone: string): string | null;
+/** "Mountain Time" from America/Denver: the long generic zone name, without "Standard"/"Daylight". */
+export declare function timezoneInWords(timeZone: string, at?: Date): string;
+/** The four keyValue rows, dropping any the record does not carry. */
+export declare function runCountItems(record: RunRecord, summary: RunSummary, opts: RunReplyOptions): {
+    key: string;
+    value: string;
+}[];
+/**
+ * The reply for one finished run of the signals job: run complete, catch-up,
+ * late start, finished with problems, or run failed (bot-replies.md sections
+ * 2, 2b and 3; status mapping from run-record-contract-v2.md).
+ *
+ * A failure offers "Wait for <time>" only when `retryScheduled` says the bot
+ * really scheduled the retry at the record's `nextRetryAt`. Without it (config
+ * and auth failures have no nextRetryAt, and an automatic retry is never
+ * retried again) the only option is "Try now".
+ */
+export declare function formatRunReply(record: RunRecord, summary: RunSummary, opts: RunReplyOptions): FormattedReply;
+/** Another run holds the company's lock (engine exit 3): nothing was started. */
+export declare function formatLockedReply(locked: LockedCompany, opts: RunReplyOptions): FormattedReply;
+/** A job that could not run the engine at all: the prose, then one danger callout with the reason. */
+export declare function formatJobErrorReply(prose: string, reason: string): FormattedReply;
+export interface JobCreatedInput {
+    /** Standard 5-field cron ("0 6 * * *") or the stored six-field cron(...) form. */
+    cron: string;
+    timezone: string;
+    name?: string;
+    companies?: string[];
+    /** A brief job exists on the same bot. */
+    hasBriefJob?: boolean;
+}
+/** "Every day at 6:00 AM" from a daily cron; null when the cron is not a plain daily or weekday time. */
+export declare function scheduleInWords(cron: string): string | null;
+/** The job-created reply (bot-replies.md section 1). The zone comes from the job record, in words. */
+export declare function formatJobCreatedReply(job: JobCreatedInput, timezoneWords?: string): FormattedReply;
+//# sourceMappingURL=reply.d.ts.map