@indigoai-us/hq-cli 5.108.0 → 5.108.2

package/dist/lib/mesh/live/daemon/presence.d.ts

@@ -0,0 +1,101 @@
+/**
+ * MQTT presence client for the work-mesh daemon.
+ *
+ * - Connects over WSS with mqtt.js using a SigV4-presigned URL
+ * - keepalive 15s, clean session, NO last-will
+ * - Publishes retained online ONLY to own presence topics
+ * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
+ * - Never subscribes to thread topics
+ * - Reconnects with jittered backoff 1s–60s on close / network change
+ */
+import { type IClientOptions, type MqttClient } from "mqtt";
+import { type Contract3Bundle, type CredentialsFetcher, type TimerHost } from "./credentials.js";
+export type MqttConnectionState = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+export interface PresencePayload {
+    v: 1;
+    status: "online" | "offline";
+    actorUid: string;
+    actorType: "human" | "agent";
+    at: string;
+}
+/** Structural mqtt client surface used by PresenceClient (test seam). */
+export interface MeshMqttClientLike {
+    on(event: string, handler: (...args: any[]) => void): unknown;
+    publish(topic: string, message: string | Buffer, opts: {
+        qos: 0 | 1 | 2;
+        retain?: boolean;
+    }, callback?: (err?: Error | null) => void): unknown;
+    end(force?: boolean, opts?: unknown, cb?: () => void): unknown;
+    /** Guard: PresenceClient must never call subscribe. */
+    subscribe?: unknown;
+}
+export type MqttConnectFn = (url: string, opts: IClientOptions) => MeshMqttClientLike;
+export interface PresenceClientOptions {
+    fetchCredentials: CredentialsFetcher;
+    mqttConnect?: MqttConnectFn;
+    timers?: TimerHost;
+    random?: () => number;
+    baseBackoffMs?: number;
+    maxBackoffMs?: number;
+    /** Invoked when online is (re)published after connect. */
+    onOnline?: (companies: string[]) => void;
+    onState?: (state: MqttConnectionState) => void;
+    onError?: (err: unknown) => void;
+    now?: () => Date;
+}
+/** Full-jitter capped exponential backoff (1s base → 60s cap by default). */
+export declare function backoffDelayMs(attempt: number, baseMs: number, maxMs: number, random: () => number): number;
+export declare function buildPresencePayload(input: {
+    status: "online" | "offline";
+    actorUid: string;
+    actorType: "human" | "agent";
+    at?: string;
+}): PresencePayload;
+/**
+ * Assert a topic is an own presence topic for the given actor.
+ * PresenceClient refuses to publish anything else.
+ */
+export declare function isOwnPresenceTopic(topic: string, actorUid: string, companyUids: ReadonlySet<string>): boolean;
+export declare class PresenceClient {
+    private readonly options;
+    private client;
+    private bundle;
+    private state;
+    private attempt;
+    private reconnectHandle;
+    private stopped;
+    private generation;
+    private publishedTopics;
+    private readonly mqttConnect;
+    private readonly timers;
+    private readonly random;
+    private readonly baseBackoffMs;
+    private readonly maxBackoffMs;
+    private readonly renewal;
+    private readonly now;
+    constructor(options: PresenceClientOptions);
+    getConnectionState(): MqttConnectionState;
+    getBundle(): Contract3Bundle | null;
+    /** Topics this client has published to (for doctor / tests). */
+    getPublishedTopics(): readonly string[];
+    private setState;
+    start(): Promise<void>;
+    /**
+     * Graceful stop: disconnect cleanly (MQTT DISCONNECT so the broker emits
+     * the lifecycle event immediately). Offline is published server-side —
+     * the client must not overwrite retained presence with offline.
+     */
+    stop(): Promise<void>;
+    /** Force a reconnect cycle (network change / sleep-wake). */
+    reconnectNow(): void;
+    private teardownClient;
+    private onCredentialsRenewed;
+    private connectOnce;
+    /** Publish retained online to every own presence topic (connect / renew). */
+    private publishAll;
+    private scheduleReconnect;
+    private clearReconnect;
+}
+/** Production mqtt.connect wrapper (typed). */
+export declare function defaultMqttConnect(url: string, opts: IClientOptions): MqttClient;
+//# sourceMappingURL=presence.d.ts.map

