@indigoai-us/hq-cli 5.345.170 → 5.345.171

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.101","bundleSha256":"353f47dca127c7f6c1e00de5c9cdce809c5c32d08b2deb9755020b8e8b822871","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.102","bundleSha256":"54baedb34f8744f3dbbfa970785c6de703a33145081969bed5b266a2fc4d4d9e","formatVersion":1}

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

@@ -84,6 +84,23 @@ export interface MergedInbox {
      */
     source: "server" | "server-partial" | "local-mirror";
 }
+/** Notes for a server inbox body that cannot certify a complete read. */
+export declare const AGENT_INBOX_INVALID_RESPONSE_NOTE = "server inbox returned an invalid response; showing the local mirror only, which may be stale";
+export declare const AGENT_INBOX_INVALID_ITEMS_NOTE = "server inbox contained invalid messages; showing valid server messages and the local mirror, which may be incomplete";
+/**
+ * Classify a decoded 200 body from GET /v1/agents/{uid}/inbox. Pass
+ * `undefined` for a body that failed to decode. `invalid` means the body had
+ * no messages array, so nothing from it can be trusted; `partial` means some
+ * items were dropped (non-objects or missing id/messageId). Valid items keep
+ * their raw fields with `id` set; callers redact before output. Never puts
+ * response bytes in a diagnostic. Pure.
+ */
+export declare function classifyAgentInboxBody(body: unknown): {
+    status: "ok" | "partial" | "invalid";
+    items: Array<Record<string, unknown> & {
+        id: string;
+    }>;
+};
 export declare function mergeAgentInbox(paths: Pick<AgentKitPaths, "inboxDir">, fetchServerInbox: () => Promise<{
     status: number;
     body: unknown;

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

@@ -138,6 +138,38 @@ export function summarizeInboxEntry(e, done) {
         done,
     };
 }
+/** Notes for a server inbox body that cannot certify a complete read. */
+export const AGENT_INBOX_INVALID_RESPONSE_NOTE = "server inbox returned an invalid response; showing the local mirror only, which may be stale";
+export const AGENT_INBOX_INVALID_ITEMS_NOTE = "server inbox contained invalid messages; showing valid server messages and the local mirror, which may be incomplete";
+/**
+ * Classify a decoded 200 body from GET /v1/agents/{uid}/inbox. Pass
+ * `undefined` for a body that failed to decode. `invalid` means the body had
+ * no messages array, so nothing from it can be trusted; `partial` means some
+ * items were dropped (non-objects or missing id/messageId). Valid items keep
+ * their raw fields with `id` set; callers redact before output. Never puts
+ * response bytes in a diagnostic. Pure.
+ */
+export function classifyAgentInboxBody(body) {
+    const messages = body?.messages;
+    if (!Array.isArray(messages))
+        return { status: "invalid", items: [] };
+    const items = [];
+    let invalidItems = 0;
+    for (const m of messages) {
+        if (!m || typeof m !== "object" || Array.isArray(m)) {
+            invalidItems += 1;
+            continue;
+        }
+        const raw = m;
+        const id = typeof raw.id === "string" && raw.id ? raw.id : typeof raw.messageId === "string" && raw.messageId ? raw.messageId : null;
+        if (!id) {
+            invalidItems += 1;
+            continue;
+        }
+        items.push({ ...raw, id });
+    }
+    return { status: invalidItems > 0 ? "partial" : "ok", items };
+}
 export async function mergeAgentInbox(paths, fetchServerInbox) {
     const byId = new Map();
     for (const e of readMirroredInbox(paths))
@@ -147,32 +179,21 @@ export async function mergeAgentInbox(paths, fetchServerInbox) {
     try {
         const res = await fetchServerInbox();
         if (res.status === 200) {
-            const messages = res.body?.messages;
             // A successful HTTP status alone cannot certify an inbox read. An error
             // envelope or an undecodable body must remain visibly unverified; never
             // include response bytes or parser errors in this diagnostic.
-            if (!Array.isArray(messages)) {
-                source = "local-mirror";
-                note = "server inbox returned an invalid response; showing the local mirror only, which may be stale";
+            const classified = classifyAgentInboxBody(res.body);
+            for (const item of classified.items) {
+                if (!byId.has(item.id))
+                    byId.set(item.id, redactAgentInboxItem(item));
             }
-            let invalidItems = 0;
-            for (const m of Array.isArray(messages) ? messages : []) {
-                if (!m || typeof m !== "object") {
-                    invalidItems += 1;
-                    continue;
-                }
-                const raw = m;
-                const id = typeof raw.id === "string" ? raw.id : typeof raw.messageId === "string" ? raw.messageId : null;
-                if (!id) {
-                    invalidItems += 1;
-                    continue;
-                }
-                if (!byId.has(id))
-                    byId.set(id, redactAgentInboxItem({ ...raw, id }));
+            if (classified.status === "invalid") {
+                source = "local-mirror";
+                note = AGENT_INBOX_INVALID_RESPONSE_NOTE;
             }
-            if (invalidItems > 0) {
+            else if (classified.status === "partial") {
                 source = "server-partial";
-                note = "server inbox contained invalid messages; showing valid server messages and the local mirror, which may be incomplete";
+                note = AGENT_INBOX_INVALID_ITEMS_NOTE;
             }
         }
         else {

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

@@ -12,6 +12,8 @@ export interface KitConfig {
     inboxPollMs: number;
     heartbeatIntervalMs: number;
     meshRefreshMs: number;
+    /** Per-request timeout for the inbox and heartbeat network calls. */
+    requestTimeoutMs: number;
     /** Ack mirrored inbox items on the server after writing them locally. */
     inboxAck: boolean;
     /**

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

@@ -8,10 +8,12 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { KIT_COMPONENTS } from "./paths.js";
 import { writePrivateFile } from "./private-file.js";
+import { KIT_REQUEST_TIMEOUT_MIN_MS, KIT_REQUEST_TIMEOUT_MS } from "./run/request-timeout.js";
 const DEFAULT_SYNC_INTERVAL_MS = 5 * 60_000;
 const DEFAULT_INBOX_POLL_MS = 15_000;
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 60_000;
 const DEFAULT_MESH_REFRESH_MS = 5 * 60_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = KIT_REQUEST_TIMEOUT_MS;
 /**
  * Kit components whose health this install actually reports. `sync` drops out
  * when the vault is not mirrored to disk — there is no loop to be healthy or
@@ -30,6 +32,7 @@ export function defaultKitConfig(paths, cliVersion, now = () => new Date()) {
         inboxPollMs: DEFAULT_INBOX_POLL_MS,
         heartbeatIntervalMs: DEFAULT_HEARTBEAT_INTERVAL_MS,
         meshRefreshMs: DEFAULT_MESH_REFRESH_MS,
+        requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
         inboxAck: false,
         syncFiles: false,
         installedAt: now().toISOString(),
@@ -56,6 +59,9 @@ export function readKitConfig(paths, cliVersion) {
         inboxPollMs: num("inboxPollMs"),
         heartbeatIntervalMs: num("heartbeatIntervalMs"),
         meshRefreshMs: num("meshRefreshMs"),
+        // 0, negative or missing keeps the default; a tiny positive value would
+        // time out every poll, so it is raised to the minimum.
+        requestTimeoutMs: Math.max(KIT_REQUEST_TIMEOUT_MIN_MS, num("requestTimeoutMs")),
         inboxAck: raw.inboxAck === true,
         syncFiles: raw.syncFiles === true,
         installedAt: typeof raw.installedAt === "string" ? raw.installedAt : base.installedAt,

package/dist/lib/agent-kit/mcp/tools.js

@@ -17,7 +17,8 @@
  */
 import { CLI_VERSION } from "../../../cli-version.js";
 import { peekIdToken } from "../../../utils/id-token.js";
-import { defaultAudienceFor, isAgentUid, isRecipientUid } from "../../../lib/notify-recipient.js";
+import { PERSON_AGENT_AUDIENCE_MESSAGE, callerMayUseAudience, defaultAudienceFor, isAgentUid, isRecipientUid } from "../../../lib/notify-recipient.js";
+import { tokenIsMachinePrincipal } from "../../../lib/caller-principal.js";
 import { redactAgentInboxItem } from "../inbox-redact.js";
 import { markInboxDone, mergeAgentInbox, readDoneIds, summarizeInboxEntry } from "../inbox-state.js";
 import { AttachmentCompanyUnresolvedError, fetchChatAttachment } from "./attachments.js";
@@ -232,13 +233,20 @@ export function buildAgentMcpTools(clients) {
                 if (audience !== undefined && !["human", "agent", "both"].includes(audience)) {
                     throw new McpToolInputError('"audience" must be human, agent, or both');
                 }
+                // The token decides who is sending. Normally the agent's machine
+                // identity; if it ever resolves to a person login, people only send
+                // human messages, so refuse agent/both before any send.
+                const token = await clients.getToken();
+                const machineCaller = tokenIsMachinePrincipal(token);
+                if (!callerMayUseAudience(audience, machineCaller)) {
+                    return errorResult(PERSON_AGENT_AUDIENCE_MESSAGE);
+                }
                 if (/^chn_[A-Za-z0-9]+$/.test(to)) {
                     // A channel or group DM: post into it, so a reply lands where the
                     // message arrived instead of in a private DM to the sender.
-                    const token = await clients.getToken();
                     const res = await clients.apiJson(token, `/v1/notify/channels/${encodeURIComponent(to)}/messages`, {
                         method: "POST",
-                        body: { body: message, audience: audience ?? defaultAudienceFor("channel") },
+                        body: { body: message, audience: audience ?? defaultAudienceFor("channel", machineCaller) },
                     });
                     if (res.status < 200 || res.status >= 300) {
                         return errorResult(`Channel send failed (${res.status}): ${describeError(res.body)}`);
@@ -252,8 +260,7 @@ export function buildAgentMcpTools(clients) {
                         : (() => {
                             throw new McpToolInputError('"to" must be an email, prs_… or agt_… uid, or a chn_… channel id');
                         })();
-                body.audience = audience ?? defaultAudienceFor(isAgentUid(to) ? "agent" : "person");
-                const token = await clients.getToken();
+                body.audience = audience ?? defaultAudienceFor(isAgentUid(to) ? "agent" : "person", machineCaller);
                 const res = await clients.apiJson(token, "/v1/notify/dm", { method: "POST", body });
                 if (res.status < 200 || res.status >= 300) {
                     return errorResult(`DM send failed (${res.status}): ${describeError(res.body)}`);

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

@@ -54,11 +54,14 @@ export interface HeartbeatDeps {
     agentUid: string;
     apiBaseUrl: string;
     intervalMs: number;
-    getToken: () => Promise<string>;
+    /** Mints or refreshes the machine token; the signal cancels a stuck refresh. */
+    getToken: (signal?: AbortSignal) => Promise<string>;
     log: KitLogger;
     /** Components this kit runs; defaults to all of them. */
     components?: readonly KitComponent[];
-    post?: (token: string, body: HeartbeatBody, identity?: HeartbeatIdentity) => Promise<number | HeartbeatPostResult>;
+    post?: (token: string, body: HeartbeatBody, identity?: HeartbeatIdentity, signal?: AbortSignal) => Promise<number | HeartbeatPostResult>;
+    /** Per-request timeout for the token mint and the heartbeat POST (kit.json `requestTimeoutMs`). */
+    requestTimeoutMs?: number;
     /** Re-read the configured identity and endpoint once when a freshly minted token differs. */
     getConfiguredAgentIdentity?: () => HeartbeatIdentity;
     now?: () => Date;
@@ -72,7 +75,7 @@ export interface HeartbeatPostResult {
     status: number;
     bodyText?: string;
 }
-export declare function defaultHeartbeatPost(identity: HeartbeatIdentity): (token: string, body: HeartbeatBody, requestIdentity?: HeartbeatIdentity) => Promise<HeartbeatPostResult>;
+export declare function defaultHeartbeatPost(identity: HeartbeatIdentity): (token: string, body: HeartbeatBody, requestIdentity?: HeartbeatIdentity, signal?: AbortSignal) => Promise<HeartbeatPostResult>;
 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

@@ -17,6 +17,7 @@ import { vaultApiFetch } from "../../../utils/vault-api.js";
 import { readComponentStatus } from "../creds.js";
 import { KIT_COMPONENTS } from "../paths.js";
 import { writePrivateFile } from "./../private-file.js";
+import { KIT_REQUEST_TIMEOUT_MS, withRequestTimeout } from "./request-timeout.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
@@ -51,13 +52,14 @@ export function readLastHeartbeat(paths) {
     }
 }
 export function defaultHeartbeatPost(identity) {
-    return async (token, body, requestIdentity = identity) => {
+    return async (token, body, requestIdentity = identity, signal) => {
         const res = await vaultApiFetch({
             token,
             baseUrl: requestIdentity.apiBaseUrl,
             path: `/v1/agents/${encodeURIComponent(requestIdentity.agentUid)}/heartbeat`,
             method: "POST",
             body: body,
+            ...(signal ? { signal } : {}),
         });
         return { status: res.status, bodyText: await res.text().catch(() => "") };
     };
@@ -85,7 +87,8 @@ async function beatOnceResult(deps) {
     const now = deps.now ?? (() => new Date());
     const body = buildHeartbeatBody(deps.paths, now, undefined, deps.components ?? KIT_COMPONENTS);
     try {
-        const token = await deps.getToken();
+        const timeoutMs = deps.requestTimeoutMs ?? KIT_REQUEST_TIMEOUT_MS;
+        const token = await withRequestTimeout(timeoutMs, undefined, (signal) => deps.getToken(signal));
         const tokenUid = tokenAgentUid(token);
         let identity = { agentUid: deps.agentUid, apiBaseUrl: deps.apiBaseUrl };
         if (tokenUid !== undefined && tokenUid !== identity.agentUid) {
@@ -103,7 +106,7 @@ async function beatOnceResult(deps) {
             }
         }
         const post = deps.post ?? defaultHeartbeatPost(identity);
-        const response = await post(token, body, identity);
+        const response = await withRequestTimeout(timeoutMs, undefined, (signal) => post(token, body, identity, signal));
         const result = typeof response === "number" ? { status: response } : response;
         const status = result.status;
         const ok = status >= 200 && status < 300;

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

@@ -22,6 +22,8 @@ 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 declare const INBOX_POLL_BACKOFF_MAX_MS = 30000;
+/** A poll slower than this logs one line with its duration and outcome. */
+export declare const INBOX_SLOW_POLL_MS = 10000;
 export interface InboxItem {
     id: string;
     raw: Record<string, unknown>;
@@ -37,14 +39,17 @@ export interface InboxDeps {
     apiBaseUrl: string;
     pollMs: number;
     ack: boolean;
-    getToken: () => Promise<string>;
+    /** Mints or refreshes the machine token; the signal cancels a stuck refresh. */
+    getToken: (signal?: AbortSignal) => Promise<string>;
     log: KitLogger;
     fetchInbox?: (token: string, signal?: AbortSignal) => Promise<InboxFetchResult>;
-    ackItem?: (token: string, id: string) => Promise<number>;
+    ackItem?: (token: string, id: string, signal?: AbortSignal) => Promise<number>;
     warmCache?: (token: string, agentUid: string) => Promise<unknown>;
     sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
     readInboxBackoffEnabled?: () => Promise<boolean>;
     signal?: AbortSignal;
+    /** Per-request timeout for the token mint, inbox GET and acks (kit.json `requestTimeoutMs`). */
+    requestTimeoutMs?: number;
     companySlug?: string;
     maxPolls?: number;
     /** Override wake config lookup (tests). `null` disables the wake. */
@@ -71,7 +76,7 @@ export declare function agentApiUrl(apiBaseUrl: string, route: string): string;
 export declare function agentInboxUrl(apiBaseUrl: string, agentUid: string): string;
 export declare function truncateBody(text: string, max?: number): string;
 export declare function defaultFetchInbox(agentUid: string, apiBaseUrl: string): (token: string, signal?: AbortSignal) => Promise<InboxFetchResult>;
-export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string) => Promise<number>;
+export declare function defaultAckItem(agentUid: string, apiBaseUrl: string): (token: string, id: string, signal?: AbortSignal) => Promise<number>;
 export declare function pollInboxOnce(deps: InboxDeps): Promise<{
     ok: boolean;
     mirrored: number;

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

@@ -25,10 +25,13 @@ import { redactAgentInboxItem, scrubInboxMirror, withInboxMirrorLock } from "../
 import { mkdirPrivate, writePrivateFile } from "./../private-file.js";
 import { createAgentKitInboxBackoffFlagReader } from "../inbox-poll-backoff-flag.js";
 import { buildWakeNotice, currentWakeState, fireWake, readWakeConfig, shouldWake, } from "../wake.js";
+import { KIT_REQUEST_TIMEOUT_MS, KitRequestTimeoutError, withRequestTimeout } from "./request-timeout.js";
 export const SEEN_IDS_NAME = "seen-ids.json";
 export const INBOX_JSONL_NAME = "inbox.jsonl";
 export const MAX_SEEN_IDS = 5000;
 export const INBOX_POLL_BACKOFF_MAX_MS = 30_000;
+/** A poll slower than this logs one line with its duration and outcome. */
+export const INBOX_SLOW_POLL_MS = 10_000;
 /** 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 : {};
@@ -141,12 +144,13 @@ export function defaultFetchInbox(agentUid, apiBaseUrl) {
     };
 }
 export function defaultAckItem(agentUid, apiBaseUrl) {
-    return async (token, id) => {
+    return async (token, id, signal) => {
         const res = await vaultApiFetch({
             token,
             baseUrl: apiBaseUrl,
             path: `/v1/agents/${encodeURIComponent(agentUid)}/inbox/${encodeURIComponent(id)}/ack`,
             method: "POST",
+            ...(signal ? { signal } : {}),
         });
         return res.status;
     };
@@ -154,6 +158,27 @@ export function defaultAckItem(agentUid, apiBaseUrl) {
 export async function pollInboxOnce(deps) {
     if (deps.signal?.aborted)
         return { ok: false, mirrored: 0 };
+    const startedAt = Date.now();
+    const result = await pollInboxOnceTimed(deps);
+    const elapsed = Date.now() - startedAt;
+    // One line per slow or timed-out poll: duration and outcome only, never a
+    // token or message content. A timeout already logged its own line.
+    if (result.outcome !== "timeout" && result.outcome !== "aborted" && elapsed >= INBOX_SLOW_POLL_MS) {
+        deps.log("warn", `inbox poll slow: ${elapsed}ms outcome=${result.outcome}`);
+    }
+    return { ok: result.ok, mirrored: result.mirrored };
+}
+async function pollInboxOnceTimed(deps) {
+    const startedAt = Date.now();
+    const timeoutMs = deps.requestTimeoutMs ?? KIT_REQUEST_TIMEOUT_MS;
+    const bounded = (fn) => withRequestTimeout(timeoutMs, deps.signal, fn);
+    // A timed-out step is a failed poll: stamp error and let the loop retry on
+    // the base interval. It never falls through to the empty-inbox path.
+    const timedOut = (step) => {
+        writeComponentStatus(deps.paths, "inbox", "error");
+        deps.log("error", `inbox poll timed out: ${step} after ${Date.now() - startedAt}ms (limit ${timeoutMs}ms) outcome=timeout`);
+        return { ok: false, mirrored: 0, outcome: "timeout" };
+    };
     // Mirrors written before credential redaction are scrubbed on the next poll,
     // before a wake can send the bot at the files. A write or rename error is
     // counted and retried on the next poll. The log is a count and errno codes,
@@ -178,23 +203,29 @@ export async function pollInboxOnce(deps) {
     const warmCache = deps.warmCache ?? (async () => { });
     let token;
     try {
-        token = await deps.getToken();
+        token = await bounded((signal) => deps.getToken(signal));
     }
     catch (err) {
+        if (deps.signal?.aborted)
+            return { ok: false, mirrored: 0, outcome: "aborted" };
+        if (err instanceof KitRequestTimeoutError)
+            return timedOut("token mint");
         writeComponentStatus(deps.paths, "inbox", "error");
         deps.log("error", `inbox token mint failed: ${err instanceof Error ? err.message : String(err)}`);
-        return { ok: false, mirrored: 0 };
+        return { ok: false, mirrored: 0, outcome: "error" };
     }
     let res;
     try {
-        res = await fetchInbox(token, deps.signal);
+        res = await bounded((signal) => fetchInbox(token, signal));
     }
     catch (err) {
         if (deps.signal?.aborted)
-            return { ok: false, mirrored: 0 };
+            return { ok: false, mirrored: 0, outcome: "aborted" };
+        if (err instanceof KitRequestTimeoutError)
+            return timedOut("inbox GET");
         writeComponentStatus(deps.paths, "inbox", "error");
         deps.log("error", `inbox fetch failed: GET ${agentInboxUrl(deps.apiBaseUrl, deps.agentUid)}: ${err instanceof Error ? err.message : String(err)}`);
-        return { ok: false, mirrored: 0 };
+        return { ok: false, mirrored: 0, outcome: "error" };
     }
     if (res.status !== 200) {
         writeComponentStatus(deps.paths, "inbox", "error");
@@ -202,7 +233,7 @@ export async function pollInboxOnce(deps) {
         // Non-OK bodies are not constrained to an error envelope and could carry
         // inbox items. Keep the status and route, but do not copy the body to logs.
         deps.log("warn", `inbox poll GET ${url} → ${res.status}`);
-        return { ok: false, mirrored: 0 };
+        return { ok: false, mirrored: 0, outcome: "error" };
     }
     writeComponentStatus(deps.paths, "inbox", "ok");
     const seen = readSeenIds(deps.paths);
@@ -211,12 +242,13 @@ export async function pollInboxOnce(deps) {
         mirrorInboxItem(deps.paths, item);
         if (deps.ack) {
             try {
-                const status = await ackItem(token, item.id);
+                const status = await bounded((signal) => ackItem(token, item.id, signal));
                 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)}`);
+                const reason = err instanceof KitRequestTimeoutError ? err.message : err instanceof Error ? err.message : String(err);
+                deps.log("warn", `ack ${item.id} failed: ${reason}`);
             }
         }
         // Persist each completed item before starting another one. If shutdown
@@ -234,7 +266,7 @@ export async function pollInboxOnce(deps) {
         }
     }
     await maybeWake(deps, fresh.length);
-    return { ok: true, mirrored: fresh.length };
+    return { ok: true, mirrored: fresh.length, outcome: "ok" };
 }
 /** Poke the bot's framework when mail is new, or still pending past the retry window. */
 async function maybeWake(deps, freshCount) {

package/dist/lib/agent-kit/run/request-timeout.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Per-request bound for the kit services' network calls.
+ *
+ * A poll on a stale or half-open connection otherwise waits until the OS
+ * drops the socket, which can take hours (row 66ce5718). Each call gets its
+ * own deadline combined with the service's shutdown signal. The deadline
+ * uses setTimeout, not AbortSignal.timeout, so tests can drive it with fake
+ * timers; `anySignal` keeps the CLI working on Node 20.0.
+ */
+/** Default per-request timeout for kit network calls (kit.json `requestTimeoutMs`). */
+export declare const KIT_REQUEST_TIMEOUT_MS = 30000;
+/** Lowest accepted kit.json `requestTimeoutMs`; smaller values are raised to this. */
+export declare const KIT_REQUEST_TIMEOUT_MIN_MS = 1000;
+export declare class KitRequestTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/**
+ * Run `fn` with a signal that aborts on shutdown or after `timeoutMs`.
+ * The result is also raced against that signal, so a call that ignores the
+ * signal (such as a token refresh waiting on a lock) still returns on time.
+ * Rejects with KitRequestTimeoutError on the deadline, or with the shutdown
+ * signal's reason on shutdown.
+ */
+export declare function withRequestTimeout<T>(timeoutMs: number, shutdown: AbortSignal | undefined, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+//# sourceMappingURL=request-timeout.d.ts.map

package/dist/lib/agent-kit/run/request-timeout.js

@@ -0,0 +1,51 @@
+/**
+ * Per-request bound for the kit services' network calls.
+ *
+ * A poll on a stale or half-open connection otherwise waits until the OS
+ * drops the socket, which can take hours (row 66ce5718). Each call gets its
+ * own deadline combined with the service's shutdown signal. The deadline
+ * uses setTimeout, not AbortSignal.timeout, so tests can drive it with fake
+ * timers; `anySignal` keeps the CLI working on Node 20.0.
+ */
+import { anySignal } from "../../../utils/vault-api.js";
+/** Default per-request timeout for kit network calls (kit.json `requestTimeoutMs`). */
+export const KIT_REQUEST_TIMEOUT_MS = 30_000;
+/** Lowest accepted kit.json `requestTimeoutMs`; smaller values are raised to this. */
+export const KIT_REQUEST_TIMEOUT_MIN_MS = 1_000;
+export class KitRequestTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`request timed out after ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.name = "KitRequestTimeoutError";
+    }
+}
+/**
+ * Run `fn` with a signal that aborts on shutdown or after `timeoutMs`.
+ * The result is also raced against that signal, so a call that ignores the
+ * signal (such as a token refresh waiting on a lock) still returns on time.
+ * Rejects with KitRequestTimeoutError on the deadline, or with the shutdown
+ * signal's reason on shutdown.
+ */
+export async function withRequestTimeout(timeoutMs, shutdown, fn) {
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(new KitRequestTimeoutError(timeoutMs)), timeoutMs);
+    const combined = anySignal(shutdown ? [shutdown, deadline.signal] : [deadline.signal]);
+    let onAbort;
+    try {
+        const aborted = new Promise((_, reject) => {
+            if (combined.signal.aborted)
+                return reject(combined.signal.reason);
+            onAbort = () => reject(combined.signal.reason);
+            combined.signal.addEventListener("abort", onAbort, { once: true });
+        });
+        return await Promise.race([fn(combined.signal), aborted]);
+    }
+    finally {
+        clearTimeout(timer);
+        if (onAbort)
+            combined.signal.removeEventListener("abort", onAbort);
+        combined.dispose();
+    }
+}
+//# sourceMappingURL=request-timeout.js.map

package/dist/lib/bot/api.d.ts

@@ -131,7 +131,7 @@ export interface MyLocalBot {
     name?: string;
     botKind?: "personal" | "company";
     computeMode?: string;
-    ownerUid?: string;
+    ownerUid?: string | null;
     online?: boolean;
     lastHeartbeatAt?: string | null;
     localConfig?: unknown;

package/dist/lib/bot/config.d.ts

@@ -3,6 +3,15 @@
  */
 export declare const BOT_RUNTIMES: readonly ["claude", "codex", "grok"];
 export type BotRuntimeId = (typeof BOT_RUNTIMES)[number];
+export declare const HQ_FLEET_RUNTIME_ENGINE_ID: "hq-fleet-runtime";
+export interface BotEngineMetadata {
+    id: typeof HQ_FLEET_RUNTIME_ENGINE_ID;
+    distribution: "hq-fleet-local";
+    version: string;
+    artifactSha256: string;
+    runtimeCommit: string;
+}
+export declare function isBotEngineMetadata(value: unknown): value is BotEngineMetadata;
 export declare function isBotRuntimeId(value: unknown): value is BotRuntimeId;
 /**
  * What a bot is (owner decisions, 2026-09-15):
@@ -80,6 +89,7 @@ export interface BotConfig {
     /** The person (prs_) who created and owns the bot. */
     ownerUid: string;
     runtime: BotRuntimeId;
+    engine?: BotEngineMetadata;
     /**
      * "personal" (acts as its owner everywhere) or "company" (acts as itself,
      * member of `companies`). Missing on bots created before kinds existed:

package/dist/lib/bot/config.js

@@ -5,6 +5,20 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { botConfigPath } from "./paths.js";
 export const BOT_RUNTIMES = ["claude", "codex", "grok"];
+export const HQ_FLEET_RUNTIME_ENGINE_ID = "hq-fleet-runtime";
+export function isBotEngineMetadata(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const engine = value;
+    return (engine.id === HQ_FLEET_RUNTIME_ENGINE_ID &&
+        engine.distribution === "hq-fleet-local" &&
+        typeof engine.version === "string" &&
+        /^\d+\.\d+\.\d+$/.test(engine.version) &&
+        typeof engine.artifactSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(engine.artifactSha256) &&
+        typeof engine.runtimeCommit === "string" &&
+        /^[a-f0-9]{40}$/.test(engine.runtimeCommit));
+}
 export function isBotRuntimeId(value) {
     return typeof value === "string" && BOT_RUNTIMES.includes(value);
 }
@@ -188,9 +202,10 @@ export function readBotConfig(dir) {
         }
         if (!isBotRuntimeId(raw.runtime))
             return null;
-        const { intro: rawIntro, kickoff: rawKickoff, kind: _kind, companies: _companies, ...rest } = raw;
+        const { intro: rawIntro, kickoff: rawKickoff, kind: _kind, companies: _companies, engine: rawEngine, ...rest } = raw;
         const intro = typeof rawIntro === "string" && rawIntro.trim() ? rawIntro : undefined;
         const kickoff = typeof rawKickoff === "string" && rawKickoff.trim() ? rawKickoff : undefined;
+        const engine = isBotEngineMetadata(rawEngine) ? rawEngine : undefined;
         // Older bot.json files carry no kind: they read (and, on the first patch,
         // persist) as personal, so every reader sees a kind.
         const kind = effectiveBotKind(raw);
@@ -201,6 +216,7 @@ export function readBotConfig(dir) {
             ...(kind === "company" ? { companies } : {}),
             ...(intro ? { intro } : {}),
             ...(kickoff ? { kickoff } : {}),
+            ...(engine ? { engine } : {}),
             enabled: raw.enabled !== false,
         };
     }