@indigoai-us/hq-cli 5.120.1 → 5.121.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 ## [Unreleased]
 
+### Documentation
+
+- The 2026-09-18 fleet-bots GA notes group the published CLI changes for plan
+  notices, DM attachments, staged skills, version reporting, knowledge-index
+  protection, and ambiguous people resolution (#634, #636, #641, #642, #643,
+  #644, #645, #647, #648, #649).
+
+## [5.121.0] — 2026-09-18
+
+### Changed
+
+- The agent kit no longer installs a work-mesh doorbell listener, and
+  `hq agent probe` no longer checks one. The doorbell was never what made a
+  bot reachable — messages arrive over the inbox either way — but it was the
+  loudest part of setup: it needed a realtime connection that restricted bot
+  hosts routinely intercept, so a perfectly healthy bot reported a failure it
+  could do nothing about.
+
+  The probe's `work-mesh` line becomes `presence`: the agent's own inbox
+  answers and its heartbeat is fresh. That is what the check was really
+  proving. `hq mesh` remains available to a bot that is asked to use it; the
+  kit simply no longer runs a listener or ships a skill telling it to.
+
+  One trade-off: an inbox doorbell used to trigger an immediate poll. Without
+  it, incoming messages are picked up by the inbox poller on its own interval
+  (15 seconds by default) rather than instantly.
+
 ## [5.120.1] — 2026-09-18
 
 - A local bot no longer replaces your own sign-in. Bots that run on your

package/dist/command-catalog.generated.d.ts

@@ -4255,7 +4255,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly options: readonly [];
         readonly subcommands: readonly [{
             readonly name: "install";
-            readonly description: "Install the work-mesh, inbox and heartbeat services plus the skills directory";
+            readonly description: "Install the inbox and heartbeat services plus the skills directory";
             readonly aliases: readonly [];
             readonly hidden: false;
             readonly usage: "[options]";
@@ -4383,7 +4383,7 @@ export declare const COMMAND_CATALOG: readonly [{
             }];
         }, {
             readonly name: "run";
-            readonly description: "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process";
+            readonly description: "Run one kit service in the foreground (sync|inbox|heartbeat), or `all` to supervise every service in one process";
             readonly aliases: readonly [];
             readonly hidden: false;
             readonly usage: "[options] <service>";
@@ -4397,7 +4397,7 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
     }, {
         readonly name: "probe";
-        readonly description: "Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console";
+        readonly description: "Verify identity, vault access, presence, DMs and secrets; report to the console";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly usage: "[options]";

package/dist/command-catalog.generated.js

@@ -5507,7 +5507,7 @@ export const COMMAND_CATALOG = [
                 "subcommands": [
                     {
                         "name": "install",
-                        "description": "Install the work-mesh, inbox and heartbeat services plus the skills directory",
+                        "description": "Install the inbox and heartbeat services plus the skills directory",
                         "aliases": [],
                         "hidden": false,
                         "usage": "[options]",
@@ -5668,7 +5668,7 @@ export const COMMAND_CATALOG = [
                     },
                     {
                         "name": "run",
-                        "description": "Run one kit service in the foreground (sync|mesh|inbox|heartbeat), or `all` to supervise every service in one process",
+                        "description": "Run one kit service in the foreground (sync|inbox|heartbeat), or `all` to supervise every service in one process",
                         "aliases": [],
                         "hidden": false,
                         "usage": "[options] <service>",
@@ -5686,7 +5686,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "probe",
-                "description": "Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console",
+                "description": "Verify identity, vault access, presence, DMs and secrets; report to the console",
                 "aliases": [],
                 "hidden": false,
                 "usage": "[options]",

package/dist/commands/agent-kit.d.ts

@@ -3,7 +3,6 @@
  * services that make an external agent a full team member:
  *
  *   sync       company vault pull loop            → component-sync
- *   mesh       work-mesh doorbell listener        → component-mesh
  *   inbox      inbox poller (mirror + optional ack) → component-inbox
  *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
  *
@@ -77,7 +76,7 @@ export interface KitRuntime {
 }
 export declare function buildKitRuntime(service: KitService | "all"): KitRuntime;
 export declare function runKitService(service: KitService, rt: KitRuntime): Promise<void>;
-/** `kit run all`: supervise the four services as child processes with restart backoff. */
+/** `kit run all`: supervise the kit services as child processes with restart backoff. */
 export declare function runAllKitServices(rt: KitRuntime, host: ServiceHostPaths): Promise<void>;
 export declare function formatFallbackStatus(paths: AgentKitPaths, kill?: KillFn): string[] | null;
 export declare function registerAgentKitCommand(agent: Command): void;

package/dist/commands/agent-kit.js

@@ -3,7 +3,6 @@
  * services that make an external agent a full team member:
  *
  *   sync       company vault pull loop            → component-sync
- *   mesh       work-mesh doorbell listener        → component-mesh
  *   inbox      inbox poller (mirror + optional ack) → component-inbox
  *   heartbeat  60 s POST /v1/agents/{uid}/heartbeat with the three above
  *
@@ -28,12 +27,11 @@ import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { isKitService, KIT_SERVICES, enabledKitServices, kitServiceSpec, kitServiceSpecs, } from "../lib/agent-kit/services.js";
 import { writeKitSkills } from "../lib/agent-kit/skills.js";
 import { runHeartbeatLoop } from "../lib/agent-kit/run/heartbeat.js";
-import { pollInboxOnce, runInboxLoop } from "../lib/agent-kit/run/inbox.js";
+import { runInboxLoop } from "../lib/agent-kit/run/inbox.js";
 import { superviseKitServices } from "../lib/agent-kit/run/supervisor.js";
 import { fallbackStatus, rebootCrontabLine, ensureRebootCrontab, shouldUseFallback, startFallback, stopFallback, } from "../lib/agent-kit/fallback.js";
 import { serviceLogPath } from "../lib/agent-kit/paths.js";
 import { spawn } from "node:child_process";
-import { startMeshListener } from "../lib/agent-kit/run/mesh-listener.js";
 import { pendingInbox } from "../lib/agent-kit/inbox-state.js";
 import { buildWakeNotice, clearWakeConfig, currentWakeState, DEFAULT_WAKE_RETRY_MS, describeWake, fireWake, readWakeConfig, validateWakeUrl, writeWakeConfig, } from "../lib/agent-kit/wake.js";
 import { runSyncLoop } from "../lib/agent-kit/run/sync.js";
@@ -182,53 +180,9 @@ export async function runKitService(service, rt) {
                 log: rt.log,
             });
             return;
-        case "mesh": {
-            const handle = await startMeshListener({
-                paths: rt.paths,
-                agentUid: rt.creds.entityUid,
-                apiBaseUrl: rt.creds.apiBaseUrl,
-                refreshMs: rt.config.meshRefreshMs,
-                getToken: rt.getToken,
-                log: rt.log,
-                // Any doorbell (and the periodic refresh) re-polls the agent inbox, the
-                // only conversation source agent callers are authorized to read.
-                refetch: async () => {
-                    const r = await pollInboxOnce({
-                        paths: rt.paths,
-                        agentUid: rt.creds.entityUid,
-                        apiBaseUrl: rt.creds.apiBaseUrl,
-                        pollMs: rt.config.inboxPollMs,
-                        ack: rt.config.inboxAck,
-                        getToken: rt.getToken,
-                        log: rt.log,
-                    });
-                    if (!r.ok)
-                        throw new Error("agent inbox poll failed; see inbox.log");
-                },
-                // An inbox doorbell means "poll now" rather than waiting for the loop.
-                onInboxDoorbell: () => pollInboxOnce({
-                    paths: rt.paths,
-                    agentUid: rt.creds.entityUid,
-                    apiBaseUrl: rt.creds.apiBaseUrl,
-                    pollMs: rt.config.inboxPollMs,
-                    ack: rt.config.inboxAck,
-                    getToken: rt.getToken,
-                    log: rt.log,
-                }),
-            });
-            const stop = () => {
-                void handle.stop().then(() => process.exit(0));
-            };
-            process.once("SIGTERM", stop);
-            process.once("SIGINT", stop);
-            await new Promise(() => {
-                /* resident until signalled */
-            });
-            return;
-        }
     }
 }
-/** `kit run all`: supervise the four services as child processes with restart backoff. */
+/** `kit run all`: supervise the kit services as child processes with restart backoff. */
 export async function runAllKitServices(rt, host) {
     const services = enabledKitServices({ syncFiles: rt.config.syncFiles });
     rt.log("info", `supervisor starting ${services.join(",")} agent=${rt.creds.entityUid} cli=${CLI_VERSION}`);
@@ -286,7 +240,7 @@ export function registerAgentKitCommand(agent) {
         .description("Install, inspect, or run the external-agent background services");
     kit
         .command("install")
-        .description("Install the work-mesh, inbox and heartbeat services plus the skills directory")
+        .description("Install the inbox and heartbeat services plus the skills directory")
         .option("--hq-root <path>", "Local HQ tree to sync the company vault into (default: ~/.hq-agent/hq)")
         .option("--sync-files", "Also mirror the company vault to disk. Off by default: files are read on demand through the hq MCP server")
         .option("--no-sync-files", "Do not mirror the vault to disk (default; removes the loop if an earlier install added it)")

package/dist/commands/agent-probe.d.ts

@@ -5,11 +5,8 @@
  *   whoami       mint as the machine identity; token names this agent
  *   files        a vault listing answers on demand (or, with --sync-files, a
  *                pull succeeds and the company folder exists)
- *   work-mesh    the personal (contract-2) realtime vend names this agent, the
- *                agent-authorized inbox route answers 200, and this host's own
- *                presence is live: a fresh last-heartbeat.json plus an ok
- *                component-mesh stamp from the doorbell listener. (The company
- *                roster route is owner/admin-only and 404s for agt_ callers.)
+ *   presence     the agent-authorized inbox route answers 200 and this host's
+ *                own presence is live (a fresh last-heartbeat.json)
  *   dm           send a DM to self via POST /v1/notify/dm (accepted) and read the agent inbox (200)
  *                through GET /v1/agents/{uid}/inbox (the agent read surface;
  *                /v1/notify/thread is intentionally closed to agents)
@@ -51,9 +48,6 @@ export interface ProbeDeps {
     runHq: (args: string[]) => Promise<number>;
     /** Mirror the vault to disk. Off by default: files are read through the API. */
     syncFiles?: boolean;
-    vendRealtime: (token: string) => Promise<{
-        actorUid: string;
-    }>;
     /** GET /v1/agents/{self}/inbox — agent-authorized, self-scoped. */
     readInbox: (token: string) => Promise<InboxFetchResult>;
     sendDm: (token: string, toUid: string, body: string) => Promise<void>;

package/dist/commands/agent-probe.js

@@ -5,11 +5,8 @@
  *   whoami       mint as the machine identity; token names this agent
  *   files        a vault listing answers on demand (or, with --sync-files, a
  *                pull succeeds and the company folder exists)
- *   work-mesh    the personal (contract-2) realtime vend names this agent, the
- *                agent-authorized inbox route answers 200, and this host's own
- *                presence is live: a fresh last-heartbeat.json plus an ok
- *                component-mesh stamp from the doorbell listener. (The company
- *                roster route is owner/admin-only and 404s for agt_ callers.)
+ *   presence     the agent-authorized inbox route answers 200 and this host's
+ *                own presence is live (a fresh last-heartbeat.json)
  *   dm           send a DM to self via POST /v1/notify/dm (accepted) and read the agent inbox (200)
  *                through GET /v1/agents/{uid}/inbox (the agent read surface;
  *                /v1/notify/thread is intentionally closed to agents)
@@ -33,9 +30,6 @@ import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
 import { sendAgentDm } from "./agents.js";
-import { createPersonalRealtimeFetcher } from "../lib/mesh/live/daemon/credentials.js";
-import { readComponentStatus } from "../lib/agent-kit/creds.js";
-import { COMPONENT_STALE_AFTER_MS } from "../lib/agent-kit/run/heartbeat.js";
 import { defaultFetchInbox } from "../lib/agent-kit/run/inbox.js";
 import { agentKitPaths } from "../lib/agent-kit/paths.js";
 import { readKitConfig } from "../lib/agent-kit/kit-config.js";
@@ -142,40 +136,33 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "files", ok: false, detail: "skipped: no token" });
     }
-    // 3. work-mesh: vend + agent-authorized reachability + self presence
-    if (token && companyUid) {
+    // 3. presence: HQ can see this agent, and the agent can read its own inbox.
+    //
+    // This replaces a work-mesh check that also required the realtime doorbell
+    // to be connected. The doorbell was never what made an agent reachable —
+    // messages arrive over the inbox either way — and on a host whose egress
+    // intercepts that connection it could never pass, so a perfectly healthy
+    // bot reported a failure it could do nothing about.
+    if (token) {
         try {
-            const vend = await deps.vendRealtime(token);
-            if (vend.actorUid !== self) {
-                checks.push({ name: "work-mesh", ok: false, detail: `realtime vend is for ${vend.actorUid}` });
-            }
-            else {
-                const inbox = await deps.readInbox(token);
-                const age = heartbeatAgeSeconds(deps.paths, now);
-                const mesh = readComponentStatus(deps.paths, "mesh", COMPONENT_STALE_AFTER_MS.mesh, now);
-                const reachable = inbox.status === 200;
-                const fresh = age !== null && age <= PRESENCE_FRESH_SECONDS;
-                const meshOk = mesh.status === "ok";
-                const ok = reachable && fresh && meshOk;
-                const parts = [
-                    "realtime vend ok",
-                    `inbox GET → ${inbox.status}`,
-                    `heartbeat ${age === null ? "never" : `${age}s ago`}`,
-                    `mesh listener ${mesh.status}${mesh.at ? ` @${mesh.at.toISOString()}` : ""}`,
-                ];
-                checks.push({
-                    name: "work-mesh",
-                    ok,
-                    detail: `${parts.join("; ")}${ok ? "" : " — is `hq agent kit` installed and running? see ~/.hq-agent/logs/mesh.log"}`,
-                });
-            }
+            const inbox = await deps.readInbox(token);
+            const age = heartbeatAgeSeconds(deps.paths, now);
+            const reachable = inbox.status === 200;
+            const fresh = age !== null && age <= PRESENCE_FRESH_SECONDS;
+            const ok = reachable && fresh;
+            checks.push({
+                name: "presence",
+                ok,
+                detail: `inbox GET → ${inbox.status}; heartbeat ${age === null ? "never" : `${age}s ago`}` +
+                    (ok ? "" : " — is `hq agent kit` installed and running? see ~/.hq-agent/logs/"),
+            });
         }
         catch (err) {
-            checks.push({ name: "work-mesh", ok: false, detail: errText(err) });
+            checks.push({ name: "presence", ok: false, detail: errText(err) });
         }
     }
     else {
-        checks.push({ name: "work-mesh", ok: false, detail: "skipped: no token/company" });
+        checks.push({ name: "presence", ok: false, detail: "skipped: no token" });
     }
     // 4. dm: the send is accepted and the agent inbox is readable.
     // The server never delivers a self-DM into the sender's own inbox
@@ -289,10 +276,6 @@ export function defaultProbeDeps(paths, creds) {
         getToken: () => ensureCognitoToken({ tokenSource: "machine", interactive: false }),
         resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
         runHq: defaultRunPull(process.execPath, process.argv[1], process.env),
-        vendRealtime: async (token) => {
-            const bundle = await createPersonalRealtimeFetcher({ token, baseUrl: base })();
-            return { actorUid: bundle.actorUid };
-        },
         readInbox: (token) => defaultFetchInbox(creds.entityUid, base)(token),
         sendDm: (token, to, body) => sendAgentDm(token, to, body),
         listSecrets: async (token, companyUid) => {
@@ -318,7 +301,7 @@ export function defaultProbeDeps(paths, creds) {
 export function registerAgentProbeCommand(agent) {
     agent
         .command("probe")
-        .description("Verify identity, vault sync, work-mesh presence, DMs and secrets; report to the console")
+        .description("Verify identity, vault access, presence, DMs and secrets; report to the console")
         .option("--json", "Print machine-readable JSON")
         .action(async (opts) => {
         try {

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

@@ -20,7 +20,7 @@ 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 type KitComponent = "sync" | "inbox";
 export declare const KIT_COMPONENTS: readonly KitComponent[];
 export interface AgentKitPaths {
     home: string;

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

@@ -22,7 +22,7 @@ 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 const KIT_COMPONENTS = ["sync", "inbox"];
 export function agentDir(home = os.homedir(), env = process.env) {
     const override = env[AGENT_DIR_ENV]?.trim();
     if (override)

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

@@ -20,7 +20,6 @@ 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, components_ = KIT_COMPONENTS) {

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

@@ -1,11 +1,11 @@
 /**
- * The four kit services and how each is launched. Every unit runs
+ * The kit services and how each is launched. Every unit runs
  * `node hq agent kit run <service>`; the service reads kit.json and the
  * machine-creds file itself, so the units carry paths and nothing else.
  */
 import type { ServiceSpec } from "../service-manager/types.js";
 import type { AgentKitPaths } from "./paths.js";
-export type KitService = "sync" | "mesh" | "inbox" | "heartbeat";
+export type KitService = "sync" | "inbox" | "heartbeat";
 export declare const KIT_SERVICES: readonly KitService[];
 export declare const KIT_LABEL_PREFIX = "ai.getindigo.hq-agent";
 export declare function isKitService(value: string): value is KitService;

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

@@ -1,17 +1,16 @@
 /**
- * The four kit services and how each is launched. Every unit runs
+ * The kit services and how each is launched. Every unit runs
  * `node hq agent kit run <service>`; the service reads kit.json and the
  * machine-creds file itself, so the units carry paths and nothing else.
  */
 import { serviceLogPath } from "./paths.js";
-export const KIT_SERVICES = ["sync", "mesh", "inbox", "heartbeat"];
+export const KIT_SERVICES = ["sync", "inbox", "heartbeat"];
 export const KIT_LABEL_PREFIX = "ai.getindigo.hq-agent";
 export function isKitService(value) {
     return KIT_SERVICES.includes(value);
 }
 const DESCRIPTIONS = {
     sync: "HQ agent kit: company vault sync loop",
-    mesh: "HQ agent kit: work-mesh doorbell listener",
     inbox: "HQ agent kit: inbox poller",
     heartbeat: "HQ agent kit: heartbeat reporter",
 };

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

@@ -125,29 +125,6 @@ Rules:
 - Request the narrowest \`--only\` set the command needs.
 - If a secret is missing, say which NAME is missing and ask a human admin to
   add it with \`hq secrets set\` — do not ask for the value in chat.
-`,
-    },
-    {
-        name: "work-mesh-status",
-        description: "Report and update this agent's live work status and read the team's work mesh via the hq CLI.",
-        body: `# Work mesh status
-
-The work mesh is HQ's live board of who is working on what. It is the source
-of truth for project stories and active sessions. The kit's listener re-polls
-this agent's inbox whenever a doorbell rings.
-
-\`\`\`bash
-hq mesh session status --company <slug>          # who is working on what right now
-hq mesh start --company <slug> --project <slug> --summary "<what you are starting>"
-hq mesh progress --company <slug> --project <slug> --summary "<what changed>"
-hq mesh blocked --company <slug> --project <slug> --summary "<what blocks you>"
-hq mesh done --company <slug> --project <slug> --summary "<what you finished>"
-hq mesh note --company <slug> --project <slug> --summary "<short note>"
-\`\`\`
-
-Post \`start\` when you pick up a piece of work and \`done\` when you finish it.
-Keep entries to one line. Presence (online / stale / offline) is derived
-from the kit heartbeat automatically — you do not need to report it.
 `,
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.120.1",
+  "version": "5.121.0",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {

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

@@ -1,103 +0,0 @@
-/**
- * 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,inbox}`. 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 contract-2 (personal) vend
- * (POST /v1/realtime/credentials {contractVersion: 2}), whose STS policy grants
- * the caller's own `hq/{uid}/*` topics. The contract-3 vend the presence daemon
- * uses only grants company presence + thread-directory topics, so subscribing
- * to personal doorbells with it made AWS IoT drop the connection before SUBACK.
- * Only doorbell topics the vend advertises are subscribed (one ungranted topic
- * in a SUBSCRIBE disconnects the whole client). An `inbox` doorbell triggers
- * an immediate inbox poll via `onInboxDoorbell`. 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 PersonalCredentialsFetcher, type PersonalRealtimeBundle } 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", "inbox"];
-export declare const DOORBELL_DEBOUNCE_MS = 2000;
-export declare const RECONNECT_BASE_MS = 1000;
-export declare const RECONNECT_MAX_MS = 60000;
-/**
- * Consecutive failed MQTT attempts before the listener stops treating the
- * doorbell as reachable and runs on the periodic refetch alone.
- *
- * The doorbell is an OPTIMISATION, not the source of truth: policy
- * hq-work-mesh-source-of-truth puts the work mesh behind REST, MQTT only
- * carries ids, and `schedulePeriodic` already refetches on its own cadence. So
- * a host that cannot reach AWS IoT is not a broken agent — it is an agent with
- * a slower doorbell. Some bot sandboxes sit behind an egress proxy that
- * intercepts the connection and answers with non-TLS bytes (observed on the
- * Muse pilot: `tls_validate_record_header:wrong version number`, reconnecting
- * forever while vend, inbox and heartbeat were all healthy). Before this, that
- * host retried until the process died and reported component-mesh=error the
- * whole time.
- */
-export declare const MESH_FALLBACK_AFTER_ATTEMPTS = 5;
-/**
- * How often polling mode re-tries MQTT. Long, because the usual cause is the
- * network the host is on, which does not change minute to minute — but it is
- * retried, so a bot moved to an unrestricted network recovers its instant
- * doorbell without being reinstalled.
- */
-export declare const MESH_FALLBACK_RETRY_MS: number;
-export declare function doorbellTopics(actorUid: string): string[];
-/**
- * Doorbell topics this session may subscribe to: the intersection of
- * DOORBELL_KINDS with the personal topics the vend advertises. AWS IoT
- * disconnects the client on any unauthorized topic in a SUBSCRIBE, so a kind
- * the server does not (yet) grant is skipped rather than risked.
- */
-export declare function grantedDoorbellTopics(bundle: Pick<PersonalRealtimeBundle, "actorUid" | "topics">): string[];
-export declare function isInboxDoorbell(topic: string): boolean;
-/** 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?: PersonalCredentialsFetcher;
-    /** Called immediately (not debounced) when an `hq/{uid}/inbox` doorbell rings. */
-    onInboxDoorbell?: () => Promise<unknown> | void;
-    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: () => MeshListenerState;
-}
-/**
- * `polling` is a healthy state: the doorbell is unreachable, so the cache is
- * kept current by the periodic refetch alone. Incoming DMs are unaffected —
- * the inbox poller is a separate service on its own interval.
- */
-export type MeshListenerState = "idle" | "connecting" | "subscribed" | "polling" | "closed";
-export declare function startMeshListener(deps: MeshListenerDeps): Promise<MeshListenerHandle>;
-//# sourceMappingURL=mesh-listener.d.ts.map

package/dist/lib/agent-kit/run/mesh-listener.js

@@ -1,296 +0,0 @@
-/**
- * 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,inbox}`. 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 contract-2 (personal) vend
- * (POST /v1/realtime/credentials {contractVersion: 2}), whose STS policy grants
- * the caller's own `hq/{uid}/*` topics. The contract-3 vend the presence daemon
- * uses only grants company presence + thread-directory topics, so subscribing
- * to personal doorbells with it made AWS IoT drop the connection before SUBACK.
- * Only doorbell topics the vend advertises are subscribed (one ungranted topic
- * in a SUBSCRIBE disconnects the whole client). An `inbox` doorbell triggers
- * an immediate inbox poll via `onInboxDoorbell`. 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 mqtt from "mqtt";
-import { defaultFetchInbox } from "./inbox.js";
-import { createPersonalRealtimeFetcher, MQTT_KEEPALIVE_SECONDS, renewalDelayMs, } from "../../mesh/live/daemon/credentials.js";
-import { presignIotWssUrl } from "../../mesh/live/daemon/presign.js";
-import { writeComponentStatus } from "../creds.js";
-export const DOORBELL_KINDS = ["dm", "work", "sessions", "notifications", "inbox"];
-export const DOORBELL_DEBOUNCE_MS = 2_000;
-export const RECONNECT_BASE_MS = 1_000;
-export const RECONNECT_MAX_MS = 60_000;
-/**
- * Consecutive failed MQTT attempts before the listener stops treating the
- * doorbell as reachable and runs on the periodic refetch alone.
- *
- * The doorbell is an OPTIMISATION, not the source of truth: policy
- * hq-work-mesh-source-of-truth puts the work mesh behind REST, MQTT only
- * carries ids, and `schedulePeriodic` already refetches on its own cadence. So
- * a host that cannot reach AWS IoT is not a broken agent — it is an agent with
- * a slower doorbell. Some bot sandboxes sit behind an egress proxy that
- * intercepts the connection and answers with non-TLS bytes (observed on the
- * Muse pilot: `tls_validate_record_header:wrong version number`, reconnecting
- * forever while vend, inbox and heartbeat were all healthy). Before this, that
- * host retried until the process died and reported component-mesh=error the
- * whole time.
- */
-export const MESH_FALLBACK_AFTER_ATTEMPTS = 5;
-/**
- * How often polling mode re-tries MQTT. Long, because the usual cause is the
- * network the host is on, which does not change minute to minute — but it is
- * retried, so a bot moved to an unrestricted network recovers its instant
- * doorbell without being reinstalled.
- */
-export const MESH_FALLBACK_RETRY_MS = 30 * 60_000;
-export function doorbellTopics(actorUid) {
-    return DOORBELL_KINDS.map((k) => `hq/${actorUid}/${k}`);
-}
-/**
- * Doorbell topics this session may subscribe to: the intersection of
- * DOORBELL_KINDS with the personal topics the vend advertises. AWS IoT
- * disconnects the client on any unauthorized topic in a SUBSCRIBE, so a kind
- * the server does not (yet) grant is skipped rather than risked.
- */
-export function grantedDoorbellTopics(bundle) {
-    const advertised = new Set(Object.values(bundle.topics));
-    return doorbellTopics(bundle.actorUid).filter((t) => advertised.has(t));
-}
-export function isInboxDoorbell(topic) {
-    return /^hq\/[^/]+\/inbox$/.test(topic);
-}
-function backoff(attempt, random) {
-    const cap = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * 2 ** attempt);
-    return Math.max(RECONNECT_BASE_MS, Math.floor(random() * cap));
-}
-export async function startMeshListener(deps) {
-    const now = deps.now ?? (() => new Date());
-    const random = deps.random ?? Math.random;
-    const setT = deps.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
-    const clearT = deps.clearTimeout ?? ((h) => clearTimeout(h));
-    const connect = deps.connect ?? ((url, opts) => mqtt.connect(url, opts));
-    // Agent callers are refused by the human conversation routes
-    // (/v1/notify/inbox|contacts|thread → 403 AGENT_ROUTE_NOT_SUPPORTED), so the
-    // default refetch reads the agent's own inbox, the agent-authorized source.
-    const refetch = deps.refetch ??
-        (async (token, uid) => {
-            const res = await defaultFetchInbox(uid, deps.apiBaseUrl)(token);
-            if (res.status !== 200) {
-                throw new Error(`GET ${res.url ?? "agent inbox"} → ${res.status}${res.bodyText ? ` body=${res.bodyText}` : ""}`);
-            }
-        });
-    const fetchCredentials = deps.fetchCredentials ??
-        (async () => {
-            const token = await deps.getToken();
-            return createPersonalRealtimeFetcher({ token, baseUrl: deps.apiBaseUrl })();
-        });
-    let state = "idle";
-    /**
-     * The doorbell is unreachable and the periodic refetch is carrying the
-     * cache. Tracked separately from `state`, which follows the MQTT connection
-     * through every retry attempt.
-     */
-    let polling = false;
-    let client = null;
-    let stopped = false;
-    let attempt = 0;
-    let debounce = null;
-    let renewal = null;
-    let periodic = null;
-    let refetching = null;
-    let pendingReason = null;
-    const doRefetch = async (reason) => {
-        if (refetching) {
-            pendingReason = reason;
-            return refetching;
-        }
-        refetching = (async () => {
-            try {
-                const token = await deps.getToken();
-                await refetch(token, deps.agentUid);
-                // Polling counts as healthy: the component's job is keeping the cache
-                // current, and in this mode it is doing exactly that, just on the
-                // periodic cadence instead of on a doorbell.
-                const healthy = state === "subscribed" || polling;
-                writeComponentStatus(deps.paths, "mesh", healthy ? "ok" : "error");
-                deps.log("info", `cache refetched (${reason})`);
-            }
-            catch (err) {
-                writeComponentStatus(deps.paths, "mesh", "error");
-                deps.log("error", `refetch failed (${reason}): ${err instanceof Error ? err.message : String(err)}`);
-            }
-            finally {
-                refetching = null;
-            }
-            if (pendingReason) {
-                const next = pendingReason;
-                pendingReason = null;
-                await doRefetch(next);
-            }
-        })();
-        return refetching;
-    };
-    const ring = (topic) => {
-        if (isInboxDoorbell(topic) && deps.onInboxDoorbell) {
-            try {
-                void Promise.resolve(deps.onInboxDoorbell()).catch((err) => deps.log("warn", `inbox poll on doorbell failed: ${err instanceof Error ? err.message : String(err)}`));
-            }
-            catch (err) {
-                deps.log("warn", `inbox poll on doorbell failed: ${err instanceof Error ? err.message : String(err)}`);
-            }
-        }
-        if (debounce)
-            clearT(debounce);
-        debounce = setT(() => {
-            debounce = null;
-            void doRefetch(`doorbell ${topic}`);
-        }, DOORBELL_DEBOUNCE_MS);
-    };
-    const schedulePeriodic = () => {
-        if (periodic)
-            clearT(periodic);
-        periodic = setT(() => {
-            periodic = null;
-            void doRefetch("periodic").then(schedulePeriodic);
-        }, deps.refreshMs);
-    };
-    const scheduleReconnect = () => {
-        if (stopped)
-            return;
-        if (attempt >= MESH_FALLBACK_AFTER_ATTEMPTS) {
-            // Stop reporting an unreachable doorbell as a broken component, and stop
-            // hammering a connection this host cannot make. The periodic refetch
-            // carries the cache; MQTT is retried occasionally in case the network
-            // changes.
-            const wasPolling = polling;
-            polling = true;
-            if (!wasPolling) {
-                deps.log("warn", `mqtt unreachable after ${attempt} attempts; falling back to periodic refetch every ${deps.refreshMs}ms. ` +
-                    "Incoming DMs are unaffected (the inbox poller is a separate service). " +
-                    `Retrying mqtt in ${MESH_FALLBACK_RETRY_MS}ms.`);
-                void doRefetch("fallback");
-            }
-            setT(() => {
-                attempt = 0;
-                void connectOnce();
-            }, MESH_FALLBACK_RETRY_MS);
-            return;
-        }
-        const delay = backoff(attempt, random);
-        attempt += 1;
-        deps.log("warn", `mqtt reconnect in ${delay}ms (attempt ${attempt})`);
-        setT(() => void connectOnce(), delay);
-    };
-    const connectOnce = async () => {
-        if (stopped)
-            return;
-        state = "connecting";
-        let bundle;
-        try {
-            bundle = await fetchCredentials();
-            if (bundle.actorUid !== deps.agentUid) {
-                throw new Error(`realtime vend is for ${bundle.actorUid}, expected ${deps.agentUid}`);
-            }
-        }
-        catch (err) {
-            if (!polling)
-                writeComponentStatus(deps.paths, "mesh", "error");
-            deps.log("error", `credential vend failed: ${err instanceof Error ? err.message : String(err)}`);
-            scheduleReconnect();
-            return;
-        }
-        const url = presignIotWssUrl(bundle.credentials, bundle.iotEndpoint, bundle.region, now());
-        const c = connect(url, {
-            clientId: bundle.clientId,
-            keepalive: MQTT_KEEPALIVE_SECONDS,
-            clean: true,
-            reconnectPeriod: 0,
-            protocolVersion: 4,
-        });
-        client = c;
-        let settled = false;
-        const topics = grantedDoorbellTopics(bundle);
-        const skipped = doorbellTopics(bundle.actorUid).filter((t) => !topics.includes(t));
-        if (skipped.length > 0)
-            deps.log("info", `vend does not grant ${skipped.join(", ")}; not subscribing`);
-        c.on("connect", () => {
-            if (topics.length === 0) {
-                deps.log("error", "realtime vend advertises no doorbell topics");
-                c.end(true);
-                return;
-            }
-            c.subscribe(topics, { qos: 1 }, (err) => {
-                if (err) {
-                    deps.log("error", `subscribe failed: ${err.message}`);
-                    c.end(true);
-                    return;
-                }
-                settled = true;
-                attempt = 0;
-                polling = false;
-                state = "subscribed";
-                writeComponentStatus(deps.paths, "mesh", "ok");
-                deps.log("info", `subscribed to ${topics.length} doorbell topics`);
-                void doRefetch("connect");
-                if (renewal)
-                    clearT(renewal);
-                renewal = setT(() => {
-                    deps.log("info", "renewing realtime credentials");
-                    c.end(true);
-                }, renewalDelayMs(now().getTime(), bundle.expiresAt));
-            });
-        });
-        c.on("message", (topic) => {
-            // Ids-only doorbell: the payload is never parsed for content.
-            ring(topic);
-        });
-        c.on("error", (err) => {
-            deps.log("warn", `mqtt error: ${err.message}`);
-        });
-        c.on("close", () => {
-            if (client !== c)
-                return;
-            client = null;
-            const wasSubscribed = state === "subscribed";
-            state = stopped ? "closed" : "idle";
-            // A close while polling is the periodic MQTT retry failing again; the
-            // periodic refetch is still doing the component's job, so it is not an
-            // error.
-            if (!polling)
-                writeComponentStatus(deps.paths, "mesh", "error");
-            if (!settled || !wasSubscribed)
-                deps.log("warn", "mqtt closed before subscribe settled");
-            scheduleReconnect();
-        });
-    };
-    schedulePeriodic();
-    await connectOnce();
-    return {
-        stop: async () => {
-            stopped = true;
-            state = "closed";
-            if (debounce)
-                clearT(debounce);
-            if (renewal)
-                clearT(renewal);
-            if (periodic)
-                clearT(periodic);
-            const c = client;
-            client = null;
-            if (c)
-                await new Promise((r) => c.end(true, undefined, () => r()));
-        },
-        refetchNow: doRefetch,
-        ring,
-        state: () => (polling && state !== "subscribed" && state !== "closed" ? "polling" : state),
-    };
-}
-//# sourceMappingURL=mesh-listener.js.map