package/dist/lib/mesh/live/daemon/presence.js

@@ -0,0 +1,250 @@
+/**
+ * MQTT presence client for the work-mesh daemon.
+ *
+ * - Connects over WSS with mqtt.js using a SigV4-presigned URL
+ * - keepalive 15s, clean session, NO last-will
+ * - Publishes retained online ONLY to own presence topics
+ * - Offline is server-only (IoT lifecycle → PresenceIngestFunction)
+ * - Never subscribes to thread topics
+ * - Reconnects with jittered backoff 1s–60s on close / network change
+ */
+import mqtt from "mqtt";
+import { CredentialRenewalManager, MQTT_KEEPALIVE_SECONDS, realTimerHost, } from "./credentials.js";
+import { presignIotWssUrl } from "./presign.js";
+/** Full-jitter capped exponential backoff (1s base → 60s cap by default). */
+export function backoffDelayMs(attempt, baseMs, maxMs, random) {
+    const cap = Math.min(maxMs, baseMs * 2 ** attempt);
+    return Math.max(0, random() * cap);
+}
+export function buildPresencePayload(input) {
+    return {
+        v: 1,
+        status: input.status,
+        actorUid: input.actorUid,
+        actorType: input.actorType,
+        at: input.at ?? new Date().toISOString(),
+    };
+}
+/**
+ * Assert a topic is an own presence topic for the given actor.
+ * PresenceClient refuses to publish anything else.
+ */
+export function isOwnPresenceTopic(topic, actorUid, companyUids) {
+    const m = /^hq\/([^/]+)\/presence\/([^/]+)$/.exec(topic);
+    if (!m)
+        return false;
+    const companyUid = m[1];
+    const topicActor = m[2];
+    return topicActor === actorUid && companyUids.has(companyUid);
+}
+export class PresenceClient {
+    options;
+    client = null;
+    bundle = null;
+    state = "idle";
+    attempt = 0;
+    reconnectHandle = null;
+    stopped = false;
+    generation = 0;
+    publishedTopics = [];
+    mqttConnect;
+    timers;
+    random;
+    baseBackoffMs;
+    maxBackoffMs;
+    renewal;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.mqttConnect =
+            options.mqttConnect ??
+                ((url, opts) => mqtt.connect(url, opts));
+        this.timers = options.timers ?? realTimerHost;
+        this.random = options.random ?? Math.random;
+        this.baseBackoffMs = options.baseBackoffMs ?? 1_000;
+        this.maxBackoffMs = options.maxBackoffMs ?? 60_000;
+        this.now = options.now ?? (() => new Date());
+        this.renewal = new CredentialRenewalManager(options.fetchCredentials, (bundle) => void this.onCredentialsRenewed(bundle), (err) => options.onError?.(err), this.timers);
+    }
+    getConnectionState() {
+        return this.state;
+    }
+    getBundle() {
+        return this.bundle;
+    }
+    /** Topics this client has published to (for doctor / tests). */
+    getPublishedTopics() {
+        return this.publishedTopics;
+    }
+    setState(state) {
+        if (this.state === state)
+            return;
+        this.state = state;
+        this.options.onState?.(state);
+    }
+    async start() {
+        if (this.stopped)
+            throw new Error("PresenceClient already stopped");
+        this.setState("connecting");
+        await this.connectOnce();
+    }
+    /**
+     * Graceful stop: disconnect cleanly (MQTT DISCONNECT so the broker emits
+     * the lifecycle event immediately). Offline is published server-side —
+     * the client must not overwrite retained presence with offline.
+     */
+    async stop() {
+        this.stopped = true;
+        this.generation += 1;
+        this.renewal.stop();
+        this.clearReconnect();
+        this.teardownClient(false);
+        this.setState("closed");
+    }
+    /** Force a reconnect cycle (network change / sleep-wake). */
+    reconnectNow() {
+        if (this.stopped)
+            return;
+        this.attempt = 0;
+        this.clearReconnect();
+        void this.connectOnce();
+    }
+    teardownClient(force) {
+        const client = this.client;
+        if (!client)
+            return;
+        this.client = null;
+        try {
+            if (force) {
+                client.end(true);
+            }
+            else {
+                client.end(false);
+            }
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    async onCredentialsRenewed(bundle) {
+        this.bundle = bundle;
+        if (this.stopped)
+            return;
+        // Reconnect with the new presigned URL, then re-publish online.
+        this.attempt = 0;
+        await this.connectOnce();
+    }
+    async connectOnce() {
+        if (this.stopped)
+            return;
+        this.clearReconnect();
+        const generation = ++this.generation;
+        this.teardownClient(true);
+        try {
+            if (!this.bundle) {
+                this.bundle = await this.options.fetchCredentials();
+                this.renewal.schedule(this.bundle);
+            }
+            const bundle = this.bundle;
+            const url = presignIotWssUrl(bundle.credentials, bundle.iotEndpoint, bundle.region, this.now());
+            if (this.stopped || generation !== this.generation)
+                return;
+            let client;
+            try {
+                client = this.mqttConnect(url, {
+                    clientId: bundle.clientId,
+                    clean: true,
+                    reconnectPeriod: 0,
+                    keepalive: MQTT_KEEPALIVE_SECONDS,
+                    protocolVersion: 4,
+                    // No last-will: one connection serves several companies.
+                });
+            }
+            catch (err) {
+                this.options.onError?.(err);
+                this.scheduleReconnect();
+                return;
+            }
+            this.client = client;
+            client.on("connect", () => {
+                if (this.stopped || generation !== this.generation)
+                    return;
+                this.attempt = 0;
+                this.setState("connected");
+                void this.publishAll("online").then(() => {
+                    this.options.onOnline?.(bundle.companies.map((c) => c.companyUid));
+                });
+            });
+            client.on("error", (err) => {
+                if (this.stopped || generation !== this.generation)
+                    return;
+                this.options.onError?.(err);
+            });
+            client.on("close", () => {
+                if (this.stopped || generation !== this.generation)
+                    return;
+                this.scheduleReconnect();
+            });
+        }
+        catch (err) {
+            this.options.onError?.(err);
+            this.scheduleReconnect();
+        }
+    }
+    /** Publish retained online to every own presence topic (connect / renew). */
+    async publishAll(status) {
+        const bundle = this.bundle;
+        const client = this.client;
+        if (!bundle || !client)
+            return;
+        const companyUids = new Set(bundle.companies.map((c) => c.companyUid));
+        const payload = JSON.stringify(buildPresencePayload({
+            status,
+            actorUid: bundle.actorUid,
+            actorType: bundle.actorType,
+            at: this.now().toISOString(),
+        }));
+        for (const company of bundle.companies) {
+            const topic = company.presenceTopic;
+            if (!isOwnPresenceTopic(topic, bundle.actorUid, companyUids)) {
+                this.options.onError?.(new Error(`refusing to publish to non-presence topic`));
+                continue;
+            }
+            await new Promise((resolve) => {
+                try {
+                    client.publish(topic, payload, { qos: 1, retain: true }, () => resolve());
+                    if (!this.publishedTopics.includes(topic)) {
+                        this.publishedTopics.push(topic);
+                    }
+                }
+                catch (err) {
+                    this.options.onError?.(err);
+                    resolve();
+                }
+            });
+        }
+    }
+    scheduleReconnect() {
+        if (this.stopped)
+            return;
+        this.setState("reconnecting");
+        this.clearReconnect();
+        const delay = backoffDelayMs(this.attempt, this.baseBackoffMs, this.maxBackoffMs, this.random);
+        this.attempt += 1;
+        this.reconnectHandle = this.timers.setTimeout(() => {
+            this.reconnectHandle = null;
+            void this.connectOnce();
+        }, delay);
+    }
+    clearReconnect() {
+        if (this.reconnectHandle !== null) {
+            this.timers.clearTimeout(this.reconnectHandle);
+            this.reconnectHandle = null;
+        }
+    }
+}
+/** Production mqtt.connect wrapper (typed). */
+export function defaultMqttConnect(url, opts) {
+    return mqtt.connect(url, opts);
+}
+//# sourceMappingURL=presence.js.map

package/dist/lib/mesh/live/daemon/presign.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SigV4 query-presign of wss://{endpoint}/mqtt for AWS IoT Core.
+ *
+ * Approach mirrors hq-desktop-app packages/core/src/mesh/presign.ts:
+ * sign WITHOUT X-Amz-Security-Token, then append the session token after.
+ */
+export interface IotCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    expiration?: string;
+}
+export declare function hex(bytes: Buffer | Uint8Array): string;
+export declare function rfc3986Encode(value: string): string;
+export declare function amzDateOf(now: Date): string;
+/** Presign a WSS MQTT URL for IoT Core using STS credentials. */
+export declare function presignIotWssUrl(creds: IotCredentials, endpoint: string, region: string, now?: Date): string;
+//# sourceMappingURL=presign.d.ts.map

