@indigoai-us/hq-cli 5.115.6 → 5.116.0

package/dist/lib/agent-kit/paths.d.ts

@@ -0,0 +1,42 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ */
+export declare const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export declare const HOST_KEY_NAME = "host-key";
+export declare const HOST_KEY_PUB_NAME = "host-key.pub";
+export declare const MACHINE_CREDS_NAME = "machine-creds.json";
+export declare const KIT_CONFIG_NAME = "kit.json";
+export declare const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export type KitComponent = "sync" | "mesh" | "inbox";
+export declare const KIT_COMPONENTS: readonly KitComponent[];
+export interface AgentKitPaths {
+    home: string;
+    agentDir: string;
+    hostKeyPath: string;
+    hostKeyPubPath: string;
+    machineCredsPath: string;
+    kitConfigPath: string;
+    stateDir: string;
+    inboxDir: string;
+    logsDir: string;
+    skillsDir: string;
+    lastHeartbeatPath: string;
+}
+export declare function agentDir(home?: string, env?: NodeJS.ProcessEnv): string;
+export declare function agentKitPaths(home?: string, env?: NodeJS.ProcessEnv): AgentKitPaths;
+export declare function componentStatePath(paths: Pick<AgentKitPaths, "stateDir">, component: KitComponent): string;
+export declare function serviceLogPath(paths: Pick<AgentKitPaths, "logsDir">, service: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/lib/agent-kit/paths.js

@@ -0,0 +1,56 @@
+/**
+ * On-host layout for an external agent (api-contract v1, "Host files"):
+ *
+ *   ~/.hq-agent/host-key             Ed25519 private key, PKCS8 PEM, 0600
+ *   ~/.hq-agent/host-key.pub         Ed25519 public key, SPKI PEM
+ *   ~/.hq-agent/machine-creds.json   credentials + hostKeyPath/companySlug/apiBaseUrl, 0600
+ *   ~/.hq-agent/kit.json             kit install settings (hq root, intervals)
+ *   ~/.hq-agent/state/               component-{sync,mesh,inbox}, last-heartbeat.json
+ *   ~/.hq-agent/inbox/               mirrored inbox items (one JSON per message)
+ *   ~/.hq-agent/logs/*.log           one log per kit service
+ *   ~/.hq-agent/skills/<name>/SKILL.md
+ *
+ * `HQ_AGENT_DIR` relocates the whole tree (tests, containers). The creds file
+ * additionally honours `HQ_MACHINE_CREDS_FILE`, the override hq-cloud reads,
+ * so a kit pointed at a custom creds path and hq-cloud's mint agree.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+export const AGENT_DIR_ENV = "HQ_AGENT_DIR";
+export const HOST_KEY_NAME = "host-key";
+export const HOST_KEY_PUB_NAME = "host-key.pub";
+export const MACHINE_CREDS_NAME = "machine-creds.json";
+export const KIT_CONFIG_NAME = "kit.json";
+export const LAST_HEARTBEAT_NAME = "last-heartbeat.json";
+export const KIT_COMPONENTS = ["sync", "mesh", "inbox"];
+export function agentDir(home = os.homedir(), env = process.env) {
+    const override = env[AGENT_DIR_ENV]?.trim();
+    if (override)
+        return override;
+    return path.join(home, ".hq-agent");
+}
+export function agentKitPaths(home = os.homedir(), env = process.env) {
+    const dir = agentDir(home, env);
+    const credsOverride = env.HQ_MACHINE_CREDS_FILE?.trim();
+    const stateDir = path.join(dir, "state");
+    return {
+        home,
+        agentDir: dir,
+        hostKeyPath: path.join(dir, HOST_KEY_NAME),
+        hostKeyPubPath: path.join(dir, HOST_KEY_PUB_NAME),
+        machineCredsPath: credsOverride || path.join(dir, MACHINE_CREDS_NAME),
+        kitConfigPath: path.join(dir, KIT_CONFIG_NAME),
+        stateDir,
+        inboxDir: path.join(dir, "inbox"),
+        logsDir: path.join(dir, "logs"),
+        skillsDir: path.join(dir, "skills"),
+        lastHeartbeatPath: path.join(stateDir, LAST_HEARTBEAT_NAME),
+    };
+}
+export function componentStatePath(paths, component) {
+    return path.join(paths.stateDir, `component-${component}`);
+}
+export function serviceLogPath(paths, service) {
+    return path.join(paths.logsDir, `${service}.log`);
+}
+//# sourceMappingURL=paths.js.map

package/dist/lib/agent-kit/run/heartbeat.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Kit service: heartbeat reporter.
+ *
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with
+ * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
+ * external-agent body from api-contract v1, mirroring the hosted box's
+ * hq-agent-heartbeat.sh (which folds per-component stamp files into one
+ * beat). Component values are read from the stamps the other three services
+ * write; a missing or stale stamp reports `error`, never silence.
+ *
+ * The last successful beat is recorded at state/last-heartbeat.json so
+ * `hq agent probe` can report its age.
+ */
+import { type ComponentStatus } from "../creds.js";
+import type { KitLogger } from "../log.js";
+import { type AgentKitPaths, type KitComponent } from "../paths.js";
+/** A component stamp older than this reads as error. */
+export declare const COMPONENT_STALE_AFTER_MS: Record<KitComponent, number>;
+export interface HeartbeatBody {
+    components: Record<KitComponent, ComponentStatus>;
+    cliVersion: string;
+    hostInfo: {
+        os: string;
+        arch: string;
+        hostname: string;
+        cliVersion: string;
+    };
+}
+export declare function buildHeartbeatBody(paths: Pick<AgentKitPaths, "stateDir">, now?: () => Date, hostInfo?: HeartbeatBody["hostInfo"]): HeartbeatBody;
+export interface LastHeartbeat {
+    at: string;
+    components: Record<KitComponent, ComponentStatus>;
+    status: number;
+}
+export declare function writeLastHeartbeat(paths: Pick<AgentKitPaths, "stateDir" | "lastHeartbeatPath">, record: LastHeartbeat): void;
+export declare function readLastHeartbeat(paths: Pick<AgentKitPaths, "lastHeartbeatPath">): LastHeartbeat | null;
+export interface HeartbeatDeps {
+    paths: AgentKitPaths;
+    agentUid: string;
+    apiBaseUrl: string;
+    intervalMs: number;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    post?: (token: string, body: HeartbeatBody) => Promise<number>;
+    now?: () => Date;
+    sleep?: (ms: number) => Promise<void>;
+    maxBeats?: number;
+}
+export declare function defaultHeartbeatPost(agentUid: string, apiBaseUrl: string): (token: string, body: HeartbeatBody) => Promise<number>;
+export declare function beatOnce(deps: HeartbeatDeps): Promise<boolean>;
+export declare function runHeartbeatLoop(deps: HeartbeatDeps): Promise<void>;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/lib/agent-kit/run/heartbeat.js

@@ -0,0 +1,97 @@
+/**
+ * Kit service: heartbeat reporter.
+ *
+ * Every 60 s POST /v1/agents/{uid}/heartbeat with
+ * `{ components: { sync, mesh, inbox }, cliVersion, hostInfo }` — the
+ * external-agent body from api-contract v1, mirroring the hosted box's
+ * hq-agent-heartbeat.sh (which folds per-component stamp files into one
+ * beat). Component values are read from the stamps the other three services
+ * write; a missing or stale stamp reports `error`, never silence.
+ *
+ * The last successful beat is recorded at state/last-heartbeat.json so
+ * `hq agent probe` can report its age.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import { CLI_VERSION } from "../../../cli-version.js";
+import { vaultApiFetch } from "../../../utils/vault-api.js";
+import { readComponentStatus } from "../creds.js";
+import { KIT_COMPONENTS } from "../paths.js";
+/** A component stamp older than this reads as error. */
+export const COMPONENT_STALE_AFTER_MS = {
+    sync: 3 * 60 * 60_000, // sync passes every 5 min; three hours of silence is real trouble
+    mesh: 3 * 60_000,
+    inbox: 3 * 60_000,
+};
+export function buildHeartbeatBody(paths, now = () => new Date(), hostInfo) {
+    const components = {};
+    for (const c of KIT_COMPONENTS) {
+        components[c] = readComponentStatus(paths, c, COMPONENT_STALE_AFTER_MS[c], now).status;
+    }
+    return {
+        components,
+        cliVersion: CLI_VERSION,
+        hostInfo: hostInfo ?? {
+            os: `${os.platform()} ${os.release()}`,
+            arch: os.arch(),
+            hostname: os.hostname(),
+            cliVersion: CLI_VERSION,
+        },
+    };
+}
+export function writeLastHeartbeat(paths, record) {
+    fs.mkdirSync(paths.stateDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(paths.lastHeartbeatPath, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+export function readLastHeartbeat(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(paths.lastHeartbeatPath, "utf8"));
+        return typeof raw.at === "string" ? raw : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function defaultHeartbeatPost(agentUid, apiBaseUrl) {
+    return async (token, body) => {
+        const res = await vaultApiFetch({
+            token,
+            baseUrl: apiBaseUrl,
+            path: `/v1/agents/${encodeURIComponent(agentUid)}/heartbeat`,
+            method: "POST",
+            body: body,
+        });
+        return res.status;
+    };
+}
+export async function beatOnce(deps) {
+    const now = deps.now ?? (() => new Date());
+    const post = deps.post ?? defaultHeartbeatPost(deps.agentUid, deps.apiBaseUrl);
+    const body = buildHeartbeatBody(deps.paths, now);
+    try {
+        const token = await deps.getToken();
+        const status = await post(token, body);
+        const ok = status >= 200 && status < 300;
+        if (ok) {
+            writeLastHeartbeat(deps.paths, { at: now().toISOString(), components: body.components, status });
+        }
+        deps.log(ok ? "info" : "warn", `heartbeat ${status} sync=${body.components.sync} mesh=${body.components.mesh} inbox=${body.components.inbox}`);
+        return ok;
+    }
+    catch (err) {
+        deps.log("error", `heartbeat failed: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+export async function runHeartbeatLoop(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let beats = 0;
+    for (;;) {
+        await beatOnce(deps);
+        beats += 1;
+        if (deps.maxBeats !== undefined && beats >= deps.maxBeats)
+            return;
+        await sleep(deps.intervalMs);
+    }
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/lib/agent-kit/run/inbox.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Kit service: inbox poller.
+ *
+ * Mirrors the poll half of the hosted box's hq-agent-inbox.sh: every
+ * `inboxPollMs` GET /v1/agents/{uid}/inbox, take `.messages[]`, and stamp
+ * `component-inbox` ok on a 200 (any other status → error, token re-minted
+ * on the next pass). The hosted watcher then dispatches each item to a
+ * provider and acks it; an external bot brings its own brain, so this
+ * service only MIRRORS: each new item is written once to
+ * ~/.hq-agent/inbox/<id>.json and appended to inbox.jsonl for the bot to
+ * consume, and the work-mesh conversation cache is refreshed so `hq dm`
+ * and the skills see the same state.
+ *
+ * Acking is opt-in (kit.json `inboxAck`): with it off the server keeps the
+ * item until the bot acks (`POST /v1/agents/{uid}/inbox/{id}/ack`), and the
+ * poller dedupes by id so the same item is never mirrored twice.
+ */
+import type { KitLogger } from "../log.js";
+import type { AgentKitPaths } from "../paths.js";
+export declare const SEEN_IDS_NAME = "seen-ids.json";
+export declare const INBOX_JSONL_NAME = "inbox.jsonl";
+export declare const MAX_SEEN_IDS = 5000;
+export interface InboxItem {
+    id: string;
+    raw: Record<string, unknown>;
+}
+/** Pull `{id}` out of each server item; items without a string id are dropped. */
+export declare function extractInboxItems(body: unknown): InboxItem[];
+export declare function readSeenIds(paths: Pick<AgentKitPaths, "inboxDir">): Set<string>;
+export declare function writeSeenIds(paths: Pick<AgentKitPaths, "inboxDir">, seen: Set<string>): void;
+export declare function mirrorInboxItem(paths: Pick<AgentKitPaths, "inboxDir">, item: InboxItem): string;
+export interface InboxDeps {
+    paths: AgentKitPaths;
+    agentUid: string;
+    apiBaseUrl: string;
+    pollMs: number;
+    ack: boolean;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    fetchInbox?: (token: string) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+    ackItem?: (token: string, id: string) => Promise<number>;
+    warmCache?: (token: string, agentUid: string) => Promise<unknown>;
+    sleep?: (ms: number) => Promise<void>;
+    maxPolls?: number;
+}
+export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string) => Promise<{
+    status: number;
+    body: unknown;
+}>;
+export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string) => Promise<number>;
+export declare function pollInboxOnce(deps: InboxDeps): Promise<{
+    ok: boolean;
+    mirrored: number;
+}>;
+export declare function runInboxLoop(deps: InboxDeps): Promise<void>;
+//# sourceMappingURL=inbox.d.ts.map

package/dist/lib/agent-kit/run/inbox.js

@@ -0,0 +1,152 @@
+/**
+ * Kit service: inbox poller.
+ *
+ * Mirrors the poll half of the hosted box's hq-agent-inbox.sh: every
+ * `inboxPollMs` GET /v1/agents/{uid}/inbox, take `.messages[]`, and stamp
+ * `component-inbox` ok on a 200 (any other status → error, token re-minted
+ * on the next pass). The hosted watcher then dispatches each item to a
+ * provider and acks it; an external bot brings its own brain, so this
+ * service only MIRRORS: each new item is written once to
+ * ~/.hq-agent/inbox/<id>.json and appended to inbox.jsonl for the bot to
+ * consume, and the work-mesh conversation cache is refreshed so `hq dm`
+ * and the skills see the same state.
+ *
+ * Acking is opt-in (kit.json `inboxAck`): with it off the server keeps the
+ * item until the bot acks (`POST /v1/agents/{uid}/inbox/{id}/ack`), and the
+ * poller dedupes by id so the same item is never mirrored twice.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { vaultApiFetch } from "../../../utils/vault-api.js";
+import { warmMeshConversationCache } from "../../mesh/api.js";
+import { writeComponentStatus } from "../creds.js";
+export const SEEN_IDS_NAME = "seen-ids.json";
+export const INBOX_JSONL_NAME = "inbox.jsonl";
+export const MAX_SEEN_IDS = 5000;
+/** Pull `{id}` out of each server item; items without a string id are dropped. */
+export function extractInboxItems(body) {
+    const rec = body && typeof body === "object" ? body : {};
+    const messages = Array.isArray(rec.messages) ? rec.messages : [];
+    const items = [];
+    for (const m of messages) {
+        if (!m || typeof m !== "object")
+            continue;
+        const raw = m;
+        const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
+        if (!id || !/^[A-Za-z0-9._:-]{1,200}$/.test(id))
+            continue;
+        items.push({ id, raw });
+    }
+    return items;
+}
+export function readSeenIds(paths) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(paths.inboxDir, SEEN_IDS_NAME), "utf8"));
+        return new Set(Array.isArray(raw) ? raw.filter((x) => typeof x === "string") : []);
+    }
+    catch {
+        return new Set();
+    }
+}
+export function writeSeenIds(paths, seen) {
+    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
+    const list = [...seen].slice(-MAX_SEEN_IDS);
+    fs.writeFileSync(path.join(paths.inboxDir, SEEN_IDS_NAME), JSON.stringify(list), { mode: 0o600 });
+}
+export function mirrorInboxItem(paths, item) {
+    fs.mkdirSync(paths.inboxDir, { recursive: true, mode: 0o700 });
+    const dest = path.join(paths.inboxDir, `${item.id}.json`);
+    fs.writeFileSync(dest, `${JSON.stringify(item.raw, null, 2)}\n`, { mode: 0o600 });
+    fs.appendFileSync(path.join(paths.inboxDir, INBOX_JSONL_NAME), `${JSON.stringify({ id: item.id, mirroredAt: new Date().toISOString(), ...item.raw })}\n`, { mode: 0o600 });
+    return dest;
+}
+export function defaultFetchInbox(agentUid, apiBaseUrl) {
+    return async (token) => {
+        const res = await vaultApiFetch({
+            token,
+            baseUrl: apiBaseUrl,
+            path: `/v1/agents/${encodeURIComponent(agentUid)}/inbox`,
+        });
+        const body = await res.json().catch(() => ({}));
+        return { status: res.status, body };
+    };
+}
+export function defaultAckItem(agentUid, apiBaseUrl) {
+    return async (token, id) => {
+        const res = await vaultApiFetch({
+            token,
+            baseUrl: apiBaseUrl,
+            path: `/v1/agents/${encodeURIComponent(agentUid)}/inbox/${encodeURIComponent(id)}/ack`,
+            method: "POST",
+        });
+        return res.status;
+    };
+}
+export async function pollInboxOnce(deps) {
+    const fetchInbox = deps.fetchInbox ?? defaultFetchInbox(deps.agentUid, deps.apiBaseUrl);
+    const ackItem = deps.ackItem ?? defaultAckItem(deps.agentUid, deps.apiBaseUrl);
+    const warmCache = deps.warmCache ?? ((token, uid) => warmMeshConversationCache(token, uid));
+    let token;
+    try {
+        token = await deps.getToken();
+    }
+    catch (err) {
+        writeComponentStatus(deps.paths, "inbox", "error");
+        deps.log("error", `inbox token mint failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { ok: false, mirrored: 0 };
+    }
+    let res;
+    try {
+        res = await fetchInbox(token);
+    }
+    catch (err) {
+        writeComponentStatus(deps.paths, "inbox", "error");
+        deps.log("error", `inbox fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+        return { ok: false, mirrored: 0 };
+    }
+    if (res.status !== 200) {
+        writeComponentStatus(deps.paths, "inbox", "error");
+        deps.log("warn", `inbox poll ${res.status}`);
+        return { ok: false, mirrored: 0 };
+    }
+    writeComponentStatus(deps.paths, "inbox", "ok");
+    const seen = readSeenIds(deps.paths);
+    const fresh = extractInboxItems(res.body).filter((i) => !seen.has(i.id));
+    for (const item of fresh) {
+        mirrorInboxItem(deps.paths, item);
+        seen.add(item.id);
+        if (deps.ack) {
+            try {
+                const status = await ackItem(token, item.id);
+                if (status < 200 || status >= 300)
+                    deps.log("warn", `ack ${item.id} → ${status}`);
+            }
+            catch (err) {
+                deps.log("warn", `ack ${item.id} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    if (fresh.length > 0) {
+        writeSeenIds(deps.paths, seen);
+        deps.log("info", `inbox mirrored ${fresh.length} item(s)`);
+        try {
+            await warmCache(token, deps.agentUid);
+        }
+        catch (err) {
+            deps.log("warn", `cache refresh failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { ok: true, mirrored: fresh.length };
+}
+export async function runInboxLoop(deps) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    let polls = 0;
+    for (;;) {
+        await pollInboxOnce(deps);
+        polls += 1;
+        if (deps.maxPolls !== undefined && polls >= deps.maxPolls)
+            return;
+        await sleep(deps.pollMs);
+    }
+}
+//# sourceMappingURL=inbox.js.map

package/dist/lib/agent-kit/run/mesh-listener.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Kit service: work-mesh doorbell listener.
+ *
+ * Policy hq-work-mesh-source-of-truth: the work mesh (REST) is the source of
+ * truth; MQTT carries IDS-ONLY doorbells on the agent's personal topics
+ * `hq/{agt_*}/{dm,work,sessions,notifications}`. This listener is the cache
+ * writer: on any doorbell it refetches through the REST API into
+ * ~/.hq/work-mesh/cache (warmMeshConversationCache) — message bodies are
+ * never taken from MQTT. A periodic refresh covers missed doorbells.
+ *
+ * Credentials come from the same contract-3 vend the mesh daemon uses
+ * (POST /v1/realtime/credentials); the WSS URL is SigV4-presigned. The
+ * connection is rebuilt before the vended credentials expire. `component-mesh`
+ * is stamped ok while subscribed and refreshing, error otherwise.
+ */
+import { type IClientOptions } from "mqtt";
+import { type CredentialsFetcher } from "../../mesh/live/daemon/credentials.js";
+import type { KitLogger } from "../log.js";
+import type { AgentKitPaths } from "../paths.js";
+export declare const DOORBELL_KINDS: readonly ["dm", "work", "sessions", "notifications"];
+export declare const DOORBELL_DEBOUNCE_MS = 2000;
+export declare const RECONNECT_BASE_MS = 1000;
+export declare const RECONNECT_MAX_MS = 60000;
+export declare function doorbellTopics(actorUid: string): string[];
+/** Minimal mqtt client surface the listener needs (test seam). */
+export interface DoorbellMqttClient {
+    on(event: string, handler: (...args: any[]) => void): unknown;
+    subscribe(topics: string | string[], opts: {
+        qos: 0 | 1 | 2;
+    }, callback?: (err: Error | null) => void): unknown;
+    end(force?: boolean, opts?: unknown, cb?: () => void): unknown;
+}
+export type DoorbellConnectFn = (url: string, opts: IClientOptions) => DoorbellMqttClient;
+export interface MeshListenerDeps {
+    paths: AgentKitPaths;
+    agentUid: string;
+    apiBaseUrl: string;
+    refreshMs: number;
+    getToken: () => Promise<string>;
+    log: KitLogger;
+    fetchCredentials?: CredentialsFetcher;
+    connect?: DoorbellConnectFn;
+    refetch?: (token: string, actorUid: string) => Promise<unknown>;
+    now?: () => Date;
+    random?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+}
+export interface MeshListenerHandle {
+    stop: () => Promise<void>;
+    /** Force a cache refetch (tests / doorbell path). */
+    refetchNow: (reason: string) => Promise<void>;
+    /** Simulate a doorbell (tests). */
+    ring: (topic: string) => void;
+    state: () => "idle" | "connecting" | "subscribed" | "closed";
+}
+export declare function startMeshListener(deps: MeshListenerDeps): Promise<MeshListenerHandle>;
+//# sourceMappingURL=mesh-listener.d.ts.map