@indigoai-us/hq-cli 5.345.191 → 5.345.194

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

@@ -0,0 +1,202 @@
+import { localDate } from "./local-date.js";
+import { type LockTakeover } from "./run-lock.js";
+import { type UploadDeps } from "./steps/upload.js";
+import { type SignalsRunAlertSenders } from "./failure-alert.js";
+import type { RaiseSignalsFailureAlertsResult } from "../hot-channels/alert.js";
+import type { ErrorKind, HotChannelSyncFn, SignalsStep, SpawnSyncFn, StepFailure, StepName, StepStatus } from "./steps/types.js";
+import type { AdapterFlagReader } from "./adapters-catalog.js";
+export declare const SIGNALS_TRIGGERS: readonly ["job", "chat", "manual", "brief"];
+export type SignalsTrigger = (typeof SIGNALS_TRIGGERS)[number];
+export declare const SIGNALS_STEP_CHOICES: readonly ["garden", "extract", "adapters", "upload", "all"];
+export type SignalsStepChoice = (typeof SIGNALS_STEP_CHOICES)[number];
+export declare const STEP_ORDER: StepName[];
+export declare const RUN_RECORD_SCHEMA_VERSION: 2;
+/** A failed run with a transient error is due for a retry this long after it finished. */
+export declare const RETRY_DELAY_MS: number;
+export interface StepRecord {
+    name: StepName;
+    itemsIn: number;
+    itemsOut: number;
+    durationMs: number;
+    status: StepStatus;
+    skippedReason?: string;
+    error?: string;
+    /** The step's own error detail (reconnect, signed-out, ...). The record-level errorKind is the coarse v2 kind. */
+    errorKind?: ErrorKind;
+    modelTurns?: number;
+    estimatedSpendUsd?: number;
+    byAdapter?: Record<string, number>;
+    itemsInByAdapter?: Record<string, number>;
+    tokenLevels?: Record<string, string>;
+    adapterSkips?: Record<string, string>;
+    uploaded?: {
+        count: number;
+        bytes: number;
+    };
+    plan?: string[];
+    detail?: Record<string, unknown>;
+    skipped?: number;
+    review?: number;
+    failures?: StepFailure[];
+    skippedItems?: {
+        file: string;
+        reason: string;
+    }[];
+    rejectedCandidates?: number;
+}
+/** "dry-run" is only ever returned in memory; a dry run writes no record. */
+export type RunStatus = "running" | "complete" | "partial" | "failed" | "skipped" | "dry-run";
+export type RunErrorKind = "transient" | "config" | "auth";
+export interface RunRecord {
+    schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;
+    company: string;
+    startedAt: string;
+    finishedAt: string | null;
+    trigger: SignalsTrigger;
+    pid: number;
+    catchUp: boolean;
+    dryRun: boolean;
+    status: RunStatus;
+    /** prefs-off, late-start, ... on a skipped record; else null. */
+    skipReason: string | null;
+    /** v1 name of skipReason, kept for older readers. */
+    skippedReason?: string;
+    currentStep: StepName | null;
+    steps: StepRecord[];
+    maxBudgetUsd: number;
+    maxTurns: number;
+    /** Set when a job run finishes complete or partial; carried forward by every later run that day. */
+    jobRanAt: string | null;
+    /** On failed with errorKind transient: finishedAt + 15 minutes. */
+    nextRetryAt: string | null;
+    errorKind: RunErrorKind | null;
+    /** One plain-language sentence on failed and partial records. */
+    failureReason: string | null;
+    /** late-start, step-failed:{step}, step-partial:{step}, or null. */
+    partialReason: string | null;
+    /** v1 name of partialReason, kept for older readers. */
+    partial: string | null;
+    /** In-memory only: this call found the day's job already ran and did nothing. */
+    alreadyRanToday: boolean;
+    counts: {
+        sourcesIn: number;
+        signalsOut: number;
+    };
+    lockTakeover?: LockTakeover;
+}
+/** A company another run is holding the lock for. Nothing was started for it. */
+export interface LockedCompany {
+    company: string;
+    status: "running";
+    startedAt: string;
+    trigger: string;
+}
+export interface RunSummaryEntry {
+    company: string;
+    status: RunStatus;
+    trigger: SignalsTrigger;
+    /** The record's catchUp flag, so it always matches the company's record. */
+    catchUp: boolean;
+    finishedAt: string | null;
+    skipReason?: string;
+    skippedReason?: string;
+    itemsIn: number;
+    itemsOut: number;
+    estimatedSpendUsd: number;
+}
+export interface RunSummary {
+    schemaVersion: typeof RUN_RECORD_SCHEMA_VERSION;
+    date: string;
+    trigger: SignalsTrigger;
+    companies: RunSummaryEntry[];
+    totals: {
+        itemsIn: number;
+        itemsOut: number;
+        estimatedSpendUsd: number;
+    };
+    status: RunStatus;
+    finishedAt: string;
+}
+export interface RunSignalsResult {
+    date: string;
+    records: RunRecord[];
+    locked: LockedCompany[];
+    /** Summary of this call's companies. summary.json on disk holds every company's latest entry. */
+    summary: RunSummary;
+    /**
+     * The signals-failure alert result per company whose run landed sources and
+     * produced no signals (US-018). Omitted when no alert sender was given.
+     */
+    alerts?: Record<string, RaiseSignalsFailureAlertsResult>;
+}
+export interface RunSignalsOptions {
+    hqRoot: string;
+    company?: string;
+    dryRun?: boolean;
+    step?: SignalsStepChoice;
+    trigger?: SignalsTrigger;
+    force?: boolean;
+    catchUp?: boolean;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    now?: () => Date;
+    spawn?: SpawnSyncFn;
+    hotChannelSync?: HotChannelSyncFn;
+    /** Adapter ids the adapters step gates and syncs. Defaults to the builtin registry. */
+    registeredAdapterIds?: readonly string[];
+    uploadDeps?: Partial<UploadDeps>;
+    /**
+     * Company flag reader for the adapters step's gate. Unset in production:
+     * the hot-channel sync then reads the adapter flags through the shared
+     * hq-flags evaluator with the signed-in session.
+     */
+    isFlagOn?: AdapterFlagReader;
+    steps?: Partial<Record<StepName, SignalsStep>>;
+    /**
+     * Where the signals-failure alert goes (US-018): after the run, a company
+     * whose extract step read sources and produced nothing (or failed after new
+     * landings) alerts the owner through the ledger alert path, deduped hourly.
+     * Unset = no alert check.
+     */
+    signalsAlert?: SignalsRunAlertSenders;
+    /** Lock liveness check; defaults to process.kill(pid, 0). */
+    isPidAlive?: (pid: number) => boolean;
+    /**
+     * Source items (`sources/<channel>/<file>.md`) to process again: the extract
+     * step re-queues each with the worklist's `--redo` before listing its
+     * channel. Needs `company`.
+     */
+    redo?: readonly string[];
+}
+/** Bad input from the caller (company slug, missing company): exit 2. */
+export declare class SignalsUsageError extends Error {
+    constructor(message: string);
+}
+/** Broken local setup (missing or failing knowledge-prefs.sh): errorKind config. */
+export declare class SignalsConfigError extends Error {
+    constructor(message: string);
+}
+export declare const defaultSpawn: SpawnSyncFn;
+export { localDate };
+export declare function runRecordRel(date: string, company: string): string;
+export declare function summaryRel(date: string): string;
+/** Companies under companies/ that are also listed in companies/manifest.yaml. */
+export declare function listCompanies(hqRoot: string): string[];
+/** Reads one knowledge preference. Throws SignalsConfigError when the script is missing or fails. */
+export declare function readPref(hqRoot: string, company: string, field: string, spawn: SpawnSyncFn): boolean;
+/** Coarse v2 kind for a step's detailed kind. */
+export declare function toRunErrorKind(kind: ErrorKind | undefined): RunErrorKind;
+/** Fills the v2 outcome fields of a finished record from its steps. */
+export declare function finalizeRecord(record: RunRecord, input: {
+    lateStart: boolean;
+    lateStartHour: number;
+    finishedAt: Date;
+}): void;
+export declare function runSignals(opts: RunSignalsOptions): Promise<RunSignalsResult>;
+/**
+ * Exit code for `hq signals run`: 1 when a company failed (a job that already
+ * ran today does not count), else 3 when another run held a company's lock,
+ * else 0 (complete, partial, skipped, already ran).
+ */
+export declare function signalsExitCode(result: RunSignalsResult): 0 | 1 | 3;
+//# sourceMappingURL=engine.d.ts.map