package/dist/lib/mesh/live/daemon/presign.js

@@ -0,0 +1,65 @@
+/**
+ * SigV4 query-presign of wss://{endpoint}/mqtt for AWS IoT Core.
+ *
+ * Approach mirrors hq-desktop-app packages/core/src/mesh/presign.ts:
+ * sign WITHOUT X-Amz-Security-Token, then append the session token after.
+ */
+import { createHash, createHmac } from "node:crypto";
+const IOT_SERVICE = "iotdevicegateway";
+const CANONICAL_URI = "/mqtt";
+const ALGORITHM = "AWS4-HMAC-SHA256";
+export function hex(bytes) {
+    return Buffer.from(bytes).toString("hex");
+}
+export function rfc3986Encode(value) {
+    return encodeURIComponent(value).replace(/[!*'()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+export function amzDateOf(now) {
+    return now
+        .toISOString()
+        .replace(/[:-]|\.\d{3}/g, "")
+        .replace(/Z?$/, "Z");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data, "utf8").digest();
+}
+function sha256Hex(data) {
+    return createHash("sha256").update(data, "utf8").digest("hex");
+}
+/** Presign a WSS MQTT URL for IoT Core using STS credentials. */
+export function presignIotWssUrl(creds, endpoint, region, now = new Date()) {
+    const amzDate = amzDateOf(now);
+    const dateStamp = amzDate.slice(0, 8);
+    const scope = `${dateStamp}/${region}/${IOT_SERVICE}/aws4_request`;
+    const canonicalQuery = `X-Amz-Algorithm=${rfc3986Encode(ALGORITHM)}` +
+        `&X-Amz-Credential=${rfc3986Encode(`${creds.accessKeyId}/${scope}`)}` +
+        `&X-Amz-Date=${rfc3986Encode(amzDate)}` +
+        `&X-Amz-SignedHeaders=host`;
+    const canonicalHeaders = `host:${endpoint}\n`;
+    const canonicalRequest = [
+        "GET",
+        CANONICAL_URI,
+        canonicalQuery,
+        canonicalHeaders,
+        "host",
+        sha256Hex(""),
+    ].join("\n");
+    const stringToSign = [
+        ALGORITHM,
+        amzDate,
+        scope,
+        sha256Hex(canonicalRequest),
+    ].join("\n");
+    const kDate = hmac(`AWS4${creds.secretAccessKey}`, dateStamp);
+    const kRegion = hmac(kDate, region);
+    const kService = hmac(kRegion, IOT_SERVICE);
+    const kSigning = hmac(kService, "aws4_request");
+    const signature = hex(hmac(kSigning, stringToSign));
+    let url = `wss://${endpoint}${CANONICAL_URI}?${canonicalQuery}` +
+        `&X-Amz-Signature=${signature}`;
+    if (creds.sessionToken) {
+        url += `&X-Amz-Security-Token=${rfc3986Encode(creds.sessionToken)}`;
+    }
+    return url;
+}
+//# sourceMappingURL=presign.js.map

package/dist/lib/mesh/live/daemon/run.d.ts

@@ -0,0 +1,74 @@
+/**
+ * hq mesh daemon run — single-instance resident process.
+ *
+ * - pid lock at ~/.hq/work-mesh/daemon/pid
+ * - fs.watch spool + 2s debounce; flush at least every 10s (US-008 path)
+ * - replay context outbox
+ * - board.md refresh for bound sessions ≤ every 60s
+ * - MQTT presence (contract-3)
+ * - SIGTERM/SIGINT: flush once more, MQTT DISCONNECT (server derives offline), exit
+ */
+import { type FlushSummary } from "../flush.js";
+import { type CredentialsFetcher, type TimerHost } from "./credentials.js";
+import { type PidLockDeps } from "./pid-lock.js";
+import { PresenceClient, type MqttConnectFn } from "./presence.js";
+import { TranscriptWatcher, type TranscriptFs } from "./transcript-watch.js";
+export declare const SPOOL_DEBOUNCE_MS = 2000;
+export declare const FLUSH_INTERVAL_MS = 10000;
+export interface DaemonRunDeps {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    meshRoot?: string;
+    workContextRoot?: string;
+    pidLock?: PidLockDeps;
+    timers?: TimerHost;
+    fetchCredentials?: CredentialsFetcher;
+    mqttConnect?: MqttConnectFn;
+    /** Injected flush (tests). */
+    flush?: () => Promise<FlushSummary>;
+    /** Injected outbox replay (tests). */
+    replayOutbox?: () => Promise<{
+        delivered: number;
+        queued: number;
+        quarantined: number;
+    }>;
+    /** Injected board refresh (tests). */
+    refreshBoards?: () => Promise<{
+        refreshed: number;
+        skipped: number;
+        errors: number;
+    }>;
+    /** When false, skip MQTT (flush-only mode for tests). */
+    enablePresence?: boolean;
+    /** When false, skip transcript-watch lane (tests). Default true. */
+    enableTranscriptWatch?: boolean;
+    /** Injectable transcript fs (tests). */
+    transcriptFs?: TranscriptFs;
+    /** HQ tree root for deterministic cwd→company/project mapping. */
+    hqRoot?: string;
+    /** Process signal registration seam. */
+    processEvents?: Pick<NodeJS.Process, "once" | "on" | "off">;
+    exit?: (code: number) => void;
+    /** Token provider (tests). */
+    getToken?: () => Promise<string>;
+    log?: (dir: string, line: string) => void;
+    /** Stop after this many ms (tests). */
+    runForMs?: number;
+    random?: () => number;
+    now?: () => Date;
+}
+export interface DaemonHandle {
+    stop: () => Promise<void>;
+    dir: string;
+    presence: PresenceClient | null;
+    /** Hook-activity map shared with the transcript watcher (US-018). */
+    lastHookEventAt: Map<string, number>;
+    /** Transcript watcher instance when enabled. */
+    transcriptWatcher: TranscriptWatcher | null;
+}
+/**
+ * Start the daemon. Resolves once the process is running (lock held, loops armed).
+ * Call handle.stop() or send SIGTERM for graceful shutdown.
+ */
+export declare function runMeshDaemon(deps?: DaemonRunDeps): Promise<DaemonHandle>;
+//# sourceMappingURL=run.d.ts.map