@indigoai-us/hq-cli 5.116.0 → 5.117.1

package/dist/commands/agent-probe.js

@@ -4,9 +4,14 @@
  *
  *   whoami       mint as the machine identity; token names this agent
  *   team-sync    `hq sync pull --all` succeeds and the company folder exists
- *   work-mesh    realtime credentials vend for this agent and the roster row
- *                shows presence online/stale (heartbeat landed)
- *   dm           send a DM to self via the notify surface and read it back
+ *   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.)
+ *   dm           send a DM to self via POST /v1/notify/dm and read it back
+ *                through GET /v1/agents/{uid}/inbox (the agent read surface;
+ *                /v1/notify/thread is intentionally closed to agents)
  *   secrets      `GET /secrets/{companyUid}` answers 200
  *
  * Output is the exact shape the console recipes promise: one
@@ -26,8 +31,11 @@ import { CLI_VERSION } from "../cli-version.js";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { peekIdToken } from "../utils/id-token.js";
 import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
-import { listAgents, readAgentThread, sendAgentDm } from "./agents.js";
-import { createContract3Fetcher } from "../lib/mesh/live/daemon/credentials.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";
 import { readLastHeartbeat } from "../lib/agent-kit/run/heartbeat.js";
@@ -35,6 +43,8 @@ import { defaultRunPull, syncPullArgs } from "../lib/agent-kit/run/sync.js";
 import { requireExternalCreds } from "./agent-kit.js";
 export const DM_ROUNDTRIP_TIMEOUT_MS = 20_000;
 export const DM_ROUNDTRIP_POLL_MS = 2_000;
+/** A heartbeat older than this does not count as live presence (3 missed 60 s beats). */
+export const PRESENCE_FRESH_SECONDS = 180;
 function errText(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -108,7 +118,7 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "team-sync", ok: false, detail: "skipped: no token" });
     }
-    // 3. mesh-presence
+    // 3. work-mesh: vend + agent-authorized reachability + self presence
     if (token && companyUid) {
         try {
             const vend = await deps.vendRealtime(token);
@@ -116,17 +126,23 @@ export async function runProbe(deps) {
                 checks.push({ name: "work-mesh", ok: false, detail: `realtime vend is for ${vend.actorUid}` });
             }
             else {
-                const roster = await deps.listRoster(token, companyUid);
-                const row = roster.find((r) => r.uid === self);
-                const presence = typeof row?.presence === "string" ? row.presence : "unknown";
-                const last = typeof row?.lastHeartbeatAt === "string" ? row.lastHeartbeatAt : "never";
-                const ok = presence === "online" || presence === "stale";
+                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: row
-                        ? `realtime vend ok; presence=${presence} lastHeartbeatAt=${last}${ok ? "" : " — is `hq agent kit` installed and running?"}`
-                        : "realtime vend ok but this agent is not on the company roster",
+                    detail: `${parts.join("; ")}${ok ? "" : " — is `hq agent kit` installed and running? see ~/.hq-agent/logs/mesh.log"}`,
                 });
             }
         }
@@ -137,27 +153,37 @@ export async function runProbe(deps) {
     else {
         checks.push({ name: "work-mesh", ok: false, detail: "skipped: no token/company" });
     }
-    // 4. dm-roundtrip
+    // 4. dm round-trip: send via notify, read back via the agent inbox
     if (token) {
         try {
             const body = `hq agent probe ${nonce}`;
             await deps.sendDm(token, self, body);
             const deadline = now().getTime() + (deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS);
             let found = false;
+            let lastStatus = 0;
             for (;;) {
-                const msgs = await deps.readThread(token, self);
-                if (msgs.some((m) => typeof m.body === "string" && m.body.includes(nonce))) {
+                const res = await deps.readInbox(token);
+                lastStatus = res.status;
+                if (res.status === 200 && inboxContainsNonce(res.body, nonce)) {
                     found = true;
                     break;
                 }
+                // A 4xx will not heal by polling (auth/route refusal): stop now.
+                if (res.status >= 400 && res.status < 500)
+                    break;
                 if (now().getTime() >= deadline)
                     break;
                 await sleep(DM_ROUNDTRIP_POLL_MS);
             }
+            const secs = Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000);
             checks.push({
                 name: "dm",
                 ok: found,
-                detail: found ? "sent to self via /v1/notify/dm and read back" : `sent but not visible in thread after ${Math.round((deps.dmTimeoutMs ?? DM_ROUNDTRIP_TIMEOUT_MS) / 1000)}s`,
+                detail: found
+                    ? "sent to self via /v1/notify/dm and read back from /v1/agents/{uid}/inbox"
+                    : lastStatus === 200
+                        ? `sent but not visible in /v1/agents/{uid}/inbox after ${secs}s`
+                        : `sent but /v1/agents/{uid}/inbox answered ${lastStatus}`,
             });
         }
         catch (err) {
@@ -205,6 +231,19 @@ export async function runProbe(deps) {
     }
     return result;
 }
+/** True when any inbox item (whatever its channel shape) carries the nonce. */
+export function inboxContainsNonce(body, nonce) {
+    const rec = body && typeof body === "object" ? body : {};
+    const messages = Array.isArray(rec.messages) ? rec.messages : [];
+    return messages.some((m) => {
+        try {
+            return JSON.stringify(m).includes(nonce);
+        }
+        catch {
+            return false;
+        }
+    });
+}
 export function formatHeartbeatAge(age) {
     if (age === null)
         return "never (kit heartbeat has not posted yet)";
@@ -241,12 +280,11 @@ export function defaultProbeDeps(paths, creds) {
         resolveCompanyUid: (token, slug) => getCompanyUid(token, slug),
         runPull: defaultRunPull(process.execPath, process.argv[1], process.env),
         vendRealtime: async (token) => {
-            const bundle = await createContract3Fetcher({ token, baseUrl: base })();
+            const bundle = await createPersonalRealtimeFetcher({ token, baseUrl: base })();
             return { actorUid: bundle.actorUid };
         },
-        listRoster: async (token, companyUid) => (await listAgents(token, companyUid)),
+        readInbox: (token) => defaultFetchInbox(creds.entityUid, base)(token),
         sendDm: (token, to, body) => sendAgentDm(token, to, body),
-        readThread: async (token, withUid) => readAgentThread(token, withUid, 20),
         listSecrets: async (token, companyUid) => {
             const res = await vaultApiFetch({
                 token,

package/dist/commands/bot.d.ts

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { type RuntimeSignInIssue } from "../lib/bot/runtime-sign-in.js";
-import { type BotKind, type BotMemoryMode, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
+import { type BotLocalConfig, type MyLocalBot, type BotKind, type BotMemoryMode, type BotNotRunnableReason, type BotConfig, type BotRuntimeId, type LaunchctlExec } from "../lib/bot/index.js";
 /** Real launchctl; every failure is a non-ok result, never a throw. */
 export declare const defaultLaunchctl: LaunchctlExec;
 /** The desktop app creates HQ's setup bot under this name, always from the `setup` worker. */
@@ -101,5 +101,144 @@ export declare function runBotSet(nameArg: string, opts: {
     effort?: string;
     json?: boolean;
 }): Promise<void>;
+/**
+ * The one bot the caller means. Matches the local folder name, the cloud slug,
+ * the display name, or the agt_ uid; an ambiguous name is refused rather than
+ * guessed at.
+ */
+export declare function matchRemoteBots(bots: readonly MyLocalBot[], wanted: string): MyLocalBot[];
+export declare function resolveRemoteBot(bots: readonly MyLocalBot[], wanted: string): MyLocalBot;
+/**
+ * Why HQ could not say which bots the account owns. The desktop app switches
+ * on these values, so they are contract, not prose:
+ *
+ *   server-unsupported  the HQ Cloud in front of us has no listing route
+ *   auth                the sign-in was refused
+ *   network             HQ could not be reached at all
+ *   server-error        HQ answered 5xx
+ *   error               anything else
+ */
+export type RemoteBotsUnavailableReason = "server-unsupported" | "auth" | "network" | "server-error" | "error";
+export interface RemoteBotsUnavailable {
+    reason: RemoteBotsUnavailableReason;
+    message: string;
+}
+/**
+ * Turn any failure of `GET /v1/agents/mine` into one plain sentence plus a
+ * stable reason. Production HQ Cloud does not serve that route yet, and an
+ * uncaught 404 reached the person verbatim as "HQ API /v1/agents/mine → 404:
+ * Not found" — and, under --json, as no document at all.
+ */
+export declare function remoteBotsUnavailable(err: unknown): RemoteBotsUnavailable;
+/**
+ * A cloud teardown that only got part of the way, said in the same vocabulary
+ * the desktop switches on, plus the one decision that follows from it.
+ *
+ * `DELETE /v1/agents/{uid}` answers 200 with `terminal:false` and a per-step
+ * `failures` map when it could do only part of the job. Those strings are raw
+ * infrastructure: one real answer carried the AWS account id, an assumed-role
+ * ARN and a DynamoDB table ARN. They are classified here and never repeated —
+ * `detail` is a plain clause, `steps` is the server's own step names and
+ * nothing of what they said.
+ *
+ * `retryable` is the local-state decision. Running `hq bot rm` again can only
+ * finish the job when the step that failed might behave differently next time.
+ * A refusal, or a step whose target was already gone, answers the same way
+ * forever, so the local copy goes and the message says the leftover is HQ's.
+ *
+ * `reason` reuses {@link RemoteBotsUnavailableReason}: `auth` for a refused
+ * step (a permission problem, on either side of the call), `error` for a step
+ * whose target was already gone, `server-error` for anything HQ may yet
+ * finish.
+ */
+export interface BotRemovalIncomplete {
+    reason: RemoteBotsUnavailableReason;
+    /** One plain clause naming what stopped. Never a transport string. */
+    detail: string;
+    /** Whether running the same command again can still finish the removal. */
+    retryable: boolean;
+    /** The server's step names only — no ids, ARNs or messages. */
+    steps: string[];
+}
+export declare function botRemovalIncomplete(failures?: Record<string, string>): BotRemovalIncomplete;
+/**
+ * Rebuild a bot.json from the settings the cloud kept for it. A bot created
+ * before HQ saved settings comes back on defaults, and anything this HQ can no
+ * longer provide (a worker that is not here, a thinking level the chosen
+ * runtime does not accept) is reported rather than silently kept.
+ */
+export declare function configFromLocalConfig(input: {
+    name: string;
+    agentUid: string;
+    ownerUid: string;
+    hqRoot: string;
+    dir: string;
+    local: BotLocalConfig | null;
+    overrides?: {
+        runtime?: BotRuntimeId;
+        model?: string;
+    };
+    now?: () => Date;
+}): {
+    config: BotConfig;
+    notes: string[];
+};
+export interface BotAdoptResult {
+    name: string;
+    agentUid: string;
+    runtime: BotRuntimeId;
+    kind: BotKind;
+    companies: string[];
+    dir: string;
+    worker: string;
+    memory: BotMemoryMode;
+    memoryDir: string;
+    /** True when the cloud had no saved settings and defaults were used. */
+    defaulted: boolean;
+    notes: string[];
+    daemon: string | null;
+}
+export declare function runBotAdopt(nameArg: string, opts: {
+    runtime?: string;
+    model?: string;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface BotRestoreRow {
+    name: string;
+    agentUid: string;
+    /** restored = brought back here; repaired = new credentials for one already here. */
+    action: "restored" | "repaired" | "skipped" | "failed" | "would-restore" | "would-repair" | "would-skip";
+    detail: string;
+    /** Present only on a bot skipped because this computer cannot run it. */
+    reason?: BotNotRunnableReason;
+}
+/**
+ * `hq bot restore` — every local bot this account owns that is not set up on
+ * this computer comes back. This is what the desktop app and a post-install
+ * hook call after a reinstall or on a new Mac.
+ */
+export declare function runBotRestore(opts: {
+    all?: boolean;
+    dryRun?: boolean;
+    daemon?: boolean;
+    start?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export interface RemoteBotRow {
+    name: string;
+    agentUid: string;
+    kind: string;
+    online: boolean;
+    lastHeartbeatAt: string | null;
+    /** True when this bot is set up on this computer. */
+    here: boolean;
+    settings: string;
+    /** False when this computer cannot run it, whatever the listing says. */
+    runnable: boolean;
+    /** Why not, when `runnable` is false: the same vocabulary adopt and restore use. */
+    reason: BotNotRunnableReason | null;
+}
 export declare function registerBotCommand(program: Command): void;
 //# sourceMappingURL=bot.d.ts.map